@gr8ful/spf 0.13.0 → 0.15.0

package/README.md

@@ -766,9 +766,24 @@ A **classic** PAT (fine-grained tokens use different permission names — not co
 | Private | `repo` | Everything above, full read/write |
 | Public only | `public_repo` | The same, restricted to public repos |
 
-**Do not grant the `project` scope.** It's a separate, unrelated permission for GitHub Projects (classic/org/user boards) — `spf watch` doesn't touch Projects at all, so granting it would just be more access than this tool ever uses.
+There's no dedicated "issues" or "pull requests" scope on classic PATs — GitHub bundles both into `repo`/`public_repo`, which is why that table covers everything by default.
 
-There's no dedicated "issues" or "pull requests" scope on classic PATs — GitHub bundles both into `repo`/`public_repo`, which is why that's the whole table.
+Native GitHub Projects v2 board status (the board's Status column) is a separate, optional layer on top, off by default — labels alone don't move it, so an issue's Status sits wherever it started unless you opt in with `watch.github.project_number` and `watch.github.status_map`:
+
+```yaml
+watch:
+  issue_provider: github
+  repo: owner/name
+  github:
+    project_number: 3   # owner's Projects v2 board number — see the board's own URL
+    status_map:          # optional — unset by default, per state
+      ready: Todo
+      working: In Progress
+      review: In Review
+      done: Done
+```
+
+Only the states you map are touched; an unmapped state keeps today's label-only behavior, and `project_number: 0` (the default) disables sync outright regardless of `status_map`. This needs the **`project`** scope in addition to `repo`/`public_repo` — Projects v2 has no REST API at all, only GraphQL, and that surface is gated by its own scope; grant it only if you're using `status_map`. A configured option name with no matching Status option (or a rejected mutation) is logged and skipped, never thrown — the label update is what `spf watch` actually depends on; status sync is a best-effort convenience on top of it. `spf watch init` and `spf watch`'s own startup check both validate a configured `status_map` against the real project's Status options, read-only, and exit non-zero on a mismatch, the same way Jira's `issue_types` is validated below.
 
 ### Jira (`issue_provider: jira`)
 
@@ -777,9 +792,26 @@ export JIRA_EMAIL=you@example.com
 export JIRA_API_TOKEN=...   # id.atlassian.com -> Security -> API tokens
 ```
 
-State is modeled as Jira **labels** (`<prefix>:ready`, etc.), mirroring GitHub exactly, rather than native workflow status transitions — the latter would need per-project transition-id mapping, since workflows vary by project/scheme; labels work identically everywhere with zero per-project setup. One caveat: colons are a legal Jira label character and JQL matches on them fine, but they won't show up in Jira's own label autocomplete UI — cosmetic only.
+State is modeled as Jira **labels** (`<prefix>:ready`, etc.), mirroring GitHub exactly — labels are spf's actual state machine and always get written unconditionally, with zero per-project setup. One caveat: colons are a legal Jira label character and JQL matches on them fine, but they won't show up in Jira's own label autocomplete UI — cosmetic only.
 
-`spf watch init` still doesn't create any labels here (Jira labels are freeform strings with no color/description registry to seed, unlike GitHub's) — it reports the labels this run will use. But with `watch.refine.enabled`, it now also validates `watch.jira.issue_types` against the real project's issue types, read-only, and exits non-zero on a mismatch — see "Refining specs" above.
+Native Jira workflow status (the board's Status column) is a separate, optional layer on top, off by default — labels alone don't move it, so an issue's Status sits wherever it started unless you opt in with `watch.jira.status_map`:
+
+```yaml
+watch:
+  issue_provider: jira
+  jira:
+    base_url: https://your-domain.atlassian.net
+    project_key: PROJ
+    status_map:        # optional — unset by default, per state
+      ready: To Do
+      working: In Progress
+      review: In Review
+      done: Done
+```
+
+Only the states you map are touched; an unmapped state keeps today's label-only behavior. This is opt-in rather than automatic because Jira workflows vary by project/scheme — status names and which transitions are reachable from where isn't something spf can assume, unlike labels. A configured name with no reachable transition (or a rejected one) is logged and skipped, never thrown — the label update is what `spf watch` actually depends on; status sync is a best-effort convenience on top of it.
+
+`spf watch init` still doesn't create any labels here (Jira labels are freeform strings with no color/description registry to seed, unlike GitHub's) — it reports the labels this run will use. With `watch.refine.enabled`, it also validates `watch.jira.issue_types` against the real project's issue types, read-only, and exits non-zero on a mismatch — see "Refining specs" above. Independent of `refine.enabled`, if `watch.jira.status_map` has any entry configured, both `spf watch init` and `spf watch`'s own startup check validate it against the real project's statuses the same way, and exit non-zero on a mismatch.
 
 ### Bitbucket (`code_host: bitbucket`)
 
@@ -839,6 +871,22 @@ Getting each channel's URL:
 - **webhook** — any endpoint that accepts a JSON POST of the event: Discord,
   n8n, Zapier, a homegrown receiver.
 
+One webhook, many `spf` instances: if several repos' `spf watch` (or
+`spf run`) all post to the same Slack/Teams/webhook endpoint, set
+`notifications.project` to a short label so messages from each are
+distinguishable — it prefixes every title (`[api] watch: reconcileOrphans
+error`) and adds a `repo` field. Left unset, it falls back to `watch.repo`,
+so most `spf watch` setups need nothing extra; set it explicitly when
+`watch.repo` is blank or two watched repos share a basename.
+
+```yaml
+notifications:
+  events: attention
+  project: api            # optional; defaults to watch.repo
+  channels:
+    - kind: slack
+```
+
 Delivery never blocks or fails a run: an unconfigured/misconfigured channel
 is skipped with one warning, and a failed POST logs one line and is
 swallowed — never changes a run's exit code. One thing worth knowing under

package/assets/skill/references/config.md

@@ -160,6 +160,9 @@ Full mechanism: the main README's "`spf watch`" section. Field reference:
 | `chain_options` | map of string -> string | Options passed straight through to `chain` (and `refine.chain`) for every unattended dispatch — the same shape an interactive `spf <chain> --suite <name>` builds, e.g. `{suite: strict}` or `{agent: some-agent}`. Default `{}`. Only useful for a chain whose behavior actually reads the option (a step-derived chain's `--suite`; an imperative chain ignores an option it doesn't know about). |
 | `jira.base_url` / `jira.project_key` | string | Only consulted when `issue_provider: jira`. |
 | `jira.issue_types` | map: `epic`/`feature`/`story`/`bug`/`task`/`spec` -> string | Only consulted when `issue_provider: jira` AND `refine.enabled`. What each `RefinedIssue.kind` (plus `spec`, a standalone spec proposed by a split — see below) creates as on Jira — defaults `epic`/`feature` → `Epic`, `story`/`spec` → `Story`, `bug` → `Bug`, `task` → `Task`, overridable per kind. Validated against the real project by both `spf watch init` and `spf watch`'s own startup check. |
+| `jira.status_map` | map: `spec-ready`/`ready`/`working`/`review`/`done`/`blocked` -> string | Only consulted when `issue_provider: jira`. Optional, empty (unset) by default — when a state has no entry, `spf watch` updates only the `<prefix>:<state>` label on that transition, exactly as before this field existed. When a state IS mapped to a real Jira status name (e.g. `working: "In Progress"`), `spf watch` also transitions the issue's native Status field there, best-effort: no reachable transition, or a rejected one, is logged and skipped rather than failing the run — the label update is what `spf watch` actually depends on, status sync is a convenience on top. Validated against the real project's statuses by both `spf watch init` and `spf watch`'s own startup check, same as `issue_types`. |
+| `github.project_number` | int ≥0 | Only consulted when `issue_provider: github`. Which of the repo OWNER's Projects v2 boards `status_map` syncs against (Projects v2 numbers are per-owner, not per-repo — see the board's own URL). Default `0`, which disables status sync outright regardless of `status_map`; there's no sane "guess the board" default. |
+| `github.status_map` | map: `spec-ready`/`ready`/`working`/`review`/`done`/`blocked` -> string | Only consulted when `issue_provider: github` AND `project_number` is set. Optional, empty (unset) by default — an unmapped state stays label-only, a mapped one also sets the Projects v2 "Status" field, best-effort (no matching Status option, or a rejected mutation, is logged and skipped, never thrown — the label update is what `spf watch` actually depends on, status sync is a convenience on top). Needs `GITHUB_TOKEN` to carry the `project` scope in addition to `repo`/`public_repo` — Projects v2 is GraphQL-only. Validated against the real project's Status options by both `spf watch init` and `spf watch`'s own startup check. |
 | `refine.enabled` | bool | Turns on the second lane: decompose a `<prefix>:spec-ready` product spec into a feature/story-or-bug tree of real issues, instead of running `chain` against it directly (a spec isn't individually workable). Default `false` — off by default, so an existing `watch:` config is unaffected by upgrading. Needs `issue_provider: github` or `"jira"` — both implement issue authoring (create + link a hierarchy); any other value fails loudly at startup. |
 | `refine.chain` | string | Which registered chain runs per claimed spec. Default `refine`. |
 | `refine.concurrency` | int ≥1 | The refine lane's own budget, separate from `concurrency`. Default `1`. |
@@ -277,6 +280,7 @@ default; adding it is entirely additive.
 |---|---|---|
 | `events` | `"off"` \| `"errors"` \| `"attention"` \| `"all"` | The whole filter, narrowest to widest. `off` (default): nothing. `errors`: only true failures — failed runs/phases (`run_failed`/`phase_failed`), `watch_error`. `attention`: `errors` plus anything needing a human but not itself a failure — a blocked issue (`issue_blocked`) or a spec needing feedback (`spec_needs_feedback`). `all`: every curated milestone (run started, issue claimed, PR opened, ...) plus `attention` and `errors`. |
 | `timeout_ms` | int | Per-request timeout for a channel's HTTP POST. Default `5000`. |
+| `project` | string | Label prefixed onto every outbound title (`[api] watch: ...`) and added as a `repo` field — for disambiguating multiple `spf` instances that share one webhook. Default `""`, which falls back to `watch.repo`. |
 | `channels[]` | array | See below. |
 
 `channels[].kind`: `"slack"` \| `"teams"` \| `"webhook"`. `channels[].events`

package/dist/cli/commands/doctor.js

@@ -861,6 +861,14 @@ export async function doctorCommand(argv) {
                 ? "set"
                 : 'not set — spf watch needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo); see README.md\'s "GITHUB_TOKEN scope" section');
         }
+        if (cfg.watch.issue_provider === "github") {
+            const statusMapEntries = Object.entries(cfg.watch.github.status_map).filter(([, v]) => Boolean(v));
+            check(report, "watch.github.status_map", true, statusMapEntries.length > 0
+                ? cfg.watch.github.project_number
+                    ? `${statusMapEntries.length} state(s) configured to sync Projects v2 #${cfg.watch.github.project_number}'s Status field — run \`spf watch init\` to validate them, and make sure GITHUB_TOKEN has the "project" scope`
+                    : `${statusMapEntries.length} state(s) configured but watch.github.project_number is unset — status sync stays disabled until it's set`
+                : "not configured — spf watch will only update labels on this repo, never a Projects v2 board (optional, off by default)", "info");
+        }
         if (cfg.watch.issue_provider === "jira") {
             check(report, "watch.jira", Boolean(cfg.watch.jira.base_url.trim() && cfg.watch.jira.project_key.trim()), cfg.watch.jira.base_url.trim() && cfg.watch.jira.project_key.trim()
                 ? `${cfg.watch.jira.base_url} (${cfg.watch.jira.project_key})`
@@ -868,6 +876,10 @@ export async function doctorCommand(argv) {
             check(report, "JIRA_EMAIL / JIRA_API_TOKEN", Boolean(process.env["JIRA_EMAIL"] && process.env["JIRA_API_TOKEN"]), process.env["JIRA_EMAIL"] && process.env["JIRA_API_TOKEN"]
                 ? "set"
                 : 'not set — spf watch needs an Atlassian account email plus an API token (id.atlassian.com -> Security -> API tokens); see README.md\'s "spf watch" section');
+            const statusMapEntries = Object.entries(cfg.watch.jira.status_map).filter(([, v]) => Boolean(v));
+            check(report, "watch.jira.status_map", true, statusMapEntries.length > 0
+                ? `${statusMapEntries.length} state(s) configured to sync a native Jira status — run \`spf watch init\` to validate them against the real project's statuses`
+                : "not configured — spf watch will only update labels on this project, never the Jira Status field (optional, off by default)", "info");
         }
         if (cfg.watch.code_host === "bitbucket") {
             check(report, "BITBUCKET_EMAIL / BITBUCKET_API_TOKEN", Boolean(process.env["BITBUCKET_EMAIL"] && process.env["BITBUCKET_API_TOKEN"]), process.env["BITBUCKET_EMAIL"] && process.env["BITBUCKET_API_TOKEN"]
@@ -1023,6 +1035,15 @@ export async function doctorCommand(argv) {
             const label = ch.name ? `${ch.kind} (${ch.name})` : ch.kind;
             check(report, `notifications: ${label}`, Boolean(process.env[envKey]), process.env[envKey] ? `${envKey} set` : `${envKey} is not set`);
         }
+        // See `NotificationsConfigSchema.project`'s doc comment / `resolveNotifier`'s
+        // same fallback — informational only (never fails doctor), since an
+        // unset project tag is harmless unless this webhook ends up shared.
+        if (cfg.notifications.channels.length > 0) {
+            const project = cfg.notifications.project.trim() || cfg.watch.repo.trim();
+            check(report, "notifications.project", true, project
+                ? `tag: "${project}"`
+                : "not set, and watch.repo is empty — outbound messages won't carry a repo/project tag; if this webhook is ever shared across multiple spf instances, set notifications.project to tell them apart", project ? "info" : "warn");
+        }
     }
     return finish(report, flags["json"]);
 }

package/dist/cli/commands/watch.js

@@ -100,7 +100,7 @@ export function resolveIssueProvider(cfg) {
             console.error('GITHUB_TOKEN is not set — spf watch needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo). See README.md\'s "GITHUB_TOKEN scope" section.');
             return null;
         }
-        return new GitHubProvider(repo, cfg.watch.label_prefix, token);
+        return new GitHubProvider(repo, cfg.watch.label_prefix, token, cfg.watch.github.project_number, cfg.watch.github.status_map);
     }
     if (cfg.watch.issue_provider === "jira") {
         if (!cfg.watch.jira.base_url.trim() || !cfg.watch.jira.project_key.trim()) {
@@ -113,7 +113,7 @@ export function resolveIssueProvider(cfg) {
             console.error('JIRA_EMAIL and JIRA_API_TOKEN must both be set — spf watch needs an Atlassian account email plus an API token (id.atlassian.com -> Security -> API tokens). See README.md\'s "spf watch" section.');
             return null;
         }
-        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token, cfg.watch.jira.issue_types);
+        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token, cfg.watch.jira.issue_types, cfg.watch.jira.status_map);
     }
     console.error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} is not supported`);
     return null;
@@ -136,7 +136,7 @@ function resolveCodeHostProvider(cfg) {
             console.error('GITHUB_TOKEN is not set — spf watch needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo). See README.md\'s "GITHUB_TOKEN scope" section.');
             return null;
         }
-        return new GitHubProvider(cfg.watch.repo, cfg.watch.label_prefix, token);
+        return new GitHubProvider(cfg.watch.repo, cfg.watch.label_prefix, token, cfg.watch.github.project_number, cfg.watch.github.status_map);
     }
     if (cfg.watch.code_host === "bitbucket") {
         const email = process.env["BITBUCKET_EMAIL"];
@@ -196,6 +196,24 @@ export async function watchInitCommand(argv) {
         if (checks.some((c) => !c.exists))
             return 1;
     }
+    if (cfg.watch.issue_provider === "jira" && provider instanceof JiraProvider && Object.values(cfg.watch.jira.status_map).some(Boolean)) {
+        const checks = await provider.validateStatusMap();
+        console.log(`\nvalidating watch.jira.status_map against ${cfg.watch.jira.project_key}:`);
+        for (const c of checks) {
+            console.log(`  ${c.exists ? "✓" : "✗"} ${c.state} → ${c.jiraStatus}${c.exists ? "" : ` — no status named "${c.jiraStatus}" in ${cfg.watch.jira.project_key}`}`);
+        }
+        if (checks.some((c) => !c.exists))
+            return 1;
+    }
+    if (cfg.watch.issue_provider === "github" && provider instanceof GitHubProvider && Object.values(cfg.watch.github.status_map).some(Boolean)) {
+        const checks = await provider.validateStatusMap();
+        console.log(`\nvalidating watch.github.status_map against Projects v2 #${cfg.watch.github.project_number}:`);
+        for (const c of checks) {
+            console.log(`  ${c.exists ? "✓" : "✗"} ${c.state} → ${c.githubStatus}${c.exists ? "" : ` — no Status option named "${c.githubStatus}" on Projects v2 #${cfg.watch.github.project_number}`}`);
+        }
+        if (checks.some((c) => !c.exists))
+            return 1;
+    }
     return 0;
 }
 /** Shared by `runChain`/`runRefine`/the fan-out lane's dispatch: best-effort enrichment of a generic "didn't succeed" message with the first phase that actually failed, read back from the worktree's own (symlinked) trace db. Top-level (not a `watchCommand` local) so `makeWatchFanoutDispatch` below can share it — see that factory's own doc comment for why. */
