Close the discipline seams + context economics (review findings 1–3, 5) — 0.4.0/0.5.0

.claude/skills/clauderizer-cascade/SKILL.md

@@ -8,9 +8,8 @@ description: After changing a tracked entity (subsystem, feature, decision, inva
 Cascade is **post-hoc and judgment-based**: it finds what *might* be affected; you decide what actually is.
 
 1. `cz_cascade(entity_id, transition)` — walks the Project DAG forward and writes a report listing direct + transitive dependents, each marked "needs review".
-2. Open each flagged dependent. Decide: affected or not?
-   - If affected: make the edit, then note it under "Updates applied".
-   - If not: note "no change needed".
-3. Resolve every "needs review" marker before the session ends — a report with unresolved markers shows up as a pending cascade in `cz_status` and fails the `cascade_hygiene` pre-flight check.
+2. Open each flagged dependent. Decide: affected or not? If affected, make the edit.
+3. Record every verdict with `cz_resolve_cascade(verdicts={...}, updates_applied=...)` — verdicts maps each entity id to what you did ("no change needed", "updated pin to ^2.0.0", …) and updates_applied summarizes the concrete edits. Never hand-edit the report.
+4. Resolve every "needs review" marker before the session ends — a report with unresolved markers shows up as a pending cascade in `cz_status` and fails the `cascade_hygiene` pre-flight check.
 
 Status transitions already trigger cascade via `cz_transition_status`; use this skill for manual triggers or to finish reconciling a report.

.claude/skills/clauderizer-close-gameplan/SKILL.md

@@ -6,7 +6,13 @@ description: Close out a completed (or explicitly deferred) gameplan. Use when a
 # Close a gameplan
 
 1. Confirm every phase is complete or explicitly deferred (`cz_status`).
-2. Run a full cascade pass; resolve any pending reports.
-3. Update project-level docs (CHANGELOG, ARCHITECTURE, REQUIREMENTS) to reflect final state.
-4. Write a `POST-MORTEM.md` in the gameplan dir: what worked, what didn't (with root causes), and concrete improvements to the procedure. This is where the system itself gets better.
-5. Leave the gameplan directory on disk (nothing is deleted) and clear/replace `active_gameplan` in `.clauderizer/config.toml`.
+2. Run a full cascade pass; resolve any pending reports with `cz_resolve_cascade`.
+3. **Curate the lessons** — this is where memory earns its keep:
+   - `cz_promote_lesson` the few that should outlive this gameplan (they land in
+     `docs/LESSONS.md` and ride in every future handoff, across gameplans).
+     Promotion is a chance to distill: pass `text` to tighten the wording.
+   - `cz_consolidate_lessons` overlapping ones first, then promote the synthesis.
+   - The rest stay archived with the closed gameplan — promote deliberately, not in bulk.
+4. Update project-level docs (CHANGELOG, ARCHITECTURE, REQUIREMENTS) to reflect final state.
+5. Write a `POST-MORTEM.md` in the gameplan dir: what worked, what didn't (with root causes), and concrete improvements to the procedure. This is where the system itself gets better.
+6. Leave the gameplan directory on disk (nothing is deleted) and clear/replace `active_gameplan` in `.clauderizer/config.toml`.

.claude/skills/clauderizer-do-phase/SKILL.md

@@ -9,8 +9,8 @@ description: Execute or continue the current gameplan phase end-to-end — pre-f
 2. Call `cz_preflight`. If any enabled check fails, STOP and report — do not write code.
 3. Execute the phase tasks. Honor every rule in `CLAUDE.md` and the accumulated lessons.
 4. Closing protocol:
-   - Record outcomes: `cz_add_correction` for any divergence; `cz_add_lesson` for anything generalizable.
+   - Record outcomes: `cz_add_correction` for any divergence; `cz_add_lesson` for anything generalizable; `cz_obsolete_lesson` for lessons this phase made irrelevant; if the lessons list is repeating itself, `cz_consolidate_lessons`.
    - For each subsystem/feature whose state changed, `cz_transition_status` (this fires cascade automatically when enabled).
-   - For any other tracked edit, run `cz_cascade` and fill in the report's "needs review" verdicts.
+   - For any other tracked edit, run `cz_cascade`, then record the verdicts with `cz_resolve_cascade` (never hand-edit the report).
    - `cz_write_handoff` for the next phase.
    - Run exit verification (the host test/build commands) and report the final count.

.claude/skills/clauderizer-record/SKILL.md

@@ -10,6 +10,7 @@ Route the capture to the correct tool so the graph stays consistent — never ha
 - **A decision** ("we decided X because Y") → `cz_add_decision` (project-wide ADR, or scope `gameplan` for tactics).
 - **A rule that must always hold** → `cz_add_invariant`.
 - **A reusable lesson** → `cz_add_lesson` (pick a category; it rolls into every future handoff).
+- **A lesson that no longer applies** → `cz_obsolete_lesson` (marks it; the log keeps the line, handoffs stop carrying it).
 - **A divergence from the plan** → `cz_add_correction` (optionally promote a `lesson` in the same call).
-- **A persistent risk** → record under `docs/HARDENING.md` (append-only; never delete entries).
+- **A persistent risk / audit finding** → `cz_add_finding`; resolve later with `cz_resolve_finding` (append-only; never delete entries).
 - **A new subsystem/feature/external service** → `cz_upsert_entity`.

.clauderizer/config.toml

@@ -2,6 +2,7 @@
 version = "1"
 size = "standard"
 preflight_checks = ["branch_base", "clean_tree", "tests", "build", "deps_spotcheck", "branch_creation", "cascade_hygiene"]
+preflight_advisory = []
 
 [host]
 profile = "python"
@@ -19,4 +20,4 @@ cascade = true
 amendments = false
 
 [active_gameplan]
-id = "2026-05-30-clauderizer-v1-bootstrap"
+id = "2026-06-09-context-economics"

.clauderizer/profile.lock.toml

@@ -1,10 +1,12 @@
 profile = "python"
 
 [commands]
-test = "pytest -q"
+# pyproject addopts already pass -q; doubling it (-qq) suppresses the
+# "N passed" summary line that baseline_test_regex needs to parse.
+test = "pytest"
 build = ""
 lint = "ruff check ."
 typecheck = "mypy ."
 
 [preflight]
-baseline_test_regex = "(\d+) passed"
+baseline_test_regex = "(\\d+) passed"

CHANGELOG.md

@@ -2,6 +2,77 @@
 
 All notable changes to Clauderizer are documented here.
 
+## [0.5.0] — 2026-06-09
+
+Closes review finding 5 (**context economics**): cumulative memory grew
+monotonically — handoffs carried every lesson forever, lessons died with their
+gameplan at close, and nothing measured the bundle. Per ADR D-009 the answer is
+consolidation *pressure*, never caps: three blessed writes plus visibility, with
+the audit trail intact.
+
+### Added
+- **`cz_consolidate_lessons`** — synthesize N overlapping lessons into one; each
+  source is marked `(obsolete: consolidated into #N)` and every future handoff
+  carries one line instead of many. All sources validated before anything is
+  written.
+- **`cz_promote_lesson`** — promote an enduring lesson into a compact,
+  on-demand `docs/LESSONS.md` as an `L-NN` entry with provenance; the source is
+  marked `(promoted <date>: L-NN)` and stops rolling up individually. Handoffs
+  gain a "Project Lessons (distilled)" section that rides **across gameplans** —
+  lessons finally outlive the gameplan that learned them.
+- **Memory gauge** — `cz_status` / the SessionStart digest report
+  `Memory: N active lessons, M project (~K tok handoff)` and nudge toward
+  consolidate/promote/obsolete past `ACTIVE_LESSONS_WARN` (12, a documented
+  constant). Bloat is a visible state, not a silent failure mode.
+- `cz_obsolete_lesson` accepts `L-NN` ids, so the project list is curated with
+  the same rules (its `number` parameter is now a string).
+- Close-gameplan skill: a lesson-curation step (consolidate, then promote
+  deliberately — not in bulk); do-phase nudges consolidation when the list
+  repeats itself.
+
+## [0.4.0] — 2026-06-09
+
+Closes the **discipline seams** from the 2026-06-09 external review: the places
+where the workflow still depended on agents hand-editing tracked docs because
+the blessed write was missing, destructive, or never ran.
+
+### Added
+- **`cz_resolve_cascade`** — record per-dependent verdicts + the Updates
+  applied/deferred sections on a cascade report. Previously, clearing the
+  `cascade_hygiene` preflight check *required* a forbidden hand-edit — the rules
+  banned the only way to make progress. Defaults to the latest pending report;
+  partial resolution keeps it pending (`status_bundle.pending_cascades` is now
+  the public, shared predicate).
+- **`cz_obsolete_lesson`** — mark an accumulated lesson `(obsolete <date>: <reason>)`
+  through a tool. The line stays in the log (append-only memory); handoff roll-ups
+  stop carrying it, so cumulative handoffs can shrink without a hand-edit.
+- **Baseline write-back** — a green `cz_preflight` run that measures a test count
+  now refreshes the active gameplan's "Current baseline test count" line
+  (anti-pattern #7, stale references, applied to the system itself: this repo's
+  own hook said "0 tests" while 84 passed).
+- **Completed-gameplan status** — a gameplan whose phases are all complete now
+  reports "all N phase(s) COMPLETE" with close-out guidance instead of the
+  confusing "no in-progress or ready phase found".
+- **`doctor`: lock-file check** — flags a `profile.lock.toml` that doesn't parse
+  (whose overrides were being silently ignored).
+
+### Changed
+- **Marker-protected handoffs (D-008)** — `cz_write_handoff` owns only a
+  `<!-- clauderizer:handoff -->` marker block; regeneration replaces the block and
+  preserves everything outside it byte-for-byte. Fresh handoffs add an agent-owned
+  "Phase Notes" scaffold; legacy generated skeletons are migrated wholesale;
+  unrecognized files are preserved verbatim below the block. `cz_next_phase_context`
+  returns the merged view, so a context fetch includes on-disk enrichment.
+- Skills no longer instruct hand-edits anywhere: cascade/do-phase route through
+  `cz_resolve_cascade`, record routes risks through `cz_add_finding`.
+
+### Fixed
+- **`Profile.to_lock_toml` emitted invalid TOML** for profiles whose baseline
+  regex contains backslashes (e.g. python's `(\d+) passed`) — and since
+  `load_for_repo` falls back silently on parse errors, every python-profile lock
+  written by `init` was being ignored in its entirety. Lock values are now
+  TOML-escaped, with a round-trip regression test across all packaged profiles.
+
 ## [0.3.0] — 2026-06-05
 
 Fixes the **state-mutation surface** — the gaps a second dogfooding session found

CLAUDE.md

@@ -13,10 +13,15 @@ into context automatically — no manual reading order. To refresh on demand, ca
 - `cz_status` / `cz_next_phase_context` — where things stand; the next phase bundle.
 - `cz_graph_query` — look up an entity and its dependents/dependencies.
 - `cz_preflight` — run the pre-flight checks (tests/build via the host profile).
-- `cz_cascade` — after a tracked edit, walk dependents and write a cascade report.
-- `cz_write_handoff` — assemble the next cumulative phase handoff.
+- `cz_cascade` / `cz_resolve_cascade` — after a tracked edit, walk dependents,
+  then record the verdicts (never hand-edit the report).
+- `cz_write_handoff` — assemble the next cumulative phase handoff (your notes
+  outside its marker block survive regeneration).
 - `cz_add_decision` / `cz_add_invariant` / `cz_add_lesson` / `cz_add_correction`
   / `cz_upsert_entity` / `cz_transition_status` — structured, graph-aware writes.
+- `cz_consolidate_lessons` / `cz_promote_lesson` / `cz_obsolete_lesson` — keep
+  memory compact: synthesize overlap, promote the enduring to `docs/LESSONS.md`,
+  mark the stale.
 
 **Rules**: never hand-edit frontmatter or append to tracked logs directly — use the
 `cz_*` tools so the graph stays consistent. The procedure spec is at

README.md

@@ -250,6 +250,11 @@ setup is worse than no check).
   assembled from one canonical list, so phase N+3 never repeats a mistake phase N already solved.
 - **Append-only memory** — decisions, invariants, hardening findings, incidents, corrections,
   and lessons are never deleted, only superseded. A permanent audit trail.
+- **Consolidation pressure, not caps** — cumulative memory could otherwise crowd out the
+  context window it serves. Overlapping lessons get synthesized (`cz_consolidate_lessons`),
+  enduring ones promoted to a compact `docs/LESSONS.md` that rides in every future handoff
+  across gameplans (`cz_promote_lesson`), and the status digest carries a memory gauge that
+  warns when the active-lesson count crosses the line. Nothing is ever auto-deleted.
 
 ## CLI
 
@@ -265,9 +270,10 @@ clauderize mcp               # launch the MCP server (stdio)
 ## MCP surface
 
 **Read** · `cz_status` · `cz_next_phase_context` · `cz_graph_query`
-**Rituals** · `cz_preflight` · `cz_cascade` · `cz_write_handoff`
+**Rituals** · `cz_preflight` · `cz_cascade` · `cz_resolve_cascade` · `cz_write_handoff`
 **Mutations** · `cz_create_gameplan` · `cz_add_phase` · `cz_transition_phase` · `cz_add_amendment`
 · `cz_add_decision` · `cz_add_invariant` · `cz_add_finding` · `cz_resolve_finding` · `cz_add_lesson`
+· `cz_obsolete_lesson` · `cz_consolidate_lessons` · `cz_promote_lesson`
 · `cz_add_correction` · `cz_upsert_entity` · `cz_transition_status`
 **Resources** · `clauderizer://status` · `clauderizer://procedure` · `clauderizer://entity/{id}`
 

docs/DECISIONS.md

@@ -48,3 +48,15 @@ _(Add entries with `cz_add_decision`.)_
 **Context**: Edits must stay valid and idempotent.
 **Decision**: Every structured write routes through markdown/writer.py.
 **Consequences**: No tool does a free-form replace.
+
+### D-008 — Engine-regenerated regions in shared docs are marker-delimited
+
+**Context**: cz_write_handoff regenerates PHASE-N-HANDOFF.md by overwriting the whole file, destroying agent enrichment; meanwhile init already merges the CLAUDE.md stanza through marker blocks without clobbering user text.
+**Decision**: Any engine-regenerated content inside a document that agents or humans may also edit is delimited by <!-- clauderizer:NAME:start/end --> markers and rewritten via writer.upsert_marker_block. Regeneration replaces only the block; everything outside is preserved byte-for-byte.
+**Consequences**: Handoffs become safely enrichable; the CLAUDE.md stanza and handoffs now follow one pattern; future generated regions (e.g. status digests embedded in docs) inherit it.
+
+### D-009 — Cumulative memory gets consolidation pressure, not caps
+
+**Context**: Finding 5: append-only memory + cumulative handoffs grow monotonically; the only pruning was the (obsolete) marker, with nothing driving it and no cross-gameplan continuity for lessons.
+**Decision**: Memory stays append-only — no caps, no auto-deletion, no LRU. Counter-pressure is three blessed writes plus visibility: cz_consolidate_lessons (N->1 within a gameplan), cz_promote_lesson (gameplan lesson -> compact project docs/LESSONS.md carried by all future handoffs), and a memory gauge in the status digest that warns past a documented threshold and names the remedies.
+**Consequences**: Handoffs can shrink without losing the audit trail; lessons survive gameplan close through deliberate curation rather than bulk carryover; bloat is a visible, nudged state instead of a silent failure mode.

docs/LESSONS.md

@@ -0,0 +1,24 @@
+# Distilled Lessons
+
+> Project-level lessons promoted from gameplans (`cz_promote_lesson`).
+> Every future handoff carries this list, so it must stay compact: obsolete
+> entries that stop earning their place (`cz_obsolete_lesson` with the `L-NN`
+> id). Entries are never deleted, only marked.
+
+## Lessons
+
+### Category: Process
+
+**L-01.** Markdown round-trip idempotency (apply-twice == apply-once) is the load-bearing test for every mutation. *(from 2026-05-30-clauderizer-v1-bootstrap)*
+
+### Category: Observability
+
+**L-02.** Health checks must verify capability, not just presence — a green check on a non-launchable setup is worse than no check. *(from 2026-05-30-clauderizer-v1-bootstrap)*
+
+### Category: Design
+
+**L-03.** Name tools by their effect: a context fetch must never mutate the tree. *(from 2026-05-30-clauderizer-v1-bootstrap)*
+
+### Category: Integration
+
+**L-04.** Every file the engine writes must round-trip through its own parser in tests; never swallow config parse errors silently. *(from 2026-06-09-discipline-seams)*

docs/gameplans/2026-05-30-clauderizer-v1-bootstrap/CHAT-HANDOFF-INDEX.md

@@ -13,7 +13,7 @@ then calls `cz_next_phase_context` for the active phase. No manual reading order
 
 Run `cz_preflight` before any code. If any enabled check fails: STOP, report.
 
-**Current baseline test count**: 0
+**Current baseline test count**: 84
 
 ## Ending Protocol
 
@@ -42,7 +42,7 @@ obsolete items — mark with "(obsolete)" rather than deleting.)_
 
 ### Category: Process
 
