loop-engineering-harness 1.0.0

package/README.md

@@ -0,0 +1,266 @@
+# Loop Engineering — an agent harness for brownfield Claude Code
+
+Turn Claude Code into a disciplined, observable, **continuously-looping** multi-agent
+development pipeline you can drop into an existing codebase without disrupting it.
+
+> **The thesis:** policy lives in exit codes and artifacts on disk, not in prompts.
+> Agents exercise judgment; hooks and scripts enforce the rules; files carry the
+> state. Anything an agent could forget or rationalize past is enforced deterministically.
+
+Built entirely on Claude Code's native primitives — subagents, skills, hooks, slash
+commands — plus **graphify** (deterministic code knowledge graph) and **Langfuse**
+(trace observability). Design record: [Architecture.md](Architecture.md),
+[Implementation.md](Implementation.md), [Usecase.md](Usecase.md),
+[DevelopmentUpdates.md](DevelopmentUpdates.md), [HookDevelopment.md](HookDevelopment.md).
+
+---
+
+## Install
+
+```bash
+npx loop-engineering-harness detect .      # dry run — show exactly what will change
+npx loop-engineering-harness init .        # install (prints a plan, asks to confirm)
+npx loop-engineering-harness uninstall .   # remove everything; keeps your specs/
+```
+
+> **Note:** You can also install directly from GitHub without publishing:
+> ```bash
+> npx github:AakashRajendran0926/Loop-Engineering init .
+> ```
+
+Brownfield-safe by construction:
+
+- **`CLAUDE.md`** gains a delimited `<!-- harness:begin -->…<!-- harness:end -->`
+  block below your content — never a rewrite. Upgrades replace only the block.
+- **`.claude/settings.json`** is deep-merged: your hooks are preserved and never
+  reordered; harness hooks are appended with a `"_harness": true` marker. Invalid
+  JSON aborts the install rather than guessing.
+- **File collisions** (e.g. you already have `agents/reviewer.md`) are written as
+  `reviewer.harness.md` with a warning — your file is never clobbered.
+- **A manifest** records exactly what was written, so `uninstall` restores a
+  **byte-identical** repo (minus `specs/`, which is your work product).
+
+---
+
+## The gate stack — the whole point
+
+Every gate is a hook that reads disk and exits non-zero to block. The harness
+summons a human at bad **inputs**, bad **flow**, goal **drift**, failed **outputs**,
+and unversioned **change** — each decided mechanically, never by an agent grading
+itself.
+
+| Gate | Fires on | Blocks unless… |
+|---|---|---|
+| `retrieval-nudge.py` | Grep/Glob | broad search goes graph-first (`graphify query`); auto-inits graphify if absent |
+| `requirements-gate.py` | Task | intent is unambiguous, requirements structured (AC1, AC2…), flow in order, plan covers exactly the acceptance criteria |
+| `dispatch-gate.py` | Task | G0–G6: approval-hash matches, graph fresh, breaker healthy, upstream done, under retry cap, prompt within context budget |
+| `divergence-monitor.py` | Edit/Write | writes stay inside the task's declared footprint (else trips the breaker) |
+| `artifact-size.py` | Edit/Write | context-pack / review stay within their compression budget |
+| `commit-gate.py` | Bash | a passing **integration review** exists for the current diff |
+| `version-gate.py` | Bash | major deps acknowledged, code version + changelog recorded, dev history captured |
+
+Supporting hooks: `state-updater.py` (single writer of `state.json` + derived
+breaker `health`), `precompact-guard.py`/`session-rehydrate.py` (compaction
+indifference + resume), `trace-emitter.py` (Langfuse + local traces),
+`version-tracker.py` (dependency deltas).
+
+---
+
+## Using it — `/feature`
+
+```
+/feature add order cancellation with refund handling
+```
+
+1. **Discovery interview** (main thread, human) → `discovery.md` with `AC1, AC2…` acceptance criteria
+2. **context-researcher** (isolated window, graph-first) → `context-pack.md` (~2k tokens, sectioned per work area)
+3. **planner** → `contracts/` then `plan.md` (footprints, `satisfies:` coverage tags, `VERSION-IMPACT`, token estimates) → runs `extract-deps.py` → `task-graph.json`
+4. **Plan approval** (human, or `--auto-approve`) → `approvals.json` signs the decomposition; automation is frozen until it matches `plan.md`'s hash
+5. **Specialists** dispatched per the computed schedule — parallel only where footprints are *literally disjoint*, sequential along edges; task-scoped prompts (Rule 1), stateless retries (Rule 3)
+6. **reviewer** per task, then one **integration review** over the combined diff
+7. **Version** the feature (bump + changelog + snapshot)
+8. **Commit** — the commit gate *and* version gate open; the PR is backed by the full artifact chain in `specs/`, not a bare diff
+
+`/feature` is the only opt-in — ordinary Claude Code usage in the repo is untouched.
+
+---
+
+## Retrieval is graph-first: graphify → skills → memory
+
+`retrieval-nudge.py` redirects broad `Grep`/`Glob` toward a dependency-aware
+`graphify query`. Narrow, file-scoped searches pass through. If no graph exists it
+routes to `/graphify .` (which self-installs and builds one). It blocks a session
+at most **once**, so it steers the first broad search but can never wedge a subagent.
+
+---
+
+## The human gate — summoned by evidence, before work goes wrong
+
+Four conditions freeze automation until a person resolves them
+(`requirements-gate.py`, and `approve-plan.py` refuses to sign a failing plan):
+
+| Condition | Detected as |
+|---|---|
+| Ambiguous / unorganized intention | `discovery.md` missing Intent & Scope, or unresolved markers (TBD / ??? / "clarify") |
+| Vague / unstructured requirements | required sections absent, or no structured acceptance criteria (AC1, AC2…) |
+| Wrong flow | implementation dispatched before its phase artifacts exist (discovery → context-pack → plan → task-graph) |
+| Diverted from user requirements | an acceptance criterion covered by no task (under-delivery), or a task citing an AC absent from discovery (scope creep) |
+
+A block is not a retry — the message says *re-enter interview mode*. `--force` on
+`approve-plan.py` overrides but is recorded in `approvals.json` as a logged decision.
+
+---
+
+## Version Controller — dependency, code, and development versioning
+
+A feature does not commit until it is versioned (`version-tracker.py` +
+`version-gate.py` + [`version.py`](template/.claude/scripts/version.py)):
+
+- **Dependency** — the pre-feature dependency set is baselined at approval; every
+  manifest edit (`package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`,
+  `Cargo.toml`) is diffed and classified major/minor/patch into
+  `dependencies.json`. A **major** bump must be acknowledged after review.
+- **Code** — `version.py bump` derives a semver bump from the plan's
+  `VERSION-IMPACT`, updates `VERSION`, and writes a `CHANGELOG.md` entry.
+- **Development** — `version.py snapshot` hashes the spec artifacts into
+  `history.json` at each milestone (`approved` → `integrated` → …) so a feature's
+  evolution is auditable, not overwritten.
+
+```bash
+python .claude/scripts/version.py status <feature>
+```
+
+---
+
+## Autonomous workflow — the outer loop
+
+The driver processes a **feature queue**, running each in a fresh headless
+`claude -p` session to one of three terminal states read back from `state.json`.
+Escalations **park** (with a question for a human) instead of stalling the queue;
+a parked feature resumes from artifacts in a brand-new session — recover-from-
+compaction and resume-from-parking are the same mechanism.
+
+```bash
+agent-harness queue add "add order cancellation with refunds"
+agent-harness queue add "nightly CSV export" --auto-approve   # headless self-approve
+agent-harness loop                    # drive the queue to terminal states
+agent-harness queue list              # done / parked (+ the questions)
+#   ...human appends the answer to specs/<f>/discovery.md...
+agent-harness requeue <feature-id>    # resume in a fresh session
+agent-harness metrics                 # per-feature burndown + tokens-per-passing-task
+```
+
+The human gate (interview + plan approval) is deliberate — ambiguity is routed to
+people, not retried into confident guesses. `--auto-approve` is a **logged**
+opt-out for trusted/CI features; every downstream gate still enforces. Token
+burndown is fed from each session's real usage into the circuit breaker (halts at
+100% of the approved budget). Dashboards: [docs/langfuse-dashboards.md](docs/langfuse-dashboards.md).
+
+---
+
+## The artifact chain
+
+The pipeline's real data structure is `specs/<feature>/` — agents are transient,
+artifacts are the pipeline:
+
+```
+specs/<feature>/
+├── discovery.md            # interview output; AC1, AC2… ; appended on escalation
+├── context-pack.md         # ~2k-token brief, sectioned per work area
+├── plan.md                 # tasks + footprints + satisfies: + VERSION-IMPACT + est_tokens
+├── contracts/              # interface agreements, written before any specialist runs
+├── task-graph.json         # computed schedule (extract-deps.py)
+├── approvals.json          # the signed autonomy boundary (plan hash + budget)
+├── state.json              # per-task status, attempts, phase, breaker health (hook-written)
+├── review.<task>.<n>.json  # reviewer verdicts, one per attempt
+├── dependencies.json       # dependency deltas vs baseline (+ .baseline.json)
+├── version.json            # code semver bump for this feature
+├── history.json            # development-version snapshots per milestone
+├── divergence.json         # footprint violations + token burndown
+└── pipeline-context.md     # PreCompact snapshot (load-bearing minimum)
+specs/_queue.json · _answers.json · _active.json   # the loop driver's ledgers
+```
+
+---
+
+## What gets installed
+
+```
+.claude/
+├── settings.json          # hook registrations (merged)
+├── agents/                # context-researcher, planner, specialist-{db,backend,frontend}, reviewer
+├── skills/                # discovery-interview, contract-writing, review-taxonomy
+├── commands/feature.md    # /feature — pipeline entry point
+├── hooks/                 # 12 hooks + harness_lib, loop_lib, req_lib, version_lib
+└── scripts/               # extract-deps.py, approve-plan.py, changeset.py, version.py
+CLAUDE.md                  # merged harness block
+harness.config.json        # every knob (below)
+```
+
+---
+
+## Configuration — `harness.config.json`
+
+```jsonc
+{
+  "graphify":   { "binary": "graphify", "index_path": "graphify-out/" },
+  "retries":    { "mechanical": 2, "contract": 1, "ambiguity": 0, "security": 0 },
+  "dependency_depth": 1,
+  "retrieval_nudge": { "mode": "block", "auto_init": true },
+  "budgets":    { "context_pack": 2000, "review_findings": 500, "dispatch_prompt_max": 8000 },
+  "circuit_breaker": { "footprint_violations": { "warn": 1, "halt": 2 },
+                       "max_escalations_per_feature": 2, "burndown": { "warn_pct": 80, "halt_pct": 100 } },
+  "requirements": { "enabled": true, "min_acceptance_criteria": 1, "require_coverage": true },
+  "versioning":  { "enabled": true, "require_major_dep_ack": true, "require_code_bump": true, "require_dev_history": true },
+  "loop":       { "queue": "specs/_queue.json", "answer_queue": "specs/_answers.json", "auto_approve": false },
+  "observability": { "provider": "langfuse", "enabled": true, "host": "env:LANGFUSE_HOST",
+                     "public_key": "env:LANGFUSE_PUBLIC_KEY", "secret_key": "env:LANGFUSE_SECRET_KEY" },
+  "gates": { "commit_requires_integration_review": true, "commit_requires_version": true }
+}
+```
+
+Secrets are `env:` references only — never literal keys on disk. Any gate is a
+config toggle; bypasses are logged decisions, not silent workarounds.
+
+---
+
+## Observability & the flywheel
+
+`trace-emitter.py` streams one Langfuse trace per session (trace id = `session_id`),
+with subagent spans, tool child-spans, and review verdicts as scores. Every failed
+review and escalation lands in a regression dataset labeled with `failure_class`.
+If Langfuse is unreachable it falls back to `.claude/traces/` — observability never
+becomes an availability dependency. Offline view: `agent-harness metrics`.
+
+## Standalone tool
+
+Try the deterministic dependency extractor with zero agents:
+
+```bash
+python .claude/scripts/extract-deps.py --files src/auth/    # "what does this change touch?"
+```
+
+## Testing
+
+```bash
+npm test        # node tests/run.js — 84 checks across extract-deps determinism,
+                # every hook (stdin fixtures), the loop driver (mock runner),
+                # metrics, the Version Controller, and installer byte-identity
+```
+
+## Requirements
+
+- **Node ≥ 16** (installer + loop driver; zero runtime dependencies)
+- **Python 3.8+** on PATH (`python`, `python3`, or `py`) for hooks/scripts
+- **graphify** for graph-first retrieval — `/graphify` self-installs it on first run
+- **Claude Code** (for the `claude -p` headless loop) and, optionally, **Langfuse**
+
+## Reversibility
+
+`uninstall` removes the `_harness` hooks, the harness files, and the delimited
+`CLAUDE.md` block, and leaves `specs/`. A pre-populated `.claude/` returns
+byte-identical. Reversibility is an adoption feature, not an afterthought.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+'use strict';
+// Loop Engineering harness installer.
+//   agent-harness init [target] [--yes] [--python <cmd>]
+//   agent-harness detect [target]
+//   agent-harness uninstall [target] [--yes]
+
+const path = require('path');
+const readline = require('readline');
+const { detect, formatReport } = require('../src/detect');
+const { install } = require('../src/install');
+const { uninstall } = require('../src/uninstall');
+const loop = require('../src/loop');
+const { computeMetrics, formatMetrics } = require('../src/metrics');
+
+function parseArgs(argv) {
+  const out = { _: [], yes: false, python: null, dryRun: false, once: false, autoApprove: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--yes' || a === '-y') out.yes = true;
+    else if (a === '--dry-run') out.dryRun = true;
+    else if (a === '--once') out.once = true;
+    else if (a === '--auto-approve') out.autoApprove = true;
+    else if (a === '--python') out.python = argv[++i];
+    else if (a.startsWith('--python=')) out.python = a.slice(9);
+    else out._.push(a);
+  }
+  return out;
+}
+
+function confirm(question) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) return resolve(false);
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (ans) => { rl.close(); resolve(/^y(es)?$/i.test(ans.trim())); });
+  });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cmd = args._[0] || 'help';
+  const target = path.resolve(args._[1] || '.');
+
+  if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    console.log([
+      'Loop Engineering — agent harness for brownfield Claude Code repos',
+      '',
+      'Usage:',
+      '  agent-harness init [target]        Install into a repo (prints a plan first)',
+      '  agent-harness detect [target]      Show the install plan, write nothing',
+      '  agent-harness uninstall [target]   Remove the harness (keeps specs/)',
+      '',
+      '  agent-harness queue add "<desc>"   Add a feature to the work queue',
+      '  agent-harness queue list           Show the queue and parked features',
+      '  agent-harness loop                 Run the autonomous driver over the queue',
+      '  agent-harness requeue <id>         Re-queue a parked feature after answering',
+      '  agent-harness metrics              Per-feature burndown + tokens-per-task',
+      '',
+      'Flags:  --yes | -y   skip confirmation      --python <cmd>   force interpreter',
+      '        --once       one feature then stop   --auto-approve  headless self-approval',
+      '        --dry-run    plan the loop, run nothing',
+    ].join('\n'));
+    return 0;
+  }
+
+  if (cmd === 'queue') {
+    const sub = args._[1];
+    const root = path.resolve(args._[2] || '.');
+    if (sub === 'add') {
+      const desc = args._[2];
+      if (!desc) { console.error('usage: agent-harness queue add "<description>"'); return 1; }
+      const id = loop.addToQueue(process.cwd(), desc, { autoApprove: args.autoApprove, now: new Date().toISOString() });
+      console.log(`queued '${id}'`);
+      return 0;
+    }
+    if (sub === 'list' || !sub) {
+      const q = loop.loadQueue(root);
+      const ans = require('fs').existsSync(loop.answersPath(root))
+        ? JSON.parse(require('fs').readFileSync(loop.answersPath(root), 'utf8')) : { parked: [] };
+      console.log('Queue:');
+      for (const f of q.features) console.log(`  [${f.status}] ${f.id} — ${f.description}`);
+      if (ans.parked && ans.parked.length) {
+        console.log('\nParked (need a human):');
+        for (const p of ans.parked) console.log(`  ${p.id} (${p.terminal}): ${p.question}`);
+      }
+      return 0;
+    }
+    console.error(`unknown: queue ${sub}`); return 1;
+  }
+
+  if (cmd === 'requeue') {
+    loop.requeue(process.cwd(), args._[1], new Date().toISOString());
+    console.log(`re-queued '${args._[1]}'`);
+    return 0;
+  }
+
+  if (cmd === 'loop') {
+    const root = path.resolve(args._[1] || '.');
+    if (args.dryRun) {
+      const q = loop.loadQueue(root);
+      const pending = q.features.filter((f) => f.status === 'pending');
+      console.log(`dry-run: ${pending.length} pending feature(s): ${pending.map((f) => f.id).join(', ') || '(none)'}`);
+      return 0;
+    }
+    const summary = await loop.processQueue(root, {
+      once: args.once, autoApprove: args.autoApprove, log: (m) => console.log(m),
+    });
+    console.log(`\nDone. committed: ${summary.committed.length}, ` +
+      `escalated: ${summary.escalated.length}, needs_approval: ${summary.needs_approval.length}, ` +
+      `incomplete: ${summary.incomplete.length}`);
+    if (summary.escalated.length || summary.needs_approval.length) {
+      console.log('Parked features await a human — see: agent-harness queue list');
+    }
+    return 0;
+  }
+
+  if (cmd === 'metrics') {
+    console.log(formatMetrics(computeMetrics(path.resolve(args._[1] || '.'))));
+    return 0;
+  }
+
+  if (cmd === 'detect') {
+    console.log(formatReport(detect(target, args.python)));
+    return 0;
+  }
+
+  if (cmd === 'init' || cmd === 'install') {
+    const report = detect(target, args.python);
+    console.log(formatReport(report));
+    console.log('');
+    if (!report.settings.valid) { console.error('Aborted: fix settings.json first.'); return 1; }
+    if (!args.yes) {
+      const ok = await confirm('Proceed with install? [y/N] ');
+      if (!ok) {
+        console.log('Aborted. (Re-run with --yes for non-interactive install.)');
+        return process.stdin.isTTY ? 0 : 1;
+      }
+    }
+    const { manifest } = install(target, { python: args.python, now: new Date().toISOString() });
+    console.log(`Installed. CLAUDE.md: ${manifest.claudeMd}; ` +
+      `${manifest.filesAdded.length} files added` +
+      (manifest.filesRenamed.length ? `, ${manifest.filesRenamed.length} collision(s) renamed to *.harness.*` : '') +
+      `. Next: /feature <description>`);
+    return 0;
+  }
+
+  if (cmd === 'uninstall') {
+    if (!args.yes) {
+      const ok = await confirm(`Uninstall the harness from ${target}? (specs/ is kept) [y/N] `);
+      if (!ok) { console.log('Aborted.'); return process.stdin.isTTY ? 0 : 1; }
+    }
+    const res = uninstall(target);
+    console.log(`Uninstalled. Removed ${res.removed.length} files; ` +
+      `settings: ${res.settings}; CLAUDE.md: ${res.claudeMd}` +
+      (res.usedManifest ? '' : ' (no manifest — heuristic uninstall)') + '. specs/ left in place.');
+    return 0;
+  }
+
+  console.error(`Unknown command: ${cmd}. Try: agent-harness help`);
+  return 1;
+}
+
+main().then((code) => process.exit(code || 0)).catch((err) => {
+  console.error('Error: ' + err.message);
+  process.exit(1);
+});

