create-agdf 0.5.0 → 0.6.1

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

@@ -0,0 +1,48 @@
+# AGDF Run State
+
+## Run Meta
+
+- control_state_version: 2
+- run_id:
+- lifecycle: active
+- revision: 1
+- revision_id:
+- mode: structured_delivery
+- current_gate: UR
+- decision: in_progress
+- owner: agent
+
+## Objective
+
+Describe the trustworthy outcome.
+
+## Current Control State
+
+| Question | Answer |
+|---|---|
+| What is known? |  |
+| What is approved? |  |
+| What is missing? |  |
+| What is the next allowed action? |  |
+| What is explicitly forbidden right now? |  |
+
+## Approvals
+
+| Gate | Status | Evidence |
+|---|---|---|
+| UR | missing |  |
+| PRD | missing |  |
+| SD | missing |  |
+| TP | missing |  |
+| QA | missing |  |
+| UAT | missing |  |
+
+## Evidence
+
+| Evidence | Source | Covers | Strength |
+|---|---|---|---|
+
+## Closeout
+
+- next_allowed_action: Draft the current allowed artefact and preserve evidence.
+- quality_outlook: Keep one mutable authority for this run.

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

@@ -1,6 +1,6 @@
 ---
 name: agdf-brownfield-analysis
-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.
+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
@@ -47,8 +47,8 @@ Do not mix both modes silently. Name the active mode in the output.
 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 `agdf-gate-check` permits `Brownfield Review` or the selected canonical run record names Brownfield Review as the next allowed action
+- after `agdf-gate-check` permits implementation preparation or the selected canonical run record 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

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

@@ -28,7 +28,7 @@ This skill is the primary operating path for gate judgement.
 
 First inspect the durable control state directly:
 
-- `.agdf/control/AGDF_RUN.md`
+- selected `.agdf/control/runs/<run_id>/RUN_STATE.md` (or legacy `AGDF_RUN.md` before explicit migration)
 - `.agdf/control/MASTER_BACKLOG.md`
 - `.agdf/control/SOT_REGISTRY.md`
 - `.agdf/control/CONTEXT_GRAPH.md`
@@ -47,7 +47,7 @@ npx --yes @agdf/cli@latest gate-check --json
 npx --yes @agdf/cli@latest delivery-map --json
 ```
 
-`init` creates the control scaffold. `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.
+`init` creates the control scaffold. `doctor` checks whether `.agdf/control/` is actionable. `agdf-gate-check` consumes that result and the selected canonical run record 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 reports are validators and JSON evidence, not the primary user experience, not a required ritual for normal work and not a second rule system. If a report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
@@ -124,14 +124,19 @@ If a status is not explicit, do not assume it is satisfied.
 12. If branch, workspace and durable artefacts disagree, do not choose a scope silently; report the ambiguity and ask for the smallest clarifying gate action.
 
 ## Output
-Keep the result short and operational:
-
-- **Current gate:** `<GateName or internal step>`
-- **Status:** `open | blocked`
-- **Allowed:** `<allowed outputs>`
-- **Forbidden:** `<forbidden outputs>`
-- **Missing approval:** `Approval: <GateName> | none`
-- **Next step:** `<single permissible next step>`
+Keep the result short and operational. Render the Runtime Contract's compact human-facing Run Status Card rather than a surface-specific summary:
+
+| Run status | Value |
+|---|---|
+| Status | `open | blocked` |
+| Current gate | `<GateName or internal step>` |
+| Allowed now | `<currently allowed outputs>` |
+| Blocked by | `<blocking condition or none>` |
+| Missing approval | `Approval: <GateName> | none` |
+| Next step | `<single permissible next step>` |
+| Quality outlook | `<next meaningful quality focus or none>` |
+
+When an approval is missing, also include `Next gate after approval` and `Allowed after approval` exactly as constrained by the Runtime Contract. Keep forbidden outputs, evidence and next-skill detail in the concise surrounding text when relevant; they are not extra status-card rows.
 
 If this skill creates or updates control artefacts, do not paste full file bodies into the chat.
 List paths, summarize the decision, name the blocker or approval needed, and keep the durable content in the files.

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

