claude-code-governance

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

claude-code-governance

★ 9 Open GitHub ↗

Context Governance for Claude Code — hooks, skills, and automation framework for preventing context drift across sessions

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Context Governance Installer for Claude Code

Portable installer that sets up the full Context Governance architecture at the user level (`~/.claude/`).

## Quick Install

```bash
bash ~/.claude/governance-installer/install.sh
```

## Options

| Flag | Effect |
|---|---|
| `--core-only` | Install only 7 core governance skills (skip 5 extended toolkit skills) |
| `--force` | Overwrite existing files without prompting |
| `--dry-run` | Preview what would be installed (no changes) |
| `--no-claude-md` | Skip CLAUDE.md — keep your existing user instructions |
| `--uninstall` | Remove all governance files (backs up before removal) |

## What Gets Installed

### Hooks (11 scripts in `~/.claude/hooks/`)
| Event | Script | Purpose |
|---|---|---|
| SessionStart | `pre-session.sh` | Detects governance, triggers briefing |
| UserPromptSubmit | `pre-task.sh` | Governance lite check per message |
| PreToolUse (Edit/Write) | `governance-guard.sh` | Blocks protected-doc edits without success token |
| PreToolUse (Edit/Write) | `pre-write.sh` | Impact map before file changes |
| PostToolUse (Edit/Write) | `post-milestone.sh` | State update after milestones |
| TaskCompleted | `check-full-finish.sh` | Warns about uncommitted changes |
| Stop | `end-session.sh` | Session-end handoff |

### Core Skills (7)
- **bootstrapper** — Loads relevant project context for session briefing
- **context-governance** — Audits context file hygiene (lite + full modes)
- **evidence-debugger** — Root-cause analysis with confidence grading
- **impact-safe-executor** — Pre-write impact map, scope enforcement
- **init-governance** — One-time project scaffold for governance structure
- **live-state-orchestrator** — Keeps PLAN/MEMORY/HANDOFF in sync
- **parallel-session-merge** — Reconciles multi-agent parallel work

### Extended Skills (5, skipped with `--core-only`)
- **plan-and-execute** — Multi-agent planning pipeline
- **qa-sec** — QA + Security audit suite
- **multi-agents** — Orchestrated agent teams
- **full-finish** — Universal post-task release pipeline
- **enable-remote-code** — Remote control for Claude Code sessions

### Docs (2 guides in `~/.claude/docs/`)
- **GOVERNANCE-AGENT-GUIDE.md** — Structured guide for LLM implementation
- **GOVERNANCE-HUMAN-GUIDE.md** — Human-readable governance reference

### Configuration
- **CLAUDE.md** — User-level instructions (session protocol, security, governance rules)
- **settings.json** — Hook registrations merged into existing settings

## Portability

To install on another machine:
1. Copy the entire `~/.claude/governance-installer/` directory
2. Run `bash ~/.claude/governance-installer/install.sh`

All paths use `~/` notation — works on Windows (Git Bash/MSYS2), macOS, and Linux.

## Kill Switch

Disable all governance hooks without uninstalling:
```bash
export GOVERNANCE_HOOKS=0
```

## Uninstall

```bash
bash ~/.claude/governance-installer/install.sh --uninstall
```
Backs up all files before removal. CLAUDE.md is NOT removed (manual decision).

## Testing the hooks (sandbox, never touches your real ~/.claude)

```bash
bash bundle/hooks/governance/tests/test-session-state.sh
bash bundle/hooks/governance/tests/test-payload-root.sh
```

## Rolling out an update to a client machine

```bash
git pull
bash install.sh --force          # backs up ~/.claude/hooks, skills, docs first
bash bundle/hooks/governance/tests/test-session-state.sh
bash verify.sh
```

## Changelog

- **2026-08-17 — the `$PWD` pattern is gone from all seven hooks.** The remaining four
  (`canonical-cwd-check.sh`, `plan-gate.sh`, `parallel-import.sh`, `pre-done.sh`) now resolve the
  project from the payload as well. `canonical-cwd-check.sh` needed its own treatment: it is
  deliberately **standalone** — kill switch only, no `_common.sh` — so that it still works when the
  rest of the framework does not, and that property was worth preserving, so it extracts the
  payload `cwd` inline instead of gaining a dependency. It is also the one hook where drift is
  worse than a lost record: it asks *"is this session sitting on the canonical copy?"*, so judging
  the wrong directory either cries wolf or — far worse — stays **silent while the session really is
  on a stale duplicate**, which is the failure that already cost this toolchain a corrupted
  cloud-synced `.git` once. Tests 9-11 pin all three of its signals: no false alarm from outside the
  project, the wrong-copy warning still fires, and the tombstone is found via the session's
  directory. Suite now 11/11; `test-session-state.sh` unchanged at 23/23.
  **Four of these seven still run nowhere** — see the entry below. Anchoring them is what makes
  wiring them a one-line decision later instead of a fix-then-wire project.
