create-agdf 0.2.4 → 0.2.5

package/bin/create-agdf.js

@@ -35,6 +35,7 @@ const codexPluginFiles = [
   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", "BROWNFIELD_REVIEW.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"),
@@ -57,6 +58,7 @@ const controlFiles = [
   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", "BROWNFIELD_REVIEW.md"),
   join(".agdf", "control", "templates", "artefacts", "PRD.md"),
   join(".agdf", "control", "templates", "artefacts", "SD.md"),
   join(".agdf", "control", "templates", "artefacts", "TP.md"),
@@ -87,6 +89,7 @@ const liveControlFiles = [
 ];
 const artefactTemplateFiles = [
   join(".agdf", "control", "templates", "artefacts", "UR.md"),
+  join(".agdf", "control", "templates", "artefacts", "BROWNFIELD_REVIEW.md"),
   join(".agdf", "control", "templates", "artefacts", "PRD.md"),
   join(".agdf", "control", "templates", "artefacts", "SD.md"),
   join(".agdf", "control", "templates", "artefacts", "TP.md"),
@@ -745,7 +748,9 @@ function isInternalStepSatisfied(runState, step) {
 
 function modeSliceDecision(runState) {
   const decision = runState.mode_slice_decision?.decision ?? "";
-  if (!decision || isPlaceholderValue(decision)) return "undecided";
+  const scopeReason = runState.mode_slice_decision?.scope_reason ?? "";
+  const evidence = runState.mode_slice_decision?.evidence ?? "";
+  if (!decision || isPlaceholderValue(decision) || !filled(scopeReason) || !filled(evidence)) return "undecided";
   return decision;
 }
 
@@ -917,11 +922,11 @@ function transitionDecisionForRunState(runState) {
         missing_approval: "none",
         allowed: [
           "decide whether the approved UR is quick_task, structured_slice, structured_delivery or block",
-          "record scope reason and evidence in AGDF_RUN.md",
+          "record scope reason, evidence and required next gate depth in AGDF_RUN.md",
           "choose the next required gate depth before drafting PRD or implementing",
         ],
         forbidden: ["create PRD before process size is decided", "create SD", "create TP", "implement code", "claim QA or release readiness"],
-        next_allowed_action: "Record the Mode/Slice Decision from Brownfield Review before choosing PRD depth or Quick Task execution.",
+        next_allowed_action: "Record the Mode/Slice Decision from Brownfield Review with scope reason and evidence before choosing PRD depth or Quick Task execution.",
       };
     }
 
@@ -1091,13 +1096,14 @@ function readBacklogPointers(targetDir) {
       title: cells[2] ?? "",
       status: cleanStatusCell(cells[3] ?? ""),
       ur: cells[4] ?? "",
-      prd: cells[5] ?? "",
-      sd: cells[6] ?? "",
-      tp: cells[7] ?? "",
-      qa: cells[8] ?? "",
-      or: cells[9] ?? "",
-      current_spec: cells[10] ?? "",
-      notes: cells[11] ?? "",
+      brownfield_review: cells[5] ?? "",
+      prd: cells[6] ?? "",
+      sd: cells[7] ?? "",
+      tp: cells[8] ?? "",
+      qa: cells[9] ?? "",
+      or: cells[10] ?? "",
+      current_spec: cells[11] ?? "",
+      notes: cells[12] ?? "",
     }));
 }
 

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

@@ -9,8 +9,9 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 | File | Purpose |
 |---|---|
 | `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/QA/OR artefacts |
+| `templates/MASTER_BACKLOG.md` | Template for the living backlog pointer: active initiatives and current UR/Brownfield/PRD/SD/TP/QA/OR artefacts |
 | `templates/artefacts/UR.md` | Template for the durable user requirement artefact of a work item |
+| `templates/artefacts/BROWNFIELD_REVIEW.md` | Template for the durable Brownfield Review and Mode/Slice Decision |
 | `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 |
@@ -30,6 +31,7 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
     artefacts/
       <work-item>/
         UR.md
+        BROWNFIELD_REVIEW.md
         PRD.md
         SD.md
         TP.md
@@ -63,6 +65,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.
+- Brownfield Review records the post-UR Mode/Slice Decision before PRD depth or Quick Task execution is chosen.
 - 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.
 - OR records the run closeout and next permissible step; it does not approve later gates.
 - `SOT_REGISTRY.md` decides which document owns which domain.

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

@@ -44,7 +44,7 @@ Valid approval format for new runs: `Approval: <GateName>`.
 | PRD |  | `draft | approved | superseded | not_applicable` |  |
 | SD |  | `draft | approved | superseded | not_applicable` |  |
 | TP |  | `draft | approved | superseded | not_applicable` |  |
-| Brownfield Review |  | `missing | done | not_applicable` |  |
+| Brownfield Review |  | `missing | draft | done | not_applicable | superseded` |  |
 | Review |  | `missing | done | not_applicable` |  |
 | QA |  | `missing | pass | revise | block | not_applicable` |  |
 | OR |  | `missing | done | not_applicable` |  |
@@ -52,11 +52,13 @@ Valid approval format for new runs: `Approval: <GateName>`.
 ## Mode / Slice Decision
 
 Set this after Brownfield Review. Do not assume the full gate chain before the existing-system impact is understood.
+Quick Task execution or implementation is not allowed until this decision is visible with scope reason and evidence.
 
 - decision: `undecided | quick_task | structured_slice | structured_delivery | block`
 - required_next_gate: `none | PRD | SD | TP | Brownfield Analysis`
 - scope_reason:
 - evidence:
+- transparency_note:
 
 ## Artefact Chain
 

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

