@ai-substrate/engineering-harness 0.2.0-canary.45

package/harness/cli/dist/services/extensions/verb-context.js

@@ -0,0 +1,97 @@
+import { formatDegraded, formatError, formatOk, formatUnconfigured, } from '../../output/envelope.js';
+import { ErrorCodes } from '../../output/error-codes.js';
+/**
+ * Build the `VerbContext` an author's handler receives. Surfaces the injected
+ * ports (read-mostly) + envelope-helper closures so a verb never imports the
+ * kernel. `ctx.exec` adapts the author-facing signature (optional args + cwd) to
+ * `ExecPort.run`, defaulting cwd to the invocation cwd (WS-A Decision 3).
+ */
+export function buildVerbContext(deps, invocation) {
+    return {
+        cwd: invocation.cwd,
+        args: invocation.args,
+        options: invocation.options,
+        exec: (command, args = [], opts) => deps.exec.run(command, args, { cwd: opts?.cwd ?? invocation.cwd }),
+        fs: deps.fs,
+        env: deps.env,
+        git: deps.git,
+        clock: deps.clock,
+        ok: (data, opts) => ({
+            status: 'ok',
+            data,
+            ...(opts?.evidence && { evidence: opts.evidence }),
+            ...(opts?.next_action && { next_action: opts.next_action }),
+        }),
+        degraded: (data, next_action, opts) => ({
+            status: 'degraded',
+            data,
+            next_action,
+            ...(opts?.evidence && { evidence: opts.evidence }),
+        }),
+        unconfigured: (next_action, opts) => ({
+            status: 'unconfigured',
+            next_action,
+            ...(opts?.data !== undefined && { data: opts.data }),
+        }),
+        error: (code, message, opts) => ({
+            status: 'error',
+            error: { code, message, ...(opts?.details !== undefined && { details: opts.details }) },
+            next_action: opts?.next_action ?? message,
+        }),
+    };
+}
+/** Treat empty/whitespace-only strings as absent so a blank value can't satisfy P5. */
+function nonBlank(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+/**
+ * Finalize what a handler RETURNED into a canonical Envelope: the kernel adds
+ * `command` (the verb name) + `timestamp` (from the clock) and maps status →
+ * the right constructor, guaranteeing a non-blank `next_action` on every non-`ok`
+ * status (P5) even if the author returned a raw object without one — a blank or
+ * whitespace-only `next_action` is treated as missing. A JS extension that returns
+ * an unknown `status` (outside the typed union) is mapped to an `E141` error
+ * Envelope rather than falling through to `undefined`.
+ */
+export function finalizeVerbResult(result, name, clock) {
+    switch (result.status) {
+        case 'ok':
+            return formatOk(name, result.data, clock, {
+                ...(result.evidence && { evidence: result.evidence }),
+                ...(nonBlank(result.next_action) && { next_action: result.next_action }),
+            });
+        case 'degraded':
+            return formatDegraded(name, result.data, nonBlank(result.next_action) ?? 'Review the degraded result above.', clock, result.evidence ? { evidence: result.evidence } : undefined);
+        case 'unconfigured':
+            return formatUnconfigured(name, nonBlank(result.next_action) ?? 'No behaviour is mapped for this verb yet.', clock, result.data !== undefined ? { data: result.data } : undefined);
+        case 'error': {
+            const message = nonBlank(result.error?.message) ?? 'The verb reported an error.';
+            return formatError(name, result.error?.code ?? ErrorCodes.UNKNOWN, message, clock, {
+                ...(result.error?.details !== undefined && { details: result.error.details }),
+                next_action: nonBlank(result.next_action) ?? message,
+            });
+        }
+        default:
+            return formatError(name, ErrorCodes.EXTENSION_RUNTIME_ERROR, `Verb '${name}' returned an invalid status '${String(result.status)}'.`, clock, {
+                next_action: `This is a bug in the extension; a verb must return one of ok/degraded/unconfigured/error. Fix or remove the extension providing '${name}'.`,
+            });
+    }
+}
+/**
+ * Invoke a verb's handler with isolation: a returned `VerbResult` is finalized;
+ * a thrown error becomes an `E141` error Envelope surfacing the message (never a
+ * raw stack trace — honesty, AC-style). Awaits async handlers.
+ */
+export async function runVerb(verb, ctx, clock) {
+    try {
+        const result = await verb.run(ctx);
+        return finalizeVerbResult(result, verb.name, clock);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return formatError(verb.name, ErrorCodes.EXTENSION_RUNTIME_ERROR, `Verb '${verb.name}' threw at runtime: ${message}`, clock, {
+            next_action: `This is a bug in the extension; fix or remove the extension providing '${verb.name}'.`,
+        });
+    }
+}
+//# sourceMappingURL=verb-context.js.map

package/harness/cli/dist/services/extensions/verb-context.js.map

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

package/harness/cli/dist/services/help/help-service.d.ts

@@ -0,0 +1,42 @@
+import type { FsPort } from '../../adapters/fs/fs-port.js';
+import type { VerbRegistry } from '../extensions/registry.js';
+/** Machine-readable per-verb summary surfaced by `help` (AC-1/AC-6). */
+export interface VerbSummary {
+    name: string;
+    summary: string;
+    status: 'loaded';
+    /** True when the verb's extension folder carries an `instructions.md` briefing (plan 014 AC-4). */
+    has_instructions: boolean;
+}
+/** The full help payload — human-rendered as text, JSON-rendered as an envelope `data`. */
+export interface HelpContent {
+    purpose: string;
+    /** The agent's first hop: where to self-brief (plan 014 AC-4). */
+    agents_start_here: string;
+    output_modes: string[];
+    exit_codes: Record<string, string>;
+    safe_first_actions: string[];
+    verbs: VerbSummary[];
+    extensions: {
+        installed: number;
+        failed: number;
+        conflicts: number;
+    };
+}
+/**
+ * Build the help payload from the assembled verb registry. The `FsPort` is used
+ * ONLY for per-verb `instructions.md` existence probes at help-build time (plan
+ * 014 D4) — no content is read here.
+ */
+export declare function buildHelp(registry: VerbRegistry, fs: FsPort): HelpContent;
+/** The honest "no extensions installed yet" next_action, or undefined when verbs exist. */
+export declare function helpEmptyHint(content: HelpContent): string | undefined;
+/**
+ * Render the help payload as human-readable text (pure — returns a string).
+ * Core commands and contributed verbs print under SEPARATE headings (`Commands:`
+ * vs `Extensions:`) so the dynamic, extension-owned surface is visually distinct
+ * from the fixed core. `useColor` accents the headings (cyan core / green
+ * extensions) + dims descriptions; it defaults off so non-interactive callers
+ * (and tests) get plain text. The entrypoint resolves it from human + TTY state.
+ */
+export declare function renderHelpText(content: HelpContent, useColor?: boolean): string;

package/harness/cli/dist/services/help/help-service.js

@@ -0,0 +1,108 @@
+import { helpPalette } from '../../output/style.js';
+import { instructionsPathFor } from '../instructions/instructions-service.js';
+const PURPOSE = "The agent-friendly front door to this repo's engineering harness. " +
+    'Verbs are owned by extensions: each is a little package at `./.harness/extensions/<name>/` ' +
+    '(entry `extension.ts`, briefing `instructions.md`) and becomes a `harness <verb>` command. ' +
+    '`help`, `doctor`, `new`, `docs`, `skills`, `record`, and `instructions` are always available.';
+const AGENTS_START_HERE = 'npx harness instructions — the agent briefing (then `harness instructions <verb>` per verb)';
+const OUTPUT_MODES = [
+    '--json forces JSON output',
+    '--no-json forces human output',
+    'HARNESS_JSON=1 forces JSON (useful in CI)',
+    'otherwise: piped output → JSON, an interactive TTY → human',
+];
+const EXIT_CODES = {
+    '0': 'ok or degraded (the command reported successfully)',
+    '1': 'error (something failed; see error.code + next_action)',
+    '2': 'unconfigured (no behaviour mapped to this verb yet)',
+};
+const EMPTY_HINT = 'No extensions installed yet. Run `harness new <name>` to scaffold one into ' +
+    '`./.harness/extensions/<name>/` (entry `extension.ts` + briefing `instructions.md`). See the authoring guide.';
+/**
+ * Build the help payload from the assembled verb registry. The `FsPort` is used
+ * ONLY for per-verb `instructions.md` existence probes at help-build time (plan
+ * 014 D4) — no content is read here.
+ */
+export function buildHelp(registry, fs) {
+    const installed = registry.records.filter((r) => r.status === 'loaded').length;
+    const failed = registry.records.filter((r) => r.status === 'failed').length;
+    const conflicts = registry.records.filter((r) => r.status === 'conflict').length;
+    const safeFirstActions = [
+        'harness instructions — the agent briefing (AGENTS START HERE)',
+        'harness doctor — see which extensions loaded (and any that failed)',
+        'harness docs — list the bundled docs (then `harness docs <id>` to read one)',
+        'harness new <name> — scaffold a new extension (add --wrap "<cmd>" to wrap a real command)',
+        "harness skills install --target <cli> — install this harness's skills into your CLI",
+        'harness help --json — the machine-readable verb list',
+    ];
+    if (registry.verbs.length > 0) {
+        safeFirstActions.push(`harness ${registry.verbs[0]?.name} --help — usage for a contributed verb`);
+    }
+    return {
+        purpose: PURPOSE,
+        agents_start_here: AGENTS_START_HERE,
+        output_modes: OUTPUT_MODES,
+        exit_codes: EXIT_CODES,
+        safe_first_actions: safeFirstActions,
+        verbs: registry.verbs.map((verb) => {
+            const briefingPath = instructionsPathFor(verb.name, registry);
+            return {
+                name: verb.name,
+                summary: verb.summary,
+                status: 'loaded',
+                has_instructions: briefingPath !== null && fs.exists(briefingPath),
+            };
+        }),
+        extensions: { installed, failed, conflicts },
+    };
+}
+/** The honest "no extensions installed yet" next_action, or undefined when verbs exist. */
+export function helpEmptyHint(content) {
+    return content.verbs.length === 0 ? EMPTY_HINT : undefined;
+}
+/**
+ * Render the help payload as human-readable text (pure — returns a string).
+ * Core commands and contributed verbs print under SEPARATE headings (`Commands:`
+ * vs `Extensions:`) so the dynamic, extension-owned surface is visually distinct
+ * from the fixed core. `useColor` accents the headings (cyan core / green
+ * extensions) + dims descriptions; it defaults off so non-interactive callers
+ * (and tests) get plain text. The entrypoint resolves it from human + TTY state.
+ */
+export function renderHelpText(content, useColor = false) {
+    const c = helpPalette(useColor);
+    const lines = [];
+    lines.push('▶ AGENTS START HERE: npx harness instructions (the agent briefing)', '');
+    lines.push('harness — engineering harness front door', '', content.purpose, '');
+    lines.push(c.heading('Commands:'));
+    lines.push(`  help                ${c.dim('explain the harness (this output)')}`);
+    lines.push(`  doctor              ${c.dim('report what is configured + which extensions loaded')}`);
+    lines.push(`  instructions [verb] ${c.dim("the agent briefing (core, or one verb's instructions.md)")}`);
+    lines.push(`  new <name>          ${c.dim('scaffold a new extension into ./.harness/extensions/<name>/')}`);
+    lines.push(`  docs [id]           ${c.dim('list the bundled docs, or print one by id')}`);
+    lines.push('', c.extHeading('Extensions:'));
+    if (content.verbs.length === 0) {
+        lines.push('  (no extensions installed yet)');
+    }
+    for (const verb of content.verbs) {
+        const briefing = verb.has_instructions ? ' 📖' : '';
+        lines.push(`  ${verb.name.padEnd(18)}${c.dim(verb.summary)}${briefing}`);
+    }
+    const { failed, conflicts } = content.extensions;
+    if (failed > 0 || conflicts > 0) {
+        lines.push('', `⚠ ${failed} failed, ${conflicts} conflict(s) — run \`harness doctor\`.`);
+    }
+    lines.push('', c.heading('Output modes:'));
+    for (const mode of content.output_modes) {
+        lines.push(`  - ${mode}`);
+    }
+    lines.push('', c.heading('Exit codes:'));
+    for (const [code, meaning] of Object.entries(content.exit_codes)) {
+        lines.push(`  ${code}  ${meaning}`);
+    }
+    lines.push('', c.heading('Safe first actions:'));
+    for (const action of content.safe_first_actions) {
+        lines.push(`  - ${action}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=help-service.js.map

package/harness/cli/dist/services/help/help-service.js.map

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

package/harness/cli/dist/services/init/governance-template.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The governance-doc skeleton `harness init` stamps. An inline TypeScript string
+ * constant (mirroring `services/record/core-types/retro.ts` → `RETRO_TEMPLATE`
+ * and `services/scaffold/templates.ts`): it compiles into `dist/` and ships via
+ * the existing `files: ["harness/cli/bin","harness/cli/dist","LICENSE"]` glob —
+ * no `package.json`/build/`gen:docs` change, no runtime file read.
+ *
+ * Scaffold-and-seed ONLY. The skeleton's section set + order mirror the canonical
+ * governance doc (`skills/eng-harness-loop/eng-harness-flow/references/governance-doc.md`
+ * and this repo's own `.harness/engineering-harness.md`) so its runtime readers —
+ * boot (maturity), `eng-harness-0-adopt` (the `## Injection map`), and the
+ * router's S3 rung — recognise it as a real governance doc. Every repo-specific
+ * field is a `TODO`/empty placeholder and maturity is seeded `L0`: a
+ * populated-but-false doc would make boot misreport and violates "the harness
+ * never fakes success". Emptiness here is correctness — the skills and the
+ * Improve beat fill the body.
+ *
+ * This module is intentionally I/O-free (zero imports): the act owns the fs
+ * side-effects via the injected `fs` port, never the builder (Constitution P2).
+ */
+export declare const GOVERNANCE_SKELETON = "# Engineering harness\n\n> **AGENTS START HERE \u2192 `npx --no-install harness instructions`** \u2014 the CLI's\n> baked agent briefing (envelope contract, role split, discovery loop). Then\n> `npx --no-install harness instructions <verb>` per verb.\n\n## Boot command\n<!-- TODO (eng-harness-0-adopt / `harness new boot --wrap \"<cmd>\"`):\n     the exact command that boots the system to a healthy, observable state (<60s target). -->\n\n## Health check\n<!-- TODO: the command/endpoint that proves the system is up (read by boot Stage 1). -->\n\n## Interact method\n<!-- TODO: how an agent sends input to the running system (boot Stage 2). -->\n\n## Observe method\n<!-- TODO: how an agent captures evidence \u2014 logs, screenshots, traces (boot Stage 3). -->\n\n## Deterministic signal inventory\n<!-- TODO: sensors that prove behaviour without inference \u2014 runtime inspectability,\n     smoke paths, architecture/static checks, security/dependency/schema checks. -->\n\n## Evidence paths\n<!-- TODO: where artifacts land (log/trace/screenshot/output locations). -->\n\n## Injection map\n<!-- Where the repo's extant dev/SDD flow calls /eng-harness-flow. One row per seam.\n     Filled by eng-harness-0-adopt Step 3 (with the user's go-ahead). -->\n\n| Seam event | Fires from | What fires it |\n|---|---|---|\n| <!-- e.g. session-start --> | | |\n\n## Back-pressure gaps\n<!-- TODO: behaviours still relying on inference/human eyeballing \u2014 improvement\n     candidates, named honestly. Never scores. -->\n\n## Current maturity snapshot\n**L0 \u2014 seeded at inception by `harness init`; nothing proven yet.**\n<!-- The single, current L0\u2013L4 level the harness is ACTUALLY at. Updated ONLY at\n     the Improve beat (never by boot, which is read-only). See maturity-assessment.md. -->\n";
+/**
+ * The governance-doc skeleton `harness init` writes. Pure — no fs/clock/process
+ * access — so it is unit-testable by snapshot and stays a deterministic "copy in
+ * a template". Repo-specific content is the skills' / Improve beat's job.
+ */
+export declare function buildGovernanceSkeleton(): string;

package/harness/cli/dist/services/init/governance-template.js

@@ -0,0 +1,72 @@
+/**
+ * The governance-doc skeleton `harness init` stamps. An inline TypeScript string
+ * constant (mirroring `services/record/core-types/retro.ts` → `RETRO_TEMPLATE`
+ * and `services/scaffold/templates.ts`): it compiles into `dist/` and ships via
+ * the existing `files: ["harness/cli/bin","harness/cli/dist","LICENSE"]` glob —
+ * no `package.json`/build/`gen:docs` change, no runtime file read.
+ *
+ * Scaffold-and-seed ONLY. The skeleton's section set + order mirror the canonical
+ * governance doc (`skills/eng-harness-loop/eng-harness-flow/references/governance-doc.md`
+ * and this repo's own `.harness/engineering-harness.md`) so its runtime readers —
+ * boot (maturity), `eng-harness-0-adopt` (the `## Injection map`), and the
+ * router's S3 rung — recognise it as a real governance doc. Every repo-specific
+ * field is a `TODO`/empty placeholder and maturity is seeded `L0`: a
+ * populated-but-false doc would make boot misreport and violates "the harness
+ * never fakes success". Emptiness here is correctness — the skills and the
+ * Improve beat fill the body.
+ *
+ * This module is intentionally I/O-free (zero imports): the act owns the fs
+ * side-effects via the injected `fs` port, never the builder (Constitution P2).
+ */
+export const GOVERNANCE_SKELETON = `# Engineering harness
+
+> **AGENTS START HERE → \`npx --no-install harness instructions\`** — the CLI's
+> baked agent briefing (envelope contract, role split, discovery loop). Then
+> \`npx --no-install harness instructions <verb>\` per verb.
+
+## Boot command
+<!-- TODO (eng-harness-0-adopt / \`harness new boot --wrap "<cmd>"\`):
+     the exact command that boots the system to a healthy, observable state (<60s target). -->
+
+## Health check
+<!-- TODO: the command/endpoint that proves the system is up (read by boot Stage 1). -->
+
+## Interact method
+<!-- TODO: how an agent sends input to the running system (boot Stage 2). -->
+
+## Observe method
+<!-- TODO: how an agent captures evidence — logs, screenshots, traces (boot Stage 3). -->
+
+## Deterministic signal inventory
+<!-- TODO: sensors that prove behaviour without inference — runtime inspectability,
+     smoke paths, architecture/static checks, security/dependency/schema checks. -->
+
+## Evidence paths
+<!-- TODO: where artifacts land (log/trace/screenshot/output locations). -->
+
+## Injection map
+<!-- Where the repo's extant dev/SDD flow calls /eng-harness-flow. One row per seam.
+     Filled by eng-harness-0-adopt Step 3 (with the user's go-ahead). -->
+
+| Seam event | Fires from | What fires it |
+|---|---|---|
+| <!-- e.g. session-start --> | | |
+
+## Back-pressure gaps
+<!-- TODO: behaviours still relying on inference/human eyeballing — improvement
+     candidates, named honestly. Never scores. -->
+
+## Current maturity snapshot
+**L0 — seeded at inception by \`harness init\`; nothing proven yet.**
+<!-- The single, current L0–L4 level the harness is ACTUALLY at. Updated ONLY at
+     the Improve beat (never by boot, which is read-only). See maturity-assessment.md. -->
+`;
+/**
+ * The governance-doc skeleton `harness init` writes. Pure — no fs/clock/process
+ * access — so it is unit-testable by snapshot and stays a deterministic "copy in
+ * a template". Repo-specific content is the skills' / Improve beat's job.
+ */
+export function buildGovernanceSkeleton() {
+    return GOVERNANCE_SKELETON;
+}
+//# sourceMappingURL=governance-template.js.map

package/harness/cli/dist/services/init/governance-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"governance-template.js","sourceRoot":"","sources":["../../../src/services/init/governance-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0ClC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,mBAAmB,CAAC;AAC7B,CAAC"}

package/harness/cli/dist/services/init/init-service.d.ts

@@ -0,0 +1,38 @@
+import type { FsPort } from '../../adapters/fs/fs-port.js';
+import type { ProcessPort } from '../../adapters/process/process-port.js';
+/** The governance doc's fixed filename inside `.harness/` (singleton — no date, no slug). */
+export declare const GOVERNANCE_DOC = "engineering-harness.md";
+/**
+ * Ports the init service needs: `fs` for the side-effects, `proc` to resolve the
+ * repo root. No Clock — the skeleton is static and the path is fixed.
+ */
+export interface InitDeps {
+    fs: FsPort;
+    proc: ProcessPort;
+}
+/**
+ * Outcome of seeding the governance doc. `created` distinguishes a fresh stamp
+ * (`true`) from an idempotent no-op on an existing doc (`false`); the act maps
+ * this onto the Envelope + exit code (ok → 0, error → 1).
+ */
+export type InitOutcome = {
+    ok: true;
+    path: string;
+    created: boolean;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+    next_action: string;
+};
+/**
+ * Seed `.harness/engineering-harness.md` with the governance-doc skeleton — the
+ * Inception write-condition (governance-doc.md G5). This is the INCEPTION writer,
+ * so it bootstraps `.harness/` itself (unlike `record`, which returns
+ * `unconfigured` when `.harness/` is absent). Idempotent + NEVER-CLOBBER: the
+ * exists-check runs FIRST, and an existing doc is left byte-identical and
+ * reported `created:false` (it holds the real maturity + injection map by then).
+ * Side-effects go through the injected `fs` port; the pure skeleton comes from
+ * the builder (Constitution P2 — no `node:fs` in services).
+ */
+export declare function initGovernance(deps: InitDeps): InitOutcome;

package/harness/cli/dist/services/init/init-service.js

@@ -0,0 +1,44 @@
+import { ErrorCodes } from '../../output/error-codes.js';
+import { posixJoin, toPosix } from '../shared/posix-path.js';
+import { HARNESS_DIR } from '../shared/temp.js';
+import { buildGovernanceSkeleton } from './governance-template.js';
+/** The governance doc's fixed filename inside `.harness/` (singleton — no date, no slug). */
+export const GOVERNANCE_DOC = 'engineering-harness.md';
+/**
+ * Seed `.harness/engineering-harness.md` with the governance-doc skeleton — the
+ * Inception write-condition (governance-doc.md G5). This is the INCEPTION writer,
+ * so it bootstraps `.harness/` itself (unlike `record`, which returns
+ * `unconfigured` when `.harness/` is absent). Idempotent + NEVER-CLOBBER: the
+ * exists-check runs FIRST, and an existing doc is left byte-identical and
+ * reported `created:false` (it holds the real maturity + injection map by then).
+ * Side-effects go through the injected `fs` port; the pure skeleton comes from
+ * the builder (Constitution P2 — no `node:fs` in services).
+ */
+export function initGovernance(deps) {
+    const { fs, proc } = deps;
+    // Logical paths are POSIX on every OS (plan 017) — convert once at the boundary.
+    const cwd = toPosix(proc.cwd());
+    const harnessDir = posixJoin(cwd, HARNESS_DIR);
+    const fileAbs = posixJoin(harnessDir, GOVERNANCE_DOC);
+    const relPath = posixJoin(HARNESS_DIR, GOVERNANCE_DOC);
+    // Never clobber: exists-check FIRST — skip mkdirp+write entirely on a hit.
+    if (fs.exists(fileAbs)) {
+        return { ok: true, path: relPath, created: false };
+    }
+    // Absent → bootstrap `.harness/` then stamp the skeleton, both under ONE guard
+    // so a permissions failure surfaces as E190 (not a generic E100).
+    try {
+        fs.mkdirp(harnessDir);
+        fs.writeText(fileAbs, buildGovernanceSkeleton());
+    }
+    catch (err) {
+        return {
+            ok: false,
+            code: ErrorCodes.INIT_WRITE_FAILED,
+            message: `Could not write ${relPath}: ${err instanceof Error ? err.message : String(err)}`,
+            next_action: `Could not write \`${relPath}\` (permissions?). Check the repo root is writable.`,
+        };
+    }
+    return { ok: true, path: relPath, created: true };
+}
+//# sourceMappingURL=init-service.js.map

package/harness/cli/dist/services/init/init-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-service.js","sourceRoot":"","sources":["../../../src/services/init/init-service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,6FAA6F;AAC7F,MAAM,CAAC,MAAM,cAAc,GAAG,wBAAwB,CAAC;AAoBvD;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAc;IAC3C,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IAC1B,iFAAiF;IACjF,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAChC,MAAM,UAAU,GAAG,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,SAAS,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,SAAS,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IAEvD,2EAA2E;IAC3E,IAAI,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACrD,CAAC;IAED,+EAA+E;IAC/E,kEAAkE;IAClE,IAAI,CAAC;QACH,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACtB,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,uBAAuB,EAAE,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,UAAU,CAAC,iBAAiB;YAClC,OAAO,EAAE,mBAAmB,OAAO,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;YAC1F,WAAW,EAAE,qBAAqB,OAAO,qDAAqD;SAC/F,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACpD,CAAC"}

package/harness/cli/dist/services/instructions/core-instructions.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The baked CORE agent briefing surfaced by bare `harness instructions` (plan
+ * 014 AC-1). A TS constant on purpose: it documents the CLI's own contract, so
+ * it should version with the CLI binary (plan § Accepted assumptions) — unlike
+ * per-extension briefings, which live beside their extension as
+ * `.harness/extensions/<name>/instructions.md` and are read from disk at every
+ * invocation.
+ *
+ * Audience: the CALLING agent (not minih workers, not humans skimming docs).
+ */
+export declare const CORE_INSTRUCTIONS = "# Harness CLI \u2014 agent briefing\n\nAGENTS START HERE. You are an agent operating this repository through its\nengineering harness. Division of labour: **the harness brings determinism,\nyou bring the inference.** Verbs compute repeatable facts (run suites, collect\nevidence, scaffold files); these instructions \u2014 and each verb's own briefing \u2014\ntell you the role you play around those facts and the judgment expected back.\n\nWhy this surface exists: the harness is the **focal point of the repo's\ndeterministic layer** \u2014 the one discoverable place where proof lives (build,\ntest, boot, sensors, evidence) instead of diffuse scripts and tribal\nknowledge. The deal that makes it compound: **encode, don't document** \u2014 if\nyou had to infer something twice, that is a missing command, not a missing\ndoc; propose it as a one-line observation (\u00A7 Friction capture, below).\nDiscoverability is the point: `--help`, `doctor`, and these briefings exist\nso the layer can be enumerated, not remembered.\n\n## The envelope contract\n\nEvery command emits ONE envelope. Pass `--json` to get it machine-readable:\n\n  { \"command\", \"status\", \"data\", \"error?\", \"next_action?\", \"timestamp\" }\n\n- `status` is one of: `ok` | `degraded` | `unconfigured` | `error`.\n- Exit codes: 0 = ok/degraded \u00B7 2 = unconfigured \u00B7 1 = error.\n- `next_action` is REQUIRED on any non-ok status \u2014 it is the prescribed fix.\n  Follow it before improvising.\n- The harness never fakes success: `unconfigured` means \"nothing is mapped\n  here yet\", not \"it worked\".\n\n## Self-briefing loop (one hop each)\n\n1. `harness help --json` \u2014 the verb map; each verb carries\n   `has_instructions` so you know which briefings exist.\n2. `harness doctor --json` \u2014 what loaded, what failed, and why (per-extension\n   provenance; convention complaints; every complaint has a next_action).\n3. `harness instructions <verb>` \u2014 read a verb's briefing BEFORE using it.\n   It states what the verb computes deterministically and what judgment it\n   expects back from you.\n\n## Friction capture (observe as you work)\n\nNotice friction while you work? Capture it the moment it happens \u2014 one\ncommand, no path/ID/timestamp bookkeeping, and it survives context\ncompaction (the buffer lives on disk):\n\n  harness observe \"<what happened, 10+ chars>\" --kind difficulty --severity degrading\n\n- Kinds: difficulty | magic-wand | gift | insight | coordination |\n  improvement-suggestion | confusion. Severities: blocking | degrading |\n  annoying. `--target`, `--workaround`, `--suggested-encoding` optional.\n- Identity is optional: `--agent <slug>` \u2192 `HARNESS_AGENT` env \u2192 a shared\n  `agent` bucket. Capture never fails on identity.\n- Two storage classes: `.harness/records/` is COMMITTED team memory;\n  `.harness/temp/` is TRANSIENT session scratch \u2014 gitignored, never\n  committed (capture and `harness record` calls self-heal the protection;\n  `harness doctor` checks it).\n- Drain at session end: `harness observe --list --json` sweeps all buckets \u2192\n  save what matters via `harness record retro` (use the returned\n  `data.path`) \u2192 `harness observe --clear`.\n\n## Where briefings live\n\nEach extension is a little package: `.harness/extensions/<name>/` with\n`extension.ts` (the verb code) and `instructions.md` (the briefing you are\nreading the equivalent of now). Briefings are loaded from disk at every\ninvocation \u2014 edits are live on the next call, no rebuild. Multi-verb\nextensions share their folder's single briefing.\n";

package/harness/cli/dist/services/instructions/core-instructions.js

@@ -0,0 +1,80 @@
+/**
+ * The baked CORE agent briefing surfaced by bare `harness instructions` (plan
+ * 014 AC-1). A TS constant on purpose: it documents the CLI's own contract, so
+ * it should version with the CLI binary (plan § Accepted assumptions) — unlike
+ * per-extension briefings, which live beside their extension as
+ * `.harness/extensions/<name>/instructions.md` and are read from disk at every
+ * invocation.
+ *
+ * Audience: the CALLING agent (not minih workers, not humans skimming docs).
+ */
+export const CORE_INSTRUCTIONS = `# Harness CLI — agent briefing
+
+AGENTS START HERE. You are an agent operating this repository through its
+engineering harness. Division of labour: **the harness brings determinism,
+you bring the inference.** Verbs compute repeatable facts (run suites, collect
+evidence, scaffold files); these instructions — and each verb's own briefing —
+tell you the role you play around those facts and the judgment expected back.
+
+Why this surface exists: the harness is the **focal point of the repo's
+deterministic layer** — the one discoverable place where proof lives (build,
+test, boot, sensors, evidence) instead of diffuse scripts and tribal
+knowledge. The deal that makes it compound: **encode, don't document** — if
+you had to infer something twice, that is a missing command, not a missing
+doc; propose it as a one-line observation (§ Friction capture, below).
+Discoverability is the point: \`--help\`, \`doctor\`, and these briefings exist
+so the layer can be enumerated, not remembered.
+
+## The envelope contract
+
+Every command emits ONE envelope. Pass \`--json\` to get it machine-readable:
+
+  { "command", "status", "data", "error?", "next_action?", "timestamp" }
+
+- \`status\` is one of: \`ok\` | \`degraded\` | \`unconfigured\` | \`error\`.
+- Exit codes: 0 = ok/degraded · 2 = unconfigured · 1 = error.
+- \`next_action\` is REQUIRED on any non-ok status — it is the prescribed fix.
+  Follow it before improvising.
+- The harness never fakes success: \`unconfigured\` means "nothing is mapped
+  here yet", not "it worked".
+
+## Self-briefing loop (one hop each)
+
+1. \`harness help --json\` — the verb map; each verb carries
+   \`has_instructions\` so you know which briefings exist.
+2. \`harness doctor --json\` — what loaded, what failed, and why (per-extension
+   provenance; convention complaints; every complaint has a next_action).
+3. \`harness instructions <verb>\` — read a verb's briefing BEFORE using it.
+   It states what the verb computes deterministically and what judgment it
+   expects back from you.
+
+## Friction capture (observe as you work)
+
+Notice friction while you work? Capture it the moment it happens — one
+command, no path/ID/timestamp bookkeeping, and it survives context
+compaction (the buffer lives on disk):
+
+  harness observe "<what happened, 10+ chars>" --kind difficulty --severity degrading
+
+- Kinds: difficulty | magic-wand | gift | insight | coordination |
+  improvement-suggestion | confusion. Severities: blocking | degrading |
+  annoying. \`--target\`, \`--workaround\`, \`--suggested-encoding\` optional.
+- Identity is optional: \`--agent <slug>\` → \`HARNESS_AGENT\` env → a shared
+  \`agent\` bucket. Capture never fails on identity.
+- Two storage classes: \`.harness/records/\` is COMMITTED team memory;
+  \`.harness/temp/\` is TRANSIENT session scratch — gitignored, never
+  committed (capture and \`harness record\` calls self-heal the protection;
+  \`harness doctor\` checks it).
+- Drain at session end: \`harness observe --list --json\` sweeps all buckets →
+  save what matters via \`harness record retro\` (use the returned
+  \`data.path\`) → \`harness observe --clear\`.
+
+## Where briefings live
+
+Each extension is a little package: \`.harness/extensions/<name>/\` with
+\`extension.ts\` (the verb code) and \`instructions.md\` (the briefing you are
+reading the equivalent of now). Briefings are loaded from disk at every
+invocation — edits are live on the next call, no rebuild. Multi-verb
+extensions share their folder's single briefing.
+`;
+//# sourceMappingURL=core-instructions.js.map

package/harness/cli/dist/services/instructions/core-instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-instructions.js","sourceRoot":"","sources":["../../../src/services/instructions/core-instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoEhC,CAAC"}

package/harness/cli/dist/services/instructions/instructions-service.d.ts

@@ -0,0 +1,52 @@
+import type { FsPort } from '../../adapters/fs/fs-port.js';
+import type { VerbRegistry } from '../extensions/registry.js';
+/** The bare `harness instructions` payload (plan 014 AC-1). */
+export interface CoreInstructionsPayload {
+    /** The baked core agent briefing (a TS constant — versions with the CLI). */
+    instructions: string;
+    /** Verbs whose owning extension folder carries an `instructions.md` right now. */
+    verbs_with_instructions: string[];
+}
+/**
+ * What `harness instructions <verb>` resolves to. The act maps these onto the
+ * envelope per D3: `ok` → ok/0, `unknown-verb`/`missing` → unconfigured/2 (gap
+ * semantics, no error code), `unreadable` → error E145/1.
+ */
+export type VerbInstructionsOutcome = {
+    kind: 'ok';
+    verb: string;
+    path: string;
+    instructions: string;
+} | {
+    kind: 'unknown-verb';
+    verb: string;
+} | {
+    kind: 'missing';
+    verb: string;
+    path: string;
+} | {
+    kind: 'unreadable';
+    verb: string;
+    path: string;
+};
+/**
+ * Verb → briefing path (plan 014 D5): find the record whose accepted `verbs[]`
+ * contains the verb, take `dirname(entryPath)`, join `instructions.md`. The
+ * contract stays untouched — no `instructions` field anywhere — and multi-verb
+ * extensions share their folder's single file for free. `null` = unknown verb.
+ */
+export declare function instructionsPathFor(verbName: string, registry: VerbRegistry): string | null;
+/**
+ * Build the bare-invocation payload. `verbs_with_instructions` is an `FsPort`
+ * existence probe per registered verb at build time (D4) — cheap, and honest
+ * about what is queryable right now.
+ */
+export declare function buildCoreInstructions(registry: VerbRegistry, fs: FsPort): CoreInstructionsPayload;
+/**
+ * Load a verb's briefing from disk NOW (D4 — lazily at invocation, never cached
+ * across calls, so an edit is visible on the next invocation with no rebuild).
+ * FsPort semantics make the missing/unreadable split: `exists()` false → the
+ * file was never authored (a gap); `exists()` true but `readText()` null → it
+ * is there but unreadable (a fault).
+ */
+export declare function loadVerbInstructions(verbName: string, registry: VerbRegistry, fs: FsPort): VerbInstructionsOutcome;