@gr8ful/spf 0.3.0 → 0.5.0

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 });
@@ -195,6 +284,15 @@ async function runIssue(deps, issue) {
             return;
         }
         wtGit.push("origin", branch);
+        // The human merging this PR sees whatever the reviewer found — or, if
+        // nothing reviewed this change at all, is told that plainly rather than
+        // left to assume a silent approval. `reviewSummary` is already
+        // sanitized/truncated by the caller (see runChain's own doc comment).
+        const reviewLine = result.reviewSummary
+            ? result.reviewSummary
+            : result.reviewRequired
+                ? "Reviewer ran, but no verdict could be read back from the session data."
+                : `Nothing reviewed this change — chain \`${deps.chain}\` has no reviewer step.`;
         // 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
@@ -203,7 +301,7 @@ async function runIssue(deps, issue) {
         const pr = await deps.codeHost.openPr({
             branch,
             title: `${issue.title} (${issue.id})`,
-            body: `Automated by \`spf watch\` — chain \`${deps.chain}\`, adw_id \`${adwId}\`, issue ${issue.id}.`,
+            body: `Automated by \`spf watch\` — chain \`${deps.chain}\`, adw_id \`${adwId}\`, issue ${issue.id}.\n\n${reviewLine}`,
             base: deps.baseBranch,
         });
         await deps.provider.writeMarker(issue, { worktree: worktreePath, branch, pr: pr.number, attempt: 0 });
@@ -213,7 +311,13 @@ async function runIssue(deps, issue) {
             kind: "pr_opened",
             level: "info",
             title: `PR #${pr.number} opened`,
-            fields: [["issue", issue.id], ["title", issue.title], ["chain", deps.chain]],
+            detail: reviewLine,
+            fields: [
+                ["issue", issue.id],
+                ["title", issue.title],
+                ["chain", deps.chain],
+                ["review", result.reviewSummary ? "reviewed" : result.reviewRequired ? "reviewer ran, no verdict" : "not reviewed"],
+            ],
             url: pr.url || undefined,
         });
     }
@@ -231,6 +335,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 +431,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 +470,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

@@ -11,7 +11,7 @@
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { CHAINS, findChain, resolveRequiredAgents } from "../chains/index.js";
+import { CHAINS, findChain, resolveRequiredAgents, resolveRequiredSuites } from "../chains/index.js";
 // name -> [phases, requiredAgents (with no options), requiredSuites]
 const EXPECTED = {
     prompt: { phases: "engineer(request) -> <agent>", agents: ["builder"], suites: [] },
@@ -41,9 +41,10 @@ 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) " +
+            "-> reviewer [-> builder(revise) -> reviewer ...] -> code(retest, if revised) -> engineer(signoff) -> git(commit_build) " +
             "-> code(changes) -> documenter -> git(commit_docs)",
         agents: ["planner", "builder", "reviewer", "documenter"],
         suites: ["test"],
