wendkeep 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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.7.0] — 2026-07-05
+
+Ergonomics: the loop without hand-editing files.
+
+### Added
+- **`change status`** — one screen: tasks (done/open with `[req:]`/`[sensor:]`), sensor
+  evidence, verdict state (ok / stale / incomplete / absent), mutation round.
+- **`change done <id>` / `undone <id>`** — tick tasks from the CLI (exact-id anchored).
+- **`change diff`** — dry-run preview of the spec promotion (`+` ADDED / `~` MODIFIED /
+  `-` REMOVED / `!` warnings) without touching `07-Specs`.
+- **`spec list` / `spec show <capability>`** — read-only views over the living specs.
+- **`sensors list`** — the sensors from `wendkeep.sensors.json`; a **JSON Schema** for the
+  file now ships in the package (`schema/`) and the init seed points `$schema` at it.
+- README: "the loop in five minutes" worked example.
+
+### Fixed
+- `change` subcommands without a positional argument no longer mistake the `--vault` value
+  for a slug.
+
 ## [0.6.1] — 2026-07-05
 
 Hardening: CI + real-world gate holes found by self-audit.
@@ -141,6 +160,7 @@ Initial release — the capture engine, extracted from a system in daily product
 - `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.7.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.7.0
 [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

package/README.md

@@ -70,8 +70,11 @@ No re‑copying, no snapshot to re‑sync — the package is the single source o
 |---|---|
 | `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 change <sub>` | Change lifecycle: `new [--simple]` / `list` / `show` / `status` / `done <id>` / `undone <id>` / `diff` / `archive [--force]`. |
+| `wendkeep verify [--deep]` | Run the change's task sensors; `--deep` assembles the independent-verification package. |
+| `wendkeep spec <sub>` | Living specs: `list` / `show <capability>`. |
+| `wendkeep sensors list` | Show the sensors from `wendkeep.sensors.json` (JSON Schema included in the package). |
+| `wendkeep lesson add "t" "l"` | Record a project-local lesson (injected at the next SessionStart). |
 | `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). |
@@ -90,7 +93,37 @@ explore → propose → apply (TDD) → verify → archive
 - **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.
+`wendkeep init` also seeds **native process skills** (`wk-workflow`, `wk-tdd`, `wk-debugging`, `wk-brainstorming`, `wk-planning`, `wk-verify`) 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.
+
+### The loop in five minutes
+
+```bash
+npx wendkeep init --yes                        # vault + hooks + sensors + skills
+npx wendkeep change new dark-mode              # proposta/design/tarefas — change is now active
+```
+
+Edit `tarefas.md` — tag proof and requirement per task:
+
+```markdown
+- [ ] 1.1 toggle persists across sessions [req:UI-1] [sensor:tests]
+```
+
+Declare the capability in `proposta.md` (`specs: [ui]`) and author its delta in
+`specs/ui/spec.md` (`## ADDED Requirements` → `### Requisito: UI-1 — dark mode toggle`). Then:
+
+```bash
+npx wendkeep change status                     # one screen: tasks / sensors / verdict
+npx wendkeep change done 1.1                   # tick a task from the CLI
+npx wendkeep verify                            # run the declared sensors -> evidencia.json
+npx wendkeep verify --deep                     # assemble the verification package
+# the wk-verify skill (fresh, read-only pass) writes verdict.json
+npx wendkeep change diff                       # preview what will land in 07-Specs
+npx wendkeep change archive dark-mode          # gate: sensors + verdict + no open tasks
+```
+
+The archive promotes the delta into the living `07-Specs/ui.md`, mints an ADR, and the
+Obsidian graph now links *session ↔ change ↔ requirement ↔ decision*. A change that names
+no `[req:]` skips the independent verdict — the sensor gate is its proof.
 
 ## How it works
 

package/bin/wendkeep.mjs

@@ -43,7 +43,10 @@ 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 change <sub>        Change lifecycle: new [--simple] | list | show | status |
+                           done <id> | undone <id> | diff | archive [--force].
+  wendkeep spec <sub>          Living specs: list | show <capability>.
+  wendkeep sensors list        Show the sensors from wendkeep.sensors.json.
   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
@@ -117,6 +120,16 @@ async function main() {
       runLesson(rest);
       break;
     }
