⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v1.5.2

harness-audit

fabianmartinelli-fm@fabianmartinelli-fm⭐ 8 stars· last commit 1mo ago· 4 open issues

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.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 8 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

harness-audit

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

License: MIT Tests Python 3.9+ Agents Obsidian

Português (Brasil)

harness-audit is an Agent Skill 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:

RepoBeforeAfter
Large Next.js product repo555.8k tokens, 56% of a 1M window73.6k, 7%
Hospitality SaaS repo347.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, including a third one where the after-benchmark turned out to be invalid, and why.


Contents


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

CommandWhat it doesChanges project files?When to use
/harness-audit diagnoseDetects 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 applyCreates 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 verifyTakes 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 checkRuns 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

RiskExamplesApproval
Lowfrontmatter, index, broken links, moving files into the right foldersonce, as a batch
Mediummoving content out of entry files into rules, skills or docs; scoping rules; turning prose rules into hooksper group
Highmerging or rewriting knowledge, archiving notes, anything outside the repo (user-level files, external vault)item by item

Quick start

# 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

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 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

AgentProject folderNotes
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

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

// HOW IT'S BUILT

// FILES

30 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/harness-audit/SKILL.md25 KB7ab57b723c7bupstream ↗
    ---
    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.
    
  • skills/harness-audit/scripts/benchenv.py6.5 KBf2de221dca2aupstream ↗
    #!/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()
    
  • skills/harness-audit/scripts/build_index.py3.1 KB97e2670a94a8upstream ↗
    #!/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()
    
  • skills/harness-audit/scripts/code_sensor.py5.2 KB53da25235f2fupstream ↗
    #!/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())
    
  • skills/harness-audit/scripts/detect.py5.6 KBd7675e96fd51upstream ↗
    #!/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()
    
  • skills/harness-audit/scripts/dirty.py11 KBbda773a78727upstream ↗
    #!/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()
    
  • skills/harness-audit/scripts/hlib.py15 KB88b8c73787b0upstream ↗
    """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] + "…"
    
  • skills/harness-audit/scripts/hook.py6.8 KB0827ea0f5f15upstream ↗
    #!/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)
    
  • skills/harness-audit/scripts/install.py19 KB37184616982eupstream ↗
    #!/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()
    
  • skills/harness-audit/scripts/inventory.py29 KB85ccefac8d19upstream ↗
    #!/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()
    
  • skills/harness-audit/scripts/lint.py25 KB8ef905304287upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/scripts/measure.py13 KBe4ed09586ed0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/scripts/sync.py6.3 KBcde4a4aa7997upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/scripts/transcripts.py5.0 KBf7932ddd8b2cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/references/agents/antigravity.md2.1 KBfa2122d0c94cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/references/agents/claude-code.md6.3 KB7369d352dfd3upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/references/agents/codex.md1.8 KB461aa683a690upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/references/agents/cursor.md1.7 KB31cddd8f849eupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/references/obsidian.md2.5 KBd437e3af04b0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/references/principles.md2.9 KB517c1db25b53upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/references/report-template.md2.6 KB906bd2dc7574upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/references/rubric.md6.3 KB016af1f390b6upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/assets/templates/ci/harness.yml642 B8056057008b4upstream ↗
    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
    
  • skills/harness-audit/assets/templates/entry-block.md384 Bd771f12e6376upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/assets/templates/harness-keeper-skill.tmpl2.6 KBc7d17c5033afupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/assets/templates/hooks/antigravity.hooks.example.json689 B00612cac4d48upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/assets/templates/log.md270 Be0e11555b7d1upstream ↗
    ---
    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>`
    
    
  • skills/harness-audit/assets/templates/PLACEMENT.md2.6 KB3799cb9fa892upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/harness-audit/assets/templates/rules-README.md420 Be878f4ad116fupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/fabianmartinelli-fm-harness-audit-skills-harness-audit.md

// REPO STATS

8 stars
4 open issues
Last commit: 1mo ago