@lchase/kiln 0.1.0 → 0.4.0

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}.`);
     }

package/dist/reconcile.js

@@ -1,3 +1,6 @@
+import { INVESTIGATION_WORKFLOW } from "./findings.js";
+/** Why a transient attempt failed. Written under `<kilnDir>/attempts`, not on the job. */
+export const FAILURE_REASONS = ["stalled", "orphaned", "crashed", "failed"];
 export function inFlightCount(observation) {
     return observation.jobs.filter((job) => inFlight(job, observation)).length;
 }
@@ -14,35 +17,51 @@ function inFlight(job, observation) {
  * `approved` is the approve decision while the run is still alive. It holds
  * a slot and does not unblock dependents. An ok run with no readable
  * decision is `failed`, so a missing artifact cannot unblock the next job.
+ * An investigation is `done` on approve and never `in-review`.
  */
 export function jobState(job, observation) {
-    if (job.launchFailed && !job.run)
-        return "failed";
-    if (job.run) {
-        if (isLanded(job))
-            return landedState(job);
-        if (job.run.status === "ok" && job.run.gateDecision === "reject")
-            return "rejected";
-        if (job.run.status === "ok")
-            return "failed";
-        if (job.run.status === "failed")
-            return "failed";
-        if (job.run.status === "dead")
-            return "dead";
-        if (job.run.status === "suspended")
-            return "needs-human";
-        if (job.run.gateDecision === "approve")
-            return "approved";
+    if (job.launching && (!job.run || job.runRetired))
         return "running";
-    }
+    if (job.run && !job.runRetired)
+        return activeRunState(job);
+    if (job.run && isLanded(job))
+        return landedState(job);
+    if (job.run?.status === "ok" && job.run.gateDecision === "reject")
+        return "rejected";
+    if (job.run?.status === "suspended")
+        return "needs-human";
+    if (job.retriesExhausted)
+        return "dead";
+    if (job.runRetired || job.run?.status === "failed" || job.run?.status === "dead")
+        return "failed";
     if (job.launching)
         return "running";
     if (!dependenciesMet(job, observation))
         return "blocked";
-    if (job.launchError)
+    if (job.launchError || job.launchFailed)
         return "failed";
     return "queued";
 }
+/** State of the current run, before the attempt ledger retires it. */
+function activeRunState(job) {
+    if (!job.run)
+        return "queued";
+    if (isLanded(job))
+        return landedState(job);
+    if (job.run.status === "ok" && job.run.gateDecision === "reject")
+        return "rejected";
+    if (job.run.status === "ok")
+        return "failed";
+    if (job.run.status === "failed")
+        return "failed";
+    if (job.run.status === "dead")
+        return "dead";
+    if (job.run.status === "suspended")
+        return "needs-human";
+    if (job.run.gateDecision === "approve")
+        return "approved";
+    return "running";
+}
 /**
  * After-merged (the default) needs every upstream `done`.
  * Stacked needs its one upstream landed (approved and the run finished ok),
@@ -60,15 +79,22 @@ export function dependenciesMet(job, observation) {
 export function isLanded(job) {
     return job.run?.status === "ok" && job.run.gateDecision === "approve";
 }
-/** `deliver=local`: landed. `deliver=pr`: landed and the pull request has merged. */
+/**
+ * `deliver=local`: landed. `deliver=pr`: landed and the pull request has merged.
+ * An investigation is done once the gate says approve. There is no pull request.
+ */
 export function isDone(job) {
     if (!isLanded(job))
         return false;
+    if (job.workflow === INVESTIGATION_WORKFLOW)
+        return true;
     if ((job.deliver ?? "local") !== "pr")
         return true;
     return job.delivery?.merged === true || job.delivery?.prState === "MERGED";
 }
 function landedState(job) {
+    if (job.workflow === INVESTIGATION_WORKFLOW)
+        return "done";
     if ((job.deliver ?? "local") !== "pr")
         return "done";
     const delivery = job.delivery;
@@ -85,6 +111,8 @@ function landedState(job) {
 function needsDelivery(job) {
     if (job.error)
         return false;
+    if (job.workflow === INVESTIGATION_WORKFLOW)
+        return false;
     if ((job.deliver ?? "local") !== "pr")
         return false;
     if (!isLanded(job))
@@ -102,11 +130,35 @@ function canLaunch(job, observation) {
         return false;
     return dependenciesMet(job, observation);
 }
-export function decide(observation) {
+/** A recorded transient failure whose backoff has elapsed. One retry per tick, ahead of a new job. */
+function canRetry(job, observation, now) {
+    if (job.error || job.launching || job.retriesExhausted || job.ledgerError)
+        return false;
+    if (job.run && !job.runRetired)
+        return false;
+    if (!job.nextRetryAt)
+        return false;
+    const due = Date.parse(job.nextRetryAt);
+    if (!Number.isFinite(due) || due > now.getTime())
+        return false;
+    if (job.run?.gateDecision === "reject" || isLanded(job))
+        return false;
+    if (job.run?.status === "suspended")
+        return false;
+    return dependenciesMet(job, observation);
+}
+export function decide(observation, now = new Date()) {
     const actions = observation.breadcrumbsToClear.map((crumb) => ({
         type: "clear-breadcrumb",
         path: crumb.path,
     }));
+    for (const job of observation.jobs) {
+        if (job.error || job.workflow !== INVESTIGATION_WORKFLOW)
+            continue;
+        if (!isLanded(job) || job.findingsPath)
+            continue;
+        actions.push({ type: "record-findings", jobId: job.jobId });
+    }
     for (const job of observation.jobs) {
         if (!needsDelivery(job))
             continue;
@@ -114,6 +166,11 @@ export function decide(observation) {
     }
     if (inFlightCount(observation) >= observation.maxConcurrent)
         return actions;
+    const retry = observation.jobs.find((job) => canRetry(job, observation, now));
+    if (retry) {
+        actions.push({ type: "retry", jobId: retry.jobId, repo: retry.repo });
+        return actions;
+    }
     const ready = observation.jobs.filter((job) => canLaunch(job, observation));
     const healthy = ready.filter((job) => !job.launchError);
     const picked = healthy[0] ?? ready[0];