@specship/specship-win32-arm64 0.25.0 → 0.29.0

package/lib/dist/workflows/agents/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Headless-agent registry and selection (REQ-AGENTADAPT-005/006).
+ *
+ * The agent is resolved once at run start — `--agent`, then
+ * `SPECSHIP_WORKFLOW_AGENT`, then `workflow.agent` in specship.config.json,
+ * then the coding agent that launched the command, then Claude Code — and is
+ * stored on the run so approve / revise / resume use the same one.
+ */
+import type { HeadlessAgent, HeadlessAgentConfig } from './types';
+export type { HeadlessAgent, HeadlessAgentConfig, HeadlessInvocation, StreamParseState } from './types';
+export declare const DEFAULT_WORKFLOW_AGENT: string;
+/** Run-metadata key the chosen agent is stored under. */
+export declare const RUN_AGENT_KEY = "agent";
+export declare function knownWorkflowAgents(): string[];
+export declare function getHeadlessAgent(id: string): HeadlessAgent | undefined;
+export declare class UnknownWorkflowAgentError extends Error {
+    constructor(name: string, source: string);
+}
+export interface ResolveAgentOptions {
+    flag?: string;
+    env?: NodeJS.ProcessEnv;
+    projectRoot: string;
+}
+/** The agent id for a new run, or throws UnknownWorkflowAgentError (REQ-AGENTADAPT-006.A4). */
+export declare function resolveWorkflowAgent(opts: ResolveAgentOptions): string;
+/** `workflow.agents.<id>` settings (model tier mapping), {} when unset. */
+export declare function workflowAgentConfig(projectRoot: string, id: string): HeadlessAgentConfig;
+//# sourceMappingURL=index.d.ts.map

package/lib/dist/workflows/agents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/workflows/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAElE,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGxG,eAAO,MAAM,sBAAsB,QAAyB,CAAC;AAC7D,yDAAyD;AACzD,eAAO,MAAM,aAAa,UAAU,CAAC;AAErC,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAEtE;AAED,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAIzC;AAgBD,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,+FAA+F;AAC/F,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAgBtE;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,mBAAmB,CAGxF"}

package/lib/dist/workflows/agents/index.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Headless-agent registry and selection (REQ-AGENTADAPT-005/006).
+ *
+ * The agent is resolved once at run start — `--agent`, then
+ * `SPECSHIP_WORKFLOW_AGENT`, then `workflow.agent` in specship.config.json,
+ * then the coding agent that launched the command, then Claude Code — and is
+ * stored on the run so approve / revise / resume use the same one.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnknownWorkflowAgentError = exports.RUN_AGENT_KEY = exports.DEFAULT_WORKFLOW_AGENT = void 0;
+exports.knownWorkflowAgents = knownWorkflowAgents;
+exports.getHeadlessAgent = getHeadlessAgent;
+exports.resolveWorkflowAgent = resolveWorkflowAgent;
+exports.workflowAgentConfig = workflowAgentConfig;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const claude_1 = require("./claude");
+const gemini_1 = require("./gemini");
+const AGENTS = [claude_1.claudeHeadlessAgent, gemini_1.geminiHeadlessAgent];
+exports.DEFAULT_WORKFLOW_AGENT = claude_1.claudeHeadlessAgent.id;
+/** Run-metadata key the chosen agent is stored under. */
+exports.RUN_AGENT_KEY = 'agent';
+function knownWorkflowAgents() {
+    return AGENTS.map((a) => a.id);
+}
+function getHeadlessAgent(id) {
+    return AGENTS.find((a) => a.id === id);
+}
+class UnknownWorkflowAgentError extends Error {
+    constructor(name, source) {
+        super(`Unknown workflow agent "${name}" (from ${source}). Known agents: ${knownWorkflowAgents().join(', ')}`);
+        this.name = 'UnknownWorkflowAgentError';
+    }
+}
+exports.UnknownWorkflowAgentError = UnknownWorkflowAgentError;
+function readWorkflowConfig(projectRoot) {
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'specship.config.json'), 'utf8'));
+        return (cfg && typeof cfg.workflow === 'object' && cfg.workflow) || {};
+    }
+    catch {
+        return {};
+    }
+}
+/** The agent id for a new run, or throws UnknownWorkflowAgentError (REQ-AGENTADAPT-006.A4). */
+function resolveWorkflowAgent(opts) {
+    const env = opts.env ?? process.env;
+    const cfg = readWorkflowConfig(opts.projectRoot);
+    const explicit = [
+        [opts.flag, '--agent'],
+        [env.SPECSHIP_WORKFLOW_AGENT, 'SPECSHIP_WORKFLOW_AGENT'],
+        [cfg.agent, 'workflow.agent in specship.config.json'],
+    ];
+    for (const [value, source] of explicit) {
+        if (typeof value !== 'string' || !value.trim())
+            continue;
+        const id = value.trim().toLowerCase();
+        if (!getHeadlessAgent(id))
+            throw new UnknownWorkflowAgentError(value, source);
+        return id;
+    }
+    const launcher = AGENTS.find((a) => a.id !== exports.DEFAULT_WORKFLOW_AGENT && a.launchedFrom(env));
+    return launcher?.id ?? exports.DEFAULT_WORKFLOW_AGENT;
+}
+/** `workflow.agents.<id>` settings (model tier mapping), {} when unset. */
+function workflowAgentConfig(projectRoot, id) {
+    const entry = readWorkflowConfig(projectRoot).agents?.[id];
+    return entry && typeof entry === 'object' ? entry : {};
+}
+//# sourceMappingURL=index.js.map

