@mknightzzz/stw 0.1.0

package/dist/agentic-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentic-types.js","sourceRoot":"","sources":["../src/agentic-types.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,UAAU,EAAE,aAAa,CAAU,CAAC"}

package/dist/agents.d.ts

@@ -0,0 +1,7 @@
+import type { ModelTier } from './types.js';
+export interface AgentDefinition {
+    agent_id: string;
+    tool: string;
+    model: string;
+    tier: ModelTier;
+}

package/dist/agents.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agents.js.map

package/dist/agents.js.map

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

package/dist/assignments.d.ts

@@ -0,0 +1,7 @@
+import type { AssignmentsFile, TaskGraph, StwConfig } from './types.js';
+import type { AgentDefinition } from './agents.js';
+export interface AssignmentsResult {
+    assignments: AssignmentsFile;
+    warnings: string[];
+}
+export declare function generateAssignments(graph: TaskGraph, agents: AgentDefinition[], config: StwConfig): AssignmentsResult;

package/dist/assignments.js

@@ -0,0 +1,125 @@
+import { routeTask } from './router.js';
+const AGENT_FALLBACKS = {
+    cheap: ['cheap', 'medium', 'strong'],
+    medium: ['medium', 'strong'],
+    strong: ['strong'],
+    reader: ['medium', 'strong'],
+};
+export function generateAssignments(graph, agents, config) {
+    const warnings = [...detectScopeOverlaps(graph), ...detectStaleAssignmentsAfterReplan(graph)];
+    const assignments = graph.tasks.map((task) => createAssignment(task, agents, config));
+    return {
+        assignments: {
+            schema_version: 1,
+            run_id: graph.run_id,
+            assignments,
+        },
+        warnings,
+    };
+}
+function createAssignment(task, agents, config) {
+    const route = routeTask({
+        risk: task.risk,
+        task_type: task.task_type,
+        model_tier: task.model_tier,
+    }, config);
+    const agent = selectAgent(agents, route.tier);
+    const reasonParts = [
+        `task_type=${task.task_type}`,
+        `risk=${task.risk}`,
+        `provider=${route.provider}`,
+        `provider_model=${route.model}`,
+    ];
+    if (agent.tier !== route.tier) {
+        reasonParts.push(`agent_tier=${agent.tier}`);
+    }
+    return {
+        task_id: task.id,
+        agent_id: agent.agent_id,
+        tool: agent.tool,
+        model: agent.model,
+        tier: route.tier,
+        reason: reasonParts.join(', '),
+    };
+}
+function selectAgent(agents, tier) {
+    for (const candidateTier of AGENT_FALLBACKS[tier]) {
+        const agent = agents.find((item) => item.tier === candidateTier);
+        if (agent) {
+            return agent;
+        }
+    }
+    throw new Error(`No agent available for tier "${tier}"`);
+}
+function detectScopeOverlaps(graph) {
+    const warnings = [];
+    const taskById = new Map(graph.tasks.map((task) => [task.id, task]));
+    const reachabilityCache = new Map();
+    for (let index = 0; index < graph.tasks.length; index += 1) {
+        for (let otherIndex = index + 1; otherIndex < graph.tasks.length; otherIndex += 1) {
+            const left = graph.tasks[index];
+            const right = graph.tasks[otherIndex];
+            if (isSerialized(left.id, right.id, taskById, reachabilityCache)) {
+                continue;
+            }
+            const overlap = intersectFiles(left.scope.files, right.scope.files);
+            if (overlap.length === 0) {
+                continue;
+            }
+            if (left.scope.allow_shared_files && right.scope.allow_shared_files) {
+                warnings.push(`Shared-file parallelism risk between ${left.id} and ${right.id}: ${overlap.join(', ')}`);
+                continue;
+            }
+            warnings.push(`Scope overlap between ${left.id} and ${right.id}: ${overlap.join(', ')}`);
+        }
+    }
+    return warnings;
+}
+function detectStaleAssignmentsAfterReplan(graph) {
+    const warnings = [];
+    const seen = new Set();
+    for (const task of graph.tasks) {
+        if (seen.has(task.id)) {
+            warnings.push(`Stale assignment risk after replan: duplicate task ID ${task.id}`);
+            continue;
+        }
+        seen.add(task.id);
+    }
+    return warnings;
+}
+function isSerialized(leftTaskId, rightTaskId, taskById, reachabilityCache) {
+    return (hasDependencyPath(leftTaskId, rightTaskId, taskById, reachabilityCache) ||
+        hasDependencyPath(rightTaskId, leftTaskId, taskById, reachabilityCache));
+}
+function hasDependencyPath(fromTaskId, toTaskId, taskById, reachabilityCache) {
+    return getReachableDependencies(fromTaskId, taskById, reachabilityCache).has(toTaskId);
+}
+function getReachableDependencies(taskId, taskById, reachabilityCache) {
+    const cached = reachabilityCache.get(taskId);
+    if (cached) {
+        return cached;
+    }
+    const task = taskById.get(taskId);
+    const reachable = new Set();
+    if (task) {
+        for (const dependencyId of task.dependencies) {
+            reachable.add(dependencyId);
+            for (const nestedDependencyId of getReachableDependencies(dependencyId, taskById, reachabilityCache)) {
+                reachable.add(nestedDependencyId);
+            }
+        }
+    }
+    reachabilityCache.set(taskId, reachable);
+    return reachable;
+}
+function intersectFiles(leftFiles, rightFiles) {
+    const rightSet = new Set(rightFiles);
+    const overlap = [];
+    for (const file of leftFiles) {
+        if (rightSet.has(file) && !overlap.includes(file)) {
+            overlap.push(file);
+        }
+    }
+    return overlap.sort();
+}
+//# sourceMappingURL=assignments.js.map

