@timekast/factory 2.3.0 → 2.4.0

package/dist/commands/provision.js

@@ -44,6 +44,7 @@ import { RAIL_TIMEKAST, RailError, RailKeyMissingError } from '../lib/rail.js';
 import { classifyDeploymentState, connectedProjects, createRailwayClient, RailwayApiError, RailwayNameTakenError, RAILWAY_SERVICE_NAME, sameRepo as sameRailwayRepo, } from '../lib/railway-api.js';
 import { isRailwayProvided, isRailwaySyncTo, railwaySyncDifferences, railwaySyncLabel, railwaySyncName, } from '../lib/vault-adopt.js';
 import { createVaultClient, formatLocation, VAULT_CI_PATH, VAULT_ENV_DEVELOP, VAULT_ENV_LOCAL, VAULT_ENV_MAIN, VAULT_LAYOUT_ENVIRONMENTS, VAULT_ROOT_PATH, VAULT_TEST_ISOLATION_KEY, } from '../lib/vault-api.js';
+import { readValueFlag } from '../lib/flags.js';
 import { wireVaultWrapper } from '../lib/wrapper-wiring.js';
 /**
  * The THREE GitHub Secrets the E2E runner (`pnpm test:e2e` → `e2e-runner.ts` +
@@ -143,20 +144,6 @@ const KNOWN_DNS_ROUTES = ['org', 'cliente-cf', 'registrar'];
 /** Default verification-poll timeout (minutes) and interval (seconds) — issue §4. */
 export const DEFAULT_VERIFY_TIMEOUT_MIN = 10;
 export const VERIFY_POLL_INTERVAL_SEC = 30;
-/** Read the value of a `--key=value` or `--key value` flag from an argv slice. */
-function readValueFlag(argv, name) {
-    const prefix = `--${name}=`;
-    const inline = argv.find((arg) => arg.startsWith(prefix));
-    if (inline)
-        return inline.slice(prefix.length);
-    const idx = argv.indexOf(`--${name}`);
-    if (idx !== -1) {
-        const next = argv[idx + 1];
-        if (next && !next.startsWith('-'))
-            return next;
-    }
-    return undefined;
-}
 /**
  * Parse `--services=a,b,c` into the typed service list, rejecting unknown tokens
  * with a `CLIError` (a typo must not silently provision nothing). An empty/absent
@@ -1376,7 +1363,7 @@ const VAULT_PER_ENV_MINTED = ['AUTH_SECRET'];
  * Which keys each destination gets depends on the services the run includes: `neon` writes the
  * connection strings and the CI keys, `vercel` the runtime values, `backlog` its local creds.
  */
