@haposoft/cafekit 0.16.0-rc.1 → 0.16.0-rc.3

package/src/claude/skills/test/SKILL.md

@@ -1,201 +1,175 @@
 ---
 name: hapo:test
-description: "Run and verify project tests across all scopes: unit, integration, e2e, and UI. Blast-radius scoping for speed, chrome-devtools for UI verification, structured verdicts for downstream automation."
+description: "Execute the smallest adequate verification scope and own the canonical execution proof."
 user-invocable: true
-when_to_use: "Invoke to run and verify unit, integration, e2e, and UI tests."
+when_to_use: "Use after implementation, for a feature scope, or for an explicit test request."
 category: testing
-keywords: [test, unit, integration, e2e]
+keywords: [test, unit, integration, e2e, proof]
 argument-hint: "[scope|--full|--ui <url>|--ui-auth <url>|--ui-flow <url>]"
 metadata:
   author: haposoft
   version: "2.0.0"
 ---
-# Test — Verify Implementation Quality
+# Test — execution proof owner
 
-Run the project's test suite, analyze results, and return a structured verdict.
-Designed to work **after `hapo:develop`**. Standalone `/hapo:test` uses the same `test-runner` contract that `hapo:develop` relies on during its Quality Gate, and may run **in parallel with `hapo:code-review`**.
-
-**Principles:** Fail-fast | Blast-radius scoping | Zero hidden failures | No mocking to pass
+`hapo:test` is the sole owner of canonical execution proof. It runs real
+commands, records what ran, and emits the receipt consumed by closeout and
+review. Review may consume that receipt but must not run tests, create a second
+receipt, or claim execution proof.
 
 ## Usage
 
