ai-delivery-workflow 0.5.1 → 0.7.0

package/skills/ai-delivery-define-product/SKILL.md

@@ -5,6 +5,8 @@ description: Discover and define a product through a guided interview, then prod
 
 # Define Product
 
+Use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` for every business decision, domain term, constraint, risk, and open question. Recompute the frontier after each answer and write confirmed knowledge into the product manual or baseline before Gate A/B.
+
 Turn an initial idea into two human-approved baselines without inventing unresolved business decisions.
 
 ## Artifact Location
@@ -24,7 +26,7 @@ This Skill owns `01-product-shaping`. Discovery, product definition, and prototy
 
 ## Preflight
 
-Read the project state, artifact registry, applicable standards, and existing product baseline. For a change, identify the affected terms, terminals, features, stories, and acceptance criteria before editing. In prototype-reconciliation mode also read the complete adjustment log, requirement change set, formal UI confirmation, exact Prototype revision and checksum, normalized Page and Review Scene catalogs, UI Mapping, and bidirectional product coverage.
+Read the project state, artifact registry, applicable standards, existing product baseline, and the current `confirmation-summary.yaml`. For a change, identify the affected terms, terminals, features, stories, and acceptance criteria before editing. In prototype-reconciliation mode also read the shared `product-impact-assessment.yaml`, complete adjustment log, requirement change set, formal UI confirmation, exact Prototype revision and checksum, normalized Page and Review Scene catalogs, UI Mapping, and bidirectional product coverage. Facts discovered from the repository remain `observed_fact`; only the business sponsor confirms product intent, scope, terminology, priority, risk acceptance, or Gate decisions.
 
 ## Run Discovery
 
@@ -34,6 +36,8 @@ Read the project state, artifact registry, applicable standards, and existing pr
 4. Produce the discovery baseline and run completeness and contradiction checks.
 5. Submit discovery Gate A for human approval. Do not start product definition while Gate A is rejected or incomplete.
 
+After each answer, append a structured confirmation record, recompute the frontier, and persist exactly one idempotent user-owned next action when another decision is required. Before Gate A or Gate B, produce a shared-understanding summary and link every confirmed business decision and domain term to its owning product artifact. Do not save the conversation transcript.
+
 ## Define The Product
 
 1. Define the product specification, capability structure, business flows, user stories, acceptance criteria, non-functional requirements, and business priority.
@@ -59,6 +63,7 @@ Required outputs:
 - `acceptance-criteria.csv`;
 - traceability association CSV files;
 - `product-baseline.yaml` with versions and item-level approval state.
+- `confirmation-summary.yaml` with the current frontier, confirmed/rejected/deferred decisions, authority references, and shared-understanding result.
 
 In prototype-reconciliation mode also produce the terminal requirement change set, bidirectional product coverage, product artifact delta, and `product-prototype-reconciliation.yaml`.
 
@@ -68,12 +73,12 @@ Use the schemas and controlled values in [product-contract.md](references/produc
 
 Run this mode only after the candidate Prototype revision is approved for every visual or interactive Page and Review Scene and all of its adjustments are terminal.
 
-1. Review every row in `requirement-change-set.csv`; classify it as approved, rejected, or requiring clarification. Do not approve a requirement merely because the prototype implements it.
+1. Review the shared `product-impact-assessment.yaml` first. Confirm that every `product-update-required` or `clarification-required` finding has a user-owned question, affected stable IDs, and a return reason. Review every row in `requirement-change-set.csv`; classify it as approved, rejected, or requiring clarification. Do not approve a requirement merely because the prototype implements it.
 2. Verify both directions of `prototype-product-coverage.csv`: every prototype behavior must resolve to an approved feature/story/acceptance criterion, and every visual product behavior must resolve to a prototype element or justified `not-applicable` row.
 3. Apply approved added, modified, retired, or superseded requirements to a new product baseline version. Preserve stable IDs for modifications and retire IDs instead of reusing them.
 4. Re-run Gate B for every changed product artifact and record exact approval evidence. When nothing changes, retain the existing baseline and record an `aligned` no-change decision.
 5. Write `product-prototype-reconciliation.yaml` with the input/output product baseline checksums, prototype/formal-UI checksums, terminal and terminology checks, requirement-change closure, stale artifacts, and required prototype revalidation.
-6. Return rejected prototype behavior to experience for removal. Return an updated baseline to experience, mark the affected Page and Review Scene revisions stale, and require their staged re-approval in a new Prototype revision. Repeat until the receipt is `status: valid`, `decision: aligned`, and every requirement change is terminal.
+6. Return rejected prototype behavior to experience for removal. Return an updated baseline to experience, resolve the shared impact assessment, mark the affected Page and Review Scene revisions stale, and require their staged re-approval in a new Prototype revision. Repeat until the receipt is `status: valid`, `decision: aligned`, every requirement change is terminal, and every product impact assessment is `resolved` or `superseded`.
 
 ## Handoff
 

package/skills/ai-delivery-deploy-production/SKILL.md

@@ -5,6 +5,8 @@ description: Execute R08 production deployment of one human-approved immutable r
 
 # Deploy Production
 
+Production deployment questions use the shared confirmation protocol and the exact release summary. Require explicit `PRODUCTION-APPROVAL`; never infer deployment authorization from a passing candidate.
+
 Execute the approved plan exactly. Do not rebuild, patch, add unlisted items, change configuration ad hoc, or decide that the release succeeded.
 
 ## Artifact Location

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

@@ -5,6 +5,8 @@ description: Design and reconcile a coherent application, technical, data, secur
 
 # Design Architecture
 
+Use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` for architecture decisions, quality-budget exceptions, product-impact findings, and risk acceptance. Link confirmed records to the architecture baseline or Gate before handoff.
+
 Use one skill with `initial` and `reconcile` modes so coupled architecture views remain consistent.
 
 ## Artifact Location
