feat: harness bootstrap

.github/workflows/harness.yml

@@ -0,0 +1,24 @@
+name: Harness CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  harness:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Run harness pipeline
+        run: make ci

.gitignore

@@ -1 +1,3 @@
 .worktrees/
+.worktree/
+harness/target/

AGENTS.md

@@ -0,0 +1,53 @@
+# Repository Map
+
+Use this file as a table of contents only. Canonical guidance lives in the linked documents.
+
+```
+AGENTS.md
+ARCHITECTURE.md
+NON_NEGOTIABLE_RULES.md
+docs/
+├── design-docs/
+│   ├── index.md
+│   ├── core-beliefs.md
+│   ├── local-operations.md
+│   ├── observability-shim.md
+│   └── worktree-isolation.md
+├── exec-plans/
+│   ├── active/
+│   ├── completed/
+│   └── tech-debt-tracker.md
+├── generated/
+├── product-specs/
+│   ├── index.md
+│   └── harness-demo-app.md
+├── references/
+│   └── codex-app-server-llm.txt
+├── PLANS.md
+```
+
+## Start Here
+
+- Rules that block merge: `NON_NEGOTIABLE_RULES.md`
+- System map and package boundaries: `ARCHITECTURE.md`
+- Design doc index and ownership: `docs/design-docs/index.md`
+- Product docs: `docs/product-specs/index.md`
+- Execution plan policy: `docs/PLANS.md`
+
+## Runtime Surfaces
+
+- Ralph Loop CLI: `./ralph-loop`
+- Harness CLI: `harness/target/release/harnesscli`
+- Harness Make targets: `Makefile.harness`
+
+## Specs In Repo
+
+- Current product spec: `SPEC.md`
+- Ralph Loop spec import: `specs/ralph-loop/SPEC.md`
+- Harness spec import: `specs/harness-spec/SPEC.md`
+
+## Working Rules
+
+- Keep this file short and navigational.
+- Put substantive guidance in the linked docs, not here.
+- Update the relevant canonical doc when code or operating practice changes.

ARCHITECTURE.md

@@ -0,0 +1,70 @@
+# Architecture
+
+## Purpose
+
+This repository currently contains two related systems:
+
+1. A Go implementation of `ralph-loop`, an agent-first CLI that prepares a worktree, drives Codex through a setup and coding loop, and streams structured run data.
+2. A Rust `harnesscli` bootstrap that turns the repository into a harnessed codebase with stable commands for smoke, lint, typecheck, test, audit, init, boot, observability, and cleanup.
+
+The long-term product direction in [`SPEC.md`](SPEC.md) is a Git impact analyzer. The code that exists today is still mostly harness and orchestration infrastructure.
+
+## Package Boundaries
+
+### Go runtime
+
+- `cmd/ralph-loop`
+  - Thin CLI entrypoint.
+  - Resolves the current working directory and hands control to `internal/ralphloop`.
+- `internal/ralphloop`
+  - Parsing, schema generation, worktree management, session tracking, log handling, JSON-RPC transport, and orchestration.
+  - This package is the only place that should contain Ralph Loop behavior.
+
+Dependency direction:
+
+- `cmd/ralph-loop` -> `internal/ralphloop`
+- `internal/ralphloop` -> Go standard library
+
+### Rust harness runtime
+
+- `harness/src/main.rs`
+  - `clap` entrypoint and shared process exit handling.
+- `harness/src/cmd/*`
+  - One module per command group.
+- `harness/src/util`
+  - Shared output, process, worktree, and filesystem helpers.
+
+Dependency direction:
+
+- `main` -> `cmd`, `util`
+- `cmd/*` -> `util`
+- `util` -> Rust stdlib plus small serialization helpers
+
+## Repository Zones
+
+- `specs/`
+  - Imported upstream specs and references. Treat these as vendored inputs, not primary implementation locations.
+- `docs/design-docs/`
+  - Canonical operational and engineering rationale.
+- `docs/product-specs/`
+  - Product-facing behavior descriptions, including the harness demo app contract.
+- `docs/exec-plans/`
+  - Checked-in execution plans and technical debt tracking.
+- `.worktree/`
+  - Runtime state generated per Git worktree by the harness system.
+
+## Entry Points
+
+- `./ralph-loop`
+  - Repo-root executable wrapper around `go run ./cmd/ralph-loop`.
+- `cargo build --release --manifest-path harness/Cargo.toml`
+  - Builds `harnesscli`.
+- `make ci`
+  - Stable top-level validation flow once the harness is built.
+
+## Boundary Rules
+
+- Do not add new Ralph Loop logic under `cmd/`.
+- Do not place durable operating guidance in `AGENTS.md`.
+- Do not edit imported spec files unless the change is explicitly a spec sync.
+- All new automation-facing repository operations should prefer `harnesscli` subcommands over ad hoc shell scripts.

