notarius/docs/roadmap/implementation.md

# Policy Alignment Implementation Plan

## Purpose And Execution Contract

Implement [Standard Repository Policy Alignment](policy.md). That feature
roadmap owns the target policy choices and justified Notarius exceptions; this
document owns implementation order. It replaces the completed kit-upgrade plan,
not the implementation or contracts delivered by that earlier work.

Each numbered stage is one bounded prompt for a gpt-5.6-terra coding agent.
Complete stages in order. Inspect the worktree before each stage, preserve
unrelated work, validate the resulting documentation, and commit the coherent
stage under agent policy. Report changed files, checks, and any concrete blocker.
Do not push, tag, publish, or retire unrelated roadmaps.

This is a documentation/policy migration. Do not change application code,
dependency pins, tests, release scripts, runtime contracts, or release gates.
No production credentials or model calls are needed.

## Fixed Sources And Adoption Rules

Use upstream full commit
`d84a38ebab26f048cafbe59a2246700c35d29843` throughout.
Begin with its
[adoption guide](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md).
Read applicable local policies through `docs/development.md`; when revising a
policy, also read the upstream counterpart and affected cross-policy provisions.
Do not reconstruct historical adoption baselines.

Retrieve pinned files through public URLs or `git show` against that exact
commit in an available checkout. Do not use an unverified sibling working tree
or silently select newer upstream content. An unavailable source is a concrete
blocker to copying it accurately, not a reason to invent its text.

For every adopted policy:

- Copy upstream wording verbatim except for required template removal and the
  agreed, substantive project-specific customizations in the feature roadmap.
- Retain its upstream Base Policy Version; set Last Updated to the actual date
  the local document is adopted, not the review date by habit.
- Add Upstream Source pointing to its own file at the full selected commit:
  `https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/FILE.md`.
- Remove the entire Base Policy Template section and perform its instructions.
  Keep upstream generic rules outside it, including commit-pinned example links.
- Explain substantive local exceptions briefly where they apply, or retain an
  existing rationale/ADR link. Do not create an exception registry or preserve
  stylistic paraphrases merely because they already exist.

Current public project and adoption-guide links are discovery links; they may
follow main. Source, example, and attribution links stay commit-pinned. Preserve
accurate preexisting example pins supplied by the selected OSS template.
Metadata must reflect only documents actually adopted by the current stage.
The transition may temporarily contain mixed versions without claiming otherwise.

## Stage 1 — Establish Provenance And Copied-Policy Licensing

**Status:** Complete (2026-09-28).

**Goal:** Establish the self-contained adoption and licensing foundation.
One prompt limited to two short policies and their actual notice materials.

**Read:** Selected upstream `docs/policy/meta.md` (1.0),
`docs/policy/oss.md` (1.8), `COPYRIGHT`,
`examples/licensing/policy-attribution.md`, and the adoption guide;
local `COPYRIGHT`, `LICENSE`, and the feature roadmap.

**Files:** Create `docs/policy/meta.md`, `docs/policy/oss.md`,
`docs/oss/attribution.md`, and
`docs/oss/licenses/CC-BY-SA-4.0.txt`; update `COPYRIGHT`.

1. Adopt meta and OSS using the fixed-source rules. Keep public discovery URLs
   in meta and link to the existing local developer guide and new attribution.
   Point project-specific OSS context to Notarius's grant and release runbook;
   do not import generic example projects.
2. Create attribution with `# Open Source Attribution Notices` followed by
   the canonical policy entry. Replace all three UPSTREAM_COMMIT placeholders.
   Initially identify the two newly adopted policy files as adapted material.
   Later stages expand this statement as their material is actually adopted;
   do not imply that the older five files have already been refreshed.
3. Copy the complete CC BY-SA 4.0 standard text from the pinned reference asset.
   Preserve the canonical copyright/SPDX/notices/source arrangement and its
   modification indication. Do not add research or compliance prose.