@@ -23,28 +25,31 @@ This Skill shares `02-solution-design` with `$ai-delivery-design-experience`. In
 
 ## Preflight
 
-Read the approved product baseline, business glossary, terminal matrix, feature catalog, applicable standards, and prior architecture decisions. Reject incomplete or inconsistent inputs instead of guessing product scope.
+Read the approved product baseline, business glossary, terminal matrix, feature catalog, applicable standards, prior architecture decisions, the current `confirmation-summary.yaml`, and the configured code repository's `AGENTS.md`, `CODEBASE_GUIDE.md`, and relevant `docs/CODEBASE_INDEX.md` entries. Read [product-impact-assessment-contract.md](../ai-delivery-orchestrate/references/product-impact-assessment-contract.md) before classifying a design discovery. Treat handbook content and confirmation summaries as context/traceability only: architecture artifacts and decisions remain the sole authority for boundaries and dependency rules. Reject missing, stale, malformed, or conflicting references instead of guessing product scope; record a draft remediation when documentation is incomplete.
 
 ## Initial Mode
 
-1. Convert non-functional requirements into measurable quality scenarios and budgets.
+1. Convert non-functional requirements into measurable quality scenarios and budgets. If a new budget, constraint, or tradeoff changes product scope, priority, risk acceptance, terminology, terminal coverage, or acceptance, create `product-impact-assessment.yaml` before continuing.
 2. Define system context, application and component boundaries, terminal implementation strategies, data ownership, authentication and authorization, security controls, deployment topology, observability, and operational constraints.
 3. Select technology stacks with exact supported versions, package and build tools, repository layout, dependency policy, and required commands.
 4. Draft APIs, events, data contracts, migration strategy, test seams, and delivery constraints.
 5. Record only decisions that are costly to reverse and based on real tradeoffs.
