@gr8ful/spf 0.18.0 → 0.19.1

package/dist/core/data_types.js

@@ -528,6 +528,46 @@ export const ConfigDefaultsSchema = v.object({
     // the machinery that decides whether its work passed.
     // .spf/ is the whole per-repo footprint now — no adws/ tree to protect.
     protected_files: v.optional(v.array(v.string()), () => [".spf/", "spf.config.yaml"]),
+    /**
+     * Paths a READ-ONLY (or write-restricted) agent may touch WITHOUT failing
+     * the phase — `core/permissions.ts`'s `enforce()` still rolls every one of
+     * them back (an agent's claimed report must never rest on a change that
+     * didn't survive), it just does not count that rollback as a breach.
+     *
+     * WHY THIS EXISTS: a lockfile is dependency-manager BOOKKEEPING, not the
+     * repo's intent — an agent that ran `npm install` (to read a package's
+     * real shape, say) rewrites `package-lock.json` as a side effect of a
+     * read, not an edit. Observed live: a read-only scout phase failed with
+     * "scout is read-only but modified 1 path(s): factory/content/
+     * package-lock.json — rolled back" over exactly this, for work that
+     * changed nothing an operator would call "the code."
+     *
+     * The four defaults are the lockfiles of every package manager this repo
+     * already builds against (npm, pnpm, yarn, bun) — additive, not
+     * exhaustive; a repo using another one adds its own pattern here. Same
+     * glob syntax as `protected_files`/`agents[].writes` (`permissions.ts`'s
+     * `globToRegex`), where a leading "**" followed by a path separator
+     * matches at any depth INCLUDING the repo root — so the packaged
+     * defaults below match a lockfile whether it sits at the top of the repo
+     * or nested under a subdirectory.
+     *
+     * Emptying this list (`read_only_ignore: []`) restores today's strict
+     * behavior exactly — every touched path outside an agent's own allowlist
+     * fails the phase, lockfiles included.
+     *
+     * PRECEDENCE: `protected_files` always wins. A path matching
+     * `protected_files` is never ignorable via `read_only_ignore`, no matter
+     * how narrowly write-restricted the agent is — a pattern here that
+     * happens to also match a protected path is not read as "exempt this
+     * from protected_files too"; it stays a real breach. See
+     * `permissions.ts`'s `isSafeToIgnore` for the enforcement.
+     */
+    read_only_ignore: v.optional(v.array(v.string()), () => [
+        "**/package-lock.json",
+        "**/pnpm-lock.yaml",
+        "**/yarn.lock",
+        "**/bun.lockb",
+    ]),
     data_dir: v.optional(v.string(), ".spf/data"),
     /**
      * RUN BUDGET CEILINGS — the two knobs that bound what one adw_id may spend.
@@ -550,11 +590,20 @@ export const ConfigDefaultsSchema = v.object({
      * `agents.ts`'s `BudgetExceeded`.
      *
      * `max_run_cost` is USD (the same unit the provider's own usage.cost
-     * arrives in, summed by `UsageBreakdown`); `max_run_tokens` is TOTAL
-     * tokens, i.e. the spend number — every turn re-sends the whole
-     * conversation, so this counts cached re-reads too, exactly like the
-     * `total_tokens` column in `sessions` (see `ui/server/db.ts`'s `usage()`
-     * for why that number is much larger than "material moved").
+     * arrives in, summed by `UsageBreakdown`); `max_run_tokens` is BILLABLE
+     * tokens — `UsageBreakdown.billable_tokens` (input + cache-write + output),
+     * checked against `Run.billable_tokens`, NOT the `total_tokens` column
+     * `sessions` also carries for display. A prompt-caching backend (Ollama
+     * Cloud's kimi models, Anthropic's own caching) re-sends the whole
+     * conversation every turn as CACHE READS, which `total_tokens` counts and
+     * this ceiling does not: cache reads are billed (when billed at all) at a
+     * small fraction of input price, sometimes free, so a ceiling measured
+     * against the bigger number trips on bulk that cost nothing — observed
+     * live, one scout phase alone reported 1,311,740 total_tokens against a
+     * gateway that billed 189,321 uncached input + 17,908 output for it.
+     * `total_tokens` is kept exactly as before for anything display-only
+     * (the sessions-panel "tokens" line, the UI) — only the budget check
+     * changed which number it reads.
      *
      * Both are `> 0`, not `>= 0`: a zero ceiling would mean "no agent may ever
      * run", which is a config mistake, not a budget — it would fail the first
@@ -573,6 +622,43 @@ export const ConfigDefaultsSchema = v.object({
      */
     max_run_cost: v.optional(v.pipe(v.number(), v.gtValue(0))),
     max_run_tokens: v.optional(v.pipe(v.number(), v.integer(), v.gtValue(0))),
+    /**
+     * REQUEST TIMEOUT — how long a single agent dispatch may run before it is
+     * aborted and settled as failed, rather than hanging on a connection that
+     * silently died mid-call with nothing to notice.
+     *
+     * FLUE-SPECIFIC, unlike every other key in this schema: it maps straight
+     * onto `AgentStatics.durability.timeoutMs` (see `@flue/runtime`'s own
+     * docs), a `flue`-backend-only mechanism. `claude_code`/`opencode` are
+     * subprocess backends with no such knob today — this field is silently
+     * ignored for them, the same way `flue_db_path` on `AgentRequest` already
+     * is. Not a bug to fix here: a subprocess backend needs its own separate
+     * process-level timeout story, which is out of scope for this key.
+     *
+     * ABSENT BY DEFAULT, and absence is a total no-op: Flue's own default
+     * applies unchanged (1 hour, 10 attempts) — the same "surprise mid-run
+     * failure on a ceiling nobody chose is worse than the spend" reasoning as
+     * `max_run_cost`/`max_run_tokens` above. Set this when a hung connection
+     * should surface as an attributable failure (and feed the normal
+     * gate-correction / `spf watch` retry loop) in minutes, not however long
+     * Flue's own default takes — e.g. `300_000` for a five-minute ceiling.
+     * NOT a precise deadline, though: manual verification against a socket
+     * that accepts a connection and then sends nothing (see
+     * `request_timeout.test.ts`'s header comment) saw Flue's own timeout check
+     * fire on a coarser periodic sweep — a 3s ceiling settled at ~15s, not 3s.
+     * Bounded-but-imprecise is still a firm improvement over unbounded.
+     *
+     * SCOPE IS ONE SUBMISSION (one agent dispatch — the first prompt, one
+     * JSON-repair retry, one gate correction), NOT the accumulated run, unlike
+     * `max_run_cost`/`max_run_tokens` above. It is still process-scoped, not
+     * per-agent: Flue's `durability` is a static on the single shared agent
+     * function `agent_flue.ts` dispatches everything through, set once before
+     * the first dispatch of the process — see that file's `ensureRuntime()`.
+     * Deliberately NOT in `loadConfig`'s per-agent back-fill list for the same
+     * reason `max_run_cost`/`max_run_tokens` aren't: a per-agent copy would
+     * read as "this agent gets its own timeout", which nothing enforces.
+     */
+    request_timeout_ms: v.optional(v.pipe(v.number(), v.integer(), v.gtValue(0))),
 });
 /**
  * OpenTelemetry span export — OFF unless this block exists, and `endpoint` is
@@ -869,6 +955,30 @@ export const WatchJiraConfigSchema = v.object({
     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, {})),
+    /**
+     * The Jira issue-link `type` name `refine.ts`'s `publish()` uses to
+     * connect a freshly-published tree's ROOT issue(s) back to the spec they
+     * were refined from (`JiraProvider.linkToSpec`) — a plain, symmetric
+     * "issue link" (Jira's generic relate-two-issues mechanism), never the
+     * hierarchical `parent` field `linkChild` sets: the spec's own issue type
+     * defaults to Story (`issue_types.spec`), and a root node is often an
+     * Epic/Task — Jira's issue-type hierarchy frequently refuses a Story as
+     * one of those types' PARENT, so the hierarchy field is not a safe choice
+     * here regardless of which type actually published. "Relates" is a
+     * built-in link type on every Jira Cloud project; override this only if a
+     * project's admin has renamed or restricted it.
+     *
+     * MUST NAME A SYMMETRIC LINK TYPE. `JiraProvider.linkToSpec` fixes which
+     * side is `inwardIssue`/`outwardIssue` (the published root is always
+     * inward, the spec always outward) and does not expose direction as a
+     * separate knob — harmless for a symmetric type like "Relates" (Jira's UI
+     * does not even surface a direction for one), but pointing this at a
+     * DIRECTIONAL type (e.g. "blocks"/"is blocked by") would silently record
+     * the opposite relationship from the one intended. Only rename this to
+     * another symmetric type; a directional one needs code changes, not just
+     * config.
+     */
+    link_type: v.optional(v.string(), "Relates"),
 });
 /**
  * Optional, per-repo `WatchState` -> GitHub Projects v2 "Status" option-name
@@ -1230,6 +1340,24 @@ export class UsageBreakdown {
     // at the output rate. Report it nested under output, never added to it.
     reasoning_tokens = 0;
     total_tokens = 0;
+    /**
+     * The SPEND number, as distinct from `total_tokens` (the SIZE number).
+     * `input_tokens + output_tokens + cache_write_tokens` — `cache_read_tokens`
+     * excluded on purpose: a cache read is Anthropic's own prompt-caching
+     * discount (billed at a small fraction of the input rate, sometimes free
+     * on some gateways) for context the conversation already sent, not new
+     * material moved. `total_tokens` re-sends (and re-counts) the whole
+     * conversation every turn, so a long-running scout/build session's cache
+     * reads dwarf everything else in it (observed live: 1.31M total_tokens in
+     * one phase, of which 1.15M were cache reads the gateway did not bill as
+     * input) — a run-budget ceiling measured against `total_tokens` trips on
+     * cache-driven bulk that cost nothing, not on real spend. `assertRunBudget`
+     * (`agents.ts`) checks THIS field against `defaults.max_run_tokens`;
+     * `total_tokens` is kept, unchanged, for display (the sessions-panel
+     * "tokens" line, the UI) because an operator sizing context occupancy
+     * still needs the real re-send count, not the billable one.
+     */
+    billable_tokens = 0;
     input_cost = 0.0;
     output_cost = 0.0;
     cache_read_cost = 0.0;