@@ -28,7 +28,7 @@ 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.
+When `.agdf/control/` is present, persist or link the OR under `.agdf/control/artefacts/<key>/OR.md` and reference it from the selected canonical `RUN_STATE.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

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

@@ -30,7 +30,8 @@ Do not add a separate `Quality outlook` line for pure Quick Tasks unless the tas
 ### Non-Normative Trivial Change Boundary
 
 A `quick_task` whose entire diff stays fully outside all of the following paths may close using only
-the compact output shape above, and must not create, rewrite or expand any of `AGDF_RUN.md`'s core
+the compact output shape above, and must not create, rewrite or expand any selected canonical
+`RUN_STATE.md` core
 sections (Run Meta, Objective, Current Control State, Source And Scope State, Run Status Card,
 Approvals, Artefacts, Mode/Slice Decision, Artefact Chain, Evidence, Missing Evidence, Risks, Context
 Graph Impact, Knowledge Persistence Decision, Closeout):
@@ -207,9 +208,10 @@ OR is not mandatory for a pure explanation, read-only inspection, small review,
 When in doubt, use a short OR-lite only if it clarifies gate state, evidence, risk, or the next permissible step.
 
 A `quick_task` fully inside the Non-Normative Trivial Change Boundary above stays exempt from the full
-`AGDF_RUN.md` ceremony even when it is otherwise a relevant run. If `AGDF_RUN.md` currently reflects
-another active run, append exactly one line to that run's `Prior Run Pointers` section noting what
-changed and that it is unrelated; do not edit any other section or any other existing line.
+selected-run ceremony even when it is otherwise a relevant run. If a selected canonical
+`RUN_STATE.md` currently reflects another scope, append exactly one line to that run's
+`Prior Run Pointers` section noting what changed and that it is unrelated; do not edit any other
+section or any other existing line.
 
 ## Gate Rules
 
@@ -225,7 +227,7 @@ changed and that it is unrelated; do not edit any other section or any other exi
 - Missing control files or missing current-state fields do not forbid the agent from preparing the current allowed artefact. They forbid later-gate work and implementation. For a fresh request, the default allowed work is to draft a minimal UR in the response and request `Approval: UR`. Initialize or write `.agdf/control/` only when the user explicitly asks for durable AGDF control state, the repository already uses `.agdf/control/` as its live working state, or a deterministic CLI/CI setup path is being executed.
 - `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.
+- 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 the selected canonical `RUN_STATE.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.
@@ -327,10 +329,18 @@ Relevant-run closeout must reconcile Context Graph impact before presenting a cl
 
 ## Control Scaffold
 
+### Run-Scoped Control State
+
+Canonical mutable run state lives at `.agdf/control/runs/<run_id>/RUN_STATE.md`, one file per run.
+Repository-level discovery is derived; do not maintain a writable active-run dashboard. Select with
+`--run`, then `AGDF_RUN_ID`, or automatically only when exactly one run is active. Ambiguity fails
+closed. Legacy `AGDF_RUN.md` is migration input or an explicitly rendered non-authoritative projection,
+never a second writable owner. Read-only commands must not migrate state.
+
 When a repository needs durable AGDF state, use the plugin-local `control/` scaffold as the starting point.
 
 - `config.json` stores project language preferences. Use `artifact_language` for generated AGDF artefacts and `chat_language` for user-facing responses unless the user explicitly asks otherwise. Runtime rules remain English.
-- `AGDF_RUN.md` is the current run dashboard.
+- `.agdf/control/runs/<run_id>/RUN_STATE.md` is the canonical current-run dashboard; legacy `AGDF_RUN.md` is migration input or an explicit non-authoritative projection.
 - `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.
@@ -378,8 +388,8 @@ They make the repository state checkable, but they do not replace the native ski
 
 ## 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.
+`delivery-map --json` is the machine-readable delivery picture for the selected canonical control state.
+It derives, but does not replace, the selected `RUN_STATE.md` and `MASTER_BACKLOG.md` state.
 
 It must expose:
 

