narratio/docs/roadmap/implementation.md

# Implementation Plan: Standard Repository Policy Alignment

Status: In progress.

## Scope and execution instructions

Implement [the policy roadmap](policy.md). This replaces the completed Audita
migration plan, retained in Git history. This planning pass changes no executable
code or adopted policies. The instructions below govern the later implementation.

Complete Stage 1 through Stage 7 in order, one bounded implementation prompt per
stage for gpt-5.6-terra. Record actual completion and verification under each stage
and commit each coherent completed unit with a plain-English message. Intermediate
states are not release candidates. Do not publish, tag, push, change dependencies,
or rewrite released material as part of this work.

Before each stage, read root AGENTS.md, the development reading guide, the roadmap,
and the policies applicable to that stage. Reuse unchanged policy text already in
context. Agents and documentation apply throughout; meta governs adoption; OSS
governs incorporated material; architecture/testing/release apply to the script
and test stages. Do not impose whole-suite policy reading on unrelated tasks.

Use upstream commit `d84a38ebab26f048cafbe59a2246700c35d29843` throughout. Start
with its [adoption guide](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md).
Read source documents at that revision, not mutable sibling worktree content.
Public access or a verified Git object is sufficient. Do not reconstruct prior
adoption history. If an exact source/notice cannot be verified, report the concrete
gap rather than inventing a commit, copyright, or license expression.

## Selected decisions

### Common policy language and provenance

Adopt non-project-specific upstream wording verbatim. Remove template-only
sections, customize required project content, and retain only the locally
significant exceptions identified in the roadmap. Preserve Narratio's actual
application contracts; this is not an architecture redesign or new safety audit.

Every adopted policy receives its actual Base Policy Version, actual local
adoption date, and an Upstream Source URL with the full reviewed commit and its
own `docs/policy/<filename>.md` path. Use current branch URLs only for public
discovery/adoption-guide navigation. Preserve commit-pinned upstream example
links; do not duplicate the example collection locally. No sync checker or
metadata registry is required.

### Attribution scope and presentation

Use OSS v1.8's exact House Format. Attribution contains factual entries, not
research notes. Put concrete exception reasoning in OSS policy or an appropriate
decision record. Credit copied policy, agent-orientation, and reading-guide
material accurately, distinguishing adapted portions from unrelated local text.
Keep adapted material CC-BY-SA-4.0 and application code GPL-3.0-or-later.

Inventory selected modules and shipped runtime material, not every historical
go.sum entry or development executable. Include the test-only go-cmp module as
part of the maintained module inventory with factual scope identification. Do not
include separately installed Audita, Notarius, PromptKit, or other subprocess
applications merely because Narratio invokes them. Include any actual copied
material discovered in the repository. Combine related modules into a component
entry only when their source revisions and notices can all be represented
accurately; do not invent a single revision for independently tagged modules.

### Final release validation and mechanics

Keep the current `scripts/release.sh VERSION` interface and source-push-before-tag
workflow. The optional `check-release-candidate.sh VERSION` remains diagnostic;
normal release instructions invoke only publication, which calls the checker once.
No persistent validation receipt/cache or skip-validation escape hatch is added.

The final checker runs these checks once per invocation:

| Check | Selected treatment and reason |
| --- | --- |
| Stable version and nonempty matching note/title | Retain existing identity checks. Remove fixed section-heading checks; content and footer are preparation responsibilities, not a new prose parser. |
| `go mod tidy -diff` | Retain: detects an incomplete checked-in module graph without modifying source. Module downloads are preparation, not application-service calls. |
| Tracked Go formatting and diff whitespace | Retain existing inexpensive source hygiene checks; do not add whole-history scans. |
| `go test -race -count=1 ./...` | The single full suite. It includes doccheck and maintained examples. Race instrumentation adds distinct coverage for Narratio's concurrent I/O, cancellation, and shared state. Remove the separate ordinary full-suite invocation. |
| `go vet ./...` | Retain distinct static checks not established by runtime tests. |
| Release asset builder | Retain three existing targets and embedded-version smoke check. Remove redundant `go build ./...`; package tests compile packages and the builder validates deliverables. |
| Extra focused doc/example test invocations | Remove: covered by the full suite. Remain available for development diagnosis. |

