ai-delivery-workflow 0.5.0 → 0.6.0

package/skills/ai-delivery-design-architecture/assets/architecture-template/architecture-gate.yaml

@@ -13,3 +13,5 @@ approved_by: null
 approved_at: null
 evidence: []
 standards: []
+product_impact_assessment_ref: PRODUCT-IMPACT-ASSESSMENT-0001@1
+product_impact_assessment_checksum: REPLACE_WITH_SHA256

package/skills/ai-delivery-design-architecture/assets/architecture-template/prototype-architecture-validation.yaml

@@ -11,6 +11,7 @@ input_artifacts:
   prototype_tool_selection: PROTOTYPE-TOOL-SELECTION-0001@1
   prototype_review_decision: PROTOTYPE-REVIEW-DECISION-0001@1
   prototype_impact_assessment: PROTOTYPE-IMPACT-ASSESSMENT-0001@1
+  product_impact_assessment: PRODUCT-IMPACT-ASSESSMENT-0001@1
 standards: []
 ui_handoff_ref: UI-HANDOFF-0001@1
 ui_handoff_checksum: REPLACE_WITH_SHA256
@@ -36,6 +37,7 @@ prototype_review_sessions_checksum: REPLACE_WITH_SHA256
 prototype_review_comments_checksum: REPLACE_WITH_SHA256
 prototype_adjustment_log_checksum: REPLACE_WITH_SHA256
 prototype_impact_assessment_checksum: REPLACE_WITH_SHA256
+product_impact_assessment_checksum: REPLACE_WITH_SHA256
 traceability_checksum: REPLACE_WITH_SHA256
 state_catalog_checksum: REPLACE_WITH_SHA256
 feature_screen_coverage_checksum: REPLACE_WITH_SHA256

package/skills/ai-delivery-design-architecture/references/architecture-contract.md

@@ -23,6 +23,10 @@ Add experience coverage validation, exact UI handoff acceptance, selected framew
 
 Produce one `prototype-architecture-validation.yaml` for the exact Prototype revision. Pin the `ui-handoff.yaml` version/checksum, Prototype revision/checksum, source and review-bundle checksums, UI Mapping checksum, normalized catalog checksums, source confirmation, staged Gate receipts, aligned product reconciliation, framework selection, design tokens, interaction/component contracts, change sets, review/impact checksums, linked coverage, and final architecture baseline. Resolve affected Page, Review Scene, prototype-element, UI Mapping, UI component, frontend-source, and acceptance IDs only from the normalized catalogs. Record decision (`accepted` or `changes-required`), affected identities, dependency/component/contract impacts, quality-budget conflicts, unresolved issues, evidence, and return node. Use `status: valid` only with `accepted`; reject any missing or conflicting identity or a handoff not ready for development. Never infer a relationship from a file name or catalog order. Do not modify experience artifacts.
 
+## Product Impact Return
+
+When architecture discovers a change to product scope, terminal coverage, business rules, terminology, acceptance, priority, risk acceptance, or non-functional requirements, produce the shared `product-impact-assessment.yaml` and return to `01-product-shaping`. A quality budget that only changes implementation limits may be `architecture-only`; the assessment must prove that no product asset changed. An unresolved `product-update-required` or `clarification-required` assessment blocks the architecture handoff.
+
 ## Architecture Decision Test
 
 Record a decision only when it is costly to reverse, surprising without context, and based on a real tradeoff. Mark platform, paid service, security/privacy boundary, irreversible data/infrastructure, material cost or schedule, and product-deviation decisions as human-gated.

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

@@ -23,9 +23,9 @@ This Skill shares `02-solution-design` with `$ai-delivery-design-architecture`.
 
 ## Preflight
 
-Read the approved product baseline, terminal and feature catalogs, initial architecture baseline, major-decision approval receipt or explicit not-required assessment, applicable design standards, and existing experience baseline. Verify all input versions and checksums. Return missing terminal scope or feature behavior to product definition; refuse to prototype from unapproved major architecture decisions.
+Read the approved product baseline, terminal and feature catalogs, initial architecture baseline, major-decision approval receipt or explicit not-required assessment, applicable design standards, existing experience baseline, and the current confirmation summary. Read [product-impact-assessment-contract.md](../ai-delivery-orchestrate/references/product-impact-assessment-contract.md) before recording a change impact. Verify all input versions and checksums. Return missing terminal scope, business terminology, or feature behavior to product definition; refuse to prototype from unapproved major architecture decisions. Record tool, visual-system, framework, and Page decisions in the summary before their controlled Gate.
 
-When `prototype.yaml` has `status: migration-pending-ux-ui` or a `prototype-migration.yaml` exists, apply the Legacy Prototype Migration section of [experience-contract.md](references/experience-contract.md). Treat copied member sources as migration inputs, complete the normalized catalogs and current Review Shell, then freeze and validate a new revision before requesting `UX-UI`; no legacy approval is reusable.
+Require the current `prototype.yaml`, v2 catalogs, isolated source tree, and Review Shell before authoring. A missing current catalog or checksum is a failed preflight; repair the current Prototype package before continuing.
 
 ## Workflow
 
