wendkeep 0.86.0 → 0.87.0

package/scripts/validate-commit-range.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import {
+  messageEvidence, messageScope, messageTasks, messageTests, nativeDesignReference, validateCommitMessage,
+} from '../packages/commit/src/index.mjs';
+import {
+  collectCommitSensorProof,
+  commitTaskSensorIds,
+  parseSignedEvidenceRef,
+  validateCommitProofSet,
+} from '../packages/commit/src/proof-validation.mjs';
+
+function option(argv, name) {
+  const index = argv.indexOf(name);
+  if (index >= 0) return argv[index + 1] || '';
+  return argv.find((item) => item.startsWith(`${name}=`))?.slice(name.length + 1) || '';
+}
+
+function git(args, { binary = false, allowFailure = false } = {}) {
+  const result = spawnSync('git', args, {
+    encoding: binary ? null : 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024,
+  });
+  if (!allowFailure && result.status !== 0) {
+    process.stderr.write((binary ? result.stderr?.toString('utf8') : result.stderr) || `git ${args.join(' ')} failed\n`);
+    process.exit(2);
+  }
+  return result;
+}
+const text = (args, options) => String(git(args, options).stdout || '');
+const objectExists = (specifier) => git(['cat-file', '-e', specifier], { allowFailure: true }).status === 0;
+const parents = (sha) => text(['show', '-s', '--format=%P', sha]).trim().split(/\s+/).filter(Boolean);
+
+function commitDiff(sha) {
+  const parent = parents(sha)[0];
+  const args = parent
+    ? ['diff', '--binary', '--no-ext-diff', '--no-color', parent, sha]
+    : ['show', '--format=', '--binary', '--no-ext-diff', '--no-color', sha];
+  return git(args, { binary: true }).stdout;
+}
+
+function changedFiles(sha) {
+  const parent = parents(sha)[0];
+  const args = parent
+    ? ['diff', '--name-only', '-z', '--no-renames', parent, sha]
+    : ['diff-tree', '--root', '--no-commit-id', '--name-only', '-z', '-r', sha];
+  return text(args).split('\0').filter(Boolean).map((path) => path.replaceAll('\\', '/'))
+    .sort((left, right) => left.localeCompare(right, 'en'));
+}
+
+function scopeFor(sha) {
+  return { sha256: createHash('sha256').update(commitDiff(sha)).digest('hex'), files: changedFiles(sha) };
+}
+
+const docsPath = (path) => /^(?:docs\/|README(?:\.en)?\.md$|[^/]+\.md$)/.test(path);
+const testPath = (path) => /^(?:tests?\/|fixtures?\/)/.test(path) || /(?:^|\/)__tests__\//.test(path);
+function trivialCommit(subject, files) {
+  if (!files.length) return false;
+  if (/^docs(?:\([^)]*\))?:/.test(subject)) return files.every(docsPath);
+  if (/^test(?:\([^)]*\))?:/.test(subject)) return files.every(testPath);
+  if (/^chore(?:\([^)]*\))?:/.test(subject)) return files.every((path) => docsPath(path) || testPath(path));
+  return false;
+}
+
+function mergeErrors(sha, message) {
+  const commitParents = parents(sha);
+  if (commitParents.length < 2 || !/^Merge\b/.test(message.split(/\r?\n/, 1)[0])) {
+    return ['merge commit must have multiple parents and a canonical Merge subject'];
+  }
+  const errors = [];
+  for (const path of changedFiles(sha)) {
+    const mergeObject = text(['rev-parse', `${sha}:${path}`], { allowFailure: true }).trim();
+    if (!mergeObject) continue;
+    const inherited = commitParents.some((parent) => (
+      text(['rev-parse', `${parent}:${path}`], { allowFailure: true }).trim() === mergeObject
+    ));
+    if (!inherited) errors.push(`WENDKEEP_COMMIT_MERGE_RESOLUTION_UNGOVERNED: ${path}`);
+  }
+  return errors;
+}
+
+function commitJson(sha, path) {
+  try { return JSON.parse(text(['show', `${sha}:${path}`])); } catch { return null; }
+}
+
+function collectSensorsAtCommit(sha, entries) {
+  const ids = commitTaskSensorIds(entries);
+  if (!ids.length) return null;
+  const config = commitJson(sha, 'wendkeep.sensors.json');
+  if (!config || !Array.isArray(config.sensors)) {
+    throw Object.assign(new Error('versioned wendkeep.sensors.json is required'), {
+      code: 'WENDKEEP_COMMIT_SENSOR_CONFIG_MISSING',
+    });
+  }
+  const parent = mkdtempSync(join(tmpdir(), 'wendkeep-commit-range-'));
+  const checkout = join(parent, 'checkout');
+  const added = git(['worktree', 'add', '--detach', '--force', checkout, sha], { allowFailure: true });
+  if (added.status !== 0) {
+    rmSync(parent, { recursive: true, force: true });
+    throw Object.assign(new Error(String(added.stderr || 'temporary commit checkout failed').trim()), {
+      code: 'WENDKEEP_COMMIT_CHECKOUT_FAILED',
+    });
+  }
+  try {
+    return collectCommitSensorProof({ sensors: config.sensors, ids, cwd: checkout });
+  } finally {
+    git(['worktree', 'remove', '--force', checkout], { allowFailure: true });
+    const bounded = resolve(parent);
+    if (bounded.startsWith(resolve(tmpdir()))) rmSync(bounded, { recursive: true, force: true });
+  }
+}
+
+function evidenceErrors(sha, message, scope) {
+  const errors = [];
+  const evidence = messageEvidence(message);
+  const entries = [];
+  for (const item of evidence) {
+    if (item.status !== 'verified' || ['evidence', 'receipt', 'verdict'].includes(item.kind)) {
+      errors.push('WENDKEEP_COMMIT_REMOTE_PROOF_UNAVAILABLE');
+      continue;
+    }
+    let signed;
+    try { signed = parseSignedEvidenceRef(item.ref); }
+    catch (error) { errors.push(error.code || error.message); continue; }
+    if (!objectExists(`${sha}:${signed.path}`)) {
+      errors.push(`WENDKEEP_COMMIT_EVIDENCE_UNVERSIONED: ${signed.path}`);
+      continue;
+    }
+    entries.push({ kind: item.kind, path: signed.path, sha256: signed.sha256, content: text(['show', `${sha}:${signed.path}`]) });
+    if (item.status !== 'verified') errors.push(`WENDKEEP_COMMIT_EVIDENCE_STATUS_INVALID: ${signed.path}`);
+  }
+  const adr = message.match(/^ADR:\s*(ADR-\d{4,})$/m)?.[1] || '';
+  const design = nativeDesignReference(message);
+  const authority = adr
+    ? { kind: 'adr', adr, ref: entries.find((entry) => entry.kind === 'adr')?.path || '', issue: message.match(/^Refs:\s*(#\d+)$/m)?.[1] || '' }
+    : { kind: 'native', issue: message.match(/^Issue:\s*(#\d+)$/m)?.[1] || '', design };
+  try {
+    const config = commitJson(sha, '.wendkeep.json') || {};
+    const executionProof = collectSensorsAtCommit(sha, entries);
+    const snapshot = {
+      head_sha: parents(sha)[0] || sha,
+      index_tree_sha: text(['show', '-s', '--format=%T', sha]).trim(),
+    };
+    const resolved = validateCommitProofSet({
+      entries, authority, stagedHash: scope.sha256,
+      context: {
+        projectId: config.projectId || '',
+        changeSlug: adr ? adr.toLowerCase() : `issue-${authority.issue.slice(1)}`,
+        baseSha: snapshot.base_sha,
+        headSha: snapshot.head_sha,
+        indexTreeSha: snapshot.index_tree_sha,
+        worktreeDigest: snapshot.worktree_digest,
+        dirty: snapshot.dirty,
+        sensorConfigSha256: executionProof?.configSha256,
+        executionProof,
+        profile: String(config?.harness?.profile || 'OFF').toUpperCase(),
+      },
+    });
+    if (JSON.stringify(messageTasks(message)) !== JSON.stringify(resolved.tasks)) errors.push('WENDKEEP_COMMIT_TASKS_MISMATCH');
+    if (JSON.stringify(messageTests(message)) !== JSON.stringify(resolved.tests)) errors.push('WENDKEEP_COMMIT_TESTS_MISMATCH');
+  } catch (error) {
+    errors.push(`${error.code || 'WENDKEEP_COMMIT_EVIDENCE_UNVERIFIED'}: ${error.message}`);
+  }
+  return errors;
+}
+
+function authorityErrors(sha, message) {
+  const errors = [];
+  const design = nativeDesignReference(message);
+  if (!design) return errors;
+  if (!objectExists(`${sha}:${design}`)) return [`WENDKEEP_COMMIT_DESIGN_UNVERSIONED: ${design}`];
+  const issue = message.match(/^Issue:\s*(#\d+)$/m)?.[1] || '';
+  const content = text(['show', `${sha}:${design}`]);
+  if (!content.includes(issue)) errors.push('WENDKEEP_COMMIT_NATIVE_ISSUE_UNVERIFIED');
+  const config = commitJson(sha, '.wendkeep.json');
+  if (String(config?.harness?.profile || '').toUpperCase() !== 'OFF') errors.push('WENDKEEP_COMMIT_NATIVE_PROFILE_REQUIRED');
+  const adrPaths = text(['ls-tree', '-r', '--name-only', sha]).split(/\r?\n/)
+    .filter((path) => /ADR-\d+.*\.md$/i.test(path));
+  if (adrPaths.some((path) => {
+    const adr = text(['show', `${sha}:${path}`]);
+    return adr.includes(issue) && adr.includes(design.split('/').at(-1));
+  })) errors.push('WENDKEEP_COMMIT_CAUSAL_AUTHORITY_EXISTS');
+  return errors;
+}
+
+function configuredPrivacyErrors(sha, message) {
+  const config = commitJson(sha, '.wendkeep.json');
+  const vault = typeof config?.vault === 'string' ? config.vault.replaceAll('\\', '/').trim() : '';
+  if (!vault) return [];
+  const name = vault.split('/').filter(Boolean).at(-1) || '';
+  const lower = message.toLowerCase();
+  return [vault, name].some((marker) => marker.length >= 3 && lower.includes(marker.toLowerCase()))
+    ? ['WENDKEEP_COMMIT_PRIVATE_PATH: message references the configured project Vault'] : [];
+}
+
+const base = option(process.argv.slice(2), '--base') || process.env.WENDKEEP_COMMIT_BASE || '';
+const head = option(process.argv.slice(2), '--head') || process.env.WENDKEEP_COMMIT_HEAD || 'HEAD';
+if (!base) {
+  process.stderr.write('WENDKEEP_COMMIT_ARGUMENT: --base is required\n');
+  process.exit(2);
+}
+
+const commits = text(['rev-list', '--reverse', `${base}..${head}`]).trim().split(/\r?\n/).filter(Boolean);
+const failures = [];
+for (const sha of commits) {
+  const message = text(['show', '-s', '--format=%B', sha]);
+  const subject = message.split(/\r?\n/, 1)[0];
+  const commitParents = parents(sha);
+  const errors = [...configuredPrivacyErrors(sha, message)];
+  if (commitParents.length > 1) {
+    errors.push(...mergeErrors(sha, message));
+  } else {
+    const result = validateCommitMessage(message);
+    errors.push(...result.errors);
+    if (messageEvidence(message).some((item) => (
+      item.status !== 'verified' || ['evidence', 'receipt', 'verdict'].includes(item.kind)
+    ))) errors.push('WENDKEEP_COMMIT_REMOTE_PROOF_UNAVAILABLE');
+    const files = changedFiles(sha);
+    if (!result.governed && !trivialCommit(subject, files)) errors.push('WENDKEEP_COMMIT_PRODUCT_CHANGE_UNGOVERNED');
+    if (result.governed && result.ok) {
+      const expected = scopeFor(sha);
+      const observed = messageScope(message);
+      if (expected.sha256 !== observed.sha256 || JSON.stringify(expected.files) !== JSON.stringify(observed.files)) {
+        errors.push('WENDKEEP_COMMIT_SCOPE_MISMATCH');
+      }
+      errors.push(...evidenceErrors(sha, message, expected), ...authorityErrors(sha, message));
+    }
+  }
+  if (errors.length) failures.push({ sha, subject, errors: [...new Set(errors)] });
+}
+
+if (failures.length) {
+  process.stderr.write(`WENDKEEP_COMMIT_RANGE_INVALID: ${failures.length} invalid commit(s)\n`);
+  for (const failure of failures) {
+    process.stderr.write(`${failure.sha.slice(0, 12)} ${failure.subject}\n`);
+    for (const error of failure.errors) process.stderr.write(`  - ${error}\n`);
+  }
+  process.exit(1);
+}
+process.stdout.write(`${commits.length} commit(s) valid\n`);

package/src/doctor.mjs

@@ -19,6 +19,7 @@ import {
 import { inspectPortableState } from './portable.mjs';
 import { inspectSyncOutbox, readLocalSyncState } from './sync-outbox.mjs';
 import { readProjectForValidation } from '../packages/vault/src/validate-memory.mjs';
+import { inspectGitCommitHooks } from './git-commit-hooks.mjs';
 
 const healthStatusLabel = (status) => ({
   healthy: 'saudável', warning: 'atenção', degraded: 'degradada', blocked: 'bloqueada', legacy: 'legado',
@@ -182,6 +183,11 @@ export function runDoctor(argv) {
     process.stdout.write(`  → ${issue.slug}: ${issue.errorCode} — ${issue.repair}\n`);
   }
 
+  const commitHooks = inspectGitCommitHooks({ projectRoot });
+  process.stdout.write(`\n[commit-hooks] ${commitHooks.status}\n`);
+  for (const issue of commitHooks.issues) process.stdout.write(`  ! ${issue}\n`);
+  if (commitHooks.repair) process.stdout.write(`  → ${commitHooks.repair}\n`);
+
   const activeContexts = inspectActiveContextHealth({ vaultBase, projectRoot });
   process.stdout.write(`\n${renderActiveContextHealthLines(activeContexts).join('\n')}\n`);
 
@@ -257,6 +263,7 @@ export function runDoctor(argv) {
     || repairable.length
     || warnings.length
     || worktrees.issues.length
+    || (commitHooks.configured && commitHooks.status !== 'healthy')
     || activeContexts.issues.length
     || ['diverged', 'invalid'].includes(portable.status)
     || sync.status === 'corrupt'

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/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.