# harness-audit

Adopt this skill: https://proskills.md/skills/other/fabianmartinelli-fm-harness-audit-skills-harness-audit

Page: https://proskills.md/skills/other/fabianmartinelli-fm-harness-audit-skills-harness-audit
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/harness-audit/SKILL.md
size: 26030
sha: 7ab57b723c7b2fdfb943528950988f4a7deef970
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/SKILL.md

````text
---
name: harness-audit
description: Audits and restructures a project's AI agent harness (CLAUDE.md, AGENTS.md, GEMINI.md, rules, skills, hooks, docs and Obsidian vault notes) so an agent starts each session with a short map and finds the rest on demand, then installs the guardrails that keep it that way. Expect the win in speed, consistency and blast radius rather than in tokens. Run manually with /harness-audit diagnose | apply | verify | check. Supports Claude Code, Codex, Cursor and Antigravity CLI, with or without Obsidian.
license: MIT
compatibility: Python 3.9+ and git. Full support for Claude Code, Codex, Cursor and Antigravity CLI (legacy Gemini CLI treated as Antigravity). Use a frontier model for diagnose/apply.
metadata:
  version: "1.5.2"
  source: "https://github.com/fabianmartinelli-fm/harness-audit"
disable-model-invocation: true
argument-hint: "diagnose | apply | verify | check"
---

# Harness audit

Goal: an agent starts each session with a small, stable map and finds everything else on demand, and the project stays that way after you leave.

Evidence to keep in mind (details in `references/principles.md`): more always-loaded instructions degrade adherence and cost; auto-generated or redundant instruction files can lower task success; so this skill **removes and relocates** more than it writes, and **measures** before and after.

`SKILL_DIR` below means the folder containing this file. Scripts need only Python and git.

## Commands

| Command | Writes | Purpose |
|---|---|---|
| `diagnose` (default) | `.harness/reports/` only | Setup interview, inventory, baseline, scorecard, change plan |
| `apply` | project files, on a git branch, after approval | Execute the approved plan, install maintenance layer |
| `verify` | `.harness/reports/` | Re-measure, lock budgets, write the final report |
| `check` | nothing | Fast maintenance lint for periodic use |

If the user gives no argument, run `diagnose`. Never run `apply` without an approved plan from `diagnose` in this project.

Write every report and question in the user's language. Keep code, file names and frontmatter keys in English.

---

## diagnose

### 1. Detect, then confirm with the user

Run `python3 SKILL_DIR/scripts/detect.py --project .` and show a short summary. It scans the repo, parent folders and common locations (Documents, iCloud Obsidian, Dropbox, OneDrive) for Obsidian vaults; if the user keeps vaults elsewhere, rerun with `--search <folder>`. Then ask, in one message, with detected answers as defaults:

1. **Agents used on this project**: Claude Code, Codex, Cursor, Antigravity CLI (Gemini CLI counts as Antigravity).
2. **Obsidian**: does this project use an Obsidian vault? List the vaults found. If yes: which vault, which folder holds this project's notes, and the topology (`inside-repo`, `repo-inside-vault`, `external`).
3. **Where agent-facing knowledge should live**: repo `docs/` (portable, versioned, works for teammates and CI) or the vault folder (single place for the human). Explain the trade-off in one sentence each; see `references/obsidian.md`.
4. **Scope of user-level files** (`~/.claude`, `~/.codex`, `~/.gemini`): include them in the measurement? They affect every project, so they are measured but never changed without explicit per-file approval.

If the user already answered some of these earlier in the conversation, do not ask again.

### 2. Safety

Run `python3 SKILL_DIR/scripts/detect.py --project . --git-only` and read `upstream`.

- Require a git repo.
- **If the working tree is unclean, survey it before asking for anything.** In both pilots what
  sat uncommitted was real work: a submodule pointer carrying a whole release of another
  repository, tag included, and a month-old stash that took a line-by-line comparison to prove
  redundant. "Commit or stash first" without evidence asks the user to decide blind. Read
  `dirty` from the same `--git-only` output and present it item by item, in the user's language:
  - **untracked build output or dependencies** (`cache`): the folder, how many files, how big,
    and the `.gitignore` line that would cover it, proposed as text. Do not edit `.gitignore`.
  - **advanced submodule pointer** (`submodules`): the commits and tags between the recorded
    pointer and the current one. That list is what says whether it is work or leftovers.
  - **modified files** (`modified`): lines changed and how long since the file was touched.
  - **other untracked files** (`untracked`): path, size, date.
  - **stashes** (`stashes`): how many, from when, how many lines in how many files each.
  Each item carries an `evidence_command` the user can run to see it for themselves. Categories
  are capped at 20 items with the remainder reported as a count, and on a slow survey the
  itemised view is dropped in favour of counts (`degraded`); `python3 .harness/scripts/dirty.py`
  gives the full list on demand.
  Then present the options by name, in this order: **commit** the work on a branch, **keep it**
  with `git stash push`, or **discard it**. Say plainly that discarding is the only irreversible
  one. About the stash, say once: it moves the work out of the way without losing it, but a
  stash is easy to forget — the second pilot had a month-old one nobody ever applied, and
  proving it was redundant cost a line-by-line comparison — so for work with any value a branch
  commit holds up better than a growing stash stack. Never present discarding as the default or
  the recommendation, and never order the options with it first.
- **This skill never cleans a working tree.** Not with a generic approval, not inside `apply`,
  not "while we are here". It never runs `git stash`, `git checkout`, `git clean`, `git reset`,
  `git add` or `git commit` over the user's uncommitted work, and the survey itself is read-only.
  The user resolves the tree outside the skill; `apply` continues once `--git-only` comes back
  clean. This is a rule, not a preference.
- **Require the branch to be current with the remote.** A baseline measured on a stale branch
  measures files that no longer exist: in the second pilot the audit read a CLAUDE.md of 11,015
  lines while the remote had 13,071, and the mismatch only surfaced mid-`apply`.
  - `behind` greater than 0 and `ahead` 0: stop. Say how many commits are missing and offer
    `git pull --ff-only`.
  - `diverged`: stop and say so. Do not propose a rebase or a merge: in a repository with
    parallel sessions and worktrees that call is the user's.
  - No `upstream` and no `origin/HEAD` (`reference` is null): record it in the report and carry
    on; a local-only project has nothing to compare against.
  - `stale_comparison` is true (`behind` is 0 but the local copy of the remote is a day or more
    old): do not stop, and say one line — the comparison is against data from
    `reference_age_days` days ago, run `git fetch` to confirm. The scripts never fetch: writing
    to the network inside someone else's repository, unasked, is not this skill's call, and a
    `behind: 0` read from stale data is exactly the false comfort the second pilot ran into.
    When `behind` is above 0 the number already says enough and this note is redundant.
- If `git_environment.wrapper_suspected` is true, note it in the report: a different `git` is
  first on PATH. The scripts call the real binary, but anything you run by hand does not.
- Nothing is written outside `.harness/reports/` during diagnose.

### 3. Baseline

Both files below are written to disk before you discuss any number. `verify` compares
against them, and a later `apply` in a new session has nothing to stand on without them.

```bash
python3 SKILL_DIR/scripts/inventory.py --project . [--include-user] --out .harness/reports/inventory-baseline.json
python3 SKILL_DIR/scripts/measure.py snapshot --project . --label baseline [--include-user]
```

Confirm `.harness/reports/inventory-baseline.json` exists before continuing. If it is missing, rerun the command; do not proceed from numbers that live only in the conversation.

**The inventory is a lower bound, never the starting total.** It counts files. It cannot
count what plugins, MCP tool schemas, custom agents and `SessionStart` hook output add,
and that difference is large: in the first pilot the inventory read 9,288 always-on
tokens while a fresh session started at about 70,000. With `--include-user` the report
lists those sources under `user_runtime` (names and commands only, never executed, never
any env value or token), so the gap is visible instead of silent. **The authoritative
starting number is `/context` in a fresh session.** Ask for it, record it, and use it in
the report; treat the static estimate as the floor.

**`/context` understates the total when Claude reads `AGENTS.md` directly.** Since v2.1.277
Claude Code reads `AGENTS.md` on its own when no `CLAUDE.md`, `.claude/CLAUDE.md` or
`CLAUDE.local.md` sits in the working directory or above it — and that file appears in neither
`/memory` nor the Memory files list of `/context`. So in a project with an `AGENTS.md` and no
`CLAUDE.md`, ask the user for one more thing: the session line
`no CLAUDE.md found; AGENTS.md loaded: <path>`. If it is there, add the size of that file (the
inventory reports it under `conditional`, kind `agents-md-direct`) to the `/context` number and
say in the report why the two disagree. If it is not there, the file is not loaded at all and
the project is running with no instructions — which is the same evidence, read the other way.

The inventory never asserts that a direct read is happening: whether the session fetched feature
flags, whether it is the first one after an upgrade, and whether the `agents-md` plugin is
enabled are invisible from disk. It reports `undetermined` with the two ways to settle it
(`/config` → Project instructions, and the `AGENTS.md loaded` line), and keeps the file out of
the always-on total until you confirm. Report both numbers and their reason; do not pick one.

Read `instruction_resolution` in the inventory before writing any number: it says which file
each agent actually reads here, the `instructionFiles` value and where it came from,
`claudeMdExcludes` from every layer, the `CLAUDE.local.md` and `AGENTS.override.md` found, and
the Claude Code version. That is the part nobody can deduce from the repository alone.

Ask the user for numbers the scripts cannot read, and pass them with `--manual '{...}'`:
- Claude Code: output of `/context` in a fresh session (total and Memory files section), plus
  the `AGENTS.md loaded` line when the project has an `AGENTS.md` and no `CLAUDE.md`.
- Cursor: context usage shown in a fresh chat.
- Antigravity: `agy inspect` output for loaded context files, rules and skills.

**Say which chars-per-token ratio produced every estimate, and never call an estimate a
measurement.** The default 4.00 is the figure for running English prose; a harness is not
prose, and the third pilot measured 2.10 over 600,892 characters of dense technical
markdown — an error of 1.90x, always downwards, so a project twice over budget reads as
inside it. The cause is the shape of the text (tables, bold markers, backticked
identifiers, paths, UUIDs), not its language: a technical repository in English is
underestimated just as badly. Once you have a real `/context`, calibrate and record it:

```bash
python3 SKILL_DIR/scripts/measure.py calibrate --manual '{"context_memory_files_tokens": 285800}' --apply
```

Calibrating raises every estimate at once, which is the point — the old ones were a floor —
so H002 and the ratchet will fire on projects that looked inside their budget. Re-baseline
the ratchet afterwards with `lint.py --update-lock`.

**When the always-on estimate exceeds the context window of the smallest model in use, that
is a hard failure, not a budget overrun, and the report says so in those words.** In the
third pilot the `CLAUDE.md` alone was worth ~279,000 tokens: no 200k model could open the
project at all — not for a trivial question, with no tools loaded. Set
`budgets.context_window` in `.harness/config.json` to that model's window and H002 changes
its message accordingly; without it, the check is yours to make and to write down.

Optional but recommended: agree on 3 to 5 representative tasks for this project (see
`references/rubric.md`, "Task benchmark"). **The tasks are run by the user, in a fresh
session, on both sides of the comparison.** Not by you and not by a subagent: a subagent
inherits the context snapshot its parent session started with, so it measures the harness
as it was at startup, whatever is on disk now. The "before" side gets away with it only
by coincidence — at that point the startup snapshot and the disk still agree.

### 4. Read the harness

Read every always-on file listed in the inventory and a sample of the largest docs. For the agents in use, read the matching `references/agents/<agent>.md`. If Obsidian is in use, read `references/obsidian.md`.

### 5. Score and plan

Score the harness with `references/rubric.md`. Then **write `.harness/reports/plan.md` to disk
before presenting anything to the user**, using the structure in `references/report-template.md`
(section "Plan"). The file is the plan; what you say in the conversation is a summary of the
file. A plan that exists only in the conversation is lost the moment the session ends, and
`apply` in a new session will refuse to run.

Also record in the plan any missing sensor: if the project has no lint command, `install.py`
installs no code sensor, and that is a gap to state explicitly, not something to paper over by
installing a check that cannot run.

Each proposed change must state: what moves, from where, to where (per `assets/templates/PLACEMENT.md`), estimated always-on tokens saved per agent, and risk level:

- **low**: frontmatter, index, links, moving files into placement folders, deleting exact duplicates generated by tools.
- **medium**: moving content out of entry files into rules, skills or docs; scoping rules; converting prose rules into hooks or lint.
- **high**: merging or rewriting knowledge, archiving notes, anything outside the repo (user-level files, the vault when external).

Rules for the plan:
- Prefer relocation over rewriting. Keep the user's wording when moving content.
- Entry file target: a map, not an encyclopedia. One canonical `AGENTS.md` for all agents; `CLAUDE.md` starts with `@AGENTS.md` plus only Claude-specific lines; `GEMINI.md` should not repeat `AGENTS.md`.
- **Keep the `@AGENTS.md` import even though Claude Code can now read `AGENTS.md` by itself.**
  The import is the only arrangement that holds in every session, provider and configuration:
  a version before v2.1.277, the first session after an install or upgrade, Amazon Bedrock or
  any session without feature flags, telemetry disabled, `disableAllHooks`,
  `allowManagedHooksOnly`, the `agents-md` plugin switched off, or a teammate whose Project
  instructions is `claude-md`. It also survives a personal `CLAUDE.local.md`, which otherwise
  switches the direct read off for that one person. The import never causes a double read under
  any value of Project instructions — Claude Code skips an `AGENTS.md` it already loaded. Treat
  the direct read as a convenience that saves a file, not as an equivalent arrangement, and
  never plan to delete a `CLAUDE.md` whose only content is `@AGENTS.md`.
- Remove what agents can discover by themselves (directory listings, dependency lists, generic advice). Keep non-obvious commands, gotchas, and conventions that differ from defaults.
- Anything that must always happen becomes a hook, linter or CI step, not a sentence.
- **A rule that becomes a command guard carries three requirements**, and they are not
  optional refinements — the third pilot lost work to all three in one afternoon. This skill
  installs no command guard itself; these are requirements the plan writes into the project.
  1. The matcher matches the **command**, not the string anywhere in the text: strip
     heredocs and quoted content before matching. Without that, the guard refuses the commit
     whose message explains the rule, and every command written to fix the guard is blocked
     too, because each one quotes the string.
  2. A test case, in the project's own suite, asserting that
     `git commit -m "never use <forbidden command>"` **passes**. A sensor that gets in the
     way of writing about itself is a sensor someone switches off on a Friday night.
  3. After any block, check what of the call actually happened. A blocked call is aborted
     whole, so it takes unrelated work down with it, silently: in the pilot a refused Bash
     call also carried the creation of a script, and it was reported as existing for three
     turns before anyone noticed it never did.
- Never plan to delete knowledge. Superseded content gets `status: superseded`.

Present the scorecard and a summary of the plan grouped by risk, and say where the file is.
Ask the user to approve: low as a batch, medium per group, high item by item. Write the
approvals back into `plan.md` as they come in, so the decisions survive the session too.

---

## apply

0. Rerun the safety check: `python3 SKILL_DIR/scripts/detect.py --project . --git-only`. `apply`
   often runs in a later session, and the branch can have fallen behind since `diagnose`. Same
   rules as diagnose step 2, plus: if the branch moved at all since the baseline, say so and ask
   whether to re-measure before changing anything.
0b. Require the approved plan on disk. Read `.harness/reports/plan.md`; a baseline at
   `.harness/reports/inventory-baseline.json` should be there too. If `plan.md` is missing,
   refuse and say exactly this: the file `.harness/reports/plan.md` does not exist, so there is
   no approved plan in this project; recreate it by running `/harness-audit diagnose`, which
   writes the plan and the baseline before asking for approval. Never reconstruct the plan from
   memory or from the conversation.
1. `git switch -c harness-audit/<date>`.
2. Install the maintenance layer (dry run first, show the output, then apply):
   ```bash
   python3 SKILL_DIR/scripts/install.py --project . --agents <list> --docs-dir <dir> \
     [--vault-path <vault> --vault-topology <t>] --entry-blocks --with-precommit [--with-ci]
   python3 SKILL_DIR/scripts/install.py ... --apply
   ```
   The pre-commit goes into `.githooks/` (tracked by git) and `core.hooksPath` is pointed at it,
   so a clone gets the sensor and CI is not the only gate. Two cases where the installer steps
   back and tells you instead: `core.hooksPath` already points somewhere else (husky), where it
   installs there and changes nothing; and untracked executable hooks already in `.git/hooks`,
   where it installs nothing, because setting `core.hooksPath` would silently disable them.
   Relay that message to the user and let them decide. With a `package.json` present, a
   `prepare` script arms the hooks on `npm install`, and the entry file documents the manual
   command for everyone else.
   The opening budgets are set from what the project measures today, not from the default
   targets, and are marked `budgets_transitional` in `.harness/config.json`. A gate that is red
   on its first run blocks the very commits that are shrinking the harness, which is what
   happened in the second pilot. The photograph is the starting line; the ratchet does the
   lowering, exactly as the code sensor does. `lint.py` warns (`H019`) on every run while the
   mark is there, so a transitional budget cannot quietly become permanent.