package/lib/dist/workflows/agents/index.js.map

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

package/lib/dist/workflows/agents/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Headless-agent adapters for workflow prompt steps (AGENTADAPT-DOC,
+ * REQ-AGENTADAPT-005). One adapter per coding agent owns that host's binary,
+ * argument translation and output parsing; the prompt runner stays
+ * host-neutral and gets the same step result whichever host ran it.
+ */
+import type { PromptNode } from '../schemas/workflow';
+import type { WorkflowEventType } from '../../types';
+/** Accumulated state while parsing an agent's streamed output. */
+export interface StreamParseState {
+    /** True once at least one line parsed as a known stream event. */
+    sawStream: boolean;
+    /** Final result text from a terminal result event, if the host sends one. */
+    resultText: string | null;
+    /** Concatenated assistant text (the result when there's no result text). */
+    assistantText: string;
+    costUsd?: number;
+    durationMs?: number;
+    model?: string;
+    /** Set when the host's own terminal event reports failure. */
+    failure?: string;
+}
+export declare function newStreamState(): StreamParseState;
+export type EmitFn = (type: WorkflowEventType, data?: Record<string, unknown>) => void;
+/** What to spawn for one step. */
+export interface HeadlessInvocation {
+    bin: string;
+    args: string[];
+    /** Written to the child's stdin, then closed. */
+    stdin: string;
+}
+/** Per-agent settings from `workflow.agents.<id>` in specship.config.json. */
+export interface HeadlessAgentConfig {
+    /** Model tier alias (`haiku`, `sonnet`, `opus`) → this host's model id. */
+    models?: Record<string, string>;
+}
+export interface HeadlessAgent {
+    /** The name `--agent` / `SPECSHIP_WORKFLOW_AGENT` / `workflow.agent` use. */
+    readonly id: string;
+    /** True when `env` shows the command was launched from inside this host. */
+    launchedFrom(env: NodeJS.ProcessEnv): boolean;
+    /**
+     * Translate a step. Returns `{ error }` — never a partial invocation — when
+     * the step uses something this host cannot honour (REQ-AGENTADAPT-007.A4).
+     */
+    build(node: PromptNode, config: HeadlessAgentConfig, env: NodeJS.ProcessEnv): HeadlessInvocation | {
+        error: string;
+    };
+    /** Parse one output line, emitting live events and folding into `state`. */
+    handleLine(line: string, emit: EmitFn, state: StreamParseState): void;
+}
+/** A short, single-line summary of a tool's input for the `tool_called` event. */
+export declare function summarizeToolInput(input: unknown): string;
+export declare function parseJsonLine(line: string): Record<string, unknown> | null;
+//# sourceMappingURL=types.d.ts.map

package/lib/dist/workflows/agents/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/workflows/agents/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,SAAS,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,cAAc,IAAI,gBAAgB,CAEjD;AAED,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAEvF,kCAAkC;AAClC,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC;IAC9C;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,mBAAmB,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,kBAAkB,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACrH,4EAA4E;IAC5E,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACvE;AAED,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAezD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAS1E"}

