@structured-vibe-coding/core 0.12.1 → 0.13.0

package/dist/chunk-SM734TFW.js

@@ -0,0 +1,784 @@
+import {
+  activeStages,
+  buildContext,
+  changeDirName,
+  clearActiveIf,
+  firstActiveStageId,
+  getStage,
+  isStageSkipped,
+  loadWorkflow,
+  nextStageId,
+  nowIso,
+  saveChangeMeta,
+  setActiveChange,
+  shouldAutoSkip,
+  uniqueChangeDirName
+} from "./chunk-A752UVPF.js";
+import {
+  ChangeMetaSchema
+} from "./chunk-67AUAGNV.js";
+import {
+  archiveDir,
+  changeMetaPath,
+  changePath,
+  changesDir,
+  memoryDir,
+  templatesDir
+} from "./chunk-7MJYPJMR.js";
+import {
+  copyDir,
+  ensureDir,
+  listDirs,
+  pathExists,
+  readText,
+  readYaml,
+  removePath,
+  writeText,
+  writeYaml
+} from "./chunk-EPFURATC.js";
+
+// src/greenfield.ts
+import { join as join3 } from "pathe";
+
+// 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 } = await import("./agents-WL3PNTJL.js");
+    await refreshActiveAgentContext(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, {
+            idea: String(meta.flags?.idea ?? meta.title ?? "")
+          });
+          break;
+        }
+      }
+    } else {
+      const fallback = join2(tdir, `${artifact.id}.md`);
+      if (await pathExists(fallback)) {
+        content = interpolate(await readText(fallback), meta, stage, workflow, {
+          idea: String(meta.flags?.idea ?? meta.title ?? "")
+        });
+      }
+    }
+    await writeText(target, content);
+    created.push(artifact.path);
+  }
+  return created;
+}
+function interpolate(template, meta, stage, workflow, extra) {
+  const idea = extra?.idea || String(meta.flags?.idea ?? "") || meta.title.replace(/^Greenfield:\s*/i, "");
+  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)).replaceAll("{{idea}}", idea);
+}
+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 } = await import("./agents-WL3PNTJL.js");
+        await refreshActiveAgentContext(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 } = await import("./agents-WL3PNTJL.js");
+    await refreshActiveAgentContext(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);
+  let promoted;
+  if (ctx.meta.workflow === "greenfield" || ctx.meta.flags?.greenfield === true) {
+    try {
+      const { promoteGreenfieldToMemory: promoteGreenfieldToMemory2 } = await import("./greenfield-NTLW6XBL.js");
+      promoted = await promoteGreenfieldToMemory2(projectRoot, config, changeId);
+    } catch {
+    }
+  }
+  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,
+      promoted,
+      ctx: {
+        id: changeId,
+        path: archivedTo,
+        meta,
+        workflow: ctx.workflow,
+        stages: ctx.stages,
+        active: ctx.active
+      }
+    };
+  }
+  return {
+    archivedTo,
+    promoted,
+    ctx: await buildContext(projectRoot, config, changeId)
+  };
+}
+
+// src/greenfield.ts
+var FEATURE_HEADER = /^##\s+(F-\d+)\s*:\s*(.+?)\s*$/i;
+async function startGreenfield(input) {
+  const idea = input.idea.trim();
+  if (!idea || idea.length < 3) {
+    throw new Error('Provide a one-line product idea, e.g. sdd greenfield "Team expense tracker for remote startups"');
+  }
+  const title = idea.length > 80 ? `Greenfield: ${idea.slice(0, 77)}\u2026` : `Greenfield: ${idea}`;
+  const ctx = await createChange({
+    projectRoot: input.projectRoot,
+    config: input.config,
+    title,
+    workflowName: "greenfield",
+    flags: { greenfield: true, idea }
+  });
+  const visionPath = join3(ctx.path, "vision.md");
+  if (await pathExists(visionPath)) {
+    let body = await readText(visionPath);
+    if (body.includes("{{idea}}")) {
+      body = body.replaceAll("{{idea}}", idea);
+      await writeText(visionPath, body);
+    } else if (!body.includes(idea)) {
+      body = body.replace(
+        /## One-liner\n+(\s*[-–—]\s*\n)?/,
+        `## One-liner
+
+${idea}
+
+`
+      );
+      if (!body.includes(idea)) {
+        body = `${body.trim()}
+
+## One-liner
+
+${idea}
+`;
+      }
+      await writeText(visionPath, body);
+    }
+  }
+  return { ctx, idea, visionPath };
+}
+function parseFeaturesBacklog(markdown, sourcePath) {
+  const lines = markdown.split(/\r?\n/);
+  const features = [];
+  let current = null;
+  const flush = () => {
+    if (current) features.push(current);
+    current = null;
+  };
+  for (const line of lines) {
+    const h = line.match(FEATURE_HEADER);
+    if (h) {
+      flush();
+      current = {
+        id: h[1].toUpperCase(),
+        name: h[2].trim(),
+        status: "planned",
+        priority: "should",
+        workflow: "feature",
+        summary: "",
+        requirements: "",
+        notes: "",
+        sourcePath
+      };
+      continue;
+    }
+    if (!current) continue;
+    const field = line.match(
+      /^\s*[-*]\s*\*\*(Status|Priority|Workflow|Summary|Requirements|Notes):\*\*\s*(.*)$/i
+    );
+    if (field) {
+      const key = field[1].toLowerCase();
+      const val = field[2].trim();
+      if (key === "status") current.status = val || current.status;
+      else if (key === "priority") current.priority = val || current.priority;
+      else if (key === "workflow") current.workflow = val || current.workflow;
+      else if (key === "summary") current.summary = val;
+      else if (key === "requirements") current.requirements = val;
+      else if (key === "notes") current.notes = val;
+    }
+  }
+  flush();
+  return features;
+}
+async function findFeaturesBacklogPath(projectRoot, config) {
+  const mem = join3(memoryDir(projectRoot, config), "features.md");
+  if (await pathExists(mem)) return mem;
+  const { getActiveChangeId: getActiveChangeId2 } = await import("./change-context-W4HDO2IK.js");
+  const active = await getActiveChangeId2(projectRoot, config);
+  if (active) {
+    const p = join3(changePath(projectRoot, config, active), "features.md");
+    if (await pathExists(p)) return p;
+  }
+  const ids = (await listDirs(changesDir(projectRoot, config))).sort().reverse();
+  for (const id of ids) {
+    try {
+      const p = join3(changePath(projectRoot, config, id), "features.md");
+      if (await pathExists(p)) {
+        const body = await readText(p);
+        if (parseFeaturesBacklog(body, p).length) return p;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+async function listBacklogFeatures(projectRoot, config) {
+  const path = await findFeaturesBacklogPath(projectRoot, config);
+  if (!path) {
+    throw new Error(
+      'No feature backlog found. Run `sdd greenfield "your idea"` and complete the features stage (or add memory/features.md).'
+    );
+  }
+  const features = parseFeaturesBacklog(await readText(path), path);
+  if (!features.length) {
+    throw new Error(
+      `No F-NNN features parsed in ${path}. Use headings like: ## F-001: Short name`
+    );
+  }
+  return { path, features };
+}
+async function startFeatureFromBacklog(input) {
+  const id = input.featureId.trim().toUpperCase();
+  if (!/^F-\d+$/i.test(id)) {
+    throw new Error(`Feature id must look like F-001 (got "${input.featureId}")`);
+  }
+  const { path, features } = await listBacklogFeatures(
+    input.projectRoot,
+    input.config
+  );
+  const feature = features.find((f) => f.id === id);
+  if (!feature) {
+    const known = features.map((f) => f.id).join(", ");
+    throw new Error(`Feature ${id} not found in ${path}. Known: ${known}`);
+  }
+  const workflowName = input.workflowName?.trim() || feature.workflow?.trim() || "feature";
+  const title = feature.name ? `${feature.id}: ${feature.name}` : feature.id;
+  const ctx = await createChange({
+    projectRoot: input.projectRoot,
+    config: input.config,
+    title,
+    workflowName,
+    flags: {
+      from_backlog: feature.id,
+      greenfield_feature: true
+    }
+  });
+  const stage = ctx.workflow.stages.find((s) => s.id === ctx.meta.stage);
+  const art = stage?.artifacts.find((a) => a.required) ?? stage?.artifacts[0];
+  if (art) {
+    const artPath = join3(ctx.path, art.path);
+    if (await pathExists(artPath)) {
+      let body = await readText(artPath);
+      if (!isSubstantiveArtifactContent(body)) {
+        body = [
+          `# ${feature.name || feature.id}`,
+          ``,
+          `> From backlog **${feature.id}** \xB7 priority: ${feature.priority}`,
+          ``,
+          `## Summary`,
+          ``,
+          feature.summary || feature.name || "(fill in)",
+          ``,
+          `## Requirements`,
+          ``,
+          feature.requirements || "-",
+          ``,
+          `## Notes`,
+          ``,
+          feature.notes || "-",
+          ``,
+          `## Success`,
+          ``,
+          `-`,
+          ``
+        ].join("\n");
+        await writeText(artPath, body);
+      }
+    }
+  }
+  await updateFeatureStatus(path, feature.id, "in_progress");
+  return { ctx, feature };
+}
+async function updateFeatureStatus(backlogPath, featureId, status) {
+  const id = featureId.toUpperCase();
+  let md = await readText(backlogPath);
+  const re = new RegExp(
+    `(##\\s+${id}\\s*:[\\s\\S]*?[-*]\\s*\\*\\*Status:\\*\\*\\s*)([^\\n]+)`,
+    "i"
+  );
+  if (!re.test(md)) return;
+  md = md.replace(re, `$1${status}`);
+  await writeText(backlogPath, md);
+}
+async function promoteGreenfieldToMemory(projectRoot, config, changeId) {
+  const dir = changePath(projectRoot, config, changeId);
+  const mem = memoryDir(projectRoot, config);
+  await ensureDir(mem);
+  const map = [
+    { from: "vision.md", to: "product.md" },
+    { from: "requirements.md", to: "requirements.md" },
+    { from: "features.md", to: "features.md" },
+    { from: "architecture.md", to: "architecture.md" }
+  ];
+  const written = [];
+  for (const { from, to } of map) {
+    const src = join3(dir, from);
+    if (!await pathExists(src)) continue;
+    const body = await readText(src);
+    if (!isSubstantiveArtifactContent(body)) continue;
+    const dest = join3(mem, to);
+    await writeText(
+      dest,
+      body.includes("Promoted from greenfield") ? body : `${body.trim()}
+
+---
+
+_Promoted from greenfield change \`${changeId}\`._
+`
+    );
+    written.push(join3(config.memory_path, to));
+  }
+  const indexPath = join3(mem, "index.md");
+  if (await pathExists(indexPath)) {
+    let index = await readText(indexPath);
+    if (!index.includes("features.md")) {
+      index = index.replace(
+        /\| Architecture \|/,
+        `| Feature backlog | [features.md](features.md) |
+| Architecture |`
+      );
+      await writeText(indexPath, index);
+    }
+  }
+  return written;
+}
+
+export {
+  isSubstantiveArtifactContent,
+  incompletePriorStageErrors,
+  canLeaveStage,
+  fallbackIncompleteStageId,
+  approveGate,
+  startGreenfield,
+  parseFeaturesBacklog,
+  findFeaturesBacklogPath,
+  listBacklogFeatures,
+  startFeatureFromBacklog,
+  updateFeatureStatus,
+  promoteGreenfieldToMemory,
+  createChange,
+  advanceStage,
+  skipStage,
+  switchWorkflow,
+  completeChange
+};