@@ -39,12 +39,14 @@ When `prototype.yaml` has `status: migration-pending-ux-ui` or a `prototype-migr
 8. Build the one production-compatible runnable Prototype in the isolated `prototype/source` tree using the selected framework and architecture runtime. Keep mock data and do not bind production services. When a Review Scene needs an outside protocol, run `ai-delivery mock setup <workspace>` and `ai-delivery mock start <workspace>`, register every mock with explicit External Dependency Mock (`external-dependency`) or Product Backend Mock (`product-backend`) kind, owner, approved contract reference, replacement condition, protocol, operation/channel, and stable scenario identity, then review `ai-delivery mock sync <workspace> --dry-run`. Only after that dry-run validates every named scenario and dispatcher input may `ai-delivery mock sync <workspace>` run. Keep Product Backend Mock entries for unfinished product-owned public contracts in their separate catalog and never misclassify them as external. Export each actual OpenAPI/AsyncAPI definition changed through the managed Microcks UI into `mock-admin-exports/`, then bind its kind, Mock ID, protocol, relative path, and SHA-256 in `mock-admin-export.yaml`; freeze must protocol-validate every mapped scenario against those exported bytes. Production traffic recording, production credentials, and unsanitized personal data are prohibited, and every explicit import requires passed sanitization evidence. Map every active Review Scene exactly once in `mock-scenario-mappings.csv`. Run `ai-delivery mock freeze <workspace> --experience <relative-directory> --scenario-pack mock-scenario-pack-request.yaml --dry-run`, ask the user to approve that exact candidate checksum, then run the same command without `--dry-run` and formally register the immutable Mock Scenario Pack checksum as `artifact_type: mock-scenario-pack`. Only that registered Pack is authoritative for the Prototype revision and later UI Acceptance. A Product Backend Mock may drive a UI scene, but the real backend is not proven and end-to-end acceptance is not satisfied by that mock. Prototype routes reference only the registered Pack's `mock_id` and `scenario_id`, then trigger the contract-defined dispatcher deterministically; do not duplicate response logic inside the Prototype. Maintain one current Review Shell that consumes the server-supplied `review_path` query parameter and renders the matching registered prototype route. Expose every Page and Review Scene through that direct route, and keep production routes limited to real business Pages. Every visible control must work; cover navigation, validation, loading, empty, success, error, permission, disabled, recovery, responsive behavior, and accessibility in `interaction-contract.csv`. Bind prototype routes, production routes, frontend sources, and acceptance IDs once in `ui-mapping.csv`.
 9. Record every adjustment immediately in `prototype-adjustment-log.csv`, including its classification, before/after revision, reason, requirement/change references, and product, architecture, and test impacts. Never overwrite a prior revision. Create or update `experience-change-set.csv`, `experience-change-domains.csv`, and `requirement-change-set.csv` using stable IDs.
 10. Run mandatory Gate `UX-UI`. Validate the exact Prototype revision, start or reuse `ai-delivery manager serve <workspace>`, and give the returned loopback URL plus P12/P13 affected Page and Review Scene IDs to the user. The Review Shell derives each Page as `approved`, `pending-review`, `changes-requested`, or `stale` from checksummed Page review receipts; it shows the changed evidence domains, all owning Review Scenes, and the Page/Scene/revision checksums. The user must operate that exact revision and write `approved` or reason-required `changes-requested` decisions only through the Workflow Manager controlled API. Never let browser code edit YAML, formal state, or receipts directly. Across revisions, consider decisions only from the checksum-validated `previous_revision` ancestor chain, nearest ancestor first; never inherit from a descendant or unrelated revision. Carry forward a Page approval only when that prior decision is approved and the complete Page checksum is identical; a later changes-requested decision on the selected ancestor takes precedence. Label the final pending Page action `Approve Page and complete UX-UI`, and atomically write its Page receipt with the formal `UX-UI` Gate decision. After approval, reject further Page decisions until a new immutable Prototype revision has a new pending `UX-UI` Gate. Record and re-review every adjustment until `formal-ui-confirmation.yaml` reaches candidate approval with no open comments. A content or catalog change requires a new exact revision; the Workflow Manager must reject target revision drift before accepting a decision.
-11. After every affected Page and Review Scene is candidate-approved, aggregate the full adjustment and requirement-change sets and invoke `$ai-delivery-define-product` in prototype-reconciliation mode. Produce complete bidirectional `prototype-product-coverage.csv`. Product owns `product-prototype-reconciliation.yaml`; never silently rewrite product requirements to match the Prototype.
-12. When reconciliation finds a product change, create and approve a new product baseline, mark affected artifacts stale, revise the same Prototype source, rerun the required Gate, and repeat reconciliation. Reject or remove unapproved prototype behavior. Proceed only with `decision: aligned` and every requirement change terminal.
+11. After every affected Page and Review Scene is candidate-approved, aggregate the full adjustment and requirement-change sets and create or update the shared `product-impact-assessment.yaml`. Classify each change as `no-impact`, `architecture-only`, `product-update-required`, or `clarification-required`; invoke `$ai-delivery-define-product` in prototype-reconciliation mode whenever the latter two apply. Produce complete bidirectional `prototype-product-coverage.csv`. Product owns `product-prototype-reconciliation.yaml`; never silently rewrite product requirements to match the Prototype.
+12. When reconciliation finds a product change, create and approve a new product baseline, resolve the shared assessment, mark affected artifacts stale, revise the same Prototype source, rerun the required Gate, and repeat reconciliation. Reject or remove unapproved prototype behavior. Proceed only with `decision: aligned`, every requirement change terminal, and no unresolved product impact assessment.
 13. Derive added, modified, retired, superseded, and unchanged experience rows by comparing stable IDs and checksums with the prior frozen experience baseline. Use phase states `proposed`, `interaction-confirmed`, `visual-confirmed`, `formal-ui-confirmed`, `architecture-accepted`, `ready-for-development`, `included-in-work-package`, `implemented`, and `verified`; use `changes-requested`, `stale`, `blocked`, `retired`, and `superseded` when applicable.
 14. Freeze one immutable `prototype-revision.yaml` for the iteration. Its checksummed review bundle contains the Review Shell, terminal/Page/Review Scene/trigger/route/UI Mapping/Review Unit/Review Unit Page, Component Registration, Data Contract, Component Candidate, component binding, implementation mapping, and Source Inspection Snapshot catalogs, Visual Standard evidence, review evidence, and `frontend-change-scope.yaml`; bind the scope with its own SHA-256 in the revision. Pin the exact source revision and run `ai-delivery prototype-revision validate <workspace> --experience <relative-directory> --revision <relative-yaml>` before registration; never copy or fork the logical Prototype for a new iteration.
 15. Run contract completeness checks and write one source confirmation plus `ui-handoff.yaml` for the exact Prototype revision. Set `development_readiness: ready-for-development` only when `UX-VS`, `UX-UI`, product reconciliation, and revision validation all pass and no blocking or stale requirement/experience change remains.
 
+Treat Prototype Change Requests and human Page decisions as governed decisions, not informal chat. Link their exact receipt/checksum into the confirmation summary; a new requirement or architecture impact returns to the owning node rather than being decided locally.
+
 Tool selection, visual-system/framework approval, formal-UI approval, and final product reconciliation are required decisions for every visual or interactive prototype. Only genuinely non-visual terminals may use justified `not-applicable` results.
 
 ## Outputs
@@ -68,10 +70,10 @@ Tool selection, visual-system/framework approval, formal-UI approval, and final
 - `feature-screen-coverage.csv` mapping feature ID, terminal ID, flow ID, screen ID, and state ID;
 - versioned experience baseline and unresolved technical questions.
 
-Read [experience-contract.md](references/experience-contract.md) for handoff identity and [prototype-management-contract.md](references/prototype-management-contract.md) for tool, terminal, Page, Review Scene, route, UI Mapping, and review rules. Use `assets/experience-template/` for all controlled templates; files explicitly labeled legacy are compatibility inputs, not current-flow outputs.
+Read [experience-contract.md](references/experience-contract.md) for handoff identity and [prototype-management-contract.md](references/prototype-management-contract.md) for tool, terminal, Page, Review Scene, route, UI Mapping, and review rules. Use `assets/experience-template/` for all controlled templates.
 
 ## Handoff
 
 Send the experience baseline, `ui-handoff.yaml`, tool-selection receipt, both experience Gate receipts, product-reconciliation receipt, change sets, interaction/visual/component contracts, exact Prototype revision identity/checksum, source revision, review-bundle checksum, catalog checksums, traceability checksum, and source-confirmation checksum to `$ai-delivery-design-architecture` in reconcile mode. Preserve the same frozen revision for planning and test design; downstream nodes must never edit experience artifacts.
 
-Legacy `prototype-set.yaml` and member manifests are read-only compatibility inputs. A compatibility reader may normalize them in memory when inspecting historical iterations, and the explicit CLI migration may copy their validated bytes into the current isolated source tree. This Skill never creates, updates, or deletes a prototype set, member bundle, member-scoped manifest, closed iteration, archive, legacy Gate, or legacy event.
+Complete when the current Prototype Revision is frozen, validated, approved through `UX-VS` and `UX-UI`, reconciled with product requirements, and handed off with checksums for every source and catalog.

package/skills/ai-delivery-design-experience/assets/experience-template/product-prototype-reconciliation.yaml

@@ -7,6 +7,8 @@ producer_skill: ai-delivery-define-product
 input_product_baseline: PRODUCT-BASELINE-0001@1
 input_prototype_revision: PROTOTYPE-REVISION-0001@1
 input_prototype_revision_checksum: REPLACE_WITH_SHA256
+product_impact_assessment_ref: PRODUCT-IMPACT-ASSESSMENT-0001@1
+product_impact_assessment_checksum: REPLACE_WITH_SHA256
 formal_ui_confirmation_ref: FORMAL-UI-CONFIRMATION-0001@1
 requirement_change_set_ref: requirement-change-set.csv
 requirement_change_set_checksum: REPLACE_WITH_SHA256

package/skills/ai-delivery-design-experience/assets/experience-template/ui-handoff.yaml

@@ -14,14 +14,17 @@ required_gates:
   visual_system_ref: VISUAL-SYSTEM-CONFIRMATION-0001@1
   formal_ui_ref: FORMAL-UI-CONFIRMATION-0001@1
   product_reconciliation_ref: PRODUCT-PROTOTYPE-RECONCILIATION-0001@1
+  product_impact_assessment_ref: PRODUCT-IMPACT-ASSESSMENT-0001@1
 required_gate_checksums:
   visual_system: REPLACE_WITH_SHA256
   formal_ui: REPLACE_WITH_SHA256
   product_reconciliation: REPLACE_WITH_SHA256
+  product_impact_assessment: REPLACE_WITH_SHA256
 required_gate_statuses:
   visual_system: pending
   formal_ui: pending
   product_reconciliation: pending
+  product_impact_assessment: pending
 artifacts:
   ui_mapping_ref: ui-mapping.csv
   ui_mapping_checksum: REPLACE_WITH_SHA256

package/skills/ai-delivery-design-experience/references/experience-contract.md

@@ -18,7 +18,7 @@ Use state types `default`, `loading`, `empty`, `success`, `partial`, `error`, `p
 
 Include task flows, information architecture, page inventory, interaction contract, design-reference selection, runnable HTML Visual Reference, visual direction, framework/component/icon selection, machine-readable design tokens, component states, a production-compatible runnable prototype, responsive behavior, accessibility rules, content rules, change sets, final product reconciliation, and unresolved technical questions.
 
