@gr8ful/spf 0.1.0

package/dist/core/data_types.js

@@ -0,0 +1,382 @@
+/**
+ * Concrete data types for the SPF ADW system.
+ *
+ * RULE (four-param rule): any function that takes more than 4 parameters takes
+ * ONE of these objects instead. AgentCall and PhaseParams are the pattern.
+ *
+ * Every agent call declares a concrete output type — an envelope built with
+ * envelopeType() — that its final JSON response is parsed against. No untyped
+ * handoffs. Validation is Valibot's job here (zod's/Python's pydantic
+ * equivalent) — chosen because Flue's own structured-output wiring is built
+ * on Valibot, so an envelope type doubles as the tool schema handed to it
+ * with no second definition.
+ */
+import * as v from "valibot";
+// ── Phases ────────────────────────────────────────────────────────────────────
+/** Everything run.phase() needs. Passed as one object, never loose params. */
+const PhaseParamsShape = v.object({
+    name: v.string(), // short id, unique within the run: "plan", "build"
+    kind: v.picklist(["engineer", "agent", "code"]),
+    owner: v.string(), // engineer's name, "git", or an agent name from config
+    description: v.string(), // REQUIRED: what this phase does and why — see below
+    retries: v.optional(v.pipe(v.number(), v.integer()), 0), // agent phases: gate-failure retries via continue
+});
+/**
+ * A phase name identifies; a description explains. Both are required.
+ *
+ * The description is the only sentence the trace, the console, and the
+ * phase block in the UI ever show about intent — everything else is ids,
+ * statuses, and timings. `commit_plan: "Commit the plan"` tells a reader
+ * nothing they could not already see, so an echo is rejected the same way
+ * a blank one is. This is a construction-time error on purpose: it fires
+ * before the phase opens, not after a run is already in the trace.
+ */
+export const PhaseParamsSchema = v.pipe(PhaseParamsShape, v.rawTransform(({ dataset, addIssue, NEVER }) => {
+    const value = dataset.value;
+    const text = value.description.split(/\s+/).filter(Boolean).join(" ");
+    const name = value.name || "?";
+    if (!text) {
+        addIssue({
+            message: `phase ${JSON.stringify(name)}: description is required — one sentence on what this ` +
+                `phase does and why. It is what the trace and the UI show.`,
+        });
+        return NEVER;
+    }
+    if (text.replace(/\.+$/, "").toLowerCase() === name.replace(/_/g, " ").toLowerCase()) {
+        addIssue({
+            message: `phase ${JSON.stringify(name)}: description ${JSON.stringify(text)} only restates the phase name — ` +
+                `say what it does and why instead.`,
+        });
+        return NEVER;
+    }
+    return { ...value, description: text };
+}));
+export function makePhaseParams(input) {
+    return v.parse(PhaseParamsSchema, input);
+}
+// ── Envelopes (agent output types) ───────────────────────────────────────────
+const EnvelopeBaseEntries = {
+    status: v.picklist(["success", "fail"]),
+    summary: v.optional(v.string(), ""),
+    artifacts: v.optional(v.array(v.string()), () => []),
+    notes_for_next_agent: v.optional(v.string(), ""),
+};
+export const EnvelopeBaseSchema = v.object(EnvelopeBaseEntries);
+function envelopeType(name, entries) {
+    const schema = v.object({ ...EnvelopeBaseEntries, ...entries });
+    return { name, schema, fields: Object.keys(schema.entries) };
+}
+export const GenericOutput = envelopeType("GenericOutput", {});
+export const PlanOutput = envelopeType("PlanOutput", {
+    // Subject for committing the PLAN — the spec file the planner wrote, not the
+    // implementation it describes. Each agent's commit_message covers its own
+    // work product, so a chain that commits per step never reuses one agent's
+    // words for another agent's diff.
+    commit_message: v.optional(v.string(), ""),
+});
+export const BuildOutput = envelopeType("BuildOutput", {
+    changed_files: v.optional(v.array(v.string()), () => []),
+    commit_message: v.optional(v.string(), ""), // consumed by the git commit phase
+});
+export const ScoutFindingSchema = v.object({
+    file: v.string(),
+    note: v.optional(v.string(), ""),
+});
+export const ScoutOutput = envelopeType("ScoutOutput", {
+    findings: v.optional(v.array(ScoutFindingSchema), () => []),
+});
+/** One thing the request (or plan) asked for, and whether it is there. */
+export const ReviewFindingSchema = v.object({
+    requirement: v.string(), // the ask, in the requester's words
+    met: v.boolean(),
+    evidence: v.optional(v.string(), ""), // where it lives, or what is missing
+});
+/** Confirmation that what was built is what was asked for — not a test run. */
+export const ReviewOutput = envelopeType("ReviewOutput", {
+    approved: v.optional(v.boolean(), false),
+    findings: v.optional(v.array(ReviewFindingSchema), () => []),
+    blocking: v.optional(v.array(v.string()), () => []), // what must change before approval
+});
+/** Where the write-up of a completed change landed. */
+export const DocumentOutput = envelopeType("DocumentOutput", {
+    document_path: v.optional(v.string(), ""), // the doc in the repo, e.g. app_docs/<adw_id>_<slug>.md
+    documented_files: v.optional(v.array(v.string()), () => []),
+    commit_message: v.optional(v.string(), ""),
+});
+// ── Deterministic quality blocks ─────────────────────────────────────────────
+export const QualityAreaSchema = v.picklist(["frontend", "backend"]);
+export const QualityOperationSchema = v.picklist(["lint", "typecheck", "build"]);
+/** One deterministic quality command, as configured in spf.config.yaml's `quality.checks`. */
+export const QualityCheckSpecSchema = v.object({
+    name: v.string(),
+    area: v.optional(QualityAreaSchema, "backend"),
+    operation: QualityOperationSchema,
+    argv: v.pipe(v.array(v.string()), v.minLength(1, "argv must name at least the binary to run")),
+    timeout_seconds: v.optional(v.number(), 120),
+});
+/**
+ * `quality.checks` names the deterministic commands; `quality.suites` groups
+ * them into what a chain actually runs (`test`, `all`, ...). An unconfigured
+ * suite is a hard error at validate() time — see agents.validate() — not a
+ * silent placeholder that reports green. There is deliberately no packaged
+ * default suite: "no quality commands configured yet" must fail loudly on
+ * the first quality-gated chain, not quietly pass one.
+ */
+export const QualityConfigSchema = v.object({
+    checks: v.optional(v.array(QualityCheckSpecSchema), () => []),
+    suites: v.optional(v.record(v.string(), v.array(v.string())), () => ({})),
+});
+export function makeChangeCapture(input) {
+    return {
+        base: input.base ?? "main",
+        max_diff_lines: input.max_diff_lines ?? 2000,
+        include_untracked: input.include_untracked ?? true,
+    };
+}
+/**
+ * The commit a change is measured from, and why that one.
+ *
+ * `reason` is the line the trace shows. A diff is only as trustworthy as the
+ * thing it was taken against, so the ADW records that choice instead of
+ * leaving the reader to infer it.
+ */
+export class BaseRef {
+    ref;
+    commit;
+    reason;
+    constructor(ref, commit, reason = "") {
+        this.ref = ref;
+        this.commit = commit;
+        this.reason = reason;
+    }
+    /** Display form — a named ref as itself, a pinned raw sha shortened. */
+    get label() {
+        if (this.ref.length === 40 && /^[0-9a-f]+$/.test(this.ref)) {
+            return this.ref.slice(0, 7);
+        }
+        return this.ref;
+    }
+}
+/** What changed since the base commit — pure git facts, no judgement. */
+export class ChangeSet {
+    base;
+    files;
+    untracked;
+    insertions;
+    deletions;
+    stat;
+    diff_path;
+    truncated;
+    constructor(base, files = [], untracked = [], insertions = 0, deletions = 0, stat = "", diff_path = "", // the full diff, written into context_handoff/
+    truncated = false) {
+        this.base = base;
+        this.files = files;
+        this.untracked = untracked;
+        this.insertions = insertions;
+        this.deletions = deletions;
+        this.stat = stat;
+        this.diff_path = diff_path;
+        this.truncated = truncated;
+    }
+    get empty() {
+        return this.files.length === 0 && this.untracked.length === 0;
+    }
+}
+/**
+ * A ChangeSet shaped as an envelope so an agent can be handed it directly.
+ *
+ * Same adapter idea as VerifyOutput: code computes the diff, the documenter
+ * consumes it through the one door every agent handoff uses.
+ */
+export const ChangesOutput = envelopeType("ChangesOutput", {
+    base: v.optional(v.string(), ""), // "<ref> @ <commit> — <reason>"
+    changed_files: v.optional(v.array(v.string()), () => []),
+    insertions: v.optional(v.number(), 0),
+    deletions: v.optional(v.number(), 0),
+    stat: v.optional(v.string(), ""),
+    diff_path: v.optional(v.string(), ""), // read this for the full diff
+});
+/**
+ * A deterministic result, shaped as an envelope so an agent can consume it.
+ *
+ * Agents hand each other typed envelopes; code blocks return QualityResult.
+ * This is the adapter, so a failing lint or test run flows back into the
+ * builder through exactly the same door a tester agent's report used to —
+ * the ADW script is the only thing that knows the difference.
+ */
+export const VerifyOutput = envelopeType("VerifyOutput", {
+    passed: v.optional(v.boolean(), false),
+    failures: v.optional(v.array(v.string()), () => []),
+});
+/**
+ * What every gate returns: the checks it ran. Violations are derived.
+ *
+ * Authoring stays a one-liner per item — `report.check(...)` appends and
+ * returns self, so a gate is a loop and a return.
+ */
+export class GateReport {
+    checks = [];
+    check(item, ok, note = "") {
+        this.checks.push({ item, ok, note });
+        return this;
+    }
+    get violations() {
+        return this.checks.filter((c) => !c.ok).map((c) => `${c.item}: ${c.note || "failed"}`);
+    }
+    get passed() {
+        return this.violations.length === 0;
+    }
+}
+export function makeAgentCall(input) {
+    return { previous: null, gates: [], ...input };
+}
+// ── Config ───────────────────────────────────────────────────────────────────
+export const PromptEngineeringSchema = v.object({
+    system: v.string(), // path to system.md
+    user: v.string(), // path to user.md
+});
+export const ThinkingLevelSchema = v.picklist(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+export const AgentConfigSchema = v.object({
+    name: v.string(),
+    coding_agent: v.optional(v.picklist(["flue", "claude_code"]), "flue"),
+    model: v.optional(v.string(), "google/gemini-3.6-flash"),
+    thinking: v.optional(ThinkingLevelSchema, "medium"),
+    color: v.optional(v.string(), ""), // hex swatch for this agent's lane in the UI
+    purpose: v.optional(v.string(), ""),
+    prompt_engineering: PromptEngineeringSchema,
+    harness_engineering: v.optional(v.array(v.string()), () => []),
+    tools: v.optional(v.nullable(v.array(v.string()))), // allowlist; undefined/null = all tools usable
+    // What this agent may MODIFY in the repo, enforced in code after every call
+    // (see core/permissions.ts). `tools` cannot express this: `bash` runs
+    // anything and `write` reaches any path, so an agent's capability list is a
+    // statement of intent that nothing checks.
+    //   undefined -> unrestricted, except the roster-wide `protected_files` paths
+    //   []        -> read-only: may modify nothing tracked
+    //   [...]     -> only these. A trailing "/" means a directory prefix; a "*"
+    //                makes it a glob; anything else is an exact path.
+    writes: v.optional(v.nullable(v.array(v.string()))),
+});
+export const ConfigDefaultsSchema = v.object({
+    coding_agent: v.optional(v.picklist(["flue", "claude_code"]), "flue"),
+    model: v.optional(v.string(), "google/gemini-3.6-flash"),
+    thinking: v.optional(ThinkingLevelSchema, "medium"),
+    color: v.optional(v.string(), ""),
+    harness_engineering: v.optional(v.array(v.string()), () => []),
+    tools: v.optional(v.nullable(v.array(v.string()))), // roster-wide allowlist; unset = all tools usable
+    // Off-limits to every agent that has not named them in its own `writes`.
+    // The factory's own code is the default: an agent must not be able to edit
+    // the machinery that decides whether its work passed.
+    // .spf/ is the whole per-repo footprint now — no adws/ tree to protect.
+    protected_files: v.optional(v.array(v.string()), () => [".spf/", "spf.config.yaml"]),
+    data_dir: v.optional(v.string(), ".spf/data"),
+});
+export const ObservabilityConfigSchema = v.object({
+    db: v.optional(v.string(), ".spf/data/spf.db"),
+    poll_ms: v.optional(v.number(), 500),
+});
+/**
+ * `spf watch`'s configuration. `provider` is a small enum today (just
+ * `"github"`) by design — adding Jira/Linear later is a new provider
+ * module (`core/issues/*_provider.ts`) implementing `IssueProvider` plus
+ * one more enum entry here, not a rewrite of the poll loop.
+ *
+ * `repo` has no sensible default and is validated as required at `spf
+ * watch` startup, not here — an empty string parses fine (this schema has
+ * no opinion on whether watch is even configured), matching the same
+ * "fails loudly before anything spawns, not eagerly at parse time" pattern
+ * `quality:` already uses.
+ */
+export const WatchProviderSchema = v.picklist(["github"]);
+export const WatchConfigSchema = v.object({
+    provider: v.optional(WatchProviderSchema, "github"),
+    repo: v.optional(v.string(), ""), // "owner/name"
+    label_prefix: v.optional(v.string(), "spf"),
+    chain: v.optional(v.string(), "plan-build-test"),
+    base_branch: v.optional(v.string(), "main"),
+    poll_ms: v.optional(v.number(), 60_000),
+    concurrency: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 2),
+});
+export const SFConfigSchema = v.object({
+    defaults: v.optional(ConfigDefaultsSchema, () => v.parse(ConfigDefaultsSchema, {})),
+    observability: v.optional(ObservabilityConfigSchema, () => v.parse(ObservabilityConfigSchema, {})),
+    agents: v.optional(v.array(AgentConfigSchema), () => []),
+    quality: v.optional(QualityConfigSchema, () => v.parse(QualityConfigSchema, {})),
+    watch: v.optional(WatchConfigSchema, () => v.parse(WatchConfigSchema, {})),
+});
+export function makeEventRecord(input) {
+    return {
+        phase_id: "",
+        name: "",
+        payload: {},
+        parent_id: "",
+        tokens: null,
+        started_at: null,
+        ended_at: null,
+        ...input,
+    };
+}
+/**
+ * Tokens and the dollars they cost, per component, summed over a call.
+ *
+ * Mirrors pi's `usage` shape one-for-one so the numbers reconcile with what
+ * pi itself reports: `input` EXCLUDES cache reads, which bill at their own
+ * (cheaper) rate — add them to learn the size of the prompt that was sent.
+ */
+export class UsageBreakdown {
+    input_tokens = 0;
+    output_tokens = 0;
+    cache_read_tokens = 0;
+    cache_write_tokens = 0;
+    // Thinking tokens. NOT a fifth component: measured across every session on
+    // disk, reasoning is always <= output and the four components above always
+    // sum to totalTokens, so reasoning is the thinking SHARE of output, billed
+    // at the output rate. Report it nested under output, never added to it.
+    reasoning_tokens = 0;
+    total_tokens = 0;
+    input_cost = 0.0;
+    output_cost = 0.0;
+    cache_read_cost = 0.0;
+    cache_write_cost = 0.0;
+    total_cost = 0.0;
+    /**
+     * Fold in one pi `message_end` usage object.
+     *
+     * `totalTokens` is passed in rather than re-derived: the caller already
+     * computes it pi's way (totalTokens, else the sum of the parts).
+     */
+    add_turn(usage, totalTokens) {
+        const cost = usage.cost || {};
+        this.input_tokens += usage.input || 0;
+        this.output_tokens += usage.output || 0;
+        this.cache_read_tokens += usage.cacheRead || 0;
+        this.cache_write_tokens += usage.cacheWrite || 0;
+        this.reasoning_tokens += usage.reasoning || 0;
+        this.total_tokens += totalTokens;
+        this.input_cost += cost.input || 0.0;
+        this.output_cost += cost.output || 0.0;
+        this.cache_read_cost += cost.cacheRead || 0.0;
+        this.cache_write_cost += cost.cacheWrite || 0.0;
+        this.total_cost += cost.total || 0.0;
+    }
+    /** Add another call's usage — a phase that retries spends more than once. */
+    merge(other) {
+        for (const key of Object.keys(this)) {
+            this[key] = this[key] + other[key];
+        }
+    }
+    toJSON() {
+        return { ...this };
+    }
+}
+export function makeAgentResult(input) {
+    return {
+        text: "",
+        report: null,
+        tokens: 0,
+        cost: 0,
+        usage: new UsageBreakdown(),
+        context_tokens: 0,
+        context_window: 0,
+        ...input,
+    };
+}