+    case 'spec': {
+      const { runSpec } = await import('../src/spec.mjs');
+      runSpec(rest);
+      break;
+    }
+    case 'sensors': {
+      const { runSensors } = await import('../src/sensors.mjs');
+      runSensors(rest);
+      break;
+    }
     case '--version':
     case '-v':
       process.stdout.write(`${version()}\n`);

package/hooks/change-core.mjs

@@ -123,6 +123,17 @@ export function parseTasks(md) {
   return tasks;
 }
 
+// Toggle a task checkbox by its exact id (0.7.0 ergonomics). Returns false when absent.
+export function setTaskDone(changeDir, taskId, done = true) {
+  const path = join(changeDir, 'tarefas.md');
+  const md = readFileSync(path, 'utf8');
+  const esc = String(taskId).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`^(-\\s+\\[)( |x)(\\]\\s+${esc}\\s)`, 'm');
+  if (!re.test(md)) return false;
+  writeFileSync(path, md.replace(re, `$1${done ? 'x' : ' '}$3`), 'utf8');
+  return true;
+}
+
 export function listChanges(vaultBase) {
   const base = join(vaultBase, CHANGES_DIR);
   const active = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.6.1",
+  "version": "0.7.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": {
@@ -11,6 +11,7 @@
     "bin",
     "src",
     "hooks",
+    "schema",
     "README.md",
     "CHANGELOG.md"
   ],

package/schema/wendkeep.sensors.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/rogersialves/wendkeep/main/schema/wendkeep.sensors.schema.json",
+  "title": "wendkeep.sensors.json",
+  "description": "Native sensor config for the wendkeep harness (harness contract v1.1).",
+  "type": "object",
+  "required": ["version", "sensors"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "source": { "type": "string" },
+    "sensors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "command"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "severity": { "enum": ["critical", "warning"], "default": "critical" },
+          "type": { "enum": ["command", "mutation"], "default": "command" },
+          "command": { "type": "string", "minLength": 1 },
+          "report": {
+            "type": "string",
+            "description": "type: mutation only — path (project-relative) to the mutation-testing-elements report."
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/src/change.mjs

@@ -6,10 +6,11 @@ import {
   activeChange,
   listChanges,
   parseTasks,
+  setTaskDone,
   archiveChange,
 } from '../hooks/change-core.mjs';
 import { evaluateGate, requiredSensors } from '../hooks/sensors-core.mjs';
-import { evaluateVerdict, tasksHashOf } from '../hooks/spec-core.mjs';
+import { evaluateVerdict, tasksHashOf, parseSpecsList, parseDelta, parseRequirements, applyDelta } from '../hooks/spec-core.mjs';
 import { getNextAdrNumber, readControl } from '../hooks/obsidian-common.mjs';
 
 function resolveVault(argv) {
@@ -27,6 +28,13 @@ function resolveVault(argv) {
   return isAbsolute(base) ? base : resolve(process.cwd(), base);
 }
 
+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')}`;
@@ -35,7 +43,8 @@ function today() {
 export function runChange(argv) {
   const [sub, ...rest] = argv;
   const vaultBase = resolveVault(rest);
-  const slugArg = () => rest.find((a) => !a.startsWith('-'));
+  const VALUE_FLAGS = new Set(['--vault', '--change', '--project']);
+  const slugArg = () => rest.find((a, i) => !a.startsWith('-') && !VALUE_FLAGS.has(rest[i - 1]));
 
   if (sub === 'new') {
     const slug = slugArg();
@@ -69,6 +78,76 @@ export function runChange(argv) {
     process.exit(0);
   }
 
+  if (sub === 'status') {
+    const slug = slugArg() || activeChange(vaultBase);
+    if (!slug) { process.stderr.write('wendkeep change status: no change (arg or active)\n'); process.exit(2); }
+    const dir = join(vaultBase, '08-Mudanças', slug);
+    let tarefasMd;
+    try { tarefasMd = readFileSync(join(dir, 'tarefas.md'), 'utf8'); }
+    catch { process.stderr.write(`wendkeep change status: not found: ${slug}\n`); process.exit(2); }
+    const tasks = parseTasks(tarefasMd);
+    const done = tasks.filter((t) => t.done).length;
+    process.stdout.write(`change: ${slug}${slug === activeChange(vaultBase) ? ' (ativa)' : ''}\n`);
+    let specs = [];
+    try { specs = parseSpecsList(readFileSync(join(dir, 'proposta.md'), 'utf8')); } catch { /* sem proposta */ }
+    process.stdout.write(`specs: ${specs.join(', ') || '(nenhuma)'}\n`);
+    process.stdout.write(`tarefas: ${done} done / ${tasks.length - done} open\n`);
+    for (const t of tasks) {
+      process.stdout.write(`  [${t.done ? 'x' : ' '}] ${t.id} ${t.text}${t.req ? ` [req:${t.req}]` : ''}${t.sensor ? ` [sensor:${t.sensor}]` : ''}\n`);
+    }
+    let evidence = null;
+    try { evidence = JSON.parse(readFileSync(join(dir, 'evidencia.json'), 'utf8')); } catch { /* sem evidência */ }
+    if (evidence) for (const e of evidence) process.stdout.write(`  ${e.status === 'green' ? '✓' : '✗'} ${e.id} (${e.severity || 'critical'})\n`);
+    else process.stdout.write('evidencia: ausente\n');
+    const reqIds = [...new Set(tasks.map((t) => t.req).filter(Boolean))];
+    let verdict = null;
+    try { verdict = JSON.parse(readFileSync(join(dir, 'verdict.json'), 'utf8')); } catch { /* sem verdict */ }
+    if (!reqIds.length) process.stdout.write('verdict: não exigido (sem [req:])\n');
+    else if (!verdict) process.stdout.write('verdict: ausente — rode `wendkeep verify --deep` + wk-verify\n');
+    else {
+      const v = evaluateVerdict(verdict, reqIds, { tasksHash: tasksHashOf(tarefasMd) });
+      process.stdout.write(`verdict: ${v.ok ? 'ok' : v.stale ? 'stale — re-verifique' : `incompleto: falta ${v.missing.join(', ')}`}\n`);
+    }
+    try { process.stdout.write(`mutation-round: ${readFileSync(join(dir, '.mutation-round'), 'utf8').trim()}/3\n`); } catch { /* sem rodadas */ }
+    process.exit(0);
+  }
+
+  if (sub === 'done' || sub === 'undone') {
+    const taskId = slugArg();
+    if (!taskId) { process.stderr.write(`wendkeep change ${sub}: missing <taskId>\n`); process.exit(2); }
+    const slug = opt(rest, '--change') || activeChange(vaultBase);
+    if (!slug) { process.stderr.write(`wendkeep change ${sub}: no active change\n`); process.exit(2); }
+    const dir = join(vaultBase, '08-Mudanças', slug);
+    let ok = false;
+    try { ok = setTaskDone(dir, taskId, sub === 'done'); } catch { /* sem tarefas.md */ }
+    if (!ok) { process.stderr.write(`wendkeep change ${sub}: task não encontrada: ${taskId}\n`); process.exit(2); }
+    process.stdout.write(`task ${taskId}: ${sub === 'done' ? '[x]' : '[ ]'}\n`);
+    process.exit(0);
+  }
+
+  if (sub === 'diff') {
+    const slug = slugArg() || activeChange(vaultBase);
+    if (!slug) { process.stderr.write('wendkeep change diff: no change (arg or active)\n'); process.exit(2); }
+    const dir = join(vaultBase, '08-Mudanças', slug);
+    let specs = [];
+    try { specs = parseSpecsList(readFileSync(join(dir, 'proposta.md'), 'utf8')); }
+    catch { process.stderr.write(`wendkeep change diff: not found: ${slug}\n`); process.exit(2); }
+    if (!specs.length) { process.stdout.write('diff: sem specs declaradas na proposta\n'); process.exit(0); }
+    for (const cap of specs) {
+      let delta;
+      try { delta = parseDelta(readFileSync(join(dir, 'specs', cap, 'spec.md'), 'utf8')); }
+      catch { process.stdout.write(`! sem delta para ${cap}\n`); continue; }
+      process.stdout.write(`spec: ${cap}\n`);
+      for (const r of delta.added) process.stdout.write(`  + ${r.id || r.name} (ADDED)\n`);
+      for (const r of delta.modified) process.stdout.write(`  ~ ${r.id || r.name} (MODIFIED)\n`);
+      for (const k of delta.removed) process.stdout.write(`  - ${k} (REMOVED)\n`);
+      let living = [];
+      try { living = parseRequirements(readFileSync(join(vaultBase, '07-Specs', `${cap}.md`), 'utf8')); } catch { /* nova capability */ }
+      for (const w of applyDelta(living, delta).warnings) process.stdout.write(`  ! ${w}\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); }
@@ -109,6 +188,6 @@ export function runChange(argv) {
     process.exit(0);
   }
 
-  process.stderr.write(`wendkeep change: unknown subcommand "${sub}". Known: new, list, show, archive.\n`);
+  process.stderr.write(`wendkeep change: unknown subcommand "${sub}". Known: new, list, show, status, done, undone, diff, archive.\n`);
   process.exit(2);
 }

package/src/dotcontext-seed.mjs

@@ -37,7 +37,7 @@ export function renderSensorsJson(scripts = {}) {
       });
     }
   }
-  return `${JSON.stringify({ version: 1, source: 'manual', sensors }, null, 2)}\n`;
+  return `${JSON.stringify({ $schema: 'https://raw.githubusercontent.com/rogersialves/wendkeep/main/schema/wendkeep.sensors.schema.json', version: 1, source: 'manual', sensors }, null, 2)}\n`;
 }
 
 function readProjectScripts(projectPath) {

package/src/sensors.mjs

@@ -0,0 +1,23 @@
+// `wendkeep sensors list` — read-only view over wendkeep.sensors.json (0.7.0).
+import { resolve } from 'node:path';
+import { loadSensors } from '../hooks/sensors-core.mjs';
+
+export function runSensors(argv) {
+  const [sub, ...rest] = argv;
+  if (sub !== 'list') {
+    process.stderr.write(`wendkeep sensors: unknown subcommand "${sub}". Known: list.\n`);
+    process.exit(2);
+  }
+  let project;
+  for (let i = 0; i < rest.length; i += 1) {
+    if (rest[i] === '--project') project = rest[++i];
+    else if (rest[i].startsWith('--project=')) project = rest[i].slice(10);
+  }
+  const projectRoot = resolve(project || process.cwd());
+  const sensors = loadSensors(projectRoot);
+  if (!sensors.length) { process.stdout.write('sensors: (nenhum — crie wendkeep.sensors.json na raiz)\n'); process.exit(0); }
+  for (const s of sensors) {
+    process.stdout.write(`${s.id}: ${s.type || 'command'} · ${s.severity || 'critical'} · ${s.command}\n`);
+  }
+  process.exit(0);
+}

package/src/spec.mjs

@@ -0,0 +1,53 @@
+// `wendkeep spec <sub>` — read-only views over the living specs in 07-Specs (0.7.0).
+import { readFileSync, readdirSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { parseRequirements } from '../hooks/spec-core.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 spec: no vault. Pass --vault <path> or set OBSIDIAN_VAULT_PATH.\n');
+    process.exit(2);
+  }
+  return isAbsolute(base) ? base : resolve(process.cwd(), base);
+}
+
+export function runSpec(argv) {
+  const [sub, ...rest] = argv;
+  const vaultBase = resolveVault(rest);
+  const specsDir = join(vaultBase, '07-Specs');
+
+  if (sub === 'list') {
+    let files = [];
+    try { files = readdirSync(specsDir).filter((f) => f.endsWith('.md') && f !== 'README.md'); } catch { /* sem specs */ }
+    if (!files.length) { process.stdout.write('specs: (nenhuma)\n'); process.exit(0); }
+    for (const f of files) {
+      const md = readFileSync(join(specsDir, f), 'utf8');
+      const n = parseRequirements(md).length;
+      const upd = md.match(/> Atualizado por .* em (\d{4}-\d{2}-\d{2})/);
+      process.stdout.write(`${f.replace(/\.md$/, '')}: ${n} requisito(s)${upd ? ` (atualizado ${upd[1]})` : ''}\n`);
+    }
+    process.exit(0);
+  }
+
+  if (sub === 'show') {
+    const cap = rest.find((a, i) => !a.startsWith('-') && rest[i - 1] !== '--vault');
+    if (!cap) { process.stderr.write('wendkeep spec show: missing <capability>\n'); process.exit(2); }
+    let md;
+    try { md = readFileSync(join(specsDir, `${cap}.md`), 'utf8'); }
+    catch { process.stderr.write(`wendkeep spec show: not found: ${cap}\n`); process.exit(2); }
+    const reqs = parseRequirements(md);
+    process.stdout.write(`${cap}: ${reqs.length} requisito(s)\n`);
+    for (const r of reqs) process.stdout.write(`  ${r.id ? `${r.id} — ` : ''}${r.name}\n`);
+    process.exit(0);
+  }
+
+  process.stderr.write(`wendkeep spec: unknown subcommand "${sub}". Known: list, show.\n`);
+  process.exit(2);
+}