Makefile

@@ -0,0 +1 @@
+-include Makefile.harness

Makefile.harness

@@ -0,0 +1,22 @@
+HARNESS := harness/target/release/harnesscli
+
+.PHONY: smoke test lint typecheck check ci harness-build
+
+harness-build:
+	@cargo build --release --manifest-path harness/Cargo.toml
+
+smoke: harness-build
+	@$(HARNESS) smoke
+
+test: harness-build
+	@$(HARNESS) test
+
+lint: harness-build
+	@$(HARNESS) lint
+
+typecheck: harness-build
+	@$(HARNESS) typecheck
+
+check: lint typecheck
+
+ci: smoke check test

NON_NEGOTIABLE_RULES.md

@@ -0,0 +1,25 @@
+# Non-Negotiable Rules
+
+These rules are absolute. Violations block merge.
+
+## Rule 1: New Behavior Must Be Tested
+
+- Every new command, module, and branch of behavior needs tests before merge.
+- Changes to existing behavior must update tests in the same change.
+- For this repository, that means both Go tests for `internal/ralphloop` and Rust tests for `harnesscli` when those surfaces change.
+
+## Rule 2: Machine-Readable Automation Is Required
+
+- Automation-facing commands must support structured output.
+- JSON is the default for non-TTY execution.
+- Errors in automation flows must be emitted as structured payloads, not prose-only failures.
+
+## Rule 3: No Blind Sleeps For Readiness
+
+- Any boot or lifecycle command must verify readiness with a real probe.
+- If readiness cannot be proven, the command must fail non-zero and report the failing resource.
+
+## Rule 4: Repository Knowledge Is Canonical
+
+- Durable product, runtime, and architecture guidance belongs in versioned repo docs.
+- `AGENTS.md` stays navigational; substantive guidance belongs in `ARCHITECTURE.md` or `docs/`.

docs/PLANS.md

@@ -0,0 +1,32 @@
+# Plans
+
+Execution plans are first-class repository artifacts.
+
+## Locations
+
+- `docs/exec-plans/active/`
+  - In-flight work with current milestone status.
+- `docs/exec-plans/completed/`
+  - Archived plans that reflect what actually shipped.
+- `docs/exec-plans/tech-debt-tracker.md`
+  - Known debt, missing invariants, and follow-up cleanup items.
+
+## When To Create A Plan
+
+- Create a checked-in plan for multi-step work, cross-file refactors, harness changes, and anything likely to span more than one coding turn.
+- Small one-file fixes can stay lightweight, but the decision and rationale should still be discoverable from code and commit history.
+
+## Minimum Plan Shape
+
+- Goal
+- Background
+- Milestones
+- Current progress
+- Key decisions
+- Remaining issues
+- Links
+
+## Freshness
+
+- Update plan status as milestones move.
+- Move completed plans into `docs/exec-plans/completed/` instead of deleting them.

docs/design-docs/core-beliefs.md

@@ -0,0 +1,31 @@
+# Core Beliefs
+
+## Product Beliefs
+
+- The repository should converge on a single operator surface for automation instead of accumulating fragile shell entrypoints.
+- The long-term product is a Git impact analyzer, but the immediate engineering priority is reliable harnessing and agent operability.
+- Worktree-local behavior is preferable to shared mutable state because it keeps agent runs isolated and reproducible.
+- Structured command output matters more than pretty terminal output for automation paths.
+
+## Agent-First Operating Principles
+
+1. **Repository knowledge is the system of record.**
+   If a decision matters, it must be encoded in code, markdown, schema, or a checked-in plan.
+
+2. **What the agent cannot see does not exist.**
+   Product intent, architecture constraints, and operating conventions need to be discoverable in-repo.
+
+3. **Enforce boundaries centrally, allow autonomy locally.**
+   Rules belong in command contracts, tests, and CI rather than informal expectation.
+
+4. **Corrections are cheap, waiting is expensive.**
+   Prefer short feedback loops, fast validation commands, and follow-up fixes over long-lived ambiguity.
+
+5. **Prefer boring technology.**
+   The current Go and Rust choices are intentional because both are stable, well-known, and easy to automate.
+
+6. **Encode taste once, enforce continuously.**
+   Naming, output contracts, and lifecycle behavior should be captured in code and docs so every run sees the same standard.
+
+7. **Treat documentation as executable infrastructure.**
+   Docs are part of the harness. If runtime behavior changes, the corresponding canonical doc must change too.

docs/design-docs/index.md

