create-agdf 0.20.2 → 0.30.0

package/generated/plugins/agdf/companion/view.mjs

@@ -0,0 +1,84 @@
+// Panel view model and terminal text (AC-002, AC-005, AC-006, AC-010): turns a snapshot, the
+// session's assignment and the user's choices into localized, display-ready fields. Read-only and
+// host-independent; the adapter draws it on desktop or as text in the terminal.
+
+import { assignRun } from './assignment.mjs';
+import { FIGURE_TEXT } from './figure.mjs';
+import { condensedGateBar, gateBar, gateMarks } from './gate-bar.mjs';
+import { gateTitle, label, localizeNextStep } from './localization.mjs';
+import { displayState } from './state.mjs';
+
+const two = value => String(value).padStart(2, '0');
+// Last part of a project root in either path form ("C:\Work\app\" → "app").
+const folderName = root => String(root ?? '').replace(/[\\/]+$/u, '').split(/[\\/]/u).pop() || String(root ?? '');
+// Host-local wall-clock time, HH:MM.
+export const clockText = ms => { const at = new Date(ms); return `${two(at.getHours())}:${two(at.getMinutes())}`; };
+
+// input: { snapshot, sessionStartedAt, selection, mention, isBrowsing, isTurnActive, registry, labels,
+// locale, columns, isObjectiveExpanded }. Display only: the adapter persists selection changes.
+export function buildPanelView(input) {
+  const { snapshot, registry, labels, locale } = input;
+  const t = (path, params) => label(labels, locale, path, params);
+  const base = { title: t('title'), locale, mood: 'neutral', stateLabel: t('states.neutral'),
+    readAt: snapshot ? t('fields.lastRead', { time: clockText(snapshot.readAt) }) : null,
+    stale: snapshot?.stale ? t('messages.stale', { time: clockText(snapshot.stale.failedAt), readAt: clockText(snapshot.readAt) }) : null,
+    canRetry: true, openRuns: [] };
+  const neutral = (message, extra = {}) => ({ ...base, message, ...extra });
+  const unreadable = reason => neutral(t('messages.unreadable', { reason: t(`unreadable.${reason}`) }));
+
+  if (!snapshot) return neutral(t('messages.reading'), { readAt: null });
+  if (snapshot.status === 'failed') return unreadable('failed');
+  if (snapshot.status === 'no_control') {
+    return neutral(t('messages.noControl', { folder: folderName(snapshot.root) }), { hint: t('messages.noControlHint', { path: snapshot.root ?? '' }) });
+  }
+
+  const { run, origin, open, chatRunId } = assignRun({ runs: snapshot.runs, sessionStartedAt: input.sessionStartedAt, selection: input.selection,
+    mention: input.mention ?? null, isBrowsing: Boolean(input.isBrowsing) });
+  // Each open run carries its condensed gate bar for the list (owner request of 2026-10-28).
+  const openRuns = open.map(item => ({ id: item.id, objective: item.objective, bar: condensedGateBar(gateMarks(item)) }));
+  if (!run) {
+    const broken = input.selection && snapshot.unreadable.find(item => item.id === input.selection);
+    if (broken) return { ...unreadable(broken.reason), openRuns, chatRunId };
+    if (!open.length) return neutral(t('messages.noOpenRuns'));
+    return neutral(t('messages.noRunAssigned'), { hint: t('messages.noRunAssignedHint'), openRuns, chatRunId,
+      openCount: t('fields.openRuns', { count: open.length }) });
+  }
+
+  const position = open.findIndex(item => item.id === run.id);
+  const openCount = position >= 0 ? t('fields.position', { position: position + 1, count: open.length }) : t('fields.openRuns', { count: open.length });
+  const state = displayState(run, { isTurnActive: input.isTurnActive });
+  // A run in an unknown state keeps stepping and the way back to the chat's run (CR-F01).
+  if (state.mood === null) return { ...unreadable('unknownState'), runId: run.id, openRuns, chatRunId, openCount };
+  const reasonParams = { gate: gateTitle(registry, locale, state.reason.gate), decision: t(`decisions.${state.reason.decision}`) };
+  return {
+    ...base,
+    mood: state.mood,
+    stateLabel: t(`states.${state.mood}`),
+    reason: t(`reasons.${state.reason.key}`, reasonParams),
+    gateBar: gateBar(gateMarks(run), input.columns),
+    runId: run.id,
+    objective: run.objective,
+    isObjectiveExpanded: Boolean(input.isObjectiveExpanded),
+    nextStep: run.lifecycle === 'completed' ? null : localizeNextStep(registry, locale, run.next).text,
+    origin: t(`origin.${origin}`),
+    originKind: origin,
+    chatRunId,
+    openRuns,
+    openCount,
+  };
+}
+
+// Text fallback for surfaces without Svg: state, gate bar and next step on separate lines.
+export function terminalText(view, { labels, locale }) {
+  const t = path => label(labels, locale, path);
+  const lines = [view.title, `${FIGURE_TEXT[view.mood]} ${view.stateLabel}${view.reason ? ` · ${view.reason}` : ''}`];
+  if (view.message) lines.push(view.message);
+  if (view.hint) lines.push(view.hint);
+  if (view.gateBar) lines.push(view.gateBar);
+  if (view.runId) lines.push(view.origin ? `${view.runId} · ${view.origin}` : view.runId);
+  if (view.objective) lines.push(`${t('fields.objective')}: ${view.objective}`);
+  if (view.nextStep) lines.push(`${t('fields.nextStep')}: ${view.nextStep}`);
+  if (view.stale) lines.push(view.stale);
+  if (view.readAt) lines.push(view.readAt);
+  return lines.join('\n');
+}

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

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

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

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

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

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

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

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