package/lib/dist/workflows/agents/types.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Headless-agent adapters for workflow prompt steps (AGENTADAPT-DOC,
+ * REQ-AGENTADAPT-005). One adapter per coding agent owns that host's binary,
+ * argument translation and output parsing; the prompt runner stays
+ * host-neutral and gets the same step result whichever host ran it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newStreamState = newStreamState;
+exports.summarizeToolInput = summarizeToolInput;
+exports.parseJsonLine = parseJsonLine;
+function newStreamState() {
+    return { sawStream: false, resultText: null, assistantText: '' };
+}
+/** A short, single-line summary of a tool's input for the `tool_called` event. */
+function summarizeToolInput(input) {
+    if (input == null)
+        return '';
+    let s;
+    if (typeof input === 'string') {
+        s = input;
+    }
+    else if (typeof input === 'object') {
+        const o = input;
+        const pick = o.file_path ?? o.path ?? o.command ?? o.pattern ?? o.query ?? o.url ?? o.prompt;
+        s = typeof pick === 'string' ? pick : JSON.stringify(o);
+    }
+    else {
+        s = String(input);
+    }
+    s = s.replace(/\s+/g, ' ').trim();
+    return s.length > 140 ? `${s.slice(0, 140)}…` : s;
+}
+function parseJsonLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const ev = JSON.parse(trimmed);
+        return ev && typeof ev === 'object' && !Array.isArray(ev) ? ev : null;
+    }
+    catch {
+        return null; // not JSON — ignore (hosts may print plain diagnostics)
+    }
+}
+//# sourceMappingURL=types.js.map

package/lib/dist/workflows/agents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/workflows/agents/types.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAoBH,wCAEC;AAiCD,gDAeC;AAED,sCASC;AA7DD,SAAgB,cAAc;IAC5B,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;AACnE,CAAC;AAgCD,kFAAkF;AAClF,SAAgB,kBAAkB,CAAC,KAAc;IAC/C,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IAC7B,IAAI,CAAS,CAAC;IACd,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,CAAC,GAAG,KAAK,CAAC;IACZ,CAAC;SAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,KAAgC,CAAC;QAC3C,MAAM,IAAI,GACR,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC;QAClF,CAAC,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC1D,CAAC;SAAM,CAAC;QACN,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC;IACD,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAClC,OAAO,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,SAAgB,aAAa,CAAC,IAAY;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC/B,OAAO,EAAE,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,EAA8B,CAAC,CAAC,CAAC,IAAI,CAAC;IACrG,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,CAAC,wDAAwD;IACvE,CAAC;AACH,CAAC"}

package/lib/dist/workflows/batch.d.ts

@@ -0,0 +1,63 @@
+/**
+ * REQ-THRU-001 — parallel batch runs.
+ *
+ * `specship workflow run-batch <workflow> --specs <ID,…>` starts one run per
+ * requirement, each in its own worktree. Requirements whose `implementations:`
+ * files overlap never run concurrently: the later one is placed in a later
+ * wave and waits for the earlier wave to finish. No wave holds more runs than
+ * the concurrency limit.
+ */
+export declare const DEFAULT_BATCH_CONCURRENCY = 3;
+export interface BatchSpec {
+    id: string;
+    implementationFiles: string[];
+}
+/** Statuses after which a run is finished (no longer holding its files). */
+export declare const TERMINAL_RUN_STATUSES: Set<string>;
+/**
+ * Plan the waves. Specs are visited in input order; each goes into the
+ * earliest wave that (a) comes after every wave holding a spec it shares an
+ * implementation file with, and (b) still has room under `concurrency`.
+ */
+export declare function planBatch(specs: BatchSpec[], concurrency: number): string[][];
+/**
+ * Implementation files of a requirement, read from its spec file's
+ * `implementations:` block (`path:Symbol` bullets → `path`). Null when the
+ * requirement is not found under specs/.
+ */
+export declare function implementationFilesFor(projectRoot: string, requirementId: string): string[] | null;
+export interface BatchRunResult {
+    specId: string;
+    runId: string;
+    status: string;
+    wave: number;
+}
+export interface RunBatchOptions {
+    projectRoot: string;
+    specIds: string[];
+    concurrency?: number;
+    /** Start one run for a requirement; resolves once the run is started/settled. */
+    startRun: (specId: string) => Promise<{
+        runId: string;
+        status: string;
+    }>;
+    /**
+     * Wait until a started run is finished. Default: the run is finished when
+     * `startRun` resolves. The CLI waits for a terminal status so a run paused
+     * at an approval still holds its files.
+     */
+    waitForRun?: (runId: string, status: string) => Promise<string>;
+    /** Resolve a requirement's implementation files (default: its spec file). */
+    resolveFiles?: (specId: string) => string[] | null;
+    /** Called with the full plan before any run starts. */
+    onPlan?: (waves: string[][]) => void;
+    /** Called as each run is started. */
+    onRunStarted?: (run: BatchRunResult) => void;
+}
+export interface RunBatchResult {
+    waves: string[][];
+    runs: BatchRunResult[];
+}
+/** Start the runs wave by wave; a wave finishes before the next one starts. */
+export declare function runBatch(opts: RunBatchOptions): Promise<RunBatchResult>;
+//# sourceMappingURL=batch.d.ts.map

