ridgeline 0.6.0 → 0.7.2

package/dist/engine/pipeline/research.exec.js

@@ -37,8 +37,10 @@ exports.invokeResearcher = exports.assembleInputSections = void 0;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const ensemble_exec_1 = require("./ensemble.exec");
+const claude_exec_1 = require("../claude/claude.exec");
 const agent_registry_1 = require("../discovery/agent.registry");
 const flavour_resolve_1 = require("../discovery/flavour.resolve");
+const pipeline_shared_1 = require("./pipeline.shared");
 // ---------------------------------------------------------------------------
 // Shared prompt helpers
 // ---------------------------------------------------------------------------
@@ -60,6 +62,51 @@ const assembleInputSections = (specMd, constraintsMd, tasteMd) => {
 };
 exports.assembleInputSections = assembleInputSections;
 // ---------------------------------------------------------------------------
+// Research agenda
+// ---------------------------------------------------------------------------
+const AGENDA_SYSTEM_PROMPT = `You are a research agenda planner. Given a specification and a domain gap checklist, identify what the spec is missing or vague about, and produce a focused research agenda.
+
+Your output is a markdown research agenda that will be given to research specialists to focus their web searches. Be specific — name the gaps, suggest search terms, and prioritize by impact.
+
+If prior research findings are provided, note which areas are already well-covered and should not be re-researched unless contradictory information is found. Focus the agenda on unexplored territory.
+
+Keep your response concise — under 500 words. No preamble.`;
+const buildAgendaUserPrompt = (specMd, gapsMd, existingResearchMd, changelogMd) => {
+    const sections = [];
+    sections.push("## spec.md\n");
+    sections.push(specMd);
+    sections.push("");
+    if (gapsMd) {
+        sections.push("## Domain Gap Checklist\n");
+        sections.push(gapsMd);
+        sections.push("");
+    }
+    if (existingResearchMd) {
+        sections.push("## Prior Research (already conducted)\n");
+        sections.push(existingResearchMd);
+        sections.push("");
+    }
+    if (changelogMd) {
+        sections.push("## Spec Changelog (recommendations already incorporated)\n");
+        sections.push(changelogMd);
+        sections.push("");
+    }
+    sections.push("Produce a focused research agenda identifying gaps and specific questions for specialists to investigate.");
+    return sections.join("\n");
+};
+const buildResearchAgenda = async (specMd, gapsMd, existingResearchMd, changelogMd, model, timeoutMinutes) => {
+    const result = await (0, claude_exec_1.invokeClaude)({
+        systemPrompt: AGENDA_SYSTEM_PROMPT,
+        userPrompt: buildAgendaUserPrompt(specMd, gapsMd, existingResearchMd, changelogMd),
+        model: "sonnet",
+        allowedTools: [],
+        cwd: process.cwd(),
+        timeoutMs: Math.min(timeoutMinutes * 60 * 1000, 3 * 60 * 1000), // cap at 3 min
+        onStderr: (0, pipeline_shared_1.createStderrHandler)("agenda"),
+    });
+    return result.result ?? "";
+};
+// ---------------------------------------------------------------------------
 // Prompt construction
 // ---------------------------------------------------------------------------
 /** Build a research specialist system prompt from shared context + overlay. */
@@ -67,13 +114,19 @@ const buildResearchSpecialistPrompt = (context, overlay) => {
     return `${context}\n\n${overlay}`;
 };
 /** Assemble the user prompt for a research specialist. */
