@shardworks/astrolabe-apparatus 0.1.291 → 0.1.292

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardworks/astrolabe-apparatus",
-  "version": "0.1.291",
+  "version": "0.1.292",
   "license": "ISC",
   "repository": {
     "type": "git",
@@ -20,18 +20,18 @@
   },
   "dependencies": {
     "zod": "4.3.6",
-    "@shardworks/stacks-apparatus": "0.1.291",
-    "@shardworks/tools-apparatus": "0.1.291",
-    "@shardworks/clerk-apparatus": "0.1.291",
-    "@shardworks/spider-apparatus": "0.1.291",
-    "@shardworks/fabricator-apparatus": "0.1.291",
-    "@shardworks/loom-apparatus": "0.1.291",
-    "@shardworks/animator-apparatus": "0.1.291",
-    "@shardworks/clockworks-apparatus": "0.1.291"
+    "@shardworks/tools-apparatus": "0.1.292",
+    "@shardworks/stacks-apparatus": "0.1.292",
+    "@shardworks/clerk-apparatus": "0.1.292",
+    "@shardworks/spider-apparatus": "0.1.292",
+    "@shardworks/fabricator-apparatus": "0.1.292",
+    "@shardworks/loom-apparatus": "0.1.292",
+    "@shardworks/clockworks-apparatus": "0.1.292",
+    "@shardworks/animator-apparatus": "0.1.292"
   },
   "devDependencies": {
     "@types/node": "25.5.0",
-    "@shardworks/nexus-core": "0.1.291"
+    "@shardworks/nexus-core": "0.1.292"
   },
   "files": [
     "dist",

package/sage-primer-attended.md

@@ -73,7 +73,13 @@ When citing click-derived reasoning in a decision's `rationale`, reference the c
 
 **Goal:** Map the landscape the change operates in. Understand scope, blast radius, cross-cutting concerns, and existing patterns. Pure reading — no design thinking yet.
 
-Your inventory feeds a downstream spec writer who produces **intent-based briefs** (not prescriptive implementation specs). The spec writer needs to understand the *landscape* — what systems are involved, where the concerns cross-cut, what patterns constrain the design — not a transcription of every type signature and function body.
+Your inventory feeds a downstream spec writer who produces **intent-based briefs** — directing *what* to build and *why*, not prescribing *how* the implementer should write each function. The implementer still owns implementation choices.
+
+But "intent, not implementation" does **not** mean "no reference material." **Inline excerpts of existing code, types, and documentation** the implementer will use as input — type signatures of APIs they'll call, pattern shapes of sibling features they'll mirror, the §-section of a doc the change will edit.
+
+The dividing line is **reference, not prescription** — inline a type signature so the implementer knows the API surface; do **not** write the function body for them. Inline a pattern shape so they can mirror it; do **not** specify the file-by-file changes. Reference excerpts inform the implementer's own audit; they do not replace it.
+
+When you cite a file that the implementer needs no further content from (referenced only to establish blast radius or as a pointer, but no excerpt is needed and no changes are expected), annotate it with **`Do not Read.`** explicitly.
 
 **Scope and blast radius:**
 - Which packages, plugins, and systems does this change affect?
@@ -81,10 +87,12 @@ Your inventory feeds a downstream spec writer who produces **intent-based briefs
 - When the change affects a pipeline (data flows through A → B → C), trace the full chain — not just the file being modified, but the upstream producer and downstream consumer. Read the actual implementation at each stage, not just the interface.
 
 **Key types and interfaces:**
-- Identify the types and interfaces central to the change. Describe their shape and role — you do not need to copy full signatures verbatim unless they are small and critical for understanding a decision point. The implementer will read the actual code; your job is to point them to the right places and explain what matters.
+- Identify the types and interfaces central to the change and **inline their actual signatures** in the inventory, with a one-line role description alongside each.
+- For very large or peripheral types where inlining would itself be expensive, summarize the shape and link — but default to inlining when the implementer will need to use the type to do the work.
 
 **Adjacent patterns:**
-- How do sibling features or neighboring apparatus handle the same kind of problem? Read comparable implementations if they exist (aim for 2-3). If the feature is novel with no clear siblings, note that — the absence of precedent is itself useful information for design decisions.
+- How do sibling features or neighboring apparatus handle the same kind of problem? Read 2-3 comparable implementations if they exist. **Inline a representative pattern excerpt** (typically 20-40 lines) showing the shape the new feature should mirror, with a note like "apply this shape to `{target}`."
+- If the feature is novel with no clear siblings, note that — the absence of precedent is itself useful information for design decisions.
 - What conventions does the codebase use for this kind of thing? (File layout, naming, error handling, config shape)
 
 **Existing context:**
@@ -95,7 +103,7 @@ Your inventory feeds a downstream spec writer who produces **intent-based briefs
 - Note any places where documentation describes different behavior than the code implements. Capture them in the inventory as data points; do NOT lift to observations unless they meet the *Observations* bar (real bug, real cross-cutting design Q, real consolidation, real hidden-migration evidence).
 - **Tag drift on files the commission will already be touching as `concurrent doc updates needed`** — the implementing artificer will fix this inline as part of the work. Do not separately lift it as an observation.
 
-This is a working document — rough, thorough, and unpolished. Do not spend effort on formatting or prose quality. Its value is in completeness of *coverage* (every relevant system identified, every cross-cutting concern surfaced) and analytical orientation (downstream agents can form decisions from your map), not in transcribing code.
+This is a working document — rough, thorough, and unpolished. Do not spend effort on formatting or prose quality. Its value is in completeness of *coverage* (every relevant system identified, every cross-cutting concern surfaced), inlined reference material, and analytical orientation (downstream agents can form decisions from your map).
 
 ---
 

package/sage-primer-reader.md

@@ -41,7 +41,13 @@ You also have the standard file-reading tools (Read, Glob, Grep) for exploring t
 
 **Goal:** Map the landscape the change operates in. Understand scope, blast radius, cross-cutting concerns, and existing patterns. Pure reading — no design thinking yet.
 
-Your inventory feeds a downstream scoping primer and spec writer who produce **intent-based briefs** (not prescriptive implementation specs). They need to understand the *landscape* — what systems are involved, where the concerns cross-cut, what patterns constrain the design — not a transcription of every type signature and function body.
+Your inventory feeds a downstream scoping primer and spec writer who produce **intent-based briefs** — directing *what* to build and *why*, not prescribing *how* the implementer should write each function. The implementer still owns implementation choices.
+
+But "intent, not implementation" does **not** mean "no reference material." **Inline excerpts of existing code, types, and documentation** the implementer will use as input — type signatures of APIs they'll call, pattern shapes of sibling features they'll mirror, the §-section of a doc the change will edit.
+
+The dividing line is **reference, not prescription** — inline a type signature so the implementer knows the API surface; do **not** write the function body for them. Inline a pattern shape so they can mirror it; do **not** specify the file-by-file changes. Reference excerpts inform the implementer's own audit; they do not replace it.
+
+When you cite a file that the implementer needs no further content from (referenced only to establish blast radius or as a pointer, but no excerpt is needed and no changes are expected), annotate it with **`Do not Read.`** explicitly.
 
 **Scope and blast radius:**
 - Which packages, plugins, and systems does this change affect?
@@ -49,10 +55,12 @@ Your inventory feeds a downstream scoping primer and spec writer who produce **i
 - When the change affects a pipeline (data flows through A → B → C), trace the full chain — not just the file being modified, but the upstream producer and downstream consumer. Read the actual implementation at each stage, not just the interface.
 
 **Key types and interfaces:**
-- Identify the types and interfaces central to the change. Describe their shape and role — you do not need to copy full signatures verbatim unless they are small and critical for understanding a decision point. The implementer will read the actual code; your job is to point them to the right places and explain what matters.
+- Identify the types and interfaces central to the change and **inline their actual signatures** in the inventory, with a one-line role description alongside each.
+- For very large or peripheral types where inlining would itself be expensive, summarize the shape and link — but default to inlining when the implementer will need to use the type to do the work.
 
 **Adjacent patterns:**
-- How do sibling features or neighboring apparatus handle the same kind of problem? Read comparable implementations if they exist (aim for 2-3). If the feature is novel with no clear siblings, note that — the absence of precedent is itself useful information for design decisions.
+- How do sibling features or neighboring apparatus handle the same kind of problem? Read 2-3 comparable implementations if they exist. **Inline a representative pattern excerpt** (typically 20-40 lines) showing the shape the new feature should mirror, with a note like "apply this shape to `{target}`."
+- If the feature is novel with no clear siblings, note that — the absence of precedent is itself useful information for design decisions.
 - What conventions does the codebase use for this kind of thing? (File layout, naming, error handling, config shape)
 
 **Existing context:**
@@ -72,7 +80,7 @@ Your inventory feeds a downstream scoping primer and spec writer who produce **i
   - **`live`** — still open. Flag as a dependency in the inventory if the brief's approach hinges on it.
   - **`dropped`** — abandoned; context only, not load-bearing.
 
-This is a working document — rough, thorough, and unpolished. Do not spend effort on formatting or prose quality. Its value is in completeness of *coverage* (every relevant system identified, every cross-cutting concern surfaced) and analytical orientation (downstream agents can form decisions from your map), not in transcribing code.
+This is a working document — rough, thorough, and unpolished. Do not spend effort on formatting or prose quality. Its value is in completeness of *coverage* (every relevant system identified, every cross-cutting concern surfaced), inlined reference material, and analytical orientation (downstream agents can form decisions from your map).
 
 ### Boundaries
 

package/sage-primer-solo.md

@@ -73,7 +73,13 @@ When citing click-derived reasoning in a decision's `rationale`, reference the c
 
 **Goal:** Map the landscape the change operates in. Understand scope, blast radius, cross-cutting concerns, and existing patterns. Pure reading — no design thinking yet.
 
-Your inventory feeds a downstream spec writer who produces **intent-based briefs** (not prescriptive implementation specs). The spec writer needs to understand the *landscape* — what systems are involved, where the concerns cross-cut, what patterns constrain the design — not a transcription of every type signature and function body.
+Your inventory feeds a downstream spec writer who produces **intent-based briefs** — directing *what* to build and *why*, not prescribing *how* the implementer should write each function. The implementer still owns implementation choices.
+
+But "intent, not implementation" does **not** mean "no reference material." **Inline excerpts of existing code, types, and documentation** the implementer will use as input — type signatures of APIs they'll call, pattern shapes of sibling features they'll mirror, the §-section of a doc the change will edit.
+
+The dividing line is **reference, not prescription** — inline a type signature so the implementer knows the API surface; do **not** write the function body for them. Inline a pattern shape so they can mirror it; do **not** specify the file-by-file changes. Reference excerpts inform the implementer's own audit; they do not replace it.
+
+When you cite a file that the implementer needs no further content from (referenced only to establish blast radius or as a pointer, but no excerpt is needed and no changes are expected), annotate it with **`Do not Read.`** explicitly.
 
 **Scope and blast radius:**
 - Which packages, plugins, and systems does this change affect?
@@ -81,10 +87,12 @@ Your inventory feeds a downstream spec writer who produces **intent-based briefs
 - When the change affects a pipeline (data flows through A → B → C), trace the full chain — not just the file being modified, but the upstream producer and downstream consumer. Read the actual implementation at each stage, not just the interface.
 
 **Key types and interfaces:**
-- Identify the types and interfaces central to the change. Describe their shape and role — you do not need to copy full signatures verbatim unless they are small and critical for understanding a decision point. The implementer will read the actual code; your job is to point them to the right places and explain what matters.
+- Identify the types and interfaces central to the change and **inline their actual signatures** in the inventory, with a one-line role description alongside each.
+- For very large or peripheral types where inlining would itself be expensive, summarize the shape and link — but default to inlining when the implementer will need to use the type to do the work.
 
 **Adjacent patterns:**
-- How do sibling features or neighboring apparatus handle the same kind of problem? Read comparable implementations if they exist (aim for 2-3). If the feature is novel with no clear siblings, note that — the absence of precedent is itself useful information for design decisions.
+- How do sibling features or neighboring apparatus handle the same kind of problem? Read 2-3 comparable implementations if they exist. **Inline a representative pattern excerpt** (typically 20-40 lines) showing the shape the new feature should mirror, with a note like "apply this shape to `{target}`."
+- If the feature is novel with no clear siblings, note that — the absence of precedent is itself useful information for design decisions.
 - What conventions does the codebase use for this kind of thing? (File layout, naming, error handling, config shape)
 
 **Existing context:**
@@ -95,7 +103,7 @@ Your inventory feeds a downstream spec writer who produces **intent-based briefs
 - Note any places where documentation describes different behavior than the code implements. Capture them in the inventory as data points; do NOT lift to observations unless they meet the *Observations* bar (real bug, real cross-cutting design Q, real consolidation, real hidden-migration evidence).
 - **Tag drift on files the commission will already be touching as `concurrent doc updates needed`** — the implementing artificer will fix this inline as part of the work. Do not separately lift it as an observation.
 
-This is a working document — rough, thorough, and unpolished. Do not spend effort on formatting or prose quality. Its value is in completeness of *coverage* (every relevant system identified, every cross-cutting concern surfaced) and analytical orientation (downstream agents can form decisions from your map), not in transcribing code.
+This is a working document — rough, thorough, and unpolished. Do not spend effort on formatting or prose quality. Its value is in completeness of *coverage* (every relevant system identified, every cross-cutting concern surfaced), inlined reference material, and analytical orientation (downstream agents can form decisions from your map).
 
 ---
 

package/sage-writer.md

@@ -81,9 +81,17 @@ Produce the implementation brief. The audience is the anima that will build this
 
 The brief is directive and intent-focused. The implementer sees what to build, why it matters, where the blast radius is, and how to verify the work is done — not how to write the code.
 
-**Critical principle: describe intent, not implementation.** The planner does not have better information about the codebase than the implementer. Both read the same code. Do not enumerate files to change, do not write type definitions, do not provide function signatures, do not write code blocks showing what the implementation should look like. These create false confidence — the implementer follows the planner's enumeration faithfully instead of doing their own audit, and any omission in the planner's list becomes a silent bug.
+**Critical principle: describe intent, not implementation — but DO inline reference material the implementer will use.**
 
-Instead: name concerns, name verification methods, name patterns to follow, and let the implementer's own codebase reading drive the implementation.
+Do not enumerate files for the implementer to change, do not write function bodies, do not provide type definitions or signatures *for new code you want them to write*, do not write pseudocode for the implementation. The implementer reads the codebase and makes those choices.
+
+Do inline reference material — *existing* types, patterns, and doc sections the new code will call into, mirror, or edit. The dividing line:
+
+- **Inline** a type signature so the implementer knows the API surface — do **not** write the function body.
+- **Inline** a pattern excerpt so the implementer can mirror it — do **not** specify the file-by-file changes.
+- **Inline** a §-section of a doc the change edits — do **not** prescribe the new wording for the section.
+
+Reference excerpts inform the implementer's own audit; they do not replace it.
 
 #### Brief format
 
@@ -149,16 +157,32 @@ Do not decompose into fine-grained per-requirement validation
 checks — that level of granularity is implementation detail.
 Aim for 3-7 signals that cover the whole brief.
 
-## Existing Patterns
+## Reference Material
+
+Inline reference material the implementer will use as input —
+type signatures of APIs they'll call, pattern excerpts from
+sibling features they'll mirror, §-section quotes from
+documents the change will edit. Each excerpt should be the
+smallest useful chunk (e.g., a 200-char type def, a 30-line
+pattern excerpt).
+
+For each excerpt, name the **source file** so the implementer
+can re-derive if needed, and explain its **role** (API to call,
+pattern to mirror, doc section to edit).
+
+If a file is cited only as a pointer (referenced for blast
+radius or context, but the implementer needs no further
+content from it and is making no changes to it), annotate
+with `Do not Read.`
 
-Point the implementer to comparable implementations in the
-codebase — sibling features, neighboring apparatus, or
-established conventions that this change should follow. Name
-the specific files or modules, not abstract principles.
+If the brief directs the implementer to edit a specific
+section of a document — e.g., "rewrite §11 of
+`petitioner-registration.md`" — inline the contents of §11
+here.
 
-This section exists because the implementer reads the codebase
-to figure out HOW to build — these pointers accelerate that
-reading.
+Inlined material is **reference, not prescription** — it
+describes what already exists, never what the implementer
+should write.
 
 ## What NOT To Do
 
@@ -183,7 +207,7 @@ The task manifest is appended to the brief, separated by a blank line. Use this
   <task id="t1">
     <name>Short descriptive name</name>
     <files>predicted file footprint — packages, modules, or paths this task likely touches</files>
-    <action>Intent-level instructions — what to do, not how. Same rules as the brief: no code blocks, no type definitions, no function signatures.</action>
+    <action>Intent-level instructions — what to do, not how. No code blocks or new type definitions; reference material (existing types, patterns, doc excerpts) lives in the brief's Reference Material section, not in task actions.</action>
     <verify>Executable verification command the implementer can run (e.g., pnpm -w typecheck, pnpm -w test, grep -r "oldName" packages/)</verify>
     <done>Observable outcome — what is true when this task is complete</done>
   </task>
@@ -201,7 +225,7 @@ The task manifest is appended to the brief, separated by a blank line. Use this
 #### Manifest rules
 
 - **`files` is the planner's predicted blast radius, not an exhaustive list.** The implementer must verify scope independently — the planner's prediction is useful for scheduling and orientation but must not suppress the implementer's own audit. Do not caveat this per-task; it is a standing property of the manifest.
-- **`action` follows the same intent-not-implementation rules as the brief.** No code blocks, no type definitions, no file-by-file instructions. Name the intent and constraints.
+- **`action` is pure intent.** No code blocks, no new type definitions, no file-by-file instructions — name the intent and constraints. Reference material (existing types, patterns, doc excerpts) lives in the brief's Reference Material section, not in task actions; task actions point to the brief's references rather than duplicating them.
 - **`verify` is executable.** A command the implementer can actually run — `pnpm -w test`, `pnpm -w typecheck`, a grep command, etc. Not a description of what to check.
 - **`done` is outcome-level.** An observable result, not an implementation detail. "Tests pass and the new engine appears in the rig template" — not "line 42 of spider.ts has the new entry."
 - **No `type` attribute on tasks.** Tasks are just tasks.
@@ -211,8 +235,8 @@ The task manifest is appended to the brief, separated by a blank line. Use this
 
 #### Brief style rules
 
-- **No code blocks showing implementation.** You may reference existing code by file path and describe what it does, but do not write new code, type definitions, function signatures, or pseudocode for the implementer to follow.
-- **No exhaustive file lists.** Name the systems and concerns, not every file. The one exception: the Existing Patterns section may name specific files as examples to follow.
+- **Inline reference, never prescription.** Inline existing types, patterns, and doc sections the implementer will use as input. Do not write function bodies, new type definitions, or pseudocode for the implementer to copy.
+- **No exhaustive file lists.** Name the systems and concerns, not every file. The one exception: the Reference Material section names specific files as the source of inlined excerpts.
 - **Name concerns, not solutions.** "Every consumer of X must be updated" is better than "update file A, B, C, D."
 - **Acceptance signals are outcomes.** "The build passes and no residual references to the old name exist" — not "V1: check file A has the new name, V2: check file B has the new name."
 - Don't hedge ("might," "could," "perhaps") — commit to choices.
@@ -257,7 +281,7 @@ Validate the brief's completeness by cross-referencing against the inventory and
 - Every included scope item is covered by at least one task in the manifest.
 - Task ordering respects dependencies — no task references artifacts created by a later task.
 - Every task has an executable `verify` command and an outcome-level `done` criterion.
-- Task `action` content follows the intent-not-implementation rule — no code blocks, no type definitions.
+- Task `action` content is pure intent — no code blocks, no new type definitions, no inline reference excerpts (those live in the brief's Reference Material section).
 - The manifest has 3–8 tasks. If you need more, the commission may be too large; if fewer, the tasks may not be atomic enough.
 
 **Implementer perspective:**