- **2026-08-17 — `pre-session.sh` / `pre-task.sh` anchored too, and an audit of which hooks are
  actually wired.** Same `$PWD` defect as §18, in the two hooks that gate the *start* of everything:
  from a directory holding a `CLAUDE.md` but no manifest — the exact shape of `~/.claude` —
  `pre-session.sh` announced *"Ungoverned project detected. Run `/init-governance` NOW"* about a
  fully governed repo, and `pre-task.sh` skipped enforcement outright. Both now call the new
  `gov_prime_payload`, which reads stdin **once**, exports the cache so subshells stop re-reading a
  drained stream (`gov_state_file` was consuming the payload inside `$( )`, leaving every later
  read empty), and resolves `GOV_PROJECT_ROOT`. Tests 6-8 in `tests/test-payload-root.sh`, incl. the
  negative control that an ungoverned directory is still called ungoverned.
  **The audit is the bigger finding:** of the seven hooks carrying this pattern, only
  `pre-session.sh` and `pre-task.sh` are registered on any event at all. `canonical-cwd-check.sh`,
  `plan-gate.sh`, `parallel-import.sh` and `pre-done.sh` **run nowhere** — every `settings.json`
  mention of them is a permissions-allowlist line, and `pre-done.sh` appears in `post-milestone.sh`
  only inside a comment. `canonical-cwd-check.sh` is the guard against working on a stale duplicate
  copy, and project docs describe it as enforcing that invariant at SessionStart; it does not.
  Wiring them is a behaviour change, not a bug fix, so it is left as an explicit decision.
- **2026-08-17 — `sync-governance-copies.sh` mirrors, it never RESURRECTS; and it is finally wired.**
  The script was written to keep the 4 copies of the governance code in step, but it **was never
  registered as a hook** — the only mention of it in `settings.json` was a permissions allowlist
  line. It had therefore never run once, which is why the mirrors drift. Before wiring it up, two
  `mkdir -p` calls had to go: the skills targets (and the GoldB-Agent hooks target) created the
  destination when it was absent, so editing any user-level skill would have **re-created shadow
  copies that had been deliberately deleted** — on 2026-08-17 three of them (`wa-cc-bridge`,
  `whatsapp`, `wa-cc-poll`) were removed from two repos precisely because a project-level
  `.claude/skills/<x>` shadows the user-level original, and two had already drifted. A deletion is a
  decision; an auto-sync that silently undoes it is the defect class this framework exists to catch.
  Now: refresh a mirror that exists, leave a removed one removed. The gate is the individual skill's
  directory, not the `skills/` root, so an existing root cannot smuggle in a new shadow copy.
  Register it on `PostToolUse` (`Edit|Write|MultiEdit|NotebookEdit`) alongside `post-milestone.sh`.
- **2026-08-17 — hooks judge the project of the EDIT, not their own `$PWD` (Agent Guide §18).**
  Writes made while a session's shell stood outside the project root were **silently dropped** from
  the session change log. Two independent `$PWD` dependencies in `post-milestone.sh`: a relative
  `[ ! -f "docs/context/CONTEXT-MANIFEST.md" ]` test, and `gov_role_guard SOURCE` →
  `gov_detect_role` → `gov_find_project_root`, whose upward walk finds the **user-level**
  `~/.claude/CLAUDE.md`, calls it "the project", sees no `.git` beside it and reports `DEPLOYMENT`.
  Running a test suite out of `~/.claude/skills/<x>` was enough to trigger both. Visible symptom was
  a false BLOCK at close ("HANDOFF.md was not refreshed" when it had been); the dangerous direction
  is the inverse — the same omission under-counts `SESSION_WRITES`, and `end-session.sh` only fires
  at `>= 3`, so **a session could close with no handoff and the gate would stay quiet**. New
  `gov_payload_root <payload>` + `gov_is_governed <root>` in `_common.sh` resolve the project from
  the hook payload (`cwd` → `file_path` → `$PWD` walk, with a regex fallback when strict JSON
  parsing fails), and `gov_detect_role` now honours `GOV_PROJECT_ROOT`. Regression test:
  `tests/test-payload-root.sh` (5 checks, incl. a negative control that an ungoverned edit is still
  skipped). **Still carrying the same pattern and NOT changed here:** `parallel-import.sh:17`,
  `plan-gate.sh:24`, `pre-done.sh:19`, `pre-session.sh:183,186`, `pre-task.sh:33,39`,
  `canonical-cwd-check.sh:56` — each gates a different lifecycle stage and needs its own test
  before being touched.
- **2026-08-16 — session-scoped state (Agent Guide §17).** Per-session state dirs
  (`~/.claude/logs/sessions/<sid>/`), crash-vs-parallel detection at SessionStart, `GOV_DRY_RUN=1`
  for every state-mutating hook, `_common.sh` primes the stdin payload once (`gov_hook_input`),
  `sync-governance-copies.sh` mirrors `docs/*.md`, `end-session.sh` pulls (`--rebase`) before pushing
  and stages only the queued files, drift advisory live-vs-bundle, sandbox test harness (23 checks).
- **2026-08-15 — parallel-session awareness (Agent Guide §16).** Detection signals + git rules
  when two Claude sessions share one working tree; `pre-session.sh` 3-way union.

claude-code-governance

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README