@gr8ful/spf 0.3.0 → 0.4.0

package/dist/core/watch.d.ts

@@ -7,6 +7,21 @@ export interface ChainRunResult {
     /** Shown to the engineer via a `blocked` comment on a failed/no-op run. */
     detail: string;
 }
+/** One issue the refine lane created — enough for `finishSpec`'s summary comment and the marker's idempotency record. */
+export interface RefinedIssueRef {
+    id: string;
+    title: string;
+    kind: string;
+    isLeaf: boolean;
+}
+export interface RefineRunResult {
+    accepted: boolean;
+    adwId: string;
+    /** Shown to the engineer via a `blocked` comment on a failed/no-op run. */
+    detail: string;
+    /** What `steps.publishIssues()` created, read back from its side-channel file — see `cli/commands/watch.ts`'s `runRefine`. Empty when `!accepted`. */
+    created: RefinedIssueRef[];
+}
 export interface WatchDeps {
     provider: IssueProvider;
     codeHost: CodeHostProvider;
@@ -17,6 +32,23 @@ export interface WatchDeps {
     chain: string;
     baseBranch: string;
     concurrency: number;
+    /**
+     * The second lane — decomposing a `<prefix>:spec-ready` product spec
+     * instead of building a `<prefix>:ready` issue. `false` (the default) is
+     * a complete no-op: `claimSpecs`/`reconcileRefining` return immediately,
+     * so an existing `spf watch` config sees no new poll traffic at all until
+     * this is turned on. See `WatchConfigSchema`'s `refine` field.
+     */
+    refineEnabled: boolean;
+    refineConcurrency: number;
+    refineChain: string;
+    /** Same shape as `runChain`, for the refine lane — see its own doc comment for why the two aren't unified into one callback. */
+    runRefine: (opts: {
+        prompt: string;
+        cwd: string;
+        adwId: string;
+        issueId: string;
+    }) => Promise<RefineRunResult>;
     worktreesDir: string;
     /**
      * Symlink (or otherwise wire up) `<worktreePath>/.spf/data` to the MAIN
@@ -49,9 +81,22 @@ export interface WatchDeps {
 }
 export interface WatchRunState {
     inflight: Set<string>;
+    /**
+     * Separate from `inflight` — not a defensive copy of the same set, a
+     * genuinely different budget. The refine lane's `claimSpecs` caps against
+     * `refineConcurrency`, independent of the build lane's `concurrency`; a
+     * shared set would conflate "how many specs are being refined" with "how
+     * many issues are being built" and make either budget impossible to
+     * enforce on its own. The two never collide on an id in practice (a
+     * `spec-ready` issue and a `ready` issue are never the same issue), but
+     * that isn't why this is separate — the budgets are what require it.
+     */
+    refining: Set<string>;
 }
 export declare function createWatchState(): WatchRunState;
 export declare function branchNameFor(issue: Issue): string;
+/** Same idea as `branchNameFor`, for the refine lane's throwaway worktree — a spec never gets a PR, so this branch is only ever fetched-from-and-thrown-away, never pushed. */
+export declare function refineBranchNameFor(issue: Issue): string;
 /**
  * Any issue labeled `working` that THIS process isn't tracking is an
  * orphan — a daemon restart, or another instance's claim this process
@@ -59,9 +104,19 @@ export declare function branchNameFor(issue: Issue): string;
  * merged) PR; otherwise retry up to `MAX_ORPHAN_ATTEMPTS`, then give up.
  */
 export declare function reconcileOrphans(deps: WatchDeps, state: WatchRunState): Promise<void>;
+/**
+ * The refine lane's own `reconcileOrphans` — a `refining`-labeled spec this
+ * process isn't tracking is either a completed publish that crashed before
+ * its own `transition(issue, "done")` ran (resume: finish it, no re-run),
+ * or a genuine orphan (retry up to `MAX_ORPHAN_ATTEMPTS`, then give up).
+ * A no-op entirely when `watch.refine` is off — see `WatchDeps.refineEnabled`.
+ */
+export declare function reconcileRefining(deps: WatchDeps, state: WatchRunState): Promise<void>;
 /** Poll every `review`-labeled issue's PR for merged (-> done) or closed-without-merging (-> blocked). */
 export declare function finishReviews(deps: WatchDeps): Promise<void>;
 /** Claim as many `ready` issues as the concurrency budget allows, and kick off `runIssue` for each in the background. */
 export declare function claimNewWork(deps: WatchDeps, state: WatchRunState): Promise<void>;
-/** One poll tick: reconcile, finish, claim — each independently caught, so one phase's error never blocks the rest. */
+/** Claim as many `spec-ready` specs as `refineConcurrency` allows, and kick off `runSpec` for each in the background. A no-op when `watch.refine` is off. */
+export declare function claimSpecs(deps: WatchDeps, state: WatchRunState): Promise<void>;
+/** One poll tick: reconcile both lanes, finish reviews, then claim both lanes — each stage independently caught, so one stage's error never blocks the rest. */
 export declare function tick(deps: WatchDeps, state: WatchRunState): Promise<void>;

package/dist/core/watch.js

@@ -1,10 +1,18 @@
 /**
- * The `spf watch` state machine: poll -> claim -> run a chain -> PR ->
- * done/blocked. Provider-agnostic (drives whatever `IssueProvider` it's
- * given) and chain-agnostic (drives whatever `runChain` callback it's
+ * The `spf watch` state machine — two lanes over the same poll loop.
+ *
+ * The build lane: poll -> claim -> run a chain -> PR -> done/blocked.
+ * The refine lane (`watch.refine.enabled`, off by default): poll a
+ * `spec-ready` product spec -> claim -> decompose it into a feature/story
+ * tree -> publish those as real issues -> done/blocked. A spec is not
+ * individually workable, so this lane never opens a PR — it hands the build
+ * lane its next batch of `ready`-able work instead (see `core/refine.ts`).
+ *
+ * Provider-agnostic (drives whatever `IssueProvider` it's given) and
+ * chain-agnostic (drives whatever `runChain`/`runRefine` callback it's
  * given) — deliberately kept out of `src/chains/`'s dependency direction,
- * so this stays testable against a fake provider and a fake `runChain`
- * with no chain registry involved.
+ * so this stays testable against a fake provider and fake callbacks with no
+ * chain registry involved.
  *
  * Design lifted from the user's own GitHub-poller reference implementation
  * (a label-as-state-machine daemon), leaned down for a v1: no per-issue
@@ -30,24 +38,33 @@
 import path from "node:path";
 const MAX_ORPHAN_ATTEMPTS = 2;
 export function createWatchState() {
-    return { inflight: new Set() };
+    return { inflight: new Set(), refining: new Set() };
 }
-export function branchNameFor(issue) {
-    const slug = issue.title
+function slugifyTitle(title) {
+    return (title
         .toLowerCase()
         .split(/\s+/)
         .filter(Boolean)
         .slice(0, 5)
         .join("-")
-        .replace(/[^a-z0-9-]/g, "");
+        .replace(/[^a-z0-9-]/g, "") || "issue");
+}
+export function branchNameFor(issue) {
     // 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);
+    return `spf-watch/${issue.id}-${slugifyTitle(issue.title)}`.slice(0, 200);
+}
+/** Same idea as `branchNameFor`, for the refine lane's throwaway worktree — a spec never gets a PR, so this branch is only ever fetched-from-and-thrown-away, never pushed. */
+export function refineBranchNameFor(issue) {
+    return `spf-refine/${issue.id}-${slugifyTitle(issue.title)}`.slice(0, 200);
 }
 function worktreePathFor(deps, issue) {
     return path.join(deps.worktreesDir, `issue-${issue.id}`);
 }
+function specWorktreePathFor(deps, issue) {
+    return path.join(deps.worktreesDir, `spec-${issue.id}`);
+}
 function cleanupWorktree(deps, marker) {
     if (!marker)
         return;
@@ -106,6 +123,78 @@ export async function reconcileOrphans(deps, state) {
         }
     }
 }
