@gr8ful/spf 0.3.0 → 0.5.0

package/dist/chains/simple_sdlc.js

@@ -8,7 +8,17 @@
  *         -> builder -> code(test) [-> builder(fix) -> code(test) ... bounded]
  *         -> reviewer [-> builder(revise) -> reviewer ... bounded]
  *         -> code(retest, only if a revision changed code)
- *         -> git(commit_build) -> code(changes) -> documenter -> git(commit_docs)
+ *         -> engineer(signoff) -> git(commit_build) -> code(changes) -> documenter -> git(commit_docs)
+ *
+ * The signoff phase is where "agent proposes, code disposes" gets literal:
+ * `review.approved` is the AI reviewer's PROPOSAL, and this chain's
+ * `commit_build` predicate is the only place in this codebase where such a
+ * proposal gates a commit at all (`build-review` has no commit step). A
+ * human at the keyboard DISPOSES of it — `decideSignoff` below — and their
+ * answer, not `review.approved`, becomes the final predicate. Unattended
+ * (`spf watch`, CI) has nobody to ask, so it either proceeds on the AI
+ * verdict alone with a loud warning, or fails the phase closed, depending on
+ * `review.require_human_signoff` — see that function's own comment.
  *
  * Three commits, three work products, three authors. The plan, the code, and the
  * write-up each land in their own commit, and each commit message is the words of
@@ -47,12 +57,95 @@ import * as changes from "../core/changes.js";
 import * as gates from "../core/gates.js";
 import * as quality from "../core/quality.js";
 import { DOCUMENT_NOTES } from "../core/prompts.js";
+import { createAsker, isInteractive } from "../cli/ask.js";
+import { paint } from "../core/console.js";
+import { committerIdentity } from "../core/git_helper.js";
 import { commitEnvelope, logChangeset, startRun } from "./steps.js";
 import { BuildOutput, DocumentOutput, PlanOutput, ReviewOutput, makeAgentCall, makeChangeCapture, makePhaseParams, } from "../core/data_types.js";
 export const REQUIRED_AGENTS = ["planner", "builder", "reviewer", "documenter"];
 export const REQUIRED_SUITES = ["test"];
 const MAX_FIX_LOOPS = 3;
 const MAX_REVISION_LOOPS = 2;
