halfcycle 0.3.39 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "halfcycle",
-  "version": "0.3.39",
+  "version": "0.4.0",
   "description": "Halfcycle Method bundle — resolution-stub slash commands, remote method-delivery registration, and governance-hook wiring for a Halfcycle engagement repo. It ships NO worker role files: a project's roles are authored from that project's own recorded decisions at orchestration kickoff (FX-2, W3-F-27).",
   "commands": [
     {

package/README.md

@@ -42,7 +42,7 @@ A method document cannot fix that, because a document cannot interrupt you. This
 
 Credit where it is due, and it is due. GStack, Matt Pocock's skills, GitHub Spec Kit, BMAD, OpenSpec and claude-flow are genuinely good, and between them they taught this whole category that the bottleneck is discipline rather than model intelligence. We took two things from them deliberately and say so: the one-question-at-a-time interrogation shape, and an install that is one command and then stays out of your way.
 
-The objection this usually meets is that it must be too much for a small project. It would be, if there were one setting. A folder you download has exactly one, so whoever wrote it had to choose who to disappoint, and it is usually the small project that gets buried and quietly drops the process in week three. This reads the work instead and sizes itself to it, which is the section further down.
+The objection this usually meets is that it must be too much for a small project. It would be, if there were one setting. A folder you download has exactly one, so whoever wrote it had to choose who to disappoint, and it is usually the small project that gets buried and quietly drops the process in week three. Halfcycle sizes each piece of work with a diagnostic before it starts instead, and records which design documents it includes and which it skips, which is the section further down.
 
 Writing the process down was never the hard part. What a folder you download structurally cannot have is these three things.
 
@@ -146,16 +146,14 @@ This matters enough to be specific about.
 
 **Halfcycle never holds or proxies your Claude credential.** Inference runs on your own Claude Code, on your own subscription or seats. We are not a hosted runtime reselling you inference.
 
-**Your own Halfcycle credential lives outside this repository, in a file named `env` under your home directory — never in anything you'd commit.** Closing a phase rewrites it, to clear which phase was open, and it is also renewed there automatically to keep your connection current. Nothing else changes it.
+**Your own Halfcycle credential lives outside this repository, in a file named `env` under your home directory — never in anything you'd commit.** Installing writes it. Opening or closing a phase rewrites it, to record which phase is open, and the credential in it is also renewed there automatically to keep your connection current. Uninstalling with `--remove-credential` deletes it. Nothing else changes it.
 
-**What the checks receive is the shape of a change, not its contents.** File paths, structural shapes, environment variable names and how they are used, the tables a write touches, route signatures, outbound host names. There is no file body and no diff in the request.
+**What the checks receive is the shape of a change and short excerpts of the code being edited — never a whole file and never a diff.** File paths, structural shapes, environment variable names and how they are used, the tables a write touches, route signatures, outbound host names. There is no file body and no diff in the request.
 
-**Source excerpts are off, at both ends, for every engagement today.** The wire format does have a field for them, so the honest version of this is a conditional statement rather than a flat one, and it rests on three things rather than on our good intentions: your runner does not attach an excerpt unless you turn a flag on, and that flag is off by default; anything that does arrive for an engagement that has not opted in is stripped on our side before the checks or any model see it; and there is no way to opt in today, because nothing in the product can set that flag. If that ever changes, our privacy policy changes with it, and it is the policy — not this paragraph — that states the guarantee.
+**Short excerpts of the code being edited are sent to Halfcycle to run its checks, under the terms you accepted at sign-in.** Our privacy policy, not this paragraph, states how we handle what you send.
 
 **What the readiness audit submits, and what it never carries.** `halfcycle_submit_findings` is how your session sends the audit's answers: a probe's status, a count, a repo-relative path, a short name. Never a file body, a diff or a source excerpt — the wire carries no field for prose, so a path or a name is the most it can carry. What Halfcycle keeps is what your session submitted, the judgement it reached, and which account and machine sign-in the submission came from; the documents themselves never reach it.
 
-**A promise, for the day a check does need to read something you wrote:** what you send it will be read and not kept: the finding and its evidence persist, the source does not, and training or benchmarking on it is foreclosed. It is written here now, labelled as a commitment rather than a feature, so the promise is public before the mechanism is.
-
 **Nothing method-shaped is left behind.** The runbooks, templates and question sets reach the session that asks for them, scoped to the step you are on, and are never at rest in your repository.
 
 ## What you keep

package/bin/bin.bundle.mjs

@@ -14820,7 +14820,7 @@ function readMcpServerUrl() {
 }
 function readExcerptConfig() {
   const raw = process.env["HALFCYCLE_SOURCE_EXCERPTS"];
-  const enabled = (raw ?? "").trim().toLowerCase() === "true";
+  const enabled = (raw ?? "").trim().toLowerCase() !== "false";
   const readCap = (name, fallback) => {
     const v = process.env[name];
     if (v === void 0)
@@ -15358,8 +15358,8 @@ function hookReply(event) {
     }
   };
 }
-function infraWarningText(message) {
-  return `[Halfcycle] WARNING: Guard service unavailable \u2014 ${message}. The session continues without checks.`;
+function infraWarningText() {
+  return "[Halfcycle] WARNING: Halfcycle's check service could not be reached, so nothing was checked this time. The session continues without checks.";
 }
 function localFaultText(message) {
   return `[Halfcycle] WARNING: Local fault \u2014 ${message}. The guard service was not contacted. Session continues (fail-open).`;
@@ -15701,8 +15701,10 @@ async function attempt(url2, token, request, fetchFn, retry) {
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { relative } from "node:path";
+var COLOR_AWARE_SUBCOMMANDS = /* @__PURE__ */ new Set(["diff", "show", "log"]);
 function git(args2, cwd, timeoutMs) {
-  const result = spawnSync("git", args2, {
+  const argv = COLOR_AWARE_SUBCOMMANDS.has(args2[0] ?? "") ? [args2[0], "--no-color", ...args2.slice(1)] : args2;
+  const result = spawnSync("git", argv, {
     cwd,
     encoding: "utf-8",
     ...timeoutMs === void 0 ? {} : { timeout: timeoutMs }
@@ -16816,13 +16818,21 @@ function produceExcerpts(diffContent, descriptors, caps) {
   const excerpts = [];
   const seen = /* @__PURE__ */ new Set();
   const lines = diffContent.split("\n");
-  let lineNo = 0;
+  let newLineNo;
   for (const raw of lines) {
-    if (raw.startsWith("-") && !raw.startsWith("---"))
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);
+    if (hunk) {
+      newLineNo = Number.parseInt(hunk[1], 10);
+      continue;
+    }
+    if (newLineNo === void 0)
+      continue;
+    if (raw.startsWith("\\"))
       continue;
-    if (raw.startsWith("+++") || raw.startsWith("---"))
+    if (raw.startsWith("-"))
       continue;
-    lineNo += 1;
+    const lineNo = newLineNo;
+    newLineNo += 1;
     if (!raw.startsWith("+"))
       continue;
     const text = raw.slice(1).trim();
@@ -17092,7 +17102,10 @@ async function runCi() {
     };
   });
   const context = loadChangeSetContext(repoRoot);
-  const changeSet = buildChangeSet(fileDiffEntries, { ...context, excerpts: readExcerptConfig() });
+  const changeSet = buildChangeSet(fileDiffEntries, {
+    ...context,
+    excerpts: { enabled: false, ...EXCERPT_DEFAULTS }
+  });
   const configResult = readConfig();
   if (!configResult.config) {
     const oidc = readActionsOidcEnv();
@@ -17668,7 +17681,7 @@ async function evaluateEdit(reply, readSeat) {
       reply.notice(contractFaultText(failure.message));
       return;
     }
-    reply.notice(infraWarningText(failure.reason));
+    reply.notice(infraWarningText());
     return;
   }
   const telemetryConfig = readTelemetryConfig();
@@ -17964,7 +17977,7 @@ async function evaluateSession(input, kind, reply, readSeat) {
       reply.notice(contractFaultText(failure.message));
       return;
     }
-    reply.notice(infraWarningText(failure.reason));
+    reply.notice(infraWarningText());
     return;
   }
   const telemetryConfig = readTelemetryConfig();

package/dist/bin.js

@@ -238,6 +238,7 @@ var MCP_SERVER_KEY = "halfcycle";
 function quoteForShell(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+var HALFCYCLE_COMMAND = "npx halfcycle@latest";
 
 // ../events/dist/result.js
 import { z as z2 } from "zod";
@@ -4593,31 +4594,44 @@ function renderCouldNotRun(entries, p) {
   }
   return lines.join("\n");
 }
-function headline(observed, attested, checks) {
+function headlineText(observed, attested, checks) {
   const met = attested.decision === "done-when-met";
   const problemsReported = attested.walk !== null && attested.walk.verdict === "defects";
   switch (observed.crossed.kind) {
     case "none":
       if (!met) {
-        return "**Closed by override.** Halfcycle saw nothing outstanding, and the person closing the phase chose to override rather than state its finish conditions were met.";
+        return ["Closed by override.", "Halfcycle saw nothing outstanding, and the person closing the phase chose to override rather than state its finish conditions were met."];
       }
       if (problemsReported) {
-        return "**Closed with problems reported.** Halfcycle saw nothing outstanding, and the person closing the phase reported problems found in its acceptance walk.";
+        return ["Closed with problems reported.", "Halfcycle saw nothing outstanding, and the person closing the phase reported problems found in its acceptance walk."];
       }
-      return checks === "not-observed" ? "**Closed with nothing outstanding, but no check on record.** Halfcycle saw nothing outstanding, and the person closing the phase stated its finish conditions were met, but Halfcycle has no record of any check running during this phase, so this is not a clean result." : "**Closed cleanly.** Halfcycle saw nothing outstanding, and the person closing the phase stated its finish conditions were met.";
+      return checks === "not-observed" ? ["Closed with nothing outstanding, but no check on record.", "Halfcycle saw nothing outstanding, and the person closing the phase stated its finish conditions were met, but Halfcycle has no record of any check running during this phase, so this is not a clean result."] : ["Closed cleanly.", "Halfcycle saw nothing outstanding, and the person closing the phase stated its finish conditions were met."];
     case "unfinished-steps":
     case "clean-over-findings":
       if (!met) {
-        return "**Closed over outstanding work.** Halfcycle saw work still outstanding, and the person closing the phase chose to override it.";
+        return ["Closed over outstanding work.", "Halfcycle saw work still outstanding, and the person closing the phase chose to override it."];
       }
-      return problemsReported ? "**Closed over outstanding work.** Halfcycle saw work still outstanding, and the person closing the phase closed it as it stood, reporting problems found in its acceptance walk." : "**Closed over outstanding work.** Halfcycle saw work still outstanding, and the person closing the phase stated its finish conditions were met anyway.";
+      return problemsReported ? ["Closed over outstanding work.", "Halfcycle saw work still outstanding, and the person closing the phase closed it as it stood, reporting problems found in its acceptance walk."] : ["Closed over outstanding work.", "Halfcycle saw work still outstanding, and the person closing the phase stated its finish conditions were met anyway."];
     case "not-recorded":
       if (!met) {
-        return "**Outstanding work not recorded.** Halfcycle has no record of what was outstanding at this close. The person closing the phase chose to override.";
+        return ["Outstanding work not recorded.", "Halfcycle has no record of what was outstanding at this close. The person closing the phase chose to override."];
       }
-      return problemsReported ? "**Outstanding work not recorded.** Halfcycle has no record of what was outstanding at this close. The person closing the phase reported problems found in its acceptance walk." : "**Outstanding work not recorded.** Halfcycle has no record of what was outstanding at this close. The person closing the phase stated its finish conditions were met.";
+      return problemsReported ? ["Outstanding work not recorded.", "Halfcycle has no record of what was outstanding at this close. The person closing the phase reported problems found in its acceptance walk."] : ["Outstanding work not recorded.", "Halfcycle has no record of what was outstanding at this close. The person closing the phase stated its finish conditions were met."];
   }
 }
+function headline(observed, attested, checks) {
+  const [title, sentence] = headlineText(observed, attested, checks);
+  return `**${title}** ${sentence}`;
+}
+function latestCloseHeadline(record2) {
+  const attested = new Map(record2.attested.closes.map((c) => [c.sequence, c]));
+  const ordered = [...record2.observed.closes].sort((a, b) => a.sequence - b.sequence);
+  const latest = ordered[ordered.length - 1];
+  const stated = latest === void 0 ? void 0 : attested.get(latest.sequence);
+  if (latest === void 0 || stated === void 0)
+    throw new Error(MISMATCHED_HALVES);
+  return headlineText(latest, stated, record2.observed.checks.state).join(" ");
+}
 function closedAtText(closedAt, p) {
   const m = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2})(?:\.\d+)?Z$/.exec(closedAt);
   return m === null ? p.text(closedAt) : `${m[1]} ${m[2]} UTC`;
@@ -4670,9 +4684,9 @@ function machines(coverage, checks) {
 function walkLines(walk, p) {
   const label = "> - Acceptance walk (the finished work tried as a user would, by someone other than its builder): ";
   if (walk === null)
-    return [`${label}none reported.`];
+    return [`${label}the person closing the phase reported none.`];
   const lines = [
-    `${label}${walk.verdict === "clean" ? "reported as finding no problems." : "reported as finding problems."}`
+    `${label}${walk.verdict === "clean" ? "the person closing the phase said it found no problems." : "the person closing the phase said it found problems."}`
   ];
   walk.findings.forEach((finding, i) => {
     lines.push(`>   - Finding ${String(i + 1)}: ${p.text(finding)}`);
@@ -4963,7 +4977,8 @@ async function obtainBuildRecord(credential, repoRoot, phase, io = NODE_RECORD_P
     return {
       kind: "written",
       jsonPath: relative3(repoRoot, result.jsonPath),
-      mdPath: relative3(repoRoot, result.mdPath)
+      mdPath: relative3(repoRoot, result.mdPath),
+      headline: latestCloseHeadline(answer.record)
     };
   }
   if (isMissingRoute(res.status, raw)) {
@@ -4982,12 +4997,22 @@ async function obtainBuildRecord(credential, repoRoot, phase, io = NODE_RECORD_P
   };
 }
 function refetchCommand(phase) {
-  return `npx halfcycle@latest build-record ${quoteForShell(phase)}`;
+  return `${HALFCYCLE_COMMAND} build-record ${quoteForShell(phase)}`;
 }
 
 // dist/open-phase.js
 import { readFileSync as readFileSync7 } from "node:fs";
 import { join as join7 } from "node:path";
+function describeOpen(opened) {
+  const { phase, previousPhase } = opened;
+  if (previousPhase === phase) {
+    return phase === null ? "Already at project scope \u2014 nothing moved." : `Phase "${phase}" is already open \u2014 nothing moved.`;
+  }
+  const what = phase === null ? "Returned to project scope." : `Opened phase "${phase}".`;
+  if (previousPhase === null)
+    return phase === null ? what : `Moved from project scope to phase "${phase}".`;
+  return opened.decision.blockingFinding === null ? `${what} Phase "${previousPhase}" before it had already been closed.` : `${what} Phase "${previousPhase}" before it was not closed, and this override is recorded.`;
+}
 var OpenPhaseRefused = class extends Error {
   status;
   finding;
@@ -5302,13 +5327,41 @@ function requirementMessage(verb, flag) {
 function runnableInvocation(verb, phase) {
   const contract = contractFor(verb);
   const flags = (contract?.required ?? []).map((req) => `${req.flag} ${PLACEHOLDERS[req.flag] ?? '"\u2026"'}`).join(" ");
-  return `halfcycle ${verb} ${quoteForShell(phase)}${flags ? ` ${flags}` : ""}`;
+  return `${HALFCYCLE_COMMAND} ${verb} ${quoteForShell(phase)}${flags ? ` ${flags}` : ""}`;
 }
 var PLACEHOLDERS = {
   "--verdict": "<clean|defects>",
   "--actor": '"you"',
-  "--evidence": '"\u2026"'
+  "--evidence": '"<what shows this phase is ready to start>"'
 };
+var REASON_PLACEHOLDER = {
+  "open-phase": "<why you are opening it anyway>",
+  "close-phase": "<why you are closing over this>"
+};
+function closeOverrideInvocation(phase, verdict, actor) {
+  return `${HALFCYCLE_COMMAND} close-phase ${quoteForShell(phase)} --verdict ${verdict} --actor ${quoteForShell(actor)} --override --reason "${REASON_PLACEHOLDER["close-phase"]}"`;
+}
+var OWN_WORDS = {
+  "--reason": "reason",
+  "--evidence": "evidence",
+  "--finding": "finding"
+};
+function isPlaceholder(value) {
+  const v = value.trim();
+  return v === "\u2026" || v === "..." || /^<[^<>]+>$/.test(v);
+}
+function placeholderRefusal(verb, tokens) {
+  for (let i = 0; i < tokens.length - 1; i++) {
+    const noun = OWN_WORDS[tokens[i]];
+    const value = tokens[i + 1];
+    if (noun === void 0 || value.startsWith("--"))
+      continue;
+    if (isPlaceholder(value)) {
+      return `halfcycle ${verb}: ${tokens[i]} "${value.trim()}" is a placeholder from an example \u2014 replace it with your own ${noun}; nothing was sent.`;
+    }
+  }
+  return null;
+}
 
 // dist/uninstall.js
 import { lstatSync as lstatSync2, readFileSync as readFileSync8, readdirSync, rmSync as rmSync3, rmdirSync, writeFileSync as writeFileSync5 } from "node:fs";
@@ -5370,7 +5423,7 @@ function readMergedJson(targetRepo, rel) {
     value = void 0;
   }
   if (!isPlainObject2(value)) {
-    throw new Refusal(`${rel} is not a JSON object, so Halfcycle cannot take its own entries out of it and nothing was removed. Fix it or delete it, then run "npx halfcycle uninstall" again.`);
+    throw new Refusal(`${rel} is not a JSON object, so Halfcycle cannot take its own entries out of it and nothing was removed. Fix it or delete it, then run "${HALFCYCLE_COMMAND} uninstall" again.`);
   }
   return { state: "object", value };
 }
@@ -5384,14 +5437,14 @@ function validate(options) {
   if (!lexists(manifestPath)) {
     if (!lexists(pinPath))
       return "not-installed";
-    throw new Refusal(`Halfcycle was installed here by a version that kept no record of what it wrote, so nothing was removed. Run "npx halfcycle" once \u2014 it writes that record \u2014 then run "npx halfcycle uninstall".`);
+    throw new Refusal(`Halfcycle was installed here by a version that kept no record of what it wrote, so nothing was removed. Run "${HALFCYCLE_COMMAND}" once \u2014 it writes that record \u2014 then run "${HALFCYCLE_COMMAND} uninstall".`);
   }
   let manifest;
   try {
     manifest = parseManifest(readFileSync8(manifestPath, "utf-8"));
   } catch (err) {
     const why = err instanceof UnreadableManifestError ? err.message : "it could not be read";
-    throw new Refusal(`${INSTALL_MANIFEST_REL} cannot be read (${why}), so nothing was removed. Restore it from git, or run "npx halfcycle" once to rewrite it, then run "npx halfcycle uninstall" again.`);
+    throw new Refusal(`${INSTALL_MANIFEST_REL} cannot be read (${why}), so nothing was removed. Restore it from git, or run "${HALFCYCLE_COMMAND}" once to rewrite it, then run "${HALFCYCLE_COMMAND} uninstall" again.`);
   }
   let engagementId;
   let pinReadable = true;
@@ -5907,13 +5960,13 @@ function renderUninstallReport(result, home) {
   section("Kept, because it changed after Halfcycle wrote it \u2014 delete it yourself if you do not want it:", result.kept);
   section('Kept in .gitignore, because the path each line covers still exists \u2014 without the line, "git add ." would commit it:', result.keptIgnoreLines);
   section("Left alone \u2014 Halfcycle did not write these, or cannot tell that it did:", result.leftAlone);
-  section('Could not remove \u2014 fix the cause, then run "npx halfcycle uninstall" again to finish:', result.failed);
+  section(`Could not remove \u2014 fix the cause, then run "${HALFCYCLE_COMMAND} uninstall" again to finish:`, result.failed);
   const c = result.credential;
   switch (c.kind) {
     case "still-held":
       out.push(`[halfcycle] This machine still holds this project's credential, at ${shownPath(c.dir, home)}.`);
       out.push("  Every checkout and worktree of this project on this machine uses it.");
-      out.push(`  To remove it too:  npx halfcycle uninstall ${REMOVE_CREDENTIAL_FLAG}`);
+      out.push(`  To remove it too:  ${HALFCYCLE_COMMAND} uninstall ${REMOVE_CREDENTIAL_FLAG}`);
       break;
     case "invalid-id":
       out.push(`[halfcycle] This machine may still hold a credential for this project, but the project id in ${BUNDLE_PIN_REL} is not valid, so it is not shown as a path.`);
@@ -5921,7 +5974,7 @@ function renderUninstallReport(result, home) {
     case "removed":
       out.push(`[halfcycle] Removed this machine's credential for this project, at ${shownPath(c.dir, home)}.`);
       out.push("  Every other checkout and worktree of this project on this machine used it too. Each stops reaching");
-      out.push("  Halfcycle until `npx halfcycle` is run there again.");
+      out.push(`  Halfcycle until \`${HALFCYCLE_COMMAND}\` is run there again.`);
       break;
     case "not-held":
       out.push(`[halfcycle] This machine holds no credential for this project (nothing at ${shownPath(c.dir, home)}).`);
@@ -5930,7 +5983,7 @@ function renderUninstallReport(result, home) {
       out.push(`[halfcycle] No credential was removed: ${BUNDLE_PIN_REL} is missing, so there is no project id to find it by.`);
       break;
     case "failed":
-      out.push(`[halfcycle] Could not remove this machine's credential for this project, at ${shownPath(c.dir, home)}: ${c.reason}. Run "npx halfcycle uninstall ${REMOVE_CREDENTIAL_FLAG}" again to finish.`);
+      out.push(`[halfcycle] Could not remove this machine's credential for this project, at ${shownPath(c.dir, home)}: ${c.reason}. Run "${HALFCYCLE_COMMAND} uninstall ${REMOVE_CREDENTIAL_FLAG}" again to finish.`);
       break;
     case "nothing-to-say":
       break;
@@ -6079,17 +6132,17 @@ function reportClaudeCodeVersion(verbose2, deps = {}) {
 function shortId(id) {
   return id.length > 10 ? `${id.slice(0, 8)}\u2026` : id;
 }
-var USAGE = `  halfcycle [install] [target-repo] [engagement-id] [self-build|client]
+var USAGE = `  ${HALFCYCLE_COMMAND} [install] [target-repo] [engagement-id] [self-build|client]
          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> [--repo <root>]
+  ${HALFCYCLE_COMMAND} check-drift <target-repo>
+  ${HALFCYCLE_COMMAND} build-record <phase> [--repo <root>]
          fetch a closed phase's Build Record again and write it into docs/build-records/
-  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>]
+  ${HALFCYCLE_COMMAND} open-phase <phase|--none> --actor "\u2026" (--evidence "\u2026" | --override --reason "\u2026") [--repo <root>]
+  ${HALFCYCLE_COMMAND} close-phase <phase> --verdict <clean|defects> --actor "\u2026" [--finding "\u2026"]\u2026 [--override --reason "\u2026"] [--repo <root>]
          [--thesis "\u2026"] [--outcome "\u2026"] [--deviation "\u2026"]\u2026
          close the phase and write its Build Record into docs/build-records/
-  halfcycle uninstall [${REMOVE_CREDENTIAL_FLAG}]
+  ${HALFCYCLE_COMMAND} uninstall [${REMOVE_CREDENTIAL_FLAG}]
          take out what the installer added to this project, keeping anything you changed
          ${REMOVE_CREDENTIAL_FLAG}: also remove this machine's credential for the project, which every
          checkout and worktree of that project on this machine shares
@@ -6470,13 +6523,23 @@ ${USAGE}`);
     const toProjectScope = rest.includes("--none");
     const phaseArg = firstPositional(rest);
     if (!toProjectScope && !phaseArg) {
-      process.stderr.write('halfcycle open-phase: name the phase to open, or pass --none to return to project scope.\n  halfcycle open-phase <phase> --actor "you" --evidence "what makes the entry condition hold"\n  halfcycle open-phase <phase> --actor "you" --override --reason "why you are opening it anyway"\n');
+      process.stderr.write(`halfcycle open-phase: name the phase to open, or pass --none to return to project scope.
+  ${HALFCYCLE_COMMAND} open-phase <phase> --actor "you" --evidence "<what shows this phase is ready to start>"
+  ${HALFCYCLE_COMMAND} open-phase <phase> --actor "you" --override --reason "${REASON_PLACEHOLDER["open-phase"]}"
+`);
       process.exit(2);
       return;
     }
     const openShortfalls = missingRequirements("open-phase", rest);
     if (openShortfalls.length > 0) {
       process.stderr.write(`${openShortfalls[0].message}
+`);
+      process.exit(2);
+      return;
+    }
+    const openPlaceholder = placeholderRefusal("open-phase", rest);
+    if (openPlaceholder !== null) {
+      process.stderr.write(`${openPlaceholder}
 `);
       process.exit(2);
       return;
@@ -6491,15 +6554,8 @@ ${USAGE}`);
     try {
       const credential = readRepoCredential(repoRoot);
       const opened = await openPhase(credential, toProjectScope ? null : phaseArg, entry);
-      const what = opened.phase === null ? "project scope" : `phase "${opened.phase}"`;
-      const from = opened.previousPhase === null ? "project scope" : `phase "${opened.previousPhase}"`;
-      if (opened.previousPhase === opened.phase) {
-        process.stdout.write(opened.phase === null ? "[halfcycle] Already at project scope \u2014 nothing moved.\n" : `[halfcycle] Phase "${opened.phase}" is already open \u2014 nothing moved.
-`);
-      } else {
-        process.stdout.write(`[halfcycle] Moved from ${from} to ${what}.
+      process.stdout.write(`[halfcycle] ${describeOpen(opened)}
 `);
-      }
       process.stdout.write(`[halfcycle] Recorded as ${opened.decision.decision} by ${opened.decision.actor} at ${opened.decision.decidedAt}.
 `);
       if (opened.decision.blockingFinding) {
@@ -6529,7 +6585,7 @@ halfcycle open-phase: until ${opened.stampFailure.path} can be written, guard ev
 `);
         }
         if (err.status === 409) {
-          process.stderr.write(`halfcycle open-phase: close the phase first \u2014 \`${runnableInvocation("close-phase", err.previousPhase ?? "<phase>")}\` (add --finding "\u2026" once per finding when the verdict is defects) \u2014 or re-run with --override --reason "\u2026", which is recorded, not waived.
+          process.stderr.write(`halfcycle open-phase: close the phase first \u2014 \`${runnableInvocation("close-phase", err.previousPhase ?? "<phase>")}\` (add --finding "<what is still wrong>" once per finding when the verdict is defects) \u2014 or re-run with --override --reason "${REASON_PLACEHOLDER["open-phase"]}", which is recorded, not waived.
 `);
         }
         process.exit(1);
@@ -6545,13 +6601,23 @@ halfcycle open-phase: until ${opened.stampFailure.path} can be written, guard ev
     const repoRoot = flagValue(rest, "--repo") ?? process.cwd();
     const phaseArg = firstPositional(rest);
     if (!phaseArg) {
-      process.stderr.write('halfcycle close-phase: name the phase you are closing.\n  halfcycle close-phase <phase> --verdict clean --actor "you"\n  halfcycle close-phase <phase> --verdict defects --actor "you" --finding "what is still wrong"\n');
+      process.stderr.write(`halfcycle close-phase: name the phase you are closing.
+  ${HALFCYCLE_COMMAND} close-phase <phase> --verdict clean --actor "you"
+  ${HALFCYCLE_COMMAND} close-phase <phase> --verdict defects --actor "you" --finding "<what is still wrong>"
+`);
       process.exit(2);
       return;
     }
     const closeShortfalls = missingRequirements("close-phase", rest);
     if (closeShortfalls.length > 0) {
       process.stderr.write(`${closeShortfalls[0].message}
+`);
+      process.exit(2);
+      return;
+    }
+    const closePlaceholder = placeholderRefusal("close-phase", rest);
+    if (closePlaceholder !== null) {
+      process.stderr.write(`${closePlaceholder}
 `);
       process.exit(2);
       return;
@@ -6607,7 +6673,7 @@ halfcycle open-phase: until ${opened.stampFailure.path} can be written, guard ev
         findings: findingsDetail.length,
         findingsDetail
       }, closeDecision, void 0, repoRoot, stated);
-      process.stdout.write(`[halfcycle] Phase "${phaseArg}" closed as ${verdict}${findingsDetail.length > 0 ? ` with ${findingsDetail.length} finding(s)` : ""} by ${closeDecision.actor}. The next phase can be opened.
+      process.stdout.write(`[halfcycle] Phase "${phaseArg}" closed by ${closeDecision.actor}${findingsDetail.length > 0 ? `, who reported ${findingsDetail.length} finding(s)` : ""}. The next phase can be opened.
 `);
       if (closeDecision.decision === "override") {
         process.stdout.write(`[halfcycle] This close was an OVERRIDE: ${closeDecision.reason}
@@ -6624,7 +6690,7 @@ halfcycle open-phase: until ${opened.stampFailure.path} can be written, guard ev
       } else {
         process.stderr.write(notWrittenLines("close-phase", obtained, phaseArg));
       }
-      process.stdout.write(`[halfcycle] Open the next phase with: halfcycle open-phase <phase> --actor "you" --evidence "\u2026"
+      process.stdout.write(`[halfcycle] Open the next phase with: ${HALFCYCLE_COMMAND} open-phase <phase> --actor "you" --evidence "<what shows this phase is ready to start>"
 `);
       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}
@@ -6645,7 +6711,7 @@ halfcycle close-phase: until ${closed.stampFailure.path} can be written, guard e
 `);
           process.stderr.write(`halfcycle close-phase: outstanding work \u2014 ${plainOutstandingFinding(err.finding)}
 `);
-          process.stderr.write(`halfcycle close-phase: close it anyway with \`halfcycle close-phase ${quoteForShell(phaseArg)} --verdict ${verdict} --actor ${quoteForShell(closeActor)} --override --reason "\u2026"\` \u2014 recorded, not waived.
+          process.stderr.write(`halfcycle close-phase: close it anyway with \`${closeOverrideInvocation(phaseArg, verdict, closeActor)}\` \u2014 recorded, not waived.
 `);
           process.exit(1);
           return;
@@ -6656,7 +6722,9 @@ halfcycle close-phase: until ${closed.stampFailure.path} can be written, guard e
           process.stderr.write("halfcycle close-phase: Nothing was closed.\n");
         }
         if (err.code === "PhaseAlreadyClosed") {
-          process.stderr.write("halfcycle close-phase: to close a phase again, open it again first.\nhalfcycle close-phase: To get a closed phase's Build Record: npx halfcycle@latest build-record <the phase that closed>\n");
+          process.stderr.write(`halfcycle close-phase: to close a phase again, open it again first.
+halfcycle close-phase: To get a closed phase's Build Record: ${HALFCYCLE_COMMAND} build-record <the phase that closed>
+`);
         }
         process.exit(1);
         return;
@@ -6701,6 +6769,7 @@ function writtenLines(written) {
   return `[halfcycle] Build Record written:
   ${written.mdPath}
   ${written.jsonPath}
+[halfcycle] The record says: ${written.headline}
 `;
 }
 function notWrittenLines(verb, outcome, phase) {