@gr8ful/spf 0.14.0 → 0.16.0

package/dist/core/data_types.js

@@ -475,7 +475,7 @@ export const SandboxConfigSchema = v.object({
 });
 export const AgentConfigSchema = v.object({
     name: v.string(),
-    coding_agent: v.optional(v.picklist(["flue", "claude_code"]), "flue"),
+    coding_agent: v.optional(v.picklist(["flue", "claude_code", "opencode"]), "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
@@ -510,7 +510,7 @@ export const AgentConfigSchema = v.object({
     sandbox: v.optional(v.nullable(SandboxBackendSchema)),
 });
 export const ConfigDefaultsSchema = v.object({
-    coding_agent: v.optional(v.picklist(["flue", "claude_code"]), "flue"),
+    coding_agent: v.optional(v.picklist(["flue", "claude_code", "opencode"]), "flue"),
     model: v.optional(v.string(), "google/gemini-3.6-flash"),
     thinking: v.optional(ThinkingLevelSchema, "medium"),
     color: v.optional(v.string(), ""),
@@ -587,8 +587,97 @@ export const OTelConfigSchema = v.object({
     headers: v.optional(v.record(v.string(), v.string()), undefined),
     service_name: v.optional(v.string(), "spf"),
 });
+/**
+ * MIGRATION NOTE (BT-issue #66, 3 PRs): `observability.db` used to be ONLY a
+ * bare string (a local sqlite path, defaulting to ".spf/data/spf.db"). This
+ * is now a discriminated shape that additionally accepts an explicit
+ * `{ kind: "sqlite", path? }` object (equivalent to the string form, just
+ * spelled out) and a `{ kind: "d1", database_id, ... }` object that names a
+ * remote Cloudflare D1 database instead of a local file. The bare-string
+ * form is unchanged and remains the default for every existing config —
+ * nothing in the wild needs to change. `resolveObservabilityDb` below
+ * normalizes all three accepted forms to one shape.
+ *
+ * PR 1 (this schema + normalizer + `paths.resolveDataPaths` plumbing) left
+ * `resolveDataPaths` refusing a `kind: "d1"` config outright — no adapter
+ * existed yet. PR 2 (`core/trace_db.ts`'s `TraceDb` interface, `LocalTraceDb`,
+ * `D1TraceDb`, and `createTraceDb()`, wired through `Tracer`/`SfDb`) removes
+ * that refusal: `resolveDataPaths` now returns a usable descriptor for
+ * either kind, and both backends are real. PR 3 wires `spf doctor`/`spf
+ * init`'s interview flow to the new option.
+ */
+export const SqliteDbConfigSchema = v.object({
+    kind: v.literal("sqlite"),
+    path: v.optional(v.string(), ".spf/data/spf.db"),
+});
+/**
+ * `account_id_env`/`api_token_env` default to the SAME env var names
+ * `core/cloudflare_provider.ts` already reads for the Cloudflare Workers AI
+ * provider (`CLOUDFLARE_ACCOUNT_ID`/`CLOUDFLARE_API_TOKEN`, see
+ * `core/providers.ts`'s `PROVIDER_ENV_KEYS.cloudflare`) — one Cloudflare
+ * account's credentials, read from the same two env vars, cover both
+ * Workers AI and a D1-backed trace db unless a config explicitly points
+ * elsewhere (e.g. a second Cloudflare account) by naming different env vars.
+ */
+export const D1DbConfigSchema = v.object({
+    kind: v.literal("d1"),
+    database_id: v.string(),
+    account_id_env: v.optional(v.string(), "CLOUDFLARE_ACCOUNT_ID"),
+    api_token_env: v.optional(v.string(), "CLOUDFLARE_API_TOKEN"),
+});
+/**
+ * A plain `v.union([v.string(), v.variant("kind", [...])])` was tried first
+ * and rejected: valibot's plain union reports every failed branch with the
+ * same generic "Expected (string | Object) but received Object", swallowing
+ * `v.variant`'s own precise "kind must be sqlite or d1" / "database_id is
+ * required" messages. This `rawTransform` dispatches on `typeof value`
+ * itself — string passes through unchanged (the back-compat form), anything
+ * else is handed to `v.variant("kind", ...)` and ITS issues (which already
+ * name the offending field) are re-surfaced verbatim, prefixed with
+ * `observability.db:` so a nested failure is still easy to place in a large
+ * config file. See `src/test/data_types.test.ts` for the exact messages
+ * this produces for each rejected shape.
+ */
+const ObservabilityDbVariantSchema = v.variant("kind", [SqliteDbConfigSchema, D1DbConfigSchema]);
+export const ObservabilityDbSchema = v.pipe(v.unknown(), v.rawTransform(({ dataset, addIssue, NEVER }) => {
+    const value = dataset.value;
+    if (typeof value === "string")
+        return value;
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        const result = v.safeParse(ObservabilityDbVariantSchema, value);
+        if (result.success)
+            return result.output;
+        for (const issue of result.issues)
+            addIssue({ message: `observability.db: ${issue.message}` });
+        return NEVER;
+    }
+    addIssue({
+        message: `observability.db must be a string path, or an object with kind: "sqlite" or kind: "d1" (got ${JSON.stringify(value)})`,
+    });
+    return NEVER;
+}));
+/**
+ * Normalizes `observability.db` — bare string, `{kind:"sqlite",...}`, or
+ * `{kind:"d1",...}` — to one shape. Pure and side-effect-free: does NOT
+ * resolve `path` to an absolute path (that's `paths.resolveDataPaths`'s job,
+ * which needs `repo_root` to do it) and does NOT read the D1 env vars it
+ * names (that's PR 2's adapter's job, at the point it actually needs to
+ * authenticate).
+ */
+export function resolveObservabilityDb(db) {
+    if (typeof db === "string")
+        return { kind: "sqlite", path: db };
+    if (db.kind === "sqlite")
+        return { kind: "sqlite", path: db.path ?? ".spf/data/spf.db" };
+    return {
+        kind: "d1",
+        database_id: db.database_id,
+        account_id_env: db.account_id_env ?? "CLOUDFLARE_ACCOUNT_ID",
+        api_token_env: db.api_token_env ?? "CLOUDFLARE_API_TOKEN",
+    };
+}
 export const ObservabilityConfigSchema = v.object({
-    db: v.optional(v.string(), ".spf/data/spf.db"),
+    db: v.optional(ObservabilityDbSchema, ".spf/data/spf.db"),
     poll_ms: v.optional(v.number(), 500),
     // Absent by default. `agents.ts`'s mergeRawConfig spreads `observability`
     // field-by-field, so this nested object merges as a WHOLE-OBJECT replace on
@@ -596,6 +685,14 @@ export const ObservabilityConfigSchema = v.object({
     // which is the semantics you want for an endpoint + its headers (a
     // half-merged pair of the two would send tokens to the wrong collector).
     // Pinned by a merge-survival test in src/test/data_types.test.ts.
+    //
+    // `db` merges the same whole-value way: `mergeRawConfig`'s `observability`
+    // spread is key-by-key over `observability`'s OWN keys (db/poll_ms/otel),
+    // never deeper — an override's `db:` (string or object, either kind)
+    // replaces the base's `db:` in full, so a `{kind:"d1",...}` override can
+    // never end up with a stray `path` key leaked in from a `{kind:"sqlite",
+    // path:...}` base (or vice versa). See the merge-survival test for `db` in
+    // src/test/data_types.test.ts.
     otel: v.optional(OTelConfigSchema),
 });
 /**
@@ -661,19 +758,94 @@ export const JiraIssueTypeMapSchema = v.object({
      */
     spec: v.optional(v.string(), "Story"),
 });
+/**
+ * Optional, per-project `WatchState` -> Jira workflow-status-name map.
+ * Unlike `JiraIssueTypeMapSchema`, this has no sane universal default:
+ * "To Do" vs "Open" vs "Backlog" (and everything in between) is entirely
+ * per-project workflow configuration in Jira, so every field defaults to
+ * unset. A `WatchState` with no entry here keeps today's behavior exactly —
+ * `jira_provider.ts`'s `transition()`/`claim()` update the label only and
+ * never attempt a status change for it.
+ *
+ * Deliberately covers only the states a human's Jira board status would
+ * plausibly want to reflect (the build lane, `spec-ready` through
+ * `blocked`) — the refine-lane states (`refining`, `split-proposed`, ...)
+ * are internal bookkeeping for `core/refine.ts`, not board-visible work.
+ *
+ * `jira_provider.ts`'s `syncStatus()` is the reader; `validateStatusMap()`
+ * is what `spf watch init` and `spf watch`'s own startup check should call
+ * to confirm each configured name is a real status on the project before an
+ * unattended run relies on it — same shape as `issue_types`/
+ * `validateIssueTypes()`.
+ */
+export const JiraStatusMapSchema = v.object({
+    "spec-ready": v.optional(v.string()),
+    ready: v.optional(v.string()),
+    working: v.optional(v.string()),
+    review: v.optional(v.string()),
+    done: v.optional(v.string()),
+    blocked: v.optional(v.string()),
+});
 /**
  * Only consulted when `issue_provider: jira`. Auth is `JIRA_EMAIL` +
  * `JIRA_API_TOKEN` env vars, checked at startup like `GITHUB_TOKEN`. Whole-
  * object replace on config-file-layer merge, like `refine`/
  * `observability.otel` (see `agents.ts`'s `mergeRawConfig`) — an override
- * file that touches `watch.jira` at all must repeat `issue_types` too if it
- * wants to keep a customized mapping, same caveat that already applies to
- * `base_url`/`project_key` today.
+ * file that touches `watch.jira` at all must repeat `issue_types`/
+ * `status_map` too if it wants to keep a customized mapping, same caveat
+ * that already applies to `base_url`/`project_key` today.
  */
 export const WatchJiraConfigSchema = v.object({
     base_url: v.optional(v.string(), ""), // e.g. "https://your-domain.atlassian.net"
     project_key: v.optional(v.string(), ""), // e.g. "PROJ"
     issue_types: v.optional(JiraIssueTypeMapSchema, () => v.parse(JiraIssueTypeMapSchema, {})),
+    status_map: v.optional(JiraStatusMapSchema, () => v.parse(JiraStatusMapSchema, {})),
+});
+/**
+ * Optional, per-repo `WatchState` -> GitHub Projects v2 "Status" option-name
+ * map — the GitHub-side twin of `JiraIssueTypeMap`'s sibling on the Jira
+ * provider (see `jira_provider.ts`'s `status_map`). No sane universal
+ * default: a board's Status column options ("Todo"/"In Progress"/"Done", or
+ * anything else) are per-project configuration, so every field defaults to
+ * unset. A `WatchState` with no entry keeps today's behavior exactly —
+ * `github_provider.ts`'s `transition()`/`claim()` update the label only and
+ * never touch Projects v2 for it.
+ *
+ * Same six build-lane states as Jira's map — the refine-lane's own
+ * bookkeeping states (`refining`, `split-proposed`, ...) aren't board-visible
+ * work, same reasoning as `jira_provider.ts`'s `JiraStatusMapSchema`.
+ *
+ * `github_provider.ts`'s `syncStatus()` is the reader; `validateStatusMap()`
+ * is what `spf watch init` and `spf watch`'s own startup check call to
+ * confirm each configured name is a real Status option on the configured
+ * project before an unattended run relies on it.
+ */
+export const GithubStatusMapSchema = v.object({
+    "spec-ready": v.optional(v.string()),
+    ready: v.optional(v.string()),
+    working: v.optional(v.string()),
+    review: v.optional(v.string()),
+    done: v.optional(v.string()),
+    blocked: v.optional(v.string()),
+});
+/**
+ * Only consulted when `issue_provider: github` (or `code_host: github`) AND
+ * `status_map` actually has an entry configured — `project_number: 0` (the
+ * default) disables status sync outright regardless of `status_map`, since
+ * there's no sane "guess the board" default: a repo can have zero, one, or
+ * many Projects v2 boards, and none of them is canonical. Scoped to the
+ * repo's OWNER (`watch.repo`'s "owner/name", the owner half) — GitHub
+ * Projects v2 numbers are per-owner, not per-repo, so `project_number: 3`
+ * means owner's project #3, which may or may not have this repo's issues on
+ * it yet (`github_provider.ts`'s `syncStatus()` adds the issue to the
+ * project itself the first time it needs to). Whole-object replace on
+ * config-file-layer merge, like `jira`/`refine` above — an override file
+ * that touches `watch.github` at all must repeat `status_map` too if it
+ * wants to keep a customized mapping.
+ */
+export const WatchGithubConfigSchema = v.object({
+    project_number: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0)), 0),
+    status_map: v.optional(GithubStatusMapSchema, () => v.parse(GithubStatusMapSchema, {})),
 });
 /**
  * The second `spf watch` lane: decompose a `<prefix>:spec-ready` product
@@ -798,6 +970,7 @@ export const WatchConfigSchema = v.object({
      */
     chain_options: v.optional(v.record(v.string(), v.string()), () => ({})),
     jira: v.optional(WatchJiraConfigSchema, () => v.parse(WatchJiraConfigSchema, {})),
+    github: v.optional(WatchGithubConfigSchema, () => v.parse(WatchGithubConfigSchema, {})),
     refine: v.optional(WatchRefineConfigSchema, () => v.parse(WatchRefineConfigSchema, {})),
     fanout: v.optional(WatchFanoutConfigSchema, () => v.parse(WatchFanoutConfigSchema, {})),
 });