@@ -1,31 +1,32 @@
 # AGDF Master Backlog
 
-This file is the living control pointer for active AGDF delivery work. Detailed UR, PRD, SD, TP, QA and OR artefacts should live in stable paths and be linked from here.
+This file is the living control pointer for active AGDF delivery work. Detailed UR, Brownfield Review, PRD, SD, TP, QA and OR artefacts should live in stable paths and be linked from here.
 
 ## Rules
 
 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 and persisted or linked.
-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. Generic consent such as "ok", "go ahead", "do it", "continue", "leg los" or "approved" does not update a gate. Only `Approval: <GateName>` does.
-6. Keep only steering-relevant work in `Active Backlog`.
-7. Every active item has exactly one current spec pointer and a visible artefact chain.
-8. Historical artefacts remain linkable but do not override the current pointer.
-9. If an item is superseded, mark the replacement.
-10. If active work grows beyond roughly ten items, triage the backlog.
+3. Brownfield Review is created for the same work item after UR approval when existing-system impact must be sized before PRD depth or Quick Task execution.
+4. PRD, SD, TP and QA report artefacts are created for the same work item after the previous gate is approved and persisted or linked.
+5. `Approval: PRD`, `Approval: SD`, `Approval: TP` and `Approval: QA` require the corresponding durable artefact or linked repository SoT before the next gate can open.
+6. Generic consent such as "ok", "go ahead", "do it", "continue", "leg los" or "approved" does not update a gate. Only `Approval: <GateName>` does.
+7. Keep only steering-relevant work in `Active Backlog`.
+8. Every active item has exactly one current spec pointer and a visible artefact chain.
+9. Historical artefacts remain linkable but do not override the current pointer.
+10. If an item is superseded, mark the replacement.
+11. If active work grows beyond roughly ten items, triage the backlog.
 
 ## Active Backlog
 
-| Prio | Key | Title | Status | UR | PRD | SD | TP | QA | OR | Current Spec | Notes |
-|---:|---|---|---|---|---|---|---|---|---|---|---|
-| P1 |  |  | `in_progress | blocked` |  |  |  |  |  |  |  |  |
+| Prio | Key | Title | Status | UR | Brownfield Review | PRD | SD | TP | QA | OR | Current Spec | Notes |
+|---:|---|---|---|---|---|---|---|---|---|---|---|---|
+| P1 |  |  | `in_progress | blocked` |  |  |  |  |  |  |  |  |  |
 
 ## Planned / Parking Lot
 
-| Prio | Key | Title | Status | UR | PRD | SD | TP | QA | OR | Current Spec | Notes |
-|---:|---|---|---|---|---|---|---|---|---|---|---|
-| P2 |  |  | `planned | review_needed` |  |  |  |  |  |  |  |  |
+| Prio | Key | Title | Status | UR | Brownfield Review | PRD | SD | TP | QA | OR | Current Spec | Notes |
+|---:|---|---|---|---|---|---|---|---|---|---|---|---|
+| P2 |  |  | `planned | review_needed` |  |  |  |  |  |  |  |  |  |
 
 ## Completed / Superseded Pointers
 

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

@@ -0,0 +1,67 @@
+# Brownfield Review: <Title>
+
+Gate: Brownfield Review
+Type: Brownfield Review
+Mode: `post_ur_review`
+Status: `draft | done | not_applicable | superseded`
+
+## Run
+
+- run_id:
+- related_ur:
+- current_gate:
+- reviewer:
+- reviewed_at:
+
+## Objective
+
+What approved UR scope is being sized and routed?
+
+## Existing-System View
+
+| Area | Existing owner or artefact | Evidence | Impact |
+|---|---|---|---|
+| Product semantics |  |  | `none | low | medium | high` |
+| Source of truth |  |  | `none | low | medium | high` |
+| Runtime path |  |  | `none | low | medium | high` |
+| UI / UX |  |  | `none | low | medium | high` |
+| Persistence / data |  |  | `none | low | medium | high` |
+| Tests / QA |  |  | `none | low | medium | high` |
+| Release / operations |  |  | `none | low | medium | high` |
+
+## Reuse And Parallel-Structure Risk
+
+| Finding | Evidence | Risk | Required action |
+|---|---|---|---|
+|  |  | `none | warn | revise | block` |  |
+
+## Mode / Slice Decision
+
+- decision: `quick_task | structured_slice | structured_delivery | block`
+- required_next_gate: `none | PRD | SD | TP | Brownfield Analysis`
+- scope_reason:
+- evidence:
+- transparency_note:
+
+## PRD / SD Open Questions
+
+| Question | Required gate | Impact |
+|---|---|---|
+|  | `none | PRD | SD | TP` | `warn | revise | block` |
+
+## Context Graph Impact
+
+- context_graph_impact: `none | link_only | update_existing_node | new_node_required | sot_drift`
+- context_graph_refs:
+- context_graph_required_action: `none | link | update | create | resolve_drift`
+- context_graph_gate_effect: `none | warning | revise | block`
+- context_graph_evidence:
+
+## Next Permissible Step
+
+- next_allowed_action:
+- forbidden_until_then:
+
+## Quality Outlook
+
+- quality_outlook:

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

@@ -22,10 +22,18 @@ The skill answers:
 Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
 
 Brownfield-specific output must make evidence, missing existing-system view, parallel-structure risk, reuse strategy, and the minimal next step visible.
