create-agdf 0.10.2 → 0.11.0

package/generated/plugins/agdf/runtime/create-agdf/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [

package/generated/plugins/agdf/runtime/runtime-manifest.json

@@ -2,7 +2,7 @@
   "schema_version": "1",
   "generated": true,
   "source": "create-agdf/cli",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "entrypoint": "create-agdf/bin/agdf-validator.js",
-  "digest": "9103a8c171c070432f22b4f3c40e39c46ddd183f8fabfe7fb701784aab8ca2d3"
+  "digest": "55653e0c7f7d732bd4bf2973f5208fea23c6d7edb6a4616499c818d1089c4f3b"
 }

package/generated/plugins/agdf/scripts/check-runtime-integrity.mjs

@@ -137,6 +137,7 @@ const expectedControlFiles = [
   "templates/artefacts/BROWNFIELD_REVIEW.md",
   "templates/artefacts/VERIFIED_CHANGE.md",
   "templates/artefacts/PRD.md",
+  "templates/artefacts/UX_INTENT_DEFINITION.md",
   "templates/artefacts/SD.md",
   "templates/artefacts/TP.md",
   "templates/artefacts/QA_REPORT.md",
@@ -369,6 +370,16 @@ for (const required of gateCheckOperationalBoundaries) {
 for (const duplicatedPolicy of ["Surface behavior:", "Make exactly one native-attempt", "Interaction Locale Contract", "decorated_label_only"]) {
   if (gateCheckSkill.includes(duplicatedPolicy)) failures.push(`gate-check must not duplicate normative interaction policy: ${duplicatedPolicy}`);
 }
+if (!gateCheckSkill.includes("`status_presentation.markdown` verbatim")) {
+  failures.push("gate-check must consume the deterministic operational status presentation");
+}
+if (gateCheckSkill.includes("| Run status | Value |")) {
+  failures.push("gate-check must not maintain a second operational status-card template");
+}
+if (!runtimeContract.includes("### Deterministic Operational Presentation")
+  || !/must\s+not reconstruct a table/.test(runtimeContract)) {
+  failures.push("interaction contract must own deterministic operational status presentation");
+}
 
 for (const gate of ["UR", "PRD", "SD", "TP", "QA", "UAT"]) {
   for (const locale of ["en", "de"]) {
@@ -507,6 +518,37 @@ if (isFile(pagesIndexPath) && !read(pagesIndexPath).includes("{skills.length} Co
   failures.push("Pages skill heading must derive its count from skills.length");
 }
 
+if (isFile(pagesSiteDataPath)) {
+  const pagesSiteData = read(pagesSiteDataPath);
+  for (const requiredWorkflowPhrase of [
+    "Conditional: UX Intent Definition",
+    "Post-UR routing records Greenfield or Brownfield and UI/UX impact",
+    "This fail-closed analysis is not a gate",
+    "The approved PRD is the sole product authority",
+    "Task Plan Review then verifies UX Intent Fidelity",
+    "QA cannot pass partial, missing or not-verifiable criteria",
+  ]) {
+    if (!pagesSiteData.includes(requiredWorkflowPhrase)) {
+      failures.push(`Pages workflow must preserve UX-intent lifecycle phrase: ${requiredWorkflowPhrase}`);
+    }
+  }
+}
+
+if (isFile(pagesIndexPath)) {
+  const pagesIndex = read(pagesIndexPath);
+  for (const requiredFidelityPhrase of [
+    "Approved PRD contract",
+    "requirements_gap",
+    "not_verifiable",
+    "Incomplete UX Intent Fidelity prevents a QA pass",
+    "{skills.map(skill => (",
+  ]) {
+    if (!pagesIndex.includes(requiredFidelityPhrase)) {
+      failures.push(`Pages fidelity evidence must preserve phrase: ${requiredFidelityPhrase}`);
+    }
+  }
+}
+
 if (codexPlugin && pluginDefinition) {
   if (codexPlugin.name !== pluginDefinition.id) failures.push("Codex plugin manifest name must match canonical AGDF plugin definition");
   if (codexPlugin.version !== pluginDefinition.version) failures.push("Codex plugin manifest version must match canonical AGDF plugin definition");
@@ -824,11 +866,8 @@ for (const skill of expectedSkills) {
     if (!skillMd.includes("The canonical gate order and transition model live only in `../../meta/contracts/gate-transition.md`")) {
       failures.push("gate-check must point to gate-transition.md as gate transition SoT");
     }
-    for (const label of ["Status", "Current gate", "Allowed now", "Blocked by", "Missing approval", "Next step", "Quality outlook"]) {
-      if (!skillMd.includes(`| ${label} |`)) failures.push(`gate-check must render Run Status Card label: ${label}`);
-    }
-    if (!skillMd.includes("Next gate after approval") || !skillMd.includes("Allowed after approval")) {
-      failures.push("gate-check must render post-approval Run Status Card fields when an approval is missing");
+    if (!skillMd.includes("`status_presentation.markdown` verbatim") || !skillMd.includes("Do not maintain or render a skill-local table template")) {
+      failures.push("gate-check must delegate operational status rendering to the canonical projection");
     }
     if (!skillMd.includes("A decision value without scope reason and evidence is still missing")) {
       failures.push("gate-check must require evidenced Mode/Slice Decision before later work");
@@ -864,6 +903,14 @@ for (const skill of expectedSkills) {
       failures.push("gate-check must classify CLI reports as validators, not the primary workflow");
     }
   }
+  if (skill === "release-or") {
+    const rulesSection = skillMd.match(/## Rules\r?\n([\s\S]*?)(?=\r?\n## )/)?.[1] ?? "";
+    const ruleNumbers = [...rulesSection.matchAll(/^(\d+)\. /gm)].map((match) => Number(match[1]));
+    const expectedRuleNumbers = ruleNumbers.map((_, index) => index + 1);
+    if (ruleNumbers.length === 0 || JSON.stringify(ruleNumbers) !== JSON.stringify(expectedRuleNumbers)) {
+      failures.push(`release-or Rules numbering must be sequential from 1, got ${ruleNumbers.join(", ") || "none"}`);
+    }
+  }
 
   for (const [pathLabel, content] of [
     [`${skill}/SKILL.md`, skillMd],
@@ -896,6 +943,8 @@ const contextGraphTemplatePath = join(controlRoot, "templates", "CONTEXT_GRAPH.m
 const sotRegistryTemplatePath = join(controlRoot, "templates", "SOT_REGISTRY.md");
 const qualityContractsPath = join(controlRoot, "templates", "AGENT_QUALITY_CONTRACTS.json");
 const brownfieldReviewTemplatePath = join(controlRoot, "templates", "artefacts", "BROWNFIELD_REVIEW.md");
+const uxIntentTemplatePath = join(controlRoot, "templates", "artefacts", "UX_INTENT_DEFINITION.md");
+const prdTemplatePath = join(controlRoot, "templates", "artefacts", "PRD.md");
 const verifiedChangeTemplatePath = join(controlRoot, "templates", "artefacts", "VERIFIED_CHANGE.md");
 const orTemplatePath = join(controlRoot, "templates", "artefacts", "OR.md");
 const backlogTemplatePath = join(controlRoot, "templates", "MASTER_BACKLOG.md");
@@ -965,11 +1014,84 @@ if (isFile(sotRegistryTemplatePath)) {
 
 if (isFile(brownfieldReviewTemplatePath)) {
   const brownfieldReviewTemplate = read(brownfieldReviewTemplatePath);
-  for (const required of ["Existing-System View", "Reuse And Parallel-Structure Risk", "Mode / Slice Decision", "transparency_note", "Next Permissible Step"]) {
+  for (const required of ["Existing-System View", "Reuse And Parallel-Structure Risk", "Mode / Slice Decision", "transparency_note", "Next Permissible Step", "delivery_context", "ui_ux_impact", "ui_ux_impact_reason", "ux_intent_definition_required", "ux_intent_definition_result"]) {
     if (!brownfieldReviewTemplate.includes(required)) failures.push(`BROWNFIELD_REVIEW.md missing control field: ${required}`);
   }
 }
 
+if (isFile(uxIntentTemplatePath)) {
+  const template = read(uxIntentTemplatePath);
+  for (const required of ["Decision: ready | blocked | not_applicable", "effective_state_authority_by_mode", "primary_state_presentation_owner_by_mode", "recovery_paths", "Proposed PRD Acceptance Criteria", "non-authorizing analytical input"]) {
+    if (!template.includes(required)) failures.push(`UX_INTENT_DEFINITION.md missing contract field: ${required}`);
+  }
+  if (/^Gate:|^Gate approval:|Approval:/m.test(template)) failures.push("UX_INTENT_DEFINITION.md must not carry gate or approval authority");
+}
+
+if (isFile(prdTemplatePath)) {
+  const template = read(prdTemplatePath);
+  for (const required of ["UX Intent And Success", "Working Modes And Effective State", "effective_state_authority", "primary_state_presentation_owner", "Activation, Blockers, Recovery And Transitions", "visible retry", "stable `criterion_id`"]) {
+    if (!template.includes(required)) failures.push(`PRD.md missing mandatory UX requirement: ${required}`);
+  }
+}
+
+if (isFile(join(skillRoot, "ux-intent-definition", "SKILL.md"))) {
+  const skill = read(join(skillRoot, "ux-intent-definition", "SKILL.md"));
+  for (const required of ["ready | blocked | not_applicable", "effective_state_authority_by_mode", "primary_state_presentation_owner_by_mode", "A required blocked result prevents PRD readiness", "not a user gate"]) {
+    if (!skill.includes(required)) failures.push(`ux-intent-definition SKILL.md missing invariant: ${required}`);
+  }
+}
+
+const normalizedGapFieldOrder = "finding_id | gap_type | routing_target | gap_status | evidence | required_next_step";
+const normalizedGapMappingHeader = "| gap_type | meaning | routing_target |";
+const qualityContractPath = join(contractsDir, "quality.md");
+if (isFile(qualityContractPath)) {
+  const contract = read(qualityContractPath);
+  for (const required of [
+    "## Normalized Review Gaps",
+    normalizedGapFieldOrder,
+    "requirements_gap",
+    "design_gap",
+    "plan_gap",
+    "implementation_gap",
+    "evidence_gap",
+    "emergent_risk",
+    "UR | PRD | SD | TP | CD+Tests | evidence_obligation",
+    "gap_status` is exactly `open | resolved",
+    "It is not a seventh normalized finding type",
+  ]) {
+    if (!contract.includes(required)) failures.push(`quality contract missing normalized review-gap invariant: ${required}`);
+  }
+}
+
+for (const skillName of ["task-plan-review", "clean-implementation-review", "code-review", "qa-gate"]) {
+  const path = join(skillRoot, skillName, "SKILL.md");
+  if (!isFile(path)) continue;
+  const skill = read(path);
+  for (const required of ["§Normalized Review Gaps", "fail closed"]) {
+    if (!skill.includes(required)) failures.push(`${skillName} SKILL.md missing normalized review-gap consumer invariant: ${required}`);
+  }
+  if (skillName !== "qa-gate" && !skill.includes(normalizedGapFieldOrder)) {
+    failures.push(`${skillName} SKILL.md missing normalized finding field order`);
+  }
+  if (skill.includes(normalizedGapMappingHeader)) {
+    failures.push(`${skillName} SKILL.md must not duplicate the complete normalized gap mapping`);
+  }
+}
+
+if (isFile(join(skillRoot, "task-plan-review", "SKILL.md"))) {
+  const skill = read(join(skillRoot, "task-plan-review", "SKILL.md"));
+  for (const required of ["## UX Intent Fidelity", "prd_criterion | working_mode_state | task_id | visible_evidence | fidelity_status | gap_type", "requirements_gap", "not_verifiable"]) {
+    if (!skill.includes(required)) failures.push(`task-plan-review SKILL.md missing UX fidelity invariant: ${required}`);
+  }
+}
+
+if (isFile(join(skillRoot, "qa-gate", "SKILL.md"))) {
+  const skill = read(join(skillRoot, "qa-gate", "SKILL.md"));
+  for (const required of ["UX Intent Fidelity", "visible evidence", "requirements_gap"]) {
+    if (!skill.includes(required)) failures.push(`qa-gate SKILL.md missing UX fidelity consumption: ${required}`);
+  }
+}
+
 if (isFile(verifiedChangeTemplatePath)) {
   const verifiedChangeTemplate = read(verifiedChangeTemplatePath);
   for (const required of ["related_ur", "canonical_owner", "allowed_source_paths", "allowed_derived_paths", "baseline_tracked_paths", "baseline_untracked_paths", "escalation_target", "validation_commands"]) {

package/generated/plugins/agdf/skills/brownfield-analysis/SKILL.md

@@ -35,6 +35,11 @@ When `.agdf/control/` is present, persist or link `post_ur_review` output under
 
 Do not mix both modes silently. Name the active mode in the output.
 
+In `post_ur_review`, also record `delivery_context`, `ui_ux_impact`, `ui_ux_impact_reason` and
+`ux_intent_definition_required` using the single classification and routing contract in
+`../../meta/contracts/gate-transition.md`. Greenfield records make existing-system evidence explicitly
+not applicable; Brownfield records cite repository evidence. Do not create a second Greenfield router.
+
 ## Rules
 1. Brownfield first: understand the existing codebase before PRD/SD decisions when existing-system impact is possible, and again before implementation.
 2. Brownfield Review after `Approval: UR` is a sizing and routing step. It must visibly decide `quick_task`, `verified_change`, `structured_slice`, `structured_delivery`, or `block` before PRD depth or implementation is chosen. Persist the completed review and its decision, scope reason, evidence and required next gate in the same internal operation; mark the review `done` only after both the artefact and canonical run projection are complete. An interrupted, incomplete or legacy record stays at fail-closed `Mode/Slice Decision` recovery without another user approval.
@@ -124,6 +129,10 @@ Use a concise structure:
 - required_next_step:
 ```
 
+For `post_ur_review`, include the four UI/UX routing fields immediately after `scope`. If UX intent
+definition is required, its `ready | blocked | not_applicable` result must be visible before PRD
+readiness. A required `blocked` result is at least `revise` for this routing step.
+
 ## Pass / Revise / Block Guidance
 - `pass`: existing owners are understood, reuse path is clear, and no blocking drift or parallel structure risk remains.
 - `revise`: relevant evidence, tests, ownership, or reuse path is incomplete.

package/generated/plugins/agdf/skills/clean-implementation-review/SKILL.md

@@ -24,6 +24,8 @@ Use these focused runtime-contract modules:
 - `../../meta/contracts/context-graph.md`
 
 Clean-review-specific output must make the primary solution, fallbacks, workarounds, parallel structures, exit criteria, and next cleanup/review step visible.
+Applicable findings must use `../../meta/contracts/quality.md` §Normalized Review Gaps. This skill
+must distinguish a missing upstream decision from implementation that violates an approved decision.
 
 ## Rules
 1. Clean primary solution before fallback.
@@ -35,6 +37,10 @@ Clean-review-specific output must make the primary solution, fallbacks, workarou
 7. Maintainability matters; "works somehow" is not enough.
 8. Async execute paths must not decide product rules again.
 9. Shared finalization or merge rules belong in one owner.
+10. Missing canonical ownership, fallback policy, exit criteria or parallel-structure decisions are
+    upstream gaps; do not invent those decisions during review.
+11. Actual code that violates an approved design or plan is an implementation gap.
+12. Missing, unknown or contradictory classifications fail closed and stay open.
 
 ## When To Use
 - after `CD+Tests`
@@ -89,6 +95,16 @@ Use this compact structure:
 - required_next_step:
 ```
 
+When findings exist, append:
+
+```text
+## Normalized Findings
+| finding_id | gap_type | routing_target | gap_status | evidence | required_next_step |
+|---|---|---|---|---|---|
+```
+
+Use the shared Quality Contract for meanings and routes; do not copy its complete mapping here.
+
 ## Pass / Revise / Block Guidance
 - `pass`: primary solution is clean, tested, and integrated with existing owners.
 - `revise`: solution works but contains avoidable fallback, unclear ownership, or missing evidence.
@@ -106,3 +122,5 @@ This skill must not:
 - hide unjustified workarounds
 - treat green tests as proof of solution integrity
 - decide final QA
+- create a missing design, plan or product decision during review
+- silently repair or reclassify an invalid normalized finding

package/generated/plugins/agdf/skills/code-review/SKILL.md

@@ -23,6 +23,8 @@ Use these focused runtime-contract modules:
 - `../../meta/contracts/context-graph.md`
 
 Code-review-specific output must make actual findings, missing review scope, evidence strength, and the next required step visible.
+Applicable findings must use `../../meta/contracts/quality.md` §Normalized Review Gaps. Concrete diff
+defects remain Code Review findings; missing upstream constraints route to their authoritative owner.
 
 ## Rules
 1. Review the actual diff and impacted code, not intent alone.
@@ -33,6 +35,9 @@ Code-review-specific output must make actual findings, missing review scope, evi
 6. Brownfield owners and existing conventions are binding unless deviation is justified.
 7. Distinguish blocking defects from fixable review findings.
 8. CR does not grant QA pass.
+9. Do not turn Code Review into a static requirements checklist or invent missing upstream constraints.
+10. A genuinely new implementation risk uses `emergent_risk` with an explicit earliest-owner assessment.
+11. Missing, unknown or contradictory classifications fail closed and stay open.
 
 ## When To Use
 - after `CD+Tests`
@@ -81,6 +86,16 @@ Use this compact structure:
 - required_next_step:
 ```
 
+When findings exist, append:
+
+```text
+## Normalized Findings
+| finding_id | gap_type | routing_target | gap_status | evidence | required_next_step |
+|---|---|---|---|---|---|
+```
+
+Use the shared Quality Contract for meanings and routes; do not copy its complete mapping here.
+
 ## Decision Guidance
 - `pass`: no meaningful review finding remains evident in reviewed scope.
 - `revise`: fixable correctness, regression, or maintainability issues remain.
@@ -100,3 +115,5 @@ This skill must not:
 - hide missing review scope
 - generate style-only findings
 - duplicate TP Review or QA as if they were the same step
+- invent a requirement, design decision or plan obligation to justify a finding
+- silently repair or reclassify an invalid normalized finding

package/generated/plugins/agdf/skills/gate-check/SKILL.md

@@ -85,10 +85,11 @@ This skill owns only these operational responsibilities:
 5. Revalidate the same run, gate and revision immediately after the response and before persistence.
 6. Persist only a currently valid exact approval through the existing control-state workflow.
 
-For status, blocked, read-only or rationale interactions, consume the same canonical projection and
-locale contract without asking for approval. Internal process steps remain distinct from user
-decisions. If the projection, adapter evidence or revalidation is missing, follow the contract's
-fail-closed outcome and leave authority unchanged.
+For status, blocked, read-only or rationale interactions, consume the canonical
+`status_presentation.markdown` verbatim and apply the locale contract without asking for approval.
+Do not reconstruct its fields, ordering, labels or Markdown from `status_card` JSON. Internal process
+steps remain distinct from user decisions. If the projection, adapter evidence or revalidation is
+missing, follow the contract's fail-closed outcome and leave authority unchanged.
 
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
@@ -163,23 +164,15 @@ If a status is not explicit, do not assume it is satisfied.
 12. If branch, workspace and durable artefacts disagree, do not choose a scope silently; report the ambiguity and ask for the smallest clarifying gate action.
 
 ## Output
-Keep the result short and operational. Render the Runtime Contract's compact human-facing Run Status Card rather than a surface-specific summary:
-
-| Run status | Value |
-|---|---|
-| Status | `open | blocked` |
-| Current gate | `<GateName or internal step>` |
-| Allowed now | `<currently allowed outputs>` |
-| Blocked by | `<blocking condition or none>` |
-| Missing approval | `Approval: <GateName> | none` |
-| Next step | `<single permissible next step>` |
-| Quality outlook | `<next meaningful quality focus or none>` |
-
-When an approval is missing, also include `Next gate after approval` and `Allowed after approval` exactly as constrained by the Runtime Contract. Keep forbidden outputs, evidence and next-skill detail in the concise surrounding text when relevant; they are not extra status-card rows.
+Keep the result short and operational. For a status-only response, consume the Runtime Contract's
+code-owned `status_presentation.markdown` verbatim. It is the compact localized operational Run
+Status Card and already includes current and post-approval authority, next-step and quality fields.
+Keep full raw evidence in `status_card` JSON or concise surrounding detail when relevant; do not turn
+the primary chat card into an audit dump. Do not maintain or render a skill-local table template.
 
 This complete operational status table remains the status-reporting and detail
 surface. When the same response immediately requests a ready gate approval,
-render its six-field compact approval-time projection first, then the Gate
+render its five-field compact approval-time projection first, then the Gate
 Transition Card in the same immediately preceding assistant message, then
 invoke exactly one native question or exact-text fallback. Both cards derive
 from the same snapshot and are shown exactly once.

package/generated/plugins/agdf/skills/qa-gate/SKILL.md

@@ -31,6 +31,8 @@ Use these focused runtime-contract modules:
 QA-specific `decision` is exactly `pass | revise | block`.
 `pass` is allowed only when TP coverage, Brownfield fit, solution integrity, and relevant documentation/Context Graph impact are sufficiently evidenced.
 `sot_drift` must not pass silently as a warning.
+Consume applicable findings through `../../meta/contracts/quality.md` §Normalized Review Gaps.
+QA must not maintain a second mapping or reclassify review findings.
 
 When post-CD+Tests review evidence exists, present the Runtime Contract's derived Quality
 Readiness projection before the detailed QA report: Plan coverage, Solution integrity, Code
@@ -48,6 +50,11 @@ Gate Transition Card or the durable QA report.
 6. Solution integrity is mandatory.
 7. Always output exactly one decision: `pass`, `revise`, or `block`.
 8. Open risks, missing tests, partial TP coverage, or side effects must be visible.
+9. Applicable UX Intent Fidelity rows must all be `fulfilled` with suitable visible evidence before `pass`.
+10. A `requirements_gap` routes to PRD revision; QA must not invent or accept the missing criterion.
+11. Any applicable normalized finding that is `open`, missing, unknown, contradictory or supported by
+    insufficient evidence prevents `pass`.
+12. A `resolved` finding counts only when its durable review evidence proves the routed correction or decision.
 
 ## When To Use
 - after `CD+Tests`
@@ -82,14 +89,16 @@ If evidence is missing, lower the decision accordingly.
 2. Verify TP coverage.
 3. Verify P0/P1 completion.
 4. Verify Brownfield fit.
-5. Verify solution integrity.
-6. Verify tests and evidence strength.
-7. Verify documentation and Context Graph impact if relevant.
-8. Decide:
+5. Verify UX Intent Fidelity when applicable, including visible evidence for visible-behavior claims.
+6. Consume normalized findings without reclassification; fail closed on every open or invalid row.
+7. Verify solution integrity.
+8. Verify tests and evidence strength.
+9. Verify documentation and Context Graph impact if relevant.
+10. Decide:
    - `pass`
    - `revise`
    - `block`
-9. State the single required next step.
+11. State the single required next step.
 
 ## Output
 Use this shape:
@@ -125,3 +134,4 @@ This skill must not:
 - replace UAT
 - treat missing reviews as completed
 - downgrade SoT drift to harmless warning
+- silently repair, normalize or reroute a review finding

package/generated/plugins/agdf/skills/release-or/SKILL.md

@@ -52,7 +52,7 @@ Use the Runtime Contract definition of `Relevant Run` to decide whether OR is ma
 13. Keep machine status normalization in the CLI; do not write internal snake_case status values into the human-facing backlog.
 14. Reconcile Context Graph impact before clean closeout: report `context_graph_reconciliation: resolved | not_applicable | open_gap`.
 15. If Context Graph work remains unresolved, report it as an explicit open gap and do not describe the run as cleanly handoff-ready.
-15. After writing or updating `MASTER_BACKLOG.md`, run `doctor --json` (or the locally available equivalent) and resolve any `AGDF_BACKLOG_STATUS_UNKNOWN` or `AGDF_BACKLOG_ARTEFACT_LABEL_UNKNOWN` finding before closeout. See the AGDF control scaffold's `MASTER_BACKLOG.md` template Rules section for the canonical status/artefact label vocabulary.
+16. After writing or updating `MASTER_BACKLOG.md`, run `doctor --json` (or the locally available equivalent) and resolve any `AGDF_BACKLOG_STATUS_UNKNOWN` or `AGDF_BACKLOG_ARTEFACT_LABEL_UNKNOWN` finding before closeout. See the AGDF control scaffold's `MASTER_BACKLOG.md` template Rules section for the canonical status/artefact label vocabulary.
 
 ## When To Use
 - at the end of every relevant run

package/generated/plugins/agdf/skills/task-plan-review/SKILL.md

@@ -27,6 +27,8 @@ Use these focused runtime-contract modules:
 
 TP-specific output must evaluate every relevant `task_id` with completion status, AC coverage, evidence, missing evidence, and QA-relevant gaps.
 If `context_graph_required_action` is not `none`, the affected task is complete only if follow-up, evidence, or an intentionally open gap is visible.
+Applicable review gaps must use `../../meta/contracts/quality.md` §Normalized Review Gaps. This skill
+must not maintain its own type-to-route mapping.
 
 ## Rules
 1. The Task Plan is the reference, not plausible code.
@@ -39,6 +41,12 @@ If `context_graph_required_action` is not `none`, the affected task is complete
 8. P0/P1 gaps must be handed to QA.
 9. Out-of-scope changes must be reported.
 10. When evidence is unclear, fail closed to at least `partially_done`.
+11. When approved PRD UX criteria apply, verify both PRD-to-TP coverage and TP-to-code/surface fulfilment.
+12. Never invent a missing UX requirement. Report `requirements_gap` and route it to PRD revision.
+13. Visible behavior requires visible evidence; code evidence alone is `not_verifiable`.
+14. A fulfilled UX Intent Fidelity row uses `none`; every non-fulfilled applicable row uses one
+    normalized gap type and a contract-valid route.
+15. Missing, unknown or contradictory classifications fail closed and stay open.
 
 ## Clarifications
 ### TP Slice Before Target State
@@ -90,6 +98,27 @@ Use this compact structure:
 - required_next_step:
 ```
 
+When applicable, append:
+
+```text
+## UX Intent Fidelity
+| prd_criterion | working_mode_state | task_id | visible_evidence | fidelity_status | gap_type |
+|---|---|---|---|---|---|
+```
+
+Use `fulfilled | partial | missing | not_verifiable` for `fidelity_status` and
+the shared Quality Contract for `gap_type`. `none` is allowed only on a fulfilled row.
+
+When an applicable gap needs routing detail, append:
+
+```text
+## Normalized Findings
+| finding_id | gap_type | routing_target | gap_status | evidence | required_next_step |
+|---|---|---|---|---|---|
+```
+
+Use only contract-defined values. Do not reconstruct the type-to-route mapping locally.
+
 Completion status:
 
 - `fully_done`
@@ -122,3 +151,7 @@ This skill must not:
 - hide partial work
 - upgrade missing evidence into confidence
 - reinterpret the TP scope
+- create or silently repair product requirements
+- treat code existence as visible UX evidence
+- emit `none` as a normalized finding type
+- silently repair or reclassify an invalid finding

package/generated/plugins/agdf/skills/ux-intent-definition/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: ux-intent-definition
+description: Use this skill after approved UR and post-UR routing when UI/UX impact is medium or high, or low with ambiguous product semantics, to define user intent, success, working modes, effective state, visible state ownership, activation, blockers, recovery and transitions as structured PRD input; fail closed when evidence or product decisions are unresolved. This internal analysis never grants gate permission or replaces the approved PRD.
+---
+
+# ux-intent-definition
+
+## Purpose
+
+Create structured, testable UX intent input before PRD approval so implementation reviews verify an
+approved product promise instead of inventing requirements after code exists.
+
+## Runtime Contract
+
+Use:
+
+- `../../meta/contracts/gate-transition.md` for impact routing, authority and revision behavior;
+- `../../meta/contracts/quality.md` for evidence and fail-closed output discipline.
+
+## Authority
+
+This is an internal analytical skill, not a user gate. It cannot approve artefacts, grant
+implementation permission, change approved UR/PRD intent, prescribe technical design or become a
+parallel product source of truth. Proposed criteria become authoritative only when incorporated into
+and approved as PRD content. Technical storage, derivation and component ownership remain SD concerns.
+
+## Inputs
+
+- approved UR and its intent, success signal, primary action and persona/context;
+- post-UR `delivery_context`, `ui_ux_impact`, reason and required flag;
+- existing behavior/ownership evidence for Brownfield work;
+- known working modes, state semantics, activation, blockers, recovery and transitions.
+
+## Workflow
+
+1. Confirm the approved UR and routing evidence. If required evidence is absent or conflicts, block.
+2. Identify the primary user intent, observable success and primary decision/action.
+3. For every relevant working mode, define effective state and visible state types.
+4. Separate `effective_state_authority_by_mode` from
+   `primary_state_presentation_owner_by_mode`; do not turn either into technical ownership.
+5. Define activation/deactivation, blockers with visible next actions, actionable recovery (including
+   visible retry for recoverable transient failure) and relevant state transitions.
+6. Propose observable PRD acceptance criteria and identify open product questions.
+7. Return exactly one decision: `ready | blocked | not_applicable`.
+
+## Decision Rules
+
+- `ready`: every required output is reliable enough for PRD drafting.
+- `blocked`: user intent, modes, effective state, authority, activation, blockers, recovery, transitions
+  or Brownfield evidence is missing, contradictory or materially ambiguous.
+- `not_applicable`: routing proves that no relevant user-facing intent, state or recovery behavior changes.
+
+A conflict with approved UR routes to UR revision. A material product change discovered after PRD
+approval routes to PRD revision, or UR revision when intent/scope changes. Never resolve the conflict
+silently. A required blocked result prevents PRD readiness.
+
+## Output
+
+Populate each field or use an explicit, justified `not_applicable`:
+
+```text
+- decision: ready | blocked | not_applicable
+- blocking_reason:
+- primary_user_intent:
+- success_signal:
+- primary_decision_or_action:
+- working_modes:
+- effective_state_by_mode:
+- visible_state_types:
+- effective_state_authority_by_mode:
+- primary_state_presentation_owner_by_mode:
+- activation_paths:
+- blockers:
+- recovery_paths:
+- relevant_state_transitions:
+- proposed_prd_acceptance_criteria:
+- open_product_questions:
+- affected_outputs:
+- evidence:
+- missing_evidence:
+- required_next_step:
+```
+
+For `blocked`, `blocking_reason`, `open_product_questions`, `affected_outputs`, `evidence`,
+`missing_evidence` and `required_next_step` are mandatory. When durable control state exists, write
+the result to `.agdf/control/artefacts/<key>/UX_INTENT_DEFINITION.md` without a Gate or approval field.
+
+## Forbidden
+
+- invent product intent or silently choose between conflicting modes/state authorities;
+- bypass UR/PRD revision or claim PRD readiness from a blocked result;
+- add a gate, approval value or implementation permission;
+- prescribe components, persistence, endpoints, styles or other technical design;
+- treat supporting analysis as authoritative beside the approved PRD.

package/generated/plugins/agdf/skills/ux-intent-definition/help.md

@@ -0,0 +1,17 @@
+## NAME
+
+`ux-intent-definition` - define testable UX intent before PRD approval
+
+## SYNOPSIS
+
+`/ux-intent-definition` [`--help`|`-h`]
+
+## DESCRIPTION
+
+Produces structured `ready | blocked | not_applicable` PRD input for user intent, success, working
+modes, effective state, visible ownership, activation, blockers, recovery and transitions. It is an
+internal non-authorizing analysis and fails closed when product semantics or evidence are unresolved.
+
+## SEE ALSO
+
+See SKILL.md for triggers, authority, required fields and decision rules.

package/lib/cli/validation-handlers.js

@@ -24,7 +24,8 @@ export function createValidationHandlers(io = console) {
         const output = printApprovalEnvelope(report, { io, reEvaluate: () => evaluateGateCheck(options.dir, options) });
         return output.status === "blocked" ? 2 : 0;
       }
-      printGateCheckReport(report, options.json, options.statusCard, io);
+      const presentationRendered = printGateCheckReport(report, options.json, options.statusCard, io);
+      if (presentationRendered === false) return 2;
       return report.status === "blocked" ? 2 : 0;
     }],
     ["delivery-map", (options) => {