wendkeep 0.20.1 → 0.21.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.21.0] — 2026-07-08
+
+Process enforcement — fixes from a real planning failure (production session): the model planned
+in chat, never invoked the wk-* skills, left the change scaffold raw and archived it with
+`--force`, minting a bogus ADR.
+
+### Added
+- **`<wk_process>` router injected every session** (brain-inject): the enforcement layer the
+  skills were missing. Plan → wk-brainstorming + wk-planning; record → `change new` + FILL
+  proposta/design/tarefas; implement → wk-tdd; close → verify + wk-verify + archive. States
+  explicitly that `archive --force` is the user's call, never the agent's. Localized (pt-BR/en).
+- **G0 — anti-scaffold gate**: `change archive` now blocks when proposta/design/tarefas still
+  carry the scaffold placeholders (`(motivo da mudança)`, `(abordagem técnica)`,
+  `(primeira tarefa)` + en variants) — an unfilled scaffold is not a completed change.
+  `--force` still escapes (human hatch); new `scaffoldPlaceholders(dir)` in change-core.
+
+### Fixed
+- **session-ensure now stamps `session_id`** in the notes it creates — the 4th note-creation
+  path, missed in 0.18.0 (it has its own skeleton builder). Notes born from UserPromptSubmit
+  (no SessionStart, e.g. resumed windows) were coming out without identity.
+
 ## [0.20.1] — 2026-07-06
 
 ### Changed

package/hooks/brain-inject.mjs

@@ -9,6 +9,36 @@ import { getVaultBase, readHookInput, writeHookOutput } from './obsidian-common.
 import { brainDir } from './brain-core.mjs';
 import { buildActiveChangeInjection } from './change-core.mjs';
 import { buildLessonsInjection } from './lessons-core.mjs';
+import { getLocale } from './locale.mjs';
+
+// The process ROUTER — the enforcement layer. The wk-* skills are passive files; without a
+// standing instruction the model plans in chat, leaves the change scaffold raw and forces the
+// gate (seen in production: change archived with `(primeira tarefa)` open, via --force). This
+// block is injected EVERY session so planning always routes through the a2 loop.
+function processRouter(localeId) {
+  if (localeId === 'en') {
+    return [
+      '<wk_process>',
+      'Spec-driven process (mandatory for any non-trivial task):',
+      '1. Plan: skill wk-brainstorming (approved design) → wk-planning (task plan).',
+      '2. Record: `wendkeep change new <slug>` and FILL 08-Changes/<slug>/ — proposta.md (why/what), design.md (the approved approach), tarefas.md (the plan\'s tasks, `- [ ] N.N` with [req:ID]/[sensor:id]). Never leave the scaffold placeholders.',
+      '3. Implement: wk-tdd per task; tick `- [x]` as you finish. Something broke? wk-debugging.',
+      '4. Close: `wendkeep verify` (+ `--deep` + skill wk-verify) → `wendkeep change archive`.',
+      'NEVER `archive --force` on your own — a red gate means pending work; --force is the user\'s call, not yours.',
+      '</wk_process>',
+    ].join('\n');
+  }
+  return [
+    '<wk_process>',
+    'Processo spec-driven (obrigatório em tarefa não-trivial):',
+    '1. Planejar: skill wk-brainstorming (design aprovado) → wk-planning (plano de tarefas).',
+    '2. Registrar: `wendkeep change new <slug>` e PREENCHA 08-Mudanças/<slug>/ — proposta.md (porquê/o quê), design.md (a abordagem aprovada), tarefas.md (as tarefas do plano, `- [ ] N.N` com [req:ID]/[sensor:id]). Nunca deixe os placeholders do scaffold.',
+    '3. Implementar: wk-tdd por tarefa; marque `- [x]` ao concluir. Quebrou algo? wk-debugging.',
+    '4. Fechar: `wendkeep verify` (+ `--deep` + skill wk-verify) → `wendkeep change archive`.',
+    'PROIBIDO `archive --force` por conta própria — gate vermelho significa trabalho pendente; --force é decisão do usuário, não sua.',
+    '</wk_process>',
+  ].join('\n');
+}
 
 const MAX_LINES = 45; // CORE ≤25 + DIGEST ≤15 + folga; salvaguarda se o CORE crescer à mão
 
@@ -26,9 +56,10 @@ export function buildInjection(vaultBase) {
     lines.push('*…truncado pelo budget — fonte completa: .brain/CORE.md + .brain/DIGEST.md*');
   }
   const brain = ['<brain_memory>', ...lines, pointer, '</brain_memory>'].join('\n');
+  const router = processRouter(getLocale(vaultBase).id);
   const change = buildActiveChangeInjection(vaultBase);
   const lessons = buildLessonsInjection(vaultBase);