package/dist/core/gates.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Validation gates: verify the envelope's CLAIMS, never guesses.
+ *
+ * A gate is `gate(envelope, run) -> GateReport` — one check per item it looked at.
+ * Violations are derived from the failed checks and sent back to the SAME agent
+ * session as a correction. Every check is recorded either way, so a green gate
+ * says WHAT it verified instead of only that it passed.
+ *
+ * Gates check what is mechanically checkable; plan quality is a reviewer's job.
+ *
+ * An envelope's artifact/file paths are the AGENT's claims, and the agent runs
+ * with `run.repo_root` as its cwd — so a relative claim is resolved against
+ * that root, never against this process's own cwd. A claim that resolves
+ * outside the repo entirely is reported as a violation rather than silently
+ * stat'd (or not found) somewhere unexpected.
+ */
+import { GateReport, type EnvelopeBase, type GateFn, type RunContext } from "./data_types.ts";
+export declare function artifactsExist(envelope: EnvelopeBase, run: RunContext): GateReport;
+export declare function filesNonEmpty(envelope: EnvelopeBase, run: RunContext): GateReport;
+export declare function jsonParses(envelope: EnvelopeBase, run: RunContext): GateReport;
+/** Every file claimed changed must exist on disk. */
+export declare function diffMatchesClaims(envelope: EnvelopeBase, run: RunContext): GateReport;
+/**
+ * A review's verdict must agree with the findings it just wrote down.
+ *
+ * Nothing here judges the code — that is the reviewer's job. This checks the
+ * envelope against itself: an approval that ships blocking items, or a
+ * rejection that names no problem, is a claim the harness can refute without
+ * reading a line of the diff.
+ */
+export declare function verdictConsistent(envelope: EnvelopeBase, _run: RunContext): GateReport;
+/** Gate factory: the given shell command must exit 0, run from run.repo_root. */
+export declare function testsPass(command: string): GateFn;

