wendkeep 0.2.6 → 0.3.0

package/README.md

@@ -38,13 +38,13 @@ npx wendkeep init
 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).
 3. Add the `wendkeep-vault` MCP server to `.mcp.json` (skip with `--no-mcp`).
-4. Offer to pin **companion** plugins/MCP (multi-choice; `context-mode` pre-checked). Each is wired through the most agent-agnostic path it supports — `context-mode` as an `.mcp.json` MCP server (any agent), `understand-anything` via a `understand-inject` SessionStart hook that injects its domain graph when generated, and the Claude Code plugin layer (`extraKnownMarketplaces` + `enabledPlugins`) as a bonus. Control with `--companions <csv>` or `--no-companions`. (`caveman` additionally runs its own cross-agent installer on non-Claude agents.)
+4. Offer to pin **companion** plugins/MCP (multi-choice; `context-mode` + `dotcontext` pre-checked). Each is wired through the most agent-agnostic path it supports — `context-mode` and `dotcontext` as `.mcp.json` MCP servers (any agent), `understand-anything` via a `understand-inject` SessionStart hook that injects its domain graph when generated, and the Claude Code plugin layer (`extraKnownMarketplaces` + `enabledPlugins`) as a bonus. **`dotcontext`** (execution/PREVC harness) also gets its lifecycle hooks wired (SessionStart-last + Stop + PostToolUse, pinned CLI) and a starter `.context/config/sensors.json` seeded with a `wendkeep validate-memory` sensor plus one per detected `package.json` script (test/typecheck/lint/build) — add the `.context/runtime|cache|logs|plans|agents|skills/` paths to `.gitignore` (wendkeep doesn't touch git). If dotcontext is already configured globally (`~/.claude.json`), the project MCP entry is **skipped automatically** to avoid a duplicate; tune with `--dotcontext-mcp <auto|project|none>` and `--dotcontext-hooks <full|light|none>` (light drops PostToolUse). Control selection with `--companions <csv>` or `--no-companions`. (`caveman` additionally runs its own cross-agent installer on non-Claude agents.)
 5. Install a **color system** into the vault's `.obsidian/`: a CSS snippet that accents notes by type (session/decision/bug/learning, via the `cssclasses` the hooks emit) plus graph color groups by folder. Non-destructive merge into `appearance.json`/`graph.json`; skip with `--no-colors`.
 6. Seed the **curated memory layer**: `.brain/CORE.md` (the hand-curated hot layer, with the 3 required sections) and `.brain/COMPACTION_PROTOCOL.md` (the protocol guide). The auto layers (`DIGEST.md`, `index.jsonl`) are generated by the hooks. Validate the curated layer with `wendkeep validate-memory` (cap 25 lines, 3 sections, no secrets/PII).
 7. Seed the **definitions layer**: `.brain/agents/` + `.brain/skills/` (versioned source of truth for custom agents/skills, with a README + one example each). Run `wendkeep sync-defs` to copy them into the project's agent dirs (`.brain/agents/*.toml` → `.codex/agents/`, `.brain/skills/<name>/` → `.claude/skills/`).
 
 ```bash
-npx wendkeep init --vault "~/vaults/work" --project . --yes   # non-interactive (companions: context-mode)
+npx wendkeep init --vault "~/vaults/work" --project . --yes   # non-interactive (companions: context-mode,dotcontext)
 npx wendkeep init --companions "context-mode,caveman" --yes
 npx wendkeep init --no-companions --yes
 ```

package/bin/wendkeep.mjs

@@ -29,10 +29,13 @@ Usage:
     --vault <path>         Obsidian vault folder (default: <project>/.<project-name>-vault).
     --project <path>       Project root to wire (default: current directory).
     --no-mcp               Do not add the mcpvault MCP server to .mcp.json.
-    --companions <csv>     Companion plugins/MCP to pin: context-mode,caveman,understand-anything
-                           (default when interactive/--yes: context-mode).
+    --companions <csv>     Companion plugins/MCP to pin: context-mode,dotcontext,caveman,understand-anything
+                           (default when interactive/--yes: context-mode,dotcontext).
     --no-companions        Skip companion plugins/MCP entirely.
     --no-colors            Skip the Obsidian color system (.obsidian snippet + graph groups).
+    --dotcontext-mcp <v>   dotcontext MCP placement: auto (default; skip project entry
+                           if already global), project, or none.
+    --dotcontext-hooks <v> dotcontext hooks: full (default), light (no PostToolUse), none.
     --yes, -y              Non-interactive; accept defaults.
     --force                Overwrite existing wendkeep config blocks.
 
@@ -40,6 +43,8 @@ Usage:
                            agent's JSON on stdin. Names: ${RUNNABLE_HOOKS.join(', ')}.
 
   wendkeep doctor [--vault P]  Run a vault health check.
+  wendkeep change <sub>        Change lifecycle: new <slug> | list | show <slug> | archive <slug>.
+  wendkeep verify [--change s] Run a change's task sensors + record evidence (the gate).
   wendkeep validate-memory [path]  Validate .brain/CORE.md against the compaction
                            protocol (cap 25, 3 sections, no secrets/PII). Uses
                            --vault <path> or OBSIDIAN_VAULT_PATH if no path given.
@@ -96,6 +101,16 @@ async function main() {
       runSyncDefs(rest);
       break;
     }
+    case 'change': {
+      const { runChange } = await import('../src/change.mjs');
+      runChange(rest);
+      break;
+    }
+    case 'verify': {
+      const { runVerify } = await import('../src/verify.mjs');
+      runVerify(rest);
+      break;
+    }
     case '--version':
     case '-v':
       process.stdout.write(`${version()}\n`);

package/hooks/brain-inject.mjs

@@ -7,6 +7,7 @@ import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { getVaultBase, readHookInput, writeHookOutput } from './obsidian-common.mjs';
 import { brainDir } from './brain-core.mjs';
+import { buildActiveChangeInjection } from './change-core.mjs';
 
 const MAX_LINES = 45; // CORE ≤25 + DIGEST ≤15 + folga; salvaguarda se o CORE crescer à mão
 
@@ -23,7 +24,9 @@ export function buildInjection(vaultBase) {
     lines = lines.slice(0, MAX_LINES);
     lines.push('*…truncado pelo budget — fonte completa: .brain/CORE.md + .brain/DIGEST.md*');
   }
-  return ['<brain_memory>', ...lines, pointer, '</brain_memory>'].join('\n');
+  const brain = ['<brain_memory>', ...lines, pointer, '</brain_memory>'].join('\n');
+  const change = buildActiveChangeInjection(vaultBase);
+  return change ? `${brain}\n${change}` : brain;
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/hooks/change-core.mjs

@@ -0,0 +1,178 @@
+// hooks/change-core.mjs
+// Native change/spec lifecycle in the vault (Pilar B). Vault-facing lib consumed by
+// the `wendkeep change` CLI (src/change.mjs) and the brain-inject hook. No external deps.
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureDir, wikilinkFromRel } from './obsidian-common.mjs';
+
+export const CHANGES_DIR = '08-Mudanças';
+export const SPECS_DIR = '07-Specs';
+export const ARCHIVE_DIR = '_arquivo';
+const POINTER = '.brain/CURRENT_CHANGE.md';
+
+export function changeDirRel(slug) {
+  return join(CHANGES_DIR, slug);
+}
+
+export function renderChangeScaffold({ slug, sessionRel, dateStr }) {
+  const source = sessionRel ? `\n  - "${wikilinkFromRel(sessionRel)}"` : ' []';
+  const proposta = `---
+type: change
+status: active
+date: ${dateStr}
+cssclasses:
+  - topic-change
+tags:
+  - mudanca
+source:${source}
+specs: []
+---
+
+# ${slug}
+
+## Por quê
+
+(motivo da mudança)
+
+## O que muda
+
+(escopo da mudança)
+`;
+  const design = `# ${slug} — design
+
+## Abordagem
+
+(abordagem técnica)
+`;
+  const tarefas = `# ${slug} — tarefas
+
+- [ ] 1.1 (primeira tarefa)
+`;
+  return { proposta, design, tarefas };
+}
+
+export function activeChange(vaultBase) {
+  try {
+    const m = readFileSync(join(vaultBase, POINTER), 'utf8').match(/^change:\s*(.+)$/m);
+    return m ? m[1].trim() : '';
+  } catch {
+    return '';
+  }
+}
+
+export function setActiveChange(vaultBase, slug) {
+  mkdirSync(join(vaultBase, '.brain'), { recursive: true });
+  writeFileSync(join(vaultBase, POINTER), `change: ${slug}\n`, 'utf8');
+}
+
+export function clearActiveChange(vaultBase) {
+  const p = join(vaultBase, POINTER);
+  if (existsSync(p)) writeFileSync(p, 'change:\n', 'utf8');
+}
+
+export function newChange(vaultBase, slug, { sessionRel = '', dateStr }) {
+  const dir = join(vaultBase, CHANGES_DIR, slug);
+  const existed = existsSync(join(dir, 'proposta.md'));
+  mkdirSync(dir, { recursive: true });
+  const files = renderChangeScaffold({ slug, sessionRel, dateStr });
+  const write = (name, content) => {
+    const f = join(dir, name);
+    if (!existsSync(f)) writeFileSync(f, content, 'utf8');
+  };
+  write('proposta.md', files.proposta);
+  write('design.md', files.design);
+  write('tarefas.md', files.tarefas);
+  setActiveChange(vaultBase, slug);
+  return { rel: changeDirRel(slug), created: !existed };
+}
+
+export function parseTasks(md) {
+  const tasks = [];
+  const re = /^-\s+\[( |x)\]\s+(\S+)\s+(.*)$/gm;
+  const sensorRe = /\[sensor:\s*([\w.-]+)\]/;
+  let m;
+  while ((m = re.exec(String(md))) !== null) {
+    let text = m[3].trim();
+    const sm = text.match(sensorRe);
+    const sensor = sm ? sm[1] : undefined;
+    if (sm) text = text.replace(sensorRe, '').replace(/\s+/g, ' ').trim();
+    tasks.push({ id: m[2], text, done: m[1] === 'x', ...(sensor ? { sensor } : {}) });
+  }
+  return tasks;
+}
+
+export function listChanges(vaultBase) {
+  const base = join(vaultBase, CHANGES_DIR);
+  const active = [];
+  let archived = [];
+  try {
+    for (const name of readdirSync(base)) {
+      if (name === ARCHIVE_DIR) continue;
+      if (existsSync(join(base, name, 'proposta.md'))) active.push(name);
+    }
+  } catch { /* no changes dir yet */ }
+  try {
+    archived = readdirSync(join(base, ARCHIVE_DIR)).filter((n) => !n.startsWith('.'));
+  } catch { /* none */ }
+  return { active, archived };
+}
+
+export function buildActiveChangeInjection(vaultBase, { maxTasks = 8 } = {}) {
+  const slug = activeChange(vaultBase);
+  if (!slug) return '';
+  let md = '';
+  try { md = readFileSync(join(vaultBase, CHANGES_DIR, slug, 'tarefas.md'), 'utf8'); } catch { return ''; }
+  const open = parseTasks(md).filter((t) => !t.done).slice(0, maxTasks);
+  const lines = open.map((t) => `- [ ] ${t.id} ${t.text}`);
+  const more = open.length === maxTasks ? '\n*…mais tarefas em tarefas.md*' : '';
+  return `<active_change>
+Mudança ativa: ${slug} — [[${CHANGES_DIR}/${slug}/proposta]]. Tarefas abertas:
+${lines.join('\n')}${more}
+</active_change>`;
+}
+
+export function activeChangeLink(vaultBase) {
+  const slug = activeChange(vaultBase);
+  return slug ? `Change ativa: [[${CHANGES_DIR}/${slug}/proposta]]` : '';
+}
+
+// Gate seam (Pilar B stub; Pilar C replaces with real sensor evidence).
+export function gateGreen() {
+  return { ok: true, failing: [] };
+}
+
+export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrNum }) {
+  const src = join(vaultBase, CHANGES_DIR, slug);
+  const verdict = gate(src);
+  if (!verdict.ok) return { ok: false, failing: verdict.failing || [] };
+
+  const destRel = join(CHANGES_DIR, ARCHIVE_DIR, `${dateStr}-${slug}`);
+  ensureDir(join(vaultBase, CHANGES_DIR, ARCHIVE_DIR));
+  renameSync(src, join(vaultBase, destRel));
+
+  const [year] = String(dateStr).split('-');
+  const adrDirRel = join('04-Decisões', year);
+  ensureDir(join(vaultBase, adrDirRel));
+  const num = String(adrNum).padStart(3, '0');
+  const adrRel = join(adrDirRel, `ADR-${num}-${slug}.md`);
+  const changeWikilink = wikilinkFromRel(join(destRel, 'proposta'));
+  writeFileSync(join(vaultBase, adrRel), `---
+type: decision
+status: accepted
+date: ${dateStr}
+cssclasses:
+  - topic-decision
+tags:
+  - decisao
+---
+
+# ADR-${num} — ${slug}
+
+## Decisão
+
+Mudança ${changeWikilink} concluída e arquivada.
+`, 'utf8');
+
+  clearActiveChange(vaultBase);
+  return { ok: true, failing: [], archivedRel: destRel, adrRel };
+}