-Do not select new product terminals or change feature behavior. Route those changes to product definition.
+Do not select new product terminals or change feature behavior. Route those changes to product definition through the shared `product-impact-assessment.yaml`; the assessment is required even when the discovery starts as a Prototype adjustment or a new Review Scene.
 
 Apply [prototype-management-contract.md](prototype-management-contract.md) to the project's one logical Prototype. It cannot enter authoring without a valid human tool-selection receipt and no revision can freeze without valid `UX-VS`, `UX-UI`, product-reconciliation, adjustment-closure, and impact-assessment evidence.
 
@@ -26,7 +26,7 @@ Apply [prototype-management-contract.md](prototype-management-contract.md) to th
 
 `UX-VS` accepts exact design-reference selection, Visual Reference HTML/manifest, visual-direction, design-token, framework/component/icon-selection, component registry/configuration, selected components, checksummed local adaptations, component-state, license, upstream-attribution, and complete design-input checksums. Before Gate completion, `ai-delivery visual-standard validate <workspace> --experience <relative-directory>` must pass. Missing or drifted inputs, incomplete checksum coverage, and expired approvals fail closed. `UX-UI` accepts a production-compatible runnable Prototype revision with complete interaction/state evidence, no dead controls, and the selected visual system applied. Product reconciliation runs after all affected Pages and Review Scenes are candidate-approved and before freeze.
 