-6. Submit major decisions for human approval before experience design proceeds.
+6. Classify each discovery with the shared assessment. `no-impact` and `architecture-only` require evidence; `product-update-required` and `clarification-required` return to `01-product-shaping` and block the architecture handoff until product reconciliation is valid.
+7. Submit major decisions for human approval before experience design proceeds.
 
 Major decisions include platforms, paid services, security or privacy boundaries, hard-to-reverse data or infrastructure choices, material cost/performance/schedule tradeoffs, and deviations from approved product scope.
 
 ## Reconcile Mode
 
-1. Read the experience baseline, `ui-handoff.yaml`, both staged Gate receipts (`UX-VS` and `UX-UI`), aligned `product-prototype-reconciliation.yaml` receipt, experience/requirement change sets, interaction contract, design tokens, framework selection, component-state matrix, page-component map, the exact immutable Prototype revision and checksum, its source and review-bundle checksums, the normalized terminal, Page, Review Scene, trigger-condition, route, and UI Mapping catalogs, review/impact records, traceability, and source confirmation. Verify every exact identity/checksum and require the handoff to be complete and free of stale references. Reject a missing or conflicting reference; never infer a relationship from a file name or catalog order.
+1. Read the experience baseline, `ui-handoff.yaml`, both staged Gate receipts (`UX-VS` and `UX-UI`), the aligned `product-prototype-reconciliation.yaml` receipt, the shared `product-impact-assessment.yaml`, experience/requirement change sets, interaction contract, design tokens, framework selection, component-state matrix, page-component map, the exact immutable Prototype revision and checksum, its source and review-bundle checksums, the normalized terminal, Page, Review Scene, trigger-condition, route, and UI Mapping catalogs, review/impact records, traceability, and source confirmation. Verify every exact identity/checksum and require the handoff to be complete and free of stale references. Reject a missing or conflicting reference; never infer a relationship from a file name or catalog order.
 2. Resolve every affected Page, Review Scene, UI component, frontend source, and acceptance ID through the pinned UI Mapping. Verify that the selected UI framework/version is compatible with the architecture stack and dependency policy, and that every mapped interaction, state, permission, query, upload, real-time behavior, failure mode, responsive rule, and accessibility requirement is technically supported. Use stable change, terminal, Page, Review Scene, prototype-element, UI Mapping, component, frontend-source, and acceptance IDs in findings.
 3. Write one `prototype-architecture-validation.yaml` for the Prototype revision with the UI handoff identity/checksum, Prototype revision and UI Mapping checksums, all consumed artifact versions/checksums, exact architecture baseline version/checksum, implementability decision, affected changes/Pages/Review Scenes/mappings/components/acceptance criteria, issues, and return node. An accepted receipt uses `status: valid`; a `changes-required` receipt uses `status: invalid`. Accept the handoff only when the receipt passes, then advance accepted experience changes from `formal-ui-confirmed` to `architecture-accepted` and `ready-for-development` through the state CLI.
-4. Return product or experience defects to their producer. Do not silently weaken approved behavior or edit the frozen prototype.
+4. Wrap any product-affecting architecture finding in `product-impact-assessment.yaml`. Return `product-update-required` and `clarification-required` to `01-product-shaping`; return experience defects to their producer. Do not silently weaken approved behavior, edit the frozen prototype, or continue with an unresolved assessment.
 5. Finalize APIs, data access, events, component boundaries, test seams, deployment requirements, and implementation constraints.
 6. Reopen human approval only when reconciliation creates or changes a major decision.
 
+For each new architecture decision, append a confirmation record with factual evidence, alternatives, recommendation, user decision, impact, and owning architecture artifact. Ask only frontier decisions that are not answerable from the environment. A confirmed record never substitutes for the architecture Gate.
+
 ## Outputs
 
 Produce one versioned architecture baseline containing:
@@ -61,6 +66,8 @@ Produce one versioned architecture baseline containing:
 - prototype architecture validation receipt in reconcile mode;
 - UI framework/dependency acceptance and exact `ui-handoff.yaml` receipt in reconcile mode;
 - final test seams and component impact map.
