create-agdf 0.20.2 → 0.31.0

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

@@ -1,139 +0,0 @@
-# AGDF Run State
-
-## Run Meta
-
-- run_id:
-- started_at:
-- mode: `quick_task | verified_change | structured_delivery`
-- current_gate: `none | UR | Brownfield Review | Mode/Slice Decision | PRD | SD | TP | Quick Task Execution | Verified Change Execution | Brownfield Analysis | CD+Tests | CR | QA | UAT | OR`
-- decision: `pass | revise | block | in_progress`
-- owner:
-
-## Objective
-
-What outcome is this run trying to make trustworthy?
-
-## 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? |  |
-
-## Source And Scope State
-
-- normative_instruction_source:
-- multi_scope_state: `clear | ambiguous | blocked`
-- active_scope_evidence:
-- competing_scope_lines:
-- branch_workspace_evidence:
-- branch_workspace_scope_effect: `supports | conflicts | insufficient | not_checked`
-
-## Run Status Card
-
-This is a compact projection of the control state. It does not replace gate-check, QA, OR or approvals.
-
-| Run status | Value |
-|---|---|
-| Status |  |
-| Current gate |  |
-| Allowed now |  |
-| Blocked by |  |
-| Missing approval |  |
-| Next step |  |
-| Quality outlook |  |
-
-## Approvals
-
-Valid approval format for new runs: `Approval: <GateName>`.
-
-| Gate | Status | Evidence |
-|---|---|---|
-| UR | `missing | approved | not_applicable` |  |
-| PRD | `missing | approved | not_applicable` |  |
-| SD | `missing | approved | not_applicable` |  |
-| TP | `missing | approved | not_applicable` |  |
-| QA | `missing | approved | not_applicable` |  |
-| UAT | `missing | approved | not_applicable` |  |
-
-## Artefacts
-
-| Type | Path | Status | Notes |
-|---|---|---|---|
-| UR |  | `draft | approved | superseded | not_applicable` |  |
-| PRD |  | `draft | approved | superseded | not_applicable` |  |
-| SD |  | `draft | approved | superseded | not_applicable` |  |
-| TP |  | `draft | approved | superseded | not_applicable` |  |
-| Brownfield Review |  | `missing | draft | done | not_applicable | superseded` |  |
-| Verified Change |  | `missing | draft | eligible | executed | escalated` |  |
-| Review |  | `missing | done | not_applicable` |  |
-| QA |  | `missing | pass | revise | block | not_applicable` |  |
-| OR |  | `missing | done | not_applicable` |  |
-
-## Mode / Slice Decision
-
-Set this after Brownfield Review. Do not assume the full gate chain before the existing-system impact is understood.
-Quick Task execution or implementation is not allowed until this decision is visible with scope reason and evidence.
-
-- decision: `undecided | quick_task | verified_change | structured_slice | structured_delivery | block`
-- required_next_gate: `none | PRD | SD | TP | Brownfield Analysis`
-- scope_reason:
-- evidence:
-- transparency_note:
-
-## Artefact Chain
-
-Keep the active work item traceable. A gate may open only when the previous gate has both exact approval and a durable or linked artefact.
-
-| From | Relationship | To | Evidence |
-|---|---|---|---|
-| UR | `approved_by` | `Approval: UR` |  |
-| PRD | `derived_from` | UR |  |
-| SD | `derived_from` | PRD |  |
-| TP | `derived_from` | SD |  |
-| QA_REPORT | `tests` | TP |  |
-
-## Evidence
-
-| Evidence | Source | Covers | Strength |
-|---|---|---|---|
-|  |  |  | `direct | indirect | weak` |
-
-## Missing Evidence
-
-| Missing evidence | Impact | Required next step |
-|---|---|---|
-|  | `warn | revise | block` |  |
-
-## Risks
-
-| Risk | Impact | Mitigation or owner |
-|---|---|---|
-|  | `warn | revise | block` |  |
-
-## Context Graph Impact
-
-- context_graph_impact: `none | link_only | update_existing_node | new_node_required | sot_drift`
-- context_graph_refs:
-- context_graph_reconciliation: `resolved | not_applicable | open_gap`
-- context_graph_required_action: `none | link | update | create | resolve_drift`
-- context_graph_gate_effect: `none | warning | revise | block`
-- context_graph_evidence:
-
-## Knowledge Persistence Decision
-
-- memory_target: `context_graph | sot_registry | scope_artifact | open_questions | none`
-- memory_reason:
-- memory_refs:
-
-## Closeout
-
-- delivered:
-- not_delivered:
-- verification_performed:
-- unverified:
-- next_allowed_action:
-- quality_outlook:

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

