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

package/src/claude/scripts/spec-resolver.cjs

@@ -68,6 +68,105 @@ function candidateError(reason, code = 'malformed') {
   return error;
 }
 
+const WORKFLOW_STATUSES = new Set(['pending', 'in_progress', 'paused', 'blocked', 'done']);
+const WORKFLOW_TASK_NAME = /^task-[A-Za-z0-9][A-Za-z0-9._-]*\.md$/;
+
+function workflowTaskStatus(content, taskName) {
+  const matches = String(content || '').matchAll(/^\s*(?:\*\*)?Status(?:\*\*)?\s*:\s*(?:\*\*)?\s*([A-Za-z_-]+)(?:\*\*)?\s*$/gim);
+  const values = [...matches].map((match) => match[1].toLowerCase().replaceAll('-', '_'));
+  if (values.length !== 1 || !WORKFLOW_STATUSES.has(values[0])) {
+    throw candidateError(`${taskName} must contain exactly one supported Status field`);
+  }
+  return values[0];
+}
+
+function inspectWorkflowFeature(specsDir, canonicalSpecs, requestedName) {
+  const featureDir = path.join(specsDir, requestedName);
+  let featureLstat;
+  try {
+    featureLstat = fs.lstatSync(featureDir);
+  } catch (error) {
+    if (isMissingError(error)) return { missing: true };
+    throw candidateError(`feature lstat error: ${error.message}`);
+  }
+  if (featureLstat.isSymbolicLink() || !featureLstat.isDirectory()) {
+    throw candidateError('workflow feature entry must be a regular directory');
+  }
+
+  const canonicalFeature = fs.realpathSync(featureDir);
+  if (!isPathInside(canonicalSpecs, canonicalFeature) || path.dirname(canonicalFeature) !== canonicalSpecs) {
+    throw candidateError('workflow feature directory must be a direct child of specs root');
+  }
+
+  const featureName = path.basename(canonicalFeature);
+  if (fs.existsSync(path.join(canonicalFeature, 'spec.json'))) {
+    return { legacyPresent: true, featureName, featureDir: canonicalFeature };
+  }
+
+  const planFile = path.join(canonicalFeature, 'plan.md');
+  let planLstat;
+  try {
+    planLstat = fs.lstatSync(planFile);
+  } catch (error) {
+    if (isMissingError(error)) return { missingWorkflow: true, featureName, featureDir: canonicalFeature };
+    throw candidateError(`plan.md lstat error: ${error.message}`);
+  }
+  if (planLstat.isSymbolicLink() || !planLstat.isFile() || fs.realpathSync(planFile) !== planFile) {
+    throw candidateError('plan.md must be a regular non-symlink file in the workflow feature directory');
+  }
+
+  const taskNames = fs.readdirSync(canonicalFeature, { withFileTypes: true })
+    .filter((entry) => WORKFLOW_TASK_NAME.test(entry.name))
+    .map((entry) => entry.name)
+    .sort();
+  if (taskNames.length === 0) {
+    return { missingWorkflow: true, featureName, featureDir: canonicalFeature };
+  }
+
+  const tasks = taskNames.map((taskName) => {
+    const taskFile = path.join(canonicalFeature, taskName);
+    const taskLstat = fs.lstatSync(taskFile);
+    if (taskLstat.isSymbolicLink() || !taskLstat.isFile() || fs.realpathSync(taskFile) !== taskFile) {
+      throw candidateError(`${taskName} must be a regular non-symlink file in the workflow feature directory`);
+    }
+    return {
+      path: taskName,
+      status: workflowTaskStatus(fs.readFileSync(taskFile, 'utf8'), taskName),
+    };
+  });
+  const taskRegistry = Object.fromEntries(tasks.map((task) => [task.path, { status: task.status }]));
+  const allTasksDone = tasks.every((task) => task.status === 'done');
+  return {
+    layoutKind: 'process-v3',
+    featureName,
+    specsDir: canonicalSpecs,
+    featureDir: canonicalFeature,
+    planFile,
+    stateFile: planFile,
+    phase: allTasksDone ? 'done' : 'execution',
+    taskRegistry,
+    tasks,
+    allTasksDone,
+  };
+}
+
+function normalizeLegacyWorkflowCandidate(candidate) {
+  const registry = candidate.spec?.task_registry || {};
+  const tasks = Object.entries(registry).map(([taskPath, task]) => ({
+    path: taskPath,
+    status: task?.status || 'pending',
+  }));
+  return {
+    ...candidate,
+    layoutKind: 'legacy-spec',
+    stateFile: candidate.specFile,
+    phase: candidate.spec?.current_phase || candidate.spec?.phase || 'unknown',
+    taskRegistry: registry,
+    tasks,
+    allTasksDone: tasks.length > 0 && tasks.every((task) => task.status === 'done'),
+  };
+}
+
 function inspectFeature(specsDir, canonicalSpecs, requestedName) {
   const featureDir = path.join(specsDir, requestedName);
   let featureLstat;
@@ -491,6 +590,193 @@ function resolvePersistedSpec({ projectRoot, runtime, explicitFeature, explicitP
   }
 }
 
+function scanWorkflowFeatures(specsDir) {
+  let canonicalSpecs;
+  try {
+    canonicalSpecs = fs.realpathSync(specsDir);
+  } catch (error) {
+    if (isMissingError(error)) return { active: [], candidates: [], invalid: [] };
+    return { active: [], candidates: [], invalid: [{ featureName: '<specs>', reason: error.message }] };
+  }
+
+  const active = [];
+  const candidates = [];
+  const invalid = [];
+  const entries = fs.readdirSync(canonicalSpecs, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+    .sort((left, right) => left.name.localeCompare(right.name));
+  for (const entry of entries) {
+    try {
+      const candidate = inspectWorkflowFeature(canonicalSpecs, canonicalSpecs, entry.name);
+      if (candidate.missing || candidate.missingWorkflow || candidate.legacyPresent) continue;
+      candidates.push(candidate);
+      if (!candidate.allTasksDone) active.push(candidate);
+    } catch (error) {
+      invalid.push({ featureName: entry.name, reason: error.message, planFile: path.join(canonicalSpecs, entry.name, 'plan.md') });
+    }
+  }
+  return { active, candidates, invalid };
+}
+
+function explicitWorkflowFeatureName({ projectRoot, specsDir, explicitFeature, explicitPath }) {
+  if (explicitFeature !== undefined && explicitFeature !== null) {
+    if (typeof explicitFeature !== 'string' || explicitFeature.trim() === ''
+      || explicitFeature.includes('/') || explicitFeature.includes('\\') || explicitFeature.includes('..')) {
+      return { error: 'explicit_malformed', explicitFeature, reason: `malformed feature name: ${explicitFeature}` };
+    }
+    return { featureName: explicitFeature.trim() };
+  }
+
+  if (typeof explicitPath !== 'string' || explicitPath.trim() === '') {
+    return { error: 'explicit_malformed', explicitPath, reason: 'empty explicit path' };
+  }
+  const targetPath = path.resolve(projectRoot, explicitPath);
+  let targetLstat;
+  try {
+    targetLstat = fs.lstatSync(targetPath);
+  } catch (error) {
+    return isMissingError(error)
+      ? { error: 'explicit_not_found', explicitPath, reason: `workflow target not found at ${explicitPath}` }
+      : { error: 'explicit_malformed', explicitPath, reason: `explicit path stat error: ${error.message}` };
+  }
+  if (targetLstat.isSymbolicLink()) {
+    return { error: 'explicit_malformed', explicitPath, reason: 'explicit workflow target must not be a symlink' };
+  }
+
+  let featureDir;
+  if (targetLstat.isDirectory()) {
+    featureDir = targetPath;
+  } else if (targetLstat.isFile()
+    && (path.basename(targetPath) === 'plan.md' || WORKFLOW_TASK_NAME.test(path.basename(targetPath)))) {
+    featureDir = path.dirname(targetPath);
+  } else {
+    return { error: 'explicit_malformed', explicitPath, reason: 'explicit workflow path must target a feature directory, plan.md, or flat task-*.md' };
+  }
+  const relative = path.relative(path.resolve(specsDir), featureDir);
+  if (!relative || relative.includes(path.sep) || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    return { error: 'explicit_malformed', explicitPath, reason: 'explicit workflow path must target a direct child of specs root' };
+  }
+  return { featureName: relative };
+}
+
+/**
+ * Resolve the authoring/execution workflow visible to prompt and Stop hooks.
+ * Persisted spec resolution remains unchanged; process-v3 is an additive adapter
+ * and never becomes completion-authority input by way of findAllSpecCandidates.
+ */
+function resolveWorkflowCandidate({ projectRoot, runtime, explicitFeature, explicitPath, target, includeCompleted = false } = {}) {
+  if (!projectRoot) throw new TypeError('projectRoot required');
+  const normalized = extractExplicitTarget(
+    target,
+    explicitFeature !== undefined ? { explicitFeature } : null,
+    explicitPath !== undefined ? { explicitPath } : null,
+  );
+  if (normalized) {
+    if (Object.prototype.hasOwnProperty.call(normalized, 'explicitFeature')) explicitFeature = normalized.explicitFeature;
+    if (Object.prototype.hasOwnProperty.call(normalized, 'explicitPath')) explicitPath = normalized.explicitPath;
+  }
+  const hasExplicit = explicitFeature !== undefined && explicitFeature !== null
+    || explicitPath !== undefined && explicitPath !== null;
+  let specsDir;
+  try {
+    specsDir = specsDirectory(projectRoot, runtime || {});
+  } catch (error) {
+    return { error: hasExplicit ? 'explicit_malformed' : 'invalid_specs', candidates: ['<specs>'], reason: error.message };
+  }
+
+  if (hasExplicit) {
+    const legacyDirect = resolveActiveSpec({ projectRoot, runtime, explicitFeature, explicitPath });
+    if (legacyDirect && !legacyDirect.error) return normalizeLegacyWorkflowCandidate(legacyDirect);
+    const identity = explicitWorkflowFeatureName({ projectRoot, specsDir, explicitFeature, explicitPath });
+    if (identity.error) return identity;
+
+    const legacy = resolveActiveSpec({ projectRoot, runtime, explicitFeature: identity.featureName });
+    if (legacy && !legacy.error) return normalizeLegacyWorkflowCandidate(legacy);
+    if (legacy && legacy.error !== 'explicit_not_found') return legacy;
+
+    let canonicalSpecs;
+    try {
+      canonicalSpecs = fs.realpathSync(specsDir);
+      const candidate = inspectWorkflowFeature(specsDir, canonicalSpecs, identity.featureName);
+      if (candidate.missing || candidate.missingWorkflow || candidate.legacyPresent) {
+        return { error: 'explicit_not_found', explicitFeature: identity.featureName, explicitPath, reason: `workflow not found for feature ${identity.featureName}` };
+      }
+      return candidate;
+    } catch (error) {
+      return { error: 'explicit_malformed', explicitFeature: identity.featureName, explicitPath, reason: error.message };
+    }
+  }
+
+  let legacyActive;
+  try {
+    const legacyCandidates = includeCompleted
+      ? findAllSpecCandidates(projectRoot, runtime || {})
+      : findAllActiveSpecs(projectRoot, runtime || {});
+    legacyActive = legacyCandidates.map(normalizeLegacyWorkflowCandidate);
+  } catch (error) {
+    return {
+      error: 'invalid_specs',
+      candidates: Array.isArray(error.invalid) ? error.invalid.map((entry) => entry.featureName) : ['<specs>'],
+      invalid: error.invalid || [],
+      reason: error.message,
+    };
+  }
+  const workflow = scanWorkflowFeatures(specsDir);
+  if (workflow.invalid.length > 0) {
+    return {
+      error: 'invalid_specs',
+      candidates: workflow.invalid.map((entry) => entry.featureName),
+      invalid: workflow.invalid,
+      reason: `Invalid workflow candidates: ${workflow.invalid.map((entry) => `${entry.featureName}: ${entry.reason}`).join('; ')}`,
+    };
+  }
+  const workflowCandidates = includeCompleted ? workflow.candidates : workflow.active;
+  const active = [...legacyActive, ...workflowCandidates]
+    .sort((left, right) => left.featureName.localeCompare(right.featureName));
+  if (active.length === 0) return null;
+  if (active.length === 1) return active[0];
+  return {
+    error: includeCompleted ? 'multiple_persisted' : 'multiple_active',
+    candidates: active.map((candidate) => candidate.featureName),
+    active,
+    reason: `Multiple ${includeCompleted ? 'persisted' : 'active'} workflows found: ${active.map((candidate) => candidate.featureName).join(', ')}. Provide explicit feature.`,
+  };
+}
+
+/**
+ * Narrow a Stop-gate ambiguity without changing legacy persisted-spec rules.
+ * A single unfinished process-v3 packet is the current workflow; completed
+ * packets are historical. If every process-v3 packet is complete, return the
+ * set so the gate can revalidate all receipts instead of blocking on identity.
+ */
+function refineWorkflowGateResolution(resolved) {
+  if (!resolved || resolved.error !== 'multiple_persisted' || !Array.isArray(resolved.active)) {
+    return resolved;
+  }
+  const candidates = resolved.active;
+  if (candidates.length === 0 || candidates.some((candidate) => candidate.layoutKind !== 'process-v3')) {
+    return resolved;
+  }
+
+  const unfinished = candidates.filter((candidate) => !candidate.allTasksDone);
+  if (unfinished.length === 1) return unfinished[0];
+  if (unfinished.length > 1) {
+    return {
+      ...resolved,
+      error: 'multiple_active',
+      candidates: unfinished.map((candidate) => candidate.featureName),
+      active: unfinished,
+      reason: `Multiple active workflows found: ${unfinished.map((candidate) => candidate.featureName).join(', ')}. Provide explicit feature.`,
+    };
+  }
+  return {
+    layoutKind: 'process-v3-completed-set',
+    candidates,
+    specsDir: candidates[0].specsDir,
+    allTasksDone: true,
+  };
+}
+
 module.exports = {
   specsDirectory,
   findAllActiveSpecs,
@@ -498,4 +784,6 @@ module.exports = {
   extractExplicitTarget,
   resolveActiveSpec,
   resolvePersistedSpec,
+  resolveWorkflowCandidate,
+  refineWorkflowGateResolution,
 };

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

@@ -1,187 +1,151 @@
 ---
 name: hapo:develop
-description: "Implement an explicitly invoked ready or low-risk change with policy-proportional evidence and one closeout owner."
+description: "Implement an explicitly requested process-first feature or task, run its real verification, and close it with one evidence owner. Also supports existing legacy Specs packets."
 user-invocable: true
-when_to_use: "Use to implement a ready spec, a specific task, or a Direct low-risk change."
+when_to_use: "Use to implement a ready feature packet, one named task, or a clear low-risk change."
 category: utilities
 keywords: [implementation, specs, verification]
 argument-hint: "[feature-name|specs-directory-path] [task-file] [--flash] [--parallel [N]] [--notes]"
 metadata:
   author: haposoft
-  version: "1.0.0"
+  version: "3.0.0"
 ---
-# Develop — implementation and closeout contract
+# Develop — implement, prove, synchronize
 
-Implement the requested scope, then close it with one canonical execution owner.
-For a durable spec, `spec.json` is machine authority and Markdown is a human
-projection. The v2.1 policy snapshot persists minimum input; lane, label,
-artifact profile, and ceremony are derived views. The executable policy source
-is `src/claude/scripts/workflow-policy.cjs` (installed as
-`.claude/scripts/workflow-policy.cjs`).
+Implement only the explicitly requested scope. For a process-first feature,
+`plan.md` and flat tasks are the durable packet; one closeout owner coordinates verification, review, sync, and docs impact without borrowing evidence.
+
+Develop never starts merely because Specs finished. The user invokes it.
 
 ## Usage and pre-state guard
 
 ```text
 /hapo:develop <feature>
 /hapo:develop specs/<feature>
-/hapo:develop <feature> <specific-task-file.md>
+/hapo:develop <feature> task-02-<slug>.md
 /hapo:develop <feature> --flash
 /hapo:develop <feature> --parallel [N]
 /hapo:develop <feature> --notes
 ```
 
-`--notes` is opt-in. Without it, do not create or update `implementation-notes.html`; there is no notes opt-out flag. When requested, load `references/implementation-notes-template.html` and record concrete decisions, gaps, scope-escape exceptions, risks, and verification caveats.
+`--notes` is opt-in. Only then load `references/implementation-notes-template.html`;
+record decisions, scope exceptions, risks, gaps, and verification limits. Never create it by default.
 
-Run the policy pre-state guard before loading a spec or mutating state. The incompatible pair must exit `2` and create no state, receipt, worktree, subagent, or commit: this is the `flash+parallel fail-fast` gate.
+Before any state mutation, reject `--flash` combined with `--parallel`:
 
 ```bash
 node .claude/scripts/workflow-policy.cjs --flash --parallel --json
 ```
 
-Expected message:
-
-```text
-Unsupported flags: --flash and --parallel are incompatible.
-Remediation: run `/hapo:develop <feature> --flash` or `/hapo:develop <feature> --parallel [N]`.
-No spec state, task receipt, worktree, subagent, or commit was created.
-```
-
-## Policy authority
-
-For durable specs, persisted `workflow_policy` authority is the v2.1 minimum.
-Canonical authoring supplies `planning_depth`, `assurance_level`,
-`classified_minimum`, and normalized `risks`; lane and ceremony remain derived
-views.
-
-Classify before spec/state mutation:
-
-```bash
-node .claude/scripts/workflow-policy.cjs --classify-lane --task-json '<task JSON>' --json
-```
-
-- **Direct**: clear, isolated, reversible, low-risk. Skip spec/state/registry ceremony and run targeted verification with proportional evidence.
-- **Standard**: use the bounded spec profile and focused inspection. A small feature needs no task registry/bundle and closes once at the feature boundary.
-- **Critical**: derived Strict view. Add durable task state, research, or review
-  only when actual topology, uncertainty, or assurance requires it.
+The pair exits `2` before a task edit, receipt, worktree, subagent, or commit. Do not reproduce it with a looser parser.
 
-Risk can raise the classified minimum. Reclassify before persistence. After
-persistence, a per-feature baseline is monotonic and no downgrade is supported
-until a trusted issuer exists; the baseline applies only to that feature.
-Legacy approval fields and caller booleans have zero authority.
+## Resolve the work packet
 
-Develop starts only from the user's explicit Develop invocation. Technical
-`ready_for_implementation` never dispatches Develop, and Specs must never
-auto-chain into this workflow.
+1. Resolve one `specs/<feature>/plan.md` plus flat `task-NN-*.md`; an explicit task path wins.
+2. Read C1 scope, exclusions, acceptance mapping, ownership, and task order.
+3. A task is unblocked only when every named dependency is done with a valid inline Receipt.
+4. Full-feature mode selects one unblocked task at a time, in plan order.
+   Specific-task mode implements only that task and then stops.
+5. Without a packet, work directly only when the change is clear, isolated, reversible, and low-risk.
 
-`execution_tier` (`Light | Standard | Deep`) is a read-only legacy adapter (`Direct | Standard | Critical`). It cannot emit policy, create obligations, select a workflow, or override the lane. Do not branch on it for new behavior.
+Ambiguity, overlapping ownership, a dependency cycle, or a missing Verification Plan is a blocker. Do not guess.
 
 ## Modes
 
-### Specific task
+### Sequential feature or specific task
 
-Load exactly one task packet, implement only its scope, run its evidence, and stop after synchronization. Specific-task mode never selects or chains into another pending task.
+Set the selected task's single `Status:` field to `in_progress`. Implement its
+Outcome and Acceptance only. Do not start the next task until proof, review,
+and sync for the current task finish. A specific-task invocation never chains.
 
-### Full feature
+### Parallel (`--parallel [N]`)
 
-For a task-bearing policy, resolve one unblocked task at a time, complete its cycle, synchronize, and recompute the queue. A bounded Standard feature without tasks runs one feature-level cycle. Stop on the first unresolved block or missing proof; run final integration only after all pending tasks finish.
+Load `references/parallel-waves.md`. Require disjoint writes, satisfied dependencies,
+isolated worktrees, a bounded wave, and one controller writer; otherwise work sequentially.
 
-### Parallel (opt-in)
+### Flash (`--flash`)
 
-Load `references/parallel-waves.md` only with `--parallel`. It may use isolated worktrees and a bounded wave, but lane obligations, single-writer rules, immutable provenance, and final integration remain in force. Otherwise process one unblocked task at a time.
+Flash is an explicit speed trade-off, never completion:
 
-### 3. Flash Mode (`--flash`)
-Flash is an explicit speed trade-off, not a completion shortcut:
-
-- skip dedicated test suites, full task evidence execution, and extended manual
-  checks;
-- run only a cheap available syntax/typecheck/compile preflight;
-- never weaken or delete tests;
-- synchronize only as `in_progress` with `FLASH_UNVERIFIED`,
-  `dependencyBlocked: true`, `unblocks: false`, and blocker
+- run only an available cheap syntax, typecheck, or compile preflight;
+- skip dedicated tests, extended manual checks, and review retry loops;
+- keep `Status: in_progress` and record `FLASH_UNVERIFIED` plus blocker
   `awaiting /hapo:test <feature>`;
-- never claim `Test PASS`, `Evidence PASS`, `Auto-Approved`, or
-  `production-ready`.
+- do not unblock dependents or report Test PASS, Evidence PASS,
+  production-ready, or done;
+- promotion later requires a fresh canonical PASS receipt through the trusted
+  sync-finalize path.
 
-Only trusted sync-finalize may promote a current `FLASH_UNVERIFIED` task with explicit `--verdict PASS` and canonical proof; caller promotion fields are ignored/rejected, and marker-only proof never promotes. Stored state remains `in_progress`/`FLASH_UNVERIFIED`, dependency-blocked with a concrete blocker, omits promotion fields, and binds proof to expected Base/Head anchors.
-## Workflow
-`Classify lane → load lane artifacts → scout obligations → implement current
-scope → one closeout owner → test receipt → review → docs-impact sync.`
+Never weaken, delete, or rewrite tests to make Flash look complete.
 
-### Step 1 — Load and scope
+## Task cycle
 
-- Direct does not create a spec, state, registry, task bundle, or notes file.
-- Standard requires its bounded validated artifacts, but not a
-  registry when the scope is small and no task obligation is persisted.
-- Critical requires only the artifacts named by its snapshot obligations.
-- For task-bearing work, load one requested task or one unblocked task and
-  extract the exact seven v2.1 sections: `Outcome`, `Scope`, `Anchors and Ownership`,
-  `Changes`, `Acceptance`, `Dependencies`, and `Verification Plan`.
-  Use typed `coordination.boundaries` for ownership/DAG/proof/parallel authority.
-- Before implementation, transition `pending` to `in_progress` in task Markdown `**Status:**` and `spec.json.task_registry[path]` with synchronized timestamps. Never write execution proof into the task plan.
-- A spec-ready execution-evidence or independent-audit slot may be `PENDING`
-  before implementation; pending is not proof and cannot close the feature.
+### 1. Scout
 
-### Step 2 — Scout
+Trace entrypoints, callers, dependents, registration, errors, and owned files.
+Compilation does not prove an unmounted UI, unregistered route, uncalled service, or missing consumer.
 
-Scout depth follows assurance, risk, and blast radius. Identify real
-entrypoints/callers, integration points, dependents, reachability risks, and
-safe scope. File count is not review depth; stop if a runtime entrypoint cannot
-be grounded.
+### 2. Implement
 
-### Step 3 — Implement
+Honor Scope, Ownership, Acceptance, and Dependencies. Do not silently replace named contracts;
+scope expansion requires evidence and a return to C1, not implementation convenience.
 
-Implement only the scoped behavior and named contracts. Do not silently replace
-frameworks, auth, transport, storage, or runtime boundaries. Do not mark a
-runtime-facing file complete while it is orphaned, unmounted, unregistered, or
-uncalled. A specific-task request ends after that task; no automatic chain.
+### 3. Verify and review once
 
-<SCOPE-FIDELITY>
-The `scope_lock`, requirements, design contracts, and active task are
-the implementation contract. Scope escape requires a concrete reachability or
-compile reason and must not deliver a later task early.
-</SCOPE-FIDELITY>
+The test owner executes the exact Verification Plan and records real output.
+The review owner, when risk or repository policy requires review, evaluates
+correctness, security, scope, and reachability but does not manufacture proof.
+Use `PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED`; only literal PASS can close.
 
-### Step 4 — Closeout owner
+Load `references/quality-gate.md` for the closeout contract. Remediate an
+observed failure, then rerun only affected proof and review. Do not blind-retry
+a blocked environment. After three failed repair rounds, stop and ask the user.
 
-The controller assigns exactly one closeout owner for the current task or feature. It invokes testing once, then review once when required; no phase re-runs either as a hidden gate.
+### 4. Write the inline Receipt and sync
 
-- For task-bearing work, the test owner executes the Verification Plan and writes the canonical execution receipt to `receipts/<task-basename>.md` only after real execution.
-- The review owner evaluates correctness, security, and spec compliance; it
-  consumes existing proof but never creates or claims execution proof.
-- Review depth follows `assurance_level`, risk, and blast radius. Lane is only
-  a derived view, and depth does not follow the
-  number of files changed.
-- Finding count never selects review depth or overrides missing execution proof.
-- Use the shared adapter surface: `PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED`.
-  Warnings do not waive missing proof; `FAIL` is remediable and `BLOCKED` stops.
+After a real pass, append or replace the task's final `## Receipt` with:
 
-Load `references/quality-gate.md` for the exact closeout contract. It has no
-fixed Light/Standard/Deep agent sequence.
+- `Verification: PASS`;
+- the exact `Command:` and `Exit: 0`;
+- runtime-derived `Base:` and `Head:`;
+- a non-empty fenced block containing current command output;
+- required negative, reachability, and artifact proof from the task.
 
-### Step 5 — Sync and docs checkpoint
+Then set `Status: done`, update only implemented checkboxes, and recompute the
+queue. Missing, stale, contradictory, zero-test, placeholder, or marker-only
+proof leaves the task unfinished.
 
-Only a canonical receipt with task identity/path, exact command/result, expected versus observed behavior, bound provenance, applicable negative/reachability proof, and required artifact hashes can close a task. Prefer `receipts/<task-basename>.md`; legacy task `## Evidence` is read-compatible, but conflicting proof identities fail closed. Missing, pending, marker-only, or contradictory evidence stays unfinished. Critical audits need distinct session IDs, expected Base/Head binding, concrete evidence, and literal `verdict: "PASS"`; `Audit: PASS` is not evidence.
-After verification, synchronize status/timestamps/task state. Then evaluate
-actual docs impact:
+### 5. Finish the requested boundary
 
-- `none`: record it and stop;
-- `minor`/`major`: update only affected existing docs through the normal docs
-  workflow, with no broad refresh.
+Specific-task mode stops after its sync. Full-feature mode continues one task
+at a time, then runs the feature-level integration command and reachability
+check named by the repository or plan. Show current evidence and limitations at
+C3; the user decides completion.
 
-Do not run a docs checkpoint merely because a task finished.
+Evaluate docs impact from the behavior actually changed:
 
-## Definition of done and handoff
+- `none`: report it and make no docs edit;
+- `minor` or `major`: update only affected existing docs through the docs flow.
 
-Done requires active criteria, all required evidence, reachable runtime behavior,
-a receipt bound to expected Base/Head, and every lane obligation. Only literal
-`PASS` can complete; `PASS_WITH_WARNINGS` remains unfinished.
-`--flash` records only `FLASH_UNVERIFIED` and never done.
+## Definition of done
 
-For a full feature, after the last task run the **Final Integration Scout** for runtime-facing surfaces and compare reachability/scope before completion. The same test owner creates `feature-receipt.md` exactly once from final integration proof. Task-bearing closeout requires every task receipt plus that feature receipt; taskless Compact/Full creates only the feature receipt at closeout. Its earlier absence is normal. A specific task stops after synchronization and creates no feature receipt unless it also completes the full integration boundary.
+Done requires satisfied acceptance, reachable behavior, current executable
+proof, correct Base/Head binding, resolved blocking review findings, and no
+scope substitution. `PASS_WITH_WARNINGS`, `NO_TESTS`, `FLASH_UNVERIFIED`, or a
+review-only pass cannot close work.
 
 ## Attached references
 
-- `references/quality-gate.md` — closeout ownership, verdict normalization, and
-  evidence checks.
-- `references/parallel-waves.md` — opt-in worktree waves.
-- `references/implementation-notes-template.html` — loaded only with `--notes`.
+- `references/quality-gate.md` — proof and review ownership.
+- `references/parallel-waves.md` — opt-in isolated worktree waves.
+- `references/implementation-notes-template.html` — only with `--notes`.
+
+## Legacy workflow compatibility
+
+If the selected feature contains `spec.json`, use its persisted
+`workflow_policy`, `task_registry`, nested task paths, typed boundaries,
+separate task receipts, and feature closeout receipt exactly as the legacy
+adapters require. Preserve `planning_depth`, `assurance_level`, derived lane,
+and read-only `execution_tier`; do not project these fields into a new v3
+packet. Keep JSON and Markdown status synchronized, and use the existing
+completion-authority path for final closeout.