create-agdf 0.2.0 → 0.2.3

package/README.md

@@ -36,6 +36,7 @@ The generated `.agdf/control/templates/` files are reusable starting points for
 
 - `AGDF_RUN.md` for the current run dashboard
 - `MASTER_BACKLOG.md` for active delivery pointers
+- `templates/artefacts/` for durable UR, PRD, SD, TP and QA report artefact templates
 - `SOT_REGISTRY.md` for one source of truth per domain
 - `CONTEXT_GRAPH.md` for durable Brownfield findings, decisions, risks, evidence and exit criteria
 - `AGENT_QUALITY_CONTRACTS.json` for reusable block, revise and warning conditions
@@ -50,6 +51,11 @@ This writes:
 
 - `.agdf/control/AGDF_RUN.md`
 - `.agdf/control/MASTER_BACKLOG.md`
+- `.agdf/control/templates/artefacts/UR.md`
+- `.agdf/control/templates/artefacts/PRD.md`
+- `.agdf/control/templates/artefacts/SD.md`
+- `.agdf/control/templates/artefacts/TP.md`
+- `.agdf/control/templates/artefacts/QA_REPORT.md`
 - `.agdf/control/SOT_REGISTRY.md`
 - `.agdf/control/CONTEXT_GRAPH.md`
 - `.agdf/control/AGENT_QUALITY_CONTRACTS.json`

package/bin/create-agdf.js

@@ -14,6 +14,7 @@ const pluginInstallCommand = "claude plugin add arndtgold/ai-native-governance-d
 const allowedTargets = new Set(["codex", "copilot", "both", "init", "doctor", "gate-check"]);
 const agdfFragmentPath = "AGENTS.agdf.md";
 const userGateOrder = ["UR", "PRD", "SD", "TP", "QA", "UAT"];
