create-agdf 0.14.4 → 0.20.0

package/generated/plugins/copilot/agdf/skills/contracts/modes.md

@@ -0,0 +1,195 @@
+# AGDF Runtime Contract — Modes
+
+## Mode Selection
+
+| Mode | Default | Escalate When |
+|---|---|---|
+| Quick Task Mode | positively activated narrow delivery work such as bounded debugging or a local fix without new product semantics | a new user capability, architecture/policy/persistence impact, formal artefacts, or approvals are involved |
+| Structured Delivery Mode | formal delivery runs, gate-relevant work, release-critical changes | always use gate discipline, internal reviews, and OR |
+
+Request Activation precedes Mode Selection. Ordinary assessment, explanation, comparison,
+recommendation, review, diagnosis, hypothetical advice and AGDF-as-topic discussion remain ordinary
+read-only handling and are not Quick Tasks. Quick Task is a downstream process choice for an actual
+delivery effect or explicit AGDF operation; it is never an activation fallback.
+
+Quick Task Mode must not become ritual gate overhead. It lightens artefact depth, never activation:
+a positively activated small fix still closes with the Quick Task Output below.
+Structured Delivery must not bypass missing approvals.
+New product semantics, functional change, user-visible behaviour, policy, persistence, architecture or release-critical work requires a durable UR in `.agdf/control/` or a linked authoritative repository SoT before later artefacts or implementation.
+UR, PRD, SD, TP and QA report approvals require durable artefacts or linked authoritative repository SoT entries before the next gate can open.
+
+## Quick Task Output
+
+Quick Tasks are intentionally lightweight, but they must not become invisible.
+Use this compact output shape when no formal gate artefact is required:
+
+- `result`: what changed or was concluded
+- `evidence`: files, commands, observations, or reasoning that support the result
+- `risk`: remaining risk or `none`
+- `next_step`: the single next useful action or `none`
+
+Do not add a separate `Quality outlook` line for pure Quick Tasks unless the task became a relevant run.
+
+### Quick Task and Compact Delivery
+
+Use **Quick Task** only after positive Request Activation for bounded debugging, operational work and
+eligible narrow fixes that introduce no new product semantics or formal artefacts. Read-only
+questions, reviews and diagnosis without a requested delivery effect remain outside AGDF. When an
+approved UR is followed by a Brownfield Review that selects the persisted `quick_task` mode, use
+**Compact Delivery** as the human-facing label. The stored and JSON value remains `quick_task`;
+Compact Delivery is not a new mode or approval gate.
+
+Brownfield Review owns the Mode/Slice selection. A completed review records its decision, scope
+reason, evidence and required next depth in the same internal operation. `Mode/Slice Decision` remains
+only a fail-closed recovery step for incomplete or legacy records and is not a normal second user
+decision.
+
+### Structured Depth Decision
+
+This section is the sole normative owner for choosing between `structured_slice` and
+`structured_delivery`. Apply it only after an approved durable UR, a Brownfield Review of the
+existing-system context, and unchanged evaluation of Quick Task/Compact Delivery and Verified
+Change. A compact path must be ineligible or explicitly escalated, and the decisive depth facts must
+be durably evidenced before a positive structured decision is recorded.
+
+Choose `structured_delivery` when any one evidenced full-depth trigger applies:
+
+1. **Authority, policy or security** — a trust or authority boundary, permission, security,
+   compliance or normative policy changes, or independent decision owners require coordinated
+   approval.
+2. **Architecture or runtime** — execution, orchestration, durable execution, concurrency, failure
+   or recovery boundaries change beyond a local slice.
+3. **Persistence, data or migration** — persistent schema or meaning changes, data migration,
+   irreversible state transition, coordinated cutover, an extended compatibility window or
+   non-local rollback is required.
+4. **External or public contract** — an external API, public CLI behavior, protocol, file format or
+   compatibility-sensitive integration contract changes, including independent consumer
+   coordination or versioning.
+5. **Release, deployment or cross-host** — the work needs its own rollout, deployment, rollback,
+   feature-flag or release plan, or coordinated activation across hosts, products or operational
+   boundaries.
+6. **Unbounded consumer or owner coordination** — the outcome cannot be delivered as an
+   independently acceptable and reversible slice, or consumers or owners require a shared cutover
+   or compatibility window.
+
+A single trigger is decisive because of its effect, never because of a numeric count.
+
+Choose `structured_slice` only when `depth_facts_status` is `complete`, no full-depth trigger is
+evidenced, and all seven bounded-slice checks are positively evidenced as `pass`:
+
+| Check ID | Required evidence |
+|---|---|
+| `coherent_outcome` | One coherent user or product outcome has a clear acceptance boundary. |
+| `authority_boundary` | Authority and source of truth are known and no new trust, policy, permission or security boundary is introduced. |
+| `owner_consumer_coordination` | Owners and consumers are identified and coordination stays inside the slice without a shared external cutover. |
+| `full_depth_impacts_absent` | Architecture, runtime, persistence, data, external API, public CLI, release and cross-host effects are evidenced as not full-depth relevant. |
+| `migration_propagation_bounded` | Migration and propagation are bounded, compatible, testable and locally reversible. |
+| `failure_recovery_local` | Failure, recovery and rollback remain controllable inside the slice. |
+| `independently_acceptable` | The slice has independent acceptance signals and hides no unknown later work as a prerequisite. |
+
+Multiple files, owners, consumers or derived paths do not fail these checks by themselves. File,
+owner, consumer, task or derived-path counts are not a decision proxy and must never be used as a
+threshold for either structured mode.
+
+If a decisive fact is missing or conflicting and no evidenced full-depth trigger already supports
+`structured_delivery`, the product-language result is `depth_unresolved`. This is not a persisted
+mode. Persist the existing Mode/Slice value `block`, use `depth_facts_missing` or
+`depth_facts_conflicting`, name the affected facts and evidence owner where known, link the
+Brownfield Review, forbid later artefacts and implementation, and provide a precise next action for
+evidence completion and Brownfield/Mode-Slice re-evaluation. Unknown facts must not default to
+`structured_delivery`.
+
+Positive decisions persist the existing `structured_slice | structured_delivery` value, required
+next gate, a `scope_reason` containing the primary reason code and decisive rationale plus the
+rejected alternative, and evidence linking the complete Structured Depth Evidence. Re-evaluate
+before continuing whenever scope growth reveals a new full-depth trigger.
+
+Normalized reason codes are audit and rationale categories, not new modes or gates:
+
+- `bounded_structured_slice`
+- `authority_policy_security_depth`
+- `architecture_runtime_depth`
+- `persistence_migration_depth`
+- `external_contract_depth`
+- `release_cross_host_depth`
+- `unbounded_consumer_coordination`
+- `depth_facts_missing`
+- `depth_facts_conflicting`
+
+Structured Slice and Structured Delivery use the same existing gate and approval sequence. Their
+difference is artefact depth: Slice artefacts cover only the coherent bounded outcome and its owners,
+contracts, propagation, recovery, tasks and tests; Full Delivery covers every affected authority,
+architecture, runtime, consumer, migration, operational and release boundary.
+
+Historical or deterministic benchmark observations are non-authorizing evidence. They do not define
+this policy, retroactively regrade historical runs or prove live-host behavior. A future benchmark
+may apply this policy only with complete, versioned neutral depth facts.
+
+### Verified Change
+
+`verified_change` is a compact, fail-closed path for a bounded user-visible change with one canonical owner and deterministic proof. It is neither a prose exception nor a new user approval gate.
+
+After `Approval: UR`, Brownfield Review may select `verified_change` only when a durable `VERIFIED_CHANGE.md` record can prove all of the following before implementation:
+
+The existing gate-check/evaluator compact-record owner receives the bound absolute plugin-owned
+`template_path` for `VERIFIED_CHANGE.md`. It must not create another skill, route or template lookup,
+and it must not fall back to repository scaffold copies when the plugin template is unavailable.
+
+1. exactly one repository-relative canonical owner and bounded source/derived paths;
+2. no gate, permission, security, persistence, architecture, external API, CLI or release behavior impact;
+3. deterministic propagation when derived paths exist, plus at least one deterministic validation command;
+4. a full baseline commit plus tracked and untracked worktree baseline paths captured before eligibility, with no candidate path already dirty; and
+5. an explicit `structured_slice` or `structured_delivery` escalation target.
+
+The record is the compact Brownfield selection, eligibility, execution and mini-closeout artefact. The selected run may link the same normalized record path as Brownfield Review, Verified Change and OR only in `verified_change` mode and only with lifecycle-consistent role states; separate Brownfield and OR files remain supported. Permitted control paths derive only from recognized, explicitly linked artefacts beneath the selected run's own artefact directory.
+
+A missing, failed, unknown or ambiguous field/check must fail closed: mark the record `escalated` and continue at its declared structured target. Unrelated paths already dirty at baseline remain isolated; newly introduced unlisted paths invalidate the compact path. An executed record requires a machine-readable exact changed-path snapshot with passing scope status, passing validation evidence and, where applicable, passing propagation evidence. Active runs compare that snapshot with the current post-baseline worktree. Completed executed runs validate the persisted snapshot and record evidence without being retroactively invalidated by later unrelated live-worktree changes.
+
+### Non-Normative Trivial Change Boundary
+
+A `quick_task` whose entire diff stays fully outside all of the following paths may close using only
+the compact output shape above, and must not create, rewrite or expand any selected canonical
+`RUN_STATE.md` core
+sections (Run Meta, Objective, Current Control State, Source And Scope State, Run Status Card,
+Approvals, Artefacts, Mode/Slice Decision, Artefact Chain, Evidence, Missing Evidence, Risks, Context
+Graph Impact, Knowledge Persistence Decision, Closeout):
+
+- `plugins/agdf/skills/**`
+- `plugins/agdf/control/templates/**`
+- `plugins/agdf/meta/**`
+- `packages/cli/lib/**`
+- `packages/cli/bin/**`
+- any other executable code file, in any language, anywhere in the repository
+
+A `MASTER_BACKLOG.md` entry is required only when the change is otherwise a "Relevant Run" below. A
+change that is not clearly and fully outside every listed path fails closed to the existing, unchanged
+ceremony — ambiguity is never read as permission for the lighter path.
+
+#### Narrow Code-Fix Criterion
+
+A change that touches one of the otherwise-excluded code paths above may still close with only the
+compact Quick Task Output shape — Code Review remains mandatory regardless — when **all** of the
+following hold. Any single condition failing, or any ambiguity about whether a condition holds, keeps
+the full existing ceremony unchanged:
+
+1. The diff is confined to a single function, or a function together with its direct,
+   necessarily-coupled caller, in exactly one file.
+2. A new or updated automated regression test exercises the fixed behavior and passes.
+3. No PRD, SD, TP, gate name, exact approval formula, or documented CLI flag/output-schema field is
+   added, removed, or changed — only internal correctness of already-approved behavior.
+4. `doctor` (or the locally available equivalent) and the directly affected existing test suite both
+   pass unchanged in shape after the fix, with no assertion skipped or weakened beyond what the fix
+   itself introduces.
+
+
+## Bug Lightweight Track
+
+For narrow defect work, a repository may use a lightweight bug scope instead of the full UR/PRD/SD/TP chain when all of the following are true:
+
+- the defect is tied to a concrete symptom or ticket
+- the expected behavior is clear enough to test
+- no new product semantics, architecture, policy, persistence or cross-owner decision is introduced
+- a durable bug artefact or linked authoritative issue records reproduction, actual behavior, expected behavior, fix boundary, open questions and evidence plan
+
+The Bug Lightweight Track does not remove QA, OR, evidence, Brownfield fit or exact approvals required by the target repository.
+If the bug grows beyond the stated boundary, escalate to normal AGDF gate flow.

