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.