wendkeep 0.61.0 → 0.63.0

package/CHANGELOG.md

@@ -4,6 +4,54 @@ 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.63.0] — 2026-07-28
+
+### Added
+
+- **O Vault público passa a expor locale e taxonomia de pastas, e o Harness passa a expor o
+  store durável de FLOW.** As novas superfícies canônicas estão disponíveis por
+  wendkeep/vault e wendkeep/harness e são validadas a partir de um tarball instalado em consumidor
+  isolado, inclusive com um ciclo persistido completo.
+
+### Changed
+
+- **Locale agora pertence a packages/vault/src e o store de FLOW a packages/harness/src.**
+  hooks/locale.mjs e hooks/vault-runtime-store.mjs permanecem como fachadas puras, preservando por
+  identidade todas as constantes e funções usadas por consumidores existentes.
+- **A extração stateful não exige migração.** Paths em .brain/runtime, schemas, ids, locks,
+  tentativas, recibos, reservas, promoções, atomicidade, contenção multiprocesso e validação física
+  de paths mantêm o contrato anterior.
+- **A direção Harness → Vault é verificada pelo índice público canônico.** Vault continua proibido
+  de depender do Harness, enquanto CLI, MCP, Integrations, Pi e flow-core permanecem fora deste
+  corte modular.
+
+### Fixed
+
+- **Promoções concorrentes no Windows/Node 22 não confundem a liberação transitória do lock com
+  um path inseguro.** O Vault agora revalida, com backoff curto e limitado, o lock público que
+  desaparece entre `lstat` e `realpath` e leituras `ENOENT` de owner/lease. A aquisição compartilha
+  um único budget/deadline e a liberação limpa o lock sem resíduo; junctions, reparse points, links
+  dangling, erros não transitórios e locks privados `.pending` continuam falhando fechado.
+
+## [0.62.0] — 2026-07-28
+
+### Added
+
+- **`wendkeep/harness` passa a expor o policy kernel reutilizável.** Os contratos dos cinco
+  Perfis de Operação e a engine de sensores podem ser importados pela superfície pública do pacote
+  raiz, com identidade validada a partir de um tarball realmente instalado.
+
+### Changed
+
+- **As implementações canônicas de perfis e sensores agora pertencem a
+  `packages/harness/src`.** `src/operating-profile.mjs` e `hooks/sensors-core.mjs` permanecem como
+  fachadas de reexport, preservando funções, constantes, objetos congelados e consumidores atuais.
+- **A direção modular do Harness virou contrato estrutural.** O workspace aceita somente built-ins,
+  módulos internos e a superfície pública do Vault; Vault continua proibido de depender do
+  Harness, e CLI, MCP, Integrations e Pi permanecem adaptadores superiores.
+- **OFF preserva a semântica publicada:** Keep Core/Vault continua ativo e a governança automática
+  fica desligada; comandos explícitos do operador não ganham bloqueios novos nesta extração.
+
 ## [0.61.0] — 2026-07-28
 
 ### Added

package/README.en.md

@@ -16,13 +16,23 @@
 **Persistent memory for AI coding agents, built on your Obsidian vault.** Every Claude Code **and Codex** session is captured turn by turn into local Markdown — `init` wires both (Codex asks you to approve its hooks once; `import` backfills past sessions either way) — with token/cost tracking and automatically extracted decisions, bugs, and learnings. That always-on plane is **Keep Core**. On top of it, **Wend Runtime** provides a native, zero-dependency lifecycle (spec → change → TDD → sensor-gated archive), selected through the `OFF`, `FLOW`, `GUIDE`, `GOVERN`, and `ASSURE` Operating Profiles. 100% local, open-core.
 
 The runtime is being separated into six physical boundaries — `cli`, `harness`, `vault`, `mcp`,
-`integrations`, and `pi` — without fragmenting installation. The private `vault` workspace now
-canonically owns safe binding and the Shared Project Memory v2 kernel (schema, mode, handoff,
-ledger, projection, and validation), exposed by the root package through `wendkeep/vault`.
-Historical imports, including installed bare subpaths such as `wendkeep/hooks/...`, keep working
-through compatibility facades and no session data needs migration;
+`integrations`, and `pi` — without fragmenting installation. The private `harness` and `vault`
+workspaces now canonically own Operating Profiles/the sensor engine and safe binding/the Shared
+Project Memory v2 kernel, respectively. The root package exposes those surfaces through
+`wendkeep/harness` and `wendkeep/vault`; historical imports keep working through compatibility
+facades and no session data needs migration;
 see the [modular architecture](docs/en/architecture.md).
 