@@ -396,6 +414,49 @@ export async function watchCommand(argv) {
             }
         }
     }
+    // watch.jira.status_map applies to every build-lane transition, independent
+    // of watch.refine.enabled — validated at startup for the same reason
+    // issue_types is: a bad status name should stop the daemon before it
+    // starts, not fail silently (well, log-and-skip — see jira_provider.ts's
+    // syncStatus()) on every single transition once it's running. Silent when
+    // status_map is empty (the default, opt-in feature) or has no mismatches.
+    if (cfg.watch.issue_provider === "jira" && provider instanceof JiraProvider) {
+        const configured = Object.values(cfg.watch.jira.status_map).some(Boolean);
+        if (configured) {
+            const checks = await provider.validateStatusMap();
+            const mismatches = checks.filter((c) => !c.exists);
+            if (mismatches.length > 0) {
+                console.error(`watch.jira.status_map has ${mismatches.length} mismatch(es) against ${cfg.watch.jira.project_key}:`);
+                for (const c of checks) {
+                    console.error(`  ${c.exists ? "✓" : "✗"} ${c.state} → ${c.jiraStatus}${c.exists ? "" : ` — no status named "${c.jiraStatus}" in ${cfg.watch.jira.project_key}`}`);
+                }
+                console.error(`Fix watch.jira.status_map, or the project's statuses, before running spf watch unattended. Run \`spf watch init\` any time to re-check.`);
+                return 1;
+            }
+        }
+    }
+    // watch.github.status_map applies to every build-lane transition,
+    // independent of watch.refine.enabled — validated at startup for the same
+    // reason watch.jira.issue_types is: a bad Status option name should stop
+    // the daemon before it starts, not fail silently (well, log-and-skip —
+    // see github_provider.ts's syncStatus()) on every single transition once
+    // it's running. Silent when status_map is empty (the default, opt-in
+    // feature) or has no mismatches.
+    if (cfg.watch.issue_provider === "github" && provider instanceof GitHubProvider) {
+        const configured = Object.values(cfg.watch.github.status_map).some(Boolean);
+        if (configured) {
+            const checks = await provider.validateStatusMap();
+            const mismatches = checks.filter((c) => !c.exists);
+            if (mismatches.length > 0) {
+                console.error(`watch.github.status_map has ${mismatches.length} mismatch(es) against Projects v2 #${cfg.watch.github.project_number}:`);
+                for (const c of checks) {
+                    console.error(`  ${c.exists ? "✓" : "✗"} ${c.state} → ${c.githubStatus}${c.exists ? "" : ` — no Status option named "${c.githubStatus}" on Projects v2 #${cfg.watch.github.project_number}`}`);
+                }
+                console.error(`Fix watch.github.status_map (and watch.github.project_number), or the project's Status options, before running spf watch unattended. Run \`spf watch init\` any time to re-check.`);
+                return 1;
+            }
+        }
+    }
     // watch.fanout.n > 1 startup gates — all guarded so watch.fanout.n: 1 (the
     // default) reaches none of them, and a bad configuration stops the daemon
     // before it starts rather than failing silently every tick.

package/dist/cli/interview.js

@@ -412,14 +412,22 @@ export async function runInterview(asker, ctx) {
             });
             const projectKey = await asker.text("Jira project key", { validate: (val) => (val.trim() ? null : "required") });
             watch.jira = { base_url: baseUrl.replace(/\/+$/, ""), project_key: projectKey.toUpperCase() };