4. Add a distinct scope statement to COPYRIGHT: policy material adapted from
   Standard Repository Policies remains CC-BY-SA-4.0, with attribution defining
   the affected material. Keep the existing GPL-3.0-or-later application grant,
   warranty disclaimer, and third-party statement; leave root LICENSE unchanged.
5. Do not create placeholder dependency entries. Dependency inventory is assigned
   to Stages 4–5, and remains tracked here rather than asserted complete.

**Acceptance:** Both policies have correct versions, date, file-specific source
links, and no template-only section. All new relative links resolve. Attribution
describes this stage's actual material, and code licensing is unchanged.

**Validation:** Compare copied policy bodies and license text to the pinned
sources; inspect deliberate substitutions. Run `git diff --check` and review
the COPYRIGHT diff. No Go tests are needed.

## Stage 2 — Standardize General Policies And Selective Orientation

**Status:** Complete (2026-09-28).

**Goal:** Adopt the general rules and their reading workflow. One prompt:
three largely verbatim policy updates plus small orientation edits.

**Read:** Local agent/testing/documentation policies; pinned upstream versions
1.3, 1.3, and 1.11 respectively; upstream `agents/AGENTS.md` and the adoption
guide's Policy Reading Guide; local `AGENTS.md` and `docs/development.md`.

**Files:** Update `docs/policy/agents.md`, `testing.md`,
`documentation.md`, root `AGENTS.md`, `docs/development.md`, and
`docs/oss/attribution.md`.

1. Adopt agent and testing substantive wording without local paraphrases.
   Remove the redundant agent preamble, additional generic contract-preservation
   prose, and ADR-0017 illustration. Its decision remains in architecture/ADR;
   this is not permission to change it.
2. Adopt documentation wording and ownership rows. Customize the consumer row
   for existing subprocess guidance, not a hypothetical public Go API.
   Omit the inapplicable HTTP contract row; preserve applicable CLI/config/
   operations/integration/internal ownership. Remove the local duplicate
   implementation-details-versus-policy section.
3. Base root AGENTS.md on upstream `agents/AGENTS.md`, not upstream root
   AGENTS.md. Preserve applicable existing instructions. Require orientation
   through the developer guide and agent policy, but not full-suite reading.
4. Add the adoption guide's seven-row selective Policy Reading Guide and its
   selection/reuse/scope-expansion rules to docs/development.md. Retain existing
   subsystem navigation and validation guidance; remove redundant competing
   policy-trigger rows from the old table rather than creating two authorities.
5. Expand the attribution material statement to identify the newly refreshed
   policy files, adapted AGENTS.md, and copied policy-reading-guide portion of
   docs/development.md. Do not license the unrelated remainder as copied policy.
   Ensure the COPYRIGHT scope statement covers these identified portions.

**Acceptance:** General rules match upstream, except required documentation
ownership customization. All seven policy triggers are available; existing
subsystem links still work. Reading is selective and public discovery is reachable.
No test changes or stricter testing/commit requirements were introduced.

**Validation:** Diff each policy against its pinned source, inspect AGENTS and
developer-guide navigation, check attribution scope and relative links, and run
`git diff --check`. Search affected files for leftover template instructions.

## Stage 3 — Align Architecture And Release Policies Without Contract Changes

**Goal:** Complete the customized policies and release navigation. One prompt
focused on preserving existing decisions rather than redesigning them.

**Read:** Local architecture and release policies, docs/release.md, relevant
linked ADRs; pinned upstream architecture 1.3 and release 1.4. Use
docs/internal/overview.md and existing canonical contracts only where needed to
resolve an ownership question.

**Files:** Update `docs/policy/architecture.md`, `docs/policy/release.md`,
`docs/release.md`, and `docs/oss/attribution.md`.

1. Adopt upstream general architecture ownership/approach guidance. Replace its
   application-specific template guidance with Notarius's existing decisions.
   Preserve the feature roadmap's enumerated pipeline, module, assets, domain,
   identity, validation/retry, scheduling, configuration/provenance, state,
   secret-handling, permissions, platform, and distribution contracts.
   Keep existing application-specific sections unless an edit is necessary for
   the adopted structure; do not turn this into a broad architecture rewrite.
