halfcycle 0.3.17 → 0.3.19

package/dist/index.js

@@ -54,11 +54,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(),
@@ -170,6 +185,67 @@ var CREW_ROSTER = [
 var CREW_ROSTER_SIZE = CREW_ROSTER.length;
 var CREW_CALLSIGNS = CREW_ROSTER.map((member) => member.callsign);
 
+// ../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 (identity === "")
+    return "(empty)";
+  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, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { platform as platform2 } from "node:os";
@@ -192,6 +268,7 @@ function engagementStateDir(engagementId, home) {
 function engagementEnvPath(engagementId, home) {
   return join2(engagementStateDir(engagementId, home), ENV_FILENAME);
 }
+var NOT_THIS_ACCOUNT_MARKER_FILENAME = "not-this-account";
 var GUARD_ENV_KEYS = [
   "GUARD_SERVICE_URL",
   "GUARD_SERVICE_TOKEN",
@@ -233,33 +310,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"))
@@ -273,17 +367,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);
-  mkdirSync(dir, { recursive: true, mode: 448 });
   let existing;
   try {
     existing = readFileSync(path, "utf-8");
   } catch {
     existing = null;
   }
-  const reconciled = reconcileEnvText(existing, values);
+  const reconciled = reconcileEnvText(existing, values, keys);
+  if (existing === null && reconciled === "")
+    return "skipped";
+  mkdirSync(dir, { recursive: true, mode: 448 });
   const outcome = existing === reconciled ? "skipped" : "written";
   if (outcome === "written") {
     writeFileSync(path, reconciled, { mode: 384 });
@@ -313,14 +409,15 @@ function engagementResolutionShell() {
 # desktop session's PATH, so the id is cut out with sed \u2014 after flattening the
 # file, because sed is line-oriented and the pin's line breaks are not a contract.
 #
-# Sets HALFCYCLE_ENV_FILE, HALFCYCLE_ENV_ENGAGEMENT and HALFCYCLE_ENV_PROBLEM in
-# the CALLER's shell and returns a status. Call it as \`if halfcycle_env_file \u2026\`,
-# never as \`$(halfcycle_env_file \u2026)\` \u2014 a command substitution is a subshell and
-# would discard everything it set.
+# Sets HALFCYCLE_ENV_FILE, HALFCYCLE_ENV_ENGAGEMENT, HALFCYCLE_ENV_PROBLEM and
+# HALFCYCLE_ENV_NOT_THIS_ACCOUNT in the CALLER's shell and returns a status. Call
+# it as \`if halfcycle_env_file \u2026\`, never as \`$(halfcycle_env_file \u2026)\` \u2014 a
+# command substitution is a subshell and would discard everything it set.
 halfcycle_env_file() {
   HALFCYCLE_ENV_FILE=""
   HALFCYCLE_ENV_ENGAGEMENT=""
   HALFCYCLE_ENV_PROBLEM=""
+  HALFCYCLE_ENV_NOT_THIS_ACCOUNT=""
   hc_pin="$1/.halfcycle/bundle.json"
   if [ ! -f "$hc_pin" ]; then
     HALFCYCLE_ENV_PROBLEM="no-pin"
@@ -336,6 +433,9 @@ halfcycle_env_file() {
     HALFCYCLE_ENV_PROBLEM="no-home"
     return 1
   fi
+  if [ -f "$HOME/.halfcycle/${ENGAGEMENTS_DIR}/$hc_id/${NOT_THIS_ACCOUNT_MARKER_FILENAME}" ]; then
+    HALFCYCLE_ENV_NOT_THIS_ACCOUNT=1
+  fi
   hc_env="$HOME/.halfcycle/${ENGAGEMENTS_DIR}/$hc_id/${ENV_FILENAME}"
   if [ ! -f "$hc_env" ]; then
     HALFCYCLE_ENV_PROBLEM="no-credential"
@@ -715,6 +815,13 @@ if halfcycle_env_file "$PROJECT_DIR"; then
   set +a
 fi
 
+# Pass along WHY this machine has no credential, as a plain variable \u2014 the
+# marker check above already answered it, and this is the one bit of that
+# answer the runner binary needs to say the right thing on every edit.
+if [ "$HALFCYCLE_ENV_NOT_THIS_ACCOUNT" = "1" ]; then
+  export HALFCYCLE_NOT_THIS_ACCOUNT=1
+fi
+
 exec node "$PROJECT_DIR/${VENDORED_BIN_REL}" "$@"
 `;
 }
@@ -730,13 +837,20 @@ MARKER_FILE="\${TMPDIR%/}/halfcycle-session-\${HASH}.ref"
 git -C "$REPO_ROOT" rev-parse HEAD > "$MARKER_FILE" 2>/dev/null || true
 
 # ---------------------------------------------------------------------------
-# STANDING GUARD-COVERAGE STATEMENT (T-27).
+# STANDING GUARD-COVERAGE STATEMENT (T-27; two arms since T-02b).
 #
 # A repository with no credential on this machine is UNGUARDED: the PostToolUse
 # hook will find nothing to evaluate with, and it says so once per edit, after
 # the edit. This says it once, up front, before anything is written \u2014 which is
 # the one thing a session-start hook can do that nothing else can.
 #
+# TWO REASONS TO HAVE NO CREDENTIAL, TWO DIFFERENT THINGS TO SAY (T-02b,
+# solo-project-ownership \u2014 outcome B). "You have not signed in here yet" is
+# fixed by re-running the installer; "this is not your project" is permanent,
+# and the same remedy would send the reader in a circle forever. The two are
+# told apart by HALFCYCLE_ENV_NOT_THIS_ACCOUNT, set by \`halfcycle_env_file\`
+# below from a machine-level marker beside the credential store.
+#
 # Everything below runs in a SUBSHELL: it sources a credential store, and a
 # session-start hook must not leak an engagement's variables into whatever the
 # editor runs next. Any failure inside it is swallowed; this script's exit
@@ -750,18 +864,33 @@ ${engagementResolutionShell()}
     . "$HALFCYCLE_ENV_FILE"
     set +a
   fi
-  hc_missing=""
-  for hc_key in ${GUARD_COVERAGE_REQUIRED_KEYS.join(" ")}; do
-    eval "hc_value=\\\${$hc_key:-}"
-    if [ -z "$hc_value" ]; then hc_missing="$hc_missing $hc_key"; fi
-  done
-  if [ -n "$hc_missing" ]; then
-    echo "[halfcycle] NO GUARD COVERAGE IN THIS REPOSITORY. Nothing will evaluate the edits made in"
-    echo "[halfcycle] this session: this machine has no Halfcycle credential for it, so the guard hook"
-    echo "[halfcycle] has nothing to call with (missing:$hc_missing)."
-    echo "[halfcycle] Run \\"npx halfcycle\\" in this repository to fix it \u2014 it signs you in through your"
-    echo "[halfcycle] browser if needed, writes the credential to \\$HOME/.halfcycle outside this tree,"
-    echo "[halfcycle] and needs nothing configured first."
+  if [ "$HALFCYCLE_ENV_NOT_THIS_ACCOUNT" = "1" ]; then
+    # OUTCOME B (T-02b, solo-project-ownership). This is not the missing-keys
+    # case below wearing different words: there is nothing to fix, and the loop
+    # that follows is skipped entirely rather than run and then overridden \u2014 a
+    # repository whose credential is absent for THIS reason must never be told
+    # to re-run the installer, which can never obtain one for it.
+    echo "[halfcycle] This project belongs to another Halfcycle account, so nothing here is checked."
+    echo "[halfcycle] Your work carries on exactly as it would without Halfcycle \u2014 no edit is"
+    echo "[halfcycle] evaluated, and nothing you do is reported as having passed."
+    echo "[halfcycle] Halfcycle is Solo today \u2014 one developer per project \u2014 with Team plans coming."
+    echo "[halfcycle] Ask the project's owner for view access."
+    echo "[halfcycle] If this account is wrong, sign in as the one that owns the project and run"
+    echo "[halfcycle] \\"npx halfcycle\\" again."
+  else
+    hc_missing=""
+    for hc_key in ${GUARD_COVERAGE_REQUIRED_KEYS.join(" ")}; do
+      eval "hc_value=\\\${$hc_key:-}"
+      if [ -z "$hc_value" ]; then hc_missing="$hc_missing $hc_key"; fi
+    done
+    if [ -n "$hc_missing" ]; then
+      echo "[halfcycle] NO GUARD COVERAGE IN THIS REPOSITORY. Nothing will evaluate the edits made in"
+      echo "[halfcycle] this session: this machine has no Halfcycle credential for it, so the guard hook"
+      echo "[halfcycle] has nothing to call with (missing:$hc_missing)."
+      echo "[halfcycle] Run \\"npx halfcycle\\" in this repository to fix it \u2014 it signs you in through your"
+      echo "[halfcycle] browser if needed, writes the credential to \\$HOME/.halfcycle outside this tree,"
+      echo "[halfcycle] and needs nothing configured first."
+    fi
   fi
 ) 2>/dev/null || true
 exit 0
@@ -921,8 +1050,20 @@ if [ -z "$TOKEN" ]; then
       no-home)
         echo "halfcycle: HOME is not set, so the credential store cannot be located." >&2 ;;
       *)
-        echo "halfcycle: this machine holds no credential for engagement $HALFCYCLE_ENV_ENGAGEMENT." >&2
-        echo "halfcycle: run \\"npx halfcycle\\" in this repository \u2014 it will sign you in through your browser if needed, and write the credential to $HOME/.halfcycle, outside this repository." >&2 ;;
+        # OUTCOME B (T-02b, solo-project-ownership) is a \`no-credential\` PROBLEM
+        # with a REASON attached, checked here rather than as a fifth case value
+        # \u2014 see \`engagementResolutionShell\`'s own docblock for why. Re-running
+        # this installer can never obtain a credential for this reason, so it is
+        # the one sentence in this file that must not say to.
+        if [ "$HALFCYCLE_ENV_NOT_THIS_ACCOUNT" = "1" ]; then
+          echo "halfcycle: this project belongs to another Halfcycle account, so this machine has no" >&2
+          echo "halfcycle: credential for it and the Halfcycle tools are not available here. Nothing is" >&2
+          echo "halfcycle: broken \u2014 ask the project's owner for view access, or sign in as the account" >&2
+          echo "halfcycle: that owns it and run \\"npx halfcycle\\" again." >&2
+        else
+          echo "halfcycle: this machine holds no credential for engagement $HALFCYCLE_ENV_ENGAGEMENT." >&2
+          echo "halfcycle: run \\"npx halfcycle\\" in this repository \u2014 it will sign you in through your browser if needed, and write the credential to $HOME/.halfcycle, outside this repository." >&2
+        fi ;;
     esac
     exit 1
   fi
@@ -1266,11 +1407,13 @@ var CreateEngagementRefused = class extends Error {
   status;
   serverMessage;
   errorCode;
-  constructor(status, serverMessage, errorCode, message) {
+  reason;
+  constructor(status, serverMessage, errorCode, reason, message) {
     super(message);
     this.status = status;
     this.serverMessage = serverMessage;
     this.errorCode = errorCode;
+    this.reason = reason;
     this.name = "CreateEngagementRefused";
   }
   /**
@@ -1315,7 +1458,8 @@ function planeRefusal(detail) {
     return void 0;
   return {
     message: candidate.message,
-    error: typeof candidate.error === "string" ? candidate.error : void 0
+    error: typeof candidate.error === "string" ? candidate.error : void 0,
+    reason: typeof candidate.reason === "string" ? candidate.reason : void 0
   };
 }
 var CONTROL_ORIGIN_HINT = `This CLI talks to ${DEFAULT_CONTROL_ORIGIN}; it must be the CONTROL origin \u2014 the one that serves /engagements and /board/enter-codes. The MCP server runs at a different address, and the platform supplies that one itself; you configure neither.`;
@@ -1349,7 +1493,7 @@ async function requestEngagementValues(url, requestBody, credential, shape) {
     const detail = await res.text().catch(() => "");
     const refusal = res.status === 404 ? void 0 : planeRefusal(detail);
     if (refusal) {
-      throw new CreateEngagementRefused(res.status, refusal.message, refusal.error, `[bundle install] ${shape.action} failed: ${url} returned ${res.status}. ${refusal.message} ${shape.nothingHappened}.`);
+      throw new CreateEngagementRefused(res.status, refusal.message, refusal.error, refusal.reason, `[bundle install] ${shape.action} failed: ${url} returned ${res.status}. ${refusal.message} ${shape.nothingHappened}.`);
     }
     const wrongOrigin = res.status === 404 ? `That address answered, but it does not serve ${shape.route} \u2014 so it is not the Halfcycle service. ` : "";
     throw new Error(`[bundle install] ${shape.action} failed: ${url} returned ${res.status}. ${wrongOrigin}${detail ? `Response: ${detail.slice(0, 300)}. ` : ""}${shape.nothingHappened}. ` + CONTROL_ORIGIN_HINT);
@@ -1877,8 +2021,203 @@ function projectSeedGuard(fired, includeExplanation) {
 // dist/build-record/sources.js
 import { readFileSync as readFileSync7, existsSync as existsSync6 } from "node:fs";
 import { createHash } from "node:crypto";
-import { join as join8 } from "node:path";
+import { join as join10 } 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 dirname4, join as join8 } from "node:path";
+var CLOSE_RECORD_FORMAT = "halfcycle-phase-close/v1";
+var BUILD_RECORD_ZONE_B_DIR = join8(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 join8(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(dirname4(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, join as join9, resolve, 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 = join9("docs", "build-records");
+function serialiseRecordJson(record2) {
+  return JSON.stringify(record2, null, 2) + "\n";
+}
+function assertInsideOutDir(outDir, candidate, identity) {
+  const rel = relative2(outDir, resolve(candidate));
+  const isPlainFilename = rel !== "" && rel !== ".." && !isAbsolute(rel) && rel === basename(rel);
+  if (!isPlainFilename) {
+    throw new InvalidPhaseIdentityError(identity, BUILD_RECORD_DIR);
+  }
+}
+function writeBuildRecord(repoRoot, record2) {
+  const outDir = resolve(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 = join9(outDir, `${segment}.json`);
+  const mdPath = join9(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}`);
@@ -1934,7 +2273,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 = join8(logDir, `phase-${phaseId}.jsonl`);
+  const logPath = join10(logDir, `${renderPhaseSegment(phaseId)}.jsonl`);
   if (!existsSync6(logPath)) {
     throw new MissingSourceError("guard-eval log", `no runner guard-eval log at ${logPath} for phase ${phaseId}`);
   }
@@ -1950,7 +2289,7 @@ function readGuardEvalLog(logDir, phaseId) {
   return runs;
 }
 function readOrchestrationState(phasesDir, phaseId) {
-  const statePath = join8(phasesDir, `phase-${phaseId}-orchestration-state.json`);
+  const statePath = join10(phasesDir, `${renderPhaseSegment(phaseId)}-orchestration-state.json`);
   if (!existsSync6(statePath)) {
     throw new MissingSourceError("orchestration state", `no orchestration-state file at ${statePath} for phase ${phaseId}`);
   }
@@ -1967,22 +2306,21 @@ function readOrchestrationState(phasesDir, phaseId) {
   }
   return { tasks };
 }
-function readGitClose(repoRoot) {
-  let closeCommit;
-  let closedDate;
+function readPhaseClose(repoRoot, phaseId) {
+  const path = closeRecordPath(repoRoot, phaseId);
+  if (!existsSync6(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(readFileSync7(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) => {
@@ -1993,6 +2331,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");
@@ -2008,7 +2347,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");
@@ -2016,7 +2355,7 @@ function loadSources(opts) {
   return {
     orchestration,
     narrated,
-    git: git2,
+    close,
     guardEvalRuns,
     touchedInvariants: opts.touchedInvariants
   };
@@ -2046,15 +2385,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,
@@ -2068,85 +2407,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 join9, resolve, relative as relative2, isAbsolute } from "node:path";
-var BUILD_RECORD_DIR = join9("docs", "build-records");
-function serialiseRecordJson(record2) {
-  return JSON.stringify(record2, null, 2) + "\n";
-}
-function writeBuildRecord(repoRoot, record2) {
-  const outDir = resolve(repoRoot, BUILD_RECORD_DIR);
-  const expected = resolve(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 = join9(outDir, `phase-${record2.phase.id}.json`);
-  const mdPath = join9(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({
@@ -2163,9 +2423,13 @@ function assemblePhaseBuildRecord(opts) {
 export {
   BUILD_RECORD_DIR,
   BUILD_RECORD_FORMAT,
+  BUILD_RECORD_ZONE_B_DIR,
+  CLOSE_RECORD_FORMAT,
   CreateEngagementRefused,
   FLAT_FILE_TRACKER_HOME,
   HALFCYCLE_STATE_FORMAT,
+  InvalidCloseRecordError,
+  InvalidPhaseIdentityError,
   MissingSourceError,
   SetupManifest,
   ZONE_B_DIR,
@@ -2173,8 +2437,10 @@ export {
   applySetupWrites,
   assembleBuildRecord,
   assemblePhaseBuildRecord,
+  assertValidPhaseIdentity,
   buildEngagementRecord,
   checkDrift,
+  closeRecordPath,
   contextIndexRow,
   createEngagement,
   deriveInvariantsExercised,
@@ -2185,29 +2451,33 @@ export {
   engagementRecordRow,
   flatFileTrackerDefault,
   install,
+  isValidPhaseIdentity,
   layerDocumentRow,
   loadSources,
   mergeSettings,
   mergeWithRecords,
   mintBoardEnterCode,
   mintOrReadIdentity,
+  parseCloseRecord,
   projectSeedGuard,
   projectSeedGuards,
   questionsToPut,
   readBundlePin,
-  readGitClose,
   readGuardEvalLog,
   readOrchestrationState,
+  readPhaseClose,
   readRemote,
   readRootCommit,
   renderAnchor,
   renderBuildRecordMarkdown,
   renderDiscovery,
+  renderPhaseSegment,
   runBootstrapScan,
   scanLayers,
   serialiseRecordJson,
   trackerHomeRow,
   validateNarrated,
-  writeBuildRecord
+  writeBuildRecord,
+  writeCloseRecord
 };
 //# sourceMappingURL=index.js.map