@ai-substrate/engineering-harness 0.2.0

package/harness/cli/dist/app.js

@@ -0,0 +1,221 @@
+import { Command } from 'commander';
+import { registerDocsAct } from './acts/docs.js';
+import { registerDoctorAct } from './acts/doctor.js';
+import { registerHelpAct } from './acts/help.js';
+import { registerInitAct } from './acts/init.js';
+import { registerInstructionsAct } from './acts/instructions.js';
+import { registerNewAct } from './acts/new.js';
+import { registerObserveAct } from './acts/observe.js';
+import { registerRecordAct } from './acts/record.js';
+import { registerSkillsAct } from './acts/skills.js';
+import { registerUpdateAct } from './acts/update.js';
+import { registerVerbAct } from './acts/verb.js';
+import { SystemClock } from './adapters/clock/system-clock.js';
+import { NodeEnv } from './adapters/env/node-env.js';
+import { NodeExec } from './adapters/exec/node-exec.js';
+import { NodeFs } from './adapters/fs/node-fs.js';
+import { ExecGit } from './adapters/git/exec-git.js';
+import { JitiLoader } from './adapters/loader/jiti-loader.js';
+import { NodeProcess } from './adapters/process/node-process.js';
+import { formatError, formatOk } from './output/envelope.js';
+import { ErrorCodes } from './output/error-codes.js';
+import { exitWithEnvelope, setBannerDecorator } from './output/exit.js';
+import { createOutputPort, processWriters, selectMode, } from './output/output-port.js';
+import { helpStyleConfig, resolveUseColor } from './output/style.js';
+import { validateVerbRegistry } from './services/config/load-config.js';
+import { discoverExtensions } from './services/extensions/discovery.js';
+import { buildExtensionRegistry, } from './services/extensions/registry.js';
+import { buildRecordRegistry, coreRecordTypes, } from './services/record/registry.js';
+import { buildBannerDecorator } from './services/update/banner.js';
+import { readVersion } from './version.js';
+/**
+ * Tri-state read of the output flag from argv. The entrypoint resolves this
+ * ONCE — commander collapses `--json`/`--no-json` to a single boolean and loses
+ * the "absent" state that lets env/TTY decide, so acts must never re-derive it.
+ */
+export function jsonFlag(argv) {
+    if (argv.includes('--no-json')) {
+        return false;
+    }
+    if (argv.includes('--json')) {
+        return true;
+    }
+    return undefined;
+}
+/**
+ * Safe mode: skip extension discovery entirely (core commands only). Detected
+ * from raw argv (`--no-extensions`) or env (`HARNESS_NO_EXTENSIONS=1`) BEFORE
+ * parse, since the registry must be known before commander is built.
+ *
+ * NOTE (v1): the argv scan is a simple `includes`, so a `--no-extensions` placed
+ * after a verb name (as a verb's own option) would also trigger safe mode. The
+ * env var is the unambiguous path; revisit if a verb ever needs that flag.
+ */
+export function isExtensionsDisabled(argv, env) {
+    return argv.includes('--no-extensions') || env.HARNESS_NO_EXTENSIONS === '1';
+}
+function orientationEnvelope(version) {
+    return formatOk('harness', {
+        version,
+        purpose: "Front door to this repo's engineering harness.",
+        next_steps: ['harness help', 'harness doctor'],
+    }, new SystemClock(), { next_action: 'Run `harness help` for the command surface.' });
+}
+/**
+ * Map a thrown commander error (raised because `exitOverride` is set) to an
+ * actionable envelope. Returns `null` for help/version display (commander
+ * already printed; the caller exits 0). Unknown command/option/missing-arg →
+ * `E108`; anything else (an unexpected bug) → `E100` — so no raw stack trace
+ * ever escapes.
+ */
+export function commanderErrorEnvelope(err, clock) {
+    if (err.code === 'commander.helpDisplayed' ||
+        err.code === 'commander.version' ||
+        err.code === 'commander.help') {
+        return null;
+    }
+    const code = typeof err.code === 'string' && err.code.startsWith('commander.')
+        ? ErrorCodes.INVALID_ARGS
+        : ErrorCodes.UNKNOWN;
+    return formatError('harness', code, err.message ?? 'Unexpected error.', clock, {
+        next_action: 'Run `harness help` for usage.',
+    });
+}
+/** Last-resort envelope for an unexpected error before/around parse — routed through the kernel. */
+function unexpectedEnvelope(err, clock) {
+    return formatError('harness', ErrorCodes.UNKNOWN, err instanceof Error ? err.message : String(err), clock, { next_action: 'This is an unexpected harness error; please report it.' });
+}
+/**
+ * Discover + load the repo's extensions into the extension registry (verbs +
+ * record types + provenance) in one pass, unless safe mode is on (then the
+ * registry is empty — core commands + core record types only). Core record-type
+ * names are reserved so an extension can never shadow them. Runs BEFORE parse so
+ * each verb is a registered command (WS-A Decision 6).
+ */
+export async function loadRegistry(argv, env, deps, loader) {
+    if (isExtensionsDisabled(argv, env)) {
+        return { verbs: [], recordTypes: [], records: [] };
+    }
+    const discovery = discoverExtensions(deps.fs, deps.proc);
+    return buildExtensionRegistry(discovery.candidates, loader, {
+        reservedRecordTypes: new Set(coreRecordTypes.map((t) => t.type)),
+        rejected: discovery.rejected,
+    });
+}
+/**
+ * Build the composition root: global flags + core commands (incl. `record`, built
+ * from the merged record registry = core ∪ extension) + one subcommand per
+ * discovered verb, each registered with the pre-resolved `io` + injected ports. No
+ * business logic, no fs/process/git here.
+ */
+export function buildProgram(version, io, deps, registry) {
+    const program = new Command()
+        .name('harness')
+        .description("The agent-friendly front door to this repo's engineering harness.")
+        .version(version, '-v, --version')
+        .option('--json', 'force JSON output')
+        .option('--no-json', 'force human output')
+        .option('--no-extensions', 'skip loading repo extensions (core commands only)')
+        // Core commands sit under the default `Commands:` heading; each extension
+        // verb overrides this with `Extensions:` (see registerVerbAct) so the two
+        // surfaces read as distinct sections in `--help`. configureHelp accents the
+        // headings; commander strips the ANSI itself on non-color output streams.
+        .commandsGroup('Commands:')
+        .configureHelp(helpStyleConfig())
+        .exitOverride();
+    const recordRegistry = buildRecordRegistry(coreRecordTypes, registry.recordTypes ?? []);
+    // Cross-cutting: register the update banner ONCE so every command's exit
+    // chokepoint surfaces a known update (JSON field + human stderr line) from a
+    // single sync cache read. No-op until the cache holds a newer version (AC9);
+    // with no resolvable home (test fakes) it never fires.
+    setBannerDecorator(buildBannerDecorator({
+        fs: deps.fs,
+        env: deps.env,
+        installed: version,
+        mode: io.mode,
+        writers: io.writers,
+    }));
+    registerHelpAct(program, io, registry, deps.fs);
+    registerDoctorAct(program, io, registry, recordRegistry);
+    registerInitAct(program, io, deps);
+    registerNewAct(program, io, deps);
+    registerDocsAct(program, io);
+    registerSkillsAct(program, io, deps);
+    registerUpdateAct(program, io, deps, version);
+    registerRecordAct(program, io, deps, recordRegistry);
+    registerObserveAct(program, io, deps);
+    registerInstructionsAct(program, io, { fs: deps.fs, clock: deps.clock }, registry);
+    for (const verb of registry.verbs) {
+        registerVerbAct(program, verb, deps, io);
+    }
+    // Bare `harness` (no subcommand) prints an orientation envelope.
+    program.action(() => {
+        exitWithEnvelope(orientationEnvelope(version), createOutputPort(io.mode, io.writers));
+    });
+    return program;
+}
+function defaultDeps() {
+    return {
+        exec: new NodeExec(),
+        fs: new NodeFs(),
+        env: new NodeEnv(),
+        git: new ExecGit(),
+        clock: new SystemClock(),
+        proc: new NodeProcess(),
+    };
+}
+/**
+ * The async composition root (WS-A Decision 6): resolve output mode, discover +
+ * load extensions, validate the assembled registry, then `await parseAsync`.
+ * Three distinct error boundaries keep the kernel the sole exit point:
+ *   1. an unexpected discovery/load error → `E100` (routed through the kernel);
+ *   2. a malformed registry → the `E120` validation envelope;
+ *   3. a commander parse error → `commanderErrorEnvelope` (help/version → exit 0).
+ */
+export async function main(argv = process.argv, overrides = {}) {
+    const deps = overrides.deps ?? defaultDeps();
+    const loader = overrides.loader ?? new JitiLoader();
+    const env = overrides.env ?? process.env;
+    const isTty = overrides.isTty ?? Boolean(process.stdout.isTTY);
+    const writers = overrides.writers ?? processWriters;
+    const version = overrides.version ?? readVersion();
+    const clock = deps.clock;
+    const mode = selectMode({ json: jsonFlag(argv) }, env, isTty);
+    const io = { mode, writers, useColor: resolveUseColor({ mode, isTty, env }) };
+    const port = createOutputPort(io.mode, io.writers);
+    // Register the update banner BEFORE any exit — incl. the pre-build discovery /
+    // registry-validation error envelopes below, which exit before buildProgram
+    // (which re-registers it) runs (companion F004). Idempotent: same decorator.
+    setBannerDecorator(buildBannerDecorator({
+        fs: deps.fs,
+        env: deps.env,
+        installed: version,
+        mode: io.mode,
+        writers: io.writers,
+    }));
+    let registry;
+    try {
+        registry = await loadRegistry(argv, env, deps, loader);
+    }
+    catch (err) {
+        exitWithEnvelope(unexpectedEnvelope(err, clock), port);
+        return;
+    }
+    const check = validateVerbRegistry(registry.verbs, clock);
+    if (check.status === 'error') {
+        exitWithEnvelope(check, port);
+        return;
+    }
+    try {
+        await buildProgram(version, io, deps, registry).parseAsync(argv);
+    }
+    catch (err) {
+        const envelope = commanderErrorEnvelope(err, clock);
+        if (envelope === null) {
+            // help/version: commander already printed; returning lets Node exit 0.
+            return;
+        }
+        exitWithEnvelope(envelope, port);
+    }
+}
+//# sourceMappingURL=app.js.map

