audita/docs/roadmap/policy.md

Standard Policy Alignment

Last updated: 2026-09-28

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 and Review Revision

Align Audita with Standard Repository Policies, 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.

The accepted review compared Audita's current documents directly against upstream commit d84a38ebab26f048cafbe59a2246700c35d29843, beginning with the adoption and update guide at that revision. 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

• 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 routes readers to the contributor guide and agent policy. docs/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 and 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 lacks the prescribed final licensing statements. The release procedure lacks licensing-footer instructions, and the release workflow 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.

Targeted Policy Set and Justified Customizations

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.

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.

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.

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.

Provenance and Selective Reading

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:

https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/<filename>.md

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.

In meta.md, retain these public discovery destinations:

• Standard Repository Policies.
• Current adoption and update guide.

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.

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.

Copied Policy Licensing and Local Material

Follow the selected revision's canonical policy attribution entry and project grant. 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.

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.

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.

Component Attribution

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.

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.

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 reviewed dependency revisions remain useful starting evidence, subject to checking the dependencies selected when implementation occurs:

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

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.