@gr8ful/spf 0.13.0 → 0.15.0

package/dist/core/data_types.js

@@ -661,19 +661,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 +873,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, {})),
 });
@@ -834,6 +910,13 @@ export const NotificationsConfigSchema = v.object({
     events: v.optional(NotifyScopeSchema, "off"),
     timeout_ms: v.optional(v.number(), 5_000),
     channels: v.optional(v.array(NotifyChannelSchema), () => []),
+    // Prefixed onto every outbound title (e.g. "[api] watch: ..." ) and added
+    // as a `repo` field, so one Slack/Teams/webhook endpoint shared across
+    // several `spf watch` instances (one per repo) can tell them apart.
+    // Empty means "derive from watch.repo" (see `resolveNotifier`) — set this
+    // explicitly only when that repo string isn't a good enough label, e.g.
+    // it's blank, or two watched repos share a basename.
+    project: v.optional(v.string(), ""),
 });
 /**
  * `simple_sdlc`'s human-signoff gate — see the ACCEPTED ADVERSARIAL

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",

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

@@ -18,13 +18,22 @@
  *    one paragraph of plain text, nothing richer.
  *
  * State is modeled as Jira labels (`<prefix>:ready`, etc.), mirroring
- * `github_provider.ts` exactly, rather than native workflow status
- * transitions — the latter would need per-project transition-id mapping
- * (workflows vary by project/scheme in Jira), while labels work
- * identically everywhere with zero per-project setup. One caveat, verified
- * against Atlassian's own docs: colons ARE a legal label character and JQL
- * matches on them fine, they just don't show up in Jira's label
- * autocomplete UI — cosmetic only, not a functional issue.
+ * `github_provider.ts` exactly — labels are spf's ACTUAL state machine and
+ * always get written, unconditionally. One caveat, verified against
+ * Atlassian's own docs: colons ARE a legal label character and JQL matches
+ * on them fine, they just don't show up in Jira's label autocomplete UI —
+ * cosmetic only, not a functional issue.
+ *
+ * Native workflow status is a separate, OPTIONAL, best-effort layer on top
+ * (`syncStatus()`), driven entirely by the configured `statusMap` — empty
+ * by default, so an existing config's behavior is unchanged. It's optional
+ * rather than baked into every `transition()` call unconditionally because
+ * Jira workflows vary by project/scheme (status names, which transitions
+ * are reachable from where) in a way labels never do; a project that wants
+ * its board's Status column to move when spf changes a label opts in with
+ * `watch.jira.status_map`, and a misconfigured or unreachable entry there
+ * degrades to a logged warning, never a thrown error — a status-sync miss
+ * must never block the label update `spf watch` actually depends on.
  *
  * `ensureLabels()` is a no-op that reports the labels this run will use:
  * Jira labels are freeform strings with no color/description registry to
@@ -58,7 +67,7 @@
  * Jira API error at publish time — a genuine platform difference, not
  * something this file tries to paper over.
  */
-import type { JiraIssueTypeMap } from "../data_types.ts";
+import type { JiraIssueTypeMap, JiraStatusMap } from "../data_types.ts";
 import type { EnsureLabelsResult, Issue, IssueAuthoringKind, IssueAuthoringProvider, IssueComment, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
 export declare class JiraProvider implements IssueProvider, IssueAuthoringProvider {
     private readonly baseUrl;
@@ -67,8 +76,9 @@ export declare class JiraProvider implements IssueProvider, IssueAuthoringProvid
     private readonly email;
     private readonly apiToken;
     private readonly issueTypes;
+    private readonly statusMap;
     constructor(baseUrl: string, // e.g. "https://your-domain.atlassian.net", no trailing slash
-    projectKey: string, labelPrefix: string, email: string, apiToken: string, issueTypes: JiraIssueTypeMap);
+    projectKey: string, labelPrefix: string, email: string, apiToken: string, issueTypes: JiraIssueTypeMap, statusMap?: JiraStatusMap);
     private authHeader;
     private jira;
     private label;
@@ -145,6 +155,37 @@ export declare class JiraProvider implements IssueProvider, IssueAuthoringProvid
         to?: WatchState;
     }): Promise<boolean>;
     transition(issue: Issue, to: WatchState, detail?: string): Promise<void>;
+    /**
+     * Best-effort native workflow-status sync — a no-op unless `statusMap`
+     * configures a name for `to`. Looked up per call, not cached: the
+     * available transitions are FROM-status-dependent, so the same target
+     * status can need a different transition id depending where the issue
+     * currently sits, and this same issue's status keeps moving across calls
+     * as it advances through the build lane. Every failure mode here
+     * (unconfigured, unreachable, or a rejected transition) 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;
+    /**
+     * Read-only validation of the configured `status_map` against this
+     * project's real statuses — what `spf watch init` and `spf watch`'s own
+     * startup check should call to catch a misnamed status before an
+     * unattended run silently no-ops its status sync every time, the same
+     * role `validateIssueTypes()` plays for `issue_types`.
+     *
+     * Uses `/rest/api/3/project/{key}/statuses`, which groups statuses by
+     * issue type — Jira workflows can differ per issue type within one
+     * project. A configured name is "exists" if ANY issue type in the project
+     * has it: good enough to catch a typo, not a guarantee every issue type
+     * this map is used against can actually reach it (that's what
+     * `syncStatus()`'s own per-call transition lookup is for).
+     */
+    validateStatusMap(): Promise<Array<{
+        state: string;
+        jiraStatus: string;
+        exists: boolean;
+    }>>;
     comment(issue: Issue, body: string): Promise<void>;
     /** The single fetch every comment-reading method (`findMarkerComment`, `listComments`) builds on. */
     private fetchComments;

