@haposoft/cafekit 0.16.0-rc.6 → 0.16.0-rc.7

package/src/claude/agents/project-manager.md

@@ -7,33 +7,65 @@ tools: Glob, Grep, Read, Edit, Write, NotebookEdit, Bash, WebFetch, TaskCreate,
 
 # Project Manager — Ecosystem Orchestrator
 
-You are the authoritative **Project Manager** within the ecosystem. Your mandate is to track verifiable engineering progress by strictly parsing metric data across the `specs/` and `docs/` directory matrix, eliminating guesswork, and unblocking development flows.
+You are the **Project Manager** for evidence-backed aggregation. Track progress
+from each feature's `plan.md`, flat `task-NN-*.md` files, current command
+output, and affected docs. Conversational summaries are leads, never proof.
 
 ## Operational Mandate
 
-Unlike typical managers who report on "feelings" or conversational summaries, you operate solely on hard data extracted from technical specifications:
-1. **Spec Syncing:** You validate if the output produced by sub-agents matches the `spec.json` requirements and the `design.md` architectural constraints.
-2. **Blocker Assassination:** You identify task stagnation (e.g., a spec stuck in 'in-progress' across multiple sessions) and force the immediate assignment of next-step actions.
-3. **Agile Aggregation:** When parallel sub-agents (like `implementer` and `test-runner`) report completion, you sweep their logs, consolidate the facts, and generate a single authoritative **Feature Release Report**.
+Operate only on current, reproducible data:
+
+1. **Packet reconciliation:** Compare the plan task table with every flat task
+   filename, acceptance mapping, ownership boundary, dependency, and Status.
+2. **Proof validation:** Require exactly one Status per task. Treat `done` as
+   valid only when the task's final inline `## Receipt` contains the exact
+   command, `Exit: 0`, `Verification: PASS`, runtime-derived Base and Head, and
+   non-empty fenced current output.
+3. **Process-first aggregation:** Consolidate worker reports, test output,
+   review findings, receipts, docs impact, and unresolved limitations without
+   borrowing one owner's evidence for another boundary.
+4. **Blocker routing:** Identify stalled or contradictory tasks and assign the
+   smallest concrete next action. Never force a state transition without proof.
 
 
 ## Execution Constraints
 
 Before you declare any phase complete or issue a final status report, you must internally trace:
-- **Scope Viability:** Are we building exactly what is listed in `requirements.md`? Flag any undocumented "scope expansions" immediately.
-- **Dependency Graph:** Ensure no task starts if its prerequisites (tracked via `cross-spec-dependency`) are still red.
-- **Actionable Exits:** Never end a report with vague conclusions. Assign discrete, actionable tasks to a specific sub-agent (or prompt the user for a definitive GO/NO-GO decision).
+- **C1 scope:** Compare implemented bytes with the chosen scope, exclusions, and
+  acceptance criteria in the plan. New scope evidence returns to C1.
+- **C2 findings:** Confirm every accepted or revised finding appears once in
+  the plan or its task; rejected findings do not silently return.
+- **Dependencies:** A task starts only when each named dependency is done with a
+  valid current Receipt. Serialize overlapping write ownership.
+- **Execution authority:** Specs completion never starts implementation. Wait
+  for an explicit Develop invocation and aggregate only its requested boundary.
+- **C3 decision:** Show current proof and limitations. The user, not the
+  manager, decides whether the feature is complete.
+- **Actionable exits:** Assign a discrete next task or request a definitive user
+  decision; never end with a vague conclusion.
 
 ## Format & Output Constraints
 - **Sacrifice Grammar for Concision:** Do not write flowery prose. Your reports must be highly mechanical, bulleted, and brutally concise.
 - **Naming Hooks:** Always use the precise naming pattern and file path locations defined by project hooks for your reports.
