ai-delivery-workflow 0.5.1 → 0.7.0

package/skills/ai-delivery-orchestrate/assets/communication-template/confirmation-examples.yaml

@@ -0,0 +1,67 @@
+schema_version: 1
+summary_id: CONFIRMATION-EXAMPLE-0001
+version: 2
+status: confirmed
+node: 01-product-shaping
+iteration_id: ITERATION-EXAMPLE-0001
+task_id: TASK-EXAMPLE-0001
+owner: product-and-architecture-reviewers
+source_revision: EXAMPLE-SOURCE-REVISION
+updated_at: 2026-08-23T00:00:00Z
+frontier_round: 2
+shared_understanding: true
+shared_understanding_actor: human:product-owner
+shared_understanding_confirmed_at: 2026-08-23T00:05:00Z
+grouping_rationale: null
+records:
+  - confirmation_id: CONF-PRODUCT-0001
+    question_id: Q-PRODUCT-0001
+    parent_decision_id: null
+    frontier_round: 1
+    category: business_decision
+    status: confirmed
+    question: "Which problem is in the first release?"
+    recommendation: "Start with preventing missed handoffs."
+    options:
+      - id: MISSED-HANDOFFS
+        label: "Prevent missed handoffs"
+        rationale: "Matches the observed operational pain and keeps scope narrow."
+    decision: "Prevent missed handoffs"
+    rationale: "The sponsor prioritizes accountability over reporting breadth."
+    actor: human:product-owner
+    confirmed_at: 2026-08-23T00:01:00Z
+    depends_on: []
+    evidence_refs: ["bootstrap-report@1"]
+    authority_refs: ["product-manual@1"]
+    impact_refs: ["scope-baseline@1"]
+    owner: product-owner
+    next_action: "Ask the dependent architecture boundary question."
+    next_action_owner: agent
+    supersedes: null
+    superseded_by: null
+  - confirmation_id: CONF-ARCH-0001
+    question_id: Q-ARCH-0001
+    parent_decision_id: CONF-PRODUCT-0001
+    frontier_round: 2
+    category: architecture_decision
+    status: confirmed
+    question: "Should handoff ownership be enforced in the workflow state model?"
+    recommendation: "Enforce explicit owner transfer and zero-mutation waits."
+    options:
+      - id: EXPLICIT-OWNER
+        label: "Explicit owner transfer"
+        rationale: "Prevents an agent from guessing through a user wait."
+    decision: "Explicit owner transfer"
+    rationale: "The sponsor accepts the additional checkpoint fields for auditability."
+    actor: human:maintainer
+    confirmed_at: 2026-08-23T00:04:00Z
+    depends_on: [CONF-PRODUCT-0001]
+    evidence_refs: ["checkpoint-contract@1"]
+    authority_refs: ["architecture-baseline@1", "architecture-gate@1"]
+    impact_refs: ["checkpoint-contract@1"]
+    owner: architecture-owner
+    next_action: "Link both decisions to the approved baselines before Gate completion."
+    next_action_owner: agent
+    supersedes: null
+    superseded_by: null
+open_questions: []

package/skills/ai-delivery-orchestrate/assets/communication-template/confirmation-summary.yaml

@@ -0,0 +1,42 @@
+schema_version: 1
+summary_id: CONFIRMATION-SUMMARY-0001
+version: 1
+status: draft
+node: 01-product-shaping
+iteration_id: ITERATION-0001
+task_id: TASK-0001
+owner: team-or-role
+source_revision: REPLACE_WITH_CODE_OR_WORKFLOW_COMMIT
+updated_at: REPLACE_WITH_ISO_TIMESTAMP
+frontier_round: 1
+shared_understanding: false
+shared_understanding_actor: null
+shared_understanding_confirmed_at: null
+grouping_rationale: null
+records:
+  - confirmation_id: CONF-0001
+    question_id: Q-0001
+    parent_decision_id: null
+    frontier_round: 1
+    category: business_decision
+    status: proposed
+    question: "What decision must the user make?"
+    recommendation: "Recommended option and why."
+    options:
+      - id: OPTION-A
+        label: "Option A"
+        rationale: "Tradeoff and evidence."
+    decision: null
+    rationale: null
+    actor: null
+    confirmed_at: null
+    depends_on: []
+    evidence_refs: []
+    authority_refs: []
+    impact_refs: []
+    owner: product-owner
+    next_action: "Ask Q-0001 and wait for the user's answer."
+    next_action_owner: user
+    supersedes: null
+    superseded_by: null
+open_questions: []

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/iterations/ITER-0001/02-solution-design/product-impact-assessment.yaml