3. Execute only approved plan items. Move scoped rules into `.harness/rules/` and procedures into `.harness/skills/`. Add frontmatter to docs. Slim entry files.
4. Regenerate and check:
   ```bash
   python3 .harness/scripts/sync.py
   python3 .harness/scripts/build_index.py
   python3 .harness/scripts/lint.py
   ```
   Fix errors. Warnings may remain only if listed in the report with a reason.
5. Append to the docs log: `## [YYYY-MM-DD] audit | harness restructured (see .harness/reports/)`.
6. Commit in small, reviewable commits (install, relocation, entry files). Do not merge: the user reviews the branch.

For agent-specific install steps (Codex hook trust, Antigravity hook schema, Cursor restart), follow `references/agents/<agent>.md`.

---

## verify

1. Ask the user to open a fresh session in each agent and share the same manual numbers as the
   baseline. The comparison that matters is `/context` before against `/context` after: the
   script totals are a lower bound and miss plugins, MCP servers, agents and hook output.
   If the project has an `AGENTS.md` and no `CLAUDE.md`, ask again for the
   `no CLAUDE.md found; AGENTS.md loaded: <path>` line and add that file to both sides of the
   comparison — `/context` leaves it out, so comparing the raw numbers would credit the audit
   with a reduction it did not make, or hide one it did.
2. `python3 .harness/scripts/measure.py snapshot --label after --manual '{...}'`
3. `python3 .harness/scripts/measure.py compare --before baseline --after after`
4. **Measure what you can measure alone, and hand the rest back.** `verify` produces on its
   own: the `/context` comparison (from the number the user pastes, as in step 1), lint,
   budgets and ratchet, entry-file sizes, and Codex read coverage (`AGENTS.md` bytes against
   `project_doc_max_bytes`). It cannot produce the behavioural half. Say so in one sentence
   rather than leaving it out: **you cannot open a fresh session, and a subagent inherits the
   context snapshot this session started with, so it would measure the harness as it was
   before the change, not as it is now.** Promising it anyway is what cost the third pilot
   2.17M tokens and five confident, false verdicts.
   So, if task benchmarks were agreed: prove the environment, then present the prompts.
   ```bash
   python3 .harness/scripts/benchenv.py --dir <worktree> --commit <audit commit> --main .
   ```
   Run it for every directory a task will run in, **before** the battery and **again after**
   — an environment can change in the middle, and a task believed to be read-only wrote a
   migration file into the main tree in the pilot. Exit 1 means abort: do not launch to see
   what happens. Paste its output into the report beside the verdicts.
   Then give the user the prompts, ask them to run each one in a fresh session of the agent
   and model being measured, and ask for, per task: success, turns, startup and peak context,
   **tokens and tool uses**, irrelevant files read, human corrections.
5. Feed the task numbers back in and let the comparison judge them:
   `measure.py snapshot --label after --manual '{"tasks": [{"id": "T1", "tokens_before": …, "tokens_after": …}]}'`.
   `compare` exits 2 when a large always-on reduction comes back with a flat per-task cost:
   those two numbers cannot both be right, and the usual cause is an environment that is not
   the one the audit changed. Do not report verdicts from a run that exits 2.
6. If always-on context went up for any agent, or benchmarks got worse, say so plainly and propose a rollback of the responsible change.
7. Lock the new budgets so they can only shrink:
   `python3 .harness/scripts/lint.py --update-lock --close-transitional`.
   `--update-lock` on its own records the ratchet baseline and leaves the transitional
   budgets alone, because closing them freezes whatever the project measures at that moment
   as its permanent budget: run halfway through a migration it locks in the half-migrated
   state and removes the H019 that says the budget is provisional. `--close-transitional`
   belongs here, once, when the plan is done. It prints the before and after per budget and
   per agent — show that output to the user.
8. Write `.harness/reports/HARNESS-REPORT.md` with `references/report-template.md` (section
   "Final report"). Every number in it records **which process produced it**: a fresh session
   run by the user, a local script, or a subagent.

---

## check

`python3 .harness/scripts/lint.py` (or `SKILL_DIR/scripts/lint.py` if not installed yet), plus
`python3 .harness/scripts/code_sensor.py` when a code sensor is installed. Summarize findings by severity, propose fixes, and suggest a full `diagnose` when budgets are breached (`H002`, `H006`, `H015`) or more than 10 warnings accumulated.

`H020`, `H021` and `H022` are about which instruction file each agent ends up reading, and all
three are silent in daily use: a personal `CLAUDE.local.md` that switches the team's `AGENTS.md`
off for one person, a `CLAUDE.md` over 4 MiB that Claude Code skips whole instead of truncating,
and an `AGENTS.override.md` that Codex reads with precedence and Claude Code never reads. Report
them with the resolution line from the inventory, not on their own.

## Reference files

- `references/principles.md`: why this design (context rot, instruction budget, progressive disclosure, guides and sensors). Read once per audit.
- `references/rubric.md`: scorecard criteria, thresholds, task benchmark method.
- `references/obsidian.md`: vault topologies and how agents reach notes.
- `references/agents/claude-code.md`, `codex.md`, `cursor.md`, `antigravity.md`: what each agent loads and how its hooks work.
- `references/report-template.md`: plan and final report structure.
- `assets/templates/PLACEMENT.md`: the placement map installed into the project.
- `scripts/dirty.py`: read-only survey of an unclean working tree (cache, submodule pointers, modified files, untracked files, stashes) with the evidence for each.
- `scripts/code_sensor.py`: per-file ratchet over the project's own linter (fails only when a file gets worse). Configured under `code_sensor` in `.harness/config.json`.
- `scripts/benchenv.py`: proves a benchmark directory is on the commit you think it is, with
  observable artefacts, and that the main tree is clean. Exit 1 aborts.
````

## File: skills/harness-audit/scripts/benchenv.py
size: 6662
sha: f2de221dca2a550b3aa12c34b3e51332d95fc15e
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/benchenv.py

```text
#!/usr/bin/env python3
"""Prove which harness a benchmark environment actually contains, before anything runs there.

The third pilot ran the whole "after" battery in worktrees born from the default branch
instead of the audit commit. All five tasks measured the old harness: a CLAUDE.md of 6,198
lines, no docs/, no scoped rules. ~2.17M tokens spent, no valid measurement, and — worse
than the waste — five confident verdicts that were false, written up as if the new rules
had fired when no rule existed in that tree at all.

Two `git` calls would have caught it. So they are a script, not a sentence in a rubric:
anything that must always happen is a sensor here, and a check that depends on someone
remembering to run it is not ready.

Usage:
  python3 benchenv.py --dir <worktree> --commit <sha>      prove it, exit 1 if it does not hold
  python3 benchenv.py --dir <worktree> --commit <sha> --json

What it proves, in order:
  1. the directory is a git worktree and which commit its HEAD is on;
  2. the audit commit is an ancestor of that HEAD (so the change is present);
  3. observable artefacts of the new state: entry-file line counts, the docs directory,
     the scoped rules on disk. A commit id is a claim; these are the evidence.
  4. that the main tree is clean, which is how a task that "only reads" is caught writing.

Run it before the battery and again after: an environment can change in the middle, and
the proof belongs in the report next to the verdicts.
"""
from __future__ import annotations

import argparse
import json
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
from hlib import docs_root, find_project_root, git, git_ok, load_config, read_text  # noqa: E402

ENTRY = ("CLAUDE.md", "AGENTS.md", "GEMINI.md", "AGENTS.override.md")

def artefacts(d: Path) -> dict:
    """What the directory actually contains, readable without trusting any commit id."""
    cfg = load_config(d)
    docs = docs_root(d, cfg)
    rules = []
    for sub in (".harness/rules", ".claude/rules", ".cursor/rules", ".agents/rules"):
        rules += [str(p.relative_to(d)) for p in sorted((d / sub).glob("*.md*"))]
    return {
        "entry_file_lines": {n: read_text(d / n).count("\n") + 1 for n in ENTRY if (d / n).is_file()},
        "docs_dir": str(cfg.get("docs_dir")),
        "docs_dir_exists": docs.is_dir(),
        "docs_files": len(list(docs.rglob("*.md"))) if docs.is_dir() else 0,
        "scoped_rules": rules,
        "harness_installed": (d / ".harness/config.json").is_file(),
    }

def prove(d: Path, commit: str | None, main: Path | None) -> dict:
    problems = []
    inside = git(d, "rev-parse", "--is-inside-work-tree").strip() == "true"
    if not inside:
        problems.append(f"{d} is not a git worktree: nothing here can be proved")
        return {"dir": str(d), "ok": False, "problems": problems}
    head = git(d, "rev-parse", "HEAD").strip()
    common = git(d, "rev-parse", "--git-common-dir").strip()
    own = git(d, "rev-parse", "--absolute-git-dir").strip()
    isolated = bool(common and own and Path(common).resolve() != Path(own).resolve())
    out = {
        "dir": str(d),
        "head": head,
        "branch": git(d, "rev-parse", "--abbrev-ref", "HEAD").strip(),
        "separate_worktree": isolated,
        "expected_commit": commit,
        "artefacts": artefacts(d),
    }
    if commit:
        resolved = git(d, "rev-parse", "--verify", f"{commit}^{{commit}}").strip()
        if not resolved:
            problems.append(f"commit {commit} does not exist in {d}: the change is not even fetched here")
        else:
            out["expected_commit_resolved"] = resolved
            ok = git_ok(d, "merge-base", "--is-ancestor", resolved, head)
            out["commit_is_ancestor"] = ok
            if not ok:
                problems.append(
                    f"HEAD {head[:12]} does not contain {resolved[:12]}: this environment is NOT the one "
                    "the audit changed. Every number measured here describes the old harness.")
    if main is not None:
        dirty = [l for l in git(main, "status", "--porcelain").splitlines() if l.strip()]
        out["main_tree"] = str(main)
        out["main_tree_clean"] = not dirty
        out["main_tree_changes"] = dirty[:20]
        if dirty:
            problems.append(
                f"the main tree {main} has {len(dirty)} uncommitted change(s): a benchmark task wrote "
                "outside its isolation. 'This task only reads' is a hypothesis about the agent, and the "
                "benchmark exists because that hypothesis is not reliable.")
    # Isolation is reported, never assumed: a task believed to be read-only wrote a
    # migration file straight into the main tree in the third pilot.
    if not isolated:
        problems.append(f"{d} is the main working tree, not an isolated worktree: a task that writes "
                        "will write into the project itself")
    out["ok"] = not problems
    out["problems"] = problems
    return out

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--dir", required=True, help="the directory the benchmark task will run in")
    ap.add_argument("--commit", help="the audit commit that must be an ancestor of its HEAD")
    ap.add_argument("--main", help="the project's main working tree, checked for stray writes")
    ap.add_argument("--json", action="store_true")
    a = ap.parse_args()
    d = Path(a.dir).expanduser().resolve()
    main_tree = find_project_root(Path(a.main).expanduser()) if a.main else None
    out = prove(d, a.commit, main_tree)
    if a.json:
        print(json.dumps(out, indent=2))
    else:
        print(f"dir:      {out['dir']}")
        print(f"head:     {out.get('head', '-')} ({out.get('branch', '-')})")
        print(f"worktree: {'isolated' if out.get('separate_worktree') else 'MAIN TREE'}")
        if a.commit:
            print(f"contains {a.commit}: {out.get('commit_is_ancestor')}")
        art = out.get("artefacts", {})
        print(f"entry files: {art.get('entry_file_lines')}")
        print(f"docs: {art.get('docs_dir')} exists={art.get('docs_dir_exists')} files={art.get('docs_files')}")
        print(f"scoped rules: {len(art.get('scoped_rules', []))}")
        if "main_tree_clean" in out:
            print(f"main tree clean: {out['main_tree_clean']}")
        for x in out["problems"]:
            print(f"PROBLEM: {x}")
        print("OK: this environment is the one you think it is" if out["ok"]
              else "ABORT: do not launch the benchmark here")
    sys.exit(0 if out["ok"] else 1)

if __name__ == "__main__":
    main()
```

## File: skills/harness-audit/scripts/build_index.py
size: 3192
sha: 97e2670a94a863e4f7495f0aa50f8aaec7ccb025
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/build_index.py

```text
#!/usr/bin/env python3
"""Generate the docs index from frontmatter. The index is generated, never hand-written.

Each entry: link | one-line description | read when | status | updated.
Content between the harness markers is replaced; anything outside is preserved.
Works as an Obsidian note too (standard markdown links resolve in Obsidian).

Usage: python3 build_index.py [--project PATH] [--check]
Exit 1 with --check when the index is out of date.
"""
from __future__ import annotations

import argparse
import os
import sys
from pathlib import Path

from hlib import doc_rel, docs_root, find_project_root, index_path, iter_md, load_config, parse_frontmatter, read_text, rel

START, END = "<!-- harness:index:start -->", "<!-- harness:index:end -->"
HEADER = """---
description: Generated catalog of project knowledge. Read first, then open only what the task needs.
status: active
---
# Index

Generated by `.harness/scripts/build_index.py`. Do not edit between the markers.
"""

def render(root: Path, cfg: dict) -> str:
    ipath = index_path(root, cfg)
    droot = docs_root(root, cfg)
    groups = {}
    for p in sorted(iter_md(droot, exclude=cfg["index"].get("exclude", []))):
        if p.resolve() == ipath.resolve():
            continue
        fm, _ = parse_frontmatter(read_text(p))
        parts = Path(doc_rel(root, cfg, p)).parts
        group = "/".join(parts[:-1]) if len(parts) > 1 else "(root)"
        link = os.path.relpath(p, ipath.parent).replace(os.sep, "/")
        desc = str(fm.get("description", "")).replace("|", "/") or "MISSING DESCRIPTION"
        when = str(fm.get("read_when", "")).replace("|", "/")
        groups.setdefault(group, []).append(
            f"| [{p.stem}]({link.replace(' ', '%20')}) | {desc} | {when} | {fm.get('status', '')} | {fm.get('updated', '')} |")
    lines = [START, ""]
    for g in sorted(groups):
        lines += [f"## {g}", "", "| Doc | What it is | Read when | Status | Updated |", "|---|---|---|---|---|"]
        lines += groups[g] + [""]
    if not groups:
        lines.append("_No documents yet._\n")
    lines.append(END)
    return "\n".join(lines)

def merged(current: str, block: str) -> str:
    if START in current and END in current:
        pre = current.split(START)[0]
        post = current.split(END, 1)[1]
        return pre + block + post
    return HEADER + "\n" + block + "\n"

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--project", default=".")
    ap.add_argument("--check", action="store_true")
    a = ap.parse_args()
    root = find_project_root(Path(a.project))
    cfg = load_config(root)
    path = index_path(root, cfg)
    current = read_text(path) if path.exists() else ""
    new = merged(current, render(root, cfg))
    if a.check:
        if new.strip() != current.strip():
            print(f"index out of date: run python3 .harness/scripts/build_index.py", file=sys.stderr)
            sys.exit(1)
        print("index up to date")
        return
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(new if new.endswith("\n") else new + "\n", encoding="utf-8")
    print(f"wrote {rel(root, path)}")

if __name__ == "__main__":
    main()
```

## File: skills/harness-audit/scripts/code_sensor.py
size: 5322
sha: 53da25235f2f4e8e55e3d097cfcb1800e8fb5210
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/code_sensor.py

