@timekast/factory 1.19.0 → 1.21.0

package/dist/commands/provision.js

@@ -27,9 +27,10 @@ import { FACTORY_ORG } from '../lib/constants.js';
 import { CLIError } from '../lib/cli-error.js';
 import { apexZoneOf, CloudflareApiError, CLOUDFLARE_API_BASE, deleteDnsRecord, ensureCnameRecord, ensureDnsRecord, findCnameRecord, resolveZoneId, resolveZoneIdForName, CNAME_VERCEL_TARGET, TIMEKAST_ZONE_NAME, provisionDomains, } from '../lib/cloudflare-api.js';
 import { createDevelopBranch, createNeonProject, createProjectApiKey, deleteNeonApiKeysByName, deleteNeonProject, getConnectionUri, listNeonBranches, listNeonProjects, NeonApiError, NEON_API_BASE, NEON_DEVELOP_BRANCH, } from '../lib/neon-api.js';
-import { defaultEnvPath, readVercelToken, runProvisionPreflight, } from '../lib/provision-preflight.js';
+import { createBacklogProject, deleteBacklogProject, mintBacklogKey, BacklogApiError, } from '../lib/backlog-api.js';
+import { defaultEnvPath, readEnvKeyNames, readVercelToken, runProvisionPreflight, } from '../lib/provision-preflight.js';
 import { addVercelDomain, buildEnvPlan, createVercelProject, generateAuthSecret, generateMfaEncryptionKey, getLinkedRepoId, getVercelDomainStatus, GitHubAppNotInstalledError, linkGitRepo, listVercelProjects, patchProjectSettings, pushEnvPlan, removeVercelDomain, triggerDeployment, upsertEnvVar, listEnvVars, VercelApiError, writeVercelProjectJson, } from '../lib/vercel-env.js';
-import { writeE2eLocalCreds, writeEmailLocalCreds, writeEnvLocal } from '../lib/env-file.js';
+import { writeBacklogLocalCreds, writeE2eLocalCreds, writeEmailLocalCreds, writeEnvLocal, } from '../lib/env-file.js';
 import { adoptState, ADOPT_UNKNOWN, clearProvisionState, clearState, hasProvisionState, isServiceComplete, PROVISION_DIR, PROVISION_STATE_FILE, readDestroyTarget, readProvisionState, writeProvisionState, } from '../lib/provision-state.js';
 /**
  * The THREE GitHub Secrets the E2E runner (`pnpm test:e2e` → `e2e-runner.ts` +
@@ -103,9 +104,12 @@ export function isValidSubdomainSlug(slug) {
  * The services `--services` understands, in canonical provisioning order. `github`
  * precedes `vercel`: PROV-004 (the `github` step) builds the git substrate AND
  * creates the Vercel PROJECT, whose `projectId` PROV-003 (the `vercel` env-sync
- * step) then consumes. The order is normalized regardless of `--services` input.
+ * step) then consumes. `backlog` (BSYNC-003) runs LAST — after `vercel`/`dns` have
+ * created `.env.local` — so it APPENDS its two keys instead of racing the Neon-string
+ * write (`writeEnvLocal` only creates `.env.local` when absent). The order is
+ * normalized regardless of `--services` input.
  */
-const KNOWN_SERVICES = ['neon', 'github', 'vercel', 'dns'];
+const KNOWN_SERVICES = ['neon', 'github', 'vercel', 'dns', 'backlog'];
 /** The known `--dns` route tokens, for validation. */
 const KNOWN_DNS_ROUTES = ['org', 'cliente-cf', 'registrar'];
 /** Default verification-poll timeout (minutes) and interval (seconds) — issue §4. */
