create-agdf 0.20.2 → 0.31.0

package/generated/plugins/agdf/companion/run-state.mjs

@@ -0,0 +1,97 @@
+// Run view reader (SD SDD-010): obtains the Core run view through the plugin runtime's read-only
+// `run-view` command and maps it to the companion's runs. The companion derives no run semantics of
+// its own: status, gate path, missing approval, next step and figure come from the status card's
+// evaluator. Process access is injected by the host ({ run(argv, init) }, as `$.process` provides).
+
+export const RUN_VIEW_SCHEMA = 'run-view/1';
+export const RUN_VIEW_TIMEOUT_MS = 10_000;
+// Why a run-view read failed; each has a catalog text under `unreadable` (shown with the failure).
+export const READ_FAILURE_REASONS = Object.freeze(['timeout', 'unavailable', 'exit', 'malformed', 'source_changed']);
+// Store reasons of a read that may succeed on the next attempt (a write during the read, the read
+// budget); they keep the last good view, marked stale, like a failed read (CR delta review RV-1).
+export const TRANSIENT_STORE_REASONS = Object.freeze(['source_changed', 'timeout']);
+// The internal steps between an approved TP and QA, shown as the build phase in the gate bar.
+export const BUILD_GATES = Object.freeze(['Brownfield Analysis', 'CD+Tests', 'CR']);
+export const isStructured = route => route === 'structured_delivery' || route === 'structured_slice';
+const TEXT_LIMIT = 240;
+const clip = text => { const value = String(text ?? ''); return value.length > TEXT_LIMIT ? `${value.slice(0, TEXT_LIMIT - 1)}…` : value; };
+
+// The only command the companion runs: the read-only run view of one project root.
+export function runViewArgv({ pluginRoot, root, language, runIds = [] }) {
+  return ['node', `${pluginRoot}/runtime/agdf-local.js`, 'run-view', '--dir', root, '--json', '--language', language,
+    ...runIds.flatMap(runId => ['--run', runId])];
+}
+
+// One run-view entry as the companion's run.
+export function companionRun(entry) {
+  return Object.freeze({
+    id: entry.run_id,
+    lifecycle: entry.lifecycle,
+    evaluated: entry.evaluated === true,
+    gate: entry.current_gate ?? null,
+    route: entry.mode ?? null,
+    updatedAt: entry.last_activity ?? '',
+    missing: entry.missing_approval ?? 'none',
+    next: entry.next_step ?? '',
+    nextText: entry.next_step_text ?? '',
+    blockingText: entry.blocking_text ?? '',
+    path: Object.freeze((entry.path ?? []).map(({ gate, status }) => Object.freeze({ gate, status }))),
+    figure: entry.figure,
+    // Bound documents changed after recording (SDD-008), as the run view reports them.
+    drift: Object.freeze((entry.drift ?? []).map(item => Object.freeze({ ...item }))),
+    // The authored objective, never the status card's run title or a template text.
+    objective: clip(entry.objective ?? ''),
+  });
+}
+
+// stdout of the command as a snapshot: { status, root, runs, unreadable, diagnosis, readAt }.
+// status is ok, no_control, unavailable (store diagnosis with reason) or failed (no usable view).
+export function snapshotFromRunView(stdout, { now }) {
+  let view;
+  try { view = JSON.parse(stdout); } catch { return { status: 'failed', runs: [], unreadable: [], readAt: now, error: 'malformed' }; }
+  if (view?.schema_version !== RUN_VIEW_SCHEMA || !Array.isArray(view.runs) || !view.store) {
+    return { status: 'failed', runs: [], unreadable: [], readAt: now, error: 'malformed' };
+  }
+  if (view.store.status === 'unavailable' && TRANSIENT_STORE_REASONS.includes(view.store.reason)) {
+    return { status: 'failed', runs: [], unreadable: [], readAt: now, error: view.store.reason };
+  }
+  // A run read while its files changed (after the run view's bounded retries) makes the view incomplete;
+  // like a transient store failure it keeps the last good view instead of showing that run as blocked.
+  const changedRun = view.runs.find(run => TRANSIENT_STORE_REASONS.includes(run?.evaluation_error));
+  if (changedRun) return { status: 'failed', runs: [], unreadable: [], readAt: now, error: changedRun.evaluation_error };
+  const status = view.store.status === 'ok' ? 'ok' : view.store.status === 'no_control' ? 'no_control' : 'unavailable';
+  return {
+    status,
+    root: view.root,
+    reason: view.store.reason ?? null,
+    // The run folders of an unsupported store, which the run view counts without reading them (AC-002).
+    runFolders: Number.isSafeInteger(view.store.run_folders) && view.store.run_folders > 0 ? view.store.run_folders : null,
+    runs: view.runs.filter(entry => entry.valid !== false && entry.listed !== false).map(companionRun),
+    unreadable: (view.diagnosis?.unreadable ?? []).map(({ run_id, reason }) => ({ id: run_id, reason })),
+    diagnosis: view.diagnosis ?? null,
+    readAt: now,
+  };
+}
+
+// Runs the command through the host and never throws: a process failure, a timeout or malformed
+// output is a failed snapshot with its cause, which the adapter settles as stale.
+export async function readSnapshot(processes, { pluginRoot, root, language, runIds = [], now, clock = () => Date.now() }) {
+  let ran;
+  const started = await clock();
+  try {
+    ran = await processes.run(runViewArgv({ pluginRoot, root, language, runIds }), { timeoutMs: RUN_VIEW_TIMEOUT_MS });
+  } catch {
+    // `$.process.run` rejects when the command cannot start or is still running at the timeout; its
+    // message format is not specified, so the elapsed time tells the two apart (CR finding CIR-06).
+    const elapsed = (await clock()) - started;
+    return { status: 'failed', runs: [], unreadable: [], readAt: now, error: elapsed >= RUN_VIEW_TIMEOUT_MS ? 'timeout' : 'unavailable' };
+  }
+  if (ran.exitCode !== 0 && ran.exitCode !== 2) return { status: 'failed', runs: [], unreadable: [], readAt: now, error: 'exit' };
+  return snapshotFromRunView(ran.stdout, { now });
+}
+
+// A transient failure keeps the last good snapshot, marked stale with the failed read time (AC-006).
+export function settleSnapshot(previous, next) {
+  if (next.status !== 'failed' || !previous || previous.status === 'failed') return next;
+  return { ...previous, stale: { failedAt: next.readAt, error: next.error } };
+}

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