2. Adopt release wording with narrow project customizations: source only,
   lightweight tags, main/origin, branch-before-tag, no prereleases, and no
   hosted/asynchronous deliverables. Keep the native CLI/version check and
   GOWORK=off rationale. Preserve the historical no-retrospective-notes decision.
   Retain unchanged generic requirements verbatim.
3. Add the OSS footer rule for new notes. Update the runbook with a copyable
   three-link COPYRIGHT | LICENSE | ATTRIBUTION footer using absolute
   `https://gitea.maximumdirect.net/eric/notarius/src/tag/<version>/...` paths.
   Explain substitution of the selected release tag and local path checking.
   Do not require a future tag to resolve or change publication scripts.
4. Expand policy attribution to the complete adopted docs/policy set, retaining
   the AGENTS/developer-guide scope from Stage 2 and any relevant adaptation
   indications. All seven per-document source links now identify this adoption.

**Acceptance:** Existing architecture and release choices are unchanged and their
local reasons remain clear. Upstream generic wording is used where applicable.
There are no new gates, platforms, artifacts, retrospective notes, or ADR edits.

**Validation:** Review policy diffs specifically for added/removed requirements,
check runbook agreement and affected links, and run `git diff --check`.
Do not run a release/publication command. No runtime tests are warranted.

## Stage 4 — Attribute The Kit Dependencies And Catalogs

**Goal:** Add the first bounded group of component notices: ConfigKit,
PromptKit, and their two backend catalogs. One prompt for four related projects.

**Read:** Adopted OSS policy; go.mod/go.sum, resolved build dependency metadata;
exact selected module COPYRIGHT/LICENSE/NOTICE/attribution files and VCS metadata.
The reviewed pins are ConfigKit v0.4.1, PromptKit v0.11.1, and both catalog
modules v2.20260926.0; verify the actual selected versions before writing.

**Files:** Update `docs/oss/attribution.md`; add applicable texts under
`docs/oss/licenses/`.

1. Use read-only discovery such as `GOWORK=off go list -m -json all`,
   `GOWORK=off go list -deps ./cmd/notarius`, and selected module contents.
   Dependency acquisition may populate the module cache but must not change
   dependency pins or introduce a local replace directive.
2. Establish each selected version's exact source commit from module/VCS
   metadata; peel annotated tags to commits. Do not substitute a tag object ID,
   main-branch head, assumed sibling HEAD, or version tag in attribution URLs.
3. Add factual House Format entries with supplied copyright statements,
   applicable SPDX expressions, local standard-text links, required upstream
   notice links, and exact-commit Source links. Preserve alternatives and
   exceptions; determine scope from contents rather than filenames.
4. Include LGPLv3 and its GPLv3 companion for the kit grants, and MIT for the
   catalogs where confirmed by the pinned sources. Reuse shared local standard
   texts; leave root project LICENSE unchanged.
5. Inspect upstream dependency inventories for leads, but do not copy them
   wholesale or treat them as substitutes for Notarius's own inclusion scope.
   Hand remaining selected third-party components to Stage 5 through the stage
   report, not editorial prose in attribution.

**Acceptance:** These four components have verified source/notice links and
complete applicable local texts. No dependency changes, guessed notices, or
new distribution obligations were invented.

**Validation:** Check exact revision correspondence, upstream filenames, every
new local license link, and byte fidelity of standard texts. Run
`git diff --check`; confirm go.mod/go.sum are unchanged. Report discovery
commands and evidence; do not add a persistent inventory tool or audit artifact.

## Stage 5 — Complete Attribution And Connect Reader Navigation

**Goal:** Finish remaining incorporated-component coverage and canonical
navigation. One prompt for the remaining small dependency set and doc links.

**Read:** Adopted OSS policy, remaining selected module/source notices,
README.md, integration guides, and repository evidence of copied code/assets.
Start with jsonschema/v6 v6.0.2, x/text v0.40.0, yaml.v3 v3.0.1, and yaml/v4
v4.0.0-rc.6, then resolve any additional actual incorporation revealed by
Stage 4. A go.sum entry alone is not proof of incorporation.