```text
#!/usr/bin/env python3
"""Per-file ratchet over a project's own linter. Fails only when a file gets worse.

A binary gate is unusable on a codebase that already has problems: the first pilot
had 57 pre-existing ESLint errors, so "zero errors" would have blocked every commit
and been switched off within a day. Instead we record how many problems each file
has today and fail only when a file goes above its own line. Improvements are reported
but never written back on their own: moving the line is a deliberate act
(--update-baseline), because the baseline is a tracked generated file and silently
rewriting it on every commit that fixes something is a standing merge conflict.

  python3 code_sensor.py [--project PATH] [--update-baseline] [--staged]

The command and output format come from .harness/config.json:

  "code_sensor": {"command": "npx eslint . --format json", "format": "eslint-json",
                  "baseline": ".harness/eslint-baseline.json"}

format is "eslint-json" (an ESLint JSON report) or "text" (any tool that prints one
problem per line as path:line:col: message or path(line,col): message). Nothing here
is ESLint-specific beyond that default.
Exit: 0 ok or baseline created, 1 a file got worse, 2 sensor misconfigured.
"""
from __future__ import annotations

import argparse
import json
import re
import subprocess
import sys
from pathlib import Path

HERE = Path(__file__).resolve().parent
sys.path.insert(0, str(HERE))
from hlib import changed_files, find_project_root, load_config, read_text, rel  # noqa: E402

DEFAULT_BASELINE = ".harness/code-baseline.json"
TEXT_RE = re.compile(r"^\s*([^\s:(][^:(]*\.[A-Za-z0-9]+)[:(](\d+)")

def config(root: Path) -> dict:
    return load_config(root).get("code_sensor") or {}

def parse_eslint_json(out: str, root: Path) -> dict:
    try:
        data = json.loads(out or "[]")
    except ValueError:
        return {}
    counts = {}
    for f in data if isinstance(data, list) else []:
        path = f.get("filePath")
        if not path:
            continue
        n = int(f.get("errorCount", 0)) + int(f.get("warningCount", 0))
        if n:
            counts[rel(root, Path(path))] = n
    return counts

def parse_text(out: str, root: Path) -> dict:
    counts = {}
    for line in (out or "").splitlines():
        m = TEXT_RE.match(line)
        if not m:
            continue
        p = Path(m.group(1))
        key = rel(root, p if p.is_absolute() else root / p)
        counts[key] = counts.get(key, 0) + 1
    return counts

def run(root: Path, cfg: dict):
    proc = subprocess.run(cfg["command"], shell=True, cwd=str(root), capture_output=True, text=True)
    out = proc.stdout + ("" if cfg.get("format") == "eslint-json" else "\n" + proc.stderr)
    fmt = cfg.get("format", "text")
    return parse_eslint_json(proc.stdout, root) if fmt == "eslint-json" else parse_text(out, root)

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--project", default=".")
    ap.add_argument("--update-baseline", action="store_true", help="accept current counts as the new line")
    ap.add_argument("--staged", action="store_true", help="only judge files staged for commit")
    a = ap.parse_args()
    root = find_project_root(Path(a.project))
    cfg = config(root)
    if not cfg.get("command"):
        print("code_sensor: no command in .harness/config.json -> code_sensor.command; nothing to check.")
        return 2

    counts = run(root, cfg)
    bpath = root / cfg.get("baseline", DEFAULT_BASELINE)
    fresh = not bpath.exists()
    base = {} if fresh else (json.loads(read_text(bpath) or "{}") or {})
    scope = set(changed_files(root, staged_only=True)) if a.staged else None

    worse = [(f, base.get(f, 0), n) for f, n in sorted(counts.items())
             if n > base.get(f, 0) and (scope is None or f in scope)]

    if fresh or a.update_baseline:
        bpath.parent.mkdir(parents=True, exist_ok=True)
        bpath.write_text(json.dumps(counts, indent=2, sort_keys=True) + "\n", encoding="utf-8")
        print(f"code_sensor: baseline {'created' if fresh else 'updated'} at {rel(root, bpath)} "
              f"({sum(counts.values())} problem(s) in {len(counts)} file(s)). Commit it.")
        return 0

    if worse:
        print("code_sensor: these files got worse than their baseline:")
        for f, was, now in worse:
            print(f"  {f}: {was} -> {now}")
        print("Fix them, or run: python3 .harness/scripts/code_sensor.py --update-baseline "
              "(and say in the commit why the line moved up).")
        return 1

    gone = sum(base.get(f, 0) - counts.get(f, 0) for f in base if counts.get(f, 0) < base.get(f, 0))
    if gone:
        # Tightening the line is the user's call, never a side effect of a commit that
        # happened to fix something: the baseline is a generated file, and rewriting it
        # behind people's backs turns every improvement into a merge conflict for the team.
        print(f"code_sensor: ok, {gone} problem(s) fewer than the baseline. "
              f"Consolidate when you want to with: python3 .harness/scripts/code_sensor.py --update-baseline")
        return 0
    print(f"code_sensor: ok, no file above its baseline ({sum(counts.values())} known problem(s)).")
    return 0

if __name__ == "__main__":
    sys.exit(main())
```

## File: skills/harness-audit/scripts/detect.py
size: 5767
sha: d7675e96fd51a9b27db4add9fbe2a9df4a915e26
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/detect.py

```text
#!/usr/bin/env python3
"""Pre-interview detection. The skill shows these findings to the user and asks to confirm.

Detects: agents configured in the project, Obsidian vaults (inside the repo, in parent
folders, and in common locations), candidate docs folders, git state.

Usage: python3 detect.py [--project PATH] [--search ~/Some/Folder ...] [--git-only]

--git-only prints just the git state (clean tree, distance from the upstream). apply
reruns it, because apply can happen in a different session hours after diagnose.
"""
from __future__ import annotations

import argparse
import os
import re
from pathlib import Path

import dirty
from hlib import HOME, detect_agents, dump_json, find_project_root, git, git_environment, rel, upstream_state

COMMON_VAULT_PARENTS = [
    HOME / "Documents", HOME / "Obsidian", HOME / "obsidian", HOME / "Vaults", HOME / "Notes",
    HOME / "Library/Mobile Documents/iCloud~md~obsidian/Documents",
    HOME / "Dropbox", HOME / "OneDrive", HOME / "Google Drive", HOME,
]

def vaults_under(base: Path, max_depth: int):
    found = []
    if not base.is_dir():
        return found
    base_depth = len(base.parts)
    for dirpath, dirnames, _ in os.walk(base):
        depth = len(Path(dirpath).parts) - base_depth
        if ".obsidian" in dirnames:
            found.append(Path(dirpath))
        dirnames[:] = [d for d in dirnames if not d.startswith(".") and d not in ("node_modules", "Library")
                       and depth < max_depth]
    return found

def name_tokens(name: str) -> set:
    """The parts of a project name worth matching a folder against.

    Repository directories carry suffixes the note folder does not: `tavoloo` in the vault
    against `tavoloo-fmsolutions-main` on disk. Exact-name matching missed that in the third
    pilot. Tokens shorter than 4 characters are dropped — `api`, `web` or `app` would match
    half a vault.
    """
    parts = {p for p in re.split(r"[-_. ]+", name.lower()) if len(p) >= 4}
    if len(name) >= 4:
        parts.add(name.lower())
    return parts

def folders_like_project(vault: Path, project_name: str):
    tokens = name_tokens(project_name)
    if not tokens:
        return []
    out = []
    for d in vault.rglob("*"):
        if not d.is_dir() or ".obsidian" in d.parts:
            continue
        dn = d.name.lower()
        if dn in tokens or any(t in dn for t in tokens):
            out.append(d)
    return sorted(out)

def topology(root: Path, vault: Path) -> str:
    r, v = root.resolve(), vault.resolve()
    if v == r or str(v).startswith(str(r) + os.sep):
        return "inside-repo"
    if str(r).startswith(str(v) + os.sep):
        return "repo-inside-vault"
    return "external"

def git_state(root: Path) -> dict:
    return {
        "project": str(root),
        "is_git_repo": bool(git(root, "rev-parse", "--is-inside-work-tree").strip()),
        "branch": git(root, "rev-parse", "--abbrev-ref", "HEAD").strip(),
        "uncommitted_changes": len([l for l in git(root, "status", "--porcelain").splitlines() if l]),
        "dirty": dirty.survey(root),
        "upstream": upstream_state(root),
        "git_environment": git_environment(),
    }

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--project", default=".")
    ap.add_argument("--git-only", action="store_true", help="print only the git state (fast)")
    ap.add_argument("--search", nargs="*", default=[], help="extra folders to scan for vaults")
    a = ap.parse_args()
    root = find_project_root(Path(a.project))
    if a.git_only:
        print(dump_json(git_state(root), None))
        return

    candidates = set(vaults_under(root, 4))
    for p in root.parents:
        if (p / ".obsidian").is_dir():
            candidates.add(p)
    for extra in a.search:
        candidates.update(vaults_under(Path(extra).expanduser(), 3))
    for base in COMMON_VAULT_PARENTS:
        candidates.update(vaults_under(base, 2 if base != HOME else 1))

    vaults = []
    for v in sorted(candidates):
        project_folders = [rel(v, d) for d in folders_like_project(v, root.name)][:5]
        vaults.append({"path": str(v), "topology": topology(root, v),
                       "folders_named_like_project": project_folders,
                       # An empty match list is not an answer, it is the absence of one. The
                       # third pilot read `[]` and nearly concluded the project had no
                       # knowledge layer at all, while `B01 Projetos/tavoloo/` sat there with
                       # an overview, 204 lines of decisions and 361 of log. Listing the
                       # top level costs nothing and lets a human settle it in one look.
                       "top_level_folders": sorted(d.name for d in v.iterdir()
                                                   if d.is_dir() and not d.name.startswith("."))[:40]})

    docs_candidates = [d for d in ("docs", "doc", "documentation", "wiki", "notes", "knowledge", "agent_docs")
                       if (root / d).is_dir()]
    result = {
        **git_state(root),
        "agents_detected": detect_agents(root),
        "obsidian_vaults_found": vaults,
        "docs_folder_candidates": docs_candidates,
        "harness_installed": (root / ".harness/config.json").exists(),
        "questions_to_confirm": [
            "Which agents do you use on this project? (detected list is a suggestion)",
            "Do you use Obsidian with this project? If yes, which vault and which folder holds this project's notes?",
            "Should agent-facing knowledge live in the repo (docs/) or in the vault folder?",
            "Language for reports?",
        ],
    }
    print(dump_json(result, None))

if __name__ == "__main__":
    main()
```

## File: skills/harness-audit/scripts/dirty.py
size: 11037
sha: bda773a78727ce8400b13f72a88bd5da595ee5ea
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/dirty.py

```text
#!/usr/bin/env python3
"""Read-only survey of an unclean working tree, so the user decides with evidence.

In both pilots what sat uncommitted was real work: a submodule pointer carrying a whole
release of another repository, tag included, and a month-old stash that took a line-by-line
comparison to prove redundant. Both times the agent investigated on its own initiative.
"Commit or stash first" without that survey asks the user to decide blind.

  python3 dirty.py [--project PATH]

This module NEVER writes: no stash, checkout, clean, reset, add or commit, and no .gitignore
edit. It runs read-only git commands through hlib.git (the real binary) and returns facts.
It also never copies file content into the report: the report lands in .harness/reports/,
which is versioned and shared, and the working tree it describes is someone's unfinished
work. Paths, sizes, line counts and dates only; user-written text (a stash subject, a
submodule commit message) is clipped and passed through the secret mask.
"""
from __future__ import annotations

import argparse
import os
import re
import sys
import time
from pathlib import Path

HERE = Path(__file__).resolve().parent
sys.path.insert(0, str(HERE))
from hlib import dump_json, find_project_root, git, mask_secrets, safe_command  # noqa: E402

# Directory and file names that mean "build output or installed dependency", not work.
CACHE_NAMES = {
    "node_modules", ".next", ".nuxt", ".svelte-kit", ".pnpm-store", ".yarn", ".turbo", ".parcel-cache",
    "dist", "build", "out", "target", "coverage", ".coverage", "__pycache__", ".pytest_cache",
    ".mypy_cache", ".ruff_cache", ".venv", "venv", ".gradle", ".tox", "vendor", ".terraform",
}
CACHE_SUFFIXES = (".pyc", ".pyo", ".log", ".tsbuildinfo")
MAX_ITEMS = 20          # per category; the rest is reported as a count
# Past this, stop describing items one by one: the survey runs on every --git-only call,
# including apply's step 0. Overridable so the degraded path can be exercised.
SLOW_SECONDS = float(os.environ.get("HARNESS_DIRTY_SLOW_SECONDS", "2.0"))
SUBJECT_CHARS = 80

def safe_text(text: str) -> str:
    """User-written text (stash subject, commit message): clipped and masked."""
    return safe_command(text, SUBJECT_CHARS)

def safe_path(rel_path: str) -> str:
    """A path is data too: a filename can carry a credential (an exported .env, a dumped token),
    and this report is versioned."""
    return mask_secrets(rel_path)

def is_cache(rel_path: str) -> bool:
    parts = Path(rel_path).parts
    return any(p in CACHE_NAMES for p in parts) or rel_path.endswith(CACHE_SUFFIXES)

def cache_root(rel_path: str) -> str:
    parts = Path(rel_path).parts
    for i, p in enumerate(parts):
        if p in CACHE_NAMES:
            return "/".join(parts[:i + 1]) + "/"
    return rel_path

def stat_of(root: Path, rel_path: str):
    p = root / rel_path
    try:
        st = p.stat()
        return st.st_size, int((time.time() - st.st_mtime) // 86400)
    except OSError:
        return 0, None

def dir_totals(root: Path, rel_dir: str):
    files = size = 0
    for p in (root / rel_dir).rglob("*"):
        try:
            if p.is_file():
                files += 1
                size += p.stat().st_size
        except OSError:
            continue
    return files, size

def human(size: int) -> str:
    for unit in ("B", "KB", "MB", "GB"):
        if size < 1024 or unit == "GB":
            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
        size /= 1024.0
    return f"{size:.1f} GB"

def parse_status(root: Path):
    """One status call feeds every category: a second pass over a large tree is wasted time."""
    modified, untracked, submodules = [], [], []
    for line in git(root, "status", "--porcelain", "--untracked-files=all").splitlines():
        if len(line) < 4:
            continue
        code, path = line[:2], line[3:].split(" -> ")[-1].strip().strip('"')
        if code == "??":
            untracked.append(path)
        elif code.strip():
            (submodules if (root / path).is_dir() else modified).append((code, path))
    return modified, untracked, submodules

def numstat_map(root: Path, *args):
    out = {}
    for line in git(root, "diff", "--numstat", *args).splitlines():
        parts = line.split("\t")
        if len(parts) == 3:
            added, removed, path = parts
            a, r = (0 if added == "-" else int(added)), (0 if removed == "-" else int(removed))
            prev = out.get(path, (0, 0))
            out[path] = (prev[0] + a, prev[1] + r)
    return out

def modified_items(root: Path, modified):
    work = numstat_map(root)
    staged = numstat_map(root, "--cached")
    items = []
    for code, path in modified:
        a, r = work.get(path, (0, 0))
        sa, sr = staged.get(path, (0, 0))
        _, age = stat_of(root, path)
        items.append({"path": safe_path(path), "status": code.strip(), "added": a + sa, "removed": r + sr,
                      "staged": bool(code[0].strip()), "age_days": age,
                      "evidence_command": safe_path(f"git diff -- {path}")})
    items.sort(key=lambda x: -(x["added"] + x["removed"]))
    return items

def untracked_items(root: Path, untracked):
    """Cache is grouped by its root directory; a list of 12,000 files helps nobody."""
    caches, plain = {}, []
    for path in untracked:
        if is_cache(path):
            caches.setdefault(cache_root(path), 0)
            caches[cache_root(path)] += 1
            continue
        size, age = stat_of(root, path)
        plain.append({"path": safe_path(path), "size_bytes": size, "size": human(size), "age_days": age})
    plain.sort(key=lambda x: -x["size_bytes"])
    cache_items = []
    for rel_dir in sorted(caches):
        if rel_dir.endswith("/"):
            files, size = dir_totals(root, rel_dir.rstrip("/"))
        else:
            size, _ = stat_of(root, rel_dir)
            files = 1
        cache_items.append({"path": safe_path(rel_dir), "files": files, "size_bytes": size, "size": human(size),
                            "suggested_gitignore": safe_path(rel_dir),
                            "note": "build output or installed dependency; proposed only, nothing written"})
    cache_items.sort(key=lambda x: -x["size_bytes"])
    return cache_items, plain

def submodule_items(root: Path, candidates):
    """The commits and tags between the recorded pointer and the current one are the evidence
    that says whether an advanced submodule is work or leftovers."""
    items = []
    for _, path in candidates:
        recorded = ""
        for line in git(root, "ls-files", "-s", path).splitlines():
            parts = line.split()
            if len(parts) >= 2:
                recorded = parts[1]
        current = git(root, "-C", path, "rev-parse", "HEAD").strip() if (root / path / ".git").exists() else ""
        sub = root / path
        if not recorded or not current or recorded == current:
            continue
        commits, tags = [], []
        for line in git(sub, "log", "--format=%h%x09%s", f"{recorded}..{current}").splitlines()[:MAX_ITEMS]:
            h, _, subject = line.partition("\t")
            commits.append({"commit": h, "subject": safe_text(subject)})
            for t in git(sub, "tag", "--points-at", h).split():
                tags.append(t)
        items.append({"path": safe_path(path), "recorded": recorded[:12], "current": current[:12],
                      "commits": commits, "tags": sorted(set(tags)),
                      "evidence_command": safe_path(
                          f"git -C {path} log --oneline {recorded[:12]}..{current[:12]}")})
    return items

def stash_items(root: Path):
    items = []
    # %cI, not --date=iso: --date rewrites %gd into stash@{2026-09-18 ...}, and the ref has to
    # stay stash@{0} for the evidence command to be usable.
    for line in git(root, "stash", "list", "--format=%gd%x09%cI%x09%s").splitlines():
        ref, _, rest = line.partition("\t")
        when, _, subject = rest.partition("\t")
        files = added = removed = 0
        for stat_line in git(root, "stash", "show", "--numstat", ref).splitlines():
            parts = stat_line.split("\t")
            if len(parts) == 3:
                files += 1
                added += 0 if parts[0] == "-" else int(parts[0])
                removed += 0 if parts[1] == "-" else int(parts[1])
        age = None
        m = re.match(r"(\d{4})-(\d{2})-(\d{2})", when)
        if m:
            import datetime
            age = (datetime.date.today() - datetime.date(*(int(x) for x in m.groups()))).days
        items.append({"ref": ref, "date": when[:10], "age_days": age, "files": files,
                      "added": added, "removed": removed, "subject": safe_text(subject),
                      "evidence_command": f"git stash show -p {ref}"})
    return items

def cap(items, kind):
    """Cap every category: a report is evidence, not a dump."""
    return {kind: items[:MAX_ITEMS], f"{kind}_total": len(items),
            f"{kind}_omitted": max(0, len(items) - MAX_ITEMS)}

def survey(root: Path) -> dict:
    started = time.time()
    modified_raw, untracked_raw, sub_raw = parse_status(root)
    result = {"clean": not (modified_raw or untracked_raw or sub_raw) and not git(root, "stash", "list").strip(),
              "read_only": True}
    result.update(cap(modified_items(root, modified_raw), "modified"))
    caches, plain = untracked_items(root, untracked_raw)
    result.update(cap(caches, "cache"))
    result.update(cap(plain, "untracked"))
    result.update(cap(submodule_items(root, sub_raw), "submodules"))
    result.update(cap(stash_items(root), "stashes"))
    result["elapsed_seconds"] = round(time.time() - started, 2)
    if result["elapsed_seconds"] > SLOW_SECONDS:
        # A big tree with node_modules unignored can make the per-item walk the slow part of
        # every --git-only call, including apply's step 0. Keep the counts, drop the detail.
        for kind in ("modified", "cache", "untracked", "stashes"):
            result[f"{kind}_omitted"] = result[f"{kind}_total"]
            result[kind] = []
        result["degraded"] = (f"survey took {result['elapsed_seconds']}s; reporting counts only. "
                              "Run python3 .harness/scripts/dirty.py for the itemised view.")
    result["options"] = [
        "commit the work on a branch",
        "keep it with git stash push",
        "discard it (irreversible; only if you have looked at the evidence above)",
    ]
    result["never_run_by_this_skill"] = ["git stash", "git checkout", "git clean", "git reset",
                                         "git add", "git commit"]
    return result

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--project", default=".")
    ap.add_argument("--out")
    a = ap.parse_args()
    root = find_project_root(Path(a.project))
    print(dump_json(survey(root), Path(a.out) if a.out else None))

if __name__ == "__main__":
    main()
```

