@brainwav/coding-harness

Coding Harness

Coding Harness is a CLI control plane for repositories that use AI coding agents. Coding Harness exists to let humans steer and agents execute safely, with PR lead time as the primary north-star metric. Its north star is reducing PR lead time by shrinking the review and rework loop while keeping humans in the steering role and preserving strict evidence, SHA, and rollback discipline.

It is best thought of as the layer around the agents, not the agent runtime itself. It helps you make a repo safer to automate by giving it a contract, repo-local verification scripts, review policy, CI migration tooling, and artifact-backed rollout checks.

The shortest honest description of the project today is:

• it helps humans steer and agents execute safely
• it reduces PR lead time by making review and rework cheaper
• it gives downstream repos repo-local verification and preflight scripts
• it validates review, docs, plan, and authorization policy before merge
• it supports staged CI migration, rollback, and autonomy expansion with artifact-backed evidence

Table of Contents

• Start Here
• Lite Mode (Solo And Small Team)
• North Star
• Why Teams Use It
• What It Is Best At Today
• Security Posture Baseline
• Installation
• Repo-local Wrapper
• Repo-local Verification
• Common Workflows
  • Hero Workflow 1: Bootstrap a repository
  • Hero Workflow 2: Start work on an issue
  • Hero Workflow 3: Submit a change for review
  • Learning-loop closeout
  • Advanced: Migrate CI with rollback and proof
  • Advanced: Validate a Symphony workflow contract
  • Advanced: Evaluate a pilot before expanding autonomy
• Command Index
• Requirements
• Local Development
• Packaged Codex Skill
• Issue Reporting
• Trust Artifacts

Start Here

Get from zero to a governed, agent-ready repository in five steps (standard path):

# 1. Install
pnpm add -g @brainwav/coding-harness

# 2. Preview what harness will scaffold (no writes)
harness init --dry-run

# 3. Apply and track the scaffold
harness init --track

# 4. Validate the contract file
harness contract validate

# 5. Check overall repo health
harness health --json

That is the minimum viable path. The common routes beyond this are:

• Agent cockpit loop — run harness next --json, inspect safeToRun, then execute nextCommand only when it is safe; see CLI reference.
• Bootstrap a repository — dry-run, init, contract validate, health, upgrade
• Start work on an issue — linear prepare, preflight, policy gates
• Submit a change for review — docs-gate, review-gate, linear sync

For CI migration, pilot evaluation, or workflow contracts, see the advanced workflows below.

Lite Mode (Solo And Small Team)

Use lite mode when you want a low-friction setup first and governance depth later.

# 1. Minimal scaffold for solo/small-team adoption
harness init --minimal --track

# 2. Minimal policy contract (alias of minimal)
harness contract init --preset lite --force

# 3. Validate and inspect quickly
harness contract validate
harness check --json

Lite mode intentionally omits heavier surfaces such as docs-drift policy, diff budget policy, evidence policy defaults, and full governance policy sections. It keeps the contract focused on gate dispatch essentials.

Upgrade path from lite to standard:

harness contract init --preset standard --force
harness contract validate

That upgrade preserves your lightweight adoption start while adding the recommended default policy layers for team-scale operation.

North Star

Coding Harness is not trying to maximize governance surface area. Its canonical north star is to reduce PR lead time by shrinking the review and rework loop without weakening evidence quality, SHA discipline, or rollback safety.

• Humans steer. Agents execute.
• Low and medium-risk autonomy should be automated when evidence is deterministic.
• High-risk changes remain human-mediated.
• Repeated failures should become durable guardrails instead of repeated review comments or chat reminders.

The canonical statement of that contract lives in docs/roadmap/north-star.md.

North-star command outputs also use canonical artifact contracts so agents can carry evidence between tools without guessing path or schema names. The harness.contract.json product-surface registry records review cadence for these governed surfaces, so release readiness checks update the status matrix and its lastReviewedAt contract entry together. Current stable artifact paths include .harness/guardrails/north-star/drift-findings.json for drift-gate, .harness/guardrails/north-star/surface-classification-snapshot.json for doctor, and .harness/guardrails/north-star/alignment-decision.json for review-gate alignment decisions.