package/generated/plugins/agdf/mcp/server/README.md

@@ -2,7 +2,7 @@
 
 Local STDIO MCP adapter.
 
-MCP tools: `agdf_dispatch`, `agdf_inspect`, `agdf_prepare`, `agdf_record`, `agdf_approve`, `agdf_revise`, `agdf_closeout`.
+MCP tools: `agdf_dispatch`, `agdf_inspect`, `agdf_project`, `agdf_run`, `agdf_prepare`, `agdf_record`, `agdf_approve`, `agdf_revise`, `agdf_closeout`.
 
 [Integration guide](../../docs/architecture/09-mcp-integrationsrichtlinien.md).
 [Command flow](../../docs/architecture/core-mcp-command-flow.md): bounded writes,
@@ -10,6 +10,13 @@ contract/status reads, original-operation recovery and the app-only decision fac
 Host tool permission is separate from a deliberate gate decision. The source candidate's
 click actions remain disabled while native app-only mediation is unqualified.
 
+`agdf_closeout` also ends active runs as `superseded` or `abandoned`. Kind `closure.preview` takes
+`{"entries":[{"run_id","outcome","reason","successor_run"|"successor_reference"}]}` and returns the
+preview text with the phrase `Close runs: <preview_id>`; kind `closure.apply` takes `preview_id`
+and the owner's verbatim `confirmation`. Both use a target-bound envelope without `run_id` or
+`expected_revision_id`; every other `agdf_closeout` kind keeps the per-run envelope. The agent
+forwards only the owner's reply and never supplies the phrase itself.
+
 `agdf_inspect` also exposes read-only draft preflight through `operation: artifact-readiness`:
 
 ```json
@@ -44,9 +51,59 @@ Keep the original document revision, including for historical reads. Catalog pag
 16 candidates; scans stop at 256 records, 1 MiB of record bytes or 1024 directory entries. Catalog,
 document and preview cursors are not interchangeable. Prepared records prove no human approval.
 
+For a known task target, always send `primary_target` together with its actual `target_source`:
+`explicit_target` for a named target, `continued_target` for a previously confirmed target, or
+`current_repository` for an unambiguous request about the current repository. `working_directory`
+alone never selects it. A bound `gate-check` returns `navigation.read_context`: copy those explicit
+selectors into later status reads, adding `operation: "gate-check"`. This is a reusable locator,
+not a connection session or permission; target and Run checks run again on every call. Never add
+`gate` or `expected_revision_id` to a status read. For document reads, copy the exact returned
+`read_arguments`, including the original revision. A uniquely selected document is the first
+`navigation.next_calls` entry, ahead of optional operation help. Follow every document page before
+that help. An ambiguous or incomplete catalog still requires selection and never chooses a record.
+
+Input-validation hints describe missing fields for the selected operation and invalid Run-ID
+syntax. They neither normalize IDs nor fill targets, replace revisions, replay writes or grant
+approval. The original SDK and Core validators continue to reject the original invalid request.
+For malformed status/document reads with individually valid explicit locators, the hint can include
+a complete new `gate-check` read. This suggestion is length-bounded, excludes write/revision/document
+selectors and is validated again when called. It never fabricates the missing presentation ID.
+Read the returned catalog and exact document arguments; `authoring-inputs` is not a substitute for
+reading the selected prepared document. A wrong operation group gets a correction only when the
+operation kind has exactly one registered owner; ambiguous kinds require contract discovery.
+
 Dispatch follows the canonical skill-dispatch contract;
 inspect exposes read-only doctor, gate-check, delivery-map and contract operations.
 
+`agdf_inspect/project-state` observes the confirmed existing Git project's setup without a Run.
+Deliberate `agdf_project/project.initialize` uses the shared Core initializer and fixed versioned
+plan, preserving authored initialized governance. It creates no Run, approval, installation,
+permission or Git effect and exposes no force/repair/arbitrary writer. Original request recovery
+uses `operation-status` module `project.initialize/<original UUID>`, distinct from Run creation.
+Unknown/unowned partial states remain blocked. Successful setup returns creation help.
+
+`agdf_run/run.create` creates an unapproved Run from a semantic title and original operation UUID;
+pre-Run `operation-status` resolves a lost response without inventing a second Run.
+`authoring-inputs` returns versioned templates and exact sources with bounded cursors.
+`agdf_record/material.stage` transfers at most 16 KiB per part and 128 KiB per file, then seals
+Core-owned references for existing typed writers, including reviewed formal artefacts, unapproved
+UR replacement, Verified Change and closeout. Code edits, actual tests and Git execution remain
+external work; none of these operations grants approval.
+
+MCP `doctor` observes an exact selected Run without enumerating unrelated histories. All-active
+diagnosis returns bounded pages and an opaque observation cursor; consume every `next_cursor`.
+Only complete accounted observations have an overall domain status. Partial, stale, expired or
+resource-limited reads never imply a clean pass. Read failures report elapsed/unmeasured timing
+and read recovery separately from uncertain writes and their original operation receipts.
+
+Preparation opens no UI. `presentation.prepare` freezes one Markdown decision document;
+`presentation.deliver` chooses its primary delivery once. The ordinary route returns the whole
+Markdown. Optional `agdf_decision_view` opens a non-primary read-only preview. UI primary delivery
+requires actual bound current-surface confirmation and gives Chat only a short pointer; action
+qualification remains separate. The current SDK adapter cannot establish that surface identity,
+so capability/qualification alone always keeps Markdown as the primary route. Replay adds no
+second question; explicit fallback retires a primary view before returning the same Markdown.
+
 The shared Core continuation service may record one previously sealed relationship correction
 for an authorized bound `continue_delivery` request, then route the same run afresh. The routing
 service itself remains read-only. Accordingly, `agdf_dispatch` declares `readOnlyHint: false`;
@@ -70,12 +127,37 @@ MCP transaction retain separate results and recovery. A verified plugin is never
 because MCP setup fails. Marketplace-only installation has no CLI callback and therefore remains
 plugin-only.
 
-`agdf_dispatch` requires `presentation_language` as one well-formed BCP 47 tag. The host selects it
-from the latest natural-language request: an explicit response-language instruction wins, otherwise
-the dominant language is used, with `en` for mixed or ambiguous input. Missing or invalid input is
-rejected by the MCP schema before governance evaluation. A valid unsupported tag is accepted and
-renders through the complete English locale pack. The production tests exercise this contract
-separately for protocol versions `2025-11-25` and `2026-07-28`.
+The nine regular MCP tools may omit `presentation_language`; the adapter resolves a valid explicit
+request override, then the confirmed project's `.agdf/control/config.json`, then the versioned
+`plugins/agdf/meta/agdf-defaults.json`. Shipped preferences are `chat_language: en`,
+`artifact_language: en`, `presentation_route: markdown`, and `gate_check_variant: null`.
+The existing complete project configuration remains the only project override file. The last two
+settings are optional siblings of its language fields. Explicit invalid input and present invalid
+recognized settings are errors; defaults never activate or repair missing/incomplete control.
+
+Set an explicit BCP 47 language when the current request differs from the configured language.
+A valid unsupported presentation tag selects one complete English pack; malformed tags/resources
+fail. Presentation overrides never change artefact language or approved material. Existing setup
+locale selection and stored project values remain; normal calls and package generation write no config.
+The seven command groups also allow omitted `schema_version` and `assurance`; their fixed values
+come from the contracts, not configuration or independent human proof. `presentation.deliver` may
+omit route; only inspect `gate-check` may inherit the configured variant. UI/approval owners stay unchanged.
+
+`working_directory` may be omitted only with private trustworthy invocation context. Current native
+adapters have no evidenced task-directory source and return `working_directory_required` on omission;
+supply the absolute execution directory explicitly. Neither target nor plugin/process directory is a substitute.
+All target/Run/revision/operation/presentation/digest/reply bindings remain explicit. The SDK accepts
+the public omission schema; existing Core owners receive and validate the complete effective envelope.
+Existing explicit clients remain usable. Existing inspect/help reports expose effective values and sources
+without a mandatory extra lookup before each ordinary call.
+
+Existing family records retain original resolution in their versioned `resolved/1` extension. New readers
+validate its original family version and original logical/effective request digests. Unchanged complete-envelope
+digest and existing family recovery stay authoritative. A same-UUID retry restores original values after
+configuration changes; another logical request conflicts. Prepared language/material/identity remain immutable.
+Legacy records are read unchanged; old binaries can reject new record versions. No shadow ledger or automatic
+history/config migration is introduced. Repository/SDK, native CLI transport, installed plugin and human UI
+acceptance require separate evidence; a smaller definition or green build alone proves no task-efficiency gain.
 
 ### Selected Cockpit draft authoring check
 
@@ -134,3 +216,33 @@ This follows the [MCP tool error contract](https://modelcontextprotocol.io/speci
 and [SDK error behavior](https://ts.sdk.modelcontextprotocol.io/v2/servers/errors).
 Local protocol, package and browser tests do not establish native host or agent
 performance; the unchanged ergonomics comparison records that evidence separately.
+
+
+### Owned thread execution
+
+New packages declare `agdfExecutionModel: owner_threads_v1` and the exact owner-protocol
+import/export. The existing launcher and detached retention owner remain OS processes.
+That owner hosts one genuine SDK facade Worker and at most three counted generation
+Workers. Per-request Workers keep their existing execution and lock owners. Public
+STDIO uses native streams and backpressure; generation output cannot write MCP STDOUT.
+One entry-owned SDK output queue serializes actual writes, bounding queued frames/bytes
+without lowering existing per-result or UI resource limits. A blocked reader therefore
+does not create a parallel drain/error listener for every response.
+The private channel accepts bounded finite JSON with exact fields, a per-connection
+token/epoch, publication identity and original operation identity. It limits pending
+frames and bytes, and requalifies replacement candidates through the existing immutable
+publisher. Historical packages retain their declared process path and digest entry sets.
+
+Executable claims bind once to actual native Worker objects. Successful actual exit
+and a complete close acknowledgement are both required for release. Facade loss drains
+surviving work without replay; unconfirmed exits, uncertain effects and nested locks
+remain protected. Fatal failure of the shared owner process can lose all its Workers;
+original operation receipts and retained claims remain the recovery evidence. No PID
+scan, claim garbage collection or timeout alone establishes safe termination.
+
+Repository tests exercise both actual STDIO protocols, replacement, bounded channel
+admission and real write/lock interruption in disposable, fully rehashed fault candidates.
+They do not qualify an installed host or another OS. The fixed performance test selects
+the actual owned plugin launcher with 20/20 samples and p95 limits of 2500 ms cold /
+1000 ms warm. Performance acceptance and native qualification are separate
+required evidence, not consequences of the topology declaration.