-`ui-handoff.yaml` is the single downstream readiness interface. It pins the experience baseline, exact Prototype revision, all Gate receipts, interaction contract, tokens, framework selection, component states, UI Mapping, experience/requirement changes, and product coverage. It remains `development_readiness: blocked` until every Gate and `prototype-revision validate` pass, product decision is `aligned`, all requirement changes are terminal, and no referenced artifact is stale.
+`ui-handoff.yaml` is the single downstream readiness interface. It pins the experience baseline, exact Prototype revision, all Gate receipts, interaction contract, tokens, framework selection, component states, UI Mapping, experience/requirement changes, product coverage, and the shared product impact assessment. It remains `development_readiness: blocked` until every Gate and `prototype-revision validate` pass, product decision is `aligned`, all requirement changes are terminal, every impact assessment is resolved or superseded, and no referenced artifact is stale.
 
 Use `experience-change-set.csv` for `added`, `modified`, `retired`, `superseded`, and `unchanged` stable identities. Normalize multiple domains through `experience-change-domains.csv`; allowed domains are `requirement`, `layout`, `navigation`, `interaction`, `state`, `content`, `visual`, `component`, `responsive`, and `accessibility`. Do not infer deltas by visually comparing prototype files.
 
@@ -42,17 +42,7 @@ When Review Scenes depend on protocol simulations, keep External Dependency Mock
 
 Each iteration and every approval, source confirmation, architecture receipt, test receipt, plan, development task, and candidate check pin one exact Prototype revision identity and checksum. Later source work creates a new revision of the same Prototype; it never creates a Prototype copy or member bundle.
 
-Legacy `prototype-set.yaml` and member manifests are accepted only as read-only historical inputs. Compatibility readers may normalize their identities for inspection, verification, rebuild, or explicit migration. Current producers never generate or mutate set/member artifacts.
-
-## Legacy Prototype Migration
-
-`upgrade` installs migration capability and reports `prototype_migration.required_follow_up`; it never applies the Prototype migration. `migrate --dry-run` is the authoritative zero-write plan, and `migrate` applies it only when `can_apply: true`.
-
-For the open iteration, validate set/member identity, manifest/source/catalog SHA-256, contained paths, and stable terminal, Page, route, and file identities. A valid zero-member input is `not-required`. A single member migrates automatically only when every identity, checksum, catalog, and target is unambiguous. Multiple members merge equal stable identities and block on differing definitions until one checksum-bound `human:<identity>` decision selects the canonical member. The one migration decision file always contains both `decisions` and `prototype_decisions` lists.
-
-Apply creates only `.workflow/experience/<iteration-id>/prototype.yaml`, `prototype-migration.yaml`, copied `prototype/source/<member-id>/...` bytes, and a current Review Shell. Preserve legacy set/member/source bytes, closed and archived iterations, Gate files, approvals, and events. The new descriptor uses `prototype_id: PROTOTYPE`, `status: migration-pending-ux-ui`, and `current_revision_ref: null`.
-
-Migration approval is never inherited. Complete the current normalized catalogs and Review Shell, freeze a new immutable revision, pass `prototype-revision validate`, then request a new `UX-UI`. The migration Review Shell is only a navigation aid; Workflow Manager may accept decisions only for the new complete frozen revision, and P17 keeps the migration lineage available for audit.
+The current Prototype package contains one `prototype.yaml`, one source tree, one Review Shell, and the normalized v2 catalogs. Freeze each approved iteration as one immutable `prototype-revision.yaml`, validate it with `ai-delivery prototype-revision validate`, and route all Page decisions through Workflow Manager against that exact revision checksum. A missing catalog, source checksum, or review receipt blocks the flow until the current package is repaired.
 
 `prototype-traceability.csv`:
 

package/skills/ai-delivery-design-experience/references/prototype-management-contract.md

@@ -33,7 +33,7 @@ Keep all terminals in the same logical Prototype. `prototype-terminals.csv` decl
 
 The frozen Review Shell entrypoint must consume Workflow Manager's `review_path` query parameter and render the matching active path from `prototype-routes.csv`. Treat an absent, unknown, retired, or cross-terminal path as an explicit not-found state. Relative CSS, JavaScript, font, and media references must remain runnable from the frozen entrypoint; Manager embeds only that checksummed content in a sandbox and never interprets product behavior.
 
