create-agdf 0.14.5 → 0.20.1

package/README.md

@@ -4,6 +4,11 @@ Bootstrap AGDF into the coding-agent surface and repository where work actually
 
 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
+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.
+
 ## Quick start
 
 AGDF's normal operating model has three roles: chat/skills provide the user interaction,
@@ -11,6 +16,20 @@ AGDF's normal operating model has three roles: chat/skills provide the user inte
 second gate system. Use `npx ...@latest` below for installation and explicit refresh; after
 `npm install -g @agdf/cli`, prefer `agdf ...` for repeated local checks.
 
+The development command groups also have CLI entries `agdf-prepare`, `agdf-record`,
+`agdf-approve`, `agdf-revise` and `agdf-closeout`, each accepting the exact bounded JSON
+envelope via `--command-file`. Read the selected contract first; retain the original UUID
+after uncertainty. See [Core and MCP command flow](../../docs/architecture/core-mcp-command-flow.md)
+for bindings, decision permissions, receipts, compatibility and qualification boundaries.
+
+> [!IMPORTANT]
+> **MCP and UI evidence:** The previously published AGDF 0.14.5 release did not include the MCP support
+> described here. The MCP and MCP App details describe the repository development build, not a verified
+> `@agdf/cli@latest` resolution or native-host qualification. The version alone does not identify
+> the payload; compare payload digests and the loaded session. Runtime plugins for Codex, Claude Code
+> and GitHub Copilot declare MCP themselves;
+> the public OpenAI Skills-only candidate contains no MCP server.
+
 If you use Codex, this is the recommended first installation:
 
 ```bash
@@ -19,16 +38,60 @@ npx --yes @agdf/cli@latest codex
 
 Fully restart Codex, open a fresh task in the repository you want to work in, and describe the intended change. Restoring a previous task can retain stale AGDF skills. AGDF starts with the smallest permitted governance step; it does not make implementation automatic.
 
+**Claude Code and Codex share plugin-managed MCP, with different UI profiles.** The shared default
+build enables Cockpit (`agdf-cockpit`) and the gate-decision MCP App in Codex. It does not enable
+those UI paths in Claude Code. A separate Claude-specific Cockpit development build exists.
+Rendering requires host MCP App support and separate native evidence; production gate-decision
+click actions remain disabled pending qualification. See [MCP and UI by host](../../INSTALL.md#claude-code-and-codex-mcp-and-ui).
+
 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 for Claude Code. |
-| GitHub Copilot | `npx --yes @agdf/cli@latest copilot` | The AGDF plugin with prefixed skills and a consent-bound session hook. |
-| OpenCode, user-wide discovery | `npx --yes @agdf/cli@latest opencode` | The npm plugin and global native skills; repository governance remains opt-in. |
-| OpenCode, one repository | `npx --yes @agdf/cli@latest opencode-repo` | Durable control configuration that activates the once-installed global runtime. |
+| 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. |
 | 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,
+the invocation-directory target proposal and separate read-only MCP status for project and user
+scope. It then offers **Complete setup**, **Plugin only** and **Cancel**. Complete setup is marked
+recommended but is never preselected. Choosing it opens a second screen with **Project**, **User**
+and **Back**. That screen also has no default. Back returns to the first choice without mutation.
+Only the selected, available scope is passed to the existing MCP lifecycle owner. Plugin only
+leaves every MCP registration unchanged.
+
+Non-interactive use defaults to plugin only. Codex, Claude Code and Copilot already declare MCP
+through the runtime plugin and reject `--with-mcp`. For OpenCode, separate MCP registration requires
+an explicit absolute target:
+
+```bash
+npx --yes @agdf/cli@latest codex --plugin-only
+npx --yes @agdf/cli@latest opencode --with-mcp --dir /absolute/path/to/repository
+npx --yes @agdf/cli@latest opencode --with-mcp --scope user --dir /absolute/path/to/repository
+```
+
+Empty or unsupported answers never select a setup or scope; end of input cancels before mutation.
+Native host priority remains authoritative, so a higher-priority project registration can make the
+user option unavailable. The setup choice and the following automatic-check choice are separate.
+Neither grants governance authority. A plugin failure prevents MCP mutation. A later MCP failure
+keeps the verified plugin and returns a partial result with one recovery action. Restart the host
+and start a fresh session before treating a matching configuration as discovered.
+
+For OpenCode, an existing plugin-only command with `--dir` keeps its old meaning: the path is the
+OpenCode configuration directory. Only `opencode --with-mcp --dir <absolute-project>` treats it as
+the MCP target. `OPENCODE_CONFIG_DIR` or the normal default still selects the plugin configuration.
+Installations performed only by a marketplace or host UI remain plugin-only because that path
+cannot execute the guided CLI transaction.
+
+For local wrappers such as `npm run install:codex`, npm's absolute `INIT_CWD` supplies the proposed
+target. If it is absent, the wrapper uses the process working directory. It resolves and validates
+that directory before host-specific preparation; an invalid value fails with
+`AGDF_LOCAL_INVOCATION_DIRECTORY_INVALID` before package generation or host mutation. Human and
+JSON results distinguish this invocation context from the native registration path and the source
+that actually wins the host's MCP precedence rules.
+
 The runtime-bearing `codex`, `claude`, `copilot` and `opencode` installers ask before enabling narrow automatic
 local checks on an interactive terminal. The choices are `enable`, `manual` and `cancel`; enablement
 is never preselected. Every interactive installation or update asks again. A previous choice is
@@ -54,10 +117,125 @@ Claude deny/ask precedence and all explicit OpenCode permissions remain authorit
 Skills-only OpenAI candidate has no runtime or hooks and therefore remains manual/external for this
 capability.
 
+For Codex, the installer and `runtime-checks status --surface codex` read native `hooks/list`
+metadata through the local Codex CLI. A modified or untrusted AGDF session hook requires review
+in `/hooks`. An enabled, trusted hook instead reports that verification in a fresh session is
+pending; it does not ask you to grant the same trust again. Missing, ambiguous or unsupported
+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.
 
 ## 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:
+
+```bash
+node ./bin/create-agdf.js codex --control-dir /absolute/path/to/repository --control-migration safe
+```
+
+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:
+
+```bash
+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.
+
+
 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.
 
 Installation, activation and explicit lifecycle changes:
@@ -70,15 +248,75 @@ 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 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
+npx --yes @agdf/cli@latest mcp enable --surface copilot --dir /absolute/path/to/repository
 npx --yes @agdf/cli@latest status --surface codex
+npx --yes @agdf/cli@latest status --surface codex --dir /absolute/path/to/repository --scope project
 npx --yes @agdf/cli@latest disable --surface codex --scope repository
+npx --yes @agdf/cli@latest disable --surface codex --scope repository --dir /absolute/path/to/repository --with-mcp
 npx --yes @agdf/cli@latest disable --surface copilot --scope repository
 npx --yes @agdf/cli@latest disable --surface copilot --scope repository --shared
 npx --yes @agdf/cli@latest uninstall --surface codex --scope global
+npx --yes @agdf/cli@latest uninstall --surface codex --scope global --with-mcp --mcp-scope project --dir /absolute/path/to/repository
 npx --yes @agdf/cli@latest init
 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`.
+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
+AGDF approval. The process is offline while serving and exposes no generic shell, filesystem or
+network operation, but it inherits the operating-system permissions of the host user.
+
+The CLI requires Node.js 22 or later. MCP enablement requires the actual registered executable
+to be Node.js 22 or later and installs the exact matching `@agdf/mcp-server` package only after the
+explicit `enable` command:
+
+```bash
+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
+npx --yes @agdf/cli@latest mcp disable --surface codex --dir /absolute/path/to/repository
+```
+
+Project scope is the default. Add `--scope user` only after choosing the broader effect explicitly.
+After enablement, restart the host and verify tool discovery in a fresh session. OpenCode exposes
+the qualified name `agdf_agdf_dispatch`; the server-level name is `agdf_dispatch`. Its adapter reads
+the installed major version and writes the flat OpenCode 1.x or nested OpenCode 2.x MCP shape. `status` is
+read-only, and `disable` removes only the owned registration plus an unreferenced owned runtime.
+Foreign entries fail closed. Node.js versions below 22 are rejected by the CLI before application
+loading and cannot acquire an MCP runtime. Upgrade Node.js before retrying. One runtime is shared by all
+registrations in the selected project or user scope and is removed only after its last owned
+reference is gone.
+
+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`.
+- 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.
+
+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
+registration occurs only after an explicit complete CLI setup choice or a separate `mcp enable`.
+
+Host support is evidence-based and recorded independently. Configuration or protocol negotiation
+alone does not establish support. Every tuple remains `unverified` until the exact host client,
+client variant, operating system, architecture, scope, configuration source, Node runtime, server,
+dispatcher, SDK and entrypoint identity have direct discovery, bounded dispatch, failure and
+cleanup evidence. Controlled 2025-11-25 and 2026-07-28 protocol tests remain a separate server lane;
+they do not fill a host tuple when the host does not expose its negotiated protocol. The public
+OpenAI Skills-only candidate contains no MCP metadata or runtime.
+
 Repeated operational validation and bounded planning use the installed, version-pinned local command:
 
 ```bash
@@ -86,19 +324,198 @@ agdf doctor
 agdf gate-check --status-card
 agdf gate-check --approval-envelope
 agdf gate-check --json
+agdf skill-dispatch --json --skill gate-check --surface codex --language de --working-directory /absolute/context
 agdf delivery-map --json
 agdf delivery-path-search --surface codex --json
 agdf delivery-path-search --surface claude --json
+agdf contract --module gate-transition
+```
+
+`contract --module <name>` prints one packaged runtime-contract module named by the plugin
+definition. Skills read their modules this way after `skill_continuation`, because Claude Code grants
+skills no read access to the plugin directory.
+
+Installed AGDF sessions supply the exact version-matched `skill-dispatch` binding to canonical
+skills. It resolves the target first and returns either a terminal canonical result or one bounded
+continuation packet. The result's `host_action.text` carries the exact terminal presentation or
+recovery text. For `terminal: true`, the entire assistant response must equal that text: no added
+question, explanation, heading, citation, translation, choice or later tool call. It never grants
+approval. Pass an explicit target pair only when the conversation has actually selected one; do not
+substitute the working directory.
+
+A governed delivery intake (`delivery.start`) adds `--intake` (MCP: `intake: true`). While no active
+run exists or the selected run has no durable UR revision, gate-check then returns a non-terminal
+`intake_continuation` whose ordered steps create the run, write the UR and record it with
+`run-step --step ur`; the agent runs them and dispatches again instead of ending the turn. A ready
+approval and every other state stay terminal.
+
+When a resolved target contains several active runs, the gate evaluator returns one complete
+canonical `candidate_runs` inventory. A QA continuation retains this inventory in
+`control.candidate_runs`, including each run's identifier, objective, normalized current gate,
+decision and revision. The QA skill filters these returned records by `current_gate: QA`; it does
+not reconstruct the inventory by scanning run files itself.
+
+For `skill-dispatch`, `--language` is required and carries one well-formed BCP 47 tag selected from
+the latest natural-language request. An explicit response-language instruction wins; otherwise the
+host supplies the dominant request language and uses `en` when the request is mixed or ambiguous.
+The registry currently contains complete `de` and `en` packs. Regional variants such as `de-DE`
+and `en-US` resolve to their complete primary-language pack. A valid unsupported tag uses the
+complete English pack. Missing, wrong-type, padded, list, underscore, POSIX-suffixed and malformed
+values stop before target or gate evaluation and are never repaired or inferred from the host or
+runtime. This differs from detected CLI system locale input and from `config --language`, which
+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
+
+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.
+
+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:
+
+- `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.
+
+```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>
 ```
 
+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.
+
+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.
+
 Canonical run lifecycle:
 
 ```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>
 ```
 
+`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.
+
+### Explicit local approval command (development)
+
+The additive ESM export `create-agdf/control-command` and `run-approve --operation <uuid>` use
+one shared approval path. Importing the export reads package-owned metadata; it does not select a
+target, launch Git, initialize a host, print, exit or write. Existing package exports are unchanged.
+
+```js
+import {
+  CONTROL_COMMAND_SCHEMA_VERSION,
+  resolveControlCommandTarget,
+  recordGateApprovalCommand,
+} from "create-agdf/control-command";
+
+const { root, target_id } = resolveControlCommandTarget("/absolute/path/to/repository");
+const result = recordGateApprovalCommand(root, {
+  schema_version: CONTROL_COMMAND_SCHEMA_VERSION,
+  action: "record_gate_approval",
+  target_id,
+  run_id: runId,
+  gate: "UR",
+  expected_revision_id: presentedRevisionId,
+  presentation_id: presentedPresentationId,
+  response: verbatimDeliberateReply,
+  operation_id: operationId, // a UUID retained with this exact request across retries
+  assurance: "cooperative_local",
+});
+```
+
+The command is closed: these fields are required and unknown fields are rejected. The caller
+forwards the deliberate reply for the current durable presentation. Validation preserves existing
+reply semantics, including surrounding-whitespace handling; request identity retains the original
+response bytes. Neither caller roles, a presentation ID, a digest nor a successful tool call prove
+that a human saw or approved the presentation. Every result reports cooperative assurance and
+`independent_human_proof: unavailable`; stronger authority requests are rejected without mutation.
+The canonical realpath target ID is a local binding, not a portable repository identity or token.
+
+```bash
+agdf run-approve --dir /absolute/path/to/repository --run <run_id> --gate UR \
+  --revision <revision_id> --presentation <presentation_id> --response "Approval: 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.
+
+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.
+An identical operation UUID and request returns `already_applied` without another revision;
+a changed payload with the same UUID returns `operation_payload_conflict`. Receipt-bearing Runs
+require this upgraded runtime. Legacy Runs retain byte-identical approval-seal semantics.
+Other writers, PRD supersession and bounded recovery preserve existing receipts. Recovery can
+preserve receipt history only while its recorded approval seal still verifies; it clears effective
+approvals rather than adopting a historical receipt as a new decision.
+
+Results separate `binding`, request identity, historical `effect`, observed `current` state,
+`assurance` and commit/durability `observations`. `accepted` and `already_applied` are the only
+successful command outcomes. `rejected` requires correcting the request or preparing a new current
+presentation/reply. `retryable_failure` permits an identical retry after the live lock or transient
+pre-commit failure resolves. `recovery_required` means the canonical effect or acknowledgement
+cannot safely be concluded. After an interruption, retain and retry the identical command; a
+valid canonical receipt is acknowledged with file/directory synchronization, without writing a
+revision. Windows reports directory synchronization as unavailable. A replay after later changes
+returns the old effect alongside current state and never restores an effective approval.
+
+MCP exposes no mutating approval tool. This lane is cooperative local calling, not authenticated
+human attestation or protection against arbitrary writes by an operating-system user. Qualification
+of source, packed external consumers, generated validators, installed hosts and native platforms
+must remain separate. The command test scripts use disposable targets and private fault harnesses;
+they do not install or publish the package.
+
 ### Advanced / Compatibility
 
 Backward-compatible scaffold usage:
@@ -140,8 +557,8 @@ it does not localize the CLI lifecycle card.
 - `codex` installs the AGDF plugin globally for Codex
 - `codex-repo` writes a repository-local Codex marketplace under `.agents/plugins/` and a local AGDF plugin copy under `plugins/agdf/`
 - `claude` installs the AGDF plugin globally for Claude Code
-- `copilot` registers the AGDF-owned local Marketplace and installs `agdf@agdf` through Copilot CLI; when `copilot` is not on `PATH`, it runs the pinned official `@github/copilot` CLI package through npm, then verifies AGDF in Copilot's own plugin list
-- `opencode` installs the AGDF npm plugin and ten native skills as a user-wide OpenCode surface
+- `copilot` registers the AGDF-owned local Marketplace and installs `agdf@agdf` through Copilot CLI; when `copilot` is not on `PATH`, it runs the pinned official `@github/copilot` CLI package through npm, then verifies the plugin identity and all expected enabled plugin skills against the installed package content
+- `opencode` installs the AGDF npm plugin and native AGDF skills as a user-wide OpenCode surface
 - `opencode-status` reports OpenCode global config, package loadability, global native-skill completeness, installed host/plugin-SDK versions, declaration-level support for AGDF's two experimental hooks, durable repository activation, legacy compatibility and observable session signals
 - `status` reports installation, repository activation and delivery separately without mutating state
 - `runtime-checks status|enable|manual` reports the requested/effective automatic-check state or gives the exact reinstall route needed to change it
@@ -154,7 +571,7 @@ The `codex` and `claude` commands install the complete shared plugin built into
 `create-agdf` package. The `copilot` command installs a dedicated generated profile containing only
 the Copilot manifest, prefixed skills, hook, required contracts and exact-version runtime. Every profile
 is rendered from the same canonical sources. The installers atomically stage their profile under an AGDF-owned user-data marketplace, register
-that stable local path through the host CLI and verify the exposed version. Source `plugin/` therefore
+that stable local source with the host and verify the exposed version. Source `plugins/agdf/` therefore
 contains no generated runtime bytes and the source checkout exposes no installable root marketplace.
 
 Repository lifecycle support is deliberately asymmetric:
@@ -191,10 +608,30 @@ Successful installation verifies the installed version but not an already loaded
 restart the host and start a fresh session or task. Restoring the previous session can retain stale
 AGDF skills and must not be treated as current loaded-session evidence.
 
-Copilot staging uses the independent path `<AGDF data directory>/marketplaces/agdf-copilot`. This
+When a host exposes both plugin-root variables, runtime validation follows the active surface.
+Codex prefers `PLUGIN_ROOT` and falls back to `CLAUDE_PLUGIN_ROOT`; Claude Code uses the reverse
+order. Copilot accepts only `PLUGIN_ROOT`, and OpenCode has no plugin-root binding. Windows hooks
+select the fallback with an explicit PowerShell `if` expression. They never concatenate both root
+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
+`<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`.
 
+Copilot uses Git transport from this same canonical staging root. The installer generates Git
+metadata and a content-derived branch outside the plugin payload, registers the source through
+Copilot's `extraKnownMarketplaces` settings and runs the native plugin installer. Git must be
+available. Existing AGDF-owned directory registrations are migrated automatically; foreign
+marketplaces are refused. Same-version source changes receive a new ref, and failures restore the
+previous package and AGDF settings. There is no separate manual package snapshot to maintain.
+
+Installation is healthy only when `copilot skill list --json` exposes every expected skill from one
+enabled plugin installation with matching package content. Missing, disabled, shadowed or stale
+skills produce a verification failure. This is host discovery evidence; restart the desktop app and
+check a fresh session for rendered behavior.
+
 The Copilot installer does not create, rewrite or remove repository files. Existing `AGENTS.md`, `.github/` and `.agdf/control/` content remains untouched. Use `init` separately when a repository should own surface-neutral durable AGDF control state.
 
 Use the `codex-repo` target when AGDF should be available only inside one repository instead of being installed as a personal/global Codex plugin.
@@ -205,7 +642,8 @@ 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.
 
-Use the `opencode` target to install the AGDF npm plugin as a user-wide OpenCode hook:
+**OpenCode support remains experimental in 0.20.x.** Use the `opencode` target to install the
+AGDF npm plugin as a user-wide OpenCode hook:
 
 ```bash
 npx --yes @agdf/cli@latest opencode