package/lib/dist/workflows/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../src/workflows/batch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,aAA4D,CAAC;AAE/F;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CA+B7E;AAMD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAalG;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzE;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,6EAA6E;IAC7E,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,EAAE,GAAG,IAAI,CAAC;IACnD,uDAAuD;IACvD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,IAAI,CAAC;IACrC,qCAAqC;IACrC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;IAClB,IAAI,EAAE,cAAc,EAAE,CAAC;CACxB;AAED,+EAA+E;AAC/E,wBAAsB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA8B7E"}

package/lib/dist/workflows/batch.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * REQ-THRU-001 — parallel batch runs.
+ *
+ * `specship workflow run-batch <workflow> --specs <ID,…>` starts one run per
+ * requirement, each in its own worktree. Requirements whose `implementations:`
+ * files overlap never run concurrently: the later one is placed in a later
+ * wave and waits for the earlier wave to finish. No wave holds more runs than
+ * the concurrency limit.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TERMINAL_RUN_STATUSES = exports.DEFAULT_BATCH_CONCURRENCY = void 0;
+exports.planBatch = planBatch;
+exports.implementationFilesFor = implementationFilesFor;
+exports.runBatch = runBatch;
+const fs = __importStar(require("fs"));
+const postcheck_1 = require("../spec-quality/postcheck");
+exports.DEFAULT_BATCH_CONCURRENCY = 3;
+/** Statuses after which a run is finished (no longer holding its files). */
+exports.TERMINAL_RUN_STATUSES = new Set(['completed', 'failed', 'cancelled', 'rejected']);
+/**
+ * Plan the waves. Specs are visited in input order; each goes into the
+ * earliest wave that (a) comes after every wave holding a spec it shares an
+ * implementation file with, and (b) still has room under `concurrency`.
+ */
+function planBatch(specs, concurrency) {
+    const limit = Math.max(1, Math.floor(concurrency) || 1);
+    const waves = [];
+    const waveOf = new Map();
+    const filesOf = new Map();
+    for (let i = 0; i < specs.length; i++) {
+        const spec = specs[i];
+        if (waveOf.has(spec.id))
+            continue; // duplicate id — schedule once
+        const files = new Set(spec.implementationFiles.map(normalizeFile));
+        let minWave = 0;
+        for (let j = 0; j < i; j++) {
+            const earlier = specs[j];
+            const w = waveOf.get(earlier.id);
+            if (w === undefined)
+                continue;
+            const ef = filesOf.get(earlier.id);
+            for (const f of files) {
+                if (ef.has(f)) {
+                    minWave = Math.max(minWave, w + 1);
+                    break;
+                }
+            }
+        }
+        let wave = minWave;
+        while (waves[wave] && waves[wave].length >= limit)
+            wave++;
+        while (waves.length <= wave)
+            waves.push([]);
+        waves[wave].push(spec.id);
+        waveOf.set(spec.id, wave);
+        filesOf.set(spec.id, files);
+    }
+    return waves.filter((w) => w.length > 0);
+}
+function normalizeFile(f) {
+    return f.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+}
+/**
+ * Implementation files of a requirement, read from its spec file's
+ * `implementations:` block (`path:Symbol` bullets → `path`). Null when the
+ * requirement is not found under specs/.
+ */
+function implementationFilesFor(projectRoot, requirementId) {
+    const specFile = (0, postcheck_1.findSpecFile)(projectRoot, requirementId);
+    if (!specFile)
+        return null;
+    const block = (0, postcheck_1.requirementBlock)(fs.readFileSync(specFile, 'utf8'), requirementId);
+    if (block === null)
+        return null;
+    const files = new Set();
+    for (const bullet of (0, postcheck_1.linkBullets)(block, 'implementations')) {
+        const target = bullet.replace(/^`|`$/g, '').trim();
+        const colon = target.indexOf(':');
+        const file = normalizeFile(colon > 0 ? target.slice(0, colon) : target);
+        if (file)
+            files.add(file);
+    }
+    return [...files];
+}
+/** Start the runs wave by wave; a wave finishes before the next one starts. */
+async function runBatch(opts) {
+    const resolve = opts.resolveFiles ?? ((id) => implementationFilesFor(opts.projectRoot, id));
+    const specs = [];
+    const missing = [];
+    for (const id of opts.specIds) {
+        const files = resolve(id);
+        if (files === null)
+            missing.push(id);
+        else
+            specs.push({ id, implementationFiles: files });
+    }
+    if (missing.length > 0) {
+        throw new Error(`Requirement(s) not found under specs/: ${missing.join(', ')}`);
+    }
+    const waves = planBatch(specs, opts.concurrency ?? exports.DEFAULT_BATCH_CONCURRENCY);
+    opts.onPlan?.(waves);
+    const runs = [];
+    for (let w = 0; w < waves.length; w++) {
+        const wave = waves[w];
+        const settled = await Promise.all(wave.map(async (specId) => {
+            const started = await opts.startRun(specId);
+            const run = { specId, runId: started.runId, status: started.status, wave: w };
+            opts.onRunStarted?.(run);
+            if (opts.waitForRun)
+                run.status = await opts.waitForRun(started.runId, started.status);
+            return run;
+        }));
+        runs.push(...settled);
+    }
+    return { waves, runs };
+}
+//# sourceMappingURL=batch.js.map