package/generated/.opencode/agdf-runtime-contract.md

@@ -30,7 +30,8 @@ Do not add a separate `Quality outlook` line for pure Quick Tasks unless the tas
 ### Non-Normative Trivial Change Boundary
 
 A `quick_task` whose entire diff stays fully outside all of the following paths may close using only
-the compact output shape above, and must not create, rewrite or expand any of `AGDF_RUN.md`'s core
+the compact output shape above, and must not create, rewrite or expand any selected canonical
+`RUN_STATE.md` core
 sections (Run Meta, Objective, Current Control State, Source And Scope State, Run Status Card,
 Approvals, Artefacts, Mode/Slice Decision, Artefact Chain, Evidence, Missing Evidence, Risks, Context
 Graph Impact, Knowledge Persistence Decision, Closeout):
@@ -207,9 +208,10 @@ OR is not mandatory for a pure explanation, read-only inspection, small review,
 When in doubt, use a short OR-lite only if it clarifies gate state, evidence, risk, or the next permissible step.
 
 A `quick_task` fully inside the Non-Normative Trivial Change Boundary above stays exempt from the full
-`AGDF_RUN.md` ceremony even when it is otherwise a relevant run. If `AGDF_RUN.md` currently reflects
-another active run, append exactly one line to that run's `Prior Run Pointers` section noting what
-changed and that it is unrelated; do not edit any other section or any other existing line.
+selected-run ceremony even when it is otherwise a relevant run. If a selected canonical
+`RUN_STATE.md` currently reflects another scope, append exactly one line to that run's
+`Prior Run Pointers` section noting what changed and that it is unrelated; do not edit any other
+section or any other existing line.
 
 ## Gate Rules
 
@@ -225,7 +227,7 @@ changed and that it is unrelated; do not edit any other section or any other exi
 - Missing control files or missing current-state fields do not forbid the agent from preparing the current allowed artefact. They forbid later-gate work and implementation. For a fresh request, the default allowed work is to draft a minimal UR in the response and request `Approval: UR`. Initialize or write `.agdf/control/` only when the user explicitly asks for durable AGDF control state, the repository already uses `.agdf/control/` as its live working state, or a deterministic CLI/CI setup path is being executed.
 - `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.
+- 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 the selected canonical `RUN_STATE.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.
@@ -327,10 +329,18 @@ Relevant-run closeout must reconcile Context Graph impact before presenting a cl
 
 ## Control Scaffold
 
+### Run-Scoped Control State
+
+Canonical mutable run state lives at `.agdf/control/runs/<run_id>/RUN_STATE.md`, one file per run.
+Repository-level discovery is derived; do not maintain a writable active-run dashboard. Select with
+`--run`, then `AGDF_RUN_ID`, or automatically only when exactly one run is active. Ambiguity fails
+closed. Legacy `AGDF_RUN.md` is migration input or an explicitly rendered non-authoritative projection,
+never a second writable owner. Read-only commands must not migrate state.
+
 When a repository needs durable AGDF state, use the plugin-local `control/` scaffold as the starting point.
 
 - `config.json` stores project language preferences. Use `artifact_language` for generated AGDF artefacts and `chat_language` for user-facing responses unless the user explicitly asks otherwise. Runtime rules remain English.