@@ -1,39 +0,0 @@
-# AGDF Master Backlog
-
-This file is the living control pointer for active AGDF delivery work. Detailed UR, Brownfield Review, PRD, SD, TP, QA and OR artefacts should live in stable paths and be linked from here.
-
-## Rules
-
-1. New product semantics, functional change or user-visible behaviour change starts as a new UR draft in a stable local artefact path, for example `.agdf/control/artefacts/<key>/UR.md`, unless an authoritative repository SoT already exists and is linked here.
-2. `Approval: UR` adds or updates exactly one steering row with a document-relative Markdown link to the UR.
-3. Brownfield Review is created for the same work item after UR approval when existing-system impact must be sized before PRD depth or Quick Task execution.
-4. PRD, SD, TP and QA report artefacts are created for the same work item after the previous gate is approved and persisted or linked.
-5. `Approval: PRD`, `Approval: SD`, `Approval: TP` and `Approval: QA` require the corresponding durable artefact or linked repository SoT before the next gate can open.
-6. Generic consent such as "ok", "go ahead", "do it", "continue", "leg los" or "approved" does not update a gate. Only `Approval: <GateName>` does.
-7. Keep only steering-relevant work in `Active Backlog`.
-8. Every active item has exactly one linked current spec and a visible linked artefact chain.
-9. Historical artefacts remain linkable but do not override the current pointer.
-10. If an item is superseded, mark the replacement.
-11. If active work grows beyond roughly ten items, triage the backlog.
-12. `Status` must be one of the human-readable labels normalized by `packages/core/lib/control-evaluation/shared.js`: Needs UR, Awaiting Brownfield Review, Awaiting PRD, Awaiting PRD Approval, Awaiting SD, Awaiting SD Approval, Awaiting TP, Awaiting TP Approval, In Progress, Blocked, Awaiting QA, Awaiting UAT, Awaiting OR, Completed, Superseded, Abandoned. Generated observations also use Work pending, Approval pending, QA report pending, QA evidence open, QA correction open, QA source decision required, QA blocked, Source unconfirmed, Closeout pending, Unconfirmed, and phase-specific Brownfield Analysis/CD+Tests/CR/Quick Task Execution/Verified Change Execution/Mode/Slice Decision work pending. The parser module is authoritative; this list only mirrors it for readability.
-13. `Artefacts` link labels must be one of the labels normalized by the same parser module: `ur`, `brownfield`, `prd`, `sd`, `tp`, `qa`, `or` (case-insensitive). Do not invent other labels such as a raw artefact filename.
-14. After writing or updating this file, run `doctor --json` (or the locally available equivalent) and resolve any `AGDF_BACKLOG_STATUS_UNKNOWN` or `AGDF_BACKLOG_ARTEFACT_LABEL_UNKNOWN` finding before treating the edit as done.
-15. A `Work item` cell may optionally start with a bracketed scope tag, one of `[framework-maintenance]` or `[external-delivery]`, so the split between AGDF's own maintenance work and external product delivery stays visible at a glance. The tag is never required retroactively on `Completed / Superseded Pointers` rows. `packages/core/lib/control-evaluation/shared.js` is authoritative for the accepted values.
-16. After writing or updating this file, also resolve any `AGDF_BACKLOG_SCOPE_LABEL_UNKNOWN` finding, which fires only for a present-but-unrecognized bracketed tag, never for an absent one.
-
-17. Core writers may place a bounded `agdf-backlog-summary-v1` comment after a complete table, separated by a blank line. It records the addressed row, target, actual Run revision, observation time and consumed source digests; it never authorizes. Preserve it with its row. Older rows remain readable without it. Invalid/foreign/ambiguous observations remain visibly unconfirmed; reading does not synchronize or scan all Runs.
-
-## Active Backlog
-
-| Priority | Key | Work item | Status | Artefacts | Current spec | Next step |
-|---:|---|---|---|---|---|---|
-
-## Planned / Parking Lot
-
-| Priority | Key | Work item | Status | Artefacts | Current spec | Next step |
-|---:|---|---|---|---|---|---|
-
-## Completed / Superseded Pointers
-
-| Key | Work item | Final status | Historical record | Outcome |
-|---|---|---|---|---|

