@timekast/factory 1.18.0 → 1.20.0

package/dist/commands/update.js

@@ -45,7 +45,7 @@ import { CLAUDE_MD_FILE, GITATTRIBUTES_FILE, LOCKFILE_FILE, PRETTIERIGNORE_FILE,
 import { decideCommit } from '../lib/commit-decision.js';
 import { extractManagedBlock, syncManagedBlock } from '../lib/gitattributes.js';
 import { diffLockfiles, hasLockfile, normalizeThenHash, planAutoRegister, readLockfile, writeLockfile, } from '../lib/lockfile.js';
-import { detectProfile, insertFactoryUpdateScript, setAgentKitVersion, } from '../lib/package-json.js';
+import { detectProfile, emptyShippedE2EPort, insertFactoryUpdateScript, setAgentKitVersion, } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
 import { printProvisionPointer } from '../lib/provision-pointer.js';
 import { hasProvisionState } from '../lib/provision-state.js';
@@ -58,6 +58,7 @@ export function parseUpdateFlags(argv) {
         mineAll: argv.includes('--mine-all'),
         resume: argv.includes('--resume'),
         verify: argv.includes('--verify'),
+        dryRun: argv.includes('--dry-run'),
         core: argv.includes('--core'),
         full: argv.includes('--full'),
         commit: argv.includes('--commit'),
@@ -332,6 +333,10 @@ function maintainDerivedPkg(rootDir, agentKitVersion) {
     try {
         warnOnScriptConflict(insertFactoryUpdateScript(pkgPath).action, pkgPath);
         setAgentKitVersion(pkgPath, agentKitVersion);
+        // Retire the E2E port the kit used to ship (`ports.e2e: 3006`) so the runner that just
+        // arrived via `scripts/**` can derive one per checkout. Conditional and silent: it only
+        // ever touches that exact value, so a dev-chosen port survives every update untouched.
+        emptyShippedE2EPort(pkgPath);
     }
     catch {
         console.warn('Aviso: no se pudo actualizar package.json (¿JSON inválido?); el cerebro se instaló igual. ' +
@@ -395,6 +400,26 @@ function syncDerivedPrettierignore(rootDir, stagedDir) {
         console.warn('Aviso: no se pudo sincronizar `.prettierignore`; el cerebro se instaló igual.');
     }
 }
+/** Exit code of `--dry-run` when the preview found conflicts (0 = none). Lets a
+ * non-interactive caller (the GUI) branch on the result instead of clobbering. */
+const DRY_RUN_CONFLICTS_EXIT = 2;
+/**
+ * `--dry-run`: preview the plan (buckets + the explicit conflict list) and apply
+ * NOTHING. Prints the conflicting paths so a human or agent sees exactly what
+ * collides before deciding. The GUI runs this first: no conflicts → it is safe to
+ * apply `--theirs-all` (only adds/overwrites of clean files); conflicts → hand off
+ * to the CLI for per-file resolution instead of silently taking theirs.
+ */
+function reportDryRun(diff, manifest) {
+    console.log(`\n🔍 Vista previa de update a v${manifest.version} — no se modificó nada:`);
+    reportSummary(diff, manifest);
+    if (diff.conflicts.length > 0) {
+        console.log('\nArchivos en conflicto (los modificaste tú y el Factory también los cambió):');
+        for (const c of diff.conflicts)
+            console.log(`  • ${c.path}`);
+        console.log('\nPara resolverlos, corre `factory update` (sin `--dry-run`): pregunta archivo por archivo.');
+    }
+}
 /** Print the deletes + kept-retired (design §7.6 — visible) + a one-line summary. */
 function reportSummary(diff, manifest) {
     if (diff.deleteSilent.length > 0) {
@@ -469,6 +494,9 @@ export async function runUpdate(flags, deps = {}) {
     if (flags.beta && flags.stable) {
         throw new CLIError('No puedes combinar `--beta` con `--stable`.');
     }
+    if (flags.dryRun && (flags.verify || flags.resume)) {
+        throw new CLIError('No puedes combinar `--dry-run` con `--verify` ni `--resume`.');
+    }
     // --verify and --resume short-circuit (no download).
     if (flags.verify) {
         runVerify(rootDir);
@@ -529,6 +557,14 @@ export async function runUpdate(flags, deps = {}) {
                 'El release está mal publicado; no se modificó nada.');
         }
         if (legacy) {
+            // --dry-run on a no-lockfile repo: nothing to conflict with (first sync has no
+            // prior version), so report clean and STOP — never auto-register under dry-run.
+            if (flags.dryRun) {
+                console.log('\n🔍 Vista previa: este repo aún no tiene lockfile. El primer `factory update` ' +
+                    'registra el cerebro; en el primer sync no hay conflictos posibles.');
+                process.exitCode = 0;
+                return;
+            }
             await applyLegacy(rootDir, stagedDir, manifest);
             // Legacy auto-register succeeded → end-pointer (PVSKILL-002).
             printProvisionPointer({ assumeYes: flags.yes });
@@ -542,6 +578,14 @@ export async function runUpdate(flags, deps = {}) {
         ]);
         const disk = hashDiskPaths(rootDir, trackedPaths);
         const diff = diffLockfiles(oldLock, manifest, disk);
+        // --dry-run: preview + STOP. No prompts, no apply, no lockfile, no commit.
+        // Exit 2 when conflicts exist so the GUI branches on it (0 otherwise). `return`
+        // runs the finally → tmpRoot is cleaned (no update-state was written).
+        if (flags.dryRun) {
+            reportDryRun(diff, manifest);
+            process.exitCode = diff.conflicts.length > 0 ? DRY_RUN_CONFLICTS_EXIT : 0;
+            return;
+        }
         // Resolve conflicts.
         const theirsConflicts = [];
         for (const conflict of diff.conflicts) {

package/dist/index.js

@@ -11,6 +11,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CLIError } from './lib/cli-error.js';
 import { parseAddFlags, runAdd } from './commands/add.js';
+import { parseBacklogPushFlags, parseBacklogSyncFlags, runBacklogPush, runBacklogSync, } from './commands/backlog.js';
 import { parseEnvPushFlags, parseEnvWizardFlags, runEnvPush, runEnvWizardApply, runEnvWizardGenVapid, runEnvWizardPlan, runEnvWizardReview, } from './commands/env.js';
 import { parseInviteAdminFlags, runInviteAdmin } from './commands/invite-admin.js';
 import { envWizardFlow } from './tui/env-wizard-flow.js';
@@ -40,7 +41,8 @@ Comandos:
                    (--launcher: verifica el entorno — Node ≥ 22, gh, gh auth, membresía org)
   publish <qué>    Publica el entregable (proposal|mockup|both) a proposals.timekast.mx
   unpublish [qué]  Baja del hub un entregable publicado (proposal|mockup|both; default both)
-  provision        Aprovisiona la infra de un derivado (Neon/Vercel/GitHub/DNS) — flag-driven, --json
+  provision        Aprovisiona la infra de un derivado (Neon/Vercel/GitHub/DNS/backlog) — flag-driven, --json
+  backlog <sub>    push: refleja el backlog local en backlog.timekast.mx · sync: status + self-healing
   secrets <file>   Mergea un archivo KEY=value de secretos de metodología a ~/.claude/.env (chmod 600)
   env <sub>        push: sube product vars a Vercel (day-2) · wizard: configura .env.local
   invite-admin     Crea una invitación de super_admin para un derivado (sin password en texto plano)
@@ -69,6 +71,7 @@ Sobre \`update\`:
     --mine-all     Conserva tu versión en todos los conflictos
     --resume       Retoma un update interrumpido sin re-descargar
     --verify       Reporta diferencias disco-vs-lockfile sin modificar nada
+    --dry-run      Previsualiza el plan (conflictos incluidos) SIN aplicar; sale 2 si hay conflictos
     --beta         Entra al canal beta (instala el último pre-release \`-beta.N\`)
     --stable       Sale del canal beta y baja al estable (limpia \`beta\` del lockfile)
     --yes / -y     Auto-confirma el auto-registro de un repo legacy (sin lockfile) —
@@ -81,7 +84,10 @@ Sobre \`provision\`:
   headless-safe; la interacción la pone la skill \`tk-provision\`. Preflight
   fail-closed (gh + tokens del gate + \`VERCEL_TOKEN\` con acceso al team);
   \`neonctl\` es opcional (ausente → warning). Flags:
-    --services=a,b   Servicios a crear (neon,vercel,github,dns)
+    --services=a,b   Servicios a crear (neon,vercel,github,dns,backlog). \`backlog\`
+                     registra el proyecto en backlog.timekast.mx y escribe
+                     BACKLOG_API_KEY + BACKLOG_PROJECT_ID a .env.local (requiere
+                     BACKLOG_ADMIN_TOKEN en el rail; ausente en un bundle → se omite)
     --slug=<slug>    Identificador del stack (nombre del proyecto + dominios interinos)
     --team=<id>      Team de Vercel (override; default = \`VERCEL_TEAM_ID\` del rail ~/.claude/.env)
     --org-id=<id>    Org de GitHub (override; default = org del Factory)
@@ -117,6 +123,24 @@ Sobre \`env\`:
     --plan [--json]  Emite el plan de preguntas (lo consume el agente / la skill tk-provision)
     --apply [--push] Lee \`{ answers, push? }\` JSON por stdin y escribe \`.env.local\`
 
+Sobre \`backlog\`:
+  \`backlog push\` refleja el backlog local (\`project/backlog/*\`) en
+  backlog.timekast.mx en cascada (épicas → features de los Refs \`FT-XX\` → issues
+  story/task según el campo \`Board:\`). Read-only por defecto: sin \`BACKLOG_API_KEY\`
+  en \`.env.local\` termina con exit 0 y una nota (nunca bloquea \`/backlog\`). Flags:
+    --reconcile      PATCH del status cuando el elemento ya existe (en vez de saltarlo)
+    --stamp          Incluye issues/épicas sin UUID y estampa su \`Backlog UUID\` de vuelta
+    --backfill       Campaña legacy: incluye + estampa un backlog pre-BSYNC-007 completo
+    --source-lang <l>  Idioma del texto pusheado (default \`es\`)
+
+  \`backlog sync\` actualiza el status de un elemento puntual y corre un heartbeat de
+  self-healing (repara drift vs backlog.timekast.mx). Fire-and-forget: sin
+  \`BACKLOG_API_KEY\` termina con exit 0; acotado a un deadline de 5s (nunca bloquea el
+  workflow). Flags:
+    --issue <ID> --status <s>   PATCH del status de un issue (s: enum remoto o bucket local)
+    --epic <ID>  --status <s>   Equivalente para una épica
+    --heal-only                 Corre solo el self-healing (sin el sync puntual)
+
 Sobre \`invite-admin\`:
   Materializa el primer super_admin de un derivado por invitación (reemplaza el
   viejo seed con password en texto plano). Resuelve la connection string del
@@ -220,6 +244,23 @@ async function main(argv) {
             await runProvision(parseProvisionFlags(rest));
             return;
         }
+        case 'backlog': {
+            const sub = rest[0];
+            // `factory backlog push` — mirror the local backlog to backlog.timekast.mx.
+            // Read-only by default (no key → exit 0).
+            if (sub === 'push') {
+                await runBacklogPush(parseBacklogPushFlags(rest.slice(1)));
+                return;
+            }
+            // `factory backlog sync` — point status-sync + self-healing heartbeat
+            // (BSYNC-006). Fire-and-forget: no key → exit 0; bounded to a 5s deadline.
+            if (sub === 'sync') {
+                await runBacklogSync(parseBacklogSyncFlags(rest.slice(1)));
+                return;
+            }
+            throw new CLIError(`Subcomando de backlog desconocido: \`${sub ?? '(ninguno)'}\`. ` +
+                'Uso: `factory backlog push` | `factory backlog sync`.');
+        }
         case 'publish': {
             await runPublish(parsePublishArgs(rest));
             return;

package/dist/lib/atomic-swap.js

@@ -25,13 +25,20 @@ import path from 'node:path';
 import { CLIError } from './cli-error.js';
 import { CLAUDE_MD_FILE, TIMEKAST_DIR } from './constants.js';
 import { parseLockfile } from './lockfile.js';
-/** Roots a manifest path may live under (mirrors `profiles.json#track`). */
-const ALLOWED_ROOTS = ['.claude/', 'scripts/', '.husky/'];
+/**
+ * Roots a manifest path may live under (mirrors `profiles.json#track`).
+ *
+ * `.github/workflows/` is deliberately NARROWER than `.github/` — the tracked set is
+ * only the CI workflows, and widening the guard to the whole directory would let a
+ * tampered tarball rewrite issue templates, CODEOWNERS or funding config.
+ */
+const ALLOWED_ROOTS = ['.claude/', 'scripts/', '.husky/', '.github/workflows/'];
 /**
  * Reject a manifest path that is unsafe to write: absolute, escaping via `..`, or
- * outside the tracked scope (`.claude/**`, `scripts/**`, `CLAUDE.md`, `.husky/**`). A correct
- * release never produces these — this guards a mispublished/tampered tarball from
- * writing `src/` or escaping the repo root. Separator-agnostic (Windows-safe).
+ * outside the tracked scope (`.claude/**`, `scripts/**`, `CLAUDE.md`, `.husky/**`,
+ * `.github/workflows/**`). A correct release never produces these — this guards a
+ * mispublished/tampered tarball from writing `src/` or escaping the repo root.
+ * Separator-agnostic (Windows-safe).
  */
 export function assertSafeTrackedPath(rel) {
     const segments = rel.split(/[\\/]/);
@@ -40,7 +47,7 @@ export function assertSafeTrackedPath(rel) {
     }
     const tracked = rel === CLAUDE_MD_FILE || ALLOWED_ROOTS.some((root) => rel.startsWith(root));
     if (!tracked) {
-        throw new CLIError(`El manifest declara \`${rel}\`, fuera del scope rastreado (\`.claude/\`, \`scripts/\`, \`CLAUDE.md\`, \`.husky/\`). ` +
+        throw new CLIError(`El manifest declara \`${rel}\`, fuera del scope rastreado (\`.claude/\`, \`scripts/\`, \`CLAUDE.md\`, \`.husky/\`, \`.github/workflows/\`). ` +
             'El release está mal construido; no se tocó nada.');
     }
 }

package/dist/lib/backlog-api.js

@@ -0,0 +1,302 @@
+/**
+ * Backlog-central REST v1 client for the Factory ↔ backlog.timekast.mx integration.
+ *
+ * A THIN HTTP client that MIRRORS the proven fetch shape of `neon-api.ts`
+ * (`Authorization: Bearer ${key}` + a constant base URL + a typed error carrying
+ * the HTTP status + an injectable `fetchImpl` seam) — we reuse that shape rather
+ * than reinvent an HTTP client per command (issue §6). The provision/push/sync
+ * commands (BSYNC-003/005/006) consume this single surface instead of each
+ * hand-rolling headers/errors/backoff.
+ *
+ * TWO auth scopes ride the SAME `Authorization: Bearer` header; the CALLER picks
+ * which key to pass (this client does not distinguish them):
+ *   - the org-level `admin` token (rail `BACKLOG_ADMIN_TOKEN`) — ONLY the three
+ *     org endpoints: `POST /projects`, `POST /projects/{pid}/keys`,
+ *     `DELETE /projects/{pid}`. It 403s (`PROJECT_NOT_IN_KEY`) on anything scoped
+ *     to a project's elements.
+ *   - the per-project `read_write` key (derivative `.env.local` `BACKLOG_API_KEY`)
+ *     — every element/release/sync-state/summary call.
+ * (Live-verified separation — `project/abraham/smoke-findings.md` Hallazgo 1.)
+ *
+ * Every call surfaces a typed {@link BacklogApiError} on a non-2xx response that
+ * carries the HTTP status + best-effort body, so the caller can map edge cases to
+ * actionable es-MX messages. The `429` (rate ~120 req/min) backoff lives HERE, in
+ * the shared request helper — NOT in the parser/mapping of BSYNC-004 (issue §6).
+ *
+ * The `fetch` impl is an INJECTABLE seam (`BacklogApiDeps.fetchImpl`) so the unit
+ * tests drive method + URL + payload with a mock and NEVER hit the live network;
+ * the real end-to-end exercise is BSYNC-001 (spike) + BSYNC-014 (E2E).
+ */
+/** Backlog-central REST v1 base (`servers[0].url` of the live `/openapi.json`). */
+export const BACKLOG_API_BASE = 'https://backlog.timekast.mx/api/v1';
+/** Timeout (ms) per call — a dead network must not hang the command using it. */
+const BACKLOG_API_TIMEOUT_MS = 30_000;
+/**
+ * A `429 Too Many Requests` (rate ~120 req/min) is retried with linear backoff —
+ * same shape `neon-api.ts` uses for its `423` lock retry. Tests inject a no-op
+ * `sleepImpl` so no real time passes.
+ */
+const BACKLOG_RATE_MAX_RETRIES = 4;
+const BACKLOG_RATE_BACKOFF_MS = 1_000;
+// ─────────────────────────────────────────────────────────────────────────────
+// Error + injectable seams (calqued 1:1 from neon-api.ts)
+// ─────────────────────────────────────────────────────────────────────────────
+/** A non-2xx response from the backlog API. Carries the HTTP status for mapping. */
+export class BacklogApiError extends Error {
+    status;
+    /** The raw response body (best-effort, truncated) — context, never a secret. */
+    body;
+    constructor(status, body, context) {
+        super(`Backlog API ${status} en ${context}: ${body || '(sin cuerpo)'}`);
+        this.name = 'BacklogApiError';
+        this.status = status;
+        this.body = body;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Path segment (plural) per element type — the API routes elements by plural. */
+const ELEMENT_PATH_SEGMENT = {
+    epic: 'epics',
+    feature: 'features',
+    story: 'stories',
+    task: 'tasks',
+    bug: 'bugs',
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Shared request helper — headers, timeout, 429 backoff, error, `{data}` unwrap
+// ─────────────────────────────────────────────────────────────────────────────
+/** Shared headers for every backlog call (Bearer auth + JSON). */
+function backlogHeaders(apiKey) {
+    return {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+    };
+}
+/** Read a response body as text (best-effort) for error context — never throws. */
+async function safeBody(response) {
+    try {
+        return (await response.text()).slice(0, 500);
+    }
+    catch {
+        return '';
+    }
+}
+/** Parse a JSON body defensively — a missing/invalid body yields `{}`, never throws. */
+async function safeJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Perform one backlog call: Bearer headers + JSON body + per-call abort timeout,
+ * retrying `429` with linear backoff (the ONE place backoff lives — issue §6).
+ * On any other non-2xx it throws a typed {@link BacklogApiError}. On success it
+ * unwraps the universal `{ data }` envelope and returns `data` typed as `T`.
+ *
+ * @throws {BacklogApiError} on any non-2xx (after exhausting the 429 retries).
+ */
+async function backlogRequest(apiKey, path, init, context, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const sleep = deps.sleepImpl ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const doFetch = () => fetchImpl(`${BACKLOG_API_BASE}${path}`, {
+        method: init.method,
+        headers: backlogHeaders(apiKey),
+        ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+        signal: AbortSignal.timeout(BACKLOG_API_TIMEOUT_MS),
+    });
+    // Retry on 429 (rate limit) with linear backoff — every endpoint can hit it.
+    let response = await doFetch();
+    for (let attempt = 0; response.status === 429 && attempt < BACKLOG_RATE_MAX_RETRIES; attempt++) {
+        await sleep(BACKLOG_RATE_BACKOFF_MS * (attempt + 1));
+        response = await doFetch();
+    }
+    if (!response.ok) {
+        throw new BacklogApiError(response.status, await safeBody(response), context);
+    }
+    const json = (await safeJson(response));
+    return json.data;
+}
+/**
+ * Create the backlog project — `POST /projects` with the org-level `admin` token.
+ * `internalKey` is our slug (server validates `^[a-z0-9-]{3,40}$`; a collision
+ * 409s `INTERNAL_KEY_TAKEN` — the caller adopts the existing project). Returns the
+ * project id (`{pid}`) + its public board UUID (smoke Hallazgo 1).
+ *
+ * @throws {BacklogApiError} on any non-2xx (409 = internalKey taken → adopt).
+ */
+export async function createBacklogProject(adminToken, input, deps = {}) {
+    const data = await backlogRequest(adminToken, '/projects', {
+        method: 'POST',
+        body: {
+            name: input.name,
+            internalKey: input.internalKey,
+            defaultLanguage: input.defaultLanguage ?? 'es',
+            enabledLanguages: input.enabledLanguages ?? ['es', 'en'],
+        },
+    }, 'POST /projects', deps);
+    if (!data?.id || !data?.publicUuid) {
+        throw new BacklogApiError(201, JSON.stringify(data).slice(0, 500), 'POST /projects (respuesta sin id/publicUuid)');
+    }
+    return { id: data.id, publicUuid: data.publicUuid };
+}
+/**
+ * Mint a per-project `read_write` key — `POST /projects/{pid}/keys` with the
+ * `admin` token. The returned `plaintextKey` (`tk_live_*`, scope fixed to this
+ * project) is SHOW-ONCE: it is the only time this value is readable, so the caller
+ * writes it straight to `.env.local` (`BACKLOG_API_KEY`) and never logs it.
+ *
+ * @throws {BacklogApiError} on any non-2xx.
+ */
+export async function mintBacklogKey(adminToken, projectId, keyName, deps = {}) {
+    const data = await backlogRequest(adminToken, `/projects/${encodeURIComponent(projectId)}/keys`, { method: 'POST', body: { name: keyName } }, 'POST /projects/{pid}/keys', deps);
+    if (!data?.plaintextKey) {
+        throw new BacklogApiError(201, JSON.stringify(data).slice(0, 500), 'POST /projects/{pid}/keys (respuesta sin plaintextKey)');
+    }
+    return data.plaintextKey;
+}
+/**
+ * Soft-delete the backlog project — `DELETE /projects/{pid}` with the `admin`
+ * token. It DEACTIVATES (does not hard-delete, does not cascade) and is
+ * IDEMPOTENT: a repeat returns 200 with the same `{ deactivated: true }` (smoke
+ * Hallazgo 7). Unblocks `--destroy` (BSYNC-003).
+ *
+ * @throws {BacklogApiError} on any non-2xx.
+ */
+export async function deleteBacklogProject(adminToken, projectId, deps = {}) {
+    await backlogRequest(adminToken, `/projects/${encodeURIComponent(projectId)}`, { method: 'DELETE' }, 'DELETE /projects/{pid}', deps);
+}
+/**
+ * Shared POST for the four element creates — `POST /projects/{pid}/{plural}`.
+ * The body is the caller's already-mapped payload (BSYNC-004 builds it); this
+ * client only performs the HTTP call. Returns the created id + minted humanId.
+ *
+ * NOTE on idempotency: a re-POST of an existing `id` currently returns `500`
+ * (NOT the documented `409 ELEMENT_ID_EXISTS`) — smoke Hallazgo 3. So the push
+ * (BSYNC-005) MUST pre-check existence via {@link getSyncState}, not treat a
+ * status here as an "already exists" signal.
+ *
+ * @throws {BacklogApiError} on any non-2xx.
+ */
+async function createElement(apiKey, projectId, segment, body, context, deps) {
+    const data = await backlogRequest(apiKey, `/projects/${encodeURIComponent(projectId)}/${segment}`, { method: 'POST', body }, context, deps);
+    const humanId = data?.humanId;
+    // The response may echo the id; fall back to the client-supplied one we sent.
+    const id = data?.id ?? body.id;
+    if (!id || !humanId) {
+        throw new BacklogApiError(201, JSON.stringify(data).slice(0, 500), `${context} (respuesta sin id/humanId)`);
+    }
+    return { id, humanId };
+}
+/** Create an epic — `POST /projects/{pid}/epics`. @throws {BacklogApiError} on non-2xx. */
+export async function createEpic(apiKey, projectId, body, deps = {}) {
+    return createElement(apiKey, projectId, 'epics', body, 'POST /projects/{pid}/epics', deps);
+}
+/** Create a feature — `POST /projects/{pid}/features`. @throws {BacklogApiError} on non-2xx. */
+export async function createFeature(apiKey, projectId, body, deps = {}) {
+    return createElement(apiKey, projectId, 'features', body, 'POST /projects/{pid}/features', deps);
+}
+/** Create a story — `POST /projects/{pid}/stories`. @throws {BacklogApiError} on non-2xx. */
+export async function createStory(apiKey, projectId, body, deps = {}) {
+    return createElement(apiKey, projectId, 'stories', body, 'POST /projects/{pid}/stories', deps);
+}
+/** Create a task — `POST /projects/{pid}/tasks`. @throws {BacklogApiError} on non-2xx. */
+export async function createTask(apiKey, projectId, body, deps = {}) {
+    return createElement(apiKey, projectId, 'tasks', body, 'POST /projects/{pid}/tasks', deps);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Element status PATCH — per-project `read_write` key (BSYNC-005/006)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Update one element's status — `PATCH /projects/{pid}/{plural}/{id}` with
+ * `{ status }` (smoke Hallazgo 3). `elementType` selects the plural path segment.
+ * The response `{ updated: true }` is not echoed back to the caller.
+ *
+ * @throws {BacklogApiError} on any non-2xx.
+ */
+export async function patchElementStatus(apiKey, projectId, elementType, elementId, status, deps = {}) {
+    const segment = ELEMENT_PATH_SEGMENT[elementType];
+    await backlogRequest(apiKey, `/projects/${encodeURIComponent(projectId)}/${segment}/${encodeURIComponent(elementId)}`, { method: 'PATCH', body: { status } }, `PATCH /projects/{pid}/${segment}/{id}`, deps);
+}
+/**
+ * Read the project's flat element list — `GET /projects/{pid}/sync-state` (smoke
+ * Hallazgo 4). It lists ALL elements (does NOT filter by visibility), so it is the
+ * remote `{ id → (status, points, updatedAt) }` truth the self-healing diffs
+ * against the local SSOT — and the existence pre-check the push uses in place of
+ * the (broken) 409-on-collision signal. Paginated via `page`/`pageSize`; the
+ * caller reads `total` to decide whether more pages are needed.
+ *
+ * @throws {BacklogApiError} on any non-2xx.
+ */
+export async function getSyncState(apiKey, projectId, opts = {}, deps = {}) {
+    const query = new URLSearchParams();
+    if (opts.page !== undefined)
+        query.set('page', String(opts.page));
+    if (opts.pageSize !== undefined)
+        query.set('pageSize', String(opts.pageSize));
+    const suffix = query.toString() ? `?${query.toString()}` : '';
+    const data = await backlogRequest(apiKey, `/projects/${encodeURIComponent(projectId)}/sync-state${suffix}`, { method: 'GET' }, 'GET /projects/{pid}/sync-state', deps);
+    return {
+        items: data?.items ?? [],
+        total: data?.total ?? 0,
+        page: data?.page ?? 1,
+        pageSize: data?.pageSize ?? data?.items?.length ?? 0,
+    };
+}
+/**
+ * List the project's releases — `GET /projects/{pid}/releases`. Feeds the
+ * adopt-by-name flow (releases take NO client-supplied id, so the push matches an
+ * existing release by name before creating one — D12). Tolerates either a bare
+ * `data: [...]` or a `data: { items: [...] }` envelope (same defensive parse
+ * `neon-api.ts` uses for its key list).
+ *
+ * @throws {BacklogApiError} on any non-2xx.
+ */
+export async function listBacklogReleases(apiKey, projectId, deps = {}) {
+    const data = await backlogRequest(apiKey, `/projects/${encodeURIComponent(projectId)}/releases`, { method: 'GET' }, 'GET /projects/{pid}/releases', deps);
+    const list = Array.isArray(data) ? data : (data?.items ?? []);
+    return list
+        .filter((r) => typeof r?.id === 'string')
+        .map((r) => ({ id: r.id, name: (r.name ?? {}) }));
+}
+/**
+ * Create a release — `POST /projects/{pid}/releases` (smoke Hallazgo 5). It takes
+ * no client-supplied `id`; the server mints one and returns it. Returns the new
+ * release id.
+ *
+ * @throws {BacklogApiError} on any non-2xx.
+ */
+export async function createRelease(apiKey, projectId, body, deps = {}) {
+    const data = await backlogRequest(apiKey, `/projects/${encodeURIComponent(projectId)}/releases`, { method: 'POST', body }, 'POST /projects/{pid}/releases', deps);
+    if (!data?.id) {
+        throw new BacklogApiError(201, JSON.stringify(data).slice(0, 500), 'POST /projects/{pid}/releases (respuesta sin id)');
+    }
+    return { id: data.id };
+}
+/**
+ * Assign an element to a release — `POST /releases/{rid}/assignments` (smoke
+ * Hallazgo 5). NOTE this route is RELEASE-scoped, NOT under `/projects/{pid}`.
+ * The mapping rule: assign ONLY epics — features/stories inherit the release, and
+ * assigning a child whose ancestor epic is already assigned 422s `PARENT_MISMATCH`
+ * (tasks/bugs are not releasable at all). Enforcing that rule is the caller's job;
+ * the API accepts `epic`/`feature`/`story` here.
+ *
+ * @throws {BacklogApiError} on any non-2xx.
+ */
+export async function assignToRelease(apiKey, releaseId, elementType, elementId, deps = {}) {
+    await backlogRequest(apiKey, `/releases/${encodeURIComponent(releaseId)}/assignments`, { method: 'POST', body: { elementType, elementId } }, 'POST /releases/{rid}/assignments', deps);
+}
+/**
+ * Read the project's rollup — `GET /projects/{pid}/summary` (smoke Hallazgo 5).
+ * The rollup propagates epic → release and drops `wont_do` from point
+ * denominators. Prefer {@link getSyncState} for heartbeat/reconcile; use this for
+ * a point/progress rollup view.
+ *
+ * @throws {BacklogApiError} on any non-2xx.
+ */
+export async function getSummary(apiKey, projectId, deps = {}) {
+    return backlogRequest(apiKey, `/projects/${encodeURIComponent(projectId)}/summary`, { method: 'GET' }, 'GET /projects/{pid}/summary', deps);
+}