+In the **0.63 Harness FLOW Store** phase, `packages/vault/src/locale.mjs` becomes the canonical
+source for Vault locale and taxonomy, while `packages/harness/src/flow-store.mjs` becomes the
+canonical durable FLOW store. The historical `hooks/locale.mjs` and
+`hooks/vault-runtime-store.mjs` facades preserve export identity. Harness depends only on Vault's
+public index — never the reverse — with no migration of paths, schemas, or locks; the tarball
+remains a single artifact published by the root `wendkeep` package.
+Under multiprocess contention, transient release of the public lock and its owner/lease metadata
+is revalidated with a bounded budget/deadline, including final cleanup; junctions, reparse points,
+dangling locks, and non-transient errors are still rejected before any write.
+
 ```bash
 npm i -D wendkeep && npx wendkeep init      # captures from the next session on
 npx wendkeep import                          # backfill past Claude + Codex sessions
@@ -189,8 +199,9 @@ Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://
 ## Operating Profiles — Keep Core is always active
 
 **Keep Core is always active**: the Vault, sessions, identity, CORE/SHARED, lessons, costs,
-and persistence do not turn off with the harness. **Wend Runtime** controls only the governance
-layer:
+and persistence do not turn off with the harness. **Wend Runtime** controls only the automatic
+governance layer. Even under `OFF`, explicit WendKeep commands remain available; invoking one is a
+deliberate opt-in and runs that command's own validations:
 
 | Profile | Route | Use |
 |---|---|---|

package/README.md

@@ -16,13 +16,23 @@
 **Persistent memory for AI coding agents, built on your Obsidian vault.** Every Claude Code **and Codex** session is captured turn by turn into local Markdown — `init` wires both (Codex asks you to approve its hooks once; `import` backfills past sessions either way) — with token/cost tracking and automatically extracted decisions, bugs, and learnings. That always-on plane is **Keep Core**. On top of it, **Wend Runtime** provides a native, zero-dependency lifecycle (spec → change → TDD → sensor-gated archive), selected through the `OFF`, `FLOW`, `GUIDE`, `GOVERN`, and `ASSURE` Operating Profiles. 100% local, open-core.
 
 The runtime is being separated into six physical boundaries — `cli`, `harness`, `vault`, `mcp`,
-`integrations`, and `pi` — without fragmenting installation. The private `vault` workspace now
-canonically owns safe binding and the Shared Project Memory v2 kernel (schema, mode, handoff,
-ledger, projection, and validation), exposed by the root package through `wendkeep/vault`.
-Historical imports, including installed bare subpaths such as `wendkeep/hooks/...`, keep working
-through compatibility facades and no session data needs migration;
+`integrations`, and `pi` — without fragmenting installation. The private `harness` and `vault`
+workspaces now canonically own Operating Profiles/the sensor engine and safe binding/the Shared
+Project Memory v2 kernel, respectively. The root package exposes those surfaces through
+`wendkeep/harness` and `wendkeep/vault`; historical imports keep working through compatibility
+facades and no session data needs migration;
 see the [modular architecture](docs/en/architecture.md).
 
+In the **0.63 Harness FLOW Store** phase, `packages/vault/src/locale.mjs` becomes the canonical
+source for Vault locale and taxonomy, while `packages/harness/src/flow-store.mjs` becomes the
+canonical durable FLOW store. The historical `hooks/locale.mjs` and
+`hooks/vault-runtime-store.mjs` facades preserve export identity. Harness depends only on Vault's
+public index — never the reverse — with no migration of paths, schemas, or locks; the tarball
+remains a single artifact published by the root `wendkeep` package.
+Under multiprocess contention, transient release of the public lock and its owner/lease metadata
+is revalidated with a bounded budget/deadline, including final cleanup; junctions, reparse points,
+dangling locks, and non-transient errors are still rejected before any write.
+
 ```bash
 npm i -D wendkeep && npx wendkeep init      # captures from the next session on
 npx wendkeep import                          # backfill past Claude + Codex sessions
