wendkeep 0.86.0 → 0.88.0

package/schema/commit-message-v1.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wendkeep.dev/schema/commit-message-v1.schema.json",
+  "title": "WendKeep evidence-based commit input",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "subject", "capability", "authority", "evidence"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "summary"],
+      "properties": {
+        "type": { "enum": ["feat", "fix", "refactor", "perf"] },
+        "scope": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._/-]*$" },
+        "summary": { "type": "string", "minLength": 1, "maxLength": 120 }
+      }
+    },
+    "capability": { "type": "string", "minLength": 1, "maxLength": 500 },
+    "authority": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "adr", "ref"],
+          "properties": {
+            "kind": { "const": "adr" },
+            "adr": { "type": "string", "pattern": "^ADR-[0-9]{4,}$" },
+            "ref": { "type": "string", "minLength": 1 },
+            "issue": { "type": "string", "pattern": "^#[0-9]+$" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "issue", "design"],
+          "properties": {
+            "kind": { "const": "native" },
+            "issue": { "type": "string", "pattern": "^#[0-9]+$" },
+            "design": { "type": "string", "pattern": "^(docs/superpowers/specs|plans)/(?!\\.{1,2}(?:/|$))(?!.*//)(?!.*\\/\\.{1,2}(?:\\/|$))[a-zA-Z0-9._/-]+\\.md$" }
+          }
+        }
+      ]
+    },
+    "staged_diff": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sha256", "files"],
+      "properties": {
+        "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" },
+        "files": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "ref"],
+        "properties": {
+          "kind": { "enum": ["adr", "design", "evidence", "receipt", "spec", "task", "verdict"] },
+          "ref": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "limits": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": { "agent": { "type": "string" } }
+    }
+  }
+}

package/schema/observer/006-observer-security.sql

