create-agdf 0.20.1 → 0.30.0

package/README.md

@@ -2,13 +2,44 @@
 
 Bootstrap AGDF into the coding-agent surface and repository where work actually happens. It installs or generates the surface-specific guidance, skills and optional durable control files that help teams make scope, approvals, evidence and delivery state visible.
 
-AGDF is useful when AI-assisted work can affect an existing system and a team needs a traceable answer to: what is allowed next, who approved it and what evidence supports it. It is deliberately not a substitute for engineering judgement, security review, tests, product ownership or human acceptance. For the framework's fit, limits and examples, start with the [project overview](../README.md).
+AGDF is useful when AI-assisted work can affect an existing system and a team needs a traceable answer to: what is allowed next, who approved it and what evidence supports it. It is deliberately not a substitute for engineering judgement, security review, tests, product ownership or human acceptance. For the framework's fit, limits and examples, start with the [project overview](../../README.md).
 
-GitHub Copilot and OpenCode are **experimentally supported in 0.20.x**. Both have adapters and
+GitHub Copilot and OpenCode are **experimentally supported in 0.30.0**. Both have adapters and
 automated regression tests; native qualification is not currently claimed. Tests with simulated
 hosts do not establish behavior in an actual Copilot or OpenCode session. See the
 [host compatibility report](../../docs/compatibility/HOST_COMPATIBILITY.md) for dated evidence and gaps.
 
+## Project setup diagnosis (development build)
+
+For a confirmed existing Git root, CLI and installed validator share Core's read-only setup facts:
+
+```bash
+agdf project-state --dir /absolute/git/root --json
+agdf operation-status --dir /absolute/git/root --module project.initialize/ORIGINAL_UUID --json
+agdf status --surface codex --dir /absolute/git/root --native --json
+```
+
+The first two reads accept optional `--language TAG`; operation-status here supports project.initialize.
+Exit 0 means a complete available result, including pending; 2 means blocked/unavailable/incomplete;
+1 means invalid usage. Keep the original UUID and exact request after uncertainty. The existing
+`agdf-project --command-file REQUEST.json` writer remains the explicit setup fallback.
+Reads never initialize or create a Run. Missing evidence does not prove a past write never happened.
+
+Codex status distinguishes installation/registration, configuration and actual owned-provider tools.
+Without `--native`, it observes only relevant configuration, with no thread or model turn. Unsupported
+settings/provenance remain unknown. Explicit catalog observation uses the existing per-invocation
+startup wait override and stays within 45 seconds including cleanup; configuration observation has a
+15-second ceiling. It changes no global settings or server timeout. This is no general speed guarantee.
+
+An empty Doctor inventory explains `allow_no_active_runs`: default revise with zero findings;
+explicit true preserves pass. Project health and delivery readiness remain separate. Preserve
+specific missing-source, stale-revision and runtime causes, deleted state and original identity.
+
+Run `npm run native:codex-project-setup -- --out /absolute/unused/report-directory` from the source
+checkout for one finite independent session using the existing authenticated host and configured model.
+It starts from an empty directory, supplies no identities or seeds, and audits native events, original
+receipt and all 16 file hashes. A baseline installed tuple does not qualify an uninstalled candidate.
+
 ## Quick start
 
 AGDF's normal operating model has three roles: chat/skills provide the user interaction,
@@ -49,9 +80,9 @@ Use a different target when Codex is not your agent surface:
 | Surface or goal | Start with | What it gives you |
 |---|---|---|
 | Claude Code | `npx --yes @agdf/cli@latest claude` | The AGDF plugin with MCP; the shared default build does not enable the Codex UI paths. |
-| GitHub Copilot (**experimental in 0.20.x**) | `npx --yes @agdf/cli@latest copilot` | The AGDF plugin with prefixed skills and a consent-bound session hook. |
-| OpenCode, user-wide discovery (**experimental in 0.20.x**) | `npx --yes @agdf/cli@latest opencode` | The npm plugin and global native skills; repository governance remains opt-in. |
-| OpenCode, one repository (**experimental in 0.20.x**) | `npx --yes @agdf/cli@latest opencode-repo` | Durable control configuration that activates the once-installed global runtime. |
+| GitHub Copilot (**experimental in 0.30.0**) | `npx --yes @agdf/cli@latest copilot` | The AGDF plugin with prefixed skills and a consent-bound session hook. |
+| OpenCode, user-wide discovery (**experimental in 0.30.0**) | `npx --yes @agdf/cli@latest opencode` | The npm plugin and global native skills; repository governance remains opt-in. |
+| OpenCode, one repository (**experimental in 0.30.0**) | `npx --yes @agdf/cli@latest opencode-repo` | Durable control configuration that activates the once-installed global runtime. |
 | Durable control state in an existing setup | `npx --yes @agdf/cli@latest init` | Live `.agdf/control/` state when the repository explicitly needs it. |
 
 In the next AGDF version, an interactive runtime-bearing installer will first show the plugin state,
