@orkestrel/brief 0.0.7 → 0.0.8

package/README.md

@@ -1,17 +1,29 @@
 # @orkestrel/brief
 
-A synchronous, deterministic specification compiler. A rough request compiles into a
-`Brief` — a closed, JSON-serializable execution contract another agent can run with no
-interpretation left to do — and every downstream artifact (the prompt a model reads, a
-completion condition, a subagent dispatch) is projected from that one source of truth.
+> The specification compiler: a synchronous, deterministic pipeline that resolves a rough
+> request into a `Brief` — a closed, content-hashed execution contract another agent can run
+> with no interpretation left to do — gated by a traceable reasoner and projected into every
+> downstream artifact.
 
-A brief with blocking gaps never emits. The readiness gate is a `@orkestrel/reason`
-`LogicalDefinition`, so every verdict carries a traceable account of which check missed.
+Compile a request with the `createBriefCompiler` factory, read the `Briefing` it returns, and
+project the brief it carries into the prompt a model reads, a completion condition, or a
+subagent dispatch. A brief with blocking gaps never emits: the readiness gate is a
+`@orkestrel/reason` `LogicalDefinition`, so every verdict carries a traceable account of which
+check missed. Part of the `@orkestrel` line.
+
+## Install
 
 ```sh
 npm install @orkestrel/brief
 ```
 
+## Requirements
+
+- Node.js >= 22.12.0, matching the `engines` field in `package.json`
+- ESM and CommonJS entry points, selected by the `exports` field in `package.json`
+
+## Usage
+
 ```ts
 import {
 	createBriefCompiler,
@@ -36,6 +48,8 @@ if (briefing.brief !== undefined) {
 compiler.destroy()
 ```
 
+## Guide
+
 Full documentation: [`guides/brief.md`](guides/brief.md). The guides index lives at
 [`guides/README.md`](guides/README.md).
 

package/dist/src/core/index.cjs

@@ -4,7 +4,13 @@ let _orkestrel_interpret = require("@orkestrel/interpret");
 let _orkestrel_reason = require("@orkestrel/reason");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 //#region src/core/constants.ts
-/** 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.
+*/
 var TASK_OPERATIONS = Object.freeze([
 	"create",
 	"refactor",
@@ -87,7 +93,7 @@ var GATE_ID = "gate";
 * 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
@@ -95,7 +101,7 @@ var GATE_ID = "gate";
 */
 var LINE_BREAK_PATTERN = /\r\n|[\n\r\u2028\u2029]/;
 /**
-* 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
@@ -121,6 +127,9 @@ var BLANK_PATTERN = /^ +$/;
 * 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
@@ -169,14 +178,21 @@ function isBriefError(value) {
 }
 //#endregion
 //#region src/core/shapers.ts
-/** 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`. */
 var textShape = (0, _orkestrel_contract.stringShape)({ pattern: SINGLE_LINE_PATTERN });
 /** Describes a non-empty single-line string — the shape mirror of `isLine`. */
 var lineShape = (0, _orkestrel_contract.stringShape)({
 	min: 1,
 	pattern: SINGLE_LINE_PATTERN
 });
-/** Describes the `Task` shape — closed operation and domain vocabularies plus a non-empty statement. */
+/**
+* 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`.
+*/
 var taskShape = (0, _orkestrel_contract.objectShape)({
 	operation: (0, _orkestrel_contract.literalShape)(TASK_OPERATIONS),
 	domain: (0, _orkestrel_contract.literalShape)(TASK_DOMAINS),
@@ -187,14 +203,25 @@ var referenceShape = (0, _orkestrel_contract.objectShape)({
 	path: lineShape,
 	note: lineShape
 }, { description: "One referenced path and why it is listed." });
-/** Describes the `Manifest` shape — disjoint reference partitions. */
+/**
+* Describes the `Manifest` shape — disjoint reference partitions.
+*
+* @remarks
+* Each partition is an `arrayShape(referenceShape)`; disjointness is `validateBrief`'s pass
+* rather than the shape's.
+*/
 var manifestShape = (0, _orkestrel_contract.objectShape)({
 	read: (0, _orkestrel_contract.arrayShape)(referenceShape),
 	edit: (0, _orkestrel_contract.arrayShape)(referenceShape),
 	locked: (0, _orkestrel_contract.arrayShape)(referenceShape),
 	forbidden: (0, _orkestrel_contract.arrayShape)(referenceShape)
 }, { description: "The disjoint file partitions of a brief." });
-/** Describes the `Outcome` shape — a one-based rank, the result text, and whether it gates done. */
+/**
+* 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.
+*/
 var outcomeShape = (0, _orkestrel_contract.objectShape)({
 	rank: (0, _orkestrel_contract.integerShape)({ min: 1 }),
 	text: lineShape,
@@ -286,6 +313,10 @@ var isText = (value) => (0, _orkestrel_contract.isString)(value) && !LINE_BREAK_
 /**
 * 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.
 */
@@ -624,6 +655,10 @@ function buildTask(operation, domain, statement) {
 /**
 * 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`.
@@ -1010,6 +1045,10 @@ function countSentences(statement) {
 /**
 * 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.
 *
@@ -1038,7 +1077,7 @@ function findBlockingGaps(source) {
 * 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
@@ -1502,8 +1541,9 @@ function exampleToLines(entry) {
 * 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.
@@ -1632,10 +1672,11 @@ function briefToGoal(input, turns = 16) {
 * 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.
@@ -2282,6 +2323,45 @@ var BriefCompiler = class {
 * 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'