+// ── sign-off: agent proposes, code disposes, literally ──────────────────────
+/** Printed (never thrown) whenever this chain commits on `review.approved` alone — nobody answered. */
+export const AI_ONLY_SIGNOFF_WARNING = "committing on an AI-only verdict — set review.require_human_signoff or run attended";
+/**
+ * Turn the reviewer's `approved` PROPOSAL into a human DISPOSAL wherever a
+ * human is reachable; otherwise apply this release's documented default.
+ *
+ * Attended (`canPrompt`): shows the reviewer's findings and blocking list,
+ * then asks — default `false` (never `review.approved`: an AI's own verdict
+ * must never be its own auto-approval), bounded by
+ * `review.signoff_timeout_seconds` (expiry resolves to that same `false` —
+ * see `cli/ask.ts`'s `confirm`). The human's answer is the return value;
+ * `review.approved` never overrides it either way.
+ *
+ * Unattended or no TTY: nobody to ask, so `require_human_signoff` decides.
+ * `true` fails the phase CLOSED (throws) — this release will not let an
+ * unattended run manufacture a "yes" nobody gave it. `false` (this release's
+ * default) proceeds on `review.approved` alone, but never quietly: a loud
+ * warning prints AND is logged every time, because the day this default
+ * flips is the day silence here would have been the bug.
+ */
+export async function decideSignoff(params) {
+    const { review, canPrompt, requireHumanSignoff, signoffTimeoutSeconds, asker, identity, log, warn } = params;
+    if (!canPrompt) {
+        if (requireHumanSignoff) {
+            throw new Error("review.require_human_signoff is true but this run is unattended — rerun attended, " +
+                "or run via `spf watch`, where a human merges the PR instead of this phase.");
+        }
+        warn(paint("bold yellow", `⚠ ${AI_ONLY_SIGNOFF_WARNING}`));
+        log({
+            decision: "ai_only",
+            warning: AI_ONLY_SIGNOFF_WARNING,
+            human: false,
+            review_approved: review.approved,
+            blocking: review.blocking,
+            findings: review.findings,
+        });
+        return { accepted: review.approved, recordedYes: false };
+    }
+    if (!asker)
+        throw new Error("decideSignoff: canPrompt is true but no asker was supplied");
+    warn("");
+    warn(paint("bold", "── sign-off required before commit ──"));
+    for (const finding of review.findings) {
+        const mark = finding.met ? paint("green", "met") : paint("red", "MISSING");
+        warn(`  ${mark}  ${finding.requirement}${finding.evidence ? paint("dim", ` — ${finding.evidence}`) : ""}`);
+    }
+    if (review.blocking.length > 0) {
+        warn(paint("red", `  blocking: ${review.blocking.join("; ")}`));
+    }
+    warn("");
+    const accepted = await asker.confirm(identity ? `${identity.name}, approve and commit?` : "Approve and commit?", false, { timeoutMs: signoffTimeoutSeconds * 1000 });
+    log({
+        decision: accepted ? "approved" : "declined",
+        human: true,
+        engineer: identity?.name ?? null,
+        review_approved: review.approved,
+        blocking: review.blocking,
+        findings: review.findings,
+    });
+    if (accepted && !identity) {
+        warn(paint("dim", "  no git committer identity (user.name/user.email) is set — sign-off recorded, no Signed-off-by trailer"));
+        log({ note: "signoff recorded without a git committer identity — trailer skipped" });
+    }
+    return { accepted, recordedYes: accepted };
+}
+/**
+ * Whether `commit_build` may attach a `Signed-off-by:` trailer: only when
+ * the outcome recorded an explicit human "yes" (`recordedYes`) AND there is
+ * an identity to attest it with. Deliberately NOT `outcome.accepted` alone —
+ * the AI-only unattended path can also produce `accepted: true` (see
+ * `decideSignoff`'s unattended branch), and that path must never mint a
+ * trailer. Pulled out as its own named function, rather than inlined at the
+ * `commitEnvelope` call site, specifically so a refactor that swaps
+ * `recordedYes` for `verified`/`accepted` there breaks a test here instead
+ * of silently minting trailers for AI-only commits.
+ */
+export function trailerFor(outcome, identity) {
+    return outcome.recordedYes && identity ? identity : null;
+}
 export async function main(ctx) {
     const { prompt } = ctx;
     const run = startRun(ctx, REQUIRED_AGENTS, REQUIRED_SUITES);
@@ -113,9 +206,46 @@ export async function main(ctx) {
     // Red tests or a rejected review stop the chain here: the code stays
     // uncommitted and nothing is documented, because there is nothing worth
     // describing yet. The plan commit stands — it is a record of what was asked.
-    const verified = test !== null && test.passed && review !== null && review.approved;
+    const aiApproved = test !== null && test.passed && review !== null && review.approved;
+    // The sign-off phase — see decideSignoff's comment and the module header —
+    // only runs once the AI's own two gates (green suite, approved review) are
+    // both already met; it never runs to rescue a run that failed either one.
+    let verified = false;
+    let recordedYes = false;
+    let identity; // hoisted: commit_build reads this too, gated by recordedYes
+    if (aiApproved) {
+        const canPrompt = isInteractive() && !ctx.unattended; // amendment: never infer this from TTY state alone
+        identity = committerIdentity(run.repo_root);
+        const asker = canPrompt ? createAsker() : null;
+        try {
+            const outcome = await run.phase(makePhaseParams({
+                name: "signoff",
+                kind: "engineer",
+                owner: identity?.name || run.engineer,
+                description: "A human disposes of the AI reviewer's approval before anything commits",
+            }), (ph) => decideSignoff({
+                review: review,
+                canPrompt,
+                requireHumanSignoff: run.cfg.review.require_human_signoff,
+                signoffTimeoutSeconds: run.cfg.review.signoff_timeout_seconds,
+                asker,
+                identity,
+                log: (payload) => ph.log(payload),
+                warn: (line) => console.log(line),
+            }));
+            verified = outcome.accepted;
+            recordedYes = outcome.recordedYes;
+        }
+        finally {
+            asker?.close();
+        }
+    }
     if (verified) {
-        await run.phase(makePhaseParams({ name: "commit_build", kind: "code", owner: "git", description: "Land the code only now: green suite, approved review" }), async (ph) => commitEnvelope(run, ph, build));
+        await run.phase(makePhaseParams({ name: "commit_build", kind: "code", owner: "git", description: "Land the code only now: green suite, approved review, human sign-off" }), 
+        // trailerFor gates the trailer on recordedYes, not just `verified` — see
+        // its own comment: a Signed-off-by line must trace back to an explicit
+        // "yes", never to the AI-only path (where `verified` can also be true).
+        async (ph) => commitEnvelope(run, ph, build, trailerFor({ accepted: verified, recordedYes }, identity)));
         const changeset = await run.phase(makePhaseParams({ name: "changes", kind: "code", owner: "git", description: "Diff the whole run against its pinned baseline, for the documenter" }), async (ph) => {
             const result = changes.capture(run, makeChangeCapture({ base: baseline }));
             logChangeset(ph, result);
@@ -132,5 +262,5 @@ export async function main(ctx) {
         })));
         await run.phase(makePhaseParams({ name: "commit_docs", kind: "code", owner: "git", description: "Ship the write-up in its own commit, beside the code it describes" }), async (ph) => commitEnvelope(run, ph, document));
     }
-    return run.finish(verified, "the suite or the review never came back clean");
+    return run.finish(verified, "the suite or the review never came back clean, or sign-off never came");
 }