Why Teams Use It

Teams usually adopt Coding Harness for one of four jobs:

• Bootstrap a repo once, then keep it aligned. harness init can scaffold harness.contract.json, WORKFLOW.md, PR templates, CodeRabbit defaults, repo-local verification scripts, and rollback metadata instead of leaving each repo to invent its own setup.
• Put policy in code instead of chat reminders. Commands like docs-gate, plan-gate, review-gate, linear-gate, check-authz, and local-memory-preflight make governance expectations runnable.
• Change CI and review workflow without losing trust. ci-migrate, branch-protect, verify-coderabbit, and parity-proof tooling exist for controlled migration rather than "edit YAML and hope".
• Expand autonomy gradually. Pilot evaluation, rollback, workflow-contract validation, remediation, and evidence verification give teams a way to ask "should this be automated further?" with artifacts instead of instinct.

What It Is Best At Today

The code, tests, and recent history point to a few especially strong surfaces.

• Governed bootstrap and upgrade. init, upgrade, and eject are mature command families. They support dry runs, tracked updates, rollback, interactive review, minimal mode, and repo-specific scaffolding decisions.

• CI migration with proof and rollback. ci-migrate is one of the deepest tested surfaces in the repo. It supports prepare, verify, commit, abort, branch-protection sync, proof packs, and merge-queue cutover evidence.

• Review and governance gates. review-gate, docs-gate, ci-ownership-gate, verify-coderabbit, linear-gate, check-authz, and doctor are current, active surfaces. This repo now assumes CodeRabbit, not Greptile, as the primary AI review path.

• Pilot control-plane evaluation. pilot-evaluate, pilot-rollback, remediation, gap-case management, and workflow-contract scorecards are real product surfaces with substantial test coverage.

• Repo-local verification and preflight. Harness scaffolds scripts/codex-preflight.sh, scripts/verify-work.sh, and scripts/validate-codestyle.sh so a downstream repo has a local verification contract instead of a loosely documented checklist.

• Context, search, and multi-repo audit. search, context,

  source-outline, diagram/ERD context packs, index-context, context-health, tooling-audit, and org-audit make the project broader than "just repo init". It also helps teams inspect governed context and drift across repositories.

If you want the highest-confidence paths today, start with init, upgrade, ci-migrate, docs-gate or review-gate, verify-coderabbit, local-memory-preflight, and pilot-evaluate.

Security Posture Baseline

This repository tracks baseline security posture with OpenSSF OSPS + Scorecard artifacts that are versioned alongside code.

• Baseline status and control matrix: docs/security/2026-04-09-openssf-osps-baseline-status.md
• Scorecard floor policy: security/openssf-scorecard-policy.json
• Regression evaluator: scripts/check-scorecard-regressions.mjs
• Continuous CI security gate: .circleci/config.yml (security-scan in pr-pipeline)
• External Semgrep Cloud gate: GitHub required check semgrep-cloud-platform/scan
• Release workflow validation tool: ripgrep (rg) for docs:ubiquitous:guard during tag-triggered publish

Security scanning now runs in CircleCI as part of pr-pipeline. GitHub Actions in this repository is reserved for release publishing only (.github/workflows/release-private-npm.yml). That release workflow installs ripgrep before pnpm check because the docs:ubiquitous:guard step shells out to rg on GitHub-hosted runners. Semgrep Cloud is enforced separately as an external GitHub App required check. The machine-readable harness.contract.json ciOwnership block keeps that split explicit: CircleCI owns the primary PR gate, CodeRabbit remains the independent review check, Semgrep Cloud remains independent external security evidence, and any GitHub Actions fallback workflow must stay manual/emergency-only unless the contract is intentionally migrated.

Installation

Published package usage requires registry access to @brainwav/coding-harness.

