wendkeep 0.4.0 → 0.6.1

package/CHANGELOG.md

@@ -0,0 +1,151 @@
+# Changelog
+
+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.6.1] — 2026-07-05
+
+Hardening: CI + real-world gate holes found by self-audit.
+
+### Added
+- **CI (GitHub Actions):** test + check matrix on ubuntu/windows × Node 18/20/22.
+- **Open-task gate:** `change archive` blocks while tasks are open (`- [ ]`, including mutation
+  fix-tasks `M.n` — a surviving mutant can no longer be archived). Explicit escape: `--force`.
+- **Freshness seal (`tasksHash`):** `verify --deep` fingerprints `tarefas.md` into the package
+  and verdict; the gate rejects a verdict minted against different tasks as stale. Pre-0.6.1
+  verdicts (no hash) still accepted.
+- **Auto-lesson on mutation escalation:** the 3rd surviving round records a project-local lesson.
+- **Session link in proposta:** `change new` fills `source:` with the active session (graph edge
+  proposta → sessão).
+
+### Fixed
+- `.mutation-round` now resets when the report comes back clean (a future survivor starts a
+  fresh 3-round cycle instead of instantly escalating).
+- `verify` exits 1 when mutants survive (was 0 — CI couldn't see it).
+- `.brain/lessons/` capped at 50 (oldest pruned) instead of growing unbounded.
+
+## [0.6.0] — 2026-07-05
+
+Enforcement layer (Wave B of the TLC-parity program) — closes TLC parity.
+
+### Added
+- **Discrimination sensor (`type: mutation`):** delegates to the project's mutation tool and
+  parses its mutation-testing-elements report; surviving mutants become fix tasks in the active
+  change (`- [ ] M.n mata mutante file:line`), bounded to 3 rounds before escalating.
+- **Harness self-check:** `wendkeep doctor` now validates the a2 state — an invalid
+  `wendkeep.sensors.json`, a broken `CURRENT_CHANGE` pointer, changes without a `proposta.md`,
+  an orphan `[req:]` (unknown requirement), and stale verdicts.
+- **Lessons loop:** `wendkeep lesson add "<trigger>" "<lesson>"` records a project-local lesson in
+  `.brain/lessons/`; `brain-inject` surfaces the recent ones as a `<lessons>` block at SessionStart.
+- **Auto-sizing:** `wendkeep change new <slug> --simple` scaffolds only proposta + tarefas
+  (no design / spec-delta) for trivial changes.
+- **Harness contract v1.1** (`docs/14-harness-contract.md`): the mutation + lesson formats.
+
+## [0.5.0] — 2026-07-05
+
+Verification & credibility layer (Wave A of the TLC-parity program). The gate stops being
+"green sensors" alone and starts requiring an independent verdict for changes that touch a spec.
+
+### Added
+- **Requirement IDs + traceability:** living-spec requirements carry a stable ID
+  (`### Requisito: GATE-1 — nome`); tasks reference them with `[req:<ID>]`; the archive ADR
+  lists the requirements it satisfied. Rastro req → task → verdict → ADR.
+- **`wendkeep verify --deep`:** assembles a verification package (`verificacao.json`) for an
+  independent pass. A trivial change (no `[req:]`, sensors green) gets an auto verdict.
+- **Independent verdict gate:** `change archive` now also requires `verdict.json` (`ok`, covering
+  every declared `[req:]`) for requirement-bearing changes.
+- **TLC-grade process skills:** rewrote `wk-tdd` (spec-derived assertions, non-shallow litmus,
+  test adequacy, test-learning) and `wk-brainstorming` (closure gate + out-of-scope); new
+  `wk-verify` (fresh read-only verifier, author≠verifier).
+- **Harness contract v1** (`docs/14-harness-contract.md`): the extension-point formats.
+
+### Changed
+- Requirement-less changes are unaffected — the sensor gate remains their proof. The verdict
+  requirement applies only when a change declares `[req:]` tasks. Specs from 0.4.0 (headings
+  without an ID) stay valid.
+
+## [0.4.0] — 2026-07-05
+
+Spec promotion (the living contract) + harness fixes.
+
+### Added
+- **Spec promotion** — `wendkeep change archive` merges each capability's spec delta
+  (`## ADDED` / `## MODIFIED` / `## REMOVED Requirements`) into the living
+  `07-Specs/<capability>.md`. Multi-capability per change via `specs: [slugs]` in the
+  proposta; the living spec footer wikilinks the archived change (`hooks/spec-core.mjs`).
+- Change scaffold now seeds an example spec delta at `specs/exemplo/spec.md`.
+- `wendkeep change archive` prints promoted capabilities and surfaces delta warnings
+  (ADDED-already-exists / MODIFIED-missing) without blocking.
+
+### Changed
+- `wendkeep init` now runs `sync-defs` itself — process skills and agents are delivered
+  to `.claude/skills` / `.codex/agents` immediately (no manual step).
+- The archive gate and `wendkeep verify` share one rule: only **critical** (or missing)
+  sensors block; a red `warning` sensor is advisory. Evidence records each sensor's severity.
+- README documents the change/verify/skills commands and the a2 loop.
+
+## [0.3.0] — 2026-07-05
+
+The a2 native harness — a zero-dependency spec→change→proof loop on the vault memory
+core (recreates the best of OpenSpec + dotcontext + superpowers, natively).
+
+### Added
+- **Pilar B — change lifecycle:** `wendkeep change new|list|show|archive`. Scaffolds
+  `08-Mudanças/<slug>/` (proposta/design/tarefas); the active change is injected at the
+  next `SessionStart`; archive moves the change to `_arquivo/` and mints an ADR in
+  `04-Decisões/`. New vault folders `07-Specs/`, `08-Mudanças/` (`hooks/change-core.mjs`).
+- **Pilar C — verify + gate:** `wendkeep verify` runs a change's task-declared sensors
+  (`[sensor:<id>]` hints) from a native `wendkeep.sensors.json`, records `evidencia.json`;
+  `change archive` gates on the evidence (`hooks/sensors-core.mjs`).
+- **Pilar A — process skills:** native `wk-workflow` / `wk-tdd` / `wk-debugging` /
+  `wk-brainstorming` / `wk-planning` seeded into `.brain/skills` (`src/skills-seed.mjs`).
+
+## [0.2.7] — 2026-06-30
+
+### Added
+- **Definitions layer:** `.brain/agents/` + `.brain/skills/` as versioned source of truth,
+  copied into the project with `wendkeep sync-defs`.
+- **dotcontext seed:** a starter `.context/config/sensors.json` (a `validate-memory` sensor
+  plus one per detected `package.json` script) when the dotcontext companion is selected.
+
+## [0.2.1] – [0.2.6] — 2026-06-29
+
+Rapid iteration on the companion + memory layers (same day):
+- **Companions** wired the most agent-agnostic way (context-mode / dotcontext as MCP,
+  understand-anything via a domain-graph SessionStart injector, caveman via installer).
+- **Obsidian color system** — a mode-agnostic CSS snippet (note-type accents) + graph
+  color groups, merged non-destructively into `.obsidian/`.
+- **Curated memory protocol** — `.brain/CORE.md` + `COMPACTION_PROTOCOL.md` and
+  `wendkeep validate-memory` (cap 25 lines, 3 sections, no secrets/PII).
+- Cross-platform caveman installer fix (npx non-interactive; Gemini excluded).
+- Derived notes grouped by month under the year.
+
+## [0.2.0] — 2026-06-29
+
+### Added
+- Companion plugins/MCP selection in `wendkeep init` (context-mode, understand-anything,
+  caveman) with idempotent settings/`.mcp.json` merging.
+
+## [0.1.0] — 2026-06-29
+
+Initial release — the capture engine, extracted from a system in daily production use.
+
+### Added
+- Automatic session capture (`SessionStart` / `UserPromptSubmit` / `Stop` hooks) into
+  `02-Sessões/` as turn-by-turn Markdown.
+- Multi-agent provider detection (Claude Code, Codex, Copilot).
+- Token & cost tracking (cache-aware `pricing.json`).
+- Auto-extracted derived notes (decisions / bugs / learnings), backlinked to the session.
+- Curated memory (`.brain/` cold index + `CORE` + `DIGEST` injected at `SessionStart`).
+- `wendkeep init` (cross-platform installer) + optional `@bitbonsai/mcpvault` MCP server.
+
+<!-- Only v0.4.0+ is tagged in git (history starts here); older versions link to npm. -->
+[0.6.1]: https://github.com/rogersialves/wendkeep/releases/tag/v0.6.1
+[0.6.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.6.0
+[0.5.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.5.0
+[0.4.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.4.0
+[0.3.0]: https://www.npmjs.com/package/wendkeep/v/0.3.0
+[0.2.7]: https://www.npmjs.com/package/wendkeep/v/0.2.7
+[0.2.0]: https://www.npmjs.com/package/wendkeep/v/0.2.0
+[0.1.0]: https://www.npmjs.com/package/wendkeep/v/0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roger Alves
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,7 @@
 # wendkeep
 
+![test](https://github.com/rogersialves/wendkeep/actions/workflows/test.yml/badge.svg)
+
 **A persistent‑memory harness for AI coding agents, built on your Obsidian vault.** Every Claude Code / Codex session is captured turn‑by‑turn into local Markdown — with token/cost tracking, auto‑extracted decisions, bugs and learnings, and a curated memory layer injected back at the start of the next session. On top of that memory core sits a native, zero‑dependency **change lifecycle** (spec → change → TDD → sensor‑gated archive) that keeps intent, work and proof wikilinked in one graph. 100% local, open‑core.
 
 > Status: `v0.1` — extracted from a system in daily production use. The capture engine, cost tracking and graph wiring are battle‑tested; the cross‑platform installer (`wendkeep init`) is the new part. See [`docs/`](docs/) for the project's strategy and decision log.

package/bin/wendkeep.mjs

@@ -45,6 +45,7 @@ Usage:
   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 lesson add "t" "l"   Record a project-local lesson (injected at SessionStart).
   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.
@@ -111,6 +112,11 @@ async function main() {
       runVerify(rest);
       break;
     }
+    case 'lesson': {
+      const { runLesson } = await import('../src/lessons.mjs');
+      runLesson(rest);
+      break;
+    }
     case '--version':
     case '-v':
       process.stdout.write(`${version()}\n`);

package/hooks/brain-inject.mjs

@@ -8,6 +8,7 @@ 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';
+import { buildLessonsInjection } from './lessons-core.mjs';
 
 const MAX_LINES = 45; // CORE ≤25 + DIGEST ≤15 + folga; salvaguarda se o CORE crescer à mão
 
@@ -26,7 +27,8 @@ export function buildInjection(vaultBase) {
   }
   const brain = ['<brain_memory>', ...lines, pointer, '</brain_memory>'].join('\n');
   const change = buildActiveChangeInjection(vaultBase);
-  return change ? `${brain}\n${change}` : brain;
+  const lessons = buildLessonsInjection(vaultBase);
+  return [brain, change, lessons].filter(Boolean).join('\n');
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/hooks/change-core.mjs

@@ -79,7 +79,7 @@ export function clearActiveChange(vaultBase) {
   if (existsSync(p)) writeFileSync(p, 'change:\n', 'utf8');
 }
 
-export function newChange(vaultBase, slug, { sessionRel = '', dateStr }) {
+export function newChange(vaultBase, slug, { sessionRel = '', dateStr, simple = false }) {
   const dir = join(vaultBase, CHANGES_DIR, slug);
   const existed = existsSync(join(dir, 'proposta.md'));
   mkdirSync(dir, { recursive: true });
@@ -89,13 +89,15 @@ export function newChange(vaultBase, slug, { sessionRel = '', dateStr }) {
     if (!existsSync(f)) writeFileSync(f, content, 'utf8');
   };
   write('proposta.md', files.proposta);
-  write('design.md', files.design);
   write('tarefas.md', files.tarefas);
-  // Seed an example spec delta so the promotion format is discoverable.
-  const exampleDelta = join(dir, 'specs', 'exemplo', 'spec.md');
-  if (!existsSync(exampleDelta)) {
-    mkdirSync(join(dir, 'specs', 'exemplo'), { recursive: true });
-    writeFileSync(exampleDelta, files.specDelta, 'utf8');
+  // Auto-sizing (Wave B): a --simple change skips the design + spec-delta scaffold.
+  if (!simple) {
+    write('design.md', files.design);
+    const exampleDelta = join(dir, 'specs', 'exemplo', 'spec.md');
+    if (!existsSync(exampleDelta)) {
+      mkdirSync(join(dir, 'specs', 'exemplo'), { recursive: true });
+      writeFileSync(exampleDelta, files.specDelta, 'utf8');
+    }
   }
   setActiveChange(vaultBase, slug);
   return { rel: changeDirRel(slug), created: !existed };
@@ -105,13 +107,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+)\]/;
   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 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 } : {}) });
+    const req = rm ? rm[1] : undefined;
+    if (sm) text = text.replace(sensorRe, '');
+    if (rm) text = text.replace(reqRe, '');
+    text = text.replace(/\s+/g, ' ').trim();
+    tasks.push({ id: m[2], text, done: m[1] === 'x', ...(sensor ? { sensor } : {}), ...(req ? { req } : {}) });
   }
   return tasks;
 }
