create-agdf 0.20.1 → 0.30.0

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;
-}
-

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

@@ -1,226 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { lstatSync, mkdirSync, unlinkSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { isSafeControlRelativePath } from "../control-state/contained-file.js";
-import { directoryIdentity, regularFileSnapshot } from "../control-state/run-store-inspection.js";
-import { parseRunState } from "../control-state/run-state-parser.js";
-import { approvalSeal, artefactFileDigest, canonicalRunText, listedArtefactPaths, runSealState } from "../control-state/run-seal.js";
-import { inspectSelfReferenceRecovery } from "../control-state/run-recovery.js";
-import { atomicWrite, unapproveRecoveryApprovals, withRunLock, writeRunLocked, writeRunRecoveryLocked } from "../control-state/run-state-writer.js";
-import { inspectControlMigration } from "./compatibility.js";
-
-const digest = (content) => `sha256:${createHash("sha256").update(content).digest("hex")}`;
-const textDigest = (content) => digest(canonicalRunText(content));
-const pathError = (path) => Object.assign(new Error("AGDF_REPAIR_PATH_INVALID"), { code: "AGDF_REPAIR_PATH_INVALID", path });
-
-function checkedPath(root, relative, { createParents = false } = {}) {
-  if (!isSafeControlRelativePath(relative)) throw pathError(relative);
-  try { directoryIdentity(root); } catch { throw pathError(relative); }
-  let cursor = root;
-  const segments = relative.split("/");
-  for (const segment of segments.slice(0, -1)) {
-    cursor = join(cursor, segment);
-    try { directoryIdentity(cursor); } catch (error) {
-      if (error.code !== "ENOENT") throw pathError(relative);
-      if (!createParents) return null;
-      mkdirSync(cursor, { mode: 0o700 });
-      directoryIdentity(cursor);
-    }
-  }
-  const path = join(root, relative);
-  try {
-    const stat = lstatSync(path);
-    if (stat.isSymbolicLink() || !stat.isFile()) throw pathError(relative);
-  } catch (error) { if (error.code !== "ENOENT") throw error; }
-  return path;
-}
-
-function gitOriginals(root, path, readGitOriginals) {
-  if (!isSafeControlRelativePath(path) || typeof readGitOriginals !== "function") return [];
-  try {
-    const entries = readGitOriginals(root, path);
-    if (!Array.isArray(entries) || entries.length > 9) return [];
-    return entries.filter(entry => entry?.path === path && isSafeControlRelativePath(entry.git_path)
-      && entry.source === "git" && /^[0-9a-f]{40,64}$/u.test(entry.commit)
-      && typeof entry.bytes === "string" && entry.bytes.length <= 3 * 1024 * 1024
-      && entry.digest === textDigest(Buffer.from(entry.bytes, "base64").toString("utf8")));
-  } catch { return []; }
-}
-
-function proposal(root, item, fields) {
-  const proposed = { ...item, ...fields };
-  proposed.artefacts = [...new Set([...item.artefacts.map((artifact) => artifact.path), ...listedArtefactPaths(proposed.candidate_content)])]
-    .map((path) => { checkedPath(root, path); return { path, digest: artefactFileDigest(root, path) }; });
-  return proposed;
-}
-
-function inspectRunRepair(root, run, readGitOriginals) {
-  const relative = `.agdf/control/runs/${run.run_id}/RUN_STATE.md`;
-  const path = checkedPath(root, relative);
-  const content = regularFileSnapshot(path).content.toString("utf8");
-  const parsed = parseRunState(content, run.run_id);
-  const item = { run_id: run.run_id, kind: "manual", available: false, required: [], sources: [],
-    source_content: content, source_digest: digest(content), source_revision_id: parsed.meta.revision_id,
-    candidate_content: null, files: [], artefacts: listedArtefactPaths(content).map((path) => {
-      checkedPath(root, path);
-      return { path, digest: artefactFileDigest(root, path) };
-    }) };
-  if (!parsed.valid || parsed.meta.lifecycle !== "active" || run.pending_recoveries?.length) {
-    item.required = run.diagnostics.length ? run.diagnostics : [{ code: "AGDF_REPAIR_MANUAL_REQUIRED", path: relative }];
-    return item;
-  }
-  const seal = runSealState(root, content);
-  const checkpoint = inspectSelfReferenceRecovery(root, run.run_id);
-  if (checkpoint) {
-    return proposal(root, item, { kind: "self_reference", available: true, candidate_content: checkpoint.content,
-      sources: [{ path: relative, source: "recovery_journal", journal: checkpoint.source }] });
-  }
-  if (seal.status === "content_changed") {
-    const original = gitOriginals(root, relative, readGitOriginals).find((candidate) => {
-      const text = Buffer.from(candidate.bytes, "base64").toString("utf8");
-      const state = parseRunState(text, run.run_id);
-      return state.valid && state.meta.lifecycle === "active" && state.meta.revision_id === parsed.meta.revision_id
-        && runSealState(root, text).status === "valid" && runSealState(root, text).recorded.content_seal === seal.recorded.content_seal && approvalSeal(text) === seal.recorded.approval_seal
-        && listedArtefactPaths(text).every((path) => artefactFileDigest(root, path).startsWith("sha256:"));
-    });
-    if (original) return proposal(root, item, { kind: "run_snapshot", available: true,
-      candidate_content: Buffer.from(original.bytes, "base64").toString("utf8"), sources: [original] });
-  }
-  if (seal.status === "unsealed") {
-    for (const artifact of listedArtefactPaths(content)) {
-      const target = checkedPath(root, artifact);
-      const status = artefactFileDigest(root, artifact);
-      if (!["missing", "unresolved"].includes(status)) continue;
-      // A descriptive placeholder is not a filename; repair never invents paths or evidence.
-      if (!artifact.startsWith(`.agdf/control/artefacts/${run.run_id}/`) || !isSafeControlRelativePath(artifact)) {
-        item.required.push({ code: "AGDF_REPAIR_REFERENCE_REQUIRED", path: artifact });
-        continue;
-      }
-      if (target) {
-        try { lstatSync(target); item.required.push({ code: "AGDF_REPAIR_MANUAL_REQUIRED", path: artifact }); continue; }
-        catch (error) { if (error.code !== "ENOENT") throw error; }
-      }
-      const original = gitOriginals(root, artifact, readGitOriginals)[0];
-      if (original) { item.files.push(original); item.sources.push(original); }
-      else item.required.push({ code: "AGDF_REPAIR_ORIGINAL_REQUIRED", path: artifact });
-    }
-    if (item.files.length && !item.required.length) {
-      item.kind = "missing_artefacts";
-      item.available = true;
-      item.candidate_content = unapproveRecoveryApprovals(content);
-      item.approval_reset = true;
-      return proposal(root, item, {});
-    }
-  }
-  if (!item.required.length) item.required = run.diagnostics.length ? run.diagnostics : [{ code: "AGDF_REPAIR_MANUAL_REQUIRED", path: relative }];
-  return item;
-}
-
-export function inspectControlRepair(root, { readGitOriginals } = {}) {
-  const control = inspectControlMigration(root);
-  const items = [];
-  const diagnostics = [...control.diagnostics];
-  // An incomplete inventory or unsafe scaffold cannot authorize repair writes.
-  if (!diagnostics.length) for (const run of control.runs.filter((entry) => entry.status === "repair_required")) {
-    try { items.push(inspectRunRepair(root, run, readGitOriginals)); } catch (error) {
-      items.push({ run_id: run.run_id, kind: "manual", available: false, files: [], sources: [],
-        required: [{ code: String(error.code ?? error.message), ...(error.path ? { path: error.path } : {}) }] });
-    }
-  }
-  return { target: root, control, items, diagnostics, authorizes: false };
-}
-
-function publicRepair(plan, status) {
-  return { status, target: plan.target, authorizes: false, diagnostics: plan.diagnostics,
-    items: plan.items.map(({ run_id, kind, available, required, sources, outcome, backup }) => ({
-      run_id, kind, available, required,
-      sources: sources.map(({ bytes, ...source }) => source), ...(outcome ? { outcome, backup } : {}),
-    })) };
-}
-
-function applyRunRepair(root, item, hooks = {}, readGitOriginals) {
-  const relative = `.agdf/control/runs/${item.run_id}/RUN_STATE.md`;
-  const path = checkedPath(root, relative);
-  return withRunLock(path, () => {
-    if (regularFileSnapshot(path).content.toString("utf8") !== item.source_content) throw new Error("AGDF_STALE_RUN_REVISION");
-    // Re-read the selected source under the lock; callback mutation and source changes cannot
-    // replace the displayed restoration with another snapshot or a newly found original.
-    const run = inspectControlMigration(root).runs.find((entry) => entry.run_id === item.run_id);
-    if (!run || run.status !== "repair_required") throw new Error("AGDF_STALE_RUN_REVISION");
-    const current = inspectRunRepair(root, run, readGitOriginals);
-    if (JSON.stringify(current) !== JSON.stringify(item)) throw new Error("AGDF_STALE_RUN_REVISION");
-    const directory = join(dirname(path), "repair-previews");
-    try { mkdirSync(directory, { mode: 0o700 }); } catch (error) { if (error.code !== "EEXIST") throw error; }
-    directoryIdentity(directory);
-    if (process.platform !== "win32" && (lstatSync(directory).mode & 0o077)) throw new Error("AGDF_RECOVERY_JOURNAL_PERMISSIONS_INVALID");
-    const id = randomUUID();
-    const journalPath = join(directory, `${id}.json`);
-    const updatedAt = new Date().toISOString();
-    const nextRevisionId = randomUUID();
-    const journal = { schema_version: 1, phase: "prepared", created_at: updatedAt, run_id: item.run_id,
-      source_content: item.source_content, source_digest: item.source_digest, sources: item.sources,
-      files: item.files, candidate_content: item.candidate_content, next_revision_id: nextRevisionId };
-    atomicWrite(journalPath, `${JSON.stringify(journal, null, 2)}\n`);
-    const restored = [];
-    try {
-      for (const file of item.files) {
-        const target = checkedPath(root, file.path, { createParents: true });
-        try { lstatSync(target); throw new Error("AGDF_STALE_RUN_REVISION"); }
-        catch (error) { if (error.code !== "ENOENT") throw error; }
-        atomicWrite(target, Buffer.from(file.bytes, "base64"));
-        restored.push({ ...file, snapshot: regularFileSnapshot(target) });
-      }
-      hooks.beforeRunWrite?.();
-      const options = { expectedContent: item.source_content, expectedRevisionId: item.source_revision_id,
-        nextRevisionId, updatedAt, validateBeforeWrite: () => {
-          checkedPath(root, relative);
-          for (const artifact of item.artefacts) {
-            checkedPath(root, artifact.path);
-            const expected = item.files.find((file) => file.path === artifact.path)?.digest ?? artifact.digest;
-            if (artefactFileDigest(root, artifact.path) !== expected) throw new Error("AGDF_STALE_RUN_REVISION");
-          }
-        } };
-      if (item.kind === "missing_artefacts") writeRunRecoveryLocked(path, item.candidate_content, options);
-      else writeRunLocked(path, item.candidate_content, item.source_revision_id, { ...options, allowContentChange: true });
-      hooks.afterRunWrite?.();
-      const result = regularFileSnapshot(path).content.toString("utf8");
-      if (runSealState(root, result).status !== "valid") throw new Error("AGDF_CONTROL_REPAIR_VERIFICATION_FAILED");
-      atomicWrite(journalPath, `${JSON.stringify({ ...journal, phase: "committed", result_digest: digest(result) }, null, 2)}\n`);
-      return { outcome: "repaired", backup: journalPath.slice(root.length + 1) };
-    } catch (error) {
-      // Roll back only files we created and still own, only while the run was not replaced.
-      // A post-rename interruption retains the complete original snapshot and avoids a second write.
-      if (regularFileSnapshot(path).content.toString("utf8") === item.source_content) for (const file of restored) {
-        const target = checkedPath(root, file.path);
-        if (target) {
-          const current = regularFileSnapshot(target);
-          if (current.dev === file.snapshot.dev && current.ino === file.snapshot.ino
-              && current.content.equals(file.snapshot.content)) unlinkSync(target);
-        }
-      }
-      throw error;
-    }
-  });
-}
-
-export async function repairInstallationControl(control, { chooseRepair, confirmRepair, hooks, readGitOriginals } = {}) {
-  if (control.status !== "repair_required" || typeof chooseRepair !== "function") return control;
-  if (await chooseRepair(structuredClone(control)) !== "start") return control;
-  const plan = inspectControlRepair(control.target, { readGitOriginals });
-  const candidates = plan.items.filter((item) => item.available);
-  let decision = "skip";
-  if (typeof confirmRepair === "function") decision = await confirmRepair(structuredClone(plan));
-  if (decision === "repair") for (const item of candidates) {
-    try { Object.assign(item, applyRunRepair(control.target, item, hooks, readGitOriginals)); }
-    catch (error) { plan.diagnostics.push({ run_id: item.run_id, code: String(error.code ?? error.message) }); }
-  }
-  const after = inspectControlMigration(control.target);
-  after.changes = control.changes;
-  after.repair = publicRepair(plan, !candidates.length ? "needs_input" : decision !== "repair" ? "deferred"
-    : plan.diagnostics.length || after.status !== "current" ? "partial" : "applied");
-  if (plan.diagnostics.length) {
-    after.diagnostics.push(...plan.diagnostics);
-    after.status = "repair_required";
-  }
-  return after;
-}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/backlog-summary-shape.d.ts

@@ -1,4 +0,0 @@
-export const BACKLOG_SUMMARY_FIELDS: readonly string[];
-export function validBacklogSummary(value: unknown): boolean;
-
-export function validWorkSummary(value: unknown, runId: string): boolean;