create-agdf 0.20.2 → 0.31.0

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

@@ -1,125 +1,51 @@
 # AGDF Control Scaffold
 
-AGDF is primarily a control system for AI-assisted delivery. The skills guide the agent during a run; these files make the run state durable in a repository.
+Explicit initialization creates `control_layout: "run-folders-v1"`. This is the only supported layout; Runs use control-state version 4. Missing, old or unknown layouts and Run versions are unsupported. Inspection preserves their bytes and reports the incompatibility. There is no migration, conversion, legacy projection, automatic reset or fallback.
 
-Use this scaffold when a target repository should keep AGDF state outside chat history and tool memory.
-
-## Files
-
-| File | Purpose |
-|---|---|
-| `config.json` | Project language preference for generated AGDF artefacts and user-facing chat |
-| `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 |
-| `templates/artefacts/VERIFIED_CHANGE.md` | Compact fail-closed record for an eligible Verified Change |
-| `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 |
-
-## Recommended Target Layout
+## Current layout
 
 ```text
-.agdf/
-  control/
-    runs/
-      <run_id>/
-        RUN_STATE.md
-    config.json
-    AGDF_RUN.md
-    MASTER_BACKLOG.md
-    artefacts/
-      <work-item>/
-        UR.md
-        BROWNFIELD_REVIEW.md
-        PRD.md
-        SD.md
-        TP.md
-        QA_REPORT.md
-        OR.md
-    SOT_REGISTRY.md
-    CONTEXT_GRAPH.md
-    AGENT_QUALITY_CONTRACTS.json
+.agdf/control/
+  config.json
+  README.md
+  SOT_REGISTRY.md
+  CONTEXT_GRAPH.md
+  AGENT_QUALITY_CONTRACTS.json
+  BRAND.md
+  templates/
+  planned/<plan_id>/UR.md
+  runs/<run_id>/
+    RUN_STATE.md
+    documents/                 UR, analyses, PRD, SD, TP, reviews, QA_REPORT, OR
+    evidence/                  bounded supporting evidence
+    control/
+      presentations/           exact decision documents and optional preview snapshots
+      RUN_STEP_PENDING.json    original operation intent, only while pending
+    history/
+      planning/UR.md           immutable handed-off planning source
+      revisions/<operation_id>/manifest.json
+      revisions/<operation_id>/files/
 ```
 
-Keep these files small and reviewable. They are control artefacts, not a second documentation site.
-
-Create the live files with:
-
-```bash
-npx --yes @agdf/cli@latest init
-```
+Configuration, templates and curated project context stay project-wide. A multi-Run closure preview is a target-wide decision proposal under `closure-previews/`; it changes no Run until deliberately applied. Run-owned outputs never use a separate top-level artefacts directory.
 
-If only the project language preference is missing or should change after plugin installation, write just the config file:
+`BRAND.md` starts as a neutral English worksheet. Complete it with the project's
+own design intent and declare the finished source in `SOT_REGISTRY.md` when it is
+authoritative for design work.
 
-```bash
-npx --yes @agdf/cli@latest config --language en
-```
+`RUN_STATE.md` keeps identity, objective, mode and typed decisions, source bindings and operations. Approval status, current gate, current document references, relationship chains, evidence summaries and inventory are derived when read. They are not separately writable tables or a second state file. A binding embeds its reviewer attestation; no separate RECORD/REVIEW JSON repeats its mapping. A planned handoff records its source in the creation receipt and immutable planning snapshot, without an origin JSON copy.
 
-Then check whether the live state is actionable:
+Create a fresh scaffold in an explicitly confirmed existing Git repository:
 
