@williambeto/ai-workflow 1.19.1 → 2.2.0

package/src/commands/execute.js

@@ -0,0 +1,172 @@
+import { RequestClassifier } from "../core/request-classifier.js";
+import { ExecutionPlanner } from "../core/execution-planner.js";
+import { WorkflowStateMachine } from "../core/workflow-state-machine.js";
+import { BranchGate } from "../core/gates/branch-gate.js";
+import { OpenCodeAdapter } from "../core/runtime/opencode-adapter.js";
+import { runCollectEvidence } from "./collect-evidence.js";
+import { QualityGuard } from "../core/validation/quality-guard.js";
+import { HandoffEngine } from "../core/handoff/handoff-engine.js";
+import { HealerEngine } from "../core/healing/healer-engine.js";
+import { createCliRemediationExecutor } from "../core/healing/cli-remediation-executor.js";
+import { isRecoverableGateFailure, isTerminalFailure } from "../core/statuses.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32) || "task";
+}
+
+function combineValidation(evidence, quality) {
+  const statuses = [evidence.internalStatus, quality.overallStatus];
+  let overallStatus = "PASS";
+  if (statuses.includes("BLOCKED")) overallStatus = "BLOCKED";
+  else if (statuses.includes("FAIL")) overallStatus = "FAIL";
+  else if (statuses.includes("FAIL_DELEGATION_GATE")) overallStatus = "FAIL_DELEGATION_GATE";
+  else if (statuses.includes("FAIL_QUALITY_GATE")) overallStatus = "FAIL_QUALITY_GATE";
+  else if (statuses.includes("PASS_WITH_NOTES")) overallStatus = "PASS_WITH_NOTES";
+  return { overallStatus, evidence, quality };
+}
+
+/**
+ * runExecute - Coordinators natural request execution.
+ */
+export async function runExecute({ cwd, naturalRequest, override, taskSlug: taskSlugOverride }) {
+  if (!naturalRequest || !naturalRequest.trim()) {
+    throw new Error("Missing request. Please provide a natural request string via positional arguments or --request flag.");
+  }
+
+  const taskSlug = taskSlugOverride || slugify(naturalRequest);
+  console.log(`\n[AI WORKFLOW] Executing natural request intake [slug: ${taskSlug}]...\n`);
+
+  const stateMachine = new WorkflowStateMachine();
+
+  // 1. Classification
+  const classifier = new RequestClassifier();
+  const classification = classifier.classify(naturalRequest);
+  console.log(`[CLASSIFIED] Intent: ${classification.intent}, Mode: ${classification.mode}, Profile: ${classification.profile}`);
+  stateMachine.transitionTo("CLASSIFIED");
+
+  // 2. Planning
+  const planner = new ExecutionPlanner({ cwd });
+  const plan = planner.plan(classification, taskSlug);
+  console.log(`[PLANNED] Owner: ${plan.owner}, Remediation limit: ${plan.remediationLimit}`);
+  stateMachine.transitionTo("PLANNED");
+
+  // 3. Branch Gate
+  const branchGate = new BranchGate({ memoryDir: path.join(cwd, ".ai-workflow"), cwd });
+  const gateResult = branchGate.check(override, {
+    autoRecover: true,
+    taskSlug,
+    readOnly: !plan.branchNeeded
+  });
+
+  if (gateResult.blocked) {
+    stateMachine.transitionTo("BLOCKED");
+    throw new Error(`[GATE BLOCKED] ${gateResult.reason}`);
+  }
+  console.log(`[PASS] Branch Gate: ${gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : `${gateResult.branch} is authorized`}.`);
+  stateMachine.transitionTo("BRANCH_READY");
+
+  // 4. Spec template creation (for full/deep mode)
+  if (plan.specPath) {
+    const fullSpecPath = path.join(cwd, plan.specPath);
+    const specExists = await fs.access(fullSpecPath).then(() => true).catch(() => false);
+    if (!specExists) {
+      await fs.mkdir(path.dirname(fullSpecPath), { recursive: true });
+      const specTemplatePath = path.join(cwd, ".ai-workflow/templates/specs/standard.md");
+      const templateContent = await fs.readFile(specTemplatePath, "utf8").catch(() => {
+        return `# [STANDARD] Specification: ${classification.request}\n\n## Metadata\n\n- ID: SPEC-${taskSlug}\n- Author: Spec-Engineer\n- Status: DRAFT\n- Date: ${new Date().toISOString().split("T")[0]}\n\n## Functional Requirements\n\n- ${classification.request}\n\n## Technical Implementation Plan\n\n### Files to Create/Modify\n\n- \`src/index.js\`\n\n## Acceptance Criteria\n\n- [ ] Implemented successfully\n\n## Testing Strategy\n\n- [ ] Behavior tests pass`;
+      });
+      await fs.writeFile(fullSpecPath, templateContent);
+      console.log(`[EXECUTE] Created DRAFT specification template at: ${plan.specPath}`);
+    }
+  }
+
+  // 5. Delegation
+  stateMachine.transitionTo("DELEGATED");
+  stateMachine.transitionTo("IMPLEMENTING");
+
+  const adapter = new OpenCodeAdapter({ cwd });
+  let promptMsg = classification.request;
+  if (plan.specPath) {
+    promptMsg = `Please review and fill in the specification file at: ${plan.specPath}. Make sure to change the Status field to 'APPROVED' in the Metadata section, and then implement the behavior described.`;
+  }
+
+  const runResult = await adapter.execute(promptMsg, {
+    agent: plan.owner,
+    dangerouslySkipPermissions: true
+  });
+
+  if (!runResult.success) {
+    console.error(`[EXECUTE] OpenCode adapter execution reported failure.`);
+  }
+  stateMachine.transitionTo("IMPLEMENTED");
+
+  // 6. Validation
+  stateMachine.transitionTo("VALIDATING");
+  const validateWorkflow = async () => {
+    const evidence = await runCollectEvidence({
+      cwd,
+      exitOnError: false,
+      taskSlug,
+      mode: plan.mode,
+      profile: plan.profile,
+      branchRecovery: gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : "NOT_REQUIRED"
+    });
+    const quality = await new QualityGuard({ cwd, taskSlug, mode: plan.mode }).verify();
+    return combineValidation(evidence, quality);
+  };
+
+  let result = await validateWorkflow();
+
+  // 7. Bounded Remediation
+  if (isRecoverableGateFailure(result.overallStatus)) {
+    stateMachine.transitionTo("REMEDIATING");
+    console.log(`\n[REMEDIATION REQUIRED] ${result.overallStatus}. Starting bounded ${plan.mode} remediation.`);
+    const executor = createCliRemediationExecutor(cwd);
+    const healer = new HealerEngine({ cwd, mode: plan.mode, taskSlug });
+    
+    result = await healer.run({
+      initialResult: result,
+      validate: async () => {
+        stateMachine.transitionTo("REVALIDATING");
+        const res = await validateWorkflow();
+        return res;
+      },
+      remediate: executor
+    });
+  }
+
+  if (isTerminalFailure(result.overallStatus)) {
+    stateMachine.transitionTo("BLOCKED");
+    throw new Error(`[WORKFLOW BLOCKED] ${result.overallStatus}: Validation could not be resolved safely.`);
+  }
+
+  // 8. Finalizer
+  const finalState = result.overallStatus === "PASS"
+    ? "COMPLETED"
+    : result.overallStatus === "PASS_WITH_NOTES"
+      ? "COMPLETED_WITH_NOTES"
+      : "BLOCKED";
+
+  stateMachine.transitionTo(finalState);
+
+  console.log("\n--- Final Handoff ---");
+  const handoffEngine = new HandoffEngine({ cwd });
+  const handoffPath = await handoffEngine.generate({
+    taskId: taskSlug,
+    status: finalState,
+    specPaths: plan.specPath ? [plan.specPath] : [],
+    evidence: result.evidence,
+    nextActions: `Profile ${plan.profile}. Observed execution completed with status ${finalState}.`
+  });
+
+  console.log(`\n[AI WORKFLOW COMPLETE] ${finalState}`);
+  console.log(`Handoff Packet: ${path.relative(cwd, handoffPath)}\n`);
+
+  return { ...result, stateHistory: stateMachine.getHistory() };
+}

