@maycombhq/atticus 2.0.0-beta.26 → 2.0.0-beta.27

package/dist/{chunk-WH3ZFLXT.js → chunk-SVOGRJO6.js}

@@ -10,22 +10,22 @@ import {
   blockingIssues,
   readStoreMarker,
   readStoreVia
-} from "./chunk-UTZMF5CV.js";
+} from "./chunk-23TTURB2.js";
+import {
+  outsideProfileSystems,
+  readCatalog
+} from "./chunk-QC6GSNIK.js";
 import {
   AdapterError,
   mergeBlockers,
   requireApproval
-} from "./chunk-6U65YB54.js";
-import {
-  outsideProfileSystems,
-  readCatalog
-} from "./chunk-2HDNOUJU.js";
+} from "./chunk-I57IH5X6.js";
 import {
   baseClonePath,
   createGit,
   readChangeRepos,
   writeChangeRepos
-} from "./chunk-XIJBQM45.js";
+} from "./chunk-X5B7KYPD.js";
 import {
   ChangeLifecycle,
   ChangeTouches,
@@ -46,10 +46,10 @@ import {
   specFlowFiles,
   taskBranch,
   toCanonicalYaml
-} from "./chunk-6ZDAEUKB.js";
+} from "./chunk-WJWSB65O.js";
 import {
   writeFileAtomic
-} from "./chunk-MEMEO7YO.js";
+} from "./chunk-SMFFUFMN.js";
 import {
   ChangeArtifact,
   Finding,
@@ -62,7 +62,7 @@ import {
   fastPathOf,
   loadOpenSpecSettings,
   loadOrgPack
-} from "./chunk-LZFKJ2BR.js";
+} from "./chunk-A3LVMCA5.js";
 import {
   require_dist
 } from "./chunk-BQGDB6ZL.js";