+When `.agdf/control/` is present, persist or link `post_ur_review` output under `.agdf/control/artefacts/<key>/BROWNFIELD_REVIEW.md`.
+
+## Modes
+
+- `post_ur_review`: use after approved durable UR to size and route the work. Output must decide `quick_task`, `structured_slice`, `structured_delivery`, or `block` with scope reason and evidence.
+- `pre_implementation_analysis`: use after approved durable TP to verify the implementation path before `CD+Tests`. Output must focus on reuse path, owners, regression risk, test impact and minimal clean implementation.
+
+Do not mix both modes silently. Name the active mode in the output.
 
 ## 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 decide `quick_task`, `structured_slice`, `structured_delivery`, or `block` before PRD depth or implementation is chosen.
+2. Brownfield Review after `Approval: UR` is a sizing and routing step. It must visibly decide `quick_task`, `structured_slice`, `structured_delivery`, or `block` before PRD depth or implementation is chosen.
 3. Reuse-before-create: prefer existing modules, services, components, tables, endpoints, tests, and configuration.
 4. Minimal clean slice: choose the smallest durable intervention, not merely the smallest technical diff.
 5. No silent parallel structures.
@@ -63,7 +71,7 @@ Use what is available:
 
 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 PRD/SD detail or starting implementation.
-When used as Brownfield Review after `Approval: UR`, do not recommend PRD, SD, TP, or implementation until the Mode/Slice Decision is explicit.
+When used as Brownfield Review after `Approval: UR`, do not recommend PRD, SD, TP, or implementation until the Mode/Slice Decision is explicit, evidenced and recorded.
 
 ## Workflow
 1. Identify affected tasks and scope.
@@ -96,11 +104,14 @@ Use a concise structure:
 
 ```text
 ## Brownfield Analysis
+- mode: post_ur_review | pre_implementation_analysis
 - decision: pass | revise | block | not_applicable
 - mode_slice_decision: quick_task | structured_slice | structured_delivery | block
 - required_next_gate: none | PRD | SD | TP | Brownfield Analysis
+- artefact: .agdf/control/artefacts/<key>/BROWNFIELD_REVIEW.md | none
 - scope:
 - evidence:
+- transparency: why later artefacts are skipped, shortened or required
 - missing_evidence:
 - current_coverage:
 - reuse_strategy:

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

@@ -19,6 +19,7 @@ This skill must not create later artefacts such as PRD, SD, TP, CD, CR, QA, or U
 
 ## Runtime Contract
 Use `../agdf-runtime-contract.md` for gate terms, closeout discipline, and non-duplication rules.
+The canonical gate order and transition model live only in the Runtime Contract. This skill evaluates the current state against that model; it must not maintain a second complete gate table.
 
 ## Native Control Path
 
@@ -59,35 +60,13 @@ The CLI reports are validators and JSON evidence, not the primary user experienc
 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 Brownfield Review, 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.
 13. After Brownfield Review, decide the process size before drafting PRD or implementing: `quick_task | structured_slice | structured_delivery | block`.
+14. The Mode/Slice Decision must be visible and evidenced before any Quick Task execution, PRD shortcut or implementation. A decision value without scope reason and evidence is still missing.
 
-## Gate Order
-User gates:
-
-`UR -> PRD -> SD -> TP -> QA -> UAT`
-
-Internal mandatory steps:
-
-`Brownfield Review -> Mode/Slice Decision -> 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, Brownfield Review missing | `Brownfield Review` | classify workstream, existing owners, SoT, reuse risks, change size and PRD/SD open questions; mark review done or not_applicable | PRD, SD, TP, implementation, QA, release | none |
-| Brownfield Review done or not_applicable, Mode/Slice Decision missing | `Mode/Slice Decision` | decide `quick_task`, `structured_slice`, `structured_delivery` or `block`; record evidence and required next gate depth | PRD, SD, TP, implementation, QA, release | none |
-| Mode/Slice Decision is `quick_task` | `Quick Task Execution` | implement only the narrow approved UR scope, run relevant checks, record evidence and OR-lite | broad PRD/SD/TP by ritual, scope expansion, QA or release claims without evidence | none |
-| Mode/Slice Decision is `structured_slice` or `structured_delivery`, PRD missing or draft | `PRD` | draft/refine PRD at the smallest justified depth, define scope, acceptance criteria and non-goals, persist/link PRD, request `Approval: PRD` | SD, TP, implementation-preparation 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 |
+## Gate Evaluation
 
 If `Approval: UR` is present, do not say implementation is the next step.
 The next step is Brownfield Review when Brownfield, ownership, runtime, policy, persistence, architecture, UI or UX impact is possible; after that, the next step is a Mode/Slice Decision. Do not assume the full PRD/SD/TP chain before the existing-system impact is understood.
+Use the Runtime Contract's Gate Transition Model to derive the current gate, allowed outputs, forbidden outputs and missing approval.
 
 ## When To Use
 - new user intent to build, add, change, extend, refactor or deliver something
@@ -127,6 +106,7 @@ If a status is not explicit, do not assume it is satisfied.
 7. Ensure the next step follows the gate transition table. In particular, never jump from `Approval: UR` to implementation.
 8. Treat a generic "start", "continue" or "leg los" request as a request to perform only the current next allowed action.
 9. After Brownfield Review, choose the smallest safe process path before creating later artefacts.
+10. If the selected path is not visibly recorded with scope reason and evidence, keep the run at `Mode/Slice Decision`.
 
 ## Output
 Keep the result short and operational:

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

@@ -29,9 +29,10 @@ Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fie
 
 OR-specific output must make gate status, delivered and intentionally not delivered content, missing approvals, missing evidence, risks, retained fallbacks, and the next permissible step visible.
 When `.agdf/control/` is present, persist or link the OR under `.agdf/control/artefacts/<key>/OR.md` and reference it from `AGDF_RUN.md` or `MASTER_BACKLOG.md` when it is steering-relevant.