package/harness/cli/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/harness/cli/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/harness/cli/dist/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { main } from './app.js';
+// Pipe-friendly raw output (`harness docs <id> | head`) can have stdout closed
+// by the reader before we finish writing, which Node surfaces as EPIPE. Treat a
+// broken pipe as a normal early-close (not a failure) so the raw-dump path never
+// prints a stack trace; re-surface any other stream error unchanged. Uses
+// process.exitCode (never process.exit) so the single-exit architecture holds.
+process.stdout.on('error', (err) => {
+    if (err.code === 'EPIPE') {
+        process.exitCode = 0;
+        return;
+    }
+    throw err;
+});
+// Thin bin entry — always runs. All composition logic lives in app.ts (testable,
+// never auto-runs). Called unconditionally so the npm/npx bin symlink works
+// regardless of how the symlink resolves (companion F005).
+//
+// main() routes every expected failure through the exit kernel; this .catch() is
+// a CATASTROPHIC-only net so the async bin can never float an unhandled promise
+// rejection (which would bypass the kernel + the Envelope contract). KF-04.
+main().catch((err) => {
+    process.exitCode = 1;
+    process.stderr.write(`harness: unexpected error: ${err instanceof Error ? err.message : String(err)}\n`);
+});
+//# sourceMappingURL=index.js.map

