halfcycle 0.4.6 → 0.4.8

package/dist/close-phase.d.ts

@@ -38,7 +38,7 @@
  * note. The service freezes both into the phase's Build Record; the caller fetches
  * that record afterwards (`build-record/obtain.ts`).
  */
-import { type AcceptanceOutcome, type PhaseCloseDecision } from '@halfcycle/events';
+import { type AcceptanceOutcome, type MethodUpdate, type PhaseCloseDecision } from '@halfcycle/events';
 import { type PhaseStampFailure, type RepoCredential } from './open-phase.js';
 /**
  * Whether the commit this phase closed at could be read, and if so the full hash
@@ -76,6 +76,13 @@ export interface ClosedPhase {
     stampFailure: PhaseStampFailure | null;
     /** The commit sent with the close, or why none could be read. */
     closeCommit: CloseCommitOutcome;
+    /**
+     * The method version this close moved the project to (`existing-projects-carry-on`
+     * AC2), or `null` when it did not move. An older control's answer carries no
+     * field at all, which reads the same as `null` here — this CLI then prints
+     * and writes nothing about a move, exactly as it did before this field existed.
+     */
+    methodUpdated: MethodUpdate | null;
 }
 /**
  * Read the full HEAD commit of the NAMED repository, before the close is sent.

package/dist/close-phase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"close-phase.d.ts","sourceRoot":"","sources":["../src/close-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAmB,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG/F;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElG;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,4EAA4E;AAC5E,eAAO,MAAM,aAAa,EAAE,gBAAkE,CAAC;AAE/F,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvC,iEAAiE;IACjE,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,kBAAkB,CA4BhF;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAExB,MAAM,EAAE,MAAM;IAE9B;;;;;OAKG;aACa,OAAO,CAAC,EAAE,MAAM;IAChC;;;;;;;;;;OAUG;aACa,IAAI,CAAC,EAAE,MAAM;gBApBb,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM;IACf;;;;;OAKG;IACa,OAAO,CAAC,EAAE,MAAM,YAAA;IAChC;;;;;;;;;;OAUG;IACa,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,kBAAkB,EACzB,IAAI,CAAC,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,GAAE,gBAAgC,GACvC,OAAO,CAAC,WAAW,CAAC,CAyEtB"}
+{"version":3,"file":"close-phase.d.ts","sourceRoot":"","sources":["../src/close-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAmB,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG/F;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElG;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,4EAA4E;AAC5E,eAAO,MAAM,aAAa,EAAE,gBAAkE,CAAC;AAE/F,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvC,iEAAiE;IACjE,WAAW,EAAE,kBAAkB,CAAC;IAChC;;;;;OAKG;IACH,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;CACpC;AAcD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,kBAAkB,CA4BhF;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAExB,MAAM,EAAE,MAAM;IAE9B;;;;;OAKG;aACa,OAAO,CAAC,EAAE,MAAM;IAChC;;;;;;;;;;OAUG;aACa,IAAI,CAAC,EAAE,MAAM;gBApBb,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM;IACf;;;;;OAKG;IACa,OAAO,CAAC,EAAE,MAAM,YAAA;IAChC;;;;;;;;;;OAUG;IACa,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,kBAAkB,EACzB,IAAI,CAAC,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,GAAE,gBAAgC,GACvC,OAAO,CAAC,WAAW,CAAC,CAiFtB"}

package/dist/draw/index.d.ts

@@ -1,17 +1,27 @@
 /**
  * The client half of `npx halfcycle@latest draw architecture` (System view · E1,
- * feature `diagram-files-for-docs`, AC1, AC4, AC5, AC6 and AC8's missing route).
+ * feature `diagram-files-for-docs`, AC1, AC4, AC5, AC6 and AC8's missing route) and of
+ * `draw phase <phase>` (System view · E2, feature `draw-phase-picture`, AC1 and AC5).
  *
- * THE ORDER IS THE SPEC'S. (1) read and check `docs/system.json`; (2) report it and
- * get its version — both through `system`'s own first stage,
- * `checkAndReportDescription` (`../system-report.ts`), never a copy of it; (3) ask the
- * service to draw that version; (4) check all five files, every look's picture and the
- * Mermaid, then write them; (5) print the Markdown, whose image line is the embedded
- * look's PNG (`EMBED_IMAGE_REL`, `./write.ts`, composed from the same table as that
- * file's path). The place and the files already there are checked on the machine
- * before anything is sent, and again just before writing, so a refusal this command
- * can make locally never costs a request, and a change made while it waited is still
- * seen.
+ * THE ORDER IS THE SPEC'S. (1) read and check `docs/system.json`; for a phase, read and
+ * check its plan in the same stage's `beforeSend`, through `plan`'s own
+ * `readAndCheckPlan` (`../plan.ts`), never a copy of it; then the place and the files in
+ * the way; (2) report the description and get its version — both through `system`'s
+ * own first stage, `checkAndReportDescription` (`../system-report.ts`), never a copy of
+ * it; for a phase, then report the plan through `DrawDeps.reportPlan`, `plan`'s own
+ * request (`reportPhasePlan`), sending the very plan `beforeSend` checked, never a
+ * second read of the file; (3) ask the service to draw that version; (4) check all five
+ * files, every look's picture and the Mermaid, then write them; (5) print the
+ * Markdown, whose image line is the embedded look's PNG (`embedImageLink`,
+ * `./write.ts`, composed from the same table as that file's path). The place and the
+ * files already there are checked on the machine before anything is sent, and again
+ * just before writing, so a refusal this command can make locally never costs a
+ * request, and a change made while it waited is still seen.
+ *
+ * A PHASE'S FILES. The base name is `phaseDiagramBase(phase)`, `renderPhaseSegment`'s
+ * segment. A phase that is not a valid identity is refused naming it, before anything
+ * is read; so is one whose base name ends in the Flight Deck word, in any case, whose
+ * Broadsheet files would take another phase's Flight Deck names.
  *
  * ONE RESPONSE-HANDLING RULE, the Build Record path's. A body that parses under
  * `systemDrawResultSchema` (`@halfcycle/events`, the one home of the shape) is
@@ -19,33 +29,49 @@
  * this POST means it predates drawing — asked of `isMissingRoute`
  * (`../missing-route.ts`), the one predicate, never a copy of its expression; a
  * missing report route says the same, because either way this service cannot draw.
- * Anything else is reported by its status and the service's own sentence.
+ * For a phase, the plan route and the draw route's phase arm ship in one service
+ * release, so a missing plan route is the one signal that this service cannot draw
+ * phase pictures, and the draw route is then never asked. Anything else is reported by
+ * its status and the service's own sentence.
  *
  * NO BYTE OF THE RESPONSE DECIDES A PATH (INV-023): the response gives contents only;
- * where they go is `./write.ts`'s constants.
+ * where they go is `./write.ts`'s constants and the base name this module chose from
+ * the arguments.
  *
- * WHAT LEAVES THE MACHINE. The checked description (through the shared stage), then
- * only `{ version, picture: 'architecture' }`.
+ * WHAT LEAVES THE MACHINE. The checked description (through the shared stage); for a
+ * phase, the checked plan (through `plan`'s request); then only the draw request,
+ * `{ version, picture: 'architecture' }` or `{ picture: 'phase', phase, planVersion }`.
  *
  * INV-001: Node builtins, the global `fetch`, `@halfcycle/events` and `@halfcycle/core`
  * only. SHIPS TO CLIENT DISK inside the CLI: every string here is a sentence a person
  * reads, so none names an internal register, route or setting; no comment sits beside
  * an object member.
  */