-```bash
-/hapo:test                    # Blast-radius mode: only tests affected by recent changes
-/hapo:test --full             # Run full test suite regardless of changes
-/hapo:test <scope>            # Test a specific module or path
-/hapo:test <feature-name>     # Spec-aware test: load specs/<feature-name> and verify scope/task evidence
-/hapo:test specs/<feature>    # Spec-aware test by spec directory
-/hapo:test --ui <url>         # UI verification via chrome-devtools (public pages)
-/hapo:test --ui-auth <url>    # UI verification with auth injection (protected pages)
-/hapo:test --ui-flow <url>    # UI testing with User Journey (form fill/submit simulation)
+```text
+/hapo:test
+/hapo:test --full
+/hapo:test <scope-or-path>
+/hapo:test <feature-name>
+/hapo:test specs/<feature>
+/hapo:test --ui <url>
+/hapo:test --ui-auth <url>
+/hapo:test --ui-flow <url>
 ```
 
-<HARD-GATE>
-NEVER claim tests pass when they were NOT actually executed.
-NEVER mock, stub, or skip a failing test to produce a green result.
-If no test command is detected, report NO_TESTS — do not fabricate results.
-If a test command exits 0 but runs 0 tests, report NO_TESTS — this is a green lie, not a PASS.
-If tests fail, list every failure explicitly — do not summarize failures away.
-</HARD-GATE>
+## Hard gates
 
-<SCOPE-GATE>
-When a feature name or `specs/<feature>` path is supplied, testing is spec-aware.
-Load `spec.json`, `requirements.md`, `design.md`, active/recent task files, and task `Evidence` / test-plan proof.
-The verdict MUST compare executed/reachable behavior against `scope_lock`, requirements, design contracts, task Completion Criteria, and runtime reachability obligations.
-Build/typecheck success without scoped runtime proof is not PASS.
-## Flash promotion contract
-
-Executable policy source: `.claude/scripts/workflow-policy.cjs` (source: `src/claude/scripts/workflow-policy.cjs`). Its `consumeReviewVerdict` and `promoteFlashTask` functions are sole source for PASS/FAIL/BLOCKED handling and task-scoped promotion.
-
-When `/hapo:test <feature>` finds a task with `status: "in_progress"` and receipt `FLASH_UNVERIFIED`, evaluate that task's exact Evidence and runtime reachability only:
-
-- PASS → replace receipt with concrete proof while keeping `status: "in_progress"`, `dependencyBlocked: true`, `unblocks: false`, and `readyForSync: true`; only explicit `/hapo:sync ... sync-finalize` may set `done` and unblock dependents.
-- FAIL, BLOCKED, or NO_TESTS → keep `status: "in_progress"`, keep or update blocker, and do not promote any other flash task.
-- Never blanket-promote every flash task in a feature because one task passed.
-
-
-
-```mermaid
-flowchart TD
-    A["/hapo:test"] --> B[Phase 1: Detect]
-    B --> C{Test runner found?}
-    C -->|No| Z[STOP: Verdict = NO_TESTS]
-    C -->|Yes| D[Phase 2: Execute]
-    D --> E{--ui / auth / flow?}
-    E -->|Yes| F["UI Verification (Parallel Subagents)"]
-    E -->|No| G[Code Tests (Blast Radius)]
-    F --> H[Phase 3: Verdict]
-    G --> H
-    H --> I[Phase 4: Sync Memory]
-    I -->|PASS| J[Hand off to hapo:code-review]
-    I -->|FAIL| K[Load failure-triage.md → classify → escalate]
-```
+- Never claim a pass without executing the relevant command.
+- Never mock, stub, delete, weaken, or skip a failing assertion to obtain green.
+- A missing runner, missing required command, or zero executed tests is not
+  `PASS`; report the blocker and keep closeout unfinished.
+- A compile/typecheck failure is a precheck failure even if no test command is
+  available.
+- Preserve the exact command, exit result, provenance, and artifact hashes
+  required by the canonical receipt schema.
 
-### Phase 1 — Detect
-
-Auto-detect the test runner from project files:
-- `package.json` → npm/yarn/pnpm/bun test, jest, vitest, mocha
-- `pyproject.toml` / `setup.cfg` → pytest
-- `go.mod` → go test
-- `Cargo.toml` → cargo test
-- `pubspec.yaml` → flutter test
-
-Unless `--full` is specified: apply **Blast Radius scoping** to run only tests
-affected by recent file changes. See `references/execution-strategy.md` Phase A.
-
-If the argument resolves to `specs/<feature>` or a feature directory under `specs/`, enter **Spec-Aware Mode**:
-- Load `spec.json`, `requirements.md`, `design.md`, and task files referenced by `task_registry`
-- Identify tasks marked `done`, `in_progress`, or recently changed
-- Extract exact commands, runtime/artifact proof, runtime reachability proof, and negative-path checks
-- Scope test selection by affected task files, but do not skip any mandatory task evidence
-
-### Phase 2 — Execute
-
-**Code testing (default):**
-1. Pre-flight: run typecheck/lint to catch compile errors first
-2. Execute test command with coverage flags
-3. Collect test counts, coverage percentages, and fail stack traces
-4. Treat 0 executed tests as `NO_TESTS`, even if the command exits 0
-5. In Spec-Aware Mode, inspect runtime reachability from declared entrypoints/callers and fail if scoped surfaces are missing or orphaned
-
-**Spec-aware test type escalation:**
-- Unit tests are mandatory when task evidence covers pure logic, transforms, validators, sorting/filtering, or regressions.
-- Component/integration tests are expected when task evidence covers stateful UI, context/store wiring, API/service boundaries, or persistence.
-- E2E/UI flow tests are expected once a complete user-facing workflow exists, not for isolated foundation tasks.
-- Visual/responsive checks are expected for layout, theme, dashboard, and style tasks.
-- Accessibility checks are expected for interactive UI surfaces where focus, roles, labels, keyboard navigation, or ARIA can regress.
-- Smoke checks are enough for scaffold/config tasks unless the task requires deeper proof.
-- Performance/security checks are only mandatory when the requirement, design risk, or touched runtime boundary calls for them.
-
-**UI verification (`--ui` / `--ui-auth` / `--ui-flow`):**
-Execute multi-page discovery, then spawn **Parallel UI Subagents** (test-runner instances) to handle Smoke, Core-Vitals, Accessibility, SEO, Security, and User Flows simultaneously.
-See `references/execution-strategy.md` Phase C for full phase breakdown.
-
-Delegate execution to `test-runner` agent:
-```
-Agent(subagent_type="test-runner",
-  prompt="Run tests. Scope: [blast-radius|full|ui|spec-aware]. Target: [path|url|feature]. Load specs when target is a feature. Return structured verdict with scope/spec coverage and runtime reachability.",
-  description="Test [feature]")
-```
+## Scope and lane
+
+For a feature target, load `spec.json`, `requirements.md`, `design.md`, and
+task evidence only when that target exists. Compare actual execution against
+`scope_lock`, contracts, completion criteria, runtime reachability, and
+negative-path obligations.
+
+Choose depth from the persisted lane, risk, and blast radius:
 
-### Phase 3 — Verdict
+- Direct: targeted commands and diff/runtime self-check;
+- Standard: bounded affected suite and feature receipt;
+- Critical: strict commands plus the independent evidence required by the
+  persisted obligations.
 
-Return a **structured verdict** (required format — not free-form prose):
+Do not infer depth from file count or from the legacy `execution_tier`. That
+field is a read-only compatibility adapter. A task bundle is not required for a
+small Standard feature.
+
+## Spec-Aware Mode
+
+<SCOPE-GATE>
+For a feature target, test only the active scope, requirements, completion
+criteria, and reachable runtime surfaces. A missing or orphaned runtime surface
+is a failure even when the command exits successfully.
+</SCOPE-GATE>
+
+Use blast-radius selection by default; `--full` overrides selection, not proof
+requirements. Use UI checks only when a reachable UI surface is in scope.
+
+## Execution
+
+1. Detect the project runner and exact commands from repository files and task
+   evidence. Do not invent commands.
+2. Run a cheap compile/typecheck precheck where the project provides one.
+3. Execute the smallest adequate unit, integration, UI, E2E, accessibility,
+   performance, or security proof for the changed surface.
+4. Inspect runtime reachability and declared artifacts when the task creates
+   runtime-facing or generated output.
+5. Preserve raw outcomes and write one canonical receipt. A receipt must not
+   contain secrets or placeholder provenance.
+
+Required proof type follows the behavior, not ceremony:
+
+| Surface | Adequate proof |
+|---|---|
+| pure logic/parser/validator | unit plus negative path |
+| stateful UI or module wiring | component/integration and mounted path |
+| API, persistence, provider, or process boundary | real contract/state handoff |
+| complete user workflow | E2E or UI flow |
+| layout or responsive behavior | viewport/visual check |
+| interactive focus/labels/keyboard | accessibility check |
+| regression | reproduction before fix plus passing regression |
+| security/performance | only when requirement, risk, or boundary requires it |
+
+## Canonical receipt
+
+The receipt is execution evidence, not a status marker. It must contain the
+actual command, a successful exit result, both provenance anchors (`Base` and
+`Head`, or their canonical aliases), and any declared artifact SHA-256. Reject
+`Exit: 1`, conflicting outcomes, empty commands, placeholders, missing
+provenance, zero execution, and failure summaries. No-artifact tasks remain
+compatible; declared artifacts require hashes.
+
+Closeout and flash callers must also provide an explicit runtime binding; a
+valid-length `Base`/`Head` pair alone is not identity proof. The minimal adapter
+contract is `const binding = policy.createReceiptBinding({ base, head })`, then
+pass `receipt_binding: binding` to `completionDecision` or include the binding's
+`expectedProvenance` in the flash task. The policy requires that binding and
+compares both receipt anchors before completion or flash promotion.
+
+For a normal closeout, emit a receipt that the shared policy validator accepts.
+For `--flash`, emit proof for the current `FLASH_UNVERIFIED` task only. Only explicit trusted sync-finalize may promote it. The
+receipt may make the task eligible for trusted sync-finalize, but it must not
+promote the task, unblock dependents, or fabricate a done state.
+
+## Verdict and handoff
+
+The shared workflow surface is:
+
+`PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED`
+
+Warnings describe residual, non-blocking concerns; they never replace missing
+execution proof. A legacy diagnostic result such as `NO_TESTS` is normalized by
+the shared adapter to an unfinished outcome and is never treated as `PASS`.
 
 ```markdown
 ## Test Verdict
 
