@mikenguyen69/harness 0.1.0-beta.1

package/dist/internal/system/explore/index.js

@@ -0,0 +1,91 @@
+/**
+ * explore — the exploration lane (D7). A `mode: explore` unit runs ring-0 only
+ * and has no edge to `merged` (enforced by mergeGate). Its only exits:
+ *
+ *   - abort:    unit.aborted. The spike is thrown away.
+ *   - graduate: emit a draft `spec.authored` from what was learned (intent,
+ *               discovered scope, discovered acceptance criteria) and plan a
+ *               normal `build` unit for it.
+ */
+import { append, read as ledgerRead, } from "../ledger/index.js";
+import { projectUnits } from "../units/index.js";
+export class ExploreError extends Error {
+    name = "ExploreError";
+}
+function bareId(ref) {
+    return ref.includes("#") ? ref.slice(ref.indexOf("#") + 1) : ref;
+}
+function assertExplore(unitId, events) {
+    const u = projectUnits(events).get(bareId(unitId));
+    if (!u)
+        throw new ExploreError(`no such unit: ${unitId}`);
+    if (u.mode !== "explore")
+        throw new ExploreError(`unit "${unitId}" is not mode: explore`);
+    if (u.state === "merged" || u.state === "aborted")
+        throw new ExploreError(`unit "${unitId}" is already ${u.state}`);
+    return u;
+}
+export function abortExplore(unitId, opts) {
+    const events = ledgerRead(opts.ledgerDir);
+    const u = assertExplore(unitId, events);
+    return append(opts.ledgerDir, {
+        system: opts.system ?? events[0]?.system ?? unitId,
+        actor: { kind: "human", id: "operator" },
+        type: "unit.aborted",
+        ts: opts.now ?? new Date().toISOString(),
+        body: {
+            unit_id: unitId,
+            ...(u.component ? { component: u.component } : {}),
+            reason: "explore: aborted",
+        },
+    });
+}
+/** Emit a draft build spec from the spike's learnings and plan the build unit. */
+export function graduateExplore(unitId, discovered, opts) {
+    const events = ledgerRead(opts.ledgerDir);
+    const u = assertExplore(unitId, events);
+    const ts = opts.now ?? new Date().toISOString();
+    const sys = opts.system ?? events[0]?.system ?? unitId;
+    const draftSpecId = `${u.component ?? "core"}#${bareId(unitId)}-graduated`;
+    const spec = {
+        id: draftSpecId,
+        component: u.component ?? "core",
+        mode: "build",
+        intent: discovered.intent,
+        acceptance_criteria: discovered.acceptanceCriteria,
+        scope: discovered.scope,
+    };
+    const out = [];
+    out.push(append(opts.ledgerDir, {
+        system: sys,
+        actor: { kind: "human", id: "operator" },
+        type: "unit.aborted",
+        ts,
+        body: {
+            unit_id: unitId,
+            reason: "explore: graduated",
+            graduated_to: draftSpecId,
+        },
+    }));
+    out.push(append(opts.ledgerDir, {
+        system: sys,
+        actor: { kind: "human", id: "operator" },
+        type: "spec.authored",
+        ts,
+        body: { spec_id: draftSpecId, draft: true, from_explore: unitId, spec },
+    }));
+    out.push(append(opts.ledgerDir, {
+        system: sys,
+        actor: { kind: "harness", id: "harness" },
+        type: "unit.planned",
+        ts,
+        body: {
+            unit_id: draftSpecId,
+            component: u.component ?? "core",
+            mode: "build",
+            from_explore: unitId,
+        },
+    }));
+    return { draftSpecId, events: out };
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/system/gates/cli.js

@@ -0,0 +1,43 @@
+/**
+ * `harness gate --pre` — see src/gates/pre.ts for the policy. Any other
+ * `harness gate <name>` invocation (a single built-in gate run, e.g. the
+ * `spec`/`size`/`gen:fresh` gates a profile's `run =` line shells out to) is
+ * not implemented yet — that is a separate, larger piece of work than ring 0
+ * and stays a tracked skeleton (see docs/implement/plan.md).
+ *
+ *   harness gate --pre --file <path> [--component <dir>] [--profiles <dir>]
+ *
+ * Exit: 0 pass (including "no cheap gates bound") · 1 a cheap gate failed ·
+ * 2 halt (component.toml / profile could not be resolved).
+ */
+import { runGatePre } from "./pre.js";
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 && args[i + 1] ? args[i + 1] : undefined;
+}
+export function gateCommand(args) {
+    if (!args.includes("--pre"))
+        return undefined; // let the caller fall through
+    const result = runGatePre({
+        ...(flag(args, "component") ? { componentDir: flag(args, "component") } : {}),
+        ...(flag(args, "profiles") ? { profilesDir: flag(args, "profiles") } : {}),
+        ...(flag(args, "file") ? { file: flag(args, "file") } : {}),
+    });
+    if (result.verdict === "halt") {
+        process.stderr.write(`⛔ gate --pre halted: ${result.haltReason}\n`);
+        return 2;
+    }
+    if (result.gates.length === 0) {
+        process.stdout.write("· no cheap gates bound; nothing to check at ring 0\n");
+        return 0;
+    }
+    for (const g of result.gates) {
+        const mark = g.outcome === "pass" ? "✓" : "✗";
+        process.stdout.write(`  ${mark} ${g.name.padEnd(12)} ${String(g.durationMs).padStart(6)}ms\n`);
+        if (g.outcome !== "pass" && g.output.trim()) {
+            process.stderr.write(g.output.trim() + "\n");
+        }
+    }
+    return result.verdict === "pass" ? 0 : 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/internal/system/gates/detectors.js

@@ -0,0 +1,55 @@
+/**
+ * gate detectors — the small, replay-testable checks behind a few named gates.
+ * Each takes plain data (no filesystem, no tools) so a corpus fixture can drive
+ * it deterministically.
+ */
+import picomatch from "picomatch";
+const SUPPRESSION_RE = /\b(eslint-disable(?:-next-line|-line)?|@ts-(?:ignore|expect-error|nocheck)|noqa|type:\s*ignore|nosec|prettier-ignore)\b/;
+/** `gate:lint` — net-new suppression comments introduced by a diff. */
+export function suppressionDelta(before, after) {
+    const count = (s) => s.split("\n").filter((l) => SUPPRESSION_RE.test(l)).length;
+    const beforeLines = new Set(before
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => SUPPRESSION_RE.test(l)));
+    const added = [];
+    for (const l of after.split("\n")) {
+        const t = l.trim();
+        if (SUPPRESSION_RE.test(t) && !beforeLines.has(t))
+            added.push(t);
+    }
+    // also catch a raw increase even if lines look identical (duplication)
+    if (added.length === 0 && count(after) > count(before))
+        added.push("(suppression count increased)");
+    return added;
+}
+/** `gate:size`/scope — changed files that fall outside the unit's declared scope globs. */
+export function scopeCross(changedFiles, scopeGlobs) {
+    if (scopeGlobs.length === 0)
+        return changedFiles.slice();
+    const isMatch = picomatch(scopeGlobs.map((g) => g.replace(/\\/g, "/")), { dot: true });
+    return changedFiles
+        .map((f) => f.replace(/\\/g, "/"))
+        .filter((f) => !isMatch(f));
+}
+/** `gate:arch` — a test file weakened in the same unit as the code it covers. */
+export function testWeakening(input) {
+    const isTest = (p) => /\.(?:test|spec)\.[tj]sx?$/.test(p) ||
+        /(^|\/)(?:tests?|__tests__)\//.test(p);
+    const stemOf = (p) => p
+        .split(/[/\\]/)
+        .pop()
+        .replace(/\.(?:test|spec)\.[tj]sx?$/, "")
+        .replace(/\.[tj]sx?$/, "");
+    const subjectStems = new Set(input.changed.filter((p) => !isTest(p)).map(stemOf));
+    const flags = [];
+    for (const [testFile, removed] of Object.entries(input.assertionsRemoved)) {
+        if (removed <= 0 || !input.changed.includes(testFile))
+            continue;
+        if (subjectStems.has(stemOf(testFile))) {
+            flags.push(`${testFile}: ${removed} assertion(s) removed while its subject (${stemOf(testFile)}) changed in the same unit`);
+        }
+    }
+    return flags;
+}
+//# sourceMappingURL=detectors.js.map

