coherence

Coherence

Coherence — one name across npm slug, brand, and /coherence:* slash commands.

A Claude Code plugin that detects documentation drift (when code changes without updating its docs) and proposes surgical patches via a two-stage LLM pipeline. It runs as a set of Claude Code hooks + slash commands; team-distributable surfaces live as committed files under coherence/ (no backend, ever).

• Detects drift through PostToolUse signal capture + a SessionStart trickle scan; surfaces proposals on demand.
• Plans repairs via a Stage 1 canonical-selection LLM call (claude-sonnet-4-6).
• Writes patches via a Stage 2 patch-writer LLM call with deterministic validation: format → apply → change-class recount → line-count ratio → prompt injection → hallucination grep → asserts.
• Auto-applies patches in Graduated mode with a per-section trust gate; never auto-applies destructive or frontmatter changes.
• Validates documentation contracts via asserts: frontmatter with 8 engines (text-pattern + codebase-linked, including v1.0.1 Fix 8's symbol_exported for LIM-1 closure).
• Audits the corpus with a free-tier bundling report + flag-gated LLM cross-section consistency pass.
• Signs releases with Sigstore cosign keyless OIDC via GitHub Actions; verifiable via Rekor.

Install

claude plugin install coherence    # Anthropic plugin registry (canonical)

For local development:

git clone https://github.com/HUMBLEF0OL/coherence.git
cd coherence
npm install
npm run build

The plugin manifest is .claude-plugin/plugin.json.

Capabilities

Drift detection + repair

/coherence:status            # mode, buffer, costs, recent activity
/coherence:review            # run the Stop pipeline mid-session
/coherence:review --estimate # Stage 1 only — group/section count
/coherence:doctor            # probe host capabilities
/coherence:repair            # fix anchor collisions, state drift, trust orphans
/coherence:recover           # clear auto-disable sentinel, reset locks

Anchor format: HTML comment pairs in any Markdown file —

<!-- coherence:section id="install" -->
## Install

...

<!-- /coherence:section -->

GitHub-slug heading fallback with -1 / -2 disambiguation when an explicit id="..." is absent. Fenced code blocks are skipped during scan (R-18).

Modes (per-directory)

/coherence:graduate                       # global → Graduated
/coherence:graduate annotate docs/        # annotate mode for docs/
/coherence:graduate author                # author mode (signal detectors fire)
/coherence:graduate --revert              # → Observe
/coherence:graduate --status              # effective mode for cwd

Mode	Behaviour
Observe	Watch + propose for review; never auto-apply.
Annotate	Detect anchor-less Markdown; propose anchor placement (DD-069).
Author	Three signal detectors fire (bash repetition, file-creation patterns, agent corrections) and seed Author LLM proposals into the DD-065 quarantine boundary.
Graduated	Additive patches auto-apply; modifying patches gated by trust score ≥ 0.85; destructive + frontmatter always require confirmation.

Proposals (cross-the-boundary)

Net-new artifacts (skills, agents, slash commands, annotations) land in .claude/coherence/proposals/<kind>/<id>/. Nothing reaches user-owned paths (.claude/skills/, etc.) without an explicit cross-the-boundary write (DD-065 / SG-3 — token-gated, statically asserted by tests/security/v0.2/sg-3-no-out-of-quarantine-write.test.ts).

/coherence:propose-list
/coherence:propose-show <id>
/coherence:propose-accept <id>             # user-typed accept
/coherence:propose-accept <id> --rename    # suffix on collision
/coherence:propose-reject <id>
/coherence:propose-revert-acceptance <id>  # undo (DD-083)
/coherence:annotate docs/intro.md          # ad-hoc annotate proposal
/coherence:de-annotate docs/intro.md       # strip or graduate auto-annotations

Trust ladder

A per-developer, per-section accept/edit/revert event log at .claude/coherence/trust-ledger.json drives the auto-apply gate for modifying patches. The score is the DD-138 weighted accept rate with a 30-day half-life decay (ALPHA = 0.977):

numerator   = Σ ev.weight   × ALPHA^ageDays   (accept=+1, revert=−1, edit=0)
denominator = Σ ev.denWeight × ALPHA^ageDays   (accept=1,  revert=1,  edit=0.5)
score       = numerator / denominator           (0 when |denominator| < 0.001)

LRU-capped at 200 events/section, sorted ascending by _ts. Concurrent recordEvent calls are serialised by an in-process per-ledger mutex (M-LEDGER-1).