create-agdf 0.10.0 → 0.10.2

package/README.md

@@ -25,7 +25,7 @@ Use a different target when Codex is not your agent surface:
 |---|---|---|
 | Claude Code | `npx --yes @agdf/cli@latest claude` | The AGDF plugin for Claude Code. |
 | 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` | Repository instructions, native skills, permissions and control templates. |
+| OpenCode, one repository | `npx --yes @agdf/cli@latest opencode-repo` | Durable control configuration that activates the once-installed global runtime. |
 | GitHub Copilot | `npx --yes @agdf/cli@latest copilot` | Repository instructions, visible skills and control templates. |
 | Durable control state in an existing setup | `npx --yes @agdf/cli@latest init` | Live `.agdf/control/` state when the repository explicitly needs it. |
 
@@ -35,7 +35,7 @@ For prerequisites, all surface-specific flows and operational boundaries, use th
 
 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.
 
-Preferred long-term CLI shape:
+Installation, activation and explicit lifecycle changes:
 
 ```bash
 npx --yes @agdf/cli@latest codex
@@ -49,26 +49,26 @@ npx --yes @agdf/cli@latest disable --surface codex --scope repository
 npx --yes @agdf/cli@latest uninstall --surface codex --scope global
 npx --yes @agdf/cli@latest init
 npx --yes @agdf/cli@latest config --language en
-npx --yes @agdf/cli@latest doctor
-npx --yes @agdf/cli@latest gate-check --status-card
-npx --yes @agdf/cli@latest gate-check --approval-envelope
-npx --yes @agdf/cli@latest gate-check --json
 ```
 
-Operational validation and bounded planning:
+Repeated operational validation and bounded planning use the installed, version-pinned local command:
 
 ```bash
-npx --yes @agdf/cli@latest delivery-map --json
-npx --yes @agdf/cli@latest delivery-path-search --surface codex --json
-npx --yes @agdf/cli@latest delivery-path-search --surface claude --json
+agdf doctor
+agdf gate-check --status-card
+agdf gate-check --approval-envelope
+agdf gate-check --json
+agdf delivery-map --json
+agdf delivery-path-search --surface codex --json
+agdf delivery-path-search --surface claude --json
 ```
 
 Canonical run lifecycle:
 
 ```bash
-npx --yes @agdf/cli@latest run-create --run <run_id>
-npx --yes @agdf/cli@latest run-migrate [--run <run_id>]
-npx --yes @agdf/cli@latest run-render-legacy --run <run_id>
+agdf run-create --run <run_id>
+agdf run-migrate [--run <run_id>]
+agdf run-render-legacy --run <run_id>
 ```
 
 ### Advanced / Compatibility
@@ -115,14 +115,22 @@ it does not localize the CLI lifecycle card.
 - `claude` installs the AGDF plugin globally for Claude Code
 - `copilot` writes `AGENTS.md`, Copilot custom instructions under `.github/`, visible repository skills under `.github/skills/`, and AGDF control templates under `.agdf/control/`
 - `opencode` installs the AGDF npm plugin and nine native skills as a user-wide OpenCode surface
-- `opencode-status` reports OpenCode global config, package loadability, global native-skill completeness, session signals and repository surface presence
+- `opencode-status` reports OpenCode global config, package loadability, global native-skill completeness, durable repository activation, legacy compatibility and observable session signals
 - `status` reports installation, repository activation and delivery separately without mutating state
 - `disable` writes a supported repository-local opt-out while retaining global capability and durable control state
 - `uninstall` previews and, only with `--confirm`, applies a selected global removal through supported native/owned operations
-- `opencode-repo` writes `opencode.json`, `.opencode/AGDF.md`, prefixed native OpenCode skills under `.opencode/skills/`, explicit question/edit/bash/skill permissions, and AGDF control templates under `.agdf/control/`
+- `opencode-repo` writes durable AGDF control configuration and templates under `.agdf/control/`; it does not copy a second OpenCode runtime surface
 - `both` writes the Codex repository-local marketplace plus the Copilot-facing repository files
 - `config` writes or updates only `.agdf/control/config.json` for an already installed plugin or an existing repository
 
+The `codex` and `claude` commands install from the complete plugin built into the released
+`create-agdf` package. They atomically stage it under an AGDF-owned user-data marketplace, register
+that stable local path through the host CLI and verify the exposed version. Source `plugin/` therefore
+contains no generated runtime bytes, and routine installed validation does not depend on the GitHub
+checkout, npm cache, PATH or registry. Rerunning either command performs the explicit update and
+migrates only the exact known legacy AGDF GitHub marketplace; foreign same-name registrations fail
+closed and failed host operations restore the prior owned stage.
+
 If the target repository already has an `AGENTS.md`, `create-agdf` preserves it and writes `AGENTS.agdf.md` instead of replacing your existing instructions. Merge the AGDF fragment into your current `AGENTS.md` when you want Copilot to load both instruction sets. The generated `.github/copilot-instructions.md` keeps Copilot pointed at `AGENTS.md`, `.github/skills/` and `.agdf/control/` without duplicating the full AGDF rule model. Use `--force` only when you explicitly want to overwrite generated files.
 
 Use the `codex-repo` target when AGDF should be available only inside one repository instead of being installed as a personal/global Codex plugin.
@@ -141,19 +149,19 @@ Then verify the visible installation state:
 npx --yes @agdf/cli@latest opencode-status --json
 ```
 