-export function buildVaultPlan(projectName, services) {
+export function buildVaultPlan(projectName, services, target) {
     const keys = {};
     const references = {};
     const add = (loc, names, asRef = false) => {
@@ -1416,7 +1403,9 @@ export function buildVaultPlan(projectName, services) {
     if (services.includes('backlog')) {
         add(VAULT_LOCAL_ROOT, ['BACKLOG_API_KEY', 'BACKLOG_PROJECT_ID']);
     }
-    const railway = services.includes('railway');
+    // The syncs follow the DESTINATION, not this run's steps: a run with `vault` but without the
+    // `railway` step still deploys to Railway, and never gets the Vercel syncs.
+    const railway = services.includes('railway') || target === 'railway';
     return {
         project: projectName,
         environments: VAULT_LAYOUT_ENVIRONMENTS.map((env) => env.slug),
@@ -5436,12 +5425,17 @@ function goLiveRetryHint(mailDomain) {
     const client = mailDomain.startsWith(prefix) ? mailDomain.slice(prefix.length) : '<tu dominio>';
     return `repite el go-live (\`factory provision --domain=${client}\`)`;
 }
+/** Whether the state records a kit domain in that Railway environment (created, or found by adopt). */
+function hasRailwayKitDomain(state, role) {
+    const rw = state?.railway;
+    return Boolean(rw?.customDomains?.[role] || rw?.adoptedDomains?.some((d) => d.role === role));
+}
 /**
  * Print the resolved client-domain operation tree for `--domain --dry-run`
  * (PROV-006 §8): the exact domain, the DNS route, whether the CNAME is created or
  * printed, the interim-retire intent, and the env updates — mutating NOTHING.
  */
-function printClientDomainPlan(domain, interim, route, confirm, target, clientMail = false) {
+function printClientDomainPlan(domain, hosts, route, confirm, target, clientMail = false) {
     console.log(`\nPlan de \`--domain=${domain}\` (ruta DNS: ${route}):`);
     if (target === 'railway') {
         // RWAY-005: the CNAME's destination and the TXT are what Railway returns for the domain.
@@ -5466,8 +5460,11 @@ function printClientDomainPlan(domain, interim, route, confirm, target, clientMa
         }
         console.log(`  … sondea GET /v9/projects/.../domains/${domain} hasta verified:true (o timeout)`);
     }
-    console.log(`  ${confirm ? '－' : '? (requiere --confirm o prompt)'} retira el interino ${interim} ` +
-        `(el dev ${domain}-dev se conserva)`);
+    const { interim, dev } = hosts;
+    console.log(interim
+        ? `  ${confirm ? '－' : '? (requiere --confirm o prompt)'} retira el interino ${interim}` +
+            (dev ? ` (el dev ${dev} se conserva)` : '')
+        : '  · sin dominio interino registrado: no hay nada que retirar');
     console.log(clientMail
         ? `  ↻ EMAIL_FROM=noreply@${mailDomainFor(domain)} · NEXT_PUBLIC_APP_URL=https://${domain}`
         : `  ↻ NEXT_PUBLIC_APP_URL=https://${domain}`);
@@ -8923,7 +8920,7 @@ export async function runProvision(flags, deps = {}) {
         };
     }
     if (flags.services.includes('vault')) {
-        result.vault = buildVaultPlan(projectName, flags.services);
+        result.vault = buildVaultPlan(projectName, flags.services, target);
     }
     if (vaultDecision.skipped) {
         result.vaultSkipped = vaultDecision.skipped;
@@ -8956,8 +8953,12 @@ export async function runProvision(flags, deps = {}) {
             if (hasDomain) {
                 // Same rule as the real retire (DOM-001): the plan must print the interim the
                 // project ACTUALLY has, not one re-derived in the current org zone.
-                const interim = existingProvisionDomains(projectName, state?.dns).prod;
-                printClientDomainPlan(flags.domain, interim, flags.dns, flags.confirm, target, flags.clientMail === true);
+                const hosts = existingProvisionDomains(projectName, state?.dns);
+                // Railway records its kit domains by environment: without one there is nothing to retire.
+                const onRailway = target === 'railway';
+                const interim = onRailway && !hasRailwayKitDomain(state, 'main') ? undefined : hosts.prod;
+                const dev = onRailway && !hasRailwayKitDomain(state, 'develop') ? undefined : hosts.dev;
+                printClientDomainPlan(flags.domain, { interim, dev }, flags.dns, flags.confirm, target, flags.clientMail === true);
             }
         }
         return result;
@@ -8968,7 +8969,9 @@ export async function runProvision(flags, deps = {}) {
     const preflight = await runProvisionPreflight({
         services: preflightServices,
         teamId: flags.team,
-        repoSlug: `${FACTORY_ORG}/${projectName}`,
+        // The repo the steps target (state → `--repo` → `origin` → default), never one re-derived
+        // from the slug: a repo named apart from its slug would fail a check the run would pass.
+        ...(repoSlug ? { repoSlug } : {}),
         rootDir,
         ...(target ? { target } : {}),
     }, { rail });

package/dist/commands/prune.js

@@ -0,0 +1,255 @@
+/**
+ * `factory prune <sub>` — share a derived repo with outside collaborators WITHOUT the
+ * methodology. The member who runs it acts with their own `gh` session and permissions.
+ *
+ * Model (`.claude/docs/working-with-collaborators.md`): members of the org clone the repo and
+ * run `factory update`, which drops the whole kit on their disk — the restricted part is
+ * gitignored, so it never enters the repository. Collaborators fork and open PRs; they see the
+ * product, the always-on rules and the kit systems, never the content of the procedures.
+ *
+ * Everything here is switched on per repo by `.timekast/prune.json`, which only `prepare`
+ * writes. A repo without it behaves exactly as before.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { execa } from 'execa';
+import { CLIError } from '../lib/cli-error.js';
+import { GITIGNORE_FILE } from '../lib/constants.js';
+import { readValueFlag } from '../lib/flags.js';
+import { commitWithPrivateIndex, trackedFiles } from '../lib/prune-git.js';
+import { checkPr, REJECTED_PACKAGE_FIELDS } from '../lib/prune-pr-check.js';
+import { applyTierFiles, defaultPruneDeps, originRepo, pruneAudit, pruneCutover, pruneFinish, pruneInvite, } from '../lib/prune-remote.js';
+import { DEFAULT_PRUNE_TIER, PRUNE_MARKER_PATH, getTier, isRestricted, readPruneMarker, readPruneTiers, } from '../lib/prune-tiers.js';
+import { detectRepo } from '../lib/repo-detection.js';
+const PRUNE_USAGE = 'Uso: `factory prune prepare [--tier=collab] [--skip-verify]` · ' +
+    '`factory prune cutover [--confirm] [--discard-develop] [--resume] [--repo=owner/nombre]` · ' +
+    '`factory prune invite <usuario-github> [--repo=owner/nombre]` · ' +
+    '`factory prune finish [--repo=owner/nombre]` · `factory prune audit [--repo=owner/nombre]` · ' +
+    '`factory prune check-pr <número> [--repo=owner/nombre] [--json]`.';
+export function parsePrunePrepareFlags(argv) {
+    return {
+        tier: readValueFlag(argv, 'tier') ?? DEFAULT_PRUNE_TIER,
+        skipVerify: argv.includes('--skip-verify'),
+    };
+}
+/**
+ * Write the tier's `.gitignore` block and the switch, untrack what the block now ignores, and
+ * commit all of it in one go. Idempotent: a second run on a prepared repo changes nothing and
+ * commits nothing.
+ */
+export async function prunePrepare(rootDir, flags) {
+    const head = await execa('git', ['rev-parse', '--verify', '-q', 'HEAD'], {
+        cwd: rootDir,
+        reject: false,
+    });
+    if (head.exitCode !== 0) {
+        throw new CLIError('El repo no tiene commits todavía; haz el primer commit antes de `prune`.');
+    }
+    const tier = getTier(readPruneTiers(rootDir), flags.tier);
+    // The two files this command owns must not carry someone's uncommitted work: the commit
+    // below takes them whole.
+    const dirty = await execa('git', ['status', '--porcelain', '--', GITIGNORE_FILE, PRUNE_MARKER_PATH], { cwd: rootDir, reject: false });
+    if (dirty.stdout.trim() !== '') {
+        throw new CLIError(`\`${GITIGNORE_FILE}\` o \`${PRUNE_MARKER_PATH}\` tienen cambios sin commitear. ` +
+            'Commitéalos o descártalos y vuelve a correr `factory prune prepare`.');
+    }
+    // 1. The block and the switch — `at` survives a re-run with the same tier, so a re-run
+    // changes nothing.
+    const prior = readPruneMarker(rootDir);
+    const legacyBlockRemoved = applyTierFiles(rootDir, flags.tier, tier, prior?.tier === flags.tier ? prior.at : new Date().toISOString());
+    // 2. Untrack what the tier restricts, and commit it with the block and the switch.
+    const untracked = (await trackedFiles(rootDir)).filter((p) => isRestricted(tier, p));
+    const commit = await commitWithPrivateIndex(rootDir, {
+        remove: untracked,
+        add: [GITIGNORE_FILE, PRUNE_MARKER_PATH],
+        message: `chore(prune): keep the methodology local (tier ${flags.tier})`,
+    });
+    return {
+        tier: flags.tier,
+        untracked,
+        legacyBlockRemoved,
+        ...(commit.committed ? { commit: commit.sha } : {}),
+    };
+}
+/** Group untracked paths by their first two segments, for a summary a person can read. */
+function summarizePaths(paths) {
+    const groups = new Map();
+    for (const p of paths) {
+        const key = p.split('/').slice(0, 2).join('/');
+        groups.set(key, (groups.get(key) ?? 0) + 1);
+    }
+    return [...groups].sort().map(([k, n]) => `  • ${k}/ (${n})`);
+}
+async function runPrunePrepare(flags) {
+    const rootDir = requireRepoRoot();
+    const result = await prunePrepare(rootDir, flags);
+    if (result.legacyBlockRemoved) {
+        console.log('✔ Quité el bloque `timekast:collab` hecho a mano; lo reemplaza el bloque del kit.');
+    }
+    if (!result.commit) {
+        console.log(`✔ El repo ya estaba preparado con el tier \`${result.tier}\`; no cambió nada.`);
+    }
+    else {
+        console.log(`✔ Tier \`${result.tier}\` aplicado y commiteado (${result.commit}, sin push). ` +
+            `Dejé de trackear ${result.untracked.length} archivo(s); siguen en tu disco:`);
+        for (const line of summarizePaths(result.untracked))
+            console.log(line);
+    }
+    if (flags.skipVerify)
+        return;
+    const pkgPath = path.join(rootDir, 'package.json');
+    const hasVerify = existsSync(pkgPath) &&
+        Boolean(JSON.parse(readFileSync(pkgPath, 'utf8')).scripts
+            ?.verify);
+    if (!hasVerify) {
+        console.log('ℹ️  Este repo no tiene `pnpm verify`; no corrí la verificación.');
+        return;
+    }
+    console.log('\n▸ Corriendo `pnpm verify`…');
+    const verify = await execa('pnpm', ['verify'], { cwd: rootDir, stdio: 'inherit', reject: false });
+    if (verify.exitCode !== 0) {
+        process.exitCode = 1;
+        console.error('✖ `pnpm verify` falló. Revísalo antes de seguir con el corte.');
+    }
+}
+// ---------------------------------------------------------------------------
+// cutover · invite · finish · audit (GitHub, with the member's `gh` session)
+// ---------------------------------------------------------------------------
+export function parseCutoverFlags(argv) {
+    return {
+        repo: readValueFlag(argv, 'repo'),
+        tier: readValueFlag(argv, 'tier') ?? DEFAULT_PRUNE_TIER,
+        confirm: argv.includes('--confirm'),
+        discardDevelop: argv.includes('--discard-develop'),
+        resume: argv.includes('--resume'),
+    };
+}
+async function runPruneCutover(flags, deps) {
+    const rootDir = requireRepoRoot();
+    const { preflight, result } = await pruneCutover(rootDir, flags, deps);
+    if (!result) {
+        console.log([
+            `✔ Preflight del corte de \`${preflight.repo}\` en verde. No toqué nada.`,
+            '',
+            'Plan:',
+            `  1. Snapshot de \`main\` (${preflight.mainSha.slice(0, 7)}) con el tier aplicado, validado sin rutas restringidas.`,
+            `  2. Crear \`${preflight.next}\` (privado) y subir el snapshot como \`main\` y \`develop\` — un solo commit.`,
+            `  3. Renombrar \`${preflight.repo}\` → \`${preflight.legacy}\` y \`${preflight.next}\` → \`${preflight.repo}\`.`,
+            '  4. Permitir forks SOLO en el repo nuevo; sin workflows de PRs de forks.',
+            ...(preflight.developAhead.length > 0
+                ? [
+                    `  ⚠  Se pierden ${preflight.developAhead.length} commit(s) de \`develop\` (--discard-develop).`,
+                ]
+                : []),
+            '',
+            'Para ejecutarlo: `factory prune cutover --confirm`.',
+        ].join('\n'));
+        return;
+    }
+    console.log(`✔ Corte hecho: \`${result.repo}\` es el repo nuevo (un commit, ${result.snapshot}); ` +
+        `el anterior quedó como \`${result.legacy}\`.`);
+    for (const w of result.warnings)
+        console.warn(`⚠  ${w}`);
+    if (result.notMigrated.length > 0) {
+        console.log(`\nNo migró (sigue en \`${result.legacy}\`):`);
+        for (const line of result.notMigrated)
+            console.log(`  • ${line}`);
+    }
+    console.log('\nSiguiente: reconecta el proyecto de Vercel al repo nuevo en el dashboard (Settings → Git), ' +
+        'pide a los socios volver a clonar, y corre `factory prune finish` cuando Production despliegue.');
+}
+function printAudit(repo, audit) {
+    const clean = audit.roots.length === 1 && audit.leaks.length === 0;
+    if (clean) {
+        console.log(`✔ Historia de \`${repo}\` limpia: una raíz, ninguna ruta del tier \`${audit.tierName}\`.`);
+        return true;
+    }
+    if (audit.roots.length !== 1) {
+        console.error(`✖ \`${repo}\` tiene ${audit.roots.length} commits raíz (esperado: 1) — ` +
+            'probablemente un clon viejo pusheó la historia anterior.');
+    }
+    if (audit.leaks.length > 0) {
+        console.error(`✖ ${audit.leaks.length} ruta(s) restringida(s) en la historia (incluye refs de PRs):`);
+        for (const p of audit.leaks)
+            console.error(`    ${p}`);
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+function requireRepoRoot() {
+    const root = detectRepo(process.cwd()).repoRoot;
+    if (!root)
+        throw new CLIError('Corre `factory prune` dentro de un repo git.');
+    return root;
+}
+async function repoFrom(argv) {
+    return readValueFlag(argv, 'repo') ?? (await originRepo(requireRepoRoot()));
+}
+/** `factory prune <sub> [...]` — dispatch lives here so every branch is testable. */
+export async function runPruneCommand(args, deps = defaultPruneDeps) {
+    const sub = args[0];
+    const rest = args.slice(1);
+    switch (sub) {
+        case 'prepare':
+            await runPrunePrepare(parsePrunePrepareFlags(rest));
+            return;
+        case 'cutover':
+            await runPruneCutover(parseCutoverFlags(rest), deps);
+            return;
+        case 'invite': {
+            const user = rest.find((a) => !a.startsWith('-') && rest[rest.indexOf(a) - 1] !== '--repo');
+            if (!user)
+                throw new CLIError(`Falta el usuario de GitHub del colaborador. ${PRUNE_USAGE}`);
+            const repo = await repoFrom(rest);
+            await pruneInvite(repo, user, deps);
+            console.log(`✔ Invité a \`${user}\` a \`${repo}\` con lectura. Tiene que aceptar la invitación; ` +
+                'después forkea y abre PRs a la rama de trabajo.');
+            return;
+        }
+        case 'finish': {
+            const repo = await repoFrom(rest);
+            const done = await pruneFinish(repo, deps);
+            console.log(`✔ \`${repo}-legacy\`: forks apagados, ${done.removedCollaborators.length} colaborador(es) ` +
+                'externo(s) quitado(s) y archivado.');
+            if (!printAudit(repo, done.audit))
+                process.exitCode = 1;
+            return;
+        }
+        case 'check-pr': {
+            const raw = rest.find((a) => /^\d+$/.test(a));
+            if (!raw)
+                throw new CLIError(`Falta el número del PR. ${PRUNE_USAGE}`);
+            const repo = await repoFrom(rest);
+            const result = await checkPr(repo, Number(raw), deps);
+            const refused = result.rejected.length > 0 || result.packageFields.length > 0;
+            if (rest.includes('--json')) {
+                console.log(JSON.stringify({ refused, ...result }, null, 2));
+            }
+            else if (!refused) {
+                console.log(`✔ PR #${raw}: ningún archivo fuera del producto (${result.files.length} archivo(s)).`);
+            }
+            else {
+                console.error(`✖ PR #${raw} rechazado antes del checkout — toca lo que corre alrededor del producto:`);
+                for (const r of result.rejected)
+                    console.error(`    ${r.path} — ${r.why}`);
+                for (const f of result.packageFields) {
+                    console.error(`    package.json#${f} — ${REJECTED_PACKAGE_FIELDS.includes(f) ? 'comandos que corren en tu máquina' : 'revísalo a mano'}`);
+                }
+                console.error('  Regrésalo al colaborador, o que un socio rehaga ese cambio.');
+            }
+            if (refused)
+                process.exitCode = 1;
+            return;
+        }
+        case 'audit': {
+            const repo = await repoFrom(rest);
+            if (!printAudit(repo, await pruneAudit(repo, deps)))
+                process.exitCode = 1;
+            return;
+        }
+        default:
+            throw new CLIError(`Subcomando de prune desconocido: \`${sub ?? '(ninguno)'}\`. ${PRUNE_USAGE}`);
+    }
+}

package/dist/commands/update.js

@@ -42,13 +42,15 @@ import { applyPlan, clearUpdateState, defaultBackupDir, hasUpdateState, readUpda
 import { applyClaudeMdRetrofit, assessClaudeMd, reportClaudeMd, } from '../lib/claude-md.js';
 import { collectClaudePaths } from '../lib/claude-paths.js';
 import { CLIError } from '../lib/cli-error.js';
-import { CLAUDE_MD_FILE, GITATTRIBUTES_FILE, LOCKFILE_FILE, PRETTIERIGNORE_FILE, PROFILES, TIMEKAST_DIR, } from '../lib/constants.js';
+import { CLAUDE_MD_FILE, GITATTRIBUTES_FILE, GITIGNORE_FILE, LOCKFILE_FILE, PRETTIERIGNORE_FILE, PROFILES, TIMEKAST_DIR, } from '../lib/constants.js';
 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, maintainKitScripts, setAgentKitVersion } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
 import { printProvisionPointer } from '../lib/provision-pointer.js';
+import { planPruneMaintenance } from '../lib/prune-update.js';
+import { isRestricted, PRUNE_MARKER_PATH } from '../lib/prune-tiers.js';
 import { printRetrofitReminder } from '../lib/retrofit-reminder.js';
 import { hasProvisionState } from '../lib/provision-state.js';
 import { loginCommand } from '../lib/rail.js';
@@ -332,15 +334,20 @@ function runVerify(rootDir) {
  * → prompt y/n · headless → commit by default (a headless run needs it). Stages ONLY
  * what the update touched (the applied manifest paths + lockfile + package.json +
  * .gitattributes) — never `git add -A`. Best-effort: no identity / no repo → warn + skip.
+ * In a pruned repo (`prune` given) it also untracks what the tier restricts, leaves the
+ * restricted applied paths out, and stages `.gitignore`, the switch and the shared kit paths
+ * that are not tracked yet.
  */
-async function maybeCommitBrain(rootDir, version, appliedPaths, flags) {
+async function maybeCommitBrain(rootDir, version, appliedPaths, flags, prune = null) {
     const decision = decideCommit({
         commit: flags.commit,
         noCommit: flags.noCommit,
         isTTY: Boolean(process.stdout.isTTY),
     });
-    if (decision === 'skip')
+    if (decision === 'skip') {
+        reportPendingPrune(prune);
         return;
+    }
     let doCommit = decision === 'commit';
     if (decision === 'prompt') {
         const { yes } = await prompts({
@@ -351,17 +358,31 @@ async function maybeCommitBrain(rootDir, version, appliedPaths, flags) {
         });
         doCommit = yes === true;
     }
-    if (!doCommit)
+    if (!doCommit) {
+        reportPendingPrune(prune);
         return;
+    }
     const candidates = [
-        ...appliedPaths,
+        // A pruned repo never stages what its tier keeps local (it is ignored, and the guard would
+        // refuse it); it DOES stage the shared kit paths not yet tracked (`prune-update.ts`).
+        ...(prune ? appliedPaths.filter((p) => !isRestricted(prune.tier, p)) : appliedPaths),
+        ...(prune ? [...prune.publish, GITIGNORE_FILE, PRUNE_MARKER_PATH] : []),
         `${TIMEKAST_DIR}/${LOCKFILE_FILE}`,
         ...(existsSync(path.join(rootDir, 'package.json')) ? ['package.json'] : []),
         ...(existsSync(path.join(rootDir, GITATTRIBUTES_FILE)) ? [GITATTRIBUTES_FILE] : []),
         ...(existsSync(path.join(rootDir, PRETTIERIGNORE_FILE)) ? [PRETTIERIGNORE_FILE] : []),
     ];
     try {
-        await execa('git', ['add', '--', ...candidates], { cwd: rootDir, reject: false });
+        const stageable = await filterStageable(rootDir, candidates);
+        if (prune && prune.untrack.length > 0) {
+            await execa('git', ['rm', '--cached', '-q', '--ignore-unmatch', '--', ...prune.untrack], {
+                cwd: rootDir,
+                reject: false,
+            });
+        }
+        if (stageable.length > 0) {
+            await execa('git', ['add', '--', ...stageable], { cwd: rootDir, reject: false });
+        }
         // Nothing staged (e.g. a no-op update) → no empty commit.
         const staged = await execa('git', ['diff', '--cached', '--quiet'], {
             cwd: rootDir,
@@ -382,6 +403,34 @@ async function maybeCommitBrain(rootDir, version, appliedPaths, flags) {
         console.warn('Aviso: no se pudo commitear; el cerebro se instaló igual.');
     }
 }
+/**
+ * The brain commit was skipped in a pruned repo: whatever the tier asks the index to change
+ * (untrack a restricted path, publish a newly shared one) is still pending. `prune prepare`
+ * does exactly that and is idempotent, so it is the one instruction to give.
+ */
+function reportPendingPrune(prune) {
+    if (!prune || (prune.untrack.length === 0 && prune.publish.length === 0))
+        return;
+    console.log(`ℹ️  Repo compartido (tier \`${prune.tierName}\`): quedan ${prune.untrack.length} ruta(s) por ` +
+        `dejar de trackear y ${prune.publish.length} por publicar. Corre \`factory prune prepare\` ` +
+        'para commitearlo.');
+}
+/**
+ * Keep only the paths `git add` can take: on disk, or in the index (a deletion to stage).
+ *
+ * ONE path that is in neither — a retired file the dev never committed, which the update just
+ * removed from disk — makes `git add -- a b c` exit 128 having staged NOTHING, so the brain
+ * commit was lost in silence (the warning below only fires when `git commit` fails, and a
+ * clean index commits nothing). Exported for the CLI suite.
+ */
+export async function filterStageable(rootDir, candidates) {
+    const listed = await execa('git', ['ls-files', '-z', '--cached', '--', ...candidates], {
+        cwd: rootDir,
+        reject: false,
+    });
+    const inIndex = new Set(listed.exitCode === 0 ? listed.stdout.split('\0').filter(Boolean) : []);
+    return [...new Set(candidates)].filter((rel) => inIndex.has(rel) || existsSync(path.join(rootDir, rel)));
+}
 /**
  * `--resume`: re-apply a persisted mid-flight state without re-downloading
  * (design §7.5). Reads the staged dir + plan from `.timekast/.update-state.json`.
@@ -422,7 +471,8 @@ async function runResume(rootDir, flags) {
     const claudeMdInserted = claudeMd ? applyClaudeMdRetrofit(rootDir, claudeMd) : false;
     // Maintain dotfiles BEFORE removing the staged dir (the .gitattributes source).
     const pkgMutations = maintainDerivedDotfiles(rootDir, state.stagedDir, newLock.version);
-    await maybeCommitBrain(rootDir, newLock.version, [...state.plan.writes, ...state.plan.deletes, ...(claudeMdInserted ? [CLAUDE_MD_FILE] : [])], flags);
+    const prune = await planPruneMaintenance(rootDir, state.stagedDir, newLock.files.map((f) => f.path));
+    await maybeCommitBrain(rootDir, newLock.version, [...state.plan.writes, ...state.plan.deletes, ...(claudeMdInserted ? [CLAUDE_MD_FILE] : [])], flags, prune);
     rmSync(state.stagedDir, { recursive: true, force: true });
     // A resumed update maintains package.json exactly like a normal one, so it owes the dev the
     // same account of what it moved there (`BND-004`).
@@ -940,7 +990,8 @@ export async function runUpdate(flags, deps = {}) {
         // in case B it is in `ignoreLocal`, so the plan never names it).
         const claudeMdInserted = applyClaudeMdRetrofit(rootDir, claudeMd);
         const pkgMutations = maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
-        await maybeCommitBrain(rootDir, manifest.version, [...plan.writes, ...plan.deletes, ...(claudeMdInserted ? [CLAUDE_MD_FILE] : [])], flags);
+        const prune = await planPruneMaintenance(rootDir, stagedDir, manifest.files.map((f) => f.path));
+        await maybeCommitBrain(rootDir, manifest.version, [...plan.writes, ...plan.deletes, ...(claudeMdInserted ? [CLAUDE_MD_FILE] : [])], flags, prune);
         // `theirsConflicts` IS the overwritten-local list: same source whether the dev answered
         // the prompt, passed `--theirs-all`, or ran headless — there is no second path. The
         // package.json mutations ride the SAME closing summary, not three loose notices.
@@ -1056,6 +1107,9 @@ async function applyLegacy(rootDir, stagedDir, manifest) {
     // first sync this repo records, so the birth seal = the manifest's version.
     writeLockfile(rootDir, { ...manifest, factoryVersion: manifest.version });
     const pkgMutations = maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
+    // No brain commit on this path; the block is still kept in step (the index is left to
+    // `prune prepare`, which the pending notice names).
+    reportPendingPrune(await planPruneMaintenance(rootDir, stagedDir, manifest.files.map((f) => f.path)));
     reportPkgMutations(pkgMutations);
     if (claudeMdExists) {
         console.log('\nConservé tu `CLAUDE.md` (no se sobrescribió). Verifica que importe las rules del kit ' +

package/dist/index.js

@@ -19,6 +19,7 @@ import { envWizardFlow } from './tui/env-wizard-flow.js';
 import { parseDoctorFlags, runDoctor, runLauncherDoctor } from './commands/doctor.js';
 import { parseNewFlags, runNew } from './commands/new.js';
 import { parseProvisionFlags, runProvision } from './commands/provision.js';
+import { runPruneCommand } from './commands/prune.js';
 import { parsePublishArgs, runPublish } from './commands/publish.js';
 import { parseStatusFlags, runStatus } from './commands/status.js';
 import { runTicketCommand } from './commands/ticket.js';
@@ -52,6 +53,13 @@ Comandos:
   env <sub>        push: sube product vars a Vercel (day-2) · wizard: configura las variables
                    (en la bóveda si el repo la tiene; sin bóveda, en .env.local)
   invite-admin     Crea una invitación de super_admin para un derivado (sin password en texto plano)
+  prune <sub>      Comparte el repo con colaboradores externos sin la metodología (lo guía /prune):
+                   prepare: aplica el tier (.gitignore + .timekast/prune.json) y deja de trackear
+                   lo restringido · cutover: corte a un repo cuya historia nunca tuvo la
+                   metodología (sin --confirm sólo corre el preflight) · invite <usuario>:
+                   colaborador externo con lectura · finish: archiva el -legacy y audita ·
+                   audit: revisa que la historia del repo no tenga rutas restringidas ·
+                   check-pr <n>: rechaza un PR de colaborador que toque algo fuera del producto
   vault <sub>      adopt: pasa a la bóveda un repo que nació antes de ella (sin --apply sólo
                    enseña el plan, por nombre y huella — nunca valores; con varios proyectos
                    de Vercel, --vercel-project <id> elige el principal) · sync railway: crea
@@ -410,6 +418,12 @@ async function main(argv) {
             await runVaultCommand(rest);
             return;
         }
+        case 'prune': {
+            // `factory prune <sub>` — share a repo with outside collaborators without the
+            // methodology. Dispatch lives in the command module (testable branches).
+            await runPruneCommand(rest);
+            return;
+        }
         case 'invite-admin': {
             // Mint a single-use super_admin invite against the target branch's DB.
             // Spawns the kit script `scripts/tools/invite-admin.ts` with the resolved

package/dist/lib/constants.js

@@ -104,6 +104,19 @@ export const GITATTRIBUTES_FILE = '.gitattributes';
  * turns every later `factory:update` into false conflicts (A2).
  */
 export const PRETTIERIGNORE_FILE = '.prettierignore';
+/**
+ * Repo-root `.gitignore`. Same managed-block treatment, but ONLY in a pruned repo
+ * (`factory prune`): the block lists the kit paths kept local to the members, generated
+ * from `.claude/policy/prune-tiers.json`. A repo without the switch below never gets one.
+ */
+export const GITIGNORE_FILE = '.gitignore';
+/**
+ * File name, under `.timekast/`, of the per-repo switch written by `factory prune prepare`
+ * (`{ tier, at }`). Its OWN file, not a lockfile field: `update` rewrites the lockfile whole.
+ * Without it every prune behavior — the `.gitignore` block, the untracking in `update`, the
+ * pre-commit guard — stays off.
+ */
+export const PRUNE_FILE = 'prune.json';
 /**
  * Managed-block sentinels. These are PREFIXES (the live source lines carry extra
  * descriptive text + trailing `>>>`/`<<<`), matched with `startsWith` so detection

package/dist/lib/flags.js

@@ -0,0 +1,14 @@
+/** Read the value of a `--key=value` or `--key value` flag from an argv slice. */
+export function readValueFlag(argv, name) {
+    const prefix = `--${name}=`;
+    const inline = argv.find((arg) => arg.startsWith(prefix));
+    if (inline)
+        return inline.slice(prefix.length);
+    const idx = argv.indexOf(`--${name}`);
+    if (idx !== -1) {
+        const next = argv[idx + 1];
+        if (next && !next.startsWith('-'))
+            return next;
+    }
+    return undefined;
+}