diff --git a/docs/memory-system/05-implementation-process.md b/docs/memory-system/05-implementation-process.md index 6652b16..e5aa9ad 100644 --- a/docs/memory-system/05-implementation-process.md +++ b/docs/memory-system/05-implementation-process.md @@ -1,3 +1,6 @@ +--- +hygiene: frozen +--- # Implementation Process _Last updated: 2026-07-02_ | _Status: Steps 2a/2b/2d executed — toolchain installed, context fix applied, vault graph built; model selected (qwen2.5-coder:7b); Step 2c (reference set) previously complete. Step 2 fully executed._ diff --git a/plugins/os-doc-hygiene/HANDOFF-add-deterministic-core.md b/plugins/os-doc-hygiene/HANDOFF-add-deterministic-core.md deleted file mode 100644 index 165dae0..0000000 --- a/plugins/os-doc-hygiene/HANDOFF-add-deterministic-core.md +++ /dev/null @@ -1,57 +0,0 @@ -# Handoff — `add-deterministic-core` apply (paused at build-spike gate) - -**Status: 15 / 25 tasks complete.** Resume with `/opsx:apply add-deterministic-core`. -Nothing below is blocked on code — it is blocked on one human visual check. - -## Where we are - -| Group | Tasks | State | -|---|---|---| -| 1 — build-spike (SessionStart banner) | 1.1 ✓ · 1.2 ⛔ gate · 1.3 ⛔ | **AWAITING VISUAL CONFIRMATION** | -| 2 — scanner (`doc-scanner`) | 2.1–2.6 ✓ | done — `scripts/scanner.py`, 56 tests pass | -| 3 — state store (`state-store`) | 3.1–3.8 ✓ | done — `scripts/state_store.py`, 30 tests pass | -| 4 — reminder hook (`session-reminder`) | 4.1–4.4 | NOT STARTED — needs Group 3 + confirmed hook format (1.3) | -| 5 — cross-seam verification | 5.1–5.4 | NOT STARTED — run last; 5.3 writes `scripts/CONTEXT.md`, 5.4 is `openspec validate --strict` | - -## THE GATE (task 1.2) — do this first on resume - -Task 1.2 requires a human to start a real Claude Code session and **visually confirm** the spike banner renders. Everything downstream (1.3 → Group 4 → Group 5) is gated on it. The enable path is ALREADY fully set up — do NOT re-derive it: - -- The plugin `doc-hygiene@cc-plugins` is **already installed, enabled, and cached**. (`enabledPlugins."doc-hygiene@cc-plugins": true` in `~/.claude/settings.json`; marketplace registered under `extraKnownMarketplaces.cc-plugins` → directory `/home/jared/dev/cc-plugins`.) -- There is **no `/install` slash command** in this build (v2.1.181) — plugin management is the `claude plugin ...` CLI, already run. -- CC loads hooks from the cache snapshot `~/.claude/plugins/cache/cc-plugins/doc-hygiene/0.0.1/hooks/hooks.json`, which is **byte-identical to source**. If `hooks/hooks.json` is edited later, run `claude plugin update doc-hygiene@cc-plugins` to re-snapshot before testing. -- The `systemMessage` banner mechanism is **proven** in this build — memsearch's SessionStart banner renders the same way. - -**To confirm:** start a fresh Claude Code session (any directory; plugin is user-scoped) and look for, alongside the memsearch line: - - [doc-hygiene] Documentation health reminder is active. Run /os-doc-hygiene:check to scan for stale or bloated docs. - -- **Renders** → check task 1.2, then do task 1.3 (record the confirmed format: plugin-root `hooks/hooks.json`, top-level `hooks` key, per-matcher nested `hooks` array, `systemMessage` field, `matcher: startup|resume`, `timeout: 5`). Then build Group 4, then Group 5. -- **Blank** → the hooks.json format or loading is wrong for this build; debug BEFORE Group 4 inherits the format. (Format currently mirrors the canonical corrected shape from commit `4d595a9`, avoiding the 3 prior hook-format bugs.) - -## Group 4 build notes (when unblocked) - -- 4.1: `Reminder` decision PURE over `(last_check, last_reminded, now, threshold)` per design D5 — silent when fresh; banner when stale and not snoozed; snooze keyed on **calendar day** via `last_reminded`. -- 4.2: reminder script reads state via the Group 3 `StateStore` (already built) with an injected clock; on banner emit `systemMessage` naming the slash command + write `last_reminded = now`; on silent write nothing; always exit 0; missing/unreadable state = never-checked (stale). No scan, no model (invariant #1). -- 4.3: update `hooks/hooks.json` to invoke the reminder script (reuse confirmed format from 1.3), `timeout` ≤ 5s. This REPLACES the spike's fixed banner. -- 4.4: tests with injected clock (invariants #1, #2): fresh→silent; stale+never→banner; stale+reminded-same-day→silent; stale+reminded-prior-day→banner; assert only `last_reminded` mutated, only on banner. -- Build Group 4 with **Sonnet** (real systems Python), not Haiku. - -## Open decision for the user (flag, not yet resolved) - -Scanner deviation (tasks 2.2/2.3): the implementer read design **D7** as placing *append-only* in the **exclusion pipeline only**, NOT as a per-path signal (an append-only file is excluded before signals run, so an `append_only_growth` signal would be self-contradictory). The dead signal was removed. The spec's signal list mentioned "append-only growth" only as an illustrative "for example." **Confirm this reading is acceptable**, or restore append-only as a signal. - -## Conventions for the resuming session - -- Orchestrator-subagent pattern (project CLAUDE.md): delegate via Agent tool; do NOT call Read/Write/Bash/Grep/Glob/Edit directly. Model routing: scripts=no model (author with Sonnet for real logic), classification=Sonnet, orchestration=Opus. -- Each parallel agent owns disjoint files; serialize `tasks.md` checkbox edits in the orchestrator to avoid write races. -- Do NOT push commits. Do NOT commit `map-driven-planning/docs/`. -- Changing any invariant requires `invariants.md` + golden-examples update + explicit human META-RULE approval. (Known pre-existing: `invariants.md` #2 "Why" prose still has stale `clear`/`compact` wording — behavior is correct; prose fix is META-RULE-gated and untouched.) - -## Files created this session -- `hooks/hooks.json` (spike banner) -- `scripts/scanner.py`, `scripts/state_store.py` -- `tests/test_scanner_exclusions.py`, `tests/test_scanner_signals.py`, `tests/test_state_store.py` -- `tests/fixtures/scanner/...`, `tests/fixtures/state_store/...` -- `.claude-plugin/marketplace.json` (parent repo — doc-hygiene registration) -- `openspec/changes/add-deterministic-core/tasks.md` (15 boxes checked)