ai-delivery-workflow 0.5.0 → 0.6.0

package/lib/toml-hooks.mjs

@@ -14,7 +14,6 @@ export const HOOK_EVENTS = [
 ];
 
 const HOOK_COMMAND = "node .workflow/tools/hooks/hook-event.mjs";
-const LEGACY_HOOK_COMMAND = "node .ai-delivery/hooks/hook-event.mjs";
 
 function hookBlock(event, newline) {
   return [
@@ -102,9 +101,8 @@ export function mergeHookConfig(existing, { force = false } = {}) {
   const newline = existing.includes("\r\n") ? "\r\n" : "\n";
   let text = existing.trimEnd();
   const actions = [];
-  if (text.includes(LEGACY_HOOK_COMMAND)) {
-    text = text.replaceAll(LEGACY_HOOK_COMMAND, HOOK_COMMAND);
-    actions.push("migrate AI delivery Hook command into .workflow/tools");
+  if (text.includes("node .ai-delivery/hooks/hook-event.mjs")) {
+    throw new Error("Unsupported legacy Hook command; remove the .ai-delivery handler before installing the current Hook.");
   }
   if (force) {
     const refreshed = removeDeliveryHandlerBlocks(text);

package/lib/workflow-manager-governance.mjs

@@ -24,7 +24,6 @@ export const WORKFLOW_MANAGER_GOVERNANCE_SCHEMA_VERSION = "workflow-manager.gove
 const RELATIONS_FILE = ".workflow/control/relations.yaml";
 const SETTINGS_FILE = ".workflow/config/manager-settings.json";
 const RECEIPTS_ROOT = ".workflow/control/receipts";
-const EVENTS_FILE = ".workflow/control/events/workflow-manager-events.jsonl";
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,191}$/;
 const SAFE_ENTITY_TYPE = /^[a-z][a-z0-9-]{0,63}$/;
 const RELATION_TYPES = new Set([
@@ -59,18 +58,6 @@ function contained(root, relative) {
   return absolute;
 }
 
-function atomicWrite(file, content) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
-  fs.writeFileSync(temporary, content, { encoding: "utf8", flag: "wx" });
-  try {
-    fs.renameSync(temporary, file);
-  } catch (error) {
-    fs.rmSync(temporary, { force: true });
-    throw error;
-  }
-}
-
 function requireHuman(actor) {
   if (!/^human:[A-Za-z0-9._@/-]+$/.test(String(actor || ""))) {
     throw new Error("Governed confirmation requires actor human:<identity>");
@@ -92,16 +79,13 @@ function receiptFiles(root) {
 
 function replay(root, action, input, subject = null) {
   if (!input.idempotency_key) return null;
-  const legacyRequestChecksum = checksum({ action, input });
-  const governedRequestChecksum = workflowManagerRequestChecksum(action, input, subject);
+  const expectedRequestChecksum = workflowManagerRequestChecksum(action, input, subject);
   for (const file of receiptFiles(root)) {
     try {
       const receipt = JSON.parse(fs.readFileSync(file, "utf8"));
       if (receipt.action !== action || receipt.idempotency_key !== input.idempotency_key) continue;
-      const legacy = receipt.request_checksum === legacyRequestChecksum;
-      const governed = receipt.request_checksum === governedRequestChecksum
-        && (receipt.subject ?? null) === subject;
-      if (!legacy && !governed) {
+      if (receipt.request_checksum !== expectedRequestChecksum
+          || (receipt.subject ?? null) !== subject) {
         throw new Error("Idempotency key was already used for a different request");
       }
       return receipt;
@@ -112,34 +96,6 @@ function replay(root, action, input, subject = null) {
   return null;
 }
 
-function record(root, action, input, detail = {}) {
-  const timestamp = new Date().toISOString();
-  const receipt = {
-    schema_version: 1,
-    receipt_id: `WMG-${crypto.randomUUID()}`,
-    action,
-    actor: input.actor,
-    idempotency_key: input.idempotency_key || null,
-    request_checksum: checksum({ action, input }),
-    applied_at: timestamp,
-    ...detail,
-  };
-  receipt.receipt_checksum = checksum(receipt);
-  atomicWrite(contained(root, `${RECEIPTS_ROOT}/${receipt.receipt_id}.json`), `${JSON.stringify(receipt, null, 2)}\n`);
-  const event = {
-    schema_version: 1,
-    event_id: `WME-${crypto.randomUUID()}`,
-    type: `workflow-manager.${action}`,
-    occurred_at: timestamp,
-    receipt_id: receipt.receipt_id,
-    subject: detail.subject || null,
-  };
-  const eventFile = contained(root, EVENTS_FILE);
-  fs.mkdirSync(path.dirname(eventFile), { recursive: true });
-  fs.appendFileSync(eventFile, `${JSON.stringify(event)}\n`, "utf8");
-  return { receipt, event };
-}
-
 function relationsDocument(root) {
   const file = contained(root, RELATIONS_FILE);
   if (!fs.existsSync(file)) return { file, document: { schema_version: 1, revision: 0, relations: [] }, checksum: null };

package/lib/workspace.mjs

@@ -4,7 +4,6 @@ import { spawnSync } from "node:child_process";
 import { parse as parseYaml, stringify as stringifyYaml } from "./yaml-runtime.mjs";
 
 export const WORKSPACE_CONFIG = path.join(".workflow", "config", "workspace.yaml");
-export const LEGACY_WORKSPACE_CONFIG = path.join(".ai-delivery", "workspace.yaml");
 
 function toPosix(value) {
   return value.replaceAll("\\", "/");
@@ -114,7 +113,7 @@ function initializeWorkflowRepository(workspaceRoot, branch, remote, heads, acti
     const current = gitBranch(workspaceRoot);
     if (current !== branch) {
       if (gitHasCommit(workspaceRoot)) {
-        throw new Error(`Existing workflow repository must already use ${branch}; automatic migration is not supported.`);
+        throw new Error(`Existing workflow repository must already use ${branch}; automatic branch changes are not supported.`);
       }
       if (!dryRun) runGit(workspaceRoot, ["symbolic-ref", "HEAD", `refs/heads/${branch}`]);
     }
@@ -172,7 +171,7 @@ export function validateCodePath(workspaceRoot, codePath = "code") {
   if (!normalized || normalized.includes("/") || normalized === "." || normalized === "..") {
     throw new Error("Code path must be a relative direct child directory.");
   }
-  if (new Set([".git", ".workflow", ".ai-delivery", ".agents", ".codex"]).has(normalized)) {
+  if (new Set([".git", ".workflow", ".agents", ".codex"]).has(normalized)) {
     throw new Error(`Reserved code path: ${normalized}`);
   }
   const absolute = path.resolve(workspaceRoot, normalized);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-delivery-workflow",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Project-scoped Codex skills and hooks for artifact-driven AI software delivery",
   "type": "module",
   "repository": {
@@ -22,7 +22,7 @@
     "skills"
   ],
   "scripts": {
-    "test": "node --test verification/*.test.mjs",
+    "test": "node --test --test-concurrency=4 verification/*.test.mjs",
     "manager:build": "npm --prefix manager run build",
     "skills:validate": "node bin/validate-skills.mjs",
     "audit:generate": "node audit/generate-all.mjs",

package/skills/ai-delivery-bootstrap/SKILL.md

@@ -44,7 +44,7 @@ The first product question is the safe stopping point. Do not invent the initial
 - `codebase-uninitialized`: use packaged `ai-delivery bootstrap`, review the repository baseline, inventory, context index, and adoption assessment, then invoke `$ai-delivery-define-product` to distinguish observed behavior from intended product behavior.
 - `workflow-interrupted`: do not write bootstrap artifacts. If `runtime.next_action_owner` is `user`, return the recorded `next_action` as the single business question and perform no recovery, activation, checkpoint, task, artifact, or Git mutation. If it is `external`, report the recorded wait condition without mutation. Only an `agent`-owned next action may invoke `$ai-delivery-checkpoint-task recover`, reconcile reality, inspect the pending Evolution queue without applying changes mid-task, and continue `recommended_task_id`. When required input arrives, transfer ownership with both `--next-action-owner agent` and a new idempotent `--next-action`.
 - `workflow-ready`: when a queued task is recommended, first apply the same `next_action_owner` boundary; activate it through `$ai-delivery-checkpoint-task` only when the owner is `agent`. Otherwise use the reported specialist skill or `$ai-delivery-orchestrate` to derive the next development node. Treat `release-ready` versions as completed development evidence, not implicit release intent. Route to `$ai-delivery-orchestrate-release` only when the user explicitly requests a release.
-- `workflow-inconsistent`: stop automatic mutation, run the available project/package doctor internally, report exact conflicts, and obtain a repair decision. An installed project must use packaged `upgrade --dry-run` for managed installation drift and `migrate --dry-run` for legacy schema, task grouping, anchor, or archive conflicts rather than repeat `init`. Structural migration copies legacy-root workflow material, adds explicit task attempts, and preserves lifecycle and scope facts; grouping ambiguities require a source-checksum-bound `--decisions` document with a `human:` actor and rationale. Route an approved premature-archive correction through packaged `repair --invalidate-archive` with a human actor, reason, RCA evidence, and recovery evidence; the original archive remains immutable. Use `upgrade --force` only when the user explicitly approves replacing the reported managed files.
+- `workflow-inconsistent`: stop automatic mutation, run the available project/package doctor internally, report exact conflicts, and obtain an explicit repair decision. Use `upgrade --dry-run` for current managed installation drift; malformed current state, missing anchors, archive conflicts, and checksum drift fail closed until repaired through the governed current-state interface. Use `upgrade --force` only when the user explicitly approves replacing the reported managed files.
 
 ## Brownfield Rules
 
@@ -52,6 +52,10 @@ Treat repository scans as observations, not approved product or architecture tru
 
 Do not replace existing product, architecture, test, or release baselines. Keep the project-state report and related observations outside the formal artifact registry while they remain working drafts, preserve every timestamped bootstrap run, and update only the `.workflow/delivery/bootstrap/latest.yaml` pointer.
 
+### Codebase Handbook Discovery
+
+For the configured nested code repository, inspect `AGENTS.md`, `CODEBASE_GUIDE.md`, and `docs/CODEBASE_INDEX.md` as read-only maintainer documents. The report records `observed`, `approved`, or `stale`; missing files are a warning, while malformed, path-invalid, symlink, or sensitive-content findings fail closed. Compare each declared `source_commit` with the code repository HEAD. Never infer an approved rule from the generated inventory, and never overwrite these files during bootstrap or upgrade.
+
 ## Resume Boundary
 
 Codex lifecycle Hooks provide audit and heartbeat data only. Versioned Evolution Hooks may return `pass`, `warn`, or an approved `block`, but they never select or complete tasks and never mutate formal workflow state. A bootstrap report may recommend recovery, but `$ai-delivery-checkpoint-task` remains authoritative for task order, dependency readiness, worktree reconciliation, and idempotent continuation. Route pending feedback and extension evaluation to `$ai-delivery-evolve-workflow` only at a task, version, or explicit review safe point.

package/skills/ai-delivery-bootstrap/references/bootstrap-contract.md

@@ -28,7 +28,7 @@ After installation, `node .workflow/tools/bootstrap/bootstrap.mjs inspect` is th
 
 `ai-delivery bootstrap <project-root>` may initialize only `empty-uninitialized` and `codebase-uninitialized` projects through the project-scoped installer. Preserve existing code and configuration. On partial or conflicting installation, return `workflow-inconsistent` without writes. `--force` is allowed only after explicit user approval.
 
-For an installed legacy or conflicting state, keep Bootstrap read-only. Use packaged `migrate --dry-run` to report schema conversion, semantic task groups and ambiguities, state/archive conflicts, verified anchors, and exact file changes. A legacy root migration copies `delivery/`, `control/`, and `standards/` into `.workflow/` while preserving source bytes; flat task shards gain explicit attempts with checksummed rollback backups. Resolve grouping ambiguities only through a checksum-bound `--decisions` document with a `human:` actor and rationale. Migration must not activate or close tasks, infer completion, change scope, or rewrite legacy events. Incorrect archives require the separate packaged `repair --invalidate-archive` forward transaction with an explicit human actor, reason, RCA evidence, and recovery evidence; the original archive bytes remain authoritative history.
+For an installed or conflicting state, keep Bootstrap read-only and return `workflow-inconsistent` with the failing path and remediation. Use the packaged `repair --invalidate-archive` forward transaction only for an explicitly identified archive integrity defect; it records a human actor, reason, RCA evidence, and recovery evidence without rewriting immutable history.
 
 For an uninitialized project, generate repository inventory and context artifacts from the first read-only scan snapshot. Do not let installer-generated `AGENTS.md`, `.gitignore`, Hook, skill, standard, or delivery files contaminate the observed pre-install codebase baseline.
 

package/skills/ai-delivery-checkpoint-task/SKILL.md

@@ -11,10 +11,6 @@ Treat explicit task snapshots as authoritative. Treat Hook events as an audit tr
 
 Write portable task state to `.workflow/control/tasks/<task-id>.yaml` and `.workflow/control/checkpoints/<task-id>/<checkpoint-id>.yaml`. Keep only PID, heartbeat, temporary locks, raw Hook events, and unshared context under ignored `.workflow/delivery/runtime/`. Keep durable node documents under `.workflow/iterations/<iteration-id>/<node-id>/`; runtime snapshots never replace registered delivery artifacts. Resolve code branch and commit from `.workflow/config/workspace.yaml` and the nested code repository.
 
-## Legacy Node Boundary
-
-Legacy development nodes are read-only compatibility. `inspect` remains a strictly read-only diagnosis path for historical tasks. `init`, `activate`, `checkpoint`, `finish`, and `archive-version` reject legacy task targets before mutation or Hook dispatch; `recover` refuses to materialize them and `publish` refuses to share them. New tasks use only the `development-seven-node` route, while `R00-release-request` through `R10-release-archive` remain writable.
-
 ## Start Or Resume
 
 1. Locate the project root and shared state root.
@@ -64,6 +60,8 @@ Checkpoint after every externally meaningful milestone, before a long command, a
 
 Use shared shards and the newest shared checkpoint as the portable recovery source. If local runtime is absent and `next_action_owner` is `agent`, `recover` restores it from shared state. For `user` or `external`, report the wait state without hydration; after the input arrives, `activate` performs the atomic hydration and owner transfer. If local and shared revisions or semantic checksums differ, stop for reconciliation. Inspect both Git repositories before resuming. Report pending `.workflow/delivery/runtime/evolution/pending/` events, but defer their evaluation until the recovered task reaches a safe point.
 
+Confirmation waits persist the summary path, question identity, frontier round, and an idempotent next action. `user` and `external` ownership remains strict zero-mutation wait until explicit input transfer.
+
 Generate a compact recovery report from snapshots, checkpoints, Hook events, Git, and workspace state. Return active work and failed tasks in `retryable_task_ids` by default; use `--include-closed` only when completed or abandoned details are required for an explicit audit. For each iteration, report total, completed, closed, remaining, active, retryable, queued, dependency-ready, and waiting tasks plus one deterministic `recommended_task_id`. Prefer an interrupted or active task, then the lowest-sequence failed task requiring `activate --new-attempt --phase repair`, then the lowest-sequence queued task whose dependencies are all `completed`. Resume only idempotent steps. Re-read production and external systems before any deployment recovery; never replay production deployment automatically.
 
 ## Hook Boundary

package/skills/ai-delivery-checkpoint-task/references/checkpoint-contract.md

@@ -34,7 +34,7 @@ Keep `.workflow/delivery/runtime/` local and ignored. Persist durable stage outp
 
 `task-state.mjs` is the only runtime-state writer. Do not directly edit task JSON, checkpoint JSON, active-task markers, recovery output, or archive indexes. Formal workflow and artifact state belong to `.workflow/tools/state/state.mjs`; do not edit its YAML or JSONL streams directly.
 
-Legacy development nodes are read-only compatibility. `inspect` remains read-only for historical task diagnosis. `init`, `activate`, `checkpoint`, `finish`, and `archive-version` reject legacy task targets before mutation or Hook dispatch; `recover` does not hydrate them and `publish` does not share them. New task contracts use only the `development-seven-node` route, while `R00-release-request` through `R10-release-archive` remain writable.
+Task contracts use the current `development-seven-node` route or the independent `R00-release-request` through `R10-release-archive` release route. `inspect` is read-only diagnosis; `init`, `activate`, `checkpoint`, `finish`, `recover`, `archive-version`, and `publish` operate only on current task contracts.
 
 When the installed Evolution CLI exists, `init`, `activate`, `checkpoint`, `finish`, and `archive-version` emit idempotent schema 1 `task.before`, `task.after`, and `task.failed` events. An approved blocking `task.before` result stops the task command before mutation. Hook dispatch failures otherwise fail open as warnings and never replace checkpoint state as the completion authority.
 
@@ -75,7 +75,9 @@ For an installed dual-repository project, `task-state.mjs` resolves `code_branch
 
 `blockers` represents current unresolved blockers. A `blocked` update replaces that list; any transition to another status clears it. Historical blocker text remains available in prior checkpoints and events.
 
-`next_action_owner` is required in persisted state and has exactly three values: `agent`, `user`, or `external`; only a truly absent field in a legacy snapshot defaults to `agent`, while explicit null, empty, boolean, numeric, or unknown values are invalid. `user` and `external` are zero-mutation wait states. `recover` may report shared wait state but must not hydrate local task or resume files for it. After the required input arrives, `activate` requires both `--next-action-owner agent` and a new idempotent `--next-action`; it may atomically hydrate a missing local runtime snapshot from the matching shared shard and transfer ownership in the same transition. Same-revision local and shared content must have identical semantic checksums. Evidence arrays are ordered sets: replaying an already recorded `--evidence` value does not append a duplicate.
+`next_action_owner` is required in persisted state and has exactly three values: `agent`, `user`, or `external`; explicit null, empty, boolean, numeric, or unknown values are invalid. `user` and `external` are zero-mutation wait states. `recover` may report shared wait state but must not hydrate local task or resume files for it. After the required input arrives, `activate` requires both `--next-action-owner agent` and a new idempotent `--next-action`; it may atomically hydrate a missing local runtime snapshot from the matching shared shard and transfer ownership in the same transition. Same-revision local and shared content must have identical semantic checksums. Evidence arrays are ordered sets: replaying an already recorded `--evidence` value does not append a duplicate.
+
+When waiting on a confirmation frontier, persist the summary path, `question_id`, `frontier_round`, and summary checksum in checkpoint evidence. Repeated answers are idempotent; superseding a decision appends a new record and never overwrites prior confirmation.
 
 Pass `--state-root` when worktrees must write to one shared primary state directory. Pass `--worktree` during init so the script writes a local `.workflow/delivery/runtime/active-task.json` marker pointing to that state root. Later `checkpoint`, `finish`, and `recover` commands automatically use the marker's shared state root.
 

package/skills/ai-delivery-checkpoint-task/scripts/hook-event.mjs

@@ -144,15 +144,9 @@ function enforceFrontendGuard(projectRoot, input) {
 }
 
 try {
-  const currentProjectFile = findUp(process.cwd(), path.join(".workflow", "delivery", "project.yaml"));
-  const legacyProjectFile = currentProjectFile
-    ? null
-    : findUp(process.cwd(), path.join("delivery", "project.yaml"));
-  const projectFile = currentProjectFile || legacyProjectFile;
+  const projectFile = findUp(process.cwd(), path.join(".workflow", "delivery", "project.yaml"));
   if (!projectFile) process.exit(0);
-  const projectRoot = currentProjectFile
-    ? path.dirname(path.dirname(path.dirname(projectFile)))
-    : path.dirname(path.dirname(projectFile));
+  const projectRoot = path.dirname(path.dirname(path.dirname(projectFile)));
   const markerFile = path.join(projectRoot, ".workflow", "delivery", "runtime", "active-task.json");
   const marker = fs.existsSync(markerFile) ? JSON.parse(fs.readFileSync(markerFile, "utf8")) : null;
   const raw = await readStdin();

package/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs

@@ -42,19 +42,13 @@ const REPEATABLE_ARGS = new Set([
   "completed-step", "blocker", "evidence", "depends-on", "acceptance", "finding-json",
   "change-set-json",
 ]);
-const LEGACY_DEVELOPMENT_NODE_IDS = new Set([
-  "01-product-discovery",
-  "02-product-definition",
-  "03-architecture-initial",
-  "04-experience-design",
-  "05-architecture-reconcile",
-  "06-platform-preparation",
-  "07-iteration-planning",
-  "08-test-design",
-  "09-development",
-  "10-change-review",
-  "11-candidate-verification",
-  "12-version-closeout",
+const VALID_NODE_IDS = new Set([
+  "00-bootstrap", "01-product-shaping", "02-solution-design", "03-delivery-readiness",
+  "04-implementation", "05-candidate-assurance", "06-version-closeout",
+  "R00-release-request", "R01-version-selection", "R02-release-eligibility", "R03-material-aggregation",
+  "R04-release-candidate", "R05-release-verification", "R06-release-preparation", "R07-production-approval",
+  "R08-production-deployment", "R09-production-verification", "R10-release-archive",
+  "development", "implementation", "planning", "test", "review",
 ]);
 
 function parseArgs(argv) {
@@ -83,10 +77,8 @@ function requireValue(args, key) {
   return value;
 }
 
-function assertNotLegacyDevelopmentNode(node) {
-  if (LEGACY_DEVELOPMENT_NODE_IDS.has(node)) {
-    throw new Error(`Legacy workflow node is read-only: ${node}`);
-  }
+function assertCurrentNode(node) {
+  if (!VALID_NODE_IDS.has(node)) throw new Error(`Unsupported workflow node: ${node}`);
   return node;
 }
 
@@ -720,7 +712,7 @@ function repairChangesSinceBaseline(workflowRoot, baseline) {
 }
 
 function writeSharedTask(runtime, workflowRoot, task) {
-  assertNotLegacyDevelopmentNode(task.node);
+  assertCurrentNode(task.node);
   const sharedFile = sharedTaskFile(workflowRoot, task.task_id);
   let previousRevision = 0;
   if (fs.existsSync(sharedFile)) {
@@ -786,25 +778,15 @@ function normalizeTask(task) {
     task[key] = [...new Set(task[key])];
   }
   task.sequence = parseSequence(task.sequence);
-  task.next_action_owner = parseNextActionOwner(task.next_action_owner);
-  task.responsibility = task.responsibility || task.skill || "agent";
+  task.next_action_owner = parseNextActionOwner(task.next_action_owner, undefined);
+  if (!task.responsibility) throw new Error(`Task ${task.task_id || "unknown"} is missing responsibility.`);
   task.derived_from = task.derived_from || null;
   task.supersedes = task.supersedes || null;
-  if (!Array.isArray(task.attempts)) {
-    const legacyNumber = Number(task.attempt || 0);
-    task.attempts = legacyNumber > 0 && (task.started_at || task.status !== "queued")
-      ? [normalizeAttempt(task.task_id, {
-        number: legacyNumber,
-        status: projectedTaskStatus(task.status, "attempt"),
-        started_at: task.started_at || task.created_at || null,
-        finished_at: CLOSED_STATUS.has(task.status) ? task.finished_at || task.updated_at || null : null,
-      }, legacyNumber)]
-      : [];
-  } else {
-    task.attempts = task.attempts.map((attempt, index) => normalizeAttempt(task.task_id, attempt, index + 1));
+  if (Object.prototype.hasOwnProperty.call(task, "attempt") || !Array.isArray(task.attempts)) {
+    throw new Error(`Task ${task.task_id || "unknown"} must use canonical attempts.`);
   }
+  task.attempts = task.attempts.map((attempt, index) => normalizeAttempt(task.task_id, attempt, index + 1));
   task.change_sets = Array.isArray(task.change_sets) ? task.change_sets.map((item) => normalizeChangeSet(item)) : [];
-  task.attempt = task.attempts.at(-1)?.number || 0;
   return task;
 }
 
@@ -852,7 +834,6 @@ function startAttempt(task, phase, timestamp) {
     time_entries: [],
   }, number);
   task.attempts.push(attempt);
-  task.attempt = number;
   return attempt;
 }
 
@@ -1379,7 +1360,7 @@ function summarizeIteration(tasks, iterationId) {
 function commandInit(args) {
   const taskId = sanitizeId(requireValue(args, "task-id"));
   const iterationId = sanitizeId(requireValue(args, "iteration-id"));
-  const node = assertNotLegacyDevelopmentNode(requireValue(args, "node"));
+  const node = assertCurrentNode(requireValue(args, "node"));
   const { projectRoot, stateRoot, workflowRoot, runtime } = statePaths(args);
   return withTaskLock(runtime, `version.${iterationId}`, () => withTaskLock(runtime, taskId, () => {
     if (fs.existsSync(archivedTaskIndexFile(runtime, taskId))) {
@@ -1424,6 +1405,7 @@ function commandInit(args) {
     const candidateContract = normalizeTask({
       ...(existing || {}),
       ...contractFields,
+      attempts: existing?.attempts || [],
       next_action_owner: existing?.next_action_owner || "agent",
     });
     if (existing) {
@@ -1459,7 +1441,6 @@ function commandInit(args) {
       ...contractFields,
       status,
       sequence: parseSequence(args.sequence ?? existing?.sequence),
-      attempt: 0,
       attempts: [],
       change_sets: [],
       input_artifacts: args["input-artifact"] || existing?.input_artifacts || [],
@@ -1486,7 +1467,7 @@ function commandInit(args) {
     clearTaskMarker(task);
     appendEvent(runtime, taskId, "task-initialized", {
       status: task.status,
-      attempt: task.attempt,
+      attempt_count: task.attempts.length,
       derived_from: task.derived_from,
       supersedes: task.supersedes,
     });
@@ -1557,7 +1538,6 @@ function commandActivate(args) {
       phase.status = "active";
       phase.finished_at = null;
     }
-    task.attempt = attempt.number;
     task.started_at ||= timestamp;
     task.updated_at = timestamp;
     task.finished_at = null;
@@ -1573,7 +1553,7 @@ function commandActivate(args) {
     });
     appendEvent(runtime, taskId, "task-activated", {
       status,
-      attempt: task.attempt,
+      attempt_count: task.attempts.length,
       attempt_id: attempt.attempt_id,
       phase: attempt.phases.at(-1)?.phase || null,
       new_attempt: newAttempt,
@@ -1627,7 +1607,7 @@ function commandUpdate(args, finish = false) {
     writeResume(runtime, task);
     appendEvent(runtime, taskId, finish ? "task-finished" : "task-checkpointed", {
       status,
-      attempt: attempt.number,
+      attempt_number: attempt.number,
       attempt_id: attempt.attempt_id,
       phase: attempt.phases.at(-1)?.phase || null,
     });
@@ -1696,7 +1676,7 @@ function commandArchiveVersion(args) {
       .map((name) => normalizeTask(JSON.parse(fs.readFileSync(path.join(tasksDir, name), "utf8"))))
       .filter((task) => task.iteration_id === iterationId);
     if (!tasks.length) throw new Error(`No tasks found for version: ${iterationId}`);
-    for (const task of tasks) assertNotLegacyDevelopmentNode(task.node);
+    for (const task of tasks) assertCurrentNode(task.node);
     const sharedById = new Map(readSharedTasks(workflowRoot, stateRoot).map((task) => [task.task_id, task]));
     for (const task of tasks) {
       const shared = sharedById.get(task.task_id);
@@ -1795,7 +1775,7 @@ function commandRecover(args) {
   const reportableTasks = selectedTasks
     .filter((task) => !requested || task.task_id === requested)
     .filter((task) => includeClosed || !RECOVERY_COMPLETE_STATUS.has(task.status));
-  for (const task of reportableTasks) assertNotLegacyDevelopmentNode(task.node);
+  for (const task of reportableTasks) assertCurrentNode(task.node);
   for (const task of reportableTasks) {
     if (missingLocalTaskIds.has(task.task_id)) atomicWrite(taskFile(runtime, task.task_id), task);
   }
@@ -1853,7 +1833,7 @@ function commandPublish(args) {
   const checkpointDirectory = path.join(workflowRoot, "control", "checkpoints", taskId);
   if (!fs.existsSync(sharedFile)) throw new Error(`Shared task state not found: ${taskId}`);
   const shared = JSON.parse(fs.readFileSync(sharedFile, "utf8"));
-  assertNotLegacyDevelopmentNode(shared.node);
+  assertCurrentNode(shared.node);
 
   const repository = gitState(stateRoot);
   if (!repository.repository || path.resolve(repository.root).toLowerCase() !== path.resolve(stateRoot).toLowerCase()) {
@@ -1978,7 +1958,7 @@ function assertWritableEvolutionTarget(args, command) {
   if (!new Set(["init", "activate", "checkpoint", "finish", "archive-version"]).has(command)) return;
   if (command === "init") {
     const node = args.node && args.node !== true ? String(args.node) : null;
-    if (node) assertNotLegacyDevelopmentNode(node);
+    if (node) assertCurrentNode(node);
     return;
   }
   const { runtime, workflowRoot, stateRoot } = statePaths(args);
@@ -1990,14 +1970,14 @@ function assertWritableEvolutionTarget(args, command) {
     if (!iterationId || !fs.existsSync(tasksDir)) return;
     for (const name of fs.readdirSync(tasksDir).filter((item) => item.endsWith(".json"))) {
       const task = normalizeTask(JSON.parse(fs.readFileSync(path.join(tasksDir, name), "utf8")));
-      if (task.iteration_id === iterationId) assertNotLegacyDevelopmentNode(task.node);
+      if (task.iteration_id === iterationId) assertCurrentNode(task.node);
     }
     return;
   }
   const taskId = args["task-id"] && args["task-id"] !== true ? sanitizeId(args["task-id"]) : null;
   if (!taskId) return;
   const task = taskSources(runtime, workflowRoot, stateRoot, taskId).task;
-  if (task) assertNotLegacyDevelopmentNode(task.node);
+  if (task) assertCurrentNode(task.node);
 }
 
 function dispatchTaskEvolution(context, phase, result = null, error = null) {

package/skills/ai-delivery-close-version/SKILL.md

@@ -11,24 +11,27 @@ Finish one planned version and stop before release. Never start a release from t
 
 1. Recover or initialize the `06-version-closeout` task through `$ai-delivery-checkpoint-task`.
 2. Run `node .workflow/tools/state/state.mjs verify --history`.
-3. Require a passing immutable candidate, a completed Candidate Assurance receipt for that same candidate, closed version tasks, complete requirement/test/material traceability, and no unresolved blocking defect.
+3. Require a passing immutable candidate, a completed Candidate Assurance receipt for that same candidate, a resolved or superseded product impact assessment bound to the candidate, closed version tasks, complete requirement/test/material traceability, and no unresolved blocking defect.
 4. Read the preceding version lineage and Git policy. Require the candidate to descend from the current `line/<product-id>` head, except for the first version.
 
 ## Close The Version
 
 1. Read `.workflow/config/workspace.yaml`; verify the candidate in the configured code repository and populate `repo_id`, `code_commit`, `source_path`, and SHA-256.
-2. Freeze the candidate commit and create code `version-ready/<version-id>/rN`. Never move or replace an existing Tag; increment `rN` only for a newly verified replacement candidate.
-3. Fast-forward code `line/<product-id>` to the tagged commit. Never advance code `main` here.
-4. Copy the closeout assets into `.workflow/iterations/<version-id>/06-version-closeout/`, populate the code Tag identity, and compute the final manifest SHA-256.
-5. Register the immutable closeout semantic revision directly as `release-ready` with the formal state CLI, and complete `06-version-closeout` with that registered artifact as evidence. Do not register a draft and mutate its status in place.
-6. Commit all version workflow materials and create immutable workflow `workflow-ready/<version-id>/rN` at that exact workflow commit. Record the workflow commit, workflow Tag, and manifest checksum in the lineage index without rewriting the tagged manifest.
-7. Verify both Tags and the manifest checksum. Inspect the current development scope revision, then run `state.mjs transition --expected-scope-revision <revision> --event version-closed --iteration-id <version-id> --artifact-id <closeout-artifact-id>` to update the audited cumulative development identity. Never edit `latest_line_version_id` directly.
-8. Run `state.mjs snapshot create --id <version-id> --reason version-boundary`, then `state.mjs verify --history --since-anchor`. The first trusted anchor performs a full-history audit before creation; later anchors validate the suffix from the previous anchor.
-9. Archive tasks with `task-state.mjs archive-version --version-status release-ready --candidate-id <candidate-id> --evidence <closeout-artifact-id>`. The command must first obtain `snapshot references` from the formal-state CLI and fail before writing if the anchor, scope, or candidate is missing. Verify that the version manifest references checksummed task summaries, complete attempt values, scope, candidate, Gate decisions, and the version-boundary anchor; then checkpoint the Git, anchor, and archive evidence and finish the task.
-10. Invoke `$ai-delivery-evolve-workflow evaluate --safe-point version --iteration-id <version-id>`. Record trial results and decisions, but never use an Evolution result as release intent.
+2. Validate the candidate's codebase handbook and navigation index at the exact code commit. Record their status, checksums, owner, last review, and any stale/invalid findings in closeout evidence; require repair or explicit maintainer acceptance before marking documentation evidence complete.
+3. Freeze the candidate commit and create code `version-ready/<version-id>/rN`. Never move or replace an existing Tag; increment `rN` only for a newly verified replacement candidate.
+4. Fast-forward code `line/<product-id>` to the tagged commit. Never advance code `main` here.
+5. Copy the closeout assets into `.workflow/iterations/<version-id>/06-version-closeout/`, populate the code Tag identity, and compute the final manifest SHA-256.
+6. Register the immutable closeout semantic revision directly as `release-ready` with the formal state CLI, and complete `06-version-closeout` with that registered artifact as evidence. Do not register a draft and mutate its status in place.
+7. Commit all version workflow materials and create immutable workflow `workflow-ready/<version-id>/rN` at that exact workflow commit. Record the workflow commit, workflow Tag, and manifest checksum in the lineage index without rewriting the tagged manifest.
+8. Verify both Tags and the manifest checksum. Inspect the current development scope revision, then run `state.mjs transition --expected-scope-revision <revision> --event version-closed --iteration-id <version-id> --artifact-id <closeout-artifact-id>` to update the audited cumulative development identity. Never edit `latest_line_version_id` directly.
+9. Run `state.mjs snapshot create --id <version-id> --reason version-boundary`, then `state.mjs verify --history --since-anchor`. The first trusted anchor performs a full-history audit before creation; later anchors validate the suffix from the previous anchor.
+10. Archive tasks with `task-state.mjs archive-version --version-status release-ready --candidate-id <candidate-id> --evidence <closeout-artifact-id>`. The command must first obtain `snapshot references` from the formal-state CLI and fail before writing if the anchor, scope, or candidate is missing. Verify that the version manifest references checksummed task summaries, complete attempt values, scope, candidate, Gate decisions, and the version-boundary anchor; then checkpoint the Git, anchor, and archive evidence and finish the task.
+11. Invoke `$ai-delivery-evolve-workflow evaluate --safe-point version --iteration-id <version-id>`. Record trial results and decisions, but never use an Evolution result as release intent.
 
 ## Stop Boundary
 
 Report the release-ready version, code Tag, workflow Tag, manifest checksum, cumulative line head, archived task count, and next planned version. Stop and wait for either the next version iteration or an explicit user release request. Do not invoke release orchestration implicitly.
 
 Read [version-closeout-contract.md](references/version-closeout-contract.md) before writing outputs.
+
+Before closeout, validate the confirmation summary and ensure confirmed product, architecture, standard, and risk decisions have authority references and matching checksums. Deferred or open decisions remain visible in closeout evidence. Closing a version does not imply release intent.

package/skills/ai-delivery-close-version/references/version-closeout-contract.md

@@ -4,6 +4,7 @@
 
 - planned version ID, product ID, predecessor version, and iteration plan;
 - immutable candidate ID, commit, artifact digest, and passing verification decision;
+- resolved or superseded `product-impact-assessment.yaml` bound to the candidate and the aligned product baseline;
 - complete closed-task summary and unresolved-risk statement;
 - current `line/<product-id>` head and applicable standards baseline.
 
@@ -17,4 +18,4 @@ After Candidate Assurance has completed for the same immutable candidate, the `r
 
 ## Failure rules
 
-Block closeout for active tasks, mutable candidates, failed verification, missing materials, Git divergence, an existing tag resolving to another commit, or a candidate that does not include a synchronized production hotfix. Mark affected candidates `stale`; never edit a previously closed version.
+Block closeout for active tasks, mutable candidates, failed verification, missing materials, an unresolved or checksum-drifted product impact assessment, Git divergence, an existing tag resolving to another commit, or a candidate that does not include a synchronized production hotfix. Mark affected candidates `stale`; never edit a previously closed version.

package/skills/ai-delivery-define-product/SKILL.md

@@ -24,7 +24,7 @@ This Skill owns `01-product-shaping`. Discovery, product definition, and prototy
 
 ## Preflight
 
-Read the project state, artifact registry, applicable standards, and existing product baseline. For a change, identify the affected terms, terminals, features, stories, and acceptance criteria before editing. In prototype-reconciliation mode also read the complete adjustment log, requirement change set, formal UI confirmation, exact Prototype revision and checksum, normalized Page and Review Scene catalogs, UI Mapping, and bidirectional product coverage.
+Read the project state, artifact registry, applicable standards, existing product baseline, and the current `confirmation-summary.yaml`. For a change, identify the affected terms, terminals, features, stories, and acceptance criteria before editing. In prototype-reconciliation mode also read the shared `product-impact-assessment.yaml`, complete adjustment log, requirement change set, formal UI confirmation, exact Prototype revision and checksum, normalized Page and Review Scene catalogs, UI Mapping, and bidirectional product coverage. Facts discovered from the repository remain `observed_fact`; only the business sponsor confirms product intent, scope, terminology, priority, risk acceptance, or Gate decisions.
 
 ## Run Discovery
 
@@ -34,6 +34,8 @@ Read the project state, artifact registry, applicable standards, and existing pr
 4. Produce the discovery baseline and run completeness and contradiction checks.
 5. Submit discovery Gate A for human approval. Do not start product definition while Gate A is rejected or incomplete.
 
+After each answer, append a structured confirmation record, recompute the frontier, and persist exactly one idempotent user-owned next action when another decision is required. Before Gate A or Gate B, produce a shared-understanding summary and link every confirmed business decision and domain term to its owning product artifact. Do not save the conversation transcript.
+
 ## Define The Product
 
 1. Define the product specification, capability structure, business flows, user stories, acceptance criteria, non-functional requirements, and business priority.
@@ -59,6 +61,7 @@ Required outputs:
 - `acceptance-criteria.csv`;
 - traceability association CSV files;
 - `product-baseline.yaml` with versions and item-level approval state.
+- `confirmation-summary.yaml` with the current frontier, confirmed/rejected/deferred decisions, authority references, and shared-understanding result.
 
 In prototype-reconciliation mode also produce the terminal requirement change set, bidirectional product coverage, product artifact delta, and `product-prototype-reconciliation.yaml`.
 
@@ -68,12 +71,12 @@ Use the schemas and controlled values in [product-contract.md](references/produc
 
 Run this mode only after the candidate Prototype revision is approved for every visual or interactive Page and Review Scene and all of its adjustments are terminal.
 
-1. Review every row in `requirement-change-set.csv`; classify it as approved, rejected, or requiring clarification. Do not approve a requirement merely because the prototype implements it.
+1. Review the shared `product-impact-assessment.yaml` first. Confirm that every `product-update-required` or `clarification-required` finding has a user-owned question, affected stable IDs, and a return reason. Review every row in `requirement-change-set.csv`; classify it as approved, rejected, or requiring clarification. Do not approve a requirement merely because the prototype implements it.
 2. Verify both directions of `prototype-product-coverage.csv`: every prototype behavior must resolve to an approved feature/story/acceptance criterion, and every visual product behavior must resolve to a prototype element or justified `not-applicable` row.
 3. Apply approved added, modified, retired, or superseded requirements to a new product baseline version. Preserve stable IDs for modifications and retire IDs instead of reusing them.
 4. Re-run Gate B for every changed product artifact and record exact approval evidence. When nothing changes, retain the existing baseline and record an `aligned` no-change decision.
 5. Write `product-prototype-reconciliation.yaml` with the input/output product baseline checksums, prototype/formal-UI checksums, terminal and terminology checks, requirement-change closure, stale artifacts, and required prototype revalidation.
-6. Return rejected prototype behavior to experience for removal. Return an updated baseline to experience, mark the affected Page and Review Scene revisions stale, and require their staged re-approval in a new Prototype revision. Repeat until the receipt is `status: valid`, `decision: aligned`, and every requirement change is terminal.
+6. Return rejected prototype behavior to experience for removal. Return an updated baseline to experience, resolve the shared impact assessment, mark the affected Page and Review Scene revisions stale, and require their staged re-approval in a new Prototype revision. Repeat until the receipt is `status: valid`, `decision: aligned`, every requirement change is terminal, and every product impact assessment is `resolved` or `superseded`.
 
 ## Handoff
 

package/skills/ai-delivery-design-architecture/SKILL.md

@@ -23,28 +23,31 @@ This Skill shares `02-solution-design` with `$ai-delivery-design-experience`. In
 
 ## Preflight
 
-Read the approved product baseline, business glossary, terminal matrix, feature catalog, applicable standards, and prior architecture decisions. Reject incomplete or inconsistent inputs instead of guessing product scope.
+Read the approved product baseline, business glossary, terminal matrix, feature catalog, applicable standards, prior architecture decisions, the current `confirmation-summary.yaml`, and the configured code repository's `AGENTS.md`, `CODEBASE_GUIDE.md`, and relevant `docs/CODEBASE_INDEX.md` entries. Read [product-impact-assessment-contract.md](../ai-delivery-orchestrate/references/product-impact-assessment-contract.md) before classifying a design discovery. Treat handbook content and confirmation summaries as context/traceability only: architecture artifacts and decisions remain the sole authority for boundaries and dependency rules. Reject missing, stale, malformed, or conflicting references instead of guessing product scope; record a draft remediation when documentation is incomplete.
 
 ## Initial Mode
 
-1. Convert non-functional requirements into measurable quality scenarios and budgets.
+1. Convert non-functional requirements into measurable quality scenarios and budgets. If a new budget, constraint, or tradeoff changes product scope, priority, risk acceptance, terminology, terminal coverage, or acceptance, create `product-impact-assessment.yaml` before continuing.
 2. Define system context, application and component boundaries, terminal implementation strategies, data ownership, authentication and authorization, security controls, deployment topology, observability, and operational constraints.
 3. Select technology stacks with exact supported versions, package and build tools, repository layout, dependency policy, and required commands.
 4. Draft APIs, events, data contracts, migration strategy, test seams, and delivery constraints.
 5. Record only decisions that are costly to reverse and based on real tradeoffs.
-6. Submit major decisions for human approval before experience design proceeds.
+6. Classify each discovery with the shared assessment. `no-impact` and `architecture-only` require evidence; `product-update-required` and `clarification-required` return to `01-product-shaping` and block the architecture handoff until product reconciliation is valid.
+7. Submit major decisions for human approval before experience design proceeds.
 
 Major decisions include platforms, paid services, security or privacy boundaries, hard-to-reverse data or infrastructure choices, material cost/performance/schedule tradeoffs, and deviations from approved product scope.
 
 ## Reconcile Mode
 
-1. Read the experience baseline, `ui-handoff.yaml`, both staged Gate receipts (`UX-VS` and `UX-UI`), aligned `product-prototype-reconciliation.yaml` receipt, experience/requirement change sets, interaction contract, design tokens, framework selection, component-state matrix, page-component map, the exact immutable Prototype revision and checksum, its source and review-bundle checksums, the normalized terminal, Page, Review Scene, trigger-condition, route, and UI Mapping catalogs, review/impact records, traceability, and source confirmation. Verify every exact identity/checksum and require the handoff to be complete and free of stale references. Reject a missing or conflicting reference; never infer a relationship from a file name or catalog order.
+1. Read the experience baseline, `ui-handoff.yaml`, both staged Gate receipts (`UX-VS` and `UX-UI`), the aligned `product-prototype-reconciliation.yaml` receipt, the shared `product-impact-assessment.yaml`, experience/requirement change sets, interaction contract, design tokens, framework selection, component-state matrix, page-component map, the exact immutable Prototype revision and checksum, its source and review-bundle checksums, the normalized terminal, Page, Review Scene, trigger-condition, route, and UI Mapping catalogs, review/impact records, traceability, and source confirmation. Verify every exact identity/checksum and require the handoff to be complete and free of stale references. Reject a missing or conflicting reference; never infer a relationship from a file name or catalog order.
 2. Resolve every affected Page, Review Scene, UI component, frontend source, and acceptance ID through the pinned UI Mapping. Verify that the selected UI framework/version is compatible with the architecture stack and dependency policy, and that every mapped interaction, state, permission, query, upload, real-time behavior, failure mode, responsive rule, and accessibility requirement is technically supported. Use stable change, terminal, Page, Review Scene, prototype-element, UI Mapping, component, frontend-source, and acceptance IDs in findings.
 3. Write one `prototype-architecture-validation.yaml` for the Prototype revision with the UI handoff identity/checksum, Prototype revision and UI Mapping checksums, all consumed artifact versions/checksums, exact architecture baseline version/checksum, implementability decision, affected changes/Pages/Review Scenes/mappings/components/acceptance criteria, issues, and return node. An accepted receipt uses `status: valid`; a `changes-required` receipt uses `status: invalid`. Accept the handoff only when the receipt passes, then advance accepted experience changes from `formal-ui-confirmed` to `architecture-accepted` and `ready-for-development` through the state CLI.
-4. Return product or experience defects to their producer. Do not silently weaken approved behavior or edit the frozen prototype.
+4. Wrap any product-affecting architecture finding in `product-impact-assessment.yaml`. Return `product-update-required` and `clarification-required` to `01-product-shaping`; return experience defects to their producer. Do not silently weaken approved behavior, edit the frozen prototype, or continue with an unresolved assessment.
 5. Finalize APIs, data access, events, component boundaries, test seams, deployment requirements, and implementation constraints.
 6. Reopen human approval only when reconciliation creates or changes a major decision.
 
+For each new architecture decision, append a confirmation record with factual evidence, alternatives, recommendation, user decision, impact, and owning architecture artifact. Ask only frontier decisions that are not answerable from the environment. A confirmed record never substitutes for the architecture Gate.
+
 ## Outputs
 
 Produce one versioned architecture baseline containing:
@@ -61,6 +64,8 @@ Produce one versioned architecture baseline containing:
 - prototype architecture validation receipt in reconcile mode;
 - UI framework/dependency acceptance and exact `ui-handoff.yaml` receipt in reconcile mode;
 - final test seams and component impact map.
+- handbook review evidence: exact code commit, files/sections consulted, stale or missing findings, and maintainer confirmation required for any promoted rule.
+- confirmation summary and decision-to-architecture artifact traceability.
 
 Do not require DDD constructs. Use business terms from the product manual and provide explicit mappings for unavoidable technical names.