-Legacy canvas/file catalogs are read-only compatibility inputs. When inspecting them, One canvas contains exactly one main-page family and stable identities remain immutable. Current authoring records source structure in the Prototype repository and normalized terminal/route catalogs instead of creating member-scoped canvas or file registries.
+The current Prototype package records source structure in the Prototype repository and normalized terminal/route catalogs. One Review Scene belongs to one stable Page family, and stable identities remain immutable across revisions.
 
 ## Production Frontend Scope
 

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

@@ -60,3 +60,7 @@ Read [test-design-contract.md](references/test-design-contract.md) and use `asse
 ## Handoff
 
 Development receives the exact ready UI handoff, aligned product reconciliation, actionable experience changes, Prototype revision/checksum, UI Mapping checksum, normalized catalog checksums, and affected stable identities with the public contract, validates that all are actionable, and returns missing seams or ambiguous expectations here. Independent verification later derives additional cases from the approved sources and candidate behavior.
+
+## Confirmation Boundary
+
+Read the current confirmation summary and approved product/architecture baselines. Ask only for test-policy, quality-budget, exception, or residual-risk decisions that cannot be established from repository evidence; append each answer and link it to the test contract. Proposed or deferred records are not approvals.

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

@@ -31,7 +31,7 @@ For UI-bearing scope, pin the exact frozen Mock Scenario Pack identity and check
 
 Resolve the only code repository from `.workflow/config/workspace.yaml`. Put source, retained tests, package manifests, and all work branches there; put work-package definitions, task shards, review decisions, and evidence in the workflow repository. Every handoff reference to code must include the configured `repo_id`, exact `code_commit`, optional `code_tag`, `source_path`, and SHA-256.
 
-1. Analyze impacted components, contracts, data, configuration, infrastructure, security, and documentation.
+1. Read the handbook and the affected `CODEBASE_INDEX.md` entries at the exact configured code commit. Analyze impacted components, contracts, data, configuration, infrastructure, security, and documentation.
 2. Produce the smallest dependency graph of technical work packages that can deliver the vertical slice.
 3. Define a capability-based role per package. Combine related capabilities when safe; create specialized roles only when the work requires them.
 4. Resolve the affected Page, Review Scene, UI component, frontend source, and acceptance IDs through the pinned UI Mapping and frontend scope. Declare objective, inputs, relevant `experience_change_id` values, exact Prototype revision, frontend scope, and UI Mapping identities, terminal/Page/Review Scene/prototype-element/component/frontend-source/acceptance IDs, allowed and forbidden modification scope, dependencies, stack and commands, TDD seam, outputs, completion evidence, risks, and rollback considerations.
@@ -40,6 +40,10 @@ Resolve the only code repository from `.workflow/config/workspace.yaml`. Put sou
 7. Assign a stable execution sequence, write the complete technical work package and dependency CSV files, then register every package as a `queued` `$ai-delivery-checkpoint-task` snapshot. Do not execute the first package until the complete derived group is recoverable.
 8. Use `$ai-delivery-manage-git` to create an isolated worktree and `work/<iteration-id>/<task-id>-<slug>` branch for every package.
 
+For every package, record `handbook_read_commit`, consulted paths, and an explicit `documentation_update: required|not-required` decision. A new/moved directory or entrypoint, dependency-direction change, test relocation, generated-file boundary, or high-risk rule change requires an index/guide update in the same change or a documented owner handoff. The handbook never expands the package's allowed modification scope.
+
+When implementation reveals a behavioral, scope, architecture, or risk ambiguity, stop and append one confirmation record to the owning node. Do not widen a package from chat; require a scope amend or upstream decision and preserve `next_action_owner: user|external` as a zero-mutation wait.
+
 ## Execute And Converge
 
 1. Invoke `$ai-delivery-execute-work-package` for each ready package. For every production UI path, require `ai-delivery frontend-guard check-file <workspace> --path <path>` immediately before its first write; missing current Prototype approval or UI Mapping coverage stops the package.
@@ -65,6 +69,7 @@ Require TDD for business behavior, defect fixes, and contracts. Allow documented
 - independent review results and resolutions;
 - slice traceability and known limitations;
 - buildable candidate commit and `candidate-manifest.yaml`, with exact Prototype revision, UI Mapping, handoff, reconciliation, and task-traceability checksums for every UI-bearing candidate.
+- codebase handbook/index update or a signed no-change assessment, with path existence, duplicate-entry, link, status, source-commit, and sensitive-content validation results.
 
 Read [development-contract.md](references/development-contract.md) and use `assets/development-template/` for traceability and candidate files.
 

package/skills/ai-delivery-develop-iteration/assets/development-template/candidate-manifest.yaml

@@ -21,6 +21,8 @@ ui_handoff_ref: UI-HANDOFF-0001@1
 ui_handoff_checksum: REPLACE_WITH_SHA256
 product_prototype_reconciliation_ref: PRODUCT-PROTOTYPE-RECONCILIATION-0001@1
 product_prototype_reconciliation_checksum: REPLACE_WITH_SHA256
+product_impact_assessment_ref: PRODUCT-IMPACT-ASSESSMENT-0001@1
+product_impact_assessment_checksum: REPLACE_WITH_SHA256
 prototype_revision_ref: PROTOTYPE-REVISION-0001@1
 prototype_revision_checksum: REPLACE_WITH_SHA256
 prototype_source_revision: REPLACE_WITH_IMMUTABLE_SOURCE_REVISION

package/skills/ai-delivery-execute-work-package/SKILL.md

@@ -23,11 +23,13 @@ This Skill executes implementation and approved repair phases for a stable logic
 
 ## Preflight
 
-1. Read the work package, source baselines, applicable standards, confirmed test seam, repository instructions, and exact UI handoff, `product-prototype-reconciliation.yaml`, experience-change mapping, Prototype revision/checksum, frontend scope checksum, UI Mapping checksum, normalized catalog and review/impact checksums, and terminal/Page/Review Scene/prototype-element/UI component/frontend-source/acceptance mappings when the package is UI-bearing. Require every mapped change to be `ready-for-development` and its action to be one of `create|update|remove|migrate|no-code`.
+1. Read the work package, source baselines, applicable standards, repository instructions, `CODEBASE_GUIDE.md`, and affected `docs/CODEBASE_INDEX.md` entries at the exact code commit, plus the exact UI handoff, `product-prototype-reconciliation.yaml`, experience-change mapping, Prototype revision/checksum, frontend scope checksum, UI Mapping checksum, normalized catalog and review/impact checksums, and terminal/Page/Review Scene/prototype-element/UI component/frontend-source/acceptance mappings when the package is UI-bearing. Require every mapped change to be `ready-for-development` and its action to be one of `create|update|remove|migrate|no-code`.
 2. Verify the current branch and worktree with `$ai-delivery-manage-git`.
 3. Inspect the current code and tests before planning edits.
 4. Stop on missing dependencies, missing or conflicting Prototype revision or UI Mapping references, overlapping ownership, ambiguous acceptance behavior, or an infeasible architecture. Never infer relationships from file names or row order. Return evidence to the orchestrator.
 
+Read the confirmation summary for this iteration. Treat new user requirements, behavior interpretations, technical exceptions, and risk acceptance as records owned by the relevant upstream node; do not silently convert them into implementation decisions.
+
 ## TDD Loop
 
 For one vertical behavior at a time:
@@ -49,7 +51,7 @@ Perform cleanup or refactoring only from a Green checkpoint and expose it to ind
 
 - Run architecture-specified format, lint, type, build, test, migration, and security commands.
 - Run `ai-delivery frontend-guard verify-diff <workspace> --base <fixed-base> --head <candidate-head>` for a UI-bearing package and retain the independent Git diff report; local Hook success is not evidence.
-- Update task-to-experience-change traceability and advance implemented rows through the state CLI; update technical documentation, configuration catalogs, and migration/rollback notes when affected.
+- Update task-to-experience-change traceability and advance implemented rows through the state CLI; update technical documentation, configuration catalogs, and migration/rollback notes when affected. Validate handbook/index paths and record the required/no-change decision before handoff.
 - Record deviations and TDD exceptions explicitly.
 - Commit only files in the allowed scope and produce a review packet with commands and evidence.
 

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

@@ -41,17 +41,15 @@ Require every workflow document to be written under project `.workflow/`. Use `.
 
 ## Formal State
 