@@ -151,6 +158,29 @@ export function activeChangeLink(vaultBase) {
   return slug ? `Change ativa: [[${CHANGES_DIR}/${slug}/proposta]]` : '';
 }
 
+// Append fix tasks for surviving mutants to a change's tarefas.md (Wave B). Deduped by
+// file:line, numbered M.<n> continuing from any existing fix tasks. Returns count added.
+export function appendFixTasks(changeDir, mutants, sensorId) {
+  const path = join(changeDir, 'tarefas.md');
+  let md = '';
+  try { md = readFileSync(path, 'utf8'); } catch { /* nova */ }
+  const existing = new Set([...md.matchAll(/mata mutante (\S+):(\d+)/g)].map((m) => `${m[1]}:${m[2]}`));
+  const nums = [...md.matchAll(/^-\s+\[[ x]\]\s+M\.(\d+)\b/gm)].map((m) => Number(m[1]));
+  let n = nums.length ? Math.max(...nums) : 0;
+  const lines = [];
+  for (const mut of mutants || []) {
+    const key = `${mut.file}:${mut.line}`;
+    if (existing.has(key)) continue;
+    existing.add(key);
+    n += 1;
+    lines.push(`- [ ] M.${n} mata mutante ${mut.file}:${mut.line} (${mut.mutator}) [sensor:${sensorId}]`);
+  }
+  if (!lines.length) return 0;
+  const sep = md === '' || md.endsWith('\n') ? '' : '\n';
+  writeFileSync(path, `${md}${sep}${lines.join('\n')}\n`, 'utf8');
+  return lines.length;
+}
+
 // Gate seam (Pilar B stub; Pilar C replaces with real sensor evidence).
 export function gateGreen() {
   return { ok: true, failing: [] };
@@ -176,6 +206,9 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
     }
   } catch { /* proposta ilegível — segue só com ADR */ }
 