package/generated/plugins/agdf/runtime/create-agdf/lib/control-maintenance/interaction.js

@@ -1,28 +0,0 @@
-import { createInterface } from "node:readline/promises";
-import process from "node:process";
-import { interactionLocales } from "#agdf-core/resources/context.js";
-import { selectControlMigration, selectControlRepair } from "#agdf-core/control-maintenance/interaction.js";
-export * from "#agdf-core/control-maintenance/interaction.js";
-export async function promptControlMigration(plan, {
-  input = process.stdin, output = process.stdout, registry = interactionLocales, language = "en",
-} = {}) {
-  const prompt = createInterface({ input, output });
-  try {
-    return await selectControlMigration(plan, { registry, language,
-      write(value) { output.write(`${value}\n`); },
-      readChoice({ prompt: question }) { return prompt.question(question); },
-    });
-  } finally { prompt.close(); }
-}
-
-export async function promptControlRepair(value, {
-  input = process.stdin, output = process.stdout, registry = interactionLocales, language = "en", phase = "offer",
-} = {}) {
-  const prompt = createInterface({ input, output });
-  try {
-    return await selectControlRepair(value, { registry, language, phase,
-      write(text) { output.write(`${text}\n`); },
-      readChoice({ prompt: question }) { return prompt.question(question); },
-    });
-  } finally { prompt.close(); }
-}

package/generated/plugins/agdf/runtime/create-agdf/lib/control-maintenance/repair.js

@@ -1,4 +0,0 @@
-import { inspectControlRepair as inspect, repairInstallationControl as repair } from "#agdf-core/control-maintenance/repair.js";
-import { readGitOriginals } from "../runtime/git-originals.js";
-export const inspectControlRepair = (root, options = {}) => inspect(root, { readGitOriginals, ...options });
-export const repairInstallationControl = (control, options = {}) => repair(control, { readGitOriginals, ...options });

package/generated/plugins/agdf/runtime/create-agdf/lib/control-maintenance/service.js

@@ -1,3 +0,0 @@
-import { runControlMaintenance as run } from "#agdf-core/control-maintenance/service.js";
-import { readGitOriginals } from "../runtime/git-originals.js";
-export const runControlMaintenance = (target, options = {}) => run(target, { readGitOriginals, ...options });

package/generated/plugins/agdf/runtime/create-agdf/lib/control-state/run-recovery.js

@@ -1,5 +0,0 @@
-import { inspectRunRecovery as inspect, previewRunRecovery as preview } from "#agdf-core/control-state/run-recovery.js";
-import { readGitHistory } from "../runtime/git-history.js";
-export { applyRunRecovery, inspectSelfReferenceRecovery } from "#agdf-core/control-state/run-recovery.js";
-export const inspectRunRecovery = (root, runId, options = {}) => inspect(root, runId, { readGitHistory, ...options });
-export const previewRunRecovery = (root, runId, options = {}) => preview(root, runId, { readGitHistory, ...options });

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-inspect/cockpit-backlog.js

