diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md index 17ba663..fa00462 100644 --- a/docs/roadmap/policy.md +++ b/docs/roadmap/policy.md @@ -1,240 +1,250 @@ -# Licensing Policy Adoption +# Standard Policy Alignment -**Last updated:** 2026-09-26 +**Last updated:** 2026-09-28 -**Status:** Accepted direction; adoption work remains to be implemented. This -roadmap defines the target and scope, not a staged implementation plan. +**Status:** Accepted direction; implementation pending. This roadmap replaces +its earlier licensing-only scope and defines the desired end state, not a staged +implementation plan. Updating this roadmap does not adopt the policies below. -## Purpose +## Purpose and Review Revision -Establish self-contained licensing and attribution documentation for Audita, -using the House Format defined below. Keep licensing, documentation ownership, -and release guidance consistent while retaining Audita's existing policies. +Align Audita with [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy), +using identical policy language except where a substantive, locally significant +requirement or decision justifies a variation. Adopt upstream wording verbatim +for non-substantive differences. Perform the required template customizations +without inventing application contracts, restrictions, or guarantees. -Audita's selected grant is already GPL-3.0-or-later. This work documents that -choice and the applicable upstream attribution; it does not reconsider the -license, change application behavior, or replace the entire policy suite. +The accepted review compared Audita's current documents directly against upstream +commit **`d84a38ebab26f048cafbe59a2246700c35d29843`**, beginning with the +[adoption and update guide at that revision](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md). +Use that revision for this adoption. Historical adoption baselines need not be +reconstructed or assessed. A later upstream revision requires deliberate review, +not an automatic substitution during implementation. + +The public upstream repository, discovery links, and copied-policy attribution +are part of the accepted direction. This supersedes the earlier instruction to +omit references to the policy repository. ## Current Baseline -As of commit `982b595`: +- Audita has five adopted policies: agents 1.0, architecture 1.0, documentation + 1.1, testing 1.0, and release 1.0. None has per-document `Upstream Source` + metadata. `meta.md` and `oss.md` are absent. +- [AGENTS.md](../../AGENTS.md) routes readers to the contributor guide and agent + policy. [docs/development.md](../development.md) has component-specific reading + guidance, but lacks the upstream selective Policy Reading Guide and currently + directs all tasks to the architecture policy. +- [COPYRIGHT](../../COPYRIGHT) and [LICENSE](../../LICENSE) already establish + Audita's GPL-3.0-or-later application grant and full GPLv3 text. The grant does + not yet identify the scope of separately licensed copied policy documents. +- There is no canonical `docs/oss/attribution.md` or local dependency license-text + collection. Relevant component notices still require an evidence-based inventory. +- The [README](../../README.md) lacks the prescribed final licensing statements. + The [release procedure](../release.md) lacks licensing-footer instructions, and + the [release workflow](../../.woodpecker/release.yml) does not explicitly reuse + checked-in release notes as hosted release bodies. +- Audita already releases through one publication command with an atomic source + and tag push. Linux amd64 and arm64 are required; macOS arm64 is best-effort + development support. Successful publication completes the release without + waiting for CI or artifact delivery. -- [COPYRIGHT](../../COPYRIGHT) contains the project identity, copyright, - GPL-3.0-or-later SPDX expression and grant, warranty disclaimer, and third-party - statement. [LICENSE](../../LICENSE) contains the full GPLv3 text. These already - follow the selected project licensing convention and need no substantive revision. -- There is no `docs/policy/oss.md`, canonical `docs/oss/attribution.md`, or local - dependency license-text collection. -- The [documentation policy](../policy/documentation.md) lacks ownership and - boundary rules for licensing documents. The [contributor guide](../development.md) - lacks a licensing and attribution reading path. -- The [README](../../README.md) does not end with the prescribed project-license - and attribution statements. -- The [release policy](../policy/release.md) and [release procedure](../release.md) - do not specify the licensing footer. The tag-triggered - [release workflow](../../.woodpecker/release.yml) publishes Linux binaries and - checksums, but does not explicitly use the checked-in release note as its - hosted release body. -- Dependencies include ConfigKit, PromptKit and its backend packages, YAML and - JSON Schema libraries, and other transitive modules. A complete inventory of - relevant components, exact source revisions, and applicable notices has not yet - been established; `go.mod` alone is not that inventory. +## Targeted Policy Set and Justified Customizations -Audita publishes source and releases through its Gitea repository. Linux amd64 -and arm64 are the supported production targets; macOS arm64 remains best-effort -for local development. Successful release completion remains the successful -push of the release source and tag, without waiting for CI asset publication. +All seven policy files belong under `docs/policy/`. The versions below are those +at the selected upstream revision. No existing policy is wholly unchanged; +existing architectural decisions and platform commitments need no substantive +revision merely to align the text. -## Reviewed Dependency Updates +| Policy | Target version | Required alignment and justified local treatment | +| --- | --- | --- | +| `agents.md` | 1.3 | Adopt upstream substantive language verbatim. Retain Audita's graph-first Codebase Discovery section because it is an explicitly selected repository workflow. | +| `architecture.md` | 1.3 | Adopt general ownership, boundary, and constraint guidance, then perform the template's required application-specific customization. Preserve Audita's ordered pipeline, ConfigKit/PromptKit responsibilities, deterministic processing, recovery, concurrency, and secret-handling decisions. These describe real project requirements rather than stylistic preferences. | +| `documentation.md` | 1.11 | Adopt upstream prose and applicable ownership rows. Retain concrete output-contract ownership, contributor change recipes, and the decision to place operating/recovery guidance in operations instead of restoring troubleshooting documentation. Omit HTTP API and public Go API ownership rows because Audita has neither responsibility. | +| `testing.md` | 1.3 | Adopt substantive text verbatim. Its distinction between established contracts and invented test requirements needs no local exception. | +| `release.md` | 1.4 | Adopt upstream substantive language. Preserve Linux amd64/arm64 requirements, best-effort macOS arm64, unsupported Windows/macOS amd64, and Audita's explicit decision against human release gates. These are selected support and workflow commitments. | +| `meta.md` | 1.0 | Adopt provenance, local authority, and public discovery guidance with accurate metadata and local attribution navigation. No additional substantive exception is needed. | +| `oss.md` | 1.8 | Adopt the House Format and maintenance rules, with required project-specific facts and reference links. Preserve Audita's GPL-3.0-or-later application grant, Gitea host, and existing distribution channels. | -ConfigKit v0.4.1 and PromptKit v0.11.1 are now selected. Both make their -LGPL-3.0-or-later grant explicit in `COPYRIGHT` and provide the LGPLv3 and -incorporated GPLv3 texts together in `LICENSE`. Neither changes library code. -PromptKit also selects MIT-licensed OpenRouter and Rakestrawhome catalogs at -v2.20260926.0; those catalog updates leave Go code and profile data unchanged. +Remove each `Base Policy Template` section after carrying out its instructions. +Keep local customizations identifiable and explain their project-specific reason +in the appropriate policy; do not maintain alternate paraphrases of shared rules. +Architecture customization does not authorize a package redesign or additional +threat-model guarantees. Supporting documents are warranted by existing +responsibilities and substantive content, not by unused template examples. -Use the selected public source revisions as the starting points for their -attribution entries: +Successful-tag-push completion, asynchronous artifacts, minimal automated gates, +and proportionate validation are now shared upstream rules. Replace Audita's +parallel explanations with the upstream language rather than describing these +as continuing exceptions. Keep concrete commands, remotes, build targets, and +publication mechanics in the release procedure with appropriate policy links. -- ConfigKit v0.4.1: `0adb94f59e44827908eff401d4381a398fe17107`. -- PromptKit v0.11.1: `15e40679546f2e21b6f51cc84b6f0a087a8486db`. -- OpenRouter catalog v2.20260926.0: `4f731d217e0bc39151c010f50fb5912706e7b6b3`. -- Rakestrawhome catalog v2.20260926.0: `48918a3ad39fd99843cda94a86133b1b3881d596`. +## Provenance and Selective Reading -Inspect the selected components directly. Dependency attribution documents can -help locate relevant notices, but should not be copied wholesale: Audita's -inventory reflects material actually incorporated into or distributed with Audita. +For every adopted policy, retain the selected upstream `Base Policy Version`, +set `Last Updated` to its actual local adoption date, and introduce `Upstream +Source` linking to that exact file at the selected full commit. The URL pattern is: -## Targeted End State - -### Canonical Policy and Ownership - -Create `docs/policy/oss.md` for Audita's selected grant and distribution, using -the requirements in this roadmap. Make it self-contained, with references to -Audita's canonical documents and public component sources. Record its adoption -date and appropriate policy version metadata. - -The policy establishes the House Format, maintenance responsibilities, -and treatment of concrete exceptions. It identifies the settled project grant -and routes readers to the canonical documents for source hosting and release -publication mechanics. It does not infer separate licenses for Audita packages. - -Add the following licensing ownership and boundary guidance to the local -documentation policy: - -| Document | Owned content | -| --- | --- | -| `docs/policy/oss.md` | Licensing conventions, attribution format, maintenance, and concrete exceptions. | -| `COPYRIGHT` | Project identity, copyright statements, SPDX expression, grant, disclaimer, and third-party statement. | -| `LICENSE` | Complete, unmodified project license text. | -| `docs/oss/attribution.md` | Relevant component attribution entries. | -| `docs/oss/licenses/` | Complete, verbatim applicable standard license and companion texts. | -| `docs/release.md` | Concrete immutable release-link URLs and publication mechanics. | - -The contributor guide directs licensing, dependency, copied-code or asset, -attribution, and release-document changes to the appropriate policy and owner. -Preserve existing documentation ownership, agent commit and discovery rules, -and Audita's retirement of standalone troubleshooting documentation. Keep -policy version metadata accurate; unrelated policy changes are outside this -adoption scope. - -### Relevant Attribution and License Texts - -Create a canonical inventory covering upstream components incorporated into or -distributed with Audita: relevant direct and transitive dependencies, copied code -or assets, and applicable Go runtime notices. Determine inclusion from actual use -and distribution, not merely presence in `go.mod` or classification as direct or -indirect. Do not automatically include every development tool or test-only module. - -Each component entry uses the five-field House Format: - -1. Project name. -2. Upstream copyright statements, preserving their wording. -3. Applicable SPDX identifier or expression, when one exists. -4. Links to applicable local standard texts and upstream project-specific notices. -5. A source repository link identifying the exact imported commit. - -Resolve component versions to their actual source commits. Upstream source and -notice links use those commits, not version tags or moving branches. Preserve -multiple copyright statements, licensing alternatives, and exceptions; record a -selected licensing option when relevant without inventing an SPDX identifier. - -Copy only applicable standard license texts and required companion texts into -`docs/oss/licenses/`. Preserve complete wording and use recognizable filenames; -multiple entries can share a text. Make companions directly reachable from each -relevant entry, including GPLv3 where an LGPLv3 entry requires it. Inspect upstream -file contents rather than assuming a file named `LICENSE` contains only standard -wording. - -Apply the selected house interpretation accepting direct, commit-specific links -for project-specific license and attribution notice reproduction. Do not add a -blanket local-copy requirement or repeated approval solely because upstream terms -use reproduction, inclusion, or copy language. Preserve required notices already -present in incorporated source. Concrete obligations beyond notice reproduction, -such as source supply or modified-file marking, receive their own applicable -treatment and are recorded in the policy or affected entry when needed. - -This inventory and format do not themselves certify license compatibility or -resolve every possible distribution obligation. Resolve concrete uncovered -issues before the affected use or distribution; do not reopen settled choices -without such an issue. - -### Discoverability and Release Publication - -End the README with these two statements: - -```markdown -Audita 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/.md ``` -Add the following licensing navigation requirements to Audita's release policy. -Each new checked-in release note and its hosted download page ends with links visibly labeled `COPYRIGHT | LICENSE | ATTRIBUTION`. -Use absolute Gitea URLs to the three canonical files at the release's immutable -tag or corresponding immutable source commit. This differs from dependency -attribution links, which identify the exact imported upstream commit. +Substitute each of `agents`, `architecture`, `documentation`, `testing`, `release`, +`meta`, and `oss`; a repository-root or shared generic source link is insufficient. +These links describe the source actually incorporated, not a reconstructed claim +about older local documents. Git and per-document metadata are sufficient; no +separate synchronization registry or recurring check is required. -The release procedure owns the concrete URL pattern and how publication delivers -that footer. Reuse the checked-in release note as the hosted release body through -the release workflow where supported, avoiding separately maintained notice -lists or release prose. Verify the publication plugin's supported configuration -when implementing that integration; if it cannot consume the note directly, use -the smallest supported publication mechanism that preserves the same content. +In `meta.md`, retain these public discovery destinations: -Validate future-tag paths against the candidate checkout during ordinary release -preparation. A future tag need not already resolve remotely. Keep release success -at source/tag push and treat asynchronous publication failures under the existing -release correction procedure. +- [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy). +- [Current adoption and update guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md). -### Ongoing Maintenance and Published History +Discovery links follow the current upstream project and guide. Adopted-source, +notice, and example links remain commit-pinned. Preserve valid pinned example +references supplied by the selected policy, or pin them to this review revision +after checking the referenced assets; do not turn them into moving-branch links. -Update affected attribution, source commits, and license texts alongside changes -that add, remove, upgrade, copy, or change distribution of relevant components. -Check the selected upstream source instead of assuming notices are unchanged. -Git retains previous attribution versions. +Adapt upstream `agents/AGENTS.md` into Audita's root orientation, retaining its +existing applicable instructions. Add the adoption guide's Policy Reading Guide +to `docs/development.md` and retain the component-specific task guide. Route +policy adoption and updates to `meta.md`, repository recommendations and changes +to agents, application-code or structure work to architecture, validation choices +to testing, documentation work to documentation, dependency/licensing work to +OSS, and release/versioning work to release policy. Read applicable policies +before their decisions, reuse unchanged context, and expand reading with scope. +Do not require reading the entire suite for every task. -Apply the new presentation convention prospectively. Do not retrofit v2.0.0 or -older published tags, notes, binaries, or checksums. Current licensing statements -do not change the grant recorded in an older tagged source tree. Any concrete -historical omission discovered during inventory should receive deliberate -handling under its applicable terms and Audita's release correction policy. +## Copied Policy Licensing and Local Material -## Work Required +Follow the selected revision's +[canonical policy attribution entry](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/policy-attribution.md) +and [project grant](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT). +Insert the entry beneath the title in `docs/oss/attribution.md`, substitute the +full review commit in all three URLs, and accurately identify copied/adapted +material, including orientation or reading-guide text where copied. Preserve +supplied creator, copyright, license, disclaimer notices, and modification +indications. Keep the material statement concise. -- Adopt and tailor the OSS policy; merge related documentation ownership and - release guidance while retaining Audita-specific decisions. -- Inspect actual incorporated and distributed components, establish their source - revisions and notices, and create attribution entries and applicable texts. -- Add contributor navigation and the README statements once their destinations - exist. -- Extend the release procedure with the immutable footer convention and connect - hosted release content to the checked-in note through the publication workflow. -- Review affected links, standard-text fidelity, attribution evidence, policy - references, and consistency with the existing release process. Validate the - publication configuration at its affected boundary without creating a release - solely to test this documentation change. +Copy `CC-BY-SA-4.0.txt` into `docs/oss/licenses/`. Add the adoption guide's scoped +notice to `COPYRIGHT`, identifying the adapted policies as CC-BY-SA-4.0 and +routing readers to attribution for the affected material. Account accurately for +other copied guidance in that scope. Audita's application code remains +GPL-3.0-or-later; unrelated documentation is not automatically relicensed. +The root GPLv3 `LICENSE` needs no change. -These are work areas, not an implementation sequence. Policy and attribution -content form one coherent area; release publication integration is another. -Detailed implementation steps can be planned separately. +| Material | Destination or treatment | +| --- | --- | +| Applicable policies, including `meta.md` and `oss.md` | Copy and customize under `docs/policy/`, retaining provenance. | +| Upstream `agents/AGENTS.md` | Adapt into root `AGENTS.md`. | +| Selective reading guidance | Integrate into Audita's own `docs/development.md`. | +| Upstream README, root AGENTS.md, developer guide, and adoption guide | Keep upstream and consult through links; do not copy as local guides. | +| Licensing example collection | Keep upstream with commit-pinned references; use it to create actual notices. Original example formatting is CC0 and alone needs no policy attribution entry. | +| Applicable standard and companion license texts | Copy complete, unmodified texts locally; no blanket collection. | -## Acceptance Criteria +## Component Attribution -- Audita has an adopted OSS policy with working repository references, accurate - version metadata, and self-contained repository-specific guidance. -- Documentation ownership and contributor navigation identify the canonical - licensing documents without duplicating their substantive content. -- Relevant incorporated and distributed components have evidence-based House - Format entries, exact imported-commit links, and applicable standard and - companion texts. Concrete uncovered obligations have a recorded treatment. -- The existing project grant and full license text remain consistent; no - relicensing or unsupported claims of ownership are introduced. -- The README ends with the license and attribution statements. -- Future release preparation produces the immutable licensing footer in both the - checked-in note and hosted body, with one maintained source for that content. -- Affected local links, intended future-tag paths, text copies, and publication - configuration are checked with validation proportionate to the change. -- Published history and Audita's existing platform scope and release-success - definition remain intact. +Complete the previously agreed inventory of relevant incorporated or distributed +components: direct and transitive dependencies, copied code/documentation/assets, +and applicable Go runtime notices. Determine inclusion from actual material and +use, not simply presence in `go.mod`; tooling or consultation alone does not +require an entry. Inspect selected sources directly rather than copying a +dependency's attribution document wholesale. -## Scope Boundaries +Use the exact House Format in OSS policy 1.8: the prescribed title followed by +component entries, factual identification, applicable supplied copyrights and +SPDX expressions, standard license/notice labels, and `[Source](COMMIT_URL).` +links. Omit unavailable optional fields instead of adding explanatory filler. +Preserve required upstream material, license alternatives, and exceptions. +Keep research narratives, compliance conclusions, and exception reasoning out +of attribution; place reasoning in the OSS policy or an appropriate decision +record. This replaces the older roadmap's permission to put exception reasoning +in a component entry. -This work introduces no mandatory scanner, full software bill of materials, -recurring legal sign-off, additional human approval, publication-time network -check, or CI wait. Ordinary attribution maintenance and release-document review -are preparation work, not new release gates. +Upstream component and notice links identify exact imported commits. Local +standard texts include directly reachable companions, such as GPLv3 for LGPLv3. +Apply the adopted house interpretation of notice links without blanket extra +local-copy requirements or repeated approval. Concrete obligations beyond notice +reproduction receive their own applicable treatment; the format alone does not +certify compatibility or resolve every distribution obligation. -The formatting convention alone does not require separate downloadable license -assets, source bundles, or a different binary package format. A concrete component -obligation may need specific treatment, but is not a basis for inventing blanket -requirements. No application code, dependency upgrade, prompt change, or general -policy-suite rewrite is part of this feature. +The reviewed dependency revisions remain useful starting evidence, subject to +checking the dependencies selected when implementation occurs: -## Open Questions +| Component | Reviewed version | Source commit | +| --- | --- | --- | +| ConfigKit | v0.4.1 | `0adb94f59e44827908eff401d4381a398fe17107` | +| PromptKit | v0.11.1 | `15e40679546f2e21b6f51cc84b6f0a087a8486db` | +| OpenRouter catalog | v2.20260926.0 | `4f731d217e0bc39151c010f50fb5912706e7b6b3` | +| Rakestrawhome catalog | v2.20260926.0 | `48918a3ad39fd99843cda94a86133b1b3881d596` | -No product or policy decisions remain open for this scope. Component-specific -source revisions and notices, and the publication plugin's supported release-body -mechanism, require verification during implementation. These are factual follow-up -work, not additional approval gates; raise a decision only if that verification -reveals a concrete unresolved obligation or a material publication tradeoff. +These library patches changed licensing/documentation rather than library code +or catalog profiles. ConfigKit and PromptKit identify LGPL-3.0-or-later; the +selected catalogs identify MIT. Other relevant dependencies still need inventory. + +## Discoverability and Release Integration + +End README with the project-license and attribution statements prescribed by the +OSS policy, using Audita's actual grant. `COPYRIGHT` owns the separately licensed +policy scope; README links to that grant and the attribution document. + +Update `docs/release.md` to specify the final `COPYRIGHT | LICENSE | ATTRIBUTION` +links in every new release note and hosted download page. Use absolute Gitea URLs +at the release's immutable tag or source commit. Reuse the checked-in note as the +hosted body where supported; verify the publication plugin's supported mechanism +and make the necessary focused `.woodpecker/release.yml` change. Avoid separately +maintained release prose or notice lists. + +Preserve the current atomic source/tag publication approach, supported targets, +and completion point. Align procedure wording with upstream's preparation, +ambiguous-push recovery, and asynchronous retry rules. Handle completed-roadmap +retirement during preparation, preserving planned/deferred work and repairing +links; this roadmap update does not authorize deleting other roadmaps now. + +Check intended future-tag paths against the candidate source without requiring +the tag to resolve before publication. Apply the formatting convention +prospectively; leave published tags, notes, artifacts, and checksums intact. +Concrete historical omissions, if discovered, receive deliberate treatment under +their applicable terms and release correction rules. + +## Work Required and Acceptance Criteria + +Implementation covers the seven policy documents, `AGENTS.md`, +`docs/development.md`, `COPYRIGHT`, `docs/oss/attribution.md`, applicable files in +`docs/oss/licenses/`, README, the release procedure, and focused hosted-body +publication wiring. Update this roadmap's implementation status when appropriate. +A separate staged implementation plan can define the editing sequence. + +The work is complete when: + +- Shared policy language matches the selected upstream revision after required + template removal and customization; retained variations have substantive + Audita-specific reasons as identified above. +- All seven policies have accurate versions, adoption dates, and file-specific + commit-pinned source links. Public discovery links and selective orientation + are in place, with no leftover template-only instructions or broken links. +- Copied policy/guidance scope, modification status, credit, CC-BY-SA text, and + root grant notice follow the documented upstream arrangement while preserving + Audita's application license. +- Relevant components have verified House Format entries, exact source/notice + commits, and complete applicable license texts, without editorial commentary. +- README and future release documentation provide the required navigation, and + hosted release content comes from the checked-in note through a verified + publication mechanism. +- Audita's application contracts, architectural decisions, platform commitments, + release completion semantics, and published history are preserved. +- Affected text, links, license copies, metadata, and publication configuration + pass proportionate review and validation. No release is needed solely to test + adoption; behavioral workflow changes receive focused validation if required. + +## Scope Boundaries and Open Questions + +No policy decisions remain open for the agreed scope. Component-specific notices +and the publication plugin's supported release-body mechanism require factual +verification during implementation. Raise a decision only for a concrete +unresolved obligation or material tradeoff uncovered by that work. + +This feature does not require application refactoring, dependency upgrades, +mandatory scanners, a full SBOM, recurring legal approvals, synchronization +checks, additional human release gates, publication-time network checks, or CI +waiting. The documentation convention alone does not require downloadable +license assets, source bundles, or a different binary package format.