halfcycle 0.4.5 → 0.4.7

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // dist/bin.js
-import { existsSync as existsSync7, readFileSync as readFileSync11, realpathSync as realpathSync3, statSync, writeSync as writeSync2 } from "node:fs";
+import { existsSync as existsSync7, readFileSync as readFileSync14, realpathSync as realpathSync4, statSync, writeSync as writeSync2 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { join as join12 } from "node:path";
+import { join as join15 } from "node:path";
 
 // dist/install.js
 import { execFileSync as execFileSync2 } from "node:child_process";
@@ -143,6 +143,7 @@ var VENDORED_BIN_REL = ".halfcycle/bin/bin.bundle.mjs";
 var SESSION_START_MARKER_REL = ".claude/hooks/session-start-marker.sh";
 var GUARD_RUNNER_REL = ".claude/hooks/guard-runner.sh";
 var USER_PROMPT_REMINDER_REL = ".claude/hooks/user-prompt-reminder.sh";
+var USER_PROMPT_SCOPE_REL = ".claude/hooks/user-prompt-scope.sh";
 var SESSION_END_MARKER_REL = ".claude/hooks/session-end-marker.sh";
 var WRITE_CAPABLE_TOOLS = ["Edit", "MultiEdit", "NotebookEdit", "Write"];
 function hookCommand(script, verb) {
@@ -171,6 +172,13 @@ var HALFCYCLE_HOOK_WIRING = [
     command: hookCommand(USER_PROMPT_REMINDER_REL),
     script: USER_PROMPT_REMINDER_REL
   },
+  {
+    event: "UserPromptSubmit",
+    matcher: null,
+    timeout: 10,
+    command: hookCommand(USER_PROMPT_SCOPE_REL),
+    script: USER_PROMPT_SCOPE_REL
+  },
   {
     event: "PostToolUse",
     matcher: WRITE_CAPABLE_TOOLS.join("|"),
@@ -252,6 +260,131 @@ function quoteForShell(value) {
 }
 var HALFCYCLE_COMMAND = "npx halfcycle@latest";
 
+// ../core/dist/shown-plans.js
+var SHOWN_PLANS_FILENAME = "shown-plans.json";
+var SHOWN_PLANS_FORMAT = 1;
+var RECORD_KEYS = ["entries", "format"];
+var ENTRY_KEYS = ["number", "phase", "shownAt", "version"];
+function parseShownPlans(text) {
+  try {
+    if (typeof text !== "string")
+      return [];
+    const parsed = JSON.parse(text);
+    if (!isPlainObject(parsed) || !hasExactKeys(parsed, RECORD_KEYS))
+      return [];
+    if (parsed["format"] !== SHOWN_PLANS_FORMAT)
+      return [];
+    const rawEntries = parsed["entries"];
+    if (!Array.isArray(rawEntries))
+      return [];
+    const entries = [];
+    for (const raw of rawEntries) {
+      const entry = readEntry(raw);
+      if (entry === null)
+        return [];
+      entries.push(entry);
+    }
+    return hasDuplicates(entries) ? [] : entries;
+  } catch {
+    return [];
+  }
+}
+function serialiseShownPlans(entries) {
+  if (!Array.isArray(entries))
+    throw new Error(UNRECORDABLE);
+  const copied = [];
+  for (const raw of entries) {
+    const entry = readEntry(raw);
+    if (entry === null)
+      throw new Error(UNRECORDABLE);
+    copied.push(entry);
+  }
+  if (hasDuplicates(copied))
+    throw new Error(UNRECORDABLE);
+  return `${JSON.stringify({ format: SHOWN_PLANS_FORMAT, entries: copied }, null, 2)}
+`;
+}
+var UNRECORDABLE = "the list just shown could not be recorded on this machine.";
+function readEntry(raw) {
+  if (!isPlainObject(raw) || !hasExactKeys(raw, ENTRY_KEYS))
+    return null;
+  const phase = raw["phase"];
+  const number = raw["number"];
+  const version = raw["version"];
+  const shownAt = raw["shownAt"];
+  if (typeof phase !== "string" || phase === "")
+    return null;
+  if (!isPositiveInteger(number) || !isPositiveInteger(version))
+    return null;
+  if (!isIsoInstant(shownAt))
+    return null;
+  return { phase, number, version, shownAt };
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function hasExactKeys(value, keys) {
+  const own = Object.keys(value).sort();
+  return own.length === keys.length && own.every((key, i) => key === keys[i]);
+}
+function isPositiveInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+}
+function isIsoInstant(value) {
+  if (typeof value !== "string")
+    return false;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) && new Date(ms).toISOString() === value;
+}
+function hasDuplicates(entries) {
+  const phases = new Set(entries.map((entry) => entry.phase));
+  const numbers = new Set(entries.map((entry) => entry.number));
+  return phases.size !== entries.length || numbers.size !== entries.length;
+}
+
+// ../core/dist/phase-reference.js
+var TYPED_NUMBER = /^(?:0|[1-9][0-9]*)$/;
+function resolvePhaseReference(typed, phases) {
+  if (typeof typed !== "string" || typed === "")
+    return null;
+  const byIdentity = phases.filter((entry) => entry.phase === typed);
+  if (byIdentity.length > 0)
+    return byIdentity.length === 1 ? byIdentity[0] : null;
+  if (!TYPED_NUMBER.test(typed))
+    return null;
+  const byNumber = phases.filter((entry) => Number.isInteger(entry.number) && String(entry.number) === typed);
+  return byNumber.length === 1 ? byNumber[0] : null;
+}
+
+// ../core/dist/release-version.js
+var RELEASE_VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+function isReleaseVersion(value) {
+  return typeof value === "string" && RELEASE_VERSION_PATTERN.test(value);
+}
+function significant(part) {
+  const trimmed = part.replace(/^0+/, "");
+  return trimmed === "" ? "0" : trimmed;
+}
+function compareReleaseVersions(a, b) {
+  if (!isReleaseVersion(a) || !isReleaseVersion(b)) {
+    throw new TypeError("compareReleaseVersions takes two MAJOR.MINOR.PATCH versions");
+  }
+  const pa = a.split(".").map(significant);
+  const pb = b.split(".").map(significant);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i];
+    const y = pb[i];
+    if (x.length !== y.length)
+      return x.length - y.length;
+    if (x !== y)
+      return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
 // ../events/dist/result.js
 import { z as z2 } from "zod";
 var firedGuardSchema = z2.object({
@@ -321,18 +454,19 @@ function hasLoneSurrogate(text) {
 }
 var LONE_SURROGATE_MESSAGE = "must be valid text: it holds half of a character pair with no other half";
 
-// ../events/dist/build-record.js
-import { z as z4 } from "zod";
-
 // ../events/dist/state.js
 import { z as z3 } from "zod";
 var utcIso8601 = z3.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/, "must be a UTC ISO-8601 timestamp ending in Z");
 var STATE_RECORD_FORMAT = "halfcycle-state-record/v1";
 var stepIdSchema = z3.string().regex(/^(l[0-5](-l[0-5])?|xl)\.[a-z0-9-]+$/);
-var methodVersionSchema = z3.string().regex(/^\d+\.\d+\.\d+$/);
+var methodVersionSchema = z3.string().regex(RELEASE_VERSION_PATTERN);
 var anchorPathRegex = /^(?!\/)(?!.*#)(?!method\/)(?!(.*\/)?docs\/method\/).+$/;
 var recordKindSchema = z3.enum(["artefact", "step-run", "gate", "intervention"]);
 var methodLayerSchema = z3.enum(["l0", "l1", "l2", "l3", "l3-l4", "l4", "l5", "xl"]);
+var PHASE_SCOPED_LAYERS = ["l4", "l5"];
+function isPhaseScopedLayer(layer) {
+  return PHASE_SCOPED_LAYERS.includes(layer);
+}
 var evidenceKindSchema = z3.enum(["anchor", "diff", "repro", "question-answer", "no-op"]);
 var declarableEvidenceKindSchema = z3.enum(["anchor", "diff", "repro", "question-answer"]);
 var dispositionSchema = z3.enum([
@@ -506,6 +640,9 @@ var stateRecordSchema = z3.discriminatedUnion("recordKind", [
   interventionRecordSchema
 ]);
 
+// ../events/dist/build-record.js
+import { z as z4 } from "zod";
+
 // ../events/dist/control-characters.js
 var CONTROL_CHARACTER_CLASS = "\\p{Cc}";
 var CONTROL_CHARACTER = new RegExp(CONTROL_CHARACTER_CLASS, "u");
@@ -609,9 +746,11 @@ function statementText(max) {
   });
 }
 var closeActorSchema = plainText(ACTOR_MAX);
+var PHASE_NAME_RULE = `must be a phase name: not empty, no slash or backslash, not starting with a dot, no control characters, at most ${PHASE_NAME_MAX_BYTES} bytes`;
 var phaseNameSchema = z4.string().refine((v) => isValidPhaseIdentity(v), {
-  message: `must be a phase name: not empty, no slash or backslash, not starting with a dot, no control characters, at most ${PHASE_NAME_MAX_BYTES} bytes`
+  message: PHASE_NAME_RULE
 });
+var phaseIdentitySchema = z4.union([z4.string(), z4.number()], { error: "must be a phase name or a whole number" }).refine((v) => isValidPhaseIdentity(v), { message: PHASE_NAME_RULE });
 var closeStatementsSchema = z4.object({
   thesis: statementText(STATEMENT_MAX).nullable(),
   outcome: statementText(STATEMENT_MAX).nullable(),
@@ -887,17 +1026,31 @@ var phaseEntryDecisionRecordSchema = z5.object({
   blockingFinding: z5.string().nullable(),
   decidedAt: utcIso86012
 }).strict();
+var methodUpdateSchema = z5.object({
+  from: methodVersionSchema,
+  to: methodVersionSchema
+}).strict();
 var openPhaseResponseSchema = z5.object({
   engagement: engagementStatusResponseSchema,
   /** What is open now. `null` is project scope. */
   phase: z5.string().nullable(),
   /** What was open before this decision. `null` is project scope. */
   previousPhase: z5.string().nullable(),
-  decision: phaseEntryDecisionRecordSchema
+  decision: phaseEntryDecisionRecordSchema,
+  /** The method version this project moved to with this open, or `null` when it did not move. */
+  methodUpdated: methodUpdateSchema.nullable()
+}).strict();
+var acceptPhaseResponseSchema = engagementStatusResponseSchema.extend({
+  methodUpdated: methodUpdateSchema.nullable()
 }).strict();
 
 // ../events/dist/crew.js
 import { z as z6 } from "zod";
+
+// ../events/dist/human-agent.js
+var HUMAN_AGENT = "Human";
+
+// ../events/dist/crew.js
 var crewGroupSchema = z6.enum(["builder", "reviewer", "always-on"]);
 var crewTierSchema = z6.enum(["deep", "standard", "fast"]);
 var CREW_DISCIPLINE_MAX = 64;
@@ -1090,9 +1243,700 @@ var CREW_ROSTER = [
 var CREW_ROSTER_SIZE = CREW_ROSTER.length;
 var CREW_CALLSIGNS = CREW_ROSTER.map((member) => member.callsign);
 
-// ../events/dist/device-auth.js
+// ../events/dist/build-snapshot.js
 import { z as z7 } from "zod";
-var utcIso86013 = z7.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/, "must be a UTC ISO-8601 timestamp ending in Z");
+var buildTaskStateSchema = z7.enum([
+  "pending",
+  "in-flight",
+  "completed",
+  "failed",
+  "blocked"
+]);
+var BUILD_TASK_TITLE_MAX = 240;
+var BUILD_SNAPSHOT_TASK_LIMIT = 500;
+var buildTaskSchema = z7.object({
+  // The task's own id, as the coordinator's graph names it.
+  id: z7.string().min(1).max(64),
+  // What the task is, in the coordinator's words. A description of the work,
+  // bounded and scanned — never an excerpt of anybody's code.
+  title: z7.string().min(1).max(BUILD_TASK_TITLE_MAX),
+  // What the task is doing right now.
+  state: buildTaskStateSchema,
+  // Who holds it — a bare callsign, or the value naming a person when the work is
+  // a person's. Absent when nothing has been dispatched to it yet.
+  agent: z7.string().min(1).max(32).optional(),
+  // The kind of work the holder does. Present exactly when an agent holds it.
+  discipline: z7.string().min(1).max(64).optional(),
+  // How much thinking the holder brings. Present exactly when an agent holds it,
+  // and there is no field naming the supplier behind it.
+  tier: z7.string().min(1).max(32).optional(),
+  // The tasks this one cannot start before. Always present; empty means it waits
+  // on nothing, which is different from not having been computed.
+  dependsOn: z7.array(z7.string().min(1).max(64)).max(BUILD_SNAPSHOT_TASK_LIMIT),
+  // The one task this task checks, when it is a check on other work. Absent on a
+  // task that is doing the work rather than checking it.
+  reviews: z7.string().min(1).max(64).optional(),
+  // Which wave of the phase this task belongs to — the wave that writes the
+  // specifications, or the wave that builds them. Absent when the graph does not
+  // record it, which is different from the task belonging to neither.
+  layer: methodLayerSchema.optional(),
+  // When it was picked up, and when it settled. A reader computes how long it
+  // took; neither this row nor this payload carries a duration.
+  startedAt: utcIso8601.optional(),
+  settledAt: utcIso8601.optional()
+}).strict().superRefine((task, ctx) => {
+  if (task.reviews !== void 0 && task.reviews === task.id) {
+    ctx.addIssue({
+      code: z7.ZodIssueCode.custom,
+      path: ["reviews"],
+      message: `'${task.id}' reviews itself \u2014 a review names the OTHER task it checks.`
+    });
+  }
+  if (task.layer !== void 0 && !isPhaseScopedLayer(task.layer)) {
+    ctx.addIssue({
+      code: z7.ZodIssueCode.custom,
+      path: ["layer"],
+      message: `'${task.layer}' is not a wave a phase runs \u2014 expected one of ${PHASE_SCOPED_LAYERS.join(", ")}.`
+    });
+  }
+  const profiled = task.agent !== void 0 && task.agent !== HUMAN_AGENT;
+  for (const field of ["discipline", "tier"]) {
+    if (profiled && task[field] === void 0) {
+      ctx.addIssue({
+        code: z7.ZodIssueCode.custom,
+        path: [field],
+        message: `'${field}' is required on a task an agent holds.`
+      });
+    }
+    if (!profiled && task[field] !== void 0) {
+      ctx.addIssue({
+        code: z7.ZodIssueCode.custom,
+        path: [field],
+        message: task.agent === void 0 ? `'${field}' must be absent on a task nobody holds.` : `'${field}' must be absent on work a person holds.`
+      });
+    }
+  }
+});
+var buildPhaseSchema = z7.string().min(1).max(128);
+var BUILD_PHASE_TITLE_MAX = 160;
+var buildPhaseTitleSchema = z7.string().min(1).max(BUILD_PHASE_TITLE_MAX);
+var buildTaskListSchema = z7.array(buildTaskSchema).max(BUILD_SNAPSHOT_TASK_LIMIT).superRefine((tasks, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, task] of tasks.entries()) {
+    if (seen.has(task.id)) {
+      ctx.addIssue({
+        code: z7.ZodIssueCode.custom,
+        path: [index, "id"],
+        message: `duplicate task id '${task.id}' \u2014 one graph names each task once.`
+      });
+    }
+    seen.add(task.id);
+  }
+});
+var buildSnapshotSchema = z7.object({
+  // Which phase this graph belongs to.
+  phase: buildPhaseSchema,
+  // That phase's name in words, when the project gives it one.
+  phaseTitle: buildPhaseTitleSchema.optional(),
+  // Every task on it. Never a partial graph and never a change since last time.
+  tasks: buildTaskListSchema,
+  // When this graph was last reported.
+  reportedAt: utcIso8601,
+  // When work on this phase was first reported with no approval of its scope in force.
+  builtWithoutApproval: utcIso8601.optional()
+}).strict();
+var buildPhaseEntrySchema = z7.object({
+  // Which phase has a stored graph.
+  phase: buildPhaseSchema,
+  // That phase's name in words, when the project gave it one.
+  phaseTitle: buildPhaseTitleSchema.optional(),
+  // When that phase's graph was last reported.
+  reportedAt: utcIso8601,
+  // Present when work on this phase was reported with no approval of its scope in force.
+  builtWithoutApproval: z7.literal(true).optional()
+}).strict();
+var buildSnapshotReportSchema = z7.object({
+  // Which phase this graph belongs to.
+  phase: buildPhaseSchema,
+  // That phase's name in words, when the project gives it one.
+  phaseTitle: buildPhaseTitleSchema.optional(),
+  // The whole graph, every time. Reporting a change instead of the graph is the
+  // one thing this route does not accept.
+  tasks: buildTaskListSchema
+}).strict();
+var buildSnapshotReportResultSchema = z7.object({
+  // What happened. One outcome today; a refusal travels as the shared wire error.
+  outcome: z7.literal("recorded"),
+  // Which phase the graph was recorded against.
+  phase: buildPhaseSchema,
+  // When it was recorded.
+  reportedAt: utcIso8601
+}).strict();
+
+// ../events/dist/phase-plan.js
+import { z as z9 } from "zod";
+
+// ../events/dist/check-problems.js
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function dotted(path) {
+  return path.map((key) => String(key)).join(".");
+}
+function isMissingKey(raw, path) {
+  if (path.length === 0)
+    return false;
+  let parent = raw;
+  for (const key of path.slice(0, -1)) {
+    if (!isRecord(parent) && !Array.isArray(parent))
+      return false;
+    parent = parent[key];
+  }
+  return isRecord(parent) && !(String(path[path.length - 1]) in parent);
+}
+function shapeProblemsOf(schema, raw, undeclared) {
+  const parsed = schema.safeParse(raw);
+  if (parsed.success)
+    return [];
+  const problems = [];
+  for (const issue of parsed.error.issues) {
+    if (issue.code === "unrecognized_keys") {
+      for (const key of issue.keys) {
+        problems.push({ path: dotted([...issue.path, key]), message: undeclared });
+      }
+    } else if (isMissingKey(raw, issue.path)) {
+      problems.push({ path: dotted(issue.path), message: "is required" });
+    } else {
+      problems.push({ path: dotted(issue.path), message: issue.message });
+    }
+  }
+  return problems;
+}
+function shown(value) {
+  return looksLikeSecret(value) ? "a value that looks like a credential" : `"${value}"`;
+}
+
+// ../events/dist/system-description.js
+import { z as z8 } from "zod";
+var SYSTEM_DESCRIPTION_FORMAT = 1;
+var SYSTEM_PARTS_MAX = 60;
+var SYSTEM_CONNECTIONS_MAX = 400;
+var SYSTEM_SLOT_MAX = 11;
+var SYSTEM_OWNS_MAX = 20;
+var SYSTEM_OWNED_PATTERN_MAX = 200;
+var SYSTEM_PART_NAME_MAX = 60;
+var SYSTEM_PART_DESCRIPTION_MAX = 160;
+var SYSTEM_CONNECTION_LABEL_MAX = 60;
+var SYSTEM_PART_ID_PATTERN = /^[a-z][a-z0-9-]{0,39}$/;
+var SYSTEM_LANES = ["clients", "edge", "services", "data", "external"];
+var systemLaneSchema = z8.enum(SYSTEM_LANES, {
+  error: `must be one of ${SYSTEM_LANES.join(", ")}`
+});
+var SYSTEM_CONNECTION_KINDS = ["call", "event", "write", "external"];
+var systemConnectionKindSchema = z8.enum(SYSTEM_CONNECTION_KINDS, {
+  error: `must be one of ${SYSTEM_CONNECTION_KINDS.join(", ")}`
+});
+var LINE_SEPARATOR = /[\u2028\u2029]/;
+function descriptionText(max) {
+  return statementText(max).refine((v) => v.trim().length > 0, { message: "must not be empty or only spaces" }).refine((v) => !LINE_SEPARATOR.test(v), {
+    message: "must be one line: it holds a line or paragraph separator"
+  });
+}
+var systemPartIdSchema = z8.string().regex(SYSTEM_PART_ID_PATTERN, {
+  message: "must be a short id: a lowercase letter, then lowercase letters, digits or hyphens, 40 characters at most"
+}).refine((v) => !looksLikeSecret(v), { message: "looks like a password or key; choose another id" });
+function hasEmptySegment(pattern) {
+  return pattern.split("/").some((segment) => segment.length === 0);
+}
+function hasDotSegment(pattern) {
+  return pattern.split("/").some((segment) => segment === "." || segment === "..");
+}
+function hasPartialDoubleStar(pattern) {
+  return pattern.split("/").some((segment) => segment.includes("**") && segment !== "**");
+}
+var SEGMENT_CHARACTERS = /^[A-Za-z0-9._\-*]*$/;
+function hasForeignCharacter(pattern) {
+  return pattern.split("/").some((segment) => !SEGMENT_CHARACTERS.test(segment));
+}
+var systemOwnedPatternSchema = z8.string().max(SYSTEM_OWNED_PATTERN_MAX, { message: `must be at most ${SYSTEM_OWNED_PATTERN_MAX} characters` }).refine((v) => !hasEmptySegment(v), {
+  message: "must not start or end with a slash, or have two slashes together"
+}).refine((v) => !hasDotSegment(v), { message: 'must not have a "." or ".." folder in it' }).refine((v) => !hasPartialDoubleStar(v), { message: '"**" must stand alone between slashes' }).refine((v) => !hasForeignCharacter(v), {
+  message: 'may use only letters, digits, ".", "_", "-" and "*" between slashes'
+}).refine((v) => !looksLikeSecret(v), {
+  message: "this path looks like a credential; list a shorter folder above it"
+});
+var systemPartSchema = z8.object({
+  id: systemPartIdSchema,
+  name: descriptionText(SYSTEM_PART_NAME_MAX),
+  description: descriptionText(SYSTEM_PART_DESCRIPTION_MAX),
+  lane: systemLaneSchema,
+  slot: z8.number({ error: `must be a whole number from 0 to ${SYSTEM_SLOT_MAX}` }).int({ error: `must be a whole number from 0 to ${SYSTEM_SLOT_MAX}` }).min(0, { error: `must be a whole number from 0 to ${SYSTEM_SLOT_MAX}` }).max(SYSTEM_SLOT_MAX, { error: `must be a whole number from 0 to ${SYSTEM_SLOT_MAX}` }),
+  outside: z8.boolean(),
+  owns: z8.array(systemOwnedPatternSchema).max(SYSTEM_OWNS_MAX, { message: `can list at most ${SYSTEM_OWNS_MAX} paths` })
+}).strict();
+var systemConnectionSchema = z8.object({
+  from: systemPartIdSchema,
+  to: systemPartIdSchema,
+  kind: systemConnectionKindSchema,
+  label: descriptionText(SYSTEM_CONNECTION_LABEL_MAX)
+}).strict();
+var systemDescriptionSchema = z8.object({
+  format: z8.literal(SYSTEM_DESCRIPTION_FORMAT, { error: `must be ${SYSTEM_DESCRIPTION_FORMAT}` }),
+  parts: z8.array(systemPartSchema).min(1, { message: "must list at least one part" }).max(SYSTEM_PARTS_MAX, { message: `can hold at most ${SYSTEM_PARTS_MAX} parts (five lanes of twelve slots)` }),
+  connections: z8.array(systemConnectionSchema).max(SYSTEM_CONNECTIONS_MAX, { message: `can hold at most ${SYSTEM_CONNECTIONS_MAX} connections` })
+}).strict();
+var systemDescriptionProblemSchema = z8.object({
+  path: z8.string(),
+  message: z8.string()
+}).strict();
+function shapeProblems(raw) {
+  return shapeProblemsOf(systemDescriptionSchema, raw, "is not a field a description has");
+}
+function quoted(value) {
+  return typeof value === "string" ? shown(value) : "another part";
+}
+function crossFieldProblems(raw) {
+  const problems = [];
+  if (!isRecord(raw))
+    return problems;
+  const parts = Array.isArray(raw.parts) ? raw.parts : [];
+  const connections = Array.isArray(raw.connections) ? raw.connections : [];
+  const ids = /* @__PURE__ */ new Set();
+  const placed = /* @__PURE__ */ new Map();
+  const owners = /* @__PURE__ */ new Map();
+  parts.forEach((part, i) => {
+    if (!isRecord(part))
+      return;
+    if (typeof part.id === "string") {
+      if (ids.has(part.id)) {
+        problems.push({ path: `parts.${i}.id`, message: `another part already has the id ${shown(part.id)}` });
+      }
+      ids.add(part.id);
+    }
+    if (typeof part.lane === "string" && typeof part.slot === "number") {
+      const place = `${part.lane}\0${part.slot}`;
+      const earlier = placed.get(place);
+      if (earlier !== void 0) {
+        problems.push({
+          path: `parts.${i}.slot`,
+          message: `${quoted(parts[earlier].id)} already sits in lane ${shown(part.lane)} at slot ${part.slot}`
+        });
+      } else {
+        placed.set(place, i);
+      }
+    }
+    if (typeof part.outside === "boolean" && Array.isArray(part.owns)) {
+      if (part.outside && part.owns.length > 0) {
+        problems.push({ path: `parts.${i}.owns`, message: "must be empty for a part outside the repository" });
+      }
+      if (!part.outside && part.owns.length === 0) {
+        problems.push({ path: `parts.${i}.owns`, message: "must list at least one path this part owns" });
+      }
+    }
+    if (Array.isArray(part.owns)) {
+      part.owns.forEach((pattern, k) => {
+        if (typeof pattern !== "string")
+          return;
+        const owner = owners.get(pattern);
+        if (owner === void 0) {
+          owners.set(pattern, i);
+        } else if (owner === i) {
+          problems.push({ path: `parts.${i}.owns.${k}`, message: `${shown(pattern)} is listed twice in this part` });
+        } else {
+          problems.push({
+            path: `parts.${i}.owns.${k}`,
+            message: `${shown(pattern)} is already owned by ${quoted(parts[owner].id)}`
+          });
+        }
+      });
+    }
+  });
+  const pairs = /* @__PURE__ */ new Set();
+  connections.forEach((connection, i) => {
+    if (!isRecord(connection))
+      return;
+    const { from, to } = connection;
+    if (typeof from === "string" && !ids.has(from)) {
+      problems.push({ path: `connections.${i}.from`, message: `names no part: ${shown(from)}` });
+    }
+    if (typeof to === "string" && !ids.has(to)) {
+      problems.push({ path: `connections.${i}.to`, message: `names no part: ${shown(to)}` });
+    }
+    if (typeof from === "string" && typeof to === "string") {
+      if (from === to) {
+        problems.push({ path: `connections.${i}.to`, message: `must name a different part from "from" (${shown(from)})` });
+      }
+      const pair = `${from}\0${to}`;
+      if (pairs.has(pair)) {
+        problems.push({ path: `connections.${i}`, message: `another connection already goes from ${shown(from)} to ${shown(to)}` });
+      }
+      pairs.add(pair);
+    }
+  });
+  return problems;
+}
+function checkSystemDescription(value) {
+  const problems = [...shapeProblems(value), ...crossFieldProblems(value)];
+  if (problems.length > 0)
+    return { ok: false, problems };
+  return { ok: true, description: systemDescriptionSchema.parse(value) };
+}
+function segmentMatches(pattern, segment) {
+  const literals = pattern.split("*");
+  if (literals.length === 1)
+    return pattern === segment;
+  const first = literals[0];
+  const last = literals[literals.length - 1];
+  if (!segment.startsWith(first))
+    return false;
+  let position = first.length;
+  for (const literal of literals.slice(1, -1)) {
+    const found = segment.indexOf(literal, position + 1);
+    if (found === -1)
+      return false;
+    position = found + literal.length;
+  }
+  return segment.length - last.length >= position + 1 && segment.endsWith(last);
+}
+function patternOwns(pattern, path) {
+  const want = pattern.split("/");
+  const have = path.split("/");
+  const width = have.length + 1;
+  const seen = new Uint8Array((want.length + 1) * width);
+  const from = (i, j) => {
+    if (i === want.length)
+      return true;
+    const cell = i * width + j;
+    if (seen[cell] !== 0)
+      return seen[cell] === 2;
+    const segment = want[i];
+    const result = segment === "**" ? from(i + 1, j) || j < have.length && from(i, j + 1) : j < have.length && segmentMatches(segment, have[j]) && from(i + 1, j + 1);
+    seen[cell] = result ? 2 : 1;
+    return result;
+  };
+  return from(0, 0);
+}
+function specificity(pattern) {
+  const segments = pattern.split("/");
+  const firstWildcard = segments.findIndex((segment) => segment.includes("*"));
+  return {
+    leadingLiterals: firstWildcard === -1 ? segments.length : firstWildcard,
+    wildcards: segments.filter((segment) => segment.includes("*")).length,
+    literalCharacters: pattern.replace(/[*/]/g, "").length
+  };
+}
+function outranks(a, b) {
+  if (a.rank.leadingLiterals !== b.rank.leadingLiterals)
+    return b.rank.leadingLiterals - a.rank.leadingLiterals;
+  if (a.rank.wildcards !== b.rank.wildcards)
+    return a.rank.wildcards - b.rank.wildcards;
+  if (a.rank.literalCharacters !== b.rank.literalCharacters)
+    return b.rank.literalCharacters - a.rank.literalCharacters;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function ownerOf(path, description) {
+  let best = null;
+  for (const part of description.parts) {
+    for (const pattern of part.owns) {
+      if (!patternOwns(pattern, path))
+        continue;
+      const candidate = { id: part.id, rank: specificity(pattern) };
+      if (best === null || outranks(candidate, best) < 0)
+        best = candidate;
+    }
+  }
+  return best === null ? null : best.id;
+}
+var systemReportRecordedSchema = z8.object({
+  outcome: z8.literal("recorded"),
+  version: z8.number().int().min(1),
+  reportedAt: utcIso8601
+}).strict();
+var systemReportRefusedSchema = z8.object({
+  outcome: z8.literal("refused"),
+  problems: z8.array(systemDescriptionProblemSchema).min(1)
+}).strict();
+var systemReportUnavailableSchema = z8.object({
+  outcome: z8.literal("unavailable")
+}).strict();
+var systemReportResultSchema = z8.discriminatedUnion("outcome", [
+  systemReportRecordedSchema,
+  systemReportRefusedSchema,
+  systemReportUnavailableSchema
+]);
+var SYSTEM_DRAW_SVG_MAX_BYTES = 2 * 1024 * 1024;
+var SYSTEM_DRAW_MERMAID_MAX_BYTES = 256 * 1024;
+var SYSTEM_DRAW_PNG_MAX_BYTES = 8 * 1024 * 1024;
+var SYSTEM_DIAGRAM_MARKER_LINE = "<!-- drawn by Halfcycle from docs/system.json -->";
+var systemDrawArchitectureRequestSchema = z8.object({
+  picture: z8.literal("architecture"),
+  version: z8.number().int().min(1)
+}).strict();
+var systemDrawPhaseRequestSchema = z8.object({
+  picture: z8.literal("phase"),
+  phase: phaseIdentitySchema,
+  planVersion: z8.number().int().min(1)
+}).strict();
+var systemDrawRequestSchema = z8.discriminatedUnion("picture", [
+  systemDrawArchitectureRequestSchema,
+  systemDrawPhaseRequestSchema
+]);
+function utf8ByteLength2(text) {
+  let bytes = 0;
+  for (let i = 0; i < text.length; i++) {
+    const unit = text.charCodeAt(i);
+    if (unit < 128)
+      bytes += 1;
+    else if (unit < 2048)
+      bytes += 2;
+    else if (unit >= 55296 && unit <= 56319 && i + 1 < text.length) {
+      const next = text.charCodeAt(i + 1);
+      if (next >= 56320 && next <= 57343) {
+        bytes += 4;
+        i++;
+      } else {
+        bytes += 3;
+      }
+    } else
+      bytes += 3;
+  }
+  return bytes;
+}
+var BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+function base64DecodedLength(text) {
+  const padding = text.endsWith("==") ? 2 : text.endsWith("=") ? 1 : 0;
+  return text.length / 4 * 3 - padding;
+}
+var SYSTEM_PICTURE_THEMES = ["broadsheet", "flightdeck"];
+var systemPictureSchema = z8.object({
+  svg: z8.string().min(1).refine((v) => utf8ByteLength2(v) <= SYSTEM_DRAW_SVG_MAX_BYTES, { message: "the picture is larger than 2 MB" }),
+  png: z8.string().min(1).refine((v) => v.length % 4 === 0 && BASE64.test(v), { message: "the image is not valid base64" }).refine((v) => base64DecodedLength(v) <= SYSTEM_DRAW_PNG_MAX_BYTES, { message: "the image is larger than 8 MB" })
+}).strict();
+var systemPicturesSchema = /* @__PURE__ */ z8.object(Object.fromEntries(SYSTEM_PICTURE_THEMES.map((theme) => [theme, systemPictureSchema]))).strict();
+var systemDrawDrawnSchema = /* @__PURE__ */ z8.object({
+  outcome: z8.literal("drawn"),
+  mermaid: z8.string().min(1).refine((v) => utf8ByteLength2(v) <= SYSTEM_DRAW_MERMAID_MAX_BYTES, {
+    message: "the diagram text is larger than 256 KB"
+  }),
+  pictures: systemPicturesSchema
+}).strict();
+var systemDrawRefusedSchema = z8.object({
+  outcome: z8.literal("refused"),
+  reason: z8.string().min(1)
+}).strict();
+var systemDrawUnavailableSchema = z8.object({
+  outcome: z8.literal("unavailable")
+}).strict();
+var systemDrawResultSchema = /* @__PURE__ */ z8.discriminatedUnion("outcome", [
+  systemDrawDrawnSchema,
+  systemDrawRefusedSchema,
+  systemDrawUnavailableSchema
+]);
+
+// ../events/dist/phase-plan.js
+var PHASE_PLAN_FORMAT = 1;
+var PHASE_PLAN_CHANGES_MAX = 60;
+var PHASE_PLAN_SUMMARY_MAX = 160;
+var SCOPE_NOTE_MAX = 500;
+var PHASE_PLAN_PHASE_MAX = buildPhaseSchema.maxLength ?? 0;
+var PHASE_PLAN_CHANGE_KINDS = ["add", "change", "remove"];
+var phasePlanChangeSchema = z9.enum(PHASE_PLAN_CHANGE_KINDS, {
+  error: `must be one of ${PHASE_PLAN_CHANGE_KINDS.join(", ")}`
+});
+var phasePlanPhaseSchema = phaseIdentitySchema.refine((v) => !isValidPhaseIdentity(v) || buildPhaseSchema.safeParse(String(v)).success, { message: `must be at most ${PHASE_PLAN_PHASE_MAX} characters` });
+var phasePlanSummarySchema = descriptionText(PHASE_PLAN_SUMMARY_MAX);
+var phasePlanEntrySchema = z9.object({
+  part: systemPartIdSchema,
+  change: phasePlanChangeSchema,
+  summary: phasePlanSummarySchema
+}).strict();
+var phasePlanSchema = z9.object({
+  format: z9.literal(PHASE_PLAN_FORMAT, { error: `must be ${PHASE_PLAN_FORMAT}` }),
+  phase: phasePlanPhaseSchema,
+  changes: z9.array(phasePlanEntrySchema).min(1, { message: "must list at least one part" }).max(PHASE_PLAN_CHANGES_MAX, { message: `can list at most ${PHASE_PLAN_CHANGES_MAX} parts` })
+}).strict();
+function planCrossFieldProblems(raw, description) {
+  const problems = [];
+  if (!isRecord(raw) || !Array.isArray(raw.changes))
+    return problems;
+  const known = new Set(description.parts.map((p) => p.id));
+  const named = /* @__PURE__ */ new Map();
+  raw.changes.forEach((change, i) => {
+    if (!isRecord(change) || typeof change.part !== "string")
+      return;
+    if (!known.has(change.part)) {
+      problems.push({ path: `changes.${i}.part`, message: `names no part in the system description: ${shown(change.part)}` });
+    }
+    const earlier = named.get(change.part);
+    if (earlier === void 0) {
+      named.set(change.part, i);
+    } else {
+      problems.push({ path: `changes.${i}.part`, message: `${shown(change.part)} is already listed at changes.${earlier}` });
+    }
+  });
+  return problems;
+}
+function checkPhasePlan(value, description) {
+  const problems = [
+    ...shapeProblemsOf(phasePlanSchema, value, "is not a field a plan has"),
+    ...planCrossFieldProblems(value, description)
+  ];
+  if (problems.length > 0)
+    return { ok: false, problems };
+  return { ok: true, plan: phasePlanSchema.parse(value) };
+}
+var scopePhaseSchema = buildPhaseSchema.refine((v) => isValidPhaseIdentity(v), {
+  message: "must be a phase name"
+});
+var SCOPE_STATE_NAMES = [
+  "not-planned",
+  "waiting",
+  "sent-back",
+  "approved",
+  "partly-stale",
+  "withdrawn"
+];
+var scopeStateNameSchema = z9.enum(SCOPE_STATE_NAMES);
+var plannedScopeStateSchema = scopeStateNameSchema.exclude(["not-planned"]);
+var SCOPE_PART_STATUSES = ["approved", "waiting"];
+var scopePartStatusSchema = z9.enum(SCOPE_PART_STATUSES);
+var SCOPE_ACTS = ["approve", "send-back", "withdraw"];
+var scopeActSchema = z9.enum(SCOPE_ACTS);
+var SCOPE_GIVEN_IN = ["console", "chat"];
+var scopeGivenInSchema = z9.enum(SCOPE_GIVEN_IN);
+var scopeNoteSchema = descriptionText(SCOPE_NOTE_MAX);
+var scopeNoteWireSchema = z9.string().max(SCOPE_NOTE_MAX);
+var SCOPE_PART_VERDICTS = ["ok", "change"];
+var scopePartVerdictSchema = z9.enum(SCOPE_PART_VERDICTS);
+var scopeDecisionPartSchema = z9.object({
+  part: systemPartIdSchema,
+  verdict: scopePartVerdictSchema,
+  note: scopeNoteWireSchema.optional()
+}).strict();
+var planVersionSchema = z9.number().int().min(1);
+var phasePlanRequestSchema = z9.object({
+  descriptionVersion: z9.number().int().min(1),
+  plan: z9.unknown()
+}).strict();
+var phasePlanRecordedSchema = z9.object({
+  outcome: z9.literal("recorded"),
+  version: planVersionSchema,
+  phaseNumber: z9.number().int().min(1),
+  state: plannedScopeStateSchema,
+  changedParts: z9.array(systemPartIdSchema).max(PHASE_PLAN_CHANGES_MAX),
+  typedApprovalOffered: z9.boolean(),
+  reportedAt: utcIso8601
+}).strict();
+var phasePlanRefusedSchema = z9.object({
+  outcome: z9.literal("refused"),
+  problems: z9.array(systemDescriptionProblemSchema).min(1)
+}).strict();
+var phasePlanUnavailableSchema = z9.object({
+  outcome: z9.literal("unavailable")
+}).strict();
+var phasePlanResultSchema = z9.discriminatedUnion("outcome", [
+  phasePlanRecordedSchema,
+  phasePlanRefusedSchema,
+  phasePlanUnavailableSchema
+]);
+var scopeApproveRequestSchema = z9.object({
+  act: z9.literal("approve"),
+  planVersion: planVersionSchema,
+  parts: z9.array(scopeDecisionPartSchema).max(PHASE_PLAN_CHANGES_MAX)
+}).strict();
+var scopeSendBackRequestSchema = z9.object({
+  act: z9.literal("send-back"),
+  planVersion: planVersionSchema,
+  parts: z9.array(scopeDecisionPartSchema).max(PHASE_PLAN_CHANGES_MAX),
+  note: scopeNoteWireSchema.optional()
+}).strict();
+var scopeWithdrawRequestSchema = z9.object({
+  act: z9.literal("withdraw"),
+  planVersion: planVersionSchema
+}).strict();
+var scopeDecisionRequestSchema = z9.discriminatedUnion("act", [
+  scopeApproveRequestSchema,
+  scopeSendBackRequestSchema,
+  scopeWithdrawRequestSchema
+]);
+var scopeDecisionRecordedSchema = z9.object({
+  outcome: z9.literal("recorded"),
+  act: scopeActSchema,
+  phase: scopePhaseSchema,
+  planVersion: planVersionSchema,
+  state: plannedScopeStateSchema,
+  decidedAt: utcIso8601
+}).strict();
+var scopeDecisionAlreadyApprovedSchema = z9.object({
+  outcome: z9.literal("already-approved"),
+  replanNeeded: z9.boolean(),
+  reason: z9.string().min(1)
+}).strict();
+var scopeDecisionRefusedSchema = z9.object({
+  outcome: z9.literal("refused"),
+  problems: z9.array(systemDescriptionProblemSchema).min(1)
+}).strict();
+var scopeDecisionUnavailableSchema = z9.object({
+  outcome: z9.literal("unavailable")
+}).strict();
+function reasonOutcome(outcome) {
+  return z9.object({ outcome: z9.literal(outcome), reason: z9.string().min(1) }).strict();
+}
+var scopeDecisionResultSchema = z9.discriminatedUnion("outcome", [
+  scopeDecisionRecordedSchema,
+  scopeDecisionAlreadyApprovedSchema,
+  scopeDecisionRefusedSchema,
+  scopeDecisionUnavailableSchema,
+  reasonOutcome("not-owner"),
+  reasonOutcome("no-owner"),
+  reasonOutcome("plan-changed"),
+  reasonOutcome("nothing-to-withdraw"),
+  reasonOutcome("build-started")
+]);
+var scopeReadPartSchema = z9.object({
+  part: systemPartIdSchema,
+  name: systemPartSchema.shape.name,
+  change: phasePlanChangeSchema,
+  summary: phasePlanSummarySchema,
+  status: scopePartStatusSchema,
+  changed: z9.boolean()
+}).strict();
+var scopeReadDecisionSchema = z9.object({
+  act: scopeActSchema,
+  planVersion: planVersionSchema,
+  givenIn: scopeGivenInSchema,
+  at: utcIso8601,
+  parts: z9.array(scopeDecisionPartSchema).max(PHASE_PLAN_CHANGES_MAX),
+  note: scopeNoteWireSchema.optional()
+}).strict();
+var scopeReadNotPlannedSchema = z9.object({
+  phase: scopePhaseSchema,
+  state: z9.literal("not-planned"),
+  canDecide: z9.boolean()
+}).strict();
+var scopeReadPlannedSchema = z9.object({
+  phase: scopePhaseSchema,
+  state: plannedScopeStateSchema,
+  phaseNumber: z9.number().int().min(1),
+  planVersion: planVersionSchema,
+  parts: z9.array(scopeReadPartSchema).min(1).max(PHASE_PLAN_CHANGES_MAX),
+  decisions: z9.array(scopeReadDecisionSchema),
+  canDecide: z9.boolean(),
+  replanLine: z9.string().min(1).optional()
+}).strict();
+var scopeReadSchema = z9.union([scopeReadNotPlannedSchema, scopeReadPlannedSchema]);
+
+// ../events/dist/client-version.js
+var CHAT_APPROVAL_CLIENT_VERSION = "0.4.7";
+function clientMeetsChatApprovalFloor(version) {
+  return isReleaseVersion(version) && compareReleaseVersions(version, CHAT_APPROVAL_CLIENT_VERSION) >= 0;
+}
+var TYPED_APPROVAL_OFF_SENTENCE = "Approving by typing is switched off for now.";
+var CLIENT_UPDATE_SENTENCE = `To approve by typing in a session, Halfcycle needs updating: run \`${HALFCYCLE_COMMAND}\` in this project's folder, then reopen your session and ask again.`;
+
+// ../events/dist/device-auth.js
+import { z as z10 } from "zod";
+var utcIso86013 = z10.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/, "must be a UTC ISO-8601 timestamp ending in Z");
 var DEVICE_AUTH_STATUS = {
   /** The poll: minted, nobody has acted yet. Keep polling. 200. */
   PENDING: "pending",
@@ -1133,25 +1977,25 @@ var DEVICE_POLL_REFUSALS = [
   DEVICE_AUTH_STATUS.EXPIRED,
   DEVICE_AUTH_STATUS.UNKNOWN
 ];
-var deviceAuthStartResponseSchema = z7.object({
-  deviceCode: z7.string().min(1),
-  userCode: z7.string().min(1),
-  verificationUrl: z7.string().min(1),
+var deviceAuthStartResponseSchema = z10.object({
+  deviceCode: z10.string().min(1),
+  userCode: z10.string().min(1),
+  verificationUrl: z10.string().min(1),
   expiresAt: utcIso86013,
-  pollIntervalMs: z7.number().int().positive()
+  pollIntervalMs: z10.number().int().positive()
 }).strict();
-var devicePollPendingSchema = z7.object({
-  status: z7.literal(DEVICE_AUTH_STATUS.PENDING),
-  pollIntervalMs: z7.number().int().positive()
+var devicePollPendingSchema = z10.object({
+  status: z10.literal(DEVICE_AUTH_STATUS.PENDING),
+  pollIntervalMs: z10.number().int().positive()
 }).strict();
-var devicePollApprovedSchema = z7.object({
-  status: z7.literal(DEVICE_AUTH_STATUS.APPROVED),
-  accountId: z7.string().min(1),
-  credential: z7.string().min(1),
+var devicePollApprovedSchema = z10.object({
+  status: z10.literal(DEVICE_AUTH_STATUS.APPROVED),
+  accountId: z10.string().min(1),
+  credential: z10.string().min(1),
   expiresAt: utcIso86013
 }).strict();
-var deviceAuthRefusalSchema = z7.object({
-  status: z7.enum([
+var deviceAuthRefusalSchema = z10.object({
+  status: z10.enum([
     DEVICE_AUTH_STATUS.DECLINED,
     DEVICE_AUTH_STATUS.EXPIRED,
     DEVICE_AUTH_STATUS.UNKNOWN,
@@ -1162,25 +2006,25 @@ var deviceAuthRefusalSchema = z7.object({
     DEVICE_AUTH_STATUS.ALREADY_DECIDED,
     DEVICE_AUTH_STATUS.TERMS_REQUIRED
   ]),
-  message: z7.string().min(1)
+  message: z10.string().min(1)
 }).strict();
-var devicePollResponseSchema = z7.union([
+var devicePollResponseSchema = z10.union([
   devicePollPendingSchema,
   devicePollApprovedSchema,
   deviceAuthRefusalSchema
 ]);
-var deviceConfirmRequestSchema = z7.object({
-  userCode: z7.string().min(1),
-  decision: z7.enum(["approve", "decline"]),
-  externalAuthId: z7.string().min(1).optional(),
-  email: z7.string().optional(),
-  acceptTerms: z7.boolean().optional()
+var deviceConfirmRequestSchema = z10.object({
+  userCode: z10.string().min(1),
+  decision: z10.enum(["approve", "decline"]),
+  externalAuthId: z10.string().min(1).optional(),
+  email: z10.string().optional(),
+  acceptTerms: z10.boolean().optional()
 }).strict();
-var deviceConfirmRecordedSchema = z7.object({
-  status: z7.literal(DEVICE_AUTH_STATUS.RECORDED),
-  accountId: z7.string().min(1).optional()
+var deviceConfirmRecordedSchema = z10.object({
+  status: z10.literal(DEVICE_AUTH_STATUS.RECORDED),
+  accountId: z10.string().min(1).optional()
 }).strict();
-var deviceConfirmResponseSchema = z7.union([
+var deviceConfirmResponseSchema = z10.union([
   deviceConfirmRecordedSchema,
   deviceAuthRefusalSchema
 ]);
@@ -1209,45 +2053,45 @@ function loopbackVerificationUrl(verificationUrl, target) {
 }
 
 // ../events/dist/join-refusal.js
-import { z as z8 } from "zod";
+import { z as z11 } from "zod";
 var NOT_THIS_ACCOUNT_REASON = "not-this-account";
 var JOIN_REFUSAL_STATUS = 403;
-var notThisAccountRefusalSchema = z8.object({
-  statusCode: z8.literal(JOIN_REFUSAL_STATUS),
-  error: z8.string(),
-  message: z8.string(),
-  reason: z8.literal(NOT_THIS_ACCOUNT_REASON)
+var notThisAccountRefusalSchema = z11.object({
+  statusCode: z11.literal(JOIN_REFUSAL_STATUS),
+  error: z11.string(),
+  message: z11.string(),
+  reason: z11.literal(NOT_THIS_ACCOUNT_REASON)
 }).strict();
-var joinRefusalSchema = z8.union([notThisAccountRefusalSchema, wireErrorSchema]);
+var joinRefusalSchema = z11.union([notThisAccountRefusalSchema, wireErrorSchema]);
 function isNotThisAccountRefusal(body) {
   return typeof body === "object" && body !== null && body.reason === NOT_THIS_ACCOUNT_REASON;
 }
 
 // ../events/dist/account-identity.js
-import { z as z9 } from "zod";
-var accountIdentitySchema = z9.object({
-  accountId: z9.string().min(1),
-  email: z9.string().min(1).optional()
+import { z as z12 } from "zod";
+var accountIdentitySchema = z12.object({
+  accountId: z12.string().min(1),
+  email: z12.string().min(1).optional()
 }).strict();
 function safeParseAccountIdentity(payload) {
   return accountIdentitySchema.safeParse(payload);
 }
 
 // ../events/dist/credential-wire.js
-import { z as z10 } from "zod";
-var engagementCredentialResponseSchema = z10.object({
-  engagementId: z10.string(),
-  sessionToken: z10.string(),
-  mcpUrl: z10.string(),
-  guardUrl: z10.string(),
-  controlTelemetryUrl: z10.string(),
-  methodVersion: z10.string().optional(),
-  consoleUrl: z10.string().optional()
+import { z as z13 } from "zod";
+var engagementCredentialResponseSchema = z13.object({
+  engagementId: z13.string(),
+  sessionToken: z13.string(),
+  mcpUrl: z13.string(),
+  guardUrl: z13.string(),
+  controlTelemetryUrl: z13.string(),
+  methodVersion: z13.string().optional(),
+  consoleUrl: z13.string().optional()
 }).strict();
-var ciTokenExchangeResponseSchema = z10.object({
-  token: z10.string(),
+var ciTokenExchangeResponseSchema = z13.object({
+  token: z13.string(),
   expiresAt: utcIso8601,
-  engagementId: z10.string()
+  engagementId: z13.string()
 }).strict();
 var NO_CREDENTIAL_PLACEHOLDER = "halfcycle:no-credential";
 var NOT_THIS_ACCOUNT_PLACEHOLDER = "halfcycle:not-this-account";
@@ -1264,44 +2108,44 @@ var PLACEHOLDER_SENTENCES = Object.freeze({
 });
 
 // ../events/dist/project-engagement.js
-import { z as z11 } from "zod";
-var projectIdSchema = z11.string().uuid();
-var projectEngagementRequestSchema = z11.object({
-  derivedName: z11.string()
+import { z as z14 } from "zod";
+var projectIdSchema = z14.string().uuid();
+var projectEngagementRequestSchema = z14.object({
+  derivedName: z14.string()
 }).strict();
 
 // ../events/dist/phase-record.js
-import { z as z12 } from "zod";
-var phaseRecordRefusalReasonSchema = z12.enum([
+import { z as z15 } from "zod";
+var phaseRecordRefusalReasonSchema = z15.enum([
   "still-open",
   "reopened",
   "never-opened",
   "never-closed",
   "closed-before-records"
 ]);
-var phaseRecordRecordSchema = z12.object({
-  outcome: z12.literal("record"),
+var phaseRecordRecordSchema = z15.object({
+  outcome: z15.literal("record"),
   phase: phaseNameSchema,
   record: buildRecordV2Schema
 }).strict().refine((body) => body.record.phase === body.phase, {
   message: "the record is for a different phase than the one asked for",
   path: ["record", "phase"]
 });
-var phaseRecordWithheldSchema = z12.object({
-  outcome: z12.literal("withheld"),
+var phaseRecordWithheldSchema = z15.object({
+  outcome: z15.literal("withheld"),
   phase: phaseNameSchema,
-  sequence: z12.number().int().min(1),
+  sequence: z15.number().int().min(1),
   closedAt: utcIso8601,
-  message: z12.string()
+  message: z15.string()
 }).strict();
 var phaseRecordRefusedSchema = wireErrorSchema.extend({
-  outcome: z12.literal("refused"),
+  outcome: z15.literal("refused"),
   phase: phaseNameSchema,
-  statusCode: z12.literal(409),
-  error: z12.literal("PhaseRecordRefused"),
+  statusCode: z15.literal(409),
+  error: z15.literal("PhaseRecordRefused"),
   reason: phaseRecordRefusalReasonSchema
 }).strict();
-var phaseRecordResponseSchema = z12.discriminatedUnion("outcome", [
+var phaseRecordResponseSchema = z15.discriminatedUnion("outcome", [
   phaseRecordRecordSchema,
   phaseRecordWithheldSchema,
   phaseRecordRefusedSchema
@@ -1375,8 +2219,8 @@ var ENV_FILENAME = ENGAGEMENT_ENV_FILENAME;
 var HALFCYCLE_DIR = HALFCYCLE_DIR_NAME;
 var InvalidEngagementIdError = class extends Error {
   constructor(engagementId) {
-    const shown = JSON.stringify(engagementId.length > 80 ? `${engagementId.slice(0, 80)}\u2026` : engagementId);
-    super(`${shown} is not a Halfcycle project id, so it cannot name a folder on this machine and nothing was written. A project id looks like 3f2a1c4e-8b7d-4e2f-9a61-0c5d7e8f9b10. If it is the "${PIN_ENGAGEMENT_ID_FIELD}" in .halfcycle/bundle.json, delete that file and run "npx halfcycle" again: this repository is then set up as a new Halfcycle project.`);
+    const shown2 = JSON.stringify(engagementId.length > 80 ? `${engagementId.slice(0, 80)}\u2026` : engagementId);
+    super(`${shown2} is not a Halfcycle project id, so it cannot name a folder on this machine and nothing was written. A project id looks like 3f2a1c4e-8b7d-4e2f-9a61-0c5d7e8f9b10. If it is the "${PIN_ENGAGEMENT_ID_FIELD}" in .halfcycle/bundle.json, delete that file and run "npx halfcycle" again: this repository is then set up as a new Halfcycle project.`);
     this.name = "InvalidEngagementIdError";
   }
 };
@@ -1662,17 +2506,17 @@ function fileSha256(bytes) {
   const text = typeof bytes === "string" ? bytes : Buffer2.from(bytes).toString("utf-8");
   return sha256Hex(text.split("\n").map(lineKey).join("\n"));
 }
-function canonicalJson(value) {
+function canonicalJson2(value) {
   if (Array.isArray(value))
-    return value.map(canonicalJson);
+    return value.map(canonicalJson2);
   if (value !== null && typeof value === "object") {
-    const entries = Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => [k, canonicalJson(v)]);
+    const entries = Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => [k, canonicalJson2(v)]);
     return Object.fromEntries(entries);
   }
   return value;
 }
 function canonicalSha256(value) {
-  return sha256Hex(JSON.stringify(canonicalJson(value)));
+  return sha256Hex(JSON.stringify(canonicalJson2(value)));
 }
 function byString(a, b) {
   return a < b ? -1 : a > b ? 1 : 0;
@@ -1691,7 +2535,7 @@ function serializeManifest(manifest) {
     leftAlone: [...manifest.leftAlone].sort(byString),
     settings
   };
-  return JSON.stringify(canonicalJson(ordered), null, 2) + "\n";
+  return JSON.stringify(canonicalJson2(ordered), null, 2) + "\n";
 }
 var UnreadableManifestError = class extends Error {
   constructor(reason) {
@@ -1700,7 +2544,7 @@ var UnreadableManifestError = class extends Error {
   }
 };
 var HEX64 = /^[0-9a-f]{64}$/;
-function isRecord(value) {
+function isRecord2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function stringArray(value, field) {
@@ -1721,7 +2565,7 @@ function bool(value, field) {
   return value;
 }
 function appendedTextRecord(value, field) {
-  if (!isRecord(value))
+  if (!isRecord2(value))
     throw new UnreadableManifestError(`"${field}" is not an object`);
   onlyKeys(value, ["created", "appended"], `"${field}"`);
   return {
@@ -1741,7 +2585,7 @@ function parseManifest(text) {
   } catch {
     throw new UnreadableManifestError("it is not valid JSON");
   }
-  if (!isRecord(raw))
+  if (!isRecord2(raw))
     throw new UnreadableManifestError("it is not a JSON object");
   onlyKeys(raw, ["format", "files", "createdDirs", "leftAlone", "settings", "mcp", "gitignore", "gitattributes"], "the manifest");
   if (raw["format"] !== INSTALL_MANIFEST_FORMAT) {
@@ -1750,7 +2594,7 @@ function parseManifest(text) {
   if (!Array.isArray(raw["files"]))
     throw new UnreadableManifestError('"files" is not a list');
   const files = raw["files"].map((entry) => {
-    if (!isRecord(entry) || typeof entry["path"] !== "string") {
+    if (!isRecord2(entry) || typeof entry["path"] !== "string") {
       throw new UnreadableManifestError('a "files" entry has no path');
     }
     if (entry["perMachine"] === true) {
@@ -1764,7 +2608,7 @@ function parseManifest(text) {
     return { path: entry["path"], sha256: entry["sha256"] };
   });
   const s = raw["settings"];
-  if (!isRecord(s))
+  if (!isRecord2(s))
     throw new UnreadableManifestError('"settings" is missing');
   onlyKeys(s, [
     "created",
@@ -1791,7 +2635,7 @@ function parseManifest(text) {
   let mcp;
   if (raw["mcp"] !== void 0) {
     const m = raw["mcp"];
-    if (!isRecord(m))
+    if (!isRecord2(m))
       throw new UnreadableManifestError('"mcp" is not an object');
     onlyKeys(m, ["created", "adopted", "mcpServersCreated", "entrySha256"], '"mcp"');
     if (m["entrySha256"] !== void 0 && (typeof m["entrySha256"] !== "string" || !HEX64.test(m["entrySha256"]))) {
@@ -2097,6 +2941,8 @@ var WRITE_ALLOWLIST = [
   BUNDLE_PIN_REL,
   ".halfcycle/bin",
   "docs/build-records",
+  // Architecture pictures the draw command writes from Halfcycle's answer. The installer never writes here; keep the entry so this path stays declared as one Halfcycle writes.
+  "docs/diagrams",
   "test/fixtures/captured",
   MCP_REGISTRATION_REL,
   ".gitattributes",
@@ -2195,7 +3041,7 @@ function recordSettingsMerge(draft, existing, generated, preexisted) {
   const generatedHooks = generated.hooks ?? {};
   const hookCommands = Object.values(generatedHooks).flatMap((entries) => entries.flatMap((entry) => entry.hooks.map((h) => h.command)));
   const ours = /* @__PURE__ */ new Set([...hookCommands, ...HALFCYCLE_HOOK_COMMANDS]);
-  const existingHooks = isPlainObject(existing.hooks) ? existing.hooks : void 0;
+  const existingHooks = isPlainObject2(existing.hooks) ? existing.hooks : void 0;
   const heldOurs = Object.values(existingHooks ?? {}).some((entries) => Array.isArray(entries) && entries.some((entry) => isHalfcycleEntry(entry, ours)));
   const existingDeny = Array.isArray(existing.permissions?.deny) ? existing.permissions.deny : [];
   const schemaChanged = generated.$schema !== void 0 && existing.$schema !== generated.$schema;
@@ -2213,12 +3059,12 @@ function recordSettingsMerge(draft, existing, generated, preexisted) {
 }
 function recordMcpMerge(draft, existingText, writtenText) {
   const before = existingText === null ? void 0 : JSON.parse(existingText);
-  const servers = isPlainObject(before) ? before["mcpServers"] : void 0;
+  const servers = isPlainObject2(before) ? before["mcpServers"] : void 0;
   const written = JSON.parse(writtenText);
   recordMcp(draft, {
     created: existingText === null,
-    adopted: draft.previous === null && isPlainObject(servers) && MCP_SERVER_KEY in servers,
-    mcpServersCreated: !(isPlainObject(before) && "mcpServers" in before),
+    adopted: draft.previous === null && isPlainObject2(servers) && MCP_SERVER_KEY in servers,
+    mcpServersCreated: !(isPlainObject2(before) && "mcpServers" in before),
     entrySha256: canonicalSha256(written.mcpServers[MCP_SERVER_KEY])
   });
 }
@@ -2231,8 +3077,8 @@ function recordMcpAdoptionOnly(draft, existingText) {
   } catch {
     return;
   }
-  const servers = isPlainObject(before) ? before["mcpServers"] : void 0;
-  if (!isPlainObject(servers) || !(MCP_SERVER_KEY in servers))
+  const servers = isPlainObject2(before) ? before["mcpServers"] : void 0;
+  if (!isPlainObject2(servers) || !(MCP_SERVER_KEY in servers))
     return;
   recordMcp(draft, { created: false, adopted: true, mcpServersCreated: false });
 }
@@ -2317,7 +3163,7 @@ function readFileOrNull(path) {
     return null;
   }
 }
-function isPlainObject(value) {
+function isPlainObject2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function readPluginManifest() {
@@ -2665,6 +3511,54 @@ printf '%s\\n' '${USER_PROMPT_REMINDER_SENTENCE}'
 exit 0
 `;
 }
+var GENERATED_USER_PROMPT_SCOPE_HEADER = "# Typed scope approval \u2014 generated by";
+function generateUserPromptScopeHook() {
+  return `#!/usr/bin/env bash
+${GENERATED_USER_PROMPT_SCOPE_HEADER} the Halfcycle installer.
+#
+# Lets the owner of this project approve a phase's scope, or send it back, by
+# typing "approve <phase>" or "send back <phase>: <note>" as the whole prompt in
+# their own Claude Code session.
+#
+# AN ORDINARY PROMPT STARTS NOTHING. This script reads the hook input once and
+# looks only at the start of the prompt's value. Unless the prompt begins, after
+# any whitespace (typed, or escaped in the input), with "approve " or
+# "send back " in any case, it exits 0 with no output, and Node never starts.
+# A quote inside any other field arrives escaped, so no other field (the folder
+# the session is in, for one) can read as the start of the prompt.
+#
+# Otherwise it finds the project root from its own location, never from the
+# folder the session has moved to, and hands the same input to the guard
+# wrapper beside it. That decides whether the line counts and prints at most
+# one plain line. Nothing here ever blocks a prompt.
+#
+# FAILS OPEN up to that hand-over: any error before it exits 0 with no output.
+# After it, the wrapper's own exit stands.
+trap 'exit 0' ERR
+set -e
+
+# Read with the shell's own builtin, so the check below is the only program an
+# ordinary prompt starts.
+HC_INPUT=""
+IFS= read -r -d '' HC_INPUT || true
+
+# What may come before the phrase: whitespace as typed, as a short escape, as a
+# \\u escape, or as the UTF-8 bytes of a Unicode space. Compared byte for byte.
+HC_LEAD='[[:space:]]|\\\\[nrtf]|\\\\u(000[9a-d]|0020|00a0|1680|200[0-9a]|202[89f]|205f|3000|feff)'
+HC_LEAD="$HC_LEAD|"$'\\xc2\\xa0|\\xe1\\x9a\\x80|\\xe2\\x80[\\x80-\\x8a\\xa8\\xa9\\xaf]|\\xe2\\x81\\x9f|\\xe3\\x80\\x80|\\xef\\xbb\\xbf'
+if ! printf '%s' "$HC_INPUT" | LC_ALL=C grep -Eiq "\\"prompt\\"[[:space:]]*:[[:space:]]*\\"($HC_LEAD)*(approve|send back) "; then
+  exit 0
+fi
+
+HC_SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+HC_PROJECT_ROOT=$(CDPATH= cd -- "$HC_SCRIPT_DIR/../.." && pwd)
+export CLAUDE_PROJECT_DIR="$HC_PROJECT_ROOT"
+
+trap - ERR
+set +e
+exec bash "$HC_PROJECT_ROOT/.claude/hooks/guard-runner.sh" hook user-prompt-submit <<<"$HC_INPUT"
+`;
+}
 var CI_STANZA_KNOWN_HEADER_HASHES = [
   "b225800b2d699811f32ac213238cbf81c35b5e6a74114bdf55e39cd9d7e2928f",
   "674181735460f051af7c157222cf851fc3000fb3b8af3a10ea0bde9fe5eaba1f",
@@ -2740,6 +3634,7 @@ function removeRetiredMcpHeadersHelper(targetRepo) {
 var OWNED_GENERATED_HEADERS = {
   ".claude/hooks/guard-runner.sh": GENERATED_GUARD_RUNNER_HEADER,
   ".claude/hooks/user-prompt-reminder.sh": GENERATED_USER_PROMPT_REMINDER_HEADER,
+  ".claude/hooks/user-prompt-scope.sh": GENERATED_USER_PROMPT_SCOPE_HEADER,
   ".claude/hooks/session-end-marker.sh": GENERATED_SESSION_END_HEADER,
   ".claude/hooks/session-start-marker.sh": GENERATED_SESSION_START_HEADER
 };
@@ -2748,6 +3643,7 @@ function hookScriptsThisVersionWrites() {
     [".claude/hooks/guard-runner.sh", generateGuardRunnerWrapper()],
     [".claude/hooks/session-end-marker.sh", generateSessionEndMarker()],
     [".claude/hooks/user-prompt-reminder.sh", generateUserPromptReminderHook()],
+    [".claude/hooks/user-prompt-scope.sh", generateUserPromptScopeHook()],
     [".claude/hooks/session-start-marker.sh", generateSessionStartMarker()]
   ];
 }
@@ -2892,6 +3788,25 @@ function writeBundlePin(targetRepoRoot, version, engagementId, engagementType, c
   const pinText = inLineEndingOf(readFileOrNull(pinPath), JSON.stringify(pin, null, 2) + "\n");
   writeAllowlisted(pinPath, targetRepoRoot, pinText, writtenPaths);
 }
+function updatePinnedMethodVersion(repoRoot, engagementId, version) {
+  let pin;
+  try {
+    pin = readBundlePin(repoRoot);
+  } catch {
+    return;
+  }
+  if (pin === null || pin.engagementId !== engagementId)
+    return;
+  const pinPath = join5(repoRoot, BUNDLE_PIN_REL);
+  const updated = { ...pin, methodVersion: version };
+  const pinText = inLineEndingOf(readFileOrNull(pinPath), JSON.stringify(updated, null, 2) + "\n");
+  try {
+    writeAllowlisted(pinPath, repoRoot, pinText, []);
+  } catch {
+    process.stderr.write(`[halfcycle] Could not update ${BUNDLE_PIN_REL} with the new method version.
+`);
+  }
+}
 function writeCrewRoster(targetRepoRoot, report) {
   const doc = {
     $comment: "GENERATED by the Halfcycle installer \u2014 do not edit by hand. Re-run the installer to pick up a roster change.",
@@ -3324,14 +4239,14 @@ async function bindLoopback(env = process.env, engagementId) {
     else
       pending = callback;
   }, engagementId));
-  const bindProblem = await new Promise((resolve4) => {
+  const bindProblem = await new Promise((resolve5) => {
     const onError = (err) => {
-      resolve4(`${err.code ?? "bind failed"} on ${LOOPBACK_REDIRECT_HOST}:${wanted.port}`);
+      resolve5(`${err.code ?? "bind failed"} on ${LOOPBACK_REDIRECT_HOST}:${wanted.port}`);
     };
     server.once("error", onError);
     server.listen({ host: LOOPBACK_REDIRECT_HOST, port: wanted.port }, () => {
       server.removeListener("error", onError);
-      resolve4(null);
+      resolve5(null);
     });
   });
   if (bindProblem !== null) {
@@ -3347,9 +4262,9 @@ async function bindLoopback(env = process.env, engagementId) {
     bound: true,
     target: { port: address.port, state },
     boundAddress: address.address,
-    waitForCallback: ({ timeoutMs, onStillWaiting, stillWaitingMs = DEFAULT_STILL_WAITING_MS }) => new Promise((resolve4) => {
+    waitForCallback: ({ timeoutMs, onStillWaiting, stillWaitingMs = DEFAULT_STILL_WAITING_MS }) => new Promise((resolve5) => {
       if (pending !== null) {
-        resolve4(pending);
+        resolve5(pending);
         return;
       }
       const startedAt = Date.now();
@@ -3360,7 +4275,7 @@ async function bindLoopback(env = process.env, engagementId) {
         clearTimeout(timer);
         deliver = null;
         abandon = null;
-        resolve4(value);
+        resolve5(value);
       };
       const timer = setTimeout(() => finish(null), Math.max(0, timeoutMs));
       deliver = finish;
@@ -3374,9 +4289,9 @@ async function bindLoopback(env = process.env, engagementId) {
   };
 }
 function closeServer(server) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     server.closeAllConnections();
-    server.close(() => resolve4());
+    server.close(() => resolve5());
   });
 }
 
@@ -3399,7 +4314,7 @@ function defaultWrite(text) {
   process.stdout.write(text);
 }
 function defaultSleep(ms) {
-  return new Promise((resolve4) => setTimeout(resolve4, ms));
+  return new Promise((resolve5) => setTimeout(resolve5, ms));
 }
 function browserOpenCommand(os, url) {
   if (os === "darwin")
@@ -3446,12 +4361,12 @@ async function openBrowser(url, env = process.env, os = platform3(), spawnImpl =
     };
   }
   const { command, args: args2, windowsVerbatimArguments } = browserOpenCommand(os, url);
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     let child;
     try {
       child = spawnImpl(command, args2, { stdio: "ignore", env, windowsVerbatimArguments });
     } catch {
-      resolve4({ opened: false, reason: `${command} could not be run` });
+      resolve5({ opened: false, reason: `${command} could not be run` });
       return;
     }
     let settled = false;
@@ -3460,7 +4375,7 @@ async function openBrowser(url, env = process.env, os = platform3(), spawnImpl =
         return;
       settled = true;
       clearTimeout(timer);
-      resolve4(attempt);
+      resolve5(attempt);
     };
     const timer = setTimeout(() => {
       child.unref();
@@ -3605,17 +4520,17 @@ async function pollBesideLoopback(serviceUrl, started, wake, deps) {
       continue;
     }
     if (sleep === void 0) {
-      await new Promise((resolve4) => {
-        const timer = setTimeout(resolve4, started.pollIntervalMs);
+      await new Promise((resolve5) => {
+        const timer = setTimeout(resolve5, started.pollIntervalMs);
         interrupt = () => {
           clearTimeout(timer);
-          resolve4();
+          resolve5();
         };
       });
     } else {
-      await new Promise((resolve4) => {
-        interrupt = resolve4;
-        void sleep(started.pollIntervalMs).then(resolve4);
+      await new Promise((resolve5) => {
+        interrupt = resolve5;
+        void sleep(started.pollIntervalMs).then(resolve5);
       });
     }
     interrupt = null;
@@ -4237,9 +5152,9 @@ function wrongAccountVisibility(act) {
 async function askLine(question2) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    return await new Promise((resolve4) => {
-      rl.once("close", () => resolve4(""));
-      rl.question(question2).then(resolve4, () => resolve4(""));
+    return await new Promise((resolve5) => {
+      rl.once("close", () => resolve5(""));
+      rl.question(question2).then(resolve5, () => resolve5(""));
     });
   } finally {
     rl.close();
@@ -4506,10 +5421,10 @@ var SYSTEM_FOLDERS = [
   "C:\\Program Files",
   "C:\\Program Files (x86)"
 ];
-function refuseSystemFolder(targetRepo, platform4 = process.platform) {
+function refuseSystemFolder(targetRepo, platform5 = process.platform) {
   const key = (folder) => {
     const real = realOrLiteral(folder);
-    return platform4 === "win32" ? real.toLowerCase() : real;
+    return platform5 === "win32" ? real.toLowerCase() : real;
   };
   const target = key(targetRepo);
   if (SYSTEM_FOLDERS.some((folder) => key(folder) === target)) {
@@ -4642,11 +5557,11 @@ import { execFileSync as execFileSync3 } from "node:child_process";
 import { existsSync as existsSync5, realpathSync as realpathSync2 } from "node:fs";
 import { delimiter as delimiter2, join as join7 } from "node:path";
 function probeClaudeCodeVersion(timeoutMs, deps = {}) {
-  const platform4 = deps.platform ?? process.platform;
+  const platform5 = deps.platform ?? process.platform;
   const exec = deps.exec ?? execFileSync3;
   let raw;
   try {
-    raw = platform4 === "win32" ? exec("cmd.exe", ["/d", "/s", "/c", '"claude --version"'], {
+    raw = platform5 === "win32" ? exec("cmd.exe", ["/d", "/s", "/c", '"claude --version"'], {
       encoding: "utf-8",
       timeout: timeoutMs,
       stdio: ["ignore", "pipe", "ignore"],
@@ -4676,7 +5591,7 @@ var INSTALL_METHOD_RULES = [
 ];
 function probeClaudeCodeInstallMethod(deps = {}) {
   const env = deps.env ?? process.env;
-  const platform4 = deps.platform ?? process.platform;
+  const platform5 = deps.platform ?? process.platform;
   const exists = deps.exists ?? existsSync5;
   const realpath = deps.realpath ?? ((file) => {
     try {
@@ -4685,7 +5600,7 @@ function probeClaudeCodeInstallMethod(deps = {}) {
       return file;
     }
   });
-  const names = platform4 === "win32" ? ["claude.exe", "claude.cmd"] : ["claude"];
+  const names = platform5 === "win32" ? ["claude.exe", "claude.cmd"] : ["claude"];
   const dirs = (env["PATH"] ?? "").split(delimiter2).filter((dir) => dir !== "");
   for (const dir of dirs) {
     for (const name of names) {
@@ -5068,7 +5983,7 @@ function renderBuildRecordV2Markdown(record2) {
     `Phase: ${phase} (the name the client gave it)`,
     OBSERVED_LABEL,
     [
-      `- Method version: ${p.text(record2.observed.methodVersion)}. The Halfcycle method is updated from time to time, and each update has its own version number. This is the one the project was run under; it does not change during a project.`,
+      `- Method version: ${p.text(record2.observed.methodVersion)}. The Halfcycle method is updated from time to time, and each update has its own version number. This is the one the phase was run under. A project moves to a newer version only between phases.`,
       `- Project identifier: ${p.text(record2.observed.engagementId)}. Halfcycle keeps this project's records under this identifier.`,
       `- Record format: ${p.text(record2.format)}. This names the layout this file and the .json file beside it follow, for software that reads them.`
     ].join("\n"),
@@ -5098,10 +6013,14 @@ function assertInsideOutDir(outDir, candidate, identity) {
     throw new InvalidPhaseIdentityError(identity, BUILD_RECORD_DIR);
   }
 }
-function createExclusiveOnDisk(path, text) {
+function createExclusiveOnDisk(path, data) {
+  const bytes = typeof data === "string" ? Buffer.from(data, "utf-8") : data;
   const fd = openSync(path, "wx");
   try {
-    writeSync(fd, text);
+    let written = 0;
+    while (written < bytes.length) {
+      written += writeSync(fd, bytes, written, bytes.length - written);
+    }
   } catch (err) {
     closeSync(fd);
     rmSync3(path, { force: true });
@@ -5218,6 +6137,22 @@ function replaceOne(io, tmp, finalPath, text) {
 
 // dist/build-record/obtain.js
 import { relative as relative3 } from "node:path";
+
+// dist/missing-route.js
+var MESSAGE = {
+  GET: /^Route GET .* not found\.$/s,
+  POST: /^Route POST .* not found\.$/s
+};
+function isMissingRoute(method, status, body) {
+  if (status !== 404 || typeof body !== "object" || body === null)
+    return false;
+  const { error, message } = body;
+  if (error !== "Not Found" || typeof message !== "string")
+    return false;
+  return MESSAGE[method].test(message);
+}
+
+// dist/build-record/obtain.js
 var REFUSAL_FOLLOW_UP = {
   "still-open": "Nothing was written. The record is produced when the phase closes.",
   "reopened": "Nothing was written. A new record is produced when the phase closes again.",
@@ -5229,12 +6164,6 @@ var REFUSAL_REASONS = phaseRecordRefusalReasonSchema.options;
 function buildRecordUrl(credential, phase) {
   return `${credential.serviceUrl}/engagements/${encodeURIComponent(credential.engagementId)}/phases/${encodeURIComponent(phase)}/build-record`;
 }
-function isMissingRoute(status, body) {
-  if (status !== 404 || typeof body !== "object" || body === null)
-    return false;
-  const { error, message } = body;
-  return error === "Not Found" && typeof message === "string" && /^Route GET .* not found\.$/s.test(message);
-}
 async function obtainBuildRecord(credential, repoRoot, phase, io = NODE_RECORD_PAIR_IO) {
   const url = buildRecordUrl(credential, phase);
   let res;
@@ -5291,7 +6220,7 @@ async function obtainBuildRecord(credential, repoRoot, phase, io = NODE_RECORD_P
       headline: latestCloseHeadline(answer.record)
     };
   }
-  if (isMissingRoute(res.status, raw)) {
+  if (isMissingRoute("GET", res.status, raw)) {
     return { kind: "unavailable", why: "this Halfcycle service does not provide Build Records yet." };
   }
   const message = typeof raw === "object" && raw !== null && typeof raw.message === "string" ? raw.message : null;
@@ -5313,6 +6242,10 @@ function refetchCommand(phase) {
 // dist/open-phase.js
 import { readFileSync as readFileSync8 } from "node:fs";
 import { join as join9 } from "node:path";
+function readMethodUpdate(value) {
+  const parsed = methodUpdateSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
 function describeOpen(opened) {
   const { phase, previousPhase } = opened;
   if (previousPhase === phase) {
@@ -5422,13 +6355,18 @@ async function openPhase(credential, phase, entry, home) {
     phase: body.phase,
     previousPhase: body.previousPhase,
     stampFailure,
-    decision: body.decision
+    decision: body.decision,
+    methodUpdated: readMethodUpdate(body.methodUpdated)
   };
 }
 
 // dist/close-phase.js
 import { execFileSync as execFileSync4 } from "node:child_process";
 var NO_STATEMENTS = { thesis: null, outcome: null, deviations: [] };
+function readMethodUpdate2(value) {
+  const parsed = methodUpdateSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
 function readCloseCommit(repoRoot) {
   if (repoRoot === void 0) {
     return {
@@ -5517,7 +6455,13 @@ async function closePhase(credential, phase, outcome, close, home, repoRoot, sta
     throw new Error(`[halfcycle] The response from ${url} did not carry { engagementId, status }. The phase may or may not have closed \u2014 read the engagement's status before retrying.`);
   }
   const stampFailure = writePhaseStamp(credential.engagementId, null, home);
-  return { engagementId: answer.engagementId, status: answer.status, stampFailure, closeCommit };
+  return {
+    engagementId: answer.engagementId,
+    status: answer.status,
+    stampFailure,
+    closeCommit,
+    methodUpdated: readMethodUpdate2(answer.methodUpdated)
+  };
 }
 function describeIssuePath(path) {
   const [head, field] = path;
@@ -5532,12 +6476,1119 @@ function describeIssuePath(path) {
   return path.map(String).join(".") || "(the close)";
 }
 
+// dist/system-report.js
+import { execFileSync as execFileSync5 } from "node:child_process";
+import { readFileSync as readFileSync9 } from "node:fs";
+import { join as join10 } from "node:path";
+var SYSTEM_DESCRIPTION_REL = "docs/system.json";
+function readDescriptionFile(repoRoot) {
+  let text;
+  try {
+    text = readFileSync9(join10(repoRoot, SYSTEM_DESCRIPTION_REL), "utf-8");
+  } catch (err) {
+    const code = err.code;
+    return code === "ENOENT" || code === "ENOTDIR" ? { kind: "missing" } : { kind: "unreadable" };
+  }
+  try {
+    return { kind: "read", value: JSON.parse(text) };
+  } catch (err) {
+    return { kind: "not-json", error: err instanceof Error ? err.message : String(err) };
+  }
+}
+function problemPlace(raw, path) {
+  if (path === "")
+    return SYSTEM_DESCRIPTION_REL;
+  const [list, index] = path.split(".");
+  const position = Number(index);
+  if (!Number.isInteger(position) || position < 0)
+    return path;
+  const items = typeof raw === "object" && raw !== null ? raw[list ?? ""] : void 0;
+  const item = Array.isArray(items) ? items[position] : void 0;
+  const fields = typeof item === "object" && item !== null ? item : {};
+  if (list === "parts") {
+    const id = fields["id"];
+    return typeof id === "string" && id !== "" ? `${path} (part "${id}")` : `${path} (part ${position + 1})`;
+  }
+  if (list === "connections") {
+    const from = fields["from"];
+    const to = fields["to"];
+    return typeof from === "string" && typeof to === "string" ? `${path} (connection "${from}" to "${to}")` : `${path} (connection ${position + 1})`;
+  }
+  return path;
+}
+function problemLines(raw, problems) {
+  return problems.map((p) => `  ${problemPlace(raw, p.path)}: ${p.message}
+`).join("");
+}
+var listTrackedFiles = (repoRoot) => {
+  try {
+    const out = execFileSync5("git", ["-C", repoRoot, "ls-files", "-z"], {
+      encoding: "utf-8",
+      env: gitEnvForNamedRepo(),
+      stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 256 * 1024 * 1024
+    });
+    return out.split("\0").filter((p) => p !== "");
+  } catch {
+    return null;
+  }
+};
+function unownedPatterns(description, tracked) {
+  if (tracked === null)
+    return null;
+  const found = [];
+  for (const part of description.parts) {
+    for (const pattern of part.owns) {
+      const alone = {
+        format: description.format,
+        parts: [{ ...part, owns: [pattern] }],
+        connections: []
+      };
+      if (!tracked.some((path) => ownerOf(path, alone) !== null))
+        found.push({ partId: part.id, pattern });
+    }
+  }
+  return found;
+}
+function unownedPatternLines(unowned, verb) {
+  return unowned.map((u) => `halfcycle ${verb}: warning: "${u.pattern}" (part "${u.partId}") matches no file in this repository. Correct the path, or remove it if the code moved.
+`).join("");
+}
+function systemReportUrl(credential) {
+  return `${credential.serviceUrl}/engagements/${encodeURIComponent(credential.engagementId)}/system`;
+}
+function serviceHost(serviceUrl) {
+  try {
+    return new URL(serviceUrl).host;
+  } catch {
+    return serviceUrl;
+  }
+}
+async function reportSystemDescription(credential, description) {
+  let res;
+  let text;
+  try {
+    res = await fetch(systemReportUrl(credential), {
+      method: "POST",
+      headers: { authorization: `Bearer ${credential.token}`, "content-type": "application/json" },
+      body: JSON.stringify(description)
+    });
+    text = await res.text();
+  } catch {
+    return {
+      kind: "unavailable",
+      why: `could not reach Halfcycle at ${serviceHost(credential.serviceUrl)}. Check this machine's connection, then run this again.`
+    };
+  }
+  let raw = null;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    raw = null;
+  }
+  const parsed = systemReportResultSchema.safeParse(raw);
+  if (parsed.success) {
+    const answer = parsed.data;
+    if (answer.outcome === "recorded") {
+      return { kind: "recorded", version: answer.version, reportedAt: answer.reportedAt };
+    }
+    if (answer.outcome === "refused")
+      return { kind: "refused", problems: answer.problems };
+    return {
+      kind: "unavailable",
+      why: "Halfcycle could not record it just now. Nothing was recorded; run this again in a minute."
+    };
+  }
+  if (isMissingRoute("POST", res.status, raw))
+    return { kind: "no-route" };
+  const message = typeof raw === "object" && raw !== null && typeof raw.message === "string" ? raw.message : null;
+  if (res.ok) {
+    return {
+      kind: "unavailable",
+      why: "Halfcycle sent an answer this command could not read. Nothing was recorded; try again later."
+    };
+  }
+  return {
+    kind: "unavailable",
+    why: `Halfcycle answered ${res.status}${message === null ? "." : `: ${message}`}`
+  };
+}
+async function checkAndReportDescription(repoRoot, deps, verb, beforeSend = () => null) {
+  const p = `halfcycle ${verb}:`;
+  const file = readDescriptionFile(repoRoot);
+  if (file.kind === "missing") {
+    return {
+      kind: "stopped",
+      stderr: `${p} there is no ${SYSTEM_DESCRIPTION_REL} in this project yet. Run the Layer 2 architecture step to write it, then run this again.
+`
+    };
+  }
+  if (file.kind === "unreadable") {
+    return {
+      kind: "stopped",
+      stderr: `${p} ${SYSTEM_DESCRIPTION_REL} could not be read. Check that it is a file you can open, then run this again.
+`
+    };
+  }
+  if (file.kind === "not-json") {
+    return {
+      kind: "stopped",
+      stderr: `${p} ${SYSTEM_DESCRIPTION_REL} is not valid JSON (${file.error}). Fix it, then run this again. Nothing was sent.
+`
+    };
+  }
+  const checked = checkSystemDescription(file.value);
+  if (!checked.ok) {
+    const n = checked.problems.length;
+    return {
+      kind: "stopped",
+      stderr: `${p} ${SYSTEM_DESCRIPTION_REL} has ${n} ${n === 1 ? "problem" : "problems"}, so nothing was sent:
+` + problemLines(file.value, checked.problems)
+    };
+  }
+  const unowned = unownedPatterns(checked.description, deps.listTracked(repoRoot));
+  const warnings = unowned === null ? "" : unownedPatternLines(unowned, verb);
+  const refusal = beforeSend(checked.description);
+  if (refusal !== null)
+    return { kind: "stopped", stderr: warnings + refusal };
+  let credential;
+  try {
+    credential = deps.readCredential(repoRoot);
+  } catch {
+    return {
+      kind: "stopped",
+      stderr: warnings + `${p} this project is not connected to Halfcycle on this machine. Run ${HALFCYCLE_COMMAND} here first, then run this again. Nothing was sent.
+`
+    };
+  }
+  const outcome = await deps.report(credential, checked.description);
+  switch (outcome.kind) {
+    case "recorded":
+      return { kind: "recorded", version: outcome.version, credential, warnings };
+    case "refused": {
+      const n = outcome.problems.length;
+      return {
+        kind: "stopped",
+        stderr: warnings + `${p} Halfcycle refused ${SYSTEM_DESCRIPTION_REL} (${n} ${n === 1 ? "problem" : "problems"}); nothing was recorded:
+` + problemLines(file.value, outcome.problems)
+      };
+    }
+    case "no-route":
+      return { kind: "no-route", warnings };
+    case "unavailable":
+      return { kind: "stopped", stderr: warnings + `${p} ${outcome.why}
+` };
+  }
+}
+async function runSystem(repoRoot, deps) {
+  const stage = await checkAndReportDescription(repoRoot, deps, "system");
+  switch (stage.kind) {
+    case "stopped":
+      return { stdout: "", stderr: stage.stderr, exitCode: 1 };
+    case "no-route":
+      return {
+        stdout: "",
+        stderr: stage.warnings + "halfcycle system: this Halfcycle service cannot take a system description yet. Nothing was recorded.\n",
+        exitCode: 1
+      };
+    case "recorded":
+      return {
+        stdout: `[halfcycle] System description recorded: version ${stage.version}.
+`,
+        stderr: stage.warnings,
+        exitCode: 0
+      };
+  }
+}
+
+// dist/plan.js
+import { chmodSync as chmodSync3, mkdirSync as mkdirSync7, readFileSync as readFileSync10, renameSync as renameSync2, unlinkSync, writeFileSync as writeFileSync6 } from "node:fs";
+import { platform as platform4 } from "node:os";
+import { join as join11 } from "node:path";
+var PLAN_USAGE = `${HALFCYCLE_COMMAND} plan <phase> [--show] [--repo <root>]`;
+var PLAN_DIR_REL = "docs/phases";
+function planFileRel(phase) {
+  return `${PLAN_DIR_REL}/${renderPhaseSegment(phase)}.plan.json`;
+}
+var PLAN_CHANGE_LABELS = {
+  add: "Will be added",
+  change: "Will change",
+  remove: "Will be removed"
+};
+function parsePlanArgs(argv) {
+  const positionals = [];
+  let repoRoot;
+  let show = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--repo") {
+      const value = argv[i + 1];
+      if (repoRoot !== void 0 || value === void 0 || value === "" || value.startsWith("-"))
+        return { ok: false };
+      repoRoot = value;
+      i++;
+      continue;
+    }
+    if (arg === "--show") {
+      if (show)
+        return { ok: false };
+      show = true;
+      continue;
+    }
+    if (arg.startsWith("-"))
+      return { ok: false };
+    positionals.push(arg);
+  }
+  if (positionals.length !== 1)
+    return { ok: false };
+  return { ok: true, phase: positionals[0], show, repoRoot };
+}
+function planProblemPlace(raw, fileRel, path) {
+  if (path === "")
+    return fileRel;
+  const [list, index] = path.split(".");
+  const position = Number(index);
+  if (list !== "changes" || !Number.isInteger(position) || position < 0)
+    return path;
+  const changes = typeof raw === "object" && raw !== null ? raw["changes"] : void 0;
+  const item = Array.isArray(changes) ? changes[position] : void 0;
+  const part = typeof item === "object" && item !== null ? item["part"] : void 0;
+  return typeof part === "string" && part !== "" ? `${path} (part "${part}")` : `${path} (part ${position + 1})`;
+}
+function planProblemLines(raw, fileRel, problems) {
+  return problems.map((p) => `  ${planProblemPlace(raw, fileRel, p.path)}: ${p.message}
+`).join("");
+}
+function readAndCheckPlan(repoRoot, phase, description, verb) {
+  const p = `halfcycle ${verb}:`;
+  const fileRel = planFileRel(phase);
+  let text;
+  try {
+    text = readFileSync10(join11(repoRoot, fileRel), "utf-8");
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return {
+        ok: false,
+        line: `${p} there is no ${fileRel} in this project yet. Write the plan in the scoping step, then run this again. Nothing was sent.
+`
+      };
+    }
+    return {
+      ok: false,
+      line: `${p} ${fileRel} could not be read. Check that it is a file you can open, then run this again. Nothing was sent.
+`
+    };
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    const why = err instanceof Error ? err.message : String(err);
+    return { ok: false, line: `${p} ${fileRel} is not valid JSON (${why}). Fix it, then run this again. Nothing was sent.
+` };
+  }
+  const named = typeof raw === "object" && raw !== null ? raw["phase"] : void 0;
+  if (isValidPhaseIdentity(named) && renderPhaseSegment(named) !== renderPhaseSegment(phase)) {
+    return {
+      ok: false,
+      line: `${p} ${fileRel} is the plan for phase "${String(named)}", not phase "${phase}". Run this for the phase the plan names, or correct the plan's phase. Nothing was sent.
+`
+    };
+  }
+  const checked = checkPhasePlan(raw, description);
+  if (!checked.ok) {
+    const n = checked.problems.length;
+    return {
+      ok: false,
+      line: `${p} ${fileRel} has ${n} ${n === 1 ? "problem" : "problems"}, so nothing was sent:
+` + planProblemLines(raw, fileRel, checked.problems)
+    };
+  }
+  return { ok: true, plan: checked.plan };
+}
+function planReportUrl(credential, phase) {
+  return `${credential.serviceUrl}/engagements/${encodeURIComponent(credential.engagementId)}/phases/${encodeURIComponent(String(phase))}/plan`;
+}
+function serviceHost2(serviceUrl) {
+  try {
+    return new URL(serviceUrl).host;
+  } catch {
+    return serviceUrl;
+  }
+}
+async function reportPhasePlan(credential, plan, descriptionVersion) {
+  const body = { descriptionVersion, plan };
+  let res;
+  let text;
+  try {
+    res = await fetch(planReportUrl(credential, plan.phase), {
+      method: "POST",
+      headers: { authorization: `Bearer ${credential.token}`, "content-type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    text = await res.text();
+  } catch {
+    return {
+      kind: "unavailable",
+      why: `could not reach Halfcycle at ${serviceHost2(credential.serviceUrl)}. Check this machine's connection, then run this again.`
+    };
+  }
+  let raw = null;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    raw = null;
+  }
+  const parsed = phasePlanResultSchema.safeParse(raw);
+  if (parsed.success) {
+    const answer = parsed.data;
+    if (answer.outcome === "recorded") {
+      return {
+        kind: "recorded",
+        version: answer.version,
+        phaseNumber: answer.phaseNumber,
+        state: answer.state,
+        changedParts: answer.changedParts,
+        typedApprovalOffered: answer.typedApprovalOffered
+      };
+    }
+    if (answer.outcome === "refused")
+      return { kind: "refused", problems: answer.problems };
+    return {
+      kind: "unavailable",
+      why: "Halfcycle could not record the plan just now. Nothing was recorded; run this again in a minute."
+    };
+  }
+  if (isMissingRoute("POST", res.status, raw))
+    return { kind: "no-route" };
+  if (res.ok) {
+    return {
+      kind: "unavailable",
+      why: "Halfcycle sent an answer this command could not read. The plan may not be recorded; run this again later."
+    };
+  }
+  const message = typeof raw === "object" && raw !== null && typeof raw.message === "string" ? raw.message : null;
+  return {
+    kind: "unavailable",
+    why: `Halfcycle answered ${res.status}${message === null ? "." : `: ${message}`}`
+  };
+}
+function writeShownPlan(engagementId, entry, home) {
+  let temp = null;
+  try {
+    const dir = engagementStateDir(engagementId, home);
+    const path = join11(dir, SHOWN_PLANS_FILENAME);
+    let existing = [];
+    try {
+      existing = parseShownPlans(readFileSync10(path, "utf-8"));
+    } catch {
+      existing = [];
+    }
+    const kept = existing.filter((e) => e.phase !== entry.phase && e.number !== entry.number);
+    const entries = [...kept, entry];
+    const body = serialiseShownPlans(entries);
+    mkdirSync7(dir, { recursive: true, mode: 448 });
+    temp = join11(dir, `.${SHOWN_PLANS_FILENAME}.${process.pid}.tmp`);
+    writeFileSync6(temp, body, { mode: 384 });
+    if (platform4() !== "win32")
+      chmodSync3(temp, 384);
+    renameSync2(temp, path);
+    return { ok: true, entries };
+  } catch {
+    if (temp !== null) {
+      try {
+        unlinkSync(temp);
+      } catch {
+      }
+    }
+    return { ok: false };
+  }
+}
+function readPinnedClientVersion(repoRoot) {
+  try {
+    const version = readBundlePin(repoRoot)?.version;
+    return typeof version === "string" ? version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function planRefusedLines(verb, phase, plan, problems) {
+  const fileRel = planFileRel(phase);
+  const n = problems.length;
+  return `halfcycle ${verb}: Halfcycle refused ${fileRel} (${n} ${n === 1 ? "problem" : "problems"}); the plan was not recorded:
+` + planProblemLines(plan, fileRel, problems);
+}
+function notAPhaseNameLine(verb, phase) {
+  return `halfcycle ${verb}: "${phase}" is not a phase name: a name cannot be empty, start with a dot, or hold a slash, a backslash or a control character. Nothing was sent.
+`;
+}
+function planStateSentence(state) {
+  switch (state) {
+    case "waiting":
+      return "Waiting for the owner's approval.";
+    case "approved":
+      return "The owner has approved this plan.";
+    case "partly-stale":
+      return "The owner approved an earlier plan; the parts marked as changed wait for the owner's approval.";
+    case "sent-back":
+      return "The owner sent this plan back. Change it to answer the owner's notes, then run this again.";
+    case "withdrawn":
+      return "The owner withdrew their approval of this plan. It waits for the owner's approval again.";
+  }
+}
+function approvalLine(phase, number, typedApprovalOffered, pinnedVersion, shown2) {
+  if (!typedApprovalOffered)
+    return TYPED_APPROVAL_OFF_SENTENCE;
+  if (!clientMeetsChatApprovalFloor(pinnedVersion))
+    return CLIENT_UPDATE_SENTENCE;
+  const byNumber = String(number);
+  const numberReachesThis = byNumber !== phase && resolvePhaseReference(byNumber, shown2)?.phase === phase;
+  const typed = numberReachesThis ? `\`approve ${phase}\` (or \`approve ${byNumber}\`)` : `\`approve ${phase}\``;
+  return `To approve it, the project's owner types ${typed} in their own Claude Code session. Only the owner can.`;
+}
+function changeLines(plan, description, changed) {
+  const names = new Map(description.parts.map((part) => [part.id, part.name]));
+  const marked = new Set(changed);
+  return plan.changes.map((c) => {
+    const mark = marked.has(c.part) ? " (changed since the owner last decided)" : "";
+    return `  - ${names.get(c.part) ?? c.part} \xB7 ${PLAN_CHANGE_LABELS[c.change]} \xB7 ${c.summary}${mark}
+`;
+  }).join("");
+}
+async function runPlan(repoRoot, phase, show, deps) {
+  const p = "halfcycle plan:";
+  if (!isValidPhaseIdentity(phase))
+    return { stdout: "", stderr: notAPhaseNameLine("plan", phase), exitCode: 1 };
+  let checkedPlan = null;
+  let checkedDescription = null;
+  const stage = await checkAndReportDescription(repoRoot, deps, "plan", (description2) => {
+    const checked = readAndCheckPlan(repoRoot, phase, description2, "plan");
+    if (!checked.ok)
+      return checked.line;
+    checkedPlan = checked.plan;
+    checkedDescription = description2;
+    return null;
+  });
+  if (stage.kind === "stopped")
+    return { stdout: "", stderr: stage.stderr, exitCode: 1 };
+  const cannotTakeYet = `${p} this Halfcycle service cannot take a phase plan yet. Nothing was recorded.
+`;
+  if (stage.kind === "no-route")
+    return { stdout: "", stderr: stage.warnings + cannotTakeYet, exitCode: 1 };
+  const warnings = stage.warnings;
+  const plan = checkedPlan;
+  const description = checkedDescription;
+  if (plan === null || description === null) {
+    return { stdout: "", stderr: warnings + `${p} the plan was not checked, so nothing more was sent.
+`, exitCode: 1 };
+  }
+  const outcome = await deps.reportPlan(stage.credential, plan, stage.version);
+  switch (outcome.kind) {
+    case "no-route":
+      return { stdout: "", stderr: warnings + cannotTakeYet, exitCode: 1 };
+    case "unavailable":
+      return { stdout: "", stderr: warnings + `${p} ${outcome.why}
+`, exitCode: 1 };
+    case "refused":
+      return { stdout: "", stderr: warnings + planRefusedLines("plan", phase, plan, outcome.problems), exitCode: 1 };
+    case "recorded":
+      break;
+  }
+  const shownPhase = String(plan.phase);
+  const recorded = `[halfcycle] Plan for ${shownPhase} recorded: plan version ${outcome.version} (phase ${outcome.phaseNumber}).`;
+  const stateSentence = planStateSentence(outcome.state);
+  if (!show)
+    return { stdout: `${recorded} ${stateSentence}
+`, stderr: warnings, exitCode: 0 };
+  const entry = {
+    phase: shownPhase,
+    number: outcome.phaseNumber,
+    version: outcome.version,
+    shownAt: deps.now().toISOString()
+  };
+  const written = deps.recordShown(stage.credential.engagementId, entry);
+  const listed = `${recorded}
+` + changeLines(plan, description, outcome.changedParts) + `${stateSentence}
+`;
+  if (!written.ok) {
+    return {
+      stdout: listed,
+      stderr: warnings + `${p} the list above could not be recorded on this machine, so typing an approval for it would not work. Check that the .halfcycle folder in your home folder can be written to, then run this again.
+`,
+      exitCode: 1
+    };
+  }
+  const stdout = listed + `${approvalLine(shownPhase, outcome.phaseNumber, outcome.typedApprovalOffered, deps.pinnedClientVersion(repoRoot), written.entries)}
+`;
+  return { stdout, stderr: warnings, exitCode: 0 };
+}
+
+// dist/draw/write.js
+import { closeSync as closeSync2, lstatSync as lstatSync2, mkdirSync as mkdirSync8, openSync as openSync2, readFileSync as readFileSync11, readSync, realpathSync as realpathSync3, rmSync as rmSync4 } from "node:fs";
+import { dirname as dirname5, isAbsolute as isAbsolute3, join as join12, relative as relative4, resolve as resolve3, sep } from "node:path";
+var DOCS_DIR = "docs";
+var DIAGRAMS_DIR = "diagrams";
+var DIAGRAM_DIR_REL = `${DOCS_DIR}/${DIAGRAMS_DIR}`;
+var ARCHITECTURE_NAME = "architecture";
+var ARCHITECTURE_BASE = ARCHITECTURE_NAME;
+function phaseDiagramBase(phase) {
+  return renderPhaseSegment(phase);
+}
+var FLIGHTDECK_SUFFIX = ".flightdeck";
+function baseTakesFlightDeckNames(base) {
+  return base.toLowerCase().endsWith(FLIGHTDECK_SUFFIX);
+}
+function pictureNames(base) {
+  const names = {
+    broadsheet: base,
+    flightdeck: `${base}${FLIGHTDECK_SUFFIX}`
+  };
+  return names;
+}
+var EMBEDDED_LOOK = "broadsheet";
+var DIAGRAM_MARKER_LINE = SYSTEM_DIAGRAM_MARKER_LINE;
+var PNG_SIGNATURE = Uint8Array.from([137, 80, 78, 71, 13, 10, 26, 10]);
+function svgOf(look) {
+  return `${look}.svg`;
+}
+function pngOf(look) {
+  return `${look}.png`;
+}
+var DIAGRAM_FILES = [
+  ...SYSTEM_PICTURE_THEMES.map(svgOf),
+  ...SYSTEM_PICTURE_THEMES.map(pngOf),
+  "mmd"
+];
+function fileNames(base) {
+  const looks = pictureNames(base);
+  return Object.fromEntries([
+    ...SYSTEM_PICTURE_THEMES.flatMap((look) => [
+      [svgOf(look), `${looks[look]}.svg`],
+      [pngOf(look), `${looks[look]}.png`]
+    ]),
+    ["mmd", `${base}.mmd`]
+  ]);
+}
+function embedImageName(base) {
+  return fileNames(base)[pngOf(EMBEDDED_LOOK)];
+}
+function markdownLinkName(name) {
+  return encodeURIComponent(name).replace(/\(/g, "%28").replace(/\)/g, "%29");
+}
+function embedImageLink(base, doc) {
+  const up = doc === "docs" ? "" : "../";
+  return `${up}${DIAGRAMS_DIR}/${markdownLinkName(embedImageName(base))}`;
+}
+function diagramPaths(repoRoot, base) {
+  const root = resolve3(repoRoot);
+  const dir = join12(root, DOCS_DIR, DIAGRAMS_DIR);
+  const names = fileNames(base);
+  const file = Object.fromEntries(DIAGRAM_FILES.map((which) => [which, join12(dir, names[which])]));
+  return { repoRoot: root, dir, file };
+}
+function diagramRel(base, which) {
+  return `${DIAGRAM_DIR_REL}/${fileNames(base)[which]}`;
+}
+var DIAGRAM_FILES_AS_LISTED = [
+  ...SYSTEM_PICTURE_THEMES.flatMap((look) => [pngOf(look), svgOf(look)]),
+  "mmd"
+];
+function spokenList(items) {
+  if (items.length <= 1)
+    return items.join("");
+  return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+function lstatOrNull2(path) {
+  try {
+    return lstatSync2(path);
+  } catch {
+    return null;
+  }
+}
+function isInside(outer, inner) {
+  const rel = relative4(outer, inner);
+  return rel === "" || !isAbsolute3(rel) && rel !== ".." && !rel.startsWith(`..${sep}`);
+}
+function checkDiagramPlace(paths) {
+  let root;
+  try {
+    root = realpathSync3(paths.repoRoot);
+  } catch {
+    return { ok: false, why: `the folder ${paths.repoRoot} could not be opened. Check the path, then run this again.` };
+  }
+  let ancestor = paths.dir;
+  while (lstatOrNull2(ancestor) === null) {
+    const parent = dirname5(ancestor);
+    if (parent === ancestor)
+      break;
+    ancestor = parent;
+  }
+  let real;
+  try {
+    real = realpathSync3(ancestor);
+  } catch {
+    return {
+      ok: false,
+      why: `${DIAGRAM_DIR_REL} leads to a place that does not exist. Remove the link in the way, then run this again.`
+    };
+  }
+  if (!isInside(root, real)) {
+    return {
+      ok: false,
+      why: `${DIAGRAM_DIR_REL} leads outside this repository, so nothing was written. Remove the link in the way, then run this again.`
+    };
+  }
+  let isFolder = false;
+  try {
+    isFolder = lstatSync2(real).isDirectory();
+  } catch {
+    isFolder = false;
+  }
+  if (!isFolder) {
+    const name = relative4(root, real).split("\\").join("/");
+    return {
+      ok: false,
+      why: `${name === "" ? "this repository" : name} is not a folder, so ${DIAGRAM_DIR_REL} cannot be made. Move it, then run this again.`
+    };
+  }
+  return { ok: true };
+}
+function startsWithMarkerLine(bytes) {
+  const head = Buffer.from(bytes.subarray(0, DIAGRAM_MARKER_LINE.length + 2)).toString("utf-8");
+  return head.startsWith(`${DIAGRAM_MARKER_LINE}
+`) || head.startsWith(`${DIAGRAM_MARKER_LINE}\r
+`);
+}
+function readHead(path) {
+  const fd = openSync2(path, "r");
+  try {
+    const head = Buffer.alloc(DIAGRAM_MARKER_LINE.length + 2);
+    const got = readSync(fd, head, 0, head.length, 0);
+    return head.subarray(0, got);
+  } finally {
+    closeSync2(fd);
+  }
+}
+function readExistingSet(paths) {
+  const found = Object.fromEntries(DIAGRAM_FILES.map((which) => [which, null]));
+  for (const which of DIAGRAM_FILES) {
+    const stat = lstatOrNull2(paths.file[which]);
+    if (stat === null)
+      continue;
+    if (!stat.isFile())
+      return { ok: false, inTheWay: which, temp: false };
+    try {
+      found[which] = readFileSync11(paths.file[which]);
+    } catch {
+      return { ok: false, inTheWay: which, temp: false };
+    }
+  }
+  for (const look of SYSTEM_PICTURE_THEMES) {
+    const svg = found[svgOf(look)];
+    if (svg !== null && !startsWithMarkerLine(svg))
+      return { ok: false, inTheWay: svgOf(look), temp: false };
+  }
+  for (const look of SYSTEM_PICTURE_THEMES) {
+    if (found[pngOf(look)] !== null && found[svgOf(look)] === null)
+      return { ok: false, inTheWay: pngOf(look), temp: false };
+  }
+  if (found.mmd !== null && found[svgOf(EMBEDDED_LOOK)] === null)
+    return { ok: false, inTheWay: "mmd", temp: false };
+  const temp = Object.fromEntries(DIAGRAM_FILES.map((which) => [which, null]));
+  for (const which of DIAGRAM_FILES) {
+    const stat = lstatOrNull2(tempPath(paths, which));
+    if (stat === null)
+      continue;
+    if (!stat.isFile())
+      return { ok: false, inTheWay: which, temp: true };
+    try {
+      temp[which] = readHead(tempPath(paths, which));
+    } catch {
+      return { ok: false, inTheWay: which, temp: true };
+    }
+  }
+  for (const look of SYSTEM_PICTURE_THEMES) {
+    const svg = temp[svgOf(look)];
+    if (svg !== null && !startsWithMarkerLine(svg))
+      return { ok: false, inTheWay: svgOf(look), temp: true };
+  }
+  const markedSvgBeside = (look) => found[svgOf(look)] !== null || temp[svgOf(look)] !== null;
+  for (const look of SYSTEM_PICTURE_THEMES) {
+    if (temp[pngOf(look)] !== null && !markedSvgBeside(look))
+      return { ok: false, inTheWay: pngOf(look), temp: true };
+  }
+  if (temp.mmd !== null && !markedSvgBeside(EMBEDDED_LOOK))
+    return { ok: false, inTheWay: "mmd", temp: true };
+  return { ok: true, existing: found, ourTemps: DIAGRAM_FILES.filter((which) => temp[which] !== null) };
+}
+function tempPath(paths, which) {
+  return `${paths.file[which]}.tmp`;
+}
+function inTheWayLine(base, which, temp = false) {
+  return `${diagramRel(base, which)}${temp ? ".tmp" : ""} is already there and was not drawn by this command. Move it or delete it, then run this again. Nothing was written.`;
+}
+function checkPictures(drawn, base) {
+  const set = {};
+  for (const look of SYSTEM_PICTURE_THEMES) {
+    const picture = drawn.pictures[look];
+    const pngFor = diagramRel(base, pngOf(look));
+    const svgFor = diagramRel(base, svgOf(look));
+    const png = Buffer.from(picture.png, "base64");
+    if (png.length > SYSTEM_DRAW_PNG_MAX_BYTES)
+      return { ok: false, why: `the image for ${pngFor} is larger than 8 MB` };
+    if (png.length < PNG_SIGNATURE.length || !PNG_SIGNATURE.every((b, i) => png[i] === b)) {
+      return { ok: false, why: `the image for ${pngFor} is not a PNG` };
+    }
+    const svg = Buffer.from(picture.svg, "utf-8");
+    if (svg.length > SYSTEM_DRAW_SVG_MAX_BYTES)
+      return { ok: false, why: `the picture for ${svgFor} is larger than 2 MB` };
+    const body = picture.svg.endsWith("\n") ? picture.svg.slice(0, -1) : picture.svg;
+    if (!picture.svg.startsWith(`${DIAGRAM_MARKER_LINE}
+<svg`) || !body.endsWith("</svg>")) {
+      return { ok: false, why: `the picture for ${svgFor} is not a complete SVG drawn by Halfcycle` };
+    }
+    set[pngOf(look)] = png;
+    set[svgOf(look)] = svg;
+  }
+  const mmd = Buffer.from(drawn.mermaid, "utf-8");
+  if (mmd.length > SYSTEM_DRAW_MERMAID_MAX_BYTES)
+    return { ok: false, why: "the diagram text is larger than 256 KB" };
+  if (!drawn.mermaid.startsWith("flowchart"))
+    return { ok: false, why: "the diagram text is not a Mermaid flowchart" };
+  set.mmd = mmd;
+  return { ok: true, set };
+}
+function removeQuietly(path) {
+  try {
+    rmSync4(path, { force: true });
+  } catch {
+    return;
+  }
+}
+function sameBytes(a, b) {
+  return a !== null && Buffer.from(a).equals(b);
+}
+function writeDiagramSet(repoRoot, base, set, io = NODE_RECORD_PAIR_IO) {
+  const paths = diagramPaths(repoRoot, base);
+  const place = checkDiagramPlace(paths);
+  if (!place.ok)
+    return { kind: "unsafe", why: place.why };
+  const read = readExistingSet(paths);
+  if (!read.ok)
+    return { kind: "in-the-way", file: read.inTheWay, temp: read.temp };
+  const existing = read.existing;
+  const changed = DIAGRAM_FILES.filter((which) => !sameBytes(existing[which], set[which]));
+  if (changed.length === 0)
+    return { kind: "up-to-date" };
+  try {
+    mkdirSync8(paths.dir, { recursive: true });
+  } catch {
+    return { kind: "failed", file: changed[0], removed: [] };
+  }
+  const made = checkDiagramPlace(paths);
+  if (!made.ok)
+    return { kind: "unsafe", why: made.why };
+  const tmp = (which) => tempPath(paths, which);
+  for (const which of read.ourTemps)
+    removeQuietly(tmp(which));
+  const staged = [];
+  const clearStaged = () => {
+    for (const which of staged)
+      removeQuietly(tmp(which));
+  };
+  for (const which of changed) {
+    try {
+      io.createExclusive(tmp(which), set[which]);
+      staged.push(which);
+    } catch {
+      clearStaged();
+      return { kind: "failed", file: which, removed: [] };
+    }
+  }
+  const renamed = [];
+  for (const which of changed) {
+    try {
+      io.rename(tmp(which), paths.file[which]);
+      renamed.push(which);
+    } catch {
+      clearStaged();
+      const removed = restore(io, paths, renamed, existing);
+      return { kind: "failed", file: which, removed };
+    }
+  }
+  return { kind: "written", changed };
+}
+function restore(io, paths, renamed, existing) {
+  const removed = [];
+  for (const which of [...renamed].reverse()) {
+    const finalPath = paths.file[which];
+    const previous = existing[which];
+    const tmp = tempPath(paths, which);
+    try {
+      if (previous === null) {
+        rmSync4(finalPath, { force: true });
+        continue;
+      }
+      rmSync4(tmp, { force: true });
+      io.createExclusive(tmp, previous);
+      io.rename(tmp, finalPath);
+    } catch {
+      removeQuietly(tmp);
+      removeQuietly(finalPath);
+      removed.push(which);
+    }
+  }
+  return removed;
+}
+
+// dist/draw/index.js
+var DRAW_USAGE = `${HALFCYCLE_COMMAND} draw (architecture | phase <phase>) [--repo <root>]`;
+function parseDrawArgs(argv) {
+  const positionals = [];
+  let repoRoot;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--repo") {
+      const value = argv[i + 1];
+      if (repoRoot !== void 0 || value === void 0 || value === "" || value.startsWith("-"))
+        return { ok: false };
+      repoRoot = value;
+      i++;
+      continue;
+    }
+    if (arg.startsWith("-"))
+      return { ok: false };
+    positionals.push(arg);
+  }
+  if (positionals.length === 1 && positionals[0] === "architecture") {
+    return { ok: true, picture: { kind: "architecture" }, repoRoot };
+  }
+  if (positionals.length === 2 && positionals[0] === "phase") {
+    return { ok: true, picture: { kind: "phase", phase: positionals[1] }, repoRoot };
+  }
+  return { ok: false };
+}
+function systemDrawUrl(credential) {
+  return `${credential.serviceUrl}/engagements/${encodeURIComponent(credential.engagementId)}/system/draw`;
+}
+function serviceHost3(serviceUrl) {
+  try {
+    return new URL(serviceUrl).host;
+  } catch {
+    return serviceUrl;
+  }
+}
+async function requestDrawing(credential, request) {
+  let res;
+  let text;
+  try {
+    res = await fetch(systemDrawUrl(credential), {
+      method: "POST",
+      headers: { authorization: `Bearer ${credential.token}`, "content-type": "application/json" },
+      body: JSON.stringify(request)
+    });
+    text = await res.text();
+  } catch {
+    return {
+      kind: "unavailable",
+      why: `could not reach Halfcycle at ${serviceHost3(credential.serviceUrl)}. Check this machine's connection, then run this again. Nothing was written.`
+    };
+  }
+  let raw = null;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    raw = null;
+  }
+  const parsed = systemDrawResultSchema.safeParse(raw);
+  if (parsed.success) {
+    const answer = parsed.data;
+    if (answer.outcome === "drawn")
+      return { kind: "drawn", drawn: answer };
+    if (answer.outcome === "refused")
+      return { kind: "refused", reason: answer.reason };
+    return {
+      kind: "unavailable",
+      why: "Halfcycle could not draw the pictures just now. Nothing was written; run this again in a minute."
+    };
+  }
+  if (isMissingRoute("POST", res.status, raw))
+    return { kind: "no-route" };
+  if (res.ok) {
+    return {
+      kind: "unavailable",
+      why: "Halfcycle sent an answer this command could not read. Nothing was written; try again later."
+    };
+  }
+  const message = typeof raw === "object" && raw !== null && typeof raw.message === "string" ? raw.message : null;
+  return {
+    kind: "unavailable",
+    why: `Halfcycle answered ${res.status}${message === null ? "." : `: ${message}`} Nothing was written.`
+  };
+}
+var P = "halfcycle draw:";
+var CANNOT_DRAW_YET = `${P} this Halfcycle service cannot draw pictures yet. Nothing was written.
+`;
+var CANNOT_DRAW_PHASE_YET = `${P} this Halfcycle service cannot draw phase pictures yet. Nothing was written.
+`;
+function markdownAltText(text) {
+  return text.replace(/[[\]\\]/g, (ch) => `\\${ch}`);
+}
+var ARCHITECTURE_PASTE = { doc: "docs", alt: "Architecture", base: ARCHITECTURE_BASE };
+function phasePaste(phase) {
+  return { doc: "docs/phases", alt: `Phase ${phase}`, base: phaseDiagramBase(phase) };
+}
+function pasteLines(mermaid, target) {
+  const block = mermaid.endsWith("\n") ? mermaid : `${mermaid}
+`;
+  const where = target.doc === "docs" ? "a document directly under docs/" : "this phase's document in docs/phases/";
+  return `
+Paste this into ${where}:
+
+![${markdownAltText(target.alt)}](${embedImageLink(target.base, target.doc)})
+
+\`\`\`mermaid
+` + block + "```\n";
+}
+function localRefusal(repoRoot, base) {
+  const paths = diagramPaths(repoRoot, base);
+  const place = checkDiagramPlace(paths);
+  if (!place.ok)
+    return `${P} ${place.why}
+`;
+  const read = readExistingSet(paths);
+  if (!read.ok)
+    return `${P} ${inTheWayLine(base, read.inTheWay, read.temp)}
+`;
+  return null;
+}
+async function runDraw(repoRoot, picture, deps) {
+  if (picture.kind === "architecture") {
+    const stage2 = await checkAndReportDescription(repoRoot, deps, "draw", () => localRefusal(repoRoot, ARCHITECTURE_BASE));
+    if (stage2.kind === "stopped")
+      return { stdout: "", stderr: stage2.stderr, exitCode: 1 };
+    if (stage2.kind === "no-route")
+      return { stdout: "", stderr: stage2.warnings + CANNOT_DRAW_YET, exitCode: 1 };
+    return drawAndWrite(repoRoot, deps, stage2.credential, { version: stage2.version, picture: "architecture" }, ARCHITECTURE_PASTE, stage2.warnings, CANNOT_DRAW_YET);
+  }
+  const phase = picture.phase;
+  if (!isValidPhaseIdentity(phase))
+    return { stdout: "", stderr: notAPhaseNameLine("draw", phase), exitCode: 1 };
+  const base = phaseDiagramBase(phase);
+  if (baseTakesFlightDeckNames(base)) {
+    return {
+      stdout: "",
+      stderr: `${P} the phase "${phase}" cannot be drawn: its pictures would take the names of another phase's Flight Deck pictures. Name the phase so it does not end in ".flightdeck", then run this again. Nothing was sent.
+`,
+      exitCode: 1
+    };
+  }
+  let checkedPlan = null;
+  const beforeSend = (description) => {
+    const checked = readAndCheckPlan(repoRoot, phase, description, "draw");
+    if (!checked.ok)
+      return checked.line;
+    const refusal = localRefusal(repoRoot, base);
+    if (refusal !== null)
+      return refusal;
+    checkedPlan = checked.plan;
+    return null;
+  };
+  const stage = await checkAndReportDescription(repoRoot, deps, "draw", beforeSend);
+  if (stage.kind === "stopped")
+    return { stdout: "", stderr: stage.stderr, exitCode: 1 };
+  if (stage.kind === "no-route")
+    return { stdout: "", stderr: stage.warnings + CANNOT_DRAW_PHASE_YET, exitCode: 1 };
+  const warnings = stage.warnings;
+  const plan = checkedPlan;
+  if (plan === null) {
+    return { stdout: "", stderr: warnings + `${P} the plan was not checked, so nothing more was sent.
+`, exitCode: 1 };
+  }
+  const reported = await deps.reportPlan(stage.credential, plan, stage.version);
+  switch (reported.kind) {
+    case "no-route":
+      return { stdout: "", stderr: warnings + CANNOT_DRAW_PHASE_YET, exitCode: 1 };
+    case "unavailable":
+      return { stdout: "", stderr: warnings + `${P} ${reported.why}
+`, exitCode: 1 };
+    case "refused":
+      return { stdout: "", stderr: warnings + planRefusedLines("draw", phase, plan, reported.problems), exitCode: 1 };
+    case "recorded":
+      break;
+  }
+  return drawAndWrite(repoRoot, deps, stage.credential, { picture: "phase", phase: plan.phase, planVersion: reported.version }, phasePaste(phase), warnings, CANNOT_DRAW_PHASE_YET);
+}
+async function drawAndWrite(repoRoot, deps, credential, request, target, warnings, cannotDrawYet) {
+  const base = target.base;
+  const outcome = await deps.draw(credential, request);
+  if (outcome.kind === "no-route")
+    return { stdout: "", stderr: warnings + cannotDrawYet, exitCode: 1 };
+  if (outcome.kind === "refused") {
+    return {
+      stdout: "",
+      stderr: warnings + `${P} Halfcycle would not draw the pictures: ${outcome.reason} Nothing was written.
+`,
+      exitCode: 1
+    };
+  }
+  if (outcome.kind === "unavailable")
+    return { stdout: "", stderr: warnings + `${P} ${outcome.why}
+`, exitCode: 1 };
+  const checked = checkPictures(outcome.drawn, base);
+  if (!checked.ok) {
+    return {
+      stdout: "",
+      stderr: warnings + `${P} Halfcycle sent pictures this command cannot use (${checked.why}). Nothing was written; try again later.
+`,
+      exitCode: 1
+    };
+  }
+  const rel = (which) => diagramRel(base, which);
+  const result = deps.write(repoRoot, base, checked.set);
+  switch (result.kind) {
+    case "up-to-date":
+      return {
+        stdout: `[halfcycle] The pictures in ${DIAGRAM_DIR_REL}/ are up to date.
+` + pasteLines(outcome.drawn.mermaid, target),
+        stderr: warnings,
+        exitCode: 0
+      };
+    case "written":
+      return {
+        stdout: `[halfcycle] Wrote ${spokenList(DIAGRAM_FILES_AS_LISTED.map(rel))}.
+` + pasteLines(outcome.drawn.mermaid, target),
+        stderr: warnings,
+        exitCode: 0
+      };
+    case "in-the-way":
+      return { stdout: "", stderr: warnings + `${P} ${inTheWayLine(base, result.file, result.temp)}
+`, exitCode: 1 };
+    case "unsafe":
+      return { stdout: "", stderr: warnings + `${P} ${result.why}
+`, exitCode: 1 };
+    case "failed": {
+      const lost = result.removed.length === 0 ? "The pictures already there are as they were." : `${spokenList(result.removed.map(rel))} could not be put back as ${result.removed.length === 1 ? "it was, so it was" : "they were, so they were"} removed; the other pictures are as they were.`;
+      return {
+        stdout: "",
+        stderr: warnings + `${P} ${rel(result.file)} could not be written. ${lost} Check that you can write to ${DIAGRAM_DIR_REL}, then run this again.
+`,
+        exitCode: 1
+      };
+    }
+  }
+}
+
 // dist/cli-contract.js
-var CLI_VERBS = ["install", "check-drift", "build-record", "open-phase", "close-phase", "uninstall"];
+var CLI_VERBS = ["install", "check-drift", "build-record", "open-phase", "close-phase", "system", "draw", "plan", "uninstall"];
 var CONTRACTS = [
   { verb: "install", required: [], conditional: [] },
   { verb: "check-drift", required: [], conditional: [] },
   { verb: "build-record", required: [], conditional: [] },
+  { verb: "system", required: [], conditional: [] },
+  { verb: "draw", required: [], conditional: [] },
+  { verb: "plan", required: [], conditional: [] },
   { verb: "uninstall", required: [], conditional: [] },
   {
     verb: "open-phase",
@@ -5674,9 +7725,9 @@ function placeholderRefusal(verb, tokens) {
 }
 
 // dist/uninstall.js
-import { lstatSync as lstatSync2, readFileSync as readFileSync9, readdirSync, rmSync as rmSync4, rmdirSync, writeFileSync as writeFileSync6 } from "node:fs";
+import { lstatSync as lstatSync3, readFileSync as readFileSync12, readdirSync, rmSync as rmSync5, rmdirSync, writeFileSync as writeFileSync7 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { dirname as dirname5, join as join10, relative as relative4, sep } from "node:path";
+import { dirname as dirname6, join as join13, relative as relative5, sep as sep2 } from "node:path";
 var REMOVE_CREDENTIAL_FLAG = "--remove-credential";
 function parseUninstallArgs(args2) {
   let removeCredential = false;
@@ -5693,7 +7744,7 @@ function parseUninstallArgs(args2) {
 }
 function lexists(path) {
   try {
-    lstatSync2(path);
+    lstatSync3(path);
     return true;
   } catch {
     return false;
@@ -5702,9 +7753,9 @@ function lexists(path) {
 function symlinkOnPath(root, rel) {
   let current = root;
   for (const segment of rel.split("/")) {
-    current = join10(current, segment);
+    current = join13(current, segment);
     try {
-      if (lstatSync2(current).isSymbolicLink())
+      if (lstatSync3(current).isSymbolicLink())
         return true;
     } catch {
       return false;
@@ -5712,7 +7763,7 @@ function symlinkOnPath(root, rel) {
   }
   return false;
 }
-function isPlainObject2(value) {
+function isPlainObject3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function serializeJson(value) {
@@ -5724,13 +7775,13 @@ function readMergedJson(targetRepo, rule) {
   const { rel } = rule;
   if (symlinkOnPath(targetRepo, rel))
     return { state: "symlink" };
-  const path = join10(targetRepo, rel);
+  const path = join13(targetRepo, rel);
   if (!lexists(path))
     return { state: "absent" };
   let text;
   let value;
   try {
-    text = readFileSync9(path, "utf-8");
+    text = readFileSync12(path, "utf-8");
   } catch {
     text = "";
   }
@@ -5739,7 +7790,7 @@ function readMergedJson(targetRepo, rule) {
   } catch {
     value = void 0;
   }
-  if (isPlainObject2(value))
+  if (isPlainObject3(value))
     return { state: "object", text, value };
   if (!rule.holdsOurs(text))
     return { state: "not-ours" };
@@ -5747,15 +7798,15 @@ function readMergedJson(targetRepo, rule) {
 }
 function validate(options, rules) {
   const { targetRepo, removeCredential, home } = options;
-  const manifestPath = join10(targetRepo, INSTALL_MANIFEST_REL);
-  const pinPath = join10(targetRepo, BUNDLE_PIN_REL);
+  const manifestPath = join13(targetRepo, INSTALL_MANIFEST_REL);
+  const pinPath = join13(targetRepo, BUNDLE_PIN_REL);
   if (symlinkOnPath(targetRepo, INSTALL_MANIFEST_REL) || symlinkOnPath(targetRepo, BUNDLE_PIN_REL)) {
     throw new Refusal(`.halfcycle, or a file Halfcycle keeps in it, is a symbolic link here, so nothing was followed and nothing was removed.`);
   }
   let manifest = null;
   if (lexists(manifestPath)) {
     try {
-      manifest = parseManifest(readFileSync9(manifestPath, "utf-8"));
+      manifest = parseManifest(readFileSync12(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 "${HALFCYCLE_COMMAND}" once to rewrite it, then run "${HALFCYCLE_COMMAND} uninstall" again.`);
@@ -5765,8 +7816,8 @@ function validate(options, rules) {
   let pinReadable = true;
   if (lexists(pinPath)) {
     try {
-      const pin = JSON.parse(readFileSync9(pinPath, "utf-8"));
-      const id = isPlainObject2(pin) ? pin[PIN_ENGAGEMENT_ID_FIELD] : void 0;
+      const pin = JSON.parse(readFileSync12(pinPath, "utf-8"));
+      const id = isPlainObject3(pin) ? pin[PIN_ENGAGEMENT_ID_FIELD] : void 0;
       engagementId = typeof id === "string" && id !== "" ? id : void 0;
     } catch {
       pinReadable = false;
@@ -5789,8 +7840,8 @@ function validate(options, rules) {
       throw new Refusal(`the project id in ${BUNDLE_PIN_REL} is not a valid Halfcycle project id, so it cannot name a folder on this machine. Nothing was removed, here or under ~/.halfcycle.`);
     }
     if (engagementId !== void 0) {
-      const expectedParent = join10(home ?? homedir2(), HALFCYCLE_DIR_NAME, ENGAGEMENTS_DIR_NAME);
-      if (dirname5(engagementStateDir(engagementId, home)) !== expectedParent) {
+      const expectedParent = join13(home ?? homedir2(), HALFCYCLE_DIR_NAME, ENGAGEMENTS_DIR_NAME);
+      if (dirname6(engagementStateDir(engagementId, home)) !== expectedParent) {
         throw new Refusal(`the project id in ${BUNDLE_PIN_REL} does not name a folder under ~/.halfcycle/engagements. Nothing was removed.`);
       }
     }
@@ -5813,13 +7864,13 @@ function mergedFileRules(writeSet) {
 function writeBack(targetRepo, rel, current, next, lists, name) {
   if (next === current)
     return;
-  const path = join10(targetRepo, rel);
+  const path = join13(targetRepo, rel);
   try {
     if (next === null) {
-      rmSync4(path);
+      rmSync5(path);
       name(lists.removed, rel, rel);
     } else {
-      writeFileSync6(path, next, "utf-8");
+      writeFileSync7(path, next, "utf-8");
       name(lists.restored, rel, rel);
     }
   } catch {
@@ -5831,7 +7882,7 @@ function noRecord(targetRepo, writeSet) {
   const claim = (rel, header, lines) => {
     let text;
     try {
-      text = symlinkOnPath(targetRepo, rel) ? "" : readFileSync9(join10(targetRepo, rel), "utf-8");
+      text = symlinkOnPath(targetRepo, rel) ? "" : readFileSync12(join13(targetRepo, rel), "utf-8");
     } catch {
       text = "";
     }
@@ -5860,16 +7911,16 @@ function noRecord(targetRepo, writeSet) {
 }
 function ourHookEntries(value, commands) {
   const hooks = value["hooks"];
-  if (!isPlainObject2(hooks))
+  if (!isPlainObject3(hooks))
     return [];
   const found = [];
   for (const [event, entries] of Object.entries(hooks)) {
     if (!Array.isArray(entries))
       continue;
     for (const entry of entries) {
-      if (!isPlainObject2(entry) || !Array.isArray(entry["hooks"]))
+      if (!isPlainObject3(entry) || !Array.isArray(entry["hooks"]))
         continue;
-      const objects = entry["hooks"].filter(isPlainObject2);
+      const objects = entry["hooks"].filter(isPlainObject3);
       if (isHalfcycleEntry({ hooks: objects }, commands)) {
         found.push({ event, entry });
       }
@@ -5879,7 +7930,7 @@ function ourHookEntries(value, commands) {
 }
 function ourMcpServers(value) {
   const servers = value["mcpServers"];
-  return isPlainObject2(servers) && MCP_SERVER_KEY in servers ? servers : null;
+  return isPlainObject3(servers) && MCP_SERVER_KEY in servers ? servers : null;
 }
 function unmergeSettings(value, rec, writeSet) {
   let changed = false;
@@ -5890,7 +7941,7 @@ function unmergeSettings(value, rec, writeSet) {
     refused.push(`${SETTINGS_REL}: a deny rule the install record names but Halfcycle never adds (it was kept)`);
   }
   const hooks = value["hooks"];
-  if (isPlainObject2(hooks)) {
+  if (isPlainObject3(hooks)) {
     const ours = new Set(ourHookEntries(value, commands).map(({ entry }) => entry));
     let emptiedAnEvent = false;
     for (const event of Object.keys(hooks)) {
@@ -5925,7 +7976,7 @@ function unmergeSettings(value, rec, writeSet) {
     }
   }
   const permissions = value["permissions"];
-  if (isPlainObject2(permissions) && Array.isArray(permissions["deny"])) {
+  if (isPlainObject3(permissions) && Array.isArray(permissions["deny"])) {
     const deny = permissions["deny"];
     for (const hash of denyHashes) {
       for (let i = deny.length - 1; i >= 0; i--) {
@@ -5957,7 +8008,7 @@ function unmergeSettings(value, rec, writeSet) {
 }
 function unmergeMcp(value, rec) {
   const servers = value["mcpServers"];
-  if (!isPlainObject2(servers))
+  if (!isPlainObject3(servers))
     return { changed: false };
   let changed = false;
   let removedEntry = false;
@@ -6057,7 +8108,7 @@ function lastOccurrence(text, block) {
 }
 function coveredPathExists(targetRepo, line) {
   const path = line.trim().replace(/^\//, "").replace(/\/$/, "");
-  return path !== "" && lexists(join10(targetRepo, path));
+  return path !== "" && lexists(join13(targetRepo, path));
 }
 function uninstall(options) {
   const result = {
@@ -6137,7 +8188,7 @@ function uninstall(options) {
   const gitattributes = manifest.gitattributes ?? { created: false, appended: [] };
   trimAppendedFile(targetRepo, gitattributes, deleteWhenEmpty(gitattributes.created), gitattributesRules(writeSet), result, name);
   const foundNothing = result.removed.length + result.restored.length + result.kept.length + result.failed.length === 0 && result.keptIgnoreLines.length === 0;
-  if (checked.manifest === null && !lexists(join10(targetRepo, BUNDLE_PIN_REL)) && foundNothing) {
+  if (checked.manifest === null && !lexists(join13(targetRepo, BUNDLE_PIN_REL)) && foundNothing) {
     return { outcome: "not-installed", exitCode: 0, ...result, credential: nothingToSay };
   }
   const credential = handleCredential(options, checked);
@@ -6145,7 +8196,7 @@ function uninstall(options) {
   if (result.failed.length === 0 && !credentialFailed) {
     removeInstalledFile(targetRepo, BUNDLE_PIN_REL, recorded.get(BUNDLE_PIN_REL), writeSet, result, name);
     try {
-      rmSync4(join10(targetRepo, INSTALL_MANIFEST_REL), { force: true });
+      rmSync5(join13(targetRepo, INSTALL_MANIFEST_REL), { force: true });
       named.add(INSTALL_MANIFEST_REL);
     } catch {
       name(result.failed, INSTALL_MANIFEST_REL, INSTALL_MANIFEST_REL);
@@ -6180,7 +8231,7 @@ function applyMergedJson(targetRepo, rule, file, deleteWhenEmpty, lists, name, e
     return;
   const empty = Object.keys(value).length === 0 && deleteWhenEmpty;
   writeBack(targetRepo, rel, file.text, empty ? null : inLineEndingOf(file.text, serializeJson(value)), lists, name);
-  if (adopted && lexists(join10(targetRepo, rel))) {
+  if (adopted && lexists(join13(targetRepo, rel))) {
     name(lists.leftAlone, `${rel} (Halfcycle's hooks were taken out. There is no record of this file from before the install, so a permission rule or "$schema" Halfcycle added may still be there \u2014 it cannot be told apart from your own)`, rel);
   }
 }
@@ -6193,10 +8244,10 @@ function removeInstalledFile(targetRepo, path, entry, writeSet, lists, name) {
     name(lists.leftAlone, `${path} (a symbolic link, or inside one \u2014 not followed)`, path);
     return;
   }
-  const abs = join10(targetRepo, path);
+  const abs = join13(targetRepo, path);
   let isFile;
   try {
-    isFile = lstatSync2(abs).isFile();
+    isFile = lstatSync3(abs).isFile();
   } catch {
     return;
   }
@@ -6207,7 +8258,7 @@ function removeInstalledFile(targetRepo, path, entry, writeSet, lists, name) {
   if (!writeSet.ownedDirs.has(path.slice(0, path.lastIndexOf("/")))) {
     let bytes;
     try {
-      bytes = readFileSync9(abs);
+      bytes = readFileSync12(abs);
     } catch {
       name(lists.failed, path, path);
       return;
@@ -6218,7 +8269,7 @@ function removeInstalledFile(targetRepo, path, entry, writeSet, lists, name) {
     }
   }
   try {
-    rmSync4(abs);
+    rmSync5(abs);
     name(lists.removed, path, path);
   } catch {
     name(lists.failed, path, path);
@@ -6227,9 +8278,9 @@ function removeInstalledFile(targetRepo, path, entry, writeSet, lists, name) {
 function removeEmptyDir(targetRepo, dir, writeSet, lists, name) {
   if (!writeSet.dirs.has(dir) || symlinkOnPath(targetRepo, dir))
     return;
-  const abs = join10(targetRepo, dir);
+  const abs = join13(targetRepo, dir);
   try {
-    if (!lstatSync2(abs).isDirectory() || readdirSync(abs).length > 0)
+    if (!lstatSync3(abs).isDirectory() || readdirSync(abs).length > 0)
       return;
   } catch {
     return;
@@ -6246,10 +8297,10 @@ function trimAppendedFile(targetRepo, rec, deleteWhenEmpty, rules, lists, name)
     name(lists.leftAlone, `${rel} (a symbolic link \u2014 not followed)`, rel);
     return [];
   }
-  const path = join10(targetRepo, rel);
+  const path = join13(targetRepo, rel);
   let before;
   try {
-    before = readFileSync9(path, "utf-8");
+    before = readFileSync12(path, "utf-8");
   } catch {
     return [];
   }
@@ -6277,10 +8328,10 @@ function handleCredential(options, checked) {
   if (!lexists(dir))
     return { kind: "not-held", dir };
   try {
-    if (lstatSync2(dir).isSymbolicLink())
+    if (lstatSync3(dir).isSymbolicLink())
       return { kind: "failed", dir, reason: "it is a symbolic link" };
-    rmSync4(engagementEnvPath(engagementId, home), { force: true });
-    rmSync4(notThisAccountMarkerPath(engagementId, home), { force: true });
+    rmSync5(engagementEnvPath(engagementId, home), { force: true });
+    rmSync5(notThisAccountMarkerPath(engagementId, home), { force: true });
     if (readdirSync(dir).length === 0)
       rmdirSync(dir);
   } catch (err) {
@@ -6293,16 +8344,16 @@ function filesUnder(root, rel) {
   const walk = (dirRel) => {
     let names;
     try {
-      if (!lstatSync2(join10(root, dirRel)).isDirectory())
+      if (!lstatSync3(join13(root, dirRel)).isDirectory())
         return;
-      names = readdirSync(join10(root, dirRel));
+      names = readdirSync(join13(root, dirRel));
     } catch {
       return;
     }
     for (const entry of names.sort()) {
       const childRel = `${dirRel}/${entry}`;
       try {
-        if (lstatSync2(join10(root, childRel)).isDirectory())
+        if (lstatSync3(join13(root, childRel)).isDirectory())
           walk(childRel);
         else
           out.push(childRel);
@@ -6316,9 +8367,9 @@ function filesUnder(root, rel) {
 }
 function shownPath(path, home) {
   const base = home ?? homedir2();
-  const rel = relative4(base, path);
-  const under = rel !== "" && !rel.startsWith("..") && !rel.startsWith(sep);
-  return `${under ? `~/${rel.split(sep).join("/")}` : path}/`;
+  const rel = relative5(base, path);
+  const under = rel !== "" && !rel.startsWith("..") && !rel.startsWith(sep2);
+  return `${under ? `~/${rel.split(sep2).join("/")}` : path}/`;
 }
 function renderUninstallReport(result, home) {
   if (result.outcome === "refused") {
@@ -6374,8 +8425,8 @@ function renderUninstallReport(result, home) {
 }
 
 // dist/banner-facts.js
-import { readFileSync as readFileSync10 } from "node:fs";
-import { basename as basename3, join as join11, resolve as resolve3 } from "node:path";
+import { readFileSync as readFileSync13 } from "node:fs";
+import { basename as basename3, join as join14, resolve as resolve4 } from "node:path";
 var BRAND_URL = "halfcycle.ai";
 var TAGLINE = [
   "Fewer cycles.",
@@ -6388,7 +8439,7 @@ var TAGLINE_NARROW = [
 ];
 function bundleVersion() {
   try {
-    const pkg = JSON.parse(readFileSync10(join11(BUNDLE_ROOT, "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync13(join14(BUNDLE_ROOT, "package.json"), "utf-8"));
     return typeof pkg.version === "string" ? pkg.version : void 0;
   } catch {
     return void 0;
@@ -6467,7 +8518,7 @@ function openingBannerContent(projectDir, env = process.env, probes = REAL_PROBE
 }
 function safeBasename(dir) {
   try {
-    const name = basename3(resolve3(dir)).trim();
+    const name = basename3(resolve4(dir)).trim();
     return name === "" ? "project" : name;
   } catch {
     return "project";
@@ -6528,6 +8579,12 @@ var USAGE = `  ${HALFCYCLE_COMMAND} [install] [target-repo] [engagement-id] [sel
   ${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_COMMAND} system [--repo <root>]
+         check docs/system.json, the description of your system, and send it to Halfcycle
+  ${DRAW_USAGE}
+         draw the architecture picture, or one phase's plan, from docs/system.json into docs/diagrams/
+  ${PLAN_USAGE}
+         check a phase's plan in docs/phases/ and send it to Halfcycle; --show lists it for the owner
   ${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
@@ -6540,7 +8597,7 @@ var USAGE = `  ${HALFCYCLE_COMMAND} [install] [target-repo] [engagement-id] [sel
 `;
 function isHalfcycleMonorepo(dir) {
   try {
-    const pkg = JSON.parse(readFileSync11(join12(dir, "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync14(join15(dir, "package.json"), "utf-8"));
     return pkg.name === "halfcycle-monorepo";
   } catch {
     return false;
@@ -6548,8 +8605,8 @@ function isHalfcycleMonorepo(dir) {
 }
 function isHomeFolder(dir) {
   try {
-    const target = realpathSync3(dir);
-    const home = realpathSync3(homedir3());
+    const target = realpathSync4(dir);
+    const home = realpathSync4(homedir3());
     return process.platform === "win32" ? target.toLowerCase() === home.toLowerCase() : target === home;
   } catch {
     return false;
@@ -6976,6 +9033,69 @@ ${USAGE}`);
     }
     return;
   }
+  if (cmd === "system") {
+    const repoRoot = flagValue(rest, "--repo") ?? process.cwd();
+    const run = await runSystem(repoRoot, {
+      readCredential: (root) => readRepoCredential(root),
+      listTracked: listTrackedFiles,
+      report: reportSystemDescription
+    });
+    if (run.stdout !== "")
+      process.stdout.write(run.stdout);
+    if (run.stderr !== "")
+      process.stderr.write(run.stderr);
+    process.exitCode = run.exitCode;
+    return;
+  }
+  if (cmd === "draw") {
+    const parsed = parseDrawArgs(rest);
+    if (!parsed.ok) {
+      process.stderr.write(`halfcycle draw: usage: ${DRAW_USAGE}
+`);
+      process.exitCode = 2;
+      return;
+    }
+    const repoRoot = parsed.repoRoot ?? process.cwd();
+    const run = await runDraw(repoRoot, parsed.picture, {
+      readCredential: (root) => readRepoCredential(root),
+      listTracked: listTrackedFiles,
+      report: reportSystemDescription,
+      reportPlan: reportPhasePlan,
+      draw: requestDrawing,
+      write: (root, base, set) => writeDiagramSet(root, base, set)
+    });
+    if (run.stdout !== "")
+      process.stdout.write(run.stdout);
+    if (run.stderr !== "")
+      process.stderr.write(run.stderr);
+    process.exitCode = run.exitCode;
+    return;
+  }
+  if (cmd === "plan") {
+    const parsed = parsePlanArgs(rest);
+    if (!parsed.ok) {
+      process.stderr.write(`halfcycle plan: usage: ${PLAN_USAGE}
+`);
+      process.exitCode = 2;
+      return;
+    }
+    const repoRoot = parsed.repoRoot ?? process.cwd();
+    const run = await runPlan(repoRoot, parsed.phase, parsed.show, {
+      readCredential: (root) => readRepoCredential(root),
+      listTracked: listTrackedFiles,
+      report: reportSystemDescription,
+      reportPlan: reportPhasePlan,
+      pinnedClientVersion: readPinnedClientVersion,
+      recordShown: (engagementId, entry) => writeShownPlan(engagementId, entry),
+      now: () => /* @__PURE__ */ new Date()
+    });
+    if (run.stdout !== "")
+      process.stdout.write(run.stdout);
+    if (run.stderr !== "")
+      process.stderr.write(run.stderr);
+    process.exitCode = run.exitCode;
+    return;
+  }
   if (cmd === "open-phase") {
     const repoRoot = flagValue(rest, "--repo") ?? process.cwd();
     const toProjectScope = rest.includes("--none");
@@ -7020,6 +9140,11 @@ ${USAGE}`);
         process.stdout.write(`[halfcycle] This decision CROSSED: ${opened.decision.blockingFinding}
 `);
       }
+      if (opened.methodUpdated) {
+        process.stdout.write(`[halfcycle] ${openMethodMovedLine(opened.methodUpdated)}
+`);
+        updatePinnedMethodVersion(repoRoot, credential.engagementId, opened.methodUpdated.to);
+      }
       if (opened.stampFailure) {
         process.stderr.write(`halfcycle open-phase: the phase moved, but this machine's copy of it could not be written: ${opened.stampFailure.reason}
 halfcycle open-phase: until ${opened.stampFailure.path} can be written, guard evaluations here are filed under whatever phase that file still names. Fix the file and re-run this command \u2014 re-running it is safe.
@@ -7137,6 +9262,11 @@ halfcycle open-phase: until ${opened.stampFailure.path} can be written, guard ev
         process.stdout.write(`[halfcycle] This close was an OVERRIDE: ${closeDecision.reason}
 `);
       }
+      if (closed.methodUpdated) {
+        process.stdout.write(`[halfcycle] ${closeMethodMovedLine(closed.methodUpdated)}
+`);
+        updatePinnedMethodVersion(repoRoot, credential.engagementId, closed.methodUpdated.to);
+      }
       if (!closed.closeCommit.read) {
         process.stderr.write(`halfcycle close-phase: the commit this phase closed at could not be read (${closed.closeCommit.reason}), so its Build Record shows the commit as not stated.
 `);
@@ -7223,6 +9353,12 @@ function readStatementFlags(argv) {
 function plainOutstandingFinding(finding) {
   return finding.replace(/\(attempted-failed\)/g, "(attempted, and did not finish)");
 }
+function closeMethodMovedLine(moved) {
+  return `Halfcycle's method has a newer version, ${moved.to}. Your next phase will follow it. The phase you just closed stays recorded under ${moved.from}, the version it ran under.`;
+}
+function openMethodMovedLine(moved) {
+  return `This phase follows Halfcycle's newer method version, ${moved.to}. The project was on ${moved.from}.`;
+}
 function writtenLines(written) {
   return `[halfcycle] Build Record written:
   ${written.mdPath}