Record policy language style audit

tmp/audit.md

@@ -0,0 +1,283 @@
+# 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.