@ai-substrate/engineering-harness 0.2.0

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

@@ -0,0 +1,53 @@
+import { posixDirname, posixJoin } from '../shared/posix-path.js';
+import { CORE_INSTRUCTIONS } from './core-instructions.js';
+/**
+ * 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 function instructionsPathFor(verbName, registry) {
+    const record = registry.records.find((r) => r.verbs.some((v) => v.name === verbName));
+    if (record === undefined) {
+        return null;
+    }
+    // entryPath is POSIX from discovery (plan 017) — derive in POSIX space so the
+    // surfaced briefing path stays forward-slash on every OS.
+    return posixJoin(posixDirname(record.entryPath), 'instructions.md');
+}
+/**
+ * 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 function buildCoreInstructions(registry, fs) {
+    const verbs_with_instructions = registry.verbs
+        .filter((verb) => {
+        const path = instructionsPathFor(verb.name, registry);
+        return path !== null && fs.exists(path);
+    })
+        .map((verb) => verb.name);
+    return { instructions: CORE_INSTRUCTIONS, verbs_with_instructions };
+}
+/**
+ * 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 function loadVerbInstructions(verbName, registry, fs) {
+    const path = instructionsPathFor(verbName, registry);
+    if (path === null) {
+        return { kind: 'unknown-verb', verb: verbName };
+    }
+    if (!fs.exists(path)) {
+        return { kind: 'missing', verb: verbName, path };
+    }
+    const instructions = fs.readText(path);
+    if (instructions === null) {
+        return { kind: 'unreadable', verb: verbName, path };
+    }
+    return { kind: 'ok', verb: verbName, path, instructions };
+}
+//# sourceMappingURL=instructions-service.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instructions-service.js","sourceRoot":"","sources":["../../../src/services/instructions/instructions-service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAqB3D;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB,EAAE,QAAsB;IAC1E,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC;IACtF,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,8EAA8E;IAC9E,0DAA0D;IAC1D,OAAO,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC,CAAC;AACtE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAsB,EAAE,EAAU;IACtE,MAAM,uBAAuB,GAAG,QAAQ,CAAC,KAAK;SAC3C,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;QACf,MAAM,IAAI,GAAG,mBAAmB,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACtD,OAAO,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC,CAAC;SACD,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,CAAC;AACtE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAgB,EAChB,QAAsB,EACtB,EAAU;IAEV,MAAM,IAAI,GAAG,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACrD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAClD,CAAC;IACD,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACnD,CAAC;IACD,MAAM,YAAY,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACtD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;AAC5D,CAAC"}

package/harness/cli/dist/services/observe/buffer-codec.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The entry grammar for the transient observation buffer (plan 015 D2): the
+ * exact YAML-blocks-in-markdown shape the old observe skill taught, kept so
+ * legacy hand-written buffers parse natively (D3). The CLI is the sole writer
+ * going forward — a constrained serializer (flat fields + the `system.compound`
+ * block, stable field order) paired with a tolerant line-based parser. No
+ * `yaml` runtime dependency: the grammar is a small contract and the
+ * npx-installed core stays at commander+jiti only (constitution P10).
+ */
+/** The 7 universal-schema kinds and their ID prefixes (workshop 005 § D5/D6). */
+export declare const OBSERVATION_KINDS: {
+    readonly difficulty: "DL";
+    readonly 'magic-wand': "MW";
+    readonly gift: "GFT";
+    readonly insight: "INS";
+    readonly coordination: "COORD";
+    readonly 'improvement-suggestion': "SUGG";
+    readonly confusion: "CONF";
+};
+export type ObservationKind = keyof typeof OBSERVATION_KINDS;
+export declare const OBSERVATION_SEVERITIES: readonly ["blocking", "degrading", "annoying"];
+export interface ObservationEntry {
+    id: string;
+    kind: string;
+    description: string;
+    target?: string;
+    severity?: string;
+    workaround?: string;
+    suggested_encoding?: string;
+    /** From the nested `system.compound` block. */
+    first_seen_at?: string;
+}
+/**
+ * Serialize one entry as an append-ready YAML block — identical in shape to the
+ * old skill's template, including the full `system.compound` lifecycle block
+ * (D10) so drained entries carry the fields the harvest already expects.
+ */
+export declare function serializeEntry(entry: ObservationEntry): string;
+/**
+ * Tolerant parse of a whole buffer: split on `- id:` block starts; a block that
+ * fails to parse or lacks a required field (valid id, known kind, non-empty
+ * description) counts as *malformed* — skipped, counted, and returned RAW in
+ * `deviant` so callers can preserve it on disk (D3: nothing is silently
+ * dropped, not even by `--clear`). Non-blank content before the first block
+ * counts as one malformed chunk.
+ */
+export declare function parseBuffer(content: string): {
+    entries: ObservationEntry[];
+    malformed: number;
+    deviant: string[];
+};