## File: skills/harness-audit/scripts/hlib.py
size: 15718
sha: 88b8c73787b077e968c5dcff091ffaaac4a9224d
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/hlib.py

```text
"""Shared helpers for harness-audit scripts. Python 3.9+, standard library only."""
from __future__ import annotations

import fnmatch
import json
import os
import re
import shutil
import subprocess
import time
from pathlib import Path

HOME = Path.home()
AGENTS = ("claude-code", "codex", "cursor", "antigravity")
ENTRY_FILES = ("CLAUDE.md", "CLAUDE.local.md", "AGENTS.md", "AGENTS.override.md", "GEMINI.md")
GENERATED_MARK = "<!-- harness:generated"

DEFAULT_CONFIG = {
    "version": 1,
    "agents": "auto",
    "docs_dir": "docs",
    "vault": {"enabled": False, "path": None, "project_folder": None, "topology": None},
    "budgets": {
        "always_on_tokens": 5000,
        "entry_file_lines": 120,
        "codex_project_doc_bytes": 32768,
        "rule_tokens": 1500,
        "skill_description_chars": 400,
        "doc_tokens_warn": 8000,
        "stale_days": 120,
        "chars_per_token": None,
        "context_window": None,
    },
    "ratchet": True,
    "lint": {"suppress": {}},
    "benchmark": {"big_reduction_pct": 50, "min_cost_delta_pct": 10},
    "required_frontmatter": ["description", "updated", "status"],
    "allowed_status": ["active", "draft", "superseded", "archived", "completed"],
    "index": {"file": "index.md", "exclude": ["raw/**", "index.md", "log.md", "_templates/**", "_attachments/**"]},
    "log": {"file": "log.md"},
    "placement": {
        "decisions": "Architecture decisions (ADR), NNNN-title.md, never deleted, mark superseded",
        "plans/active": "Work in progress plans",
        "plans/completed": "Finished plans",
        "runbooks": "Operational procedures a human or agent follows",
        "references": "Long reference material, read on demand only",
        "architecture": "System maps and domain boundaries",
        "product": "Product specs and requirements",
        "raw": "Immutable sources (clippings, transcripts). Read-only for agents",
    },
    "rules_source": ".harness/rules",
    "skills_source": ".harness/skills",
}

def docs_root(root: Path, cfg: dict) -> Path:
    """docs_dir may be relative to the repo or an absolute/~ path into an Obsidian vault."""
    d = str(cfg.get("docs_dir", "docs"))
    p = Path(d.replace("~", str(HOME), 1)) if d.startswith("~") else Path(d)
    return (p if p.is_absolute() else root / p).resolve()

def doc_rel(root: Path, cfg: dict, p: Path) -> str:
    """Path relative to the docs root (used for placement, exclude and index grouping)."""
    try:
        return Path(p).resolve().relative_to(docs_root(root, cfg)).as_posix()
    except ValueError:
        return ""

def index_path(root: Path, cfg: dict) -> Path:
    return docs_root(root, cfg) / cfg["index"].get("file", "index.md")

def log_path(root: Path, cfg: dict) -> Path:
    return docs_root(root, cfg) / cfg["log"].get("file", "log.md")

# Chars per token. 4.00 is the figure for running English prose, and it is what this
# estimate used everywhere until the third pilot measured the real ratio on a dense
# technical harness: 2.10, an error of 1.90x, always downwards. The cause is the shape of
# the text, not its language — markdown tables, bold markers, backticked identifiers,
# paths, UUIDs and hashes fragment far more than words do. The same 2.10 later predicted a
# file set 69.7% smaller to within 0.1%, so a ratio measured once on a project holds for
# that project. `measure.py calibrate` derives it from a real /context and writes it to
# budgets.chars_per_token; load_config() picks it up from there.
# ponytail: process-wide, set by load_config; one project per process, which is how every
# script here runs. Pass `ratio` explicitly if that ever stops being true.
DEFAULT_CHARS_PER_TOKEN = 4.0
_chars_per_token = DEFAULT_CHARS_PER_TOKEN

def estimate_tokens(text: str, ratio: float | None = None) -> int:
    """Token estimate from character count. A FLOOR, never a measurement.

    The ratio is configurable because the default is wrong by up to 2x on dense technical
    markdown. Whatever this returns, the authoritative number is /context in a fresh session.
    """
    return max(0, round(len(text) / (ratio or _chars_per_token)))

def chars_per_token(cfg: dict) -> float:
    try:
        return float(cfg.get("budgets", {}).get("chars_per_token") or DEFAULT_CHARS_PER_TOKEN)
    except (TypeError, ValueError):
        return DEFAULT_CHARS_PER_TOKEN

def ratio_note(cfg: dict) -> str:
    """One line for the report: which ratio produced the estimates, and where it came from."""
    r = chars_per_token(cfg)
    if r == DEFAULT_CHARS_PER_TOKEN:
        return (f"{r:.2f} chars/token (default, for running English prose; dense technical markdown "
                "measures closer to 2.10, so these estimates are a floor). "
                "Calibrate with: measure.py calibrate")
    return f"{r:.2f} chars/token (calibrated for this project, budgets.chars_per_token)"

def read_text(path: Path) -> str:
    try:
        return path.read_text(encoding="utf-8", errors="replace")
    except (OSError, UnicodeError):
        return ""

def find_project_root(start: Path) -> Path:
    cur = start.resolve()
    for p in [cur, *cur.parents]:
        if (p / ".git").exists() or (p / ".harness").is_dir():
            return p
    return cur

def load_config(root: Path) -> dict:
    cfg = json.loads(json.dumps(DEFAULT_CONFIG))
    path = root / ".harness" / "config.json"
    if path.exists():
        user = json.loads(read_text(path) or "{}")
        for k, v in user.items():
            if isinstance(v, dict) and isinstance(cfg.get(k), dict):
                cfg[k].update(v)
            else:
                cfg[k] = v
    global _chars_per_token
    _chars_per_token = chars_per_token(cfg)
    return cfg

# ---------------------------------------------------------------- frontmatter
FM_RE = re.compile(r"\A---\s*\n(.*?)\n---\s*(\n|\Z)", re.S)

def _scalar(v: str):
    v = v.strip()
    if len(v) >= 2 and v[0] == v[-1] and v[0] in "\"'":
        return v[1:-1]
    low = v.lower()
    if low in ("true", "yes"):
        return True
    if low in ("false", "no"):
        return False
    if v.startswith("[") and v.endswith("]"):
        inner = v[1:-1].strip()
        return [_scalar(x) for x in inner.split(",") if x.strip()] if inner else []
    return v

def parse_frontmatter(text: str):
    """Minimal YAML subset: key: value, inline lists, block lists. Returns (dict, body)."""
    m = FM_RE.match(text)
    if not m:
        return {}, text
    data, key = {}, None
    for raw in m.group(1).splitlines():
        if not raw.strip() or raw.lstrip().startswith("#"):
            continue
        item = re.match(r"^\s*-\s+(.*)$", raw)
        if item and key is not None:
            if not isinstance(data.get(key), list):
                data[key] = []
            data[key].append(_scalar(item.group(1)))
            continue
        kv = re.match(r"^([A-Za-z0-9_\-]+)\s*:\s*(.*)$", raw)
        if kv:
            key, val = kv.group(1), kv.group(2)
            data[key] = _scalar(val) if val.strip() else []
    return data, text[m.end():]

def as_list(v) -> list:
    if v is None or v == "" or v == []:
        return []
    if isinstance(v, list):
        return [str(x) for x in v]
    return [x.strip() for x in str(v).split(",") if x.strip()]

# ---------------------------------------------------------------- files
def rel(root: Path, p: Path) -> str:
    try:
        return p.resolve().relative_to(root.resolve()).as_posix()
    except ValueError:
        return str(p)

def match_any(path: str, patterns) -> bool:
    return any(fnmatch.fnmatch(path, pat) for pat in patterns)

def iter_md(base: Path, exclude=(), root: Path | None = None):
    """Yield .md/.mdc under base. exclude globs are matched relative to base."""
    if not base.is_dir():
        return
    for dirpath, dirnames, filenames in os.walk(base):
        dirnames[:] = [d for d in dirnames if d not in (".git", "node_modules", ".obsidian", ".trash")]
        for f in filenames:
            if f.endswith((".md", ".mdc")):
                p = Path(dirpath) / f
                if not match_any(p.relative_to(base).as_posix(), exclude):
                    yield p

# ---------------------------------------------------------------- git
# Every read below is parsed (porcelain, --oneline, rev-parse, ls-files, status
# --short), so a shell wrapper that "improves" git output silently breaks the
# parser. In the second pilot an rtk wrapper on PATH turned
# `git worktree list --porcelain` back into the human format and the audit read
# garbage. So: call the real binary, and say so when PATH points elsewhere.
PATH_GIT = shutil.which("git")
GIT_BIN = "/usr/bin/git" if os.access("/usr/bin/git", os.X_OK) else (PATH_GIT or "git")

def git_environment() -> dict:
    """What git we actually run, and whether something on PATH is shadowing it."""
    return {
        "git_bin": GIT_BIN,
        "path_git": PATH_GIT,
        "wrapper_suspected": bool(PATH_GIT and os.path.realpath(PATH_GIT) != os.path.realpath(GIT_BIN)),
        "note": ("A different git is first on PATH; harness scripts call the real binary because "
                 "they parse machine-readable output." if PATH_GIT and
                 os.path.realpath(PATH_GIT) != os.path.realpath(GIT_BIN) else ""),
    }

def claude_code_version():
    """Version string of the claude binary on PATH, or None when it cannot be read.

    Reading AGENTS.md directly needs v2.1.277 or later, so the version is part of
    knowing which instruction file a session actually loads. `--version` is the only
    command this skill runs besides git, and a failure is reported as None, never guessed.
    """
    exe = shutil.which("claude")
    if not exe:
        return None
    try:
        out = subprocess.run([exe, "--version"], capture_output=True, text=True, timeout=10)
    except (OSError, subprocess.SubprocessError):
        return None
    m = re.search(r"\d+\.\d+\.\d+", out.stdout or "")
    return m.group(0) if m else None

def version_tuple(v) -> tuple:
    return tuple(int(x) for x in re.findall(r"\d+", str(v or ""))[:3]) or (0,)

def git(root: Path, *args) -> str:
    try:
        out = subprocess.run([GIT_BIN, "-C", str(root), *args], capture_output=True, text=True, timeout=20)
        return out.stdout if out.returncode == 0 else ""
    except (OSError, subprocess.SubprocessError):
        return ""

def git_ok(root: Path, *args) -> bool:
    """Exit status of a git command, for the ones that answer with it and print nothing.

    `merge-base --is-ancestor` is the case: it says yes or no in the return code, so git()
    returning "" for both a false answer and a failure would read as "no" either way.
    """
    try:
        out = subprocess.run([GIT_BIN, "-C", str(root), *args], capture_output=True, text=True, timeout=20)
        return out.returncode == 0
    except (OSError, subprocess.SubprocessError):
        return False

def upstream_state(root: Path) -> dict:
    """How far the working branch is from the branch it should be measured against.

    A baseline read from a branch 48 commits behind the remote measures a file that
    no longer exists: that is what happened in the second pilot, and it only surfaced
    mid-apply. @{upstream} is the right reference when it is set; a working branch
    without one still has origin/HEAD to compare against.

    Nothing here touches the network: fetching inside someone else's repository, unasked,
    is not ours to do. So the answer carries its own age. reference_age_days says how old
    the local copy of the remote is, and stale_comparison marks the case that gives false
    comfort: behind 0 measured against data nobody refreshed today.
    """
    state = {"upstream": None, "reference": None, "behind": 0, "ahead": 0, "diverged": False,
             "reference_age_days": None, "stale_comparison": False}
    ref = git(root, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}").strip()
    if ref:
        state["upstream"] = ref
    else:
        head = git(root, "symbolic-ref", "--short", "refs/remotes/origin/HEAD").strip()
        ref = head or ""
    if not ref:
        return state
    state["reference"] = ref
    counts = git(root, "rev-list", "--left-right", "--count", f"{ref}...HEAD").split()
    if len(counts) == 2:
        state["behind"], state["ahead"] = int(counts[0]), int(counts[1])
        state["diverged"] = state["behind"] > 0 and state["ahead"] > 0
    state["reference_age_days"] = reference_age_days(root)
    age = state["reference_age_days"]
    state["stale_comparison"] = state["behind"] == 0 and age is not None and age >= 1
    return state

def reference_age_days(root: Path):
    """Days since the local copy of the remote was last refreshed, or None if unknown."""
    gitdir = git(root, "rev-parse", "--git-dir").strip()
    if not gitdir:
        return None
    base = Path(gitdir) if Path(gitdir).is_absolute() else root / gitdir
    for name in ("FETCH_HEAD", "refs/remotes/origin/HEAD"):
        p = base / name
        if p.exists():
            return int((time.time() - p.stat().st_mtime) // 86400)
    return None

def changed_files(root: Path, staged_only=False) -> list:
    if staged_only:
        out = git(root, "diff", "--cached", "--name-only", "--diff-filter=ACMR")
        return [l for l in out.splitlines() if l]
    out = git(root, "status", "--porcelain", "--untracked-files=all")
    files = []
    for line in out.splitlines():
        path = line[3:].split(" -> ")[-1].strip().strip('"')
        if path:
            files.append(path)
    return files

def detect_agents(root: Path) -> list:
    found = []
    if (root / "CLAUDE.md").exists() or (root / ".claude").is_dir():
        found.append("claude-code")
    if (root / "AGENTS.md").exists() or (root / ".codex").is_dir():
        found.append("codex")
    if (root / ".cursor").is_dir() or (root / ".cursorrules").exists():
        found.append("cursor")
    if (root / "GEMINI.md").exists() or (root / ".agents").is_dir() or (root / ".gemini").is_dir():
        found.append("antigravity")
    return found

def enabled_agents(root: Path, cfg: dict) -> list:
    a = cfg.get("agents", "auto")
    if a == "auto" or not a:
        return detect_agents(root) or ["claude-code"]
    return [x for x in a if x in AGENTS]

def dump_json(data, path: Path | None):
    text = json.dumps(data, indent=2, ensure_ascii=False)
    if path:
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(text + "\n", encoding="utf-8")
    return text

# ---------------------------------------------------------------- redaction
SECRET_KV_RE = re.compile(
    r"\b([A-Za-z0-9_\-]*(?:token|key|secret|password|passwd|pwd|apikey|auth)[A-Za-z0-9_\-]*)"
    r"(\s*[=:]\s*)(\"[^\"]*\"|'[^']*'|\S+)", re.I)
SECRET_FLAG_RE = re.compile(
    r"(--?[A-Za-z0-9_\-]*(?:token|key|secret|password|passwd|pwd|apikey|auth)[A-Za-z0-9_\-]*)"
    r"(\s+)(\"[^\"]*\"|'[^']*'|\S+)", re.I)

def mask_secrets(text: str) -> str:
    """Replace the value of any token=/key=/secret=/password= pair with ***.

    The inventory is written into the user's project and may be committed, so no
    credential picked up from a hook command may ever reach the report.
    """
    out = SECRET_KV_RE.sub(lambda m: f"{m.group(1)}{m.group(2)}***", text or "")
    return SECRET_FLAG_RE.sub(lambda m: f"{m.group(1)}{m.group(2)}***", out)

def safe_command(text: str, limit: int = 160) -> str:
    """Masked and clipped form of a hook command. Never executed, only described."""
    out = mask_secrets(" ".join(str(text or "").split()))
    return out if len(out) <= limit else out[:limit] + "…"
```