package/dist/chains/steps.d.ts

@@ -16,14 +16,35 @@
  * The loops (`fixLoop`, `reviseLoop`) own their bounded iteration and dynamic
  * phase naming (`test_1`, `fix_1`, ...) INTERNALLY — a chain's step list is
  * therefore always flat, with no loop or conditional syntax at the
- * composition layer. That is what would make a future declarative (YAML)
- * chain tractable: it would only ever need to name steps and pass them
- * tuning params, never express control flow.
+ * composition layer. That is what makes a declarative (YAML) chain
+ * tractable: it only ever names steps and passes them tuning params, never
+ * expresses control flow. `chains/repo_chains.ts` is that reader — every
+ * factory below is a name a `.spf/chains/*.yaml` file may use, and its
+ * `opts` object is that step's entire vocabulary.
+ *
+ * Consequences of being that vocabulary, all of which apply to the code
+ * below and none of which are cosmetic:
+ *
+ *  - EVERY DEFAULT IS A PUBLISHED DEFAULT. `src/test/chains.test.ts` pins the
+ *    exact `phases`/`requiredAgents`/`requiredSuites` strings every built-in
+ *    chain derives from these factories. A factory called with no opts must
+ *    keep producing byte-identical output forever; if a default label moves,
+ *    that is a bug in this file, not in the test.
+ *  - PARAMS ADD, THEY DO NOT SUBTRACT. A repo-local chain is data supplied by
+ *    the target repo; it may widen what a step does (an extra gate, a
+ *    different owner, more retries) but it must never be able to weaken the
+ *    checks spf itself imposes. See GATE_ALLOWLIST below for the one place
+ *    that rule bites hardest.
+ *  - A BAD PARAM MUST FAIL AT DEFINITION TIME. A factory validates what it
+ *    can the moment it is called (see `preflightDescription`), so a malformed
+ *    chain is a load-time problem the loader can report against a file and a
+ *    line, never a phase that blows up ten minutes into an unattended run.
  */