+/**
+ * Post the summary comment on a decomposed spec and transition it to `done`
+ * — the refine lane's one shared finishing move, reached from both the
+ * normal path (`runSpec`, right after a successful publish) and the
+ * orphan-resume path (`reconcileRefining`, when a completed publish's
+ * marker survived a crash the `transition` itself didn't). `created` only
+ * has titles/kinds in the normal path — an orphan resume has nothing but
+ * the ids `WatchMarker.refined` recorded, and the comment degrades to a
+ * bare list of `#id`s rather than blocking on a re-fetch.
+ */
+async function finishSpec(deps, issue, created) {
+    const body = created.length > 0
+        ? `spf watch refined this spec into ${created.length} issue(s):\n\n` +
+            created.map((c) => (c.title ? `- #${c.id} (${c.kind}): ${c.title}` : `- #${c.id}`)).join("\n") +
+            `\n\nPromote any of them to \`${deps.labelPrefix}:ready\` when it's worth building.`
+        : `spf watch refined this spec but the refiner produced no issues.`;
+    deps.notify({
+        kind: "spec_refined",
+        level: "info",
+        title: `spec ${issue.id} refined`,
+        detail: `${created.length} issue(s) created.`,
+        fields: [["issue", issue.id], ["title", issue.title], ["created", String(created.length)]],
+    });
+    if (!deps.dryRun) {
+        await deps.provider.comment(issue, body);
+        await deps.provider.transition(issue, "done");
+    }
+}
+/**
+ * The refine lane's own `reconcileOrphans` — a `refining`-labeled spec this
+ * process isn't tracking is either a completed publish that crashed before
+ * its own `transition(issue, "done")` ran (resume: finish it, no re-run),
+ * or a genuine orphan (retry up to `MAX_ORPHAN_ATTEMPTS`, then give up).
+ * A no-op entirely when `watch.refine` is off — see `WatchDeps.refineEnabled`.
+ */
+export async function reconcileRefining(deps, state) {
+    if (!deps.refineEnabled)
+        return;
+    const refining = await deps.provider.listInState("refining");
+    for (const issue of refining) {
+        if (state.refining.has(issue.id))
+            continue;
+        const marker = await deps.provider.readMarker(issue);
+        if (marker?.refined && marker.refined.length > 0) {
+            deps.log(`watch: spec ${issue.id} orphaned after publish already completed — finishing`);
+            await finishSpec(deps, issue, marker.refined.map((id) => ({ id })));
+            continue;
+        }
+        const attempt = (marker?.attempt ?? 0) + 1;
+        if (attempt <= MAX_ORPHAN_ATTEMPTS) {
+            deps.log(`watch: spec ${issue.id} orphaned mid-refine, retry ${attempt}/${MAX_ORPHAN_ATTEMPTS} — back to spec-ready`);
+            if (!deps.dryRun) {
+                await deps.provider.writeMarker(issue, { ...marker, attempt });
+                await deps.provider.transition(issue, "spec-ready");
+            }
+        }
+        else {
+            deps.log(`watch: spec ${issue.id} orphaned past ${MAX_ORPHAN_ATTEMPTS} attempts — blocked`);
+            deps.notify({
+                kind: "issue_blocked",
+                level: "error",
+                title: `spec ${issue.id} blocked`,
+                detail: `Gave up after ${MAX_ORPHAN_ATTEMPTS} orphaned refine attempts.`,
+                fields: [["issue", issue.id], ["title", issue.title]],
+            });
+            if (!deps.dryRun) {
+                await deps.provider.transition(issue, "blocked", `Gave up after ${MAX_ORPHAN_ATTEMPTS} orphaned refine attempts.`);
+                cleanupWorktree(deps, marker);
+            }
+        }
+    }
+}
 /** Poll every `review`-labeled issue's PR for merged (-> done) or closed-without-merging (-> blocked). */
 export async function finishReviews(deps) {
     const reviewing = await deps.provider.listInState("review", { includeAll: true });
@@ -231,6 +320,72 @@ async function runIssue(deps, issue) {
         cleanupWorktree(deps, { worktree: worktreePath, branch });
     }
 }