@@ -0,0 +1,22 @@
+// Figure state of a run (SD SDD-004): the Core run view carries the derived mood and reason, so the
+// companion only overlays its own turn activity. It derives no run semantics itself.
+
+export const MOODS = Object.freeze(['laeuft', 'baut', 'wartet', 'blockiert', 'fertig', 'bereit']);
+
+// { mood, reason: { key, gate?, decision?, reason? } } as the run view derived it.
+export function runState(run) {
+  return run?.figure ?? { mood: 'bereit', reason: { key: 'idle' } };
+}
+
+// Moods a main-loop turn does not cover: a run being built stays baut, and a run waiting for an
+// approval or a decision stays wartet, since the chat usually asks for it during that turn (chat-run
+// navigation SDD-07). A blocked run shows läuft, since the chat usually resolves it.
+const THROUGH_TURN = new Set(['baut', 'wartet']);
+
+// A main-loop turn in progress shows läuft for every other mood; the run-derived state returns after
+// the turn.
+export function displayState(run, { isTurnActive = false } = {}) {
+  const derived = runState(run);
+  if (isTurnActive && !THROUGH_TURN.has(derived.mood)) return { mood: 'laeuft', reason: { key: 'turnActive' } };
+  return derived;
+}

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

@@ -0,0 +1,129 @@
+// 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 } from './localization.mjs';
+import { displayState } from './state.mjs';
+import { READ_FAILURE_REASONS } from './run-state.mjs';
+import { eventText, latestReview, PANE_EVENTS, shortDigest } from './events.mjs';
+
+const two = value => String(value).padStart(2, '0');
+// Preview lines the terminal text shows beneath the material line.
+export const TERMINAL_PREVIEW_LINES = 3;
+// 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, events, eventsAvailable }. Display only: the adapter persists
+// selection changes. `events` are this root's journal events since the last main-loop turn, newest first.
+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: 'bereit', stateLabel: t('states.bereit'),
+    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: [] };
+  // Event lines name only runs other than the shown one (owner request of 2026-11-06, T-013).
+  const events = shownRunId => eventFields(input, t, { shownRunId, runs: snapshot?.runs ?? [] });
+  const neutral = (message, extra = {}) => ({ ...base, ...events(null), 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') {
+    const reason = READ_FAILURE_REASONS.includes(snapshot.error) ? snapshot.error : 'unavailable';
+    return neutral(t('messages.runViewUnavailable', { reason: t(`unreadable.${reason}`) }));
+  }
+  if (snapshot.status === 'unavailable') {
+    // An unsupported store names how many run folders it holds and why none is readable (AC-002).
+    const reason = snapshot.reason ?? 'read_failed';
+    return snapshot.runFolders
+      ? neutral(t('messages.unreadableRuns', { count: snapshot.runFolders, reasons: t(`unreadable.${reason}`) }))
+      : unreadable(reason);
+  }
+  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) });
+  // Unreadable runs stay visible as a count with their reasons beside the readable ones (AC-002, AC-003).
+  const reasons = [...new Set(snapshot.unreadable.map(item => t(`unreadable.${item.reason}`)))].join(', ');
+  const unreadableHint = snapshot.unreadable.length ? t('messages.unreadableRuns', { count: snapshot.unreadable.length, reasons }) : null;
+  // 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, unreadableHint };
+    if (!open.length) return neutral(unreadableHint ?? t('messages.noOpenRuns'));
+    return neutral(t('messages.noRunAssigned'), { hint: t('messages.noRunAssignedHint'), openRuns, chatRunId, unreadableHint,
+      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 });
+  const reasonParams = { gate: gateTitle(registry, locale, state.reason.gate), decision: run.blockingText || state.reason.decision,
+    reason: state.reason.reason ? t(`unreadable.${state.reason.reason}`) : '' };
+  return {
+    ...base,
+    ...events(run.id),
+    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 : run.nextText || null,
+    unreadableHint,
+    origin: t(`origin.${origin}`),
+    originKind: origin,
+    chatRunId,
+    openRuns,
+    openCount,
+    drift: run.drift?.length ? run.drift.map(item => t('messages.drift', { document: item.document,
+      recorded: shortDigest(item.recorded_digest), current: shortDigest(item.current_digest) })) : null,
+  };
+}
+
+// Pane entries of the journal (decision P1) and the review facts of the newest staging or recording
+// (decision P2); without a readable journal the pane says so and invents nothing. `naming` is
+// { shownRunId, runs }: the shown run's events name no run.
+function eventFields(input, t, naming) {
+  const events = (input.events ?? []).slice(0, PANE_EVENTS);
+  const gate = value => gateTitle(input.registry, input.locale, value);
+  return {
+    events: events.length ? events.map(event => `${clockText(Date.parse(event.at))} ${eventText(event, t, { gateTitle: gate, ...naming })}`) : null,
+    review: latestReview(events, t),
+    eventsHint: input.eventsAvailable === false ? t('messages.eventsUnavailable') : null,
+  };
+}
+
+// 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.unreadableHint && view.unreadableHint !== view.message) lines.push(view.unreadableHint);
+  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}`);
+  for (const warning of view.drift ?? []) lines.push(warning);
+  if (view.events) lines.push(`${t('fields.events')}:`, ...view.events);
+  if (view.review) {
+    lines.push(`${t('fields.material')}: ${view.review.summary} · ${view.review.match}${view.review.truncated ? ` · ${view.review.truncated}` : ''}`);
+    // The terminal shows the start of the preview too (PRD M1, AC-007; CR finding B10).
+    if (view.review.preview) lines.push(...view.review.preview.split('\n').slice(0, TERMINAL_PREVIEW_LINES).map(line => `  ${line}`));
+  }
+  if (view.eventsHint) lines.push(view.eventsHint);
+  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,51 @@
 # AGDF Control Scaffold
 
-AGDF is primarily a control system for AI-assisted delivery. The skills guide the agent during a run; these files make the run state durable in a repository.
+Explicit initialization creates `control_layout: "run-folders-v1"`. This is the only supported layout; Runs use control-state version 4. Missing, old or unknown layouts and Run versions are unsupported. Inspection preserves their bytes and reports the incompatibility. There is no migration, conversion, legacy projection, automatic reset or fallback.
 
-Use this scaffold when a target repository should keep AGDF state outside chat history and tool memory.
-
-## Files
-
-| File | Purpose |
-|---|---|
-| `config.json` | Project language preference for generated AGDF artefacts and user-facing chat |
-| `templates/RUN_STATE.md` | Canonical version-2 template for isolated per-run state |
-| `templates/AGDF_RUN.md` | Legacy migration-input and compatibility-projection template |
-| `templates/MASTER_BACKLOG.md` | Template for the living backlog pointer: active initiatives and current UR/Brownfield/PRD/SD/TP/QA/OR artefacts |
-| `templates/artefacts/UR.md` | Template for the durable user requirement artefact of a work item |
-| `templates/artefacts/BROWNFIELD_REVIEW.md` | Template for the durable Brownfield Review and Mode/Slice Decision |
-| `templates/artefacts/VERIFIED_CHANGE.md` | Compact fail-closed record for an eligible Verified Change |
-| `templates/artefacts/PRD.md` | Template for the durable product requirements artefact |
-| `templates/artefacts/SD.md` | Template for the durable solution design artefact |
-| `templates/artefacts/TP.md` | Template for the durable task and test plan artefact |
-| `templates/artefacts/QA_REPORT.md` | Template for the durable QA decision report |
-| `templates/artefacts/OR.md` | Template for the durable Orchestration Report closeout |
-| `templates/SOT_REGISTRY.md` | Template for the source-of-truth registry: one primary owner per domain |
-| `templates/CONTEXT_GRAPH.md` | Template for project memory: durable decisions, Brownfield findings, risks, evidence and exit criteria |
-| `templates/AGENT_QUALITY_CONTRACTS.json` | Template for machine-readable warning, revise and block contracts for review and QA |
-
-## Recommended Target Layout
+## Current layout
 
 ```text
