cleargate 0.14.0 → 0.15.0

package/dist/lib/ledger.cjs

@@ -117,4 +117,3 @@ function sumDeltas(rows) {
 0 && (module.exports = {
   sumDeltas
 });
-//# sourceMappingURL=ledger.cjs.map

package/dist/lib/ledger.js

@@ -3,7 +3,7 @@ import { createRequire as __cgCreateRequire } from "module";
 const require = __cgCreateRequire(import.meta.url);
 import {
   init_esm_shims
-} from "../chunk-BTSZOEWC.js";
+} from "../chunk-P6KEDAK2.js";
 
 // src/lib/ledger.ts
 init_esm_shims();
@@ -99,4 +99,3 @@ function sumDeltas(rows) {
 export {
   sumDeltas
 };
-//# sourceMappingURL=ledger.js.map

package/dist/lib/lifecycle-reconcile.cjs

@@ -888,4 +888,3 @@ function reconcileCurrentSprintStories(opts) {
   rollUpParentStatus,
   walkActiveParents
 });
-//# sourceMappingURL=lifecycle-reconcile.cjs.map

package/dist/lib/lifecycle-reconcile.js

@@ -12,8 +12,8 @@ import {
   reconcileLifecycle,
   rollUpParentStatus,
   walkActiveParents
-} from "../chunk-5DI2Z3C2.js";
-import "../chunk-BTSZOEWC.js";
+} from "../chunk-Y53ZZYYU.js";
+import "../chunk-P6KEDAK2.js";
 export {
   ARTIFACT_TERMINAL_STATUSES,
   VERB_STATUS_MAP,
@@ -26,4 +26,3 @@ export {
   rollUpParentStatus,
   walkActiveParents
 };
-//# sourceMappingURL=lifecycle-reconcile.js.map

package/dist/{whoami-EANGN46Z.js → whoami-JKQQPABQ.js}

@@ -8,11 +8,11 @@ import {
   getMembershipState,
   loadConfig,
   requireMcpUrl
-} from "./chunk-PDE37WFQ.js";
-import "./chunk-E3X7IE5E.js";
+} from "./chunk-A7MSQUU7.js";
+import "./chunk-PY6FHGV5.js";
 import {
   init_esm_shims
-} from "./chunk-BTSZOEWC.js";
+} from "./chunk-P6KEDAK2.js";
 
 // src/commands/whoami.ts
 init_esm_shims();