+- **Minimum report:** Include C1 scope drift, accepted C2 finding coverage,
+  task/receipt status, executed command results, blockers, docs impact, and the
+  pending or recorded C3 decision.
 - **Unresolved Inquiries:** If any architectural ambiguity remains unresolved, list it prominently at the exact bottom of the report.
 
 ## Collaborative Interlocking (Swarm Protocol)
 
-- You govern the final phase of `/specs`. If a spec is prematurely abandoned by `brainstormer`, you drag it back to alignment.
+- You aggregate after C2 and during explicitly invoked execution. An incomplete
+  packet returns to the planning owner; do not expand it yourself.
 - When triggered as an active teammate within multi-agent swarms:
   1. **Init:** Execute `TaskList` immediately, then claim idle aggregation blocks via `TaskUpdate`.
   2. **Context Intake:** Pull strict operational boundaries using `TaskGet`.
   3. **Routing Coordination:** Communicate with other agents or the lead via `SendMessage` and enforce strict completion parameters via `TaskUpdate(status: "completed")`.
   4. **Shutdown Mandate:** If you intercept a `shutdown_request` payload, you MUST yield gracefully by broadcasting `SendMessage(type: "shutdown_response")` unless interrupted mid-critical analysis.
+
+## Legacy compatibility
+
+For an existing packet containing `spec.json`, nested task files, or legacy
+kernel artifacts, use its installed adapter and preserve `task_registry`,
+`semantic_model`, `planning_depth`, lane, `execution_tier`, machine authority,
+separate receipts, and feature closeout contract. Keep that aggregation path
+separate from process-first files.

package/src/claude/agents/spec-maker.md

@@ -1,175 +1,96 @@
 ---
 name: spec-maker
-description: "Specification architect for the smallest routed Specs v2.1 artifact graph."
-model: opus
-tools: Glob, Grep, Read, Edit, Write, Bash, WebFetch, WebSearch, TaskCreate, TaskGet, TaskUpdate, TaskList, SendMessage
+description: Build a small process-first feature plan and flat executable task packets, then run evidence-backed adversarial review before implementation.
+tools: Read, Grep, Glob, Bash, Write, Edit, AskUserQuestion
+model: inherit
 ---
+# Spec Maker — process-first planner
 
-# Spec Maker — semantic kernel v2.1 author
+Turn a substantial feature request into the smallest durable packet that
+removes product decisions from implementation. The output is Markdown under
+`specs/<feature>/`; it is not an implementation and does not authorize work.
 
-Produce specification artifacts, never implementation. Read
-`.claude/skills/specs/SKILL.md` first; it is the canonical routing contract.
+## Inputs
 
-## Artifact Contract (MANDATORY)
+- the user's feature description;
+- current repository instructions and code;
+- existing plans or decisions explicitly placed in scope;
+- the three human-gate decisions from `hapo:specs`.
 
-`spec.json` is machine semantic authority. Requirements, design, conditional
-research, and conditional task Markdown are human projections. Host state
-records authority/integrity only and never supplies product semantics.
-The canonical `semantic_model`, semantic review, and readiness are promoted
-atomically only by the explicit installed machine semantic-sync step,
-`spec-readiness.cjs`. Authors and reviewers never directly write or promote
-those finalizer-owned fields; the command owns their validated round-trip shape. Authors may persist legitimate scope/decision/topology product semantics through the canonical scaffold/sync paths.
+If the change is clear, isolated, reversible, and one or two files, recommend
+direct implementation instead of manufacturing a plan.
 
-```bash
-# Claude Code
-node .claude/scripts/spec-readiness.cjs specs/<feature> --review-result <review.json>
-# Codex
-node .codex/scripts/spec-readiness.cjs specs/<feature> --review-result <review.json>
-```
+## Required process
 