-The installed producer route is `development-seven-node`: `00-bootstrap -> 01-product-shaping -> 02-solution-design -> 03-delivery-readiness -> 04-implementation -> 05-candidate-assurance -> 06-version-closeout`. Producer Skills and installed guidance use only these development node IDs. `development-legacy-13` is read-only compatibility: inspect, verify, rebuild, and explicit migration may consume historical state, while every new legacy task, artifact, transition, candidate, closeout, or Gate write is rejected. Release nodes `R00-release-request` through `R10-release-archive` remain writable.
-
-When Bootstrap reports legacy compatibility or a premature archive, use the packaged top-level CLI before normal orchestration. Run `ai-delivery migrate <project> --dry-run` and require a reviewed report with schemas, semantic task groups, ambiguities, conflicts, verified anchors, and exact file changes. A legacy root migration copies workflow material into `.workflow/`; flat task shards gain explicit attempts without changing their lifecycle status or scope. Resolve every ambiguity through a source-checksum-bound `--decisions` document with a `human:` actor and rationale, then rerun dry-run. Apply migration only when `can_apply` is true; its manifest and backups must preserve source bytes, task lifecycle facts, scope, formal views, and legacy event bytes. Resolve an incorrect archive only through `ai-delivery repair <project> --invalidate-archive <iteration-id>` with an explicit human actor, reason, RCA evidence, and recovery evidence. The resulting forward transaction invalidates current eligibility while the original archive remains byte-identical. Use rollback only before any post-migration schema 2 transaction or migrated-byte drift; afterward use forward repair. Compaction is never part of migration: run `ai-delivery compact <project> --dry-run` only after a trusted anchor exists, review its exact coverage and byte report, and apply only on explicit operator intent.
+The installed producer route is `development-seven-node`: `00-bootstrap -> 01-product-shaping -> 02-solution-design -> 03-delivery-readiness -> 04-implementation -> 05-candidate-assurance -> 06-version-closeout`. Release nodes `R00-release-request` through `R10-release-archive` remain writable. New work, state, artifacts, transitions, candidates, closeouts, and Gates use only these current node IDs.
 
 1. Use `node .workflow/tools/state/state.mjs inspect` to read schema 2 formal state: independent `development_state` and `release_state` scopes, the top-level workflow audit revision, and the artifact-registry revision.
-2. Keep `draft` and `review-draft` files mutable and outside the formal registry. Register only immutable semantic revisions such as `submitted`, `rejected`, `approved`, `frozen`, or `failed`; every later decision uses a new artifact ID and `--supersedes`. `artifact status` exists only to migrate a legacy registered working draft once and must not mutate a formal revision.
+2. Keep `draft` and `review-draft` files mutable and outside the formal registry. Register only immutable semantic revisions such as `submitted`, `rejected`, `approved`, `frozen`, or `failed`; every later decision uses a new artifact ID and `--supersedes`.
 3. Start development with `iteration-started`; start release only after explicit user intent with `release-started`. Record node, candidate, closeout, and archive changes with `transition`. Record human or contract Gates with `gate request` and `gate decide`.
 4. At Delivery Readiness, run `scope freeze` to enable `scope_contract_version: 1` and bind approved Slices, requirements, acceptance, tasks, and artifacts. Afterward, only a human-approved `scope amend` may change scope. Use `scope warn` for a budget overrun; it must remain `warn-only` with `reslice_performed: false` and must not automatically replan or reslice.
