From a5a252ab30da963eda2102b8061ee007d1269b58 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 28 Sep 2026 01:13:10 +0000 Subject: [PATCH] Expand roadmap to align the full policy set --- docs/roadmap/policy.md | 324 +++++++++++++++++++++-------------------- 1 file changed, 168 insertions(+), 156 deletions(-) diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md index 004544c..ba9a72b 100644 --- a/docs/roadmap/policy.md +++ b/docs/roadmap/policy.md @@ -1,196 +1,208 @@ -# Align Licensing Documentation With the Standard Policy +# Align Narratio With Standard Repository Policies Status: Accepted; implementation pending. -## Goal +## Goal and Approved Scope -Adopt the agreed licensing-documentation conventions without changing -Narratio's license, runtime behavior, or release responsibility boundary. Make -project licensing and upstream attribution easy to find and maintain through -ordinary development and release preparation. +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 roadmap defines the target and scope, not implementation sequencing. +This document defines the target and scope, not implementation stages. 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. -## Current Baseline +## Fixed Review Revision and Baseline -The agreed house conventions cover project licensing, component attribution, -and README/release navigation. Policy templates are internal administrative -material, not an attribution source. Do not cite or link their repository, -filesystem location, or contents in Narratio documentation. Adopted policies -must be self-contained; license texts and component notices must trace to their -actual public publishers and upstream projects. +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. -Narratio currently has: +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. -- A root `COPYRIGHT` identifying Narratio, its copyright holder, and the - `GPL-3.0-or-later` grant, warranty disclaimer, and third-party-material caveat. -- A complete root `LICENSE` matching the standard GPLv3 text except - for a missing final newline. No substantive licensing correction is needed. -- Documentation policy based on v1.1, without the new licensing ownership map, - and no `docs/policy/oss.md` or `docs/oss/` attribution collection. -- A README without the prescribed closing license and attribution navigation. -- Release policy and procedure without the new licensing footer convention. - The existing Woodpecker publisher already uses the matching checked-in release - document as the hosted Gitea release body. +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. -Narratio publishes source and tagged Linux amd64/arm64 and best-effort macOS -arm64 binaries with checksums. Successful publication of the intended tag to -`origin` remains the release command's responsibility boundary; asset publication -is asynchronous. The current dependency graph includes ConfigKit, AWS modules, -Go extension packages, YAML libraries, and test dependencies. This roadmap does -not claim that their individual terms or attribution coverage have been audited. +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. -ConfigKit is now selected at v0.4.1, whose patch contains licensing/documentation -changes only. Its project grant is LGPL-3.0-or-later and its LICENSE includes -both LGPLv3 and GPLv3. PromptKit v0.11.1 likewise updates licensing documentation -and selects MIT-licensed catalog releases, but is not in Narratio's Go module -graph. Its use by separately installed downstream applications does not make it -a Narratio dependency or justify adding it to this inventory by itself. +## Policy Target -## Targeted End State +| 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. | -The existing project grant remains unchanged. A tailored OSS policy governs -licensing documentation, and a canonical attribution inventory accurately -describes material incorporated into or distributed with Narratio. Applicable -standard texts are available locally; project-specific upstream notices and -source links identify the actual imported commits. +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. -README and future release documents navigate to these canonical materials. -Contributors can discover the policy from the development guide and maintain -attribution in the same change as the relevant dependency or distribution change. -There is no duplicate inventory, new licensing service, or additional release -approval system. +## Provenance and Orientation -## Required Changes +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: -### Adopt a Tailored OSS Policy +```text +https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/FILE.md +``` -Add `docs/policy/oss.md` using the agreed OSS conventions, retaining its base version -and recording the adoption date. Remove template instructions and adapt links -that point to template-only examples or reference collections. Do not introduce -placeholder documents merely to satisfy those links. +Substitute the correct filename for each policy. Preserve accurate provenance in +later edits; Git records suffice without a new adoption registry or sync service. -Identify Narratio's existing application license and connect the policy to the -canonical repository and release documentation for its Gitea host, distribution -channels, and publication mechanism. Preserve the author's license choice; -adoption is not relicensing. Leave COPYRIGHT and LICENSE substantively intact; -normalizing the final newline is optional formatting only. +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. -Retain the agreed House Format and settled interpretation of notice links: -project-specific license and attribution material is linked at its imported -commit rather than copied locally solely because its terms use reproduction, -inclusion, or copy language. This convention does not establish license -compatibility or discharge distinct obligations such as modified-file notices -or corresponding source. Preserve required notices in incorporated source. -Record concrete obligations or unresolved rights questions outside the format -with their reason and selected treatment; do not invent exceptions based on -common ownership or require repeated approval of the settled convention. +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. -### Establish Canonical Ownership and Contributor Routing +## Justified Local Customizations -Incorporate the agreed licensing ownership additions into -`docs/policy/documentation.md`, preserving Narratio-specific ownership -and existing unrelated decisions. Clearly assign: +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. -- Project identity, copyright, and grant to `COPYRIGHT`. -- Complete project license text to `LICENSE`. -- General licensing and attribution conventions to `docs/policy/oss.md`. -- Component-specific attribution to `docs/oss/attribution.md`. -- Verbatim standard dependency license texts to `docs/oss/licenses/`. -- Navigation to README and release notes; concrete release URL construction - and publication mechanics to `docs/release.md`. +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. -Record the selective policy update accurately; do not imply unrelated policy -changes have been adopted by merely changing version metadata. -Add a task-specific reading route in `docs/development.md` for licensing, -dependency, attribution, and release-document changes. Avoid repeating the OSS -rules in the agent, architecture, or testing policies. +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. -### Establish the Attribution Inventory +## Licensing, Attribution, and Local Materials -Review actual incorporated and distributed material, including relevant -transitive dependencies, Go runtime material in binaries, and copied code or -assets. Use the selected source revisions and actual use/distribution to decide -coverage, not just direct entries in `go.mod`. Neither every development tool -nor every separately installed subprocess application automatically belongs in -the inventory. Review any such component if Narratio actually incorporates or -distributes it. +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. -Create `docs/oss/attribution.md` with the agreed five-field format: project -name, faithful upstream copyright statements, applicable SPDX expression, -license/notice links, and a source repository link. Preserve multiple statements, -licensing alternatives, versions, and exceptions where applicable. Do not infer -ownership or invent identifiers; identify nonstandard terms through their texts. +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. -Resolve source and notice links to the exact imported commit, including for -copied material. Version tags and moving branches are not substitutes for those -component commit links. Inspect the selected source's license and notices rather -than assuming terms from a dependency name or current upstream main branch. +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. -Copy only the applicable complete, unmodified standard texts into -`docs/oss/licenses/`. Reuse a text across entries where appropriate, but preserve -distinct versions and exceptions. Make required companion texts directly -reachable from the affected entry; LGPLv3, if applicable, includes GPLv3. -Classify upstream files by content, not filename: a LICENSE file containing -project-specific notices may require both its upstream link and a local standard -text link. Keep explanatory prose outside the verbatim texts. +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. -### Add README and Release Navigation +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. -End README with two friendly statements linking to the existing GPL v3-or-later -grant in COPYRIGHT and the new attribution document. +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. -Update `docs/policy/release.md` to reference the OSS footer convention, and -`docs/release.md` to give the concrete Narratio Gitea URL construction. Each new -release document and its hosted download page must end with three links whose -visible text is `COPYRIGHT | LICENSE | ATTRIBUTION`. Use absolute URLs at that -release's immutable tag or corresponding immutable source revision. Unlike -upstream component links, these release-navigation links may use the release tag. +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. -Retain reuse of the checked-in release note by `.woodpecker/release.yml`; no new -publisher is expected. Prepare the footer alongside the note and verify its -intended paths against the candidate source. A future tag need not already -resolve remotely. Do not add publication-time network checks or CI polling. +## Coordinated Release Alignment -### Keep Ongoing Maintenance Proportionate +Update release policy, `docs/release.md`, relevant scripts, tests, and development +guidance together so rules and executable behavior agree: -Update affected entries, source/notice commit links, and texts in changes that -add, remove, upgrade, copy, or alter distribution of relevant components. Review -faithful license text copies, statements, and destinations through ordinary -change review and existing local documentation checks. +- 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. Resolve the exact set during implementation planning + against these criteria rather than leaving a blanket exemption or expansion. +- 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. -Apply the formatting convention prospectively. Do not retrofit published tags, -release notes, binaries, or checksums. Any actual historical omission discovered -during the inventory requires deliberate treatment under the applicable terms -and existing release correction policy, not silent rewriting of a 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. -## Scope Boundaries +## Boundaries and Completion Evidence -- No license change, automatic copyright-year advancement, or blanket per-file - header requirement. -- No mandatory scanner, full SBOM, recurring legal sign-off, new release approval - gate, or new network availability requirement. -- No automatic requirement for separate downloadable license assets, source - bundles, or a different binary packaging format. Concrete obligations found - during the inventory still require their applicable treatment. -- No changes to application behavior, dependency versions, platform support, - or successful-tag-push release completion. -- No wholesale replacement of Narratio-specific policy with generic templates. -- No adoption in this scope of broader release-process changes to - validation, repeated checks, fixed note sections, or release preparation. - Those changes warrant a separate deliberate review of policy, scripts, and - tests. The licensing additions must not silently enact them. +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. -## Completion Evidence +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. -The tailored policy and ownership/routing changes are present; the inventory -covers the material identified by the source/distribution review; entries have -faithful notices and exact source revisions; applicable local texts and companion -links are complete; README and release guidance provide the prescribed navigation; -and local documentation checks pass. Historical releases and existing publication -guards remain unchanged. Review must establish these facts rather than treating -the mere existence of new Markdown files as completion. +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 decisions remain open for this scope. Component-specific rights or -distribution questions discovered during the inventory must be surfaced with -evidence rather than guessed or expanded into blanket restrictions. +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.