## File: skills/harness-audit/scripts/hook.py
size: 6931
sha: 0827ea0f5f157b96d5a2f6cadedbfaec095c0a2e
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/hook.py

```text
#!/usr/bin/env python3
"""One hook script for every agent. Installed at .harness/scripts/hook.py.

  python3 .harness/scripts/hook.py --agent claude-code --event post-edit
  python3 .harness/scripts/hook.py --agent cursor      --event stop
Events: post-edit | stop | session-start

Protocols (checked Sept 2026, see references/agents/*):
  claude-code  exit 2 + stderr is fed back to Claude; Stop honors stop_hook_active.
  codex        Claude-style hooks: exit 2 + stderr (verify against your Codex version).
  cursor       afterFileEdit cannot talk to the agent: we record the edit and report on stop
               via {"followup_message": ...}; sessionStart returns {"additional_context": ...}.
  antigravity  best effort: stderr + exit 2. Pre-commit and CI remain the guaranteed gate.
Hooks never crash the agent session: any internal error exits 0.
"""
from __future__ import annotations

import argparse
import json
import re
import sys
import time
from pathlib import Path

PATCH_RE = re.compile(r"^\*\*\* (?:Add|Update|Delete) File: (.+)$", re.M)
PATH_KEYS = {"file_path", "filePath", "path", "notebook_path", "target_file", "TargetFile", "AbsolutePath"}
MAX_BLOCKS = 2

def collect_paths(obj, out):
    if isinstance(obj, dict):
        for k, v in obj.items():
            if k in PATH_KEYS and isinstance(v, str):
                out.add(v)
            else:
                collect_paths(v, out)
    elif isinstance(obj, list):
        for v in obj:
            collect_paths(v, out)
    elif isinstance(obj, str) and "*** " in obj:
        out.update(m.strip() for m in PATCH_RE.findall(obj))

def state_file(root: Path) -> Path:
    return root / ".harness/state/session.json"

def load_state(root: Path) -> dict:
    try:
        return json.loads(state_file(root).read_text())
    except (OSError, ValueError):
        return {"edits": [], "blocks": {}}

def save_state(root: Path, st: dict):
    p = state_file(root)
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_text(json.dumps(st))

def session_id(payload: dict) -> str:
    return str(payload.get("session_id") or payload.get("conversation_id") or payload.get("sessionId") or "default")

def feedback(agent: str, event: str, msg: str, payload: dict, root: Path):
    """Emit a message the agent will act on, respecting loop guards."""
    st = load_state(root)
    sid = session_id(payload)
    if event == "stop":
        if payload.get("stop_hook_active") or int(payload.get("loop_count") or 0) >= MAX_BLOCKS:
            return 0
        blocks = st["blocks"].get(sid, 0)
        if blocks >= MAX_BLOCKS:
            return 0
        st["blocks"][sid] = blocks + 1
        save_state(root, st)
    if agent == "cursor":
        if event == "stop":
            print(json.dumps({"followup_message": msg}))
        return 0
    print(msg, file=sys.stderr)
    return 2

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--agent", required=True, choices=["claude-code", "codex", "cursor", "antigravity"])
    ap.add_argument("--event", required=True, choices=["post-edit", "stop", "session-start"])
    ap.add_argument("--project", default=None)
    a = ap.parse_args()
    raw = sys.stdin.read() if not sys.stdin.isatty() else ""
    try:
        payload = json.loads(raw) if raw.strip() else {}
    except ValueError:
        payload = {}

    sys.path.insert(0, str(Path(__file__).resolve().parent))
    import lint  # noqa: E402
    from hlib import changed_files, doc_rel, find_project_root, load_config, log_path, rel  # noqa: E402

    start = a.project or payload.get("cwd") or (payload.get("workspace_roots") or [None])[0] or "."
    root = find_project_root(Path(start))
    cfg = load_config(root)

    if a.event == "post-edit":
        paths = set()
        collect_paths(payload, paths)
        rels = [rel(root, Path(p) if Path(p).is_absolute() else root / p) for p in paths]
        relevant = [r for r in rels if lint.is_harness_file(root, cfg, r)]
        if not relevant:
            return 0
        st = load_state(root)
        st["edits"] = sorted(set(st["edits"]) | set(relevant))
        st.setdefault("first_edit", time.time())
        st["updated"] = time.time()
        save_state(root, st)
        if a.agent == "cursor":
            return 0
        findings, _ = lint.run(root, relevant)
        errors = [x for x in findings if x["severity"] == "error" and x["code"] != "H008"]
        if errors:
            return feedback(a.agent, a.event, "Harness check failed for the file you just edited. Fix before continuing:\n"
                            + lint.format_text(errors), payload, root)
        return 0

    if a.event == "stop":
        st = load_state(root)
        touched = set(st.get("edits", []))
        touched |= {f for f in changed_files(root) if lint.is_harness_file(root, cfg, f)}
        if not touched:
            return 0
        findings, _ = lint.run(root, sorted(touched))
        problems = [x for x in findings if x["severity"] == "error"]
        docs_touched = [t for t in touched if lint.is_doc(root, cfg, t)]
        lp = rel(root, log_path(root, cfg))
        log_file = log_path(root, cfg)
        since = st.get("first_edit") or st.get("updated")
        log_fresh = lp in touched or bool(log_file.exists() and since and log_file.stat().st_mtime >= since)
        if docs_touched and not log_fresh and log_file.exists():
            problems.append({"code": "H018", "severity": "error", "path": lp,
                             "message": f"{len(docs_touched)} doc(s) changed but the log was not updated",
                             "fix": f"Append one line to {lp}: ## [YYYY-MM-DD] <kind> | <what changed>"})
        if problems:
            return feedback(a.agent, a.event, "Before finishing, put the harness back in order:\n"
                            + lint.format_text(problems)
                            + "\nThen run: python3 .harness/scripts/build_index.py && python3 .harness/scripts/lint.py",
                            payload, root)
        st["edits"], st["blocks"] = [], {}
        st.pop("first_edit", None)
        save_state(root, st)
        return 0

    if a.event == "session-start":
        f = lint.Findings()
        lint.check_budgets(root, cfg, f)
        over = [x for x in f if x["code"] in ("H002", "H006", "H015")]
        if not over:
            return 0
        msg = ("Harness alert: " + "; ".join(f"{x['path']}: {x['message']}" for x in over)
               + ". Follow .harness/PLACEMENT.md and do not add to always-on files.")
        if a.agent == "cursor":
            print(json.dumps({"additional_context": msg}))
        else:
            print(msg)
        return 0
    return 0

if __name__ == "__main__":
    try:
        sys.exit(main())
    except Exception as exc:  # never break the agent session
        print(f"harness hook internal error (ignored): {exc}", file=sys.stderr)
        sys.exit(0)
```

## File: skills/harness-audit/scripts/install.py
size: 19296
sha: 37184616982e3bc3dc19db05db06c2039a373fc9
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/install.py