package/dist/core/gates.js

@@ -0,0 +1,144 @@
+/**
+ * Validation gates: verify the envelope's CLAIMS, never guesses.
+ *
+ * A gate is `gate(envelope, run) -> GateReport` — one check per item it looked at.
+ * Violations are derived from the failed checks and sent back to the SAME agent
+ * session as a correction. Every check is recorded either way, so a green gate
+ * says WHAT it verified instead of only that it passed.
+ *
+ * Gates check what is mechanically checkable; plan quality is a reviewer's job.
+ *
+ * An envelope's artifact/file paths are the AGENT's claims, and the agent runs
+ * with `run.repo_root` as its cwd — so a relative claim is resolved against
+ * that root, never against this process's own cwd. A claim that resolves
+ * outside the repo entirely is reported as a violation rather than silently
+ * stat'd (or not found) somewhere unexpected.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, statSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { GateReport } from "./data_types.js";
+import { operatorEnv } from "./utils.js";
+const TAIL_CHARS = 1000; // command output kept as evidence on a failure
+/**
+ * Anchor an envelope-declared path to `run.repo_root`. Absolute paths pass
+ * through unchanged (an agent that reports an absolute path meant exactly
+ * that path). Returns `null` when the resolved path escapes the repo — a
+ * gate should report that as a violation, not silently check outside it.
+ */
+function resolveClaim(p, run) {
+    const resolved = path.isAbsolute(p) ? p : path.resolve(run.repo_root, p);
+    const rel = path.relative(run.repo_root, resolved);
+    if (rel === "..")
+        return null;
+    if (rel.startsWith(`..${path.sep}`))
+        return null;
+    return resolved;
+}
+function size(p) {
+    const n = statSync(p).size;
+    return n < 1024 ? `${n}B` : `${(n / 1024).toFixed(1)}KB`;
+}
+export function artifactsExist(envelope, run) {
+    const report = new GateReport();
+    for (const a of envelope.artifacts) {
+        const resolved = resolveClaim(a, run);
+        if (resolved === null) {
+            report.check(a, false, `declared artifact resolves outside the repo (${run.repo_root})`);
+            continue;
+        }
+        const exists = existsSync(resolved);
+        report.check(a, exists, exists ? `exists, ${size(resolved)}` : "declared artifact does not exist");
+    }
+    return report;
+}
+export function filesNonEmpty(envelope, run) {
+    const report = new GateReport();
+    for (const a of envelope.artifacts) {
+        const resolved = resolveClaim(a, run);
+        if (resolved === null)
+            continue; // artifactsExist's job to report the escape
+        if (!existsSync(resolved) || !statSync(resolved).isFile())
+            continue; // existence is artifactsExist's job
+        const empty = statSync(resolved).size === 0;
+        report.check(a, !empty, empty ? "declared artifact is empty" : size(resolved));
+    }
+    return report;
+}
+export function jsonParses(envelope, run) {
+    const report = new GateReport();
+    for (const a of envelope.artifacts) {
+        if (!a.endsWith(".json"))
+            continue;
+        const resolved = resolveClaim(a, run);
+        if (resolved === null || !existsSync(resolved))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(resolved, "utf-8"));
+            const kind = Array.isArray(parsed) ? "list" : typeof parsed === "object" && parsed !== null ? "dict" : typeof parsed;
+            report.check(a, true, `parses, ${kind}`);
+        }
+        catch (error) {
+            report.check(a, false, `declared JSON artifact does not parse: ${error.message}`);
+        }
+    }
+    return report;
+}
+/** Every file claimed changed must exist on disk. */
+export function diffMatchesClaims(envelope, run) {
+    const report = new GateReport();
+    const changedFiles = envelope.changed_files ?? [];
+    for (const f of changedFiles) {
+        const resolved = resolveClaim(f, run);
+        if (resolved === null) {
+            report.check(f, false, `claimed changed file resolves outside the repo (${run.repo_root})`);
+            continue;
+        }
+        const exists = existsSync(resolved);
+        report.check(f, exists, exists ? `exists, ${size(resolved)}` : "claimed changed file does not exist");
+    }
+    return report;
+}
+/**
+ * A review's verdict must agree with the findings it just wrote down.
+ *
+ * Nothing here judges the code — that is the reviewer's job. This checks the
+ * envelope against itself: an approval that ships blocking items, or a
+ * rejection that names no problem, is a claim the harness can refute without
+ * reading a line of the diff.
+ */
+export function verdictConsistent(envelope, _run) {
+    const report = new GateReport();
+    const approved = Boolean(envelope.approved ?? false);
+    const blocking = envelope.blocking ?? [];
+    const findings = envelope.findings ?? [];
+    const unmet = findings.filter((f) => !f.met).map((f) => f.requirement);
+    report.check("approved vs blocking", !(approved && blocking.length > 0), blocking.length === 0
+        ? "no blocking items"
+        : approved
+            ? `${blocking.length} blocking item(s) while approved=true`
+            : `${blocking.length} blocking item(s), not approved`);
+    report.check("approved vs findings", !(approved && unmet.length > 0), unmet.length === 0
+        ? "every requirement met"
+        : approved
+            ? `${unmet.length} unmet requirement(s) while approved=true`
+            : `${unmet.length} unmet requirement(s), not approved`);
+    report.check("rejection names a problem", approved || blocking.length > 0 || unmet.length > 0, approved || blocking.length > 0 || unmet.length > 0
+        ? "verdict is supported"
+        : "approved=false but no blocking item or unmet requirement was given");
+    return report;
+}
+/** Gate factory: the given shell command must exit 0, run from run.repo_root. */
+export function testsPass(command) {
+    const gate = (_envelope, run) => {
+        const result = spawnSync(command, { shell: true, encoding: "utf-8", cwd: run.repo_root, env: operatorEnv() });
+        const ok = result.status === 0;
+        let note = `exit ${result.status}`;
+        if (!ok) {
+            note += "\n" + ((result.stdout || "") + (result.stderr || "")).slice(-TAIL_CHARS);
+        }
+        return new GateReport().check(command, ok, note);
+    };
+    Object.defineProperty(gate, "name", { value: `tests_pass(${command})` });
+    return gate;
+}