@@ -886,7 +1059,7 @@ export const ReviewConfigSchema = v.object({
  */
 export const TierSchema = v.object({
     name: v.pipe(v.string(), v.minLength(1)),
-    coding_agent: v.optional(v.picklist(["flue", "claude_code"]), "flue"),
+    coding_agent: v.optional(v.picklist(["flue", "claude_code", "opencode"]), "flue"),
     model: v.pipe(v.string(), v.minLength(1)),
 });
 /**

package/dist/core/fanout.d.ts

@@ -204,7 +204,7 @@ export interface FanoutDeps {
     /** Run one attempt's chain in `cwd`, returning its exit code. */
     runAttempt: (dispatch: AttemptDispatch) => Promise<number>;
     /** Read this adw_id's gate/usage rows from the SHARED db. Must not throw — return `ZERO_METRICS` on any hiccup. */
-    readMetrics: (adwId: string) => AttemptMetrics;
+    readMetrics: (adwId: string) => Promise<AttemptMetrics>;
     log: (message: string) => void;
     /**
      * Opt-in first-past-the-post. Default (unset/false): every attempt that

package/dist/core/fanout.js

@@ -239,7 +239,7 @@ export async function runBestOf(deps) {
             decided = true;
         let metrics = ZERO_METRICS;
         try {
-            metrics = deps.readMetrics(adwId);
+            metrics = await deps.readMetrics(adwId);
         }
         catch (caught) {
             // Metrics are for RANKING, never for correctness — an attempt whose

package/dist/core/gates.js

@@ -96,7 +96,20 @@ export function diffMatchesClaims(envelope, run) {
             continue;
         }
         const exists = existsSync(resolved);
-        report.check(f, exists, exists ? `exists, ${size(resolved)}` : "claimed changed file does not exist");
+        // A bulk/mechanical change (a repo-wide formatter, a codemod) tempts an
+        // agent to compress many identical edits into one descriptive sentence
+        // ("139 files reformatted (app/, components/, ...)") instead of listing
+        // each path — that string obviously never resolves, but the plain
+        // "does not exist" message gives no hint why, so a retry repeats the
+        // same mistake. Whitespace inside an otherwise-nonexistent claim is the
+        // cheap, cheap-to-check signal: a real repo-relative path is never a
+        // prose fragment. Never suppresses the failure itself, only clarifies it.
+        const looksLikeProse = !exists && /\s/.test(f);
+        report.check(f, exists, exists
+            ? `exists, ${size(resolved)}`
+            : looksLikeProse
+                ? "claimed changed file does not exist — this looks like a summary sentence, not a path; list every changed file individually, even for a bulk/mechanical change"
+                : "claimed changed file does not exist");
     }
     return report;
 }

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

@@ -8,7 +8,8 @@
  * a couple dozen REST calls, none of them exotic. `spf`'s own package stays
  * dependency-free either way.
  *
- * Auth is a classic PAT via `GITHUB_TOKEN` (`repo` scope), read once at
+ * Auth is a classic PAT via `GITHUB_TOKEN` (`repo` scope — plus `project` if
+ * `watch.github.status_map` is configured, see below), read once at
  * construction — matching the reference implementation's pattern and this
  * project's existing env-var-for-credentials philosophy. `listByLabel`
  * paginates up to `MAX_LIST_PAGES` (500 issues per label query) — no longer
@@ -17,7 +18,21 @@
  * page 1 would silently lose to a new low-priority one), not just a missed
  * issue. A repo past even that cap gets a loud warning, never a silent
  * truncation — see `listByLabel`'s own doc comment.
+ *
+ * State is modeled as labels (`<prefix>:ready`, etc.) — labels are spf's
+ * ACTUAL state machine and always get written, unconditionally. Native
+ * GitHub Projects v2 board status is a separate, OPTIONAL, best-effort layer
+ * on top (`syncStatus()`), driven entirely by `watch.github.status_map` —
+ * empty by default, so an existing config's behavior is unchanged. It's
+ * opt-in, and GraphQL-only (Projects v2 has no REST API), because not every
+ * repo has a board wired up, and a board's Status option names are per-
+ * project configuration `spf` can't assume; a misconfigured or unreachable
+ * entry degrades to a logged warning, never a thrown error — same rule
+ * `jira_provider.ts`'s own `syncStatus()` follows, for the same reason: a
+ * status-sync miss must never block the label update `spf watch` actually
+ * depends on.
  */
+import type { GithubStatusMap } from "../data_types.ts";
 import type { CodeHostProvider, EnsureLabelsResult, Issue, IssueAuthoringKind, IssueAuthoringProvider, IssueComment, IssueProvider, PrRef, PrStatus, WatchMarker, WatchState } from "./provider.ts";
 /**
  * The refine lane's leaf/container taxonomy — see `data_types.ts`'s
@@ -32,9 +47,23 @@ export declare class GitHubProvider implements IssueProvider, CodeHostProvider,
     private readonly repo;
     private readonly labelPrefix;
     private readonly token;
+    private readonly projectNumber;
+    private readonly statusMap;
+    /** Resolved lazily by `resolveProjectStatusField()` — cached only on SUCCESS, so a transient GraphQL hiccup gets retried the next call rather than disabling status sync for this instance's entire (potentially daemon-long) lifetime. */
+    private projectMeta?;
     constructor(repo: string, // "owner/name"
-    labelPrefix: string, token: string);
+    labelPrefix: string, token: string, projectNumber?: number, // 0 = status sync disabled, regardless of statusMap
+    statusMap?: GithubStatusMap);
     private gh;
+    /**
+     * Projects v2 has no REST surface at all — this is the one place this
+     * file talks GraphQL instead of REST. A GraphQL "not found" (bad login,
+     * bad project number, missing `project` scope) comes back as a 200 with a
+     * null data field plus an `errors` array, not a non-2xx — callers read
+     * `data` being falsy as "couldn't resolve," same as a 404 elsewhere in
+     * this file.
+     */
+    private ghGraphql;
     private label;
     private typeLabel;
     /** Mirrors `core/refine.ts`'s own module-level `priorityLabel()` — that one stays provider-agnostic (a plain string, no `this`); this one is `ensureLabels()`'s seeding half. */
@@ -82,6 +111,41 @@ export declare class GitHubProvider implements IssueProvider, CodeHostProvider,
         to?: WatchState;
     }): Promise<boolean>;
     transition(issue: Issue, to: WatchState, detail?: string): Promise<void>;