package/harness/cli/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhC,+EAA+E;AAC/E,gFAAgF;AAChF,iFAAiF;AACjF,0EAA0E;AAC1E,+EAA+E;AAC/E,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAA0B,EAAE,EAAE;IACxD,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QACzB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,MAAM,GAAG,CAAC;AACZ,CAAC,CAAC,CAAC;AAEH,iFAAiF;AACjF,4EAA4E;AAC5E,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,gFAAgF;AAChF,4EAA4E;AAC5E,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACrB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,8BAA8B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CACnF,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/harness/cli/dist/output/envelope.d.ts

@@ -0,0 +1,68 @@
+import type { Clock } from '../adapters/clock/clock-port.js';
+/** The four output states. `unconfigured` is the honest "no mapped behaviour yet". */
+export type Status = 'ok' | 'error' | 'degraded' | 'unconfigured';
+export interface Evidence {
+    /** Human label, e.g. "doctor report" or "coverage summary". */
+    label: string;
+    /** Repo-relative path where durable proof was written, if any. */
+    path?: string;
+    /** Set true when the command explicitly produced NO durable evidence. */
+    none?: boolean;
+}
+/**
+ * Optional, additive "an update is available" notice (plan 019). Set ONLY at the
+ * exit chokepoint (exit.ts), never by the format* constructors — so existing
+ * envelope snapshots / `toEqual` tests are unaffected when no update is known,
+ * and the MCP-stable seam stays additive (P4).
+ */
+export interface UpdateAvailable {
+    /** Currently-installed CLI version. */
+    installed: string;
+    /** Latest version available on the registry. */
+    latest: string;
+    /** Exact command to run to update — pinned to "harness update". */
+    command: string;
+}
+export interface Envelope {
+    command: string;
+    status: Status;
+    /** ISO-8601, from an injected Clock (deterministic in tests). */
+    timestamp: string;
+    data?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    evidence?: Evidence[];
+    next_action?: string;
+    /** Optional additive update notice (plan 019); set only at the exit chokepoint. */
+    update_available?: UpdateAvailable;
+}
+/**
+ * Success. `next_action` is optional for `ok` only — every non-`ok` status has a
+ * dedicated constructor below that REQUIRES `next_action` (workshop 001 field-presence rule).
+ */
+export declare function formatOk<T>(command: string, data: T, clock: Clock, opts?: {
+    evidence?: Evidence[];
+    next_action?: string;
+}): Envelope;
+/**
+ * Succeeded with caveats (exit 0 by default). `next_action` is REQUIRED — the
+ * contract guarantees a non-`ok` envelope always tells an agent what to do next.
+ */
+export declare function formatDegraded<T>(command: string, data: T, next_action: string, clock: Clock, opts?: {
+    evidence?: Evidence[];
+}): Envelope;
+/**
+ * Honest "not built". `next_action` REQUIRED; `data` is optional so a command can
+ * carry context (e.g. `harness run smoke --dry-run` → `{dry_run:true,slot,mapped_command:null}`,
+ * workshop 001 worked example #4). Always maps to exit 2.
+ */
+export declare function formatUnconfigured(command: string, next_action: string, clock: Clock, opts?: {
+    data?: unknown;
+}): Envelope;
+export declare function formatError(command: string, code: string, message: string, clock: Clock, opts?: {
+    details?: unknown;
+    next_action?: string;
+}): Envelope;