@@ -1,135 +0,0 @@
-import { join } from 'node:path';
-import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from '../control-read/fs.js';
-import { markdownSection, parseBacklogSection, tableRows, cleanStatusCell, markdownLink, resolvedBacklogLinkTarget } from '../control-evaluation/shared.js';
-import { isSafeControlRelativePath } from '../control-state/contained-file.js';
-import { READ_LIMITS, fail } from '../control-read/snapshot.js';
-import { COCKPIT_BACKLOG_SECTIONS } from './cockpit-list.js';
-import { decodeBacklogMarker, savedBacklogSummary } from '../control-state/backlog-summary.js';
-
-const SOURCE = '.agdf/control/MASTER_BACKLOG.md';
-const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
-const headings = COCKPIT_BACKLOG_SECTIONS;
-const completedHeader = ['key', 'work item', 'status', 'record', 'outcome'];
-const canonicalCompletedHeader = ['key', 'work item', 'final status', 'historical record', 'outcome'];
-
-// A stored pointer projection. It never resolves Runs, evaluates gates or follows links.
-export function projectCockpitBacklog(root) {
-  const path = join(root, SOURCE);
-  if (!existsSync(path)) return { state: 'missing', code: 'backlog_missing', data: null };
-  const bytes = readFileSync(path);
-  if (bytes.length > READ_LIMITS.preview) fail('resource_limit');
-  let source;
-  try { source = decoder.decode(bytes); if (source.includes('\0')) throw Error(); }
-  catch { return { state: 'unsupported', code: 'backlog_unsupported', data: null }; }
-  const entries = [], diagnostics = [], counts = {};
-  const markers = source.split('\n').map(decodeBacklogMarker).filter(Boolean);
-  const diagnostic = (code, section, key = null) => diagnostics.push({ code, path: SOURCE, section, key });
-  for (const section of headings) {
-    const content = markdownSection(source, section), rows = tableRows(content);
-    if (!new RegExp(`^## ${section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm').test(source)) {
-      diagnostic('backlog_section_missing', section); counts[section] = 0; continue;
-    }
-    if (!rows.length) { diagnostic('backlog_layout_missing', section); counts[section] = 0; continue; }
-    const completed = section === headings[2];
-    const normalized = rows[0].map(cell => cell.toLowerCase().trim());
-    let pointers = [];
-    if (completed) {
-      if (![completedHeader.join('|'), canonicalCompletedHeader.join('|')].includes(normalized.join('|'))) {
-        diagnostic('backlog_layout_unsupported', section); counts[section] = 0; continue;
-      }
-    } else {
-      const findings = [];
-      pointers = parseBacklogSection(content, findings, SOURCE);
-      diagnostics.push(...findings.map(row => ({ ...row, section })));
-      if (findings.some(row => row.code === 'AGDF_BACKLOG_LAYOUT_UNKNOWN')) { counts[section] = 0; continue; }
-    }
-    const width = rows[0].length;
-    let pointerIndex = 0;
-    for (const cells of rows.slice(1).filter(row => row.some(Boolean))) {
-      const pointer = completed ? null : pointers[pointerIndex++];
-      const compact = width === 7;
-      const key = cleanStatusCell(cells[completed ? 0 : 1] ?? '');
-      const malformed = cells.length !== width || !key || !(cells[completed ? 1 : 2] ?? '').trim();
-      if (malformed) diagnostic('backlog_row_malformed', section, key);
-      const saved_summary = savedBacklogSummary(root, section, cells, markers);
-      if (saved_summary.code) diagnostic(saved_summary.code, section, key);
-      entries.push({ section, key, original_key: cells[completed ? 0 : 1] ?? '',
-        title: cells[completed ? 1 : 2] ?? '', stored_status: cells[completed ? 2 : 3] ?? '',
-        scope: pointer?.scope ?? '', priority: completed ? null : cells[0] ?? '',
-        stored_next_step: completed ? cells[4] ?? '' : cells[compact ? 6 : 12] ?? '',
-        source_links: completed ? cells[3] ?? '' : compact ? cells[4] ?? '' : cells.slice(4, 11).join(' · '),
-        current_spec: completed ? null : cells[compact ? 5 : 11] ?? '',
-        normalized_pointer: pointer, saved_summary,
-        selectable: !malformed && /^[A-Za-z0-9_-]{1,128}$/.test(key) });
-    }
-    counts[section] = entries.filter(row => row.section === section).length;
-  }
-  const seen = new Map();
-  for (const entry of entries) {
-    if (seen.has(entry.key)) {
-      diagnostic('backlog_key_duplicate', entry.section, entry.key);
-      entry.selectable = false; seen.get(entry.key).selectable = false;
-    } else seen.set(entry.key, entry);
-  }
-  return { state: diagnostics.length ? 'partial' : entries.length ? 'available' : 'empty',
-    code: diagnostics.length ? 'backlog_partial' : null,
-    data: { kind: 'backlog', entries, diagnostics, source_path: SOURCE,
-      content_digest: createHash('sha256').update(bytes).digest('hex'), counts } };
-}
-
-export function backlogUrSource(row) {
-  const paths = new Set();
-  for (const match of `${row.source_links} · ${row.current_spec ?? ''}`.matchAll(/\[UR\]\([^)]+\)/gi)) {
-    const link = markdownLink(match[0]);
-    const path = link && resolvedBacklogLinkTarget(link.target);
-    if (!path || /[%#?\0]/.test(link.target) || !isSafeControlRelativePath(path)
-      || !path.startsWith('.agdf/control/artefacts/') || !/\.md$/i.test(path)) return { path: null, code: 'resource_denied' };
-    paths.add(path);
-  }
-  return paths.size === 1 ? { path: [...paths][0], code: null }
-    : { path: null, code: paths.size ? 'ur_link_ambiguous' : 'ur_link_missing' };
-}
-
-// Passive Markdown heading extraction for list presentation only. No evaluator changes.
-export function backlogUrHeading(content) {
-  let fence = null, comment = false, front = false, previous = '';
-  const lines = content.replace(/^\uFEFF/, '').split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    let line = lines[i];
-    if (i === 0 && line.trim() === '---') { front = true; continue; }
-    if (front) { if (/^(---|\.\.\.)\s*$/.test(line)) front = false; continue; }
-    if (comment) { const end = line.indexOf('-->'); if (end < 0) continue; line = line.slice(end + 3); comment = false; }
-    const block = line.match(/^ {0,3}(`{3,}|~{3,})/);
-    if (fence) { if (new RegExp(`^ {0,3}${fence[0]}{${fence.length},}\\s*$`).test(line)) fence = null; continue; }
-    if (block) { fence = block[1]; previous = ''; continue; }
-    while (line.includes('<!--')) {
-      const start = line.indexOf('<!--'), end = line.indexOf('-->', start + 4);
-      if (end < 0) { line = line.slice(0, start); comment = true; previous = ''; break; }
-      line = line.slice(0, start) + line.slice(end + 3);
-    }
-    const atx = line.match(/^ {0,3}#(?:[ \t]+(.*)|$)/);
-    if (atx) return (atx[1] ?? '').replace(/[ \t]+#+[ \t]*$/, '').trim();
-    if (previous && /^ {0,3}=+\s*$/.test(line)) return previous;
-    const paragraph = line.trim() && !/^(?:\s{4}|\t)|^ {0,3}(?:[#>|]|[-+*]\s|\d+[.)]\s|[-*_]{3,}\s*$)/.test(line);
-    previous = paragraph ? (previous ? previous + '\n' : '') + line.trim() : '';
-  }
-  return '';
-}
-
-export function projectBacklogUrTitle(root, view, row, backlogDigest) {
-  const source = backlogUrSource(row);
-  const observation = { state: 'unavailable', code: source.code, path: source.path, heading: null, title: null,
-    content_digest: null, observed_as_of: view.observed_as_of, backlog_digest: backlogDigest };
-  if (!source.path) return observation;
-  const read = view.readOptionalFileSync(join(root, source.path), READ_LIMITS.preview);
-  if (read.code) return { ...observation, code: read.code };
-  let content;
-  try { content = decoder.decode(read.bytes); if (content.includes('\0')) throw Error(); }
-  catch { return { ...observation, code: 'document_unsupported' }; }
-  const heading = backlogUrHeading(content), title = heading.replace(/^UR:\s*/i, '').trim();
-  if (!title) return { ...observation, code: 'ur_heading_missing' };
-  if ([...heading].length > 512 || Buffer.byteLength(heading, 'utf8') > 2048) return { ...observation, code: 'resource_limit' };
-  return { ...observation, state: 'available', code: null, heading, title,
-    content_digest: createHash('sha256').update(read.bytes).digest('hex') };
-}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-maintenance/interaction.js

@@ -1,57 +0,0 @@
-import { interactionLocales } from "../resources/context.js";
-import { localePack } from "../interaction-presentation.js";
-import { renderMaintenanceOffer, renderControlMigrationDecision, renderControlRepairOffer, renderControlRepairPlan } from "./presentation.js";
-
-export async function selectControlMaintenance(control, {
-  readChoice, write = () => {}, registry = interactionLocales, language = "en",
-} = {}) {
-  if (typeof readChoice !== "function") throw new Error("AGDF_MAINTENANCE_INTERACTION_REQUIRED");
-  const copy = localePack(registry, language).repositoryMaintenance;
-  write(renderMaintenanceOffer(control, { registry, language }));
-  while (true) {
-    let raw;
-    try { raw = await readChoice({ prompt: copy.prompt, default: null }); } catch { return "skip"; }
-    const choice = typeof raw === "string" ? raw.trim().toLowerCase() : "";
-    if (!choice || ["2", "skip", "later"].includes(choice)) return "skip";
-    if (["1", "start"].includes(choice)) return "start";
-    if (["3", "d", "details"].includes(choice)) write(renderMaintenanceOffer(control, { registry, language, details: true }));
-    else write(copy.invalid);
-  }
-}
-
-export async function selectControlMigration(plan, {
-  readChoice, write = () => {}, registry = interactionLocales, language = "en",
-} = {}) {
-  if (typeof readChoice !== "function") throw new Error("AGDF_CONTROL_MIGRATION_READER_REQUIRED");
-  const copy = localePack(registry, language).installSetup.controlMigration;
-  write(renderControlMigrationDecision(plan, { registry, language }));
-  while (true) {
-    let value;
-    try { value = await readChoice({ prompt: copy.batchPrompt, default: null }); } catch { return "skip"; }
-    const choice = typeof value === "string" ? value.trim().toLowerCase() : "";
-    if (!choice || ["2", "skip", "later"].includes(choice)) return "skip";
-    if (["1", "migrate"].includes(choice)) return "migrate";
-    if (["3", "d", "details"].includes(choice)) write(renderControlMigrationDecision(plan, { registry, language, details: true }));
-    else write(copy.invalidChoice);
-  }
-}
-
-export async function selectControlRepair(value, {
-  readChoice, write = () => {}, registry = interactionLocales, language = "en", phase = "offer",
-} = {}) {
-  if (typeof readChoice !== "function") throw new Error("AGDF_CONTROL_REPAIR_READER_REQUIRED");
-  if (!["offer", "plan"].includes(phase)) throw new Error("AGDF_CONTROL_REPAIR_PHASE_INVALID");
-  const copy = localePack(registry, language).installSetup.controlRepair;
-  const render = phase === "offer" ? renderControlRepairOffer : renderControlRepairPlan;
-  write(render(value, { registry, language }));
-  while (true) {
-    let raw;
-    try { raw = await readChoice({ prompt: copy.prompt, default: null }); } catch { return "skip"; }
-    const choice = typeof raw === "string" ? raw.trim().toLowerCase() : "";
-    if (!choice || ["2", "skip", "later"].includes(choice)) return "skip";
-    if (choice === "1" && (phase === "offer" || value.items.some((item) => item.available))) return phase === "offer" ? "start" : "repair";
-    if (["3", "d", "details"].includes(choice)) write(render(value, { registry, language, details: true }));
-    else write(copy.invalidChoice);
-  }
-}
-

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-maintenance/migration.js

@@ -1,85 +0,0 @@
-import { join } from "node:path";
-import { regularFileSnapshot } from "../control-state/run-store-inspection.js";
-import { applyRunRecovery, inspectRunRecovery, previewRunRecovery } from "../control-state/run-recovery.js";
-import { inspectControlMigration, safeApprovalReset } from "./compatibility.js";
-
-export async function migrateInstallationControl(root, { mode = "inspect", confirmMigration } = {}) {
-  if (!["inspect", "safe"].includes(mode)) throw new Error("AGDF_CONTROL_MIGRATION_MODE_INVALID");
-  const before = inspectControlMigration(root);
-  if (mode === "inspect" || !root) return before;
-  const changes = [];
-  const errors = [];
-  // A structural inventory failure never authorizes a partial migration of an incomplete inventory.
-  if (before.diagnostics.some((finding) => finding.code !== "AGDF_LEGACY_MIGRATION_REQUIRED")) return before;
-  const candidates = before.runs.filter((entry) => entry.status === "migration_required" || entry.pending_recoveries?.length);
-  // Bind the single decision to read-only snapshots. Declining must not even create journals.
-  // The canonical recovery writer still checks each selected revision under its own lock.
-  let selected;
-  if (typeof confirmMigration === "function" && candidates.length) {
-    selected = new Map();
-    for (const run of candidates) {
-      try {
-        if (run.pending_recoveries?.length > 1) throw new Error("AGDF_RECOVERY_JOURNAL_CONFLICT");
-        const pending = run.pending_recoveries?.[0];
-        const journalContent = pending ? regularFileSnapshot(join(root, pending.journal)).content.toString("utf8") : null;
-        const journal = pending ? JSON.parse(journalContent) : null;
-        const inspection = pending ? null : inspectRunRecovery(root, run.run_id, { inspectHistory: false });
-        selected.set(run.run_id, {
-          run_id: run.run_id, pending, journalContent,
-          source_revision_id: journal?.source_revision_id ?? inspection.revision_id,
-          source_content_digest: journal?.source_content_digest ?? inspection.content_digest,
-          source_artefacts: journal?.source_artefacts ?? inspection.artefacts,
-          prior_approvals: journal?.prior_approvals ?? inspection.approvals,
-          next_gate: journal?.next_gate ?? inspection.next_gate_if_recovered,
-        });
-      } catch (error) { errors.push({ run_id: run.run_id, code: String(error.code ?? error.message) }); }
-    }
-    if (selected.size) {
-      const plan = { target: root, control: before, runs: [...selected.values()], diagnostics: errors,
-        approval_reset_count: [...selected.values()].filter((run) => !safeApprovalReset(run.prior_approvals)).length,
-        authorizes: false };
-      if (await confirmMigration(structuredClone(plan)) !== "migrate") return before;
-    }
-  }
-  for (const run of candidates) {
-    if (selected && !selected.has(run.run_id)) continue;
-    if (run.pending_recoveries?.length > 1) { errors.push({ run_id: run.run_id, code: "AGDF_RECOVERY_JOURNAL_CONFLICT" }); continue; }
-    if (run.pending_recoveries?.length) run.safe_to_migrate = safeApprovalReset(run.pending_recoveries[0].prior_approvals ?? []);
-    if (!selected && !run.safe_to_migrate) continue;
-    try {
-      const snapshot = selected?.get(run.run_id);
-      const pending = run.pending_recoveries?.[0];
-      if (snapshot) {
-        if (pending) {
-          if (regularFileSnapshot(join(root, pending.journal)).content.toString("utf8") !== snapshot.journalContent) {
-            throw new Error("AGDF_STALE_RUN_REVISION");
-          }
-        } else {
-          const current = inspectRunRecovery(root, run.run_id, { inspectHistory: false });
-          if (current.revision_id !== snapshot.source_revision_id || current.content_digest !== snapshot.source_content_digest
-              || JSON.stringify(current.artefacts) !== JSON.stringify(snapshot.source_artefacts)) throw new Error("AGDF_STALE_RUN_REVISION");
-        }
-      }
-      const preview = pending ?? previewRunRecovery(root, run.run_id);
-      if (snapshot && !pending && (preview.source_content_digest !== snapshot.source_content_digest
-          || JSON.stringify(preview.source_artefacts) !== JSON.stringify(snapshot.source_artefacts))) throw new Error("AGDF_STALE_RUN_REVISION");
-      // A concurrent approval change must never turn a safe migration into approval invalidation.
-      const journal = JSON.parse(regularFileSnapshot(join(root, preview.journal)).content.toString("utf8"));
-      const safe = safeApprovalReset(journal.prior_approvals);
-      const confirmation = selected || safe ? preview.confirmation : null;
-      if (confirmation !== preview.confirmation) continue;
-      const applied = applyRunRecovery(root, { runId: run.run_id, previewId: preview.preview_id, confirmation });
-      if (applied.seal_status !== "valid" && applied.outcome !== "already_recovered") throw new Error("AGDF_CONTROL_MIGRATION_VERIFICATION_FAILED");
-      changes.push({ run_id: run.run_id, outcome: applied.outcome, revision_id: applied.revision_id,
-        backup: preview.journal, next_gate: preview.next_gate });
-    } catch (error) {
-      errors.push({ run_id: run.run_id, code: String(error.code ?? error.message) });
-    }
-  }
-  const after = inspectControlMigration(root);
-  after.changes = changes;
-  after.diagnostics.push(...errors);
-  if (errors.length) after.status = "repair_required";
-  return after;
-}
-