cc-os/plugins/os-doc-hygiene/openspec/changes/add-deterministic-core/design.md

Design: Deterministic Core

Context

The report schema (build step #1) is frozen in openspec/specs/report-schema/. This change builds the deterministic substrate beneath it: the three zero-model runtime components that must exist before the AI check pass can run. Per CLAUDE.md build order item 2, those are the reminder hook, the scanner, and the state store.

Constraints that shape this design:

• Invariant #6 (deterministic-first): none of these seams may invoke a model. Everything here is scripts with structured JSON output, correct exit codes, and injected clock/filesystem for testability.
• Invariant #1: the SessionStart hook only reminds — no scan, no classification, no mutation except writing last_reminded.
• Invariant #2: the reminder snoozes to at most once per calendar day while stale.
• Invariant #3: state lives in-project under gitignored .dochygiene/; no global index; never silently edit .gitignore.
• Invariant #4: report rollover keeps only the latest .json + .md pair.
• Invariant #9: frozen/ignored/append-only files are never shortlisted.
• No CC-hook precedent: no plugin in this collection has wired a Claude Code hook. The systemMessage-banner mechanism was confirmed against the hook docs when the PRD was finalized, but it has never been exercised here — hence the build-spike gate.

The scanner's output is not the machine report. The frozen schema places signals on entries, and entries are AI-produced. The scanner emits an intermediate artifact (shortlist + per-path signals); the check change folds that into report.shortlist and entries[].signals.

Goals / Non-Goals

Goals:

• Wire and prove the SessionStart → systemMessage banner path (build-spike).
• A deterministic reminder script: staleness comparison, once/day snooze, zero tokens, mutate only last_reminded, injected-clock testable.
• A deterministic scanner: shortlist + per-path signals, full exclusion pipeline, no model, intermediate artifact (not a report).
• A deterministic state store: project-root resolution, lifecycle timestamps, atomic writes, report rollover, write confinement, no global index, no silent .gitignore edits.
• Each seam unit-testable in isolation with injected clock and filesystem.

Non-Goals:

• The AI classify pass / check skill, entries, op/op_type/safety_tier.
• token_estimate / raw_tokens population (owned by check; see proposal).
• The .gitignore ignore-entry offer UX (owned by check). This change only guarantees the store never silently edits .gitignore.
• The clean skill, patch-applier, mtime-guard application, and sweep.
• Per-project scope-config overrides beyond the documented defaults (the schema records scope_globs/excluded_dirs; richer override UX is later).

Decisions

D1. Three capabilities, one per deterministic seam

session-reminder, doc-scanner, state-store map one-to-one onto the three runtime components, each with its own independently-testable seam (injected-clock snooze; exclusion pipeline; root-resolution + rollover + atomic-write). A single monolithic capability would couple three unrelated concerns and blur which requirement each test pins. Alternative considered: one deterministic-core capability — rejected because the test seams and invariants are disjoint and would read as an unfocused requirement pile.

D2. Build-spike is a sequential gate, not a capability

The spike proves the SessionStart → systemMessage mechanism with a hardcoded banner before any logic depends on it. The hook-wiring it proves belongs under session-reminder (the capability that owns the hook). It is a task-level gate: nothing else in this change starts until the spike renders visibly in a real session. The "confirmed to render visibly" criterion is an implementation-time acceptance criterion discharged when the executor runs it — not at artifact-authoring time. Alternative considered: fold the spike into the reminder hook task — rejected because building snooze/staleness logic atop an unproven mechanism would conflate a mechanism failure with a logic bug.

D3. Injected clock and filesystem on every seam

Each component takes a Clock (returns "now") and a filesystem/root abstraction by constructor injection. Tests pass a frozen clock and a temp dir; production passes the real clock and resolved root. This makes the snooze, staleness, and rollover behaviors deterministic under test with no real time and no real session. Alternative considered: read datetime.now() and os.getcwd() inline — rejected: untestable snooze/staleness, the exact behaviors invariants #1/#2 demand proof of.

D4. Project-root resolution: git root, fallback cwd

resolve_project_root(start_dir):
    walk upward from start_dir looking for a `.git` directory
    if found:  return that directory          # git root
    else:      return start_dir                # fallback: cwd

Resolution is deterministic and pure given start_dir and the filesystem. All state and reports live under <project_root>/.dochygiene/. Writes are confined to that directory (invariant #3); no path outside the resolved root is ever written. Alternative considered: an env var or marker file for the root — rejected as per-project setup, against US-27 (works without setup beyond enablement).

D5. Snooze and staleness logic (reminder)

The reminder is a pure decision over (last_check, last_reminded, now, threshold):

remind?(state, now, threshold_days):
    stale     = last_check is None OR (now - last_check) > threshold_days
    if not stale:                         return SILENT          # fresh: no banner
    if last_reminded is None:             return BANNER          # never reminded
    if same_calendar_day(last_reminded, now): return SILENT      # snoozed today
    return BANNER                                                # stale, new day

On BANNER the script writes last_reminded = now (the only mutation) and emits the systemMessage. On SILENT it writes nothing. Snooze keys on calendar day, not a 24h sliding window — invariant #2 says "once per calendar day," and a sliding window would let two banners straddle midnight-adjacent sessions. The snooze is load-bearing because the hook fires on every matched startup/resume event; without it, reopening or resuming a project several times in one working day re-fires the banner each time. (The matcher is startup|resume, so clear/ compact do not trigger the hook at all — the matcher, not the snooze, handles those; the snooze handles repeated startup/resume within a calendar day.) The script exits 0 always (never blocks the session) with a low timeout (≤5s) in hooks.json. Alternative considered: snooze on a rolling 24h delta — rejected per the calendar-day wording and the midnight edge case.

D6. Reminder never scans (invariant #1)

The reminder script reads only state.json. It does not import or invoke the scanner, reads no doc content, and computes the banner purely from timestamps. The banner text is fixed prose plus the day-count and the slash command — it reflects no freshly-computed analysis. This is what keeps the hook zero-token and side-effect-free beyond last_reminded.

D7. Scanner exclusion pipeline (ordered, short-circuiting)

The scanner walks files matching the scope globs, then applies exclusions so a file that matches any exclusion never reaches the shortlist (invariant #9):

for each candidate path under project_root:
  1. dir-prune:      skip if any path component is in excluded_dirs
                     (build, vendor, archive, graphify-out, .dochygiene)  # self-exclusion here
  2. ignore-match:   skip if matched by a .dochygiene-ignore pattern
  3. frozen-frontmatter: skip if YAML frontmatter has `hygiene: frozen`
  4. append-only:    skip if detected as an append-only log
  → otherwise: compute signals, add (path, signals) to the intermediate artifact

Dir-pruning happens first and at the directory level so excluded trees are never descended (cheap, and self-excludes .dochygiene/ before any state file is read as a doc). Exclusion precedes signal computation so excluded files cost nothing. Append-only detection is heuristic and deterministic (e.g. monotonic dated/ sectioned growth with no in-place edits across git history, or a documented append-only marker) — the exact heuristic is an implementation detail, but it must be deterministic and unit-tested with a positive and a negative fixture. Alternative considered: compute signals first then filter — rejected: wastes work and risks an excluded file leaking into output if a later filter is missed.

D8. Scanner emits an intermediate artifact, not a report

The scanner's output is { shortlist: [path...], signals: { path: [signal...] } } (or an equivalent intermediate shape) — paths plus their objective signals. It does not write a machine report, entries, category, op, or token_estimate. The check change reads this artifact and produces the report. Keeping the scanner output intermediate honors the frozen schema's split (scanner → shortlist; AI → entries with signals) and keeps this change from re-deriving the report shape. Signals are objective facts only (the schema's "objective scanner facts that support the classification"); the scanner attaches no judgment.

D9. Atomic writes (state store)

Every write to state.json and to report files is write-temp-then-rename: write to a temp file in the same directory, fsync, then os.replace onto the target. os.replace is atomic on POSIX, so a concurrent reader (e.g. a second session's reminder) sees either the old or the new file, never a torn write. Alternative considered: in-place truncate-and-write — rejected: a crash mid-write corrupts state, and the reminder reads state on every session.

D10. Report rollover (state store)

write_report(json_blob, md_blob):
    delete any existing *.json and *.md report in .dochygiene/   # keep latest only
    atomically write the new .json and .md pair

Exactly one report pair survives each write (invariant #4) — the tool must not become the bloat it polices. Rollover deletes the prior pair before writing the new one. (Report content generation is owned by check; the store only owns the rollover-and-atomic-write mechanics, exposed for check to call.) Alternative considered: timestamped report history — rejected by invariant #4.

D11. State store never silently edits .gitignore

The store creates .dochygiene/ (allowed — an untracked, not-yet-ignored dir is fine; invariant #3 forbids editing .gitignore, not creating the dir) and confines all writes to it. It never opens or appends to .gitignore. Detecting whether .dochygiene/ is ignored and offering to add the entry is a check-change concern (US-4 / PRD "State & artifacts"), explicitly out of scope here.

Risks / Trade-offs

• [The systemMessage banner doesn't render or the hook entry format is wrong for this collection] → The build-spike gate exists precisely for this: a hardcoded-banner spike is run and visually confirmed before any logic is built on it. If the spike fails, only the spike is reworked, not the reminder logic.
• [Append-only detection is heuristic — false negatives re-flag a log, false positives hide a real doc] → Deterministic heuristic pinned by positive and negative unit fixtures; .dochygiene-ignore and hygiene: frozen give the user explicit overrides for any heuristic miss (invariant #9 has three independent exclusion paths, so no single heuristic is the only guard).
• [Calendar-day snooze across timezones] → Snooze compares calendar days in a single, documented timezone (the injected clock's). Tests pin the boundary (same-day → silent, next-day-while-stale → banner). Acceptable for a motivational reminder; not a correctness-critical clock.
• [Cleared-file audit gap] → A shortlisted file the AI later clears loses its scanner signals (they live on entries, which a cleared file lacks). This is a frozen-schema decision (see report-schema design "Why scanner signals live only on entries"), inherited here, not introduced. The scanner's intermediate artifact does hold per-path signals; whether check persists cleared-file signals is its call.
• [Reminder reads state on every session — a corrupt state.json could block] → Atomic writes (D9) prevent torn state; the reminder treats a missing/unreadable state as "never checked" (stale) and exits 0 regardless, never blocking the session (invariant #1).

Migration Plan

Additive only — no existing behavior changes (no code exists yet). Deploy order is the task order: spike gate first, then scanner ∥ state-store in parallel, then the reminder hook (which depends on the state store for last_reminded). Rollback is removing hooks/hooks.json and the new scripts; nothing else consumes them yet.

Open Questions

• Staleness threshold default (days before the reminder fires) — a constant for this change; the value is an implementation detail, not a spec'd contract. Per-project override is a later concern.
• Exact append-only heuristic — left to implementation, constrained only to be deterministic and fixture-tested (positive + negative).