builder-assistant-engineer 0.2.0

package/dist/review/tests.js

@@ -0,0 +1,140 @@
+import { isTestFile } from "../digest/baseline.js";
+const RUST_TEST = /#\[(?:tokio::)?test\]|#\[cfg\(test\)\]/;
+const ASSERTION = /\bexpect\s*[({]|\bExpect\s*\(|\bassert\w*!\s*\(|\bassert\w*\s*[(]|\bassert\.\w+\s*\(|^\s*assert\s|\b(?:assert|refute)_\w+\b|\brefute\w*\s*[(\s]|\.should\b|\bshould\s*[.(]|\bshouldBe\b|\.Should\(\)|\bt\.(?:Error|Errorf|Fatal|Fatalf|Fail)\b|\bt\.(?:is|not|equal|deepEqual|true|false|truthy|falsy|ok|notOk|same|match|throws)\s*\(|\brequire\.\w+\(|\bXCTAssert\w*\(|#(?:expect|require)\s*\(|\bAssert\.\w+\(|\bassertThat\(|\bself\.assert\w*\(|\$this->assert\w*\(|\bthrow\b/;
+const COMMENT = /^\s*(\/\/|#(?!\[)|\*|\/\*)/;
+const DECLARATIONS = [
+    /\b(?:it|test|specify)(?:\.\w+)*\s*\(\s*(['"`])(.+?)\1/g,
+    /^\s*it\s+(['"])(.+?)\1/gm,
+    /^\s*(?:async\s+)?def\s+()(test\w*)\s*\(/gm,
+    /^\s*func\s+()(Test\w+)\s*\(/gm,
+    /^\s*func\s+()(test\w+)\s*\(/gm,
+    /^\s*test\s+(["'])(.+?)\1\s+do\b/gm,
+    /\bt\.Run\(\s*(["'`])(.+?)\1/g,
+    /\bfunction\s+()(test\w+)\s*\(/g,
+    /@(?:Test|ParameterizedTest|RepeatedTest)\b(?:\([^)]*\))?(?:\s*@[\w.]+(?:\([^)]*\))?)*\s*(?:(?:public|protected|private|internal|open|override|suspend|static|final)\s+)*(?:void|fun)\s+()`?([\w ]+?)`?\s*\(/g,
+    /\[(?:Fact|Theory|Test|TestMethod|TestCase)\b[^\]]*\](?:\s*\[[^\]]*\])*\s*(?:(?:public|private|internal|protected|static|async)\s+)*(?:void|Task)\s+()(\w+)\s*\(/g,
+    /#\[(?:tokio::)?test\](?:\s*#\[[^\]]*\])*\s*(?:pub\s+)?(?:async\s+)?fn\s+()(\w+)\s*\(/g,
+];
+const ANNOTATED = /#\[(?:tokio::)?test\]|@(?:Test|ParameterizedTest|RepeatedTest|TestFactory)\b|\[(?:Fact|Theory|Test|TestMethod|TestCase)\b/g;
+const SKIP_MARKERS = [
+    [".skip", /\b(?:it|test|describe|context|suite)(?:\.\w+)*\.(?:skip|skipIf|runIf)\b/],
+    [".only", /\b(?:it|test|describe|context|suite)(?:\.\w+)*\.only\b/],
+    [".todo", /\b(?:it|test)(?:\.\w+)*\.todo\b/],
+    ["pytestmark", /\bpytestmark\s*=.*pytest\.mark\.(?:skip|skipif)\b/],
+    ["@pytest.mark.xfail", /\bpytestmark\s*=.*pytest\.mark\.xfail\b|@pytest\.mark\.xfail\b/],
+    ["go:build ignore", /^\/\/\s*(?:go:build|\+build)\s+ignore\b/m],
+    ["expected failure", /\b(?:it|test)(?:\.\w+)*\.(?:fails|failing)\b|\btest\.fail\s*\(/],
+    ["@unittest.expectedFailure", /@unittest\.expectedFailure\b|@expectedFailure\b/],
+    ["pytest.xfail", /\bpytest\.xfail\s*\(/],
+    ["focused test", /(?:^|[^.\w$])f(?:it|describe)\s*\(/m],
+    ["x-prefixed spec", /^\s*x(?:it|describe|context|specify)\s+["']/m],
+    ["rspec skip", /^\s*(?:skip|pending)(?:\s+["']|\s*$|\s+do\b)/m],
+    [
+        "node:test skip",
+        /\b(?:it|test|describe|suite)\s*\([^\n]*\bskip\s*:\s*true\b|\bt\.(?:skip|todo)\s*\(/,
+    ],
+    ["x-prefixed test", /\bx(?:it|describe|test|context)\s*\(/],
+    ["test.fixme", /\btest\.fixme\b/],
+    ["@pytest.mark.skip", /@pytest\.mark\.(?:skip|skipif)\b/],
+    ["pytest.skip", /\bpytest\.skip\s*\(/],
+    ["@unittest.skip", /@unittest\.skip\w*/],
+    ["t.Skip", /\bt\.Skip(?:f|Now)?\s*\(/],
+    ["#[ignore]", /#\[ignore\b/],
+    ["@Disabled", /@Disabled\b/],
+    ["@Ignore", /@Ignore\b|\[Ignore\b/],
+    ["this.skip", /\bthis\.skip\s*\(/],
+    ["markTestSkipped", /markTestSkipped\s*\(/],
+];
+const RUNNER_CONFIG = /(^|\/)(vitest\.(config|workspace)|jest\.config|playwright\.config|cypress\.config|karma\.conf|vite\.config)\.[cm]?[jt]s(on)?$|(^|\/)(pytest\.ini|conftest\.py|\.mocharc(\.\w+)?|phpunit\.xml(\.dist)?)$/;
+const EXCLUSIONS = [
+    ["testPathIgnorePatterns", /testPathIgnorePatterns/],
+    ["testIgnore", /\btestIgnore\b/],
+    ["--deselect", /--deselect\b/],
+    ["-k", /(^|\s|["'])-k(\s|=)/],
+    ["norecursedirs", /\bnorecursedirs\b/],
+    ["pytest_collection_modifyitems", /pytest_collection_modifyitems/],
+    ["pytest_ignore_collect", /pytest_ignore_collect|collect_ignore/],
+    ["testMatch", /\btestMatch\b|\btestRegex\b/],
+    ["roots", /\broots\s*:/],
+    ["test exclude", /\btest\s*:\s*\{[^}]*\b(?:exclude|include)\b/],
+];
+const SUPPRESSIONS = [
+    ["@ts-ignore", /@ts-(?:ignore|expect-error|nocheck)\b/, undefined],
+    [
+        "eslint-disable",
+        /eslint-disable(?:-next-line|-line)?\b/,
+        /eslint-disable(?:-next-line|-line)?\s+[@\w/-]/,
+    ],
+    ["biome-ignore", /biome-ignore\b/, /biome-ignore\S*\s+\S/],
+    ["type: ignore", /#\s*type:\s*ignore\b/, /#\s*type:\s*ignore\[/],
+    ["noqa", /#\s*noqa\b/i, /#\s*noqa:\s*[A-Z]/i],
+    ["pylint: disable", /pylint:\s*disable\b/, /pylint:\s*disable=(?!all\b)[\w-]/],
+    ["nolint", /\/\/\s*nolint\b/, /\/\/\s*nolint:\w/],
+    ["#[allow]", /#!?\[allow\(/, /#!?\[allow\(/],
+    [
+        "@SuppressWarnings",
+        /@SuppressWarnings\b|@Suppress\(/,
+        /@SuppressWarnings\(\s*["{]|@Suppress\(\s*"/,
+    ],
+    ["rubocop:disable", /rubocop:disable\b/, /rubocop:disable\s+(?!all\b)[A-Z]/],
+    [
+        "phpstan-ignore",
+        /@phpstan-ignore|@psalm-suppress/,
+        /@phpstan-ignore(?:-next-line|-line)?\s+[\w.]+|@psalm-suppress\s+\w/,
+    ],
+];
+const DIRECTIVES = new Set(["go:build ignore"]);
+export const EXPECTED_FAILURES = new Set([
+    "expected failure",
+    "@unittest.expectedFailure",
+    "pytest.xfail",
+    "@pytest.mark.xfail",
+]);
+const EXPECTED_OUTPUT = /(^|\/)__snapshots__\/|\.snap$|(^|\/)testdata\/|\.golden$|(^|\/)__fixtures__\/.*\.expected/;
+export function suppressionLines(text) {
+    return text.split("\n").flatMap((line) => SUPPRESSIONS.filter(([, pattern]) => pattern.test(line)).map(([name, , specific]) => ({
+        name,
+        specific: specific?.test(line) ?? false,
+    })));
+}
+export function isExpectedOutput(path) {
+    return EXPECTED_OUTPUT.test(path);
+}
+export function isTestChange(item) {
+    return isTestFile(item.path) || (item.path.endsWith(".rs") && RUST_TEST.test(item.text));
+}
+export function addsAssertions(item) {
+    return isTestChange(item) && assertionCount(item.text) > 0;
+}
+export function assertionCount(text) {
+    return code(text).filter((line) => ASSERTION.test(line)).length;
+}
+export function testNames(text) {
+    const body = code(text).join("\n");
+    return DECLARATIONS.flatMap((pattern) => [...body.matchAll(pattern)].map((match) => match[2] ?? "")).filter(Boolean);
+}
+export function annotatedCount(text) {
+    return [...code(text).join("\n").matchAll(ANNOTATED)].length;
+}
+function code(text) {
+    return text.split("\n").filter((line) => !COMMENT.test(line));
+}
+export function markerCounts(text) {
+    const counts = new Map();
+    const kept = new Set(code(text));
+    for (const line of text.split("\n")) {
+        for (const [name, pattern] of SKIP_MARKERS) {
+            if (!kept.has(line) && !DIRECTIVES.has(name))
+                continue;
+            if (pattern.test(line))
+                counts.set(name, (counts.get(name) ?? 0) + 1);
+        }
+    }
+    return counts;
+}
+export function isRunnerConfig(path) {
+    return RUNNER_CONFIG.test(path);
+}
+export function exclusionKeys(text) {
+    return EXCLUSIONS.filter(([, pattern]) => pattern.test(text)).map(([name]) => name);
+}

package/dist/tasks/attempts.js

@@ -0,0 +1,71 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { readTextIfExists } from "../core/fs.js";
+import { asRecord } from "../core/json.js";
+import { runDir } from "./runs.js";
+export const GATE_STAGES = [
+    "agent",
+    "contract",
+    "refused",
+    "declined",
+    "verification",
+    "regression",
+    "integrity",
+    "handoff",
+    "review",
+];
+export const MAX_ATTEMPTS = 3;
+const ATTEMPTS_FILE = "attempts.jsonl";
+const OUTCOMES = new Set(["done", "failed", "blocked"]);
+export async function recordAttempt(cwd, id, attempt) {
+    const dir = runDir(cwd, id);
+    await mkdir(dir, { recursive: true });
+    await appendFile(join(dir, ATTEMPTS_FILE), `${JSON.stringify(attempt)}\n`, "utf8");
+}
+export async function readAttempts(cwd, id) {
+    const text = (await readTextIfExists(join(runDir(cwd, id), ATTEMPTS_FILE))) ?? "";
+    return text
+        .split(/\r?\n/)
+        .filter((line) => line.trim() !== "")
+        .flatMap((line) => {
+        const attempt = toAttempt(line);
+        return attempt ? [attempt] : [];
+    });
+}
+function toAttempt(line) {
+    let data;
+    try {
+        data = asRecord(JSON.parse(line));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof data.startedAt !== "string" || !OUTCOMES.has(String(data.outcome)))
+        return undefined;
+    const stage = GATE_STAGES.find((value) => value === data.stage);
+    return {
+        startedAt: data.startedAt,
+        durationMs: typeof data.durationMs === "number" ? data.durationMs : 0,
+        headless: data.headless === true,
+        outcome: data.outcome,
+        ...(stage ? { stage } : {}),
+        regressions: strings(data.regressions),
+        ...(typeof data.reason === "string" ? { reason: data.reason } : {}),
+        ...(Array.isArray(data.skips) ? { skips: strings(data.skips) } : {}),
+        ...(Array.isArray(data.accepted) ? { accepted: strings(data.accepted) } : {}),
+    };
+}
+export function sinceBlocked(attempts) {
+    const last = attempts.map((attempt) => attempt.outcome).lastIndexOf("blocked");
+    return attempts.slice(last + 1);
+}
+export async function attemptsLeft(cwd, id) {
+    return Math.max(0, MAX_ATTEMPTS - sinceBlocked(await readAttempts(cwd, id)).length);
+}
+export async function blockedReason(cwd, id) {
+    return (await readAttempts(cwd, id)).filter((attempt) => attempt.outcome === "blocked").at(-1)
+        ?.reason;
+}
+function strings(value) {
+    return Array.isArray(value) ? value.map(String) : [];
+}

package/dist/tasks/checks.js

@@ -0,0 +1,181 @@
+import { logicalLines, parseLine, program } from "./shell-words.js";
+const RUNNERS = new Set(("npm npx pnpm pnpx yarn bun bunx deno node tsx ts-node vitest jest mocha ava tap playwright cypress tsc vue-tsc eslint biome prettier stylelint " +
+    "python python3 py pytest tox nox ruff mypy pyright flake8 black isort uv poetry pipenv hatch pdm " +
+    "go gofmt golangci-lint staticcheck cargo rustc make cmake ctest ninja gradle gradlew mvn mvnw dotnet java javac kotlinc sbt " +
+    "php composer phpunit pest phpstan psalm bundle rake rspec ruby rails rubocop mix elixir swift xcodebuild flutter dart shellcheck " +
+    "turbo nx lerna rush just bazel bazelisk moon").split(" "));
+const CHECKS = new Set(["test", "[", "[[", "grep", "egrep", "fgrep", "rg", "diff", "cmp"]);
+const HELPERS = new Set("cd echo printf ls cat pwd true : export sleep head tail wc sort uniq tee mkdir touch cp which exit set".split(" "));
+const TRIVIAL = new Set("echo printf ls cat pwd true : exit sleep cd export".split(" "));
+const GIT_READ = new Set([
+    "diff",
+    "status",
+    "log",
+    "show",
+    "ls-files",
+    "grep",
+    "rev-parse",
+    "describe",
+    "blame",
+]);
+const DYNAMIC = new Set(["eval", "source", ".", "exec", "xargs", "command", "builtin", "env"]);
+const RELEASING = {
+    npm: ["publish", "unpublish", "deprecate", "owner", "login", "adduser", "dist-tag"],
+    pnpm: ["publish", "login"],
+    yarn: ["publish", "npm", "login"],
+    bun: ["publish"],
+    cargo: ["publish", "yank", "owner", "login"],
+    docker: ["push", "login"],
+    podman: ["push", "login"],
+    poetry: ["publish"],
+    uv: ["publish"],
+    hatch: ["publish"],
+    pdm: ["publish"],
+    twine: ["upload"],
+    gem: ["push", "yank"],
+    dotnet: ["nuget"],
+    mvn: ["deploy", "release:perform", "release:prepare"],
+    mvnw: ["deploy", "release:perform", "release:prepare"],
+    gradle: ["publish"],
+    gradlew: ["publish"],
+    mix: ["hex.publish"],
+    dart: ["pub"],
+    flutter: ["pub"],
+};
+const WRAPPERS = new Set(["timeout", "nice", "xvfb-run", "nohup", "time"]);
+const HEADERS = new Set(["for", "case", "select", "in"]);
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh", "fish", "pwsh", "powershell", "cmd"]);
+const SCRIPT_SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
+const DOWNLOADERS = new Set(["curl", "wget"]);
+const MASKING = /\bset\s+\+[A-Za-z]*e[A-Za-z]*\b|\bset\s+\+o\s+(?:errexit|pipefail)\b|\btrap\s+-?\s*['"]?\s*['"]?\s+ERR\b/;
+const FALLBACK_OK = /^\s*(?:exit\s+(?:[1-9]\d*|\$\?)|false|\{[^}]*\bexit\s+(?:[1-9]\d*|\$\?)\s*;?\s*\})/;
+export function trivialityProblems(lines) {
+    const logical = logicalLines(lines);
+    const masked = logical
+        .filter((line) => MASKING.test(line) || masksWithOperators(line))
+        .map((command) => ({ command, reason: "masks" }));
+    const checks = logical.some((line) => parseLine(line).commands.some((command) => runsOrChecks(command)));
+    const trivial = logical.length > 0 && !checks
+        ? [{ command: logical.join("\n"), reason: "trivial" }]
+        : [];
+    return [...masked, ...trivial];
+}
+export function allowlistProblems(lines, allow) {
+    return logicalLines(lines).flatMap((line) => {
+        const parsed = parseLine(line);
+        if (parsed.substitution || /[<>]\(/.test(line)) {
+            return [{ command: line, reason: "dynamic" }];
+        }
+        const downloads = parsed.commands.some((command) => DOWNLOADERS.has(baseName(program(command).name)));
+        const bad = parsed.commands.find((command) => !allow.some((prefix) => command.text.startsWith(prefix)) && !allowed(command, downloads));
+        if (!bad)
+            return [];
+        const { name } = program(bad);
+        const dynamic = DYNAMIC.has(name) || SHELLS.has(name);
+        return [{ command: line, reason: dynamic ? "dynamic" : "notAllowed" }];
+    });
+}
+function masksWithOperators(line) {
+    const unquoted = line.replace(/'[^']*'|"(?:[^"\\]|\\.)*"/g, "''");
+    const fallbacks = unquoted.split("||").slice(1);
+    if (fallbacks.some((fallback) => !FALLBACK_OK.test(fallback) && !checksAgain(fallback))) {
+        return true;
+    }
+    return /(^|[^&|])&(\s*$|\s*[;)]|\s+\S)/.test(unquoted.replace(/&&|&>|>&|\|&|\d>&\d/g, ""));
+}
+function checksAgain(fallback) {
+    const [first] = parseLine(fallback.trim()).commands;
+    if (!first)
+        return false;
+    const { name } = program(first);
+    return CHECKS.has(baseName(name));
+}
+function runsOrChecks(command) {
+    const { name, args } = unwrap(program(command));
+    const base = baseName(name);
+    if (RUNNERS.has(base) || runsScriptFile(base, args))
+        return true;
+    if (CHECKS.has(base))
+        return true;
+    if (base === "curl")
+        return args.some((arg) => /^(-[a-zA-Z]*f[a-zA-Z]*|--fail(-with-body)?)$/.test(arg));
+    if (base === "jq")
+        return args.some((arg) => /^(-[a-zA-Z]*e[a-zA-Z]*|--exit-status)$/.test(arg));
+    if (base === "git")
+        return args[0] === "diff" && args.some((arg) => arg === "--exit-code" || arg === "--quiet");
+    return false;
+}
+function allowed(command, downloads) {
+    if (HEADERS.has(command.words[0] ?? ""))
+        return true;
+    const { name, args } = unwrap(program(command));
+    const base = baseName(name);
+    if (name === "")
+        return true;
+    if (!downloads && runsScriptFile(base, args))
+        return true;
+    if (DYNAMIC.has(base) || SHELLS.has(base))
+        return false;
+    if (releases(base, args))
+        return false;
+    if (base === "rm")
+        return safeRemove(args);
+    if (base === "git")
+        return GIT_READ.has(args[0] ?? "");
+    if (base === "curl" || base === "jq")
+        return true;
+    if (!TRIVIAL.has(base) &&
+        name.includes("/") &&
+        !/(^|\/)node_modules\/\.bin\/|(^|\/)vendor\/bin\//.test(name) &&
+        !/^\.\/(gradlew|mvnw)$/.test(name)) {
+        return false;
+    }
+    return RUNNERS.has(base) || CHECKS.has(base) || HELPERS.has(base);
+}
+function runsScriptFile(base, args) {
+    if (!SCRIPT_SHELLS.has(base))
+        return false;
+    const script = args.find((arg) => !arg.startsWith("-"));
+    const flags = args.slice(0, script ? args.indexOf(script) : args.length);
+    if (!script || flags.some((flag) => /^-[a-zA-Z]*[cis]/.test(flag) || flag.startsWith("--"))) {
+        return false;
+    }
+    return (!script.startsWith("/") && !script.split(/[\\/]/).includes("..") && !/^[a-z]:/i.test(script));
+}
+function unwrap(found) {
+    const base = baseName(found.name);
+    if (!WRAPPERS.has(base))
+        return found;
+    let index = 0;
+    const args = found.args;
+    while (index < args.length && (args[index] ?? "").startsWith("-")) {
+        index += /^-(n|s|k|-signal|-kill-after|-server-args)$/.test(args[index] ?? "") ? 2 : 1;
+    }
+    if (base === "timeout")
+        index++;
+    const [name = "", ...rest] = args.slice(index);
+    return name ? unwrap({ name, args: rest }) : { name: base, args: [] };
+}
+function releases(base, args) {
+    if (args.includes("--dry-run"))
+        return false;
+    const subcommands = RELEASING[base];
+    const first = args.find((arg) => !arg.startsWith("-"));
+    if (subcommands && first && subcommands.includes(first))
+        return true;
+    if (!["npx", "pnpx", "bunx"].includes(base) || !first)
+        return false;
+    const rest = args.slice(args.indexOf(first) + 1);
+    return releases(baseName(first), rest);
+}
+function safeRemove(args) {
+    const paths = args.filter((arg) => !arg.startsWith("-"));
+    return (paths.length > 0 &&
+        paths.every((path) => !/^([/~]|[a-z]:)/i.test(path) &&
+            !path.split(/[\\/]/).includes("..") &&
+            !/^(\.|\*|\.\/?\*?)$/.test(path) &&
+            !path.includes("$")));
+}
+function baseName(name) {
+    return (name.split("/").at(-1) ?? name).replace(/\.(cmd|exe|bat)$/i, "");
+}

package/dist/tasks/frontmatter.js

@@ -0,0 +1,58 @@
+import { parse } from "yaml";
+import { asRecord } from "../core/json.js";
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+const LINE = /^([A-Za-z_][\w-]*)[ \t]*:[ \t]*(.*)$/;
+export function splitFrontmatter(text) {
+    const match = FRONTMATTER.exec(text);
+    if (!match)
+        return undefined;
+    return { data: parseFields(match[1] ?? ""), body: text.slice(match[0].length) };
+}
+export function setFrontmatterFields(text, fields) {
+    const match = FRONTMATTER.exec(text);
+    if (!match)
+        return text;
+    let lines = (match[1] ?? "").split(/\r?\n/);
+    for (const [key, value] of Object.entries(fields)) {
+        const first = lines.findIndex((line) => LINE.exec(line)?.[1] === key);
+        lines =
+            first === -1
+                ? [...lines, `${key}: ${value}`]
+                : lines.flatMap((line, index) => {
+                    if (index === first)
+                        return [`${key}: ${value}`];
+                    return LINE.exec(line)?.[1] === key ? [] : [line];
+                });
+    }
+    return `---\n${lines.join("\n")}\n---\n${text.slice(match[0].length)}`;
+}
+function parseFields(raw) {
+    try {
+        return asRecord(parse(raw));
+    }
+    catch {
+        return parseLoose(raw);
+    }
+}
+function parseLoose(raw) {
+    const fields = {};
+    for (const line of raw.split(/\r?\n/)) {
+        const match = LINE.exec(line);
+        if (match?.[1])
+            fields[match[1]] = looseValue((match[2] ?? "").trim());
+    }
+    return fields;
+}
+function looseValue(value) {
+    const list = /^\[(.*)\]$/.exec(value);
+    if (list) {
+        return (list[1] ?? "")
+            .split(",")
+            .map((item) => unquote(item.trim()))
+            .filter(Boolean);
+    }
+    return unquote(value);
+}
+function unquote(value) {
+    return /^(["']).*\1$/.test(value) ? value.slice(1, -1) : value;
+}

package/dist/tasks/graph.js

@@ -0,0 +1,27 @@
+export function findCycle(nodes) {
+    const edges = new Map(nodes.map((node) => [node.id, node.dependsOn]));
+    const state = new Map();
+    const stack = [];
+    const visit = (id) => {
+        if (state.get(id) === "done")
+            return undefined;
+        if (state.get(id) === "visiting")
+            return [...stack.slice(stack.indexOf(id)), id];
+        state.set(id, "visiting");
+        stack.push(id);
+        for (const next of edges.get(id) ?? []) {
+            const cycle = visit(next);
+            if (cycle)
+                return cycle;
+        }
+        stack.pop();
+        state.set(id, "done");
+        return undefined;
+    };
+    for (const node of nodes) {
+        const cycle = visit(node.id);
+        if (cycle)
+            return cycle;
+    }
+    return undefined;
+}

package/dist/tasks/handoff.js

@@ -0,0 +1,62 @@
+import { COMMAND_KEYS } from "../config/schema.js";
+import { compareIds } from "./load.js";
+import { sectionTexts } from "./schema.js";
+import { waitingOn } from "./select.js";
+export const MAX_LOG_LINES = 8;
+export const RECENT_LOGS = 3;
+const LOG_HEADING = /^##[ \t]+(log|registro|bitácora|bitacora)[ \t]*$/im;
+const COMMENT = /<!--[\s\S]*?-->/g;
+export function logLines(task) {
+    return sectionTexts(task.body, "log")
+        .join("\n")
+        .replace(COMMENT, "")
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .filter((line) => line.trim() !== "");
+}
+export function withLogSection(text) {
+    return LOG_HEADING.test(text) ? text : `${text.trimEnd()}\n\n## Log\n`;
+}
+export function planContext(config, tasks, current, completedAt = new Map()) {
+    return [planState(tasks, current), commandsSection(config), recentNotes(tasks, completedAt)]
+        .filter(Boolean)
+        .join("\n\n");
+}
+function planState(tasks, current) {
+    const done = tasks.filter((task) => task.meta.status === "done").length;
+    const blocked = tasks.filter((task) => task.meta.status === "blocked");
+    const others = tasks.filter((task) => task.meta.id !== current.meta.id);
+    const upNext = others
+        .filter((task) => task.meta.status === "pending")
+        .filter((task) => waitingOn(task, tasks).every((id) => id === current.meta.id))
+        .slice(0, 3);
+    const lines = [
+        `- Done: ${done} of ${tasks.length} tasks. You are on ${current.meta.id} (phase ${current.meta.phase}).`,
+    ];
+    if (blocked.length > 0)
+        lines.push(`- Blocked, do not work on them: ${titles(blocked)}`);
+    if (upNext.length > 0)
+        lines.push(`- Up next after this task: ${titles(upNext)}`);
+    return ["## Where the plan stands", "", ...lines].join("\n");
+}
+function commandsSection(config) {
+    const lines = COMMAND_KEYS.flatMap((key) => {
+        const command = config.commands[key];
+        return command ? [`- ${key}: \`${command}\``] : [];
+    });
+    return lines.length > 0 ? ["## Project commands", "", ...lines].join("\n") : "";
+}
+function recentNotes(tasks, completedAt) {
+    const notes = tasks
+        .filter((task) => task.meta.status === "done" && logLines(task).length > 0)
+        .sort((a, b) => (completedAt.get(b.meta.id) ?? 0) - (completedAt.get(a.meta.id) ?? 0) ||
+        compareIds(b.meta.id, a.meta.id))
+        .slice(0, RECENT_LOGS)
+        .map((task) => `### ${task.meta.id} ${task.meta.title}\n\n${logLines(task).join("\n")}`);
+    if (notes.length === 0)
+        return "";
+    return ["## Handoff notes from the last finished tasks", ...notes].join("\n\n");
+}
+function titles(tasks) {
+    return tasks.map((task) => `${task.meta.id} ${task.meta.title}`).join("; ");
+}

package/dist/tasks/learn.js

@@ -0,0 +1,128 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { LANGUAGE_NAMES } from "../analyst/prompt.js";
+import { runWithFormatRetry } from "../analyst/retry.js";
+import { readLessons, withLessons } from "../artifacts/lessons.js";
+import { managedBody, mergeManaged } from "../artifacts/merge.js";
+import { FormatError, UserError } from "../core/errors.js";
+import { readTextIfExists, writeText } from "../core/fs.js";
+import { renderPrompt } from "../core/prompt-loader.js";
+import { displayPath } from "../core/state.js";
+import { truncateText } from "../digest/format.js";
+import { capturedPrompt, trustAgentsMd } from "../gates/capture.js";
+import { withoutLog } from "../gates/contract.js";
+import { t } from "../i18n/index.js";
+import { runDir } from "./runs.js";
+const lessonSchema = z.object({ root_cause: z.string().min(1), rule: z.string().min(1) });
+export const LESSON_FORMAT = 'JSON only: {"root_cause": "one or two sentences", "rule": "one imperative line"}';
+const LESSON_FILE = "lesson.md";
+const AGENTS_MD = "AGENTS.md";
+const RECENT_RUNS = 3;
+const MAX_RUN_CHARS = 6_000;
+const MAX_AGENTS_MD = 20_000;
+const REASONS = {
+    blocked: "was blocked after every automatic retry failed",
+    review: "failed its review twice",
+};
+export function parseLesson(text) {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start === -1 || end < start)
+        throw new FormatError("no JSON object found");
+    let data;
+    try {
+        data = JSON.parse(text.slice(start, end + 1));
+    }
+    catch (error) {
+        throw new FormatError(`invalid JSON: ${error instanceof Error ? error.message : error}`);
+    }
+    const result = lessonSchema.safeParse(data);
+    if (!result.success)
+        throw new FormatError(z.prettifyError(result.error));
+    const rule = result.data.rule
+        .split(/\r?\n/)[0]
+        ?.replace(/^[-*]\s+/, "")
+        .trim() ?? "";
+    if (rule === "")
+        throw new FormatError("rule is empty");
+    return { rootCause: result.data.root_cause.trim(), rule: rule.replace(/\s+/g, " ") };
+}
+export async function learnFromFailure(ctx, capture, reason) {
+    const path = join(runDir(ctx.cwd, capture.id), LESSON_FILE);
+    if (capture.config.backend === "manual" || (await readTextIfExists(path)) !== undefined)
+        return;
+    const lesson = await askLesson(ctx, capture, reason);
+    if (!lesson)
+        return;
+    const { id } = capture;
+    ctx.prompter.note(t("lesson.body", { cause: lesson.rootCause, rule: lesson.rule }), t("lesson.title", { id }));
+    const approved = ctx.flags.yes || (await ctx.prompter.confirm(t("lesson.confirm"), true));
+    await writeText(path, renderLesson(id, reason, lesson, approved));
+    if (!approved) {
+        ctx.prompter.info(t("lesson.skipped", { path: displayPath(path) }));
+        return;
+    }
+    await addLesson(ctx.cwd, lesson.rule);
+    await trustAgentsMd(ctx.cwd, capture, withRule(capture.agentsMd, lesson.rule));
+    ctx.prompter.success(t("lesson.added"));
+}
+export async function addLesson(cwd, rule) {
+    const path = join(cwd, AGENTS_MD);
+    const text = withRule(await readTextIfExists(path), rule);
+    await writeText(path, text);
+    return text;
+}
+export function withRule(before, rule) {
+    const lessons = readLessons(before ?? "");
+    if (lessons.includes(rule))
+        return before ?? "";
+    const body = withLessons(managedBody(before ?? ""), [...lessons, rule]);
+    return mergeManaged(before, body, AGENTS_MD);
+}
+async function askLesson(ctx, capture, reason) {
+    const prompt = renderPrompt(capturedPrompt(capture, "lesson"), {
+        reason: REASONS[reason],
+        task: withoutLog(capture.task),
+        failures: await recentRuns(ctx.cwd, capture.id),
+        agents_md: truncateText(capture.agentsMd ?? "(none)", MAX_AGENTS_MD),
+        output_language: LANGUAGE_NAMES[capture.config.lang],
+    });
+    try {
+        return await ctx.prompter.spinner(t("lesson.asking", { id: capture.id }), () => runWithFormatRetry({
+            backend: ctx.createBackend(capture.config.backend),
+            prompt,
+            options: { cwd: ctx.cwd, access: "read" },
+            parse: parseLesson,
+            format: LESSON_FORMAT,
+            fixPrompt: capturedPrompt(capture, "fix-format"),
+            onRetry: () => ctx.prompter.warn(t("format.retrying")),
+        }));
+    }
+    catch (error) {
+        if (!(error instanceof UserError))
+            throw error;
+        ctx.prompter.warn(t("lesson.failed", { details: error.message }));
+        return undefined;
+    }
+}
+async function recentRuns(cwd, id) {
+    const dir = runDir(cwd, id);
+    const names = (await readdir(dir).catch(() => []))
+        .filter((name) => name.endsWith(".md") && name !== LESSON_FILE)
+        .sort()
+        .slice(-RECENT_RUNS);
+    const runs = await Promise.all(names.map(async (name) => truncateText((await readTextIfExists(join(dir, name))) ?? "", MAX_RUN_CHARS)));
+    return runs.join("\n\n---\n\n") || "(no run logs)";
+}
+function renderLesson(id, reason, lesson, approved) {
+    return [
+        `# Lesson from ${id}`,
+        "",
+        `- Reason: ${REASONS[reason]}`,
+        `- Root cause: ${lesson.rootCause}`,
+        `- Rule: ${lesson.rule}`,
+        `- Added to AGENTS.md: ${approved ? "yes" : "no"}`,
+        "",
+    ].join("\n");
+}