diff --git a/README.md b/README.md index a7d687a..781bc14 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,8 @@ updates are incorporated deliberately. Use the [licensing examples](examples/licensing/) as references when writing actual notices. Copy needed texts from the [license collection](docs/oss/licenses/README.md). -Applications do not need their own copy of this project's example collection. +Keep the example collection upstream and use its linked examples to create +the project's actual notices. ## Work On This Project diff --git a/docs/adoption.md b/docs/adoption.md index dddb789..ce43dbe 100644 --- a/docs/adoption.md +++ b/docs/adoption.md @@ -21,13 +21,11 @@ templates themselves, use the [contributor guide](development.md). Select an upstream commit and read the policies relevant to the requested work. Use a revision containing the [project grant](../COPYRIGHT) and the reference -assets you intend to use. Record its full commit identifier; a moving branch -name is not an adoption baseline. No package manager or automatic update service -is required. +assets you intend to use. Record its full commit identifier as the adoption +baseline. Git records are sufficient to maintain adoption provenance. -Preserve existing downstream decisions and unrelated changes. Adoption is a -local customization task, not authorization to add every capability, document, -restriction, or release gate mentioned in the templates. +Preserve existing downstream decisions and unrelated changes. Customize selected +policies to existing project responsibilities and the author's requested scope. ## Copy And Customize @@ -35,10 +33,9 @@ restriction, or release gate mentioned in the templates. downstream locations. Follow each template's adoption instructions and remove its `Base Policy Template` section afterward. Create supporting documents when they have useful - content for an existing responsibility, rather than filling an empty outline. + content for an existing responsibility. 2. Tailor architecture to the actual project. Preserve the author's selected - license and existing application contracts. Do not infer new product behavior - from policy examples. + license and existing application contracts. 3. Retain each document's `Base Policy Version` and set `Last Updated` to the local adoption date. Add `Upstream Source` metadata linking to that specific document at the selected commit. Retain this provenance in future edits. @@ -90,8 +87,8 @@ there; the documentation policy remains the owner of the documentation topic map ## Attribute Copied Policies Use the [canonical attribution entry](../examples/licensing/policy-attribution.md) -in the downstream `docs/oss/attribution.md`. It is an entry fragment to insert -beneath that document's existing title, not an additional document title. +by inserting it beneath the existing title in the downstream +`docs/oss/attribution.md`. - Replace `UPSTREAM_COMMIT` with the selected full commit in all three URLs. - Adjust the `Material:` sentence to identify the files actually copied. Keep @@ -134,7 +131,7 @@ Original example formatting is available under CC0 as specified in attribution entry for this project. Keep links to these examples in the adopted policy pointed at upstream commits. -Do not populate the downstream `examples/` directory with this collection. +Keep the example collection upstream and use it to create actual project notices. Copy the applicable standard license texts into the actual local license files; retain their wording and their own terms. Those copies remain necessary under the House Format even though example documents stay upstream. @@ -147,30 +144,27 @@ When asked to check the policy set and recommend updates: `Base Policy Version`, and local customizations. Different documents may have different adoption baselines. 2. Inspect upstream `main` and record its full commit identifier. Use that fixed - revision for the review so later upstream changes do not shift the comparison. + revision throughout the comparison. 3. Compare each recorded upstream file with its counterpart at the review revision, then assess the upstream changes against the locally customized policy. Version labels help orientation; inspect the actual differences. Note new, renamed, or removed upstream policies where relevant to the project. 4. Recommend applicable changes with their reasons, identify conflicts with deliberate local choices, and name policies that need no update. Include the - baseline and review revisions so the comparison can be reproduced. Do not - recommend wholesale replacement merely because upstream differs. -5. If a baseline is missing or unavailable, report the uncertainty. You may - compare available content, but do not assume the local policy is an unchanged - upstream copy or invent an adoption revision. If upstream cannot be reached, - report that limitation rather than claiming the policies are current. + baseline and review revisions so the comparison can be reproduced. Ground + recommendations in the local project's needs. +5. Base provenance claims on available evidence. Report missing or unavailable + baselines explicitly and qualify comparisons accordingly. Report upstream + access failures and the resulting limits on the review. -For a recommendation-only request, leave files and adoption metadata unchanged. -A completed review does not mean a newer policy has been adopted. Apply the -following procedure when implementation is requested. +For a recommendation-only request, preserve the current files and adoption +metadata. Apply the following procedure when implementation is requested. ## Update Deliberately Compare the previously recorded upstream files with a selected newer revision. -Apply relevant changes while preserving local decisions; do not overwrite -customized documents wholesale or treat every upstream recommendation as a new -local requirement. +Apply relevant changes while preserving local decisions and selecting updates +that serve the project. Update `Base Policy Version` when adopting a newer template version and update `Upstream Source` to the revision actually incorporated. Change `Last Updated` @@ -178,7 +172,7 @@ 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. -Do not change a source reference to a version that was merely reviewed. +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 diff --git a/docs/development.md b/docs/development.md index d52adbc..b1696e9 100644 --- a/docs/development.md +++ b/docs/development.md @@ -9,8 +9,8 @@ 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 template examples do not require this repository to acquire -application interfaces or infrastructure. +Application-specific examples illustrate downstream adoption. This repository +maintains policy templates and reference materials. ## Policy Reading Guide @@ -39,7 +39,7 @@ application interfaces or infrastructure. Keep reusable instructions portable. Put adoption instructions in template sections and project-specific contributor procedures here. Original licensing examples belong under `examples/licensing/`; explanatory instructions belong in -their guide or policy so they are not copied into notices. +their guide or policy. Increment the affected template's `Base Policy Version` and update its date when changing its substantive rules or adoption instructions. Preserve the licensing @@ -47,15 +47,12 @@ scope defined in `COPYRIGHT`; reproduced license texts must remain verbatim. Review the diff, run `git diff --check` for changed prose, and check affected links and examples. Example placeholders and destination-relative links should be -validated against the documented downstream layout, not treated as published -URLs or missing local dependencies. No application build or new test suite is -needed for prose-only changes. Retain upstream formatting in verbatim license -texts even where it would trigger whitespace warnings. +validated against the documented downstream layout. Diff, link, and example +review suffice for prose-only changes. Retain upstream formatting in verbatim +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. New assets can use local -links within this repository until a containing commit is available; do not -invent a future hash or publish changes merely to obtain one. -Before publication, confirm that public reference links are accessible. This is -change validation, not a recurring downstream release gate. +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. diff --git a/docs/oss/licenses/README.md b/docs/oss/licenses/README.md index cd6b72e..f12bf8b 100644 --- a/docs/oss/licenses/README.md +++ b/docs/oss/licenses/README.md @@ -3,11 +3,11 @@ This collection supplies reusable reference texts for repositories adopting the [Open Source Licensing And Attribution Policy](../../policy/oss.md). Copy the texts your incorporated code, documentation, or assets use into your repository's -`docs/oss/licenses/`, together with applicable companion texts. The collection is not exhaustive, and adopting -projects need not copy every file. +`docs/oss/licenses/`, together with applicable companion texts. Select the texts +applicable to incorporated material. -These files are reference material. Their presence does not license this -repository or an adopting project under every listed license. +These files are reference material. Each project's grant is stated in COPYRIGHT; +each component's grant is identified in its attribution entry. ## Sources @@ -40,14 +40,13 @@ and the example-format dedication described in the root [COPYRIGHT](../../../COP Put actual upstream copyright statements in the component's attribution entry. Link project-specific notices and exceptions to the imported upstream commit. - GNU filenames identify the text version. The attribution entry's SPDX - expression specifies `-only` or `-or-later` according to the upstream grant; - a shared text does not select that grant for the component. + expression specifies `-only` or `-or-later` according to the upstream grant. - LGPL 2.0 is the GNU Library General Public License. LGPL 2.1 and 3.0 are the GNU Lesser General Public License; these versions are distinct. - When copying LGPL 3.0, also copy GPL 3.0, whose terms it incorporates, and make both texts reachable from the attribution entry. Include other companion texts or exceptions when the component's applicable terms require them. -Record any intentional source refresh here and preserve the retrieved text -without editorial changes. No synchronization service or recurring release check -is required for this reference collection. +Record intentional source refreshes here and preserve retrieved texts verbatim. +Synchronization services and recurring release checks are optional for this +reference collection. diff --git a/docs/policy/agents.md b/docs/policy/agents.md index 4927f2a..8cf748f 100644 --- a/docs/policy/agents.md +++ b/docs/policy/agents.md @@ -1,18 +1,18 @@ # Agent Policy -**Base Policy Version:** 1.1 +**Base Policy Version:** 1.2 -**Last Updated**: 2026-09-23 +**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: -1. Review the policy, remove any rules that must not apply to the current project, and add any additional rules that are required by the current project; +1. Retain applicable rules and add project-specific requirements; 2. Update the `Last Updated` field to the current date; and 3. Remove this heading (`Base Policy Template`) and the associated text. -Most projects will not require any revisions to the substantive policy rules as written below. +Most projects can adopt the substantive rules as written. ## Purpose @@ -59,9 +59,9 @@ 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. Do not commit after every intermediate edit or create empty commits. +documentation. Commit each completed outcome that contains file changes. Complete the appropriate validation before committing. If work is incomplete or -validation is blocked, report that state rather than presenting it as completed. +validation is blocked, report that state accurately. Before committing: @@ -69,10 +69,10 @@ Before committing: changes. Identify changes that predate the current unit of work. 2. Exclude secrets, local environment files, generated junk, and unrelated changes. 3. Stage only the files or hunks belonging to the completed unit. Use `git add .` - only when every included change belongs to that unit. Do not disturb unrelated - staged or unstaged work. -4. Review `git diff --staged` and run appropriate checks for the change. Do not - repeat checks already passed for unchanged content merely to create a commit. + only when every included change belongs to that unit. Preserve unrelated + staged and unstaged work. +4. Review `git diff --staged` and run appropriate checks for the change. Reuse + successful checks for unchanged content. 5. Review `git log --oneline -n 10` and use `git commit -m ""`. 6. Report the commit identifier and any remaining uncommitted work. diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 8432508..0ac0806 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -1,8 +1,8 @@ # Architecture Policy -**Base Policy Version:** 1.1 +**Base Policy Version:** 1.2 -**Last Updated**: 2026-09-25 +**Last Updated**: 2026-09-27 ## Base Policy Template @@ -14,14 +14,12 @@ Repositories that implement this policy should: 2. Distinguish rules governing development from descriptions of implemented structure. Keep proposed changes and implementation status in their canonical documents under the [documentation policy](documentation.md); -3. Reference supporting documents only when they contain useful information. - Do not create `TODO` documents solely to populate an architectural outline; +3. Reference supporting documents when they contain useful information; 4. Update the `Last Updated` field to the current date; and 5. Remove this heading (`Base Policy Template`) and the associated text. -This template requires substantial customization. Select topics that matter to -the application; the examples below are not a checklist of required subsystems, -interfaces, or supporting documents. +This template requires substantial customization. Select topics relevant to +the application from the examples below. ## Purpose And Ownership @@ -31,7 +29,7 @@ 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 rather than repeating those definitions here. +to ADRs for decision rationale. ## Architectural Approach @@ -40,23 +38,22 @@ 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. The preference -does not by itself require an interface for every type, a fixed directory tree, -or adapters for collaborators that have no external integration responsibility. +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 -An adopted architectural constraint governs development. It is not evidence -that every component or capability to which it could apply already exists. -For example, a rule that external integrations belong behind adapters can -apply to future integrations without implying that those integrations are -implemented or planned. +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; do not describe the target structure as -already implemented or treat acceptance as proof of compliance. +transition through those documents. Describe the target structure as implemented +when the corresponding changes land. Constraints must reflect deliberately selected requirements and decisions. Do not promote incidental implementation choices into architectural invariants. @@ -81,12 +78,11 @@ application's adopted requirements, along with scenarios it explicitly excludes. For example, distinguish handling untrusted application input from defending against a privileged actor concurrently modifying the host filesystem. -These statements should explain the scope of the adopted architectural constraints. Excluding a scenario is not a claim that it cannot occur. Do not -infer additional defenses or guarantees merely because a hypothetical threat -can be described. Unsettled scope decisions should be raised for a deliberate +Threat exclusions define the scope of the adopted requirements. Base defenses +and guarantees on those requirements and raise unsettled scope for a deliberate decision under the [agent policy](agents.md). -Keep this discussion proportionate. A separate threat assessment or security -document is not required merely to adopt this template. Configuration, -operations, and internal documents retain ownership of credential supply, +Keep this discussion proportionate to the application. A separate threat +assessment or security document is optional when adopting this template. +Configuration, operations, and internal documents retain ownership of credential supply, runtime handling, and implementation mechanisms under the documentation policy. diff --git a/docs/policy/documentation.md b/docs/policy/documentation.md index 2edb93a..e302b76 100644 --- a/docs/policy/documentation.md +++ b/docs/policy/documentation.md @@ -1,6 +1,6 @@ # Documentation Policy -**Base Policy Version:** 1.9 +**Base Policy Version:** 1.10 **Last Updated**: 2026-09-27 @@ -25,7 +25,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 @@ -37,27 +37,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. -Architectural constraints may govern future changes without implying that the -components or capabilities they would govern already exist. This does not permit -describing a proposed system structure as implemented. +Architectural constraints may govern future changes. Describe current structure +from implemented behavior. -ADRs 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. +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. @@ -100,9 +99,8 @@ secret values. | 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. | -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. +Create supporting documents for existing interfaces and responsibilities when +substantive content is available. ## Boundary Rules @@ -125,12 +123,10 @@ 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 diff --git a/docs/policy/oss.md b/docs/policy/oss.md index c8bf77a..2a4a36e 100644 --- a/docs/policy/oss.md +++ b/docs/policy/oss.md @@ -1,6 +1,6 @@ # Open Source Licensing And Attribution Policy -**Base Policy Version:** 1.6 +**Base Policy Version:** 1.7 **Last Updated**: 2026-09-27 @@ -22,8 +22,8 @@ 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 -convenience, not an exhaustive catalog or a required bundle; maintain the project's -own attribution entries and upstream notice links under this policy. +reference collection from which projects select applicable texts. Maintain the +project's own attribution entries and upstream notice links under this policy. ## Purpose And Scope @@ -32,8 +32,7 @@ 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. -Treatment follows the component's terms and actual use, rather than its -classification as a direct dependency. +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 @@ -66,9 +65,9 @@ license texts and preserve distinct versions and exceptions. The linked examples are reference material hosted in the public policy repository at a fixed commit. Retain these upstream links when adopting this -policy; do not copy the example collection into the application's or library's -`examples/` directory. Create the project's actual `COPYRIGHT` and attribution -files using the examples. Applicable license texts still belong locally in +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. ## Project Licensing @@ -88,10 +87,9 @@ individual packages. Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/application/COPYRIGHT) or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/library/COPYRIGHT) to create the project’s root `COPYRIGHT` file. -Replace the project name, years, and holders with accurate information; do not -assume the maintainer owns every contribution or advance years automatically. +Use verified project names, contribution years, and copyright holders. For another selected license, adapt the grant, SPDX expression, disclaimer, and -text references together. The examples do not constrain the author's choice. +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 @@ -113,8 +111,7 @@ 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. Do not add an introductory summary, -policy links, audit narrative, disclaimer, or concluding explanation. +followed directly by component entries. These comprise the complete document. Each entry presents these five fields in order, with blank lines between them: @@ -123,19 +120,18 @@ Each entry presents these five fields in order, with blank lines between them: 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; do not describe dependency-discovery methods. + 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. If the selected upstream - source supplies no applicable statement, omit this field without inventing - one or adding an explanation of its absence. + 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**, using `[Source](COMMIT_URL).` with no `Source:` - prefix or additional description. +5. **Source repository link**, rendered exactly as `[Source](COMMIT_URL).`. 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`. @@ -164,16 +160,15 @@ 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 the upstream copies instead of storing them locally. Every upstream -repository or notice link must identify the exact commit corresponding to the +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. -Do not use moving branches or version tags as substitutes for that commit. -Classify material by its contents, not its filename. An upstream `LICENSE`, +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 rather than leaving readers to infer their location. +reachable from the entry. For project-specific license and attribution material, this policy accepts direct links to the applicable upstream texts as satisfying reproduction, diff --git a/docs/policy/release.md b/docs/policy/release.md index 78a1d19..9a1c122 100644 --- a/docs/policy/release.md +++ b/docs/policy/release.md @@ -1,8 +1,8 @@ # Release Policy -**Base Policy Version:** 1.2 +**Base Policy Version:** 1.3 -**Last Updated**: 2026-09-26 +**Last Updated**: 2026-09-27 ## Base Policy Template @@ -59,9 +59,9 @@ 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. -Artifact delivery is a separate status. A successful tag push is not evidence -that artifacts are available. Delivery failures do not reverse source-release -success, and optional investigation must not delay release completion. +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. ## Versioning And Compatibility @@ -97,15 +97,13 @@ source tree. Use the complete version tag as the filename and begin with a title containing the product name and that exact version. Include a short summary and any relevant compatibility impact or upgrade -instructions. Keep the note proportionate to the change. Fixed sections and -explicit no-action boilerplate are not required. Existing historical notes -need not be rewritten to adopt this format. +instructions. Choose sections suited to the release and keep the note +proportionate to the change. Apply the format to new release notes. 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. A release note must not substitute for current documentation. -If annotated tags are used, derive their summary from the checked-in note -rather than requiring a separately authored account of the same release. +where useful. If annotated tags are used, derive their summary from the +checked-in note. 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 @@ -113,12 +111,11 @@ 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. -Version selection, release-note content, and retirement of completed roadmaps -are preparation responsibilities, not separate human approval gates. Preserve -planned and deferred work and repair affected links when retiring roadmaps. -Ordinary change review covers unintended files, credentials, and private data; -do not repeat it as a release-specific sign-off. Ignored local files are not -prohibited merely because they exist: they are not included in the tagged source. +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. ## Candidate Validation diff --git a/docs/policy/testing.md b/docs/policy/testing.md index 5d3fbb1..e4e545e 100644 --- a/docs/policy/testing.md +++ b/docs/policy/testing.md @@ -1,24 +1,24 @@ # Testing Policy -**Base Policy Version:** 1.1 +**Base Policy Version:** 1.2 -**Last Updated**: 2026-09-25 +**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: -1. Review the policy, remove any rules that must not apply to the current project, and add any additional rules that are required by the current project; +1. Retain applicable rules and add project-specific requirements; 2. Update the `Last Updated` field to the current date; and 3. Remove this heading (`Base Policy Template`) and the associated text. -Most projects will not require any revisions to the substantive testing policy rules as written below. +Most projects can adopt the substantive rules as written. ## Purpose Our tests exist to make **incorrect changes expensive and correct changes cheap**. -We do not optimize for test count, line coverage, exhaustive isolation, or the fewest possible tests. We optimize for sufficient confidence in important behavior while imposing as little unnecessary friction as possible on future development. +We optimize for sufficient confidence in important behavior while minimizing friction on future development. ## Every test has a cost @@ -32,9 +32,9 @@ Evaluate that tradeoff at two levels: 1. **Per test:** What realistic defect does this test detect, how consequential would that defect be, and is that protection worth the test's lifetime cost? 2. **Across the suite:** Does this collection provide materially more confidence than a smaller, simpler suite would? -Some friction is intentional. Tests should make dangerous changes—such as breaking compatibility, corrupting data, violating security boundaries, or reintroducing subtle bugs—require deliberate review. They should not make ordinary internal changes needlessly expensive. +Some friction is intentional. Tests should make dangerous changes—such as breaking compatibility, corrupting data, violating security boundaries, or reintroducing subtle bugs—require deliberate review. Keep ordinary internal changes inexpensive. -The cost of a test is not a reason to omit testing by default. Do not cite maintenance cost abstractly. When omitting a plausible test, be able to state why the protected failure is low-risk, already covered, obvious, reversible, or cheaper to detect elsewhere. For consequential, subtle, or difficult-to-observe behavior, the presumption should favor testing. +Evaluate maintenance cost against the specific failure being protected. When omitting a plausible test, be able to state why the protected failure is low-risk, already covered, obvious, reversible, or cheaper to detect elsewhere. For consequential, subtle, or difficult-to-observe behavior, the presumption should favor testing. ## Default testing style @@ -66,7 +66,7 @@ To the extent the following features are present in the application, prioritize 6. Previously observed or plausible regressions. 7. Representative integration and end-to-end workflows. -A package-level contract is behavior relied upon by another package or major collaborator, not every observable detail of a package implementation. +A package-level contract comprises behavior relied upon by another package or major collaborator. Choose tests for requested behavior and established contracts. Tests must not introduce new restrictions, guarantees, or threat scenarios merely because they @@ -93,11 +93,11 @@ 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. -Do not force all behavior through oversized end-to-end tests. Do not test every private helper merely because it exists. Choose the boundary that gives durable confidence with the least incidental coupling. +Choose the boundary that gives durable confidence with the least incidental coupling. ## Test behavior, not implementation -A test should protect a decision, contract, or invariant. A test must not memorialize the current implementation. +A test should protect a selected decision, contract, or invariant. A test is suspect when its main purpose is to detect that someone: @@ -108,7 +108,7 @@ A test is suspect when its main purpose is to detect that someone: - replaced one correct algorithm with another; or - refactored internal object structure without changing behavior. -Refactoring should normally require no test edits unless the refactored structure is itself part of the contract. +Behavioral tests should normally remain stable through internal refactoring that preserves the contract. ## Expected effects of different changes @@ -125,7 +125,7 @@ A test failing is not the same as a test needing to be edited. Many tests may co ## Separate mechanism from policy -Configurable thresholds and defaults must not be duplicated throughout the test suite. +Derive expectations from test-controlled configuration and relationships. For this example, assume the selected contract rejects a request to start more processes than a configured limit. Do not encode its production default indirectly: @@ -161,16 +161,16 @@ limit solely to reproduce this example. The production default should be tested exactly only when its literal value is itself a public, operational, safety, protocol, or compatibility requirement. -Apply the same rule to limits, timeouts, capacities, retry counts, and ranges: test relationships and behavior, not duplicated literals. +Apply the same rule to limits, timeouts, capacities, retry counts, and ranges: test relationships and behavior. For established concurrency limits, distinguish these behaviors where the contract requires them: 1. **Configuration handling:** values are accepted or rejected according to the selected contract. 2. **Runtime enforcement:** observed peak concurrency never exceeds the configured limit. -Use a test-controlled limit and measure the behavior relative to that limit. Do not merely assert today's default value. +Use a test-controlled limit and measure the behavior relative to that limit. -## Avoid semantic duplication across layers +## Assign each behavior a test owner Each behavior should have a clear test owner. Where these layers exist: @@ -182,7 +182,7 @@ Each behavior should have a clear test owner. Where these layers exist: - CLI tests own argument and configuration mapping. - End-to-end tests prove that representative assembled workflows work. -Higher-level tests should not repeat every lower-level case. A single intentional policy change should not require unrelated edits across many test files. +Give each layer its distinct responsibility and keep expectation updates localized to the contract being changed. ## Use test doubles deliberately @@ -203,12 +203,12 @@ 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. -Do not use mocks merely to isolate every object or reproduce the implementation's call graph. +Use mocks for contractual interactions. ## Go-specific guidance Select techniques according to the behavior and risk being tested. The following -are options, not a checklist that every package or application must satisfy: +are options to select where they provide useful protection: - table-driven tests for meaningful behavioral categories and boundaries; - `t.TempDir()` for real filesystem behavior; @@ -218,19 +218,17 @@ are options, not a checklist that every package or application must satisfy: - integration tests where correctness depends on component interaction; and - a small number of representative end-to-end tests when assembled workflows expose meaningful risks not adequately covered at narrower boundaries. -Avoid exact error-string assertions unless the wording is itself contractual. Prefer `errors.Is`, `errors.As`, typed errors, or structured error fields. +Prefer `errors.Is`, `errors.As`, typed errors, or structured error fields. Use exact error-wording assertions only when the wording is contractual. -At CLI boundaries, prefer exit classifications, structured output, and the smallest stable semantic fragment needed to identify the error. Do not snapshot complete diagnostic wording unless it is contractual. +At CLI boundaries, prefer exit classifications, structured output, and the smallest stable semantic fragment needed to identify the error. Use complete diagnostic snapshots only when the wording is contractual. Golden-file updates must require an explicit local flag. CI must not update golden files automatically, and reviewers must inspect the semantic diff before accepting an update. -Keep tests readable and direct. Test helpers and fixture frameworks must earn their own maintenance cost; do not build elaborate test infrastructure for small or isolated needs. +Keep tests readable and direct. Size test helpers and fixture frameworks to the maintenance benefit they provide. ## Coverage -Coverage is a diagnostic, not a target. - -Use it to find untested critical branches and unexpectedly weak packages. Do not write low-value tests solely to increase a percentage, and do not infer test quality from coverage alone. +Use coverage to locate untested critical branches and unexpectedly weak packages. Evaluate test quality through meaningful behavioral protection and choose coverage according to risk. Pure domain logic will often warrant higher coverage than CLI wiring or external adapters. Uneven coverage is acceptable when it reflects risk. @@ -238,13 +236,13 @@ Pure domain logic will often warrant higher coverage than CLI wiring or external A bug fix should normally include a regression test that fails before the fix and passes afterward. -Retain the test when the defect could realistically recur and its consequences justify the ongoing cost. Prefer the narrowest durable test of the violated contract or invariant; do not preserve accidental implementation details from the original bug. +Retain the test when the defect could realistically recur and its consequences justify the ongoing cost. Prefer the narrowest durable test of the violated contract or invariant. -Not every historical bug requires a permanent test. If the underlying design has made recurrence impossible, the test has become redundant, or a stronger invariant test now subsumes it, remove or consolidate it. +Remove or consolidate a test when the underlying design has made recurrence impossible, its protection is redundant, or a stronger invariant test subsumes it. ## Deleting or rewriting tests -Tests are maintained code, not permanent historical artifacts. +Maintain tests according to their continuing protective value. Delete or rewrite a test when its maintenance cost exceeds the confidence it provides. @@ -260,11 +258,11 @@ Strong candidates include tests that: - are flaky, misleading, obsolete, or disproportionately expensive to diagnose; or - no longer correspond to a plausible failure mode. -Several brittle tests may encode one genuine requirement. Replace them with one durable behavior-level or invariant test rather than preserving all of them. +Several brittle tests may encode one genuine requirement. Consolidate them into one durable behavior-level or invariant test. ## Reviewing a proposed test -Use the following questions when the value, boundary, or durability of a proposed test is not self-evident. Significant test additions should be reviewable against them, but written answers are not required for every routine test. +Use the following questions when a proposed test needs closer evaluation. Significant test additions should be reviewable against them; written answers are optional for routine tests. 1. Which requested behavior or established contract does it protect, and what realistic defect would violate it? 2. How likely and consequential is that defect, and is it already protected elsewhere? @@ -278,10 +276,10 @@ A test suite is sufficient when: - important requested behavior and established contracts are protected against realistic, consequential failures; - boundaries and component interactions have coverage where they introduce meaningful risks not protected elsewhere; -- failures provide useful signal rather than redundant noise; -- legitimate internal changes usually do not require test edits; and +- failures provide useful, distinct signals; +- tests usually remain stable through legitimate internal changes; and - additional tests would mostly repeat existing protection or preserve inconsequential implementation details. -Sufficiency is a risk judgment, not a coverage percentage, test count, or required -mix of testing techniques. Reassess it as the application, its users, and the -consequences of failure evolve. +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. diff --git a/tmp/audit.md b/tmp/audit.md deleted file mode 100644 index 826ed18..0000000 --- a/tmp/audit.md +++ /dev/null @@ -1,283 +0,0 @@ -# Affirmative Language Style Audit - -Date: 2026-09-27 -Reviewed revision: `7b09ea1` -Scope: seven policy templates; root and default AGENTS.md; README; adoption and -contributor guides; license-collection README; original licensing examples and -COPYRIGHT. Verbatim license texts are outside the editorial scope. - -## Summary - -The suite is coherent, but repeated negative constructions make several rules -longer and more defensive than necessary. Testing, release, and OSS contain the -largest concentrations. Prefer an affirmative instruction that names the desired -behavior, its scope, and any necessary condition. Preserve normative strength: -replacing “must not” with “prefer” changes policy. - -The author's clarification is central: explicit negative rules such as “do not -strengthen guarantees” may be the clearest expression of intent. Retain those -rules where they directly establish an important boundary. The aim is to reduce -rhetorical negative parallelism, not to eliminate negative grammar. The -careful-review candidates below are optional; retaining the existing negative -rule is preferred whenever the affirmative alternative is less precise. - -This is a light editorial audit, grouping related occurrences rather than listing -every negative word. Locations below refer to the reviewed revision. Proposed -wording is illustrative, with adjacent rules assumed to remain in place unless -an entry explicitly proposes consolidating them. The policy files are unchanged. - -Recommended sequence: - -1. Revise redundant contrasts and negative parallelism in orientation and - explanatory prose. -2. Consolidate repeated prohibitions into affirmative rules with explicit scope. -3. Review authority limits, release requirements, and attribution exceptions - individually for equivalent meaning. -4. Preserve useful distinctions, exact technical conditions, and legal text. - -## Straightforward Revisions - -### Entry Points And Guides - -- **AGENTS.md:3; agents/AGENTS.md:2 — “Do not read the entire suite by default.”** - Use: “Read the policies selected by the task-specific reading guide.” The - surrounding instructions still require the agent policy. This can be merged - into the existing opening sentence. -- **README.md:28; docs/adoption.md:136–137; docs/policy/oss.md:67–72 — copying examples.** - Use: “Keep the example collection upstream and use its linked examples to - create the project's actual notices.” Retain the separate instruction to copy - applicable license texts locally. -- **docs/adoption.md:23–30 — baseline and customization contrasts.** - Use: “Record the selected full commit identifier as the adoption baseline. - Maintain adoption records through Git. Customize the selected policies to - existing project responsibilities and the author's requested scope.” The - existing preservation of local decisions should remain explicit. -- **docs/adoption.md:36–41 — “rather than filling an empty outline” and inferred behavior.** - Use: “Create supporting documents when they have useful content for an existing - responsibility. Tailor architecture to the actual project and preserve the - author's selected license and existing application contracts.” -- **docs/adoption.md:93–94 — “not an additional document title.”** - The positive instruction already specifies the destination: “Insert the - canonical attribution entry beneath the document's existing title.” -- **docs/adoption.md:149–162 — comparison and uncertain provenance.** - Use: “Use the recorded review commit throughout the comparison. Recommend - changes justified by the local project's needs, preserving deliberate local - choices. Base provenance claims on available evidence and report missing - baselines or unavailable upstream sources explicitly.” Retain reporting of - policies that are already current and the baseline/review identifiers. -- **docs/adoption.md:164–181 — review versus adoption.** - Use: “For a recommendation-only request, preserve the current files and - adoption metadata. Update source references when the corresponding upstream - changes are incorporated.” This can replace the repeated warning about - versions that were merely reviewed. -- **docs/development.md:10–13 — application infrastructure.** - Use: “Application-specific examples illustrate downstream adoption. This - repository maintains policy templates and reference materials.” -- **docs/development.md:40–53 — examples and prose validation.** - Use: “Keep explanatory instructions in their guide or policy. Validate example - placeholders and relative links against the documented downstream layout. - Validate prose-only changes through diff, link, and example review.” Preserve - the explicit protection against turning that work into build/test requirements - if the resulting wording leaves the scope ambiguous. -- **docs/development.md:56–61 — future hashes and recurring gates.** - Use: “Use local links for new assets until a containing commit is available. - Pin public reference links to existing commits and confirm accessibility when - preparing their publication.” Keep the release policy's gate boundary in force. - -### Agent Policy - -- **docs/policy/agents.md:11,15; docs/policy/testing.md:11,15 — template boilerplate.** - Use: “Retain applicable rules and add project-specific requirements.” Then: - “Most projects can adopt the substantive rules as written.” -- **docs/policy/agents.md:27–31 — “not for the fewest lines, fewest options…”** - Use: “Optimize for conceptual simplicity and maintainability while preserving - the requested behavior and flexibility.” The affirmative criteria already - express the intended tradeoff. -- **docs/policy/agents.md:43–48 — filesystem example and evaluative language.** - Keep the concrete example but shorten it: “Use standard-library file operations - for ordinary copying. Add application-level power-loss protection or defenses - against privileged concurrent filesystem changes when expressly requested.” - The current “wasteful, unnecessary, and not idiomatic” adds editorial emphasis - rather than another requirement. -- **docs/policy/agents.md:61–75 — commit timing and repeated checks.** - Use: “Commit each completed, focused, reviewable outcome with its relevant - tests and documentation. Report incomplete work or blocked validation - accurately. Preserve unrelated staged and unstaged changes. Reuse successful - checks for unchanged content.” Keep the existing staging and validation steps. - -### Architecture And Documentation - -- **docs/policy/architecture.md:17–24 — empty documents and checklist warning.** - Use: “Select topics relevant to the application and reference supporting - documents when they contain useful information.” -- **docs/policy/architecture.md:33–34; docs/policy/documentation.md:26–28,51–60 — repeated definitions.** - Use: “Link to the canonical owner for exact definitions and to maintained - examples for complete copyable files.” Retain audience-specific detail rules. -- **docs/policy/architecture.md:43–45 — hexagonal architecture machinery.** - Use: “Choose interfaces and package layout to serve the application's actual - boundaries. Use adapters for collaborators with external integration - responsibilities.” Preserve the strong preference for hexagonal architecture. -- **docs/policy/architecture.md:49–59; docs/policy/documentation.md:40–47 — planned versus implemented.** - Use: “Architectural constraints govern development. Describe current structure - from implemented behavior, record proposals and implementation status in the - roadmap, and record accepted decisions and rationale in ADRs.” Preserve the - ability to adopt a constraint before the affected functionality exists. -- **docs/policy/architecture.md:84–92 — threat-scope explanation.** - Use: “Threat exclusions define the scope of the adopted requirements. Base - defenses and guarantees on those requirements and raise unsettled scope for a - deliberate decision. Keep the discussion proportionate to the application.” - Retain the concrete distinction between untrusted input and privileged host - actors; those are meaningfully different scopes. -- **docs/policy/documentation.md:103–105 — absent interfaces and placeholders.** - Use: “Create supporting documents for existing interfaces and responsibilities - when substantive content is available.” This matches the updated adoption rule. -- **docs/policy/documentation.md:128–133 — historical versus current documents.** - Use: “Release notes record history at immutable tags. Maintain current behavior - in its canonical documentation and keep release procedures consistent with - adopted policy.” - -### Testing - -- **docs/policy/testing.md:21 — negative opening followed by positive restatement.** - Keep: “We optimize for sufficient confidence in important behavior while - minimizing friction on future development.” Retain the later substantive - rules governing coverage, test selection, and doubles. -- **docs/policy/testing.md:35–37 — maintenance cost.** - Use: “Keep ordinary internal changes inexpensive. Evaluate maintenance cost - against the specific failure being protected. When omitting a plausible test, - explain the concrete reason. Favor testing consequential, subtle, or - difficult-to-observe behavior.” Preserve the existing examples of valid reasons. -- **docs/policy/testing.md:69,84,96 — contracts and test selection.** - Use: “A package-level contract comprises behavior relied upon by another - package or major collaborator. Add tests when they contribute meaningful - protection against a realistic failure. Choose the narrowest stable boundary - that gives durable confidence.” -- **docs/policy/testing.md:100,111 — implementation details and refactoring.** - Use: “Protect selected decisions, contracts, and invariants. Behavioral tests - should remain stable through internal refactoring that preserves the contract.” -- **docs/policy/testing.md:128,164,171 — duplicated defaults.** - Use: “Derive expectations from test-controlled configuration and relationships. - Assert a production default's literal value when that value is contractual.” - Preserve the contrasting code examples and their conditional rejection scope. -- **docs/policy/testing.md:173,185 — semantic duplication.** - Rename the heading “Assign Each Behavior A Test Owner.” Use: “Give each layer - its distinct responsibility and keep expectation updates localized to the - contract being changed.” Retain representative higher-level workflow coverage. -- **docs/policy/testing.md:206,210–211,221–227 — doubles and Go guidance.** - Use: “Use mocks for contractual interactions. Select techniques according to - behavior and risk. Prefer structured error assertions; assert exact wording - when it is contractual. Size test helpers to the maintenance benefit they - provide.” Preserve golden-file update rules separately. -- **docs/policy/testing.md:231–235 — coverage.** - Use: “Use coverage to locate untested critical branches and unexpectedly weak - packages. Evaluate test quality through meaningful behavioral protection and - choose coverage according to risk.” -- **docs/policy/testing.md:241–247,263 — regression history.** - Use: “Maintain tests according to their continuing protective value. Remove or - consolidate tests when recurrence is impossible, protection is redundant, or a - stronger invariant test subsumes them. Consolidate brittle tests around the - durable requirement they protect.” -- **docs/policy/testing.md:267,281–286 — review and sufficiency.** - Use: “Use these questions when a proposed test needs closer evaluation; written - answers are optional for routine tests.” For the conclusion: “Judge sufficiency - by protection against consequential failures, useful failure signals, and - stability through legitimate internal changes.” Retain ongoing reassessment. - -### Release And OSS - -- **docs/policy/release.md:62–64 — source release versus artifact availability.** - Use: “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.” -- **docs/policy/release.md:99–108 — note format and duplicate summaries.** - Use: “Choose sections suited to the release. Apply the format to new release - notes. Maintain current contracts in their canonical documents. Derive any - annotated-tag summary from the checked-in note.” -- **docs/policy/release.md:117–121 — preparation and ignored files.** - Use: “Handle version selection, notes, and roadmap retirement during - preparation. Reuse ordinary change review for unintended files, credentials, - and private data. Scope release-content review to the tagged source.” -- **docs/policy/release.md:147–150 — repeated validation.** - Use: “Reuse successful validation for the exact final candidate across release - phases. Validate again when that candidate changes. Persistent validation - caches are optional.” Keep the distinction for volatile publication-state checks. -- **docs/policy/oss.md:25,35,69,85,149,172 — short rhetorical contrasts.** - Suggested replacements: “Copy the applicable texts from this reference - collection”; “Determine treatment from the component's terms and actual use”; - “Keep the reference collection upstream”; “Follow the author's selected license - scope”; “Present five fields, using as many lines as their content needs”; and - “Classify material according to its contents.” -- **docs/policy/oss.md:91–94 — copyright assumptions.** - Use: “Use verified project names, contribution years, and copyright holders. - Adapt the example to the author's selected grant.” -- **docs/policy/oss.md:116–137 — attribution structure.** - Use: “The document consists of its title followed directly by component - entries. Limit optional identification prose to factual component and material - scope. Include copyright statements supplied by the selected source. Render - the source field exactly as `[Source](COMMIT_URL).`” Retain precise labels, - punctuation, field order, and omission rules. -- **docs/policy/oss.md:167–176 — notice storage and link destinations.** - Use: “Link standard texts to local copies and project-specific notices to their - upstream copies at the exact imported commit. Make required companion texts - directly reachable from the entry.” -- **docs/oss/licenses/README.md:6–10,43–44,51–53 — collection scope.** - Use: “Select the texts applicable to incorporated material. The project's grant - is stated in COPYRIGHT; each component's grant is identified in its attribution - entry. Record intentional source refreshes here and preserve retrieved texts - verbatim.” Keep automated refresh/release checks explicitly optional if needed. - -## Passages Requiring Careful Equivalence Review - -These are candidates for affirmative wording, but their exclusions encode -important decisions. A shorter positive slogan alone would lose substance. - -| Location | Recommendation and meaning to preserve | -| --- | --- | -| agents.md:23–41,50–53; architecture.md:61–62; testing.md:71–84 | “Ground restrictions in user requirements, explicit repository contracts, or unavoidable correctness constraints. Ground additional guarantees in expressly selected contracts. Preserve operator and caller choice within that scope.” Keep the distinct authorization rules for restrictions and guarantees; implementation details and tests remain insufficient authority to create policy. | -| agents.md:80–87 | Prefer “Preserve unrelated work and leave overlapping work uncommitted with an explanation. Honor commit hooks. Pushing, publishing, amending, resetting, reverting, and rewriting history require separate user authorization.” Keep the explicit exclusions of `git commit -a` and `--no-verify` if an affirmative rendering obscures the exact forbidden commands. | -| release.md:21–25,49–55,127–157,175–177,220–222 | Preserve the successful-push completion point, offline validation, minimal gates, and optional diagnostics. “Complete the command at successful publication” works only if CI waiting, remote read-back, consumer probes, and human confirmations remain clearly outside required completion. Avoid replacing specific boundaries with a generic “keep releases simple.” | -| release.md:181–204 | Immutability, uniqueness, ambiguous-push recovery, and artifact retry conditions are substantive constraints. “Preserve published tags and contents” needs the concrete prohibitions or equivalent exhaustive conditions beside it. | -| oss.md:38–47,79–85,106–111 | Preserve attribution scope, the author's license-selection authority, existing third-party terms, and the absence of extra approval requirements. “Follow the author” alone loses these independent boundaries. | -| oss.md:149–162 | Preserve the bans on invented SPDX identifiers, silent licensing choices, and editorialized notices. The lists of unwanted commentary document observed failures and are useful examples. An affirmative alternative needs an equally precise scope for permitted content and a separate home for interpretation. | -| oss.md:178–187 | The linking house rule is an adopted decision. Keep explicit acceptance of links and the distinction from other obligations; preserve existing source notices. Style editing should leave this interpretation settled. | -| oss.md:223–240; adoption.md:184–187 | Preserve ordinary change-time review and the limits on recurring scans, legal approvals, network checks, and release gates. Preserve the concrete-exception trigger. This audit proposes no new release-time attribution review. | -| documentation.md:65–70,189 | Preserve the prohibition on real secrets and sensitive material, including its intentional-publication qualification. “Use safe examples” is substantially weaker. | -| COPYRIGHT; application/library COPYRIGHT examples | Leave grant scope, attribution permissions, third-party reservations, and warranty disclaimers intact. These are operative licensing statements, not routine prose to normalize mechanically. | - -## Useful Distinctions And Language To Retain - -- **Testing style and boundaries:** choosing real collaborators, doubles, package - APIs, and end-to-end tests involves viable alternatives. Keep explicit tradeoffs - where they help the reader choose. The suite already names classical/Detroit - testing; adding a London-style foil would be unnecessary. -- **testing.md:98 — “Test behavior, not implementation”:** a defensible, useful - distinction. An optional affirmative heading is “Protect Behavioral Contracts,” - provided the surrounding examples retain the distinction. -- **testing.md:120–124 — failing test versus obsolete test:** these lead to - different actions. Preserve the diagnostic distinction and its table. -- **testing.md:131–160 — brittle versus relational concurrency tests:** keep both - examples and the distinction between rejection, queuing, and worker limiting. -- **release.md:62–64 — source versus artifact status:** keep both concepts, even - if the sentences become affirmative. -- **Literal technical conditions:** “never exceeds the configured limit,” “no - more than once,” “no leading zeroes,” offline operation, and credential - independence express exact requirements. Their negative form is useful. -- **Defined terms and factual status:** non-goals, nonstandard licenses, - unmodified text, absent copyright statements, unchanged files, and unresolved - rights questions are meaningful descriptions. They are not stylistic defects. -- **meta.md:** already concise and affirmative; no substantive style changes - recommended. -- **Attribution examples:** already follow the factual House Format. Keep them - free of explanatory audit prose. - -## Implementation Notes - -Apply a selective editorial pass rather than a global replacement. Compare each -rewritten rule's actor, force, scope, exceptions, and timing with the original. -Keep repeated rules synchronized where the adoption guide supplies downstream -wording. Follow the repository's template version/date convention when changing -substantive rules or adoption instructions; preserve verbatim license text. - -The main opportunity is consolidation: keep the affirmative rule and retain an -explicit contrast when it adds a real choice, a precise boundary, or a useful -example of a recurring failure.