halfcycle 0.3.39 → 0.4.0

package/dist/build-record/obtain.d.ts

@@ -19,8 +19,8 @@
  * would reorder keys. The schema parse decides only whether it is written at all.
  *
  * INV-001: Node builtins, the global `fetch`, `@halfcycle/events` and
- * `@halfcycle/core` only (the latter for the one shared shell-quoting helper,
- * `quoteForShell`, used by `refetchCommand` below).
+ * `@halfcycle/core` only (the latter for the shared command prefix and shell-quoting
+ * helper, used by `refetchCommand` below).
  * SHIPS TO CLIENT DISK inside the CLI: every string here is a client-facing
  * sentence, and no comment sits beside an object member.
  */
@@ -32,11 +32,13 @@ import { type RecordPairIo } from './write.js';
  * relative to the repository). `exists`: a file this CLI will not replace is in the
  * way; nothing was written. `withheld` and `refused`: the service's answer, with its
  * own sentence. `unavailable`: the record could not be obtained, and `why` says so.
+ * `headline` is the latest close's headline as the .md states it, in plain words.
  */
 export type ObtainOutcome = {
     kind: 'written';
     jsonPath: string;
     mdPath: string;
+    headline: string;
 } | {
     kind: 'exists';
     path: string;

package/dist/build-record/obtain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"obtain.d.ts","sourceRoot":"","sources":["../../src/build-record/obtain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAwC,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAErF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,wBAAwB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;CAM+B,CAAC;AAE9D,8EAA8E;AAC9E,eAAO,MAAM,eAAe,EAAE,SAAS,wBAAwB,EAA2C,CAAC;AAE3G,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,UAAU,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKhF;AASD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,cAAc,EAC1B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,EAAE,GAAE,YAAkC,GACrC,OAAO,CAAC,aAAa,CAAC,CA0ExB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD"}
+{"version":3,"file":"obtain.d.ts","sourceRoot":"","sources":["../../src/build-record/obtain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAwC,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAGrF;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,wBAAwB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;CAM+B,CAAC;AAE9D,8EAA8E;AAC9E,eAAO,MAAM,eAAe,EAAE,SAAS,wBAAwB,EAA2C,CAAC;AAE3G,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,UAAU,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKhF;AASD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,cAAc,EAC1B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,EAAE,GAAE,YAAkC,GACrC,OAAO,CAAC,aAAa,CAAC,CA2ExB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/build-record/render-v2.d.ts

@@ -38,6 +38,14 @@ import type { BuildRecordV2 } from '@halfcycle/events';
  * so a slot is never silently empty.
  */
 export declare function printRecordText(text: string): string;
+/**
+ * The latest close's headline in plain words — the same title and sentence the .md
+ * opens that close with, without the bold. The CLI prints it after a close (cp4f
+ * T-20, acceptance walk F9), so the terminal and the record say one thing about
+ * how the phase closed: the terminal said "closed as clean" beside a record that
+ * said "this is not a clean result".
+ */
+export declare function latestCloseHeadline(record: BuildRecordV2): string;
 /**
  * Render a parsed v2 Build Record as markdown.
  *

package/dist/build-record/render-v2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-v2.d.ts","sourceRoot":"","sources":["../../src/build-record/render-v2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AA4JvD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAepD;AAuUD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CA2DzE"}
+{"version":3,"file":"render-v2.d.ts","sourceRoot":"","sources":["../../src/build-record/render-v2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AA4JvD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAepD;AAsLD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAOjE;AA+JD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CA2DzE"}

package/dist/cli-contract.d.ts

@@ -124,7 +124,9 @@ export declare function requirementMessage(verb: CliVerb, flag: string): string;
  *
  * RENDERED, not typed out. A remedy string built by hand is the defect this file
  * was opened for; one built here cannot omit a flag, because the flags come from
- * the same table the binary refuses on.
+ * the same table the binary refuses on. It starts with `HALFCYCLE_COMMAND`
+ * (`packages/core`), the one home of how a printed command reaches this CLI: a
+ * bare `halfcycle` is not on a client's PATH (cp4f T-20).
  *
  * `phase` is quoted for the shell (`quoteForShell`, `packages/core`) — a phase
  * name has no closed vocabulary and a space or `#` in it would otherwise paste
@@ -134,4 +136,25 @@ export declare function requirementMessage(verb: CliVerb, flag: string): string;
  * argument parser, which is a wider change than this function and is not done.
  */
 export declare function runnableInvocation(verb: CliVerb, phase: string): string;
+/**
+ * The `--reason` each verb's override remedy prints. Angle-bracketed so it reads
+ * as something to replace, and so `placeholderRefusal` refuses it if it is pasted
+ * unchanged — an ellipsis was pasted and recorded as the reason (cp4f T-20).
+ */
+export declare const REASON_PLACEHOLDER: {
+    readonly 'open-phase': "<why you are opening it anyway>";
+    readonly 'close-phase': "<why you are closing over this>";
+};
+/**
+ * The override remedy a refused close prints: the close the developer asked for,
+ * every value they typed quoted for the shell, plus `--override` and a reason
+ * still to be written.
+ */
+export declare function closeOverrideInvocation(phase: string, verdict: string, actor: string): string;
+/**
+ * The refusal for the first recorded flag whose value is still a placeholder, or
+ * `null`. Checked before anything is sent: the value would otherwise be recorded
+ * as written, in a record that is never rewritten.
+ */
+export declare function placeholderRefusal(verb: CliVerb, tokens: readonly string[]): string | null;
 //# sourceMappingURL=cli-contract.d.ts.map

package/dist/cli-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-contract.d.ts","sourceRoot":"","sources":["../src/cli-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAIH,iFAAiF;AACjF,eAAO,MAAM,SAAS,+FAAgG,CAAC;AAEvH,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,CAAC;CAClD;AAsFD,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAElE;AAED,iDAAiD;AACjD,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAmBD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,CAyBxF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMtE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMvE"}
+{"version":3,"file":"cli-contract.d.ts","sourceRoot":"","sources":["../src/cli-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAIH,iFAAiF;AACjF,eAAO,MAAM,SAAS,+FAAgG,CAAC;AAEvH,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,CAAC;CAClD;AAsFD,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAElE;AAED,iDAAiD;AACjD,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAmBD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,CAyBxF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMtE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMvE;AASD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;CAGrB,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK7F;AAmBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAa1F"}

package/dist/index.js

@@ -213,6 +213,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";
@@ -3547,31 +3548,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`;
@@ -3624,9 +3638,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)}`);
@@ -3919,7 +3933,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)) {
@@ -3938,7 +3953,7 @@ 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)}`;
 }
 export {
   BUILD_RECORD_DIR,