package/dist/assignments.js.map

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

package/dist/checkpoint.d.ts

@@ -0,0 +1,35 @@
+export declare const CHECKPOINT_ORDER: readonly ["pre_worker", "post_worker", "post_write", "post_validate", "post_review", "complete"];
+export type CheckpointName = (typeof CHECKPOINT_ORDER)[number];
+export interface ProcessedNotesCheckpoint {
+    schema_version: 1;
+    mr_iid: number;
+    last_seen_at: string;
+    last_processed_note_id: number | null;
+    processed_note_ids: number[];
+    updated_at: string;
+}
+/**
+ * Reads the checkpoint directory and returns the name of the next
+ * incomplete checkpoint. Walks the ordered list and returns the first
+ * checkpoint whose file does not exist.
+ *
+ * Returns null if all checkpoints exist (task is fully done).
+ */
+export declare function resumeFromCheckpoint(taskDir: string): CheckpointName | null;
+/**
+ * Persists checkpoint data atomically.
+ * Uses writeAtomic (write to temp, then rename) for crash safety.
+ */
+export declare function writeCheckpoint(taskDir: string, checkpoint: CheckpointName, data: unknown): void;
+/**
+ * Removes checkpoint files from `fromCheckpoint` onwards (inclusive).
+ * Used before a retry to prevent stale checkpoint data from a previous
+ * attempt being mistaken for current-attempt data on crash recovery.
+ */
+export declare function clearCheckpointsFrom(taskDir: string, fromCheckpoint: CheckpointName): void;
+/**
+ * Reads checkpoint data. Returns null if the checkpoint file does not exist.
+ */
+export declare function readCheckpoint<T>(taskDir: string, checkpoint: CheckpointName): T | null;
+export declare function readProcessedNotesCheckpoint(stwRoot: string | undefined, runId: string | undefined, mrIid: number): ProcessedNotesCheckpoint | null;
+export declare function writeProcessedNotesCheckpoint(stwRoot: string | undefined, runId: string | undefined, checkpoint: ProcessedNotesCheckpoint): void;

package/dist/checkpoint.js