@@ -124,117 +155,33 @@ pending; it does not ask you to grant the same trust again. Missing, ambiguous o
 native metadata stays unverified. AGDF never writes Codex trust hashes, and native trust alone
 does not prove that a session hook ran. After an update, fully restart Codex and open a fresh task.
 
-For prerequisites, all surface-specific flows and operational boundaries, use the authoritative [installation guide](../INSTALL.md). Do not run `init` merely to ask a fresh question: an agent can first clarify the request and ask for `Approval: UR` when durable control state is needed.
+For prerequisites, all surface-specific flows and operational boundaries, use the authoritative [installation guide](../../INSTALL.md). Do not run `init` merely to ask a fresh question: an agent can first clarify the request and ask for `Approval: UR` when durable control state is needed.
 
 ## Command overview
 
-### Existing repository control state during installation (development)
-
-Install and update commands inspect existing `.agdf` state in the invocation directory without
-changing it. Interactive setup shows a compact count of eligible runs and repair cases, then offers one
-migration decision for that exact repository. Choose 1 to migrate, 2 to defer, or 3 for details (d remains an alias);
-empty input keeps the inspection read-only, including recovery journals. Select a repository explicitly in automation:
+### Current control format and installation
 
-```bash
-node ./bin/create-agdf.js codex --control-dir /absolute/path/to/repository --control-migration safe
-```
+The only supported layout is explicit `run-folders-v1`, with version-4 Runs and
+current wrapped records. Installation and startup inspect the selected repository
+read-only. They report `absent`, `current`, `unsupported` or `repair_required`;
+these results never grant delivery permission. Unsupported data remains unchanged.
+There is no conversion, migration, reset, old-version reader or legacy projection.
+The optional planning package requires this current Core capability; Core remains
+usable without the extension.
 