package/harness/cli/dist/output/envelope.js

@@ -0,0 +1,56 @@
+/**
+ * Success. `next_action` is optional for `ok` only — every non-`ok` status has a
+ * dedicated constructor below that REQUIRES `next_action` (workshop 001 field-presence rule).
+ */
+export function formatOk(command, data, clock, opts) {
+    return {
+        command,
+        status: 'ok',
+        timestamp: clock.nowIso(),
+        data,
+        ...(opts?.evidence && { evidence: opts.evidence }),
+        ...(opts?.next_action && { next_action: opts.next_action }),
+    };
+}
+/**
+ * Succeeded with caveats (exit 0 by default). `next_action` is REQUIRED — the
+ * contract guarantees a non-`ok` envelope always tells an agent what to do next.
+ */
+export function formatDegraded(command, data, next_action, clock, opts) {
+    return {
+        command,
+        status: 'degraded',
+        timestamp: clock.nowIso(),
+        data,
+        ...(opts?.evidence && { evidence: opts.evidence }),
+        next_action,
+    };
+}
+/**
+ * Honest "not built". `next_action` REQUIRED; `data` is optional so a command can
+ * carry context (e.g. `harness run smoke --dry-run` → `{dry_run:true,slot,mapped_command:null}`,
+ * workshop 001 worked example #4). Always maps to exit 2.
+ */
+export function formatUnconfigured(command, next_action, clock, opts) {
+    return {
+        command,
+        status: 'unconfigured',
+        timestamp: clock.nowIso(),
+        ...(opts?.data !== undefined && { data: opts.data }),
+        next_action,
+    };
+}
+export function formatError(command, code, message, clock, opts) {
+    return {
+        command,
+        status: 'error',
+        timestamp: clock.nowIso(),
+        error: {
+            code,
+            message,
+            ...(opts?.details !== undefined && { details: opts.details }),
+        },
+        next_action: opts?.next_action ?? message,
+    };
+}
+//# sourceMappingURL=envelope.js.map

package/harness/cli/dist/output/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/output/envelope.ts"],"names":[],"mappings":"AA8CA;;;GAGG;AACH,MAAM,UAAU,QAAQ,CACtB,OAAe,EACf,IAAO,EACP,KAAY,EACZ,IAAsD;IAEtD,OAAO;QACL,OAAO;QACP,MAAM,EAAE,IAAI;QACZ,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE;QACzB,IAAI;QACJ,GAAG,CAAC,IAAI,EAAE,QAAQ,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClD,GAAG,CAAC,IAAI,EAAE,WAAW,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,IAAO,EACP,WAAmB,EACnB,KAAY,EACZ,IAAgC;IAEhC,OAAO;QACL,OAAO;QACP,MAAM,EAAE,UAAU;QAClB,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE;QACzB,IAAI;QACJ,GAAG,CAAC,IAAI,EAAE,QAAQ,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClD,WAAW;KACZ,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAe,EACf,WAAmB,EACnB,KAAY,EACZ,IAAyB;IAEzB,OAAO;QACL,OAAO;QACP,MAAM,EAAE,cAAc;QACtB,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE;QACzB,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;QACpD,WAAW;KACZ,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,OAAe,EACf,IAAY,EACZ,OAAe,EACf,KAAY,EACZ,IAAkD;IAElD,OAAO;QACL,OAAO;QACP,MAAM,EAAE,OAAO;QACf,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE;QACzB,KAAK,EAAE;YACL,IAAI;YACJ,OAAO;YACP,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;SAC9D;QACD,WAAW,EAAE,IAAI,EAAE,WAAW,IAAI,OAAO;KAC1C,CAAC;AACJ,CAAC"}