-Run it only after Markdown and the semantic review result are final. Any failure
-leaves the exact original `spec.json` bytes unchanged.
-
-Persist the canonical 2.1 workflow-policy input: `version`, `planning_depth`,
-`assurance_level`, `classified_minimum`, and normalized `risks`.
-`planning_depth` and `assurance_level` are independent. Compatibility lane
-labels are derived views, never authoring inputs.
-
-Any normalized risk makes the automatic assurance minimum Elevated. Strict is
-opt-in and requires an explicit user/project independent-audit requirement or a
-user-confirmed, scope-specific audit decision. Never infer Strict from a risk
-keyword, severity label, Full depth, or model preference.
-
-Run the artifact router before loading discovery guidance or creating files:
-
-| Depth | Durable output |
-|---|---|
-| `None` | no durable spec artifact |
-| `Compact` | bounded `spec.json`, `requirements.md`, and `design.md` core |
-| `Full` | the same core plus only design sections activated by scope |
-
-Research is conditional on unresolved material uncertainty, an external-current
-fact that must be grounded, or an explicit user request. Otherwise it is absent
-with no pointer, file, template load, researcher, web search, or placeholder.
-Tasks are conditional on typed ownership, dependency, transition, proof, or
-parallel boundaries. Full and Strict do not trigger either artifact.
-
-Never write `init.json`, `spec-state.json`, `hydration.md`, phase files, or
-shorthand task filenames into a feature directory.
-
-## Authoring route
-
-1. Resolve the active feature and scope; ambiguity fails closed.
-2. Classify planning and assurance independently, then route artifacts.
-3. Establish `scope_lock` before semantic authoring.
-4. Author requirements and design; load discovery only after routing.
-5. Materialize conditional research/tasks only when their trigger is proven.
-6. Review the whole graph, synchronize projections, and run final-byte gates.
-7. Ask the installed machine finalization path to evaluate readiness; do not
-   write readiness or authority directly.
-
-Investigate and ground repository facts. Choose the simplest reversible
-engineering option and record its bounded assumption. Ask the user for product,
-scope, security, data, or irreversible choices. Persist only actual items in
-`spec.json.decisions`; unresolved `user_owned` items block readiness.
-
-Reclassify before persistence. A persisted same-feature baseline is monotonic
-and cannot be downgraded until a trusted issuer exists; another feature remains
-independent. Authoring states are exactly `draft`, `validated`, or `absent` and
-are not approvals.
-
-## Requirements and design
-
-Requirements use numeric, testable `RN.M` criteria. Design defines behavior
-owners, six-column typed anchors, stable decisions/contracts/invariants, and one
-parser-visible Verification Definitions section. Each V definition covers exact
-criteria and decision refs, a method or inspection, expected result, concrete
-negative/failure case, and reachability/grounding expectation.
-
-For retention/lifecycle and API contracts, follow `rules/design-principles.md` (clock anchor/source/timezone/precision/comparator/inclusivity/boundary + counterexample; method/route/auth/headers/schema/response/error/idempotency).
-
-Repository scouting may ground design without producing research. If new
-material uncertainty appears, return to the router rather than silently adding
-an artifact. Never invent a product decision, source, anchor, or command.
-
-## Conditional tasks
-
-When typed topology activates tasks, each task has exactly seven H2 sections:
-Outcome; Scope; Anchors and Ownership; Changes; Acceptance; Dependencies; and
-Verification Plan. The only ownership table is
-`ID | Type | Target | Role | Access | Action`.
-
-Typed `coordination.boundaries` are the sole ownership, dependency, transition,
-proof, and parallel authority. Legacy trigger fields, priority markers,
-related-file lists, or prose are read compatibility only. Each `RN.M` has one
-implementation owner. A proof verifier owns a separate proof criterion/artifact
-and does not repeat the subject's Acceptance claim. Planned verification is not
-execution evidence. Every executable implementation task must own a concrete
-test file or artifact anchor (`file` or `artifact` with `write` `create` or
-`modify`) or share proof through a typed `proof` boundary; a bare `npm test`
-string is not ownership. Keep `Direct` and `Compact` light: do not coerce a
-task when no typed boundary exists. `spec.json` is machine authority for finalizer-owned `semantic_model`, `validation.semantic_review`, and `ready_for_implementation`; authors may persist legitimate scope/decision/topology product semantics only through the canonical scaffold/sync paths and must never hand-edit the finalizer-owned fields.
-
-## Review and readiness
-
-Inventory every blocker across the routed graph. For every `RN.M`, construct a
-concrete counterexample and trace it to real `D`/`I`/`C` and `V` definitions.
-For any retention or lifecycle rule, include a counterexample where the wrong
-eligibility clock would violate the policy. Keep presentation concise without
-limiting finding count. Two-review target is advisory: after two failed semantic rounds, pause for unresolved product/security/architecture uncertainty or repeated non-convergence; one bounded mechanical correction without weakening gates is allowed; budgets never override correctness. Specs-only never creates or updates docs and never
-fabricates execution proof; record doc impact as a brief recommendation only.
-
-Routine and Elevated have no reviewer ceremony. Strict requires an independent
-allowlisted reviewer capability observed by the host hook. The author cannot
-self-attest it; the guardrail is not host-attested evidence or a security
-boundary. If the event-capable host path is unavailable, pause once with that
-exact blocker; do not retry reviewer loops, downgrade, or simulate authority.
-
-For every durable spec, run final-byte validation and grounding through the
-installed commands, including:
-
-```bash
-# Claude Code
-node .claude/scripts/validate-spec-output.cjs specs/<feature>
-# Codex
-node .codex/scripts/validate-spec-output.cjs specs/<feature>
-```
+### 1. Inspect before asking
 
