Shorten policy documents while preserving their requirements
This commit is contained in:
@@ -23,10 +23,9 @@ updates are incorporated deliberately.
|
||||
| [Releases](docs/policy/release.md) | Minimal justified gates and a clear publication completion point. |
|
||||
| [Open source licensing and attribution](docs/policy/oss.md) | Project grants and factual upstream notices. |
|
||||
|
||||
Use the [licensing examples](examples/licensing/) as references when writing
|
||||
actual notices. Copy needed texts from the [license collection](docs/oss/licenses/README.md).
|
||||
Keep the example collection upstream and use its linked examples to create
|
||||
the project's actual notices.
|
||||
Use the upstream [licensing examples](examples/licensing/) to create actual
|
||||
project notices, and copy applicable texts from the
|
||||
[license collection](docs/oss/licenses/README.md) locally.
|
||||
|
||||
## Work On This Project
|
||||
|
||||
|
||||
@@ -172,7 +172,6 @@ when revising the local document. Keep the material description, modification
|
||||
status, and attribution links accurate. If documents use different upstream
|
||||
revisions, retain each file's exact source metadata and include the necessary
|
||||
commit-specific source and notice links in the single project attribution entry.
|
||||
Update source references when the corresponding upstream changes are incorporated.
|
||||
|
||||
Ordinary review should check the resulting rules, attribution facts, and affected
|
||||
links. A commit-based adoption record is sufficient; no recurring synchronization
|
||||
|
||||
@@ -9,8 +9,7 @@ Read the [agent policy](policy/agents.md) and inspect the working tree before
|
||||
editing. Preserve unrelated work. Follow explicit task instructions, including
|
||||
requests to leave changes uncommitted. This repository's policy files retain
|
||||
their template adoption sections because they are distributed as templates.
|
||||
Application-specific examples illustrate downstream adoption. This repository
|
||||
maintains policy templates and reference materials.
|
||||
Application-specific examples illustrate downstream adoption.
|
||||
|
||||
## Policy Reading Guide
|
||||
|
||||
@@ -54,5 +53,5 @@ license texts even where it would trigger whitespace warnings.
|
||||
Pin adopted-source and example links to commits that contain the referenced
|
||||
files. Discovery links to the upstream project and current adoption guide may
|
||||
track `main` so downstream agents can find updates. Use local links for new
|
||||
assets until a containing commit is available. Pin public reference links to existing commits and confirm
|
||||
their accessibility when preparing publication of the reference changes.
|
||||
assets until a containing commit is available. Confirm public reference links
|
||||
are accessible when preparing publication of the reference changes.
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# Agent Policy
|
||||
|
||||
**Base Policy Version:** 1.2
|
||||
**Base Policy Version:** 1.3
|
||||
|
||||
**Last Updated**: 2026-09-27
|
||||
|
||||
## Base Policy Template
|
||||
|
||||
This document is the base template for the canonical house rules that agents must follow while working in this repository. Repositories that implement this policy should:
|
||||
When adopting this policy:
|
||||
|
||||
1. Retain applicable rules and add project-specific requirements;
|
||||
2. Update the `Last Updated` field to the current date; and
|
||||
@@ -16,7 +16,7 @@ Most projects can adopt the substantive rules as written.
|
||||
|
||||
## Purpose
|
||||
|
||||
Agents working in this repository must read and adhere to the following house rules.
|
||||
Agents must read and follow these rules.
|
||||
|
||||
## Implementation Discipline
|
||||
|
||||
@@ -53,13 +53,13 @@ unless that behavior was expressly selected as part of the contract.
|
||||
|
||||
## Git Commit Policy
|
||||
|
||||
By default, create a commit after completing each coherent unit of work, using a
|
||||
By default, commit each completed, nonempty unit of work using a
|
||||
concise, plain-English message describing what changed. This policy is standing
|
||||
authorization to create those local commits; a separate user request is not
|
||||
required. An explicit user instruction to leave work uncommitted takes precedence.
|
||||
|
||||
A unit of work is a focused, reviewable outcome, including its relevant tests and
|
||||
documentation. Commit each completed outcome that contains file changes.
|
||||
documentation.
|
||||
Complete the appropriate validation before committing. If work is incomplete or
|
||||
validation is blocked, report that state accurately.
|
||||
|
||||
|
||||
@@ -1,13 +1,12 @@
|
||||
# Architecture Policy
|
||||
|
||||
**Base Policy Version:** 1.2
|
||||
**Base Policy Version:** 1.3
|
||||
|
||||
**Last Updated**: 2026-09-27
|
||||
|
||||
## Base Policy Template
|
||||
|
||||
This document is the base template for the canonical architecture policy.
|
||||
Repositories that implement this policy should:
|
||||
When adopting this policy:
|
||||
|
||||
1. Replace the application-specific guidance below with the repository's
|
||||
purpose, adopted architectural constraints, and relevant non-goals;
|
||||
@@ -44,16 +43,10 @@ for collaborators with external integration responsibilities.
|
||||
|
||||
## Adopted Constraints And Implemented Structure
|
||||
|
||||
An adopted architectural constraint governs development, including future
|
||||
functionality. For example, a rule that external integrations belong behind
|
||||
adapters applies whenever such integrations are introduced. Describe current
|
||||
structure from implemented behavior.
|
||||
|
||||
Describe implemented structure accurately. Keep proposals and implementation
|
||||
status in the roadmap, and significant decisions and their rationale in ADRs.
|
||||
When an accepted decision requires changing existing structure, identify that
|
||||
transition through those documents. Describe the target structure as implemented
|
||||
when the corresponding changes land.
|
||||
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.
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# Documentation Policy
|
||||
|
||||
**Base Policy Version:** 1.10
|
||||
**Base Policy Version:** 1.11
|
||||
|
||||
**Last Updated**: 2026-09-27
|
||||
|
||||
## Base Policy Template
|
||||
|
||||
This document is the base template for the canonical documentation policy. Repositories that implement this policy should:
|
||||
When adopting this policy:
|
||||
|
||||
1. Review the list of documents under the `Canonical Ownership` heading, remove any entries that do not currently apply and are not expected to apply to the current project, and add any additional entries that may be required by the current project;
|
||||
2. Create documents for applicable responsibilities when substantive content is available;
|
||||
@@ -72,32 +72,32 @@ 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, including license and attribution navigation. | 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. |
|
||||
| Policy-set provenance and upstream navigation | `docs/policy/meta.md` | Origin of the adopted policy set, local authority, meaning of adoption baselines, and links to upstream adoption and update guidance. | Task-specific reading triggers, detailed adoption procedures, and formal attribution notices. |
|
||||
| Agent policy | `docs/policy/agents.md` | Implementation discipline for coding agents, including proportionality, idiomatic simplicity, 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; 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, proportionate gate selection, publication controls, release completion, and the boundary between required checks and optional verification. | 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` | Project licensing defaults and author choices, COPYRIGHT conventions, upstream attribution format, license-text and notice-link conventions, discoverability, maintenance, and handling of 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, license grant, warranty disclaimer, and statement about third-party material. | Complete license texts and upstream component attribution. |
|
||||
| Project license texts | `LICENSE` | Complete project license text and incorporated companion text, with project-specific fields where required by the selected license. | General licensing policy and upstream component attribution. |
|
||||
| Upstream component attribution | `docs/oss/attribution.md` | Factual identification of incorporated code, documentation, and assets, including material scope and modification status where applicable, copyright statements, license identification, required upstream notices, and license, notice, and source links in the House Format. | 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 attribution entries where applicable. | Project-specific upstream notices, attribution prose, and policy interpretation. |
|
||||
| Repository-specific release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, concrete validation and publication commands, automated publication guards, asynchronous deliverable publication, separate delivery status, optional consumer-facing verification, and failure recovery. | General release requirements, product installation guidance, historical release summaries, and current compatibility contracts. |
|
||||
| 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 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 (if applicable) | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache, and debug handling, resume, cleanup, permissions, recovery, and operational limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. |
|
||||
| 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. |
|
||||
| Public HTTP contract (if applicable) | `docs/api.md` | Routes, authentication, media types, request and response schemas, status codes, pagination, caching, idempotency, rate limits, and HTTP retry semantics. | Client walkthroughs, upstream or downstream integration internals, implementation detail. |
|
||||
| Consumer guidance for the public Go API (if applicable) | `docs/consumers/` | Task-oriented use of the public interface, minimal client examples, and consumer responsibilities. | HTTP wire semantics, external protocol contracts, internal implementation detail. |
|
||||
| Integration contracts for external components (if applicable) | `docs/integrations/` | 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. |
|
||||
| Consumer guidance for the public Go API (if applicable) | `docs/consumers/` | Task-oriented public Go API usage, minimal examples, and consumer responsibilities. | HTTP wire semantics, external protocol contracts, internal implementation detail. |
|
||||
| Integration contracts for external components (if applicable) | `docs/integrations/` | 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. |
|
||||
| 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. |
|
||||
|
||||
Create supporting documents for existing interfaces and responsibilities when
|
||||
substantive content is available.
|
||||
@@ -106,10 +106,8 @@ substantive content is available.
|
||||
|
||||
### 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
|
||||
|
||||
@@ -130,11 +128,9 @@ consistent with adopted policy.
|
||||
|
||||
### Project Licensing And Upstream Attribution
|
||||
|
||||
The [OSS policy](oss.md) defines project licensing conventions, the upstream
|
||||
House Format, and README and release-link conventions. `COPYRIGHT` states the
|
||||
project grant; `LICENSE` supplies its complete license texts. Attribution entries
|
||||
own component-specific information. README and release documents provide navigation to those canonical materials; the
|
||||
release procedure owns URL construction and publication mechanics.
|
||||
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
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Open Source Licensing And Attribution Policy
|
||||
|
||||
**Base Policy Version:** 1.7
|
||||
**Base Policy Version:** 1.8
|
||||
|
||||
**Last Updated**: 2026-09-27
|
||||
|
||||
@@ -21,8 +21,7 @@ Repositories adopting this policy should:
|
||||
|
||||
Selected standard license texts are available in this template repository's
|
||||
[reference collection](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/docs/oss/licenses/README.md). Copy the applicable texts,
|
||||
including companion licenses, into the adopting repository. The collection is a
|
||||
reference collection from which projects select applicable texts. Maintain the
|
||||
including companion licenses, into the adopting repository. Maintain the
|
||||
project's own attribution entries and upstream notice links under this policy.
|
||||
|
||||
## Purpose And Scope
|
||||
@@ -49,13 +48,12 @@ compatibility, or resolve every obligation arising from use or distribution.
|
||||
|
||||
The [documentation policy](documentation.md) assigns ownership:
|
||||
|
||||
- `COPYRIGHT` contains the project name, copyright statements, SPDX expression,
|
||||
license grant, warranty disclaimer, and statement about third-party material.
|
||||
- `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` contains the canonical component entries.
|
||||
- `docs/oss/licenses/` contains complete, verbatim standard license texts,
|
||||
including companion texts where applicable.
|
||||
- `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
|
||||
@@ -63,12 +61,9 @@ license texts and preserve distinct versions and exceptions.
|
||||
|
||||
## Upstream Reference Examples
|
||||
|
||||
The linked examples are reference material hosted in the public policy
|
||||
repository at a fixed commit. Retain these upstream links when adopting this
|
||||
policy and keep the example collection upstream. Create the project's actual
|
||||
`COPYRIGHT` and attribution files using the examples. Applicable license texts
|
||||
still belong locally in
|
||||
`LICENSE` and `docs/oss/licenses/` as specified here.
|
||||
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
|
||||
|
||||
@@ -135,8 +130,7 @@ Each entry presents these five fields in order, with blank lines between them:
|
||||
|
||||
Use the upstream [attribution example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/attribution.md)
|
||||
to create the project’s `docs/oss/attribution.md`.
|
||||
Its three illustrative entries demonstrate a normal entry, omission of an
|
||||
unavailable copyright statement, and multiple copyrights and license texts.
|
||||
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/`
|
||||
|
||||
@@ -1,13 +1,12 @@
|
||||
# Release Policy
|
||||
|
||||
**Base Policy Version:** 1.3
|
||||
**Base Policy Version:** 1.4
|
||||
|
||||
**Last Updated**: 2026-09-27
|
||||
|
||||
## Base Policy Template
|
||||
|
||||
This document is the base template for the canonical release policy.
|
||||
Repositories that implement this policy should:
|
||||
When adopting this policy:
|
||||
|
||||
1. Adapt its requirements to the application's release needs, keeping gates
|
||||
minimal and proportionate;
|
||||
@@ -59,9 +58,8 @@ 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. Successful
|
||||
tag publication completes the source release. Report delivery failures and
|
||||
optional investigations under artifact-delivery status.
|
||||
Track source-release completion and artifact delivery separately. Report delivery
|
||||
failures and optional investigations under artifact-delivery status.
|
||||
|
||||
## Versioning And Compatibility
|
||||
|
||||
@@ -98,7 +96,7 @@ title containing the product name and that exact version.
|
||||
|
||||
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. Apply the format to new release notes.
|
||||
proportionate to the change.
|
||||
|
||||
Keep exact current contracts in their canonical documents and update affected
|
||||
documentation with the behavior change. Link to those documents from the note
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# Testing Policy
|
||||
|
||||
**Base Policy Version:** 1.2
|
||||
**Base Policy Version:** 1.3
|
||||
|
||||
**Last Updated**: 2026-09-27
|
||||
|
||||
## Base Policy Template
|
||||
|
||||
This document is the base template for the canonical testing policy. Repositories that implement this policy should:
|
||||
When adopting this policy:
|
||||
|
||||
1. Retain applicable rules and add project-specific requirements;
|
||||
2. Update the `Last Updated` field to the current date; and
|
||||
@@ -85,7 +85,8 @@ Do not add tests merely because a function, branch, or line exists. Do not add a
|
||||
|
||||
## Choose the right test boundary
|
||||
|
||||
Test through the narrowest stable boundary that expresses the behavior clearly.
|
||||
Choose the narrowest stable boundary that expresses the behavior clearly and
|
||||
provides durable confidence with minimal incidental coupling.
|
||||
|
||||
This is often the package API, but it may instead be:
|
||||
|
||||
@@ -93,20 +94,13 @@ This is often the package API, but it may instead be:
|
||||
- a package-level operation when several internal collaborators jointly produce the behavior; or
|
||||
- a larger integration boundary when correctness emerges from interaction with a real dependency.
|
||||
|
||||
Choose the boundary that gives durable confidence with the least incidental coupling.
|
||||
|
||||
## Test behavior, not implementation
|
||||
|
||||
A test should protect a selected decision, contract, or invariant.
|
||||
|
||||
A test is suspect when its main purpose is to detect that someone:
|
||||
|
||||
- changed an internal constant;
|
||||
- renamed or split a private helper;
|
||||
- reordered equivalent internal operations;
|
||||
- changed incidental formatting;
|
||||
- replaced one correct algorithm with another; or
|
||||
- refactored internal object structure without changing behavior.
|
||||
A test is suspect when it primarily detects changes to private constants or
|
||||
helpers, equivalent operation ordering, incidental formatting, equivalent
|
||||
algorithms, or internal structure that preserves behavior.
|
||||
|
||||
Behavioral tests should normally remain stable through internal refactoring that preserves the contract.
|
||||
|
||||
@@ -172,7 +166,7 @@ Use a test-controlled limit and measure the behavior relative to that limit.
|
||||
|
||||
## Assign each behavior a test owner
|
||||
|
||||
Each behavior should have a clear test owner. Where these layers exist:
|
||||
Where these layers exist, assign ownership as follows:
|
||||
|
||||
- Parser tests own parsing cases.
|
||||
- Validator tests own validation rules.
|
||||
@@ -203,12 +197,9 @@ Mocks are appropriate when the contract includes facts such as:
|
||||
- an expensive API is called no more than once; or
|
||||
- a security audit event is emitted.
|
||||
|
||||
Use mocks for contractual interactions.
|
||||
|
||||
## Go-specific guidance
|
||||
|
||||
Select techniques according to the behavior and risk being tested. The following
|
||||
are options to select where they provide useful protection:
|
||||
Select techniques by behavior and risk:
|
||||
|
||||
- table-driven tests for meaningful behavioral categories and boundaries;
|
||||
- `t.TempDir()` for real filesystem behavior;
|
||||
@@ -242,19 +233,16 @@ Remove or consolidate a test when the underlying design has made recurrence impo
|
||||
|
||||
## Deleting or rewriting tests
|
||||
|
||||
Maintain tests according to their continuing protective value.
|
||||
|
||||
Delete or rewrite a test when its maintenance cost exceeds the confidence it provides.
|
||||
Delete or rewrite tests when maintenance cost exceeds their continuing
|
||||
protective value.
|
||||
|
||||
Strong candidates include tests that:
|
||||
|
||||
- require updates after harmless internal changes;
|
||||
- directly assert private constants without protecting a real contract;
|
||||
- duplicate the same policy across several layers;
|
||||
- assert incidental private constants or snapshot large amounts of incidental output;
|
||||
- verify mock choreography rather than outcomes;
|
||||
- snapshot large amounts of incidental output;
|
||||
- test trivial private helpers already exercised through stable package behavior;
|
||||
- protect risks already covered more effectively elsewhere;
|
||||
- duplicate policy across layers, retest trivial helpers covered by package
|
||||
behavior, or protect risks covered more effectively elsewhere;
|
||||
- are flaky, misleading, obsolete, or disproportionately expensive to diagnose; or
|
||||
- no longer correspond to a plausible failure mode.
|
||||
|
||||
@@ -280,6 +268,5 @@ A test suite is sufficient when:
|
||||
- tests usually remain stable through legitimate internal changes; and
|
||||
- additional tests would mostly repeat existing protection or preserve inconsequential implementation details.
|
||||
|
||||
Judge sufficiency by protection against consequential failures, useful failure
|
||||
signals, and stability through legitimate internal changes. Reassess it as the
|
||||
application, its users, and the consequences of failure evolve.
|
||||
Reassess sufficiency as the application, its users, and the consequences of
|
||||
failure evolve.
|
||||
|
||||
275
tmp/audit.md
275
tmp/audit.md
@@ -1,275 +0,0 @@
|
||||
# Policy Concision Audit
|
||||
|
||||
Date: 2026-09-27
|
||||
|
||||
Reviewed revision: `bf92cb1`
|
||||
|
||||
## Scope And Recommendation
|
||||
|
||||
Reviewed the seven policy templates, README, adoption and contributor guides,
|
||||
agent entry points, and license-reference guidance. The policy suite remains
|
||||
unchanged. Verbatim license texts and operative licensing examples are outside
|
||||
this editorial exercise.
|
||||
|
||||
Prioritize local repetition and long descriptions. Keep useful examples,
|
||||
explicit authority limits, conditions, and exceptions. Preserve both AGENTS.md
|
||||
files, the concrete standard-library example in agents.md, and the passages
|
||||
reserved for careful equivalence review in the preceding audit. Those earlier
|
||||
findings remain available in commit `ad4a20e`; this report replaces the temporary
|
||||
audit file with the current findings.
|
||||
|
||||
A conservative first pass could remove roughly 400–650 words from the seven
|
||||
policy templates (about 5–8%), subject to reviewing actual rewrites. This is an
|
||||
editorial estimate, not a measured result or a required reduction target. The
|
||||
largest opportunities are documentation and testing. Further upstream-guide
|
||||
cleanup has less effect on ordinary downstream tasks.
|
||||
|
||||
## Reading Cost Baseline
|
||||
|
||||
Counts below are whitespace-separated words, including Markdown syntax. A
|
||||
compatible tokenizer was unavailable locally; these are not token counts.
|
||||
URLs, code, identifiers, and table syntax make word-to-token ratios variable.
|
||||
|
||||
| Policy | Current words | After removing its Base Policy Template section |
|
||||
| --- | ---: | ---: |
|
||||
| Agents | 620 | 551 |
|
||||
| Architecture | 536 | 429 |
|
||||
| Documentation | 1,861 | 1,765 |
|
||||
| Meta | 186 | 131 |
|
||||
| OSS | 1,743 | 1,605 |
|
||||
| Release | 1,595 | 1,445 |
|
||||
| Testing | 2,044 | 1,984 |
|
||||
| Total | 8,585 | 7,910 |
|
||||
|
||||
The second column of counts models only removal of adoption instructions. Actual
|
||||
adoptions also add provenance and customize rules, particularly architecture.
|
||||
Removing template instructions already saves 675 words; shortening those
|
||||
instructions further primarily benefits upstream adoption work.
|
||||
|
||||
Task-specific routing remains the largest structural saving. For example,
|
||||
agent + architecture + testing policies total 2,964 words after removing their
|
||||
template sections, before adding the developer guide and relevant application
|
||||
material. Adding documentation policy raises that subtotal to 4,729 words.
|
||||
These are illustrative reading sets, not a new required bundle.
|
||||
|
||||
## Priority Findings
|
||||
|
||||
Locations use stable headings and distinctive phrases at the reviewed revision.
|
||||
Suggested replacements are examples for review, not changes already applied.
|
||||
|
||||
### 1. Documentation: Shorten The Ownership Table
|
||||
|
||||
**Location:** docs/policy/documentation.md, Canonical Ownership.
|
||||
|
||||
The section occupies 988 words, slightly over half the document. Many cells
|
||||
repeat “current,” “complete,” “concrete,” and topic nouns already supplied by
|
||||
the owner path or topic column. Shorten cells while preserving their distinct
|
||||
assignments and exclusions.
|
||||
|
||||
Examples:
|
||||
|
||||
- README owned content: “Purpose, value, shortest successful invocation, and
|
||||
navigation, including licensing and attribution.”
|
||||
- Internal overview owned content: “Implemented packages, responsibilities,
|
||||
and links to focused internal docs.”
|
||||
- Attribution owned content: “House Format component entries: identity,
|
||||
material scope and modifications where applicable, copyright, license,
|
||||
notices, and source links.”
|
||||
- Testing-policy owned content: “Test philosophy, risk sufficiency, boundaries,
|
||||
doubles, coverage, regressions, and test maintenance.”
|
||||
|
||||
Retain every owner and unique responsibility. In particular, keep configuration
|
||||
precedence, runtime versus logical paths, public HTTP versus Go consumer
|
||||
contracts, and roadmap versus ADR ownership explicit.
|
||||
|
||||
**Recommendation:** Shorten cells first. Retain the exclusions column for this
|
||||
light pass. Removing it wholesale would require proving that every boundary is
|
||||
expressed elsewhere and could make ownership harder to understand.
|
||||
|
||||
### 2. Documentation: Consolidate Ownership Restatements
|
||||
|
||||
**Location:** Boundary Rules, especially Orientation and Project Licensing And
|
||||
Upstream Attribution.
|
||||
|
||||
Several sentences repeat table assignments. Retain the operational rule and
|
||||
remove the repeated inventory. For example, Orientation could read:
|
||||
|
||||
> Link among orientation, architecture, and internal documents; maintain each
|
||||
> package or behavior description in its canonical owner.
|
||||
|
||||
The licensing subsection can focus on README/release navigation and the release
|
||||
procedure's responsibility for URL construction. The table already assigns
|
||||
COPYRIGHT, LICENSE, attribution, and OSS policy ownership.
|
||||
|
||||
Keep the distinctive rules about internal documents linking to exact external
|
||||
contracts, updating current docs with behavior, and immutable release history.
|
||||
Preserve the Security And Privacy passage from the earlier audit.
|
||||
|
||||
**Likely combined saving for findings 1–2:** approximately 180–280 words.
|
||||
|
||||
### 3. Testing: Remove Immediate Repetition
|
||||
|
||||
**Location:** docs/policy/testing.md, Choose The Right Test Boundary, Use Test
|
||||
Doubles Deliberately, and Definition Of Sufficient.
|
||||
|
||||
- Combine the first and last boundary-selection sentences:
|
||||
“Choose the narrowest stable boundary that expresses the behavior clearly
|
||||
and provides durable confidence with minimal incidental coupling.” Keep the
|
||||
three examples of appropriate boundaries.
|
||||
- Delete the final “Use mocks for contractual interactions.” The numbered list
|
||||
already states this and the intervening examples illustrate it.
|
||||
- Keep the sufficiency checklist and its reassessment instruction; remove the
|
||||
final sentence that repeats consequential failures, useful signals, and
|
||||
refactor stability from the checklist.
|
||||
|
||||
These are direct repetitions with little interpretive value.
|
||||
|
||||
### 4. Testing: Condense Supporting Lists And Introductions
|
||||
|
||||
**Location:** Test Behavior, Not Implementation; Assign Each Behavior A Test
|
||||
Owner; Go-Specific Guidance; Deleting Or Rewriting Tests.
|
||||
|
||||
- Condense the six incidental-change examples to one sentence while keeping
|
||||
all categories: private constants/helpers, equivalent operation ordering,
|
||||
incidental formatting, equivalent algorithms, and internal structure.
|
||||
- Introduce layer ownership once: “Where these layers exist, assign ownership
|
||||
as follows.” Preserve each layer's distinct responsibility.
|
||||
- Shorten the Go-technique introduction to “Select techniques by behavior and
|
||||
risk.” Keep the conditions for fuzzing, goldens, integration, and end-to-end
|
||||
testing; those conditions prevent the list becoming a checklist.
|
||||
- Merge the first two test-maintenance sentences:
|
||||
“Delete or rewrite tests when maintenance cost exceeds their continuing
|
||||
protective value.”
|
||||
- Group overlapping deletion candidates, preserving all failure categories.
|
||||
For example, private constants, trivial helpers, and incidental snapshots can
|
||||
share a bullet describing tests tied to incidental implementation details.
|
||||
|
||||
**Likely combined saving for findings 3–4:** approximately 100–180 words.
|
||||
|
||||
Keep the expected-effects table, the distinction between a failing and obsolete
|
||||
test, the concurrency code examples, the rejection-versus-queuing qualification,
|
||||
and explicit regression-test expectations. These teach decisions that a short
|
||||
slogan would leave ambiguous. Preserve the previously reserved What Deserves
|
||||
Tests passages and execution requirements.
|
||||
|
||||
### 5. Architecture: Consolidate The Current-Structure Explanation
|
||||
|
||||
**Location:** docs/policy/architecture.md, Adopted Constraints And Implemented
|
||||
Structure.
|
||||
|
||||
“Describe current structure from implemented behavior” is immediately followed
|
||||
by “Describe implemented structure accurately.” Keep one. Condense the remaining
|
||||
lifecycle explanation while retaining future applicability and separate owners:
|
||||
|
||||
> 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.
|
||||
|
||||
Retain the explicit rule against promoting incidental choices into invariants.
|
||||
The preceding Architectural Approach already supplies the adapter example.
|
||||
|
||||
**Likely saving:** approximately 25–40 words. Preserve the hexagonal preference,
|
||||
proportionality, and concrete threat-scope distinction.
|
||||
|
||||
### 6. OSS: Shorten Navigation And Example Instructions
|
||||
|
||||
**Location:** docs/policy/oss.md, Canonical Locations, Upstream Reference
|
||||
Examples, and instructions following the House Format fields.
|
||||
|
||||
- Compress each canonical-location description while retaining its unique
|
||||
responsibilities. Keep the copyright/grant fields, companion-text rule,
|
||||
standard-text version/exception distinctions, and project-license boundary.
|
||||
- Merge the upstream-example instructions:
|
||||
“Use the commit-pinned upstream examples to create actual project notices.
|
||||
Keep the example collection upstream and applicable license texts locally.”
|
||||
Preserve the named local destinations in Canonical Locations.
|
||||
- The attribution example's three demonstrated cases can be summarized as
|
||||
“The example illustrates omitted fields and multiple copyrights and licenses.”
|
||||
The House Format already describes normal entries and the omission rules.
|
||||
- Remove the adoption-section sentence “The collection is a reference collection
|
||||
from which projects select applicable texts.” The preceding sentence already
|
||||
says to copy applicable texts. This saving is upstream-only.
|
||||
|
||||
**Likely saving:** approximately 50–90 words. Leave the exact five-field format,
|
||||
required punctuation, SPDX handling, imported-commit rules, linking house rule,
|
||||
editorial restrictions, author choice, and concrete-exception process intact.
|
||||
Preserve all previously reserved passages.
|
||||
|
||||
### 7. Agents: Small, Frequently Read Savings
|
||||
|
||||
**Location:** docs/policy/agents.md, Purpose and opening Git Commit Policy prose.
|
||||
|
||||
- “Agents working in this repository must read and adhere to the following house
|
||||
rules” can become “Agents must read and follow these rules.”
|
||||
- “Commit each completed outcome that contains file changes” repeats the opening
|
||||
default commitment. Merge its nonempty-outcome qualification into that opening
|
||||
sentence, retaining focused units, relevant tests/docs, explicit opt-out,
|
||||
and completion of validation.
|
||||
|
||||
**Likely saving:** approximately 15–30 words. Preserve both AGENTS.md files, the
|
||||
standard-library example, explicit restrictions/guarantees rules, authorization
|
||||
boundaries, and concrete commit commands. Keep the distinction between reviewing
|
||||
working-tree changes and reviewing the staged commit.
|
||||
|
||||
### 8. Release: Limit This Pass To Small Duplications
|
||||
|
||||
**Location:** docs/policy/release.md, Release Model And Completion and Release
|
||||
Documentation And Preparation.
|
||||
|
||||
- Remove “Successful tag publication completes the source release” from the
|
||||
separate artifact-status paragraph: the earlier completion rule already says
|
||||
this with the important authoritative-branch condition.
|
||||
- Remove “Apply the format to new release notes”: the section begins “Every new
|
||||
release must include…” and the remaining paragraph defines that format.
|
||||
|
||||
**Likely saving:** approximately 15–20 words. Keep the separately reported
|
||||
artifact status. Preserve all previously reserved passages on gates, offline
|
||||
checks, human approvals, immutability, publication state, and recovery. Their
|
||||
apparent repetition often covers distinct phases and failure conditions.
|
||||
|
||||
## Secondary Findings: Upstream Guides
|
||||
|
||||
These improve readability but contribute little to routine downstream policy
|
||||
reading. Avoid counting them as savings in the adopted suite.
|
||||
|
||||
- **docs/development.md, Orientation:** remove the second statement that the
|
||||
repository maintains policy templates and reference materials; it repeats
|
||||
the opening. Keep the upstream-template/downstream-example distinction.
|
||||
- **docs/development.md, Editing And Validation:** the first and last sentences
|
||||
both require commit-pinned reference links. State that once, with the discovery
|
||||
link exception, temporary local links, and publication accessibility check.
|
||||
- **README.md, Adopt The Policies:** combine the two instructions to use licensing
|
||||
examples for actual notices. Keep both destinations: upstream examples and
|
||||
locally copied applicable texts.
|
||||
- **docs/adoption.md, Update Deliberately:** remove “Update source references when
|
||||
the corresponding upstream changes are incorporated.” The preceding paragraph
|
||||
already requires Upstream Source to identify the revision actually incorporated.
|
||||
- **Template adoption boilerplate:** replace long “This document is the base
|
||||
template…” introductions with “When adopting this policy:” where applicable.
|
||||
Keep each document's actual adoption steps and removal instruction. These
|
||||
sections disappear downstream, so this is a lower priority.
|
||||
- **docs/policy/meta.md:** already small and useful. Leave it intact for this pass.
|
||||
|
||||
## Guardrails For Implementation
|
||||
|
||||
1. Preserve each rule's actor, force, scope, exceptions, and timing. A shorter
|
||||
statement that turns a prohibition into a preference fails this audit's goal.
|
||||
2. Keep conditions beside examples. Preserve concrete examples selected by the
|
||||
author and illustrative distinctions that prevent overbuilt implementations.
|
||||
3. Consolidate within documents first. Cross-document links can increase actual
|
||||
context use if agents must load another policy to resolve a routine rule.
|
||||
4. Keep the downstream reading snippet in the upstream adoption guide. Its
|
||||
repetition serves a copying workflow and is absent from ordinary downstream
|
||||
orientation once installed in the local developer guide.
|
||||
5. Avoid adding summaries, glossaries, split policy variants, or generated
|
||||
condensed copies. Each creates more text or another source to maintain.
|
||||
6. Preserve precise paths, full commit pins, provenance, and legal text. URL
|
||||
shortening, whitespace changes, and cryptic abbreviations offer poor tradeoffs.
|
||||
7. After editing, measure the changed policies and representative reading sets.
|
||||
Use a chosen tokenizer if available and name it; otherwise report word counts.
|
||||
Actual context savings depend on what the agent reads and its tokenizer.
|
||||
|
||||
A useful first pass is the table-cell cleanup, direct repetition removal, and
|
||||
shortened supporting prose above. Larger structural changes can wait for
|
||||
experience with downstream adoption.
|
||||
Reference in New Issue
Block a user