wendkeep 0.86.0 → 0.87.0

package/.githooks/commit-msg

@@ -0,0 +1,16 @@
+#!/bin/sh
+set -eu
+
+CLI=${WENDKEEP_COMMIT_CLI:-}
+if [ -z "$CLI" ]; then
+  if [ -f "./node_modules/wendkeep/bin/wendkeep.mjs" ]; then
+    CLI=./node_modules/wendkeep/bin/wendkeep.mjs
+  elif [ -f "./bin/wendkeep.mjs" ]; then
+    CLI=./bin/wendkeep.mjs
+  else
+    echo "WENDKEEP_COMMIT_CLI_MISSING: install wendkeep or run wendkeep doctor" >&2
+    exit 2
+  fi
+fi
+
+exec node "$CLI" commit validate --message-file "$1" --consume-context

package/.githooks/prepare-commit-msg

@@ -0,0 +1,16 @@
+#!/bin/sh
+set -eu
+
+CLI=${WENDKEEP_COMMIT_CLI:-}
+if [ -z "$CLI" ]; then
+  if [ -f "./node_modules/wendkeep/bin/wendkeep.mjs" ]; then
+    CLI=./node_modules/wendkeep/bin/wendkeep.mjs
+  elif [ -f "./bin/wendkeep.mjs" ]; then
+    CLI=./bin/wendkeep.mjs
+  else
+    echo "WENDKEEP_COMMIT_CLI_MISSING: install wendkeep or run wendkeep doctor" >&2
+    exit 2
+  fi
+fi
+
+exec node "$CLI" commit prepare --message-file "$1" --source "${2:-}" --commit "${3:-}"

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.87.0] — 2026-08-29
+
+### Added
+
+- **Política universal de commits baseada em evidências.** O novo pacote `wendkeep/commit`, a CLI,
+  os hooks Git e o gate de intervalo produzem e validam mensagens determinísticas a partir de
+  autoridade, tarefas, spec, escopo e sensores rederiváveis no checkout exato do commit.
+
+### Security
+
+- **Prova remota limitada ao que o CI consegue rederivar.** Evidências causais locais permanecem
+  não publicadas; alegações remotas indisponíveis, provas circulares, sensores divergentes,
+  adulterações de escopo e caminhos privados falham de modo fechado antes da persistência.
+
 ## [0.86.0] — 2026-08-28
 
 ### Added

package/README.en.md

@@ -151,6 +151,7 @@ npx wendkeep init --no-companions --no-mcp --yes              # zero companions,
 | `--no-mcp` | Skip **wendkeep's own** vault MCP (`wendkeep-vault`). Companion MCPs still follow `--companions`. |
 | `--no-colors` | Skip the Obsidian color system (`.obsidian` snippet + graph groups). |
 | `--vscode-worktree-tasks` | Create a local, Git-excluded `.vscode/tasks.json` for creating/listing/opening/finishing worktrees; never overwrites an existing file. Also accepted by `sync`. |
+| `--git-commit-hooks` | Opt in to copying commit hooks into `.githooks/` and setting local `core.hooksPath`; custom hooks are preserved without `--force`. |
 | `--yes`, `-y` | Non-interactive; accept defaults (skips the language / vault / companion prompts). |
 | `--force` | Overwrite existing wendkeep config blocks. |
 
@@ -259,6 +260,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Notes and knowledge** | BUG/APR/ADR, repairs, renumbering, lessons, and dashboard | [Notes and knowledge](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/notes-and-knowledge.md) |
 | **Costs and observability** | safe dry-run, tri-state, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
 | **Maintenance and diagnostics** | doctor, frontier/manifest freshness, drift, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
+| **Evidence-based commits** | `wendkeep commit`, tasks derived from contracts, tests only from canonical execution bound to the exact SHA, opt-in Git hooks, privacy, and remote range gate | [Commits](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/commit.md) |
 | **Local Observer** | `observer serve`, registration, incremental publication, `reconcile`, outbox, and multi-project index | [Local Observer](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer.md) |
 
 Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/verify.md),

package/README.md