-The flags are part of the development version; they do not describe the currently published
-`@agdf/cli@latest`. `--control-migration inspect` disables all control writes. `--control-dir` is
-independent of the OpenCode host configuration directory. No other repositories are scanned.
-
-The installation report separates the plugin result from `control.status`: compatible, migration
-required or repair required. A verified plugin with unresolved control compatibility returns a
-partial setup result (exit 1); it does not roll back or misreport the installed plugin. Safe
-migration covers active version-2 runs with missing seals, complete approval tables containing only
-missing approvals with empty evidence, and resolvable artefacts. Existing seals that are malformed
-or no longer match are repair cases. Unsupported versions and conflicting/missing artefacts stop
-migration of the affected runs; other eligible runs can proceed. Historical unsealed completed, superseded or abandoned runs are retained as
-non-authorizing history and are not reopened or retrospectively attested.
-
-For eligible runs with historical approvals, the common decision explicitly describes the
-approval reset and return to UR. Original records and artefact hashes are backed up automatically.
-Details show the selected runs, source revisions, prior approvals and next gates. The decision
-binds to those exact source snapshots: concurrent edits stop the affected run, and newly discovered
-runs are not added after confirmation. Repair cases do not block other eligible runs.
-Noninteractive/JSON setup never resets historical approvals. The manual `run-recovery inspect|preview|apply` path remains available.
-Legacy authoritative `AGDF_RUN.md` is reported separately and requires explicit `run-migrate`
-followed by inspection; it is not silently converted during plugin installation.
-
-If repair cases remain after migration, interactive setup offers **1: Start repair assistant**,
-**2: Later**, **3: Details**. Starting the assistant searches private recovery checkpoints and this
-repository's Git history without writing. It then shows concrete proposals and missing original
-files; a second 1/2/3 selection applies only the displayed proposals or defers them. Missing originals
-and placeholder references remain explicit input requirements. Repair is disabled by
-`--control-migration inspect`, noninteractive/JSON setup, or a failed plugin operation.
-
-The assistant can restore missing artefacts from an exact Git path in the current checkout's
-history, reset unproven approvals in the unsealed run, and record the resulting state through the
-canonical recovery writer. A changed sealed run can use a valid original snapshot of the same
-revision with identical recorded approvals. The former self-reference hashing defect is repairable
-only when a validated recovery journal reconstructs the complete current record and all other
-artefact hashes still match. Unsupported formats, changed approvals, unsafe paths and absent
-originals require manual input. No missing report or approval is invented.
-
-Before applying a proposal, the assistant saves the existing record and selected originals in a
-private `repair-previews` journal and rechecks the displayed snapshots under the run lock. A failed
-write rolls back only restored files still owned by that attempt; an interruption after atomic
-replacement retains the original backup and does not cause another revision on reinstall.
-The report distinguishes a successfully installed plugin from unresolved repository repair and
-lists the concrete files or reference corrections still needed.
-
-Migration reuses the locked, atomic recovery writer, retains the source and artefact digests in the
-recovery journal, and resumes interrupted writes without adding a second revision. A repeated
-installation leaves already migrated runs byte-identical. The journal is a recovery checkpoint
-and original snapshot, not a blanket automatic rollback: concurrent edits stop recovery. Restoring
-an older state remains an explicit operation. A new seal records integrity; it cannot prove an old
-human approval. This compatibility check does not evaluate QA or grant delivery authority.
-
-| Existing control format | Installer behavior |
-|---|---|
-| Version 2, valid seals | Inspect and preserve exact bytes. |
-| Version 2, active, unsealed, all approvals missing | Recover automatically in the explicitly selected repository. |
-| Version 2, active, unsealed, historical approvals | Include in the common, snapshot-bound decision; reset approvals only after migration is selected. |
-| Version 2, inactive and unsealed | Retain as non-authorizing historical evidence. |
-| Unsupported version, invalid/mismatched seal or missing artefact | Report repair required; do not bless or overwrite the state. |
-| Authoritative legacy `AGDF_RUN.md` | Report the explicit `run-migrate` path, then inspect its canonical output. |
-
-New recovery journals use preview format 2, which binds the write timestamp into the preview
-digest. Existing format-1 journal digests remain readable. A legacy interrupted transaction whose
-recorded result does not match the actual bytes remains a repair conflict rather than being
-silently accepted.
-
-
-### Repository maintenance without reinstalling (development)
-
-Compatibility belongs to each repository. The installed full runtime can inspect and maintain
-its explicitly selected control root directly; no installer, registry or MCP setup is involved.
-Use the fixed runtime invocation supplied by your host, for example:
+Inspect through the installed version-matched runtime, without reinstalling:
 
-```bash
+```sh
 node "<installed-plugin>/runtime/agdf-local.js" control-maintenance --dir /absolute/repository --json
 node "<installed-plugin>/runtime/agdf-local.js" control-maintenance --dir /absolute/repository --details --language de
-node "<installed-plugin>/runtime/agdf-local.js" control-maintenance --dir /absolute/repository --guided --language de
 ```
 
-These are invocation examples; use your host's actual supplied runtime path. Default, details and
-JSON inspect read-only. Guided mode needs interactive input and offers **1: Migration and repair**,
-**2: Later**, **3: Details**. Starting searches proposals only; applying a displayed migration
-batch or concrete repairs is a separate deliberate selection after scope, originals, backups and
-approval-reset consequences are shown. Blank/EOF defer. No new noninteractive apply API is exposed.
-Required originals remain named input; missing evidence is never synthesized.
-
-The prepared development CLI also exposes `agdf control-maintenance --dir /absolute/repository`.
-This new entry belongs to the development candidate; source/package tests do not refresh an older
-installed plugin or establish availability in the currently published release.
-
-Permitted startup checks report this repository's own compatibility and a compact direct invocation
-when maintenance is needed, separately from Doctor readiness. They never apply changes or wait for
-input. Disabled/stale check permission does not inspect automatically. Supported session/repository
-reentry binds fresh context; other surfaces use the explicit command fallback. Current or absent
-control needs no maintenance prompt. Package/fixture results and fresh installed-host observations
-remain separate evidence; executable identity changes retain existing permission-renewal rules.
-
+Use the actual runtime path supplied by the host. This operation only inspects;
+guided migration/repair and installation-time control-migration flags are removed.
+Current original-operation recovery uses its exact UUID, captured inputs, inspected
+pending digest and current recovery revision. Foreign bytes or unknown ownership
+stop recovery. Preserve unsupported stores separately and initialize a fresh
+explicitly confirmed Git target for current work.
 
 The Quick Start above is the recommended entry point. For the exact current command and option reference, run `npx --yes @agdf/cli@latest --help`; the groups below explain the supported surfaces, validation paths and canonical run lifecycle.
 
@@ -242,12 +189,12 @@ Installation, activation and explicit lifecycle changes:
 
 ```bash
 npx --yes @agdf/cli@latest codex