+- handbook review evidence: exact code commit, files/sections consulted, stale or missing findings, and maintainer confirmation required for any promoted rule.
+- confirmation summary and decision-to-architecture artifact traceability.
 
 Do not require DDD constructs. Use business terms from the product manual and provide explicit mappings for unavoidable technical names.
 

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

@@ -5,6 +5,8 @@ description: Select prototype and UI tools, define a confirmed visual system, pr
 
 # Design Experience
 
+Use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` for prototype, terminal, interaction, visual-system, and product-impact decisions. A Page review or chat answer is not authoritative until its receipt and owning artifact are linked.
+
 Design complete user experiences for the terminals selected by product and implemented by architecture.
 
 ## Artifact Location
@@ -23,7 +25,7 @@ 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.
 
 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.
 
@@ -39,12 +41,14 @@ Require the current `prototype.yaml`, v2 catalogs, isolated source tree, and Rev
 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

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.
 

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

@@ -5,6 +5,8 @@ description: Validate confirmed prototype testability and define the overall rel
 
 # Design Tests
 
+When test policy, quality budget, exception, or residual-risk choices need confirmation, use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` and link the answer to the test contract. Proposed or deferred records never count as test approval.
+
 Create a durable release strategy once and detailed test inputs just in time for the next slice.
 
 ## Artifact Location
@@ -60,3 +62,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

@@ -5,6 +5,8 @@ description: Orchestrate implementation of one planned vertical slice from an ex
 
 # Develop Iteration
 
+When implementation exposes ambiguity, use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md` and append one record to the owning node summary. A user or external wait is zero-mutation; chat cannot expand the package scope.
+
 Derive technical tasks just in time. Do not predefine frontend, backend, database, or other roles unless the selected slice and architecture require them.
 
 ## Artifact Location
@@ -31,7 +33,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 +42,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 +71,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-evolve-workflow/SKILL.md

@@ -5,6 +5,8 @@ description: Record explicit workflow feedback and objective delivery signals, e
 
 # Evolve The Project Workflow
 
+Workflow improvement proposals use the shared confirmation summary for explicit maintainer acceptance; an observation or AI recommendation never activates an extension by itself.
+
 Use the project Evolution CLI for every feedback, proposal, extension, trial, and decision state change. Never edit `.workflow/evolution/index.yaml` or registered extension state directly.
 
 ## Capture Feedback

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

@@ -5,6 +5,8 @@ description: Execute one architecture-constrained technical work package against
 
 # Execute Technical Work Package
 
+When execution needs a behavior, scope, or risk decision, use `../ai-delivery-orchestrate/references/communication-confirmation-contract.md`, append the question to the owning summary, and wait without modifying source or formal state while ownership is `user` or `external`.
+
 Implement only the assigned package. Do not broaden scope, choose a different stack, approve your own change, or repair unrelated defects.
 
 ## Artifact Location
@@ -23,11 +25,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 +53,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-manage-standards/SKILL.md

@@ -5,6 +5,8 @@ description: Capture, classify, approve, version, resolve, and apply durable pro
 
 # Manage Standards
 
+Record proposed standards, exceptions, and maintainer decisions through the shared confirmation protocol; link confirmed `standard_decision` records to the standards baseline or approval receipt.
+
 Persist durable rules in the repository instead of relying on chat history. Do not silently turn a preference, suggestion, or one-time instruction into a standard.
 
 ## Artifact Location

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

@@ -119,3 +119,7 @@ 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.
+
+All development nodes (`00-bootstrap` through `06-version-closeout`) and release nodes (`R00` through `R10`) inherit this protocol. Each node must load its version-scoped `confirmation-summary.yaml` at preflight, keep one frontier round active, persist user/external waits as zero-mutation states, and write confirmed knowledge into the node's owning artifact before handoff.

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`；不要自动覆盖维护者文档。