package/dist/core/git_helper.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Low-level git operations for code phases. All low-level logic lives in core/.
+ *
+ * Two discovery functions (`isRepoAt`, `findRepoRoot`) take an explicit `cwd`
+ * because they are how a repo root gets established in the first place —
+ * nothing has one yet to bind to. Everything else is repo-root-bound: call
+ * `makeGit(repoRoot)` once you have that root, and every operation it returns
+ * runs there, never against `process.cwd()`. This is deliberate — the ADW
+ * process's cwd and the repo it is operating on are two different things,
+ * and conflating them is exactly the anchor bug this factory exists to close.
+ */
+/** True when `cwd` is inside a git working tree. Never throws — this is a question. */
+export declare function isRepoAt(cwd: string): boolean;
+/**
+ * Absolute root of the git repo containing `cwd`, or `cwd` itself if it is
+ * not inside one — ADWs run fine in a non-git dir; only a commit phase
+ * requires a repo. Always absolute, so it is safe to hand to a subprocess
+ * regardless of where the ADW was launched from.
+ */
+export declare function findRepoRoot(cwd: string): string;
+export interface GitHandle {
+    currentBranch(): string;
+    createBranch(name: string): string;
+    isRepo(): boolean;
+    /** Stage the working tree and commit it. Returns the new short sha. */
+    commitAll(message: string): string;
+    changedFiles(): string[];
+    /** True when `ref` resolves to a commit. Never throws — this is a question. */
+    refExists(ref: string): boolean;
+    rev(ref?: string): string;
+    shortSha(ref?: string): string;
+    /**
+     * The commit where `ref` and `other` diverged — the honest base of a branch.
+     *
+     * On the base branch itself this returns HEAD, which makes the diff exactly
+     * "what is not committed yet". Off it, the diff is the whole branch plus the
+     * working tree. One command covers both cases, so no caller has to branch on it.
+     */
+    mergeBase(ref: string, other?: string): string;
+    isDirty(): boolean;
+    untrackedFiles(): string[];
+    /** Tracked files that differ between `base` and the working tree. */
+    diffFiles(base: string): string[];
+    diffStat(base: string): string;
+    /** [insertions, deletions] across the diff. Binary files count as neither. */
+    diffCounts(base: string): [number, number];
+    diffText(base: string): string;
+    /** `git fetch <remote> <ref>` — needed before branching off a remote base that may have moved. */
+    fetch(remote: string, ref: string): void;
+    /** `git worktree add <path> -b <branch> <startPoint>` — used by `spf watch` to isolate one issue's work outside the repo. */
+    worktreeAdd(worktreePath: string, branch: string, startPoint: string): void;
+    /** `git worktree remove <path> --force`. Never throws if the path is already gone. */
+    worktreeRemove(worktreePath: string): void;
+    /** `git branch -D <name>`. Never throws if the branch is already gone. */
+    deleteLocalBranch(name: string): void;
+    push(remote: string, branch: string): void;
+}
+/** Every operation this returns is bound to `repoRoot` — never `process.cwd()`. */
+export declare function makeGit(repoRoot: string): GitHandle;