product-runner 0.5.0

package/dist/update.js

@@ -0,0 +1,400 @@
+import { mkdir, readFile, writeFile, access, rm, readdir } from "node:fs/promises";
+import { constants } from "node:fs";
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { buildArtifacts, listFiles, sha256, writeManifest, templatesRoot, packageVersion, MANIFEST_FILENAME, } from "./scaffold.js";
+import { discoverMigrations, migrationsInSpan, applyOps, globToRegExp, } from "./migrations.js";
+/** Subpasta (dentro de docs/) onde vão os artefatos de handoff dos conflitos. */
+export const HANDOFF_DIR = ".prod-runner-update";
+/**
+ * Nome do manifesto ANTES do rename para `product-runner` (migration 0.5.0).
+ * Projetos scaffoldados em versões anteriores têm o manifesto com este nome; o
+ * `readManifest` cai pra ele pra ainda achar o cursor — e a migration 0.5.0
+ * renomeia o arquivo no disco. Literal de propósito (não derivar do novo nome).
+ */
+const LEGACY_MANIFEST_FILENAME = ".project-docs-blueprints.json";
+/** Diretórios que nunca entram na varredura do projeto. */
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    ".obsidian",
+    HANDOFF_DIR,
+]);
+async function exists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// --- Normalização (antes de comparar) -------------------------------------
+//
+// O achado central da recon: sem normalizar, o formatter do projeto faz todo
+// arquivo parecer divergente. Normalizamos AMBOS os lados só pra COMPARAR — o
+// que vai pro disco é sempre o conteúdo bruto do template.
+/** Caminho do Prettier LOCAL do projeto, ou null se não estiver instalado. */
+async function prettierBin(projectDir) {
+    const bin = join(projectDir, "node_modules", ".bin", process.platform === "win32" ? "prettier.cmd" : "prettier");
+    return (await exists(bin)) ? bin : null;
+}
+/** Roda o Prettier LOCAL do projeto (nunca baixa nada). null se indisponível. */
+function runPrettier(projectDir, filename, content) {
+    return new Promise(async (resolve) => {
+        const bin = await prettierBin(projectDir);
+        if (bin === null) {
+            resolve(null);
+            return;
+        }
+        const child = spawn(bin, ["--stdin-filepath", filename], {
+            cwd: projectDir,
+        });
+        let out = "";
+        child.stdout.on("data", (d) => (out += d));
+        child.stderr.on("data", () => { });
+        child.on("error", () => resolve(null));
+        child.on("close", (code) => resolve(code === 0 ? out : null));
+        child.stdin.end(content);
+    });
+}
+/** Reduz links a só o texto visível, pra diferença de estilo não contar. */
+function stripLinks(md) {
+    return md
+        .replace(/\[\[([^\]]+)\]\]/g, "$1") // [[wiki]]
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1"); // [texto](url)
+}
+async function normalizeForCompare(content, opts) {
+    let s = content.replace(/\r\n/g, "\n");
+    if (opts.formatNormalize) {
+        const pretty = await runPrettier(opts.projectDir, opts.filename, s);
+        if (pretty !== null)
+            s = pretty;
+    }
+    s = stripLinks(s);
+    s = s
+        .split("\n")
+        .map((l) => l.replace(/[ \t]+$/, ""))
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    return s + "\n";
+}
+/** Converte links markdown relativos pro estilo wiki `[[alvo]]` do Obsidian. */
+function toWikiLinks(md) {
+    return md.replace(/\[([^\]]+)\]\(\.?\/?([^)]+?)(?:\.md)?\)/g, (_m, _text, target) => {
+        const base = target.split("/").pop() ?? target;
+        return `[[${base}]]`;
+    });
+}
+// --- Detecção de movidos --------------------------------------------------
+/** basename ignorando o sufixo `.template` (ex.: _overview.template.md → _overview.md). */
+function normBasename(path) {
+    const base = path.split("/").pop() ?? path;
+    return base.replace(/\.template(\.[^.]+)$/, "$1");
+}
+// --- Classificação --------------------------------------------------------
+async function classify(art, templatePath, projectPath, manifest, opts) {
+    // 1. não existe no projeto → adicionar
+    if (projectPath === null) {
+        return { bucket: "add", reason: "novo no template; não existe no projeto" };
+    }
+    const projectRaw = await readFile(join(opts.targetDir, projectPath), "utf8");
+    const filename = projectPath.split("/").pop() ?? "x.md";
+    // 2. com manifesto: comparar hash bruto contra a base registrada
+    const base = manifest?.files[templatePath]?.sha256;
+    if (base) {
+        const untouched = sha256(projectRaw) === base;
+        const templateChanged = sha256(art.content) !== base;
+        if (untouched) {
+            return templateChanged
+                ? { bucket: "automerge", reason: "você não editou; template evoluiu" }
+                : { bucket: "uptodate", reason: "em dia (nada mudou)" };
+        }
+    }
+    // 3. iguais após normalizar → no-op (pega diff só de formatação/links)
+    const [np, nn] = await Promise.all([
+        normalizeForCompare(projectRaw, {
+            projectDir: opts.targetDir,
+            filename,
+            formatNormalize: opts.formatNormalize,
+        }),
+        normalizeForCompare(art.content, {
+            projectDir: opts.targetDir,
+            filename,
+            formatNormalize: opts.formatNormalize,
+        }),
+    ]);
+    if (np === nn) {
+        return { bucket: "uptodate", reason: "idêntico após normalizar formatação" };
+    }
+    // 4. divergência real → decisão humana (gera handoff)
+    return {
+        bucket: "review",
+        reason: base
+            ? "você editou e o template também mudou"
+            : "sem manifesto; divergência precisa de classificação",
+    };
+}
+// --- Plano + aplicação ----------------------------------------------------
+async function readManifest(targetDir) {
+    // nome atual primeiro; cai pro legado pra ainda achar o cursor de projetos
+    // pré-rename (a migration 0.5.0 renomeia o arquivo no disco no mesmo update).
+    for (const name of [MANIFEST_FILENAME, LEGACY_MANIFEST_FILENAME]) {
+        const p = join(targetDir, "docs", name);
+        if (!(await exists(p)))
+            continue;
+        try {
+            return JSON.parse(await readFile(p, "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function handoffContent(item, projectRaw) {
+    return `# Handoff de update — ${item.templatePath}
+
+> Gerado pelo \`product-runner update\`. O CLI **não** alterou o arquivo
+> original; isto é material pra você (ou uma sessão Claude) classificar e decidir.
+
+- **Arquivo no projeto:** \`${item.projectPath}\`${item.moved ? " (movido em relação ao template)" : ""}
+- **Origem no template:** \`${item.art.fromTemplate}\`
+- **Motivo:** ${item.reason}
+
+## Tarefa
+
+Classifique cada diferença entre as duas versões abaixo como **melhoria do
+template** (trazer) ou **customização do projeto** (preservar), e produza a
+versão final mesclada. Em caso de conflito real no mesmo trecho, explique o
+tradeoff em vez de escolher sozinho.
+
+## Versão ATUAL (no projeto)
+
+\`\`\`\`\`markdown
+${projectRaw.trimEnd()}
+\`\`\`\`\`
+
+## Versão NOVA (template)
+
+\`\`\`\`\`markdown
+${item.art.content.trimEnd()}
+\`\`\`\`\`
+`;
+}
+function migrationHandoff(mig) {
+    return `# Migration ${mig.version} — ${mig.title}
+
+> Migration **conduzida** (não-automática) do \`product-runner\`. O CLI
+> não aplicou nada; conduza as instruções abaixo com o humano.
+${mig.previous ? `\n- **De:** ${mig.previous} → **${mig.version}**` : ""}
+${mig.risk ? `- **Risco:** ${mig.risk}` : ""}
+${mig.affects.length ? `- **Afeta:** ${mig.affects.join(", ")}` : ""}
+
+${mig.body}
+`;
+}
+/**
+ * Calcula o plano de update e, se !dryRun, aplica: escreve ADD + AUTO-MERGE
+ * (ADD primeiro, pra refs resolverem), gera handoff dos REVIEW sem tocar o
+ * original, e reescreve o manifesto com a nova base.
+ */
+export async function update(opts) {
+    const manifest = await readManifest(opts.targetDir);
+    const mode = manifest ? "3way" : "legacy";
+    const profile = opts.profile ?? manifest?.profile;
+    if (!profile) {
+        throw new Error("Sem manifesto e sem --profile. Informe --profile <cli|ssr> pra um projeto legado.");
+    }
+    // nome/porta: do manifesto, ou inferidos (só afetam o CLAUDE.md, que é review)
+    let name = manifest?.projectName;
+    let port = manifest?.port ?? "3000";
+    if (!name) {
+        const claudePath = join(opts.targetDir, "CLAUDE.md");
+        if (await exists(claudePath)) {
+            const m = (await readFile(claudePath, "utf8")).match(/^#\s+(.+)$/m);
+            name = m?.[1]?.trim();
+        }
+        name = name ?? "projeto";
+    }
+    const meta = { name, profile, port };
+    // Normalização por Prettier só roda se pedida E o binário existir no projeto.
+    // Se foi pedida mas não há binário, degradamos — e sinalizamos no resultado
+    // (senão arquivos que só diferem por formatação caem em REVISAR sem aviso).
+    const prettierFound = (await prettierBin(opts.targetDir)) !== null;
+    const formatActive = opts.formatNormalize && prettierFound;
+    const effectiveOpts = { ...opts, formatNormalize: formatActive };
+    const handoffDir = join(opts.targetDir, "docs", HANDOFF_DIR);
+    // Migrations: só com manifesto (cursor conhecido). Intervalo
+    // (manifesto.version, versão-do-pacote]. Rodam ANTES do diff de estado.
+    const pkgVersion = await packageVersion(templatesRoot());
+    const migrations = manifest
+        ? migrationsInSpan(await discoverMigrations(join(templatesRoot(), "migrations")), manifest.version, pkgVersion)
+        : [];
+    if (!opts.dryRun && migrations.length) {
+        // 1. ops mecânicos das migrations autoApply, em ordem (mutam o projeto)
+        for (const mig of migrations) {
+            if (mig.autoApply && mig.ops.length) {
+                await applyOps(opts.targetDir, mig.ops, await listProjectFiles(opts.targetDir));
+            }
+        }
+        // 2. corpo conduzido → handoff (mesmo em autoApply: parte mecânica roda
+        //    sozinha, mas o que precisa de decisão humana fica em MIGRATION-<v>.md)
+        const withBody = migrations.filter((m) => m.body.trim().length > 0);
+        if (withBody.length) {
+            await mkdir(handoffDir, { recursive: true });
+            for (const mig of withBody) {
+                await writeFile(join(handoffDir, `MIGRATION-${mig.version}.md`), migrationHandoff(mig), "utf8");
+            }
+        }
+    }
+    const artifacts = await buildArtifacts(meta);
+    // índice de arquivos do projeto por basename normalizado (pra detectar movidos)
+    // (já reflete o resultado das migrations autoApply, aplicadas acima)
+    const projectFiles = await listProjectFiles(opts.targetDir);
+    const byBasename = new Map();
+    for (const p of projectFiles) {
+        const key = normBasename(p);
+        const list = byBasename.get(key) ?? [];
+        list.push(p);
+        byBasename.set(key, list);
+    }
+    const onlyRe = opts.only ? globToRegExp(opts.only) : null;
+    const templatePaths = new Set(artifacts.keys());
+    const plan = [];
+    for (const [templatePath, art] of artifacts) {
+        // resolve onde (e se) o arquivo existe no projeto
+        let projectPath = null;
+        let moved = false;
+        if (await exists(join(opts.targetDir, templatePath))) {
+            projectPath = templatePath;
+        }
+        else {
+            // candidatos a "movido": mesmo basename, mas NÃO um arquivo que já é
+            // emitido pelo template no próprio lugar dele (evita casar docs/README.md
+            // com docs/agents/README.md, p.ex.).
+            const candidates = (byBasename.get(normBasename(templatePath)) ?? []).filter((p) => !templatePaths.has(p));
+            if (candidates.length === 1) {
+                projectPath = candidates[0];
+                moved = projectPath !== templatePath;
+            }
+        }
+        if (onlyRe && !onlyRe.test(templatePath) && !(projectPath && onlyRe.test(projectPath))) {
+            continue;
+        }
+        const { bucket, reason } = await classify(art, templatePath, projectPath, manifest, effectiveOpts);
+        plan.push({
+            templatePath,
+            projectPath: projectPath ?? templatePath,
+            bucket,
+            reason,
+            moved,
+            art,
+        });
+    }
+    const counts = {
+        add: 0,
+        automerge: 0,
+        uptodate: 0,
+        review: 0,
+    };
+    for (const it of plan)
+        counts[it.bucket]++;
+    if (!opts.dryRun) {
+        const projectUsesWiki = await detectWikiLinks(opts.targetDir, projectFiles);
+        // ADD primeiro (pra refs de arquivos novos resolverem nos merges)
+        for (const it of plan.filter((i) => i.bucket === "add")) {
+            let content = it.art.content;
+            if (opts.normalizeLinks && projectUsesWiki)
+                content = toWikiLinks(content);
+            const dest = join(opts.targetDir, ...it.templatePath.split("/"));
+            await mkdir(dirname(dest), { recursive: true });
+            await writeFile(dest, content, "utf8");
+        }
+        // AUTO-MERGE: substitui no lugar atual (inclusive se movido)
+        for (const it of plan.filter((i) => i.bucket === "automerge")) {
+            let content = it.art.content;
+            if (opts.normalizeLinks && projectUsesWiki)
+                content = toWikiLinks(content);
+            const dest = join(opts.targetDir, ...it.projectPath.split("/"));
+            await mkdir(dirname(dest), { recursive: true });
+            await writeFile(dest, content, "utf8");
+        }
+        // REVIEW: gera handoff, nunca toca o original
+        const reviews = plan.filter((i) => i.bucket === "review");
+        if (reviews.length) {
+            await mkdir(handoffDir, { recursive: true });
+            // limpa só handoffs antigos; preserva o resto (ex.: marcador .last-check)
+            for (const f of await readdir(handoffDir)) {
+                if (f.endsWith(".handoff.md")) {
+                    await rm(join(handoffDir, f), { force: true });
+                }
+            }
+            for (const it of reviews) {
+                const projectRaw = await readFile(join(opts.targetDir, it.projectPath), "utf8");
+                const flat = it.templatePath.replace(/\//g, "__");
+                await writeFile(join(handoffDir, `${flat}.handoff.md`), handoffContent(it, projectRaw), "utf8");
+            }
+        }
+        // reescreve o manifesto: base passa a ser o template atual (vira 3-way no próximo)
+        await writeManifest(join(opts.targetDir, "docs"), meta, artifacts);
+    }
+    return {
+        mode,
+        plan,
+        applied: !opts.dryRun,
+        handoffDir,
+        counts,
+        formatActive,
+        prettierFound,
+        migrations,
+    };
+}
+/** Lista arquivos do projeto (POSIX, relativos a targetDir), pulando SKIP_DIRS. */
+async function listProjectFiles(targetDir) {
+    const all = await listFiles(targetDir);
+    return all.filter((p) => !p.split("/").some((seg) => SKIP_DIRS.has(seg)));
+}
+/** Heurística: o projeto usa predominantemente wiki-links `[[x]]`? */
+async function detectWikiLinks(targetDir, projectFiles) {
+    let wiki = 0;
+    for (const p of projectFiles.filter((f) => f.endsWith(".md")).slice(0, 50)) {
+        const content = await readFile(join(targetDir, p), "utf8");
+        wiki += (content.match(/\[\[[^\]]+\]\]/g) ?? []).length;
+    }
+    return wiki >= 3;
+}
+const BUCKET_LABEL = {
+    add: "➕ ADICIONA",
+    automerge: "✅ AUTO-MERGE",
+    uptodate: "✓ EM DIA",
+    review: "⚠️  REVISAR",
+};
+/** Renderiza o plano pra impressão no terminal. */
+export function renderPlan(result) {
+    const lines = [];
+    if (result.migrations.length) {
+        lines.push(`🧭 MIGRATIONS no caminho (${result.migrations.length}) — em ordem, antes do diff:`);
+        for (const mig of result.migrations) {
+            const mode = mig.autoApply ? "automático" : "conduzir";
+            const risk = mig.risk ? ` · risco ${mig.risk}` : "";
+            lines.push(`   ${mig.version}  ${mig.title}  [${mode}${risk}]`);
+        }
+        lines.push("");
+    }
+    const order = ["add", "automerge", "review", "uptodate"];
+    for (const bucket of order) {
+        const items = result.plan.filter((i) => i.bucket === bucket);
+        if (!items.length)
+            continue;
+        lines.push(`${BUCKET_LABEL[bucket]} (${items.length})`);
+        for (const it of items) {
+            const path = it.moved ? `${it.projectPath} ← ${it.templatePath}` : it.templatePath;
+            lines.push(`   ${path}  — ${it.reason}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}

package/migrations/0.3.0.md

@@ -0,0 +1,54 @@
+---
+{
+  "version": "0.3.0",
+  "previous": "0.2.3",
+  "title": "agente-prod-runner como entrada; _overview/_open-issues vão pra specs/ sem .template",
+  "risk": "low",
+  "autoApply": true,
+  "affects": [
+    "docs/_overview.template.md -> specs/_overview.md",
+    "docs/_open-issues.template.md -> specs/_open-issues.md",
+    "CLAUDE.md (seção Manutenção -> agente-prod-runner)"
+  ],
+  "ops": [
+    { "type": "rename", "from": "docs/_overview.template.md", "to": "specs/_overview.md" },
+    { "type": "rename", "from": "docs/_open-issues.template.md", "to": "specs/_open-issues.md" },
+    { "type": "replace", "glob": "**/*.md", "find": "_overview\\.template", "replace": "_overview" },
+    { "type": "replace", "glob": "**/*.md", "find": "_open-issues\\.template", "replace": "_open-issues" }
+  ]
+}
+---
+
+## O que mudou na 0.3.0
+
+Dois movimentos:
+
+1. **`_overview` / `_open-issues` saem de `docs/` (com sufixo `.template`) e viram
+   seeds em `specs/`** — `specs/_overview.md` e `specs/_open-issues.md`. É onde os
+   projetos reais já os colocavam; o `pipeline.md` sempre tratou specs como
+   habitantes de `specs/`. Os `ops` mecânicos acima fazem o rename e dropam o
+   sufixo `.template` das referências.
+
+2. **A porta de entrada agora é o `agente-prod-runner`** (roteador + ciclo de vida), e a
+   rotina de manutenção saiu do `CLAUDE.md` pro `docs/agents/agente-prod-runner.md`. O
+   `update` adiciona `agente-prod-runner.md` (e `agente-kickoff.md`, se faltar) em
+   `docs/agents/` automaticamente.
+
+## Conduza com o humano (parte não-mecânica)
+
+O `CLAUDE.md` é customizado, então o `update` o marca como REVISAR — não é tocado
+automaticamente. Ao reconciliar o handoff do `CLAUDE.md`:
+
+- **Substitua a seção `## Manutenção dos protocolos de doc` antiga** (a que trazia
+  a rotina completa de verificação/`update`) **pelo gatilho fino** da versão nova,
+  que apenas aponta para `docs/agents/agente-prod-runner.md`. **Preserve** todo o resto do
+  seu `CLAUDE.md` (stack, arquitetura, design system, tabela de estado).
+- Se o seu `CLAUDE.md` ainda **não** tinha a seção Manutenção (projeto bem antigo),
+  apenas **adicione** o gatilho fino.
+
+Depois, confira:
+
+- `specs/_overview.md` e `specs/_open-issues.md` existem e mantêm o conteúdo que
+  você havia preenchido (o rename preserva o conteúdo; só muda o caminho/nome).
+- Nenhum link aponta mais para `*_overview.template` / `*_open-issues.template`.
+  Se sobrou algum link com caminho `docs/_overview…`, ajuste para `specs/_overview.md`.

package/migrations/0.4.0.md

@@ -0,0 +1,76 @@
+---
+{
+  "version": "0.4.0",
+  "previous": "0.3.0",
+  "title": "status content-derived + fluxos de review como estágio nomeado",
+  "risk": "low",
+  "autoApply": false,
+  "affects": [
+    "docs/pipeline.md (estágio 5 + seção 'Em que estágio estou?')",
+    "docs/agents/README.md (fluxos de review na tabela/diagrama)",
+    "docs/lessons-learned.md (nova lição)",
+    "CLAUDE.md (subseção 'Em que etapa o projeto está' + caveat na tabela de estado)",
+    "specs/_overview.md (caveat 'índice derivado')"
+  ],
+  "ops": []
+}
+---
+
+## O que mudou na 0.4.0
+
+Um eixo só: **status do projeto se descobre pelo conteúdo das specs, não pela
+tabela de índice** — e os **fluxos de review** (Estágio 5) passam a ser estágio
+nomeado e verificável, não um passo solto.
+
+Motivação concreta: numa sessão de orientação, ao responder "em que etapa
+estamos / qual o próximo passo", o agente respondeu a partir das tabelas de
+status (`_overview`, tabela de estado do `CLAUDE.md`) — lidas truncadas — sem
+abrir nenhuma spec. Resultado: quase repassou a divergência do índice (que
+driftou) como verdade e confundiu "Decisões de implementação preenchidas"
+(rastro do **estágio 4**, por M1) com "review feito" (**estágio 5**, que tem
+rastro próprio). A correção torna o procedimento explícito.
+
+Mudanças por arquivo:
+
+1. **`docs/pipeline.md`** — o diagrama expande o Estágio 5 na sub-cadeia
+   **Review.Code → User Review → Review.Product → Review.LLM** (com escala de
+   Impeditivo); §5 deixa de ser "fase futura"; nova seção **"Em que estágio
+   estou?"** com a tabela de rastros e a regra de fonte (a spec é fonte;
+   `_overview`/tabela de estado são índice derivado).
+2. **`docs/agents/README.md`** — os quatro `agente-review-*` entram na tabela,
+   no diagrama e na prosa (antes não apareciam como estágio).
+3. **`docs/lessons-learned.md`** — nova lição "Status se lê do conteúdo, não do
+   índice".
+
+Os três acima são arquivos de template **não-customizados** — o diff de estado
+do `update` os reconcilia sozinho. Nada a conduzir neles.
+
+## Conduza com o humano (parte não-mecânica)
+
+Os dois arquivos abaixo são **customizados** no seu projeto, então o `update` os
+marca como REVISAR e **não** os toca automaticamente. A mudança aqui é
+**aditiva** — preserve todo o seu conteúdo e apenas inclua o que falta:
+
+- **`CLAUDE.md`:**
+  - No item do `pipeline` em "Docs de referência", **complete a cadeia** com o
+    estágio de review: `… → implementação → review (Review.Code → User Review →
+    Review.Product → Review.LLM)`.
+  - Na seção **"Estado do refactor / desenvolvimento"**, adicione o caveat
+    **"Índice derivado, não fonte"** acima da tabela (a tabela e o `_overview`
+    são conveniência que drift-a; a fonte é o conteúdo da spec).
+  - Adicione a subseção **"Em que etapa o projeto está"** (descobrir o estágio
+    pelo rastro no conteúdo da spec; cuidado para não confundir "Decisões de
+    implementação" = estágio 4 com review = estágio 5; nunca responder status de
+    leitura truncada `head -N`). Veja o texto de referência em
+    `common/claude-md.template.md` do pacote.
+
+- **`specs/_overview.md`:** adicione no header o caveat **"Índice derivado, não
+  fonte"** — não responder "qual a próxima etapa" a partir desta tabela,
+  confirmar na spec. Mesmo princípio LDoc→HDoc.
+
+Depois, confira:
+
+- `docs/pipeline.md` tem a seção "Em que estágio estou?" e o Estágio 5 com a
+  sub-cadeia de review.
+- O `CLAUDE.md` aponta para essa seção e a tabela de estado está marcada como
+  índice derivado.

package/migrations/0.5.0.md

@@ -0,0 +1,55 @@
+---
+{
+  "version": "0.5.0",
+  "previous": "0.4.0",
+  "title": "rename: project-docs-blueprints -> product-runner (e pdb -> prod-runner)",
+  "risk": "low",
+  "autoApply": true,
+  "affects": [
+    "docs/.project-docs-blueprints.json -> docs/.product-runner.json",
+    "docs/agents/agente-pdb.md -> docs/agents/agente-prod-runner.md",
+    "docs/.pdb-update/ -> docs/.prod-runner-update/ (efêmero, regenera)",
+    "CLAUDE.md / docs customizados (referências a `npx project-docs-blueprints`, `agente-pdb`, `.pdb-update`)"
+  ],
+  "ops": [
+    { "type": "rename", "from": "docs/.project-docs-blueprints.json", "to": "docs/.product-runner.json" },
+    { "type": "rename", "from": "docs/agents/agente-pdb.md", "to": "docs/agents/agente-prod-runner.md" }
+  ]
+}
+---
+
+## O que mudou na 0.5.0
+
+O pacote foi renomeado de **`project-docs-blueprints`** para **`product-runner`**,
+e a abreviação **`pdb`** virou **`prod-runner`**:
+
+- `agente-pdb.md` → `agente-prod-runner.md` (a porta de entrada / roteador)
+- `.pdb-update/` → `.prod-runner-update/` (pasta efêmera de handoffs)
+- diretivas `pdb-merge` → `prod-runner-merge` (internas ao pacote; não vão pra projetos)
+
+Mudança de identidade/marca — nada de comportamento.
+
+As partes mecânicas são aplicadas sozinhas pelos `ops`: o manifesto
+`docs/.project-docs-blueprints.json` → `docs/.product-runner.json` e o agente
+`docs/agents/agente-pdb.md` → `docs/agents/agente-prod-runner.md`. O `update`
+ainda tem um **fallback** que lê o manifesto no nome antigo se o novo não
+existir, então rodar o `update` de um projeto pré-rename funciona.
+
+A pasta `docs/.pdb-update/` é efêmera e gitignored — **não** é renomeada por op;
+ela simplesmente regenera como `docs/.prod-runner-update/` no próximo handoff.
+Pode apagar a antiga.
+
+## Conduza com o humano (parte não-mecânica)
+
+Em arquivos **customizados** (que o `update` não toca), troque referências ao
+nome antigo:
+
+- `CLAUDE.md` — `npx project-docs-blueprints …` → `npx product-runner …`; o
+  ponteiro de manutenção `agente-pdb` → `agente-prod-runner`; o aviso de
+  `.gitignore` de `docs/.pdb-update/` → `docs/.prod-runner-update/`.
+- `.gitignore` do projeto — troque a linha `docs/.pdb-update/` por
+  `docs/.prod-runner-update/`.
+- Qualquer script/CI/README seu que invoque o pacote ou cite `agente-pdb`.
+
+Busca rápida: `grep -rni "project-docs-blueprints\|pdb" .` — deve sobrar só
+histórico (CHANGELOG/migrations).

package/migrations/README.md

@@ -0,0 +1,68 @@
+# Migrations
+
+Notas de migração entre versões dos templates. **Opcionais por versão** — a
+maioria dos bumps (um arquivo novo, formatação, pequena adição) é resolvida pelo
+diff de estado do `update` e **não** precisa de migration. Uma migration só
+existe quando há mudança que o diff não expressa ou não deve aplicar sozinho:
+rename/split de arquivos, mudança de convenção, ou transformação acoplada a
+código.
+
+## Como o `update` usa
+
+1. Lê o `version` do manifesto do projeto (o "cursor").
+2. Junta as migrations no intervalo `(cursor, versão-do-pacote]`, em ordem.
+3. Roda-as **antes** do diff de estado: as `autoApply` aplicam seus `ops`
+   mecânicos; as demais viram handoff (`docs/.prod-runner-update/MIGRATION-<v>.md`) pra
+   conduzir com o humano.
+4. Depois o diff de estado reconcilia o que sobrou.
+
+## Formato
+
+Um arquivo por versão: `migrations/<x.y.z>.md`. Frontmatter **JSON** entre `---`
+(o pacote é zero-dependência; JSON.parse é robusto), seguido do corpo em
+markdown com as instruções conduzidas.
+
+```md
+---
+{
+  "version": "0.3.0",
+  "previous": "0.2.3",
+  "title": "Resumo curto da migração",
+  "risk": "high",
+  "autoApply": false,
+  "affects": ["docs/DESIGN-SYSTEM.md"],
+  "ops": []
+}
+---
+
+## O que mudou
+
+Prosa explicando a mudança e, se `autoApply: false`, como conduzir a decisão
+com o humano (o que trazer, o que preservar, qual o tradeoff).
+```
+
+### Campos
+
+| Campo | Significado |
+|---|---|
+| `version` | versão que esta migration leva o projeto a alcançar (= nome do arquivo) |
+| `previous` | versão anterior (informativo) |
+| `title` | resumo de uma linha |
+| `risk` | `low` ou `high` |
+| `autoApply` | `true` = o CLI aplica os `ops` sozinho; `false` = só apresenta, a LLM conduz |
+| `affects` | lista informativa de arquivos/áreas afetados |
+| `ops` | passos mecânicos (só executados se `autoApply: true`) |
+
+### Ops mecânicos
+
+```json
+{ "type": "rename", "from": "docs/a.md", "to": "docs/b.md" }
+{ "type": "replace", "glob": "docs/**/*.md", "find": "regex", "replace": "texto" }
+```
+
+- `rename`: move o arquivo (no-op se a origem não existir — ex.: já renomeado).
+- `replace`: regex global nos arquivos que casam o `glob` (`*` num segmento,
+  `**` atravessa).
+
+> Mudança acoplada a código (ex.: migração de tokens primitivos → semânticos)
+> **não** deve ser `autoApply` — descreva em prosa e deixe virar spec/issue.