create-agdf 0.2.2 → 0.2.4

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

@@ -9,7 +9,13 @@ 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 artefacts |
+| `templates/MASTER_BACKLOG.md` | Template for the living backlog pointer: active initiatives and current UR/PRD/SD/TP/QA/OR 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/artefacts/OR.md` | Template for the durable Orchestration Report closeout |
 | `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 +27,14 @@ 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
+        OR.md
     SOT_REGISTRY.md
     CONTEXT_GRAPH.md
     AGENT_QUALITY_CONTRACTS.json
@@ -49,6 +63,8 @@ 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.
+- OR records the run closeout and next permissible step; it does not approve later gates.
 - `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/AGDF_RUN.md

@@ -5,7 +5,7 @@
 - run_id:
 - started_at:
 - mode: `quick_task | structured_delivery`
-- current_gate: `none | UR | PRD | SD | TP | CD+Tests | CR | QA | UAT | OR`
+- current_gate: `none | UR | Brownfield Review | Mode/Slice Decision | PRD | SD | TP | Quick Task Execution | Brownfield Analysis | CD+Tests | CR | QA | UAT | OR`
 - decision: `pass | revise | block | in_progress`
 - owner:
 
@@ -44,10 +44,32 @@ 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` |  |
 | Review |  | `missing | done | not_applicable` |  |
 | QA |  | `missing | pass | revise | block | not_applicable` |  |
 | OR |  | `missing | done | not_applicable` |  |
 
+## Mode / Slice Decision
+
+Set this after Brownfield Review. Do not assume the full gate chain before the existing-system impact is understood.
+
+- decision: `undecided | quick_task | structured_slice | structured_delivery | block`
+- required_next_gate: `none | PRD | SD | TP | Brownfield Analysis`
+- scope_reason:
+- evidence:
+
+## Artefact Chain
+
+Keep the active work item traceable. A gate may open only when the previous gate has both exact approval and a durable or linked artefact.
+
+| From | Relationship | To | Evidence |
+|---|---|---|---|
+| UR | `approved_by` | `Approval: UR` |  |
+| PRD | `derived_from` | UR |  |
+| SD | `derived_from` | PRD |  |
+| TP | `derived_from` | SD |  |
+| QA_REPORT | `tests` | TP |  |
+
 ## Evidence
 
 | Evidence | Source | Covers | Strength |

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

@@ -4,23 +4,28 @@ 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 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.
 
 ## Active Backlog
 
-| Prio | Key | Title | Status | Current Spec | Notes |
-|---:|---|---|---|---|---|
-| P1 |  |  | `in_progress | blocked` |  |  |
+| Prio | Key | Title | Status | UR | PRD | SD | TP | QA | OR | Current Spec | Notes |
+|---:|---|---|---|---|---|---|---|---|---|---|---|
+| P1 |  |  | `in_progress | blocked` |  |  |  |  |  |  |  |  |
 
 ## Planned / Parking Lot
 
-| Prio | Key | Title | Status | Current Spec | Notes |
-|---:|---|---|---|---|---|
-| P2 |  |  | `planned | review_needed` |  |  |
+| Prio | Key | Title | Status | UR | PRD | SD | TP | QA | OR | Current Spec | Notes |
+|---:|---|---|---|---|---|---|---|---|---|---|---|
+| P2 |  |  | `planned | review_needed` |  |  |  |  |  |  |  |  |
 
 ## Completed / Superseded Pointers
 

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

