halfcycle 0.3.17 → 0.3.18

package/dist/bin.js

@@ -3,7 +3,7 @@
 // dist/bin.js
 import { execFileSync as execFileSync4 } from "node:child_process";
 import { readFileSync as readFileSync9 } from "node:fs";
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 
 // dist/install.js
 import { existsSync as existsSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync5, rmSync, writeFileSync as writeFileSync4 } from "node:fs";
@@ -61,11 +61,26 @@ var firedGuardSchema = z2.object({
    */
   path: z2.string().optional()
 }).strict();
+var notRunCheckSchema = z2.object({
+  /** Which check did not run, by the same reference a fired check carries. */
+  patternRef: z2.string(),
+  /**
+   * Why it could not run, in plain words — what this client did not send, or
+   * that the check's kind is not implemented yet. Never the check's own rule.
+   */
+  reason: z2.string()
+}).strict();
 var resultEnvelopeSchema = z2.object({
   guardsFired: z2.array(firedGuardSchema),
   severity: severitySchema.nullable(),
   blocking: z2.boolean(),
-  explanation: z2.string()
+  explanation: z2.string(),
+  /**
+   * The checks that could not run on this edit, each named with the reason.
+   * Absent when every check ran — so an evaluation where nothing was skipped
+   * looks exactly as it always has, and an absent list is never an empty one.
+   */
+  notRun: z2.array(notRunCheckSchema).optional()
 }).strict();
 var wireErrorSchema = z2.object({
   statusCode: z2.number(),
@@ -436,6 +451,65 @@ function safeParseAccountIdentity(payload) {
   return accountIdentitySchema.safeParse(payload);
 }
 
+// ../events/dist/phase-identity.js
+var PHASE_SEGMENT_PREFIX = "phase-";
+function isValidPhaseIdentity(identity) {
+  if (typeof identity === "number")
+    return Number.isInteger(identity) && identity >= 0;
+  if (typeof identity !== "string")
+    return false;
+  if (identity === "")
+    return false;
+  if (identity.includes("/"))
+    return false;
+  if (identity.includes("\\"))
+    return false;
+  if (identity.includes("\0"))
+    return false;
+  if (identity.startsWith("."))
+    return false;
+  return true;
+}
+var InvalidPhaseIdentityError = class extends Error {
+  /** The value that was refused, exactly as supplied. */
+  identity;
+  constructor(identity, allowedLocation) {
+    const subject = allowedLocation === void 0 ? "a file" : "a Build Record";
+    const where = allowedLocation === void 0 ? "" : `
+  Records are written only into ${allowedLocation.replace(/\\/g, "/")}/. Nothing was written.`;
+    super(`that phase identity cannot name ${subject}.
+  identity: ${describeIdentity(identity)}` + where);
+    this.name = "InvalidPhaseIdentityError";
+    this.identity = identity;
+  }
+};
+function assertValidPhaseIdentity(identity, allowedLocation) {
+  if (!isValidPhaseIdentity(identity)) {
+    throw new InvalidPhaseIdentityError(identity, allowedLocation);
+  }
+}
+function renderPhaseSegment(identity) {
+  if (!isValidPhaseIdentity(identity)) {
+    throw new InvalidPhaseIdentityError(identity);
+  }
+  return `${PHASE_SEGMENT_PREFIX}${identity}`;
+}
+function describeIdentity(identity) {
+  if (typeof identity === "string")
+    return identity;
+  if (identity === null)
+    return "null";
+  if (identity === void 0)
+    return "none supplied";
+  if (typeof identity === "number" || typeof identity === "boolean")
+    return String(identity);
+  if (Array.isArray(identity))
+    return "(a list)";
+  if (typeof identity === "object")
+    return "(an object)";
+  return `(a ${typeof identity})`;
+}
+
 // dist/engagement-credential.js
 import { chmodSync as chmodSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { platform as platform2 } from "node:os";
@@ -535,6 +609,7 @@ var ENGAGEMENT_ENV_KEYS = [
   ...GUARD_ENV_KEYS,
   "CONTROL_TELEMETRY_URL"
 ];
+var PHASE_STAMP_ENV_KEY = "HALFCYCLE_PHASE";
 var ENV_HEADER = "# Halfcycle per-engagement credential \u2014 machine level, owner-only, never in a repository.";
 function shq(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -562,33 +637,50 @@ function parseEnvText(raw) {
   return out;
 }
 function reconcileEnvText(existing, values, keys = ENGAGEMENT_ENV_KEYS) {
-  const desired = new Map(keys.map((k) => [k, values[k] ?? ""]));
+  const desired = new Map(keys.map((k) => {
+    const value = values[k];
+    return [k, value === void 0 ? "" : value];
+  }));
   const line = (k) => `${k}=${shq(desired.get(k) ?? "")}`;
+  const written = keys.filter((k) => desired.get(k) !== null);
   if (existing === null) {
+    if (written.length === 0)
+      return "";
     return `${ENV_HEADER}
-` + keys.map(line).join("\n") + "\n";
+` + written.map(line).join("\n") + "\n";
   }
   const seen = /* @__PURE__ */ new Set();
-  const out = existing.split("\n").map((existingLine) => {
+  const out = [];
+  for (const existingLine of existing.split("\n")) {
     const eq = existingLine.indexOf("=");
-    if (eq === -1)
-      return existingLine;
+    if (eq === -1) {
+      out.push(existingLine);
+      continue;
+    }
     const lhs = existingLine.slice(0, eq);
     const exported = /^\s*export\s+/.exec(lhs);
     const prefix = exported === null ? "" : exported[0];
     const key = lhs.slice(prefix.length).trim();
-    if (desired.has(key)) {
-      seen.add(key);
-      return `${prefix}${line(key)}`;
+    if (!desired.has(key)) {
+      out.push(existingLine);
+      continue;
     }
-    return existingLine;
-  });
-  const missing = keys.filter((k) => !seen.has(k));
+    seen.add(key);
+    if (desired.get(key) === null)
+      continue;
+    out.push(`${prefix}${line(key)}`);
+  }
+  const missing = written.filter((k) => !seen.has(k));
   if (missing.length > 0) {
+    const header = existing.includes(ENV_HEADER) ? "" : `${ENV_HEADER}
+`;
+    const block = header + missing.map(line).join("\n");
     const trailingBlank = out.length > 0 && out[out.length - 1] === "";
-    const prefix = trailingBlank ? "" : existing.endsWith("\n") ? "" : "\n";
-    out.push(`${prefix}${ENV_HEADER}
-` + missing.map(line).join("\n"));
+    if (trailingBlank)
+      out.splice(out.length - 1, 0, block);
+    else
+      out.push(`
+${block}`);
   }
   let result = out.join("\n");
   if (existing.endsWith("\n") && !result.endsWith("\n"))
@@ -602,17 +694,19 @@ function readEngagementEnv(engagementId, home) {
     return null;
   }
 }
-function writeEngagementEnv(engagementId, values, home) {
+function writeEngagementEnv(engagementId, values, home, keys = ENGAGEMENT_ENV_KEYS) {
   const path = engagementEnvPath(engagementId, home);
   const dir = engagementStateDir(engagementId, home);
-  mkdirSync2(dir, { recursive: true, mode: 448 });
   let existing;
   try {
     existing = readFileSync2(path, "utf-8");
   } catch {
     existing = null;
   }
-  const reconciled = reconcileEnvText(existing, values);
+  const reconciled = reconcileEnvText(existing, values, keys);
+  if (existing === null && reconciled === "")
+    return "skipped";
+  mkdirSync2(dir, { recursive: true, mode: 448 });
   const outcome = existing === reconciled ? "skipped" : "written";
   if (outcome === "written") {
     writeFileSync2(path, reconciled, { mode: 384 });
@@ -2816,8 +2910,203 @@ function projectSeedGuard(fired, includeExplanation) {
 // dist/build-record/sources.js
 import { readFileSync as readFileSync6, existsSync as existsSync4 } from "node:fs";
 import { createHash } from "node:crypto";
-import { join as join6 } from "node:path";
+import { join as join8 } from "node:path";
+
+// dist/build-record/close-record.js
 import { execFileSync as execFileSync2 } from "node:child_process";
+import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync5 } from "node:fs";
+import { dirname as dirname3, join as join6 } from "node:path";
+var CLOSE_RECORD_FORMAT = "halfcycle-phase-close/v1";
+var BUILD_RECORD_ZONE_B_DIR = join6(ZONE_B_DIR, "build-record");
+var InvalidCloseRecordError = class extends Error {
+  constructor(path, detail) {
+    super(`[build-record] the phase close record at ${path} cannot be read \u2014 ${detail}`);
+    this.name = "InvalidCloseRecordError";
+  }
+};
+function closeRecordPath(repoRoot, phase) {
+  assertValidPhaseIdentity(phase, BUILD_RECORD_ZONE_B_DIR);
+  return join6(repoRoot, BUILD_RECORD_ZONE_B_DIR, `${renderPhaseSegment(phase)}.close.json`);
+}
+function resolveCloseAtHead(repoRoot) {
+  try {
+    const closeCommit = execFileSync2("git", ["-C", repoRoot, "rev-parse", "--short", "HEAD"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    const closedDate = execFileSync2("git", ["-C", repoRoot, "show", "-s", "--format=%cs", "HEAD"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (closeCommit === "" || closedDate === "")
+      return null;
+    return { closeCommit, closedDate };
+  } catch {
+    return null;
+  }
+}
+function writeCloseRecord(repoRoot, phase) {
+  let path;
+  try {
+    path = closeRecordPath(repoRoot, phase);
+  } catch (err) {
+    return { recorded: false, path: null, reason: err instanceof Error ? err.message : String(err) };
+  }
+  const at = resolveCloseAtHead(repoRoot);
+  if (at === null) {
+    return {
+      recorded: false,
+      path,
+      reason: `the commit could not be read from ${repoRoot} \u2014 there is no git available, no repository there, or no commit in it yet`
+    };
+  }
+  const record2 = {
+    format: CLOSE_RECORD_FORMAT,
+    phase,
+    closeCommit: at.closeCommit,
+    closedDate: at.closedDate
+  };
+  try {
+    mkdirSync5(dirname3(path), { recursive: true });
+    writeFileSync5(path, JSON.stringify(record2, null, 2) + "\n", "utf-8");
+  } catch (err) {
+    return { recorded: false, path, reason: err instanceof Error ? err.message : String(err) };
+  }
+  return { recorded: true, path, closeCommit: at.closeCommit, closedDate: at.closedDate };
+}
+function parseCloseRecord(path, parsed) {
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new InvalidCloseRecordError(path, "it does not hold a record");
+  }
+  const record2 = parsed;
+  if (record2.format !== CLOSE_RECORD_FORMAT) {
+    throw new InvalidCloseRecordError(path, `it is not a ${CLOSE_RECORD_FORMAT} record (it says ${JSON.stringify(record2.format)})`);
+  }
+  const commit = record2.closeCommit;
+  const date = record2.closedDate;
+  const missing = [];
+  if (typeof commit !== "string" || commit.trim() === "")
+    missing.push("closeCommit");
+  if (typeof date !== "string" || date.trim() === "")
+    missing.push("closedDate");
+  if (missing.length > 0) {
+    throw new InvalidCloseRecordError(path, `${missing.join(" and ")} ${missing.length === 1 ? "is" : "are"} not recorded in it. A close records the commit and its date together or records neither, so a file carrying one of them was edited by hand.`);
+  }
+  if (typeof record2.phase !== "string" && typeof record2.phase !== "number") {
+    throw new InvalidCloseRecordError(path, "it does not say which phase closed");
+  }
+  return {
+    format: CLOSE_RECORD_FORMAT,
+    phase: record2.phase,
+    closeCommit: commit,
+    closedDate: date
+  };
+}
+
+// dist/build-record/write.js
+import { mkdirSync as mkdirSync6, writeFileSync as writeFileSync6 } from "node:fs";
+import { basename as basename2, join as join7, resolve as resolve2, relative as relative2, isAbsolute } from "node:path";
+
+// dist/build-record/template.js
+function severityLabel(seed) {
+  return `\`${seed.patternRef}\` (severity \`${seed.severity}\`)`;
+}
+var NOT_RECORDED = "not recorded";
+function renderCloseLine(record2) {
+  const status = `**Status:** ${record2.status.toUpperCase()}`;
+  const closed = `**Closed:** ${record2.closedDate ?? NOT_RECORDED}`;
+  const commit = record2.closeCommit === null ? `**Close commit:** ${NOT_RECORDED}` : `**Close commit:** \`${record2.closeCommit}\``;
+  return `${status} \xB7 ${closed} \xB7 ${commit}`;
+}
+function renderCloseProvenance(record2) {
+  return record2.closeCommit === null && record2.closedDate === null ? "*The close date and the commit were not recorded when this phase closed, so this record does not name them. Nothing has been substituted for them.*" : "*The close date and the commit are the client's own assertion about their own repository, written down when the phase was closed. Halfcycle did not observe them and does not check them.*";
+}
+function renderDoneWhenRows(record2) {
+  const rows = [];
+  for (const [key, dw] of Object.entries(record2.acceptance.doneWhen)) {
+    const mark = dw.result === "pass" ? "\u2705" : dw.result === "dropped" ? "\u2014" : dw.result;
+    rows.push(`| ${key} | ${mark} | ${dw.detail} |`);
+  }
+  return rows.join("\n");
+}
+function renderBuildRecordMarkdown(record2) {
+  const { phase } = record2;
+  const companion = `${renderPhaseSegment(phase.id)}.json`;
+  const guardsList = record2.seedGuards.map(severityLabel).join(", ");
+  const lines = [
+    // Fixed prose (vault-canonical template) + projected title slots.
+    `# Build Record \u2014 Phase ${phase.id}: ${phase.name}`,
+    "",
+    `**Format:** \`${record2.format}\` (markdown + JSON pair; portable, readable without Halfcycle systems)`,
+    "",
+    "> This Build Record was assembled automatically at phase close by the method bundle (`packages/bundle`). Every data field below is projected from the companion JSON \u2014 no record content is hand-authored.",
+    "",
+    `**Engagement:** ${record2.engagement} (${record2.engagementType})`,
+    `**Phase:** ${phase.id} \u2014 ${phase.name}`,
+    renderCloseLine(record2),
+    `**Companion:** [\`${companion}\`](${companion})`,
+    "",
+    renderCloseProvenance(record2),
+    "",
+    "## What this phase proved",
+    "",
+    `${record2.thesis} **Thesis held: ${record2.thesisHeld ? "yes" : "no"}.**`,
+    "",
+    "## Delivered",
+    "",
+    `- **Packages:** ${record2.delivered.packages.join(", ")}`,
+    `- **Services:** ${record2.delivered.services.join(", ")}`,
+    `- **Tools:** ${record2.delivered.tools.join(", ")}`,
+    `- **Dogfood:** ${record2.delivered.dogfood}`,
+    "",
+    guardsList ? `Guards evaluated (INV-007-safe results): ${guardsList}. *(Guard \`channel\`/\`version\` are guard-asset metadata, excluded from the v1 record \u2014 INV-007/INV-001.)*` : "No guards fired during this phase.",
+    "",
+    `## Acceptance (independent walk \u2014 walker ${record2.acceptance.walker})`,
+    "",
+    `**Verdict:** ${record2.acceptance.verdict} \xB7 **Findings:** ${record2.acceptance.findings}`,
+    "",
+    "| Done-when | Result | Evidence |",
+    "|---|---|---|",
+    renderDoneWhenRows(record2),
+    ""
+  ];
+  if (record2.acceptance.inv002ProdBypassProbe) {
+    lines.push(`**INV-002 production bypass probe:** ${record2.acceptance.inv002ProdBypassProbe.result} \u2014 ${record2.acceptance.inv002ProdBypassProbe.detail}`, "");
+  }
+  lines.push("## Gates that earned their keep", "", `**${record2.gatesEarnedKeep.defectsCaughtPreHuman}** defects were caught by the gates before the human walk; the walk itself found **${record2.gatesEarnedKeep.bugsReachingHumanWalk}**. Named: ${record2.gatesEarnedKeep.named.join("; ")}.`, "", "## Instruments", "", `- **Marginal-cost self-accounting:** ${record2.instruments.marginalCostSelfAccounting}`, `- **COE add-rate:** seam-new ${record2.instruments.coeAddRate.seamNew}, seam-repeat ${record2.instruments.coeAddRate.seamRepeat}, model-limitation ${record2.instruments.coeAddRate.modelLimitation}. ${record2.instruments.coeAddRate.notes}`, "", "## Invariants exercised", "", record2.invariantsExercised.join(", "), "", "## Deviations & decisions recorded", "", ...record2.deviations.map((d) => `- ${d}`), "", "## Tasks", "", `- **Planned:** ${record2.tasks.planned} \xB7 **Landed:** ${record2.tasks.landed} \xB7 **Cancelled:** ${record2.tasks.cancelled.length > 0 ? record2.tasks.cancelled.join(", ") : "none"}`, "");
+  return lines.join("\n");
+}
+
+// dist/build-record/write.js
+var BUILD_RECORD_DIR = join7("docs", "build-records");
+function serialiseRecordJson(record2) {
+  return JSON.stringify(record2, null, 2) + "\n";
+}
+function assertInsideOutDir(outDir, candidate, identity) {
+  const rel = relative2(outDir, resolve2(candidate));
+  const isPlainFilename = rel !== "" && rel !== ".." && !isAbsolute(rel) && rel === basename2(rel);
+  if (!isPlainFilename) {
+    throw new InvalidPhaseIdentityError(identity, BUILD_RECORD_DIR);
+  }
+}
+function writeBuildRecord(repoRoot, record2) {
+  const outDir = resolve2(repoRoot, BUILD_RECORD_DIR);
+  const identity = record2.phase.id;
+  if (!isValidPhaseIdentity(identity)) {
+    throw new InvalidPhaseIdentityError(identity, BUILD_RECORD_DIR);
+  }
+  const segment = renderPhaseSegment(identity);
+  const jsonPath = join7(outDir, `${segment}.json`);
+  const mdPath = join7(outDir, `${segment}.md`);
+  assertInsideOutDir(outDir, jsonPath, identity);
+  assertInsideOutDir(outDir, mdPath, identity);
+  mkdirSync6(outDir, { recursive: true });
+  writeFileSync6(jsonPath, serialiseRecordJson(record2), "utf-8");
+  writeFileSync6(mdPath, renderBuildRecordMarkdown(record2), "utf-8");
+  return { jsonPath, mdPath };
+}
+
+// dist/build-record/sources.js
 var MissingSourceError = class extends Error {
   constructor(sourceName, detail) {
     super(`[build-record] missing required source: ${sourceName} \u2014 ${detail}`);
@@ -2873,7 +3162,7 @@ function syntheticRunId(record2) {
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
 }
 function readGuardEvalLog(logDir, phaseId) {
-  const logPath = join6(logDir, `phase-${phaseId}.jsonl`);
+  const logPath = join8(logDir, `${renderPhaseSegment(phaseId)}.jsonl`);
   if (!existsSync4(logPath)) {
     throw new MissingSourceError("guard-eval log", `no runner guard-eval log at ${logPath} for phase ${phaseId}`);
   }
@@ -2889,7 +3178,7 @@ function readGuardEvalLog(logDir, phaseId) {
   return runs;
 }
 function readOrchestrationState(phasesDir, phaseId) {
-  const statePath = join6(phasesDir, `phase-${phaseId}-orchestration-state.json`);
+  const statePath = join8(phasesDir, `${renderPhaseSegment(phaseId)}-orchestration-state.json`);
   if (!existsSync4(statePath)) {
     throw new MissingSourceError("orchestration state", `no orchestration-state file at ${statePath} for phase ${phaseId}`);
   }
@@ -2906,22 +3195,21 @@ function readOrchestrationState(phasesDir, phaseId) {
   }
   return { tasks };
 }
-function readGitClose(repoRoot) {
-  let closeCommit;
-  let closedDate;
+function readPhaseClose(repoRoot, phaseId) {
+  const path = closeRecordPath(repoRoot, phaseId);
+  if (!existsSync4(path))
+    return { closeCommit: null, closedDate: null };
+  let parsed;
   try {
-    closeCommit = execFileSync2("git", ["-C", repoRoot, "rev-parse", "--short", "HEAD"], {
-      encoding: "utf-8"
-    }).trim();
-    closedDate = execFileSync2("git", ["-C", repoRoot, "show", "-s", "--format=%cs", "HEAD"], { encoding: "utf-8" }).trim();
+    parsed = JSON.parse(readFileSync6(path, "utf-8"));
   } catch (err) {
-    throw new MissingSourceError("git HEAD", `cannot resolve close commit/date in ${repoRoot}: ${err instanceof Error ? err.message : String(err)}`);
+    throw new InvalidCloseRecordError(path, `it is not readable JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const record2 = parseCloseRecord(path, parsed);
+  if (renderPhaseSegment(record2.phase) !== renderPhaseSegment(phaseId)) {
+    throw new InvalidCloseRecordError(path, `it records the close of ${String(record2.phase)}, not of ${String(phaseId)}`);
   }
-  if (!closeCommit)
-    throw new MissingSourceError("git HEAD", `empty commit sha in ${repoRoot}`);
-  if (!closedDate)
-    throw new MissingSourceError("git HEAD", `empty commit date in ${repoRoot}`);
-  return { closeCommit, closedDate };
+  return { closeCommit: record2.closeCommit, closedDate: record2.closedDate };
 }
 function validateNarrated(narrated) {
   const req = (v, name) => {
@@ -2932,6 +3220,7 @@ function validateNarrated(narrated) {
   req(narrated.engagement, "engagement");
   req(narrated.engagementType, "engagementType");
   req(narrated.phase?.name, "phase.name");
+  assertValidPhaseIdentity(narrated.phase?.id, BUILD_RECORD_DIR);
   req(narrated.status, "status");
   req(narrated.thesis, "thesis");
   req(narrated.delivered, "delivered");
@@ -2947,7 +3236,7 @@ function validateNarrated(narrated) {
 function loadSources(opts) {
   const orchestration = readOrchestrationState(opts.phasesDir, opts.phaseId);
   const guardEvalRuns = readGuardEvalLog(opts.guardEvalLogDir, opts.phaseId);
-  const git2 = readGitClose(opts.repoRoot);
+  const close = readPhaseClose(opts.repoRoot, opts.phaseId);
   const narrated = validateNarrated(opts.narrated);
   if (!Array.isArray(opts.touchedInvariants)) {
     throw new MissingSourceError("feature-spec Touches", "touchedInvariants must be an array");
@@ -2955,7 +3244,7 @@ function loadSources(opts) {
   return {
     orchestration,
     narrated,
-    git: git2,
+    close,
     guardEvalRuns,
     touchedInvariants: opts.touchedInvariants
   };
@@ -2985,15 +3274,15 @@ function deriveInvariantsExercised(touched) {
   return [...new Set(touched)].sort((a, b) => a.localeCompare(b));
 }
 function assembleBuildRecord(sources) {
-  const { narrated, git: git2, orchestration } = sources;
+  const { narrated, close, orchestration } = sources;
   return {
     format: BUILD_RECORD_FORMAT,
     engagement: narrated.engagement,
     engagementType: narrated.engagementType,
     phase: { id: narrated.phase.id, name: narrated.phase.name },
     status: narrated.status,
-    closedDate: git2.closedDate,
-    closeCommit: git2.closeCommit,
+    closedDate: close.closedDate,
+    closeCommit: close.closeCommit,
     thesis: narrated.thesis,
     thesisHeld: deriveThesisHeld(narrated.acceptance),
     delivered: narrated.delivered,
@@ -3007,85 +3296,6 @@ function assembleBuildRecord(sources) {
   };
 }
 
-// dist/build-record/template.js
-function severityLabel(seed) {
-  return `\`${seed.patternRef}\` (severity \`${seed.severity}\`)`;
-}
-function renderDoneWhenRows(record2) {
-  const rows = [];
-  for (const [key, dw] of Object.entries(record2.acceptance.doneWhen)) {
-    const mark = dw.result === "pass" ? "\u2705" : dw.result === "dropped" ? "\u2014" : dw.result;
-    rows.push(`| ${key} | ${mark} | ${dw.detail} |`);
-  }
-  return rows.join("\n");
-}
-function renderBuildRecordMarkdown(record2) {
-  const { phase } = record2;
-  const guardsList = record2.seedGuards.map(severityLabel).join(", ");
-  const lines = [
-    // Fixed prose (vault-canonical template) + projected title slots.
-    `# Build Record \u2014 Phase ${phase.id}: ${phase.name}`,
-    "",
-    `**Format:** \`${record2.format}\` (markdown + JSON pair; portable, readable without Halfcycle systems)`,
-    "",
-    "> This Build Record was assembled automatically at phase close by the method bundle (`packages/bundle`). Every data field below is projected from the companion JSON \u2014 no record content is hand-authored.",
-    "",
-    `**Engagement:** ${record2.engagement} (${record2.engagementType})`,
-    `**Phase:** ${phase.id} \u2014 ${phase.name}`,
-    `**Status:** ${record2.status.toUpperCase()} \xB7 **Closed:** ${record2.closedDate} \xB7 **Close commit:** \`${record2.closeCommit}\``,
-    `**Companion:** [\`phase-${phase.id}.json\`](phase-${phase.id}.json)`,
-    "",
-    "## What this phase proved",
-    "",
-    `${record2.thesis} **Thesis held: ${record2.thesisHeld ? "yes" : "no"}.**`,
-    "",
-    "## Delivered",
-    "",
-    `- **Packages:** ${record2.delivered.packages.join(", ")}`,
-    `- **Services:** ${record2.delivered.services.join(", ")}`,
-    `- **Tools:** ${record2.delivered.tools.join(", ")}`,
-    `- **Dogfood:** ${record2.delivered.dogfood}`,
-    "",
-    guardsList ? `Guards evaluated (INV-007-safe results): ${guardsList}. *(Guard \`channel\`/\`version\` are guard-asset metadata, excluded from the v1 record \u2014 INV-007/INV-001.)*` : "No guards fired during this phase.",
-    "",
-    `## Acceptance (independent walk \u2014 walker ${record2.acceptance.walker})`,
-    "",
-    `**Verdict:** ${record2.acceptance.verdict} \xB7 **Findings:** ${record2.acceptance.findings}`,
-    "",
-    "| Done-when | Result | Evidence |",
-    "|---|---|---|",
-    renderDoneWhenRows(record2),
-    ""
-  ];
-  if (record2.acceptance.inv002ProdBypassProbe) {
-    lines.push(`**INV-002 production bypass probe:** ${record2.acceptance.inv002ProdBypassProbe.result} \u2014 ${record2.acceptance.inv002ProdBypassProbe.detail}`, "");
-  }
-  lines.push("## Gates that earned their keep", "", `**${record2.gatesEarnedKeep.defectsCaughtPreHuman}** defects were caught by the gates before the human walk; the walk itself found **${record2.gatesEarnedKeep.bugsReachingHumanWalk}**. Named: ${record2.gatesEarnedKeep.named.join("; ")}.`, "", "## Instruments", "", `- **Marginal-cost self-accounting:** ${record2.instruments.marginalCostSelfAccounting}`, `- **COE add-rate:** seam-new ${record2.instruments.coeAddRate.seamNew}, seam-repeat ${record2.instruments.coeAddRate.seamRepeat}, model-limitation ${record2.instruments.coeAddRate.modelLimitation}. ${record2.instruments.coeAddRate.notes}`, "", "## Invariants exercised", "", record2.invariantsExercised.join(", "), "", "## Deviations & decisions recorded", "", ...record2.deviations.map((d) => `- ${d}`), "", "## Tasks", "", `- **Planned:** ${record2.tasks.planned} \xB7 **Landed:** ${record2.tasks.landed} \xB7 **Cancelled:** ${record2.tasks.cancelled.length > 0 ? record2.tasks.cancelled.join(", ") : "none"}`, "");
-  return lines.join("\n");
-}
-
-// dist/build-record/write.js
-import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync5 } from "node:fs";
-import { join as join7, resolve as resolve2, relative as relative2, isAbsolute } from "node:path";
-var BUILD_RECORD_DIR = join7("docs", "build-records");
-function serialiseRecordJson(record2) {
-  return JSON.stringify(record2, null, 2) + "\n";
-}
-function writeBuildRecord(repoRoot, record2) {
-  const outDir = resolve2(repoRoot, BUILD_RECORD_DIR);
-  const expected = resolve2(repoRoot, BUILD_RECORD_DIR);
-  const rel = relative2(expected, outDir);
-  if (rel !== "" || isAbsolute(rel)) {
-    throw new Error(`[build-record] refusing to write outside ${BUILD_RECORD_DIR}`);
-  }
-  mkdirSync5(outDir, { recursive: true });
-  const jsonPath = join7(outDir, `phase-${record2.phase.id}.json`);
-  const mdPath = join7(outDir, `phase-${record2.phase.id}.md`);
-  writeFileSync5(jsonPath, serialiseRecordJson(record2), "utf-8");
-  writeFileSync5(mdPath, renderBuildRecordMarkdown(record2), "utf-8");
-  return { jsonPath, mdPath };
-}
-
 // dist/build-record/index.js
 function assemblePhaseBuildRecord(opts) {
   const sources = loadSources({
@@ -3102,7 +3312,7 @@ function assemblePhaseBuildRecord(opts) {
 
 // dist/open-phase.js
 import { readFileSync as readFileSync7 } from "node:fs";
-import { join as join8 } from "node:path";
+import { join as join9 } from "node:path";
 var OpenPhaseRefused = class extends Error {
   status;
   finding;
@@ -3121,7 +3331,7 @@ var OPEN_PHASE_ENV_KEYS = [
 function readRepoCredential(repoRoot, env = process.env, home) {
   const pinned = readPinnedEngagementId(repoRoot);
   const fromStore = pinned === null ? null : readEngagementEnv(pinned, home);
-  const looked = pinned === null ? `${join8(repoRoot, ".halfcycle", "bundle.json")} (which names no engagement)` : engagementEnvPath(pinned, home);
+  const looked = pinned === null ? `${join9(repoRoot, ".halfcycle", "bundle.json")} (which names no engagement)` : engagementEnvPath(pinned, home);
   const values = {};
   for (const key of OPEN_PHASE_ENV_KEYS) {
     const value = (env[key] ?? fromStore?.[key] ?? "").trim();
@@ -3138,18 +3348,33 @@ function readRepoCredential(repoRoot, env = process.env, home) {
 }
 function readPinnedEngagementId(repoRoot) {
   try {
-    const pin = JSON.parse(readFileSync7(join8(repoRoot, ".halfcycle", "bundle.json"), "utf-8"));
+    const pin = JSON.parse(readFileSync7(join9(repoRoot, ".halfcycle", "bundle.json"), "utf-8"));
     const id = pin[PIN_ENGAGEMENT_ID_FIELD];
     return typeof id === "string" && id !== "" ? id : null;
   } catch {
     return null;
   }
 }
-async function openPhase(credential, phase, entry) {
+function writePhaseStamp(engagementId, phase, home) {
+  const path = engagementEnvPath(engagementId, home);
+  if (phase !== null && !isValidPhaseIdentity(phase)) {
+    return { path, reason: new InvalidPhaseIdentityError(phase).message };
+  }
+  try {
+    writeEngagementEnv(engagementId, { [PHASE_STAMP_ENV_KEY]: phase }, home, [PHASE_STAMP_ENV_KEY]);
+    return null;
+  } catch (err) {
+    return { path, reason: err instanceof Error ? err.message : String(err) };
+  }
+}
+async function openPhase(credential, phase, entry, home) {
   const parsed = phaseEntryDecisionSchema.safeParse(entry);
   if (!parsed.success) {
     throw new Error(`[halfcycle] The entry decision is not a decision this platform accepts: ${parsed.error.issues.map((i) => i.message).join("; ")}.`);
   }
+  if (phase !== null && !isValidPhaseIdentity(phase)) {
+    throw new InvalidPhaseIdentityError(phase);
+  }
   const url = `${credential.serviceUrl}/engagements/${encodeURIComponent(credential.engagementId)}/phase`;
   let res;
   try {
@@ -3174,9 +3399,11 @@ async function openPhase(credential, phase, entry) {
   if (!body || !(typeof body.phase === "string" || body.phase === null) || !(typeof body.previousPhase === "string" || body.previousPhase === null) || typeof body.decision !== "object" || body.decision === null || typeof body.decision.decisionId !== "string") {
     throw new Error(`[halfcycle] The response from ${url} did not carry { phase, previousPhase, decision }. The phase may or may not have moved \u2014 read the engagement's decision history before retrying.`);
   }
+  const stampFailure = writePhaseStamp(credential.engagementId, body.phase, home);
   return {
     phase: body.phase,
     previousPhase: body.previousPhase,
+    stampFailure,
     decision: body.decision
   };
 }
@@ -3194,7 +3421,7 @@ var ClosePhaseRefused = class extends Error {
     this.name = "ClosePhaseRefused";
   }
 };
-async function closePhase(credential, phase, outcome, close) {
+async function closePhase(credential, phase, outcome, close, home, repoRoot) {
   const parsed = acceptanceOutcomeSchema.safeParse(outcome);
   if (!parsed.success) {
     throw new Error(`[halfcycle] That is not an acceptance outcome this platform accepts: ${parsed.error.issues.map((i) => i.message).join("; ")}.`);
@@ -3228,7 +3455,13 @@ async function closePhase(credential, phase, outcome, close) {
   if (!body || typeof body.engagementId !== "string" || typeof body.status !== "string") {
     throw new Error(`[halfcycle] The response from ${url} did not carry { engagementId, status }. The phase may or may not have closed \u2014 read the engagement's status before retrying.`);
   }
-  return { engagementId: body.engagementId, status: body.status };
+  const closeRecord = repoRoot === void 0 ? {
+    recorded: false,
+    path: null,
+    reason: "no repository was named for this close, so there was nowhere to read a commit from"
+  } : writeCloseRecord(repoRoot, phase);
+  const stampFailure = writePhaseStamp(credential.engagementId, null, home);
+  return { engagementId: body.engagementId, status: body.status, stampFailure, closeRecord };
 }
 
 // dist/cli-contract.js
@@ -3349,7 +3582,7 @@ var PLACEHOLDERS = {
 // dist/banner-facts.js
 import { execFileSync as execFileSync3 } from "node:child_process";
 import { readFileSync as readFileSync8 } from "node:fs";
-import { basename as basename2, join as join9, resolve as resolve3 } from "node:path";
+import { basename as basename3, join as join10, resolve as resolve3 } from "node:path";
 var BRAND_URL = "halfcycle.ai";
 var TAGLINE = [
   "Fewer cycles.",
@@ -3362,7 +3595,7 @@ var TAGLINE_NARROW = [
 ];
 function bundleVersion() {
   try {
-    const pkg = JSON.parse(readFileSync8(join9(BUNDLE_ROOT, "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync8(join10(BUNDLE_ROOT, "package.json"), "utf-8"));
     return typeof pkg.version === "string" ? pkg.version : void 0;
   } catch {
     return void 0;
@@ -3451,7 +3684,7 @@ function openingBannerContent(projectDir, env = process.env, probes = REAL_PROBE
 }
 function safeBasename(dir) {
   try {
-    const name = basename2(resolve3(dir)).trim();
+    const name = basename3(resolve3(dir)).trim();
     return name === "" ? "project" : name;
   } catch {
     return "project";
@@ -3512,7 +3745,7 @@ var USAGE = `  halfcycle [install] [target-repo] [engagement-id] [self-build|cli
          install into target (default: the current directory)
          --yes / -y: use this machine's saved sign-in without being asked
   halfcycle check-drift <target-repo>
-  halfcycle build-record <phase-id> [--repo <root>]
+  halfcycle build-record <phase> [--repo <root>]
   halfcycle open-phase <phase|--none> --actor "\u2026" (--evidence "\u2026" | --override --reason "\u2026") [--repo <root>]
   halfcycle close-phase <phase> --verdict <clean|defects> --actor "\u2026" [--finding "\u2026"]\u2026 [--override --reason "\u2026"] [--repo <root>]
 
@@ -3521,7 +3754,7 @@ var USAGE = `  halfcycle [install] [target-repo] [engagement-id] [self-build|cli
 `;
 function isHalfcycleMonorepo(dir) {
   try {
-    const pkg = JSON.parse(readFileSync9(join10(dir, "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync9(join11(dir, "package.json"), "utf-8"));
     return pkg.name === "halfcycle-monorepo";
   } catch {
     return false;
@@ -3755,30 +3988,30 @@ ${USAGE}`);
   if (cmd === "build-record") {
     const phaseArg = rest[0];
     const repoRoot = rest.includes("--repo") ? rest[rest.indexOf("--repo") + 1] : process.cwd();
-    if (!phaseArg || !/^\d+$/.test(phaseArg)) {
-      process.stderr.write("halfcycle-bundle: usage: halfcycle-bundle build-record <phase-id> [--repo <root>]\n");
+    if (!phaseArg) {
+      process.stderr.write("halfcycle: usage: halfcycle build-record <phase> [--repo <root>]\n");
       process.exit(1);
       return;
     }
-    const phaseId = Number(phaseArg);
+    const phaseId = phaseArg;
     try {
-      const inputPath = join10(repoRoot, ".workbench", "build-record", `phase-${phaseId}.input.json`);
+      const inputPath = join11(repoRoot, BUILD_RECORD_ZONE_B_DIR, `${renderPhaseSegment(phaseId)}.input.json`);
       const input = JSON.parse(readFileSync9(inputPath, "utf-8"));
       const result = assemblePhaseBuildRecord({
         repoRoot,
-        phasesDir: join10(repoRoot, "docs", "phases"),
-        guardEvalLogDir: input.guardEvalLogDir ?? join10(repoRoot, ".workbench", "guard-eval-log"),
+        phasesDir: join11(repoRoot, "docs", "phases"),
+        guardEvalLogDir: input.guardEvalLogDir ?? join11(repoRoot, ".workbench", "guard-eval-log"),
         phaseId,
         narrated: input.narrated,
         touchedInvariants: input.touchedInvariants
       });
-      process.stdout.write(`[halfcycle-bundle] Build Record written:
+      process.stdout.write(`[halfcycle] Build Record written:
   ${result.jsonPath}
   ${result.mdPath}
 `);
       process.exit(0);
     } catch (err) {
-      process.stderr.write(`halfcycle-bundle build-record failed: ${err instanceof Error ? err.message : String(err)}
+      process.stderr.write(`halfcycle build-record failed: ${err instanceof Error ? err.message : String(err)}
 `);
       process.exit(1);
     }
@@ -3820,8 +4053,22 @@ ${USAGE}`);
         process.stdout.write(`[halfcycle] This decision CROSSED: ${opened.decision.blockingFinding}
 `);
       }
+      if (opened.stampFailure) {
+        process.stderr.write(`halfcycle open-phase: the phase moved, but this machine's copy of it could not be written: ${opened.stampFailure.reason}
+halfcycle open-phase: until ${opened.stampFailure.path} can be written, guard evaluations here are filed under whatever phase that file still names. Fix the file and re-run this command \u2014 re-running it is safe.
+`);
+        process.exit(1);
+        return;
+      }
       process.exit(0);
     } catch (err) {
+      if (err instanceof InvalidPhaseIdentityError) {
+        process.stderr.write(`halfcycle open-phase: ${err.message}
+halfcycle open-phase: a phase name has to work as a single folder name on this machine \u2014 that is what this machine files its guard evaluations under. Nothing was opened.
+`);
+        process.exit(2);
+        return;
+      }
       if (err instanceof OpenPhaseRefused) {
         process.stderr.write(`halfcycle open-phase: refused (${err.status}). ${err.message}
 `);
@@ -3901,15 +4148,30 @@ ${USAGE}`);
         verdict,
         findings: findingsDetail.length,
         findingsDetail
-      }, closeDecision);
+      }, closeDecision, void 0, repoRoot);
       process.stdout.write(`[halfcycle] Phase "${phaseArg}" closed as ${verdict}${findingsDetail.length > 0 ? ` with ${findingsDetail.length} finding(s)` : ""} by ${closeDecision.actor}. The engagement is now ${closed.status}.
 `);
       if (closeDecision.decision === "override") {
         process.stdout.write(`[halfcycle] This close was an OVERRIDE: ${closeDecision.reason}
+`);
+      }
+      if (closed.closeRecord.recorded) {
+        process.stdout.write(`[halfcycle] Closed at commit ${closed.closeRecord.closeCommit} (${closed.closeRecord.closedDate}). The Build Record for this phase will name it.
+`);
+      } else {
+        process.stderr.write(`halfcycle close-phase: the phase closed, but the commit it closed at was not recorded on this machine: ${closed.closeRecord.reason}
+halfcycle close-phase: this phase's Build Record will say the close commit and the close date were not recorded.
 `);
       }
       process.stdout.write(`[halfcycle] Open the next phase with: halfcycle open-phase <phase> --actor "you" --evidence "\u2026"
 `);
+      if (closed.stampFailure) {
+        process.stderr.write(`halfcycle close-phase: the phase closed, but this machine's record of it could not be cleared: ${closed.stampFailure.reason}
+halfcycle close-phase: until ${closed.stampFailure.path} can be written, guard evaluations here are still filed under the phase you just closed.
+`);
+        process.exit(1);
+        return;
+      }
       process.exit(0);
     } catch (err) {
       if (err instanceof ClosePhaseRefused) {