@timekast/factory 1.19.0 → 1.21.0

package/dist/commands/backlog.js

@@ -0,0 +1,706 @@
+/**
+ * `factory backlog push` — day-2 mirror of the LOCAL backlog to backlog.timekast.mx.
+ *
+ * Reads the repo's `project/backlog/*` epics + issues and pushes them, in CASCADE,
+ * to the central client-facing tracker: épicas → features (projected from each
+ * issue's `Refs (discovery)` `FT-XX` tokens) → issues (a `story` or a `task` per the
+ * `> **Board:**` field, default `story`). Milestones become releases (adopt-by-name,
+ * D12). It CONSUMES the BSYNC-002 REST client (`backlog-api.ts`) + the BSYNC-004
+ * parser/mapping (`backlog-parse.ts` / `backlog-mapping.ts`) — this file only
+ * orchestrates; it re-implements neither the HTTP nor the field mapping.
+ *
+ * READ-ONLY BY DEFAULT: with no `BACKLOG_API_KEY` / `BACKLOG_PROJECT_ID` in
+ * `.env.local`, it prints a note and exits 0 — the push NEVER blocks `/backlog`.
+ *
+ * IDEMPOTENCY (smoke Hallazgo 3): a re-POST of an existing client-supplied `id`
+ * returns `500` on the live API, NOT the documented `409` — so a status code is an
+ * UNRELIABLE "already exists" signal. The push therefore PRE-CHECKS existence with a
+ * single `getSyncState` read and skips what already exists; the `409` handling below
+ * is only a belt-and-suspenders for a race / a server that later fixes the code.
+ * Determinism (the stamped `Backlog UUID`, or the v5 fallback keyed on the Issue ID)
+ * is what actually guarantees a re-run never duplicates.
+ *
+ * FLAGS:
+ *   --reconcile  PATCH the element's status when it already exists (vs skip).
+ *   --stamp      Allow un-stamped issues/epics through AND write their UUID back to
+ *                the local markdown (invoked by tk-backlog Phase 8, BSYNC-008).
+ *   --backfill   Legacy campaign: same allow-through + write-back as --stamp, for a
+ *                one-by-one pass over a pre-BSYNC-007 backlog with no stamped UUIDs.
+ *   --source-lang <lang>  Source language of the pushed text (default `es`).
+ *
+ * The `is_factory` guard (D9 — the Factory never pushes its own backlog) lives in the
+ * tk-backlog Phase 8 caller (BSYNC-008), NOT here: this command pushes whatever
+ * backlog dir it is pointed at.
+ */
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { assignToRelease, BacklogApiError, createEpic, createFeature, createRelease, createStory, createTask, getSyncState, listBacklogReleases, patchElementStatus, } from '../lib/backlog-api.js';
+import { mapPriority, mapStatusToRemote, mapStoryPoints, resolveBacklogCredentials, } from '../lib/backlog-mapping.js';
+import { deterministicElementUuid, matchBlockquoteField, parseBacklogUuid, parseBoard, parseEpic, parseIssue, parseIssueId, parseStatus, parseTitle, } from '../lib/backlog-parse.js';
+export function parseBacklogPushFlags(argv) {
+    const langFlag = argv.find((a) => a.startsWith('--source-lang='));
+    const langIdx = argv.indexOf('--source-lang');
+    const sourceLang = (langFlag ? langFlag.split('=')[1] : langIdx >= 0 ? argv[langIdx + 1] : undefined) || 'es';
+    return {
+        reconcile: argv.includes('--reconcile'),
+        stamp: argv.includes('--stamp'),
+        backfill: argv.includes('--backfill'),
+        sourceLang,
+    };
+}
+/** Read every epic + issue markdown under each `project/backlog/{version}/` of `rootDir`. */
+export function collectBacklog(rootDir) {
+    const base = path.join(rootDir, 'project', 'backlog');
+    const epics = [];
+    const issues = [];
+    if (!existsSync(base))
+        return { epics, issues };
+    const readMd = (dir, sink) => {
+        if (!existsSync(dir))
+            return;
+        for (const name of readdirSync(dir).sort()) {
+            if (!name.endsWith('.md'))
+                continue;
+            const filePath = path.join(dir, name);
+            try {
+                sink.push({ path: filePath, content: readFileSync(filePath, 'utf8') });
+            }
+            catch {
+                // A single unreadable file must not abort the whole collection.
+            }
+        }
+    };
+    for (const version of readdirSync(base).sort()) {
+        const vdir = path.join(base, version);
+        let isDir = false;
+        try {
+            isDir = statSync(vdir).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        if (!isDir)
+            continue;
+        readMd(path.join(vdir, 'epics'), epics);
+        readMd(path.join(vdir, 'issues'), issues);
+    }
+    return { epics, issues };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Parse — epics + issues into a cascade plan
+// ─────────────────────────────────────────────────────────────────────────────
+/** The `EPIC-NN` token is the stable join key between an epic file and its issues. */
+const EPIC_TOKEN_RE = /EPIC-\d+/;
+/** Feature refs (`FT-01`, `FT-AUTH`, …) inside an issue's `Refs (discovery)` line. */
+const FT_TOKEN_RE = /FT-[A-Za-z0-9]+/g;
+function epicTokenOf(text) {
+    const match = text?.match(EPIC_TOKEN_RE);
+    return match ? match[0] : undefined;
+}
+/** The domain prefix of an Issue ID (`BSYNC-005` → `BSYNC`); the epic's humanPrefix. */
+function domainOf(issueId) {
+    if (!issueId)
+        return undefined;
+    const stripped = issueId.replace(/-\d+$/, '');
+    return (stripped || issueId).toUpperCase();
+}
+/** Most-frequent value (the epic's modal issue domain → humanPrefix — D10). */
+function modal(values) {
+    const counts = new Map();
+    for (const value of values)
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    let best;
+    let bestCount = -1;
+    for (const [value, count] of counts) {
+        if (count > bestCount) {
+            best = value;
+            bestCount = count;
+        }
+    }
+    return best;
+}
+function parseEpicNode(file) {
+    const fullId = parseIssueId(file.content) ?? path.basename(file.path, '.md');
+    const token = epicTokenOf(fullId) ?? epicTokenOf(path.basename(file.path)) ?? fullId;
+    const title = parseTitle(file.content) ?? token;
+    const milestone = matchBlockquoteField(file.content, 'Milestone');
+    const backlogUuid = parseBacklogUuid(file.content);
+    const uuid = backlogUuid ?? deterministicElementUuid(fullId);
+    return { file, token, fullId, title, milestone, backlogUuid, uuid, humanPrefix: 'EPIC' };
+}
+function parseIssueNode(file) {
+    const parsed = parseIssue(file.content);
+    const epicToken = epicTokenOf(parseEpic(file.content));
+    const refsLine = matchBlockquoteField(file.content, 'Refs (discovery)');
+    const featureTokens = refsLine
+        ? Array.from(new Set(Array.from(refsLine.matchAll(FT_TOKEN_RE), (m) => m[0])))
+        : [];
+    return { file, parsed, epicToken, featureTokens };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Stamp write-back (--stamp / --backfill)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Insert (or replace) the `> **Backlog UUID:** <uuid>` blockquote line so a re-run
+ * reads the same stamped id — the durable half of idempotency (§8). Idempotent: a
+ * file already carrying the same uuid is returned unchanged. Placed after the
+ * `> **Status:**` line (present in every issue/epic header).
+ */
+export function stampBacklogUuid(content, uuid) {
+    const line = `> **Backlog UUID:** ${uuid}`;
+    const existing = /[>-] \*\*Backlog UUID:\*\*[^\n]*/;
+    if (existing.test(content)) {
+        return content.replace(existing, line);
+    }
+    const statusLine = content.match(/[>-] \*\*Status:\*\*[^\n]*\n/);
+    if (statusLine) {
+        return content.replace(statusLine[0], `${statusLine[0]}${line}\n`);
+    }
+    // Fallback: right after the H1.
+    return content.replace(/^(#[^\n]*\n)/, `$1${line}\n`);
+}
+/** Adopt an existing release by name (D12 — releases take no client id). */
+function adoptReleaseByName(releases, name) {
+    const target = name.trim().toLowerCase();
+    for (const release of releases) {
+        const es = release.name?.['es']?.value;
+        if (typeof es === 'string' && es.trim().toLowerCase() === target)
+            return release.id;
+    }
+    return undefined;
+}
+/** Read the whole `sync-state` (paginated) into the existence pre-check set. */
+async function loadSyncState(apiKey, projectId, api, existing, items) {
+    const pageSize = 100;
+    let page = 1;
+    let total = Number.POSITIVE_INFINITY;
+    let seen = 0;
+    while (seen < total) {
+        const state = await getSyncState(apiKey, projectId, { page, pageSize }, api);
+        total = state.total;
+        for (const item of state.items) {
+            existing.add(item.id);
+            items.set(item.id, item);
+        }
+        seen += state.items.length;
+        if (state.items.length === 0)
+            break;
+        page += 1;
+    }
+}
+/**
+ * Push the LOCAL backlog to backlog.timekast.mx in cascade. Read-only degradation:
+ * no credentials → note + return (exit 0). Never throws for a per-element failure —
+ * it records it and continues (a `500`/`409`/network blip on one element must not
+ * abort the run — §4).
+ */
+export async function runBacklogPush(flags, rootDir = process.cwd(), deps = {}) {
+    const creds = (deps.credentials ?? ((dir) => resolveBacklogCredentials(dir)))(rootDir);
+    if (creds.status === 'not-configured') {
+        console.log(`ℹ️  Push al backlog central omitido: ${creds.reason}`);
+        console.log('   (read-only por defecto — el push nunca bloquea `/backlog`.)');
+        return;
+    }
+    const { apiKey, projectId } = creds;
+    const api = deps.api ?? {};
+    const writeFile = deps.writeFile ?? ((p, c) => writeFileSync(p, c, 'utf8'));
+    const writeBack = flags.stamp || flags.backfill;
+    const allowUnstamped = flags.stamp || flags.backfill;
+    // 1. Parse the local backlog.
+    const collected = (deps.collect ?? collectBacklog)(rootDir);
+    const issueNodes = collected.issues.map(parseIssueNode);
+    const epicNodes = collected.epics.map(parseEpicNode);
+    // Gate: skip un-stamped issues unless --stamp/--backfill (avoid spamming the
+    // central board with a whole legacy backlog on every `/backlog` run — §7).
+    const pushableIssues = issueNodes.filter((n) => n.parsed.backlogUuid !== undefined || allowUnstamped);
+    const skippedNoUuid = issueNodes.length - pushableIssues.length;
+    // Epics to push: only those a pushable issue hangs off (no orphan epics).
+    const pushableEpicTokens = new Set(pushableIssues.map((n) => n.epicToken).filter((t) => Boolean(t)));
+    const epicsToPush = epicNodes.filter((e) => pushableEpicTokens.has(e.token));
+    const epicByToken = new Map(epicsToPush.map((e) => [e.token, e]));
+    for (const epic of epicsToPush) {
+        const domains = pushableIssues
+            .filter((n) => n.epicToken === epic.token)
+            .map((n) => domainOf(n.parsed.issueId))
+            .filter((d) => Boolean(d));
+        epic.humanPrefix = modal(domains) ?? epic.humanPrefix;
+    }
+    // Features projected from each pushable issue's FT refs (§4; story sin FT → no
+    // feature is invented — the token set is simply empty for that issue).
+    const featureByToken = new Map();
+    for (const n of pushableIssues) {
+        for (const ft of n.featureTokens) {
+            if (featureByToken.has(ft))
+                continue;
+            const epicUuid = n.epicToken ? epicByToken.get(n.epicToken)?.uuid : undefined;
+            featureByToken.set(ft, { token: ft, uuid: deterministicElementUuid(ft), epicUuid });
+        }
+    }
+    // 2. Existence pre-check (the reliable idempotency signal, NOT the status code).
+    const existing = new Set();
+    const existingItems = new Map();
+    try {
+        await loadSyncState(apiKey, projectId, api, existing, existingItems);
+    }
+    catch {
+        console.warn('⚠ No pude leer `sync-state` (pre-check) — el push continúa best-effort.');
+    }
+    const created = new Set(existing);
+    const summary = { created: 0, reconciled: 0, skippedExisting: 0, failed: 0 };
+    const recordFail = (error) => {
+        summary.failed += 1;
+        const detail = error instanceof BacklogApiError ? `HTTP ${error.status}` : 'error';
+        console.warn(`⚠ Un elemento no se pudo pushear (${detail}) — el run continúa.`);
+    };
+    const stampFile = (file, uuid) => {
+        const next = stampBacklogUuid(file.content, uuid);
+        if (next !== file.content) {
+            writeFile(file.path, next);
+            file.content = next;
+        }
+    };
+    /** Create one element, honoring pre-check skip / --reconcile / 409-tolerance. */
+    const pushCreate = async (opts) => {
+        const { uuid, elementType } = opts;
+        const reconcile = async () => {
+            if (opts.reconcileStatus === undefined) {
+                summary.skippedExisting += 1;
+                return;
+            }
+            try {
+                await patchElementStatus(apiKey, projectId, elementType, uuid, opts.reconcileStatus, api);
+                summary.reconciled += 1;
+            }
+            catch (error) {
+                recordFail(error);
+            }
+        };
+        if (created.has(uuid)) {
+            if (flags.reconcile)
+                await reconcile();
+            else
+                summary.skippedExisting += 1;
+            return;
+        }
+        try {
+            await opts.create();
+            created.add(uuid);
+            summary.created += 1;
+            if (writeBack && opts.stampBack)
+                stampFile(opts.stampBack, uuid);
+        }
+        catch (error) {
+            // 409 = already exists (belt-and-suspenders; the live API returns 500 on
+            // collision — see file header — which is why the pre-check above is primary).
+            if (error instanceof BacklogApiError && error.status === 409) {
+                created.add(uuid);
+                if (flags.reconcile)
+                    await reconcile();
+                else
+                    summary.skippedExisting += 1;
+            }
+            else {
+                recordFail(error);
+            }
+        }
+    };
+    // 3. Cascade: épicas → features → issues.
+    for (const epic of epicsToPush) {
+        await pushCreate({
+            uuid: epic.uuid,
+            elementType: 'epic',
+            create: () => createEpic(apiKey, projectId, {
+                id: epic.uuid,
+                name: { es: epic.title },
+                humanPrefix: epic.humanPrefix,
+                sourceLang: flags.sourceLang,
+            }, api),
+            stampBack: epic.backlogUuid === undefined ? epic.file : undefined,
+        });
+    }
+    for (const feature of featureByToken.values()) {
+        await pushCreate({
+            uuid: feature.uuid,
+            elementType: 'feature',
+            create: () => createFeature(apiKey, projectId, {
+                id: feature.uuid,
+                name: { es: feature.token },
+                ...(feature.epicUuid ? { epicId: feature.epicUuid } : {}),
+                sourceLang: flags.sourceLang,
+            }, api),
+        });
+    }
+    for (const n of pushableIssues) {
+        const epic = n.epicToken ? epicByToken.get(n.epicToken) : undefined;
+        const featureUuid = n.featureTokens.length
+            ? featureByToken.get(n.featureTokens[0])?.uuid
+            : undefined;
+        const priority = mapPriority(n.parsed.priority);
+        const points = mapStoryPoints(n.parsed.storyPoints);
+        const title = { es: n.parsed.title ?? n.parsed.issueId ?? 'Sin título' };
+        const stampBack = n.parsed.backlogUuid === undefined ? n.file : undefined;
+        const reconcileStatus = mapStatusToRemote(n.parsed.status);
+        if (n.parsed.board === 'task') {
+            const parent = featureUuid
+                ? { type: 'feature', id: featureUuid }
+                : epic
+                    ? { type: 'epic', id: epic.uuid }
+                    : undefined;
+            if (!parent) {
+                summary.failed += 1;
+                console.warn(`⚠ ${n.parsed.issueId ?? n.file.path}: task sin épica ni feature padre — omitido.`);
+                continue;
+            }
+            const body = {
+                id: n.parsed.uuid,
+                title,
+                parent,
+                ...(priority ? { priority } : {}),
+                ...(points !== null ? { points } : {}),
+                sourceLang: flags.sourceLang,
+            };
+            await pushCreate({
+                uuid: n.parsed.uuid,
+                elementType: 'task',
+                create: () => createTask(apiKey, projectId, body, api),
+                reconcileStatus,
+                stampBack,
+            });
+        }
+        else {
+            // `story` (the default) — `bug` folds here too (no createBug primitive; it is
+            // an out-of-scope edge, story is the safe default per parseBoard).
+            const body = {
+                id: n.parsed.uuid,
+                title,
+                ...(epic ? { epicId: epic.uuid } : {}),
+                ...(featureUuid ? { featureId: featureUuid } : {}),
+                ...(n.parsed.moscow ? { moscow: n.parsed.moscow } : {}),
+                ...(priority ? { priority } : {}),
+                ...(points !== null ? { points } : {}),
+                sourceLang: flags.sourceLang,
+            };
+            await pushCreate({
+                uuid: n.parsed.uuid,
+                elementType: 'story',
+                create: () => createStory(apiKey, projectId, body, api),
+                reconcileStatus,
+                stampBack,
+            });
+        }
+    }
+    // 4. Releases (D12): one per unique `Milestone:`, adopt-by-name, assign ONLY epics
+    // (features/stories inherit; assigning a child 422s — smoke Hallazgo 5).
+    const milestones = new Map();
+    for (const epic of epicsToPush) {
+        if (!epic.milestone)
+            continue;
+        const list = milestones.get(epic.milestone) ?? [];
+        list.push(epic);
+        milestones.set(epic.milestone, list);
+    }
+    if (milestones.size > 0) {
+        let releases = [];
+        try {
+            releases = await listBacklogReleases(apiKey, projectId, api);
+        }
+        catch (error) {
+            recordFail(error);
+        }
+        for (const [name, epics] of milestones) {
+            let releaseId = adoptReleaseByName(releases, name);
+            if (releaseId) {
+                summary.skippedExisting += 1;
+            }
+            else {
+                try {
+                    releaseId = (await createRelease(apiKey, projectId, { name: { es: name }, sourceLang: flags.sourceLang }, api)).id;
+                    summary.created += 1;
+                }
+                catch (error) {
+                    recordFail(error);
+                    continue;
+                }
+            }
+            for (const epic of epics) {
+                try {
+                    await assignToRelease(apiKey, releaseId, 'epic', epic.uuid, api);
+                }
+                catch (error) {
+                    // 422 = the epic (or an ancestor) is already assigned — tolerated.
+                    if (!(error instanceof BacklogApiError && error.status === 422))
+                        recordFail(error);
+                }
+            }
+        }
+    }
+    // 5. Plain es-MX summary + the staff-curation note (visibility is server-side —
+    // smoke Hallazgo 8; pushed elements arrive invisible until staff curates once).
+    console.log(`✔ Push al backlog central: ${summary.created} creados, ${summary.reconciled} reconciliados, ` +
+        `${summary.skippedExisting} ya existían` +
+        (summary.failed ? `, ${summary.failed} con error (el run continuó)` : '') +
+        '.');
+    if (skippedNoUuid > 0) {
+        console.log(`ℹ️  ${skippedNoUuid} issue(s) sin \`Backlog UUID\` — omitidos. ` +
+            'Usa `--stamp` o `--backfill` para incluirlos y estamparlos.');
+    }
+    console.log('ℹ️  Los elementos llegan invisibles al board del cliente — el staff los hace visibles la primera vez (curación).');
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// `factory backlog sync` — point status-sync + self-healing heartbeat (BSYNC-006)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * `factory backlog sync` — the day-2 STATUS sync + self-healing heartbeat (D11).
+ * It runs a bounded, fire-and-forget pass over backlog.timekast.mx from the
+ * workflows (`/backlog`, `/implement`, BSYNC-010) — NEVER a blocking gate. Same
+ * "best-effort observability, NUNCA un gate; su fallo no aborta el flujo" principle
+ * `tk-deploy §7.5.6` already establishes for the dist-release verifier: a dead
+ * network, a failed PATCH, or a slow API cuts clean and lets the caller continue.
+ *
+ * TWO things happen under ONE 5s deadline (never blocks the caller past 5s):
+ *   1. POINT SYNC (skipped by `--heal-only`): `--issue <ID> --status <s>` /
+ *      `--epic <ID> --status <s>` resolves the element's STAMPED `Backlog UUID`
+ *      from the local markdown and PATCHes the remote status. A legacy element with
+ *      no stamped UUID is skipped-with-a-note (never crashes — §8).
+ *   2. SELF-HEALING HEARTBEAT: exactly ONE `GET /sync-state` (a heartbeat, NOT
+ *      polling), diffed `{ id → status }` remote-vs-local, repairing detected drift
+ *      via PATCH — capped at 10 repairs per invocation (never "repairs the world" in
+ *      one run; the rest wait for the next heartbeat). A repair PATCH that fails does
+ *      NOT abort the batch; the next invocation retries that element.
+ *
+ * It CONSUMES the BSYNC-002 client (`getSyncState` / `patchElementStatus`) + the
+ * BSYNC-004 parser/mapping — it re-implements neither the HTTP nor the field mapping.
+ */
+/** Overall deadline (ms) for one `sync` invocation — a slow API must never block the caller. */
+const SYNC_TIMEOUT_MS = 5_000;
+/** Max repairs per heartbeat — bounds the work so one run never "repairs the world". */
+const HEAL_MAX_REPAIRS = 10;
+/** Single-heartbeat page size — one `GET /sync-state`, not paginated polling. */
+const HEAL_PAGE_SIZE = 100;
+/** The 6 remote work states the API accepts (a `--status` value may already be one). */
+const REMOTE_STATUSES = [
+    'todo',
+    'in_progress',
+    'done',
+    'blocked',
+    'deferred',
+    'wont_do',
+];
+/** The 6 local buckets a `--status` value may use instead (mapped to remote). */
+const LOCAL_STATUS_KEYS = [
+    'todo',
+    'in-progress',
+    'done',
+    'wont-do',
+    'postponed',
+    'blocked',
+];
+/**
+ * Resolve a raw `--status` value to a remote {@link BacklogStatus}. Accepts BOTH the
+ * remote enum form (`in_progress`) and the local bucket form (`in-progress`) so the
+ * caller (a workflow or a dev) can pass either; an unknown value → `undefined` (the
+ * point sync then skips rather than PATCH a bogus status).
+ */
+function resolveStatusFlag(raw) {
+    if (!raw)
+        return undefined;
+    const value = raw.trim().toLowerCase();
+    if (REMOTE_STATUSES.includes(value))
+        return value;
+    if (LOCAL_STATUS_KEYS.includes(value)) {
+        return mapStatusToRemote(value);
+    }
+    return undefined;
+}
+/** Read a `--flag <value>` or `--flag=<value>` from argv; `undefined` if absent/bare. */
+function readFlagValue(argv, name) {
+    const eq = argv.find((a) => a.startsWith(`${name}=`));
+    if (eq)
+        return eq.slice(name.length + 1) || undefined;
+    const idx = argv.indexOf(name);
+    if (idx >= 0) {
+        const next = argv[idx + 1];
+        if (next !== undefined && !next.startsWith('--'))
+            return next;
+    }
+    return undefined;
+}
+/** Parse the `sync` argv into {@link BacklogSyncFlags}. `--issue` wins over `--epic`. */
+export function parseBacklogSyncFlags(argv) {
+    const issueId = readFlagValue(argv, '--issue');
+    const epicId = readFlagValue(argv, '--epic');
+    const status = readFlagValue(argv, '--status');
+    const healOnly = argv.includes('--heal-only');
+    const target = issueId
+        ? { kind: 'issue', id: issueId }
+        : epicId
+            ? { kind: 'epic', id: epicId }
+            : undefined;
+    return { target, status, healOnly };
+}
+/** The epic token (`EPIC-01`) an epic file carries, from its Issue ID / filename. */
+function epicIdOf(file) {
+    const fullId = parseIssueId(file.content) ?? path.basename(file.path, '.md');
+    const token = epicTokenOf(fullId) ?? epicTokenOf(path.basename(file.path));
+    return { fullId, token };
+}
+/** Locate the local file for a point-sync target. `undefined` if no such element. */
+function findTargetFile(target, collected) {
+    const wanted = target.id.toUpperCase();
+    if (target.kind === 'issue') {
+        return collected.issues.find((f) => parseIssueId(f.content)?.toUpperCase() === wanted);
+    }
+    return collected.epics.find((f) => {
+        const { fullId, token } = epicIdOf(f);
+        return token === wanted || fullId.toUpperCase() === wanted;
+    });
+}
+/**
+ * PATCH one element's remote status from its STAMPED local UUID. A legacy element
+ * with no stamped `Backlog UUID` is skipped-with-a-note (§8); a failed PATCH is
+ * logged (the self-healing retries it) but never thrown — the run continues.
+ */
+async function runPointSync(flags, collected, apiKey, projectId, api) {
+    if (!flags.target)
+        return;
+    const status = resolveStatusFlag(flags.status);
+    if (!status) {
+        console.warn(`⚠ Sync puntual omitido: \`--status\` ausente o inválido (${flags.status ?? '—'}).`);
+        return;
+    }
+    const { kind, id } = flags.target;
+    const file = findTargetFile(flags.target, collected);
+    if (!file) {
+        console.warn(`⚠ Sync puntual omitido: no encontré ${kind} \`${id}\` en el backlog local.`);
+        return;
+    }
+    // Require the STAMPED UUID (not the deterministic fallback): a legacy element
+    // without it is skipped-with-a-note rather than PATCHed against a guessed id.
+    const backlogUuid = parseBacklogUuid(file.content);
+    if (!backlogUuid) {
+        console.log(`ℹ️  ${id} sin \`Backlog UUID\` — omitido (elemento legacy sin estampar).`);
+        return;
+    }
+    const elementType = kind === 'epic' ? 'epic' : parseBoard(file.content);
+    try {
+        await patchElementStatus(apiKey, projectId, elementType, backlogUuid, status, api);
+        console.log(`✔ Sync puntual: ${id} → ${status} en el backlog central.`);
+    }
+    catch (error) {
+        const detail = error instanceof BacklogApiError ? `HTTP ${error.status}` : 'error';
+        console.warn(`⚠ Sync puntual de ${id} falló (${detail}) — el self-healing lo reintentará.`);
+    }
+}
+/**
+ * One self-healing heartbeat: a SINGLE `GET /sync-state`, diffed against the local
+ * SSOT, repairing status drift via PATCH — capped at {@link HEAL_MAX_REPAIRS}. Only
+ * status-bearing remote elements (story/task/bug — epic/feature carry `status: null`
+ * rollups) are diffable; only locally-stamped elements are matched (an un-stamped
+ * legacy issue is skipped, never crashes). A failed repair PATCH does not abort the
+ * batch — the next heartbeat retries that element.
+ */
+async function runHealing(collected, apiKey, projectId, api) {
+    const summary = { repaired: 0, failed: 0, skippedNoUuid: 0 };
+    let remote;
+    try {
+        remote = await getSyncState(apiKey, projectId, { page: 1, pageSize: HEAL_PAGE_SIZE }, api);
+    }
+    catch {
+        console.warn('⚠ No pude leer `sync-state` (heartbeat) — el self-healing se omite esta corrida.');
+        return summary;
+    }
+    // Local SSOT keyed by the STAMPED UUID (status-bearing elements = issues).
+    const localByUuid = new Map();
+    for (const file of collected.issues) {
+        const uuid = parseBacklogUuid(file.content);
+        if (!uuid) {
+            summary.skippedNoUuid += 1;
+            continue;
+        }
+        localByUuid.set(uuid, mapStatusToRemote(parseStatus(file.content)));
+    }
+    let attempts = 0;
+    for (const item of remote.items) {
+        if (attempts >= HEAL_MAX_REPAIRS)
+            break; // cap: the 11th drifted element waits for next run
+        if (item.status === null)
+            continue; // epic/feature rollup — no status axis to heal
+        const localStatus = localByUuid.get(item.id);
+        if (localStatus === undefined)
+            continue; // remote element we don't track locally
+        if (localStatus === item.status)
+            continue; // in sync — no-op
+        attempts += 1; // count the repair ATTEMPT toward the cap (bounds the network work)
+        try {
+            await patchElementStatus(apiKey, projectId, item.type, item.id, localStatus, api);
+            summary.repaired += 1;
+        }
+        catch {
+            // A single failed PATCH does not abort the batch — the next heartbeat retries it.
+            summary.failed += 1;
+        }
+    }
+    return summary;
+}
+/**
+ * Run `work` under a hard `ms` deadline. Returns `true` if it completed, `false` if
+ * the deadline fired first (the caller narrates the cut). A `work` rejection is
+ * treated as completion (point-sync/healing already swallow their own errors) so a
+ * late rejection never surfaces as an unhandled rejection. The default timer is
+ * `unref`'d + cleared so a completed run never lingers waiting on the deadline.
+ */
+async function runWithDeadline(ms, work, deadlineSleep) {
+    let timer;
+    const deadline = deadlineSleep
+        ? deadlineSleep(ms).then(() => 'timeout')
+        : new Promise((resolve) => {
+            timer = setTimeout(() => resolve('timeout'), ms);
+            if (typeof timer.unref === 'function')
+                timer.unref();
+        });
+    const done = work().then(() => 'done', () => 'done');
+    const outcome = await Promise.race([done, deadline]);
+    if (timer)
+        clearTimeout(timer);
+    return outcome === 'done';
+}
+/**
+ * Orchestrate `factory backlog sync`. Read-only degradation: no credentials → note +
+ * return (exit 0 — the sync NEVER blocks the workflow). The point sync (unless
+ * `--heal-only`) + the self-healing heartbeat both run under a single 5s deadline;
+ * on timeout the command cuts clean and the caller continues (fire-and-forget, §4).
+ */
+export async function runBacklogSync(flags, rootDir = process.cwd(), deps = {}) {
+    const creds = (deps.credentials ?? ((dir) => resolveBacklogCredentials(dir)))(rootDir);
+    if (creds.status === 'not-configured') {
+        console.log(`ℹ️  Sync al backlog central omitido: ${creds.reason}`);
+        console.log('   (fire-and-forget — el sync nunca bloquea el workflow.)');
+        return;
+    }
+    const { apiKey, projectId } = creds;
+    const api = deps.api ?? {};
+    const collected = (deps.collect ?? collectBacklog)(rootDir);
+    let heal = { repaired: 0, failed: 0, skippedNoUuid: 0 };
+    const work = async () => {
+        if (!flags.healOnly) {
+            await runPointSync(flags, collected, apiKey, projectId, api);
+        }
+        heal = await runHealing(collected, apiKey, projectId, api);
+    };
+    const completed = await runWithDeadline(SYNC_TIMEOUT_MS, work, deps.deadlineSleep);
+    if (!completed) {
+        console.warn(`⚠ Sync al backlog central cortado a los ${SYNC_TIMEOUT_MS / 1000}s — el workflow continúa sin esperar.`);
+        return;
+    }
+    if (heal.repaired || heal.failed) {
+        console.log(`✔ Self-healing: ${heal.repaired} reparado(s)` +
+            (heal.failed ? `, ${heal.failed} con error (reintenta la próxima corrida)` : '') +
+            '.');
+    }
+    else {
+        console.log('✔ Self-healing: sin drift (todo en sync).');
+    }
+    if (heal.skippedNoUuid > 0) {
+        console.log(`ℹ️  ${heal.skippedNoUuid} issue(s) sin \`Backlog UUID\` — fuera del heartbeat.`);
+    }
+}