@structured-vibe-coding/core 0.12.1 → 0.13.0

package/dist/index.js

@@ -5,37 +5,67 @@ import {
   DEFAULT_INIT_INTEGRATION,
   PROTOCOL_MD,
   SDD_AGENT_ROLES,
-  activeStages,
   agentHostPaths,
   agentKickoffMessage,
+  getIntegration,
+  installAgentIntegration,
+  installAgentIntegrations,
+  integrationKeyFor,
+  loadInstalledAgent,
+  optionForTarget,
+  parseAgentTargets,
+  parseIntegration,
+  refreshActiveAgentContext,
+  removeOtherAgentHosts,
+  renderThinAgent,
+  writeAgentHandoff
+} from "./chunk-S7SHVKG4.js";
+import {
+  defaultConfig,
+  isInitialized,
+  loadConfig,
+  saveConfig
+} from "./chunk-OJFMJHNL.js";
+import {
+  advanceStage,
+  approveGate,
+  canLeaveStage,
+  completeChange,
+  createChange,
+  fallbackIncompleteStageId,
+  findFeaturesBacklogPath,
+  incompletePriorStageErrors,
+  isSubstantiveArtifactContent,
+  listBacklogFeatures,
+  parseFeaturesBacklog,
+  promoteGreenfieldToMemory,
+  skipStage,
+  startFeatureFromBacklog,
+  startGreenfield,
+  switchWorkflow,
+  updateFeatureStatus
+} from "./chunk-SM734TFW.js";
+import {
   buildAgentPrompt,
+  formatStatus
+} from "./chunk-C725DWSB.js";
+import {
+  activeStages,
   buildContext,
   changeDirName,
   clearActiveIf,
   firstActiveStageId,
-  formatStatus,
   getActiveChangeId,
-  getIntegration,
   getStage,
   inferComplexity,
-  installAgentIntegration,
-  installAgentIntegrations,
-  integrationKeyFor,
   isStageSkipped,
   listChanges,
   listWorkflowNames,
   loadChangeMeta,
-  loadInstalledAgent,
   loadWorkflow,
   nextStageId,
   nowIso,
-  optionForTarget,
-  parseAgentTargets,
-  parseIntegration,
   recommendWorkflow,
-  refreshActiveAgentContext,
-  removeOtherAgentHosts,
-  renderThinAgent,
   resolveChangeId,
   resolveStages,
   saveChangeMeta,
@@ -43,9 +73,8 @@ import {
   shouldAutoSkip,
   slugify,
   todayIsoDate,
-  uniqueChangeDirName,
-  writeAgentHandoff
-} from "./chunk-24S2YWWL.js";
+  uniqueChangeDirName
+} from "./chunk-A752UVPF.js";
 import {
   ArtifactDefSchema,
   ChangeMetaSchema,
@@ -53,12 +82,8 @@ import {
   GateSchema,
   StageSchema,
   VerifyCommandSchema,
-  WorkflowSchema,
-  defaultConfig,
-  isInitialized,
-  loadConfig,
-  saveConfig
-} from "./chunk-KZHNYGD6.js";
+  WorkflowSchema
+} from "./chunk-67AUAGNV.js";
 import {
   SDD_DIR,
   activePointerPath,
@@ -88,487 +113,21 @@ import {
   writeYaml
 } from "./chunk-EPFURATC.js";
 
-// src/change.ts
-import { join as join2 } from "pathe";
-
-// src/stage-gates.ts
-import { join } from "pathe";
-
-// src/artifacts.ts
-function isSubstantiveArtifactContent(content) {
-  const stripped = content.replace(/<!--[\s\S]*?-->/g, "").replace(/^#{1,6}\s+.*$/gm, "").replace(/^>\s.*$/gm, "").replace(/^\s*[-*+]\s*$/gm, "").replace(/^\s*[-*+]\s*\.\.\.\s*$/gm, "").replace(/^\s*[-*+]\s*TBD\s*$/gim, "").replace(/^\s*[-*+]\s*TODO\s*$/gim, "").replace(/^\s*\|.*\|\s*$/gm, "").replace(/`+/g, "").trim();
-  if (stripped.length < 48) return false;
-  const meaningful = stripped.replace(/[-–—_.\s]/g, "").replace(/\b(TBD|TODO|N\/A|none|n\/a)\b/gi, "");
-  return meaningful.length >= 32;
-}
-function incompleteArtifactReason(path, content) {
-  if (content == null) {
-    return `Missing required artifact: ${path}`;
-  }
-  if (!isSubstantiveArtifactContent(content)) {
-    return [
-      `Required artifact still incomplete (looks like empty template/stub): ${path}`,
-      ``,
-      `Open that file and replace the template with a few real sentences, for example:`,
-      `  - What is broken or missing?`,
-      `  - What will you change?`,
-      `  - How will you know it worked?`,
-      ``,
-      `Then run: sdd next`,
-      `Optional stages only: sdd skip <stage> -r "not needed"`
-    ].join("\n");
-  }
-  return null;
-}
-
-// src/stage-gates.ts
-async function checkRequiredArtifacts(changePath2, stageId, artifacts) {
-  const errors = [];
-  for (const artifact of artifacts) {
-    if (!artifact.required) continue;
-    if (artifact.path.endsWith("/")) {
-      const target2 = join(changePath2, artifact.path);
-      if (!await pathExists(target2)) {
-        errors.push(`Missing required directory: ${artifact.path} (stage ${stageId})`);
-      }
-      continue;
-    }
-    const target = join(changePath2, artifact.path);
-    if (!await pathExists(target)) {
-      errors.push(incompleteArtifactReason(artifact.path, null));
-      continue;
-    }
-    const content = await readText(target);
-    const reason = incompleteArtifactReason(artifact.path, content);
-    if (reason) {
-      errors.push(`${reason} (stage ${stageId})`);
-    }
-  }
-  return errors;
-}
-async function incompletePriorStageErrors(ctx) {
-  const errors = [];
-  const stages = activeStages(ctx.workflow, ctx.meta);
-  const currentIdx = stages.findIndex((s) => s.id === ctx.meta.stage);
-  if (currentIdx <= 0) return errors;
-  for (let i = 0; i < currentIdx; i++) {
-    const stage = stages[i];
-    if (isStageSkipped(ctx.meta, stage.id) || shouldAutoSkip(stage, ctx.meta)) {
-      continue;
-    }
-    const required = stage.artifacts.filter((a) => a.required);
-    if (!required.length && stage.optional) continue;
-    const stageErrors = await checkRequiredArtifacts(
-      ctx.path,
-      stage.id,
-      stage.artifacts
-    );
-    if (stageErrors.length) {
-      errors.push(
-        `Prior stage "${stage.id}" is not complete \u2014 finish it or \`sdd skip ${stage.id} -r "\u2026"\` if optional.`
-      );
-      errors.push(...stageErrors);
-    }
-  }
-  return errors;
-}
-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 };
-  }
-  errors.push(...await incompletePriorStageErrors(ctx));
-  errors.push(
-    ...await checkRequiredArtifacts(ctx.path, stage.id, stage.artifacts)
-  );
-  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.`
-      );
-    }
-  }
-  if (stage.optional || stage.kind === "clarify" || stage.kind === "brainstorm") {
-    warnings.push(
-      `Stage "${stage.id}" is optional (${stage.kind ?? "optional"}). Skip with: sdd skip ${stage.id} -r "not needed"`
-    );
-  }
-  return { ok: errors.length === 0, errors, warnings };
-}
-async function fallbackIncompleteStageId(ctx) {
-  const stages = activeStages(ctx.workflow, ctx.meta);
-  for (const stage of stages) {
-    if (stage.id === ctx.meta.stage) break;
-    if (isStageSkipped(ctx.meta, stage.id) || shouldAutoSkip(stage, ctx.meta)) {
-      continue;
-    }
-    const required = stage.artifacts.filter((a) => a.required);
-    if (!required.length && stage.optional) continue;
-    const errs = await checkRequiredArtifacts(ctx.path, stage.id, stage.artifacts);
-    if (errs.length) return stage.id;
-  }
-  return null;
-}
-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-R4RMNXOS.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) {
-  let ctx = await buildContext(projectRoot, config, changeId);
-  const warnings = [];
-  if (ctx.meta.status === "completed") {
-    throw new Error("Change is already completed.");
-  }
-  if (!opts?.force) {
-    const fallback = await fallbackIncompleteStageId(ctx);
-    if (fallback && fallback !== ctx.meta.stage) {
-      const from2 = ctx.meta.stage;
-      ctx.meta.stage = fallback;
-      await saveChangeMeta(projectRoot, config, ctx.meta);
-      const stage2 = getStage(ctx.workflow, ctx.meta, fallback);
-      const artifactsCreated2 = await materializeStageArtifacts(
-        projectRoot,
-        config,
-        changeId,
-        ctx.workflow,
-        ctx.meta,
-        stage2
-      );
-      try {
-        const { refreshActiveAgentContext: refreshActiveAgentContext2 } = await import("./agents-R4RMNXOS.js");
-        await refreshActiveAgentContext2(projectRoot);
-      } catch {
-      }
-      const updated2 = await buildContext(projectRoot, config, changeId);
-      return {
-        ctx: updated2,
-        from: from2,
-        to: fallback,
-        completed: false,
-        artifactsCreated: artifactsCreated2,
-        warnings: [
-          ...warnings,
-          `Fell back to incomplete stage "${fallback}" (required work not done). Finish it before advancing.`
-        ]
-      };
-    }
-  }
-  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-R4RMNXOS.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";
+import { join as join2 } from "pathe";
 
 // src/defaults.ts
 import { existsSync } from "fs";
 import { fileURLToPath } from "url";
-import { dirname, join as join3 } from "pathe";
+import { dirname, join } from "pathe";
 function defaultsRoot() {
   const here = dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    join3(here, "..", "defaults"),
+    join(here, "..", "defaults"),
     // npm package: dist/../defaults
-    join3(here, "defaults"),
+    join(here, "defaults"),
     // same-dir defaults if present
-    join3(here, "..", "..", "defaults")
+    join(here, "..", "..", "defaults")
     // src/ during some test runners
   ];
   for (const c of candidates) {
@@ -577,13 +136,13 @@ function defaultsRoot() {
   return candidates[0];
 }
 function defaultWorkflowsDir() {
-  return join3(defaultsRoot(), "workflows");
+  return join(defaultsRoot(), "workflows");
 }
 function defaultTemplatesDir() {
-  return join3(defaultsRoot(), "templates");
+  return join(defaultsRoot(), "templates");
 }
 function defaultMemoryDir() {
-  return join3(defaultsRoot(), "memory");
+  return join(defaultsRoot(), "memory");
 }
 
 // src/init.ts
@@ -591,15 +150,15 @@ async function initProject(opts) {
   const { projectRoot, force = false } = opts;
   const created = [];
   const root = sddRoot(projectRoot);
-  if (await pathExists(join4(root, "config.yaml")) && !force) {
+  if (await pathExists(join2(root, "config.yaml")) && !force) {
     throw new Error(
-      `Already initialized (${join4(root, "config.yaml")}). Use --force to re-copy defaults.`
+      `Already initialized (${join2(root, "config.yaml")}). Use --force to re-copy defaults.`
     );
   }
   const config = defaultConfig();
   await ensureDir(root);
   await saveConfig(projectRoot, config);
-  created.push(join4(root, "config.yaml"));
+  created.push(join2(root, "config.yaml"));
   const wfDest = workflowsDir(projectRoot);
   await ensureDir(wfDest);
   const wfSrc = defaultWorkflowsDir();
@@ -621,7 +180,7 @@ async function initProject(opts) {
     await copyDirSkipExisting(mSrc, mDest);
   } else {
     await writeTextIfMissing(
-      join4(mDest, "index.md"),
+      join2(mDest, "index.md"),
       `# Documentation map
 
 Parent page for **stable** project docs. Start here, then open only what you need.