pnpm add -g @brainwav/coding-harness
harness --help

If your team uses mise, this also works:

mise install -g npm:@brainwav/coding-harness

The package is best suited to repositories that want a governed local CLI surface. After installation, the usual next step is not "read every command", it is to run harness init --dry-run in the target repository and inspect the scaffold plan.

Repo-local Wrapper

harness init now scaffolds scripts/harness-cli.sh for downstream repos that want a repo-local wrapper around the published CLI package.

Use it like this:

bash scripts/harness-cli.sh verify-coderabbit

For script-driven gating in downstream repos, use:

bash scripts/run-harness-gate.sh <gate-command> [args...]

When run from a harness source checkout (@brainwav/coding-harness), use scripts/run-harness-gate.sh for fail-closed pnpm/tsx checks so the repo does not silently fall back to a different harness binary.

If the wrapper cannot resolve local @brainwav/coding-harness, treat that as a repo bootstrap/install problem, not a harness command failure. In a pnpm repo, repair it with:

pnpm install
pnpm add -D @brainwav/coding-harness
pnpm exec harness <command>

This matters because downstream repos can standardize on one local command surface even if contributors use different shells or global setups.

Repo-local Verification

Use bash scripts/verify-work.sh as the canonical repo-local verification entrypoint. It runs repo-local preflight in required Local Memory mode and then executes the full verification bundle.

When executable behavior changes, do not stop at broad validation alone. Run the smallest real code path that exercises the exact production code touched: prefer the production function, class, CLI command, shell script, validator, or route directly. If no existing test covers the path, use a temporary local reproduction harness under codex-scripts/ and keep that directory gitignored. If the exact path cannot run because it needs unavailable credentials, external services, unsafe side effects, or generated runtime state, say so explicitly and run the nearest meaningful validation instead.

For a quicker local loop, use:

bash scripts/verify-work.sh --fast

The fast lane now includes changed-file enforcement for public API docstrings, function/file size, and related tests through pnpm run quality:docstrings, pnpm run quality:size, and pnpm run test:related. Related tests must find and run a real Vitest related path; the gate no longer passes silently when no test covers changed production source.

For downstream repos, this is one of the most practical parts of harness. It turns "what do I need to run before handoff?" into a single local command.

Common Workflows

Hero Workflow 1: Bootstrap a repository

Start with a preview, then write tracked changes once the diff looks right.

harness init --dry-run
harness init --track
harness contract validate
harness health --json

This is the best path when you want a governed starting point quickly. In the common case, init --track gives you the contract, workflow scaffolding, review policy surfaces, repo-local verification scripts, and enough metadata to upgrade or roll back cleanly later.

Use these follow-ups when the repo already has harness material:

harness init --check-updates
harness upgrade --dry-run
harness upgrade

If a legacy .harness/restore-manifest.json is missing ciProvider, harness will repair it automatically when the active provider can be inferred from harness.contract.json, an unambiguous CI layout on disk, or the requested or default init/upgrade provider.

If tracked baseline files are missing and you need to re-scaffold them:

harness init --update
harness init --interactive

To specify or override the detected project type during init:

harness init --project-type web       # explicit: cli | desktop | library | web
harness init --project-type cli --json  # machine-readable structured output

Use the contract surface when you want confidence that the repo policy file is still valid or you need a schema for editor and automation tooling:

harness contract validate
harness contract validate --json
harness contract schema > harness.contract.schema.json

Hero Workflow 2: Start work on an issue

Prepare branch context from a Linear issue, run preflight checks, then gate each file as you work.

harness linear prepare --issue <KEY>         # pre-fill branch, PR title, closing line
harness preflight-gate --contract harness.contract.json --files <comma-separated-changed-files> --admission-file artifacts/admission/declaration.json
harness policy-gate --contract harness.contract.json --files <comma-separated-changed-files>
harness blast-radius --files <comma-separated-changed-files> --json   # see which gates apply