-```bash
-agdf doctor
-agdf doctor --json
-agdf gate-check --json
+```sh
+create-agdf init --dir /absolute/project --language en
+create-agdf doctor --dir /absolute/project --json
 ```
 
-`doctor` does not replace agent judgment. It catches basic control failures: missing live files, missing current gate, missing next allowed action, empty evidence, empty backlog pointer, empty source-of-truth registry, duplicate active SoT rows and invalid quality contracts.
-`gate-check` consumes the doctor result and live run state to report whether the next process step is `open` or `blocked`.
-
-## Operating Rules
-
-- 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. When several runs are active, discovery
-  presents the most recently updated run first and lists the others, but requires an explicit run
-  selection for read-only status or explicit run-selection requests. Implementation intake first
-  provides canonical UR evidence to the coding agent for scope assignment, even with one active
-  run: resume one same-scope continuation, start a new UR run for an independent scope, or clarify
-  genuinely overlapping work. If no active run exists during a status request, ask whether to start
-  one or do something else. Status never creates a run. `updated_at` is recorded with
-  every canonical run write; older runs use file modification time until their next recorded update.
-- 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.
-- A run created by `run-create` is sealed. Record every change to it or to a listed artefact with
-  `run-update`, and record exact gate replies only with `run-approve`; an unrecorded edit blocks
-  `doctor` and `gate-check` until it is recorded.
-  If a run lists its own `RUN_STATE.md`, the seal covers its body directly and uses a self-reference
-  marker for that artefact entry. This avoids circular on-disk hashing; references to other runs
-  remain fully hashed. Old self-reference failures require a verified restoration, never a blind re-seal.
-- Record the standard small-path steps with one `run-step` call each instead of editing the run state
-  and `MASTER_BACKLOG.md` by hand: `--step ur --title` after writing `artefacts/<run_id>/UR.md`;
-  `--step route --route <mode> --reason --evidence` after writing `BROWNFIELD_REVIEW.md`;
-  `--step evidence` for test or check results; `--step review --decision --evidence` for Code Review;
-  and `--step closeout --result --evidence --risk --next` to close a `quick_task` with OR-lite. Each
-  call maintains the tables, the backlog pointer and the next allowed action and prints the next step.
-
-- 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, Verified Change execution or Quick Task execution is chosen.
-- UR, PRD, SD, TP and QA decisions require durable artefacts or links to the authoritative repository source of truth before the next gate can open.
-- OR records the run closeout and next permissible step; it does not approve later gates.
-- `SOT_REGISTRY.md` decides which document owns which domain.
-- `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.
-- 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.
+Initialization creates no Run or approval. `config` changes preferences through the existing configuration owner; it does not convert a store. Use current `run-create`, `run-step`, `run-present`, `run-approve`, `run-revise` and `run-close`, or their fixed MCP control groups. Read `operation-contract` for complete current inputs. Every mutation retains its original operation UUID and exact binding for replay; a successful historical receipt is not permission for a new effect.
 
-Do not duplicate full product documentation in this scaffold. Link to the authoritative artefact instead.
+Material staging is private and temporary. Record documents through the owning command, which publishes the file and canonical record together. Never edit a bound document or Run by hand and then reseal it. An allowed unapproved draft replacement needs current reviewed material and a fresh presentation. Approved source changes require the current source-revision preview and exact deliberate confirmation.
 
-## Planned outputs during recovery
+`doctor` and `gate-check` inspect integrity and current prerequisites; they do not create approvals. A prepared presentation binds exact reviewed material. Only a new deliberate reply to that presentation records a gate decision. The local cooperative seal detects unrecorded changes; it is not an independent signature or proof of human identity.
 
-A missing file explicitly declared `missing` or `pending` under the selected run's own
-`.agdf/control/artefacts/<run_id>/` directory is a planned output, not lost completed evidence.
-Recovery retains its path and absence in the integrity snapshot and leaves its status pending.
-It does not create evidence or approve a gate. Completed or ready evidence, unsafe paths and
-descriptive placeholders still require repair. Creating a planned file after a recovery preview
-invalidates that preview; creating it after recovery changes the seal until a canonical update.
+Planned needs are independent URs. The optional planning extension can author them; Core owns their admission, current inventory and explicit handoff. Planning neither starts a Run nor approves a gate. See [planned URs](planned-urs.md).

package/generated/.agdf/control/planned-urs.md