@@ -80,4 +80,3 @@ async function whoamiHandler(opts) {
 export {
   whoamiHandler
 };
-//# sourceMappingURL=whoami-EANGN46Z.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cleargate",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "private": false,
   "type": "module",
   "description": "Planning framework for Claude Code agents — sprint/epic/story protocol, five-role agent team (architect/developer/qa/devops/reporter), Karpathy-style awareness wiki.",
@@ -44,10 +44,11 @@
   },
   "scripts": {
     "prebuild": "tsx scripts/build-manifest.ts && node scripts/copy-planning-payload.mjs",
-    "build": "tsup",
+    "build": "rm -rf dist && tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "test": "tsx --test --test-concurrency=1 --experimental-test-module-mocks --test-reporter=spec 'test/**/*.node.test.ts' '!test/fixtures/**'",
+    "test": "node scripts/run-default-tests.mjs '!test/**/*.integration.node.test.ts' '!test/fixtures/**'",
+    "test:integration": "tsx --test --test-concurrency=1 --experimental-test-module-mocks --test-reporter=spec 'test/**/*.integration.node.test.ts'",
     "test:file": "tsx --test --test-concurrency=1 --experimental-test-module-mocks --test-reporter=spec",
     "test:node": "tsx --test --test-concurrency=1 --experimental-test-module-mocks --test-reporter=spec 'test/**/*.node.test.ts' '!test/fixtures/**'",
     "test:node:file": "tsx --test --test-concurrency=1 --experimental-test-module-mocks --test-reporter=spec",

package/templates/cleargate-planning/.claude/agents/architect.md

@@ -107,16 +107,18 @@ These rules apply under `execution_mode: v2`. Under v1 the Design Review is info
 
 ## Mode: TPV (Test Pattern Validation)
 
-Dispatched between QA-Red and Developer for standard-lane stories under v2 (fast lane skips). Dispatched only when the `pre_gate_runner.sh` wiring scan flags a problem — a clean scan (exit 0, no flags) skips the live TPV dispatch and proceeds directly to §C.4 Developer. You receive: story file, QA-Red commit SHA, list of `*.red.node.test.ts` files. You verify ONLY:
+Dispatched between QA-Red and Developer for standard-lane stories under v2 (fast lane skips). Dispatched only when the `pre_gate_runner.sh` wiring scan flags a problem — a clean scan (exit 0, no flags) skips the live TPV dispatch and proceeds directly to §C.4 Developer. You receive: story file, QA-Red commit SHA, list of red-test files (named per `sprint_context.md` §Test Stack). You verify ONLY:
 
 1. All imports resolve to real modules at the cited paths.
 2. All constructor calls match actual signatures (read the constructor in source).
 3. All `t.mock.method()` calls reference methods that exist on the mocked object.
 4. Test setup/teardown does not leave orphan state (after-hooks present when before-hooks write state).
-5. Test files end in `*.red.node.test.ts` (CR-043 immutability naming).
+5. Test files follow the red-test naming declared in `sprint_context.md` §Test Stack.
 
 You DO NOT verify test logic correctness — that is Dev's TDD challenge.
 
+> **Note (CR-081):** Semantic fixture correctness (invalid enum literals, unsatisfiable duplicate-text queries) is caught by the separate `qa_red_lint` pre-gate step (CR-081), NOT by TPV. TPV stays wiring-only — never fold semantic-correctness checks here.
+
 Return:
 - `TPV: APPROVED` — Dev proceeds.
 - `TPV: BLOCKED-WIRING-GAP — <one-sentence specific issue>` — orchestrator routes back to QA-Red; `arch_bounces` increments via `node update_state.mjs <story-id> --arch-bounce`.

package/templates/cleargate-planning/.claude/agents/developer.md

@@ -80,17 +80,11 @@ flashcards_flagged:
 
 ## Inner-loop test runner
 
-All tests use **`node:test` + `node:assert/strict`** — this is the single, mandatory runner across all ClearGate packages (EPIC-028, 2026-05-18). vitest is fully eliminated; adding it back is forbidden and blocked by the `check:no-vitest` pre-commit guard.
+Use the project's test runner and red-test naming as declared in `sprint_context.md` §Test Stack. Run the backend runner (and frontend runner if present) before committing.
 
-**File naming:** `*.node.test.ts` for all new test files.
+**Mocking pattern:** prefer constructor-injected DI seams over module-level mocks. Inject the dependency via the constructor or function parameter and pass a fake in tests. For function-level mocks, use `mock.fn()` / `mock.method()`. For static-import un-interceptability (e.g. toast, clipboard), use the `__overrides__` pattern: a `__mocks__/` stub with a mutable `__overrides__` object that the test sets before each call.
 
-**Run commands per package:**
-- `mcp/` and `cleargate-cli/`: `tsx --test --test-concurrency=1 --experimental-test-module-mocks 'test/**/*.node.test.ts'`
-- `admin/`: `node --conditions browser --import tsx tests/run-tests.mjs` — the `--conditions browser` flag is required; it triggers jsdom-bootstrap via `setup-node-test.mjs` for Svelte component tests.
-
-**Mocking pattern:** prefer constructor-injected DI seams over module-level mocks. Inject the dependency via the constructor or function parameter and pass a fake in tests. For function-level mocks, use `mock.fn()` / `mock.method()` from `node:test`. For static-import un-interceptability in admin/ (e.g. toast, clipboard), use the `__overrides__` pattern: a `__mocks__/` stub with a mutable `__overrides__` object that the test sets before each call — see `admin/TESTING.md` for full pattern description.
-
-**Full-suite verification at commit-time.** Use the project's standard test command (`npm test`, etc.) before committing.
+**Full-suite verification at commit-time.** Use the project's standard test command before committing.
 
 ## Script Invocation
 
@@ -123,8 +117,7 @@ These rules apply under `execution_mode: v2`. Under v1 they are informational.
 
 These files are **immutable** for Developer dispatches. Do not Read, Edit, Write, or stage them:
 
-- `**/*.red.test.ts` — QA-Red-authored test files (vitest naming, legacy)
-- `**/*.red.node.test.ts` — QA-Red-authored test files (node:test naming, SPRINT-22+)
+- QA-Red-authored red-test files (naming per `sprint_context.md` §Test Stack)
 
 These files are written by the QA-Red dispatch (SKILL.md §C.3) and committed to the story branch before Developer spawns. The pre-commit hook (`pre-commit-surface-gate.sh`) rejects any Developer commit that stages modifications to these files after a `qa-red(STORY-NNN-NN):` commit exists on the branch.
 

package/templates/cleargate-planning/.claude/agents/qa.md

@@ -40,16 +40,16 @@ Dispatch prompt contains: `Mode: RED — write failing tests against §4 accepta
 
 In RED mode you:
 1. Read the story's §4 acceptance Gherkin (and ONLY the story file — no implementation source files).
-2. Write failing test files named `*.red.node.test.ts` covering each acceptance scenario.
+2. Write failing test files named as declared in `sprint_context.md` §Test Stack covering each acceptance scenario.
 3. Confirm each test FAILS against the clean baseline (no implementation yet).
 4. Return the `QA-RED:` output shape (see §C.3 in SKILL.md).
 5. **Forbidden:** Read, edit, or reference any implementation file (`.ts` source, not tests).
-6. **Wiring soundness:** Tests must be wiring-sound for Architect TPV approval (SKILL.md §C.3.5). TPV checks: imports resolve, constructor signatures match, mocked methods exist, after-hooks present, file naming `*.red.node.test.ts`. Wiring gap → orchestrator routes back to QA-Red (increments `arch_bounces`, NOT `qa_bounces`).
+6. **Wiring soundness:** Tests must be wiring-sound for Architect TPV approval (SKILL.md §C.3.5). TPV checks: imports resolve, constructor signatures match, mocked methods exist, after-hooks present, file naming as declared in `sprint_context.md` §Test Stack. Wiring gap → orchestrator routes back to QA-Red (increments `arch_bounces`, NOT `qa_bounces`).
 
 Output shape for RED mode:
 ```
 QA-RED: WRITTEN | BLOCKED
-RED_TESTS: <list of *.red.node.test.ts files written>
+RED_TESTS: <list of red-test files written (naming per sprint_context.md §Test Stack)>
 BASELINE_FAIL: <count of failing scenarios>
 flashcards_flagged: [ ... ]
 ```
@@ -95,7 +95,7 @@ Dispatch verification depth by reading `lane.value` from the pack's JSON block (
   - Grep checklist for required strings (heading anchors, schema field names).
   - DoD §2.2 audit (cross-check the story's Gherkin → diff one-to-one).
   - Spec-vs-impl drift table (one row per requirement).
-  - **Skip** typecheck and targeted vitest UNLESS `pack.adjacent.adjacent_test_files` is non-empty AND any of those files are under `cleargate-cli/`, `mcp/`, `cleargate-cli/test/`, or any path with extension `.ts` / `.test.ts` / `.test.sh`.
+  - **Skip** typecheck and targeted test-suite re-run UNLESS `pack.adjacent.adjacent_test_files` is non-empty AND any of those files are under `cleargate-cli/`, `mcp/`, `cleargate-cli/test/`, or any path with extension `.ts` / `.test.ts` / `.test.sh`.
 
 - **`standard` lane** (current default — most stories):
   - Everything in `fast`, PLUS:
@@ -107,7 +107,7 @@ Dispatch verification depth by reading `lane.value` from the pack's JSON block (
 - **`runtime` lane** (NEW — CLI / integration / runtime-surface stories):
   - Everything in `standard`, PLUS:
   - **Full test suite** re-run (not just touched-file scope) — `cleargate gate test` against the full package.
-  - Coverage check: every Gherkin scenario has a passing test (zero MISSING entries).
+  - Coverage check: every Gherkin scenario has a passing test (zero MISSING entries). A red test that now passes against the Developer's commit counts as its own green — no separate green file required (red-now-green, CR-081).
   - **exit-code matrix:** invoke each new/modified command with `--help`, the happy path, and at least one explicit error path; assert exit codes match documented values.
   - **Integration smoke:** if the story changes a script under `.cleargate/scripts/`, run the script's bash test harness from a `mktemp -d` fixture (mirrors test_prep_qa_context.sh pattern at `.cleargate/scripts/test/`).
 
@@ -131,6 +131,7 @@ Verify that a Developer's claim of "done" is real. Approve with `QA: PASS` or re
 4. **Map commit to acceptance criteria.** For each Gherkin scenario in the Story:
    - Find the corresponding test in the diff
    - If no test matches, that's a FAIL with reason `missing test for "<scenario name>"`
+   - **Red-now-green clause (CR-081):** A QA-Red test file that was failing at baseline and now PASSES against the Developer's commit fully satisfies the green-test / acceptance-coverage requirement. Do NOT require a separate green-path file distinct from the now-passing red file — a duplicate is redundant under reuse-over-recreate (Rule 18). Map each Gherkin scenario to the now-passing red test; absence of a second file is NOT a MISSING entry and must not produce a FAIL.
 5. **Check for regressions** — follow the **Lane-Aware Playbook**: on `standard` lane run scoped tests (touched-file neighborhoods); on `runtime` lane run the complete package suite. If anything in scope broke, FAIL.
 6. **Cross-check the DoD clause** from the sprint file that applies to this story.
 7. **Record flashcards on recurring QA failure patterns.** `Skill(flashcard, "record: #qa <lesson>")`. Examples:
@@ -140,7 +141,7 @@ Verify that a Developer's claim of "done" is real. Approve with `QA: PASS` or re
 ## Output shape
 ```
 STORY: STORY-NNN-NN
-QA: PASS | FAIL
+QA: PASS | PASS-PENDING-SMOKE | FAIL
 TYPECHECK: pass | fail
 TESTS: X passed, Y failed, Z skipped (full suite)
 ACCEPTANCE_COVERAGE: N of M Gherkin scenarios have matching tests
@@ -151,6 +152,13 @@ flashcards_flagged:
   - "YYYY-MM-DD · #tag1 #tag2 · lesson ≤120 chars"
 ```
 
+**Verdict decision order (CR-081 × CR-082 composed):**
+1. **(a) Deferred-acceptance check (CR-082):** Does the story declare a `deferred_verification` entry whose heavy acceptance scenario was NOT run in this QA pass (out of static scope)? If yes and every OTHER static scenario passes → return `PASS-PENDING-SMOKE`. The story merges to the sprint branch but is NOT fully Done; the close gate (Step 2.9) enforces the deferred check before sprint-close. `PASS-PENDING-SMOKE` shadows `PASS` when a deferred entry is unrun.
+2. **(b) Full-coverage check (CR-081):** Else, are all Gherkin scenarios covered by passing tests — including red-now-green tests counting as their own green? → return full `PASS`.
+3. **(c)** Else → `FAIL`.
+
+Note: CR-081's red-now-green clause applies to the STATIC scenarios (step b); CR-082's PASS-PENDING-SMOKE is gated on an UNRUN DEFERRED scenario (step a). A story can be red-now-green on its static scenarios AND still be PASS-PENDING-SMOKE because a separate heavy scenario is deferred. The deferred-check (step a) is evaluated BEFORE the full-PASS branch (step b).
+
 `flashcards_flagged` is a YAML list of strings, each matching the `FLASHCARD.md` one-liner format (`YYYY-MM-DD · #tag1 #tag2 · lesson`). Default is `[]` (empty list — omit if no new cards). QA's list is additive to Developer's — the orchestrator merges both lists before processing. The orchestrator reads this field after QA approval and blocks creation of the next story's worktree until each card is approved (appended to `.cleargate/FLASHCARD.md`) or explicitly rejected (reason recorded in sprint §4 Execution Log). See protocol §4.
 
 ## Guardrails

package/templates/cleargate-planning/.claude/hooks/pending-task-sentinel.sh

@@ -51,7 +51,7 @@ mkdir -p "${SPRINT_DIR}"
 TOOL_NAME_EARLY="$(printf '%s' "${INPUT}" | jq -r '.tool_name // empty')"
 
 if [[ "${TOOL_NAME_EARLY}" == "Task" && "${SKIP_FLASHCARD_GATE:-0}" != "1" && "${SPRINT_ID}" != "_off-sprint" ]]; then
-  # Collect flagged cards from all STORY-*-dev.md and STORY-*-qa.md in SPRINT_DIR (flat layout).
+  # Collect flagged cards from all *-dev.md / *-qa.md reports (any id: STORY/CR/BUG/...), flat + reports/ subdir (CR-082 moved reports to reports/).
   UNPROCESSED_CARDS=()
   UNPROCESSED_HASHES=()
 
@@ -59,7 +59,7 @@ if [[ "${TOOL_NAME_EARLY}" == "Task" && "${SKIP_FLASHCARD_GATE:-0}" != "1" && "$
   REPORT_FILES=()
   while IFS= read -r f; do
     REPORT_FILES+=("$f")
-  done < <(ls -t "${SPRINT_DIR}"/STORY-*-dev.md "${SPRINT_DIR}"/STORY-*-qa.md 2>/dev/null)
+  done < <(ls -t "${SPRINT_DIR}"/*-dev.md "${SPRINT_DIR}"/*-qa.md "${SPRINT_DIR}"/reports/*-dev.md "${SPRINT_DIR}"/reports/*-qa.md 2>/dev/null)
 
   for REPORT_FILE in "${REPORT_FILES[@]}"; do
     [[ ! -f "${REPORT_FILE}" ]] && continue

package/templates/cleargate-planning/.claude/skills/sprint-execution/SKILL.md

@@ -149,7 +149,11 @@ Sprint branch is **never committed to directly**. All work lands via story-branc
 node .cleargate/scripts/init_sprint.mjs SPRINT-NN
 ```
 
-This writes `.cleargate/sprint-runs/SPRINT-NN/state.json` and flips `.cleargate/sprint-runs/.active` to `SPRINT-NN`. Without `state.json` the lane router, dispatch hook, and close pipeline all fail.
+This writes `.cleargate/sprint-runs/SPRINT-NN/state.json`, flips `.cleargate/sprint-runs/.active` to `SPRINT-NN` (atomic tmp+rename), and ingests SDR lane assignments so fast-lane stories are stamped correctly without manual reclassification. Without `state.json` the lane router, dispatch hook, and close pipeline all fail.
+
+**Lane ingest (CR-078):** `init_sprint.mjs` reads lane assignments from `<sprintDir>/plans/waves.json` (`lane_assignments: { "STORY-ID": "fast"|"standard" }` top-level key) when the file is present. When `waves.json` is absent it falls back to parsing the Sprint Plan §2.4 Lane Audit table (`| Story-ID | fast | rationale |`). Stories not declared in either source keep the `standard` default. Fast-lane stories receive `lane_assigned_by: 'sdr-lane-audit'`; no manual `cleargate story lane …` reclassification is needed after init.
+
+**`.active` sentinel (CR-078):** `init_sprint.mjs` atomically writes the sprint ID to `.active` as its final step. This is the single place the sentinel is SET at kickoff; `cleargate sprint close` (`sprint.ts`) is the single place it is CLEARED. If a prior `.active` value differs from the sprint being initialised, init emits `WARN: .active was SPRINT-NN, overwriting with SPRINT-MM — prior sprint may not have been closed` to stderr but does not block.
 
 `init_sprint.mjs` also writes `<sprintDir>/sprint-context.md` from `.cleargate/templates/sprint_context.md`, populated with `sprint_id` + goal (extracted from sprint plan §0 `- **Sprint Goal:** …` bullet, or placeholder if absent) + active CR list. Every Dev/QA/Architect/DevOps dispatch reads this file as preflight (see §B + §C contracts + agent prompts `## Preflight`).
 
@@ -255,6 +259,18 @@ git worktree list
 
 **Do not run `git worktree add` inside `mcp/`.** It is a nested git repo. If the story touches `mcp/`, the Developer edits `mcp/` from inside `.worktrees/STORY-NNN-NN/mcp/...` — visible as a subdirectory of the outer worktree. (`cleargate-enforcement.md` §1.3.)
 
+After creating the worktree, provision configured gitignored config into it:
+
+```bash
+bash .cleargate/scripts/provision_worktree_config.sh .worktrees/STORY-NNN-NN
+```
+
+This symlinks (or copies, per `config.yml worktree.provision_mode`) the roots in
+`config.yml worktree.provision_config` (default `[.env]`) so the target's build/tests
+load their config in-worktree without a manual step. The provisioned roots are exempt
+from the `stray_env_files` pre-gate scan — the same configured list serves as both the
+provisioning spec and the scan-exemption list (single source of truth, CR-079).
+
 ### C.3 Spawn QA-Red (standard lane only — fast lane skips this step)
 
 ```bash
@@ -295,6 +311,8 @@ After QA-Red commits Red tests, run the wiring/pre-gate scan first:
 bash .cleargate/scripts/pre_gate_runner.sh arch .worktrees/STORY-NNN-NN/ sprint/S-NN
 ```
 
+**Semantic fixture lint (CR-081 — included in the pre-gate scan above):** `pre_gate_runner.sh arch` automatically invokes `qa_red_lint.mjs` (check #5 inside `run_arch()`) against the worktree's QA-Red test files (`*.red.node.test.ts` and other red-test forms). This is a pre-gate step — it runs as part of the scan, before any TPV or Developer dispatch. If `qa_red_lint` flags a semantic fixture error (R-enum: invalid enum literal; R-query: duplicate-text `queryByText`/`getByText`), the scan exits non-zero and routes back to QA-Red via `arch_bounces` (identical to a TPV wiring gap — increment `arch_bounces` via `node .cleargate/scripts/update_state.mjs STORY-NNN-NN --arch-bounce`, then re-dispatch §C.3 QA-Red with the lint flag description). The lint check is gated by `arch.qa_red_lint` in `gate-checks.json` (default `true`).
+
 **Conditional TPV dispatch (scan-flag gated — a clean standard-lane story proceeds to §C.4 with NO Architect TPV dispatch):**
 
 - **If the scan returns exit 0 with no flags:** skip the live Architect `Mode: TPV` dispatch and proceed directly to §C.4 Spawn Developer. No Architect agent is spawned for TPV on the clean path.

package/templates/cleargate-planning/.cleargate/config.example.yml

@@ -65,3 +65,19 @@
 #   test: "cargo test"
 #   typecheck: "cargo check"
 #   lint: "cargo clippy"
+
+# worktree:
+#   # Gitignored config roots provisioned into each new story worktree (CR-079).
+#   # Each root in this list is symlinked (or copied, per provision_mode) from the
+#   # repo root into the worktree when `provision_worktree_config.sh` is called.
+#   # The same list is exempt from the stray_env_files pre-gate scan so officially-
+#   # provisioned roots do not false-flag. Default: [".env"].
+#   provision_config:
+#     - .env
+#     - .env.local   # example — add any additional gitignored config roots
+#   provision_mode: symlink   # symlink (default) | copy
+#   # symlink: creates absolute symlink worktree-root/<root> -> repo-root/<root>.
+#   #          Symlink stays live with the source .env; trivially torn down with
+#   #          the worktree. Requires target to resolve via absolute path (done
+#   #          automatically by provision_worktree_config.sh).
+#   # copy:    copies the file so the worktree can hold a divergent config.

package/templates/cleargate-planning/.cleargate/scripts/close_sprint.deferred-verify.red.node.test.ts

@@ -0,0 +1,245 @@
+/**
+ * RED test — CR-082: Deferred-Verification Close Gate
+ *
+ * Tests fail against the clean baseline because:
+ *   - close_sprint.mjs has NO Step 2.9 (deferred-verification gate absent)
+ *   - CLEARGATE_FORCE_DEFERRED_VERIFY env seam does not exist yet
+ *   - PASS-PENDING-SMOKE is absent from cleargate-planning/.claude/agents/qa.md
+ *   - deferred_verification field is absent from .cleargate/templates/story.md
+ *
+ * Run (standalone — NOT the cli npm-test suite):
+ *   node --test --import tsx .cleargate/scripts/close_sprint.deferred-verify.red.node.test.ts
+ *
+ * NOTE: On Node ≥25 `--import tsx/esm` triggers ERR_REQUIRE_CYCLE_MODULE (Node v25 stricter
+ * ESM/CJS cycle detection). Use `--import tsx` instead — functionally identical; tsx auto-detects
+ * ESM. The M3 plan specifies `tsx/esm`; this deviation is Node-version-specific and non-breaking.
+ *
+ * Node:test + assert only. No Pydantic Literal, no queryByText/getByText.
+ * qa_red_lint (CR-081, now live) will exit 0 on this file — no R-enum/R-query match.
+ *
+ * Self-isolating: every scenario uses a mktemp tmpdir, bypasses real git/Steps 2.7/2.8
+ * via CLEARGATE_SKIP_WORKTREE_CHECK=1 + CLEARGATE_SKIP_MERGE_CHECK=1.
+ * The real SPRINT-34 .active sentinel + state.json are never touched.
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const CLOSE_SPRINT = path.join(__dirname, 'close_sprint.mjs');
+
+// ── Fixture helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Minimal state.json (schema_version 3) with a single story in Done state.
+ * Uses standard lane only — no fast lane — to avoid v2.1 validation check
+ * which requires a SPRINT-NN_REPORT.md with metric rows/sections.
+ * All required per-story validator fields are present.
+ */
+function makeStateJson(sprintId: string): object {
+  return {
+    schema_version: 3,
+    sprint_id: sprintId,
+    sprint_status: 'Active',
+    stories: {
+      'CR-082': {
+        state: 'Done',
+        lane: 'standard',
+        lane_assigned_by: 'architect',
+        lane_demoted_at: null,
+        lane_demotion_reason: null,
+        qa_bounces: 0,
+        arch_bounces: 0,
+        updated_at: '2026-06-04T00:00:00Z',
+      },
+    },
+    last_action: 'test setup',
+    updated_at: '2026-06-04T00:00:00Z',
+  };
+}
+
+/** Create a tmpdir with a minimal state.json for the given sprint id. */
+function makeTmpSprintDir(sprintId: string): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `cg-cr082-red-${sprintId}-`));
+  fs.writeFileSync(
+    path.join(dir, 'state.json'),
+    JSON.stringify(makeStateJson(sprintId), null, 2) + '\n',
+    'utf8'
+  );
+  return dir;
+}
+
+/**
+ * Base env seams shared by all scenarios.
+ * All non-Step-2.9 gates bypassed so the test isolates Step 2.9 specifically.
+ */
+function baseEnv(sprintDir: string): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    CLEARGATE_SPRINT_DIR: sprintDir,
+    CLEARGATE_REPO_ROOT: REPO_ROOT,
+    CLEARGATE_SKIP_LIFECYCLE_CHECK: '1',  // skip WS8(e) dist assertion + Step 2.6/2.6b
+    CLEARGATE_SKIP_WORKTREE_CHECK: '1',   // skip Step 2.7
+    CLEARGATE_SKIP_MERGE_CHECK: '1',      // skip Step 2.8
+    CLEARGATE_SKIP_PARENT_ROLLUP: '1',    // skip Step 2.6c
+    CLEARGATE_SKIP_SPRINT_TRENDS: '1',    // skip Step 6.5
+    CLEARGATE_SKIP_SKILL_CANDIDATES: '1', // skip Step 6.6
+    CLEARGATE_SKIP_FLASHCARD_CLEANUP: '1',// skip Step 6.7
+    CLEARGATE_SKIP_BUNDLE_CHECK: '1',     // skip Step 3.5
+  };
+}
+
+/**
+ * Run close_sprint.mjs in a subprocess. Returns { exitCode, stdout, stderr }.
+ * Never throws — captures all output even on non-zero exit.
+ * Creates and destroys its own tmpdir automatically.
+ */
+function runClose(
+  sprintId: string,
+  extraEnv: NodeJS.ProcessEnv = {}
+): { exitCode: number; stdout: string; stderr: string } {
+  const sprintDir = makeTmpSprintDir(sprintId);
+  const env = { ...baseEnv(sprintDir), ...extraEnv };
+
+  const result = spawnSync('node', [CLOSE_SPRINT, sprintId, '--assume-ack'], {
+    env,
+    encoding: 'utf8',
+    timeout: 30_000,
+  });
+
+  // Clean up tmpdir regardless of outcome
+  try {
+    fs.rmSync(sprintDir, { recursive: true, force: true });
+  } catch {
+    // cleanup failure is non-fatal in test context
+  }
+
+  return {
+    exitCode: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+// ── Scenario 1: declared + NO result (null) → close BLOCKS ───────────────────
+test('Scenario 1: declared entry with no result → Step 2.9 blocks close (non-zero exit + Step 2.9 message)', () => {
+  const forcedState = JSON.stringify({
+    'STORY-TEST-01': {
+      declared: [{ command: 'docker build .', blocks: 'close' }],
+      result: null,
+    },
+  });
+
+  const { exitCode, stdout, stderr } = runClose('SPRINT-TEST', {
+    CLEARGATE_FORCE_DEFERRED_VERIFY: forcedState,
+  });
+
+  // RED: Step 2.9 is absent. close_sprint.mjs proceeds to Step 3 (prefill_report.mjs)
+  // which fails for unrelated reasons — but the Step 2.9 message is never emitted.
+  // After implementation: exit non-zero + "Step 2.9" message in combined output.
+  assert.notEqual(exitCode, 0,
+    'Expected non-zero exit when a declared deferred verification has no result');
+  const combined = stdout + stderr;
+  assert.match(
+    combined,
+    /Step 2\.9.*fail|deferred.*verif.*fail|STORY-TEST-01.*unrun|unrun.*STORY-TEST-01/i,
+    'Expected a Step 2.9 failure message for STORY-TEST-01 (unrun result); Step 2.9 not yet implemented'
+  );
+});
+
+// ── Scenario 2: declared + green result → gate PASSES ────────────────────────
+test('Scenario 2: declared entry with green result → Step 2.9 passes; close proceeds past 2.9', () => {
+  const forcedState = JSON.stringify({
+    'STORY-TEST-01': {
+      declared: [{ command: 'docker build .', blocks: 'close' }],
+      result: 'green',
+    },
+  });
+
+  const { stdout } = runClose('SPRINT-TEST', {
+    CLEARGATE_FORCE_DEFERRED_VERIFY: forcedState,
+  });
+
+  // RED: Step 2.9 is absent — stdout will never contain "Step 2.9 passed".
+  assert.match(
+    stdout,
+    /Step 2\.9 passed/i,
+    'Expected "Step 2.9 passed" in stdout when all declared verifications are green; Step 2.9 not yet implemented'
+  );
+});
+
+// ── Scenario 3: none declared → silent no-op (THE SPRINT-34-own-close case) ──
+test('Scenario 3: no deferred_verification declarations → Step 2.9 silent no-op, close proceeds', () => {
+  // No CLEARGATE_FORCE_DEFERRED_VERIFY injected — Step 2.9 should scan story files,
+  // find none with deferred_verification declarations, print the no-op line, and continue.
+  // This is the load-bearing regression: if this fails post-implementation,
+  // CR-082's own close gate would block SPRINT-34's close (sprint-ending defect).
+  const { stdout } = runClose('SPRINT-TEST', {});
+
+  // RED: Step 2.9 is absent — stdout will never contain the no-op line.
+  assert.match(
+    stdout,
+    /Step 2\.9 passed: no deferred verifications declared/i,
+    'Expected "Step 2.9 passed: no deferred verifications declared" no-op line; Step 2.9 not yet implemented'
+  );
+});
+
+// ── Scenario 4: declared + red result → close BLOCKS ─────────────────────────
+test('Scenario 4: declared entry with red result → Step 2.9 blocks close', () => {
+  const forcedState = JSON.stringify({
+    'STORY-TEST-02': {
+      declared: [{ command: 'docker build .', blocks: 'close' }],
+      result: 'red',
+    },
+  });
+
+  const { exitCode, stdout, stderr } = runClose('SPRINT-TEST', {
+    CLEARGATE_FORCE_DEFERRED_VERIFY: forcedState,
+  });
+
+  // RED: Step 2.9 is absent. exit may be non-zero (Step 3 failure) but for wrong reason.
+  assert.notEqual(exitCode, 0,
+    'Expected non-zero exit when a declared deferred verification has a red result');
+  const combined = stdout + stderr;
+  assert.match(
+    combined,
+    /Step 2\.9.*fail|deferred.*verif.*fail|STORY-TEST-02.*red|red.*STORY-TEST-02/i,
+    'Expected a Step 2.9 failure message for STORY-TEST-02 (red result); Step 2.9 not yet implemented'
+  );
+});
+
+// ── Scenario 5: grep — PASS-PENDING-SMOKE in qa.md ───────────────────────────
+test('Scenario 5: grep — PASS-PENDING-SMOKE present in cleargate-planning/.claude/agents/qa.md', () => {
+  const qaPath = path.join(REPO_ROOT, 'cleargate-planning', '.claude', 'agents', 'qa.md');
+
+  // RED: PASS-PENDING-SMOKE is not yet in qa.md — will exist after CR-082 Developer merges.
+  const grepResult = spawnSync('grep', ['-q', 'PASS-PENDING-SMOKE', qaPath], {
+    encoding: 'utf8',
+  });
+  assert.equal(
+    grepResult.status,
+    0,
+    `Expected "PASS-PENDING-SMOKE" in ${qaPath} (output-shape verdict line); field not yet added`
+  );
+});
+
+// ── Scenario 6: grep — deferred_verification field in story.md ───────────────
+test('Scenario 6: grep — deferred_verification field present in .cleargate/templates/story.md', () => {
+  const storyMdPath = path.join(REPO_ROOT, '.cleargate', 'templates', 'story.md');
+
+  // RED: deferred_verification field is not yet in story.md — will exist after CR-082 Developer merges.
+  const grepResult = spawnSync('grep', ['-q', 'deferred_verification', storyMdPath], {
+    encoding: 'utf8',
+  });
+  assert.equal(
+    grepResult.status,
+    0,
+    `Expected "deferred_verification" field in ${storyMdPath}; field not yet added`
+  );
+});