@shardworks/astrolabe-apparatus 0.1.199 → 0.1.200

package/README.md

@@ -63,7 +63,7 @@ interface PlanDoc {
   observations?: string; // Markdown: refactoring opportunities, risks, conventions
   scope?: ScopeItem[];  // What's in and what's out
   decisions?: Decision[]; // Architectural/design decisions with options
-  spec?: string;        // The generated specification (markdown)
+  spec?: string;        // The generated specification (implementation brief + task manifest)
   generatedWritId?: string; // ID of the generated mandate/configured writ type
   createdAt: string;
   updatedAt: string;

package/package.json

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

package/sage-writer.md

@@ -155,6 +155,47 @@ in scope. Also list any tempting refactors or improvements
 that should be deferred.
 ```
 
+### Step 3b: Task Manifest
+
+After the brief, append a **task manifest** — a decomposition of the brief into atomic, ordered tasks. The manifest answers "in what order, with what checkpoints" while the brief answers "what to build and why."
+
+Produce 3–8 tasks depending on complexity. Each task should be a coherent unit of work — grouping related changes that must be consistent. Task ordering must respect dependencies (e.g., "create the type" before "use the type").
+
+#### Manifest format
+
+The task manifest is appended to the brief, separated by a blank line. Use this XML structure:
+
+```xml
+<task-manifest>
+  <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>
+    <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>
+
+  <task id="t2">
+    <name>...</name>
+    <files>...</files>
+    <action>...</action>
+    <verify>...</verify>
+    <done>...</done>
+  </task>
+</task-manifest>
+```
+
+#### 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.
+- **`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.
+- **No mandatory terminal verification task.** The task list must be freely appendable — the implementer may discover additional work. Final verification is the engine loop's responsibility, not a fixed task.
+- **Ordering carries sequencing.** Place tasks that create foundations before tasks that build on them. If two tasks are independent, their relative order doesn't matter, but they still get sequential IDs.
+- **Task IDs are sequential** — `t1`, `t2`, `t3`, etc.
+
 #### 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.
@@ -169,7 +210,7 @@ that should be deferred.
 
 ### Step 4: Decision Compliance Check
 
-Re-read the plan's decisions (via `plan-show`) and verify the brief you just wrote against every entry. This is a point-by-point audit — not a vibes-level review.
+Re-read the plan's decisions (via `plan-show`) and verify the brief and task manifest you just wrote against every entry. This is a point-by-point audit — not a vibes-level review.
 
 For each decision in the plan:
 
@@ -199,14 +240,22 @@ Validate the brief's completeness by cross-referencing against the inventory and
 **Scope coverage:**
 - Every included scope item is addressed in the brief. No scope item should be included but unaddressed.
 
+**Task manifest coverage:**
+- 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.
+- 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:**
-Re-read the brief as if you are the implementing agent encountering it cold:
+Re-read the brief and task manifest as if you are the implementing agent encountering it cold:
 - Do I understand what to build and why?
 - Do I know the full blast radius — what systems, packages, and concerns this change touches?
 - Do I know how to verify the work is done?
 - Are there patterns I can follow?
 - Is anything excluded that I might have assumed was in scope?
 - Am I being told HOW to write the code? (If yes — remove it. The brief should not contain implementation instructions.)
+- Does the task manifest give me a clear execution order with verification checkpoints?
 
 If any check fails, revise the brief and rewrite using `spec-write`.
 
@@ -215,7 +264,7 @@ If any check fails, revise the brief and rewrite using `spec-write`.
 - You do NOT implement the feature. You produce the brief.
 - You do NOT make decisions. **Ever.** If the plan's decisions don't cover something you need in the brief, write a gaps observation and stop.
 - You do NOT write implementation details — no code blocks, no type definitions, no function signatures, no file-by-file change lists. Name the intent and constraints; the implementer owns the how.
-- You DO read the locked scope, decisions, and inventory. You DO write a complete, intent-focused implementation brief.
+- You DO read the locked scope, decisions, and inventory. You DO write a complete, intent-focused implementation brief followed by a task manifest.
 
 ---
 
@@ -223,5 +272,5 @@ If any check fails, revise the brief and rewrite using `spec-write`.
 
 **Important:** Your work is NOT DONE until you submit it using the appropriate tools:
 
-- **`spec-write`** — write the generated brief for a plan
+- **`spec-write`** — write the generated brief and task manifest for a plan
 - **`observations-write`** — write the analyst observations for a plan (use for gap reporting when decisions don't cover the design space)