halfcycle 0.4.13 → 0.4.14

package/bin/pre-tool-use-filter.sh

@@ -7,9 +7,96 @@ halfcycle_pt_skip() {
   local hc_t=${EPOCHREALTIME:-} hc_status
   [ "${BASH_VERSINFO[0]:-0}" -ge 5 ] || return 1
   case $hc_t in [0-9]*[.,][0-9][0-9][0-9]*) ;; *) return 1 ;; esac
+  hc_pt_live_text= hc_pt_live_sid= hc_pt_live_agent= hc_pt_live_dir=
   halfcycle_pt_quiet || return 1
+  halfcycle_pt_live || return 1
+  halfcycle_pt_own_copy || return 1
   halfcycle_pt_time_line "$hc_t"
 }
+halfcycle_pt_live() {
+  local LC_ALL=C hc_val hc_sid hc_agent= hc_cwd hc_dir hc_file hc_text= hc_ng=0 hc_re='^[A-Za-z0-9_-]{1,128}$'
+  local -a hc_files
+  halfcycle_pt_string session_id
+  case $? in 0) hc_sid=$hc_val ;; 1) return 0 ;; *) return 1 ;; esac
+  [[ $hc_sid =~ $hc_re ]] || return 0
+  halfcycle_pt_string agent_id
+  case $? in 0) hc_agent=$hc_val ;; 1) ;; *) return 1 ;; esac
+  if [ -n "$hc_agent" ]; then
+    [[ $hc_agent =~ $hc_re ]] || return 0
+    hc_agent=-$hc_agent
+  fi
+  halfcycle_pt_string cwd
+  case $? in 0) hc_cwd=$hc_val ;; 1) return 0 ;; *) return 1 ;; esac
+  [ -n "$hc_cwd" ] || return 0
+  case $hc_cwd in *'\'*|*[$'\n\r']*) return 1 ;; esac
+  hc_dir=${TMPDIR:-/tmp}
+  while [ "${hc_dir%/}" != "$hc_dir" ]; do hc_dir=${hc_dir%/}; done
+  shopt -q nullglob && hc_ng=1
+  shopt -s nullglob
+  hc_files=("$hc_dir"/halfcycle-live-"$hc_sid"/halfcycle-session-[0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z]-"$hc_sid".live"$hc_agent")
+  [ "$hc_ng" = 1 ] || shopt -u nullglob
+  [ "${#hc_files[@]}" -eq 1 ] || return 1
+  hc_file=$hc_dir/${hc_files[0]##*/}
+  IFS= read -r -d '' hc_text < "$hc_file" 2>/dev/null
+  [ "${hc_text%%$'\n'*}" = "$hc_cwd" ] || return 1
+  { printf '%s' "$hc_text" > "$hc_file"; } 2>/dev/null || return 1
+  hc_pt_live_text=$hc_text hc_pt_live_sid=$hc_sid hc_pt_live_agent=${hc_agent#-} hc_pt_live_dir=$hc_dir
+  return 0
+}
+halfcycle_pt_own_copy() {
+  local LC_ALL=C hc_val hc_top hc_rest hc_d hc_f hc_text= hc_ng=0 hc_others=0
+  local -a hc_files
+  halfcycle_pt_string tool_name || return 1
+  case $hc_val in
+    Write|Edit|MultiEdit) ;;
+    *) return 0 ;;
+  esac
+  halfcycle_pt_string file_path || return 1
+  case $hc_val in /*) ;; *) return 1 ;; esac
+  case $hc_val in *'\'*|*[$'\n\r']*) return 1 ;; esac
+  hc_rest=${hc_pt_live_text#*$'\n'}
+  hc_top=${hc_rest%%$'\n'*}
+  case $hc_top in /?*) ;; *) return 1 ;; esac
+  shopt -q nullglob && hc_ng=1
+  shopt -s nullglob
+  hc_files=("$hc_pt_live_dir"/halfcycle-live-"$hc_pt_live_sid"/halfcycle-session-[0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z]-"$hc_pt_live_sid".live-*)
+  [ "$hc_ng" = 1 ] || shopt -u nullglob
+  for hc_f in "${hc_files[@]}"; do
+    if [ -n "$hc_pt_live_agent" ]; then
+      case $hc_f in *.live-"$hc_pt_live_agent") continue ;; esac
+    fi
+    hc_others=1
+  done
+  case $hc_val in
+    "$hc_top"/?*) ;;
+    *) [ -z "$hc_pt_live_agent" ] && [ "$hc_others" = 0 ] && return 0; return 1 ;;
+  esac
+  hc_rest=${hc_val#"$hc_top"/}
+  case /$hc_rest/ in *//*|*/./*|*/../*) return 1 ;; esac
+  hc_d=$hc_top
+  while :; do
+    case $hc_rest in */*) ;; *) break ;; esac
+    hc_d=$hc_d/${hc_rest%%/*}
+    hc_rest=${hc_rest#*/}
+    [ -h "$hc_d" ] && return 1
+    [ -d "$hc_d" ] || break
+    { [ -e "$hc_d/.git" ] || [ -h "$hc_d/.git" ]; } && return 1
+  done
+  [ -z "$hc_pt_live_agent" ] && return 0
+  [ "$hc_others" = 0 ] && return 0
+  shopt -q nullglob && hc_ng=1
+  shopt -s nullglob
+  hc_files=("$hc_pt_live_dir"/halfcycle-live-"$hc_pt_live_sid"/halfcycle-session-[0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z][0-9a-z]-"$hc_pt_live_sid".live)
+  [ "$hc_ng" = 1 ] || shopt -u nullglob
+  [ "${#hc_files[@]}" -eq 1 ] || return 1
+  IFS= read -r -d '' hc_text < "$hc_pt_live_dir/${hc_files[0]##*/}" 2>/dev/null
+  case $hc_text in *$'\n'*$'\n'*) ;; *) return 1 ;; esac
+  hc_text=${hc_text#*$'\n'}
+  hc_text=${hc_text%%$'\n'*}
+  [ -n "$hc_text" ] || return 1
+  [ "$hc_text" = "$hc_top" ] && return 1
+  return 0
+}
 halfcycle_pt_quiet() {
   local LC_ALL=C hc_status hc_ext=0
   shopt -q extglob && hc_ext=1
@@ -29,7 +116,6 @@ halfcycle_pt_quiet_input() {
   case $hc_input in *'"tool_input":{'*) ;; *) return 1 ;; esac
   halfcycle_pt_once '"tool_input"' || return 1
   case $hc_tool in
