@orkestrel/brief 0.0.7 → 0.0.8

package/dist/src/core/index.d.ts

@@ -1,26 +1,26 @@
-import { Ambiguity } from '@orkestrel/interpret';
+import type { Ambiguity } from '@orkestrel/interpret';
 import { ArrayShape } from '@orkestrel/contract';
 import { BooleanShape } from '@orkestrel/contract';
-import { ContractInterface } from '@orkestrel/contract';
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { Entity } from '@orkestrel/interpret';
-import { Guard } from '@orkestrel/contract';
-import { Intent } from '@orkestrel/interpret';
-import { Interpretation } from '@orkestrel/interpret';
-import { InterpretInterface } from '@orkestrel/interpret';
+import type { ContractInterface } from '@orkestrel/contract';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { Entity } from '@orkestrel/interpret';
+import type { Guard } from '@orkestrel/contract';
+import type { Intent } from '@orkestrel/interpret';
+import type { Interpretation } from '@orkestrel/interpret';
+import type { InterpretInterface } from '@orkestrel/interpret';
 import { LiteralShape } from '@orkestrel/contract';
-import { LogicalDefinition } from '@orkestrel/reason';
-import { LogicalResult } from '@orkestrel/reason';
+import type { LogicalDefinition } from '@orkestrel/reason';
+import type { LogicalResult } from '@orkestrel/reason';
 import { NumberShape } from '@orkestrel/contract';
 import { ObjectShape } from '@orkestrel/contract';
 import { OptionalShape } from '@orkestrel/contract';
-import { ReasonInterface } from '@orkestrel/reason';
-import { ReasonValidationResult } from '@orkestrel/reason';
-import { RecordOptions } from '@orkestrel/interpret';
-import { StringShape } from '@orkestrel/contract';
-import { Subject } from '@orkestrel/reason';
+import type { ReasonInterface } from '@orkestrel/reason';
+import type { ReasonValidationResult } from '@orkestrel/reason';
+import type { RecordOptions } from '@orkestrel/interpret';
+import type { StringShape } from '@orkestrel/contract';
+import type { Subject } from '@orkestrel/reason';
 
 /**
  * Narrows unknown data to a `Brief`, throwing when it is off-contract.
@@ -133,7 +133,13 @@ import { Subject } from '@orkestrel/reason';
      destroy(): void;
  }
 
- /** Declares the `BriefCompiler`'s push observation surface. */
+ /**
+  * Declares the `BriefCompiler`'s push observation surface.
+  *
+  * @remarks
+  * `compile` carries the `Briefing` the call produced, `block` carries the blocking `Gap` list
+  * that stopped emission, `error` carries the thrown value, and `destroy` carries nothing.
+  */
  export declare type BriefCompilerEventMap = {
      readonly compile: readonly [briefing: Briefing];
      readonly block: readonly [questions: readonly Gap[]];
@@ -143,11 +149,39 @@ import { Subject } from '@orkestrel/reason';
 
  /** Declares the compilation orchestrator contract. */
  export declare interface BriefCompilerInterface {
+     /** Holds the typed emitter carrying `compile`, `block`, `error`, and `destroy`. */
      readonly emitter: EmitterInterface<BriefCompilerEventMap>;
+     /** Holds the interpret pipeline the `interpret` stage delegates to, owned or borrowed. */
      readonly interpret: InterpretInterface;
+     /** Holds the reasoner the gate evaluates its `LogicalDefinition` on, owned or borrowed. */
      readonly reason: ReasonInterface;
+     /**
+      * Runs the `interpret` → `draft` → `gate` → `pin` pipeline over a `BriefInput`, returning a
+      * complete or visible-incomplete result.
+      *
+      * @remarks
+      * Synchronous, and it never throws for a brief it cannot emit: a blocking gap, a refused
+      * gate, and a thrown stage each record their cause on `failures` and leave `brief` absent.
+      *
+      * @param input - The caller's text, interpretation, and authored sections.
+      * @returns The `Briefing` for this call, complete exactly when `brief` is present.
+      */
      compile(input: BriefInput): Briefing;
+     /**
+      * Evaluates one brief's readiness through the reasons gate — `briefToSubject` against
+      * `buildGateDefinition()`.
+      *
+      * @param brief - The brief to measure.
+      * @returns The reasoner's traceable verdict, whose `conclusion` is the `ready` fact.
+      */
      gate(brief: Brief): LogicalResult;
+     /**
+      * Tears the orchestrator down idempotently — owned engines first, the emitter last.
+      *
+      * @remarks
+      * Emits `destroy` between the two, and releases only the engines it created. Every method
+      * except this one throws `BriefError('DESTROYED', …)` afterwards.
+      */
      destroy(): void;
  }
 
@@ -203,6 +237,9 @@ import { Subject } from '@orkestrel/reason';
   * Represents the one error class this package throws.
   *
   * @remarks
+  * Extends `Error` with a readonly `code` on the `BriefErrorCode` vocabulary and an optional
+  * readonly `context` record carrying whatever the raising site can supply.
+  *
   * Throws are reserved for caller misuse: `assertBrief`, `snapshotBrief`, and `pinBrief` on
   * off-contract data throw `INVALID`; any method after `destroy()` throws `DESTROYED`; and `BriefCompiler.gate` throws
   * `GATE_FAILED` when a borrowed reasoner returns a non-logical result. A stage that fails
@@ -258,7 +295,7 @@ import { Subject } from '@orkestrel/reason';
   * types — import them from `@orkestrel/interpret` and `@orkestrel/reason`.
   *
   * `digest` identifies this OUTCOME — the brief, the questions, and the failures together — so
-  * two identical compiles share it and a refused compile has one just as a complete one does.
+  * two identical compiles share it and a refused compile has one the same way a complete one does.
   * It is not `Brief.hash`, which identifies the brief's content alone and exists only on an
   * emitted brief. Key a cache of compile results by `digest`; key a registry of briefs by
   * `hash`.
@@ -340,7 +377,13 @@ import { Subject } from '@orkestrel/reason';
      destroy(): void;
  }
 