-npx --yes @agdf/cli@latest codex-repo
+npx --yes @agdf/cli@latest codex-repo --dir /absolute/project
 npx --yes @agdf/cli@latest claude
 npx --yes @agdf/cli@latest copilot
 npx --yes @agdf/cli@latest opencode
 npx --yes @agdf/cli@latest opencode-status
-npx --yes @agdf/cli@latest opencode-repo
+npx --yes @agdf/cli@latest opencode-repo --dir /absolute/project
 npx --yes @agdf/cli@latest codex --with-mcp --dir /absolute/path/to/repository
 npx --yes @agdf/cli@latest mcp status --surface codex --dir /absolute/path/to/repository --json
 npx --yes @agdf/cli@latest mcp enable --surface codex --dir /absolute/path/to/repository
@@ -267,7 +214,7 @@ npx --yes @agdf/cli@latest config --language en
 ### Optional local MCP dispatcher (unreleased development preview)
 
 AGDF can register one local STDIO server for Codex, Claude Code, GitHub Copilot or OpenCode.
-MCP tools: `agdf_dispatch`, `agdf_inspect`, `agdf_prepare`, `agdf_record`, `agdf_approve`, `agdf_revise`, `agdf_closeout`.
+MCP tools: `agdf_dispatch`, `agdf_inspect`, `agdf_project`, `agdf_run`, `agdf_prepare`, `agdf_record`, `agdf_approve`, `agdf_revise`, `agdf_closeout`.
 Dispatch projects the existing canonical skill-dispatch
 contract; inspect provides read-only doctor, gate-check, delivery-map and contract operations.
 Tool permission and successful execution never grant an
@@ -298,12 +245,17 @@ The adapters keep native configuration ownership and precedence visible:
 
 - Codex uses project `.codex/config.toml` or user `$CODEX_HOME/config.toml`.
 - Claude Code maps AGDF project scope to native `local` and user scope to native `user`.
-- OpenCode uses project `opencode.json` or user `$OPENCODE_CONFIG_DIR/opencode.json`.
+- OpenCode reads project and user `opencode.json` / `opencode.jsonc`, plus custom and inline
+  configuration. JSONC overrides conflicting JSON entries; updates retain comments and foreign
+  servers in the existing owning file instead of creating a parallel registration.
 - The GitHub Copilot CLI contract manages project `.github/mcp.json` or user `~/.copilot/mcp-config.json` and treats
   a project `.mcp.json` entry as higher priority. A higher-priority entry blocks mutation until the
   conflict is resolved. Copilot Desktop, IDE integrations and cloud agents are separate client
   variants and require their own direct evidence.
 
+The manual Copilot adapter accepts both wrapped and bare project configurations and derives its
+tool allowlist from the Core contracts. The normal Copilot installation remains plugin-managed.
+
 Machine-readable lifecycle output separates capability, selected registration, effective source,
 discovery and final result. A matched configuration is not reported as discovered. Plugin install,
 MCP registration, tool permission and a successful tool call do not grant AGDF gate approval. MCP