package/dist/internal/system/gates/pre.js

@@ -0,0 +1,51 @@
+/**
+ * gate --pre — ring 0, the seconds-loop actuator (mission `docs/mission.md`
+ * §"the five feedback loops", loop 1). Runs only the *cheap*-cost gates bound
+ * for this component, at the component root, and reports pass/fail using the
+ * exact same policy `harness verify` (ring 1) uses (`verdictOf`) — so ring 0
+ * can give fast feedback but never disagree with ring 1 about what "failing"
+ * means. It never mints an envelope and never touches the ledger: it is the
+ * fast copy of the rule, not the guarantee (adapter docstring, principle 1).
+ *
+ * Deliberately not (yet) file-scoped: `--file <path>` is accepted (the
+ * PreToolUse hook always passes it) but not used to filter which gates run —
+ * the manifest carries no per-file gate mapping today. Every bound cheap gate
+ * runs at the component root on every call. This is honest, not silently
+ * fake precision: it is the caller's own `cost: cheap` declaration in the
+ * component manifest and the profile bindings that decides whether a gate is
+ * fast enough to belong here — calibration (`src/calibration`) is the
+ * long-run mechanism for re-labeling a gate that turns out too slow. Ring 0
+ * only ever runs when the caller opts in (`HARNESS_RING0=1`); it is never the
+ * default path.
+ */
+import { join, resolve } from "node:path";
+import { targetPath } from "../assets.js";
+import { loadManifest, loadProfile, resolveManifest, ManifestError, } from "../manifest/index.js";
+import { runGates } from "../runner/index.js";
+import { verdictOf } from "../verify/index.js";
+export function runGatePre(opts) {
+    const componentDir = resolve(opts.componentDir ?? process.cwd());
+    const profilesDir = opts.profilesDir ?? targetPath(componentDir, "profiles");
+    let bound;
+    try {
+        const manifest = loadManifest(targetPath(componentDir, "component.toml"));
+        const profile = loadProfile(join(profilesDir, manifest.harness.profile, "bindings.toml"));
+        bound = resolveManifest(manifest, profile, { context: "verify" }).bound;
+    }
+    catch (e) {
+        return {
+            verdict: "halt",
+            gates: [],
+            haltReason: e instanceof ManifestError
+                ? e.message
+                : `could not resolve gates: ${e.message}`,
+        };
+    }
+    const cheap = bound.filter((g) => g.cost === "cheap");
+    if (cheap.length === 0) {
+        return { verdict: "pass", gates: [] };
+    }
+    const gateRuns = runGates(cheap, { cwd: componentDir });
+    return { verdict: verdictOf(gateRuns), gates: gateRuns };
+}
+//# sourceMappingURL=pre.js.map

