@opengsd/get-shit-done-redux 1.0.0

package/sdk/dist/logger.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Structured JSON logger for GSD debugging.
+ *
+ * Writes structured log entries to stderr (or configurable writable stream).
+ * This is a debugging facility (R019), separate from the event stream.
+ */
+import type { Writable } from 'node:stream';
+import type { PhaseType } from './types.js';
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    phase?: PhaseType;
+    plan?: string;
+    sessionId?: string;
+    message: string;
+    data?: Record<string, unknown>;
+}
+export interface GSDLoggerOptions {
+    /** Minimum log level to output. Default: 'info'. */
+    level?: LogLevel;
+    /** Output stream. Default: process.stderr. */
+    output?: Writable;
+    /** Phase context for all log entries. */
+    phase?: PhaseType;
+    /** Plan name context for all log entries. */
+    plan?: string;
+    /** Session ID context for all log entries. */
+    sessionId?: string;
+}
+export declare class GSDLogger {
+    private readonly minLevel;
+    private readonly output;
+    private phase?;
+    private plan?;
+    private sessionId?;
+    constructor(options?: GSDLoggerOptions);
+    /** Set phase context for subsequent log entries. */
+    setPhase(phase: PhaseType | undefined): void;
+    /** Set plan context for subsequent log entries. */
+    setPlan(plan: string | undefined): void;
+    /** Set session ID context for subsequent log entries. */
+    setSessionId(sessionId: string | undefined): void;
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    private log;
+}
+//# sourceMappingURL=logger.d.ts.map

package/sdk/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAW3D,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAID,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,yCAAyC;IACzC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,KAAK,CAAC,CAAY;IAC1B,OAAO,CAAC,IAAI,CAAC,CAAS;IACtB,OAAO,CAAC,SAAS,CAAC,CAAS;gBAEf,OAAO,GAAE,gBAAqB;IAQ1C,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI;IAI5C,mDAAmD;IACnD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAIvC,yDAAyD;IACzD,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAIjD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D,OAAO,CAAC,GAAG;CAgBZ"}

package/sdk/dist/logger.js

@@ -0,0 +1,70 @@
+/**
+ * Structured JSON logger for GSD debugging.
+ *
+ * Writes structured log entries to stderr (or configurable writable stream).
+ * This is a debugging facility (R019), separate from the event stream.
+ */
+const LOG_LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+// ─── Logger class ────────────────────────────────────────────────────────────
+export class GSDLogger {
+    minLevel;
+    output;
+    phase;
+    plan;
+    sessionId;
+    constructor(options = {}) {
+        this.minLevel = LOG_LEVEL_PRIORITY[options.level ?? 'info'];
+        this.output = options.output ?? process.stderr;
+        this.phase = options.phase;
+        this.plan = options.plan;
+        this.sessionId = options.sessionId;
+    }
+    /** Set phase context for subsequent log entries. */
+    setPhase(phase) {
+        this.phase = phase;
+    }
+    /** Set plan context for subsequent log entries. */
+    setPlan(plan) {
+        this.plan = plan;
+    }
+    /** Set session ID context for subsequent log entries. */
+    setSessionId(sessionId) {
+        this.sessionId = sessionId;
+    }
+    debug(message, data) {
+        this.log('debug', message, data);
+    }
+    info(message, data) {
+        this.log('info', message, data);
+    }
+    warn(message, data) {
+        this.log('warn', message, data);
+    }
+    error(message, data) {
+        this.log('error', message, data);
+    }
+    log(level, message, data) {
+        if (LOG_LEVEL_PRIORITY[level] < this.minLevel)
+            return;
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+        };
+        if (this.phase !== undefined)
+            entry.phase = this.phase;
+        if (this.plan !== undefined)
+            entry.plan = this.plan;
+        if (this.sessionId !== undefined)
+            entry.sessionId = this.sessionId;
+        if (data !== undefined)
+            entry.data = data;
+        this.output.write(JSON.stringify(entry) + '\n');
+    }
+}
+//# sourceMappingURL=logger.js.map