+  let reqIds = [];
+  try { reqIds = [...new Set(parseTasks(readFileSync(join(src, 'tarefas.md'), 'utf8')).map((t) => t.req).filter(Boolean))]; } catch { /* sem tarefas */ }
+
   ensureDir(join(vaultBase, CHANGES_DIR, ARCHIVE_DIR));
   renameSync(src, join(vaultBase, destRel));
 
@@ -187,6 +220,7 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
   const capLine = promoted.length
     ? `\n\nCapabilities: ${promoted.map((c) => wikilinkFromRel(join(SPECS_DIR, c))).join(', ')}.`
     : '';
+  const reqLine = reqIds.length ? `\n\nRequisitos: ${reqIds.join(', ')}.` : '';
   writeFileSync(join(vaultBase, adrRel), `---
 type: decision
 status: accepted
@@ -201,7 +235,7 @@ tags:
 
 ## Decisão
 
-Mudança ${changeWikilink} concluída e arquivada.${capLine}
+Mudança ${changeWikilink} concluída e arquivada.${capLine}${reqLine}
 `, 'utf8');
 
   clearActiveChange(vaultBase);

package/hooks/harness-doctor.mjs

@@ -0,0 +1,77 @@
+// hooks/harness-doctor.mjs — integrity checks for the a2 harness state (Wave B).
+// Pure-ish (fs reads only). `wendkeep doctor` reports errors (exit 1) + warnings.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { activeChange, parseTasks } from './change-core.mjs';
+import { parseRequirements, parseSpecsList, parseDelta, evaluateVerdict } from './spec-core.mjs';
+
+const CHANGES_DIR = '08-Mudanças';
+const SPECS_DIR = '07-Specs';
+
+export function checkHarness(vaultBase, projectRoot) {
+  const errors = [];
+  const warnings = [];
+
+  // 1. wendkeep.sensors.json well-formed.
+  const sensorsPath = join(projectRoot, 'wendkeep.sensors.json');
+  if (existsSync(sensorsPath)) {
+    try {
+      const data = JSON.parse(readFileSync(sensorsPath, 'utf8'));
+      if (!Array.isArray(data.sensors)) errors.push('wendkeep.sensors.json: "sensors" não é lista');
+      else for (const s of data.sensors) if (!s.id || !s.command) errors.push(`sensor sem id/command: ${JSON.stringify(s.id || '?')}`);
+    } catch { errors.push('wendkeep.sensors.json: JSON inválido'); }
+  }
+
+  // Known requirement ids across the living specs (+ spec-without-source warning).
+  const knownReqs = new Set();
+  try {
+    for (const f of readdirSync(join(vaultBase, SPECS_DIR))) {
+      if (!f.endsWith('.md') || f === 'README.md') continue;
+      const md = readFileSync(join(vaultBase, SPECS_DIR, f), 'utf8');
+      for (const r of parseRequirements(md)) if (r.id) knownReqs.add(r.id);
+      if (!/^>\s+Atualizado por/m.test(md)) warnings.push(`spec sem origem: ${SPECS_DIR}/${f}`);
+    }
+  } catch { /* sem 07-Specs */ }
+
+  // 2/3. Changes: malformed dirs; the active change's deltas add to knownReqs.
+  const active = activeChange(vaultBase);
+  let names = [];
+  try { names = readdirSync(join(vaultBase, CHANGES_DIR)).filter((n) => n !== '_arquivo'); } catch { /* none */ }
+  for (const name of names) {
+    const dir = join(vaultBase, CHANGES_DIR, name);
+    let entries;
+    try { entries = readdirSync(dir); } catch { continue; } // a file, not a change dir
+    if (!entries.includes('proposta.md')) { errors.push(`change sem proposta.md: ${name}`); continue; }
+    if (name === active) {
+      try {
+        for (const cap of parseSpecsList(readFileSync(join(dir, 'proposta.md'), 'utf8'))) {
+          try {
+            const d = parseDelta(readFileSync(join(dir, 'specs', cap, 'spec.md'), 'utf8'));
+            for (const r of [...d.added, ...d.modified]) if (r.id) knownReqs.add(r.id);
+          } catch { /* sem delta pra essa cap */ }
+        }
+      } catch { /* proposta ilegível */ }
+    }
+  }
+
+  // 4/5. Active-change pointer resolves; [req:] orphans; stale verdict.
+  if (active) {
+    const dir = join(vaultBase, CHANGES_DIR, active);
+    if (!existsSync(join(dir, 'proposta.md'))) {
+      errors.push(`ponteiro CURRENT_CHANGE aponta pra change inexistente: ${active}`);
+    } else {
+      let tasks = [];
+      try { tasks = parseTasks(readFileSync(join(dir, 'tarefas.md'), 'utf8')); } catch { /* sem tarefas */ }
+      const reqIds = [...new Set(tasks.map((t) => t.req).filter(Boolean))];
+      for (const rid of reqIds) if (!knownReqs.has(rid)) errors.push(`req órfão em ${active}: [req:${rid}] não existe em 07-Specs nem no delta`);
+      let verdict = null;
+      try { verdict = JSON.parse(readFileSync(join(dir, 'verdict.json'), 'utf8')); } catch { /* sem verdict */ }
+      if (verdict && reqIds.length) {
+        const v = evaluateVerdict(verdict, reqIds);
+        if (!v.ok) warnings.push(`verdict stale em ${active}: falta cobrir ${v.missing.join(', ')}`);
+      }
+    }
+  }
+
+  return { errors, warnings };
+}