+/**
+ * One spec's full claim -> decompose -> publish path, run in the background
+ * — `claimSpecs` doesn't await this. The build lane's `runIssue`, minus the
+ * PR half: no `diffFiles` check (the refiner has `writes: []`, so an empty
+ * diff is the CORRECT outcome, not a failure), no push, no `openPr`. Its
+ * mirror image is "publish, then finish" instead of "commit, then review".
+ */
+async function runSpec(deps, issue) {
+    const branch = refineBranchNameFor(issue);
+    const worktreePath = specWorktreePathFor(deps, issue);
+    const adwId = `spec-${issue.id}`;
+    try {
+        // A spec re-claimed after a completed publish (the transition/comment
+        // that should have followed never ran — a crash, a kill) already has
+        // its answer on disk: skip straight to finishing rather than asking the
+        // refiner to redo work that already exists on the tracker. `to-tickets`
+        // (the skill this lane's prompt is ported from) has no such guard and
+        // would duplicate every issue on a re-run.
+        const existingMarker = await deps.provider.readMarker(issue);
+        if (existingMarker?.refined && existingMarker.refined.length > 0) {
+            deps.log(`watch: spec ${issue.id}: a previous attempt already published ${existingMarker.refined.length} issue(s) — finishing without re-running the refiner`);
+            await finishSpec(deps, issue, existingMarker.refined.map((id) => ({ id })));
+            return;
+        }
+        // See runIssue's identical comment: worktreePath/branch are deterministic
+        // from issue.id, so a leftover from a killed prior attempt is the only
+        // way either could already exist — clear it unconditionally.
+        cleanupWorktree(deps, { worktree: worktreePath, branch });
+        deps.git.fetch("origin", deps.baseBranch);
+        deps.git.worktreeAdd(worktreePath, branch, `origin/${deps.baseBranch}`);
+        deps.linkDataDir(worktreePath);
+        await deps.provider.writeMarker(issue, { worktree: worktreePath, branch, attempt: 0 });
+        const prompt = `${issue.title}\n\n${issue.body}`.trim();
+        const result = await deps.runRefine({ prompt, cwd: worktreePath, adwId, issueId: issue.id });
+        if (!result.accepted) {
+            deps.log(`watch: spec ${issue.id}: refine chain "${deps.refineChain}" did not succeed — blocked`);
+            const detail = result.detail || `Refine chain "${deps.refineChain}" (adw_id ${adwId}) did not complete successfully. Run \`spf phases ${adwId}\` for detail.`;
+            deps.notify({
+                kind: "issue_blocked",
+                level: "error",
+                title: `spec ${issue.id} blocked`,
+                detail,
+                fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.refineChain], ["adw_id", adwId]],
+            });
+            await deps.provider.transition(issue, "blocked", detail);
+            cleanupWorktree(deps, { worktree: worktreePath, branch });
+            return;
+        }
+        await deps.provider.writeMarker(issue, { worktree: worktreePath, branch, attempt: 0, refined: result.created.map((c) => c.id) });
+        await finishSpec(deps, issue, result.created);
+        cleanupWorktree(deps, { worktree: worktreePath, branch });
+    }
+    catch (error) {
+        const message = error.message;
+        deps.log(`watch: spec ${issue.id}: refine error: ${message}`);
+        deps.notify({
+            kind: "watch_error",
+            level: "error",
+            title: `spec ${issue.id} errored`,
+            detail: message,
+            fields: [["issue", issue.id], ["title", issue.title]],
+        });
+        await deps.provider.transition(issue, "blocked", `spf watch refine error: ${message}`).catch(() => undefined);
+        cleanupWorktree(deps, { worktree: worktreePath, branch });
+    }
+}
 /** Claim as many `ready` issues as the concurrency budget allows, and kick off `runIssue` for each in the background. */
 export async function claimNewWork(deps, state) {
     if (state.inflight.size >= deps.concurrency)
@@ -261,6 +416,38 @@ export async function claimNewWork(deps, state) {
         runIssue(deps, issue).finally(() => state.inflight.delete(issue.id));
     }
 }