- /** Declares the `BriefManager`'s push observation surface. */
+ /**
+  * Declares the `BriefManager`'s push observation surface.
+  *
+  * @remarks
+  * `add` and `remove` each carry the record id the store minted from the brief's content hash,
+  * and `destroy` carries nothing.
+  */
  export declare type BriefManagerEventMap = {
      readonly add: readonly [id: string];
      readonly remove: readonly [id: string];
@@ -357,15 +400,62 @@ import { Subject } from '@orkestrel/reason';
   * unchanged content is a version no-op.
   */
  export declare interface BriefManagerInterface {
+     /** Holds the typed emitter carrying `add`, `remove`, and `destroy`. */
      readonly emitter: EmitterInterface<BriefManagerEventMap>;
+     /** Holds how many records are registered. */
      readonly count: number;
+     /**
+      * Reports whether a brief with the given id is registered.
+      *
+      * @param id - The record id to look for.
+      * @returns True if a record carries that id; false otherwise.
+      */
      has(id: string): boolean;
+     /**
+      * Looks up one registered brief record by id.
+      *
+      * @param id - The record id to read.
+      * @returns The record, or `undefined` when no record carries that id.
+      */
      brief(id: string): BriefRecord | undefined;
+     /**
+      * Lists every registered brief record.
+      *
+      * @returns The records, in registration order.
+      */
      briefs(): readonly BriefRecord[];
+     /**
+      * Registers one brief from its data, minting the id from its content hash when none is given.
+      *
+      * @remarks
+      * Emits `add`. `version` bumps only when the content hash moves, so re-adding unchanged
+      * content is a no-op that keeps the record it already had.
+      *
+      * @param brief - The brief to register.
+      * @param options - An explicit `id` to key the record by.
+      * @returns The registered record.
+      */
      add(brief: Brief, options?: RecordOptions): BriefRecord;
+     /**
+      * Removes the listed briefs by id, one brief by id, or every brief.
+      *
+      * @remarks
+      * Emits `remove` once per removed id. The array overload is declared first so an id list
+      * resolves to the batch form, which reports `true` only when every listed id was present.
+      *
+      * @param ids - The record ids to remove.
+      * @returns True when every listed id was registered; false otherwise.
+      */
      remove(ids: readonly string[]): boolean;
      remove(id: string): boolean;
      remove(): void;
+     /**
+      * Tears the registry down idempotently — the collection first, the emitter last.
+      *
+      * @remarks
+      * Emits `destroy` between the two. Every method except this one throws
+      * `BriefError('DESTROYED', …)` afterwards.
+      */
      destroy(): void;
  }
 
@@ -391,80 +481,80 @@ import { Subject } from '@orkestrel/reason';
   * `trace` and `hash` are optional because `pinBrief` fills them; an unpinned draft is
   * on-contract without them.
   */
- export declare const briefShape: ObjectShape<{
-     task: ObjectShape<{
-         operation: LiteralShape<readonly TaskOperation[]>;
-         domain: LiteralShape<readonly TaskDomain[]>;
-         statement: StringShape;
-     }, false>;
-     authority: ArrayShape<ObjectShape<{
-         path: StringShape;
-         note: StringShape;
-     }, false>>;
-     manifest: ObjectShape<{
-         read: ArrayShape<ObjectShape<{
-             path: StringShape;
-             note: StringShape;
-         }, false>>;
-         edit: ArrayShape<ObjectShape<{
-             path: StringShape;
-             note: StringShape;
-         }, false>>;
-         locked: ArrayShape<ObjectShape<{
-             path: StringShape;
-             note: StringShape;
-         }, false>>;
-         forbidden: ArrayShape<ObjectShape<{
-             path: StringShape;
-             note: StringShape;
-         }, false>>;
-     }, false>;
-     outcomes: ArrayShape<ObjectShape<{
-         rank: NumberShape;
-         text: StringShape;
-         required: BooleanShape;
-     }, false>>;
-     rules: ArrayShape<StringShape>;
-     invariants: ArrayShape<StringShape>;
-     givens: ArrayShape<ObjectShape<{
-         category: StringShape;
-         name: StringShape;
-         value: StringShape;
-     }, false>>;
-     examples: ArrayShape<ObjectShape<{
-         input: StringShape;
-         output: StringShape;
-         note: OptionalShape<StringShape>;
-     }, false>>;
-     assumptions: ArrayShape<StringShape>;
-     citations: ArrayShape<ObjectShape<{
-         name: StringShape;
-         url: StringShape;
-         note: StringShape;
-     }, false>>;
-     gaps: ArrayShape<ObjectShape<{
-         field: StringShape;
-         question: StringShape;
-         blocking: BooleanShape;
-         candidates: OptionalShape<ArrayShape<StringShape>>;
-     }, false>>;
-     risks: ArrayShape<ObjectShape<{
-         severity: LiteralShape<readonly RiskSeverity[]>;
-         text: StringShape;
-         mitigation: StringShape;
-     }, false>>;
-     output: ObjectShape<{
-         format: LiteralShape<readonly OutputFormat[]>;
-         sections: OptionalShape<ArrayShape<StringShape>>;
-         include: OptionalShape<ArrayShape<StringShape>>;
-         exclude: OptionalShape<ArrayShape<StringShape>>;
-     }, false>;
-     proofs: ArrayShape<ObjectShape<{
-         text: StringShape;
-         command: StringShape;
-     }, false>>;
-     trace: OptionalShape<StringShape>;
-     hash: OptionalShape<StringShape>;
+ export declare const briefShape: ObjectShape<    {
+ task: ObjectShape<    {
+ operation: LiteralShape<readonly TaskOperation[]>;
+ domain: LiteralShape<readonly TaskDomain[]>;
+ statement: StringShape;
+ }, false>;
+ authority: ArrayShape<ObjectShape<    {
+ path: StringShape;
+ note: StringShape;
+ }, false>>;
+ manifest: ObjectShape<    {
+ read: ArrayShape<ObjectShape<    {
+ path: StringShape;
+ note: StringShape;
+ }, false>>;
+ edit: ArrayShape<ObjectShape<    {
+ path: StringShape;
+ note: StringShape;
+ }, false>>;
+ locked: ArrayShape<ObjectShape<    {
+ path: StringShape;
+ note: StringShape;
+ }, false>>;
+ forbidden: ArrayShape<ObjectShape<    {
+ path: StringShape;
+ note: StringShape;
+ }, false>>;
+ }, false>;
+ outcomes: ArrayShape<ObjectShape<    {
+ rank: NumberShape;
+ text: StringShape;
+ required: BooleanShape;
+ }, false>>;
+ rules: ArrayShape<StringShape>;
+ invariants: ArrayShape<StringShape>;
+ givens: ArrayShape<ObjectShape<    {
+ category: StringShape;
+ name: StringShape;
+ value: StringShape;
+ }, false>>;
+ examples: ArrayShape<ObjectShape<    {
+ input: StringShape;
+ output: StringShape;
+ note: OptionalShape<StringShape>;
+ }, false>>;
+ assumptions: ArrayShape<StringShape>;
+ citations: ArrayShape<ObjectShape<    {
+ name: StringShape;
+ url: StringShape;
+ note: StringShape;
+ }, false>>;
+ gaps: ArrayShape<ObjectShape<    {
+ field: StringShape;
+ question: StringShape;
+ blocking: BooleanShape;
+ candidates: OptionalShape<ArrayShape<StringShape>>;
+ }, false>>;
+ risks: ArrayShape<ObjectShape<    {
+ severity: LiteralShape<readonly RiskSeverity[]>;
+ text: StringShape;
+ mitigation: StringShape;
+ }, false>>;
+ output: ObjectShape<    {
+ format: LiteralShape<readonly OutputFormat[]>;
+ sections: OptionalShape<ArrayShape<StringShape>>;
+ include: OptionalShape<ArrayShape<StringShape>>;
+ exclude: OptionalShape<ArrayShape<StringShape>>;
+ }, false>;
+ proofs: ArrayShape<ObjectShape<    {
+ text: StringShape;
+ command: StringShape;
+ }, false>>;
+ trace: OptionalShape<StringShape>;
+ hash: OptionalShape<StringShape>;
  }, false>;
 
  /** Names the fixed compilation phases, in pipeline order. */
@@ -511,10 +601,11 @@ import { Subject } from '@orkestrel/reason';
   * Projects a brief into a subagent `Dispatch`.
   *
   * @remarks
-  * `edit` is exactly `manifest.edit`, so two dispatches whose `edit` sets do not intersect
-  * can run concurrently under the same brief without conflict.
+  * `edit` is exactly `manifest.edit` — the owned set — so two dispatches whose `edit` sets do
+  * not intersect can run concurrently under the same brief without conflict. `locked` and
+  * `forbidden` cross unchanged as the do-not-touch sets.
   *
-  * `authority` is exactly `brief.authority` in rank order, and it is a SEPARATE axis from the
+  * `authority` is exactly `brief.authority` in rank order, and it is a separate axis from the
   * permission sets rather than a further partition — a ranked path normally also appears in
   * `read` or `locked`, because the executor has to open what it obeys. It is projected as
   * paths so a machine consumer never has to parse `prompt`, which is written for a model.
@@ -588,8 +679,9 @@ import { Subject } from '@orkestrel/reason';
   * Projects a brief into the copy-ready agent prompt.
   *
   * @remarks
-  * Paths are REFERENCED, never inlined — the executor retrieves them. An empty section is
-  * omitted entirely, so the rendering carries no filler an executor must read past.
+  * Sections render in authority order, so the executor meets what wins a conflict before what
+  * it may touch. Paths are referenced, never inlined — the executor retrieves them. An empty
+  * section is omitted entirely, so the rendering carries no filler an executor must read past.
   *
   * @param input - The brief to render.
   * @returns The markdown prompt.
@@ -837,6 +929,10 @@ import { Subject } from '@orkestrel/reason';
  /**
   * Assembles a `Reference` from a path and the note that justifies listing it.
   *
+  * @remarks
+  * The one builder for an authority entry and a manifest entry alike: the container the record
+  * lands in is what says whether the path is ranked or permitted.
+  *
   * @param path - The referenced path or glob.
   * @param note - Why the path is listed.
   * @returns A fresh `Reference`.
@@ -946,10 +1042,10 @@ import { Subject } from '@orkestrel/reason';
  }
 
  /** Describes the `Citation` shape — a name, a locator, and why the source is cited. */
- export declare const citationShape: ObjectShape<{
-     name: StringShape;
-     url: StringShape;
-     note: StringShape;
+ export declare const citationShape: ObjectShape<    {
+ name: StringShape;
+ url: StringShape;
+ note: StringShape;
  }, false>;
 
  /**
@@ -998,6 +1094,45 @@ import { Subject } from '@orkestrel/reason';
   * emitter hooks.
   * @returns A working {@link BriefCompilerInterface}.
   *
+  * @example Compile and project a brief
+  * ```ts
+  * import {
+  * 	briefToGoal,
+  * 	briefToMarkdown,
+  * 	buildOutcome,
+  * 	buildProof,
+  * 	buildTask,
+  * 	createBriefCompiler,
+  * } from '@orkestrel/brief'
+  *
+  * const compiler = createBriefCompiler()
+  *
+  * const briefing = compiler.compile({
+  * 	task: buildTask('refactor', 'code', 'Refactor useForm to native browser form APIs.'),
+  * 	authority: [{ path: 'AGENTS.md', note: 'project law; wins every conflict' }],
+  * 	manifest: {
+  * 		read: [
+  * 			{ path: 'AGENTS.md', note: 'project law; wins every conflict' },
+  * 			{ path: 'guides/browser.md', note: 'the composable contract' },
+  * 		],
+  * 		edit: [{ path: 'src/browser/composables/useForm.ts', note: 'the composable being refactored' }],
+  * 		locked: [{ path: 'src/browser/types.ts', note: 'the published contract' }],
+  * 		forbidden: [{ path: 'app/**', note: 'out of scope' }],
+  * 	},
+  * 	outcomes: [buildOutcome(1, 'useForm uses native FormData with no behavior change')],
+  * 	proofs: [buildProof('type-check and lint pass', 'npm run check')],
+  * })
+  *
+  * briefing.brief !== undefined // true — the brief is present exactly when the gate passed
+  * if (briefing.brief !== undefined) {
+  * 	briefToMarkdown(briefing.brief) // the copy-ready agent prompt
+  * 	briefToGoal(briefing.brief) // the /goal completion condition
+  * }
+  *
+  * compiler.emitter.on('block', (questions) => questions.length)
+  * compiler.destroy()
+  * ```
+  *
   * @example
   * ```ts
   * import { createBriefCompiler } from '@orkestrel/brief'
@@ -1218,7 +1353,7 @@ import { Subject } from '@orkestrel/reason';
   */
  export declare function errorToMessage(error: unknown): string;
 
- /** Represents one input to output exemplar — the highest-leverage ambiguity remover. */
+ /** Represents one input to output exemplar — the ambiguity remover that leaves the least to interpret. */
  export declare interface Example {
      readonly input: string;
      readonly output: string;
@@ -1226,10 +1361,10 @@ import { Subject } from '@orkestrel/reason';
  }
 
  /** Describes the `Example` shape — one input to output exemplar. */
- export declare const exampleShape: ObjectShape<{
-     input: StringShape;
-     output: StringShape;
-     note: OptionalShape<StringShape>;
+ export declare const exampleShape: ObjectShape<    {
+ input: StringShape;
+ output: StringShape;
+ note: OptionalShape<StringShape>;
  }, false>;
 
  /**
@@ -1255,6 +1390,10 @@ import { Subject } from '@orkestrel/reason';
  /**
   * Lists the gaps that block emission.
   *
+  * @remarks
+  * A non-empty result means the gate must fail closed: a blocking gap has no safe default, so
+  * the compile yields a visible incomplete `Briefing` carrying the questions instead of a brief.
+  *
   * @param source - The brief to inspect.
   * @returns Every gap carrying `blocking: true`, in declaration order.
   *
@@ -1317,7 +1456,7 @@ import { Subject } from '@orkestrel/reason';
   * are disjoint — `findManifestOverlaps` and the `disjoint` rule enforce it — so a forbidden
   * path is in none of the grants and is reported here. An authority named in NO partition at
   * all is reported for the same reason, and that is the case a forbidden-only check misses
-  * entirely: the brief simply never says the executor may open what it must obey.
+  * entirely: the brief never says the executor may open what it must obey.
   *
   * Paths are compared as EXACT strings, matching `findManifestOverlaps`. A glob is never
   * expanded, so `read: 'guides/**'` does not grant `authority: 'guides/brief.md'`. State a
@@ -1461,11 +1600,11 @@ import { Subject } from '@orkestrel/reason';
  }
 
  /** Describes the `Gap` shape — an unknown, whether it blocks, and the candidates that would close it. */
- export declare const gapShape: ObjectShape<{
-     field: StringShape;
-     question: StringShape;
-     blocking: BooleanShape;
-     candidates: OptionalShape<ArrayShape<StringShape>>;
+ export declare const gapShape: ObjectShape<    {
+ field: StringShape;
+ question: StringShape;
+ blocking: BooleanShape;
+ candidates: OptionalShape<ArrayShape<StringShape>>;
  }, false>;
 
  /** Holds `'gate'` — the id of the `buildGateDefinition()` logical definition. */
@@ -1487,10 +1626,10 @@ import { Subject } from '@orkestrel/reason';
  }
 
  /** Describes the `Given` shape — one categorized context fact. */
- export declare const givenShape: ObjectShape<{
-     category: StringShape;
-     name: StringShape;
-     value: StringShape;
+ export declare const givenShape: ObjectShape<    {
+ category: StringShape;
+ name: StringShape;
+ value: StringShape;
  }, false>;
 
  /**
@@ -1593,6 +1732,10 @@ import { Subject } from '@orkestrel/reason';
  /**
   * Checks whether the value is a non-empty string holding no line terminator.
   *
+  * @remarks
+  * The shape of nearly every brief field: a path, a note, a statement, a rule, and a command
+  * all narrow through it.
+  *
   * @param value - The value to inspect.
   * @returns True if `value` is a non-empty string holding no line terminator; false otherwise.
   */
@@ -1707,7 +1850,7 @@ import { Subject } from '@orkestrel/reason';
   * Matches every line terminator a brief field refuses.
   *
   * @remarks
-  * Every ECMAScript line terminator, not just `\n`: a renderer that splits on any of them
+  * Every ECMAScript line terminator, not only `\n`: a renderer that splits on any of them
   * would let the others forge a markdown row. CRLF leads the alternation so a Windows
   * exemplar splits as ONE break rather than two, which would insert a blank line the caller
   * never wrote. Kept unanchored and stateless — no `g` flag — so `test` never carries
@@ -1732,24 +1875,30 @@ import { Subject } from '@orkestrel/reason';
      readonly forbidden: readonly Reference[];
  }
 
- /** Describes the `Manifest` shape — disjoint reference partitions. */
- export declare const manifestShape: ObjectShape<{
-     read: ArrayShape<ObjectShape<{
-         path: StringShape;
-         note: StringShape;
-     }, false>>;
-     edit: ArrayShape<ObjectShape<{
-         path: StringShape;
-         note: StringShape;
-     }, false>>;
-     locked: ArrayShape<ObjectShape<{
-         path: StringShape;
-         note: StringShape;
-     }, false>>;
-     forbidden: ArrayShape<ObjectShape<{
-         path: StringShape;
-         note: StringShape;
-     }, false>>;
+ /**
+  * Describes the `Manifest` shape — disjoint reference partitions.
+  *
+  * @remarks
+  * Each partition is an `arrayShape(referenceShape)`; disjointness is `validateBrief`'s pass
+  * rather than the shape's.
+  */
+ export declare const manifestShape: ObjectShape<    {
+ read: ArrayShape<ObjectShape<    {
+ path: StringShape;
+ note: StringShape;
+ }, false>>;
+ edit: ArrayShape<ObjectShape<    {
+ path: StringShape;
+ note: StringShape;
+ }, false>>;
+ locked: ArrayShape<ObjectShape<    {
+ path: StringShape;
+ note: StringShape;
+ }, false>>;
+ forbidden: ArrayShape<ObjectShape<    {
+ path: StringShape;
+ note: StringShape;
+ }, false>>;
  }, false>;
 
  /**
@@ -1764,11 +1913,16 @@ import { Subject } from '@orkestrel/reason';
      readonly required: boolean;
  }
 
- /** Describes the `Outcome` shape — a one-based rank, the result text, and whether it gates done. */
- export declare const outcomeShape: ObjectShape<{
-     rank: NumberShape;
-     text: StringShape;
-     required: BooleanShape;
+ /**
+  * Describes the `Outcome` shape — a one-based rank, the result text, and whether it gates done.
+  *
+  * @remarks
+  * `rank` is an `integerShape({ min: 1 })`, so a zero or fractional rank is off-contract.
+  */
+ export declare const outcomeShape: ObjectShape<    {
+ rank: NumberShape;
+ text: StringShape;
+ required: BooleanShape;
  }, false>;
 
  /**
@@ -1791,11 +1945,11 @@ import { Subject } from '@orkestrel/reason';
  export declare type OutputFormat = 'markdown' | 'json' | 'code' | 'diff' | 'prose';
 
  /** Describes the `Output` shape — a closed format plus its optional refinements. */
- export declare const outputShape: ObjectShape<{
-     format: LiteralShape<readonly OutputFormat[]>;
-     sections: OptionalShape<ArrayShape<StringShape>>;
-     include: OptionalShape<ArrayShape<StringShape>>;
-     exclude: OptionalShape<ArrayShape<StringShape>>;
+ export declare const outputShape: ObjectShape<    {
+ format: LiteralShape<readonly OutputFormat[]>;
+ sections: OptionalShape<ArrayShape<StringShape>>;
+ include: OptionalShape<ArrayShape<StringShape>>;
+ exclude: OptionalShape<ArrayShape<StringShape>>;
  }, false>;
 
  /**
@@ -1875,9 +2029,9 @@ import { Subject } from '@orkestrel/reason';
   }
 
   /** Describes the `Proof` shape — the claim and the command that settles it. */
-  export declare const proofShape: ObjectShape<{
-      text: StringShape;
-      command: StringShape;
+  export declare const proofShape: ObjectShape<    {
+  text: StringShape;
+  command: StringShape;
   }, false>;
 
   /**
@@ -1900,9 +2054,9 @@ import { Subject } from '@orkestrel/reason';
   }
 
   /** Describes the `Reference` shape — a path and the note that justifies listing it. */
-  export declare const referenceShape: ObjectShape<{
-      path: StringShape;
-      note: StringShape;
+  export declare const referenceShape: ObjectShape<    {
+  path: StringShape;
+  note: StringShape;
   }, false>;
 
   /** Represents one pre-empted risk and the mitigation that answers it. */
@@ -1919,14 +2073,14 @@ import { Subject } from '@orkestrel/reason';
   export declare type RiskSeverity = 'low' | 'medium' | 'high';
 
   /** Describes the `Risk` shape — a closed severity, the risk, and its mitigation. */
-  export declare const riskShape: ObjectShape<{
-      severity: LiteralShape<readonly RiskSeverity[]>;
-      text: StringShape;
-      mitigation: StringShape;
+  export declare const riskShape: ObjectShape<    {
+  severity: LiteralShape<readonly RiskSeverity[]>;
+  text: StringShape;
+  mitigation: StringShape;
   }, false>;
 
   /**
-   * Holds the positive form of {@link LINE_BREAK_PATTERN}, for the shape DSL.
+   * Holds the positive form of {@link LINE_BREAK_PATTERN}, for a `stringShape` `pattern`.
    *
    * @remarks
    * `stringShape`'s `pattern` must MATCH an accepted value, so the guard's refusal regex
@@ -1985,7 +2139,13 @@ import { Subject } from '@orkestrel/reason';
    /** Lists the `TaskDomain` values, frozen. */
    export declare const TASK_DOMAINS: readonly TaskDomain[];
 
-   /** Lists the `TaskOperation` values, frozen. */
+   /**
+    * Lists the `TaskOperation` values, frozen.
+    *
+    * @remarks
+    * Compose the tuple rather than restating its members: `literalOf(TASK_OPERATIONS)` builds the
+    * guard and `parseEnum(value, TASK_OPERATIONS)` coerces a bare value against it.
+    */
    export declare const TASK_OPERATIONS: readonly TaskOperation[];
 
    /** Names the closed vocabulary of the subject matter a brief operates on. */
@@ -2000,14 +2160,21 @@ import { Subject } from '@orkestrel/reason';
     */
    export declare type TaskOperation = 'create' | 'refactor' | 'debug' | 'extract' | 'migrate' | 'explain' | 'review' | 'optimize' | 'audit' | 'test' | 'document' | 'plan';
 
-   /** Describes the `Task` shape — closed operation and domain vocabularies plus a non-empty statement. */
-   export declare const taskShape: ObjectShape<{
-       operation: LiteralShape<readonly TaskOperation[]>;
-       domain: LiteralShape<readonly TaskDomain[]>;
-       statement: StringShape;
+   /**
+    * Describes the `Task` shape — closed operation and domain vocabularies plus a non-empty
+    * statement.
+    *
+    * @remarks
+    * `literalShape(TASK_OPERATIONS)` and `literalShape(TASK_DOMAINS)` compile the same tuples the
+    * guards read, and `statement` carries `min: 1`.
+    */
+   export declare const taskShape: ObjectShape<    {
+   operation: LiteralShape<readonly TaskOperation[]>;
+   domain: LiteralShape<readonly TaskDomain[]>;
+   statement: StringShape;
    }, false>;
 
-   /** Describes a single-line string of any length, including empty. */
+   /** Describes a single-line string of any length, including empty — the shape mirror of `isText`. */
    export declare const textShape: StringShape;
 
    /**