Redtropig/harness-anchor

# Anti-Hallucination Gates

The most common agent failure is **declaring victory too early**. This skill is the gate between "I think it works" and "evidence proves it works".

## The Iron Rule

> No claim of "done" / "fixed" / "passing" without a concrete artifact path proving it.

A claim like *"I fixed the bug"* is incomplete. The proper form:

> "Fixed by commit `abc123`. Test `tests/foo.test.ts::handles-edge-case` now passes (output captured in `.harness-anchor/test-2026-05-28.log`). Build still passes (`.build/last-build.log` exit 0)."

## The Iron Rule runs both ways

# Capturing Golden Rules

A one-off fix repairs today's symptom. A **golden rule** repairs the whole class — it makes the
harness learn so the same mistake can't recur. This skill is the **ratchet**: turn a recurring
failure into a durable, checkable rule in `golden-rules.md`.

> Hashimoto's principle: *"Anytime an agent makes a mistake, engineer a solution so it never makes
> that mistake again."* The fix is a guardrail, not a scolding — **blame the process, not the agent**.
> You're improving the environment, not the model.

## When to capture

Capture when the signal is **recurring**, not a one-off:

# Context Budget Discipline

Context is a finite resource. Every token competes for the model's attention. The "lost-in-the-middle" phenomenon is real — content buried in 50% of the window position is least attended.

This skill applies four operations to keep the budget sane.

## The Four Operations

```
SELECT     load context just-in-time, not all-at-once
WRITE      persist to disk; let the filesystem remember, not chat
COMPRESS   summarize older turns when window fills
ISOLATE    delegate so child work doesn't pollute parent context
```

# C/C++ Build Systems

The build system is the single most important piece of C/C++ tooling — it determines how every other tool (clang-tidy, IWYU, language servers, debuggers) understands your code.

## The compile_commands.json invariant

> **Every C/C++ project must export `compile_commands.json`.**

It's a JSON database of compiler invocations per file. Without it, clang-tidy/IWYU/clangd can't parse your code correctly (they need to know macros, includes, standard, flags). The `cpp-static-analysis` skill enforces this prerequisite.

## Per-build-system commands

### CMake

# C/C++ Formatting (clang-format)

`clang-format` is the de-facto C/C++ formatter. Like Prettier or rustfmt, it's deterministic and removes formatting debates.

## Prerequisites

- `clang-format` reachable — see "Is clang-format actually here?" below before concluding
  it's missing; only then `brew install clang-format` / `apt install clang-format`.
- `.clang-format` config at project root (use `templates/cpp/.clang-format.tpl` if not present — `/cpp-init` drops it for you)

## Format changed lines only (preferred)

```bash
git diff -U0 --no-color HEAD | clang-format-diff -p1 -i

# C/C++ Sanitizers — Runtime Bug Catchers

Sanitizers are compiler-instrumented runtime checks. They catch what static analysis can't (path-sensitive errors, race conditions, memory errors discovered at runtime). They run your normal tests under instrumentation; failures abort with a precise report.

| Sanitizer | What it catches | Slowdown |
|---|---|---|
| **ASan** (Address) | Use-after-free, heap/stack overflow, leaks (leaks: Linux only) | 2-3x |
| **UBSan** (UB) | Signed overflow, null deref, misaligned, OOB shift, ... (MSVC: unavailable — see Platform notes) | ~1.1x |
| **TSan** (Thread) | Data races, deadlocks (not available on Windows — see Platform notes) | 5-10x |
| **MSan** (Memory) | Use of uninitialized memory | 3x (Linux only, Clang only) |

Note: ASan + UBSan are combinable. TSan is **mutually exclusive** with ASan/MSan.

## The `/sanitize` command

# C/C++ Static Analysis

Static analysis catches an enormous class of bugs at zero runtime cost: null derefs, leaks, dangling refs, integer overflow, missing initializers, unused includes, banned APIs.

Three core tools cover most needs:

| Tool | What it catches | Cost |
|---|---|---|
| **clang-tidy** | Style + correctness + modernize + bugprone | Heavy (uses full AST) |
| **cppcheck** | Quick correctness, leaks, off-by-one | Light (own parser) |
| **IWYU** | Missing/superfluous `#include` | Heavy (compile-driven) |

## Prerequisites (hard)

