wendkeep 0.85.1 → 0.87.0

package/src/git-commit-hooks.mjs

@@ -0,0 +1,112 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const GIT_COMMIT_HOOKS = ['prepare-commit-msg', 'commit-msg'];
+export const GIT_COMMIT_HOOKS_PATH = '.githooks';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const packagedHooks = join(packageRoot, '.githooks');
+
+function git(projectRoot, args, { allowFailure = false } = {}) {
+  const result = spawnSync('git', args, {
+    cwd: projectRoot,
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  if (!allowFailure && result.status !== 0) {
+    const error = new Error((result.stderr || `git ${args.join(' ')} failed`).trim());
+    error.code = 'WENDKEEP_COMMIT_GIT_FAILED';
+    throw error;
+  }
+  return result;
+}
+
+function hookState(projectRoot, name) {
+  const source = join(packagedHooks, name);
+  const target = join(projectRoot, GIT_COMMIT_HOOKS_PATH, name);
+  if (!existsSync(target)) return { name, source, target, state: 'missing' };
+  return {
+    name,
+    source,
+    target,
+    state: readFileSync(target).equals(readFileSync(source)) ? 'current' : 'drift',
+  };
+}
+
+export function inspectGitCommitHooks({ projectRoot = process.cwd() } = {}) {
+  const root = resolve(projectRoot);
+  const repository = git(root, ['rev-parse', '--show-toplevel'], { allowFailure: true });
+  if (repository.status !== 0) {
+    return { status: 'unavailable', configured: false, issues: ['not a Git repository'], repair: '' };
+  }
+  const configured = git(root, ['config', '--local', '--get', 'core.hooksPath'], { allowFailure: true });
+  const configuredPath = configured.status === 0 ? configured.stdout.trim().replaceAll('\\', '/') : '';
+  if (!configuredPath) {
+    return { status: 'disabled', configured: false, issues: [], repair: 'wendkeep init --git-commit-hooks --yes' };
+  }
+  if (!['.githooks', './.githooks'].includes(configuredPath)) {
+    return {
+      status: 'drift',
+      configured: true,
+      configuredPath,
+      issues: [`core.hooksPath points to ${configuredPath}, not .githooks`],
+      repair: 'wendkeep init --git-commit-hooks --force --yes',
+    };
+  }
+  const states = GIT_COMMIT_HOOKS.map((name) => hookState(root, name));
+  const issues = states.filter((item) => item.state !== 'current').map((item) => (
+    item.state === 'missing'
+      ? `${item.name}: missing`
+      : `${item.name}: content differs from the installed WendKeep version`
+  ));
+  return {
+    status: issues.length ? (states.some((item) => item.state === 'missing') ? 'missing' : 'drift') : 'healthy',
+    configured: true,
+    configuredPath,
+    issues,
+    repair: issues.length ? 'wendkeep init --git-commit-hooks --force --yes' : '',
+  };
+}
+
+export function installGitCommitHooks({ projectRoot = process.cwd(), force = false } = {}) {
+  const root = resolve(projectRoot);
+  git(root, ['rev-parse', '--show-toplevel']);
+  const configured = git(root, ['config', '--local', '--get', 'core.hooksPath'], { allowFailure: true });
+  const configuredPath = configured.status === 0 ? configured.stdout.trim().replaceAll('\\', '/') : '';
+  if (configuredPath && !['.githooks', './.githooks'].includes(configuredPath) && !force) {
+    return {
+      status: 'conflict',
+      conflicts: ['core.hooksPath'],
+      configuredPath,
+      repair: 'wendkeep init --git-commit-hooks --force --yes',
+    };
+  }
+  const states = GIT_COMMIT_HOOKS.map((name) => hookState(root, name));
+  const conflicts = states.filter((item) => item.state === 'drift').map((item) => item.name);
+  if (conflicts.length && !force) {
+    return { status: 'conflict', conflicts, repair: 'wendkeep init --git-commit-hooks --force --yes' };
+  }
+  mkdirSync(join(root, GIT_COMMIT_HOOKS_PATH), { recursive: true });
+  let changed = false;
+  for (const item of states) {
+    if (item.state === 'current') continue;
+    if (item.state === 'drift' && force && !existsSync(`${item.target}.bak`)) {
+      copyFileSync(item.target, `${item.target}.bak`);
+    }
+    copyFileSync(item.source, item.target);
+    try { chmodSync(item.target, 0o755); } catch { /* Git for Windows uses its executable shim. */ }
+    changed = true;
+  }
+  if (configured.status !== 0 || configured.stdout.trim().replaceAll('\\', '/') !== GIT_COMMIT_HOOKS_PATH) {
+    git(root, ['config', '--local', 'core.hooksPath', GIT_COMMIT_HOOKS_PATH]);
+    changed = true;
+  }
+  return {
+    status: changed ? 'installed' : 'unchanged',
+    conflicts: [],
+    hooks: GIT_COMMIT_HOOKS,
+    path: join(root, GIT_COMMIT_HOOKS_PATH),
+  };
+}

package/src/init.mjs

@@ -41,6 +41,7 @@ import { adoptSpecsState, ensureSpecsReadme, SPECS_STATE_FILE } from '../hooks/s
 import { bindProjectVault, readProjectBinding } from './project-vault.mjs';
 import { seedMemoryV2 } from './memory.mjs';
 import { installVscodeWorktreeTasks } from './worktree.mjs';
+import { installGitCommitHooks } from './git-commit-hooks.mjs';
 import {
   DEFAULT_OPERATING_PROFILE,
   normalizeOperatingProfile,
@@ -69,6 +70,7 @@ function parseArgs(argv) {
     else if (a === '--no-companions') args.noCompanions = true;
     else if (a === '--no-colors') args.noColors = true;
     else if (a === '--vscode-worktree-tasks') args.vscodeWorktreeTasks = true;
+    else if (a === '--git-commit-hooks') args.gitCommitHooks = true;
     else if (a === '--dotcontext-mcp') args.dotcontextMcp = argv[++i];
     else if (a.startsWith('--dotcontext-mcp=')) args.dotcontextMcp = a.slice(17);
     else if (a === '--dotcontext-hooks') args.dotcontextHooks = argv[++i];
@@ -639,6 +641,17 @@ export async function runInit(argv) {
   }
   log(M.codexTrust);
 
+  // Git commit policy is opt-in because this is the only init surface that writes
+  // repository-local Git configuration. Existing custom hooks are never overwritten silently.
+  if (args.gitCommitHooks) {
+    const hooks = installGitCommitHooks({ projectRoot: projectPath, force: args.force });
+    if (hooks.status === 'conflict') {
+      log(`  [!] Git commit hooks preserved (${hooks.conflicts.join(', ')}); review and rerun ${hooks.repair}`);
+    } else {
+      log(`  Git commit hooks: ${hooks.status} (${hooks.path})`);
+    }
+  }
+
   // 3. .mcp.json --------------------------------------------------------------
   // Written when the native WendKeep MCP is wanted OR a selected companion ships an MCP server.
   const companionMcp = companionMcpPatch(companions, skipMcp);

package/src/memory-scale-health.mjs

@@ -0,0 +1,210 @@
+import {
+  readMemoryLedgerGeneration,
+  readMemoryProjectionSnapshot,
+  readMemoryRotationJournal,
+  readMemoryRotationReceipts,
+  readMemorySegmentManifest,
+} from '../hooks/memory-store.mjs';
+import {
+  quoteCommandArgument,
+  WENDKEEP_COMMAND,
+} from '../hooks/obsidian-common.mjs';
+
+export const MEMORY_SCALE_HEALTH_SCHEMA_VERSION = 1;
+
+function safeReason(value, fallback = '') {
+  const text = String(value || fallback).trim();
+  return text
+    ? text.replace(/[^A-Za-z0-9._:-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 120)
+    : null;
+}
+
+function numberMetric(value) {
+  const number = Number(value || 0);
+  return Number.isSafeInteger(number) && number >= 0 ? number : 0;
+}
+
+export function emptyMemoryScaleMetrics() {
+  return {
+    scaleSchemaVersion: MEMORY_SCALE_HEALTH_SCHEMA_VERSION,
+    scaleStatus: 'unknown',
+    scaleErrorCode: null,
+    snapshotStatus: 'unknown',
+    snapshotReason: null,
+    snapshotEvents: 0,
+    snapshotLedgerBytes: 0,
+    snapshotTailEvents: 0,
+    snapshotTailBytes: 0,
+    segmentStatus: 'unknown',
+    segmentCount: 0,
+    segmentCoveredEvents: 0,
+    segmentCoveredBytes: 0,
+    segmentPendingEvents: 0,
+    generationStatus: 'unknown',
+    generation: 0,
+    generationSourceEvents: 0,
+    generationActiveTailEvents: 0,
+    generationRotatedAt: null,
+    rotationJournal: 'unknown',
+    rotationRecoveryRequired: false,
+    rotationReceiptsStatus: 'unknown',
+    rotationReceipts: 0,
+    rotationReceiptCheckpoint: 'unknown',
+  };
+}
+
+function inspectSnapshot(vaultBase, metrics) {
+  try {
+    const snapshot = readMemoryProjectionSnapshot(vaultBase);
+    const tailStatus = snapshot.status === 'ok' ? snapshot.tail?.status : null;
+    metrics.snapshotStatus = snapshot.status === 'ok' && tailStatus !== 'ok'
+      ? 'invalid'
+      : snapshot.status;
+    metrics.snapshotReason = safeReason(
+      snapshot.reason || snapshot.tail?.reason,
+      metrics.snapshotStatus === 'invalid' ? 'snapshot-tail-unavailable' : '',
+    );
+    if (snapshot.status === 'ok') {
+      metrics.snapshotEvents = numberMetric(snapshot.snapshot?.event_count);
+      metrics.snapshotLedgerBytes = numberMetric(snapshot.snapshot?.ledger_bytes);
+      metrics.snapshotTailEvents = Array.isArray(snapshot.tail?.events)
+        ? snapshot.tail.events.length
+        : 0;
+      metrics.snapshotTailBytes = numberMetric(snapshot.tail?.bytes);
+    }
+  } catch (error) {
+    if (error?.code === 'VAULT_PATH_UNSAFE') throw error;
+    metrics.snapshotStatus = 'invalid';
+    metrics.snapshotReason = safeReason(error?.code, 'snapshot-read-failed');
+  }
+}
+
+function inspectSegments(vaultBase, ledgerEvents, metrics) {
+  try {
+    const manifest = readMemorySegmentManifest(vaultBase);
+    metrics.segmentStatus = manifest.status;
+    if (manifest.status === 'ok') {
+      metrics.segmentCount = numberMetric(manifest.manifest?.segment_count);
+      metrics.segmentCoveredEvents = numberMetric(manifest.manifest?.covered_event_count);
+      metrics.segmentCoveredBytes = numberMetric(manifest.manifest?.covered_bytes);
+    }
+    metrics.segmentPendingEvents = Math.max(
+      0,
+      numberMetric(ledgerEvents) - metrics.segmentCoveredEvents,
+    );
+  } catch (error) {
+    if (error?.code === 'VAULT_PATH_UNSAFE') throw error;
+    metrics.segmentStatus = 'invalid';
+    metrics.scaleErrorCode ||= safeReason(error?.code, 'segment-manifest-read-failed');
+  }
+}
+
+function inspectRotation(vaultBase, ledgerEvents, metrics) {
+  try {
+    const generation = readMemoryLedgerGeneration(vaultBase);
+    metrics.generationStatus = generation.status;
+    if (generation.status === 'ok') {
+      metrics.generation = numberMetric(generation.state?.generation);
+      metrics.generationSourceEvents = numberMetric(generation.state?.source_event_count);
+      metrics.generationActiveTailEvents = Math.max(
+        0,
+        numberMetric(ledgerEvents) - metrics.generationSourceEvents,
+      );
+      metrics.generationRotatedAt = String(generation.state?.rotated_at || '') || null;
+    }
+  } catch (error) {
+    if (error?.code === 'VAULT_PATH_UNSAFE') throw error;
+    metrics.generationStatus = 'invalid';
+    metrics.scaleErrorCode ||= safeReason(error?.code, 'generation-read-failed');
+  }
+
+  try {
+    const journal = readMemoryRotationJournal(vaultBase);
+    metrics.rotationJournal = journal.status === 'ok'
+      ? String(journal.journal?.stage || 'invalid')
+      : journal.status;
+    metrics.rotationRecoveryRequired = journal.status !== 'missing';
+  } catch (error) {
+    if (error?.code === 'VAULT_PATH_UNSAFE') throw error;
+    metrics.rotationJournal = 'invalid';
+    metrics.rotationRecoveryRequired = true;
+    metrics.scaleErrorCode ||= safeReason(error?.code, 'rotation-journal-read-failed');
+  }
+
+  try {
+    const receipts = readMemoryRotationReceipts(vaultBase);
+    metrics.rotationReceiptsStatus = receipts.status;
+    metrics.rotationReceipts = Array.isArray(receipts.receipts)
+      ? receipts.receipts.length
+      : 0;
+    metrics.rotationReceiptCheckpoint = String(receipts.checkpointStatus || 'unknown');
+  } catch (error) {
+    if (error?.code === 'VAULT_PATH_UNSAFE') throw error;
+    metrics.rotationReceiptsStatus = 'invalid';
+    metrics.rotationReceiptCheckpoint = 'invalid';
+    metrics.scaleErrorCode ||= safeReason(error?.code, 'rotation-receipts-read-failed');
+  }
+}
+
+function deriveScaleStatus(metrics) {
+  const invalid = [
+    metrics.snapshotStatus,
+    metrics.segmentStatus,
+    metrics.generationStatus,
+    metrics.rotationJournal,
+    metrics.rotationReceiptsStatus,
+    metrics.rotationReceiptCheckpoint,
+  ].some((status) => ['invalid', 'corrupt', 'blocked'].includes(status));
+  if (invalid || metrics.scaleErrorCode) return 'degraded';
+  if (metrics.rotationRecoveryRequired) return 'warning';
+  return 'healthy';
+}
+
+export function inspectMemoryScaleHealth(vaultBase, { ledgerEvents = 0 } = {}) {
+  const metrics = emptyMemoryScaleMetrics();
+  inspectSnapshot(vaultBase, metrics);
+  inspectSegments(vaultBase, ledgerEvents, metrics);
+  inspectRotation(vaultBase, ledgerEvents, metrics);
+  metrics.scaleStatus = deriveScaleStatus(metrics);
+  return metrics;
+}
+
+function statusCommand(vaultBase) {
+  return `${WENDKEEP_COMMAND} memory status --gate --vault ${quoteCommandArgument(vaultBase)}`;
+}
+
+export function augmentVaultHealthWithMemoryScale(result, vaultBase) {
+  const memory = result?.metrics?.memory;
+  if (!memory || ['legacy', 'blocked'].includes(result.memoryStatus)) return result;
+
+  try {
+    const scale = inspectMemoryScaleHealth(vaultBase, {
+      ledgerEvents: memory.ledgerEvents,
+    });
+    return {
+      ...result,
+      metrics: {
+        ...result.metrics,
+        memory: { ...memory, ...scale },
+      },
+    };
+  } catch (error) {
+    const code = safeReason(error?.code, 'memory-scale-boundary-unsafe');
+    const failure = `Memória: Artefatos de escala da memória estão inseguros ou ilegíveis (${code}). Inspecione com: ${statusCommand(vaultBase)}.`;
+    return {
+      ...result,
+      ok: false,
+      memoryStatus: 'blocked',
+      failures: [...(result.failures || []), failure],
+      metrics: {
+        ...result.metrics,
+        memory: {
+          ...memory,
+          ...emptyMemoryScaleMetrics(),
+          scaleStatus: 'blocked',
+          scaleErrorCode: code,
+        },
+      },
+    };
+  }
+}

package/src/observer-snapshot.mjs

@@ -5,6 +5,8 @@ import { allChangesState } from '../hooks/change-core.mjs';
 import { readControl, readSessionRegistry } from '../hooks/obsidian-common.mjs';
 import { runVaultHealth } from '../hooks/vault-health.mjs';
 import { readProjectForValidation } from '../packages/vault/src/validate-memory.mjs';
+import { inspectEvidenceSearchHealth } from './evidence-search-health.mjs';
+import { augmentVaultHealthWithMemoryScale } from './memory-scale-health.mjs';
 import { inspectSyncOutbox, readLocalSyncState } from './sync-outbox.mjs';
 
 export const OBSERVER_SCHEMA_VERSION = 1;
@@ -27,6 +29,11 @@ function safeText(value, max = MAX_TEXT) {
     .slice(0, max);
 }
 
+function safeCount(value) {
+  const number = Number(value || 0);
+  return Number.isSafeInteger(number) && number >= 0 ? number : 0;
+}
+
 function isoNow(value) {
   const date = value instanceof Date ? value : new Date(value ?? Date.now());
   if (Number.isNaN(date.getTime())) throw fail('captured_at inválido.');
@@ -65,9 +72,86 @@ function activeSessionSummary(vaultBase, control, registry) {
   };
 }
 
+function recallSearchSummary(metrics) {
+  return {
+    schema_version: 1,
+    status: safeText(metrics?.status || 'unknown', 32),
+    ...(metrics?.errorCode ? { error_code: safeText(metrics.errorCode, 120) } : {}),
+    authority: {
+      status: safeText(metrics?.authorityStatus || 'unknown', 32),
+      bytes: safeCount(metrics?.authorityBytes),
+    },
+    incremental: {
+      status: safeText(metrics?.incrementalStateStatus || 'unknown', 32),
+      bytes: safeCount(metrics?.incrementalStateBytes),
+      documents: safeCount(metrics?.documentCount),
+    },
+    search: {
+      status: safeText(metrics?.searchStateStatus || 'unknown', 32),
+      bytes: safeCount(metrics?.searchStateBytes),
+      chunks: safeCount(metrics?.rowCount),
+      source_index_current: metrics?.sourceIndexCurrent === true,
+      source_state_current: metrics?.sourceStateCurrent === true,
+    },
+    lexical: {
+      status: safeText(metrics?.lexicalStatus || 'unknown', 32),
+      bytes: safeCount(metrics?.lexicalBytes),
+    },
+    sqlite: {
+      status: safeText(metrics?.sqliteStatus || 'unknown', 32),
+      bytes: safeCount(metrics?.sqliteBytes),
+      capability: metrics?.sqliteCapability === true,
+    },
+    backend: safeText(metrics?.backend || 'unavailable', 40),
+  };
+}
+
+function memoryScaleSummary(memory = {}) {
+  if (memory.scaleSchemaVersion !== 1) return null;
+  return {
+    schema_version: 1,
+    status: safeText(memory.scaleStatus || 'unknown', 32),
+    ...(memory.scaleErrorCode ? { error_code: safeText(memory.scaleErrorCode, 120) } : {}),
+    snapshot: {
+      status: safeText(memory.snapshotStatus || 'unknown', 32),
+      ...(memory.snapshotReason ? { reason: safeText(memory.snapshotReason, 120) } : {}),
+      event_count: safeCount(memory.snapshotEvents),
+      ledger_bytes: safeCount(memory.snapshotLedgerBytes),
+      tail_events: safeCount(memory.snapshotTailEvents),
+      tail_bytes: safeCount(memory.snapshotTailBytes),
+    },
+    segments: {
+      status: safeText(memory.segmentStatus || 'unknown', 32),
+      count: safeCount(memory.segmentCount),
+      covered_events: safeCount(memory.segmentCoveredEvents),
+      covered_bytes: safeCount(memory.segmentCoveredBytes),
+      pending_events: safeCount(memory.segmentPendingEvents),
+    },
+    generation: {
+      status: safeText(memory.generationStatus || 'unknown', 32),
+      number: safeCount(memory.generation),
+      source_events: safeCount(memory.generationSourceEvents),
+      active_tail_events: safeCount(memory.generationActiveTailEvents),
+      rotated_at: safeText(memory.generationRotatedAt || '', 40),
+    },
+    rotation: {
+      journal: safeText(memory.rotationJournal || 'unknown', 32),
+      recovery_required: memory.rotationRecoveryRequired === true,
+      receipts_status: safeText(memory.rotationReceiptsStatus || 'unknown', 32),
+      receipts: safeCount(memory.rotationReceipts),
+      receipt_checkpoint: safeText(memory.rotationReceiptCheckpoint || 'unknown', 32),
+    },
+  };
+}
+
 function healthSummary(vaultBase) {
   try {
-    const health = runVaultHealth({ vaultBase });
+    const health = augmentVaultHealthWithMemoryScale(
+      runVaultHealth({ vaultBase }),
+      vaultBase,
+    );
+    const recall = recallSearchSummary(inspectEvidenceSearchHealth(vaultBase));
+    const memoryScale = memoryScaleSummary(health.metrics?.memory);
     return {
       ok: health.ok === true,
       status: safeText(health.memoryStatus || (health.ok ? 'healthy' : 'degraded'), 40),
@@ -75,6 +159,8 @@ function healthSummary(vaultBase) {
       warning_count: Array.isArray(health.warnings) ? health.warnings.length : 0,
       registry_sessions: Number(health.metrics?.registrySessions || 0),
       derived_notes: Number(health.metrics?.derivedNotes || 0),
+      recall_search: recall,
+      ...(memoryScale ? { memory_scale: memoryScale } : {}),
     };
   } catch {
     return {

package/src/skills-seed.mjs

@@ -524,6 +524,83 @@ the author — even if you wrote the code, enter as if you'd never seen it. Fres
 - \`verdict-template.json\` — the exact shape of the \`verdict.json\` to write.
 `;
 
+const WK_COMMIT = `# Commit universal baseado em evidências
+
+Use para preparar commits de implementação que precisem do contrato WendKeep. O gerador recebe
+somente referências sanitizadas e o diff staged resumido; nunca leia, copie ou publique o Vault,
+\`.brain\`, registros de sessão, tokens ou segredos na mensagem.
+
+## Fluxo
+
+1. Confirme que autoridade e referências de evidência estão atuais. O draft **não aceita** texto
+   caller-controlled em \`tasks\` ou \`tests\`: o runtime deriva tasks de Task Contracts concluídos;
+   Tests vêm somente de \`[sensor:<id>]\` executado pelo coletor.
+   Sensors do Envelope devem corresponder exatamente à reexecução; só a reexecução gera Tests.
+   \`[phase:verify]\` sozinho nunca prova execução, e o range reexecuta o sensor no SHA exato,
+   rederiva authority/artefatos/task/spec/Scope/config no SHA. Envelope/Verdict/receipt/TDD ficam
+   somente na validação local e são omitidos da Evidence remota; nunca publique seus IDs locais.
+   Tasks com \`[req:]\` exigem \`spec\` versionada e sanitizada. Use
+   \`authority.kind: adr\` sempre que existe uma change ou ADR causal. Somente sob perfil observado
+   \`OFF\`, sem context/change/lease ou ADR causal real, use \`authority.kind: native\`, com
+   \`Issue #NNN\` e design versionado sob \`docs/superpowers/specs/\` ou \`plans/\`.
+2. Crie um JSON conforme \`schema/commit-message-v1.schema.json\`. Não declare \`fresh\`,
+   \`verified\`, \`tasks\` ou \`tests\`: o runtime rederiva prova, digest SHA-256 do artefato,
+   binding completo de identidade/snapshot/tasks/spec/config e Scope do diff staged. Expected
+   ausente, envelope vazio, task pendente,
+   verdict sem selos/cobertura/independência ou
+   receipt sem chain/observation válidos falham fechados. \`Co-Authored-By\` é omitido
+   enquanto não houver identidade registrada confiável.
+3. Com os arquivos já staged, rode
+   \`wendkeep commit context --input <arquivo.json>\`. O CLI calcula o hash do index e grava o
+   contexto sanitizado dentro de \`.git\`, fora do working tree.
+4. Rode \`git commit\` normalmente. Os hooks opt-in revalidam contexto, hash, privacidade e
+   trivialidade antes de consumir o contexto. Instale-os
+   explicitamente com \`wendkeep init --git-commit-hooks --yes\`.
+5. Para diagnóstico, rode \`wendkeep doctor\`; para limpar contexto abandonado, use
+   \`wendkeep commit context --clear\`.
+
+Não use \`--no-verify\` para implementação. Amend, merge e squash preservam a mensagem existente e
+não recebem conteúdo inventado. A validação remota do PR continua sendo a defesa contra bypass.
+`;
+
+const WK_COMMIT_EN = `# Evidence-based universal commit
+
+Use this skill to prepare implementation commits governed by the WendKeep message contract. The
+generator receives sanitized references and a staged-diff summary only; never read, copy, or publish
+the Vault, \`.brain\`, session registries, tokens, or secrets into a commit message.
+
+## Flow
+
+1. Confirm that authority and evidence references are current. The draft **does not accept**
+   caller-controlled \`tasks\` or \`tests\`; runtime derives tasks from completed Task Contracts.
+   Tests come only from a collector-executed \`[sensor:<id>]\`.
+   Envelope sensors must exactly match reexecution; only reexecution emits Tests.
+   \`[phase:verify]\` alone never proves execution, and range re-executes the sensor at the exact
+   SHA and re-derives authority/artifacts/task/spec/Scope/config there. Envelope/Verdict/receipt/TDD
+   stay local-only and are omitted from remote Evidence; never publish their local IDs. Tasks with
+   \`[req:]\` require a versioned sanitized \`spec\`. Use \`authority.kind: adr\`
+   whenever a causal change or ADR exists. Only under observed profile \`OFF\`, with no real causal
+   context/change/lease or ADR, use \`authority.kind: native\` with \`Issue #NNN\` and a versioned
+   design under \`docs/superpowers/specs/\` or \`plans/\`.
+2. Create JSON matching \`schema/commit-message-v1.schema.json\`. Do not claim \`fresh\`,
+   \`verified\`, \`tasks\`, or \`tests\`: runtime re-derives proof, artifact SHA-256, canonical
+   full identity/snapshot/tasks/spec/config binding, and staged-diff Scope. Missing expected fields,
+   empty envelopes, pending tasks, verdicts without
+   seals/coverage/independence, and receipts
+   without a valid chain/observation fail closed. \`Co-Authored-By\` is omitted
+   until a trusted identity registry can resolve it.
+3. After staging the files, run \`wendkeep commit context --input <file.json>\`. The CLI hashes the
+   Git index and stores the sanitized context inside \`.git\`, outside the working tree.
+4. Run \`git commit\` normally. The opt-in hooks revalidate context, hash, privacy, and triviality
+   before consuming context. Install them
+   explicitly with \`wendkeep init --git-commit-hooks --yes\`.
+5. Run \`wendkeep doctor\` for diagnostics; abandon a context with
+   \`wendkeep commit context --clear\`.
+
+Do not use \`--no-verify\` for implementation work. Amend, merge, and squash preserve the existing
+message and never receive invented content. The PR range check remains the remote bypass defense.
+`;
+
 // --- bundled templates (shipped alongside the relevant SKILL.md) -------------
 
 // Shared, language-neutral verdict skeleton for the independent verify pass.
@@ -709,6 +786,7 @@ const WK_SKILLS_PT = [
   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 }]),
   skill('wk-planning', 'Use após um design aprovado ou um plano aceito (inclusive plan mode) — decompõe em plano de tarefas TDD bite-sized e registra na change ativa.', PLANNING, [{ name: 'plan-template.md', content: PLAN_TEMPLATE_PT }]),
   skill('wk-verify', 'Use no verify deep — passe independente read-only (autor≠verificador) que re-deriva a cobertura do spec e grava verdict.json.', VERIFY, [{ name: 'spec-reviewer-prompt.md', content: REVIEWER_PROMPT_PT }, { name: 'verdict-template.json', content: VERDICT_TEMPLATE }]),
+  skill('wk-commit', 'Use ao preparar commits de implementação baseados em autoridade causal, tarefas, testes e evidências verificadas, com hooks Git opt-in e privacidade local.', WK_COMMIT),
 ];
 
 const WK_SKILLS_EN = [
@@ -718,6 +796,7 @@ const WK_SKILLS_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 }]),
   skill('wk-planning', 'Use after an approved design or an accepted plan (plan mode included) — decomposes it into a bite-sized TDD task plan recorded in the active change.', PLANNING_EN, [{ name: 'plan-template.md', content: PLAN_TEMPLATE_EN }]),
   skill('wk-verify', 'Use in verify deep — an independent read-only pass (author≠verifier) that re-derives spec coverage and writes verdict.json.', VERIFY_EN, [{ name: 'spec-reviewer-prompt.md', content: REVIEWER_PROMPT_EN }, { name: 'verdict-template.json', content: VERDICT_TEMPLATE }]),
+  skill('wk-commit', 'Use when preparing implementation commits from causal authority, tasks, tests, and verified evidence, with opt-in Git hooks and local privacy.', WK_COMMIT_EN),
 ];
 
 // Skill set for a locale. WK_SKILLS stays the pt-BR set for back-compat.