```text
#!/usr/bin/env python3
"""Install the maintenance layer into a project. Dry-run by default; --apply writes.

  python3 install.py --project . --agents claude-code,codex,cursor,antigravity \
      [--docs-dir docs | --docs-dir ~/Vault/Projects/X] [--vault-path ~/Vault] [--vault-topology external] \
      [--entry-blocks] [--with-precommit] [--with-ci] --apply

Writes:
  .harness/config.json, PLACEMENT.md, scripts/, skills/harness-keeper/, rules/, reports/
  docs index + log (in docs dir or vault folder)
  hooks: .claude/settings.json | .cursor/hooks.json | .codex/hooks.json | .agents/hooks.harness.json (experimental)
  optional: git pre-commit, GitHub Actions workflow, routing block in AGENTS.md/CLAUDE.md/GEMINI.md
Never deletes. Existing hook entries are preserved; ours are added once (idempotent).
"""
from __future__ import annotations

import argparse
import json
import re
import shutil
import stat
import sys
from datetime import date
from pathlib import Path

HERE = Path(__file__).resolve().parent
SKILL = HERE.parent
TPL = SKILL / "assets/templates"
sys.path.insert(0, str(HERE))
from hlib import (AGENTS, DEFAULT_CONFIG, detect_agents, docs_root, find_project_root, git, read_text,  # noqa: E402
                  rel)

SCRIPTS = ["hlib.py", "lint.py", "build_index.py", "sync.py", "hook.py", "inventory.py", "measure.py",
           "transcripts.py", "detect.py", "code_sensor.py", "dirty.py", "benchenv.py"]
MARK = "harness/scripts/hook.py"

class Plan:
    def __init__(self, root: Path, apply: bool):
        self.root, self.apply, self.actions = root, apply, []

    def write(self, path: Path, content: str, overwrite=True):
        exists = path.exists()
        if exists and not overwrite:
            self.actions.append(f"keep   {rel(self.root, path)} (exists)")
            return
        if exists and read_text(path) == content:
            self.actions.append(f"same   {rel(self.root, path)}")
            return
        self.actions.append(f"{'update' if exists else 'create'} {rel(self.root, path)}")
        if self.apply:
            path.parent.mkdir(parents=True, exist_ok=True)
            path.write_text(content, encoding="utf-8")

    def copy(self, src: Path, dest: Path):
        self.write(dest, read_text(src))

def cmd(agent, event):
    return f"python3 .harness/scripts/hook.py --agent {agent} --event {event}"

def merge_claude(root: Path, plan: Plan, vault: str | None):
    p = root / ".claude/settings.json"
    data = json.loads(read_text(p) or "{}") if p.exists() else {}
    hooks = data.setdefault("hooks", {})
    base = 'python3 "$CLAUDE_PROJECT_DIR"/.harness/scripts/hook.py --agent claude-code --event '
    wanted = {"PostToolUse": ("Write|Edit|MultiEdit|NotebookEdit", "post-edit"), "Stop": (None, "stop"),
              "SessionStart": ("startup|resume|clear|compact", "session-start")}
    for ev, (matcher, name) in wanted.items():
        groups = hooks.setdefault(ev, [])
        if any(MARK in h.get("command", "") for g in groups for h in g.get("hooks", [])):
            continue
        g = {"hooks": [{"type": "command", "command": base + name, "timeout": 60}]}
        if matcher:
            g = {"matcher": matcher, **g}
        groups.append(g)
    if vault:
        dirs = data.setdefault("permissions", {}).setdefault("additionalDirectories", [])
        if vault not in dirs:
            dirs.append(vault)
    plan.write(p, json.dumps(data, indent=2) + "\n")

def merge_cursor(root: Path, plan: Plan):
    p = root / ".cursor/hooks.json"
    data = json.loads(read_text(p) or "{}") if p.exists() else {}
    data.setdefault("version", 1)
    hooks = data.setdefault("hooks", {})
    for ev, name in (("afterFileEdit", "post-edit"), ("stop", "stop"), ("sessionStart", "session-start")):
        lst = hooks.setdefault(ev, [])
        if not any(MARK in h.get("command", "") for h in lst):
            lst.append({"command": cmd("cursor", name)})
    plan.write(p, json.dumps(data, indent=2) + "\n")

def merge_codex(root: Path, plan: Plan):
    p = root / ".codex/hooks.json"
    data = json.loads(read_text(p) or "{}") if p.exists() else {}
    hooks = data.setdefault("hooks", {})
    wanted = {"PostToolUse": ("apply_patch|Edit|Write", "post-edit"), "Stop": (None, "stop"),
              "SessionStart": ("startup|resume|clear", "session-start")}
    for ev, (matcher, name) in wanted.items():
        groups = hooks.setdefault(ev, [])
        if any(MARK in h.get("command", "") for g in groups for h in g.get("hooks", [])):
            continue
        g = {"hooks": [{"type": "command", "command": cmd("codex", name), "timeout": 60}]}
        if matcher:
            g = {"matcher": matcher, **g}
        groups.append(g)
    plan.write(p, json.dumps(data, indent=2) + "\n")

def antigravity_example(root: Path, plan: Plan):
    plan.copy(TPL / "hooks/antigravity.hooks.example.json", root / ".agents/hooks.harness.example.json")

def active_git_hooks(root: Path) -> list:
    """Executable hooks the user already has in .git/hooks (samples do not count)."""
    d = root / ".git/hooks"
    if not d.is_dir():
        return []
    return sorted(h.name for h in d.iterdir()
                  if h.is_file() and not h.name.endswith(".sample") and h.stat().st_mode & stat.S_IXUSR)

def hooks_dir(root: Path, plan: Plan) -> Path | None:
    """Where the pre-commit belongs, without breaking a setup that already exists.

    A tracked hooks folder is the point: a hook in .git/hooks lives on one machine
    only, so a clone gets nothing. But core.hooksPath is local git config, and
    setting it silently disables whatever the user already had. So: honour an
    existing core.hooksPath (husky and friends), refuse to touch untracked hooks
    that are already active, and only then default to .githooks.
    """
    configured = git(root, "config", "--local", "--get", "core.hooksPath").strip()
    if configured:
        plan.actions.append(f"note   core.hooksPath is already {configured}: installing there, not changing it")
        return (root / configured) if not Path(configured).is_absolute() else Path(configured)
    existing = active_git_hooks(root)
    if existing:
        plan.actions.append(
            "SKIP   pre-commit: .git/hooks already has active hook(s) (" + ", ".join(existing) + "). "
            "Setting core.hooksPath would disable them. Move them to .githooks yourself, then rerun with "
            "--hooks-path .githooks, or install the hook manually.")
        return None
    return root / ".githooks"

def precommit(root: Path, plan: Plan, forced: str | None, sensor: bool):
    if not (root / ".git").is_dir():
        plan.actions.append("skip   pre-commit (not a git repo)")
        return None
    target = (root / forced) if forced else hooks_dir(root, plan)
    if target is None:
        return None
    p = target / "pre-commit"
    lines = ["python3 .harness/scripts/sync.py --check && python3 .harness/scripts/lint.py --staged || "
             "{ echo 'harness lint failed'; exit 1; }"]
    if sensor:
        # Only exit 1 means a file got worse. Exit 2 means the sensor is not configured
        # any more, which is a reason to say nothing, not a reason to block the commit.
        lines.append("python3 .harness/scripts/code_sensor.py --staged; "
                     "if [ $? -eq 1 ]; then echo 'code sensor: a file got worse'; exit 1; fi")
    block = "\n# >>> harness-audit\n" + "\n".join(lines) + "\n# <<< harness-audit\n"
    current = read_text(p) if p.exists() else "#!/bin/sh\n"
    if "harness-audit" in current:
        plan.actions.append(f"same   {rel(root, p)}")
    else:
        plan.write(p, current.rstrip("\n") + "\n" + block)
        if plan.apply:
            p.chmod(p.stat().st_mode | stat.S_IEXEC)
    return target

def activate_hooks_path(root: Path, plan: Plan, target: Path):
    """Point git at the tracked folder. Only reached when nothing was there before."""
    value = rel(root, target)
    if git(root, "config", "--local", "--get", "core.hooksPath").strip() == value:
        plan.actions.append(f"same   core.hooksPath={value}")
        return
    plan.actions.append(f"config core.hooksPath={value}")
    if plan.apply:
        git(root, "config", "core.hooksPath", value)

def npm_prepare(root: Path, plan: Plan, target: Path):
    """A clone runs `npm install`, which runs `prepare`, which arms the hooks."""
    p = root / "package.json"
    if not p.is_file():
        return
    try:
        data = json.loads(read_text(p))
    except ValueError:
        plan.actions.append("skip   package.json (not valid JSON)")
        return
    wanted = f"git config core.hooksPath {rel(root, target)} || true"
    scripts = data.setdefault("scripts", {})
    cur = scripts.get("prepare", "")
    if wanted in cur:
        plan.actions.append("same   package.json prepare")
        return
    scripts["prepare"] = f"{cur} && {wanted}" if cur.strip() else wanted
    plan.write(p, json.dumps(data, indent=2, ensure_ascii=False) + "\n")

def measured_budgets(root: Path, cfg: dict) -> dict:
    """Set the initial budgets from what the project is today, not from a target.

    A gate installed with the default budget over a legacy harness is red on its first
    run: in the second pilot it blocked the very commits that were shrinking a 13k-line
    CLAUDE.md. So the opening budget is a photograph of the current state (never looser
    than the target), it is marked transitional, and the ratchet is what brings it down
    — the same rule the code sensor follows.
    """
    import inventory
    inv = inventory.build(root, include_user=False)
    measured_tokens = max([d["always_on_est_tokens"] for d in inv["agents"].values()] or [0])
    measured_lines = 0
    for name in ("CLAUDE.md", "AGENTS.md", "GEMINI.md", "AGENTS.override.md"):
        text = read_text(root / name) if (root / name).is_file() else ""
        if text:
            measured_lines = max(measured_lines, text.count("\n") + 1)
    targets = {"always_on_tokens": int(DEFAULT_CONFIG["budgets"]["always_on_tokens"]),
               "entry_file_lines": int(DEFAULT_CONFIG["budgets"]["entry_file_lines"])}
    opening = {"always_on_tokens": max(measured_tokens, targets["always_on_tokens"]),
               "entry_file_lines": max(measured_lines, targets["entry_file_lines"])}
    cfg["budgets"].update(opening)
    if opening != targets:
        cfg["budgets_transitional"] = {"measured_on": date.today().isoformat(), "opening": opening,
                                       "targets": targets}
    else:
        cfg.pop("budgets_transitional", None)
    return opening

def budget_note(opening: dict) -> str:
    return (f"Opening budgets measured from this project: {opening['always_on_tokens']} always-on tokens, "
            f"{opening['entry_file_lines']} entry-file lines. Marked transitional; lint warns (H019) until "
            f"'lint.py --update-lock' tightens them to the real values.")

def detect_lint_command(root: Path) -> dict | None:
    """The sensor runs the project's own linter. No linter, no sensor."""
    p = root / "package.json"
    if not p.is_file():
        return None
    try:
        data = json.loads(read_text(p))
    except ValueError:
        return None
    deps = {**(data.get("dependencies") or {}), **(data.get("devDependencies") or {})}
    if not any(k == "eslint" or k.startswith("eslint") for k in deps) and "lint" not in (data.get("scripts") or {}):
        return None
    return {"command": "npx eslint . --format json", "format": "eslint-json",
            "baseline": ".harness/eslint-baseline.json"}

def entry_blocks(root: Path, plan: Plan, agents: list, idx: str, hooks: Path | None):
    """AGENTS.md is canonical. CLAUDE.md imports it. GEMINI.md never repeats it."""
    block = read_text(TPL / "entry-block.md").replace("{{INDEX}}", idx)
    if hooks is None:
        block = "\n".join(l for l in block.splitlines() if "{{HOOKS}}" not in l)
    else:
        block = block.replace("{{HOOKS}}", rel(root, hooks))
    use_agents_md = bool({"codex", "cursor", "antigravity"} & set(agents)) or (root / "AGENTS.md").exists()
    canonical = root / ("AGENTS.md" if use_agents_md else "CLAUDE.md")
    text = read_text(canonical) if canonical.exists() else ""
    if "harness:routes:start" in text:
        plan.actions.append(f"same   {canonical.name} (routing block present)")
    else:
        plan.write(canonical, (text.rstrip("\n") + "\n\n" if text else "") + block)
    if use_agents_md and "claude-code" in agents:
        cp = root / "CLAUDE.md"
        ctext = read_text(cp) if cp.exists() else ""
        if not re.search(r"^@AGENTS\.md\s*$", ctext, re.M):
            plan.write(cp, "@AGENTS.md\n\n" + ctext)
        if "harness:routes:start" in ctext:
            plan.actions.append("note   CLAUDE.md also has a routing block: remove it, AGENTS.md is canonical")
    if use_agents_md and (root / "GEMINI.md").exists():
        plan.actions.append("note   GEMINI.md: Antigravity also reads AGENTS.md; keep only Antigravity-specific lines in GEMINI.md")

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--project", default=".")
    ap.add_argument("--agents", default="auto")
    ap.add_argument("--docs-dir", default="docs")
    ap.add_argument("--vault-path")
    ap.add_argument("--vault-topology", choices=["inside-repo", "repo-inside-vault", "external"])
    ap.add_argument("--language", default="auto")
    ap.add_argument("--entry-blocks", action="store_true")
    ap.add_argument("--with-precommit", action="store_true")
    ap.add_argument("--with-ci", action="store_true")
    ap.add_argument("--hooks-path", help="install the pre-commit here instead of the detected folder "
                                         "(default: .githooks, tracked by git)")
    ap.add_argument("--lint-command", help="command the code sensor runs (default: detected from package.json)")
    ap.add_argument("--lint-format", choices=["eslint-json", "text"], default=None)
    ap.add_argument("--apply", action="store_true")
    a = ap.parse_args()
    root = find_project_root(Path(a.project))
    plan = Plan(root, a.apply)
    agents = "auto" if a.agents == "auto" else [x.strip() for x in a.agents.split(",") if x.strip() in AGENTS]

    cfg_path = root / ".harness/config.json"
    cfg = json.loads(read_text(cfg_path)) if cfg_path.exists() else json.loads(json.dumps(DEFAULT_CONFIG))
    cfg["agents"], cfg["docs_dir"], cfg["language"] = agents, a.docs_dir, a.language
    sensor = ({"command": a.lint_command, "format": a.lint_format or "text",
               "baseline": ".harness/code-baseline.json"} if a.lint_command
              else cfg.get("code_sensor") or detect_lint_command(root))
    if sensor:
        cfg["code_sensor"] = sensor
    else:
        cfg.pop("code_sensor", None)
    if a.vault_path:
        cfg["vault"] = {"enabled": True, "path": a.vault_path, "topology": a.vault_topology}
    plan.write(cfg_path, json.dumps(cfg, indent=2, ensure_ascii=False) + "\n")

    for s in SCRIPTS:
        plan.copy(HERE / s, root / ".harness/scripts" / s)
    plan.copy(TPL / "PLACEMENT.md", root / ".harness/PLACEMENT.md")
    plan.copy(TPL / "harness-keeper-skill.tmpl", root / ".harness/skills/harness-keeper/SKILL.md")
    plan.write(root / ".harness/rules/README.md", read_text(TPL / "rules-README.md"), overwrite=False)
    plan.write(root / ".harness/.gitignore", "state/\n", overwrite=False)

    droot = docs_root(root, cfg)
    plan.write(droot / cfg["log"].get("file", "log.md"), read_text(TPL / "log.md"), overwrite=False)
    enabled = agents if agents != "auto" else detect_agents(root)
    external_vault = a.vault_path if a.vault_topology == "external" else None
    if "claude-code" in enabled:
        merge_claude(root, plan, str(Path(a.docs_dir).expanduser()) if external_vault else None)
    if "cursor" in enabled:
        merge_cursor(root, plan)
    if "codex" in enabled:
        merge_codex(root, plan)
    if "antigravity" in enabled:
        antigravity_example(root, plan)
    hooks_target = None
    if a.with_precommit:
        hooks_target = precommit(root, plan, a.hooks_path, bool(sensor))
        if hooks_target is not None and hooks_target != root / ".git/hooks":
            activate_hooks_path(root, plan, hooks_target)
            npm_prepare(root, plan, hooks_target)
    if a.with_ci:
        plan.copy(TPL / "ci/harness.yml", root / ".github/workflows/harness.yml")
    if a.entry_blocks:
        idx = rel(root, droot / cfg["index"].get("file", "index.md"))
        entry_blocks(root, plan, enabled, idx, hooks_target)

    if not a.apply:  # dry run: nothing was written, so this is the best estimate available
        opening = measured_budgets(root, cfg)
        plan.actions.append(budget_note(opening))
    if not sensor:
        plan.actions.append("note   no lint command found: code sensor not installed. "
                            "Record it as a gap in the report (a project with no code sensor has no ratchet).")

    print(("APPLIED" if a.apply else "DRY RUN (use --apply to write)") + f" in {root}")
    print("\n".join("  " + x for x in plan.actions))
    if a.apply:
        import build_index
        import sync
        sync.run(root, check=False)
        ipath = docs_root(root, cfg) / cfg["index"].get("file", "index.md")
        current = read_text(ipath) if ipath.exists() else ""
        ipath.parent.mkdir(parents=True, exist_ok=True)
        ipath.write_text(build_index.merged(current, build_index.render(root, cfg)) + "\n", encoding="utf-8")
        # Measured last, on purpose: install writes the routing block into the entry files
        # and sync projects rules into them, so a budget read any earlier gates a smaller
        # project than the one that now exists.
        opening = measured_budgets(root, cfg)
        cfg_path.write_text(json.dumps(cfg, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
        print("\nSynced projections and generated the index.")
        if cfg.get("budgets_transitional"):
            print(budget_note(opening))
        print("Next: move content per the approved plan, then python3 .harness/scripts/lint.py")
        if hooks_target is not None and hooks_target != root / ".git/hooks":
            print(f"Hooks are tracked in {rel(root, hooks_target)}. A collaborator arms them with "
                  f"'git config core.hooksPath {rel(root, hooks_target)}' (npm projects get it from 'npm install').")
        if sensor:
            print(f"Code sensor: {sensor['command']} -> {sensor['baseline']}. "
                  "Run python3 .harness/scripts/code_sensor.py once and commit the baseline.")
        if "codex" in enabled:
            print("Codex: run /hooks inside Codex to trust the project hooks (or copy them to ~/.codex/hooks.json).")
        if "antigravity" in enabled:
            print("Antigravity: hook schema varies by agy version. Review .agents/hooks.harness.example.json, "
                  "adapt, rename to .agents/hooks.json, verify with 'agy inspect'. Pre-commit remains the guaranteed gate.")
        if external_vault:
            print("Vault outside the repo: Codex needs --add-dir <vault>, Cursor needs the vault in a multi-root workspace.")

if __name__ == "__main__":
    main()
```

## File: skills/harness-audit/scripts/inventory.py
size: 30100
sha: 85ccefac8d19026d41ce6f1263d43515b9166539
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/inventory.py

````text
#!/usr/bin/env python3
"""Map every harness layer per agent: always-on, conditional, on-demand.

Usage: python3 inventory.py [--project PATH] [--include-user] [--out FILE]
Loading rules reflect vendor docs as checked in Sept 2026 (see references/agents/*).
Token numbers are estimates; runtime truth comes from transcripts.py and /context.
"""
from __future__ import annotations

import argparse
import json
import os
import re
import sys
from pathlib import Path

from hlib import (HOME, as_list, claude_code_version, docs_root, dump_json, enabled_agents, estimate_tokens,
                  find_project_root, git_environment, iter_md, load_config, parse_frontmatter, read_text, rel,
                  safe_command, version_tuple)

IMPORT_RE = re.compile(r"(?<![\w`])@((?:~|\.{1,2})?/?[\w.\-/~]+)")

def strip_code(text: str) -> str:
    text = re.sub(r"```.*?```", "", text, flags=re.S)
    return re.sub(r"`[^`\n]*`", "", text)

def item(root, path: Path, kind: str, text: str | None = None, note: str = "", **extra):
    text = read_text(path) if text is None else text
    d = {"path": rel(root, path), "kind": kind, "lines": text.count("\n") + (1 if text else 0),
         "bytes": len(text.encode("utf-8")), "est_tokens": estimate_tokens(text)}
    if note:
        d["note"] = note
    d.update(extra)
    return d

# ------------------------------------------------- instruction-file resolution
# Which instruction file each agent reads here is not readable from the repository
# alone. Claude Code reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md or
# CLAUDE.local.md sits in the working directory or above it, and the switch that
# changes that (instructionFiles) is honored only in user, managed and --settings
# files: Claude Code ignores it in project and local settings. A CLAUDE.local.md is
# personal and gitignored, so it turns the team's AGENTS.md off for one person while
# the repository still looks right. So the inventory states the outcome, not just the
# files: one line per agent saying what it actually loads in this project.
MANAGED_SETTINGS = tuple(Path(p) for p in os.environ.get("HARNESS_MANAGED_SETTINGS", "").split(os.pathsep) if p) or (
    Path("/Library/Application Support/ClaudeCode/managed-settings.json"),
    Path("/etc/claude-code/managed-settings.json"),
    Path(r"C:\Program Files\ClaudeCode\managed-settings.json"),
)
DEFAULT_MODE = "claude-md-or-agents-md"
CLAUDE_MD_NAMES = ("CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md")
AGENTS_MD_NAMES = ("AGENTS.md", ".claude/AGENTS.md")
AGENTS_MD_MIN_VERSION = "2.1.277"
USER_MEMORY = HOME / ".claude/CLAUDE.md"
NOT_READ = "not read (rerun with --include-user)"

def ancestors(root: Path):
    """The project root and every directory above it, stopping at HOME."""
    for p in [root, *root.parents]:
        yield p
        if p == HOME or p == p.parent:
            return

def instruction_files_setting(read_user: bool):
    """(value, source) for pluginConfigs['agents-md@builtin'].options.instructionFiles.

    Managed first, then user. Project and local settings are not consulted because
    Claude Code ignores the key there: reading them would report a value that has
    no effect.
    """
    if not read_user:
        return DEFAULT_MODE, NOT_READ
    for path in (*MANAGED_SETTINGS, HOME / ".claude/settings.json"):
        if not path.is_file():
            continue
        opts = ((_json(path).get("pluginConfigs") or {}).get("agents-md@builtin") or {}).get("options") or {}
        if opts.get("instructionFiles"):
            return str(opts["instructionFiles"]), str(path)
    return DEFAULT_MODE, "default"

def claude_md_excludes(root: Path, read_user: bool):
    """claudeMdExcludes from every layer that honors it. Arrays merge across layers."""
    out = []
    layers = [(root / ".claude/settings.json", "project"), (root / ".claude/settings.local.json", "local")]
    if read_user:
        layers = [(p, "managed") for p in MANAGED_SETTINGS] + [(HOME / ".claude/settings.json", "user")] + layers
    for path, scope in layers:
        if path.is_file():
            for pattern in _json(path).get("claudeMdExcludes") or []:
                out.append({"pattern": str(pattern), "scope": scope, "source": str(path)})
    return out

def imports_agents_md(path: Path) -> bool:
    return any(ref.rstrip("/").split("/")[-1] == "AGENTS.md"
               for ref in IMPORT_RE.findall(strip_code(read_text(path))))

# Direct reading of AGENTS.md also depends on things no file on disk records: which
# provider the session runs on and whether it fetched feature flags, whether it is the
# first session after an install or an upgrade, and whether the built-in agents-md
# plugin is enabled there. None of those can be read here, so a positive answer is
# never asserted: it is reported as undetermined with the two ways to settle it. A
# negative answer survives all of them, because nothing in that list ever makes Claude
# read a file it would otherwise skip.
UNKNOWABLE = (
    "the provider and whether the session fetches feature flags (Amazon Bedrock, another third-party "
    "provider or telemetry disabled never read AGENTS.md directly)",
    "whether this is the first session after installing or upgrading Claude Code",
    "whether the built-in agents-md plugin is enabled, and whether disableAllHooks or "
    "allowManagedHooksOnly is set for the session",
)
CONFIRM = (
    "/config in the session: the Project instructions value, and its absence means this session cannot "
    "read AGENTS.md at all",
    "the session line: no CLAUDE.md found; AGENTS.md loaded: <path>",
)

