feat(preflight): [ STACK WARNINGS ] — flag a check stack absent at the repo root (dogfood F2)

[tigers1997]

What

F2 from the container dogfood. A default Node/pnpm intake on a project whose manifest lives in a subdir or behind Docker 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.

Change

New check_stack_reality() preflight + BINARY_TO_MANIFEST (mirrors manifest_for() in stop-run-checks.sh). It maps each configured check command's (typecheck/lint/test) first binary — through the shlex-guarded extract_first_binaries — to its stack manifest and warns when that manifest is missing at the repo root, naming the subdir for monorepos. Rendered as a [ STACK WARNINGS ] block alongside the existing preflights. Warning-only; silent when the stack matches root or no command maps to a known manifest.

Container note is host-PATH-gated (review advisory A1): it fires only when a warned binary is absent from the host PATH (toolchain genuinely in the container). A monorepo whose docker-compose.yml only backs services (host pnpm present) gets the actionable subdir warning but not a false "hooks will no-op" note.

Also hardens the pre-existing extract_first_binaries: shlex.split is now guarded against ValueError (an unbalanced quote in a cmd_* field used to crash the configurator with a traceback). check_stack_reality reuses it rather than duplicating the extraction loop (review advisory A2).

Tests

test/cc-manifest/test-stack-reality-preflight.sh — matched-silent, unmappable-silent, monorepo-names-subdir, container-note-when-toolchain-off-host, container-note-suppressed-when-on-host (via an injected which), absent-everywhere, install-only-silent, malformed-quote-safe. Plus a malformed-quote case in test-check-commands-extracted.sh. configure.py --check clean; 103/103 fixtures; 5/5 persona snapshots; module-combo smoke; dry-run repro of the [ STACK WARNINGS ] block.

Scope

Split out of #87 per CONTRIBUTING.md ("one logical change per PR") — this is the feat/minor half; F1 (SessionStart matcher) is #88. No tested_up_to / CC_VERSION bump.

🤖 Generated with Claude Code

[claude]

VERDICT: COMMENT-ONLY

PR adds check_stack_reality() — a warning-only preflight that maps each configured check command's first binary to its stack manifest (new BINARY_TO_MANIFEST) and warns when that manifest is absent from the project root. This is the exact condition that makes stop-run-checks.sh's skip rule 3 silently self-disable. Also hardens extract_first_binaries against ValueError from shlex.split. Tests are comprehensive (8 cases) and wired into CI under test/cc-manifest/. CHANGELOG entry present. No blocking issues found.

Blocking

None.

Advisory

A1 — shutil.which('./gradlew') always returns None; container note fires spuriously

configure.py, check_stack_reality (container-note block, ~line 1069)

shutil.which does not search PATH for names containing a path separator. When the name is ./gradlew, CPython falls back to os.access('./gradlew', mode) — a check against the process CWD, not target_dir. Two consequences:

1. If cc-configure is invoked with --dir /project from /home/user, which('./gradlew') returns None regardless of whether the wrapper exists in target_dir.
2. Even from the project root, ./gradlew is a project-local wrapper file, not a PATH binary. The which() heuristic ("binary absent from PATH implies container toolchain") is semantically wrong for it.

Effect: any project using ./gradlew test with a missing root build.gradle and any docker-compose.yml/Dockerfile receives the container note even when Gradle is installed locally. The primary stack warning ("no build.gradle at root") remains correct; only the appended container note is a false positive.

Suggested fix: exclude relative-path entries from the which() check:

path_bins = {b for b in warned_bins if '/' not in b}
if warnings and path_bins and any(which(b) is None for b in path_bins):

A2 — redundant import shutil inside function body

configure.py, check_stack_reality, ~line 1016

shutil is already imported at module top-level (line 22). The if which is None: import shutil block is a no-op. Simplify to:

if which is None:
    which = shutil.which