+    /**
+     * Best-effort native Projects v2 status sync — a no-op unless
+     * `project_number` AND `status_map` both configure something for `to`.
+     * Every failure mode (unconfigured, project/field not found, no matching
+     * option, a rejected mutation) is logged and swallowed, never thrown —
+     * see this file's module comment on why a status-sync miss must never
+     * break the label update callers depend on.
+     */
+    private syncStatus;
+    /**
+     * Resolves (and caches — see `projectMeta`'s own doc comment) `watch.github.project_number`'s
+     * "Status" single-select field against the repo OWNER's Projects v2 board
+     * (Projects v2 numbers are per-owner, not per-repo — see
+     * `WatchGithubConfigSchema`'s doc comment). Tries `organization(login:)`
+     * first, then `user(login:)`: an owner is exactly one of the two, and
+     * GraphQL returns that field as `null` (not a hard error) when it's the
+     * wrong kind, so falling through is safe.
+     */
+    private resolveProjectStatusField;
+    /** The item-id half of `syncStatus()`: an issue already on the project has one; otherwise this adds it, since a `status_map` entry is an implicit "yes, put this on the board" — the same way a Jira issue is already assumed to be on its project. `null` (logged) on any lookup/add failure. */
+    private resolveProjectItemId;
+    /**
+     * Read-only validation of the configured `status_map` against the real
+     * project's Status options — what `spf watch init` and `spf watch`'s own
+     * startup check call to catch a misnamed option before an unattended run
+     * silently no-ops its status sync every time, the same role
+     * `validateIssueTypes()`/`validateStatusMap()` play on the Jira side.
+     * Empty when `status_map` has no entries configured at all — nothing to
+     * report, not a mismatch.
+     */
+    validateStatusMap(): Promise<Array<{
+        state: string;
+        githubStatus: string;
+        exists: boolean;
+    }>>;
     comment(issue: Issue, body: string): Promise<void>;
     openPr(opts: {
         branch: string;

package/dist/core/issues/github_provider.js

@@ -86,11 +86,18 @@ export class GitHubProvider {
     repo;
     labelPrefix;
     token;
+    projectNumber;
+    statusMap;
+    /** Resolved lazily by `resolveProjectStatusField()` — cached only on SUCCESS, so a transient GraphQL hiccup gets retried the next call rather than disabling status sync for this instance's entire (potentially daemon-long) lifetime. */
+    projectMeta;
     constructor(repo, // "owner/name"
-    labelPrefix, token) {
+    labelPrefix, token, projectNumber = 0, // 0 = status sync disabled, regardless of statusMap
+    statusMap = {}) {
         this.repo = repo;
         this.labelPrefix = labelPrefix;
         this.token = token;
+        this.projectNumber = projectNumber;
+        this.statusMap = statusMap;
     }
     async gh(path, init) {
         const response = await fetch(`${API}${path}`, {
@@ -111,6 +118,34 @@ export class GitHubProvider {
             return undefined;
         return (await response.json());
     }
+    /**
+     * Projects v2 has no REST surface at all — this is the one place this
+     * file talks GraphQL instead of REST. A GraphQL "not found" (bad login,
+     * bad project number, missing `project` scope) comes back as a 200 with a
+     * null data field plus an `errors` array, not a non-2xx — callers read
+     * `data` being falsy as "couldn't resolve," same as a 404 elsewhere in
+     * this file.
+     */
+    async ghGraphql(query, variables) {
+        const response = await fetch(`${API}/graphql`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                Accept: "application/vnd.github+json",
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ query, variables }),
+        });
+        if (!response.ok) {
+            const detail = await response.text().catch(() => "");
+            throw new Error(`GitHub GraphQL -> ${response.status}: ${detail.slice(0, 500)}`);
+        }
+        const json = (await response.json());
+        if (!json.data) {
+            throw new Error(`GitHub GraphQL returned no data${json.errors ? `: ${json.errors.map((e) => e.message).join("; ")}` : ""}`);
+        }
+        return json.data;
+    }
     label(state) {
         return `${this.labelPrefix}:${state}`;
     }
@@ -242,8 +277,9 @@ export class GitHubProvider {
         return raw.filter((i) => !i.pull_request).map((i) => this.toIssue(i));
     }
     async claim(issue, opts) {
+        const toState = opts?.to ?? "working";
         const from = this.label(opts?.from ?? "ready");
-        const to = this.label(opts?.to ?? "working");
+        const to = this.label(toState);
         await this.gh(`/repos/${this.repo}/issues/${issue.id}/labels/${encodeURIComponent(from)}`, {
             method: "DELETE",
         }).catch(() => undefined); // already gone is fine
@@ -261,6 +297,9 @@ export class GitHubProvider {
                 body: JSON.stringify({ labels: [from] }),
             }).catch(() => undefined);
         }
+        else {
+            await this.syncStatus(issue, toState);
+        }
         return claimed;
     }
     async transition(issue, to, detail) {
@@ -274,9 +313,129 @@ export class GitHubProvider {
             method: "POST",
             body: JSON.stringify({ labels: [this.label(to)] }),
         });
+        await this.syncStatus(issue, to);
         if (detail)
             await this.comment(issue, detail);
     }
