ai-delivery-workflow 0.2.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-delivery-workflow",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Project-scoped Codex skills and hooks for artifact-driven AI software delivery",
   "type": "module",
   "repository": {
@@ -23,9 +23,12 @@
   ],
   "scripts": {
     "test": "node --test verification/*.test.mjs",
+    "manager:build": "npm --prefix manager run build",
     "skills:validate": "node bin/validate-skills.mjs",
     "audit:generate": "node audit/generate-all.mjs",
     "audit:verify": "node verification/audit/verify-audit.mjs",
+    "benchmark:autonomy": "node bin/benchmark-autonomy.mjs",
+    "release:check": "node bin/release-check.mjs",
     "pack:check": "npm pack --dry-run"
   },
   "dependencies": {
@@ -35,5 +38,8 @@
   "engines": {
     "node": ">=18"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "playwright-core": "^1.55.0"
+  }
 }

package/skills/ai-delivery-assemble-release/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Assemble Release"
-  short_description: "Validate version lineage and aggregate release materials"
+interface:
+  display_name: "Assemble Release"
+  short_description: "Validate version lineage and aggregate release materials"
   default_prompt: "Use $ai-delivery-assemble-release to validate both repositories, calculate the version closure, and assemble its candidate."

package/skills/ai-delivery-assemble-release/assets/release-material-index.csv

@@ -1,2 +1,2 @@
 item_id,category,source_version_id,artifact_id,repo_id,code_commit,code_tag,source_path,original_workflow_path,sha256,target_environment,apply_order,verification,rollback_or_recovery
-ITEM-0001,container-image,VER-0001,ART-IMAGE-0001,app,<git-sha>,version-ready/VER-0001/r1,code,.workflow/iterations/VER-0001/12-version-closeout/version-manifest.yaml,<sha256>,production,10,verify image digest,deploy previous immutable image digest
+ITEM-0001,container-image,VER-0001,ART-IMAGE-0001,app,<git-sha>,version-ready/VER-0001/r1,code,.workflow/iterations/VER-0001/06-version-closeout/version-manifest.yaml,<sha256>,production,10,verify image digest,deploy previous immutable image digest

package/skills/ai-delivery-assemble-release/assets/version-inclusion.csv

@@ -1,2 +1,2 @@
 sequence,version_id,predecessor_version_id,candidate_id,candidate_commit,version_ready_tag,manifest_path,manifest_sha256,inclusion_type
-1,VER-0001,,CAND-0001,<git-sha>,version-ready/VER-0001/r1,.workflow/iterations/VER-0001/12-version-closeout/version-manifest.yaml,<sha256>,dependency-closure
+1,VER-0001,,CAND-0001,<git-sha>,version-ready/VER-0001/r1,.workflow/iterations/VER-0001/06-version-closeout/version-manifest.yaml,<sha256>,dependency-closure

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

@@ -32,8 +32,8 @@ When inspection returns `workflow-ready`, there are no task shards, and the form
 
 1. Run `node .workflow/tools/bootstrap/bootstrap.mjs bootstrap` to create the observed bootstrap context.
 2. Start development scope `INIT-0001` through the formal state CLI.
-3. Register `TASK-INIT-0001-00` for `00-bootstrap` and `TASK-INIT-0001-01` for `01-product-discovery`, with the latter depending on the former.
-4. Finish the bootstrap task only after its report and handoff evidence are registered, then activate the discovery task.
+3. Register `TASK-INIT-0001-00` for `00-bootstrap` and `TASK-INIT-0001-01` for `01-product-shaping`, with the latter depending on the former.
+4. Finish the bootstrap task only after its report and handoff evidence are registered, then activate the Product Shaping task.
 5. Let `task-state.mjs` resolve `code_branch` and `code_commit` from the authoritative `.workflow/config/workspace.yaml`; never use the install manifest copy or record the workflow Git identity as code identity.
 
 The first product question is the safe stopping point. Do not invent the initial business need and do not leave product artifacts outside an initialized task.
@@ -44,13 +44,13 @@ 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. Never use `--force` unless 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 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.
 
 ## Brownfield Rules
 
 Treat repository scans as observations, not approved product or architecture truth. Keep generated artifacts `draft`. Exclude secrets, dependency/build directories, workflow internals, and files outside the project. Verify inferred commands before recording them as supported.
 
-Do not replace existing product, architecture, test, or release baselines. Register the project-state report, preserve every timestamped bootstrap run, and update only the `.workflow/delivery/bootstrap/latest.yaml` pointer.
+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.
 
 ## Resume Boundary
 

package/skills/ai-delivery-bootstrap/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Bootstrap AI Delivery"
-  short_description: "Inspect project state and route the next workflow action"
+interface:
+  display_name: "Bootstrap AI Delivery"
+  short_description: "Inspect project state and route the next workflow action"
   default_prompt: "Use $ai-delivery-bootstrap to inspect the dual-repository workspace, recover shared checkpoints, or initialize the minimum delivery context."

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