+Use the Runtime Contract definition of `Relevant Run` to decide whether OR is mandatory or whether a Quick Task mini-closeout is enough.
 
 ## Rules
-1. OR is always allowed and mandatory for relevant runs.
+1. OR is always allowed and mandatory for relevant runs as defined in the Runtime Contract.
 2. OR is an audit report, not a blocking gate.
 3. Do not leak artefacts from blocked later gates.
 4. Use OR-lite when early gates block.
@@ -52,6 +53,8 @@ When `.agdf/control/` is present, persist or link the OR under `.agdf/control/ar
 - after UAT
 - whenever a compact audit closeout is needed
 
+Do not force OR onto a pure explanation, read-only inspection, small review, or local debugging step that produces no durable state change and no gate consequence.
+
 ## Inputs
 Use what is available:
 

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

@@ -15,6 +15,23 @@ 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`
+
+## Relevant Run
+
+A relevant run is any run that changes durable state, creates or updates an AGDF artefact, changes code or runtime behaviour, performs a gate decision, blocks on a governance condition, produces QA/UAT/release evidence, or closes a delivery slice.
+
+OR is not mandatory for a pure explanation, read-only inspection, small review, or local debugging step that produces no durable state change and no gate consequence.
+When in doubt, use a short OR-lite only if it clarifies gate state, evidence, risk, or the next permissible step.
+
 ## Gate Rules
 
 - User gates: `UR -> PRD -> SD -> TP -> QA -> UAT`
@@ -28,6 +45,7 @@ UR, PRD, SD, TP and QA report approvals require durable artefacts or linked auth
 - Gates must never be skipped or inferred from urgency, tone, chat history, task wording or an instruction to "start". The next allowed action is always the next unsatisfied gate or internal mandatory step.
 - `Approval: UR` permits Brownfield Review after G-00 first, then a Mode/Slice Decision. It never permits implementation by itself.
 - PRD, SD and TP depth is chosen after Brownfield Review through the Mode/Slice Decision, not before existing-system impact is understood.
+- The Mode/Slice Decision must be visible before any PRD shortcut, Quick Task execution or implementation: record the decision, required next gate, scope reason and evidence in `AGDF_RUN.md` or an equivalent linked control artefact.
 - `Approval: PRD` permits Solution Design drafting, not implementation.
 - `Approval: SD` permits Task/Test Plan drafting, not implementation.
 - `Approval: TP` permits implementation-preparation Brownfield Analysis and then CD+Tests when Brownfield evidence supports it.
@@ -60,6 +78,34 @@ Mode/Slice Decision rules:
 - `structured_delivery`: use when the change has broad product, architecture, runtime, policy, persistence, release or cross-owner impact.
 - `block`: use when ownership, SoT, impact, evidence or product direction is not clear enough to choose a safe path.
 
+A Mode/Slice Decision without scope reason and evidence is not recorded. Treat it as missing and keep the next step at `Mode/Slice Decision`.
+
+## Gate Transition Model
+
+This table is the canonical transition model. Skills may reference it, but must not carry a second complete copy.
+
+| 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, Brownfield Review missing | `Brownfield Review` | classify workstream, existing owners, SoT, reuse risks, change size and PRD/SD open questions; mark review done or not_applicable | PRD, SD, TP, implementation, QA, release | none |
+| Brownfield Review done or not_applicable, Mode/Slice Decision missing or incomplete | `Mode/Slice Decision` | decide `quick_task`, `structured_slice`, `structured_delivery` or `block`; record scope reason, evidence and required next gate depth | PRD, SD, TP, implementation, QA, release | none |
+| Mode/Slice Decision is `quick_task` | `Quick Task Execution` | implement only the narrow approved UR scope, run relevant checks, record evidence and OR-lite when the run is relevant | broad PRD/SD/TP by ritual, scope expansion, QA or release claims without evidence | none |
+| Mode/Slice Decision is `structured_slice` or `structured_delivery`, PRD missing or draft | `PRD` | draft/refine PRD at the smallest justified depth, define scope, acceptance criteria and non-goals, persist/link PRD, request `Approval: PRD` | SD, TP, implementation-preparation 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 Analysis missing | `Brownfield Analysis` | run Brownfield Analysis for approved TP scope | implementation, QA, release | none |
+| Brownfield Analysis 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 |
+
+## Brownfield Modes
+
+The `agdf-brownfield-analysis` skill has two explicit modes:
+
+- `post_ur_review`: lightweight sizing and routing after approved durable UR; decides Mode/Slice Decision before PRD depth or implementation is chosen.
+- `pre_implementation_analysis`: implementation-preparation analysis after approved durable TP; verifies reuse path, owners, regression risk and fit before `CD+Tests`.
+
+Do not mix the modes silently. Name the active mode in Brownfield output.
+
 ## Quality Contract Output
 
 Structured Delivery skills use this shape when relevant:
@@ -93,6 +139,7 @@ When a repository needs durable AGDF state, use the plugin-local `control/` scaf
 
 - `AGDF_RUN.md` is the current run dashboard.
 - `MASTER_BACKLOG.md` is the living pointer for active delivery work.
+- `BROWNFIELD_REVIEW.md` records the post-UR existing-system view and Mode/Slice Decision before PRD depth or Quick Task execution is chosen.
 - `SOT_REGISTRY.md` prevents parallel sources of truth.
 - `CONTEXT_GRAPH.md` stores durable Brownfield findings, decisions, risks, evidence and exit criteria.
 - `AGENT_QUALITY_CONTRACTS.json` stores reusable block, revise and warning conditions.

package/generated/AGENTS.md