@@ -0,0 +1,42 @@
+artifact_id: PRODUCT-IMPACT-ASSESSMENT-0001
+artifact_type: product-impact-assessment
+version: 1
+iteration_id: ITER-0001
+status: draft
+producer_skill: ai-delivery-design-architecture
+source_node: 02-solution-design
+input_artifacts: []
+product_baseline:
+  id: PRODUCT-BASELINE-0001
+  version: 1
+  checksum: REPLACE_WITH_SHA256
+decision: clarification-required
+trigger:
+  kind: prototype-adjustment
+  summary: REPLACE_WITH_OBSERVED_CHANGE
+affected_product_assets:
+  terminals: []
+  features: []
+  stories: []
+  acceptance_criteria: []
+  non_functional_requirements: []
+  business_terms: []
+affected_design_assets:
+  experience_changes: []
+  prototype_pages: []
+  review_scenes: []
+  architecture_decisions: []
+  quality_budgets: []
+confirmation:
+  questions: []
+  summary_ref: .workflow/communication/confirmation-summary.yaml
+return:
+  required: true
+  node: 01-product-shaping
+  mode: prototype-reconciliation
+  reason: REPLACE_WITH_REASON
+rebaselines_required: []
+stale_artifacts: []
+product_reconciliation_ref: null
+evidence: []
+blocking_issues: []

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/bootstrap/bootstrap.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 
 import path from "node:path";
-import { bootstrapProject, inspectProjectState } from "./project-bootstrap.mjs";
+import { bootstrapProject, inspectProjectState, projectCodebaseIndex } from "./project-bootstrap.mjs";
 
 function usage() {
   return [
     "Usage:",
     "  node .workflow/tools/bootstrap/bootstrap.mjs inspect [project]",
     "  node .workflow/tools/bootstrap/bootstrap.mjs bootstrap [project] [--dry-run]",
+    "  node .workflow/tools/bootstrap/bootstrap.mjs project-index [project] [--output path]",
   ].join("\n");
 }
 