package/hooks/lessons-core.mjs

@@ -0,0 +1,52 @@
+// hooks/lessons-core.mjs — project-local lessons from verification failures (Wave B).
+// A failure distilled into a terse lesson; brain-inject surfaces the recent ones at
+// SessionStart so the framework gets sharper on your codebase. No external deps.
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const MAX_LESSONS = 50; // dir cap (#7): oldest (filename asc = date asc) pruned first
+
+function slugify(s) {
+  return String(s)
+    .toLowerCase()
+    .normalize('NFD').replace(/[̀-ͯ]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 50) || 'licao';
+}
+
+export function addLesson(vaultBase, { trigger, lesson, sourceChange = '', dateStr = '' }) {
+  const dir = join(vaultBase, '.brain', 'lessons');
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${dateStr ? `${dateStr}-` : ''}${slugify(trigger)}.md`);
+  writeFileSync(
+    path,
+    `---\ntype: lesson\ntrigger: ${JSON.stringify(String(trigger))}\nsource: ${sourceChange}\ndate: ${dateStr}\n---\n\n${lesson}\n`,
+    'utf8',
+  );
+  // Cap the directory (#7): prune oldest-by-name (date-prefixed = chronological).
+  try {
+    const files = readdirSync(dir).filter((f) => f.endsWith('.md')).sort();
+    for (const f of files.slice(0, Math.max(0, files.length - MAX_LESSONS))) {
+      unlinkSync(join(dir, f));
+    }
+  } catch { /* prune é bônus */ }
+  return path;
+}
+
+// Compact <lessons> block of the most recent lessons (filename-sorted desc; a date prefix
+// makes that chronological). Budget-capped by `max`. '' when there are none.
+export function buildLessonsInjection(vaultBase, { max = 5 } = {}) {
+  const dir = join(vaultBase, '.brain', 'lessons');
+  let files;
+  try { files = readdirSync(dir).filter((f) => f.endsWith('.md')).sort().reverse().slice(0, max); }
+  catch { return ''; }
+  const lines = [];
+  for (const f of files) {
+    try {
+      const body = readFileSync(join(dir, f), 'utf8').replace(/^---[\s\S]*?---\n/, '').trim().split('\n')[0];
+      if (body) lines.push(`- ${body}`);
+    } catch { /* skip */ }
+  }
+  return lines.length ? `<lessons>\nLições do projeto (de falhas anteriores):\n${lines.join('\n')}\n</lessons>` : '';
+}

package/hooks/sensors-core.mjs

@@ -26,11 +26,33 @@ export function runSensors(sensors, ids, { spawn = spawnSync, cwd, now } = {}) {
     const s = byId[id];
     if (!s) { evidence.push({ id, status: 'red', ts, severity: 'critical', 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, severity: s.severity || 'critical' });
+    const entry = { id, status: (r.status ?? 1) === 0 ? 'green' : 'red', ts, severity: s.severity || 'critical' };
+    if (s.type === 'mutation' && s.report) {
+      // Delegated mutation (Wave B): read the tool's mutation-testing-elements report and
+      // attach surviving mutants so verify can turn them into fix tasks.
+      try { entry.survivors = parseMutationReport(JSON.parse(readFileSync(join(cwd || '.', s.report), 'utf8'))); }
+      catch { /* report ausente/ilegível — segue só com o exit code */ }
+    }
+    evidence.push(entry);
   }
   return evidence;
 }
 
+// Parse a mutation-testing-elements report (Stryker et al.): return surviving mutants
+// (Survived | NoCoverage) as {file, line, mutator}.
+export function parseMutationReport(json) {
+  const out = [];
+  const files = json && json.files ? json.files : {};
+  for (const [file, data] of Object.entries(files)) {
+    for (const m of (data && data.mutants) || []) {
+      if (m.status === 'Survived' || m.status === 'NoCoverage') {
+        out.push({ file, line: m.location && m.location.start ? m.location.start.line : null, mutator: m.mutatorName || 'unknown' });
+      }
+    }
+  }
+  return out;
+}
+
 // A required sensor blocks the gate when it is missing (never verified) or red at a
 // non-warning severity. Warnings are advisory: a red warning does not block archive.
 // Severity comes from the evidence entry (written by runSensors); absent -> critical.

package/hooks/spec-core.mjs

@@ -1,9 +1,15 @@
 // hooks/spec-core.mjs — living spec (07-Specs) + change delta merge (OpenSpec native).
 // Pure parsing/merge + promoteSpecs (fs). No import from change-core (avoids a cycle).
+import { createHash } from 'node:crypto';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ensureDir } from './obsidian-common.mjs';
 
+// Short stable fingerprint of tarefas.md — freshness check between package/verdict and gate.
+export function tasksHashOf(md) {
+  return createHash('sha1').update(String(md)).digest('hex').slice(0, 12);
+}
+
 const SPECS_DIR = '07-Specs';
 const REQ_RE = /^### Requisito:\s*(.+)$/gm;
 
@@ -12,11 +18,15 @@ export function parseRequirements(md) {
   const matches = [...text.matchAll(REQ_RE)];
   const reqs = [];
   for (let i = 0; i < matches.length; i += 1) {
-    const name = matches[i][1].trim();
+    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]*-\d+)\s*—\s*(.+)$/);
+    const id = idM ? idM[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;
     const body = text.slice(start, end).replace(/(\n>[^\n]*)+\s*$/, '').trim();
-    reqs.push({ name, body });
+    reqs.push({ id, name, body });
   }
   return reqs;
 }
@@ -33,35 +43,36 @@ export function parseDelta(md) {
   return {
     added: parseRequirements(grab('ADDED')),
     modified: parseRequirements(grab('MODIFIED')),
-    removed: parseRequirements(grab('REMOVED')).map((r) => r.name),
+    removed: parseRequirements(grab('REMOVED')).map((r) => r.id || r.name),
   };
 }
 
 export function applyDelta(reqs, delta) {
-  const order = reqs.map((r) => r.name);
-  const map = new Map(reqs.map((r) => [r.name, r.body]));
+  const keyOf = (r) => r.id || r.name; // identity = ID when present, else the name
+  const order = reqs.map(keyOf);
+  const map = new Map(reqs.map((r) => [keyOf(r), r])); // key -> full {id,name,body}
   const warnings = [];
   for (const r of delta.added || []) {
-    if (map.has(r.name)) warnings.push(`ADDED já existe: ${r.name}`); else order.push(r.name);
-    map.set(r.name, r.body);
+    const k = keyOf(r);
+    if (map.has(k)) warnings.push(`ADDED já existe: ${k}`); else order.push(k);
+    map.set(k, r);
   }
   for (const r of delta.modified || []) {
-    if (!map.has(r.name)) { warnings.push(`MODIFIED inexistente: ${r.name}`); order.push(r.name); }
-    map.set(r.name, r.body);
+    const k = keyOf(r);
+    if (!map.has(k)) { warnings.push(`MODIFIED inexistente: ${k}`); order.push(k); }
+    map.set(k, r);
   }
-  for (const name of delta.removed || []) {
-    if (!map.has(name)) warnings.push(`REMOVED inexistente: ${name}`);
-    map.delete(name);
+  for (const k of delta.removed || []) {
+    if (!map.has(k)) warnings.push(`REMOVED inexistente: ${k}`);
+    map.delete(k);
   }
   const seen = new Set();
-  const out = order
-    .filter((n) => map.has(n) && !seen.has(n) && seen.add(n))
-    .map((n) => ({ name: n, body: map.get(n) }));
+  const out = order.filter((k) => map.has(k) && !seen.has(k) && seen.add(k)).map((k) => map.get(k));
   return { reqs: out, warnings };
 }
 
 export function renderSpec(capability, reqs, { footer } = {}) {
-  const blocks = reqs.map((r) => `### Requisito: ${r.name}\n${r.body}`).join('\n\n');
+  const blocks = reqs.map((r) => `### Requisito: ${r.id ? `${r.id} — ${r.name}` : r.name}\n${r.body}`).join('\n\n');
   const foot = footer ? `\n\n> ${footer}\n` : '\n';
   return `---\ntype: spec\ncssclasses:\n  - topic-spec\ntags:\n  - spec\n---\n\n# ${capability}\n\n## Requisitos\n\n${blocks}${foot}`;
 }
