@gr8ful/spf 0.1.6 → 0.2.1

package/dist/test/chains.test.js

@@ -0,0 +1,86 @@
+/**
+ * Regression net for the chain registry. Chains used to each be a hand-written
+ * module; now every one but `simple-sdlc` is a `steps` list whose
+ * `phases`/`requiredAgents`/`requiredSuites` are DERIVED (see
+ * `chains/steps.ts`'s `derivePhases`/`deriveRequiredAgents`/
+ * `deriveRequiredSuites`). These tests pin what that derivation produces
+ * today, so a step-factory change that silently alters a chain's shape (an
+ * agent dropped from `requiredAgents`, a suite no longer required, a phase
+ * missing from the display string) fails here instead of only showing up as
+ * a `spf list` diff nobody happened to read.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { CHAINS, findChain, resolveRequiredAgents } from "../chains/index.js";
+// name -> [phases, requiredAgents (with no options), requiredSuites]
+const EXPECTED = {
+    prompt: { phases: "engineer(request) -> <agent>", agents: ["builder"], suites: [] },
+    scout: { phases: "engineer(request) -> scout", agents: ["scout"], suites: [] },
+    plan: { phases: "engineer(request) -> planner", agents: ["planner"], suites: [] },
+    build: { phases: "engineer(request) -> builder", agents: ["builder"], suites: [] },
+    "plan-build": { phases: "engineer(request) -> planner -> builder -> git(commit)", agents: ["planner", "builder"], suites: [] },
+    "build-test": {
+        phases: "engineer(request) -> builder -> code(test) [-> builder(fix) -> code(test) ...] bounded",
+        agents: ["builder"],
+        suites: ["test"],
+    },
+    "plan-build-test": {
+        phases: "engineer(request) -> planner -> builder -> code(test) [-> builder(fix) -> code(test) ...] bounded -> git(commit)",
+        agents: ["planner", "builder"],
+        suites: ["test"],
+    },
+    "plan-build-test-quality": {
+        phases: "engineer(request) -> planner -> builder -> code(verify) [-> builder(fix) -> code(verify) ...] bounded -> git(commit)",
+        agents: ["planner", "builder"],
+        suites: ["all"],
+    },
+    "build-review": {
+        phases: "engineer(request) -> builder -> reviewer [-> builder(revise) -> reviewer ...] bounded",
+        agents: ["builder", "reviewer"],
+        suites: [],
+    },
+    quality: { phases: "engineer(request) -> code(quality)", agents: [], suites: ["all"] },
+    document: { phases: "engineer(request) -> code(changes) -> documenter", agents: ["documenter"], suites: [] },
+    "simple-sdlc": {
+        phases: "engineer(request) -> planner -> git(commit_plan) -> builder -> code(test) [-> builder(fix) -> code(test) ...] " +
+            "-> reviewer [-> builder(revise) -> reviewer ...] -> code(retest, if revised) -> git(commit_build) " +
+            "-> code(changes) -> documenter -> git(commit_docs)",
+        agents: ["planner", "builder", "reviewer", "documenter"],
+        suites: ["test"],
+    },
+};
+test("every chain in the registry has an expectation pinned here", () => {
+    const names = CHAINS.map((c) => c.name).sort();
+    assert.deepEqual(names, Object.keys(EXPECTED).sort(), "a chain was added/removed/renamed without updating this test");
+});
+for (const chain of CHAINS) {
+    const expected = EXPECTED[chain.name];
+    test(`${chain.name}: derived phases/requiredAgents/requiredSuites match what was hand-verified against \`spf list\``, () => {
+        assert.equal(chain.phases, expected.phases);
+        assert.deepEqual(resolveRequiredAgents(chain, {}), expected.agents);
+        assert.deepEqual(chain.requiredSuites, expected.suites);
+    });
+}
+test("prompt: requiredAgents depends on --agent, not a fixed list — the one dynamic case", () => {
+    const chain = findChain("prompt");
+    assert.deepEqual(resolveRequiredAgents(chain, {}), ["builder"], "no --agent -> falls back to builder");
+    assert.deepEqual(resolveRequiredAgents(chain, { agent: "planner" }), ["planner"], "--agent overrides the default");
+});
+test("every chain but simple-sdlc is a steps list; simple-sdlc alone uses the imperative run() escape hatch", () => {
+    for (const chain of CHAINS) {
+        if (chain.name === "simple-sdlc") {
+            assert.ok(chain.run, "simple-sdlc should still be the one hand-written chain");
+            assert.equal(chain.steps, undefined);
+        }
+        else {
+            assert.ok(chain.steps && chain.steps.length > 0, `${chain.name} should be a steps list`);
+            assert.equal(chain.run, undefined, `${chain.name} should not also define run()`);
+        }
+    }
+});
+test("findChain resolves every registered name and nothing else", () => {
+    for (const chain of CHAINS) {
+        assert.equal(findChain(chain.name)?.name, chain.name);
+    }
+    assert.equal(findChain("not-a-real-chain"), undefined);
+});

package/dist/test/env_file.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/env_file.test.js

@@ -0,0 +1,74 @@
+/**
+ * `.env` upsert (`cli/env_file.ts`) — the write-side counterpart of
+ * `process.loadEnvFile()` in `cli/index.ts`, which every command already
+ * uses to load `<repo_root>/.env`. Mirrors `ensureGitignore`'s idempotent
+ * shape: preserve everything unrelated, touch only the keys asked for.
+ */
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, existsSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { maskSecret, readEnvFile, upsertEnvFile, writeEnvExample } from "../cli/env_file.js";
+let dir;
+// Each test gets its own scratch directory with no .env yet — cheap, and
+// avoids one test's leftover .env leaking into the next.
+beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "spf-env-file-test-"));
+});
+afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+});
+test("upsertEnvFile creates a fresh .env with the given keys", () => {
+    const result = upsertEnvFile(dir, { GITHUB_TOKEN: "ghp_abc" });
+    assert.deepEqual(result, { added: ["GITHUB_TOKEN"], updated: [], unchanged: [] });
+    assert.equal(readEnvFile(join(dir, ".env")).get("GITHUB_TOKEN"), "ghp_abc");
+});
+test("upsertEnvFile preserves unrelated lines and comments verbatim, appends new keys under its own header", () => {
+    writeFileSync(join(dir, ".env"), "# a hand-written comment\nFOO=bar\n\nBAZ=qux\n");
+    upsertEnvFile(dir, { GITHUB_TOKEN: "ghp_abc" });
+    const raw = readFileSync(join(dir, ".env"), "utf-8");
+    assert.match(raw, /# a hand-written comment/);
+    assert.match(raw, /FOO=bar/);
+    assert.match(raw, /BAZ=qux/);
+    assert.match(raw, /GITHUB_TOKEN=ghp_abc/);
+});
+test("upsertEnvFile rewrites an existing key in place — never a duplicate line", () => {
+    writeFileSync(join(dir, ".env"), "GITHUB_TOKEN=ghp_old\nOTHER=1\n");
+    const result = upsertEnvFile(dir, { GITHUB_TOKEN: "ghp_new" });
+    assert.deepEqual(result, { added: [], updated: ["GITHUB_TOKEN"], unchanged: [] });
+    const raw = readFileSync(join(dir, ".env"), "utf-8");
+    assert.equal((raw.match(/GITHUB_TOKEN=/g) || []).length, 1);
+    assert.match(raw, /GITHUB_TOKEN=ghp_new/);
+    assert.match(raw, /OTHER=1/);
+});
+test("upsertEnvFile is a no-op the second time with the same values", () => {
+    upsertEnvFile(dir, { GITHUB_TOKEN: "ghp_abc" });
+    const before = readFileSync(join(dir, ".env"), "utf-8");
+    const result = upsertEnvFile(dir, { GITHUB_TOKEN: "ghp_abc" });
+    assert.deepEqual(result, { added: [], updated: [], unchanged: ["GITHUB_TOKEN"] });
+    assert.equal(readFileSync(join(dir, ".env"), "utf-8"), before);
+});
+test("readEnvFile ignores blank lines and comments, and returns an empty map for a missing file", () => {
+    writeFileSync(join(dir, ".env"), "# comment\n\nA=1\n  # indented comment\nB=2\n");
+    const values = readEnvFile(join(dir, ".env"));
+    assert.deepEqual([...values.entries()], [["A", "1"], ["B", "2"]]);
+    assert.equal(readEnvFile(join(dir, "nope.env")).size, 0);
+});
+test("maskSecret keeps only the last 4 characters; short values are fully masked", () => {
+    const value = "ghp_1234567890abcdef"; // 20 chars, last 4 = "cdef"
+    const masked = maskSecret(value);
+    assert.equal(masked.length, value.length);
+    assert.match(masked, /^•+cdef$/);
+    assert.equal(maskSecret("abcd"), "••••");
+    assert.equal(maskSecret("ab"), "••");
+});
+test("writeEnvExample writes key names with empty values, sorted and de-duplicated", () => {
+    writeEnvExample(dir, ["GITHUB_TOKEN", "JIRA_EMAIL", "GITHUB_TOKEN"]);
+    const raw = readFileSync(join(dir, ".env.example"), "utf-8");
+    assert.equal(raw, "# spf — keys required by this repo's spf.config.yaml; fill in real values in .env (gitignored)\nGITHUB_TOKEN=\nJIRA_EMAIL=\n");
+});
+test("writeEnvExample writes nothing when there are no keys", () => {
+    writeEnvExample(dir, []);
+    assert.equal(existsSync(join(dir, ".env.example")), false);
+});

package/dist/test/fake_asker.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared test double for `cli/ask.ts`'s `Asker` interface — the seam
+ * `runInterview` (`cli/interview.ts`) exists to be driven through, the same
+ * way `FakeProvider`/`FakeCodeHost` (`watch.test.ts`) stand in for
+ * `IssueProvider`/`CodeHostProvider`.
+ *
+ * Answers are keyed by a SUBSTRING of the question's label, not by call
+ * order — `runInterview` asks a different number of questions depending on
+ * earlier answers (skip a quality check, skip watch entirely, ...), so a
+ * positional queue would silently misalign the moment a test changes one
+ * answer. Substring matching keeps each scenario's script self-documenting
+ * and immune to that.
+ */
+import type { Asker } from "../cli/ask.js";
+export interface AskerScript {
+    text?: Record<string, string>;
+    select?: Record<string, string>;
+    confirm?: Record<string, boolean>;
+    secret?: Record<string, string>;
+    /** Used when a confirm's label matches nothing in `confirm` above. Defaults to the caller's own default. */
+    defaultConfirm?: boolean;
+}
+export declare function createFakeAsker(script: AskerScript): Asker;

package/dist/test/fake_asker.js

@@ -0,0 +1,30 @@
+function firstMatch(map, label) {
+    if (!map)
+        return undefined;
+    const key = Object.keys(map).find((k) => label.includes(k));
+    return key === undefined ? undefined : map[key];
+}
+export function createFakeAsker(script) {
+    return {
+        async text(label, opts) {
+            const answer = firstMatch(script.text, label);
+            return answer !== undefined ? answer : (opts?.default ?? "");
+        },
+        async select(label, _choices, dflt) {
+            const answer = firstMatch(script.select, label);
+            return (answer !== undefined ? answer : dflt);
+        },
+        async confirm(label, dflt) {
+            const answer = firstMatch(script.confirm, label);
+            if (answer !== undefined)
+                return answer;
+            return script.defaultConfirm ?? dflt;
+        },
+        async secret(label, _opts) {
+            return firstMatch(script.secret, label) ?? "";
+        },
+        note() { },
+        heading() { },
+        close() { },
+    };
+}

package/dist/test/init_command.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/init_command.test.js

@@ -0,0 +1,66 @@
+/**
+ * Regression guard for `spf init`'s non-interactive paths — `--yes`,
+ * `--template <name>`, and (implicitly, since the test runner's stdin/stdout
+ * are never a TTY) plain `spf init` with no flags. All three must keep
+ * writing the exact same content they always have, byte for byte, and must
+ * never touch stdin — a scripted `spf init` in CI must not hang.
+ *
+ * The interactive interview itself is covered directly against `Asker`
+ * in `interview.test.ts`; `initCommand`'s interactive branch always calls
+ * the real `createAsker()` (backed by `node:readline` on `process.stdin`),
+ * which has nothing to read in a test process — exercising it here would
+ * just hang, so it isn't.
+ */
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { initCommand } from "../cli/commands/init.js";
+let dir;
+beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "spf-init-test-"));
+    execFileSync("git", ["init", "-q"], { cwd: dir });
+});
+afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+});
+test("--yes writes the plain starter config, all commented out, with no interview", async () => {
+    const code = await initCommand(["--cwd", dir, "--yes"]);
+    assert.equal(code, 0);
+    const content = readFileSync(join(dir, ".spf", "spf.config.yaml"), "utf-8");
+    assert.match(content, /merged ON TOP of spf's packaged built-in defaults/);
+    assert.match(content, /^# quality:/m); // every real section stays commented out
+    assert.doesNotMatch(content, /^defaults:/m);
+});
+test("plain `spf init` (no TTY in a test process) falls through to the same starter config as --yes", async () => {
+    const code = await initCommand(["--cwd", dir]);
+    assert.equal(code, 0);
+    const content = readFileSync(join(dir, ".spf", "spf.config.yaml"), "utf-8");
+    assert.match(content, /merged ON TOP of spf's packaged built-in defaults/);
+});
+test("--template writes the named template as-is, skipping the interview even without --yes", async () => {
+    const code = await initCommand(["--cwd", dir, "--template", "ts-cc"]);
+    assert.equal(code, 0);
+    const content = readFileSync(join(dir, ".spf", "spf.config.yaml"), "utf-8");
+    assert.match(content, /Claude Code backend, pointed at Ollama/);
+});
+test("an existing config is left alone without --force, even for --yes", async () => {
+    await initCommand(["--cwd", dir, "--yes"]);
+    const before = readFileSync(join(dir, ".spf", "spf.config.yaml"), "utf-8");
+    const code = await initCommand(["--cwd", dir, "--template", "ts-cc"]); // no --force
+    assert.equal(code, 0);
+    assert.equal(readFileSync(join(dir, ".spf", "spf.config.yaml"), "utf-8"), before);
+});
+test("--force overwrites an existing config non-interactively", async () => {
+    await initCommand(["--cwd", dir, "--yes"]);
+    await initCommand(["--cwd", dir, "--template", "ts-cc", "--force"]);
+    const content = readFileSync(join(dir, ".spf", "spf.config.yaml"), "utf-8");
+    assert.match(content, /Claude Code backend, pointed at Ollama/);
+});
+test("never writes .env or .env.example on the non-interactive paths", async () => {
+    await initCommand(["--cwd", dir, "--yes"]);
+    assert.equal(existsSync(join(dir, ".env")), false);
+    assert.equal(existsSync(join(dir, ".env.example")), false);
+});

package/dist/test/interview.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/interview.test.js

@@ -0,0 +1,179 @@
+/**
+ * `spf init`'s interactive interview (`cli/interview.ts`) — driven through
+ * the `Asker` seam with a scripted fake (`./fake_asker.ts`), never a real
+ * TTY. Covers the three things a wrong answer would actually break:
+ *   1. the pinned-roster trap (planner/reviewer/documenter overridden
+ *      whenever the backend switches to claude_code — see agent_cc.ts/
+ *      agents.ts's back-fill comment),
+ *   2. the generated config is a genuine override — validating it requires
+ *      merging with the packaged built-in roster first, exactly like
+ *      `spf doctor` does, never the raw document alone,
+ *   3. each `spf watch` combination collects exactly the credentials
+ *      `cli/commands/watch.ts`'s resolveIssueProvider/resolveCodeHostProvider
+ *      actually read — no more, no less.
+ */
+import { test, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { runInterview, gatherContext } from "../cli/interview.js";
+import { loadConfig, validate } from "../core/agents.js";
+import { BUILTIN_CONFIG_PATH } from "../core/paths.js";
+import { createFakeAsker } from "./fake_asker.js";
+let dir;
+before(() => {
+    dir = mkdtempSync(join(tmpdir(), "spf-interview-test-"));
+    execFileSync("git", ["init", "-q"], { cwd: dir });
+    execFileSync("git", ["remote", "add", "origin", "https://github.com/acme/widgets.git"], { cwd: dir });
+    // -c user.*, not a global git config: this must pass in a fresh CI runner
+    // with no git identity configured at all (same reasoning as ui_server.test.ts).
+    execFileSync("git", ["-c", "user.email=test@example.com", "-c", "user.name=spf tests", "commit", "-q", "--allow-empty", "-m", "init"], { cwd: dir });
+});
+after(() => {
+    rmSync(dir, { recursive: true, force: true });
+});
+/** Merge with the real packaged roster and validate — the same pipeline `spf doctor` runs, and the only honest way to check a partial override document. */
+function mergedConfigPath() {
+    const configPath = join(dir, `spf.config.${Math.random().toString(36).slice(2)}.yaml`);
+    return configPath;
+}
+test("claude_code + watch(github/github): overrides the three pinned agents and merges cleanly", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: {
+            "backend runs": "claude_code",
+            "Model (Claude": "sonnet",
+            Authentication: "login",
+            "Issue tracker": "github",
+            "Code host": "github",
+            "Chain to run": "plan-build-test",
+        },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": true,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+        secret: { GITHUB_TOKEN: "ghp_abcdefghijklmnop" },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.defaults.coding_agent, "claude_code");
+    assert.equal(config.defaults.model, "sonnet");
+    const overrides = config.agents;
+    assert.deepEqual(overrides.map((a) => a.name).sort(), ["documenter", "planner", "reviewer"]);
+    for (const a of overrides)
+        assert.equal(a.model, "sonnet");
+    assert.equal(config.watch.repo, "acme/widgets"); // detected from origin
+    assert.equal(result.env.GITHUB_TOKEN, "ghp_abcdefghijklmnop");
+    assert.ok(result.envExampleKeys.includes("GITHUB_TOKEN"));
+    const configPath = mergedConfigPath();
+    const { stringify } = await import("yaml");
+    writeFileSync(configPath, stringify(config));
+    const cfg = loadConfig([BUILTIN_CONFIG_PATH, configPath]);
+    assert.equal(cfg.defaults.coding_agent, "claude_code");
+    assert.equal(cfg.agents.find((a) => a.name === "planner").model, "sonnet");
+    assert.equal(cfg.agents.find((a) => a.name === "builder").model, "sonnet"); // inherits defaults.model, needed no override
+    validate(cfg, cfg.agents.map((a) => a.name), Object.keys(cfg.quality.suites), dir); // throws on any problem
+});
+test("flue + openrouter: no pinned-agent overrides needed, provider key collected", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: { "backend runs": "flue", Provider: "openrouter" },
+        text: { "Model id": "moonshotai/kimi-k2.7" },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": false,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+        secret: { OPENROUTER_API_KEY: "sk-or-v1-test" },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.defaults.coding_agent, "flue");
+    assert.equal(config.defaults.model, "openrouter/moonshotai/kimi-k2.7");
+    assert.equal(config.agents, undefined, "flue never needs the pinned-roster fix — agents' own models are already valid Flue ids");
+    assert.equal(result.env.OPENROUTER_API_KEY, "sk-or-v1-test");
+    assert.ok(!("watch" in config));
+});
+test("watch(jira/bitbucket): collects exactly JIRA_* + BITBUCKET_*, never GITHUB_TOKEN", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({
+        select: {
+            "backend runs": "claude_code",
+            "Model (Claude": "sonnet",
+            Authentication: "login",
+            "Issue tracker": "jira",
+            "Code host": "bitbucket",
+            "Chain to run": "plan-build-test",
+        },
+        text: {
+            "Repo (workspace/repo_slug)": "acme/widgets-repo",
+            "Jira base URL": "https://acme.atlassian.net/",
+            "Jira project key": "proj",
+        },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": true,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+        secret: { JIRA_API_TOKEN: "jira-token", BITBUCKET_API_TOKEN: "bb-token" },
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    const config = result.config;
+    assert.equal(config.watch.issue_provider, "jira");
+    assert.equal(config.watch.code_host, "bitbucket");
+    assert.equal(config.watch.jira.base_url, "https://acme.atlassian.net"); // trailing slash stripped
+    assert.equal(config.watch.jira.project_key, "PROJ"); // upper-cased
+    assert.equal(result.env.JIRA_API_TOKEN, "jira-token");
+    assert.equal(result.env.BITBUCKET_API_TOKEN, "bb-token");
+    assert.equal(result.env.GITHUB_TOKEN, undefined, "neither provider needs GitHub — must not ask for or write GITHUB_TOKEN");
+});
+test("declining the final confirm returns null — nothing to write", async () => {
+    const ctx = gatherContext(dir, new Map());
+    const asker = createFakeAsker({ defaultConfirm: false }); // every confirm, including the final one, says no
+    const result = await runInterview(asker, ctx);
+    assert.equal(result, null);
+});
+test("an existing .env value is offered back as the default when a secret is left blank", async () => {
+    const ctx = gatherContext(dir, new Map([["GITHUB_TOKEN", "ghp_existingvalue"]]));
+    const asker = createFakeAsker({
+        select: {
+            "backend runs": "claude_code",
+            "Model (Claude": "sonnet",
+            Authentication: "login",
+            "Issue tracker": "github",
+            "Code host": "github",
+            "Chain to run": "plan-build-test",
+        },
+        confirm: {
+            'Add a "typecheck"': false,
+            'Add a "lint"': false,
+            'Add a "build"': false,
+            'Add a "test"': false,
+            "Enable spf watch": true,
+            "Configure advanced": false,
+            "Write .spf": true,
+        },
+        // no GITHUB_TOKEN entry in `secret` — the fake leaves it blank, same as a real user hitting Enter to keep the current value
+    });
+    const result = await runInterview(asker, ctx);
+    assert.ok(result);
+    assert.equal(result.env.GITHUB_TOKEN, undefined, "a blank secret answer must not overwrite the existing value with empty");
+});

package/dist/test/ui_server.test.js

@@ -25,7 +25,7 @@ before(async () => {
     execFileSync("git", ["-c", "user.email=test@example.com", "-c", "user.name=spf tests", "commit", "-q", "--allow-empty", "-m", "init"], { cwd: dir });
     const dbPath = join(dir, "spf.db");
     const tracer = new Tracer(dbPath, join(dir, "sessions", ADW_ID, "events.jsonl"));
-    tracer.sessionStart(ADW_ID, "tester", "adw_quality");
+    tracer.sessionStart(ADW_ID, "tester", "quality");
     const phase = {
         phase_id: `${ADW_ID}_01_request`,
         adw_id: ADW_ID,

package/dist/test/watch.test.js

@@ -1,5 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
+import path from "node:path";
 import { branchNameFor, claimNewWork, createWatchState, finishReviews, reconcileOrphans } from "../core/watch.js";
 /** In-memory fake — exactly the seam `provider.ts` exists for. */
 class FakeProvider {
@@ -91,6 +92,7 @@ function makeDeps(provider, codeHost, overrides = {}) {
         baseBranch: "main",
         concurrency: 2,
         worktreesDir: "/tmp/spf-watch-test-worktrees",
+        linkDataDir: () => { },
         dryRun: false,
         runChain: async () => ({ accepted: true, adwId: "issue-1", detail: "" }),
         log: () => { },
@@ -110,12 +112,45 @@ test("branchNameFor: sanitizes a title into a safe branch name", () => {
     assert.equal(branchNameFor({ id: "7", title: "", body: "", labels: [] }), "spf-watch/7-issue");
     assert.equal(branchNameFor({ id: "PROJ-123", title: "Fix the thing", body: "", labels: [] }), "spf-watch/PROJ-123-fix-the-thing");
 });
+test("claimNewWork: clears a stale worktree/branch from a killed prior attempt before creating a fresh one", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("2", "Retry me");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const calls = [];
+    // Simulates a `spf watch` process killed mid-run for this exact issue: a
+    // real `git.worktreeAdd` would refuse outright with "fatal: a branch
+    // named '...' already exists" until the leftover branch is cleared.
+    let branchExists = true;
+    const deps = makeDeps(provider, codeHost, {
+        git: fakeGit({
+            worktreeRemove: (p) => calls.push(`remove:${p}`),
+            deleteLocalBranch: (n) => {
+                calls.push(`delete-branch:${n}`);
+                branchExists = false;
+            },
+            worktreeAdd: (p, b) => {
+                if (branchExists)
+                    throw new Error(`fatal: a branch named '${b}' already exists`);
+                calls.push(`add:${p}`);
+            },
+        }),
+    });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    const branchIdx = calls.findIndex((c) => c.startsWith("delete-branch:"));
+    const addIdx = calls.findIndex((c) => c.startsWith("add:"));
+    assert.ok(branchIdx !== -1 && addIdx !== -1 && branchIdx < addIdx, `expected the stale branch cleared before worktreeAdd, got: ${calls.join(", ")}`);
+    // The retry then succeeds normally, same as any other claim.
+    assert.deepEqual(provider.transitions.map((t) => t.to), ["review"]);
+});
 test("claimNewWork: claims a ready issue, runs the chain, opens a PR, and moves to review", async () => {
     const provider = new FakeProvider();
     provider.addIssue("1", "Add a /health endpoint");
     const codeHost = new FakeCodeHost();
     const state = createWatchState();
-    const deps = makeDeps(provider, codeHost);
+    const linkedWorktrees = [];
+    const deps = makeDeps(provider, codeHost, { linkDataDir: (worktreePath) => linkedWorktrees.push(worktreePath) });
     await claimNewWork(deps, state);
     await waitUntil(() => state.inflight.size === 0);
     assert.deepEqual(provider.claimCalls, ["1"]);
@@ -123,6 +158,11 @@ test("claimNewWork: claims a ready issue, runs the chain, opens a PR, and moves
     assert.match(codeHost.openedPrs[0].title, /^Add a \/health endpoint \(1\)/);
     assert.deepEqual(provider.transitions.map((t) => t.to), ["review"]);
     assert.equal(provider.entries.get("1").marker?.pr, 1000);
+    // linkDataDir must run before the chain does — otherwise the run's own
+    // session/trace data resolves into the worktree's throwaway .spf/data
+    // instead of the main repo's persistent one (invisible in spf ui, and
+    // deleted along with the worktree on cleanup).
+    assert.deepEqual(linkedWorktrees, [path.join(deps.worktreesDir, "issue-1")]);
 });
 test("claimNewWork: a rejected chain run blocks the issue with the failure detail", async () => {
     const provider = new FakeProvider();

package/dist/ui/shared/types.d.ts

@@ -15,7 +15,7 @@ export type PhaseKind = "engineer" | "code" | "agent";
 export type EventType = "phase_start" | "phase_end" | "agent_start" | "agent_end" | "tool_call" | "handoff" | "gate_pass" | "gate_fail" | "log" | "error";
 export interface Session {
     adw_id: string;
-    /** ADW script(s) that ran this session, e.g. "adw_plan + adw_build_test". */
+    /** Chain(s) that ran this session, e.g. "plan + build-test". */
     adw_name: string | null;
     request: string | null;
     status: SessionStatus | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",
@@ -38,7 +38,10 @@
     "pretest": "npm run build:cli",
     "test": "node --test \"dist/**/*.test.js\"",
     "prepack": "node scripts/check-pack-ready.js",
-    "size-check": "node scripts/check-tarball-size.js"
+    "size-check": "node scripts/check-tarball-size.js",
+    "tag:major": "node scripts/tag-release.js major",
+    "tag:minor": "node scripts/tag-release.js minor",
+    "tag:patch": "node scripts/tag-release.js patch"
   },
   "dependencies": {
     "@flue/runtime": "2.0.3",

package/dist/chains/adw_build.d.ts

@@ -1,12 +0,0 @@
-/**
- * ADW Build — one-shot implementation workflow.
- *
- * Usage:
- *   spf build "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
- *
- * Phases: engineer(request) -> builder
- */
-import type { ChainContext } from "./context.ts";
-export declare const REQUIRED_AGENTS: string[];
-export declare const REQUIRED_SUITES: string[];
-export declare function main(ctx: ChainContext): Promise<number>;

package/dist/chains/adw_build.js

@@ -1,27 +0,0 @@
-/**
- * ADW Build — one-shot implementation workflow.
- *
- * Usage:
- *   spf build "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
- *
- * Phases: engineer(request) -> builder
- */
-import * as agents from "../core/agents.js";
-import * as gates from "../core/gates.js";
-import * as session from "../core/session.js";
-import { BuildOutput, makeAgentCall, makePhaseParams } from "../core/data_types.js";
-export const REQUIRED_AGENTS = ["builder"];
-export const REQUIRED_SUITES = [];
-export async function main(ctx) {
-    const { prompt, config_paths, adw_id, cwd } = ctx;
-    const cfg = agents.loadConfig(config_paths);
-    agents.validate(cfg, REQUIRED_AGENTS, REQUIRED_SUITES, cwd);
-    const run = session.ensure(cfg, adw_id, cwd);
-    await run.phase(makePhaseParams({ name: "request", kind: "engineer", owner: run.engineer, description: "Capture the incoming ask" }), async (ph) => {
-        ph.log({ input: prompt });
-    });
-    await run.phase(makePhaseParams({ name: "build", kind: "agent", owner: "builder", retries: 1, description: "Implement the request" }), async (ph) => {
-        await ph.call(makeAgentCall({ output_type: BuildOutput, prompt, gates: [gates.diffMatchesClaims] }));
-    });
-    return run.finish();
-}

package/dist/chains/adw_build_review.d.ts

@@ -1,21 +0,0 @@
-/**
- * ADW Build Review — implement, then confirm it is what was asked for.
- *
- * Usage:
- *   spf build-review "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id a1b2c3d4]
- *
- * Phases: engineer(request) -> builder -> reviewer [-> builder(revise) -> reviewer ... bounded]
- *
- * Review is not testing. Tests answer "does it run"; the reviewer answers "is this
- * the thing that was asked for" — it reads the spec (`plan.md` from a prior plan
- * phase if the session has one, else the prompt verbatim), reads the code that was
- * written, and rules on each requirement.
- *
- * Like the tester, the reviewer's phase succeeds when it RUNS and REPORTS. A
- * rejection does not fail the phase; it fails the run, checked at the end, after
- * the bounded revise loop has had its chances.
- */
-import type { ChainContext } from "./context.ts";
-export declare const REQUIRED_AGENTS: string[];
-export declare const REQUIRED_SUITES: string[];
-export declare function main(ctx: ChainContext): Promise<number>;