package/dist/internal/system/hub/cli.js

@@ -0,0 +1,51 @@
+/**
+ * `harness hub` — the operator hub.
+ *
+ *   harness hub sync    --from <ledger-dir> --to <hub-ledger-dir>
+ *                       [--spool-from <dir> --spool-to <dir>]
+ *   harness hub project [--ledger <dir>] [--redact]
+ *
+ * `sync` also copies the run-status spool (P7.2) when both `--spool-*` are
+ * given — the same pull channel, one command.
+ */
+import { syncSpool } from "../runstatus/index.js";
+import { HubError, projectLedger, syncLedger } from "./index.js";
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 && args[i + 1] ? args[i + 1] : undefined;
+}
+export function hubCommand(args) {
+    const sub = args[0];
+    if (sub === "sync") {
+        const from = flag(args, "from");
+        const to = flag(args, "to");
+        if (!from || !to) {
+            process.stderr.write("harness hub sync --from <ledger-dir> --to <hub-ledger-dir>\n");
+            return 2;
+        }
+        try {
+            const r = syncLedger(from, to);
+            let extra = "";
+            const spoolFrom = flag(args, "spool-from");
+            const spoolTo = flag(args, "spool-to");
+            if (spoolFrom && spoolTo) {
+                const files = syncSpool(spoolFrom, spoolTo);
+                extra = `; ${files.length} run-status document(s)`;
+            }
+            process.stdout.write(`synced ${r.segments.length} segment(s), ${r.events} event(s); chain intact${extra}\n`);
+            return 0;
+        }
+        catch (e) {
+            process.stderr.write(`${e.message}\n`);
+            return e instanceof HubError ? 1 : 2;
+        }
+    }
+    if (sub === "project") {
+        const state = projectLedger(flag(args, "ledger") ?? ".harness/ledger", args.includes("--redact") ? { dropReasonText: true } : undefined);
+        process.stdout.write(JSON.stringify(state, null, 2) + "\n");
+        return 0;
+    }
+    process.stderr.write("harness hub <sync --from … --to … | project [--ledger …] [--redact]>\n");
+    return 2;
+}
+//# sourceMappingURL=cli.js.map

