@lchase/kiln 0.1.0 → 0.3.0

package/dist/config.js

@@ -1,12 +1,11 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { KilnConfigError } from "./errors.js";
 import { KilnConfigFileSchema } from "./schemas.js";
 const CONFIG_NAME = "kiln.config.json";
 const REPO_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 export function loadKilnConfig(configPath, options = {}) {
-    const cwd = options.cwd ?? process.cwd();
     const home = options.home ?? homedir();
     const resolvedPath = resolve(configPath);
     let raw;
@@ -36,7 +35,7 @@ export function loadKilnConfig(configPath, options = {}) {
             ...(entry.base ? { base: entry.base } : {}),
         };
     }
-    const kilnDir = basename(configDir) === ".kiln" ? configDir : join(cwd, ".kiln");
+    const kilnDir = configDir;
     const jira = jiraFromFile(parsed.data.jira);
     return {
         configPath: resolvedPath,
@@ -51,7 +50,8 @@ export function loadKilnConfig(configPath, options = {}) {
     };
 }
 /**
- * Local config wins: `./.kiln/kiln.config.json`, then `~/.kiln/kiln.config.json`.
+ * One kiln home: `--config <file>` if given, else `$KILN_HOME/kiln.config.json`
+ * when `KILN_HOME` is set, else `~/.kiln/kiln.config.json`.
  */
 export function resolveKilnConfig(options = {}) {
     const cwd = options.cwd ?? process.cwd();
@@ -59,18 +59,17 @@ export function resolveKilnConfig(options = {}) {
     if (options.configPath) {
         return loadKilnConfig(resolve(cwd, options.configPath), { cwd, home });
     }
-    const cwdConfig = join(cwd, ".kiln", CONFIG_NAME);
-    if (existsSync(cwdConfig))
-        return loadKilnConfig(cwdConfig, { cwd, home });
-    const homeConfig = join(home, ".kiln", CONFIG_NAME);
-    if (existsSync(homeConfig))
-        return loadKilnConfig(homeConfig, { cwd, home });
-    throw new KilnConfigError([
-        "No kiln config found.",
-        `Run kiln repo add <name> <path> to create ${join(cwd, ".kiln", CONFIG_NAME)},`,
-        `or create ${join(home, ".kiln", CONFIG_NAME)}.`,
-        "Those directories are gitignored. Do not commit checkout paths.",
-    ].join("\n"));
+    const configPath = defaultConfigPath(options);
+    assertNoStaleCwdConfig(cwd, configPath);
+    if (!existsSync(configPath)) {
+        throw new KilnConfigError([
+            "No kiln config found.",
+            `Run kiln repo add <name> <path> from any directory to create ${configPath}.`,
+            "Set KILN_HOME or pass --config <file> to use a different kiln home.",
+            "Do not commit checkout paths.",
+        ].join("\n"));
+    }
+    return loadKilnConfig(configPath, { cwd, home });
 }
 const BRANCH_NAME = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
 /** Create or update one repo entry. Returns the text to print. */
@@ -85,7 +84,7 @@ export function addRepo(options) {
         assertBranchName(options.base);
     const configPath = configPathForWrite(options);
     const configDir = dirname(configPath);
-    const storedPath = pathToStore(options.repoPath, configDir, cwd, home);
+    const storedPath = pathToStore(options.repoPath, cwd, home);
     const checkout = resolveConfiguredPath(configDir, storedPath, home);
     if (!existsSync(checkout) || !statSync(checkout).isDirectory()) {
         throw new KilnConfigError(`Checkout for ${options.name} does not exist or is not a directory: ${checkout}.`);
@@ -151,18 +150,39 @@ export function assertRepoName(name) {
         throw new KilnConfigError(`Repo name ${JSON.stringify(name)} must start with a letter or digit and contain only letters, digits, dots, underscores, and hyphens.`);
     }
 }
-function configPathForWrite(options) {
+function defaultConfigPath(options) {
+    return join(kilnHomeDirectory(options), CONFIG_NAME);
+}
+/** `$KILN_HOME` when set, otherwise `~/.kiln`. A relative `KILN_HOME` resolves from `cwd`. */
+function kilnHomeDirectory(options) {
     const cwd = options.cwd ?? process.cwd();
+    const fromEnv = process.env.KILN_HOME;
+    if (typeof fromEnv === "string" && fromEnv.trim().length > 0)
+        return resolve(cwd, fromEnv);
     const home = options.home ?? homedir();
+    return join(home, ".kiln");
+}
+function configPathForWrite(options) {
+    const cwd = options.cwd ?? process.cwd();
     if (options.configPath)
         return resolve(cwd, options.configPath);
+    const configPath = defaultConfigPath(options);
+    assertNoStaleCwdConfig(cwd, configPath);
+    return configPath;
+}
+/**
+ * A leftover `./.kiln/kiln.config.json` used to be a second kiln home.
+ * Fail instead of ignoring it when the machine home has no config yet.
+ */
+function assertNoStaleCwdConfig(cwd, homeConfig) {
     const cwdConfig = join(cwd, ".kiln", CONFIG_NAME);
-    if (existsSync(cwdConfig))
-        return cwdConfig;
-    const homeConfig = join(home, ".kiln", CONFIG_NAME);
+    if (!existsSync(cwdConfig))
+        return;
+    if (resolve(cwdConfig) === resolve(homeConfig))
+        return;
     if (existsSync(homeConfig))
-        return homeConfig;
-    return cwdConfig;
+        return;
+    throw new KilnConfigError(`Found ${cwdConfig} but no home config at ${homeConfig}. mv ./.kiln ~/.kiln or pass --config / set KILN_HOME.`);
 }
 function readConfigObject(configPath) {
     if (!existsSync(configPath))
@@ -205,14 +225,12 @@ export function resolveConfiguredPath(configDir, value, home) {
     const expanded = expandHome(value, home);
     return isAbsolute(expanded) ? expanded : resolve(configDir, expanded);
 }
-function pathToStore(userPath, configDir, cwd, home) {
+function pathToStore(userPath, cwd, home) {
     if (userPath === "~" || userPath.startsWith("~/"))
         return userPath;
     if (isAbsolute(userPath))
         return userPath;
-    const absolute = resolve(cwd, userPath);
-    const stored = relative(configDir, absolute);
-    return stored === "" ? "." : stored;
+    return resolve(cwd, userPath);
 }
 function jiraFromFile(jira) {
     if (!jira)

package/dist/driver.js

@@ -3,13 +3,14 @@ import { randomUUID } from "node:crypto";
 import { closeSync, existsSync, linkSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { basename, dirname, isAbsolute, join } from "node:path";
 import { clearLaunchError, deliverJob, readDelivery, readLaunchError, resolveLaunchBase, writeDelivery, writeLaunchError, isMerged, } from "./delivery.js";
+import { appendInvestigationFindings, existingFindingsPath, findingsFilePath, INVESTIGATION_WORKFLOW, readFindingsMarkdown, writeFindings, } from "./findings.js";
 import { defaultHost } from "./host.js";
-import { readJobSpec } from "./jobs.js";
+import { readJobSpec, resolveJobSpec } from "./jobs.js";
 import { jobBasename, packageRoot } from "./paths.js";
-import { decide, jobState, } from "./reconcile.js";
-import { gateAnswerCommand, renderStatus, renderTick, yakCliPath, } from "./report.js";
+import { decide, isLanded, jobState, } from "./reconcile.js";
+import { gateAnswerCommand, renderStatus, renderTick, statusView, yakCliPath, } from "./report.js";
 import { JobSchema } from "./schemas.js";
-import { materializeWorkflow, workflowInputs } from "./workflow.js";
+import { materializeWorkflow, workflowInputs, workflowNeedsTestCommand } from "./workflow.js";
 const TAG_PREFIX = "kiln:";
 export function jobTag(jobId) {
     return `${TAG_PREFIX}${jobId}`;
@@ -22,8 +23,12 @@ export function parseJobTag(tag) {
         return undefined;
     return id;
 }
+/** The derived view `kiln status` prints and `kiln serve` renders. */
+export function readStatus(config, jobId, host = defaultHost()) {
+    return statusView(observe(config, host).observation, jobId);
+}
 export function runStatus(config, jobId, host = defaultHost()) {
-    return renderStatus(observe(config, host).observation, jobId);
+    return renderStatus(readStatus(config, jobId, host));
 }
 export function runTick(config, host = defaultHost()) {
     return withTickLock(config.kilnDir, () => {
@@ -55,6 +60,9 @@ export function answerJob(config, jobId, choice, host = defaultHost()) {
     if (result.status !== 0) {
         throw new Error(output.trim() || `Could not ${choice} job ${jobId}.`);
     }
+    if (choice === "approve") {
+        recordInvestigationFindings(config, observe(config, host), jobId);
+    }
     return output.endsWith("\n") || output.length === 0 ? output : `${output}\n`;
 }
 function gateForChoice(gates, choice) {
@@ -94,6 +102,11 @@ function observe(config, host) {
         const stackError = entry.job?.stack && (entry.job.dependsOn?.length ?? 0) !== 1
             ? "stack needs exactly one dependency."
             : undefined;
+        const logPath = crumb?.logPath || existingLog(config.kilnDir, entry.meta.jobId);
+        const specPath = entry.job ? resolveJobSpec(config.kilnDir, entry.job.spec) : undefined;
+        const findingsPath = entry.job?.workflow === INVESTIGATION_WORKFLOW
+            ? existingFindingsPath(config.kilnDir, entry.job.id)
+            : undefined;
         jobs.push({
             jobId: entry.meta.jobId,
             repo: entry.job?.repo ?? "",
@@ -101,13 +114,15 @@ function observe(config, host) {
             title: entry.job?.title ?? "",
             dependsOn: entry.job?.dependsOn ?? [],
             ...(entry.job?.source ? { source: entry.job.source } : {}),
+            ...(specPath ? { specPath } : {}),
             deliver,
             ...(entry.job?.stack ? { stack: true } : {}),
             ...(delivery ? { delivery } : {}),
+            ...(findingsPath ? { findingsPath } : {}),
             launching: Boolean(crumb) && !run && childAlive,
             launchFailed: Boolean(crumb) && !run && !childAlive,
             ...(launchError ? { launchError } : {}),
-            ...(crumb?.logPath ? { logPath: crumb.logPath } : {}),
+            ...(logPath ? { logPath } : {}),
             ...(run ? { run } : {}),
             ...(entry.meta.error || repoError || stackError
                 ? { error: entry.meta.error ?? repoError ?? stackError }
@@ -126,6 +141,7 @@ function observe(config, host) {
 function apply(config, world, actions, host) {
     const launches = [];
     const delivers = [];
+    const findings = [];
     for (const action of actions) {
         if (action.type === "clear-breadcrumb") {
             rmSync(action.path, { force: true });
@@ -135,13 +151,38 @@ function apply(config, world, actions, host) {
             delivers.push(deliverObserved(config, world, action.jobId, host));
             continue;
         }
+        if (action.type === "record-findings") {
+            const recorded = recordInvestigationFindings(config, world, action.jobId);
+            if (recorded.status !== "skip")
+                findings.push(recorded);
+            continue;
+        }
         const job = world.jobs.get(action.jobId);
         if (!job) {
             throw new Error(`Tick planned a launch for ${action.jobId}, which is not in the observed jobs.`);
         }
         launches.push(launchJob(config, world, job, host));
     }
-    return renderTick(world.observation, actions, launches, delivers);
+    return renderTick(world.observation, actions, launches, delivers, findings);
+}
+/**
+ * Copy an approved investigation's markdown into `<kilnDir>/findings`.
+ * A file that is already present is left as it is. A missing or incomplete
+ * artifact is reported and does not fail the tick.
+ */
+function recordInvestigationFindings(config, world, jobId) {
+    const job = world.jobs.get(jobId);
+    const observed = world.observation.jobs.find((candidate) => candidate.jobId === jobId);
+    if (!job || job.workflow !== INVESTIGATION_WORKFLOW || !observed?.run || !isLanded(observed)) {
+        return { status: "skip", jobId };
+    }
+    if (observed.findingsPath)
+        return { status: "skip", jobId };
+    const markdown = readFindingsMarkdown(observed.run.checkout, observed.run.runId);
+    if (!markdown)
+        return { status: "missing", jobId };
+    const path = writeFindings(config.kilnDir, job.id, markdown);
+    return { status: "wrote", jobId, path };
 }
 function deliverObserved(config, world, jobId, host) {
     const job = world.jobs.get(jobId);
@@ -190,6 +231,33 @@ function pullRequestBase(world, job, repo, host) {
     host.git.fetch(repo.path);
     return host.git.defaultBranch(repo.path);
 }
+function assertStackTarget(world, job) {
+    if (!job.stack)
+        return;
+    const upstreamId = job.dependsOn?.[0];
+    if (!upstreamId)
+        return;
+    const upstream = world.jobs.get(upstreamId);
+    if (upstream?.workflow !== INVESTIGATION_WORKFLOW)
+        return;
+    throw new Error(`stack cannot target investigation job ${upstream.id}. An investigation does not land a branch.`);
+}
+/** Spec text for this launch. Investigation dependencies append their findings. */
+function specHandedToYak(config, world, job) {
+    const base = readJobSpec(config.kilnDir, job);
+    const sections = [];
+    for (const depId of job.dependsOn ?? []) {
+        const dep = world.jobs.get(depId);
+        if (!dep || dep.workflow !== INVESTIGATION_WORKFLOW)
+            continue;
+        const path = findingsFilePath(config.kilnDir, dep.id);
+        if (!existsSync(path)) {
+            throw new Error(`Job ${job.id} depends on investigation ${dep.id} (${dep.title}), which has no findings file at ${path}.`);
+        }
+        sections.push({ title: dep.title, markdown: readFileSync(path, "utf8") });
+    }
+    return appendInvestigationFindings(base, sections);
+}
 function upstreamBranch(world, job) {
     const upstreamId = job.dependsOn?.[0];
     if (!upstreamId)
@@ -233,8 +301,9 @@ function launchJob(config, world, job, host) {
     if (!repo) {
         throw new Error(`Repo ${job.repo} is not registered. Run kiln repo add ${job.repo} <path>.`);
     }
+    const sourceWorkflow = readFileSync(join(packageRoot(), "workflows", `${job.workflow}.yaml`), "utf8");
     const testCommand = repo.test;
-    if (!testCommand?.trim()) {
+    if (workflowNeedsTestCommand(sourceWorkflow) && !testCommand?.trim()) {
         throw new Error(`Repo ${job.repo} has no test command. Set repos.${job.repo}.test. The feature workflow refuses to run an empty KILN_TEST.`);
     }
     const workflow = materializeWorkflow(config.kilnDir, job.id, job.workflow);
@@ -243,8 +312,10 @@ function launchJob(config, world, job, host) {
     const crumbPath = breadcrumbPath(config.kilnDir, job.id);
     ensureCheckoutExcludes(repo.path);
     let baseSha;
+    let specText;
     try {
         clearLaunchError(config.kilnDir, job.id);
+        assertStackTarget(world, job);
         baseSha = resolveLaunchBase({
             checkout: repo.path,
             deliver: repo.deliver,
@@ -253,6 +324,7 @@ function launchJob(config, world, job, host) {
             ...(job.stack ? { upstreamBranch: upstreamBranch(world, job) } : {}),
             git: host.git,
         });
+        specText = specHandedToYak(config, world, job);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -260,8 +332,6 @@ function launchJob(config, world, job, host) {
         writeFileSync(logPath, `${message}\n`);
         return { jobId: job.id, repo: job.repo, output: message };
     }
-    const specText = readJobSpec(config.kilnDir, job);
-    const sourceWorkflow = readFileSync(join(packageRoot(), "workflows", `${job.workflow}.yaml`), "utf8");
     const input = workflowInputs(sourceWorkflow, {
         title: job.title,
         specText,
@@ -467,20 +537,141 @@ function openGates(runDir, events) {
     return gates;
 }
 function readGate(runDir, stepId) {
+    const reviews = readReviewArtifacts(runDir);
     const file = join(runDir, "pending", `${stepId}.request.json`);
-    if (!existsSync(file))
-        return { stepId, prompt: "(request file missing)" };
+    if (!existsSync(file)) {
+        return { stepId, prompt: "(request file missing)", ...(reviews.length > 0 ? { reviews } : {}) };
+    }
     const request = JSON.parse(readFileSync(file, "utf8"));
     const prompt = request.kind === "loop-exhausted"
         ? `loop exhausted (${request.tripped ?? "budget"} at iteration ${request.iteration ?? "?"})`
         : (request.rendered ?? stepId).split("\n")[0] ?? stepId;
     const shape = answerShape(request.answerSchema);
+    const rendered = typeof request.rendered === "string" ? clipText(request.rendered, 2000) : undefined;
+    const artifacts = readNamedArtifacts(runDir, artifactNames(request.context?.artifacts));
     return {
         stepId,
         prompt,
+        ...(rendered ? { rendered } : {}),
         ...(shape ? { answerField: shape.field, choices: shape.choices } : {}),
+        ...(artifacts.length > 0 ? { artifacts } : {}),
+        ...(reviews.length > 0 ? { reviews } : {}),
     };
 }
+const REVIEW_STEPS = ["security", "ux", "ui", "code"];
+const ARTIFACT_NAME = /^[A-Za-z0-9._-]+$/;
+const SECRET_KEY = /api[_-]?token|password|secret|authorization|credential/i;
+/** The launch log stays after the breadcrumb is cleared. Status prints it only for a failed launch. */
+function existingLog(kilnDir, jobId) {
+    let name;
+    try {
+        name = jobBasename(jobId);
+    }
+    catch {
+        return undefined;
+    }
+    const path = join(kilnDir, "logs", `${name}.log`);
+    return existsSync(path) ? path : undefined;
+}
+function artifactNames(value) {
+    if (!Array.isArray(value))
+        return [];
+    const names = [];
+    for (const entry of value) {
+        if (typeof entry !== "string" || !ARTIFACT_NAME.test(entry) || names.includes(entry))
+            continue;
+        names.push(entry);
+    }
+    return names;
+}
+function readNamedArtifacts(runDir, names) {
+    const found = [];
+    for (const name of names) {
+        const file = join(runDir, "artifacts", `${name}.json`);
+        if (!existsSync(file))
+            continue;
+        found.push(readArtifactSummary(file, name));
+    }
+    return found;
+}
+function readReviewArtifacts(runDir) {
+    const dir = join(runDir, "artifacts");
+    if (!existsSync(dir))
+        return [];
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const best = new Map();
+    for (const file of files) {
+        const match = /^(security|ux|ui|code)(?:\.(\d+))?\.json$/.exec(file);
+        if (!match?.[1])
+            continue;
+        const iter = match[2] ? Number(match[2]) : 0;
+        const previous = best.get(match[1]);
+        if (!previous || iter >= previous.iter)
+            best.set(match[1], { iter, file });
+    }
+    const found = [];
+    for (const step of REVIEW_STEPS) {
+        const picked = best.get(step);
+        if (!picked)
+            continue;
+        found.push(readArtifactSummary(join(dir, picked.file), step));
+    }
+    return found;
+}
+function readArtifactSummary(file, name) {
+    if (!existsSync(file))
+        return { name, summary: "(missing artifact)" };
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return { name, summary: summarizeArtifact(name, parsed) };
+    }
+    catch {
+        return { name, summary: "(unreadable artifact)" };
+    }
+}
+function summarizeArtifact(name, value) {
+    const clean = redactSecrets(value);
+    if (name === "input" && isRecord(clean)) {
+        const title = clean.title;
+        return typeof title === "string" && title.trim() ? `title: ${clipText(title, 120)}` : "(no title)";
+    }
+    if (isRecord(clean)) {
+        const head = typeof clean.decision === "string" ? clean.decision : typeof clean.verdict === "string" ? clean.verdict : undefined;
+        const detail = typeof clean.reason === "string" ? clean.reason : typeof clean.findings === "string" ? clean.findings : undefined;
+        if (head)
+            return clipText(detail ? `${head} — ${detail}` : head, 280);
+    }
+    try {
+        return clipText(JSON.stringify(clean), 280);
+    }
+    catch {
+        return "(unreadable artifact)";
+    }
+}
+function redactSecrets(value) {
+    if (Array.isArray(value))
+        return value.map(redactSecrets);
+    if (!isRecord(value))
+        return value;
+    const out = {};
+    for (const [key, inner] of Object.entries(value)) {
+        out[key] = SECRET_KEY.test(key) ? "[redacted]" : redactSecrets(inner);
+    }
+    return out;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function clipText(text, max) {
+    const trimmed = text.trim();
+    return trimmed.length <= max ? trimmed : `${trimmed.slice(0, max - 1)}...`;
+}
 function answerShape(schema) {
     if (typeof schema !== "object" || schema === null || !("properties" in schema))
         return undefined;

package/dist/findings.js

@@ -0,0 +1,79 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { jobBasename } from "./paths.js";
+/**
+ * Workflow name for a spike, probe, or research job.
+ * An approved investigation is `done` with no pull request and no land.
+ */
+export const INVESTIGATION_WORKFLOW = "investigation";
+/**
+ * Headings the findings markdown must contain. The investigation prompt
+ * asks for these spellings. Kiln stores the agent's markdown only when
+ * every one of them is present.
+ */
+export const FINDINGS_HEADINGS = [
+    "## Questions",
+    "## Answers",
+    "## Unconfirmed",
+    "## Implications for dependent tickets",
+];
+/** `<kilnDir>/findings/<jobId>.md`. The job file does not store this path. */
+export function findingsFilePath(kilnDir, jobId) {
+    return join(kilnDir, "findings", `${jobBasename(jobId)}.md`);
+}
+/** Absolute path when the findings file is already on disk. */
+export function existingFindingsPath(kilnDir, jobId) {
+    const path = findingsFilePath(kilnDir, jobId);
+    return existsSync(path) ? path : undefined;
+}
+export function findingsMarkdownComplete(markdown) {
+    return FINDINGS_HEADINGS.every((heading) => markdown.includes(heading));
+}
+/**
+ * Store the approved findings document. Writing the same text again does
+ * not touch the file. A document missing a required heading is refused.
+ */
+export function writeFindings(kilnDir, jobId, markdown) {
+    if (!findingsMarkdownComplete(markdown)) {
+        throw new Error(`Findings for ${jobId} are missing a required section. Expected ${FINDINGS_HEADINGS.join(", ")}.`);
+    }
+    const path = findingsFilePath(kilnDir, jobId);
+    mkdirSync(dirname(path), { recursive: true });
+    const body = markdown.endsWith("\n") ? markdown : `${markdown}\n`;
+    if (existsSync(path) && readFileSync(path, "utf8") === body)
+        return path;
+    writeFileSync(path, body);
+    return path;
+}
+/** The explore step's `findings` artifact, when it is a complete markdown document. */
+export function readFindingsMarkdown(checkout, runId) {
+    const path = join(checkout, ".runs", runId, "artifacts", "findings.json");
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed !== "object" || parsed === null || !("markdown" in parsed))
+            return undefined;
+        const markdown = parsed.markdown;
+        if (typeof markdown !== "string")
+            return undefined;
+        const text = markdown.trim();
+        if (!text || !findingsMarkdownComplete(text))
+            return undefined;
+        return text;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Spec text handed to yak. Investigation dependencies contribute a
+ * `## Findings from <title>` section. The stored spec file is not modified.
+ */
+export function appendInvestigationFindings(specText, sections) {
+    if (sections.length === 0)
+        return specText;
+    const base = specText.endsWith("\n") ? specText : `${specText}\n`;
+    const blocks = sections.map((section) => `## Findings from ${section.title}\n\n${section.markdown.trim()}\n`);
+    return `${base}\n${blocks.join("\n")}`;
+}

package/dist/intake/jira.js

@@ -1,5 +1,6 @@
 import { assertCanStack, listValidJobs, renderAddedJob, writeJob } from "../jobs.js";
 import { assertWorkflowName } from "../workflow.js";
+import { INVESTIGATION_WORKFLOW } from "../findings.js";
 import { typeLooksLikeSpike, workflowForSpike } from "./tickets.js";
 /** Jira issue keys, stored and matched in uppercase (`PROJ-123`). */
 const ISSUE_KEY = /^[A-Z][A-Z0-9]+-\d+$/;
@@ -29,7 +30,9 @@ export async function addFromJira(config, input) {
     }
     const issue = parseIssue(key, parseJson(issueResponse.body, key), acceptanceField);
     const warnings = [];
-    const workflow = workflowForSpike(key, typeLooksLikeSpike(issue.issueType), input.workflow, warnings);
+    const workflow = workflowForSpike(typeLooksLikeSpike(issue.issueType), input.workflow);
+    if (workflow === INVESTIGATION_WORKFLOW)
+        assertWorkflowName(workflow);
     const dependsOn = mergeDepends(dependencyIds(config, issue.blockedBy, warnings), input.dependsOn);
     assertDependsExist(config, dependsOn);
     const specText = jiraIssueSpec({

package/dist/intake/tickets.js

@@ -1,8 +1,8 @@
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
+import { INVESTIGATION_WORKFLOW } from "../findings.js";
 import { listValidJobs, newJobId, writeJob } from "../jobs.js";
 import { assertWorkflowName } from "../workflow.js";
-import { packageRoot } from "../paths.js";
 /** Context files larger than this are named in the spec instead of copied in. */
 export const CONTEXT_INLINE_LIMIT = 40 * 1024;
 const TICKET_FILE = /^(\d+)-.+\.md$/;
@@ -21,21 +21,30 @@ export function importTickets(config, input) {
     assertWorkflowName(requested);
     const context = resolveContext(dirAbs, input.contextPath, input.cwd);
     const tickets = readTickets(dirAbs);
-    if (input.stack) {
-        const offender = tickets.find((ticket) => ticket.blockedBy.length > 1) ??
-            tickets.find((ticket) => ticket.blockedBy.length !== 1);
-        if (offender) {
-            throw new Error(`Ticket ${offender.file} has ${offender.blockedBy.length} dependencies. stack needs exactly one.`);
-        }
-    }
     const warnings = [];
     const workflows = new Map();
     for (const ticket of tickets) {
-        const workflow = workflowFor(ticket, requested, warnings);
+        const workflow = workflowFor(ticket, requested);
         if (workflow !== requested)
             assertWorkflowName(workflow);
         workflows.set(ticket.path, workflow);
     }
+    if (input.stack) {
+        const offender = tickets.find((ticket) => ticket.blockedBy.length > 1) ??
+            tickets.find((ticket) => ticket.blockedBy.length !== 1);
+        if (offender) {
+            throw new Error(`Ticket ${offender.file} has ${offender.blockedBy.length} dependencies. stack needs exactly one.`);
+        }
+        for (const ticket of tickets) {
+            const dep = ticket.blockedBy[0];
+            if (!dep)
+                continue;
+            const upstream = tickets.find((candidate) => candidate.number === dep.number);
+            if (!upstream || workflows.get(upstream.path) !== INVESTIGATION_WORKFLOW)
+                continue;
+            throw new Error(`Ticket ${ticket.file} stacks on ${upstream.file}, which is an investigation. An investigation does not land a branch.`);
+        }
+    }
     const existing = new Map();
     for (const job of listValidJobs(config)) {
         if (job.source?.kind !== "tickets")
@@ -170,21 +179,17 @@ function composeSpec(ticketText, context) {
     const body = context.text.endsWith("\n") ? context.text : `${context.text}\n`;
     return `${base}\n## Background\n\n${body}`;
 }
-function workflowFor(ticket, requested, warnings) {
-    return workflowForSpike(ticket.file, ticket.spike, requested, warnings);
+function workflowFor(ticket, requested) {
+    return workflowForSpike(ticket.spike, requested);
 }
 /**
- * Spike and research work uses `investigation` when that workflow file exists.
- * Otherwise the requested workflow is kept and the same warning is recorded.
+ * Spike and research work uses the investigation workflow.
  * Jira intake calls this for issue types Spike and Research.
  */
-export function workflowForSpike(label, spike, requested, warnings) {
+export function workflowForSpike(spike, requested) {
     if (!spike)
         return requested;
-    if (existsSync(join(packageRoot(), "workflows", "investigation.yaml")))
-        return "investigation";
-    warnings.push(`warning: ${label} looks like a spike or says no product code; workflows/investigation.yaml is missing, using ${requested}.`);
-    return requested;
+    return INVESTIGATION_WORKFLOW;
 }
 function readTickets(dirAbs) {
     const names = readdirSync(dirAbs)

package/dist/jobs.js

@@ -1,6 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, isAbsolute, join } from "node:path";
+import { INVESTIGATION_WORKFLOW } from "./findings.js";
 import { jobBasename } from "./paths.js";
 import { JobSchema } from "./schemas.js";
 import { assertWorkflowName } from "./workflow.js";
@@ -119,7 +120,8 @@ export function listValidJobs(config) {
 /**
  * `stack` needs one upstream in the same repo: the pull request has one base
  * branch, and the worktree is cut from that branch. Zero dependencies and
- * two or more are both rejected. An upstream that is not on disk yet is
+ * two or more are both rejected. An investigation upstream is rejected: that
+ * workflow does not land a branch. An upstream that is not on disk yet is
  * allowed here so an import batch can validate the count before every job
  * exists; the same-repo check runs when the upstream file is already there.
  */
@@ -131,6 +133,9 @@ export function assertCanStack(repo, dependsOn, stack, known = []) {
     }
     const upstreamId = dependsOn[0];
     const upstream = known.find((job) => job.id === upstreamId);
+    if (upstream?.workflow === INVESTIGATION_WORKFLOW) {
+        throw new Error(`stack cannot target investigation job ${upstreamId}. An investigation does not land a branch.`);
+    }
     if (upstream && upstream.repo !== repo) {
         throw new Error(`stack needs upstream ${upstreamId} to be in repo ${repo}. That job is in repo ${upstream.repo}.`);
     }