@@ -151,6 +151,7 @@ npx wendkeep init --no-companions --no-mcp --yes              # zero companions,
 | `--no-mcp` | Skip **wendkeep's own** vault MCP (`wendkeep-vault`). Companion MCPs still follow `--companions`. |
 | `--no-colors` | Skip the Obsidian color system (`.obsidian` snippet + graph groups). |
 | `--vscode-worktree-tasks` | Create a local, Git-excluded `.vscode/tasks.json` for creating/listing/opening/finishing worktrees; never overwrites an existing file. Also accepted by `sync`. |
+| `--git-commit-hooks` | Opt in to copying commit hooks into `.githooks/` and setting local `core.hooksPath`; custom hooks are preserved without `--force`. |
 | `--yes`, `-y` | Non-interactive; accept defaults (skips the language / vault / companion prompts). |
 | `--force` | Overwrite existing wendkeep config blocks. |
 
@@ -259,6 +260,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Notes and knowledge** | BUG/APR/ADR, repairs, renumbering, lessons, and dashboard | [Notes and knowledge](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/notes-and-knowledge.md) |
 | **Costs and observability** | safe dry-run, tri-state, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
 | **Maintenance and diagnostics** | doctor, frontier/manifest freshness, drift, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
+| **Evidence-based commits** | `wendkeep commit`, tasks derived from contracts, tests only from canonical execution bound to the exact SHA, opt-in Git hooks, privacy, and remote range gate | [Commits](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/commit.md) |
 | **Local Observer** | `observer serve`, registration, incremental publication, `reconcile`, outbox, and multi-project index | [Local Observer](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer.md) |
 
 Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/verify.md),

package/docs/en/commands/commit.md

