@forwardimpact/libharness 2.0.0 → 3.0.1

package/src/orchestration-toolkit.js

@@ -1,7 +1,7 @@
 /**
  * OrchestrationToolkit — tool schemas, per-role tool sets, and handler
  * factories for orchestration between leads (facilitator, supervisor,
- * discuss-lead) and their participating agents.
+ * discuss-lead) and the agents that take part.
  *
  * **Tool surface, by role:**
  *
@@ -15,16 +15,16 @@
  *   | Discuss agt |  ✓  |   ✓    |    ✓     |    ✓     |          | RFC                   |
  *   | Judge       |     |        |          |          |    ✓     |                       |
  *
- * **Ask is async.** Ask returns `{askIds:[…]}` immediately and posts the
+ * **Ask is async.** Ask returns `{askIds:[…]}` immediately. It posts the
  * question to the addressee's bus queue. The reply arrives on the asker's
- * next turn as `[answer#N] <participant>: <text>`. Pending state keys by
- * `askId` (visible in `[ask#N]` tags), so duplicate Asks to the same
- * addressee coexist without overwriting.
+ * next turn as `[answer#N] <participant>: <text>`. The toolkit keys pending
+ * state by `askId` (visible in `[ask#N]` tags). Duplicate Asks to the same
+ * addressee then coexist and never overwrite each other.
  *
  * **Answer's `askId` is optional.** With a matching askId, the reply
- * routes to that specific asker. Without, the handler auto-picks if
- * exactly one ask is owed to the caller, otherwise routes the message
- * as an Announce so it still reaches everyone.
+ * routes to that specific asker. Without one, the handler auto-picks when
+ * exactly one ask is owed to the caller. Otherwise the handler routes the
+ * message as an Announce so it still reaches everyone.
  */
 
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
@@ -48,9 +48,9 @@ export function createOrchestrationContext() {
 
 /**
  * Guard for terminal tools (`Conclude`, `Adjourn`, `Recess`). Returns an
- * error result when the caller still has Asks in flight, telling them to
- * end the turn and wait for the auto-resume. Returns `null` when no Asks
- * are pending and the terminal tool is free to run.
+ * error result when the caller still has Asks in flight. That result tells
+ * the caller to end the turn and wait for the auto-resume. Returns `null`
+ * when no Asks are pending and the terminal tool is free to run.
  */
 export function requireNoPendingAsks(ctx) {
   if (ctx.pendingAsks.size === 0) return null;
@@ -62,18 +62,18 @@ export function requireNoPendingAsks(ctx) {
 /**
  * Guard for terminal tools in discuss mode (`Adjourn`, `Recess`). Returns
  * an error result when the lead's inbox has unprocessed messages from the
- * human, telling them to end the turn and wait for the auto-resume.
- * Returns `null` when no inbox messages are pending and the terminal tool
- * is free to run.
+ * human. That result tells the lead to end the turn and wait for the
+ * auto-resume. Returns `null` when no inbox messages are pending and the
+ * terminal tool is free to run.
  */
 export function requireNoUnprocessedInbox(ctx) {
   if (!ctx.messageBus?.hasPending?.("lead")) return null;
   return errorResult(
-    "New messages from the human are waiting. End your turn. You will be resumed to process them.",
+    "New messages from the human are in your inbox. End your turn. You will be resumed to process them.",
   );
 }
 
-/** Mark the session as concluded; cancel any open Asks so askers see the synthetic null on their next turn. */
+/** Mark the session as concluded. Cancel any open Asks so askers see the synthetic null on their next turn. */
 export function createConcludeHandler(ctx) {
   return async ({ verdict, summary }) => {
     const guard = requireNoPendingAsks(ctx);
@@ -84,11 +84,11 @@ export function createConcludeHandler(ctx) {
 }
 
 /**
- * Shared terminal-tool helper. Conclude / Adjourn / Recess all set the
- * same three context fields (`concluded`, `verdict`, `summary`) and
- * cancel any in-flight Asks for the same reason: nobody will ever
- * answer them now. Mode-specific handlers (Adjourn, Recess) layer
- * extra state on top before calling this.
+ * Shared terminal-tool helper. Conclude, Adjourn, and Recess all set the
+ * same three context fields (`concluded`, `verdict`, `summary`). All three
+ * also cancel any in-flight Asks for the same reason. Nobody will ever
+ * answer them now. Mode-specific handlers (Adjourn, Recess) layer extra
+ * state on top before they call this.
  */
 export function concludeSession(ctx, { verdict, summary, reason }) {
   ctx.concluded = true;
@@ -124,21 +124,24 @@ function registerPendingAsk(ctx, { from, addressee, question }) {
 }
 
 /**
- * Create an Ask handler. Registers a pending entry per addressee, posts
- * the ask on the bus, returns `{askIds:[…]}` immediately. The LLM uses
- * those ids to match the `[answer#N]` it sees on a later turn.
+ * Create an Ask handler. The handler registers a pending entry for each
+ * addressee. It posts the ask on the bus. It returns `{askIds:[…]}`
+ * immediately. The LLM uses those ids to match the `[answer#N]` it sees on
+ * a later turn.
  *
  * @param {object} ctx
  * @param {object} opts
  * @param {string} opts.from
  * @param {string|undefined} opts.defaultTo - `undefined` means "broadcast
- *   to everyone else"; a participant name means "target that one when
+ *   to everyone else". A participant name means "target that one when
  *   `to` is omitted."
  */
 export function createAskHandler(ctx, { from, defaultTo }) {
   return async ({ question, to }) => {
     if (ctx.concluded) {
-      return errorResult("Session is concluded; Ask was not delivered.");
+      return errorResult(
+        "The session is concluded. The handler did not deliver your Ask.",
+      );
     }
     const addressees = resolveAddressees(ctx, { from, to, defaultTo });
     if (addressees.length === 0) {
@@ -157,7 +160,8 @@ export function createAskHandler(ctx, { from, defaultTo }) {
  * - askId provided + matches a pending entry whose addressee is the caller →
  *   route the reply to the asker's queue and clear the pending entry.
  * - askId provided but unknown or wrong addressee → `isError`. The caller
- *   tried to specify; we tell them why it didn't match.
+ *   tried to name an askId. The handler tells the caller why it did not
+ *   match.
  * - askId omitted + exactly one ask owed by the caller → auto-pick it.
  * - askId omitted + 0 or many pending → broadcast as Announce so the
  *   message still reaches every other participant.
@@ -180,9 +184,9 @@ export function createAnswerHandler(ctx, { from }) {
     ctx.messageBus.announce(from, message);
     const reason =
       owed.length === 0
-        ? "no pending ask for you"
-        : `${owed.length} pending asks (askId omitted is ambiguous)`;
-    return textResult(`Answer routed as Announce — ${reason}.`);
+        ? "You have no pending ask."
+        : `You have ${owed.length} pending asks. An omitted askId is ambiguous.`;
+    return textResult(`Answer routed as Announce. ${reason}`);
   };
 }
 
@@ -191,7 +195,7 @@ function routeAnswerByAskId(ctx, { from, askId, message }) {
   if (!entry) return errorResult(`No pending ask with askId=${askId}.`);
   if (entry.addresseeName !== from) {
     return errorResult(
-      `Ask #${askId} is addressed to ${entry.addresseeName}, not ${from}.`,
+      `Ask #${askId} is addressed to ${entry.addresseeName}. You are ${from}.`,
     );
   }
   ctx.pendingAsks.delete(askId);
@@ -208,9 +212,9 @@ export function createAnnounceHandler(ctx, { from }) {
 }
 
 /**
- * Cancel pending Asks and route a synthetic `[no answer: <reason>]` to
- * each asker's queue so callers never deadlock on a participant ignoring
- * its inbox.
+ * Cancel pending Asks. Route a synthetic `[no answer: <reason>]` to each
+ * asker's queue, so callers never deadlock when a participant ignores its
+ * inbox.
  *
  * @param {object} ctx
  * @param {string} reason - Surfaced inside `[no answer: <reason>]`.
@@ -234,8 +238,8 @@ export function pendingAsksOwedBy(ctx, addressee) {
 }
 
 /**
- * Inject a synthetic reminder onto the addressee's bus queue and mark
- * each owed ask as reminded. Returns true when a reminder fired.
+ * Inject a synthetic reminder onto the addressee's bus queue. Mark each
+ * owed ask as reminded. Returns true when a reminder fired.
  */
 export function remindOwedAsks(ctx, addressee) {
   const owed = pendingAsksOwedBy(ctx, addressee).filter((e) => !e.reminded);
@@ -252,13 +256,13 @@ export function remindOwedAsks(ctx, addressee) {
 // --- Tool descriptions (shared across roles) ---
 
 const ASK_DESC_BROADCAST =
-  "Send a question to one named participant, or omit 'to' to broadcast to every other participant. Returns {askIds:[…]} immediately; the reply arrives on a later turn as `[answer#N] <from>: <text>` in your inbox.";
+  "Send a question to one named participant. Omit 'to' to broadcast to every other participant. Returns {askIds:[…]} immediately. The reply arrives on a later turn as `[answer#N] <from>: <text>` in your inbox.";
 
 const ASK_DESC_TARGETED = (target) =>
-  `Send a question to ${target}. Returns {askIds:[N]} immediately; the reply arrives on a later turn as \`[answer#N] ${target}: <text>\` in your inbox.`;
+  `Send a question to ${target}. Returns {askIds:[N]} immediately. The reply arrives on a later turn as \`[answer#N] ${target}: <text>\` in your inbox.`;
 
 const ANSWER_DESC =
-  "Reply to an ask addressed to you. Quote askId from the [ask#N] tag on the question; omit it and the handler auto-picks the only pending ask, or routes your message as an Announce when 0 or many are pending.";
+  "Reply to an ask addressed to you. Quote askId from the [ask#N] tag on the question. Omit askId and the handler auto-picks the only pending ask. When 0 or many asks are pending, the handler routes your message as an Announce.";
 
 const ANNOUNCE_DESC = "Broadcast a message with no reply expected.";
 
@@ -275,7 +279,7 @@ const ADJOURN_DESC =
   "End the discussion. Provide a verdict ('adjourned' or 'failed') and a summary. Cancels any unanswered Asks.";
 
 const RECESS_DESC =
-  "End the run and schedule an out-of-session re-dispatch. Cancels any unanswered Asks. Use only when waiting on an external reply or duration. Do not use to wait on in-flight Asks.";
+  "End the run. Schedule an out-of-session re-dispatch. Cancels any unanswered Asks. Use only when you wait on an external reply or duration. Do not use to wait on in-flight Asks.";
 
 // --- Tool builders ---
 
@@ -283,7 +287,7 @@ const RECESS_DESC =
 function textResult(text) {
   return { content: [{ type: "text", text }] };
 }
-/** Build an MCP tool error result wrapping a single text message. */
+/** Build an MCP tool error result that wraps a single text message. */
 function errorResult(text) {
   return { content: [{ type: "text", text }], isError: true };
 }
@@ -298,10 +302,10 @@ function jsonResult(obj) {
  * @param {object} ctx
  * @param {object} opts
  * @param {string} opts.from - Caller's canonical name.
- * @param {string|undefined} opts.defaultTo - Default Ask target; `undefined`
+ * @param {string|undefined} opts.defaultTo - Default Ask target. `undefined`
  *   means "broadcast across everyone else when `to` is omitted."
  * @param {boolean} opts.broadcast - Whether Ask accepts a `to` field at all.
- *   Leads with multiple participants set this true; supervise's
+ *   Leads with multiple participants set this true. Supervise's
  *   single-participant roles set it false.
  */
 function baseTools(ctx, { from, defaultTo, broadcast }) {
@@ -338,19 +342,20 @@ function concludeTool(ctx) {
 }
 
 const ADVISOR_DESC =
-  "Consult a stronger model on one focused question. Your full session context (system prompt, prompts, transcript so far) is forwarded automatically — you cannot restrict it. The advice returns in the tool result. The consult budget is shared session-wide across all participants.";
+  "Consult a stronger model on one focused question. The tool forwards your full session context (system prompt, prompts, transcript so far) automatically. You cannot restrict it. The advice returns in the tool result. All participants share one session-wide consult budget.";
 
 /**
- * Build the `Advisor` consult tool for one caller. Mode-agnostic: loop
- * modes pass it into the agent tool-server factories via `extraTools`;
- * run mode gives it a dedicated server. No orchestration-context
- * dependency — the budget object and emit callback are injected.
+ * Build the `Advisor` consult tool for one caller. The tool is
+ * mode-agnostic. Loop modes pass it into the agent tool-server factories
+ * through `extraTools`. Run mode gives it a dedicated server. The tool has
+ * no orchestration-context dependency. The budget object and the emit
+ * callback arrive as injected dependencies.
  *
  * @param {object} deps
  * @param {string} deps.from - Caller's canonical name (event attribution).
  * @param {(question: string) => Promise<{advice?: string, unavailable?: boolean, reason?: string, durationMs: number}>} deps.consult
  * @param {(event: object) => void} deps.emit - Orchestrator-event emitter for the `advisor_consult` event.
- * @param {{maxUses: number, used: number}} deps.budget - Session-wide budget shared by every caller's handler.
+ * @param {{maxUses: number, used: number}} deps.budget - Session-wide budget that every caller's handler shares.
  * @param {string} deps.model - Advisor model id, carried on the consult event.
  */
 export function advisorTool({ from, consult, emit, budget, model }) {
@@ -378,7 +383,7 @@ export function advisorTool({ from, consult, emit, budget, model }) {
         remaining,
       });
       if (r.unavailable) {
-        // Not isError: fail-open, the caller continues normally.
+        // Not isError. This fails open, so the caller continues normally.
         return textResult(
           `The advisor is unavailable (${r.reason}) — proceed with your best judgment.`,
         );
@@ -477,7 +482,7 @@ export function createRequestForCommentHandler(ctx) {
 function requestForCommentTool(ctx) {
   return tool(
     "RequestForComment",
-    "Open a new Discussion thread for long-horizon coordination on an open question. The bridge creates the thread; replies arrive asynchronously on future runs.",
+    "Open a new Discussion thread for long-horizon coordination on an open question. The bridge creates the thread. Replies arrive asynchronously on future runs.",
     {
       channel: z.string(),
       body: z.string(),
@@ -487,8 +492,8 @@ function requestForCommentTool(ctx) {
   );
 }
 
-// Re-export the building blocks discuss-tools.js needs to assemble its
-// own lead tool surface (it has two extra terminal tools).
+// Re-export the parts discuss-tools.js needs to assemble its own lead tool
+// surface (it has two extra terminal tools).
 export {
   ADJOURN_DESC,
   baseTools,

package/src/orchestrator-helpers.js

@@ -1,8 +1,8 @@
 /**
  * Render a drained batch of bus messages as tagged text lines so the
  * LLM can read its inbox at a glance. Asks and answers include the
- * `askId` in the tag (`[ask#42] facilitator: …`, `[answer#42] agent: …`)
- * so the addressee can quote it back via Answer's `askId` field.
+ * `askId` in the tag (`[ask#42] facilitator: …`, `[answer#42] agent: …`).
+ * The addressee can then quote it back in Answer's `askId` field.
  *
  * @param {Array<{from: string, text: string, kind?: string, askId?: number}>} messages
  * @returns {string}

package/src/profile-prompt.js

@@ -1,8 +1,8 @@
 /**
- * System prompt composition for agent runners.
+ * Compose system prompts for agent runners.
  *
  * libharness assembles every agent system prompt from up to two parallel,
- * sibling-tagged sections (see COALIGNED.md § L0):
+ * sibling-tagged sections (see JIDOKA.md § L0):
  *
  *     <agent_profile>
  *     …persona body…
@@ -12,39 +12,40 @@
  *     …orchestration mechanics, then any amendment…
  *     </session_protocol>
  *
- * The two tags are siblings joined by a blank line — neither nests inside
+ * The two tags are siblings. A blank line joins them. Neither nests inside
  * the other. A section appears only when its content is present. The tag
- * convention lives entirely here: profile `.md` files and trailer constants
+ * convention lives entirely here. Profile `.md` files and trailer constants
  * carry no tags.
  *
- * The `<session_protocol>` body is assembled from up to three fragments, in
- * order of decreasing generality:
+ * The composer assembles the `<session_protocol>` body from up to three
+ * fragments, in order of decreasing generality:
  *
  *   1. the role-invariant orchestration trailer (libharness-owned);
  *   2. the profile's own hoisted `## Session Protocol` section, if present;
  *   3. a run-specific amendment, if supplied.
  *
- * Fragment 2 is the convention-based hoist: a profile may carry a level-2
+ * Fragment 2 is the convention-based hoist. A profile may carry a level-2
  * `## Session Protocol` markdown heading whose body is the role's work
- * routine. When present, that section is lifted out of `<agent_profile>` and
- * folded into `<session_protocol>` next to the orchestration mechanics, so
- * the harness comms protocol and the role's work routine read as one
- * coherent block. The heading line itself is dropped — the tag already names
- * the section. Profiles with no such heading are unaffected (the entire body
- * stays in `<agent_profile>`).
+ * routine. When the heading is present, the composer lifts that section out
+ * of `<agent_profile>`. It folds the section into `<session_protocol>` next
+ * to the orchestration mechanics. The harness comms protocol and the role's
+ * work routine then read as one coherent block. The composer drops the
+ * heading line itself, because the tag already names the section. A profile
+ * with no such heading is unaffected. Its entire body stays in
+ * `<agent_profile>`.
  *
  * Helpers:
  *
  * - `composeProfilePrompt(name, opts)` — profile + `claude_code` preset.
- *   Used by agent participants that need the full Claude Code tool surface.
+ *   Agent participants that need the full Claude Code tool surface use it.
  *
- * - `composeLeadPrompt(opts)` — plain string, no preset. Used by lead
- *   roles (supervisor, facilitator, discuss lead) that should only see
+ * - `composeLeadPrompt(opts)` — plain string, no preset. Lead roles
+ *   (supervisor, facilitator, discuss lead) use it. They should only see
  *   the orchestration instructions and optionally a profile body.
  *
  * - `composeSystemPrompt(opts)` — unified entry point. Threads `amend` into
- *   the protocol section as the run-specific fragment, then delegates to one
- *   of the above based on `opts.role`.
+ *   the protocol section as the run-specific fragment. Then delegates to one
+ *   of the above by `opts.role`.
  */
 
 import { join } from "node:path";
@@ -55,13 +56,13 @@ const SESSION_PROTOCOL_TAG = "session_protocol";
 
 /**
  * A level-2 heading that names the profile's hoisted session-protocol
- * section. Case-insensitive, tolerant of trailing whitespace, but the level
- * is fixed at two `#` so a `### Session Protocol` subsection does not trip
- * the hoist.
+ * section. The match ignores case. It tolerates trailing whitespace. The
+ * level is fixed at two `#`, so a `### Session Protocol` subsection does
+ * not trip the hoist.
  */
 const SESSION_PROTOCOL_HEADING = /^##[ \t]+session protocol[ \t]*$/i;
 
-/** A level-1 or level-2 heading — the boundary that ends a hoisted section. */
+/** A level-1 or level-2 heading. This boundary ends a hoisted section. */
 const SECTION_BOUNDARY = /^#{1,2}[ \t]+\S/;
 
 /** Wrap content in a semantic section tag, each on its own line. */
@@ -71,11 +72,11 @@ function wrapSection(tag, content) {
 
 /**
  * Assemble the parallel `<agent_profile>` / `<session_protocol>` sections.
- * The profile section is emitted only when `body` is non-empty. The protocol
- * section is built by joining its fragments (in the order given) with a
- * blank-line separator, dropping any that are empty, and is emitted only
- * when at least one fragment survives. The two tags are siblings joined by a
- * blank line and never nest.
+ * This function emits the profile section only when `body` is non-empty. It
+ * builds the protocol section from the fragments in the order given. It
+ * joins them with a blank-line separator and drops any empty fragment. It
+ * emits the protocol section only when at least one fragment survives. The
+ * two tags are siblings. A blank line joins them. They never nest.
  *
  * @param {object} parts
  * @param {string} [parts.body] - Profile body, frontmatter-stripped and with
@@ -95,10 +96,10 @@ function assembleSections({ body, protocolParts = [] }) {
 /**
  * Split a frontmatter-stripped profile body into its persona and an optional
  * hoisted `## Session Protocol` section. The section runs from its heading to
- * the next level-1/level-2 heading (or end of body); the heading line is
- * dropped. Anything before and after the section is rejoined into `persona`.
- * When the body carries no `## Session Protocol` heading, the whole body is
- * returned as `persona` and `protocol` is `undefined`.
+ * the next level-1/level-2 heading (or end of body). This function drops the
+ * heading line. It rejoins anything before and after the section into
+ * `persona`. When the body carries no `## Session Protocol` heading, the
+ * whole body returns as `persona` and `protocol` is `undefined`.
  *
  * @param {string} body - Frontmatter-stripped, trimmed profile body.
  * @returns {{ persona: string, protocol: string | undefined }}
@@ -127,14 +128,14 @@ function splitSessionProtocol(body) {
 }
 
 /**
- * Read a profile `.md`, strip its frontmatter, and split off any hoisted
+ * Read a profile `.md`. Strip its frontmatter. Split off any hoisted
  * `## Session Protocol` section. Reads synchronously off the injected
- * `runtime.fsSync` surface — this composer runs inside the synchronous
+ * `runtime.fsSync` surface. This composer runs inside the synchronous
  * SDK-option builders of the supervisor / facilitator / discusser / judge
- * factories, so it cannot go async without an unbounded cascade.
+ * factories. So it cannot go async without an unbounded cascade.
  *
  * @param {string} name - Profile basename (no `.md` suffix)
- * @param {string} profilesDir - Directory containing `<name>.md`
+ * @param {string} profilesDir - Directory that contains `<name>.md`
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {{ persona: string, protocol: string | undefined }}
  */
@@ -145,19 +146,19 @@ function readProfileSections(name, profilesDir, runtime) {
 }
 
 /**
- * Compose a `claude_code`-preset system prompt from a profile file. The
- * persona is wrapped in `<agent_profile>`; the protocol trailer, the
- * profile's hoisted `## Session Protocol` section, and any amendment are
- * joined (in that order) into a sibling `<session_protocol>`.
+ * Compose a `claude_code`-preset system prompt from a profile file. This
+ * function wraps the persona in `<agent_profile>`. It joins the protocol
+ * trailer, the profile's hoisted `## Session Protocol` section, and any
+ * amendment into a sibling `<session_protocol>`, in that order.
  *
  * @param {string} name - Profile basename (no `.md` suffix)
  * @param {object} opts
- * @param {string} opts.profilesDir - Directory containing `<name>.md`
- * @param {string} [opts.trailer] - Session protocol orchestration mechanics,
- *   the first fragment of the `<session_protocol>` section.
+ * @param {string} opts.profilesDir - Directory that contains `<name>.md`
+ * @param {string} [opts.trailer] - Orchestration mechanics for the session
+ *   protocol, the first fragment of the `<session_protocol>` section.
  * @param {string} [opts.amend] - Run-specific amendment, the last fragment of
  *   the `<session_protocol>` section.
- * @param {import("@forwardimpact/libutil/runtime").Runtime} opts.runtime - Ambient collaborators; uses `fsSync.readFileSync`.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} opts.runtime - Ambient collaborators. Uses `fsSync.readFileSync`.
  * @returns {{type: "preset", preset: "claude_code", append: string}}
  */
 export function composeProfilePrompt(
@@ -177,18 +178,18 @@ export function composeProfilePrompt(
 
 /**
  * Compose a plain-string system prompt for a lead role (no Claude Code
- * preset). The protocol trailer, an optional profile's hoisted
- * `## Session Protocol` section, and any amendment are joined into
- * `<session_protocol>`; an optional persona is wrapped in a sibling
- * `<agent_profile>` before it.
+ * preset). This function joins the protocol trailer, an optional profile's
+ * hoisted `## Session Protocol` section, and any amendment into
+ * `<session_protocol>`. It wraps an optional persona in a sibling
+ * `<agent_profile>` before that section.
  *
  * @param {object} opts
  * @param {string} [opts.profile] - Profile basename (no `.md` suffix)
- * @param {string} [opts.profilesDir] - Directory containing profile files
+ * @param {string} [opts.profilesDir] - Directory that contains profile files
  * @param {string} opts.trailer - Session protocol (orchestration instructions)
  * @param {string} [opts.amend] - Run-specific amendment, the last fragment of
  *   the `<session_protocol>` section.
- * @param {import("@forwardimpact/libutil/runtime").Runtime} opts.runtime - Ambient collaborators; uses `fsSync.readFileSync`.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} opts.runtime - Ambient collaborators. Uses `fsSync.readFileSync`.
  * @returns {string}
  */
 export function composeLeadPrompt({
@@ -209,20 +210,20 @@ export function composeLeadPrompt({
 }
 
 /**
- * Unified entry point for composing system prompts. Threads an optional
+ * Unified entry point that composes a system prompt. Threads an optional
  * amendment through as the run-specific fragment of `<session_protocol>`
- * (after the trailer and any hoisted profile section), then delegates by
+ * (after the trailer and any hoisted profile section). Then delegates by
  * role.
  *
  * @param {object} opts
- * @param {"lead"|"agent"} opts.role - `"lead"` produces a plain string;
+ * @param {"lead"|"agent"} opts.role - `"lead"` produces a plain string.
  *   `"agent"` produces a `claude_code` preset object.
  * @param {string} [opts.profile] - Profile basename
  * @param {string} [opts.profilesDir]
  * @param {string} opts.trailer - Session protocol (orchestration instructions)
  * @param {string} [opts.amend] - Caller-supplied amendment, the last fragment
  *   inside `<session_protocol>`, joined with a blank-line separator.
- * @param {import("@forwardimpact/libutil/runtime").Runtime} opts.runtime - Ambient collaborators; uses `fsSync.readFileSync`.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} opts.runtime - Ambient collaborators. Uses `fsSync.readFileSync`.
  * @returns {string | {type: "preset", preset: "claude_code", append: string}}
  */
 export function composeSystemPrompt({