package/harness/cli/dist/output/error-codes.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Central error-code table (grep `Exxx` to find call sites). Start minimal;
+ * grow as commands are added. Workshop 001 § Error code table.
+ */
+export declare const ErrorCodes: {
+    /** Unclassified failure (last resort). */
+    readonly UNKNOWN: "E100";
+    /** Missing/invalid argument or flag. */
+    readonly INVALID_ARGS: "E108";
+    /** `.harness`/command-map config failed validation. */
+    readonly CONFIG_INVALID: "E120";
+    /** A doctor check raised an unexpected error (vs. reporting a failing layer). */
+    readonly DOCTOR_CHECK_FAILED: "E130";
+    /** An extension file couldn't be imported or failed shape validation (per-extension, non-fatal; surfaced by `doctor`). */
+    readonly EXTENSION_LOAD_FAILED: "E140";
+    /** A verb handler threw at invocation time, or returned an invalid result (isolated → error Envelope, never a raw stack). */
+    readonly EXTENSION_RUNTIME_ERROR: "E141";
+    /** Two extensions (or an extension + a reserved core name) declared the same verb name. */
+    readonly EXTENSION_VERB_CONFLICT: "E142";
+    /** A flat code file sits directly under `.harness/extensions/` — unsupported layout since plan 014; move it to `<name>/extension.ts`. */
+    readonly EXTENSION_FLAT_LAYOUT: "E143";
+    /** An extension folder is missing its conventional `instructions.md` agent briefing (doctor wails; the verb still runs). */
+    readonly EXTENSION_INSTRUCTIONS_MISSING: "E144";
+    /** `harness instructions <verb>`: the extension's `instructions.md` exists but could not be read. */
+    readonly INSTRUCTIONS_UNREADABLE: "E145";
+    /** `harness observe`: a bucket's session buffer exists but could not be read (never silent data loss). */
+    readonly OBSERVE_BUFFER_UNREADABLE: "E146";
+    /** `harness new`: the requested verb name fails the name rules (empty, spaces, separators, etc.). */
+    readonly SCAFFOLD_INVALID_NAME: "E150";
+    /** `harness new`: the requested name is reserved by a core command (`help`/`doctor`/`new`). */
+    readonly SCAFFOLD_NAME_RESERVED: "E151";
+    /** `harness new`: a file already exists at the target path and `--force` was not passed. */
+    readonly SCAFFOLD_FILE_EXISTS: "E152";
+    /** `harness new`: the directory create or file write itself failed (permissions, etc.). */
+    readonly SCAFFOLD_WRITE_FAILED: "E153";
+    /** `harness docs <id>`: no curated doc is registered under that id. */
+    readonly DOC_NOT_FOUND: "E160";
+    /** `harness skills install`: the underlying `npx skills add` pass-through failed (non-zero exit / spawn error). */
+    readonly SKILLS_INSTALL_FAILED: "E170";
+    /** `harness record <type>`: no such record type in the merged registry (core ∪ extension). */
+    readonly RECORD_TYPE_UNKNOWN: "E180";
+    /** `harness record <type>`: the records directory create or file write itself failed (permissions, etc.). */
+    readonly RECORD_WRITE_FAILED: "E181";
+    /** `harness init`: writing the governance-doc skeleton (`.harness/engineering-harness.md`) failed (permissions, etc.). */
+    readonly INIT_WRITE_FAILED: "E190";
+    /** `harness update`/`self-install`: the global npm install failed (generic / unclassified). */
+    readonly UPDATE_FAILED: "E200";
+    /** `harness update`/`self-install`: the npm registry rejected the install — unexpected auth on the public package (wrong registry / stale login), or it isn't published yet / the registry is unreachable. */
+    readonly UPDATE_AUTH_FAILED: "E201";
+    /** `harness update`/`self-install`: the global npm install was denied (filesystem permissions). */
+    readonly UPDATE_PERMISSION_DENIED: "E202";
+    /** `harness update`/`self-install`: npm was not found on PATH. */
+    readonly UPDATE_NPM_MISSING: "E203";
+    /** `harness update --pin`: the requested version is not published in the registry. */
+    readonly UPDATE_VERSION_NOT_FOUND: "E204";
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];