@@ -222,6 +226,7 @@ const SERVICE_LABEL = {
     vercel: 'Vercel (env sync por target)',
     github: 'GitHub + Vercel (sustrato git + proyecto + env + E2E)',
     dns: 'DNS + Resend (dominio del entorno)',
+    backlog: 'Backlog central (proyecto en backlog.timekast.mx + API key)',
 };
 /** Build the ordered plan: each requested service is `skip` if complete, else `create`. */
 function buildPlan(services, state) {
@@ -579,6 +584,163 @@ export async function provisionNeon(rootDir, state, deps = {}) {
             '  La API key project-scoped se creó; reintenta con `--resume` cuando el repo exista.');
     }
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// BSYNC-003 — `backlog`: register the project in backlog.timekast.mx
+// ─────────────────────────────────────────────────────────────────────────────
+/** The rail key holding the org-level backlog `admin` token (create/mint/delete). */
+export const BACKLOG_ADMIN_TOKEN_ENV = 'BACKLOG_ADMIN_TOKEN';
+/**
+ * The backlog-central `internalKey` rule (`^[a-z0-9-]{3,40}$`) — DELIBERATELY DISTINCT
+ * from the DNS subdomain rule of {@link isValidSubdomainSlug} (no leading/trailing
+ * hyphen, ≤59 chars). A backlog internalKey is NOT a DNS label, so it has its own
+ * shape: 3–40 chars of lowercase, digits and hyphens (server-side rule, live-verified
+ * in `project/abraham/smoke-findings.md` Hallazgo 1 — uppercase 422s).
+ */
+export const BACKLOG_SLUG_RE = /^[a-z0-9-]{3,40}$/;
+/**
+ * Normalize + validate a slug as a backlog-central `internalKey` BEFORE any POST
+ * (issue §4/§8). Lowercases first (the server 422s on uppercase), then asserts the
+ * {@link BACKLOG_SLUG_RE} shape. Returns the normalized value so the POST always uses
+ * the canonical form. Distinct from `assertValidSubdomainSlug` (the DNS-label check).
+ *
+ * @throws {CLIError} when the slug cannot be a valid backlog internalKey.
+ */
+export function normalizeBacklogSlug(raw) {
+    const slug = raw.toLowerCase();
+    if (!BACKLOG_SLUG_RE.test(slug)) {
+        throw new CLIError(`El slug \`${raw}\` no es un internalKey válido para backlog central.\n` +
+            'Debe ser 3–40 caracteres de minúsculas, dígitos y guiones (`^[a-z0-9-]{3,40}$`).');
+    }
+    return slug;
+}
+/**
+ * Map a backlog-central REST failure to an actionable, es-MX `CLIError` (issue §4/§8).
+ * The `409 INTERNAL_KEY_TAKEN` hints at `--adopt` WITHOUT auto-adopting (plan decision
+ * H2: silently adopting a colliding project risks mixing two projects by accident). A
+ * 401/403 points at re-importing the rail token; a 422 at the slug shape.
+ */
+function backlogErrorToCliError(error, internalKey, context) {
+    if (error instanceof BacklogApiError) {
+        switch (error.status) {
+            case 401:
+            case 403:
+                return new CLIError(`El \`BACKLOG_ADMIN_TOKEN\` es inválido o no autoriza ${context} (backlog respondió ${error.status}).\n` +
+                    'Renuévalo con `factory secrets <archivo>` y reintenta.');
+            case 409:
+                return new CLIError(`Ya existe un proyecto de backlog central con el internalKey \`${internalKey}\` ` +
+                    '(backlog respondió 409 `INTERNAL_KEY_TAKEN`).\n' +
+                    'NO se auto-adopta (evita mezclar dos proyectos por accidente). Si es tu proyecto, ' +
+                    'reconstruye el estado con `--adopt`; si no, elige otro con `--slug`.');
+            case 422:
+                return new CLIError(`Backlog central rechazó el internalKey \`${internalKey}\` como inválido (respondió 422).\n` +
+                    'Usa un slug de 3–40 caracteres de minúsculas, dígitos y guiones.');
+            default:
+                return new CLIError(`Falló la llamada a backlog central en ${context}: ${error.message}`);
+        }
+    }
+    return new CLIError(`Falló la llamada a backlog central en ${context}: ${error?.message ?? 'error'}`);
+}
+/**
+ * BSYNC-003 — provision the backlog-central project: normalize the slug, create the
+ * project (`POST /projects`, org `admin` token), mint a per-project `read_write` key
+ * (`POST /projects/{pid}/keys`), and write BOTH the key + the project id to
+ * `.env.local` (`BACKLOG_API_KEY` + `BACKLOG_PROJECT_ID`, PROVISION_OWNED → never
+ * pushed to Vercel). State records IDs ONLY (`{ projectId, keyMinted }`) — the
+ * SHOW-ONCE key value is NEVER persisted anywhere but the gitignored `.env.local`.
+ *
+ * Auth split (smoke Hallazgo 1): the org `admin` token drives ONLY the two org
+ * endpoints here (create project + mint key); the minted `read_write` key is what the
+ * derivative's `backlog push`/`sync` later consume. The project id is persisted
+ * IMMEDIATELY after create, so a mint failure leaves a resumable partial state.
+ *
+ * No-echo: the minted key value never reaches stdout/log — only key NAMES are printed.
+ *
+ * @throws {CLIError} on a missing rail token, an invalid slug (before any POST), a
+ *   `409 INTERNAL_KEY_TAKEN` (hint: `--adopt`, no auto-adopt), or any backlog failure.
+ */
+export async function provisionBacklog(rootDir, state, deps = {}) {
+    // Fully complete only when the key was minted + written. Re-entering a partial run
+    // (project created, key not yet minted) finishes the mint WITHOUT re-creating.
+    if (state.backlog?.keyMinted)
+        return;
+    const envPath = deps.envPath ?? defaultEnvPath();
+    const adminToken = readGateValue(BACKLOG_ADMIN_TOKEN_ENV, envPath);
+    if (!adminToken) {
+        throw new CLIError('No se pudo leer `BACKLOG_ADMIN_TOKEN` de `~/.claude/.env`.\n' +
+            'Ejecuta `factory secrets <archivo>` para bajar el token del archivo de secretos y reintenta.');
+    }
+    // Normalize + validate the slug against the backlog rule BEFORE any POST (§4/§8).
+    const internalKey = normalizeBacklogSlug(state.projectName);
+    const apiDeps = { fetchImpl: deps.fetchImpl, sleepImpl: deps.sleepImpl };
+    // 1. Create the project (reuse a partial run's projectId; else POST). Persist the id
+    //    IMMEDIATELY so a mint failure leaves a resumable partial state (IDs only).
+    let projectId;
+    if (state.backlog?.projectId) {
+        projectId = state.backlog.projectId;
+    }
+    else {
+        let project;
+        try {
+            project = await createBacklogProject(adminToken, { name: state.projectName, internalKey }, apiDeps);
+        }
+        catch (error) {
+            throw backlogErrorToCliError(error, internalKey, 'crear el proyecto');
+        }
+        projectId = project.id;
+        state.backlog = { projectId };
+        writeProvisionState(rootDir, state);
+    }
+    // 2. Mint the per-project `read_write` key (SHOW-ONCE). Its VALUE goes straight to
+    //    `.env.local`; it is NEVER persisted in the state nor printed (no-echo).
+    let apiKey;
+    try {
+        apiKey = await mintBacklogKey(adminToken, projectId, `${state.projectName}-provision`, apiDeps);
+    }
+    catch (error) {
+        throw backlogErrorToCliError(error, internalKey, 'mintar la API key del proyecto');
+    }
+    // 3. Write BACKLOG_API_KEY + BACKLOG_PROJECT_ID to `.env.local` (0600, PROVISION_OWNED).
+    //    writeBacklogLocalCreds CREATES `.env.local` when absent (a standalone `backlog`
+    //    run has no Neon/Vercel step to seed it). No-echo: print only KEY NAMES.
+    if (writeBacklogLocalCreds(rootDir, projectId, apiKey)) {
+        console.log('  ＋ .env.local (BACKLOG_API_KEY · BACKLOG_PROJECT_ID — registro en backlog.timekast.mx)');
+    }
+    else {
+        console.warn('⚠ No se pudieron escribir las credenciales de backlog en `.env.local`. ' +
+            'El proyecto se creó; agrégalas a mano (la key es show-once, revísala en la app).');
+    }
+    // 4. Mark done — key minted + written. State holds IDs only (never the key value).
+    state.backlog = { projectId, keyMinted: true };
+    writeProvisionState(rootDir, state);
+}
+/**
+ * Resolve whether the `backlog` service can run given the rail token. UNLIKE the
+ * fail-closed rail tokens (Neon/Vercel abort when missing), a missing
+ * `BACKLOG_ADMIN_TOKEN` degrades GRACEFULLY (issue AC): a WARN + skip when `backlog`
+ * is ONE of several requested services (the rest continue), but a hard error when it
+ * is the SOLE service requested (there'd be nothing to do). Returns the services to
+ * actually run — `backlog` stripped when skipped. Pure + FS-light: `envPath` is
+ * explicit so the unit test drives every branch against a temp rail.
+ *
+ * Runs BEFORE the preflight, so a stripped `backlog` never reaches
+ * `assertGateTokensPresent` (which would otherwise fail-close on the missing token).
+ *
+ * @throws {CLIError} when `backlog` is the sole requested service and the token is absent.
+ */
+export function resolveBacklogService(services, envPath = defaultEnvPath()) {
+    if (!services.includes('backlog'))
+        return services;
+    if (readEnvKeyNames(envPath).has(BACKLOG_ADMIN_TOKEN_ENV))
+        return services;
+    if (services.length === 1) {
+        throw new CLIError('Falta `BACKLOG_ADMIN_TOKEN` en `~/.claude/.env` y `backlog` es el único servicio pedido.\n' +
+            'Impórtalo con `factory secrets <archivo>` (el master del org) y reintenta.');
+    }
+    console.warn('⚠ Falta `BACKLOG_ADMIN_TOKEN` en `~/.claude/.env` — omito el servicio `backlog` ' +
+        '(los demás continúan).\n' +
+        '  Impórtalo con `factory secrets <archivo>` para registrar el proyecto en backlog.timekast.mx.');
+    return services.filter((s) => s !== 'backlog');
+}
 /**
  * Resolve the four pooled+direct Neon connection strings, ALWAYS by re-deriving
  * fresh from Neon — provision persists NO credentials file (Neon is the source of
@@ -2038,6 +2200,12 @@ async function runServiceStep(service, rootDir, state, flags) {
             // (RESEND_API_KEY + the fixed EMAIL_FROM), then `state.dns = { domain, devDomain }`.
             await provisionDns(rootDir, state, flags.team);
             break;
+        case 'backlog':
+            // BSYNC-003: register the project in backlog.timekast.mx (POST /projects with the
+            // org admin token) + mint a per-project read_write key + write BACKLOG_API_KEY /
+            // BACKLOG_PROJECT_ID to `.env.local` (PROVISION_OWNED — never to Vercel).
+            await provisionBacklog(rootDir, state, {});
+            break;
         default:
             throw new CLIError(`Paso de provision no implementado: \`${service}\`.`);
     }
@@ -2361,6 +2529,10 @@ function describeDestroyPlan(target) {
     if (target.githubRepo) {
         lines.push(`  － Repo GitHub ${target.githubRepo} — \`gh repo delete\` (sesión del dev)`);
     }
+    if (target.backlogProjectId) {
+        lines.push(`  － Proyecto backlog central ${target.backlogProjectId} — DELETE /projects ` +
+            '(soft-delete, `BACKLOG_ADMIN_TOKEN` del rail)');
+    }
     if (lines.length === 0) {
         lines.push('  (No hay recursos registrados que destruir — el estado no tiene ids.)');
     }
@@ -2547,6 +2719,38 @@ async function destroyGithubRepo(target, runGh) {
         return { resource, status: 'failed', detail: message || 'error en `gh repo delete`' };
     }
 }
+/**
+ * Soft-delete the backlog-central project via `DELETE /projects/{pid}` (BSYNC-003).
+ * INTENTIONALLY DIFFERENT from the other providers' teardown: those hard-delete with
+ * the DEV's own session (`gh`/`vercel`) — backlog has no such per-dev session, so it
+ * reuses the rail's `BACKLOG_ADMIN_TOKEN` (the smoke confirmed the admin token DELETEs
+ * a project). The delete is a SOFT delete (deactivates, no cascade) and IDEMPOTENT: a
+ * repeat returns 200, and a 404 (already gone) is treated as "already clean" — same
+ * 404-tolerance principle as {@link destroyNeonProject} (issue §8).
+ */
+async function destroyBacklogProject(target, adminToken, deps) {
+    const resource = `Proyecto backlog central (${target.backlogProjectId})`;
+    if (!target.backlogProjectId) {
+        return {
+            resource: 'Proyecto backlog central',
+            status: 'skipped',
+            detail: 'sin id en el estado',
+        };
+    }
+    try {
+        await deleteBacklogProject(adminToken, target.backlogProjectId, deps);
+        return { resource, status: 'removed', detail: 'desactivado (soft-delete idempotente)' };
+    }
+    catch (error) {
+        if (error instanceof BacklogApiError && error.status === 404) {
+            return { resource, status: 'removed', detail: 'ya estaba desactivado (404)' };
+        }
+        const detail = error instanceof BacklogApiError
+            ? `backlog respondió ${error.status}`
+            : (error?.message ?? 'error de red');
+        return { resource, status: 'failed', detail };
+    }
+}
 /**
  * Orchestrate the per-provider teardown (issue §4 + §8). Each provider failure is
  * logged and the run CONTINUES with the others; the outcomes are collected so the
@@ -2649,6 +2853,24 @@ async function teardownProviders(target, deps) {
     if (target.githubRepo) {
         outcomes.push(await destroyGithubRepo(target, deps.runGh));
     }
+    // 5. Backlog central — soft-delete the project via `DELETE /projects` with the rail's
+    //    `BACKLOG_ADMIN_TOKEN`. UNLIKE the providers above (deleted with the dev's own
+    //    session), backlog only HAS the org admin token — create+delete-capable per the
+    //    smoke — so the teardown reuses it. A missing token is a `failed` (keeps the
+    //    state + flags the orphan), never a silent skip. Soft + idempotent (404 → gone).
+    if (target.backlogProjectId) {
+        const backlogToken = readGateValue(BACKLOG_ADMIN_TOKEN_ENV, deps.envPath);
+        if (!backlogToken) {
+            outcomes.push({
+                resource: `Proyecto backlog central (${target.backlogProjectId})`,
+                status: 'failed',
+                detail: 'sin `BACKLOG_ADMIN_TOKEN` en el rail — desactívalo a mano en la app',
+            });
+        }
+        else {
+            outcomes.push(await destroyBacklogProject(target, backlogToken, { fetchImpl: deps.fetchImpl }));
+        }
+    }
     return outcomes;
 }
 /** Print the per-provider teardown report (es-MX) and flag the not-removed ones. */