Keep GOWORK=off for owned Go commands. Use explicit `-mod=readonly` on owned
test/vet/build commands, including the asset builder, so incidental vendor trees
are not selected and validation cannot silently edit the module requirements.
Do not overwrite all caller GOFLAGS just to set this option. Keep tidy's own
`-diff` mode. These choices preserve the existing module-based release model.

Remove the blanket tracked-go.work/go.work.sum rejection: they are inert with
GOWORK=off. Remove the mere-existence vendor-directory rejection. Narrow the
existing all-replacements ban to filesystem replacements: release inputs remain
versioned modules rather than machine-local replacement paths; allow versioned
module replacements. Use Go's module metadata, not regex parsing of replace
blocks. A `go list -m` template inspecting `.Replace.Version` can report local
replacement module names. Do not build a new dependency-policy framework.
This narrows an existing prohibition; supporting repository-local replacement
modules is not introduced by this work.

Retain exact-candidate guards, origin/main matching, clean tracked/untracked state
as reported by Git, fresh versions, lightweight tags, explicit-ref push, and
builder destination protections. Ignored local files alone do not fail release.
Do not add successful-push network read-back, CI polling, native macOS checks,
new artifacts, or application credential requirements. Cheap mutable publication
state checks before and after validation remain justified.

## Stage 1: Adopt common policy, provenance, and orientation

Status: Complete (2026-09-28).

Verification: Compared all adopted policy text with the pinned Git objects;
agents, testing, and meta match after template removal, metadata insertion, and
whitespace cleanup. Reviewed the Narratio-specific documentation, architecture,
and OSS deviations. The CC-BY-SA-4.0 text is byte-identical to the pinned
source. `go test ./internal/doccheck` and `git diff --check` passed. Dependency
attribution and release-policy/procedure alignment remain for later stages.

Read the pinned adoption guide, all seven pinned policy templates, the attribution
example for policies, and current local counterparts. Review the roadmap's local
customizations, root AGENTS.md, and docs/development.md.

1. Adopt agents v1.3, testing v1.3, documentation v1.11, architecture v1.3,
   meta v1.0, and OSS v1.8. Preserve upstream common wording and apply only
   necessary project customizations. Leave release policy adoption to Stage 5,
   when executable behavior will match it. Do not falsely stamp that file now.
2. Preserve Narratio's architecture-specific stage, manifest, storage, credential,
   group-workspace, and platform contracts. Retain troubleshooting ownership;
   omit unused public API responsibilities. Remove redundant local general-agent
   elaborations rather than preserving stylistic variants.
3. Add accurate per-file metadata and adapt upstream agents/AGENTS.md plus the
   supplied selective policy-reading guidance. Preserve existing task routes.
4. Create attribution with the canonical policy entry and local CC-BY-SA-4.0
   text. Describe exactly the material adopted so far, including adapted reading
   guidance. Add COPYRIGHT's limited document-license scope. Root LICENSE and
   the application grant remain unchanged. Do not imply the not-yet-updated
   release policy was adopted from this commit.
5. Keep public discovery links in meta and source/example links pinned. While
   release policy still has its old headings, make the OSS correction-policy
   cross-reference resolve to the existing heading; restore the standard target
   when Stage 5 lands. Do not create dead local example links.

Verification: compare each adopted file to its pinned source, checking that each
remaining substantive deviation is justified. Run doccheck and diff checks.
Record that dependency attribution and release alignment remain incomplete.

## Stage 2: Attribute core modules and shipped Go material

Status: Complete (2026-09-28).

