create-agdf 0.20.1 → 0.30.0

package/lib/scaffold/plan.js

@@ -1,3 +1,5 @@
+import { CURRENT_LAYOUT } from '#agdf-core/control-state/run-identity.js';
+import { canonicalInitPlan } from "#agdf-core/resources/canonical-init-plan.js";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { generatedRoot, languageConfigContent, pluginDefinition } from "../cli/runtime-context.js";
@@ -16,9 +18,7 @@ const codexPluginFiles = [
   join(".agents", "plugins", "marketplace.json"),
   join("plugins", "agdf", ".codex-plugin", "plugin.json"),
   join("plugins", "agdf", "control", "README.md"),
-  join("plugins", "agdf", "control", "templates", "AGDF_RUN.md"),
   join("plugins", "agdf", "control", "templates", "RUN_STATE.md"),
-  join("plugins", "agdf", "control", "templates", "MASTER_BACKLOG.md"),
   join("plugins", "agdf", "control", "templates", "SOT_REGISTRY.md"),
   join("plugins", "agdf", "control", "templates", "CONTEXT_GRAPH.md"),
   join("plugins", "agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
@@ -43,9 +43,7 @@ const codexPluginFiles = [
 ];
 const controlFiles = [
   join(".agdf", "control", "README.md"),
-  join(".agdf", "control", "templates", "AGDF_RUN.md"),
   join(".agdf", "control", "templates", "RUN_STATE.md"),
-  join(".agdf", "control", "templates", "MASTER_BACKLOG.md"),
   join(".agdf", "control", "templates", "SOT_REGISTRY.md"),
   join(".agdf", "control", "templates", "CONTEXT_GRAPH.md"),
   join(".agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
@@ -60,10 +58,6 @@ const controlFiles = [
   join(".agdf", "control", "templates", "artefacts", "OR.md"),
 ];
 const liveControlFiles = [
-  {
-    path: join(".agdf", "control", "MASTER_BACKLOG.md"),
-    source: join(".agdf", "control", "templates", "MASTER_BACKLOG.md"),
-  },
   {
     path: join(".agdf", "control", "SOT_REGISTRY.md"),
     source: join(".agdf", "control", "templates", "SOT_REGISTRY.md"),
@@ -104,37 +98,20 @@ export function generatedFilesForTarget(target, targetDir, force, languagePrefer
   const files = [];
 
   if (target === "config") {
+    const configPath = join(targetDir, '.agdf', 'control', 'config.json');
+    let existing = { control_layout: CURRENT_LAYOUT };
+    try { existing = JSON.parse(readFileSync(configPath, 'utf8')); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (!existing || typeof existing !== 'object' || Array.isArray(existing)) throw Error('invalid_control_config');
     files.push({
       path: join(".agdf", "control", "config.json"),
-      content: languageConfigContent(languagePreference),
+      content: languageConfigContent(languagePreference, existing),
       allowOverwrite: true,
     });
     return files;
   }
 
-  if (target === "init") {
-    addLanguageConfig(files, languagePreference);
-    files.push({
-      path: join(".agdf", "control", "README.md"),
-      content: loadAsset(join(".agdf", "control", "README.md")),
-    });
-
-    for (const controlPath of liveControlFiles) {
-      files.push({
-        path: controlPath.path,
-        content: loadAsset(controlPath.source),
-      });
-    }
-
-    for (const templatePath of artefactTemplateFiles) {
-      files.push({
-        path: templatePath,
-        content: loadAsset(templatePath),
-      });
-    }
-
-    return files;
-  }
+  if (target === "init") return canonicalInitPlan(languagePreference);
 
   if (target === "codex-repo") {
     addLanguageConfig(files, languagePreference);

package/lib/scaffold/presentation.js

@@ -31,7 +31,7 @@ export function createCanonicalInitLifecycleResult(destination, initialization)
     restart: { required: false, reason: "none" },
     next_action: {
       kind: "control_setup",
-      text: "Create or migrate one canonical run with an explicit run id before drafting durable delivery state.",
+      text: 'Capture a planned UR, or create a canonical Run for delivery. Inspect inventory before selecting existing work.',
     },
     changes: created,
     retained,
@@ -113,7 +113,7 @@ export function printNextSteps(target, destination, files, removedOpenCodeAgents
     io.log(`- AGDF language preference: artefacts=${language.artifact_language}, chat=${language.chat_language}, runtime=${language.runtime_language}.`);
   }
   if (target === "init") {
-    io.log("- Create the canonical run with `run-create --run <run_id>` and record each later step with `run-step` instead of editing RUN_STATE.md by hand.");
+    io.log("- Create a current Run with `run-create --title <title> --operation <uuid>`; retain its returned Run/revision and record later steps through their inspected current commands.");
     io.log("- An active delivery intake continues without a second setup prompt: write the UR, record it with `run-step --step ur`, then dispatch gate-check with `--intake`.");
     io.log("- Run the installed `agdf doctor` to check the control state before the next agent run.");
     io.log("- Commit the live control files once they represent the repository's current delivery state.");

package/lib/scaffold/write.js

@@ -1,16 +1,21 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { pluginDefinition } from "../cli/runtime-context.js";
+import { atomicWrite } from '#agdf-core/owned-file-lock.js';
+import { markControlMutationEffect } from '#agdf-core/control-state/control-layout.js';
+import { hasSymlinkComponent } from '#agdf-core/control-state/contained-file.js';
 
 export function writeGeneratedFile(targetDir, relativePath, content, force, allowOverwrite = false) {
   const outputPath = join(targetDir, relativePath);
+  if (relativePath.replaceAll('\\', '/') === '.agdf/control/config.json' && hasSymlinkComponent(targetDir, '.agdf/control/config.json')) throw Error('AGDF_CONTROL_PATH_INVALID');
   mkdirSync(dirname(outputPath), { recursive: true });
 
   if (existsSync(outputPath) && !force && !allowOverwrite) {
     throw new Error(`Refusing to overwrite existing file: ${relativePath}. Re-run with --force if you want to replace it.`);
   }
 
-  writeFileSync(outputPath, content, "utf8");
+  if (relativePath.replaceAll('\\', '/') === '.agdf/control/config.json') { markControlMutationEffect(); atomicWrite(outputPath, content); }
+  else writeFileSync(outputPath, content, 'utf8');
 }
 
 export function removeOwnedLegacyOpenCodeAgents(targetDir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.20.1",
+  "version": "0.30.0",
   "description": "Install AGDF plugins, bootstrap supported repository surfaces and validate durable governance state.",
   "type": "module",
   "engines": {
@@ -14,6 +14,7 @@
     "generated/.opencode",
     "generated/opencode.json",
     "generated/plugins/agdf",
+    "generated/plugins/agdf-planning",
     "generated/plugins/copilot/agdf",
     "generated/submissions/openai/agdf",
     "opencode-plugin.js",
@@ -26,7 +27,10 @@
     "./control-command": "./lib/control-command.js",
     "./cli": "./bin/create-agdf.js",
     "./mcp-dispatch-runtime": "./lib/mcp-dispatch-runtime.js",
-    "./opencode-plugin": "./opencode-plugin.js"
+    "./opencode-plugin": "./opencode-plugin.js",
+    "./mcp-protocol-runtime": "./lib/mcp-protocol-runtime.js",
+    "./mcp-worker-runtime": "./lib/mcp-worker-runtime.js",
+    "./mcp-owner-protocol": "./lib/mcp-owner-protocol.js"
   },
   "bin": {
     "create-agdf": "./bin/create-agdf.js"

package/runtime/core/lib/control-evaluation/closeout-readiness.js

@@ -8,6 +8,14 @@ import { inspectQaReports } from './qa-follow-up.js';
 export { STRUCTURED_REQUIRED_REVIEWS, reviewArtefactType };
 
 export const closeoutConfirmation = (runId, revisionId, operationId, orDigest) => `Close Run: ${runId} ${revisionId} ${operationId} ${orDigest}`;
+// Discovery and validation share the existing compact document requirements.
+export const QUICK_CLOSEOUT_AUTHORING_FORMAT = {
+  template: 'OR', report_mode: 'OR-lite',
+  required_metadata: [{ field: 'run_id', label: 'Run' }, { field: 'report_mode', label: 'Report mode' }],
+  run_binding: 'Exactly one Run: <current run_id> or - run_id: <current run_id>; never both.',
+  required_sections: ['Result', 'Evidence', 'Risk', 'Next Step'],
+  template_scope: 'Use the bound OR template for identity; OR-lite needs only the declared metadata and four concrete sections, not OR-full sections.',
+};
 const value = (text, field, label) => cleanStatusCell(extractField(text, field) || (label ? text.match(new RegExp(`^${label}:[ \\t]*(.*)$`, 'mu'))?.[1] : ''));
 const concrete = text => filled(text) && !isPlaceholderValue(text) && !/^(?:tbd|todo|<)/iu.test(text);
 export function closeoutContext(text) {
@@ -22,7 +30,7 @@ export function evaluateCloseoutReadiness(state, report, readArtefact, { prepare
   const findings = [], fail = reason => findings.push(reason), route = state.mode_slice_decision?.decision;
   const structured = ['structured_slice', 'structured_delivery'].includes(route);
   if (typeof report !== 'string' || Buffer.byteLength(report) > 131072) return { ready: false, findings: ['or_unavailable_or_oversized'] };
-  if (prepared) for (const [field, label] of [['run_id', 'Run'], ['report_mode', 'Report mode'], ...(structured ? [['status', 'Status']] : [])]) {
+  if (prepared) for (const [field, label] of [...QUICK_CLOSEOUT_AUTHORING_FORMAT.required_metadata.map(row => [row.field, row.label]), ...(structured ? [['status', 'Status']] : [])]) {
     const declarations = [...report.matchAll(new RegExp(`^(?:- ${field}|${label}):[ \\t]*(.*)$`, 'gmu'))];
     if (declarations.length !== 1) fail('or_field_ambiguous:' + field);
   }
@@ -34,7 +42,7 @@ export function evaluateCloseoutReadiness(state, report, readArtefact, { prepare
   if (programme?.applicable && !programme.final_ready) fail('programme_aggregation_unfulfilled');
   if (!structured) {
     if (state.artefacts.get('CR')?.status !== 'done') fail('code_review_missing');
-    for (const section of ['Result', 'Evidence', 'Risk', 'Next Step']) if (!concrete(markdownSection(report, section).trim())) fail(`or_${section.toLowerCase().replaceAll(' ', '_')}_missing`);
+    for (const section of QUICK_CLOSEOUT_AUTHORING_FORMAT.required_sections) if (!concrete(markdownSection(report, section).trim())) fail(`or_${section.toLowerCase().replaceAll(' ', '_')}_missing`);
   } else {
     if (!['done', 'completed', 'pass'].includes(value(report, 'status', 'Status'))) fail('or_status_unconfirmed');
     for (const gate of ['UR', 'PRD', 'SD', 'TP', 'QA', 'UAT']) {

package/runtime/core/lib/control-evaluation/decision-content-placeholder.js

@@ -0,0 +1,9 @@
+// Template prompts and status-only values that never count as authored content. Pure, so the
+// run inventory and other `node:`-free readers share the same rule.
+const prompts = new Set(['describe the trustworthy outcome.', 'what outcome should become possible?',
+  'which tp tasks are fully done, partially done or not done?', 'what remains unverified?', 'which risks remain and what is their impact?']);
+export function isDecisionContentPlaceholder(value) {
+  if (typeof value !== 'string') return true;
+  const text = value.trim().replace(/^`([^`]+)`$/u, '$1').replace(/\s+/gu, ' ').toLowerCase();
+  return !text || prompts.has(text) || /^(?:todo|tbd|<[^>]+>|(?:draft|done|ready|blocked|pass|revise|block)(?:\s*\|\s*(?:draft|done|ready|blocked|pass|revise|block))+)$/.test(text);
+}

package/runtime/core/lib/control-evaluation/decision-content-readiness.js

@@ -3,14 +3,9 @@ import { containedRegularFile, hasSymlinkComponent } from '../control-state/cont
 import { artefactFileDigest } from '../control-state/run-seal-compute.js';
 import { readAuthoredContent, readReportDecision } from './report-decision.js';
 import { inspectQaReports } from './qa-follow-up.js';
+import { isDecisionContentPlaceholder } from './decision-content-placeholder.js';
 
-const prompts = new Set(['describe the trustworthy outcome.', 'what outcome should become possible?',
-  'which tp tasks are fully done, partially done or not done?', 'what remains unverified?', 'which risks remain and what is their impact?']);
-export function isDecisionContentPlaceholder(value) {
-  if (typeof value !== 'string') return true;
-  const text = value.trim().replace(/^`([^`]+)`$/u, '$1').replace(/\s+/gu, ' ').toLowerCase();
-  return !text || prompts.has(text) || /^(?:todo|tbd|<[^>]+>|(?:draft|done|ready|blocked|pass|revise|block)(?:\s*\|\s*(?:draft|done|ready|blocked|pass|revise|block))+)$/.test(text);
-}
+export { isDecisionContentPlaceholder };
 export function concreteDecisionContent(value, { allowNone = false } = {}) {
   return typeof value === 'string' && value.length <= 1200 && !isDecisionContentPlaceholder(value)
     && !/^(?:pass|passed|revise|block|done|ready|draft)$/iu.test(value.trim())

package/runtime/core/lib/control-evaluation/definition-sources.js

@@ -1,3 +1,4 @@
+import { runDocumentPath } from '../control-state/run-identity.js';
 import { readFileSync } from '../control-read/fs.js';
 import { hasSymlinkComponent, containedRegularFile } from '../control-state/contained-file.js';
 import { artefactFileDigest } from '../control-state/run-seal-compute.js';
@@ -14,7 +15,7 @@ export function inspectUxIntentDecision(content) {
 export function inspectDefinitionSources(root, state, runId, gate, sourceTypes) {
   const sources = [];
   const issue = (code, path, expected, observed, repairable = false) => ({ sources, issue: { code, path, expected, observed, repairable } });
-  const output = `.agdf/control/artefacts/${runId}/${gate}.md`;
+  const output = `${runDocumentPath(runId, '')}/${gate}.md`;
   if (!state || hasSymlinkComponent(root, output)) return issue('unsafe_destination', output, 'contained non-symlink output', 'unsafe');
   for (const type of sourceTypes) {
     const path = String(state.artefacts.get(type)?.path ?? '').replace(/^`|`$/gu, '');
@@ -29,7 +30,7 @@ export function inspectDefinitionSources(root, state, runId, gate, sourceTypes)
   const reviewSource = sources.find(source => source.type === 'Brownfield Review');
   const review = reviewSource ? readFileSync(containedRegularFile(root, reviewSource.path).path, 'utf8') : '';
   if (extractField(review, 'ux_intent_definition_required') === 'yes') {
-    const canonical = `.agdf/control/artefacts/${runId}/UX_INTENT_DEFINITION.md`;
+    const canonical = `${runDocumentPath(runId, '')}/UX_INTENT_DEFINITION.md`;
     const analysis = state.artefacts.get('UX Intent Definition');
     const path = String(analysis?.path || canonical).replace(/^`|`$/gu, '');
     if (path !== canonical || hasSymlinkComponent(root, path)) return issue('unsafe_ux_source', path, canonical, 'foreign or unsafe source');

package/runtime/core/lib/control-evaluation/delivery-map.js

@@ -1,5 +1,3 @@
-import { existsSync } from "../control-read/fs.js";
-import { join } from 'node:path';
 import { aggregate } from "../control-state/aggregate.js";
 import { resolveRuns } from "../control-state/run-state-resolver.js";
 import { resolveConfiguredChatLanguage } from "../resources/context.js";
@@ -7,7 +5,7 @@ import { isGateSatisfied, transitionDecisionForRunState } from "./gate-policy.js
 import { effectiveNextAllowedAction } from "./next-action.js";
 import { gateApprovalStatus, readRunState, resolvedArtefactFile } from "./run-state.js";
 import { deliveryRelationships, relationshipRequired, sameRelationship } from "./delivery-relationships.js";
-import { allowNoActiveRuns, filled, markdownSection, parseBacklogSection, readTargetFile } from "./shared.js";
+import { allowNoActiveRuns, filled } from "./shared.js";
 import { evaluateReconciliationState } from "./parent-reconciliation.js";
 import { readSourceRevisions, sourceRevisionObservation } from "../control-state/run-source-revisions.js";
 import { readArtefactBindings } from "../control-state/artefact-bindings.js";
@@ -153,14 +151,6 @@ export function deriveQualityOutlook(runState, findings = []) {
   return "No additional quality follow-up identified from the current control state.";
 }
 
-function readBacklogPointers(targetDir) {
-  const backlogPath = join(".agdf", "control", "MASTER_BACKLOG.md");
-  if (!existsSync(join(targetDir, backlogPath))) return [];
-
-  const backlog = readTargetFile(targetDir, backlogPath);
-  const activeSection = markdownSection(backlog, "Active Backlog");
-  return parseBacklogSection(activeSection);
-}
 
 export function evaluateDeliveryMap(targetDir, selection = {}, dependencies = {}) {
   const { evaluateDoctor, buildStatusCard, postApprovalTransition } = dependencies;
@@ -253,7 +243,7 @@ export function evaluateDeliveryMap(targetDir, selection = {}, dependencies = {}
       chatLanguage: resolveConfiguredChatLanguage(targetDir),
       findings: map.findings,
     }),
-    backlog_pointers: readBacklogPointers(targetDir),
+    backlog_pointers: [], // Legacy field: current relationships come from registered Run sources.
     artefacts: Object.fromEntries([...runState.artefacts.entries()]),
     approvals: Object.fromEntries([...runState.approvals.entries()]),
     mode_slice_decision: runState.mode_slice_decision,