@orkestrel/scaffold 0.0.123 → 0.0.125
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agents/skills/orkestrel-publish/scripts/steps.js +523 -0
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +70 -11
- package/dist/bin/main.js +18 -18
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +5 -1
- package/dist/host/agents/platforms/windows.md +9 -1
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/methods.md +30 -2
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -0
- package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +5 -1
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +23 -6
- package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +654 -0
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +79 -14
- package/dist/host/claude/agents/orkestrel.md +45 -45
- package/dist/host/claude/rules/patterns.md +1 -1
- package/dist/host/claude/rules/portability.md +2 -0
- package/dist/host/claude/rules/quality.md +3 -1
- package/dist/host/claude/rules/tests.md +3 -1
- package/dist/host/guides/agent.md +349 -244
- package/dist/host/guides/brief.md +52 -48
- package/dist/host/guides/browser.md +2 -2
- package/dist/host/guides/contract.md +226 -104
- package/dist/host/guides/database.md +12 -12
- package/dist/host/guides/interpret.md +531 -155
- package/dist/host/guides/mcp.md +183 -61
- package/dist/host/guides/ndjson.md +47 -34
- package/dist/host/guides/ollama.md +123 -66
- package/dist/host/guides/program.md +117 -39
- package/dist/host/guides/qualifier.md +110 -59
- package/dist/host/guides/rater.md +85 -32
- package/dist/host/guides/reason.md +377 -114
- package/dist/host/guides/scaffold.md +20 -12
- package/dist/host/guides/study.md +580 -483
- package/dist/host/guides/tool.md +163 -58
- package/dist/host/guides/toolbox.md +159 -80
- package/dist/host/guides/workflow.md +44 -25
- package/dist/host/manifest.json +41 -35
- package/dist/src/core/index.cjs +17 -17
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +17 -17
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +23 -11
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +10 -6
- package/dist/src/server/index.d.ts +10 -6
- package/dist/src/server/index.js +23 -11
- package/dist/src/server/index.js.map +1 -1
- package/package.json +17 -17
|
@@ -106,7 +106,7 @@ pipeline at all.
|
|
|
106
106
|
| `Given` | interface | `{ category, name, value }` | Represents one context fact handed to the executor — a convention, a version, a constraint value. |
|
|
107
107
|
| `Example` | interface | `{ input, output, note? }` | Represents one input to output exemplar — the ambiguity remover that leaves the least to interpret. |
|
|
108
108
|
| `Citation` | interface | `{ name, url, note }` | Represents one external source — what it is called, where it lives, and why it is cited. |
|
|
109
|
-
| `Gap` | interface | `{ field, question, blocking, candidates? }`
|
|
109
|
+
| `Gap` | interface | `{ fault?, field, question, blocking, candidates? }` | Represents one unknown the brief has not resolved. |
|
|
110
110
|
| `Risk` | interface | `{ severity, text, mitigation }` | Represents one pre-empted risk and the mitigation that answers it. |
|
|
111
111
|
| `Output` | interface | `{ format, sections?, include?, exclude? }` | Represents the closed shape of the deliverable. |
|
|
112
112
|
| `Proof` | interface | `{ text, command }` | Represents one mechanical, transcript-provable check. |
|
|
@@ -135,20 +135,24 @@ The `Briefing` deliberately carries cross-package payloads by their originating
|
|
|
135
135
|
never re-exported here. The verdict is the gate's own traceable account: every readiness
|
|
136
136
|
check, met or missed, narrated by the reasoner.
|
|
137
137
|
|
|
138
|
+
Derived givens keep each entity's `provenance.category`: `extracted`, `carried`, `default`,
|
|
139
|
+
`computed`, or `subject`. A derived gap keeps its ambiguity's `fault`, when present, and
|
|
140
|
+
its supplied question text. Required ambiguities remain blocking gaps.
|
|
141
|
+
|
|
138
142
|
### Constants
|
|
139
143
|
|
|
140
|
-
| Name | Kind | Signature
|
|
141
|
-
| ------------------------ | ----- |
|
|
142
|
-
| `TASK_OPERATIONS` | const | `readonly TaskOperation[]`
|
|
143
|
-
| `TASK_DOMAINS` | const | `readonly TaskDomain[]`
|
|
144
|
-
| `OUTPUT_FORMATS` | const | `readonly OutputFormat[]`
|
|
145
|
-
| `RISK_SEVERITIES` | const | `readonly RiskSeverity[]`
|
|
146
|
-
| `INTERPRETATION_MEMBERS` | const | `readonly ("ambiguities" \| "confidence" \| "definition" \| "digest" \| "entities" \| "failures" \| "intent" \| "mappings" \| "normalized" \| "prompt" \| "stages" \| "subject" \| "text")[]` | Lists every published `Interpretation` member name, frozen. |
|
|
147
|
-
| `DEFAULT_BRIEF_TURNS` | const | `16`
|
|
148
|
-
| `GATE_ID` | const | `"gate"`
|
|
149
|
-
| `LINE_BREAK_PATTERN` | const | `RegExp`
|
|
150
|
-
| `SINGLE_LINE_PATTERN` | const | `RegExp`
|
|
151
|
-
| `BLANK_PATTERN` | const | `RegExp`
|
|
144
|
+
| Name | Kind | Signature | Summary |
|
|
145
|
+
| ------------------------ | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
146
|
+
| `TASK_OPERATIONS` | const | `readonly TaskOperation[]` | Lists the `TaskOperation` values, frozen. |
|
|
147
|
+
| `TASK_DOMAINS` | const | `readonly TaskDomain[]` | Lists the `TaskDomain` values, frozen. |
|
|
148
|
+
| `OUTPUT_FORMATS` | const | `readonly OutputFormat[]` | Lists the `OutputFormat` values, frozen. |
|
|
149
|
+
| `RISK_SEVERITIES` | const | `readonly RiskSeverity[]` | Lists the `RiskSeverity` values, frozen. |
|
|
150
|
+
| `INTERPRETATION_MEMBERS` | const | `readonly ("ambiguities" \| "confidence" \| "defaulted" \| "definition" \| "digest" \| "entities" \| "failures" \| "intent" \| "mappings" \| "normalized" \| "prompt" \| "recipe" \| "refusals" \| "repairs" \| "stages" \| "subject" \| "text" \| "version")[]` | Lists every published `Interpretation` member name, frozen. |
|
|
151
|
+
| `DEFAULT_BRIEF_TURNS` | const | `16` | Holds `16` — the default turn cap `briefToGoal` renders. |
|
|
152
|
+
| `GATE_ID` | const | `"gate"` | Holds `'gate'` — the id of the `buildGateDefinition()` logical definition. |
|
|
153
|
+
| `LINE_BREAK_PATTERN` | const | `RegExp` | Matches every line terminator a brief field refuses. |
|
|
154
|
+
| `SINGLE_LINE_PATTERN` | const | `RegExp` | Holds the positive form of `LINE_BREAK_PATTERN`, for a `stringShape` `pattern`. |
|
|
155
|
+
| `BLANK_PATTERN` | const | `RegExp` | Matches a string of one or more spaces and nothing else. |
|
|
152
156
|
|
|
153
157
|
An interpretation the compiler reads is foreign data, and a class instance carries its contract
|
|
154
158
|
on the prototype, so `BriefCompiler` materializes the members `INTERPRETATION_MEMBERS` names into
|
|
@@ -307,26 +311,25 @@ value; `briefShape` composes the section shapes, and `createBriefContract()` com
|
|
|
307
311
|
The guard family and the shape family are independent mechanisms over one vocabulary.
|
|
308
312
|
That is deliberate: a single source could not disagree with itself, so it could never catch
|
|
309
313
|
a mistake. [`tests/src/core/shapers.test.ts`](../tests/src/core/shapers.test.ts) drives both
|
|
310
|
-
over the same values
|
|
311
|
-
`
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
|
315
|
-
|
|
|
316
|
-
| `
|
|
317
|
-
| `
|
|
318
|
-
| `
|
|
319
|
-
| `
|
|
320
|
-
| `
|
|
321
|
-
| `
|
|
322
|
-
| `
|
|
323
|
-
| `
|
|
324
|
-
| `
|
|
325
|
-
| `
|
|
326
|
-
| `
|
|
327
|
-
| `
|
|
328
|
-
| `
|
|
329
|
-
| `briefShape` | const | `import("@orkestrel/contract").ObjectShape<{ task: import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly import("./types.js").TaskOperation[]>; domain: import("@orkestrel/contract").LiteralShape<readonly import("./types.js").TaskDomain[]>; statement: StringShape; }, false>; authority: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>>; manifest: import("@orkestrel/contract").ObjectShape<{ read: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>>; edit: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>>; locked: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>>; forbidden: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>>; }, false>; outcomes: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ rank: import("@orkestrel/contract").NumberShape; text: StringShape; required: import("@orkestrel/contract").BooleanShape; }, false>>; rules: import("@orkestrel/contract").ArrayShape<StringShape>; invariants: import("@orkestrel/contract").ArrayShape<StringShape>; givens: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ category: StringShape; name: StringShape; value: StringShape; }, false>>; examples: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ input: StringShape; output: StringShape; note: import("@orkestrel/contract").OptionalShape<StringShape>; }, false>>; assumptions: import("@orkestrel/contract").ArrayShape<StringShape>; citations: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ name: StringShape; url: StringShape; note: StringShape; }, false>>; gaps: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ field: StringShape; question: StringShape; blocking: import("@orkestrel/contract").BooleanShape; candidates: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<StringShape>>; }, false>>; risks: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ severity: import("@orkestrel/contract").LiteralShape<readonly import("./types.js").RiskSeverity[]>; text: StringShape; mitigation: StringShape; }, false>>; output: import("@orkestrel/contract").ObjectShape<{ format: import("@orkestrel/contract").LiteralShape<readonly import("./types.js").OutputFormat[]>; sections: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<StringShape>>; include: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<StringShape>>; exclude: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<StringShape>>; }, false>; proofs: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ text: StringShape; command: StringShape; }, false>>; trace: import("@orkestrel/contract").OptionalShape<StringShape>; hash: import("@orkestrel/contract").OptionalShape<StringShape>; }, false>` | Describes the whole `Brief` shape, section shapes composed. |
|
|
314
|
+
over the same values. `createBriefContract` returns `ContractInterface<Infer<typeof briefShape>>`; the value type follows the composed shape. Definitions cross through the contract's `is` method,
|
|
315
|
+
never its coercing `parse` method. The stored round trip remains JSON text through `parseBrief`.
|
|
316
|
+
|
|
317
|
+
| Name | Kind | Signature | Summary |
|
|
318
|
+
| ---------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
319
|
+
| `textShape` | const | `StringShape` | Describes a single-line string of any length, including empty — the shape mirror of `isText`. |
|
|
320
|
+
| `lineShape` | const | `StringShape` | Describes a non-empty single-line string — the shape mirror of `isLine`. |
|
|
321
|
+
| `taskShape` | const | `import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly import("./types.js").TaskOperation[]>; domain: import("@orkestrel/contract").LiteralShape<readonly import("./types.js").TaskDomain[]>; statement: StringShape; }, false>` | Describes the `Task` shape — closed operation and domain vocabularies plus a non-empty statement. |
|
|
322
|
+
| `referenceShape` | const | `import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>` | Describes the `Reference` shape — a path and the note that justifies listing it. |
|
|
323
|
+
| `manifestShape` | const | `import("@orkestrel/contract").ObjectShape<{ read: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>>; edit: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>>; locked: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>>; forbidden: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>>; }, false>` | Describes the `Manifest` shape — disjoint reference partitions. |
|
|
324
|
+
| `outcomeShape` | const | `import("@orkestrel/contract").ObjectShape<{ rank: import("@orkestrel/contract").NumberShape; text: StringShape; required: import("@orkestrel/contract").BooleanShape; }, false>` | Describes the `Outcome` shape — a one-based rank, the result text, and whether it gates done. |
|
|
325
|
+
| `givenShape` | const | `import("@orkestrel/contract").ObjectShape<{ category: StringShape; name: StringShape; value: StringShape; }, false>` | Describes the `Given` shape — one categorized context fact. |
|
|
326
|
+
| `exampleShape` | const | `import("@orkestrel/contract").ObjectShape<{ input: StringShape; output: StringShape; note: import("@orkestrel/contract").OptionalShape<StringShape>; }, false>` | Describes the `Example` shape — one input to output exemplar. |
|
|
327
|
+
| `citationShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: StringShape; url: StringShape; note: StringShape; }, false>` | Describes the `Citation` shape — a name, a locator, and why the source is cited. |
|
|
328
|
+
| `gapShape` | const | `import("@orkestrel/contract").ObjectShape<{ field: StringShape; question: StringShape; blocking: import("@orkestrel/contract").BooleanShape; candidates: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<StringShape>>; fault: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["type"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; expected: import("@orkestrel/contract").LiteralShape<readonly import("@orkestrel/contract").FaultKind[]>; received: StringShape; }, false>, import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["missing"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; expected: import("@orkestrel/contract").LiteralShape<readonly import("@orkestrel/contract").FaultKind[]>; }, false>, import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["constraint"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; expected: import("@orkestrel/contract").LiteralShape<readonly import("@orkestrel/contract").FaultKind[]>; constraint: import("@orkestrel/contract").LiteralShape<readonly import("@orkestrel/contract").FaultConstraint[]>; limit: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").NumberShape, StringShape]>>; received: StringShape; }, false>, import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["variant"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; variants: import("@orkestrel/contract").NumberShape; }, false>, import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["variant"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; variants: import("@orkestrel/contract").NumberShape; key: StringShape; expected: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").NumberShape, import("@orkestrel/contract").BooleanShape]>>; }, false>, import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["oneOf"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; matched: import("@orkestrel/contract").NumberShape; }, false>, import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["oneOf"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; matched: import("@orkestrel/contract").NumberShape; key: StringShape; expected: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").NumberShape, import("@orkestrel/contract").BooleanShape]>>; }, false>, import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["extra"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; }, false>]>>; }, false>` | Describes the `Gap` shape — an unknown, whether it blocks, and the candidates that would close it. |
|
|
329
|
+
| `riskShape` | const | `import("@orkestrel/contract").ObjectShape<{ severity: import("@orkestrel/contract").LiteralShape<readonly import("./types.js").RiskSeverity[]>; text: StringShape; mitigation: StringShape; }, false>` | Describes the `Risk` shape — a closed severity, the risk, and its mitigation. |
|
|
330
|
+
| `outputShape` | const | `import("@orkestrel/contract").ObjectShape<{ format: import("@orkestrel/contract").LiteralShape<readonly import("./types.js").OutputFormat[]>; sections: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<StringShape>>; include: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<StringShape>>; exclude: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<StringShape>>; }, false>` | Describes the `Output` shape — a closed format plus its optional refinements. |
|
|
331
|
+
| `proofShape` | const | `import("@orkestrel/contract").ObjectShape<{ text: StringShape; command: StringShape; }, false>` | Describes the `Proof` shape — the claim and the command that settles it. |
|
|
332
|
+
| `briefShape` | const | `import("@orkestrel/contract").ObjectShape<{ task: import("@orkestrel/contract").ObjectShape<{ operation: import("@orkestrel/contract").LiteralShape<readonly import("./types.js").TaskOperation[]>; domain: import("@orkestrel/contract").LiteralShape<readonly import("./types.js").TaskDomain[]>; statement: StringShape; }, false>; authority: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>>; manifest: import("@orkestrel/contract").ObjectShape<{ read: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>>; edit: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>>; locked: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>>; forbidden: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ path: StringShape; note: StringShape; }, false>>; }, false>; outcomes: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ rank: import("@orkestrel/contract").NumberShape; text: StringShape; required: import("@orkestrel/contract").BooleanShape; }, false>>; rules: import("@orkestrel/contract").ArrayShape<StringShape>; invariants: import("@orkestrel/contract").ArrayShape<StringShape>; givens: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ category: StringShape; name: StringShape; value: StringShape; }, false>>; examples: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ input: StringShape; output: StringShape; note: import("@orkestrel/contract").OptionalShape<StringShape>; }, false>>; assumptions: import("@orkestrel/contract").ArrayShape<StringShape>; citations: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ name: StringShape; url: StringShape; note: StringShape; }, false>>; gaps: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ field: StringShape; question: StringShape; blocking: import("@orkestrel/contract").BooleanShape; candidates: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<StringShape>>; fault: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["type"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; expected: import("@orkestrel/contract").LiteralShape<readonly import("@orkestrel/contract").FaultKind[]>; received: StringShape; }, false>, import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["missing"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; expected: import("@orkestrel/contract").LiteralShape<readonly import("@orkestrel/contract").FaultKind[]>; }, false>, import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["constraint"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; expected: import("@orkestrel/contract").LiteralShape<readonly import("@orkestrel/contract").FaultKind[]>; constraint: import("@orkestrel/contract").LiteralShape<readonly import("@orkestrel/contract").FaultConstraint[]>; limit: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").NumberShape, StringShape]>>; received: StringShape; }, false>, import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["variant"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; variants: import("@orkestrel/contract").NumberShape; }, false>, import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["variant"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; variants: import("@orkestrel/contract").NumberShape; key: StringShape; expected: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").NumberShape, import("@orkestrel/contract").BooleanShape]>>; }, false>, import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["oneOf"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; matched: import("@orkestrel/contract").NumberShape; }, false>, import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["oneOf"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; matched: import("@orkestrel/contract").NumberShape; key: StringShape; expected: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").NumberShape, import("@orkestrel/contract").BooleanShape]>>; }, false>, import("@orkestrel/contract").ObjectShape<{ reason: import("@orkestrel/contract").LiteralShape<readonly ["extra"]>; path: import("@orkestrel/contract").UnionShape<readonly [StringShape, import("@orkestrel/contract").ArrayShape<StringShape>]>; }, false>]>>; }, false>>; risks: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ severity: import("@orkestrel/contract").LiteralShape<readonly import("./types.js").RiskSeverity[]>; text: StringShape; mitigation: StringShape; }, false>>; output: import("@orkestrel/contract").ObjectShape<{ format: import("@orkestrel/contract").LiteralShape<readonly import("./types.js").OutputFormat[]>; sections: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<StringShape>>; include: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<StringShape>>; exclude: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<StringShape>>; }, false>; proofs: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ text: StringShape; command: StringShape; }, false>>; trace: import("@orkestrel/contract").OptionalShape<StringShape>; hash: import("@orkestrel/contract").OptionalShape<StringShape>; }, false>` | Describes the whole `Brief` shape, section shapes composed. |
|
|
330
333
|
|
|
331
334
|
```ts
|
|
332
335
|
import {
|
|
@@ -599,7 +602,7 @@ already own, and cross `snapshotBrief` when you want intake to own it for you.
|
|
|
599
602
|
| --------------------- | -------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
|
|
600
603
|
| `createBriefCompiler` | function | `(options?: BriefCompilerOptions) => BriefCompilerInterface` | Creates a compilation orchestrator. |
|
|
601
604
|
| `createBriefManager` | function | `(options?: BriefManagerOptions) => BriefManagerInterface` | Creates a brief registry. |
|
|
602
|
-
| `createBriefContract` | function | `() => ContractInterface<
|
|
605
|
+
| `createBriefContract` | function | `() => ContractInterface<Infer<typeof briefShape>>` | Compiles `briefShape` into a guard, parser, JSON Schema, and seeded generator bundle. |
|
|
603
606
|
|
|
604
607
|
Every entry here builds something. `assertBrief` constructs nothing — it returns its
|
|
605
608
|
argument after the guard passes — so it is a helper, not a factory, and lives beside
|
|
@@ -675,7 +678,7 @@ const audit = buildBrief(buildTask('audit', 'code', 'Audit the barrel for undocu
|
|
|
675
678
|
|
|
676
679
|
const engine = createBriefCompiler()
|
|
677
680
|
const verdict = engine.gate(audit)
|
|
678
|
-
verdict.conclusion //
|
|
681
|
+
verdict.conclusion // 'met' — no blocking gaps, outcomes and proofs present, manifest disjoint
|
|
679
682
|
verdict.trace // the step-by-step readiness account, straight from the LogicalReasoner
|
|
680
683
|
|
|
681
684
|
const briefing = engine.compile({
|
|
@@ -788,6 +791,8 @@ These invariants hold across `src/core` and this guide:
|
|
|
788
791
|
`BriefStageRecord` is discriminated by `stage`, so that replay is readable without a single
|
|
789
792
|
type assertion. The measures and the verdict are conjoined in the refusing direction: a
|
|
790
793
|
brief must satisfy each, so a borrowed engine can withhold a pass it cannot grant.
|
|
794
|
+
Only `conclusion: 'met'` permits emission; `unmet` and `unread` refuse. Each rule's
|
|
795
|
+
`state` names whether it is met, unmet, or unread.
|
|
791
796
|
|
|
792
797
|
4. **The brief is the source of truth; projections never add.** `briefToMarkdown`,
|
|
793
798
|
`briefToGoal`, and `briefToDispatch` are pure views over the pinned brief: the prompt
|
|
@@ -818,10 +823,8 @@ These invariants hold across `src/core` and this guide:
|
|
|
818
823
|
[`tests/src/core/shapers.test.ts`](../tests/src/core/shapers.test.ts), which drives both
|
|
819
824
|
over one value set. That test is the guarantee, and it is a real one: adding a property to
|
|
820
825
|
`briefShape` that `Brief` does not have turns its assertions red.
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
positions, so it catches a shape that infers too little and would accept one that infers
|
|
824
|
-
too much.
|
|
826
|
+
The contract returns `ContractInterface<Infer<typeof briefShape>>`; runtime lockstep tests, rather than
|
|
827
|
+
its return type, compare the shape with `isBrief`.
|
|
825
828
|
7. **Coded errors.** Every throw out of this module is a `BriefError` with a machine-readable
|
|
826
829
|
code, and `catch` blocks narrow with `isBriefError`, never `as`. The `context` is whatever
|
|
827
830
|
the code can actually supply rather than a fixed pair: `DRAFT_FAILED` carries
|
|
@@ -917,6 +920,7 @@ needs an interpret pipeline that can actually match the request:
|
|
|
917
920
|
import { buildOutcome, buildOutput, buildProof, createBriefCompiler } from '@orkestrel/brief'
|
|
918
921
|
import { createInterpret } from '@orkestrel/interpret'
|
|
919
922
|
import { createQuantitativeDefinition } from '@orkestrel/reason'
|
|
923
|
+
import { numberShape, objectShape } from '@orkestrel/contract'
|
|
920
924
|
|
|
921
925
|
const migrations = createBriefCompiler({
|
|
922
926
|
interpret: createInterpret({
|
|
@@ -932,8 +936,8 @@ const migrations = createBriefCompiler({
|
|
|
932
936
|
name: 'Migration',
|
|
933
937
|
domain: 'code',
|
|
934
938
|
intents: ['migrate'],
|
|
935
|
-
mappings: [{ entity: 'count', aliases: [], field: 'count' }],
|
|
936
|
-
|
|
939
|
+
mappings: [{ entity: 'count', aliases: ['stores'], field: 'count' }],
|
|
940
|
+
shape: objectShape({ count: numberShape() }),
|
|
937
941
|
computations: [],
|
|
938
942
|
definition: createQuantitativeDefinition('migration', 'Migration', []),
|
|
939
943
|
},
|
|
@@ -944,7 +948,7 @@ const migrations = createBriefCompiler({
|
|
|
944
948
|
})
|
|
945
949
|
|
|
946
950
|
const migration = migrations.compile({
|
|
947
|
-
text: 'migrate the 3
|
|
951
|
+
text: 'migrate the 3 stores to the replacement driver seam',
|
|
948
952
|
manifest: {
|
|
949
953
|
read: [{ path: 'guides/stores.md', note: 'the driver seam contract' }],
|
|
950
954
|
edit: [{ path: 'src/core/stores/**', note: 'the three legacy stores' }],
|
|
@@ -960,7 +964,7 @@ migration.stages.map((record) => record.stage) // ['interpret', 'draft', 'gate',
|
|
|
960
964
|
migration.interpretation?.intent // { action: 'migrate', domain: 'code', confidence: 1 }
|
|
961
965
|
migration.brief?.task.operation // 'migrate' — derived through the caller vocabulary
|
|
962
966
|
migration.brief?.givens // [{ category: 'extracted', name: 'count', value: '3' }]
|
|
963
|
-
migration.verdict?.conclusion //
|
|
967
|
+
migration.verdict?.conclusion // 'met' — the gate's traceable yes
|
|
964
968
|
migration.brief !== undefined // true
|
|
965
969
|
migrations.destroy()
|
|
966
970
|
```
|
|
@@ -1003,7 +1007,7 @@ stopped.brief // undefined — the gate failed closed, and that absence is the s
|
|
|
1003
1007
|
stopped.questions // [{ field: 'output', question: 'Does the result need…', blocking: true, … }]
|
|
1004
1008
|
stopped.questions.length // 1 — one question to answer, then re-compile
|
|
1005
1009
|
stopped.failures // [{ stage: 'gate', code: 'BLOCKED', message: '1 blocking gap(s)' }]
|
|
1006
|
-
stopped.verdict?.rules.filter((entry) =>
|
|
1010
|
+
stopped.verdict?.rules.filter((entry) => entry.state !== 'met') // exactly which rules missed
|
|
1007
1011
|
stopped.verdict?.trace // the reasoner's narration of the rules that derived, not the misses
|
|
1008
1012
|
blocked.destroy()
|
|
1009
1013
|
```
|
|
@@ -1045,8 +1049,8 @@ measures // { operation: 'refactor', blocking: 0, outcomes: 2, required: 2, proo
|
|
|
1045
1049
|
|
|
1046
1050
|
const ruling = engine.reason(measures, buildGateDefinition())
|
|
1047
1051
|
if (ruling.reasoning === 'logical') {
|
|
1048
|
-
ruling.conclusion //
|
|
1049
|
-
ruling.rules.filter((entry) =>
|
|
1052
|
+
ruling.conclusion // 'met' — ready to emit
|
|
1053
|
+
ruling.rules.filter((entry) => entry.state !== 'met') // the rules that missed
|
|
1050
1054
|
}
|
|
1051
1055
|
engine.destroy()
|
|
1052
1056
|
|
|
@@ -1074,7 +1078,7 @@ engine.reason(measures, house) // conclusion is `fit` — base readiness AND anc
|
|
|
1074
1078
|
|
|
1075
1079
|
Keep `buildGateDefinition().rules` whole. `fit` reads the `ready` fact, so dropping the rule that
|
|
1076
1080
|
derives it leaves `fit` conjoining something nothing proved, and a base-ready brief concludes
|
|
1077
|
-
`
|
|
1081
|
+
`'unread'`.
|
|
1078
1082
|
|
|
1079
1083
|
**`compile` does not decide readiness with this definition.** `findUnmetRules(brief)` measures
|
|
1080
1084
|
the same readiness rules in code and refuses before any verdict is read; the preceding definition is
|
|
@@ -1086,7 +1090,7 @@ keeps them saying the same thing.
|
|
|
1086
1090
|
**`buildGateDefinition()` takes no arguments, and there is no option that reaches it.** That is
|
|
1087
1091
|
the design, not an omission. The reasoner overlays every derived fact into one flat
|
|
1088
1092
|
namespace, so a caller rule named for a readiness fact — `specified`, `proven`, `single` —
|
|
1089
|
-
overwrites the fact `ready` conjoins, and a brief carrying a blocking gap concludes `
|
|
1093
|
+
overwrites the fact `ready` conjoins, and a brief carrying a blocking gap concludes `'met'`.
|
|
1090
1094
|
A gate whose whole job is to fail closed cannot take rules from the caller it is gating.
|
|
1091
1095
|
|
|
1092
1096
|
Readiness is this package's contract. A caller who needs different readiness composes their
|