@@ -95,3 +106,20 @@ export function promoteSpecs(vaultBase, changeDir, specs, { changeWikilink, date
   }
   return { promoted, warnings };
 }
+
+// Gate check for the independent verdict (Wave A). A requirement-bearing change must have
+// a verdict that is ok and covers every declared req id. A requirement-less change passes:
+// nothing for an independent verifier to check — the sensor gate is already the proof.
+export function evaluateVerdict(verdict, reqIds, { tasksHash } = {}) {
+  const ids = reqIds || [];
+  if (ids.length === 0) return { ok: true, missing: [] };
+  if (!verdict || verdict.ok !== true) return { ok: false, missing: [] };
+  // Freshness (G3/#6): a verdict minted against a different tarefas.md is stale. Verdicts
+  // without a hash (pre-0.6.1) are accepted for backward compat.
+  if (tasksHash && verdict.tasksHash && verdict.tasksHash !== tasksHash) {
+    return { ok: false, missing: [], stale: true };
+  }
+  const covered = new Set((verdict.coverage || []).filter((c) => c.covered).map((c) => c.req));
+  const missing = ids.filter((r) => !covered.has(r));
+  return { ok: missing.length === 0, missing };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.4.0",
+  "version": "0.6.1",
   "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": {
@@ -11,7 +11,8 @@
     "bin",
     "src",
     "hooks",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18"
@@ -32,5 +33,13 @@
     "token-cost"
   ],
   "author": "Roger Alves",
-  "license": "MIT"
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rogersialves/wendkeep.git"
+  },
+  "homepage": "https://github.com/rogersialves/wendkeep#readme",
+  "bugs": {
+    "url": "https://github.com/rogersialves/wendkeep/issues"
+  }
 }

package/src/change.mjs

@@ -9,7 +9,8 @@ import {
   archiveChange,
 } from '../hooks/change-core.mjs';
 import { evaluateGate, requiredSensors } from '../hooks/sensors-core.mjs';