+const durableGateArtefacts = new Set(["UR", "PRD", "SD", "TP", "QA"]);
 const codexSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.codex.skillPrefix}${skill.slug}`);
 const copilotSkillNames = pluginDefinition.skillSet.map((skill) => `${pluginDefinition.copilot.skillPrefix}${skill.slug}`);
 const codexPluginFiles = [
@@ -25,6 +26,11 @@ const codexPluginFiles = [
   join("plugins", "agdf", "control", "templates", "SOT_REGISTRY.md"),
   join("plugins", "agdf", "control", "templates", "CONTEXT_GRAPH.md"),
   join("plugins", "agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "UR.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "PRD.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "SD.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "TP.md"),
+  join("plugins", "agdf", "control", "templates", "artefacts", "QA_REPORT.md"),
   join("plugins", "agdf", "hooks", "hooks.json"),
   join("plugins", "agdf", "hooks", "session-start.sh"),
   join("plugins", "agdf", "meta", "agdf-agent-router.md"),
@@ -41,6 +47,11 @@ const controlFiles = [
   join(".agdf", "control", "templates", "SOT_REGISTRY.md"),
   join(".agdf", "control", "templates", "CONTEXT_GRAPH.md"),
   join(".agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
+  join(".agdf", "control", "templates", "artefacts", "UR.md"),
+  join(".agdf", "control", "templates", "artefacts", "PRD.md"),
+  join(".agdf", "control", "templates", "artefacts", "SD.md"),
+  join(".agdf", "control", "templates", "artefacts", "TP.md"),
+  join(".agdf", "control", "templates", "artefacts", "QA_REPORT.md"),
 ];
 const liveControlFiles = [
   {
@@ -64,6 +75,13 @@ const liveControlFiles = [
     source: join(".agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
   },
 ];
+const artefactTemplateFiles = [
+  join(".agdf", "control", "templates", "artefacts", "UR.md"),
+  join(".agdf", "control", "templates", "artefacts", "PRD.md"),
+  join(".agdf", "control", "templates", "artefacts", "SD.md"),
+  join(".agdf", "control", "templates", "artefacts", "TP.md"),
+  join(".agdf", "control", "templates", "artefacts", "QA_REPORT.md"),
+];
 const doctorRequiredFiles = [
   join(".agdf", "control", "AGDF_RUN.md"),
   join(".agdf", "control", "MASTER_BACKLOG.md"),
@@ -202,6 +220,13 @@ function generatedFilesForTarget(target, targetDir, force) {
       });
     }
 
+    for (const templatePath of artefactTemplateFiles) {
+      files.push({
+        path: templatePath,
+        content: loadAsset(templatePath),
+      });
+    }
+
     return files;
   }
 
@@ -528,6 +553,17 @@ function cleanStatusCell(value) {
   return value.replace(/^`|`$/g, "").trim();
 }
 
+function addApprovalRows(approvals, section) {
+  for (const cells of tableRows(section)) {
+    const [gate, status, evidence] = cells;
+    if (!userGateOrder.includes(gate)) continue;
+    approvals.set(gate, {
+      status: cleanStatusCell(status ?? ""),
+      evidence: evidence ?? "",
+    });
+  }
+}
+
 function readRunState(targetDir) {
   const runPath = join(".agdf", "control", "AGDF_RUN.md");
   if (!existsSync(join(targetDir, runPath))) {
@@ -537,19 +573,25 @@ function readRunState(targetDir) {
       current_gate: "",
       next_allowed_action: "",
       approvals: new Map(),
+      artefacts: new Map(),
       evidence_refs: [],
     };
   }
 
   const content = readTargetFile(targetDir, runPath);
-  const approvalsSection = content.match(/## Approvals([\s\S]*?)(?:\n## |\n# |$)/)?.[1] ?? "";
   const approvals = new Map();
-  for (const cells of tableRows(approvalsSection)) {
-    const [gate, status, evidence] = cells;
-    if (!userGateOrder.includes(gate)) continue;
-    approvals.set(gate, {
+  addApprovalRows(approvals, content.match(/## Approvals([\s\S]*?)(?:\n## |\n# |$)/)?.[1] ?? "");
+  addApprovalRows(approvals, content.match(/## Gate Checklist([\s\S]*?)(?:\n## |\n# |$)/)?.[1] ?? "");
+
+  const artefacts = new Map();
+  const artefactsSection = content.match(/## Artefacts([\s\S]*?)(?:\n## |\n# |$)/)?.[1] ?? "";
+  for (const cells of tableRows(artefactsSection)) {
+    const [type, path, status, notes] = cells;
+    if (!userGateOrder.includes(type)) continue;
+    artefacts.set(type, {
+      path: path ?? "",
       status: cleanStatusCell(status ?? ""),
-      evidence: evidence ?? "",
+      notes: notes ?? "",
     });
   }
 
@@ -570,6 +612,7 @@ function readRunState(targetDir) {
     current_gate: extractField(content, "current_gate"),
     next_allowed_action: extractField(content, "next_allowed_action"),
     approvals,
+    artefacts,
     evidence_refs,
   };
 }
@@ -593,29 +636,131 @@ function gateApprovalStatus(runState, gate) {
   return runState.approvals.get(gate)?.status ?? "";
 }
 
+function gateArtefactStatus(runState, gate) {
+  if (!userGateOrder.includes(gate)) return { status: "not_applicable", path: "" };
+  return runState.artefacts.get(gate) ?? { status: "", path: "" };
+}
+
+function isDurableGateArtefactSatisfied(runState, gate) {
+  if (!durableGateArtefacts.has(gate)) return true;
+  const artefact = gateArtefactStatus(runState, gate);
+  if (!artefact.path || isPlaceholderValue(artefact.path)) return false;
+  if (gate === "QA") return artefact.status === "pass";
+  return artefact.status === "approved";
+}
+
+function durableArtefactBlock(gate, nextGate) {
+  const label = gate === "QA" ? "QA report" : `${gate} artefact`;
+  const stablePath = gate === "QA" ? ".agdf/control/artefacts/<key>/QA_REPORT.md" : `.agdf/control/artefacts/<key>/${gate}.md`;
+  return {
+    status: "blocked",
+    current_gate: gate,
+    blocking_reason: `missing_durable_${gate.toLowerCase()}_artefact`,
+    missing_approval: "none",
+    allowed: [
+      `persist the approved ${label} in a stable artefact path such as ${stablePath}`,
+      "link the artefact from AGDF_RUN.md and MASTER_BACKLOG.md",
+      "run gate-check again",
+    ],
+    forbidden: nextGate
+      ? [`create ${nextGate}`, "create later-gate artefacts", "implement gated work", "claim QA or release readiness"]
+      : ["create later-gate artefacts", "implement gated work", "claim release readiness"],
+    next_allowed_action: `Persist the approved ${label} and link it from the AGDF control state before continuing.`,
+  };
+}
+
+function isGateSatisfied(runState, gate) {
+  const status = gateApprovalStatus(runState, gate);
+  if (status === "not_applicable") return true;
+  if (status !== "approved") return false;
+  return isDurableGateArtefactSatisfied(runState, gate);
+}
+
+function transitionDecisionForRunState(runState) {
+  if (gateApprovalStatus(runState, "UR") === "approved" && !isGateSatisfied(runState, "UR")) return durableArtefactBlock("UR", "PRD");
+
+  if (!isGateSatisfied(runState, "UR")) {
+    return {
+      status: "blocked",
+      current_gate: "UR",
+      blocking_reason: "missing_exact_approval",
+      missing_approval: "Approval: UR",
+      allowed: ["clarify user need", "formulate and persist UR", "record evidence", "request exact UR approval"],
+      forbidden: ["create PRD", "create SD", "create TP", "run Brownfield Analysis", "implement code", "claim QA or release readiness"],
+      next_allowed_action: "Clarify the user requirement, persist the UR, and request exact approval: Approval: UR",
+    };
+  }
+
+  if (gateApprovalStatus(runState, "PRD") === "approved" && !isGateSatisfied(runState, "PRD")) return durableArtefactBlock("PRD", "SD");
+
+  if (!isGateSatisfied(runState, "PRD")) {
+    return {
+      status: "open",
+      current_gate: "PRD",
+      blocking_reason: "none",
+      missing_approval: "Approval: PRD",
+      allowed: ["draft or refine PRD", "define scope", "define acceptance criteria", "define non-goals", "request exact PRD approval"],
+      forbidden: ["create SD", "create TP", "run Brownfield Analysis as implementation preparation", "implement code", "claim QA or release readiness"],
+      next_allowed_action: "Draft or refine the PRD; do not implement before PRD, SD and TP are approved.",
+    };
+  }
+
+  if (gateApprovalStatus(runState, "SD") === "approved" && !isGateSatisfied(runState, "SD")) return durableArtefactBlock("SD", "TP");
+
+  if (!isGateSatisfied(runState, "SD")) {
+    return {
+      status: "open",
+      current_gate: "SD",
+      blocking_reason: "none",
+      missing_approval: "Approval: SD",
+      allowed: ["draft or refine Solution Design", "define architecture", "define ownership", "request exact SD approval"],
+      forbidden: ["create TP", "implement code", "claim QA or release readiness"],
+      next_allowed_action: "Draft or refine the Solution Design; do not implement before SD and TP are approved.",
+    };
+  }
+
+  if (gateApprovalStatus(runState, "TP") === "approved" && !isGateSatisfied(runState, "TP")) return durableArtefactBlock("TP", "Brownfield Analysis");
+
+  if (!isGateSatisfied(runState, "TP")) {
+    return {
+      status: "open",
+      current_gate: "TP",
+      blocking_reason: "none",
+      missing_approval: "Approval: TP",
+      allowed: ["draft or refine Task/Test Plan", "define task IDs", "define test evidence", "request exact TP approval"],
+      forbidden: ["implement code", "claim QA or release readiness"],
+      next_allowed_action: "Draft or refine the Task/Test Plan; do not implement before TP is approved.",
+    };
+  }
+
+  if (gateApprovalStatus(runState, "QA") === "approved" && !isGateSatisfied(runState, "QA")) return durableArtefactBlock("QA", "UAT");
+
+  return {
+    status: "open",
+    current_gate: "Brownfield Analysis",
+    blocking_reason: "none",
+    missing_approval: "none",
+    allowed: ["run Brownfield Analysis for the approved TP scope", "verify existing owners, reuse paths and regression risks"],
+    forbidden: ["implement before Brownfield evidence supports the approved TP path", "claim QA or release readiness"],
+    next_allowed_action: "Run Brownfield Analysis for the approved TP scope before CD+Tests.",
+  };
+}
+
 function evaluateGateCheck(targetDir) {
   const doctorReport = evaluateDoctor(targetDir);
   const runState = readRunState(targetDir);
-  const fallbackGate = firstUnapprovedGate(runState.approvals);
-  const currentGate = normalizeCurrentGate(runState.current_gate, fallbackGate);
-  const currentApprovalStatus = gateApprovalStatus(runState, currentGate);
+  const transitionDecision = transitionDecisionForRunState(runState);
   const doctorBlocker = doctorReport.findings.find((finding) => finding.severity === "block");
   const doctorRevise = doctorReport.findings.find((finding) => finding.severity === "revise");
 
-  let status = "open";
-  let blockingReason = "none";
-  let missingApproval = "none";
-  let allowed = [
-    "continue with the documented next allowed action",
-    "update evidence when new facts are observed",
-    "run doctor or gate-check again after control changes",
-  ];
-  let forbidden = [
-    "bypass the documented gate state",
-    "treat warnings as resolved without evidence",
-  ];
+  let status = transitionDecision.status;
+  let currentGate = transitionDecision.current_gate;
+  let blockingReason = transitionDecision.blocking_reason;
+  let missingApproval = transitionDecision.missing_approval;
+  let allowed = transitionDecision.allowed;
+  let forbidden = transitionDecision.forbidden;
   let nextAllowedAction = isPlaceholderValue(runState.next_allowed_action)
-    ? "Continue with the current documented gate only after setting next_allowed_action."
+    ? transitionDecision.next_allowed_action
     : runState.next_allowed_action;
 
   if (doctorBlocker) {
@@ -627,16 +772,9 @@ function evaluateGateCheck(targetDir) {
   } else if (doctorRevise) {
     status = "blocked";
     blockingReason = doctorRevise.code;
-    allowed = ["repair the incomplete control state", "run doctor again"];
+    allowed = [...new Set(["repair the incomplete control state", ...transitionDecision.allowed, "run doctor again"])];
     forbidden = ["continue governed delivery", "create later-gate artefacts", "implement gated work"];
     nextAllowedAction = doctorRevise.next_step;
-  } else if (userGateOrder.includes(currentGate) && currentApprovalStatus !== "approved" && currentApprovalStatus !== "not_applicable") {
-    status = "blocked";
-    blockingReason = "missing_exact_approval";
-    missingApproval = `Approval: ${currentGate}`;
-    allowed = ["clarify the current gate", "record evidence", "write OR-lite status", "request exact approval"];
-    forbidden = ["create later-gate artefacts", "implement gated work", "mark QA or UAT as passed"];
-    nextAllowedAction = `Request exact approval: Approval: ${currentGate}`;
   }
 
   return {

package/generated/.agdf/control/README.md

@@ -10,6 +10,11 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 |---|---|
 | `templates/AGDF_RUN.md` | Template for current run state: mode, gate, approvals, evidence, risks, next allowed action |
 | `templates/MASTER_BACKLOG.md` | Template for the living backlog pointer: active initiatives and current UR/PRD/SD/TP artefacts |
+| `templates/artefacts/UR.md` | Template for the durable user requirement artefact of a work item |
+| `templates/artefacts/PRD.md` | Template for the durable product requirements artefact |
+| `templates/artefacts/SD.md` | Template for the durable solution design artefact |
+| `templates/artefacts/TP.md` | Template for the durable task and test plan artefact |
+| `templates/artefacts/QA_REPORT.md` | Template for the durable QA decision report |
 | `templates/SOT_REGISTRY.md` | Template for the source-of-truth registry: one primary owner per domain |
 | `templates/CONTEXT_GRAPH.md` | Template for project memory: durable decisions, Brownfield findings, risks, evidence and exit criteria |
 | `templates/AGENT_QUALITY_CONTRACTS.json` | Template for machine-readable warning, revise and block contracts for review and QA |
@@ -21,6 +26,13 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
   control/
     AGDF_RUN.md
     MASTER_BACKLOG.md
+    artefacts/
+      <work-item>/
+        UR.md
+        PRD.md
+        SD.md
+        TP.md
+        QA_REPORT.md
     SOT_REGISTRY.md
     CONTEXT_GRAPH.md
     AGENT_QUALITY_CONTRACTS.json
@@ -49,6 +61,7 @@ npm create agdf@latest gate-check --json
 
 - `AGDF_RUN.md` is the current run dashboard.
 - `MASTER_BACKLOG.md` points to active delivery work; detailed artefacts live beside the work item.
+- UR, PRD, SD, TP and QA decisions require durable artefacts or links to the authoritative repository source of truth before the next gate can open.
 - `SOT_REGISTRY.md` decides which document owns which domain.
 - `CONTEXT_GRAPH.md` records durable project knowledge only when it has evidence and an exit criterion.
 - `AGENT_QUALITY_CONTRACTS.json` names reusable block, revise and warning conditions.

package/generated/.agdf/control/templates/MASTER_BACKLOG.md

@@ -4,11 +4,15 @@ This file is the living control pointer for active AGDF delivery work. Detailed
 
 ## Rules
 
-1. Keep only steering-relevant work in `Active Backlog`.
-2. Every active item has exactly one current spec pointer.
-3. Historical artefacts remain linkable but do not override the current pointer.
-4. If an item is superseded, mark the replacement.
-5. If active work grows beyond roughly ten items, triage the backlog.
+1. New product semantics, functional change or user-visible behaviour change starts as a new UR draft in a stable local artefact path, for example `.agdf/control/artefacts/<key>/UR.md`, unless an authoritative repository SoT already exists and is linked here.
+2. `Approval: UR` adds or updates exactly one steering row with a link to the UR.
+3. PRD, SD, TP and QA report artefacts are created for the same work item after the previous gate is approved.
+4. `Approval: PRD`, `Approval: SD`, `Approval: TP` and `Approval: QA` require the corresponding durable artefact or linked repository SoT before the next gate can open.
+5. Keep only steering-relevant work in `Active Backlog`.
+6. Every active item has exactly one current spec pointer.
+7. Historical artefacts remain linkable but do not override the current pointer.
+8. If an item is superseded, mark the replacement.
+9. If active work grows beyond roughly ten items, triage the backlog.
 
 ## Active Backlog
 

package/generated/.agdf/control/templates/artefacts/PRD.md

@@ -0,0 +1,42 @@
+# PRD: <Title>
+
+Status: draft
+Gate: PRD
+Gate approval: open
+Based on: UR
+Date:
+Owner:
+
+## 1. Product Scope
+
+What exactly must be delivered?
+
+## 2. Acceptance Criteria
+
+Which observable outcomes must be true?
+
+## 3. Non-Goals
+
+What remains out of scope?
+
+## 4. Users And Roles
+
+Who is affected and who decides?
+
+## 5. Constraints
+
+Which business, operational, legal, security or compatibility constraints apply?
+
+## 6. Evidence Requirements
+
+Which evidence must later support QA?
+
+## 7. Risks And Open Questions
+
+Which questions must SD, TP or Brownfield Analysis clarify later?
+
+## 8. Next Step
+
+Review this PRD and approve only with:
+
+`Approval: PRD`

package/generated/.agdf/control/templates/artefacts/QA_REPORT.md

@@ -0,0 +1,38 @@
+# QA Report: <Title>
+
+Status: draft
+Gate: QA
+Gate approval: open
+Based on: TP, implementation evidence, task-plan review
+Date:
+Owner:
+
+## 1. QA Decision
+
+Decision: `pass | revise | block`
+
+## 2. TP Coverage
+
+Which TP tasks are fully done, partially done or not done?
+
+## 3. Evidence
+
+Which tests, logs, diffs, reviews or observations support the decision?
+
+## 4. Missing Evidence
+
+What remains unverified?
+
+## 5. Risks
+
+Which risks remain and what is their impact?
+
+## 6. Required Next Step
+
+What is the next permitted action?
+
+## 7. Gate Approval
+
+Approve this QA decision only with:
+
+`Approval: QA`

package/generated/.agdf/control/templates/artefacts/SD.md

@@ -0,0 +1,42 @@
+# SD: <Title>
+
+Status: draft
+Gate: SD
+Gate approval: open
+Based on: PRD
+Date:
+Owner:
+
+## 1. Solution Overview
+
+How will the approved PRD be solved?
+
+## 2. Ownership And Source Of Truth
+
+Which existing modules, documents, services or owners remain authoritative?
+
+## 3. Architecture Decisions
+
+Which design decisions are binding for implementation?
+
+## 4. Integration Points
+
+Which APIs, data flows, UI surfaces, jobs, queues or external systems are affected?
+
+## 5. Constraints And Compatibility
+
+Which constraints must implementation preserve?
+
+## 6. Test And Evidence Strategy
+
+Which evidence must TP and QA later collect?
+
+## 7. Risks And Open Questions
+
+Which risks remain before task planning?
+
+## 8. Next Step
+
+Review this solution design and approve only with:
+
+`Approval: SD`

package/generated/.agdf/control/templates/artefacts/TP.md

@@ -0,0 +1,36 @@
+# TP: <Title>
+
+Status: draft
+Gate: TP
+Gate approval: open
+Based on: SD
+Date:
+Owner:
+
+## 1. Task List
+
+| task_id | Task | Acceptance mapping | Evidence required |
+|---|---|---|---|
+| T1 |  |  |  |
+
+## 2. Test Plan
+
+Which automated, manual or inspection checks must run?
+
+## 3. Brownfield Scope
+
+Which existing owners, modules or artefacts must be inspected before implementation?
+
+## 4. Out Of Scope
+
+Which implementation work is explicitly not part of this TP?
+
+## 5. Risks And Blockers
+
+Which risks must block, revise or warn later QA?
+
+## 6. Next Step
+
+Review this task and test plan and approve only with:
+
+`Approval: TP`

package/generated/.agdf/control/templates/artefacts/UR.md

@@ -0,0 +1,41 @@
+# UR: <Title>
+
+Status: draft
+Gate: UR
+Gate approval: open
+Date:
+Owner:
+
+## 1. Problem
+
+What user, business or operational problem should be solved?
+
+## 2. Goal
+
+What outcome should become possible?
+
+## 3. Scope
+
+What is included in this first slice?
+
+## 4. Non-Goals
+
+What is explicitly not part of this UR?
+
+## 5. Acceptance Signals
+
+How will we know the need is clear enough for PRD?
+
+## 6. Existing Source Of Truth
+
+Which existing repository artefacts, docs, code paths or decisions must be respected?
+
+## 7. Risks And Unknowns
+
+Which questions must PRD, SD or Brownfield Analysis clarify later?
+
+## 8. Next Step
+
+Review this UR and approve only with:
+
+`Approval: UR`

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

@@ -1,6 +1,6 @@
 ---
 name: agdf-brownfield-analysis
-description: Use this skill before implementation in an existing codebase, especially for feature extensions, bug fixes, refactorings, or changes to existing modules. It analyzes existing artefacts, current coverage, reuse strategy, risks, and the minimal clean implementation path. Use it before CD+Tests.
+description: Use this skill after gate-check or live AGDF control state confirms that implementation preparation is allowed, and before non-trivial implementation in an existing codebase. It analyzes existing artefacts, current coverage, reuse strategy, risks, and the minimal clean implementation path. Do not use it as the first AGDF skill for a fresh "I want to build/change X" prompt when approval, scope, or next allowed action is unclear.
 ---
 
 # brownfield-analysis
@@ -38,6 +38,7 @@ Brownfield-specific output must make evidence, missing existing-system view, par
 12. Specification archive migrations must follow the archive index if present.
 
 ## When To Use
+- after `agdf-gate-check` permits implementation preparation or live `.agdf/control/AGDF_RUN.md` already names Brownfield Analysis as the next allowed action
 - before `CD+Tests`
 - before changes to an existing repository
 - bug fixes in existing modules
@@ -58,6 +59,7 @@ Use what is available:
 - repository conventions
 
 If inputs are missing, work only from observable evidence and mark gaps explicitly.
+If gate status, approval, scope or next allowed action is unclear, stop and route to `agdf-gate-check` instead of recommending or starting implementation.
 
 ## Workflow
 1. Identify affected tasks and scope.

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

@@ -1,6 +1,6 @@
 ---
 name: agdf-gate-check
-description: Use this skill when the active gate is unclear, when a later-gate artefact is requested, when an exact approval may be missing, or when the next permissible step must be determined. Use it before creating formal artefacts in Structured Delivery and whenever implicit consent might be mistaken for approval.
+description: Use this skill as the default first AGDF skill for any new build, change, extension, refactor, feature, CLI, app, fix with product semantics, Structured Delivery request, unclear approval, later-gate artefact request, or unclear next permissible step. Use it before brownfield-analysis, implementation, formal artefacts, QA, or release when approval/evidence/next action is not already explicit.
 ---
 
 # gate-check
@@ -43,6 +43,9 @@ The CLI report is evidence for this skill, not a second rule system. If the repo
 7. Internal process steps are not user approval gates.
 8. OR-lite is allowed if it does not leak blocked content.
 9. SoT/runtime/product-semantics drift can trigger an early product gate, usually `UR`.
+10. Approval of one user gate permits work on the next gate artefact only; it never skips directly to implementation.
+11. New product semantics, functional change or user-visible behaviour change requires a durable UR in `.agdf/control/` or a linked authoritative repository SoT before PRD, SD, TP, Brownfield Analysis or implementation.
+12. Approval text and durable artefact presence are separate requirements for UR, PRD, SD, TP and QA report decisions. Approval text without the corresponding persisted or linked artefact keeps the current gate at that gate.
 
 ## Gate Order
 User gates:
@@ -53,7 +56,25 @@ Internal mandatory steps:
 
 `Brownfield Analysis -> CD+Tests -> CR -> OR`
 
+## Gate Transitions
+
+Use this transition model for Structured Delivery:
+
+| State | Current gate or step | Allowed | Forbidden | Missing approval |
+|---|---|---|---|---|
+| No approved UR | `UR` | clarify user need, formulate and persist UR, request `Approval: UR` | PRD, SD, TP, Brownfield Analysis, implementation, QA, release | `Approval: UR` |
+| `UR` approved and UR artefact persisted or linked, PRD missing or draft | `PRD` | draft/refine PRD, define scope, acceptance criteria and non-goals, persist/link PRD, request `Approval: PRD` | SD, TP, Brownfield Analysis, implementation, QA, release | `Approval: PRD` |
+| `PRD` approved and PRD artefact persisted or linked, SD missing or draft | `SD` | draft/refine Solution Design, ownership and architecture, persist/link SD, request `Approval: SD` | TP, implementation, QA, release | `Approval: SD` |
+| `SD` approved and SD artefact persisted or linked, TP missing or draft | `TP` | draft/refine Task/Test Plan, task IDs, evidence plan, persist/link TP, request `Approval: TP` | implementation, QA, release | `Approval: TP` |
+| `TP` approved and TP artefact persisted or linked, Brownfield missing | `Brownfield Analysis` | run Brownfield Analysis for approved TP scope | implementation, QA, release | none |
+| Brownfield passed for approved TP | `CD+Tests` | implement approved TP tasks and run tests | QA pass, UAT, release | none |
+| `QA` approved but QA report missing or not pass | `QA` | persist/link QA report with `pass` decision or revise/block evidence | UAT, release | none |
+
+If `Approval: UR` is present, do not say implementation is the next step.
+The next step is PRD work unless the run is explicitly classified as a Quick Task with no new product semantics and no formal artefact requirement.
+
 ## When To Use
+- new user intent to build, add, change, extend, refactor or deliver something
 - Structured Delivery before first artefact creation
 - unclear current gate
 - user says "continue" or similar without exact approval
@@ -63,6 +84,9 @@ Internal mandatory steps:
 
 Not required for simple Quick Tasks without new product scope and without formal artefacts.
 
+For a fresh prompt such as "I want to build a small CLI", use this skill first.
+Do not route directly to `agdf-brownfield-analysis` or implementation until this skill or live AGDF control state says that implementation preparation is the next allowed action.
+
 ## Inputs
 Use what is available:
 
@@ -82,6 +106,7 @@ If a status is not explicit, do not assume it is satisfied.
 4. Derive allowed and forbidden outputs.
 5. Name the exact missing approval, if any.
 6. If consent was only implicit, say it is not yet approval and provide the exact formula.
+7. Ensure the next step follows the gate transition table. In particular, never jump from `Approval: UR` to implementation.
 
 ## Output
 Keep the result short and operational:
@@ -99,6 +124,9 @@ This skill must not:
 - create PRD before UR approval
 - create SD before PRD approval
 - create TP while earlier gates block
+- suggest implementation immediately after `Approval: UR`
+- suggest implementation immediately after `Approval: PRD`
+- suggest implementation immediately after `Approval: SD`
 - perform full Brownfield Analysis unless explicitly requested
 - provide implementation snippets while implementation is gated
 - present QA or UAT as passed without evidence

package/generated/.github/skills/agdf-runtime-contract.md

@@ -12,6 +12,8 @@ It is the operational reference for skill outputs, but it is not a second copy o
 
 Quick Task Mode must not become ritual gate overhead.
 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.
 
 ## Gate Rules
 
@@ -21,6 +23,12 @@ Structured Delivery must not bypass missing approvals.
 - Legacy alias: `Freigabe: <GateName>` may be accepted when reviewing older German runs, but all new outputs must use `Approval: <GateName>`.
 - Implicit consent is not approval.
 - The earliest blocking gate wins.
+- For UR, PRD, SD, TP and QA, approval and durable artefact presence are separate requirements. A gate is not satisfied by approval text alone when its artefact is missing from `.agdf/control/` or not linked to the authoritative repository SoT.
+- Approval of one user gate permits work on the next gate artefact only. It does not permit implementation unless the approved gate is `TP` and required internal implementation prerequisites are satisfied.
+- `Approval: UR` permits PRD drafting, not implementation.
+- `Approval: PRD` permits Solution Design drafting, not implementation.
+- `Approval: SD` permits Task/Test Plan drafting, not implementation.
+- `Approval: TP` permits Brownfield Analysis and then CD+Tests when Brownfield evidence supports it.
 - `CD+Tests` is implementation and test status only, not a delivery signal.
 - `agdf-code-review` standardizes the mandatory `CR` step, but does not replace QA.
 - `agdf-qa-gate` decides final `pass | revise | block`.

package/generated/AGENTS.md

@@ -23,27 +23,34 @@ Therefore generated Copilot skill names use the AGDF prefix:
 Do not remove that prefix in Copilot-facing repository skills.
 Codex and Claude Code plugin surfaces use the same canonical router with unprefixed skill names because their plugin namespace already carries `agdf`.
 ## Mode Selection
+Default entry rule: a new user intent to build, add, change, extend, refactor or otherwise deliver something starts with `agdf-gate-check` unless it is clearly only a question, explanation, local inspection, or explicitly scoped review.
+
 Use Quick Task Mode for questions, small reviews, local debugging and narrow fixes without new product semantics.
 
 Use Structured Delivery Mode for new capabilities, architecture, policy, persistence, release-critical work, formal artefacts or explicit approvals.
 
+Any new product semantics, functional change or user-visible behaviour change requires a durable UR first.
+Persist it in `.agdf/control/` or link it from there to the target repository's authoritative source of truth before PRD, SD, TP, Brownfield Analysis or implementation.
+Treat approval text and durable artefact presence as separate checks for UR, PRD, SD, TP and QA report decisions.
+
 Quick Task Mode must still cite evidence and close with a concrete result.
 Structured Delivery Mode must respect gates, reviews and closeout discipline.
 
 ## Skill Routing
 | Skill | Use For | Boundary |
 |---|---|---|
-| `agdf-brownfield-analysis` | before non-trivial implementation in existing systems | clarifies reuse, owners and risks |
+| `agdf-brownfield-analysis` | after gate-check permits implementation preparation, before non-trivial changes in existing systems | clarifies reuse, owners and risks; never bypasses gate-check |
 | `agdf-clean-implementation-review` | inspect workarounds, fallbacks, parallel structures or symptom fixes | not a TP or QA substitute |
 | `agdf-code-review` | mandatory CR step after code changes, focused on defects, regression and security findings | does not replace TP review, clean review or QA |
 | `agdf-delivery-closeout` | commit/PR-near handoff after QA/OR/UAT | never performs VCS actions automatically |
-| `agdf-gate-check` | unclear approval, Structured Delivery, later-gate artefact requested | does not create later artefacts |
+| `agdf-gate-check` | new build/change intent, unclear approval, Structured Delivery, later-gate artefact requested | does not create later artefacts |
 | `agdf-qa-gate` | final QA decision | only instance for `pass | revise | block` |
 | `agdf-release-or` | auditable closeout for every relevant run | not a QA substitute |
 | `agdf-task-plan-review` | after implementation and before QA, verify TP coverage | no final QA decision |
 
 Select exactly one primary skill first.
 Add more only when they cover a distinct concrete risk dimension.
+Do not choose `agdf-brownfield-analysis` as the first primary skill for a fresh "I want to build/change X" prompt unless `agdf-gate-check` or existing live AGDF control state already makes implementation preparation the next allowed action.
 
 ## Runtime Contract
 For repeated output, gate, Quality Contract and Context Graph rules, use:

package/generated/plugins/agdf/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",
   "author": {
     "name": "AI-native Governance & Delivery Framework",

package/generated/plugins/agdf/control/README.md

@@ -10,6 +10,11 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 |---|---|
 | `templates/AGDF_RUN.md` | Template for current run state: mode, gate, approvals, evidence, risks, next allowed action |
 | `templates/MASTER_BACKLOG.md` | Template for the living backlog pointer: active initiatives and current UR/PRD/SD/TP artefacts |
+| `templates/artefacts/UR.md` | Template for the durable user requirement artefact of a work item |
+| `templates/artefacts/PRD.md` | Template for the durable product requirements artefact |
+| `templates/artefacts/SD.md` | Template for the durable solution design artefact |
+| `templates/artefacts/TP.md` | Template for the durable task and test plan artefact |
+| `templates/artefacts/QA_REPORT.md` | Template for the durable QA decision report |
 | `templates/SOT_REGISTRY.md` | Template for the source-of-truth registry: one primary owner per domain |
 | `templates/CONTEXT_GRAPH.md` | Template for project memory: durable decisions, Brownfield findings, risks, evidence and exit criteria |
 | `templates/AGENT_QUALITY_CONTRACTS.json` | Template for machine-readable warning, revise and block contracts for review and QA |
@@ -21,6 +26,13 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
   control/
     AGDF_RUN.md
     MASTER_BACKLOG.md
+    artefacts/
+      <work-item>/
+        UR.md
+        PRD.md
+        SD.md
+        TP.md
+        QA_REPORT.md
     SOT_REGISTRY.md
     CONTEXT_GRAPH.md
     AGENT_QUALITY_CONTRACTS.json
@@ -49,6 +61,7 @@ npm create agdf@latest gate-check --json
 
 - `AGDF_RUN.md` is the current run dashboard.
 - `MASTER_BACKLOG.md` points to active delivery work; detailed artefacts live beside the work item.
+- UR, PRD, SD, TP and QA decisions require durable artefacts or links to the authoritative repository source of truth before the next gate can open.
 - `SOT_REGISTRY.md` decides which document owns which domain.
 - `CONTEXT_GRAPH.md` records durable project knowledge only when it has evidence and an exit criterion.
 - `AGENT_QUALITY_CONTRACTS.json` names reusable block, revise and warning conditions.

package/generated/plugins/agdf/control/templates/MASTER_BACKLOG.md

@@ -4,11 +4,15 @@ This file is the living control pointer for active AGDF delivery work. Detailed
 
 ## Rules
 
-1. Keep only steering-relevant work in `Active Backlog`.
-2. Every active item has exactly one current spec pointer.
-3. Historical artefacts remain linkable but do not override the current pointer.
-4. If an item is superseded, mark the replacement.
-5. If active work grows beyond roughly ten items, triage the backlog.
+1. New product semantics, functional change or user-visible behaviour change starts as a new UR draft in a stable local artefact path, for example `.agdf/control/artefacts/<key>/UR.md`, unless an authoritative repository SoT already exists and is linked here.
+2. `Approval: UR` adds or updates exactly one steering row with a link to the UR.
+3. PRD, SD, TP and QA report artefacts are created for the same work item after the previous gate is approved.
+4. `Approval: PRD`, `Approval: SD`, `Approval: TP` and `Approval: QA` require the corresponding durable artefact or linked repository SoT before the next gate can open.
+5. Keep only steering-relevant work in `Active Backlog`.
+6. Every active item has exactly one current spec pointer.
+7. Historical artefacts remain linkable but do not override the current pointer.
+8. If an item is superseded, mark the replacement.
+9. If active work grows beyond roughly ten items, triage the backlog.
 
 ## Active Backlog
 

package/generated/plugins/agdf/control/templates/artefacts/PRD.md

@@ -0,0 +1,42 @@
+# PRD: <Title>
+
+Status: draft
+Gate: PRD
+Gate approval: open
+Based on: UR
+Date:
+Owner:
+
+## 1. Product Scope
+
+What exactly must be delivered?
+
+## 2. Acceptance Criteria
+
+Which observable outcomes must be true?
+
+## 3. Non-Goals
+
+What remains out of scope?
+
+## 4. Users And Roles
+
+Who is affected and who decides?
+
+## 5. Constraints
+
+Which business, operational, legal, security or compatibility constraints apply?
+
+## 6. Evidence Requirements
+
+Which evidence must later support QA?
+
+## 7. Risks And Open Questions
+
+Which questions must SD, TP or Brownfield Analysis clarify later?
+
+## 8. Next Step
+
+Review this PRD and approve only with:
+
+`Approval: PRD`

package/generated/plugins/agdf/control/templates/artefacts/QA_REPORT.md

@@ -0,0 +1,38 @@
+# QA Report: <Title>
+
+Status: draft
+Gate: QA
+Gate approval: open
+Based on: TP, implementation evidence, task-plan review
+Date:
+Owner:
+
+## 1. QA Decision
+
+Decision: `pass | revise | block`
+
+## 2. TP Coverage
+
+Which TP tasks are fully done, partially done or not done?
+
+## 3. Evidence
+
+Which tests, logs, diffs, reviews or observations support the decision?
+
+## 4. Missing Evidence
+
+What remains unverified?
+
+## 5. Risks
+
+Which risks remain and what is their impact?
+
+## 6. Required Next Step
+
+What is the next permitted action?
+
+## 7. Gate Approval
+
+Approve this QA decision only with:
+
+`Approval: QA`

package/generated/plugins/agdf/control/templates/artefacts/SD.md

@@ -0,0 +1,42 @@
+# SD: <Title>
+
+Status: draft
+Gate: SD
+Gate approval: open
+Based on: PRD
+Date:
+Owner:
+
+## 1. Solution Overview
+
+How will the approved PRD be solved?
+
+## 2. Ownership And Source Of Truth
+
+Which existing modules, documents, services or owners remain authoritative?
+
+## 3. Architecture Decisions
+
+Which design decisions are binding for implementation?
+
+## 4. Integration Points
+
+Which APIs, data flows, UI surfaces, jobs, queues or external systems are affected?
+
+## 5. Constraints And Compatibility
+
+Which constraints must implementation preserve?
+
+## 6. Test And Evidence Strategy
+
+Which evidence must TP and QA later collect?
+
+## 7. Risks And Open Questions
+
+Which risks remain before task planning?
+
+## 8. Next Step
+
+Review this solution design and approve only with:
+
+`Approval: SD`

package/generated/plugins/agdf/control/templates/artefacts/TP.md

@@ -0,0 +1,36 @@
+# TP: <Title>
+
+Status: draft
+Gate: TP
+Gate approval: open
+Based on: SD
+Date:
+Owner:
+
+## 1. Task List
+
+| task_id | Task | Acceptance mapping | Evidence required |
+|---|---|---|---|
+| T1 |  |  |  |
+
+## 2. Test Plan
+
+Which automated, manual or inspection checks must run?
+
+## 3. Brownfield Scope
+
+Which existing owners, modules or artefacts must be inspected before implementation?
+
+## 4. Out Of Scope
+
+Which implementation work is explicitly not part of this TP?
+
+## 5. Risks And Blockers
+
+Which risks must block, revise or warn later QA?
+
+## 6. Next Step
+
+Review this task and test plan and approve only with:
+
+`Approval: TP`

package/generated/plugins/agdf/control/templates/artefacts/UR.md

@@ -0,0 +1,41 @@
+# UR: <Title>
+
+Status: draft
+Gate: UR
+Gate approval: open
+Date:
+Owner:
+
+## 1. Problem
+
+What user, business or operational problem should be solved?
+
+## 2. Goal
+
+What outcome should become possible?
+
+## 3. Scope
+
+What is included in this first slice?
+
+## 4. Non-Goals
+
+What is explicitly not part of this UR?
+
+## 5. Acceptance Signals
+
+How will we know the need is clear enough for PRD?
+
+## 6. Existing Source Of Truth
+
+Which existing repository artefacts, docs, code paths or decisions must be respected?
+
+## 7. Risks And Unknowns
+
+Which questions must PRD, SD or Brownfield Analysis clarify later?
+
+## 8. Next Step
+
+Review this UR and approve only with:
+
+`Approval: UR`

package/generated/plugins/agdf/meta/agdf-agent-router.md

@@ -24,27 +24,34 @@ Do not duplicate the plugin namespace in Codex or Claude Code plugin skill names
 That `agdf-` prefix is reserved for GitHub Copilot repository skills, where no plugin namespace exists.
 
 ## Mode Selection
+Default entry rule: a new user intent to build, add, change, extend, refactor or otherwise deliver something starts with `gate-check` unless it is clearly only a question, explanation, local inspection, or explicitly scoped review.
+
 Use Quick Task Mode for questions, small reviews, local debugging and narrow fixes without new product semantics.
 
 Use Structured Delivery Mode for new capabilities, architecture, policy, persistence, release-critical work, formal artefacts or explicit approvals.
 
+Any new product semantics, functional change or user-visible behaviour change requires a durable UR first.
+Persist it in `.agdf/control/` or link it from there to the target repository's authoritative source of truth before PRD, SD, TP, Brownfield Analysis or implementation.
+Treat approval text and durable artefact presence as separate checks for UR, PRD, SD, TP and QA report decisions.
+
 Quick Task Mode must still cite evidence and close with a concrete result.
 Structured Delivery Mode must respect gates, reviews and closeout discipline.
 
 ## Skill Routing
 | Skill | Use For | Boundary |
 |---|---|---|
-| `brownfield-analysis` | before non-trivial implementation in existing systems | clarifies reuse, owners and risks |
+| `brownfield-analysis` | after gate-check permits implementation preparation, before non-trivial changes in existing systems | clarifies reuse, owners and risks; never bypasses gate-check |
 | `clean-implementation-review` | inspect workarounds, fallbacks, parallel structures or symptom fixes | not a TP or QA substitute |
 | `code-review` | mandatory CR step after code changes, focused on defects, regression and security findings | does not replace TP review, clean review or QA |
 | `delivery-closeout` | commit/PR-near handoff after QA/OR/UAT | never performs VCS actions automatically |
-| `gate-check` | unclear approval, Structured Delivery, later-gate artefact requested | does not create later artefacts |
+| `gate-check` | new build/change intent, unclear approval, Structured Delivery, later-gate artefact requested | does not create later artefacts |
 | `qa-gate` | final QA decision | only instance for `pass | revise | block` |
 | `release-or` | auditable closeout for every relevant run | not a QA substitute |
 | `task-plan-review` | after implementation and before QA, verify TP coverage | no final QA decision |
 
 Select exactly one primary skill first.
 Add more only when they cover a distinct concrete risk dimension.
+Do not choose `brownfield-analysis` as the first primary skill for a fresh "I want to build/change X" prompt unless `gate-check` or existing live AGDF control state already makes implementation preparation the next allowed action.
 
 ## Runtime Contract
 For repeated output, gate, Quality Contract and Context Graph rules, use:

package/generated/plugins/agdf/meta/agdf-constitution.md

@@ -105,7 +105,15 @@ Transform transient reasoning into durable knowledge.
 
 Create or update artefacts whenever they improve traceability or future work.
 
-Typical artefacts include:
+For new product semantics, functional change, user-visible behaviour, policy,
+persistence, architecture, release-critical work or any Structured Delivery run,
+a User Requirement (UR) is mandatory.
+
+UR, PRD, SD, TP and QA report approvals require durable artefacts in the target
+repository's AGDF control state or links from that control state to the
+repository's authoritative source of truth before the next gate can open.
+
+Artefacts include:
 
 * User Requirements
 * Product Requirements Docs (PRD)

package/generated/plugins/agdf/meta/agdf-plugin.definition.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "AI-native Governance & Delivery Framework",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",
@@ -42,8 +42,8 @@
   "skillSet": [
     {
       "slug": "brownfield-analysis",
-      "useFor": "before non-trivial implementation in existing systems",
-      "boundary": "clarifies reuse, owners and risks"
+      "useFor": "after gate-check permits implementation preparation, before non-trivial changes in existing systems",
+      "boundary": "clarifies reuse, owners and risks; never bypasses gate-check"
     },
     {
       "slug": "clean-implementation-review",
@@ -62,7 +62,7 @@
     },
     {
       "slug": "gate-check",
-      "useFor": "unclear approval, Structured Delivery, later-gate artefact requested",
+      "useFor": "new build/change intent, unclear approval, Structured Delivery, later-gate artefact requested",
       "boundary": "does not create later artefacts"
     },
     {

package/generated/plugins/agdf/meta/agdf-runtime-contract.md

@@ -12,6 +12,8 @@ It is the operational reference for skill outputs, but it is not a second copy o
 
 Quick Task Mode must not become ritual gate overhead.
 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.
 
 ## Gate Rules
 
@@ -21,6 +23,12 @@ Structured Delivery must not bypass missing approvals.
 - Legacy alias: `Freigabe: <GateName>` may be accepted when reviewing older German runs, but all new outputs must use `Approval: <GateName>`.
 - Implicit consent is not approval.
 - The earliest blocking gate wins.
+- For UR, PRD, SD, TP and QA, approval and durable artefact presence are separate requirements. A gate is not satisfied by approval text alone when its artefact is missing from `.agdf/control/` or not linked to the authoritative repository SoT.
+- Approval of one user gate permits work on the next gate artefact only. It does not permit implementation unless the approved gate is `TP` and required internal implementation prerequisites are satisfied.
+- `Approval: UR` permits PRD drafting, not implementation.
+- `Approval: PRD` permits Solution Design drafting, not implementation.
+- `Approval: SD` permits Task/Test Plan drafting, not implementation.
+- `Approval: TP` permits Brownfield Analysis and then CD+Tests when Brownfield evidence supports it.
 - `CD+Tests` is implementation and test status only, not a delivery signal.
 - `code-review` standardizes the mandatory `CR` step, but does not replace QA.
 - `qa-gate` decides final `pass | revise | block`.

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

@@ -1,6 +1,6 @@
 ---
 name: brownfield-analysis
-description: Use this skill before implementation in an existing codebase, especially for feature extensions, bug fixes, refactorings, or changes to existing modules. It analyzes existing artefacts, current coverage, reuse strategy, risks, and the minimal clean implementation path. Use it before CD+Tests.
+description: Use this skill after gate-check or live AGDF control state confirms that implementation preparation is allowed, and before non-trivial implementation in an existing codebase. It analyzes existing artefacts, current coverage, reuse strategy, risks, and the minimal clean implementation path. Do not use it as the first AGDF skill for a fresh "I want to build/change X" prompt when approval, scope, or next allowed action is unclear.
 ---
 
 # brownfield-analysis
@@ -38,6 +38,7 @@ Brownfield-specific output must make evidence, missing existing-system view, par
 12. Specification archive migrations must follow the archive index if present.
 
 ## When To Use
+- after `gate-check` permits implementation preparation or live `.agdf/control/AGDF_RUN.md` already names Brownfield Analysis as the next allowed action
 - before `CD+Tests`
 - before changes to an existing repository
 - bug fixes in existing modules
@@ -58,6 +59,7 @@ Use what is available:
 - repository conventions
 
 If inputs are missing, work only from observable evidence and mark gaps explicitly.
+If gate status, approval, scope or next allowed action is unclear, stop and route to `gate-check` instead of recommending or starting implementation.
 
 ## Workflow
 1. Identify affected tasks and scope.

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

@@ -1,6 +1,6 @@
 ---
 name: gate-check
-description: Use this skill when the active gate is unclear, when a later-gate artefact is requested, when an exact approval may be missing, or when the next permissible step must be determined. Use it before creating formal artefacts in Structured Delivery and whenever implicit consent might be mistaken for approval.
+description: Use this skill as the default first AGDF skill for any new build, change, extension, refactor, feature, CLI, app, fix with product semantics, Structured Delivery request, unclear approval, later-gate artefact request, or unclear next permissible step. Use it before brownfield-analysis, implementation, formal artefacts, QA, or release when approval/evidence/next action is not already explicit.
 ---
 
 # gate-check
@@ -43,6 +43,9 @@ The CLI report is evidence for this skill, not a second rule system. If the repo
 7. Internal process steps are not user approval gates.
 8. OR-lite is allowed if it does not leak blocked content.
 9. SoT/runtime/product-semantics drift can trigger an early product gate, usually `UR`.
+10. Approval of one user gate permits work on the next gate artefact only; it never skips directly to implementation.
+11. New product semantics, functional change or user-visible behaviour change requires a durable UR in `.agdf/control/` or a linked authoritative repository SoT before PRD, SD, TP, Brownfield Analysis or implementation.
+12. Approval text and durable artefact presence are separate requirements for UR, PRD, SD, TP and QA report decisions. Approval text without the corresponding persisted or linked artefact keeps the current gate at that gate.
 
 ## Gate Order
 User gates:
@@ -53,7 +56,25 @@ Internal mandatory steps:
 
 `Brownfield Analysis -> CD+Tests -> CR -> OR`
 
+## Gate Transitions
+
+Use this transition model for Structured Delivery:
+
+| State | Current gate or step | Allowed | Forbidden | Missing approval |
+|---|---|---|---|---|
+| No approved UR | `UR` | clarify user need, formulate and persist UR, request `Approval: UR` | PRD, SD, TP, Brownfield Analysis, implementation, QA, release | `Approval: UR` |
+| `UR` approved and UR artefact persisted or linked, PRD missing or draft | `PRD` | draft/refine PRD, define scope, acceptance criteria and non-goals, persist/link PRD, request `Approval: PRD` | SD, TP, Brownfield Analysis, implementation, QA, release | `Approval: PRD` |
+| `PRD` approved and PRD artefact persisted or linked, SD missing or draft | `SD` | draft/refine Solution Design, ownership and architecture, persist/link SD, request `Approval: SD` | TP, implementation, QA, release | `Approval: SD` |
+| `SD` approved and SD artefact persisted or linked, TP missing or draft | `TP` | draft/refine Task/Test Plan, task IDs, evidence plan, persist/link TP, request `Approval: TP` | implementation, QA, release | `Approval: TP` |
+| `TP` approved and TP artefact persisted or linked, Brownfield missing | `Brownfield Analysis` | run Brownfield Analysis for approved TP scope | implementation, QA, release | none |
+| Brownfield passed for approved TP | `CD+Tests` | implement approved TP tasks and run tests | QA pass, UAT, release | none |
+| `QA` approved but QA report missing or not pass | `QA` | persist/link QA report with `pass` decision or revise/block evidence | UAT, release | none |
+
+If `Approval: UR` is present, do not say implementation is the next step.
+The next step is PRD work unless the run is explicitly classified as a Quick Task with no new product semantics and no formal artefact requirement.
+
 ## When To Use
+- new user intent to build, add, change, extend, refactor or deliver something
 - Structured Delivery before first artefact creation
 - unclear current gate
 - user says "continue" or similar without exact approval
@@ -63,6 +84,9 @@ Internal mandatory steps:
 
 Not required for simple Quick Tasks without new product scope and without formal artefacts.
 
+For a fresh prompt such as "I want to build a small CLI", use this skill first.
+Do not route directly to `brownfield-analysis` or implementation until this skill or live AGDF control state says that implementation preparation is the next allowed action.
+
 ## Inputs
 Use what is available:
 
@@ -82,6 +106,7 @@ If a status is not explicit, do not assume it is satisfied.
 4. Derive allowed and forbidden outputs.
 5. Name the exact missing approval, if any.
 6. If consent was only implicit, say it is not yet approval and provide the exact formula.
+7. Ensure the next step follows the gate transition table. In particular, never jump from `Approval: UR` to implementation.
 
 ## Output
 Keep the result short and operational:
@@ -99,6 +124,9 @@ This skill must not:
 - create PRD before UR approval
 - create SD before PRD approval
 - create TP while earlier gates block
+- suggest implementation immediately after `Approval: UR`
+- suggest implementation immediately after `Approval: PRD`
+- suggest implementation immediately after `Approval: SD`
 - perform full Brownfield Analysis unless explicitly requested
 - provide implementation snippets while implementation is gated
 - present QA or UAT as passed without evidence

package/package.json

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