The linear prepare command outputs a branch name, PR title, and body fragment so you never need to construct these by hand or from memory.

For contracts with a northStar block (harness.contract.json v1.6+), preflight-gate requires an admission declaration via --admission-file <path>. Use --skip admission-declaration only when bypass is explicitly authorized for the run.

preflight-gate exit codes are command-specific: 0 for pass, 1 for policy violations, 3 for contract load or existence failures, and 10 for unexpected system errors. Automation workflows that need richer categorization should also consume the JSON payload.

Hero Workflow 3: Submit a change for review

Gate the change locally before pushing, then confirm review wiring is correct.

harness docs-gate --mode advisory --json
harness plan-gate --require-plan-id --require-traceability --json
harness review-gate --token "$GITHUB_TOKEN" --owner <owner> --repo <repo> --pr <number> --sha <head-sha>
harness linear sync --findings findings.json --team <TEAM>

If harness.contract.json declares governed north-star surfaces and your diff touches one of them, review-gate also requires four PR-body decisions: lead_time_path, manual_glue, agent_reliability, and safety_floor. Each line must answer yes and include an Evidence: reference. Repos that do not declare northStar governance or do not touch governed surfaces keep the legacy SHA and review-check behavior. If review-gate returns review_evidence_incomplete or review_evidence_contradiction, update the PR body with the required decision lines and evidence, or roll back high-risk changes until evidence is coherent; see review-gate north-star evidence for complete recovery steps.

For repos using CodeRabbit, pair the review-gate with:

harness verify-coderabbit --json

That gives you a concrete local answer for "is the repo-side review wiring correct?" before you debug GitHub-side behavior.

Learning-loop closeout

When a repository has imported CodeRabbit learning evidence, use the learning loop before PR handoff so repeated review feedback becomes guardrail data instead of another comment thread.

harness learnings gate --source .harness/learnings/coderabbit.local.json --files <changed-files> --json
harness review-context --source .harness/learnings/coderabbit.local.json --files <changed-files> --json
harness north-star-feedback --source .harness/learnings/coderabbit.local.json --json

The --files value accepts comma-separated paths or multiple following path tokens.

If a repeated high-usage learning appears, promote it into a concrete validator, gate, scaffold regression, generated-artifact rule, review-context fact, or explicit exception. Use Project Brain for the durable distilled rule or decision, and keep the imported learning artifact as the machine-readable evidence source. If no local learning artifact exists yet, record that as n.a. in the PR evidence rather than pretending the loop ran.

Advanced: Migrate CI with rollback and proof

harness ci-migrate prepare --provider circleci --dry-run
harness ci-migrate prepare --provider circleci --apply
harness ci-migrate verify --snapshot <snapshot-id>
harness ci-migrate commit --snapshot <snapshot-id>

Use abort or --rollback if parity or external control-plane checks fail. For cutover follow-through, the same command family also supports:

harness ci-migrate sync-branch-protection
harness ci-migrate promote-mode

Advanced: Validate a Symphony workflow contract

Coding Harness can scaffold a WORKFLOW.md, generate compact workflow specs, and validate readiness for Symphony-style execution.

harness workflow:generate --source docs/specs/my-flow.md --output WORKFLOW.md
harness symphony-check
pnpm workflow:validate

To keep Linear metadata and findings aligned from the same CLI surface:

harness linear prepare --issue JSC-123
harness linear sync --findings findings.json --team JSC

This is one of the more understated parts of the project today: it is not only scaffolding repo files, it also includes machinery for defining, checking, and operating workflow contracts.

Advanced: Evaluate a pilot before expanding autonomy

harness pilot-evaluate --artifacts artifacts/pilot --lane health --output artifacts/pilot/result.json
harness pilot-rollback --mode manual

This part of the CLI is designed for artifact-backed rollout decisions, not just dashboard reporting.

Command Index

The tables below keep README parity with the CLI while staying short. For full flags, use harness --help.

For agent planning and command safety routing, prefer the machine-readable capability catalog:

harness commands --json

Use the catalog directly to choose a safe command before execution:

# Human workflow: inspect mutative commands and required flags
harness commands --json | jq '
  .commands[]
  | select(.mutability != "read")
  | {name, category, mutability, requiredFlags}'

# Agent workflow: route to read-only alternatives first when available
harness commands --json | jq '
  .commands[]
  | {name, mutability, safeFirstAlternatives}
  | select((.safeFirstAlternatives | length) > 0)'

Bootstrap And Governance

Command	Purpose
commands	Emit the versioned machine-readable command capability catalog (--json)
init	Scaffold or update harness-managed repo surfaces (--project-type, --json, --dry-run, --force, --track, --update, --migrate, --minimal, --issue-tracker)
eject	Safely remove harness-managed files and templates, including legacy Greptile artifacts, while preserving custom non-Greptile CI workflows (--dry-run, --force)
check	Zero-config repo health snapshot — works before full setup
next	Agent-native cockpit entrypoint that recommends the next safe existing command (--json, optional --files, optional --mode local|pr|ci)
audit	Audit for configuration drift, parity gaps, and governance posture
doctor	Check all gate prerequisites (tools, files, config, CI)
health	Unified gate status scorecard across all gates
brain	Query and update Project Brain context artifacts
contract	Validate harness.contract.json or print the JSON Schema (init, validate, schema)
upgrade	Safely upgrade harness in an existing repo (--dry-run, --json preview supported)
ci-migrate	Stage, verify, commit, abort, sync branch protection, or promote CI mode
branch-protect	Configure GitHub branch protection rulesets
verify-work	Run canonical repo-local verification (fresh or resume mode)
verify-coderabbit	Verify CodeRabbit configuration and remote wiring
preset	List and inspect bundled presets
symphony-check	Validate WORKFLOW.md, Linear config, and transition-table readiness

Review And Policy Gates

Command	Purpose
policy-gate	Validate policy expectations from changed files
preflight-gate	Run fast policy checks before expensive work
review-gate	Validate SHA-linked review readiness (review check + review-policy required checks)
docs-gate	Enforce documentation parity for governed changes
plan-gate	Validate plan IDs, traceability, and acceptance evidence
brainstorm-gate	Validate brainstorm artifacts
prompt-gate	Validate prompt template usage
pr-template-gate	Validate PR template completion and placeholder replacement
license-gate	Validate open-source license expectations
check-authz	Validate authorization policy for mutative operations
check-environment	Validate pilot environment governance checks
local-memory-preflight	Run the structured Local Memory preflight smoke checks
artifact-gate	Check generated artifact changes against the artifact provenance registry
ci-ownership-gate	Validate CircleCI primary ownership plus CodeRabbit and Semgrep required checks
blast-radius	Determine required checks from changed files
risk-tier	Classify changed files by risk tier
diff-budget	Enforce diff budget constraints
observability-gate	Check metrics cardinality limits
silent-error	Detect silent error-handling anti-patterns
memory-gate	Validate local-memory workflow compliance

Linear And Workflow Operations

Command	Purpose
linear	Claim, hand off, close, prepare, or sync Linear work from one command family
linear-gate	Enforce Linear-first intake, branch naming, and PR linkage
workflow:generate	Generate compact workflow specs from annotated markdown

Pilot, Remediation, And Automation

Command	Purpose
pilot-evaluate	Evaluate pilot metrics and determine promotion readiness
pilot-rollback	Move pilot mode between autonomous and manual states
simulate	Run counterfactual policy simulation
automation-run	Execute idempotent automation playbooks
gap-case	Manage production gap cases
remediate	Plan and run deterministic remediation for findings
replay	Re-run policy checks from saved snapshots

Drift, Search, And Evidence