+    /**
+     * Best-effort native Projects v2 status sync — a no-op unless
+     * `project_number` AND `status_map` both configure something for `to`.
+     * Every failure mode (unconfigured, project/field not found, no matching
+     * option, a rejected mutation) is logged and swallowed, never thrown —
+     * see this file's module comment on why a status-sync miss must never
+     * break the label update callers depend on.
+     */
+    async syncStatus(issue, to) {
+        const statusName = this.statusMap[to];
+        if (!statusName)
+            return;
+        const meta = await this.resolveProjectStatusField();
+        if (!meta)
+            return; // already logged inside resolveProjectStatusField, or simply unconfigured (project_number: 0)
+        const optionId = meta.options.get(statusName);
+        if (!optionId) {
+            console.error(`spf watch: issue #${issue.id} — GitHub Projects #${this.projectNumber} has no Status option named ${JSON.stringify(statusName)} (watch.github.status_map.${to}) — skipping status sync, label already updated`);
+            return;
+        }
+        try {
+            const itemId = await this.resolveProjectItemId(issue, meta.projectId);
+            if (!itemId)
+                return; // already logged inside resolveProjectItemId
+            await this.ghGraphql(`mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
+          updateProjectV2ItemFieldValue(input: {projectId: $projectId, itemId: $itemId, fieldId: $fieldId, value: {singleSelectOptionId: $optionId}}) {
+            clientMutationId
+          }
+        }`, { projectId: meta.projectId, itemId, fieldId: meta.statusFieldId, optionId });
+        }
+        catch (err) {
+            console.error(`spf watch: issue #${issue.id} — GitHub Projects status sync to ${JSON.stringify(statusName)} failed; label already updated — ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Resolves (and caches — see `projectMeta`'s own doc comment) `watch.github.project_number`'s
+     * "Status" single-select field against the repo OWNER's Projects v2 board
+     * (Projects v2 numbers are per-owner, not per-repo — see
+     * `WatchGithubConfigSchema`'s doc comment). Tries `organization(login:)`
+     * first, then `user(login:)`: an owner is exactly one of the two, and
+     * GraphQL returns that field as `null` (not a hard error) when it's the
+     * wrong kind, so falling through is safe.
+     */
+    async resolveProjectStatusField() {
+        if (!this.projectNumber)
+            return null;
+        if (this.projectMeta)
+            return this.projectMeta;
+        const owner = this.repo.split("/")[0];
+        let data;
+        try {
+            data = await this.ghGraphql(`query($login: String!, $number: Int!) {
+          organization(login: $login) { projectV2(number: $number) { id fields(first: 50) { nodes { ... on ProjectV2SingleSelectField { id name options { id name } } } } } }
+          user(login: $login) { projectV2(number: $number) { id fields(first: 50) { nodes { ... on ProjectV2SingleSelectField { id name options { id name } } } } } }
+        }`, { login: owner, number: this.projectNumber });
+        }
+        catch (err) {
+            console.error(`spf watch: couldn't resolve GitHub Projects v2 #${this.projectNumber} for ${owner} — status sync skipped this run — ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+        const project = data.organization?.projectV2 ?? data.user?.projectV2;
+        if (!project) {
+            console.error(`spf watch: GitHub Projects v2 #${this.projectNumber} not found for ${owner} (or GITHUB_TOKEN lacks "project" scope) — status sync skipped this run`);
+            return null;
+        }
+        const statusField = project.fields.nodes.find((f) => f !== null && f.name === "Status");
+        if (!statusField) {
+            console.error(`spf watch: GitHub Projects v2 #${this.projectNumber} has no "Status" single-select field — status sync skipped this run`);
+            return null;
+        }
+        this.projectMeta = { projectId: project.id, statusFieldId: statusField.id, options: new Map(statusField.options.map((o) => [o.name, o.id])) };
+        return this.projectMeta;
+    }
+    /** The item-id half of `syncStatus()`: an issue already on the project has one; otherwise this adds it, since a `status_map` entry is an implicit "yes, put this on the board" — the same way a Jira issue is already assumed to be on its project. `null` (logged) on any lookup/add failure. */
+    async resolveProjectItemId(issue, projectId) {
+        const [owner, name] = this.repo.split("/");
+        let data;
+        try {
+            data = await this.ghGraphql(`query($owner: String!, $name: String!, $number: Int!) {
+          repository(owner: $owner, name: $name) {
+            issue(number: $number) { id projectItems(first: 20) { nodes { id project { id } } } }
+          }
+        }`, { owner, name, number: Number(issue.id) });
+        }
+        catch (err) {
+            console.error(`spf watch: issue #${issue.id} — couldn't look up its GitHub Projects item; status sync skipped, label already updated — ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+        const ghIssue = data.repository?.issue;
+        if (!ghIssue)
+            return null; // deleted between the label update and here — nothing left to sync
+        const existing = ghIssue.projectItems.nodes.find((n) => n.project.id === projectId);
+        if (existing)
+            return existing.id;
+        try {
+            const added = await this.ghGraphql(`mutation($projectId: ID!, $contentId: ID!) { addProjectV2ItemById(input: {projectId: $projectId, contentId: $contentId}) { item { id } } }`, { projectId, contentId: ghIssue.id });
+            return added.addProjectV2ItemById.item.id;
+        }
+        catch (err) {
+            console.error(`spf watch: issue #${issue.id} — couldn't add it to GitHub Projects #${this.projectNumber}; status sync skipped, label already updated — ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /**
+     * Read-only validation of the configured `status_map` against the real
+     * project's Status options — what `spf watch init` and `spf watch`'s own
+     * startup check call to catch a misnamed option before an unattended run
+     * silently no-ops its status sync every time, the same role
+     * `validateIssueTypes()`/`validateStatusMap()` play on the Jira side.
+     * Empty when `status_map` has no entries configured at all — nothing to
+     * report, not a mismatch.
+     */
+    async validateStatusMap() {
+        const entries = Object.entries(this.statusMap).filter((entry) => Boolean(entry[1]));
+        if (entries.length === 0)
+            return [];
+        const meta = await this.resolveProjectStatusField();
+        return entries.map(([state, githubStatus]) => ({ state, githubStatus, exists: meta ? meta.options.has(githubStatus) : false }));
+    }
     async comment(issue, body) {
         await this.gh(`/repos/${this.repo}/issues/${issue.id}/comments`, {
             method: "POST",