@@ -0,0 +1,159 @@
+# Evidence-based commits
+
+**English** · [Português](../../pt-BR/commands/commit.md)
+
+## Purpose
+
+Produce the same auditable message from Codex, Claude Code, or another Git client using typed input,
+public references, and a staged-index summary only. The deterministic kernel does not read the
+Vault, `.brain`, session registries, or the network.
+
+## When to use
+
+Use before `feat`, `fix`, `refactor`, or `perf` implementation commits that must record causal
+authority, tasks, tests, scope, and verifiable evidence consistently across harnesses.
+
+## When not to use
+
+Do not use it to invent proof, publish private content, rewrite history, or automate pushes.
+`docs`, `test`, and `chore` commits need no context only when every changed file is objectively
+documentation/test material. Product changes require the governed body regardless of type.
+
+## Prerequisites
+
+Run inside a Git repository with WendKeep installed locally and the selected product files already
+present in the staged index.
+
+## Syntax
+
+```bash
+npx --no-install wendkeep commit context --input <json|-> [--json]
+npx --no-install wendkeep commit context --clear [--json]
+npx --no-install wendkeep commit render --input <json|->
+npx --no-install wendkeep commit prepare --message-file <path> [--source <source>]
+npx --no-install wendkeep commit validate --message-file <path> [--json]
+```
+
+## Options and exit codes
+
+- Exit `0`: context written/cleared or message valid.
+- Exit `1`: invalid governed message.
+- Exit `2`: invalid argument, JSON, Git state, privacy boundary, or stale context.
+- `--consume-context` is reserved for the `commit-msg` wrapper and removes context after validation.
+
+## Opt-in installation
+
+The default `init` does not enable Git hooks. To copy the portable wrappers and set
+`core.hooksPath=.githooks` for this repository only:
+
+```bash
+npx --no-install wendkeep init --git-commit-hooks --yes
+```
+
+Custom hooks are never overwritten silently. When `init` finds a conflict it preserves the file.
+Review it and rerun with `--force` only when replacement is intended; the previous file is retained
+as `.bak`.
+A custom `core.hooksPath` is also a conflict and remains untouched without `--force`.
+
+## Examples
+
+### Prepare a commit
+
+Create JSON matching `schema/commit-message-v1.schema.json`. Declare authority and evidence
+references, but do not provide `tasks`, `tests`, `fresh`, or `verified`. Runtime derives tasks from
+completed canonical Task Contracts. Tests come only from `[sensor:<id>]` sensors executed by the
+collector; `[phase:verify]` alone is never a result. Sensors
+declared in an Envelope must exactly match the canonical reexecution in IDs, configuration,
+command, severity, and result; only that reexecution emits a `Tests` line. The remote gate
+re-executes each sensor in the checkout for that exact commit SHA. Every
+published reference gets a re-derived SHA-256 digest. ADR/design validate artifact ID and path;
+tasks containing `[req:]` require a versioned, sanitized `spec` reference that defines every
+requirement. Evidence Envelope, Verdict, receipt, and TDD attestation may participate in local
+validation, but are omitted from remote Evidence: worktree/session/branch IDs are not published,
+and self-contained consistency is not promoted to proof. A message claiming them as
+`fresh`/`verified` is rejected with `WENDKEEP_COMMIT_REMOTE_PROOF_UNAVAILABLE`. The fixed trailers
+`Remote-Proof-Scope: git,authority,tasks,spec,sensors` and `Local-Causal-Proof: unpublished` make
+that boundary explicit. Range re-derives authority/artifacts, task/spec, Git `Scope`, and
+config/sensors from the SHA, and only canonical reexecution emits `Tests`. `Co-Authored-By` is
+omitted until a trusted identity registry can resolve it.
+
+The normal authority is the causal ADR:
+
+```json
+{ "authority": { "kind": "adr", "adr": "ADR-1234", "ref": "docs/ADR-1234.md", "issue": "#123" } }
+```
+
+Only when no causal change/ADR exists may the native harness declare the fallback below. `issue`
+must be `#NNN` and `design` must be versioned in the same commit under
+`docs/superpowers/specs/` or `plans/`:
+
+```json
+{
+  "authority": {
+    "kind": "native",
+    "issue": "#40",
+    "design": "docs/superpowers/specs/approved-design.md"
+  }
+}
+```
+
+Runtime observes effective profile `OFF`, no causal context/change/lease or ADR, and the issue in the
+design. This mode emits unique `Authority: native-no-causal-change`, `Issue`, and `Design` trailers. Free text, unversioned
+design, stale/unverified proof, or a missing body/tests fail closed.
+
+```bash
+git add <product-files>
+npx --no-install wendkeep commit context --input commit-input.json
+git commit -m "feat(scope): draft"
+```
+
+`commit context` calculates the staged diff SHA-256 and stores the sanitized context at
+`.git/wendkeep-commit-input.json`, outside the working tree. `prepare-commit-msg` replaces the draft
+with the canonical message; `commit-msg` validates it and consumes the context. If the index changes,
+the context becomes stale and must be recreated.
+`commit-msg` rereads context, compares the complete message and staged hash/files, and consumes
+context only after success. Merge, squash, and amend clear incompatible context so it cannot leak
+to the next commit. `--message-file` stays inside the repository or Git directory.
+
+Other commands:
+
+```bash
+npx --no-install wendkeep commit render --input commit-input.json
+npx --no-install wendkeep commit validate --message-file .git/COMMIT_EDITMSG
+npx --no-install wendkeep commit context --clear
+```
+
+Objectively trivial commits remain unchanged. Implementation
+commits (`feat`, `fix`, `refactor`, and `perf`) require a Conventional Commit subject with an ADR or
+the restricted native fallback above, Capability, Evidence, Tasks, Tests, and Scope sections, the
+staged hash, and a `WendKeep-Commit: v1` trailer. Amend, merge, and squash never receive duplicate or
+invented proof.
+
+## Privacy and fail-closed behavior
+
+- Embedded absolute paths, any configured/default Vault, `.brain`, session registries, PII, and secrets are rejected
+  before persistence.
+- `reported`, `legacy-unbound`, `stale`, and `unproven` evidence cannot be presented as proof.
+- Context holds sanitized references and diff metadata, never private Vault content.
+- `--no-verify` is not accepted: CI validates every new commit, including merges and novel resolutions.
+
+## Expected result
+
+A deterministic, self-contained message with no private material, the hash of the committed index,
+and coherent causal trailers.
+
+## Common errors and diagnosis
+
+`wendkeep doctor` reports `[commit-hooks] healthy`, `disabled`, `missing`, or `drift` and remains
+read-only. After review, recover missing or divergent files with:
+
+```bash
+npx --no-install wendkeep init --git-commit-hooks --force --yes
+```
+
+When abandoning a commit, remove only its transient context with
+`wendkeep commit context --clear`. No command rewrites history or pushes automatically.
+
+## Next steps
+
+Review the generated message, commit it, and let the PR range gate detect any local bypass.

package/docs/pt-BR/commands/commit.md

