ai-delivery-workflow 0.3.0 → 0.5.0

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

@@ -34,6 +34,8 @@ 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.
+
 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.
 
 ## Commands
@@ -41,12 +43,16 @@ When the installed Evolution CLI exists, `init`, `activate`, `checkpoint`, `fini
 Resolve `scripts/task-state.mjs` relative to this skill directory when invoking the bundled script.
 
 ```text
-node scripts/task-state.mjs init --task-id TASK-0001 --iteration-id ITER-0001 --node development --skill ai-delivery-develop-iteration --goal "Implement slice" --next-action "Derive work packages" --next-action-owner agent
+node scripts/task-state.mjs init --task-id TASK-0001 --iteration-id ITER-0001 --node development --skill ai-delivery-develop-iteration --goal "Implement slice" --responsibility delivery-agent --scope SLICE-001 --acceptance AC-001 --next-action "Derive work packages" --next-action-owner agent
 node scripts/task-state.mjs init --task-id TASK-0002 --iteration-id ITER-0001 --node test --skill ai-delivery-verify-candidate --goal "Verify candidate" --status queued --sequence 2 --depends-on TASK-0001 --next-action "Run candidate verification"
 node scripts/task-state.mjs recover --iteration-id ITER-0001
-node scripts/task-state.mjs activate --task-id TASK-0002
-node scripts/task-state.mjs checkpoint --task-id TASK-0001 --status checkpointed --completed-step "Public contract validated" --next-action "Create worktrees"
-node scripts/task-state.mjs finish --task-id TASK-0001 --status completed --next-action "Run candidate verification"
+node scripts/task-state.mjs inspect --task-id TASK-0001 --include-closed
+node scripts/task-state.mjs activate --task-id TASK-0002 --phase implementation
+node scripts/task-state.mjs checkpoint --task-id TASK-0001 --status pending-review --phase review --completed-step "Public contract validated" --next-action "Collect review findings"
+node scripts/task-state.mjs finish --task-id TASK-0001 --status failed --phase review --finding-json '{"finding_id":"FIND-001","severity":"blocking","status":"open","summary":"Acceptance branch is missing","evidence":["review@1"]}' --change-set-json '{"change_set_id":"CHANGESET-001","approval_actor":"product-owner@example.invalid","rationale":"Repair the complete review batch","finding_ids":["FIND-001"],"allowed_files":["src/acceptance.mjs"],"expected_evidence":["test-report@2"],"review_axes":["standards","spec"],"collection_decision":"fail"}' --time-category review --elapsed-minutes 12 --next-action "Apply one repair set"
+node scripts/task-state.mjs activate --task-id TASK-0001 --new-attempt --phase repair --next-action "Apply one repair set"
+node scripts/task-state.mjs finish --task-id TASK-0001 --status completed --phase review --finding-json '{"finding_id":"FIND-001","severity":"blocking","status":"resolved","summary":"Acceptance branch is covered","evidence":["test-report@2"],"changed_files":["src/acceptance.mjs"],"change_set_id":"CHANGESET-001"}' --next-action "Run candidate verification"
+node scripts/task-state.mjs init --task-id TASK-0001-V2 --iteration-id ITER-0001 --node development --skill ai-delivery-develop-iteration --goal "Implement expanded slice" --scope SLICE-002 --acceptance AC-002 --derived-from TASK-0001 --status queued --next-action "Await scope approval"
 node scripts/task-state.mjs finish --task-id TASK-0001 --status interrupted --next-action "Which user group is affected first?" --next-action-owner user
 node scripts/task-state.mjs recover --mark-interrupted --stale-minutes 15
 node scripts/task-state.mjs recover --include-closed
