wendkeep 0.38.3 → 0.40.0

package/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.40.0] — 2026-07-16
+
+### Added
+
+- `parseTasks` captura **todos** os `[req:]` de uma tarefa em `reqs: string[]` (`req` permanece
+  como alias do primeiro, retrocompatível). Antes, só o primeiro entrava no pacote de
+  verificação e os demais sumiam sem aviso.
+- Heading de requisito aceita ID puro (`### Requisito: GATE-1`) como identidade, além do
+  formato preferido `### Requisito: <ID> — <nome>`. Diagnóstico de requisito órfão agora
+  ensina o formato esperado com exemplo concreto.
+- `findProjectRoot`: `wendkeep verify` executado de um subdiretório sobe a árvore até achar
+  `wendkeep.sensors.json`/`.wendkeep.json` (à la `.git`); `--project` continua autoritativo.
+- `--help`/`-h` universal: qualquer subcomando com `--help` imprime a ajuda e sai com 0,
+  interceptado antes da resolução de vault — nunca executa o comando.
+
+### Fixed
+
+- Regex de ID de requisito unificada entre tarefa e spec (`REQ_ID_RE_SRC`): IDs
+  multi-segmento (`API-AUTH-2`) agora são reconhecidos também nas tarefas.
+- `wendkeep verify` distingue `wendkeep.sensors.json` ausente (aviso com path + dica
+  `--project`) de JSON inválido (erro alto com a mensagem do parse). Antes, ambos viravam
+  "sensor não definido" para todos os sensores.
+- `wendkeep import` com flag desconhecida agora falha com exit 2 citando a flag, em vez de
+  cair no default destrutivo `--source all` (que chegou a importar 78 sessões sem querer).
+- Templates seed (skills de workflow pt/en) documentam o formato de heading de requisito e o
+  suporte a múltiplos `[req:]` por tarefa.
+
+## [0.39.0] — 2026-07-13
+
+### Added
+
+- Configuração provider-neutral `.wendkeep.json`, descoberta do diretório da sessão para os
+  pais, permitindo que Codex e Claude Code resolvam o mesmo vault sem variável global do
+  Windows. Caminhos relativos ao projeto e caminhos absolutos são suportados.
+- Identidade estável `projectId`, espelhada em `.brain/PROJECT.json`; vínculos que apontem
+  para o vault de outro projeto são rejeitados antes de qualquer gravação.
+- `doctor` informa caminho e origem do vínculo efetivo. Comandos CLI executados dentro do
+  projeto também descobrem o vault local, mantendo `--vault` como override explícito.
+
+### Changed
+
+- `wendkeep init` cria o vínculo projeto→vault de forma idempotente e adota instalações
+  antigas registradas em `.claude/settings.json`, sem mover ou dividir o histórico.
+- Um vínculo local sempre vence um `OBSIDIAN_VAULT_PATH` herdado pelo processo. A variável
+  permanece apenas para compatibilidade de comandos manuais legados.
+
+### Fixed
+
+- Hooks do Codex deixam de gravar sessões no vault doméstico `~/wendkeep-vault` quando o
+  processo não recebe o ambiente privado do Claude Code. Sem vínculo local ou payload
+  explícito, o hook agora falha de modo seguro, emite diagnóstico e não cria arquivos.
+- Projetos simultâneos deixam de compartilhar acidentalmente sessões, mudanças e grafo por
+  causa de uma variável global de usuário apontando para um único vault.
+
+### Migration
+
+- Após atualizar, execute uma vez `wendkeep init --project . --vault <vault> --yes`, depois
+  `wendkeep sync-defs --project . --reseed` e `wendkeep doctor --project .`; reinicie Codex e
+  Claude Code para recarregar os artefatos gerados.
+
 ## [0.38.3] — 2026-07-12
 
 ### Fixed

package/README.md

@@ -60,7 +60,7 @@ npx wendkeep init
 `wendkeep init` is interactive and **idempotent**. It will:
 
 1. Create the vault folder taxonomy and a templated `README.md` (default vault: `<project>/.<project-name>-vault`, e.g. `.MyApp-vault`; override with `--vault`).
-2. **Merge** the three session hooks and `OBSIDIAN_VAULT_PATH` into `.claude/settings.json` — without clobbering your existing settings (a `.bak` is saved; an unparseable file is left untouched and a `.new` is written for you to merge).
+2. Write a provider-neutral **`.wendkeep.json`** binding at the project root and a matching `.brain/PROJECT.json` marker in the vault. Codex and Claude Code discover the same vault from their session `cwd`; no machine-global environment variable is required. Existing `.claude/settings.json` registrations are adopted automatically.
 3. Add the **`wendkeep-vault`** MCP server to `.mcp.json` so the agent can read/write the vault. Skip with `--no-mcp` — e.g. when the agent already has a vault MCP. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
 4. Offer to pin **companion** plugins/MCP (multi-choice; only `context-mode` pre-checked). Each is wired the most agent-agnostic way it supports:
    - **`context-mode`** — context optimizer + FTS5 memory, as a `.mcp.json` MCP server (any agent). The recommended default.
@@ -96,15 +96,32 @@ npx wendkeep init --no-companions --no-mcp --yes              # zero companions,
 
 Then open the vault in Obsidian, send a test prompt in your agent, and confirm a note appears under `02-Sessões/…` (or `02-Sessions/…` for an `en` vault).
 
+### Project isolation
+
+Each project owns a `.wendkeep.json` containing a stable `projectId` and its vault path.
+Relative paths (for example `.NutriGymBrain`) are resolved from the project root; absolute
+paths are also supported. Hooks search upward from the agent's `cwd`, so nested packages use
+the nearest binding. The vault carries the same identity in `.brain/PROJECT.json`; a mismatch
+is rejected before any session is written. If no binding exists, hooks fail closed and never
+create the historical `~/wendkeep-vault` fallback.
+
+`OBSIDIAN_VAULT_PATH` remains only as legacy/manual CLI compatibility. It is not used to
+route automatic Codex or Claude hooks and a project-local binding overrides an inherited
+machine value.
+
 ## Updating
 
-Because the hooks live inside the installed package (settings.json calls `npx wendkeep hook <name>`), upgrading is just:
+Because the hooks live inside the installed package, upgrade the package and re-run the
+idempotent init. The init step creates/migrates the provider-neutral project binding:
 
 ```bash
-npm update wendkeep
+npm install --save-dev wendkeep@latest
+npx --no-install wendkeep init --project . --vault <your-vault> --yes
+npx --no-install wendkeep sync-defs --project . --reseed
+npx --no-install wendkeep doctor --project .
 ```
 
-No re‑copying, no snapshot to re‑sync — the package is the single source of truth.
+Restart Codex and Claude Code after reseeding their generated skills.
 
 ## Commands
 

package/README.pt-BR.md