@@ -1463,8 +1463,46 @@ function testPlanFor(ctx, type, risk) {
 // packages/changes/dist/lifecycle.js
 var import_yaml5 = __toESM(require_dist(), 1);
 import { createHash } from "node:crypto";
-import { readdir as readdir4, readFile as readFile6 } from "node:fs/promises";
-import { join as join7 } from "node:path";
+import { readdir as readdir5, readFile as readFile7 } from "node:fs/promises";
+import { join as join8 } from "node:path";
+
+// packages/changes/dist/planning.js
+import { copyFile, mkdir, readdir as readdir4, readFile as readFile6 } from "node:fs/promises";
+import { dirname, join as join7 } from "node:path";
+var GENERATED_MARK = "<!-- Generated by atticus plan";
+var PLANNING_FILES = ["stories.md", "tasks.md", "requests.md"];
+var isGenerated = (text) => text.replace(/^\uFEFF/, "").trimStart().startsWith(GENERATED_MARK);
+async function personWritten(dir, rels) {
+  const own = [];
+  for (const rel of rels) {
+    const text = await readFile6(join7(dir, ...rel.split("/")), "utf8").catch(() => void 0);
+    if (text !== void 0 && !isGenerated(text))
+      own.push(rel);
+  }
+  return own;
+}
+async function keepPersonWritten(dir, rel, stage, files, o = {}) {
+  if (!files.length)
+    return void 0;
+  const base = join7(dir, "stage", `${stage}-by-person`);
+  const taken = (await readdir4(base).catch(() => [])).map((n2) => Number(n2)).filter((n2) => Number.isInteger(n2) && n2 > 0);
+  const n = Math.max(Math.max(0, ...taken) + 1, Math.floor(o.atLeast ?? 1));
+  for (const f of files) {
+    const dest = join7(base, String(n), ...f.split("/"));
+    await mkdir(dirname(dest), { recursive: true });
+    await copyFile(join7(dir, ...f.split("/")), dest).catch((e) => {
+      if (e.code !== "ENOENT")
+        throw e;
+    });
+  }
+  return `${rel}/stage/${stage}-by-person/${n}/`;
+}
+var personWrittenPlanning = (dir) => personWritten(dir, PLANNING_FILES);
+var writesPlanning = (step) => step.artifacts.includes("stories") || step.artifacts.includes("tasks");
+var stageWorkDone = (state) => state === "done" || state === "person";
+var stageIdle = (state) => state === "not-started" || state === "skipped";
+
+// packages/changes/dist/lifecycle.js
 function phaseState(phase) {
   return phase === "release" ? "release-ready" : phase;
 }
@@ -1529,7 +1567,7 @@ async function phaseStage(ctx, change, phase) {
     return void 0;
   const dir = changeFolder(ctx.root, change.id);
   for (const x of ctx.policy.stages)
-    if (await readFile6(join7(dir, ...x.loop.split("/"))).then(() => true, () => false))
+    if (await readFile7(join8(dir, ...x.loop.split("/"))).then(() => true, () => false))
       return step;
   return void 0;
 }
@@ -1538,9 +1576,12 @@ async function checkStage(root, change, step) {
   const dir = changeFolder(root, change.id);
   const run = stageCommand(step, change.id);
   const reason = (message) => [{ code: "stage-not-done", message }];
-  const text = await readFile6(join7(dir, ...step.loop.split("/")), "utf8").catch(() => void 0);
-  if (text === void 0)
+  const text = await readFile7(join8(dir, ...step.loop.split("/")), "utf8").catch(() => void 0);
+  if (text === void 0) {
+    if (writesPlanning(step) && (await personWrittenPlanning(dir)).length)
+      return [];
     return reason(`The ${step.stage} stage hasn't run yet: run ${run}.`);
+  }
   let loop;
   try {
     loop = (0, import_yaml5.parse)(text);
@@ -1572,7 +1613,7 @@ async function checkStage(root, change, step) {
   const out = [];
   const artifactFile = new Set(Object.values(FILE));
   for (const w of step.writes.filter((x) => !x.endsWith("/") && !x.startsWith("stage/") && !isWritePattern(x) && !artifactFile.has(x)))
-    if (!await readFile6(join7(dir, ...w.split("/"))).then(() => true, () => false))
+    if (!await readFile7(join8(dir, ...w.split("/"))).then(() => true, () => false))
       out.push(...reason(`${w} is missing, though the ${step.stage} stage is done: run ${run} again.`));
   return out;
 }
@@ -1584,7 +1625,7 @@ async function stageFiles(dir, step) {
     else if (isWritePattern(w)) {
       const parent = w.split("/").slice(0, -1).join("/");
       out.push(...(await walk(dir, parent)).filter((p) => writeMatches(w, p)));
-    } else if (await readFile6(join7(dir, ...w.split("/"))).then(() => true, () => false))
+    } else if (await readFile7(join8(dir, ...w.split("/"))).then(() => true, () => false))
       out.push(w);
   }
   return [...new Set(out)].sort();
@@ -1592,7 +1633,7 @@ async function stageFiles(dir, step) {
 async function walk(dir, rel = "") {
   let entries;
   try {
-    entries = await readdir4(join7(dir, rel), { withFileTypes: true });
+    entries = await readdir5(join8(dir, rel), { withFileTypes: true });
   } catch {
     return [];
   }
@@ -1615,7 +1656,7 @@ async function artifactFiles(dir, artifact) {
   }
   const f = `${artifact}.md`;
   try {
-    await readFile6(join7(dir, f));
+    await readFile7(join8(dir, f));
     return [f];
   } catch {
     return [];
@@ -1634,6 +1675,9 @@ var FILE = {
   tasks: "tasks.md",
   snow: "snow.md"
 };
+async function artifactWritten(root, change, artifact) {
+  return (await checkArtifacts(root, { id: change }, [artifact])).length === 0;
+}
 async function checkArtifacts(root, change, artifacts) {
   const dir = changeFolder(root, change.id);
   const reasons = [];
@@ -1645,7 +1689,7 @@ async function checkArtifacts(root, change, artifacts) {
       reasons.push({ code: "missing-artifact", artifact: a, message: `${FILE[a]} is missing.` });
       continue;
     }
-    const texts = await Promise.all(files.map((f) => readFile6(join7(dir, f), "utf8")));
+    const texts = await Promise.all(files.map((f) => readFile7(join8(dir, f), "utf8")));
     if (!texts.some(isFilled)) {
       reasons.push({
         code: "unfilled-artifact",
@@ -1659,25 +1703,25 @@ async function checkArtifacts(root, change, artifacts) {
 async function checkFindings(root, change, gates) {
   const reasons = [];
   for (const gate of gates) {
-    const base = join7(changeFolder(root, change.id), "review", gate);
+    const base = join8(changeFolder(root, change.id), "review", gate);
     let rounds;
     try {
-      rounds = (await readdir4(base, { withFileTypes: true })).filter((d) => d.isDirectory() && /^\d+$/.test(d.name)).map((d) => Number(d.name));
+      rounds = (await readdir5(base, { withFileTypes: true })).filter((d) => d.isDirectory() && /^\d+$/.test(d.name)).map((d) => Number(d.name));
     } catch {
       continue;
     }
     if (rounds.length === 0)
       continue;
     const round2 = Math.max(...rounds);
-    const dir = join7(base, String(round2));
-    const files = (await readdir4(dir)).filter((f) => /\.ya?ml$/.test(f)).sort();
+    const dir = join8(base, String(round2));
+    const files = (await readdir5(dir)).filter((f) => /\.ya?ml$/.test(f)).sort();
     const unfinished = {
       code: "round-unfinished",
       message: `Critic round ${round2} on the ${gate} gate didn't finish: run atticus critic ${change.id} --gate ${gate} again.`
     };
     let hasMeta = false;
     try {
-      const meta = (0, import_yaml5.parse)(await readFile6(join7(dir, "meta", "round.yaml"), "utf8"));
+      const meta = (0, import_yaml5.parse)(await readFile7(join8(dir, "meta", "round.yaml"), "utf8"));
       hasMeta = true;
       if (meta?.state === "in-progress") {
         reasons.push(unfinished);
@@ -1704,7 +1748,7 @@ async function checkFindings(root, change, gates) {
       const rel = `review/${gate}/${round2}/${f}`;
       let data;
       try {
-        data = (0, import_yaml5.parse)(await readFile6(join7(dir, f), "utf8"));
+        data = (0, import_yaml5.parse)(await readFile7(join8(dir, f), "utf8"));
       } catch {
         data = void 0;
       }
@@ -1752,7 +1796,7 @@ function mandatoryGates(ctx) {
 async function checkMandatoryRounds(root, change, gates) {
   const reasons = [];
   for (const gate of gates) {
-    const rounds = await readdir4(join7(changeFolder(root, change.id), "review", gate), {
+    const rounds = await readdir5(join8(changeFolder(root, change.id), "review", gate), {
       withFileTypes: true
     }).then((ds) => ds.filter((d) => d.isDirectory() && /^\d+$/.test(d.name)), () => []);
     if (rounds.length === 0)
@@ -1780,15 +1824,31 @@ function sha256(text) {
 
 // packages/changes/dist/progress.js
 var import_yaml6 = __toESM(require_dist(), 1);
-import { readFile as readFile7 } from "node:fs/promises";
-import { join as join8 } from "node:path";
+import { readFile as readFile8 } from "node:fs/promises";
+import { join as join9 } from "node:path";
+function phaseIndex(state) {
+  if (state === "draft" || state === "returned")
+    return 0;
+  if (state === "release-ready")
+    return PHASES.indexOf("release");
+  const i = PHASES.indexOf(state);
+  return i >= 0 ? i : PHASES.length;
+}
 async function stageCompletion(ctx, change) {
   const dir = changeFolder(ctx.root, change.id);
   const out = [];
   for (const s of ctx.policy.stages) {
-    const text = await readFile7(join8(dir, ...s.loop.split("/")), "utf8").catch(() => void 0);
+    const text = await readFile8(join9(dir, ...s.loop.split("/")), "utf8").catch(() => void 0);
     let state = "not-started";
-    if (text !== void 0) {
+    if (text === void 0) {
+      const own = writesPlanning(s) ? await personWrittenPlanning(dir) : [];
+      if (own.length) {
+        out.push({ stage: s.stage, phase: s.phase, state: "person", files: own });
+        continue;
+      }
+      if (change.state && phaseIndex(change.state) > PHASES.indexOf(s.phase))
+        state = "skipped";
+    } else {
       try {
         const y = (0, import_yaml6.parse)(text);
         state = typeof y?.state === "string" ? y.state : "unknown";
@@ -1803,7 +1863,7 @@ async function stageCompletion(ctx, change) {
 var cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
 var and = (xs) => xs.length <= 1 ? xs[0] ?? "" : `${xs.slice(0, -1).join(", ")} and ${xs.at(-1)}`;
 function workProgress(type, state, stages, raised = false) {
-  if (stages.every((s) => s.state === "not-started"))
+  if (stages.every((s) => stageIdle(s.state)))
     return void 0;
   const phase = state === "returned" ? type.phases[0] : statePhase(state);
   if (!phase)
@@ -1812,21 +1872,22 @@ function workProgress(type, state, stages, raised = false) {
   const own = stages.filter((s) => type.phases.includes(s.phase));
   if (own.length && own.every((s) => type.phases.indexOf(s.phase) < at))
     return void 0;
-  const done = own.filter((s) => s.state === "done").map((s) => s.stage);
-  const ahead = own.filter((s) => s.state === "done" && type.phases.indexOf(s.phase) > at).map((s) => s.phase);
+  const done = own.filter((s) => stageWorkDone(s.state)).map((s) => s.stage);
+  const ahead = own.filter((s) => stageWorkDone(s.state) && type.phases.indexOf(s.phase) > at).map((s) => s.phase);
   const current = own.find((s) => s.phase === phase);
-  const under = own.find((s) => s.state !== "done" && s.state !== "not-started");
-  const last = own.filter((s) => s.state === "done").at(-1);
+  const under = own.find((s) => !stageWorkDone(s.state) && !stageIdle(s.state));
+  const last = own.filter((s) => stageWorkDone(s.state)).at(-1);
+  const said = (s) => s.state === "person" ? `${s.stage} (written by a person)` : s.stage;
   const name = handoffName(type, phase);
   let summary;
   if (under)
     summary = `The ${under.stage} stage is ${under.state === "questions" ? "waiting on answers" : under.state}${done.length ? ` (${and(done)} done)` : ""}; the change is in ${state}.`;
-  else if (!current || current.state !== "done")
+  else if (!current || !stageWorkDone(current.state))
     summary = `${done.length ? `${cap(and(done))} done; ` : ""}the ${current?.stage ?? phase} stage hasn't run yet; the change is in ${state}.`;
   else if (ahead.length)
-    summary = `${cap(last.stage)} done; the change is still in ${state}: ${raised ? "merge" : "raise"} "${name}" (the ${phase} hand-off), then the ${and(ahead)} hand-offs.`;
+    summary = `${cap(said(last))} done; the change is still in ${state}: ${raised ? "merge" : "raise"} "${name}" (the ${phase} hand-off), then the ${and(ahead)} hand-offs.`;
   else
-    summary = `${cap(current.stage)} done; waiting on "${name}" (the ${phase} hand-off${raised ? " PR to merge" : ", not raised yet"}).`;
+    summary = `${cap(said(current))} done; waiting on "${name}" (the ${phase} hand-off${raised ? " PR to merge" : ", not raised yet"}).`;
   return { done, ahead, summary };
 }
 
@@ -1847,20 +1908,20 @@ function prApprovers(handoff2, approvers) {
 }
 
 // packages/changes/dist/assess.js
-import { readFile as readFile10 } from "node:fs/promises";
-import { join as join11 } from "node:path";
+import { readFile as readFile11 } from "node:fs/promises";
+import { join as join12 } from "node:path";
 
 // packages/changes/dist/release-prs.js
 var import_yaml8 = __toESM(require_dist(), 1);
-import { readFile as readFile9, writeFile } from "node:fs/promises";
+import { readFile as readFile10, writeFile } from "node:fs/promises";
 import { existsSync as existsSync2 } from "node:fs";
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 
 // packages/changes/dist/task-branches.js
 var import_yaml7 = __toESM(require_dist(), 1);
 import { existsSync } from "node:fs";
-import { readdir as readdir5, readFile as readFile8 } from "node:fs/promises";
-import { join as join9 } from "node:path";
+import { readdir as readdir6, readFile as readFile9 } from "node:fs/promises";
+import { join as join10 } from "node:path";
 var TASK_DECISION_FILE = "decision.yaml";
 var TaskDecision = external_exports.strictObject({
   schemaVersion: external_exports.literal(1),
@@ -1873,12 +1934,12 @@ var TaskDecision = external_exports.strictObject({
   reason: external_exports.string().min(1)
 });
 async function taskRefs(root, id) {
-  const dir = join9(changeFolder(root, id), "tasks");
+  const dir = join10(changeFolder(root, id), "tasks");
   const out = [];
-  for (const d of await readdir5(dir, { withFileTypes: true }).catch(() => [])) {
+  for (const d of await readdir6(dir, { withFileTypes: true }).catch(() => [])) {
     if (!d.isDirectory())
       continue;
-    const text = await readFile8(join9(dir, d.name, "task-run.yaml"), "utf8").catch(() => void 0);
+    const text = await readFile9(join10(dir, d.name, "task-run.yaml"), "utf8").catch(() => void 0);
     let y;
     try {
       y = text ? (0, import_yaml7.parse)(text) : void 0;
@@ -1906,7 +1967,7 @@ async function taskRefs(root, id) {
   return out;
 }
 function repoDir(root, r) {
-  const dirs = [join9(root, r.worktree)];
+  const dirs = [join10(root, r.worktree)];
   try {
     dirs.push(baseClonePath(root, r.id));
   } catch {
@@ -1914,7 +1975,7 @@ function repoDir(root, r) {
   return dirs.find((d) => existsSync(d));
 }
 async function readTaskDecision(root, id, task) {
-  const text = await readFile8(join9(changeFolder(root, id), "tasks", task, TASK_DECISION_FILE), "utf8").catch(() => void 0);
+  const text = await readFile9(join10(changeFolder(root, id), "tasks", task, TASK_DECISION_FILE), "utf8").catch(() => void 0);
   if (text === void 0)
     return void 0;
   try {
@@ -2031,7 +2092,7 @@ async function recordTaskDecision(root, id, task, o) {
     at: o.at,
     reason
   });
-  await writeFileAtomic(join9(changeFolder(root, id), "tasks", task, TASK_DECISION_FILE), toCanonicalYaml(d, ["schemaVersion", "task", "branch", "commit"]));
+  await writeFileAtomic(join10(changeFolder(root, id), "tasks", task, TASK_DECISION_FILE), toCanonicalYaml(d, ["schemaVersion", "task", "branch", "commit"]));
   return d;
 }
 
@@ -2066,7 +2127,7 @@ var NothingFile = external_exports.strictObject({
 });
 async function readReleaseFile(root, id) {
   const empty = { schemaVersion: 1, nothingToRelease: [] };
-  const text = await readFile9(join10(changeFolder(root, id), RELEASE_PRS_FILE), "utf8").catch(() => void 0);
+  const text = await readFile10(join11(changeFolder(root, id), RELEASE_PRS_FILE), "utf8").catch(() => void 0);
   if (text === void 0)
     return empty;
   try {
@@ -2081,14 +2142,14 @@ async function readNothing(root, id) {
 }
 async function writeReleaseFile(root, id, nothing, merged) {
   const byRepo = (xs) => [...xs].sort((a, b) => a.repo < b.repo ? -1 : a.repo > b.repo ? 1 : 0);
-  await writeFile(join10(changeFolder(root, id), RELEASE_PRS_FILE), toCanonicalYaml(NothingFile.parse({
+  await writeFile(join11(changeFolder(root, id), RELEASE_PRS_FILE), toCanonicalYaml(NothingFile.parse({
     schemaVersion: 1,
     nothingToRelease: byRepo(nothing),
     ...merged.length ? { merged: byRepo(merged) } : {}
   })), "utf8");
 }
 function repoDir2(root, r) {
-  const dirs = [join10(root, r.worktree)];
+  const dirs = [join11(root, r.worktree)];
   try {
     dirs.push(baseClonePath(root, r.id));
   } catch {
@@ -2259,7 +2320,7 @@ async function raiseReleasePrs(root, id, o) {
       continue;
     }
     const notes = movedOn ? [movedOn] : [];
-    const dir = join10(root, r.worktree);
+    const dir = join11(root, r.worktree);
     if (existsSync2(dir)) {
       const onHost = await git(["ls-remote", "--heads", remote, `refs/heads/${r.branch}`], dir).then((x) => x.stdout.trim() ? "yes" : "no").catch((e) => {
         notes.push(`Atticus couldn't reach ${remote} (${firstLine(e)}): push ${r.branch} yourself if the host lacks it.`);
@@ -2447,7 +2508,7 @@ function buildOf(pr) {
   return "passed";
 }
 async function requireMergedPrs(root) {
-  const text = await readFile9(join10(orgPackDirOf(root), "process", "ci.yaml"), "utf8").catch(() => void 0);
+  const text = await readFile10(join11(orgPackDirOf(root), "process", "ci.yaml"), "utf8").catch(() => void 0);
   if (text === void 0)
     return true;
   try {
@@ -2580,43 +2641,45 @@ async function changeReport(root, id) {
   const ctx = await loadChangeContext(root);
   const a = await assess(ctx, await changeStore(root).read(id));
   const tasks = a.phase === "build" ? await taskTicks(root, id) : void 0;
-  return { ...a, nextStep: nextStep(a, tasks), problems: ctx.problems };
+  const next = nextStep(a, tasks);
+  return { ...a, nextStep: next.text, ready: next.ready, problems: ctx.problems };
 }
 async function taskTicks(root, id) {
-  const text = await readFile10(join11(changeFolder(root, id), "tasks.md"), "utf8").catch(() => "");
+  const text = await readFile11(join12(changeFolder(root, id), "tasks.md"), "utf8").catch(() => "");
   const boxes = [...text.matchAll(/^\s*[-*]\s+\[([ xX])\]/gm)].map((m) => m[1] !== " ");
   return boxes.length ? { done: boxes.filter(Boolean).length, total: boxes.length } : void 0;
 }
 function nextStep(a, tasks) {
+  const not = (text) => ({ text, ready: false });
   switch (a.state) {
     case "draft":
-      return "Create the change with atticus change new.";
+      return not("Create the change with atticus change new.");
     case "archived":
-      return "Nothing: the change is archived.";
+      return not("Nothing: the change is archived.");
     case "released":
-      return "Archive the change.";
+      return not("Archive the change.");
     case "post-release-review":
-      return a.reasons.length ? "Resolve the post-release review findings, then archive the change." : "Review the skipped lenses, then archive the change.";
+      return not(a.reasons.length ? "Resolve the post-release review findings, then archive the change." : "Review the skipped lenses, then archive the change.");
     case "returned":
-      return `Revise the work, then hand off ${a.phase} again.`;
+      return not(`Revise the work, then hand off ${a.phase} again.`);
   }
   const name = handoffName(a.type, a.phase);
   if (!a.handoff) {
     if (!a.blockers.length && tasks && tasks.done < tasks.total)
-      return `Finish the ${a.phase} work (${tasks.done} of ${tasks.total} tasks ticked in tasks.md), then raise "${name}".`;
-    return a.blockers.length ? `Finish the ${a.phase} work, then raise "${name}".` : `Ready to raise "${name}".`;
+      return not(`Finish the ${a.phase} work (${tasks.done} of ${tasks.total} tasks ticked in tasks.md), then raise "${name}".`);
+    return a.blockers.length ? not(`Finish the ${a.phase} work, then raise "${name}".`) : { text: `Ready to raise "${name}".`, ready: true };
   }
   if (a.handoff.state === "changes-requested")
-    return `Update the artifacts and hand off again on PR #${a.handoff.pr.number}.`;
+    return not(`Update the artifacts and hand off again on PR #${a.handoff.pr.number}.`);
   if (isManualPrUrl(a.handoff.pr.url))
-    return manualHandoffWords(a.handoff.phase);
-  return `Merge PR #${a.handoff.pr.number} once it is approved (${a.handoff.pr.url}); syncing then moves the change on.`;
+    return not(manualHandoffWords(a.handoff.phase));
+  return not(`Merge PR #${a.handoff.pr.number} once it is approved (${a.handoff.pr.url}); syncing then moves the change on.`);
 }
 
 // packages/changes/dist/new-change.js
 var import_yaml9 = __toESM(require_dist(), 1);
-import { mkdir, readFile as readFile11, writeFile as writeFile2 } from "node:fs/promises";
-import { join as join12 } from "node:path";
+import { mkdir as mkdir2, readFile as readFile12, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join13 } from "node:path";
 var nowIso2 = () => (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
 var strip2 = (h) => h.startsWith("@") ? h.slice(1) : h;
 function windowsUnsafeName(id) {
@@ -2628,7 +2691,7 @@ function slugify(title) {
 }
 async function exists(path) {
   try {
-    await readFile11(path);
+    await readFile12(path);
     return true;
   } catch {
     return false;
@@ -2636,7 +2699,7 @@ async function exists(path) {
 }
 async function defaultSchema(root) {
   try {
-    const cfg = (0, import_yaml9.parse)(await readFile11(join12(openspecDirOf(root), "config.yaml"), "utf8"));
+    const cfg = (0, import_yaml9.parse)(await readFile12(join13(openspecDirOf(root), "config.yaml"), "utf8"));
     if (cfg && typeof cfg.schema === "string")
       return cfg.schema;
   } catch {
@@ -2660,17 +2723,17 @@ async function newChange(root, opts) {
   const now = opts.now ?? nowIso2();
   const by = strip2(opts.by);
   const dir = changeFolder(root, id);
-  if (opts.openspec && !await exists(join12(dir, ".openspec.yaml"))) {
+  if (opts.openspec && !await exists(join13(dir, ".openspec.yaml"))) {
     await opts.openspec.newChange(id, { description: opts.title });
   } else {
-    await mkdir(dir, { recursive: true });
-    if (!await exists(join12(dir, ".openspec.yaml")))
-      await writeFile2(join12(dir, ".openspec.yaml"), `schema: ${await defaultSchema(root)}
+    await mkdir2(dir, { recursive: true });
+    if (!await exists(join13(dir, ".openspec.yaml")))
+      await writeFile2(join13(dir, ".openspec.yaml"), `schema: ${await defaultSchema(root)}
 created: ${now.slice(0, 10)}
 `, "utf8");
   }
-  if (!await exists(join12(dir, "brief.md")))
-    await writeFileAtomic(join12(dir, "brief.md"), renderTemplate(template, {
+  if (!await exists(join13(dir, "brief.md")))
+    await writeFileAtomic(join13(dir, "brief.md"), renderTemplate(template, {
       title: opts.title,
       id,
       type: type.id,
@@ -2710,7 +2773,7 @@ created: ${now.slice(0, 10)}
 // packages/changes/dist/publish.js
 import { rm } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { join as join13, resolve } from "node:path";
+import { join as join14, resolve } from "node:path";
 function gitHandoffPublisher(opts = {}) {
   const remote = opts.remote ?? "origin";
   const env = opts.env ?? process.env;
@@ -2744,7 +2807,7 @@ function gitHandoffPublisher(opts = {}) {
         "--quiet",
         `refs/remotes/${remote}/${base}^{commit}`
       ]) ?? await out(["rev-parse", "--verify", `refs/heads/${base}^{commit}`]);
-      const index = join13(gitDir, `atticus-handoff-index-${process.pid}-${randomUUID()}`);
+      const index = join14(gitDir, `atticus-handoff-index-${process.pid}-${randomUUID()}`);
       const staged = createGit({ env: { ...env, GIT_INDEX_FILE: index } });
       try {
         await staged(["read-tree", start], root);
@@ -2799,13 +2862,13 @@ async function keepLocalBranch(out, tryOut, branch, start, commit) {
 }
 
 // packages/changes/dist/handoff.js
-import { readdir as readdir7, readFile as readFile13 } from "node:fs/promises";
-import { join as join15 } from "node:path";
+import { readdir as readdir8, readFile as readFile14 } from "node:fs/promises";
+import { join as join16 } from "node:path";
 
 // packages/changes/dist/drafted.js
 var import_yaml10 = __toESM(require_dist(), 1);
-import { mkdir as mkdir2, readdir as readdir6, readFile as readFile12, rm as rm2 } from "node:fs/promises";
-import { dirname, join as join14, relative, sep } from "node:path";
+import { mkdir as mkdir3, readdir as readdir7, readFile as readFile13, rm as rm2 } from "node:fs/promises";
+import { dirname as dirname2, join as join15, relative, sep } from "node:path";
 var CAPTURE_SCHEMA_VERSION = 1;
 var DraftCapture = external_exports.object({
   schemaVersion: external_exports.literal(CAPTURE_SCHEMA_VERSION),
@@ -2880,7 +2943,7 @@ var sameText = (text, recorded) => sha256(text) === recorded || sha256(text.repl
 async function walk2(dir, rel = "") {
   let entries;
   try {
-    entries = await readdir6(join14(dir, rel), { withFileTypes: true });
+    entries = await readdir7(join15(dir, rel), { withFileTypes: true });
   } catch {
     return [];
   }
@@ -3025,7 +3088,7 @@ async function captureHandoff(input) {
   } else {
     const texts = await Promise.all(recorded.map(async (r) => [
       r,
-      await readFile12(join14(folder, ...r.path.split("/")), "utf8").catch(() => void 0)
+      await readFile13(join15(folder, ...r.path.split("/")), "utf8").catch(() => void 0)
     ]));
     if (texts.every(([r, t]) => t !== void 0 && sameText(t, r.sha256))) {
       from = "working-tree";
@@ -3089,11 +3152,11 @@ async function captureHandoff(input) {
     } : {}
   };
   const p = capturePaths(name);
-  await rm2(join14(folder, ...p.drafted.split("/")), { recursive: true, force: true });
-  await rm2(join14(folder, ...p.merged.split("/")), { recursive: true, force: true });
+  await rm2(join15(folder, ...p.drafted.split("/")), { recursive: true, force: true });
+  await rm2(join15(folder, ...p.merged.split("/")), { recursive: true, force: true });
   const put = async (base, rel, text) => {
-    const f = join14(folder, ...base.split("/"), ...rel.split("/"));
-    await mkdir2(dirname(f), { recursive: true });
+    const f = join15(folder, ...base.split("/"), ...rel.split("/"));
+    await mkdir3(dirname2(f), { recursive: true });
     await writeFileAtomic(f, text);
   };
   for (const [rel, t] of draftedFiles)
@@ -3101,37 +3164,37 @@ async function captureHandoff(input) {
   if (state === "captured")
     for (const [rel, t] of mergedFiles)
       await put(p.merged, rel, t);
-  await mkdir2(join14(folder, "stage"), { recursive: true });
-  await writeFileAtomic(join14(folder, ...p.capture.split("/")), HEADER + (0, import_yaml10.stringify)(capture, { lineWidth: 0 }));
+  await mkdir3(join15(folder, "stage"), { recursive: true });
+  await writeFileAtomic(join15(folder, ...p.capture.split("/")), HEADER + (0, import_yaml10.stringify)(capture, { lineWidth: 0 }));
   return { capture, file: p.capture };
 }
 async function readFolderFiles(dir) {
   const out = /* @__PURE__ */ new Map();
   for (const f of await walk2(dir))
-    out.set(f, (await readFile12(join14(dir, ...f.split("/")), "utf8")).replace(/\r\n/g, "\n"));
+    out.set(f, (await readFile13(join15(dir, ...f.split("/")), "utf8")).replace(/\r\n/g, "\n"));
   return out;
 }
 async function changeFolders(root) {
-  const base = join14(root, ...changesRelOf(root).split("/"));
+  const base = join15(root, ...changesRelOf(root).split("/"));
   const out = [];
-  const list = async (dir) => (await readdir6(dir, { withFileTypes: true }).catch(() => [])).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  const list = async (dir) => (await readdir7(dir, { withFileTypes: true }).catch(() => [])).filter((e) => e.isDirectory()).map((e) => e.name).sort();
   for (const name of await list(base)) {
     if (name === "archive")
-      for (const a of await list(join14(base, "archive")))
-        out.push(join14(base, "archive", a));
+      for (const a of await list(join15(base, "archive")))
+        out.push(join15(base, "archive", a));
     else
-      out.push(join14(base, name));
+      out.push(join15(base, name));
   }
   return out;
 }
 async function readDraftPairs(root) {
   const out = [];
   for (const folder of await changeFolders(root)) {
-    const names = (await readdir6(join14(folder, "stage")).catch(() => [])).filter((f) => f.endsWith(".capture.yaml")).sort();
+    const names = (await readdir7(join15(folder, "stage")).catch(() => [])).filter((f) => f.endsWith(".capture.yaml")).sort();
     for (const f of names) {
       let capture;
       try {
-        capture = DraftCapture.parse((0, import_yaml10.parse)(await readFile12(join14(folder, "stage", f), "utf8")));
+        capture = DraftCapture.parse((0, import_yaml10.parse)(await readFile13(join15(folder, "stage", f), "utf8")));
       } catch {
         continue;
       }
@@ -3139,8 +3202,8 @@ async function readDraftPairs(root) {
       out.push({
         capture,
         folder: relative(root, folder).split(sep).join("/"),
-        drafted: await readFolderFiles(join14(folder, ...p.drafted.split("/"))),
-        merged: await readFolderFiles(join14(folder, ...p.merged.split("/")))
+        drafted: await readFolderFiles(join15(folder, ...p.drafted.split("/"))),
+        merged: await readFolderFiles(join15(folder, ...p.merged.split("/")))
       });
     }
   }
@@ -3160,8 +3223,8 @@ async function completeCaptures(root, ctx, o) {
       continue;
     for (const h of change.handoffs.filter((x) => x.state === "merged")) {
       const { name } = await captureStageOf(ctx, change, h.phase);
-      const file = join14(changeFolder(root, change.id), ...capturePaths(name).capture.split("/"));
-      const prior = await readFile12(file, "utf8").then((t) => DraftCapture.safeParse((0, import_yaml10.parse)(t)), () => void 0);
+      const file = join15(changeFolder(root, change.id), ...capturePaths(name).capture.split("/"));
+      const prior = await readFile13(file, "utf8").then((t) => DraftCapture.safeParse((0, import_yaml10.parse)(t)), () => void 0);
       if (prior?.success && prior.data.pr.number === h.pr.number && prior.data.state !== "waiting-for-merge")
         continue;
       const base = prior?.success ? prior.data.base : o.defaultBase ?? "main";
@@ -3202,16 +3265,16 @@ async function load(root, id) {
 }
 async function walkReview(dir, gate) {
   const out = [];
-  const base = join15(dir, "review", gate);
+  const base = join16(dir, "review", gate);
   let rounds;
   try {
-    rounds = (await readdir7(base)).filter((r) => /^\d+$/.test(r)).sort((a, b) => Number(a) - Number(b));
+    rounds = (await readdir8(base)).filter((r) => /^\d+$/.test(r)).sort((a, b) => Number(a) - Number(b));
   } catch {
     return [];
   }
   for (const r of rounds) {
     try {
-      for (const f of (await readdir7(join15(base, r))).filter((x) => /\.ya?ml$/.test(x)).sort())
+      for (const f of (await readdir8(join16(base, r))).filter((x) => /\.ya?ml$/.test(x)).sort())
         out.push(`review/${gate}/${r}/${f}`);
     } catch {
     }
@@ -3222,12 +3285,12 @@ async function keptPairFiles(dir) {
   const out = [];
   let entries;
   try {
-    entries = await readdir7(join15(dir, "stage"), { withFileTypes: true });
+    entries = await readdir8(join16(dir, "stage"), { withFileTypes: true });
   } catch {
     return out;
   }
   const walk3 = async (rel) => {
-    for (const e of await readdir7(join15(dir, ...rel.split("/")), { withFileTypes: true }).catch(() => [])) {
+    for (const e of await readdir8(join16(dir, ...rel.split("/")), { withFileTypes: true }).catch(() => [])) {
       const p = `${rel}/${e.name}`;
       if (e.isDirectory())
         await walk3(p);
@@ -3261,7 +3324,7 @@ async function handoffFiles(ctx, a, phase) {
       for (const f of await stageFiles(dir, step))
         files.add(f);
   }
-  const present = async (f) => readFile13(join15(dir, ...f.split("/"))).then(() => true, () => false);
+  const present = async (f) => readFile14(join16(dir, ...f.split("/"))).then(() => true, () => false);
   for (const own of [
     "stage/corrections.yaml",
     "stage/drafted.yaml",
@@ -3274,7 +3337,7 @@ async function handoffFiles(ctx, a, phase) {
     for (const extra of ["tasks.md", "repos.yaml"])
       if (await present(extra))
         files.add(extra);
-    for (const t of await readdir7(join15(dir, "tasks"), { withFileTypes: true }).catch(() => []))
+    for (const t of await readdir8(join16(dir, "tasks"), { withFileTypes: true }).catch(() => []))
       if (t.isDirectory() && await present(`tasks/${t.name}/report.md`))
         files.add(`tasks/${t.name}/report.md`);
   }
@@ -3348,7 +3411,7 @@ async function handoff(root, id, opts) {
     await requireValid(opts.openspec, id);
   const { files, artifacts } = await handoffFiles(ctx, a, phase);
   const dir = changeFolder(root, id);
-  const hashed = await Promise.all(files.map(async (path) => ({ path, sha256: sha256(await readFile13(join15(dir, path))) })));
+  const hashed = await Promise.all(files.map(async (path) => ({ path, sha256: sha256(await readFile14(join16(dir, path))) })));
   const authors = { ...change.authors };
   for (const art of artifacts) {
     const people = (opts.authors?.[art] ?? [by]).map(strip3);
@@ -3711,8 +3774,8 @@ async function archiveChange(root, id, opts) {
 
 // packages/changes/dist/learn.js
 var import_yaml11 = __toESM(require_dist(), 1);
-import { readFile as readFile14 } from "node:fs/promises";
-import { join as join16 } from "node:path";
+import { readFile as readFile15 } from "node:fs/promises";
+import { join as join17 } from "node:path";
 var LEARN_SCHEMA_VERSION = 1;
 var MAX_CELLS = 4e6;
 var lines = (text) => {
@@ -4101,7 +4164,7 @@ async function pairTouches(root, p) {
         flows.push(m[1]);
     }
   }
-  const change = yaml(await readFile14(join16(root, ...p.folder.split("/"), "change.yaml"), "utf8").catch(() => ""));
+  const change = yaml(await readFile15(join17(root, ...p.folder.split("/"), "change.yaml"), "utf8").catch(() => ""));
   const touches = change?.touches ?? {};
   for (const r of Array.isArray(touches.repos) ? touches.repos : [])
     if (typeof r === "string")
@@ -4194,8 +4257,8 @@ async function detectConflicts(root) {
 }
 
 // packages/changes/dist/size.js
-import { readFile as readFile15 } from "node:fs/promises";
-import { join as join17 } from "node:path";
+import { readFile as readFile16 } from "node:fs/promises";
+import { join as join18 } from "node:path";
 async function changeSize(ctx, change) {
   const type = ctx.orgPack.changeTypes.types.find((t) => t.id === change.type);
   if (!type)
@@ -4204,7 +4267,7 @@ async function changeSize(ctx, change) {
       why: "standard",
       words: `${change.type} isn't a change type in change-types.yaml, so ${change.id} takes the full path.`
     };
-  const brief = await readFile15(join17(changeFolder(ctx.root, change.id), "brief.md"), "utf8").catch(() => "");
+  const brief = await readFile16(join18(changeFolder(ctx.root, change.id), "brief.md"), "utf8").catch(() => "");
   const f = fastPathOf(type, brief);
   const gate = f.fast ? fastGateOf(type, ctx.orgPack.gates) : void 0;
   const words = {
@@ -4219,12 +4282,12 @@ async function changeSize(ctx, change) {
 
 // packages/changes/dist/openspec-stores.js
 import { existsSync as existsSync3 } from "node:fs";
-import { readFile as readFile16, writeFile as writeFile3 } from "node:fs/promises";
+import { readFile as readFile17, writeFile as writeFile3 } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, isAbsolute, join as join18, relative as relative2, resolve as resolve2, sep as sep2 } from "node:path";
+import { basename, isAbsolute, join as join19, relative as relative2, resolve as resolve2, sep as sep2 } from "node:path";
 function storeDirOf(root, path) {
   if (path === "~" || path.startsWith("~/") || path.startsWith("~\\"))
-    return join18(homedir(), path.slice(2));
+    return join19(homedir(), path.slice(2));
   return isAbsolute(path) ? resolve2(path) : resolve2(root, path);
 }
 function packRel(root) {
@@ -4254,7 +4317,7 @@ async function storeSpecLookup(root, capability) {
 var REMOTE = /^[a-z][a-z0-9+.-]*:\/\//i;
 var SCP = /^[^/\\]+@[^:/\\]+:/;
 async function metarepoOrigin(root, git = createGit()) {
-  if (!existsSync3(join18(root, ".git")))
+  if (!existsSync3(join19(root, ".git")))
     return void 0;
   try {
     const url = (await git(["remote", "get-url", "origin"], root)).stdout.trim();
@@ -4277,8 +4340,8 @@ async function referenceMetarepoIn(root, repoDir3, o = {}) {
       file,
       why: marker.missing ? `this metarepo isn't an OpenSpec store yet (no ${STORE_MARKER}): run atticus upgrade --openspec-store, commit the file, then hand down again` : `this metarepo's ${STORE_MARKER} can't be read (${marker.notes.join("; ")})`
     };
-  const path = join18(repoDir3, "openspec", "config.yaml");
-  const text = await readFile16(path, "utf8").catch(() => void 0);
+  const path = join19(repoDir3, "openspec", "config.yaml");
+  const text = await readFile17(path, "utf8").catch(() => void 0);
   if (text === void 0)
     return {
       action: "skipped",
@@ -4529,6 +4592,15 @@ export {
   scoreRisk,
   testsFor,
   testPlanFor,
+  GENERATED_MARK,
+  PLANNING_FILES,
+  isGenerated,
+  personWritten,
+  keepPersonWritten,
+  personWrittenPlanning,
+  writesPlanning,
+  stageWorkDone,
+  stageIdle,
   phaseState,
   statePhase,
   nextState,
@@ -4541,6 +4613,7 @@ export {
   checkStage,
   stageFiles,
   artifactFiles,
+  artifactWritten,
   checkArtifacts,
   checkFindings,
   mandatoryGates,