cli.js

#!/usr/bin/env node
/**
 * harness-kit — A CLI for harness engineering principles.
 *
 * Usage:
 *   harness-kit              List all 12 theses with summaries
 *   harness-kit thesis N     Read thesis N in detail
 *   harness-kit scaffold     Generate AGENTS.md + ARCHITECTURE.md scaffolding
 *   harness-kit review       Run a repository review (broad diagnostic)
 *   harness-kit improve      Guided playbook for improving one harnessed job
 *   harness-kit crossref     Read the ICM ↔ Harness Engineering cross-reference
 *   harness-kit playbook     List available playbooks
 */

import { readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { createInterface } from "node:readline";

const __dirname = dirname(fileURLToPath(import.meta.url));
const THESES_DIR = join(__dirname, "theses");
const PLAYBOOKS_DIR = join(__dirname, "playbooks");
const CROSSREF_DIR = join(__dirname, "crossref");
const SCAFFOLD_DIR = join(THESES_DIR, "_scaffold");

const THESIS_TITLES = [
  null,
  "Hold the worker constant",
  "Deploy into the private process-data iceberg",
  "Give one agent the whole job",
  "Route context just in time",
  "Make capabilities legible and operable",
  "Make the repository teach the agent",
  "Maximize autonomy inside explicit authority",
  "Prove the outcome in the real environment",
  "Turn feedback into infrastructure",
  "Preserve coherence and own lifetime risk",
  "Run known work as a continuous loop",
  "Optimize for measured effectiveness",
];

const THESIS_DESCRIPTIONS = [
  null,
  "Treat the chosen model and coding agent as a black box during one adoption epoch. Requalify environment when the worker changes.",
  "Organizations cannot presume private process data will be in general model weights. Keep current records with authoritative owners, compose them into retrievable context and bounded capability.",
  "One primary trajectory owns decomposition, execution, integration, proof, and safe lifecycle closure. Humans provide direction and authority at consequential boundaries.",
  "Keep a large navigable knowledge store and a small active working set. Root guidance routes; runbooks preserve workflows; skills teach approaches; checks surface constraints just in time.",
  "A capability becomes usable through the complete loop of discovery, selection, invocation, interpretation, repair, and real-system verification.",
  "Every file an agent reads becomes prompt material. The repository teaches local nonfunctional requirements through canonical owners, repeated structures, migrations, examples, types, and executable constraints.",
  "Keep capability and authority as separate contracts. Let the worker act broadly in reversible environments; make consequential grants scoped, revocable, auditable, and recoverable.",
  "Match evidence to the user or operational claim. A green check proves only its assertion; browser journeys, corpora, traces, canaries, and deployed health close different loops.",
  "Trajectory evidence, review, and incidents can expose missing harness capabilities. Move stable lessons into their earliest durable owner before they compound.",
  "Abundant implementation makes future coherence scarce. A feedback-controlled environment carries lived judgment into later work while preserving behavioral contracts and migration integrity.",
  "Settled outcomes with signal, proof, and authority can enter repository-owned loops. Durable state, feedback, and retirement conditions keep runs aligned with the current world.",
  "Tokens, lines, agents, and checks are inputs. Optimize useful outcomes per unit of scarce human attention, with acceptable latency, risk, and maintenance.",
];

function listTheses() {
  console.log("\n  📚 Harness Engineering — 12 Theses\n");
  for (let i = 1; i <= 12; i++) {
    const preview = THESIS_DESCRIPTIONS[i].length > 72
      ? THESIS_DESCRIPTIONS[i].slice(0, 69) + "..."
      : THESIS_DESCRIPTIONS[i];
    console.log(`  ${String(i).padStart(2)}. ${THESIS_TITLES[i]}`);
    console.log(`     ${preview}\n`);
  }
  console.log("  Commands:");
  console.log("    harness-kit thesis N     — Read thesis N in full");
  console.log("    harness-kit scaffold     — Generate AGENTS.md + ARCHITECTURE.md");
  console.log("    harness-kit review       — Repository review (broad diagnostic)");
  console.log("    harness-kit improve      — Guided job-improvement playbook");
  console.log("    harness-kit crossref     — ICM ↔ Harness Engineering cross-reference");
  console.log("    harness-kit playbook     — List operational playbooks\n");
}

function showThesis(n) {
  const num = parseInt(n);
  if (num < 1 || num > 12) {
    console.error(`Unknown thesis: ${n}. Choose 1–12.`);
    process.exit(1);
  }
  const slug = THESIS_TITLES[num].toLowerCase().replace(/[,\s]+/g, "-").replace(/-+/g, "-");
  const file = join(THESES_DIR, `${String(num).padStart(2, "0")}-${slug}.md`);
  if (!existsSync(file)) {
    console.error(`Thesis file not found: ${file}`);
    process.exit(1);
  }
  const content = readFileSync(file, "utf-8");
  console.log(content);
}

function scaffold(options) {
  const name = options.name || "my-project";
  const targetDir = options.dir || ".";

  if (!existsSync(targetDir)) {
    mkdirSync(targetDir, { recursive: true });
  }

  const agentsContent = `# AGENTS.md — Agent Guide for ${name}

This guide is for agents working on ${name}. Use it as context for understanding
the project's intent, architecture, and operating loop.

## What ${name} is

*A one-paragraph description of this project.*

## Operating loop

1. Read the target's available instructions and architecture first.
2. Inspect the actual domain model, manifests, tools, tests, and permissions.
3. Name the governing decision that local evidence leaves unresolved.
4. Let target-local truth govern the implementation.
5. Verify the result through the project's native checks and observable journeys.

## Task classes

*(List the common types of work agents do on this project, with links to relevant
docs, commands, and proof for each.)*

## Key resources

- Architecture: ARCHITECTURE.md
- CI: *link to CI config*
- Deployment: *link to deployment docs*
`;

  const archContent = `# Architecture — ${name}

## Ownership

| Path | Owns |
|------|------|
| \`ARCHITECTURE.md\` | Document ownership and routing invariants |
| \`AGENTS.md\` | Application routing for consuming agents |
| \`README.md\` | Public definition and entry point |

*(List additional owned paths as the project grows.)*

## Invariants

1. *(A short list of principles that should never be violated.)*
`;

  const agentsPath = join(targetDir, "AGENTS.md");
  const archPath = join(targetDir, "ARCHITECTURE.md");

  if (existsSync(agentsPath)) {
    console.log(`  ⚠️  ${agentsPath} already exists — skipping`);
  } else {
    writeFileSync(agentsPath, agentsContent);
    console.log(`  ✅ Created ${agentsPath}`);
  }

  if (existsSync(archPath)) {
    console.log(`  ⚠️  ${archPath} already exists — skipping`);
  } else {
    writeFileSync(archPath, archContent);
    console.log(`  ✅ Created ${archPath}`);
  }
}

function showReview() {
  const file = join(PLAYBOOKS_DIR, "repository-review.md");
  if (!existsSync(file)) {
    console.log("Repository Review Playbook not bundled yet.");
    console.log("Source: https://github.com/lopopolo/harness-engineering/blob/trunk/playbooks/repository-review.md");
    process.exit(1);
  }
  const content = readFileSync(file, "utf-8");
  console.log(content);
}

function showImprove() {
  const file = join(PLAYBOOKS_DIR, "improve-harness.md");
  if (!existsSync(file)) {
    console.log("Improve One Harnessed Job playbook not bundled yet.");
    console.log("Source: https://github.com/lopopolo/harness-engineering/blob/trunk/playbooks/improve-harness.md");
    process.exit(1);
  }
  const content = readFileSync(file, "utf-8");
  console.log(content);
}

function showCrossref() {
  const file = join(CROSSREF_DIR, "README.md");
  if (!existsSync(file)) {
    console.log("Cross-reference not bundled yet.");
    process.exit(1);
  }
  const content = readFileSync(file, "utf-8");
  console.log(content);
}

function listPlaybooks() {
  console.log("\n  📋 Harness Engineering — Operational Playbooks\n");
  console.log("  review     — Repository Review: assess whether a repo's harness");
  console.log("               lets an agent complete real jobs");
  console.log("  improve    — Improve One Harnessed Job: baseline → gap → fix → verify\n");
  console.log("  Commands:");
  console.log("    harness-kit review       — Run a repository review");
  console.log("    harness-kit improve      — Run the job improvement playbook");
  console.log("    harness-kit crossref     — ICM mapping\n");
}

function runImproveGuide() {
  console.log("\n  🔧 Improve One Harnessed Job — Guided Playbook\n");
  console.log("  This interactive guide walks through the 6-step loop:\n");
  console.log("  Step 1: Establish scope and authority");
  console.log("  Step 2: Observe the baseline");
  console.log("  Step 3: Locate the earliest failed handoff");
  console.log("  Step 4: State one intervention hypothesis");
  console.log("  Step 5: Implement and verify at the claim boundary");
  console.log("  Step 6: Run a fresh trajectory\n");
  console.log("  Non-interactive mode — record your results in a structured format:\n");
  console.log("  ---");
  console.log("  ## Job Contract");
  console.log("  Target and revision:");
  console.log("  Relevant external state:");
  console.log("  Fixed worker:");
  console.log("  Representative job:");
  console.log("  Accepted outcome:");
  console.log("  Suspected harness gap:");
  console.log("");
  console.log("  ## Baseline Evidence");
  console.log("  (observable outcome, not summary)");
  console.log("");
  console.log("  ## Earliest Failed Handoff");
  console.log("  Type: context | capability | domain | authority | proof | feedback | limitation");
  console.log("  Owner:");
  console.log("");
  console.log("  ## Intervention");
  console.log("  If <intervention> at <owner>, then <behavior change> because <mechanism>.");
  console.log("");
  console.log("  ## Verification");
  console.log("  (what was checked and what the rerun showed)");
  console.log("  ---\n");
}

// --- Main ---
const args = process.argv.slice(2);
const cmd = args[0];

if (!cmd || cmd === "list" || cmd === "ls") {
  listTheses();
} else if (cmd === "thesis" || cmd === "t") {
  showThesis(args[1]);
} else if (cmd === "scaffold" || cmd === "s") {
  const nameIdx = args.indexOf("--name");
  const dirIdx = args.indexOf("--dir");
  scaffold({
    name: nameIdx >= 0 ? args[nameIdx + 1] : undefined,
    dir: dirIdx >= 0 ? args[dirIdx + 1] : undefined,
  });
} else if (cmd === "review" || cmd === "r") {
  showReview();
} else if (cmd === "improve" || cmd === "i") {
  runImproveGuide();
} else if (cmd === "crossref" || cmd === "x") {
  showCrossref();
} else if (cmd === "playbook" || cmd === "p") {
  listPlaybooks();
} else if (cmd === "--help" || cmd === "-h" || cmd === "help") {
  console.log(`
  harness-kit — Harness engineering reference and scaffolding

  Usage:
    harness-kit                   List all 12 theses
    harness-kit thesis N          Read thesis N in detail
    harness-kit scaffold          Generate AGENTS.md + ARCHITECTURE.md
    harness-kit review            Run a repository review
    harness-kit improve           Guided job-improvement playbook
    harness-kit crossref          ICM ↔ Harness Engineering cross-reference

  Examples:
    harness-kit thesis 6          Read "Make the repository teach the agent"
    harness-kit scaffold --name my-repo --dir ../my-repo
    harness-kit crossref          Show the ICM mapping
  `);
} else {
  console.error(`Unknown command: ${cmd}. Try --help`);
  process.exit(1);
}