@@ -58,7 +59,7 @@ for (const chain of CHAINS) {
     test(`${chain.name}: derived phases/requiredAgents/requiredSuites match what was hand-verified against \`spf list\``, () => {
         assert.equal(chain.phases, expected.phases);
         assert.deepEqual(resolveRequiredAgents(chain, {}), expected.agents);
-        assert.deepEqual(chain.requiredSuites, expected.suites);
+        assert.deepEqual(resolveRequiredSuites(chain, {}), expected.suites);
     });
 }
 test("prompt: requiredAgents depends on --agent, not a fixed list — the one dynamic case", () => {
@@ -66,6 +67,11 @@ test("prompt: requiredAgents depends on --agent, not a fixed list — the one dy
     assert.deepEqual(resolveRequiredAgents(chain, {}), ["builder"], "no --agent -> falls back to builder");
     assert.deepEqual(resolveRequiredAgents(chain, { agent: "planner" }), ["planner"], "--agent overrides the default");
 });
+test("plan-build-test: requiredSuites depends on --suite, the same way prompt's agent does", () => {
+    const chain = findChain("plan-build-test");
+    assert.deepEqual(resolveRequiredSuites(chain, {}), ["test"], "no --suite -> falls back to the compiled-in default");
+    assert.deepEqual(resolveRequiredSuites(chain, { suite: "custom" }), ["custom"], "--suite overrides the default");
+});
 test("every chain but simple-sdlc is a steps list; simple-sdlc alone uses the imperative run() escape hatch", () => {
     for (const chain of CHAINS) {
         if (chain.name === "simple-sdlc") {

package/dist/test/data_types.test.js

@@ -14,8 +14,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as v from "valibot";
 import { toJsonSchema } from "@valibot/to-json-schema";
-import { AgentConfigSchema, BuildOutput, ChangesOutput, DocumentOutput, GenericOutput, NotificationsConfigSchema, PhaseParamsSchema, PlanOutput, ReviewOutput, ScoutOutput, VerifyOutput, makePhaseParams, } from "../core/data_types.js";
-import { loadConfig } from "../core/agents.js";
+import { AgentConfigSchema, BuildOutput, ChangesOutput, DocumentOutput, EventRecordTypeSchema, GenericOutput, NotificationsConfigSchema, PhaseParamsSchema, PlanOutput, ReviewConfigSchema, ReviewOutput, ScoutOutput, VerifyOutput, makePhaseParams, } from "../core/data_types.js";
+import { agentEnv, loadConfig } from "../core/agents.js";
 test("writes: three-state semantics — absent, null, and [] all mean something different", () => {
     const base = { name: "builder", prompt_engineering: { system: "s.md", user: "u.md" } };
     const unrestricted = v.parse(AgentConfigSchema, base);
@@ -80,3 +80,141 @@ test("notifications survives loadConfig's merge — key-by-key like observabilit
         rmSync(dir, { recursive: true, force: true });
     }
 });
+test("ReviewConfigSchema: defaults to require_human_signoff=false, signoff_timeout_seconds=300", () => {
+    const parsed = v.parse(ReviewConfigSchema, {});
+    assert.equal(parsed.require_human_signoff, false, "this release fails OPEN by default — see the schema's own doc comment");
+    assert.equal(parsed.signoff_timeout_seconds, 300);
+});
+// The silent-drop trap: mergeRawConfig (core/agents.ts) is a FIXED-SHAPE
+// object literal, so a `review:` key in a real config file that isn't named
+// on both sides of that literal is dropped before SFConfigSchema ever sees
+// it — parsing would then succeed anyway, quietly, on the schema default.
+// This is adversarial history on this branch, not a hypothetical: it is
+// exactly the bug `observability`/`notifications` already guard against, and
+// `review` gets the same guard the day it is added.
+test("review survives loadConfig's merge — the silent-drop trap mergeRawConfig's fixed-shape literal sets, for a single config file", () => {
+    const dir = mkdtempSync(join(tmpdir(), "spf-review-merge-test-"));
+    try {
+        const configPath = join(dir, "spf.config.yaml");
+        writeFileSync(configPath, "review:\n  require_human_signoff: true\n  signoff_timeout_seconds: 45\n");
+        const cfg = loadConfig([configPath]);
+        assert.equal(cfg.review.require_human_signoff, true, "a review: value from a real config file must reach SFConfig, not be dropped by mergeRawConfig's object literal");
+        assert.equal(cfg.review.signoff_timeout_seconds, 45);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("review merges key-by-key across two layered config files, like observability/notifications", () => {
+    const dir = mkdtempSync(join(tmpdir(), "spf-review-merge-layered-test-"));
+    try {
+        const base = join(dir, "base.yaml");
+        const override = join(dir, "override.yaml");
+        writeFileSync(base, "review:\n  require_human_signoff: false\n  signoff_timeout_seconds: 120\n");
+        writeFileSync(override, "review:\n  require_human_signoff: true\n");
+        const cfg = loadConfig([base, override]);
+        assert.equal(cfg.review.require_human_signoff, true, "override wins for the key it names");
+        assert.equal(cfg.review.signoff_timeout_seconds, 120, "unset in the override -> the base's value survives, key-by-key, not a whole-block replace");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+// observability.otel is the one nested OBJECT under a top-level key that
+// mergeRawConfig spreads field-by-field, so its merge semantics differ from its
+// siblings' and are worth pinning: `otel:` is replaced as a WHOLE OBJECT by an
+// override that names it (you never want a half-merged endpoint/headers pair —
+// that is how an auth token gets POSTed to the wrong collector), while
+// `observability`'s other keys still merge key-by-key around it. Also the
+// activation contract: absent by default, so no repo starts exporting because
+// it upgraded.
+test("observability.otel survives loadConfig's merge — absent by default, whole-object replace on override", () => {
+    const dir = mkdtempSync(join(tmpdir(), "spf-otel-merge-test-"));
+    try {
+        const bare = join(dir, "bare.yaml");
+        writeFileSync(bare, "observability:\n  poll_ms: 250\n");
+        assert.equal(loadConfig([bare]).observability.otel, undefined, "no otel: block -> export stays off, the default for every repo");
+        const base = join(dir, "base.yaml");
+        const override = join(dir, "override.yaml");
+        writeFileSync(base, "observability:\n  poll_ms: 250\n  otel:\n    endpoint: http://base-collector:4318/v1/traces\n    headers: {authorization: base-token}\n    service_name: base\n");
+        writeFileSync(override, "observability:\n  otel:\n    endpoint: http://override-collector:4318/v1/traces\n");
+        const cfg = loadConfig([base, override]);
+        assert.equal(cfg.observability.poll_ms, 250, "observability's other keys still merge key-by-key around otel");
+        assert.equal(cfg.observability.otel?.endpoint, "http://override-collector:4318/v1/traces");
+        assert.equal(cfg.observability.otel?.headers, undefined, "whole-object replace: the base's auth header does NOT follow the override's endpoint");
+        assert.equal(cfg.observability.otel?.service_name, "spf", "and the base's service_name doesn't either — the schema default applies");
+        // A single config file must reach SFConfig at all — the silent-drop trap
+        // mergeRawConfig's fixed-shape object literal sets for any new key.
+        const single = join(dir, "single.yaml");
+        writeFileSync(single, "observability:\n  otel:\n    endpoint: https://collector.example.com/v1/traces\n");
+        assert.equal(loadConfig([single]).observability.otel?.endpoint, "https://collector.example.com/v1/traces");
+        // A typo fails at config load, not as a silent per-run export failure.
+        const bad = join(dir, "bad.yaml");
+        writeFileSync(bad, "observability:\n  otel:\n    endpoint: not-a-url\n");
+        assert.throws(() => loadConfig([bad]), /invalid config/, "endpoint is URL-validated");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("EventRecordTypeSchema accepts every observed event type and rejects an unknown one", () => {
+    for (const type of ["phase_start", "agent_start", "tool_call", "handoff", "gate_pass", "gate_fail", "log", "agent_end", "phase_end", "error"]) {
+        assert.equal(v.parse(EventRecordTypeSchema, type), type);
+    }
+    assert.throws(() => v.parse(EventRecordTypeSchema, "bogus_type"), "an event type outside the observed set must be rejected, not silently stored");
+});
+test("AgentConfigSchema: env_allowlist is optional and defaults to undefined (byte-identical to before this field existed)", () => {
+    const base = { name: "builder", prompt_engineering: { system: "s.md", user: "u.md" } };
+    const unset = v.parse(AgentConfigSchema, base);
+    assert.equal(unset.env_allowlist, undefined);
+    const allowlisted = v.parse(AgentConfigSchema, { ...base, env_allowlist: ["MY_API_KEY"] });
+    assert.deepEqual(allowlisted.env_allowlist, ["MY_API_KEY"]);
+    const nulled = v.parse(AgentConfigSchema, { ...base, env_allowlist: null });
+    assert.equal(nulled.env_allowlist, null, "null must parse (the 'unrestricted' spelling config.md teaches for writes)");
+});
+// This is the load-bearing half of the field: the schema merely declares
+// the shape, agentEnv() is what actually filters the operator's own
+// environment down to the allowlist. A test that only exercised the schema
+// (as the previous version of this test did) would never notice agentEnv
+// silently failing to filter anything.
+test("agentEnv: filters the operator environment down to the allowlist plus the baseline keys", () => {
+    const base = { name: "builder", prompt_engineering: { system: "s.md", user: "u.md" } };
+    const savedApiKey = process.env["MY_API_KEY"];
+    const savedSecret = process.env["SECRET_TOKEN"];
+    try {
+        process.env["MY_API_KEY"] = "abc123";
+        process.env["SECRET_TOKEN"] = "should-never-appear";
+        // unset -> undefined: both backends fall back to `request.env ?? operatorEnv()`,
+        // so this is byte-identical to the unfiltered behavior that predates the field.
+        const unset = v.parse(AgentConfigSchema, base);
+        assert.equal(agentEnv(unset), undefined);
+        // [] -> baseline-only: every ENV_BASELINE_KEYS entry actually present in
+        // process.env, and nothing else — SECRET_TOKEN must not leak through.
+        const empty = v.parse(AgentConfigSchema, { ...base, env_allowlist: [] });
+        const baselineOnly = agentEnv(empty);
+        const baselineKeys = ["PATH", "HOME", "USER", "LANG", "TERM", "TMPDIR"];
+        for (const key of Object.keys(baselineOnly)) {
+            assert.ok(baselineKeys.includes(key), `${key} is not a baseline key — [] must yield baseline-only`);
+        }
+        assert.equal(baselineOnly["SECRET_TOKEN"], undefined);
+        assert.equal(baselineOnly["MY_API_KEY"], undefined);
+        // ["MY_API_KEY"] -> baseline + MY_API_KEY, with SECRET_TOKEN provably absent.
+        const allowlisted = v.parse(AgentConfigSchema, { ...base, env_allowlist: ["MY_API_KEY"] });
+        const filtered = agentEnv(allowlisted);
+        assert.equal(filtered["MY_API_KEY"], "abc123");
+        assert.equal(filtered["SECRET_TOKEN"], undefined, "an unrelated secret must not survive the filter");
+        for (const key of Object.keys(filtered)) {
+            assert.ok(baselineKeys.includes(key) || key === "MY_API_KEY", `${key} leaked through the allowlist unexpectedly`);
+        }
+    }
+    finally {
+        if (savedApiKey === undefined)
+            delete process.env["MY_API_KEY"];
+        else
+            process.env["MY_API_KEY"] = savedApiKey;
+        if (savedSecret === undefined)
+            delete process.env["SECRET_TOKEN"];
+        else
+            process.env["SECRET_TOKEN"] = savedSecret;
+    }
+});

package/dist/test/git_helper.test.d.ts

@@ -0,0 +1 @@
+import "./hermetic_git.ts";

package/dist/test/git_helper.test.js

@@ -0,0 +1,59 @@
+import "./hermetic_git.js";
+/**
+ * `findRepoRoot()`'s contract is "never throws, always returns some root."
+ * `isRepoAt()` only proves `git rev-parse --git-dir` succeeds, which is also
+ * true inside a bare repo and inside a `.git/` directory itself — neither
+ * has a work tree, so the follow-up `--show-toplevel` call fails there even
+ * though `isRepoAt()` said yes. Regression coverage for that gap: before the
+ * fix, `findRepoRoot()` let that failure propagate as an uncaught throw,
+ * which — because `cli/index.ts` calls `paths.resolveAnchor()` outside its
+ * top-level try/catch — crashed every command (including `spf --version`)
+ * when run from a bare repo or from inside `.git/`.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { findRepoRoot } from "../core/git_helper.js";
+test("findRepoRoot falls back to cwd inside a bare repo (no work tree)", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "spf-bare-"));
+    try {
+        execFileSync("git", ["init", "--bare", dir], { stdio: "ignore" });
+        const root = findRepoRoot(dir);
+        assert.equal(root, path.resolve(dir));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("findRepoRoot falls back to cwd inside a repo's .git directory", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "spf-dotgit-"));
+    try {
+        execFileSync("git", ["init"], { cwd: dir, stdio: "ignore" });
+        const gitDir = path.join(dir, ".git");
+        const root = findRepoRoot(gitDir);
+        assert.equal(root, path.resolve(gitDir));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("findRepoRoot resolves the toplevel of an ordinary work tree", () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "spf-worktree-"));
+    try {
+        execFileSync("git", ["init"], { cwd: dir, stdio: "ignore" });
+        const sub = path.join(dir, "nested");
+        execFileSync("node", ["-e", `require("fs").mkdirSync(${JSON.stringify(sub)})`]);
+        const root = findRepoRoot(sub);
+        // git may resolve symlinked tmpdirs (e.g. macOS /tmp -> /private/tmp) —
+        // compare against what git itself reports as the raw toplevel is what
+        // resolveAnchor ultimately does too, so lean on findRepoRoot from the
+        // repo root itself for a stable assertion.
+        assert.equal(root, findRepoRoot(dir));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});

package/dist/test/hermetic_git.d.ts

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

package/dist/test/hermetic_git.js

@@ -0,0 +1,22 @@
+/**
+ * Import this FIRST in any test file that spawns `git`.
+ *
+ * When the suite runs inside a git hook (lefthook's `pre-push`), git exports
+ * GIT_DIR — and sometimes GIT_WORK_TREE/GIT_INDEX_FILE — into every child
+ * process, and those beat `cwd` for every git invocation. A test that does
+ * `git init` / `git remote add` / `git commit` in a scratch tmpdir then
+ * silently operates on the REAL repository being pushed. Observed damage
+ * before this guard existed: a stray empty "init" commit landed on the
+ * checked-out branch, and `git init` re-initialized the shared `.git`
+ * directory as BARE (git treats a target directory named `.git` as a bare
+ * repo), breaking `git status` in the main checkout until `core.bare` was
+ * flipped back.
+ *
+ * Deleting the variables at module load — each test file is its own
+ * `node --test` process — makes `cwd` authoritative again for the whole
+ * file, including git calls made by the code under test.
+ */
+for (const key of ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_PREFIX", "GIT_COMMON_DIR", "GIT_OBJECT_DIRECTORY"]) {
+    delete process.env[key];
+}
+export {};

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

@@ -1 +1,14 @@
-export {};
+/**
+ * Regression guard for `spf init`'s non-interactive paths — `--yes`,
+ * `--template <name>`, and (implicitly, since the test runner's stdin/stdout
+ * are never a TTY) plain `spf init` with no flags. All three must keep
+ * writing the exact same content they always have, byte for byte, and must
+ * never touch stdin — a scripted `spf init` in CI must not hang.
+ *
+ * The interactive interview itself is covered directly against `Asker`
+ * in `interview.test.ts`; `initCommand`'s interactive branch always calls
+ * the real `createAsker()` (backed by `node:readline` on `process.stdin`),
+ * which has nothing to read in a test process — exercising it here would
+ * just hang, so it isn't.
+ */
+import "./hermetic_git.js";