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

Adopt remaining policies and selective reading guide

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 01:07:03 +00:00
parent 9723102117
commit edbbf3d5ea
10 changed files with 491 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
AGENTS.md
View File

@@ -1,4 +1,6 @@
Please review `docs/development.md` for initial orientation in this repository Start with `docs/development.md` for orientation and use its policy reading guide
and follow its task-specific reading guide. to select the policies applicable to the task. Do not read the entire suite by
default.
Review and follow `docs/policy/agents.md` before recommending, planning, or implementing any changes to this repository. Read and follow `docs/policy/agents.md` before recommending, planning, or
implementing repository changes.

6
COPYRIGHT
View File

@@ -18,6 +18,6 @@ GNU General Public License for more details.
Third-party code and assets are subject to their respective license terms. Third-party code and assets are subject to their respective license terms.
Policy documents adapted from Standard Repository Policies remain licensed Policy documents and guidance adapted from Standard Repository Policies
under CC-BY-SA-4.0. See docs/oss/attribution.md for the affected material, remain licensed under CC-BY-SA-4.0. See docs/oss/attribution.md for the
upstream credit, and license links. affected material, upstream credit, and license links.

27
docs/development.md
View File

@@ -7,9 +7,8 @@ Audita is a Go CLI for transcript polishing. Start with the
## Before Changing the Repository ## Before Changing the Repository
Coding agents must read and follow the [agent policy](policy/agents.md) before Coding agents must read and follow the [agent policy](policy/agents.md) before
recommending, planning, or implementing changes. Read the recommending, planning, or implementing changes. Use the policy reading guide
[architecture policy](policy/architecture.md) for boundaries and invariants, below to select the policies applicable to the task.
then use the task guide below rather than reading every reference indiscriminately.
Confirm the requested scope and behavior contract, make focused changes in the Confirm the requested scope and behavior contract, make focused changes in the
owning component, and update the relevant tests and canonical documentation owning component, and update the relevant tests and canonical documentation
@@ -18,6 +17,28 @@ sufficiency; the [documentation policy](policy/documentation.md) governs content
ownership. Commit discipline and agent Git restrictions are in the ownership. Commit discipline and agent Git restrictions are in the
[agent policy](policy/agents.md#git-commit-policy). [agent policy](policy/agents.md#git-commit-policy).
## Policy Reading Guide
| Policy | Read before… |
| --- | --- |
| [Policy set provenance](policy/meta.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
| [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. |
| [Architecture](policy/architecture.md) | Planning or changing application code or its structure. |
| [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. |
| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
| [Release](policy/release.md) | Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions. |
- Read applicable policies before making decisions they govern; multiple policies
may apply.
- Select policies using the task triggers above. Follow cross-references to
relevant sections when needed to resolve a concrete question.
- Reuse policies already available in context; reread when changed or no longer
available.
- Expand reading when the task's scope expands.
- When revising a policy itself, read that policy and any provisions elsewhere
affected by the revision.
## Baseline Validation ## Baseline Validation
Use Go 1.25.5 or newer. From the repository root: Use Go 1.25.5 or newer. From the repository root:

2
docs/oss/attribution.md
View File

@@ -2,7 +2,7 @@
## Standard Repository Policies ## Standard Repository Policies
Material: `docs/policy/meta.md`, `docs/policy/agents.md`, and `docs/policy/testing.md`, adapted for this repository. Material: All documents under `docs/policy/`, root `AGENTS.md`, and the Policy Reading Guide in `docs/development.md`, adapted for this repository.
Copyright (C) 2026 Eric Rakestraw Copyright (C) 2026 Eric Rakestraw

40
docs/policy/architecture.md
View File

@@ -1,10 +1,42 @@
# Architecture Policy # Architecture Policy
**Base Policy Version:** 1.0 **Base Policy Version:** 1.3
**Last Updated**: 2026-09-24 **Last Updated**: 2026-09-28
**Upstream Source:** [Standard Repository Policies architecture](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md)
## Purpose and System Shape ## Purpose And Ownership
The adopted policy defines the application's purpose and the architectural
constraints contributors must follow. It owns system boundaries, responsibility
and dependency rules, established invariants, and explicit non-goals.
Describe the concrete package inventory and implementation mechanics in internal
documentation. Link to canonical public contracts for their exact behavior and
to ADRs for decision rationale.
## Architectural Approach
Hexagonal architecture is strongly recommended, including encapsulating external
integrations and APIs within internal adapters. Keep domain and application
logic independent of external integration details, and make dependency direction
clear in the adopted policy.
Implement that separation with proportionate, idiomatic code. Choose interfaces
and package layout to serve the application's actual boundaries. Use adapters
for collaborators with external integration responsibilities.
## Adopted Constraints And Implemented Structure
Architectural constraints govern current and future development. Record
implemented structure accurately, proposals and implementation status in the
roadmap, and significant decisions and rationale in ADRs. Describe a target
structure as implemented when its changes land.
Constraints must reflect deliberately selected requirements and decisions.
Do not promote incidental implementation choices into architectural invariants.
## Application-Specific Topics
Audita is a single-process Go CLI for transcript polishing. Its architecture Audita is a single-process Go CLI for transcript polishing. Its architecture
separates deterministic transcript processing from external LLM effects through separates deterministic transcript processing from external LLM effects through
@@ -74,7 +106,7 @@ future changes should treat those current contracts deliberately. Current implem
limits are documented in the [internal overview](../internal/overview.md#current-scope); limits are documented in the [internal overview](../internal/overview.md#current-scope);
they are not additional prohibitions on future development. they are not additional prohibitions on future development.
## Errors and Secret Handling ## Trust Boundaries And Threat Scope
Errors should identify the failed processing phase sufficiently for users and Errors should identify the failed processing phase sufficiently for users and
subprocess callers. Preserve the stream and exit behavior defined by the subprocess callers. Preserve the stream and exit behavior defined by the

96
docs/policy/documentation.md
View File

@@ -1,8 +1,9 @@
# Documentation Policy # Documentation Policy
**Base Policy Version:** 1.1 **Base Policy Version:** 1.11
**Last Updated**: 2026-09-23 **Last Updated**: 2026-09-28
**Upstream Source:** [Standard Repository Policies documentation](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md)
## Purpose ## Purpose
@@ -16,7 +17,7 @@ to drift for users, operators, developers, integrators, and LLM coding agents.
Each authoritative fact belongs in one document. A non-owning document may give Each authoritative fact belongs in one document. A non-owning document may give
a short, stable summary for orientation, but it must link to the canonical owner a short, stable summary for orientation, but it must link to the canonical owner
instead of repeating volatile details. for volatile details.
Volatile details include commands, flags, configuration fields and defaults, Volatile details include commands, flags, configuration fields and defaults,
module keys, schemas, file names, paths, status codes, retry behavior, and module keys, schemas, file names, paths, status codes, retry behavior, and
@@ -28,24 +29,26 @@ contract, maintain it only in the owning document.
Outside `docs/roadmap/`, documentation describes implemented behavior only. Outside `docs/roadmap/`, documentation describes implemented behavior only.
Partial features may be described only to their implemented boundary. Partial features may be described only to their implemented boundary.
ADRs are the narrow exception: an ADR may record an accepted architectural Architectural constraints may govern future changes. Describe current structure
decision before implementation, but acceptance must not be presented as proof from implemented behavior.
that the behavior exists. The roadmap owns implementation status and sequencing
until the decision is implemented. Current architecture, user, operator, ADRs may record an accepted architectural decision before implementation. The
integration, and internal documentation are updated when the behavior lands. roadmap owns implementation status and sequencing until the decision is
implemented. Current architecture, user, operator, integration, and internal
documentation are updated when the behavior lands.
### Audience And Detail ### Audience And Detail
Write for the document's stated audience and include only the detail needed for Write for the document's stated audience and include only the detail needed for
its owned topic. User and operator docs should not expose implementation detail. its owned topic. Keep user and operator docs focused on using and operating the
Developer docs should link to user-facing and external contracts rather than application. Developer docs should link to user-facing and external contracts
restate them. for their definitions.
### Examples ### Examples
Complete copyable files belong in `examples/`. Documentation may use the Complete copyable files belong in `examples/`. Documentation may use the
smallest illustrative snippet needed to explain its owned topic, but should link smallest illustrative snippet needed to explain its owned topic, but should link
to maintained examples instead of embedding a second complete copy. to maintained examples for complete copyable files.
Examples must be valid, secret-free, and tested where practical. Commands and Examples must be valid, secret-free, and tested where practical. Commands and
configuration used in documentation should match the application. configuration used in documentation should match the application.
@@ -61,40 +64,43 @@ secret values.
| Topic | Canonical owner | Owned content | Content owned elsewhere | | Topic | Canonical owner | Owned content | Content owned elsewhere |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| Product orientation and minimal end-to-end quickstart | `README.md` | What this application is, why it is useful, one shortest successful invocation, and links onward. | Complete command reference, configuration reference, operational procedures, implementation detail. | | Product orientation and minimal end-to-end quickstart | `README.md` | Purpose, value, shortest successful invocation, and navigation, including licensing and attribution. | Complete command reference, configuration reference, operational procedures, implementation detail. |
| Contributor entry point | `docs/development.md` | Task-oriented reading guide, minimal contributor orientation, baseline validation commands, and links to canonical docs. | Package inventory, architecture rules, subsystem behavior, detailed change recipes. | | Contributor entry point | `docs/development.md` | Task-oriented reading guide, contributor orientation, baseline validation commands, and canonical links. | Package inventory, architecture rules, subsystem behavior, detailed change recipes. |
| Application architecture policy | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, architectural boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. | | Application architecture policy | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. |
| Agent policy | `docs/policy/agents.md` | Implementation discipline for coding agents, including proportionality, idiomatic simplicity, code discovery, Git commit restrictions, and rules against inventing requirements, restrictions, guarantees, or repository policy. | Application contracts, architecture, testing policy, and contributor procedures. | | Policy-set provenance and upstream navigation | `docs/policy/meta.md` | Policy-set origin, local authority, adoption baselines, and upstream adoption and update links. | Task-specific reading triggers, detailed adoption procedures, and formal attribution notices. |
| Agent policy | `docs/policy/agents.md` | Proportionate, idiomatic implementation; graph-first code discovery, commit discipline, and rules against inventing requirements, restrictions, guarantees, or policy. | Application contracts, architecture, testing policy, and contributor procedures. |
| Documentation policy | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. | | Documentation policy | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. |
| Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression-test policy, and criteria for adding, rewriting, or deleting tests. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. | | Testing policy | `docs/policy/testing.md` | Test philosophy, risk sufficiency, boundaries, doubles, coverage, regressions, and test maintenance. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. |
| Release policy | `docs/policy/release.md` | Versioning and compatibility rules, release integrity and immutability requirements, release-documentation policy, required gates, publication controls, verification requirements, and exception policy. | Repository-specific commands, product installation guidance, CLI version semantics, historical release summaries, and CI implementation detail. | | Release policy | `docs/policy/release.md` | Versioning, compatibility, release integrity and immutability, release documentation, proportionate gates, publication controls, completion, and required versus optional checks. | Repository-specific commands, product installation guidance, CLI version semantics, historical release summaries, and CI implementation detail. |
| Repository-specific release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, concrete validation and publication commands, repository and registry guards, deliverable publication, consumer-facing verification, and failure recovery. | General release requirements, product installation guidance, historical release summaries, and current compatibility contracts. | | Open source licensing and attribution policy | `docs/policy/oss.md` | License defaults and author choices, COPYRIGHT and attribution formats, license/notice links, discoverability, maintenance, and concrete exceptions. | Component entries, license texts, release commands, and dependency security review. |
| CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. | | Project copyright and license grant | `COPYRIGHT` | Project identity, copyright holders and years, SPDX expression, grant, warranty disclaimer, and third-party statement. | Complete license texts and upstream component attribution. |
| Configuration contract | `docs/config.md` | Discovery and precedence, file schema, fields, defaults, environment overrides, validation rules, and user-selectable module or validator keys. | Complete example files, CLI syntax, runtime state lifecycle, module implementation details. | | Project license texts | `LICENSE` | Complete project and incorporated companion license texts, with required project-specific fields. | General licensing policy and upstream component attribution. |
| Operations | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache, and debug handling, cleanup, permissions, recovery, and operational limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. | | Upstream component attribution | `docs/oss/attribution.md` | House Format component entries: identity, material scope and modifications where applicable, copyright, license, required notices, and license, notice, and source links. | General attribution policy, exception reasoning, research narratives, compliance commentary, and complete standard license texts. |
| Integration contracts for external components | `docs/integrations/`, including `docs/integrations/output-files.md` for serialized outputs | External file formats and protocols, upstream and downstream contracts, logical output bundle paths and schemas, media types, and compatibility behavior. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. | | Standard dependency license texts | `docs/oss/licenses/` | Complete, verbatim standard license texts shared by applicable entries. | Project-specific upstream notices, attribution prose, and policy interpretation. |
| Inventory of implemented internal packages | `docs/internal/overview.md` | Current packages and components, their implemented responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. | | Repository-specific release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, validation and publication commands and automated guards, asynchronous deliverables, delivery status, optional consumer verification, and recovery. | General release requirements, product installation guidance, historical release summaries, and current compatibility contracts. |
| Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. | | CLI contract (if applicable) | `docs/cli.md` | Commands, arguments, flags, invocation semantics, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. |
| Configuration contract (if applicable) | `docs/config.md` | Discovery, precedence, schema, fields, defaults, environment overrides, validation, and selectable module and validator keys. | Complete example files, CLI syntax, runtime state lifecycle, module implementation details. |
| Operations (if applicable) | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache and debug handling, resume, cleanup, permissions, recovery, and limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. |
| Integration contracts for external components (if applicable) | `docs/integrations/`, including `docs/integrations/output-files.md` for serialized outputs | External formats and protocols, upstream and downstream contracts, logical output paths and schemas, media types, and compatibility. | Physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. |
| Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
| Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
| Contributor change recipes | Relevant files under `docs/internal/`, including `docs/internal/cli-config.md`, `docs/internal/modules.md`, and `docs/internal/validators.md` | Concrete editing and validation steps for each component. | Contributor orientation, global policy, and definitions of external contracts. | | Contributor change recipes | Relevant files under `docs/internal/`, including `docs/internal/cli-config.md`, `docs/internal/modules.md`, and `docs/internal/validators.md` | Concrete editing and validation steps for each component. | Contributor orientation, global policy, and definitions of external contracts. |
| Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. | | Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. |
| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status; sequencing; and task breakdowns. | Implemented behavior reference and architectural decision rationale. | | Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
| Release-note history | `docs/releases/` | One checked-in historical summary for each source release made under the procedure. The note at the immutable tag is that release's record. | Current commands, behavior, contracts, and compatibility definitions. | | Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. |
| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other files intended to be copied or run. | Field-by-field reference, command reference, prose explanation. | | Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. |
Documents that do not exist are required only when the corresponding interface Create supporting documents for existing interfaces and responsibilities when
or responsibility exists. Do not create placeholder API, consumer, integration, substantive content is available.
or operations documents for behavior the application does not have. Audita has Audita has retired its standalone troubleshooting guide; concrete operating and
retired its standalone troubleshooting guide; concrete operating and recovery recovery procedures belong in `docs/operations.md`.
procedures belong in `docs/operations.md`.
## Boundary Rules ## Boundary Rules
### Orientation ### Orientation
The README owns product orientation. The developer guide routes contributors. Link among orientation, architecture, and internal documents; maintain each
Architecture owns normative structure. Internal overview owns the current package or behavior description in its canonical owner.
concrete component map. These documents may link to one another but should not
maintain parallel package or behavior descriptions.
### Commands, Configuration, And Operations ### Commands, Configuration, And Operations
@@ -108,12 +114,16 @@ other contracts.
The release policy defines requirements and invariants that every release must The release policy defines requirements and invariants that every release must
satisfy. The repository-specific release procedure defines the commands and satisfy. The repository-specific release procedure defines the commands and
workflow maintainers use to satisfy that policy. Release notes are immutable workflow maintainers use to satisfy that policy. Release notes record history
historical summaries, not current-state contract owners: the checked-in note at at immutable tags. Maintain current behavior in its canonical documentation,
an immutable tag records that release, while current canonical documentation update it with the corresponding behavior changes, and keep release procedures
must change with the behavior it describes. Do not use a release procedure or consistent with adopted policy.
release note to weaken policy, redefine current behavior, or defer required
documentation updates. ### Project Licensing And Upstream Attribution
README and release documents link to the canonical licensing and attribution
materials under the [OSS policy](oss.md). The release procedure owns URL
construction and publication mechanics.
### Contracts And Implementation ### Contracts And Implementation

215
docs/policy/oss.md Normal file
View File

@@ -0,0 +1,215 @@
# Open Source Licensing And Attribution Policy
**Base Policy Version:** 1.8
**Last Updated**: 2026-09-28
**Upstream Source:** [Standard Repository Policies oss](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/oss.md)
## Purpose And Scope
This policy defines project licensing conventions and a repeatable House Format
for upstream attribution and license notices. It covers the project's own code
and upstream components incorporated into or distributed with the application
or library, including relevant transitive dependencies and copied code,
documentation, or assets.
Determine treatment from the component's terms and actual use.
Consulting development guidance or using tooling alone does not require an
attribution entry. Copying or adapting documentation for inclusion in the
repository is different: preserve its applicable attribution and license terms.
A material's role as development guidance does not exempt copied documents.
Apply any express permissions for attribution-free reuse of example formatting.
The baseline is a publicly available source repository with releases published
alongside it. The format is independent of language, forge, and build system.
It does not require attribution for every development tool, establish license
compatibility, or resolve every obligation arising from use or distribution.
Audita uses the existing GPL-3.0-or-later application grant in
[`COPYRIGHT`](../../COPYRIGHT). The Gitea distribution and publication procedure
are documented in the [release runbook](../release.md).
## Canonical Locations
The [documentation policy](documentation.md) assigns ownership:
- `COPYRIGHT`: project name, copyright statements, SPDX expression, grant,
warranty disclaimer, and third-party statement.
- `LICENSE` contains the complete, unmodified project license text, including
incorporated companion text. Dependency attribution does not relicense the project.
- `docs/oss/attribution.md`: canonical component entries.
- `docs/oss/licenses/`: complete, verbatim standard and applicable companion texts.
Use recognizable license filenames, such as `Apache-2.0.txt` or `LGPL-3.0.txt`.
A shared standard text may serve multiple entries. Keep explanations outside
license texts and preserve distinct versions and exceptions.
## Upstream Reference Examples
Use the commit-pinned upstream examples to create actual project notices.
Retain their links and keep the example collection upstream; keep applicable
license texts locally as specified above.
## Project Licensing
Unless the author specifies otherwise, use **GPL version 3 or later**
(`GPL-3.0-or-later`) for applications and **LGPL version 3 or later**
(`LGPL-3.0-or-later`) for libraries. An author's explicit choice takes precedence:
for example, a one-off script may use MIT. Such a choice requires no exception
rationale, additional approval, or compensating controls under this policy.
These defaults guide new license selection. Adopting this policy does not
relicense existing code or override third-party terms. Preserve an existing
license unless the author deliberately changes it. For mixed-purpose projects,
follow the author's selected scope rather than inferring different licenses for
individual packages.
Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/application/COPYRIGHT)
or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/library/COPYRIGHT)
to create the project’s root `COPYRIGHT` file.
Use verified project names, contribution years, and copyright holders.
For another selected license, adapt the grant, SPDX expression, disclaimer, and
text references together to reflect the author's selected grant.
For GPLv3 projects, copy the complete GPLv3 text into `LICENSE`. For LGPLv3
projects, place the complete LGPLv3 text followed by the complete GPLv3 text in
`LICENSE`; the LGPL incorporates the GPL terms. Keep the texts unmodified and
place project-specific statements in `COPYRIGHT`. For the default grants, the
grant and SPDX expression in `COPYRIGHT` must expressly identify `or-later`;
follow the author’s choice if a different grant is selected.
For other licenses, provide their complete text and any required project-specific
fields; the standard reference collection remains unchanged. Keep `COPYRIGHT`,
`LICENSE`, SPDX expressions, and README descriptions consistent with the actual
grant. This convention introduces no blanket requirement for per-file headers;
preserve notices or add them where the applicable terms require them.
Identify separately licensed documentation or assets in the project grant, with
links to their attribution and license information. An application's default
code license does not override the terms of incorporated documentation.
## Upstream Attribution House Format
Begin `docs/oss/attribution.md` with `# Open Source Attribution Notices`,
followed directly by component entries. These comprise the complete document.
Each entry presents these five fields in order, with blank lines between them:
1. **Project name** as a level-two heading. An optional identification paragraph
may follow, such as `Selected module: MODULE at VERSION.` with the module and
version in backticks. For copied documentation, a concise `Material:` sentence
may identify the affected files and whether they were adapted or copied
without modification. A factual qualifier such as `(transitive dependency)`
is permitted. Limit optional identification prose to factual component and
material scope.
2. **Upstream copyright statement or statements**, preserving their wording.
Put multiple statements in separate paragraphs. Include this field when the
selected upstream source supplies an applicable statement; otherwise, omit it.
3. **SPDX license identifier or expression**, when applicable, using
`SPDX-License-Identifier: EXPRESSION`.
4. **License and notice links**, beginning `License and notices:`, separated
by ` | `, and ending with a period. Label local standard texts by license
name, such as `MIT` or `Apache 2.0`. Label upstream files by their actual
filenames, such as `COPYRIGHT`, `LICENSE`, `NOTICE`, or `PATENTS`.
5. **Source repository link**, rendered exactly as `[Source](COMMIT_URL).`.
Use the upstream [attribution example](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/attribution.md)
to create the project’s `docs/oss/attribution.md`.
The example illustrates omitted fields and multiple copyrights and licenses.
Replace the uppercase placeholders and illustrative URLs with actual component
information. Local license links are relative to the destination
`docs/oss/attribution.md`; copy the applicable texts into its `licenses/`
directory. Do not copy example entries for components the project does not use.
These are five fields, not a line limit. Omit the SPDX field when no applicable
identifier exists; identify nonstandard terms through the linked text. Preserve
licensing alternatives and exceptions, and record a selected option when
relevant through the factual license identification. Do not invent an identifier
or silently resolve an unsettled licensing choice.
Keep entries factual. Do not add agent-authored explanations of license
expressions, file-level license scope, research performed, retained source
notices, or compliance conclusions. Avoid filler such as "none is invented
here" and embellished link labels such as "upstream LICENSE", "additional
patent grant", or "at the imported commit". Preserve actual required upstream
content; this rule excludes editorial additions, not required notices. Policy
interpretation and exception reasoning belong in the adopted OSS policy or an
appropriate decision record, not the attribution document.
## License Texts And Upstream Links
Link standard license texts to their local copies. Link project-specific
notices to their upstream copies. Every upstream repository or notice link must
identify the exact commit corresponding to the
imported version, including the selected source revision for copied material.
Classify material according to its contents. An upstream `LICENSE`,
`COPYING`, or similar file may contain project-specific notices or exceptions
in addition to standard wording. Link both the local standard text and the
commit-specific upstream file when needed. Make companion license texts directly
reachable from the entry.
For project-specific license and attribution material, this policy accepts
direct links to the applicable upstream texts as satisfying reproduction,
inclusion, or copy requirements. This is the adopted house interpretation.
Agents must apply it without adding local-copy requirements or seeking repeated
approval solely because a license uses those terms.
This interpretation concerns notice reproduction. Concrete obligations such as
marking modified files or supplying corresponding source receive their own
applicable treatment. Preserve required notices already present in incorporated
source files; the central attribution entry does not authorize stripping them.
## Discoverability
End the project's README with two friendly statements linking to its actual
grant in `COPYRIGHT` and the attribution document. For example, for a project
with the stated license:
```markdown
PROJECT_NAME is licensed under the [LGPL v3.0 or later](COPYRIGHT).
[Open Source attribution notices](docs/oss/attribution.md) are available.
```
Each new checked-in release document and its hosted download page must end
with links whose visible text is `COPYRIGHT | LICENSE | ATTRIBUTION`. Use absolute
URLs to those files at the release's immutable tag or corresponding immutable source
revision so the links work in both locations. This release navigation is distinct
from upstream component links, which must use the imported commit.
Reuse the checked-in release document as the hosted release body where supported.
The release procedure owns concrete URLs and publication mechanics for delivering
the links through the selected channel. Do not maintain duplicate notice lists.
These conventions do not by themselves require separate downloadable license
assets, source bundles, or a different binary package format.
## Maintenance And Exceptions
Update project licensing statements together when the author changes the grant
or its scope. Update upstream notices in the change that adds, removes, upgrades,
copies, or changes the distribution of a relevant component. Check the selected source's license
and notices rather than assuming they are unchanged. Update affected entries,
commit links, and texts; retain historical versions through Git.
Check affected statements, faithful standard-text copies, and link destinations
as part of ordinary change review. For a future release tag, check intended file
paths against the candidate source; the tag need not resolve remotely before
publication. Do not add publication-time network checks, CI polling, recurring
legal sign-offs, mandatory scanners, or a full software bill of materials merely
to implement this policy.
Use the House Format routinely. Raise an exception only for a concrete obligation
or unresolved rights question it does not address, including any arising from a
particular distribution channel. Record the issue and selected treatment in the
adopted OSS policy or an appropriate decision record. Attribution entries
contain the resulting factual identification and required material, without
repeating that reasoning. Resolve the issue before the affected use or
distribution without reopening settled choices.
Common ownership of projects is neither required nor a blanket exception.
Apply the formatting convention prospectively. Do not rewrite published tags,
notes, binaries, or checksums to retrofit it. Address actual omissions deliberately
under the applicable terms and the [release correction policy](release.md#immutability-and-failure-recovery).
Ordinary attribution maintenance and release links are preparation work, not new
release approval gates.

248
docs/policy/release.md
View File

@@ -1,40 +1,47 @@
# Release Policy # Release Policy
**Base Policy Version:** 1.0 **Base Policy Version:** 1.4
**Last Updated**: 2026-09-23 **Last Updated**: 2026-09-28
**Upstream Source:** [Standard Repository Policies release](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md)
## Purpose ## Purpose
This policy defines the minimum requirements for selecting, validating, This policy defines a proportionate workflow for validating and publishing an
publishing, verifying, and correcting releases. Its goal is to make every intended source revision under a fresh version. Releases should require little
release intentional, reproducible from an exact source revision, documented routine intervention, avoid repeated work, and preserve published contents.
for consumers, and safe from retrospective replacement.
The repository-specific commands that implement these requirements belong in The repository-specific commands belong in `docs/release.md`. Historical release
`docs/release.md`. Historical release summaries belong in `docs/releases/`. summaries belong in `docs/releases/`. The procedure must agree with the adopted
This is an Audita-specific adaptation of the base policy, not a requirement to policy and link to it rather than introduce additional release requirements.
implement the standard unchanged. Adapt it further when Audita's needs warrant;
the canonical procedure must agree with the adopted policy.
## Release Model ## Release Model And Completion
A release identifies one exact source commit with an immutable version tag and A source release identifies one exact committed source revision through an
its checked-in release note. The primary release branch is `main`. immutable version tag and a version-matched, checked-in release note. The
primary release branch is `main` unless the adopted policy specifies otherwise.
The procedure must name the authoritative publication remote.
Release success means that the intended version tag has been created and A successful push of the intended tag, with its source commit available on the
successfully pushed to the authoritative remote with its source commit. The authoritative primary branch, completes the release. The source commit may be
release procedure ends at that point. It must never wait for CI to complete or pushed before the tag or published together with it through an atomic push.
require successful CI status, artifact publication, or consumer installation as The procedure must choose and document the supported approach.
a completion gate.
CI builds and publishes binaries and checksums asynchronously from the tagged Release commands must finish at successful publication. They must not wait for
source. Delayed or failed automation does not reverse release success. Artifact or poll CI, require successful CI status, inspect downloadable artifacts, or
availability is a separate status and must not be claimed merely because the tag check consumer installation or Go module availability as completion gates.
was pushed. Published artifacts must be traceable to the tagged source. A failed or ambiguous push requires resolving the authoritative remote state
before declaring success or retrying; successful pushes do not require a
separate remote read-back gate.
Automation must not silently change the source candidate, move a published tag, Repositories may publish source only. Additional binaries, images, packages,
or replace an existing published artifact. checksums, or other declared deliverables may be published asynchronously from
the tagged source. The procedure must identify those deliverables and the
responsibility of their automation. Published deliverables must be traceable
to that source and identify the same version.
Track source-release completion and artifact delivery separately. Report delivery
failures and optional investigations under artifact-delivery status.
## Supported Platforms ## Supported Platforms
@@ -51,11 +58,14 @@ prerequisites.
## Versioning And Compatibility ## Versioning And Compatibility
Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
no leading zeroes. Each version must be unused locally and on the authoritative no leading zeroes. Prereleases require an explicit adopted policy defining
remote before publication begins. their format and use.
Unless an adopted policy explicitly supports and defines prereleases, The selected version must be unused locally and on the authoritative remote.
prerelease versions are not permitted. Do not require queries to every configured remote or publication service.
A version known to have already been published must not be reused, even if the
normal guards do not inspect that channel. Adding a distribution channel
requires a deliberate update to the policy and procedure where needed.
For releases at or after `v1.0.0`: For releases at or after `v1.0.0`:
@@ -68,101 +78,133 @@ configuration, data, integration, or compatibility contract when the release
note explains the impact and required consumer action. A patch release must note explains the impact and required consumer action. A patch release must
not intentionally break those contracts within its minor line. not intentionally break those contracts within its minor line.
A repository with additional compatibility promises must define them in its Additional compatibility promises and deliberate exceptions belong in the
adopted policy or canonical contract documentation. A release note may explain adopted policy or canonical contract documentation. Release notes explain
a compatibility change, but it must not redefine the current compatibility changes; they do not redefine current compatibility contracts.
contract.
## Release Documentation ## Release Documentation And Preparation
Every release made under this policy must include Every new release must include `docs/releases/<version>.md` in the tagged
`docs/releases/<version>.md` in the tagged source tree. The filename must use source tree. Use the complete version tag as the filename and begin with a
the complete version tag, and the document must begin with a title containing title containing the product name and that exact version.
the product name and that exact version.
Release notes must contain a short summary and any relevant compatibility or Include a short summary and any relevant compatibility impact or upgrade
upgrade instructions. Fixed sections and explicit no-action boilerplate are not instructions. Choose sections suited to the release and keep the note
required. Keep notes proportionate to the change. proportionate to the change.
Release notes are immutable historical summaries. They should link to current Keep exact current contracts in their canonical documents and update affected
canonical documentation for exact behavior. Every affected canonical document documentation with the behavior change. Link to those documents from the note
must be updated in the same candidate; a release note must not substitute for where useful. If annotated tags are used, derive their summary from the
current documentation or defer required documentation changes. checked-in note.
## Candidate Preparation And Validation Include the release footer defined by the [OSS policy](oss.md#discoverability)
in each new release document and preserve it on the hosted download page. The
release procedure defines the concrete URLs and publication mechanics. Prepare
these links with the release note; they do not add a network check or approval
gate.
Use the minimum gates needed for confidence in Audita's release. Provide one Handle version selection, release-note content, and retirement of completed
local command for the selected automated checks, following the roadmaps during preparation. Preserve planned and deferred work and repair
[testing policy](testing.md). Run the deterministic, offline default test suite affected links when retiring roadmaps. Reuse ordinary change review for
once for the candidate and verify that both required Linux targets build. unintended files, credentials, and private data. Scope release-content review
Avoid duplicate test runs solely to satisfy separate release phases. to the tagged source.
Additional checks must address a concrete risk not already covered. Do not ## Candidate Validation
inherit a mandatory linting, documentation audit, platform matrix, or live-service
checklist solely from the base policy. Documentation migration validation is
separate work, not automatically a recurring release gate.
Automate mechanical guards. Do not require manual approvals, sign-offs, laptop Provide one publication command that validates the final committed candidate,
testing, or post-publication inspection as release gates. Version selection and checks publication state, and publishes the intended refs. A validation-only
mode or command may be provided for diagnosis, but must not be a required step
before publication repeats the same checks.
Run the complete deterministic, offline default test suite once for the final
candidate, following the [testing policy](testing.md). For repositories that
publish builds, verify the required build targets. Select those targets for
the application's actual support commitments; native testing on each platform
and access to particular hardware are not default release prerequisites.
Additional gates must address a concrete risk that the existing checks do not
adequately cover. Do not automatically require linting, race testing, module
hygiene audits, documentation audits, credential scans, example validation, or
expanded platform matrices solely because they are possible. Retain such
checks when their distinct protection justifies their cost. A one-time migration
check must not silently become a permanent release requirement.
Release tests must not require real credentials, mutable application services,
paid APIs, provider probes, or inference calls. The procedure may describe dependency
preparation separately from offline validation.
Avoid duplicate validation across release phases. Successful checks for the
same final candidate need not be repeated solely to satisfy another phase;
any reuse must clearly apply to that exact candidate. Persistent validation
caches are not required. If the candidate changes, validate the new candidate.
Cheap publication-state checks may be repeated immediately before pushing
because local or remote state may have changed during validation.
Automate mechanical guards. Do not require manual approvals, sign-offs, or
routine confirmations as release gates. Version selection and
a concise release summary remain preparation inputs, not separate approval rounds. a concise release summary remain preparation inputs, not separate approval rounds.
## Publication Guards ## Publication Guards
The procedure must automate the small set of checks needed to publish the Automate the checks needed to publish the intended source under a fresh version:
intended source under a fresh version:
- valid, unused version on the authoritative remote; - the version has the adopted format and is unused locally and on the
- clean worktree and index on the primary release branch; authoritative remote;
- the exact candidate that passed the local checks, including its matching note; - the worktree and index are clean on the primary release branch;
- publication of that source commit and the exact intended tag. - the source being published is the exact candidate that passed validation,
including its matching release note;
- the remote primary branch already identifies that candidate, or an atomic
source/tag push will advance it to that candidate without discarding remote
history; and
- the tag identifies the validated candidate and only the intended refs are
published.
Do not require remote CI success. Avoid an additional manual confirmation for Fetch the authoritative branch and tag state as needed for these checks.
each mechanical guard. Publish explicit refs rather than all local tags. Do not force branch or tag updates to bypass a failed guard. Publish explicit
A successful push is the completion signal; a failed or ambiguous push must be refs rather than all local tags. Do not require CI success, publication-service
resolved against remote ref state before declaring success or retrying. availability checks, or a separate manual confirmation for each guard.
## Immutability And Correction ## Immutability And Failure Recovery
Published version tags and published deliverables are immutable. Do not move, Published version tags and published contents are immutable. Do not move,
overwrite, recreate, or delete a published tag. Do not replace an artifact, overwrite, recreate, or delete a published tag, or replace a published artifact,
image, package, checksum, signature, provenance statement, or release note checksum, signature, provenance statement, or release note under that version.
under an already published version. The checked-in note at the immutable tag is that release's historical record.
If validation fails before publication, correct and commit the candidate, then If validation fails before publication, correct and commit the candidate and
rerun the release command. Validation must apply to the exact candidate. An rerun the publication command. If a push fails or its outcome is ambiguous,
unpublished local tag may be removed after confirming that it was never published inspect the authoritative remote before retrying. Remove an unpublished local
or used by a release channel. tag only after confirming it was never published or used by a release channel.
An unavailable remote leaves publication status unknown; do not overwrite a tag
to resolve uncertainty.
If a defect is discovered after publication, leave the published release intact. Correct the defect on the primary branch, choose a Transient network, authentication, CI, or consumer-availability failures do not
new patch version or other semantically appropriate new version, write a new by themselves require a new version. Asynchronous delivery may be retried from
matching release note, and perform the complete release procedure again. the same immutable tag. Missing artifacts may be published later, provided
existing published contents are not replaced and the additions remain consistent
with the tagged source and any already-published checksum manifest. If that
cannot be achieved, publish a new version.
A distribution channel's supported yank, deprecation, or advisory mechanism A defect requiring changes to published source or contents requires a corrected
may warn consumers away from a defective release, but it must not replace that commit, a new semantically appropriate version, a matching release note, and
release's contents or reuse its version. the release procedure again. Leave the original release intact. A channel's
yank, deprecation, or advisory mechanism may warn consumers away from a defective
release without replacing its contents or reusing its version.
## Repository Release Procedure ## Repository Release Procedure
Maintain [docs/release.md](../release.md) as a short, executable maintainer runbook. Maintain `docs/release.md` as a short, executable maintainer runbook. It must
It must identify prerequisites, authoritative remote, version and note preparation, identify:
one local validation command, automated source/tag guards, exact publication
commands, and failure handling. It must name the asynchronous automation and link
to this policy for supported platforms and release-success semantics.
Describe how to diagnose or retry failed artifact delivery separately from release 1. prerequisites, primary branch, and authoritative remote;
completion. Missing artifacts may be published later from the same immutable tag; 2. version and release-note preparation;
existing published artifacts must not be overwritten. A source defect requires a 3. one publication command with its selected local checks and automated guards;
new version. No polling or CI waiting belongs in the release command. 4. declared deliverables, required build targets, and automation responsibilities;
5. the successful-push completion point and separately reported delivery status;
and
6. failure handling, ambiguous-push recovery, and asynchronous delivery retries.
## Audita Adaptations Use copyable commands where practical. Keep optional diagnostics and consumer
verification clearly optional. The procedure must not turn preparation work,
The maintainer approved these deviations from the base policy on 2026-09-23: ordinary change review, or post-publication investigation into additional
release gates.
- Audita's needs govern policy adaptation rather than strict template compliance.
- Only Linux amd64 and arm64 are required; macOS arm64 is best effort.
- A successful tag push completes the release; asynchronous CI cannot block it.
- Gates are minimal, automated where practical, and avoid redundant validation
and human intervention.
The [release procedure](../release.md) and its linked scripts implement these
requirements. CI delivery remains asynchronous.

2
docs/releases/README.md
View File

@@ -3,7 +3,7 @@
- [Audita v2.0.0](v2.0.0.md) - [Audita v2.0.0](v2.0.0.md)
- [Audita v1.1.0](v1.1.0.md) - [Audita v1.1.0](v1.1.0.md)
See the [release documentation requirements](../policy/release.md#release-documentation). See the [release documentation requirements](../policy/release.md#release-documentation-and-preparation).
Use the [release procedure](../release.md) to prepare and publish new releases. Use the [release procedure](../release.md) to prepare and publish new releases.
This index does not reconstruct or replace records for existing tags. This index does not reconstruct or replace records for existing tags.

9
docs/roadmap/implementation.md
View File

@@ -2,7 +2,7 @@
**Last updated:** 2026-09-28 **Last updated:** 2026-09-28
**Status:** Planned; no stages implemented. **Status:** In progress; Stages 1–2 complete.
**Audience:** gpt-5.6-terra coding agent. **Audience:** gpt-5.6-terra coding agent.
**Audita planning baseline:** `91d9be68a7bb3a102900253fdfd8438f0a43f666`. **Audita planning baseline:** `91d9be68a7bb3a102900253fdfd8438f0a43f666`.
**Selected upstream revision:** `d84a38ebab26f048cafbe59a2246700c35d29843`. **Selected upstream revision:** `d84a38ebab26f048cafbe59a2246700c35d29843`.
@@ -105,6 +105,13 @@ scope. No application test or publication is required.
## Stage 2 — Customize Remaining Policies and Install Selective Orientation ## Stage 2 — Customize Remaining Policies and Install Selective Orientation
**Completed:** 2026-09-28. Adopted architecture 1.3, documentation 1.11,
release 1.4, and OSS 1.8 with the selected Audita variations. Installed the
upstream root orientation and verbatim Policy Reading Guide, expanded the
scoped attribution, and repaired the release documentation heading link.
Checked versions, provenance and example destinations, local links, policy
differences, and `git diff --check`.
**Files:** `docs/policy/architecture.md`, `docs/policy/documentation.md`, **Files:** `docs/policy/architecture.md`, `docs/policy/documentation.md`,
`docs/policy/release.md`, `docs/policy/oss.md`, `AGENTS.md`, `docs/policy/release.md`, `docs/policy/oss.md`, `AGENTS.md`,
`docs/development.md`, `docs/oss/attribution.md`, and `COPYRIGHT` as needed for `docs/development.md`, `docs/oss/attribution.md`, and `COPYRIGHT` as needed for