@@ -227,9 +665,30 @@ npm create agdf@latest -- opencode-repo
 ```
 
 OpenCode loads the AGDF npm plugin and global native skills from global OpenCode config. Global adapters use the collision-safe `agdf-global-` prefix, including `agdf-global-gate-check`. `opencode-repo` adds the durable `.agdf/control/config.json` marker and control templates; it does not write `opencode.json`, `.opencode/AGDF.md`, copied contracts or copied skills.
-The global skills load on demand through OpenCode's native `skill` tool. Use `agdf-global-gate-check` first for new build/change intent or unclear approval. Existing local `.opencode/` assets remain supported as a compatibility path and are not deleted.
+The global skills load on demand through OpenCode's native `skill` tool. After positive Request Activation selects actual delivery work, use `agdf-global-gate-check` first. Unclear approval alone never activates AGDF. Existing local `.opencode/` assets remain supported as a compatibility path and are not deleted.
 The built-in `question` tool can present a gate choice, but `.agdf/control/` and exact post-response validation remain authoritative; technical permission and auto-mode outcomes never approve an AGDF gate. Explicit `permission.question: deny` remains unchanged and uses exact-text fallback.
-The global layer makes the ten native AGDF skills discoverable, but does not activate repository governance by itself. Global skills fail closed until the current repository has valid `.agdf/control/config.json`. Use `opencode-repo` to create the durable activation marker.
+The global layer makes the native AGDF skills discoverable, but does not activate repository governance by itself. Global skills fail closed until the current repository has valid `.agdf/control/config.json`. Use `opencode-repo` to create the durable activation marker.
+
+### Request activation and instruction loading
+
+AGDF uses one two-stage instruction model across its generated surfaces. Before selection, generated
+profiles provide one compact Request Activation kernel and short discovery descriptions. They make
+detailed routing, gate, quality and closeout instructions available on demand only after the current
+request has positively activated AGDF. OpenCode uses the same compact bootstrap and keeps the full
+router available on demand instead of registering it as an eager instruction.
+
+The versioned `instructionFootprint` contract defines UTF-8 byte budgets and structural conditions
+for the kernel, discovery descriptions, SessionStart, OpenCode static and dynamic context,
+compaction and the selected `gate-check` skill. Deterministic generation and package checks enforce
+those limits. The `skillSet.discovery` metadata describes the intended discovery boundary; it is not
+a claim that every host technically enforces that boundary.
+
+Source, generated and package evidence do not prove what an installed host ultimately retains or
+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)
+records the design evidence and its limits.
 
 ## Control scaffold
 
@@ -291,8 +750,8 @@ npx --yes create-agdf@latest gate-check --json
 
 The gate check reports `open | blocked`, the current gate, blocking reason, missing exact approval, allowed outputs, forbidden outputs, next allowed action, evidence references and the embedded doctor report.
 
-Use an installed `agdf gate-check --approval-envelope` to print deterministic ready-gate cards and the
-exact-text request without a fresh registry lookup. Use `gate-check --status-card` for compact
+Use an installed `agdf gate-check --approval-envelope` for a read-only summary and link to the
+current artefact. Prepare a bound approval with `run-present` before asking the user. Use `gate-check --status-card` for compact
 operational detail and keep `gate-check --json` for native-adapter input, automation, CI, regression
 evidence and audit trails. The CLI output validates and renders the selected run; it does not replace
 the agent-native workflow or approve a gate.
@@ -332,11 +791,11 @@ Together, `init`, `doctor` and `gate-check --json` turn AGDF from an instruction
 
 The repository-facing AGDF sources are maintained in:
 
-- `plugin/meta/agdf-agent-router.md`
-- `plugin/meta/agdf-plugin.definition.json`
-- `plugin/skills/`
-- `plugin/meta/agdf-runtime-contract.md`
-- `plugin/control/`
+- `plugins/agdf/meta/agdf-agent-router.md`
+- `plugins/agdf/meta/agdf-plugin.definition.json`
+- `plugins/agdf/skills/`
+- `plugins/agdf/meta/agdf-runtime-contract.md`
+- `plugins/agdf/control/`
 
 Skill routing is rendered from `skillSet.slug`, `useFor`, `boundary` and the target surface `skillPrefix`; it is not maintained as separate Codex, Claude Code and Copilot routing tables.
 
@@ -361,21 +820,39 @@ This README is the package guide. Keep framework rationale, limits and examples
 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:
 
 ```bash