@@ -0,0 +1,95 @@
+# Planned URs in the current Run model
+
+Canonical initialization includes an empty `.gitkeep` in `runs/` and `planned/`
+so Git checkouts retain empty stores. The planned inventory ignores only this
+exact marker when it is an empty regular file; other unsupported entries remain
+findings. The marker is neither a planned UR nor a lock or approval record.
+
+New projects use `control_layout: "run-folders-v1"`. Each planned need lives in
+`.agdf/control/planned/<plan_id>/UR.md`, with exactly one initial `Planning schema:
+planned-ur-v1`, `Planning id:` and `Planning priority: high|normal|low` scalar.
+The existing UR template and `ur-definition` owner apply in both planning and Run
+mode. The entire canonical file supplies source identity; edits require its digest.
+Planning remains UR-only, may save incomplete clarification and grants no approval.
+
+Core supports this without an extension. The optional **AGDF Planning** Codex
+package organizes dialogue and delegates every write and readiness check to Core.
+It contains no second runtime/MCP server, UR template, control engine or saved list.
+Its supported qualification target for this change is Codex CLI; repository tests
+do not establish native support for Desktop/Cockpit or another host.
+
+## Core CLI
+
+Use an explicit absolute project directory. A new capture derives its identity
+from the original UUID; the human supplies a need rather than a technical ID.
+
+```sh
+create-agdf init --dir /absolute/project
+create-agdf planned --dir /absolute/project --action list
+create-agdf planned --dir /absolute/project --action create --evidence /absolute/UR.md --priority high --operation <uuid>
+create-agdf planned --dir /absolute/project --action inspect --plan-id <returned-plan-id>
+create-agdf planned --dir /absolute/project --action replace --plan-id <id> --source-digest <inspected-sha256> --evidence /absolute/updated-UR.md --operation <uuid>
+create-agdf planned --dir /absolute/project --action start --plan-id <id> --source-digest <inspected-sha256> --operation <uuid>
+```
+
+Replacement edits the same file and keeps its planning identity. Starting requires
+a complete, clarified UR and deliberate selected-source handoff. Exactly one Run
+receives its initial unapproved `documents/UR.md` and immutable
+`history/planning/UR.md`. The creation receipt owns its origin binding; no separate
+origin JSON is written. Retrying the original UUID returns that Run; a later start
+of the same source also refers to it. After transfer, planning writes reject edits;
+active source revision belongs to the Run. Normal UR review/approval still follows.
+The planning-local `TRANSFER.json` is a transfer receipt protecting the source
+from reuse after its Run becomes unavailable. It is not origin authority or a
+maintained inventory; an unconfirmed marker is reported rather than trusted.
+
+`inventory` combines planned needs and canonical Runs. Planning order is priority,
+normalized title and identity; Runs retain existing Core ordering. Transferred
+sources are references on the resulting Run, not another undertaking. Readers
+never repair, migrate or persist a list. Partial/malformed/unavailable sources stay
+visible separately from empty inventory. Cockpit source selectors are opaque,
+snapshot-bound and read-only; planning views have no gate approval action.
+
+## MCP and authoring
+
+The fixed groups remain. `agdf_inspect` exposes `planned-inventory`,
+`planned-entry`, planning-scoped `authoring-inputs` and original operation status.
+`agdf_record` exposes `planned_material.stage`, `planned_ur.create` and CAS
+`planned_ur.replace`; `agdf_run` exposes `run.create_from_planned`.
+Use operation-contract for the exact variant and all required envelope fields.
+Planning uses `planning: {plan_id, expected_digest}` instead of Run/revision;
+mixed scopes and cross-source material grants are rejected. Material/source caps
+remain 128 KiB, chunks 16 KiB, requests 64 KiB. Read all authoring input pages.
+
+Dispatch the existing `ur-definition` with explicit planning scope. Run mode and
+gate semantics retain their owners. Missing capability is a dependency diagnosis,
+not permission to construct a runtime, use shell fallback or fabricate a Run.
+
+Install the extension deliberately after compatible Core:
+
+```sh
+create-agdf codex --package planning --plugin-only
+codex plugin remove agdf-planning@agdf-planning
+```
+
+Core metadata must expose `planned-ur-v1` protocol 1. Fresh-session tool capability
+checks additionally detect disabled or missing Core. Removing the extension does
+not remove Core or project control. Neither planning nor native tests authorize a
+global installation, authentication change, release or Git operation.
+
+## Current-format boundary
+
+Only explicit `run-folders-v1`, version-4 Runs and current wrapped operation
+records are supported. Older layouts and record versions are reported as
+unsupported without mutation. There is no layout migration or legacy fallback.
+Use a fresh target for current work; preserve unsupported data separately.
+
+A handoff publishes one unapproved Run with documents/UR.md and the exact
+immutable history/planning/UR.md snapshot. Its creation receipt binds that source;
+no separate origin JSON or current-pointer table is maintained. Replay keeps the
+original UUID and selected source digest. Pending recovery validates its captured
+owned files before completing or rolling back the original effect.
+
+Current Run mutations use independent Run/resource locks and wrapped version-7
+journals. Another valid Run journal does not exclude unrelated work. Unknown
+ownership, unsupported journals or changed bytes stop recovery without deletion.

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