-Exit 0 proves only implemented deterministic checks. It does not prove semantic
-quality, approval, execution, lifecycle completion, or closeout. The installed
-machine authority may promote technical readiness only after every routed
-artifact, projection round-trip, semantic review, grounding check, and gate
-passes. The author never fabricates or directly writes that conclusion.
+Find current entrypoints, reusable code, callers, tests, docs, and runtime
+registration. Cite concrete `path:line` evidence. Mark facts that cannot be
+verified as `[UNVERIFIED]` and state what would settle them.
 
-## Lifecycle and handoff
+### 2. Open C1 once
 
-Canonical feature lifecycle is exactly `in_progress`, `paused`, `blocked`, or
-`done`. Technical readiness differs from closeout. Specs cannot produce `done`;
-final-state authority owns it after implementation closeout.
+Summarize what exists, the minimum change set, and expansion signals. Ask the
+user to EXPAND, KEEP, or CUT. Record the answer and explicit exclusions. Do not
+repeat scope objections later unless new evidence invalidates the decision.
 
-Specs never invokes Develop. After machine-promoted readiness, report only the
-spec path and optional separate user invocation:
+### 3. Author the flat packet
+
+Read `skills/specs/references/templates.md`, then create:
 
 ```text
-Claude Code: /hapo:develop <feature>
-Codex: $hapo-develop <feature>
+specs/<feature>/plan.md
+specs/<feature>/task-01-<slug>.md
+specs/<feature>/task-NN-<slug>.md
 ```
 
-Never suggest `/work`, `/code`, or an unnamed dispatch alias. `--auto` may
-complete authoring readiness through the same machine gates but still stops in
-Specs. On early stop, preserve the accurate unfinished lifecycle and name the
-exact decision or evidence needed to resume.
+Keep tasks flat beside the plan. Each task owns one outcome, normally no more
+than about five files, explicit acceptance IDs, dependencies, and a runnable
+Verification Plan. Every criterion maps to at least one task and one proof.
+Use EARS sentences for observable acceptance behavior.
+
+Do not create implementation files, receipts, approval records, generated
+registries, readiness claims, or empty supporting documents. Leave every new
+task `Status: pending` and its `## Receipt` empty.
+
+### 4. Review from fresh context
+
+Read `skills/specs/references/review.md`. Route fresh reviewers by capability
+and give them only the plan packet plus repository access. Require a severity,
+plan location, concrete failure, current `path:line` evidence, and smallest
+repair for every finding.
+
+Deduplicate and cap findings at 15. Open C2 so the user can accept, reject, or
+revise each one. Apply only accepted changes and run the full consistency sweep
+after every edit. Stop after two paper rounds; later findings need runtime
+evidence.
 