Command	Purpose
drift-gate	Evaluate consistency drift across governance surfaces
org-audit	Scan multi-repo governance and drift posture
tooling-audit	Audit managed repo tooling baselines
gardener	Detect stale docs and broken links
context-health	Generate advisory context-integrity scorecards
learnings	Import local operational review evidence, run exact-file learning gates, and generate high-usage promotion candidates via learnings import, learnings gate, and learnings promote
review-context	Generate PR review context from changed files and imported operational learnings, including applicable learned constraints and validation-plan entries
validation-plan	Recommend repo-canonical validation commands from changed files and imported validation-contract learnings, with network-required commands separated
artifact-gate	Check changed generated artifacts against .harness/artifact-provenance.json so template/source edits accompany runtime mirrors
ci-ownership-gate	Validate that CircleCI owns the primary PR workflow while CodeRabbit and Semgrep Cloud remain independent required checks
search	Run hybrid lexical and semantic search; if --limit or --threshold is omitted, contextCompact policy applies when present, otherwise static defaults (DEFAULT_SEARCH_LIMIT, DEFAULT_SIMILARITY_THRESHOLD) are used
context	Search indexed plans, specs, and brainstorms; if --limit or --threshold is omitted, contextCompact policy applies when present, otherwise static defaults (DEFAULT_SEARCH_LIMIT, DEFAULT_SIMILARITY_THRESHOLD) are used

| source-outline | Inspect TypeScript-family signatures and comments before opening implementations, with optional single-symbol implementation unwrapping via --symbol |

| index-context | Build the local semantic-search index | | evidence-verify | Validate screenshot and evidence artifacts | | ui:fast | Run a Storybook-first local UI loop | | ui:verify | Run Playwright smoke verification with evidence capture | | ui:explore | Run agent-browser exploratory testing |

For agent source inspection, use harness source-outline <path> before opening raw TypeScript-family files. If implementation detail is needed, unwrap one symbol at a time with --symbol <name> so context growth stays deliberate.

After instruction discovery, use AI/context/diagram-context.md as the compact architecture map; it combines Mermaid architecture, dependency, database, and ERD diagrams, with .diagram/manifest.json available when a narrower diagram file is enough.

Requirements

• Node.js: >= 24.0.0
• Package manager for this repo: pnpm@10.33.0
• GitHub auth: required for commands that inspect or mutate remote GitHub state, including branch-protect, review-gate, and remote CodeRabbit checks
• Linear auth: required for linear* flows and for a clean symphony-check result
• Local Memory: required for repo-local required preflight mode and for the default scripts/verify-work.sh flow scaffolded into downstream repos
• Ollama/local embeddings: required for the semantic side of search, context, and index-context
• Browser automation tooling: required for ui:verify and ui:explore workflows
• Ralph CLI: required for environment readiness and CircleCI orb-pinning validation (ralph --version)

Coding Harness does not create secrets for you and does not bypass branch protection or review policy. It also does not run your CI provider or agent runtime for you. Its job is to scaffold, validate, and enforce the control-plane layer around those systems.

Local Development

If you are developing this repository itself:

mise trust            # activate pinned toolchain from .mise.toml
make setup            # installs deps + configures git hooks
pnpm build
pnpm exec tsx src/cli.ts --help
pnpm check

When you change executable behavior in this repository, run the smallest real path that exercises the touched production code before claiming it works. If you need a throwaway reproduction harness, keep it under codex-scripts/ so it stays local-only.

When you change runtime behavior or artifact formats, run the deeper validation path as well:

pnpm test:deep

Packaged Codex Skill

The npm package ships a reusable Codex skill at .agents/skills/coding-harness/SKILL.md.

It covers:

• harness install and update workflows
• capability boundaries and safe usage rules
• command discovery and validation expectations

Run the packaged-skill validation lane after changing the bundle:

pnpm skill:validate

Repository-local skills follow the same convention:

.agents/skills/<skill-name>/SKILL.md

Issue Reporting

This repository uses Linear-first intake. Create or update work in the coding-harness project.

Trust Artifacts

Reference outputs for the main trust surfaces are in docs/examples/trust-artifacts/. These examples let you verify what the harness produces without running the full system.