@@ -0,0 +1,159 @@
+# Commits baseados em evidências
+
+**PT-BR** · [English](../../en/commands/commit.md)
+
+## Objetivo
+
+Produzir a mesma mensagem auditável em Codex, Claude Code ou outro cliente Git, usando somente
+entrada tipada, referências públicas e o resumo do index staged. O kernel é determinístico e não
+lê o Vault, `.brain`, registros de sessão ou rede.
+
+## Quando usar
+
+Use antes de commits de implementação `feat`, `fix`, `refactor` ou `perf` que precisam registrar
+autoridade causal, tarefas, testes, escopo e evidência verificável de forma equivalente entre
+harnesses.
+
+## Quando não usar
+
+Não use para inventar prova, publicar conteúdo privado, reescrever histórico ou automatizar push.
+Commits `docs`, `test` e `chore` dispensam contexto somente quando todos os arquivos alterados são
+objetivamente documentação/testes. Alteração de produto exige o corpo governado mesmo com outro tipo.
+
+## Pré-requisitos
+
+Execute dentro de um repositório Git, com o WendKeep instalado localmente e os arquivos do produto
+já selecionados no index staged.
+
+## Sintaxe
+
+```bash
+npx --no-install wendkeep commit context --input <json|-> [--json]
+npx --no-install wendkeep commit context --clear [--json]
+npx --no-install wendkeep commit render --input <json|->
+npx --no-install wendkeep commit prepare --message-file <path> [--source <source>]
+npx --no-install wendkeep commit validate --message-file <path> [--json]
+```
+
+## Opções e códigos de saída
+
+- Exit `0`: contexto escrito/limpo ou mensagem válida.
+- Exit `1`: mensagem governada inválida.
+- Exit `2`: argumento, JSON, Git, privacidade ou contexto inválido/stale.
+- `--consume-context` é reservado ao wrapper `commit-msg`; remove o contexto após validação verde.
+
+## Instalação opt-in
+
+Os hooks Git não são ativados pelo `init` padrão. Para copiar os wrappers portáteis e configurar
+`core.hooksPath=.githooks` somente neste repositório:
+
+```bash
+npx --no-install wendkeep init --git-commit-hooks --yes
+```
+
+Hooks personalizados nunca são sobrescritos silenciosamente. Se o `init` encontrar conflito, ele
+preserva o arquivo. Revise-o e, somente se quiser substituí-lo, execute novamente com `--force`; o
+arquivo anterior fica em `.bak`.
+Um `core.hooksPath` customizado também é conflito: sem `--force` ele permanece intocado.
+
+## Exemplos
+
+### Preparar um commit
+
+Crie um JSON conforme `schema/commit-message-v1.schema.json`. Declare autoridade e referências de
+evidência, mas não envie `tasks`, `tests`, `fresh` ou `verified`. O runtime deriva tarefas do
+checklist canônico com Task Contracts concluídos. Testes vêm somente de sensores declarados por
+`[sensor:<id>]` e executados pelo coletor; `[phase:verify]`
+sozinho nunca é resultado. Sensors declarados no Envelope devem corresponder exatamente em IDs,
+configuração, comando, severidade e resultado à reexecução canônica; apenas essa reexecução gera a
+linha `Tests`. O gate remoto reexecuta o sensor no checkout do SHA correspondente.
+Cada referência publicada recebe digest SHA-256 rederivado. ADR/design validam
+ID/path/artefato. Tasks com `[req:]` exigem uma referência `spec` versionada e sanitizada que defina
+cada requisito. Evidence Envelope, Verdict, receipt e TDD attestation podem participar da validação
+local, mas são omitidos da Evidence remota: não há publicação de IDs de worktree/sessão/branch nem
+promoção de consistência autocontida para prova. Se uma mensagem os alegar como `fresh`/`verified`,
+o range rejeita `WENDKEEP_COMMIT_REMOTE_PROOF_UNAVAILABLE`. Os trailers fixos
+`Remote-Proof-Scope: git,authority,tasks,spec,sensors` e `Local-Causal-Proof: unpublished` tornam
+essa fronteira explícita. No range, authority/artefatos, task/spec, `Scope` Git e config/sensors são
+rederivados do SHA, e apenas a reexecução canônica gera `Tests`. `Co-Authored-By` é
+omitido enquanto não houver identidade registrada confiável.
+
+A autoridade normal é a ADR causal:
+
+```json
+{ "authority": { "kind": "adr", "adr": "ADR-1234", "ref": "docs/ADR-1234.md", "issue": "#123" } }
+```
+
+Somente quando não existe change/ADR causal, o harness nativo pode declarar o fallback abaixo.
+`issue` deve ser `#NNN` e `design` precisa estar versionado no mesmo commit sob
+`docs/superpowers/specs/` ou `plans/`:
+
+```json
+{
+  "authority": {
+    "kind": "native",
+    "issue": "#40",
+    "design": "docs/superpowers/specs/design-aprovado.md"
+  }
+}
+```
+
+O runtime confirma perfil efetivo `OFF`, ausência de context/change/lease e ADR causal reais, além
+da issue no design. Esse modo gera trailers únicos `Authority: native-no-causal-change`, `Issue` e `Design`. Texto solto,
+design não versionado, prova stale/unverified, corpo ou testes ausentes falham fechados.
+
+```bash
+git add <arquivos-do-produto>
+npx --no-install wendkeep commit context --input commit-input.json
+git commit -m "feat(escopo): rascunho"
+```
+
+`commit context` calcula o hash SHA-256 do diff staged e guarda o contexto sanitizado em
+`.git/wendkeep-commit-input.json`, fora do working tree. `prepare-commit-msg` substitui o rascunho
+pela mensagem canônica; `commit-msg` valida e consome o contexto. Se o index mudar, o contexto fica
+stale e deve ser recriado.
+O `commit-msg` relê o contexto, compara a mensagem inteira e o hash/files staged, e só consome o
+contexto após sucesso. `merge`, `squash` e amend limpam contexto incompatível para não contaminar o
+commit seguinte. `--message-file` fica contido no repositório ou git-dir.
+
+Outros comandos:
+
+```bash
+npx --no-install wendkeep commit render --input commit-input.json
+npx --no-install wendkeep commit validate --message-file .git/COMMIT_EDITMSG
+npx --no-install wendkeep commit context --clear
+```
+
+Commits realmente triviais permanecem intactos. Commits de implementação
+`feat`, `fix`, `refactor` e `perf` exigem assunto Conventional Commit com ADR ou o fallback nativo
+restrito acima, seções Capability, Evidence, Tasks, Tests e Scope, hash staged e trailer
+`WendKeep-Commit: v1`. Amend, merge e squash não recebem corpo duplicado ou prova inventada.
+
+## Privacidade e falha segura
+
+- Caminhos absolutos mesmo embutidos, qualquer Vault configurado/default, `.brain`, registros de sessão, PII e segredos são
+  rejeitados antes da persistência.
+- Evidência `reported`, `legacy-unbound`, `stale` ou `unproven` não pode ser apresentada como prova.
+- O contexto contém referências sanitizadas e metadados do diff, nunca o conteúdo privado do Vault.
+- `--no-verify` não é um fluxo aceito: o CI valida cada commit novo, inclusive merges e resoluções inéditas.
+
+## Resultado esperado
+
+Uma mensagem determinística, autocontida, sem material privado, com hash do mesmo index que foi
+commitado e trailers causais coerentes.
+
+## Erros comuns e diagnóstico
+
+`wendkeep doctor` mostra `[commit-hooks] healthy`, `disabled`, `missing` ou `drift` e permanece
+read-only. Para recuperar arquivos ausentes ou divergentes após revisão:
+
+```bash
+npx --no-install wendkeep init --git-commit-hooks --force --yes
+```
+
+Se um commit for abandonado, limpe apenas o contexto transitório com
+`wendkeep commit context --clear`. Nenhum comando reescreve histórico ou faz push automaticamente.
+
+## Próximos passos
+
+Revise a mensagem gerada, faça o commit e deixe o gate de range do PR validar qualquer bypass local.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.86.0",
+  "version": "0.87.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": [
@@ -9,6 +9,7 @@
   "exports": {
     "./harness": "./packages/harness/src/index.mjs",
     "./vault": "./packages/vault/src/index.mjs",
+    "./commit": "./packages/commit/src/index.mjs",
     "./hooks/*": "./hooks/*",
     "./src/*": "./src/*",
     "./bin/*": "./bin/*",
@@ -28,8 +29,10 @@
     "bin",
     "src",
     "hooks",
+    ".githooks",
     "packages",
     "schema",
+    "scripts/validate-commit-range.mjs",
     "web/observer",
     "docs/pt-BR/commands/*.md",
     "docs/en/commands/*.md",
@@ -42,7 +45,7 @@
   },
   "scripts": {
     "precheck": "node --check src/capabilities.mjs && node --check src/host-capabilities.mjs && node --check src/task-contracts.mjs && node --check src/task-leases.mjs && node --check src/task.mjs && node --check src/change.mjs && node --check src/archive-operation-lock.mjs && node --check src/worktree.mjs && node --check src/worktree-cleanup.mjs && node --check src/provenance-gate.mjs && node --check src/provenance-sources.mjs && node --check src/receipt-ledger.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 hooks/session-stop.mjs && node --check packages/vault/src/worktree-metadata.mjs && node --check packages/vault/src/evidence-envelope.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/integrations/src/capabilities.mjs && node --check packages/pi/src/index.mjs && node --check src/sync-protocol.mjs && node --check src/sync-outbox.mjs && node --check src/sync-adapters.mjs && node --check src/sync-protocol-cli.mjs && node --check packages/mcp/src/sync.mjs && node --check src/portable.mjs && node --check src/tdd.mjs && node --check src/tdd-attestation.mjs && node --check src/tdd-attestation-store.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/mcp.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/audit.mjs && node --check packages/mcp/src/cli.mjs && node --check packages/mcp/src/config.mjs && node --check packages/mcp/src/effects.mjs && node --check packages/mcp/src/executor.mjs && node --check packages/mcp/src/server.mjs && node --check packages/mcp/src/stdio.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",
+    "check": "node --check scripts/validate-commit-range.mjs && node --check packages/commit/src/index.mjs && node --check packages/commit/src/cli.mjs && node --check packages/commit/src/git-runtime.mjs && node --check src/git-commit-hooks.mjs && 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/mcp.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/audit.mjs && node --check packages/mcp/src/cli.mjs && node --check packages/mcp/src/config.mjs && node --check packages/mcp/src/effects.mjs && node --check packages/mcp/src/executor.mjs && node --check packages/mcp/src/server.mjs && node --check packages/mcp/src/stdio.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",
     "release": "node scripts/release.mjs",

package/packages/cli/src/index.mjs

@@ -34,6 +34,7 @@ Usage:
     --no-companions        Skip companion plugins/MCP entirely.
     --no-colors            Skip the Obsidian color system (.obsidian snippet + graph groups).
     --vscode-worktree-tasks Create local, Git-excluded VS Code tasks for managed worktrees.
+    --git-commit-hooks      Opt in to .githooks + local core.hooksPath for evidence commits.
     --dotcontext-mcp <v>   dotcontext MCP placement: auto (default; skip project entry
                            if already global), project, or none.
     --dotcontext-hooks <v> dotcontext hooks: full (default), light (no PostToolUse), none.
@@ -53,6 +54,7 @@ Usage:
                            Uses explicit CAS/conflicts and an offline outbox; --remote path or --url HTTPS.
 
   wendkeep doctor [--vault P]  Health check. --scope core|runtime · --strict for CI/release.
+  wendkeep commit <sub>        Evidence-based Git commits: context | render | prepare | validate.
   wendkeep portable <sub>      Shared authored state: status | export | import | diff.
                            Default file: .wendkeep/portable/state.json; private runtime stays local.
   wendkeep mcp <serve|config>  Native semantic MCP over stdio, or client config generation.
@@ -232,6 +234,9 @@ async function main(argv) {
     } else if (cmd === 'capabilities') {
       const { CAPABILITIES_HELP } = await import('../../../src/capabilities.mjs');
       process.stdout.write(CAPABILITIES_HELP);
+    } else if (cmd === 'commit') {
+      const { COMMIT_HELP } = await import('../../commit/src/cli.mjs');
+      process.stdout.write(COMMIT_HELP);
     } else {
       process.stdout.write(HELP);
     }
@@ -245,7 +250,7 @@ async function main(argv) {
     // `sync` starts with `init` and resolves the freshly bound Vault itself. Pre-resolving
     // here would prevent that repair step from reporting a corrupt binding as its own
     // first-stage failure (and could never make it as far as the guarded init).
-    && !['init', 'sync', 'worktree', 'hook', 'observer', 'mcp', 'capabilities', '--version', '-v', '--help', '-h', 'help'].includes(cmd)) {
+    && !['init', 'sync', 'worktree', 'hook', 'observer', 'mcp', 'capabilities', 'commit', '--version', '-v', '--help', '-h', 'help'].includes(cmd)) {
     await preferProjectVault(rest);
   }
   switch (cmd) {
@@ -262,6 +267,11 @@ async function main(argv) {
       process.exit(runDoctor(rest));
       break;
     }
+    case 'commit': {
+      const { runCommit } = await import('../../commit/src/cli.mjs');
+      process.exit(runCommit(rest));
+      break;
+    }
     case 'portable': {
       const { runPortable } = await import('../../../src/portable.mjs');
       process.exit(runPortable(rest));

package/packages/commit/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@wendkeep/commit",
+  "private": true,
+  "type": "module",
+  "exports": "./src/index.mjs"
+}

package/packages/commit/src/cli.mjs

@@ -0,0 +1,89 @@
+import { readFileSync } from 'node:fs';
+
+import { renderCommitMessage } from './commit-message.mjs';
+import {
+  buildCommitInput,
+  clearCommitContext,
+  prepareCommitMessageFile,
+  validateCommitMessageFile,
+  writeCommitContext,
+} from './git-runtime.mjs';
+
+export const COMMIT_HELP = `wendkeep commit — evidence-based Git commit policy
+
+Usage:
+  wendkeep commit context --input <json|-> [--json]
+  wendkeep commit context --clear [--json]
+  wendkeep commit render --input <json|->
+  wendkeep commit prepare --message-file <path> [--source <source>]
+  wendkeep commit validate --message-file <path> [--consume-context] [--json]
+
+The context is stored under the repository Git directory, never in the Vault or working tree.
+`;
+
+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 readInput(path) {
+  if (!path) throw Object.assign(new Error('--input is required'), { code: 'WENDKEEP_COMMIT_ARGUMENT' });
+  const source = path === '-' ? readFileSync(0, 'utf8') : readFileSync(path, 'utf8');
+  return JSON.parse(source);
+}
+
+function outputJson(value) {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+export function runCommit(argv, { cwd = process.cwd() } = {}) {
+  const [subcommand, ...rest] = argv;
+  const json = rest.includes('--json');
+  try {
+    if (!subcommand || subcommand === 'help' || rest.includes('--help') || rest.includes('-h')) {
+      process.stdout.write(COMMIT_HELP);
+      return 0;
+    }
+    if (subcommand === 'context') {
+      const result = rest.includes('--clear')
+        ? clearCommitContext({ cwd })
+        : writeCommitContext(readInput(option(rest, '--input')), { cwd });
+      if (json) outputJson(rest.includes('--clear') ? result : { path: result.path, schema_version: 1 });
+      else process.stdout.write(`${rest.includes('--clear') ? 'cleared' : 'written'}: ${result.path}\n`);
+      return 0;
+    }
+    if (subcommand === 'render') {
+      const input = buildCommitInput(readInput(option(rest, '--input')), { cwd });
+      process.stdout.write(renderCommitMessage(input));
+      return 0;
+    }
+    if (subcommand === 'prepare') {
+      const result = prepareCommitMessageFile({
+        messageFile: option(rest, '--message-file'),
+        source: option(rest, '--source'),
+        cwd,
+      });
+      if (json) outputJson(result);
+      return 0;
+    }
+    if (subcommand === 'validate') {
+      const result = validateCommitMessageFile({
+        messageFile: option(rest, '--message-file'),
+        consumeContext: rest.includes('--consume-context'),
+        cwd,
+      });
+      if (json) outputJson(result);
+      if (!result.ok) {
+        process.stderr.write(`WENDKEEP_COMMIT_MESSAGE_INVALID\n${result.errors.map((error) => `- ${error}`).join('\n')}\n`);
+        return 1;
+      }
+      return 0;
+    }
+    process.stderr.write(`wendkeep commit: unknown subcommand "${subcommand}"\n`);
+    return 2;
+  } catch (error) {
+    process.stderr.write(`${error.code || 'WENDKEEP_COMMIT_ERROR'}: ${error.message}\n`);
+    return 2;
+  }
+}