@@ -58,7 +58,7 @@ npx wendkeep init
 O `wendkeep init` é interativo e **idempotente**. Ele:
 
 1. Cria a taxonomia de pastas do cofre e um `README.md` templado (cofre padrão: `<projeto>/.<nome-do-projeto>-vault`, ex.: `.MeuApp-vault`; sobrescreva com `--vault`).
-2. **Mescla** os três hooks de sessão e o `OBSIDIAN_VAULT_PATH` no `.claude/settings.json` — sem atropelar suas configs (salva um `.bak`; arquivo ilegível fica intocado e um `.new` é escrito pra você mesclar).
+2. Grava um vínculo provider-neutral **`.wendkeep.json`** na raiz do projeto e o marcador correspondente `.brain/PROJECT.json` no cofre. Codex e Claude Code descobrem o mesmo vault pelo `cwd` da sessão, sem variável global do Windows. Registros antigos em `.claude/settings.json` são adotados automaticamente.
 3. Adiciona o servidor MCP **`wendkeep-vault`** ao `.mcp.json` pro agente ler/escrever o cofre. Pule com `--no-mcp` — ex.: quando o agente já tem um MCP de cofre. (`--no-mcp` pula *só o MCP do próprio wendkeep*; os MCPs de companion seguem `--companions`.)
 4. Oferece fixar plugins/MCP **companion** (múltipla escolha; **nenhum** pré-marcado). Cada um é wirado do jeito mais agnóstico que suporta:
    - **`context-mode`** — otimizador de contexto + memória FTS5, como servidor MCP no `.mcp.json` (qualquer agente).
@@ -94,15 +94,31 @@ npx wendkeep init --no-companions --no-mcp --yes              # zero companions,
 
 Depois abra o cofre no Obsidian, mande um prompt de teste no seu agente e confirme que uma nota aparece em `02-Sessões/…` (ou `02-Sessions/…` num cofre `en`).
 
+### Isolamento por projeto
+
+Cada projeto possui um `.wendkeep.json` com `projectId` estável e caminho do vault. Caminhos
+relativos, como `.NutriGymBrain`, partem da raiz do projeto; caminhos absolutos também são
+aceitos. Os hooks procuram o vínculo mais próximo subindo a partir do `cwd`. O vault guarda a
+mesma identidade em `.brain/PROJECT.json`, e uma divergência bloqueia a escrita. Sem vínculo,
+os hooks falham de modo seguro e nunca criam o antigo fallback `~/wendkeep-vault`.
+
+`OBSIDIAN_VAULT_PATH` permanece somente como compatibilidade legada para comandos manuais.
+Ele não roteia hooks automáticos do Codex ou Claude, e o vínculo local prevalece sobre uma
+variável herdada da máquina.
+
 ## Atualizar
 
-Como os hooks vivem dentro do pacote instalado (o settings.json chama `npx wendkeep hook <name>`), atualizar é só:
+Como os hooks vivem dentro do pacote instalado, atualize e rode novamente o `init`
+idempotente. Essa etapa cria ou migra o vínculo provider-neutral:
 
 ```bash
-npm update wendkeep
+npm install --save-dev wendkeep@latest
+npx --no-install wendkeep init --project . --vault <seu-vault> --yes
+npx --no-install wendkeep sync-defs --project . --reseed
+npx --no-install wendkeep doctor --project .
 ```
 
-Sem recopiar, sem snapshot pra re‑sincronizar — o pacote é a única fonte da verdade.
+Reinicie Codex e Claude Code depois de resemear as skills geradas.
 
 ## Comandos
 

package/bin/wendkeep.mjs

@@ -102,8 +102,39 @@ function runHook(name) {
   process.exit(r.status ?? 0);
 }
 