@@ -59,6 +65,12 @@ node scripts/task-state.mjs publish --task-id TASK-0001 --push
 
 Every state transition writes both the local runtime snapshot and the portable task shard/checkpoint. `publish` refuses unrelated dirty paths, commits only the selected task scope, and does not push unless `--push` is explicit. When local runtime is missing, `recover` reconstructs an `agent`-owned task from shared shards; `user` and `external` wait states remain read-only until an explicit `activate` transfer. A revision or semantic-checksum mismatch is a hard conflict, not a last-writer-wins update.
 
+`task-state.mjs inspect` is strictly read-only. It never hydrates shared state into runtime, writes a resume or checkpoint, changes timestamps, creates a lock, or changes Git state. Use it for task-level diagnosis; use `recover` only when an agent-owned task must actually be hydrated and resumed.
+
+The stable logical task contract consists of iteration, node/responsibility, skill, goal, scope, dependencies, and acceptance. `init` always creates queued work and rejects every other requested status; activation is the only path that starts A1 and checks dependencies. Completed, failed, and abandoned require an activated attempt and `finish`. Repeating `init` with the same contract and task ID is idempotent and zero-write. Registering the same contract under another task ID, or changing any contract field under the same task ID, fails closed. Create a new task and declare `--derived-from` or `--supersedes` only when that contract materially changes.
+
+Queued tasks have `attempt: 0` and an empty `attempts` collection, and `checkpoint` or `finish` refuses them until activation. Activation creates `TASK-ID/A1`; ordinary blocked or interrupted recovery continues that attempt. Phase status is always derived from the task transition; `--phase-status` is rejected. A failed task cannot satisfy dependencies and cannot be reactivated implicitly. `activate --new-attempt --phase <phase>` explicitly creates the next attempt under the same task identity. Each attempt contains ordered phases, structured findings, and optional time entries categorized as implementation, test, review, workflow, user wait, external wait, or rework. Entering review captures `review_subject_baseline`; approval fails unless the current Git subject still matches it. Findings use stable IDs plus severity, status, summary, evidence, changed files, and an optional stable `change_set_id`; every record is append-only and the latest record for one ID is its current conclusion. `--change-set-json` is accepted only in review and must name every current open finding plus review axes and the collection decision. The CLI promotes the pinned subject to `repair_baseline`, persists the canonical `feedback_collection`, computes its `collection_checksum`, and stores the immutable approval actor, rationale, exact finding IDs, allowed files, and expected evidence. During concentrated rereview, a resolved record must refer to an existing open finding in that approved set, include the expected evidence, and declare exactly the real Git changes since approval; the CLI rejects undeclared changes and files outside the approval. A task cannot become `completed` while any current blocking finding remains `open`. Failed and abandoned tasks cannot satisfy dependencies; only `completed` can.
+
 For an installed dual-repository project, `task-state.mjs` resolves `code_branch` and `code_commit` from the authoritative `.workflow/config/workspace.yaml` and its configured nested code Git root. The install manifest and task worktree are not workspace identity fallbacks. The task's workflow worktree or workflow branch must never be persisted as code identity. If the workspace configuration is missing, its code path is not a direct child, or the configured code root is not an independent Git repository, the mutation fails instead of recording a fallback identity.
 
 `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.
@@ -67,11 +79,13 @@ For an installed dual-repository project, `task-state.mjs` resolves `code_branch
 
 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.
 
-Use `finish` only with `completed`, `blocked`, `interrupted`, `failed`, or `abandoned`. Use `checkpoint` for all other statuses.
+Use `finish` only with `completed`, `blocked`, `interrupted`, `failed`, or `abandoned`. Closed statuses `completed`, `failed`, and `abandoned` are rejected by `checkpoint`; use `checkpoint` only for continuing or paused work.
 
 Register all known iteration tasks as `queued` before execution. `queued` registration does not write `.workflow/delivery/runtime/active-task.json`, so several future tasks may share a worktree safely. `activate` verifies that every `depends_on` task exists and is `completed`, changes the selected task to `running` or `preparing`, writes a new checkpoint, and creates the active task marker for Hook correlation.
 