**Files:** Update `docs/oss/attribution.md`, applicable
`docs/oss/licenses/*`, `README.md`,
`docs/integrations/pkg-configkit.md`, and
`docs/integrations/pkg-promptkit.md`.

1. Inspect direct/transitive incorporation and copied material separately.
   Apply the same exact-revision, factual-entry, and faithful-text rules as
   Stage 4. Include relevant components, not every tool used in development.
   Do not add generic entries with unresolved versions or copyrights.
2. Use the OSS format for omitted copyright/SPDX fields where the source
   supplies no applicable value. Preserve required project-specific notices.
   Raise only a concrete unresolved obligation or rights issue; do not seek
   blanket approval for the already selected linked-notice arrangement.
3. End README with the prescribed GPL-v3-or-later COPYRIGHT link and the
   Open Source attribution notices link. Do not imply that every incorporated
   component or document has the application's license.
4. Replace competing license/notice paragraphs in both integration guides with
   concise links to the relevant canonical attribution anchors. Keep dependency
   pins, behavior, compatibility, and public API links in the guides.
5. Keep the attribution document to its title and factual component entries.
   Do not include the inventory research, legal conclusions, or completion logs.
   Do not copy unused upstream examples or standard licenses.

**Acceptance:** Attribution covers the verified relevant components and copied
policy material, with only applicable texts. README and integration links point
to the canonical inventory; no user-visible API or dependency settings change.

**Validation:** Review coverage against resolved dependencies and inspected
copied-material evidence, validate affected relative/source links and text
fidelity, and run `git diff --check`. No Go suite, scanner, or SBOM is required
solely for documentation changes.

## Stage 6 — Verify The Complete Adoption

**Goal:** Perform the cross-document check and correct scoped documentation
defects. One prompt; no fresh feature work or automated policy-sync system.

**Read:** The feature roadmap; the seven resulting policies and their pinned
sources; AGENTS.md, developer guide, COPYRIGHT, README, attribution/license
materials, release runbook, and affected integration links.

**Work and acceptance:**

1. Compare all seven policies directly against the selected revision. Classify
   remaining differences as metadata, template removal, required customization,
   or a feature-roadmap exception. Replace accidental paraphrases with upstream
   wording. Preserve established local requirements.
2. Confirm versions 1.3/1.3/1.11/1.3/1.4/1.0/1.8 for agents, architecture,
   documentation, testing, release, meta, and OSS respectively. Verify each
   Upstream Source targets its own file and Last Updated reflects actual work.
3. Confirm discovery links follow public project/main-guide URLs while adopted
   source, examples, and component attribution remain accurately commit-pinned.
   Check no placeholder UPSTREAM_COMMIT, template-only section, or local
   checkout-dependent reference remains in adopted materials.
4. Check selective policy routing, local authority, canonical documentation
   ownership, copied-material scope/modification status, unchanged application
   grant/root LICENSE, and directly reachable license/companion texts.
5. Verify source-only publication, selected gates, optional diagnostics,
   release completion, and prospective-only footer guidance still agree.
   Do not modify historical notes, accepted ADRs, or scripts to satisfy this check.
6. Review changed-file scope: only intended policy, notice, and supporting
   documentation files should have changed. Correct in-scope documentation
   defects, report unresolved concrete issues, and leave unrelated roadmap
   retirement and release preparation to an explicit later request.

**Validation:** Run `git diff --check`; inspect file/link destinations and
compare local standard texts with verified sources. A search for
`Base Policy Template` or `UPSTREAM_COMMIT` in adopted files should be empty;
do not confuse explanatory roadmap text with an unfilled adopted template.
No production tests, new test framework, recurring synchronization gate, or
release execution is needed.

## Open Questions

None at the agreed baseline. Policy choices and exceptions are settled.
A newly discovered concrete notice/source or rights issue should be reported
with evidence and viable treatments rather than resolved by inventing a broader
requirement. That contingency does not authorize reopening settled policies.