eric/audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Expand the roadmap for standard policy alignment

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 00:54:17 +00:00
parent 5150b5c636
commit 91d9be68a7
1 changed files with 217 additions and 207 deletions
Download Patch File Download Diff File Expand all files Collapse all files

424
docs/roadmap/policy.md
View File

@@ -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/<filename>.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.