wendkeep 0.29.2 → 0.31.0

package/src/init.mjs

@@ -9,9 +9,12 @@ import { createInterface } from 'node:readline/promises';
 import {
   VAULT_FOLDERS,
   SESSION_HOOKS,
+  CHANGE_NUDGE_HOOKS,
+  CHANGE_GATE_HOOKS,
   MCP_SERVER_KEY,
   mcpServerEntry,
   hookCommand,
+  hookCommandLocal,
   deriveVaultDirName,
   selectableCompanions,
   resolveCompanions,
@@ -91,27 +94,45 @@ function backup(path) {
 
 // --- merges -----------------------------------------------------------------
 
-export function mergeSettings(existing, { vaultPath, withMcp, force, companions = [], skipMcp = [], dotcontextHookLevel = 'full' }) {
+// Comando preferido para um hook: node-direto quando o projeto tem o pacote local (alta
+// frequência sem cold-start de npx — ver R3 do design 0.31.0); senão o npx portátil.
+export function hookCommandFor(name, projectPath) {
+  try {
+    if (projectPath && existsSync(join(projectPath, 'node_modules', 'wendkeep', 'hooks', `${name}.mjs`))) {
+      return hookCommandLocal(name);
+    }
+  } catch { /* fs indisponível — npx */ }
+  return hookCommand(name);
+}
+
+export function mergeSettings(existing, { vaultPath, withMcp, force, companions = [], skipMcp = [], dotcontextHookLevel = 'full', projectPath = '' }) {
   const s = existing && typeof existing === 'object' ? { ...existing } : {};
   s.hooks = { ...(s.hooks || {}) };
   let added = 0;
-  // wendkeep's own session hooks + any companion-authored hooks. Stable-sort by
-  // `order` (default 0) so higher-order companion hooks (e.g. dotcontext's order 100)
-  // fold AFTER wendkeep's own within each event. A spec may carry its own `command`
-  // (dotcontext dispatch) instead of a wendkeep hook `name`.
-  const allSpecs = [...SESSION_HOOKS, ...companionHookSpecs(companions, { dotcontextHookLevel })].sort(
-    (a, b) => (a.order ?? 0) - (b.order ?? 0),
-  );
+  // wendkeep's own session hooks + the change-lifecycle hooks (0.31.0, default) + any
+  // companion-authored hooks. Stable-sort by `order` (default 0) so higher-order companion
+  // hooks (e.g. dotcontext's order 100) fold AFTER wendkeep's own within each event. A spec
+  // may carry its own `command` (dotcontext dispatch) instead of a wendkeep hook `name`.
+  const allSpecs = [
+    ...SESSION_HOOKS,
+    ...CHANGE_NUDGE_HOOKS,
+    ...CHANGE_GATE_HOOKS,
+    ...companionHookSpecs(companions, { dotcontextHookLevel }),
+  ].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
   for (const h of allSpecs) {
-    const command = h.command ?? hookCommand(h.name);
+    const command = h.command ?? (h.preferLocal ? hookCommandFor(h.name, projectPath) : hookCommand(h.name));
+    // Dual-recognition: um hook nomeado é reconhecido tanto na forma npx quanto na node-direta,
+    // para que trocar a forma preferida (ou re-initar noutra máquina) nunca duplique o grupo.
+    const candidates = h.command ? [h.command] : [hookCommand(h.name), hookCommandLocal(h.name)];
     const groups = Array.isArray(s.hooks[h.event]) ? [...s.hooks[h.event]] : [];
-    const owning = groups.find((g) => (g.hooks || []).some((x) => x.command === command));
+    const owning = groups.find((g) => (g.hooks || []).some((x) => candidates.includes(x.command)));
     if (owning) {
       // Already wired: never add a duplicate group (the old `if (present && !force)` fell through
       // under --force and appended a second identical group). Under --force, refresh the managed
       // entry's fields in place — without disturbing any sibling hooks the user grouped with it.
       if (force) {
-        const hk = owning.hooks.find((x) => x.command === command);
+        const hk = owning.hooks.find((x) => candidates.includes(x.command));
+        hk.command = command;
         hk.timeout = h.timeout;
         if (h.statusMessage) hk.statusMessage = h.statusMessage;
         if (h.matcher && (owning.hooks || []).length === 1) owning.matcher = h.matcher;
@@ -477,12 +498,12 @@ export async function runInit(argv) {
   const settingsRead = readJsonSafe(settingsPath);
   if (!settingsRead.ok) {
     // Unparseable existing file — never clobber. Drop a .new for manual merge.
-    const fresh = mergeSettings(null, { vaultPath, withMcp: args.mcp, force: true, companions, skipMcp, dotcontextHookLevel }).settings;
+    const fresh = mergeSettings(null, { vaultPath, withMcp: args.mcp, force: true, companions, skipMcp, dotcontextHookLevel, projectPath }).settings;
     writeJson(`${settingsPath}.new`, fresh);
     log(M.settingsBadJson(settingsPath));
   } else {
     const hadFile = settingsRead.data !== null;
-    const { settings, added } = mergeSettings(settingsRead.data, { vaultPath, withMcp: args.mcp, force: args.force, companions, skipMcp, dotcontextHookLevel });
+    const { settings, added } = mergeSettings(settingsRead.data, { vaultPath, withMcp: args.mcp, force: args.force, companions, skipMcp, dotcontextHookLevel, projectPath });
     if (hadFile) backup(settingsPath);
     writeJson(settingsPath, settings);
     log(M.settings(hadFile ? M.merged : M.created, added, hadFile ? M.bakSaved : ''));

package/src/renumber.mjs

@@ -0,0 +1,32 @@
+// `wendkeep renumber-decisions` — retroactive ADR fix. Renumbers every note in 04-Decisões to
+// `ADR-<NNNN>-<slug>` in chronological order, renames the files, and rewrites every wikilink to
+// them across the vault. Preview by default; pass --apply to write. Idempotent.
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { renumberDecisions } from '../hooks/renumber-decisions.mjs';
+
+function opt(argv, name) {
+  const i = argv.indexOf(name);
+  if (i >= 0) return argv[i + 1];
+  const eq = argv.find((a) => a.startsWith(`${name}=`));
+  return eq ? eq.slice(name.length + 1) : undefined;
+}
+
+export function runRenumberDecisions(argv) {
+  const vaultRaw = opt(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
+  if (!vaultRaw) { process.stderr.write('wendkeep renumber-decisions: no vault (--vault or OBSIDIAN_VAULT_PATH).\n'); process.exit(2); }
+  const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);
+  if (!existsSync(vaultBase)) { process.stderr.write(`wendkeep renumber-decisions: vault not found: ${vaultBase}\n`); process.exit(2); }
+
+  const apply = argv.includes('--apply');
+  const report = renumberDecisions(vaultBase, { apply });
+
+  if (argv.includes('--json')) { process.stdout.write(`${JSON.stringify(report, null, 2)}\n`); process.exit(0); }
+
+  process.stdout.write(`${report.total} decisão(ões) · ${report.renamed} a renomear${apply ? ` · ${report.filesTouched} arquivo(s) com links atualizados` : ''}\n`);
+  for (const p of report.plan.filter((x) => x.renamed)) {
+    process.stdout.write(`  ADR-${String(p.num).padStart(4, '0')}  ${p.from}\n              → ${p.to}\n`);
+  }
+  if (!apply) process.stdout.write('\nNada foi escrito (preview). Rode com --apply para renomear e atualizar os wikilinks.\n');
+  process.exit(0);
+}

package/src/skills-seed.mjs

@@ -16,6 +16,12 @@ const WORKFLOW = `# Loop a2 — o ciclo de trabalho do wendkeep
 Use ao começar qualquer mudança não-trivial. O loop mantém memória (vault) e prova
 (sensores) juntas, tudo linkado no grafo do Obsidian.
 
+<HARD-GATE>
+NÃO edite arquivos de código antes do passo 2 (Propose / \`wendkeep change new\`).
+Toda tarefa não-trivial passa pelo loop — planejar no chat e sair editando deixa o
+vault cego. Exceção única: mudança trivial (typo, 1 linha).
+</HARD-GATE>
+
 ## Os passos
 
 1. **Explore** — entenda o problema antes de propor. Leia o código/contexto relevante.
@@ -222,6 +228,12 @@ const WORKFLOW_EN = `# The a2 loop — wendkeep's work cycle
 Use it when starting any non-trivial change. The loop keeps memory (vault) and proof
 (sensors) together, wikilinked in the Obsidian graph.
 
+<HARD-GATE>
+Do NOT edit code files before step 2 (Propose / \`wendkeep change new\`).
+Every non-trivial task goes through the loop — planning in chat and editing right away
+leaves the vault blind. Single exception: a trivial change (typo, one line).
+</HARD-GATE>
+
 ## Steps
 
 1. **Explore** — understand the problem before proposing.
@@ -518,21 +530,24 @@ size of the problem>
 <verifiable criteria: for each requirement, the test that fails → passes>
 `;
 
+// As descriptions são o gatilho de ativação: o harness casa a description com o PEDIDO do
+// usuário ("implementa X", "corrige Y"), não com abstrações ("mudança não-trivial"). Gatilhos
+// concretos + instrução imperativa = a skill dispara sozinha (paridade Superpowers).
 const WK_SKILLS_PT = [
-  skill('wk-workflow', 'Use ao começar qualquer mudança não-trivial — orquestra o loop a2 (explore, propose, apply, verify, archive) nos comandos wendkeep.', WORKFLOW),
+  skill('wk-workflow', 'Use SEMPRE que o usuário pedir para implementar, criar, corrigir, refatorar, adicionar ou alterar código — qualquer tarefa de código não-trivial. Invoque ANTES de editar qualquer arquivo: orquestra o loop a2 (wendkeep change new → tarefas → verify → archive) e registra tudo no vault.', WORKFLOW),
   skill('wk-tdd', 'Use ao implementar qualquer comportamento — Red/Green/Refactor com testes que discriminam (derivados do spec, litmus não-raso, adequação).', TDD),
-  skill('wk-debugging', 'Use quando algo falha ou quebra — depuração sistemática por hipótese antes de corrigir.', DEBUGGING),
-  skill('wk-brainstorming', 'Use quando a ideia ainda é vaga — vira design aprovado, com closure gate e tabela out-of-scope, antes de código.', BRAINSTORMING, [{ name: 'design-template.md', content: DESIGN_TEMPLATE_PT }]),
-  skill('wk-planning', 'Use após um design aprovado — decompõe em plano de tarefas TDD bite-sized.', PLANNING, [{ name: 'plan-template.md', content: PLAN_TEMPLATE_PT }]),
+  skill('wk-debugging', 'Use quando algo falha, quebra, dá erro ou regride — depuração sistemática por hipótese antes de corrigir.', DEBUGGING),
+  skill('wk-brainstorming', 'Use quando a ideia ainda é vaga ou o usuário quer discutir/planejar uma feature (inclusive em plan mode) — vira design aprovado, com closure gate e tabela out-of-scope, antes de código.', BRAINSTORMING, [{ name: 'design-template.md', content: DESIGN_TEMPLATE_PT }]),
+  skill('wk-planning', 'Use após um design aprovado ou um plano aceito (inclusive plan mode) — decompõe em plano de tarefas TDD bite-sized e registra na change ativa.', PLANNING, [{ name: 'plan-template.md', content: PLAN_TEMPLATE_PT }]),
   skill('wk-verify', 'Use no verify deep — passe independente read-only (autor≠verificador) que re-deriva a cobertura do spec e grava verdict.json.', VERIFY, [{ name: 'spec-reviewer-prompt.md', content: REVIEWER_PROMPT_PT }, { name: 'verdict-template.json', content: VERDICT_TEMPLATE }]),
 ];
 
 const WK_SKILLS_EN = [
-  skill('wk-workflow', 'Use when starting any non-trivial change — orchestrates the a2 loop (explore, propose, apply, verify, archive) over the wendkeep commands.', WORKFLOW_EN),
+  skill('wk-workflow', 'Use WHENEVER the user asks to implement, create, fix, refactor, add or change code — any non-trivial coding task. Invoke BEFORE editing any file: it orchestrates the a2 loop (wendkeep change new → tasks → verify → archive) and records everything in the vault.', WORKFLOW_EN),
   skill('wk-tdd', 'Use when implementing any behaviour — Red/Green/Refactor with tests that discriminate (spec-derived, non-shallow litmus, adequacy).', TDD_EN),
-  skill('wk-debugging', 'Use when something fails or breaks — systematic hypothesis-driven debugging before fixing.', DEBUGGING_EN),
-  skill('wk-brainstorming', 'Use when the idea is still vague — turns it into an approved design, with a closure gate and out-of-scope table, before code.', BRAINSTORMING_EN, [{ name: 'design-template.md', content: DESIGN_TEMPLATE_EN }]),
-  skill('wk-planning', 'Use after an approved design — decomposes it into a bite-sized TDD task plan.', PLANNING_EN, [{ name: 'plan-template.md', content: PLAN_TEMPLATE_EN }]),
+  skill('wk-debugging', 'Use when something fails, breaks, errors or regresses — systematic hypothesis-driven debugging before fixing.', DEBUGGING_EN),
+  skill('wk-brainstorming', 'Use when the idea is still vague or the user wants to discuss/plan a feature (plan mode included) — turns it into an approved design, with a closure gate and out-of-scope table, before code.', BRAINSTORMING_EN, [{ name: 'design-template.md', content: DESIGN_TEMPLATE_EN }]),
+  skill('wk-planning', 'Use after an approved design or an accepted plan (plan mode included) — decomposes it into a bite-sized TDD task plan recorded in the active change.', PLANNING_EN, [{ name: 'plan-template.md', content: PLAN_TEMPLATE_EN }]),
   skill('wk-verify', 'Use in verify deep — an independent read-only pass (author≠verifier) that re-derives spec coverage and writes verdict.json.', VERIFY_EN, [{ name: 'spec-reviewer-prompt.md', content: REVIEWER_PROMPT_EN }, { name: 'verdict-template.json', content: VERDICT_TEMPLATE }]),
 ];
 
@@ -545,20 +560,22 @@ export const WK_SKILLS = WK_SKILLS_PT;
 // Seed each skill into <brainDir>/skills/<name>/ if absent (non-destructive): SKILL.md plus any
 // bundled template/prompt files. Existing files are never overwritten, so re-seeding an older
 // install just fills in the new template files alongside its SKILL.md.
-export function seedWkSkills(brainDir, localeId = 'pt-BR') {
+// { refresh: true } (sync-defs --reseed) SOBRESCREVE as wk-* com os seeds atuais — é como um
+// vault existente recebe descriptions/HARD-GATE novos (edições manuais nas wk-* são perdidas).
+export function seedWkSkills(brainDir, localeId = 'pt-BR', { refresh = false } = {}) {
   const created = [];
   for (const s of wkSkills(localeId)) {
     const dir = join(brainDir, 'skills', s.name);
     mkdirSync(dir, { recursive: true });
-    const writeIfAbsent = (name, content) => {
+    const write = (name, content) => {
       const f = join(dir, name);
-      if (!existsSync(f)) {
+      if (refresh || !existsSync(f)) {
         writeFileSync(f, content, 'utf8');
         created.push(f);
       }
     };
-    writeIfAbsent('SKILL.md', s.body);
-    for (const file of s.files || []) writeIfAbsent(file.name, file.content);
+    write('SKILL.md', s.body);
+    for (const file of s.files || []) write(file.name, file.content);
   }
   return created;
 }

package/src/sync-defs.mjs

@@ -7,6 +7,8 @@
 // cross-platform robustness.
 import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
+import { seedWkSkills } from './skills-seed.mjs';
+import { getLocale } from '../hooks/locale.mjs';
 
 // Managed AGENTS.md section (0.8.0): the agent-agnostic distribution channel. Codex, Amp,
 // Cursor, Zed et al. read AGENTS.md — one file covers them all. Only the content between
@@ -114,6 +116,12 @@ export function runSyncDefs(argv) {
   }
   const vaultBase = isAbsolute(base) ? base : resolve(process.cwd(), base);
   const projectPath = resolve(project || process.cwd());
+  // --reseed (0.31.0): sobrescreve as wk-* de .brain/skills com os seeds da versão instalada
+  // ANTES de copiar — é como um vault existente recebe descriptions/HARD-GATE novos.
+  if (argv.includes('--reseed')) {
+    const n = seedWkSkills(join(vaultBase, '.brain'), getLocale(vaultBase).id, { refresh: true });
+    process.stdout.write(`wendkeep sync-defs: ${n.length} arquivo(s) de skill re-semeados em .brain/skills\n`);
+  }
   const r = syncDefs(vaultBase, projectPath);
   process.stdout.write(
     `wendkeep sync-defs: ${r.agents.length} agent(s) -> .codex/agents, ${r.skills.length} skill(s) -> .claude/skills\n`,

package/src/taxonomy.mjs

@@ -45,10 +45,16 @@ export const HOOK_FILES = [
   'session-backfill.mjs',
   'import-sessions.mjs',
   'decision-capture.mjs',
+  'renumber-decisions.mjs',
   'subagent-stop.mjs',
   'task-log.mjs',
   'vault-health.mjs',
   'understand-inject.mjs',
+  'change-context.mjs',
+  'change-warn.mjs',
+  'change-guard.mjs',
+  'change-nag.mjs',
+  'plan-capture.mjs',
 ];
 
 // Hook scripts that are safe to invoke directly via `wendkeep hook <name>`.
@@ -67,6 +73,11 @@ export const RUNNABLE_HOOKS = [
   'brain-reindex',
   'vault-health',
   'understand-inject',
+  'change-context',
+  'change-warn',
+  'change-guard',
+  'change-nag',
+  'plan-capture',
 ];
 
 // The MCP server entry wendkeep wires into .mcp.json so the agent can read/write the
@@ -106,6 +117,27 @@ export function hookCommand(name) {
   return `npx wendkeep hook ${name}`;
 }
 
+// Forma node-direta do comando de hook: 1 processo (~100-250ms) em vez dos 3 do npx (cold-start
+// de segundos no Windows). Usada pelos hooks de ALTA FREQUÊNCIA (por prompt / por tool-call)
+// quando o projeto tem wendkeep instalado localmente; o init decide (hookCommandFor).
+export function hookCommandLocal(name) {
+  return `node node_modules/wendkeep/hooks/${name}.mjs`;
+}
+
+// Hooks do lifecycle de change (0.31.0) — enforcement do loop a2. Nudges (contexto/aviso/
+// cobrança/captura de plano) e gate (deny/ask no Bash). Separados em dois grupos para
+// preservar a opção futura de gates opt-in; hoje o init wira TODOS por default.
+// preferLocal: alta frequência → invocação node-direta quando houver instalação local.
+export const CHANGE_NUDGE_HOOKS = [
+  { event: 'UserPromptSubmit', matcher: null, name: 'change-context', timeout: 15, order: 10, preferLocal: true, statusMessage: 'wendkeep: change ping' },
+  { event: 'PostToolUse', matcher: 'Edit|Write|MultiEdit', name: 'change-warn', timeout: 10, order: 10, preferLocal: true, statusMessage: 'wendkeep: change warn' },
+  { event: 'PostToolUse', matcher: 'ExitPlanMode', name: 'plan-capture', timeout: 15, order: 10, preferLocal: true, statusMessage: 'wendkeep: capturing approved plan' },
+  { event: 'Stop', matcher: null, name: 'change-nag', timeout: 15, order: 10, preferLocal: true, statusMessage: 'wendkeep: open tasks check' },
+];
+export const CHANGE_GATE_HOOKS = [
+  { event: 'PreToolUse', matcher: 'Bash', name: 'change-guard', timeout: 10, order: 10, preferLocal: true, statusMessage: 'wendkeep: change gate' },
+];
+
 // --- companion plugins / MCP --------------------------------------------------
 // Optional tools wendkeep init can pin alongside the vault. Each is wired through
 // the MOST agent-agnostic mechanism it supports; the Claude Code plugin entry