package/harness/cli/dist/services/observe/buffer-codec.js

@@ -0,0 +1,139 @@
+/**
+ * The entry grammar for the transient observation buffer (plan 015 D2): the
+ * exact YAML-blocks-in-markdown shape the old observe skill taught, kept so
+ * legacy hand-written buffers parse natively (D3). The CLI is the sole writer
+ * going forward — a constrained serializer (flat fields + the `system.compound`
+ * block, stable field order) paired with a tolerant line-based parser. No
+ * `yaml` runtime dependency: the grammar is a small contract and the
+ * npx-installed core stays at commander+jiti only (constitution P10).
+ */
+/** The 7 universal-schema kinds and their ID prefixes (workshop 005 § D5/D6). */
+export const OBSERVATION_KINDS = {
+    difficulty: 'DL',
+    'magic-wand': 'MW',
+    gift: 'GFT',
+    insight: 'INS',
+    coordination: 'COORD',
+    'improvement-suggestion': 'SUGG',
+    confusion: 'CONF',
+};
+export const OBSERVATION_SEVERITIES = ['blocking', 'degrading', 'annoying'];
+/** `<PREFIX>-<3+ digits>` per workshop 005 § D6 — anything else is a deviant block. */
+const ID_PATTERN = /^[A-Z]+-\d{3,}$/;
+/** The flat entry fields (plus first_seen_at from the nested block), any indent. */
+const FIELD_PATTERN = /^\s+(kind|description|target|severity|workaround|suggested_encoding|first_seen_at):\s*(.*)$/;
+/**
+ * Serialize one entry as an append-ready YAML block — identical in shape to the
+ * old skill's template, including the full `system.compound` lifecycle block
+ * (D10) so drained entries carry the fields the harvest already expects.
+ */
+export function serializeEntry(entry) {
+    const lines = [
+        `- id: ${entry.id}`,
+        `  kind: ${entry.kind}`,
+        `  description: ${JSON.stringify(entry.description)}`,
+    ];
+    if (entry.target !== undefined)
+        lines.push(`  target: ${entry.target}`);
+    if (entry.severity !== undefined)
+        lines.push(`  severity: ${entry.severity}`);
+    if (entry.workaround !== undefined) {
+        lines.push(`  workaround: ${JSON.stringify(entry.workaround)}`);
+    }
+    if (entry.suggested_encoding !== undefined) {
+        lines.push(`  suggested_encoding: ${JSON.stringify(entry.suggested_encoding)}`);
+    }
+    lines.push('  system:', '    compound:', '      status: open', '      source: agent-self', `      first_seen_at: "${entry.first_seen_at ?? ''}"`);
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Tolerant parse of a whole buffer: split on `- id:` block starts; a block that
+ * fails to parse or lacks a required field (valid id, known kind, non-empty
+ * description) counts as *malformed* — skipped, counted, and returned RAW in
+ * `deviant` so callers can preserve it on disk (D3: nothing is silently
+ * dropped, not even by `--clear`). Non-blank content before the first block
+ * counts as one malformed chunk.
+ */
+export function parseBuffer(content) {
+    const entries = [];
+    const deviant = [];
+    let malformed = 0;
+    if (content.trim().length === 0) {
+        return { entries, malformed, deviant };
+    }
+    const lines = content.split('\n');
+    const starts = [];
+    lines.forEach((line, i) => {
+        if (line.startsWith('- id:'))
+            starts.push(i);
+    });
+    const preamble = lines.slice(0, starts[0] ?? lines.length).join('\n');
+    if (preamble.trim().length > 0) {
+        malformed += 1;
+        deviant.push(preamble);
+    }
+    for (let s = 0; s < starts.length; s++) {
+        const startLine = starts[s];
+        const block = lines.slice(startLine, starts[s + 1] ?? lines.length);
+        const entry = parseBlock(block);
+        if (entry === null) {
+            malformed += 1;
+            deviant.push(block.join('\n'));
+        }
+        else {
+            entries.push(entry);
+        }
+    }
+    return { entries, malformed, deviant };
+}
+function parseBlock(block) {
+    const id = bareValue((block[0] ?? '').slice('- id:'.length));
+    const fields = {};
+    for (const line of block.slice(1)) {
+        const m = FIELD_PATTERN.exec(line);
+        if (m?.[1] !== undefined && m[2] !== undefined && !(m[1] in fields)) {
+            fields[m[1]] = unquote(m[2]);
+        }
+    }
+    const { kind, description } = fields;
+    if (!ID_PATTERN.test(id) || kind === undefined || !(kind in OBSERVATION_KINDS)) {
+        return null;
+    }
+    if (description === undefined || description.length === 0) {
+        return null;
+    }
+    return {
+        id,
+        kind,
+        description,
+        ...(fields.target !== undefined && { target: fields.target }),
+        ...(fields.severity !== undefined && { severity: fields.severity }),
+        ...(fields.workaround !== undefined && { workaround: fields.workaround }),
+        ...(fields.suggested_encoding !== undefined && {
+            suggested_encoding: fields.suggested_encoding,
+        }),
+        ...(fields.first_seen_at !== undefined && { first_seen_at: fields.first_seen_at }),
+    };
+}
+/** Quoted values are JSON strings; bare values may carry the old template's inline `# comments`. */
+function unquote(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith('"')) {
+        const m = /^"((?:[^"\\]|\\.)*)"/.exec(trimmed);
+        if (m !== null) {
+            try {
+                return JSON.parse(`"${m[1]}"`);
+            }
+            catch {
+                return m[1] ?? '';
+            }
+        }
+        return trimmed;
+    }
+    return bareValue(trimmed);
+}
+/** Strip an unquoted trailing ` # comment` (the old skill's template carried them inline). */
+function bareValue(raw) {
+    return (raw.split(/\s+#/)[0] ?? raw).trim();
+}
+//# sourceMappingURL=buffer-codec.js.map

package/harness/cli/dist/services/observe/buffer-codec.js.map

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

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

@@ -0,0 +1,87 @@
+import type { Clock } from '../../adapters/clock/clock-port.js';
+import type { EnvPort } from '../../adapters/env/env-port.js';
+import type { FsPort } from '../../adapters/fs/fs-port.js';
+import type { ProcessPort } from '../../adapters/process/process-port.js';
+import { type ObservationEntry } from './buffer-codec.js';
+/**
+ * Pure capture/list/clear logic for `harness observe` behind injected ports
+ * (P2/P3) — the deterministic half of in-flight friction capture the old
+ * observe skill made agents re-infer every session. The CLI owns: agent
+ * identity resolution (D4), schema validation at write (D6), per-kind
+ * sequential IDs over a tolerant parse (D2/D3), append-only buffer writes,
+ * and the `ensureTemp()` gitignore guarantee at capture time (AC-5).
+ */
+export interface ObserveDeps {
+    fs: FsPort;
+    clock: Clock;
+    proc: ProcessPort;
+    env: EnvPort;
+}
+export interface CaptureOptions {
+    description?: string;
+    kind?: string;
+    target?: string;
+    severity?: string;
+    workaround?: string;
+    suggestedEncoding?: string;
+    agent?: string;
+}
+export interface ObserveFailure {
+    ok: false;
+    status: 'error' | 'unconfigured';
+    code?: string;
+    message: string;
+    next_action: string;
+}
+export type CaptureOutcome = {
+    ok: true;
+    bucket: string;
+    id: string;
+    kind: string;
+    path: string;
+} | ObserveFailure;
+/** One pending observation, annotated with the bucket it came from (D9). */
+export interface AnnotatedEntry extends ObservationEntry {
+    bucket: string;
+}
+export type ListOutcome = {
+    ok: true;
+    observations: AnnotatedEntry[];
+    buckets_scanned: string[];
+    malformed_skipped: number;
+} | ObserveFailure;
+export type ClearOutcome = {
+    ok: true;
+    cleared: number;
+    buckets_scanned: string[];
+    malformed_skipped: number;
+} | ObserveFailure;
+/**
+ * Resolve the buffer bucket (D4, extending spec D-11): `--agent` flag →
+ * `HARNESS_AGENT` env → the literal `agent`. Each candidate is kebab-sanitized;
+ * an empty or whitespace-only value is treated as unset and falls through the
+ * chain — capture NEVER fails on identity (it's provenance labeling, not
+ * routing ceremony).
+ */
+export declare function resolveBucket(agentFlag: string | undefined, env: EnvPort): string;
+/** Capture ONE observation: validate → resolve identity → assign ID → append. */
+export declare function captureObservation(opts: CaptureOptions, deps: ObserveDeps): CaptureOutcome;
+/**
+ * List pending observations — ALL buckets by default (the sweep that keeps any
+ * bucket from stranding, D-12), `--agent` narrowing to one. Entries come back
+ * verbatim, annotated with their bucket; deviant blocks are counted in
+ * `malformed_skipped` and preserved on disk (D3/D9).
+ */
+export declare function listObservations(opts: {
+    agent?: string;
+}, deps: ObserveDeps): ListOutcome;
+/**
+ * Remove what `--list` would return (all buckets by default, `--agent`-scoped;
+ * files kept). `cleared` counts the valid entries removed. Deviant blocks are
+ * NOT destroyed: they are written back in place (and reported in
+ * `malformed_skipped`) so hand-written-but-unparseable text survives the drain
+ * for manual inspection (D3 — nothing is silently dropped, companion F001).
+ */
+export declare function clearObservations(opts: {
+    agent?: string;
+}, deps: ObserveDeps): ClearOutcome;

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

@@ -0,0 +1,221 @@
+import { ErrorCodes } from '../../output/error-codes.js';
+import { posixJoin, toPosix } from '../shared/posix-path.js';
+import { ensureTemp, HARNESS_DIR, TEMP_DIR } from '../shared/temp.js';
+import { OBSERVATION_KINDS, OBSERVATION_SEVERITIES, parseBuffer, serializeEntry, } from './buffer-codec.js';
+const BUFFER_FILE = 'session-buffer.md';
+const DEFAULT_BUCKET = 'agent';
+const MIN_DESCRIPTION = 10;
+/** Lowercase-kebab the raw identity; empties out rather than failing (D4). */
+function sanitizeBucket(raw) {
+    return raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * Resolve the buffer bucket (D4, extending spec D-11): `--agent` flag →
+ * `HARNESS_AGENT` env → the literal `agent`. Each candidate is kebab-sanitized;
+ * an empty or whitespace-only value is treated as unset and falls through the
+ * chain — capture NEVER fails on identity (it's provenance labeling, not
+ * routing ceremony).
+ */
+export function resolveBucket(agentFlag, env) {
+    for (const candidate of [agentFlag, env.get('HARNESS_AGENT')]) {
+        if (candidate !== undefined) {
+            const cleaned = sanitizeBucket(candidate);
+            if (cleaned.length > 0)
+                return cleaned;
+        }
+    }
+    return DEFAULT_BUCKET;
+}
+/** Capture ONE observation: validate → resolve identity → assign ID → append. */
+export function captureObservation(opts, deps) {
+    const cwd = toPosix(deps.proc.cwd());
+    if (!deps.fs.exists(posixJoin(cwd, HARNESS_DIR))) {
+        return unconfiguredRepo(cwd);
+    }
+    // Validation at write (D6): reject before any side effect, buffer untouched.
+    const kind = opts.kind ?? '';
+    const kinds = Object.keys(OBSERVATION_KINDS);
+    if (!kinds.includes(kind)) {
+        return {
+            ok: false,
+            status: 'unconfigured',
+            message: `Unknown --kind ${JSON.stringify(kind)}.`,
+            next_action: `Pass --kind as one of: ${kinds.join(', ')}.`,
+        };
+    }
+    const description = opts.description ?? '';
+    if (description.length < MIN_DESCRIPTION) {
+        return {
+            ok: false,
+            status: 'unconfigured',
+            message: `Description too short (${description.length} chars).`,
+            next_action: `Describe the observation in at least ${MIN_DESCRIPTION} characters (got ${description.length}).`,
+        };
+    }
+    if (opts.severity !== undefined &&
+        !OBSERVATION_SEVERITIES.includes(opts.severity)) {
+        return {
+            ok: false,
+            status: 'unconfigured',
+            message: `Unknown --severity ${JSON.stringify(opts.severity)}.`,
+            next_action: `Pass --severity as one of: ${OBSERVATION_SEVERITIES.join(', ')}.`,
+        };
+    }
+    const bucket = resolveBucket(opts.agent, deps.env);
+    const bucketDir = posixJoin(cwd, HARNESS_DIR, TEMP_DIR, bucket);
+    const bufferAbs = posixJoin(bucketDir, BUFFER_FILE);
+    const relPath = posixJoin(HARNESS_DIR, TEMP_DIR, bucket, BUFFER_FILE);
+    let existing = '';
+    if (deps.fs.exists(bufferAbs)) {
+        const text = deps.fs.readText(bufferAbs);
+        if (text === null) {
+            return unreadableBuffer(relPath);
+        }
+        existing = text;
+    }
+    // Per-kind sequential ID over the VALID entries only — malformed blocks are
+    // skipped by the scan and the buffer is never rewritten (AC-3).
+    const prefix = OBSERVATION_KINDS[kind];
+    const id = nextId(prefix, parseBuffer(existing).entries);
+    const entry = {
+        id,
+        kind,
+        description,
+        ...(opts.target !== undefined && { target: opts.target }),
+        ...(opts.severity !== undefined && { severity: opts.severity }),
+        ...(opts.workaround !== undefined && { workaround: opts.workaround }),
+        ...(opts.suggestedEncoding !== undefined && { suggested_encoding: opts.suggestedEncoding }),
+        first_seen_at: deps.clock.nowIso(),
+    };
+    try {
+        ensureTemp(deps); // the transient guarantee fires at capture time (AC-5)
+        deps.fs.mkdirp(bucketDir);
+        const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+        deps.fs.writeText(bufferAbs, existing + separator + serializeEntry(entry));
+    }
+    catch (err) {
+        return {
+            ok: false,
+            status: 'error',
+            code: ErrorCodes.UNKNOWN,
+            message: `Could not write ${relPath}: ${err instanceof Error ? err.message : String(err)}`,
+            next_action: `Could not write \`${relPath}\` (permissions?). Check \`${HARNESS_DIR}/\` is writable.`,
+        };
+    }
+    return { ok: true, bucket, id, kind, path: relPath };
+}
+/**
+ * List pending observations — ALL buckets by default (the sweep that keeps any
+ * bucket from stranding, D-12), `--agent` narrowing to one. Entries come back
+ * verbatim, annotated with their bucket; deviant blocks are counted in
+ * `malformed_skipped` and preserved on disk (D3/D9).
+ */
+export function listObservations(opts, deps) {
+    const swept = sweepBuckets(opts, deps);
+    if ('failure' in swept)
+        return swept.failure;
+    const observations = [];
+    let malformed = 0;
+    for (const bucket of swept.buckets) {
+        const { entries, malformed: m } = parseBuffer(bucket.content);
+        malformed += m;
+        for (const entry of entries) {
+            observations.push({ ...entry, bucket: bucket.name });
+        }
+    }
+    return {
+        ok: true,
+        observations,
+        buckets_scanned: swept.buckets.map((b) => b.name),
+        malformed_skipped: malformed,
+    };
+}
+/**
+ * Remove what `--list` would return (all buckets by default, `--agent`-scoped;
+ * files kept). `cleared` counts the valid entries removed. Deviant blocks are
+ * NOT destroyed: they are written back in place (and reported in
+ * `malformed_skipped`) so hand-written-but-unparseable text survives the drain
+ * for manual inspection (D3 — nothing is silently dropped, companion F001).
+ */
+export function clearObservations(opts, deps) {
+    const swept = sweepBuckets(opts, deps);
+    if ('failure' in swept)
+        return swept.failure;
+    let cleared = 0;
+    let malformed = 0;
+    for (const bucket of swept.buckets) {
+        const { entries, malformed: m, deviant } = parseBuffer(bucket.content);
+        cleared += entries.length;
+        malformed += m;
+        const kept = deviant.map((chunk) => (chunk.endsWith('\n') ? chunk : `${chunk}\n`)).join('');
+        deps.fs.writeText(bucket.bufferAbs, kept);
+    }
+    return {
+        ok: true,
+        cleared,
+        buckets_scanned: swept.buckets.map((b) => b.name),
+        malformed_skipped: malformed,
+    };
+}
+/**
+ * Resolve which buckets to operate on and read their buffers up front, so an
+ * unreadable buffer mid-sweep fails the whole command honestly (E146, D6)
+ * before any truncation happens.
+ */
+function sweepBuckets(opts, deps) {
+    const cwd = toPosix(deps.proc.cwd());
+    if (!deps.fs.exists(posixJoin(cwd, HARNESS_DIR))) {
+        return { failure: unconfiguredRepo(cwd) };
+    }
+    const tempDir = posixJoin(cwd, HARNESS_DIR, TEMP_DIR);
+    const scoped = opts.agent !== undefined ? sanitizeBucket(opts.agent) : undefined;
+    const candidates = scoped !== undefined && scoped.length > 0 ? [scoped] : deps.fs.readdir(tempDir).slice().sort();
+    const buckets = [];
+    for (const name of candidates) {
+        const bufferAbs = posixJoin(tempDir, name, BUFFER_FILE);
+        if (!deps.fs.exists(bufferAbs)) {
+            continue; // not a bucket (e.g. the nested .gitignore) or nothing captured yet
+        }
+        const content = deps.fs.readText(bufferAbs);
+        if (content === null) {
+            return { failure: unreadableBuffer(posixJoin(HARNESS_DIR, TEMP_DIR, name, BUFFER_FILE)) };
+        }
+        buckets.push({ name, bufferAbs, content });
+    }
+    return { buckets };
+}
+function nextId(prefix, entries) {
+    let max = 0;
+    const pattern = new RegExp(`^${prefix}-(\\d+)$`);
+    for (const entry of entries) {
+        const m = pattern.exec(entry.id);
+        if (m?.[1] !== undefined) {
+            const n = Number.parseInt(m[1], 10);
+            if (n > max)
+                max = n;
+        }
+    }
+    return `${prefix}-${String(max + 1).padStart(3, '0')}`;
+}
+function unconfiguredRepo(cwd) {
+    return {
+        ok: false,
+        status: 'unconfigured',
+        message: `No ${HARNESS_DIR}/ directory found in ${cwd}.`,
+        next_action: `No \`${HARNESS_DIR}/\` here — set up the harness first (create \`${HARNESS_DIR}/\`), then re-run.`,
+    };
+}
+function unreadableBuffer(relPath) {
+    return {
+        ok: false,
+        status: 'error',
+        code: ErrorCodes.OBSERVE_BUFFER_UNREADABLE,
+        message: `Observation buffer ${relPath} exists but could not be read.`,
+        next_action: `Inspect \`${relPath}\` — fix permissions or move it aside, then retry (the CLI never deletes it).`,
+    };
+}
+//# sourceMappingURL=observe-service.js.map

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

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

package/harness/cli/dist/services/record/contract.d.ts

@@ -0,0 +1,32 @@
+/**
+ * PUBLIC record-type contract — the type an extension author imports to declare a
+ * new kind of record (alongside the verb contract).
+ *
+ * Authors `import type { HarnessRecordType } from '@ai-substrate/engineering-harness/contract'`
+ * (re-exported from `services/extensions/contract.ts`, which the package's
+ * `exports["./contract"]` map resolves). Everything here is **types only**, so it
+ * is erased at runtime — even a plain `.js` record extension can reference it via
+ * JSDoc with no runtime dependency on the core.
+ *
+ * The CLI is deliberately **schema-agnostic**: it knows only these four fields and
+ * writes the `template` to a path. The record's *actual* schema lives INSIDE the
+ * `template` body (frontmatter keys + commented guidance), so adding the next
+ * record type is "a template + four fields", never a change to `harness record`.
+ */
+/** A record type: a named template the `record` command scaffolds into `.harness/records/<type>/`. */
+export interface HarnessRecordType {
+    /** Discriminator — distinguishes a record-type export from a verb export. REQUIRED. */
+    kind: 'record';
+    /**
+     * The `<type>` arg + the `.harness/records/<type>/` directory name.
+     * Pattern: `^[a-z][a-z0-9-]*$` (same rule as verb names).
+     */
+    type: string;
+    /** One line — shown by `harness record --list` and `doctor`. */
+    description: string;
+    /**
+     * The file body the agent fills. The record's "schema" lives HERE as
+     * frontmatter + commented field guidance — the CLI never parses it.
+     */
+    template: string;
+}

package/harness/cli/dist/services/record/contract.js

@@ -0,0 +1,17 @@
+/**
+ * PUBLIC record-type contract — the type an extension author imports to declare a
+ * new kind of record (alongside the verb contract).
+ *
+ * Authors `import type { HarnessRecordType } from '@ai-substrate/engineering-harness/contract'`
+ * (re-exported from `services/extensions/contract.ts`, which the package's
+ * `exports["./contract"]` map resolves). Everything here is **types only**, so it
+ * is erased at runtime — even a plain `.js` record extension can reference it via
+ * JSDoc with no runtime dependency on the core.
+ *
+ * The CLI is deliberately **schema-agnostic**: it knows only these four fields and
+ * writes the `template` to a path. The record's *actual* schema lives INSIDE the
+ * `template` body (frontmatter keys + commented guidance), so adding the next
+ * record type is "a template + four fields", never a change to `harness record`.
+ */
+export {};
+//# sourceMappingURL=contract.js.map

package/harness/cli/dist/services/record/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/services/record/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}