-5. Read `inspect.derived_node_states` instead of assigning formal node status from narration. The projection uses task facts and blocking findings, Gates, artifacts, candidate identity, the current scope manifest, and completion receipts. A governed node may complete only from `ready-to-complete`; completion writes a receipt bound to those facts. Historical scopes without `scope_contract_version` retain legacy compatibility.
-6. Pass `artifact_registry.revision` through `--expected-revision` for artifact mutations. For scope, transition, and Gate mutations, pass the owning `development_state.revision` or `release_state.revision` through `--expected-scope-revision`; the top-level workflow revision form remains compatibility-only. A transition or Gate that consumes evidence records an artifact handoff in the same transaction and advances the artifact-registry revision, so inspect again before the next artifact mutation. On a conflict, inspect again and reconcile; never retry blindly.
-7. Run routine `verify` before handoff, node completion, and after recovery. It validates current formal views without traversing historical shards or decompressing archives. At ordinary task safe points, run `snapshot create --reason configured-interval`; the command is a no-op until the configured event interval is reached. Run `verify --history --since-anchor` after an anchor exists. `artifact compact` and `artifact prune` default to zero-write plans. Compact preserves original legacy shards in a checksummed gzip bundle and removes loose files only after full replay reproduces the anchored registry checksum; afterward `verify --history` reports `compacted-history`. Only explicit `artifact prune --apply` may replace covered shards with a retention receipt; afterward verification reports `retained-history` and does not claim deleted bytes were re-audited. Let the CLI enforce graph prerequisites, successful completion evidence, current-attempt mandatory Gates, and scope identity. Release nodes independently require routine verification at every release handoff. Stop on checksum, schema, audit, identity, or state-invariant failure.
+5. Read `inspect.derived_node_states` instead of assigning formal node status from narration. The projection uses task facts and blocking findings, Gates, artifacts, candidate identity, the current scope manifest, and completion receipts. A governed node may complete only from `ready-to-complete`; completion writes a receipt bound to those facts.
+6. Pass `artifact_registry.revision` through `--expected-revision` for artifact mutations. For scope, transition, and Gate mutations, pass the owning `development_state.revision` or `release_state.revision` through `--expected-scope-revision`. A transition or Gate that consumes evidence records an artifact handoff in the same transaction and advances the artifact-registry revision, so inspect again before the next artifact mutation. On a conflict, inspect again and reconcile; never retry blindly.
+7. Run routine `verify` before handoff, node completion, and after recovery. It validates current formal views and their recorded history. At ordinary task safe points, run `snapshot create --reason configured-interval`; the command is a no-op until the configured event interval is reached. Run `verify --history --since-anchor` after an anchor exists. `artifact prune` defaults to a zero-write plan; only explicit `artifact prune --apply` may replace covered shards with a retention receipt, after which verification reports `retained-history` and does not claim deleted bytes were re-audited. Let the CLI enforce graph prerequisites, successful completion evidence, current-attempt mandatory Gates, and scope identity. Release nodes independently require routine verification at every release handoff. Stop on checksum, schema, audit, identity, or state-invariant failure.
 8. Never directly edit controlled formal state, shared task/checkpoint shards, or runtime task state. Treat global workflow and artifact indexes as deterministic views over authoritative shards where available. If either state script fails, repair the input or script problem rather than bypassing it.
 9. When the user clearly expresses a workflow improvement, invoke `$ai-delivery-evolve-workflow feedback record` and report the feedback ID. Do not save ordinary discussion, full conversation text, secrets, or AI reasoning. Evaluate pending evidence only after a task, version closeout, or explicit evolution review.
 
@@ -121,3 +119,5 @@ For status requests, show the current iteration, active and blocked development/
 
 Read [workflow-model.md](references/workflow-model.md) for the state graph, gate rules, and artifact lifecycle.
 Read [formal-state-contract.md](references/formal-state-contract.md) before mutating formal state.
+Read [codebase-document-contract.md](references/codebase-document-contract.md) when creating, reviewing, or locating the code repository's `AGENTS.md`, `CODEBASE_GUIDE.md`, or `docs/CODEBASE_INDEX.md`.
+Read [communication-confirmation-contract.md](references/communication-confirmation-contract.md) when a node asks for, records, resumes, or audits a user/external decision. Validate summaries with `scripts/confirmation-state.mjs`; this index never replaces the owning product, architecture, standards, task, Gate, or formal-state artifact.

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

@@ -0,0 +1,14 @@
+# 代码仓库 AI 工作入口
+
+这是独立代码 Git 仓库的 Agent 入口。详细的项目背景、工程规范、模块地图和维护责任见 [`CODEBASE_GUIDE.md`](CODEBASE_GUIDE.md)；目录和关键文件定位见 [`docs/CODEBASE_INDEX.md`](docs/CODEBASE_INDEX.md)。
+
+开始源码定位、影响分析或代码修改前：
+
+1. 读取本文件；
+2. 读取 `CODEBASE_GUIDE.md` 中与当前变更相关的章节；
+3. 从 `docs/CODEBASE_INDEX.md` 读取目标目录或文件条目；
+4. 回到实际源码、测试和当前 Git 状态核对，不把索引当作源码事实的替代品。
+
+工程分层、测试位置、命名和高风险路径以 `CODEBASE_GUIDE.md` 及其引用的批准决策为准。任务允许文件范围、正式工作流 Gate 和当前测试契约优先于本文件中的导航提示。
+
+如果文档与源码、正式架构或批准规范冲突，标记冲突并暂停依赖该段说明；不要猜测、扩大修改范围或覆盖项目文档。

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