+npm --prefix create-agdf run test:cli-gates
 npm --prefix create-agdf run smoke-test
 npm --prefix create-agdf run eval:skills
 npm --prefix create-agdf run eval:skills:record -- --surface codex --case gate-check-normal
 ```
 
+`test:cli-gates` runs the CLI against disposable repositories and prints each scenario's result and duration. During gate work, select one scenario with `npm --prefix create-agdf run test:cli-gates -- --case duplicate-prd` (`new-ur` and `bound-ur` are also available). Run the full smoke suite before release handoff.
+
 `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.
 
 ## Publishing
 
-The repository publishes this package and the primary user-facing `@agdf/cli` wrapper as one coupled AGDF release.
+The repository publishes this package, `@agdf/mcp-server` and the primary user-facing `@agdf/cli`
+wrapper as one coupled AGDF release.
 See the root `RELEASE.md` for the sequenced `agdf-v<version>` workflow and npm token requirements.
 
 ## Trademark Notice
 
 AGDF(TM) and AI Governance & Delivery Framework(TM) are marks of Arndt Gold.
 Use of the AGDF name and marks is governed by the project trademark guidelines.
+
+
+### Approval preparation compatibility
+
+New approvals require `run-present --run <id> --gate <gate> --revision <uuid>` before showing the
+returned text and waiting for the user. The presentation links the exact current gate artefact and
+shows its digest, run, gate and revision. Before the approval action it includes a short
+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.
+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.