package/{packages/ai-workflow/src → src}/commands/init.js

@@ -2,10 +2,11 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { createInstallPlan } from "../core/install-plan.js";
 import { buildAiWorkflowConfig, getTemplateFiles, isValidProfile } from "../core/templates.js";
-import { exists, writeFileSafe } from "../core/filesystem.js";
+import { exists, writeFileSafe, readJson } from "../core/filesystem.js";
 import { createManagedBackup, createManagedPathBackup } from "../core/backup.js";
 import { mergeOpencodeConfig } from "../core/opencode-merge.js";
-import { buildSymlinkEntries, isSymlinkTo } from "../core/symlink-layout.js";
+import { buildSymlinkEntries, isSymlinkTo, setupInternalSymlinks } from "../core/symlink-layout.js";
+import { GeminiAdapter, ClaudeAdapter, CodexAdapter } from "../adapters/index.js";
 
 function summarize(actions) {
   const createCount = actions.filter((a) => a.type === "create").length;
@@ -79,16 +80,63 @@ async function upsertGitignoreBlock(cwd, entries) {
   return "updated";
 }
 
-export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite, profile }) {
-  const selectedProfile = profile ?? "full";
-  const installRoot = ".ai-workflow";
+async function injectScripts(cwd) {
+  const pkgPath = path.join(cwd, "package.json");
+  if (!(await exists(pkgPath))) return;
+
+  try {
+    const pkg = await readJson(pkgPath);
+    if (!pkg.scripts) pkg.scripts = {};
+
+    if (!pkg.scripts.validate) {
+      pkg.scripts.validate = "ai-workflow collect-evidence";
+      await writeFileSafe(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+      return true;
+    }
+  } catch {
+    // Ignore invalid package.json
+  }
+  return false;
+}
+
+export async function runInit({
+ cwd, yes, force, dryRun, noInstall, noOverwrite, gemini, claude, codex, "dev-mode": devMode, profile }) {
+  // Self-execution guard
+  if (!devMode) {
+    try {
+      const pkgPath = path.join(cwd, "package.json");
+      if (await exists(pkgPath)) {
+        const pkg = await readJson(pkgPath);
+        if (pkg.name === "@williambeto/ai-workflow") {
+          console.error("\nFATAL: Cannot run 'ai-workflow init' inside its own development repository.");
+          console.error("This would corrupt the development environment. Aborting.");
+          console.error("Use the --dev-mode flag if you are developing the kit itself and need to test the init command.\n");
+          process.exit(1);
+        }
+      }
+    } catch {
+      // Ignore if package.json is unreadable. The guard is a safety net.
+    }
+  }
+
+  const selectedProfile = profile || "standard";
 
   if (!isValidProfile(selectedProfile)) {
-    throw new Error(`invalid profile: ${selectedProfile}. Use minimal, operational, or full.`);
+    console.error(`Invalid profile: "${selectedProfile}". Valid profiles: standard, full`);
+    process.exit(1);
   }
+  const installRoot = ".ai-workflow";
+
+  const platforms = [];
+  if (gemini) platforms.push("gemini");
+  if (claude) platforms.push("claude");
+  if (codex) platforms.push("codex");
 
   console.log(`ai-workflow: initializing in ${cwd}`);
   console.log(`Profile: ${selectedProfile}`);
+  if (platforms.length > 0) {
+    console.log(`Platforms: ${platforms.join(", ")}`);
+  }
 
   const actions = await createInstallPlan({ cwd, exists, profile: selectedProfile });
   const linkEntries = buildSymlinkEntries({ templateFiles: getTemplateFiles(selectedProfile), installRoot });
@@ -105,6 +153,9 @@ export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite,
 
   if (dryRun) {
     console.log("Dry-run enabled. No files were written.");
+    if (platforms.length > 0) {
+      console.log("ai-workflow: (dry-run) platform migration would be executed after file writing.");
+    }
     return;
   }
 
@@ -128,17 +179,10 @@ export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite,
     }
 
     const content =
-      action.relativePath === ".ai-workflow.json"
+      action.relativePath === ".ai-workflow/config.json"
         ? `${JSON.stringify(
             buildAiWorkflowConfig({
-              profile: selectedProfile,
-              managedFiles: Array.from(
-                new Set([
-                  ...Object.keys(getTemplateFiles(selectedProfile)).map((p) => path.join(installRoot, p)),
-                  ".ai-workflow.json"
-                ])
-              ),
-              managedLinks: linkEntries.map((entry) => entry.linkPath)
+              profile: selectedProfile
             }),
             null,
             2
@@ -175,6 +219,8 @@ export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite,
         maxPerFile: 20
       });
       linkBackups.push(backupPath);
+      // Ensure we remove the old path before symlinking if it's not already handled by backup
+      await fs.rm(absoluteLinkPath, { recursive: true, force: true });
     }
 
     const stat = await fs.lstat(absoluteTargetPath);
@@ -182,6 +228,7 @@ export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite,
     const linkTarget = process.platform === "win32" ? absoluteTargetPath : path.relative(path.dirname(absoluteLinkPath), absoluteTargetPath);
 
     try {
+      await fs.mkdir(path.dirname(absoluteLinkPath), { recursive: true });
       await fs.symlink(linkTarget, absoluteLinkPath, type);
     } catch (error) {
       throw new Error(
@@ -193,25 +240,77 @@ export async function runInit({ cwd, yes, force, dryRun, noInstall, noOverwrite,
     linkCreated.push(linkPath);
   }
 
-  const opencodeResult =
-    selectedProfile === "minimal"
-      ? { reason: "skipped (minimal profile)" }
-      : await mergeOpencodeConfig(cwd, { force, backupRoot, profile: selectedProfile });
+  await setupInternalSymlinks(cwd, installRoot);
+
+  const opencodeResult = await mergeOpencodeConfig(cwd, { force, backupRoot });
 
   const generatedIgnoreEntries = [
     ".ai-workflow/",
-    ".ai-workflow.json",
     ".ai-workflow-backups/",
+    "opencode.jsonc.backup.*",
     ...linkEntries.flatMap((entry) => toIgnoreEntries(entry.linkPath))
   ];
 
+  if (gemini) {
+    generatedIgnoreEntries.push(".gemini/");
+  }
+  if (codex) {
+    generatedIgnoreEntries.push(".agents/", ".codex/");
+  }
+  if (claude) {
+    generatedIgnoreEntries.push(".claude/");
+  }
+
   const gitignoreResult = await upsertGitignoreBlock(cwd, generatedIgnoreEntries);
+  const scriptInjected = await injectScripts(cwd);
+
+  if (platforms.length > 0) {
+    console.log("ai-workflow: migrating to native platforms...");
+    const agentsDir = path.join(cwd, installRoot, "opencode/agents");
+    const skillsDir = path.join(cwd, installRoot, "opencode/skills");
+
+    const agentFiles = (await fs.readdir(agentsDir).catch(() => []))
+      .filter((f) => f.endsWith(".md"))
+      .map((f) => path.join(agentsDir, f));
+
+    if (gemini) {
+      const adapter = new GeminiAdapter({ cwd });
+      
+      // Collect specialized skills from the new opencode/skills path
+      const skillFolders = await fs.readdir(skillsDir).catch(() => []);
+      const skillFiles = [];
+      for (const folder of skillFolders) {
+        const skillPath = path.join(skillsDir, folder, "SKILL.md");
+        if (await exists(skillPath)) {
+          skillFiles.push(skillPath);
+        }
+      }
+
+      const allFiles = [...agentFiles, ...skillFiles];
+      const transformed = await Promise.all(allFiles.map((f) => adapter.transform(f)));
+      await adapter.deploy(transformed, installRoot);
+      console.log(`- gemini: deployed AI Workflow Kit agents to .gemini/ (native discovery enabled)`);
+    }
+
+    if (claude) {
+      const adapter = new ClaudeAdapter({ cwd });
+      await adapter.deploy(installRoot);
+      console.log("- claude: deployed AI Workflow Kit agents to CLAUDE.md and .claude/rules/ (native discovery enabled)");
+    }
+
+    if (codex) {
+      const adapter = new CodexAdapter({ cwd });
+      await adapter.deploy(installRoot);
+      console.log("- codex: deployed AI Workflow Kit agents to .agents/, .codex/, and .github/ (native discovery enabled)");
+    }
+  }
 
   console.log("Installation complete.");
   console.log(`- profile: ${selectedProfile}`);
 
   console.log(`- opencode.jsonc: ${opencodeResult.reason}`);
   console.log(`- .gitignore: ${gitignoreResult}`);
+  console.log(`- scripts: ${scriptInjected ? "injected 'validate'" : "already-up-to-date"}`);
   console.log(`- symlink layout: ${linkCreated.length > 0 ? `created ${linkCreated.length}` : "already-up-to-date"}`);
   if (backups.length > 0) {
     console.log(`- backups created: ${backups.length}`);

package/src/commands/run.js

@@ -0,0 +1,112 @@
+import { BranchGate } from "../core/gates/branch-gate.js";
+import { SpecValidator } from "../core/sdd/validator.js";
+import { HandoffEngine } from "../core/handoff/handoff-engine.js";
+import { runCollectEvidence } from "./collect-evidence.js";
+import { QualityGuard } from "../core/validation/quality-guard.js";
+import { HealerEngine } from "../core/healing/healer-engine.js";
+import { createCliRemediationExecutor } from "../core/healing/cli-remediation-executor.js";
+import { isRecoverableGateFailure, isTerminalFailure } from "../core/statuses.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { getWorkflowProfile, resolveWorkflowProfile } from "../core/workflow-profiles.js";
+
+function normalizeTaskSlugFromSpec(specPath) {
+  const normalized = String(specPath).replaceAll("\\", "/");
+  const marker = "/docs/workflows/";
+  const index = normalized.includes(marker)
+    ? normalized.indexOf(marker) + marker.length
+    : normalized.startsWith("docs/workflows/") ? "docs/workflows/".length : -1;
+  if (index >= 0) {
+    const slug = normalized.slice(index).split("/")[0];
+    if (slug) return slug;
+  }
+  return path.basename(specPath, path.extname(specPath));
+}
+
+function combineValidation(evidence, quality) {
+  const statuses = [evidence.internalStatus, quality.overallStatus];
+  let overallStatus = "PASS";
+  if (statuses.includes("BLOCKED")) overallStatus = "BLOCKED";
+  else if (statuses.includes("FAIL")) overallStatus = "FAIL";
+  else if (statuses.includes("FAIL_DELEGATION_GATE")) overallStatus = "FAIL_DELEGATION_GATE";
+  else if (statuses.includes("FAIL_QUALITY_GATE")) overallStatus = "FAIL_QUALITY_GATE";
+  else if (statuses.includes("PASS_WITH_NOTES")) overallStatus = "PASS_WITH_NOTES";
+  return { overallStatus, evidence, quality };
+}
+
+/**
+ * Coordinates branch safety, specification validation, observed validation, bounded remediation, and handoff.
+ * Failed required validation can never be promoted to success.
+ */
+export async function runMasterOrchestrator({ cwd, specPath, override, remediationExecutor = null }) {
+  console.log("\n[AI WORKFLOW] Starting evidence-backed orchestration...\n");
+
+  const branchGate = new BranchGate({ memoryDir: path.join(cwd, ".ai-workflow"), cwd });
+  const taskSlug = specPath ? normalizeTaskSlugFromSpec(specPath) : "implementation";
+  const gateResult = branchGate.check(override, { autoRecover: true, taskSlug });
+  if (gateResult.blocked) throw new Error(`[GATE BLOCKED] ${gateResult.reason}`);
+  console.log(`[PASS] Branch Gate: ${gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : `${gateResult.branch} is authorized`}.`);
+
+  if (!specPath) throw new Error("[SDD BLOCKED] Missing --spec-path. An approved specification is required.");
+
+  const validator = new SpecValidator();
+  const absoluteSpecPath = path.isAbsolute(specPath) ? specPath : path.join(cwd, specPath);
+  const validation = await validator.validate(absoluteSpecPath);
+  if (!validation.valid) throw new Error(`[SDD BLOCKED] Specification is not ready: ${validation.reason}`);
+
+  const executionMode = validation.tier === "deep" ? "full" : validation.tier === "tiny" ? "quick" : "standard";
+  const specContent = await fs.readFile(absoluteSpecPath, "utf8");
+  const workflowProfile = resolveWorkflowProfile({ request: specContent });
+  const profileDefinition = getWorkflowProfile(workflowProfile);
+  console.log(`[PASS] Specification: ${validation.tier.toUpperCase()} spec is APPROVED.`);
+  console.log(`[PROFILE] ${workflowProfile} -> ${profileDefinition.owner}; skills: ${profileDefinition.skills.join(", ") || "none"}.`);
+
+  const validateWorkflow = async () => {
+    const evidence = await runCollectEvidence({
+      cwd,
+      exitOnError: false,
+      taskSlug,
+      mode: executionMode,
+      profile: workflowProfile,
+      branchRecovery: gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : "NOT_REQUIRED"
+    });
+    const quality = await new QualityGuard({ cwd, taskSlug, mode: executionMode }).verify();
+    return combineValidation(evidence, quality);
+  };
+
+  let result = await validateWorkflow();
+  if (isRecoverableGateFailure(result.overallStatus)) {
+    console.log(`\n[REMEDIATION REQUIRED] ${result.overallStatus}. Starting bounded ${executionMode} remediation.`);
+    // Use the provided executor (programmatic API) or fall back to the default CLI executor.
+    // The CLI executor re-runs failed npm scripts; it does not modify source code.
+    const executor = typeof remediationExecutor === "function"
+      ? remediationExecutor
+      : createCliRemediationExecutor(cwd);
+    const healer = new HealerEngine({ cwd, mode: executionMode, taskSlug });
+    result = await healer.run({ initialResult: result, validate: validateWorkflow, remediate: executor });
+  }
+
+  if (isTerminalFailure(result.overallStatus)) {
+    throw new Error(`[WORKFLOW BLOCKED] ${result.overallStatus}: ${result.reason || "Validation could not be resolved safely."}`);
+  }
+  if (isRecoverableGateFailure(result.overallStatus)) {
+    throw new Error(`[WORKFLOW BLOCKED] Unresolved gate status after remediation: ${result.overallStatus}`);
+  }
+
+  console.log("\n--- Final Handoff ---");
+  const handoffEngine = new HandoffEngine({ cwd });
+  const handoffPath = await handoffEngine.generate({
+    taskId: path.basename(specPath, ".md"),
+    status: result.overallStatus,
+    specPaths: [specPath],
+    evidence: result.evidence,
+    nextActions: `Profile ${workflowProfile}. Observed validation completed. Ready for review or explicitly approved release actions.`
+  });
+
+  console.log(`\n[AI WORKFLOW COMPLETE] ${result.overallStatus}`);
+  if (result.remediation?.attempts) console.log(`Remediation attempts: ${result.remediation.attempts}`);
+  console.log(`Handoff Packet: ${path.relative(cwd, handoffPath)}\n`);
+  return { ...result, workflowProfile };
+}
+
+export { combineValidation };

package/src/core/completion-contract.js

@@ -0,0 +1,35 @@
+/**
+ * Evaluates objective owner-output completeness. It does not judge visual taste.
+ * A caller may resume the same owner once; a second incomplete result must block.
+ */
+export function evaluateOwnerCompletion({
+  expectedFiles = [],
+  existingFiles = [],
+  validation = {},
+  ownerReportComplete = false,
+  resumeCount = 0
+} = {}) {
+  const existing = new Set(existingFiles);
+  const missingFiles = expectedFiles.filter((file) => !existing.has(file));
+  const missingValidation = Object.entries(validation)
+    .filter(([, value]) => value === "REQUIRED" || value === false)
+    .map(([key]) => key);
+  const missing = [
+    ...missingFiles.map((file) => `file:${file}`),
+    ...missingValidation.map((check) => `validation:${check}`),
+    ...(!ownerReportComplete ? ["owner-report"] : [])
+  ];
+
+  if (missing.length === 0) {
+    return { status: "PASS", action: "continue", missing: [] };
+  }
+  if (resumeCount < 1) {
+    return { status: "INCOMPLETE", action: "resume-same-owner", missing };
+  }
+  return {
+    status: "BLOCKED",
+    action: "stop",
+    reason: "Owner output remained incomplete after one resume",
+    missing
+  };
+}

package/src/core/execution-planner.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+
+/**
+ * ExecutionPlanner - Formulates a minimum operational plan based on classification.
+ */
+export class ExecutionPlanner {
+  constructor({ cwd = process.cwd() } = {}) {
+    this.cwd = cwd;
+  }
+
+  /**
+   * Generates an execution plan.
+   * @param {Object} classification - The output of RequestClassifier.
+   * @param {string} taskSlug - Descriptive slug for the task.
+   * @returns {Object} Operational plan contract.
+   */
+  plan(classification, taskSlug = "task") {
+    const remediationLimit = classification.mode === "full" ? 3 : classification.mode === "quick" ? 1 : 2;
+    const branchNeeded = classification.intent === "write";
+    const specPath = classification.specNeeded
+      ? path.join("docs/workflows", taskSlug, "spec.md")
+      : null;
+
+    // Build default expected validations based on the resolved profile
+    const validationsExpected = [];
+    if (classification.validationNeeded) {
+      validationsExpected.push("test");
+      if (classification.profile.startsWith("frontend")) {
+        validationsExpected.push("lint", "build");
+      } else if (classification.profile === "backend-api") {
+        validationsExpected.push("lint");
+      }
+    }
+
+    const restrictions = [
+      "Never commit or push directly to main/master.",
+      "Always execute behavior tests for new or modified behavior."
+    ];
+
+    if (classification.risk === "high") {
+      restrictions.push("Require independent validation review.");
+    }
+
+    return {
+      objective: classification.request,
+      scope: classification.intent === "read-only" ? "Analysis and verification" : "Implementation of requested behavior",
+      restrictions,
+      owner: classification.owner,
+      skills: [...classification.skills],
+      branchNeeded,
+      branchName: branchNeeded ? `feat/${taskSlug}` : null,
+      validationsExpected,
+      remediationLimit,
+      specPath,
+      mode: classification.mode,
+      profile: classification.profile
+    };
+  }
+}