-**Status:** PASS | FAIL | PARTIAL | NO_TESTS
-**Scope:** blast-radius (N/M tests) | full-suite (N tests) | ui-check
-**Duration:** Xs
+**Status:** PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED
+**Scope:** [target and selection]
+**Commands:** [exact commands]
+**Exit:** [actual result]
+**Duration:** [measured time]
+**Receipt:** [path or inline canonical receipt]
 
 ### Results
-- Passed: N | Failed: N | Skipped: N
-
-### Coverage (if applicable)
-| Metric    | Result | Threshold | Status    |
-|-----------|--------|-----------|-----------|
-| Lines     | X%     | 80%       | PASS/FAIL |
-| Branches  | X%     | 70%       | PASS/FAIL |
-| Functions | X%     | 80%       | PASS/FAIL |
-
-### Failures (if any)
-1. `path/to/file.test.ts:42` — AssertionError: expected X but got Y — Category: Logic Error
-
-### UI Results (if --ui)
-- Console errors: N found | none
-- Network errors (4xx/5xx): N found | none
-- Performance: LCP Xms | CLS X | FCP Xms
-- Accessibility issues: N found | none
-- Screenshots: [paths]
-
-### Scope / Spec Coverage (if feature scope)
-- Requirements covered: N/N
-- Task evidence checks: PASS | FAIL | UNVERIFIED
-- Runtime reachability: PASS | FAIL | UNVERIFIED
-- Out-of-scope behavior detected: none | [list]
-
-### Test Regression Check
-- **Comparison:** Compare current test count and assertion depth against previous runs.
-- **Result:** OK | REGRESSION (tests deleted/weakened)
+- Passed: N | Failed: N | Skipped: N | Executed: N
+
+### Scope / reachability
+- Requirements: [covered/uncovered]
+- Runtime reachability: PASS | FAIL | BLOCKED
+- Artifact/provenance checks: PASS | FAIL | BLOCKED
 
 ### Action