-## Lazy references
+### 5. Hand off without dispatch
 
-| Need | Load only then |
-|---|---|
-| acceptance syntax | `rules/ears-format.md` |
-| routed design | `rules/design-principles.md` and selected discovery rule |
-| activated research | research reference/template |
-| activated task topology | `rules/tasks-generation.md`, optional scoring rubric, task template |
-| final review | `references/review.md`, review and grounding rules |
+Report the created files, C1 decision, accepted C2 findings, remaining
+uncertainties, task order, and first unblocked task. Do not start Develop or
+claim implementation readiness. The user chooses when execution begins.
 
-Claude Code and Codex are the acceptance runtimes. Verify both installed
-projections and use native vocabulary on each surface. Report unresolved
-questions last.
+## Authoring constraints
+
+- One mutable fact has one home; other files link to it.
+- A task is not a bucket for several independent outcomes.
+- Unknown outcomes become questions, not guessed requirements.
+- Ambiguous rules receive two or three examples before C2.
+- Ownership overlap or dependency uncertainty prevents a parallel claim.
+- A command that cannot be run from the named work context is not verification.
+- User approval and test proof are different facts; never infer either.
+- Existing legacy specs remain untouched unless migration is explicitly asked.
+
+## Output
+
+End with:
+
+```text
+Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+Files: <plan and task paths>
+C1: <decision>
+C2: <accepted/rejected/revised counts>
+Next: <first unblocked task or blocker>
+Unresolved questions: <none or concise list>
+```

package/src/claude/gitignore

@@ -1,4 +1,4 @@
-# CafeKit local runtime (.claude/ or .opencode/)
+# CafeKit local runtime (.claude/)
 # Also ignored at project root by the installer. This file protects
 # force-adds (`git add -f`) and partial un-ignores of the runtime folder.
 

package/src/claude/hooks/__tests__/spec-gate.test.js

@@ -78,6 +78,40 @@ function bindFixtureReceipt(dir, value) {
   return value.replaceAll(VALID_BASE, context.base).replaceAll(VALID_HEAD, context.head);
 }
 