-.agdf/
-  control/
-    runs/
-      <run_id>/
-        RUN_STATE.md
-    config.json
-    AGDF_RUN.md
-    MASTER_BACKLOG.md
-    artefacts/
-      <work-item>/
-        UR.md
-        BROWNFIELD_REVIEW.md
-        PRD.md
-        SD.md
-        TP.md
-        QA_REPORT.md
-        OR.md
-    SOT_REGISTRY.md
-    CONTEXT_GRAPH.md
-    AGENT_QUALITY_CONTRACTS.json
+.agdf/control/
+  config.json
+  README.md
+  SOT_REGISTRY.md
+  CONTEXT_GRAPH.md
+  AGENT_QUALITY_CONTRACTS.json
+  BRAND.md
+  templates/
+  planned/<plan_id>/UR.md
+  runs/<run_id>/
+    RUN_STATE.md
+    documents/                 UR, analyses, PRD, SD, TP, reviews, QA_REPORT, OR
+    evidence/                  bounded supporting evidence
+    control/
+      presentations/           exact decision documents and optional preview snapshots
+      RUN_STEP_PENDING.json    original operation intent, only while pending
+    history/
+      planning/UR.md           immutable handed-off planning source
+      revisions/<operation_id>/manifest.json
+      revisions/<operation_id>/files/
 ```
 
-Keep these files small and reviewable. They are control artefacts, not a second documentation site.
-
-Create the live files with:
-
-```bash
-npx --yes @agdf/cli@latest init
-```
+Configuration, templates and curated project context stay project-wide. A multi-Run closure preview is a target-wide decision proposal under `closure-previews/`; it changes no Run until deliberately applied. Run-owned outputs never use a separate top-level artefacts directory.
 
-If only the project language preference is missing or should change after plugin installation, write just the config file:
+`BRAND.md` starts as a neutral English worksheet. Complete it with the project's
+own design intent and declare the finished source in `SOT_REGISTRY.md` when it is
+authoritative for design work.
 
-```bash
-npx --yes @agdf/cli@latest config --language en
-```
+`RUN_STATE.md` keeps identity, objective, mode and typed decisions, source bindings and operations. Approval status, current gate, current document references, relationship chains, evidence summaries and inventory are derived when read. They are not separately writable tables or a second state file. A binding embeds its reviewer attestation; no separate RECORD/REVIEW JSON repeats its mapping. A planned handoff records its source in the creation receipt and immutable planning snapshot, without an origin JSON copy.
 
-Then check whether the live state is actionable:
+Create a fresh scaffold in an explicitly confirmed existing Git repository:
 
-```bash
-agdf doctor
-agdf doctor --json
-agdf gate-check --json
+```sh
+create-agdf init --dir /absolute/project --language en
+create-agdf doctor --dir /absolute/project --json
 ```
 