-- `AGDF_RUN.md` is the current run dashboard.
+- `.agdf/control/runs/<run_id>/RUN_STATE.md` is the canonical current-run dashboard; legacy `AGDF_RUN.md` is migration input or an explicit non-authoritative projection.
 - `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.
@@ -378,8 +388,8 @@ They make the repository state checkable, but they do not replace the native ski
 
 ## 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.
+`delivery-map --json` is the machine-readable delivery picture for the selected canonical control state.
+It derives, but does not replace, the selected `RUN_STATE.md` and `MASTER_BACKLOG.md` state.
 
 It must expose:
 

package/generated/.opencode/agents/agdf-brownfield-analysis.md

@@ -47,8 +47,8 @@ Do not mix both modes silently. Name the active mode in the output.
 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 `agdf-gate-check` permits `Brownfield Review` or the selected canonical run record names Brownfield Review as the next allowed action
+- after `agdf-gate-check` permits implementation preparation or the selected canonical run record 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

package/generated/.opencode/agents/agdf-gate-check.md

@@ -28,7 +28,7 @@ This skill is the primary operating path for gate judgement.
 
 First inspect the durable control state directly:
 
-- `.agdf/control/AGDF_RUN.md`
+- selected `.agdf/control/runs/<run_id>/RUN_STATE.md` (or legacy `AGDF_RUN.md` before explicit migration)
 - `.agdf/control/MASTER_BACKLOG.md`
 - `.agdf/control/SOT_REGISTRY.md`
 - `.agdf/control/CONTEXT_GRAPH.md`
@@ -47,7 +47,7 @@ npx --yes @agdf/cli@latest gate-check --json
 npx --yes @agdf/cli@latest delivery-map --json
 ```
 
-`init` creates the control scaffold. `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.
+`init` creates the control scaffold. `doctor` checks whether `.agdf/control/` is actionable. `agdf-gate-check` consumes that result and the selected canonical run record 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 reports are validators and JSON evidence, not the primary user experience, not a required ritual for normal work and not a second rule system. If a report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
@@ -124,14 +124,19 @@ If a status is not explicit, do not assume it is satisfied.
 12. If branch, workspace and durable artefacts disagree, do not choose a scope silently; report the ambiguity and ask for the smallest clarifying gate action.
 
 ## Output
-Keep the result short and operational:
-
-- **Current gate:** `<GateName or internal step>`
-- **Status:** `open | blocked`
-- **Allowed:** `<allowed outputs>`
-- **Forbidden:** `<forbidden outputs>`
-- **Missing approval:** `Approval: <GateName> | none`
-- **Next step:** `<single permissible next step>`
+Keep the result short and operational. Render the Runtime Contract's compact human-facing Run Status Card rather than a surface-specific summary:
+
+| Run status | Value |
+|---|---|
+| Status | `open | blocked` |
+| Current gate | `<GateName or internal step>` |
+| Allowed now | `<currently allowed outputs>` |
+| Blocked by | `<blocking condition or none>` |
+| Missing approval | `Approval: <GateName> | none` |
+| Next step | `<single permissible next step>` |
+| Quality outlook | `<next meaningful quality focus or none>` |
+
+When an approval is missing, also include `Next gate after approval` and `Allowed after approval` exactly as constrained by the Runtime Contract. Keep forbidden outputs, evidence and next-skill detail in the concise surrounding text when relevant; they are not extra status-card rows.
 
 If this skill creates or updates control artefacts, do not paste full file bodies into the chat.
 List paths, summarize the decision, name the blocker or approval needed, and keep the durable content in the files.

package/generated/.opencode/agents/agdf-release-or.md

@@ -28,7 +28,7 @@ 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.
+When `.agdf/control/` is present, persist or link the OR under `.agdf/control/artefacts/<key>/OR.md` and reference it from the selected canonical `RUN_STATE.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

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