@@ -366,84 +318,89 @@ runtime. This differs from detected CLI system locale input and from `config --l
 persists the project preference after a governance target is available. A target-unresolved result
 cannot read project configuration safely because no project has been selected yet.
 
-### Late source revision
+`agdf control-maintenance --dir /absolute/project --json` inspects current compatibility read-only; unsupported stores are preserved without migration or repair.
 
-At a valid active structured `CD+Tests` boundary, with exact approved UR/PRD/SD/TP and
-completed required preparation, source revision reopens the earliest changed source.
-It preserves exact unchanged upstream approvals and revokes affected current approvals,
-relationships, analytical inputs and implementation/review fulfillment. It retains code/tests.
-Awaiting CR, QA/UAT/OR, closed, damaged and pending states cannot use this path.
+### Current Run commands
 
-Write a reviewed proposal under `.agdf/control/artefacts/<run_id>/`. Its exact JSON keys are
-`schema_version: "1"`, `target_id`, `run_id`, `expected_revision_id`, `operation_id`,
-`source_gate`, `reason`, `intended_change`, `sources`, and `impact_assessment`. `target_id`
-is the canonical local command target digest. `sources` contains the exact current
-`{type,path,digest}` entries in UR/PRD/SD/TP order. `impact_assessment` contains:
+Current aliases share Core input normalization, captured configuration and original
+operation replay with the fixed MCP command groups. Provide an operation UUID when
+an exact retry may be needed; preserve the returned identity and inspected revision.
+`run-create` derives its new Run ID from that UUID and requires an explicit title.
 
-- `reviewer`, `earliest_source` (matching `source_gate`) and `implementation_evidence`;
-- `upstream`: exact unchanged earlier source entries plus a concrete `rationale` for each;
-- `analyses`: every linked Brownfield Review/UX input, each with `type`, exact `path`/`digest`,
-  `disposition: "retain" | "reassess"` and `reason`; UR revision requires reassessment;
-- `unresolved: []`; unresolved or contradictory impact must be clarified before preview.
+```sh
+agdf run-create --dir /absolute/project --title 'Clarify one requirement' --operation <uuid>
+agdf run-step --dir /absolute/project --run <id> --revision <uuid> --operation <uuid> --step ur --title 'Clarify one requirement' --evidence /absolute/reviewed-UR.md
+agdf run-step --dir /absolute/project --run <id> --revision <uuid> --operation <uuid> --step artefact --gate PRD --evidence /absolute/reviewed-PRD.md --reviewer 'Source reviewer' --reviewed true --update-draft false
+agdf run-present --dir /absolute/project --run <id> --revision <uuid> --gate UR --operation <uuid>
+```
 
-```bash
-agdf run-revise --preview --dir /absolute/repository --run <run_id> \
-  --revision <revision_id> --source-gate TP --operation <uuid> \
-  --evidence .agdf/control/artefacts/<run_id>/proposal.json --json
-agdf run-revise --apply --dir /absolute/repository --run <run_id> \
-  --revision <revision_id> --source-gate TP --operation <same_uuid> \
-  --evidence .agdf/control/artefacts/<run_id>/proposal.json --preview-digest <returned_digest>
-agdf run-revise --inspect --dir /absolute/repository --run <run_id> \
-  --revision <observed_revision_id> --operation <same_uuid>
-agdf run-revise --recover --dir /absolute/repository --run <run_id> \
-  --revision <old_or_committed_revision_id> --operation <same_uuid>
+These are input examples; use actual inspected identities and reviewed files.
+Show the exact prepared presentation before forwarding a new deliberate reply with
+`run-approve --presentation <id> --response 'Approval: UR'`. A historical reply
+cannot approve changed material. Staging grants no delivery or approval authority.
+
+For full-text terminal delivery through Codex CLI, the optional `render-document`
+frontend consumes `codex exec --json` output. Its `--request` mode generates the
+matching read-only model request from an explicitly selected, validated canonical
+presentation envelope. This supplies the verified target hash and original
+historical selectors, the `structuredContent.report` path and a bounded loop over
+all actual `next_cursor` values. It includes no document body or approval.
+Use the same selectors for request generation and rendering; replace the quoted
+placeholder IDs below with the real inspected selection (Bash example):
+
+```sh
+set -euo pipefail
+selection=(--dir /absolute/project --run '<id>' --revision '<uuid>' --gate UR --presentation '<uuid>')
+request=$(agdf render-document "${selection[@]}" --request)
+codex exec --json "$request" | agdf render-document "${selection[@]}"
 ```
 