@@ -28,6 +28,8 @@ 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 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.
 
 When an active or dependency-ready runtime task exists, defer to its task contract and write no bootstrap artifacts. An `agent`-owned next action routes to checkpoint recovery. A `user`-owned next action returns the recorded question verbatim and forbids all task, checkpoint, artifact, formal-state, and Git mutation until the user answers. An `external`-owned next action reports the wait condition and also forbids mutation. Read-only inspection must return `mutation_allowed: false` for the latter two cases.
@@ -46,7 +48,7 @@ For a newly initialized project or a ready project without a recoverable task, c
     bootstrap-plan.yaml
 ```
 
-Register `project-state-report.yaml` through `.workflow/tools/state/state.mjs artifact register`. Keep every generated artifact `draft`. Bootstrap code must call the shared formal-state module and must not parse and rewrite the registry itself.
+Keep every generated artifact `draft` and do not register it in the formal artifact registry. `project-state-report.yaml` remains discoverable through the checksummed `.workflow/delivery/bootstrap/latest.yaml` pointer until a later workflow node creates an immutable semantic revision. Bootstrap code must not parse or rewrite the registry itself.
 
 ## Artifact Meaning
 
@@ -61,7 +63,7 @@ Register `project-state-report.yaml` through `.workflow/tools/state/state.mjs ar
 
 Natural-language startup is the public user interface. The AI must translate “开始”, “继续”, “下一步”, status questions, product ideas, and release intent into internal Skill and CLI calls; it must never delegate workflow command selection or execution to the user.
 
-For a ready installation with no formal delivery artifact and no task shard, initialize the deterministic `INIT-0001` bootstrap/discovery task pair before writing product material. This is runtime state, unlike the draft tasks in `bootstrap-plan.yaml`. Resolve every shared task's code identity from the nested repository configured by `.workflow/config/workspace.yaml`, never from the install manifest or workflow repository.
+For a ready installation with no formal delivery artifact and no task shard, initialize the deterministic `INIT-0001` Bootstrap/Product Shaping task pair before writing product material. This is runtime state, unlike the draft tasks in `bootstrap-plan.yaml`. Resolve every shared task's code identity from the nested repository configured by `.workflow/config/workspace.yaml`, never from the install manifest or workflow repository.
 
 For an empty project, hand off to `$ai-delivery-define-product` and ask for the problem to solve, target users, and success measure one decision at a time.
 

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