@@ -0,0 +1,13 @@
+# Design Docs Index
+
+| Document | Canonical Topic | Owner | Intended Audience | Update When |
+| --- | --- | --- | --- | --- |
+| [`core-beliefs.md`](./core-beliefs.md) | Product beliefs and agent-first operating principles | Repo maintainers | Humans and agents | Product direction or operating model changes |
+| [`local-operations.md`](./local-operations.md) | Local command surface, env vars, troubleshooting | Repo maintainers | Humans and agents | Commands, env vars, or validation flows change |
+| [`worktree-isolation.md`](./worktree-isolation.md) | Worktree ID derivation, runtime roots, and port allocation | Repo maintainers | Humans and agents | Boot/runtime behavior changes |
+| [`observability-shim.md`](./observability-shim.md) | Current telemetry data flow and local query contract | Repo maintainers | Humans and agents | Observability data paths or query contract changes |
+
+## Status
+
+- These documents are the canonical operational layer for the repository.
+- `AGENTS.md` should only point here, not duplicate this content.

docs/design-docs/local-operations.md

@@ -0,0 +1,69 @@
+# Local Operations
+
+## Primary Commands
+
+### Go Ralph Loop
+
+- `./ralph-loop schema --output json`
+  - Show the live command contract.
+- `./ralph-loop init --dry-run --output json`
+  - Preview worktree initialization details.
+- `./ralph-loop "<prompt>" --output ndjson --preserve-worktree`
+  - Run the loop and keep the generated worktree for inspection.
+
+### Harness CLI
+
+- `cargo build --release --manifest-path harness/Cargo.toml`
+  - Build `harnesscli`.
+- `harness/target/release/harnesscli smoke`
+  - Fast compile sanity check for the Go code.
+- `harness/target/release/harnesscli lint`
+  - Formatting plus static analysis checks.
+- `harness/target/release/harnesscli typecheck`
+  - Full repository build validation.
+- `harness/target/release/harnesscli test`
+  - Go tests plus Rust harness tests.
+- `harness/target/release/harnesscli audit . --output json`
+  - Verify required harness files and directories exist.
+- `harness/target/release/harnesscli init`
+  - Create the current worktree runtime root and metadata.
+- `harness/target/release/harnesscli boot start`
+  - Start the deterministic local demo app for this worktree.
+
+### Make Targets
+
+- `make smoke`
+- `make lint`
+- `make typecheck`
+- `make check`
+- `make test`
+- `make ci`
+
+## Environment Variables
+
+### Ralph Loop
+
+- `RALPH_LOOP_CODEX_COMMAND`
+  - Overrides the command used to start Codex app-server.
+
+### Harness
+
+- `HARNESS_SMOKE_CMD`
+- `HARNESS_LINT_CMD`
+- `HARNESS_TYPECHECK_CMD`
+- `HARNESS_TEST_CMD`
+  - Override the default command run by the matching `harnesscli` subcommand.
+
+- `DISCODE_WORKTREE_ID`
+  - Override the derived worktree ID.
+
+- `APP_PORT_BASE`
+- `DISCODE_APP_PORT`
+- `PORT`
+  - Override demo app port selection.
+
+## Troubleshooting
+
+- If `./ralph-loop` cannot talk to Codex, confirm `codex app-server` works in your shell or set `RALPH_LOOP_CODEX_COMMAND`.
+- If `harnesscli boot start` reports a busy port, rerun with `DISCODE_APP_PORT` or stop the conflicting process.
+- If automation output looks human-oriented in scripts, pass `--output json` explicitly even though non-TTY defaults should already select JSON.

docs/design-docs/observability-shim.md

@@ -0,0 +1,32 @@
+# Observability Shim
+
+## Current State
+
+This repository is at the start of the harness-spec observability work. The current implementation is a local observability shim, not the full Vector + Victoria stack described by later phases of `specs/harness-spec`.
+
+## Data Flow
+
+- `harnesscli boot start` writes process logs under `.worktree/<worktree_id>/logs/`.
+- `harnesscli observability start` creates a per-worktree observability metadata file and declares the local query endpoints that will be used by future phases.
+- `harnesscli observability query` currently supports local log-file queries and returns structured output.
+
+## Query Contract
+
+- Default output is JSON in non-TTY mode.
+- `--output ndjson` is available for line-oriented query results.
+- Query responses include:
+  - `worktree_id`
+  - `runtime_root`
+  - `kind`
+  - `items`
+
+## Upgrade Path
+
+Later harness phases should replace this shim with a real per-worktree telemetry stack:
+
+- Vector for collection and fan-out
+- VictoriaLogs for logs
+- VictoriaMetrics for metrics
+- VictoriaTraces for traces
+
+When that happens, this document must be updated before merge.