package/harness/cli/dist/output/error-codes.js

@@ -0,0 +1,57 @@
+/**
+ * Central error-code table (grep `Exxx` to find call sites). Start minimal;
+ * grow as commands are added. Workshop 001 § Error code table.
+ */
+export const ErrorCodes = {
+    /** Unclassified failure (last resort). */
+    UNKNOWN: 'E100',
+    /** Missing/invalid argument or flag. */
+    INVALID_ARGS: 'E108',
+    /** `.harness`/command-map config failed validation. */
+    CONFIG_INVALID: 'E120',
+    /** A doctor check raised an unexpected error (vs. reporting a failing layer). */
+    DOCTOR_CHECK_FAILED: 'E130',
+    /** An extension file couldn't be imported or failed shape validation (per-extension, non-fatal; surfaced by `doctor`). */
+    EXTENSION_LOAD_FAILED: 'E140',
+    /** A verb handler threw at invocation time, or returned an invalid result (isolated → error Envelope, never a raw stack). */
+    EXTENSION_RUNTIME_ERROR: 'E141',
+    /** Two extensions (or an extension + a reserved core name) declared the same verb name. */
+    EXTENSION_VERB_CONFLICT: 'E142',
+    /** A flat code file sits directly under `.harness/extensions/` — unsupported layout since plan 014; move it to `<name>/extension.ts`. */
+    EXTENSION_FLAT_LAYOUT: 'E143',
+    /** An extension folder is missing its conventional `instructions.md` agent briefing (doctor wails; the verb still runs). */
+    EXTENSION_INSTRUCTIONS_MISSING: 'E144',
+    /** `harness instructions <verb>`: the extension's `instructions.md` exists but could not be read. */
+    INSTRUCTIONS_UNREADABLE: 'E145',
+    /** `harness observe`: a bucket's session buffer exists but could not be read (never silent data loss). */
+    OBSERVE_BUFFER_UNREADABLE: 'E146',
+    /** `harness new`: the requested verb name fails the name rules (empty, spaces, separators, etc.). */
+    SCAFFOLD_INVALID_NAME: 'E150',
+    /** `harness new`: the requested name is reserved by a core command (`help`/`doctor`/`new`). */
+    SCAFFOLD_NAME_RESERVED: 'E151',
+    /** `harness new`: a file already exists at the target path and `--force` was not passed. */
+    SCAFFOLD_FILE_EXISTS: 'E152',
+    /** `harness new`: the directory create or file write itself failed (permissions, etc.). */
+    SCAFFOLD_WRITE_FAILED: 'E153',
+    /** `harness docs <id>`: no curated doc is registered under that id. */
+    DOC_NOT_FOUND: 'E160',
+    /** `harness skills install`: the underlying `npx skills add` pass-through failed (non-zero exit / spawn error). */
+    SKILLS_INSTALL_FAILED: 'E170',
+    /** `harness record <type>`: no such record type in the merged registry (core ∪ extension). */
+    RECORD_TYPE_UNKNOWN: 'E180',
+    /** `harness record <type>`: the records directory create or file write itself failed (permissions, etc.). */
+    RECORD_WRITE_FAILED: 'E181',
+    /** `harness init`: writing the governance-doc skeleton (`.harness/engineering-harness.md`) failed (permissions, etc.). */
+    INIT_WRITE_FAILED: 'E190',
+    /** `harness update`/`self-install`: the global npm install failed (generic / unclassified). */
+    UPDATE_FAILED: 'E200',
+    /** `harness update`/`self-install`: the npm registry rejected the install — unexpected auth on the public package (wrong registry / stale login), or it isn't published yet / the registry is unreachable. */
+    UPDATE_AUTH_FAILED: 'E201',
+    /** `harness update`/`self-install`: the global npm install was denied (filesystem permissions). */
+    UPDATE_PERMISSION_DENIED: 'E202',
+    /** `harness update`/`self-install`: npm was not found on PATH. */
+    UPDATE_NPM_MISSING: 'E203',
+    /** `harness update --pin`: the requested version is not published in the registry. */
+    UPDATE_VERSION_NOT_FOUND: 'E204',
+};
+//# sourceMappingURL=error-codes.js.map