package/sdk/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,MAAM,kBAAkB,GAA6B;IACnD,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AA6BF,gFAAgF;AAEhF,MAAM,OAAO,SAAS;IACH,QAAQ,CAAS;IACjB,MAAM,CAAW;IAC1B,KAAK,CAAa;IAClB,IAAI,CAAU;IACd,SAAS,CAAU;IAE3B,YAAY,UAA4B,EAAE;QACxC,IAAI,CAAC,QAAQ,GAAG,kBAAkB,CAAC,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,CAAC;QAC5D,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;QAC/C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACrC,CAAC;IAED,oDAAoD;IACpD,QAAQ,CAAC,KAA4B;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,mDAAmD;IACnD,OAAO,CAAC,IAAwB;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,yDAAyD;IACzD,YAAY,CAAC,SAA6B;QACxC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAA8B;QACnD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAA8B;QAClD,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAA8B;QAClD,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAA8B;QACnD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IAEO,GAAG,CAAC,KAAe,EAAE,OAAe,EAAE,IAA8B;QAC1E,IAAI,kBAAkB,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,QAAQ;YAAE,OAAO;QAEtD,MAAM,KAAK,GAAa;YACtB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,KAAK;YACL,OAAO;SACR,CAAC;QAEF,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACvD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACpD,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;YAAE,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QACnE,IAAI,IAAI,KAAK,SAAS;YAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;QAE1C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;IAClD,CAAC;CACF"}

package/sdk/dist/model-catalog.d.ts

@@ -0,0 +1,31 @@
+interface RuntimeTierEntry {
+    model: string;
+    reasoning_effort?: string;
+}
+type RuntimeTierTable = Record<string, Record<string, RuntimeTierEntry | null>>;
+interface AgentCatalogEntry {
+    golden: 'opus' | 'sonnet' | 'haiku';
+    balanced: 'opus' | 'sonnet' | 'haiku';
+    budget: 'opus' | 'sonnet' | 'haiku';
+    phaseType: string;
+    routingTier: 'light' | 'standard' | 'heavy';
+}
+interface ModelCatalog {
+    profiles: string[];
+    phaseTypes: string[];
+    adaptiveTierMap: Record<'light' | 'standard' | 'heavy', 'opus' | 'sonnet' | 'haiku'>;
+    runtimeTierDefaults: RuntimeTierTable;
+    agents: Record<string, AgentCatalogEntry>;
+}
+export declare const catalog: ModelCatalog;
+export declare const VALID_PROFILES: string[];
+export declare const SUPPORTED_RUNTIMES: string[];
+export type Runtime = (typeof SUPPORTED_RUNTIMES)[number];
+export declare const MODEL_PROFILES: Record<string, Record<string, string>>;
+export declare const AGENT_TO_PHASE_TYPE: Record<string, string>;
+export declare const AGENT_DEFAULT_TIERS: Record<string, string>;
+export declare function getAgentToModelMapForProfile(normalizedProfile: string): Record<string, string>;
+export declare function resolveRuntimeTierDefault(runtime: string, alias: 'opus' | 'sonnet' | 'haiku'): RuntimeTierEntry | null;
+export declare function runtimesWithReasoningEffort(): Set<string>;
+export {};
+//# sourceMappingURL=model-catalog.d.ts.map

package/sdk/dist/model-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-catalog.d.ts","sourceRoot":"","sources":["../src/model-catalog.ts"],"names":[],"mappings":"AAGA,UAAU,gBAAgB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC,CAAC,CAAC;AAEhF,UAAU,iBAAiB;IACzB,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IACtC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC;CAC7C;AAED,UAAU,YAAY;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC,OAAO,GAAG,UAAU,GAAG,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,CAAC;IACrF,mBAAmB,EAAE,gBAAgB,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC3C;AAGD,eAAO,MAAM,OAAO,EAAE,YAA6E,CAAC;AAEpG,eAAO,MAAM,cAAc,EAAE,MAAM,EAA0B,CAAC;AAC9D,eAAO,MAAM,kBAAkB,UAA2C,CAAC;AAC3E,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOjE,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAEtD,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAEtD,CAAC;AAEF,wBAAgB,4BAA4B,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAO9F;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,gBAAgB,GAAG,IAAI,CAEtH;AAED,wBAAgB,2BAA2B,IAAI,GAAG,CAAC,MAAM,CAAC,CAMzD"}

