@timekast/factory 1.25.0 → 1.27.0

package/dist/commands/ticket.js

@@ -0,0 +1,487 @@
+/**
+ * `factory ticket push <archivo>` — the derivative → Factory channel.
+ *
+ * A derivative documents a kit defect as a markdown file under `project/factory/`
+ * (the `fx-factory-tickets` convention). Until now that file was a dead end: it sat
+ * in the repo until somebody opened the Factory by hand. This command delivers it as
+ * a GitHub issue in the Factory repo and stamps the resulting URL back into the
+ * ticket's canonical `**GitHub issue:**` slot.
+ *
+ * THREE THINGS THIS COMMAND DELIBERATELY DOES NOT DO:
+ *
+ *   1. It never CREATES the `kit-drift` label — only applies it. Creating a label
+ *      requires `write` on the repo; applying one requires `triage`. Creating it
+ *      would break the command for exactly the population that only has `triage`.
+ *      A missing label degrades to a warning + a retry without it, never a failure.
+ *   2. It never spawns a shell. Every one of the CLI's `execa` calls is
+ *      `execa(file, [args])` with no `shell: true`; a `... || true` would break that
+ *      invariant and make the path and the body injectable. Tolerance comes from
+ *      `{ reject: false }` and reading `exitCode`, not from shell syntax.
+ *   3. It never publishes without a gate, and it never prints the body. The ticket
+ *      lands in a repo the whole org reads, so publishing asks first: `--dry-run`
+ *      shows the destination and the derived title, and an interactive confirmation
+ *      (fail-closed when headless) precedes the create. Keeping the body off the
+ *      screen is not a secret heuristic — it is the observation that the file is in
+ *      the caller's own repo and the published body is byte-identical to it, so
+ *      opening the file IS reviewing what would be published.
+ *
+ * The body travels over STDIN (`--body-file -` + `{ input }`), the same discipline
+ * as `gh secret set` in `provision.ts`: it never lands in argv (visible in the
+ * process table of the multi-tenant Agent Server) and never hits the argv limit.
+ *
+ * CREDENTIALS: none new. The command reuses the developer's own `gh` session via
+ * the shared `runPreflight` (gh installed → authenticated → org member). A failed
+ * preflight degrades to a note + `exit 0` — the same `not-configured` contract
+ * `factory backlog push` has without `BACKLOG_API_KEY`, never a stack trace.
+ */
+import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { execa } from 'execa';
+import prompts from 'prompts';
+import { CLIError, PreflightError } from '../lib/cli-error.js';
+import { FACTORY_REPO, FACTORY_TICKET_ASSIGNEE, FACTORY_TICKET_DIR, FACTORY_TICKET_LABEL, GITHUB_ISSUE_BODY_MAX, GITHUB_ISSUE_TITLE_MAX, } from '../lib/constants.js';
+import { runPreflight } from '../lib/preflight.js';
+import { detectRepo } from '../lib/repo-detection.js';
+/**
+ * Flags of `ticket push` that take a VALUE. Their following token belongs to the
+ * flag, so it can never be read as the ticket path (`--label kit-drift ticket.md`
+ * used to resolve the "file" to `kit-drift` and die with "no se encontró el archivo").
+ */
+const VALUE_FLAGS = new Set(['--assignee', '--label']);
+/** Read `--name value` / `--name=value`; a following flag is NOT a value. */
+function readFlagValue(argv, name) {
+    const inline = argv.find((arg) => arg.startsWith(`--${name}=`));
+    if (inline)
+        return inline.slice(name.length + 3) || undefined;
+    const idx = argv.indexOf(`--${name}`);
+    if (idx < 0)
+        return undefined;
+    const next = argv[idx + 1];
+    return next && !next.startsWith('-') ? next : undefined;
+}
+/**
+ * First positional argument: the first token that is neither a flag NOR the value of
+ * a value-taking flag ({@link VALUE_FLAGS}). Same discipline as {@link readFlagValue},
+ * read from the other side.
+ */
+export function firstPositional(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg.startsWith('-')) {
+            const next = argv[i + 1];
+            if (VALUE_FLAGS.has(arg) && next !== undefined && !next.startsWith('-'))
+                i += 1;
+            continue;
+        }
+        return arg;
+    }
+    return undefined;
+}
+export function parseTicketPushFlags(argv) {
+    return {
+        dryRun: argv.includes('--dry-run'),
+        yes: argv.includes('--yes') || argv.includes('-y'),
+        assignee: readFlagValue(argv, 'assignee') ?? FACTORY_TICKET_ASSIGNEE,
+        label: readFlagValue(argv, 'label') ?? FACTORY_TICKET_LABEL,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Path containment
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Resolve `filePath` to a real, regular file CONTAINED in `project/factory/`.
+ *
+ * The containment is `realpath` + `path.relative`, NOT a string prefix, and that
+ * is the whole point of this function:
+ *
+ *   - `startsWith('project/factory')` accepts `project/factory-backup/…`.
+ *   - git versions symlinks, so a file with a perfectly legitimate ticket name can
+ *     point at `~/.claude/.env` — the org rail (VERCEL_TOKEN, NEON_API_KEY,
+ *     CLOUDFLARE_API_TOKEN, RESEND_API_KEY, BACKLOG_ADMIN_TOKEN). Publishing that
+ *     to a shared repo is the failure this guard exists to prevent.
+ *
+ * Unlike `assertSafeTrackedPath` (whose input is a release manifest), this input
+ * comes from the user AND the file gets opened and published — string checks do
+ * not cut it.
+ *
+ * @throws {CLIError} outside the tickets dir, missing, or not a regular file.
+ */
+export function resolveTicketPath(rootDir, filePath) {
+    const ticketsRoot = path.join(rootDir, ...FACTORY_TICKET_DIR.split('/'));
+    if (!existsSync(ticketsRoot)) {
+        throw new CLIError(`No existe \`${FACTORY_TICKET_DIR}/\` en \`${rootDir}\`.\n` +
+            'Un factory-ticket vive ahí (convención `fx-factory-tickets`); no hay nada que entregar.');
+    }
+    // A relative path is resolved against the CWD first (what a dev types after a
+    // tab-completion in a subdirectory) and against the repo root second (the
+    // canonical repo-relative form the docs use). Both must survive containment.
+    const candidates = path.isAbsolute(filePath)
+        ? [filePath]
+        : [path.resolve(process.cwd(), filePath), path.resolve(rootDir, filePath)];
+    const found = candidates.find((candidate) => existsSync(candidate));
+    if (!found) {
+        throw new CLIError(`No se encontró el archivo \`${filePath}\`.\n` +
+            `Pasa la ruta de un ticket bajo \`${FACTORY_TICKET_DIR}/\`.`);
+    }
+    let realRepo;
+    let realRoot;
+    let realTarget;
+    try {
+        realRepo = realpathSync(rootDir);
+        realRoot = realpathSync(ticketsRoot);
+        realTarget = realpathSync(found);
+    }
+    catch {
+        throw new CLIError(`No se pudo resolver \`${filePath}\` (¿un enlace roto?). No se entregó nada.`);
+    }
+    // The ANCHOR of the containment must itself be inside the repo. `project/factory`
+    // can BE a symlink — git versions symlinks with their target and materialises them
+    // on checkout — and anchoring the fence on its target moves the fence: with
+    // `project/factory -> ~/.claude`, everything under the org rail's directory would
+    // resolve as "contained" and become publishable. Checked before the file's own
+    // containment, because a compromised root makes that check meaningless.
+    // `rootRel === ''` counts as an escape, symmetrically with the file check below: an empty
+    // relative path means the tickets root resolved to the REPO itself, which widens the fence
+    // from `project/factory/` to the whole checkout — gitignored files included. Two versioned
+    // symlinks (`project/factory -> ..` and `ticket.md -> .env.local`) reach `.env.local` that way.
+    const rootRel = path.relative(realRepo, realRoot);
+    if (rootRel === '' || path.isAbsolute(rootRel) || rootRel.split(/[\\/]/)[0] === '..') {
+        throw new CLIError(`\`${FACTORY_TICKET_DIR}/\` sale del árbol del repo: se resolvió a \`${realRoot}\`, ` +
+            `fuera de \`${realRepo}\`.\n` +
+            'La contención se ancla en el repo, así que un directorio de tickets que apunta afuera se ' +
+            'rechaza entero — no se entregó nada.');
+    }
+    const rel = path.relative(realRoot, realTarget);
+    const escapes = rel === '' || path.isAbsolute(rel) || rel.split(/[\\/]/)[0] === '..';
+    if (escapes) {
+        throw new CLIError(`\`${filePath}\` no está dentro de \`${FACTORY_TICKET_DIR}/\` — se resolvió a \`${realTarget}\`.\n` +
+            'Solo se entrega un archivo real contenido en ese directorio (los enlaces que salen del árbol se rechazan).');
+    }
+    if (!statSync(realTarget).isFile()) {
+        throw new CLIError(`\`${filePath}\` no es un archivo regular; no hay ticket que entregar.`);
+    }
+    return realTarget;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Stamping (`fx-factory-tickets §6.2`)
+// ─────────────────────────────────────────────────────────────────────────────
+/** Canonical header field the delivered URL is stamped into. It is the ONLY field a tool writes. */
+const GITHUB_ISSUE_FIELD = '**GitHub issue:**';
+const ESTADO_FIELD = '**Estado:**';
+/**
+ * Write `url` into the ticket's `**GitHub issue:**` slot, which is born holding an
+ * em-dash and sits immediately after `**Estado:**`. Stamping the URL does NOT touch
+ * `Estado` — delivering is not triaging (`fx-factory-tickets §6.2`).
+ *
+ * A ticket written before the convention has no such field; it is inserted right
+ * after `Estado` rather than dropped, so the ticket stops being a dead end either
+ * way. With no header block at all, nothing is changed and the caller warns.
+ */
+export function stampGitHubIssueUrl(content, url) {
+    const stamped = `${GITHUB_ISSUE_FIELD} ${url}`;
+    const lines = content.split('\n');
+    const fieldIdx = lines.findIndex((line) => line.startsWith(GITHUB_ISSUE_FIELD));
+    if (fieldIdx >= 0) {
+        lines[fieldIdx] = stamped;
+        return { content: lines.join('\n'), changed: true };
+    }
+    const estadoIdx = lines.findIndex((line) => line.startsWith(ESTADO_FIELD));
+    if (estadoIdx >= 0) {
+        lines.splice(estadoIdx + 1, 0, stamped);
+        return { content: lines.join('\n'), changed: true };
+    }
+    return { content, changed: false };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Terminal safety
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Every C0/C1 control character EXCEPT `\n` and `\t` — the ones a terminal ACTS on
+ * instead of printing (`\x1b` starts a CSI sequence, `\x0d` returns the carriage,
+ * `\x9b` is CSI on its own).
+ */
+const CONTROL_CHARS = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+/**
+ * Render untrusted ticket text for a HUMAN to read, with every terminal control
+ * character shown as its own escape (`\x1b` prints as the four characters `\x1b`).
+ *
+ * WHAT THIS GUARDS. `--dry-run` prints the DERIVED TITLE, and that title is built from
+ * the ticket's H1 ({@link buildIssueTitle}) — a line of a file whose whole purpose is to
+ * carry pasted command output. Unescaped, it drives the terminal instead of appearing in
+ * it: `\x1b[nA` (cursor up) overwrites the destination, assignee and label printed just
+ * above it, and `\x1b[8m` (conceal) hides part of itself from the reviewer's eye. The
+ * printed preview IS the gate, so anything that can rewrite the preview defeats it.
+ *
+ * 🔴 ESCAPED, NOT STRIPPED. Sanitising would break the other promise — that what you
+ * approve is byte-for-byte what gets published. The PUBLISHED title is untouched: this
+ * only changes its representation on screen.
+ */
+export function escapeControlChars(text) {
+    return text.replace(CONTROL_CHARS, (char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Issue creation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Title of the delivered issue: the ticket's H1 plus its filename. The H1 alone is
+ * generic by convention (`# Factory Ticket — sk-drift`), so a queue of them would be
+ * unreadable; the filename carries the project, the date and the counter.
+ */
+export function buildIssueTitle(body, filePath) {
+    const basename = path.basename(filePath);
+    const heading = body.split('\n').find((line) => line.startsWith('# '));
+    const title = heading ? `${heading.slice(2).trim()} (${basename})` : basename;
+    if (title.length <= GITHUB_ISSUE_TITLE_MAX)
+        return title;
+    // Same class of input as the body (hand-written, unbounded), so the same treatment:
+    // capped here with the truncation VISIBLE, instead of a raw 422 from the API. The
+    // ellipsis eats one character so the result never exceeds the cap.
+    return `${title.slice(0, GITHUB_ISSUE_TITLE_MAX - 1).trimEnd()}…`;
+}
+/**
+ * `gh` rejected the ASSIGNEE (a renamed login, somebody who left the org) — recoverable.
+ * Symmetric to {@link isMissingLabel}: the assignee is a login hardcoded in a CLI
+ * published to the whole fleet, so a single change outside this repo would otherwise
+ * break the channel for every derivative at once.
+ */
+function isRejectedAssignee(stderr) {
+    return (/assign/i.test(stderr) &&
+        /(not found|could not|no existe|does not exist|invalid|unable)/i.test(stderr));
+}
+/** `gh` rejected the label itself (it does not exist in the repo) — recoverable. */
+function isMissingLabel(stderr) {
+    return (/label/i.test(stderr) && /(not found|could not add|no existe|does not exist)/i.test(stderr));
+}
+/** First issue URL printed by `gh issue create`. */
+function extractIssueUrl(stdout) {
+    return /https:\/\/\S*\/issues\/\d+/.exec(stdout)?.[0];
+}
+/** Default confirmation — `prompts`, defaulting to NO (a publish is not undoable). */
+async function defaultConfirm(message) {
+    const { proceed } = await prompts({
+        type: 'confirm',
+        name: 'proceed',
+        message,
+        initial: false,
+    });
+    return proceed === true;
+}
+/**
+ * Deliver one factory-ticket to the Factory repo as a GitHub issue.
+ *
+ * Order matters and is asserted by the unit test: containment → read → size →
+ * (`--dry-run` stops here) → gh session → publish gate → create → verify
+ * assignee/label → stamp. Every guard that can reject runs BEFORE `gh` is ever
+ * spawned.
+ */
+export async function runTicketPush(filePath, flags = parseTicketPushFlags([]), rootDir = detectRepo(process.cwd()).repoRoot ?? process.cwd(), deps = {}) {
+    const target = resolveTicketPath(rootDir, filePath);
+    const body = readFileSync(target, 'utf8');
+    const shown = path.relative(rootDir, target) || path.basename(target);
+    if (body.trim().length === 0) {
+        throw new CLIError(`El ticket \`${shown}\` está vacío; no hay nada que entregar.`);
+    }
+    if (body.length > GITHUB_ISSUE_BODY_MAX) {
+        throw new CLIError(`El ticket \`${shown}\` mide ${body.length.toLocaleString('es-MX')} caracteres y GitHub ` +
+            `topa el cuerpo de un issue en ${GITHUB_ISSUE_BODY_MAX.toLocaleString('es-MX')}.\n` +
+            'Recorta el `## Context snippet (optional)` (o divide el hallazgo en dos tickets) y vuelve a intentar.');
+    }
+    const title = buildIssueTitle(body, target);
+    const isTTY = deps.isTTY ?? Boolean(process.stdout.isTTY);
+    const confirm = deps.confirm ?? defaultConfirm;
+    // 1. `--dry-run` — print what would be published, mutate nothing. What reaches the screen
+    //    is the DESTINATION and the derived title, never file content; the title is escaped so
+    //    it cannot drive the terminal. What gets published is `body`, untouched.
+    if (flags.dryRun) {
+        console.log(`\n📋 Entrega simulada (\`--dry-run\`) de \`${shown}\`:\n`);
+        console.log(`   Repo destino : ${FACTORY_REPO}`);
+        console.log(`   Asignado     : ${flags.assignee}`);
+        console.log(`   Etiqueta     : ${flags.label}`);
+        // Escaped: the title is BUILT from the H1 of the ticket, so it carries the same untrusted
+        // bytes as any other line of it (see `escapeControlChars`).
+        console.log(`   Título       : ${escapeControlChars(title)}`);
+        console.log(`   Cuerpo       : ${body.split('\n').length} líneas — ábrelo en \`${shown}\``);
+        // 🔴 THE BODY IS NEVER PRINTED, and there is no flag that prints it.
+        //
+        // Not a mitigation — a dissolved question. Why print the body at all? It is a file in the
+        // user's own repo: they can open it, and since the published body is byte-identical,
+        // opening the file IS seeing what would be published. What this command uniquely knows is
+        // what the user cannot see alone: the destination, the assignee, the label and the derived
+        // title. Printing those and nothing else means no file content reaches the screen at all.
+        //
+        // No `--show-body` escape hatch, deliberately: the caller most likely to run `--dry-run` is
+        // an agent checking before publishing, its output lands in a transcript nobody can purge,
+        // and a flag is exactly what an agent would pass.
+        console.log('\nNo se creó ningún issue (`--dry-run`). El cuerpo no se imprime — ábrelo tú.');
+        return;
+    }
+    // 2. gh session. A failed preflight is `not-configured`, NOT an error: note + exit 0.
+    try {
+        await (deps.preflight ?? runPreflight)();
+    }
+    catch (error) {
+        if (error instanceof PreflightError) {
+            console.log(`ℹ️  Entrega omitida: ${error.message}`);
+            console.log('   El ticket sigue en tu repo, intacto. Este comando usa tu propia sesión de `gh` — ' +
+                'no hay ningún token que configurar.');
+            return;
+        }
+        throw error;
+    }
+    // 3. Publish gate. The body lands in a repo the whole org can read, so it never goes out
+    //    unasked: headless without `--yes` is fail-closed, a TTY is asked, `--yes` is the answer
+    //    given in advance.
+    if (!flags.yes) {
+        if (!isTTY) {
+            throw new CLIError(`No se publica sin confirmación: \`${shown}\` se publicaría íntegro en ${FACTORY_REPO}.\n` +
+                'Revisa el contenido con `--dry-run` y, si es correcto, vuelve a correr con `--yes`.');
+        }
+        const proceed = await confirm(`¿Crear el issue en ${FACTORY_REPO} con el contenido de \`${shown}\`?`);
+        if (!proceed) {
+            console.log('Cancelado. No se creó ningún issue.');
+            return;
+        }
+    }
+    // 4. Create the issue. Body over STDIN; label applied, never created.
+    //
+    //    TWO RUNGS OF DEGRADATION, and they are symmetric on purpose. Both the label and
+    //    the assignee are values this CLI hardcodes for the WHOLE fleet, so both can be
+    //    invalidated by a single change outside this repo (a deleted label, a renamed
+    //    login, somebody leaving the org). Neither may turn the channel into a dead end:
+    //    a rejected one degrades to a retry without it plus a warning, never a failure.
+    const coreArgs = [
+        'issue',
+        'create',
+        '--repo',
+        FACTORY_REPO,
+        '--title',
+        title,
+        '--body-file',
+        '-',
+    ];
+    let labelDropped = false;
+    let assigneeDropped = false;
+    const create = () => execa('gh', [
+        ...coreArgs,
+        ...(assigneeDropped ? [] : ['--assignee', flags.assignee]),
+        ...(labelDropped ? [] : ['--label', flags.label]),
+    ], { input: body, reject: false });
+    let result = await create();
+    if (result.exitCode !== 0 && isMissingLabel(String(result.stderr ?? ''))) {
+        labelDropped = true;
+        result = await create();
+    }
+    if (result.exitCode !== 0 && isRejectedAssignee(String(result.stderr ?? ''))) {
+        assigneeDropped = true;
+        result = await create();
+    }
+    if (result.exitCode !== 0) {
+        throw new CLIError(`\`gh issue create\` falló (código ${result.exitCode}) y no se reintenta a ciegas.\n` +
+            `${String(result.stderr ?? '').trim()}\n` +
+            `Si el asignado del canal ya no es válido (login renombrado, o alguien que salió del org), ` +
+            `pasa uno con \`--assignee <login>\`.\n` +
+            `El ticket \`${shown}\` quedó intacto; ningún issue se creó a medias.`);
+    }
+    const stdout = String(result.stdout ?? '');
+    const url = extractIssueUrl(stdout);
+    if (!url) {
+        console.log(`✅ Issue creado en ${FACTORY_REPO}.`);
+        console.log(stdout.trim());
+        console.warn('⚠️  No se pudo leer la URL de la salida de `gh`, así que el ticket local no se estampó. ' +
+            'Copia la URL de arriba al campo `**GitHub issue:**`.');
+        return;
+    }
+    console.log(`✅ Issue creado: ${url}`);
+    if (assigneeDropped) {
+        console.warn(`⚠️  ${FACTORY_REPO} rechazó al asignado \`${flags.assignee}\`; el issue se creó SIN asignado.\n` +
+            '   El canal quedó sin ruta de aviso al maintainer: avísale a mano, y corre la próxima ' +
+            'entrega con `--assignee <login>` (o pide que se actualice el default del CLI).');
+    }
+    if (labelDropped) {
+        console.warn(`⚠️  La etiqueta \`${flags.label}\` no existe en ${FACTORY_REPO}; el issue se creó sin ella.\n` +
+            `   Un maintainer la crea una vez (\`gh label create ${flags.label} -R ${FACTORY_REPO}\`) y las ` +
+            'siguientes entregas la aplican solas.');
+    }
+    // 5. Verify the effect of assignee + label instead of assuming it. GitHub DROPS
+    //    both SILENTLY when the author lacks `triage` on the repo, and the org's base
+    //    permission is `read` — so the two notification mechanisms of this channel can
+    //    fail at once, without a word, unless we look.
+    await verifyIssueFields(url, flags, labelDropped, assigneeDropped);
+    // 6. Stamp the URL back. If this fails, the URL is already on screen (step above):
+    //    never leave the dev without the URL of an issue that already exists.
+    const stamp = stampGitHubIssueUrl(body, url);
+    if (!stamp.changed) {
+        console.warn(`⚠️  \`${shown}\` no tiene el campo \`${GITHUB_ISSUE_FIELD}\` ni \`${ESTADO_FIELD}\`, así que no se estampó. ` +
+            'Agrega la URL a mano (`fx-factory-tickets §6.2`).');
+        return;
+    }
+    try {
+        (deps.writeFile ?? ((p, c) => writeFileSync(p, c, 'utf8')))(target, stamp.content);
+        console.log(`   URL estampada en \`${shown}\` (el \`Estado\` no cambia: entregar no es triar).`);
+    }
+    catch (error) {
+        console.warn(`⚠️  El issue existe (${url}) pero \`${shown}\` no se pudo actualizar: ` +
+            `${error instanceof Error ? error.message : String(error)}\n` +
+            `   Copia la URL al campo \`${GITHUB_ISSUE_FIELD}\` a mano.`);
+    }
+}
+/**
+ * `factory ticket <sub> [...]` — the whole dispatch of the command, HERE and not in
+ * `index.ts`, so the three branches (`push`, a missing file, an unknown sub-command)
+ * are reachable from a test. The entrypoint only routes `case 'ticket'` to this.
+ */
+export async function runTicketCommand(args) {
+    const sub = args[0];
+    // `factory ticket push <archivo>` — deliver a factory-ticket from `project/factory/`
+    // to the Factory repo as a GitHub issue (EXTPT-003).
+    if (sub === 'push') {
+        const rest = args.slice(1);
+        const file = firstPositional(rest);
+        if (!file) {
+            throw new CLIError('Falta el archivo del ticket. Uso: `factory ticket push <archivo>` ' +
+                '(una ruta bajo `project/factory/`).');
+        }
+        await runTicketPush(file, parseTicketPushFlags(rest));
+        return;
+    }
+    throw new CLIError(`Subcomando de ticket desconocido: \`${sub ?? '(ninguno)'}\`. ` +
+        'Uso: `factory ticket push <archivo>`.');
+}
+/**
+ * Read back the created issue and say plainly whether the assignee and the label
+ * actually stuck. Silence here would be the worst outcome: the dev believes the
+ * maintainer was notified and the queue is greppable, and neither is true.
+ */
+async function verifyIssueFields(url, flags, labelDropped, assigneeDropped) {
+    const view = await execa('gh', ['issue', 'view', url, '--json', 'assignees,labels'], {
+        reject: false,
+    });
+    if (view.exitCode !== 0) {
+        console.warn('⚠️  No se pudo verificar el asignado ni la etiqueta del issue creado ' +
+            `(\`gh issue view\` salió con ${view.exitCode}). Ábrelo y confírmalo a mano.`);
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(String(view.stdout ?? '{}'));
+    }
+    catch {
+        console.warn('⚠️  No se pudo leer la respuesta de `gh issue view`; verifica el issue a mano.');
+        return;
+    }
+    // A field WE dropped on purpose was already reported by the caller with its real
+    // reason; re-reporting it here as "GitHub lo descartó en silencio" would be false.
+    const noAssignee = (!parsed.assignees || parsed.assignees.length === 0) && !assigneeDropped;
+    const noLabel = (!parsed.labels || parsed.labels.length === 0) && !labelDropped;
+    if (!noAssignee && !noLabel)
+        return;
+    if (noAssignee) {
+        console.warn(`⚠️  El issue quedó SIN ASIGNADO: GitHub descartó \`${flags.assignee}\` en silencio.`);
+    }
+    if (noLabel) {
+        console.warn(`⚠️  El issue quedó sin la etiqueta \`${flags.label}\`: GitHub la descartó en silencio.`);
+    }
+    console.warn(`   GitHub descarta asignado y etiquetas cuando quien crea el issue no tiene al menos \`triage\` ` +
+        `sobre ${FACTORY_REPO} (el permiso base del org es \`read\`).\n` +
+        '   Pide `triage` sobre el repo, o el ticket queda sin ruta de aviso al maintainer.');
+}

package/dist/commands/update.js

@@ -67,6 +67,7 @@ export function parseUpdateFlags(argv) {
         beta: argv.includes('--beta'),
         stable: argv.includes('--stable'),
         yes: argv.includes('--yes') || argv.includes('-y'),
+        launcher: argv.includes('--launcher'),
     };
 }
 /** Default acquire: download the sticky-profile tarball, stage + validate it. */
@@ -566,7 +567,17 @@ function syncDerivedPrettierignore(rootDir, stagedDir) {
 const KIT_TESTS_DIR = 'scripts/tools/__tests__/';
 /** 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;
+/**
+ * 🔴 FROZEN WIRE FORMAT — the same class of contract as the retrofit signal marker
+ * (ADR-004 §1/§4), and for the same reason. `update --dry-run` reports "the preview found
+ * conflicts" with this code, and the GUI launcher reads it to decide whether it may chain the
+ * real apply. Its twin is calqued BY VALUE in `desktop/renderer/panels/update-project.tsx`
+ * (`DRY_RUN_CONFLICTS_EXIT`) — two npm packages with no dependency edge, so no compiler will
+ * ever catch a drift. Changing this number silently kills the launcher's clobber guard, which
+ * is exactly the failure that shipped once already (see `cli/src/lib/exit-code.ts`).
+ * Exported so the golden pin in the test suite can assert it.
+ */
+export 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
@@ -859,7 +870,7 @@ export async function runUpdate(flags, deps = {}) {
         // `oldLock.version` is the version BEFORE this update, which is what separates the guides
         // that just arrived from the ones that were already sitting there. A legacy repo carries
         // `0.0.0`, so every guide reads as new — correct: it has seen none of them.
-        printRetrofitReminder({ rootDir, fromVersion: oldLock.version });
+        printRetrofitReminder({ rootDir, fromVersion: oldLock.version, guiSignal: flags.launcher });
         // End-pointer to the next step (PVSKILL-002). Reached only after a clean apply;
         // `--verify`/`--resume` short-circuit above (verify NEVER prints), an error path
         // throws earlier, and headless `--yes` is suppressed (CI noise).

package/dist/index.js

@@ -10,6 +10,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CLIError } from './lib/cli-error.js';
+import { resolveSuccessExitCode } from './lib/exit-code.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';
@@ -21,6 +22,7 @@ import { parseProvisionFlags, runProvision } from './commands/provision.js';
 import { parsePublishArgs, runPublish } from './commands/publish.js';
 import { secretsCommand } from './commands/secrets.js';
 import { parseStatusFlags, runStatus } from './commands/status.js';
+import { runTicketCommand } from './commands/ticket.js';
 import { parseUnpublishTargets, runUnpublish } from './commands/unpublish.js';
 import { maybeOfferAdopt, parseUpdateFlags, runUpdate } from './commands/update.js';
 import { detectRepo } from './lib/repo-detection.js';
@@ -43,6 +45,7 @@ Comandos:
   unpublish [qué]  Baja del hub un entregable publicado (proposal|mockup|both; default both)
   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
+  ticket <sub>     push: entrega un factory-ticket de project/factory/ al repo del Factory
   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)
@@ -141,6 +144,19 @@ Sobre \`backlog\`:
     --epic <ID>  --status <s>   Equivalente para una épica
     --heal-only                 Corre solo el self-healing (sin el sync puntual)
 
+Sobre \`ticket\`:
+  \`ticket push <archivo>\` entrega un factory-ticket de \`project/factory/\` al repo
+  del Factory como un issue de GitHub, y estampa la URL de vuelta en el campo
+  \`**GitHub issue:**\` del ticket (el \`Estado\` no cambia: entregar no es triar).
+  Cero credenciales nuevas: usa tu propia sesión de \`gh\`; sin sesión avisa y sale 0.
+  El cuerpo se publica ÍNTEGRO en un repo compartido, así que hay compuerta:
+    --dry-run        Imprime destino, asignado, etiqueta y título; no crea nada
+    --yes / -y       Salta la confirmación interactiva (obligatorio en headless)
+    --assignee <u>   Asignado del issue (default: el maintainer del Factory)
+    --label <l>      Etiqueta a aplicar (default: kit-drift; se aplica, no se crea)
+  El cuerpo NO se imprime: es un archivo de tu propio repo y lo publicado es idéntico,
+  así que abrirlo es verlo. Revísalo antes de confirmar.
+
 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
@@ -261,6 +277,13 @@ async function main(argv) {
             throw new CLIError(`Subcomando de backlog desconocido: \`${sub ?? '(ninguno)'}\`. ` +
                 'Uso: `factory backlog push` | `factory backlog sync`.');
         }
+        case 'ticket': {
+            // `factory ticket push <archivo>` — deliver a factory-ticket from
+            // `project/factory/` to the Factory repo as a GitHub issue (EXTPT-003).
+            // The dispatch lives in the command module so its branches are testable.
+            await runTicketCommand(rest);
+            return;
+        }
         case 'publish': {
             await runPublish(parsePublishArgs(rest));
             return;
@@ -328,7 +351,11 @@ async function main(argv) {
     }
 }
 main(process.argv.slice(2)).then(() => {
-    process.exit(0);
+    // NOT a bare `process.exit(0)`. An explicit argument overrides `process.exitCode`, so
+    // hardcoding 0 threw away the outcome code of any command that succeeded but had
+    // something to report — `update --dry-run`'s "there are conflicts" (exit 2) among them,
+    // which left the launcher's clobber guard dead. See `resolveSuccessExitCode`.
+    process.exit(resolveSuccessExitCode(process.exitCode));
 }, (error) => {
     if (error instanceof CLIError) {
         // An empty message is intentional (the command already rendered its own