+/** Claim as many `spec-ready` specs as `refineConcurrency` allows, and kick off `runSpec` for each in the background. A no-op when `watch.refine` is off. */
+export async function claimSpecs(deps, state) {
+    if (!deps.refineEnabled)
+        return;
+    if (state.refining.size >= deps.refineConcurrency)
+        return;
+    const eligible = await deps.provider.listInState("spec-ready");
+    for (const issue of eligible) {
+        if (state.refining.size >= deps.refineConcurrency)
+            break;
+        if (state.refining.has(issue.id))
+            continue;
+        if (deps.dryRun) {
+            deps.log(`watch: [dry-run] would claim spec ${issue.id} (${issue.title}) and run refine chain "${deps.refineChain}"`);
+            continue;
+        }
+        const claimed = await deps.provider.claim(issue, { from: "spec-ready", to: "refining" });
+        if (!claimed) {
+            deps.log(`watch: spec ${issue.id} lost the claim race this tick — skipping`);
+            continue;
+        }
+        deps.log(`watch: claimed spec ${issue.id}: ${issue.title}`);
+        deps.notify({
+            kind: "issue_claimed",
+            level: "info",
+            title: `spec ${issue.id} claimed`,
+            fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.refineChain]],
+        });
+        state.refining.add(issue.id);
+        runSpec(deps, issue).finally(() => state.refining.delete(issue.id));
+    }
+}
 function tickErrorHandler(deps, stage) {
     return (error) => {
         const message = error.message;
@@ -268,9 +455,11 @@ function tickErrorHandler(deps, stage) {
         deps.notify({ kind: "watch_error", level: "error", title: `watch: ${stage} error`, detail: message, fields: [] });
     };
 }
-/** One poll tick: reconcile, finish, claim — each independently caught, so one phase's error never blocks the rest. */
+/** One poll tick: reconcile both lanes, finish reviews, then claim both lanes — each stage independently caught, so one stage's error never blocks the rest. */
 export async function tick(deps, state) {
     await reconcileOrphans(deps, state).catch(tickErrorHandler(deps, "reconcileOrphans"));
+    await reconcileRefining(deps, state).catch(tickErrorHandler(deps, "reconcileRefining"));
     await finishReviews(deps).catch(tickErrorHandler(deps, "finishReviews"));
+    await claimSpecs(deps, state).catch(tickErrorHandler(deps, "claimSpecs"));
     await claimNewWork(deps, state).catch(tickErrorHandler(deps, "claimNewWork"));
 }

package/dist/test/chains.test.js

@@ -41,6 +41,7 @@ const EXPECTED = {
     },
     quality: { phases: "engineer(request) -> code(quality)", agents: [], suites: ["all"] },
     document: { phases: "engineer(request) -> code(changes) -> documenter", agents: ["documenter"], suites: [] },
+    refine: { phases: "engineer(request) -> refiner -> code(publish)", agents: ["refiner"], 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) " +

package/dist/test/init_command.test.js

@@ -64,3 +64,20 @@ test("never writes .env or .env.example on the non-interactive paths", async ()
     assert.equal(existsSync(join(dir, ".env")), false);
     assert.equal(existsSync(join(dir, ".env.example")), false);
 });