# Docs Lookup (with fallback)

When you need authoritative information about an unfamiliar **tool / API / error message / library behavior**, follow this fallback chain. Each step has explicit success and failure criteria so the agent never silently degrades to guessing.

```
Step 1: Structured docs MCP   (Context7; or Microsoft Learn for .NET/Azure/Windows/MSVC)
   ↓ (unavailable / no match / wrong content / tool error)
Step 2: WebSearch     (broader web, recent ecosystem changes)
   ↓ (unavailable / no useful results / paywalled)
Step 3: Calibrated uncertainty (tell user what you tried + what's needed)
```

**You do not skip steps.** If Step 1 fails, you go to Step 2. If Step 2 fails, you go to Step 3. You do NOT retry Step 1 with the same query hoping for a different answer.

# Feature State Keeper

You maintain the **machine-readable scope record** of this project. Three files form the state trio:

| File | Role |
|---|---|
| `feature_list.json` | Scope boundary + done criteria + evidence |
| `progress.md` | Append-only session history |
| `session-handoff.md` | Single-page "what's the state right now" |

## Altitude — feature ledger vs superpowers' execution records

When `superpowers` is also active, **two record systems coexist by altitude — keep them from drifting:**

# Init Verification

Before writing any code, **prove the environment is healthy**. Anthropic's Nov 2025 harness guidance: *the initializer agent runs init.sh, then the coding agent picks up — health is verified BEFORE work begins*.

## When to invoke

- First action of every fresh session
- After `git checkout` to a different branch
- After dependency changes (package.json / Cargo.toml / etc. modified)
- After OS / toolchain updates
- When a previously-working command suddenly fails
- Before claiming a feature done (re-verify in case of drift)

## Procedure

# Project Indexing

`PROJECT-TOC.md` is the project's **machine-friendly index** — one line per file, ≤80 chars summary. Reading it is dramatically cheaper than `Glob`-ing the whole tree.

## When to use

- "Where is X defined?"
- "Find the file that handles Y"
- Before any `Glob '**/*.ext'` against more than a small directory
- When starting work in an unfamiliar codebase

## Reading flow

1. **Check `PROJECT-TOC.md` exists.** If missing, the project is un-indexed. Suggest `/index-project` and fall back to Glob for the current question.

# Self-Correction Loop

When your edit produces a warning/error signal, you're in a **correction loop**. This skill is the discipline that keeps the loop productive instead of thrashing.

## Trigger signals

You should engage this loop when ANY of these happen after your edit:

- `PostToolUse` hook injected `clang-tidy warnings:` / `lint warnings:` / similar
- A `Bash` command you ran returned non-zero exit
- A test runner reports failures
- A type-checker reports errors
- The user says "that broke X" / "it's failing now"

# Test Coverage Design

A passing test suite proves only that *the tests you wrote* pass — not that they exercise what the
feature actually requires or where the code is actually risky. This skill is the **post-implementation**
discipline for closing that gap: derive what *must* be tested, check it against what the suite runs, and
design the smallest test set that covers it.

## Altitude — where this sits vs. superpowers TDD

| Phase | Owner | What |
|---|---|---|
| **Pre-implementation** (spec-driven, test-first) | superpowers `test-driven-development` | Red-green-refactor; write the failing test *before* the code. Deliberately **code-blind**. |
| **Post-implementation** (code-aware) | **this skill + `coverage-analyst`** | Read the actual code for risk; confirm the spec's obligations are met **and actually run**. |

# Using harness-anchor

You have the **harness-anchor** runtime layer, companion to `superpowers` (process methodology): it anchors **state persistence, scope boundaries, verification gates, and C/C++ engineering**.

<!-- os-windows-start -->
**Windows session (Git-Bash):** plugin scripts already handle path and JSON-engine portability — do not hand-"fix" MSYS paths or shell out to PowerShell. C/C++ caveat: TSan/LSan are unavailable on this platform; read the `cpp-sanitizers` skill's Windows platform notes before trusting sanitizer coverage.
<!-- os-windows-end -->

## Priority Order

1. **User's explicit instructions** (CLAUDE.md, direct requests) — highest
2. **superpowers skills** (process)
3. **harness-anchor skills** (state/scope/verification/cpp)
4. Default system prompt — lowest