package/harness/cli/dist/output/error-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.js","sourceRoot":"","sources":["../../src/output/error-codes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,0CAA0C;IAC1C,OAAO,EAAE,MAAM;IACf,wCAAwC;IACxC,YAAY,EAAE,MAAM;IACpB,uDAAuD;IACvD,cAAc,EAAE,MAAM;IACtB,iFAAiF;IACjF,mBAAmB,EAAE,MAAM;IAC3B,0HAA0H;IAC1H,qBAAqB,EAAE,MAAM;IAC7B,6HAA6H;IAC7H,uBAAuB,EAAE,MAAM;IAC/B,2FAA2F;IAC3F,uBAAuB,EAAE,MAAM;IAC/B,yIAAyI;IACzI,qBAAqB,EAAE,MAAM;IAC7B,4HAA4H;IAC5H,8BAA8B,EAAE,MAAM;IACtC,qGAAqG;IACrG,uBAAuB,EAAE,MAAM;IAC/B,0GAA0G;IAC1G,yBAAyB,EAAE,MAAM;IACjC,qGAAqG;IACrG,qBAAqB,EAAE,MAAM;IAC7B,+FAA+F;IAC/F,sBAAsB,EAAE,MAAM;IAC9B,4FAA4F;IAC5F,oBAAoB,EAAE,MAAM;IAC5B,2FAA2F;IAC3F,qBAAqB,EAAE,MAAM;IAC7B,uEAAuE;IACvE,aAAa,EAAE,MAAM;IACrB,mHAAmH;IACnH,qBAAqB,EAAE,MAAM;IAC7B,8FAA8F;IAC9F,mBAAmB,EAAE,MAAM;IAC3B,6GAA6G;IAC7G,mBAAmB,EAAE,MAAM;IAC3B,0HAA0H;IAC1H,iBAAiB,EAAE,MAAM;IACzB,+FAA+F;IAC/F,aAAa,EAAE,MAAM;IACrB,8MAA8M;IAC9M,kBAAkB,EAAE,MAAM;IAC1B,mGAAmG;IACnG,wBAAwB,EAAE,MAAM;IAChC,kEAAkE;IAClE,kBAAkB,EAAE,MAAM;IAC1B,sFAAsF;IACtF,wBAAwB,EAAE,MAAM;CACxB,CAAC"}

package/harness/cli/dist/output/exit.d.ts

@@ -0,0 +1,29 @@
+import type { Envelope } from './envelope.js';
+import type { OutputPort, Writers } from './output-port.js';
+export declare function exitCodeFor(env: Envelope): number;
+/**
+ * A decorator applied to every outgoing envelope at the single exit chokepoint,
+ * registered ONCE by the composition root (plan 019, T007). It may mutate the
+ * envelope (e.g. set the additive `update_available` field, which the JSON
+ * renderer then serializes) and/or write a side-channel line (e.g. the human-mode
+ * update banner to stderr).
+ *
+ * Centralising it here is deliberate (KF-09): `exitWithEnvelope` is the ONE path
+ * every command exits through (43 call sites), and the per-act bespoke human
+ * `{ emit }` ports bypass `renderHuman` — so decorating here is the only place
+ * that reaches EVERY command with zero per-site plumbing. Default null = no-op.
+ */
+export type BannerDecorator = (env: Envelope) => void;
+/** Register (or clear, with null) the exit-chokepoint banner decorator. */
+export declare function setBannerDecorator(decorator: BannerDecorator | null): void;
+/** Single exit point for the whole CLI — only the kernel calls process.exit. */
+export declare function exitWithEnvelope(env: Envelope, io: OutputPort): never;
+/**
+ * Verbatim passthrough exit: write raw text to stdout and let the process exit
+ * NATURALLY with `code` (0 by default) — set `process.exitCode` and return, never
+ * `process.exit`. A large raw payload (e.g. `harness docs <id>`) piped or
+ * redirected must not be truncated by an early `process.exit` that races the
+ * stdout flush; a natural return lets Node drain stdout first (companion F002).
+ * Envelope-bearing commands still use `exitWithEnvelope`.
+ */
+export declare function emitRawAndExit(text: string, writers: Writers, code?: number): void;

package/harness/cli/dist/output/exit.js

