plumbline: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project status

Plumbline is implemented and shipping. It is a Go module (github.com/sroberts/plumbline, Go 1.26.1) with a Cobra CLI, a Bubble Tea TUI, a 23-signal detector catalog, GoReleaser packaging, and nine CI workflows. It assesses itself at ACMM Level 5.

SPEC.md is the implementation contract — numbered sections, cited throughout the source (SPEC.md §6 = signal model, §7 = scoring, §9 = output formats). Read the relevant section before changing behavior it pins. The ACMM paper is the model source; SPEC.md is what plumbline actually does, and §6's "Deviations from the source paper" records where the two diverge on purpose. It is a contract, not a sketch: change it in the same commit as the behavior it describes.

Build & test

make build      # binary with version ldflags
make test       # unit + E2E
make test-race  # race detector
make lint       # gofmt + go vet (golangci-lint if installed)

CONTRIBUTING.md has the full pre-PR checklist and the package-by-package "where things live" map — read it rather than rediscovering the layout.

Architecture in brief

• pkg/acmm — the public types. Anything here is --json surface and part of the compatibility contract.
• internal/scanner — the single IO chokepoint. Signals read the RepoIndex, never the filesystem directly.
• internal/signals/lN/<id>.go — one file per detector, self-registering via init(). The level packages are blank-imported from cmd/plumbline/registrations.go and cmd/gen-signal-docs/main.go; a new level package needs adding to both.
• internal/signals.Fixer — an optional interface. Most signals don't implement it, and plumbline fix <id> correctly exits 2 for those. Don't add a fixer for a signal whose remedy needs real judgment (which monitoring SDK, which triage rules) — the fix_hint prose is the answer there.
• internal/workflows — GitHub Actions YAML parsed into a CI-agnostic AST. Workflow signals go through it, never raw YAML regex; if the AST cannot express what a detector needs, extend the AST.
• internal/badge — the SVG plumbline badge writes. Self-contained (no shields.io round-trip); output must stay byte-stable or the drift gate churns.
• internal/dependabot — the .github/dependabot.yml plumbline install-dependabot writes, derived from the manifests present rather than templated. Deliberately detected by no signal, so scaffolding it moves no verdict; SPEC.md §4 "The second exception" has the argument.
• internal/ciworkflow — the workflow plumbline install-ci writes, and the variant registry behind both the CLI --list and the TUI [w] picker. The only workflow plumbline generates; read SPEC.md §4 "The one carve-out" before widening it.
• internal/fix — where fix, install-skill, and install-ci write inside a target repo. Refuses overwrite; in-repo paths only. plumbline badge is the one writer that bypasses it, because regenerating in place is the point — it refuses any --out target that exists without the generated-file marker.