wendkeep 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # wendkeep
 
-**Automatically capture your AI coding agent sessions as local Markdown in your Obsidian vault.** Every Claude Code / Codex session is written turn‑by‑turn into your vault — with token/cost tracking, auto‑extracted decisions, bugs and learnings, and a curated memory layer injected back at the start of the next session. 100% local, open‑core.
+**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.
 
@@ -41,7 +41,8 @@ npx wendkeep init
 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/`).
+7. Seed the **definitions + skills layer**: `.brain/agents/` + `.brain/skills/` (versioned source of truth), including the native process skills `wk-workflow` / `wk-tdd` / `wk-debugging` / `wk-brainstorming` / `wk-planning`. `init` runs `wendkeep sync-defs` for you, delivering them to `.codex/agents/` + `.claude/skills/` (re‑run `sync-defs` after editing `.brain`).
+8. Seed the **change/spec lifecycle**: the `07-Specs/` + `08-Mudanças/` folders and a native `wendkeep.sensors.json` (a `validate-memory` sensor plus one per detected `package.json` script). Drives `wendkeep change` / `wendkeep verify` — see **Change lifecycle** below.
 
 ```bash
 npx wendkeep init --vault "~/vaults/work" --project . --yes   # non-interactive (companions: context-mode,dotcontext)
@@ -65,11 +66,30 @@ No re‑copying, no snapshot to re‑sync — the package is the single source o
 
 | Command | What it does |
 |---|---|
-| `wendkeep init` | Set up wendkeep in a project (vault taxonomy + settings + MCP). |
+| `wendkeep init` | Set up wendkeep in a project (vault taxonomy + settings + MCP + skills). |
 | `wendkeep hook <name>` | Run a session hook; invoked by `settings.json` (reads agent JSON on stdin). |
+| `wendkeep change <sub>` | Change lifecycle: `new <slug>` / `list` / `show <slug>` / `archive <slug>`. |
+| `wendkeep verify [--change s]` | Run the active (or named) change's task sensors; record evidence (the gate). |
+| `wendkeep sync-defs` | Copy `.brain/agents\|skills` into the project (`.codex/agents`, `.claude/skills`). |
+| `wendkeep validate-memory [path]` | Validate `.brain/CORE.md` (cap 25, 3 sections, no secrets/PII). |
 | `wendkeep doctor [--vault P]` | Run a vault health check (integrity of sessions, registry, links). |
 | `wendkeep --version` / `--help` | Version / usage. |
 
+## Change lifecycle — the a2 loop (spec‑driven, native)
+
+Beyond capturing sessions, wendkeep is a **harness**: a native, zero‑dependency loop that keeps *intent* (specs), *work* (changes) and *proof* (sensors) together in the vault, wikilinked into the Obsidian graph.
+
+```
+explore → propose → apply (TDD) → verify → archive
+```
+
+- **Propose** — `wendkeep change new <slug>` scaffolds `08-Mudanças/<slug>/` (`proposta.md`, `design.md`, `tarefas.md`, and a `specs/` delta). The change becomes *active* and is injected at the next `SessionStart`, so the agent resumes work‑in‑progress.
+- **Apply** — implement each `tarefas.md` task. Tag a task that needs machine proof with `[sensor:<id>]`.
+- **Verify** — `wendkeep verify` runs the sensors your tasks declared (from `wendkeep.sensors.json` at the project root) and records `evidencia.json`. A critical red fails the gate; a `warning` red is advisory.
+- **Archive** — `wendkeep change archive <slug>` **gates** on the evidence (blocks unless every declared critical sensor is green), promotes each capability's spec delta (`ADDED`/`MODIFIED`/`REMOVED`) into the living `07-Specs/<capability>.md`, moves the change to `_arquivo/`, and mints an ADR in `04-Decisões/`.
+
+`wendkeep init` also seeds **native process skills** (`wk-workflow`, `wk-tdd`, `wk-debugging`, `wk-brainstorming`, `wk-planning`) into `.brain/skills` and delivers them to `.claude/skills` — the *how* layer, zero‑dep. Optional companions (`context-mode`, `dotcontext`, `understand-anything`, `caveman`) remain an opt‑in extra layer.
+
 ## How it works
 
 ```

package/hooks/change-core.mjs

@@ -4,6 +4,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ensureDir, wikilinkFromRel } from './obsidian-common.mjs';
+import { parseSpecsList, promoteSpecs } from './spec-core.mjs';
 
 export const CHANGES_DIR = '08-Mudanças';
 export const SPECS_DIR = '07-Specs';
@@ -48,7 +49,15 @@ specs: []
 
 - [ ] 1.1 (primeira tarefa)
 `;
