narratio/docs/roadmap/implementation.md

Implementation Plan: Standard Repository Policy Alignment

Status: In progress.

Scope and execution instructions

Implement the policy roadmap. 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. 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: Pending.

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.