@@ -0,0 +1,28 @@
+# Brand and Design Intent
+
+Complete this worksheet with confirmed project decisions. Declare the completed
+profile in `SOT_REGISTRY.md` when it is the project's authoritative design source.
+
+## Owner and scope
+
+Name the accountable owner, the product, and the surfaces and audiences covered.
+
+## Design intent
+
+Describe what people should understand, feel, or be able to do when using the
+product. Tie each priority to a concrete user task or situation.
+
+## Information and visual priorities
+
+Explain what deserves emphasis in relevant states and how the project balances
+competing priorities. Record any confirmed constraints and their sources.
+
+## Observable checks
+
+For each applicable priority, name the scenario, the expected observable outcome,
+and the evidence that would verify it. Record open decisions with their owners.
+
+## Related sources
+
+Link the project's design system, implementation values, and brand usage policy
+where applicable.

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

@@ -1,93 +1,44 @@
 # AGDF Run State
 
-## Run Meta
-
-- control_state_version: 2
-- run_id:
-- lifecycle: active
-- revision: 1
-- revision_id:
-- updated_at:
-- mode: structured_delivery
-- current_gate: UR
-- decision: in_progress
-- owner: agent
+Core creates the canonical version-4 document and its identity, revision and seals.
+This template describes authored fields; do not copy it as an initialized Run.
+Typed records are appended only by their owning current commands. Derived control,
+approval, document, relationship and evidence tables are rendered on inspection.
 
 ## 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? |  |
+## Mode/Slice Decision
 
-## Approvals
+- scope_reason:
+- evidence:
 
-| Gate | Status | Evidence |
-|---|---|---|
-| UR | missing |  |
-| PRD | missing |  |
-| SD | missing |  |
-| TP | missing |  |
-| QA | missing |  |
-| UAT | missing |  |
+The Run Meta mode is the single routing fact, recorded with the Brownfield Review.
 
-## Artefacts
+## Relationships
 
-| Type | Path | Status | Notes |
+| From | Relationship | To | Evidence |
 |---|---|---|---|
-| UR |  | draft |  |
-| Brownfield Review |  | missing |  |
-| Verified Change |  | missing |  |
-| PRD |  | missing |  |
-| SD |  | missing |  |
-| TP |  | missing |  |
-| Brownfield Analysis |  | missing |  |
-| CD+Tests |  | missing |  |
-| CR |  | missing |  |
-| QA |  | missing |  |
-
-## Mode/Slice Decision
 
-- decision: `quick_task | verified_change | structured_slice | structured_delivery | block`
-- required_next_gate:
-- scope_reason:
-- evidence:
+Only independent Parent/programme relationships are authored here. Document
+source relationships and UR approval relationships derive from typed bindings.
 
 ## Parent Reconciliation Handoff
 
-Optional. Omit this section when no explicit `OR | reconciles_with | parent_run:<run_id>` Artefact
-Chain row exists. The relationship row owns the Parent ID and evidence; do not copy them here.
+Optional: use only with an evidenced OR reconciles_with parent_run relationship.
 
 - parent_reconciliation_disposition: `action_required | accepted_open`
 - parent_reconciliation_next_action:
 
 ## Programme Aggregation Readiness
 
-Optional. Use only on an explicit Parent/programme run with evidenced
-`Aggregate | includes | child_run:<run_id>` rows.
+Optional: use only with evidenced Aggregate includes child_run relationships.
 
 - programme_acceptance_ref:
 - programme_aggregation_evidence:
 - programme_aggregation_missing_evidence: `none`
 
-## Artefact Chain
-
-| From | Relationship | To | Evidence |
-|---|---|---|---|
-
-## 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.
+- quality_outlook:

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

@@ -69,6 +69,17 @@ visible feedback, blocker/failure behavior, recovery/next action, observable suc
 evidence. Specify observable behavior, not implementation. Do not leave the section empty or retain
 placeholders when requesting approval.
 
+Use separate field names; never combine them (for example,
+`observable_success_required_evidence` is not `observable_success`). For same-language approval,
+each criterion needs at least one nonempty `observable_success`, `visible_feedback` or
+`expected_effective_state`. Keep applicable UX fields separate as well. Example:
+
+```markdown
+- criterion_id: AC-001
+  - observable_success: A later list command shows the saved task unchanged.
+  - required_evidence: A real CLI test across separate processes.
+```
+
 ## 6. Non-Goals
 
 What remains out of scope?

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