-  return { proposta, design, tarefas };
+  const specDelta = `## ADDED Requirements
+### Requisito: (nome)
+(comportamento / cenários)
+
+## MODIFIED Requirements
+
+## REMOVED Requirements
+`;
+  return { proposta, design, tarefas, specDelta };
 }
 
 export function activeChange(vaultBase) {
@@ -82,6 +91,12 @@ export function newChange(vaultBase, slug, { sessionRel = '', dateStr }) {
   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');
+  }
   setActiveChange(vaultBase, slug);
   return { rel: changeDirRel(slug), created: !existed };
 }
@@ -147,6 +162,20 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
   if (!verdict.ok) return { ok: false, failing: verdict.failing || [] };
 
   const destRel = join(CHANGES_DIR, ARCHIVE_DIR, `${dateStr}-${slug}`);
+  const changeWikilink = wikilinkFromRel(join(destRel, 'proposta'));
+
+  // Promote spec deltas into the living 07-Specs BEFORE moving (deltas live in src).
+  let promoted = [];
+  let specWarnings = [];
+  try {
+    const specs = parseSpecsList(readFileSync(join(src, 'proposta.md'), 'utf8'));
+    if (specs.length) {
+      const res = promoteSpecs(vaultBase, src, specs, { changeWikilink, dateStr });
+      promoted = res.promoted;
+      specWarnings = res.warnings;
+    }
+  } catch { /* proposta ilegível — segue só com ADR */ }
+
   ensureDir(join(vaultBase, CHANGES_DIR, ARCHIVE_DIR));
   renameSync(src, join(vaultBase, destRel));
 
@@ -155,7 +184,9 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
   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'));
+  const capLine = promoted.length
+    ? `\n\nCapabilities: ${promoted.map((c) => wikilinkFromRel(join(SPECS_DIR, c))).join(', ')}.`
+    : '';
   writeFileSync(join(vaultBase, adrRel), `---
 type: decision
 status: accepted
@@ -170,9 +201,9 @@ tags:
 
 ## Decisão
 
-Mudança ${changeWikilink} concluída e arquivada.
+Mudança ${changeWikilink} concluída e arquivada.${capLine}
 `, 'utf8');
 
   clearActiveChange(vaultBase);
-  return { ok: true, failing: [], archivedRel: destRel, adrRel };
+  return { ok: true, failing: [], archivedRel: destRel, adrRel, promoted, specWarnings };
 }

package/hooks/sensors-core.mjs

@@ -24,15 +24,23 @@ export function runSensors(sensors, ids, { spawn = spawnSync, cwd, now } = {}) {
   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; }
+    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 });
+    evidence.push({ id, status: (r.status ?? 1) === 0 ? 'green' : 'red', ts, severity: s.severity || 'critical' });
   }
   return evidence;
 }
 
+// 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.
 export function evaluateGate(evidence, requiredIds) {
-  const byId = Object.fromEntries((evidence || []).map((e) => [e.id, e.status]));
-  const failing = (requiredIds || []).filter((id) => byId[id] !== 'green');
+  const byId = Object.fromEntries((evidence || []).map((e) => [e.id, e]));
+  const failing = (requiredIds || []).filter((id) => {
+    const e = byId[id];
+    if (!e) return true; // never verified
+    if (e.status === 'green') return false;
+    return (e.severity || 'critical') !== 'warning';
+  });
   return { ok: failing.length === 0, failing };
 }

package/hooks/spec-core.mjs