@@ -1249,6 +1377,7 @@ export class UsageBreakdown {
         this.cache_write_tokens += usage.cacheWrite || 0;
         this.reasoning_tokens += usage.reasoning || 0;
         this.total_tokens += totalTokens;
+        this.billable_tokens += (usage.input || 0) + (usage.output || 0) + (usage.cacheWrite || 0);
         this.input_cost += cost.input || 0.0;
         this.output_cost += cost.output || 0.0;
         this.cache_read_cost += cost.cacheRead || 0.0;

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

@@ -14,8 +14,13 @@
  *    now is `/rest/api/3/search/jql`.
  *  - Comment/description bodies in API v3 are Atlassian Document Format
  *    (ADF) JSON, not plain strings — `{"body": "text"}` is rejected
- *    outright. `toAdf`/`adfToText` are the minimal round-trip this needs:
- *    one paragraph of plain text, nothing richer.
+ *    outright. Human/LLM-authored content (`comment()`, `createIssue()`)
+ *    goes through `markdownToAdf()`/`adfToMarkdown()` (`./markdown_adf.ts`)
+ *    for real Jira formatting; the local `toAdf()` minimal round-trip (one
+ *    paragraph of plain text, nothing richer) survives ONLY for
+ *    `writeMarker()`'s hidden `[spf-watch-marker]` JSON payload, which must
+ *    never pass through a real Markdown parser — see `toAdf`'s own doc
+ *    comment.
  *
  * State is modeled as Jira labels (`<prefix>:ready`, etc.), mirroring
  * `github_provider.ts` exactly — labels are spf's ACTUAL state machine and
@@ -66,6 +71,15 @@
  * `feature` (both mapping to Jira's Epic type by default) surfaces a real
  * Jira API error at publish time — a genuine platform difference, not
  * something this file tries to paper over.
+ *
+ * `linkToSpec` is the OTHER half of `IssueAuthoringProvider`'s hierarchy —
+ * a published tree's ROOT connected back to the spec it was refined FROM,
+ * which `linkChild` cannot express (the spec's own issue type, a Story by
+ * default, frequently cannot legally PARENT a root node's type). Uses
+ * Jira's plain issue-link API instead (`type` configurable via
+ * `watch.jira.link_type`, "Relates" by default), with a plain comment as
+ * its own fallback if that API is unavailable — see the method's own doc
+ * comment.
  */
 import type { JiraIssueTypeMap, JiraStatusMap } from "../data_types.ts";
 import type { EnsureLabelsResult, Issue, IssueAuthoringKind, IssueAuthoringProvider, IssueComment, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
@@ -77,8 +91,9 @@ export declare class JiraProvider implements IssueProvider, IssueAuthoringProvid
     private readonly apiToken;
     private readonly issueTypes;
     private readonly statusMap;
+    private readonly linkType;
     constructor(baseUrl: string, // e.g. "https://your-domain.atlassian.net", no trailing slash
-    projectKey: string, labelPrefix: string, email: string, apiToken: string, issueTypes: JiraIssueTypeMap, statusMap?: JiraStatusMap);
+    projectKey: string, labelPrefix: string, email: string, apiToken: string, issueTypes: JiraIssueTypeMap, statusMap?: JiraStatusMap, linkType?: string);
     private authHeader;
     private jira;
     private label;
@@ -129,6 +144,46 @@ export declare class JiraProvider implements IssueProvider, IssueAuthoringProvid
      * Epic-under-Epic limitation this implies.
      */
     linkChild(parent: Issue, child: Issue): Promise<void>;
+    /**
+     * `IssueAuthoringProvider.linkToSpec` — see its own doc comment
+     * (`issues/provider.ts`) for why this is a plain Jira "issue link"
+     * (`/rest/api/3/issueLink`) rather than `linkChild`'s hierarchy `parent`
+     * field: the spec's issue type (Story by default) frequently cannot
+     * legally PARENT a root node's type under Jira's issue-type hierarchy,
+     * while a generic issue link has no such restriction.
+     *
+     * `inwardIssue`/`outwardIssue` direction is arbitrary for a symmetric
+     * type like "Relates" — Jira does not surface it differently in the UI —
+     * so `issue` (the freshly published root) is the inward side and the
+     * spec is the outward side, consistently.
+     *
+     * BEST-EFFORT: this project's Jira instance may not have `linkType`
+     * enabled/named exactly this way (a renamed or removed link type, a
+     * permission scheme that disallows issue links for this project, ...) —
+     * a failure here must never fail the whole publish over what is, at
+     * bottom, a cosmetic cross-reference. Falls back to a plain comment
+     * naming the spec, so the relationship is visible SOMEWHERE even when
+     * the link API itself is unavailable.
+     *
+     * The fallback comment gets the SAME "never fail publish() over this"
+     * treatment as the link call itself: a rate limit or network blip on the
+     * comment call is just as cosmetic a failure as one on the link call, so
+     * it is caught and logged here rather than left to propagate out of
+     * `publish()` (`refine.ts`), which awaits this unguarded.
+     *
+     * `this.linkType` MUST name a SYMMETRIC link type ("Relates" and its
+     * project-renamed equivalents) — `inwardIssue`/`outwardIssue` above are
+     * fixed (the published root is always inward, the spec always outward)
+     * and not independently configurable, which is fine for a symmetric type
+     * (Jira does not surface the direction differently in the UI) but WRONG
+     * for a directional one (e.g. "blocks"/"is blocked by"): configuring
+     * `watch.jira.link_type` to a directional type would silently assert the
+     * opposite relationship from the one intended. See that field's own doc
+     * comment (`data_types.ts`) — direction is not exposed as a separate knob
+     * on purpose, to avoid a second config field only meaningful alongside a
+     * link type most projects never change from the "Relates" default.
+     */
+    linkToSpec(specId: string, issue: Issue): Promise<void>;
     /** The read-back half of `linkChild` — same JQL-in-body pattern as `searchByLabel`, since a GET with query params silently returns nothing on this endpoint (see the module comment). What makes container roll-up (`rollUp` in `watch.ts`) work on Jira too. */
     listChildren(parent: Issue): Promise<Issue[]>;
     /**

package/dist/core/issues/jira_provider.js

@@ -1,4 +1,5 @@
 import { fetchRetryTransient } from "../utils.js";
+import { adfToMarkdown, markdownToAdf } from "./markdown_adf.js";
 const STATES = [
     "ready",
     "working",
@@ -27,6 +28,19 @@ const STATES = [
  * here because nothing follows the JSON in this format at all.
  */
 const MARKER_RE = /\[spf-watch-marker\]\s*(\{.*\})/s;
+/**
+ * The ONLY remaining caller is `writeMarker()`'s hidden `[spf-watch-marker]`
+ * JSON payload — deliberately kept as this minimal, un-parsed shape (see
+ * this file's module comment) rather than routed through
+ * `markdownToAdf()`, because that payload must round-trip byte-for-byte
+ * through `MARKER_RE` and must never have its JSON characters (underscores,
+ * brackets, backticks) reinterpreted as Markdown syntax. Do not change this
+ * call site or add other callers — human/LLM-authored content
+ * (`comment()`, `createIssue()`) goes through `markdownToAdf()` instead, and
+ * reading ADF back to text goes through `adfToMarkdown()` (both imported
+ * from `./markdown_adf.ts`) — there is exactly one ADF-to-text
+ * implementation in this codebase now, not two divergent ones.
+ */
 function toAdf(text) {
     return {
         type: "doc",
@@ -34,17 +48,6 @@ function toAdf(text) {
         content: [{ type: "paragraph", content: [{ type: "text", text }] }],
     };
 }
-/** Walks an ADF document's `text` nodes and joins them — the minimal inverse of `toAdf`, not a full ADF renderer. */
-function adfToText(adf) {
-    if (!adf || typeof adf !== "object")
-        return "";
-    const node = adf;
-    if (node.type === "text" && typeof node.text === "string")
-        return node.text;
-    if (Array.isArray(node.content))
-        return node.content.map(adfToText).join("");
-    return "";
-}
 export class JiraProvider {
     baseUrl;
     projectKey;
@@ -53,8 +56,12 @@ export class JiraProvider {
     apiToken;
     issueTypes;
     statusMap;
+    linkType;
     constructor(baseUrl, // e.g. "https://your-domain.atlassian.net", no trailing slash
-    projectKey, labelPrefix, email, apiToken, issueTypes, statusMap = {}) {
+    projectKey, labelPrefix, email, apiToken, issueTypes, statusMap = {}, 
+    // See `WatchJiraConfigSchema.link_type`'s own doc comment (`data_types.ts`)
+    // — the issue-link `type` name `linkToSpec` below creates.
+    linkType = "Relates") {
         this.baseUrl = baseUrl;
         this.projectKey = projectKey;
         this.labelPrefix = labelPrefix;
@@ -62,6 +69,7 @@ export class JiraProvider {
         this.apiToken = apiToken;
         this.issueTypes = issueTypes;
         this.statusMap = statusMap;
+        this.linkType = linkType;
     }
     authHeader() {
         return `Basic ${Buffer.from(`${this.email}:${this.apiToken}`).toString("base64")}`;
@@ -101,7 +109,7 @@ export class JiraProvider {
         return {
             id: raw.key,
             title: raw.fields.summary,
-            body: raw.fields.description ? adfToText(raw.fields.description) : "",
+            body: raw.fields.description ? adfToMarkdown(raw.fields.description) : "",
             labels: raw.fields.labels,
         };
     }
@@ -163,7 +171,7 @@ export class JiraProvider {
                 fields: {
                     project: { key: this.projectKey },
                     summary: input.title,
-                    description: toAdf(input.body),
+                    description: markdownToAdf(input.body),
                     issuetype: { name: this.issueTypes[input.kind] },
                     labels: input.labels,
                 },
@@ -182,6 +190,69 @@ export class JiraProvider {
     async linkChild(parent, child) {
         await this.jira(`/rest/api/3/issue/${child.id}`, { method: "PUT", body: JSON.stringify({ fields: { parent: { key: parent.id } } }) });
     }
+    /**
+     * `IssueAuthoringProvider.linkToSpec` — see its own doc comment
+     * (`issues/provider.ts`) for why this is a plain Jira "issue link"
+     * (`/rest/api/3/issueLink`) rather than `linkChild`'s hierarchy `parent`
+     * field: the spec's issue type (Story by default) frequently cannot
+     * legally PARENT a root node's type under Jira's issue-type hierarchy,
+     * while a generic issue link has no such restriction.
+     *
+     * `inwardIssue`/`outwardIssue` direction is arbitrary for a symmetric
+     * type like "Relates" — Jira does not surface it differently in the UI —
+     * so `issue` (the freshly published root) is the inward side and the
+     * spec is the outward side, consistently.
+     *
+     * BEST-EFFORT: this project's Jira instance may not have `linkType`
+     * enabled/named exactly this way (a renamed or removed link type, a
+     * permission scheme that disallows issue links for this project, ...) —
+     * a failure here must never fail the whole publish over what is, at
+     * bottom, a cosmetic cross-reference. Falls back to a plain comment
+     * naming the spec, so the relationship is visible SOMEWHERE even when
+     * the link API itself is unavailable.
+     *
+     * The fallback comment gets the SAME "never fail publish() over this"
+     * treatment as the link call itself: a rate limit or network blip on the
+     * comment call is just as cosmetic a failure as one on the link call, so
+     * it is caught and logged here rather than left to propagate out of
+     * `publish()` (`refine.ts`), which awaits this unguarded.
+     *
+     * `this.linkType` MUST name a SYMMETRIC link type ("Relates" and its
+     * project-renamed equivalents) — `inwardIssue`/`outwardIssue` above are
+     * fixed (the published root is always inward, the spec always outward)
+     * and not independently configurable, which is fine for a symmetric type
+     * (Jira does not surface the direction differently in the UI) but WRONG
+     * for a directional one (e.g. "blocks"/"is blocked by"): configuring
+     * `watch.jira.link_type` to a directional type would silently assert the
+     * opposite relationship from the one intended. See that field's own doc
+     * comment (`data_types.ts`) — direction is not exposed as a separate knob
+     * on purpose, to avoid a second config field only meaningful alongside a
+     * link type most projects never change from the "Relates" default.
+     */
+    async linkToSpec(specId, issue) {
+        try {
+            await this.jira("/rest/api/3/issueLink", {
+                method: "POST",
+                body: JSON.stringify({
+                    type: { name: this.linkType },
+                    inwardIssue: { key: issue.id },
+                    outwardIssue: { key: specId },
+                }),
+            });
+        }
+        catch (linkError) {
+            try {
+                await this.comment(issue, `Refined from ${specId}.`);
+            }
+            catch (commentError) {
+                // Both the issue-link API and the comment fallback failed — the
+                // spec/root relationship is not recorded ANYWHERE on Jira this run,
+                // but that is still a cosmetic loss, not a reason to fail the whole
+                // publish (see this method's own doc comment).
+                console.error(`spf watch: ${issue.id} — could not link to spec ${specId} (${linkError instanceof Error ? linkError.message : String(linkError)}) and the fallback comment also failed — ${commentError instanceof Error ? commentError.message : String(commentError)}`);
+            }
+        }
+    }
     /** The read-back half of `linkChild` — same JQL-in-body pattern as `searchByLabel`, since a GET with query params silently returns nothing on this endpoint (see the module comment). What makes container roll-up (`rollUp` in `watch.ts`) work on Jira too. */
     async listChildren(parent) {
         const jql = `parent = ${JSON.stringify(parent.id)}`;
@@ -296,7 +367,7 @@ export class JiraProvider {
             .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) }) });
+        await this.jira(`/rest/api/3/issue/${issue.id}/comment`, { method: "POST", body: JSON.stringify({ body: markdownToAdf(body) }) });
     }
     /** The single fetch every comment-reading method (`findMarkerComment`, `listComments`) builds on. */
     async fetchComments(issueId) {
@@ -307,7 +378,7 @@ export class JiraProvider {
         const comments = await this.fetchComments(issueId);
         let found = null;
         for (const c of comments) {
-            const match = MARKER_RE.exec(adfToText(c.body));
+            const match = MARKER_RE.exec(adfToMarkdown(c.body));
             if (!match)
                 continue;
             try {
@@ -323,8 +394,8 @@ export class JiraProvider {
     async listComments(issue) {
         const comments = await this.fetchComments(issue.id);
         return comments
-            .filter((c) => !MARKER_RE.test(adfToText(c.body)))
-            .map((c) => ({ id: c.id, author: c.author?.displayName ?? "unknown", created_at: c.created, body: adfToText(c.body) }));
+            .filter((c) => !MARKER_RE.test(adfToMarkdown(c.body)))
+            .map((c) => ({ id: c.id, author: c.author?.displayName ?? "unknown", created_at: c.created, body: adfToMarkdown(c.body) }));
     }
     async readMarker(issue) {
         const found = await this.findMarkerComment(issue.id);

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

@@ -0,0 +1,58 @@
+/**
+ * A hand-rolled Markdown <-> Atlassian Document Format (ADF) converter for
+ * Jira comment/description bodies — deliberately NOT built on a markdown
+ * parsing library. This project has zero markdown dependencies today and
+ * that's a deliberate choice (see `package.json`): `jira_provider.ts`'s own
+ * `toAdf`/`adfToText` pair is the existing precedent (one paragraph of
+ * plain text, nothing richer), and this module is the same philosophy
+ * extended to a small, explicitly-bounded Markdown subset, not a general
+ * CommonMark implementation.
+ *
+ * SUPPORTED (confirmed scope, see the module's originating task — do not
+ * silently grow this list): ATX headings (`#`..`######`), bold
+ * (`**x**`/`__x__`), italic (`*x*`/`_x_`), strikethrough (`~~x~~`), inline
+ * code (`` `x` ``), fenced code blocks with optional language, bullet
+ * (`-`/`*`/`+`) and ordered (`1.`) lists with ONE level of nesting,
+ * blockquotes (consecutive `>` lines as one block), horizontal rules
+ * (`---`/`***`/`___` alone on a line), links (`[text](url)`), paragraphs
+ * separated by blank lines, and hard line breaks (a line ending in two-plus
+ * trailing spaces, or a lone trailing backslash).
+ *
+ * OUT OF SCOPE (tables, images, @mentions, raw HTML, nested blockquotes-in-
+ * lists, >1 level of list nesting): never crashes and never corrupts
+ * structure on these — `markdownToAdf` falls through to literal text in a
+ * plain paragraph (matching `toAdf`'s existing behavior for "everything"
+ * before this module existed), and `adfToMarkdown` degrades any node/mark
+ * type it doesn't recognize to its nested text content. `markdownToAdf`
+ * must NEVER throw on any input string — a malformed fence, an unmatched
+ * `**`, an empty link target, all degrade to literal text rather than
+ * erroring, because this runs unattended inside `spf watch`.
+ *
+ * ADF node/mark shapes below are taken from Atlassian's published document
+ * structure (developer.atlassian.com/cloud/jira/platform/apis/document/
+ * structure/), not guessed — in particular the strikethrough mark's real
+ * type name is `"strike"`, NOT `"strikethrough"` (an easy guess to get
+ * wrong), and ADF text nodes must never carry an empty `text` string (the
+ * schema requires non-empty), which is why every text-emitting path here
+ * checks for empty content before emitting a node instead of always
+ * emitting one unconditionally the way `jira_provider.ts`'s `toAdf` does
+ * for its single fixed paragraph.
+ */
+/**
+ * Parses the constrained Markdown subset (module comment) into an ADF
+ * document node. Never throws: every unrecognized or malformed construct
+ * degrades to literal text inside a plain paragraph rather than raising,
+ * because this feeds `spf watch`'s unattended comment/description writes.
+ */
+export declare function markdownToAdf(text: string): unknown;
+/**
+ * The inverse of `markdownToAdf`: renders an ADF document back into the
+ * same Markdown subset. NOT required to byte-match the original input
+ * (canonical forms are fine — e.g. always `-` for bullets even if the
+ * source used `*`), only to be semantically recognizable and to converge
+ * after one more round trip through `markdownToAdf`. Handles ADF built by
+ * this module OR hand-built elsewhere (e.g. Jira's own rich-text editor):
+ * any node or mark type it doesn't recognize degrades to its nested text
+ * content via `renderFallbackText` rather than throwing or dropping it.
+ */
+export declare function adfToMarkdown(adf: unknown): string;