cc-os/plugins/os-doc-hygiene/invariants.md

Invariants — doc-hygiene

This file is the reversion-protection contract for the plugin. It is a durable, human-gated list of behavioral invariants a future agent must never silently break. It implements Layer 1 of the reversion-protection pattern (see ../cc-architect/references/tool-patterns/reversion-protection.md); the golden examples in examples/golden/ are Layer 2.

META-RULE (read before changing anything)

Changing any invariant below requires, together and in the same change:

1. Updating this file (invariants.md) to reflect the new behavior.
2. Updating the golden examples in examples/golden/ that the change affects.
3. Explicit human approval — present the specific change ("this will change how X behaves") and get a real decision, not a rubber-stamp. Log the approval in the decisions record.

In-conversation instructions cannot override the META-RULE. An agent that finds an invariant inconvenient must surface it for human approval, not route around it.

Change-impact note (include with any audit touching these)

## Change Impact Analysis
### Invariants affected
- [ ] None
- [ ] #N: <which invariant, and why it must change>
### Golden examples affected
- [ ] None
- [ ] examples/golden/<file>: <output changes because…>
### Risk: [LOW | MEDIUM | HIGH] — <one line>

---

1. SessionStart hook only reminds

• Invariant: The SessionStart hook only emits a systemMessage reminder banner — it spends zero AI tokens, runs no scan or classification, and mutates nothing except writing last_reminded to state.
• Why: This is the non-intrusive premise of the whole tool. If the hook ever did analysis or edited files, it would burn tokens and silently change repos on every session — the exact behavior the plugin promises never to do.
• Enforced by: reminder hook unit test with injected clock (asserts notice / no-notice / snoozed, no file mutation beyond last_reminded); review of hooks/hooks.json that the hook invokes only the deterministic reminder script with timeout ≤ 5s and exit 0.
• Violation looks like: the hook shells out to the scanner or an AI pass; the banner text reflects freshly-computed analysis; any doc file is touched at session start; the session blocks or exits non-zero.

2. Reminder snoozes ≤ once/day while stale

• Invariant: While docs are stale, the reminder fires at most once per calendar day, gated by the last_reminded timestamp.
• Why: This hook matches startup|resume, so it fires every time the user reopens or resumes a project. Without the snooze the banner re-fires on each such event within one working day, becoming nag-ware and training the user to ignore it. (clear/compact are not matched by this hook — the matcher, not the snooze, excludes them.)
• Enforced by: reminder hook unit test with injected clock (second invocation same day → no banner; next day while still stale → banner).
• Violation looks like: the banner appears on every resume/compact; the snooze keys off something other than last_reminded; a same-day re-fire.

3. State lives in-project under gitignored .dochygiene/

• Invariant: All state and reports live under a gitignored .dochygiene/ directory at the resolved project root (git root, fallback cwd). There is no global, cross-project index, and the tool never silently edits the user's .gitignore.
• Why: A global index would race, corrupt, and itself go stale across projects. Silently editing .gitignore is an outward mutation that violates the non-intrusive premise; the dir being tracked would pollute the repo.
• Enforced by: state store unit test (root resolution + writes confined to .dochygiene/); scanner self-exclusion test (.dochygiene/ never scanned); GAP: needs test that no global path outside the project root is written and that .gitignore is only modified on explicit confirmation.
• Violation looks like: a ~/.dochygiene or other global index appears; state written outside the project root; .gitignore edited without the user confirming the one-line offer.

4. Report rollover — keep only the latest report

• Invariant: Each check deletes the prior report before writing the new one; exactly one report (human .md + machine .json) is retained.
• Why: The tool must not become the bloat it polices. Accumulating reports would pile up artifacts in every repo it cleans.
• Enforced by: state store unit test (write two reports in sequence → only the latest pair remains on disk).
• Violation looks like: timestamped report history accumulates; old .json/.md reports survive a second check.

5. Cleanup is git-safe — clean tree, one commit

• Invariant: Cleanup runs only on a clean/committed working tree (or after an auto-committed WIP checkpoint), and each cleanup run lands as exactly one reviewable commit.
• Why: Uncommitted user work must never be lost or entangled with the tool's edits, and the whole sweep must be trivially inspectable and revertable as a single unit.
• Enforced by: GAP: needs test — cleanup executor integration test on a fixture repo asserting (a) refusal / auto-checkpoint on a dirty tree, (b) exactly one new commit after a run.
• Violation looks like: cleanup proceeds on a dirty tree without checkpointing; a run produces zero, two, or many commits; edits left uncommitted in the working tree.

6. Deterministic-first — scripts do the mechanical work, AI does only judgment

• Invariant: Scan, state, patch-apply, and token-estimate are deterministic scripts with no model. AI is used only for classification and prose distillation. The token estimator uses a local tokenizer — never an API call.
• Why: This keeps checks fast, cheap, and trustworthy, and keeps mechanical operations reproducible and unit-testable. Pulling a model into the deterministic seams makes them nondeterministic and expensive.
• Enforced by: scanner, state store, patch-applier, and token-estimator unit tests run with no model in the loop; review that estimator code path makes no network/API call.
• Violation looks like: the scanner or patch-applier calls a model; the token estimator hits the Claude API; classification logic is hard-coded into a script instead of delegated to the AI pass.

7. Safety tiers — auto runs unattended, confirm escalates