package/generated/plugins/copilot/agdf/skills/contracts/prd-definition.md

@@ -0,0 +1,130 @@
+# AGDF Runtime Contract — PRD Definition
+
+Use only a bound `skill_continuation` with `phase: prd_definition`. This contract owns semantic
+product drafting and clarification; it creates no gate, writer, persistence or approval authority.
+
+## Binding and sources
+
+Dispatch prd-definition before direct work. An unbound invocation uses the existing
+resolve_delivery_run candidate inventory, matching the original request to approved UR scope,
+then gate-check resume intake with run_id and expected_revision_id. Never select AGDF_RUN_ID,
+invent a replacement run/UR or use discovery, skill selection or cwd as editing intent.
+
+Use the returned governance_target, run_id, revision_id, contained artifact_path, absolute
+plugin-owned template_path and exact sources. The installed, version-matched plugin is the sole
+authoring-template authority. Repository `.agdf/control/templates/` copies are derived scaffold
+references and never override template_path. If template_path is unavailable or unsafe, stop
+without writing or falling back and route the explicit plugin repair/reinstall recovery.
+Read the approved UR, completed Brownfield Review/Mode-Slice result and required ready UX Intent
+Definition, original request and confirmed answers. Invalid/stale/foreign/approved bindings,
+missing prerequisites, source proof or integrity blockers require fresh canonical control.
+The approved UR is the primary derivation source; analyses are subordinate inputs.
+
+## Draft the product
+
+Use the existing PRD format, not a new template store: draft/open metadata with named Owner and
+`Traceability contract: criteria-chain-v1`; Product Scope; UX Intent And Success; Working Modes And
+Effective State; Activation, Blockers, Recovery And Transitions; Acceptance Criteria; Non-Goals;
+Users And Roles; Constraints; Evidence Requirements; Risks And Open Questions; Approval Decisions;
+Next Step. Populate relevant fields concretely or justify not_applicable. Product authority and
+visible presentation owner are distinct; technical storage/architecture/task choices belong later.
+
+Derive supported scope, roles, constraints and observable acceptance from the approved need and
+confirmed context. Preserve non-goals and unique stable criterion_id values; never invent users,
+product promises, approval, new scope or later design. Each applicable UX criterion names working
+mode, source state, action, expected effective state, visible feedback, blocker/failure behavior,
+recovery/next action, observable success and required evidence. Structural completeness is not
+semantic proof: retain the concrete inputs/draft and reasoned derivation for later review.
+
+## Clarify product decisions
+
+Keep one Approval Decisions table: Decision | Timing | Status | Resolution | Owner. A product,
+acceptance, accountable-owner or release-acceptance question belongs to before_prd. If material
+information is missing, preserve a useful draft with that row open and ask one bundled question.
+Do not manufacture an answer or report readiness. Retain answered context; sufficient inputs need
+no redundant question, and Run IDs are not product questions. Genuine later_sd/later_tp questions
+remain owner-bound deferrals, never hidden product decisions. Conflicting approved UR intent routes
+to its existing revision owner before a changed product draft can be presented.
+
+When a visible flow or decision remains hard to assess in prose, use a focused UI preview or scenario
+walkthrough following `ux-intent-definition`'s UI preview guidance. Reuse existing UX findings rather
+than creating a parallel specification or requiring another preview. Carry the scenario, observed
+feedback and qualification limits into the existing UX Intent And Success and Evidence Requirements
+sections; translate adopted behavior into stable acceptance criterion IDs. Record material product
+choices in the same Approval Decisions table, preserving unresolved `before_prd` rows. A positive
+reaction to a mockup resolves only the product questions actually answered; it is not `Approval: PRD`.
+For an optional aid, an unavailable visualization capability alone is not a readiness blocker when
+semantics can be clarified otherwise. Preserve an explicitly required preview from approved UR scope:
+read the UX report's exact run-local preview version, relative path, digests and observation limits.
+Confirm that the referenced durable copy exists and matches before relying on its findings; a
+chat-only preview, stale version or missing requested interaction leaves the obligation open.
+Use the existing UX analytical recovery route for missing required preview evidence; do not invent
+a product answer, repeat UR intake or bypass the required UX result. If PRD clarification creates or
+changes a preview, apply the UX skill's same retention and versioning rules. Keep material choices
+open until actually answered. Scope changes return to the earliest affected owner. Preview fidelity
+does not prescribe SD choices or prove working implementation.
+
+Gate-check alone evaluates readiness. Permission to finish clarification under
+AGDF_PRD_DECISIONS_OPEN does not remove the blocker or permit approval. Missing required UX input
+and unrelated integrity/source blockers are not PRD clarification permission. Use the interaction
+contract Bounded internal recovery route for eligible UX preparation; do not author PRD first.
+
+## Prepare the preview review handoff
+
+For a required UI preview, put a concise review task and versioned preview access in UX Intent And
+Success, relate the scenarios to stable criterion IDs, and retain the observations and limitations
+in Evidence Requirements. Keep material answers in Approval Decisions. Explain that PRD approval
+adopts the specified behavior and criteria; implementation, visual-design acceptance and delivery
+evidence require their own applicable sources. Do not label a proposed flow as already delivered.
+Follow interaction.md PRD Preview Review At Approval for the single canonical presentation owner,
+viewing/approval distinction, host availability and required revalidation. Prepare source material;
+never hand-build an extra approval card or claim missing runtime integration is implemented.
+
+The PRD owns exactly one `## Preview Review` section containing only one fenced `json` object.
+Use `schema_version: "1"`, a short lowercase `version` ending in `-vN`, the canonical approved
+`source_ur_digest`, and `entry: ".agdf/control/artefacts/<run_id>/previews/<version>/index.html"`.
+Provide `files` sorted by path, each with `path`, raw-byte SHA-256 `digest`, exact `bytes` and
+`media_type`; also provide `review_task`, nonempty `scenarios`, valid PRD `criterion_ids`, and
+`open_questions` (an array, possibly empty). No other keys or separate manifest are accepted.
+The whole descriptor is at most 16 KiB; at most 32 files, 128 KiB each and 1 MiB combined.
+Supported media are text/html, text/css, text/javascript and PNG/JPEG/WebP/GIF/SVG images.
+Keep classic scripts, styles, CSS imports and images local and declared; no network, modules,
+forms, embedded frames or host calls. Unsupported resource syntax fails explicitly. Bundle or
+simplify the example within the existing unapproved source owner; never substitute a blank view.
+The prepared PRD presentation snapshots exact source files and the isolated rendered view. It
+offers versioned access beside the document; opening it is not approval or proof of human review.
+A changed or unavailable required file requires repair/revision and a fresh presentation before
+an approval reply. Existing unmarked URs need no descriptor; an authored descriptor always binds.
+
+## Explicit revision and recording
+
+Before recording, use the continuation's resolved language and summary fields with
+gate-artifact-preparation's Language and approval summary preparation. A translated summary
+must be part of the draft before presentation, not deferred until a renderer failure.
+Use the shared canonical summary validator and separate recognized goal, scope and decisions
+labels. A required malformed summary is an unready authoring input, not a missing user choice.
+On an eligible own unapproved formatting diagnosis, correct once, validate and replace through
+the same typed writer, then reevaluate without a restart question. An unchanged failure stops;
+this does not permit editing a ready or approved draft without its existing authority.
+
+For a registered ready unapproved draft, require an actual human drafting/revision request;
+loading or selecting this skill is insufficient. The shared explicit route is gate-check with
+intake true, intake_mode resume, run_id, expected_revision_id and prd_action revise
+(CLI --prd-action revise). Ordinary ready-draft continuation presents the existing result.
+Never edit an approved PRD or transfer its approval. An approved-intent change uses the existing
+earliest affected UR/PRD revision route, not this unapproved authoring assignment.
+
+Use the shared Reviewed Recording Input in gate-artifact-preparation and existing
+run-step --step artefact --gate PRD --evidence <recording-input.json> with the supplied current
+run/revision. Record PRD derived_from the exact approved UR; analyses do not replace that source.
+Initial registration uses update_draft false; explicit registered replacement uses true with
+fresh reviewed mapping and recording paths. Retain previous proof/history and other protected
+bytes. Never hand-author receipts, substitute run-update for required source binding or reseal
+unknown edits. Follow existing transaction recovery and supported visible retry with fresh state.
+
+Use the returned revision and redispatch gate-check. When supplied, prepare exact run-present,
+show its returned text verbatim and wait for a NEW deliberate Approval: PRD. A different artifact
+language needs the existing localized summary: goal, scope, every criterion ID once and decision
+context, within unchanged limits. Editorial correction uses permitted canonical replacement and
+a fresh presentation; an old reply cannot approve changed content. Only valid PRD approval permits
+the existing SD stage. This skill creates no SD, TP, implementation, QA or release result.