@@ -0,0 +1,36 @@
+/** Status → exit code (authoritative). Workshop 001 § Status → exit code mapping. */
+const EXIT_BY_STATUS = {
+    ok: 0,
+    degraded: 0,
+    unconfigured: 2,
+    error: 1,
+};
+export function exitCodeFor(env) {
+    return EXIT_BY_STATUS[env.status];
+}
+let bannerDecorator = null;
+/** Register (or clear, with null) the exit-chokepoint banner decorator. */
+export function setBannerDecorator(decorator) {
+    bannerDecorator = decorator;
+}
+/** Single exit point for the whole CLI — only the kernel calls process.exit. */
+export function exitWithEnvelope(env, io) {
+    // Decorate BEFORE emit so the JSON renderer serializes any field the decorator
+    // sets (e.g. update_available) and the human banner precedes the act's output.
+    bannerDecorator?.(env);
+    io.emit(env);
+    process.exit(exitCodeFor(env));
+}
+/**
+ * Verbatim passthrough exit: write raw text to stdout and let the process exit
+ * NATURALLY with `code` (0 by default) — set `process.exitCode` and return, never
+ * `process.exit`. A large raw payload (e.g. `harness docs <id>`) piped or
+ * redirected must not be truncated by an early `process.exit` that races the
+ * stdout flush; a natural return lets Node drain stdout first (companion F002).
+ * Envelope-bearing commands still use `exitWithEnvelope`.
+ */
+export function emitRawAndExit(text, writers, code = 0) {
+    writers.out(text);
+    process.exitCode = code;
+}
+//# sourceMappingURL=exit.js.map

package/harness/cli/dist/output/exit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit.js","sourceRoot":"","sources":["../../src/output/exit.ts"],"names":[],"mappings":"AAGA,qFAAqF;AACrF,MAAM,cAAc,GAA2B;IAC7C,EAAE,EAAE,CAAC;IACL,QAAQ,EAAE,CAAC;IACX,YAAY,EAAE,CAAC;IACf,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,GAAa;IACvC,OAAO,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC;AAgBD,IAAI,eAAe,GAA2B,IAAI,CAAC;AAEnD,2EAA2E;AAC3E,MAAM,UAAU,kBAAkB,CAAC,SAAiC;IAClE,eAAe,GAAG,SAAS,CAAC;AAC9B,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,gBAAgB,CAAC,GAAa,EAAE,EAAc;IAC5D,+EAA+E;IAC/E,+EAA+E;IAC/E,eAAe,EAAE,CAAC,GAAG,CAAC,CAAC;IACvB,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACb,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,OAAgB,EAAE,IAAI,GAAG,CAAC;IACrE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC"}

package/harness/cli/dist/output/output-port.d.ts

@@ -0,0 +1,54 @@
+import type { Envelope } from './envelope.js';
+/**
+ * The sink the kernel exits through. Concrete human/JSON renderers (output-port.ts
+ * § T008) implement this; defining it here keeps `exit.ts` free of renderer details.
+ */
+export interface OutputPort {
+    emit(env: Envelope): void;
+}
+export type OutputMode = 'json' | 'human';
+/**
+ * Resolved per-invocation I/O, computed ONCE by the entrypoint and threaded to
+ * acts. Acts must NOT re-derive the mode from `program.opts()` — commander
+ * collapses `--json`/`--no-json` to a boolean and loses the "flag absent" state
+ * that lets env/TTY decide. The entrypoint resolves it via `jsonFlag(argv)`.
+ */
+export interface CliIo {
+    mode: OutputMode;
+    writers: Writers;
+    /**
+     * Whether the hand-rolled `harness help` renderer should emit ANSI color.
+     * Resolved ONCE by the entrypoint (human + interactive TTY, minus NO_COLOR);
+     * optional so test call sites that omit it default to plain text. Commander's
+     * own `--help` does its own color detection and ignores this.
+     */
+    useColor?: boolean;
+}
+/**
+ * Where rendered text goes. Injected so renderers are unit-testable without
+ * touching real process streams.
+ */
+export interface Writers {
+    out(text: string): void;
+    err(text: string): void;
+}
+/** Default writers — the real process streams. */
+export declare const processWriters: Writers;
+/**
+ * Human-vs-JSON selection precedence (highest wins):
+ *   1. explicit --json / --no-json flag
+ *   2. HARNESS_JSON=1 env (CI, where TTY detection is unreliable)
+ *   3. TTY detection: piped (!isTty) => json, interactive => human
+ */
+export declare function selectMode(flags: {
+    json?: boolean;
+}, env: NodeJS.ProcessEnv, isTty: boolean): OutputMode;
+/** JSON renderer — one parseable line to stdout. */
+export declare function renderJson(env: Envelope, writers?: Writers): void;
+/**
+ * Human renderer — progress/diagnostics (here, the next_action) go to stderr;
+ * the final one-line summary goes to stdout (so `harness ... | …` pipes the summary).
+ */
+export declare function renderHuman(env: Envelope, writers?: Writers): void;
+/** Build an OutputPort for a selected mode. */
+export declare function createOutputPort(mode: OutputMode, writers?: Writers): OutputPort;