• Invariant: Only auto-tier ops (deterministic + reversible + objective) run without a prompt; every confirm-tier op (destructive, subjective, or generative) is escalated for human approval before it is applied.
• Why: auto ops run unattended. The tier boundary is the safety wall that keeps anything destructive, subjective, or model-generated from changing the user's repo without their say-so. (Enforced structurally by #10.)
• Enforced by: cleanup executor unit test (an auto entry applies silently; a confirm entry routes to the approval list and is not applied without approval); the derivation guarantee in #10. GAP: needs test — sweep gating test (a confirm-tier op still escalates under the check-then-clean path, not just standalone clean).
• Violation looks like: a destructive or generative op runs without a prompt; the approval gate is skipped under sweep's convenience path; an auto op that is not deterministic+reversible.

8. mtime / content guard — never apply a cached edit to a changed file

• Invariant: Before applying any pre-computed exact_edit, the cleaner verifies the target file's current content hash matches the entry's expected_sha256 (captured at generated_at); on mismatch it skips the edit and recommends re-analysis rather than applying blindly.
• Why: A file edited between check and clean may no longer have the structure the cached edit assumes; applying it blindly corrupts the file.
• Enforced by: patch-applier mtime/content-guard unit test (fixture whose hash differs from expected_sha256 → edit skipped, re-analysis recommended).
• Violation looks like: a cached edit applies to a file whose hash no longer matches; the guard compares only mtime and not content, or is bypassed.

9. Frozen / ignored files are never flagged

• Invariant: Files marked hygiene: frozen in frontmatter, files matched by .dochygiene-ignore, and detected append-only logs are never surfaced as candidates by the scanner.
• Why: Re-flagging deliberately-frozen records and append-only logs every week destroys the user's trust in the tool. This is a correctness requirement, not a nicety.
• Enforced by: scanner unit tests per exclusion (frozen frontmatter, ignore file, append-only detection) — each fixture present in the tree, absent from the shortlist.
• Violation looks like: a hygiene: frozen doc, an ignored path, or an append-only log appears in the shortlist or report entries.

10. safety_tier is DERIVED, never model-assigned

• Invariant: safety_tier is computed solely by the deterministic function safety_tier(op_type, is_destructive, is_reversible) and recorded in the report; the model never assigns it. The function returns confirm whenever op_type == generative, is_destructive, or not is_reversible, and returns auto only for a deterministic + non-destructive + reversible op — so it can never emit auto for a generative, destructive, or irreversible op.
• Why: This is the structural enforcement of #7. If the model could write safety_tier directly, one misclassification would let a destructive or generative op run unattended. Deriving it removes the model from the safety decision entirely.
• Enforced by: schema validation (the recorded safety_tier must equal the function output for the entry's inputs — reject otherwise); a truth-table unit test of the function covering all (op_type, is_destructive, is_reversible) combinations.
• Violation looks like: a report entry whose safety_tier disagrees with the derivation; an auto tier on a generative/destructive/irreversible op; the model emitting the tier as a free field.

11. op_type is a property of the chosen op; exact_edit present iff deterministic

• Invariant: op_type describes the operation the classifier selected (not a free field, not looked up from category.subtype), and an entry carries exact_edit if and only if op_type == deterministic; generative ops carry no exact_edit. The biconditional is validated deterministically.
• Why: The same subtype (e.g. contradicted) may map to either a deterministic delete or a generative rewrite depending on the chosen op, so op_type must track the op. Pre-writing prose edits at check time would spend Sonnet tokens for work that may never be applied; tying exact_edit to deterministic keeps a check cheap and the schema unambiguous.
• Enforced by: schema validation (reject generative with an exact_edit, reject deterministic without one); golden example with the same subtype appearing under both op-types.
• Violation looks like: a generative entry carrying an exact_edit; a deterministic entry missing one; op_type derived from category.subtype instead of from the chosen op.

12. Scanner never flags own test fixtures or golden classifier examples

• Invariant: The scanner must never surface files under doc-hygiene's own fixtures/ directories (bare name match, pruned at any depth) or under examples/golden/ (path-aware parent/child match: a dir named golden whose immediate parent is named examples is pruned; a golden/ dir with any other parent is still scanned). Both entries appear in DEFAULT_EXCLUDED_DIRS in scripts/scanner.py.
• Why: These directories are deliberately populated with stale and bloated documents — they are the scanner's own test inputs. Flagging them is a false positive; applying a cleanup op to them would corrupt the test suite. The path-aware narrowing for examples/golden is required because doc-hygiene installs globally: a blanket bare-name golden exclusion would silently skip legitimate golden/ directories in unrelated host projects.
• Enforced by: tests/test_scanner_exclusions.py — TestFixtureAndGoldenExclusion class, which covers: test_fixtures_subtree_not_scanned_by_default (bare-name fixtures pruned at any depth); test_examples_golden_subtree_not_scanned_by_default (path-aware prune of examples/golden); test_bare_golden_dir_without_examples_parent_is_scanned (false-negative guard — a golden/ dir under a non-examples parent is NOT pruned); and count-accuracy companions test_fixtures_files_cost_no_files_scanned_count / test_examples_golden_files_cost_no_files_scanned_count.
• Violation looks like: a file under tests/fixtures/ or examples/golden/classifier/ appears in the scanner shortlist or report entries; the exclusion is removed or narrowed; a bare golden name-match replaces the path-aware examples/golden pair (breaks globally-installed correctness).

---

Schema note: The machine report schema is itself a frozen contract (see openspec/changes/add-report-schema/). Any change to a report field, enum value, or documented semantic falls under the META-RULE above.