@@ -1,6 +1,6 @@
 {
   "name": "agdf",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Codex-first operating system for governed AI-assisted delivery.",
   "author": {
     "name": "Arndt Gold",

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

@@ -9,7 +9,8 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 | File | Purpose |
 |---|---|
 | `config.json` | Project language preference for generated AGDF artefacts and user-facing chat |
-| `templates/AGDF_RUN.md` | Template for current run state: mode, gate, approvals, evidence, risks, next allowed action |
+| `templates/RUN_STATE.md` | Canonical version-2 template for isolated per-run state |
+| `templates/AGDF_RUN.md` | Legacy migration-input and compatibility-projection template |
 | `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 |
@@ -27,6 +28,9 @@ Use this scaffold when a target repository should keep AGDF state outside chat h
 ```text
 .agdf/
   control/
+    runs/
+      <run_id>/
+        RUN_STATE.md
     config.json
     AGDF_RUN.md
     MASTER_BACKLOG.md
@@ -71,7 +75,13 @@ npx --yes @agdf/cli@latest gate-check --json
 
 ## Operating Rules
 
-- `AGDF_RUN.md` is the current run dashboard.
+- Canonical mutable state is isolated per run at `runs/<run_id>/RUN_STATE.md`. Run discovery is
+  derived; do not maintain a writable active-run index. Select explicitly with `--run` or
+  `AGDF_RUN_ID` when more than one run is active.
+- Migrate legacy state explicitly with `run-migrate`; read-only commands never migrate. A retained
+  `AGDF_RUN.md` is migration input or a non-authoritative projection, not a second writable owner.
+
+- The selected `runs/<run_id>/RUN_STATE.md` is the current run dashboard.
 - `config.json` stores the project preference for artefact and chat language; runtime rules stay English.
 - `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.
@@ -80,6 +90,8 @@ npx --yes @agdf/cli@latest gate-check --json
 - `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.
-- `AGDF_RUN.md` can be edited concurrently from different machines or sessions. Give it a `.gitattributes` entry (`.agdf/control/AGDF_RUN.md merge=union`, git's built-in union driver — no local `git config` registration needed, unlike a custom named driver) so concurrent edits merge automatically instead of blocking. Always re-run `doctor`/`gate-check` and visually skim the merged file after a merge or pull that could have touched it: a union merge on conflicting lines (e.g. two different `current_gate` values) keeps both lines rather than erroring, and `doctor` reads only the first match per field, so it will not by itself flag that duplication — it only catches missing or structurally malformed fields.
+- Never assign `merge=union` to canonical `runs/<run_id>/RUN_STATE.md` records. Concurrent edits to the
+  same run must remain conflict-visible; independent runs naturally change different files. After a
+  merge or pull, rerun `doctor` and `gate-check` for the selected run.
 
 Do not duplicate full product documentation in this scaffold. Link to the authoritative artefact instead.

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

@@ -0,0 +1,48 @@
+# AGDF Run State
+
+## Run Meta
+
+- control_state_version: 2
+- run_id:
+- lifecycle: active
+- revision: 1
+- revision_id:
+- mode: structured_delivery
+- current_gate: UR
+- decision: in_progress
+- owner: agent
+
+## Objective
+
+Describe the trustworthy outcome.
+
+## Current Control State
+
+| Question | Answer |
+|---|---|
+| What is known? |  |
+| What is approved? |  |
+| What is missing? |  |
+| What is the next allowed action? |  |
+| What is explicitly forbidden right now? |  |
+
+## Approvals
+
+| Gate | Status | Evidence |
+|---|---|---|
+| UR | missing |  |
+| PRD | missing |  |
+| SD | missing |  |
+| TP | missing |  |
+| QA | missing |  |
+| UAT | missing |  |
+
+## Evidence
+
+| Evidence | Source | Covers | Strength |
+|---|---|---|---|
+
+## Closeout
+
+- next_allowed_action: Draft the current allowed artefact and preserve evidence.
+- quality_outlook: Keep one mutable authority for this run.

package/generated/plugins/agdf/hooks/session-start.sh

@@ -6,6 +6,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 META_DIR="$(cd "${SCRIPT_DIR}/../meta" && pwd)"
 ROUTER="${META_DIR}/agdf-agent-router.md"
 CONSTITUTION="${META_DIR}/agdf-constitution.md"
+RUNTIME_CONTRACT="${META_DIR}/agdf-runtime-contract.md"
 CONFIG_PATH="${PWD}/.agdf/control/config.json"
 
 CONFIG_HINT="Project config: .agdf/control/config.json not found. Use npx --yes @agdf/cli@latest config --language de|en to persist the project language."
@@ -40,4 +41,5 @@ Do not print the full router or constitution unless the user asks for them.
 Source of truth:
 - ${ROUTER}
 - ${CONSTITUTION}
+- ${RUNTIME_CONTRACT}
 EOF

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

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "agdf",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "displayName": "AI Governance & Delivery Framework",
   "developerName": "Arndt Gold",
   "description": "Codex-first operating system for governed AI-assisted delivery.",

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

@@ -30,7 +30,8 @@ Do not add a separate `Quality outlook` line for pure Quick Tasks unless the tas
 ### Non-Normative Trivial Change Boundary
 
 A `quick_task` whose entire diff stays fully outside all of the following paths may close using only
-the compact output shape above, and must not create, rewrite or expand any of `AGDF_RUN.md`'s core
+the compact output shape above, and must not create, rewrite or expand any selected canonical
+`RUN_STATE.md` core
 sections (Run Meta, Objective, Current Control State, Source And Scope State, Run Status Card,
 Approvals, Artefacts, Mode/Slice Decision, Artefact Chain, Evidence, Missing Evidence, Risks, Context
 Graph Impact, Knowledge Persistence Decision, Closeout):
@@ -207,9 +208,10 @@ OR is not mandatory for a pure explanation, read-only inspection, small review,
 When in doubt, use a short OR-lite only if it clarifies gate state, evidence, risk, or the next permissible step.
 
 A `quick_task` fully inside the Non-Normative Trivial Change Boundary above stays exempt from the full
-`AGDF_RUN.md` ceremony even when it is otherwise a relevant run. If `AGDF_RUN.md` currently reflects
-another active run, append exactly one line to that run's `Prior Run Pointers` section noting what
-changed and that it is unrelated; do not edit any other section or any other existing line.
+selected-run ceremony even when it is otherwise a relevant run. If a selected canonical
+`RUN_STATE.md` currently reflects another scope, append exactly one line to that run's
+`Prior Run Pointers` section noting what changed and that it is unrelated; do not edit any other
+section or any other existing line.
 
 ## Gate Rules
 
@@ -225,7 +227,7 @@ changed and that it is unrelated; do not edit any other section or any other exi
 - Missing control files or missing current-state fields do not forbid the agent from preparing the current allowed artefact. They forbid later-gate work and implementation. For a fresh request, the default allowed work is to draft a minimal UR in the response and request `Approval: UR`. Initialize or write `.agdf/control/` only when the user explicitly asks for durable AGDF control state, the repository already uses `.agdf/control/` as its live working state, or a deterministic CLI/CI setup path is being executed.
 - `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.
+- 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 the selected canonical `RUN_STATE.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.
@@ -327,10 +329,18 @@ Relevant-run closeout must reconcile Context Graph impact before presenting a cl
 
 ## Control Scaffold
 
+### Run-Scoped Control State
+
+Canonical mutable run state lives at `.agdf/control/runs/<run_id>/RUN_STATE.md`, one file per run.
+Repository-level discovery is derived; do not maintain a writable active-run dashboard. Select with
+`--run`, then `AGDF_RUN_ID`, or automatically only when exactly one run is active. Ambiguity fails
+closed. Legacy `AGDF_RUN.md` is migration input or an explicitly rendered non-authoritative projection,
+never a second writable owner. Read-only commands must not migrate state.
+
 When a repository needs durable AGDF state, use the plugin-local `control/` scaffold as the starting point.
 
 - `config.json` stores project language preferences. Use `artifact_language` for generated AGDF artefacts and `chat_language` for user-facing responses unless the user explicitly asks otherwise. Runtime rules remain English.
-- `AGDF_RUN.md` is the current run dashboard.
+- `.agdf/control/runs/<run_id>/RUN_STATE.md` is the canonical current-run dashboard; legacy `AGDF_RUN.md` is migration input or an explicit non-authoritative projection.
 - `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.
@@ -378,8 +388,8 @@ They make the repository state checkable, but they do not replace the native ski
 
 ## 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.
+`delivery-map --json` is the machine-readable delivery picture for the selected canonical control state.
+It derives, but does not replace, the selected `RUN_STATE.md` and `MASTER_BACKLOG.md` state.
 
 It must expose:
 

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

@@ -1,6 +1,6 @@
 ---
 name: brownfield-analysis
-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.
+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
@@ -47,8 +47,8 @@ Do not mix both modes silently. Name the active mode in the output.
 13. Specification archive migrations must follow the archive index if present.
 
 ## When To Use
-- after `gate-check` permits `Brownfield Review` or live `.agdf/control/AGDF_RUN.md` names Brownfield Review as the next allowed action
-- after `gate-check` permits implementation preparation or live `.agdf/control/AGDF_RUN.md` already names Brownfield Analysis as the next allowed action
+- after `gate-check` permits `Brownfield Review` or the selected canonical run record names Brownfield Review as the next allowed action
+- after `gate-check` permits implementation preparation or the selected canonical run record 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

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

@@ -28,7 +28,7 @@ This skill is the primary operating path for gate judgement.
 
 First inspect the durable control state directly:
 
-- `.agdf/control/AGDF_RUN.md`
+- selected `.agdf/control/runs/<run_id>/RUN_STATE.md` (or legacy `AGDF_RUN.md` before explicit migration)
 - `.agdf/control/MASTER_BACKLOG.md`
 - `.agdf/control/SOT_REGISTRY.md`
 - `.agdf/control/CONTEXT_GRAPH.md`
@@ -47,7 +47,7 @@ npx --yes @agdf/cli@latest gate-check --json
 npx --yes @agdf/cli@latest delivery-map --json
 ```
 
-`init` creates the control scaffold. `doctor` checks whether `.agdf/control/` is actionable. `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.
+`init` creates the control scaffold. `doctor` checks whether `.agdf/control/` is actionable. `gate-check` consumes that result and the selected canonical run record 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 reports are validators and JSON evidence, not the primary user experience, not a required ritual for normal work and not a second rule system. If a report says `blocked`, do not continue with later-gate artefacts until the reported blocker is resolved.
@@ -124,14 +124,19 @@ If a status is not explicit, do not assume it is satisfied.
 12. If branch, workspace and durable artefacts disagree, do not choose a scope silently; report the ambiguity and ask for the smallest clarifying gate action.
 
 ## Output
-Keep the result short and operational:
-
-- **Current gate:** `<GateName or internal step>`
-- **Status:** `open | blocked`
-- **Allowed:** `<allowed outputs>`
-- **Forbidden:** `<forbidden outputs>`
-- **Missing approval:** `Approval: <GateName> | none`
-- **Next step:** `<single permissible next step>`
+Keep the result short and operational. Render the Runtime Contract's compact human-facing Run Status Card rather than a surface-specific summary:
+
+| Run status | Value |
+|---|---|
+| Status | `open | blocked` |
+| Current gate | `<GateName or internal step>` |
+| Allowed now | `<currently allowed outputs>` |
+| Blocked by | `<blocking condition or none>` |
+| Missing approval | `Approval: <GateName> | none` |
+| Next step | `<single permissible next step>` |
+| Quality outlook | `<next meaningful quality focus or none>` |
+
+When an approval is missing, also include `Next gate after approval` and `Allowed after approval` exactly as constrained by the Runtime Contract. Keep forbidden outputs, evidence and next-skill detail in the concise surrounding text when relevant; they are not extra status-card rows.
 
 If this skill creates or updates control artefacts, do not paste full file bodies into the chat.
 List paths, summarize the decision, name the blocker or approval needed, and keep the durable content in the files.

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

@@ -28,7 +28,7 @@ It reports:
 Use `../../meta/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.
+When `.agdf/control/` is present, persist or link the OR under `.agdf/control/artefacts/<key>/OR.md` and reference it from the selected canonical `RUN_STATE.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

package/lib/control-state/aggregate.js

@@ -0,0 +1,18 @@
+const STATUS_RANK = { pass: 0, warn: 1, revise: 2, block: 3 };
+
+export function aggregate(results, { allowNoActiveRuns = false } = {}) {
+  const runs = [...results].sort((left, right) =>
+    left.run_id.localeCompare(right.run_id),
+  );
+  const status = runs.length
+    ? runs.reduce(
+        (current, run) =>
+          STATUS_RANK[run.status] > STATUS_RANK[current] ? run.status : current,
+        "pass",
+      )
+    : allowNoActiveRuns
+      ? "pass"
+      : "revise";
+
+  return { status, runs };
+}