+function optionValue(argv, name) {
+  const index = argv.indexOf(name);
+  if (index >= 0) return argv[index + 1] || '';
+  return argv.find((item) => item.startsWith(`${name}=`))?.slice(name.length + 1) || '';
+}
+
+async function preferProjectVault(argv) {
+  // Existing command modules still consume OBSIDIAN_VAULT_PATH internally. Populate it
+  // only inside this CLI process from the provider-neutral project binding, overriding
+  // any inherited machine-global value. An explicit --vault remains authoritative.
+  if (optionValue(argv, '--vault')) return;
+  try {
+    const { resolveProjectVault } = await import('../src/project-vault.mjs');
+    const resolved = resolveProjectVault({ startDir: optionValue(argv, '--project') || process.cwd() });
+    process.env.OBSIDIAN_VAULT_PATH = resolved.base;
+  } catch {
+    // Backward-compatible manual CLI behavior: individual commands still explain
+    // --vault / legacy env when no project binding exists. Hooks do not use this path.
+  }
+}
+
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
+  // Universal --help: any subcommand with --help/-h prints usage and never executes.
+  // Intercepted BEFORE vault resolution so it works anywhere — help must never depend
+  // on project state, and no command may treat --help as a runnable default.
+  if (cmd && (rest.includes('--help') || rest.includes('-h'))) {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
+  if (cmd && !['init', 'hook', '--version', '-v', '--help', '-h', 'help'].includes(cmd)) {
+    await preferProjectVault(rest);
+  }
   switch (cmd) {
     case 'init': {
       const { runInit } = await import('../src/init.mjs');

package/hooks/change-core.mjs

@@ -4,7 +4,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { ensureDir, wikilinkFromRel, monthFolderRelFromDateStr } from './obsidian-common.mjs';
-import { parseSpecsList, promoteSpecs, discoverSpecDeltas, tasksHashOf, captureSpecBaseline } from './spec-core.mjs';
+import { parseSpecsList, promoteSpecs, discoverSpecDeltas, tasksHashOf, captureSpecBaseline, REQ_ID_RE_SRC } from './spec-core.mjs';
 import { getLocale } from './locale.mjs';
 
 export const ARCHIVE_DIR = '_arquivo';
@@ -161,18 +161,18 @@ export function parseTasks(md) {
   const tasks = [];
   const re = /^-\s+\[( |x)\]\s+(\S+)\s+(.*)$/gm;
   const sensorRe = /\[sensor:\s*([\w.-]+)\]/;
-  const reqRe = /\[req:\s*([A-Z][A-Z0-9]*-\d+)\]/;
+  const reqReG = new RegExp(`\\[req:\\s*(${REQ_ID_RE_SRC})\\]`, 'g');
   let m;
   while ((m = re.exec(String(md))) !== null) {
     let text = m[3].trim();
     const sm = text.match(sensorRe);
-    const rm = text.match(reqRe);
+    const reqs = [...text.matchAll(reqReG)].map((r) => r[1]);
     const sensor = sm ? sm[1] : undefined;
-    const req = rm ? rm[1] : undefined;
     if (sm) text = text.replace(sensorRe, '');
-    if (rm) text = text.replace(reqRe, '');
+    if (reqs.length) text = text.replace(reqReG, '');
     text = text.replace(/\s+/g, ' ').trim();
-    tasks.push({ id: m[2], text, done: m[1] === 'x', ...(sensor ? { sensor } : {}), ...(req ? { req } : {}) });
+    // `req` stays as alias of the first id — older consumers keep working.
+    tasks.push({ id: m[2], text, done: m[1] === 'x', ...(sensor ? { sensor } : {}), ...(reqs.length ? { req: reqs[0], reqs } : {}) });
   }
   return tasks;
 }
@@ -419,7 +419,7 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
   }
 
   let reqIds = [];
-  try { reqIds = [...new Set(parseTasks(readFileSync(join(src, 'tarefas.md'), 'utf8')).map((t) => t.req).filter(Boolean))]; } catch { /* sem tarefas */ }
+  try { reqIds = [...new Set(parseTasks(readFileSync(join(src, 'tarefas.md'), 'utf8')).flatMap((t) => t.reqs ?? []))]; } catch { /* sem tarefas */ }
 
   ensureDir(join(vaultBase, chDir, ARCHIVE_DIR));
   try {

package/hooks/harness-doctor.mjs

@@ -41,7 +41,7 @@ export function checkHarness(vaultBase, projectRoot) {
     let tasks = [];
     let tarefasMd = '';
     try { tarefasMd = readFileSync(join(dir, 'tarefas.md'), 'utf8'); tasks = parseTasks(tarefasMd); } catch { /* sem tarefas */ }
-    const reqIds = [...new Set(tasks.map((t) => t.req).filter(Boolean))];
+    const reqIds = [...new Set(tasks.flatMap((t) => t.reqs ?? []))];
     const effective = buildEffectiveRequirementPackage(vaultBase, dir, reqIds);
     errors.push(...effective.errors.map((e) => `${name}: spec efetiva inválida: ${e}`));
     if (effective.missing.length) errors.push(`req órfão em ${name}: ${effective.missing.map((id) => `[req:${id}]`).join(', ')} não existe na spec efetiva`);

package/hooks/obsidian-common.mjs

@@ -2,9 +2,10 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'fs';
 import { basename, dirname, join, relative } from 'path';
 import { getLocale } from './locale.mjs';
+import { resolveProjectVault } from '../src/project-vault.mjs';
 
-// Neutral fallback only. The vault is normally resolved from the
-// OBSIDIAN_VAULT_PATH env var (set by `wendkeep init`) via getVaultBase() below.
+// Deprecated export kept for consumers that imported it before 0.39.0. Automatic
+// hooks never use this fallback: an unbound project fails closed.
 export const DEFAULT_VAULT_BASE = join(
   process.env.USERPROFILE || process.env.HOME || process.cwd(),
   'wendkeep-vault',
@@ -31,19 +32,12 @@ export function writeHookOutput(payload = {}) {
   process.stdout.write(JSON.stringify(payload));
 }
 
-// Resolve the vault and report WHERE the path came from, so callers can react to
-// an unconfigured install instead of silently writing to the home fallback.
-//   env     -> OBSIDIAN_VAULT_PATH (set by `wendkeep init`)
-//   payload -> obsidian_vault_path from the hook's JSON input
-//   default -> DEFAULT_VAULT_BASE (~/wendkeep-vault) — a phantom vault nobody opened
+// Resolve from explicit hook payload or the nearest project-local binding. A legacy
+// `.claude/settings.json` registration is accepted as a migration bridge so Codex can
+// discover projects initialized by older WendKeep versions. Global process env and the
+// historical home fallback are intentionally excluded to prevent cross-project writes.
 export function resolveVault(input = {}) {
-  if (process.env.OBSIDIAN_VAULT_PATH) {
-    return { base: process.env.OBSIDIAN_VAULT_PATH, source: 'env' };
-  }
-  if (input && input.obsidian_vault_path) {
-    return { base: input.obsidian_vault_path, source: 'payload' };
-  }
-  return { base: DEFAULT_VAULT_BASE, source: 'default' };
+  return resolveProjectVault({ input });
 }
 
 export function getVaultBase(input = {}) {
@@ -60,16 +54,15 @@ export function debugLog(...args) {
   process.stderr.write(`[wendkeep] ${text}\n`);
 }
 
-// Warn loudly (stderr) when the vault resolved to the home fallback — i.e. neither
-// OBSIDIAN_VAULT_PATH nor a payload path was provided. Without this the hooks write
-// notes into ~/wendkeep-vault with zero signal that the install is misconfigured.
-// Returns the resolution source so callers can branch if they want.
+// Migration warning for projects that are still discovered through Claude's local
+// settings. Missing bindings throw before this point and are handled by each hook's
+// fail-closed top-level catch.
 export function warnIfDefaultVault(input = {}) {
   const { base, source } = resolveVault(input);
-  if (source === 'default') {
+  if (source === 'legacy-project-settings') {
     process.stderr.write(
-      `[wendkeep] WARNING: OBSIDIAN_VAULT_PATH não definido — gravando no fallback "${base}". ` +
-        'Rode `wendkeep init` ou defina OBSIDIAN_VAULT_PATH apontando ao seu vault Obsidian.\n',
+      `[wendkeep] Configuração legada do vault detectada em .claude/settings.json ("${base}"). `
+        + 'Rode `wendkeep init --yes` para criar .wendkeep.json; Codex e Claude continuarão no mesmo vault.\n',
     );
   }
   return source;

package/hooks/sensors-core.mjs

@@ -2,15 +2,37 @@
 // Pure-ish: `spawn` is injectable so runs are testable without a shell. Config lives
 // at the PROJECT ROOT (wendkeep.sensors.json); evidence lives per-change in the vault.
 import { spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 
 export function loadSensors(projectRoot, file = 'wendkeep.sensors.json') {
+  return loadSensorsDetailed(projectRoot, file).sensors;
+}
+
+// Missing config and broken config are different failures: absent file usually means
+// wrong cwd (subdirectory), broken JSON means the config itself needs fixing. Collapsing
+// both into [] made every sensor report "sensor não definido" — a misleading diagnosis.
+export function loadSensorsDetailed(projectRoot, file = 'wendkeep.sensors.json') {
+  const path = join(projectRoot, file);
+  if (!existsSync(path)) return { sensors: [], missing: true, error: null, path };
   try {
-    const data = JSON.parse(readFileSync(join(projectRoot, file), 'utf8'));
-    return Array.isArray(data.sensors) ? data.sensors : [];
-  } catch {
-    return [];
+    const data = JSON.parse(readFileSync(path, 'utf8'));
+    return { sensors: Array.isArray(data.sensors) ? data.sensors : [], missing: false, error: null, path };
+  } catch (e) {
+    return { sensors: [], missing: false, error: e.message, path };
+  }
+}
+
+// Climb the directory tree looking for a project marker (wendkeep.sensors.json or
+// .wendkeep.json), like git does with .git — shells in agent harnesses keep their cwd
+// across commands, so verify is often run from a subdirectory.
+export function findProjectRoot(startDir) {
+  let dir = resolve(startDir);
+  for (;;) {
+    if (existsSync(join(dir, 'wendkeep.sensors.json')) || existsSync(join(dir, '.wendkeep.json'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
   }
 }
 

package/hooks/spec-core.mjs

@@ -22,15 +22,29 @@ export const MANAGED_SPEC_MARKER = '<!-- wendkeep:managed-spec — generated fro
 // Parse is BILINGUAL always (mixed vaults never break); rendering follows the vault locale.
 const REQ_RE = /^### (?:Requisito|Requirement):\s*(.+)$/gm;
 
+// Single source of truth for requirement-id shape — task tags ([req:ID]) and spec
+// headings MUST agree, or coverage silently misses (multi-segment ids like API-AUTH-2).
+export const REQ_ID_RE_SRC = '[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\\d+';
+
+// Orphan diagnostics must teach the fix, not just name the ids — the heading format
+// is the most common cause and lives only here.
+export function formatOrphanReqs(ids) {
+  const list = ids.join(', ');
+  const ex = ids[0] || 'GATE-1';
+  return `requisito(s) órfão(s) na spec efetiva: ${list} — heading esperado no spec.md da change: "### Requisito: ${ex} — <nome>" (ou só "### Requisito: ${ex}")`;
+}
+
 export function parseRequirements(md) {
   const text = String(md);
   const matches = [...text.matchAll(REQ_RE)];
   const reqs = [];
   for (let i = 0; i < matches.length; i += 1) {
     const raw = matches[i][1].trim();
-    // Identity is the ID (e.g. GATE-1) when the heading is "<ID> — <nome>"; else the whole text.
-    const idM = raw.match(/^([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+)\s*—\s*(.+)$/);
-    const id = idM ? idM[1] : null;
+    // Identity is the ID (e.g. GATE-1) when the heading is "<ID> — <nome>" or a bare
+    // "<ID>"; else the whole text. Bare ids keep specs writable without the em-dash.
+    const idM = raw.match(new RegExp(`^(${REQ_ID_RE_SRC})\\s*—\\s*(.+)$`));
+    const bare = idM ? null : raw.match(new RegExp(`^(${REQ_ID_RE_SRC})$`));
+    const id = idM ? idM[1] : bare ? bare[1] : null;
     const name = idM ? idM[2].trim() : raw;
     const start = matches[i].index + matches[i][0].length;
     const end = i + 1 < matches.length ? matches[i + 1].index : text.length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.38.3",
+  "version": "0.40.0",
   "description": "A persistent-memory harness for AI coding agents on your Obsidian vault: turn-by-turn session capture plus a native, zero-dependency spec→change→verify→archive loop (sensor-gated, independent verdict, mutation discrimination). Local-first, agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "check": "node --check bin/wendkeep.mjs && node --check src/init.mjs && node --check src/doctor.mjs",
+    "check": "node --check bin/wendkeep.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/project-vault.mjs",
     "test": "node --test",
     "release": "node scripts/release.mjs",
     "release:dry": "node scripts/release.mjs --dry-run"
@@ -46,6 +46,6 @@
     "url": "https://github.com/rogersialves/wendkeep/issues"
   },
   "devDependencies": {
-    "wendkeep": "^0.38.2"
+    "wendkeep": "^0.39.0"
   }
 }

package/src/change.mjs

@@ -17,7 +17,7 @@ import {
   scaffoldPlaceholders,
 } from '../hooks/change-core.mjs';
 import { evaluateGate, requiredSensors } from '../hooks/sensors-core.mjs';
-import { buildEffectiveRequirementPackage, evaluateVerdict, tasksHashOf, parseSpecsList, parseDelta, parseRequirements, applyDelta, validateSpecImpact } from '../hooks/spec-core.mjs';
+import { buildEffectiveRequirementPackage, evaluateVerdict, formatOrphanReqs, tasksHashOf, parseSpecsList, parseDelta, parseRequirements, applyDelta, validateSpecImpact } from '../hooks/spec-core.mjs';
 import { getNextAdrNumber, readControl, readSessionRegistry, upsertSessionRegistry } from '../hooks/obsidian-common.mjs';
 import { getLocale } from '../hooks/locale.mjs';
 
@@ -147,13 +147,13 @@ export function runChange(argv) {
     process.stdout.write(`specs: ${specs.join(', ') || '(nenhuma)'}\n`);
     process.stdout.write(`tarefas: ${done} done / ${tasks.length - done} open\n`);
     for (const t of tasks) {
-      process.stdout.write(`  [${t.done ? 'x' : ' '}] ${t.id} ${t.text}${t.req ? ` [req:${t.req}]` : ''}${t.sensor ? ` [sensor:${t.sensor}]` : ''}\n`);
+      process.stdout.write(`  [${t.done ? 'x' : ' '}] ${t.id} ${t.text}${(t.reqs ?? []).map((r) => ` [req:${r}]`).join('')}${t.sensor ? ` [sensor:${t.sensor}]` : ''}\n`);
     }
     let evidence = null;
     try { evidence = JSON.parse(readFileSync(join(dir, 'evidencia.json'), 'utf8')); } catch { /* sem evidência */ }
     if (evidence) for (const e of evidence) process.stdout.write(`  ${e.status === 'green' ? '✓' : '✗'} ${e.id} (${e.severity || 'critical'})\n`);
     else process.stdout.write('evidencia: ausente\n');
-    const reqIds = [...new Set(tasks.map((t) => t.req).filter(Boolean))];
+    const reqIds = [...new Set(tasks.flatMap((t) => t.reqs ?? []))];
     const effective = buildEffectiveRequirementPackage(vaultBase, dir, reqIds);
     if (effective.errors.length || effective.missing.length) {
       process.stdout.write(`spec efetiva: inválida (${[...effective.errors, ...effective.missing.map((id) => `req órfão ${id}`)].join('; ')})\n`);
@@ -239,10 +239,10 @@ export function runChange(argv) {
           return { ok: false, failing: ['evidência stale (tarefas.md mudou desde o último verify) — rode `wendkeep verify` de novo'] };
         }
       }
-      const reqIds = [...new Set(tasks.map((t) => t.req).filter(Boolean))];
+      const reqIds = [...new Set(tasks.flatMap((t) => t.reqs ?? []))];
       const effective = buildEffectiveRequirementPackage(vaultBase, dir, reqIds);
       if (effective.errors.length) return { ok: false, failing: [`spec efetiva inválida: ${effective.errors.join('; ')}`] };
-      if (effective.missing.length) return { ok: false, failing: [`requisito(s) órfão(s) na spec efetiva: ${effective.missing.join(', ')}`] };
+      if (effective.missing.length) return { ok: false, failing: [formatOrphanReqs(effective.missing)] };
       let evidence = [];
       try { evidence = JSON.parse(readFileSync(join(dir, 'evidencia.json'), 'utf8')); } catch { /* no evidence */ }
       const s = evaluateGate(evidence, required);

package/src/doctor.mjs

@@ -2,10 +2,11 @@
 // harness integrity check (hooks/harness-doctor.mjs). Exits 1 on any error.
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { checkHarness } from '../hooks/harness-doctor.mjs';
 import { checkSyncDefs } from './sync-defs.mjs';
+import { resolveProjectVault } from './project-vault.mjs';
 
 export function runDoctor(argv) {
   const here = dirname(fileURLToPath(import.meta.url));
@@ -23,19 +24,28 @@ export function runDoctor(argv) {
     else passthrough.push(a);
   }
 
-  const env = { ...process.env };
-  if (vault) env.OBSIDIAN_VAULT_PATH = isAbsolute(vault) ? vault : resolve(process.cwd(), vault);
-  if (!env.OBSIDIAN_VAULT_PATH) {
-    process.stderr.write('wendkeep doctor: no vault. Pass --vault <path> or set OBSIDIAN_VAULT_PATH.\n');
+  const projectRoot = resolve(project || process.cwd());
+  let resolution;
+  try {
+    resolution = resolveProjectVault({
+      startDir: projectRoot,
+      explicitVault: vault || '',
+      validateIdentity: !vault,
+    });
+  } catch (error) {
+    process.stderr.write(`wendkeep doctor: ${error.message}\n`);
     process.exit(2);
   }
-  const vaultBase = env.OBSIDIAN_VAULT_PATH;
-  const projectRoot = resolve(project || process.cwd());
+  const vaultBase = resolution.base;
+  process.stdout.write(`[vault] ${resolution.source}: ${vaultBase} (project: ${projectRoot})\n`);
+  if (resolution.source === 'legacy-project-settings') {
+    process.stdout.write('  ! migração pendente: rode `wendkeep init --project . --vault "<vault>" --yes` para criar .wendkeep.json\n');
+  }
 
   // 1. Session/vault integrity (existing check).
   let healthStatus = 0;
   if (existsSync(hookFile)) {
-    const r = spawnSync(process.execPath, [hookFile, ...passthrough], { stdio: 'inherit', env });
+    const r = spawnSync(process.execPath, [hookFile, ...passthrough, '--vault', vaultBase], { stdio: 'inherit' });
     healthStatus = r.status ?? 0;
   }
 

package/src/import.mjs

@@ -12,7 +12,22 @@ function opt(argv, name) {
   return eq ? eq.slice(name.length + 1) : undefined;
 }
 
+const KNOWN_FLAGS = new Set([
+  '--vault', '--project', '--source', '--from', '--codex-from', '--since', '--limit',
+  '--dry-run', '--json', '--rescan-decisions', '--stamp-ids', '--help', '-h',
+]);
+
 export function runImportCli(argv) {
+  // Import writes to the vault; an unrecognized flag must never fall through to the
+  // destructive default (--source all). Fail fast, point at --help.
+  for (const a of argv) {
+    if (!a.startsWith('-')) continue;
+    const name = a.includes('=') ? a.slice(0, a.indexOf('=')) : a;
+    if (!KNOWN_FLAGS.has(name)) {
+      process.stderr.write(`wendkeep import: flag desconhecida "${name}" (use --help)\n`);
+      process.exit(2);
+    }
+  }
   const vaultRaw = opt(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
   if (!vaultRaw) { process.stderr.write('wendkeep import: no vault (--vault or OBSIDIAN_VAULT_PATH).\n'); process.exit(2); }
   const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);

package/src/init.mjs

@@ -1,6 +1,6 @@
 // `wendkeep init` — cross-platform replacement for setup-vault.ps1.
-// Creates the vault taxonomy, NON-DESTRUCTIVELY merges the session hooks +
-// OBSIDIAN_VAULT_PATH into .claude/settings.json, and adds the mcpvault server to
+// Creates the vault taxonomy + provider-neutral project binding, NON-DESTRUCTIVELY
+// merges the session hooks into .claude/settings.json, and adds the mcpvault server to
 // .mcp.json. Idempotent: re-running only adds what is missing.
 import { spawnSync } from 'node:child_process';
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
@@ -41,6 +41,7 @@ import { seedWkSkills } from './skills-seed.mjs';
 import { LOCALES, DEFAULT_LOCALE, getLocale, clearLocaleCache, vaultFolders } from '../hooks/locale.mjs';
 import { seedDotcontext, globalHasDotcontext, resolveDotcontextSkipMcp, renderSensorsJson } from './dotcontext-seed.mjs';
 import { adoptSpecsState, SPECS_STATE_FILE } from '../hooks/spec-core.mjs';
+import { bindProjectVault, readProjectBinding } from './project-vault.mjs';
 
 function parseArgs(argv) {
   const args = { mcp: true, yes: false, force: false };
@@ -281,7 +282,7 @@ const MESSAGES = {
     readmeCreated: ', README.md criado', viewsNote: (n) => `, ${n} view(s) + dashboard`,
     defs: (s, a) => `        defs entregues: ${s} skill(s) -> .claude/skills + .agents/skills, ${a} agent(s) -> .codex/agents`,
     settingsBadJson: (p) => `  [2/4] settings.json existe mas não é JSON válido -> escrevi ${p}.new (mescle à mão)`,
-    settings: (verb, added, bak) => `  [2/4] settings.json ${verb} (${added} hook(s) wirados, OBSIDIAN_VAULT_PATH setado${bak})`,
+    settings: (verb, added, bak) => `  [2/4] settings.json ${verb} (${added} hook(s) wirados; .wendkeep.json é o vínculo compartilhado${bak})`,
     mcpBadJson: (p) => `  [3/4] .mcp.json existe mas não é JSON válido -> escrevi ${p}.new (mescle à mão)`,
     mcp: (verb, names, bak) => `  [3/4] .mcp.json ${verb} (${names}${bak})`,
     mcpSkipped: '  [3/4] .mcp.json ignorado (--no-mcp, sem companions MCP)',
@@ -306,7 +307,7 @@ const MESSAGES = {
     readmeCreated: ', README.md created', viewsNote: (n) => `, ${n} view(s) + dashboard`,
     defs: (s, a) => `        defs delivered: ${s} skill(s) -> .claude/skills + .agents/skills, ${a} agent(s) -> .codex/agents`,
     settingsBadJson: (p) => `  [2/4] settings.json exists but is not valid JSON -> wrote ${p}.new (merge by hand)`,
-    settings: (verb, added, bak) => `  [2/4] settings.json ${verb} (${added} hook(s) wired, OBSIDIAN_VAULT_PATH set${bak})`,
+    settings: (verb, added, bak) => `  [2/4] settings.json ${verb} (${added} hook(s) wired; .wendkeep.json is the shared binding${bak})`,
     mcpBadJson: (p) => `  [3/4] .mcp.json exists but is not valid JSON -> wrote ${p}.new (merge by hand)`,
     mcp: (verb, names, bak) => `  [3/4] .mcp.json ${verb} (${names}${bak})`,
     mcpSkipped: '  [3/4] .mcp.json skipped (--no-mcp, no MCP companions)',
@@ -334,9 +335,14 @@ export function parseLocaleAnswer(ans) {
   return 'pt-BR';
 }
 
-// The vault path this project was set up with — read from .claude/settings.json's
-// OBSIDIAN_VAULT_PATH (written by a prior init). Empty when the project isn't configured yet.
+// The vault path this project was set up with. New installs use the provider-neutral
+// `.wendkeep.json`; `.claude/settings.json` remains a local migration bridge for projects
+// initialized before 0.39.0.
 export function detectRegisteredVault(projectPath) {
+  try {
+    const binding = readProjectBinding(projectPath);
+    if (binding?.base) return binding.base;
+  } catch { /* init will surface/repair through an explicit --vault */ }
   try {
     const s = JSON.parse(readFileSync(join(projectPath, '.claude', 'settings.json'), 'utf8'));
     const v = s && s.env && s.env.OBSIDIAN_VAULT_PATH;
@@ -357,8 +363,8 @@ export async function runInit(argv) {
   const projectPath = resolve(args.project || process.cwd());
   const log = (s) => process.stdout.write(`${s}\n`);
 
-  // Recognize an already-configured project: the vault is registered in the project's
-  // settings.json (OBSIDIAN_VAULT_PATH) and its locale is locked in the vault's config.json.
+  // Recognize an already-configured project through `.wendkeep.json`, or through the
+  // project-local Claude setting during migration. Locale remains locked in vault config.
   // On re-run (e.g. after `npm i -D wendkeep@latest`) we reuse both and SKIP the language + vault
   // prompts — asking again risks a divergent vault from a mistyped name. `--vault` / `--locale`
   // override; the vault question is a once-per-project thing.
@@ -393,6 +399,10 @@ export async function runInit(argv) {
   }
   vaultPath = isAbsolute(vaultPath) ? vaultPath : resolve(projectPath, vaultPath);
 
+  // Persist the provider-neutral binding before any hook/config delivery. This also
+  // claims the vault identity and rejects accidental cross-project graph contamination.
+  bindProjectVault({ projectRoot: projectPath, vaultPath });
+
   // Companion plugins/MCP selection. --no-companions wins; --companions <csv> is
   // explicit; an interactive TTY gets a multi-choice prompt (context-mode pre-checked);
   // otherwise the non-interactive default (context-mode only).

package/src/project-vault.mjs

@@ -0,0 +1,221 @@
+import { randomUUID } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, dirname, isAbsolute, join, parse, relative, resolve } from 'node:path';
+
+export const PROJECT_CONFIG_FILE = '.wendkeep.json';
+export const PROJECT_MARKER_REL = '.brain/PROJECT.json';
+export const PROJECT_CONFIG_SCHEMA = 1;
+
+function json(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); }
+  catch (error) {
+    const wrapped = new Error(`Configuração WendKeep inválida em "${path}": ${error.message}`);
+    wrapped.code = 'WENDKEEP_VAULT_CONFIG_INVALID';
+    throw wrapped;
+  }
+}
+
+function atomicJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  const content = `${JSON.stringify(value, null, 2)}\n`;
+  if (existsSync(path) && readFileSync(path, 'utf8') === content) return false;
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temp, content, 'utf8');
+  renameSync(temp, path);
+  return true;
+}
+
+function startDirectory(value) {
+  const candidate = resolve(String(value || process.cwd()));
+  try { return statSync(candidate).isFile() ? dirname(candidate) : candidate; }
+  catch { return candidate; }
+}
+
+function walkParents(start) {
+  const result = [];
+  let current = startDirectory(start);
+  const root = parse(current).root;
+  while (true) {
+    result.push(current);
+    if (current === root) break;
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return result;
+}
+
+function inputStart(input = {}, fallback = '') {
+  return input.cwd
+    || input.project_dir
+    || input.projectDir
+    || input.workspace?.cwd
+    || process.env.CLAUDE_PROJECT_DIR
+    || fallback
+    || process.cwd();
+}
+
+function vaultFromConfig(projectRoot, config) {
+  if (!config || config.schemaVersion !== PROJECT_CONFIG_SCHEMA || !config.projectId || !config.vault) {
+    const error = new Error(
+      `Configuração incompleta em "${join(projectRoot, PROJECT_CONFIG_FILE)}". `
+      + 'Rode `wendkeep init --project <path> --vault <path>`.',
+    );
+    error.code = 'WENDKEEP_VAULT_CONFIG_INVALID';
+    throw error;
+  }
+  return isAbsolute(config.vault) ? resolve(config.vault) : resolve(projectRoot, config.vault);
+}
+
+export function readProjectBinding(projectRoot) {
+  const root = resolve(projectRoot);
+  const path = join(root, PROJECT_CONFIG_FILE);
+  if (!existsSync(path)) return null;
+  const config = json(path);
+  return { config, configPath: path, projectRoot: root, base: vaultFromConfig(root, config) };
+}
+
+export function findProjectBinding(start) {
+  for (const projectRoot of walkParents(start)) {
+    const found = readProjectBinding(projectRoot);
+    if (found) return found;
+  }
+  return null;
+}
+
+export function findLegacyProjectVault(start) {
+  for (const projectRoot of walkParents(start)) {
+    const settingsPath = join(projectRoot, '.claude', 'settings.json');
+    if (!existsSync(settingsPath)) continue;
+    try {
+      const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+      const raw = settings?.env?.OBSIDIAN_VAULT_PATH;
+      if (typeof raw === 'string' && raw.trim()) {
+        return {
+          base: isAbsolute(raw) ? resolve(raw) : resolve(projectRoot, raw),
+          projectRoot,
+          source: 'legacy-project-settings',
+          configPath: settingsPath,
+          projectId: '',
+        };
+      }
+    } catch { /* init/doctor explicam JSON inválido; descoberta segue procurando */ }
+  }
+  return null;
+}
+
+export function readVaultMarker(vaultPath) {
+  const markerPath = join(resolve(vaultPath), ...PROJECT_MARKER_REL.split('/'));
+  if (!existsSync(markerPath)) return null;
+  return { marker: json(markerPath), markerPath };
+}
+
+function validateMarker(result) {
+  const found = readVaultMarker(result.base);
+  if (!found) {
+    const error = new Error(
+      `O vault "${result.base}" ainda não possui ${PROJECT_MARKER_REL}. `
+      + `Rode \`wendkeep init --project "${result.projectRoot}" --vault "${result.base}" --yes\`.`,
+    );
+    error.code = 'WENDKEEP_VAULT_MARKER_MISSING';
+    throw error;
+  }
+  if (found.marker?.projectId !== result.projectId) {
+    const error = new Error(
+      `Vault de outro projeto: configuração "${result.projectId}" aponta para marcador `
+      + `"${found.marker?.projectId || 'ausente'}" em "${found.markerPath}".`,
+    );
+    error.code = 'WENDKEEP_VAULT_PROJECT_MISMATCH';
+    throw error;
+  }
+}
+
+export function resolveProjectVault({
+  input = {},
+  startDir = '',
+  explicitVault = '',
+  allowLegacySettings = true,
+  validateIdentity = true,
+} = {}) {
+  const start = inputStart(input, startDir);
+  const explicit = explicitVault || input?.obsidian_vault_path;
+  if (explicit) {
+    return {
+      base: isAbsolute(explicit) ? resolve(explicit) : resolve(startDirectory(start), explicit),
+      source: explicitVault ? 'explicit' : 'payload',
+      projectRoot: startDirectory(start),
+      projectId: '',
+      configPath: '',
+    };
+  }
+
+  const binding = findProjectBinding(start);
+  if (binding) {
+    const result = {
+      base: binding.base,
+      source: 'project-config',
+      projectRoot: binding.projectRoot,
+      projectId: binding.config.projectId,
+      configPath: binding.configPath,
+    };
+    if (validateIdentity) validateMarker(result);
+    return result;
+  }
+
+  if (allowLegacySettings) {
+    const legacy = findLegacyProjectVault(start);
+    if (legacy) return legacy;
+  }
+
+  const error = new Error(
+    `Nenhum vault WendKeep vinculado ao projeto em "${startDirectory(start)}". `
+    + `Crie ${PROJECT_CONFIG_FILE} com \`wendkeep init --project "${startDirectory(start)}" --vault <path> --yes\`.`,
+  );
+  error.code = 'WENDKEEP_VAULT_UNCONFIGURED';
+  throw error;
+}
+
+function portableVaultPath(projectRoot, vaultPath) {
+  const rel = relative(projectRoot, vaultPath);
+  if (rel && !rel.startsWith('..') && !isAbsolute(rel)) return rel.replaceAll('\\', '/');
+  return vaultPath;
+}
+
+export function bindProjectVault({ projectRoot, vaultPath }) {
+  const root = resolve(projectRoot);
+  const base = isAbsolute(vaultPath) ? resolve(vaultPath) : resolve(root, vaultPath);
+  const existing = readProjectBinding(root);
+  const existingMarker = readVaultMarker(base);
+  const projectId = existing?.config?.projectId || existingMarker?.marker?.projectId || randomUUID();
+
+  if (existingMarker?.marker?.projectId && existingMarker.marker.projectId !== projectId) {
+    const error = new Error(
+      `Não é seguro vincular "${root}" ao vault de outro projeto: `
+      + `esperado "${projectId}", encontrado "${existingMarker.marker.projectId}".`,
+    );
+    error.code = 'WENDKEEP_VAULT_PROJECT_MISMATCH';
+    throw error;
+  }
+
+  mkdirSync(join(base, '.brain'), { recursive: true });
+  const config = {
+    schemaVersion: PROJECT_CONFIG_SCHEMA,
+    projectId,
+    vault: portableVaultPath(root, base),
+  };
+  const marker = {
+    schemaVersion: PROJECT_CONFIG_SCHEMA,
+    projectId,
+    projectName: basename(root),
+  };
+  atomicJson(join(base, ...PROJECT_MARKER_REL.split('/')), marker);
+  atomicJson(join(root, PROJECT_CONFIG_FILE), config);
+  return { base, projectRoot: root, projectId, config, marker };
+}

package/src/skills-seed.mjs

@@ -35,15 +35,18 @@ vault cego. Exceção única: mudança trivial (typo, 1 linha).
    Antes de implementar, resolva \`spec_impact\` na proposta:
    - \`required\`: liste a capability em \`specs:\` e preencha
      \`specs/<capability>/spec.md\` com ADDED/MODIFIED/REMOVED; ligue tarefas com \`[req:ID]\`.
+     Heading de requisito: \`### Requisito: <ID> — <nome>\` (ou só \`### Requisito: <ID>\`);
+     o ID é a identidade (ex.: \`GATE-1\`, \`API-AUTH-2\`).
    - \`none\`: registre uma justificativa real em \`spec_impact_reason\`.
    \`pending\` nunca é estado pronto para implementação ou archive.
 3. **Apply** — implemente cada tarefa de \`tarefas.md\` com disciplina **wk-tdd**
    (teste vermelho antes do código). Marque \`- [x]\` ao concluir. Declare nas tarefas:
    - \`[sensor:<id>]\` — a prova automatizada (roda no verify).
    - \`[req:<ID>]\` — o requisito do spec que a tarefa satisfaz (ex.: \`[req:GATE-1]\`),
-      quando a change mexe numa capability. Toda autoria de spec ocorre somente em
+      quando a change mexe numa capability. Uma tarefa pode declarar vários
+      \`[req:]\` — todos contam na cobertura. Toda autoria de spec ocorre somente em
       \`08-Mudanças/<slug>/specs/<capability>/spec.md\`; \`07-Specs\` é gerado/read-only.
-   Ex.: \`- [ ] 2.1 valida CORE [req:MEM-1] [sensor:memory-validation]\`.
+   Ex.: \`- [ ] 2.1 valida CORE [req:MEM-1] [req:MEM-2] [sensor:memory-validation]\`.
 4. **Verify** — \`wendkeep verify\` roda os sensores → \`evidencia.json\`. Depois
    \`wendkeep verify --deep\` monta o *pacote de verificação* pro passe independente.
 5. **Verify deep** — a skill **wk-verify** (passe fresco, autor≠verificador) lê o pacote,
@@ -259,8 +262,11 @@ leaves the vault blind. Single exception: a trivial change (typo, one line).
    Before implementation, resolve \`spec_impact\`: \`required\` needs the capability listed in
    \`specs:\` plus a real \`specs/<capability>/spec.md\` delta and \`[req:ID]\` links; \`none\`
    needs a real \`spec_impact_reason\`. \`pending\` is never ready for implementation/archive.
+   Requirement heading: \`### Requirement: <ID> — <name>\` (or bare \`### Requirement: <ID>\`);
+   the ID is the identity (e.g. \`GATE-1\`, \`API-AUTH-2\`).
 3. **Apply** — implement each task in tarefas.md with **wk-tdd** (red test first). Tag tasks:
-   \`[sensor:<id>]\` (automated proof) and \`[req:<ID>]\` (the spec requirement it satisfies).
+   \`[sensor:<id>]\` (automated proof) and \`[req:<ID>]\` (the spec requirement it satisfies;
+   a task may declare several \`[req:]\` tags — all of them count toward coverage).
    Author specs only in \`08-Changes/<slug>/specs/\`; \`07-Specs\` is generated/read-only.
 4. **Verify** — \`wendkeep verify\` runs the sensors; then \`wendkeep verify --deep\` builds
    the verification package.

package/src/spec.mjs

@@ -49,7 +49,7 @@ export function runSpec(argv) {
       tasks = parseTasks(readFileSync(join(changeDir, 'tarefas.md'), 'utf8'));
     }
     catch { process.stderr.write(`wendkeep spec effective: change not found: ${slug}\n`); process.exit(2); }
-    const reqIds = [...new Set(tasks.map((task) => task.req).filter(Boolean))];
+    const reqIds = [...new Set(tasks.flatMap((task) => task.reqs ?? []))];
     const effective = buildEffectiveRequirementPackage(vaultBase, changeDir, reqIds);
     if (effective.errors.length) {
       process.stderr.write(`wendkeep spec effective: invalid delta: ${effective.errors.join('; ')}\n`);

package/src/vault-readme.mjs

@@ -52,7 +52,7 @@ export function renderVaultReadme({ projectName, vaultPath, withMcp = true, loca
     const mcpIntro = withMcp ? ', and read/written by the **MCPVault** MCP server' : '';
     const access = [`- **Obsidian:** open this folder with "Open folder as vault" → \`${vaultPath}\``];
     if (withMcp) access.push('- **Agent (MCP):** the `wendkeep-vault` server (MCPVault) points at this vault (set in `.mcp.json`), giving the agent read/write on the notes.');
-    access.push('- **Hooks:** `settings.json` calls `npx wendkeep hook <name>`; the vault is located via `OBSIDIAN_VAULT_PATH` (also written by `wendkeep init`).');
+    access.push('- **Hooks:** Codex and Claude Code call `npx wendkeep hook <name>`; the vault is discovered from the project-local `.wendkeep.json` binding and checked against `.brain/PROJECT.json`.');
     return `# Obsidian vault — ${name}
 
 > Knowledge base of **${name}**, captured automatically by wendkeep from AI coding-agent
@@ -84,7 +84,7 @@ ${access.join('\n')}
   const mcpIntro = withMcp ? ', e lida/escrita pelo MCP server **MCPVault**' : '';
   const access = [`- **Obsidian:** abra esta pasta com "Open folder as vault" → \`${vaultPath}\``];
   if (withMcp) access.push('- **Agente (MCP):** o servidor `wendkeep-vault` (MCPVault) é apontado para este vault pelo `wendkeep init` (em `.mcp.json`), dando ao agente leitura/escrita das notas.');
-  access.push('- **Hooks:** `settings.json` chama `npx wendkeep hook <name>`; o vault é localizado via a env `OBSIDIAN_VAULT_PATH` (também gravada pelo `wendkeep init`).');
+  access.push('- **Hooks:** Codex e Claude Code chamam `npx wendkeep hook <name>`; o vault é descoberto pelo vínculo local `.wendkeep.json` e validado contra `.brain/PROJECT.json`.');
   return `# Vault Obsidian — ${name}
 
 > Base de conhecimento de **${name}**, capturada automaticamente pelo wendkeep a

package/src/verify.mjs

@@ -4,10 +4,11 @@
 import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { parseTasks, activeChange, appendFixTasks } from '../hooks/change-core.mjs';
-import { loadSensors, requiredSensors, runSensors, evaluateGate } from '../hooks/sensors-core.mjs';
+import { loadSensorsDetailed, findProjectRoot, requiredSensors, runSensors, evaluateGate } from '../hooks/sensors-core.mjs';
 import {
   buildEffectiveRequirementPackage,
   captureSpecBaseline,
+  formatOrphanReqs,
   tasksHashOf,
 } from '../hooks/spec-core.mjs';
 import { addLesson } from '../hooks/lessons-core.mjs';
@@ -29,7 +30,9 @@ export function runVerify(argv) {
   const vaultRaw = opt(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
   if (!vaultRaw) { process.stderr.write('wendkeep verify: no vault (--vault or OBSIDIAN_VAULT_PATH).\n'); process.exit(2); }
   const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);
-  const projectRoot = resolve(opt(argv, '--project') || process.cwd());
+  // --project wins; otherwise climb from cwd to the nearest project marker (agent shells
+  // keep their cwd across commands, so verify from a subdirectory is a recurring miss).
+  const projectRoot = resolve(opt(argv, '--project') || findProjectRoot(process.cwd()) || process.cwd());
   const slug = opt(argv, '--change') || activeChange(vaultBase);
   if (!slug) { process.stderr.write('wendkeep verify: no change (--change or active).\n'); process.exit(2); }
 
@@ -39,7 +42,15 @@ export function runVerify(argv) {
   catch { process.stderr.write(`wendkeep verify: change not found: ${slug}\n`); process.exit(2); }
 
   const ids = requiredSensors(parseTasks(tarefas));
-  const sensors = loadSensors(projectRoot);
+  const loaded = loadSensorsDetailed(projectRoot);
+  if (loaded.error) {
+    process.stderr.write(`wendkeep verify: wendkeep.sensors.json inválido em ${loaded.path}: ${loaded.error}\n`);
+    process.exit(2);
+  }
+  if (loaded.missing && ids.length) {
+    process.stderr.write(`wendkeep verify: wendkeep.sensors.json não encontrado em ${loaded.path} — rode da raiz do projeto ou use --project <raiz>\n`);
+  }
+  const sensors = loaded.sensors;
   const evidence = runSensors(sensors, ids, { cwd: projectRoot });
   writeFileSync(join(changeDir, 'evidencia.json'), `${JSON.stringify(evidence, null, 2)}\n`, 'utf8');
   // Freshness seal: bind this evidence to the tarefas.md it was produced against, so the archive
@@ -90,7 +101,7 @@ export function runVerify(argv) {
   // change (no [req:] tasks, sensors green) gets an auto verdict — no agent pass needed.
   if (argv.includes('--deep')) {
     const tasks = parseTasks(tarefas);
-    const reqIds = [...new Set(tasks.map((t) => t.req).filter(Boolean))];
+    const reqIds = [...new Set(tasks.flatMap((t) => t.reqs ?? []))];
     const tasksHash = tasksHashOf(tarefas);
     captureSpecBaseline(vaultBase, changeDir);
     const effective = buildEffectiveRequirementPackage(vaultBase, changeDir, reqIds);
@@ -99,7 +110,7 @@ export function runVerify(argv) {
       process.exit(1);
     }
     if (effective.missing.length) {
-      process.stderr.write(`verify --deep: requisito(s) órfão(s) na spec efetiva: ${effective.missing.join(', ')}\n`);
+      process.stderr.write(`verify --deep: ${formatOrphanReqs(effective.missing)}\n`);
       process.exit(1);
     }
     const pkg = {
@@ -116,7 +127,7 @@ export function runVerify(argv) {
           body: req.body,
         };
       }),
-      tasks: tasks.map((t) => ({ id: t.id, text: t.text, req: t.req || null, done: t.done })),
+      tasks: tasks.map((t) => ({ id: t.id, text: t.text, req: t.req || null, reqs: t.reqs || [], done: t.done })),
       sensors: evidence,
     };
     writeFileSync(join(changeDir, 'verificacao.json'), `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');