fix: container/monorepo dogfood hardening — SessionStart freeze-loss (F1) + [ STACK WARNINGS ] preflight (F2)

[tigers1997]

Why

Dogfooding cc-configure into a containerized project (Python + FastAPI backend + Vite frontend, both via Docker; no root package.json) surfaced two issues. The local review verdict was "safe to commit" — true — but the configurator silently under-delivered, and one shipped hook had a latent freeze-loss bug.

F1 — fix(commands): SessionStart marker-clear freeze-loss

The microbit-enforcer SessionStart marker-clear shipped with no matcher, so it fired on every SessionStart source (startup, resume, clear, compact). That silently wiped .claude/.frozen / .guarded / .careful on --resume and after compaction — i.e. mid-session, exactly when a long session most needs a /freeze to hold. Now "matcher": "startup|clear" (source set confirmed against code.claude.com/docs/en/hooks-guide): markers clear only on a brand-new session or /clear, and persist across resume/compaction.

F2 — feat(preflight): [ STACK WARNINGS ]

A default Node/pnpm intake on a containerized/monorepo project produces check commands (pnpm typecheck/lint/test) that stop-run-checks.sh silently skips (skip rule 3: no package.json at root) — the whole Stop-loop self-disables with zero feedback. New check_stack_reality() (+ BINARY_TO_MANIFEST, mirroring manifest_for() in stop-run-checks.sh) warns at configure time when a configured check command's manifest is missing at root, names the subdir for monorepos (frontend/package.json), and notes when a docker-compose.yml/Dockerfile means the host-side hooks will no-op. Warning-only; never blocks; silent when the stack matches root or no command maps to a known manifest (bare tsc/pytest/ruff).

Verification

• configure.py --check ✓ · 104/104 fixtures ✓ · 5/5 persona snapshots ✓ · module-combo smoke ✓
• Reproduced the dogfood scenario end-to-end: containerized layout (frontend/package.json + docker-compose.yml, no root manifest) → both warnings render; silent with a root package.json.

Scope

No tested_up_to / CC_VERSION bump (no-lone-bumps). F3 — container-aware execution (point check/format commands at docker compose exec <svc>) — is intentionally deferred as a separate design item.

Files

• templates/commands/microbit-enforcer/settings-patch.json — matcher + comment
• configure.py — BINARY_TO_MANIFEST, check_stack_reality(), [ STACK WARNINGS ] render
• templates/core/CLAUDE.md, examples/python-uv-fastapi/{CLAUDE.md,.claude/settings.json} — doc/example sync
• test/microbit-enforcer/test-sessionstart-matcher.sh, test/cc-manifest/test-stack-reality-preflight.sh
• CHANGELOG.md

🤖 Generated with Claude Code

[claude]

VERDICT: BLOCK

PR adds the `startup|clear` matcher to the microbit-enforcer SessionStart hook (F1) and a new `check_stack_reality()` preflight (F2). The matcher fix is correct and the preflight design is sound, but two blocking issues need to land before merge.

Blocking

B1 — `shlex.split` unguarded in `check_stack_reality` — crashes the configurator on any cmd value with an unclosed quote

`configure.py:1015` — `shlex.split(val)` is called bare inside the loop over all six `cmd_*` form fields. `shlex.split` raises `ValueError: No closing quotation` on input like `pnpm test --grep 'foo` (a common copy-paste mistake). There is no `try/except` around the call and no outer catch in `main()` at the call site (configure.py:2710). The `except OSError` at line 1028 covers only `iterdir()`. One bad form field turns a preflight warning into a full configurator crash with a raw traceback.

Fix: `try: parts = shlex.split(val)\nexcept ValueError: parts = val.strip().split()` (or `continue` on bad input). The pre-existing `extract_first_binaries()` (~line 984) has the same gap; worth fixing in the same pass.

B2 — Four user-facing files still describe the old (now-wrong) marker lifecycle

The PR's core fix is that freeze/guard/careful markers survive `--resume` and compaction, clearing only on `startup|clear`. `templates/core/CLAUDE.md` was correctly softened to "transient session state" — but four other shipped files were not updated and now contradict the behavior this PR introduces:

• `templates/commands/freeze/SKILL.md:37-39` — "Frozen state does not persist across Claude Code session restarts: the `SessionStart` hook clears all microbit markers." This is now the opposite of the truth.
• `templates/commands/guard/SKILL.md:41-43` — "The configurator clears `.guarded` on session start (SessionStart hook)."
• `templates/commands/careful/SKILL.md:45` — "Careful patterns persist for the session, cleared on session start."
• `templates/commands/microbit-enforcer/microbit-enforcer.sh:14-16` — "a SessionStart hook clears all three files. Markers are session-scoped, not persistent."

A user reading `freeze/SKILL.md` will expect their freeze to be gone after a resume; the fix makes it survive. The model loading these skill files mid-session will reason about the wrong lifecycle. These are shipped templates, so the stale text reaches every project that installs the microbit commands.

Advisory

A1 — `check_stack_reality` warning text blames `stop-run-checks.sh` for commands it never runs