package/dist/internal/system/hub/index.js

@@ -0,0 +1,146 @@
+/**
+ * hub — the operator side. Pulls read-only ledger replicas, runs a
+ * deterministic projection over them, and can redact reason-text on export.
+ *
+ *   - sync: copy JSONL segments, then verify the chain — a divergent replica
+ *     fails loudly (HubError), never silently stale.
+ *   - project: a pure reduction to a derived state. Re-projecting from scratch
+ *     yields a byte-identical object (the golden property).
+ *   - redact: strip reason / detail / context text for clients that require it.
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { read as ledgerRead, verifyChain, } from "../ledger/index.js";
+import { projectUnits } from "../units/index.js";
+import { projectDoors } from "../doors/index.js";
+export class HubError extends Error {
+    name = "HubError";
+}
+const SEGMENT_RE = /^\d{6}\.jsonl$/;
+/** Copy ledger segments from a source dir into the hub, then verify the chain. */
+export function syncLedger(fromDir, toDir) {
+    if (!existsSync(fromDir))
+        throw new HubError(`no ledger at ${fromDir}`);
+    mkdirSync(toDir, { recursive: true });
+    const segments = readdirSync(fromDir)
+        .filter((n) => SEGMENT_RE.test(n))
+        .sort();
+    for (const seg of segments)
+        cpSync(join(fromDir, seg), join(toDir, seg));
+    const chain = verifyChain(toDir);
+    if (!chain.ok) {
+        throw new HubError(`divergent replica: chain BROKEN at seq ${chain.seq} — ${chain.reason}`);
+    }
+    return { segments, events: chain.length };
+}
+const REDACT_KEYS = ["reason", "detail", "context", "why"];
+/** Return copies of the events with free-text fields blanked per config. */
+export function redact(events, config) {
+    if (!config.dropReasonText)
+        return events;
+    return events.map((e) => {
+        const body = { ...e.body };
+        for (const k of REDACT_KEYS)
+            if (k in body)
+                body[k] = "[redacted]";
+        return { ...e, body };
+    });
+}
+/** Deterministic projection — sorted throughout, order-independent, re-runnable. */
+export function project(events) {
+    const sorted = [...events].sort((a, b) => a.seq - b.seq);
+    const units = [...projectUnits(sorted).values()].sort((a, b) => a.id.localeCompare(b.id));
+    const doors = [...projectDoors(sorted).values()].sort((a, b) => a.id.localeCompare(b.id));
+    const unitCounts = {};
+    for (const u of units)
+        unitCounts[u.state] = (unitCounts[u.state] ?? 0) + 1;
+    const sessions = new Map();
+    for (const e of sorted) {
+        if (!e.type.startsWith("session."))
+            continue;
+        const b = e.body;
+        const id = b.session_id ?? "unknown";
+        const s = sessions.get(id) ?? {
+            id,
+            unit: b.unit_id ?? "",
+            model: null,
+            costUsd: 0,
+            events: 0,
+        };
+        s.events++;
+        if (b.unit_id)
+            s.unit = b.unit_id;
+        if (b.model)
+            s.model = b.model;
+        if (typeof b.cost_usd === "number")
+            s.costUsd += b.cost_usd;
+        sessions.set(id, s);
+    }
+    const escapes = [];
+    for (const e of sorted) {
+        if (e.type !== "escape.routed")
+            continue;
+        const b = e.body;
+        escapes.push({
+            scenario: b.scenario ?? "",
+            owner: b.owner ?? null,
+            newUnit: b.new_unit ?? null,
+        });
+    }
+    const systemHalts = [];
+    for (const e of sorted) {
+        if (e.type !== "system.halted")
+            continue;
+        const b = e.body;
+        systemHalts.push({ cause: b.cause ?? "", detail: b.detail ?? "" });
+    }
+    const runAnalyses = [];
+    for (const e of sorted) {
+        if (e.type !== "run.analyzed")
+            continue;
+        const b = e.body;
+        runAnalyses.push({
+            runId: b.run_id ?? "",
+            ts: e.ts,
+            units: (b.units ?? []).map((u) => ({
+                unitId: u.unit_id ?? "",
+                turnsTotal: u.turns_total ?? 0,
+                toolFailures: u.tool_failures ?? 0,
+                attempts: u.attempts ?? 0,
+                wallMs: u.wall_ms ?? 0,
+                agentMs: u.agent_ms ?? 0,
+                costUsd: typeof u.cost_usd === "number" ? u.cost_usd : null,
+                runner: u.runner ?? "",
+                model: u.model ?? "",
+            })),
+            findings: (b.findings ?? []).map((f) => ({
+                rule: f.rule ?? "",
+                unitId: f.unit_id ?? "",
+                severity: f.severity ?? "info",
+                count: f.count ?? 0,
+            })),
+            logRef: b.log_ref ?? "",
+        });
+    }
+    return {
+        system: sorted[0]?.system ?? null,
+        counts: {
+            events: sorted.length,
+            units: unitCounts,
+            doorsOpen: doors.filter((d) => d.state === "opened").length,
+            escapes: escapes.length,
+            systemHalts: systemHalts.length,
+        },
+        units,
+        doors,
+        sessions: [...sessions.values()].sort((a, b) => a.id.localeCompare(b.id)),
+        escapes,
+        systemHalts,
+        runAnalyses,
+    };
+}
+export function projectLedger(ledgerDir, redaction) {
+    const events = ledgerRead(ledgerDir);
+    return project(redaction ? redact(events, redaction) : events);
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/system/init/index.js

@@ -0,0 +1,83 @@
+/**
+ * init — scaffold hooks (`harness hook pre-tool-use`).
+ *
+ * Named owner of init-composes-hook-install: system-harness `init` invokes the
+ * agent-harness hook-install path (`adapter/install`) directly as a subprocess
+ * composition. system-harness does not import `@harness/agent`. The published
+ * facade only routes `harness init` here and adds no hook-install logic.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { packageProfilesDir, packageTemplatesDir, targetOwnedPaths, targetPath, } from "../assets.js";
+/** Public facade hook command — never an internal binary path. */
+export const HOOK_COMMAND = "harness hook pre-tool-use";
+/** Documented composition: system init → agent-harness adapter/install. */
+export const HOOK_INSTALL_OWNER = "system-harness init composes agent-harness adapter/install";
+function resolveAgentHookInstall() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const fromEnv = process.env.AGENT_HARNESS_BIN;
+    const candidates = [
+        // staged / published layout: dist/internal/{system,agent}/
+        join(here, "..", "..", "agent", "adapter", "install.js"),
+        // workspace layout: repos/{system,agent}-harness/{src,dist}/
+        join(here, "..", "..", "..", "agent-harness", "dist", "adapter", "install.js"),
+        ...(fromEnv ? [join(dirname(fromEnv), "adapter", "install.js")] : []),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    throw new Error(`agent-harness hook-install path not found (looked in ${candidates.join(", ")}); build @harness/agent`);
+}
+/**
+ * Invoke the agent-harness hook-install path. `command` is accepted for call-site
+ * compatibility; the install path always writes `HOOK_COMMAND`.
+ */
+export function writeInitHooks(repoRoot, _command = HOOK_COMMAND) {
+    const install = resolveAgentHookInstall();
+    const result = spawnSync(process.execPath, [install, "--cwd", resolve(repoRoot)], {
+        encoding: "utf8",
+        windowsHide: true,
+    });
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.stdout || "").trim();
+        throw new Error(`hook-install failed (${result.status}): ${detail || "no output"}`);
+    }
+    const written = (result.stdout ?? "").trim();
+    return written || targetPath(repoRoot, ".claude", "settings.json");
+}
+export function runInit(repoRoot) {
+    const root = resolve(repoRoot);
+    return {
+        repoRoot: root,
+        hooksPath: writeInitHooks(root),
+        profilesDir: packageProfilesDir(),
+        templatesDir: packageTemplatesDir(),
+    };
+}
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 && args[i + 1] ? args[i + 1] : undefined;
+}
+export function initCommand(args, cwd = process.cwd()) {
+    if (args.includes("--help") || args.includes("-h")) {
+        process.stdout.write("harness init [--cwd <dir>]  scaffold hooks (harness hook pre-tool-use)\n");
+        return 0;
+    }
+    const repo = resolve(flag(args, "cwd") ?? cwd);
+    mkdirSync(targetOwnedPaths(repo).harnessDir, { recursive: true });
+    try {
+        const result = runInit(repo);
+        process.stdout.write(`✓ hooks  ${result.hooksPath}\n`);
+        process.stdout.write(`  (profiles from ${result.profilesDir})\n`);
+        process.stdout.write(`  (templates from ${result.templatesDir})\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`harness init: ${error.message}\n`);
+        return 1;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/system/ledger/cli.js

@@ -0,0 +1,54 @@
+/**
+ * `harness ledger <sub>` — the single write path into the record plane.
+ *
+ *   harness ledger append        < event.json     append one event (stdin JSON), print it
+ *   harness ledger verify-chain                   recompute the chain; exit 1 on any break
+ *   harness ledger read                           print every event as JSONL
+ *
+ * Common flag: --dir <path>   (default .harness/ledger)
+ *
+ * agent-harness appends its session and eval events through this same command,
+ * so chaining (and later, signing) live in one implementation.
+ */
+import { readFileSync } from "node:fs";
+import { append, read, verifyChain } from "./index.js";
+const DEFAULT_DIR = ".harness/ledger";
+function dirFrom(args) {
+    const i = args.indexOf("--dir");
+    return i >= 0 && args[i + 1] ? args[i + 1] : DEFAULT_DIR;
+}
+export function ledgerCommand(args) {
+    const sub = args[0];
+    const dir = dirFrom(args);
+    switch (sub) {
+        case "append": {
+            const raw = readFileSync(0, "utf8").trim();
+            if (raw === "") {
+                process.stderr.write("harness ledger append: expected an event JSON on stdin\n");
+                return 2;
+            }
+            const ev = JSON.parse(raw);
+            const written = append(dir, ev);
+            process.stdout.write(JSON.stringify(written) + "\n");
+            return 0;
+        }
+        case "read": {
+            for (const e of read(dir))
+                process.stdout.write(JSON.stringify(e) + "\n");
+            return 0;
+        }
+        case "verify-chain": {
+            const result = verifyChain(dir);
+            if (result.ok) {
+                process.stdout.write(`ok — ${result.length} event(s), chain intact\n`);
+                return 0;
+            }
+            process.stderr.write(`BROKEN at seq ${result.seq}: ${result.reason}\n`);
+            return 1;
+        }
+        default:
+            process.stderr.write("harness ledger <append|read|verify-chain> [--dir <path>]\n");
+            return 2;
+    }
+}
+//# sourceMappingURL=cli.js.map