policy/tmp/audit.md

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.