-`finish` closes an individual task but does not archive it. Default recovery omits closed tasks so they do not consume resume context. Archive the entire planned version after version closeout marks it `release-ready`, after historical production verification marks it `released`, or when explicitly `abandoned`. A release-ready archive requires the immutable candidate ID and verification evidence; a released archive requires release ID and production evidence. Every task in that version must be closed. Archival first writes the portable version package, then removes that version from active shared task/checkpoint collections; `recover` never scans `.workflow/control/archives/`.
+`finish` closes an individual task but does not archive it. Closed counts include completed, failed, and abandoned tasks, but default recovery returns failed tasks as retryable work and omits only completed and abandoned details. Archive the entire planned version after version closeout marks it `release-ready`, after historical production verification marks it `released`, or when explicitly `abandoned`. A release-ready archive requires the immutable candidate ID and verification evidence; a released archive requires release ID and production evidence. Every task in that version must be closed. Before the first archive write, `archive-version` calls the installed formal-state CLI's `snapshot references` command and fails closed unless the latest trusted anchor contains the target scope manifest and candidate. The version manifest references checksummed archived task summaries and each attempt receipt (whose checksum covers the complete attempt value addressed by its reference), plus the anchored scope manifest, candidate, Gate decisions, and history anchor; it does not duplicate those formal records inline. Archival first writes the portable version package, then removes that version from active shared task/checkpoint collections; `recover` never scans `.workflow/control/archives/`.
+
+If an archived version is later proven ineligible, keep every archive byte unchanged. The packaged top-level `ai-delivery repair --invalidate-archive` command appends the only valid correction/invalidation record under `.workflow/control/repairs/transactions/`, with the archive checksum, an explicit human actor, reason, RCA evidence, and recovery evidence. Recovery continues to ignore archived task details; current eligibility projections exclude an invalidated archive through that forward transaction.
 
 ## Hook Events
 
@@ -83,9 +97,9 @@ Hooks receive lifecycle JSON on stdin. Redact secrets, cap payload size, append
 
 - Reconcile recorded branch, worktree, dirty files, heartbeat, and next action.
 - Stop without mutation when the recommended task's `next_action_owner` is `user` or `external`; only report the recorded question or wait condition.
-- Keep closed tasks in the current version until version archival, but exclude them from normal recovery output.
+- Keep closed tasks in the current version until version archival. Normal recovery excludes completed and abandoned details but includes failed tasks in `retryable_task_ids`.
 - Determine iteration progress from all task snapshots, including the closed snapshots hidden from the normal task list.
-- Prefer an existing active or interrupted task during recovery. If none exists, recommend the lowest-sequence queued task whose dependencies are all `completed`.
+- Prefer an existing active or interrupted task during recovery. If none exists, recommend the lowest-sequence failed task for explicit `activate --new-attempt --phase repair`; only then recommend the lowest-sequence queued task whose dependencies are all `completed`.
 - Never activate a task with a missing, failed, abandoned, blocked, or otherwise incomplete dependency.
 - Use one portable version archive under `.workflow/control/archives/versions/`; runtime archive copies are disposable and non-authoritative. Pass `--portable-only` when no local detailed copy should be created.
 - Treat a stale `running` task as a recovery candidate, not automatically failed.

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

@@ -53,6 +53,96 @@ async function readStdin() {
   return Buffer.concat(chunks).toString("utf8");
 }
 