def instruction_resolution(root: Path, read_user: bool, agents=()) -> dict:
    mode, mode_source = instruction_files_setting(read_user)
    settings_read = read_user and mode_source != NOT_READ
    version = claude_code_version() if read_user else None
    blocking, local_only, agents_files, imported = [], [], [], []
    for p in ancestors(root):
        for name in CLAUDE_MD_NAMES:
            f = p / name
            if not f.is_file() or f.resolve() == USER_MEMORY.resolve():
                continue
            blocking.append(rel(root, f))
            if name == "CLAUDE.local.md":
                local_only.append(rel(root, f))
            if imports_agents_md(f):
                imported.append(rel(root, f))
        for name in AGENTS_MD_NAMES:
            if (p / name).is_file():
                agents_files.append(rel(root, p / name))
    override = rel(root, root / "AGENTS.override.md") if (root / "AGENTS.override.md").is_file() else None

    # Reasons direct reading is off that ARE visible from disk. Any one of them settles it.
    ruled_out = []
    if not agents_files:
        ruled_out.append("there is no AGENTS.md in the working directory or above it")
    if settings_read and mode in ("claude-md", "managed-only"):
        ruled_out.append(f"Project instructions is {mode}")
    if settings_read and mode == DEFAULT_MODE and blocking:
        ruled_out.append("the CLAUDE.md family is present: " + ", ".join(blocking))
    if version and version_tuple(version) < version_tuple(AGENTS_MD_MIN_VERSION):
        ruled_out.append(f"Claude Code {version} is older than v{AGENTS_MD_MIN_VERSION}")

    unknowns = []
    if not ruled_out:
        if not settings_read:
            unknowns.append("the Project instructions value (user and managed settings not read: rerun with "
                            "--include-user)")
        if not version:
            unknowns.append(f"the Claude Code version, which must be v{AGENTS_MD_MIN_VERSION} or later (no "
                            "readable claude binary on PATH)")
        unknowns.extend(UNKNOWABLE)
    agents_md_read = "no" if ruled_out else "undetermined"

    effective = {}
    for a in agents or ("claude-code",):
        if a == "claude-code":
            if agents_md_read == "undetermined":
                if blocking and not settings_read:
                    would = (f"{', '.join(blocking)} loads either way; {', '.join(agents_files)} is skipped under "
                             f"the default value and loaded after it under claude-md-and-agents-md")
                elif blocking:
                    would = (f"{', '.join(blocking)} loads, and {', '.join(agents_files)} after it "
                             f"(Project instructions {mode})")
                else:
                    would = (f"{', '.join(agents_files)} would be read directly: no CLAUDE.md, .claude/CLAUDE.md "
                             f"or CLAUDE.local.md in this tree switches it off")
                text = (f"undetermined for AGENTS.md. {would}. What is undetermined cannot be read from disk: " +
                        "; ".join(unknowns) + ". Confirm with " + " and ".join(CONFIRM))
            elif blocking and imported:
                text = f"{', '.join(blocking)}, with AGENTS.md through the @import in {', '.join(imported)}"
            elif blocking:
                text = f"{', '.join(blocking)} only" + (
                    "; AGENTS.md is not read directly because " + " and ".join(ruled_out) if agents_files else "")
            else:
                text = ("no project instruction file" if not agents_files else
                        "no project instruction file at launch: " + " and ".join(ruled_out))
            if settings_read and mode == "managed-only":
                text = "only the managed CLAUDE.md and auto memory (project, local, user and every AGENTS.md left out)"
        elif a == "codex":
            chain = override or (rel(root, root / "AGENTS.md") if (root / "AGENTS.md").is_file() else None)
            text = f"{chain} (AGENTS.override.md wins over AGENTS.md)" if override else (chain or "no project doc")
        elif a == "cursor":
            text = rel(root, root / "AGENTS.md") if (root / "AGENTS.md").is_file() else "no AGENTS.md; .cursor/rules only"
        else:
            names = [n for n in ("GEMINI.md", "AGENTS.md") if (root / n).is_file()]
            text = ", ".join(names) if names else "no context file"
        effective[a] = text

    notes = [
        "instructionFiles is honored in user, managed and --settings files only: a value in project or "
        "local settings has no effect and is not read here.",
        "Server-managed settings come from the claude.ai console and cannot be read from disk: a value "
        "deployed that way is not visible in this report, so a 'no' that rests on the setting can still be wrong.",
        "claudeMdExcludes is recorded, not applied to the estimates below; it also applies inside an "
        "AGENTS.md that Claude reads directly.",
    ]
    if agents_md_read == "undetermined":
        notes.append("An AGENTS.md read directly is NOT listed in /memory or under Memory files in /context, so "
                     "/context understates the always-on total by its size. InstructionsLoaded hooks do not fire "
                     "for it either. It is reported as conditional here and left out of always_on_est_tokens: a "
                     "total that moves with an assumption is worse than two numbers with their reason.")
    if agents_files and agents_md_read == "no":
        notes.append("AGENTS.md exists and is not read directly: " + " and ".join(ruled_out) + ".")
    return {
        "instruction_files": mode,
        "instruction_files_source": mode_source,
        "claude_code_version": version,
        "claude_md_files": blocking,
        "claude_local_md": local_only,
        "agents_md_files": agents_files,
        "agents_md_imported_by": imported,
        "agents_override_md": override,
        "claude_md_excludes": claude_md_excludes(root, read_user),
        "agents_md_read": agents_md_read,
        "ruled_out_because": ruled_out,
        "undetermined_because": unknowns,
        "confirm_with": list(CONFIRM),
        "effective": effective,
        "notes": notes,
    }

# ---------------------------------------------------------------- claude code
def claude_imports(root, path: Path, depth=0, seen=None):
    seen = seen if seen is not None else set()
    out = []
    if depth >= 4:
        return out
    for ref in IMPORT_RE.findall(strip_code(read_text(path))):
        if "/" not in ref and "." not in ref:
            continue
        target = Path(ref.replace("~", str(HOME), 1)) if ref.startswith("~") else (path.parent / ref)
        target = target.resolve()
        if target in seen or not target.is_file():
            continue
        seen.add(target)
        external = not str(target).startswith(str(root.resolve()))
        out.append(item(root, target, "import", note=f"imported by {rel(root, path)} (loads at launch)",
                        external=external))
        out.extend(claude_imports(root, target, depth + 1, seen))
    return out

def skill_listing(root, dirs, agent):
    always, hidden = [], []
    for d in dirs:
        if not d.is_dir():
            continue
        for sk in sorted(d.glob("*/SKILL.md")):
            fm, _ = parse_frontmatter(read_text(sk))
            desc = f"{fm.get('name', sk.parent.name)}: {fm.get('description', '')} {fm.get('when_to_use', '')}"
            entry = item(root, sk, "skill-description", text=desc, description_chars=len(str(fm.get("description", ""))))
            if agent == "claude-code" and fm.get("disable-model-invocation") is True:
                entry["note"] = "manual-only: description not in context"
                hidden.append(entry)
            else:
                always.append(entry)
    return always, hidden

def claude_layers(root: Path, include_user: bool, res: dict):
    always, cond = [], []
    candidates = []
    for p in ancestors(root):
        for name in ("CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md"):
            # At HOME, .claude/CLAUDE.md IS the user memory: counts only with include_user.
            if (p / name).is_file() and (p / name).resolve() != USER_MEMORY.resolve():
                candidates.append(p / name)
    if include_user and USER_MEMORY.is_file():
        candidates.append(USER_MEMORY)
    seen = set()
    for c in candidates:
        if c.resolve() in seen:
            continue
        seen.add(c.resolve())
        always.append(item(root, c, "memory-file"))
        always.extend(claude_imports(root, c, seen=seen))
    # An AGENTS.md Claude reads directly costs the same as a CLAUDE.md and appears in
    # neither /memory nor /context, so it has to be visible somewhere. It is listed as
    # conditional, with the reason: whether the session really reads it cannot be settled
    # from disk, and a total that silently absorbs that guess is worse than two numbers.
    if res.get("agents_md_read") == "undetermined":
        for r in res["agents_md_files"]:
            p = (root / r) if not Path(r).is_absolute() else Path(r)
            if not p.is_file() or p.resolve() in seen:
                continue
            seen.add(p.resolve())
            cond.append(item(root, p, "agents-md-direct",
                             note="counts toward always-on only if direct reading is active in the session; "
                                  "left out of always_on_est_tokens while that is undetermined. Confirm with "
                                  "the line: no CLAUDE.md found; AGENTS.md loaded: <path>"))
            cond.extend(claude_imports(root, p, seen=seen))
    rule_dirs = [root / ".claude/rules"] + ([HOME / ".claude/rules"] if include_user else [])
    for rd in rule_dirs:
        for r in iter_md(rd):
            fm, _ = parse_frontmatter(read_text(r))
            if as_list(fm.get("paths")):
                cond.append(item(root, r, "rule-scoped", paths=as_list(fm.get("paths"))))
            else:
                always.append(item(root, r, "rule-unscoped", note="no paths: loads every session"))
    for sub in root.rglob("CLAUDE.md"):
        if sub.parent != root and ".git" not in sub.parts and "node_modules" not in sub.parts:
            cond.append(item(root, sub, "nested-memory", note="loads when files in this dir are read"))
    enc = "-" + str(root.resolve()).strip("/").replace("/", "-").replace(".", "-")
    mem = HOME / ".claude/projects" / enc / "memory/MEMORY.md"
    if mem.is_file():
        text = "\n".join(read_text(mem).splitlines()[:200])[:25000]
        always.append(item(root, mem, "auto-memory-index", text=text, note="first 200 lines / 25KB"))
    skill_dirs = [root / ".claude/skills"] + ([HOME / ".claude/skills"] if include_user else [])
    s_always, s_hidden = skill_listing(root, skill_dirs, "claude-code")
    always.extend(s_always)
    notes = ["Plugin skills, MCP server instructions and output styles also load; confirm with /context.",
             f"Instruction files resolved as: {res['effective'].get('claude-code', '')} "
             f"(Project instructions: {res['instruction_files']}, from {res['instruction_files_source']})."]
    if res["instruction_files_source"] not in (NOT_READ, "default") and res["instruction_files"] == "managed-only":
        notes.append("Project instructions is managed-only: the project, local and user files listed above are "
                     "NOT loaded at launch in this configuration, only the managed CLAUDE.md and auto memory.")
    pending = [x for x in cond if x["kind"] == "agents-md-direct"]
    if pending:
        notes.append("Outside the always-on total, pending confirmation: " +
                     ", ".join(f"{x['path']} ~{x['est_tokens']} tokens" for x in pending) +
                     f" (~{sum(x['est_tokens'] for x in pending)} tokens in all). Add them to the total if the "
                     "session shows the AGENTS.md loaded line; /context will not show them either way.")
    return always, cond, s_hidden, notes

# ---------------------------------------------------------------- codex
def codex_layers(root: Path, include_user: bool, cfg: dict):
    always, cond, notes = [], [], []
    cap = int(cfg["budgets"].get("codex_project_doc_bytes", 32768))
    if include_user:
        for n in ("AGENTS.override.md", "AGENTS.md"):
            if (HOME / ".codex" / n).is_file() and read_text(HOME / ".codex" / n).strip():
                always.append(item(root, HOME / ".codex" / n, "global-instructions"))
                break
    used = 0
    for n in ("AGENTS.override.md", "AGENTS.md"):
        p = root / n
        if p.is_file() and read_text(p).strip():
            e = item(root, p, "project-doc")
            used += e["bytes"]
            if used > cap:
                e["note"] = f"TRUNCATED: project doc chain exceeds {cap} bytes"
            always.append(e)
            break
    for sub in root.rglob("AGENTS.md"):
        if sub.parent != root and ".git" not in sub.parts and "node_modules" not in sub.parts:
            cond.append(item(root, sub, "nested-project-doc", note="loads only when Codex starts inside this dir"))
    s_always, _ = skill_listing(root, [root / ".agents/skills", root / ".codex/skills"] +
                                ([HOME / ".agents/skills", HOME / ".codex/skills"] if include_user else []), "codex")
    always.extend(s_always)
    notes.append(f"Codex caps the combined AGENTS.md chain at project_doc_max_bytes ({cap} bytes) and truncates silently.")
    notes.append("Codex has no @import: pointers must be plain paths the agent reads on demand.")
    return always, cond, [], notes

# ---------------------------------------------------------------- cursor
def cursor_layers(root: Path, include_user: bool):
    always, cond, notes = [], [], []
    if (root / "AGENTS.md").is_file():
        always.append(item(root, root / "AGENTS.md", "agents-md"))
    if (root / ".cursorrules").is_file():
        always.append(item(root, root / ".cursorrules", "legacy-cursorrules", note="deprecated: migrate to .cursor/rules"))
    for r in iter_md(root / ".cursor/rules"):
        text = read_text(r)
        if r.suffix != ".mdc":
            cond.append(item(root, r, "ignored-rule", note=".md in .cursor/rules is ignored; use .mdc"))
            continue
        fm, _ = parse_frontmatter(text)
        if fm.get("alwaysApply") is True:
            always.append(item(root, r, "rule-always"))
        elif as_list(fm.get("globs")):
            cond.append(item(root, r, "rule-globs", globs=as_list(fm.get("globs"))))
        elif fm.get("description"):
            always.append(item(root, r, "rule-agent-requested-description", text=str(fm.get("description"))))
            cond.append(item(root, r, "rule-agent-requested"))
        else:
            cond.append(item(root, r, "rule-manual"))
    s_always, _ = skill_listing(root, [root / ".cursor/skills"] + ([HOME / ".cursor/skills"] if include_user else []), "cursor")
    always.extend(s_always)
    notes.append("User Rules live in Cursor settings (not on disk) and always apply: review them manually.")
    return always, cond, [], notes

# ---------------------------------------------------------------- antigravity
def antigravity_layers(root: Path, include_user: bool):
    always, cond, notes = [], [], []
    if include_user and (HOME / ".gemini/GEMINI.md").is_file():
        always.append(item(root, HOME / ".gemini/GEMINI.md", "global-context"))
    for n in ("GEMINI.md", "AGENTS.md"):
        if (root / n).is_file():
            always.append(item(root, root / n, "context-file"))
    for r in iter_md(root / ".agents/rules"):
        always.append(item(root, r, "workspace-rule", note="assumed always-on; verify with agy inspect"))
    s_always, _ = skill_listing(root, [root / ".agents/skills"], "antigravity")
    always.extend(s_always)
    notes.append("Antigravity reads GEMINI.md literally (no @import expansion). Legacy Gemini CLI did expand @imports.")
    notes.append("If GEMINI.md and AGENTS.md both exist, their content is paid twice: keep one canonical.")
    return always, cond, [], notes

# ---------------------------------------------------------------- user runtime
# Plugins, custom agents, MCP servers and SessionStart hook output are always-on
# costs that never appear as files in the project. They are listed here so the
# baseline is not read as the whole story. Nothing in this section is executed,
# and no env value, header, URL or credential is ever written out.
SETTINGS_FILES = (".claude/settings.json", ".claude/settings.local.json", ".claude.json")

def _json(path: Path) -> dict:
    try:
        data = json.loads(read_text(path) or "{}")
    except ValueError:
        return {}
    return data if isinstance(data, dict) else {}

def user_settings():
    return [(p, _json(p)) for p in (HOME / f for f in SETTINGS_FILES) if p.is_file()]

def plugin_dir(marketplace: str, name: str) -> Path | None:
    """Resolve an enabled plugin to its folder on disk.

    ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/ is the installed copy.
    ~/.claude/plugins/marketplaces/ holds catalogs of plugins that are NOT installed,
    and *.bak copies are leftovers: neither may be counted.
    """
    base = HOME / ".claude/plugins/cache" / marketplace / name
    if not base.is_dir():
        return None
    versions = sorted((d for d in base.iterdir() if d.is_dir() and not d.name.endswith(".bak")),
                      key=lambda d: d.name)
    return versions[-1] if versions else (base if (base / ".claude-plugin").is_dir() else None)

def enabled_plugins():
    """[(id, marketplace, name, dir or None)] for every plugin switched on in settings."""
    out, seen = [], set()
    for _, data in user_settings():
        for pid, on in (data.get("enabledPlugins") or {}).items():
            if on is not True or pid in seen:
                continue
            seen.add(pid)
            name, _, marketplace = str(pid).partition("@")
            out.append((pid, marketplace, name, plugin_dir(marketplace, name)))
    return sorted(out)

def mcp_servers(plugins):
    """Server NAMES only. Values carry env, headers and tokens and are never read."""
    found = []
    for path, data in user_settings():
        for name in (data.get("mcpServers") or {}):
            found.append({"name": name, "source": rel(HOME, path)})
    for pid, _, _, d in plugins:
        if d and (d / ".mcp.json").is_file():
            for name in (_json(d / ".mcp.json").get("mcpServers") or {}):
                found.append({"name": name, "source": f"plugin:{pid}"})
    return found

def custom_agents(root: Path, plugins):
    out = []
    for p in sorted(iter_md(HOME / ".claude/agents")):
        fm, _ = parse_frontmatter(read_text(p))
        desc = f"{fm.get('name', p.stem)}: {fm.get('description', '')}"
        out.append(item(root, p, "agent-description", text=desc, source="user"))
    for pid, _, _, d in plugins:
        if not d:
            continue
        for p in sorted(iter_md(d / "agents")):
            fm, _ = parse_frontmatter(read_text(p))
            desc = f"{fm.get('name', p.stem)}: {fm.get('description', '')}"
            out.append(item(root, p, "agent-description", text=desc, source=f"plugin:{pid}"))
    return out