-**3.** Markdown round-trip idempotency (apply-twice==apply-once) is the load-bearing test for every mutation.
+**3.** Markdown round-trip idempotency (apply-twice==apply-once) is the load-bearing test for every mutation. (promoted 2026-06-09: L-01)
 
 **4.** Make init idempotent via marker blocks, key-scoped JSON merges, and exists-checks — never clobber user content.
 
@@ -58,7 +58,7 @@ obsolete items — mark with "(obsolete)" rather than deleting.)_
 
 ### Category: Observability
 
-**6.** Health checks must verify capability, not just presence: `doctor` now probes that the MCP/hook command is actually executable — a green check on a non-launchable setup is worse than no check.
+**6.** Health checks must verify capability, not just presence: `doctor` now probes that the MCP/hook command is actually executable — a green check on a non-launchable setup is worse than no check. (promoted 2026-06-09: L-02)
 
 **11.** Hook failures must surface where the agent can see them: the SessionStart hook now prints errors to stdout (session context), never silently to stderr.
 
@@ -72,4 +72,4 @@ obsolete items — mark with "(obsolete)" rather than deleting.)_
 
 ### Category: Design
 
-**10.** Name tools by their effect: a 'context fetch' must not mutate the tree. cz_next_phase_context now assembles the handoff in-memory (write=False) and only cz_write_handoff persists.
+**10.** Name tools by their effect: a 'context fetch' must not mutate the tree. cz_next_phase_context now assembles the handoff in-memory (write=False) and only cz_write_handoff persists. (promoted 2026-06-09: L-03)