package/hooks/sensors-core.mjs

@@ -0,0 +1,38 @@
+// hooks/sensors-core.mjs — native sensor runner + evidence gate (Pilar C).
+// 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';
+
+export function loadSensors(projectRoot, file = 'wendkeep.sensors.json') {
+  try {
+    const data = JSON.parse(readFileSync(join(projectRoot, file), 'utf8'));
+    return Array.isArray(data.sensors) ? data.sensors : [];
+  } catch {
+    return [];
+  }
+}
+
+export function requiredSensors(tasks) {
+  return [...new Set((tasks || []).map((t) => t.sensor).filter(Boolean))];
+}
+
+export function runSensors(sensors, ids, { spawn = spawnSync, cwd, now } = {}) {
+  const byId = Object.fromEntries((sensors || []).map((s) => [s.id, s]));
+  const ts = now || new Date().toISOString();
+  const evidence = [];
+  for (const id of ids) {
+    const s = byId[id];
+    if (!s) { evidence.push({ id, status: 'red', ts, note: 'sensor não definido' }); continue; }
+    const r = spawn(s.command, [], { cwd, shell: true, stdio: 'ignore' });
+    evidence.push({ id, status: (r.status ?? 1) === 0 ? 'green' : 'red', ts });
+  }
+  return evidence;
+}
+
+export function evaluateGate(evidence, requiredIds) {
+  const byId = Object.fromEntries((evidence || []).map((e) => [e.id, e.status]));
+  const failing = (requiredIds || []).filter((id) => byId[id] !== 'green');
+  return { ok: failing.length === 0, failing };
+}