@@ -36,9 +36,10 @@ Do not infer approval from "ok", "go ahead", "do it", "approved", "continue", "l
 Those phrases may express intent to proceed, but they do not unlock a gate unless the exact gate formula is present.
 After `Approval: UR`, run lightweight Brownfield Review before PRD when Brownfield, ownership, runtime, policy, persistence, architecture, UI or UX impact is possible.
 Brownfield Review must produce a Mode/Slice Decision: `quick_task`, `structured_slice`, `structured_delivery` or `block`.
+Make that decision visible before coding or drafting later artefacts: state the selected path, scope reason, evidence and next required gate in the live control state or linked artefact.
 Do not assume the full PRD/SD/TP chain before that decision; use only as much gate depth as the reviewed change size justifies.
 
-Quick Task Mode must still cite evidence and close with a concrete result.
+Quick Task Mode must still use the Runtime Contract mini-output: `result`, `evidence`, `risk`, `next_step`.
 Structured Delivery Mode must respect gates, reviews and closeout discipline.
 
 ## Skill Routing
@@ -56,7 +57,7 @@ Structured Delivery Mode must respect gates, reviews and closeout discipline.
 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.
-Never jump directly from `Approval: UR`, implicit consent, or a generic "start" request to implementation. Route to Brownfield Review, then Mode/Slice Decision, then the smallest safe next gate or Quick Task execution.
+Never jump directly from `Approval: UR`, implicit consent, or a generic "start" request to implementation. Route to Brownfield Review, then a visible Mode/Slice Decision with evidence, then the smallest safe next gate or Quick Task execution.
 
 ## 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.4",
+  "version": "0.2.5",
   "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

@@ -9,8 +9,9 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 | File | Purpose |
 |---|---|
 | `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/QA/OR artefacts |
+| `templates/MASTER_BACKLOG.md` | Template for the living backlog pointer: active initiatives and current UR/Brownfield/PRD/SD/TP/QA/OR artefacts |
 | `templates/artefacts/UR.md` | Template for the durable user requirement artefact of a work item |
+| `templates/artefacts/BROWNFIELD_REVIEW.md` | Template for the durable Brownfield Review and Mode/Slice Decision |
 | `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 |
@@ -30,6 +31,7 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
     artefacts/
       <work-item>/
         UR.md
+        BROWNFIELD_REVIEW.md
         PRD.md
         SD.md
         TP.md
@@ -63,6 +65,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.
+- Brownfield Review records the post-UR Mode/Slice Decision before PRD depth or Quick Task execution is chosen.
 - 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.
 - OR records the run closeout and next permissible step; it does not approve later gates.
 - `SOT_REGISTRY.md` decides which document owns which domain.

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

@@ -44,7 +44,7 @@ Valid approval format for new runs: `Approval: <GateName>`.
 | PRD |  | `draft | approved | superseded | not_applicable` |  |
 | SD |  | `draft | approved | superseded | not_applicable` |  |
 | TP |  | `draft | approved | superseded | not_applicable` |  |
-| Brownfield Review |  | `missing | done | not_applicable` |  |
+| Brownfield Review |  | `missing | draft | done | not_applicable | superseded` |  |
 | Review |  | `missing | done | not_applicable` |  |
 | QA |  | `missing | pass | revise | block | not_applicable` |  |
 | OR |  | `missing | done | not_applicable` |  |
@@ -52,11 +52,13 @@ Valid approval format for new runs: `Approval: <GateName>`.
 ## Mode / Slice Decision
 
 Set this after Brownfield Review. Do not assume the full gate chain before the existing-system impact is understood.
+Quick Task execution or implementation is not allowed until this decision is visible with scope reason and evidence.
 
 - decision: `undecided | quick_task | structured_slice | structured_delivery | block`
 - required_next_gate: `none | PRD | SD | TP | Brownfield Analysis`
 - scope_reason:
 - evidence:
+- transparency_note:
 
 ## Artefact Chain
 

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

@@ -1,31 +1,32 @@
 # AGDF Master Backlog
 
-This file is the living control pointer for active AGDF delivery work. Detailed UR, PRD, SD, TP, QA and OR artefacts should live in stable paths and be linked from here.
+This file is the living control pointer for active AGDF delivery work. Detailed UR, Brownfield Review, PRD, SD, TP, QA and OR artefacts should live in stable paths and be linked from here.
 
 ## Rules
 
 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 and persisted or linked.
-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. Generic consent such as "ok", "go ahead", "do it", "continue", "leg los" or "approved" does not update a gate. Only `Approval: <GateName>` does.
-6. Keep only steering-relevant work in `Active Backlog`.
-7. Every active item has exactly one current spec pointer and a visible artefact chain.
-8. Historical artefacts remain linkable but do not override the current pointer.
-9. If an item is superseded, mark the replacement.
-10. If active work grows beyond roughly ten items, triage the backlog.
+3. Brownfield Review is created for the same work item after UR approval when existing-system impact must be sized before PRD depth or Quick Task execution.
+4. PRD, SD, TP and QA report artefacts are created for the same work item after the previous gate is approved and persisted or linked.
+5. `Approval: PRD`, `Approval: SD`, `Approval: TP` and `Approval: QA` require the corresponding durable artefact or linked repository SoT before the next gate can open.
+6. Generic consent such as "ok", "go ahead", "do it", "continue", "leg los" or "approved" does not update a gate. Only `Approval: <GateName>` does.
+7. Keep only steering-relevant work in `Active Backlog`.
+8. Every active item has exactly one current spec pointer and a visible artefact chain.
+9. Historical artefacts remain linkable but do not override the current pointer.
+10. If an item is superseded, mark the replacement.
+11. If active work grows beyond roughly ten items, triage the backlog.
 
 ## Active Backlog
 