-    NotebookEdit|Agent) return 0 ;;
     Bash)
       halfcycle_pt_string command
       case $? in 1) return 0 ;; 2) return 1 ;; esac
@@ -225,6 +311,7 @@ halfcycle_pt_records() {
   halfcycle_pt_holds 'features' $'f?(\x01)e?(\x01)a?(\x01)t?(\x01)u?(\x01)r?(\x01)e?(\x01)s' && return 1
   halfcycle_pt_holds 'decisions' $'d?(\x01)e?(\x01)c?(\x01)i?(\x01)s?(\x01)i?(\x01)o?(\x01)n?(\x01)s' && return 1
   halfcycle_pt_holds 'build-tasks.json' $'b?(\x01)u?(\x01)i?(\x01)l?(\x01)d?(\x01)-?(\x01)t?(\x01)a?(\x01)s?(\x01)k?(\x01)s?(\x01).?(\x01)j?(\x01)s?(\x01)o?(\x01)n' && return 1
+  halfcycle_pt_holds 'task-plan.json' $'t?(\x01)a?(\x01)s?(\x01)k?(\x01)-?(\x01)p?(\x01)l?(\x01)a?(\x01)n?(\x01).?(\x01)j?(\x01)s?(\x01)o?(\x01)n' && return 1
   halfcycle_pt_holds 'build-records' $'b?(\x01)u?(\x01)i?(\x01)l?(\x01)d?(\x01)-?(\x01)r?(\x01)e?(\x01)c?(\x01)o?(\x01)r?(\x01)d?(\x01)s' && return 1
   halfcycle_pt_holds '.claude' $'.?(\x01)c?(\x01)l?(\x01)a?(\x01)u?(\x01)d?(\x01)e' && return 1
   return 0
@@ -286,6 +373,11 @@ halfcycle_pt_branch() {
   local hc_dir hc_dotgit hc_gitdir hc_text hc_line hc_ptr hc_path
   hc_branch=null
   case $1 in /*) ;; *) return 0 ;; esac
+  hc_dir=$1
+  while [ -n "$hc_dir" ] && [ "$hc_dir" != / ]; do
+    [ -L "$hc_dir" ] && return 1
+    hc_dir=${hc_dir%/*}
+  done
   halfcycle_pt_resolve "$1"
   hc_dir=$hc_path
   [ -d "$hc_dir" ] || return 0

package/dist/bin.d.ts

@@ -15,6 +15,7 @@
  *   halfcycle draw architecture|phase <phase> — draw the architecture or a phase's pictures into docs/diagrams (`draw/`)
  *   halfcycle plan <phase> [--show]          — check a phase's plan and report it; list it (`plan.ts`)
  *   halfcycle review <phase> --show | --answer <part> "…" — list a phase's close review; answer a question (`review.ts`)
+ *   halfcycle prove <phase> <task> --label "…" (--before|--after) [-- <cmd>] — run a check once on this machine and record what it saw (`prove.ts`)
  *   halfcycle uninstall [--remove-credential] — take back what the installer wrote here
  *
  * NO `ci` VERB (T-25, operator decision 2026-09-22(c)) — `ci bind`/`ci unbind`

package/dist/bin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG"}
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG"}

package/dist/build-record/pair-io.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The file discipline every record-pair writer shares: exclusive create, the
+ * write-then-rename replace, and the no-half-pair create of a `.json` beside its `.md`.
+ *
+ * ONE COPY FOR TWO WRITERS. A phase's Build Record (`write.ts`, `writeRecordPair`) and
+ * a small change's record (`write-change.ts`, `writeChangeRecordPair`) write their pairs
+ * through these helpers, and `draw`'s three-file writer goes through the same seam, so
+ * there is one exclusive-create on disk, not one per writer. What each writer decides
+ * for itself is only what to do when a file is already in the way: the phase writer may
+ * replace its own earlier record, the small-change writer, whose record is write-once,
+ * never replaces.
+ *
+ * Nothing here builds a path. Every caller composes and checks its own paths before it
+ * hands them over (INV-023).
+ */
+/**
+ * The file operations a pair writer makes, behind one seam so a test can make
+ * the SECOND write fail and watch the first come back out. `createExclusive` opens
+ * with `wx` (never truncates an existing file) and removes what it created if the
+ * write itself fails; `rename` replaces in one step on the same filesystem.
+ *
+ * ONE SEAM FOR TEXT AND BYTES. `draw`'s three-file writer (`../draw/write.ts`) goes
+ * through this same seam with a PNG's bytes, so a string is written as UTF-8 and a
+ * byte array as itself.
+ */
+export interface RecordPairIo {
+    createExclusive(path: string, data: string | Uint8Array): void;
+    rename(from: string, to: string): void;
+}
+export declare const NODE_RECORD_PAIR_IO: RecordPairIo;
+/** Serialise a served record for the `.json`: 2-space indent, trailing newline. */
+export declare function serialiseServedRecord(rawRecord: unknown): string;
+/** Is `err` the file system saying the file is already there? */
+export declare function isEexist(err: unknown): boolean;
+/** The text at `path`, or `null` when it cannot be read as a file. */
+export declare function readIfPresent(path: string): string | null;
+/**
+ * Create both files of a pair exclusively, `.json` first. `created`: both are down.
+ * `exists`: one of the two was already there, and nothing this call created is left
+ * behind (a `.json` it created is removed again), so the caller's own replace rule
+ * decides from a clean state. Any other failure is thrown, with nothing left behind.
+ */
+export declare function createPairExclusive(io: RecordPairIo, jsonPath: string, jsonText: string, mdPath: string, mdText: string): 'created' | 'exists';
+/**
+ * Write `text` to `tmp` and rename it over `finalPath`. A `.tmp` left by an earlier
+ * crash is removed first and never read. On failure the temporary file is removed.
+ */
+export declare function replaceOne(io: RecordPairIo, tmp: string, finalPath: string, text: string): void;
+//# sourceMappingURL=pair-io.d.ts.map

package/dist/build-record/pair-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pair-io.d.ts","sourceRoot":"","sources":["../../src/build-record/pair-io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IAC/D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AA2BD,eAAO,MAAM,mBAAmB,EAAE,YAGjC,CAAC;AAEF,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAEhE;AAED,iEAAiE;AACjE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAE9C;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMzD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,YAAY,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,SAAS,GAAG,QAAQ,CAYtB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAS/F"}

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

@@ -0,0 +1,25 @@
+/**
+ * The Markdown half of a small change's record pair (feature `three-paths`, *The
+ * writer*): `renderChangeRecordMarkdown` turns a frozen `smallChangeRecordSchema` value
+ * into the `.md` written beside its `.json` under `docs/build-records/changes/`.
+ *
+ * A SMALL CHANGE IS NOT A PHASE, and its record never reads as one: no line here says
+ * approved, unapproved, or asks for an approval (three-paths AC6, INV-024). A small
+ * change carries no approval to give or to lack, so the words never appear.
+ *
+ * WHOSE WORDS ARE WHOSE (INV-025). What Halfcycle counted is under "What Halfcycle
+ * saw"; the agent's one line, a reviewer's finding, a diagnosis and a call are each
+ * marked as the agent's own. A change that ended without a count (stopped, or moved up
+ * by the person) says Halfcycle did not count it, never that nothing changed. A window
+ * with no recorded check run reads as not observed, never as nothing found (INV-021).
+ *
+ * Every string from the record is printed through the Build Record renderer's own
+ * escapers (`printRecordText` for a slot with a line of its own, `printStrictText` for
+ * a slot sharing a line), so record text cannot become markup. One home for that rule.
+ *
+ * SHIPS TO CLIENT DISK inside the CLI: no comment sits beside an object member.
+ */
+import type { SmallChangeRecord } from '@halfcycle/events';
+/** The `.md` of a small change's record. Pure: the same record renders the same text. */
+export declare function renderChangeRecordMarkdown(record: SmallChangeRecord): string;
+//# sourceMappingURL=render-change.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render-change.d.ts","sourceRoot":"","sources":["../../src/build-record/render-change.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAsH3D,yFAAyF;AACzF,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CA4C5E"}

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

@@ -16,10 +16,12 @@
  * bytes, whatever key order a database hands back.
  *
  * IT DOES NOT PARSE. The caller parses the record first; the type here is the
- * contract's own inferred type. Two of the contract's functions are imported at
+ * contract's own inferred type. Four of the contract's functions are imported at
  * runtime, because each is the one home of what it composes: `codeLinkLine`, the
- * code line every reader prints for a part, and `removalsOf`, the parts a closed
- * review leaves to take out of the system description. Neither is restated here.
+ * code line every reader prints for a part; `removalsOf`, the parts a closed
+ * review leaves to take out of the system description; `hasOwnerReview`, whether a
+ * record kept the owner's review (v3 and v4 did, v2 did not); and `keptPathOf`, the
+ * phase's path a v4 record kept. None is restated here, and no format is compared.
  * The one cross-half rule it relies
  * on — both halves describe the same closes, paired by `sequence` — it checks
  * itself and throws on, because printing a close without its other half would
@@ -77,8 +79,11 @@ export declare function latestCloseHeadline(record: BuildRecord): string;
  * learned an earlier round said something else).
  *
  * Render a parsed Build Record as markdown: v2's observed and attested halves, which
- * a v3 record carries unchanged, and for a v3 record the owner's review after the
- * latest close (RM1–RM3, feature `close-review-and-carry-drop`).
+ * a v3 or v4 record carries unchanged; for a v4 record its path; for a v3 or v4
+ * record the owner's review after the latest close (RM1–RM3, feature
+ * `close-review-and-carry-drop`); and for a v4 record alone the calls made without asking
+ * (C1–C5) and the owner's answers to checks Halfcycle never ran, after the review. An
+ * older record prints neither section, so its Markdown is unchanged.
  *
  * Throws, in client words, if the two halves describe different closes — which a
  * parsed record cannot do. Output uses `\n` only and ends in exactly one `\n`.

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAGL,KAAK,WAAW,EAKjB,MAAM,mBAAmB,CAAC;AA8J3B;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAepD;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASpD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvD;AAgMD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAO/D;AAmRD;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAyEvE"}
+{"version":3,"file":"render-v2.d.ts","sourceRoot":"","sources":["../../src/build-record/render-v2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAgBL,KAAK,WAAW,EAQjB,MAAM,mBAAmB,CAAC;AA8J3B;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAepD;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASpD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvD;AA2MD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAO/D;AAyTD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAgFvE"}

package/dist/build-record/write-change.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The small-change record pair writer (feature `three-paths`, *The writer*).
+ *
+ * A small change's record is not a phase's Build Record, so it never goes through
+ * `writeRecordPair`: it has its own folder, `docs/build-records/changes/`, its own
+ * renderer (`render-change.ts`) and a narrower replace rule.
+ *
+ * THE FILENAME COMES FROM THE CALLER'S `sortingId` ARGUMENT, never from the record
+ * (INV-023). The argument is checked as a UUID (`sortingIdSchema`, the contracts' one
+ * home of a change id) here, where every caller converges, before any path is made,
+ * so the CLI's own check is not the only one. `record.sortingId` is never read for a
+ * path: a record naming another change, or `../x`, still lands at the argument's name.
+ * After the join, every path, temporary ones included, is checked to be a plain file
+ * directly inside the folder, comparing two operands that move independently: the
+ * folder (from `repoRoot` and a constant) and the candidate (from the argument).
+ *
+ * WRITE-ONCE, SO NEVER REPLACED. The service freezes a small change's record once, so
+ * the same `.json` bytes already there are up to date (the `.md` is rendered again,
+ * so a renderer change never refuses the CLI's own pair), and anything else in the way
+ * is refused, naming the file. The exclusive create and the no-half-pair rule are the
+ * shared ones in `pair-io.ts`.
+ *
+ * All-or-nothing: the id is checked, every path asserted and both texts rendered
+ * before the folder is made or the first file created.
+ */
+import { type SmallChangeRecord } from '@halfcycle/events';
+import { type RecordPairIo } from './pair-io.js';
+/** The one output folder for small-change records, relative to the project root. */
+export declare const CHANGE_RECORD_DIR: string;
+/** A change id that cannot name a record file: refused before any path is made. */
+export declare class InvalidChangeIdError extends Error {
+    readonly id: unknown;
+    constructor(id: unknown);
+}
+/**
+ * Assert that a joined path is still a plain file directly inside `outDir`. Exported
+ * so a test can hand it a candidate outside the folder: no id that passes the UUID
+ * check can produce one, so only a direct call can tell this guard from a deleted one.
+ */
+export declare function assertInsideChangeDir(outDir: string, candidate: string, id: unknown): void;
+/**
+ * What `writeChangeRecordPair` did. `created`: neither file existed. `up-to-date`: the
+ * `.json` already held these exact bytes, and the `.md` was rendered again.
+ * `in-the-way`: something else is at one of the two paths; nothing was written and
+ * `path` names it.
+ */
+export type ChangeRecordPairResult = {
+    kind: 'created' | 'up-to-date';
+    jsonPath: string;
+    mdPath: string;
+} | {
+    kind: 'in-the-way';
+    path: string;
+};
+/**
+ * Write a small change's record pair into `docs/build-records/changes/`: the `.json`
+ * as the service sent it, the `.md` rendered from the parsed record.
+ *
+ * @throws InvalidChangeIdError when `sortingId` is not a change id.
+ * @throws the file system's own error when a write fails; nothing is left behind.
+ */
+export declare function writeChangeRecordPair(repoRoot: string, sortingId: string, rawRecord: unknown, record: SmallChangeRecord, io?: RecordPairIo): ChangeRecordPairResult;
+//# sourceMappingURL=write-change.d.ts.map

package/dist/build-record/write-change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-change.d.ts","sourceRoot":"","sources":["../../src/build-record/write-change.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE5E,OAAO,EAML,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,QAA2C,CAAC;AAE1E,mFAAmF;AACnF,qBAAa,oBAAqB,SAAQ,KAAK;IACjC,QAAQ,CAAC,EAAE,EAAE,OAAO;gBAAX,EAAE,EAAE,OAAO;CAIjC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAI1F;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,SAAS,GAAG,YAAY,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,iBAAiB,EACzB,EAAE,GAAE,YAAkC,GACrC,sBAAsB,CA0BxB"}

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

@@ -25,6 +25,7 @@
  * before the `mkdirSync` and the first create, so a refused record leaves no file
  * and no empty directory behind.
  */
+import { NODE_RECORD_PAIR_IO, serialiseServedRecord, type RecordPairIo } from './pair-io.js';
 import { type BuildRecord } from '@halfcycle/events';
 /** The one and only output directory (relative to the target repo root). */
 export declare const BUILD_RECORD_DIR: string;
@@ -43,20 +44,11 @@ export declare const BUILD_RECORD_DIR: string;
  */
 export declare function assertInsideOutDir(outDir: string, candidate: string, identity: unknown): void;
 /**
- * The file operations `writeRecordPair` makes, behind one seam so a test can make
- * the SECOND write fail and watch the first come back out. `createExclusive` opens
- * with `wx` (never truncates an existing file) and removes what it created if the
- * write itself fails; `rename` replaces in one step on the same filesystem.
- *
- * ONE SEAM FOR TEXT AND BYTES. `draw`'s three-file writer (`../draw/write.ts`) goes
- * through this same seam with a PNG's bytes, so a string is written as UTF-8 and a
- * byte array as itself, and there is one exclusive-create on disk, not two.
+ * The shared file discipline (`pair-io.ts`): one exclusive-create, one replace and one
+ * no-half-pair create for this writer and the small-change writer. Re-exported so the
+ * callers that have always imported them from here keep doing so.
  */
-export interface RecordPairIo {
-    createExclusive(path: string, data: string | Uint8Array): void;
-    rename(from: string, to: string): void;
-}
-export declare const NODE_RECORD_PAIR_IO: RecordPairIo;
+export { NODE_RECORD_PAIR_IO, serialiseServedRecord, type RecordPairIo };
 /**
  * What `writeRecordPair` did. `created`: neither file existed. `up-to-date`: the
  * `.json` already held these exact bytes, and the `.md` was rendered again.
@@ -72,8 +64,6 @@ export type RecordPairResult = {
     kind: 'in-the-way';
     path: string;
 };
-/** Serialise a served record for the `.json`: 2-space indent, trailing newline. */
-export declare function serialiseServedRecord(rawRecord: unknown): string;
 /**
  * Write a phase's Build Record pair into `docs/build-records/`: the `.json` as the
  * service sent it, and the `.md` rendered from the parsed record.

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

@@ -1 +1 @@
-{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/build-record/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAcH,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAE3B,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,QAAgC,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAM7F;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IAC/D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AA2BD,eAAO,MAAM,mBAAmB,EAAE,YAGjC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,SAAS,GAAG,YAAY,GAAG,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAEhE;AA0CD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,WAAW,EACnB,EAAE,GAAE,YAAkC,GACrC,gBAAgB,CAyDlB"}
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/build-record/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,EACL,mBAAmB,EAInB,qBAAqB,EACrB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAE3B,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,QAAgC,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAM7F;AAED;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,KAAK,YAAY,EAAE,CAAC;AAEzE;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,SAAS,GAAG,YAAY,GAAG,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AA8BzC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,WAAW,EACnB,EAAE,GAAE,YAAkC,GACrC,gBAAgB,CAkDlB"}

package/dist/change.d.ts

@@ -0,0 +1,136 @@
+/**
+ * `npx halfcycle@latest change` — sorting a change, moving it up, and ending a small
+ * change (Safe, lean, fast · E3, feature `three-paths` AC2–AC4, AC6's writer, AC8's
+ * missing route; `mini-phase` *The CLI*).
+ *
+ * THREE FORMS, required flags declared once in `cli-contract.ts` (`missingRequirements`
+ * enforces them, and the remedy-string seam test reads the same table):
+ * - `change sort --request "<line>" --touches <path>… [--contract <from>:<to>]…
+ *   [--stored-data] [--standing-rule] [--new-part]` checks `docs/system.json` exactly as
+ *   `system` does (`checkAndReportDescription`, the one path), reads HEAD as the start
+ *   commit (a project with no commit cannot sort), sends the description, then the
+ *   sort, and prints control's answer: its sentence, the sorting's id, what to say next.
+ *   The path is never worked out here: control re-runs the one rule (`sortChange`) and
+ *   records its own answer. The request is checked locally with the contracts' own
+ *   `checkChangeSortRequest` first, so a request control would refuse costs no request.
+ * - `change up <mini|full> --change <id>` moves an unfinished small change up and, the
+ *   change now being finished, writes its record pair; `--phase <phase>` moves a mini
+ *   phase up instead. A move down is refused here with the contracts' own sentence,
+ *   before anything is sent; control refuses it again, as it refuses every move down.
+ * - `change done <id>` reads the record FIRST. A record found means the change has
+ *   ended: the pair is written, the outcome printed, and nothing else happens — no
+ *   runner is started, no report is sent. Only when the service says the change has
+ *   not ended does it start the runner's `observe --change <id>`, which reads the
+ *   basis, counts or finishes by the work standing, and prints one line this module
+ *   parses with `observeChangeRunResultSchema` (one home, shared with the runner).
+ *
+ * THE RECORD'S FILENAME COMES FROM THE `<id>` ARGUMENT, checked as a change id here and
+ * again by the writer, never from a field of the record (INV-023).
+ *
+ * A SMALL CHANGE IS NOT A PHASE (INV-024): no line here asks for, mentions or marks an
+ * approval. Every sentence about a path is the contracts' `CHANGE_PATH_WORDS` or
+ * control's own answer; none is restated here (INV-003). Nothing a step id; the next
+ * thing to say is the phrase control's answer carries (INV-016).
+ *
+ * TOPOLOGY. Every route here takes the project credential alone: no GitHub
+ * installation, no open phase, no portal session (INV-022). A service without a route
+ * is told apart by `isMissingRoute`, and the CLI says so and exits 1.
+ *
+ * INV-001: Node builtins, the global `fetch`, `@halfcycle/events` and `@halfcycle/core`
+ * only; the runner is spawned, never imported. SHIPS TO CLIENT DISK inside the CLI: no
+ * comment sits beside an object member, and every string is a sentence a person reads.
+ */
+import { type ChangeContract, type ObserveChangeRunResult, type SmallChangeRecord } from '@halfcycle/events';
+import { type HeadCommitOutcome } from './close-phase.js';
+import type { RepoCredential } from './open-phase.js';
+import { type SystemDeps, type SystemRun } from './system-report.js';
+import { type ChangeRecordPairResult } from './build-record/write-change.js';
+/** The verb's usage, one home: printed by `--help` and by a usage error. */
+export declare const CHANGE_USAGE: string;
+/** What one invocation asks for, once its words have been read. */
+export type ChangeArgs = {
+    readonly form: 'sort';
+    readonly request: string;
+    readonly touches: readonly string[];
+    readonly contracts: readonly ChangeContract[];
+    readonly storedData: boolean;
+    readonly standingRule: boolean;
+    readonly newPart: boolean;
+    readonly repoRoot?: string;
+} | {
+    readonly form: 'up';
+    readonly to: 'mini' | 'full';
+    readonly target: {
+        readonly kind: 'change';
+        readonly sortingId: string;
+    } | {
+        readonly kind: 'phase';
+        readonly phase: string;
+    };
+    readonly repoRoot?: string;
+} | {
+    readonly form: 'done';
+    readonly sortingId: string;
+    readonly repoRoot?: string;
+};
+/** The words read, or the line to print and the code to exit with. Nothing was sent. */
+export type ParsedChange = {
+    ok: true;
+    args: ChangeArgs;
+} | {
+    ok: false;
+    line: string;
+    exitCode: 1 | 2;
+};
+/**
+ * Read `rest` (the words after `change`). The required flags are the contract's
+ * (`missingRequirements`), refused first with the contract's own sentence; then each
+ * form's own words are read, and anything else is a usage error. Nothing is read from
+ * disk and nothing is sent.
+ */
+export declare function parseChangeArgs(rest: readonly string[]): ParsedChange;
+/** The pieces the verb reaches outside itself through; replaced in tests. */
+export interface ChangeDeps extends SystemDeps {
+    readonly readHead: (repoRoot: string) => HeadCommitOutcome;
+    readonly fetch: typeof fetch;
+    readonly observeChange: (credential: RepoCredential, repoRoot: string, sortingId: string) => Promise<ObserveChangeRunResult>;
+    readonly writePair: (repoRoot: string, sortingId: string, rawRecord: unknown, record: SmallChangeRecord) => ChangeRecordPairResult;
+}
+/**
+ * The one line the `observe --change` child printed, read through the shared
+ * `observeChangeRunResultSchema`, or `unreachable` when stdout holds no such line.
+ */
+export declare function readObserveChangeLine(stdout: string): ObserveChangeRunResult;
+/**
+ * End a small change through the runner's `observe --change <id>`, spawned the way the
+ * close step spawns the runner's verbs (`runRunnerChild`), with the same credential.
+ * The id is the checked argument. Never throws.
+ */
+export declare function runObserveChangeChild(binary: string | Error, credential: RepoCredential, repoRoot: string, sortingId: string): Promise<ObserveChangeRunResult>;
+/** The line naming what to say next: the phrase the service's answer carries. */
+export declare function nextSayLine(say: string): string;
+/** The command that ends a small change, or writes its record again: the one remedy. */
+export declare function changeDoneCommand(sortingId: string): string;
+/** What a finished change's record says about how it ended, in the contracts' words. */
+export declare function recordOutcomeLines(record: SmallChangeRecord): string;
+/**
+ * `change sort`. The local check runs with the description that just passed and the
+ * HEAD just read; the description version is not known until the service answers, so
+ * the local check is given the lowest version there is, which no rule reads beyond its
+ * shape. The request that leaves carries the version the service gave.
+ */
+export declare function runChangeSort(repoRoot: string, args: Extract<ChangeArgs, {
+    form: 'sort';
+}>, deps: ChangeDeps): Promise<SystemRun>;
+/** `change up`: a small change by its id, or a mini phase by its name. */
+export declare function runChangeUp(repoRoot: string, args: Extract<ChangeArgs, {
+    form: 'up';
+}>, deps: ChangeDeps): Promise<SystemRun>;
+/**
+ * `change done <id>`. The record is read first; the runner is started only when the
+ * service says the change has not ended (three-paths AC4).
+ */
+export declare function runChangeDone(repoRoot: string, sortingId: string, deps: ChangeDeps): Promise<SystemRun>;
+/** The whole verb, once its words are read: the form's run. */
+export declare function runChange(repoRoot: string, args: ChangeArgs, deps: ChangeDeps): Promise<SystemRun>;
+//# sourceMappingURL=change.d.ts.map

package/dist/change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change.d.ts","sourceRoot":"","sources":["../src/change.ts"],"names":[],"mappings":"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"}

package/dist/check-tasks.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `npx halfcycle@latest check-tasks <phase> [--with-task-list] [--repo <root>]`
+ * (`collision-free-parallel-work` AC3; `checks-as-work-lands` AC3, AC6).
+ *
+ * OFFLINE, ALWAYS. This verb reads at most two files on the person's own machine —
+ * `docs/build-records/task-plan.json` and, with `--with-task-list`,
+ * `docs/build-records/build-tasks.json` — and nothing else. It opens no credential
+ * file, makes no network call, and needs no sign-in. Everything it prints comes from
+ * `checkTaskPlan` (`@halfcycle/core`), which is pure: this module's whole job is
+ * reading the two files, handing them to that function, and printing what it
+ * returns.
+ *
+ * ONE HOME FOR THE PLAN'S SHAPE AND ITS RULES (INV-003): `taskPlanSchema`,
+ * `taskListFileSchema`, `checkTaskPlan` and every line it prints live in
+ * `@halfcycle/core`'s `task-plan.ts`. This file restates none of them — it only
+ * turns a missing or unparsable file into the one kind of answer this verb gives for
+ * that (exit 2, naming the file), and turns the function's lines into the exit code
+ * the spec pins (0 clean, 1 any refusal).
+ *
+ * THE TASK LIST IS READ ONLY WHEN ASKED. Without `--with-task-list` this verb never
+ * opens `build-tasks.json`, so a stale or disagreeing list on disk from an earlier
+ * phase changes nothing about a planning run — the one case
+ * `collision-free-parallel-work`'s *Decisions taken* exists to prevent.
+ *
+ * A MISSING TASK LIST IS NOT AN ERROR. Only the plan file is required input; a task
+ * list that is missing, names another phase, or carries no phase at all (the shape
+ * written before this release) reads as `checkTaskPlan`'s note N1 and exits 0 on an
+ * otherwise clean plan. A plan file in the same state is always a hard failure (exit
+ * 2), because the plan is this verb's one required input.
+ *
+ * SHIPS TO CLIENT DISK inside the CLI (INV-001: Node builtins, `@halfcycle/core`
+ * only — no network, so no `@halfcycle/events` and no `fetch`). Every string here is
+ * a sentence a person reads in their own terminal, so none names an internal
+ * register, a route, or this project's own tooling; no comment sits beside an
+ * object member.
+ */
+/** The usage line, printed for no phase, an extra argument or an unknown flag. */
+export declare const CHECK_TASKS_USAGE = "npx halfcycle@latest check-tasks <phase> [--with-task-list] [--repo <root>]";
+/**
+ * What the arguments after `check-tasks` came to. Exactly one positional (the
+ * phase), at most one `--with-task-list` and at most one `--repo <root>`; anything
+ * else, no phase included, is usage.
+ */
+export type CheckTasksArgs = {
+    ok: true;
+    phase: string;
+    withTaskList: boolean;
+    repoRoot: string | undefined;
+} | {
+    ok: false;
+};
+export declare function parseCheckTasksArgs(argv: readonly string[]): CheckTasksArgs;
+/** What a run of the verb came to. */
+export interface CheckTasksRun {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+/**
+ * The whole verb. Reads `docs/build-records/task-plan.json` under `repoRoot`, and,
+ * with `withTaskList`, `docs/build-records/build-tasks.json`; hands both to
+ * `checkTaskPlan` and prints its lines, one per line, in the order it returns them,
+ * or `checkTaskPlan`'s own clear line when there is nothing to report. Never throws.
+ *
+ * Exit 0 when nothing refuses, 1 when anything does, 2 when the plan file is
+ * missing or either file cannot be read or parsed as JSON or does not match the
+ * shape this tool reads (naming which file, and where). A missing task list is not
+ * an error (see the module header) and never changes the exit code on its own.
+ */
+export declare function runCheckTasks(repoRoot: string, phase: string, withTaskList: boolean): CheckTasksRun;
+//# sourceMappingURL=check-tasks.d.ts.map

package/dist/check-tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-tasks.d.ts","sourceRoot":"","sources":["../src/check-tasks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAgBH,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,gFAAgF,CAAC;AAE/G;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAChF;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AAElB,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAuB3E;AA2CD,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,aAAa,CA4BnG"}