narratio/docs/roadmap/policy.md

# Align Narratio With Standard Repository Policies

Status: Implemented (2026-09-28); release pending.

Implementation evidence: The [implementation plan](implementation.md) records
completion and verification of each bounded unit. Seven adopted policies are
credited at the pinned source revision; the local release checker, runbook,
publication tests, CI references, and OSS notices now follow the selected
workflow. The full race-enabled suite, vet, module/format/shell checks, and
synthetic release assets passed. No source release or asynchronous asset
delivery was initiated by this implementation work.

## 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](implementation.md)
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](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md).
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:

```text
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](https://gitea.maximumdirect.net/eric/policy)
and [current adoption guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md).
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.