# aih — Enterprise AI Bootstrapping Harness
[](https://github.com/samartomar/ai-harness/actions/workflows/ci.yml)
[](https://github.com/samartomar/ai-harness/actions/workflows/codeql.yml)
[](https://scorecard.dev/viewer/?uri=github.com/samartomar/ai-harness)
[](https://app.codecov.io/gh/samartomar/ai-harness)
[](LICENSE)
[](package.json)
Use the coding agent that fits your workflow. `aih` is a cross-platform CLI that
prepares developer workstations and repositories for **reviewable, governed
AI-assisted coding**, with repository-owned context, supported guardrails,
governed capability workflows, and verification surfaces.
It supports enterprise environments ranging from
locked-down, TLS-intercepted networks to open ones. It extracts corporate trust,
tunes local inference, adds repo guardrails, wires up MCP / observability /
sandboxing, and lays down a tool-agnostic context architecture — all from one
command surface. On top of that setup it runs a governance loop for external
agent skills — vet → approve → pack → marketplace → evidence — anchored in a
committed approval lock (`aih-skills.lock.json`).
See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the shipped architecture and
current trust boundaries, and [docs/CONTROL_MATRIX.md](docs/CONTROL_MATRIX.md) for
the claim -> implementation -> test proof map.
> **Provided as open-source software under Apache-2.0 on an "AS IS" basis.** No warranty,
> support obligation, SLA, indemnity, consulting, or professional advice is provided. `aih`
> is dry-run by default — review the plan before running `--apply`. See [DISCLAIMER.md](DISCLAIMER.md).
## The stable command contract
For the current v6 line, pin `@aihq/harness@^6` unless your organization pins an
exact release for reproducible rollout. Every command, flag, and deprecated alias is
snapshot-tested in CI against a committed fixture, the `--json` envelope is
schema-pinned, and exit-code semantics are pinned — a surface change fails the build
until it ships as a reviewed contract decision. Renames ship as deprecated aliases
(the old name keeps working, with a one-line warning) before a major removes them,
and security fixes land on the latest minor — upgrading is the fix path. The full
policy: [STABILITY.md](STABILITY.md).
## Design posture
## Install
Install and verify a published release. Current releases publish npm provenance plus GitHub release
checksums and a keyless cosign bundle:
```bash
npm install -g @aihq/harness@6.1.0 # then run: aih --help
aih verify-release 6.1.0 # checks npm signatures, GitHub release sums, and cosign evidence for 6.1.0
```
Full release verification requires local `npm`, `gh`, and `cosign`; proceed only when all three legs
pass. A skipped leg is incomplete evidence, not a successful rollout gate.
Per-version release notes — what changed, and why — live in
[CHANGELOG.md](https://github.com/samartomar/ai-harness/blob/main/CHANGELOG.md). It ships inside the
npm tarball too, so an evaluator can read the version history straight from the unpacked package.
Library integrations can import the strict Package Graph v1 TypeScript schema from
`@aihq/harness` and resolve its structural editor schema at
`@aihq/harness/schemas/aih-package-graph.schema.json`. Cross-record checks such as
identity uniqueness, direct-member resolution, and evidence subject binding belong
to the TypeScript parser; graph metadata is never approval or evidence by itself.
`buildPackageGraphIndex` retains every authority claim, preserves identical claims,
and reports divergent definitions without choosing a winner. Its canonical serializer
validates source references, claim and projection digests, and conflict records before
emitting byte-identical JSON. Source-store digests are caller assertions at this
layer; authority adapters are responsible for hashing exact store bytes. The pure
builder performs no I/O and never turns graph metadata into approval or evidence.
The exported Package Graph authority adapters hash the exact bytes they parse. They
join the shipped baseline catalog to its evidence lock, enrich exact ECC
materialization receipts, and project strict GitHub skill locks and pack catalogs
without mutating any source store. Discovery classification keeps exact
lock/receipt registrations, catalog-only membership, undeclared immutable residue,
divergence, and unsupported mutable observations separate. GitLab, Bitbucket,
Azure DevOps, and GHES adapters are not implemented.
The exported Strix detector contract is separate from static trust scanning. It
pins the verified Strix v1.5.2 source and immutable sandbox image identities,
preflights an operator-installed CLI plus an already-present runnable platform
manifest, and normalizes bounded headless output into strict PoC-redacted evidence.
Org policy can declare local-fixture-only intent with telemetry off and AIH hard
ceilings of $10, 20 turns, and five minutes. `aih evidence build` packages typed
records found under `.aih/security/strix` only after bounded, fatal-UTF-8,
whole-document validation. This foundation performs no scan, image pull, install,
or posture enforcement; publication does not claim AIH executed the detector.
From source (contributors)
```bash
npm install # deps
npm run build # → dist/cli.js (bin: aih)
node dist/cli.js --help
```
### Trust configuration notes
`trust.internalScopes` is intentionally inert until an org configures internal package scopes in
policy. Without that scope list, dependency-confusion checks still report general package risk but do
not guess which names are private to your organization.
### Baseline component evidence
`aih ecc` and `aih superpowers` acquire only exact Git commits into quarantine. Selected component
paths must match the vendor lock shipped in the npm release or an attributable GitHub-attested org
bundle. Covered user seats verify hashes and signatures; they do not rerun the release analyzers.
Missing/mismatched coverage warns without an authorization receipt at `vibe` and denies at
`enterprise`. A signed `blocked` verdict denies at every posture and cannot be waived by org
evidence for the same bytes. See [Baseline Component Evidence](docs/security/baseline-evidence.md)
for the vet/sign/policy flow.
### Analytics & operations
| Command | What it does |
| --- | --- |
| [`aih report`](docs/commands.md#aih-report) | Render the read-only analytics digest — context footprint, adoption, trends; `--v9`/`--open` build the offline HTML dashboard. |
| [`aih track`](docs/commands.md#aih-track) | Record one metrics sample (commits, LOC delta, adoption) to `.aih/history.jsonl` — the time-series behind `aih report` trends. |
| [`aih usage`](docs/commands.md#aih-usage) | Install the multi-tool usage-capture layer → `.aih/usage.jsonl` — local activity counts only, no cost, no prompts. |
| [`aih telemetry`](docs/commands.md#aih-telemetry) | Inject OpenTelemetry env, a redacting Bindplane collector, and an analytics fetcher. |
| [`aih mcp`](docs/commands.md#aih-mcp) | Generate MCP config for targeted CLIs; a bare first run stays on Claude, while `--detect` explicitly selects runnable tools. Use `--mcp-compliant` to omit denied generated servers from targeted configs. |
| [`aih sandbox`](docs/commands.md#aih-sandbox) | Generate a devcontainer + managed sandbox settings (egress allowlist, `failIfUnavailable`). |
### Verification
| Command | What it does |
| --- | --- |
| [`aih docs-lint`](docs/commands.md#aih-docs-lint) | Run the read-only BetterDoc prose check and claim-ledger gate over public Markdown; hard claim orphans fail closed, while prose guidance is advisory. |
| [`aih doctor`](docs/commands.md#aih-doctor) | Verify the workstation/repo configuration fail-closed; workspace mode validates each child repo, and Enterprise posture attests declared capability surfaces. |
| [`aih status`](docs/commands.md#aih-status) | Show a read-only inventory of what the harness has configured. |
Shared flags: `--apply`, `--force`, `--verify`, `--json`, `--posture `, `--support-out `, `--no-log`, `--context-dir `, `--root `, `--cli `, `--all-tools`, `--detect`, `--yes` (read-only commands take the relevant subset).
Settings also read from `AIH_*` env vars (`AIH_APPLY`, `AIH_CONTEXT_DIR`, `AIH_LOG`, …).
### Plugins
At startup `aih` probes for exactly one optional peer package: **`@aihq/enterprise`** — the literal
name, never env- or config-selectable, so nothing can point the probe at other code. The package name
is a reserved extension point; the open-source harness does not require it to be published. When installed,
it contributes additive enterprise command capabilities through its `aihCommands` export
(`CommandSpec[]`) as defined in the
[enterprise extension point spec](docs/product/enterprise-extension-point.md). Those commands register
as native subcommands through the identical path as the built-ins: shared flags, posture resolution,
the dirty-worktree gate, and the run ledger all apply unchanged. Not installed → zero output, fully
local. `AIH_NO_PLUGINS=1` disables the
probe. A plugin that fails to load, exports the wrong shape, or ships an invalid spec degrades to
local-only with a one-line `aih: plugin:` warning on stderr — and a plugin command can never shadow
a built-in (built-ins always win). Installing the plugin package **is** the trust decision:
importing it runs its code, exactly like any other dependency you install.
The probe is hardened at its seams. The package must resolve from **the install tree `aih` itself
runs from** (the `node_modules` chain above the aih binary), so a global or `npx`-run `aih` pointed
at an untrusted repo never imports a `node_modules/@aihq/enterprise` planted inside that repo.
Honesty note: when aih is installed *inside* the target repo, the repo already controls the binary
itself — the boundary is exactly "the tree aih runs from", nothing stronger. The import also races
a 2-second startup budget (timeout → local-only with a warning), and `aih --version` skips the
probe entirely. Plugin specs cannot claim shared or reserved flags (`--apply`, `--json`, `--help`,
…), cannot take the names `help`/`version`, and alias fields plus any `skipWorktreeGate` field are
stripped — aliases are core-owned and the dirty-worktree preflight always applies to plugin commands.
### Dashboard
`aih report --open` builds a **self-contained, offline** HTML dashboard (dark by default with a
light toggle; fonts embedded) — context footprint + a KPI strip, an adoption ring, output-velocity
and code-quality panels, and trend sparklines from recorded history (`aih track`). Add `--v9` for
the newer developer-console dashboard: every panel is explicitly LIVE, PREVIEW, or EMPTY, so demo
data never reads as real. When the report derives findings (see [Support tickets](#support-tickets)),
a **Suggested actions** section leads with copy-to-clipboard tickets. Add `--demo` for showcase data,
or `--refresh ` to keep it live.
*The `--v9` developer console with `--demo` showcase data: harness-wiring score, ranked
fix actions, and the remediation ledger. This image uses demo/local data, not customer
telemetry. `aih report --demo --v9` opens the same dashboard locally.*
### Targeting CLIs
`aih ecc`, `aih superpowers`, and `aih bootstrap-ai` only touch the agent CLIs you actually use.
Pass `--cli` with a comma-separated list, `--all-tools` for every supported CLI, or `--detect` to
auto-target the CLIs found on this machine; the default is `claude`. Supported:
`claude, codex, cursor, antigravity, gemini, copilot, windsurf, opencode, zed, kimi, kiro`.
At Enterprise posture, an org policy must declare a non-empty `governance.supportedClis` allow-list. Its absence fails closed and names the current registry ids so an administrator can deliberately paste the full list; wildcard sentinels are not supported. At Vibe posture, absence is unrestricted. A present list at either posture is an organization sanction gate: selected, detected, or marker-derived CLI targets outside it are refused by name before later capability checks, materialization, or projection.
```bash
aih bootstrap-ai --cli claude # writes CLAUDE.md (the default target, auto-loaded)
# repeatable declarations add to detection and the prior machine union
aih ecc --cli claude,codex --with framework:react --with lang:typescript
aih superpowers --cli antigravity # verify exact pin; guidance only (no mutable plugin exec)
aih bootstrap-ai --cli kiro --kiro-hook-runtime ide1-cli3 # Kiro IDE1/CLI3 hooks opt-in
aih bootstrap-ai --detect # target only the CLIs installed here
aih init . --all-tools # bootstrap a repo for every CLI at once
```
Each CLI gets its native entry: **Claude → `CLAUDE.md`** (the default target, auto-loaded),
Codex/OpenCode/Zed/Kimi/Antigravity → `AGENTS.md`, Gemini → `GEMINI.md`, Cursor →
`.cursor/rules/*.mdc`, Windsurf → `.windsurfrules`, Copilot → `.github/copilot-instructions.md`,
Kiro → `.kiro/steering/00-canon.md` (`inclusion: always`, with a `#[[file:…/RULE_ROUTER.md]]`
live-reference). For a tool aih doesn't target yet, `/adapters/other-tools.md`
documents how to point it at `RULE_ROUTER.md`.
**Per-tool depth (Kiro example).** Claude reuses your `~/.claude` baseline, so its entry is just
`CLAUDE.md`. Tools that can't read `~/.claude` get fuller native content instead — Kiro is the
deepest case (schemas verified against [Kiro's docs](https://kiro.dev/docs/steering/) and ECC's
real `.kiro/` tree):
- `aih bootstrap-ai --cli kiro` → `.kiro/steering/agent-tools.md` (stack-aware CLI usage).
Add `--kiro-hook-runtime ide1-cli3` to project standalone v1 `.kiro/hooks/*.json` hooks for
secret scan, tests-on-edit, and metrics-on-stop; the explicit capability is persisted for doctor.
Those hook files load in Kiro IDE 1.x and Kiro CLI 3.x. Kiro CLI 2.x keeps hooks inside each
custom-agent definition, so AIH does not mutate an arbitrary agent or claim hook coverage there.
A pre-existing reserved hook filename is never overwritten, and prune/uninstall leave current or
legacy hook names advisory because a filename alone cannot prove AIH ownership.
- `aih bootstrap-ai --detect` recognizes the documented `kiro-cli` executable. The public target
remains `kiro`; bare `kiro` is not treated as proof of the CLI because it can be an IDE/CLI router.
- `aih adopt --migrate-cli` inventories Kiro steering, hooks, custom-agent definitions, skills,
prompts, settings, and specs. Every `.kiro/agents/**` definition, including Markdown, remains
operator-owned runtime configuration; steering, skills, prompts, and specs can move into the canon.
- `aih policy project` can distribute reviewed stdio MCP selections to
`.kiro/settings/mcp.json` under receipt ownership of exact server names. It preserves unrelated
workspace configuration and never calls that managed enforcement: custom agents may override or
opt out of workspace MCP inheritance.
- `aih ecc --cli kiro` → emits scoped consult guidance; Kiro's native installer cannot yet
materialize the component union safely, so aih does not run it.
- In a governed repository, `aih ecc --lifecycle install --cli kiro` is a separate AIH-owned
path: it projects only evidence-passed selected agents with an exact pinned Kiro mapping, skills,
and steering from the exact pinned source, under dual selected/runtime evidence and receipt
ownership. A mapped agent lands as its exact selected `.kiro/agents/.md` IDE representation
and curated `.kiro/agents/.json` CLI configuration; an unmapped agent is reported by name,
while a pre-existing same-name Markdown/JSON definition, including a
case-folded spelling on a case-sensitive filesystem, is refused rather than overwritten. It does
not run or adopt the native installer or project hooks/settings/scripts.
- `aih superpowers --cli kiro` → `.kiro/steering/superpowers-methodology.md` (the
brainstorm → plan → TDD → review routing, since Kiro can't load `~/.claude/superpowers`).
**Detection** (`--detect`) targets runnable CLI binaries on PATH — and it is the *only* thing that
does. Nothing on your machine changes what a bare run targets: runnable binaries need `--detect`,
and config dirs (`~/.claude`, `~/.codex`, `~/.gemini`, `~/.cursor`, `~/.kiro`, …) are reported as
config-only traces that are advisory, may be stale, and never drive setup unless you type the CLI
with `--cli` or `--all-tools`. Precedence: `--all-tools` > `--cli` > `--detect` > committed marker >
default `claude`. When `--detect` finds no runnable CLI it defaults to `claude` and says so; a bare
run that defaults to `claude` while the repo already has other bootloaders (`AGENTS.md`, …) says
that too, naming the files it will not regenerate or drift-check. **In an interactive terminal,
`--detect` shows the runnable list and any config-only traces
before asking you to confirm or edit it** (press Enter to accept, or type a comma-separated list to
add/remove tools) before anything installs — pass `--yes` (or run non-interactively / piped /
`--json`) to skip the prompt and use the runnable list as-is. `aih doctor` reports runnable vs
config-only CLIs, and `aih bootstrap-ai --verify` adds a per-CLI **"installed"** confirm step (pass =
runnable binary on PATH, skip = config-only/not here yet, bootloader still written) alongside the
drift gate.
**Canon directory name.** Every generated file and reference adopts `--context-dir ` — use any
name you like; the default is the visible `ai-coding/`:
```bash
aih init # → ai-coding/ (default, visible)
aih init --context-dir my-canon # → my-canon/ (any name; everything adapts)
aih init --context-dir .ai-context # → hidden, the old default
```
ECC install actions execute under `--apply` only after exact component evidence clears and the same
quarantined tree re-hashes. By default, `aih ecc` materializes the additive union of its common
baseline, detected or repeatably declared project riders, posture-selected security, and validated
MCPs; `--profile full` is the explicit full-surface opt-in. Evidence verdicts apply per component:
authorized components install, while held components are quarantined and reported with their exact
codes and reasons. No install process starts unless ECC's installer runtime is also authorized.
The project contribution keeps the requested intent, while each target record contains only the
surface actually installed. The primary project/target contribution ledger lives at
`~/.aih/ecc/registration-ledger.json` and commits only after every install step succeeds. A bare
`aih prune` also checks that ledger: missing project roots are retired, the live
component/MCP union is recomputed, and only state-recorded aih-managed operations no longer shared
by a live project are removed. Dry-run reports the diff without mutation; `--apply` hash-binds all
inputs, rolls back partial failure, and replaces target state before committing the ledger last.
Superpowers marketplace/TUI paths cannot bind installed bytes to that
tree, so aih executes none of them; it emits pin-aware guidance and says those marketplace selections
are not evidence-covered. ECC and Superpowers are complementary — ECC supplies stack-aware rules,
agents, and memory; Superpowers supplies the disciplined agent loop that uses them.
For Codex, installed ECC skills are consumed on demand by name, such as `$configure-ecc`, from the
literal Codex skills path (`~/.codex/skills//SKILL.md`); they are not an ambient auto-loaded
`.agents/skills/` surface. `aih ecc --cli codex` still installs the selected ECC Codex
skills/agents from ECC's manifest, but uses add-only Codex TOML merge helpers and a fenced AGENTS
merge rather than the upstream `ecc-install --target codex` copy mode for shared `~/.codex` files.
Its scoped MCP block contains pinned `sequential-thinking` plus GitHub at enterprise (and
repo-declared local graph/memory servers); Context7 and Exa are never defaults.
For ECC's separate external MCP catalog, `governance.eccMcpApprovals` is only a seat approval record.
An operator still performs an explicit Add when a project needs one approved HTTPS entry:
`aih ecc mcp add memxus --cli claude --apply`. That path writes project-local JSON client configs for
Claude, Cursor, Copilot, Kimi, and Kiro; guarded global JSON configs for Antigravity, Gemini, Windsurf,
OpenCode, and Zed; and guarded Codex TOML. It records ownership under `.aih/`, removes only unchanged
receipt-owned entries with `aih ecc mcp remove --cli --apply`, and doctor reports local
receipt/config ownership state. It does not contact the endpoint, scan the remote tool list, or install all
approved entries.
The portable Policy Workbench uses a flat Ledger paper-and-ink identity in light and dark themes. Its left rail remains the canonical selection surface, including on compact screens; the inspector is mutation-free, narrates the selected-to-materialized journey, and offers one routed next action. Curation and custom-source forms live in a separate authoring sidebar. The separate Add MCP sidebar records the exact `governance.eccMcpApprovals` decision; it does not choose a client or configure one. For an entry marked HTTPS-configurable, the seat operator still selects one client explicitly with the command above; manual entries remain approval-only until a supported lifecycle exists.
The Workbench also authors source-locked ECC hook controls: Minimal, Standard, or Strict profile selection and eligible per-hook disables. Policy projection records those choices only as receipt-owned `ECC_HOOK_PROFILE` and `ECC_DISABLED_HOOKS` keys in Claude `settings.json.env`; it never rewrites ECC launchers. ECC executes and enforces the selection after process spawn, so disabling a hook does not erase its spawn cost.
### Layered AI canon (`bootstrap-ai`)
The harness models the same two-layer setup used in the reference repos (eicp / ai-os / syntegris):
- **Layer 1 — user baseline:** `--baseline ecc` — the default and sole selectable baseline
(ECC + Superpowers installed per CLI by `aih ecc` / `aih superpowers`).
- **Layer 2 — repo canon:** the committed `ai-coding/` (or `--context-dir`) tree — `RULE_ROUTER.md`
(stack-aware routing entry point), the contract files `project.json`, `project.md`, and `setup.md`,
`adapters/.md` (per-tool wiring notes), and the root **bootloaders** (`CLAUDE.md`, `AGENTS.md`,
`GEMINI.md`, Cursor/Windsurf/Copilot). `REGENERATION.md` is emitted only for `--canon legacy`.
`aih bootstrap-ai` generates and verifies Layer 2. Each bootloader is hand-editable tool-specific
content **plus one marker-delimited shared block** that `bootstrap-ai` regenerates idempotently —
your edits outside the markers survive (merged in, with an `.aih.bak` backup). `aih bootstrap-ai --verify`
is the **drift gate**: it fails if the router is missing or a bootloader's block has been hand-edited
away from the canonical source — wire it into CI to keep every tool's entry point in sync.
```bash
aih bootstrap-ai --all-tools --apply # lay down RULE_ROUTER + adapters + bootloaders for every CLI
aih bootstrap-ai --verify # CI drift gate (no writes; exit 1 on drift)
```
Precedence: **Layer 2 wins** on conflict — repo canon overrides the generic baseline. Run
`aih contract` to refresh the contract files the compact router points at.
### Multi-repo workspaces
Most orgs split a product across **separate repos** (a UI repo and a backend repo in one git org). An
agent editing the UI then has no view into the backend — no cross-repo blast radius. `aih workspace`
is a federated bridge, not a monorepo replacement: the child repo owns truth, and the parent workspace
owns routing, contract edges, snapshots, MCP wiring, and report rollups. It bridges that gap from the
**parent folder** that holds the repos:
```bash
aih workspace ./my-org --repos ui,backend --apply
```
It writes, at the parent (it does **not** touch the child repos — run `aih init` in each):
- `/cross-repo-architecture.md` — per-repo responsibilities + a **cross-repo feature map**
(UI column · backend column · the contract). **Write-once** — aih seeds it from your repo list, then
you own it; re-running never overwrites it.
- `/repo-discipline.md` — load a repo's own canon before editing it.
- Targeted CLI bootloaders — `CLAUDE.md` by default; `--cli`/`--all-tools` can add
`AGENTS.md`, `GEMINI.md`, `.kiro/steering/00-canon.md`, and other tool-native entries.
- `.code-workspace` — opens every repo in one VS Code window.
- `.mcp.json` — one **code-review graph MCP** per present declared child repo, using absolute
root-anchored child paths so MCP clients work from any launch directory.
- `.aih-workspace.json` — marker that puts `aih doctor` into **workspace mode** (validates each child
repo is scaffolded); object-form repos can retain optional `remote`/`ref` source metadata.
- Child repos are an explicit allowlist: use `--repos` or an existing `.aih-workspace.json`. If child
Git repos are present without an allowlist, `aih workspace` reports candidates but does not add them
to `.aih-workspace.json` or workspace MCP scope.
- `aih workspace snapshot --lock --apply` writes the recorded child remote into
`/workspace-lock.json` when present, so a lock captures both the commit and fetch
location. A manifest-declared `remote` takes precedence; otherwise snapshot collection reads only
child-local `origin` config and never fetches.
- `aih workspace hydrate --apply` restores a declared workspace from `.aih-workspace.json` plus the
committed workspace lock: missing children are cloned from recorded remotes, present clean children
are checked out to the recorded ref, and children with no recorded remote are skipped with a note.
Until a declared child exists, `aih workspace --apply` skips that child's graph MCP scope and emits
a hydrate note instead of wiring an empty path.
- `aih workspace graph` projects the **declared** contract edges into a queryable cross-repo graph:
`--repo`/`--from`/`--to`/`--kind` answer "what depends on what" from `.aih-workspace.json` alone,
and `--apply` writes the projection to `.aih/workspace-graph.json`. Declared topology is the source
of truth — the per-repo graph MCP servers are optional enrichment, never required.
### Support tickets
Any verifying command (`aih doctor`, `aih heal`, `aih secrets --verify`, …) turns a failed or skipped
check that carries a `Check.code` into a ticket-ready support template — three registers keyed off who
fixes the issue, and external tickets are tool-neutral by contract (they never name aih). Labels print
by default; `--support-out ` writes full tickets, `--json` carries them. Registers, redaction, and
the `SETUP.md` context markers: [docs/commands.md](docs/commands.md#support-tickets).
### Run ledger
Every `aih` invocation appends one structured row to **`.aih/runs/YYYY-MM.jsonl`** (UTC, month-sharded,
append-only) — a "what happened" diagnostics trail: schema version, run id, capability, redacted argv,
status (`success` / `failed` / `partial` / `error`), exit code, mode (apply/verify/json/sarif), platform,
host hash, repo remote hash, write tally, and verification + support counts. It's distinct from
`.aih/history.jsonl` (the per-commit metrics behind `aih report` trends). Logging is **on only after the
repo is initialised** (a committed `.aih-config.json` marker exists) and never fails a command; opt out
with **`--no-log`** or **`AIH_LOG=0`**. Like all of `.aih/`, the ledger is gitignored local diagnostics
— never committed. `aih evidence build` packages it into a checksummed bundle; use
`aih evidence build --sign --require-signature` when the bundle crosses a
sharing boundary that requires tamper evidence.
### Examples
```bash
aih doctor --json # what's configured? (read-only)
aih init . --apply # bootstrap the current repo
aih certs --ca-pattern Zscaler --apply --verify
aih hardware # preview the tuned inference env block
AIH_CONTEXT_DIR=ai-coding aih scaffold --apply
aih doctor --support-out .aih/tickets # write IT/support tickets for failing checks (kept local)
aih report --v9 --apply --out .aih/reports/local-v9.html
aih usage --apply --cli claude,codex,gemini
aih usage --rollup ../repo-a,../repo-b
```
## Releases & roadmap
- **Roadmap** — [ROADMAP.md](ROADMAP.md), tracked as
[GitHub Milestones](https://github.com/samartomar/ai-harness/milestones).
- **Changelog** — [CHANGELOG.md](CHANGELOG.md); tagged builds on
[Releases](https://github.com/samartomar/ai-harness/releases).
- **Versioning & support** — [VERSIONING.md](VERSIONING.md). SemVer; security fixes
land on the **latest minor** — upgrade to the latest release line to stay fixed.
- **Supply chain** — the current release workflow publishes via npm **Trusted Publishing** with build
**provenance** and ships an **SPDX SBOM**, a **SHA256 checksum**, its keyless **cosign
signature bundle** (`SHA256SUMS.txt.sigstore.json`), and the Sigstore **build-provenance
bundle** on the GitHub Release. Releases from `v0.6.0` onward include the sigstore/provenance
assets; earlier historical tags have a narrower asset set. Tagged release artifacts claim
[SLSA Build L2](docs/security/release-slsa.md) under SLSA v1.2; no Build L3 claim is
made. Verify a published release with `aih verify-release [version]`; a skipped verification leg
is incomplete evidence. Consumers with provenance-aware policy can also use `gh attestation verify`.
- **Support** — [SUPPORT.md](SUPPORT.md) · **Security** — [SECURITY.md](SECURITY.md)
(private reporting) · **Contributing** — [CONTRIBUTING.md](CONTRIBUTING.md).
## Development
```bash
npm test # vitest
npm run typecheck # tsc --noEmit
npm run lint # biome
npm run build # tsup → dist/
```
Stack: TypeScript (ESM) · commander · zod · vitest · biome · tsup. Coverage floors
are enforced in [vitest.config.ts](vitest.config.ts) — set just below the achieved
levels so coverage only ratchets up; CI and releases fail on regression. See
[CONTRIBUTING.md](CONTRIBUTING.md) for the contributor workflow.
### Stability
The tests behind [the stable command contract](#the-stable-command-contract) live in
[tests/contract/](tests/contract/): every command and option is snapshotted against a
committed fixture ([command-surface.json](tests/contract/command-surface.json)), the
`--json` envelope is schema-pinned, and exit-code semantics are pinned. Additive changes
regenerate the fixture in the same PR (label it `contract:additive`); removals or renames
of anything pinned are breaking and ship in majors only, per [STABILITY.md](STABILITY.md).
## License
[Apache-2.0](LICENSE).