-import { getNextAdrNumber } from '../hooks/obsidian-common.mjs';
+import { evaluateVerdict, tasksHashOf } from '../hooks/spec-core.mjs';
+import { getNextAdrNumber, readControl } from '../hooks/obsidian-common.mjs';
 
 function resolveVault(argv) {
   let vault;
@@ -39,7 +40,10 @@ export function runChange(argv) {
   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() });
+    // G2: link the active session into the proposta's source: (graph edge proposta->sessão).
+    let sessionRel = '';
+    try { sessionRel = readControl(vaultBase).session_file || ''; } catch { /* sem control */ }
+    const r = newChange(vaultBase, slug, { dateStr: today(), simple: rest.includes('--simple'), sessionRel });
     process.stdout.write(`change ${r.created ? 'created' : 'exists'}: ${r.rel} (active)\n`);
     process.exit(0);
   }
@@ -70,15 +74,33 @@ export function runChange(argv) {
     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 tarefasMd = '';
+      try { tarefasMd = readFileSync(join(dir, 'tarefas.md'), 'utf8'); } catch { /* no tasks */ }
+      const tasks = parseTasks(tarefasMd);
+      // G1: uma change não arquiva com tarefa aberta (inclui fix-tasks M.n de mutação).
+      const open = tasks.filter((t) => !t.done);
+      if (open.length && !rest.includes('--force')) {
+        return { ok: false, failing: [`${open.length} tarefa(s) aberta(s) (ex.: ${open[0].id} ${open[0].text}) — conclua ou use --force`] };
+      }
+      const required = requiredSensors(tasks);
+      const reqIds = [...new Set(tasks.map((t) => t.req).filter(Boolean))];
       let evidence = [];
       try { evidence = JSON.parse(readFileSync(join(dir, 'evidencia.json'), 'utf8')); } catch { /* no evidence */ }
-      return evaluateGate(evidence, required);
+      const s = evaluateGate(evidence, required);
+      if (!s.ok) return s;
+      // Independent verdict (Wave A): required only when the change declares [req:] tasks.
+      let verdict = null;
+      try { verdict = JSON.parse(readFileSync(join(dir, 'verdict.json'), 'utf8')); } catch { /* none */ }
+      const v = evaluateVerdict(verdict, reqIds, { tasksHash: tasksHashOf(tarefasMd) });
+      if (!v.ok) {
+        if (v.stale) return { ok: false, failing: ['verdict stale (tarefas.md mudou depois da verificação) — re-verifique: `wendkeep verify --deep` + wk-verify'] };
+        return { ok: false, failing: verdict ? [`verdict incompleto: falta ${v.missing.join(', ')}`] : ['sem verdict — rode `wendkeep verify --deep` + skill wk-verify'] };
+      }
+      return { ok: true, failing: [] };
     };
     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.stderr.write(`change archive BLOCKED (gate): ${r.failing.join('; ')}\n`);
       process.exit(1);
     }
     process.stdout.write(`archived: ${r.archivedRel}; ADR: ${r.adrRel}\n`);

package/src/doctor.mjs

@@ -1,36 +1,48 @@
-// `wendkeep doctor` — run the bundled vault-health check against a vault.
-// Resolves the vault from --vault or the OBSIDIAN_VAULT_PATH env var, then runs
-// hooks/vault-health.mjs (which reads getVaultBase()).
+// `wendkeep doctor` — vault/session integrity (hooks/vault-health.mjs) PLUS the a2
+// 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 { fileURLToPath } from 'node:url';
+import { checkHarness } from '../hooks/harness-doctor.mjs';
 
 export function runDoctor(argv) {
   const here = dirname(fileURLToPath(import.meta.url));
   const hookFile = join(here, '..', 'hooks', 'vault-health.mjs');
-  if (!existsSync(hookFile)) {
-    process.stderr.write(`wendkeep doctor: vault-health.mjs not found at ${hookFile}\n`);
-    process.exit(2);
-  }
 
   let vault;
+  let project;
   const passthrough = [];
   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);
+    else if (a === '--project') project = argv[++i];
+    else if (a.startsWith('--project=')) project = a.slice(10);
     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');
     process.exit(2);
   }
+  const vaultBase = env.OBSIDIAN_VAULT_PATH;
+  const projectRoot = resolve(project || process.cwd());
+
+  // 1. Session/vault integrity (existing check).
+  let healthStatus = 0;
+  if (existsSync(hookFile)) {
+    const r = spawnSync(process.execPath, [hookFile, ...passthrough], { stdio: 'inherit', env });
+    healthStatus = r.status ?? 0;
+  }
+
+  // 2. Harness integrity (Wave B).
+  const { errors, warnings } = checkHarness(vaultBase, projectRoot);
+  process.stdout.write(`\n[harness] ${errors.length} erro(s), ${warnings.length} aviso(s)\n`);
+  for (const e of errors) process.stdout.write(`  ✗ ${e}\n`);
+  for (const w of warnings) process.stdout.write(`  ! ${w}\n`);
 
-  const r = spawnSync(process.execPath, [hookFile, ...passthrough], { stdio: 'inherit', env });
-  process.exit(r.status ?? 0);
+  process.exit(healthStatus !== 0 || errors.length ? 1 : 0);
 }

package/src/lessons.mjs

