@bookedsolid/rea 0.29.0 → 0.30.0

package/dist/cli/doctor.js

@@ -1,3 +1,4 @@
+import { execFileSync } from 'node:child_process';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import fsPromises from 'node:fs/promises';
@@ -7,7 +8,7 @@ import { loadRegistry } from '../registry/loader.js';
 import { loadFingerprintStore } from '../registry/fingerprints-store.js';
 import { fingerprintServer } from '../registry/fingerprint.js';
 import { CodexProbe } from '../gateway/observability/codex-probe.js';
-import { inspectPrePushState } from './install/pre-push.js';
+import { inspectPrePushState, isHusky9Stub, resolveHusky9StubTarget, } from './install/pre-push.js';
 import { summarizeTelemetry } from '../gateway/observability/codex-telemetry.js';
 import { CLAUDE_MD_MANIFEST_PATH, SETTINGS_MANIFEST_PATH, enumerateCanonicalFiles, } from './install/canonical.js';
 import { buildFragment } from './install/claude-md.js';
@@ -16,6 +17,8 @@ import { manifestExists, readManifest } from './install/manifest-io.js';
 import { sha256OfBuffer, sha256OfFile } from './install/sha.js';
 import { DELEGATION_SIGNAL_TOOL_NAME } from '../audit/delegation-event.js';
 import { computeHash } from '../audit/fs.js';
+import { PREPARE_COMMIT_MSG_BODY_MARKER, PREPARE_COMMIT_MSG_MARKER, } from './install/prepare-commit-msg.js';
+import { validateSettings } from '../config/settings-schema.js';
 import { POLICY_FILE, REA_DIR, REGISTRY_FILE, getPkgVersion, log, reaPath } from './utils.js';
 function checkFileExists(label, filePath, fatal) {
     const exists = fs.existsSync(filePath);
@@ -134,7 +137,15 @@ function checkRegistryParses(baseDir, registryPath) {
         };
     }
 }