-The status command reports global configuration, package loadability, global native-skill completeness, session signals and whether the current repository has `.opencode/AGDF.md` plus the `agdf-gate-check` surface. It does not infer an active OpenCode session from config alone.
+The status command reports global configuration, package loadability, global native-skill completeness, durable repository activation, legacy local-surface compatibility and session signals. It does not infer an active OpenCode session from config alone.
 In JSON schema version 1, `repository_surface.gate_check_agent` remains a deprecated compatibility alias for the native `gate_check_skill` path so existing status consumers keep working during the agent-to-skill migration.
 
-Use the `opencode-repo` target when AGDF should be available to OpenCode from repository files:
+Use the `opencode-repo` target when a repository should opt into the globally installed AGDF OpenCode runtime:
 
 ```bash
 npm create agdf@latest -- opencode-repo
 ```
 
-OpenCode loads the AGDF npm plugin and global native skills from global OpenCode config, plus repository instructions from `.opencode/AGDF.md`, explicit `question`/`edit`/`bash`/`skill` permissions and canonical `agdf-` project skills under `.opencode/skills/`. Global adapters use the collision-safe `agdf-global-` prefix. AGDF for OpenCode has a global discoverability layer installed with `npx --yes @agdf/cli@latest opencode` and a repository-local governance surface generated by `opencode-repo`.
-Those generated skills load on demand through OpenCode's native `skill` tool. Use `agdf-gate-check` first for new build/change intent or unclear approval.
-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. If `opencode.json` already exists, AGDF keeps it unchanged and writes `opencode.agdf.json` as a merge fragment. Preserve any explicit `permission.question` decision when reviewing that fragment; `deny` uses exact-text fallback.
-The global layer makes the nine native AGDF skills discoverable, but does not activate repository governance by itself. Global skills fail closed until the current repository has `.opencode/AGDF.md`, `.opencode/skills/agdf-gate-check/SKILL.md` and `.agdf/control/`. Use `opencode-repo` to write that repository surface.
+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 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 nine 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.
 
 ## Control scaffold
 
@@ -224,7 +232,7 @@ the agent-native workflow or approve a gate.
 Use `delivery-path-search` only for high-impact planning decisions with several materially different next steps:
 
 ```bash
-npx --yes @agdf/cli@latest delivery-path-search --surface codex --json
+agdf delivery-path-search --surface codex --json
 ```
 
 The runtime uses bounded best-first Delivery Path Search, not MCTS. It is read-only and advisory: the result must be checked by canonical `gate-check`. Codex and Claude Code are executable, tool-enforced evaluator adapters and support opt-in `--generate-candidates`; generated proposals supplement the deterministic baseline and are deterministically validated before evaluation. Copilot and OpenCode reuse the same skill and contracts as instruction-only surfaces until conforming executable adapters are available.