@@ -17,12 +18,16 @@ try {
   if (command === "--help" || command === "help") {
     process.stdout.write(`${usage()}\n`);
   } else {
-    const projectArg = args.find((value, index) => index > 0 && !value.startsWith("--"));
+    const projectArg = args.find((value, index) => index > 0 && !value.startsWith("--") && args[index - 1] !== "--output");
     const target = path.resolve(projectArg || process.cwd());
+    const outputIndex = args.indexOf("--output");
+    const output = outputIndex >= 0 ? args[outputIndex + 1] : null;
     const result = command === "inspect"
       ? inspectProjectState(target)
       : command === "bootstrap"
         ? bootstrapProject(null, target, { dryRun: args.includes("--dry-run") })
+        : command === "project-index"
+          ? projectCodebaseIndex(path.resolve(target, inspectProjectState(target).workspace?.code_repository?.path || "code"), output ? path.resolve(target, output) : null)
         : null;
     if (!result) throw new Error(`Unknown command: ${command}\n\n${usage()}`);
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/skills/ai-delivery-orchestrate/references/codebase-document-contract.md

@@ -0,0 +1,93 @@
+# Codebase Documentation Contract
+
+This contract defines the project-owned documentation that lives in the independent code repository. It is a writing and validation contract, not a second workflow state store.
+
+## Files
+
+```text
+code/
+├─ AGENTS.md
+├─ CODEBASE_GUIDE.md
+└─ docs/
+   └─ CODEBASE_INDEX.md
+```
+
+- `CODEBASE_GUIDE.md` is the human-readable handbook for repository maintainers and contributors.
+- `AGENTS.md` is a short agent entrypoint. It contains only high-priority rules and conditional pointers into the handbook and index.
+- `docs/CODEBASE_INDEX.md` is the human-readable navigation map for directories, modules, entrypoints, tests, dependencies, risks, and maintenance ownership.
+
+`docs/CODEBASE_INDEX.md` remains the single source of truth. When a CLI, CodeGraph adapter, or validator needs structured input, generate the read-only machine projection with `node .workflow/tools/bootstrap/bootstrap.mjs project-index <project>`. The projection is written to the workflow repository at `.workflow/delivery/bootstrap/codebase-index.yaml`, includes the source checksum and status, and is never edited directly or copied back into Markdown.
+
+## Authority
+
+The project workflow repository remains authoritative for approved architecture, standards, formal state, task scope, Gates, and release identity. Code-repository documentation explains how to apply those decisions while working in source. When the handbook conflicts with an approved workflow artifact, stop relying on the conflicting section, report the conflict, and update the handbook through the owning workflow node.
+
+The environment is authoritative for facts it already expresses precisely, such as package scripts, compiler options, CI jobs, and directory names. The handbook should capture rationale, conventions, risks, and entrypoints that the environment cannot express reliably; it should link to rather than duplicate long configuration files.
+
+## Audience and language
+
+Write for a repository maintainer first. Use plain Simplified Chinese for explanatory prose and preserve technical identifiers, paths, commands, schemas, and protocol values exactly. A maintainer should be able to answer these questions without reading source code first:
+
+1. What is this project and where does execution start?
+2. How do I install, run, test, debug, review, and release it?
+3. Which layers and modules may depend on each other?
+4. Which paths are high risk, generated, externally maintained, or not directly editable?
+5. Which tests and evidence are required after a change?
+6. Who maintains this document and when must it be updated?
+
+## Guide sections
+
+`CODEBASE_GUIDE.md` must contain, or explicitly link to, these sections:
+
+1. project overview and ownership;
+2. quick start and verified commands;
+3. repository map and runtime entrypoints;
+4. layering and dependency direction;
+5. naming, testing, error, logging, configuration, security, and migration conventions;
+6. change workflow and verification expectations;
+7. risks, generated files, protected paths, and rollback notes;
+8. documentation ownership, freshness, approval references, and update triggers.
+
+## Index fields
+
+Every index row describes a directory or a key file relative to the code-repository root. Use these columns when applicable:
+
+| Field | Meaning |
+| --- | --- |
+| `path` | Relative path; never an absolute path or a path containing `..`. |
+| `purpose` | Why the directory or file exists. |
+| `entrypoints` | Main executable, route, public API, or command entrypoints. |
+| `tests` | Relevant native test paths or commands. |
+| `dependencies` | Important allowed dependencies or consumers. |
+| `risk` | `low`, `medium`, or `high`, with a short reason for `high`. |
+| `generated` | Whether a command regenerates the content. |
+| `owner` | Team or role responsible for keeping the entry accurate. |
+| `source_commit` | Code commit the entry was checked against. |
+| `last_reviewed` | ISO date of the latest human or validator review. |
+| `status` | `observed`, `approved`, or `stale`. |
+| `references` | Architecture, standards, task, test, or operational references. |
+
+Directory-level rows are the default. Use file-level rows for entrypoints, cross-layer adapters, persistence/authentication/deployment configuration, generated boundaries, and high-risk modules. The index is not required to enumerate every ordinary source file.
+
+## Freshness and safety
+
+- `observed` means discovered by Bootstrap or a tool and not yet approved by a maintainer.
+- `approved` means reviewed against the current code and the relevant approved architecture/standards.
+- `stale` means the recorded `source_commit` or referenced path may no longer describe the code.
+- A missing, stale, conflicting, or path-invalid entry must be reported before code modification relies on it.
+- Never put credentials, private keys, production data, or large source excerpts in these files.
+- `init` and `upgrade` must preserve existing code-repository documentation. Any creation or revision must be explicit, reviewable, and attributable to the owning workflow task.
+- A projection with a checksum mismatch, invalid source index, or stale source commit is unusable until the Markdown source is reviewed and regenerated.
+
+## Writing quality
+
+Prefer short paragraphs, tables, links, and concrete examples. Put the answer before the background. Keep one rule in one authoritative location. Link to formal workflow artifacts instead of copying their full contents. Every procedural section should end with a checkable command, file, review, or evidence criterion.
+
+## Completion checklist
+
+- A maintainer can find the runtime entrypoint, test entrypoint, and high-risk paths within one screen of navigation.
+- Every high-risk index row names its tests, owner, and update trigger.
+- Commands are verified from repository configuration or a recorded validation run.
+- All paths resolve inside the code repository and all status/commit metadata is current.
+- Conflicts with workflow architecture or standards are explicitly linked and not silently resolved in prose.
+- Any machine consumer reads the generated projection only after verifying `source_checksum` against the current Markdown source.

package/skills/ai-delivery-orchestrate/references/communication-confirmation-contract.md

@@ -0,0 +1,69 @@
+# Communication Confirmation Contract
+
+This contract records structured user decisions without storing a conversation transcript. It is a traceability index, not a second product, architecture, standards, task, or formal-state authority.
+
+## Placement and authority
+
+Store a mutable draft and its later immutable revisions under the current workflow repository's version-scoped node directory:
+
+```text
+.workflow/iterations/<iteration-id>/<node-id>/confirmation-summary.yaml
+```
+
+The summary may point to product, architecture, standards, task, Gate, or release artifacts, but those owning artifacts remain authoritative. A `confirmed` record is incomplete until its `authority_refs` points to the owning artifact or explicitly records the handoff that will create it.
+
+Do not store full chat transcripts, credentials, production data, or model reasoning. Preserve only the question, recommendation, decision, rationale, evidence references, impact, and next action needed to resume safely.
+
+## Knowledge categories
+
+Allowed `category` values are:
+
+- `observed_fact`: source, configuration, Git, test, or runtime fact found by the Agent;
+- `business_fact`, `business_decision`, `domain_term`, `business_constraint`;
+- `architecture_decision`;
+- `standard_decision`;
+- `risk`, `assumption`, `open_question`;
+- `execution_fact`, `execution_decision`.
+
+Facts require `evidence_refs`. User decisions require `actor`, `decision`, and `confirmed_at`; an Agent recommendation is never approval. `domain_term` records must point to the Product Manual Business Glossary or a superseding product artifact. `architecture_decision` records must point to an architecture baseline, decision record, or architecture Gate.
+
+## Confirmation statuses
+
+`proposed` is waiting for a decision. `confirmed` and `rejected` close a decision. `deferred` remains unresolved and must retain a responsible owner and next action. `superseded` is historical and must point to the replacement through `supersedes` or `superseded_by`.
+
+## Decision tree and frontier
+
+Each record has a stable `confirmation_id`, a `question_id`, a `frontier_round`, and optional `depends_on` decision IDs. The current frontier consists only of `proposed` records whose dependencies are closed by `confirmed`, `rejected`, or a valid superseding record. A dependency cycle, unknown dependency, or proposed record with unresolved dependencies is invalid rather than silently skipped.
+
+The default interaction policy is one user decision per round. Multiple questions may be presented together only when they are independent, low-risk, and the summary explicitly records the grouping rationale.
+
+## All-node integration
+
+Every formal development and release node uses this same protocol when a user or external decision is needed. The node-specific authority remains the owner shown below:
+
+| Node | Questions and knowledge to capture | Authority / return path |
+| --- | --- | --- |
+| `00-bootstrap` | observed repository facts, missing context, first product frontier | Bootstrap report; business choices return to `01-product-shaping` |
+| `01-product-shaping` | users, goals, scope, terminals, domain terms, business rules, priority, risk acceptance | discovery/product baseline and `GATE-A`/`GATE-B` |
+| `02-solution-design` | architecture tradeoffs, UX choices, new terminals, non-functional impact, product-impact assessment | architecture/experience baseline, UX Gates, or product return |
+| `03-delivery-readiness` | Slice boundaries, dependencies, environments, test policy, budget exceptions | scope manifest, test/platform contracts, or scope amend |
+| `04-implementation` | behavior ambiguity, implementation constraints, risk acceptance, allowed-file changes | task evidence, approved change set, or owning-node return |
+| `05-candidate-assurance` | exceptions, residual risk, test gaps, candidate acceptance | review/verification evidence or producer return |
+| `06-version-closeout` | unresolved decisions, release readiness, archive exceptions | version manifest/closeout; release intent remains separate |
+| `R00`-`R10` release | release intent, target selection, eligibility exceptions, production approval, deployment/rollback decisions | release artifacts, `PRODUCTION-APPROVAL`, production evidence |
+
+At node entry, read the current summary before asking a question. After each answer, append or supersede the record, recompute the frontier, and link the decision to its authority artifact before advancing. A node may continue without a question only when its evidence proves the decision is agent-verifiable or an approved baseline is unchanged.
+
+## Shared understanding
+
+Set `shared_understanding: true` only after the current frontier is empty and the user has confirmed the summary. `deferred` and `open_question` records may remain, but each must identify an owner and an idempotent `next_action`. A node must not perform an action that depends on an unresolved decision.
+
+## Wait and mutation boundary
+
+When `next_action_owner` is `user` or `external`, the task remains a zero-mutation wait state. Recovery reports the exact recorded question or wait condition; it does not activate tasks, mutate formal state, register artifacts, or change Git. After the required input arrives, the controlled task CLI transfers ownership to `agent` with a new idempotent next action.
+
+## Superseding and provenance
+
+Never edit a confirmed record in place. A correction creates a new record with `supersedes`, retains the previous checksum/reference, and routes affected artifacts stale or back to their owning node. Every summary revision should retain `summary_id`, `version`, `source_revision`, `owner`, and `updated_at`.
+
+See `assets/communication-template/confirmation-examples.yaml` for a maintainer-readable two-round example: a confirmed product decision opens an architecture frontier, and shared understanding is recorded only after both decisions have authority references.

package/skills/ai-delivery-orchestrate/references/product-impact-assessment-contract.md

@@ -0,0 +1,87 @@
+# Product Impact Assessment Contract
+
+`product-impact-assessment.yaml` is the shared design-stage receipt for any finding that may change an approved product baseline. It is an impact record, not a product decision. Product intent, scope, terminology, priority, risk acceptance, and terminal selection remain owned by `01-product-shaping`.
+
+## When to create one
+
+Create one before continuing `02-solution-design` when design discovers any of the following:
+
+- a Prototype adjustment changes user-visible behavior, acceptance, or a terminal;
+- a new logical terminal, Page, Review Scene, or channel is needed;
+- a quality, security, privacy, compliance, availability, performance, or cost requirement changes product tradeoffs;
+- an architecture constraint changes a goal, business rule, scope, priority, risk acceptance, or terminology;
+- a user confirmation is needed to choose between materially different product outcomes.
+
+Use `no-impact` only when the evidence proves that approved product behavior, scope, terminals, terminology, acceptance, and non-functional requirements are unchanged.
+
+## Controlled values
+
+`decision` is one of:
+
+- `no-impact`: design may continue after recording evidence;
+- `architecture-only`: only implementation structure changes and approved product behavior is unchanged;
+- `product-update-required`: product must create and approve a successor baseline;
+- `clarification-required`: a user decision is needed before classification can close.
+
+`status` is `draft`, `awaiting-product`, `resolved`, `invalid`, or `superseded`. A resolved `no-impact` or `architecture-only` assessment has `status: resolved`; `product-update-required` and `clarification-required` remain `awaiting-product` until a valid product reconciliation receipt is linked.
+
+## Required fields
+
+```yaml
+artifact_id: PRODUCT-IMPACT-ASSESSMENT-0001
+artifact_type: product-impact-assessment
+version: 1
+iteration_id: ITER-0001
+status: draft
+producer_skill: ai-delivery-design-architecture
+source_node: 02-solution-design
+input_artifacts: []
+product_baseline:
+  id: PRODUCT-BASELINE-0001
+  version: 1
+  checksum: SHA256
+decision: clarification-required
+trigger:
+  kind: prototype-adjustment
+  summary: "Describe the observed change"
+affected_product_assets:
+  terminals: []
+  features: []
+  stories: []
+  acceptance_criteria: []
+  non_functional_requirements: []
+  business_terms: []
+affected_design_assets:
+  experience_changes: []
+  prototype_pages: []
+  review_scenes: []
+  architecture_decisions: []
+  quality_budgets: []
+confirmation:
+  questions: []
+  summary_ref: .workflow/communication/confirmation-summary.yaml
+return:
+  required: true
+  node: 01-product-shaping
+  mode: prototype-reconciliation
+  reason: "Explain why product ownership is required"
+rebaselines_required: []
+stale_artifacts: []
+product_reconciliation_ref: null
+evidence: []
+blocking_issues: []
+```
+
+Every listed asset uses a stable ID. Every input and evidence item pins a version and checksum when one exists. `return.node` is `01-product-shaping` for `product-update-required` and `clarification-required`; it is the owning design phase for a closed `no-impact` or `architecture-only` result.
+
+## Closure and propagation
+
+1. The producing design skill writes the assessment and checkpoints it before asking a user question or changing downstream artifacts.
+2. `product-update-required` or `clarification-required` blocks the current design handoff. Product owns the question and writes `product-prototype-reconciliation.yaml` plus a new approved product baseline when needed.
+3. A successor product baseline supersedes the input baseline. Affected architecture, experience, planning, test, and delivery artifacts become `stale` until revalidated against the successor checksum.
+4. `architecture-only` may continue only when the assessment explicitly proves no product asset changed and any major architecture decision has its own approval.
+5. `no-impact` and `architecture-only` do not authorize editing a frozen Prototype or approved product baseline.
+
+## Compatibility
+
+The existing `prototype-impact-assessment.yaml` remains a Prototype-local evidence record. Its `assessments`, review checksums, and adjustment log are consumed as `input_artifacts` or `affected_design_assets`; it must be wrapped by this contract before a cross-node return or final handoff. The old `decision: changes-required` maps to `product-update-required` only when an affected product asset is listed; otherwise it maps to `architecture-only` or `clarification-required` after review.

package/skills/ai-delivery-orchestrate/scripts/confirmation-state.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { readConfirmationSummary } from "../../../lib/communication-confirmation.mjs";
+
+const [command, file] = process.argv.slice(2);
+if (!command || !file || !["validate", "frontier"].includes(command)) {
+  console.error("Usage: confirmation-state.mjs <validate|frontier> <confirmation-summary.yaml>");
+  process.exit(2);
+}
+try {
+  const result = readConfirmationSummary(file);
+  const payload = {
+    summary_checksum: result.checksum,
+    valid: result.validation.valid,
+    errors: result.validation.errors,
+    warnings: result.validation.warnings,
+    frontier: result.validation.frontier,
+    blocked_proposals: result.validation.blocked_proposals,
+  };
+  process.stdout.write(`${JSON.stringify(command === "frontier" ? {
+    summary_checksum: payload.summary_checksum,
+    valid: payload.valid,
+    errors: payload.errors,
+    frontier: payload.frontier,
+    blocked_proposals: payload.blocked_proposals,
+  } : payload, null, 2)}\n`);
+  process.exit(result.validation.valid ? 0 : 1);
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/skills/ai-delivery-orchestrate-release/SKILL.md

@@ -5,6 +5,8 @@ description: Orchestrate a production release independently from iteration deliv
 
 # Orchestrate Independent Release
 
+Release nodes use the shared confirmation protocol for explicit release intent, target selection, eligibility exceptions, production approval, deployment, rollback, and archive decisions. User/external waits are zero-mutation and never replay production actions.
+
 Coordinate `R00` through `R10`. Never infer release intent from completed versions or start production work from normal iteration orchestration.
 
 ## Start From Explicit Intent
@@ -18,7 +20,7 @@ Coordinate `R00` through `R10`. Never infer release intent from completed versio
 ## Route Release Nodes
 
 1. `R01-version-selection`: invoke `$ai-delivery-assemble-release` to calculate and freeze the version selection, including the R00 `main` snapshot and exactly one target `version-ready` Tag.
-2. `R02-release-eligibility`: require continuous lineage, immutable tags, eligible artifacts, and the unchanged R00 main snapshot. For incremental release the snapshot must precede the target Tag; for same-version redeploy the target Tag must already be reachable from the snapshot. Also require every adjacent code and workflow ancestry edge, available images, compatible migrations/configuration, and no stale candidate.
+2. `R02-release-eligibility`: require continuous lineage, immutable tags, eligible artifacts, and the unchanged R00 main snapshot. For incremental release the snapshot must precede the target Tag; for same-version redeploy the target Tag must already be reachable from the snapshot. Also require every adjacent code and workflow ancestry edge, available images, compatible migrations/configuration, a resolved or superseded product impact assessment, and no stale candidate.
 3. `R03-material-aggregation`: aggregate checksummed requirements, architecture, prototypes, code, images, configuration, migrations, tests, risks, operations, and rollback materials.
 4. `R04-release-candidate`: invoke `$ai-delivery-manage-git`'s `scripts/release-git.mjs create-candidate` with `--release-id`, `--release-branch`, `--expected-main`, one `--source-tag`, its exact `--source-commit`, `--receipt`, and `--apply`. It creates `release/<release-id>-<slug>` from that snapshot. It merges the Tag with `--no-ff` for incremental release; for same-version redeploy when the Tag is already in the snapshot, it freezes that snapshot as the no-new-merge candidate. A moved `main` invalidates this release ID's candidate instead of changing its base.
 5. `R05-release-verification`: invoke `$ai-delivery-verify-candidate` with `scope: release`, bound to the exact candidate merge commit. Any release-fix creates a new candidate and repeats affected verification.
@@ -31,3 +33,5 @@ Coordinate `R00` through `R10`. Never infer release intent from completed versio
 Run routine formal `verify` at every handoff and reserve `verify --history` for R10 or an explicit history audit. Preserve failed releases and evidence. Stop instead of replaying a production action after recovery.
 
 Read [release-workflow-contract.md](references/release-workflow-contract.md) and use the request and selection assets.
+
+Validate the confirmation summary and require an explicit release decision linked to the release artifact. Proposed, deferred, or superseded records cannot authorize release; ambiguity returns to its owning node and leaves the release waiting.

package/skills/ai-delivery-plan-iteration/SKILL.md

@@ -5,6 +5,8 @@ description: Plan an agile AI delivery iteration by prioritizing business outcom
 
 # Plan Iteration
 
+When scope, priority, dependency, budget, or acceptance choices need confirmation, use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` and the version-scoped `confirmation-summary.yaml`. Recompute the frontier after each answer and keep unresolved business choices out of `scope freeze`.
+
 Plan business capability increments. Do not pre-split work into fixed frontend, backend, database, or human-role silos.
 
 ## Artifact Location
@@ -23,7 +25,7 @@ This Skill owns the planning task phases inside `03-delivery-readiness` and conv
 
 ## Preflight
 
-Read approved product, final architecture, and experience baselines; exact `ui-handoff.yaml`; aligned `product-prototype-reconciliation.yaml`; experience/requirement change sets; interaction, visual, component, and page-component contracts; the exact confirmed Prototype revision and checksum; its source and review-bundle checksums; the normalized terminal, Page, Review Scene, trigger-condition, route, and UI Mapping catalogs; and the accepted architecture receipt; current backlog; production state; applicable standards; and unresolved risks. Require `development_readiness: ready-for-development` and reject stale changes, missing or conflicting references, non-passing decisions, or identity/checksum mismatches. Never infer a relationship from a file name or catalog order. Distinguish product priority from technical execution order.
+Read approved product, final architecture, and experience baselines; exact `ui-handoff.yaml`; aligned `product-prototype-reconciliation.yaml`; experience/requirement change sets; interaction, visual, component, and page-component contracts; the exact confirmed Prototype revision and checksum; its source and review-bundle checksums; the normalized terminal, Page, Review Scene, trigger-condition, route, and UI Mapping catalogs; and the accepted architecture receipt; current backlog; production state; applicable standards; unresolved risks; and the code repository handbook/index entries for affected paths. Require `development_readiness: ready-for-development` and reject stale changes, missing or conflicting references, non-passing decisions, or identity/checksum mismatches. Never infer a relationship from a file name or catalog order. Distinguish product priority from technical execution order.
 
 ## Workflow
 
@@ -54,9 +56,14 @@ Read approved product, final architecture, and experience baselines; exact `ui-h
 - `slice-experience-change-traceability.csv` showing which added/modified/retired experience changes enter each slice;
 - replanning rules and current plan baseline.
 - a draft `scope-manifest.yaml` whose approved contents are frozen through `scope freeze`; later `scope amend` revisions are append-only and budget `scope warn` records never mutate it.
+- handbook/index readiness receipt recording the consulted `source_commit`, path/command/test validation, maintainer owner, and whether affected documentation needs an approved update.
 
 Do not output component-level technical tasks. The development orchestrator derives those just in time from a selected slice and the latest architecture.
 
+## Confirmation Boundary
+
+Read the current confirmation summary before proposing scope. Agent-verifiable facts require evidence; only product-owner scope choices and risk acceptance become user questions. Append each answer, recompute the frontier, and keep unresolved business decisions out of `scope freeze`.
+
 Read [planning-contract.md](references/planning-contract.md) and use `assets/planning-template/` for a new iteration.
 
 ## Handoff

package/skills/ai-delivery-prepare-platform/SKILL.md

@@ -5,6 +5,8 @@ description: Prepare the delivery and operations platform required to build, tes
 
 # Prepare Delivery Platform
 
+When a platform, environment, dependency, cost, or risk choice needs a user or external decision, read `../ai-delivery-orchestrate/references/communication-confirmation-contract.md`, update the current `confirmation-summary.yaml`, and wait without mutation while ownership is `user` or `external`.
+
 Run as a parallel stream after initial architecture and join application development before independent candidate verification.
 
 ## Artifact Location
@@ -23,7 +25,7 @@ This Skill contributes a parallel task stream inside `03-delivery-readiness`; it
 
 ## Preflight
 
-Read initial and final architecture as available, deployment topology, stack manifest, quality targets, security standards, current environment baselines, and iteration scope. Treat cloud, paid-service, privacy, and hard-to-reverse infrastructure changes as major architecture decisions.
+Read initial and final architecture as available, deployment topology, stack manifest, quality targets, security standards, current environment baselines, iteration scope, and the current confirmation summary. Treat cloud, paid-service, privacy, and hard-to-reverse infrastructure changes as major architecture decisions. Agent-investigated platform facts require evidence; user choices about cost, risk, privacy, or irreversible infrastructure require a frontier confirmation and the architecture/approval artifact that owns the decision.
 
 ## Workflow
 

package/skills/ai-delivery-prepare-release/SKILL.md

@@ -5,6 +5,8 @@ description: Prepare an independently verified multi-version or same-version rel
 
 # Prepare Release
 
+Use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` for release intent, target selection, exception, rollback, and external-side-effect questions. Version completion never substitutes for explicit release intent.
+
 Create an auditable release package. Do not deploy production.
 
 ## Artifact Location
@@ -46,3 +48,5 @@ Read [release-contract.md](references/release-contract.md) and use `assets/relea
 ## Handoff
 
 Return exactly one immutable prepared release package to `$ai-delivery-orchestrate-release`. Human production approval occurs independently at `R07-production-approval`.
+
+Read the closeout confirmation summary and require an explicit, current release intent. Version completion or candidate pass never authorizes publication or external side effects.

package/skills/ai-delivery-review-change/SKILL.md

@@ -5,6 +5,8 @@ description: Independently review a technical work-package change against approv
 
 # Review Change
 
+When review feedback requires an exception, risk acceptance, or scope decision, use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md`; link the confirmed result to the approved `change_set_id` or return it to the owning producer.
+
 Review independently from the implementation context. Do not edit product code or approve a change with unresolved blocking findings.
 
 ## Artifact Location
@@ -23,7 +25,7 @@ Use `04-implementation` for pre-merge package review phases. Use `05-candidate-a
 
 ## Preflight
 
-Read the work package, diff, approved source artifacts, standards versions, architecture constraints, TDD evidence, test results, allowed modification scope, exact UI handoff and `product-prototype-reconciliation.yaml` checksums, Prototype revision and UI Mapping checksums, task-to-experience-change actions, and terminal/Page/Review Scene/prototype-element/UI component/frontend-source/acceptance mappings for UI-bearing work. Reject missing or conflicting references and never infer relationships from file names or row order. Re-run relevant checks when evidence is absent or stale.
+Read the work package, diff, approved source artifacts, standards versions, architecture constraints, TDD evidence, test results, allowed modification scope, codebase handbook/index read receipt, exact UI handoff and `product-prototype-reconciliation.yaml` checksums, Prototype revision and UI Mapping checksums, task-to-experience-change actions, and terminal/Page/Review Scene/prototype-element/UI component/frontend-source/acceptance mappings for UI-bearing work. Reject missing or conflicting references and never infer relationships from file names or row order. Re-run relevant checks when evidence is absent or stale. Confirm structural changes have a matching index update or an explicit, justified no-change assessment.
 
 ## Two-Phase Review Protocol
 
@@ -48,3 +50,5 @@ Report findings first, ordered by severity, with tight file and line references.
 Do not use `pass` when required checks did not run. Do not repair findings yourself; return the approved change set to the work-package executor and wait for concentrated rereview evidence.
 
 Read [review-contract.md](references/review-contract.md).
+
+Review findings and confirmation records are separate evidence. If a finding requires user acceptance, an exception, or a product/architecture decision, append a proposed record and stop at its owning node; chat cannot close a Gate or expand allowed scope.