-| Prio | Key | Title | Status | UR | PRD | SD | TP | QA | OR | Current Spec | Notes |
-|---:|---|---|---|---|---|---|---|---|---|---|---|
-| P1 |  |  | `in_progress | blocked` |  |  |  |  |  |  |  |  |
+| Prio | Key | Title | Status | UR | Brownfield Review | PRD | SD | TP | QA | OR | Current Spec | Notes |
+|---:|---|---|---|---|---|---|---|---|---|---|---|---|
+| P1 |  |  | `in_progress | blocked` |  |  |  |  |  |  |  |  |  |
 
 ## Planned / Parking Lot
 
-| Prio | Key | Title | Status | UR | PRD | SD | TP | QA | OR | Current Spec | Notes |
-|---:|---|---|---|---|---|---|---|---|---|---|---|
-| P2 |  |  | `planned | review_needed` |  |  |  |  |  |  |  |  |
+| Prio | Key | Title | Status | UR | Brownfield Review | PRD | SD | TP | QA | OR | Current Spec | Notes |
+|---:|---|---|---|---|---|---|---|---|---|---|---|---|
+| P2 |  |  | `planned | review_needed` |  |  |  |  |  |  |  |  |  |
 
 ## Completed / Superseded Pointers
 

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

@@ -0,0 +1,67 @@
+# Brownfield Review: <Title>
+
+Gate: Brownfield Review
+Type: Brownfield Review
+Mode: `post_ur_review`
+Status: `draft | done | not_applicable | superseded`
+
+## Run
+
+- run_id:
+- related_ur:
+- current_gate:
+- reviewer:
+- reviewed_at:
+
+## Objective
+
+What approved UR scope is being sized and routed?
+
+## Existing-System View
+
+| Area | Existing owner or artefact | Evidence | Impact |
+|---|---|---|---|
+| Product semantics |  |  | `none | low | medium | high` |
+| Source of truth |  |  | `none | low | medium | high` |
+| Runtime path |  |  | `none | low | medium | high` |
+| UI / UX |  |  | `none | low | medium | high` |
+| Persistence / data |  |  | `none | low | medium | high` |
+| Tests / QA |  |  | `none | low | medium | high` |
+| Release / operations |  |  | `none | low | medium | high` |
+
+## Reuse And Parallel-Structure Risk
+
+| Finding | Evidence | Risk | Required action |
+|---|---|---|---|
+|  |  | `none | warn | revise | block` |  |
+
+## Mode / Slice Decision
+
+- decision: `quick_task | structured_slice | structured_delivery | block`
+- required_next_gate: `none | PRD | SD | TP | Brownfield Analysis`
+- scope_reason:
+- evidence:
+- transparency_note:
+
+## PRD / SD Open Questions
+
+| Question | Required gate | Impact |
+|---|---|---|
+|  | `none | PRD | SD | TP` | `warn | revise | block` |
+
+## Context Graph Impact
+
+- context_graph_impact: `none | link_only | update_existing_node | new_node_required | sot_drift`
+- context_graph_refs:
+- context_graph_required_action: `none | link | update | create | resolve_drift`
+- context_graph_gate_effect: `none | warning | revise | block`
+- context_graph_evidence:
+
+## Next Permissible Step
+
+- next_allowed_action:
+- forbidden_until_then:
+
+## Quality Outlook
+
+- quality_outlook:

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

@@ -37,9 +37,10 @@ Do not infer approval from "ok", "go ahead", "do it", "approved", "continue", "l
 Those phrases may express intent to proceed, but they do not unlock a gate unless the exact gate formula is present.
 After `Approval: UR`, run lightweight Brownfield Review before PRD when Brownfield, ownership, runtime, policy, persistence, architecture, UI or UX impact is possible.
 Brownfield Review must produce a Mode/Slice Decision: `quick_task`, `structured_slice`, `structured_delivery` or `block`.
+Make that decision visible before coding or drafting later artefacts: state the selected path, scope reason, evidence and next required gate in the live control state or linked artefact.
 Do not assume the full PRD/SD/TP chain before that decision; use only as much gate depth as the reviewed change size justifies.
 
-Quick Task Mode must still cite evidence and close with a concrete result.
+Quick Task Mode must still use the Runtime Contract mini-output: `result`, `evidence`, `risk`, `next_step`.
 Structured Delivery Mode must respect gates, reviews and closeout discipline.
 
 ## Skill Routing
@@ -57,7 +58,7 @@ Structured Delivery Mode must respect gates, reviews and closeout discipline.
 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.
-Never jump directly from `Approval: UR`, implicit consent, or a generic "start" request to implementation. Route to Brownfield Review, then Mode/Slice Decision, then the smallest safe next gate or Quick Task execution.
+Never jump directly from `Approval: UR`, implicit consent, or a generic "start" request to implementation. Route to Brownfield Review, then a visible Mode/Slice Decision with evidence, then the smallest safe next gate or Quick Task execution.
 
 ## Runtime Contract
 For repeated output, gate, Quality Contract and Context Graph rules, use:

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

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "AI-native Governance & Delivery Framework",
   "description": "Codex-first workflow skills for gated, auditable AI-assisted software delivery.",

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