package/sdk/dist/model-catalog.js

@@ -0,0 +1,31 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const CATALOG_PATH = new URL('../shared/model-catalog.json', import.meta.url);
+export const catalog = JSON.parse(readFileSync(fileURLToPath(CATALOG_PATH), 'utf-8'));
+export const VALID_PROFILES = [...catalog.profiles];
+export const SUPPORTED_RUNTIMES = Object.keys(catalog.runtimeTierDefaults);
+export const MODEL_PROFILES = Object.fromEntries(Object.entries(catalog.agents).map(([agent, meta]) => [agent, {
+        quality: meta.golden,
+        balanced: meta.balanced,
+        budget: meta.budget,
+        adaptive: catalog.adaptiveTierMap[meta.routingTier],
+    }]));
+export const AGENT_TO_PHASE_TYPE = Object.fromEntries(Object.entries(catalog.agents).map(([agent, meta]) => [agent, meta.phaseType]));
+export const AGENT_DEFAULT_TIERS = Object.fromEntries(Object.entries(catalog.agents).map(([agent, meta]) => [agent, meta.routingTier]));
+export function getAgentToModelMapForProfile(normalizedProfile) {
+    const profile = VALID_PROFILES.includes(normalizedProfile) ? normalizedProfile : 'balanced';
+    const out = {};
+    for (const [agent, profiles] of Object.entries(MODEL_PROFILES)) {
+        out[agent] = profile === 'inherit' ? 'inherit' : profiles[profile] ?? profiles.balanced;
+    }
+    return out;
+}
+export function resolveRuntimeTierDefault(runtime, alias) {
+    return catalog.runtimeTierDefaults[runtime]?.[alias] ?? null;
+}
+export function runtimesWithReasoningEffort() {
+    return new Set(Object.entries(catalog.runtimeTierDefaults)
+        .filter(([, tiers]) => Object.values(tiers).some((entry) => entry && entry.reasoning_effort))
+        .map(([runtime]) => runtime));
+}
+//# sourceMappingURL=model-catalog.js.map

package/sdk/dist/model-catalog.js.map

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

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

@@ -0,0 +1,72 @@
+/**
+ * Phase-aware prompt factory — assembles complete prompts for each phase type.
+ *
+ * Reads workflow .md + agent .md files from disk (D006), extracts structured
+ * blocks (<role>, <purpose>, <process>), and composes system prompts with
+ * injected context files per phase type.
+ */
+import type { ContextFiles, ParsedPlan } from './types.js';
+import { PhaseType } from './types.js';
+/**
+ * Maps phase types to their workflow file names.
+ */
+declare const PHASE_WORKFLOW_MAP: Record<PhaseType, string>;
+/**
+ * Extract content from an XML-style block (e.g., <purpose>...</purpose>).
+ * Returns the trimmed inner content, or empty string if not found.
+ */
+export declare function extractBlock(content: string, tagName: string): string;
+/**
+ * Extract all <step> blocks from a workflow's <process> section.
+ * Returns an array of step contents with their name attributes.
+ */
+export declare function extractSteps(processContent: string): Array<{
+    name: string;
+    content: string;
+}>;
+/**
+ * Strip YAML frontmatter (---...---) from an agent definition file,
+ * returning only the markdown/XML content body.
+ */
+export declare function stripYamlFrontmatter(content: string): string;
+export declare class PromptFactory {
+    private readonly workflowsDir;
+    private readonly agentsDir;
+    private readonly projectAgentsDir?;
+    private readonly sdkPromptsDir;
+    private readonly projectDir?;
+    constructor(options?: {
+        gsdInstallDir?: string;
+        agentsDir?: string;
+        projectAgentsDir?: string;
+        sdkPromptsDir?: string;
+        projectDir?: string;
+    });
+    /**
+     * Build a complete prompt for the given phase type.
+     *
+     * For execute phase with a plan, delegates to buildExecutorPrompt().
+     * For other phases, assembles: role + purpose + process steps + context.
+     */
+    buildPrompt(phaseType: PhaseType, plan: ParsedPlan | null, contextFiles: ContextFiles, phaseDir?: string): Promise<string>;
+    /**
+     * Load the workflow file for a phase type.
+     * Tries installed GSD workflows first (the complete, up-to-date versions),
+     * then falls back to SDK bundled copies only if installed not found.
+     * Returns the raw content, or undefined if not found.
+     */
+    loadWorkflowFile(phaseType: PhaseType): Promise<string | undefined>;
+    /**
+     * Load the agent definition for a phase type.
+     * Tries installed agents first (the complete, up-to-date versions),
+     * then SDK bundled copies as last resort.
+     * Returns undefined if no agent is mapped or file not found.
+     */
+    loadAgentDef(phaseType: PhaseType): Promise<string | undefined>;
+    /**
+     * Format context files into a prompt section.
+     */
+    private formatContextFiles;
+}
+export { PHASE_WORKFLOW_MAP };
+//# sourceMappingURL=phase-prompt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"phase-prompt.d.ts","sourceRoot":"","sources":["../src/phase-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAQvC;;GAEG;AACH,QAAA,MAAM,kBAAkB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAOjD,CAAC;AAIF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAIrE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAa7F;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG5D;AAID,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;gBAEzB,OAAO,CAAC,EAAE;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB;IAYD;;;;;OAKG;IACG,WAAW,CACf,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,UAAU,GAAG,IAAI,EACvB,YAAY,EAAE,YAAY,EAC1B,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC;IAwDlB;;;;;OAKG;IACG,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAoBzE;;;;;OAKG;IACG,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IA2BrE;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAyB3B;AAED,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/sdk/dist/phase-prompt.js

