Back to Blog

Claude Code - Lighthouse: Making Multi-File Changes Safe, Transparent, and Reversible

• DevTools • By Raja Patnaik

The following specification describes a new Claude Code feature I call Lighthouse that makes large codebase edits transparent and safe: the agent states intent in a Change Contract, shows blast radius via an Impact Map, and executes work in Checkpoints with snapshots and one‑click rollbacks.

Table of contents

Problem

Claude Code is by far my favorite coding assistant. Yet even after countless hours of working with it, I am hesitant to approve complex code changes. These hesitations are amplified for larger teams with larger codebases:

  • Opacity - reviewers see diffs but not intent or invariants.
  • Unknown blast radius - large edits touch code outside the immediate area.
  • Rollback anxiety - if something breaks in step 3 of 6, recovery is slow and manual.

Lighthouse addresses this with the following features:

  1. Change Contract - a machine‑readable spec of intent, impact, tests, budgets, and rollback plan.
  2. Impact Map - an interactive repo graph that explains why files/modules are in scope, with confidence metrics.
  3. Checkpoints - stepwise execution with snapshots (code, env, logs) and one‑click rollback.

Goals & Non-Goals

Goals

  • Raise trust in multi‑file edits (higher first‑pass CI pass rate and review acceptance).
  • Shorten review time for >5‑file PRs by providing intent and blast‑radius visualization.
  • Make failure cheap via consistent snapshots and rollbacks.

Non‑Goals

  • Auto‑merging without human review.
  • Replacing Git/CI/test frameworks.
  • Perfect static analysis; we surface confidence and allow human overrides.

End-to-End UX

Happy path

  1. claude plan "migrate pricing module to v2 calculator"

    • Claude drafts a Change Contract and renders the Impact Map panel.

  2. The user reviews and edits: invariants, excluded modules, required checkpoints, budgets.

  3. Click Start. Claude creates a work branch and Checkpoint 0 (snapshot).

  4. Claude executes Step 1 → runs scoped tests → creates Checkpoint 1.

  5. Repeats for steps 2…N until Pre‑PR Checkpoint is green.

  6. Claude opens a PR with Contract, Map, and Checkpoint Report attached.

  7. Reviewer approves; merge; artifacts are archived per policy.

Failure path: If tests fail at Step 3, policy may auto‑pause; user can Fix & Continue or Rollback to Checkpoint 2.

Artifacts

Change Contract

A machine‑readable YAML (and JSON) that captures intent, scope, tests, budgets, and rollback strategy.

id: cc-2025-09-01-00123
title: "Migrate pricing module to v2 calculator"
version: 1
author: "@sara"
created_at: "2025-09-01T10:15:22Z"
intent:
  summary: "Replace legacy DiscountEngine with CalculatorV2 across checkout."
  invariants:
    - "Public API of /checkout responses unchanged."
    - "No change to persisted order schema."
  non_goals:
    - "Analytics pipeline refactor."
impact:
  targets: ["pricing/", "checkout/", "services/cart/"]
  exclusions: ["analytics/"]
  risk_level: "medium"   # low|medium|high
  confidence: 0.72
  reasons:
    - "Call graph from CartService.quote -> PricingClient.GetQuote"
    - "Imports from pricing/discounts/* routed to pricing/v2/*"
test_plan:
  impacted_suites: ["pricing/*", "checkout/*", "api/quote/*"]
  new_tests:
    - "property: discounts never increase total price"
    - "regression: coupon edge cases from issue-842"
checkpoints:
  required:
    - "Build compiles"
    - "Impacted unit tests green"
    - "Sandbox e2e quote flow"
rollback:
  strategy: "git revert to checkpoint"
  mitigations: ["feature flag pricing_v2", "shadow compare in staging"]
budgets:
  time_per_step_minutes: 20
  tokens_per_step: 200000
approvals_required:
  codeowners: ["@payments-team", "@checkout-core"]
policies:
  dangerous_ops: ["mass_delete>20", "db_schema_drop"]

Editing: Users can edit before execution; policies may require additional fields (e.g., rollback required for risk=high).

Impact Map

Interactive visualizations displayed in the CLI (or IDE).

1) Default summary view