package/generated/plugins/copilot/agdf/skills/contracts/quality.md

@@ -0,0 +1,228 @@
+# AGDF Runtime Contract — Quality
+
+## Quality Readiness Projection
+
+When `qa-gate` authors or refines `QA_REPORT.md`, it uses only the bound absolute plugin-owned
+`template_path`. Repository scaffold copies are derived review references, not an authoring source.
+An unavailable or unsafe template blocks QA report authoring without mutation or success-shaped
+fallback; it does not turn missing evidence into a QA decision.
+
+After CD+Tests, when any of the four review/QA artefacts exists, surfaces may show one compact
+derived `Quality Readiness` projection. It answers the user-facing question "what is the current
+quality outcome and what should happen next?" without replacing evidence or creating another
+decision authority.
+
+- It contains exactly four rows, in this order: `Plan coverage` from `task-plan-review`,
+  `Solution integrity` from `clean-implementation-review`, `Code quality` from `code-review`,
+  and `QA decision` from `qa-gate`.
+- `qa-gate` is always labeled as the sole decision owner. The other three rows are evidence
+  dimensions, not competing pass/revise/block decisions.
+- Overall status reuses canonical severity ordering. Missing or conflicting required evidence
+  must not render `pass`; surface `revise` or `block` with the decisive reason and one permitted
+  next action instead.
+- The projection is derived, non-persistent and non-authorizing. It cannot accept an approval,
+  advance a gate, suppress a report or replace the Run Status Card, Gate Transition Card, JSON
+  projection or durable review artefacts.
+- Show compact rows on `pass`. On `revise` or `block`, expand only the decisive row with its
+  canonical report reference; do not paste complete reports into chat.
+
+
+## Chat Output Discipline
+
+Durable artefacts are for the repository, not for flooding the chat.
+When a skill creates or updates `.agdf/control/` files, gate artefacts, reviews, QA reports or OR reports, the chat response must stay compact:
+
+- name the artefact path and status
+- summarize the decision or content in a few lines
+- state the current gate, forbidden work and next permissible step
+- mention validation evidence when available
+
+Do not paste full control files, full artefact bodies, full templates or full generated reports into the chat unless the user explicitly asks to see the full content.
+For larger or more formal work, create or update the durable artefacts fully, then reference them by path and summarize what changed.
+
+### Chat and Tool-Call Discipline
+
+Chat output shows decisions and outcomes. Files show evidence and detail. The agent
+uses the sole Routine Continuation And Visible Events policy in interaction.md; every required
+checkpoint and review still executes. It minimises tool calls and accompanying chat text. This
+is surface-agnostic: it changes agent behaviour and framework text, not host rendering.
+Whether a host renders a tool-call block visibly is a host concern; the framework ensures
+the agent makes fewer calls and produces less text around them.
+
+Skill output compaction:
+
+- QA, Code Review, TP Review and Clean Implementation Review output is 1 line at `pass`:
+  `<skill>: pass — <one-line summary>`.
+- At `revise`/`block`: the decisive dimension, reason and next action. The Quality
+  Readiness projection is shown only at `revise`/`block`, not at `pass`.
+- Full reports remain in durable files; the chat references the path.
+
+Tool-call batching:
+
+- `RUN_STATE.md` is written once per user gate approval, not once per field change. The
+  agent keeps intermediate state in memory between gate approvals and writes the complete
+  updated state in one operation, then records it with `run-update` before the next `gate-check`.
+- The agent does not `read` existing artefacts for format reference. Skill instructions
+  carry the format/structure inline. If a specific existing artefact must be inspected
+  for content (not format), the read has no accompanying commentary.
+- Artefact writes are silent: the agent names the path and a 1-line summary only when an
+  artefact is first created or significantly changed — not on every state update.
+- Validation commands (tests, integrity, diff) show pass/fail only. Full output appears
+  only on failure.
+
+Always visible:
+
+- Gate decisions (Run Status Card, Gate Transition Card, approval question).
+- Post-acceptance narration (1 line per gate transition).
+- Delivery summary (UAT/OR compact summary).
+- Errors, blockers and evidence at `revise`/`block`.
+
+
+## Quality Contract Output
+
+Current structured QA preparation requires concrete authored fields in the first scalar block
+of existing QA sections: `delivered_result` under TP Coverage, `qualification_limits` under
+Missing Evidence and `delivery_risks` under Risks (canonical numbered headings supported).
+Only limits/risks permit explicit `none`. Initial Run drafts stay authorable; current decisions
+require concrete orienting Objective. The shared bounded context observer excludes examples,
+quotes/code/HTML and whole template values; diagnosis and preparation never repair sources.
+UAT derives Goal from approved UR, actual result/limits from current QA, original QA/accepted
+deviation disposition and the existing approval effect. It stores no second result authority.
+When source and display languages differ, existing source-authored Approval Summary uses
+Goal/Ziel and Delivered result/Ergebnis, Qualification limits/Grenzen, Risks/Risiken. Complete
+current fields before new QA approval; missing approved legacy content stays protected and
+needs its existing renewal assessment, never silent backfill. Historical accepted documents
+and completed Runs retain original proof. No content check grants approval or proves truth.
+
+Core reads reported technical results through one shared observer. `Decision`/`decision` and
+technical `Status` declarations may repeat the same supported result; `passed` normalizes to
+`pass`. Lifecycle metadata such as `Status: draft` or `Status: done` is not a QA result.
+Only initial result metadata (optionally after the report H1) and the first scalar field block
+under a column-zero H2 `Decision` or `QA Decision` heading are authored result contexts. Numeric
+section prefixes and closing heading hashes are supported; canonical `## 1. QA Decision` remains
+valid. Prose, unrelated/nested headings and non-metadata fields close the field block; a blank
+line never reopens it. Metadata names are the existing Decision, Status, Gate, Gate approval,
+Based on, Date, Owner, Type, Mode, Reviewer, reviewed_at, run_id, source_revision and Traceability
+contract. Fenced/indented code, lists, blockquotes (including lazy continuations), HTML containers,
+comments and raw blocks never supply results or conflicts. Only a clearly terminated container
+allows a following genuine decision section; uncertain/unclosed markup keeps its remainder excluded.
+This is a conservative bounded report grammar, not general Markdown parsing or prose-intent inference.
+Bound Quick review and non-UX internal registration reuse the observer. Only the internal analysis
+domain opts into `not_applicable`; its existing eligibility/reason checks remain authoritative.
+Conflicting supported values, an unknown or empty explicit Decision, or a missing supported
+result remain unconfirmed. This observes authored evidence only: it grants no QA decision,
+approval, source replacement or closeout permission. Exact approved bytes and current bindings
+remain separately enforced.
+
+Structured Delivery skills use this shape when relevant:
+
+- `decision`: `pass | revise | block | not_applicable`
+- `evidence`: concrete artefacts, files, tests, logs, diffs, or observations
+- `missing_evidence`: missing proof needed for a stronger claim
+- `risks`: remaining risks, assumptions, fallbacks, drift, or blockers
+- `required_next_step`: exactly the next clean step
+- `impact_codes`: affected Quality Contract codes, if the target repo has a registry
+
+
+## Normalized Review Gaps
+
+This section is the sole normative owner for review-gap classification and routing. An applicable
+finding from Task Plan Review, Clean Implementation Review or Code Review carries exactly one
+normalized gap type and one routing target:
+
+| gap_type | meaning | routing_target |
+|---|---|---|
+| `requirements_gap` | approved product behavior or an acceptance criterion is missing or contradictory | `PRD`; use `UR` only when user intent or scope changed |
+| `design_gap` | technical ownership, architecture, fallback policy, exit criterion or a prohibited parallel structure was not decided | `SD` |
+| `plan_gap` | an approved requirement or design obligation lacks an executable task, test or evidence mapping | `TP` |
+| `implementation_gap` | code or a surface does not fulfil an approved requirement, design or task | `CD+Tests` |
+| `evidence_gap` | required test, runtime or visible evidence is absent or insufficient | `evidence_obligation` |
+| `emergent_risk` | implementation exposes a concrete risk not reasonably decidable from approved artefacts | earliest affected `UR | PRD | SD | TP | CD+Tests | evidence_obligation` target after explicit assessment |
+
+Normalized finding rows use these fields in order:
+
+`finding_id | gap_type | routing_target | gap_status | evidence | required_next_step`
+
+- `finding_id` is stable within the durable review report.
+- `gap_type` is exactly one type from the table above.
+- `routing_target` is exactly `UR | PRD | SD | TP | CD+Tests | evidence_obligation` and must agree
+  with the fixed route above. `requirements_gap` may use `UR` only with evidence of changed user
+  intent or scope. An open `emergent_risk` requires an explicit earliest-owner assessment
+  before routing corrective work; a resolved row retains its original route and resolution evidence.
+- `gap_status` is exactly `open | resolved`.
+- `evidence` names concrete source, diff, test, observation or missing proof.
+- `required_next_step` for an open finding is exactly one executable action consistent with
+  the routing target. A resolved finding may state `none`, explain that no further corrective
+  action remains, or name its subsequent review/lifecycle step. Its evidence must remain concrete;
+  resolution never makes a missing field, invalid type/route or placeholder evidence valid.
+
+Missing, unknown or contradictory fields fail closed as an open gap. Consumers must not silently
+reclassify a finding. Classification is non-authorizing: it cannot edit or approve UR, PRD, SD or TP,
+advance a gate or replace a review decision. `qa-gate` consumes the normalized findings and cannot
+return `pass` while any applicable finding is open or invalid.
+
+`none` is not a seventh normalized finding type. It is permitted as a presentation sentinel on a
+fulfilled UX Intent Fidelity row and as `required_next_step` on a resolved finding, never as
+`gap_type`, `routing_target` or resolution evidence. Open findings still require executable action.
+
+Current QA/UAT decision preparation and prepared closeout use the same normalized-finding
+observer. A technical pass cannot present a human approval while a registered review contains
+an open or invalid finding. Historical approved reports are observed without rewriting their
+bytes, decisions or receipts; a resolved finding does not require a new repair or a new approval.
+
+A consumer may repeat the field order and allowed scalar values needed to emit valid output. It must
+reference this section for meanings and routes instead of maintaining a second complete mapping.
+
+## Human QA Acceptance With Deviations
+
+The technical QA decision remains exactly `pass | revise | block`. An explicit human acceptance
+of deviations is a separate disposition; it never changes `revise` to `pass`, resolves a finding,
+marks a missing test passed, or grants native production qualification.
+
+The existing unapproved QA report may contain one `QA Deviation Acceptance` JSON section,
+specified in `docs/qa-deviation-acceptance.md`. Core evaluates it through the normalized finding
+owner above. Only complete, current low/medium evidence-only findings may be proposed; every
+open finding must be covered exactly. Upstream or implementation gaps, malformed/conflicting
+findings, `block`, non-passing protected Code/Clean reviews, stale associations and hard Run
+blockers prevent this route. Existing required obligations are not silently waived.
+
+Before requesting a decision, show the bounded usage scope and each finding's risk, consequence,
+follow-up and owner. The sole contextual action is `Approve with deviations` (German:
+`Mit Abweichungen freigeben`); Chat uses the existing exact `Approval: QA` against that newly
+presented version. A previously rejected response is never transferred. The existing approval
+transaction, receipt and exact-material owner record one effect for both routes. UAT follows
+only after that deliberate acceptance; the original report and open findings remain intact.
+UAT and OR must carry the accepted deviations forward explicitly.
+
+## UX Intent Fidelity
+
+When an approved PRD contains applicable UX criteria, `task-plan-review` produces an additional
+evidence matrix with these columns in order:
+
+`prd_criterion | working_mode_state | task_id | visible_evidence | fidelity_status | gap_type`
+
+`fidelity_status` is exactly `fulfilled | partial | missing | not_verifiable`. A fulfilled row uses
+the `none` sentinel. Any non-fulfilled row uses the applicable normalized type from `Normalized
+Review Gaps`; it may also emit the normalized finding shape when routing detail is required.
+
+This matrix verifies PRD-to-TP coverage and TP-to-code/surface fulfilment. It does not create product
+requirements and does not decide QA. A missing implementation-relevant PRD requirement is a
+`requirements_gap` and routes to PRD revision. `qa-gate` consumes this evidence and cannot return
+`pass` while an applicable row is `partial`, `missing` or `not_verifiable`, or while a visible-behavior
+claim has code evidence without visible evidence. The four-row Quality Readiness projection and
+`qa-gate` sole decision ownership remain unchanged.
+
+A skill may briefly remind this shape, but must not duplicate a complete code or rule matrix.
+
+
+## Skill Output
+
+Every skill output should be as short as possible and as concrete as needed.
+It must distinguish:
+
+- facts
+- evidence
+- assumptions
+- interpretations
+- missing evidence
+- the next permissible step