@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdk/dist/planning-journal.js

@@ -0,0 +1,88 @@
+import { appendFile, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+export class PlanningJournal {
+    options;
+    path;
+    constructor(options) {
+        this.options = options;
+        this.path = join(options.projectDir, '.sdd', 'journal.jsonl');
+    }
+    async append(input) {
+        const existing = await this.findByIdempotency(input.idempotencyKey);
+        const requestHash = hashRequest(input);
+        if (existing) {
+            if (existing.requestHash !== requestHash) {
+                throw new Error(`conflicting idempotency key: ${input.idempotencyKey}`);
+            }
+            return existing;
+        }
+        const events = await this.readAll();
+        const event = {
+            id: randomUUID(),
+            schemaVersion: 1,
+            projectionVersion: this.options.projectionVersion ?? 1,
+            projectId: input.projectId,
+            source: {
+                id: this.options.sourceId,
+                kind: this.options.sourceKind ?? 'sdk',
+                seq: events.filter((candidate) => candidate.source.id === this.options.sourceId).length + 1,
+            },
+            runId: this.options.runId,
+            workstreamId: input.workstreamId,
+            planId: input.planId,
+            itemId: input.itemId,
+            actor: input.actor,
+            authority: 'local',
+            type: input.type,
+            idempotencyKey: input.idempotencyKey,
+            causationId: input.causationId,
+            occurredAt: new Date().toISOString(),
+            payload: input.payload,
+            evidenceIds: input.evidenceIds ?? [],
+            parentEventIds: input.parentEventIds ?? [],
+            trace: input.trace ?? {},
+            requestHash,
+        };
+        await mkdir(join(this.options.projectDir, '.sdd'), { recursive: true });
+        await appendFile(this.path, `${JSON.stringify(event)}\n`, 'utf8');
+        return event;
+    }
+    async readAll() {
+        let raw = '';
+        try {
+            raw = await readFile(this.path, 'utf8');
+        }
+        catch {
+            return [];
+        }
+        return raw
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    async compact(events) {
+        await mkdir(join(this.options.projectDir, '.sdd'), { recursive: true });
+        const tmp = `${this.path}.tmp`;
+        await writeFile(tmp, events.map((event) => JSON.stringify(event)).join('\n') + (events.length ? '\n' : ''), 'utf8');
+        await rename(tmp, this.path);
+    }
+    async findByIdempotency(idempotencyKey) {
+        const events = await this.readAll();
+        return events.find((event) => event.idempotencyKey === idempotencyKey) ?? null;
+    }
+}
+function hashRequest(input) {
+    return createHash('sha256')
+        .update(JSON.stringify({
+        projectId: input.projectId,
+        type: input.type,
+        payload: input.payload,
+        planId: input.planId,
+        itemId: input.itemId,
+        actor: input.actor,
+    }))
+        .digest('hex');
+}
+//# sourceMappingURL=planning-journal.js.map

package/sdk/dist/planning-journal.js.map

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

package/sdk/dist/planning-runtime.d.ts

@@ -0,0 +1,67 @@
+import { PlanningJournal, type PlanningEventActor } from './planning-journal.js';
+type RuntimeOptions = {
+    projectDir: string;
+    projectId: string;
+    runId: string;
+    sourceId: string;
+    actor: PlanningEventActor;
+};
+type RuntimeMeta = {
+    idempotencyKey: string;
+    planId?: string;
+    itemId?: string;
+};
+type NextInput = RuntimeMeta & {
+    selector?: {
+        itemId?: string;
+        titleIncludes?: string;
+    };
+    createPlan?: {
+        title: string;
+        items: Array<{
+            title: string;
+            description?: string;
+            dependsOn?: string[];
+        }>;
+    };
+};
+type CheckpointInput = RuntimeMeta & {
+    summary?: string;
+    subTasks?: Array<{
+        id?: string;
+        text: string;
+    }>;
+    agentCriteria?: Array<{
+        id?: string;
+        text: string;
+    }>;
+    criteriaMet?: string[];
+    blocked?: {
+        reason: string;
+        nextAction?: string;
+    };
+};
+type DoneInput = RuntimeMeta & {
+    summary: string;
+    blockers?: string[];
+    criteriaMet?: string[];
+    evidenceRefs?: string[];
+    evidencePolicy?: 'auto' | 'explicit' | 'waive';
+    evidenceWaiverReason?: string;
+    advance?: boolean;
+};
+export declare class PlanningRuntime {
+    private readonly options;
+    readonly journal: PlanningJournal;
+    constructor(options: RuntimeOptions);
+    status(input: RuntimeMeta): Promise<import("./planning-journal.js").PlanningEvent>;
+    next(input: NextInput): Promise<import("./planning-journal.js").PlanningEvent>;
+    checkpoint(input: CheckpointInput): Promise<import("./planning-journal.js").PlanningEvent>;
+    sync(input: RuntimeMeta & {
+        cursor?: string;
+    }): Promise<import("./planning-journal.js").PlanningEvent>;
+    done(input: DoneInput): Promise<import("./planning-journal.js").PlanningEvent>;
+    private record;
+}
+export {};
+//# sourceMappingURL=planning-runtime.d.ts.map

package/sdk/dist/planning-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planning-runtime.d.ts","sourceRoot":"","sources":["../src/planning-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEjF,KAAK,cAAc,GAAG;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,kBAAkB,CAAC;CAC3B,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,KAAK,SAAS,GAAG,WAAW,GAAG;IAC7B,QAAQ,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,UAAU,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAC;YAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;CAC7G,CAAC;AAEF,KAAK,eAAe,GAAG,WAAW,GAAG;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,aAAa,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD,CAAC;AAEF,KAAK,SAAS,GAAG,WAAW,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;IAC/C,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,qBAAa,eAAe;IAGd,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;gBAEL,OAAO,EAAE,cAAc;IASpD,MAAM,CAAC,KAAK,EAAE,WAAW;IAIzB,IAAI,CAAC,KAAK,EAAE,SAAS;IAOrB,UAAU,CAAC,KAAK,EAAE,eAAe;IAUjC,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAI7C,IAAI,CAAC,KAAK,EAAE,SAAS;IAYrB,OAAO,CAAC,MAAM;CAWf"}

package/sdk/dist/planning-runtime.js

@@ -0,0 +1,58 @@
+import { PlanningJournal } from './planning-journal.js';
+export class PlanningRuntime {
+    options;
+    journal;
+    constructor(options) {
+        this.options = options;
+        this.journal = new PlanningJournal({
+            projectDir: options.projectDir,
+            sourceId: options.sourceId,
+            runId: options.runId,
+            sourceKind: 'sdk',
+        });
+    }
+    status(input) {
+        return this.record('plan.status', input, {});
+    }
+    next(input) {
+        return this.record('plan.next', input, {
+            selector: input.selector,
+            createPlan: input.createPlan,
+        });
+    }
+    checkpoint(input) {
+        return this.record('plan.checkpoint', input, {
+            summary: input.summary,
+            subTasks: input.subTasks,
+            agentCriteria: input.agentCriteria,
+            criteriaMet: input.criteriaMet,
+            blocked: input.blocked,
+        });
+    }
+    sync(input) {
+        return this.record('plan.sync', input, { cursor: input.cursor });
+    }
+    done(input) {
+        return this.record('plan.done', input, {
+            summary: input.summary,
+            blockers: input.blockers,
+            criteriaMet: input.criteriaMet,
+            evidenceRefs: input.evidenceRefs,
+            evidencePolicy: input.evidencePolicy ?? 'auto',
+            evidenceWaiverReason: input.evidenceWaiverReason,
+            advance: input.advance ?? true,
+        });
+    }
+    record(type, input, payload) {
+        return this.journal.append({
+            projectId: this.options.projectId,
+            type,
+            actor: this.options.actor,
+            planId: input.planId,
+            itemId: input.itemId,
+            idempotencyKey: input.idempotencyKey,
+            payload,
+        });
+    }
+}
+//# sourceMappingURL=planning-runtime.js.map

package/sdk/dist/planning-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planning-runtime.js","sourceRoot":"","sources":["../src/planning-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAA2B,MAAM,uBAAuB,CAAC;AAuCjF,MAAM,OAAO,eAAe;IAGG;IAFpB,OAAO,CAAkB;IAElC,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;QAClD,IAAI,CAAC,OAAO,GAAG,IAAI,eAAe,CAAC;YACjC,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,UAAU,EAAE,KAAK;SAClB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,KAAkB;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,IAAI,CAAC,KAAgB;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,EAAE;YACrC,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,UAAU,EAAE,KAAK,CAAC,UAAU;SAC7B,CAAC,CAAC;IACL,CAAC;IAED,UAAU,CAAC,KAAsB;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,KAAK,EAAE;YAC3C,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC,KAAwC;QAC3C,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,IAAI,CAAC,KAAgB;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,EAAE;YACrC,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,cAAc,EAAE,KAAK,CAAC,cAAc,IAAI,MAAM;YAC9C,oBAAoB,EAAE,KAAK,CAAC,oBAAoB;YAChD,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;SAC/B,CAAC,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,IAAY,EAAE,KAAkB,EAAE,OAAgC;QAC/E,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;YACzB,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS;YACjC,IAAI;YACJ,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;YACzB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,cAAc,EAAE,KAAK,CAAC,cAAc;YACpC,OAAO;SACR,CAAC,CAAC;IACL,CAAC;CACF"}

package/sdk/dist/prompt-builder.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Prompt builder — assembles executor prompts from parsed plans.
+ *
+ * Converts a ParsedPlan into a structured prompt that tells the
+ * executor agent exactly what to do: follow the tasks sequentially,
+ * verify each one, and produce a SUMMARY.md at the end.
+ */
+import type { ParsedPlan } from './types.js';
+declare const DEFAULT_ALLOWED_TOOLS: string[];
+/**
+ * Extract the tools list from a sdd-executor.md agent definition.
+ * Falls back to DEFAULT_ALLOWED_TOOLS if parsing fails.
+ */
+export declare function parseAgentTools(agentDef: string): string[];
+/**
+ * Extract the role instructions from a sdd-executor.md agent definition.
+ * Returns the <role>...</role> block content, or empty string.
+ */
+export declare function parseAgentRole(agentDef: string): string;
+/**
+ * Options for buildExecutorPrompt beyond the required plan.
+ */
+export interface ExecutorPromptOptions {
+    /** Raw content of sdd-executor.md agent definition. */
+    agentDef?: string;
+    /** Phase directory relative to project root (e.g. `.planning/phases/01-auth`). */
+    phaseDir?: string;
+}
+/**
+ * Build the executor prompt from a parsed plan and optional agent definition.
+ *
+ * The prompt instructs the executor to:
+ * 1. Follow the plan tasks sequentially
+ * 2. Run verification for each task
+ * 3. Commit each task individually
+ * 4. Produce a SUMMARY.md file on completion
+ *
+ * @param plan - Parsed plan structure from plan-parser
+ * @param agentDefOrOpts - Raw agent definition string (legacy) or ExecutorPromptOptions
+ * @returns Assembled prompt string
+ */
+export declare function buildExecutorPrompt(plan: ParsedPlan, agentDefOrOpts?: string | ExecutorPromptOptions): string;
+export { DEFAULT_ALLOWED_TOOLS };
+//# sourceMappingURL=prompt-builder.d.ts.map

package/sdk/dist/prompt-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-builder.d.ts","sourceRoot":"","sources":["../src/prompt-builder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAY,MAAM,YAAY,CAAC;AAIvD,QAAA,MAAM,qBAAqB,UAAoD,CAAC;AAIhF;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAc1D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGvD;AA8CD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,qBAAqB,GAAG,MAAM,CAuG7G;AAED,OAAO,EAAE,qBAAqB,EAAE,CAAC"}

package/sdk/dist/prompt-builder.js

@@ -0,0 +1,180 @@
+/**
+ * Prompt builder — assembles executor prompts from parsed plans.
+ *
+ * Converts a ParsedPlan into a structured prompt that tells the
+ * executor agent exactly what to do: follow the tasks sequentially,
+ * verify each one, and produce a SUMMARY.md at the end.
+ */
+// ─── Constants ───────────────────────────────────────────────────────────────
+const DEFAULT_ALLOWED_TOOLS = ['Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob'];
+// ─── Agent definition parsing ────────────────────────────────────────────────
+/**
+ * Extract the tools list from a sdd-executor.md agent definition.
+ * Falls back to DEFAULT_ALLOWED_TOOLS if parsing fails.
+ */
+export function parseAgentTools(agentDef) {
+    // Look for "tools:" in the YAML frontmatter
+    const frontmatterMatch = agentDef.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch)
+        return DEFAULT_ALLOWED_TOOLS;
+    const toolsMatch = frontmatterMatch[1].match(/^tools:\s*(.+)$/m);
+    if (!toolsMatch)
+        return DEFAULT_ALLOWED_TOOLS;
+    const tools = toolsMatch[1]
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean);
+    return tools.length > 0 ? tools : DEFAULT_ALLOWED_TOOLS;
+}
+/**
+ * Extract the role instructions from a sdd-executor.md agent definition.
+ * Returns the <role>...</role> block content, or empty string.
+ */
+export function parseAgentRole(agentDef) {
+    const match = agentDef.match(/<role>([\s\S]*?)<\/role>/i);
+    return match ? match[1].trim() : '';
+}
+// ─── Prompt assembly ─────────────────────────────────────────────────────────
+/**
+ * Format a single task into a prompt block.
+ */
+function formatTask(task, index) {
+    const lines = [];
+    lines.push(`### Task ${index + 1}: ${task.name}`);
+    if (task.files.length > 0) {
+        lines.push(`**Files:** ${task.files.join(', ')}`);
+    }
+    if (task.read_first.length > 0) {
+        lines.push(`**Read first:** ${task.read_first.join(', ')}`);
+    }
+    lines.push('');
+    lines.push('**Action:**');
+    lines.push(task.action);
+    if (task.verify) {
+        lines.push('');
+        lines.push('**Verify:**');
+        lines.push(task.verify);
+    }
+    if (task.done) {
+        lines.push('');
+        lines.push('**Done when:**');
+        lines.push(task.done);
+    }
+    if (task.acceptance_criteria.length > 0) {
+        lines.push('');
+        lines.push('**Acceptance criteria:**');
+        for (const criterion of task.acceptance_criteria) {
+            lines.push(`- ${criterion}`);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Build the executor prompt from a parsed plan and optional agent definition.
+ *
+ * The prompt instructs the executor to:
+ * 1. Follow the plan tasks sequentially
+ * 2. Run verification for each task
+ * 3. Commit each task individually
+ * 4. Produce a SUMMARY.md file on completion
+ *
+ * @param plan - Parsed plan structure from plan-parser
+ * @param agentDefOrOpts - Raw agent definition string (legacy) or ExecutorPromptOptions
+ * @returns Assembled prompt string
+ */
+export function buildExecutorPrompt(plan, agentDefOrOpts) {
+    const opts = typeof agentDefOrOpts === 'string'
+        ? { agentDef: agentDefOrOpts }
+        : agentDefOrOpts ?? {};
+    const { agentDef, phaseDir } = opts;
+    const sections = [];
+    // ── Role instructions from agent definition ──
+    if (agentDef) {
+        const role = parseAgentRole(agentDef);
+        if (role) {
+            sections.push(`## Role\n\n${role}`);
+        }
+    }
+    // ── Objective ──
+    if (plan.objective) {
+        sections.push(`## Objective\n\n${plan.objective}`);
+    }
+    else {
+        sections.push(`## Objective\n\nExecute plan: ${plan.frontmatter.plan || plan.frontmatter.phase || 'unnamed'}`);
+    }
+    // ── Plan metadata ──
+    const meta = [];
+    if (plan.frontmatter.phase)
+        meta.push(`Phase: ${plan.frontmatter.phase}`);
+    if (plan.frontmatter.plan)
+        meta.push(`Plan: ${plan.frontmatter.plan}`);
+    if (plan.frontmatter.type)
+        meta.push(`Type: ${plan.frontmatter.type}`);
+    if (meta.length > 0) {
+        sections.push(`## Plan Info\n\n${meta.join('\n')}`);
+    }
+    // ── Context references ──
+    if (plan.context_refs.length > 0) {
+        const refs = plan.context_refs.map((r) => `- @${r}`).join('\n');
+        sections.push(`## Context Files\n\nRead these files for context before starting:\n${refs}`);
+    }
+    // ── Tasks ──
+    if (plan.tasks.length > 0) {
+        const taskBlocks = plan.tasks.map((t, i) => formatTask(t, i)).join('\n\n---\n\n');
+        sections.push(`## Tasks\n\nExecute these tasks sequentially. For each task: read any referenced files, execute the action, run verification, confirm done criteria, then commit.\n\n${taskBlocks}`);
+    }
+    else {
+        sections.push(`## Tasks\n\nNo tasks defined in this plan. Review the objective and determine if any actions are needed.`);
+    }
+    // ── Must-haves ──
+    if (plan.frontmatter.must_haves) {
+        const mh = plan.frontmatter.must_haves;
+        const parts = [];
+        if (mh.truths.length > 0) {
+            parts.push('**Truths (invariants):**');
+            for (const t of mh.truths) {
+                parts.push(`- ${t}`);
+            }
+        }
+        if (mh.artifacts.length > 0) {
+            parts.push('**Required artifacts:**');
+            for (const a of mh.artifacts) {
+                parts.push(`- \`${a.path}\`: ${a.provides}`);
+            }
+        }
+        if (mh.key_links.length > 0) {
+            parts.push('**Key links:**');
+            for (const l of mh.key_links) {
+                parts.push(`- ${l.from} → ${l.to} via ${l.via}`);
+            }
+        }
+        if (parts.length > 0) {
+            sections.push(`## Must-Haves\n\n${parts.join('\n')}`);
+        }
+    }
+    // ── Completion instructions ──
+    // Derive the SUMMARY filename from plan frontmatter (e.g. "01-01-SUMMARY.md")
+    // Phase may be "01-auth" or "01" — extract leading number, zero-pad to 2 digits.
+    const phaseNum = (plan.frontmatter.phase || '').match(/^(\d+)/)?.[1] || '';
+    const planNum = (plan.frontmatter.plan || '').match(/^(\d+)/)?.[1] || '';
+    const summaryName = phaseNum && planNum
+        ? `${phaseNum.padStart(2, '0')}-${planNum.padStart(2, '0')}-SUMMARY.md`
+        : 'SUMMARY.md';
+    const summaryPath = phaseDir
+        ? `${phaseDir}/${summaryName}`
+        : summaryName;
+    sections.push(`## Completion\n\n` +
+        `After all tasks are complete:\n` +
+        `1. Run any overall verification or success criteria checks\n` +
+        `2. Create \`${summaryPath}\` documenting:\n` +
+        `   - One-line summary of what was accomplished\n` +
+        `   - Tasks completed with commit hashes\n` +
+        `   - Any deviations from the plan\n` +
+        `   - Files created or modified\n` +
+        `   - Known issues (if any)\n` +
+        `3. Commit the SUMMARY.md\n` +
+        `4. Report completion`);
+    return sections.join('\n\n');
+}
+export { DEFAULT_ALLOWED_TOOLS };
+//# sourceMappingURL=prompt-builder.js.map

package/sdk/dist/prompt-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-builder.js","sourceRoot":"","sources":["../src/prompt-builder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,gFAAgF;AAEhF,MAAM,qBAAqB,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEhF,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,4CAA4C;IAC5C,MAAM,gBAAgB,GAAG,QAAQ,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;IACpE,IAAI,CAAC,gBAAgB;QAAE,OAAO,qBAAqB,CAAC;IAEpD,MAAM,UAAU,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACjE,IAAI,CAAC,UAAU;QAAE,OAAO,qBAAqB,CAAC;IAE9C,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC;SACxB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,qBAAqB,CAAC;AAC1D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC1D,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACtC,CAAC;AAED,gFAAgF;AAEhF;;GAEG;AACH,SAAS,UAAU,CAAC,IAAc,EAAE,KAAa;IAC/C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,YAAY,KAAK,GAAG,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAElD,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC1B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAExB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED,IAAI,IAAI,CAAC,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;QACvC,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,mBAAmB,EAAE,CAAC;YACjD,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAYD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAgB,EAAE,cAA+C;IACnG,MAAM,IAAI,GAA0B,OAAO,cAAc,KAAK,QAAQ;QACpE,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE;QAC9B,CAAC,CAAC,cAAc,IAAI,EAAE,CAAC;IACzB,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IACpC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,gDAAgD;IAChD,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,IAAI,EAAE,CAAC;YACT,QAAQ,CAAC,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,kBAAkB;IAClB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,QAAQ,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IACrD,CAAC;SAAM,CAAC;QACN,QAAQ,CAAC,IAAI,CAAC,iCAAiC,IAAI,CAAC,WAAW,CAAC,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,SAAS,EAAE,CAAC,CAAC;IACjH,CAAC;IAED,sBAAsB;IACtB,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,IAAI,IAAI,CAAC,WAAW,CAAC,KAAK;QAAE,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC;IAC1E,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI;QAAE,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;IACvE,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI;QAAE,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;IACvE,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,QAAQ,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,2BAA2B;IAC3B,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChE,QAAQ,CAAC,IAAI,CAAC,sEAAsE,IAAI,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED,cAAc;IACd,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAClF,QAAQ,CAAC,IAAI,CAAC,wKAAwK,UAAU,EAAE,CAAC,CAAC;IACtM,CAAC;SAAM,CAAC;QACN,QAAQ,CAAC,IAAI,CAAC,0GAA0G,CAAC,CAAC;IAC5H,CAAC;IAED,mBAAmB;IACnB,IAAI,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;QAChC,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC;QACvC,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,IAAI,EAAE,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,KAAK,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;YACvC,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC;gBAC1B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QAED,IAAI,EAAE,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;YACtC,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,SAAS,EAAE,CAAC;gBAC7B,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;QAED,IAAI,EAAE,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YAC7B,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,SAAS,EAAE,CAAC;gBAC7B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;YACnD,CAAC;QACH,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,QAAQ,CAAC,IAAI,CAAC,oBAAoB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED,gCAAgC;IAChC,8EAA8E;IAC9E,iFAAiF;IACjF,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3E,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACzE,MAAM,WAAW,GAAG,QAAQ,IAAI,OAAO;QACrC,CAAC,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,aAAa;QACvE,CAAC,CAAC,YAAY,CAAC;IACjB,MAAM,WAAW,GAAG,QAAQ;QAC1B,CAAC,CAAC,GAAG,QAAQ,IAAI,WAAW,EAAE;QAC9B,CAAC,CAAC,WAAW,CAAC;IAEhB,QAAQ,CAAC,IAAI,CACX,mBAAmB;QACnB,iCAAiC;QACjC,8DAA8D;QAC9D,eAAe,WAAW,mBAAmB;QAC7C,kDAAkD;QAClD,2CAA2C;QAC3C,qCAAqC;QACrC,kCAAkC;QAClC,8BAA8B;QAC9B,4BAA4B;QAC5B,sBAAsB,CACvB,CAAC;IAEF,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED,OAAO,EAAE,qBAAqB,EAAE,CAAC"}

package/sdk/dist/prompt-sanitizer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Prompt sanitizer — resolves @-file references and strips interactive CLI
+ * patterns from SDD-1 prompts so they're safe for headless SDK use.
+ *
+ * @-file references (e.g., @~/.claude/sdd/references/foo.md) are
+ * resolved by reading the file and inlining the content. This preserves the
+ * critical instructions that the real agent prompts depend on.
+ *
+ * Patterns removed (interactive-only, not useful headless):
+ * - /sdd-... skill commands (can't invoke skills in Agent SDK)
+ * - AskUserQuestion(...) calls
+ * - STOP directives in interactive contexts
+ * - SlashCommand() calls
+ * - 'wait for user' / 'ask the user' instructions
+ */
+/**
+ * Resolve @-file references by reading the file and inlining the content.
+ * References that can't be resolved (file not found) are removed silently.
+ *
+ * @param input - Prompt text with @-references
+ * @param projectDir - Project directory for resolving relative paths
+ * @returns Prompt with @-references replaced by file contents
+ */
+export declare function resolveAtReferences(input: string, projectDir?: string): string;
+/**
+ * Sanitize a prompt for headless SDK use:
+ * 1. Resolve @-file references (inline the content)
+ * 2. Strip interactive-only patterns
+ *
+ * @param input - Raw prompt string from agent/workflow files
+ * @param projectDir - Project directory for resolving relative @-references
+ * @returns Cleaned prompt ready for Agent SDK use
+ */
+export declare function sanitizePrompt(input: string, projectDir?: string): string;
+//# sourceMappingURL=prompt-sanitizer.d.ts.map

package/sdk/dist/prompt-sanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-sanitizer.d.ts","sourceRoot":"","sources":["../src/prompt-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAkBH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAkB9E;AAgCD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAgBzE"}

package/sdk/dist/prompt-sanitizer.js

@@ -0,0 +1,101 @@
+/**
+ * Prompt sanitizer — resolves @-file references and strips interactive CLI
+ * patterns from SDD-1 prompts so they're safe for headless SDK use.
+ *
+ * @-file references (e.g., @~/.claude/sdd/references/foo.md) are
+ * resolved by reading the file and inlining the content. This preserves the
+ * critical instructions that the real agent prompts depend on.
+ *
+ * Patterns removed (interactive-only, not useful headless):
+ * - /sdd-... skill commands (can't invoke skills in Agent SDK)
+ * - AskUserQuestion(...) calls
+ * - STOP directives in interactive contexts
+ * - SlashCommand() calls
+ * - 'wait for user' / 'ask the user' instructions
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+// ─── @-reference resolution ──────────────────────────────────────────────────
+/**
+ * Matches @-file references in prompt text. Handles:
+ * - @~/.claude/sdd/references/foo.md
+ * - @~/.claude/sdd/workflows/bar.md
+ * - @.planning/PROJECT.md (project-relative)
+ *
+ * Only resolves references that start a line or follow whitespace,
+ * not email addresses or @ mentions in prose.
+ */
+const AT_REFERENCE_PATTERN = /^(\s*)@(~\/[^\s]+|\.planning\/[^\s]+)/gm;
+/**
+ * Resolve @-file references by reading the file and inlining the content.
+ * References that can't be resolved (file not found) are removed silently.
+ *
+ * @param input - Prompt text with @-references
+ * @param projectDir - Project directory for resolving relative paths
+ * @returns Prompt with @-references replaced by file contents
+ */
+export function resolveAtReferences(input, projectDir) {
+    if (!input)
+        return input;
+    return input.replace(AT_REFERENCE_PATTERN, (_match, indent, refPath) => {
+        const resolvedPath = refPath.startsWith('~/')
+            ? refPath.replace('~/', `${homedir()}/`)
+            : projectDir
+                ? `${projectDir}/${refPath}`
+                : refPath;
+        try {
+            const content = readFileSync(resolvedPath, 'utf-8').trim();
+            return `${indent}${content}`;
+        }
+        catch {
+            // File not found — remove the reference silently
+            return '';
+        }
+    });
+}
+// ─── Interactive pattern stripping ───────────────────────────────────────────
+/**
+ * Patterns that are interactive-only and should be stripped for headless use.
+ * Note: @~/... file references are NOT stripped — they're resolved above.
+ */
+const LINE_PATTERNS = [
+    // @file:path/to/something references (explicit @file: directive, not @~/...)
+    /^.*@file:\S+.*$/gm,
+    // /sdd-command references — entire line containing a skill command
+    /^.*\/sdd[:-]\S+.*$/gm,
+    // AskUserQuestion(...) calls — entire line
+    /^.*AskUserQuestion\s*\(.*$/gm,
+    // SlashCommand() calls — entire line
+    /^.*SlashCommand\s*\(.*$/gm,
+    // STOP directives — lines that are primarily "STOP" instructions
+    /^.*\bSTOP\b(?:\s+(?:and\s+)?(?:wait|ask|here|now)).*$/gm,
+    /^\s*STOP\s*[.!]?\s*$/gm,
+    // 'wait for user' / 'ask the user' instruction lines
+    /^.*\bwait\s+for\s+(?:the\s+)?user\b.*$/gim,
+    /^.*\bask\s+the\s+user\b.*$/gim,
+];
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Sanitize a prompt for headless SDK use:
+ * 1. Resolve @-file references (inline the content)
+ * 2. Strip interactive-only patterns
+ *
+ * @param input - Raw prompt string from agent/workflow files
+ * @param projectDir - Project directory for resolving relative @-references
+ * @returns Cleaned prompt ready for Agent SDK use
+ */
+export function sanitizePrompt(input, projectDir) {
+    if (!input)
+        return input;
+    // Step 1: Resolve @-file references to inline content
+    let result = resolveAtReferences(input, projectDir);
+    // Step 2: Strip interactive-only patterns
+    for (const pattern of LINE_PATTERNS) {
+        pattern.lastIndex = 0;
+        result = result.replace(pattern, '');
+    }
+    // Collapse runs of 3+ blank lines down to 2 (preserve paragraph breaks)
+    result = result.replace(/\n{3,}/g, '\n\n');
+    return result.trim();
+}
+//# sourceMappingURL=prompt-sanitizer.js.map

package/sdk/dist/prompt-sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-sanitizer.js","sourceRoot":"","sources":["../src/prompt-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,oBAAoB,GAAG,yCAAyC,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,UAAmB;IACpE,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAEzB,OAAO,KAAK,CAAC,OAAO,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,MAAc,EAAE,OAAe,EAAE,EAAE;QACrF,MAAM,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;YAC3C,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,OAAO,EAAE,GAAG,CAAC;YACxC,CAAC,CAAC,UAAU;gBACV,CAAC,CAAC,GAAG,UAAU,IAAI,OAAO,EAAE;gBAC5B,CAAC,CAAC,OAAO,CAAC;QAEd,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;YAC3D,OAAO,GAAG,MAAM,GAAG,OAAO,EAAE,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,iDAAiD;YACjD,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,aAAa,GAAa;IAC9B,6EAA6E;IAC7E,mBAAmB;IAEnB,mEAAmE;IACnE,sBAAsB;IAEtB,2CAA2C;IAC3C,8BAA8B;IAE9B,qCAAqC;IACrC,2BAA2B;IAE3B,iEAAiE;IACjE,yDAAyD;IACzD,wBAAwB;IAExB,qDAAqD;IACrD,2CAA2C;IAC3C,+BAA+B;CAChC,CAAC;AAEF,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,UAAmB;IAC/D,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAEzB,sDAAsD;IACtD,IAAI,MAAM,GAAG,mBAAmB,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAEpD,0CAA0C;IAC1C,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;QACpC,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC;QACtB,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,wEAAwE;IACxE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAE3C,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;AACvB,CAAC"}

package/sdk/dist/query/active-workstream-store.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Read active workstream pointer from `.planning/active-workstream`.
+ * Invalid or stale pointers are self-healed by clearing the file.
+ */
+export declare function readActiveWorkstream(projectDir: string): string | null;
+export declare function writeActiveWorkstream(projectDir: string, name: string | null): void;
+//# sourceMappingURL=active-workstream-store.d.ts.map

package/sdk/dist/query/active-workstream-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-workstream-store.d.ts","sourceRoot":"","sources":["../../src/query/active-workstream-store.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBtE;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAcnF"}