+            asker.note("Jira workflow status (the board's Status column) stays untouched by default — labels alone drive spf watch. " +
+                "Opt in with watch.jira.status_map (per-state -> Jira status name) to also sync it, then run `spf watch init` to validate.");
         }
         const needsGithub = issueProvider === "github" || codeHost === "github";
         if (needsGithub) {
-            asker.note('classic PAT, "repo" scope (private) or "public_repo" (public-only) — never "project".');
+            asker.note(issueProvider === "github"
+                ? 'classic PAT, "repo" scope (private) or "public_repo" (public-only) — add "project" too if you plan to use watch.github.status_map (native Projects v2 board sync).'
+                : 'classic PAT, "repo" scope (private) or "public_repo" (public-only).');
             const token = await asker.secret("GITHUB_TOKEN", { current: ctx.existingEnv.get("GITHUB_TOKEN") });
             if (token)
                 env["GITHUB_TOKEN"] = token;
             envExampleKeys.push("GITHUB_TOKEN");
+            if (issueProvider === "github") {
+                asker.note("GitHub Projects v2 board status (the board's Status column) stays untouched by default — labels alone drive spf watch. " +
+                    "Opt in with watch.github.project_number + watch.github.status_map (per-state -> Status option name) to also sync it, then run `spf watch init` to validate.");
+            }
         }
         if (issueProvider === "jira") {
             const email = await asker.text("JIRA_EMAIL", { default: ctx.gitEmail ?? "" });
@@ -527,6 +535,15 @@ export async function runInterview(asker, ctx) {
             const timeoutMs = await asker.text("notifications.timeout_ms", { default: "5000" });
             if (timeoutMs !== "5000")
                 notifications.timeout_ms = Number(timeoutMs);
+            // Only matters when one Slack/Teams/webhook endpoint is shared across
+            // several `spf` instances — defaults to watch.repo (resolveNotifier's
+            // own fallback), so most single-repo setups can just accept it and
+            // write nothing extra into the generated config.
+            const repoDefault = watch?.repo || "";
+            asker.note("Tags every outbound title/field so messages are distinguishable if this webhook is shared across repos — defaults to watch.repo.");
+            const project = await asker.text("notifications.project", { default: repoDefault });
+            if (project !== repoDefault)
+                notifications.project = project;
         }
     }
     // ── 6. review + confirm ─────────────────────────────────────────────────────

