From edbbf3d5ea7909d38a10db7ce13920a9c13297a3 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 28 Sep 2026 01:07:03 +0000 Subject: [PATCH] Adopt remaining policies and selective reading guide --- AGENTS.md | 8 +- COPYRIGHT | 6 +- docs/development.md | 27 +++- docs/oss/attribution.md | 2 +- docs/policy/architecture.md | 40 +++++- docs/policy/documentation.md | 96 +++++++------ docs/policy/oss.md | 215 ++++++++++++++++++++++++++++ docs/policy/release.md | 248 +++++++++++++++++++-------------- docs/releases/README.md | 2 +- docs/roadmap/implementation.md | 9 +- 10 files changed, 491 insertions(+), 162 deletions(-) create mode 100644 docs/policy/oss.md diff --git a/AGENTS.md b/AGENTS.md index 924c8db..8b791c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,6 @@ -Please review `docs/development.md` for initial orientation in this repository -and follow its task-specific reading guide. +Start with `docs/development.md` for orientation and use its policy 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. diff --git a/COPYRIGHT b/COPYRIGHT index ea7166c..69d73f2 100644 --- a/COPYRIGHT +++ b/COPYRIGHT @@ -18,6 +18,6 @@ GNU General Public License for more details. Third-party code and assets are subject to their respective license terms. -Policy documents adapted from Standard Repository Policies remain licensed -under CC-BY-SA-4.0. See docs/oss/attribution.md for the affected material, -upstream credit, and license links. +Policy documents and guidance adapted from Standard Repository Policies +remain licensed under CC-BY-SA-4.0. See docs/oss/attribution.md for the +affected material, upstream credit, and license links. diff --git a/docs/development.md b/docs/development.md index f72b376..3c29d64 100644 --- a/docs/development.md +++ b/docs/development.md @@ -7,9 +7,8 @@ Audita is a Go CLI for transcript polishing. Start with the ## Before Changing the Repository Coding agents must read and follow the [agent policy](policy/agents.md) before -recommending, planning, or implementing changes. Read the -[architecture policy](policy/architecture.md) for boundaries and invariants, -then use the task guide below rather than reading every reference indiscriminately. +recommending, planning, or implementing changes. Use the policy reading guide +below to select the policies applicable to the task. Confirm the requested scope and behavior contract, make focused changes in the 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 [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 Use Go 1.25.5 or newer. From the repository root: diff --git a/docs/oss/attribution.md b/docs/oss/attribution.md index 0adfeeb..c7378b1 100644 --- a/docs/oss/attribution.md +++ b/docs/oss/attribution.md @@ -2,7 +2,7 @@ ## 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 diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index f0568c4..2b38111 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -1,10 +1,42 @@ # 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 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); 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 subprocess callers. Preserve the stream and exit behavior defined by the diff --git a/docs/policy/documentation.md b/docs/policy/documentation.md index c51b72b..bafacb7 100644 --- a/docs/policy/documentation.md +++ b/docs/policy/documentation.md @@ -1,8 +1,9 @@ # 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 @@ -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 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, 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. Partial features may be described only to their implemented boundary. -ADRs are the narrow exception: an ADR may record an accepted architectural -decision before implementation, but acceptance must not be presented as proof -that the behavior exists. The 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. +Architectural constraints may govern future changes. Describe current structure +from implemented behavior. + +ADRs may record an accepted architectural decision before implementation. The +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 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. -Developer docs should link to user-facing and external contracts rather than -restate them. +its owned topic. Keep user and operator docs focused on using and operating the +application. Developer docs should link to user-facing and external contracts +for their definitions. ### Examples Complete copyable files belong in `examples/`. Documentation may use the 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 configuration used in documentation should match the application. @@ -61,40 +64,43 @@ secret values. | 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. | -| 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. | -| 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. | -| 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. | +| 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, 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, boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. | +| 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. | -| 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. | -| 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. | -| 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. | -| 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. | -| 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. | -| 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. | -| 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. | -| 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. | -| 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. | +| 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, 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. | +| 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. | +| 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. | +| Project license texts | `LICENSE` | Complete project and incorporated companion license texts, with required project-specific fields. | General licensing policy and upstream component attribution. | +| 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. | +| 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. | +| 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. | +| 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. | | 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. | -| 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. | -| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other files intended to be copied or run. | Field-by-field reference, command reference, prose explanation. | +| 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 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 copyable or runnable files. | Field-by-field reference, command reference, prose explanation. | -Documents that do not exist are required only when the corresponding interface -or responsibility exists. Do not create placeholder API, consumer, integration, -or operations documents for behavior the application does not have. Audita has -retired its standalone troubleshooting guide; concrete operating and recovery -procedures belong in `docs/operations.md`. +Create supporting documents for existing interfaces and responsibilities when +substantive content is available. +Audita has retired its standalone troubleshooting guide; concrete operating and +recovery procedures belong in `docs/operations.md`. ## Boundary Rules ### Orientation -The README owns product orientation. The developer guide routes contributors. -Architecture owns normative structure. Internal overview owns the current -concrete component map. These documents may link to one another but should not -maintain parallel package or behavior descriptions. +Link among orientation, architecture, and internal documents; maintain each +package or behavior description in its canonical owner. ### Commands, Configuration, And Operations @@ -108,12 +114,16 @@ other contracts. The release policy defines requirements and invariants that every release must satisfy. The repository-specific release procedure defines the commands and -workflow maintainers use to satisfy that policy. Release notes are immutable -historical summaries, not current-state contract owners: the checked-in note at -an immutable tag records that release, while current canonical documentation -must change with the behavior it describes. Do not use a release procedure or -release note to weaken policy, redefine current behavior, or defer required -documentation updates. +workflow maintainers use to satisfy that policy. Release notes record history +at immutable tags. Maintain current behavior in its canonical documentation, +update it with the corresponding behavior changes, and keep release procedures +consistent with adopted policy. + +### 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 diff --git a/docs/policy/oss.md b/docs/policy/oss.md new file mode 100644 index 0000000..e7f8b83 --- /dev/null +++ b/docs/policy/oss.md @@ -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. diff --git a/docs/policy/release.md b/docs/policy/release.md index 070c165..4ac5fc7 100644 --- a/docs/policy/release.md +++ b/docs/policy/release.md @@ -1,40 +1,47 @@ # 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 -This policy defines the minimum requirements for selecting, validating, -publishing, verifying, and correcting releases. Its goal is to make every -release intentional, reproducible from an exact source revision, documented -for consumers, and safe from retrospective replacement. +This policy defines a proportionate workflow for validating and publishing an +intended source revision under a fresh version. Releases should require little +routine intervention, avoid repeated work, and preserve published contents. -The repository-specific commands that implement these requirements belong in -`docs/release.md`. Historical release summaries belong in `docs/releases/`. -This is an Audita-specific adaptation of the base policy, not a requirement to -implement the standard unchanged. Adapt it further when Audita's needs warrant; -the canonical procedure must agree with the adopted policy. +The repository-specific commands belong in `docs/release.md`. Historical release +summaries belong in `docs/releases/`. The procedure must agree with the adopted +policy and link to it rather than introduce additional release requirements. -## Release Model +## Release Model And Completion -A release identifies one exact source commit with an immutable version tag and -its checked-in release note. The primary release branch is `main`. +A source release identifies one exact committed source revision through an +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 -successfully pushed to the authoritative remote with its source commit. The -release procedure ends at that point. It must never wait for CI to complete or -require successful CI status, artifact publication, or consumer installation as -a completion gate. +A successful push of the intended tag, with its source commit available on the +authoritative primary branch, completes the release. The source commit may be +pushed before the tag or published together with it through an atomic push. +The procedure must choose and document the supported approach. -CI builds and publishes binaries and checksums asynchronously from the tagged -source. Delayed or failed automation does not reverse release success. Artifact -availability is a separate status and must not be claimed merely because the tag -was pushed. Published artifacts must be traceable to the tagged source. +Release commands must finish at successful publication. They must not wait for +or poll CI, require successful CI status, inspect downloadable artifacts, or +check consumer installation or Go module availability as completion gates. +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, -or replace an existing published artifact. +Repositories may publish source only. Additional binaries, images, packages, +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 @@ -51,11 +58,14 @@ prerequisites. ## Versioning And Compatibility 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 -remote before publication begins. +no leading zeroes. Prereleases require an explicit adopted policy defining +their format and use. -Unless an adopted policy explicitly supports and defines prereleases, -prerelease versions are not permitted. +The selected version must be unused locally and on the authoritative remote. +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`: @@ -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 not intentionally break those contracts within its minor line. -A repository with additional compatibility promises must define them in its -adopted policy or canonical contract documentation. A release note may explain -a compatibility change, but it must not redefine the current compatibility -contract. +Additional compatibility promises and deliberate exceptions belong in the +adopted policy or canonical contract documentation. Release notes explain +changes; they do not redefine current compatibility contracts. -## Release Documentation +## Release Documentation And Preparation -Every release made under this policy must include -`docs/releases/.md` in the tagged source tree. The filename must use -the complete version tag, and the document must begin with a title containing -the product name and that exact version. +Every new release must include `docs/releases/.md` in the tagged +source tree. Use the complete version tag as the filename and begin with a +title containing the product name and that exact version. -Release notes must contain a short summary and any relevant compatibility or -upgrade instructions. Fixed sections and explicit no-action boilerplate are not -required. Keep notes proportionate to the change. +Include a short summary and any relevant compatibility impact or upgrade +instructions. Choose sections suited to the release and keep the note +proportionate to the change. -Release notes are immutable historical summaries. They should link to current -canonical documentation for exact behavior. Every affected canonical document -must be updated in the same candidate; a release note must not substitute for -current documentation or defer required documentation changes. +Keep exact current contracts in their canonical documents and update affected +documentation with the behavior change. Link to those documents from the note +where useful. If annotated tags are used, derive their summary from the +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 -local command for the selected automated checks, following the -[testing policy](testing.md). Run the deterministic, offline default test suite -once for the candidate and verify that both required Linux targets build. -Avoid duplicate test runs solely to satisfy separate release phases. +Handle version selection, release-note content, and retirement of completed +roadmaps during preparation. Preserve planned and deferred work and repair +affected links when retiring roadmaps. Reuse ordinary change review for +unintended files, credentials, and private data. Scope release-content review +to the tagged source. -Additional checks must address a concrete risk not already covered. Do not -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. +## Candidate Validation -Automate mechanical guards. Do not require manual approvals, sign-offs, laptop -testing, or post-publication inspection as release gates. Version selection and +Provide one publication command that validates the final committed candidate, +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. ## Publication Guards -The procedure must automate the small set of checks needed to publish the -intended source under a fresh version: +Automate the checks needed to publish the intended source under a fresh version: -- valid, unused version on the authoritative remote; -- clean worktree and index on the primary release branch; -- the exact candidate that passed the local checks, including its matching note; -- publication of that source commit and the exact intended tag. +- the version has the adopted format and is unused locally and on the + authoritative remote; +- the worktree and index are clean on the primary release branch; +- 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 -each mechanical guard. Publish explicit refs rather than all local tags. -A successful push is the completion signal; a failed or ambiguous push must be -resolved against remote ref state before declaring success or retrying. +Fetch the authoritative branch and tag state as needed for these checks. +Do not force branch or tag updates to bypass a failed guard. Publish explicit +refs rather than all local tags. Do not require CI success, publication-service +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, -overwrite, recreate, or delete a published tag. Do not replace an artifact, -image, package, checksum, signature, provenance statement, or release note -under an already published version. +Published version tags and published contents are immutable. Do not move, +overwrite, recreate, or delete a published tag, or replace a published artifact, +checksum, signature, provenance statement, or release note under that 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 -rerun the release command. Validation must apply to the exact candidate. An -unpublished local tag may be removed after confirming that it was never published -or used by a release channel. +If validation fails before publication, correct and commit the candidate and +rerun the publication command. If a push fails or its outcome is ambiguous, +inspect the authoritative remote before retrying. Remove an unpublished local +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 -new patch version or other semantically appropriate new version, write a new -matching release note, and perform the complete release procedure again. +Transient network, authentication, CI, or consumer-availability failures do not +by themselves require a new version. Asynchronous delivery may be retried from +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 -may warn consumers away from a defective release, but it must not replace that -release's contents or reuse its version. +A defect requiring changes to published source or contents requires a corrected +commit, a new semantically appropriate version, a matching release note, and +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 -Maintain [docs/release.md](../release.md) as a short, executable maintainer runbook. -It must identify prerequisites, authoritative remote, version and note preparation, -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. +Maintain `docs/release.md` as a short, executable maintainer runbook. It must +identify: -Describe how to diagnose or retry failed artifact delivery separately from release -completion. Missing artifacts may be published later from the same immutable tag; -existing published artifacts must not be overwritten. A source defect requires a -new version. No polling or CI waiting belongs in the release command. +1. prerequisites, primary branch, and authoritative remote; +2. version and release-note preparation; +3. one publication command with its selected local checks and automated guards; +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 - -The maintainer approved these deviations from the base policy on 2026-09-23: - -- 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. +Use copyable commands where practical. Keep optional diagnostics and consumer +verification clearly optional. The procedure must not turn preparation work, +ordinary change review, or post-publication investigation into additional +release gates. diff --git a/docs/releases/README.md b/docs/releases/README.md index a987cd1..47f55bb 100644 --- a/docs/releases/README.md +++ b/docs/releases/README.md @@ -3,7 +3,7 @@ - [Audita v2.0.0](v2.0.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. This index does not reconstruct or replace records for existing tags. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 67e9382..c6c231e 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -2,7 +2,7 @@ **Last updated:** 2026-09-28 -**Status:** Planned; no stages implemented. +**Status:** In progress; Stages 1–2 complete. **Audience:** gpt-5.6-terra coding agent. **Audita planning baseline:** `91d9be68a7bb3a102900253fdfd8438f0a43f666`. **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 +**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`, `docs/policy/release.md`, `docs/policy/oss.md`, `AGENTS.md`, `docs/development.md`, `docs/oss/attribution.md`, and `COPYRIGHT` as needed for