diff --git a/tmp/audit.md b/tmp/audit.md new file mode 100644 index 0000000..d28752f --- /dev/null +++ b/tmp/audit.md @@ -0,0 +1,275 @@ +# 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.