ai-delivery-workflow 0.5.1 → 0.6.0

package/skills/ai-delivery-orchestrate/assets/codebase-template/docs/CODEBASE_INDEX.md

@@ -0,0 +1,87 @@
+# 代码库索引
+
+> 本索引面向代码仓库管理者和 Agent。路径均相对于代码仓库根目录；工程规范见 [`CODEBASE_GUIDE.md`](../CODEBASE_GUIDE.md)。
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | `<observed | approved | stale>` |
+| 适用代码提交 | `<commit-or-tag>` |
+| 最后核对 | `<YYYY-MM-DD>` |
+| 维护责任 | `<team-or-role>` |
+| 正式依据 | `<architecture / standards / task references>` |
+
+## 1. 先从哪里看
+
+| 目标 | 首选位置 | 说明 |
+| --- | --- | --- |
+| 启动应用 | `<path>` | `<what it assembles>` |
+| 查找接口或路由 | `<path>` | `<protocol/entrypoint>` |
+| 查找业务规则 | `<path>` | `<domain/application boundary>` |
+| 查找数据访问 | `<path>` | `<repository/adapter>` |
+| 查找测试 | `<path>` | `<native test convention>` |
+| 查找部署配置 | `<path>` | `<environment/deployment boundary>` |
+
+## 2. 顶层目录
+
+| 路径 | 职责 | 主要入口 | 关联测试 | 风险 | 状态 |
+| --- | --- | --- | --- | --- | --- |
+| `<path>` | `<purpose>` | `<entrypoints>` | `<tests>` | `<low/medium/high>` | `<status>` |
+
+普通源码目录按职责归类；入口文件、跨层适配器、持久化/鉴权/部署配置和高风险模块可单独列在“关键文件索引”。
+
+## 3. 模块索引
+
+### `<module path>`
+
+`<one-sentence responsibility>`
+
+| 项目 | 内容 |
+| --- | --- |
+| 入口 | `<path>` |
+| 业务规则 | `<path>` |
+| 数据访问 | `<path>` |
+| 主要测试 | `<path/command>` |
+| 允许依赖 | `<modules or interfaces>` |
+| 禁止依赖 | `<private implementation or layer>` |
+| 高风险变更 | `<risk triggers>` |
+| 维护状态 | `<status>; 最近核对 <commit>` |
+
+重复模块按同一结构追加，避免把每个普通文件写成独立说明。
+
+## 4. 关键文件索引
+
+| 文件 | 作用 | 修改前先读 | 测试/验证 | 风险 | 生成或外部维护 |
+| --- | --- | --- | --- | --- | --- |
+| `<relative path>` | `<purpose>` | `<guide/decision/test contract>` | `<test or command>` | `<low/medium/high>` | `<no/generated/external>` |
+
+## 5. 典型定位路径
+
+### `<change type>`
+
+1. 从 `<entrypoint or module>` 开始；
+2. 检查 `<contract or dependency>`；
+3. 在 `<layer>` 实施业务变更；
+4. 更新或运行 `<tests>`；
+5. 如果结构、入口、依赖或风险变化，更新本索引并关联 `<reference>`。
+
+## 6. 不应从索引直接推断的内容
+
+- 索引不能替代实际源码、测试和当前 Git 状态核对；
+- `observed` 条目只是扫描观察，不能视为已批准架构；
+- `generated` 文件通过生成命令更新，不直接编辑；
+- 索引未列出的文件不等于允许修改；任务允许文件范围和正式安全规则优先；
+- CodeGraph、Semble 或索引给出的定位结果都必须回到具体源码和测试确认。
+
+## 7. 维护记录
+
+当顶层目录、模块、入口、依赖方向、测试位置、生成流程、部署入口或安全边界变化时更新本索引。
+
+| 字段 | 值 |
+| --- | --- |
+| `source_commit` | `<commit>` |
+| `last_reviewed` | `<YYYY-MM-DD>` |
+| `status` | `<observed | approved | stale>` |
+| `owner` | `<team-or-role>` |
+| `references` | `<architecture / standards / tasks>` |
+
+发现路径失效、提交漂移或内容冲突时，先标记为 `stale`；不要自动覆盖维护者文档。

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/references/codebase-document-contract.md

@@ -0,0 +1,91 @@
+# 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.
+
+The first release uses Markdown as the source of truth. A YAML or database projection is out of scope until a real consumer and synchronization contract exist.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,52 @@
+# 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.
+
+## 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