@@ -0,0 +1,64 @@
+-- wendkeep:structural
+-- Security lifecycle: hash-only credentials, access audit, retention, purge receipts and encrypted columns.
+
+ALTER TABLE llm_calls ADD COLUMN prompt_envelope TEXT NOT NULL DEFAULT '';
+ALTER TABLE llm_calls ADD COLUMN response_envelope TEXT NOT NULL DEFAULT '';
+ALTER TABLE llm_calls ADD COLUMN metadata_envelope TEXT NOT NULL DEFAULT '';
+ALTER TABLE documents ADD COLUMN content_envelope TEXT NOT NULL DEFAULT '';
+ALTER TABLE documents ADD COLUMN metadata_envelope TEXT NOT NULL DEFAULT '';
+ALTER TABLE transcripts ADD COLUMN metadata_envelope TEXT NOT NULL DEFAULT '';
+ALTER TABLE project_snapshots ADD COLUMN snapshot_envelope TEXT NOT NULL DEFAULT '';
+
+CREATE TABLE IF NOT EXISTS observer_tokens (
+  token_id TEXT PRIMARY KEY,
+  token_hash TEXT NOT NULL UNIQUE,
+  role TEXT NOT NULL CHECK(role IN ('viewer', 'auditor', 'publisher', 'admin')),
+  project_ids_json TEXT NOT NULL,
+  scopes_json TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  revoked_at TEXT,
+  rotated_from TEXT REFERENCES observer_tokens(token_id) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_observer_tokens_hash_active ON observer_tokens(token_hash, revoked_at, expires_at);
+
+CREATE TABLE IF NOT EXISTS observer_access_audit (
+  audit_id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  token_id TEXT REFERENCES observer_tokens(token_id) ON DELETE SET NULL,
+  capability TEXT NOT NULL,
+  outcome TEXT NOT NULL,
+  occurred_at TEXT NOT NULL,
+  metadata_json TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS idx_observer_audit_project_time ON observer_access_audit(project_id, occurred_at);
+
+CREATE TABLE IF NOT EXISTS observer_retention_policies (
+  project_id TEXT PRIMARY KEY REFERENCES projects(project_id) ON DELETE CASCADE,
+  policy_json TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS observer_purge_receipts (
+  receipt_id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  request_hash TEXT NOT NULL,
+  cutoff_at TEXT NOT NULL,
+  classes_json TEXT NOT NULL,
+  counts_json TEXT NOT NULL,
+  purged_at TEXT NOT NULL,
+  receipt_hash TEXT NOT NULL UNIQUE,
+  receipt_json TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_observer_purge_project_time ON observer_purge_receipts(project_id, purged_at);
+CREATE INDEX IF NOT EXISTS idx_observer_purge_request ON observer_purge_receipts(project_id, request_hash, purged_at);
+
+CREATE TABLE IF NOT EXISTS observer_security_backfill (
+  project_id TEXT PRIMARY KEY REFERENCES projects(project_id) ON DELETE CASCADE,
+  status TEXT NOT NULL,
+  protected_rows INTEGER NOT NULL DEFAULT 0,
+  updated_at TEXT NOT NULL
+);

package/schema/observer-policy-v1.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wendkeep.dev/schema/observer-policy-v1.schema.json",
+  "title": "WendKeep Observer policy v1",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "document_capture": { "enum": ["none", "metadata", "selected", "full"] },
+    "transcript_capture": { "enum": ["none", "metadata", "messages", "full"] },
+    "prompt_capture": { "enum": ["none", "redacted", "full"] },
+    "response_capture": { "enum": ["none", "redacted", "full"] },
+    "usage_capture": { "enum": ["none", "aggregate", "calls"] },
+    "require_loopback_auth": { "type": "boolean" },
+    "encryption_required": { "type": "boolean" },
+    "rules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["data_class", "capture"],
+        "properties": {
+          "project_id": { "type": "string", "minLength": 1, "maxLength": 121 },
+          "data_class": { "enum": ["document", "transcript", "prompt", "response", "usage"] },
+          "path": { "type": "string", "maxLength": 2048 },
+          "entity_type": { "type": "string", "maxLength": 160 },
+          "capture": { "enum": ["none", "metadata", "selected", "full", "messages", "redacted", "aggregate", "calls"] }
+        }
+      }
+    },
+    "redaction": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["pattern"],
+            "properties": {
+              "pattern": { "type": "string", "minLength": 1, "maxLength": 512 },
+              "replacement": { "type": "string", "maxLength": 160 }
+            }
+          }
+        }
+      }
+    },
+    "retention": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "document": { "type": "integer", "minimum": 0 },
+        "transcript": { "type": "integer", "minimum": 0 },
+        "prompt": { "type": "integer", "minimum": 0 },
+        "response": { "type": "integer", "minimum": 0 },
+        "usage": { "type": "integer", "minimum": 0 },
+        "documents": { "type": "integer", "minimum": 0 },
+        "calls": { "type": "integer", "minimum": 0 },
+        "transcripts": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/schema/sync-event-v1.schema.json

@@ -20,6 +20,16 @@
     "observed_at": { "type": "string", "format": "date-time" },
     "operation": { "enum": ["put", "tombstone", "resolve"] },
     "privacy": { "enum": ["shared", "private"] },
+    "policy_ref": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["policy_id", "version", "hash"],
+      "properties": {
+        "policy_id": { "type": "string", "minLength": 1, "maxLength": 160 },
+        "version": { "type": "integer", "minimum": 1 },
+        "hash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
+      }
+    },
     "payload": {}
   }
 }

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/observer-auth.mjs

@@ -8,3 +8,11 @@ export function observerAuthHeaders(token, headers = {}) {
     ? { ...headers, authorization: `Bearer ${resolved}` }
     : { ...headers };
 }
+
+export {
+  registerObserverToken,
+  resolveObserverPrincipal,
+  revokeObserverToken,
+  rotateObserverToken,
+} from '../packages/observer/src/token-registry.mjs';
+export { authorizeObserverPrincipal } from '../packages/observer/src/authz.mjs';