+function workflowRuntimeContext(dir) {
+  return PROVENANCE.deriveRuntimeContext({
+    projectRoot: dir,
+    specsRoot: path.join(dir, 'specs'),
+    specFile: path.join(dir, 'specs', FEATURE, 'plan.md'),
+    featureName: FEATURE,
+    runtimeSession: 'test',
+  });
+}
+
+function makeWorkflowFixture(receiptLines = [], plannedCommand = 'node --test') {
+  const dir = tmpDir();
+  const featureDir = path.join(dir, 'specs', FEATURE);
+  fs.mkdirSync(featureDir, { recursive: true });
+  fs.writeFileSync(path.join(featureDir, 'plan.md'), '# Demo plan\n');
+  const context = workflowRuntimeContext(dir);
+  const task = [
+    '# Task 01: demo',
+    '',
+    'Status: done',
+    '',
+    '## Verification Plan',
+    '',
+    `- Command: ${plannedCommand}`,
+    '',
+    ...receiptLines,
+    '',
+  ].join('\n')
+    .replaceAll(VALID_BASE, context.base)
+    .replaceAll(VALID_HEAD, context.head);
+  fs.writeFileSync(path.join(featureDir, 'task-01-demo.md'), task);
+  return dir;
+}
+
 function installFeatureReceipt(dir, featureName = FEATURE, session = 'test') {
   const featureDir = path.join(dir, 'specs', featureName);
   const specFile = path.join(featureDir, 'spec.json');
@@ -1241,3 +1275,131 @@ test('30. phantom vectors via gate evidence must block with verification_state (
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
+
+test('31. process-v3 done task without inline Receipt blocks', () => {
+  const dir = makeWorkflowFixture();
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body, 'missing process-v3 receipt should block');
+    assert.strictEqual(body.decision, 'block');
+    assert.match(body.reason, /missing_receipt/);
+    assert.match(body.reason, /## Receipt/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('32. process-v3 requires Receipt heading and runtime-bound provenance', () => {
+  const legacyHeading = makeWorkflowFixture([
+    '## Evidence', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', 'pass', '```',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, legacyHeading).stdout);
+    assert.ok(body, 'legacy Evidence heading must not satisfy process-v3 receipt');
+    assert.match(body.reason, /missing_receipt/);
+  } finally {
+    fs.rmSync(legacyHeading, { recursive: true, force: true });
+  }
+
+  const stale = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_BASE}`, '```text', 'pass', '```',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, stale).stdout);
+    assert.ok(body, 'stale process-v3 provenance should block');
+    assert.match(body.reason, /provenance/);
+  } finally {
+    fs.rmSync(stale, { recursive: true, force: true });
+  }
+});
+
+test('33. process-v3 done task with canonical inline Receipt passes', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', '$ node --test', 'pass: 1', '```',
+  ]);
+  try {
+    clearCache();
+    const result = runHook({}, dir);
+    assert.strictEqual(result.code, 0, result.stderr);
+    assert.strictEqual(result.stdout, '');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('34. process-v3 Receipt command must match the exact Verification Plan command', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: true', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', '$ true', 'pass: 1', '```',
+  ], 'pnpm test');
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body, 'a substituted receipt command must block');
+    assert.strictEqual(body.decision, 'block');
+    assert.match(body.reason, /command_identity/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('35. process-v3 Stop ignores a completed packet when one packet remains active', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', '$ node --test', 'pass: 1', '```',
+  ]);
+  try {
+    const activeDir = path.join(dir, 'specs', 'active');
+    fs.mkdirSync(activeDir, { recursive: true });
+    fs.writeFileSync(path.join(activeDir, 'plan.md'), '# Active plan\n');
+    fs.writeFileSync(path.join(activeDir, 'task-01-active.md'), [
+      '# Task 01: active', '', 'Status: pending', '',
+      '## Verification Plan', '', '- Command: node --test', '',
+    ].join('\n'));
+    clearCache();
+    const result = runHook({}, dir);
+    assert.strictEqual(result.code, 0, result.stderr);
+    assert.strictEqual(result.stdout, '');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('36. process-v3 Stop accepts two completed packets with valid Receipts', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', '$ node --test', 'pass: 1', '```',
+  ]);
+  try {
+    const otherDir = path.join(dir, 'specs', 'other');
+    fs.mkdirSync(otherDir, { recursive: true });
+    fs.writeFileSync(path.join(otherDir, 'plan.md'), '# Other plan\n');
+    const context = PROVENANCE.deriveRuntimeContext({
+      projectRoot: dir,
+      specsRoot: path.join(dir, 'specs'),
+      specFile: path.join(otherDir, 'plan.md'),
+      featureName: 'other',
+      runtimeSession: 'test',
+    });
+    fs.writeFileSync(path.join(otherDir, 'task-01-other.md'), [
+      '# Task 01: other', '', 'Status: done', '',
+      '## Verification Plan', '', '- Command: node --test', '',
+      '## Receipt', '',
+      'Verification: PASS', 'Command: node --test', 'Exit: 0',
+      `Base: ${context.base}`, `Head: ${context.head}`,
+      '```text', '$ node --test', 'pass: 1', '```', '',
+    ].join('\n'));
+    clearCache();
+    const result = runHook({}, dir);
+    assert.strictEqual(result.code, 0, result.stderr);
+    assert.strictEqual(result.stdout, '');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/claude/hooks/lib/context.cjs

@@ -2,7 +2,7 @@
 /**
  * context.cjs - Context/reminder building for session injection
  *
- * Extracted from hooks for reuse in both Claude hooks and OpenCode plugins.
+ * Extracted from hooks for reuse across runtime adapters.
  * Builds session context, rules, paths, and plan information.
  *
  * @module context

package/src/claude/hooks/lib/detect.cjs

@@ -2,7 +2,7 @@
 /**
  * detect.cjs - Project and environment detection logic
  *
- * Extracted from session.cjs for reuse in both Claude hooks and OpenCode plugins.
+ * Extracted from session.cjs for reuse across runtime adapters.
  * Detects project type, package manager, framework, and runtime versions.
  *
  * @module detect

package/src/claude/hooks/spec-gate.cjs

@@ -93,6 +93,7 @@ try {
     if (typeof POLICY.validateCanonicalReceipt !== 'function'
       || typeof POLICY.completionDecisionForSpec !== 'function'
       || typeof RECEIPT.checkTaskReceipt !== 'function'
+      || typeof RECEIPT.checkWorkflowReceiptSet !== 'function'
       || typeof FINAL_STATE.evaluateCloseout !== 'function') {
       throw new Error('shared workflow policy lacks completion authority functions');
     }
@@ -112,8 +113,37 @@ try {
   } catch { /* gate stays on */ }
   // Active-spec discovery via shared resolver — explicit target if present, else fail on ambiguity.
   const baseDir   = cwd;