@@ -0,0 +1,213 @@
+/**
+ * Phase-aware prompt factory — assembles complete prompts for each phase type.
+ *
+ * Reads workflow .md + agent .md files from disk (D006), extracts structured
+ * blocks (<role>, <purpose>, <process>), and composes system prompts with
+ * injected context files per phase type.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PhaseType } from './types.js';
+import { buildExecutorPrompt } from './prompt-builder.js';
+import { PHASE_AGENT_MAP } from './tool-scoping.js';
+import { sanitizePrompt } from './prompt-sanitizer.js';
+import { resolveLegacyInstallDir } from './sdk-package-compatibility.js';
+// ─── Workflow file mapping ───────────────────────────────────────────────────
+/**
+ * Maps phase types to their workflow file names.
+ */
+const PHASE_WORKFLOW_MAP = {
+    [PhaseType.Execute]: 'execute-plan.md',
+    [PhaseType.Research]: 'research-phase.md',
+    [PhaseType.Plan]: 'plan-phase.md',
+    [PhaseType.Verify]: 'verify-phase.md',
+    [PhaseType.Discuss]: 'discuss-phase.md',
+    [PhaseType.Repair]: 'execute-plan.md',
+};
+// ─── XML block extraction ────────────────────────────────────────────────────
+/**
+ * Extract content from an XML-style block (e.g., <purpose>...</purpose>).
+ * Returns the trimmed inner content, or empty string if not found.
+ */
+export function extractBlock(content, tagName) {
+    const regex = new RegExp(`<${tagName}[^>]*>([\\s\\S]*?)<\\/${tagName}>`, 'i');
+    const match = content.match(regex);
+    return match ? match[1].trim() : '';
+}
+/**
+ * Extract all <step> blocks from a workflow's <process> section.
+ * Returns an array of step contents with their name attributes.
+ */
+export function extractSteps(processContent) {
+    const steps = [];
+    const stepRegex = /<step\s+name="([^"]*)"[^>]*>([\s\S]*?)<\/step>/gi;
+    let match;
+    while ((match = stepRegex.exec(processContent)) !== null) {
+        steps.push({
+            name: match[1],
+            content: match[2].trim(),
+        });
+    }
+    return steps;
+}
+// ─── YAML frontmatter stripping ─────────────────────────────────────────────
+/**
+ * Strip YAML frontmatter (---...---) from an agent definition file,
+ * returning only the markdown/XML content body.
+ */
+export function stripYamlFrontmatter(content) {
+    const match = content.match(/^---\s*\n[\s\S]*?\n---\s*\n?([\s\S]*)$/);
+    return match ? match[1].trim() : content.trim();
+}
+// ─── PromptFactory class ─────────────────────────────────────────────────────
+export class PromptFactory {
+    workflowsDir;
+    agentsDir;
+    projectAgentsDir;
+    sdkPromptsDir;
+    projectDir;
+    constructor(options) {
+        const gsdInstallDir = options?.gsdInstallDir ?? resolveLegacyInstallDir();
+        this.workflowsDir = join(gsdInstallDir, 'workflows');
+        this.agentsDir = options?.agentsDir ?? join(gsdInstallDir, '..', 'agents');
+        this.projectAgentsDir = options?.projectAgentsDir;
+        this.projectDir = options?.projectDir;
+        // SDK prompts dir: explicit override → package-relative default via import.meta.url
+        this.sdkPromptsDir =
+            options?.sdkPromptsDir ??
+                join(fileURLToPath(new URL('.', import.meta.url)), '..', 'prompts');
+    }
+    /**
+     * Build a complete prompt for the given phase type.
+     *
+     * For execute phase with a plan, delegates to buildExecutorPrompt().
+     * For other phases, assembles: role + purpose + process steps + context.
+     */
+    async buildPrompt(phaseType, plan, contextFiles, phaseDir) {
+        // Execute phase with a plan: delegate to existing buildExecutorPrompt
+        if (phaseType === PhaseType.Execute && plan) {
+            const agentDef = await this.loadAgentDef(phaseType);
+            return sanitizePrompt(buildExecutorPrompt(plan, { agentDef, phaseDir }), this.projectDir);
+        }
+        // Prompt assembly order is cache-optimized (#1614):
+        // Stable prefix (deterministic per phase type) → cached by Anthropic at 0.1x cost
+        // Variable suffix (.planning/ files) → uncached, changes per project/run
+        const sections = [];
+        // ── STABLE PREFIX (cacheable across runs for the same phase type) ──
+        // ── Full agent definition ──
+        // Include the complete agent definition (minus YAML frontmatter), not just
+        // the <role> block. The real agents have critical instructions in sections
+        // like <philosophy>, <task_breakdown>, <plan_format>, <execution_flow>,
+        // <scope_estimation>, <context_fidelity>, <checkpoints>, etc.
+        const agentDef = await this.loadAgentDef(phaseType);
+        if (agentDef) {
+            const agentContent = stripYamlFrontmatter(agentDef);
+            if (agentContent) {
+                sections.push(`## Agent Instructions\n\n${agentContent}`);
+            }
+        }
+        // ── Workflow purpose + process ──
+        const workflow = await this.loadWorkflowFile(phaseType);
+        if (workflow) {
+            const purpose = extractBlock(workflow, 'purpose');
+            if (purpose) {
+                sections.push(`## Purpose\n\n${purpose}`);
+            }
+            const process = extractBlock(workflow, 'process');
+            if (process) {
+                const steps = extractSteps(process);
+                if (steps.length > 0) {
+                    const stepBlocks = steps.map((s) => `### ${s.name}\n\n${s.content}`).join('\n\n');
+                    sections.push(`## Process\n\n${stepBlocks}`);
+                }
+            }
+        }
+        // ── VARIABLE SUFFIX (project-specific, changes per run) ──
+        // ── Context files ──
+        const contextSection = this.formatContextFiles(contextFiles);
+        if (contextSection) {
+            sections.push(contextSection);
+        }
+        return sanitizePrompt(sections.join('\n\n'), this.projectDir);
+    }
+    /**
+     * Load the workflow file for a phase type.
+     * Tries installed GSD workflows first (the complete, up-to-date versions),
+     * then falls back to SDK bundled copies only if installed not found.
+     * Returns the raw content, or undefined if not found.
+     */
+    async loadWorkflowFile(phaseType) {
+        const filename = PHASE_WORKFLOW_MAP[phaseType];
+        // Try installed GSD workflows first (complete versions)
+        const paths = [
+            join(this.workflowsDir, filename),
+            join(this.sdkPromptsDir, 'workflows', filename),
+        ];
+        for (const p of paths) {
+            try {
+                return await readFile(p, 'utf-8');
+            }
+            catch {
+                // Not found at this path, try next
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Load the agent definition for a phase type.
+     * Tries installed agents first (the complete, up-to-date versions),
+     * then SDK bundled copies as last resort.
+     * Returns undefined if no agent is mapped or file not found.
+     */
+    async loadAgentDef(phaseType) {
+        const agentFilename = PHASE_AGENT_MAP[phaseType];
+        if (!agentFilename)
+            return undefined;
+        // Priority: installed agents → project-level → SDK bundled (last resort)
+        const paths = [
+            join(this.agentsDir, agentFilename),
+        ];
+        if (this.projectAgentsDir) {
+            paths.push(join(this.projectAgentsDir, agentFilename));
+        }
+        // SDK bundled copies are last resort only
+        paths.push(join(this.sdkPromptsDir, 'agents', agentFilename));
+        for (const p of paths) {
+            try {
+                return await readFile(p, 'utf-8');
+            }
+            catch {
+                // Not found at this path, try next
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Format context files into a prompt section.
+     */
+    formatContextFiles(contextFiles) {
+        const entries = [];
+        const fileLabels = {
+            state: 'Project State (STATE.md)',
+            roadmap: 'Roadmap (ROADMAP.md)',
+            context: 'Context (CONTEXT.md)',
+            research: 'Research (RESEARCH.md)',
+            requirements: 'Requirements (REQUIREMENTS.md)',
+            config: 'Config (config.json)',
+            plan: 'Plan (PLAN.md)',
+            summary: 'Summary (SUMMARY.md)',
+        };
+        for (const [key, label] of Object.entries(fileLabels)) {
+            const content = contextFiles[key];
+            if (content) {
+                entries.push(`### ${label}\n\n${content}`);
+            }
+        }
+        if (entries.length === 0)
+            return null;
+        return `## Context\n\n${entries.join('\n\n')}`;
+    }
+}
+export { PHASE_WORKFLOW_MAP };
+//# sourceMappingURL=phase-prompt.js.map

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

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

package/sdk/dist/phase-runner.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Phase Runner — core state machine driving the full phase lifecycle.
+ *
+ * Orchestrates: discuss → research → plan → execute → verify → advance
+ * with config-driven step skipping, human gate callbacks, event emission,
+ * and structured error handling per step.
+ */
+import type { PhaseRunnerResult, PhaseRunnerOptions } from './types.js';
+import { PhaseStepType } from './types.js';
+import type { GSDConfig } from './config.js';
+import type { GSDTools } from './gsd-tools.js';
+import type { GSDEventStream } from './event-stream.js';
+import type { PromptFactory } from './phase-prompt.js';
+import type { ContextEngine } from './context-engine.js';
+import type { GSDLogger } from './logger.js';
+export declare class PhaseRunnerError extends Error {
+    readonly phaseNumber: string;
+    readonly step: PhaseStepType;
+    readonly cause?: Error | undefined;
+    constructor(message: string, phaseNumber: string, step: PhaseStepType, cause?: Error | undefined);
+}
+export type VerificationOutcome = 'passed' | 'human_needed' | 'gaps_found' | 'architectural_debt' | 'status_unreadable';
+export interface PhaseRunnerDeps {
+    projectDir: string;
+    tools: GSDTools;
+    promptFactory: PromptFactory;
+    contextEngine: ContextEngine;
+    eventStream: GSDEventStream;
+    config: GSDConfig;
+    logger?: GSDLogger;
+}
+export declare class PhaseRunner {
+    private readonly projectDir;
+    private readonly tools;
+    private readonly promptFactory;
+    private readonly contextEngine;
+    private readonly eventStream;
+    private readonly config;
+    private readonly logger?;
+    constructor(deps: PhaseRunnerDeps);
+    /**
+     * Run a full phase lifecycle: discuss → research → plan → plan-check → execute → verify → advance.
+     *
+     * Each step is gated by config flags and phase state. Human gate callbacks
+     * are invoked at decision points; when not provided, auto-approve is used.
+     */
+    run(phaseNumber: string, options?: PhaseRunnerOptions): Promise<PhaseRunnerResult>;
+    /**
+     * Retry a step function once on failure.
+     * On first error/failure, logs a warning and calls the function once more.
+     * Returns the result from the last attempt.
+     */
+    private retryOnce;
+    /**
+     * Run the plan-check step.
+     * Loads the gsd-plan-checker agent definition, runs a Verify-scoped session,
+     * and parses output for PASS/FAIL signals.
+     */
+    private runPlanCheckStep;
+    /**
+     * Run the self-discuss step for auto-mode.
+     * When auto_advance is true and no context exists, run an AI self-discuss
+     * session that identifies gray areas and makes opinionated decisions.
+     */
+    private runSelfDiscussStep;
+    /**
+     * Run a single phase step session (discuss, research, plan).
+     * Emits step start/complete events and captures errors.
+     */
+    private runStep;
+    /**
+     * Run the execute step — uses phase-plan-index for wave-grouped parallel execution.
+     * Plans in the same wave run concurrently via Promise.allSettled().
+     * Waves execute sequentially (wave 1 completes before wave 2 starts).
+     * Respects config.parallelization: false to fall back to sequential execution.
+     * Filters out plans with has_summary: true (already completed).
+     */
+    private runExecuteStep;
+    /**
+     * Execute a single plan by ID within the execute step.
+     * Loads the plan file, parses it, and passes the parsed plan to the prompt
+     * builder so the executor gets the full plan content (tasks, objectives, etc.).
+     */
+    private executeSinglePlan;
+    /**
+     * Run the verify step with full gap closure cycle.
+     * Verification outcome routing:
+     * - passed → proceed to advance
+     * - human_needed → invoke onVerificationReview callback
+     * - gaps_found → plan (create gap plans) → execute (run gap plans) → re-verify
+     * Gap closure retries are capped at configurable maxGapRetries (default 1).
+     */
+    private runVerifyStep;
+    /**
+     * Run the advance step — mark phase complete.
+     * Gated by config.workflow.auto_advance or callback approval.
+     */
+    private runAdvanceStep;
+    /**
+     * Map PhaseStepType to PhaseType for prompt/context resolution.
+     */
+    private stepToPhaseType;
+    /**
+     * Parse the verification outcome by checking VERIFICATION.md on disk.
+     * The verify session may succeed (no runtime errors) while writing
+     * status: gaps_found to VERIFICATION.md — we need to check the file,
+     * not just the session exit code.
+     *
+     * Falls back to session result if VERIFICATION.md can't be parsed.
+     */
+    private parseVerificationOutcome;
+    private verificationErrorForOutcome;
+    /**
+     * Block phase completion when source files changed by this phase still contain
+     * unresolved TBD/FIXME/XXX comments. Markers are allowed only when the same
+     * line references tracked follow-up work (issue/PR number or DEF-* id).
+     *
+     * The debt scan is intentionally scoped to literal source paths declared in
+     * phase plan frontmatter `files_modified` and task `files`. Glob patterns are
+     * not expanded, and files modified during execution but omitted from the plan
+     * are not scanned; git-diff-based coverage would be a separate enhancement.
+     */
+    private checkArchitecturalDebt;
+    private listPhasePlanPaths;
+    private extractPlanFiles;
+    private shouldScanForArchitecturalDebt;
+    private findUnresolvedDebtMarkers;
+    private hasFormalDebtReference;
+    private resolveProjectPath;
+    private realpathForBoundary;
+    /**
+     * Check RESEARCH.md for unresolved open questions (#1602).
+     * Returns the gate result — pass means safe to proceed to planning.
+     */
+    private checkResearchGate;
+    /**
+     * Invoke the onBlockerDecision callback, falling back to auto-approve.
+     */
+    private invokeBlockerCallback;
+    /**
+     * Invoke the onVerificationReview callback, falling back to auto-accept.
+     */
+    private invokeVerificationCallback;
+}
+//# sourceMappingURL=phase-runner.d.ts.map