create-agdf 0.14.1 → 0.14.2

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/cli/parse-args.js

@@ -0,0 +1,173 @@
+import { resolve } from "node:path";
+import process from "node:process";
+import { configuredLanguage, resolveLanguagePreference } from "./runtime-context.js";
+import { resolveCommand, supportedCommandNames } from "./command-registry.js";
+
+export class CliUsageError extends Error {
+  constructor(message, { showUsage = false } = {}) {
+    super(message);
+    this.name = "CliUsageError";
+    this.exitCode = 1;
+    this.showUsage = showUsage;
+  }
+}
+
+function requiredValue(args, index, option) {
+  const next = args[index + 1];
+  if (!next) throw new CliUsageError(`Missing value for ${option}`);
+  return next;
+}
+
+export function parseArgs(argv, dependencies = {}) {
+  const cwd = dependencies.cwd ?? process.cwd();
+  const languagePreference = dependencies.resolveLanguagePreference ?? resolveLanguagePreference;
+  const normalizeLanguage = dependencies.configuredLanguage ?? configuredLanguage;
+  const args = [...argv];
+  let target;
+  let dir = ".";
+  let force = false;
+  let json = false;
+  let verbose = false;
+  let statusCard = false;
+  let approvalEnvelope = false;
+  let language;
+  let dirExplicit = false;
+  let surface = "generic";
+  let fixture;
+  let persist = false;
+  let model;
+  let generateCandidates = false;
+  let generatorModel;
+  let maxGeneratedCandidates = 5;
+  let generationTimeoutMs = 30000;
+  let generationCostUnits = 5;
+  let runId;
+  let allActive = false;
+  let scope;
+  let confirm = false;
+  let runtimeChecksDecision;
+  let runtimeChecksAction;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg) continue;
+    if (arg === "--help" || arg === "-h") return { kind: "help" };
+    if (arg === "--force") { force = true; continue; }
+    if (arg === "--json") { json = true; continue; }
+    if (arg === "--verbose") { verbose = true; continue; }
+    if (arg === "--status-card") { statusCard = true; continue; }
+    if (arg === "--approval-envelope") { approvalEnvelope = true; continue; }
+    if (arg === "--persist") { persist = true; continue; }
+    if (arg === "--generate-candidates") { generateCandidates = true; continue; }
+    if (arg === "--all-active") { allActive = true; continue; }
+    if (arg === "--confirm") { confirm = true; continue; }
+
+    if (arg === "--runtime-checks") {
+      const next = requiredValue(args, i, arg);
+      if (!["enable", "manual", "cancel"].includes(next)) throw new CliUsageError("--runtime-checks must be enable, manual or cancel.");
+      runtimeChecksDecision = next;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--run") {
+      runId = requiredValue(args, i, arg);
+      i += 1;
+      continue;
+    }
+
+    if (["--surface", "--scope", "--fixture", "--model", "--generator-model", "--max-generated-candidates", "--generation-timeout-ms", "--generation-cost-units"].includes(arg)) {
+      const next = requiredValue(args, i, arg);
+      if (arg === "--surface") {
+        if (!["codex", "claude", "copilot", "opencode", "generic"].includes(next)) {
+          throw new CliUsageError("Unsupported surface. Use codex, claude, copilot, opencode or generic.");
+        }
+        surface = next;
+      } else if (arg === "--scope") {
+        if (!["repository", "global"].includes(next)) throw new CliUsageError("Unsupported scope. Use repository or global.");
+        scope = next;
+      } else if (arg === "--fixture") fixture = next;
+      else if (arg === "--model") model = next;
+      else if (arg === "--generator-model") generatorModel = next;
+      else {
+        const value = Number(next);
+        const maximum = arg === "--generation-timeout-ms" ? 30000 : 5;
+        if (!Number.isInteger(value) || value < 1 || value > maximum) {
+          throw new CliUsageError(`${arg} must be an integer from 1 to ${maximum}.`);
+        }
+        if (arg === "--max-generated-candidates") maxGeneratedCandidates = value;
+        else if (arg === "--generation-timeout-ms") generationTimeoutMs = value;
+        else generationCostUnits = value;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--language" || arg === "--lang") {
+      const next = requiredValue(args, i, arg);
+      const normalized = normalizeLanguage(next);
+      if (!normalized) throw new CliUsageError("Invalid language tag. Use a BCP 47 tag such as de, en or fr-CA.");
+      language = normalized;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--dir") {
+      dir = requiredValue(args, i, arg);
+      dirExplicit = true;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--target" || arg === "-t") {
+      target = requiredValue(args, i, arg);
+      i += 1;
+      continue;
+    }
+
+    if (!arg.startsWith("-") && !target) {
+      target = arg;
+      continue;
+    }
+    if (!arg.startsWith("-") && target === "runtime-checks" && !runtimeChecksAction) {
+      if (!["status", "enable", "manual"].includes(arg)) throw new CliUsageError("runtime-checks action must be status, enable or manual.");
+      runtimeChecksAction = arg;
+      continue;
+    }
+    throw new CliUsageError(`Unknown argument: ${arg}`);
+  }
+
+  if (!target || !resolveCommand(target)) {
+    throw new CliUsageError(`Please choose one target: ${supportedCommandNames().join(", ")}.`, { showUsage: true });
+  }
+
+  return {
+    kind: "command",
+    options: {
+      target,
+      dir: resolve(cwd, dir),
+      force,
+      json,
+      verbose,
+      statusCard,
+      approvalEnvelope,
+      dirExplicit,
+      language: languagePreference(language),
+      surface,
+      fixture: fixture ? resolve(cwd, fixture) : null,
+      persist,
+      model,
+      generateCandidates,
+      runId,
+      allActive,
+      scope,
+      confirm,
+      runtimeChecksDecision,
+      runtimeChecksAction: runtimeChecksAction ?? "status",
+      generatorModel,
+      maxGeneratedCandidates,
+      generationTimeoutMs,
+      generationCostUnits,
+    },
+  };
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/cli/runtime-context.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+import {
+  canonicalizeLanguageTag,
+  resolvePresentationLocale,
+} from "../interaction-presentation.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const packageRoot = resolve(__dirname, "../..");
+export const generatedRoot = join(packageRoot, "generated");
+
+const pluginDefinitionPath = join(generatedRoot, "plugins", "agdf", "meta", "agdf-plugin.definition.json");
+const interactionLocalesPath = join(generatedRoot, "plugins", "agdf", "meta", "agdf-interaction-locales.json");
+
+export const pluginDefinition = JSON.parse(readFileSync(pluginDefinitionPath, "utf8"));
+export const interactionLocales = JSON.parse(readFileSync(interactionLocalesPath, "utf8"));
+
+export function configuredLanguage(value) {
+  const normalized = canonicalizeLanguageTag(value);
+  if (!normalized) return "";
+  const language = normalized.split("-")[0];
+  if (interactionLocales.locales[normalized] || interactionLocales.locales[language]) {
+    return resolvePresentationLocale(interactionLocales, normalized);
+  }
+  return normalized;
+}
+
+export function detectSystemLocale(env = process.env) {
+  const envLocale = env.LC_ALL || env.LC_MESSAGES || env.LANG || env.LANGUAGE || "";
+  if (envLocale) return envLocale;
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().locale || "";
+  } catch {
+    return "";
+  }
+}
+
+export function resolveLanguagePreference(explicitLanguage, env = process.env) {
+  const explicit = configuredLanguage(explicitLanguage);
+  if (explicit) {
+    return {
+      artifact_language: explicit,
+      chat_language: explicit,
+      runtime_language: "en",
+      source: "parameter",
+      detected_locale: detectSystemLocale(env) || "unknown",
+    };
+  }
+
+  const detectedLocale = detectSystemLocale(env);
+  const detected = configuredLanguage(detectedLocale) || interactionLocales.fallbackLocale;
+  return {
+    artifact_language: detected,
+    chat_language: detected,
+    runtime_language: "en",
+    source: detectedLocale ? "system_locale" : "default",
+    detected_locale: detectedLocale || "unknown",
+  };
+}
+
+export function resolveConfiguredChatLanguage(targetDir) {
+  const configPath = join(targetDir, ".agdf", "control", "config.json");
+  if (!existsSync(configPath)) return interactionLocales.fallbackLocale;
+  try {
+    const config = JSON.parse(readFileSync(configPath, "utf8"));
+    return resolvePresentationLocale(interactionLocales, config.chat_language);
+  } catch {
+    return interactionLocales.fallbackLocale;
+  }
+}
+
+export function languageConfigContent(languagePreference) {
+  return `${JSON.stringify({
+    artifact_language: languagePreference.artifact_language,
+    chat_language: languagePreference.chat_language,
+    runtime_language: languagePreference.runtime_language,
+    source: languagePreference.source,
+    detected_locale: languagePreference.detected_locale,
+  }, null, 2)}\n`;
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/cli/validation-handlers.js

@@ -0,0 +1,46 @@
+import {
+  buildStatusCard,
+  evaluateGateCheck,
+  printApprovalEnvelope,
+  postApprovalTransition,
+  printGateCheckReport,
+} from "../control-evaluation/gate-check.js";
+import { evaluateDeliveryMap, printDeliveryMapReport } from "../control-evaluation/delivery-map.js";
+import { evaluateDoctor, printDoctorReport } from "../control-evaluation/doctor.js";
+import { executeDeliveryPathSearch } from "./delivery-path-search-command.js";
+
+const deliveryMapDependencies = Object.freeze({ evaluateDoctor, buildStatusCard, postApprovalTransition });
+
+export function createValidationHandlers(io = console) {
+  return new Map([
+    ["doctor", (options) => {
+      const report = evaluateDoctor(options.dir, options);
+      printDoctorReport(report, options.json, io);
+      return report.status === "block" ? 2 : 0;
+    }],
+    ["gate-check", (options) => {
+      const report = evaluateGateCheck(options.dir, options);
+      if (options.approvalEnvelope) {
+        const output = printApprovalEnvelope(report, { io, reEvaluate: () => evaluateGateCheck(options.dir, options) });
+        return output.status === "blocked" ? 2 : 0;
+      }
+      const presentationRendered = printGateCheckReport(report, options.json, options.statusCard, io);
+      if (presentationRendered === false) return 2;
+      return report.status === "blocked" ? 2 : 0;
+    }],
+    ["delivery-map", (options) => {
+      const report = evaluateDeliveryMap(options.dir, options, deliveryMapDependencies);
+      printDeliveryMapReport(report, options.json, io);
+      return report.status === "block" ? 2 : 0;
+    }],
+    ["delivery-path-search", async (options) => {
+      try {
+        const result = await executeDeliveryPathSearch(options, io);
+        return result.status === "recommendation" ? 0 : 2;
+      } catch (error) {
+        io.error(`Delivery Path Search failed: ${error.message}`);
+        return 2;
+      }
+    }],
+  ]);
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/control-evaluation/delivery-map.js

@@ -0,0 +1,301 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { aggregate, resolveRuns } from '../control-state/index.js';
+import { resolveConfiguredChatLanguage } from '../cli/runtime-context.js';
+import { isGateSatisfied, transitionDecisionForRunState } from './gate-policy.js';
+import { gateApprovalStatus, readRunState, resolvedArtefactFile } from './run-state.js';
+import { allowNoActiveRuns, filled, isPlaceholderValue, markdownSection, parseBacklogSection, readTargetFile } from './shared.js';
+import { evaluateReconciliationState } from './parent-reconciliation.js';
+
+const deliveryRelationships = [
+  { from: "UR", relationship: "approved_by", to: "Approval: UR", requiredBy: "UR" },
+  { from: "PRD", relationship: "derived_from", to: "UR", requiredBy: "PRD" },
+  { from: "SD", relationship: "derived_from", to: "PRD", requiredBy: "SD" },
+  { from: "TP", relationship: "derived_from", to: "SD", requiredBy: "TP" },
+  { from: "QA_REPORT", relationship: "tests", to: "TP", requiredBy: "QA" },
+];
+
+function relationshipRequired(runState, requiredBy) {
+  if (gateApprovalStatus(runState, requiredBy) === "not_applicable") return false;
+  if (requiredBy === "QA") {
+    return isGateSatisfied(runState, "QA");
+  }
+
+  return isGateSatisfied(runState, requiredBy);
+}
+
+function findRelationship(runState, expected) {
+  return runState.artefact_chain.find((row) =>
+    row.from === expected.from
+    && row.relationship === expected.relationship
+    && row.to === expected.to
+  );
+}
+
+function severityFromImpact(value) {
+  if (value === "block") return "block";
+  if (value === "revise") return "revise";
+  if (value === "warning" || value === "warn") return "warn";
+  return null;
+}
+
+export function analyzeDeliveryMap(runState, dependencies = {}) {
+  const findings = [];
+  const reconciliation = evaluateReconciliationState(runState, dependencies);
+  findings.push(...reconciliation.findings);
+  const relationships = deliveryRelationships.map((expected) => {
+    const row = findRelationship(runState, expected);
+    const required = relationshipRequired(runState, expected.requiredBy);
+    const evidence = row?.evidence ?? "";
+    const status = !row ? "missing" : filled(evidence) ? "pass" : required ? "missing_evidence" : "template";
+
+    if (required && status !== "pass") {
+      findings.push({
+        severity: "revise",
+        code: status === "missing" ? "AGDF_DELIVERY_RELATIONSHIP_MISSING" : "AGDF_DELIVERY_RELATIONSHIP_EVIDENCE_MISSING",
+        message: `${expected.from} must be traceable via ${expected.relationship} ${expected.to}.`,
+        path: runState.path,
+        next_step: "Fill the Artefact Chain row with concrete evidence before treating the delivery map as complete.",
+      });
+    }
+
+    return {
+      from: expected.from,
+      relationship: expected.relationship,
+      to: expected.to,
+      required,
+      status,
+      evidence,
+    };
+  });
+
+  for (const item of runState.missing_evidence) {
+    const severity = severityFromImpact(item.impact);
+    if (!severity) continue;
+    findings.push({
+      severity,
+      code: "AGDF_MISSING_EVIDENCE_DECLARED",
+      message: item.missing_evidence,
+      path: runState.path,
+      next_step: item.required_next_step || "Resolve or explicitly accept the missing evidence before advancing the gate.",
+    });
+  }
+
+  for (const item of runState.risks) {
+    const severity = severityFromImpact(item.impact);
+    if (!severity) continue;
+    findings.push({
+      severity,
+      code: "AGDF_RISK_DECLARED",
+      message: item.risk,
+      path: runState.path,
+      next_step: item.mitigation_or_owner || "Assign mitigation or ownership before advancing the gate.",
+    });
+  }
+
+  const contextSeverity = severityFromImpact(runState.context_graph?.gate_effect);
+  if (contextSeverity) {
+    findings.push({
+      severity: contextSeverity,
+      code: "AGDF_CONTEXT_GRAPH_GATE_EFFECT",
+      message: `Context Graph impact is ${runState.context_graph.impact || "unspecified"} with gate effect ${runState.context_graph.gate_effect}.`,
+      path: runState.path,
+      next_step: runState.context_graph.required_action && runState.context_graph.required_action !== "none"
+        ? `Resolve Context Graph action: ${runState.context_graph.required_action}.`
+        : "Clarify the Context Graph impact before advancing the gate.",
+    });
+  }
+
+  const multiScopeState = runState.source_scope?.multi_scope_state;
+  if (multiScopeState === "ambiguous" || multiScopeState === "blocked") {
+    findings.push({
+      severity: multiScopeState === "blocked" ? "block" : "revise",
+      code: "AGDF_SCOPE_AMBIGUOUS",
+      message: "Multiple active scope lines are plausible; the agent must not choose one silently.",
+      path: runState.path,
+      next_step: "List competing scope lines with gate and artefact evidence, then clarify the active scope.",
+    });
+  }
+
+  const branchEffect = runState.source_scope?.branch_workspace_scope_effect;
+  if (branchEffect === "conflicts" || branchEffect === "insufficient") {
+    findings.push({
+      severity: branchEffect === "conflicts" ? "revise" : "warn",
+      code: "AGDF_BRANCH_NOT_SCOPE_PROOF",
+      message: "Branch or workspace evidence is not sufficient scope proof.",
+      path: runState.path,
+      next_step: "Confirm the active scope from durable artefacts or record why branch/workspace evidence is only supporting evidence.",
+    });
+  }
+
+  if (runState.memory?.target && runState.memory.target !== "none" && !filled(runState.memory.reason)) {
+    findings.push({
+      severity: "warn",
+      code: "AGDF_MEMORY_TARGET_REASON_MISSING",
+      message: "Knowledge persistence target is set without a reason.",
+      path: runState.path,
+      next_step: "Fill memory_reason or set memory_target to none.",
+    });
+  }
+
+  return {
+    relationships,
+    missing_evidence: runState.missing_evidence,
+    risks: runState.risks,
+    context_graph: runState.context_graph,
+    source_scope: runState.source_scope,
+    memory: runState.memory,
+    parent_reconciliation: reconciliation.parent_reconciliation,
+    programme_aggregation: reconciliation.programme_aggregation,
+    findings,
+  };
+}
+
+export function deriveQualityOutlook(runState, findings = []) {
+  if (filled(runState.quality_outlook)) return runState.quality_outlook;
+  if (findings.some((finding) => finding.severity === "block" || finding.severity === "revise")) {
+    return "Resolve blocking or revise-level delivery-map findings before making stronger quality claims.";
+  }
+  if (findings.some((finding) => finding.severity === "warn")) {
+    return "Review warning-level findings when investing further in delivery confidence.";
+  }
+  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;
+  if (typeof evaluateDoctor !== "function" || typeof buildStatusCard !== "function" || typeof postApprovalTransition !== "function") {
+    throw new TypeError("evaluateDeliveryMap requires doctor and status-card composition dependencies.");
+  }
+  if (selection.allActive) {
+    const selected = resolveRuns(targetDir, { allActive: true });
+    const runs = selected.runs.map((run) => ({
+      run_id: run.run_id,
+      report: evaluateDeliveryMap(targetDir, { runId: run.run_id }, dependencies),
+    }));
+    const status = selected.findings.length
+      ? "block"
+      : aggregate(
+          runs.map((item) => ({
+            run_id: item.run_id,
+            status: item.report.status,
+          })),
+          { allowNoActiveRuns: allowNoActiveRuns(targetDir) },
+        ).status;
+    const findings = [
+      ...selected.findings.map((finding) => ({
+        ...finding,
+        severity: "block",
+        message: "Invalid canonical run entry.",
+        next_step: "Repair or remove the invalid run entry.",
+      })),
+      ...runs.flatMap((item) =>
+        (item.report.doctor_report?.findings ?? item.report.findings).map((finding) => ({
+          ...finding,
+          run_id: item.run_id,
+        })),
+      ),
+    ];
+    return {
+      schema_version: "1",
+      status,
+      current_gate: "all-active",
+      next_allowed_action: runs.length
+        ? "Resolve per-run findings."
+        : "Create or activate a governed run.",
+      quality_outlook: "Keep every active run independently actionable.",
+      relationships: runs.flatMap((item) => item.report.relationships),
+      findings,
+      runs,
+    };
+  }
+  const doctorReport = evaluateDoctor(targetDir, selection);
+  const runState = readRunState(targetDir, selection);
+  const map = analyzeDeliveryMap(runState, {
+    loadRun: (runId) => readRunState(targetDir, { runId }),
+    resolveFile: (path) => resolvedArtefactFile(targetDir, path),
+  });
+  const gateDecision = transitionDecisionForRunState(runState);
+  const currentGate = gateDecision.current_gate;
+
+  const severityRank = { block: 3, revise: 2, warn: 1 };
+  const deliverySeverity = map.findings.reduce((max, finding) => Math.max(max, severityRank[finding.severity] ?? 0), 0);
+  const doctorSeverity = severityRank[doctorReport.status] ?? 0;
+  const maxSeverity = Math.max(deliverySeverity, doctorSeverity);
+  const status = maxSeverity >= 3 ? "block" : maxSeverity === 2 ? "revise" : maxSeverity === 1 ? "warn" : "pass";
+
+  const qualityOutlook = deriveQualityOutlook(runState, map.findings);
+  const nextAllowedAction = isPlaceholderValue(runState.next_allowed_action) ? gateDecision.next_allowed_action : runState.next_allowed_action;
+  const postApproval = postApprovalTransition(gateDecision.missing_approval);
+
+  return {
+    schema_version: "1",
+    status,
+    checked_at: new Date().toISOString(),
+    target_dir: targetDir,
+    current_gate: currentGate,
+    next_allowed_action: nextAllowedAction,
+    next_gate_after_approval: postApproval.next_gate_after_approval,
+    allowed_after_approval: postApproval.allowed_after_approval,
+    quality_outlook: qualityOutlook,
+    status_card: buildStatusCard({
+      status,
+      currentGate,
+      allowed: gateDecision.allowed,
+      forbidden: gateDecision.forbidden,
+      blockingReason: gateDecision.blocking_reason,
+      missingApproval: gateDecision.missing_approval,
+      nextAllowedAction,
+      runState,
+      chatLanguage: resolveConfiguredChatLanguage(targetDir),
+      findings: map.findings,
+    }),
+    backlog_pointers: readBacklogPointers(targetDir),
+    artefacts: Object.fromEntries([...runState.artefacts.entries()]),
+    approvals: Object.fromEntries([...runState.approvals.entries()]),
+    mode_slice_decision: runState.mode_slice_decision,
+    relationships: map.relationships,
+    evidence_refs: runState.evidence_refs,
+    missing_evidence: map.missing_evidence,
+    risks: map.risks,
+    context_graph: map.context_graph,
+    source_scope: map.source_scope,
+    memory: map.memory,
+    parent_reconciliation: map.parent_reconciliation,
+    programme_aggregation: map.programme_aggregation,
+    findings: map.findings,
+    doctor_status: doctorReport.status,
+    doctor_summary: doctorReport.summary,
+    doctor_report: doctorReport,
+  };
+}
+
+export function printDeliveryMapReport(report, json, io = console) {
+  if (json) {
+    io.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  io.log(`AGDF delivery-map: ${report.status}`);
+  io.log(`Current gate: ${report.current_gate}`);
+  io.log(`Next allowed action: ${report.next_allowed_action}`);
+  io.log(`Quality outlook: ${report.quality_outlook}`);
+  io.log(`Relationships: ${report.relationships.filter((item) => item.status === "pass").length}/${report.relationships.length} evidenced`);
+  io.log(`Findings: ${report.findings.length}`);
+
+  for (const finding of report.findings) {
+    io.log("");
+    io.log(`[${finding.severity}] ${finding.code}`);
+    io.log(finding.message);
+    io.log(`Next step: ${finding.next_step}`);
+  }
+}