-Preview is nonmutating; cancellation needs no command. Apply rechecks its exact facts under
-Run then Backlog locks, stages/syncs immutable raw-byte history and commits the sealed Run
-before updating Backlog. `Source Revisions` is append-only Run evidence; archive manifests
-and snapshots remain subordinate historical proof. Historical resolution uses original-path
-archived bytes, including old mappings and presentations, after canonical drafts are replaced.
-Invalidated receipts remain inspectable but cannot satisfy current readiness.
+`--server` selects the exact Codex MCP server ID (default `agdf`); plugin server
+names must be supplied explicitly. Use a read-only Codex tool profile for this
+flow. The renderer rejects unexpected tool/write traffic, incomplete turns,
+conflicting responses, changed bindings, missing pages, bad digests and unsafe
+terminal control characters before printing any document text. It reads the
+canonical presentation envelope and receives document bytes only through MCP.
+The complete verified document is written to stdout without an extra newline;
+an `AGDF_DOCUMENT_DELIVERY` receipt goes to stderr. This is a distinct terminal
+delivery mode, not an agent-chat message, human-review proof or gate approval.
+Stored JSONL can be replayed; the receipt alone does not attest a live model run.
+Request generation reads only canonical metadata, grants no tool permission and
+does not launch Codex. The generated request keeps progress metadata in model
+context while the frontend receives the full original MCP frames directly.
+Its tool call uses a literal name; dynamic `tools[match.name]` dispatch remains
+outside the observer's proof. If necessary, discover the actual name separately
+and replace only that literal, preserving all selected values and the read loop.
+
+For internal results, explicit bounded recovery and complete typed inputs use the
+fixed group routes `agdf-project`, `agdf-run`, `agdf-prepare`, `agdf-record`,
+`agdf-approve`, `agdf-revise` and `agdf-closeout` with `--command-file <regular.json>`.
+Only `--command-file` and `--json` are accepted on these routes; envelope fields
+cannot be overridden by CLI flags. Read the current operation-contract for the exact
+schema. No RECORD/REVIEW JSON input duplicates a reviewed source mapping.
 
-Sources are unlinked rather than edited by reopening. Their existing owners record new drafts,
-reviewed bindings, presentations and fresh deliberate approvals. Renewed TP requires fresh
-preparation and current-plan implementation/test/review evidence. Existing MCP dispatch/inspect
-observe this current state and history references; late apply/recover remain local CLI commands.
-No MCP write tool or argument is added. A matching operation replay is nonmutating and reports
-original versus current revision; changed same-ID requests are refused. Unknown/pending state
-blocks ordinary work until explicit recovery can prove rollback or one committed effect.
+### Late source revision
 
-Canonical run lifecycle:
+`agdf run-revise` uses the same current source-revision owner; read its contract for the exact proposal, preview digest and confirmation before applying.
 
-```bash
-agdf run-create --run <run_id>
-agdf run-update --run <run_id> --revision <revision_id>
-agdf run-revise --run <run_id> --revision <revision_id>
-agdf run-step --run <run_id> --revision <revision_id> --step <ur|route|review|evidence|closeout> [step fields]
-agdf run-present --run <run_id> --gate <gate> --revision <revision_id>
-agdf run-approve --run <run_id> --gate <UR|PRD|SD|TP|QA|UAT> --revision <revision_id> --presentation <presentation_id> --response "Approval: <gate>"
-agdf run-migrate [--run <run_id>]
-agdf run-render-legacy --run <run_id>
-```
+The current source-revision owner retains policy 2: an actual eligible structured
+pre-UAT phase, the earliest changed approved source, exact unchanged upstream
+proof, reviewed analytical and quality impact, explicit preview and deliberate
+confirmation. It does not widen eligibility or infer approval from tool consent.
+
+Read the current `source_revision.preview`/`source_revision.apply` operation help
+and reviewed proposal format (version 3). Preview changes no Run. The apply command
+requires its exact preview digest and confirmation selector, the original operation
+UUID and unchanged reviewed proposal. The resulting version-4 receipt and version-2
+archive bind the historical sources below `runs/<id>/history/revisions/<operation>/`.
+Affected downstream approvals and fulfillment require renewed work; code files stay
+available without becoming current qualification evidence.
 
