@shardworks/astrolabe-apparatus 0.1.132

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Sean Boots
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# `@shardworks/astrolabe-apparatus`
+
+The Astrolabe transforms patron briefs into structured work specifications. It drives a multi-stage planning pipeline — inventory, analysis, patron review, and specification writing — using a sequence of clockwork engines and anima sessions. It sits between the Clerk (writ lifecycle) and the Spider (rig execution), contributing kit pieces to both.
+
+---
+
+## Installation
+
+```json
+{
+  "dependencies": {
+    "@shardworks/astrolabe-apparatus": "workspace:*"
+  }
+}
+```
+
+The Astrolabe requires `stacks` and `clerk` and recommends `spider`, `loom`, `fabricator`, and `oculus`.
+
+## API
+
+The Astrolabe exposes an `AstrolabeApi` via `provides`, accessible at runtime via `guild().apparatus<AstrolabeApi>('astrolabe')`.
+
+```typescript
+import type { AstrolabeApi } from '@shardworks/astrolabe-apparatus';
+
+const astrolabe = guild().apparatus<AstrolabeApi>('astrolabe');
+
+// Show a single plan
+const plan = await astrolabe.show('w-abc123-def456');
+
+// List plans with filters
+const plans = await astrolabe.list({ status: 'writing', codex: 'my-codex', limit: 10 });
+
+// Partially update a plan (engines and tools use this internally)
+const updated = await astrolabe.patch('w-abc123-def456', { spec: '# Spec\n...' });
+```
+
+### `AstrolabeApi`
+
+```typescript
+interface AstrolabeApi {
+  /** Show a plan by id. Throws if not found. */
+  show(planId: string): Promise<PlanDoc>;
+
+  /** List plans with optional filters, ordered by createdAt descending. */
+  list(filters?: PlanFilters): Promise<PlanDoc[]>;
+
+  /** Partially update a plan. Returns the updated document. Throws if not found. */
+  patch(planId: string, fields: Partial<Omit<PlanDoc, 'id'>>): Promise<PlanDoc>;
+}
+```
+
+### `PlanDoc`
+
+A `PlanDoc` is keyed by the brief writ ID and tracks the full planning lifecycle:
+
+```typescript
+interface PlanDoc {
+  id: string;           // Brief writ ID
+  codex: string;        // Target codex
+  status: PlanStatus;   // 'reading' | 'analyzing' | 'reviewing' | 'writing' | 'completed' | 'failed'
+  inventory?: string;   // Markdown: affected files, types, interfaces, patterns
+  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)
+  generatedWritId?: string; // ID of the generated mandate/configured writ type
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+### `PlanFilters`
+
+```typescript
+interface PlanFilters {
+  status?: PlanStatus;  // Filter by planning status
+  codex?: string;       // Filter by codex name
+  limit?: number;       // Max results (default: 20)
+  offset?: number;      // Skip N results
+}
+```
+
+## Configuration
+
+Add an `astrolabe` section to `guild.json` to configure behaviour:
+
+```json
+{
+  "astrolabe": {
+    "generatedWritType": "mandate"
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `generatedWritType` | `string` | `"mandate"` | Writ type posted by the spec-writer engine |
+
+## Support Kit
+
+### Books
+
+The Astrolabe declares one book in Stacks:
+
+| Book | Owner | Indexes |
+|---|---|---|
+| `plans` | `astrolabe` | `status`, `codex`, `createdAt` |
+
+### Writ Types (contributed to Clerk)
+
+| Name | Description |
+|---|---|
+| `brief` | A patron brief triggering the planning pipeline |
+
+### Roles (contributed to Loom)
+
+| Role | Qualified Name | Permissions | Strict |
+|---|---|---|---|
+| `sage` | `astrolabe.sage` | `astrolabe:read`, `astrolabe:write`, `clerk:read` | `true` |
+
+### Engines (contributed to Fabricator)
+
+| Engine ID | Description |
+|---|---|
+| `astrolabe.plan-init` | Creates a PlanDoc from the brief writ; validates codex presence |
+| `astrolabe.inventory-check` | Validates that the reader produced a non-empty inventory |
+| `astrolabe.decision-review` | Two-pass engine: blocks for patron review, then reconciles answers |
+
+### Rig Templates (contributed to Spider)
+
+| Template | Mapped Writ Type | Engines |
+|---|---|---|
+| `astrolabe.planning` | `brief` | plan-init → draft → reader → inventory-check → analyst → decision-review → spec-writer → seal |
+
+The `resolutionEngine` is `spec-writer` — the rig's completion summary comes from the specification writer session.
+
+### Tools
+
+| Tool | Permission | Description |
+|---|---|---|
+| `plan-show` | `astrolabe:read` | Show full detail for a plan by ID |
+| `plan-list` | `astrolabe:read` | List plans with optional status/codex filters |
+| `inventory-write` | `astrolabe:write` | Write or replace the codebase inventory |
+| `scope-write` | `astrolabe:write` | Write or replace the scope items array |
+| `decisions-write` | `astrolabe:write` | Write or replace the decisions array |
+| `observations-write` | `astrolabe:write` | Write or replace analyst observations |
+| `spec-write` | `astrolabe:write` | Write or replace the generated specification |
+
+Write tools only update their artifact field plus `updatedAt`. Status transitions are the exclusive responsibility of the clockwork engines.

package/dist/astrolabe.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The Astrolabe — brief-to-specification planning apparatus.
+ *
+ * The Astrolabe transforms patron briefs into structured work specifications
+ * by driving a multi-stage planning pipeline: inventory → analysis →
+ * patron review → specification writing.
+ *
+ * See: docs/architecture/apparatus/astrolabe.md
+ */
+import type { Plugin } from '@shardworks/nexus-core';
+import type { AstrolabeConfig } from './types.ts';
+declare function resolveAstrolabeConfig(): AstrolabeConfig;
+export declare function createAstrolabe(): Plugin;
+export { resolveAstrolabeConfig };
+//# sourceMappingURL=astrolabe.d.ts.map

package/dist/astrolabe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"astrolabe.d.ts","sourceRoot":"","sources":["../src/astrolabe.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,wBAAwB,CAAC;AAQrE,OAAO,KAAK,EAEV,eAAe,EAGhB,MAAM,YAAY,CAAC;AAUpB,iBAAS,sBAAsB,IAAI,eAAe,CAEjD;AA0FD,wBAAgB,eAAe,IAAI,MAAM,CAwPxC;AAGD,OAAO,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/astrolabe.js

@@ -0,0 +1,319 @@
+/**
+ * The Astrolabe — brief-to-specification planning apparatus.
+ *
+ * The Astrolabe transforms patron briefs into structured work specifications
+ * by driving a multi-stage planning pipeline: inventory → analysis →
+ * patron review → specification writing.
+ *
+ * See: docs/architecture/apparatus/astrolabe.md
+ */
+import { guild } from '@shardworks/nexus-core';
+import { tool } from '@shardworks/tools-apparatus';
+import { z } from 'zod';
+import { createPlanInitEngine, createInventoryCheckEngine, createDecisionReviewEngine, } from "./engines/index.js";
+// ── Config resolver ──────────────────────────────────────────────────
+function resolveAstrolabeConfig() {
+    return guild().guildConfig().astrolabe ?? {};
+}
+// ── Rig template ─────────────────────────────────────────────────────
+const planningTemplate = {
+    engines: [
+        {
+            id: 'plan-init',
+            designId: 'astrolabe.plan-init',
+            upstream: [],
+            givens: { writ: '${writ}' },
+        },
+        {
+            id: 'draft',
+            designId: 'draft',
+            upstream: ['plan-init'],
+            givens: { writ: '${writ}' },
+        },
+        {
+            id: 'reader',
+            designId: 'anima-session',
+            upstream: ['draft'],
+            givens: {
+                role: 'astrolabe.sage',
+                prompt: 'MODE: READER\n\nPlan ID: ${yields.plan-init.planId}\n\n' +
+                    'You are beginning a new planning session. Use plan-show to read the plan, ' +
+                    'then inventory the codebase and write the inventory using inventory-write.',
+                cwd: '${yields.draft.path}',
+                writ: '${writ}',
+            },
+        },
+        {
+            id: 'inventory-check',
+            designId: 'astrolabe.inventory-check',
+            upstream: ['reader'],
+            givens: {
+                planId: '${yields.plan-init.planId}',
+            },
+        },
+        {
+            id: 'analyst',
+            designId: 'anima-session',
+            upstream: ['inventory-check'],
+            givens: {
+                role: 'astrolabe.sage',
+                prompt: 'MODE: ANALYST\n\nPlan ID: ${yields.plan-init.planId}\n\n' +
+                    'You are continuing the reader conversation. Use plan-show to read the current ' +
+                    'plan state, then produce scope, decisions, and observations using the write tools.',
+                cwd: '${yields.draft.path}',
+                conversationId: '${yields.reader.conversationId}',
+                writ: '${writ}',
+            },
+        },
+        {
+            id: 'decision-review',
+            designId: 'astrolabe.decision-review',
+            upstream: ['analyst'],
+            givens: {
+                planId: '${yields.plan-init.planId}',
+            },
+        },
+        {
+            id: 'spec-writer',
+            designId: 'anima-session',
+            upstream: ['decision-review'],
+            givens: {
+                role: 'astrolabe.sage',
+                prompt: 'MODE: WRITER\n\nPlan ID: ${yields.plan-init.planId}\n\n' +
+                    'You are continuing the analyst conversation. Use plan-show to read the full ' +
+                    'plan including patron-reviewed decisions, then write the specification using spec-write.',
+                cwd: '${yields.draft.path}',
+                conversationId: '${yields.analyst.conversationId}',
+                writ: '${writ}',
+            },
+        },
+        {
+            id: 'seal',
+            designId: 'seal',
+            upstream: ['spec-writer'],
+            givens: { abandon: true },
+        },
+    ],
+    resolutionEngine: 'spec-writer',
+};
+// ── Factory ──────────────────────────────────────────────────────────
+export function createAstrolabe() {
+    let plansBook;
+    // ── Engines ────────────────────────────────────────────────────
+    const planInitEngine = createPlanInitEngine(() => plansBook);
+    const inventoryCheckEngine = createInventoryCheckEngine(() => plansBook);
+    const decisionReviewEngine = createDecisionReviewEngine(() => plansBook);
+    // ── API ────────────────────────────────────────────────────────
+    const api = {
+        async show(planId) {
+            const plan = await plansBook.get(planId);
+            if (!plan) {
+                throw new Error(`Plan "${planId}" not found.`);
+            }
+            return plan;
+        },
+        async list(filters) {
+            const conditions = [];
+            if (filters?.status)
+                conditions.push(['status', '=', filters.status]);
+            if (filters?.codex)
+                conditions.push(['codex', '=', filters.codex]);
+            const limit = filters?.limit ?? 20;
+            const offset = filters?.offset;
+            return plansBook.find({
+                where: conditions.length > 0 ? conditions : undefined,
+                orderBy: ['createdAt', 'desc'],
+                limit,
+                ...(offset !== undefined ? { offset } : {}),
+            });
+        },
+        async patch(planId, fields) {
+            return plansBook.patch(planId, fields);
+        },
+    };
+    // ── Tools ──────────────────────────────────────────────────────
+    const planShowTool = tool({
+        name: 'plan-show',
+        description: 'Show full detail for a plan',
+        instructions: 'Returns the complete plan document including inventory, scope, decisions, ' +
+            'observations, and spec fields. The planId is the brief writ ID.',
+        params: {
+            planId: z.string().describe('Plan id (same as the brief writ id)'),
+        },
+        permission: 'astrolabe:read',
+        handler: async ({ planId }) => {
+            const plan = await plansBook.get(planId);
+            if (!plan)
+                throw new Error(`Plan "${planId}" not found.`);
+            return plan;
+        },
+    });
+    const planListTool = tool({
+        name: 'plan-list',
+        description: 'List plans with optional filters',
+        instructions: 'Returns plan summaries ordered by createdAt descending (newest first). ' +
+            'Filter by status or codex to narrow results.',
+        params: {
+            status: z
+                .enum(['reading', 'analyzing', 'reviewing', 'writing', 'completed', 'failed'])
+                .optional()
+                .describe('Filter by plan status'),
+            codex: z.string().optional().describe('Filter by codex name'),
+            limit: z.number().optional().default(20).describe('Maximum results (default: 20)'),
+            offset: z.number().optional().describe('Number of results to skip'),
+        },
+        permission: 'astrolabe:read',
+        handler: async (params) => {
+            const where = [];
+            if (params.status)
+                where.push(['status', '=', params.status]);
+            if (params.codex)
+                where.push(['codex', '=', params.codex]);
+            return plansBook.find({
+                where: where.length > 0 ? where : undefined,
+                orderBy: ['createdAt', 'desc'],
+                limit: params.limit,
+                ...(params.offset !== undefined ? { offset: params.offset } : {}),
+            });
+        },
+    });
+    const inventoryWriteTool = tool({
+        name: 'inventory-write',
+        description: 'Write the codebase inventory for a plan',
+        instructions: 'Writes or replaces the inventory field on the plan. The inventory should be a ' +
+            'markdown document describing affected files, types, interfaces, and patterns.',
+        params: {
+            planId: z.string().describe('Plan id'),
+            inventory: z.string().describe('Inventory content (markdown)'),
+        },
+        permission: 'astrolabe:write',
+        handler: async ({ planId, inventory }) => {
+            return plansBook.patch(planId, { inventory, updatedAt: new Date().toISOString() });
+        },
+    });
+    const scopeWriteTool = tool({
+        name: 'scope-write',
+        description: 'Write or replace the scope items for a plan',
+        instructions: 'Writes the full scope array. Each scope item has an id, description, rationale, ' +
+            'and included flag.',
+        params: {
+            planId: z.string().describe('Plan id'),
+            scope: z
+                .array(z.object({
+                id: z.string(),
+                description: z.string(),
+                rationale: z.string(),
+                included: z.boolean(),
+            }))
+                .describe('Scope items'),
+        },
+        permission: 'astrolabe:write',
+        handler: async ({ planId, scope }) => {
+            return plansBook.patch(planId, { scope, updatedAt: new Date().toISOString() });
+        },
+    });
+    const decisionsWriteTool = tool({
+        name: 'decisions-write',
+        description: 'Write or replace the decisions for a plan',
+        instructions: 'Writes the full decisions array. Each decision has an id, scope references, question, ' +
+            'options, and optional recommendation/rationale fields.',
+        params: {
+            planId: z.string().describe('Plan id'),
+            decisions: z
+                .array(z.object({
+                id: z.string(),
+                scope: z.array(z.string()),
+                question: z.string(),
+                context: z.string().optional(),
+                options: z.record(z.string(), z.string()),
+                recommendation: z.string().optional(),
+                rationale: z.string().optional(),
+                selected: z.string().optional(),
+                patronOverride: z.string().optional(),
+            }))
+                .describe('Decision items'),
+        },
+        permission: 'astrolabe:write',
+        handler: async ({ planId, decisions }) => {
+            return plansBook.patch(planId, { decisions, updatedAt: new Date().toISOString() });
+        },
+    });
+    const observationsWriteTool = tool({
+        name: 'observations-write',
+        description: 'Write analyst observations for a plan',
+        instructions: 'Writes or replaces the observations field. The observations should be a markdown ' +
+            'document noting refactoring opportunities, risks, and conventions.',
+        params: {
+            planId: z.string().describe('Plan id'),
+            observations: z.string().describe('Observations content (markdown)'),
+        },
+        permission: 'astrolabe:write',
+        handler: async ({ planId, observations }) => {
+            return plansBook.patch(planId, { observations, updatedAt: new Date().toISOString() });
+        },
+    });
+    const specWriteTool = tool({
+        name: 'spec-write',
+        description: 'Write the generated specification for a plan',
+        instructions: 'Writes or replaces the spec field. The spec should be a markdown document ' +
+            'containing the implementation specification.',
+        params: {
+            planId: z.string().describe('Plan id'),
+            spec: z.string().describe('Specification content (markdown)'),
+        },
+        permission: 'astrolabe:write',
+        handler: async ({ planId, spec }) => {
+            return plansBook.patch(planId, { spec, updatedAt: new Date().toISOString() });
+        },
+    });
+    // ── Apparatus ──────────────────────────────────────────────────
+    return {
+        apparatus: {
+            requires: ['stacks', 'clerk'],
+            recommends: ['spider', 'loom', 'fabricator', 'oculus'],
+            supportKit: {
+                books: {
+                    plans: { indexes: ['status', 'codex', 'createdAt'] },
+                },
+                writTypes: [
+                    { name: 'brief', description: 'A patron brief triggering the planning pipeline' },
+                ],
+                roles: {
+                    sage: {
+                        permissions: ['astrolabe:read', 'astrolabe:write', 'clerk:read'],
+                        strict: true,
+                        instructionsFile: 'sage.md',
+                    },
+                },
+                engines: {
+                    'astrolabe.plan-init': planInitEngine,
+                    'astrolabe.inventory-check': inventoryCheckEngine,
+                    'astrolabe.decision-review': decisionReviewEngine,
+                },
+                rigTemplates: {
+                    planning: planningTemplate,
+                },
+                rigTemplateMappings: {
+                    brief: 'astrolabe.planning',
+                },
+                tools: [
+                    planShowTool,
+                    planListTool,
+                    inventoryWriteTool,
+                    scopeWriteTool,
+                    decisionsWriteTool,
+                    observationsWriteTool,
+                    specWriteTool,
+                ],
+            },
+            provides: api,
+            start(_ctx) {
+                const stacks = guild().apparatus('stacks');
+                plansBook = stacks.book('astrolabe', 'plans');
+            },
+        },
+    };
+}
+// Export resolveAstrolabeConfig for external use (lazy config access)
+export { resolveAstrolabeConfig };
+//# sourceMappingURL=astrolabe.js.map

package/dist/astrolabe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"astrolabe.js","sourceRoot":"","sources":["../src/astrolabe.ts"],"names":[],"mappings":"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"}

package/dist/engines/decision-review.d.ts

@@ -0,0 +1,21 @@
+/**
+ * decision-review clockwork engine.
+ *
+ * Two-pass engine:
+ *
+ * First run (plan status 'analyzing'):
+ *   - Maps decisions to ChoiceQuestionSpec and scope items to BooleanQuestionSpec.
+ *   - Creates an InputRequestDoc in spider/input-requests.
+ *   - Blocks with 'patron-input' block type.
+ *   - If no decisions and no scope items, completes immediately.
+ *
+ * Re-run (plan status 'reviewing'):
+ *   - Reads the completed InputRequestDoc.
+ *   - Reconciles answers back into the PlanDoc.
+ *   - Yields a human-readable decisionSummary markdown string.
+ */
+import type { EngineDesign } from '@shardworks/fabricator-apparatus';
+import type { Book } from '@shardworks/stacks-apparatus';
+import type { PlanDoc } from '../types.ts';
+export declare function createDecisionReviewEngine(getPlansBook: () => Book<PlanDoc>): EngineDesign;
+//# sourceMappingURL=decision-review.d.ts.map

package/dist/engines/decision-review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-review.d.ts","sourceRoot":"","sources":["../../src/engines/decision-review.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAqC,MAAM,kCAAkC,CAAC;AACxG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AAUzD,OAAO,KAAK,EAAE,OAAO,EAAuB,MAAM,aAAa,CAAC;AAiDhE,wBAAgB,0BAA0B,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,YAAY,CA8L1F"}

package/dist/engines/decision-review.js

@@ -0,0 +1,225 @@
+/**
+ * decision-review clockwork engine.
+ *
+ * Two-pass engine:
+ *
+ * First run (plan status 'analyzing'):
+ *   - Maps decisions to ChoiceQuestionSpec and scope items to BooleanQuestionSpec.
+ *   - Creates an InputRequestDoc in spider/input-requests.
+ *   - Blocks with 'patron-input' block type.
+ *   - If no decisions and no scope items, completes immediately.
+ *
+ * Re-run (plan status 'reviewing'):
+ *   - Reads the completed InputRequestDoc.
+ *   - Reconciles answers back into the PlanDoc.
+ *   - Yields a human-readable decisionSummary markdown string.
+ */
+import { guild, generateId } from '@shardworks/nexus-core';
+// ── Helpers ──────────────────────────────────────────────────────────
+function composeDetails(context, rationale) {
+    if (context && rationale) {
+        return `${context}\n\nRecommendation rationale: ${rationale}`;
+    }
+    if (context)
+        return context;
+    if (rationale)
+        return `Recommendation rationale: ${rationale}`;
+    return undefined;
+}
+function buildDecisionSummary(decisions, scope) {
+    const parts = [];
+    if (decisions.length > 0) {
+        parts.push('## Decisions');
+        parts.push('');
+        for (const decision of decisions) {
+            parts.push(`### ${decision.id}: ${decision.question}`);
+            const selectedKey = decision.selected ?? decision.recommendation;
+            if (selectedKey && decision.options[selectedKey]) {
+                parts.push(`**Selected:** ${decision.options[selectedKey]}`);
+            }
+            else if (selectedKey) {
+                parts.push(`**Selected:** ${selectedKey}`);
+            }
+            if (decision.patronOverride) {
+                parts.push(`**Patron override:** ${decision.patronOverride}`);
+            }
+            parts.push('');
+        }
+    }
+    if (scope.length > 0) {
+        parts.push('## Scope');
+        parts.push('');
+        for (const item of scope) {
+            const check = item.included ? '[x]' : '[ ]';
+            const suffix = item.included ? '' : ' (excluded)';
+            parts.push(`- ${check} ${item.id}: ${item.description}${suffix}`);
+        }
+    }
+    return parts.join('\n').trim();
+}
+// ── Engine factory ───────────────────────────────────────────────────
+export function createDecisionReviewEngine(getPlansBook) {
+    return {
+        id: 'astrolabe.decision-review',
+        async run(givens, context) {
+            const planId = givens.planId;
+            const book = getPlansBook();
+            const plan = await book.get(planId);
+            if (!plan) {
+                throw new Error(`Plan "${planId}" not found.`);
+            }
+            // ── First run: status === 'analyzing' ─────────────────────────
+            if (plan.status === 'analyzing') {
+                const decisions = plan.decisions ?? [];
+                const scopeItems = plan.scope ?? [];
+                // Fast-path: no decisions and no scope
+                if (decisions.length === 0 && scopeItems.length === 0) {
+                    await book.patch(planId, {
+                        status: 'writing',
+                        updatedAt: new Date().toISOString(),
+                    });
+                    return {
+                        status: 'completed',
+                        yields: { decisionSummary: '' },
+                    };
+                }
+                // Build questions
+                const questions = {};
+                const answers = {};
+                for (const decision of decisions) {
+                    const choiceSpec = {
+                        type: 'choice',
+                        label: decision.question,
+                        details: composeDetails(decision.context, decision.rationale),
+                        options: decision.options,
+                        allowCustom: true,
+                    };
+                    questions[decision.id] = choiceSpec;
+                    if (decision.recommendation) {
+                        answers[decision.id] = { selected: decision.recommendation };
+                    }
+                }
+                for (const item of scopeItems) {
+                    const boolSpec = {
+                        type: 'boolean',
+                        label: item.description,
+                        details: item.rationale,
+                    };
+                    questions[`scope:${item.id}`] = boolSpec;
+                    answers[`scope:${item.id}`] = item.included;
+                }
+                // Compose message
+                let message;
+                try {
+                    const clerk = guild().apparatus('clerk');
+                    const writ = await clerk.show(planId);
+                    const includedScope = scopeItems.filter(s => s.included).map(s => s.description);
+                    const scopeSummary = includedScope.length > 0
+                        ? `\n\nIn-scope items: ${includedScope.join(', ')}`
+                        : '';
+                    message = `Planning review for: ${writ.title} (codex: ${plan.codex})${scopeSummary}`;
+                }
+                catch {
+                    message = `Planning review for plan: ${planId} (codex: ${plan.codex})`;
+                }
+                // Create InputRequestDoc
+                const requestId = generateId('ir', 4);
+                const now = new Date().toISOString();
+                const inputRequest = {
+                    id: requestId,
+                    rigId: context.rigId,
+                    engineId: context.engineId,
+                    status: 'pending',
+                    message,
+                    questions,
+                    answers,
+                    createdAt: now,
+                    updatedAt: now,
+                };
+                const stacks = guild().apparatus('stacks');
+                const inputRequestsBook = stacks.book('spider', 'input-requests');
+                await inputRequestsBook.put(inputRequest);
+                // Update plan status to 'reviewing'
+                await book.patch(planId, {
+                    status: 'reviewing',
+                    updatedAt: now,
+                });
+                return {
+                    status: 'blocked',
+                    blockType: 'patron-input',
+                    condition: { requestId },
+                };
+            }
+            // ── Re-run: status === 'reviewing' ────────────────────────────
+            if (plan.status === 'reviewing') {
+                // Extract requestId from priorBlock or query book
+                let requestId;
+                if (context.priorBlock?.condition) {
+                    const cond = context.priorBlock.condition;
+                    requestId = cond.requestId;
+                }
+                else {
+                    // Fallback: query by rigId + engineId
+                    const stacks = guild().apparatus('stacks');
+                    const inputRequestsBook = stacks.book('spider', 'input-requests');
+                    const found = await inputRequestsBook.find({
+                        where: [
+                            ['rigId', '=', context.rigId],
+                            ['engineId', '=', context.engineId],
+                        ],
+                        limit: 1,
+                    });
+                    if (found.length === 0) {
+                        throw new Error(`No InputRequestDoc found for rig "${context.rigId}" engine "${context.engineId}".`);
+                    }
+                    requestId = found[0].id;
+                }
+                const stacks = guild().apparatus('stacks');
+                const inputRequestsBook = stacks.book('spider', 'input-requests');
+                const inputRequest = await inputRequestsBook.get(requestId);
+                if (!inputRequest) {
+                    throw new Error(`InputRequestDoc "${requestId}" not found.`);
+                }
+                // Reconcile answers back into the plan
+                const decisions = (plan.decisions ?? []).map(d => ({ ...d }));
+                const scopeItems = (plan.scope ?? []).map(s => ({ ...s }));
+                for (const [key, answer] of Object.entries(inputRequest.answers)) {
+                    if (key.startsWith('scope:')) {
+                        const scopeId = key.slice('scope:'.length);
+                        const item = scopeItems.find(s => s.id === scopeId);
+                        if (item) {
+                            item.included = answer;
+                        }
+                    }
+                    else {
+                        const decision = decisions.find(d => d.id === key);
+                        if (decision) {
+                            const choiceAnswer = answer;
+                            if ('selected' in choiceAnswer) {
+                                decision.selected = choiceAnswer.selected;
+                            }
+                            else if ('custom' in choiceAnswer) {
+                                decision.patronOverride = choiceAnswer.custom;
+                            }
+                        }
+                    }
+                }
+                const decisionSummary = buildDecisionSummary(decisions, scopeItems);
+                const now = new Date().toISOString();
+                await book.patch(planId, {
+                    decisions,
+                    scope: scopeItems,
+                    status: 'writing',
+                    updatedAt: now,
+                });
+                return {
+                    status: 'completed',
+                    yields: { decisionSummary },
+                };
+            }
+            throw new Error(`decision-review: unexpected plan status "${plan.status}" for plan "${planId}". ` +
+                `Expected 'analyzing' or 'reviewing'.`);
+        },
+    };
+}
+//# sourceMappingURL=decision-review.js.map

package/dist/engines/decision-review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-review.js","sourceRoot":"","sources":["../../src/engines/decision-review.ts"],"names":[],"mappings":"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"}

package/dist/engines/index.d.ts

@@ -0,0 +1,4 @@
+export { createPlanInitEngine } from './plan-init.ts';
+export { createInventoryCheckEngine } from './inventory-check.ts';
+export { createDecisionReviewEngine } from './decision-review.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/engines/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engines/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/engines/index.js

@@ -0,0 +1,4 @@
+export { createPlanInitEngine } from "./plan-init.js";
+export { createInventoryCheckEngine } from "./inventory-check.js";
+export { createDecisionReviewEngine } from "./decision-review.js";
+//# sourceMappingURL=index.js.map

package/dist/engines/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engines/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/engines/inventory-check.d.ts

@@ -0,0 +1,11 @@
+/**
+ * inventory-check clockwork engine.
+ *
+ * Validates that the reader stage produced a non-empty inventory on the PlanDoc.
+ * Throws if the plan is missing or has no inventory content.
+ */
+import type { EngineDesign } from '@shardworks/fabricator-apparatus';
+import type { Book } from '@shardworks/stacks-apparatus';
+import type { PlanDoc } from '../types.ts';
+export declare function createInventoryCheckEngine(getPlansBook: () => Book<PlanDoc>): EngineDesign;
+//# sourceMappingURL=inventory-check.d.ts.map

package/dist/engines/inventory-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inventory-check.d.ts","sourceRoot":"","sources":["../../src/engines/inventory-check.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAqC,MAAM,kCAAkC,CAAC;AACxG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,wBAAgB,0BAA0B,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,YAAY,CA4B1F"}

package/dist/engines/inventory-check.js

@@ -0,0 +1,27 @@
+/**
+ * inventory-check clockwork engine.
+ *
+ * Validates that the reader stage produced a non-empty inventory on the PlanDoc.
+ * Throws if the plan is missing or has no inventory content.
+ */
+export function createInventoryCheckEngine(getPlansBook) {
+    return {
+        id: 'astrolabe.inventory-check',
+        async run(givens, _context) {
+            const planId = givens.planId;
+            const book = getPlansBook();
+            const plan = await book.get(planId);
+            if (!plan) {
+                throw new Error(`Plan "${planId}" not found.`);
+            }
+            if (typeof plan.inventory !== 'string' || plan.inventory.length === 0) {
+                throw new Error(`Plan "${planId}" has no inventory — reader stage did not produce output.`);
+            }
+            return {
+                status: 'completed',
+                yields: {},
+            };
+        },
+    };
+}
+//# sourceMappingURL=inventory-check.js.map

package/dist/engines/inventory-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inventory-check.js","sourceRoot":"","sources":["../../src/engines/inventory-check.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,UAAU,0BAA0B,CAAC,YAAiC;IAC1E,OAAO;QACL,EAAE,EAAE,2BAA2B;QAE/B,KAAK,CAAC,GAAG,CACP,MAA+B,EAC/B,QAA0B;YAE1B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAgB,CAAC;YACvC,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;YAE5B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACpC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,KAAK,CAAC,SAAS,MAAM,cAAc,CAAC,CAAC;YACjD,CAAC;YAED,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACtE,MAAM,IAAI,KAAK,CACb,SAAS,MAAM,2DAA2D,CAC3E,CAAC;YACJ,CAAC;YAED,OAAO;gBACL,MAAM,EAAE,WAAW;gBACnB,MAAM,EAAE,EAAE;aACX,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/engines/plan-init.d.ts

@@ -0,0 +1,11 @@
+/**
+ * plan-init clockwork engine.
+ *
+ * Creates a PlanDoc keyed by the brief writ ID. Validates that the writ
+ * has a codex and that no plan already exists for this writ.
+ */
+import type { EngineDesign } from '@shardworks/fabricator-apparatus';
+import type { Book } from '@shardworks/stacks-apparatus';
+import type { PlanDoc } from '../types.ts';
+export declare function createPlanInitEngine(getPlansBook: () => Book<PlanDoc>): EngineDesign;
+//# sourceMappingURL=plan-init.d.ts.map

package/dist/engines/plan-init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-init.d.ts","sourceRoot":"","sources":["../../src/engines/plan-init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAqC,MAAM,kCAAkC,CAAC;AACxG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AAEzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,YAAY,CAwCpF"}

package/dist/engines/plan-init.js

@@ -0,0 +1,39 @@
+/**
+ * plan-init clockwork engine.
+ *
+ * Creates a PlanDoc keyed by the brief writ ID. Validates that the writ
+ * has a codex and that no plan already exists for this writ.
+ */
+export function createPlanInitEngine(getPlansBook) {
+    return {
+        id: 'astrolabe.plan-init',
+        async run(givens, _context) {
+            const writ = givens.writ;
+            const book = getPlansBook();
+            // Validate codex
+            if (!writ.codex || typeof writ.codex !== 'string' || writ.codex.trim() === '') {
+                throw new Error(`Writ "${writ.id}" has no codex — cannot create a plan.`);
+            }
+            // Check for duplicate
+            const existing = await book.get(writ.id);
+            if (existing !== null) {
+                throw new Error(`Plan "${writ.id}" already exists.`);
+            }
+            // Create plan
+            const now = new Date().toISOString();
+            const plan = {
+                id: writ.id,
+                codex: writ.codex,
+                status: 'reading',
+                createdAt: now,
+                updatedAt: now,
+            };
+            await book.put(plan);
+            return {
+                status: 'completed',
+                yields: { planId: writ.id },
+            };
+        },
+    };
+}
+//# sourceMappingURL=plan-init.js.map

package/dist/engines/plan-init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-init.js","sourceRoot":"","sources":["../../src/engines/plan-init.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,MAAM,UAAU,oBAAoB,CAAC,YAAiC;IACpE,OAAO;QACL,EAAE,EAAE,qBAAqB;QAEzB,KAAK,CAAC,GAAG,CACP,MAA+B,EAC/B,QAA0B;YAE1B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAe,CAAC;YACpC,MAAM,IAAI,GAAG,YAAY,EAAE,CAAC;YAE5B,iBAAiB;YACjB,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;gBAC9E,MAAM,IAAI,KAAK,CAAC,SAAS,IAAI,CAAC,EAAE,wCAAwC,CAAC,CAAC;YAC5E,CAAC;YAED,sBAAsB;YACtB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACzC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;gBACtB,MAAM,IAAI,KAAK,CAAC,SAAS,IAAI,CAAC,EAAE,mBAAmB,CAAC,CAAC;YACvD,CAAC;YAED,cAAc;YACd,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACrC,MAAM,IAAI,GAAY;gBACpB,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,MAAM,EAAE,SAAS;gBACjB,SAAS,EAAE,GAAG;gBACd,SAAS,EAAE,GAAG;aACf,CAAC;YAEF,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAErB,OAAO;gBACL,MAAM,EAAE,WAAW;gBACnB,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE;aAC5B,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @shardworks/astrolabe-apparatus — The Astrolabe.
+ *
+ * Brief-to-specification planning: transforms patron briefs into structured
+ * work specifications through a multi-stage pipeline of inventory, analysis,
+ * patron review, and specification writing.
+ *
+ * See: docs/architecture/apparatus/astrolabe.md
+ */
+export type { PlanDoc, ScopeItem, Decision, PlanStatus, PlanFilters, AstrolabeConfig, AstrolabeApi, } from './types.ts';
+export { createAstrolabe } from './astrolabe.ts';
+declare const _default: import("@shardworks/nexus-core").Plugin;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,YAAY,EACV,OAAO,EACP,SAAS,EACT,QAAQ,EACR,UAAU,EACV,WAAW,EACX,eAAe,EACf,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;;AAKjD,wBAAiC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @shardworks/astrolabe-apparatus — The Astrolabe.
+ *
+ * Brief-to-specification planning: transforms patron briefs into structured
+ * work specifications through a multi-stage pipeline of inventory, analysis,
+ * patron review, and specification writing.
+ *
+ * See: docs/architecture/apparatus/astrolabe.md
+ */
+export { createAstrolabe } from "./astrolabe.js";
+// ── Default export: the apparatus plugin ──────────────────────────────
+import { createAstrolabe } from "./astrolabe.js";
+export default createAstrolabe();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAcH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,yEAAyE;AAEzE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,eAAe,eAAe,EAAE,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Astrolabe — public types.
+ *
+ * PlanDoc, ScopeItem, Decision, and supporting types for the brief-to-spec
+ * planning pipeline.
+ */
+export type PlanStatus = 'reading' | 'analyzing' | 'reviewing' | 'writing' | 'completed' | 'failed';
+export interface PlanDoc {
+    [key: string]: unknown;
+    /** The brief writ ID — primary key. */
+    id: string;
+    /** The codex this plan targets. */
+    codex: string;
+    /** Planning status. */
+    status: PlanStatus;
+    /** Codebase inventory: affected files, types, interfaces, patterns. */
+    inventory?: string;
+    /** Analyst observations: refactoring opportunities, risks, conventions. */
+    observations?: string;
+    /** Scope items: what's in and what's out. */
+    scope?: ScopeItem[];
+    /** Architectural/design decisions with options and analysis. */
+    decisions?: Decision[];
+    /** The generated specification. */
+    spec?: string;
+    /** The writ ID of the generated mandate (or configured type). */
+    generatedWritId?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ScopeItem {
+    id: string;
+    description: string;
+    rationale: string;
+    included: boolean;
+}
+export interface Decision {
+    id: string;
+    scope: string[];
+    question: string;
+    context?: string;
+    options: Record<string, string>;
+    recommendation?: string;
+    rationale?: string;
+    selected?: string;
+    patronOverride?: string;
+}
+export interface PlanFilters {
+    /** Filter by status. */
+    status?: PlanStatus;
+    /** Filter by codex name. */
+    codex?: string;
+    /** Maximum number of results (default: 20). */
+    limit?: number;
+    /** Number of results to skip. */
+    offset?: number;
+}
+export interface AstrolabeConfig {
+    /** The writ type posted by the spec-writer engine. Default: 'mandate'. */
+    generatedWritType?: string;
+}
+declare module '@shardworks/nexus-core' {
+    interface GuildConfig {
+        astrolabe?: AstrolabeConfig;
+    }
+}
+export interface AstrolabeApi {
+    /** Show a plan by id. Throws if not found. */
+    show(planId: string): Promise<PlanDoc>;
+    /** List plans with optional filters, ordered by createdAt descending. */
+    list(filters?: PlanFilters): Promise<PlanDoc[]>;
+    /** Partially update a plan. Returns the updated document. Throws if not found. */
+    patch(planId: string, fields: Partial<Omit<PlanDoc, 'id'>>): Promise<PlanDoc>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAIpG,MAAM,WAAW,OAAO;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,MAAM,EAAE,UAAU,CAAC;IAGnB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IAGnB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,gEAAgE;IAChE,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IAGvB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAID,MAAM,WAAW,WAAW;IAC1B,wBAAwB;IACxB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,OAAO,QAAQ,wBAAwB,CAAC;IACtC,UAAU,WAAW;QACnB,SAAS,CAAC,EAAE,eAAe,CAAC;KAC7B;CACF;AAID,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,yEAAyE;IACzE,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAChD,kFAAkF;IAClF,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/E"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Astrolabe — public types.
+ *
+ * PlanDoc, ScopeItem, Decision, and supporting types for the brief-to-spec
+ * planning pipeline.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@shardworks/astrolabe-apparatus",
+  "version": "0.1.132",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shardworks/nexus",
+    "directory": "packages/plugins/astrolabe"
+  },
+  "description": "The Astrolabe — brief-to-specification planning apparatus",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "4.3.6",
+    "@shardworks/stacks-apparatus": "0.1.132",
+    "@shardworks/tools-apparatus": "0.1.132",
+    "@shardworks/clerk-apparatus": "0.1.132",
+    "@shardworks/fabricator-apparatus": "0.1.132",
+    "@shardworks/spider-apparatus": "0.1.132",
+    "@shardworks/loom-apparatus": "0.1.132",
+    "@shardworks/nexus-core": "0.1.132"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.0"
+  },
+  "files": [
+    "dist",
+    "sage.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --disable-warning=ExperimentalWarning --experimental-transform-types --test 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/sage.md

@@ -0,0 +1,11 @@
+# Astrolabe Sage
+
+You are the Astrolabe sage — a planning anima that refines patron briefs into structured specifications.
+
+Your role is to guide the planning pipeline through its stages:
+
+- **Reader**: Inventory the codebase, identifying affected files, types, interfaces, and patterns.
+- **Analyst**: Produce scope items, architectural decisions, and observations from the inventory.
+- **Writer**: Synthesize patron-reviewed decisions into a complete implementation specification.
+
+Always use the available tools to read and write plan artifacts. Do not assume state — query the plan with `plan-show` before writing.