package/bin/agdf-validator.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import process from "node:process";
+import { runValidatorCli } from "../lib/runtime/validator-application.js";
+
+try {
+  process.exitCode = await runValidatorCli(process.argv.slice(2));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

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

@@ -66,9 +66,9 @@ npx --yes @agdf/cli@latest config --language en
 Then check whether the live state is actionable:
 
 ```bash
-npx --yes @agdf/cli@latest doctor
-npx --yes @agdf/cli@latest doctor --json
-npx --yes @agdf/cli@latest gate-check --json
+agdf doctor
+agdf doctor --json
+agdf gate-check --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.

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

@@ -37,7 +37,7 @@ Do not mix both modes silently. Name the active mode in the output.
 
 ## Rules
 1. Brownfield first: understand the existing codebase before PRD/SD decisions when existing-system impact is possible, and again before implementation.
-2. Brownfield Review after `Approval: UR` is a sizing and routing step. It must visibly decide `quick_task`, `verified_change`, `structured_slice`, `structured_delivery`, or `block` before PRD depth or implementation is chosen.
+2. Brownfield Review after `Approval: UR` is a sizing and routing step. It must visibly decide `quick_task`, `verified_change`, `structured_slice`, `structured_delivery`, or `block` before PRD depth or implementation is chosen. Persist the completed review and its decision, scope reason, evidence and required next gate in the same internal operation; mark the review `done` only after both the artefact and canonical run projection are complete. An interrupted, incomplete or legacy record stays at fail-closed `Mode/Slice Decision` recovery without another user approval.
 3. Reuse-before-create: prefer existing modules, services, components, tables, endpoints, tests, and configuration.
 4. Minimal clean slice: choose the smallest durable intervention, not merely the smallest technical diff.
 5. No silent parallel structures.

package/generated/.github/skills/agdf-delivery-path-search/SKILL.md

@@ -35,16 +35,17 @@ Skip for routine questions, obvious local fixes and approved implementation with
 1. Run AGDF gate-check and inspect durable control state.
 2. Confirm that search is allowed and implementation is not occurring during exploration.
 3. Declare the active surface and its enforcement level.
-4. Invoke the shared CLI runtime:
+4. Resolve the exact-version surface-local validator using the same ownership rules as `agdf-gate-check`. Do not search `PATH`, query a registry, install a package or invoke `npx ...@latest` during routine planning. If no owned or explicitly configured exact-version validator is available, report `machine_validation: unavailable` or `machine_validation: external_required` and stop the machine-evaluated search.
+5. Invoke the shared CLI runtime:
 
 ```bash
-npx --yes @agdf/cli@latest delivery-path-search --surface <surface> --json
+node <surface-local-agdf> delivery-path-search --surface <surface> --json
 ```
 
 Optional AI-native candidate generation is explicit:
 
 ```bash
-npx --yes @agdf/cli@latest delivery-path-search \
+node <surface-local-agdf> delivery-path-search \
   --surface codex \
   --generate-candidates \
   --json
@@ -52,9 +53,9 @@ npx --yes @agdf/cli@latest delivery-path-search \
 
 It supplements the deterministic baseline with at most one bounded generator call. Treat proposals as untrusted until the canonical core validates schema, gate action, scope, duplicates and material diversity. Report generation provenance, budgets, rejections and failure. Never hide deterministic fallback or switch providers automatically.
 
-5. Treat facts, repository evidence, assumptions and model judgements separately.
-6. Return exactly one recommendation or `no_safe_recommendation`.
-7. Run canonical AGDF gate-check after search. Never translate a recommendation into permission.
+6. Treat facts, repository evidence, assumptions and model judgements separately.
+7. Return exactly one recommendation or `no_safe_recommendation`.
+8. Run canonical AGDF gate-check after search. Never translate a recommendation into permission.
 
 ## Enforcement
 

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

@@ -44,17 +44,23 @@ If required control files are missing, do not automatically create a full `.agdf
 The default first action is to draft the minimal UR in the response and request `Approval: UR`.
 Use `init` only when the user explicitly asks for durable AGDF control state, the repository already uses `.agdf/control/` as its live working state, or a deterministic CLI/CI setup path is being executed.
 
-Use the executable control path when a machine-readable check is requested, when the gate state is ambiguous, when CI or PR evidence is needed, when deterministic ready-gate rendering is required, or when a repository-local automation needs JSON output. Prefer an already installed `agdf` executable; use registry-resolved `npx ...@latest` only for bootstrap, installation, explicit refresh or when no local executable exists:
+Use the executable control path when a machine-readable check is requested, when the gate state is ambiguous, when CI or PR evidence is needed, when deterministic ready-gate rendering is required, or when a repository-local automation needs JSON output. Resolve the version-matched validator owned by the active surface first: `<plugin-root>/runtime/agdf-local.js` for Codex or Claude, or `<opencode-config>/agdf/bin/agdf-local.js` for OpenCode. Run its `--resolve-only --json` probe before treating its output as machine evidence. An explicitly configured absolute `AGDF_VALIDATOR_PATH` is the only secondary local candidate and must match the active AGDF version.
+
+Routine validation uses that resolved local entrypoint:
 
 ```bash
-npx --yes @agdf/cli@latest init
-npx --yes @agdf/cli@latest doctor --json
-npx --yes @agdf/cli@latest gate-check --json
-npx --yes @agdf/cli@latest delivery-map --json
+node <surface-local-agdf> doctor --json
+node <surface-local-agdf> gate-check --json
+node <surface-local-agdf> delivery-map --json
 ```
 
-For repeated local checks, use `agdf doctor --json`, `agdf gate-check --json` or
-`agdf gate-check --approval-envelope`. The last command prints the validated
+If no exact-version local validator exists, continue through agent-native inspection where permitted
+and state `machine_validation: unavailable` or `external_required`; do not automatically invoke
+`npx`, install a package or contact the registry. Registry-resolved commands are reserved for an
+explicit bootstrap, installation, repair or refresh requested as a lifecycle action.
+
+For repeated local checks, use the resolved entrypoint with `doctor --json`, `gate-check --json` or
+`gate-check --approval-envelope`. The last command prints the validated
 two-card exact-text interaction; JSON exposes the same `approval_presentation`
 for a native-capable adapter.
 
@@ -65,93 +71,24 @@ The CLI reports are validators and JSON evidence, not the primary user experienc
 
 ## Native Interaction Path
 
-Use the Runtime Contract's Native Interaction Contract to classify every candidate interaction as `clarification`, `tool_permission`, `gate_approval`, `blocked` or `status` before selecting a host control.
-
-Prefer inspection over asking. Do not invoke a structured question for status reporting, facts available in the repository, routine read-only work or a gate that is not ready. Do not repeatedly prompt for the same non-ready gate.
-
-For a fresh request classified as read-only with no required run decision, emit the locale pack's
-`primary.readOnlyOrientationDescription` sentence once before the findings. This path creates no run, persists
-nothing, requests no approval and reuses the existing status projection. Do not repeat the sentence
-during the same request.
-
-For a ready `gate_approval`:
-
-1. Resolve exactly one selected run and evaluate the current gate.
-2. Confirm the required durable artefact is present and ready before presenting a question.
-3. Consume the validated canonical `approval_presentation` for the same selected run, gate and revision. Do not compose or rewrite headings, fields, card order, locale copy or Markdown in the model.
-4. Emit its complete `run_status_card` block first and `gate_transition_card` block second in one immediately preceding assistant message. The first heading is neutral; the five status fields are selected run, readiness, current gate, human-readable required decision and a neutral approve/revise/decline instruction. The exact approval value appears only in the transition card across these two blocks.
-5. Never put either card only into the question, button description or hidden tool context. Do not invoke a native question until both rendered blocks are visible.
-6. If the projection is absent or invalid, render no partial card and invoke no native control. Re-evaluate the gate. Use only the exact-text request when the same gate is still ready and its canonical value is independently valid; otherwise report the non-ready reason and request no decision.
-7. Distinguish internal process steps from user decisions in natural language. For example, after `Approval: TP`, say that pre-implementation Brownfield Analysis runs next and that no further user action is required now; do not expose `next_user_gate: none` or `user_action_required: no`, and do not ask for a second approval for Brownfield Analysis.
-8. Ask exactly one question that names the selected `run_id` and `current_gate`.
-9. Offer options in stable order: exact `Approval: <GateName>`, localized revise and localized decline. Add explicit cancel only where supported after decline; otherwise host dismissal maps to cancel. Never preselect, skip, auto-submit or reorder an option.
-10. Use the surface adapter declared in the canonical plugin definition only when it can wait for deliberate input without auto-resolution and can transport `exact_option_value` or `separate_label_and_value`; never invoke a `decorated_label_only` adapter. Otherwise request the same exact approval in concise text.
-11. Render both supplied cards once in that single complete assistant message. Never merge, reverse, omit, duplicate or reconstruct them; the decision heading does not replace either card. If the native attempt is unavailable or not applied, continue to exact text without repeating either card.
-12. Re-run gate evaluation for the same run and expected gate after the response and immediately before persistence.
-13. Reject a missing artefact, ambiguous or wrong run, wrong gate, stale expected gate, timeout/default, hook-supplied answer, agent message, technical permission outcome or plan approval.
-14. Persist accepted input only through the existing control-state workflow.
-
-Before projecting a ready gate, evaluate adapter callability, deliberate wait safety and canonical
-approval-value transport. Expose `native_attempt_required: true` only when that preflight proves
-`exact_option_value` or `separate_label_and_value` transport with safe deliberate waiting. Decorated-only,
-missing, conflicting or unknown capability exposes false and `unavailable_before_invocation`; unsafe
-waiting exposes false and `unsafe_to_wait`. In both cases use exact text without invoking the adapter.
-A hook, permission result or session context message cannot replace an eligible attempt or supply its answer.
-
-Before composing the question, resolve the configured chat locale from `.agdf/control/config.json` through `../agdf-interaction-locales.json`: exact complete pack, language subtag, then English fallback. German and English are initial packs, not a closed language list. Keep `Approval: <GateName>` exactly unchanged in every language, and do not mix presentation languages within one interaction. Labels and descriptions use the same resolved locale; host-owned UI chrome remains host-owned and may use a different language.
-
-The canonical renderer resolves the complete locale pack. The initial German pack includes `Bereit für deine Entscheidung`, `Jetzt freigeben` and `Danach`; the initial English pack includes `Ready for your decision`, `Approve now` and `Next`. Verify that the supplied blocks use one locale and a neutral decision heading while leaving the exact gate identifier and approval value unchanged. Do not model-edit the supplied Markdown.
-
-The primary option is derived exactly as `Approval: <GateName>` from the evaluated current gate; only explanatory copy and non-authoritative outcome labels are localized. Concrete localized copy belongs to the user-facing interaction layer or the approved delivery artefact, not to English runtime rules.
-
-Make exactly one native-attempt for the eligible ready gate. If the host does not render,
-apply or safely return the native question on that attempt, switch immediately
-to the exact textual approval. Do not ask the user to request the buttons again
-and do not create a retry loop or simulated control.
-
-State the outcome visibly: `presented`, `unavailable_before_invocation`,
-`attempted_not_applied` or `unsafe_to_wait`. For every fallback, say in the
-configured locale why a native control was not usable, show the exact approval
-value and confirm that authority is unchanged. This transient outcome is not
-approval evidence. A new explicit user request may reopen the unchanged decision
-only after fresh run/gate/artefact revalidation; never retry automatically.
-
-Surface behavior:
-
-- Codex: invoke the native short-question/request-user-input control only when preflight proves `exact_option_value` or `separate_label_and_value`, and omit auto-resolution. The canonical `decorated_label_only` capability must use exact text without invoking the adapter. `Approval: <GateName> (Recommended)` is never a valid option or approval.
-- Claude Code: invoke `AskUserQuestion` on the first eligible attempt only when no timeout can auto-continue and no hook supplies `answers` or `updatedInput`; if it is not rendered or applied, use exact text immediately. Claude permissions and `ExitPlanMode` remain separate.
-- OpenCode: use built-in `question` when permitted. Preserve explicit `permission.question` denial and use exact text in that case. `once`, `always`, `reject` and auto mode never become gate input.
-- GitHub Copilot: the current repository-instruction surface has no conforming native approval adapter. Transmit the canonical rendered cards followed by the exact-text request; never claim or simulate a native control. Copilot tool confirmations, plan interactions and repository permissions remain separate.
-- Other, unavailable or non-interactive surfaces: use exact textual approval and wait for a new explicit user response.
-
-Localized labels such as `Überarbeiten`/`Revise`, `Ablehnen`/`Decline` and `Abbrechen`/`Cancel` are presentation mappings to stable non-approval outcomes only. A label, description, option position or recommendation never authorizes a gate. Host-provided free-text or `Überspringen`/`Skip` actions never advance an AGDF gate.
-
-A free-form response must still exactly match the current gate's approval formula after revalidation. Keep `decline`, `cancel`, `no_response`, `timeout`, `empty`, `invalid` and `stale` distinct; none advances the gate. Native presentation, host permission and plan approval are inputs or separate authority domains, never durable AGDF authority.
-
-Every primary chat card shows the selected run's `UR`, `PRD`, `SD` and `TP` in that order. Render an existing canonical path as a readable link and a missing artefact as localized non-link text; never guess paths. Resolve the human run title from current artefact heading, approved UR heading, Objective, then normalized `run_id`. Status, blocked, clarification and internal-step interactions use the same locale and artefact projection but do not show approval buttons. Keep raw process keys and machine status values in JSON or audit detail.
-
-### Breadcrumb Rendering
-
-The compact human Run Status Card includes a single-line path-derived breadcrumb showing the user's position in the delivery journey. Derive it from the Mode/Slice Decision and the Approvals table — not a fixed template. Use `✓` for fulfilled, `●` for current, `○` for open, separated by ` · `. Non-applicable gates are absent. See the Runtime Contract §Breadcrumb for the path templates and the derived `breadcrumb` array.
-
-### Post-Acceptance Transition Narration
-
-After each accepted gate approval is persisted, emit exactly one narration line using the template `<what was satisfied> → <what the agent does next internally> → <user action: yes/no>`. This generalizes the existing TP pattern (step 7 above) to every gate advancement. The narration is post-acceptance only: it never appears in the same message as the Gate Transition Card, never contains the `Approval:` value, and never repeats the decision's effect. For internal steps (Brownfield Review, Brownfield Analysis), state what the agent does next and that no user action is required, without exposing `next_user_gate: none` or asking for a second approval. See the Runtime Contract §Post-Acceptance Transition Narration for the full contract.
-
-### Internal-State Collapse in the Human Card
-
-When rendering the compact human Run Status Card, collapse internal sub-states (`verified_change` sub-states, `context_graph_required_action`, `multi_scope_state`) to stable human labels. `escalated`, `open_gap` and `blocked` remain explicitly visible. The full machine/audit projection retains all raw values unchanged. See the Runtime Contract §Internal-State Collapse for the complete mapping table.
-
-### On-Demand "Why?" Response
+`../contracts/interaction.md` is the complete normative owner for interaction kinds, locale,
+canonical values, presentation order, adapter capability, deliberate waiting, native/fallback
+behavior, transient outcomes, permissions and post-response validation. Load and apply that contract;
+do not restate or infer a surface matrix in this skill.
 
-When the user asks "why?" or "Warum?" at any gate or internal step, respond with a `status` interaction (not `gate_approval`):
+This skill owns only these operational responsibilities:
 
-1. Pull the curated rationale from `gateRationale()` in the resolved locale.
-2. Compose one fulfilled line from the selected run's Approvals table and artefact status.
-3. Compose one protects-against line from the gate's rationale and the existing `primary.actions` copy.
-4. Do not show approval controls. Do not advance any gate. Do not merge with the approval envelope.
+1. Select exactly one run and evaluate its current gate.
+2. Confirm that the required durable artefact is present and ready.
+3. Consume the canonical `approval_presentation` verbatim for the selected run, gate and revision.
+4. Present that projection and obtain deliberate input through the contract-selected native or exact-text path.
+5. Revalidate the same run, gate and revision immediately after the response and before persistence.
+6. Persist only a currently valid exact approval through the existing control-state workflow.
 
-The response is deterministic: same gate, same question, same answer. The `gate_approval` options remain exactly `approve | revise | decline | cancel`; no "why" option is added. See the Runtime Contract §Gate-Rationale-Registry and §On-Demand "Why?" Interaction for the full contract.
+For status, blocked, read-only or rationale interactions, consume the same canonical projection and
+locale contract without asking for approval. Internal process steps remain distinct from user
+decisions. If the projection, adapter evidence or revalidation is missing, follow the contract's
+fail-closed outcome and leave authority unchanged.
 
 ## Rules
 1. Fail closed when a required approval or artefact status is missing.

package/generated/.github/skills/agdf-interaction-locales.json

@@ -79,6 +79,7 @@
         "OR": "Delivery report",
         "Verified Change": "Verified change",
         "Quick Task": "Quick task",
+        "Compact Delivery": "Compact Delivery",
         "Block": "Block"
       },
       "gateActionTitles": {
@@ -281,6 +282,7 @@
         "OR": "Lieferbericht",
         "Verified Change": "Verified Change",
         "Quick Task": "Quick Task",
+        "Compact Delivery": "Kompakte Lieferung",
         "Block": "Block"
       },
       "gateActionTitles": {

package/generated/.github/skills/contracts/gate-transition.md

@@ -57,7 +57,7 @@ They must not override AGDF gates, approvals or the Runtime Contract.
 - Approval of one user gate permits work on the next allowed gate artefact or required internal step only. It does not permit implementation unless the approved gate is `TP` and required internal implementation prerequisites are satisfied.
 - Gates must never be skipped or inferred from urgency, tone, chat history, task wording or an instruction to "start". The next allowed action is always the next unsatisfied gate or internal mandatory step.
 - Missing control files or missing current-state fields do not forbid the agent from preparing the current allowed artefact. They forbid later-gate work and implementation. For a fresh request, the default allowed work is to draft a minimal UR in the response and request `Approval: UR`. Initialize or write `.agdf/control/` only when the user explicitly asks for durable AGDF control state, the repository already uses `.agdf/control/` as its live working state, or a deterministic CLI/CI setup path is being executed.
-- `Approval: UR` permits Brownfield Review after G-00 first, then a Mode/Slice Decision. It never permits implementation by itself.
+- `Approval: UR` permits Brownfield Review after G-00 first. The review records its Mode/Slice Decision in the same internal operation when evidence is sufficient; the user is told that no action is required now. A separate `Mode/Slice Decision` step is fail-closed recovery for incomplete or legacy review state, not a normal user decision. UR approval never permits implementation by itself and does not preselect PRD.
 - PRD, SD and TP depth is chosen after Brownfield Review through the Mode/Slice Decision, not before existing-system impact is understood.
 - The Mode/Slice Decision must be visible before any PRD shortcut, Quick Task execution or implementation: record the decision, required next gate, scope reason and evidence in the selected canonical `RUN_STATE.md` or an equivalent linked control artefact.
 - `Approval: PRD` permits Solution Design drafting, not implementation.
@@ -76,6 +76,9 @@ After an approved and durable UR, perform a lightweight `Brownfield Review` befo
 
 This review is not a new user approval gate, not PRD, not SD, not TP and not implementation permission.
 It is the sizing and routing step that decides how much later gate discipline is actually needed.
+When evidence is sufficient, persist the review and Mode/Slice selection together; do not expose a
+second routine user decision. Keep the standalone Mode/Slice step only for fail-closed recovery when
+the review record is incomplete or legacy.
 
 Its output is limited to:
 
@@ -131,4 +134,3 @@ The `agdf-brownfield-analysis` skill has two explicit modes:
 - `pre_implementation_analysis`: implementation-preparation analysis after approved durable TP; verifies reuse path, owners, regression risk and fit before `CD+Tests`.
 
 Do not mix the modes silently. Name the active mode in Brownfield output.
-

package/generated/.github/skills/contracts/modes.md

@@ -24,6 +24,18 @@ Use this compact output shape when no formal gate artefact is required:
 
 Do not add a separate `Quality outlook` line for pure Quick Tasks unless the task became a relevant run.
 
+### Quick Task and Compact Delivery
+
+Use **Quick Task** for ungated questions, reviews, debugging and eligible narrow fixes that introduce
+no new product semantics or formal artefacts. When an approved UR is followed by a Brownfield Review
+that selects the persisted `quick_task` mode, use **Compact Delivery** as the human-facing label. The
+stored and JSON value remains `quick_task`; Compact Delivery is not a new mode or approval gate.
+
+Brownfield Review owns the Mode/Slice selection. A completed review records its decision, scope
+reason, evidence and required next depth in the same internal operation. `Mode/Slice Decision` remains
+only a fail-closed recovery step for incomplete or legacy records and is not a normal second user
+decision.
+
 ### Verified Change
 
 `verified_change` is a compact, fail-closed path for a bounded user-visible change with one canonical owner and deterministic proof. It is neither a prose exception nor a new user approval gate.
@@ -88,4 +100,3 @@ For narrow defect work, a repository may use a lightweight bug scope instead of
 
 The Bug Lightweight Track does not remove QA, OR, evidence, Brownfield fit or exact approvals required by the target repository.
 If the bug grows beyond the stated boundary, escalate to normal AGDF gate flow.
-

package/generated/.opencode/README.md

@@ -2,16 +2,14 @@
 
 These files were generated from the AGDF source repository for OpenCode.
 
-- `opencode.json` loads the npm plugin `create-agdf` and `.opencode/AGDF.md` as repository instructions.
-- AGDF for OpenCode has a global npm/native-skill discoverability layer and this repository-local governance surface.
-- The global plugin and skills do not replace `.opencode/AGDF.md`, `.opencode/skills/` or `.agdf/control/`; repository files remain the AGDF source of truth.
-- `opencode.json` allows the built-in `question` tool, keeps `edit` and `bash` on `ask` and explicitly allows the generated `agdf-*` skills; global adapters use `agdf-global-*` to avoid same-name masking.
+- The globally installed npm plugin `create-agdf` owns the shared OpenCode runtime surface.
+- A repository is AGDF-active when `.agdf/control/config.json` is valid; this activation does not copy `.opencode/` assets.
+- Global adapters use `agdf-global-*` to avoid same-name masking by supported legacy local `agdf-*` skills.
 - Preserve an explicit user `permission.question: deny`; AGDF then uses exact textual approval and never interprets OpenCode permission outcomes or auto mode as gate authority.
-- `.opencode/skills/` contains native OpenCode skills generated from the canonical AGDF skills.
-- For new build/change intent or unclear approval, load `agdf-gate-check` through OpenCode's native `skill` tool.
-- Use `npx --yes @agdf/cli@latest opencode-status --json` to distinguish global hook/native-skill configuration, package loadability, session activity and this repository surface.
+- For new build/change intent or unclear approval, load `agdf-global-gate-check` through OpenCode's native `skill` tool.
+- Use `npx --yes @agdf/cli@latest opencode-status --json` to distinguish global hook/native-skill configuration, package loadability, durable activation, legacy compatibility and session activity.
 - For deterministic ready-gate rendering, prefer an installed `agdf gate-check --approval-envelope`; reserve `agdf gate-check --json` for native-adapter input, automation or audit evidence and use `npx ...@latest` only for bootstrap, refresh or a missing local executable.
-- `.opencode/agdf-runtime-contract.md` is the shared gate and output contract.
+- The globally installed runtime contract is the shared gate and output contract.
 
 ## Skills
 

package/generated/.opencode/agdf-interaction-locales.json

@@ -79,6 +79,7 @@
         "OR": "Delivery report",
         "Verified Change": "Verified change",
         "Quick Task": "Quick task",
+        "Compact Delivery": "Compact Delivery",
         "Block": "Block"
       },
       "gateActionTitles": {
@@ -281,6 +282,7 @@
         "OR": "Lieferbericht",
         "Verified Change": "Verified Change",
         "Quick Task": "Quick Task",
+        "Compact Delivery": "Kompakte Lieferung",
         "Block": "Block"
       },
       "gateActionTitles": {

package/generated/.opencode/contracts/gate-transition.md

@@ -57,7 +57,7 @@ They must not override AGDF gates, approvals or the Runtime Contract.
 - Approval of one user gate permits work on the next allowed gate artefact or required internal step only. It does not permit implementation unless the approved gate is `TP` and required internal implementation prerequisites are satisfied.
 - Gates must never be skipped or inferred from urgency, tone, chat history, task wording or an instruction to "start". The next allowed action is always the next unsatisfied gate or internal mandatory step.
 - Missing control files or missing current-state fields do not forbid the agent from preparing the current allowed artefact. They forbid later-gate work and implementation. For a fresh request, the default allowed work is to draft a minimal UR in the response and request `Approval: UR`. Initialize or write `.agdf/control/` only when the user explicitly asks for durable AGDF control state, the repository already uses `.agdf/control/` as its live working state, or a deterministic CLI/CI setup path is being executed.
-- `Approval: UR` permits Brownfield Review after G-00 first, then a Mode/Slice Decision. It never permits implementation by itself.
+- `Approval: UR` permits Brownfield Review after G-00 first. The review records its Mode/Slice Decision in the same internal operation when evidence is sufficient; the user is told that no action is required now. A separate `Mode/Slice Decision` step is fail-closed recovery for incomplete or legacy review state, not a normal user decision. UR approval never permits implementation by itself and does not preselect PRD.
 - PRD, SD and TP depth is chosen after Brownfield Review through the Mode/Slice Decision, not before existing-system impact is understood.
 - The Mode/Slice Decision must be visible before any PRD shortcut, Quick Task execution or implementation: record the decision, required next gate, scope reason and evidence in the selected canonical `RUN_STATE.md` or an equivalent linked control artefact.
 - `Approval: PRD` permits Solution Design drafting, not implementation.
@@ -76,6 +76,9 @@ After an approved and durable UR, perform a lightweight `Brownfield Review` befo
 
 This review is not a new user approval gate, not PRD, not SD, not TP and not implementation permission.
 It is the sizing and routing step that decides how much later gate discipline is actually needed.
+When evidence is sufficient, persist the review and Mode/Slice selection together; do not expose a
+second routine user decision. Keep the standalone Mode/Slice step only for fail-closed recovery when
+the review record is incomplete or legacy.
 
 Its output is limited to:
 
@@ -131,4 +134,3 @@ The `agdf-brownfield-analysis` skill has two explicit modes:
 - `pre_implementation_analysis`: implementation-preparation analysis after approved durable TP; verifies reuse path, owners, regression risk and fit before `CD+Tests`.
 
 Do not mix the modes silently. Name the active mode in Brownfield output.
-

package/generated/.opencode/contracts/modes.md

@@ -24,6 +24,18 @@ Use this compact output shape when no formal gate artefact is required:
 
 Do not add a separate `Quality outlook` line for pure Quick Tasks unless the task became a relevant run.
 
+### Quick Task and Compact Delivery
+
+Use **Quick Task** for ungated questions, reviews, debugging and eligible narrow fixes that introduce
+no new product semantics or formal artefacts. When an approved UR is followed by a Brownfield Review
+that selects the persisted `quick_task` mode, use **Compact Delivery** as the human-facing label. The
+stored and JSON value remains `quick_task`; Compact Delivery is not a new mode or approval gate.
+
+Brownfield Review owns the Mode/Slice selection. A completed review records its decision, scope
+reason, evidence and required next depth in the same internal operation. `Mode/Slice Decision` remains
+only a fail-closed recovery step for incomplete or legacy records and is not a normal second user
+decision.
+
 ### Verified Change
 
 `verified_change` is a compact, fail-closed path for a bounded user-visible change with one canonical owner and deterministic proof. It is neither a prose exception nor a new user approval gate.
@@ -88,4 +100,3 @@ For narrow defect work, a repository may use a lightweight bug scope instead of
 
 The Bug Lightweight Track does not remove QA, OR, evidence, Brownfield fit or exact approvals required by the target repository.
 If the bug grows beyond the stated boundary, escalate to normal AGDF gate flow.
-

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

@@ -37,7 +37,7 @@ Do not mix both modes silently. Name the active mode in the output.
 
 ## Rules
 1. Brownfield first: understand the existing codebase before PRD/SD decisions when existing-system impact is possible, and again before implementation.
-2. Brownfield Review after `Approval: UR` is a sizing and routing step. It must visibly decide `quick_task`, `verified_change`, `structured_slice`, `structured_delivery`, or `block` before PRD depth or implementation is chosen.
+2. Brownfield Review after `Approval: UR` is a sizing and routing step. It must visibly decide `quick_task`, `verified_change`, `structured_slice`, `structured_delivery`, or `block` before PRD depth or implementation is chosen. Persist the completed review and its decision, scope reason, evidence and required next gate in the same internal operation; mark the review `done` only after both the artefact and canonical run projection are complete. An interrupted, incomplete or legacy record stays at fail-closed `Mode/Slice Decision` recovery without another user approval.
 3. Reuse-before-create: prefer existing modules, services, components, tables, endpoints, tests, and configuration.
 4. Minimal clean slice: choose the smallest durable intervention, not merely the smallest technical diff.
 5. No silent parallel structures.

package/generated/.opencode/skills/agdf-delivery-path-search/SKILL.md

@@ -35,16 +35,17 @@ Skip for routine questions, obvious local fixes and approved implementation with
 1. Run AGDF gate-check and inspect durable control state.
 2. Confirm that search is allowed and implementation is not occurring during exploration.
 3. Declare the active surface and its enforcement level.
-4. Invoke the shared CLI runtime:
+4. Resolve the exact-version surface-local validator using the same ownership rules as `agdf-gate-check`. Do not search `PATH`, query a registry, install a package or invoke `npx ...@latest` during routine planning. If no owned or explicitly configured exact-version validator is available, report `machine_validation: unavailable` or `machine_validation: external_required` and stop the machine-evaluated search.
+5. Invoke the shared CLI runtime:
 
 ```bash
-npx --yes @agdf/cli@latest delivery-path-search --surface <surface> --json
+node <surface-local-agdf> delivery-path-search --surface <surface> --json
 ```
 
 Optional AI-native candidate generation is explicit:
 
 ```bash
-npx --yes @agdf/cli@latest delivery-path-search \
+node <surface-local-agdf> delivery-path-search \
   --surface codex \
   --generate-candidates \
   --json
@@ -52,9 +53,9 @@ npx --yes @agdf/cli@latest delivery-path-search \
 
 It supplements the deterministic baseline with at most one bounded generator call. Treat proposals as untrusted until the canonical core validates schema, gate action, scope, duplicates and material diversity. Report generation provenance, budgets, rejections and failure. Never hide deterministic fallback or switch providers automatically.
 
-5. Treat facts, repository evidence, assumptions and model judgements separately.
-6. Return exactly one recommendation or `no_safe_recommendation`.
-7. Run canonical AGDF gate-check after search. Never translate a recommendation into permission.
+6. Treat facts, repository evidence, assumptions and model judgements separately.
+7. Return exactly one recommendation or `no_safe_recommendation`.
+8. Run canonical AGDF gate-check after search. Never translate a recommendation into permission.
 
 ## Enforcement