-`run-create` writes a sealed run with empty Approvals, Artefacts, Mode/Slice Decision and Artefact
-Chain tables and prints its path, `revision_id` and the next UR step. The seal covers the run state
-and every file listed under Artefacts, so an edit made outside these commands blocks `doctor` and `gate-check` with `AGDF_RUN_SEAL_MISMATCH` until
-`run-update` records it as a new revision and refuses changed approval rows. With no mode,
-`run-revise` keeps its early PRD-to-SD boundary behavior before downstream artifacts are linked.
-The explicit late modes below cover source revision during approved-TP implementation.
-Run writers also reject duplicate `Artefacts` rows; replace the existing row for a type, or remove
-an extra row and retry `run-update` to record the correction.
-`run-approve` re-evaluates the gate, accepts only the exact `Approval: <gate>` reply for the
-presented `revision_id`, records it with the approved artefact's digest and advances the revision.
-`run-step` records one standard small-path transition per call (UR registration, Mode/Slice route,
-evidence, Code Review, `quick_task` closeout with OR-lite) and maintains the run tables, the
-`MASTER_BACKLOG.md` pointer and the policy-derived next action. These commands print JSON and are
-also available through the plugin's surface-local validator. The
-seal detects unrecorded edits; it is not a signature. Normal write commands reject missing seal
-lines. Restore a trusted sealed revision before recording changes; `run-migrate` remains the explicit
-path for legacy control state and does not infer approvals.
+The current `run-revise --preview|--apply|--inspect|--recover` aliases use the same
+owner. Early PRD reopening uses `run-revise --gate PRD` and its exact confirmation.
+Unapproved draft replacement uses the inspected current recording operation; UR
+replacement uses `ur_draft.replace`. Never edit a bound source or Run and reseal it.
+Retired synchronization, migration, rendering and approval-reset commands are absent.
 
 ### Explicit local approval command (development)
 
@@ -487,9 +444,9 @@ agdf run-approve --dir /absolute/path/to/repository --run <run_id> --gate UR \
   --operation <uuid> --assurance cooperative_local
 ```
 
-Omitting `--assurance` defaults to the same visible cooperative lane. Without `--operation`, the
-existing CLI result/rejection semantics remain, with additive assurance and no receipt backfill.
-`--assurance` is restricted to `run-approve`; `--operation` also identifies explicit source revisions.
+Omitting `--assurance` defaults to the same visible cooperative lane; stronger values are rejected.
+An omitted `--operation` creates a fresh UUID and returns its receipt. Retain the original UUID
+and input for exact repetition. The current command aliases share this normalization boundary.
 
 The Run contains the append-only `Approval Operations` receipt and approval in one atomically
 replaced, sealed revision. The service holds the owned Run lock across validation and commit.
@@ -518,7 +475,7 @@ they do not install or publish the package.
 
 ### Advanced / Compatibility
 
-Backward-compatible scaffold usage:
+Alternative CLI invocation syntax:
 
 ```bash
 npm create agdf@latest -- codex
@@ -615,7 +572,7 @@ select the fallback with an explicit PowerShell `if` expression. They never conc
 values. The generated runtime and SessionStart hook use the same resolver, so a compatibility
 variable cannot override the native root of the active host.
 
-**Copilot support remains experimental in 0.20.x.** Staging uses the independent path
+**Copilot support remains experimental in 0.30.0.** Staging uses the independent path
 `<AGDF data directory>/marketplaces/agdf-copilot`. This
 prevents Copilot updates and rollbacks from replacing the shared Codex and Claude payload while the
 host-facing Marketplace identity remains `agdf` and the install identity remains `agdf@agdf`.
@@ -642,7 +599,7 @@ After `npm create agdf@latest -- codex-repo`, restart Codex in that repository,
 runtime-free source checkout and is validated before lifecycle status treats `agdf@agdf-repo` as
 active.
 