@@ -25,6 +25,10 @@ Use stable IDs. If no binding design decision is needed, record one reasoned bul
 When a decision selects or changes external technology (framework, library, API, protocol,
 service or major version), name the checked authoritative source, version and check date in its
 rationale.
+Quoted CLI arguments such as `done <id>` are literal syntax. In a decision clause, a labelled
+inline JSON schema/example may use quoted type metavariables such as `"<uuid>"` and
+`"<non-empty string>"`; keep actual choices, rationale and consequence concrete. The complete
+notation and unresolved-prompt boundary are defined in `meta/contracts/sd-definition.md`.
 
 ## 4. Integration Points
 

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

@@ -27,7 +27,7 @@ What is included in this first slice?
 Preserve explicitly requested clarification deliverables such as a UI preview: purpose, user task,
 relevant scenarios, required interaction/format and timing. Distinguish a required deliverable from
 an optional aid; do not invent a preview requirement. The later UX step retains a run-bound preview
-under `.agdf/control/artefacts/<run_id>/previews/`; UR authoring records the need only.
+under `.agdf/control/runs/<run_id>/evidence/previews/`; UR authoring records the need only.
 
 ## 4. Non-Goals
 

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

@@ -1,7 +1,7 @@
 # UX Intent Definition: <Title>
 
 Status: draft | ready | blocked | not_applicable
-Decision: ready | blocked | not_applicable
+- decision: ready | blocked | not_applicable
 Based on: approved UR and post-UR routing evidence
 Date:
 Owner:

package/generated/.agents/plugins/marketplace.json

@@ -15,6 +15,18 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Productivity"
+    },
+    {
+      "name": "agdf-planning",
+      "source": {
+        "source": "local",
+        "path": "./plugins/agdf-planning"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
     }
   ]
 }

package/generated/.opencode/agdf-agent-router.md

@@ -112,7 +112,7 @@ Structured Delivery Mode must respect gates, reviews and closeout discipline.
 | `clean-implementation-review` | evidence dimension: inspect whether the solution is structurally clean | supports Quality Readiness; not a TP or QA substitute |
 | `code-review` | evidence dimension: review the actual diff for defects, regression and security findings | supports Quality Readiness; does not replace QA |
 | `delivery-closeout` | commit/PR-near handoff after QA/OR/UAT | never performs VCS actions automatically |
-| `ur-definition` | bound UR drafting, clarification or revision | content only; preserves approved intent |
+| `ur-definition` | UR drafting in planning scope or a bound Run | content only; no start or approval authority |
 | `prd-definition` | bound PRD drafting, clarification or revision | content only; preserves approved intent |
 | `sd-definition` | bound SD content | content only; preserves approved intent |
 | `tp-definition` | bound TP content | content only; preserves approved sources |
@@ -123,7 +123,7 @@ Structured Delivery Mode must respect gates, reviews and closeout discipline.
 <!-- AGDF-SKILL-ROUTING:END -->
 
 For named operations, use the catalog owner in `contracts/request-activation.md`; active-run
-inventory uses `control.doctor` with all-active inspection.
+inventory uses `control.inventory`.
 For skill or delivery routes, select exactly one primary skill first.
 Add more only when they cover a distinct concrete risk dimension.
 Do not choose `brownfield-analysis` as the first primary skill for a fresh "I want to build/change X" prompt unless `gate-check` or existing live AGDF control state already makes implementation preparation the next allowed action.
@@ -151,7 +151,7 @@ When the target repository uses the AGDF control scaffold, keep live control fil
 Use templates as starting points only.
 
 Do not let chat history become the source of truth for gate state, approvals, evidence, backlog status or durable Brownfield knowledge.
-After editing a run or its listed artefacts, record the revision with the dispatch validator's `run-update` before `gate-check`; record an exact gate reply only with `run-approve`, never by editing Approvals.
+Stage current reviewed material and record it through the inspected typed owner; never edit a bound document or Run and reseal it. Current control, approvals and document references derive from canonical typed records. Only a fresh deliberate reply to the frozen presentation records an approval.
 
 AGDF is agent-native first and CLI-verifiable by design: read the live control state, apply the active skill and make the next allowed step explicit.
 Use `init` only when durable control state is explicitly requested, the repository already uses `.agdf/control/` as its live AGDF working state, or a deterministic CLI/CI setup path is being executed.