scripts/README.md

Scripts

This directory contains harness automation tools.

Harness CLI

The Rust Harness CLI is the primary interface for the durable layer. Installed projects use the prebuilt binary at scripts/bin/harness-cli on macOS/Linux or scripts/bin/harness-cli.exe on Windows for normal Harness work.

scripts/bin/harness-cli init          # Create the database
scripts/bin/harness-cli intake ...    # Record a feature intake classification
scripts/bin/harness-cli story ...     # Add or update a story (test matrix row)
scripts/bin/harness-cli story update --id US-001 --unit 1 --integration 1 --e2e 0 --platform 0
scripts/bin/harness-cli story verify US-001  # Run the story's verify_command
scripts/bin/harness-cli decision ...  # Add a decision or run its verification
scripts/bin/harness-cli backlog ...   # Add or close a backlog item
scripts/bin/harness-cli trace ...     # Record and auto-score an agent execution trace
scripts/bin/harness-cli score-trace   # Score a trace against TRACE_SPEC.md tiers
scripts/bin/harness-cli query ...     # Query harness data, including backlog --open/--closed
scripts/bin/harness-cli query matrix --numeric  # Show proof flags as 1/0
scripts/bin/harness-cli db changeset apply .harness/changesets/run_123.changeset.jsonl
scripts/bin/harness-cli db rebuild --from .harness/changesets
scripts/bin/harness-cli migrate       # Apply pending schema migrations
scripts/bin/harness-cli --version     # Print the installed CLI version

Run scripts/bin/harness-cli help or scripts/bin/harness-cli query help for full usage. On Windows, use the same commands through .\scripts\bin\harness-cli.exe.

Proof flags on story update are numeric booleans: use 1 for yes and 0 for no. story verify <id> runs the configured verify_command; it does not accept proof flags. Configure the command with story add/update --verify, run story verify <id>, then update proof flags with story update.

Backlog --risk uses Harness lanes, not severity words: use tiny, normal, or high-risk. Use tiny instead of low. query matrix defaults to human-readable yes/no; use query matrix --numeric when copying values into story update.

The schema lives in scripts/schema/ and is version-controlled. The database file (harness.db) is .gitignored.

Set HARNESS_DB_PATH=/path/to/harness.db when a workflow needs harness-cli to operate on an isolated copied database. HARNESS_DB_PATH takes precedence over the legacy HARNESS_DB override; if neither is set, the CLI uses harness.db in the repository root.

Set HARNESS_RUN_ID=<run-id> during an isolated run to append semantic operation records to .harness/changesets/<run-id>.changeset.jsonl under the resolved repository root. The first write records a changeset.header; durable write commands append operation records such as story.update, trace.add, and decision.add. Normal CLI use without HARNESS_RUN_ID writes no changeset.

Requires: the prebuilt Rust CLI at scripts/bin/harness-cli on macOS/Linux or scripts/bin/harness-cli.exe on Windows.

Direct database inspection may still use SQLite tools, but normal Harness use should go through the Rust CLI.

Rust CLI Commands

Current migrated commands:

scripts/bin/harness-cli init
scripts/bin/harness-cli migrate
scripts/bin/harness-cli import brownfield
scripts/bin/harness-cli intake ...
scripts/bin/harness-cli story add ...
scripts/bin/harness-cli story update ...
scripts/bin/harness-cli story verify ...
scripts/bin/harness-cli decision add ...
scripts/bin/harness-cli decision verify ...
scripts/bin/harness-cli backlog add ...
scripts/bin/harness-cli backlog close ...
scripts/bin/harness-cli trace ...
scripts/bin/harness-cli score-trace
scripts/bin/harness-cli query matrix
scripts/bin/harness-cli query backlog
scripts/bin/harness-cli query decisions
scripts/bin/harness-cli query intakes
scripts/bin/harness-cli query traces
scripts/bin/harness-cli query friction
scripts/bin/harness-cli query stats
scripts/bin/harness-cli query sql ...
scripts/bin/harness-cli db changeset apply ...
scripts/bin/harness-cli db rebuild --from ...

scripts/bin/harness-cli import brownfield seeds or refreshes the durable database from existing Harness v0 markdown in docs/TEST_MATRIX.md, docs/decisions/, and docs/HARNESS_BACKLOG.md. This keeps already-installed Harness repos on the Rust CLI path without losing their populated operating docs.

Installer