package/hooks/session-stop.mjs

@@ -6,6 +6,7 @@ import { pathToFileURL } from 'url';
 import { createLinkedNotes } from './linked-notes.mjs';
 import { addUsage, costBreakdown, emptyTokenUsage, normalizeClaudeUsage, normalizeCodexUsage, priceForModel, updateSessionUsage } from './token-usage.mjs';
 import { buildBrainDigest, buildBrainIndex } from './brain-core.mjs';
+import { activeChangeLink } from './change-core.mjs';
 import {
   ensureDir,
   findActiveSessionByTranscript,
@@ -1072,6 +1073,14 @@ function main() {
     findLinkedDerivedNotes(vaultBase, sessionRel),
   );
   finalizeSessionFile(sessionPath, tx, created, endedAt);
+  // Link bidirecional sessão↔change ativa no grafo Obsidian. Fail-quiet: nunca derruba o Stop.
+  try {
+    const chgLink = activeChangeLink(vaultBase);
+    if (chgLink) {
+      const cur = readFileSync(sessionPath, 'utf8');
+      if (!cur.includes(chgLink)) writeFileSync(sessionPath, `${cur.trimEnd()}\n\n${chgLink}\n`, 'utf8');
+    }
+  } catch { /* nunca derruba o Stop */ }
   writeControl(vaultBase, {
     status: 'inactive',
     session_file: '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Automatically capture AI coding agent sessions (Claude Code, Codex) as local Markdown in your Obsidian vault — turn-by-turn history, cost/token tracking, auto-extracted decisions/bugs/learnings, rendered in the graph. Local-first.",
   "type": "module",
   "bin": {

package/src/change.mjs

@@ -0,0 +1,90 @@
+// `wendkeep change <sub>` — native change lifecycle CLI (Pilar B).
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import {
+  newChange,
+  activeChange,
+  listChanges,
+  parseTasks,
+  archiveChange,
+} from '../hooks/change-core.mjs';
+import { evaluateGate, requiredSensors } from '../hooks/sensors-core.mjs';
+import { getNextAdrNumber } from '../hooks/obsidian-common.mjs';
+
+function resolveVault(argv) {
+  let vault;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--vault') vault = argv[++i];
+    else if (a.startsWith('--vault=')) vault = a.slice(8);
+  }
+  const base = vault || process.env.OBSIDIAN_VAULT_PATH;
+  if (!base) {
+    process.stderr.write('wendkeep change: no vault. Pass --vault <path> or set OBSIDIAN_VAULT_PATH.\n');
+    process.exit(2);
+  }
+  return isAbsolute(base) ? base : resolve(process.cwd(), base);
+}
+
+function today() {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+export function runChange(argv) {
+  const [sub, ...rest] = argv;
+  const vaultBase = resolveVault(rest);
+  const slugArg = () => rest.find((a) => !a.startsWith('-'));
+
+  if (sub === 'new') {
+    const slug = slugArg();
+    if (!slug) { process.stderr.write('wendkeep change new: missing <slug>\n'); process.exit(2); }
+    const r = newChange(vaultBase, slug, { dateStr: today() });
+    process.stdout.write(`change ${r.created ? 'created' : 'exists'}: ${r.rel} (active)\n`);
+    process.exit(0);
+  }
+
+  if (sub === 'list') {
+    const { active, archived } = listChanges(vaultBase);
+    const cur = activeChange(vaultBase);
+    process.stdout.write(`active: ${active.map((s) => (s === cur ? `*${s}` : s)).join(', ') || '(none)'}\n`);
+    process.stdout.write(`archived: ${archived.join(', ') || '(none)'}\n`);
+    process.exit(0);
+  }
+
+  if (sub === 'show') {
+    const slug = slugArg();
+    if (!slug) { process.stderr.write('wendkeep change show: missing <slug>\n'); process.exit(2); }
+    let md;
+    try { md = readFileSync(join(vaultBase, '08-Mudanças', slug, 'tarefas.md'), 'utf8'); }
+    catch { process.stderr.write(`wendkeep change show: not found: ${slug}\n`); process.exit(2); }
+    const tasks = parseTasks(md);
+    const open = tasks.filter((t) => !t.done).length;
+    process.stdout.write(`${slug}: ${tasks.length} task(s), ${open} open\n`);
+    for (const t of tasks) process.stdout.write(`  [${t.done ? 'x' : ' '}] ${t.id} ${t.text}\n`);
+    process.exit(0);
+  }
+
+  if (sub === 'archive') {
+    const slug = slugArg() || activeChange(vaultBase);
+    if (!slug) { process.stderr.write('wendkeep change archive: missing <slug> and no active change\n'); process.exit(2); }
+    // Real gate (Pilar C): every sensor a task declared must be green in evidencia.json.
+    const gate = (dir) => {
+      let required = [];
+      try { required = requiredSensors(parseTasks(readFileSync(join(dir, 'tarefas.md'), 'utf8'))); } catch { /* no tasks */ }
+      let evidence = [];
+      try { evidence = JSON.parse(readFileSync(join(dir, 'evidencia.json'), 'utf8')); } catch { /* no evidence */ }
+      return evaluateGate(evidence, required);
+    };
+    const r = archiveChange(vaultBase, slug, { dateStr: today(), adrNum: getNextAdrNumber(vaultBase), gate });
+    if (!r.ok) {
+      process.stderr.write(`change archive BLOCKED (gate): failing sensors: ${r.failing.join(', ')} — run \`wendkeep verify\`.\n`);
+      process.exit(1);
+    }
+    process.stdout.write(`archived: ${r.archivedRel}; ADR: ${r.adrRel}\n`);
+    process.exit(0);
+  }
+
+  process.stderr.write(`wendkeep change: unknown subcommand "${sub}". Known: new, list, show, archive.\n`);
+  process.exit(2);
+}

package/src/dotcontext-seed.mjs

@@ -0,0 +1,83 @@
+// dotcontext .context/config seeding + MCP-placement resolution.
+// Seeds `memory-validation` (`wendkeep validate-memory`, valid in any wendkeep
+// project) plus a sensor for each detected package.json script (test/typecheck/
+// lint/build). Project-specific commands beyond that are left to `context init`.
+// Non-destructive. Also resolves whether to add the project MCP entry (skip it
+// when dotcontext is already configured globally in ~/.claude.json).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// package.json script -> sensor (only seeded if the script exists in the project).
+const SCRIPT_SENSORS = [
+  { script: 'typecheck', id: 'typecheck', name: 'Typecheck', severity: 'critical' },
+  { script: 'test', id: 'tests', name: 'Tests', severity: 'critical' },
+  { script: 'lint', id: 'lint', name: 'Lint', severity: 'warning' },
+  { script: 'build', id: 'build', name: 'Build', severity: 'warning' },
+];
+
+export function renderSensorsJson(scripts = {}) {
+  const sensors = [
+    {
+      id: 'memory-validation',
+      name: 'CORE validation',
+      description: 'valida .brain/CORE.md (cap 25 + 3 seções, sem segredos) — wendkeep',
+      severity: 'critical',
+      command: 'npx wendkeep validate-memory',
+    },
+  ];
+  for (const m of SCRIPT_SENSORS) {
+    if (scripts && scripts[m.script]) {
+      sensors.push({
+        id: m.id,
+        name: m.name,
+        description: `npm run ${m.script}`,
+        severity: m.severity,
+        command: `npm run ${m.script}`,
+      });
+    }
+  }
+  return `${JSON.stringify({ version: 1, source: 'manual', sensors }, null, 2)}\n`;
+}
+
+function readProjectScripts(projectPath) {
+  try {
+    return JSON.parse(readFileSync(join(projectPath, 'package.json'), 'utf8')).scripts || {};
+  } catch {
+    return {};
+  }
+}
+
+// Create <project>/.context/config/sensors.json if absent (sensors auto-detected
+// from the project's package.json scripts). Returns paths created.
+export function seedDotcontext(projectPath) {
+  const created = [];
+  const configDir = join(projectPath, '.context', 'config');
+  mkdirSync(configDir, { recursive: true });
+  const sensorsPath = join(configDir, 'sensors.json');
+  if (!existsSync(sensorsPath)) {
+    writeFileSync(sensorsPath, renderSensorsJson(readProjectScripts(projectPath)), 'utf8');
+    created.push(sensorsPath);
+  }
+  return created;
+}
+
+// True if ~/.claude.json already declares a global dotcontext MCP server. Best-effort.
+export function globalHasDotcontext(claudeJsonPath = join(homedir(), '.claude.json')) {
+  try {
+    const data = JSON.parse(readFileSync(claudeJsonPath, 'utf8'));
+    return !!data?.mcpServers?.dotcontext;
+  } catch {
+    return false;
+  }
+}
+
+// Whether to SKIP the project-scoped dotcontext MCP entry.
+//   'none'    -> always skip
+//   'project' -> never skip
+//   'auto'/-- -> skip iff dotcontext is already global (avoid a duplicate server)
+export function resolveDotcontextSkipMcp(flag, globalHas) {
+  if (flag === 'none') return true;
+  if (flag === 'project') return false;
+  return !!globalHas;
+}

package/src/init.mjs

@@ -19,6 +19,7 @@ import {
   companionMcpPatch,
   companionHookSpecs,
   cavemanInstallCommand,
+  DOTCONTEXT_GITIGNORE,
 } from './taxonomy.mjs';
 import { renderVaultReadme } from './vault-readme.mjs';
 import { canInteractiveSelect, selectCompanionsInteractive } from './companion-select.mjs';
@@ -31,6 +32,8 @@ import {
 } from './vault-theme.mjs';
 import { renderCoreSkeleton, renderCompactionProtocol } from './validate-core.mjs';
 import { seedDefinitions } from './sync-defs.mjs';
+import { seedWkSkills } from './skills-seed.mjs';
+import { seedDotcontext, globalHasDotcontext, resolveDotcontextSkipMcp, renderSensorsJson } from './dotcontext-seed.mjs';
 
 function parseArgs(argv) {
   const args = { mcp: true, yes: false, force: false };
@@ -43,6 +46,10 @@ function parseArgs(argv) {
     else if (a === '--force') args.force = true;
     else if (a === '--no-companions') args.noCompanions = true;
     else if (a === '--no-colors') args.noColors = true;
+    else if (a === '--dotcontext-mcp') args.dotcontextMcp = argv[++i];
+    else if (a.startsWith('--dotcontext-mcp=')) args.dotcontextMcp = a.slice(17);
+    else if (a === '--dotcontext-hooks') args.dotcontextHooks = argv[++i];
+    else if (a.startsWith('--dotcontext-hooks=')) args.dotcontextHooks = a.slice(19);
     else if (a === '--companions') args.companions = argv[++i];
     else if (a.startsWith('--companions=')) args.companions = a.slice(13);
     else if (a.startsWith('--vault=')) args.vault = a.slice(8);
@@ -80,13 +87,19 @@ function backup(path) {
 
 // --- merges -----------------------------------------------------------------
 
-export function mergeSettings(existing, { vaultPath, withMcp, force, companions = [] }) {
+export function mergeSettings(existing, { vaultPath, withMcp, force, companions = [], skipMcp = [], dotcontextHookLevel = 'full' }) {
   const s = existing && typeof existing === 'object' ? { ...existing } : {};
   s.hooks = { ...(s.hooks || {}) };
   let added = 0;
-  // wendkeep's own session hooks + any companion-authored hooks (e.g. understand-inject).
-  for (const h of [...SESSION_HOOKS, ...companionHookSpecs(companions)]) {
-    const command = hookCommand(h.name);
+  // 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),
+  );
+  for (const h of allSpecs) {
+    const command = h.command ?? hookCommand(h.name);
     const groups = Array.isArray(s.hooks[h.event]) ? [...s.hooks[h.event]] : [];
     const present = groups.some((g) => (g.hooks || []).some((x) => x.command === command));
     if (present && !force) {
@@ -110,7 +123,7 @@ export function mergeSettings(existing, { vaultPath, withMcp, force, companions
     s.enabledPlugins = { ...(s.enabledPlugins || {}), ...cp.enabledPlugins };
   }
 
-  const companionMcp = Object.keys(companionMcpPatch(companions));
+  const companionMcp = Object.keys(companionMcpPatch(companions, skipMcp));
   if (withMcp || companionMcp.length) {
     const set = new Set(Array.isArray(s.enabledMcpjsonServers) ? s.enabledMcpjsonServers : []);
     if (withMcp) set.add(MCP_SERVER_KEY);
@@ -120,11 +133,11 @@ export function mergeSettings(existing, { vaultPath, withMcp, force, companions
   return { settings: s, added };
 }
 
-export function mergeMcp(existing, { vaultPath, withVault = true, companions = [] }) {
+export function mergeMcp(existing, { vaultPath, withVault = true, companions = [], skipMcp = [] }) {
   const m = existing && typeof existing === 'object' ? { ...existing } : {};
   m.mcpServers = { ...(m.mcpServers || {}) };
   if (withVault) m.mcpServers[MCP_SERVER_KEY] = mcpServerEntry(vaultPath);
-  Object.assign(m.mcpServers, companionMcpPatch(companions));
+  Object.assign(m.mcpServers, companionMcpPatch(companions, skipMcp));
   return m;
 }
 
@@ -229,6 +242,16 @@ export async function runInit(argv) {
   log(`  companions : ${companions.length ? companions.join(', ') : 'none'}`);
   log(`  colors     : ${args.noColors ? 'skipped' : 'wendkeep-colors (snippet + graph groups)'}\n`);
 
+  // dotcontext controls (only relevant when selected): hook level + MCP placement.
+  // Skip the project MCP entry when dotcontext is already global (avoids a duplicate
+  // server / version clash); --dotcontext-mcp project|none and --dotcontext-hooks
+  // full|light|none override.
+  const dotcontextHookLevel = args.dotcontextHooks || 'full';
+  const skipMcp = [];
+  if (companions.includes('dotcontext') && resolveDotcontextSkipMcp(args.dotcontextMcp, globalHasDotcontext())) {
+    skipMcp.push('dotcontext');
+  }
+
   // 1. Vault taxonomy ---------------------------------------------------------
   if (!existsSync(vaultPath)) mkdirSync(vaultPath, { recursive: true });
   let created = 0;
@@ -258,19 +281,32 @@ export async function runInit(argv) {
   // Seed the definitions layer (.brain/agents + .brain/skills): versioned source of
   // truth for custom agents/skills. `wendkeep sync-defs` copies them to the agent dirs.
   seedDefinitions(brainDir);
-  log(`  [1/4] vault taxonomy: ${VAULT_FOLDERS.length} folders (${created} created)${readmeNote}, .brain seeded (CORE + agents/skills)`);
+  seedWkSkills(brainDir); // Pilar A: native process skills (wk-workflow/tdd/debugging/...).
+  // Seed the change/spec layer starters (Pilar B) — non-destructive.
+  const specsReadme = join(vaultPath, '07-Specs', 'README.md');
+  if (!existsSync(specsReadme)) writeFileSync(specsReadme, '# Specs — contrato vivo\n\nCapacidades do projeto (requisitos/cenários). Changes em `08-Mudanças/` promovem deltas aqui no `wendkeep change archive`.\n', 'utf8');
+  const changeTpl = join(vaultPath, 'Templates', 'Change.md');
+  if (!existsSync(changeTpl)) writeFileSync(changeTpl, '---\ntype: change\nstatus: active\ncssclasses:\n  - topic-change\n---\n\n# <slug>\n\n## Por quê\n\n## O que muda\n', 'utf8');
+  // Seed the native sensor config (Pilar C) at project root — non-destructive.
+  const sensorsFile = join(projectPath, 'wendkeep.sensors.json');
+  if (!existsSync(sensorsFile)) {
+    let scripts = {};
+    try { scripts = JSON.parse(readFileSync(join(projectPath, 'package.json'), 'utf8')).scripts || {}; } catch { /* no package.json */ }
+    writeFileSync(sensorsFile, renderSensorsJson(scripts), 'utf8');
+  }
+  log(`  [1/4] vault taxonomy: ${VAULT_FOLDERS.length} folders (${created} created)${readmeNote}, .brain + change/spec + sensors seeded`);
 
   // 2. .claude/settings.json --------------------------------------------------
   const settingsPath = join(projectPath, '.claude', 'settings.json');
   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 }).settings;
+    const fresh = mergeSettings(null, { vaultPath, withMcp: args.mcp, force: true, companions, skipMcp, dotcontextHookLevel }).settings;
     writeJson(`${settingsPath}.new`, fresh);
     log(`  [2/4] settings.json exists but is not valid JSON -> wrote ${settingsPath}.new (merge by hand)`);
   } else {
     const hadFile = settingsRead.data !== null;
-    const { settings, added } = mergeSettings(settingsRead.data, { vaultPath, withMcp: args.mcp, force: args.force, companions });
+    const { settings, added } = mergeSettings(settingsRead.data, { vaultPath, withMcp: args.mcp, force: args.force, companions, skipMcp, dotcontextHookLevel });
     if (hadFile) backup(settingsPath);
     writeJson(settingsPath, settings);
     log(`  [2/4] settings.json ${hadFile ? 'merged' : 'created'} (${added} hook(s) wired, OBSIDIAN_VAULT_PATH set${hadFile ? ', .bak saved' : ''})`);
@@ -278,11 +314,11 @@ export async function runInit(argv) {
 
   // 3. .mcp.json --------------------------------------------------------------
   // Written when mcpvault is wanted OR a selected companion ships an MCP server.
-  const companionMcp = companionMcpPatch(companions);
+  const companionMcp = companionMcpPatch(companions, skipMcp);
   if (args.mcp || Object.keys(companionMcp).length) {
     const mcpPath = join(projectPath, '.mcp.json');
     const mcpRead = readJsonSafe(mcpPath);
-    const mcpOpts = { vaultPath, withVault: args.mcp, companions };
+    const mcpOpts = { vaultPath, withVault: args.mcp, companions, skipMcp };
     const names = [args.mcp && MCP_SERVER_KEY, ...Object.keys(companionMcp)].filter(Boolean).join(', ');
     if (!mcpRead.ok) {
       writeJson(`${mcpPath}.new`, mergeMcp(null, mcpOpts));
@@ -309,6 +345,15 @@ export async function runInit(argv) {
   // plugin entry is already wired in settings.json regardless.
   if (companions.includes('caveman')) runCavemanInstaller(log);
 
+  // dotcontext: MCP + lifecycle hooks are wired by mergeSettings/mergeMcp above;
+  // here we seed the versioned .context/config starter and print the gitignore note.
+  if (companions.includes('dotcontext')) {
+    const seeded = seedDotcontext(projectPath);
+    const mcpNote = skipMcp.includes('dotcontext') ? 'MCP global (project entry skipped)' : 'MCP (project)';
+    log(`\n  dotcontext: ${mcpNote} + hooks(${dotcontextHookLevel}); .context/config seeded (${seeded.length} file(s)).`);
+    log(`  [!] add to .gitignore (wendkeep não toca git): ${DOTCONTEXT_GITIGNORE.join(' ')}`);
+  }
+
   log('\nNext steps:');
   log(`  1. Open the vault in Obsidian: "Open folder as vault" -> ${vaultPath}`);
   log('  2. Make sure wendkeep is installed where the agent runs (npm i -D wendkeep, or -g).');

package/src/skills-seed.mjs

@@ -0,0 +1,163 @@
+// src/skills-seed.mjs — native, zero-dep process skills (Pilar A: the HOW layer).
+// Seeded into the vault's .brain/skills; distributed by `wendkeep sync-defs` to
+// .claude/skills. Wendkeep-flavored (reference change/verify), concise native prose.
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function skill(name, description, body) {
+  return { name, description, body: `---\nname: ${name}\ndescription: ${description}\n---\n${body}` };
+}
+
+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.
+
+## Os passos
+
+1. **Explore** — entenda o problema antes de propor. Leia o código/contexto relevante.
+2. **Propose** — \`wendkeep change new <slug>\`. Isso cria \`08-Mudanças/<slug>/\` com:
+   - \`proposta.md\` — *por quê* e *o que muda* (o WHAT).
+   - \`design.md\` — a abordagem técnica.
+   - \`tarefas.md\` — a lista de tarefas \`- [ ] N.N descrição\`.
+   A mudança vira a *ativa* (ponteiro \`.brain/CURRENT_CHANGE.md\`) e é injetada no
+   próximo SessionStart, então você retoma o trabalho em curso automaticamente.
+3. **Apply** — implemente cada tarefa de \`tarefas.md\` com disciplina **wk-tdd**
+   (teste vermelho antes do código). Marque \`- [x]\` ao concluir cada uma.
+   Em tarefas cujo resultado precisa de *prova*, declare o sensor no fim da linha:
+   \`- [ ] 2.1 valida CORE [sensor:memory-validation]\`.
+4. **Verify** — \`wendkeep verify\`. Roda os sensores declarados pelas tarefas e grava
+   \`evidencia.json\`. Verde = prova registrada.
+5. **Archive** — \`wendkeep change archive <slug>\`. O *gate* trava se algum sensor
+   declarado não estiver verde. Passando, move a mudança pro \`_arquivo\` e gera um ADR
+   em \`04-Decisões/\`.
+
+## Regras
+
+- Uma mudança ativa por vez. Termine (archive) antes de abrir outra.
+- Se uma tarefa não precisa de prova automatizada, não declare sensor — o gate só exige
+  o que você declarou. Sem \`[sensor:]\`, o archive não trava.
+- A proposta linka a sessão de origem; a sessão linka a mudança ativa. É de propósito:
+  o grafo do Obsidian mostra plano↔sessão↔decisão.
+`;
+
+const TDD = `# TDD — Red, Green, Refactor
+
+Use ao implementar qualquer comportamento. Nunca escreva código de produção sem um
+teste vermelho pedindo por ele.
+
+## O ciclo
+
+1. **Red** — escreva o menor teste que falha por faltar o comportamento desejado.
+2. **Rode e veja falhar** — confirme que falha *pelo motivo certo* (não por erro de
+   import/typo). Um teste que nunca falhou não prova nada.
+3. **Green** — o código mínimo que faz o teste passar. Nada além disso.
+4. **Refactor** — limpe com os testes verdes te protegendo. Rode de novo.
+
+## Regras
+
+- Um comportamento por teste. Nome do teste descreve o comportamento, não a implementação.
+- Passos pequenos: um ciclo red→green leva minutos, não horas.
+- Não teste detalhe interno que você vai refatorar — teste a interface observável.
+- Bug encontrado = primeiro um teste que o reproduz (vermelho), depois a correção (verde).
+`;
+
+const DEBUGGING = `# Depuração sistemática
+
+Use quando algo falha, quebra ou dá resultado errado. Uma hipótese por vez — não saia
+mudando coisas no escuro.
+
+## O método
+
+1. **Reproduza** — um caso mínimo e determinístico que dispara a falha. Sem repro
+   confiável, você não sabe se corrigiu.
+2. **Uma hipótese** — a causa mais provável, específica o suficiente pra testar.
+3. **Isole** — confirme ou descarte a hipótese ANTES de corrigir: bisect, log no ponto
+   suspeito, comente metade. Prove onde está, não onde você acha que está.
+4. **Corrija a raiz** — o defeito real, não o sintoma. Se só some o sintoma, você não
+   entendeu a causa.
+5. **Verifique** — o repro do passo 1 sumiu E a suíte segue verde. Sem regressão.
+
+## Regras
+
+- Mudou várias coisas de uma vez e "consertou"? Você não sabe o que consertou. Reverta,
+  isole uma variável por vez.
+- Leia a mensagem de erro inteira e a stack — a linha decisiva costuma estar ali.
+- "Não faz sentido" = uma suposição sua está errada. Cheque as suposições, não o improvável.
+`;
+
+const BRAINSTORMING = `# Brainstorming — ideia vira design
+
+Use quando a ideia ainda é vaga. Transforme-a num design aprovado ANTES de escrever
+qualquer código.
+
+## Como
+
+1. **Explore o contexto** — arquivos, docs, histórico relevante.
+2. **Pergunte uma coisa por vez** — propósito, restrições, critério de sucesso. Prefira
+   múltipla escolha. Não despeje dez perguntas juntas.
+3. **Proponha 2–3 abordagens** — com trade-offs e sua recomendação primeiro.
+4. **Apresente o design em seções** — escale ao tamanho do problema; confirme cada seção.
+
+## Gate rígido
+
+NÃO escreva código, scaffold nem tome ação de implementação até apresentar um design e o
+usuário aprovar. Vale pra TODO projeto, por mais simples que pareça — "simples demais pra
+precisar de design" é onde suposições não-checadas mais custam. O design pode ser curto,
+mas tem que existir e ser aprovado.
+
+Ao aprovar, o próximo passo é **wk-planning** (design → plano). Não pule pra implementação.
+`;
+
+const PLANNING = `# Planejamento — design vira plano de tarefas
+
+Use depois de um design aprovado. Produza um plano que um dev sem contexto do projeto
+consiga executar.
+
+## Antes das tarefas
+
+Mapeie os arquivos: quais criar/modificar e a responsabilidade de cada um. Arquivos que
+mudam juntos ficam juntos; um arquivo, uma responsabilidade. É aqui que a decomposição
+trava.
+
+## Tarefas bite-sized (TDD)
+
+Cada tarefa termina num entregável testável de forma independente. Cada passo é uma ação
+de 2–5 min:
+
+- Escreva o teste que falha (mostre o código do teste).
+- Rode e veja falhar (comando exato + saída esperada).
+- Implementação mínima (mostre o código).
+- Rode e veja passar.
+- Checkpoint: suíte verde.
+
+## Regras
+
+- Caminhos de arquivo exatos, sempre. Código real em cada passo — nada de "TODO",
+  "tratar erros apropriadamente", "similar à Task N".
+- DRY, YAGNI. Corte features que o design não pediu.
+- Nomes/assinaturas consistentes entre tarefas (uma função é \`x()\` em toda parte).
+`;
+
+export const WK_SKILLS = [
+  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-tdd', 'Use ao implementar qualquer comportamento — disciplina Red, Green, Refactor.', 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 — transforma ideia em design aprovado antes de código.', BRAINSTORMING),
+  skill('wk-planning', 'Use após um design aprovado — decompõe em plano de tarefas TDD bite-sized.', PLANNING),
+];
+
+// Seed each skill into <brainDir>/skills/<name>/SKILL.md if absent (non-destructive).
+export function seedWkSkills(brainDir) {
+  const created = [];
+  for (const s of WK_SKILLS) {
+    const dir = join(brainDir, 'skills', s.name);
+    mkdirSync(dir, { recursive: true });
+    const f = join(dir, 'SKILL.md');
+    if (!existsSync(f)) {
+      writeFileSync(f, s.body, 'utf8');
+      created.push(f);
+    }
+  }
+  return created;
+}

package/src/taxonomy.mjs

@@ -15,6 +15,8 @@ export const VAULT_FOLDERS = [
   '04-Decisões',
   '05-Bugs',
   '06-Aprendizados',
+  '07-Specs',
+  '08-Mudanças',
   'Templates',
   '.brain',
 ];
@@ -30,6 +32,8 @@ export const HOOK_FILES = [
   'token-usage.mjs',
   'pricing.json',
   'brain-core.mjs',
+  'change-core.mjs',
+  'sensors-core.mjs',
   'brain-inject.mjs',
   'brain-recall.mjs',
   'brain-reindex.mjs',
@@ -113,6 +117,17 @@ export const COMPANIONS = [
     // No MCP, no agnostic hook: on non-Claude agents, run its own installer
     // (see cavemanInstallCommand — npx, non-interactive, Gemini excluded).
   },
+  {
+    id: 'dotcontext',
+    label: 'dotcontext — orquestração de execução (PREVC + sensores + gate E→V)',
+    default: true,
+    // MCP-only (no Claude Code plugin). Agent-agnostic server, @latest surface.
+    mcp: { key: 'dotcontext', entry: { type: 'stdio', command: 'npx', args: ['-y', '@dotcontext/mcp@latest'], env: {} } },
+    // Lifecycle hooks via the pinned CLI; wired by wendkeep (single writer).
+    dotcontextHooks: { cliVersion: '1.1.1', source: 'claude-code' },
+    // Seed a starter .context/config (one neutral sensor).
+    contextSeed: true,
+  },
 ];
 
 const COMPANION_BY_ID = Object.fromEntries(COMPANIONS.map((c) => [c.id, c]));
@@ -139,6 +154,7 @@ export function companionSettingsPatch(ids) {
   for (const id of ids) {
     const c = COMPANION_BY_ID[id];
     if (!c) continue;
+    if (!c.marketplace || !c.plugin) continue; // MCP-only companions (e.g. dotcontext) have no plugin layer
     extraKnownMarketplaces[c.id] = { source: c.marketplace };
     enabledPlugins[`${c.plugin}@${c.id}`] = true;
   }
@@ -146,9 +162,13 @@ export function companionSettingsPatch(ids) {
 }
 
 // The .mcp.json fragment (agent-agnostic layer) for MCP-capable companions only.
-export function companionMcpPatch(ids) {
+// `skip` omits ids whose MCP is already configured elsewhere (e.g. dotcontext set
+// globally in ~/.claude.json — avoids a duplicate project-scoped server).
+export function companionMcpPatch(ids, skip = []) {
+  const skipSet = new Set(skip);
   const servers = {};
   for (const id of ids) {
+    if (skipSet.has(id)) continue;
     const c = COMPANION_BY_ID[id];
     if (c?.mcp) servers[c.mcp.key] = c.mcp.entry;
   }
@@ -158,7 +178,10 @@ export function companionMcpPatch(ids) {
 // SessionStart hook specs wendkeep must author for companions that lack a native
 // one (only Understand-Anything's domain-graph injector today). Same shape as
 // SESSION_HOOKS so the same merge logic wires them.
-export function companionHookSpecs(ids) {
+// `dotcontextHookLevel`: 'full' (SessionStart+Stop+PostToolUse), 'light' (drops the
+// per-tool PostToolUse trace hook — cuts latency when other PostToolUse hooks exist),
+// or 'none' (MCP only, no lifecycle hooks).
+export function companionHookSpecs(ids, { dotcontextHookLevel = 'full' } = {}) {
   const specs = [];
   for (const id of ids) {
     const c = COMPANION_BY_ID[id];
@@ -168,13 +191,42 @@ export function companionHookSpecs(ids) {
         matcher: null,
         name: c.wendkeepHook,
         timeout: 15,
+        order: 0,
         statusMessage: `wendkeep: ${c.id} domain graph`,
       });
     }
+    // dotcontext: lifecycle hooks (SessionStart last + Stop + PostToolUse) that
+    // dispatch to its pinned CLI. They carry an explicit `command` (not a wendkeep
+    // hook name) and order 100 so they fold AFTER wendkeep's own session hooks.
+    if (c?.dotcontextHooks && dotcontextHookLevel !== 'none') {
+      const command = dotcontextHookCommand(c.dotcontextHooks.cliVersion, c.dotcontextHooks.source);
+      const base = { command, timeout: 8, order: 100, statusMessage: `${c.id}: harness hook` };
+      specs.push({ event: 'SessionStart', matcher: null, ...base });
+      specs.push({ event: 'Stop', matcher: null, ...base });
+      if (dotcontextHookLevel === 'full') {
+        specs.push({ event: 'PostToolUse', matcher: 'Write|Edit|Bash', ...base });
+      }
+    }
   }
   return specs;
 }
 
+// The pinned dotcontext CLI hook-dispatch command (runs on each lifecycle event).
+export function dotcontextHookCommand(cliVersion, source) {
+  return `npx -y @dotcontext/cli@${cliVersion} hook dispatch --source ${source}`;
+}
+
+// .context/ subpaths that should be gitignored (runtime/cache/regenerable). wendkeep
+// does not touch git — init prints these as a note for the user to add.
+export const DOTCONTEXT_GITIGNORE = [
+  '.context/runtime/',
+  '.context/cache/',
+  '.context/logs/',
+  '.context/plans/',
+  '.context/agents/',
+  '.context/skills/',
+];
+
 // Agents wendkeep installs caveman into via its cross-agent installer. Gemini is
 // excluded on purpose: its CLI rejects caveman's agent tool names and crashes
 // (libuv assertion) mid-install. caveman has no --exclude flag — only an --only

package/src/vault-theme.mjs

@@ -29,6 +29,8 @@ const FOLDER_PALETTE = [
   ['04-Decisões', 'violet'],
   ['05-Bugs', 'red'],
   ['06-Aprendizados', 'green'],
+  ['07-Specs', 'teal'],
+  ['08-Mudanças', 'amber'],
   ['Templates', 'slate'],
 ];
 
@@ -38,6 +40,8 @@ export const NOTE_COLORS = {
   decision: { cssClass: 'topic-decision', folder: '04-Decisões', palette: 'violet' },
   bug: { cssClass: 'topic-bug', folder: '05-Bugs', palette: 'red' },
   learning: { cssClass: 'topic-learning', folder: '06-Aprendizados', palette: 'green' },
+  spec: { cssClass: 'topic-spec', folder: '07-Specs', palette: 'teal' },
+  change: { cssClass: 'topic-change', folder: '08-Mudanças', palette: 'amber' },
 };
 
 // cssclasses that get the note-accent treatment (the four note types + a home note).

package/src/verify.mjs

@@ -0,0 +1,41 @@
+// `wendkeep verify [--change <slug>]` — run a change's task sensors, record evidence.
+// Sensors run at the PROJECT root (--project or cwd); the change + evidence live in
+// the VAULT. Writes 08-Mudanças/<slug>/evidencia.json; exit 1 if a critical sensor is red.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { parseTasks, activeChange } from '../hooks/change-core.mjs';
+import { loadSensors, requiredSensors, runSensors, evaluateGate } from '../hooks/sensors-core.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 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());
+  const slug = opt(argv, '--change') || activeChange(vaultBase);
+  if (!slug) { process.stderr.write('wendkeep verify: no change (--change or active).\n'); process.exit(2); }
+
+  const changeDir = join(vaultBase, '08-Mudanças', slug);
+  let tarefas = '';
+  try { tarefas = readFileSync(join(changeDir, 'tarefas.md'), 'utf8'); }
+  catch { process.stderr.write(`wendkeep verify: change not found: ${slug}\n`); process.exit(2); }
+
+  const ids = requiredSensors(parseTasks(tarefas));
+  const sensors = loadSensors(projectRoot);
+  const evidence = runSensors(sensors, ids, { cwd: projectRoot });
+  writeFileSync(join(changeDir, 'evidencia.json'), `${JSON.stringify(evidence, null, 2)}\n`, 'utf8');
+
+  const severity = Object.fromEntries(sensors.map((s) => [s.id, s.severity || 'critical']));
+  const critical = ids.filter((id) => severity[id] !== 'warning');
+  const { ok, failing } = evaluateGate(evidence, critical);
+  for (const e of evidence) process.stdout.write(`  ${e.status === 'green' ? '✓' : '✗'} ${e.id}\n`);
+  if (!ok) { process.stderr.write(`verify: critical sensors red: ${failing.join(', ')}\n`); process.exit(1); }
+  process.stdout.write(`verify OK (${ids.length} sensor(s))\n`);
+  process.exit(0);
+}