@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/kernel/copy.test.ts

@@ -28,6 +28,11 @@
  * in a capability source — became content the config declares
  * (`pragma.conf.ts#colophon`), which is what made removing it checkable.
  *
+ * Beside the naming rules, the same scanner enforces the HOUSE VOICE rules for
+ * user-facing copy ({@link COPY_RULES}, authored as data in `copy.ts`) over
+ * both file sets — the kernel set above and `src/capabilities/**` — in the
+ * last describe of this file. See `copy.ts` for what each rule bans and why.
+ *
  * NOTE for a reader of an older revision: this docblock used to say the
  * `examples[].cmd` sweep and the `docs/reference/*.md` regen "have to move
  * together". They must be CONSISTENT, not simultaneous — the whole sweep was
@@ -41,6 +46,7 @@ import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 import conf from "../../pragma.conf.js";
 import { BIN_NAME } from "../constants.js";
+import { COPY_RULES } from "./copy.js";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const root = resolve(here, "..");
@@ -250,13 +256,17 @@ function pushCopy(copy: string[], literal: string): void {
  * `file: literal` for every authored literal matching `pattern`, so a failure
  * names its offenders instead of only counting them.
  *
- * @param pattern - What kernel copy may not contain.
+ * @param pattern - What the copy may not contain.
+ * @param sources - The files to read; the kernel set by default.
  * @returns One entry per offending literal.
- * @note Impure — reads every kernel source.
+ * @note Impure — reads every listed source.
  */
-function findOffenders(pattern: RegExp): string[] {
+function findOffenders(
+  pattern: RegExp,
+  sources: readonly string[] = files,
+): string[] {
   const found: string[] = [];
-  for (const file of files) {
+  for (const file of sources) {
     for (const literal of readCopy(readFileSync(file, "utf-8"))) {
       if (pattern.test(literal)) {
         found.push(`${relative(root, file)}: ${literal}`);
@@ -451,3 +461,23 @@ describe("capability commands (PROTECTED)", () => {
     expect(offenders).toEqual([]);
   });
 });
+
+describe("user-facing copy house style (PROTECTED)", () => {
+  // The voice rules ({@link COPY_RULES}) run over BOTH file sets the naming
+  // rules above read — the kernel set and the capability set — because voice,
+  // unlike the distribution's name, is not content anywhere: a capability's
+  // error is the same product speaking as a kernel diagnostic. `readCopy`
+  // keeps comments, regexes, specifiers and test files out of scope, so a
+  // rule fires only on a string a user can actually be shown.
+  //
+  // One `it` per rule, NAMED by the rule, so a red run states the rule that
+  // fired; the assertion message carries the fix. What a failure prints is the
+  // offender list plus those two strings — everything needed to correct the
+  // copy lives in this repo.
+  const allSources = [...files, ...capabilitySources];
+  for (const { pattern, rule, fix } of COPY_RULES) {
+    it(rule, () => {
+      expect(findOffenders(pattern, allSources), fix).toEqual([]);
+    });
+  }
+});

package/src/kernel/copy.ts

@@ -0,0 +1,54 @@
+/**
+ * The house rules for user-facing copy, as data.
+ *
+ * Every string this CLI prints is one product speaking, and a product with one
+ * voice phrases one meaning one way. These descriptors name the phrasings that
+ * are out of that voice, why, and what to write instead; `copy.test.ts` runs
+ * them over every authored string literal in the tree — the same scanner and
+ * file sets as the naming rules there, so comments, regexes, module specifiers
+ * and test fixtures are never in scope. A failure quotes the offending literal,
+ * the rule, and the fix, and nothing else: everything a maintainer needs to
+ * correct the string lives in this file.
+ *
+ * Rules are DATA rather than assertions so the set can grow (or move into a
+ * shared standards package) without rewriting the guard, and so each rule's
+ * pattern, statement and fix are reviewed together as one unit. Precision is
+ * the set's credibility: a pattern that fires on domain vocabulary gets
+ * disabled in practice, so a carve-out is encoded in the pattern itself — with
+ * its reason — never in an exemption list beside it.
+ */
+
+/** One banned phrasing: what copy may not contain, why, and the rewrite. */
+export interface CopyRule {
+  /** What the copy must not contain. */
+  readonly pattern: RegExp;
+  /** The house rule, stated for a reader of THIS codebase. */
+  readonly rule: string;
+  /** How to fix an offending string. */
+  readonly fix: string;
+}
+
+/** The banned phrasings for user-facing copy. Enforced by `copy.test.ts`. */
+export const COPY_RULES: readonly CopyRule[] = [
+  {
+    pattern: /\b(?:could not|failed to|unable to)\b/i,
+    rule: "User-facing copy says `cannot` — one phrasing for one meaning, so the CLI reads as one voice.",
+    fix: "Rewrite with `cannot` (present tense, no hedging), naming what is wrong rather than what was attempted.",
+  },
+  {
+    // `\w+n't` covers every negated contraction in one arm; the lookbehind
+    // carves out `do/don't`, which is domain vocabulary — the name of the
+    // paired good/bad example a coding standard ships — not conversational
+    // tone. The second arm lists the pronoun contractions, which have no
+    // shared suffix shape.
+    pattern:
+      /\b(?<!do\/)\w+n't\b|\b(?:you|we|they|it|that|there|here|what|let)'(?:re|ve|ll|s|d)\b|\bi'm\b/i,
+    rule: "No contractions in user-facing copy — instructions read as statements, not conversation.",
+    fix: "Spell the words out, or restructure the sentence to drop the second person.",
+  },
+  {
+    pattern: /\b(?:please|sorry|oops)\b/i,
+    rule: "The CLI does not apologise or plead; it states the fact and the action.",
+    fix: "Drop the pleading word and instruct directly: `Report this issue at <url>.`",
+  },
+];

package/src/kernel/error/PragmaError.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { ISSUES_URL } from "../../constants.js";
 import { errorEnvelope, successEnvelope } from "../render/envelope.js";
 import { PragmaError } from "./PragmaError.js";
 import { cliRecovery } from "./recovery.js";
@@ -56,7 +57,9 @@ describe("PragmaError factories", () => {
   it("internalError attaches a report hint", () => {
     const error = PragmaError.internalError("boom");
     expect(error.code).toBe("INTERNAL_ERROR");
-    expect(error.recovery).toEqual({ message: "Please report this issue." });
+    expect(error.recovery).toEqual({
+      message: `Report this issue at ${ISSUES_URL}.`,
+    });
   });
 });
 
@@ -66,7 +69,7 @@ describe("serializeError", () => {
     expect(serializeError(error)).toEqual({
       code: "INTERNAL_ERROR",
       message: "Internal error: boom",
-      recovery: { message: "Please report this issue." },
+      recovery: { message: `Report this issue at ${ISSUES_URL}.` },
     });
   });
 

package/src/kernel/error/PragmaError.ts

@@ -1,3 +1,4 @@
+import { ISSUES_URL } from "../../constants.js";
 import type { ErrorCode, PragmaErrorData, Recovery } from "./types.js";
 
 /**
@@ -168,13 +169,14 @@ class PragmaError extends Error {
    * Factory: unexpected internal failure (a bug).
    *
    * @param reason - Description of the internal error.
-   * @returns PragmaError with code `INTERNAL_ERROR` and a "please report" hint.
+   * @returns PragmaError with code `INTERNAL_ERROR` and a report-this hint
+   *   naming the issue tracker.
    */
   static internalError(reason: string): PragmaError {
     return new PragmaError({
       code: "INTERNAL_ERROR",
       message: `Internal error: ${reason}`,
-      recovery: { message: "Please report this issue." },
+      recovery: { message: `Report this issue at ${ISSUES_URL}.` },
     });
   }
 }

package/src/kernel/error/constants.ts

@@ -25,11 +25,13 @@ const ERROR_CODES = [
   "CONFIG_ERROR",
   "INTERNAL_ERROR",
   // A runtime condition that is NOT a bug and NOT a usage mistake, so it must
-  // NOT collapse to INTERNAL_ERROR's "please report this issue": a capability
-  // genuinely unavailable in this build/environment (`create package` /
-  // `create application` in the compiled binary, whose generators read their
-  // templates from disk rather than through the embedded manifest —
-  // `create component` reads through it and runs), OR an external command
+  // NOT collapse to INTERNAL_ERROR's "report this issue": a capability
+  // genuinely unavailable in this environment (`create` refusing when its
+  // lazily-imported generator runtime cannot be loaded at all — the
+  // module-not-found backstop in `capabilities/create/create.verb.ts`, which
+  // means the `@canonical/summon-*` dependencies could not be resolved, i.e. a
+  // broken or pruned install; every declared generator otherwise runs
+  // everywhere), OR an external command
   // that RAN and failed for a fixable environment reason (a denied global
   // `npm i -g`, a network/registry failure — see `shared/assertExecOk`). Both
   // carry an actionable recovery and map to the generic runtime exit 1.

package/src/kernel/error/fromTaskError.ts

@@ -6,7 +6,7 @@
  * `MISSING_REQUIRED_ANSWER` / `GENERATOR_INVALID_ANSWER` for absent or invalid
  * non-interactive answers. `runTask` rethrows these as a `TaskExecutionError`
  * carrying `.code`. Without a bridge the CLI/MCP boundary collapses every
- * non-`PragmaError` to INTERNAL_ERROR + "please report this issue" — telling a
+ * non-`PragmaError` to INTERNAL_ERROR + "report this issue" — telling a
  * user to file a bug for cancelling their own scaffold.
  *
  * The codes are matched as STRING LITERALS, never imported from summon-core, so
@@ -62,15 +62,37 @@ export function isInterruption(error: unknown): boolean {
   return taskErrorCode(error) === TASK_INTERRUPTED;
 }
 
+/**
+ * The {@link PragmaError} a task failure CARRIES, if any. A task-layer failure
+ * raised through the failure channel (`failPragma` — so an enclosing `recover`
+ * such as setup's per-step isolation can catch it, which a synchronous throw
+ * bypasses) stores the original PragmaError as the TaskError's `cause`;
+ * `runTask` then wraps that TaskError in a `TaskExecutionError` whose
+ * `taskError` carries it. Walk both wrappers (bounded — the shapes nest at
+ * most a few levels) so the boundary recovers the ORIGINAL error with its
+ * code, message, and recovery intact.
+ */
+function carriedPragmaError(error: unknown): PragmaError | undefined {
+  let current: unknown = error;
+  for (let depth = 0; depth < 4 && current !== undefined; depth += 1) {
+    if (current instanceof PragmaError) return current;
+    const record = current as { taskError?: unknown; cause?: unknown } | null;
+    current = record?.taskError ?? record?.cause;
+  }
+  return undefined;
+}
+
 /**
  * Coerce a thrown value into a {@link PragmaError} for the CLI/MCP boundary,
- * bridging summon-core task-error codes: absent/invalid non-interactive answers
- * become INVALID_INPUT (a usage error, exit 2); a `PragmaError` passes through
- * unchanged; everything else stays INTERNAL_ERROR. Cancellation is handled
- * separately by {@link isCancellation} as a clean, non-error outcome.
+ * bridging summon-core task-error codes: a `PragmaError` (direct, or carried
+ * through the task failure channel as a TaskError `cause`) passes through
+ * unchanged; absent/invalid non-interactive answers become INVALID_INPUT (a
+ * usage error, exit 2); everything else stays INTERNAL_ERROR. Cancellation is
+ * handled separately by {@link isCancellation} as a clean, non-error outcome.
  */
 export function asPragmaError(error: unknown): PragmaError {
-  if (error instanceof PragmaError) return error;
+  const carried = carriedPragmaError(error);
+  if (carried !== undefined) return carried;
   const message = error instanceof Error ? error.message : String(error);
   const code = taskErrorCode(error);
   if (code !== undefined && ANSWER_USAGE_CODES.has(code)) {

package/src/kernel/error/recovery.ts

@@ -10,6 +10,20 @@
  * that were actually wrong were raw `cli:` object literals that never reached
  * this function at all. `kernel/copy.test.ts` covers those, at the position.
  *
+ * A THIRD authoring route is also legal and reached by NEITHER guard: a `cli`
+ * DERIVED from the program's own name at the call site. One site does this —
+ * the create mount (`capabilities/create/mount.ts`,
+ * `[...detail.chain, suggestion].join(" ")`), whose `chain[0]` is the root
+ * Commander program's name, `BIN_NAME` by wiring. It bypasses
+ * {@link cliRecovery}, and the position rule is structurally blind to it (it
+ * flags QUOTED literals containing the distribution's name, never a computed
+ * expression) — so D5 holds there by derivation, and the derivation is pinned
+ * where the value surfaces: `createGrammar.test.ts` COMPOSES its expected
+ * `cli` from {@link RECOVERY_CLI_PREFIX}, so a renamed root program reddens
+ * the cell naming the constant. (A separate `startsWith` assertion cannot
+ * pin it — behind an exact pin of the same value it has no reachable
+ * failing input.)
+ *
  * `kernel/packs/schema.ts` holds a user-authored pack's `emptyRecovery.cli` to
  * the same shape from the other side — it must NOT carry a prefix, because the
  * consuming distribution's renderer supplies one.

package/src/kernel/error/renderError.ts

@@ -7,6 +7,7 @@
  * whichever transport they use.
  */
 
+import type { OutputFormat } from "../../constants.js";
 import type { PragmaError } from "./PragmaError.js";
 import { serializeError } from "./serialize.js";
 
@@ -98,4 +99,44 @@ function renderErrorJson(error: PragmaError): string {
   return JSON.stringify({ ok: false, error: serializeError(error) });
 }
 
-export { renderErrorJson, renderErrorLlm, renderErrorPlain };
+/**
+ * Render an error for an EXPLICITLY requested machine format, or decline.
+ *
+ * The ONE machine-format envelope decision for the usage-error surfaces —
+ * `handleProgramError`'s Commander parse failures (the unknown-command arm
+ * included), the create mount's projection usage-error writer, and
+ * `writeRefusal`: an explicit `--format json` renders the failure envelope,
+ * an explicit `--format llm` the condensed Markdown form, and anything else
+ * returns `undefined` so the caller keeps its raw default bytes.
+ * Auto-detected llm is excluded by construction — `parseGlobalFlags` leaves
+ * `format` at `"plain"` under auto-detection and records `autoLlm`
+ * separately — so an inferred output mode can never move the default
+ * (cross-CLI parity) bytes. Hoisted so the gate and the renderer pick exist
+ * ONCE instead of drifting per call site (they had already split: sites
+ * gated on json only vs json|llm, and `--format llm` enveloped some members
+ * of the usage-error class while siblings stayed raw). Deliberately NOT
+ * routed through here: the always-render sites with no raw arm to arbitrate
+ * — `renderStartupError`, bin.ts's bad-`--format` rejection,
+ * `handleProgramError`'s non-Commander fallthrough, and dispatch's
+ * `renderError` (which deliberately includes autoLlm for run errors) — each
+ * picks a PragmaError renderer directly.
+ *
+ * @param error - The structured error to render.
+ * @param format - The parsed global `--format` value.
+ * @returns The rendered string for `json`/`llm`; `undefined` for `plain`.
+ */
+function renderErrorForFormat(
+  error: PragmaError,
+  format: OutputFormat,
+): string | undefined {
+  if (format === "json") return renderErrorJson(error);
+  if (format === "llm") return renderErrorLlm(error);
+  return undefined;
+}
+
+export {
+  renderErrorForFormat,
+  renderErrorJson,
+  renderErrorLlm,
+  renderErrorPlain,
+};

package/src/kernel/error/types.ts

@@ -17,7 +17,10 @@ type ErrorCode = (typeof ERROR_CODES)[number];
  * `cli` — when present — is the command as a user would type it: this
  * distribution's own bin name (`RECOVERY_CLI_PREFIX`) plus a grammar path (D5).
  * `cliRecovery` takes the path alone and prepends the prefix, so there is no
- * assertion to make — see the docblock on `error/recovery.ts`.
+ * assertion to make; the one COMPUTED producer (the create mount) derives
+ * the prefix from the program's own name, pinned by a test expectation
+ * COMPOSED from `RECOVERY_CLI_PREFIX` — the routes are enumerated in the
+ * docblock on `error/recovery.ts`.
  */
 interface Recovery {
   /** Human-readable recovery guidance. */
@@ -54,6 +57,23 @@ interface PragmaErrorData {
 interface ErrorPayload {
   readonly code: ErrorCode;
   readonly message: string;
+  /**
+   * Fuzzy-matched alternative names — BARE candidate tokens the caller can
+   * substitute for the one token it typed (a verb, a tree segment), never
+   * full invocations. The FUZZY tiers serialize this one convention:
+   * bin.ts's unknown-command tier emits the candidate name (`block`) and
+   * the create mount's unknown-segment tier the candidate segment
+   * (`react`); the corrected full command line, when one is shown, lives
+   * in the default prose did-you-mean rendering, not in this field. An
+   * excess positional is NOT a fuzzy match — its matched operand may be
+   * the very token its message calls unexpected, or one the message never
+   * names — so that producer omits this field entirely and instead ships
+   * the runnable corrected command as `recovery.cli` WHEN an operand
+   * names a sibling or child segment resolving to a declared runnable
+   * leaf (the prose did-you-mean condition, narrowed to runnable — a
+   * matched namespace keeps the prose hint but ships no recovery); with
+   * no runnable match the envelope carries neither optional field.
+   */
   readonly suggestions?: readonly string[];
   readonly recovery?: Recovery;
   readonly validOptions?: readonly string[];

package/src/kernel/index.ts

@@ -0,0 +1,35 @@
+/**
+ * The kernel's own top-level declarations — the small set of facts that belong
+ * to no sub-domain because every sub-domain may need them.
+ *
+ * This is NOT a facade over the kernel. `kernel/` is a namespace of domains,
+ * each of which keeps its own barrel (`config/`, `render/`, `runtime/`,
+ * `packs/`, `error/`, `spec/`, `completion/`, `project/…`); a consumer wanting
+ * one of those imports that domain's barrel, not this one. What lives here is
+ * only what sits directly in `kernel/`, and the bar for putting a file there
+ * is high: it must be a declaration the kernel makes about itself rather than
+ * a step in any one pipeline.
+ *
+ * Today that is the declared vocabulary and the interactivity vocabulary. The
+ * latter (`interactivity.ts`) names the questions about attended streams — is
+ * stdout captured, may we prompt, may we color (that third one lives with the
+ * styler, for the dependency reason its docblock records) — which render,
+ * dispatch and flag parsing each used to answer with their own inline probe.
+ * They are different questions over different streams, and the names are what
+ * keeps them from being flattened into one flag.
+ *
+ * The declared vocabulary is the distribution's mapping from the roles the
+ * CLI knows (a prompt, a resource) onto the RDF terms that actually
+ * carry them in the active graph. It is parsed once at module load and read
+ * from the prompt capability, the MCP prompt source, and the pack index
+ * builder, none of which owns it and any of which would otherwise hardcode
+ * someone else's IRIs.
+ *
+ * The copy-gate rule table (`copy.ts`) deliberately stays off this barrel. It
+ * is reviewed data consumed by its own test and by nothing else at runtime;
+ * exporting it here would advertise a runtime API the gate does not have.
+ */
+
+export { canPrompt, stdoutIsCaptured } from "./interactivity.js";
+export type { DeclaredVocabulary } from "./vocabulary.js";
+export { VOCABULARY } from "./vocabulary.js";

package/src/kernel/interactivity.test.ts

@@ -0,0 +1,76 @@
+import chalk from "chalk";
+import { afterEach, describe, expect, it } from "vitest";
+import { canPrompt, stdoutIsCaptured } from "./interactivity.js";
+import { canColor } from "./render/style.js";
+
+/** Force a stream's `isTTY`, as only a test may. */
+const setTTY = (
+  stream: NodeJS.ReadStream | NodeJS.WriteStream,
+  value: boolean | undefined,
+): void => {
+  (stream as { isTTY?: boolean }).isTTY = value;
+};
+
+const savedIn = process.stdin.isTTY;
+const savedOut = process.stdout.isTTY;
+const savedErr = process.stderr.isTTY;
+const savedLevel = chalk.level;
+afterEach(() => {
+  setTTY(process.stdin, savedIn);
+  setTTY(process.stdout, savedOut);
+  setTTY(process.stderr, savedErr);
+  chalk.level = savedLevel;
+});
+
+describe("the interactivity vocabulary asks THREE questions, not one", () => {
+  it("a captured stdout with an attended terminal is still promptable", () => {
+    // The case that makes flattening these wrong: an agent runs a mutating
+    // verb with `| cat` while a terminal is still attached. Answering the
+    // prompting question with stdout's probe would refuse a human; answering
+    // the output-shape question with stdin's would hand an agent a page of
+    // decoration it cannot use.
+    setTTY(process.stdout, false);
+    setTTY(process.stdin, true);
+    setTTY(process.stderr, true);
+    expect(stdoutIsCaptured()).toBe(true);
+    expect(canPrompt()).toBe(true);
+  });
+
+  it("a redirected stderr is NOT promptable, however attended stdout is", () => {
+    // `<verb> 2>/dev/null`: the step sequence renders to stderr, so gating on
+    // stdout would mount an invisible render that then blocks on stdin.
+    setTTY(process.stdout, true);
+    setTTY(process.stdin, true);
+    setTTY(process.stderr, false);
+    expect(stdoutIsCaptured()).toBe(false);
+    expect(canPrompt()).toBe(false);
+  });
+
+  it("stdin alone does not make a run promptable", () => {
+    setTTY(process.stdin, false);
+    setTTY(process.stderr, true);
+    expect(canPrompt()).toBe(false);
+  });
+
+  it("colour needs the terminal AND a usable chalk level", () => {
+    setTTY(process.stdout, true);
+    chalk.level = 1;
+    expect(canColor()).toBe(true);
+    // Off in CI-shaped environments where `supports-color` fires off a TTY…
+    setTTY(process.stdout, false);
+    expect(canColor()).toBe(false);
+    // …and off whenever the level is zeroed (what `NO_COLOR` does at load).
+    setTTY(process.stdout, true);
+    chalk.level = 0;
+    expect(canColor()).toBe(false);
+  });
+
+  it("treats an absent isTTY as captured / unpromptable, never as attended", () => {
+    setTTY(process.stdout, undefined);
+    setTTY(process.stdin, undefined);
+    setTTY(process.stderr, undefined);
+    expect(stdoutIsCaptured()).toBe(true);
+    expect(canPrompt()).toBe(false);
+    expect(canColor()).toBe(false);
+  });
+});

package/src/kernel/interactivity.ts

@@ -0,0 +1,69 @@
+/**
+ * The interactivity vocabulary — three named questions over three streams.
+ *
+ * Every one of these used to be spelled inline as a bare `process.<stream>
+ * .isTTY === true` at the site that needed it, in four places, and the
+ * spellings did not agree — because they are NOT the same question. Naming them
+ * is the point: the names are what stop the next reader from "simplifying"
+ * three probes into one flag.
+ *
+ * - {@link stdoutIsCaptured} reads **stdout**. It governs OUTPUT SHAPE: whether
+ *   a consumer is piping the data stream somewhere (the shape an agent
+ *   captures), which is what AUTO-INFERS the condensed `llm` default. Capture
+ *   is the inference, not the gate: what drops the root-help wordmark is the
+ *   resulting shape — `llm` or `json` — so an explicit `--format plain` through
+ *   a pipe is captured and keeps the art, while `--format llm` on an attended
+ *   terminal is not captured and drops it. Explicit format beats inference, in
+ *   both directions.
+ * - {@link canPrompt} reads **stdin AND stderr** — never stdout. The step
+ *   sequence renders to stderr and reads stdin, so `<verb> 2>/dev/null` is
+ *   non-interactive while `<verb> | cat` is not. Gating this one on stdout
+ *   would mount an invisible render that then blocks on stdin.
+ * - `canColor` (`render/style.ts`) reads **stdout** plus chalk's own color
+ *   level, so piped, redirected and MCP output stays byte-stable even where
+ *   `supports-color` fires off a TTY. It is the one question of the three that
+ *   lives with the styler rather than here, because it needs `chalk` and this
+ *   module is imported by global-flag parsing — which runs before `--version`
+ *   answers, on a path that must load nothing it does not use. It still asks
+ *   its stdout half through {@link stdoutIsCaptured}, so the three stay one
+ *   vocabulary.
+ *
+ * The distinction is not academic: an agent running a mutating verb with its
+ * stdout captured but a terminal still attached is CAPTURED and PROMPTABLE at
+ * the same time. Answering either question with the other's probe would either
+ * hang a pipeline or refuse a human.
+ *
+ * These are the only sanctioned readers of `process.*.isTTY` outside a test.
+ * Each is a plain function rather than a module-load constant because a test
+ * assigns the streams' `isTTY` per case, and a constant would freeze the first
+ * value the process ever saw.
+ */
+
+/**
+ * Whether stdout is going somewhere other than an attended terminal — piped,
+ * redirected, or read by a parent process.
+ *
+ * The OUTPUT-SHAPE question, and stdout's alone: it says nothing about whether
+ * a human is available to answer a prompt (see {@link canPrompt}).
+ *
+ * @returns True when stdout is not a TTY.
+ * @note Impure — reads `process.stdout.isTTY`.
+ */
+export function stdoutIsCaptured(): boolean {
+  return process.stdout.isTTY !== true;
+}
+
+/**
+ * Whether this invocation may ask the user a question: stdin AND stderr are
+ * both attended terminals.
+ *
+ * THE interactivity gate (H3). One exported fact, so the kernel's interaction
+ * context and a mounted subtree's own decision can never disagree about what
+ * "a TTY" means. Deliberately blind to stdout — see the module docblock.
+ *
+ * @returns True when a prompt can be both drawn and answered.
+ * @note Impure — reads `process.stdin.isTTY` and `process.stderr.isTTY`.
+ */
+export function canPrompt(): boolean {
+  return process.stdin.isTTY === true && process.stderr.isTTY === true;
+}

package/src/kernel/packs/collect.ts

@@ -24,11 +24,11 @@
  * costs nothing on `--help`/`__complete`.
  */
 
-import type { ConfigLayers } from "../config/types.js";
-import { PragmaError } from "../error/PragmaError.js";
+import type { ConfigLayers } from "../config/index.js";
+import { PragmaError } from "../error/index.js";
 import type { PackStoryRecord } from "../runtime/graphpack/stories.js";
-import type { CapabilityModule } from "../spec/types.js";
-import { compilePack } from "./compile.js";
+import type { CapabilityModule } from "../spec/index.js";
+import { compileStoryModule } from "./compile.js";
 import { parsePackDefinition } from "./schema.js";
 import type { PackDefinition, PackEntry } from "./types.js";
 import { assertUniqueVerbs } from "./uniqueness.js";
@@ -172,16 +172,14 @@ export function assembleEffectiveModules(
   // story both on its pack and at the top level is a refinement, not an error.
   const dynamic = new Map<string, CapabilityModule>();
   for (const entry of packageStories) {
-    dynamic.set(entry.definition.noun, {
-      name: entry.definition.noun,
-      story: true,
-      verbs: compilePack(
+    dynamic.set(
+      entry.definition.noun,
+      compileStoryModule(
         entry.definition,
         { label: entry.source, origin: "package" },
         prefixes,
       ),
-      colophon: entry.definition.colophon,
-    });
+    );
   }
   for (const tier of tiers) {
     const seen = new Set<string>();
@@ -201,16 +199,14 @@ export function assembleEffectiveModules(
         );
       }
       seen.add(definition.noun);
-      dynamic.set(definition.noun, {
-        name: definition.noun,
-        story: true,
-        verbs: compilePack(
+      dynamic.set(
+        definition.noun,
+        compileStoryModule(
           definition,
           { label: "config", origin: "config" },
           prefixes,
         ),
-        colophon: definition.colophon,
-      });
+      );
     }
   }