package/dist/core/data_types.d.ts

@@ -839,14 +839,43 @@ export declare const JiraIssueTypeMapSchema: v.ObjectSchema<{
     readonly spec: v.OptionalSchema<v.StringSchema<undefined>, "Story">;
 }, undefined>;
 export type JiraIssueTypeMap = v.InferOutput<typeof JiraIssueTypeMapSchema>;
+/**
+ * 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 declare const JiraStatusMapSchema: v.ObjectSchema<{
+    readonly "spec-ready": v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly ready: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly working: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly review: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly done: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly blocked: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type JiraStatusMap = v.InferOutput<typeof JiraStatusMapSchema>;
 /**
  * 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 declare const WatchJiraConfigSchema: v.ObjectSchema<{
     readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
@@ -873,8 +902,85 @@ export declare const WatchJiraConfigSchema: v.ObjectSchema<{
         task: string;
         spec: string;
     }>;
+    readonly status_map: v.OptionalSchema<v.ObjectSchema<{
+        readonly "spec-ready": v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly ready: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly working: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly review: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly done: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly blocked: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, () => {
+        "spec-ready"?: string | undefined;
+        ready?: string | undefined;
+        working?: string | undefined;
+        review?: string | undefined;
+        done?: string | undefined;
+        blocked?: string | undefined;
+    }>;
 }, undefined>;
 export type WatchJiraConfig = v.InferOutput<typeof WatchJiraConfigSchema>;
+/**
+ * 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 declare const GithubStatusMapSchema: v.ObjectSchema<{
+    readonly "spec-ready": v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly ready: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly working: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly review: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly done: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly blocked: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type GithubStatusMap = v.InferOutput<typeof GithubStatusMapSchema>;
+/**
+ * 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 declare const WatchGithubConfigSchema: v.ObjectSchema<{
+    readonly project_number: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, 0>;
+    readonly status_map: v.OptionalSchema<v.ObjectSchema<{
+        readonly "spec-ready": v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly ready: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly working: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly review: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly done: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly blocked: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, () => {
+        "spec-ready"?: string | undefined;
+        ready?: string | undefined;
+        working?: string | undefined;
+        review?: string | undefined;
+        done?: string | undefined;
+        blocked?: string | undefined;
+    }>;
+}, undefined>;
+export type WatchGithubConfig = v.InferOutput<typeof WatchGithubConfigSchema>;
 /**
  * The second `spf watch` lane: decompose a `<prefix>:spec-ready` product
  * spec into a feature/story tree of real issues, instead of running
@@ -1024,6 +1130,21 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
             task: string;
             spec: string;
         }>;
+        readonly status_map: v.OptionalSchema<v.ObjectSchema<{
+            readonly "spec-ready": v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly ready: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly working: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly review: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly done: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly blocked: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, () => {
+            "spec-ready"?: string | undefined;
+            ready?: string | undefined;
+            working?: string | undefined;
+            review?: string | undefined;
+            done?: string | undefined;
+            blocked?: string | undefined;
+        }>;
     }, undefined>, () => {
         base_url: string;
         project_key: string;
@@ -1035,6 +1156,42 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
             task: string;
             spec: string;
         };
+        status_map: {
+            "spec-ready"?: string | undefined;
+            ready?: string | undefined;
+            working?: string | undefined;
+            review?: string | undefined;
+            done?: string | undefined;
+            blocked?: string | undefined;
+        };
+    }>;
+    readonly github: v.OptionalSchema<v.ObjectSchema<{
+        readonly project_number: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, 0>;
+        readonly status_map: v.OptionalSchema<v.ObjectSchema<{
+            readonly "spec-ready": v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly ready: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly working: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly review: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly done: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly blocked: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, () => {
+            "spec-ready"?: string | undefined;
+            ready?: string | undefined;
+            working?: string | undefined;
+            review?: string | undefined;
+            done?: string | undefined;
+            blocked?: string | undefined;
+        }>;
+    }, undefined>, () => {
+        project_number: number;
+        status_map: {
+            "spec-ready"?: string | undefined;
+            ready?: string | undefined;
+            working?: string | undefined;
+            review?: string | undefined;
+            done?: string | undefined;
+            blocked?: string | undefined;
+        };
     }>;
     readonly refine: v.OptionalSchema<v.ObjectSchema<{
         readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
@@ -1099,6 +1256,7 @@ export declare const NotificationsConfigSchema: v.ObjectSchema<{
         readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "attention", "all"], undefined>, undefined>, undefined>;
         readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
     }, undefined>, undefined>, () => never[]>;
+    readonly project: v.OptionalSchema<v.StringSchema<undefined>, "">;
 }, undefined>;
 export type NotificationsConfig = v.InferOutput<typeof NotificationsConfigSchema>;
 /**
@@ -1362,6 +1520,21 @@ export declare const SFConfigSchema: v.ObjectSchema<{
                 task: string;
                 spec: string;
             }>;
+            readonly status_map: v.OptionalSchema<v.ObjectSchema<{
+                readonly "spec-ready": v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly ready: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly working: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly review: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly done: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly blocked: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>, () => {
+                "spec-ready"?: string | undefined;
+                ready?: string | undefined;
+                working?: string | undefined;
+                review?: string | undefined;
+                done?: string | undefined;
+                blocked?: string | undefined;
+            }>;
         }, undefined>, () => {
             base_url: string;
             project_key: string;
@@ -1373,6 +1546,42 @@ export declare const SFConfigSchema: v.ObjectSchema<{
                 task: string;
                 spec: string;
             };
+            status_map: {
+                "spec-ready"?: string | undefined;
+                ready?: string | undefined;
+                working?: string | undefined;
+                review?: string | undefined;
+                done?: string | undefined;
+                blocked?: string | undefined;
+            };
+        }>;
+        readonly github: v.OptionalSchema<v.ObjectSchema<{
+            readonly project_number: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, 0>;
+            readonly status_map: v.OptionalSchema<v.ObjectSchema<{
+                readonly "spec-ready": v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly ready: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly working: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly review: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly done: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly blocked: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>, () => {
+                "spec-ready"?: string | undefined;
+                ready?: string | undefined;
+                working?: string | undefined;
+                review?: string | undefined;
+                done?: string | undefined;
+                blocked?: string | undefined;
+            }>;
+        }, undefined>, () => {
+            project_number: number;
+            status_map: {
+                "spec-ready"?: string | undefined;
+                ready?: string | undefined;
+                working?: string | undefined;
+                review?: string | undefined;
+                done?: string | undefined;
+                blocked?: string | undefined;
+            };
         }>;
         readonly refine: v.OptionalSchema<v.ObjectSchema<{
             readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
@@ -1420,6 +1629,25 @@ export declare const SFConfigSchema: v.ObjectSchema<{
                 task: string;
                 spec: string;
             };
+            status_map: {
+                "spec-ready"?: string | undefined;
+                ready?: string | undefined;
+                working?: string | undefined;
+                review?: string | undefined;
+                done?: string | undefined;
+                blocked?: string | undefined;
+            };
+        };
+        github: {
+            project_number: number;
+            status_map: {
+                "spec-ready"?: string | undefined;
+                ready?: string | undefined;
+                working?: string | undefined;
+                review?: string | undefined;
+                done?: string | undefined;
+                blocked?: string | undefined;
+            };
         };
         refine: {
             enabled: boolean;
@@ -1443,6 +1671,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             readonly events: v.OptionalSchema<v.NullableSchema<v.PicklistSchema<["off", "errors", "attention", "all"], undefined>, undefined>, undefined>;
             readonly name: v.OptionalSchema<v.StringSchema<undefined>, "">;
         }, undefined>, undefined>, () => never[]>;
+        readonly project: v.OptionalSchema<v.StringSchema<undefined>, "">;
     }, undefined>, () => {
         events: "all" | "attention" | "errors" | "off";
         timeout_ms: number;
@@ -1452,6 +1681,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             events?: "all" | "attention" | "errors" | "off" | null | undefined;
             name: string;
         }[];
+        project: string;
     }>;
     readonly review: v.OptionalSchema<v.ObjectSchema<{
         readonly require_human_signoff: v.OptionalSchema<v.BooleanSchema<undefined>, false>;