-`doctor` does not replace agent judgment. It catches basic control failures: missing live files, missing current gate, missing next allowed action, empty evidence, empty backlog pointer, empty source-of-truth registry, duplicate active SoT rows and invalid quality contracts.
-`gate-check` consumes the doctor result and live run state to report whether the next process step is `open` or `blocked`.
-
-## Operating Rules
-
-- Canonical mutable state is isolated per run at `runs/<run_id>/RUN_STATE.md`. Run discovery is
-  derived; do not maintain a writable active-run index. When several runs are active, discovery
-  presents the most recently updated run first and lists the others, but requires an explicit run
-  selection for read-only status or explicit run-selection requests. Implementation intake first
-  provides canonical UR evidence to the coding agent for scope assignment, even with one active
-  run: resume one same-scope continuation, start a new UR run for an independent scope, or clarify
-  genuinely overlapping work. If no active run exists during a status request, ask whether to start
-  one or do something else. Status never creates a run. `updated_at` is recorded with
-  every canonical run write; older runs use file modification time until their next recorded update.
-- Migrate legacy state explicitly with `run-migrate`; read-only commands never migrate. A retained
-  `AGDF_RUN.md` is migration input or a non-authoritative projection, not a second writable owner.
-- A run created by `run-create` is sealed. Record every change to it or to a listed artefact with
-  `run-update`, and record exact gate replies only with `run-approve`; an unrecorded edit blocks
-  `doctor` and `gate-check` until it is recorded.
-  If a run lists its own `RUN_STATE.md`, the seal covers its body directly and uses a self-reference
-  marker for that artefact entry. This avoids circular on-disk hashing; references to other runs
-  remain fully hashed. Old self-reference failures require a verified restoration, never a blind re-seal.
-- Record the standard small-path steps with one `run-step` call each instead of editing the run state
-  and `MASTER_BACKLOG.md` by hand: `--step ur --title` after writing `artefacts/<run_id>/UR.md`;
-  `--step route --route <mode> --reason --evidence` after writing `BROWNFIELD_REVIEW.md`;
-  `--step evidence` for test or check results; `--step review --decision --evidence` for Code Review;
-  and `--step closeout --result --evidence --risk --next` to close a `quick_task` with OR-lite. Each
-  call maintains the tables, the backlog pointer and the next allowed action and prints the next step.
-
-- The selected `runs/<run_id>/RUN_STATE.md` is the current run dashboard.
-- `config.json` stores the project preference for artefact and chat language; runtime rules stay English.
-- `MASTER_BACKLOG.md` points to active delivery work; detailed artefacts live beside the work item.
-- Brownfield Review records the post-UR Mode/Slice Decision before PRD depth, Verified Change execution or Quick Task execution is chosen.
-- UR, PRD, SD, TP and QA decisions require durable artefacts or links to the authoritative repository source of truth before the next gate can open.
-- OR records the run closeout and next permissible step; it does not approve later gates.
-- `SOT_REGISTRY.md` decides which document owns which domain.
-- `CONTEXT_GRAPH.md` records durable project knowledge only when it has evidence and an exit criterion.
-- `AGENT_QUALITY_CONTRACTS.json` names reusable block, revise and warning conditions.
-- Never assign `merge=union` to canonical `runs/<run_id>/RUN_STATE.md` records. Concurrent edits to the
-  same run must remain conflict-visible; independent runs naturally change different files. After a
-  merge or pull, rerun `doctor` and `gate-check` for the selected run.
+Initialization creates no Run or approval. `config` changes preferences through the existing configuration owner; it does not convert a store. Use current `run-create`, `run-step`, `run-present`, `run-approve`, `run-revise` and `run-close`, or their fixed MCP control groups. Read `operation-contract` for complete current inputs. Every mutation retains its original operation UUID and exact binding for replay; a successful historical receipt is not permission for a new effect.
 