$ claude impact --goal "migrate pricing module to v2 calculator"
Lighthouse • Impact Map  - repo: shopco/checkout  - contract: cc-2025-09-01-00123
Goal: Replace DiscountEngine with CalculatorV2 across checkout
-------------------------------------------------------------------------------
Nodes: 143   Planned touches: 12   Potentially impacted: 34   Risk: MEDIUM
Graph build: 2.9s   Confidence (overall): 0.72   Test coverage (impacted): 63%
-------------------------------------------------------------------------------
Legend: [T]=Planned Touch  [I]=Potentially Impacted  Risk: ░ Low ▒ Med ▓ High
         Edge types: → call   ⇢ import   ≡ config    ≅ schema    … other

Top modules by risk × confidence:
  1. checkout/ (score 0.71 ▓▓)    2. services/cart/ (0.68 ▒▓)    3. pricing/ (0.65 ▒▒)

2) Table view (compact, greppable)

$ claude impact --format table --limit 12 --reasons 1
ROLE PATH                                      RISK COV  CONF REASON
---- ----------------------------------------- ---- ---- ---- ----------------------------------------------
[T]  pricing/v2/Calculator.ts                  MED  88%  .92  replaces DiscountEngine usage
[T]  pricing/v2/DiscountAdapter.ts             LOW  86%  .89  import from pricing/discounts/*
[T]  pricing/v2/index.ts                       LOW  91%  .87  module entry for v2 exports
[I]  services/cart/PricingClient.ts            MED  64%  .83  calls getQuote() → CalculatorV2
[I]  checkout/CheckoutFlow.ts                  HIGH 52%  .71  call path: CheckoutFlow → PricingClient → V2
[I]  api/quote/handlers.ts                     MED  55%  .61  inbound route uses PricingClient.getQuote
[I]  api/quote/schema.json                     LOW  80%  .58  schemaRef in handlers.ts
[I]  config/feature_flags.yaml                 LOW  n/a  .57  configRef: pricing_v2 flag present
[I]  services/cart/__tests__/quote.spec.ts     MED  42%  .56  impacted test: quote path assertions
[I]  checkout/__tests__/checkout.spec.ts       MED  38%  .54  impacted test: end-to-end checkout
[I]  analytics/price_events.ts                 LOW  19%  .29  weak import edge via shared types
[I]  docs/PRICING-ADR.md                       LOW  n/a  .22  documentation backref

Notes for implementation

  • RISK is derived (coverage ↓ and churn ↑ push toward HIGH).
  • CONF is the node inclusion confidence (0–1).
  • REASON shows the top ranking inclusion path (truncate to terminal width).
  • Respect --no-color for plain output; otherwise colorize RISK and ROLE.

3) ASCII graph view (readable in any TTY)

$ claude impact --format graph --width 80
[T] pricing/v2/Calculator.ts (.92)  ▒ Risk: MED
  ⇢ imports
      └── [I] services/cart/PricingClient.ts (.83) ▒ Risk: MED
            → calls
                └── [I] checkout/CheckoutFlow.ts (.71) ▓ Risk: HIGH
                      → calls
                          └── [I] api/quote/handlers.ts (.61) ▒ Risk: MED
                                ≅ schemaRef
                                    └── [I] api/quote/schema.json (.58) ░ Risk: LOW

[T] pricing/v2/DiscountAdapter.ts (.89) ░ Risk: LOW
  ⇢ imports
      └── [I] pricing/discounts/index.ts (.47) ░ Risk: LOW

[I] config/feature_flags.yaml (.57) ░ Risk: LOW
  ≡ configRef: "pricing_v2" → gates runtime switch

Legend: [T] planned touch, [I] potentially impacted, numbers in ( ) are confidence. Edges: → call, ⇢ import, ≡ configRef, ≅ schemaRef. Risk shading: ░ LOW ▒ MED ▓ HIGH.

4) “Explain why this node is included”

$ claude impact --explain checkout/CheckoutFlow.ts
WHY: checkout/CheckoutFlow.ts is 'potentially impacted' (confidence .71, risk HIGH)

Top contributing paths:
  1) pricing/v2/Calculator.ts (T) → services/cart/PricingClient.ts → checkout/CheckoutFlow.ts
     - edge weights: call(.84) × call(.81) ⇒ path score .68
  2) pricing/v2/DiscountAdapter.ts (T) ⇢ pricing/discounts/index.ts ⇢ checkout/CheckoutFlow.ts
     - edge weights: import(.77) × import(.61) ⇒ path score .47

Signals:
  - Coverage: 52% (below repo median 67%)
  - Churn: 13 commits / last 30 days (above median 6)
  - Past incidents: linked to INC-2187 (checkout total mismatch)

Suggested actions:
  - Lock critical lines (total price calc) before refactor
  - Add property test: "total never increases with discount"

5) Filtering

# Only show JS/TS files in checkout and services/cart, with medium+ risk
$ claude impact --format table \
    --filter "path:checkout/,path:services/cart/" \
    --filter "language:ts,language:tsx" \
    --filter "risk:>=MED"
ROLE PATH                                 RISK COV  CONF REASON
---- ------------------------------------ ---- ---- ---- ---------------------------------------------
[I]  services/cart/PricingClient.ts       MED  64%  .83  calls getQuote() → CalculatorV2
[I]  checkout/CheckoutFlow.ts             HIGH 52%  .71  call path: CheckoutFlow → PricingClient → V2
[I]  checkout/components/Total.tsx        MED  49%  .53  imports price formatter used by V2

6) Checkpoint‑aware overlays in the terminal

$ claude impact --format graph --with-checkpoints
CKPT 0 (baseline) ✓  CKPT 1 (create v2 calculators) ✓  CKPT 2 (switch adapters) ⚠ tests red
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ [T] pricing/v2/Calculator.ts (.92)         at CKPT 1: added file                        │
│   → services/cart/PricingClient.ts (.83)   at CKPT 2: modified (8 lines)                │
│     → checkout/CheckoutFlow.ts (.71)       at CKPT 2: modified (3 lines)  ✖ test fail   │
└─────────────────────────────────────────────────────────────────────────────────────────┘
Hint: Run `claude checkpoint revert --to 1` to roll back to CKPT 1 and retry with shims.

7) JSON output (for CI, scripts)

$ claude impact --format json --limit 5 | jq .
{
  "id": "impact-cc-2025-09-01-00123",
  "generated_at": "2025-09-01T10:22:04Z",
  "summary": {
    "nodes": 143,
    "planned_touches": 12,
    "potentially_impacted": 34,
    "risk": "MEDIUM",
    "confidence": 0.72
  },
  "nodes": [
    {
      "id": "pricing/v2/Calculator.ts",
      "path": "pricing/v2/Calculator.ts",
      "role": "planned_touch",
      "risk": "MEDIUM",
      "coverage": 0.88,
      "confidence": 0.92,
      "reasons": ["replaces DiscountEngine usage"]
    },
    {
      "id": "services/cart/PricingClient.ts",
      "path": "services/cart/PricingClient.ts",
      "role": "potentially_impacted",
      "risk": "MEDIUM",
      "coverage": 0.64,
      "confidence": 0.83,
      "reasons": ["calls getQuote() → CalculatorV2"]
    }
  ],
  "edges": [
    {"src": "pricing/v2/Calculator.ts", "dst": "services/cart/PricingClient.ts", "type": "call", "confidence": 0.84},
    {"src": "services/cart/PricingClient.ts", "dst": "checkout/CheckoutFlow.ts", "type": "call", "confidence": 0.81}
  ]
}

8) CLI UX cheatsheet (for the spec)

claude impact                             # smart summary + legend
claude impact --format table              # tabular, --limit N, --reasons K, --no-color
claude impact --format graph              # ASCII graph (width auto; --width N)
claude impact --format json               # machine-readable
claude impact --explain <path>            # "why is this included?"
claude impact --filter "<key:val,...>"    # multiple filters allowed
claude impact --with-checkpoints          # overlay checkpoint status on nodes

Filters supported (examples):

  • path:<glob or prefix> - path:checkout/
  • language:<ext> - language:ts
  • risk:<LOW|MED|HIGH or comparator> - risk:>=MED
  • role:<T|I> - role:T (planned touches only)

Implementation Notes

  • Use terminal width detection (fallback to 80) and graceful truncation with ….
  • Provide --no-color and --plain for CI. For color, stick to ANSI 16‑color baseline.
  • Keep latency tight by pre‑caching the repo graph (render target ≤ 3–8s for ~50k LOC).
  • Ensure every row/edge can surface a single top “reason” string that is informative on its own; this is the prime UX win in CLI mode.
  • All views (table/graph/json) must be derived from the same in‑memory model to avoid divergence.

Checkpoints & Snapshots

  • Types: Automatic (end of each step), Required (from Contract), Manual (dev-triggered).

  • Snapshot content:

    • Git commit + diff
    • Repro capsule (devcontainer metadata, env vars, seed data, run scripts)
    • Logs (stdout/stderr), test results (JUnit/JSON)
    • Budget usage (time, tokens), tool invocations

  • Controls:

    • Rollback to any checkpoint (fast, single command)
    • Compare checkpoints (diff + test deltas)

  • Storage:

    • Local under .claude/Lighthouse/<id>/…
    • Optional remote artifact store (configurable retention)

Detailed Technical Design

Architecture overview (CLI)

Goal: enable fully capable Lighthouse flows from the terminal - planning, rendering the Impact Map, executing with checkpoints, and opening PRs - while keeping indexing, policies, and execution local, auditable, and reversible.

High‑level components

  • claude CLI (frontend) Parses commands and flags, renders TTY output (summary/table/graph/JSON), writes artifacts to .claude/.
  • ChangeGuard Daemon (“cgd”) Lightweight local service started on demand by the CLI (or reused if running). Exposes a local gRPC/UDS API to coordinate indexing, contracts, checkpoints, and PR publishing.
  • Graph Indexer Extracts import/call/config/schema edges (LSP + tree‑sitter + build files). Persists to SQLite under .claude/index/graph.sqlite with incremental file‑watch updates.
  • Headless Agent Client Talks to the Claude Code backend with scoped tools & budgets; synthesizes the initial Change Contract from repo signals.
  • Checkpoint Runner Executes each step inside a devcontainer (preferred) or local runner. Produces snapshots, test results, and logs.
  • PR Publisher Opens/updates PRs and attaches artifacts (Contract, Impact Map JSON/PNG, Checkpoint Report, repro capsule).
  • Policy & Config Store Merges ~/.claude/config.yaml (global) and <repo>/.claude/project.yaml (repo), plus contract policies.
  • Telemetry & Logs Structured logs to .claude/logs/… and optional OpenTelemetry exporters (disabled by default; opt‑in).

Process model (ASCII)

            (TTY)
+---------------------------+
|        claude CLI         |
|  - parse flags            |
|  - render table/graph     |
|  - write artifacts        |
+-------------+-------------+
              | local gRPC / UDS (or Windows named pipe)
              v
+---------------------------+       spawns / supervises
|       cgd daemon          |-------------------------------+
|  - contract engine        |                               |
|  - graph index & cache    |                               |
|  - checkpoint orchestration|                              |
|  - policy enforcement     |                               |
+-------+----------+--------+                               |
        |          |                                        |
        |          |                                        |
        v          v                                        v
+---------------+  +--------------------+        +------------------------+
| Graph Indexer |  | Checkpoint Runner  |<------>|   Devcontainer / OS    |
|  (LSP, AST)   |  |  (git, tests, env) |        |  (Docker/Podman/fallback)|
+-------+-------+  +--------------------+        +------------------------+
        |
        | signals
        v
+------------------------+     HTTPS (scoped, budgeted)
| Headless Agent Client  |<------------------------------------+
|  (Claude Code backend) |                                     |
+------------------------+                                     |
        ^                                                       |
        | PRs / artifacts                                       |
        +---------------------+---------------------------------+
                              v
                        +-----------+
                        |  SCM/CI   |
                        | (GitHub…) |
                        +-----------+

Local state layout

.claude/
  index/graph.sqlite         # repo graph cache
  contracts/*.yaml           # versioned Change Contracts
  impact/*.json|*.png        # Impact Map exports
  checkpoints/<run-id>/*     # manifests, logs, repro capsule
  logs/*.log                 # daemon + runner logs
  config.yaml                # repo-level config/policies

Data flows by command

1) claude plan "…"

  1. CLI starts/contacts cgd.

  2. cgd loads or builds graph (Graph Indexer).

  3. cgd calls Headless Agent with graph signals (targets, coverage, churn, CODEOWNERS).

  4. Agent returns Contract draft; cgd validates against schema + applies policy gates (e.g., rollback required for risk=high).

  5. cgd synthesizes Impact Map (nodes/edges, confidence, risk overlays).

  6. CLI renders summary (TTY) and writes:

    • .claude/contracts/<id>.yaml
    • .claude/impact/<id>.json (+ optional .png if --export png)

2) claude impact [--format table|graph|json]

  1. CLI asks cgd for the current graph snapshot + contract scope.

  2. cgd returns a view model (top‑k nodes with reasons & metrics).

  3. CLI renders:

    • table: greppable, with RISK/COV/CONF
    • graph: ASCII tree (width aware)
    • json: machine‑readable (same model)

3) claude start --contract <file>

  1. cgd creates work branch + Checkpoint 0 (baseline snapshot).
  2. For each Step in the plan: a. Runner executes inside devcontainer (or local) with budgets. b. Run impacted tests from contract; collect JUnit/JSON; compute deltas. c. Produce Checkpoint N: commit + manifest + repro capsule + logs. d. Apply policy (auto‑pause or auto‑rollback on red tests, confirm dangerous ops).
  3. On success, cgd can open a PR with artifacts (--open-pr).

4) claude checkpoint revert --to <n>

  • cgd resets repo state to tagged checkpoint commit, restores env & repro capsule pointers, and reports outcome. Target ≤ 5s local.

5) claude pr open --include-artifacts

  • cgd bundles Contract, Impact Map (JSON/PNG), Checkpoint Report, and repro capsule, attaches to PR, and sets CI gates per Contract.

Interfaces (conceptual)

  • Daemon API (local):

    • Graph.GetSummary() / Explain(node)
    • Contract.Create(goal) / Validate(contract)
    • Runner.Start(contract) / Checkpoint.List() / Revert(n)
    • Artifacts.List(kind) / Export(kind, id)
    • PR.Open(contract_id, artifacts[])

  • Formatters (CLI): SummaryRenderer, TableRenderer, AsciiGraphRenderer, JsonRenderer (all read the same view model).

Security & privacy (CLI)

  • Isolation first: containerized runner by default; minimal host mounts (repo workspace + cache).
  • Least privilege: tool scopes for the agent; dangerous‑ops intercepts (mass delete, schema changes, secrets).
  • Secrets: redact .env/tokens from artifacts; optional encrypted inclusion for CI repro (policy‑gated).
  • Local only by default: no remote artifact upload unless configured. --offline mode skips agent calls and uses local graph (reduced capability).

Configuration & environment

  • Precedence: CLI flags → repo .claude/project.yaml → user ~/.claude/config.yaml.

  • Selected env vars:

    • CLDG_DAEMON_ADDR (override socket/pipe)
    • CLDG_OFFLINE=1 (no agent calls)
    • CLDG_CONTAINER=0 (force local runner)
    • CLDG_LOG_LEVEL=debug|info|warn|error
    • CLDG_NO_COLOR=1 (plain output)

  • Auth: OS keychain‑backed token store; short‑lived session tokens for the agent.

Performance targets (CLI path)

  • Initial index (100k LOC): ≤ 120s; incremental update: ≤ 500ms on change.
  • Impact Map render: 3–8s for ~50k LOC.
  • Checkpoint rollback: ≤ 5s.
  • PR assembly: ≤ 10s.

Exit codes

  • 0 success
  • 2 contract validation failed
  • 3 policy violation (e.g., unapproved dangerous op)
  • 4 graph/index unavailable and --no-build set
  • 5 agent/API error (non‑retryable)
  • 6 container runtime missing or unhealthy
  • 7 PR publish failed
  • 8 rollback performed (non‑fatal)
  • 9 user canceled / interactive declined

Sequence diagrams

claude plan 
sequenceDiagram
  autonumber
  participant CLI as claude CLI
  participant CGD as cgd daemon
  participant GI as Graph Indexer
  participant LLM as Headless Agent
  participant POL as Policy/Schema

  CLI->>CGD: Plan(goal="migrate pricing to v2")
  CGD->>GI: LoadOrBuildGraph()
  GI-->>CGD: Graph(model, stats)
  CGD->>LLM: ProposeContract(graph signals, repo heuristics)
  LLM-->>CGD: Contract Draft (YAML/JSON)
  CGD->>POL: Validate + Apply Policies
  POL-->>CGD: Approved Contract
  CGD-->>CLI: Contract + ImpactMap(view model)
  CLI->>CLI: Render summary/table/graph; write .claude/contracts + impact
claude start (with checkpoints) 
sequenceDiagram
  autonumber
  participant CLI as claude CLI
  participant CGD as cgd daemon
  participant RUN as Checkpoint Runner
  participant CTN as Devcontainer
  participant SCM as Git/Repo

  CLI->>CGD: Start(contract_id)
  CGD->>SCM: CreateBranch + Checkpoint(0)
  loop For each plan step
    CGD->>RUN: Execute(step, budgets, policy)
    RUN->>CTN: Start sandbox, apply edits, run tests
    CTN-->>RUN: Results (logs, junit)
    RUN-->>CGD: Step result + artifacts
    CGD->>SCM: Commit + Tag ckpt-N
    alt Tests red and policy=auto-rollback
      CGD->>SCM: Reset to ckpt-(N-1)
      CGD-->>CLI: Paused with rollback performed
    else Tests green
      CGD-->>CLI: Checkpoint N created
    end
  end
  CGD-->>CLI: Pre‑PR checkpoint ready

Why this shape? It keeps heavy lifting local (graph, checkpoints, policies), uses the agent for planning and code synthesis, and gives the CLI deterministic, scriptable outputs that mirror the IDE experience - ideal for CI, headless servers, and developers who live in the terminal.

Architecture overview (IDE)

+------------------+        +---------------------+        +------------------+
|    IDE Plugin    |<-----> |  Lighthouse Daemon  |<-----> |  Headless Agent  |
|(VSCode/JetBrains)|        |  (local, per repo)  |        |  Runtime (LLM)   |
+---------+--------+        +----------+----------+        +--------+---------+
          |                              |                            |
          | UI (Contract/Map/Timeline)   | gRPC/HTTP (local)          | MCP tools
          |                              |                            |
          v                              v                            v
+---------+--------+        +---------------------+        +------------------+
|   Graph Indexer  |        |  Checkpoint Runner  |        |  PR Publisher    |
|(LSP, tree-sitter)|        | (devcontainer, git) |        |   (SCM API)      |
+------------------+        +---------------------+        +------------------+
  • Daemon: local background service coordinating indexers, contract engine, checkpoints, and PR publishing.
  • Headless Agent: the Claude Code backend that plans and edits files using MCP/tools.
  • Isolation: default to devcontainer (or sandbox) for execution.

Repo indexing & graph building

Inputs

  • Language Server Protocol (symbols, references)
  • tree-sitter parsers for import/AST edges
  • Build/workspace config (e.g., tsconfig, Bazel, Gradle)
  • Optional: lightweight dynamic traces (run a small subset of tests or a discovery script to confirm hot call paths)
  • Repo heuristics: churn (git log), test coverage (lcov), CODEOWNERS

Graph

  • Stored under .claude/index/graph.sqlite (SQLite with FTS for symbol search).
  • Node: {id, kind, path, language, risk_score, coverage, churn}
  • Edge: {src, dst, type, weight, confidence, reason}

Inclusion algorithm (high level)

  • Seed with targets from user prompt + files matched by symbol search.
  • Expand along edges with decay; stop at thresholds (depth, breadth, cumulative weight).
  • Mark nodes as planned_touch when directly edited; potentially_impacted otherwise.
  • Compute confidence per node from edge confidence and coverage signals.
  • Produce reasons[] for inclusion (top‑k contributing paths).

Contract engine

  • Generates the initial Contract from the graph + heuristics.
  • Validates against JSON Schema; runs policy checks (e.g., rollback required when risk=high).
  • Exposes a structured diff when the user edits in IDE (and persists versioned copies under .claude/contracts/).
  • Emits CI metadata: which tests/suites to run, gates for required checkpoints.

Checkpoint runtime

  • Git substrate: creates ephemeral worktree/branch; auto‑commit per checkpoint with tag cg-<id>-ckpt-<n>.

  • Execution environment: devcontainer or local sandbox; per‑step budgets (time, tokens).

  • Artifacts:

    • /manifest.json (see schema)
    • /repro/ (Dockerfile/devcontainer.json, scripts, env vars, seed data)
    • /logs/ (per step)
    • /tests/ (reports)

  • Policy behaviors:

    • “Auto‑rollback on red tests”
    • “Pause for approval on dangerous ops”
    • “Require manual checkpoint before schema migrations”

  • Rollback: fast git reset --hard to checkpoint commit + restore repro capsule and env.

IDE surfaces

  • Lighthouse Panel: tabs for Contract, Impact Map, Checkpoints.
  • Map interactions: hover for reasons, right‑click to exclude/lock, open file/diff.
  • Timeline: visual list of checkpoints; click to view manifest, logs, tests; buttons for Rollback and Compare.

Accessibility: keyboard‑first operations, focus outlines, ARIA labels for graph nodes/edges.

CLI surfaces

# Draft plan: contract + map (no edits applied)
claude plan "migrate pricing to v2"

# Start execution from a saved or edited contract
claude start --contract .claude/contracts/cc-2025-09-01-00123.yaml

# Show impact map summary
claude impact --format graph

# Manage checkpoints
claude checkpoint list
claude checkpoint create "before db migration"
claude checkpoint revert --id cg-00123-ckpt-2
claude checkpoint compare --from ckpt-2 --to ckpt-4 --format table

# Open PR with artifacts attached
claude pr open --include-artifacts

PR bot surfaces

  • Contract summary (intent, invariants, risks, test plan).
  • Impact Map (PNG + JSON attachment) and a link to interactive view (if enabled in CI build).
  • Checkpoint Report (timeline with pass/fail, artifact links).
  • “Repro capsule” download link.

Policy & permissions

  • Approvals: Contract approval limited to CODEOWNERS or org roles.
  • Dangerous ops: configurable intercepts (rm -rf, mass delete >N files, schema drop, secrets exposure).
  • Budgets: per‑repo defaults and per‑run overrides; hard caps enforced (time, tokens, CPU/mem).
  • Audit: all actions emit signed, tamper‑evident events (OpenTelemetry + local append‑only log).

Observability & analytics

  • Key events: contract_created, contract_approved, map_rendered, checkpoint_created, tests_run, rollback_performed, pr_opened, pr_merged.

  • Metrics:

    • First‑pass CI pass rate for Claude PRs
    • Review latency for >5‑file PRs
    • % PRs rolled back post‑merge
    • Coverage deltas on impacted area
    • Suggestion accept rate & rework rate

APIs & Schemas

Contract JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ChangeContract",
  "type": "object",
  "required": ["id", "title", "version", "intent", "impact", "test_plan", "checkpoints", "rollback", "budgets"],
  "properties": {
    "id": {"type": "string"},
    "title": {"type": "string"},
    "version": {"type": "integer"},
    "author": {"type": "string"},
    "created_at": {"type": "string", "format": "date-time"},
    "intent": {
      "type": "object",
      "required": ["summary", "invariants"],
      "properties": {
        "summary": {"type": "string"},
        "invariants": {"type": "array", "items": {"type": "string"}},
        "non_goals": {"type": "array", "items": {"type": "string"}}
      }
    },
    "impact": {
      "type": "object",
      "required": ["targets", "risk_level"],
      "properties": {
        "targets": {"type": "array", "items": {"type": "string"}},
        "exclusions": {"type": "array", "items": {"type": "string"}},
        "risk_level": {"type": "string", "enum": ["low", "medium", "high"]},
        "confidence": {"type": "number", "minimum": 0, "maximum": 1},
        "reasons": {"type": "array", "items": {"type": "string"}}
      }
    },
    "test_plan": {
      "type": "object",
      "properties": {
        "impacted_suites": {"type": "array", "items": {"type": "string"}},
        "new_tests": {"type": "array", "items": {"type": "string"}}
      }
    },
    "checkpoints": {
      "type": "object",
      "properties": {
        "required": {"type": "array", "items": {"type": "string"}}
      }
    },
    "rollback": {
      "type": "object",
      "required": ["strategy"],
      "properties": {
        "strategy": {"type": "string"},
        "mitigations": {"type": "array", "items": {"type": "string"}}
      }
    },
    "budgets": {
      "type": "object",
      "required": ["time_per_step_minutes", "tokens_per_step"],
      "properties": {
        "time_per_step_minutes": {"type": "integer", "minimum": 1},
        "tokens_per_step": {"type": "integer", "minimum": 1}
      }
    },
    "approvals_required": {
      "type": "object",
      "properties": {
        "codeowners": {"type": "array", "items": {"type": "string"}}
      }
    },
    "policies": {
      "type": "object",
      "properties": {
        "dangerous_ops": {"type": "array", "items": {"type": "string"}}
      }
    }
  }
}

Impact Map JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ImpactMap",
  "type": "object",
  "required": ["id", "nodes", "edges", "generated_at"],
  "properties": {
    "id": {"type": "string"},
    "generated_at": {"type": "string", "format": "date-time"},
    "nodes": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "path", "kind"],
        "properties": {
          "id": {"type": "string"},
          "path": {"type": "string"},
          "kind": {"type": "string", "enum": ["file", "module", "service"]},
          "language": {"type": "string"},
          "risk_score": {"type": "number"},
          "coverage": {"type": "number"},
          "churn": {"type": "number"},
          "planned_touch": {"type": "boolean"},
          "potentially_impacted": {"type": "boolean"},
          "confidence": {"type": "number"}
        }
      }
    },
    "edges": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["src", "dst", "type"],
        "properties": {
          "src": {"type": "string"},
          "dst": {"type": "string"},
          "type": {
            "type": "string",
            "enum": ["import", "call", "configRef", "schemaRef", "route", "envVar"]
          },
          "weight": {"type": "number"},
          "confidence": {"type": "number"},
          "reason": {"type": "string"}
        }
      }
    }
  }
}

Checkpoint manifest Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "CheckpointManifest",
  "type": "object",
  "required": ["id", "contract_id", "index", "created_at", "git", "artifacts", "results", "budgets_used"],
  "properties": {
    "id": {"type": "string"},
    "contract_id": {"type": "string"},
    "index": {"type": "integer"},
    "label": {"type": "string"},
    "created_at": {"type": "string", "format": "date-time"},
    "git": {
      "type": "object",
      "properties": {
        "branch": {"type": "string"},
        "commit": {"type": "string"},
        "diff_stat": {"type": "string"}
      }
    },
    "artifacts": {
      "type": "object",
      "properties": {
        "repro_capsule_path": {"type": "string"},
        "logs_path": {"type": "string"},
        "tests_report_path": {"type": "string"}
      }
    },
    "results": {
      "type": "object",
      "properties": {
        "build_ok": {"type": "boolean"},
        "tests_passed": {"type": "boolean"},
        "failed_tests": {"type": "array", "items": {"type": "string"}}
      }
    },
    "budgets_used": {
      "type": "object",
      "properties": {
        "time_minutes": {"type": "number"},
        "tokens": {"type": "number"}
      }
    },
    "policy_flags": {
      "type": "array",
      "items": {"type": "string"}
    }
  }
}

Performance targets

  • Impact Map render: ≤ 3–8s for ~50k LOC mixed‑language repo on a modern laptop.
  • Indexing: initial index ≤ 120s for 100k LOC; incremental updates ≤ 500ms after file change.
  • Rollback: ≤ 5s to revert to any checkpoint (local).
  • PR assembly: ≤ 10s to package artifacts and open PR.

Security & privacy

  • Isolation: run edits/tests in devcontainers by default; least‑privileged tool scopes.
  • Dangerous op intercepts: explicit prompts + approvals for mass deletes, schema drops, or secret exposure.
  • Secrets handling: redact .env/secrets from artifacts by default; allow explicit opt‑in for encrypted secrets needed for repro in secured CI.
  • Audit: signed event log; local append‑only file + optional server ingest.
  • Data retention: configurable per repo/org; artifact TTL defaults (e.g., 14 days).

So, here it is, the first version of my Claude Code Lighthouse idea. Let me know what you think.