Verification: Resolved selected module tags through Go download metadata and
upstream Git records; verified ConfigKit and both YAML notices against their
selected source revisions. Resolved the release-CI Go 1.26.7 tag to its source
commit. Four new standard license texts match the pinned reference copies by
SHA-256; BSD 3-Clause differs only by removal of trailing whitespace from the
copyright placeholder line. All added commit-pinned source/notice links
returned HTTP 200. Reviewed
tracked source and example material for additional incorporated third-party
notices without finding another concrete item. `go test ./internal/doccheck`
and `git diff --check` passed. AWS module attribution remains for Stage 3.

Read adopted OSS/documentation policy, go.mod, the actual selected module source
licenses/notices, and the build toolchain declarations. Focus this prompt on
ConfigKit, both YAML module generations, go-cmp, x/sync, x/sys, and Go runtime
material. AWS modules are explicitly deferred to Stage 3.

1. Resolve selected versions to exact upstream commits using module download
   metadata or authoritative upstream Git records. Read licenses, notices,
   copyright statements, exceptions, and companion-text requirements at those
   commits. Do not rely on today's default branch or copy another project's
   inventory without verifying the versions and material.
2. Add factual House Format entries and required standard texts. ConfigKit's
   LGPLv3 entry must make both LGPLv3 and GPLv3 texts reachable. Preserve distinct
   YAML v3/v4 notices and actual expressions rather than assuming alternatives.
3. Attribute the runtime/toolchain material incorporated in the declared binary
   builds using the pinned release-CI toolchain source revision. Identify that
   scope factually; do not claim every locally built binary uses that compiler.
   Do not add a new toolchain pin or runtime scanner.
4. Inspect repository material for copied snippets/assets requiring attribution,
   distinguishing consultation from incorporation. Include verified entries;
   record any concrete unresolved material before claiming inventory completion.

Verification: check statements against selected sources, exact-commit links,
verbatim text copies, companion links, and local doccheck. Do not add generated
SBOM tooling, research prose to attribution, or runtime dependency upgrades.

## Stage 3: Complete AWS attribution and public navigation

Status: Complete (2026-09-28).

Verification: Reconciled `go list -m all` with the modules compiled into
Narratio or its maintained tests: all 24 incorporated modules are represented,
including indirect AWS modules. The YAML dependency-test-only
`gopkg.in/check.v1` is selected in the broader module graph but is not compiled
into Narratio or its tests. Go module metadata resolved sixteen SDK modules to
one commit, S3 to a distinct commit, and smithy-go to its own commit. Compared
selected Apache licenses and AWS/smithy notices to their source revisions;
verified new pinned notice and embedded singleflight license links. README
navigation, `go test ./internal/doccheck`, and `git diff --check` passed. No
dependency or released material changed.

Read adopted OSS policy and selected AWS SDK/smithy module license material.
Use go.mod plus Go's selected module graph, including indirect AWS modules.

1. Resolve and document AWS components at their actual selected revisions.
   Monorepo modules may share an entry only with accurate module/revision scope
   and all necessary notice links. Include smithy separately when its source
   and notices differ. Preserve Apache license and relevant NOTICE material.
2. Reconcile the complete attribution document against the module graph, runtime
   scope, and copied-material review. Ensure no dependency was skipped merely
   because it is indirect, and no external subprocess application was included
   solely because it is invoked. Resolve concrete gaps; do not mark them covered
   through generic wildcard prose.
3. End README with the two prescribed grant/attribution statements. Keep the
   inventory factual and centralized; ensure all applicable local texts exist.
   Do not copy unused reference licenses or example collections.

Verification: review coverage and source identity, run doccheck, compare copied
texts to their authoritative sources, and check the diff for accidental secrets
or unrelated source changes. No new legal-approval or network release gate.

## Stage 4: Simplify candidate validation and its behavioral tests

Status: Complete (2026-09-28).

