wendkeep 0.66.4 → 0.67.0

package/src/rebuild-costs.mjs

@@ -1,45 +1,231 @@
-// Deterministic cost reconstruction for historical sessions.
-// Registry is authoritative: session_file <-> transcript_path. Dry-run restores every note.
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+// Deterministic, causal reconstruction for historical session observability.
+// Dry-run is a pure composition pass; apply delegates all note mutation to the CAS publisher.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { readSessionRegistry } from '../hooks/obsidian-common.mjs';
-import { updateSessionObservability } from '../hooks/session-observability.mjs';
+import * as sessionObservability from '../hooks/session-observability.mjs';
+import {
+  mutateObservabilityStore,
+  readObservabilityStore,
+} from '../hooks/session-observability-store.mjs';
+import { sanitizeObservabilityDiagnostics } from '../hooks/session-observability-state.mjs';
 import { assertVaultPathSafe } from '../hooks/vault-path-safety.mjs';
 
-export function rebuildSessionCosts(vaultBase, { apply = false, session = '', limit = 0 } = {}) {
-  const registry = readSessionRegistry(vaultBase);
-  const report = { version: 1, generatedAt: new Date().toISOString(), mode: apply ? 'apply' : 'dry-run', scanned: 0, changed: 0, unchanged: 0, missing: [], errors: [], sessions: [] };
-  const entries = Object.entries(registry.sessions || {}).map(([sessionId, value]) => ({ sessionId, ...value }))
-    .filter((e) => e.session_file)
-    .filter((e) => !session || e.sessionId === session || e.session_file === session);
-  for (const entry of entries) {
+function sortedEntries(registry, target) {
+  return Object.entries(registry?.sessions || {})
+    .map(([sessionId, value]) => ({ sessionId, ...value }))
+    .filter((entry) => entry.session_file)
+    .filter((entry) => !target || entry.sessionId === target || entry.session_file === target)
+    .sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+}
+
+function transcriptCandidates(entry) {
+  const paths = new Set();
+  if (entry.transcript_path) paths.add(entry.transcript_path);
+  for (const path of entry.transcript_paths || []) if (path) paths.add(path);
+  const activations = Array.isArray(entry.activations)
+    ? entry.activations
+    : Object.values(entry.activations || {});
+  for (const activation of activations) {
+    if (activation?.transcript_path) paths.add(activation.transcript_path);
+    for (const path of activation?.transcript_paths || []) if (path) paths.add(path);
+  }
+  return [...paths];
+}
+
+function candidateContent(candidate, fallback) {
+  return typeof candidate?.content === 'string' ? candidate.content : fallback;
+}
+
+function candidateHash(candidate, fallback) {
+  return createHash('sha256').update(candidateContent(candidate, fallback)).digest('hex');
+}
+
+function safeDiagnostics(input, fallback = []) {
+  try {
+    return sanitizeObservabilityDiagnostics(input || fallback);
+  } catch {
+    return sanitizeObservabilityDiagnostics(fallback);
+  }
+}
+
+export function semanticRebuildReport(report) {
+  const {
+    generatedAt: _generatedAt,
+    changed = 0,
+    unchanged = 0,
+    sessions = [],
+    ...semantic
+  } = report || {};
+  return {
+    ...semantic,
+    converged: Number(changed || 0) + Number(unchanged || 0),
+    sessions: sessions.map((entry) => ({
+      ...entry,
+      status: entry.status === 'published' || entry.status === 'unchanged'
+        ? 'converged'
+        : entry.status,
+    })),
+  };
+}
+
+export function writeRebuildReportIfChanged(reportPath, report) {
+  if (existsSync(reportPath)) {
+    try {
+      const previous = JSON.parse(readFileSync(reportPath, 'utf8'));
+      if (JSON.stringify(semanticRebuildReport(previous))
+        === JSON.stringify(semanticRebuildReport(report))) return false;
+    } catch {
+      // Invalid prior reports are replaced by the sanitized current schema.
+    }
+  }
+  mkdirSync(dirname(reportPath), { recursive: true });
+  writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+  return true;
+}
+
+function markDirtyDefault(vaultBase, sessionId, diagnostics) {
+  mutateObservabilityStore(vaultBase, sessionId, (state) => ({
+    ...state,
+    observability_dirty: true,
+    diagnostics: safeDiagnostics(diagnostics, [{ code: 'STALE_FRONTIER', count: 1 }]),
+  }));
+}
+
+export function rebuildSessionCosts(
+  vaultBase,
+  {
+    apply = false,
+    session = '',
+    limit = 0,
+    limits = {},
+    overrides = {},
+  } = {},
+  effects = {},
+) {
+  const readRegistry = effects.readRegistry || readSessionRegistry;
+  const compose = effects.compose || sessionObservability.composeSessionObservability;
+  const publish = effects.publish || sessionObservability.publishSessionObservability;
+  const readStore = effects.readStore || readObservabilityStore;
+  const markDirty = effects.markDirty || markDirtyDefault;
+  const writeReport = effects.writeReport || writeRebuildReportIfChanged;
+  const now = effects.now || (() => new Date().toISOString());
+  if (typeof compose !== 'function') throw new TypeError('composeSessionObservability indisponível');
+  if (apply && typeof publish !== 'function') throw new TypeError('publishSessionObservability indisponível');
+
+  const registry = readRegistry(vaultBase);
+  const report = {
+    version: 2,
+    generatedAt: now(),
+    mode: apply ? 'apply' : 'dry-run',
+    targeted: Boolean(session),
+    overrides: { ...overrides },
+    scanned: 0,
+    changed: 0,
+    unchanged: 0,
+    degraded: 0,
+    stale: 0,
+    missing: 0,
+    errors: 0,
+    ok: true,
+    sessions: [],
+  };
+
+  for (const entry of sortedEntries(registry, session)) {
     if (limit && report.scanned >= limit) break;
     report.scanned += 1;
-    const checkedNote = assertVaultPathSafe(vaultBase, join(vaultBase, entry.session_file), {
-      expectedType: 'file', label: 'nota de sessão do rebuild de custos',
-    });
-    const note = checkedNote.target;
-    if (!entry.transcript_path || !checkedNote.exists || !existsSync(entry.transcript_path)) {
-      report.missing.push({ sessionId: entry.sessionId, session: entry.session_file, note: checkedNote.exists, transcript: !!entry.transcript_path && existsSync(entry.transcript_path), transcriptPath: entry.transcript_path || '' });
-      continue;
-    }
-    const before = readFileSync(note, 'utf8');
+    let note;
     try {
-      updateSessionObservability({
-        vaultBase, sessionPath: note, transcriptPath: entry.transcript_path,
-        caller: 'cost-rebuild', canonicalConversationId: entry.sessionId,
+      const checked = assertVaultPathSafe(vaultBase, join(vaultBase, entry.session_file), {
+        expectedType: 'file', label: 'nota de sessão do rebuild de custos',
       });
-      const after = readFileSync(note, 'utf8');
-      const changed = before !== after;
-      if (changed) report.changed += 1; else report.unchanged += 1;
-      report.sessions.push({ sessionId: entry.sessionId, session: entry.session_file, transcript: entry.transcript_path, changed });
-      if (!apply && changed) writeFileSync(note, before, 'utf8');
-    } catch (error) {
-      if (!apply) writeFileSync(note, before, 'utf8');
-      report.errors.push({ sessionId: entry.sessionId, session: entry.session_file, error: error.message });
+      const hasTranscript = transcriptCandidates(entry).some((path) => existsSync(path));
+      if (!checked.exists || !hasTranscript) {
+        report.missing += 1;
+        report.sessions.push({
+          sessionId: entry.sessionId, status: 'missing', diagnostics: [],
+        });
+        continue;
+      }
+      note = checked.target;
+      const before = readFileSync(note, 'utf8');
+      const runtimeState = readStore(vaultBase, entry.sessionId);
+      const candidate = compose({
+        vaultBase,
+        sessionContent: before,
+        sessionEntry: entry,
+        canonicalConversationId: entry.sessionId,
+        caller: 'cost-rebuild',
+        mode: 'offline',
+        limits,
+        runtimeState,
+      });
+      const diagnostics = safeDiagnostics(candidate?.diagnostics);
+      const contentHash = candidateHash(candidate, before);
+      if (candidate?.state === 'degraded') {
+        report.degraded += 1;
+        report.sessions.push({ sessionId: entry.sessionId, status: 'degraded', diagnostics });
+        if (apply) markDirty(vaultBase, entry.sessionId, diagnostics);
+        continue;
+      }
+      if (candidate?.state !== 'complete' && candidate?.state !== 'none') {
+        report.degraded += 1;
+        const invalidDiagnostics = [{ code: 'PARENT_META_INVALID', count: 1 }];
+        report.sessions.push({
+          sessionId: entry.sessionId, status: 'degraded', diagnostics: invalidDiagnostics,
+        });
+        if (apply) markDirty(vaultBase, entry.sessionId, invalidDiagnostics);
+        continue;
+      }
+
+      if (!apply) {
+        const changed = candidateContent(candidate, before) !== before;
+        if (changed) report.changed += 1;
+        else report.unchanged += 1;
+        report.sessions.push({
+          sessionId: entry.sessionId,
+          status: changed ? 'would-change' : 'unchanged',
+          candidateHash: contentHash,
+          diagnostics,
+        });
+        continue;
+      }
+
+      const outcome = publish({
+        vaultBase,
+        sessionPath: note,
+        canonicalConversationId: entry.sessionId,
+        candidate,
+        caller: 'cost-rebuild',
+        mode: 'offline',
+        allowSourceRefresh: true,
+      }) || { status: 'degraded' };
+      if (outcome.status === 'published') report.changed += 1;
+      else if (outcome.status === 'unchanged') report.unchanged += 1;
+      else if (outcome.status === 'stale' || outcome.status === 'conflict') {
+        report.stale += 1;
+        markDirty(vaultBase, entry.sessionId, [{ code: 'STALE_FRONTIER', count: 1 }]);
+      } else {
+        report.degraded += 1;
+        markDirty(vaultBase, entry.sessionId, [{ code: 'PARENT_META_INVALID', count: 1 }]);
+      }
+      report.sessions.push({
+        sessionId: entry.sessionId,
+        status: outcome.status || 'degraded',
+        candidateHash: contentHash,
+        diagnostics: safeDiagnostics(outcome.diagnostics, diagnostics),
+      });
+    } catch {
+      report.errors += 1;
+      const diagnostics = [{ code: 'PARENT_META_INVALID', count: 1 }];
+      report.sessions.push({ sessionId: entry.sessionId, status: 'degraded', diagnostics });
+      if (apply) markDirty(vaultBase, entry.sessionId, diagnostics);
     }
   }
-  report.ok = report.errors.length === 0 && report.missing.length === 0;
-  if (apply) writeFileSync(join(vaultBase, '.brain', 'COST_REBUILD.json'), `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+
+  report.ok = report.degraded === 0 && report.stale === 0
+    && report.missing === 0 && report.errors === 0;
+  if (apply) writeReport(join(vaultBase, '.brain', 'COST_REBUILD.json'), report);
   return report;
 }

package/src/skills-seed.mjs

@@ -17,6 +17,24 @@ Use ao começar implementação, correção ou refatoração. **Keep Core perman
 em todos os perfis: Vault, sessão, identidade, memória, lessons e persistência. Na ausência de
 configuração válida, **GOVERN é o padrão** compatível.
 
+## Seleção temporária por solicitação
+
+Antes de editar, classifique a implementação atual e registre a escolha auditável com
+\`wendkeep profile route <FLOW|GUIDE|GOVERN|ASSURE> --session <id> --reason <texto>\`.
+A lease vale somente para a solicitação atual; ao encerrá-la, o perfil persistente da
+sessão/projeto volta a valer. **OFF nunca é uma escolha automática da LLM**: somente uma pessoa
+pode persistir \`profile use OFF\` explicitamente.
+
+- **FLOW:** ajuste local, reversível e de escopo fechado, sem contrato/spec, segurança,
+  dependência, CI/release ou policy.
+- **GUIDE:** mudança compacta de comportamento que precisa de change/spec, sem revisão formal.
+- **GOVERN:** escolha conservadora em caso de dúvida ou risco e para superfícies sensíveis.
+- **ASSURE:** GOVERN quando confirmação explícita e handoff fazem parte do contrato.
+
+O harness da LLM faz essa classificação semântica; o Wend Runtime valida e aplica a lease.
+Se não houver uma sessão causal identificada ou o comando falhar, não fabrique estado: use o
+perfil efetivo já injetado e trate \`GOVERN\` como fallback conservador quando ele for o padrão.
+
 <HARD-GATE>
 Antes de editar, leia o **perfil efetivo** injetado pelo WendKeep e siga somente sua rota:
 - \`OFF\`: não imponha processo Wend; a governança pertence ao **harness nativo da LLM**.
@@ -268,6 +286,24 @@ Use this when starting an implementation, fix, or refactor. **Keep Core is alway
 in every profile: Vault, session, identity, memory, lessons, and persistence. With no valid
 configuration, **GOVERN is the default** for compatibility.
 
+## Temporary selection per request
+
+Before editing, classify the current implementation and record the auditable choice with
+\`wendkeep profile route <FLOW|GUIDE|GOVERN|ASSURE> --session <id> --reason <text>\`.
+The lease applies only to the current request; after it ends, the persistent session/project
+profile becomes effective again. **OFF is never an automatic LLM choice**: only a human can
+persist it explicitly through \`profile use OFF\`.
+
+- **FLOW:** a local, reversible, bounded adjustment with no contract/spec, security, dependency,
+  CI/release, or policy impact.
+- **GUIDE:** a compact behavior change that needs a change/spec but no formal review.
+- **GOVERN:** the conservative choice when uncertain or risky, and for sensitive surfaces.
+- **ASSURE:** GOVERN when explicit confirmation and handoff are part of the contract.
+
+The LLM harness owns semantic classification; Wend Runtime validates and applies the lease. If
+there is no causally identified session or the command fails, do not fabricate state: use the
+already injected effective profile, with \`GOVERN\` as the conservative configured fallback.
+
 <HARD-GATE>
 Before editing, read the injected **effective profile** and follow only its route:
 - \`OFF\`: impose no Wend process; governance belongs to the **native LLM harness**.
@@ -619,7 +655,7 @@ size of the problem>
 // usuário ("implementa X", "corrige Y"), não com abstrações ("mudança não-trivial"). Gatilhos
 // concretos + instrução imperativa = a skill dispara sozinha (paridade Superpowers).
 const WK_SKILLS_PT = [
-  skill('wk-workflow', 'Use quando o usuário pedir para implementar, criar, corrigir, refatorar, adicionar ou alterar código: leia o perfil efetivo e roteie OFF/FLOW/GUIDE/GOVERN/ASSURE ANTES de editar. Keep Core permanece ativo; GOVERN é o padrão compatível.', WORKFLOW),
+  skill('wk-workflow', 'Use quando o usuário pedir para implementar, criar, corrigir, refatorar, adicionar ou alterar código: classifique e registre a rota temporária FLOW/GUIDE/GOVERN/ASSURE ANTES de editar, então siga o perfil efetivo. Keep Core permanece ativo; OFF nunca é automático.', WORKFLOW),
   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, quebra, dá erro ou regride — depuração sistemática por hipótese antes de corrigir.', DEBUGGING),
   skill('wk-brainstorming', 'Use quando a ideia ainda é vaga ou o usuário quer discutir/planejar uma feature (inclusive em plan mode) — vira design aprovado, com closure gate e tabela out-of-scope, antes de código.', BRAINSTORMING, [{ name: 'design-template.md', content: DESIGN_TEMPLATE_PT }]),
@@ -628,7 +664,7 @@ const WK_SKILLS_PT = [
 ];
 
 const WK_SKILLS_EN = [
-  skill('wk-workflow', 'Use when the user asks to implement, create, fix, refactor, add, or change code: read the effective profile and route OFF/FLOW/GUIDE/GOVERN/ASSURE BEFORE editing. Keep Core stays active; GOVERN is the compatible default.', WORKFLOW_EN),
+  skill('wk-workflow', 'Use when the user asks to implement, create, fix, refactor, add, or change code: classify and record the temporary FLOW/GUIDE/GOVERN/ASSURE route BEFORE editing, then follow the effective profile. Keep Core stays active; OFF is never automatic.', WORKFLOW_EN),
   skill('wk-tdd', 'Use when implementing any behaviour — Red/Green/Refactor with tests that discriminate (spec-derived, non-shallow litmus, adequacy).', TDD_EN),
   skill('wk-debugging', 'Use when something fails, breaks, errors or regresses — systematic hypothesis-driven debugging before fixing.', DEBUGGING_EN),
   skill('wk-brainstorming', 'Use when the idea is still vague or the user wants to discuss/plan a feature (plan mode included) — turns it into an approved design, with a closure gate and out-of-scope table, before code.', BRAINSTORMING_EN, [{ name: 'design-template.md', content: DESIGN_TEMPLATE_EN }]),

package/src/sync-defs.mjs

@@ -62,7 +62,12 @@ function renderAgentsSection(skills, sourceHash = '') {
 
 This project uses the [wendkeep](https://github.com/rogersialves/wendkeep) harness. **Keep Core is always active**
 in every profile: Vault, session, identity, memory, lessons, and persistence integrations.
-The effective profile is selected explicitly; missing or invalid configuration uses **GOVERN as the default**.
+The persistent profile is selected explicitly; missing or invalid configuration uses **GOVERN as the default**.
+
+Before an implementation, the native LLM harness classifies the current request and may create a
+task-scoped lease with \`wendkeep profile route <FLOW|GUIDE|GOVERN|ASSURE> --session <id> --reason <text>\`.
+The lease expires when that request ends and the persistent session/project profile becomes
+effective again. **OFF is never selected adaptively**; only a human can persist \`profile use OFF\`.
 
 Route work by the effective profile:
 - **OFF** — Wend Runtime is disabled and governance belongs to the native LLM harness; Keep Core stays active.