@@ -2786,6 +3008,12 @@ export async function runProvision(flags) {
     // with no `--services` (a deferred go-live over an existing provision) or
     // alongside the initial run. It always runs AFTER the service steps.
     const hasDomain = Boolean(flags.domain);
+    // Backlog token gate (BSYNC-003): degrade gracefully vs the fail-closed rail tokens.
+    // A missing `BACKLOG_ADMIN_TOKEN` strips `backlog` (WARN) when it is one of several
+    // services, or throws when it is the only one — BEFORE the preflight so the stripped
+    // service never reaches the fail-closed `assertGateTokensPresent`. Reads the rail for
+    // presence only (no mutation) → safe to run ahead of the `--dry-run` return too.
+    flags.services = resolveBacklogService(flags.services);
     // 1. Flag validation.
     if (flags.services.length === 0 && !hasDomain) {
         throw new CLIError('No seleccionaste servicios. Usa `--services=neon,vercel,github,dns` ' +

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';
@@ -333,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. ' +

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)
@@ -82,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)
@@ -118,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
@@ -221,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

@@ -23,24 +23,44 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from './cli-error.js';
-import { CLAUDE_MD_FILE, TIMEKAST_DIR } from './constants.js';
+import { CLAUDE_MD_FILE, TIMEKAST_DIR, VITEST_SETUP_FILE } 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/'];
+/**
+ * Directory 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/'];
+/**
+ * Repo-root FILES a manifest path may be (the non-directory half of `track`).
+ *
+ * Matched EXACTLY, never by prefix. Folding these into `ALLOWED_ROOTS` would be the
+ * short spelling, but `startsWith('vitest.setup.ts')` also accepts
+ * `vitest.setup.ts.evil` — the same widening `.github/workflows/` exists to avoid. A
+ * root file is a single path, so exact equality is what the track actually says.
+ */
+const ALLOWED_FILES = [CLAUDE_MD_FILE, VITEST_SETUP_FILE];
+/** Human-readable rendering of the tracked scope, for the error message. */
+const TRACKED_SCOPE_LABEL = [...ALLOWED_ROOTS, ...ALLOWED_FILES]
+    .map((entry) => `\`${entry}\``)
+    .join(', ');
 /**
  * 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/**`, `vitest.setup.ts`). 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(/[\\/]/);
     if (rel.length === 0 || path.isAbsolute(rel) || segments.includes('..')) {
         throw new CLIError(`El manifest declara un path inseguro \`${rel}\` (absoluto o con \`..\`); no se tocó nada.`);
     }
-    const tracked = rel === CLAUDE_MD_FILE || ALLOWED_ROOTS.some((root) => rel.startsWith(root));
+    const tracked = ALLOWED_FILES.includes(rel) || 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 (${TRACKED_SCOPE_LABEL}). ` +
             'El release está mal construido; no se tocó nada.');
     }
 }