@structured-vibe-coding/core 0.5.2 → 0.5.4

package/dist/index.js

@@ -1,4 +1,5 @@
 import {
+  AGENT_INTEGRATIONS,
   AGENT_TARGET_OPTIONS,
   ALL_AGENT_TARGETS,
   ArtifactDefSchema,
@@ -14,29 +15,26 @@ import {
   WorkflowSchema,
   activePointerPath,
   activeStages,
-  advanceStage,
-  approveGate,
   archiveDir,
   buildAgentPrompt,
   buildContext,
-  canLeaveStage,
   changeDirName,
   changeMetaPath,
   changePath,
   changesDir,
   clearActiveIf,
-  completeChange,
   configPath,
   copyDir,
-  createChange,
   defaultConfig,
   domainsDir,
   ensureDir,
   firstActiveStageId,
   formatStatus,
   getActiveChangeId,
+  getIntegration,
   getStage,
   inferComplexity,
+  installAgentIntegration,
   installAgentIntegrations,
   integrationKeyFor,
   isInitialized,
@@ -68,32 +66,367 @@ import {
   sddRoot,
   setActiveChange,
   shouldAutoSkip,
-  skipStage,
   slugify,
-  switchWorkflow,
   templatesDir,
   todayIsoDate,
   uniqueChangeDirName,
   workflowsDir,
   writeText,
   writeYaml
-} from "./chunk-IO6AS6JI.js";
+} from "./chunk-I45MAHM6.js";
 
-// src/init.ts
+// src/change.ts
 import { join as join2 } from "pathe";
 
+// src/stage-gates.ts
+import { join } from "pathe";
+async function canLeaveStage(ctx, config) {
+  const stage = getStage(ctx.workflow, ctx.meta, ctx.meta.stage);
+  const errors = [];
+  const warnings = [];
+  if (!stage) {
+    return { ok: false, errors: [`Unknown stage: ${ctx.meta.stage}`], warnings };
+  }
+  for (const artifact of stage.artifacts) {
+    if (!artifact.required) continue;
+    const target = join(ctx.path, artifact.path);
+    if (!await pathExists(target)) {
+      errors.push(`Missing required artifact: ${artifact.path}`);
+    }
+  }
+  const declared = stage.gate?.type ?? "soft";
+  let effectiveGate = declared;
+  if (config.policy.gates === "hard" && declared === "soft") {
+    effectiveGate = "hard";
+  }
+  const gateState = ctx.meta.gates?.[stage.id];
+  if (effectiveGate === "hard") {
+    if (!gateState || gateState.status !== "approved" && gateState.status !== "waived") {
+      errors.push(
+        `Hard gate on stage "${stage.id}" is not approved. Run \`sdd gate approve\` or complete the checklist.`
+      );
+    }
+  } else if (effectiveGate === "soft" && stage.gate?.checklist?.length) {
+    if (!gateState || gateState.status === "pending") {
+      warnings.push(
+        `Soft gate checklist not signed off on "${stage.id}" (proceeding allowed).`
+      );
+    }
+  }
+  const requiredCmds = stage.verify?.commands?.filter((c) => c.required) ?? [];
+  if (requiredCmds.length) {
+    const verifyOk = ctx.meta.verify_results?.[stage.id]?.ok === true;
+    const humanOverride = gateState?.status === "waived" || gateState?.status === "approved";
+    if (!verifyOk && !humanOverride) {
+      errors.push(
+        `Required local verify commands have not passed for "${stage.id}". Run \`sdd verify\` (or \`sdd gate approve/waive\` with a note).`
+      );
+    } else if (!verifyOk && humanOverride) {
+      warnings.push(
+        `Stage "${stage.id}" gate signed off without a successful required verify run.`
+      );
+    }
+  }
+  return { ok: errors.length === 0, errors, warnings };
+}
+async function approveGate(projectRoot, config, changeId, stageId, note, status = "approved") {
+  const ctx = await buildContext(projectRoot, config, changeId);
+  const id = stageId ?? ctx.meta.stage;
+  ctx.meta.gates = {
+    ...ctx.meta.gates,
+    [id]: { status, note, at: nowIso() }
+  };
+  await saveChangeMeta(projectRoot, config, ctx.meta);
+  return buildContext(projectRoot, config, changeId);
+}
+
+// src/change.ts
+async function existingChangeIds(projectRoot, config) {
+  const open = await listDirs(changesDir(projectRoot, config));
+  const archived = await listDirs(archiveDir(projectRoot, config));
+  return /* @__PURE__ */ new Set([...open, ...archived]);
+}
+async function createChange(input) {
+  const { projectRoot, config, title, workflowName } = input;
+  const workflow = await loadWorkflow(projectRoot, workflowName);
+  if (!workflow.stages.length) {
+    throw new Error(`Workflow ${workflowName} has no stages`);
+  }
+  const baseId = changeDirName(title);
+  const id = uniqueChangeDirName(baseId, await existingChangeIds(projectRoot, config));
+  const dir = changePath(projectRoot, config, id);
+  await ensureDir(dir);
+  let meta = ChangeMetaSchema.parse({
+    id,
+    title,
+    workflow: workflowName,
+    created: nowIso(),
+    updated: nowIso(),
+    status: "in_progress",
+    stage: workflow.stages[0].id,
+    domain: input.domain,
+    branch: input.branch,
+    flags: input.flags ?? {},
+    overrides: {
+      skip_stages: [],
+      gates: {},
+      extra_stages: []
+    },
+    skipped: [],
+    gates: {}
+  });
+  const startId = firstActiveStageId(workflow, meta) ?? workflow.stages[0].id;
+  meta = { ...meta, stage: startId };
+  const firstStage = getStage(workflow, meta, startId);
+  if (!firstStage) {
+    throw new Error(`Workflow ${workflowName} has no active stages`);
+  }
+  await writeYaml(changeMetaPath(projectRoot, config, id), meta);
+  await materializeStageArtifacts(projectRoot, config, id, workflow, meta, firstStage);
+  await setActiveChange(projectRoot, config, id);
+  try {
+    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-4Z3YZRUK.js");
+    await refreshActiveAgentContext2(projectRoot);
+  } catch {
+  }
+  return buildContext(projectRoot, config, id);
+}
+async function materializeStageArtifacts(projectRoot, config, changeId, workflow, meta, stage) {
+  const created = [];
+  const dir = changePath(projectRoot, config, changeId);
+  const tdir = templatesDir(projectRoot);
+  for (const artifact of stage.artifacts) {
+    const target = join2(dir, artifact.path);
+    if (await pathExists(target)) continue;
+    if (artifact.path.endsWith("/")) {
+      await ensureDir(target);
+      created.push(artifact.path);
+      continue;
+    }
+    let content = defaultArtifactContent(artifact.id, meta, stage, workflow);
+    if (artifact.template) {
+      const templatePath = join2(tdir, artifact.template.replace(/^templates\//, ""));
+      const candidates = [
+        join2(tdir, artifact.template),
+        templatePath,
+        join2(tdir, `${artifact.id}.md`)
+      ];
+      for (const c of candidates) {
+        if (await pathExists(c)) {
+          content = interpolate(await readText(c), meta, stage, workflow);
+          break;
+        }
+      }
+    } else {
+      const fallback = join2(tdir, `${artifact.id}.md`);
+      if (await pathExists(fallback)) {
+        content = interpolate(await readText(fallback), meta, stage, workflow);
+      }
+    }
+    await writeText(target, content);
+    created.push(artifact.path);
+  }
+  return created;
+}
+function interpolate(template, meta, stage, workflow) {
+  return template.replaceAll("{{title}}", meta.title).replaceAll("{{id}}", meta.id).replaceAll("{{workflow}}", workflow.name).replaceAll("{{stage}}", stage.id).replaceAll("{{stage_title}}", stage.title ?? stage.id).replaceAll("{{date}}", meta.created.slice(0, 10));
+}
+function defaultArtifactContent(artifactId, meta, stage, workflow) {
+  return `# ${artifactId}
+
+> Change: **${meta.title}** (\`${meta.id}\`)  
+> Workflow: \`${workflow.name}\` \xB7 Stage: \`${stage.id}\`
+
+## Summary
+
+<!-- Write the intent / content for this artifact -->
+
+## Notes
+
+-
+`;
+}
+async function advanceStage(projectRoot, config, changeId, opts) {
+  const ctx = await buildContext(projectRoot, config, changeId);
+  const warnings = [];
+  if (ctx.meta.status === "completed") {
+    throw new Error("Change is already completed.");
+  }
+  const check = await canLeaveStage(ctx, config);
+  warnings.push(...check.warnings);
+  if (!check.ok && !opts?.force) {
+    throw new Error(check.errors.join("\n"));
+  }
+  const from = ctx.meta.stage;
+  const next = nextStageId(ctx.workflow, ctx.meta);
+  if (!next) {
+    return {
+      ctx,
+      from,
+      to: null,
+      completed: false,
+      artifactsCreated: [],
+      warnings: [...warnings, "No further stages. Run `sdd complete` when ready."]
+    };
+  }
+  ctx.meta.stage = next;
+  await saveChangeMeta(projectRoot, config, ctx.meta);
+  const stage = getStage(ctx.workflow, ctx.meta, next);
+  const artifactsCreated = await materializeStageArtifacts(
+    projectRoot,
+    config,
+    changeId,
+    ctx.workflow,
+    ctx.meta,
+    stage
+  );
+  try {
+    const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-4Z3YZRUK.js");
+    await refreshActiveAgentContext2(projectRoot);
+  } catch {
+  }
+  const updated = await buildContext(projectRoot, config, changeId);
+  return {
+    ctx: updated,
+    from,
+    to: next,
+    completed: false,
+    artifactsCreated,
+    warnings
+  };
+}
+async function skipStage(projectRoot, config, changeId, stageId, reason) {
+  if (!config.per_change.allow_skip) {
+    throw new Error("Skipping stages is disabled in .sdd/config.yaml (per_change.allow_skip).");
+  }
+  if (config.per_change.require_reason_on_skip && !reason.trim()) {
+    throw new Error("A reason is required to skip a stage.");
+  }
+  const ctx = await buildContext(projectRoot, config, changeId);
+  const stage = getStage(ctx.workflow, ctx.meta, stageId);
+  if (!stage) {
+    throw new Error(`Stage "${stageId}" not found in workflow ${ctx.meta.workflow}`);
+  }
+  if (!stage.skippable) {
+    throw new Error(`Stage "${stageId}" is not skippable.`);
+  }
+  const skip_stages = new Set(ctx.meta.overrides.skip_stages ?? []);
+  skip_stages.add(stageId);
+  ctx.meta.overrides.skip_stages = [...skip_stages];
+  ctx.meta.skipped = [
+    ...ctx.meta.skipped ?? [],
+    { stage: stageId, reason, at: nowIso() }
+  ];
+  if (ctx.meta.stage === stageId) {
+    const next = nextStageId(ctx.workflow, ctx.meta);
+    if (next) {
+      ctx.meta.stage = next;
+      const nextStage = getStage(ctx.workflow, ctx.meta, next);
+      if (nextStage) {
+        await materializeStageArtifacts(
+          projectRoot,
+          config,
+          changeId,
+          ctx.workflow,
+          ctx.meta,
+          nextStage
+        );
+      }
+    }
+  }
+  await saveChangeMeta(projectRoot, config, ctx.meta);
+  return buildContext(projectRoot, config, changeId);
+}
+async function switchWorkflow(projectRoot, config, changeId, workflowName, reason) {
+  const ctx = await buildContext(projectRoot, config, changeId);
+  const workflow = await loadWorkflow(projectRoot, workflowName);
+  if (config.allowed_workflows?.length && !config.allowed_workflows.includes(workflowName)) {
+    throw new Error(
+      `Workflow "${workflowName}" is not in allowed_workflows: ${config.allowed_workflows.join(", ")}`
+    );
+  }
+  ctx.meta.workflow = workflowName;
+  const hasStage = workflow.stages.some((s) => s.id === ctx.meta.stage);
+  if (!hasStage) {
+    ctx.meta.stage = workflow.stages[0].id;
+  }
+  if (reason) {
+    ctx.meta.flags = {
+      ...ctx.meta.flags,
+      workflow_switch_reason: reason
+    };
+  }
+  await saveChangeMeta(projectRoot, config, ctx.meta);
+  const stage = getStage(workflow, ctx.meta, ctx.meta.stage);
+  if (stage) {
+    await materializeStageArtifacts(projectRoot, config, changeId, workflow, ctx.meta, stage);
+  }
+  return buildContext(projectRoot, config, changeId);
+}
+async function completeChange(projectRoot, config, changeId) {
+  const ctx = await buildContext(projectRoot, config, changeId);
+  const next = nextStageId(ctx.workflow, ctx.meta);
+  if (next) {
+    const active = activeStages(ctx.workflow, ctx.meta);
+    const last = active[active.length - 1];
+    if (last && ctx.meta.stage !== last.id) {
+      throw new Error(
+        `Cannot complete: still on stage "${ctx.meta.stage}". Finish remaining stages or skip them. Next: ${next}`
+      );
+    }
+  }
+  const check = await canLeaveStage(ctx, config);
+  if (!check.ok) {
+    throw new Error(check.errors.join("\n"));
+  }
+  ctx.meta.status = "completed";
+  ctx.meta.completed_at = nowIso();
+  await saveChangeMeta(projectRoot, config, ctx.meta);
+  await clearActiveIf(projectRoot, config, changeId);
+  let archivedTo = null;
+  const shouldArchive = config.persistence.archive_on_complete && ctx.workflow.on_complete?.archive !== false;
+  if (shouldArchive) {
+    const dest = join2(archiveDir(projectRoot, config), changeId);
+    if (await pathExists(dest)) {
+      throw new Error(`Archive already exists for change: ${changeId}`);
+    }
+    await ensureDir(archiveDir(projectRoot, config));
+    await copyDir(ctx.path, dest);
+    await removePath(ctx.path);
+    archivedTo = dest;
+  }
+  if (archivedTo) {
+    const meta = ChangeMetaSchema.parse(await readYaml(join2(archivedTo, "meta.yaml")));
+    return {
+      archivedTo,
+      ctx: {
+        id: changeId,
+        path: archivedTo,
+        meta,
+        workflow: ctx.workflow,
+        stages: ctx.stages,
+        active: ctx.active
+      }
+    };
+  }
+  return { archivedTo, ctx: await buildContext(projectRoot, config, changeId) };
+}
+
+// src/init.ts
+import { join as join4 } from "pathe";
+
 // src/defaults.ts
 import { existsSync } from "fs";
 import { fileURLToPath } from "url";
-import { dirname, join } from "pathe";
+import { dirname, join as join3 } from "pathe";
 function defaultsRoot() {
   const here = dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    join(here, "..", "defaults"),
+    join3(here, "..", "defaults"),
     // npm package: dist/../defaults
-    join(here, "defaults"),
+    join3(here, "defaults"),
     // extension bundle: dist/defaults
-    join(here, "..", "..", "defaults")
+    join3(here, "..", "..", "defaults")
     // src/ during some test runners
   ];
   for (const c of candidates) {
@@ -102,13 +435,13 @@ function defaultsRoot() {
   return candidates[0];
 }
 function defaultWorkflowsDir() {
-  return join(defaultsRoot(), "workflows");
+  return join3(defaultsRoot(), "workflows");
 }
 function defaultTemplatesDir() {
-  return join(defaultsRoot(), "templates");
+  return join3(defaultsRoot(), "templates");
 }
 function defaultMemoryDir() {
-  return join(defaultsRoot(), "memory");
+  return join3(defaultsRoot(), "memory");
 }
 
 // src/init.ts
@@ -116,15 +449,15 @@ async function initProject(opts) {
   const { projectRoot, force = false } = opts;
   const created = [];
   const root = sddRoot(projectRoot);
-  if (await pathExists(join2(root, "config.yaml")) && !force) {
+  if (await pathExists(join4(root, "config.yaml")) && !force) {
     throw new Error(
-      `Already initialized (${join2(root, "config.yaml")}). Use --force to re-copy defaults.`
+      `Already initialized (${join4(root, "config.yaml")}). Use --force to re-copy defaults.`
     );
   }
   const config = defaultConfig();
   await ensureDir(root);
   await saveConfig(projectRoot, config);
-  created.push(join2(root, "config.yaml"));
+  created.push(join4(root, "config.yaml"));
   const wfDest = workflowsDir(projectRoot);
   await ensureDir(wfDest);
   const wfSrc = defaultWorkflowsDir();
@@ -146,15 +479,30 @@ async function initProject(opts) {
     await copyDir(mSrc, mDest);
   } else {
     await writeText(
-      join2(mDest, "product.md"),
+      join4(mDest, "index.md"),
+      `# Documentation map
+
+Parent page for **stable** project docs. Start here, then open only what you need.
+
+| Topic | File |
+|-------|------|
+| Product | [product.md](product.md) |
+| Architecture | [architecture.md](architecture.md) |
+| Conventions | [conventions.md](conventions.md) |
+
+Active work: \`.sdd/active-context.md\` and \`changes/<id>/\`.
+`
+    );
+    await writeText(
+      join4(mDest, "product.md"),
       "# Product\n\n<!-- What are you building? -->\n"
     );
     await writeText(
-      join2(mDest, "architecture.md"),
+      join4(mDest, "architecture.md"),
       "# Architecture\n\n<!-- High-level system shape -->\n"
     );
     await writeText(
-      join2(mDest, "conventions.md"),
+      join4(mDest, "conventions.md"),
       "# Conventions\n\n<!-- Coding and process conventions -->\n"
     );
   }
@@ -165,10 +513,10 @@ async function initProject(opts) {
   created.push(changesDir(projectRoot, config));
   created.push(archiveDir(projectRoot, config));
   created.push(domainsDir(projectRoot, config));
-  await writeText(join2(changesDir(projectRoot, config), ".gitkeep"), "");
-  await writeText(join2(archiveDir(projectRoot, config), ".gitkeep"), "");
-  await writeText(join2(domainsDir(projectRoot, config), ".gitkeep"), "");
-  const sddReadme = join2(root, "README.md");
+  await writeText(join4(changesDir(projectRoot, config), ".gitkeep"), "");
+  await writeText(join4(archiveDir(projectRoot, config), ".gitkeep"), "");
+  await writeText(join4(domainsDir(projectRoot, config), ".gitkeep"), "");
+  const sddReadme = join4(root, "README.md");
   if (!await pathExists(sddReadme) || force) {
     await writeText(
       sddReadme,
@@ -179,9 +527,13 @@ This directory configures local Spec-Driven Development for this repo.
 - \`config.yaml\` \u2014 project settings and per-change policy
 - \`workflows/\` \u2014 YAML workflow packs (customize freely)
 - \`templates/\` \u2014 markdown templates for stage artifacts
+- \`protocol.md\` / \`active-context.md\` \u2014 agent playbook + live task (after agent install)
 
 Work lives in \`../changes/\` and completed work in \`../archive/\`.
 
+**Documentation map (stable):** \`../memory/index.md\`  
+**Change-scoped docs:** \`../changes/<id>/\`
+
 ## Quick commands
 
 \`\`\`bash
@@ -196,10 +548,10 @@ sdd complete
     created.push(sddReadme);
   }
   let agentsResult;
-  if (Array.isArray(opts.agents) && opts.agents.length > 0) {
-    const ag = await installAgentIntegrations({
+  if (opts.agents) {
+    const ag = await installAgentIntegration({
       projectRoot,
-      targets: opts.agents,
+      target: opts.agents,
       force
     });
     created.push(...ag.created);
@@ -210,7 +562,7 @@ sdd complete
 
 // src/verify.ts
 import { spawn } from "child_process";
-import { join as join3 } from "pathe";
+import { join as join5 } from "pathe";
 function runCommand(command, cwd) {
   return new Promise((resolve) => {
     const child = spawn(command, {
@@ -239,7 +591,7 @@ async function runLocalVerify(projectRoot, config, changeId, opts) {
   if (!stage) {
     throw new Error(`Unknown stage: ${ctx.meta.stage}`);
   }
-  const evidenceDir = stage.verify?.evidence_dir != null ? join3(ctx.path, stage.verify.evidence_dir) : join3(ctx.path, "evidence", "local");
+  const evidenceDir = stage.verify?.evidence_dir != null ? join5(ctx.path, stage.verify.evidence_dir) : join5(ctx.path, "evidence", "local");
   await ensureDir(evidenceDir);
   const results = [];
   const runCommands = opts?.runCommands !== false;
@@ -253,7 +605,7 @@ async function runLocalVerify(projectRoot, config, changeId, opts) {
         exitCode,
         output: output.slice(0, 5e4)
       });
-      const logPath = join3(evidenceDir, `${cmd.name.replace(/\s+/g, "-")}.log`);
+      const logPath = join5(evidenceDir, `${cmd.name.replace(/\s+/g, "-")}.log`);
       await writeText(
         logPath,
         `# ${cmd.name}
@@ -279,7 +631,7 @@ ${output}`
     ok = results.every((r) => r.exitCode === 0);
   }
   const checklist = stage.gate?.checklist ?? [];
-  const summaryPath = join3(ctx.path, "local-test-results.md");
+  const summaryPath = join5(ctx.path, "local-test-results.md");
   const lines = [
     `# Local verify results`,
     ``,
@@ -315,7 +667,7 @@ ${output}`
   if (await pathExists(summaryPath)) {
     const stamp = nowIso();
     await writeText(
-      join3(evidenceDir, `run-${stamp.replace(/[:.]/g, "-")}.md`),
+      join5(evidenceDir, `run-${stamp.replace(/[:.]/g, "-")}.md`),
       lines.join("\n")
     );
   } else {
@@ -339,6 +691,7 @@ ${output}`
   };
 }
 export {
+  AGENT_INTEGRATIONS,
   AGENT_TARGET_OPTIONS,
   ALL_AGENT_TARGETS,
   ArtifactDefSchema,
@@ -379,9 +732,11 @@ export {
   firstActiveStageId,
   formatStatus,
   getActiveChangeId,
+  getIntegration,
   getStage,
   inferComplexity,
   initProject,
+  installAgentIntegration,
   installAgentIntegrations,
   integrationKeyFor,
   isInitialized,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structured-vibe-coding/core",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Core engine for structured vibe coding (local-first Spec-Driven Development)",
   "type": "module",
   "main": "./dist/index.js",