package/dist/core/issues/jira_provider.js

@@ -52,14 +52,16 @@ export class JiraProvider {
     email;
     apiToken;
     issueTypes;
+    statusMap;
     constructor(baseUrl, // e.g. "https://your-domain.atlassian.net", no trailing slash
-    projectKey, labelPrefix, email, apiToken, issueTypes) {
+    projectKey, labelPrefix, email, apiToken, issueTypes, statusMap = {}) {
         this.baseUrl = baseUrl;
         this.projectKey = projectKey;
         this.labelPrefix = labelPrefix;
         this.email = email;
         this.apiToken = apiToken;
         this.issueTypes = issueTypes;
+        this.statusMap = statusMap;
     }
     authHeader() {
         return `Basic ${Buffer.from(`${this.email}:${this.apiToken}`).toString("base64")}`;
@@ -213,8 +215,9 @@ export class JiraProvider {
         return Object.entries(this.issueTypes).map(([kind, jiraType]) => ({ kind, jiraType, exists: available.has(jiraType) }));
     }
     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);
         const next = issue.labels.filter((l) => l !== from);
         next.push(to);
         await this.jira(`/rest/api/3/issue/${issue.id}`, { method: "PUT", body: JSON.stringify({ fields: { labels: next } }) });
@@ -226,15 +229,72 @@ export class JiraProvider {
             revert.push(from);
             await this.jira(`/rest/api/3/issue/${issue.id}`, { method: "PUT", body: JSON.stringify({ fields: { labels: revert } }) }).catch(() => undefined);
         }
+        else {
+            await this.syncStatus(issue, toState);
+        }
         return claimed;
     }
     async transition(issue, to, detail) {
         const next = issue.labels.filter((l) => !STATES.some((s) => this.label(s) === l));
         next.push(this.label(to));
         await this.jira(`/rest/api/3/issue/${issue.id}`, { method: "PUT", body: JSON.stringify({ fields: { labels: next } }) });
+        await this.syncStatus(issue, to);
         if (detail)
             await this.comment(issue, detail);
     }
+    /**
+     * Best-effort native workflow-status sync — a no-op unless `statusMap`
+     * configures a name for `to`. Looked up per call, not cached: the
+     * available transitions are FROM-status-dependent, so the same target
+     * status can need a different transition id depending where the issue
+     * currently sits, and this same issue's status keeps moving across calls
+     * as it advances through the build lane. Every failure mode here
+     * (unconfigured, unreachable, or a rejected transition) 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;
+        let transitions;
+        try {
+            ({ transitions } = await this.jira(`/rest/api/3/issue/${issue.id}/transitions`));
+        }
+        catch (err) {
+            console.error(`spf watch: ${issue.id} — couldn't fetch available Jira transitions to sync status ${JSON.stringify(statusName)}; label already updated — ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        const match = transitions.find((t) => t.to.name === statusName);
+        if (!match) {
+            console.error(`spf watch: ${issue.id} has no available transition to Jira status ${JSON.stringify(statusName)} (watch.jira.status_map.${to}) from its current status — skipping status sync, label already updated`);
+            return;
+        }
+        await this.jira(`/rest/api/3/issue/${issue.id}/transitions`, { method: "POST", body: JSON.stringify({ transition: { id: match.id } }) }).catch((err) => {
+            console.error(`spf watch: ${issue.id} — Jira transition to ${JSON.stringify(statusName)} failed; label already updated — ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    /**
+     * Read-only validation of the configured `status_map` against this
+     * project's real statuses — what `spf watch init` and `spf watch`'s own
+     * startup check should call to catch a misnamed status before an
+     * unattended run silently no-ops its status sync every time, the same
+     * role `validateIssueTypes()` plays for `issue_types`.
+     *
+     * Uses `/rest/api/3/project/{key}/statuses`, which groups statuses by
+     * issue type — Jira workflows can differ per issue type within one
+     * project. A configured name is "exists" if ANY issue type in the project
+     * has it: good enough to catch a typo, not a guarantee every issue type
+     * this map is used against can actually reach it (that's what
+     * `syncStatus()`'s own per-call transition lookup is for).
+     */
+    async validateStatusMap() {
+        const result = await this.jira(`/rest/api/3/project/${encodeURIComponent(this.projectKey)}/statuses`);
+        const available = new Set(result.flatMap((t) => t.statuses.map((s) => s.name)));
+        return Object.entries(this.statusMap)
+            .filter((entry) => Boolean(entry[1]))
+            .map(([state, jiraStatus]) => ({ state, jiraStatus, exists: available.has(jiraStatus) }));
+    }
     async comment(issue, body) {
         await this.jira(`/rest/api/3/issue/${issue.id}/comment`, { method: "POST", body: JSON.stringify({ body: toAdf(body) }) });
     }

package/dist/core/notify/notifier.d.ts

@@ -18,13 +18,14 @@ export declare class Notifier {
     private readonly timeoutMs;
     private readonly dryRun;
     private readonly log;
+    private readonly project;
     private pending;
     constructor(channels: Array<{
         channel: NotificationChannel;
         scope: NotifyScope;
-    }>, timeoutMs: number, dryRun: boolean, log?: (message: string) => void);
+    }>, timeoutMs: number, dryRun: boolean, log?: (message: string) => void, project?: string);
     /** Sync, fire-and-forget — every call site is sync and must stay that way. */
-    send(event: NotifyEvent): void;
+    send(rawEvent: NotifyEvent): void;
     /** Await every in-flight send — call before process exit so a slow webhook isn't dropped mid-flight. */
     flush(): Promise<void>;
     /**