package/lib/dist/workflows/batch.js.map

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

package/lib/dist/workflows/defaults/claude-design-implement.yaml

@@ -53,7 +53,9 @@ systemPromptAppend: |
 
   The fidelity principle: never paraphrase or summarise design content
   when capturing it. The snapshot HTML and tokens.css are the
-  zero-loss reference layer; the spec captures contract only (behaviour,
+  zero-loss reference layer, and design.md states every value from them
+  verbatim in a fixed layout (written by `specship design extract`, never
+  transcribed by hand); the spec captures contract only (behaviour,
   accessibility, responsive, interaction states, data shape).
 
   There are two import shapes — exactly one source input is non-empty:
@@ -73,6 +75,7 @@ nodes:
     allowed_tools:
       - Read
       - Write
+      - Edit
       - Bash
       - mcp__specship__specship_explore
       - mcp__specship__specship_search
@@ -160,7 +163,29 @@ nodes:
 
       ── BOTH BRANCHES ──
 
-      4. Extract CSS custom properties + literal token-like values
+      4. Write the pixel-exact design reference (DESIGNMD-DOC). The values
+         come from the extractor, never from you:
+
+           specship design extract specs/$INPUT.SLUG/snapshot.html \
+             --out specs/$INPUT.SLUG/design.md --title "$INPUT.FILE_LABEL"
+
+         (If design.md already exists from an earlier import, use
+         `--update specs/$INPUT.SLUG/design.md` instead of `--out`.)
+         If the generated block reports a "Missing linked stylesheet",
+         copy that file next to the snapshot and re-run with `--update`.
+         Then fill design.md's authored sections — Screens & layout,
+         Components & states, Interactions & motion, Responsive behaviour,
+         Assets — following the design-md skill
+         (~/.claude/skills/design-md/SKILL.md and its
+         references/authored-sections.md): every value copied verbatim
+         from the generated block with its selector, every styled state
+         listed, no approximate wording. Run
+
+           specship design check specs/$INPUT.SLUG/design.md
+
+         and fix findings until it passes.
+
+      5. Extract CSS custom properties + literal token-like values
          (colors, spacing, font sizes, radii, transitions) from the
          snapshot to `specs/$INPUT.SLUG/tokens.css`. Use
          `specship_explore` first to find the project's existing token
@@ -175,6 +200,7 @@ nodes:
         - Any visible interaction or state cues in the CSS (`:hover`,
           `:focus`, `:disabled`, `[aria-*]` selectors) the spec
           author should be aware of.
+        - Whether `specship design check` passes on design.md.
         - For Branch A: note that source.md carries the verbatim decision
           record — the draft step should mine it for stated behaviour.
 
@@ -196,6 +222,7 @@ nodes:
         - specs/$INPUT.SLUG/snapshot.html  (visual + structural source)
         - specs/$INPUT.SLUG/tokens.css     (design tokens)
         - specs/$INPUT.SLUG/source.md      (audit record)
+        - specs/$INPUT.SLUG/design.md      (pixel-exact design reference)
 
       Spec scope: $INPUT.FILE_LABEL component(s).
       Optional inputs: owner=$INPUT.OWNER  priority=$INPUT.PRIORITY
@@ -236,6 +263,7 @@ nodes:
       source: specs/<SLUG>/source.md
       snapshot: specs/<SLUG>/snapshot.html
       tokens: specs/<SLUG>/tokens.css
+      design: specs/<SLUG>/design.md
       ---
       ```
 
@@ -257,18 +285,17 @@ nodes:
       $draft_spec.output
     capture_response: true
     on_reject:
+      # The reviewer's rejection reason is appended automatically.
       prompt: |
-        The draft was rejected with this feedback. Revise the spec
+        The draft was rejected (feedback follows). Revise the spec
         per the feedback; keep ALL existing REQ IDs stable so any
         downstream tracking survives the rewrite.
 
-        Feedback:
-        $gap_review.output
-
         Current draft:
         $draft_spec.output
 
         Output the revised draft.
+      revises: draft_spec
       max_attempts: 3
 
   - id: write_spec
@@ -323,14 +350,15 @@ nodes:
         1. The path of the spec file: `specs/$INPUT.SLUG.md`.
         2. The full list of REQ IDs the spec defines, one per line.
         3. The reference files the implementation phase should read:
+             - specs/$INPUT.SLUG/design.md (read first: every value verbatim)
              - specs/$INPUT.SLUG/snapshot.html
              - specs/$INPUT.SLUG/tokens.css
              - specs/$INPUT.SLUG/source.md
         4. The exact next command:
              /specship:spec implement <first REQ ID>
-        5. A one-line reminder that the implementation step should
-           load the snapshot for visual fidelity — the spec covers
-           contract only.
+        5. A one-line reminder that the implementation step builds the UI
+           from design.md (values verbatim) — the spec covers contract
+           only.
 
       Keep the message ≤200 words. The user is about to switch from
       this workflow to the implement workflow; this is the bridge.

package/lib/dist/workflows/defaults/spec-author.yaml

@@ -111,13 +111,15 @@ nodes:
       [the agent fills these in based on the draft above]
     capture_response: true
     on_reject:
+      # The reviewer's rejection reason is appended automatically.
       prompt: |
-        The draft was rejected with this feedback. Revise the draft to
+        The draft was rejected (feedback follows). Revise the draft to
         address it. Keep all existing IDs stable so any pre-existing links
-        survive.
+        survive. Output the full revised draft.
 
-        Feedback:
-        $gap_review.output
+        Current draft:
+        $draft.output
+      revises: draft
       max_attempts: 3
 
   - id: incorporate
@@ -177,15 +179,15 @@ nodes:
       $incorporate.output
     capture_response: true
     on_reject:
+      # The reviewer's rejection reason is appended automatically.
       prompt: |
-        Final approval was rejected. Revise the draft per the feedback,
-        re-run the quality review pass, and produce a new draft.
-
-        Feedback:
-        $finalize.output
+        Final approval was rejected (feedback follows). Revise the draft
+        per the feedback, re-run the quality review pass, and output the
+        full revised draft.
 
         Current draft:
         $incorporate.output
+      revises: incorporate
       max_attempts: 2
 
   - id: write_file