-import { type EnvelopeBase, type QualityResult, type ReviewOutputT } from "../core/data_types.ts";
+import { type EnvelopeBase, type GateFn, type QualityResult, type ReviewOutputT } from "../core/data_types.ts";
 import type { ChangeSet } from "../core/data_types.ts";
 import { Run, type PhaseHandle } from "../core/runner.ts";
 import type { ChainContext } from "./context.ts";
+import type { CommitterIdentity } from "../core/git_helper.ts";
 /** What one step hands the next — the parts of a hand-written chain's local variables. */
 export interface ChainState {
     prompt: string;
@@ -35,6 +56,12 @@ export interface ChainState {
     changeset: ChangeSet | null;
     /** HEAD, pinned by request({logBaseline: true}) before the run commits anything. */
     baseline: string;
+    /**
+     * The originating tracker issue, only meaningful to `publishIssues()` —
+     * lifted from `ChainContext.issue_id` (see its doc comment) because a
+     * `Step` only ever sees `(run, state)`, never the `ChainContext` itself.
+     */
+    issue_id: string | null;
     /** The run's own acceptance criterion — distinct from "every phase succeeded"; see Run.finish(). */
     accepted: boolean;
     /** Why not, when accepted is false — passed straight to run.finish(). */
@@ -50,67 +77,259 @@ export interface ChainState {
 export interface Step {
     (run: Run, state: ChainState): Promise<void>;
     requiredAgents?: string[] | ((options: Record<string, string>) => string[]);
-    requiredSuites?: string[];
+    /** Static for most quality/fixLoop steps; dynamic wherever --suite can override the compiled-in default (see qualityCheck/fixLoop). */
+    requiredSuites?: string[] | ((options: Record<string, string>) => string[]);
     /** Display fragment for derivePhases() — e.g. "planner", "git(commit)". */
     label?: string;
 }
 /** The identical loadConfig -> validate -> session.ensure prologue every chain repeated. */
 export declare function startRun(ctx: ChainContext, requiredAgents: string[], requiredSuites: string[]): Run;
-/** Commit an envelope in its own author's words — the message-fallback four chains repeated. */
+/**
+ * Commit an envelope in its own author's words — the message-fallback four
+ * chains repeated.
+ *
+ * `signoff`, when passed, MUST be a human's own recorded explicit "yes" —
+ * see `chains/simple_sdlc.ts`'s `decideSignoff`, the only caller that ever
+ * passes one. It is appended as a real `Signed-off-by:` trailer (blank-line
+ * separated, or joined into an existing trailer block — see
+ * `appendTrailer`). Every other caller (every chain built from `./steps.ts`'s
+ * own `commit()`, plus `simple_sdlc`'s `commit_plan`/`commit_docs`) passes
+ * nothing, because nothing gates those commits on an AI verdict — the
+ * `fixLoop` chains gate on tests, which is the philosophy working. Omitted
+ * -> no trailer, ever: a trailer that lies launders an AI verdict into a git
+ * attestation.
+ */
 export declare function commitEnvelope(run: Run, ph: PhaseHandle, envelope: EnvelopeBase & {
     commit_message?: string;
-}): void;
+}, signoff?: CommitterIdentity | null): void;
 /** Log a change-capture result the same way every chain that captures one did. */
 export declare function logChangeset(ph: PhaseHandle, result: ChangeSet): void;
+/**
+ * The gates a chain definition is allowed to name, by name.
+ *
+ * An EXPLICIT map, not `gates` itself and not a lookup on `gates[name]`:
+ * `core/gates.ts` is a module of exported functions, and reflecting over it
+ * would silently promote every future export (and every internal helper that
+ * ever gets exported for a test) into the surface a target repo's YAML can
+ * reach. Adding a gate to this map is a deliberate, reviewable act.
+ *
+ * CRITICAL POLICY — this map backs `extraGates`, which is ADDITIVE ONLY. A
+ * step's built-in gates are NON-REMOVABLE: there is no `gates:` param that
+ * replaces them, and there must never be one.
+ *
+ * The reason is what a repo-local chain IS. SPF's contract is "agent
+ * proposes, code disposes", and the code that disposes is SPF'S code — that
+ * is precisely why chains load as data (YAML naming these factories) instead
+ * of as imported repo code. A `gates: []` override would hand that back:
+ * the target repo would be editing its own disposer, and the first thing
+ * anyone under deadline pressure deletes is the gate that keeps failing —
+ * `diffMatchesClaims` (the builder claimed files it never wrote) or
+ * `verdictConsistent` (the reviewer approved while listing blockers).
+ * Those two are exactly the checks that catch an agent grading its own
+ * homework, and `spf watch` runs chains UNATTENDED (see
+ * `ChainContext.unattended`), so nobody is at the console to notice they
+ * stopped running. A weaker chain must therefore be un-expressible, not
+ * merely discouraged.
+ *
+ * `gates.testsPass` is deliberately absent: it is a FACTORY over a shell
+ * command string, so allowing it by name would mean letting a YAML file
+ * name an arbitrary command to execute inside a gate. Commands belong in
+ * `quality.checks`/`quality.suites` in spf.config.yaml, where
+ * `core/quality.ts` owns them and `core/permissions.ts` applies. If a
+ * command-running gate is ever wanted here, it needs its own param with its
+ * own review, not an entry in this map.
+ */
+export declare const GATE_ALLOWLIST: Readonly<Record<string, GateFn>>;
+/** Every name a chain definition may put in SOME `extraGates` param — for the module-level backstop in `resolveExtraGates` only. Schema validation must use the narrower, per-param lists below, never this one. */
+export declare const GATE_NAMES: readonly string[];
+/**
+ * Which gate names are meaningful on which envelope shape — the missing
+ * per-step subset `GATE_ALLOWLIST` never had. `GATE_ALLOWLIST` says "these
+ * functions exist and are the ones a chain may ever name"; these three lists
+ * say "here is the subset that reads fields THIS envelope actually has."
+ *
+ * `artifactsExist`/`filesNonEmpty`/`jsonParses` only ever read
+ * `envelope.artifacts`, which every envelope has (see `EnvelopeBase`) — safe
+ * anywhere. `diffMatchesClaims` reads `changed_files`, which only a
+ * `BuildOutput`-shaped envelope populates; naming it on a step whose
+ * envelope is something else (e.g. a review) makes it read an absent field
+ * as `[]` and pass vacuously — silent, not a real check. `verdictConsistent`
+ * reads `approved`/`blocking`/`findings`, which only a review envelope
+ * populates; on anything else its "rejection names a problem" check reads
+ * `approved: false` with nothing to blame and fails EVERY time, which is
+ * exactly the shape of bug this module exists to make load-time-visible
+ * instead of run-time-fatal.
+ */
+export declare const GENERIC_GATE_NAMES: readonly string[];
+export declare const BUILD_ENVELOPE_GATE_NAMES: readonly string[];
+export declare const REVIEW_ENVELOPE_GATE_NAMES: readonly string[];
 /** The engineer(request) phase every chain opens with. */
 export declare function request(opts?: {
     description?: string;
     logBaseline?: boolean;
 }): Step;
-export declare function plan(): Step;
+/**
+ * `owner` names WHO plans, defaulting to the `planner` agent. It flows
+ * straight into `agentStep`'s existing owner argument, which is also what
+ * `makeStep` records as `requiredAgents` and as the display `label` — so a
+ * chain that plans with a differently-named agent updates its own
+ * `spf list` line and its own config validation with no second place to
+ * edit. Same shape for `build`/`scout`/`document` below.
+ */
+export declare function plan(opts?: {
+    owner?: string;
+    description?: string;
+    retries?: number;
+    extraGates?: string[];
+}): Step;
 /**
  * `fromPlan` only changes the description — whether a plan() step precedes
  * this one already decides whether `state.previous` is a plan or null, so
- * there is nothing else for this flag to gate.
+ * there is nothing else for this flag to gate. An explicit `description`
+ * therefore makes `fromPlan` moot; it is still accepted rather than made
+ * mutually exclusive, because the two chains that pass `fromPlan` today read
+ * better for it and a definition that sets both is not ambiguous (the
+ * explicit text wins).
  */
 export declare function build(opts?: {
     fromPlan?: boolean;
+    owner?: string;
+    description?: string;
     retries?: number;
+    extraGates?: string[];
 }): Step;
-export declare function scout(): Step;
-/** The `prompt` chain's one step: --agent picks who, at run time and at requiredAgents-derivation time alike. */
-export declare function promptOnly(): Step;
-/** One deterministic quality block, standalone — never throws; sets state.accepted for run.finish() to check. */
+export declare function scout(opts?: {
+    owner?: string;
+    description?: string;
+    retries?: number;
+    extraGates?: string[];
+}): Step;
+/**
+ * The `prompt` chain's one step: --agent picks who, at run time and at
+ * requiredAgents-derivation time alike.
+ *
+ * No `owner` param, unlike the steps above: this step's whole purpose is
+ * that the OPERATOR chooses the agent at invocation time, so an owner baked
+ * into a definition would defeat it. A chain that wants a fixed agent
+ * already has one — that is what `plan`/`build`/`scout` with an `owner` are.
+ * `extraGates` is accepted (the default is genuinely no gates — a generic
+ * envelope claims nothing specific) so a definition can still demand, say,
+ * that whatever files the agent claims actually exist.
+ */
+export declare function promptOnly(opts?: {
+    description?: string;
+    retries?: number;
+    extraGates?: string[];
+}): Step;
+/**
+ * One deterministic quality block, standalone — never throws; sets
+ * state.accepted for run.finish() to check.
+ *
+ * `opts.suite` names any suite in `quality.suites`, not just "test"/"all" —
+ * those two keep their historical phase name ("test"/"quality") and
+ * description; any other configured suite name is used verbatim for both, so
+ * a chain naming a custom suite still reads truthfully in its trace and in
+ * `spf list`. `--suite` (see run.ts) overrides the compiled-in default at
+ * invocation time, the same way `promptOnly()` lets `--agent` override its
+ * owner.
+ */
 export declare function qualityCheck(opts?: {
-    suite: "test" | "all";
+    suite: string;
     description?: string;
 }): Step;
 /**
  * Bounded check -> fix loop: a known command finds the failure, the builder
  * repairs it. Always guards the last iteration — a fix on the final attempt
  * is never re-verified, so it is never spawned. Sets state.accepted/reason.
+ *
+ * `opts.suite` names any suite in `quality.suites` — "all" alone keeps its
+ * historical "verify"/"verification" naming; every other suite (including
+ * the default, "test") is named for itself, exactly as in `qualityCheck()`.
+ * `--suite` (run.ts) overrides the compiled-in default at invocation time.
  */
 export declare function fixLoop(opts?: {
-    suite: "test" | "all";
+    suite: string;
     max?: number;
     owner?: string;
+    /** The suite phase's description (`test_1`, `verify_1`, ...). */
+    description?: string;
+    /** The repair phase's description (`fix_1`, ...) — a separate phase, so a separate override. */
+    fixDescription?: string;
+    fixRetries?: number;
+    fixExtraGates?: string[];
 }): Step;
-/** Bounded review -> revise loop. Sets state.accepted/reason from the final verdict. */
+/**
+ * Bounded review -> revise loop. Sets state.accepted/reason from the final
+ * verdict.
+ *
+ * `reviewer`/`builder` name the two agents by role, defaulting to the agents
+ * literally called "reviewer" and "builder". They are two params rather than
+ * one because the whole point of this loop is that the critic and the author
+ * are DIFFERENT agents — a chain that points both at the same name has an
+ * agent reviewing its own work, which is the failure mode
+ * `gates.verdictConsistent` exists to make visible. Nothing here enforces
+ * that they differ (a repo may legitimately have one strong agent and want
+ * the self-review anyway), but the trace will say so plainly: the derived
+ * label below is built from these names, so `spf list` and the run's phases
+ * both read `x [-> x(revise) -> x ...]`.
+ */
 export declare function reviseLoop(opts?: {
     max?: number;
+    reviewer?: string;
+    builder?: string;
+    /** The review phase's description (`review_1`, ...). */
+    description?: string;
+    retries?: number;
+    extraGates?: string[];
+    /** The revise phase's description (`revise_1`, ...) — a separate phase, so a separate override. */
+    reviseDescription?: string;
+    reviseRetries?: number;
+    reviseExtraGates?: string[];
 }): Step;
 /** Commit the last agent step's envelope. `onlyIfAccepted` gates it on state.accepted (a preceding fixLoop/reviseLoop). */
 export declare function commit(opts?: {
     onlyIfAccepted?: boolean;
+    description?: string;
 }): Step;
 /** Diff the working tree against a base ref — code, not judgement. `--base` (default "main") if opts.base is unset. */
 export declare function changes(opts?: {
     base?: string;
+    description?: string;
 }): Step;
 /** Write up the captured change. Requires a preceding changes() step. */
-export declare function document(): Step;
+export declare function document(opts?: {
+    owner?: string;
+    description?: string;
+    retries?: number;
+    extraGates?: string[];
+}): Step;
+/** Decompose the spec in `prompt` into a feature/story tree — see `RefinedIssueSchema`'s doc comment. Gated so a malformed tree (wrong container/leaf kinds, an unresolved reference, a dependency cycle) re-prompts the same session before publishIssues() ever runs. */
+export declare function refine(opts?: {
+    owner?: string;
+    description?: string;
+    retries?: number;
+    extraGates?: string[];
+}): Step;
+/**
+ * Create the tree `refine()` produced on the tracker, in dependency order,
+ * and link each node to its parent. A `code` phase, not an agent one — the
+ * decision-making (topological order, label assignment, `## Blocked by`
+ * rendering) is `core/refine.ts`'s job; this step is sequencing only, per
+ * SKILL.md's "chains stay thin" rule. Requires a preceding refine() step.
+ *
+ * Writes what it created to `<context_handoff_dir>/refine_publish.json` —
+ * the side channel `cli/commands/watch.ts`'s `runRefine` reads after the
+ * chain returns, since a chain's own return value is just an exit code.
+ * `spf watch`'s own marker/comment/transition bookkeeping for the spec
+ * issue lives entirely in `core/watch.ts`'s `runSpec`, never here — a bare
+ * `spf refine` run (no daemon, no spec issue in play) still needs this step
+ * to work standalone.
+ */
+export declare function publishIssues(opts?: {
+    description?: string;
+}): Step;
 export declare function deriveRequiredAgents(steps: Step[]): string[] | ((options: Record<string, string>) => string[]);
-export declare function deriveRequiredSuites(steps: Step[]): string[];
+export declare function deriveRequiredSuites(steps: Step[]): string[] | ((options: Record<string, string>) => string[]);
 /** A display string for `spf list` — derived so it can no longer drift from what actually runs. */
 export declare function derivePhases(steps: Step[]): string;
 /** Run a chain's step list start to finish: prologue, every step in order, then run.finish(). */