-Do not duplicate full product documentation in this scaffold. Link to the authoritative artefact instead.
+Material staging is private and temporary. Record documents through the owning command, which publishes the file and canonical record together. Never edit a bound document or Run by hand and then reseal it. An allowed unapproved draft replacement needs current reviewed material and a fresh presentation. Approved source changes require the current source-revision preview and exact deliberate confirmation.
 
-## Planned outputs during recovery
+`doctor` and `gate-check` inspect integrity and current prerequisites; they do not create approvals. A prepared presentation binds exact reviewed material. Only a new deliberate reply to that presentation records a gate decision. The local cooperative seal detects unrecorded changes; it is not an independent signature or proof of human identity.
 
-A missing file explicitly declared `missing` or `pending` under the selected run's own
-`.agdf/control/artefacts/<run_id>/` directory is a planned output, not lost completed evidence.
-Recovery retains its path and absence in the integrity snapshot and leaves its status pending.
-It does not create evidence or approve a gate. Completed or ready evidence, unsafe paths and
-descriptive placeholders still require repair. Creating a planned file after a recovery preview
-invalidates that preview; creating it after recovery changes the seal until a canonical update.
+Planned needs are independent URs. The optional planning extension can author them; Core owns their admission, current inventory and explicit handoff. Planning neither starts a Run nor approves a gate. See [planned URs](planned-urs.md).

package/generated/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/BRAND.md

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