+function preToolUsePaths(input) {
+  const eventName = String(input.hook_event_name || input.hookEventName || "").toLowerCase();
+  if (eventName !== "pretooluse") return [];
+  const toolName = String(input.tool_name || input.toolName || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "");
+  const mutatingFileTools = [
+    "applypatch", "edit", "editfile", "multiedit", "write", "writefile",
+    "createfile", "deletefile", "movefile", "renamefile", "replacefile",
+  ];
+  if (!mutatingFileTools.some((name) => toolName === name || toolName.endsWith(name))) return [];
+  const toolInput = input.tool_input && typeof input.tool_input === "object"
+    ? input.tool_input
+    : {};
+  const candidates = [];
+  for (const field of ["file_path", "path", "target_file"]) {
+    if (typeof toolInput[field] === "string") candidates.push(toolInput[field]);
+  }
+  if (Array.isArray(toolInput.edits)) {
+    for (const edit of toolInput.edits) {
+      if (!edit || typeof edit !== "object") continue;
+      for (const field of ["file_path", "path", "target_file"]) {
+        if (typeof edit[field] === "string") candidates.push(edit[field]);
+      }
+    }
+  }
+  for (const field of ["patch", "input"]) {
+    if (typeof toolInput[field] !== "string") continue;
+    for (const line of toolInput[field].split(/\r?\n/)) {
+      const match = line.match(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/)
+        || line.match(/^\*\*\* Move to: (.+)$/);
+      if (match) candidates.push(match[1]);
+    }
+  }
+  return [...new Set(candidates.map((item) => item.trim()).filter(Boolean))];
+}
+
+function owningGitRoot(file) {
+  let current = fs.existsSync(file) && fs.statSync(file).isDirectory() ? file : path.dirname(file);
+  while (!fs.existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+  const result = spawnSync("git", ["-C", current, "rev-parse", "--show-toplevel"], {
+    encoding: "utf8",
+    timeout: 5_000,
+    windowsHide: true,
+  });
+  return result.status === 0 ? path.resolve(result.stdout.trim()) : null;
+}
+
+function samePath(left, right) {
+  const normalize = (value) => process.platform === "win32"
+    ? path.resolve(value).toLowerCase()
+    : path.resolve(value);
+  return normalize(left) === normalize(right);
+}
+
+function enforceFrontendGuard(projectRoot, input) {
+  const changedPaths = preToolUsePaths(input);
+  if (!changedPaths.length) return;
+  const guardCli = path.join(projectRoot, ".workflow", "tools", "frontend-guard", "frontend-guard.mjs");
+  if (!fs.existsSync(guardCli)) {
+    throw new Error(`Frontend guard runtime is missing: ${guardCli}`);
+  }
+  for (const changedPath of changedPaths) {
+    const resolvedChangedPath = path.isAbsolute(changedPath)
+      ? changedPath
+      : path.resolve(process.cwd(), changedPath);
+    const gitRoot = owningGitRoot(resolvedChangedPath);
+    if (gitRoot && samePath(gitRoot, projectRoot)) continue;
+    const guarded = spawnSync(process.execPath, [
+      guardCli, "check-file", projectRoot, "--path", resolvedChangedPath,
+    ], {
+      cwd: projectRoot,
+      encoding: "utf8",
+      timeout: 15_000,
+      windowsHide: true,
+    });
+    if (guarded.error || guarded.status !== 0) {
+      throw new Error(
+        guarded.error?.message
+        || guarded.stderr.trim()
+        || `Frontend guard rejected ${resolvedChangedPath}.`,
+      );
+    }
+  }
+}
+
 try {
   const currentProjectFile = findUp(process.cwd(), path.join(".workflow", "delivery", "project.yaml"));
   const legacyProjectFile = currentProjectFile
@@ -67,6 +157,7 @@ try {
   const marker = fs.existsSync(markerFile) ? JSON.parse(fs.readFileSync(markerFile, "utf8")) : null;
   const raw = await readStdin();
   const input = raw.trim() ? JSON.parse(raw) : {};
+  enforceFrontendGuard(projectRoot, input);
   const taskId = safeId(process.env.AI_DELIVERY_TASK_ID || marker?.task_id || input.turn_id || input.session_id);
   const stateRoot = path.resolve(process.env.AI_DELIVERY_STATE_ROOT || marker?.state_root || projectRoot);
   const workflowRoot = fs.existsSync(path.join(stateRoot, ".workflow", "delivery", "project.yaml"))