@@ -15,6 +15,23 @@ 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`
+
+## Relevant Run
+
+A relevant run is any run that changes durable state, creates or updates an AGDF artefact, changes code or runtime behaviour, performs a gate decision, blocks on a governance condition, produces QA/UAT/release evidence, or closes a delivery slice.
+
+OR is not mandatory for a pure explanation, read-only inspection, small review, or local debugging step that produces no durable state change and no gate consequence.
+When in doubt, use a short OR-lite only if it clarifies gate state, evidence, risk, or the next permissible step.
+
 ## Gate Rules
 
 - User gates: `UR -> PRD -> SD -> TP -> QA -> UAT`
@@ -28,6 +45,7 @@ UR, PRD, SD, TP and QA report approvals require durable artefacts or linked auth
 - Gates must never be skipped or inferred from urgency, tone, chat history, task wording or an instruction to "start". The next allowed action is always the next unsatisfied gate or internal mandatory step.
 - `Approval: UR` permits Brownfield Review after G-00 first, then a Mode/Slice Decision. It never permits implementation by itself.
 - PRD, SD and TP depth is chosen after Brownfield Review through the Mode/Slice Decision, not before existing-system impact is understood.
+- The Mode/Slice Decision must be visible before any PRD shortcut, Quick Task execution or implementation: record the decision, required next gate, scope reason and evidence in `AGDF_RUN.md` or an equivalent linked control artefact.
 - `Approval: PRD` permits Solution Design drafting, not implementation.
 - `Approval: SD` permits Task/Test Plan drafting, not implementation.
 - `Approval: TP` permits implementation-preparation Brownfield Analysis and then CD+Tests when Brownfield evidence supports it.
@@ -60,6 +78,34 @@ Mode/Slice Decision rules:
 - `structured_delivery`: use when the change has broad product, architecture, runtime, policy, persistence, release or cross-owner impact.
 - `block`: use when ownership, SoT, impact, evidence or product direction is not clear enough to choose a safe path.
 
+A Mode/Slice Decision without scope reason and evidence is not recorded. Treat it as missing and keep the next step at `Mode/Slice Decision`.
+
+## Gate Transition Model
+
+This table is the canonical transition model. Skills may reference it, but must not carry a second complete copy.
+
+| 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, Brownfield Review missing | `Brownfield Review` | classify workstream, existing owners, SoT, reuse risks, change size and PRD/SD open questions; mark review done or not_applicable | PRD, SD, TP, implementation, QA, release | none |
+| Brownfield Review done or not_applicable, Mode/Slice Decision missing or incomplete | `Mode/Slice Decision` | decide `quick_task`, `structured_slice`, `structured_delivery` or `block`; record scope reason, evidence and required next gate depth | PRD, SD, TP, implementation, QA, release | none |
+| Mode/Slice Decision is `quick_task` | `Quick Task Execution` | implement only the narrow approved UR scope, run relevant checks, record evidence and OR-lite when the run is relevant | broad PRD/SD/TP by ritual, scope expansion, QA or release claims without evidence | none |
+| Mode/Slice Decision is `structured_slice` or `structured_delivery`, PRD missing or draft | `PRD` | draft/refine PRD at the smallest justified depth, define scope, acceptance criteria and non-goals, persist/link PRD, request `Approval: PRD` | SD, TP, implementation-preparation 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 Analysis missing | `Brownfield Analysis` | run Brownfield Analysis for approved TP scope | implementation, QA, release | none |
+| Brownfield Analysis 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 |
+
+## Brownfield Modes
+
+The `brownfield-analysis` skill has two explicit modes:
+
+- `post_ur_review`: lightweight sizing and routing after approved durable UR; decides Mode/Slice Decision before PRD depth or implementation is chosen.
+- `pre_implementation_analysis`: implementation-preparation analysis after approved durable TP; verifies reuse path, owners, regression risk and fit before `CD+Tests`.
+
+Do not mix the modes silently. Name the active mode in Brownfield output.
+
 ## Quality Contract Output
 
 Structured Delivery skills use this shape when relevant:
@@ -93,6 +139,7 @@ When a repository needs durable AGDF state, use the plugin-local `control/` scaf
 
 - `AGDF_RUN.md` is the current run dashboard.
 - `MASTER_BACKLOG.md` is the living pointer for active delivery work.
+- `BROWNFIELD_REVIEW.md` records the post-UR existing-system view and Mode/Slice Decision before PRD depth or Quick Task execution is chosen.
 - `SOT_REGISTRY.md` prevents parallel sources of truth.
 - `CONTEXT_GRAPH.md` stores durable Brownfield findings, decisions, risks, evidence and exit criteria.
 - `AGENT_QUALITY_CONTRACTS.json` stores reusable block, revise and warning conditions.

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

@@ -22,10 +22,18 @@ The skill answers:
 Use `../../meta/agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
 
 Brownfield-specific output must make evidence, missing existing-system view, parallel-structure risk, reuse strategy, and the minimal next step visible.
+When `.agdf/control/` is present, persist or link `post_ur_review` output under `.agdf/control/artefacts/<key>/BROWNFIELD_REVIEW.md`.
+
+## Modes
+
+- `post_ur_review`: use after approved durable UR to size and route the work. Output must decide `quick_task`, `structured_slice`, `structured_delivery`, or `block` with scope reason and evidence.
+- `pre_implementation_analysis`: use after approved durable TP to verify the implementation path before `CD+Tests`. Output must focus on reuse path, owners, regression risk, test impact and minimal clean implementation.
+
+Do not mix both modes silently. Name the active mode in the output.
 
 ## 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 decide `quick_task`, `structured_slice`, `structured_delivery`, or `block` before PRD depth or implementation is chosen.
+2. Brownfield Review after `Approval: UR` is a sizing and routing step. It must visibly decide `quick_task`, `structured_slice`, `structured_delivery`, or `block` before PRD depth or implementation is chosen.
 3. Reuse-before-create: prefer existing modules, services, components, tables, endpoints, tests, and configuration.
 4. Minimal clean slice: choose the smallest durable intervention, not merely the smallest technical diff.
 5. No silent parallel structures.