Verification: The checker retains version/title, module hygiene, formatting,
whitespace, one race-enabled full suite, vet, and the asset builder while
removing duplicate test/build invocations. Go module metadata distinguishes
filesystem from versioned replacements; workspace and vendor presence are
inert under GOWORK=off and readonly module selection. Focused release-check
tests cover selected command counts, failure propagation, note handling,
replacement behavior, builder targets/version, and destination protections.
`go test ./internal/releasecheck`, shell syntax checks, `go test
./internal/doccheck`, and `git diff --check` passed. No publication ran.

Read scripts/check-release-candidate.sh, scripts/build-release-assets.sh,
scripts/release-lib.sh, and internal/releasecheck/assets_test.go. Read testing,
architecture, OSS, and both current and target release policy. This stage changes
the checker; Stage 5 completes adopted release policy and operator documentation.

1. Implement the exact selected validation matrix above. Remove fixed release
   note sections, duplicate full/focused tests, and redundant generic build.
   Retain existing note title/version checks without adding a footer parser.
2. Use the selected module mode/workspace handling in checker and builder.
   Replace blanket file/directory guards and replacement parsing as specified.
   Preserve output-directory protections and temporary cleanup ownership.
3. Update candidate test fixtures to accept a concise note without the old
   headings; missing/empty notes and mismatched titles still fail. Test inert
   workspace/vendor presence, local replacement rejection, and versioned
   replacement acceptance using representative metadata through a small Go stub.
4. Update the existing owned-command tests to prove the new gate selection and
   one invocation of each required suite/build, rather than retaining minimum
   command-count assertions. Command observation is appropriate here because
   duplicate validation is the specific regression being prevented. Exercise
   failure propagation without duplicating every unrelated module-tool behavior.
5. Preserve builder tests for three named assets, version injection, GOWORK=off,
   and destination protection. Cover readonly module selection without expanding
   into a new cross-platform infrastructure matrix.

Verification: focused internal/releasecheck tests, shell syntax checks, doccheck,
and diff checks. Do not run the real publication script against origin. Avoid
recursive real full-suite execution from within checker test fixtures.

## Stage 5: Align publication behavior, policy, and operator procedure

Status: Complete (2026-09-28).

Verification: Adopted pinned release policy v1.4 with only metadata and the
selected Narratio validation rationale added to common wording. Publication
reports failed/uncertain tag pushes without asserting nonpublication; offline
bare-remote tests cover one checker call, ignored files, retained local tag,
and the existing exact-ref/branch/candidate guards. The runbook now has one
normal publication command, immutable-tag footer URLs, separate asynchronous
delivery status, and ambiguity/recovery guidance. Updated attribution and
release navigation without changing historical notes. `go test
./internal/releasecheck ./internal/doccheck`, shell syntax checks, and
`git diff --check` passed. No tag, push, or release ran.

Read pinned release v1.4, current docs/policy/release.md and docs/release.md,
scripts/release.sh, and internal/releasecheck/publication_test.go.

1. Adopt release v1.4 verbatim except documented project choices. Record the
   selected extra validation checks and their distinct rationale in a concise
   local section; do not retain obsolete exception/compensating-control prose
   for tag-push completion or authoritative-origin scope.
2. Keep the existing publication interface and pre/post-validation guards.
   Fix push-failure reporting so it says publication failed or is unconfirmed,
   not definitively unpublished: a failed transport can have an ambiguous
   outcome. Keep the local tag for investigation; do not auto-delete or retry.
3. Rewrite the runbook around one publication command. Standalone validation is
   optional diagnosis, not a prerequisite. Keep source commit push before tag,
   exact candidate identity, current three artifacts/checksums, and lightweight
   tagging. No real tag or release is created in this stage.
4. Include the exact three footer links using Narratio Gitea URLs at the intended
   release tag. Preparing the footer and checking target paths locally is enough;
   do not require the future tag to resolve remotely. Preserve hosted note reuse.
