@gr8ful/spf 0.1.4 → 0.1.6

package/dist/core/issues/provider.d.ts

@@ -1,10 +1,18 @@
 /**
- * The issue-tracker seam `spf watch` drives — the abstraction the user's own
+ * The two seams `spf watch` drives — the abstraction the user's own
  * reference implementation (a GitHub-issues SDLC poller) never had: its
  * GitHub client is a concrete class referenced by type everywhere, so
- * adding a second tracker would mean reworking the poll loop itself. Here,
- * nothing outside `github_provider.ts` (or a future `jira_provider.ts`)
- * knows it's talking to GitHub.
+ * adding a second tracker would mean reworking the poll loop itself.
+ *
+ * `IssueProvider` (tracker: list/claim/transition/comment/markers) and
+ * `CodeHostProvider` (PR lifecycle: open/status) are deliberately separate
+ * interfaces, not one bundled seam — a tracker and a code host are
+ * independent choices in practice (Jira issues against a Bitbucket repo is
+ * a real setup, not a hypothetical one). `github_provider.ts`'s single
+ * class implements both, since GitHub natively is both; `jira_provider.ts`
+ * implements only `IssueProvider`, `bitbucket_provider.ts` only
+ * `CodeHostProvider` — any tracker x host combination is just config
+ * (`watch.issue_provider` x `watch.code_host`), never a poll-loop change.
  *
  * The label-as-state-machine design is deliberate, copied from that same
  * reference: `transition()` is the ONE mutator, so every state change is
@@ -13,7 +21,8 @@
  */
 export type WatchState = "ready" | "working" | "review" | "done" | "blocked";
 export interface Issue {
-    number: number;
+    /** Opaque tracker identifier: a GitHub issue number stringified ("42"), a Jira key ("PROJ-123"). */
+    id: string;
     title: string;
     body: string;
     labels: string[];
@@ -51,8 +60,8 @@ export interface IssueProvider {
      * Idempotently seed whatever this tracker needs for the state machine to
      * work at all — GitHub: the five `<prefix>:*` labels, with a color and
      * description, created if missing and corrected if drifted. A tracker
-     * with no such concept (a future one might model state entirely as a
-     * workflow field) can make this a no-op — `spf watch init` just reports
+     * with no such concept (Jira labels are freeform strings, not seedable
+     * objects) can make this a no-op — `spf watch init` just reports
      * whatever comes back, empty results included.
      */
     ensureLabels(): Promise<EnsureLabelsResult>;
@@ -60,10 +69,13 @@ export interface IssueProvider {
     listEligible(): Promise<Issue[]>;
     /**
      * Issues currently in `state`. `includeAll` queries closed issues too —
-     * required for `review`, since GitHub (or any tracker with a `Closes #n`
-     * convention) can auto-close an issue the instant its PR merges, often
-     * before the next poll tick runs; an open-only query would let it vanish
-     * from tracking forever.
+     * required for `review` on a tracker where closing an issue is a side
+     * effect the tracker itself performs (GitHub auto-closes on a merged
+     * `Closes #n` PR, often before the next poll tick runs); an open-only
+     * query would let it vanish from tracking forever. A tracker where
+     * nothing but `transition()` ever changes an issue's resolution (Jira,
+     * under this design) can ignore the flag — there's no side channel to
+     * miss.
      */
     listInState(state: WatchState, opts?: {
         includeAll?: boolean;
@@ -78,13 +90,24 @@ export interface IssueProvider {
     /** The one state-mutating call. `detail`, if given, is also posted as a comment. */
     transition(issue: Issue, to: WatchState, detail?: string): Promise<void>;
     comment(issue: Issue, body: string): Promise<void>;
-    openPr(issue: Issue, opts: {
+    readMarker(issue: Issue): Promise<WatchMarker | null>;
+    writeMarker(issue: Issue, marker: WatchMarker): Promise<void>;
+}
+/**
+ * The PR-lifecycle seam, independent of `IssueProvider` — see the module
+ * comment above. `openPr` takes no issue reference: cross-linking a PR to
+ * its issue is the caller's job (put the issue's `id`/title in `title`/
+ * `body`), not this seam's, since a code host paired with a different
+ * tracker has no native "closes" convention to hook into anyway. `spf
+ * watch`'s own polling (`finishReviews`), not the host's auto-close
+ * behavior, is what drives `done`/`blocked` — see `watch.ts`.
+ */
+export interface CodeHostProvider {
+    openPr(opts: {
         branch: string;
         title: string;
         body: string;
         base: string;
     }): Promise<PrRef>;
     prStatus(pr: PrRef): Promise<PrStatus>;
-    readMarker(issue: Issue): Promise<WatchMarker | null>;
-    writeMarker(issue: Issue, marker: WatchMarker): Promise<void>;
 }

package/dist/core/issues/provider.js

@@ -1,10 +1,18 @@
 /**
- * The issue-tracker seam `spf watch` drives — the abstraction the user's own
+ * The two seams `spf watch` drives — the abstraction the user's own
  * reference implementation (a GitHub-issues SDLC poller) never had: its
  * GitHub client is a concrete class referenced by type everywhere, so
- * adding a second tracker would mean reworking the poll loop itself. Here,
- * nothing outside `github_provider.ts` (or a future `jira_provider.ts`)
- * knows it's talking to GitHub.
+ * adding a second tracker would mean reworking the poll loop itself.
+ *
+ * `IssueProvider` (tracker: list/claim/transition/comment/markers) and
+ * `CodeHostProvider` (PR lifecycle: open/status) are deliberately separate
+ * interfaces, not one bundled seam — a tracker and a code host are
+ * independent choices in practice (Jira issues against a Bitbucket repo is
+ * a real setup, not a hypothetical one). `github_provider.ts`'s single
+ * class implements both, since GitHub natively is both; `jira_provider.ts`
+ * implements only `IssueProvider`, `bitbucket_provider.ts` only
+ * `CodeHostProvider` — any tracker x host combination is just config
+ * (`watch.issue_provider` x `watch.code_host`), never a poll-loop change.
  *
  * The label-as-state-machine design is deliberate, copied from that same
  * reference: `transition()` is the ONE mutator, so every state change is

package/dist/core/paths.d.ts

@@ -22,6 +22,8 @@ export declare const ASSETS_DIR: string;
 export declare const WEB_DIR: string;
 export declare const BUILTIN_CONFIG_PATH: string;
 export declare const BUILTIN_PROMPTS_DIR: string;
+/** `spf init --template <name>` reads `<name>.spf.config.yaml` from here. */
+export declare const TEMPLATES_DIR: string;
 export interface RepoAnchor {
     /** The invocation cwd this anchor was resolved from (already absolute). */
     cwd: string;

package/dist/core/paths.js

@@ -25,6 +25,8 @@ export const ASSETS_DIR = path.join(PACKAGE_ROOT, "assets");
 export const WEB_DIR = path.join(PACKAGE_ROOT, "web");
 export const BUILTIN_CONFIG_PATH = path.join(ASSETS_DIR, "defaults", "spf.config.yaml");
 export const BUILTIN_PROMPTS_DIR = path.join(ASSETS_DIR, "prompts");
+/** `spf init --template <name>` reads `<name>.spf.config.yaml` from here. */
+export const TEMPLATES_DIR = path.join(ASSETS_DIR, "templates");
 /** Walk up from `cwd` to (and including) `repoRoot` looking for a `.spf/` directory. */
 function findSfDir(cwd, repoRoot) {
     let dir = cwd;

package/dist/core/watch.d.ts

@@ -1,5 +1,5 @@
 import type { GitHandle } from "./git_helper.ts";
-import type { Issue, IssueProvider } from "./issues/provider.ts";
+import type { CodeHostProvider, Issue, IssueProvider } from "./issues/provider.ts";
 export interface ChainRunResult {
     accepted: boolean;
     adwId: string;
@@ -8,6 +8,7 @@ export interface ChainRunResult {
 }
 export interface WatchDeps {
     provider: IssueProvider;
+    codeHost: CodeHostProvider;
     git: GitHandle;
     /** Bound to a specific worktree path (diffFiles/push run there) — inject `git_helper.makeGit` for real use, a fake for tests. */
     worktreeGit: (worktreePath: string) => GitHandle;
@@ -25,7 +26,7 @@ export interface WatchDeps {
     log: (message: string) => void;
 }
 export interface WatchRunState {
-    inflight: Set<number>;
+    inflight: Set<string>;
 }
 export declare function createWatchState(): WatchRunState;
 export declare function branchNameFor(issue: Issue): string;

package/dist/core/watch.js

@@ -40,10 +40,13 @@ export function branchNameFor(issue) {
         .slice(0, 5)
         .join("-")
         .replace(/[^a-z0-9-]/g, "");
-    return `spf-watch/${issue.number}-${slug || "issue"}`.slice(0, 200);
+    // The issue's own id in the branch name isn't just labeling: Jira's
+    // Bitbucket integration auto-links a PR to the issue when its key
+    // appears anywhere in the branch name, no explicit API call needed.
+    return `spf-watch/${issue.id}-${slug || "issue"}`.slice(0, 200);
 }
 function worktreePathFor(deps, issue) {
-    return path.join(deps.worktreesDir, `issue-${issue.number}`);
+    return path.join(deps.worktreesDir, `issue-${issue.id}`);
 }
 function cleanupWorktree(deps, marker) {
     if (!marker)
@@ -67,13 +70,13 @@ function cleanupWorktree(deps, marker) {
 export async function reconcileOrphans(deps, state) {
     const working = await deps.provider.listInState("working");
     for (const issue of working) {
-        if (state.inflight.has(issue.number))
+        if (state.inflight.has(issue.id))
             continue;
         const marker = await deps.provider.readMarker(issue);
         if (marker?.pr) {
-            const status = await deps.provider.prStatus({ number: marker.pr, branch: marker.branch ?? "", url: "" });
+            const status = await deps.codeHost.prStatus({ number: marker.pr, branch: marker.branch ?? "", url: "" });
             if (status.state === "open" || status.merged) {
-                deps.log(`watch: #${issue.number} orphaned with an open/merged PR #${marker.pr} — resuming as review`);
+                deps.log(`watch: ${issue.id} orphaned with an open/merged PR #${marker.pr} — resuming as review`);
                 if (!deps.dryRun)
                     await deps.provider.transition(issue, "review");
                 continue;
@@ -81,14 +84,14 @@ export async function reconcileOrphans(deps, state) {
         }
         const attempt = (marker?.attempt ?? 0) + 1;
         if (attempt <= MAX_ORPHAN_ATTEMPTS) {
-            deps.log(`watch: #${issue.number} orphaned, retry ${attempt}/${MAX_ORPHAN_ATTEMPTS} — back to ready`);
+            deps.log(`watch: ${issue.id} orphaned, retry ${attempt}/${MAX_ORPHAN_ATTEMPTS} — back to ready`);
             if (!deps.dryRun) {
                 await deps.provider.writeMarker(issue, { ...marker, attempt });
                 await deps.provider.transition(issue, "ready");
             }
         }
         else {
-            deps.log(`watch: #${issue.number} orphaned past ${MAX_ORPHAN_ATTEMPTS} attempts — blocked`);
+            deps.log(`watch: ${issue.id} orphaned past ${MAX_ORPHAN_ATTEMPTS} attempts — blocked`);
             if (!deps.dryRun) {
                 await deps.provider.transition(issue, "blocked", `Gave up after ${MAX_ORPHAN_ATTEMPTS} orphaned attempts.`);
                 cleanupWorktree(deps, marker);
@@ -103,16 +106,16 @@ export async function finishReviews(deps) {
         const marker = await deps.provider.readMarker(issue);
         if (!marker?.pr)
             continue;
-        const status = await deps.provider.prStatus({ number: marker.pr, branch: marker.branch ?? "", url: "" });
+        const status = await deps.codeHost.prStatus({ number: marker.pr, branch: marker.branch ?? "", url: "" });
         if (status.merged) {
-            deps.log(`watch: #${issue.number}'s PR #${marker.pr} merged — done`);
+            deps.log(`watch: ${issue.id}'s PR #${marker.pr} merged — done`);
             if (!deps.dryRun) {
                 await deps.provider.transition(issue, "done");
                 cleanupWorktree(deps, marker);
             }
         }
         else if (status.state === "closed") {
-            deps.log(`watch: #${issue.number}'s PR #${marker.pr} closed without merging — blocked`);
+            deps.log(`watch: ${issue.id}'s PR #${marker.pr} closed without merging — blocked`);
             if (!deps.dryRun) {
                 await deps.provider.transition(issue, "blocked", `PR #${marker.pr} was closed without merging.`);
                 cleanupWorktree(deps, marker);
@@ -124,7 +127,7 @@ export async function finishReviews(deps) {
 async function runIssue(deps, issue) {
     const branch = branchNameFor(issue);
     const worktreePath = worktreePathFor(deps, issue);
-    const adwId = `issue-${issue.number}`;
+    const adwId = `issue-${issue.id}`;
     try {
         deps.git.fetch("origin", deps.baseBranch);
         deps.git.worktreeAdd(worktreePath, branch, `origin/${deps.baseBranch}`);
@@ -132,32 +135,37 @@ async function runIssue(deps, issue) {
         const prompt = `${issue.title}\n\n${issue.body}`.trim();
         const result = await deps.runChain({ prompt, cwd: worktreePath, adwId });
         if (!result.accepted) {
-            deps.log(`watch: #${issue.number}: chain "${deps.chain}" did not succeed — blocked`);
+            deps.log(`watch: ${issue.id}: chain "${deps.chain}" did not succeed — blocked`);
             await deps.provider.transition(issue, "blocked", result.detail || `Chain "${deps.chain}" (adw_id ${adwId}) did not complete successfully. Run \`spf phases ${adwId}\` for detail.`);
             cleanupWorktree(deps, { worktree: worktreePath, branch });
             return;
         }
         const wtGit = deps.worktreeGit(worktreePath);
         if (wtGit.diffFiles(`origin/${deps.baseBranch}`).length === 0) {
-            deps.log(`watch: #${issue.number}: chain succeeded but committed nothing — blocked`);
+            deps.log(`watch: ${issue.id}: chain succeeded but committed nothing — blocked`);
             await deps.provider.transition(issue, "blocked", `Chain "${deps.chain}" (adw_id ${adwId}) completed but left no committed changes.`);
             cleanupWorktree(deps, { worktree: worktreePath, branch });
             return;
         }
         wtGit.push("origin", branch);
-        const pr = await deps.provider.openPr(issue, {
+        // No cross-linking magic keyword here on purpose (a code host paired
+        // with a different tracker has no "Closes #n" convention to hook into
+        // — see provider.ts) — the issue id in the title/body is plain text
+        // for humans, and, on a Jira+Bitbucket pairing, exactly what Jira's own
+        // Bitbucket integration scans for to link the PR automatically.
+        const pr = await deps.codeHost.openPr({
             branch,
-            title: `${issue.title} (#${issue.number})`,
-            body: `Automated by \`spf watch\` — chain \`${deps.chain}\`, adw_id \`${adwId}\`.`,
+            title: `${issue.title} (${issue.id})`,
+            body: `Automated by \`spf watch\` — chain \`${deps.chain}\`, adw_id \`${adwId}\`, issue ${issue.id}.`,
             base: deps.baseBranch,
         });
         await deps.provider.writeMarker(issue, { worktree: worktreePath, branch, pr: pr.number, attempt: 0 });
         await deps.provider.transition(issue, "review");
-        deps.log(`watch: #${issue.number}: opened PR #${pr.number} — review`);
+        deps.log(`watch: ${issue.id}: opened PR #${pr.number} — review`);
     }
     catch (error) {
         const message = error.message;
-        deps.log(`watch: #${issue.number}: error: ${message}`);
+        deps.log(`watch: ${issue.id}: error: ${message}`);
         await deps.provider.transition(issue, "blocked", `spf watch error: ${message}`).catch(() => undefined);
         cleanupWorktree(deps, { worktree: worktreePath, branch });
     }
@@ -170,20 +178,20 @@ export async function claimNewWork(deps, state) {
     for (const issue of eligible) {
         if (state.inflight.size >= deps.concurrency)
             break;
-        if (state.inflight.has(issue.number))
+        if (state.inflight.has(issue.id))
             continue;
         if (deps.dryRun) {
-            deps.log(`watch: [dry-run] would claim #${issue.number} (${issue.title}) and run chain "${deps.chain}"`);
+            deps.log(`watch: [dry-run] would claim ${issue.id} (${issue.title}) and run chain "${deps.chain}"`);
             continue;
         }
         const claimed = await deps.provider.claim(issue);
         if (!claimed) {
-            deps.log(`watch: #${issue.number} lost the claim race this tick — skipping`);
+            deps.log(`watch: ${issue.id} lost the claim race this tick — skipping`);
             continue;
         }
-        deps.log(`watch: claimed #${issue.number}: ${issue.title}`);
-        state.inflight.add(issue.number);
-        runIssue(deps, issue).finally(() => state.inflight.delete(issue.number));
+        deps.log(`watch: claimed ${issue.id}: ${issue.title}`);
+        state.inflight.add(issue.id);
+        runIssue(deps, issue).finally(() => state.inflight.delete(issue.id));
     }
 }
 /** One poll tick: reconcile, finish, claim — each independently caught, so one phase's error never blocks the rest. */

package/dist/test/watch.test.js

@@ -4,14 +4,11 @@ import { branchNameFor, claimNewWork, createWatchState, finishReviews, reconcile
 /** In-memory fake — exactly the seam `provider.ts` exists for. */
 class FakeProvider {
     entries = new Map();
-    prs = new Map();
     ensureLabelsCalls = 0;
     transitions = [];
-    openedPrs = [];
     claimCalls = [];
-    nextPrNumber = 1000;
-    addIssue(number, title, state = "ready", marker = null) {
-        this.entries.set(number, { issue: { number, title, body: "", labels: [`spf:${state}`] }, state, marker });
+    addIssue(id, title, state = "ready", marker = null) {
+        this.entries.set(id, { issue: { id, title, body: "", labels: [`spf:${state}`] }, state, marker });
     }
     async ensureLabels() {
         this.ensureLabelsCalls++;
@@ -24,33 +21,39 @@ class FakeProvider {
         return [...this.entries.values()].filter((e) => e.state === state).map((e) => e.issue);
     }
     async claim(issue) {
-        this.claimCalls.push(issue.number);
-        const entry = this.entries.get(issue.number);
+        this.claimCalls.push(issue.id);
+        const entry = this.entries.get(issue.id);
         if (entry.state !== "ready")
             return false;
         entry.state = "working";
         return true;
     }
     async transition(issue, to, detail) {
-        this.entries.get(issue.number).state = to;
-        this.transitions.push({ number: issue.number, to, detail });
+        this.entries.get(issue.id).state = to;
+        this.transitions.push({ id: issue.id, to, detail });
     }
     async comment() { }
-    async openPr(issue, opts) {
+    async readMarker(issue) {
+        return this.entries.get(issue.id)?.marker ?? null;
+    }
+    async writeMarker(issue, marker) {
+        this.entries.get(issue.id).marker = marker;
+    }
+}
+/** In-memory fake `CodeHostProvider` — separate from `FakeProvider`, mirroring the real split. */
+class FakeCodeHost {
+    prs = new Map();
+    openedPrs = [];
+    nextPrNumber = 1000;
+    async openPr(opts) {
         const number = this.nextPrNumber++;
-        this.openedPrs.push({ issueNumber: issue.number, branch: opts.branch });
+        this.openedPrs.push({ title: opts.title, branch: opts.branch });
         this.prs.set(number, { merged: false, state: "open", ciStatus: "pending" });
         return { number, branch: opts.branch, url: `https://example.invalid/pr/${number}` };
     }
     async prStatus(pr) {
         return this.prs.get(pr.number) ?? { merged: false, state: "open", ciStatus: "pending" };
     }
-    async readMarker(issue) {
-        return this.entries.get(issue.number)?.marker ?? null;
-    }
-    async writeMarker(issue, marker) {
-        this.entries.get(issue.number).marker = marker;
-    }
 }
 function fakeGit(overrides = {}) {
     return {
@@ -77,9 +80,10 @@ function fakeGit(overrides = {}) {
         ...overrides,
     };
 }
-function makeDeps(provider, overrides = {}) {
+function makeDeps(provider, codeHost, overrides = {}) {
     return {
         provider,
+        codeHost,
         git: fakeGit(),
         worktreeGit: () => fakeGit({ diffFiles: () => ["src/index.ts"] }), // a real commit landed, by default
         labelPrefix: "spf",
@@ -102,63 +106,69 @@ async function waitUntil(predicate, timeoutMs = 2000) {
     }
 }
 test("branchNameFor: sanitizes a title into a safe branch name", () => {
-    assert.equal(branchNameFor({ number: 42, title: "Add a /health endpoint!!", body: "", labels: [] }), "spf-watch/42-add-a-health-endpoint");
-    assert.equal(branchNameFor({ number: 7, title: "", body: "", labels: [] }), "spf-watch/7-issue");
+    assert.equal(branchNameFor({ id: "42", title: "Add a /health endpoint!!", body: "", labels: [] }), "spf-watch/42-add-a-health-endpoint");
+    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: 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");
+    provider.addIssue("1", "Add a /health endpoint");
+    const codeHost = new FakeCodeHost();
     const state = createWatchState();
-    const deps = makeDeps(provider);
+    const deps = makeDeps(provider, codeHost);
     await claimNewWork(deps, state);
     await waitUntil(() => state.inflight.size === 0);
-    assert.deepEqual(provider.claimCalls, [1]);
-    assert.equal(provider.openedPrs.length, 1);
-    assert.equal(provider.openedPrs[0].issueNumber, 1);
+    assert.deepEqual(provider.claimCalls, ["1"]);
+    assert.equal(codeHost.openedPrs.length, 1);
+    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);
+    assert.equal(provider.entries.get("1").marker?.pr, 1000);
 });
 test("claimNewWork: a rejected chain run blocks the issue with the failure detail", async () => {
     const provider = new FakeProvider();
-    provider.addIssue(2, "Flaky feature");
+    provider.addIssue("2", "Flaky feature");
+    const codeHost = new FakeCodeHost();
     const state = createWatchState();
-    const deps = makeDeps(provider, {
+    const deps = makeDeps(provider, codeHost, {
         runChain: async () => ({ accepted: false, adwId: "issue-2", detail: "build-test failed at phase build" }),
     });
     await claimNewWork(deps, state);
     await waitUntil(() => state.inflight.size === 0);
-    assert.deepEqual(provider.transitions, [{ number: 2, to: "blocked", detail: "build-test failed at phase build" }]);
-    assert.equal(provider.openedPrs.length, 0);
+    assert.deepEqual(provider.transitions, [{ id: "2", to: "blocked", detail: "build-test failed at phase build" }]);
+    assert.equal(codeHost.openedPrs.length, 0);
 });
 test("claimNewWork: an accepted run with nothing committed also blocks, without opening a PR", async () => {
     const provider = new FakeProvider();
-    provider.addIssue(3, "No-op request");
+    provider.addIssue("3", "No-op request");
+    const codeHost = new FakeCodeHost();
     const state = createWatchState();
-    const deps = makeDeps(provider, { worktreeGit: () => fakeGit({ diffFiles: () => [] }) });
+    const deps = makeDeps(provider, codeHost, { worktreeGit: () => fakeGit({ diffFiles: () => [] }) });
     await claimNewWork(deps, state);
     await waitUntil(() => state.inflight.size === 0);
     assert.equal(provider.transitions[0]?.to, "blocked");
     assert.match(provider.transitions[0]?.detail ?? "", /no committed changes/);
-    assert.equal(provider.openedPrs.length, 0);
+    assert.equal(codeHost.openedPrs.length, 0);
 });
 test("claimNewWork: never claims more than the concurrency budget in one tick", async () => {
     const provider = new FakeProvider();
-    provider.addIssue(10, "one");
-    provider.addIssue(11, "two");
-    provider.addIssue(12, "three");
+    provider.addIssue("10", "one");
+    provider.addIssue("11", "two");
+    provider.addIssue("12", "three");
+    const codeHost = new FakeCodeHost();
     const state = createWatchState();
     // A runChain that never resolves keeps every claimed issue "inflight" for this assertion.
-    const deps = makeDeps(provider, { concurrency: 2, runChain: () => new Promise(() => { }) });
+    const deps = makeDeps(provider, codeHost, { concurrency: 2, runChain: () => new Promise(() => { }) });
     await claimNewWork(deps, state);
     assert.equal(state.inflight.size, 2);
     assert.equal(provider.claimCalls.length, 2);
 });
 test("claimNewWork: dry-run claims nothing and calls neither claim() nor runChain", async () => {
     const provider = new FakeProvider();
-    provider.addIssue(20, "dry run me");
+    provider.addIssue("20", "dry run me");
+    const codeHost = new FakeCodeHost();
     const state = createWatchState();
     let runChainCalled = false;
-    const deps = makeDeps(provider, {
+    const deps = makeDeps(provider, codeHost, {
         dryRun: true,
         runChain: async () => {
             runChainCalled = true;
@@ -168,60 +178,66 @@ test("claimNewWork: dry-run claims nothing and calls neither claim() nor runChai
     await claimNewWork(deps, state);
     assert.equal(provider.claimCalls.length, 0);
     assert.equal(runChainCalled, false);
-    assert.equal(provider.entries.get(20).state, "ready");
+    assert.equal(provider.entries.get("20").state, "ready");
 });
 test("reconcileOrphans: a working issue with an open PR in its marker resumes as review", async () => {
     const provider = new FakeProvider();
-    provider.addIssue(30, "orphaned mid-review", "working", { pr: 500, branch: "spf-watch/30-x" });
-    provider.prs.set(500, { merged: false, state: "open", ciStatus: "pending" });
+    provider.addIssue("30", "orphaned mid-review", "working", { pr: 500, branch: "spf-watch/30-x" });
+    const codeHost = new FakeCodeHost();
+    codeHost.prs.set(500, { merged: false, state: "open", ciStatus: "pending" });
     const state = createWatchState();
-    await reconcileOrphans(makeDeps(provider), state);
-    assert.deepEqual(provider.transitions, [{ number: 30, to: "review", detail: undefined }]);
+    await reconcileOrphans(makeDeps(provider, codeHost), state);
+    assert.deepEqual(provider.transitions, [{ id: "30", to: "review", detail: undefined }]);
 });
 test("reconcileOrphans: a working issue with no marker retries up to the cap, then blocks", async () => {
     const provider = new FakeProvider();
-    provider.addIssue(31, "orphaned, no marker", "working", null);
+    provider.addIssue("31", "orphaned, no marker", "working", null);
+    const codeHost = new FakeCodeHost();
     const state = createWatchState();
-    const deps = makeDeps(provider);
+    const deps = makeDeps(provider, codeHost);
     await reconcileOrphans(deps, state); // attempt 1 -> ready
-    assert.equal(provider.entries.get(31).state, "ready");
-    assert.equal(provider.entries.get(31).marker?.attempt, 1);
-    provider.entries.get(31).state = "working"; // simulate it getting re-claimed and orphaned again
+    assert.equal(provider.entries.get("31").state, "ready");
+    assert.equal(provider.entries.get("31").marker?.attempt, 1);
+    provider.entries.get("31").state = "working"; // simulate it getting re-claimed and orphaned again
     await reconcileOrphans(deps, state); // attempt 2 -> ready
-    assert.equal(provider.entries.get(31).state, "ready");
-    provider.entries.get(31).state = "working";
+    assert.equal(provider.entries.get("31").state, "ready");
+    provider.entries.get("31").state = "working";
     await reconcileOrphans(deps, state); // attempt 3 exceeds MAX_ORPHAN_ATTEMPTS (2) -> blocked
-    assert.equal(provider.entries.get(31).state, "blocked");
+    assert.equal(provider.entries.get("31").state, "blocked");
     assert.match(provider.transitions.at(-1)?.detail ?? "", /Gave up after 2 orphaned attempts/);
 });
 test("reconcileOrphans: skips issues this process is already tracking as in-flight", async () => {
     const provider = new FakeProvider();
-    provider.addIssue(32, "actually still running", "working", null);
+    provider.addIssue("32", "actually still running", "working", null);
+    const codeHost = new FakeCodeHost();
     const state = createWatchState();
-    state.inflight.add(32);
-    await reconcileOrphans(makeDeps(provider), state);
+    state.inflight.add("32");
+    await reconcileOrphans(makeDeps(provider, codeHost), state);
     assert.equal(provider.transitions.length, 0, "an in-flight issue must not be treated as orphaned");
 });
 test("finishReviews: a merged PR moves the issue to done", async () => {
     const provider = new FakeProvider();
-    provider.addIssue(40, "shipped", "review", { pr: 600, branch: "spf-watch/40-x" });
-    provider.prs.set(600, { merged: true, state: "closed", ciStatus: "success" });
-    await finishReviews(makeDeps(provider));
-    assert.deepEqual(provider.transitions, [{ number: 40, to: "done", detail: undefined }]);
+    provider.addIssue("40", "shipped", "review", { pr: 600, branch: "spf-watch/40-x" });
+    const codeHost = new FakeCodeHost();
+    codeHost.prs.set(600, { merged: true, state: "closed", ciStatus: "success" });
+    await finishReviews(makeDeps(provider, codeHost));
+    assert.deepEqual(provider.transitions, [{ id: "40", to: "done", detail: undefined }]);
 });
 test("finishReviews: a closed-without-merging PR blocks the issue", async () => {
     const provider = new FakeProvider();
-    provider.addIssue(41, "rejected", "review", { pr: 601, branch: "spf-watch/41-x" });
-    provider.prs.set(601, { merged: false, state: "closed", ciStatus: "failure" });
-    await finishReviews(makeDeps(provider));
+    provider.addIssue("41", "rejected", "review", { pr: 601, branch: "spf-watch/41-x" });
+    const codeHost = new FakeCodeHost();
+    codeHost.prs.set(601, { merged: false, state: "closed", ciStatus: "failure" });
+    await finishReviews(makeDeps(provider, codeHost));
     assert.equal(provider.transitions[0]?.to, "blocked");
     assert.match(provider.transitions[0]?.detail ?? "", /closed without merging/);
 });
 test("finishReviews: a still-open PR leaves the issue in review", async () => {
     const provider = new FakeProvider();
-    provider.addIssue(42, "still cooking", "review", { pr: 602, branch: "spf-watch/42-x" });
-    provider.prs.set(602, { merged: false, state: "open", ciStatus: "pending" });
-    await finishReviews(makeDeps(provider));
+    provider.addIssue("42", "still cooking", "review", { pr: 602, branch: "spf-watch/42-x" });
+    const codeHost = new FakeCodeHost();
+    codeHost.prs.set(602, { merged: false, state: "open", ciStatus: "pending" });
+    await finishReviews(makeDeps(provider, codeHost));
     assert.equal(provider.transitions.length, 0);
-    assert.equal(provider.entries.get(42).state, "review");
+    assert.equal(provider.entries.get("42").state, "review");
 });

package/package.json

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