@@ -63,7 +71,7 @@ Use what is available:
 
 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 PRD/SD detail or starting implementation.
-When used as Brownfield Review after `Approval: UR`, do not recommend PRD, SD, TP, or implementation until the Mode/Slice Decision is explicit.
+When used as Brownfield Review after `Approval: UR`, do not recommend PRD, SD, TP, or implementation until the Mode/Slice Decision is explicit, evidenced and recorded.
 
 ## Workflow
 1. Identify affected tasks and scope.
@@ -96,11 +104,14 @@ Use a concise structure:
 
 ```text
 ## Brownfield Analysis
+- mode: post_ur_review | pre_implementation_analysis
 - decision: pass | revise | block | not_applicable
 - mode_slice_decision: quick_task | structured_slice | structured_delivery | block
 - required_next_gate: none | PRD | SD | TP | Brownfield Analysis
+- artefact: .agdf/control/artefacts/<key>/BROWNFIELD_REVIEW.md | none
 - scope:
 - evidence:
+- transparency: why later artefacts are skipped, shortened or required
 - missing_evidence:
 - current_coverage:
 - reuse_strategy:

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

@@ -19,6 +19,7 @@ This skill must not create later artefacts such as PRD, SD, TP, CD, CR, QA, or U
 
 ## Runtime Contract
 Use `../../meta/agdf-runtime-contract.md` for gate terms, closeout discipline, and non-duplication rules.
+The canonical gate order and transition model live only in the Runtime Contract. This skill evaluates the current state against that model; it must not maintain a second complete gate table.
 
 ## Native Control Path
 
@@ -59,35 +60,13 @@ The CLI reports are validators and JSON evidence, not the primary user experienc
 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 Brownfield Review, 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.
 13. After Brownfield Review, decide the process size before drafting PRD or implementing: `quick_task | structured_slice | structured_delivery | block`.
+14. The Mode/Slice Decision must be visible and evidenced before any Quick Task execution, PRD shortcut or implementation. A decision value without scope reason and evidence is still missing.
 
-## Gate Order
-User gates:
-
-`UR -> PRD -> SD -> TP -> QA -> UAT`
-
-Internal mandatory steps:
-
-`Brownfield Review -> Mode/Slice Decision -> 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, Brownfield Review missing | `Brownfield Review` | classify workstream, existing owners, SoT, reuse risks, change size and PRD/SD open questions; mark review done or not_applicable | PRD, SD, TP, implementation, QA, release | none |
-| Brownfield Review done or not_applicable, Mode/Slice Decision missing | `Mode/Slice Decision` | decide `quick_task`, `structured_slice`, `structured_delivery` or `block`; record evidence and required next gate depth | PRD, SD, TP, implementation, QA, release | none |
-| Mode/Slice Decision is `quick_task` | `Quick Task Execution` | implement only the narrow approved UR scope, run relevant checks, record evidence and OR-lite | broad PRD/SD/TP by ritual, scope expansion, QA or release claims without evidence | none |
-| Mode/Slice Decision is `structured_slice` or `structured_delivery`, PRD missing or draft | `PRD` | draft/refine PRD at the smallest justified depth, define scope, acceptance criteria and non-goals, persist/link PRD, request `Approval: PRD` | SD, TP, implementation-preparation 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 |
+## Gate Evaluation
 
 If `Approval: UR` is present, do not say implementation is the next step.
 The next step is Brownfield Review when Brownfield, ownership, runtime, policy, persistence, architecture, UI or UX impact is possible; after that, the next step is a Mode/Slice Decision. Do not assume the full PRD/SD/TP chain before the existing-system impact is understood.
+Use the Runtime Contract's Gate Transition Model to derive the current gate, allowed outputs, forbidden outputs and missing approval.
 
 ## When To Use
 - new user intent to build, add, change, extend, refactor or deliver something
@@ -127,6 +106,7 @@ If a status is not explicit, do not assume it is satisfied.
 7. Ensure the next step follows the gate transition table. In particular, never jump from `Approval: UR` to implementation.
 8. Treat a generic "start", "continue" or "leg los" request as a request to perform only the current next allowed action.
 9. After Brownfield Review, choose the smallest safe process path before creating later artefacts.
+10. If the selected path is not visibly recorded with scope reason and evidence, keep the run at `Mode/Slice Decision`.
 
 ## Output
 Keep the result short and operational:

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

@@ -29,9 +29,10 @@ Use `../../meta/agdf-runtime-contract.md` for Quality Contract output, Context G
 
 OR-specific output must make gate status, delivered and intentionally not delivered content, missing approvals, missing evidence, risks, retained fallbacks, and the next permissible step visible.
 When `.agdf/control/` is present, persist or link the OR under `.agdf/control/artefacts/<key>/OR.md` and reference it from `AGDF_RUN.md` or `MASTER_BACKLOG.md` when it is steering-relevant.
+Use the Runtime Contract definition of `Relevant Run` to decide whether OR is mandatory or whether a Quick Task mini-closeout is enough.
 
 ## Rules
-1. OR is always allowed and mandatory for relevant runs.
+1. OR is always allowed and mandatory for relevant runs as defined in the Runtime Contract.
 2. OR is an audit report, not a blocking gate.
 3. Do not leak artefacts from blocked later gates.
 4. Use OR-lite when early gates block.
@@ -52,6 +53,8 @@ When `.agdf/control/` is present, persist or link the OR under `.agdf/control/ar
 - after UAT
 - whenever a compact audit closeout is needed
 
+Do not force OR onto a pure explanation, read-only inspection, small review, or local debugging step that produces no durable state change and no gate consequence.
+
 ## Inputs
 Use what is available:
 

package/package.json

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