wendkeep 0.76.9 → 0.78.0

package/hooks/harness-doctor.mjs

@@ -17,6 +17,14 @@ import {
 import { parseObservabilityCheckpoint } from './session-observability-state.mjs';
 import { readObservabilityStore } from './session-observability-store.mjs';
 import { assessObservabilityFreshness } from './session-observability-lifecycle.mjs';
+import { evaluateEvidenceBinding } from '../packages/vault/src/evidence-envelope.mjs';
+import { evidenceCheckoutBinding } from '../packages/vault/src/evidence-envelope.mjs';
+import { loadSensorsDetailed, requiredSensors } from './sensors-core.mjs';
+import {
+  captureGitSnapshot,
+  resolveEvidenceIdentity,
+  sensorConfigSha256,
+} from '../src/evidence-envelope.mjs';
 
 export function checkSessionObservability(vaultBase, deps = {}) {
   const readRegistry = deps.readRegistry || readSessionRegistry;
@@ -144,10 +152,52 @@ export function checkHarness(vaultBase, projectRoot) {
     const effective = buildEffectiveRequirementPackage(vaultBase, dir, reqIds);
     errors.push(...effective.errors.map((e) => `${name}: spec efetiva inválida: ${e}`));
     if (effective.missing.length) errors.push(`req órfão em ${name}: ${effective.missing.map((id) => `[req:${id}]`).join(', ')} não existe na spec efetiva`);
+    let evidence = null;
+    try { evidence = JSON.parse(readFileSync(join(dir, 'evidencia.json'), 'utf8')); } catch { /* sem evidência */ }
+    if (evidence) {
+      const expected = {
+        change_slug: name,
+        tasks_sha256: tasksHashOf(tarefasMd),
+        effective_spec_sha256: `sha256:${effective.hash}`,
+      };
+      let bindingUnavailable = '';
+      if (evidence.schema_version === 2 && projectRoot) {
+        try {
+          const loaded = loadSensorsDetailed(projectRoot);
+          if (loaded.error) throw new Error(`wendkeep.sensors.json inválido: ${loaded.error}`);
+          expected.identity = resolveEvidenceIdentity({
+            vaultBase,
+            projectRoot,
+            changeSlug: name,
+            sessionId: evidence.work_session_id,
+          });
+          expected.snapshot = captureGitSnapshot(projectRoot);
+          expected.sensor_config_sha256 = sensorConfigSha256(
+            loaded.sensors,
+            requiredSensors(tasks),
+          );
+        } catch (error) {
+          bindingUnavailable = error.code || error.message;
+        }
+      }
+      const binding = evaluateEvidenceBinding(evidence, expected);
+      if (binding.state === 'legacy-unbound') {
+        attention.push(`${name}: evidence legacy-unbound — rode wendkeep verify novamente`);
+      } else if (binding.state !== 'bound') {
+        attention.push(`${name}: evidence ${binding.state} (${binding.reasons.join('; ')}) — rode wendkeep verify novamente`);
+      } else if (bindingUnavailable) {
+        attention.push(`${name}: evidence binding atual indisponível (${bindingUnavailable}) — rode doctor da raiz Git e depois wendkeep verify`);
+      }
+    }
     let verdict = null;
     try { verdict = JSON.parse(readFileSync(join(dir, 'verdict.json'), 'utf8')); } catch { /* sem verdict */ }
     if (verdict && reqIds.length) {
-      const v = evaluateVerdict(verdict, reqIds, { tasksHash: tasksHashOf(tarefasMd), effectiveSpecHash: effective.hash });
+      const v = evaluateVerdict(verdict, reqIds, {
+        tasksHash: tasksHashOf(tarefasMd),
+        effectiveSpecHash: effective.hash,
+        evidenceEnvelopeId: evidence?.schema_version === 2 ? evidence.envelope_id : undefined,
+        evidenceBinding: evidence?.schema_version === 2 ? evidenceCheckoutBinding(evidence) : undefined,
+      });
       if (!v.ok) attention.push(`verdict stale/incompleto em ${name}${v.missing.length ? `: falta cobrir ${v.missing.join(', ')}` : ''}`);
     }
   }

package/hooks/spec-core.mjs

@@ -5,12 +5,12 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { getLocale } from './locale.mjs';
 import {
-  assertVaultPathSafe, assertVaultPathsSafe, mkdirVaultPath, writeVaultFileSync,
+  assertVaultPathSafe, assertVaultPathsSafe, mkdirVaultPath, writeVaultFileAtomic, writeVaultFileSync,
 } from './vault-path-safety.mjs';
 
-// Short stable fingerprint of tarefas.md — freshness check between package/verdict and gate.
+// Canonical SHA-256 fingerprint of tarefas.md — freshness binding between package/verdict and gate.
 export function tasksHashOf(md) {
-  return createHash('sha1').update(String(md)).digest('hex').slice(0, 12);
+  return `sha256:${createHash('sha256').update(String(md).replace(/\r\n?/g, '\n')).digest('hex')}`;
 }
 
 export function contentHashOf(value) {
@@ -168,7 +168,11 @@ function recordPromotedSpecs(vaultBase, capabilities) {
   return state;
 }
 
-export function captureSpecBaseline(vaultBase, changeDir, { refresh = false } = {}) {
+export function captureSpecBaseline(vaultBase, changeDir, {
+  refresh = false,
+  writeAtomic = writeVaultFileAtomic,
+  beforeRename,
+} = {}) {
   const path = join(changeDir, SPEC_BASELINE_FILE);
   const checked = assertVaultPathSafe(vaultBase, path, {
     expectedType: 'file', label: 'baseline de specs da change',
@@ -177,12 +181,12 @@ export function captureSpecBaseline(vaultBase, changeDir, { refresh = false } =
     try { return JSON.parse(readFileSync(path, 'utf8')); } catch { /* rebuild malformed baseline */ }
   }
   const baseline = { version: 1, capturedAt: new Date().toISOString(), specs: readLivingSpecs(vaultBase) };
-  writeVaultFileSync(
+  writeAtomic(
     vaultBase,
     path,
     `${JSON.stringify(baseline, null, 2)}\n`,
     'utf8',
-    { label: 'baseline de specs da change' },
+    { scopeRoot: changeDir, label: 'baseline de specs da change', beforeRename },
   );
   return baseline;
 }
@@ -474,10 +478,24 @@ export function promoteSpecs(vaultBase, changeDir, specs, { changeWikilink, date
 // Gate check for the independent verdict (Wave A). A requirement-bearing change must have
 // a verdict that is ok and covers every declared req id. A requirement-less change passes:
 // nothing for an independent verifier to check — the sensor gate is already the proof.
-export function evaluateVerdict(verdict, reqIds, { tasksHash, effectiveSpecHash } = {}) {
+export function evaluateVerdict(verdict, reqIds, {
+  tasksHash,
+  effectiveSpecHash,
+  evidenceEnvelopeId,
+  evidenceBinding,
+} = {}) {
   const ids = reqIds || [];
-  if (ids.length === 0) return { ok: true, missing: [] };
+  if (ids.length === 0 && !evidenceEnvelopeId) return { ok: true, missing: [] };
   if (!verdict || verdict.ok !== true) return { ok: false, missing: [] };
+  if (evidenceEnvelopeId && verdict.evidenceEnvelopeId !== evidenceEnvelopeId) {
+    return { ok: false, missing: [], stale: true };
+  }
+  if (evidenceBinding && (!verdict.evidenceBinding || Object.entries(evidenceBinding).some(
+    ([key, value]) => verdict.evidenceBinding[key] !== value,
+  ))) {
+    return { ok: false, missing: [], stale: true };
+  }
+  if (ids.length === 0) return { ok: true, missing: [] };
   // Freshness (G3/#6): a verdict minted against a different tarefas.md is stale. Verdicts
   // without a hash (pre-0.6.1) are accepted for backward compat.
   if (tasksHash && verdict.tasksHash && verdict.tasksHash !== tasksHash) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.76.9",
+  "version": "0.78.0",
   "description": "Vault-first persistent memory for AI coding agents, with an optional profile-aware governance runtime: OFF, FLOW, GUIDE, GOVERN, or ASSURE. Local-first and agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "workspaces": [
@@ -41,7 +41,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "precheck": "node --check src/worktree.mjs && node --check src/context.mjs && node --check src/active-context-health.mjs && node --check src/active-context-runtime.mjs && node --check hooks/active-context-store.mjs && node --check hooks/change-core.mjs && node --check hooks/brain-inject.mjs && node --check hooks/change-context.mjs && node --check packages/vault/src/worktree-metadata.mjs",
+    "precheck": "node --check src/worktree.mjs && node --check src/worktree-cleanup.mjs && node --check src/evidence-envelope.mjs && node --check src/context.mjs && node --check src/active-context-health.mjs && node --check src/active-context-runtime.mjs && node --check hooks/active-context-store.mjs && node --check hooks/change-core.mjs && node --check hooks/brain-inject.mjs && node --check hooks/change-context.mjs && node --check packages/vault/src/worktree-metadata.mjs && node --check packages/vault/src/evidence-envelope.mjs",
     "check": "node --check scripts/release.mjs && node --check scripts/release-plan.mjs && node --check scripts/release-provenance.mjs && node --check scripts/run-scope.mjs && node --check src/release-provenance.mjs && node --check bin/wendkeep.mjs && node --check packages/cli/src/index.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/active-context-health.mjs && node --check src/project-vault.mjs && node --check src/observer-auth.mjs && node --check src/observer-privacy.mjs && node --check src/observer-snapshot.mjs && node --check src/observer-store.mjs && node --check src/observer-memory.mjs && node --check src/observer-memory-publish.mjs && node --check src/observer-sql-store.mjs && node --check src/observer-sql-migrate.mjs && node --check src/observer-sql-publish.mjs && node --check src/observer-transcript-store.mjs && node --check src/observer-server.mjs && node --check src/observer.mjs && node --check src/observer-publish.mjs && node --check src/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.mjs && node --check src/work-kind.mjs && node --check src/delivery.mjs && node --check web/observer/app.mjs && node --check hooks/observer-publish.mjs && node --check hooks/evidence-context.mjs && node --check hooks/active-context-handoff-evidence.mjs && node --check hooks/evidence-recall.mjs && node --check hooks/memory-scope.mjs && node --check hooks/operating-profile-runtime.mjs && node --check hooks/operating-profile-task-store.mjs && node --check hooks/flow-core.mjs && node --check hooks/flow-protected-policy.mjs && node --check hooks/git-snapshot.mjs && node --check hooks/vault-path-safety.mjs && node --check hooks/vault-runtime-store.mjs && node --check packages/harness/src/index.mjs && node --check packages/harness/src/flow-store.mjs && node --check packages/harness/src/operating-profile.mjs && node --check packages/harness/src/sensors-core.mjs && node --check packages/integrations/src/host-hooks.mjs && node --check packages/integrations/src/hook-envelope.mjs && node --check packages/integrations/src/prompt-content.mjs && node --check packages/integrations/src/transcript-usage.mjs && node --check packages/integrations/src/transcripts.mjs && node --check packages/integrations/src/session-identity.mjs && node --check packages/integrations/src/index.mjs && node --check packages/mcp/src/config.mjs && node --check packages/mcp/src/index.mjs && node --check packages/vault/src/index.mjs && node --check packages/vault/src/project-vault.mjs && node --check packages/vault/src/vault-path-safety.mjs && node --check packages/vault/src/locale.mjs && node --check packages/vault/src/memory-schema.mjs && node --check packages/vault/src/memory-mode.mjs && node --check packages/vault/src/memory-scope.mjs && node --check packages/vault/src/memory-candidate-policy.mjs && node --check packages/vault/src/evidence-recall.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/vault/src/memory-store.mjs && node --check packages/vault/src/validate-core.mjs && node --check packages/vault/src/validate-memory.mjs",
     "test": "node --test --test-concurrency=2",
     "test:core": "node scripts/run-scope.mjs core",

package/packages/cli/src/index.mjs

@@ -249,7 +249,7 @@ async function main(argv) {
     }
     case 'worktree': {
       const { runWorktree } = await import('../../../src/worktree.mjs');
-      process.exit(runWorktree(rest));
+      process.exit(await runWorktree(rest));
       break;
     }
     case 'context': {

package/packages/harness/src/sensors-core.mjs

@@ -2,6 +2,7 @@
 // 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 { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
@@ -22,6 +23,22 @@ function sanitizeSensorDiagnostic(value) {
     .trim();
 }
 
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(String(value || '')).digest('hex')}`;
+}
+
+function sensorNow(now) {
+  const value = typeof now === 'function' ? now() : (now || new Date().toISOString());
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'string') return value;
+  return new Date(value).toISOString();
+}
+
+function elapsedMilliseconds(startedAt, finishedAt) {
+  const elapsed = Date.parse(finishedAt) - Date.parse(startedAt);
+  return Number.isFinite(elapsed) ? Math.max(0, elapsed) : 0;
+}
+
 function sensorFailureNote(result = {}) {
   const status = result.status ?? 'null';
   const header = [
@@ -86,11 +103,29 @@ export function requiredSensors(tasks) {
 
 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 startedAt = sensorNow(now);
     const s = byId[id];
-    if (!s) { evidence.push({ id, status: 'red', ts, severity: 'critical', note: 'sensor não definido' }); continue; }
+    if (!s) {
+      const finishedAt = sensorNow(now);
+      evidence.push({
+        id,
+        status: 'red',
+        ts: startedAt,
+        severity: 'critical',
+        started_at: startedAt,
+        finished_at: finishedAt,
+        duration_ms: elapsedMilliseconds(startedAt, finishedAt),
+        exit_code: null,
+        command: '',
+        command_sha256: sha256(''),
+        output_sha256: sha256(''),
+        output_tail: '',
+        note: 'sensor não definido',
+      });
+      continue;
+    }
     const r = spawn(s.command, [], {
       cwd,
       shell: true,
@@ -99,7 +134,26 @@ export function runSensors(sensors, ids, { spawn = spawnSync, cwd, env, now } =
       stdio: ['ignore', 'pipe', 'pipe'],
       ...(env ? { env } : {}),
     });
-    const entry = { id, status: (r.status ?? 1) === 0 ? 'green' : 'red', ts, severity: s.severity || 'critical' };
+    const finishedAt = sensorNow(now);
+    const rawOutput = [r.stdout, r.stderr].filter(Boolean).join('\n');
+    const outputTail = sanitizeSensorDiagnostic(rawOutput);
+    const boundedOutputTail = outputTail.length > SENSOR_DIAGNOSTIC_MAX_LENGTH
+      ? `…${outputTail.slice(-(SENSOR_DIAGNOSTIC_MAX_LENGTH - 1))}`
+      : outputTail;
+    const entry = {
+      id,
+      status: (r.status ?? 1) === 0 ? 'green' : 'red',
+      ts: startedAt,
+      severity: s.severity || 'critical',
+      command: sanitizeSensorDiagnostic(s.command),
+      command_sha256: sha256(s.command),
+      started_at: startedAt,
+      finished_at: finishedAt,
+      duration_ms: elapsedMilliseconds(startedAt, finishedAt),
+      exit_code: Number.isInteger(r.status) ? r.status : null,
+      output_sha256: sha256(rawOutput),
+      output_tail: boundedOutputTail,
+    };
     if (entry.status === 'red') entry.note = sensorFailureNote(r);
     if (s.type === 'mutation' && s.report) {
       // Delegated mutation (Wave B): read the tool's mutation-testing-elements report and

package/packages/vault/src/evidence-envelope.mjs

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === 'object' && !Buffer.isBuffer(value)) {
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [key, stableValue(value[key])]),
+    );
+  }
+  return value;
+}
+
+export function canonicalSha256(value) {
+  const bytes = Buffer.isBuffer(value) || value instanceof Uint8Array
+    ? value
+    : JSON.stringify(stableValue(value));
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+export function evidenceSensors(evidence) {
+  if (Array.isArray(evidence)) return evidence;
+  return Array.isArray(evidence?.sensors) ? evidence.sensors : [];
+}
+
+const CHECKOUT_BINDING_KEYS = [
+  'project_id', 'repository_id', 'worktree_id', 'head_sha', 'index_tree_sha', 'worktree_digest',
+];
+
+export function evidenceCheckoutBinding(evidence = {}) {
+  return Object.fromEntries(CHECKOUT_BINDING_KEYS.map((key) => [key, evidence[key]]));
+}
+
+export function evidenceCheckoutBindingMatches(actual, expected) {
+  return Boolean(actual && expected) && CHECKOUT_BINDING_KEYS.every(
+    (key) => actual[key] === expected[key] && expected[key] != null,
+  );
+}
+
+export function evaluateEvidenceBinding(evidence, expected = {}) {
+  if (!evidence) return { state: 'unproven', reasons: ['evidence missing'] };
+  if (Array.isArray(evidence) || evidence.schema_version !== 2) {
+    return { state: 'legacy-unbound', reasons: ['evidence schema v1 has no checkout binding'] };
+  }
+
+  const contextReasons = [];
+  if (expected.change_slug != null && evidence.change_slug !== expected.change_slug) {
+    contextReasons.push('change_slug mismatch');
+  }
+  for (const key of ['project_id', 'repository_id', 'worktree_id', 'work_session_id']) {
+    if (expected.identity?.[key] != null && evidence[key] !== expected.identity[key]) {
+      contextReasons.push(`${key} mismatch`);
+    }
+  }
+  if (contextReasons.length) return { state: 'context-mismatch', reasons: contextReasons };
+
+  const staleReasons = [];
+  const unsigned = { ...evidence };
+  delete unsigned.envelope_id;
+  if (!evidence.envelope_id || canonicalSha256(unsigned) !== evidence.envelope_id) {
+    staleReasons.push('envelope_id invalid');
+  }
+  for (const key of ['branch', 'base_sha', 'head_sha', 'index_tree_sha', 'worktree_digest', 'dirty']) {
+    if (expected.snapshot?.[key] != null && evidence[key] !== expected.snapshot[key]) {
+      staleReasons.push(`${key} changed`);
+    }
+  }
+  for (const key of ['tasks_sha256', 'effective_spec_sha256', 'sensor_config_sha256']) {
+    if (expected[key] != null && evidence[key] !== expected[key]) staleReasons.push(`${key} changed`);
+  }
+  return staleReasons.length
+    ? { state: 'stale', reasons: staleReasons }
+    : { state: 'bound', reasons: [] };
+}

package/packages/vault/src/index.mjs

@@ -8,5 +8,6 @@ export * from './memory-handoff.mjs';
 export * from './memory-store.mjs';
 export * from './memory-scope.mjs';
 export * from './evidence-recall.mjs';
+export * from './evidence-envelope.mjs';
 export * from './validate-core.mjs';
 export * from './validate-memory.mjs';

package/packages/vault/src/memory-handoff.mjs

@@ -5,6 +5,12 @@ import { basename, join, relative } from 'node:path';
 
 import { sanitizeMemoryText } from './memory-schema.mjs';
 import { scopeForMemoryKey } from './memory-scope.mjs';
+import {
+  evaluateEvidenceBinding,
+  evidenceCheckoutBinding,
+  evidenceCheckoutBindingMatches,
+  evidenceSensors,
+} from './evidence-envelope.mjs';
 
 const SHARED_HANDOFF_FIELDS = Object.freeze([
   ['objective', 'objective.current'],
@@ -177,9 +183,33 @@ export function collectLifecycleEvidence(vaultBase, { changeSlug = '', summary =
         };
       }
       const sensorPath = join(archivedDir, 'evidencia.json');
-      const sensors = readJson(sensorPath);
-      if (Array.isArray(sensors) && sensors.length && sensors.every((item) => item?.status === 'green')) {
+      const sensorEnvelope = readJson(sensorPath);
+      const sensors = evidenceSensors(sensorEnvelope);
+      if (sensors.length && sensors.every((item) => item?.status === 'green')) {
         evidence.sensors = [...new Set(sensors.map((item) => String(item.id || '')).filter(Boolean))].sort();
+        evidence.sensors_path = vaultRel(vaultBase, sensorPath);
+        const assessed = evaluateEvidenceBinding(sensorEnvelope, { change_slug: slug });
+        evidence.sensors_binding = assessed.state;
+        if (sensorEnvelope?.schema_version === 2 && assessed.state === 'bound') {
+          const checkoutBinding = evidenceCheckoutBinding(sensorEnvelope);
+          const verification = readJson(join(archivedDir, 'verificacao.json'));
+          const crossBound = verification?.evidenceEnvelopeId === sensorEnvelope.envelope_id
+            && verdict?.evidenceEnvelopeId === sensorEnvelope.envelope_id
+            && evidenceCheckoutBindingMatches(verification?.evidenceBinding, checkoutBinding)
+            && evidenceCheckoutBindingMatches(verdict?.evidenceBinding, checkoutBinding);
+          if (!crossBound) {
+            evidence.sensors_binding = 'stale';
+            evidence.sensors_binding_reasons = ['archived verification/verdict binding mismatch'];
+          }
+        } else if (assessed.reasons.length) {
+          evidence.sensors_binding_reasons = assessed.reasons;
+        }
+        if (sensorEnvelope?.schema_version === 2) {
+          evidence.sensors_envelope_id = sensorEnvelope.envelope_id;
+          evidence.sensors_tasks_hash = sensorEnvelope.tasks_sha256;
+          evidence.sensors_repository_id = sensorEnvelope.repository_id;
+          evidence.sensors_worktree_id = sensorEnvelope.worktree_id;
+        }
       }
     }
   }
@@ -279,12 +309,23 @@ export function buildSessionMemoryEvents({
   if (Array.isArray(evidence.sensors) && evidence.sensors.length) {
     events.push(makeEvent(context, {
       memoryKey: 'quality.latest-sensors',
-      value: [...new Set(evidence.sensors.map(String))].sort(),
-      authority: 'verified',
-      evidence: evidence.sensors,
+      value: {
+        ids: [...new Set(evidence.sensors.map(String))].sort(),
+        evidence_state: evidence.sensors_binding || 'legacy-unbound',
+        ...(evidence.sensors_envelope_id ? { envelope_id: evidence.sensors_envelope_id } : {}),
+        ...(evidence.sensors_binding && !['bound', 'legacy-unbound'].includes(evidence.sensors_binding)
+          ? { recovery: 'reabra a change e rode wendkeep verify --deep + wk-verify' }
+          : {}),
+      },
+      authority: evidence.sensors_binding === 'bound' ? 'verified' : 'reported',
+      evidence: [evidence.sensors_path].filter(Boolean),
       scopeContext: {
         changeSlug: evidence.change?.slug || normalizedShared?.change_slug,
         tasksHash: evidence.sensors_tasks_hash || normalizedShared?.tasks_hash,
+        repositoryId: evidence.sensors_repository_id,
+        worktreeId: evidence.sensors_worktree_id,
+        evidenceEnvelopeId: evidence.sensors_envelope_id,
+        evidenceState: evidence.sensors_binding,
       },
     }));
   }

package/packages/vault/src/vault-path-safety.mjs

@@ -225,10 +225,20 @@ export function writeVaultFileSync(vaultBase, targetPath, content, encoding = 'u
 export function writeVaultFileAtomic(vaultBase, targetPath, content, encoding = 'utf8', {
   label = 'arquivo atômico do Vault',
   code = 'VAULT_PATH_UNSAFE',
+  scopeRoot = '',
+  beforeRename,
 } = {}) {
   const checked = assertVaultPathSafe(vaultBase, targetPath, {
     expectedType: 'file', label, code,
   });
+  if (scopeRoot) {
+    const scope = assertVaultPathSafe(vaultBase, scopeRoot, {
+      allowMissing: false, expectedType: 'directory', label: `escopo de ${label}`, code,
+    });
+    if (!containedBy(scope.target, checked.target)) {
+      throw unsafe(`${label} escapa do escopo autorizado: ${checked.target}`, code);
+    }
+  }
   assertVaultPathSafe(vaultBase, dirname(checked.target), {
     allowMissing: false, expectedType: 'directory', label: `ancestral de ${label}`, code,
   });
@@ -245,6 +255,7 @@ export function writeVaultFileAtomic(vaultBase, targetPath, content, encoding =
       allowMissing: false, expectedType: 'file', label: `temporário de ${label}`, code,
     });
     assertVaultPathSafe(vaultBase, checked.target, { expectedType: 'file', label, code });
+    if (typeof beforeRename === 'function') beforeRename({ temporary: tmp, target: checked.target });
     renameSync(tmp, checked.target);
     tmpCreated = false;
     assertVaultPathSafe(vaultBase, checked.target, {

package/schema/wendkeep.evidence-envelope-v2.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/rogersialves/wendkeep/schema/wendkeep.evidence-envelope-v2.schema.json",
+  "title": "WendKeep Evidence Envelope v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "project_id",
+    "repository_id",
+    "worktree_id",
+    "work_session_id",
+    "change_slug",
+    "branch",
+    "base_sha",
+    "head_sha",
+    "index_tree_sha",
+    "worktree_digest",
+    "dirty",
+    "tasks_sha256",
+    "effective_spec_sha256",
+    "sensor_config_sha256",
+    "wendkeep_version",
+    "platform",
+    "started_at",
+    "finished_at",
+    "sensors",
+    "envelope_id"
+  ],
+  "properties": {
+    "schema_version": { "const": 2 },
+    "project_id": { "type": "string", "minLength": 1 },
+    "repository_id": { "type": "string", "minLength": 1 },
+    "worktree_id": { "type": "string", "minLength": 1 },
+    "work_session_id": { "type": "string", "minLength": 1 },
+    "change_slug": { "type": "string", "minLength": 1 },
+    "branch": { "type": "string", "minLength": 1 },
+    "base_sha": { "$ref": "#/$defs/gitObject" },
+    "head_sha": { "$ref": "#/$defs/gitObject" },
+    "index_tree_sha": { "$ref": "#/$defs/gitObject" },
+    "worktree_digest": { "$ref": "#/$defs/sha256" },
+    "dirty": { "type": "boolean" },
+    "tasks_sha256": { "$ref": "#/$defs/sha256" },
+    "effective_spec_sha256": { "$ref": "#/$defs/sha256" },
+    "sensor_config_sha256": { "$ref": "#/$defs/sha256" },
+    "wendkeep_version": { "type": "string", "minLength": 1 },
+    "platform": { "type": "string", "minLength": 1 },
+    "started_at": { "type": "string", "format": "date-time" },
+    "finished_at": { "type": "string", "format": "date-time" },
+    "envelope_id": { "$ref": "#/$defs/sha256" },
+    "sensors": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/sensor" }
+    }
+  },
+  "$defs": {
+    "gitObject": { "type": "string", "pattern": "^[a-f0-9]{40,64}$" },
+    "sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "sensor": {
+      "type": "object",
+      "required": [
+        "id",
+        "status",
+        "severity",
+        "command",
+        "command_sha256",
+        "started_at",
+        "finished_at",
+        "duration_ms",
+        "exit_code",
+        "output_sha256",
+        "output_tail"
+      ],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["green", "red"] },
+        "severity": { "enum": ["critical", "warning"] },
+        "command": { "type": "string" },
+        "command_sha256": { "$ref": "#/$defs/sha256" },
+        "started_at": { "type": "string", "format": "date-time" },
+        "finished_at": { "type": "string", "format": "date-time" },
+        "duration_ms": { "type": "number", "minimum": 0 },
+        "exit_code": { "type": ["integer", "null"] },
+        "output_sha256": { "$ref": "#/$defs/sha256" },
+        "output_tail": { "type": "string", "maxLength": 2000 },
+        "note": { "type": "string", "maxLength": 2000 },
+        "survivors": { "type": "array" },
+        "ts": { "type": "string", "format": "date-time" }
+      }
+    }
+  }
+}