feat: scaffold redsen-lean-harness v0.1.0

Recovered from crashed session (Node OOM). Repo contains full P0-P6 scaffold: plugin.json/marketplace.json, AGENTS.md, ADRs 0001-0006, lh CLI (init/index/graph/lane/run/memory/host/report/doctor), 10 .github/agents, 12 CLI skills, instructions, context7 mcp.json, and unit/e2e test suite. Fixed: run.mjs read --in-tokens/--out-tokens but tests and CLI docs use --input-tokens/--output-tokens, so telemetry totals were always 0. Now accepts both forms. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-09-09 22:44:15 +02:00
commit 383129f571
79 changed files with 7855 additions and 0 deletions
@@ -0,0 +1,89 @@
+# redsen-lean-harness
+
+An imperative, token-lean, self-documenting agent harness. It runs unchanged in
+**GitHub Copilot CLI** and **VS Code Copilot**.
+
+## Division of labour
+
+| Layer | Owns | Where |
+| --- | --- | --- |
+| Markdown | Behaviour — agents, skills, instructions | `.github/` |
+| Node CLI (`lh`) | Determinism — index, gates, worktree lanes, telemetry, memory | `src/` |
+| Host | Execution — subagents, fleet, tools | Copilot CLI / VS Code |
+
+We never reimplement an agent runtime. If the host can do it, the host does it.
+
+## Pipeline
+
+```
+design  → gated Q&A, nothing inferred        → .agents/specs/<slug>/decisions.md
+plan    → spec + acceptance criteria + DAG   → spec.md, plan.dag.json
+build   → worktree lanes, Ralph loop         → builder ⇄ verifier
+integrate → sequential merge + full verify   → integrator
+document  → runs throughout                  → scribe
+```
+
+The **conductor re-plans at every checkpoint**: lanes may be spawned, killed, or
+re-scoped based on results. Failures are isolated, retried within bounds, then
+planned around.
+
+## Agents
+
+| Agent | Tier | Invokable | Responsibility |
+| --- | --- | --- | --- |
+| `conductor` | strong | yes | Entry point. Owns the pipeline and the dynamic DAG. |
+| `interrogator` | strong | yes | Design-phase Q&A with recommended answers. |
+| `scout` | cheap | no | Read-only recon, fanned out N-wide. |
+| `architect` | strong | yes | Spec, acceptance criteria, architecture doc, ADRs. |
+| `splitter` | mid | no | Decomposes spec into lanes with file-scope globs. |
+| `builder` | mid | no | Implements one lane inside its worktree. |
+| `verifier` | cheap | no | Runs verify commands + structural gate. |
+| `reviewer` | strong | yes | Acceptance-criteria and scope gate. |
+| `integrator` | strong | no | Sequential merge, conflict resolution, full verify. |
+| `scribe` | cheap | no | Journal, ADRs, living spec, conventions. |
+
+## Skills
+
+`init` `design` `plan` `build` `verify` `integrate` `onboard` `memory` `index`
+`telemetry` `fast-track` `doctor`
+
+## `lh` commands
+
+| Command | Purpose |
+| --- | --- |
+| `lh init` | First-run wizard, writes `.agents/harness.config.json`. |
+| `lh index` | Token-budgeted tree-sitter repo map. |
+| `lh graph` | Structural gate: duplicates, orphans, unresolved calls. Exit 1 on violation. |
+| `lh lane` | git worktree lane lifecycle + file-scope leases. |
+| `lh run` | NDJSON telemetry + live board. |
+| `lh memory` | Memory shard CRUD, compaction, secret scanning. |
+| `lh host` | Detect host capabilities, print orchestration strategy. |
+| `lh report` | Markdown telemetry report. |
+| `lh doctor` | Environment checks. |
+
+## Per-repo footprint
+
+```
+.agents/
+  harness.config.json
+  architecture.md          # living, ADR log inside      [committed]
+  conventions.md           # living                      [committed]
+  memory/INDEX.md          # the ONLY always-loaded file [committed]
+  memory/{seed,failures,corrections,insights,conventions,quirks}.md
+  specs/<slug>/{questionnaire,decisions,spec}.md, plan.dag.json
+  runs/<id>/{board.md,events.ndjson,journal.md}
+  .cache/                  # repomap, symbols, wasm      [gitignored]
+```
+
+## Token-leanness
+
+1. Only `memory/INDEX.md` is always loaded; shards pull on demand.
+2. `lh index --budget` caps repo-map size.
+3. Cheap-tier subagents absorb exploration cost; only summaries return.
+4. `lh graph` and `lh report` emit briefs, never dumps.
+5. Skill bodies stay short; procedures live in `templates/`.
+
+## Context7
+
+Mandatory for external library work. Key is read from `CONTEXT7_API_KEY`
+**environment variable only** — the harness never writes secrets to disk.