-- PASS → Proceed. Hand off to hapo:code-review.
-- FAIL → [list specific fixes needed] → Return to implementer. (If REGRESSION: label "Test Regression — tests were deleted or weakened to produce green result")
-- PARTIAL → [list uncovered areas] → Consider adding tests.
-- NO_TESTS → No test runner detected. User must configure tests first.
-
-<lessons_learned>
-{
-  "flaky_tests_added": []
-}
-</lessons_learned>
+- PASS → give the receipt to the single closeout owner; only literal `PASS` can
+  complete a task.
+- PASS_WITH_WARNINGS → give the receipt to the closeout owner, but keep the
+  task unfinished until a literal `PASS` decision is recorded.
+- FAIL → list exact failures; implementation remains unfinished.
+- BLOCKED → state the changed prerequisite; do not blind-retry.
 ```
 
-### Phase 4 — Sync Memory
+The closeout owner calls this workflow once for the current task or feature.
+Do not trigger review from inside the test workflow and do not run a duplicate
+test pass merely because review is requested. Review evaluates correctness,
+security, and spec compliance against this proof.
 
-After receiving the verdict from `test-runner`, the orchestrator (`hapo:test`) intercepts the `<lessons_learned>` block.
-It merges the JSON data into `.hapo/test-memory.json` per `references/test-memory.md` to ensure that future runs remember flaky tests or environment setup requirements without modifying the codebase.
+## Flash proof
 
-## Skill Interconnections
-
-| Skill / Agent | Direction | Role |
-|---|---|---|
-| `hapo:code-review` | runs in parallel | Both run at Quality Gate Step 4 |
-| `hapo:develop` | orchestrates | Spawns hapo:test at Step 4 |
-| `inspector` agent | hapo:test → | Scout test file locations when structure is unfamiliar |
-| `implementer` agent | hapo:test → | FAIL verdicts route back here for fixing |
-| `test-runner` agent | hapo:test → | Primary executor, spawned via the `Agent` tool |
-| chrome-devtools scripts | test-runner → | UI verification (navigate, screenshot, console, network, performance, aria-snapshot, inject-auth) |
+When the target contains an in-progress `FLASH_UNVERIFIED` task, test only its
+exact Evidence and reachability obligations. On pass, keep the task
+`in_progress`, keep `FLASH_UNVERIFIED`, `dependencyBlocked: true`, and
+`unblocks: false`; return canonical proof to trusted sync-finalize. On failure,
+blocker, or no tests, do not promote any task.
 
 ## References
 
-- `references/execution-strategy.md` — Blast-radius algorithm, auto-detect logic, UI verification phases (A–E)
-- `references/failure-triage.md` — Failure categories, triage decision tree, escalation rules
-- `references/test-memory.md` — `.hapo/test-memory.json` schema and merge rules
-
-## Related
-
-- Previous skill: `hapo:develop`
-- Parallel skill: `hapo:code-review`
-- Parent workflow: `hapo:develop` Step 4 Quality Gate
+- `references/execution-strategy.md` — blast-radius and UI selection, loaded
+  only when the default strategy needs detail.
+- `references/failure-triage.md` — failure classification, loaded on failure.
+- `references/test-memory.md` — optional historical context; current receipt
+  evidence always wins.

package/src/codex/hooks/completion-authority-check.cjs

@@ -0,0 +1,260 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const STATE = require('./completion-authority-state.cjs');
+const { checkReceipt, evidenceBody } = require('./lib/spec-receipt.cjs');
+const { findAllSpecCandidates, resolveActiveSpec } = require('./lib/spec-utils.cjs');
+
+function plain(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function inside(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}
+
+function readBoundFile(root, target) {
+  const requested = path.isAbsolute(target) ? target : path.resolve(root, target);
+  if (!inside(root, requested)) return null;
+  try {
+    const canonicalRoot = fs.realpathSync(root);
+    const canonical = fs.realpathSync(requested);
+    if (!inside(canonicalRoot, canonical) || !fs.statSync(canonical).isFile()) return null;
+    return fs.readFileSync(canonical);
+  } catch { return null; }
+}
+
+function readTask(featureDir, taskPath) {
+  const target = path.resolve(featureDir, taskPath);
+  if (!inside(featureDir, target)) return null;
+  const bytes = readBoundFile(featureDir, target);
+  if (!bytes) return null;
+  return { bytes, text: bytes.toString('utf8'), path: fs.realpathSync(target) };
+}
+
+function artifactReferences(body) {
+  if (typeof body !== 'string') return [];
+  const references = [];
+  for (const line of body.split('\n')) {
+    if (!/^\s*Artifacts?\s*:/i.test(line) && !/^\s*Artifact\s+produced\b/i.test(line)) continue;
+    const hashes = [...line.matchAll(/\b(?:artifact[_-])?sha-?256\s*:\s*([^\s),;`]+)/gi)].map((match) => match[1]);
+    const raw = line.replace(/^\s*Artifacts?\s*:\s*/i, '').replace(/^\s*Artifact\s+produced\s*:?[ \t]*/i, '').replace(/\b(?:artifact[_-])?sha-?256\s*:\s*[^\s),;`]+/gi, '').replace(/[()[\]{}]/g, ' ').trim();
+    const paths = raw.split(/\s*(?:\+|,|;|\band\b)\s*/i).map((value) => value.trim()).filter(Boolean);
+    paths.forEach((artifactPath, index) => references.push({ path: artifactPath, hash: hashes[index] || null }));
+  }
+  return references;
+}
+
+function resolveCandidate({ projectRoot, runtime, payload }) {
+  const explicitFeature = payload.featureName || payload.feature || payload.explicitFeature || null;
+  const explicitPath = payload.specPath || payload.spec_path || payload.featurePath || null;
+  const candidates = findAllSpecCandidates(projectRoot, runtime);
+  if (candidates.length > 1) return { error: 'multiple_persisted', candidates: candidates.map((candidate) => candidate.featureName) };
+  if (candidates.length === 0) {
+    if (explicitFeature || explicitPath) return { error: 'explicit_not_found', explicitFeature, explicitPath, reason: 'no globally persisted spec matches the explicit target' };
+    return null;
+  }
+  if (!explicitFeature && !explicitPath) return candidates[0];
+  const targeted = resolveActiveSpec({ projectRoot, runtime, explicitFeature, explicitPath });
+  if (!targeted || targeted.error) {
+    return {
+      error: 'explicit_mismatch',
+      explicitFeature,
+      explicitPath,
+      reason: targeted?.reason || 'explicit target does not resolve to the persisted candidate',
+    };
+  }
+  if (targeted.featureName !== candidates[0].featureName || path.resolve(targeted.specFile) !== path.resolve(candidates[0].specFile)) {
+    return {
+      error: 'explicit_mismatch',
+      explicitFeature,
+      explicitPath,
+      reason: 'explicit target does not match the sole globally persisted candidate',
+    };
+  }
+  return candidates[0];
+}
+
+function policyRank(policy, lane) {
+  const lanes = Array.isArray(policy.LANES) ? policy.LANES : ['Direct', 'Standard', 'Critical'];
+  return lanes.indexOf(lane);
+}
+
+function policyMonotonicFailures(policy, baseline, current) {
+  const failures = [];
+  if (baseline.version !== current.version) failures.push('workflow_policy.version changed');
+  if (policyRank(policy, current.lane) < policyRank(policy, baseline.lane)) failures.push(`workflow_policy.lane downgraded from ${baseline.lane} to ${current.lane}`);
+  if (policyRank(policy, current.automatic_lane) < policyRank(policy, baseline.automatic_lane)) failures.push(`workflow_policy.automatic_lane downgraded from ${baseline.automatic_lane} to ${current.automatic_lane}`);
+  const currentRisks = new Set(current.risks);
+  for (const risk of baseline.risks) if (!currentRisks.has(risk)) failures.push(`workflow_policy risk ${risk} was removed`);
+  const currentObligations = new Set(current.proof_obligations);
+  for (const obligation of baseline.proof_obligations) if (!currentObligations.has(obligation)) failures.push(`workflow_policy obligation ${obligation} was removed`);
+  return failures;
+}
+
+function mergePolicyFloor(policy, floor, current) {
+  const merged = { ...current };
+  if (policyRank(policy, floor.lane) > policyRank(policy, current.lane)) merged.lane = floor.lane;
+  if (policyRank(policy, floor.automatic_lane) > policyRank(policy, current.automatic_lane)) merged.automatic_lane = floor.automatic_lane;
+  merged.risks = [...new Set([...current.risks, ...floor.risks])];
+  const proofObligations = [];
+  const actorNeeds = [];
+  for (const source of [current, floor]) {
+    for (let index = 0; index < source.proof_obligations.length; index += 1) {
+      const obligation = source.proof_obligations[index];
+      if (proofObligations.includes(obligation)) continue;
+      proofObligations.push(obligation);
+      actorNeeds.push(source.actor_needs[index]);
+    }
+  }
+  merged.proof_obligations = proofObligations;
+  merged.actor_needs = actorNeeds;
+  return merged;
+}
+
+function observePolicyBaseline({ STATE: state, policy, projectRoot, candidate }) {
+  if (!Object.prototype.hasOwnProperty.call(candidate.spec, 'workflow_policy')) {
+    return { ok: false, reason: 'workflow_policy is missing for persisted spec' };
+  }
+  const current = candidate.spec.workflow_policy;
+  const validation = policy.validateWorkflowPolicySnapshot(current);
+  if (!validation.valid) return { ok: false, reason: `workflow_policy is malformed: ${validation.errors.join('; ')}` };
+  let identity;
+  try {
+    identity = {
+      project_root: fs.realpathSync(projectRoot),
+      spec_file: fs.realpathSync(candidate.specFile),
+      feature_name: candidate.featureName,
+    };
+    state.ensureKey();
+    let authorityState = state.readState(projectRoot);
+    if (authorityState.malformed || authorityState.keyError || authorityState.keyMissing) {
+      return { ok: false, reason: authorityState.reason || 'completion authority state is unavailable' };
+    }
+    if (!authorityState.floor) {
+      if (authorityState.baselines.length > 0 || authorityState.pending || authorityState.grant) {
+        return { ok: false, reason: 'project policy floor is missing for persisted authority state' };
+      }
+      state.writePolicyFloor(projectRoot, current);
+      authorityState = state.readState(projectRoot);
+      if (authorityState.malformed || authorityState.keyError || authorityState.keyMissing || !authorityState.floor) {
+        return { ok: false, reason: authorityState.reason || 'project policy floor could not be persisted' };
+      }
+    } else {
+      const floorValidation = policy.validateWorkflowPolicySnapshot(authorityState.floor.policy);
+      if (!floorValidation.valid) return { ok: false, reason: `persisted project policy floor is malformed: ${floorValidation.errors.join('; ')}` };
+      const floorFailures = policyMonotonicFailures(policy, authorityState.floor.policy, current);
+      if (floorFailures.length) return { ok: false, reason: `project policy floor is monotonic and cannot be downgraded (${floorFailures.join('; ')})` };
+      const mergedFloor = mergePolicyFloor(policy, authorityState.floor.policy, current);
+      if (state.digest(authorityState.floor.policy) !== state.digest(mergedFloor)) state.writePolicyFloor(projectRoot, mergedFloor);
+    }
+    const baseline = state.readBaseline(projectRoot, identity);
+    if (!baseline) {
+      state.writeBaseline(projectRoot, identity, current);
+      return { ok: true };
+    }
+    const baselineValidation = policy.validateWorkflowPolicySnapshot(baseline.policy);
+    if (!baselineValidation.valid) return { ok: false, reason: `persisted workflow policy baseline is malformed: ${baselineValidation.errors.join('; ')}` };
+    const failures = policyMonotonicFailures(policy, baseline.policy, current);
+    if (failures.length) return { ok: false, reason: `workflow_policy baseline is monotonic and cannot be downgraded (${failures.join('; ')})` };
+    if (state.digest(baseline.policy) !== state.digest(current)) state.writeBaseline(projectRoot, identity, current);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, reason: `workflow_policy baseline unavailable: ${error.message}` };
+  }
+}
+
+function evaluateCloseout({ policy, projectRoot, runtime, payload }) {
+  const candidate = resolveCandidate({ projectRoot, runtime, payload });
+  if (!candidate) return { ok: true, candidate: null };
+  if (candidate.error) {
+    const detail = Array.isArray(candidate.candidates) ? candidate.candidates.join(', ') : (candidate.reason || candidate.error);
+    return { ok: false, candidate, reason: `${candidate.error}: ${detail}` };
+  }
+  const sessionId = payload.session_id;
+  if (typeof sessionId !== 'string' || !sessionId.trim()) return { ok: false, candidate, reason: 'trusted host session ID is unavailable' };
+  const baseline = observePolicyBaseline({ STATE, policy, projectRoot, candidate });
+  if (!baseline.ok) return { ok: false, candidate, reason: baseline.reason };
+  if (runtime.spec?.completion_gate !== undefined && runtime.spec.completion_gate !== true) return { ok: false, candidate, reason: 'runtime.spec.completion_gate is worker-writable and cannot authorize completion' };
+  const status = candidate.spec.status;
+  if (!['in_progress', 'in-progress', 'completed', 'complete'].includes(status)) return { ok: false, candidate, reason: `spec status is invalid: ${String(status)}` };
+  const registry = candidate.spec.task_registry;
+  if (!plain(registry) || Object.keys(registry).length === 0) return { ok: false, candidate, reason: 'task_registry is missing or empty' };
+
+  let runtimeContext;
+  try {
+    runtimeContext = policy.deriveRuntimeContext({
+      projectRoot,
+      specsRoot: candidate.specsDir,
+      specFile: candidate.specFile,
+      featureName: candidate.featureName,
+      runtimeSession: sessionId,
+    });
+  } catch (error) {
+    return { ok: false, candidate, reason: `runtime provenance unavailable: ${error.message}` };
+  }
+  if (!policy.isTrustedRuntimeContext(runtimeContext)) return { ok: false, candidate, reason: 'fresh trusted runtime Base/Head/context is unavailable' };
+
+  const featureDir = path.join(candidate.specsDir, candidate.featureName);
+  const receiptBodies = new Map();
+  const taskFiles = [];
+  const failures = [];
+  for (const [taskPath, task] of Object.entries(registry)) {
+    if (!plain(task) || task.status !== 'done') {
+      failures.push(`${taskPath}: status is not done`);
+      continue;
+    }
+    if (policy.isStaleFlashDone(task)) failures.push(`${taskPath}: FLASH_UNVERIFIED`);
+    const file = readTask(featureDir, taskPath);
+    const body = file ? evidenceBody(file.text) : null;
+    if (body !== null) receiptBodies.set(taskPath, body);
+    const receiptFailures = checkReceipt(featureDir, taskPath, task, runtimeContext);
+    if (receiptFailures.length) failures.push(`${taskPath}: checks ${receiptFailures.join(',')}`);
+    if (file) taskFiles.push({ path: taskPath, digest: crypto.createHash('sha256').update(file.bytes).digest('hex') });
+  }
+  if (failures.length) return { ok: false, candidate, reason: `technical completion proof is incomplete (${failures.slice(0, 4).join('; ')})` };
+
+  const firstTask = Object.keys(registry).find((taskPath) => receiptBodies.has(taskPath));
+  let completion;
+  try {
+    completion = policy.completionDecisionForSpec(candidate.spec, {
+      runtimeContext,
+      executionReceipt: firstTask ? receiptBodies.get(firstTask) : null,
+      taskContext: firstTask ? registry[firstTask] : null,
+    });
+  } catch (error) {
+    return { ok: false, candidate, reason: `workflow completion proof could not be evaluated: ${error.message}` };
+  }
+  if (completion.completion !== 'complete' && completion.completion !== 'not_applicable') {
+    return { ok: false, candidate, reason: completion.blocker || 'workflow completion proof is incomplete' };
+  }
+
+  const artifactRefs = [...receiptBodies.values()].flatMap(artifactReferences).sort((left, right) => `${left.path}:${left.hash}`.localeCompare(`${right.path}:${right.hash}`));
+  const artifactFiles = artifactRefs.map((reference) => ({
+    ...reference,
+    digest: crypto.createHash('sha256').update(readBoundFile(projectRoot, reference.path) || Buffer.from('<missing>')).digest('hex'),
+  }));
+  const specBytes = readBoundFile(projectRoot, candidate.specFile);
+  const binding = {
+    project_root: runtimeContext.project_root,
+    platform: process.platform,
+    session_id: sessionId,
+    feature_name: candidate.featureName,
+    spec_file: candidate.specFile,
+    runtime: { base: runtimeContext.base, head: runtimeContext.head, context_id: runtimeContext.context_id },
+    spec_digest: STATE.digest(candidate.spec),
+    spec_bytes_digest: crypto.createHash('sha256').update(specBytes || Buffer.from('<missing>')).digest('hex'),
+    policy_digest: STATE.digest(candidate.spec.workflow_policy ?? null),
+    task_registry_digest: STATE.digest(registry),
+    task_digest: STATE.digest(taskFiles),
+    artifact_digest: STATE.digest(artifactFiles),
+    provenance_digest: STATE.digest({ runtime: runtimeContext, receipts: [...receiptBodies.values()].map((body) => body.match(/^\s*(?:Base|Head|base_sha|head_sha)\s*:.*$/gim) || []) }),
+  };
+  binding.binding_digest = STATE.digest(binding);
+  return { ok: true, candidate, runtimeContext, binding };
+}
+
+module.exports = { evaluateCloseout, resolveCandidate, observePolicyBaseline };