-  const resolved = FINAL_STATE.resolveCandidate({ resolver: RESOLVER, projectRoot: baseDir, runtime, payload });
+  const target = typeof RESOLVER.extractExplicitTarget === 'function'
+    ? RESOLVER.extractExplicitTarget(payload)
+    : null;
+  let resolved = typeof RESOLVER.resolveWorkflowCandidate === 'function'
+    ? RESOLVER.resolveWorkflowCandidate({ projectRoot: baseDir, runtime, target, includeCompleted: true })
+    : FINAL_STATE.resolveCandidate({ resolver: RESOLVER, projectRoot: baseDir, runtime, payload });
+  if (typeof RESOLVER.refineWorkflowGateResolution === 'function') {
+    resolved = RESOLVER.refineWorkflowGateResolution(resolved);
+  }
   if (!resolved) process.exit(0);
+  if (resolved.layoutKind === 'process-v3-completed-set') {
+    const configuredGate = runtime.spec?.completion_gate;
+    if (configuredGate !== undefined && configuredGate !== true) {
+      emitBlock('Completion gate: runtime.spec.completion_gate is a worker-writable flag, not an authorization; no completion-gate bypass is supported. Remove the flag and satisfy the gate.');
+      process.exit(0);
+    }
+    const checked = RECEIPT.checkWorkflowReceiptSet(
+      resolved.candidates,
+      baseDir,
+      sessionIdentity(payload),
+      POLICY,
+    );
+    if (checked.failures.length === 0) process.exit(0);
+    const lines = [`⚠️ Completion gate: ${checked.failures.length} done task(s) lack a verification receipt.`];
+    for (const failure of checked.failures) {
+      lines.push(`- \`${failure.featureName}/${failure.taskPath}\`: failed check(s) ${failure.failures.join(', ')}`);
+      lines.push(`  Fix: write a runtime-bound \`## Receipt\` with the planned command in \`specs/${failure.featureName}/${failure.taskPath}\`.`);
+    }
+    emitBlock(lines.slice(0, 8).join('\n'));
+    process.exit(0);
+  }
   if (resolved.error === 'multiple_active' || resolved.error === 'multiple_persisted') {
     process.stdout.write(JSON.stringify({
       decision: 'block',
@@ -137,13 +167,14 @@ try {
   }
   if (resolved.error) process.exit(0);
 
-  const activeSpec = resolved.spec;
+  const activeSpec = resolved.spec || {};
+  const processWorkflow = resolved.layoutKind === 'process-v3';
   const featureName = resolved.featureName;
   const specsPath = resolved.specsDir;
   const lifecyclePhase = activeSpec.current_phase || activeSpec.phase;
   const explicitCloseout = ['done', 'completed', 'complete'].includes(activeSpec.status)
     || ['closeout', 'completion', 'completed', 'complete'].includes(lifecyclePhase);
-  if (activeSpec.schema_version === '2.1') {
+  if (!processWorkflow && activeSpec.schema_version === '2.1') {
     const finalState = FINAL_STATE.evaluateCloseout({
       resolver: RESOLVER,
       policy: POLICY,
@@ -160,7 +191,7 @@ try {
   const runtimeContext = POLICY.deriveRuntimeContext({
     projectRoot: baseDir,
     specsRoot: specsPath,
-    specFile: resolved.specFile || path.join(specsPath, featureName, 'spec.json'),
+    specFile: resolved.stateFile || resolved.specFile || path.join(specsPath, featureName, 'spec.json'),
     featureName,
     runtimeSession: sessionIdentity(payload),
   });
@@ -170,7 +201,7 @@ try {
     emitBlock('Completion gate: runtime.spec.completion_gate is a worker-writable flag, not an authorization; no completion-gate bypass is supported. Remove the flag and satisfy the gate.');
     process.exit(0);
   }
-  const taskRegistry = activeSpec.task_registry || {};
+  const taskRegistry = resolved.taskRegistry || activeSpec.task_registry || {};
   const cacheFile = path.join(__dirname, '.logs', 'spec-gate-last.json');
   const cacheExists = fs.existsSync(cacheFile);
   let cache = {};
@@ -183,7 +214,7 @@ try {
     currentStatuses[tp] = task?.status || 'pending';
   }
 
-  const staleFlashTasks = Object.entries(taskRegistry)
+  const staleFlashTasks = processWorkflow ? [] : Object.entries(taskRegistry)
     .filter(([, task]) => POLICY.isStaleFlashDone(task))
     .map(([taskPath]) => taskPath);
   if (staleFlashTasks.length > 0) {
@@ -206,11 +237,13 @@ try {
   const failures = allDoneTasks
     .map((taskPath) => ({
       taskPath,
-      fails: RECEIPT.checkTaskReceipt(featureDir, taskPath, taskRegistry[taskPath], runtimeContext, POLICY).failures,
+      fails: processWorkflow
+        ? RECEIPT.checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, POLICY).failures
+        : RECEIPT.checkTaskReceipt(featureDir, taskPath, taskRegistry[taskPath], runtimeContext, POLICY).failures,
     }))
     .filter((f) => f.fails.length > 0);
 
-  const featureCloseoutRequired = explicitCloseout && allDoneTasks.length > 0;
+  const featureCloseoutRequired = !processWorkflow && explicitCloseout && allDoneTasks.length > 0;
   const featureReceipt = featureCloseoutRequired
     ? RECEIPT.checkFeatureReceipt(featureDir, runtimeContext, POLICY)
     : null;
@@ -253,7 +286,9 @@ try {
     lines.push(`- \`${taskPath}\`: failed check(s) ${fails.join(', ')}`);
     lines.push(taskPath === 'feature-receipt.md'
       ? `  Fix: run final integration proof, then write \`specs/${featureName}/feature-receipt.md\`.`
-      : `  Fix: write canonical proof to \`specs/${featureName}/receipts/${path.posix.basename(taskPath)}\`; legacy \`## Evidence\` remains read-compatible.`);
+      : processWorkflow
+        ? `  Fix: write a runtime-bound \`## Receipt\` with command output in \`specs/${featureName}/${path.posix.basename(taskPath)}\`.`
+        : `  Fix: write canonical proof to \`specs/${featureName}/receipts/${path.posix.basename(taskPath)}\`; legacy \`## Evidence\` remains read-compatible.`);
   }
   if (completionBlocked) {
     lines.push(`- Completion decision unfinished: ${completion.blocker || 'required workflow proof is missing.'}`);