@@ -11,6 +11,10 @@ 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.
@@ -25,6 +29,16 @@ Write portable task state to `.workflow/control/tasks/<task-id>.yaml` and `.work
 
 Use statuses `queued`, `preparing`, `running`, `checkpointed`, `pending-review`, `blocked`, `interrupted`, `completed`, `failed`, and `abandoned`.
 
+## Stable Logical Tasks And Attempts
+
+Keep one stable logical task identity while iteration, node, skill, goal, scope, responsibility, dependencies, and acceptance remain unchanged. Register those fields with `init`, including repeatable `--scope` and `--acceptance` values plus `--responsibility`; every new task is initialized as `queued`, and any other requested status is rejected. Repeating the same `init` is zero-write and idempotent; attempting to register the same logical contract under another task ID is rejected. If any logical contract field changes, create a new task ID and link it with `--derived-from <task-id>` or `--supersedes <task-id>`; never encode planning, review, triage, repair, test, or version rounds in a new task-name suffix.
+
+A queued task has no attempt and cannot be checkpointed or finished; `activate --phase <phase>` creates attempt `A1`. Phase status is derived from the task transition, and `--phase-status` is not supported. Record planning, implementation, review, triage, repair, test, verification, and handoff as structured phases. Entering a review phase captures its immutable `review_subject_baseline`; later approval fails if Git changed during feedback collection. Record a review or test finding with `--finding-json <json>`; finding records are append-only, and the latest record with the same ID is its current task-level conclusion. Close feedback collection in the review phase with `--change-set-json <json>` containing `change_set_id`, `approval_actor`, `rationale`, exact `finding_ids`, repository-relative `allowed_files`, `expected_evidence`, `review_axes`, and `collection_decision`. The CLI promotes the pinned subject to `repair_baseline`, persists the canonical `feedback_collection`, and computes its SHA-256 `collection_checksum`; a caller-supplied checksum is optional and must match. A `resolved` record must reference an existing open finding and recorded approved change set, be written during concentrated rereview in the review phase, carry the expected evidence, and declare `changed_files` exactly equal to the real Git changes since approval and within the allowed files. `completed` is refused while any current blocking finding is still `open`. Optionally attribute elapsed time with paired `--time-category <category> --elapsed-minutes <minutes>`. A failed attempt cannot satisfy dependencies. Retry the unchanged task only with `activate --new-attempt --phase repair`; this creates the next attempt under the same task ID. A later task becomes dependency-ready only after the logical task itself reaches `completed`.
+
+During review, finish feedback collection across the pinned subject before any repair begins. Group every current open finding into one immutable approved `--change-set-json` record; the executor applies only that set in a repair phase and records its evidence before concentrated rereview. Never interleave code changes with feedback collection or add an unapproved finding or file to the active set.
+
+Run `scripts/task-state.mjs inspect --task-id <task-id> --include-closed` for strict read-only diagnosis. It returns source reconciliation, dependency state, attempt totals, current phase, and time by category without hydrating runtime, writing a resume, checkpointing, or changing Git state.
+
 ## Checkpoint
 
 Checkpoint after every externally meaningful milestone, before a long command, after test or review evidence, before context compaction, and before returning control. Keep `next_action` concrete and idempotent and set `next_action_owner` to `agent`, `user`, or `external`. Store decisions in their owning product, architecture, design, standard, or release artifact rather than in runtime notes alone. Repeated evidence references are idempotent and must remain unique.
@@ -33,7 +47,7 @@ Checkpoint after every externally meaningful milestone, before a long command, a
 
 1. Validate expected outputs and update the artifact registry through `.workflow/tools/state/state.mjs`.
 2. Record evidence, actual outputs, residual blockers, and the next workflow action.
-3. Atomically set `completed`, `blocked`, `failed`, `interrupted`, or explicitly `abandoned`. Treat `completed`, `failed`, and `abandoned` as closed tasks and omit them from default recovery output without archiving them individually.
+3. Atomically set `completed`, `blocked`, `failed`, `interrupted`, or explicitly `abandoned`. Closed statuses `completed`, `failed`, and `abandoned` may be written only by `finish`, never `checkpoint`. Treat them as closed for historical counts and archival eligibility. Default recovery omits `completed` and `abandoned`, but returns `failed` as retryable work until a new attempt completes or the version is abandoned.
 4. After the task snapshot succeeds, update formal workflow state only through `.workflow/tools/state/state.mjs`, then run its `verify` command.
 5. Invoke `$ai-delivery-evolve-workflow evaluate --safe-point task` after the task and formal-state writes are complete. Apply any newly eligible extension only to the next task; do not change the task that just finished.
 6. Never mark production deployment complete from a Hook event.
@@ -43,14 +57,14 @@ Checkpoint after every externally meaningful milestone, before a long command, a
 1. Use the iteration version as the archive unit; never archive one completed task independently.
 2. Require version status `release-ready`, `released`, or `abandoned` and at least one completion evidence reference. Require `candidate_id` for `release-ready`; require `release_id` for `released`.
 3. Refuse archival while any version task is queued, preparing, running, checkpointed, pending review, blocked, or interrupted.
-4. Write the portable archive manifest, task snapshots, and shared checkpoints under `.workflow/control/archives/versions/<version-id>/`. Retain detailed local event, heartbeat, and recovery copies under ignored runtime by default; use `--portable-only` to omit that disposable, non-authoritative copy.
+4. Before writing any archive file, require `state.mjs snapshot references` to project the target version from the latest trusted version-boundary anchor. Fail closed unless it returns the scope manifest, selected candidate, Gate decisions, and history anchor. Then write the portable archive manifest, task snapshots, and shared checkpoints under `.workflow/control/archives/versions/<version-id>/`. The manifest references checksummed task summary files and the complete referenced attempt values within that archive, plus every formal projection by relative path and checksum rather than copying their bodies. Retain detailed local event, heartbeat, and recovery copies under ignored runtime by default; use `--portable-only` to omit that disposable, non-authoritative copy.
 5. Only after the portable archive is complete, remove the version's shards from `.workflow/control/tasks/` and `.workflow/control/checkpoints/` and remove local active records. Normal recovery scans active collections only and must not load archived details, even with `--include-closed`.
 
 ## Recover
 
 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.
 
-Generate a compact recovery report from snapshots, checkpoints, Hook events, Git, and workspace state. Return only non-closed tasks by default; use `--include-closed` only for an explicit audit. For each iteration, report total, completed, closed, remaining, active, queued, dependency-ready, and waiting tasks plus one deterministic `recommended_task_id`. Prefer an interrupted or active task; otherwise choose 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.
+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/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Checkpoint Delivery Task"
-  short_description: "Persist task checkpoints, hook events, and resume context"
+interface:
+  display_name: "Checkpoint Delivery Task"
+  short_description: "Persist task checkpoints, hook events, and resume context"
   default_prompt: "Use $ai-delivery-checkpoint-task to start, checkpoint, publish, finish, or recover a shared delivery task."

package/skills/ai-delivery-checkpoint-task/assets/runtime-template/task.json

@@ -6,9 +6,15 @@
   "status": "queued",
   "sequence": 1,
   "depends_on": [],
-  "attempt": 1,
+  "attempt": 0,
+  "attempts": [],
+  "change_sets": [],
   "goal": "",
+  "responsibility": "",
   "scope": [],
+  "acceptance": [],
+  "derived_from": null,
+  "supersedes": null,
   "input_artifacts": [],
   "standards": [],
   "branch": null,

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"))