diff --git a/agent.yaml b/agent.yaml index 035db0637..829ab76f9 100644 --- a/agent.yaml +++ b/agent.yaml @@ -36,6 +36,7 @@ skills: - codebase-onboarding - coding-standards - compose-multiplatform-patterns + - config-health - configure-ecc - contract-first - content-engine diff --git a/manifests/install-modules.json b/manifests/install-modules.json index f1249b935..09fded654 100644 --- a/manifests/install-modules.json +++ b/manifests/install-modules.json @@ -951,6 +951,23 @@ "cost": "medium", "stability": "stable" }, + { + "id": "config-health", + "kind": "skills", + "description": "Runtime configuration integrity monitoring for Claude Code (Claude-only hooks: SessionStart/PreToolUse).", + "paths": [ + "skills/config-health", + "scripts/config-health.py" + ], + "targets": [ + "claude", + "claude-project" + ], + "dependencies": [], + "defaultInstall": false, + "cost": "light", + "stability": "beta" + }, { "id": "docs-ja-jp", "kind": "docs", diff --git a/manifests/install-profiles.json b/manifests/install-profiles.json index 15e429943..6f033a270 100644 --- a/manifests/install-profiles.json +++ b/manifests/install-profiles.json @@ -97,7 +97,8 @@ "devops-infra", "machine-learning", "supply-chain-domain", - "document-processing" + "document-processing", + "config-health" ] } } diff --git a/package.json b/package.json index 6e28aa5da..9fe11e54d 100644 --- a/package.json +++ b/package.json @@ -88,6 +88,7 @@ "scripts/catalog.js", "scripts/ci/scan-supply-chain-iocs.js", "scripts/ci/supply-chain-advisory-sources.js", + "scripts/config-health.py", "scripts/consult.js", "scripts/auto-update.js", "scripts/claw.js", @@ -161,6 +162,7 @@ "skills/code-tour/", "skills/coding-standards/", "skills/compose-multiplatform-patterns/", + "skills/config-health/", "skills/configure-ecc/", "skills/contract-first/", "skills/connections-optimizer/", diff --git a/scripts/config-health.py b/scripts/config-health.py new file mode 100644 index 000000000..9bd4c35cd --- /dev/null +++ b/scripts/config-health.py @@ -0,0 +1,296 @@ +#!/usr/bin/env python3 +""" +config-health — runtime configuration integrity monitoring for Claude Code. + +Deterministic, read-only, non-blocking monitor. Complements delivery-gate: +delivery-gate blocks at session end (missing growth-log = not retroactively +fixable); config-health warns during the session (config drift = fixable). + +Modes: + --startup SessionStart: audit hook wiring, rule references, guard staleness. + --pretool PreToolUse: re-verify matched hook scripts exist and are wired. + Reads tool_use JSON on stdin but NEVER echoes it to stdout. + --check Manual: tri-color health overview on stdout. + +Contract (from the ECC config-health skill): + - read-only — never writes to disk + - non-blocking — always exits 0, even on malformed input + - no leak — --pretool never prints raw hook input, commands, or secrets + - deterministic — same inputs → same findings (missing script = fact, not heuristic) + +Config path resolution: + - user settings: $CONFIG_HEALTH_USER_HOME/.claude/settings.json + (defaults to ~/.claude/settings.json) + - project settings: $CLAUDE_PROJECT_DIR/.claude/settings.json + (defaults to /.claude/settings.json) + +Install: cp to ~/.claude/scripts/config-health.py +Wire (in your settings.json hooks — merge, don't replace): + SessionStart: python3 ~/.claude/scripts/config-health.py --startup + PreToolUse: python3 ~/.claude/scripts/config-health.py --pretool +""" +from __future__ import annotations + +import json +import os +import re +import sys + +# Windows GBK console can't encode emoji — force UTF-8 on stdout/stderr. +# This script's warnings may be captured by hook logs, so reconfigure to +# prevent UnicodeEncodeError on non-UTF-8 consoles. +try: + sys.stdout.reconfigure(encoding='utf-8', errors='replace') + sys.stderr.reconfigure(encoding='utf-8', errors='replace') +except (AttributeError, OSError): + pass # Python <3.7 or stdout is not a TTY/stream + + +WARN_PREFIX = '[config-health] WARN: ' + +# Sessions of rule-health history to look back for guard staleness. +STALENESS_WINDOW = 5 +# Minimum tool calls for a session to be "complex enough" to expect rule markers. +MIN_TOOL_CALLS_FOR_CHECK = 5 +# Rule-health log written by the earlier Stop-hook monitor (read-only here). +RULE_HEALTH_LOG = '.claude/session-data/rule-health.jsonl' +# Metadata keys in each rule-health record, not rule counters. +NON_RULE_KEYS = {'ts', 'date', 'time', 'tool_calls', 'edits'} + +# Matches a script path in a hook command: ~/.claude/scripts/x.py, scripts/x.js, +# C:/path/x.py, ./hooks/x.py. Misses inline shell one-liners, which is fine — +# we only audit references that look like files on disk. +SCRIPT_TOKEN = re.compile(r'([^\s"\']+\.(?:py|js|mjs|cjs|sh))') + + +def resolve_dirs(): + """Return (user_home, project_dir) honoring env overrides for determinism.""" + user_home = os.environ.get('CONFIG_HEALTH_USER_HOME') or os.path.expanduser('~') + project_dir = os.environ.get('CLAUDE_PROJECT_DIR') or os.getcwd() + return user_home, project_dir + + +def read_text(path): + """Read a file defensively; return None on any read/decode error.""" + if not os.path.exists(path): + return None + try: + with open(path, 'r', encoding='utf-8') as f: + return f.read() + except (OSError, UnicodeDecodeError): + return None + + +def read_json(path): + """Parse a JSON file defensively; return None if missing or malformed.""" + text = read_text(path) + if text is None: + return None + try: + return json.loads(text) + except (ValueError, TypeError): + return None + + +def resolve_script_path(raw, project_dir): + """Turn a token from a hook command into an absolute path. + + `~` resolves against CONFIG_HEALTH_USER_HOME when set (the same override + used for the user settings path), else the real home — so tests stay + deterministic without affecting real users. + """ + if raw.startswith('~'): + override = os.environ.get('CONFIG_HEALTH_USER_HOME') + if override: + return os.path.join(override, raw[1:].lstrip('/\\')) + return os.path.expanduser(raw) + if os.path.isabs(raw): + return raw + return os.path.join(project_dir, raw) + + +def iter_hook_commands(settings): + """Yield (event, command) for every command hook in a parsed settings.json. + + Handles both the grouped form + {"hooks": {"PreToolUse": [{"matcher": "...", "hooks": [{"command": ...}]}]}} + and the flat form + {"hooks": {"PreToolUse": [{"command": ...}]}}. + """ + if not isinstance(settings, dict): + return + hooks = settings.get('hooks') + if not isinstance(hooks, dict): + return + for event, groups in hooks.items(): + if not isinstance(groups, list): + continue + for group in groups: + if not isinstance(group, dict): + continue + inner = group.get('hooks') + if isinstance(inner, list): + for hook in inner: + if isinstance(hook, dict) and isinstance(hook.get('command'), str): + yield event, hook['command'] + elif isinstance(group.get('command'), str): + yield event, group['command'] + + +def audit_hook_wiring(settings, project_dir): + """Verify every script referenced by a hook command exists on disk. + + A referenced-but-missing script is a fact, not a heuristic — this is the + core deterministic check. Never prints the full command (may hold secrets); + only the missing path is reported. + """ + findings = [] + for event, command in iter_hook_commands(settings): + for token in SCRIPT_TOKEN.findall(command): + path = resolve_script_path(token, project_dir) + if not os.path.exists(path): + findings.append( + f'hook "{event}" references missing script: {token}' + ) + return findings + + +def audit_rule_references(project_dir): + """Verify rule files referenced by CLAUDE.md exist on disk.""" + findings = [] + for base in ('CLAUDE.md', os.path.join('.claude', 'CLAUDE.md')): + content = read_text(os.path.join(project_dir, base)) + if content is None: + continue + for ref in re.finditer(r'(?:\.claude/)?rules/[A-Za-z0-9_.-]+\.md', content): + rel = ref.group(0) + fp = os.path.join(project_dir, rel) + if not os.path.exists(fp): + findings.append(f'CLAUDE.md references missing rule file: {rel}') + return findings + + +def audit_guard_staleness(user_home): + """Flag rules that stopped firing in recent sessions. + + Only fires when a rule-health.jsonl log exists (written by the earlier + Stop-hook monitor). No log → no staleness judgment (avoids false positives). + """ + log_path = os.path.join(user_home, RULE_HEALTH_LOG) + content = read_text(log_path) + if content is None: + return [] + + records = [] + for line in content.splitlines(): + line = line.strip() + if not line: + continue + try: + records.append(json.loads(line)) + except (ValueError, TypeError): + continue + if not records: + return [] + + recent = records[-STALENESS_WINDOW:] + if len(recent) < STALENESS_WINDOW: + return [] # Not enough history yet + + rule_keys = set() + for rec in recent: + rule_keys.update(k for k in rec if k not in NON_RULE_KEYS) + + findings = [] + for rule in sorted(rule_keys): + complex_sessions = [ + rec for rec in recent if rec.get('tool_calls', 0) >= MIN_TOOL_CALLS_FOR_CHECK + ] + if not complex_sessions: + continue + if all(rec.get(rule, 0) == 0 for rec in complex_sessions): + findings.append( + f'rule "{rule}" last fired {STALENESS_WINDOW}+ sessions ago → may be dead' + ) + return findings + + +def run_startup_audit(user_home, project_dir): + """SessionStart audit: hook wiring + rule references + guard staleness.""" + findings = [] + + user_settings = read_json(os.path.join(user_home, '.claude', 'settings.json')) + project_settings = read_json(os.path.join(project_dir, '.claude', 'settings.json')) + + # Both settings may be absent or malformed — each is handled independently + # and never blocks. A malformed file yields no findings (nothing to audit) + # rather than a crash. + if user_settings is not None: + findings.extend(audit_hook_wiring(user_settings, project_dir)) + if project_settings is not None: + findings.extend(audit_hook_wiring(project_settings, project_dir)) + + findings.extend(audit_rule_references(project_dir)) + findings.extend(audit_guard_staleness(user_home)) + + return findings + + +def startup_mode(): + user_home, project_dir = resolve_dirs() + findings = run_startup_audit(user_home, project_dir) + for finding in findings: + print(WARN_PREFIX + finding) + # Non-blocking by contract: never gate on process monitoring. + sys.exit(0) + + +def pretool_mode(): + # Consume tool_use JSON without ever writing it to stdout. We only need the + # fact that a hook fired, not its contents. Raw hook input / secrets are + # never echoed — enforced by the hook-contract tests. + sys.stdin.read() + + user_home, project_dir = resolve_dirs() + findings = [] + + user_settings = read_json(os.path.join(user_home, '.claude', 'settings.json')) + project_settings = read_json(os.path.join(project_dir, '.claude', 'settings.json')) + if user_settings is not None: + findings.extend(audit_hook_wiring(user_settings, project_dir)) + if project_settings is not None: + findings.extend(audit_hook_wiring(project_settings, project_dir)) + + # PreToolUse keeps stdout clean — warnings go to stderr so a non-empty + # stdout can never be misread as a block/allow decision. + for finding in findings: + print(WARN_PREFIX + finding, file=sys.stderr) + sys.exit(0) + + +def check_mode(): + """Manual tri-color overview. Read-only.""" + user_home, project_dir = resolve_dirs() + findings = run_startup_audit(user_home, project_dir) + if findings: + print('config-health: 🟡 attention') + for finding in findings: + print(' ' + WARN_PREFIX + finding) + else: + print('config-health: 🟢 normal — hook wiring, rules, and guards OK') + sys.exit(0) + + +def main(): + args = sys.argv[1:] + if '--pretool' in args: + pretool_mode() + elif '--check' in args: + check_mode() + else: + # --startup (also the default): least surprising for a SessionStart hook. + startup_mode() + + +if __name__ == '__main__': + main() diff --git a/skills/config-health/SKILL.md b/skills/config-health/SKILL.md new file mode 100644 index 000000000..536f19e0b --- /dev/null +++ b/skills/config-health/SKILL.md @@ -0,0 +1,71 @@ +--- +name: config-health +description: Runtime configuration integrity monitoring for Claude Code. Detects config drift, rule staleness, and hook wiring gaps during sessions. Complements delivery-gate with session-duration soft monitoring. +metadata: + origin: ECC +--- + +# Config Health + +A real-time monitoring layer. delivery-gate blocks at session end; config-health catches problems during the session — when cheap to fix. + +## When to Activate + +- After installing delivery-gate and wanting defense in depth +- When hooks silently stop firing +- When config rules accumulate but you're unsure which still work +- At session startup for config integrity scan +- Before high-risk Edit/Write operations + +## How It Works + +Session Start → config-health scans rules/hooks (soft warnings, never blocks) +Session Work → config-health monitors hook wiring (PreToolUse guard) +Session End → delivery-gate verifies (hard block, exit 2) + +Boundary: "Can this be fixed retroactively?" Config drift → config-health warns. Missing growth-log → delivery-gate blocks (hard exit 2). + +## What It Monitors + +1. Rule Health: scans rules, checks hook wiring, detects dead rules +2. Hook Wiring Audit: verifies scripts exist and are wired before high-risk calls +3. Guard Script Staleness: checks maintenance windows + +## Examples + +Catching silent hook failure: +SessionStart → health-check.py referenced in 3 docs, wired 0 times → WARN: dead references + +PreToolUse guard: +three-questions-guard.py: referenced in BODY.md, exists on disk, wired in settings.json → Allow + +Rule staleness: +rule "双池强制触发" last fired 15 sessions ago → WARN: may be dead + +## Install + +**ECC users:** install the `config-health` module (`npx ecc-install --modules config-health` or the `full` profile). It is a **Claude-only** module (SessionStart/PreToolUse hooks) — it does not target other harnesses, so it stays isolated from shared 13-harness modules. + +**Standalone:** copy `scripts/config-health.py` to `~/.claude/scripts/config-health.py` and verify it exists before enabling. +**Important:** Merge these hook entries into your existing `hooks` object — do not replace it, or you will lose hooks like delivery-gate. + +```json +{ + "hooks": { + "SessionStart": [{"hooks": [{"type": "command", "command": "python3 ~/.claude/scripts/config-health.py --startup", "timeout": 5000}]}], + "PreToolUse": [{"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "python3 ~/.claude/scripts/config-health.py --pretool", "timeout": 3000}]}] + } +} +``` + +## Design Principles + +1. Never block on process monitoring — config-health warns; delivery-gate blocks +2. Check what delivery-gate can't — config behavior vs filesystem state +3. Zero false positives on hook wiring — missing script = fact, not heuristic + +## Files + +| File | Purpose | Hook | +|------|---------|------| +| scripts/config-health.py | Rule health, hook audit, staleness | SessionStart + PreToolUse | diff --git a/tests/hooks/config-health.test.js b/tests/hooks/config-health.test.js new file mode 100644 index 000000000..c65d24488 --- /dev/null +++ b/tests/hooks/config-health.test.js @@ -0,0 +1,178 @@ +/** + * Hook-contract tests for scripts/config-health.py + * + * Verifies the contract haelyra asked for: present & missing scripts, + * malformed & absent settings, absent rule dirs, and warning behavior — + * every diagnostic must stay non-blocking (exit 0), exit cleanly, and never + * echo raw hook input or secrets. + * + * Run with: node tests/hooks/config-health.test.js + * (also picked up by `node tests/run-all.js`) + */ + +'use strict'; + +const assert = require('assert'); +const { spawnSync } = require('child_process'); +const fs = require('fs'); +const os = require('os'); +const path = require('path'); + +const SCRIPT = path.join(__dirname, '..', '..', 'scripts', 'config-health.py'); + +// Resolve a working python. On Windows, missing interpreters surface as +// status 9009 (not a spawn error), so probe both name and exit status. +function resolvePython() { + const probe = (name) => { + const r = spawnSync(name, ['--version'], { stdio: 'ignore' }); + return !r.error && r.status === 0; + }; + if (process.env.CONFIG_HEALTH_PYTHON) return process.env.CONFIG_HEALTH_PYTHON; + if (probe('python3')) return 'python3'; + if (probe('python')) return 'python'; + throw new Error('No python interpreter found (tried CONFIG_HEALTH_PYTHON, python3, python)'); +} + +const PYTHON = resolvePython(); + +// ---- helpers --------------------------------------------------------------- + +function test(name, fn) { + try { + fn(); + console.log(` ✓ ${name}`); + return true; + } catch (err) { + console.log(` ✗ ${name}`); + console.log(` Error: ${err.message}`); + return false; + } +} + +function makeFixture() { + // Returns { home, proj, root } — a throwaway sandbox under os.tmpdir(). + const root = fs.mkdtempSync(path.join(os.tmpdir(), 'config-health-')); + const home = path.join(root, 'home'); + const proj = path.join(root, 'proj'); + fs.mkdirSync(path.join(home, '.claude'), { recursive: true }); + fs.mkdirSync(path.join(proj, '.claude'), { recursive: true }); + return { root, home, proj }; +} + +function run(mode, { home, proj }, stdin = '') { + return spawnSync(PYTHON, [SCRIPT, mode], { + env: { ...process.env, CONFIG_HEALTH_USER_HOME: home, CLAUDE_PROJECT_DIR: proj }, + input: stdin, + encoding: 'utf8', + }); +} + +function writeSettings(home, content) { + fs.writeFileSync(path.join(home, '.claude', 'settings.json'), content, 'utf8'); +} + +const HOOKS_JSON = (scriptPath) => JSON.stringify({ + hooks: { + SessionStart: [{ hooks: [{ type: 'command', command: `python3 ${scriptPath} --start`, timeout: 5000 }] }], + PreToolUse: [{ matcher: 'Edit|Write', hooks: [{ type: 'command', command: `python3 ${scriptPath} --pretool`, timeout: 3000 }] }], + }, +}); + +// ---- suite ----------------------------------------------------------------- + +function runTests() { + console.log('\n=== Testing config-health.py hook contract ===\n'); + let passed = 0; + let total = 0; + + const t = (name, fn) => { total += 1; if (test(name, fn)) passed += 1; }; + + // Absent settings → clean, non-blocking. + t('startup with absent settings exits 0 and is silent', () => { + const fx = makeFixture(); + const r = run('--startup', fx); + assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`); + assert.strictEqual(r.stdout.trim(), '', 'expected no findings with no settings'); + }); + + // Missing referenced script → WARN, still exit 0 (never blocks). + t('startup warns on a missing referenced script but exits 0', () => { + const fx = makeFixture(); + writeSettings(fx.home, HOOKS_JSON('~/.claude/scripts/nope-guard.py')); + const r = run('--startup', fx); + assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`); + assert.ok(r.stdout.includes('missing script'), 'expected a missing-script warning'); + assert.ok(r.stdout.includes('nope-guard.py'), 'warning should name the missing file'); + }); + + // Script present → no warning. + t('startup is silent when referenced scripts exist', () => { + const fx = makeFixture(); + fs.mkdirSync(path.join(fx.home, '.claude', 'scripts'), { recursive: true }); + fs.writeFileSync(path.join(fx.home, '.claude', 'scripts', 'ok-guard.py'), '', 'utf8'); + writeSettings(fx.home, HOOKS_JSON('~/.claude/scripts/ok-guard.py')); + const r = run('--startup', fx); + assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`); + assert.ok(!r.stdout.includes('missing script'), 'expected no missing-script warning'); + }); + + // Malformed settings → clean, non-blocking, no crash. + t('startup tolerates malformed settings (exit 0, no crash)', () => { + const fx = makeFixture(); + writeSettings(fx.home, '{ not valid json'); + const r = run('--startup', fx); + assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`); + assert.ok(!/Traceback|Error/.test(r.stdout + r.stderr), 'should not crash'); + }); + + // Absent rule dir / absent CLAUDE.md → clean. + t('startup with absent rules dir and CLAUDE.md is clean', () => { + const fx = makeFixture(); // proj has .claude but no CLAUDE.md, no rules/ + const r = run('--startup', fx); + assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`); + assert.strictEqual(r.stdout.trim(), '', 'expected no findings'); + }); + + // Dead rule reference → WARN, exit 0. + t('startup warns on CLAUDE.md referencing a missing rule file', () => { + const fx = makeFixture(); + fs.writeFileSync(path.join(fx.proj, 'CLAUDE.md'), 'see rules/ghost.md\n', 'utf8'); + const r = run('--startup', fx); + assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`); + assert.ok(r.stdout.includes('missing rule file'), 'expected a dead-rule warning'); + }); + + // --pretool must NEVER echo stdin (raw hook input / secrets). + t('pretool never echoes raw hook input or secrets to stdout', () => { + const fx = makeFixture(); + const secret = 'ghp_FakeSecretToken_12345'; + const input = JSON.stringify({ tool_name: 'Write', tool_input: { file_path: 'x.md' }, api_key: secret }); + const r = run('--pretool', fx, input); + assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`); + assert.strictEqual(r.stdout, '', 'stdout must be empty — stdin must not be echoed'); + assert.ok(!(r.stdout + r.stderr).includes(secret), 'secret must not appear anywhere'); + }); + + // --pretool with malformed stdin → clean exit. + t('pretool tolerates malformed stdin (exit 0)', () => { + const fx = makeFixture(); + const r = run('--pretool', fx, 'garbage{{{{'); + assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`); + assert.ok(!/Traceback/.test(r.stdout + r.stderr), 'should not crash'); + }); + + // Warning behavior: pretool warnings go to stderr, stdout stays clean. + t('pretool warns on stderr, keeps stdout clean, stays non-blocking', () => { + const fx = makeFixture(); + writeSettings(fx.home, HOOKS_JSON('~/.claude/scripts/missing-again.py')); + const r = run('--pretool', fx, '{"tool_name":"Edit"}'); + assert.strictEqual(r.status, 0, `expected exit 0, got ${r.status}`); + assert.strictEqual(r.stdout, '', 'stdout must stay empty in pretool mode'); + assert.ok(r.stderr.includes('missing script'), 'warning should surface on stderr'); + }); + + console.log(`\n ${passed}/${total} passed`); + if (passed !== total) process.exit(1); +} + +runTests();