halfcycle 0.4.6 → 0.4.8

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // dist/bin.js
-import { existsSync as existsSync7, readFileSync as readFileSync13, realpathSync as realpathSync4, 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 join14 } 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,225 +1243,181 @@ 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 DEVICE_AUTH_STATUS = {
-  /** The poll: minted, nobody has acted yet. Keep polling. 200. */
-  PENDING: "pending",
-  /** The poll: approved, and the credential is in this body. Once only. 200. */
-  APPROVED: "approved",
-  /** Confirm: the decision was recorded (approve or decline). 200. */
-  RECORDED: "recorded",
-  /** The human refused at the confirmation page. 400 on the poll. */
-  DECLINED: "declined",
-  /** The code's absolute expiry has passed. 400. */
-  EXPIRED: "expired",
-  /** Never minted, or already spent. 400. */
-  UNKNOWN: "unknown",
-  /** Confirm: neither `approve` nor `decline` was named. Nothing was bound. 400. */
-  INVALID_DECISION: "invalid-decision",
-  /** Confirm: an approval arrived with no signed-in identity. 400. */
-  IDENTITY_REQUIRED: "identity-required",
-  /** This deployment has no `SIGNIN_BASE_URL` / `DEVICE_AUTH_CONFIRM_SECRET`. 503. */
-  NOT_CONFIGURED: "not-configured",
-  /** Confirm: the shared confirmation secret was missing or wrong. 401. */
-  UNAUTHORIZED: "unauthorized",
-  /** Confirm: the code was already approved, declined or claimed. 409. */
-  ALREADY_DECIDED: "already-decided",
-  /**
-   * Confirm: an approval named a signed-in identity whose account has not accepted
-   * the terms of service and privacy policy currently in force. 400.
-   *
-   * NOT BOUND TO THE DEVICE CODE. Unlike every other refusal in this const, this one
-   * says nothing about the code itself — the code is still `pending` after this
-   * response, exactly as it was before the request, so the SAME userCode can be
-   * confirmed again once the caller has recorded acceptance. `deviceConfirmRequestSchema`'s
-   * `acceptTerms` is how a second confirm says it did.
-   */
-  TERMS_REQUIRED: "terms-required"
-};
-var DEVICE_POLL_REFUSALS = [
-  DEVICE_AUTH_STATUS.DECLINED,
-  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),
-  expiresAt: utcIso86013,
-  pollIntervalMs: z7.number().int().positive()
-}).strict();
-var devicePollPendingSchema = z7.object({
-  status: z7.literal(DEVICE_AUTH_STATUS.PENDING),
-  pollIntervalMs: z7.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),
-  expiresAt: utcIso86013
-}).strict();
-var deviceAuthRefusalSchema = z7.object({
-  status: z7.enum([
-    DEVICE_AUTH_STATUS.DECLINED,
-    DEVICE_AUTH_STATUS.EXPIRED,
-    DEVICE_AUTH_STATUS.UNKNOWN,
-    DEVICE_AUTH_STATUS.INVALID_DECISION,
-    DEVICE_AUTH_STATUS.IDENTITY_REQUIRED,
-    DEVICE_AUTH_STATUS.NOT_CONFIGURED,
-    DEVICE_AUTH_STATUS.UNAUTHORIZED,
-    DEVICE_AUTH_STATUS.ALREADY_DECIDED,
-    DEVICE_AUTH_STATUS.TERMS_REQUIRED
-  ]),
-  message: z7.string().min(1)
-}).strict();
-var devicePollResponseSchema = z7.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()
-}).strict();
-var deviceConfirmRecordedSchema = z7.object({
-  status: z7.literal(DEVICE_AUTH_STATUS.RECORDED),
-  accountId: z7.string().min(1).optional()
-}).strict();
-var deviceConfirmResponseSchema = z7.union([
-  deviceConfirmRecordedSchema,
-  deviceAuthRefusalSchema
+var buildTaskStateSchema = z7.enum([
+  "pending",
+  "in-flight",
+  "completed",
+  "failed",
+  "blocked"
 ]);
-var LOOPBACK_REDIRECT_HOST = "127.0.0.1";
-var LOOPBACK_PORT_MIN = 1024;
-var LOOPBACK_PORT_MAX = 65535;
-var LOOPBACK_CALLBACK_PATH = "/halfcycle-cli-callback";
-var LOOPBACK_QUERY_PORT = "loopback_port";
-var LOOPBACK_QUERY_STATE = "loopback_state";
-var LOOPBACK_QUERY_RESULT = "result";
-var LOOPBACK_RESULT = {
-  APPROVED: "approved",
-  DECLINED: "declined"
-};
-var DASHBOARD_URL = "https://app.halfcycle.ai";
-function loopbackVerificationUrl(verificationUrl, target) {
-  let url;
-  try {
-    url = new URL(verificationUrl);
-  } catch {
-    return verificationUrl;
+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.`
+    });
   }
-  url.searchParams.set(LOOPBACK_QUERY_PORT, String(target.port));
-  url.searchParams.set(LOOPBACK_QUERY_STATE, target.state);
-  return url.toString();
-}
-
-// ../events/dist/join-refusal.js
-import { z as z8 } 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)
+  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 joinRefusalSchema = z8.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()
+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();
-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()
+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 ciTokenExchangeResponseSchema = z10.object({
-  token: z10.string(),
-  expiresAt: utcIso8601,
-  engagementId: z10.string()
+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();
-var NO_CREDENTIAL_PLACEHOLDER = "halfcycle:no-credential";
-var NOT_THIS_ACCOUNT_PLACEHOLDER = "halfcycle:not-this-account";
-var UPDATE_CLAUDE_CODE_PLACEHOLDER = "halfcycle:update-claude-code";
-var SWITCH_ACCOUNT_ANSWER = 'answer "s" when asked';
-var NO_CREDENTIAL_SENTENCE = 'Halfcycle is not connected: this machine has no working Halfcycle credential for this project. Run "npx halfcycle" in the project folder to sign in again.';
-var NOT_THIS_ACCOUNT_SENTENCE = `Halfcycle is not connected: this project belongs to another Halfcycle account. To switch, run "npx halfcycle" in this project and ${SWITCH_ACCOUNT_ANSWER}.`;
-var UPDATE_CLAUDE_CODE_SENTENCE = "Halfcycle is not connected: this Claude Code version does not name the server it connects to, so no credential was sent. Update Claude Code, then reopen.";
-var NO_NODE_SENTENCE = "Halfcycle is not connected: Node is not installed, or not on the path this session uses, so nothing here is checked. Install Node, then reopen.";
-var PLACEHOLDER_SENTENCES = Object.freeze({
-  [NO_CREDENTIAL_PLACEHOLDER]: NO_CREDENTIAL_SENTENCE,
-  [NOT_THIS_ACCOUNT_PLACEHOLDER]: NOT_THIS_ACCOUNT_SENTENCE,
-  [UPDATE_CLAUDE_CODE_PLACEHOLDER]: UPDATE_CLAUDE_CODE_SENTENCE
-});
 
-// ../events/dist/project-engagement.js
-import { z as z11 } from "zod";
-var projectIdSchema = z11.string().uuid();
-var projectEngagementRequestSchema = z11.object({
-  derivedName: z11.string()
-}).strict();
+// ../events/dist/phase-plan.js
+import { z as z9 } from "zod";
 
-// ../events/dist/phase-record.js
-import { z as z12 } from "zod";
-var phaseRecordRefusalReasonSchema = z12.enum([
-  "still-open",
-  "reopened",
-  "never-opened",
-  "never-closed",
-  "closed-before-records"
-]);
-var phaseRecordRecordSchema = z12.object({
-  outcome: z12.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"),
-  phase: phaseNameSchema,
-  sequence: z12.number().int().min(1),
-  closedAt: utcIso8601,
-  message: z12.string()
-}).strict();
-var phaseRecordRefusedSchema = wireErrorSchema.extend({
-  outcome: z12.literal("refused"),
-  phase: phaseNameSchema,
-  statusCode: z12.literal(409),
-  error: z12.literal("PhaseRecordRefused"),
-  reason: phaseRecordRefusalReasonSchema
-}).strict();
-var phaseRecordResponseSchema = z12.discriminatedUnion("outcome", [
-  phaseRecordRecordSchema,
-  phaseRecordWithheldSchema,
-  phaseRecordRefusedSchema
-]);
+// ../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 z13 } from "zod";
+import { z as z8 } from "zod";
 var SYSTEM_DESCRIPTION_FORMAT = 1;
 var SYSTEM_PARTS_MAX = 60;
 var SYSTEM_CONNECTIONS_MAX = 400;
@@ -1320,11 +1429,11 @@ 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 = z13.enum(SYSTEM_LANES, {
+var systemLaneSchema = z8.enum(SYSTEM_LANES, {
   error: `must be one of ${SYSTEM_LANES.join(", ")}`
 });
 var SYSTEM_CONNECTION_KINDS = ["call", "event", "write", "external"];
-var systemConnectionKindSchema = z13.enum(SYSTEM_CONNECTION_KINDS, {
+var systemConnectionKindSchema = z8.enum(SYSTEM_CONNECTION_KINDS, {
   error: `must be one of ${SYSTEM_CONNECTION_KINDS.join(", ")}`
 });
 var LINE_SEPARATOR = /[\u2028\u2029]/;
@@ -1333,7 +1442,7 @@ function descriptionText(max) {
     message: "must be one line: it holds a line or paragraph separator"
   });
 }
-var systemPartIdSchema = z13.string().regex(SYSTEM_PART_ID_PATTERN, {
+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) {
@@ -1349,74 +1458,39 @@ var SEGMENT_CHARACTERS = /^[A-Za-z0-9._\-*]*$/;
 function hasForeignCharacter(pattern) {
   return pattern.split("/").some((segment) => !SEGMENT_CHARACTERS.test(segment));
 }
-var systemOwnedPatternSchema = z13.string().max(SYSTEM_OWNED_PATTERN_MAX, { message: `must be at most ${SYSTEM_OWNED_PATTERN_MAX} characters` }).refine((v) => !hasEmptySegment(v), {
+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 = z13.object({
+var systemPartSchema = z8.object({
   id: systemPartIdSchema,
   name: descriptionText(SYSTEM_PART_NAME_MAX),
   description: descriptionText(SYSTEM_PART_DESCRIPTION_MAX),
   lane: systemLaneSchema,
-  slot: z13.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: z13.boolean(),
-  owns: z13.array(systemOwnedPatternSchema).max(SYSTEM_OWNS_MAX, { message: `can list at most ${SYSTEM_OWNS_MAX} paths` })
+  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 = z13.object({
+var systemConnectionSchema = z8.object({
   from: systemPartIdSchema,
   to: systemPartIdSchema,
   kind: systemConnectionKindSchema,
   label: descriptionText(SYSTEM_CONNECTION_LABEL_MAX)
 }).strict();
-var systemDescriptionSchema = z13.object({
-  format: z13.literal(SYSTEM_DESCRIPTION_FORMAT, { error: `must be ${SYSTEM_DESCRIPTION_FORMAT}` }),
-  parts: z13.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: z13.array(systemConnectionSchema).max(SYSTEM_CONNECTIONS_MAX, { message: `can hold at most ${SYSTEM_CONNECTIONS_MAX} connections` })
+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 = z13.object({
-  path: z13.string(),
-  message: z13.string()
+var systemDescriptionProblemSchema = z8.object({
+  path: z8.string(),
+  message: z8.string()
 }).strict();
-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 shapeProblems(raw) {
-  const parsed = systemDescriptionSchema.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: "is not a field a description has" });
-      }
-    } 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}"`;
+  return shapeProblemsOf(systemDescriptionSchema, raw, "is not a field a description has");
 }
 function quoted(value) {
   return typeof value === "string" ? shown(value) : "another part";
@@ -1573,19 +1647,19 @@ function ownerOf(path, description) {
   }
   return best === null ? null : best.id;
 }
-var systemReportRecordedSchema = z13.object({
-  outcome: z13.literal("recorded"),
-  version: z13.number().int().min(1),
+var systemReportRecordedSchema = z8.object({
+  outcome: z8.literal("recorded"),
+  version: z8.number().int().min(1),
   reportedAt: utcIso8601
 }).strict();
-var systemReportRefusedSchema = z13.object({
-  outcome: z13.literal("refused"),
-  problems: z13.array(systemDescriptionProblemSchema).min(1)
+var systemReportRefusedSchema = z8.object({
+  outcome: z8.literal("refused"),
+  problems: z8.array(systemDescriptionProblemSchema).min(1)
 }).strict();
-var systemReportUnavailableSchema = z13.object({
-  outcome: z13.literal("unavailable")
+var systemReportUnavailableSchema = z8.object({
+  outcome: z8.literal("unavailable")
 }).strict();
-var systemReportResultSchema = z13.discriminatedUnion("outcome", [
+var systemReportResultSchema = z8.discriminatedUnion("outcome", [
   systemReportRecordedSchema,
   systemReportRefusedSchema,
   systemReportUnavailableSchema
@@ -1594,10 +1668,19 @@ 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 systemDrawRequestSchema = z13.object({
-  version: z13.number().int().min(1),
-  picture: z13.literal("architecture")
+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++) {
@@ -1625,31 +1708,458 @@ function base64DecodedLength(text) {
   return text.length / 4 * 3 - padding;
 }
 var SYSTEM_PICTURE_THEMES = ["broadsheet", "flightdeck"];
-var systemPictureSchema = z13.object({
-  svg: z13.string().min(1).refine((v) => utf8ByteLength2(v) <= SYSTEM_DRAW_SVG_MAX_BYTES, { message: "the picture is larger than 2 MB" }),
-  png: z13.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" })
+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 = z13.object(Object.fromEntries(SYSTEM_PICTURE_THEMES.map((theme) => [theme, systemPictureSchema]))).strict();
-var systemDrawDrawnSchema = z13.object({
-  outcome: z13.literal("drawn"),
-  mermaid: z13.string().min(1).refine((v) => utf8ByteLength2(v) <= SYSTEM_DRAW_MERMAID_MAX_BYTES, {
+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 = z13.object({
-  outcome: z13.literal("refused"),
-  reason: z13.string().min(1)
+var systemDrawRefusedSchema = z8.object({
+  outcome: z8.literal("refused"),
+  reason: z8.string().min(1)
 }).strict();
-var systemDrawUnavailableSchema = z13.object({
-  outcome: z13.literal("unavailable")
+var systemDrawUnavailableSchema = z8.object({
+  outcome: z8.literal("unavailable")
 }).strict();
-var systemDrawResultSchema = z13.discriminatedUnion("outcome", [
+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",
+  /** The poll: approved, and the credential is in this body. Once only. 200. */
+  APPROVED: "approved",
+  /** Confirm: the decision was recorded (approve or decline). 200. */
+  RECORDED: "recorded",
+  /** The human refused at the confirmation page. 400 on the poll. */
+  DECLINED: "declined",
+  /** The code's absolute expiry has passed. 400. */
+  EXPIRED: "expired",
+  /** Never minted, or already spent. 400. */
+  UNKNOWN: "unknown",
+  /** Confirm: neither `approve` nor `decline` was named. Nothing was bound. 400. */
+  INVALID_DECISION: "invalid-decision",
+  /** Confirm: an approval arrived with no signed-in identity. 400. */
+  IDENTITY_REQUIRED: "identity-required",
+  /** This deployment has no `SIGNIN_BASE_URL` / `DEVICE_AUTH_CONFIRM_SECRET`. 503. */
+  NOT_CONFIGURED: "not-configured",
+  /** Confirm: the shared confirmation secret was missing or wrong. 401. */
+  UNAUTHORIZED: "unauthorized",
+  /** Confirm: the code was already approved, declined or claimed. 409. */
+  ALREADY_DECIDED: "already-decided",
+  /**
+   * Confirm: an approval named a signed-in identity whose account has not accepted
+   * the terms of service and privacy policy currently in force. 400.
+   *
+   * NOT BOUND TO THE DEVICE CODE. Unlike every other refusal in this const, this one
+   * says nothing about the code itself — the code is still `pending` after this
+   * response, exactly as it was before the request, so the SAME userCode can be
+   * confirmed again once the caller has recorded acceptance. `deviceConfirmRequestSchema`'s
+   * `acceptTerms` is how a second confirm says it did.
+   */
+  TERMS_REQUIRED: "terms-required"
+};
+var DEVICE_POLL_REFUSALS = [
+  DEVICE_AUTH_STATUS.DECLINED,
+  DEVICE_AUTH_STATUS.EXPIRED,
+  DEVICE_AUTH_STATUS.UNKNOWN
+];
+var deviceAuthStartResponseSchema = z10.object({
+  deviceCode: z10.string().min(1),
+  userCode: z10.string().min(1),
+  verificationUrl: z10.string().min(1),
+  expiresAt: utcIso86013,
+  pollIntervalMs: z10.number().int().positive()
+}).strict();
+var devicePollPendingSchema = z10.object({
+  status: z10.literal(DEVICE_AUTH_STATUS.PENDING),
+  pollIntervalMs: z10.number().int().positive()
+}).strict();
+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 = z10.object({
+  status: z10.enum([
+    DEVICE_AUTH_STATUS.DECLINED,
+    DEVICE_AUTH_STATUS.EXPIRED,
+    DEVICE_AUTH_STATUS.UNKNOWN,
+    DEVICE_AUTH_STATUS.INVALID_DECISION,
+    DEVICE_AUTH_STATUS.IDENTITY_REQUIRED,
+    DEVICE_AUTH_STATUS.NOT_CONFIGURED,
+    DEVICE_AUTH_STATUS.UNAUTHORIZED,
+    DEVICE_AUTH_STATUS.ALREADY_DECIDED,
+    DEVICE_AUTH_STATUS.TERMS_REQUIRED
+  ]),
+  message: z10.string().min(1)
+}).strict();
+var devicePollResponseSchema = z10.union([
+  devicePollPendingSchema,
+  devicePollApprovedSchema,
+  deviceAuthRefusalSchema
+]);
+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 = z10.object({
+  status: z10.literal(DEVICE_AUTH_STATUS.RECORDED),
+  accountId: z10.string().min(1).optional()
+}).strict();
+var deviceConfirmResponseSchema = z10.union([
+  deviceConfirmRecordedSchema,
+  deviceAuthRefusalSchema
+]);
+var LOOPBACK_REDIRECT_HOST = "127.0.0.1";
+var LOOPBACK_PORT_MIN = 1024;
+var LOOPBACK_PORT_MAX = 65535;
+var LOOPBACK_CALLBACK_PATH = "/halfcycle-cli-callback";
+var LOOPBACK_QUERY_PORT = "loopback_port";
+var LOOPBACK_QUERY_STATE = "loopback_state";
+var LOOPBACK_QUERY_RESULT = "result";
+var LOOPBACK_RESULT = {
+  APPROVED: "approved",
+  DECLINED: "declined"
+};
+var DASHBOARD_URL = "https://app.halfcycle.ai";
+function loopbackVerificationUrl(verificationUrl, target) {
+  let url;
+  try {
+    url = new URL(verificationUrl);
+  } catch {
+    return verificationUrl;
+  }
+  url.searchParams.set(LOOPBACK_QUERY_PORT, String(target.port));
+  url.searchParams.set(LOOPBACK_QUERY_STATE, target.state);
+  return url.toString();
+}
+
+// ../events/dist/join-refusal.js
+import { z as z11 } from "zod";
+var NOT_THIS_ACCOUNT_REASON = "not-this-account";
+var JOIN_REFUSAL_STATUS = 403;
+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 = z11.union([notThisAccountRefusalSchema, wireErrorSchema]);
+function isNotThisAccountRefusal(body) {
+  return typeof body === "object" && body !== null && body.reason === NOT_THIS_ACCOUNT_REASON;
+}
+
+// ../events/dist/project-page.js
+function projectPageUrl(engagementId) {
+  return isEngagementId(engagementId) ? `${DASHBOARD_URL}/${encodeURIComponent(engagementId)}` : void 0;
+}
+function requestAccessSentence(engagementId) {
+  const page = projectPageUrl(engagementId) ?? "this project's page on Halfcycle";
+  return `To ask for access, open ${page} signed in as this account and choose "Request access". Then let the project's owner know, so they can approve it.`;
+}
+
+// ../events/dist/account-identity.js
+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 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 = z13.object({
+  token: z13.string(),
+  expiresAt: utcIso8601,
+  engagementId: z13.string()
+}).strict();
+var NO_CREDENTIAL_PLACEHOLDER = "halfcycle:no-credential";
+var NOT_THIS_ACCOUNT_PLACEHOLDER = "halfcycle:not-this-account";
+var UPDATE_CLAUDE_CODE_PLACEHOLDER = "halfcycle:update-claude-code";
+var SWITCH_ACCOUNT_ANSWER = 'answer "s" when asked';
+var NO_CREDENTIAL_SENTENCE = 'Halfcycle is not connected: this machine has no working Halfcycle credential for this project. Run "npx halfcycle" in the project folder to sign in again.';
+var NOT_THIS_ACCOUNT_SENTENCE = `Halfcycle is not connected: this project belongs to another Halfcycle account. To switch, run "npx halfcycle" in this project and ${SWITCH_ACCOUNT_ANSWER}.`;
+var UPDATE_CLAUDE_CODE_SENTENCE = "Halfcycle is not connected: this Claude Code version does not name the server it connects to, so no credential was sent. Update Claude Code, then reopen.";
+var NO_NODE_SENTENCE = "Halfcycle is not connected: Node is not installed, or not on the path this session uses, so nothing here is checked. Install Node, then reopen.";
+var PLACEHOLDER_SENTENCES = Object.freeze({
+  [NO_CREDENTIAL_PLACEHOLDER]: NO_CREDENTIAL_SENTENCE,
+  [NOT_THIS_ACCOUNT_PLACEHOLDER]: NOT_THIS_ACCOUNT_SENTENCE,
+  [UPDATE_CLAUDE_CODE_PLACEHOLDER]: UPDATE_CLAUDE_CODE_SENTENCE
+});
+
+// ../events/dist/project-engagement.js
+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 z15 } from "zod";
+var phaseRecordRefusalReasonSchema = z15.enum([
+  "still-open",
+  "reopened",
+  "never-opened",
+  "never-closed",
+  "closed-before-records"
+]);
+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 = z15.object({
+  outcome: z15.literal("withheld"),
+  phase: phaseNameSchema,
+  sequence: z15.number().int().min(1),
+  closedAt: utcIso8601,
+  message: z15.string()
+}).strict();
+var phaseRecordRefusedSchema = wireErrorSchema.extend({
+  outcome: z15.literal("refused"),
+  phase: phaseNameSchema,
+  statusCode: z15.literal(409),
+  error: z15.literal("PhaseRecordRefused"),
+  reason: phaseRecordRefusalReasonSchema
+}).strict();
+var phaseRecordResponseSchema = z15.discriminatedUnion("outcome", [
+  phaseRecordRecordSchema,
+  phaseRecordWithheldSchema,
+  phaseRecordRefusedSchema
+]);
+
 // dist/engagement-credential.js
 import { chmodSync as chmodSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import { platform as platform2 } from "node:os";
@@ -2005,17 +2515,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;
@@ -2034,7 +2544,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) {
@@ -2287,11 +2797,6 @@ function nodeFloorProgram(guarded) {
   return `if(+process.versions.node.split('.')[0]<${NODE_FLOOR_MAJOR}){console.error('${NODE_FLOOR_SENTENCE_HEAD}'+process.versions.node);process.exitCode=1}else{${guarded}}`;
 }
 
-// dist/project-page.js
-function projectPageUrl(engagementId) {
-  return isEngagementId(engagementId) ? `${DASHBOARD_URL}/${encodeURIComponent(engagementId)}` : void 0;
-}
-
 // dist/merge-settings.js
 function isHalfcycleCommand(hook, halfcycleCommands) {
   if (typeof hook !== "object" || hook === null)
@@ -2540,7 +3045,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;
@@ -2558,12 +3063,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])
   });
 }
@@ -2576,8 +3081,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 });
 }
@@ -2662,7 +3167,7 @@ function readFileOrNull(path) {
     return null;
   }
 }
-function isPlainObject(value) {
+function isPlainObject2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function readPluginManifest() {
@@ -3010,6 +3515,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",
@@ -3085,6 +3638,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
 };
@@ -3093,6 +3647,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()]
   ];
 }
@@ -3237,6 +3792,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.",
@@ -4851,10 +5425,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)) {
@@ -4987,11 +5561,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"],
@@ -5021,7 +5595,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 {
@@ -5030,7 +5604,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) {
@@ -5413,7 +5987,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"),
@@ -5672,6 +6246,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) {
@@ -5781,13 +6359,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 {
@@ -5876,7 +6459,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;
@@ -5965,8 +6554,8 @@ function unownedPatterns(description, tracked) {
   }
   return found;
 }
-function unownedPatternLines(unowned) {
-  return unowned.map((u) => `halfcycle system: warning: "${u.pattern}" (part "${u.partId}") matches no file in this repository. Correct the path, or remove it if the code moved.
+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) {
@@ -6062,8 +6651,8 @@ async function checkAndReportDescription(repoRoot, deps, verb, beforeSend = () =
     };
   }
   const unowned = unownedPatterns(checked.description, deps.listTracked(repoRoot));
-  const warnings = unowned === null ? "" : unownedPatternLines(unowned);
-  const refusal = beforeSend();
+  const warnings = unowned === null ? "" : unownedPatternLines(unowned, verb);
+  const refusal = beforeSend(checked.description);
   if (refusal !== null)
     return { kind: "stopped", stderr: warnings + refusal };
   let credential;
@@ -6116,17 +6705,351 @@ async function runSystem(repoRoot, deps) {
   }
 }
 
+// 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 mkdirSync7, openSync as openSync2, readFileSync as readFileSync10, readSync, realpathSync as realpathSync3, rmSync as rmSync4 } from "node:fs";
-import { dirname as dirname5, isAbsolute as isAbsolute3, join as join11, relative as relative4, resolve as resolve3, sep } from "node:path";
+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 PICTURE_NAMES = {
-  broadsheet: ARCHITECTURE_NAME,
-  flightdeck: `${ARCHITECTURE_NAME}.flightdeck`
-};
+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]);
@@ -6141,22 +7064,35 @@ var DIAGRAM_FILES = [
   ...SYSTEM_PICTURE_THEMES.map(pngOf),
   "mmd"
 ];
-var FILE_NAMES = Object.fromEntries([
-  ...SYSTEM_PICTURE_THEMES.flatMap((look) => [
-    [svgOf(look), `${PICTURE_NAMES[look]}.svg`],
-    [pngOf(look), `${PICTURE_NAMES[look]}.png`]
-  ]),
-  ["mmd", `${ARCHITECTURE_NAME}.mmd`]
-]);
-var EMBED_IMAGE_REL = `${DIAGRAMS_DIR}/${FILE_NAMES[pngOf(EMBEDDED_LOOK)]}`;
-function diagramPaths(repoRoot) {
+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 = join11(root, DOCS_DIR, DIAGRAMS_DIR);
-  const file = Object.fromEntries(DIAGRAM_FILES.map((which) => [which, join11(dir, FILE_NAMES[which])]));
+  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(which) {
-  return `${DIAGRAM_DIR_REL}/${FILE_NAMES[which]}`;
+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)]),
@@ -6247,7 +7183,7 @@ function readExistingSet(paths) {
     if (!stat.isFile())
       return { ok: false, inTheWay: which, temp: false };
     try {
-      found[which] = readFileSync10(paths.file[which]);
+      found[which] = readFileSync11(paths.file[which]);
     } catch {
       return { ok: false, inTheWay: which, temp: false };
     }
@@ -6293,15 +7229,15 @@ function readExistingSet(paths) {
 function tempPath(paths, which) {
   return `${paths.file[which]}.tmp`;
 }
-function inTheWayLine(which, temp = false) {
-  return `${diagramRel(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 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) {
+function checkPictures(drawn, base) {
   const set = {};
   for (const look of SYSTEM_PICTURE_THEMES) {
     const picture = drawn.pictures[look];
-    const pngFor = diagramRel(pngOf(look));
-    const svgFor = diagramRel(svgOf(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` };
@@ -6337,8 +7273,8 @@ function removeQuietly(path) {
 function sameBytes(a, b) {
   return a !== null && Buffer.from(a).equals(b);
 }
-function writeDiagramSet(repoRoot, set, io = NODE_RECORD_PAIR_IO) {
-  const paths = diagramPaths(repoRoot);
+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 };
@@ -6350,7 +7286,7 @@ function writeDiagramSet(repoRoot, set, io = NODE_RECORD_PAIR_IO) {
   if (changed.length === 0)
     return { kind: "up-to-date" };
   try {
-    mkdirSync7(paths.dir, { recursive: true });
+    mkdirSync8(paths.dir, { recursive: true });
   } catch {
     return { kind: "failed", file: changed[0], removed: [] };
   }
@@ -6411,7 +7347,7 @@ function restore(io, paths, renamed, existing) {
 }
 
 // dist/draw/index.js
-var DRAW_USAGE = `${HALFCYCLE_COMMAND} draw architecture [--repo <root>]`;
+var DRAW_USAGE = `${HALFCYCLE_COMMAND} draw (architecture | phase <phase>) [--repo <root>]`;
 function parseDrawArgs(argv) {
   const positionals = [];
   let repoRoot;
@@ -6429,35 +7365,38 @@ function parseDrawArgs(argv) {
       return { ok: false };
     positionals.push(arg);
   }
-  if (positionals.length !== 1 || positionals[0] !== "architecture")
-    return { ok: false };
-  return { ok: true, repoRoot };
+  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 serviceHost2(serviceUrl) {
+function serviceHost3(serviceUrl) {
   try {
     return new URL(serviceUrl).host;
   } catch {
     return serviceUrl;
   }
 }
-async function requestDrawing(credential, version) {
-  const body = { version, picture: "architecture" };
+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(body)
+      body: JSON.stringify(request)
     });
     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. Nothing was written.`
+      why: `could not reach Halfcycle at ${serviceHost3(credential.serviceUrl)}. Check this machine's connection, then run this again. Nothing was written.`
     };
   }
   let raw = null;
@@ -6495,39 +7434,101 @@ async function requestDrawing(credential, version) {
 var P = "halfcycle draw:";
 var CANNOT_DRAW_YET = `${P} this Halfcycle service cannot draw pictures yet. Nothing was written.
 `;
-function pasteLines(mermaid) {
+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 a document directly under docs/:
+Paste this into ${where}:
 
-![Architecture](${EMBED_IMAGE_REL})
+![${markdownAltText(target.alt)}](${embedImageLink(target.base, target.doc)})
 
 \`\`\`mermaid
 ` + block + "```\n";
 }
-function localRefusal(repoRoot) {
-  const paths = diagramPaths(repoRoot);
+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(read.inTheWay, read.temp)}
+    return `${P} ${inTheWayLine(base, read.inTheWay, read.temp)}
 `;
   return null;
 }
-async function runDraw(repoRoot, deps) {
-  const stage = await checkAndReportDescription(repoRoot, deps, "draw", () => localRefusal(repoRoot));
+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_YET, exitCode: 1 };
+    return { stdout: "", stderr: stage.warnings + CANNOT_DRAW_PHASE_YET, exitCode: 1 };
   const warnings = stage.warnings;
-  const outcome = await deps.draw(stage.credential, stage.version);
+  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 + CANNOT_DRAW_YET, exitCode: 1 };
+    return { stdout: "", stderr: warnings + cannotDrawYet, exitCode: 1 };
   if (outcome.kind === "refused") {
     return {
       stdout: "",
@@ -6539,7 +7540,7 @@ async function runDraw(repoRoot, deps) {
   if (outcome.kind === "unavailable")
     return { stdout: "", stderr: warnings + `${P} ${outcome.why}
 `, exitCode: 1 };
-  const checked = checkPictures(outcome.drawn);
+  const checked = checkPictures(outcome.drawn, base);
   if (!checked.ok) {
     return {
       stdout: "",
@@ -6548,33 +7549,34 @@ async function runDraw(repoRoot, deps) {
       exitCode: 1
     };
   }
-  const result = deps.write(repoRoot, checked.set);
+  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),
+` + pasteLines(outcome.drawn.mermaid, target),
         stderr: warnings,
         exitCode: 0
       };
     case "written":
       return {
-        stdout: `[halfcycle] Wrote ${spokenList(DIAGRAM_FILES_AS_LISTED.map(diagramRel))}.
-` + pasteLines(outcome.drawn.mermaid),
+        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(result.file, result.temp)}
+      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(diagramRel))} 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.`;
+      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} ${diagramRel(result.file)} could not be written. ${lost} Check that you can write to ${DIAGRAM_DIR_REL}, then run this again.
+        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
       };
@@ -6583,13 +7585,14 @@ async function runDraw(repoRoot, deps) {
 }
 
 // dist/cli-contract.js
-var CLI_VERBS = ["install", "check-drift", "build-record", "open-phase", "close-phase", "system", "draw", "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",
@@ -6726,9 +7729,9 @@ function placeholderRefusal(verb, tokens) {
 }
 
 // dist/uninstall.js
-import { lstatSync as lstatSync3, readFileSync as readFileSync11, readdirSync, rmSync as rmSync5, 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 dirname6, join as join12, relative as relative5, sep as sep2 } 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;
@@ -6754,7 +7757,7 @@ function lexists(path) {
 function symlinkOnPath(root, rel) {
   let current = root;
   for (const segment of rel.split("/")) {
-    current = join12(current, segment);
+    current = join13(current, segment);
     try {
       if (lstatSync3(current).isSymbolicLink())
         return true;
@@ -6764,7 +7767,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) {
@@ -6776,13 +7779,13 @@ function readMergedJson(targetRepo, rule) {
   const { rel } = rule;
   if (symlinkOnPath(targetRepo, rel))
     return { state: "symlink" };
-  const path = join12(targetRepo, rel);
+  const path = join13(targetRepo, rel);
   if (!lexists(path))
     return { state: "absent" };
   let text;
   let value;
   try {
-    text = readFileSync11(path, "utf-8");
+    text = readFileSync12(path, "utf-8");
   } catch {
     text = "";
   }
@@ -6791,7 +7794,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" };
@@ -6799,15 +7802,15 @@ function readMergedJson(targetRepo, rule) {
 }
 function validate(options, rules) {
   const { targetRepo, removeCredential, home } = options;
-  const manifestPath = join12(targetRepo, INSTALL_MANIFEST_REL);
-  const pinPath = join12(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(readFileSync11(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.`);
@@ -6817,8 +7820,8 @@ function validate(options, rules) {
   let pinReadable = true;
   if (lexists(pinPath)) {
     try {
-      const pin = JSON.parse(readFileSync11(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;
@@ -6841,7 +7844,7 @@ 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 = join12(home ?? homedir2(), HALFCYCLE_DIR_NAME, ENGAGEMENTS_DIR_NAME);
+      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.`);
       }
@@ -6865,13 +7868,13 @@ function mergedFileRules(writeSet) {
 function writeBack(targetRepo, rel, current, next, lists, name) {
   if (next === current)
     return;
-  const path = join12(targetRepo, rel);
+  const path = join13(targetRepo, rel);
   try {
     if (next === null) {
       rmSync5(path);
       name(lists.removed, rel, rel);
     } else {
-      writeFileSync6(path, next, "utf-8");
+      writeFileSync7(path, next, "utf-8");
       name(lists.restored, rel, rel);
     }
   } catch {
@@ -6883,7 +7886,7 @@ function noRecord(targetRepo, writeSet) {
   const claim = (rel, header, lines) => {
     let text;
     try {
-      text = symlinkOnPath(targetRepo, rel) ? "" : readFileSync11(join12(targetRepo, rel), "utf-8");
+      text = symlinkOnPath(targetRepo, rel) ? "" : readFileSync12(join13(targetRepo, rel), "utf-8");
     } catch {
       text = "";
     }
@@ -6912,16 +7915,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 });
       }
@@ -6931,7 +7934,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;
@@ -6942,7 +7945,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)) {
@@ -6977,7 +7980,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--) {
@@ -7009,7 +8012,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;
@@ -7109,7 +8112,7 @@ function lastOccurrence(text, block) {
 }
 function coveredPathExists(targetRepo, line) {
   const path = line.trim().replace(/^\//, "").replace(/\/$/, "");
-  return path !== "" && lexists(join12(targetRepo, path));
+  return path !== "" && lexists(join13(targetRepo, path));
 }
 function uninstall(options) {
   const result = {
@@ -7189,7 +8192,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(join12(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);
@@ -7197,7 +8200,7 @@ function uninstall(options) {
   if (result.failed.length === 0 && !credentialFailed) {
     removeInstalledFile(targetRepo, BUNDLE_PIN_REL, recorded.get(BUNDLE_PIN_REL), writeSet, result, name);
     try {
-      rmSync5(join12(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);
@@ -7232,7 +8235,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(join12(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);
   }
 }
@@ -7245,7 +8248,7 @@ 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 = join12(targetRepo, path);
+  const abs = join13(targetRepo, path);
   let isFile;
   try {
     isFile = lstatSync3(abs).isFile();
@@ -7259,7 +8262,7 @@ function removeInstalledFile(targetRepo, path, entry, writeSet, lists, name) {
   if (!writeSet.ownedDirs.has(path.slice(0, path.lastIndexOf("/")))) {
     let bytes;
     try {
-      bytes = readFileSync11(abs);
+      bytes = readFileSync12(abs);
     } catch {
       name(lists.failed, path, path);
       return;
@@ -7279,7 +8282,7 @@ 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 = join12(targetRepo, dir);
+  const abs = join13(targetRepo, dir);
   try {
     if (!lstatSync3(abs).isDirectory() || readdirSync(abs).length > 0)
       return;
@@ -7298,10 +8301,10 @@ function trimAppendedFile(targetRepo, rec, deleteWhenEmpty, rules, lists, name)
     name(lists.leftAlone, `${rel} (a symbolic link \u2014 not followed)`, rel);
     return [];
   }
-  const path = join12(targetRepo, rel);
+  const path = join13(targetRepo, rel);
   let before;
   try {
-    before = readFileSync11(path, "utf-8");
+    before = readFileSync12(path, "utf-8");
   } catch {
     return [];
   }
@@ -7345,16 +8348,16 @@ function filesUnder(root, rel) {
   const walk = (dirRel) => {
     let names;
     try {
-      if (!lstatSync3(join12(root, dirRel)).isDirectory())
+      if (!lstatSync3(join13(root, dirRel)).isDirectory())
         return;
-      names = readdirSync(join12(root, dirRel));
+      names = readdirSync(join13(root, dirRel));
     } catch {
       return;
     }
     for (const entry of names.sort()) {
       const childRel = `${dirRel}/${entry}`;
       try {
-        if (lstatSync3(join12(root, childRel)).isDirectory())
+        if (lstatSync3(join13(root, childRel)).isDirectory())
           walk(childRel);
         else
           out.push(childRel);
@@ -7426,8 +8429,8 @@ function renderUninstallReport(result, home) {
 }
 
 // dist/banner-facts.js
-import { readFileSync as readFileSync12 } from "node:fs";
-import { basename as basename3, join as join13, resolve as resolve4 } 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.",
@@ -7440,7 +8443,7 @@ var TAGLINE_NARROW = [
 ];
 function bundleVersion() {
   try {
-    const pkg = JSON.parse(readFileSync12(join13(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;
@@ -7583,7 +8586,9 @@ var USAGE = `  ${HALFCYCLE_COMMAND} [install] [target-repo] [engagement-id] [sel
   ${HALFCYCLE_COMMAND} system [--repo <root>]
          check docs/system.json, the description of your system, and send it to Halfcycle
   ${DRAW_USAGE}
-         draw the architecture pictures from docs/system.json into docs/diagrams/
+         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
@@ -7596,7 +8601,7 @@ var USAGE = `  ${HALFCYCLE_COMMAND} [install] [target-repo] [engagement-id] [sel
 `;
 function isHalfcycleMonorepo(dir) {
   try {
-    const pkg = JSON.parse(readFileSync13(join14(dir, "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync14(join15(dir, "package.json"), "utf-8"));
     return pkg.name === "halfcycle-monorepo";
   } catch {
     return false;
@@ -7885,7 +8890,7 @@ ${PROJECT_RESET_LINE}
 `);
       }
       if (credential === void 0 && notThisAccountMessage !== void 0) {
-        process.stdout.write(`[halfcycle] ${notThisAccountMessage} Your work carries on exactly as it would without Halfcycle: no edit is evaluated, and nothing you do here is reported as having passed. Ask the project's owner for view access. ${identitySwitchRemedy(void 0, isInteractiveRun())}
+        process.stdout.write(`[halfcycle] ${notThisAccountMessage} Your work carries on exactly as it would without Halfcycle: no edit is evaluated, and nothing you do here is reported as having passed. ${requestAccessSentence(engagementId)} ${identitySwitchRemedy(void 0, isInteractiveRun())}
 `);
       }
       reportClaudeCodeVersion(verbose);
@@ -8055,12 +9060,38 @@ ${USAGE}`);
       return;
     }
     const repoRoot = parsed.repoRoot ?? process.cwd();
-    const run = await runDraw(repoRoot, {
+    const run = await runDraw(repoRoot, parsed.picture, {
       readCredential: (root) => readRepoCredential(root),
       listTracked: listTrackedFiles,
       report: reportSystemDescription,
+      reportPlan: reportPhasePlan,
       draw: requestDrawing,
-      write: (root, set) => writeDiagramSet(root, set)
+      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);
@@ -8113,6 +9144,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.
@@ -8230,6 +9266,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.
 `);
@@ -8316,6 +9357,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}