@@ -0,0 +1,78 @@
+import { join } from 'node:path';
+import { existsSync, unlinkSync } from 'node:fs';
+import { writeAtomic } from './storage.js';
+import { readJson } from './storage.js';
+import { fileExists, pollerCheckpointPath, writeJson } from './storage.js';
+export const CHECKPOINT_ORDER = [
+    'pre_worker',
+    'post_worker',
+    'post_write',
+    'post_validate',
+    'post_review',
+    'complete',
+];
+function checkpointPath(taskDir, checkpoint) {
+    return join(taskDir, 'checkpoints', `${checkpoint}.json`);
+}
+/**
+ * Reads the checkpoint directory and returns the name of the next
+ * incomplete checkpoint. Walks the ordered list and returns the first
+ * checkpoint whose file does not exist.
+ *
+ * Returns null if all checkpoints exist (task is fully done).
+ */
+export function resumeFromCheckpoint(taskDir) {
+    for (const cp of CHECKPOINT_ORDER) {
+        if (!existsSync(checkpointPath(taskDir, cp))) {
+            return cp;
+        }
+    }
+    // All checkpoints exist — task is fully done
+    return null;
+}
+/**
+ * Persists checkpoint data atomically.
+ * Uses writeAtomic (write to temp, then rename) for crash safety.
+ */
+export function writeCheckpoint(taskDir, checkpoint, data) {
+    const filePath = checkpointPath(taskDir, checkpoint);
+    writeAtomic(filePath, JSON.stringify(data, null, 2) + '\n');
+}
+/**
+ * Removes checkpoint files from `fromCheckpoint` onwards (inclusive).
+ * Used before a retry to prevent stale checkpoint data from a previous
+ * attempt being mistaken for current-attempt data on crash recovery.
+ */
+export function clearCheckpointsFrom(taskDir, fromCheckpoint) {
+    const startIdx = CHECKPOINT_ORDER.indexOf(fromCheckpoint);
+    for (let i = startIdx; i < CHECKPOINT_ORDER.length; i++) {
+        const filePath = checkpointPath(taskDir, CHECKPOINT_ORDER[i]);
+        if (existsSync(filePath)) {
+            unlinkSync(filePath);
+        }
+    }
+}
+/**
+ * Reads checkpoint data. Returns null if the checkpoint file does not exist.
+ */
+export function readCheckpoint(taskDir, checkpoint) {
+    const filePath = checkpointPath(taskDir, checkpoint);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    return readJson(filePath);
+}
+export function readProcessedNotesCheckpoint(stwRoot, runId, mrIid) {
+    if (!stwRoot || !runId)
+        return null;
+    const filePath = pollerCheckpointPath(stwRoot, runId, mrIid);
+    if (!fileExists(filePath))
+        return null;
+    return readJson(filePath);
+}
+export function writeProcessedNotesCheckpoint(stwRoot, runId, checkpoint) {
+    if (!stwRoot || !runId)
+        return;
+    writeJson(pollerCheckpointPath(stwRoot, runId, checkpoint.mr_iid), checkpoint);
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/checkpoint.js.map

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

package/dist/circuit-breaker.d.ts

@@ -0,0 +1,17 @@
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export interface CircuitBreakerOptions {
+    failureThreshold?: number;
+    cooldownMs?: number;
+}
+export declare class CircuitBreaker {
+    private readonly circuits;
+    private readonly failureThreshold;
+    private readonly cooldownMs;
+    constructor(options?: CircuitBreakerOptions);
+    isAvailable(provider: string, tier?: string): boolean;
+    recordSuccess(provider: string, tier?: string): void;
+    recordFailure(provider: string, tier?: string): void;
+    getState(provider: string, tier?: string): CircuitState;
+    reset(provider: string, tier?: string): void;
+    private getKey;
+}

package/dist/circuit-breaker.js

@@ -0,0 +1,65 @@
+export class CircuitBreaker {
+    circuits = new Map();
+    failureThreshold;
+    cooldownMs;
+    constructor(options) {
+        this.failureThreshold = options?.failureThreshold ?? 3;
+        this.cooldownMs = options?.cooldownMs ?? 60_000;
+    }
+    isAvailable(provider, tier) {
+        const circuit = this.circuits.get(this.getKey(provider, tier));
+        if (!circuit || circuit.state === 'closed')
+            return true;
+        if (circuit.state === 'open') {
+            const elapsed = Date.now() - circuit.lastFailureAt;
+            if (elapsed >= this.cooldownMs) {
+                circuit.state = 'half-open';
+                return true;
+            }
+            return false;
+        }
+        return true;
+    }
+    recordSuccess(provider, tier) {
+        const circuit = this.circuits.get(this.getKey(provider, tier));
+        if (!circuit)
+            return;
+        circuit.state = 'closed';
+        circuit.consecutiveFailures = 0;
+    }
+    recordFailure(provider, tier) {
+        const key = this.getKey(provider, tier);
+        let circuit = this.circuits.get(key);
+        if (!circuit) {
+            circuit = { state: 'closed', consecutiveFailures: 0, lastFailureAt: 0 };
+            this.circuits.set(key, circuit);
+        }
+        circuit.consecutiveFailures++;
+        circuit.lastFailureAt = Date.now();
+        if (circuit.state === 'half-open') {
+            circuit.state = 'open';
+        }
+        else if (circuit.consecutiveFailures >= this.failureThreshold) {
+            circuit.state = 'open';
+        }
+    }
+    getState(provider, tier) {
+        const circuit = this.circuits.get(this.getKey(provider, tier));
+        if (!circuit)
+            return 'closed';
+        if (circuit.state === 'open') {
+            const elapsed = Date.now() - circuit.lastFailureAt;
+            if (elapsed >= this.cooldownMs) {
+                circuit.state = 'half-open';
+            }
+        }
+        return circuit.state;
+    }
+    reset(provider, tier) {
+        this.circuits.delete(this.getKey(provider, tier));
+    }
+    getKey(provider, tier) {
+        return tier ? `${provider}:${tier}` : provider;
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"AAaA,MAAM,OAAO,cAAc;IACR,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;IAC9C,gBAAgB,CAAS;IACzB,UAAU,CAAS;IAEpC,YAAY,OAA+B;QACzC,IAAI,CAAC,gBAAgB,GAAG,OAAO,EAAE,gBAAgB,IAAI,CAAC,CAAC;QACvD,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,MAAM,CAAC;IAClD,CAAC;IAED,WAAW,CAAC,QAAgB,EAAE,IAAa;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/D,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAExD,IAAI,OAAO,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC;YACnD,IAAI,OAAO,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBAC/B,OAAO,CAAC,KAAK,GAAG,WAAW,CAAC;gBAC5B,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED,aAAa,CAAC,QAAgB,EAAE,IAAa;QAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/D,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,OAAO,CAAC,KAAK,GAAG,QAAQ,CAAC;QACzB,OAAO,CAAC,mBAAmB,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,aAAa,CAAC,QAAgB,EAAE,IAAa;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACxC,IAAI,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,mBAAmB,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC;YACxE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAClC,CAAC;QAED,OAAO,CAAC,mBAAmB,EAAE,CAAC;QAC9B,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEnC,IAAI,OAAO,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAClC,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC;QACzB,CAAC;aAAM,IAAI,OAAO,CAAC,mBAAmB,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAChE,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC;QACzB,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,QAAgB,EAAE,IAAa;QACtC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;QAC/D,IAAI,CAAC,OAAO;YAAE,OAAO,QAAQ,CAAC;QAE9B,IAAI,OAAO,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC;YACnD,IAAI,OAAO,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBAC/B,OAAO,CAAC,KAAK,GAAG,WAAW,CAAC;YAC9B,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC,KAAK,CAAC;IACvB,CAAC;IAED,KAAK,CAAC,QAAgB,EAAE,IAAa;QACnC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;IACpD,CAAC;IAEO,MAAM,CAAC,QAAgB,EAAE,IAAa;QAC5C,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,QAAQ,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;IACjD,CAAC;CACF"}

package/dist/claim.d.ts

@@ -0,0 +1,6 @@
+export interface ClaimResult {
+    claimed: boolean;
+    holder?: string;
+}
+export declare function claimTask(stwRoot: string, runId: string, taskId: string, agentId: string): Promise<ClaimResult>;
+export declare function releaseClaim(stwRoot: string, runId: string, taskId: string): void;

package/dist/claim.js

@@ -0,0 +1,135 @@
+import { spawn } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { taskDir } from './storage.js';
+const LOCK_READY = '__stw_claim_locked__';
+const LOCK_COMMAND = `printf '%s\\n' '${LOCK_READY}'; cat >/dev/null`;
+export async function claimTask(stwRoot, runId, taskId, agentId) {
+    const dir = taskDir(stwRoot, runId, taskId);
+    const lockPath = join(dir, 'claim.lock');
+    const statusPath = join(dir, 'status.json');
+    mkdirSync(dir, { recursive: true });
+    return await withTaskClaimLock(lockPath, () => {
+        const existing = readClaimStatus(statusPath);
+        if (existing && (existing.status === 'in_progress' || existing.status === 'complete')) {
+            return {
+                claimed: false,
+                holder: existing.agent_id,
+            };
+        }
+        const nextStatus = {
+            schema_version: 1,
+            task_id: taskId,
+            agent_id: agentId,
+            status: 'in_progress',
+            started_at: new Date().toISOString(),
+            notes: '',
+        };
+        writeFileSync(statusPath, JSON.stringify(nextStatus, null, 2) + '\n', 'utf-8');
+        return { claimed: true };
+    });
+}
+export function releaseClaim(stwRoot, runId, taskId) {
+    const dir = taskDir(stwRoot, runId, taskId);
+    const lockPath = join(dir, 'claim.lock');
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+        // Lock file may not exist, ignore
+    }
+}
+function readClaimStatus(statusPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(statusPath, 'utf-8'));
+        if (typeof parsed?.status !== 'string') {
+            throw new Error('Invalid status file: missing status field');
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+async function withTaskClaimLock(lockPath, callback) {
+    const child = spawn('flock', ['-x', '-w', '10', lockPath, 'sh', '-c', LOCK_COMMAND], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    await waitForLock(child);
+    try {
+        return await callback();
+    }
+    finally {
+        const released = waitForExit(child);
+        try {
+            child.stdin.end();
+        }
+        catch {
+            /* pipe already closed */
+        }
+        await released;
+    }
+}
+function waitForLock(child) {
+    return new Promise((resolve, reject) => {
+        let stdout = '';
+        let stderr = '';
+        const cleanup = () => {
+            child.stdout.off('data', onStdout);
+            child.stderr.off('data', onStderr);
+            child.off('error', onError);
+            child.off('exit', onExit);
+        };
+        const onStdout = (chunk) => {
+            stdout += chunk.toString();
+            if (stdout.includes(LOCK_READY)) {
+                cleanup();
+                resolve();
+            }
+        };
+        const onStderr = (chunk) => {
+            stderr += chunk.toString();
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const onExit = (code, signal) => {
+            cleanup();
+            reject(new Error(`flock exited before lock was acquired (code: ${code ?? 'null'}, signal: ${signal ?? 'null'}, stderr: ${stderr.trim()})`));
+        };
+        child.stdout.on('data', onStdout);
+        child.stderr.on('data', onStderr);
+        child.on('error', onError);
+        child.on('exit', onExit);
+    });
+}
+function waitForExit(child) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const onExit = (code, signal) => {
+            cleanup();
+            if (code === 0 && signal === null) {
+                resolve();
+                return;
+            }
+            reject(new Error(`flock exited unexpectedly while releasing lock (code: ${code ?? 'null'}, signal: ${signal ?? 'null'})`));
+        };
+        const cleanup = () => {
+            child.off('error', onError);
+            child.off('exit', onExit);
+        };
+        child.on('error', onError);
+        child.on('exit', onExit);
+    });
+}
+function isMissingFileError(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}
+//# sourceMappingURL=claim.js.map

package/dist/claim.js.map

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

package/dist/clarity-gate.d.ts

@@ -0,0 +1,12 @@
+import type { StwConfig, SeedFileEntry } from './types.js';
+export interface ClarityCheckOptions {
+    idea: string;
+    seedFiles?: SeedFileEntry[];
+    config: StwConfig;
+}
+export interface ClarityResult {
+    clear: boolean;
+    feedback?: string;
+    suggestedIdea?: string;
+}
+export declare function checkIdeaClarity(options: ClarityCheckOptions): Promise<ClarityResult>;

package/dist/clarity-gate.js

@@ -0,0 +1,83 @@
+import { callProvider } from './provider.js';
+import { routeTask } from './router.js';
+export async function checkIdeaClarity(options) {
+    const { idea, seedFiles, config } = options;
+    const seedBlock = seedFiles && seedFiles.length > 0
+        ? `\n\nSeed files provided:\n${seedFiles.map((f) => `- ${f.relativePath} (${f.sizeHuman}${f.isBinary ? ', binary' : ''})`).join('\n')}`
+        : '';
+    const prompt = `You evaluate whether a project idea is specific enough to generate a technical spec.
+Be PERMISSIVE — lean toward "clear": true when borderline. Only reject when the idea is genuinely too vague to produce anything useful.
+
+Evaluate:
+- Does the idea specify what output is wanted (API, CLI, dashboard, report, library)?
+- Does the idea specify what to do with the data/inputs (transform, analyze, visualize, serve)?
+- Is there at least one actionable verb?
+- If seed files are listed, does the idea reference or imply how to use them?
+
+Respond with JSON only: { "clear": true/false, "feedback": "...", "suggested_idea": "..." }
+
+Example clear idea: "Build a Python CLI that reads expenses.xlsx, groups spending by category, outputs a summary CSV"
+→ { "clear": true }
+
+Example vague idea: "do something with this"
+→ { "clear": false, "feedback": "No output format or processing action specified.", "suggested_idea": "Build a CLI that reads data.csv and outputs a summary report grouped by the first column" }
+
+The idea to evaluate:
+"${idea}"${seedBlock}`;
+    try {
+        const route = routeTask({
+            risk: 'low',
+            task_type: 'planning',
+            model_tier: 'cheap',
+            execution_mode: 'conservative',
+            planner_eligible: false,
+        }, config);
+        const providerConfig = config.providers[route.provider];
+        if (!providerConfig) {
+            // No cheap provider configured — fail-open
+            return { clear: true };
+        }
+        const response = await callProvider({
+            model: route.model,
+            messages: [{ role: 'user', content: prompt }],
+            max_tokens: 512,
+            temperature: 0.1,
+            timeout_ms: 30_000,
+            response_format: 'json',
+        }, providerConfig, config.defaults, 'cheap', config);
+        return parseResponse(response.content);
+    }
+    catch {
+        // Fail-open: infrastructure errors should not block the user
+        console.warn('[clarity] Clarity check failed, proceeding anyway');
+        return { clear: true };
+    }
+}
+function stripCodeFences(content) {
+    const trimmed = content.trim();
+    if (trimmed.startsWith('```')) {
+        const firstNewline = trimmed.indexOf('\n');
+        const lastFence = trimmed.lastIndexOf('```');
+        if (lastFence > firstNewline) {
+            return trimmed.slice(firstNewline + 1, lastFence).trim();
+        }
+    }
+    return trimmed;
+}
+function parseResponse(content) {
+    try {
+        const cleaned = stripCodeFences(content);
+        const parsed = JSON.parse(cleaned);
+        return {
+            clear: parsed.clear !== false, // default to clear if field missing
+            feedback: parsed.feedback,
+            suggestedIdea: parsed.suggested_idea,
+        };
+    }
+    catch {
+        // Malformed response — fail-open
+        console.warn('[clarity] Could not parse clarity response, proceeding anyway');
+        return { clear: true };
+    }
+}
+//# sourceMappingURL=clarity-gate.js.map

package/dist/clarity-gate.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};