def session_start_hooks(plugins):
    """SessionStart commands whose stdout is injected into every session. Never run."""
    out = []

    def collect(data: dict, source: str):
        for group in (data.get("hooks") or {}).get("SessionStart") or []:
            for h in group.get("hooks") or []:
                if h.get("command"):
                    out.append({"command": safe_command(h["command"]), "source": source})

    for path, data in user_settings():
        collect(data, rel(HOME, path))
    for pid, _, _, d in plugins:
        if d and (d / "hooks/hooks.json").is_file():
            collect(_json(d / "hooks/hooks.json"), f"plugin:{pid}")
    return out

def user_runtime(root: Path):
    plugins = enabled_plugins()
    agents = custom_agents(root, plugins)
    hooks = session_start_hooks(plugins)
    servers = mcp_servers(plugins)
    return {
        "plugins": [{"id": pid, "installed": bool(d), "path": str(d) if d else None} for pid, _, _, d in plugins],
        "agents": agents,
        "agents_est_tokens": sum(a["est_tokens"] for a in agents),
        "mcp_servers": servers,
        "session_start_hooks": hooks,
        "notes": [
            f"{len(plugins)} enabled plugin(s), {len(agents)} custom agent(s), {len(servers)} MCP server(s) and "
            f"{len(hooks)} SessionStart hook(s) also consume always-on context.",
            "Plugin skills, MCP tool schemas and SessionStart hook output are NOT counted in est_tokens: "
            "their size is only known at runtime. Read the total from /context in a fresh session.",
            "Hooks are listed, never executed. MCP entries are names only, with no env, header, URL or token.",
        ],
    }

def on_demand(root: Path, cfg: dict):
    droot = docs_root(root, cfg)
    files = [item(root, p, "doc") for p in iter_md(droot)]
    vault = cfg.get("vault") or {}
    vfiles = []
    if vault.get("enabled") and vault.get("path"):
        vp = Path(str(vault["path"]).replace("~", str(HOME), 1)).resolve()
        if vp != droot and not str(droot).startswith(str(vp)):
            vfiles = [item(root, p, "vault-note") for p in iter_md(vp)]
        elif vp != droot:
            vfiles = [item(root, p, "vault-note") for p in iter_md(vp) if not str(p.resolve()).startswith(str(droot))]
    return files, vfiles

def build(root: Path, include_user: bool):
    cfg = load_config(root)
    agents = enabled_agents(root, cfg)
    resolution = instruction_resolution(root, include_user, agents)
    report = {"project": str(root), "agents": {}, "include_user": include_user,
              "instruction_resolution": resolution}
    for a in agents:
        if a == "claude-code":
            al, co, hid, notes = claude_layers(root, include_user, resolution)
        elif a == "codex":
            al, co, hid, notes = codex_layers(root, include_user, cfg)
        elif a == "cursor":
            al, co, hid, notes = cursor_layers(root, include_user)
        else:
            al, co, hid, notes = antigravity_layers(root, include_user)
        report["agents"][a] = {
            "always_on": al, "conditional": co, "manual_only": hid, "notes": notes,
            "always_on_est_tokens": sum(x["est_tokens"] for x in al),
            "conditional_est_tokens": sum(x["est_tokens"] for x in co),
        }
    if include_user:
        report["user_runtime"] = user_runtime(root)
    report["always_on_floor"] = True
    report["git_environment"] = git_environment()
    report["measurement_note"] = (
        "est_tokens counts files only and is a LOWER BOUND on always-on context. Plugins, MCP servers, "
        "custom agents and SessionStart hook output are not measurable from disk. The authoritative "
        "number is /context in a fresh session.")
    docs, vault = on_demand(root, cfg)
    report["on_demand"] = {"docs_count": len(docs), "docs_est_tokens": sum(x["est_tokens"] for x in docs),
                           "vault_count": len(vault), "vault_est_tokens": sum(x["est_tokens"] for x in vault),
                           "largest_docs": sorted(docs + vault, key=lambda x: -x["est_tokens"])[:10]}
    return report

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--project", default=".")
    ap.add_argument("--include-user", action="store_true", help="also read ~/.claude, ~/.codex, ~/.gemini")
    ap.add_argument("--out")
    a = ap.parse_args()
    root = find_project_root(Path(a.project))
    report = build(root, a.include_user)
    # The resolution goes to stderr as well: it is the one answer nobody can deduce from
    # the repository, and it would otherwise be buried in the JSON nobody reads by eye.
    res = report["instruction_resolution"]
    for agent, text in res["effective"].items():
        print(f"{agent} reads: {text}", file=sys.stderr)
    print(f"Project instructions: {res['instruction_files']} (from {res['instruction_files_source']})",
          file=sys.stderr)
    print(dump_json(report, Path(a.out) if a.out else None))

if __name__ == "__main__":
    main()
````

## File: skills/harness-audit/scripts/lint.py
size: 25483
sha: 8ef905304287e2d13496f0fde5c464b931efa58a
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/lint.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/lint.py

## File: skills/harness-audit/scripts/measure.py
size: 13298
sha: e4ed09586ed03ec90ff9202a0cac782efc4af295
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/measure.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/measure.py

## File: skills/harness-audit/scripts/sync.py
size: 6434
sha: cde4a4aa7997f644817da2b18bf4e336711ed631
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/sync.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/sync.py

## File: skills/harness-audit/scripts/transcripts.py
size: 5109
sha: f7932ddd8b2cb71d49f09994b8d5b176478f7135
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/transcripts.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/scripts/transcripts.py

## File: skills/harness-audit/references/agents/antigravity.md
size: 2148
sha: fa2122d0c94cf8394682e6bc3b91ba6e201d9ef7
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/agents/antigravity.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/agents/antigravity.md

## File: skills/harness-audit/references/agents/claude-code.md
size: 6425
sha: 7369d352dfd30bc5b971559a5b0a1f8cd601ad9f
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/agents/claude-code.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/agents/claude-code.md

## File: skills/harness-audit/references/agents/codex.md
size: 1867
sha: 461aa683a690f00f4b84aed4b95380864a3884e0
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/agents/codex.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/agents/codex.md

## File: skills/harness-audit/references/agents/cursor.md
size: 1742
sha: 31cddd8f849ed9fea7ec7487d9e4a0213aa19ec8
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/agents/cursor.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/agents/cursor.md

## File: skills/harness-audit/references/obsidian.md
size: 2594
sha: d437e3af04b0fec1db70f6c1f13f7ec8770911f1
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/obsidian.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/obsidian.md

## File: skills/harness-audit/references/principles.md
size: 3014
sha: 517c1db25b530c5cc9e1393f02961483adb40645
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/principles.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/principles.md

## File: skills/harness-audit/references/report-template.md
size: 2685
sha: 906bd2dc7574e2a598a410bd733e4df36805b94c
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/report-template.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/report-template.md

## File: skills/harness-audit/references/rubric.md
size: 6432
sha: 016af1f390b6d808024b18801bbec0f273901f84
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/rubric.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/references/rubric.md

## File: skills/harness-audit/assets/templates/ci/harness.yml
size: 642
sha: 8056057008b43c0387a56220ec8a1d5d7afe2866
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/assets/templates/ci/harness.yml

```text
name: harness
on:
  pull_request:
  push:
    branches: [main]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python3 .harness/scripts/sync.py --check
      - run: python3 .harness/scripts/lint.py
      # The code sensor runs only where it was installed. A missing baseline is not
      # a failure: the sensor creates it and passes, same as the first local run.
      - name: code sensor
        if: hashFiles('.harness/scripts/code_sensor.py') != ''
        run: python3 .harness/scripts/code_sensor.py
```

## File: skills/harness-audit/assets/templates/entry-block.md
size: 384
sha: d771f12e6376c44de6502c448353e9632ac146e9
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/assets/templates/entry-block.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/assets/templates/entry-block.md

## File: skills/harness-audit/assets/templates/harness-keeper-skill.tmpl
size: 2633
sha: c7d17c5033af3ca5e392a35755715cb888d9809a
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/assets/templates/harness-keeper-skill.tmpl

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/assets/templates/harness-keeper-skill.tmpl

## File: skills/harness-audit/assets/templates/hooks/antigravity.hooks.example.json
size: 689
sha: 00612cac4d48ba2bbff969672b5f1d12b46047fa
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/assets/templates/hooks/antigravity.hooks.example.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/assets/templates/hooks/antigravity.hooks.example.json

## File: skills/harness-audit/assets/templates/log.md
size: 270
sha: e0e11555b7d1ef6563414194255d77bc16cc1912
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/assets/templates/log.md

```text
---
description: Append-only chronological log of harness and knowledge changes. Newest at the bottom.
status: active
---
# Log

Format (one line per entry, parseable with `grep "^## \["`):
`## [YYYY-MM-DD] <ingest|decision|plan|doc|rule|skill|audit> | <what changed>`

```

## File: skills/harness-audit/assets/templates/PLACEMENT.md
size: 2692
sha: 3799cb9fa8929892606068081756ca23ddccfac4
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/assets/templates/PLACEMENT.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/assets/templates/PLACEMENT.md

## File: skills/harness-audit/assets/templates/rules-README.md
size: 420
sha: e878f4ad116f6ff8a7874a73eb155bdf33d9ce93
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/assets/templates/rules-README.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/skills/harness-audit/assets/templates/rules-README.md

## File: README.md
upstream: https://github.com/fabianmartinelli-fm/harness-audit/blob/main/README.md

````text
# harness-audit

**Cut what your coding agent loads before you type, and point it straight at what it needs.**

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Tests](https://github.com/fabianmartinelli-fm/harness-audit/actions/workflows/test.yml/badge.svg)](https://github.com/fabianmartinelli-fm/harness-audit/actions/workflows/test.yml)
![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-informational)
![Agents](https://img.shields.io/badge/agents-Claude%20Code%20%7C%20Codex%20%7C%20Cursor%20%7C%20Antigravity-8A2BE2)
![Obsidian](https://img.shields.io/badge/Obsidian-supported-7C3AED)

[Português (Brasil)](README.pt-BR.md)

harness-audit is an [Agent Skill](https://agentskills.io) that audits the harness of a software project (CLAUDE.md, AGENTS.md, GEMINI.md, rules, skills, hooks, docs and Obsidian notes), restructures it so agents start every session with a short map, measures the result, and installs guardrails so the project does not drift back into a mess.

It works with **Claude Code, Codex, Cursor and Antigravity CLI** (the successor of Gemini CLI), with or without an **Obsidian** vault.

---

## What it did on real repos

Session start, read from `/context` in a fresh session:

| Repo | Before | After |
|---|---|---|
| Large Next.js product repo | 555.8k tokens, 56% of a 1M window | 73.6k, 7% |
| Hospitality SaaS repo | 347.2k, 35% | 70.5k, 7% |

The finding that paid for the first audit was not size, it was silence. `AGENTS.md` had reached 349 KB against Codex's 32 KB read cap (`project_doc_max_bytes`), so the agent was receiving roughly the first tenth of it. No error, no warning, nothing in any log. On the second repo the same cap cut the file at 19.1%, mid-sentence, and `CLAUDE.md` had grown to 603,471 bytes, which meant nothing with a 200k window could open the project at all.

**The honest ceiling:** task success was 8/8 before the audit and 8/8 after. This does not make an agent smarter and never will. What moved was time (40 min to 7 across four tasks), operator interventions (2 to 0) and side effects (6 to 0).

The three pilots are written up as [open issues](../../issues), including a third one where the after-benchmark turned out to be invalid, and why.

---

## Contents

- [The problem](#the-problem)
- [What the skill does](#what-the-skill-does)
- [Commands](#commands)
- [Quick start](#quick-start)
- [Installation](#installation)
- [How it keeps the project organized](#how-it-keeps-the-project-organized)
- [What gets installed in your project](#what-gets-installed-in-your-project)
- [Compatibility](#compatibility)
- [Obsidian](#obsidian)
- [Measuring the results](#measuring-the-results)
- [Lint codes](#lint-codes)
- [Limits](#limits)
- [FAQ](#faq)
- [Contributing](#contributing)
- [Sources](#sources)

---

## The problem

Every token an agent loads before your first prompt competes for the model's attention. In real projects that layer grows quietly:

- instruction files turn into encyclopedias;
- the same paragraphs live in CLAUDE.md, AGENTS.md and GEMINI.md;
- `@imports` pull whole documents into every session;
- rules without scope load even when you never touch that code;
- dates and "currently working on" notes break prompt caching;
- notes pile up in Obsidian with no index an agent can use.

The research points in one direction. Model accuracy degrades as context grows (Chroma, *Context Rot*, 18 models tested). Instruction-following drops when files carry too many rules (HumanLayer). Redundant or auto-generated AGENTS.md files can lower task success and raise cost (ETH Zurich evaluation). Fewer, better-placed instructions work better than more instructions.

## What the skill does

1. **Interviews you briefly.** Detects which agents the project uses and whether there is an Obsidian vault, then confirms with you.
2. **Measures a baseline.** Tokens loaded per agent, per layer (always-on, conditional, on demand), plus runtime numbers from Claude Code and Codex transcripts.
3. **Scores the harness** on 8 dimensions and writes a change plan grouped by risk.
4. **Applies only what you approve**, on a separate git branch. It relocates content instead of deleting it.
5. **Installs a maintenance layer**: a placement map, an automatic keeper skill, hooks for each agent, a git pre-commit check and optional CI.
6. **Measures again** and writes a before/after report. Budgets are locked so they can only shrink.

## Commands

| Command | What it does | Changes project files? | When to use |
|---|---|---|---|
| `/harness-audit diagnose` | Detects agents and Obsidian vaults, asks you to confirm, measures the baseline, scores the harness and writes a plan with every proposed change, its risk and the tokens it saves. | No. Writes only to `.harness/reports/`. | First run on any project, or when budgets are breached. |
| `/harness-audit apply` | Creates a git branch, installs the maintenance layer, executes only the plan items you approved, regenerates the index and projections, and runs the lint until it is clean. | Yes, on a new branch, after approval. | Right after reviewing and approving the plan. |
| `/harness-audit verify` | Takes a new snapshot, compares it with the baseline, hands you the task benchmark prompts to run in a fresh session, locks the new budgets and writes `HARNESS-REPORT.md`. | Only reports and the budget lock. | After `apply`, in fresh agent sessions. |
| `/harness-audit check` | Runs the fast lint and summarizes problems by severity with suggested fixes. | No. | Weekly, before a release, or anytime. |

Running `/harness-audit` with no argument starts `diagnose`. `apply` refuses to run without an approved plan.

In agents without slash commands, just ask: *"run the harness-audit skill in diagnose mode"*.

### How changes are approved

| Risk | Examples | Approval |
|---|---|---|
| Low | frontmatter, index, broken links, moving files into the right folders | once, as a batch |
| Medium | moving content out of entry files into rules, skills or docs; scoping rules; turning prose rules into hooks | per group |
| High | merging or rewriting knowledge, archiving notes, anything outside the repo (user-level files, external vault) | item by item |

## Quick start

```bash
# 1. Install the skill for Claude Code
git clone https://github.com/fabianmartinelli-fm/harness-audit.git
cp -r harness-audit/skills/harness-audit ~/.claude/skills/

# 2. In your project, with everything committed
claude
> /harness-audit diagnose
```

Review `.harness/reports/plan.md`, approve, then run `/harness-audit apply` and `/harness-audit verify`.

## Installation

Requirements: **Python 3.9+** (standard library only) and **git**.

### Claude Code

```bash
cp -r skills/harness-audit ~/.claude/skills/          # personal, all projects
# or
cp -r skills/harness-audit .claude/skills/            # this project only
```

Keep the `disable-model-invocation: true` line in `SKILL.md`: it hides the skill from the model's context until you call it.

### Claude apps (Settings > Skills upload)

Download `harness-audit.zip` from the [latest release](https://github.com/fabianmartinelli-fm/harness-audit/releases/latest) and upload it. The release zip contains a single `SKILL.md` with standard frontmatter, as the upload requires. Use it where Claude can reach your local project files.

### Codex, Cursor, Antigravity

| Agent | Project folder | Notes |
|---|---|---|
| Codex | `.agents/skills/harness-audit/` | user-level skills folder per Codex docs |
| Cursor | `.cursor/skills/harness-audit/` | or `~/.cursor/skills/` |
| Antigravity CLI | `.agents/skills/harness-audit/` | shares `.agents/skills` with Codex |

### Build the packages yourself

```bash
python3 tools/build_dist.py
```

Creates `dist/harness-audit.zip` and `dist/harness-keeper.zip` (upload-ready, validated) and `dist/claude-code/` (filesystem copies with Claude Code extensions).

## How it keeps the project organized

Writing instructions is not enough, because instructi
````
