@daniellins/power-claude 0.16.3

package/scripts/owner-layer.cjs

@@ -0,0 +1,442 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * owner-layer.cjs — MANIFESTO DA CAMADA DO DONO (Story SF12.1, ADR-027 Decisão 1/3).
+ *
+ * Declaração ÚNICA do que "é do dono" neste repositório. Substitui o
+ * `scripts/personal-data-patterns.cjs` previsto no draft da story: duas
+ * declarações separadas do que é do dono seriam a própria dispersão que esta
+ * story existe para corrigir, aplicada ao nosso artefato (`DF-SF12.1-1`).
+ *
+ * Exporta DUAS declarações e DOIS oráculos de alcance DISJUNTO:
+ *
+ *   1. `layers`   → a CAMADA DO DONO, declarada por manifesto lógico (globs),
+ *                   nunca por raiz física (mover o dado do pod quebraria a
+ *                   autocontenção que o `pod-export` exige — ADR-027 Decisão 1).
+ *                   Oráculo: `scanContainment()`.
+ *   2. `patterns` → a lista ENUMERADA de padrões de dado pessoal já classificados.
+ *                   Oráculo: `scanEnumeration()`.
+ *
+ * ALCANCE DE CADA ORÁCULO — declarado aqui e repetido no teste, porque um AC que
+ * promete mais que o instrumento é a classe de defeito que este projeto já pagou
+ * nove vezes no SF11:
+ *
+ *   • CONTENÇÃO prova: "nenhum arquivo dentro da camada declarada é publicado sem
+ *     ser um placeholder `*.example.*` marcado com sentinela (ou um não-`.example.`
+ *     explicitamente permitido por path, com a sua regra)". Pega dado NÃO ENUMERADO
+ *     — inclusive DNA de TERCEIRO extraído pelo `mind-extractor` — desde que esteja
+ *     dentro da camada. NÃO pega nada fora dela.
+ *   • ENUMERAÇÃO prova: "estas strings específicas não aparecem em nenhum arquivo
+ *     publicado fora da allowlist". Pega dado CONHECIDO em qualquer lugar do
+ *     tarball. NÃO prova ausência de "dado pessoal" em geral — dado pessoal não
+ *     tem gramática sintática (um nome próprio, um cargo, uma tese editorial não
+ *     têm forma reconhecível, ao contrário de `sk-`/`AKIA`/`ghp_`).
+ *
+ *   • LACUNA RESIDUAL, NOMEADA E SEM INSTRUMENTO: dado pessoal NÃO ENUMERADO e
+ *     FORA da camada declarada. Nenhum oráculo daqui o cobre e nenhum AC da
+ *     SF12.1 declara que cobre (`DEBT-SF12.1-B`). O que a encolhe é centralizar:
+ *     cada dado movido para dentro da camada sai do oráculo que depende de
+ *     memória humana (enumeração) e entra no que não depende (contenção).
+ *
+ * MANUTENÇÃO DA ENUMERAÇÃO (dono declarado da lista): quem acrescenta um dado
+ * pessoal novo acrescenta o padrão correspondente NA MESMA MUDANÇA, com `origin`
+ * preenchido. O `pc-devops` confere a lista como item nomeado do ritual de
+ * publicação (`template/.claude/agents/pc-devops.md`, seção "Publicação no npm").
+ * A garantia real, porém, NÃO é a diligência de ninguém: é a contenção, que não
+ * precisa que alguém lembre.
+ *
+ * PROJEÇÕES: a declaração é uma só; o que muda é onde se enumeram os arquivos.
+ *   • repo    → `template/…`, `scripts/…`, `LICENSE` …
+ *   • tarball → `package/template/…` (o consumidor tira o prefixo `package/`
+ *               antes de chamar as funções deste módulo — ver `stripPackagePrefix`).
+ *
+ * Node >= 18, zero dependências. Não tem efeito colateral: só declara e varre.
+ */
+
+// ---------------------------------------------------------------------------
+// Identidade fictícia canônica do repositório (ADR-027 Decisão 4, DF-SF12.1-6).
+// UMA identidade fictícia, reusada em TODA fixture — "fixture é exemplo, e
+// exemplo ensina" (lição SF11): fixtures com nomes fictícios diferentes ensinam
+// que qualquer nome serve ali, inclusive um real.
+// ---------------------------------------------------------------------------
+const FICTIONAL_IDENTITY = Object.freeze({
+  nome: 'Alexa Exemplo',
+  handle: '@alexa.exemplo',
+  origin: 'template/pods/content-carousel/workflows/wf-content-carousel.smoke.json + scripts/__fixtures__/voz-do-dono/',
+});
+
+// ---------------------------------------------------------------------------
+// SENTINELA de placeholder (ADR-027 Decisão 3, DF-SF12.1-2).
+// Serve a dois consumidores, e por isso não é ornamento:
+//   (a) o ORÁCULO distingue placeholder de dado real sem adivinhar semântica;
+//   (b) o AGENTE detecta "ainda não personalizado" sem diffar contra o
+//       `.example` — o diff quebra em silêncio se o usuário editar um campo só.
+// Duas formas aceitas, conforme o AC12 ("`meta.placeholder: true` / `pc:placeholder`"):
+//   • YAML com bloco `meta:` no schema (ex.: voice-dna) → `meta.placeholder: true`;
+//   • demais formatos, e YAML cujo schema NÃO tem `meta:` (ex.: dono.example.yaml,
+//     cuja raiz é `dono:`) → marcador `pc:placeholder` em COMENTÁRIO — forma que
+//     não inventa campo novo em schema consumido por agente.
+// ---------------------------------------------------------------------------
+const SENTINEL_COMMENT = 'pc:placeholder';
+const SENTINEL_YAML_RE = /^\s*placeholder:\s*true\s*(#.*)?$/m;
+
+// ---------------------------------------------------------------------------
+// 1) CAMADA DO DONO — globs relativos à RAIZ DO TEMPLATE (`template/`).
+//
+// `allowNonExample` lista, POR PATH, os arquivos da camada que legitimamente não
+// são `*.example.*`, cada um com a `rule` que a máquina verifica. Um arquivo da
+// camada que não é `.example.` e não está aqui REPROVA — é assim que a contenção
+// pega dado não enumerado.
+//
+// `machineConsumers` nomeia os campos de CLASSE P (parâmetro de mecanismo,
+// ADR-027 Decisão 4): personalização que alimenta um veto de máquina. O
+// reconhecimento é por grep, não por julgamento — um campo P sem consumidor
+// rastreável é erro de declaração.
+// ---------------------------------------------------------------------------
+const layers = [
+  {
+    id: 'voice-dna',
+    level: 'transversal',
+    glob: 'knowledge/voice-dna/**',
+    description:
+      'DNA de voz: do dono (voice-dna.yaml) e de terceiros extraídos pelo mind-extractor ({slug}-dna.yaml). ' +
+      'Nenhum dos dois é publicável — o de terceiro é dado pessoal de OUTRA pessoa.',
+    instancePath: 'knowledge/voice-dna/voice-dna.yaml',
+    allowNonExample: [
+      {
+        path: 'knowledge/voice-dna/README.md',
+        rule: 'mechanism-doc',
+        reason:
+          'Explica o MECANISMO (o que é o DNA, como o pod o consome, como instanciar). É autossuficiente ' +
+          'por exigência do ADR-027 Decisão 6: `docs/` NÃO entra em package.json.files, então delegar a ' +
+          'explicação a docs/mecanismos/ produziria doc inalcançável na instalação. Coberto apenas pela ' +
+          'ENUMERAÇÃO — declarado, não escondido.',
+      },
+    ],
+    machineConsumers: [],
+  },
+  {
+    id: 'dono-do-pod',
+    level: 'pod',
+    glob: 'pods/*/knowledge/dono*.yaml',
+    description:
+      'Configuração de dono por pod (ADR-010): trio de atribuição (nome/handle/autoridade) + guia de estilo ' +
+      '(degrau 2 da escada ADR-013).',
+    instancePath: 'pods/{pod}/knowledge/dono.yaml',
+    allowNonExample: [],
+    machineConsumers: [
+      {
+        field: 'dono.voz.lexico_proibido',
+        consumer: 'scripts/veto-checks/lexical-check.cjs',
+        class: 'P',
+        floor: ['—', '–'],
+        floorOrigin:
+          'achado R5/SF7.2 (em-dash/en-dash como "tell" de IA) — é fato do framework, não gosto do dono; ' +
+          'descer abaixo do piso exige atribuição explícita (padrão memoryCost.acceptedBy), subir é livre.',
+      },
+    ],
+  },
+  {
+    id: 'exemplos-do-pod',
+    level: 'pod',
+    glob: 'pods/*/examples/**',
+    description:
+      'PREVENTIVO (SF12.1, 2ª rodada — exigência do dono). Um `examples/` autorado é o caminho por onde ' +
+      'OPINIÃO e POSICIONAMENTO do dono chegam à instalação de terceiros sem passar por nenhum gate: o ' +
+      'agente lê o exemplo como referência de padrão e imita o ASSUNTO junto com a FORMA. A régua do dono: ' +
+      '"como isso é opinião e não regra ou comportamento do framework, então não deve ir pra instalação ' +
+      'padrão". Logo, exemplo publicado é ESQUELETO marcado (`*.example.*` + sentinela), nunca peça pronta. ' +
+      'Isto NÃO detecta opinião (não existe gramática sintática para opinião, mesma doutrina do ADR-027 ' +
+      'Decisão 3) — ele fecha o CANAL por onde ela passava, que é o que a máquina consegue garantir.',
+    instancePath: 'pods/{pod}/examples/',
+    allowNonExample: [
+      {
+        path: 'pods/*/examples/README.md',
+        rule: 'mechanism-doc',
+        reason: 'Índice do diretório: diz o que cada exemplo é e como usar. Coberto pela enumeração.',
+      },
+    ],
+    machineConsumers: [],
+  },
+  {
+    id: 'memoria-do-pod',
+    level: 'pod',
+    glob: 'pods/*/memory/**',
+    description:
+      '3ª camada — conhecimento GERADO pelo uso (ADR-027 Decisão 9). O template já shippa o slot vazio com o ' +
+      'mecanismo intacto; o que faltava era a guarda de regressão que impede um learnings real (atribuído ao ' +
+      'dono) de chegar ao pacote.',
+    instancePath: 'pods/{pod}/memory/',
+    allowNonExample: [
+      {
+        path: 'pods/*/memory/README.md',
+        rule: 'mechanism-doc',
+        reason: 'Descreve o contrato do store de memória do pod; não carrega conteúdo aprendido.',
+      },
+      {
+        path: 'pods/*/memory/learnings.jsonl',
+        rule: 'empty',
+        reason:
+          'Log cru append-only. O template distribui o SLOT, nunca o conteúdo: qualquer byte aqui é ' +
+          'experiência de uma instância vazando para o pacote.',
+      },
+      {
+        path: 'pods/*/memory/learnings.consolidated.md',
+        rule: 'no-heuristics',
+        reason:
+          'Consolidado curado. O template distribui só o CABEÇALHO funcional; qualquer heurística (linha ' +
+          '`- **[gatilho]** …`, formato de pod-memory.cjs:731/741) é conhecimento de instância.',
+      },
+    ],
+    machineConsumers: [],
+  },
+];
+
+// ---------------------------------------------------------------------------
+// 2) ENUMERAÇÃO — padrões de dado pessoal JÁ CLASSIFICADOS.
+//
+// Régua (Decisão 8 do pré-épico SF12): um padrão entra aqui quando é uma
+// CARACTERÍSTICA DO DONO que direcionaria o comportamento a objetivos pessoais
+// dele. Identidade de PUBLICAÇÃO não entra — `@daniellins/power-claude` é decisão
+// de produto da SF11.9 e está nos 7 usos legítimos de `bin/cli.js`; incluí-la
+// quebraria toda invocação do CLI sem proteger ninguém.
+//
+// ┌─ LEIA ANTES DE ACRESCENTAR UM PADRÃO DE NOME PRÓPRIO ────────────────────┐
+// │ **VARRER POR NOME DO DONO FOI APOSENTADO COMO PROXY** (decisão dele,     │
+// │ 2026-08-05, ADR-027 Emenda 2). O alvo NÃO é o nome — é a OPINIÃO.        │
+// │                                                                          │
+// │   *"Como criador do framework, não teria problema eu ser citado em algum  │
+// │    local. Esse é o menor dos problemas. O problema é uma preferência     │
+// │    minha atrapalhar o resultado de outra pessoa que usa o framework."*   │
+// │                                                                          │
+// │ Existem HOJE ~25 arquivos publicados que citam o dono pelo primeiro nome │
+// │ (`\bDaniel\b`) — em atribuição de regra ("Restrição inegociável",        │
+// │ "PARA no Daniel"), em fixtures (`id: 'daniel'`) e em crédito de autoria. │
+// │ **Eles FICAM, por decisão explícita.** Não são defeito, não são dívida,  │
+// │ e uma varredura por nome vai reencontrá-los todos.                       │
+// │                                                                          │
+// │ Acrescentar `Daniel` (ou qualquer primeiro nome) a esta lista reprovaria │
+// │ os 25 e faria alguém "consertar" o que o dono decidiu manter — desfazendo│
+// │ uma decisão dele achando que está limpando. O que se varre é opinião     │
+// │ (`docs/mecanismos/dono-parametrizado.md`, régua T4), e opinião não tem   │
+// │ gramática sintática: o instrumento contra ela é a CONTENÇÃO da camada,   │
+// │ não a enumeração.                                                        │
+// └──────────────────────────────────────────────────────────────────────────┘
+// ---------------------------------------------------------------------------
+const patterns = [
+  {
+    role: 'nome-civil',
+    pattern: 'Daniel Lins',
+    description:
+      'Nome civil do dono. Cobre "Daniel Lins da Silva" por substring. Autoria legítima na raiz ' +
+      '(LICENSE/package.json/README.md) está na allowlist.',
+    origin: 'Incidente @daniellins/power-claude@0.16.0 (CHANGELOG.md, §"Incidente pós-publicação") — 6 dos 9 arquivos.',
+  },
+  {
+    role: 'slug',
+    pattern: 'daniel-lins',
+    description: 'Slug hifenizado do nome — cobre nome de ARQUIVO (ex.: o `<slug>-voice-dna.yaml` removido por esta story).',
+    origin: 'Incidente 0.16.0 + achado da auditoria SF12.1: 4 referências cruzadas hardcodavam esse nome de arquivo.',
+  },
+  {
+    role: 'path-maquina',
+    pattern: '/Users/daniellinsdasilva',
+    description: 'Path da máquina pessoal do dono — vaza estrutura de diretórios locais e o username do SO.',
+    origin: 'Incidente 0.16.0 (template/knowledge/voice-dna/README.md citava o path do corpus).',
+  },
+];
+
+// ---------------------------------------------------------------------------
+// 3) ALLOWLIST da ENUMERAÇÃO — por PATH EXATO, nunca por padrão genérico.
+//
+// Por que existe (AC2): este próprio arquivo CONTÉM os literais perigosos (é a
+// lista deles) e é publicado (`scripts/` está em package.json.files) — sem a
+// allowlist, o oráculo se autoderrota. A allowlist é restrita a paths exatos
+// para não virar escotilha: um arquivo NOVO com o mesmo conteúdo continua sendo
+// reprovado (kill-test do AC2).
+// ---------------------------------------------------------------------------
+const enumerationAllowlist = [
+  {
+    path: 'LICENSE',
+    reason: 'Autoria legítima. Sempre incluído pelo npm, não controlável por package.json.files.',
+  },
+  {
+    path: 'package.json',
+    reason: 'Campo `author` + nome do escopo npm. Sempre incluído pelo npm.',
+  },
+  {
+    path: 'README.md',
+    reason: 'Página do npm; a atribuição de licença é autoria legítima. Sempre incluído pelo npm.',
+  },
+  {
+    path: 'scripts/owner-layer.cjs',
+    reason: 'ESTE arquivo — é a declaração dos padrões, logo contém todos eles. AC2.',
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Helpers de path/glob. Suporte mínimo e explícito: `*` (um segmento, sem `/`)
+// e `**` (qualquer número de segmentos). Nada de regex arbitrária no manifesto —
+// a fronteira precisa ser legível em `git diff`.
+// ---------------------------------------------------------------------------
+function globToRegExp(glob) {
+  let out = '^';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        out += '.*';
+        i++;
+        if (glob[i + 1] === '/') i++; // `**/` casa também com zero segmentos
+      } else {
+        out += '[^/]*';
+      }
+    } else if ('\\^$.|?+()[]{}'.includes(c)) {
+      out += `\\${c}`;
+    } else {
+      out += c;
+    }
+  }
+  return new RegExp(`${out}$`);
+}
+
+/** Path do glob da camada projetado na raiz do repo (`template/…`). */
+function layerGlobInRepo(layer) {
+  return `template/${layer.glob}`;
+}
+
+/** Remove o prefixo `package/` que o `npm pack` adiciona a todo path do tarball. */
+function stripPackagePrefix(p) {
+  return p.startsWith('package/') ? p.slice('package/'.length) : p;
+}
+
+function isExampleFile(logicalPath) {
+  return /\.example\./.test(logicalPath.split('/').pop());
+}
+
+function hasSentinel(content) {
+  if (content.includes(SENTINEL_COMMENT)) return true;
+  return SENTINEL_YAML_RE.test(content);
+}
+
+function layerOf(logicalPath) {
+  return layers.find((l) => globToRegExp(layerGlobInRepo(l)).test(logicalPath)) || null;
+}
+
+function allowedNonExampleEntry(layer, logicalPath) {
+  const rel = logicalPath.replace(/^template\//, '');
+  return layer.allowNonExample.find((e) => globToRegExp(e.path).test(rel)) || null;
+}
+
+const NON_EXAMPLE_RULES = {
+  'mechanism-doc': () => null,
+  empty: (content) => (content.trim() === '' ? null : 'arquivo deveria ser vazio (slot, não conteúdo)'),
+  'no-heuristics': (content) => {
+    const hits = content.split(/\r?\n/).filter((l) => /^- \*\*\[/.test(l));
+    return hits.length === 0 ? null : `contém ${hits.length} heurística(s) consolidada(s): ${hits[0].slice(0, 80)}`;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// ORÁCULO 1 — CONTENÇÃO (AC12).
+// `files`: [{ path, content }] com path LÓGICO (sem o prefixo `package/`).
+// ---------------------------------------------------------------------------
+function scanContainment(files) {
+  const violations = [];
+  for (const f of files) {
+    const layer = layerOf(f.path);
+    if (!layer) continue;
+    if (isExampleFile(f.path)) {
+      if (!hasSentinel(f.content)) {
+        violations.push({
+          path: f.path,
+          layer: layer.id,
+          reason: `placeholder SEM sentinela (esperado "${SENTINEL_COMMENT}" em comentário ou "placeholder: true" sob meta:)`,
+        });
+      }
+      continue;
+    }
+    const allowed = allowedNonExampleEntry(layer, f.path);
+    if (!allowed) {
+      violations.push({
+        path: f.path,
+        layer: layer.id,
+        reason:
+          'arquivo dentro da camada do dono que NÃO é `*.example.*` e não está declarado em `allowNonExample` ' +
+          `da camada "${layer.id}"`,
+      });
+      continue;
+    }
+    const rule = NON_EXAMPLE_RULES[allowed.rule];
+    if (!rule) {
+      violations.push({ path: f.path, layer: layer.id, reason: `regra desconhecida no manifesto: "${allowed.rule}"` });
+      continue;
+    }
+    const problem = rule(f.content);
+    if (problem) {
+      violations.push({ path: f.path, layer: layer.id, reason: `regra "${allowed.rule}": ${problem}` });
+    }
+  }
+  return violations;
+}
+
+// ---------------------------------------------------------------------------
+// ORÁCULO 2 — ENUMERAÇÃO (AC1/AC9).
+// ---------------------------------------------------------------------------
+function isAllowlisted(logicalPath) {
+  return enumerationAllowlist.some((e) => e.path === logicalPath);
+}
+
+/**
+ * Padrão por PAPEL (`nome-civil` | `slug` | `path-maquina`).
+ * Existe para que consumidores — em especial o próprio teste — refiram os
+ * literais perigosos SEM os escrever: qualquer arquivo publicado que os escreva
+ * literalmente precisaria entrar na allowlist, alargando a fronteira. Referir
+ * por papel mantém a allowlist restrita aos 4 paths do AC2.
+ */
+function patternByRole(role) {
+  const found = patterns.find((p) => p.role === role);
+  if (!found) throw new Error(`owner-layer: nenhum padrão com role "${role}"`);
+  return found.pattern;
+}
+
+function scanEnumeration(files) {
+  const violations = [];
+  for (const f of files) {
+    if (isAllowlisted(f.path)) continue;
+    const lines = f.content.split(/\r?\n/);
+    for (const p of patterns) {
+      lines.forEach((line, idx) => {
+        if (line.includes(p.pattern)) {
+          violations.push({
+            path: f.path,
+            pattern: p.pattern,
+            line: idx + 1,
+            excerpt: line.trim().slice(0, 120),
+          });
+        }
+      });
+    }
+  }
+  return violations;
+}
+
+module.exports = {
+  FICTIONAL_IDENTITY,
+  SENTINEL_COMMENT,
+  layers,
+  patterns,
+  enumerationAllowlist,
+  // helpers expostos para os testes e para quem implementar a Frente 4
+  globToRegExp,
+  layerGlobInRepo,
+  stripPackagePrefix,
+  isExampleFile,
+  hasSentinel,
+  layerOf,
+  isAllowlisted,
+  patternByRole,
+  // oráculos
+  scanContainment,
+  scanEnumeration,
+};