@gr8ful/spf 0.2.1 → 0.4.0

package/dist/test/notify.test.js

@@ -0,0 +1,174 @@
+/**
+ * The notifier: the `events` filter matrix, per-channel scope override, a
+ * real webhook POST against a local `node:http` receiver (not a `fetch`
+ * mock — proves the actual bytes on the wire), a rejecting channel never
+ * propagating, `flush()` actually awaiting pending sends, and an unset env
+ * var degrading to a warning instead of a crash.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import * as v from "valibot";
+import { Notifier, resolveNotifier, DEFAULT_NOTIFY_ENV_KEY } from "../core/notify/notifier.js";
+import { SFConfigSchema } from "../core/data_types.js";
+function baseConfig(overrides = {}) {
+    return v.parse(SFConfigSchema, { notifications: { events: "errors", channels: [], ...overrides } });
+}
+function infoEvent() {
+    return { kind: "run_started", level: "info", title: "run started", fields: [] };
+}
+function errorEvent() {
+    return { kind: "run_failed", level: "error", title: "run failed", fields: [] };
+}
+class RecordingChannel {
+    received = [];
+    label = "recording";
+    async send(event) {
+        this.received.push(event);
+    }
+}
+class RejectingChannel {
+    label = "rejecting";
+    async send() {
+        throw new Error("boom");
+    }
+}
+class BlockedChannel {
+    label = "blocked";
+    release;
+    gate = new Promise((resolve) => (this.release = resolve));
+    async send() {
+        await this.gate;
+    }
+}
+test("events: off never sends, regardless of level", () => {
+    const channel = new RecordingChannel();
+    const notifier = new Notifier([{ channel, scope: "off" }], 1000, false, () => { });
+    notifier.send(infoEvent());
+    notifier.send(errorEvent());
+    assert.deepEqual(channel.received, []);
+});
+test("events: errors sends only level=error", () => {
+    const channel = new RecordingChannel();
+    const notifier = new Notifier([{ channel, scope: "errors" }], 1000, false, () => { });
+    notifier.send(infoEvent());
+    notifier.send(errorEvent());
+    assert.equal(channel.received.length, 1);
+    assert.equal(channel.received[0].level, "error");
+});
+test("events: all sends both info and error", () => {
+    const channel = new RecordingChannel();
+    const notifier = new Notifier([{ channel, scope: "all" }], 1000, false, () => { });
+    notifier.send(infoEvent());
+    notifier.send(errorEvent());
+    assert.equal(channel.received.length, 2);
+});
+test("a per-channel scope overrides the top-level scope", () => {
+    const loud = new RecordingChannel();
+    const quiet = new RecordingChannel();
+    const notifier = new Notifier([
+        { channel: loud, scope: "all" },
+        { channel: quiet, scope: "errors" },
+    ], 1000, false, () => { });
+    notifier.send(infoEvent());
+    assert.equal(loud.received.length, 1);
+    assert.equal(quiet.received.length, 0);
+});
+test("dry-run logs and sends nothing to any channel", () => {
+    const channel = new RecordingChannel();
+    const logs = [];
+    const notifier = new Notifier([{ channel, scope: "all" }], 1000, true, (m) => logs.push(m));
+    notifier.send(infoEvent());
+    assert.deepEqual(channel.received, []);
+    assert.equal(logs.length, 1);
+    assert.match(logs[0], /would notify/);
+});
+test("a rejecting channel logs one line and never throws or blocks other channels", async () => {
+    const rejecting = new RejectingChannel();
+    const ok = new RecordingChannel();
+    const logs = [];
+    const notifier = new Notifier([
+        { channel: rejecting, scope: "all" },
+        { channel: ok, scope: "all" },
+    ], 1000, false, (m) => logs.push(m));
+    assert.doesNotThrow(() => notifier.send(infoEvent()));
+    await notifier.flush();
+    assert.equal(ok.received.length, 1);
+    assert.equal(logs.length, 1);
+    assert.match(logs[0], /rejecting notification failed: boom/);
+});
+test("flush() actually awaits pending sends before returning", async () => {
+    const blocked = new BlockedChannel();
+    const notifier = new Notifier([{ channel: blocked, scope: "all" }], 1000, false, () => { });
+    notifier.send(infoEvent());
+    let flushed = false;
+    const flushPromise = notifier.flush().then(() => {
+        flushed = true;
+    });
+    await new Promise((r) => setTimeout(r, 20));
+    assert.equal(flushed, false, "flush must not resolve before the pending send does");
+    blocked.release();
+    await flushPromise;
+    assert.equal(flushed, true);
+});
+test("resolveNotifier returns null when events is off", () => {
+    const cfg = baseConfig({ events: "off", channels: [{ kind: "webhook", webhook_url_env: "SPF_TEST_WEBHOOK" }] });
+    assert.equal(resolveNotifier(cfg), null);
+});
+test("resolveNotifier returns null when no channels are configured", () => {
+    const cfg = baseConfig({ events: "all", channels: [] });
+    assert.equal(resolveNotifier(cfg), null);
+});
+test("resolveNotifier skips a channel whose env var is unset, with one warning naming the key — never throws", () => {
+    delete process.env["SPF_TEST_WEBHOOK_UNSET"];
+    const cfg = baseConfig({ events: "all", channels: [{ kind: "webhook", webhook_url_env: "SPF_TEST_WEBHOOK_UNSET" }] });
+    const logs = [];
+    const notifier = resolveNotifier(cfg, { log: (m) => logs.push(m) });
+    assert.equal(notifier, null);
+    assert.equal(logs.length, 1);
+    assert.match(logs[0], /SPF_TEST_WEBHOOK_UNSET is not set/);
+});
+test("resolveNotifier falls back to the kind's default env key when webhook_url_env is empty", () => {
+    process.env["SLACK_WEBHOOK_URL"] = "http://127.0.0.1:1/unused";
+    try {
+        const cfg = baseConfig({ events: "all", channels: [{ kind: "slack" }] });
+        const notifier = resolveNotifier(cfg);
+        assert.notEqual(notifier, null);
+        assert.equal(DEFAULT_NOTIFY_ENV_KEY["slack"], "SLACK_WEBHOOK_URL");
+    }
+    finally {
+        delete process.env["SLACK_WEBHOOK_URL"];
+    }
+});
+test("a webhook channel posts the real NotifyEvent JSON over the wire to a local receiver", async () => {
+    let receivedBody = "";
+    let receivedContentType = "";
+    const server = createServer((req, res) => {
+        receivedContentType = req.headers["content-type"] ?? "";
+        let body = "";
+        req.on("data", (chunk) => (body += chunk));
+        req.on("end", () => {
+            receivedBody = body;
+            res.writeHead(200);
+            res.end("ok");
+        });
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const port = server.address().port;
+    const envKey = "SPF_TEST_WEBHOOK_LIVE";
+    process.env[envKey] = `http://127.0.0.1:${port}/hook`;
+    try {
+        const cfg = baseConfig({ events: "all", channels: [{ kind: "webhook", webhook_url_env: envKey }] });
+        const notifier = resolveNotifier(cfg);
+        assert.notEqual(notifier, null);
+        const event = { kind: "issue_claimed", level: "info", title: "issue 42 claimed", fields: [["issue", "42"]] };
+        notifier.send(event);
+        await notifier.flush();
+        assert.equal(receivedContentType, "application/json");
+        assert.deepEqual(JSON.parse(receivedBody), event);
+    }
+    finally {
+        delete process.env[envKey];
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+});

package/dist/test/refine.test.d.ts

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

package/dist/test/refine.test.js

@@ -0,0 +1,126 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { publish } from "../core/refine.js";
+import { refinementWellFormed } from "../core/gates.js";
+/** In-memory fake — exactly the seam `IssueAuthoringProvider` exists for. */
+class FakeTracker {
+    created = [];
+    links = [];
+    nextId = 1;
+    async createIssue(input) {
+        this.created.push(input);
+        const id = String(this.nextId++);
+        return { id, internal_id: `db-${id}`, title: input.title, body: input.body, labels: input.labels };
+    }
+    async linkChild(parent, child) {
+        this.links.push({ parent: parent.id, child: child.id });
+    }
+}
+function node(overrides) {
+    return { body: "", parent: "", blocked_by: [], ...overrides };
+}
+// ── publish() ────────────────────────────────────────────────────────────
+test("publish: creates a container before its children, and links them via linkChild", async () => {
+    const tracker = new FakeTracker();
+    const issues = [
+        node({ key: "S1", kind: "story", title: "Owner invites by email", parent: "F1" }),
+        node({ key: "F1", kind: "feature", title: "Team invitations" }),
+    ];
+    const created = await publish(tracker, issues, { labelPrefix: "spf" });
+    assert.deepEqual(tracker.created.map((c) => c.title), ["Team invitations", "Owner invites by email"], "the parent must be created before its child");
+    assert.deepEqual(tracker.links, [{ parent: "1", child: "2" }]);
+    assert.deepEqual(created.map((c) => ({ key: c.key, isLeaf: c.isLeaf })), [
+        { key: "F1", isLeaf: false },
+        { key: "S1", isLeaf: true },
+    ]);
+});
+test("publish: labels a leaf with its type AND spf:refined; a container gets only its type label", async () => {
+    const tracker = new FakeTracker();
+    const issues = [node({ key: "F1", kind: "feature", title: "A feature" }), node({ key: "S1", kind: "story", title: "A leaf", parent: "F1" })];
+    await publish(tracker, issues, { labelPrefix: "spf" });
+    const feature = tracker.created.find((c) => c.title === "A feature");
+    const leaf = tracker.created.find((c) => c.title === "A leaf");
+    assert.deepEqual(feature.labels, ["spf:type:feature"]);
+    assert.deepEqual(leaf.labels, ["spf:type:story", "spf:refined"]);
+});
+test("publish: creates a blocker before what it blocks, and renders a real #n reference in the body", async () => {
+    const tracker = new FakeTracker();
+    const issues = [
+        node({ key: "S2", kind: "bug", title: "Fix the expiry check", blocked_by: ["S1"] }),
+        node({ key: "S1", kind: "story", title: "Owner invites by email" }),
+    ];
+    const created = await publish(tracker, issues, { labelPrefix: "spf" });
+    const s1Id = created.find((c) => c.key === "S1").issue.id;
+    const s2 = tracker.created.find((c) => c.title === "Fix the expiry check");
+    assert.equal(created[0].key, "S1", "the blocker publishes first");
+    assert.match(s2.body, new RegExp(`## Blocked by\\n\\n- #${s1Id}`));
+});
+test("publish: a leaf with no blockers gets the 'None (can start immediately)' text", async () => {
+    const tracker = new FakeTracker();
+    const created = await publish(tracker, [node({ key: "S1", kind: "story", title: "A leaf" })], { labelPrefix: "spf" });
+    assert.match(created[0].issue.body, /## Blocked by\n\nNone \(can start immediately\)\./);
+});
+test("publish: renders '## Parent: #<id>' when a spec issue id is given, and omits it otherwise", async () => {
+    const tracker = new FakeTracker();
+    const withSpec = await publish(tracker, [node({ key: "S1", kind: "story", title: "A leaf" })], { labelPrefix: "spf", specIssueId: "42" });
+    assert.match(withSpec[0].issue.body, /## Parent\n\nDecomposed from #42\./);
+    const tracker2 = new FakeTracker();
+    const withoutSpec = await publish(tracker2, [node({ key: "S1", kind: "story", title: "A leaf" })], { labelPrefix: "spf" });
+    assert.doesNotMatch(withoutSpec[0].issue.body, /## Parent/);
+});
+// ── gates.refinementWellFormed ───────────────────────────────────────────
+function envelope(issues) {
+    return { status: "success", summary: "", artifacts: [], notes_for_next_agent: "", issues };
+}
+test("refinementWellFormed: an empty issues list fails", () => {
+    const report = refinementWellFormed(envelope([]), { repo_root: "/repo" });
+    assert.equal(report.passed, false);
+});
+test("refinementWellFormed: a well-formed feature/story tree with no blockers passes clean", () => {
+    const report = refinementWellFormed(envelope([node({ key: "F1", kind: "feature", title: "A feature" }), node({ key: "S1", kind: "story", title: "A leaf", parent: "F1" })]), { repo_root: "/repo" });
+    assert.equal(report.passed, true);
+});
+test("refinementWellFormed: a container mislabeled as a leaf kind fails", () => {
+    const report = refinementWellFormed(envelope([node({ key: "F1", kind: "story", title: "Should be a feature" }), node({ key: "S1", kind: "story", title: "A leaf", parent: "F1" })]), { repo_root: "/repo" });
+    assert.equal(report.passed, false);
+    assert.ok(report.violations.some((v) => v.includes("F1.kind")));
+});
+test("refinementWellFormed: a two-node parent cycle has no leaves AND fails the dependency-graph check", () => {
+    // A finite, ACYCLIC parent forest always has at least one leaf by
+    // construction (some node's children set is empty) — the only way to
+    // drive leafCount to zero is a cycle, which the dependency-graph check
+    // already independently rejects. This test exercises that overlap
+    // directly rather than asserting an "all containers, no leaves" shape
+    // that isn't otherwise reachable.
+    const report = refinementWellFormed(envelope([node({ key: "F1", kind: "feature", title: "A", parent: "F2" }), node({ key: "F2", kind: "feature", title: "B", parent: "F1" })]), { repo_root: "/repo" });
+    assert.equal(report.passed, false);
+    assert.ok(report.violations.some((v) => v.toLowerCase().includes("cycle")));
+    assert.ok(report.violations.some((v) => v.toLowerCase().includes("leaves")));
+});
+test("refinementWellFormed: an unresolved parent key fails", () => {
+    const report = refinementWellFormed(envelope([node({ key: "S1", kind: "story", title: "Orphaned", parent: "nonexistent" })]), {
+        repo_root: "/repo",
+    });
+    assert.equal(report.passed, false);
+    assert.ok(report.violations.some((v) => v.includes("parent")));
+});
+test("refinementWellFormed: an unresolved blocked_by key fails", () => {
+    const report = refinementWellFormed(envelope([node({ key: "S1", kind: "story", title: "A leaf", blocked_by: ["nonexistent"] })]), {
+        repo_root: "/repo",
+    });
+    assert.equal(report.passed, false);
+    assert.ok(report.violations.some((v) => v.includes("blocked_by")));
+});
+test("refinementWellFormed: a blocked_by cycle fails", () => {
+    const report = refinementWellFormed(envelope([
+        node({ key: "S1", kind: "story", title: "A", blocked_by: ["S2"] }),
+        node({ key: "S2", kind: "story", title: "B", blocked_by: ["S1"] }),
+    ]), { repo_root: "/repo" });
+    assert.equal(report.passed, false);
+    assert.ok(report.violations.some((v) => v.toLowerCase().includes("cycle")));
+});
+test("refinementWellFormed: duplicate keys fail", () => {
+    const report = refinementWellFormed(envelope([node({ key: "S1", kind: "story", title: "A" }), node({ key: "S1", kind: "bug", title: "B" })]), { repo_root: "/repo" });
+    assert.equal(report.passed, false);
+    assert.ok(report.violations.some((v) => v.includes("duplicate")));
+});

package/dist/test/watch.test.js

@@ -1,7 +1,7 @@
 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";
+import { branchNameFor, claimNewWork, claimSpecs, createWatchState, finishReviews, reconcileOrphans, reconcileRefining, refineBranchNameFor, tick, } from "../core/watch.js";
 /** In-memory fake — exactly the seam `provider.ts` exists for. */
 class FakeProvider {
     entries = new Map();
@@ -21,19 +21,21 @@ class FakeProvider {
     async listInState(state) {
         return [...this.entries.values()].filter((e) => e.state === state).map((e) => e.issue);
     }
-    async claim(issue) {
+    async claim(issue, opts) {
         this.claimCalls.push(issue.id);
         const entry = this.entries.get(issue.id);
-        if (entry.state !== "ready")
+        const from = opts?.from ?? "ready";
+        const to = opts?.to ?? "working";
+        if (entry.state !== from)
             return false;
-        entry.state = "working";
+        entry.state = to;
         return true;
     }
     async transition(issue, to, detail) {
         this.entries.get(issue.id).state = to;
         this.transitions.push({ id: issue.id, to, detail });
     }
-    async comment() { }
+    async comment(_issue, _body) { }
     async readMarker(issue) {
         return this.entries.get(issue.id)?.marker ?? null;
     }
@@ -91,14 +93,26 @@ function makeDeps(provider, codeHost, overrides = {}) {
         chain: "plan-build-test",
         baseBranch: "main",
         concurrency: 2,
+        // Off by default, like WatchRefineConfigSchema itself — a test that
+        // doesn't override these never touches the refine lane at all.
+        refineEnabled: false,
+        refineConcurrency: 1,
+        refineChain: "refine",
+        runRefine: async (opts) => ({ accepted: true, adwId: opts.adwId, detail: "", created: [] }),
         worktreesDir: "/tmp/spf-watch-test-worktrees",
         linkDataDir: () => { },
         dryRun: false,
         runChain: async () => ({ accepted: true, adwId: "issue-1", detail: "" }),
         log: () => { },
+        notify: () => { },
         ...overrides,
     };
 }
+/** Collects every `deps.notify(...)` call, for asserting kinds/levels without a real channel. */
+function collectNotifications() {
+    const events = [];
+    return { events, notify: (event) => events.push(event) };
+}
 async function waitUntil(predicate, timeoutMs = 2000) {
     const start = Date.now();
     while (!predicate()) {
@@ -281,3 +295,270 @@ test("finishReviews: a still-open PR leaves the issue in review", async () => {
     assert.equal(provider.transitions.length, 0);
     assert.equal(provider.entries.get("42").state, "review");
 });
+// ── notifications ────────────────────────────────────────────────────────────
+test("claim -> PR opened -> merged fires issue_claimed, pr_opened, then issue_done (all info-level)", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("50", "Add a /health endpoint");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, { notify });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.deepEqual(events.map((e) => e.kind), ["issue_claimed", "pr_opened"]);
+    assert.ok(events.every((e) => e.level === "info"));
+    codeHost.prs.set(1000, { merged: true, state: "closed", ciStatus: "success" });
+    await finishReviews(deps);
+    assert.deepEqual(events.map((e) => e.kind), ["issue_claimed", "pr_opened", "issue_done"]);
+    assert.equal(events.at(-1).level, "info");
+});
+test("a rejected chain run fires issue_blocked at error level", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("51", "Flaky feature");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, {
+        notify,
+        runChain: async () => ({ accepted: false, adwId: "issue-51", detail: "build-test failed" }),
+    });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    const blocked = events.filter((e) => e.kind === "issue_blocked");
+    assert.equal(blocked.length, 1);
+    assert.equal(blocked[0].level, "error");
+    assert.equal(blocked[0].detail, "build-test failed");
+});
+test("an accepted run with nothing committed fires issue_blocked", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("52", "No-op request");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, { notify, worktreeGit: () => fakeGit({ diffFiles: () => [] }) });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    assert.deepEqual(events.map((e) => e.kind), ["issue_claimed", "issue_blocked"]);
+    assert.match(events[1].detail ?? "", /no committed changes/);
+});
+test("an exception mid-runIssue fires watch_error at error level", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("53", "Explodes");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, {
+        notify,
+        runChain: async () => {
+            throw new Error("kaboom");
+        },
+    });
+    await claimNewWork(deps, state);
+    await waitUntil(() => state.inflight.size === 0);
+    const errors = events.filter((e) => e.kind === "watch_error");
+    assert.equal(errors.length, 1);
+    assert.equal(errors[0].level, "error");
+    assert.match(errors[0].detail ?? "", /kaboom/);
+});
+test("finishReviews: a closed-without-merging PR fires issue_blocked", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("54", "rejected", "review", { pr: 700, branch: "spf-watch/54-x" });
+    const codeHost = new FakeCodeHost();
+    codeHost.prs.set(700, { merged: false, state: "closed", ciStatus: "failure" });
+    const { events, notify } = collectNotifications();
+    await finishReviews(makeDeps(provider, codeHost, { notify }));
+    assert.deepEqual(events.map((e) => e.kind), ["issue_blocked"]);
+    assert.equal(events[0].level, "error");
+});
+test("reconcileOrphans: giving up past the retry cap fires issue_blocked", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("55", "orphaned, no marker", "working", { attempt: 2 }); // one more push exceeds MAX_ORPHAN_ATTEMPTS (2)
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    await reconcileOrphans(makeDeps(provider, codeHost, { notify }), state);
+    assert.deepEqual(events.map((e) => e.kind), ["issue_blocked"]);
+    assert.match(events[0].detail ?? "", /Gave up after 2 orphaned attempts/);
+});
+test("reconcileOrphans: a routine orphan resume/retry notifies nothing — only the terminal give-up does", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("56", "orphaned, resumable", "working", { pr: 800, branch: "spf-watch/56-x" });
+    const codeHost = new FakeCodeHost();
+    codeHost.prs.set(800, { merged: false, state: "open", ciStatus: "pending" });
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    await reconcileOrphans(makeDeps(provider, codeHost, { notify }), state);
+    assert.deepEqual(events, []);
+});
+// ── the refine lane ──────────────────────────────────────────────────────
+test("refineBranchNameFor: same sanitizer as branchNameFor, different prefix", () => {
+    assert.equal(refineBranchNameFor({ id: "9", title: "Team invitations spec", body: "", labels: [] }), "spf-refine/9-team-invitations-spec");
+});
+test("claimSpecs: a disabled refine lane never lists spec-ready issues or claims anything", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("100", "A spec", "spec-ready");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    provider.listInState = async () => {
+        throw new Error("listInState should never be called when refineEnabled is false");
+    };
+    await claimSpecs(makeDeps(provider, codeHost, { refineEnabled: false }), state);
+    assert.equal(provider.claimCalls.length, 0);
+});
+test("claimSpecs: claims a spec-ready spec, publishes, and finishes it to done with a summary comment", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("101", "Team invitations", "spec-ready");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const comments = [];
+    provider.comment = async (issue, body) => {
+        comments.push({ id: issue.id, body });
+    };
+    const deps = makeDeps(provider, codeHost, {
+        refineEnabled: true,
+        runRefine: async (opts) => ({
+            accepted: true,
+            adwId: opts.adwId,
+            detail: "",
+            created: [
+                { id: "200", title: "Owner invites by email", kind: "story", isLeaf: true },
+                { id: "199", title: "Invitations feature", kind: "feature", isLeaf: false },
+            ],
+        }),
+    });
+    await claimSpecs(deps, state);
+    await waitUntil(() => state.refining.size === 0);
+    assert.deepEqual(provider.claimCalls, ["101"]);
+    assert.deepEqual(provider.transitions.map((t) => t.to), ["done"]);
+    assert.equal(comments.length, 1);
+    assert.match(comments[0].body, /#200 \(story\): Owner invites by email/);
+    assert.deepEqual(provider.entries.get("101").marker?.refined, ["200", "199"]);
+});
+test("claimSpecs: never claims more than refineConcurrency in one tick, independent of the build lane's own budget", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("110", "one spec", "spec-ready");
+    provider.addIssue("111", "two spec", "spec-ready");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const deps = makeDeps(provider, codeHost, {
+        refineEnabled: true,
+        refineConcurrency: 1,
+        runRefine: () => new Promise(() => { }), // never resolves — keeps the claim "in flight" for this assertion
+    });
+    await claimSpecs(deps, state);
+    assert.equal(state.refining.size, 1);
+    assert.equal(provider.claimCalls.length, 1);
+});
+test("claimSpecs: dry-run claims no spec and never calls runRefine", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("120", "dry run spec", "spec-ready");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    let called = false;
+    const deps = makeDeps(provider, codeHost, {
+        refineEnabled: true,
+        dryRun: true,
+        runRefine: async (opts) => {
+            called = true;
+            return { accepted: true, adwId: opts.adwId, detail: "", created: [] };
+        },
+    });
+    await claimSpecs(deps, state);
+    assert.equal(provider.claimCalls.length, 0);
+    assert.equal(called, false);
+    assert.equal(provider.entries.get("120").state, "spec-ready");
+});
+test("claimSpecs: a rejected refine chain blocks the spec with the failure detail, without publishing anything", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("130", "unrefinable spec", "spec-ready");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const deps = makeDeps(provider, codeHost, {
+        refineEnabled: true,
+        runRefine: async (opts) => ({ accepted: false, adwId: opts.adwId, detail: "refiner failed gates", created: [] }),
+    });
+    await claimSpecs(deps, state);
+    await waitUntil(() => state.refining.size === 0);
+    assert.deepEqual(provider.transitions, [{ id: "130", to: "blocked", detail: "refiner failed gates" }]);
+});
+test("claimSpecs: a re-claimed spec whose marker already lists published issues skips runRefine entirely", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("140", "already published", "spec-ready", { refined: ["300", "301"] });
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    let called = false;
+    const deps = makeDeps(provider, codeHost, {
+        refineEnabled: true,
+        runRefine: async (opts) => {
+            called = true;
+            return { accepted: true, adwId: opts.adwId, detail: "", created: [] };
+        },
+    });
+    await claimSpecs(deps, state);
+    await waitUntil(() => state.refining.size === 0);
+    assert.equal(called, false, "to-tickets itself has no idempotency guard — this is the one this lane adds");
+    assert.deepEqual(provider.transitions.map((t) => t.to), ["done"]);
+});
+test("reconcileRefining: a refining spec whose marker already lists published issues finishes it without re-running the refiner", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("150", "orphaned after publish", "refining", { refined: ["400"] });
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    await reconcileRefining(makeDeps(provider, codeHost, { refineEnabled: true }), state);
+    assert.deepEqual(provider.transitions, [{ id: "150", to: "done", detail: undefined }]);
+});
+test("reconcileRefining: a refining spec with no marker retries up to the cap, then blocks", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("151", "orphaned, no marker", "refining", null);
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const deps = makeDeps(provider, codeHost, { refineEnabled: true });
+    await reconcileRefining(deps, state); // attempt 1 -> spec-ready
+    assert.equal(provider.entries.get("151").state, "spec-ready");
+    provider.entries.get("151").state = "refining";
+    await reconcileRefining(deps, state); // attempt 2 -> spec-ready
+    assert.equal(provider.entries.get("151").state, "spec-ready");
+    provider.entries.get("151").state = "refining";
+    await reconcileRefining(deps, state); // attempt 3 exceeds MAX_ORPHAN_ATTEMPTS (2) -> blocked
+    assert.equal(provider.entries.get("151").state, "blocked");
+    assert.match(provider.transitions.at(-1)?.detail ?? "", /Gave up after 2 orphaned refine attempts/);
+});
+test("reconcileRefining: a disabled refine lane is a complete no-op", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("152", "should be ignored", "refining", null);
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    provider.listInState = async () => {
+        throw new Error("listInState should never be called when refineEnabled is false");
+    };
+    await reconcileRefining(makeDeps(provider, codeHost, { refineEnabled: false }), state);
+    assert.equal(provider.transitions.length, 0);
+});
+test("claim -> refine -> published fires issue_claimed then spec_refined, both info-level", async () => {
+    const provider = new FakeProvider();
+    provider.addIssue("160", "A spec", "spec-ready");
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    const deps = makeDeps(provider, codeHost, {
+        refineEnabled: true,
+        notify,
+        runRefine: async (opts) => ({ accepted: true, adwId: opts.adwId, detail: "", created: [{ id: "500", title: "A story", kind: "story", isLeaf: true }] }),
+    });
+    await claimSpecs(deps, state);
+    await waitUntil(() => state.refining.size === 0);
+    assert.deepEqual(events.map((e) => e.kind), ["issue_claimed", "spec_refined"]);
+    assert.ok(events.every((e) => e.level === "info"));
+});
+test("tick: a per-stage error is caught and fires exactly one watch_error", async () => {
+    const provider = new FakeProvider();
+    const codeHost = new FakeCodeHost();
+    const state = createWatchState();
+    const { events, notify } = collectNotifications();
+    provider.listEligible = async () => {
+        throw new Error("listEligible exploded");
+    };
+    await tick(makeDeps(provider, codeHost, { notify }), state);
+    assert.deepEqual(events.map((e) => e.kind), ["watch_error"]);
+    assert.match(events[0].detail ?? "", /listEligible exploded/);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",