@@ -0,0 +1,124 @@
+# <项目名称> 代码库工程说明书
+
+> 本说明书面向代码仓库管理者、贡献者和需要安全修改源码的 Agent。
+> 目录与关键文件导航见 [`docs/CODEBASE_INDEX.md`](docs/CODEBASE_INDEX.md)。
+
+| 项目 | 内容 |
+| --- | --- |
+| 项目状态 | `<active | maintenance | archived>` |
+| 代码仓库身份 | `<repo_id>` |
+| 对应代码提交 | `<commit-or-tag>` |
+| 维护责任 | `<team-or-role>` |
+| 最后核对 | `<YYYY-MM-DD>` |
+| 正式依据 | `<architecture / standards / task references>` |
+
+## 1. 项目概览
+
+### 解决什么问题
+
+<!-- 用一至三段说明项目目标、边界和不负责的事情。 -->
+
+### 用户和运行边界
+
+<!-- 说明主要用户、支持的终端/环境、外部依赖和数据边界。 -->
+
+### 维护责任
+
+<!-- 写明代码所有者、审查责任、值班/运维入口和文档维护责任。 -->
+
+## 2. 快速开始
+
+| 目的 | 命令 | 验证结果 |
+| --- | --- | --- |
+| 安装依赖 | `<command>` | `<expected result>` |
+| 启动开发环境 | `<command>` | `<url/health signal>` |
+| 运行单元/集成测试 | `<command>` | `<pass condition>` |
+| 运行端到端测试 | `<command>` | `<pass condition>` |
+| Lint/类型检查 | `<command>` | `<pass condition>` |
+| 构建 | `<command>` | `<artifact or output>` |
+
+命令必须与仓库配置或最近一次验证记录一致；不要在这里复制完整 `package.json` 或 CI 文件。
+
+## 3. 仓库地图
+
+| 路径 | 职责 | 入口/关联测试 | 风险 |
+| --- | --- | --- | --- |
+| `<path>` | `<purpose>` | `<entrypoints and tests>` | `<low/medium/high>` |
+
+更详细的模块、关键文件、入口和测试定位见 [`docs/CODEBASE_INDEX.md`](docs/CODEBASE_INDEX.md)。
+
+## 4. 工程分层
+
+### 分层图
+
+```text
+<presentation / transport>
+        |
+<application / use cases>
+        |
+<domain>
+        |
+<infrastructure / adapters>
+```
+
+### 依赖方向
+
+- `<layer>` 可以依赖 `<layer>`，原因是 `<reason>`。
+- `<layer>` 不直接依赖 `<layer>`；应通过 `<interface/adapter>`。
+- 跨模块调用只能通过 `<public interface/event>`。
+
+正式架构决策：`<path-or-artifact-id>`。
+
+## 5. 工程约定
+
+| 主题 | 约定 | 示例/验证 |
+| --- | --- | --- |
+| 目录和文件命名 | `<rule>` | `<example>` |
+| 类型、函数和接口命名 | `<rule>` | `<example>` |
+| 测试放置 | `<rule>` | `<test path/command>` |
+| 错误处理 | `<rule>` | `<error boundary>` |
+| 日志与可观测性 | `<rule>` | `<event/field>` |
+| 配置和密钥 | `<rule>` | `<safe source>` |
+| 权限和敏感数据 | `<rule>` | `<required check>` |
+| 数据库迁移 | `<rule>` | `<rollback/compatibility check>` |
+| 生成文件 | `<rule>` | `<generator command>` |
+
+每条约定都应说明适用范围、原因和验证方式；正式规范引用放在本节末尾。
+
+## 6. 变更工作流
+
+1. 从 `.workflow/config/workspace.yaml` 解析唯一代码仓库，并确认当前分支和工作区状态。
+2. 读取本说明书相关章节和索引条目，确定入口、依赖、测试和风险。
+3. 读取任务允许文件范围、正式架构/规范和公开测试契约。
+4. 先建立或运行会失败的测试，再实施最小变更。
+5. 运行工作包测试和必要回归，记录实际命令与结果。
+6. 如果目录、入口、分层、测试位置或高风险规则变化，更新索引并重新核对引用。
+7. 将变更交给独立审查；文档冲突或不确定性进入人工确认，而不是靠猜测推进。
+
+## 7. 风险和保护边界
+
+| 路径/区域 | 风险 | 修改前置条件 | 回滚或验证 |
+| --- | --- | --- | --- |
+| `<path>` | `<risk>` | `<approval/input>` | `<check>` |
+
+生成文件通过生成命令更新；外部维护目录遵循其所有者流程；敏感配置只从受控环境注入。任务范围和正式 Gate 对本节导航提示具有优先权。
+
+## 8. 文档维护
+
+### 更新触发器
+
+- 新增、删除或移动顶层目录、业务模块、入口或高风险配置；
+- 改变依赖方向、测试位置、生成流程、部署入口或安全边界；
+- 架构决策、批准规范、维护责任或关键验证命令变化。
+
+### 维护记录
+
+| 字段 | 值 |
+| --- | --- |
+| `source_commit` | `<commit>` |
+| `last_reviewed` | `<YYYY-MM-DD>` |
+| `status` | `<observed | approved | stale>` |
+| `owner` | `<team-or-role>` |
+| `references` | `<architecture / standards / tasks>` |
+
+发现路径失效、提交漂移或与正式资料冲突时，先标记 `stale`，再由维护者或对应工作流任务修订。`init` 和 `upgrade` 不覆盖本文件。

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: []