-  return [brain, change, lessons].filter(Boolean).join('\n');
+  return [brain, router, change, lessons].filter(Boolean).join('\n');
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/hooks/change-core.mjs

@@ -53,6 +53,25 @@ ${en ? '(behaviour / scenarios)' : '(comportamento / cenários)'}
   return { proposta, design, tarefas, specDelta };
 }
 
+// Scaffold placeholder markers per file (pt + en, mirrors renderChangeScaffold). A change whose
+// proposta/design/tarefas still carry these was never actually planned — archiving it mints a
+// bogus ADR and pollutes _arquivo (seen in production). The archive gate blocks on them.
+const SCAFFOLD_MARKERS = [
+  ['proposta.md', ['(motivo da mudança)', '(escopo da mudança)', '(reason for the change)', '(scope of the change)']],
+  ['design.md', ['(abordagem técnica)', '(technical approach)']],
+  ['tarefas.md', ['(primeira tarefa)', '(first task)']],
+];
+
+export function scaffoldPlaceholders(dir) {
+  const found = [];
+  for (const [file, markers] of SCAFFOLD_MARKERS) {
+    let content = '';
+    try { content = readFileSync(join(dir, file), 'utf8'); } catch { continue; }
+    for (const m of markers) if (content.includes(m)) found.push(`${file}: ${m}`);
+  }
+  return found;
+}
+
 export function activeChange(vaultBase) {
   try {
     const m = readFileSync(join(vaultBase, POINTER), 'utf8').match(/^change:\s*(.+)$/m);

package/hooks/session-ensure.mjs

@@ -35,7 +35,7 @@ function sessionIdFromInput(input) {
   return input.session_id || input.sessionId || input.codex_session_id || '';
 }
 
-function buildSessionContent({ relPath, now, summary = 'session', reason = 'Sessão criada automaticamente pelo hook UserPromptSubmit.' }) {
+function buildSessionContent({ relPath, now, summary = 'session', sessionId = '', reason = 'Sessão criada automaticamente pelo hook UserPromptSubmit.' }) {
   const date = formatDate(now);
   const startedAt = formatLocalIso(now);
   const titleTime = formatTime(now).slice(0, 5);
@@ -48,6 +48,7 @@ date: ${date}
 started_at: ${startedAt}
 ended_at:
 provider: ${provider.id}
+session_id: ${sessionId ? yamlQuote(sessionId) : ''}
 status: active
 summary: ${yamlQuote(summary)}
 cssclasses:
@@ -267,7 +268,7 @@ function createSession({ vaultBase, sessionId, input, now }) {
   const summary = sessionSummaryFromInput(input);
   const { absPath, relPath } = allocateSessionPath(vaultBase, now, summary);
   const startedAt = formatLocalIso(now);
-  writeFileSync(absPath, buildSessionContent({ relPath, now, summary }), 'utf-8');
+  writeFileSync(absPath, buildSessionContent({ relPath, now, summary, sessionId }), 'utf-8');
   writeControl(vaultBase, {
     status: 'active',
     session_file: relPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "description": "A persistent-memory harness for AI coding agents on your Obsidian vault: turn-by-turn session capture plus a native, zero-dependency spec→change→verify→archive loop (sensor-gated, independent verdict, mutation discrimination). Local-first, agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "bin": {

package/src/change.mjs

@@ -8,6 +8,7 @@ import {
   parseTasks,
   setTaskDone,
   archiveChange,
+  scaffoldPlaceholders,
 } from '../hooks/change-core.mjs';
 import { evaluateGate, requiredSensors } from '../hooks/sensors-core.mjs';
 import { evaluateVerdict, tasksHashOf, parseSpecsList, parseDelta, parseRequirements, applyDelta } from '../hooks/spec-core.mjs';
@@ -154,6 +155,13 @@ 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) => {
+      // G0: um scaffold nunca preenchido não é uma mudança concluída — arquivar geraria um
+      // ADR falso. Bloqueia antes de qualquer outro check (o --force ainda escapa, mas a
+      // regra injetada proíbe o agente de usá-lo sem o usuário pedir).
+      const placeholders = scaffoldPlaceholders(dir);
+      if (placeholders.length && !rest.includes('--force')) {
+        return { ok: false, failing: [`scaffold não preenchido (${placeholders.join('; ')}) — preencha proposta/design/tarefas com o design e o plano antes de arquivar`] };
+      }
       let tarefasMd = '';
       try { tarefasMd = readFileSync(join(dir, 'tarefas.md'), 'utf8'); } catch { /* no tasks */ }
       const tasks = parseTasks(tarefasMd);