Record policy concision audit

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.