+test("also installs the repo-local Claude Code skill by default, on every non-interactive path", async () => {
+    const code = await initCommand(["--cwd", dir, "--yes"]);
+    assert.equal(code, 0);
+    assert.ok(existsSync(join(dir, ".claude", "skills", "spf", "SKILL.md")), "spf init should install the skill unless --no-skills is passed");
+});
+test("--no-skills skips the skill install", async () => {
+    const code = await initCommand(["--cwd", dir, "--yes", "--no-skills"]);
+    assert.equal(code, 0);
+    assert.equal(existsSync(join(dir, ".claude", "skills", "spf")), false);
+});
+test("re-running spf init doesn't re-copy an unchanged skill install (install-skill's own idempotency)", async () => {
+    await initCommand(["--cwd", dir, "--yes"]);
+    const manifestPath = join(dir, ".claude", "skills", "spf", ".spf-skill-version");
+    const before = readFileSync(manifestPath, "utf-8");
+    await initCommand(["--cwd", dir, "--template", "ts-cc"]); // no --force: config write is a no-op, skill install still runs
+    assert.equal(readFileSync(manifestPath, "utf-8"), before);
+});

package/dist/test/interview.test.js

@@ -233,15 +233,16 @@ test("customize models per agent: declining keeps today's behavior — only the
     for (const a of config.agents)
         assert.equal(a.model, "opus");
 });
-test("customize models per agent: accepting patches the pinned three and appends builder/scout", async () => {
+test("customize models per agent: accepting patches the pinned three and appends builder/scout/refiner", async () => {
     const ctx = gatherContext(dir, new Map());
-    assert.deepEqual(ctx.rosterNames.slice().sort(), ["builder", "documenter", "planner", "reviewer", "scout"]);
+    assert.deepEqual(ctx.rosterNames.slice().sort(), ["builder", "documenter", "planner", "refiner", "reviewer", "scout"]);
     const asker = createFakeAsker({
         select: { "backend runs": "claude_code", "Model (Claude": "sonnet", Authentication: "login" },
         text: {
             "  planner": "opus",
             "  builder": "sonnet",
             "  scout": "haiku",
+            "  refiner": "opus",
             "  reviewer": "opus",
             "  documenter": "sonnet",
         },
@@ -261,7 +262,7 @@ test("customize models per agent: accepting patches the pinned three and appends
     assert.ok(result);
     const config = result.config;
     const byName = Object.fromEntries(config.agents.map((a) => [a.name, a.model]));
-    assert.deepEqual(byName, { planner: "opus", reviewer: "opus", documenter: "sonnet", builder: "sonnet", scout: "haiku" });
+    assert.deepEqual(byName, { planner: "opus", reviewer: "opus", documenter: "sonnet", builder: "sonnet", scout: "haiku", refiner: "opus" });
     const configPath = mergedConfigPath();
     const { stringify } = await import("yaml");
     writeFileSync(configPath, stringify(config));

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")));
+});