@@ -637,11 +196,11 @@ Active work: \`.sdd/active-context.md\` and \`changes/<id>/\`.
 `
     );
     await writeTextIfMissing(
-      join4(mDest, "product.md"),
+      join2(mDest, "product.md"),
       "# Product\n\n<!-- What are you building? -->\n"
     );
     await writeTextIfMissing(
-      join4(mDest, "constitution.md"),
+      join2(mDest, "constitution.md"),
       `# Constitution
 
 <!-- Non-negotiables agents must not violate. Broader style lives in conventions.md. -->
@@ -668,21 +227,21 @@ Active work: \`.sdd/active-context.md\` and \`changes/<id>/\`.
 `
     );
     await writeTextIfMissing(
-      join4(mDest, "architecture.md"),
+      join2(mDest, "architecture.md"),
       "# Architecture\n\n<!-- High-level system shape -->\n"
     );
     await writeTextIfMissing(
-      join4(mDest, "conventions.md"),
+      join2(mDest, "conventions.md"),
       "# Conventions\n\n<!-- Coding and process conventions -->\n"
     );
   }
-  if (!await pathExists(join4(mDest, "constitution.md"))) {
-    const fromDefault = join4(mSrc, "constitution.md");
+  if (!await pathExists(join2(mDest, "constitution.md"))) {
+    const fromDefault = join2(mSrc, "constitution.md");
     if (await pathExists(fromDefault)) {
       await copyDirSkipExisting(mSrc, mDest);
     } else {
       await writeTextIfMissing(
-        join4(mDest, "constitution.md"),
+        join2(mDest, "constitution.md"),
         `# Constitution
 
 <!-- Non-negotiables agents must not violate. Broader style lives in conventions.md. -->
@@ -715,9 +274,9 @@ Active work: \`.sdd/active-context.md\` and \`changes/<id>/\`.
   await ensureDir(domainsDir(projectRoot, config));
   created.push(changesDir(projectRoot, config));
   created.push(domainsDir(projectRoot, config));
-  await writeText(join4(changesDir(projectRoot, config), ".gitkeep"), "");
-  await writeText(join4(domainsDir(projectRoot, config), ".gitkeep"), "");
-  const sddReadme = join4(root, "README.md");
+  await writeText(join2(changesDir(projectRoot, config), ".gitkeep"), "");
+  await writeText(join2(domainsDir(projectRoot, config), ".gitkeep"), "");
+  const sddReadme = join2(root, "README.md");
   if (!await pathExists(sddReadme) || force) {
     await writeText(
       sddReadme,
@@ -764,7 +323,7 @@ sdd complete
 
 // src/verify.ts
 import { spawn } from "child_process";
-import { join as join5 } from "pathe";
+import { join as join3 } from "pathe";
 function runCommand(command, cwd) {
   return new Promise((resolve) => {
     const child = spawn(command, {
@@ -836,7 +395,7 @@ async function runLocalVerify(projectRoot, config, changeId, opts) {
     throw new Error(`Unknown stage: ${ctx.meta.stage}`);
   }
   const evidenceDirRaw = stage.verify?.evidence_dir?.trim();
-  const evidenceDir = evidenceDirRaw && evidenceDirRaw.length > 0 ? join5(ctx.path, evidenceDirRaw) : null;
+  const evidenceDir = evidenceDirRaw && evidenceDirRaw.length > 0 ? join3(ctx.path, evidenceDirRaw) : null;
   if (evidenceDir) {
     await ensureDir(evidenceDir);
   }
@@ -853,7 +412,7 @@ async function runLocalVerify(projectRoot, config, changeId, opts) {
         output: output.slice(0, 5e4)
       });
       if (evidenceDir) {
-        const logPath = join5(evidenceDir, `${cmd.name.replace(/\s+/g, "-")}.log`);
+        const logPath = join3(evidenceDir, `${cmd.name.replace(/\s+/g, "-")}.log`);
         await writeText(
           logPath,
           `# ${cmd.name}
@@ -880,7 +439,7 @@ ${output}`
     ok = results.every((r) => r.exitCode === 0);
   }
   const checklist = stage.gate?.checklist ?? [];
-  const summaryPath = join5(ctx.path, "local-test-results.md");
+  const summaryPath = join3(ctx.path, "local-test-results.md");
   const lines = buildSummaryLines(ctx.meta.title, stage.id, ok, results, checklist);
   const summaryBody = lines.join("\n");
   if (await pathExists(summaryPath)) {
@@ -913,7 +472,7 @@ ${output}`
     if (evidenceDir) {
       const stamp = nowIso();
       await writeText(
-        join5(evidenceDir, `run-${stamp.replace(/[:.]/g, "-")}.md`),
+        join3(evidenceDir, `run-${stamp.replace(/[:.]/g, "-")}.md`),
         summaryBody
       );
     }
@@ -939,7 +498,7 @@ ${output}`
 }
 
 // src/code-context/index.ts
-import { extname as extname4, join as join8, normalize as normalize5 } from "pathe";
+import { extname as extname4, join as join6, normalize as normalize5 } from "pathe";
 
 // src/code-context/adapters/registry.ts
 import { extname as extname2 } from "pathe";
@@ -1262,7 +821,7 @@ function formatJsonSummary(summary, gaps, slices, ok) {
 
 // src/code-context/focus.ts
 import { promises as fs } from "fs";
-import { isAbsolute, join as join6, normalize as normalize3, relative } from "pathe";
+import { isAbsolute, join as join4, normalize as normalize3, relative } from "pathe";
 
 // src/code-context/ignore.ts
 import { basename as basename2, extname as extname3, normalize as normalize2 } from "pathe";
@@ -1440,12 +999,12 @@ function extractPathLikeTokens(text) {
   return found;
 }
 function toRepoRelative(projectRoot, p) {
-  const abs = isAbsolute(p) ? p : join6(projectRoot, p);
+  const abs = isAbsolute(p) ? p : join4(projectRoot, p);
   const rel = relative(projectRoot, abs);
   return normalize3(rel).replace(/\\/g, "/");
 }
 function toAbsolute(projectRoot, p) {
-  return isAbsolute(p) ? p : join6(projectRoot, p);
+  return isAbsolute(p) ? p : join4(projectRoot, p);
 }
 async function walkFiles(absDir, projectRoot, maxFiles, out, gaps) {
   if (out.length >= maxFiles) return;
@@ -1458,7 +1017,7 @@ async function walkFiles(absDir, projectRoot, maxFiles, out, gaps) {
   }
   for (const entry of entries) {
     if (out.length >= maxFiles) return;
-    const abs = join6(absDir, entry.name);
+    const abs = join4(absDir, entry.name);
     const rel = toRepoRelative(projectRoot, abs);
     const kind = classifyPath(rel);
     if (kind === "secret" || kind === "ignored") continue;
@@ -1552,7 +1111,7 @@ async function resolveChangeMeta(projectRoot, changeId, gaps) {
     return null;
   }
   const cpath = changePath(projectRoot, config, id);
-  const metaPath = join6(cpath, "meta.yaml");
+  const metaPath = join4(cpath, "meta.yaml");
   if (!await pathExists(metaPath)) {
     if (!await pathExists(cpath)) {
       gaps.push({
@@ -1585,7 +1144,7 @@ async function searchByKeywords(projectRoot, keywords, symbols, maxFiles) {
   const terms = [...keywords, ...symbols.map((s) => s.toLowerCase())];
   if (!terms.length) return out;
   for (const root of SOURCE_ROOTS) {
-    const abs = join6(projectRoot, root);
+    const abs = join4(projectRoot, root);
     if (!await pathExists(abs)) continue;
     const files = [];
     await walkFiles(abs, projectRoot, maxFiles * 4, files, []);
@@ -1599,7 +1158,7 @@ async function searchByKeywords(projectRoot, keywords, symbols, maxFiles) {
       }
       if (symbols.length) {
         try {
-          const text = await readText(join6(projectRoot, rel));
+          const text = await readText(join4(projectRoot, rel));
           if (symbols.some((s) => text.includes(s))) {
             out.push(rel);
           }
@@ -1635,7 +1194,7 @@ async function resolveFocus(request, options) {
     }
     notes.push(`Change signals from: ${change.id}`);
     for (const artifact of ["tasks.md", "feature.md", "stories.md", "lld.md"]) {
-      const body = await readBounded(join6(change.path, artifact), 8e3);
+      const body = await readBounded(join4(change.path, artifact), 8e3);
       if (!body) continue;
       if (!request.paths?.length) {
         for (const p of extractPathLikeTokens(body)) {
@@ -1718,7 +1277,7 @@ async function resolveFocus(request, options) {
 }
 
 // src/code-context/graph.ts
-import { dirname as dirname2, join as join7, normalize as normalize4 } from "pathe";
+import { dirname as dirname2, join as join5, normalize as normalize4 } from "pathe";
 var GraphLite = class {
   files = /* @__PURE__ */ new Map();
   edges = [];
@@ -1749,7 +1308,7 @@ var GraphLite = class {
   resolveImportTarget(fromFile, specifier) {
     if (!specifier.startsWith(".")) return void 0;
     const base = dirname2(fromFile);
-    const joined = normalize4(join7(base, specifier)).replace(/\\/g, "/");
+    const joined = normalize4(join5(base, specifier)).replace(/\\/g, "/");
     const candidates = [
       joined,
       `${joined}.ts`,
@@ -2175,7 +1734,7 @@ async function generateCodeContext(request, deps) {
       });
       continue;
     }
-    const abs = join8(projectRoot, rel);
+    const abs = join6(projectRoot, rel);
     if (!await pathExists(abs)) {
       gaps.push({
         code: "path_missing",
@@ -2264,7 +1823,7 @@ async function generateCodeContext(request, deps) {
   if (plan.changeId) {
     try {
       const { readYaml: readYaml2 } = await import("./fs-J6DIV6CX.js");
-      const metaPath = join8(
+      const metaPath = join6(
         projectRoot,
         // best-effort: changes/<id>/meta.yaml via relative walk
         // Prefer using change path from resolve — re-read lightly
@@ -2272,10 +1831,10 @@ async function generateCodeContext(request, deps) {
         plan.changeId,
         "meta.yaml"
       );
-      const { loadConfig: loadConfig2 } = await import("./config-4QZMRSL3.js");
+      const { loadConfig: loadConfig2 } = await import("./config-ZYEEIRXJ.js");
       const { changePath: changePath2 } = await import("./paths-64GA32IZ.js");
       const config = await loadConfig2(projectRoot);
-      const mp = join8(changePath2(projectRoot, config, plan.changeId), "meta.yaml");
+      const mp = join6(changePath2(projectRoot, config, plan.changeId), "meta.yaml");
       if (await pathExists(mp)) {
         const meta = await readYaml2(mp);
         changeTitle = meta.title ?? plan.changeId;
@@ -2329,7 +1888,7 @@ async function generateCodeContext(request, deps) {
 }
 
 // src/refine.ts
-import { join as join9 } from "pathe";
+import { join as join7 } from "pathe";
 function stageArtifactRefs(ctx, stageId) {
   const stage = getStage(ctx.workflow, ctx.meta, stageId);
   if (!stage) return [];
@@ -2337,7 +1896,7 @@ function stageArtifactRefs(ctx, stageId) {
     stageId,
     path: a.path,
     required: Boolean(a.required),
-    absPath: join9(ctx.path, a.path)
+    absPath: join7(ctx.path, a.path)
   }));
 }
 function listMarkdown(refs) {
@@ -2382,11 +1941,11 @@ async function buildRefinePlan(opts) {
     laterArtifacts.push(...stageArtifactRefs(ctx, s.id));
   }
   const focusArtifacts = stageArtifactRefs(ctx, focusStageId);
-  const constitutionPath = join9(memoryDir(opts.projectRoot, opts.config), "constitution.md");
+  const constitutionPath = join7(memoryDir(opts.projectRoot, opts.config), "constitution.md");
   const constitutionExists = await pathExists(constitutionPath);
-  const briefPath = join9(ctx.path, "refine-brief.md");
-  const reportPath = join9(ctx.path, "quality-report.md");
-  const openItemsPath = join9(ctx.path, "open-items.md");
+  const briefPath = join7(ctx.path, "refine-brief.md");
+  const reportPath = join7(ctx.path, "quality-report.md");
+  const openItemsPath = join7(ctx.path, "open-items.md");
   const briefMarkdown = buildRefineBriefMarkdown({
     ctx,
     focusStageId,
@@ -2515,7 +2074,7 @@ Do **not** invent content for later stages that were not materialized yet. If a
 }
 async function writeRefineBrief(plan, projectRoot) {
   await writeText(plan.briefPath, plan.briefMarkdown);
-  const pointer = join9(sddRoot(projectRoot), "refine-brief.md");
+  const pointer = join7(sddRoot(projectRoot), "refine-brief.md");
   await writeText(
     pointer,
     `# Refine brief pointer
@@ -2576,6 +2135,7 @@ export {
   ensureDir,
   fallbackAdapter,
   fallbackIncompleteStageId,
+  findFeaturesBacklogPath,
   firstActiveStageId,
   formatJsonSummary,
   formatStatus,
@@ -2594,6 +2154,7 @@ export {
   isSecretPath,
   isStageSkipped,
   isSubstantiveArtifactContent,
+  listBacklogFeatures,
   listChanges,
   listDirs,
   listFiles,
@@ -2608,8 +2169,10 @@ export {
   nowIso,
   optionForTarget,
   parseAgentTargets,
+  parseFeaturesBacklog,
   parseIntegration,
   pathExists,
+  promoteGreenfieldToMemory,
   readText,
   readYaml,
   recommendWorkflow,
@@ -2628,12 +2191,15 @@ export {
   shouldAutoSkip,
   skipStage,
   slugify,
+  startFeatureFromBacklog,
+  startGreenfield,
   switchWorkflow,
   templatesDir,
   todayIsoDate,
   tokenizeKeywords,
   typescriptAdapter,
   uniqueChangeDirName,
+  updateFeatureStatus,
   workflowsDir,
   writeAgentHandoff,
   writeRefineBrief,