-const assembleSpecialistUserPrompt = (specMd, constraintsMd, tasteMd) => {
+const assembleSpecialistUserPrompt = (specMd, constraintsMd, tasteMd, agenda) => {
     const sections = (0, exports.assembleInputSections)(specMd, constraintsMd, tasteMd);
+    if (agenda) {
+        sections.push("## Research Agenda\n");
+        sections.push("The following gaps and questions were identified. Focus your research on these areas:\n");
+        sections.push(agenda);
+        sections.push("");
+    }
     sections.push("Research this spec thoroughly using your web tools. Produce a markdown research report as your response.");
     return sections.join("\n");
 };
 /** Assemble the user prompt for the research synthesizer. */
-const assembleSynthesizerUserPrompt = (specMd, buildDir, drafts) => {
+const assembleSynthesizerUserPrompt = (specMd, buildDir, drafts, existingResearchMd, changelogMd, iterationNumber) => {
     const sections = [];
     sections.push("## spec.md\n");
     sections.push(specMd);
@@ -84,14 +137,28 @@ const assembleSynthesizerUserPrompt = (specMd, buildDir, drafts) => {
         sections.push(draft);
         sections.push("\n---\n");
     }
+    if (existingResearchMd) {
+        sections.push("## Existing research.md (to be updated, not replaced)\n");
+        sections.push(existingResearchMd);
+        sections.push("");
+    }
+    if (changelogMd) {
+        sections.push("## spec.changelog.md (recommendations already acted on)\n");
+        sections.push(changelogMd);
+        sections.push("");
+    }
+    sections.push("## Current Iteration\n");
+    sections.push(`Iteration: ${iterationNumber}`);
+    sections.push("");
     sections.push("## Output\n");
-    sections.push(`Write the synthesized research report to: ${buildDir}/research.md`);
+    sections.push(`Write the ${existingResearchMd ? "updated" : "new"} research report to: ${buildDir}/research.md`);
     sections.push("Use the Write tool to create the file.");
     return sections.join("\n");
 };
 const invokeResearcher = async (specMd, constraintsMd, tasteMd, config) => {
     const registry = (0, agent_registry_1.buildAgentRegistry)((0, flavour_resolve_1.resolveFlavour)(config.flavour));
     const context = registry.getContext("researchers") ?? "";
+    const gapsMd = registry.getGaps("researchers");
     const allSpecialists = registry.getSpecialists("researchers");
     // Quick mode: use only the first specialist (ecosystem by default — most broadly useful)
     // Deep mode: use all specialists
@@ -100,16 +167,18 @@ const invokeResearcher = async (specMd, constraintsMd, tasteMd, config) => {
         : allSpecialists.length > 0
             ? [allSpecialists[0]]
             : [];
+    // Build a research agenda before dispatching specialists
+    const agenda = await buildResearchAgenda(specMd, gapsMd, config.existingResearchMd, config.changelogMd, config.model, config.timeoutMinutes);
     return (0, ensemble_exec_1.invokeEnsemble)({
         label: "Researching",
         specialists,
         isStructured: false,
         buildSpecialistPrompt: (overlay) => buildResearchSpecialistPrompt(context, overlay),
-        specialistUserPrompt: assembleSpecialistUserPrompt(specMd, constraintsMd, tasteMd),
+        specialistUserPrompt: assembleSpecialistUserPrompt(specMd, constraintsMd, tasteMd, agenda || null),
         specialistSchema: "", // unused when isStructured is false
         specialistTools: ["WebFetch", "WebSearch", "Bash"],
         synthesizerPrompt: registry.getCorePrompt("researcher.md"),
-        buildSynthesizerUserPrompt: (drafts) => assembleSynthesizerUserPrompt(specMd, config.buildDir, drafts),
+        buildSynthesizerUserPrompt: (drafts) => assembleSynthesizerUserPrompt(specMd, config.buildDir, drafts, config.existingResearchMd, config.changelogMd, config.iterationNumber),
         synthesizerTools: ["Write"],
         model: config.model,
         timeoutMinutes: config.timeoutMinutes,

package/dist/engine/pipeline/research.exec.js.map

@@ -1 +1 @@
-{"version":3,"file":"research.exec.js","sourceRoot":"","sources":["../../../src/engine/pipeline/research.exec.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,4CAA6B;AAC7B,gDAAiC;AAEjC,mDAAgD;AAChD,gEAAgE;AAChE,kEAA6D;AAE7D,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,wFAAwF;AACjF,MAAM,qBAAqB,GAAG,CAAC,MAAc,EAAE,aAAqB,EAAE,OAAsB,EAAY,EAAE;IAC/G,MAAM,QAAQ,GAAa,EAAE,CAAA;IAC7B,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;IAC7B,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACjB,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAA;IACpC,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACjB,IAAI,OAAO,EAAE,CAAC;QACZ,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAA;QAC9B,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACnB,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AAdY,QAAA,qBAAqB,yBAcjC;AAED,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,+EAA+E;AAC/E,MAAM,6BAA6B,GAAG,CAAC,OAAe,EAAE,OAAe,EAAU,EAAE;IACjF,OAAO,GAAG,OAAO,OAAO,OAAO,EAAE,CAAA;AACnC,CAAC,CAAA;AAED,0DAA0D;AAC1D,MAAM,4BAA4B,GAAG,CAAC,MAAc,EAAE,aAAqB,EAAE,OAAsB,EAAU,EAAE;IAC7G,MAAM,QAAQ,GAAG,IAAA,6BAAqB,EAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC,CAAA;IACtE,QAAQ,CAAC,IAAI,CAAC,0GAA0G,CAAC,CAAA;IACzH,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAC5B,CAAC,CAAA;AAED,6DAA6D;AAC7D,MAAM,6BAA6B,GAAG,CACpC,MAAc,EACd,QAAgB,EAChB,MAAgD,EACxC,EAAE;IACV,MAAM,QAAQ,GAAa,EAAE,CAAA;IAE7B,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;IAC7B,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAEjB,QAAQ,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAA;IACjD,KAAK,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,MAAM,EAAE,CAAC;QAC5C,QAAQ,CAAC,IAAI,CAAC,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAA;QACtG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACpB,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IAC1B,CAAC;IAED,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;IAC5B,QAAQ,CAAC,IAAI,CAAC,6CAA6C,QAAQ,cAAc,CAAC,CAAA;IAClF,QAAQ,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAA;IAEvD,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAC5B,CAAC,CAAA;AAiBM,MAAM,gBAAgB,GAAG,KAAK,EACnC,MAAc,EACd,aAAqB,EACrB,OAAsB,EACtB,MAAsB,EACG,EAAE;IAC3B,MAAM,QAAQ,GAAG,IAAA,mCAAkB,EAAC,IAAA,gCAAc,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAA;IACnE,MAAM,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,EAAE,CAAA;IACxD,MAAM,cAAc,GAAG,QAAQ,CAAC,cAAc,CAAC,aAAa,CAAC,CAAA;IAE7D,yFAAyF;IACzF,iCAAiC;IACjC,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM;QAC/B,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;YACzB,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;YACrB,CAAC,CAAC,EAAE,CAAA;IAER,OAAO,IAAA,8BAAc,EAAS;QAC5B,KAAK,EAAE,aAAa;QACpB,WAAW;QACX,YAAY,EAAE,KAAK;QAEnB,qBAAqB,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,6BAA6B,CAAC,OAAO,EAAE,OAAO,CAAC;QACnF,oBAAoB,EAAE,4BAA4B,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,CAAC;QAClF,gBAAgB,EAAE,EAAE,EAAE,oCAAoC;QAC1D,eAAe,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,CAAC;QAElD,iBAAiB,EAAE,QAAQ,CAAC,aAAa,CAAC,eAAe,CAAC;QAC1D,0BAA0B,EAAE,CAAC,MAAM,EAAE,EAAE,CACrC,6BAA6B,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC;QAChE,gBAAgB,EAAE,CAAC,OAAO,CAAC;QAE3B,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,eAAe,EAAE,MAAM,CAAC,eAAe;QAEvC,MAAM,EAAE,GAAG,EAAE;YACX,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC;gBAC9D,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;YAC3D,CAAC;QACH,CAAC;KACF,CAAC,CAAA;AACJ,CAAC,CAAA;AA7CY,QAAA,gBAAgB,oBA6C5B"}
+{"version":3,"file":"research.exec.js","sourceRoot":"","sources":["../../../src/engine/pipeline/research.exec.ts"],"names":[],"mappings":"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"}

package/dist/engine/pipeline/review.exec.js

@@ -43,6 +43,8 @@ const plugin_scan_1 = require("../discovery/plugin.scan");
 const agent_registry_1 = require("../discovery/agent.registry");
 const flavour_resolve_1 = require("../discovery/flavour.resolve");
 const pipeline_shared_1 = require("./pipeline.shared");
+const state_1 = require("../../stores/state");
+const detect_1 = require("../../shapes/detect");
 const assembleUserPrompt = (config, phase, checkpointTag) => {
     const sections = [];
     sections.push("## Phase Spec\n");
@@ -62,6 +64,27 @@ const assembleUserPrompt = (config, phase, checkpointTag) => {
     sections.push("## constraints.md\n");
     sections.push(fs.readFileSync(config.constraintsPath, "utf-8"));
     sections.push("");
+    // Inject design.md
+    (0, pipeline_shared_1.appendDesign)(sections, config);
+    // Inject reviewer context from matched shapes
+    const matchedShapeNames = (0, state_1.getMatchedShapes)(config.buildDir);
+    if (matchedShapeNames.length > 0) {
+        const allDefs = (0, detect_1.loadShapeDefinitions)();
+        const matchedDefs = allDefs.filter((d) => matchedShapeNames.includes(d.name));
+        if (matchedDefs.length > 0) {
+            sections.push("## Visual Design Review Context\n");
+            sections.push("The following visual design heuristics apply to this phase:\n");
+            for (const def of matchedDefs) {
+                sections.push(`### ${def.name}\n`);
+                sections.push(def.reviewerContext);
+                sections.push("");
+            }
+            sections.push("**Review rules for design.md:**");
+            sections.push("- Hard token violations (specific values with imperative language) → severity: blocking");
+            sections.push("- Soft guidance deviations (directional language) → severity: suggestion");
+            sections.push("");
+        }
+    }
     return sections.join("\n");
 };
 const invokeReviewer = async (config, phase, checkpointTag) => {

package/dist/engine/pipeline/review.exec.js.map

@@ -1 +1 @@
-{"version":3,"file":"review.exec.js","sourceRoot":"","sources":["../../../src/engine/pipeline/review.exec.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,4CAA6B;AAE7B,uDAAoD;AACpD,6DAAiE;AACjE,mCAAmC;AACnC,oEAA4D;AAC5D,0DAA4D;AAC5D,gEAAgE;AAChE,kEAA6D;AAC7D,uDAAgF;AAEhF,MAAM,kBAAkB,GAAG,CACzB,MAAuB,EACvB,KAAgB,EAChB,aAAqB,EACb,EAAE;IACV,MAAM,QAAQ,GAAa,EAAE,CAAA;IAE7B,QAAQ,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAA;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAA;IACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAEjB,MAAM,IAAI,GAAG,IAAA,aAAO,EAAC,aAAa,CAAC,CAAA;IACnC,QAAQ,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAA;IACnD,IAAI,IAAI,EAAE,CAAC;QACT,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QACxB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACnB,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACtB,CAAC;SAAM,CAAC;QACN,QAAQ,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAA;IACvC,CAAC;IACD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAEjB,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAA;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAA;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAEjB,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAC5B,CAAC,CAAA;AAEM,MAAM,cAAc,GAAG,KAAK,EACjC,MAAuB,EACvB,KAAgB,EAChB,aAAqB,EACsC,EAAE;IAC7D,MAAM,QAAQ,GAAG,IAAA,mCAAkB,EAAC,IAAA,gCAAc,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAA;IACnE,MAAM,YAAY,GAAG,QAAQ,CAAC,aAAa,CAAC,aAAa,CAAC,CAAA;IAC1D,MAAM,UAAU,GAAG,kBAAkB,CAAC,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,CAAA;IACnE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,IAAA,uCAAsB,EAAC,EAAE,iBAAiB,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IAC3G,MAAM,QAAQ,GAAG,IAAA,yCAAuB,EAAC,MAAM,CAAC,CAAA;IAEhD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAA,0BAAY,EAAC;YAChC,YAAY;YACZ,UAAU;YACV,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC;YACvD,GAAG,IAAA,qCAAmB,EAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC;SACnD,CAAC,CAAA;QAEF,MAAM,OAAO,GAAG,IAAA,+BAAY,EAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC3C,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IAC5B,CAAC;YAAS,CAAC;QACT,KAAK,EAAE,CAAA;QACP,IAAA,+BAAiB,EAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;IACxC,CAAC;AACH,CAAC,CAAA;AA1BY,QAAA,cAAc,kBA0B1B"}
+{"version":3,"file":"review.exec.js","sourceRoot":"","sources":["../../../src/engine/pipeline/review.exec.ts"],"names":[],"mappings":"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"}

package/dist/engine/pipeline/specify.exec.d.ts

@@ -5,5 +5,6 @@ export type SpecEnsembleConfig = {
     maxBudgetUsd: number | null;
     buildDir: string;
     flavour: string | null;
+    matchedShapes: string[];
 };
 export declare const invokeSpecifier: (shapeMd: string, config: SpecEnsembleConfig) => Promise<EnsembleResult>;

package/dist/engine/pipeline/specify.exec.js

@@ -105,6 +105,24 @@ const SPEC_SPECIALIST_SCHEMA = JSON.stringify({
             items: { type: "string" },
             description: "Things the other specialists might miss",
         },
+        design: {
+            type: ["object", "null"],
+            properties: {
+                hardTokens: { type: "array", items: { type: "string" } },
+                softGuidance: { type: "array", items: { type: "string" } },
+                featureVisuals: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            feature: { type: "string" },
+                            criteria: { type: "array", items: { type: "string" } },
+                        },
+                        required: ["feature", "criteria"],
+                    },
+                },
+            },
+        },
     },
     required: ["perspective", "spec", "constraints", "tradeoffs", "concerns"],
 });
@@ -132,9 +150,90 @@ const buildSpecSpecialistPrompt = (overlay) => {
     ].join("\n");
     return `${overlay}${jsonDirective}`;
 };
-/** Assemble the user prompt for a spec specialist — just the shape content. */
-const assembleSpecialistUserPrompt = (shapeMd) => {
-    return `## shape.md\n\n${shapeMd}\n\nIMPORTANT: Respond with ONLY a JSON object. No prose, no markdown, no commentary. Just the JSON.`;
+/** Assemble the user prompt for a spec specialist — shape content plus design context. */
+const assembleSpecialistUserPrompt = (shapeMd, config) => {
+    const sections = [];
+    sections.push(`## shape.md\n\n${shapeMd}`);
+    sections.push("");
+    // Inject design.md for visual specialist context
+    const ridgelineDir = path.join(config.buildDir, "..", "..");
+    const projectDesignPath = path.join(ridgelineDir, "design.md");
+    const featureDesignPath = path.join(config.buildDir, "design.md");
+    if (fs.existsSync(projectDesignPath)) {
+        sections.push("## Project Design\n");
+        sections.push(fs.readFileSync(projectDesignPath, "utf-8"));
+        sections.push("");
+    }
+    if (fs.existsSync(featureDesignPath)) {
+        sections.push("## Feature Design\n");
+        sections.push(fs.readFileSync(featureDesignPath, "utf-8"));
+        sections.push("");
+    }
+    if (config.matchedShapes.length > 0) {
+        sections.push("## Matched Visual Shape Categories\n");
+        sections.push(config.matchedShapes.join(", "));
+        sections.push("");
+    }
+    sections.push("IMPORTANT: Respond with ONLY a JSON object. No prose, no markdown, no commentary. Just the JSON.");
+    return sections.join("\n");
+};
+/** Format a single specialist draft into prompt sections. */
+const formatDraftProposal = (sections, perspective, draft) => {
+    (0, pipeline_shared_1.formatProposalHeading)(sections, perspective, draft.tradeoffs);
+    sections.push(`**Concerns:** ${draft.concerns.join("; ")}\n`);
+    sections.push("**Spec Proposal:**");
+    sections.push(`- Title: ${draft.spec.title}`);
+    sections.push(`- Overview: ${draft.spec.overview}`);
+    sections.push(`- Features (${draft.spec.features.length}):`);
+    for (const feature of draft.spec.features) {
+        sections.push(`  - **${feature.name}**: ${feature.description}`);
+        sections.push(`    Criteria: ${feature.acceptanceCriteria.join("; ")}`);
+    }
+    sections.push(`- In scope: ${draft.spec.scopeBoundaries.inScope.join("; ")}`);
+    sections.push(`- Out of scope: ${draft.spec.scopeBoundaries.outOfScope.join("; ")}`);
+    sections.push("");
+    sections.push("**Constraints Proposal:**");
+    sections.push(`- Language: ${draft.constraints.language}, Runtime: ${draft.constraints.runtime}`);
+    if (draft.constraints.framework)
+        sections.push(`- Framework: ${draft.constraints.framework}`);
+    sections.push(`- Directory: ${draft.constraints.directoryConventions}`);
+    sections.push(`- Naming: ${draft.constraints.namingConventions}`);
+    if (draft.constraints.apiStyle)
+        sections.push(`- API style: ${draft.constraints.apiStyle}`);
+    if (draft.constraints.database)
+        sections.push(`- Database: ${draft.constraints.database}`);
+    sections.push(`- Dependencies: ${draft.constraints.dependencies.join(", ")}`);
+    sections.push(`- Check command: \`${draft.constraints.checkCommand}\``);
+    sections.push("");
+    if (draft.taste) {
+        sections.push("**Taste Proposal:**");
+        if (draft.taste.codeStyle.length > 0)
+            sections.push(`- Code style: ${draft.taste.codeStyle.join("; ")}`);
+        if (draft.taste.testPatterns.length > 0)
+            sections.push(`- Test patterns: ${draft.taste.testPatterns.join("; ")}`);
+        if (draft.taste.commitFormat)
+            sections.push(`- Commit format: ${draft.taste.commitFormat}`);
+        if (draft.taste.commentStyle)
+            sections.push(`- Comment style: ${draft.taste.commentStyle}`);
+        sections.push("");
+    }
+    if (draft.design) {
+        sections.push("**Design Proposal:**");
+        if (draft.design.hardTokens && draft.design.hardTokens.length > 0) {
+            sections.push(`- Hard tokens: ${draft.design.hardTokens.join("; ")}`);
+        }
+        if (draft.design.softGuidance && draft.design.softGuidance.length > 0) {
+            sections.push(`- Soft guidance: ${draft.design.softGuidance.join("; ")}`);
+        }
+        if (draft.design.featureVisuals && draft.design.featureVisuals.length > 0) {
+            sections.push("- Feature visuals:");
+            for (const fv of draft.design.featureVisuals) {
+                sections.push(`  - **${fv.feature}**: ${fv.criteria.join("; ")}`);
+            }
+        }
+        sections.push("");
+    }
+    sections.push("---\n");
 };
 /** Assemble the user prompt for the specifier synthesizer. */
 const assembleSynthesizerUserPrompt = (shapeMd, buildDir, drafts) => {
@@ -144,45 +243,7 @@ const assembleSynthesizerUserPrompt = (shapeMd, buildDir, drafts) => {
     sections.push("");
     sections.push("## Specialist Proposals\n");
     for (const { perspective, draft } of drafts) {
-        (0, pipeline_shared_1.formatProposalHeading)(sections, perspective, draft.tradeoffs);
-        sections.push(`**Concerns:** ${draft.concerns.join("; ")}\n`);
-        sections.push("**Spec Proposal:**");
-        sections.push(`- Title: ${draft.spec.title}`);
-        sections.push(`- Overview: ${draft.spec.overview}`);
-        sections.push(`- Features (${draft.spec.features.length}):`);
-        for (const feature of draft.spec.features) {
-            sections.push(`  - **${feature.name}**: ${feature.description}`);
-            sections.push(`    Criteria: ${feature.acceptanceCriteria.join("; ")}`);
-        }
-        sections.push(`- In scope: ${draft.spec.scopeBoundaries.inScope.join("; ")}`);
-        sections.push(`- Out of scope: ${draft.spec.scopeBoundaries.outOfScope.join("; ")}`);
-        sections.push("");
-        sections.push("**Constraints Proposal:**");
-        sections.push(`- Language: ${draft.constraints.language}, Runtime: ${draft.constraints.runtime}`);
-        if (draft.constraints.framework)
-            sections.push(`- Framework: ${draft.constraints.framework}`);
-        sections.push(`- Directory: ${draft.constraints.directoryConventions}`);
-        sections.push(`- Naming: ${draft.constraints.namingConventions}`);
-        if (draft.constraints.apiStyle)
-            sections.push(`- API style: ${draft.constraints.apiStyle}`);
-        if (draft.constraints.database)
-            sections.push(`- Database: ${draft.constraints.database}`);
-        sections.push(`- Dependencies: ${draft.constraints.dependencies.join(", ")}`);
-        sections.push(`- Check command: \`${draft.constraints.checkCommand}\``);
-        sections.push("");
-        if (draft.taste) {
-            sections.push("**Taste Proposal:**");
-            if (draft.taste.codeStyle.length > 0)
-                sections.push(`- Code style: ${draft.taste.codeStyle.join("; ")}`);
-            if (draft.taste.testPatterns.length > 0)
-                sections.push(`- Test patterns: ${draft.taste.testPatterns.join("; ")}`);
-            if (draft.taste.commitFormat)
-                sections.push(`- Commit format: ${draft.taste.commitFormat}`);
-            if (draft.taste.commentStyle)
-                sections.push(`- Comment style: ${draft.taste.commentStyle}`);
-            sections.push("");
-        }
-        sections.push("---\n");
+        formatDraftProposal(sections, perspective, draft);
     }
     sections.push("## Output Directory\n");
     sections.push(`Write spec.md, constraints.md, and optionally taste.md to: ${buildDir}/`);
@@ -191,11 +252,20 @@ const assembleSynthesizerUserPrompt = (shapeMd, buildDir, drafts) => {
 };
 const invokeSpecifier = async (shapeMd, config) => {
     const registry = (0, agent_registry_1.buildAgentRegistry)((0, flavour_resolve_1.resolveFlavour)(config.flavour));
+    // Get standard specialists
+    let specialists = registry.getSpecialists("specifiers");
+    // Conditionally add visual coherence specialist when visual shapes matched
+    if (config.matchedShapes.length > 0) {
+        const visualSpecialist = registry.getSpecialist("specifiers", "visual-coherence.md");
+        if (visualSpecialist) {
+            specialists = [...specialists, visualSpecialist];
+        }
+    }
     return (0, ensemble_exec_1.invokeEnsemble)({
         label: "Specifying",
-        specialists: registry.getSpecialists("specifiers"),
+        specialists,
         buildSpecialistPrompt: buildSpecSpecialistPrompt,
-        specialistUserPrompt: assembleSpecialistUserPrompt(shapeMd),
+        specialistUserPrompt: assembleSpecialistUserPrompt(shapeMd, config),
         specialistSchema: SPEC_SPECIALIST_SCHEMA,
         synthesizerPrompt: registry.getCorePrompt("specifier.md"),
         buildSynthesizerUserPrompt: (drafts) => assembleSynthesizerUserPrompt(shapeMd, config.buildDir, drafts),

package/dist/engine/pipeline/specify.exec.js.map

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

package/dist/flavours/data-analysis/core/refiner.md

@@ -12,10 +12,36 @@ You are the Spec Refiner for data analysis projects. You receive a spec.md and a
 - **research.md** — research findings with recommendations
 - **constraints.md** — technical constraints (do not modify these)
 - **taste.md** (optional) — style preferences (do not modify these)
+- **spec.changelog.md** (optional) — log of changes you made in prior iterations
 
 ## Your Task
 
-Rewrite spec.md incorporating research findings. Use the Write tool to overwrite the existing spec.md file.
+You have two outputs to write:
+
+### 1. Rewrite spec.md
+
+Incorporate research findings into the spec. Use the Write tool to overwrite the existing spec.md file.
+
+### 2. Write spec.changelog.md
+
+Document what you changed and why. If spec.changelog.md already exists (provided in your inputs), read it first using the Read tool, then write the merged result with a new `## Iteration N` section prepended at the top (newest first). If it doesn't exist, create it fresh.
+
+Structure:
+
+```markdown
+# Spec Changelog
+
+## Iteration N
+
+- [What changed]: [why, citing research source]
+- [What changed]: [why, citing research source]
+- Skipped: [recommendation not incorporated and why]
+
+## Iteration N-1
+(prior entries preserved)
+```
+
+Include a "Skipped" line for any Active Recommendation you deliberately chose not to incorporate, with your reasoning. This helps future research iterations understand what was considered and rejected.
 
 ## Refinement Guidelines
 
@@ -25,6 +51,7 @@ Rewrite spec.md incorporating research findings. Use the Write tool to overwrite
 - **Stay within scope**: Do not expand the spec's scope boundaries. Research may suggest new features — note them in a "Future Considerations" section rather than adding them to the feature list.
 - **Constraints are immutable**: Never modify constraints.md or taste.md. If research suggests a different library or approach, note it as a consideration in the spec, but don't change the constraints.
 - **Flag conflicts**: If research contradicts an existing spec decision, keep the original decision but add a note explaining the alternative and trade-offs.
+- **Don't repeat yourself**: Check spec.changelog.md for changes you already made in prior iterations. Don't re-apply the same change. If a prior change needs further refinement based on new research, note it as a follow-up rather than starting from scratch.
 - **Preserve analytical intent**: Do not change what the analysis is measuring or its statistical methodology unless research shows it is invalid. The user chose their metrics deliberately.
 - **Keep data schemas stable**: If the spec defines expected columns, types, or data shapes, do not alter them. Add validation notes instead.
 - **Note scale implications**: If research reveals performance concerns at the spec's data scale, add a performance note rather than changing the approach.

package/dist/flavours/data-analysis/core/researcher.md

@@ -12,39 +12,56 @@ You receive:
 
 - The current **spec.md** being researched
 - Research reports from each specialist
+- **Existing research.md** (if this is not the first iteration) — your prior work, to be updated rather than replaced
+- **spec.changelog.md** (if it exists) — a log of changes the refiner already made to spec.md based on prior recommendations
+- **Current iteration number**
 
 ## Your Task
 
-Write a unified `research.md` file to the build directory. Use the Write tool.
+### First Iteration (no existing research.md)
 
-## Output Structure
+Write a new `research.md` file to the build directory using the Write tool. Structure it according to the Output Structure below.
+
+### Subsequent Iterations (existing research.md provided)
 
-Structure research.md as follows:
+You are updating your prior research. The existing research.md contains findings from previous iterations that must be preserved.
+
+1. **Review what's already known**: Read the existing research.md findings and the spec.changelog.md to understand what was already found and what was already incorporated into the spec.
+2. **Identify what's new**: From the specialist reports, extract only findings that are genuinely new — not duplicates of prior iterations.
+3. **Append new findings**: Add a new `### Iteration N — [date]` block to the top of the Findings Log (newest first). Only include new findings in this block.
+4. **Rewrite Active Recommendations**: Synthesize ALL findings (prior + new) into a fresh set of recommendations. Remove recommendations that spec.changelog.md shows were already incorporated. Focus on what still needs attention.
+5. **Merge sources**: Add any new URLs/citations to the Sources section.
+6. **Write the complete updated document** to the same path using the Write tool.
+
+## Output Structure
 
 ```markdown
 # Research Findings
 
-> Research conducted on [date] for spec: [spec title]
+> Research for spec: [spec title]
+
+## Active Recommendations
 
-## Key Recommendations
+Bullet list of the most impactful recommendations that have NOT yet been incorporated into the spec. Rewritten each iteration to reflect the full picture. Each recommendation should be one sentence, specific enough to act on.
 
-Bullet list of the 3-5 most impactful recommendations, each in one sentence.
+## Findings Log
 
-## Detailed Findings
+### Iteration N — [date]
 
-### [Topic/Theme 1]
+#### [Topic/Theme]
 
 **Source:** [URL or citation]
 **Perspective:** [which specialist found this]
 **Relevance:** [why this matters to the spec]
 **Recommendation:** [what should change in the spec]
 
-### [Topic/Theme 2]
-...
+### Iteration N-1 — [date]
+
+(prior findings preserved exactly as written)
 
 ## Sources
 
-Numbered list of all URLs and citations referenced above.
+Numbered list of all URLs and citations across all iterations.
 ```
 
 ## Synthesis Guidelines
@@ -55,6 +72,8 @@ Numbered list of all URLs and citations referenced above.
 - **Be concrete**: Every recommendation should be specific enough that someone could act on it without further research.
 - **Preserve sources**: Always include the URL or citation. The user needs to verify your work.
 - **Stay scoped**: Only include findings relevant to the spec. Don't pad with tangentially related material.
+- **Don't re-recommend the incorporated**: If spec.changelog.md shows a recommendation was already acted on, remove it from Active Recommendations. Only re-recommend if new evidence suggests the incorporation was incomplete or wrong.
+- **Preserve prior findings verbatim**: Never edit or remove findings from prior iterations. The Findings Log is append-only.
 - **Prioritize correctness**: For data analysis, statistical validity outranks performance. Flag any spec assumptions that lack statistical grounding.
 - **Surface data shape concerns**: If research reveals that the planned analytical approach may not suit the data's distribution or scale, elevate this to a key recommendation.
 - **Note reproducibility**: Highlight findings that affect whether the analysis can be reliably re-run with updated data.

package/dist/flavours/data-analysis/researchers/gaps.md

@@ -0,0 +1,59 @@
+# Domain Gap Checklist — Data Analysis
+
+Before searching, evaluate the spec against these common gaps. Focus your research on areas where the spec is silent or vague.
+
+## Data Sources
+
+- Ingestion format and schema documented (CSV, JSON, API, DB)?
+- Update frequency and freshness requirements specified?
+- Data volume and growth projections estimated?
+- Source reliability and quality track record assessed?
+
+## Data Quality
+
+- Missing value handling strategy defined?
+- Outlier detection and treatment rules specified?
+- Validation rules and data type constraints documented?
+- Cleaning and transformation steps reproducible?
+
+## Pipeline Architecture
+
+- Batch vs streaming processing decision made?
+- Scheduling and orchestration tool specified?
+- Idempotency guarantees for re-runs?
+- Failure handling and retry logic documented?
+
+## Storage & Format
+
+- File formats chosen for each pipeline stage?
+- Database or warehouse selection justified?
+- Partitioning and indexing strategy for query performance?
+- Retention policy and archival rules defined?
+
+## Visualization
+
+- Chart types and visual encodings appropriate for the data?
+- Interactivity requirements specified (filters, drill-down, tooltips)?
+- Accessibility of visualizations (alt text, colorblind-safe palettes)?
+- Export and sharing formats documented?
+
+## Statistical Methods
+
+- Assumptions stated and validated for chosen methods?
+- Significance levels and confidence intervals specified?
+- Bias sources identified and mitigation planned?
+- Sample size and power analysis performed?
+
+## Reproducibility
+
+- Data and code versioning strategy in place?
+- Environment and dependency management documented?
+- Random seeds set for stochastic processes?
+- Notebook or script execution order clear and linear?
+
+## Privacy & Compliance
+
+- PII identified and handling rules specified?
+- Anonymization or pseudonymization methods chosen?
+- Consent and data usage agreements in place?
+- Regulatory requirements identified (GDPR, HIPAA, CCPA)?