-const EXPECTED_AGENTS = [
+/**
+ * 0.30.0 (Class M settings.json schema) — `EXPECTED_HOOKS` is exported
+ * so the schema validator at `src/config/settings-schema.ts` can
+ * cross-check rea-shipped hook filenames against entries it sees in
+ * a consumer's `.claude/settings.json`. The validator's `--strict`
+ * mode FAILS when a known rea-managed hook is missing from the
+ * consumer's registration; default mode logs a warn.
+ */
+export const EXPECTED_AGENTS = [
     'accessibility-engineer.md',
     'backend-engineer.md',
     'code-reviewer.md',
@@ -146,7 +157,7 @@ const EXPECTED_AGENTS = [
     'technical-writer.md',
     'typescript-specialist.md',
 ];
-const EXPECTED_HOOKS = [
+export const EXPECTED_HOOKS = [
     'architecture-review-gate.sh',
     'attribution-advisory.sh',
     // 0.22.0 — Bash-tier parity with `blocked-paths-enforcer.sh`.
@@ -231,6 +242,85 @@ function checkHooksInstalled(baseDir) {
     }
     return { label: 'hooks installed + executable', status: 'fail', detail: issues.join('; ') };
 }
+/**
+ * 0.30.0 Class M — validate `.claude/settings.json` against the zod
+ * schema in `src/config/settings-schema.ts`.
+ *
+ * Status posture:
+ *
+ *   - `strict: false` (default `rea doctor`) — emit a warn when:
+ *       - zod parse fails (unknown top-level key, missing matcher,
+ *         malformed hook entry, etc.),
+ *       - any `command` contains a `..` traversal after stripping
+ *         `$CLAUDE_PROJECT_DIR`,
+ *       - any rea-shipped hook from `EXPECTED_HOOKS` is missing from
+ *         the consumer's registrations.
+ *     The harness keeps working — the schema only refuses to call
+ *     malformed hook entries; we surface the issue without breaking
+ *     the install.
+ *
+ *   - `strict: true` (`rea doctor --strict`) — fail (hard) on the
+ *     same conditions. Used by CI gates that want a hard floor on
+ *     consumer settings.
+ *
+ * Returns `pass` when everything cleared. Returns one `CheckResult`
+ * per concern; called once and emits one result. Combined with the
+ * existing `checkSettingsJson` (which checks for the historical Bash
+ * + Write|Edit|MultiEdit|NotebookEdit matchers), gives consumers a
+ * complete picture.
+ */
+export function checkSettingsSchema(baseDir, strict) {
+    const label = strict ? 'settings.json schema (strict)' : 'settings.json schema (advisory)';
+    const settingsPath = path.join(baseDir, '.claude', 'settings.json');
+    if (!fs.existsSync(settingsPath)) {
+        return {
+            label,
+            status: strict ? 'fail' : 'warn',
+            detail: `missing: ${settingsPath}`,
+        };
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(settingsPath, 'utf8');
+    }
+    catch (e) {
+        return {
+            label,
+            status: strict ? 'fail' : 'warn',
+            detail: e instanceof Error ? e.message : String(e),
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        return {
+            label,
+            status: 'fail',
+            detail: `malformed JSON: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+    const result = validateSettings(parsed);
+    const issues = [];
+    if (!result.parsed) {
+        issues.push(...result.errors.map((e) => `schema: ${e}`));
+    }
+    for (const t of result.traversalFindings) {
+        issues.push(`traversal: ${t.event}[${t.matcher}].hooks[${t.index}].command — ${t.reason}`);
+    }
+    for (const missing of result.missingReaHooks) {
+        issues.push(`missing rea hook: ${missing} not registered in PreToolUse/PostToolUse`);
+    }
+    if (issues.length === 0) {
+        return { label, status: 'pass' };
+    }
+    return {
+        label,
+        status: strict ? 'fail' : 'warn',
+        detail: issues.join('; '),
+    };
+}
 function checkSettingsJson(baseDir) {
     const settingsPath = path.join(baseDir, '.claude', 'settings.json');
     if (!fs.existsSync(settingsPath)) {
@@ -344,6 +434,165 @@ export function isGitRepo(baseDir) {
     const resolved = path.isAbsolute(targetPath) ? targetPath : path.join(baseDir, targetPath);
     return fs.existsSync(resolved);
 }
+/**
+ * 0.30.0 attribution augmenter — verify the husky `prepare-commit-msg`
+ * hook state matches what `policy.attribution.co_author.enabled` asks
+ * for. Four buckets:
+ *
+ *   1. `enabled: true` + hook present + rea-managed marker → pass.
+ *   2. `enabled: true` + hook missing OR marker mismatched → fail.
+ *      Defense in depth: the loader's cross-field refinement should
+ *      already have rejected `enabled: true` without identity, but
+ *      we surface a missing hook file separately.
+ *   3. `enabled: true` + name OR email empty → fail. The loader should
+ *      have already caught this; surfacing here ensures `rea doctor`
+ *      reports a clean state for the entire augmenter surface.
+ *   4. `enabled: false` (or absent) + hook present (rea-managed) → pass
+ *      (no-op — hook ships under every install).
+ *   5. `enabled: false` (or absent) + foreign file → warn. The operator
+ *      has a `prepare-commit-msg` outside rea's marker; their commits
+ *      get whatever it does, which is fine.
+ *   6. `enabled: false` + hook absent → pass (vanilla state).
+ *
+ * Returns `info` when the rea-shipped `.git/hooks/prepare-commit-msg`
+ * lives under a hooksPath we couldn't resolve (treat as same as case
+ * 6 from doctor's perspective).
+ */
+/**
+ * Resolve the active git hooks directory for the doctor's prepare-commit-msg
+ * check. Mirrors `installCommitMsgHook`'s `readHooksPathFromGit` but
+ * synchronous (doctor is sync end-to-end). Honors `core.hooksPath` when set
+ * (husky 9 installs land at `.husky/_/`); falls back to `.git/hooks/`
+ * otherwise. Codex round 1 P2: prior implementation always looked at
+ * `.git/hooks/prepare-commit-msg`, false-reporting missing on any consumer
+ * running husky.
+ */
+function resolveHooksDirSync(baseDir) {
+    try {
+        const out = execFileSync('git', ['-C', baseDir, 'config', '--get', 'core.hooksPath'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const trimmed = out.trim();
+        if (trimmed.length > 0) {
+            return path.isAbsolute(trimmed) ? trimmed : path.join(baseDir, trimmed);
+        }
+    }
+    catch {
+        // git missing or `core.hooksPath` unset — fall through to default.
+    }
+    return path.join(baseDir, '.git', 'hooks');
+}
+export function checkPrepareCommitMsgHook(baseDir) {
+    const label = 'prepare-commit-msg hook (attribution augmenter)';
+    const hooksDir = resolveHooksDirSync(baseDir);
+    const hookPath = path.join(hooksDir, 'prepare-commit-msg');
+    let policyAttr;
+    try {
+        const policy = loadPolicy(baseDir);
+        policyAttr = policy.attribution?.co_author;
+    }
+    catch {
+        // policy-parse failure is surfaced elsewhere; default to "absent"
+        policyAttr = undefined;
+    }
+    const enabled = policyAttr?.enabled === true;
+    const hookExists = fs.existsSync(hookPath);
+    let hookIsReaManaged = false;
+    let hookMarkerMismatch = false;
+    if (hookExists) {
+        try {
+            let content = fs.readFileSync(hookPath, 'utf8');
+            // Codex round 3 P2: Husky 9 (`core.hooksPath=.husky/_`) auto-
+            // generates a stub like `. "${0%/*}/h"` at the active hooks path.
+            // Git dispatches through that stub to `.husky/prepare-commit-msg`
+            // (the canonical body, which IS rea-managed). Follow the
+            // indirection so doctor classifies the canonical body, not the
+            // stub. Same pattern as installer + pre-push doctor checks.
+            if (isHusky9Stub(content)) {
+                const target = resolveHusky9StubTarget(hookPath);
+                if (target !== null && target !== hookPath && fs.existsSync(target)) {
+                    try {
+                        content = fs.readFileSync(target, 'utf8');
+                    }
+                    catch {
+                        // canonical body unreadable — fall through with stub content,
+                        // which will classify as foreign and surface a clear error.
+                    }
+                }
+            }
+            const lines = content.split('\n');
+            hookIsReaManaged =
+                content.startsWith('#!/bin/sh\n') &&
+                    lines[1] === PREPARE_COMMIT_MSG_MARKER &&
+                    lines[2] === PREPARE_COMMIT_MSG_BODY_MARKER;
+            if (!hookIsReaManaged &&
+                content.includes('rea:prepare-commit-msg') &&
+                lines[1] !== PREPARE_COMMIT_MSG_MARKER) {
+                hookMarkerMismatch = true;
+            }
+        }
+        catch {
+            hookIsReaManaged = false;
+        }
+    }
+    if (enabled) {
+        if (!hookExists) {
+            return {
+                label,
+                status: 'fail',
+                detail: 'attribution.co_author.enabled: true but .git/hooks/prepare-commit-msg is missing — ' +
+                    'run `rea init` to install the hook, or set enabled: false.',
+            };
+        }
+        if (!hookIsReaManaged) {
+            const reason = hookMarkerMismatch
+                ? 'marker mismatch (older rea or hand-edited)'
+                : 'no rea marker';
+            return {
+                label,
+                status: 'fail',
+                detail: `attribution.co_author.enabled: true but the prepare-commit-msg hook is foreign (${reason}) — ` +
+                    'remove the existing hook and re-run `rea init`, or set enabled: false.',
+            };
+        }
+        const name = (policyAttr?.name ?? '').trim();
+        const email = (policyAttr?.email ?? '').trim();
+        if (name.length === 0 || email.length === 0) {
+            const which = name.length === 0 ? 'name' : 'email';
+            return {
+                label,
+                status: 'fail',
+                detail: `attribution.co_author.enabled: true but ${which} is empty — ` +
+                    'the policy loader should have rejected this; if you are seeing this, edit ' +
+                    '.rea/policy.yaml and either set both name+email or set enabled: false.',
+            };
+        }
+        return {
+            label,
+            status: 'pass',
+            detail: `enabled — trailer: ${name} <${email}>`,
+        };
+    }
+    // enabled: false (or absent).
+    if (!hookExists) {
+        return { label, status: 'pass', detail: 'disabled (no hook installed — vanilla state)' };
+    }
+    if (hookIsReaManaged) {
+        return {
+            label,
+            status: 'pass',
+            detail: 'disabled (rea-managed hook present, runs as no-op)',
+        };
+    }
+    return {
+        label,
+        status: 'warn',
+        detail: 'foreign prepare-commit-msg hook present — rea would refuse to overwrite. ' +
+            'When you enable attribution.co_author.enabled, the existing hook must be ' +
+            'removed or migrated to a fragment first.',
+    };
+}
 function checkCommitMsgHook(baseDir) {
     const hookPath = path.join(baseDir, '.git', 'hooks', 'commit-msg');
     if (!fs.existsSync(hookPath)) {
@@ -779,7 +1028,7 @@ export function checkDelegationHookRegistered(baseDir) {
                 '(NOT `Task|Skill` — `TaskCreate`/`TaskList` are unrelated todo-list tools).',
         };
     }
-    const cmds = (group.hooks ?? []).map((h) => typeof h.command === 'string' ? h.command : '');
+    const cmds = (group.hooks ?? []).map((h) => (typeof h.command === 'string' ? h.command : ''));
     if (!cmds.some((c) => c.includes('delegation-capture.sh'))) {
         return {
             label,
@@ -967,7 +1216,7 @@ export async function checkDelegationRoundTrip(baseDir) {
  *
  * `activeForeign` always yields `fail` — a foreign hook bypassing the gate is a hard governance gap.
  */
-export function collectChecks(baseDir, codexProbeState, prePushState) {
+export function collectChecks(baseDir, codexProbeState, prePushState, options = {}) {
     const policyPath = reaPath(baseDir, POLICY_FILE);
     const registryPath = reaPath(baseDir, REGISTRY_FILE);
     const reaDirPath = path.join(baseDir, REA_DIR);
@@ -978,6 +1227,11 @@ export function collectChecks(baseDir, codexProbeState, prePushState) {
         checkAgentsPresent(baseDir),
         checkHooksInstalled(baseDir),
         checkSettingsJson(baseDir),
+        // 0.30.0 Class M — strict zod schema check of the full
+        // .claude/settings.json shape. Complements checkSettingsJson
+        // (matcher coverage) and checkDelegationHookRegistered (Agent|Skill
+        // wiring). Hard fail under `--strict`, warn by default.
+        checkSettingsSchema(baseDir, options.strict === true),
         // 0.29.0 — delegation-telemetry MVP wiring check. Separate from
         // checkSettingsJson because that check only validates the
         // existence of the Bash + Write|Edit|MultiEdit|NotebookEdit
@@ -991,6 +1245,10 @@ export function collectChecks(baseDir, codexProbeState, prePushState) {
     // other non-source-code directories that consume rea governance.
     if (isGitRepo(baseDir)) {
         checks.push(checkCommitMsgHook(baseDir));
+        // 0.30.0 attribution augmenter — only check when policy.attribution
+        // is declared. Vanilla installs without the block see no check
+        // (cleaner output for consumers who don't opt in).
+        checks.push(checkPrepareCommitMsgHook(baseDir));
         if (prePushState !== undefined) {
             checks.push(checkPrePushHook(prePushState));
         }
@@ -1203,7 +1461,9 @@ export async function runDoctor(opts = {}) {
     catch {
         prePushState = undefined;
     }
-    const checks = collectChecks(baseDir, probeState, prePushState);
+    const checks = collectChecks(baseDir, probeState, prePushState, {
+        strict: opts.strict === true,
+    });
     // G7: async fingerprint-store check. Kept out of `collectChecks` so the
     // existing sync contract stays intact for downstream consumers; appended
     // here so runDoctor surfaces it inline.

package/dist/cli/index.js

@@ -149,11 +149,13 @@ async function main() {
         .option('--metrics', 'also print a 7-day summary of Codex telemetry (G11.5)')
         .option('--drift', 'report drift vs. the install manifest (read-only; does not mutate)')
         .option('--smoke', 'also run the 0.29.0 delegation-signal round-trip (writes a probe `rea.delegation_signal` audit record and verifies chain integrity)')
+        .option('--strict', '0.30.0 Class M — promote settings.json schema warnings (zod parse failures, path traversal, missing rea hooks) to hard fail. Use in CI gates.')
         .action(async (opts) => {
         await runDoctor({
             ...(opts.metrics === true ? { metrics: true } : {}),
             ...(opts.drift === true ? { drift: true } : {}),
             ...(opts.smoke === true ? { smoke: true } : {}),
+            ...(opts.strict === true ? { strict: true } : {}),
         });
     });
     await program.parseAsync(process.argv);

package/dist/cli/init.js

@@ -9,6 +9,7 @@ import { copyArtifacts } from './install/copy.js';
 import { ensureReaGitignore } from './install/gitignore.js';
 import { canonicalSettingsSubsetHash, defaultDesiredHooks, mergeSettings, readSettings, writeSettingsAtomic, } from './install/settings-merge.js';
 import { installCommitMsgHook } from './install/commit-msg.js';
+import { installPrepareCommitMsgHook } from './install/prepare-commit-msg.js';
 import { installPrePushFallback } from './install/pre-push.js';
 import { CodexProbe } from '../gateway/observability/codex-probe.js';
 import { buildFragment, writeClaudeMdFragment } from './install/claude-md.js';
@@ -220,11 +221,56 @@ async function runWizard(options, targetDir, reagentPolicyPath, layeredBase, exi
         ...(existingPolicy?.commitHygieneRefuseAtCommits !== undefined
             ? { commitHygieneRefuseAtCommits: existingPolicy.commitHygieneRefuseAtCommits }
             : {}),
+        // 0.30.0 attribution augmenter — preserved across re-init OR
+        // seeded from the layered profile (every shipped profile pins
+        // `enabled: false`). Conditional spread so undefined → key omitted
+        // (the field is exact-optional).
+        ...attributionConfigSpread(layeredBase, existingPolicy),
         fromReagent,
         reagentPolicyPath,
         reagentNotices: [],
     };
 }
+/**
+ * Compute the attribution-augmenter config spread to inject into a
+ * partial `ResolvedConfig` literal. Returns `{}` when neither the
+ * existing on-disk policy nor the layered profile declared the
+ * augmenter — the policy writer then omits the block entirely so
+ * consumers who haven't seen 0.30.0 don't get a mystery YAML block.
+ *
+ * Returns `{ attributionCoAuthor: ... }` otherwise. Using a spread
+ * helper instead of a value-returning function lets `exactOptionalProperty
+ * Types` distinguish "omitted" from "explicitly undefined" — required
+ * by the strict tsconfig.
+ */
+function attributionConfigSpread(layered, existing) {
+    const preserved = existing?.attributionCoAuthor;
+    if (preserved !== undefined) {
+        return {
+            attributionCoAuthor: {
+                ...(preserved.enabled !== undefined ? { enabled: preserved.enabled } : {}),
+                ...(preserved.name !== undefined ? { name: preserved.name } : {}),
+                ...(preserved.email !== undefined ? { email: preserved.email } : {}),
+                ...(preserved.skipMerge !== undefined ? { skipMerge: preserved.skipMerge } : {}),
+            },
+        };
+    }
+    const fromProfile = layered.attribution?.co_author;
+    if (fromProfile === undefined)
+        return {};
+    return {
+        attributionCoAuthor: {
+            ...(fromProfile.enabled !== undefined ? { enabled: fromProfile.enabled } : {}),
+            ...(fromProfile.name !== undefined && fromProfile.name.length > 0
+                ? { name: fromProfile.name }
+                : {}),
+            ...(fromProfile.email !== undefined && fromProfile.email.length > 0
+                ? { email: fromProfile.email }
+                : {}),
+            ...(fromProfile.skip_merge !== undefined ? { skipMerge: fromProfile.skip_merge } : {}),
+        },
+    };
+}
 /**
  * G6 — Codex install-assist probe.
  *
@@ -408,6 +454,38 @@ function readExistingPolicyForPreservation(targetDir) {
             out.commitHygieneRefuseAtCommits = refuseAt;
         }
     }
+    // 0.30.0 attribution augmenter. Preserve every field the operator
+    // may have configured so re-running `rea init` doesn't silently
+    // revert an opt-in. Block AND inline forms agree at the parser
+    // layer.
+    const attribution = policy['attribution'];
+    if (attribution !== null && typeof attribution === 'object') {
+        const attr = attribution;
+        const coAuthor = attr['co_author'];
+        if (coAuthor !== null && typeof coAuthor === 'object') {
+            const ca = coAuthor;
+            const preserved = {};
+            let any = false;
+            if (typeof ca['enabled'] === 'boolean') {
+                preserved.enabled = ca['enabled'];
+                any = true;
+            }
+            if (typeof ca['name'] === 'string') {
+                preserved.name = ca['name'];
+                any = true;
+            }
+            if (typeof ca['email'] === 'string') {
+                preserved.email = ca['email'];
+                any = true;
+            }
+            if (typeof ca['skip_merge'] === 'boolean') {
+                preserved.skipMerge = ca['skip_merge'];
+                any = true;
+            }
+            if (any)
+                out.attributionCoAuthor = preserved;
+        }
+    }
     return out;
 }
 function readExistingInstalledAt(policyPath) {
@@ -484,6 +562,28 @@ function writePolicyYaml(targetDir, config, layered) {
             lines.push(`    - ${JSON.stringify(p)}`);
         }
     }
+    // 0.30.0 attribution augmenter — emit the block whenever the layered
+    // profile (or a preserved on-disk policy) declared it. We always emit
+    // a fully-explicit `enabled` so an operator reading the file can
+    // confirm the current state at a glance without falling back to
+    // schema defaults. Identity (name/email) is omitted when empty —
+    // operators opt in by hand-editing those two fields, which keeps
+    // the policy file diff-clean on profile re-init.
+    const attr = config.attributionCoAuthor;
+    if (attr !== undefined) {
+        lines.push(`attribution:`);
+        lines.push(`  co_author:`);
+        lines.push(`    enabled: ${attr.enabled === true ? 'true' : 'false'}`);
+        if (attr.name !== undefined && attr.name.length > 0) {
+            lines.push(`    name: ${JSON.stringify(attr.name)}`);
+        }
+        if (attr.email !== undefined && attr.email.length > 0) {
+            lines.push(`    email: ${JSON.stringify(attr.email)}`);
+        }
+        if (attr.skipMerge !== undefined) {
+            lines.push(`    skip_merge: ${attr.skipMerge ? 'true' : 'false'}`);
+        }
+    }
     // 0.18.1+ helixir #9: emit audit.rotation when the layered profile
     // declared it. Empty `rotation: {}` opts in to documented defaults
     // (50 MiB / 30 days); explicit values override.
@@ -741,6 +841,10 @@ export async function runInit(options) {
             ...(existingPolicy?.commitHygieneRefuseAtCommits !== undefined
                 ? { commitHygieneRefuseAtCommits: existingPolicy.commitHygieneRefuseAtCommits }
                 : {}),
+            // 0.30.0 attribution augmenter — preserved across re-init OR
+            // seeded from the layered profile. Same precedence as the
+            // wizard path above. Conditional spread for exact-optional.
+            ...attributionConfigSpread(layeredBase, existingPolicy),
             fromReagent,
             reagentPolicyPath,
             reagentNotices,
@@ -772,6 +876,12 @@ export async function runInit(options) {
     const mergeResult = mergeSettings(settings, desired);
     await writeSettingsAtomic(settingsPath, mergeResult.merged);
     const commitMsgResult = await installCommitMsgHook(targetDir);
+    // 0.30.0 attribution augmenter — install the prepare-commit-msg
+    // hook unconditionally. The hook is a no-op when
+    // policy.attribution.co_author.enabled !== true, so it is safe to
+    // ship under every profile; consumers opt in by editing their
+    // .rea/policy.yaml.
+    const prepareCommitMsgResult = await installPrepareCommitMsgHook(targetDir);
     const prePushResult = await installPrePushFallback({ targetDir });
     const fragmentInput = {
         policyPath: `.${path.sep}rea${path.sep}policy.yaml`.replace(/\\/g, '/'),
@@ -800,6 +910,14 @@ export async function runInit(options) {
         console.log(`  + ${path.relative(targetDir, commitMsgResult.gitHook)}`);
     if (commitMsgResult.huskyHook)
         console.log(`  + ${path.relative(targetDir, commitMsgResult.huskyHook)}`);
+    if (prepareCommitMsgResult.gitHook) {
+        const verb = prepareCommitMsgResult.refreshed === true ? '~' : '+';
+        console.log(`  ${verb} ${path.relative(targetDir, prepareCommitMsgResult.gitHook)} (attribution augmenter)`);
+    }
+    if (prepareCommitMsgResult.huskyHook) {
+        const verb = prepareCommitMsgResult.refreshed === true ? '~' : '+';
+        console.log(`  ${verb} ${path.relative(targetDir, prepareCommitMsgResult.huskyHook)} (attribution augmenter)`);
+    }
     if (prePushResult.written !== undefined) {
         const verb = prePushResult.decision.action === 'refresh' ? '~' : '+';
         console.log(`  ${verb} ${path.relative(targetDir, prePushResult.written)} (pre-push fallback)`);
@@ -828,6 +946,8 @@ export async function runInit(options) {
     }
     for (const w of commitMsgResult.warnings)
         warn(w);
+    for (const w of prepareCommitMsgResult.warnings)
+        warn(w);
     for (const w of prePushResult.warnings)
         warn(w);
     for (const n of config.reagentNotices)

package/dist/cli/install/prepare-commit-msg.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Install the husky `prepare-commit-msg` hook that drives the 0.30.0
+ * attribution augmenter.
+ *
+ * The hook itself is a stable POSIX-sh body sourced from the package's
+ * own `.husky/prepare-commit-msg`. `rea init` and `rea upgrade` copy it
+ * into `.husky/` and (when `core.hooksPath` is not configured at
+ * `.husky`) `.git/hooks/` as the belt-and-suspenders pair — mirroring
+ * the `installCommitMsgHook` strategy in `commit-msg.ts`.
+ *
+ * Foreign-hook conflict pattern: the 0.13.2 prepush prior art applies.
+ * If a foreign `prepare-commit-msg` exists (no rea marker, not the husky
+ * 9 indirection stub), we REFUSE to overwrite, surface the conflict via
+ * `rea doctor`, and recommend the `.husky/prepare-commit-msg.d/<NN>-name`
+ * extension-fragment migration path (TODO: wire fragment chaining if
+ * consumers demand it; not in 0.30.0 scope).
+ *
+ * Idempotency: the canonical body carries the `# rea:prepare-commit-msg v1`
+ * marker on line 2 and `# rea:augment-body-v1` on line 3. Re-running rea
+ * init / upgrade refreshes the file in-place whenever the marker matches;
+ * foreign hooks are left alone.
+ */
+/**
+ * Marker baked into every rea-installed prepare-commit-msg hook.
+ * Anchored on line 2 (immediately after the shebang) for classification.
+ * Bump the version suffix whenever the body semantics change so
+ * upgrades migrate cleanly.
+ *
+ * v1 — 0.30.0: first version of the augmenter hook.
+ */
+export declare const PREPARE_COMMIT_MSG_MARKER = "# rea:prepare-commit-msg v1";
+/**
+ * Body marker anchored on line 3. A foreign hook that carries the
+ * header marker as a comment but has an empty body (stubbed by a
+ * consumer) will NOT be classified as rea-managed because the body
+ * marker won't be on line 3. Both markers together close the
+ * classification question.
+ */
+export declare const PREPARE_COMMIT_MSG_BODY_MARKER = "# rea:augment-body-v1";
+export type PrepareCommitMsgClassification = {
+    kind: 'absent';
+} | {
+    kind: 'rea-managed';
+    version: string;
+} | {
+    kind: 'foreign';
+    reason: string;
+};
+/**
+ * Inspect `hookPath` and decide whether it is rea-authored or foreign.
+ * Strict: BOTH markers must appear on lines 2 + 3 in order. Substring
+ * matches deliberately rejected so a comment quoting the marker doesn't
+ * fool the classifier.
+ */
+export declare function classifyPrepareCommitMsgHook(hookPath: string): Promise<PrepareCommitMsgClassification>;
+export interface PrepareCommitMsgInstallResult {
+    gitHook?: string;
+    huskyHook?: string;
+    warnings: string[];
+    /**
+     * When the install is a refresh of an existing rea-managed body, this
+     * is true. Useful for upgrade messaging.
+     */
+    refreshed?: boolean;
+    /**
+     * When the install was skipped because a foreign hook is present.
+     * Surfaced separately so `rea doctor` can render the migration path.
+     */
+    skippedForeign?: boolean;
+}
+/**
+ * Install the prepare-commit-msg hook into the consumer project at
+ * `targetDir`. Refuses to stomp foreign hooks; refreshes rea-managed
+ * hooks in place. Best-effort: a missing `.husky/` directory simply
+ * skips the husky copy (git-hooks copy is sufficient for vanilla git).
+ *
+ * Foreign-hook conflict (the 0.13.2 pre-push prior art): we never
+ * overwrite a non-rea body. The caller surfaces the conflict to the
+ * operator; `rea doctor` flags the gap so the operator can decide
+ * whether to relocate their existing hook into a fragment, replace it
+ * with rea's body, or set `attribution.co_author.enabled: false`.
+ */
+export declare function installPrepareCommitMsgHook(targetDir: string): Promise<PrepareCommitMsgInstallResult>;