`configure.py:1012-1013` iterates all six `cmd_*` keys including `cmd_install`, `cmd_build`, `cmd_dev`. When any of those triggers a manifest-missing warning, lines 1044-1047 tell the user "stop-run-checks.sh runs from the root and will silently skip these" — but `stop-run-checks.sh:51-55` only contains the three check commands (typecheck/lint/test). A user with `pip install -r requirements.txt` in `cmd_install` and no `pyproject.toml` gets a warning blaming the Stop hook, which would never run `pip` at all. The dim footer at `configure.py:2716` repeats the false attribution. Recommend either narrowing the scan to the three stop-hook keys or adjusting the warning text (and footer) to name the correct hooks that actually run `cmd_install`/`cmd_build`/`cmd_dev`.

[claude]

VERDICT: COMMENT-ONLY

PR adds two well-contained dogfood fixes: F1 scopes the microbit-enforcer SessionStart hook to startup|clear so freeze/guard/careful markers survive --resume and compaction; F2 adds a [ STACK WARNINGS ] preflight that catches a check-command stack whose manifest lives in a subdir or container rather than the repo root. Both fixes include targeted tests and the CHANGELOG entries are present and correct.

Blocking

None.

Advisory

examples/python-uv-fastapi/.claude/skills/{freeze,guard,careful}/SKILL.md — stale lifecycle language contradicts the F1 fix

The three template files were updated with the new nuance (markers survive --resume/compaction, cleared only on startup or /clear), but the corresponding generated copies inside examples/python-uv-fastapi/ were not regenerated. They still carry the old text:

• examples/python-uv-fastapi/.claude/skills/freeze/SKILL.md: "Frozen state does not persist across Claude Code session restarts: the SessionStart hook clears all microbit markers (.frozen / .guarded / .careful)."
• examples/python-uv-fastapi/.claude/skills/guard/SKILL.md: "The configurator clears .guarded on session start (SessionStart hook)." — no resume/compact nuance.
• examples/python-uv-fastapi/.claude/skills/careful/SKILL.md: "Careful patterns persist for the session, cleared on session start." — ditto.

examples/python-uv-fastapi/EXAMPLE_README.md documents that the example is regenerated by running python3 configure.py --config examples/python-uv-fastapi/.claude-config.json --dir examples/python-uv-fastapi. Running that and committing the three skill-file diffs would fix this in one shot.

[claude]

VERDICT: BLOCK

[claude]

VERDICT: BLOCK

Blocking

B1 — Scope creep: two independent changes in one PR

CONTRIBUTING.md:43 states: "One logical change per PR. Reviewers (human and AI) struggle with mixed-purpose PRs; merge friction goes up; rollback gets messy."

This PR bundles:

• F1 — a fix (patch-tier): adds "matcher": "startup|clear" to templates/commands/microbit-enforcer/settings-patch.json + doc updates. Runtime hook behavior correction; touches only JSON + markdown.
• F2 — a feat (minor-tier): adds BINARY_TO_MANIFEST + check_stack_reality() (~90 lines of Python) + new test files to configure.py. New configure-time preflight warning; touches Python, tests, CI-wired test fixtures.

No files are shared between F1 and F2. They have different Conventional Commit types, different semver implications, and independent rollback surfaces. Recommend splitting into two PRs.

---

Advisory

A1 — Container note fires false-positive for monorepo + incidental compose file

configure.py:1062 — The container note is appended whenever if warnings: (any manifest-mismatch warning) AND a compose/Dockerfile is present at root. This misfires for a common layout: pnpm configured with frontend/package.json (monorepo subdir) and a docker-compose.yml present only for backing services (Postgres, Redis, etc.) — the host-side toolchain works perfectly fine. The user gets warning #1 ("found in frontend/, cd frontend && ...", which is actionable) plus warning #2 ("hooks will no-op — point cmd_* at docker compose exec"), which is incorrect: the hooks will run because pnpm is on the host.

The container note is appropriate only when the manifest is absent everywhere (the else branch at ~line 1056). Restrict it:

• Track whether any "absent everywhere" case was hit (a boolean flag in the loop).
• Gate the container note on that flag rather than if warnings:.

A2 — check_stack_reality() duplicates extract_first_binaries() extraction loop

configure.py:1016–1025 — The 10-line bins = set() loop in check_stack_reality() is a reinvention of extract_first_binaries(). The two functions share the same key set (cmd_typecheck, cmd_lint, cmd_test) and the same shlex-fallback logic. If a new key is added to extract_first_binaries() in the future, check_stack_reality() silently misses it. Suggest replacing the loop with a call to extract_first_binaries() and taking .values(). This also eliminates the redundant import shlex inside check_stack_reality().

[tigers1997]

Superseded by a split per CONTRIBUTING.md ("one logical change per PR") — the round-3 review correctly flagged this as a mixed fix+feat bundle.

• fix(commands): scope microbit-enforcer SessionStart marker-clear to startup|clear (dogfood F1) #88 — fix(commands): SessionStart marker-clear matcher (F1)
• feat(preflight): [ STACK WARNINGS ] — flag a check stack absent at the repo root (dogfood F2) #89 — feat(preflight): [ STACK WARNINGS ] stack-reality check (F2), incorporating review advisories A1 (host-PATH-gated container note) + A2 (reuse extract_first_binaries)

Closing this one.