5. Explain ambiguous-push investigation and separate artifact delivery status.
   Transient failures can be retried from the immutable tag; already-published
   contents/checksums must not be overwritten. Source/content defects need a new
   release. Do not add an automated retry subsystem.
6. Update policy attribution material scope for the now-adopted release policy
   and the OSS correction-policy link. Update related development guidance so
   it does not retain the old mandatory duplicate release sequence.
7. Preserve offline local-bare-remote tests. Add/adjust checks that the checker
   is called once, ignored files alone do not block publication, a rejected push
   leaves its local tag, and ambiguous failure wording makes no false success or
   nonpublication claim. Keep exact-candidate, branch, dirty-state, uniqueness,
   upstream-change, and explicit-ref protections. No live forge or CI tests.

Verification: focused release/doc tests and shell syntax; inspect all current
release guidance for conflicting requirements. Historical release notes stay
unchanged. Adopt metadata only for the actual document revision incorporated.

## Stage 6: Align CI and contributor validation references

Status: Pending.

Read .woodpecker/verify.yml, .woodpecker/release.yml, .woodpecker/shuffle.yml,
the doccheck workflow graph tests, and docs/development.md.

1. Preserve asynchronous tag CI and its reuse of the candidate checker and
   checked-in note. Revalidation on a separate CI runner is independent delivery
   evidence, not a second synchronous release prerequisite. No CI-result polling.
2. Keep existing push/PR and scheduled race/shuffle responsibilities; broad CI
   optimization is outside this scope. Remove only redundant standalone
   documentation/example steps already covered by that workflow's full suite,
   repairing depends_on edges and corresponding documentation/tests. Do not
   change runner labels, platform targets, or toolchain versions.
3. Keep tag builder/publication dependencies and non-overwrite settings intact.
   The tag checker may build temporary validation assets and the subsequent
   build step creates upload assets; do not introduce cross-job artifact caching
   or a new combined publisher just to remove this delivery separation.
4. Distinguish ordinary developer checks, optional focused diagnosis, and the
   normal release entry point in documentation. Do not imply checks removed
   from the release sequence are forbidden during development.

Verification: doccheck workflow graph validation, relevant release tests, and
manual inspection that no execution path waits for CI or publishes broad refs.
No production CI configuration experiments or network publication are authorized.

## Stage 7: Verify final alignment and close the roadmap

Status: Pending.

1. Compare all seven adopted policies against their exact pinned upstream files.
   Confirm removed template instructions, correct source/version/date metadata,
   verbatim common wording, and justified local content. Check orientation and
   ownership, not just file presence. No metadata-only claim of full adoption.
2. Review attribution scope, modification descriptions, public source/notice
   commits, license texts, and README/release navigation. Ensure upstream example
   collections/guides were linked rather than copied. Do not expand the release
   gate set to automate this one-time adoption review.
3. Run the complete race-enabled suite, vet, shell syntax checks, diff checks,
   and the existing asset builder with its supported synthetic test version into
   a temporary directory. Doccheck and maintained examples run through the suite;
   reuse successful checks for unchanged content. Run tidy -diff and formatting
   checks as selected above. This is verification, not publication: do not create
   a fabricated release note or invoke release.sh on the real repository.
4. Audit test meaning: retained protections still cover candidate identity and
   publication safety; removed checks are redundant or incidental; no new
   contracts, approvals, provider calls, or live-service tests slipped in.
5. Mark this plan and the feature roadmap implemented with actual evidence and
   note release pending. Do not remove unrelated roadmaps or historical audits.
   Commit final coherent documentation/test corrections and report clean status.

## Open Questions

None requiring a product decision. The gate set and local customizations above
resolve the roadmap's planning choices. If source inspection reveals a concrete
rights question outside the adopted arrangements, stop only the affected item,
record the evidence, recommend a treatment and a viable alternative, and obtain
direction rather than inventing attribution or adding a blanket prohibition.