@@ -18,7 +18,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 +31,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

@@ -23,7 +23,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 +54,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

@@ -23,7 +23,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

@@ -46,3 +46,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

@@ -23,7 +23,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 +48,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.

package/skills/ai-delivery-validate-artifacts/SKILL.md

@@ -25,16 +25,19 @@ Require every workflow document to resolve under project `.workflow/` unless it
 4. Verify all association-table foreign keys and reject ad hoc multi-value cells where an association CSV is required.
 5. Verify required artifact sets for the target handoff.
 6. Verify baseline immutability, version increments, stale flags, and downstream impact declarations.
-7. Verify status transitions and human gates.
-8. Verify traceability from product goals through features, terminals, stories, acceptance criteria, Pages, Review Scenes, prototype elements, UI Mapping rows, UI components, frontend sources, Slices, tasks, tests, release items, and deployment evidence as applicable.
-9. For UI-bearing scope, validate the human tool-selection Gate, mandatory `UX-VS` and `UX-UI` human decisions, production-compatible runnable Prototype, stable Page and Review Scene identities, normalized terminal/trigger/route relations, Review Units, adjustment history, impact propagation, and aligned `product-prototype-reconciliation.yaml`. Validate that Workflow Manager evidence names the same checksummed target used by the Gate, uses its loopback origin and allowlisted review action, and contains no target revision drift; before `UX-VS`, its only content target is the Visual Reference, and afterward it is one exact Prototype revision.
-10. Validate every Prototype Page review receipt as an immutable checksummed YAML record under `.workflow/delivery/reviews/prototype-pages/<revision-id>/`. Reject an invalid or extra field, file-path/identity mismatch, actor, timestamp, receipt checksum, Prototype revision checksum, Page checksum, Scene checksum, or evidence checksum. Derive status from the current revision or its checksum-validated `previous_revision` ancestor chain, nearest ancestor first; reject inheritance from descendants or unrelated revisions. Carry forward only when the selected prior decision is approved and the complete Page checksum is identical; preserve a later changes-requested decision on that ancestor, and derive stale after any evidence change. Require the final Page receipt and approved `UX-UI` Gate decision to reference each other through the same actor, iteration, Prototype revision, and receipt checksum, and reject any later receipt unless a new pending `UX-UI` request exists.
-11. Verify that UI handoff, experience confirmation, architecture validation, test validation, planning, development, and verification all pin the same exact Prototype revision/checksum, source revision/checksum, review-bundle checksum, UI Mapping checksum, normalized catalog checksums, product reconciliation, experience-change checksum, review/impact checksums, and receipt checksums. Resolve every affected Page, Review Scene, UI component, frontend source, and acceptance criterion through explicit normalized foreign keys. Reject missing or conflicting references. Never infer relationships from file names or row order. Require downstream work to consume only `ready-for-development` changes.
-12. For every UI-bearing code handoff, validate the revision-bound `frontend-change-scope.yaml` checksum and its code root, non-empty frontend roots and extensions, shared component ownership, and file-only route registry ownership with the exact approved candidate-file SHA-256. Cross-check every active UI Mapping and ownership source against those roots and extensions; a declared source that would be skipped invalidates the scope. Run `ai-delivery frontend-guard verify-diff` with the handoff's fixed base and candidate head; require the independent Git diff to have current approved Page receipts and exact UI Mapping or scope coverage, and read changed route registries from the fixed candidate Git object rather than the mutable worktree. Reject Hook-only evidence, unmapped new or removed UI files, unapproved route-registry content, pending/changes-requested/stale Pages, and scope or revision drift.
-13. Before Candidate Assurance can pass a UI-bearing candidate, require successful `ui-acceptance plan` and `ui-acceptance verify` reports bound to the active attempt and immutable candidate checksum. Check exact Page/Scene/viewport coverage, pinned Playwright environment, visual diff counts and evidence, interaction and WCAG 2.2 AA checks, keyboard/focus/touch-target/text-overflow/responsive/recovery results, protocol evidence, Scenario Pack authority, and separate real backend evidence whenever Product Backend Mock rendered a Scene. Candidate checksum drift requires a new `04-implementation` candidate and Candidate Assurance attempt.
+7. For every `02-solution-design` handoff, validate the shared `product-impact-assessment.yaml`. Require a stable product-baseline binding, controlled decision, affected-asset IDs, return node, and checksums for every input/evidence reference. `product-update-required` and `clarification-required` are blocking until `01-product-shaping` supplies a valid aligned reconciliation and a successor product baseline; `no-impact` and `architecture-only` require explicit evidence that product scope, terminals, terminology, acceptance, and non-functional requirements are unchanged.
+8. Verify status transitions and human gates.
+9. Verify traceability from product goals through features, terminals, stories, acceptance criteria, Pages, Review Scenes, prototype elements, UI Mapping rows, UI components, frontend sources, Slices, tasks, tests, release items, and deployment evidence as applicable.
+10. For UI-bearing scope, validate the human tool-selection Gate, mandatory `UX-VS` and `UX-UI` human decisions, production-compatible runnable Prototype, stable Page and Review Scene identities, normalized terminal/trigger/route relations, Review Units, adjustment history, impact propagation, and aligned `product-prototype-reconciliation.yaml`. Validate that Workflow Manager evidence names the same checksummed target used by the Gate, uses its loopback origin and allowlisted review action, and contains no target revision drift; before `UX-VS`, its only content target is the Visual Reference, and afterward it is one exact Prototype revision.
+11. Validate every Prototype Page review receipt as an immutable checksummed YAML record under `.workflow/delivery/reviews/prototype-pages/<revision-id>/`. Reject an invalid or extra field, file-path/identity mismatch, actor, timestamp, receipt checksum, Prototype revision checksum, Page checksum, Scene checksum, or evidence checksum. Derive status from the current revision or its checksum-validated `previous_revision` ancestor chain, nearest ancestor first; reject inheritance from descendants or unrelated revisions. Carry forward only when the selected prior decision is approved and the complete Page checksum is identical; preserve a later changes-requested decision on that ancestor, and derive stale after any evidence change. Require the final Page receipt and approved `UX-UI` Gate decision to reference each other through the same actor, iteration, Prototype revision, and receipt checksum, and reject any later receipt unless a new pending `UX-UI` request exists.
+12. Verify that UI handoff, experience confirmation, architecture validation, test validation, planning, development, and verification all pin the same exact Prototype revision/checksum, source revision/checksum, review-bundle checksum, UI Mapping checksum, normalized catalog checksums, product reconciliation, product impact assessment, experience-change checksum, review/impact checksums, and receipt checksums. Resolve every affected Page, Review Scene, UI component, frontend source, and acceptance criterion through explicit normalized foreign keys. Reject missing or conflicting references. Never infer relationships from file names or row order. Require downstream work to consume only `ready-for-development` changes.
+13. For every UI-bearing code handoff, validate the revision-bound `frontend-change-scope.yaml` checksum and its code root, non-empty frontend roots and extensions, shared component ownership, and file-only route registry ownership with the exact approved candidate-file SHA-256. Cross-check every active UI Mapping and ownership source against those roots and extensions; a declared source that would be skipped invalidates the scope. Run `ai-delivery frontend-guard verify-diff` with the handoff's fixed base and candidate head; require the independent Git diff to have current approved Page receipts and exact UI Mapping or scope coverage, and read changed route registries from the fixed candidate Git object rather than the mutable worktree. Reject Hook-only evidence, unmapped new or removed UI files, unapproved route-registry content, pending/changes-requested/stale Pages, and scope or revision drift.
+14. Before Candidate Assurance can pass a UI-bearing candidate, require successful `ui-acceptance plan` and `ui-acceptance verify` reports bound to the active attempt and immutable candidate checksum. Check exact Page/Scene/viewport coverage, pinned Playwright environment, visual diff counts and evidence, interaction and WCAG 2.2 AA checks, keyboard/focus/touch-target/text-overflow/responsive/recovery results, protocol evidence, Scenario Pack authority, and separate real backend evidence whenever Product Backend Mock rendered a Scene. Candidate checksum drift requires a new `04-implementation` candidate and Candidate Assurance attempt.
 
 ## Output
 
 Report findings first with severity, artifact ID, location, violated rule, evidence, and owning producer. Return one decision: `valid`, `invalid`, or `blocked`. Never rewrite an invalid artifact while acting as validator; route it to the producer.
 
 Read [artifact-contract.md](references/artifact-contract.md) for required metadata, statuses, formats, and handoff sets.
+
+Validate any present `confirmation-summary.yaml` with `confirmation-state.mjs validate` and report its frontier and blocked proposals. This check is read-only and additive; it never mutates the summary or formal state.