@@ -0,0 +1,35 @@
+// `wendkeep lesson add "<trigger>" "<lesson>"` — record a project-local lesson (Wave B).
+// The wk-verify / wk-debugging skills call this when a verification fails.
+import { isAbsolute, resolve } from 'node:path';
+import { addLesson } from '../hooks/lessons-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;
+}
+
+function today() {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+export function runLesson(argv) {
+  const [sub, ...rest] = argv;
+  if (sub !== 'add') {
+    process.stderr.write(`wendkeep lesson: unknown "${sub}". Use: lesson add "<trigger>" "<lesson>"\n`);
+    process.exit(2);
+  }
+  const vaultRaw = opt(rest, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
+  if (!vaultRaw) { process.stderr.write('wendkeep lesson: no vault (--vault or OBSIDIAN_VAULT_PATH).\n'); process.exit(2); }
+  const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);
+
+  const positional = rest.filter((a, i) => !a.startsWith('--') && rest[i - 1] !== '--vault' && rest[i - 1] !== '--change');
+  const [trigger, lesson] = positional;
+  if (!trigger || !lesson) { process.stderr.write('wendkeep lesson add: precisa "<trigger>" "<lesson>"\n'); process.exit(2); }
+
+  const p = addLesson(vaultBase, { trigger, lesson, sourceChange: opt(rest, '--change') || '', dateStr: today() });
+  process.stdout.write(`lesson: ${p}\n`);
+  process.exit(0);
+}

package/src/skills-seed.mjs

@@ -23,14 +23,19 @@ Use ao começar qualquer mudança não-trivial. O loop mantém memória (vault)
    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/\`.
+   (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 de \`07-Specs\`.
+   Ex.: \`- [ ] 2.1 valida CORE [req:MEM-1] [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,
+   re-deriva a cobertura do \`07-Specs\` e grava \`verdict.json\`. Change trivial (sem
+   \`[req:]\`) recebe verdict automático — pula este passe.
+6. **Archive** — \`wendkeep change archive <slug>\`. O *gate* exige sensores verdes **E**
+   \`verdict.json\` cobrindo os \`[req:]\`. Passando, promove os deltas pro \`07-Specs\`,
+   move a change pro \`_arquivo\` e gera um ADR em \`04-Decisões/\`.
 
 ## Regras
 
@@ -41,25 +46,46 @@ Use ao começar qualquer mudança não-trivial. O loop mantém memória (vault)
   o grafo do Obsidian mostra plano↔sessão↔decisão.
 `;
 
-const TDD = `# TDD — Red, Green, Refactor
+const TDD = `# TDD — Red, Green, Refactor (testes que discriminam)
 
-Use ao implementar qualquer comportamento. Nunca escreva código de produção sem um
-teste vermelho pedindo por ele.
+Use ao implementar qualquer comportamento. Nunca escreva código de produção sem um teste
+vermelho pedindo por ele — e nunca escreva um teste que passaria sob a implementação errada.
 
 ## 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.
+1. **Red** — o menor teste que falha por faltar o comportamento.
+2. **Rode e veja falhar** — pelo motivo certo (não import/typo). Teste que nunca falhou não prova nada.
+3. **Green** — o código mínimo pra passar.
+4. **Refactor** — limpe com os verdes te protegendo.
+
+## Derive do spec, não do código
+
+Escreva a asserção a partir do *critério de aceite* do requisito (\`07-Specs\`), não lendo a
+implementação. Cada asserção mira o resultado que o spec definiu. Escrever o teste lendo o
+código = ele só confirma o que o código já faz, bugs inclusos.
+
+## Litmus não-raso
+
+Rejeite asserção que passaria sob uma implementação errada. Afirme **valor ou estado
+persistido**, nunca "o mock foi chamado". "Testado depois" é rejeitado — o teste nasce
+junto com o código da tarefa.
+
+## Adequação (necessário e suficiente)
+
+- Todo critério de aceite tem uma asserção — com evidência \`arquivo:linha\`.
+- Todo teste rastreia um requisito (\`[req:ID]\`). Teste sem requisito = escopo à toa.
+- Nem raso, nem inflado: cobre o que o spec pede, nada além.
+
+## Aprende o projeto
+
+Antes de escrever, amostre 5–10 testes existentes: estilo, localização, framework,
+profundidade por camada — trate essa profundidade como *piso*, nunca teto. Leia
+\`AGENTS.md\` / \`.cursor/rules\` / configs de CI pros padrões declarados.
 
 ## 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).
+- Um comportamento por teste; o nome descreve o comportamento, não a implementação.
+- Bug encontrado = primeiro o teste que o reproduz (vermelho), depois a correção.
 `;
 
 const DEBUGGING = `# Depuração sistemática
@@ -99,6 +125,17 @@ qualquer código.
 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.
 
+## Closure gate — nada de ambiguidade solta
+
+Antes de fechar o design, resolva cada zona cinza: decide com o usuário, ou registra como
+**assumption assinada** ("assumo X porque Y — corrija se errado"). Cinza declinado pelo
+usuário é *registrado*, não descartado no silêncio. Nada sai do design silenciosamente ambíguo.
+
+## Tabela out-of-scope
+
+Liste explicitamente o que a mudança **não** faz. Escopo não declarado vira creep; a tabela
+é o contrato do que ficou de fora — e base pra próxima change.
+
 ## Gate rígido
 
 NÃO escreva código, scaffold nem tome ação de implementação até apresentar um design e o
@@ -139,12 +176,40 @@ de 2–5 min:
 - Nomes/assinaturas consistentes entre tarefas (uma função é \`x()\` em toda parte).
 `;
 
+const VERIFY = `# Verificação independente — o passe fresco
+
+Use no passo *verify deep* do loop, depois de \`wendkeep verify --deep\`. Você é o
+**verificador**, não o autor — mesmo tendo escrito o código, entre neste passe como se
+nunca tivesse visto a implementação. Contexto fresco, read-only.
+
+## O que fazer
+
+1. Leia o pacote \`08-Mudanças/<slug>/verificacao.json\` (requisitos, tarefas, evidência).
+2. **Re-derive a cobertura do \`07-Specs\`** — pra cada \`[req:ID]\` da change, cheque se o
+   comportamento definido no requisito está coberto por um teste que discrimina (não
+   passaria sob impl errada). Evidência \`arquivo:linha\`.
+3. Outcome check ancorado no spec: o resultado observável bate com o critério de aceite?
+4. Grave \`08-Mudanças/<slug>/verdict.json\`:
+   \`{ "slug": "...", "ok": true, "coverage": [{ "req": "GATE-1", "covered": true, "evidence": "arquivo:linha" }], "tasksHash": "<copie do verificacao.json>", "notes": [] }\`.
+   O \`tasksHash\` vem do pacote — é o selo de frescor; sem ele (ou com tarefas alteradas
+   depois), o gate rejeita o verdict como stale.
+
+## Regras
+
+- **Autor ≠ verificador.** No Claude, spawn um sub-agente read-only pra este passe
+  (isolamento real). Nos outros, entre num contexto limpo e re-derive do spec, não da memória.
+- \`ok: false\` se algum requisito não tem cobertura que discrimina. Gap não é "quase lá" — é vermelho.
+- Não conserte aqui. Gap vira tarefa de correção na change; re-verifica depois.
+- O gate do \`archive\` **exige** \`verdict.json\` com \`ok\` cobrindo todo \`[req:]\`. Sem isso, não arquiva.
+`;
+
 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-tdd', 'Use ao implementar qualquer comportamento — Red/Green/Refactor com testes que discriminam (derivados do spec, litmus não-raso, adequação).', TDD),
   skill('wk-debugging', 'Use quando algo falha ou quebra — depuração sistemática por hipótese antes de corrigir.', DEBUGGING),
-  skill('wk-brainstorming', 'Use quando a ideia ainda é vaga — transforma ideia em design aprovado antes de código.', BRAINSTORMING),
+  skill('wk-brainstorming', 'Use quando a ideia ainda é vaga — vira design aprovado, com closure gate e tabela out-of-scope, antes de código.', BRAINSTORMING),
   skill('wk-planning', 'Use após um design aprovado — decompõe em plano de tarefas TDD bite-sized.', PLANNING),
+  skill('wk-verify', 'Use no verify deep — passe independente read-only (autor≠verificador) que re-deriva a cobertura do spec e grava verdict.json.', VERIFY),
 ];
 
 // Seed each skill into <brainDir>/skills/<name>/SKILL.md if absent (non-destructive).

package/src/taxonomy.mjs

@@ -35,6 +35,8 @@ export const HOOK_FILES = [
   'change-core.mjs',
   'spec-core.mjs',
   'sensors-core.mjs',
+  'harness-doctor.mjs',
+  'lessons-core.mjs',
   'brain-inject.mjs',
   'brain-recall.mjs',
   'brain-reindex.mjs',

package/src/verify.mjs

@@ -1,10 +1,17 @@
 // `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 { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
-import { parseTasks, activeChange } from '../hooks/change-core.mjs';
+import { parseTasks, activeChange, appendFixTasks } from '../hooks/change-core.mjs';
 import { loadSensors, requiredSensors, runSensors, evaluateGate } from '../hooks/sensors-core.mjs';
+import { tasksHashOf } from '../hooks/spec-core.mjs';
+import { addLesson } from '../hooks/lessons-core.mjs';
+
+function today() {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
 
 function opt(argv, name) {
   const i = argv.indexOf(name);
@@ -31,6 +38,37 @@ export function runVerify(argv) {
   const evidence = runSensors(sensors, ids, { cwd: projectRoot });
   writeFileSync(join(changeDir, 'evidencia.json'), `${JSON.stringify(evidence, null, 2)}\n`, 'utf8');
 
+  // Mutation survivors -> fix tasks (Wave B), bounded at 3 rounds then escalate. A surviving
+  // mutant always fails verify (exit 1): the suite does not discriminate yet. A clean report
+  // resets the round counter so a future survivor starts a fresh cycle.
+  const withSurvivors = evidence.filter((e) => e.survivors && e.survivors.length);
+  const roundFile = join(changeDir, '.mutation-round');
+  if (!withSurvivors.length) {
+    try { unlinkSync(roundFile); } catch { /* nunca houve rodada */ }
+  } else {
+    let round = 0;
+    try { round = Number(readFileSync(roundFile, 'utf8').trim()) || 0; } catch { /* first round */ }
+    if (round >= 3) {
+      process.stderr.write('verify: mutantes ainda sobrevivem após 3 rodadas — revise os testes à mão.\n');
+      const flat = withSurvivors.flatMap((e) => e.survivors.map((s) => `${s.file}:${s.line}`));
+      try {
+        addLesson(vaultBase, {
+          trigger: `mutantes persistentes em ${slug}`,
+          lesson: `3 rodadas de fix-tasks não mataram: ${flat.join(', ')} — os testes desses pontos não discriminam.`,
+          sourceChange: slug,
+          dateStr: today(),
+        });
+      } catch { /* lesson é bônus, nunca derruba o verify */ }
+    } else {
+      let added = 0;
+      for (const e of withSurvivors) added += appendFixTasks(changeDir, e.survivors, e.id);
+      writeFileSync(roundFile, String(round + 1), 'utf8');
+      process.stdout.write(`verify: ${added} fix-task(s) de mutação (rodada ${round + 1}/3)\n`);
+    }
+    process.stderr.write('verify: mutantes sobreviventes — a suíte não discrimina ainda.\n');
+    process.exit(1);
+  }
+
   // Same rule as the archive gate: evidence carries severity, so evaluateGate blocks
   // only on critical/missing — a red warning is advisory and passes verify.
   const { ok, failing } = evaluateGate(evidence, ids);
@@ -39,6 +77,29 @@ export function runVerify(argv) {
     process.stdout.write(`  ${mark} ${e.id}${e.severity === 'warning' && e.status === 'red' ? ' (warning)' : ''}\n`);
   }
   if (!ok) { process.stderr.write(`verify: critical sensors red: ${failing.join(', ')}\n`); process.exit(1); }
+
+  // --deep (Q2=B): assemble the verification package the wk-verify skill judges. A trivial
+  // 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 tasksHash = tasksHashOf(tarefas);
+    const pkg = {
+      slug,
+      tasksHash,
+      requirements: reqIds.map((id) => ({ id })),
+      tasks: tasks.map((t) => ({ id: t.id, text: t.text, req: t.req || null, done: t.done })),
+      sensors: evidence,
+    };
+    writeFileSync(join(changeDir, 'verificacao.json'), `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+    if (reqIds.length === 0) {
+      writeFileSync(join(changeDir, 'verdict.json'), `${JSON.stringify({ slug, ok: true, coverage: [], tasksHash, notes: ['trivial: sem requisito'] }, null, 2)}\n`, 'utf8');
+      process.stdout.write('verify --deep: pacote + verdict trivial escritos\n');
+    } else {
+      process.stdout.write('verify --deep: pacote escrito — rode a skill wk-verify pra gravar verdict.json\n');
+    }
+    process.exit(0);
+  }
   process.stdout.write(`verify OK (${ids.length} sensor(s))\n`);
   process.exit(0);
 }