package/docs/langfuse-dashboards.md

@@ -0,0 +1,39 @@
+# Langfuse Dashboards (Phase L5)
+
+`trace-emitter.py` streams one trace per session (trace id = `session_id`), with
+subagent spans, tool child-spans, and review verdicts as scores. These three
+dashboards turn that stream into the flywheel's instrument panel. Build them in
+the Langfuse UI (Dashboards → New) over your project; the metric each needs is
+noted. The same numbers are available offline via `agent-harness metrics`.
+
+## 1. Per-feature burndown
+**Question:** is a feature burning toward or through its approved budget?
+- **Source:** score/observation `tokens_spent` accumulated per feature vs the
+  `budget` recorded in `approvals.json` (the driver writes cumulative tokens into
+  `divergence.json`; trace metadata carries `feature`).
+- **Chart:** line — cumulative tokens over session time, with a horizontal marker
+  at 80% (warn) and 100% (halt) of budget. A feature crossing 100% is exactly
+  what trips the circuit breaker's burndown signal.
+
+## 2. Tokens-per-passing-task, by specialist
+**Question:** which compression stage is leaking? (Rule 5's leak detector.)
+- **Source:** per subagent span, `output_tokens` ÷ passing tasks for that
+  specialist type (`specialist-backend`, `-frontend`, `-database`).
+- **Chart:** time series, one line per specialist type. A steady creep on one
+  line localizes the leak to that specialist's retrieval/context slice — the
+  trace then shows which span carries the extra tokens.
+
+## 3. Estimate-vs-actual, by task type
+**Question:** is the planner's cost estimate trustworthy?
+- **Source:** planner-emitted per-task token estimate (in the approval package)
+  vs actual tokens for that task's spans.
+- **Chart:** scatter — estimate (x) vs actual (y), colored by failure class. Points
+  far above the diagonal are underestimated task types; feed that back into the
+  planner's estimates and the config `budgets.per_task_default`.
+
+## Regression dataset (the flywheel closes here)
+Every `"status": "fail"` review and every escalation lands as a dataset item
+labeled with `failure_class`, attempts, and resolution. Before merging any change
+to a skill, agent prompt, or hook, replay the dataset and compare scores — the
+reviewer agent is the native evaluation producer, so "evaluate" never waits on
+human labeling.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "loop-engineering-harness",
+  "version": "1.0.0",
+  "description": "Loop Engineering — a reversible, observable multi-agent Claude Code harness for brownfield codebases. Policy lives in exit codes and artifacts on disk, not in prompts.",
+  "keywords": [
+    "claude-code",
+    "loop-engineering-harness",
+    "context-engineering",
+    "graphify",
+    "langfuse",
+    "brownfield"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "agent-harness": "bin/cli.js",
+    "loop-engineering": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "template/",
+    "docs/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node tests/run.js",
+    "install-here": "node bin/cli.js init .",
+    "uninstall-here": "node bin/cli.js uninstall ."
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}

package/src/detect.js

@@ -0,0 +1,79 @@
+'use strict';
+// Builds the pre-flight detection report: what exists, what will be added,
+// merged, or renamed. Pure inspection — writes nothing.
+
+const fs = require('fs');
+const path = require('path');
+const m = require('./merge');
+
+function templateDir() { return path.join(__dirname, '..', 'template'); }
+
+// The set of files the harness ships into the adopter's .claude/ tree.
+function planClaudeFiles(target) {
+  const src = path.join(templateDir(), '.claude');
+  return m.walk(src).map((abs) => {
+    const rel = path.relative(templateDir(), abs); // e.g. .claude/hooks/x.py
+    return { src: abs, rel, dest: path.join(target, rel) };
+  });
+}
+
+function classify(dest, src) {
+  if (!fs.existsSync(dest)) return { status: 'add' };
+  const a = fs.readFileSync(dest), b = fs.readFileSync(src);
+  if (a.equals(b)) return { status: 'identical' };
+  const ext = path.extname(dest);
+  return { status: 'collision', renamedTo: dest.slice(0, -ext.length || undefined) + '.harness' + ext };
+}
+
+function detect(target, python) {
+  const report = { target, python: python || m.detectPython(), files: [] };
+
+  for (const f of planClaudeFiles(target)) {
+    report.files.push(Object.assign({ rel: f.rel.replace(/\\/g, '/') }, classify(f.dest, f.src)));
+  }
+
+  const cfgDest = path.join(target, 'harness.config.json');
+  report.config = { exists: fs.existsSync(cfgDest), action: fs.existsSync(cfgDest) ? 'keep' : 'add' };
+
+  const claudeDest = path.join(target, 'CLAUDE.md');
+  const claudeRaw = m.read(claudeDest);
+  report.claudeMd = {
+    exists: claudeRaw !== null,
+    action: claudeRaw === null ? 'create'
+      : claudeRaw.includes(m.BEGIN) ? 'upgrade-block' : 'append-block',
+  };
+
+  const setDest = path.join(target, '.claude', 'settings.json');
+  const setRaw = m.read(setDest);
+  let valid = true;
+  if (setRaw !== null && setRaw.trim() !== '') { try { JSON.parse(setRaw); } catch (_) { valid = false; } }
+  report.settings = { exists: setRaw !== null, valid, action: 'merge-hooks' };
+
+  return report;
+}
+
+function formatReport(r) {
+  const L = [];
+  L.push('Loop Engineering — installation plan');
+  L.push('  target: ' + r.target);
+  L.push('  python: ' + r.python);
+  L.push('');
+  const adds = r.files.filter((f) => f.status === 'add');
+  const same = r.files.filter((f) => f.status === 'identical');
+  const cols = r.files.filter((f) => f.status === 'collision');
+  L.push(`  files to add:      ${adds.length}`);
+  if (same.length) L.push(`  already present:   ${same.length} (identical, skipped)`);
+  for (const c of cols) L.push(`  ! COLLISION:       ${c.rel}  ->  ${path.basename(c.renamedTo)} (yours kept)`);
+  L.push('');
+  L.push(`  harness.config.json: ${r.config.action}`);
+  L.push(`  CLAUDE.md:           ${r.claudeMd.action}`);
+  if (!r.settings.valid) {
+    L.push('  .claude/settings.json: INVALID JSON — install will abort. Fix it first.');
+  } else {
+    L.push(`  .claude/settings.json: ${r.settings.action} (existing hooks preserved, ` +
+      `harness hooks appended with _harness markers)`);
+  }
+  return L.join('\n');
+}
+
+module.exports = { detect, formatReport, planClaudeFiles, templateDir };

package/src/install.js

@@ -0,0 +1,58 @@
+'use strict';
+// Applies the plan from detect.js. Writes a manifest so uninstall is exact.
+
+const fs = require('fs');
+const path = require('path');
+const m = require('./merge');
+const { detect, planClaudeFiles, templateDir } = require('./detect');
+
+const MANIFEST_REL = path.join('.claude', '.harness', 'manifest.json');
+
+function install(target, opts) {
+  opts = opts || {};
+  target = path.resolve(target);
+  const python = opts.python || m.detectPython();
+  const report = detect(target, python);
+
+  if (!report.settings.valid) {
+    throw new Error('.claude/settings.json is not valid JSON — aborting (no files written).');
+  }
+
+  const manifest = {
+    version: '1.0', python, installedAt: opts.now || null,
+    filesAdded: [], filesRenamed: [], configWritten: false,
+    claudeMd: null, settingsEvents: [],
+  };
+
+  // 1) .claude tree — collision-safe copy
+  for (const f of planClaudeFiles(target)) {
+    const res = m.copyFileSafe(f.src, f.dest);
+    const rel = path.relative(target, res.dest).replace(/\\/g, '/');
+    if (res.status === 'added') manifest.filesAdded.push(rel);
+    else if (res.status === 'renamed') {
+      manifest.filesRenamed.push(path.relative(target, res.renamedTo).replace(/\\/g, '/'));
+    }
+  }
+
+  // 2) harness.config.json — add only if absent (never clobber adopter's tuning)
+  const cfgDest = path.join(target, 'harness.config.json');
+  if (!fs.existsSync(cfgDest)) {
+    fs.copyFileSync(path.join(templateDir(), 'harness.config.json'), cfgDest);
+    manifest.configWritten = true;
+    manifest.filesAdded.push('harness.config.json');
+  }
+
+  // 3) CLAUDE.md — delimited block
+  const block = m.read(path.join(templateDir(), 'CLAUDE.harness.md'));
+  manifest.claudeMd = m.mergeClaudeMd(path.join(target, 'CLAUDE.md'), block).action;
+
+  // 4) settings.json — deep-merge hooks
+  const payload = JSON.parse(m.read(path.join(templateDir(), 'settings.harness.json')));
+  const res = m.mergeSettings(path.join(target, '.claude', 'settings.json'), payload.hooks, python);
+  manifest.settingsEvents = res.appended;
+
+  m.writeJSON(path.join(target, MANIFEST_REL), manifest);
+  return { report, manifest };
+}
+
+module.exports = { install, MANIFEST_REL };