narratio/docs/roadmap/policy.md

Align Narratio With Standard Repository Policies

Status: Accepted; implementation pending.

Goal and Approved Scope

Align Narratio's adopted policy language with Standard Repository Policies. Use upstream wording verbatim for non-substantive differences. Retain variations only for substantive, locally significant requirements or decisions and explain their justification. Follow template adoption instructions and customize required project-specific sections rather than copying instructional placeholders.

This document defines the target and scope; the implementation plan owns sequencing and concrete validation choices. It supersedes the earlier licensing-only roadmap: public upstream discovery, copied-policy attribution, and coordinated release-workflow alignment are now included. The earlier prohibition on policy-project references and deferral of broader release alignment no longer apply.

Fixed Review Revision and Baseline

The approved review compared current local documents directly with upstream commit d84a38ebab26f048cafbe59a2246700c35d29843, verified against published main on 2026-09-28. Historical adoption baselines need not be reconstructed. Do not imply that this revision was previously adopted.

Follow the adoption guide at the reviewed revision. Use this fixed revision for implementation; incorporating a later revision requires deliberate comparison rather than an implicit refresh.

Narratio has five adopted policies without per-document Upstream Source links. It lacks docs/policy/meta.md, docs/policy/oss.md, and the OSS attribution collection. Its development guide has task routes but not the standard selective policy-reading guidance. COPYRIGHT already grants GPL-3.0-or-later and LICENSE contains GPLv3; only the separate policy-document licensing scope needs adding.

The release process already ends at successful tag publication to origin, uses lightweight tags and source-push-before-tag, and publishes Gitea binaries and checksums asynchronously. Current guidance requires standalone validation before publication repeats it. The checker requires fixed note sections and repeats documentation/example tests included in the full suite. These are alignment work, not automatic justifications for different policy language.

Policy Target

Document	Target version	Required treatment
docs/policy/agents.md	1.3	Adopt upstream wording. Remove redundant general-purpose local elaborations; retain application safeguards in architecture. Existing local-commit behavior remains.
docs/policy/testing.md	1.3	Adopt upstream wording after template removal. Protect requested behavior and established contracts without turning risk categories or examples into new requirements. No local exception is needed.
docs/policy/documentation.md	1.11	Adopt general wording and customize the ownership table. Retain troubleshooting ownership and materially useful stage/integration terminology; omit inapplicable public HTTP/API responsibilities. Add provenance and licensing owners.
docs/policy/architecture.md	1.3	Adopt general framing and customize application-specific sections as instructed. Preserve Narratio's established contracts rather than substituting generic examples.
docs/policy/release.md	1.4	Adopt upstream wording with coordinated executable changes. Tag-push completion and authoritative-remote scope are now standard, not local exceptions requiring compensating controls.
docs/policy/meta.md	1.0	Add local authority, public discovery, adoption-guide navigation, and per-document provenance guidance.
docs/policy/oss.md	1.8	Add current House Format, copied-document treatment, maintenance, and reference-example links; customize project/distribution facts.

No existing policy is wholly unchanged because provenance and wording require updates. Narratio's architectural decisions and agent commit behavior need no substantive change. Wording preferences alone do not justify local variants.

Provenance and Orientation

Remove each adopted document's Base Policy Template section and replace other template-only guidance with substantive project content where required. Retain the actual Base Policy Version, set Last Updated to the adoption date, and add Upstream Source pointing to that individual file at the reviewed commit:

https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/FILE.md

Substitute the correct filename for each policy. Preserve accurate provenance in later edits; Git records suffice without a new adoption registry or sync service.

Adapt upstream agents/AGENTS.md into root AGENTS.md, preserving applicable existing instructions. Do not copy upstream's root agent instructions, which govern work on that repository. Incorporate the supplied selective Policy Reading Guide into docs/development.md: select by task, read before governed decisions, reuse available context, follow relevant cross-references, expand reading when scope expands, and read affected provisions when revising policies. Do not make reading the whole suite mandatory. Preserve useful Narratio-specific task routes.

Meta links to the public project and current adoption guide. These are current-discovery links; adopted-source and example links stay commit-pinned. Reading triggers belong in development guidance and formal credit in attribution, not duplicated in meta.

Justified Local Customizations

Preserve established stage/adapter boundaries, manifest-driven resume/restore, artifact/path contracts, publication and lock semantics, credential protections, group-owned workspace behavior, and platform support. These express Narratio's operational responsibilities; policy alignment does not authorize changing them.

Retain Linux amd64/arm64 and best-effort macOS arm64 deliverables, without new native-platform gates or Windows/Intel Mac support. Preserve origin/main, lightweight tags, and source-push-before-tag in the release procedure. These are permitted project-specific mechanics, not exceptions to tag-push completion.

Customize documentation ownership for real Narratio interfaces and responsibilities, including troubleshooting; do not create empty API/consumer documents. Keep common prose verbatim around these customizations and explain substantive local choices in their canonical owner rather than maintaining a parallel general policy essay.

Licensing, Attribution, and Local Materials