docs/gameplans/2026-06-09-context-economics/CHAT-HANDOFF-INDEX.md

@@ -0,0 +1,49 @@
+# Chat Handoff Index — Context Economics
+
+> Last updated: 2026-06-09
+> Status: Phase 0 ready
+
+## How This Works
+
+This is the coordination point for sessions executing this gameplan. A fresh
+session gets current state automatically from the Clauderizer SessionStart hook,
+then calls `cz_next_phase_context` for the active phase. No manual reading order.
+
+## Pre-Flight Verification
+
+Run `cz_preflight` before any code. If any enabled check fails: STOP, report.
+
+**Current baseline test count**: 109
+
+## Ending Protocol
+
+1. Update PHASE-STATUS.md (status + outputs + corrections).
+2. `cz_add_lesson` for anything new.
+3. `cz_transition_status` on touched entities (fires cascade).
+4. `cz_write_handoff` for the next phase.
+5. Run exit verification; report the test count.
+
+## Phase Status Table
+
+| Phase | Name | Status | Started | Completed | Handoff |
+|-------|------|--------|---------|-----------|---------|
+| 0 | Lesson consolidation | ✅ COMPLETE | 2026-06-09 | 2026-06-09 | handoffs/PHASE-0-HANDOFF.md |
+
+**Status legend**: ⬜ NOT STARTED · 🟢 READY · 🟡 IN PROGRESS · ✅ COMPLETE · ⚠️ BLOCKED · 🔴 FAILED
+
+| 1 | Lesson promotion & project LESSONS.md | ✅ COMPLETE | 2026-06-09 | 2026-06-09 | handoffs/PHASE-1-HANDOFF.md |
+
+| 2 | Memory gauge | ✅ COMPLETE | 2026-06-09 | 2026-06-09 | handoffs/PHASE-2-HANDOFF.md |
+
+## Per-Phase Completion Summaries
+
+_(None yet.)_
+
+## Accumulated Lessons
+
+_(Numbered sequentially across the whole gameplan. Categorized. Pruned of
+obsolete items — mark with "(obsolete)" rather than deleting.)_
+
+### Category: Process
+
+_(none yet)_