@@ -189,8 +199,9 @@ Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://
 ## Operating Profiles — Keep Core is always active
 
 **Keep Core is always active**: the Vault, sessions, identity, CORE/SHARED, lessons, costs,
-and persistence do not turn off with the harness. **Wend Runtime** controls only the governance
-layer:
+and persistence do not turn off with the harness. **Wend Runtime** controls only the automatic
+governance layer. Even under `OFF`, explicit WendKeep commands remain available; invoking one is a
+deliberate opt-in and runs that command's own validations:
 
 | Profile | Route | Use |
 |---|---|---|

package/docs/en/commands/operating-profiles.md

@@ -8,6 +8,10 @@ Choose how much Wend Runtime governance an execution needs without disabling **K
 Keep Core is always active: the Vault, session, identity, CORE/SHARED, lessons, costs, and
 persistence integrations continue working under every profile.
 
+The `OFF` profile disables automatic governance activation, not the CLI: explicit commands such as
+`profile`, `flow`, `change`, `verify`, and `sensors` remain available. Invoking one is a deliberate
+opt-in and runs that command's own validations and gates.
+
 ## When to use
 
 Use `profile` to inspect or explicitly select an Operating Profile. Use `FLOW` for local,
@@ -44,11 +48,28 @@ Every FLOW subcommand also accepts `--project <path>`, `--vault <path>`, and `--
 provided, `--session` scopes ID-based reads and mutations to the session that owns the FLOW; an
 ID from another session fails without mutation.
 
+## Ownership and programmatic surface
+
+The private `packages/harness` workspace canonically owns Operating Profile resolution/policy and
+the sensor engine. Programmatic consumers use the public root-package subpath:
+
+```js
+import {
+  resolveOperatingProfile,
+  runSensors,
+  evaluateGate,
+} from 'wendkeep/harness';
+```
+
+`src/operating-profile.mjs` and `hooks/sensors-core.mjs` are compatibility facades only. Dependency
+direction is `adapters (cli/mcp/integrations/pi) -> Harness -> Vault`; Vault never depends on
+Harness. The workspaces remain private and are not published as independent npm packages.
+
 ## Options and exit codes
 
 | Profile | Route | Contract |
 |---|---|---|
-| `OFF` | LLM-native harness | Wend Runtime off; Keep Core intact. |
+| `OFF` | LLM-native harness | Automatic governance off; Keep Core and explicit commands available. |
 | `FLOW` | E → V | Microcontract with Git baseline, allowlist, sensors, and receipt, without a change. |
 | `GUIDE` | P → E → V | Compact change; policy recognized for compatible evolution. |
 | `GOVERN` | P → R → E → V | Current a2 loop and conservative fallback. |
@@ -145,9 +166,10 @@ npx wendkeep flow promote $flowId --change-slug another-slug
 ## Expected result
 
 Changing profile neither creates a new session nor interrupts the Vault. In `OFF`, memory and
-lessons are still injected and Stop still persists the session/memory lifecycle, while the
-router, skill gate, change context/warn/nag/guard, and plan capture are inactive. A completed FLOW
-leaves a durable, inspectable receipt; a promoted FLOW enters the normal change lifecycle.
+lessons are still injected and Stop still persists the session/memory lifecycle, while automatic
+router, skill gate, change context/warn/nag/guard, and plan capture are inactive. Explicit commands
+remain available and run their own contracts. A completed FLOW leaves a durable, inspectable
+receipt; a promoted FLOW enters the normal change lifecycle.
 
 ## Common errors and diagnosis
 

package/docs/pt-BR/commands/operating-profiles.md

@@ -8,6 +8,10 @@ Escolher quanta governança do Wend Runtime uma execução precisa sem desligar
 O Keep Core permanece sempre ativo: Vault, sessão, identidade, CORE/SHARED, lessons, custos e
 integrações de persistência continuam funcionando em todos os perfis.
 
+O perfil `OFF` desativa a ativação automática da governança, não a CLI: comandos explícitos como
+`profile`, `flow`, `change`, `verify` e `sensors` continuam disponíveis. Invocá-los é um opt-in
+deliberado e executa as validações e gates próprios daquele comando.
+
 ## Quando usar
 
 Use `profile` para consultar ou selecionar explicitamente um Perfil de Operação. Use `FLOW` para
@@ -44,11 +48,29 @@ Todos os subcomandos FLOW também aceitam `--project <path>`, `--vault <path>` e
 Quando informado, `--session` restringe inclusive consultas e mutações por ID à sessão dona do
 FLOW; um ID de outra sessão falha sem mutação.
 
+## Ownership e superfície programática
+
+O workspace privado `packages/harness` é o dono canônico da resolução/política dos Perfis de
+Operação e da engine de sensores. Consumidores programáticos usam o subpath público do pacote raiz:
+
+```js
+import {
+  resolveOperatingProfile,
+  runSensors,
+  evaluateGate,
+} from 'wendkeep/harness';
+```
+
+`src/operating-profile.mjs` e `hooks/sensors-core.mjs` são somente fachadas de compatibilidade. A
+direção de dependências é `adapters (cli/mcp/integrations/pi) -> Harness -> Vault`; o Vault nunca
+depende do Harness. Os workspaces continuam privados e não são publicados como pacotes npm
+independentes.
+
 ## Opções e códigos de saída
 
 | Perfil | Rota | Contrato |
 |---|---|---|
-| `OFF` | harness nativo da LLM | Wend Runtime desligado; Keep Core integral. |
+| `OFF` | harness nativo da LLM | Governança automática desligada; Keep Core e comandos explícitos disponíveis. |
 | `FLOW` | E → V | Microcontrato com baseline Git, allowlist, sensores e recibo, sem change. |
 | `GUIDE` | P → E → V | Change compacta; política reconhecida para evolução compatível. |
 | `GOVERN` | P → R → E → V | Loop a2 atual e fallback conservador. |
@@ -144,8 +166,9 @@ npx wendkeep flow promote $flowId --change-slug outro-slug
 
 Trocar o perfil não cria outra sessão nem interrompe o Vault. Em `OFF`, a memória e as lessons
 continuam injetadas e o Stop continua persistindo sessão/memória, mas router, skill gate,
-change context/warn/nag/guard e captura de plano ficam inativos. Um FLOW concluído deixa recibo
-durável e consultável; um FLOW promovido passa a seguir o lifecycle normal de change.
+change context/warn/nag/guard e captura de plano automáticos ficam inativos. Os comandos explícitos
+continuam disponíveis e executam seus próprios contratos. Um FLOW concluído deixa recibo durável e
+consultável; um FLOW promovido passa a seguir o lifecycle normal de change.
 
 ## Erros comuns e diagnóstico
 

package/hooks/locale.mjs

@@ -1,73 +1 @@
-// hooks/locale.mjs — vault locale (i18n, 0.8.0). The locale is a property of the VAULT,
-// stored at <vault>/.brain/config.json ({ "locale": "en" }); absent = pt-BR (full backward
-// compat). Parsers stay bilingual everywhere; only RENDERING follows the locale.
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-export const LOCALES = {
-  'pt-BR': {
-    id: 'pt-BR',
-    folders: {
-      inbox: '00-Inbox',
-      project: '01-Projeto',
-      sessions: '02-Sessões',
-      linear: '03-Linear',
-      decisions: '04-Decisões',
-      bugs: '05-Bugs',
-      learnings: '06-Aprendizados',
-      specs: '07-Specs',
-      changes: '08-Mudanças',
-    },
-    months: ['01-JAN', '02-FEV', '03-MAR', '04-ABR', '05-MAI', '06-JUN', '07-JUL', '08-AGO', '09-SET', '10-OUT', '11-NOV', '12-DEZ'],
-    reqHeading: 'Requisito',
-    fixTaskVerb: 'mata mutante',
-    coreSections: ['Preferências do Usuário', 'Padrões Ativos', 'Pendências Abertas'],
-  },
-  en: {
-    id: 'en',
-    folders: {
-      inbox: '00-Inbox',
-      project: '01-Project',
-      sessions: '02-Sessions',
-      linear: '03-Linear',
-      decisions: '04-Decisions',
-      bugs: '05-Bugs',
-      learnings: '06-Learnings',
-      specs: '07-Specs',
-      changes: '08-Changes',
-    },
-    months: ['01-JAN', '02-FEB', '03-MAR', '04-APR', '05-MAY', '06-JUN', '07-JUL', '08-AUG', '09-SEP', '10-OCT', '11-NOV', '12-DEC'],
-    reqHeading: 'Requirement',
-    fixTaskVerb: 'kill mutant',
-    coreSections: ['User Preferences', 'Active Patterns', 'Open Items'],
-  },
-};
-
-export const DEFAULT_LOCALE = 'pt-BR';
-
-// Per-process cache: one vault per process (hooks + CLI), reads are hot paths.
-const cache = new Map();
-
-export function getLocale(vaultBase) {
-  if (!vaultBase) return LOCALES[DEFAULT_LOCALE];
-  const key = String(vaultBase);
-  if (cache.has(key)) return cache.get(key);
-  let id = DEFAULT_LOCALE;
-  try {
-    const data = JSON.parse(readFileSync(join(key, '.brain', 'config.json'), 'utf8'));
-    if (data.locale && LOCALES[data.locale]) id = data.locale;
-  } catch { /* sem config = pt-BR */ }
-  const loc = LOCALES[id];
-  cache.set(key, loc);
-  return loc;
-}
-
-// Test hook: drop the memoized entry (tests rewrite config.json under one tmpdir).
-export function clearLocaleCache() {
-  cache.clear();
-}
-
-// The full vault taxonomy for a locale (folders + fixed entries), in creation order.
-export function vaultFolders(loc) {
-  return [...Object.values(loc.folders), 'Templates', '.brain'];
-}
+export * from '../packages/vault/src/locale.mjs';

package/hooks/sensors-core.mjs

@@ -1,102 +1 @@
-// hooks/sensors-core.mjs — native sensor runner + evidence gate (Pilar C).
-// Pure-ish: `spawn` is injectable so runs are testable without a shell. Config lives
-// at the PROJECT ROOT (wendkeep.sensors.json); evidence lives per-change in the vault.
-import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-
-export const SENSOR_VAULT_ENV = 'WENDKEEP_SENSOR_VAULT';
-
-export function sensorProcessEnv(vaultBase, inherited = process.env) {
-  return {
-    ...inherited,
-    OBSIDIAN_VAULT_PATH: vaultBase,
-    [SENSOR_VAULT_ENV]: vaultBase,
-  };
-}
-
-export function loadSensors(projectRoot, file = 'wendkeep.sensors.json') {
-  return loadSensorsDetailed(projectRoot, file).sensors;
-}
-
-// Missing config and broken config are different failures: absent file usually means
-// wrong cwd (subdirectory), broken JSON means the config itself needs fixing. Collapsing
-// both into [] made every sensor report "sensor não definido" — a misleading diagnosis.
-export function loadSensorsDetailed(projectRoot, file = 'wendkeep.sensors.json') {
-  const path = join(projectRoot, file);
-  if (!existsSync(path)) return { sensors: [], missing: true, error: null, path };
-  try {
-    const data = JSON.parse(readFileSync(path, 'utf8'));
-    return { sensors: Array.isArray(data.sensors) ? data.sensors : [], missing: false, error: null, path };
-  } catch (e) {
-    return { sensors: [], missing: false, error: e.message, path };
-  }
-}
-
-// Climb the directory tree looking for a project marker (wendkeep.sensors.json or
-// .wendkeep.json), like git does with .git — shells in agent harnesses keep their cwd
-// across commands, so verify is often run from a subdirectory.
-export function findProjectRoot(startDir) {
-  let dir = resolve(startDir);
-  for (;;) {
-    if (existsSync(join(dir, 'wendkeep.sensors.json')) || existsSync(join(dir, '.wendkeep.json'))) return dir;
-    const parent = dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
-
-export function requiredSensors(tasks) {
-  return [...new Set((tasks || []).flatMap((task) => (
-    Array.isArray(task.sensors) && task.sensors.length ? task.sensors : [task.sensor]
-  )).filter(Boolean))];
-}
-
-export function runSensors(sensors, ids, { spawn = spawnSync, cwd, env, now } = {}) {
-  const byId = Object.fromEntries((sensors || []).map((s) => [s.id, s]));
-  const ts = now || new Date().toISOString();
-  const evidence = [];
-  for (const id of ids) {
-    const s = byId[id];
-    if (!s) { evidence.push({ id, status: 'red', ts, severity: 'critical', note: 'sensor não definido' }); continue; }
-    const r = spawn(s.command, [], { cwd, shell: true, stdio: 'ignore', ...(env ? { env } : {}) });
-    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.
-export function evaluateGate(evidence, requiredIds) {
-  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 };
-}
+export * from '../packages/harness/src/sensors-core.mjs';