@@ -0,0 +1,97 @@
+// 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 { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureDir } from './obsidian-common.mjs';
+
+const SPECS_DIR = '07-Specs';
+const REQ_RE = /^### Requisito:\s*(.+)$/gm;
+
+export function parseRequirements(md) {
+  const text = String(md);
+  const matches = [...text.matchAll(REQ_RE)];
+  const reqs = [];
+  for (let i = 0; i < matches.length; i += 1) {
+    const name = matches[i][1].trim();
+    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 });
+  }
+  return reqs;
+}
+
+export function parseDelta(md) {
+  const text = String(md);
+  const grab = (label) => {
+    const m = text.match(new RegExp(`^##\\s+${label} Requirements\\s*$`, 'm'));
+    if (!m) return '';
+    const rest = text.slice(m.index + m[0].length);
+    const next = rest.search(/^##\s+\w+ Requirements\s*$/m);
+    return next === -1 ? rest : rest.slice(0, next);
+  };
+  return {
+    added: parseRequirements(grab('ADDED')),
+    modified: parseRequirements(grab('MODIFIED')),
+    removed: parseRequirements(grab('REMOVED')).map((r) => 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 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);
+  }
+  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);
+  }
+  for (const name of delta.removed || []) {
+    if (!map.has(name)) warnings.push(`REMOVED inexistente: ${name}`);
+    map.delete(name);
+  }
+  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) }));
+  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 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}`;
+}
+
+export function parseSpecsList(propostaMd) {
+  const text = String(propostaMd);
+  const inline = text.match(/^specs:\s*\[(.*?)\]\s*$/m);
+  if (inline) return inline[1].split(',').map((s) => s.trim().replace(/['"]/g, '')).filter(Boolean);
+  const block = text.match(/^specs:\s*\n((?:[ \t]+-[ \t]*.+\n?)+)/m);
+  if (block) return block[1].split('\n').map((l) => l.replace(/^[ \t]*-[ \t]*/, '').trim().replace(/['"]/g, '')).filter(Boolean);
+  return [];
+}
+
+// Merge each capability's delta (in the change) into the living spec in 07-Specs.
+export function promoteSpecs(vaultBase, changeDir, specs, { changeWikilink, dateStr } = {}) {
+  const promoted = [];
+  const warnings = [];
+  for (const cap of specs) {
+    let delta;
+    try { delta = parseDelta(readFileSync(join(changeDir, 'specs', cap, 'spec.md'), 'utf8')); }
+    catch { warnings.push(`sem delta para ${cap}`); continue; }
+    const livePath = join(vaultBase, SPECS_DIR, `${cap}.md`);
+    let current = [];
+    try { current = parseRequirements(readFileSync(livePath, 'utf8')); } catch { /* nova capability */ }
+    const applied = applyDelta(current, delta);
+    warnings.push(...applied.warnings.map((w) => `${cap}: ${w}`));
+    ensureDir(join(vaultBase, SPECS_DIR));
+    const footer = changeWikilink ? `Atualizado por ${changeWikilink} em ${dateStr}.` : '';
+    writeFileSync(livePath, renderSpec(cap, applied.reqs, { footer }), 'utf8');
+    promoted.push(cap);
+  }
+  return { promoted, warnings };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.3.0",
+  "version": "0.4.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

@@ -82,6 +82,8 @@ export function runChange(argv) {
       process.exit(1);
     }
     process.stdout.write(`archived: ${r.archivedRel}; ADR: ${r.adrRel}\n`);
+    if (r.promoted && r.promoted.length) process.stdout.write(`specs promovidas: ${r.promoted.join(', ')}\n`);
+    if (r.specWarnings && r.specWarnings.length) for (const w of r.specWarnings) process.stderr.write(`  aviso spec: ${w}\n`);
     process.exit(0);
   }
 

package/src/init.mjs

@@ -31,7 +31,7 @@ import {
   mergeGraphColorGroups,
 } from './vault-theme.mjs';
 import { renderCoreSkeleton, renderCompactionProtocol } from './validate-core.mjs';
-import { seedDefinitions } from './sync-defs.mjs';
+import { seedDefinitions, syncDefs } from './sync-defs.mjs';
 import { seedWkSkills } from './skills-seed.mjs';
 import { seedDotcontext, globalHasDotcontext, resolveDotcontextSkipMcp, renderSensorsJson } from './dotcontext-seed.mjs';
 
@@ -295,6 +295,12 @@ export async function runInit(argv) {
     writeFileSync(sensorsFile, renderSensorsJson(scripts), 'utf8');
   }
   log(`  [1/4] vault taxonomy: ${VAULT_FOLDERS.length} folders (${created} created)${readmeNote}, .brain + change/spec + sensors seeded`);
+  // Deliver the seeded defs (agents + wk process skills) to the project so they're
+  // usable immediately — no separate `wendkeep sync-defs` step needed.
+  const synced = syncDefs(vaultPath, projectPath);
+  if (synced.skills.length || synced.agents.length) {
+    log(`        defs delivered: ${synced.skills.length} skill(s) -> .claude/skills, ${synced.agents.length} agent(s) -> .codex/agents`);
+  }
 
   // 2. .claude/settings.json --------------------------------------------------
   const settingsPath = join(projectPath, '.claude', 'settings.json');

package/src/taxonomy.mjs

@@ -33,6 +33,7 @@ export const HOOK_FILES = [
   'pricing.json',
   'brain-core.mjs',
   'change-core.mjs',
+  'spec-core.mjs',
   'sensors-core.mjs',
   'brain-inject.mjs',
   'brain-recall.mjs',

package/src/verify.mjs

@@ -31,10 +31,13 @@ export function runVerify(argv) {
   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`);
+  // 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);
+  for (const e of evidence) {
+    const mark = e.status === 'green' ? '✓' : (e.severity === 'warning' ? '!' : '✗');
+    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); }
   process.stdout.write(`verify OK (${ids.length} sensor(s))\n`);
   process.exit(0);