The upstream installer applies the Harness v0 operating files and folder structure to a target project directory. It defaults to the current directory, accepts a target path, and asks interactive users whether to 1. Merge, 2. Override, or 3. Stop when the target already contains AGENTS.md, docs/, or scripts/. Non-interactive installs stop on those protected paths unless --merge or --override is provided. Use --merge as the safe update path for repositories that already have Harness: it keeps existing files in place and creates only missing Harness files. Add --refresh-agent-shim when an older install has the full generated Harness guide in AGENTS.md and should move to the small stable shim. Use --override only when replacing the protected Harness surface is intentional.

curl -fsSL "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.sh?$(date +%s)" | bash -s -- --yes

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.ps1"))) -Yes

curl -fsSL "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.sh?$(date +%s)" | bash -s -- --merge --yes

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.ps1"))) -Merge -Yes

curl -fsSL "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.sh?$(date +%s)" | bash -s -- --merge --refresh-agent-shim --yes

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.ps1"))) -Merge -RefreshAgentShim -Yes

--refresh-agent-shim backs up AGENTS.md before changing it. If the existing file is recognized as the old Harness-generated operating guide, the installer replaces it with the current shim. Otherwise it appends or replaces only the marked <!-- HARNESS:BEGIN --> block so project-specific instructions remain in place.

The installer must stay limited to harness files. Do not use it to scaffold application source folders, package scripts, CI, tests, platform shells, or fake validation commands. The installer script is not part of the installed project payload.

The file payload is declared once in scripts/harness-install-files.txt and is read by both the Bash and PowerShell installers. Add new Harness docs, templates, or decisions there instead of duplicating file lists in each installer. Schema migrations are different: both installers discover scripts/schema/*.sql automatically from the source repository, so adding a new migration only requires committing the SQL file.

By default the installer also downloads the prebuilt Rust Harness CLI for the current platform into scripts/bin/harness-cli on macOS/Linux or scripts/bin/harness-cli.exe on Windows, then verifies its .sha256 checksum. A source branch can pin the release used by the installer through scripts/harness-cli-release-tag; Phase 3 pins harness-cli-v0.1.4 so branch installs receive a Phase 3-built CLI. Set HARNESS_CLI_RELEASE_TAG to override that tag, or set HARNESS_CLI_BASE_URL to point at an alternate artifact directory, such as a local file:///.../dist directory created by scripts/build-harness-cli-release.sh.

Schema Migrations

Migration files live under scripts/schema/ and are named NNN-description.sql where NNN is a zero-padded version number. Run scripts/bin/harness-cli migrate to apply pending migrations.

Future Command Contract

Expected future checks:

validate:quick
  format, lint, typecheck, unit tests, architecture check

test:integration
  backend contract and integration checks

test:e2e
  user-visible end-to-end flows

test:platform
  platform shell smoke checks, if the project has a native shell

test:release
  full suite, log checks, and performance smoke

Release Packaging

Build the current-platform Rust CLI release artifact from the source repo:

scripts/build-harness-cli-release.sh

The script writes dist/harness-cli-<platform> plus .sha256 checksums. The Windows artifact includes the .exe suffix. Supported labels are:

• macos-arm64
• macos-x64
• linux-x64
• linux-arm64
• windows-x64

For cross-compilation, pass a Cargo target triple:

scripts/build-harness-cli-release.sh --target x86_64-unknown-linux-gnu

GitHub releases are produced by .github/workflows/harness-cli-release.yml. Push a tag matching v* or harness-cli-v* to run the verification job, build all supported targets on native hosted runners, and upload these release assets:

• harness-cli-macos-arm64
• harness-cli-macos-arm64.sha256
• harness-cli-macos-x64
• harness-cli-macos-x64.sha256
• harness-cli-linux-x64
• harness-cli-linux-x64.sha256
• harness-cli-linux-arm64
• harness-cli-linux-arm64.sha256
• harness-cli-windows-x64.exe
• harness-cli-windows-x64.exe.sha256

Merged PRs are handled by .github/workflows/post-merge-maintenance.yml. The workflow always prepends a PR summary to CHANGELOG.md. If the merged PR changed crates/harness-cli/, scripts/schema/, Cargo metadata, or scripts/build-harness-cli-release.sh, it also increments the CLI patch version, updates scripts/harness-cli-release-tag, creates a matching harness-cli-v* tag, and calls the reusable Harness CLI release workflow for the tagged ref.