-import { type SystemDrawDrawn } from '@halfcycle/events';
+import { type SystemDrawDrawn, type SystemDrawRequest } from '@halfcycle/events';
 import type { RepoCredential } from '../open-phase.js';
+import { type PlanDeps } from '../plan.js';
 import { type SystemDeps, type SystemRun } from '../system-report.js';
-import { type DiagramSet, type DiagramWriteResult } from './write.js';
-export { ARCHITECTURE_NAME, DIAGRAM_DIR_REL, DIAGRAM_FILES, DIAGRAM_MARKER_LINE, EMBED_IMAGE_REL, EMBEDDED_LOOK, PICTURE_NAMES, checkPictures, diagramRel, pngOf, svgOf, diagramPaths, writeDiagramSet, } from './write.js';
-/** The usage line, printed for any argument but `architecture`. */
-export declare const DRAW_USAGE = "npx halfcycle@latest draw architecture [--repo <root>]";
+import { type DiagramBaseName, type DiagramSet, type DiagramWriteResult, type EmbeddingDoc } from './write.js';
+export { ARCHITECTURE_BASE, ARCHITECTURE_NAME, DIAGRAM_DIR_REL, DIAGRAM_FILES, DIAGRAM_MARKER_LINE, EMBEDDED_LOOK, baseTakesFlightDeckNames, checkPictures, diagramRel, embedImageLink, embedImageName, markdownLinkName, phaseDiagramBase, pictureNames, pngOf, svgOf, diagramPaths, writeDiagramSet, type DiagramBaseName, } from './write.js';
+/** The usage line, printed for anything but `architecture` or `phase <phase>`. */
+export declare const DRAW_USAGE = "npx halfcycle@latest draw (architecture | phase <phase>) [--repo <root>]";
+/** Which picture: the whole system's, or one phase's plan on it. */
+export type DrawPicture = {
+    kind: 'architecture';
+} | {
+    kind: 'phase';
+    phase: string;
+};
 /**
- * What the arguments after `draw` came to: the repository root to work in, or usage.
- * Exactly one positional, `architecture`, and at most one `--repo <root>`; anything
- * else, including no argument, is usage. A phase name never reaches here in E1.
+ * What the arguments after `draw` came to: the picture and the repository root to work
+ * in, or usage. `architecture` alone, or `phase` followed by exactly one phase, plus at
+ * most one `--repo <root>`; anything else, including no argument and `phase` with no
+ * name, is usage. The phase is not checked here: a name that cannot be a phase is the
+ * verb's to refuse, by name.
  */
 export type DrawArgs = {
     ok: true;
+    picture: DrawPicture;
     repoRoot: string | undefined;
 } | {
     ok: false;
@@ -72,20 +98,38 @@ export type DrawOutcome = {
 /** The address the drawing is asked of: the engagement is one path segment, encoded once. */
 export declare function systemDrawUrl(credential: RepoCredential): string;
 /**
- * Ask the service to draw `version`. Never throws: the network, the service and an
- * answer this CLI cannot read are each an outcome the caller prints.
+ * Ask the service to draw the picture `request` names. Never throws: the network, the
+ * service and an answer this CLI cannot read are each an outcome the caller prints.
+ */
+export declare function requestDrawing(credential: RepoCredential, request: SystemDrawRequest): Promise<DrawOutcome>;
+/**
+ * The pieces `runDraw` reaches outside itself through; replaced in tests. `reportPlan`
+ * is `plan`'s own request, used only for a phase.
  */
-export declare function requestDrawing(credential: RepoCredential, version: number): Promise<DrawOutcome>;
-/** The pieces `runDraw` reaches outside itself through; replaced in tests. */
 export interface DrawDeps extends SystemDeps {
-    readonly draw: (credential: RepoCredential, version: number) => Promise<DrawOutcome>;
-    readonly write: (repoRoot: string, set: DiagramSet) => DiagramWriteResult;
+    readonly reportPlan: PlanDeps['reportPlan'];
+    readonly draw: (credential: RepoCredential, request: SystemDrawRequest) => Promise<DrawOutcome>;
+    readonly write: (repoRoot: string, base: DiagramBaseName, set: DiagramSet) => DiagramWriteResult;
 }
-/** The Markdown to paste into a document directly under `docs/`, and the line before it. */
-export declare function pasteLines(mermaid: string): string;
+/**
+ * What a picture is pasted as: the document it goes in, and the image's alt text.
+ * The architecture's goes directly under `docs/`; a phase's in its own document in
+ * `docs/phases/`.
+ */
+export type PasteTarget = {
+    doc: EmbeddingDoc;
+    alt: string;
+    base: DiagramBaseName;
+};
+/** The architecture's paste target. */
+export declare const ARCHITECTURE_PASTE: PasteTarget;
+/** A phase's paste target: `Phase <name>`, in `docs/phases/`. */
+export declare function phasePaste(phase: string): PasteTarget;
+/** The Markdown to paste into the document `target` names, and the line before it. */
+export declare function pasteLines(mermaid: string, target: PasteTarget): string;
 /**
  * The whole verb, in the order the module header gives. Exit 0 only when the five
  * files are written or already up to date and the Markdown is printed.
  */
-export declare function runDraw(repoRoot: string, deps: DrawDeps): Promise<SystemRun>;
+export declare function runDraw(repoRoot: string, picture: DrawPicture, deps: DrawDeps): Promise<SystemRun>;
 //# sourceMappingURL=index.d.ts.map

package/dist/draw/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/draw/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAkD,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAA6B,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACjG,OAAO,EAWL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACxB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,aAAa,EACb,aAAa,EACb,aAAa,EACb,UAAU,EACV,KAAK,EACL,KAAK,EACL,YAAY,EACZ,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,mEAAmE;AACnE,eAAO,MAAM,UAAU,2DAA2D,CAAC;AAEnF;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AAElF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,CAiB/D;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,6FAA6F;AAC7F,wBAAgB,aAAa,CAAC,UAAU,EAAE,cAAc,GAAG,MAAM,CAEhE;AAUD;;;GAGG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAmDtG;AAED,8EAA8E;AAC9E,MAAM,WAAW,QAAS,SAAQ,UAAU;IAC1C,QAAQ,CAAC,IAAI,EAAE,CAAC,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACrF,QAAQ,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,KAAK,kBAAkB,CAAC;CAC3E;AAMD,4FAA4F;AAC5F,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASlD;AAYD;;;GAGG;AACH,wBAAsB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,CAAC,CAiElF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/draw/index.ts"],"names":[],"mappings":"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"}

package/dist/draw/write.d.ts

@@ -1,22 +1,30 @@
 /**
- * The architecture pictures writer — what `draw architecture` writes into the person's
- * repository (System view · E1, feature `diagram-files-for-docs`, AC4, AC5, AC6 and
- * the "someone else's file in the way" behaviour).
+ * The pictures writer — what `draw architecture` and `draw phase` write into the
+ * person's repository (System view · E1, feature `diagram-files-for-docs`, AC4, AC5,
+ * AC6 and the "someone else's file in the way" behaviour; widened to a base name by
+ * E2, feature `draw-phase-picture` AC5).
  *
  * NO BYTE OF THE RESPONSE DECIDES A PATH (INV-023). Every path here is composed from
  * `repoRoot` (the caller's `--repo` or the working directory), the constant directory
- * `docs/diagrams` and the constant name `architecture` with a constant extension. The
+ * `docs/diagrams` and a BASE NAME with a constant extension. A base name is a
+ * `DiagramBaseName`, and only two things make one: `ARCHITECTURE_BASE` (the constant
+ * `architecture`) and `phaseDiagramBase(phase)` (`renderPhaseSegment`'s segment, the
+ * one home of a phase's file segment). The type is branded, so a string from anywhere
+ * else, a response included, does not compile where a base name is asked for. The
  * response contributes file CONTENTS only; nothing in it is ever joined, resolved or
- * compared as a path. `DiagramPaths` is built by `diagramPaths(repoRoot)` alone.
+ * compared as a path. `DiagramPaths` is built by `diagramPaths(repoRoot, base)` alone.
+ *
+ * Every rule below is stated for the architecture's names, which are the base name
+ * `architecture`; a phase's are the same with its base name in their place.
  *
  * FIVE FILES, ONE TABLE. Each look in `SYSTEM_PICTURE_THEMES` (`@halfcycle/events`, the
  * one list of looks) has a PNG and an SVG; the Mermaid is one file, because Mermaid has
- * no look. A look selects its file name from `PICTURE_NAMES`, a constant typed against
+ * no look. A look selects its file name from `pictureNames(base)`, a table typed against
  * `SystemPictureTheme`, so a look the list does not hold has no name and the compiler
  * refuses a look the table forgets. The looks are iterated from the list, never from
  * the response's keys: the strict result schema already refused any other key, and
  * this module would not read one if it came. Which look documents embed is
- * `EMBEDDED_LOOK`, and only there: the printed image line (`EMBED_IMAGE_REL`) is
+ * `EMBEDDED_LOOK`, and only there: the printed image line (`embedImageLink`) is
  * composed from the same file-name table as that look's path, so the line and the file
  * cannot name different pictures.
  *
@@ -79,18 +87,42 @@
  * DISK inside the CLI: every string here is a sentence a person reads, and no comment
  * sits beside an object member.
  */
-import { type SystemDrawDrawn, type SystemPictureTheme } from '@halfcycle/events';
+import { type PhaseIdentity, type SystemDrawDrawn, type SystemPictureTheme } from '@halfcycle/events';
 import { type RecordPairIo } from '../build-record/write.js';
 /** The one directory the pictures go in, relative to the repository root, `/`-separated. */
 export declare const DIAGRAM_DIR_REL = "docs/diagrams";
-/** The one picture name E1 draws; also the Mermaid file's name. */
+/** The architecture picture's name; also its Mermaid file's name. */
 export declare const ARCHITECTURE_NAME = "architecture";
+declare const diagramBaseBrand: unique symbol;
+/**
+ * The name a set of five files is built from. Branded so only the two makers below
+ * produce one: a plain string, a response's included, is a compile error where a base
+ * name is asked for (INV-023).
+ */
+export type DiagramBaseName = string & {
+    readonly [diagramBaseBrand]: true;
+};
+/** The architecture's base name. */
+export declare const ARCHITECTURE_BASE: DiagramBaseName;
+/**
+ * A phase's base name: `renderPhaseSegment(phase)`, so `notifications` gives
+ * `phase-notifications`. Throws on an invalid identity, as that function does; the
+ * verb checks the identity first and reports it rather than throwing.
+ */
+export declare function phaseDiagramBase(phase: PhaseIdentity): DiagramBaseName;
+/**
+ * Would this base name's Broadsheet files take another set's Flight Deck names?
+ * `phase-a.flightdeck.png` is phase `a`'s Flight Deck picture, so a base name ending in
+ * the Flight Deck word, in any case (a case-insensitive file system would collide
+ * too), is refused before anything is sent.
+ */
+export declare function baseTakesFlightDeckNames(base: DiagramBaseName): boolean;
 /**
- * Each look's file name, before its extension: Broadsheet takes the bare name, Flight
- * Deck the name with its look after it. Typed against the one list of looks, so the
- * table cannot hold a look the list does not, or miss one it does.
+ * Each look's file name, before its extension: Broadsheet takes the bare base name,
+ * Flight Deck the base name with its look after it. Typed against the one list of
+ * looks, so the table cannot hold a look the list does not, or miss one it does.
  */
-export declare const PICTURE_NAMES: Readonly<Record<SystemPictureTheme, string>>;
+export declare function pictureNames(base: DiagramBaseName): Readonly<Record<SystemPictureTheme, string>>;
 /**
  * The look documents embed, and the only place that choice is made. Its PNG is the
  * printed image line, and its SVG is the one the Mermaid file sits beside.
@@ -116,19 +148,36 @@ export declare function pngOf(look: SystemPictureTheme): PictureFile;
  */
 export declare const DIAGRAM_FILES: readonly DiagramFile[];
 /**
- * The embedded picture as a document directly under `docs/` names it:
- * `diagrams/architecture.png`. Composed from the same table as that file's path.
+ * The embedded picture's file name in `docs/diagrams`: `architecture.png`. Composed
+ * from the same table as that file's path, so the printed image line and the file
+ * cannot name different pictures.
+ */
+export declare function embedImageName(base: DiagramBaseName): string;
+/**
+ * Where the document the picture is pasted into sits: directly under `docs/` (the
+ * architecture's), or in `docs/phases/` (a phase's).
+ */
+export type EmbeddingDoc = 'docs' | 'docs/phases';
+/**
+ * A file name as a Markdown link target: percent-encoded (`encodeURIComponent`), and
+ * `(` and `)` too, which would otherwise end the link.
+ */
+export declare function markdownLinkName(name: string): string;
+/**
+ * The embedded picture as a document at `doc` links it: `diagrams/architecture.png`
+ * from `docs/`, `../diagrams/phase-notifications.png` from `docs/phases/`. The file
+ * name is the one `embedImageName` gives, encoded for a link.
  */
-export declare const EMBED_IMAGE_REL: string;
+export declare function embedImageLink(base: DiagramBaseName, doc: EmbeddingDoc): string;
 /** The fixed paths, composed from `repoRoot` and constants only. */
 export interface DiagramPaths {
     readonly repoRoot: string;
     readonly dir: string;
     readonly file: Readonly<Record<DiagramFile, string>>;
 }
-export declare function diagramPaths(repoRoot: string): DiagramPaths;
+export declare function diagramPaths(repoRoot: string, base: DiagramBaseName): DiagramPaths;
 /** A file's place as a person finds it: `docs/diagrams/architecture.svg`. */
-export declare function diagramRel(which: DiagramFile): string;
+export declare function diagramRel(base: DiagramBaseName, which: DiagramFile): string;
 /**
  * The five files in the order a person reads them: each look's PNG then its SVG, then
  * the Mermaid file.
@@ -178,7 +227,7 @@ export type ExistingRead = {
  */
 export declare function readExistingSet(paths: DiagramPaths): ExistingRead;
 /** The sentence for a file in the way, or for the temporary file beside it when `temp`. */
-export declare function inTheWayLine(which: DiagramFile, temp?: boolean): string;
+export declare function inTheWayLine(base: DiagramBaseName, which: DiagramFile, temp?: boolean): string;
 /** The five files as bytes, checked and ready to write. */
 export type DiagramSet = Readonly<Record<DiagramFile, Uint8Array>>;
 /** What checking the drawn pictures came to: the bytes, or what was wrong, in plain words. */
@@ -198,7 +247,7 @@ export type PictureCheck = {
  * Each sentence names the file the bad bytes were for, so a person reading it knows
  * which picture was wrong.
  */
-export declare function checkPictures(drawn: SystemDrawDrawn): PictureCheck;
+export declare function checkPictures(drawn: SystemDrawDrawn, base: DiagramBaseName): PictureCheck;
 /**
  * What writing came to. `up-to-date`: every file already held these bytes and none
  * was touched. `written`: the files in `changed` were replaced or created.
@@ -228,5 +277,6 @@ export type DiagramWriteResult = {
  * header states. Never throws for a file-system failure: it is a `failed` result,
  * and the set on disk is the old one.
  */
-export declare function writeDiagramSet(repoRoot: string, set: DiagramSet, io?: RecordPairIo): DiagramWriteResult;
+export declare function writeDiagramSet(repoRoot: string, base: DiagramBaseName, set: DiagramSet, io?: RecordPairIo): DiagramWriteResult;
+export {};
 //# sourceMappingURL=write.d.ts.map

package/dist/draw/write.d.ts.map

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

package/dist/index.js

@@ -118,6 +118,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) {
@@ -146,6 +147,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("|"),
@@ -227,6 +235,9 @@ function quoteForShell(value) {
 }
 var HALFCYCLE_COMMAND = "npx halfcycle@latest";
 
+// ../core/dist/release-version.js
+var RELEASE_VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+
 // ../events/dist/result.js
 import { z as z2 } from "zod";
 var firedGuardSchema = z2.object({
@@ -293,15 +304,12 @@ 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"]);
@@ -478,6 +486,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");
@@ -581,9 +592,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(),
@@ -1014,6 +1027,11 @@ var deviceConfirmResponseSchema = z6.union([
 ]);
 var DASHBOARD_URL = "https://app.halfcycle.ai";
 
+// ../events/dist/project-page.js
+function projectPageUrl(engagementId) {
+  return isEngagementId(engagementId) ? `${DASHBOARD_URL}/${encodeURIComponent(engagementId)}` : void 0;
+}
+
 // ../events/dist/credential-wire.js
 import { z as z7 } from "zod";
 var engagementCredentialResponseSchema = z7.object({
@@ -1652,11 +1670,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)
@@ -2383,6 +2396,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",
@@ -2458,6 +2519,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
 };
@@ -2466,6 +2528,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()]
   ];
 }
@@ -3859,7 +3922,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"),