wendkeep 0.77.0 → 0.78.0

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" }
+      }
+    }
+  }
+}

package/src/change.mjs

@@ -19,13 +19,24 @@ import {
   isGuideCompactChange,
   setActiveChange,
 } from '../hooks/change-core.mjs';
-import { evaluateGate, requiredSensors } from '../hooks/sensors-core.mjs';
+import { evaluateGate, loadSensorsDetailed, requiredSensors } from '../hooks/sensors-core.mjs';
 import { buildEffectiveRequirementPackage, evaluateVerdict, formatOrphanReqs, tasksHashOf, parseSpecsList, parseDelta, parseRequirements, applyDelta, validateSpecImpact } from '../hooks/spec-core.mjs';
 import { getNextAdrNumber, readControl, readSessionRegistry, upsertSessionRegistry } from '../hooks/obsidian-common.mjs';
 import { getLocale } from '../hooks/locale.mjs';
 import { enqueueObserverDocumentChange } from './observer-sql-publish.mjs';
 import { readProjectForValidation } from '../packages/vault/src/validate-memory.mjs';
 import { resolveCommandActiveContext } from './active-context-runtime.mjs';
+import {
+  captureGitSnapshot,
+  resolveEvidenceIdentity,
+  sensorConfigSha256,
+} from './evidence-envelope.mjs';
+import {
+  evaluateEvidenceBinding,
+  evidenceCheckoutBinding,
+  evidenceCheckoutBindingMatches,
+  evidenceSensors,
+} from '../packages/vault/src/evidence-envelope.mjs';
 
 function observerMarkdownUnder(vaultBase, relativeRoot) {
   const output = [];
@@ -74,15 +85,15 @@ export function runChange(argv) {
   const VALUE_FLAGS = new Set(['--vault', '--change', '--project', '--session']);
   const slugArg = () => rest.find((a, i) => !a.startsWith('-') && !VALUE_FLAGS.has(rest[i - 1]));
   const projectRoot = resolve(opt(rest, '--project') || process.cwd());
+  const sessionId = opt(rest, '--session')
+    || process.env.CODEX_THREAD_ID
+    || process.env.CLAUDE_SESSION_ID
+    || '';
   let contextResolved = false;
   let resolvedContext = null;
   const context = () => {
     if (contextResolved) return resolvedContext;
     contextResolved = true;
-    const sessionId = opt(rest, '--session')
-      || process.env.CODEX_THREAD_ID
-      || process.env.CLAUDE_SESSION_ID
-      || '';
     try {
       resolvedContext = resolveCommandActiveContext({ vaultBase, projectRoot, sessionId });
       return resolvedContext;
@@ -196,19 +207,48 @@ export function runChange(argv) {
     }
     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`);
+    if (evidence) for (const e of evidenceSensors(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.flatMap((t) => t.reqs ?? []))];
     const effective = buildEffectiveRequirementPackage(vaultBase, dir, reqIds);
     if (effective.errors.length || effective.missing.length) {
       process.stdout.write(`spec efetiva: inválida (${[...effective.errors, ...effective.missing.map((id) => `req órfão ${id}`)].join('; ')})\n`);
     }
+    if (evidence) {
+      let expected = {
+        change_slug: slug,
+        tasks_sha256: tasksHashOf(tarefasMd),
+        effective_spec_sha256: `sha256:${effective.hash}`,
+      };
+      let unavailable = '';
+      try {
+        const ids = requiredSensors(tasks);
+        const loaded = loadSensorsDetailed(projectRoot);
+        expected = {
+          ...expected,
+          identity: resolveEvidenceIdentity({
+            vaultBase, projectRoot, changeSlug: slug, sessionId, context: context(),
+          }),
+          snapshot: captureGitSnapshot(projectRoot),
+          sensor_config_sha256: sensorConfigSha256(loaded.sensors, ids),
+        };
+      } catch (error) {
+        unavailable = error.code || error.message;
+      }
+      const binding = evaluateEvidenceBinding(evidence, expected);
+      process.stdout.write(`evidence-binding: ${binding.state}${binding.reasons.length ? ` (${binding.reasons.join('; ')})` : ''}${unavailable ? ` [current snapshot unavailable: ${unavailable}]` : ''}\n`);
+    }
     let verdict = null;
     try { verdict = JSON.parse(readFileSync(join(dir, 'verdict.json'), 'utf8')); } catch { /* sem verdict */ }
     if (!verdict) process.stdout.write(`verdict: ausente — rode \`wendkeep verify --deep\`${reqIds.length ? ' + wk-verify' : ' (verdict trivial automático)'}\n`);
     else if (!reqIds.length) process.stdout.write(`verdict: ${verdict.ok === true ? 'ok (trivial)' : 'não-ok — re-verifique'}\n`);
     else {
-      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,
+      });
       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 */ }
@@ -289,9 +329,34 @@ export function runChange(argv) {
       const effective = buildEffectiveRequirementPackage(vaultBase, dir, reqIds);
       if (effective.errors.length) return { ok: false, failing: [`spec efetiva inválida: ${effective.errors.join('; ')}`] };
       if (effective.missing.length) return { ok: false, failing: [formatOrphanReqs(effective.missing)] };
-      let evidence = [];
+      let evidence = null;
       try { evidence = JSON.parse(readFileSync(join(dir, 'evidencia.json'), 'utf8')); } catch { /* no evidence */ }
-      const s = evaluateGate(evidence, required);
+      const sensorEvidence = evidenceSensors(evidence);
+      if (required.length && (!evidence || evidence.schema_version !== 2)) {
+        return { ok: false, failing: ['evidência legacy-unbound não satisfaz autoridade v2 — rode `wendkeep verify` novamente'] };
+      }
+      if (evidence?.schema_version === 2) {
+        let currentBinding;
+        try {
+          const loaded = loadSensorsDetailed(projectRoot);
+          currentBinding = evaluateEvidenceBinding(evidence, {
+            change_slug: slug,
+            identity: resolveEvidenceIdentity({
+              vaultBase, projectRoot, changeSlug: slug, sessionId, context: selectedContext,
+            }),
+            snapshot: captureGitSnapshot(projectRoot),
+            tasks_sha256: tasksHashOf(tarefasMd),
+            effective_spec_sha256: `sha256:${effective.hash}`,
+            sensor_config_sha256: sensorConfigSha256(loaded.sensors, required),
+          });
+        } catch (error) {
+          return { ok: false, failing: [`binding atual indisponível (${error.code || error.message}) — recupere o contexto e rode \`wendkeep verify\` novamente`] };
+        }
+        if (currentBinding.state !== 'bound') {
+          return { ok: false, failing: [`evidência ${currentBinding.state} (${currentBinding.reasons.join('; ')}) — rode \`wendkeep verify\` novamente`] };
+        }
+      }
+      const s = evaluateGate(sensorEvidence, required);
       if (!s.ok) return s;
       // Verdict SEMPRE exigido (0.31.0) — a exigência universal vive AQUI no gate; a semântica
       // reqless→ok de evaluateVerdict (spec-core) não muda porque `verify --deep` e `change
@@ -310,6 +375,19 @@ export function runChange(argv) {
       }
       let verification = null;
       try { verification = JSON.parse(readFileSync(join(dir, 'verificacao.json'), 'utf8')); } catch { /* none */ }
+      const checkoutBinding = evidence?.schema_version === 2 ? evidenceCheckoutBinding(evidence) : null;
+      if (evidence?.schema_version === 2 && verification?.evidenceEnvelopeId !== evidence.envelope_id) {
+        return { ok: false, failing: ['pacote de verificação não está ligado ao envelope atual — rode `wendkeep verify --deep` novamente'] };
+      }
+      if (checkoutBinding && !evidenceCheckoutBindingMatches(verification?.evidenceBinding, checkoutBinding)) {
+        return { ok: false, failing: ['binding do pacote de verificação diverge do checkout provado — rode `wendkeep verify --deep` novamente'] };
+      }
+      if (evidence?.schema_version === 2 && verdict.evidenceEnvelopeId !== evidence.envelope_id) {
+        return { ok: false, failing: [`verdict não está ligado ao envelope atual — rode \`wendkeep verify --deep\`${reqIds.length ? ' + wk-verify' : ''}`] };
+      }
+      if (checkoutBinding && !evidenceCheckoutBindingMatches(verdict.evidenceBinding, checkoutBinding)) {
+        return { ok: false, failing: [`binding do verdict diverge do checkout provado — rode \`wendkeep verify --deep\`${reqIds.length ? ' + wk-verify' : ''}`] };
+      }
       if (verification?.effectiveSpecHash && verification.effectiveSpecHash !== effective.hash) {
         return { ok: false, failing: ['pacote de verificação stale (spec efetiva mudou) — rode `wendkeep verify --deep` novamente'] };
       }
@@ -317,7 +395,12 @@ export function runChange(argv) {
         return { ok: false, failing: ['verdict sem effectiveSpecHash — rode a skill wk-verify novamente'] };
       }
       if (reqIds.length) {
-        const v = evaluateVerdict(verdict, reqIds, { tasksHash: hash, effectiveSpecHash: effective.hash });
+        const v = evaluateVerdict(verdict, reqIds, {
+          tasksHash: hash,
+          effectiveSpecHash: effective.hash,
+          evidenceEnvelopeId: evidence?.schema_version === 2 ? evidence.envelope_id : undefined,
+          evidenceBinding: checkoutBinding || undefined,
+        });
         if (!v.ok) {
           if (v.stale) return { ok: false, failing: ['verdict stale (tarefas.md mudou depois da verificação) — re-verifique: `wendkeep verify --deep` + wk-verify'] };
           return { ok: false, failing: [`verdict incompleto: falta ${v.missing.join(', ')}`] };

package/src/evidence-envelope.mjs

@@ -0,0 +1,288 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { isUtf8 } from 'node:buffer';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readProjectForValidation } from '../packages/vault/src/validate-memory.mjs';
+import {
+  discoverWorktreeRepository,
+  readWorktreeRegistry,
+  worktreeIdentity,
+} from '../packages/vault/src/worktree-metadata.mjs';
+import {
+  canonicalSha256,
+  evaluateEvidenceBinding,
+  evidenceSensors,
+} from '../packages/vault/src/evidence-envelope.mjs';
+
+export { canonicalSha256, evaluateEvidenceBinding, evidenceSensors };
+
+const PACKAGE_VERSION = JSON.parse(readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'),
+  'utf8',
+)).version;
+
+export function sensorConfigSha256(sensors, ids) {
+  const selected = new Set(ids || []);
+  const canonical = (sensors || [])
+    .filter((sensor) => selected.has(sensor.id))
+    .map((sensor) => sensor)
+    .sort((left, right) => String(left.id || '').localeCompare(String(right.id || '')));
+  return canonicalSha256(canonical);
+}
+
+function normalizedPath(value) {
+  return String(value || '').replaceAll('\\', '/');
+}
+
+const BINARY_EXTENSIONS = new Set([
+  '.7z', '.a', '.avi', '.bin', '.bmp', '.class', '.dll', '.doc', '.docx', '.dylib', '.eot',
+  '.exe', '.gif', '.gz', '.ico', '.jar', '.jpeg', '.jpg', '.mov', '.mp3', '.mp4', '.o',
+  '.ogg', '.otf', '.pdf', '.png', '.so', '.tar', '.tif', '.tiff', '.ttf', '.wav', '.webm',
+  '.webp', '.woff', '.woff2', '.xls', '.xlsx', '.zip',
+]);
+
+function normalizedContent(content, binary = false) {
+  const bytes = Buffer.isBuffer(content) ? content : Buffer.from(content || '');
+  if (binary || bytes.includes(0) || !isUtf8(bytes)) return bytes;
+  return Buffer.from(bytes.toString('utf8').replace(/\r\n?/g, '\n'), 'utf8');
+}
+
+export function digestWorktreeEntries(entries) {
+  const canonical = (entries || []).map((entry) => ({
+    layer: String(entry.layer || ''),
+    status: String(entry.status || ''),
+    path: normalizedPath(entry.path),
+    ...(entry.oldPath ? { old_path: normalizedPath(entry.oldPath) } : {}),
+    content_mode: entry.binary ? 'binary' : 'text',
+    content_sha256: entry.content == null ? null : canonicalSha256(normalizedContent(entry.content, entry.binary)),
+  })).sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+  return canonicalSha256(canonical);
+}
+
+function gitResult(projectRoot, args, { spawn = spawnSync, allowFailure = false } = {}) {
+  const result = spawn('git', args, {
+    cwd: projectRoot,
+    encoding: null,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+  if (!allowFailure && (result.error || result.status !== 0)) {
+    const detail = Buffer.from(result.stderr || '').toString('utf8').trim();
+    const error = new Error(`git ${args.join(' ')} falhou${detail ? `: ${detail}` : ''}`);
+    error.code = 'WENDKEEP_EVIDENCE_GIT_FAILED';
+    throw error;
+  }
+  return result;
+}
+
+function gitText(projectRoot, args, options) {
+  const result = gitResult(projectRoot, args, options);
+  if (result.status !== 0) return '';
+  return Buffer.from(result.stdout || '').toString('utf8').trim();
+}
+
+function gitBuffer(projectRoot, args, options) {
+  const result = gitResult(projectRoot, args, options);
+  return result.status === 0 ? Buffer.from(result.stdout || '') : Buffer.alloc(0);
+}
+
+function parseNameStatus(buffer, layer) {
+  const tokens = buffer.toString('utf8').split('\0');
+  if (tokens.at(-1) === '') tokens.pop();
+  const entries = [];
+  for (let index = 0; index < tokens.length;) {
+    const status = tokens[index++];
+    const renamed = /^[RC]/.test(status);
+    const oldPath = renamed ? tokens[index++] : '';
+    const path = tokens[index++];
+    if (!path) continue;
+    entries.push({ layer, status, path, ...(oldPath ? { oldPath } : {}) });
+  }
+  return entries;
+}
+
+function binaryAttributes(projectRoot, paths, options) {
+  const unique = [...new Set(paths.filter(Boolean))];
+  if (!unique.length) return new Map();
+  const tokens = gitBuffer(projectRoot, ['check-attr', '-z', 'binary', 'text', '--', ...unique], {
+    ...options, allowFailure: true,
+  }).toString('utf8').split('\0');
+  if (tokens.at(-1) === '') tokens.pop();
+  const attributes = new Map();
+  for (let index = 0; index + 2 < tokens.length; index += 3) {
+    const [path, attribute, value] = tokens.slice(index, index + 3);
+    const entry = attributes.get(path) || {};
+    entry[attribute] = value;
+    attributes.set(path, entry);
+  }
+  return attributes;
+}
+
+function pathIsBinary(path, attributes) {
+  const values = attributes.get(path) || {};
+  if (values.binary === 'set' || values.text === 'unset') return true;
+  if (values.binary === 'unset' || values.text === 'set' || values.text === 'auto') return false;
+  const normalized = normalizedPath(path).toLowerCase();
+  const dot = normalized.lastIndexOf('.');
+  return dot >= 0 && BINARY_EXTENSIONS.has(normalized.slice(dot));
+}
+
+function readWorkingPath(projectRoot, path) {
+  const root = resolve(projectRoot);
+  const absolute = resolve(root, ...normalizedPath(path).split('/'));
+  const scoped = relative(root, absolute);
+  if (scoped === '..' || scoped.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(scoped)) {
+    return null;
+  }
+  try {
+    if (!existsSync(absolute) || !statSync(absolute).isFile()) return null;
+    return readFileSync(absolute);
+  } catch {
+    return null;
+  }
+}
+
+function changedEntries(projectRoot, options) {
+  const staged = parseNameStatus(gitBuffer(projectRoot, [
+    'diff', '--cached', '--name-status', '-z', '--find-renames', '--no-ext-diff',
+  ], options), 'index');
+  const unstaged = parseNameStatus(gitBuffer(projectRoot, [
+    'diff', '--name-status', '-z', '--find-renames', '--no-ext-diff',
+  ], options), 'worktree');
+  const untracked = gitBuffer(projectRoot, [
+    'ls-files', '--others', '--exclude-standard', '-z',
+  ], options).toString('utf8').split('\0').filter(Boolean).map((path) => ({
+    layer: 'untracked', status: '?', path,
+  }));
+  const attributes = binaryAttributes(projectRoot, [
+    ...staged.map((entry) => entry.path),
+    ...unstaged.map((entry) => entry.path),
+    ...untracked.map((entry) => entry.path),
+  ], options);
+
+  for (const entry of staged) {
+    entry.binary = pathIsBinary(entry.path, attributes);
+    entry.content = /^D/.test(entry.status)
+      ? null
+      : gitBuffer(projectRoot, ['show', `:${entry.path}`], { ...options, allowFailure: true });
+  }
+  for (const entry of [...unstaged, ...untracked]) {
+    entry.binary = pathIsBinary(entry.path, attributes);
+    entry.content = /^D/.test(entry.status) ? null : readWorkingPath(projectRoot, entry.path);
+  }
+  return [...staged, ...unstaged, ...untracked];
+}
+
+function resolveBaseSha(projectRoot, headSha, options) {
+  const upstream = gitText(projectRoot, ['rev-parse', '--verify', '@{upstream}'], {
+    ...options, allowFailure: true,
+  });
+  let candidate = upstream;
+  if (!candidate) {
+    candidate = gitText(projectRoot, ['rev-parse', '--verify', 'refs/heads/main'], {
+      ...options, allowFailure: true,
+    });
+  }
+  if (!candidate) return headSha;
+  return gitText(projectRoot, ['merge-base', headSha, candidate], {
+    ...options, allowFailure: true,
+  }) || headSha;
+}
+
+export function captureGitSnapshot(projectRoot, { spawn = spawnSync } = {}) {
+  const options = { spawn };
+  const headSha = gitText(projectRoot, ['rev-parse', 'HEAD'], options);
+  const branch = gitText(projectRoot, ['symbolic-ref', '--short', '-q', 'HEAD'], {
+    ...options, allowFailure: true,
+  }) || 'HEAD';
+  const indexTreeSha = gitText(projectRoot, ['write-tree'], options);
+  const entries = changedEntries(projectRoot, options);
+  return {
+    branch,
+    base_sha: resolveBaseSha(projectRoot, headSha, options),
+    head_sha: headSha,
+    index_tree_sha: indexTreeSha,
+    worktree_digest: digestWorktreeEntries(entries),
+    dirty: entries.length > 0,
+  };
+}
+
+export function resolveEvidenceIdentity({
+  vaultBase,
+  projectRoot,
+  changeSlug,
+  sessionId = '',
+  context = null,
+  spawn = spawnSync,
+} = {}) {
+  const project = readProjectForValidation(vaultBase);
+  const repository = discoverWorktreeRepository({ startDir: projectRoot, spawn });
+  const { registry } = readWorktreeRegistry(repository);
+  if (registry && project.ok && registry.projectId !== project.projectId) {
+    const error = new Error('PROJECT.json e registry de worktrees pertencem a projetos diferentes');
+    error.code = 'WENDKEEP_EVIDENCE_IDENTITY_MISMATCH';
+    throw error;
+  }
+  const repositoryId = context?.repositoryId
+    || registry?.repositoryId
+    || canonicalSha256({ git_common_dir: normalizedPath(repository.commonDir).toLowerCase() });
+  const projectId = context?.projectId
+    || (project.ok ? project.projectId : canonicalSha256({ repository_id: repositoryId }));
+  const worktreeId = context?.worktreeId || worktreeIdentity(repositoryId, repository.gitDir);
+  const requestedSession = String(sessionId || '').trim();
+  const workSessionId = context?.workSessionId
+    || requestedSession
+    || canonicalSha256({ project_id: projectId, worktree_id: worktreeId, change_slug: changeSlug });
+  return {
+    project_id: projectId,
+    repository_id: repositoryId,
+    worktree_id: worktreeId,
+    work_session_id: workSessionId,
+  };
+}
+
+export function assertStableHead(startSnapshot, finishSnapshot) {
+  if (startSnapshot?.head_sha !== finishSnapshot?.head_sha) {
+    const error = new Error(
+      `HEAD mudou durante verify (${startSnapshot?.head_sha || 'ausente'} -> ${finishSnapshot?.head_sha || 'ausente'}); rode novamente no commit estável`,
+    );
+    error.code = 'WENDKEEP_EVIDENCE_HEAD_CHANGED';
+    throw error;
+  }
+}
+
+export function buildEvidenceEnvelope({
+  identity,
+  changeSlug,
+  snapshot,
+  tasksSha256,
+  effectiveSpecSha256,
+  sensorConfigSha256: configSha256,
+  sensors,
+  startedAt,
+  finishedAt,
+  version = PACKAGE_VERSION,
+  runtimePlatform = `${process.platform}-${process.arch}`,
+} = {}) {
+  const envelope = {
+    schema_version: 2,
+    ...identity,
+    change_slug: changeSlug,
+    branch: snapshot.branch,
+    base_sha: snapshot.base_sha,
+    head_sha: snapshot.head_sha,
+    index_tree_sha: snapshot.index_tree_sha,
+    worktree_digest: snapshot.worktree_digest,
+    dirty: snapshot.dirty,
+    tasks_sha256: tasksSha256,
+    effective_spec_sha256: effectiveSpecSha256,
+    sensor_config_sha256: configSha256,
+    wendkeep_version: version,
+    platform: runtimePlatform,
+    started_at: startedAt,
+    finished_at: finishedAt,
+    sensors,
+  };
+  return { ...envelope, envelope_id: canonicalSha256(envelope) };
+}