diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md index 5c0c7334..42686f7a 100644 --- a/docs/roadmap/policy.md +++ b/docs/roadmap/policy.md @@ -1,207 +1,261 @@ -# Licensing Policy And Attribution Alignment +# Standard Repository Policy Alignment ## Purpose -Adopt the licensing-documentation conventions defined below while -preserving its deliberate policy adaptations, existing project grant, and -source-only release process. This is a documentation and policy work set, not -a relicensing, runtime, or release-automation project. +Bring Notarius's adopted policies into alignment with Standard Repository +Policies, using identical upstream language wherever a substantive, +project-specific decision does not require customization. Preserve Notarius's +application contracts, operator choices, selected code license, and source-only +release process. -This feature roadmap defines the target end state and required changes. It does -not implement the policy or authorize release publication. +This roadmap defines the agreed target and update scope. It does not itself +adopt policies, alter runtime behavior, or authorize a release. -## Reviewed Baseline +## Selected Upstream Revision And Current Baseline -Reviewed on 2026-09-26 against Notarius's current policy documents and pinned -dependencies. The table records the selected policy-version targets; repository -documentation must remain self-contained. +The agreed review, performed on 2026-09-28, uses full upstream commit +`d84a38ebab26f048cafbe59a2246700c35d29843` of +[Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy). +Follow the [adoption and update guide at that revision](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md). +Use that fixed revision for implementation, not whichever revision is then on +`main`. -| Policy | Current Notarius baseline | Target version | Required change | +The comparison is between the current Notarius documents and that revision. +Historical adoption baselines need not be reconstructed or assessed. Introducing +source metadata records the revision actually incorporated by this update, not +a claim about previous adoptions. + +Notarius currently has five policies, no `meta.md` or `oss.md`, and no +`docs/oss/` attribution collection. Its current agent entry point and developer +guide provide orientation but lack the complete selective policy-reading guide. +The project grant is GPL-3.0-or-later; root `LICENSE` contains the GPLv3 text. +README licensing navigation and prospective release-footer instructions are +missing. + +Public upstream discovery and attribution are now expressly approved. This +supersedes the earlier instruction to omit references to the policy source; +local checkout paths are neither necessary nor appropriate public references. + +## Alignment Rules + +- Start from the selected upstream wording, not a paraphrase of it. Adopt + non-substantive wording changes verbatim. +- Retain local variations only for substantive, locally significant + requirements or decisions. Explain their purpose in the relevant policy + section or link to existing rationale; do not add a separate exception registry. +- Follow each template's adoption instructions and remove its entire + `Base Policy Template` section. Replace required project-specific guidance + rather than leaving template instructions in an adopted policy. +- Preserve deliberately selected contracts. Simplifying duplicate wording does + not authorize changing architecture, runtime behavior, or release mechanics. +- Keep local policies authoritative. Upstream changes take effect only through + deliberate adoption; no automatic synchronization is introduced. + +## Target Policy Set And Justified Customizations + +| Local file | Current version | Target version | Required treatment | | --- | --- | --- | --- | -| `docs/policy/oss.md` | Absent | 1.2 | Adopt the licensing and attribution policy with Notarius-specific adaptation. | -| `docs/policy/documentation.md` | 1.3 | 1.5 | Merge licensing ownership and discoverability rules. | -| `docs/policy/release.md` | 1.1 | 1.2 | Add prospective release-footer guidance without new publication gates. | -| Agents, architecture, testing | 1.1 | 1.1 | Retain existing substantive rules. | +| `docs/policy/agents.md` | 1.1 | 1.3 | Adopt substantive upstream wording verbatim. Remove redundant local preamble and the ADR-0017 illustration; architecture already owns the deployment-permissions decision. No substantive exception is needed. | +| `docs/policy/architecture.md` | 1.1 | 1.3 | Adopt general purpose, ownership, architectural approach, and constraint-versus-implementation guidance while retaining the application-specific decisions described below. | +| `docs/policy/testing.md` | 1.1 | 1.3 | Adopt substantive upstream wording verbatim. Existing risk-based testing remains intact; no project-specific exception or test rewrite is needed. | +| `docs/policy/documentation.md` | 1.3 | 1.11 | Adopt upstream wording and licensing/provenance ownership rows. Customize consumer ownership for subprocess use and omit the inapplicable HTTP-contract row. Remove the duplicate local implementation-details-versus-policy section; agent policy owns that rule. | +| `docs/policy/release.md` | 1.1 | 1.4 | Adopt upstream wording with the existing source-only choices and selected gates below. Add prospective OSS-footer guidance. | +| `docs/policy/meta.md` | Absent | 1.0 | Add upstream substantive wording, including public discovery links, local authority, and local attribution navigation. | +| `docs/policy/oss.md` | Absent | 1.8 | Add upstream substantive wording, commit-pinned example links, and required Notarius context through canonical documents. | -`COPYRIGHT` already identifies Notarius, its copyright statement, and the -`GPL-3.0-or-later` grant, including the warranty disclaimer and third-party -material statement. `LICENSE` contains the matching GPLv3 text. No substantive -license-text change is required. +No existing policy remains entirely unchanged: all five need wording and/or +provenance updates. This does not imply new substantive testing or agent rules. -Current gaps are the absent `docs/oss/` attribution materials, missing README -licensing navigation, missing contributor routing to an OSS policy, and missing -release-footer instructions. `docs/integrations/pkg-promptkit.md` currently -contains a dependency-license paragraph but is not a canonical attribution -inventory. +### Architecture Exceptions -## Target End State +The architecture template expressly requires application-specific content. +Retain Notarius's fixed stage sequence rather than an arbitrary DAG, +artifact-family ownership across stages, domain-neutral framework, inward +dependency direction, external adapter boundaries, and content-only assets +package. Retain adopted validation/retry, scheduling, identity, evidence, +configuration, and provenance contracts. -### Policy Alignment Without Policy Replacement +Preserve operator-owned filesystem access policy and the separately adopted +correctness boundaries, cache/checkpoint eligibility, output/debug lifecycle, +secret handling, and platform/distribution decisions. These express existing +product requirements and ADR-backed choices, not stylistic variations. +Use existing architecture and ADRs as their authority; this migration does not +authorize strengthening or weakening them. -Adopt the OSS House Format and maintenance rules defined below in -`docs/policy/oss.md`, adapted to Notarius. All links must resolve within this -repository or to public authoritative sources; no adjacent checkout is required. +Keep concrete package inventories and implementation mechanics in their current +internal-documentation homes. No architecture redesign, new threat model, or +new abstraction is part of this work. -Identify Notarius as an application with its already selected -`GPL-3.0-or-later` grant. Preserve the distinction between licensing -defaults and explicit author choices: adopting the policy does not change -existing grants, infer different licenses for internal packages, automatically -advance copyright years, or assume ownership of third-party contributions. +### Documentation Exceptions -Merge the new documentation ownership rows and licensing boundary guidance into -Notarius's adapted documentation policy. Merge the release-footer provision -into its adapted release policy. Do not replace either document wholesale. -Preserve subprocess-consumer ownership, prospective/current documentation -boundaries, immutable accepted ADRs, and the distinction between descriptive -implementation details and adopted policy. +Notarius's consumer interface is primarily a subprocess CLI, not a public Go +API. Retain `docs/consumers/` ownership for that workflow and its consumer +responsibilities. Retain integration contracts as the owners of durable receipt +and artifact shapes. No HTTP service documentation or placeholder API document +is needed. -Changed or newly adopted policies must record their base policy version and -actual adoption date. Do not add private provenance headers, links, or attribution -entries. Unchanged policies need no version or date churn. +Other editorial variations should use upstream language, including the current +versus future behavior and accepted-ADR rules. Preserve their meaning without +retaining duplicate local formulations. -### Canonical Licensing Documentation +### Release Exceptions -| Path | Target responsibility | -| --- | --- | -| `COPYRIGHT` | Existing project identity, copyright statement, SPDX expression, grant, disclaimer, and third-party scope statement. | -| `LICENSE` | Existing complete project license text. | -| `docs/policy/oss.md` | Licensing conventions, attribution format, maintenance, discoverability, and treatment of concrete exceptions. | -| `docs/oss/attribution.md` | Canonical component-specific attribution entries. | -| `docs/oss/licenses/` | Applicable complete, verbatim standard dependency license texts, including required companion texts. | -| `README.md` | Friendly navigation to the project grant and attribution. | -| `docs/development.md` | Task-specific routing for licensing, dependency, attribution, and release-document changes. | -| `docs/release.md` | Concrete release-footer URLs and preparation instructions for Notarius's existing publication channel. | +Preserve source-only delivery, lightweight tags, `main` on `origin`, +branch-before-tag publication, and no prereleases. There are no binaries, +hosted release objects, or asynchronous artifacts to publish or recover. +Use upstream generic language where applicable, but do not introduce those +channels or atomic-push requirements. -Retain the substance of `COPYRIGHT` and `LICENSE`. Adding a missing final newline -is optional formatting cleanup, not relicensing or a prerequisite to adoption. +Retain the native CLI build and injected-version check with `GOWORK=off`: +it protects the executable entry point and release version, which package tests +alone do not verify. Preserve its documented rationale and existing optional +diagnostics. No additional validation gate is warranted. -### Attribution Based On Actual Incorporated Components +Retain the decision not to create retrospective notes for v0.1.0, v0.2.0, or +v0.3.0. Apply new footer formatting prospectively; do not rewrite published +history to retrofit it. -Inventory relevant direct and transitive dependencies and copied code/assets. -Use `go.mod`, the resolved dependency/build graph, pinned module contents, and -repository evidence to identify scope; do not treat either direct dependencies -alone or every `go.sum` entry as the complete attribution inventory. Development -tools do not automatically require entries merely because maintainers use them. +## Provenance And Selective Reading -The current module declarations identify these starting points: +Each of the seven policies must retain its actual target `Base Policy Version`, +set `Last Updated` to its actual local adoption date, and add an +`Upstream Source` link to its own source file. For example: -- ConfigKit v0.4.1 and PromptKit v0.11.1; -- `github.com/santhosh-tekuri/jsonschema/v6` v6.0.2; -- `golang.org/x/text` v0.40.0; -- `gopkg.in/yaml.v3` v3.0.1 and `go.yaml.in/yaml/v4` v4.0.0-rc.6; -- PromptKit's OpenRouter and Rakestrawhome backend catalogs at their pinned - v2.20260926.0 revisions (now MIT licensed). - -This list is an inspection starting point, not a pre-approved license inventory. -Verify each relevant component's terms, notices, and exact source revision at -the imported version; do not infer them from a newer sibling checkout or common -project ownership. Inspect copied material separately from Go module imports. - -Each attribution entry follows the five-field House Format: - -1. Project name. -2. Upstream copyright statement or statements, preserving their wording. -3. Applicable SPDX identifier or expression, preserving alternatives/exceptions. -4. License and notice links. -5. Corresponding source repository link. - -Copy only applicable standard license texts from public authoritative sources, -such as the license publisher or the verified dependency release. -Preserve them verbatim and keep explanations outside the texts. Shared standard -texts may serve multiple entries. Include directly reachable companion texts; -for example, an LGPLv3 entry must link to both LGPLv3 and GPLv3 texts. - -Component source and project-specific notice links must identify the exact -imported commit, not a branch or version tag. Determine those commits from -authoritative module/VCS metadata; do not guess them. Classify upstream files -by their contents: `LICENSE` or `COPYING` can contain project-specific statements -as well as standard wording. - -Use the selected convention that direct links to project-specific -notices satisfy the notice-reproduction format. Do not add local copies or -repeated approval requirements solely because license language refers to -reproduction or inclusion. Preserve notices already present in incorporated -source. Concrete obligations or unresolved rights questions outside this -convention receive their own documented treatment; the formatting policy is not -a blanket license-compatibility determination. - -### Discoverability And Maintenance - -End README with these links, consistent with the existing project grant: - -```markdown -Notarius is licensed under the [GPL v3.0 or later](COPYRIGHT). - -[Open Source attribution notices](docs/oss/attribution.md) are available. +```text +https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md ``` -Add a contributor reading-guide entry that routes licensing, dependency, -attribution, and release-document changes to `docs/policy/oss.md` and the relevant -canonical materials. Update component entries in the same change that adds, -removes, upgrades, copies, or changes distribution of a relevant component. +Substitute the correct filename for each policy; do not link every header to +the repository root or adoption guide. Retain provenance through subsequent +local edits. -The PromptKit integration guide should link to its canonical attribution entry -instead of maintaining a competing notice inventory. Keep integration behavior -and pinned API documentation in that guide; the exact-commit rule for attribution -links does not require rewriting unrelated API-reference links. +Use current public discovery URLs in `meta.md`: -### Prospective Release Navigation +- https://gitea.maximumdirect.net/eric/policy +- https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md -New release notes end with links whose visible text is -`COPYRIGHT | LICENSE | ATTRIBUTION`, using absolute URLs to the corresponding -Notarius files at the immutable release tag or source revision. Unlike upstream -component attribution links, these release-navigation links may use the release -tag. +Discovery links intentionally follow the current project and guide. +Adopted-source, example, and attribution links identify immutable commits. +The OSS template already includes commit-pinned example references; retain +accurate pinned references rather than converting them to branch links. -`docs/release.md` supplies a copyable footer using Notarius's Gitea repository -and the selected release version. Check intended paths against the candidate -source during preparation; an unpublished tag need not resolve remotely yet. +Adapt upstream `agents/AGENTS.md` into root `AGENTS.md`, preserving applicable +existing instructions. Direct readers to `docs/development.md`, require agent +policy before recommending/planning/implementing changes, and explicitly avoid +reading the whole policy suite by default. -Notarius continues publishing source through lightweight Git tags and checked-in -release notes. It has no hosted release objects or separate download pages, so -hosted-page guidance is currently inapplicable. Do not create -another publication channel to satisfy it. Preserve branch-before-tag order, -the existing validation command, and successful tag push as release completion. +Merge the upstream adoption guide's Policy Reading Guide into +`docs/development.md`. Include all seven task triggers, especially policy +updates, dependency/licensing changes, validation selection, and compatibility +decisions. Preserve focused subsystem navigation without duplicating policy +triggers across competing tables. Reuse policies already in context, expand +reading when scope expands, and read affected cross-policy provisions when +revising a policy. -Apply the formatting convention prospectively. Do not rewrite historical notes, -published tags, or accepted ADRs merely to retrofit navigation. Handle any actual -omission discovered during inventory deliberately under the applicable policy, -not by changing published history. +## Licensing And Attribution Target -## Scope Boundaries +### Copied Policy Material -- No application-code or dependency-version changes are needed for this work. -- No substantive rewrite of the existing project grant is proposed. -- No new ADR is needed merely to adopt these explicit policy choices. -- No mandatory license scanner, SBOM, blanket per-file header sweep, recurring - legal sign-off, or full dependency security audit is introduced. -- No publication-time network check, CI polling, extra approval gate, binary - packaging, or release-script redesign is introduced. -- Do not copy unused standard license texts or create placeholder documentation. -- Do not weaken or strengthen unrelated Notarius invariants and operator choices. +Follow the selected upstream grant and canonical policy-attribution example: -## Acceptance And Verification +- Create `docs/oss/attribution.md` with the House Format title and insert the + Standard Repository Policies entry using the selected full commit for its + source, COPYRIGHT, and LICENSE URLs. +- Identify actual copied/adapted material and modification status. Include + `docs/policy/`, the adapted root `AGENTS.md`, and the copied policy-reading + guide within `docs/development.md` as applicable. Do not claim unrelated + developer documentation was copied or relicense unrelated material. +- Preserve supplied copyright, license, and disclaimer notices through the + specified arrangement; keep the entry factual rather than adding compliance + or research commentary. +- Copy the complete, verbatim `CC-BY-SA-4.0.txt` to `docs/oss/licenses/`. +- Add the separately licensed policy-material scope to `COPYRIGHT`, pointing + to attribution for exact scope and notices. Adapted policy material remains + CC-BY-SA-4.0; application code remains GPL-3.0-or-later. Leave root `LICENSE` + unchanged. -- The adopted OSS policy, documentation policy 1.5, and release policy 1.2 agree - on canonical ownership and preserve Notarius's deliberate adaptations. -- Policy metadata identifies the base policy version and actual adoption - date, without private provenance; unchanged policies retain their existing - metadata. -- Project licensing statements remain consistent with `GPL-3.0-or-later`. -- Attribution covers the relevant incorporated components identified by the - inventory, including applicable transitive dependencies and copied material. - Entries preserve upstream statements and use verified exact-commit links. -- Applicable local standard texts are complete and faithful, with companion - texts directly reachable from their entries. No unrelated license bundle is - imported. -- README, contributor guidance, integration references, and the release runbook - link to canonical materials without duplicating the attribution inventory. -- New-release footer instructions work with the existing source-only workflow; - historical releases and publication mechanics are unchanged. -- Review edited relative links, source/notice destinations, SPDX expressions, - and standard-text comparisons, and run `git diff --check`. This documentation - change does not itself warrant production model runs or new runtime tests. +The upstream licensing-format examples are CC0; using their original formatting +alone does not require a separate attribution entry. This does not exempt +copied policy prose from its stated terms. -There are no blocking design decisions at the reviewed baseline. Any concrete -unresolved upstream notice or rights issue found during inventory should be -recorded with its evidence rather than resolved by an invented blanket rule. +### Incorporated Dependencies And Assets + +Complete the previously planned inventory of relevant direct/transitive +dependencies and copied code/assets using `go.mod`, resolved build dependencies, +and exact pinned source contents. Neither direct imports alone nor every +`go.sum` entry defines the inventory. + +Current starting points are ConfigKit v0.4.1, PromptKit v0.11.1, both PromptKit +backend catalogs v2.20260926.0, jsonschema/v6 v6.0.2, x/text v0.40.0, yaml.v3 +v3.0.1, and yaml/v4 v4.0.0-rc.6. Verify actual incorporation, terms, notices, +and exact commits; this list is not a pre-approved attribution inventory. + +Use the upstream OSS House Format without editorial elaboration. Copy only +applicable standard and companion license texts, retaining their wording. +Link component-specific notices and sources at the exact imported commit. +Apply the upstream house interpretation of linked notices without inventing +extra local-copy requirements, recurring approvals, or licensing conclusions. +Handle a concrete uncovered obligation separately if one is discovered. + +### Navigation And Canonical Ownership + +- End `README.md` with the project-grant and attribution links prescribed by + OSS policy, using Notarius's GPL-3.0-or-later grant. +- Update `docs/release.md` with a copyable prospective + `COPYRIGHT | LICENSE | ATTRIBUTION` footer using absolute Notarius URLs at + the release tag or corresponding immutable source revision. Check intended + local paths before publication; do not require an unpublished tag to resolve. +- Update `docs/integrations/pkg-configkit.md` and + `docs/integrations/pkg-promptkit.md` to link to canonical attribution rather + than maintaining competing notice inventories. Keep behavioral/API references + in those integration guides. + +## Local Materials And Upstream-Only References + +Keep the seven adopted policies, adapted agent entry point, project-specific +developer guide, actual notices, and applicable license texts locally. + +Keep the upstream README, root AGENTS.md, contributor guide, adoption guide, +and example collection upstream. Link to them when appropriate instead of +copying an additional documentation tree. Do not copy unused license texts, +example projects, or placeholder documents. Root Notarius `AGENTS.md` is based +on upstream `agents/AGENTS.md`, not upstream's own contributor instructions. + +## Recommended Work Sequence + +1. Adopt the policy set and orientation changes together with copied-policy + attribution, its local license text, and the COPYRIGHT scope statement. + Keep cross-links valid at this boundary. +2. Complete incorporated-component attribution and applicable license texts; + connect README, integration guidance, and prospective release navigation. +3. Compare the result directly with the selected upstream files, verify that + remaining variations have the stated local justification, and check notices, + metadata, and links. + +These are coherent work boundaries, not authorization to execute them during +roadmap preparation. A later implementation plan may subdivide them. + +## Scope Boundaries And Acceptance + +- No application code, dependency pins, tests, release scripts, or published + history change merely to adopt policy wording. +- No new ADR, recurring policy-sync job, SBOM, scanner, blanket header sweep, + security audit, platform matrix, approval round, or release gate is required. +- All seven policies use the selected versions and correct file-specific source + links, with actual adoption dates and no remaining template-only sections. +- Non-substantive differences use upstream wording; substantive variations are + confined to justified Notarius responsibilities and decisions. +- Orientation supports selective reading and public upstream discovery without + requiring a sibling checkout. +- Attribution accurately identifies copied material, modifications, selected + dependency revisions, notices, and faithful local license texts. Application + and policy-material license scopes remain distinct. +- Canonical navigation works without duplicate notice inventories, nonexistent + interface documents, or copied upstream guide/example collections. +- Validate affected relative and public links, metadata targets, license-text + fidelity, and `git diff --check`. Ordinary document review is sufficient; + production model runs and new runtime tests are not warranted. +- Resolve only concrete newly discovered rights or scope issues with the user; + do not reopen settled choices through blanket approval requirements. + +There are no blocking open design decisions at the agreed review baseline.