-**OpenCode support remains experimental in 0.20.x.** Use the `opencode` target to install the
+**OpenCode support remains experimental in 0.30.0.** Use the `opencode` target to install the
 AGDF npm plugin as a user-wide OpenCode hook:
 
 ```bash
@@ -687,15 +644,21 @@ Source, generated and package evidence do not prove what an installed host ultim
 orders. Fresh loaded-host evidence remains separate. In particular, OpenCode keeps one bounded
 kernel-only compaction recovery block until same-version and same-digest host observations prove
 that the system transform is reapplied and the current dispatcher binding remains available. The
-[Instruction Footprint Audit](../.agdf/control/artefacts/agdf-request-activation-boundary/INSTRUCTION_FOOTPRINT_AUDIT.md)
+[historical Instruction Footprint Audit](../../.agdf/control/archive/source/runs/agdf-request-activation-boundary/documents/INSTRUCTION_FOOTPRINT_AUDIT.md)
 records the design evidence and its limits.
 
 ## Control scaffold
 
+Initialization uses only `run-folders-v1`, with independent planned URs and derived
+planned/Run inventory. It creates no Masterbacklog and no Run implicitly. Other
+layouts and Run versions are unsupported and remain unchanged.
+See [planned UR commands and optional Codex Planning](../../plugins/agdf/control/planned-urs.md).
+
 The generated `.agdf/control/templates/` files are reusable starting points for durable AGDF state:
 
-- `runs/<run_id>/RUN_STATE.md` for each canonical current run dashboard
-- `MASTER_BACKLOG.md` for active delivery pointers
+- `runs/<run_id>/RUN_STATE.md` for canonical authored facts and typed records; current views are derived
+- `runs/<run_id>/documents/`, `evidence/`, `control/` and `history/` for all Run-owned files
+- `planned/<plan_id>/UR.md` for each planned need (UR-only; created on explicit capture)
 - `templates/artefacts/` for durable UR, PRD, SD, TP and QA report artefact templates
 - `SOT_REGISTRY.md` for one source of truth per domain
 - `CONTEXT_GRAPH.md` for durable Brownfield findings, decisions, risks, evidence and exit criteria
@@ -709,8 +672,7 @@ npm create agdf@latest -- init
 
 This writes:
 
-- `.agdf/control/runs/<run_id>/RUN_STATE.md`
-- `.agdf/control/MASTER_BACKLOG.md`
+- `.agdf/control/README.md` (Runs are created separately; no mandatory live backlog)
 - `.agdf/control/config.json`
 - `.agdf/control/templates/artefacts/UR.md`
 - `.agdf/control/templates/artefacts/PRD.md`
@@ -815,7 +777,7 @@ The routing test installs `both` into a temporary target repository and checks t
 
 ## Project, contribution and support
 
-This README is the package guide. Keep framework rationale, limits and examples in the [project overview](../README.md); keep target-specific installation in [INSTALL.md](../INSTALL.md); and use [RELEASE.md](../RELEASE.md) only when maintaining a published AGDF release.
+This README is the package guide. Keep framework rationale, limits and examples in the [project overview](../../README.md); keep target-specific installation in [INSTALL.md](../../INSTALL.md); and use [RELEASE.md](../../RELEASE.md) only when maintaining a published AGDF release.
 
 Non-sensitive feedback, examples and contributions are welcome through [GitHub Issues](https://github.com/ArndtGold/ai-native-governance-delivery-framework/issues). To validate a local package change before proposing it, run:
 
@@ -830,7 +792,7 @@ npm --prefix create-agdf run eval:skills:record -- --surface codex --case gate-c
 
 `eval:skills` is the credential-free deterministic CI lane. The recorder is an explicit supporting-evidence lane; it uses a disposable repository, records live provenance and refuses to persist a failing or mutation-violating result.
 
-The repository is licensed under [Apache-2.0](../LICENSE). No separate public `CONTRIBUTING.md`, `SECURITY.md` or private security-reporting channel is currently published. Do not treat a public issue as a private vulnerability disclosure.
+The repository is licensed under [Apache-2.0](../../LICENSE). Follow the repository [contribution guide](../../CONTRIBUTING.md), [governance](../../GOVERNANCE.md) and [security reporting policy](../../SECURITY.md). Do not treat a public issue as a private vulnerability disclosure.
 
 ## Publishing
 
@@ -852,7 +814,7 @@ shows its digest, run, gate and revision. Before the approval action it includes
 gate-specific summary, bound by `summary_digest`; UAT summarizes and presents its existing evidence
 rows. A missing summary is a presentation failure. Supply its `presentation_id` as
 `run-approve --presentation`.
-Old stored approvals remain valid; new legacy calls without the binding are rejected with recovery.
+Only current wrapped approval records and exact presentation bindings are supported; old record formats are refused unchanged.
 Never prepare a missing record after receiving an answer and reuse that answer. Read-only gate
 previews are not preparation records. Install matching runtime and skills; older runtimes reject
 new intake/continuation fields rather than silently dropping them.