@@ -0,0 +1,86 @@
+# OR: <Title>
+
+Gate: OR
+Type: Orchestration Report
+Report mode: `OR-lite | OR-full`
+Status: `draft | done | superseded`
+
+## Run
+
+- run_id:
+- related_ur:
+- related_prd:
+- related_sd:
+- related_tp:
+- related_qa_report:
+- mode_slice_decision:
+- current_gate:
+- decision: `pass | revise | block | in_progress`
+
+## Gate State
+
+| Gate or step | Status | Evidence |
+|---|---|---|
+| UR |  |  |
+| Brownfield Review |  |  |
+| Mode/Slice Decision |  |  |
+| PRD |  |  |
+| SD |  |  |
+| TP |  |  |
+| Brownfield Analysis |  |  |
+| CD+Tests |  |  |
+| CR |  |  |
+| QA |  |  |
+| UAT |  |  |
+
+## Delivered
+
+| Item | Evidence |
+|---|---|
+|  |  |
+
+## Not Delivered / Intentionally Deferred
+
+| Item | Reason | Next owner or gate |
+|---|---|---|
+|  |  |  |
+
+## Evidence
+
+| Evidence | Source | Covers | Strength |
+|---|---|---|---|
+|  |  |  | `direct | indirect | weak` |
+
+## Missing Evidence
+
+| Missing evidence | Impact | Required next step |
+|---|---|---|
+|  | `warn | revise | block` |  |
+
+## Risks And Open Items
+
+| Risk or open item | Impact | Owner or mitigation |
+|---|---|---|
+|  | `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:
+- required_approval:
+- forbidden_until_then:
+
+## Quality Outlook
+
+- quality_outlook:
+
+## Approval
+
+OR does not approve later gates. It records the next permissible step.

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 Brownfield Review, PRD, SD or later implementation-preparation Brownfield Analysis clarify?
+
+## 8. Next Step
+
+Review this UR and approve only with:
+
+`Approval: UR`

package/generated/.github/copilot-instructions.md

@@ -5,6 +5,9 @@ AGDF is active in this repository.
 - Treat `AGENTS.md` as the primary repository instruction source.
 - Use `.github/skills/` for AGDF task workflows instead of inventing parallel process rules.
 - Use `.agdf/control/` for durable run state, backlog pointers, source-of-truth ownership, Context Graph knowledge and quality contracts.
+- Apply AGDF natively from `AGENTS.md`, repository skills and live `.agdf/control/` state before reaching for helper commands.
 - Before non-trivial implementation or formal delivery work, determine whether the request is a Quick Task or Structured Delivery.
 - If approval, evidence, ownership or the next allowed action is unclear, run the AGDF gate-check workflow before creating later artefacts or code.
+- Use machine-readable checks such as `doctor --json`, `gate-check --json` or `delivery-map --json` as validators, not as the primary workflow.
+- Do not infer gate approval from generic consent such as "ok", "go ahead", "do it", "continue", "leg los" or "approved".
 - Do not treat chat history as the source of truth for gate state, approvals, evidence or delivery status.

package/generated/.github/instructions/agdf-governance.instructions.md

@@ -10,4 +10,5 @@ These files are control artefacts, not general documentation.
 - Do not duplicate the full gate model, Quality Contract table or Context Graph relationship language in new files.
 - Keep generated AGDF files small, reviewable and linked to the owning source of truth.
 - Preserve the rule that missing approval, missing evidence or unclear ownership blocks later delivery steps.
+- Preserve the rule that gates cannot be skipped by generic consent, urgency or a request to start.
 - If changing AGDF bootstrap behaviour, update the generated files, smoke test and affected setup documentation together.

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

@@ -1,12 +1,12 @@
 ---
 name: agdf-brownfield-analysis
-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.
+description: Use this skill after gate-check or live AGDF control state confirms that Brownfield Review or implementation preparation is allowed. Use it after Approval: UR as the lightweight Brownfield Review after G-00 before PRD when existing systems may be affected, and again before non-trivial implementation after TP. 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
 
 ## Purpose
-Ensure implementation in an existing system is Brownfield-oriented, not Greenfield-style.
+Ensure delivery in an existing system is Brownfield-oriented, not Greenfield-style.
 
 The skill answers:
 
@@ -15,7 +15,7 @@ The skill answers:
 - what can be reused, extended, or refactored
 - whether new artefacts are really needed
 - architecture, compatibility, migration, and regression impact
-- the minimal clean implementation path
+- the minimal clean next step
 - whether Context Graph impact exists without automatically creating a node
 
 ## Runtime Contract
@@ -24,21 +24,24 @@ Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fie
 Brownfield-specific output must make evidence, missing existing-system view, parallel-structure risk, reuse strategy, and the minimal next step visible.
 
 ## Rules
-1. Brownfield first: understand the existing codebase before implementation.
-2. Reuse-before-create: prefer existing modules, services, components, tables, endpoints, tests, and configuration.
-3. Minimal clean slice: choose the smallest durable intervention, not merely the smallest technical diff.
-4. No silent parallel structures.
-5. Existing architecture, naming, error handling, logging, security, and test conventions are binding unless deviation is justified.
-6. What is not visibly evidenced does not count as existing.
-7. Async execute paths must not become a second product-policy decision point.
-8. Visible state ownership must be checked for chat, rendering, scrolling, recovery, and status problems.
-9. SoT/runtime/product-semantics drift must be named; if official behaviour must be decided first, recommend UR or equivalent product direction.
-10. Large UI surfaces and state hooks must be checked for mixed render, view-model, derived state, orchestration, persistence, and recovery ownership.
-11. Context Graph impact must be curated; it is not a review log or version index.
-12. Specification archive migrations must follow the archive index if present.
+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.
+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.
+6. Existing architecture, naming, error handling, logging, security, and test conventions are binding unless deviation is justified.
+7. What is not visibly evidenced does not count as existing.
+8. Async execute paths must not become a second product-policy decision point.
+9. Visible state ownership must be checked for chat, rendering, scrolling, recovery, and status problems.
+10. SoT/runtime/product-semantics drift must be named; if official behaviour must be decided first, recommend UR or equivalent product direction.
+11. Large UI surfaces and state hooks must be checked for mixed render, view-model, derived state, orchestration, persistence, and recovery ownership.
+12. Context Graph impact must be curated; it is not a review log or version index.
+13. Specification archive migrations must follow the archive index if present.
 
 ## When To Use
+- after `agdf-gate-check` permits `Brownfield Review` or live `.agdf/control/AGDF_RUN.md` names Brownfield Review as the next allowed action
 - after `agdf-gate-check` permits implementation preparation or live `.agdf/control/AGDF_RUN.md` already names Brownfield Analysis as the next allowed action
+- after `Approval: UR` when existing owners, SoT, contracts, policies, persistence, runtime paths, tests, UI, UX or architecture may affect PRD/SD scope
 - before `CD+Tests`
 - before changes to an existing repository
 - bug fixes in existing modules
@@ -51,7 +54,7 @@ Brownfield-specific output must make evidence, missing existing-system view, par
 ## Inputs
 Use what is available:
 
-- Task Plan, `task_id`, `story_id`
+- approved UR, Task Plan, `task_id`, `story_id`
 - project structure
 - affected files, modules, services, APIs, data models
 - existing tests
@@ -59,7 +62,8 @@ 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.
+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.
 
 ## Workflow
 1. Identify affected tasks and scope.
@@ -93,6 +97,8 @@ Use a concise structure:
 ```text
 ## Brownfield 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
 - scope:
 - evidence:
 - missing_evidence:
@@ -116,3 +122,4 @@ This skill must not:
 - convert product-semantics drift into a mere refactor
 - create Context Graph nodes automatically
 - treat archive links as active current specification signals
+- recommend broad PRD/SD/TP or implementation by reflex before Mode/Slice Decision is recorded

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

@@ -20,29 +20,45 @@ 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.
 
-## Machine-Readable Control Path
+## Native Control Path
 
-When the target repository contains live AGDF control files, prefer the executable control path before deriving a gate decision manually:
+AGDF is applied natively through this skill, the agent router, and live `.agdf/control/` state.
+
+First inspect the durable control state directly:
+
+- `.agdf/control/AGDF_RUN.md`
+- `.agdf/control/MASTER_BACKLOG.md`
+- `.agdf/control/SOT_REGISTRY.md`
+- `.agdf/control/CONTEXT_GRAPH.md`
+- `.agdf/control/AGENT_QUALITY_CONTRACTS.json`
+
+Use the executable control path when a machine-readable check is requested, when the gate state is ambiguous, or when a repository-local automation needs JSON evidence:
 
 ```bash
 npm create agdf@latest doctor --json
 npm create agdf@latest gate-check --json
+npm create agdf@latest delivery-map --json
 ```
 
 `doctor` checks whether `.agdf/control/` is actionable. `agdf-gate-check` consumes that result and `AGDF_RUN.md` to report the operative process decision: `open | blocked`, current gate, blocking reason, missing approval, allowed outputs, forbidden outputs, next allowed action and evidence references.
+`delivery-map` reports the durable delivery picture: active artefacts, approvals, Artefact Chain relationships, evidence refs, missing evidence, risks, Context Graph gate effect and machine-readable findings.
 
-The CLI report is evidence for this skill, not a second rule system. If the report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
+The CLI reports are validators and JSON evidence, not the primary user experience and not a second rule system. If a report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
 
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.
 2. The earliest blocking gate wins.
 3. A user approval is valid only as `Approval: <GateName>`.
 4. Treat `Freigabe: <GateName>` as a legacy alias only when reviewing older German runs.
-5. Implicit consent is not approval.
+5. Implicit consent is not approval. "ok", "go ahead", "do it", "approved", "continue", "leg los" and similar phrases do not unlock gates.
 6. Do not preview later artefacts while a gate blocks.
 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 allowed gate artefact or required internal step 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 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`.
 
 ## Gate Order
 User gates:
@@ -51,7 +67,27 @@ User gates:
 
 Internal mandatory steps:
 
-`Brownfield Analysis -> CD+Tests -> CR -> OR`
+`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 |
+
+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.
 
 ## When To Use
 - new user intent to build, add, change, extend, refactor or deliver something
@@ -73,6 +109,8 @@ Use what is available:
 - current user request
 - existing exact approvals
 - status of UR, PRD, SD, TP
+- Brownfield Review status
+- Mode/Slice Decision
 - Brownfield Analysis status
 - CD+Tests, CR, QA, UAT status
 - signs of documentation/runtime/product-semantics drift
@@ -86,6 +124,9 @@ 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.
+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.
 
 ## Output
 Keep the result short and operational:
@@ -101,8 +142,15 @@ Keep the result short and operational:
 This skill must not:
 
 - create PRD before UR approval
+- create PRD before required Brownfield Review is done or explicitly not_applicable
+- create PRD before Mode/Slice Decision is recorded
 - create SD before PRD approval
 - create TP while earlier gates block
+- suggest implementation immediately after `Approval: UR`
+- suggest implementation before Brownfield Review has explicitly selected `quick_task`
+- suggest implementation immediately after `Approval: PRD`
+- suggest implementation immediately after `Approval: SD`
+- treat "ok", "leg los", "go ahead", "approved" or similar wording as gate approval
 - perform full Brownfield Analysis unless explicitly requested
 - provide implementation snippets while implementation is gated
 - present QA or UAT as passed without evidence