create-agdf 0.2.3 → 0.2.5

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/.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/UR.md

@@ -32,7 +32,7 @@ Which existing repository artefacts, docs, code paths or decisions must be respe
 
 ## 7. Risks And Unknowns
 
-Which questions must PRD, SD or Brownfield Analysis clarify later?
+Which questions must Brownfield Review, PRD, SD or later implementation-preparation Brownfield Analysis clarify?
 
 ## 8. Next Step
 

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,30 +15,41 @@ 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
 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 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 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.
+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 +62,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 +70,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, evidenced and recorded.
 
 ## Workflow
 1. Identify affected tasks and scope.
@@ -92,9 +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:
@@ -116,3 +133,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

@@ -19,59 +19,54 @@ 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.
 
-## 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 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.
+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`.
+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 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 |
+## Gate Evaluation
 
 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.
+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
@@ -93,6 +88,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
@@ -107,6 +104,9 @@ If a status is not explicit, do not assume it is satisfied.
 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.
+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:
@@ -122,11 +122,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

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

@@ -28,9 +28,11 @@ It reports:
 Use `../agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
 
 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.
@@ -51,6 +53,8 @@ OR-specific output must make gate status, delivered and intentionally not delive
 - 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:
 
@@ -77,15 +81,16 @@ If information is missing, state the gap instead of guessing.
 2. Determine report depth:
    - `OR-lite`: gate status, allowed/forbidden outputs, missing approval, next step
    - `OR-full`: also delivered artefacts, TP coverage, Brownfield fit, solution integrity, risks, fallbacks, QA/UAT status
-3. Record delivered vs intentionally not delivered content.
-4. Summarize TP coverage if a TP exists.
-5. Summarize Brownfield fit and solution integrity if reviewed.
-6. Summarize tests and verification.
-7. Summarize documentation and Context Graph impact if relevant.
-8. Name retained fallbacks and exit criteria.
-9. Set exactly one next permissible step.
-10. Set exactly one quality outlook.
-11. State whether `agdf-delivery-closeout` is the next operational handoff step when code changes exist and the delivery state allows it.
+3. Record the selected `Report mode` and durable OR target or link when `.agdf/control/` exists.
+4. Record delivered vs intentionally not delivered content.
+5. Summarize TP coverage if a TP exists.
+6. Summarize Brownfield fit and solution integrity if reviewed.
+7. Summarize tests and verification.
+8. Summarize documentation and Context Graph impact if relevant.
+9. Name retained fallbacks and exit criteria.
+10. Set exactly one next permissible step.
+11. Set exactly one quality outlook.
+12. State whether `agdf-delivery-closeout` is the next operational handoff step when code changes exist and the delivery state allows it.
 
 ## Output
 Use a compact structure:
@@ -93,6 +98,8 @@ Use a compact structure:
 ```text
 ## OR
 - gate:
+- report_mode:
+- artefact:
 - status:
 - delivered:
 - intentionally_not_delivered:

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

@@ -15,26 +15,97 @@ 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`
-- Internal mandatory steps: `Brownfield Analysis -> CD+Tests -> CR -> OR`
+- Internal mandatory steps: `Brownfield Review -> Mode/Slice Decision -> Brownfield Analysis -> CD+Tests -> CR -> OR`
 - Exact approval formula: `Approval: <GateName>`
 - 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.
+- Implicit consent is not approval. Phrases such as "ok", "go ahead", "do it", "approved", "continue", "leg los" or "looks good" are work intent, not gate 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 of one user gate permits work on the next allowed gate artefact or required internal step only. It does not permit implementation unless the approved gate is `TP` and required internal implementation prerequisites are satisfied.
+- 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 Brownfield Analysis and then CD+Tests when Brownfield evidence supports it.
+- `Approval: TP` permits implementation-preparation 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`.
 - `agdf-release-or` reports the run, but does not replace QA or produce the operative commit/PR handoff.
 - `agdf-delivery-closeout` owns the operative Git handoff text when QA/OR/UAT state allows it.
 
+## Brownfield Review After G-00
+
+After an approved and durable UR, perform a lightweight `Brownfield Review` before PRD when Brownfield, UI, UX, admin, runtime, policy, persistence, architecture, ownership or source-of-truth impact is possible.
+
+This review is not a new user approval gate, not PRD, not SD, not TP and not implementation permission.
+It is the sizing and routing step that decides how much later gate discipline is actually needed.
+
+Its output is limited to:
+
+- workstream or follow-up-slice classification
+- `Mode/Slice Decision`: `quick_task | structured_slice | structured_delivery | block`
+- affected existing owners, source-of-truth artefacts, contracts, policies, runtime paths or tests
+- reuse-before-create risks and parallel-structure risks
+- open questions that PRD or SD must resolve
+- whether implementation-preparation Brownfield Analysis will also be needed after TP
+
+Mode/Slice Decision rules:
+
+- `quick_task`: use only when Brownfield Review shows a narrow local change, no new product semantics beyond the approved UR, no architecture/policy/persistence/contract expansion, and evidence is sufficient to proceed with a small implementation plus relevant checks.
+- `structured_slice`: use when some formal artefacts are needed, but they can stay intentionally small and scoped to the approved slice.
+- `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:
@@ -68,12 +139,38 @@ 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.
+- OR reports live under `.agdf/control/artefacts/<key>/OR.md` when a run closeout is steering-relevant or should be auditable beyond the chat.
 
 The scaffold is not a second documentation site. Link to authoritative artefacts instead of copying them.
 
+## Native Runtime
+
+AGDF must work natively through the plugin router, skills and live `.agdf/control/` artefacts.
+Agents should read the live control state and apply the gate model directly before reaching for helper commands.
+
+Machine-readable commands such as `doctor --json`, `gate-check --json` and `delivery-map --json` are validators and automation interfaces.
+They make the repository state checkable, but they do not replace the native skill workflow or the durable control artefacts.
+
+## Delivery Map
+
+`delivery-map --json` is the machine-readable delivery picture for the active control state.
+It derives, but does not replace, the live `.agdf/control/AGDF_RUN.md` and `MASTER_BACKLOG.md` state.
+
+It must expose:
+
+- approved or active artefacts and approvals
+- `UR -> PRD -> SD -> TP -> QA_REPORT` relationships
+- evidence refs, missing evidence and declared risks
+- Context Graph impact and gate effect
+- findings that explain why the delivery picture is `pass | warn | revise | block`
+
+Missing relationship evidence in the Artefact Chain is at least `revise` once the related gate artefact is approved or passed.
+Declared missing evidence, declared risk or Context Graph gate effect may escalate the delivery map to `warn`, `revise` or `block`.
+
 ## Skill Output
 
 Every skill output should be as short as possible and as concrete as needed.