Create docs/oss/attribution.md with the prescribed title followed directly by factual component entries. Use the canonical Standard Repository Policies entry from the reviewed commit. Identify actual copied/adapted material, including policy files, adapted agent instructions, and copied reading-guide material as applicable. Preserve creator, copyright, license, disclaimer, and modification notices. Pin source, COPYRIGHT, and LICENSE links to the reviewed full commit.

Copy CC-BY-SA-4.0 into docs/oss/licenses/. Add the limited policy-document scope to COPYRIGHT with an attribution link: adapted policy material remains CC-BY-SA-4.0; Narratio's application code remains GPL-3.0-or-later. Root LICENSE needs no replacement. Original upstream licensing-example formatting is CC0 and alone does not require attribution.

Complete the previously agreed inventory of incorporated/distributed material: relevant transitive dependencies, Go runtime material in shipped binaries, and copied code, documentation, or assets. Inspect selected sources and actual use; neither direct dependencies alone nor every development tool defines scope. ConfigKit v0.4.1 is a dependency. PromptKit is not in Narratio's module graph; invoking a separately installed downstream application does not itself incorporate that application's dependencies into Narratio.

Follow OSS v1.8's ordered fields and presentation: project heading, applicable faithful copyright statements, applicable SPDX expression, license/notice links, and a link labeled Source to the exact commit, ending with a period. Optional identification remains factual. Preserve alternatives, exceptions, and required notices; do not invent identifiers or add research narratives, compliance conclusions, or exception reasoning to entries.

Copy applicable complete standard texts locally and make companion texts directly reachable. Link project-specific notices and sources at exact imported commits, not moving branches or tags. Apply the House interpretation of notice links without blanket additional local-copy requirements. Distinct concrete obligations still receive appropriate treatment; preserve notices in incorporated source.

Keep upstream's README, root AGENTS.md, development/adoption guides, and example collection upstream. Retain commit-pinned example links in the adopted OSS policy; create actual local notices instead of copying the example collection. Adopted policies, project orientation, actual attribution, and applicable standard texts belong locally. Do not create placeholders for template-only links.

End README with the prescribed grant and attribution links. Future release notes and hosted pages end with COPYRIGHT | LICENSE | ATTRIBUTION links at their immutable release tag or source revision. The procedure owns concrete Gitea URLs; continue using the checked-in note as the hosted body. Maintain attribution with relevant dependency/material changes through ordinary review.

Coordinated Release Alignment

Update release policy, docs/release.md, relevant scripts, tests, and development guidance together so rules and executable behavior agree:

• Make publication the normal validating-and-publishing entry point. Standalone validation remains optional rather than a mandatory duplicate prior pass.
• Remove fixed release-note section requirements. Preserve version-matched notes and titles, relevant compatibility/upgrade information, and the licensing footer.
• Remove duplicate documentation/example test invocations covered by the full suite. Avoid repeated validation of the same final candidate; no persistent validation cache is required.
• Select additional gates by concrete risk and distinct protection. Do not keep race, static, module-hygiene, formatting, or other checks merely because they exist; document reasons for retained checks. Do not remove useful checks merely to minimize command count. The implementation plan records the selected checks and their distinct justification under these criteria.
• Keep offline default tests, required build targets, fresh-version checks, clean candidate/exact source/tag guards, and explicit-ref publication.
• Treat ordinary review and roadmap retirement as preparation, not new human approval rounds. Evaluate incidental file prohibitions by their impact on tagged source rather than banning ignored local files solely because they exist.
• End at successful tag push, without CI polling, asset-availability gates, or successful-push read-back requirements. Resolve failed/ambiguous pushes from remote evidence and report asynchronous delivery separately.
• Align recovery guidance: transient delivery failures alone do not require new versions. Retries/missing-asset additions must preserve published content and checksum consistency; source/content corrections require a new release.

Expected implementation surfaces include scripts/check-release-candidate.sh, scripts/release.sh, shared helpers/builders where needed, and release tests. Review workflow references for consistency without expanding into unrelated CI repair or application behavior changes.

Boundaries and Completion Evidence

No application relicensing, automatic copyright-year advancement, blanket headers, dependency upgrade, runtime feature, or platform expansion is included. Do not add mandatory scanners, a full SBOM, recurring legal sign-offs, publication-time network checks, or release approval gates. New downloadable license assets or packaging formats are not required merely to implement the conventions; concrete component obligations still require their applicable treatment.

Apply formatting prospectively. Preserve published tags, notes, binaries, and checksums. Address any discovered historical omission deliberately under the applicable terms and correction policy, not by silently rewriting releases.

Completion requires comparison with the pinned source, accurate per-file metadata and material attribution, justified variations, substantive supporting documents, valid navigation, and complete applicable texts. Release procedures and tests must prove the selected workflow and guards without duplicate mandatory validation or CI waiting. Documentation checks and relevant release tests must pass. Merely creating Markdown files is not evidence of alignment.

No product-level decision remains open from the approved review. Concrete rights questions or gate tradeoffs unresolved by the risk-based approach must be surfaced with evidence during planning, not silently converted into stronger requirements.