@maintainabilityai/research-runner 0.1.20 → 0.1.22

package/dist/cli.js

@@ -48,6 +48,7 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const archeologist_1 = require("./runner/archeologist");
 const prd_1 = require("./runner/prd");
+const skills_1 = require("./runner/skills");
 const PKG = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8'));
 function parseFlags(argv) {
     const flags = {};
@@ -191,17 +192,54 @@ async function prdCmd(argv) {
     });
 }
 function help() {
+    const skillNames = Object.keys(skills_1.SKILLS).map(n => `skill-${n}`).sort().join('\n  ');
     process.stdout.write(`research-runner v${PKG.version}
 
 Usage:
   research-runner archeologist --brief "<topic>" --scope-level <platform|bar> --scope-id ID [--path research|archaeology] [...]
   research-runner prd --research-pr <url|path> --scope-level <platform|bar> --scope-id ID [...]
+  research-runner skill-<name>   # one-shot skill subcommand; reads JSON from stdin, writes JSON to stdout
+
+Skills (called by .agent.md tools: declarations under \$MESH_PATH):
+  ${skillNames}
 
 See README.md for the full flag surface.
 `);
 }
+/**
+ * skill-* dispatcher. Reads a JSON object from stdin, calls runSkill,
+ * writes the result as JSON to stdout. Exits non-zero on `ok: false` so
+ * the calling agent (or shell wrapper) can detect failure via exit code
+ * in addition to the structured `{ok: false, reason}` payload.
+ */
+async function skillCmd(skillName) {
+    if (!(0, skills_1.isSkillName)(skillName)) {
+        process.stdout.write(JSON.stringify({ ok: false, reason: `unknown-skill: ${skillName}` }) + '\n');
+        process.exit(1);
+    }
+    const stdinRaw = await (0, skills_1.readStdin)();
+    let input = {};
+    if (stdinRaw.trim().length > 0) {
+        try {
+            input = JSON.parse(stdinRaw);
+        }
+        catch (err) {
+            process.stdout.write(JSON.stringify({ ok: false, reason: `bad-stdin-json: ${err.message}` }) + '\n');
+            process.exit(1);
+        }
+    }
+    const result = await (0, skills_1.runSkill)(skillName, input);
+    process.stdout.write(JSON.stringify(result) + '\n');
+    if (result.ok === false) {
+        process.exit(1);
+    }
+}
 async function main() {
     const [, , subcommand, ...rest] = process.argv;
+    if (subcommand && subcommand.startsWith('skill-')) {
+        await skillCmd(subcommand.slice('skill-'.length));
+        return;
+    }
     switch (subcommand) {
         case 'archeologist':
             await archeologistCmd(rest);

package/dist/runner/court-recorder.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Strictly the fields a CloudEvents v1.0 envelope requires. Optional
+ * fields per the spec (datacontenttype, dataschema, subject, time) are
+ * folded in via `CloudEventsOptional`.
+ *
+ * See https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md
+ */
+export interface CloudEventsEnvelope<T = Record<string, unknown>> {
+    /** CloudEvents spec version. Fixed for our emitter. */
+    specversion: '1.0';
+    /** Reverse-DNS event-source identifier — e.g. `maintainabilityai/research-runner`. */
+    source: string;
+    /** Event type — maps to `audit-emitter` event_kind plus an `mai.` prefix. */
+    type: string;
+    /** Unique id — UUID v4 generated by the emitter. */
+    id: string;
+    /** ISO timestamp when the event was emitted. */
+    time: string;
+    /** MIME type of `data`. Always `application/json` for our emitter. */
+    datacontenttype: 'application/json';
+    /** OKR phase that contextualizes this event. */
+    subject: string;
+    /** The raw audit-emitter event payload. */
+    data: T;
+}
+export interface CourtRecorderInput<T> {
+    /** Reverse-DNS source identifier — e.g. `maintainabilityai/research-runner`. */
+    source: string;
+    /** Event kind from `audit-emitter` — wrapped into `mai.<kind>` for CE `type`. */
+    eventKind: string;
+    /** OKR phase (`why` | `how` | `what` | `setup` etc.) → goes in `subject`. */
+    phase: string;
+    /** The original audit-emitter event payload. Becomes `data`. */
+    payload: T;
+    /** Override timestamp (defaults to `new Date().toISOString()`). */
+    time?: string;
+    /** Override id (defaults to `crypto.randomUUID()`). */
+    id?: string;
+}
+/**
+ * Build a single CloudEvents v1.0 envelope around an audit-event payload.
+ * Stateless + deterministic given an injected `id` + `time` — handy for
+ * unit tests.
+ */
+export declare function buildCloudEventsEnvelope<T>(input: CourtRecorderInput<T>): CloudEventsEnvelope<T>;
+/**
+ * Serialize an envelope to a single JSONL line (NO trailing newline; the
+ * caller appends `\n` when writing). Throws if the envelope can't be
+ * round-tripped through JSON.stringify — that signals a non-serializable
+ * payload, which is a programmer bug, not a runtime condition.
+ */
+export declare function serializeCloudEventsEnvelope<T>(env: CloudEventsEnvelope<T>): string;

package/dist/runner/court-recorder.js

@@ -0,0 +1,77 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCloudEventsEnvelope = buildCloudEventsEnvelope;
+exports.serializeCloudEventsEnvelope = serializeCloudEventsEnvelope;
+/**
+ * Court Recorder — CloudEvents v1.0 envelope emitter for the agentic-SDLC
+ * audit chain. Wraps `audit-emitter`'s raw event payload in a CloudEvents
+ * 1.0 envelope so the resulting JSONL is SIEM-compatible without further
+ * transformation.
+ *
+ * Phase B-PR4 ships the emitter shape; agents will adopt it in their
+ * `audit-emit-event` Skill backend (B-PR1a). Each line of
+ * `okrs/<id>/audit/events/<run-id>.jsonl` is a fully-valid CloudEvents
+ * envelope whose `data` property carries the original audit-event JSON.
+ *
+ * Spec: vscode-extension/design/agentic-sdlc.md §11 (Court Recorder).
+ */
+const crypto = __importStar(require("node:crypto"));
+/**
+ * Build a single CloudEvents v1.0 envelope around an audit-event payload.
+ * Stateless + deterministic given an injected `id` + `time` — handy for
+ * unit tests.
+ */
+function buildCloudEventsEnvelope(input) {
+    return {
+        specversion: '1.0',
+        source: input.source,
+        type: `mai.${input.eventKind}`,
+        id: input.id ?? crypto.randomUUID(),
+        time: input.time ?? new Date().toISOString(),
+        datacontenttype: 'application/json',
+        subject: input.phase,
+        data: input.payload,
+    };
+}
+/**
+ * Serialize an envelope to a single JSONL line (NO trailing newline; the
+ * caller appends `\n` when writing). Throws if the envelope can't be
+ * round-tripped through JSON.stringify — that signals a non-serializable
+ * payload, which is a programmer bug, not a runtime condition.
+ */
+function serializeCloudEventsEnvelope(env) {
+    return JSON.stringify(env);
+}

package/dist/runner/hatters-tag-builder.d.ts

@@ -55,6 +55,35 @@ export interface HattersTagAttestation {
         security?: number | null;
     };
 }
+/**
+ * Evidence-mode block (v4 §11.1.7) — forces authors to be honest about
+ * whether the artifact's citations came from a fresh provider search or
+ * from cached/reused sources.
+ *
+ * Why this exists: the first round of agentic runs (run #21) loaded the
+ * SKILL.md context but had no live skill backends, so the agent silently
+ * fell back to reading repo files and produced an updated artifact that
+ * LOOKED grounded but cited zero live signals. The validator workflow
+ * (B-PR1c) cross-checks `fresh_provider_search_performed === true`
+ * against the audit JSONL's `skill_call` events for the four search
+ * providers — mismatch ⇒ `degraded-evidence` label ⇒ governance-pass
+ * promotion blocked.
+ *
+ *   live     — every cited source came from a fresh provider call this run
+ *   cached   — agent reused prior research without re-running providers
+ *   mixed    — some cited sources are fresh, some carried forward
+ *
+ * `degraded_reason` is REQUIRED on `cached` / `mixed` so the gate can
+ * surface a human-readable cause (e.g. "tavily-skill-backend-missing",
+ * "rate-limited", "rerun-after-review").
+ */
+export interface HattersTagEvidence {
+    evidence_mode: 'live' | 'cached' | 'mixed';
+    /** True iff at least one of the four search providers (tavily/arxiv/uspto/hackernews) was successfully called this run. */
+    fresh_provider_search_performed: boolean;
+    /** Free-text cause when evidence_mode !== 'live'. */
+    degraded_reason?: string;
+}
 export interface HattersTagInput {
     run_id: string;
     /** Git SHA of the mesh repo at run start. */
@@ -94,6 +123,8 @@ export interface HattersTagInput {
     okr?: HattersTagOkrContext;
     /** v4: Phase B+ agent runs populate this; legacy runs omit it. */
     attestation?: HattersTagAttestation;
+    /** v4 §11.1.7: agentic runs populate this; legacy CI runs omit it. */
+    evidence?: HattersTagEvidence;
 }
 /** Build the full Hatter's Tag block, including heading + fenced YAML. */
 export declare function buildHattersTag(input: HattersTagInput): string;

package/dist/runner/hatters-tag-builder.js

@@ -75,6 +75,18 @@ function buildHattersTag(input) {
             }
         }
     }
+    if (input.evidence) {
+        lines.push('evidence:');
+        lines.push(`  evidence_mode: ${input.evidence.evidence_mode}`);
+        lines.push(`  fresh_provider_search_performed: ${input.evidence.fresh_provider_search_performed}`);
+        if (input.evidence.degraded_reason) {
+            // Escape any colons / hashes that would break the bare YAML scalar.
+            const escaped = /[:#]/.test(input.evidence.degraded_reason)
+                ? JSON.stringify(input.evidence.degraded_reason)
+                : input.evidence.degraded_reason;
+            lines.push(`  degraded_reason: ${escaped}`);
+        }
+    }
     lines.push('audit:');
     lines.push(`  event_count: ${input.audit.event_count}`);
     lines.push(`  chain_root_hash: ${input.audit.chain_root_hash}`);

package/dist/runner/skills.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shape every skill returns. Tagged union so the agent can branch on `ok`.
+ * Handlers MUST NOT throw — they return `{ok: false, reason}` instead so
+ * the calling agent can keep going (per SKILL.md error contracts).
+ */
+export type SkillResult = ({
+    ok: true;
+} & Record<string, unknown>) | {
+    ok: false;
+    reason: string;
+};
+export type SkillHandler = (input: unknown) => Promise<SkillResult>;
+export declare const SKILLS: Record<string, SkillHandler>;
+export declare function isSkillName(name: string): boolean;
+export declare function runSkill(name: string, input: unknown): Promise<SkillResult>;
+/**
+ * Read all of stdin as a UTF-8 string. Returns '' immediately on TTY
+ * (no piped input) — handlers will reject via zod with a helpful message.
+ */
+export declare function readStdin(): Promise<string>;

package/dist/runner/skills.js

@@ -0,0 +1,792 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILLS = void 0;
+exports.isSkillName = isSkillName;
+exports.runSkill = runSkill;
+exports.readStdin = readStdin;
+/**
+ * skills — CLI subcommand backends for the agentic-SDLC Skills surface
+ * declared in `vscode-extension/code-templates/skills/<name>/SKILL.md`.
+ *
+ * Each skill is a one-shot, stateless handler: read JSON from stdin →
+ * validate with zod → do the work → write JSON to stdout. Exits 1 on
+ * error with `{ok: false, reason}` payload. This shape mirrors the SKILL.md
+ * "Error contract" sections so the calling agent can branch deterministically
+ * on `parsed.ok === false`.
+ *
+ * Why a single file: the registry is small (~12 handlers), each handler is
+ * thin (validation + delegate to existing nodes/readers), and keeping
+ * them together makes the dispatcher / capability map obvious. If a handler
+ * grows past ~150 lines, lift it into its own file under `skills/`.
+ *
+ * Mesh path resolution: handlers that read mesh state honor `$MESH_PATH`
+ * (set by `okr-bus.yml` when it shells out to the agent). Defaults to
+ * `process.cwd()` for local dev.
+ *
+ * Audit event format: `skill-audit-emit-event` writes a new event taxonomy
+ * (event_kind: skill_call | llm_call | artifact_written | review_received |
+ * state_transition | human_gate) to `okrs/<id>/audit/events/<run>.jsonl`,
+ * distinct from the pipeline runner's `node_kind` events. This is the
+ * canonical agentic-SDLC audit format per design §11.1.6.
+ */
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const yaml = __importStar(require("js-yaml"));
+const zod_1 = require("zod");
+const tavily_search_1 = require("./nodes/tavily-search");
+const arxiv_search_1 = require("./nodes/arxiv-search");
+const hackernews_search_1 = require("./nodes/hackernews-search");
+const uspto_search_1 = require("./nodes/uspto-search");
+const dedupe_and_rank_1 = require("./nodes/dedupe-and-rank");
+// ─────────────────────────────────────────────────────────────────────
+// Mesh path resolution
+// ─────────────────────────────────────────────────────────────────────
+function meshPath() {
+    return process.env.MESH_PATH || process.cwd();
+}
+// ─────────────────────────────────────────────────────────────────────
+// Knowledge skills — read mesh state, return structured JSON
+// ─────────────────────────────────────────────────────────────────────
+const KnowledgeOkrInput = zod_1.z.object({ okrId: zod_1.z.string().min(1) });
+/**
+ * `knowledge-okr` — read `okrs/<id>/okr.yaml` and return the parsed card.
+ * Matches OKRService.readRaw shape. We DO NOT enforce the full BTABoK
+ * schema here — agents need the data even when the schema is a few keys
+ * behind. They can validate downstream if needed.
+ */
+const handleKnowledgeOkr = async (input) => {
+    const parsed = KnowledgeOkrInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const yamlPath = path.join(meshPath(), 'okrs', parsed.data.okrId, 'okr.yaml');
+    if (!fs.existsSync(yamlPath)) {
+        return { ok: false, reason: 'okr-not-found' };
+    }
+    try {
+        const card = yaml.load(fs.readFileSync(yamlPath, 'utf8'));
+        return { ok: true, card };
+    }
+    catch (err) {
+        return { ok: false, reason: `yaml-parse-failed: ${err.message}` };
+    }
+};
+const KnowledgeMeshBarInput = zod_1.z.object({ barId: zod_1.z.string().min(1) });
+/**
+ * Walk platforms/<p>/bars/* looking for an app.yaml whose application.id
+ * matches. Cheap on small portfolios. Returns null when not found.
+ */
+function findBarDir(mesh, barId) {
+    const platformsDir = path.join(mesh, 'platforms');
+    if (!fs.existsSync(platformsDir)) {
+        return null;
+    }
+    for (const p of fs.readdirSync(platformsDir, { withFileTypes: true })) {
+        if (!p.isDirectory()) {
+            continue;
+        }
+        const barsDir = path.join(platformsDir, p.name, 'bars');
+        if (!fs.existsSync(barsDir)) {
+            continue;
+        }
+        for (const b of fs.readdirSync(barsDir, { withFileTypes: true })) {
+            if (!b.isDirectory()) {
+                continue;
+            }
+            const candidate = path.join(barsDir, b.name);
+            try {
+                const app = yaml.load(fs.readFileSync(path.join(candidate, 'app.yaml'), 'utf8'));
+                if (app?.application?.id === barId) {
+                    return { barDir: candidate, platformSlug: p.name };
+                }
+            }
+            catch { /* ignore non-yaml entries */ }
+        }
+    }
+    return null;
+}
+function readYaml(p) {
+    try {
+        return yaml.load(fs.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function readJson(p) {
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function readDirShallow(p) {
+    try {
+        return fs.readdirSync(p);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * `knowledge-mesh-bar` — return CALM model + threats + ADRs + app.yaml for
+ * one BAR. Per the SKILL.md output contract:
+ *   { id, name, platformId, calmModel, appYaml, repos, adrs, threats,
+ *     controls, fitnessFunctions, qualityAttributes }
+ */
+const handleKnowledgeMeshBar = async (input) => {
+    const parsed = KnowledgeMeshBarInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const found = findBarDir(meshPath(), parsed.data.barId);
+    if (!found) {
+        return { ok: false, reason: 'bar-not-found' };
+    }
+    const appYaml = readYaml(path.join(found.barDir, 'app.yaml')) ?? {};
+    const calmModel = readJson(path.join(found.barDir, 'architecture', 'bar.arch.json'));
+    const threatModel = readYaml(path.join(found.barDir, 'architecture', 'threat-model.yaml'));
+    const controls = readYaml(path.join(found.barDir, 'security', 'security-controls.yaml'));
+    const fitnessFunctions = readYaml(path.join(found.barDir, 'architecture', 'fitness-functions.yaml'));
+    const qualityAttributes = readYaml(path.join(found.barDir, 'architecture', 'quality-attributes.yaml'));
+    const adrDir = path.join(found.barDir, 'architecture', 'ADRs');
+    const adrs = [];
+    for (const name of readDirShallow(adrDir)) {
+        if (!name.endsWith('.md')) {
+            continue;
+        }
+        try {
+            const body = fs.readFileSync(path.join(adrDir, name), 'utf8');
+            const titleMatch = body.match(/^#\s+(.+)/m);
+            adrs.push({
+                id: name.replace(/\.md$/, ''),
+                title: titleMatch?.[1] ?? name,
+                body,
+            });
+        }
+        catch { /* skip unreadable */ }
+    }
+    const app = appYaml.application ?? {};
+    return {
+        ok: true,
+        bar: {
+            id: app.id ?? parsed.data.barId,
+            name: app.name ?? parsed.data.barId,
+            platformId: found.platformSlug,
+            calmModel,
+            appYaml,
+            repos: Array.isArray(app.repos) ? app.repos : [],
+            adrs,
+            threats: threatModel,
+            controls,
+            fitnessFunctions,
+            qualityAttributes,
+        },
+    };
+};
+const KnowledgeMeshPlatformInput = zod_1.z.object({ platformId: zod_1.z.string().min(1) });
+/**
+ * `knowledge-mesh-platform` — read platform.arch.json + platform.yaml +
+ * platform.decisions.yaml + list of child BARs.
+ *
+ * Platform id resolution: callers pass either the slug (e.g. "imdb") or
+ * the PLT-prefixed id (e.g. "PLT-IMDB"). We try both forms.
+ */
+const handleKnowledgeMeshPlatform = async (input) => {
+    const parsed = KnowledgeMeshPlatformInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const mesh = meshPath();
+    const platformsDir = path.join(mesh, 'platforms');
+    if (!fs.existsSync(platformsDir)) {
+        return { ok: false, reason: 'platform-not-found' };
+    }
+    const requested = parsed.data.platformId;
+    const slug = requested.toLowerCase().replace(/^plt-/, '');
+    const platformDir = path.join(platformsDir, slug);
+    if (!fs.existsSync(platformDir)) {
+        return { ok: false, reason: 'platform-not-found' };
+    }
+    const platformYaml = readYaml(path.join(platformDir, 'platform.yaml')) ?? {};
+    const calmModel = readJson(path.join(platformDir, 'platform.arch.json'));
+    const decisions = readYaml(path.join(platformDir, 'platform.decisions.yaml'));
+    const bars = [];
+    for (const b of readDirShallow(path.join(platformDir, 'bars'))) {
+        const appYaml = readYaml(path.join(platformDir, 'bars', b, 'app.yaml'));
+        const app = appYaml?.application;
+        if (app?.id) {
+            bars.push({ id: app.id, name: app.name ?? app.id });
+        }
+    }
+    return {
+        ok: true,
+        platform: {
+            id: platformYaml.id ?? `PLT-${slug.toUpperCase()}`,
+            slug,
+            name: platformYaml.name ?? slug,
+            calmModel,
+            decisions,
+            bars,
+        },
+    };
+};
+const KnowledgeMeshThreatsInput = zod_1.z.object({
+    concern: zod_1.z.string().min(1),
+    maxResults: zod_1.z.number().int().positive().optional(),
+});
+/**
+ * Walk every `<bar>/architecture/threat-model.yaml` AND any top-level
+ * `threats/` library, collect entries, return those whose tags / category /
+ * description match the concern keyword (case-insensitive substring).
+ */
+const handleKnowledgeMeshThreats = async (input) => {
+    const parsed = KnowledgeMeshThreatsInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const mesh = meshPath();
+    const concern = parsed.data.concern.toLowerCase();
+    const maxResults = parsed.data.maxResults ?? 20;
+    const out = [];
+    // Top-level threats library (optional convention)
+    const libDir = path.join(mesh, 'threats');
+    for (const name of readDirShallow(libDir)) {
+        if (!name.endsWith('.yaml') && !name.endsWith('.yml')) {
+            continue;
+        }
+        const data = readYaml(path.join(libDir, name));
+        const list = Array.isArray(data) ? data : data?.threats;
+        if (Array.isArray(list)) {
+            out.push(...list);
+        }
+    }
+    // Per-BAR threat models
+    const platformsDir = path.join(mesh, 'platforms');
+    for (const p of readDirShallow(platformsDir)) {
+        const barsDir = path.join(platformsDir, p, 'bars');
+        for (const b of readDirShallow(barsDir)) {
+            const tm = readYaml(path.join(barsDir, b, 'architecture', 'threat-model.yaml'));
+            if (Array.isArray(tm?.threats)) {
+                out.push(...tm.threats);
+            }
+        }
+    }
+    const filtered = out.filter(t => {
+        const hay = JSON.stringify(t).toLowerCase();
+        return hay.includes(concern);
+    }).slice(0, maxResults);
+    return { ok: true, threats: filtered };
+};
+const KnowledgeMeshAdrsInput = zod_1.z.object({
+    concern: zod_1.z.string().min(1),
+    scope: zod_1.z.object({
+        platformId: zod_1.z.string().optional(),
+        barIds: zod_1.z.array(zod_1.z.string()).optional(),
+    }).optional(),
+    maxResults: zod_1.z.number().int().positive().optional(),
+});
+/**
+ * Walk every `<bar>/architecture/ADRs/*.md`, optionally filtered by
+ * platform / BAR scope, return entries whose title/body matches the
+ * concern (case-insensitive substring).
+ */
+const handleKnowledgeMeshAdrs = async (input) => {
+    const parsed = KnowledgeMeshAdrsInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const mesh = meshPath();
+    const concern = parsed.data.concern.toLowerCase();
+    const maxResults = parsed.data.maxResults ?? 20;
+    const barFilter = parsed.data.scope?.barIds ? new Set(parsed.data.scope.barIds) : null;
+    const platformFilter = parsed.data.scope?.platformId?.toLowerCase().replace(/^plt-/, '') ?? null;
+    const out = [];
+    const platformsDir = path.join(mesh, 'platforms');
+    for (const p of readDirShallow(platformsDir)) {
+        if (platformFilter && p.toLowerCase() !== platformFilter) {
+            continue;
+        }
+        const barsDir = path.join(platformsDir, p, 'bars');
+        for (const b of readDirShallow(barsDir)) {
+            const appYaml = readYaml(path.join(barsDir, b, 'app.yaml'));
+            const barId = appYaml?.application?.id ?? b;
+            if (barFilter && !barFilter.has(barId)) {
+                continue;
+            }
+            const adrDir = path.join(barsDir, b, 'architecture', 'ADRs');
+            for (const name of readDirShallow(adrDir)) {
+                if (!name.endsWith('.md')) {
+                    continue;
+                }
+                try {
+                    const body = fs.readFileSync(path.join(adrDir, name), 'utf8');
+                    if (!body.toLowerCase().includes(concern)) {
+                        continue;
+                    }
+                    const titleMatch = body.match(/^#\s+(.+)/m);
+                    const statusMatch = body.match(/^##\s+Status\s*\n+\s*(\S+)/im);
+                    out.push({
+                        id: name.replace(/\.md$/, ''),
+                        title: (titleMatch?.[1] ?? name).trim(),
+                        status: (statusMatch?.[1] ?? 'unknown').trim(),
+                        tags: [],
+                        body,
+                        barId,
+                    });
+                }
+                catch { /* skip */ }
+            }
+        }
+    }
+    return { ok: true, adrs: out.slice(0, maxResults) };
+};
+const KnowledgeResearchInput = zod_1.z.object({ okrId: zod_1.z.string().min(1) });
+/**
+ * `knowledge-research` — read `okrs/<id>/why/research-doc.md` and surface
+ * the parsed structure (R-N findings + Whitespace + References).
+ *
+ * Parse strategy: the synthesis prompt-pack writes deterministic section
+ * headings. We extract by regex; if the doc doesn't follow the schema,
+ * we return the raw body so the PRD agent can still reason about it.
+ */
+const handleKnowledgeResearch = async (input) => {
+    const parsed = KnowledgeResearchInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const docPath = path.join(meshPath(), 'okrs', parsed.data.okrId, 'why', 'research-doc.md');
+    if (!fs.existsSync(docPath)) {
+        return { ok: false, reason: 'research-not-merged-yet' };
+    }
+    const body = fs.readFileSync(docPath, 'utf8');
+    /**
+     * Split by R-N headings rather than regex-capture the block — JS regex
+     * lacks `\Z` and the lookahead-for-end-of-input dance is error-prone.
+     * Walk line-by-line, accumulate into the current finding's block.
+     */
+    const findings = [];
+    const lines = body.split('\n');
+    let current = null;
+    const flush = () => {
+        if (!current) {
+            return;
+        }
+        const blockText = current.block.join('\n');
+        const supporting = [...blockText.matchAll(/^\s*-\s*(?:Supporting|S):\s*(.+)$/gm)].map(x => x[1].trim());
+        const contradicting = [...blockText.matchAll(/^\s*-\s*(?:Contradicting|C):\s*(.+)$/gm)].map(x => x[1].trim());
+        const confidenceMatch = blockText.match(/Confidence:\s*(HIGH|MEDIUM|LOW)/i);
+        findings.push({
+            id: current.id,
+            title: current.title,
+            supporting,
+            contradicting,
+            confidence: confidenceMatch?.[1].toUpperCase() ?? 'MEDIUM',
+        });
+        current = null;
+    };
+    for (const line of lines) {
+        const startMatch = line.match(/^###\s+(R-\d+)\s+(.+?)\s*$/);
+        if (startMatch) {
+            flush();
+            current = { id: startMatch[1], title: startMatch[2].trim(), block: [] };
+            continue;
+        }
+        if (/^##\s/.test(line)) {
+            flush();
+        }
+        if (current) {
+            current.block.push(line);
+        }
+    }
+    flush();
+    /** Pull bullets out of a labelled `## Section` until the next `## ` or EOF. */
+    const pullBullets = (sectionName) => {
+        const out = [];
+        let inSection = false;
+        for (const line of lines) {
+            if (new RegExp(`^##\\s+${sectionName}\\b`, 'i').test(line)) {
+                inSection = true;
+                continue;
+            }
+            if (inSection && /^##\s/.test(line)) {
+                break;
+            }
+            if (!inSection) {
+                continue;
+            }
+            const bullet = line.match(/^\s*-\s*(.+?)\s*$/);
+            if (bullet) {
+                out.push(bullet[1]);
+            }
+        }
+        return out;
+    };
+    const whitespace = pullBullets('Whitespace');
+    const references = pullBullets('References');
+    return { ok: true, findings, whitespace, references, rawBody: body };
+};
+// ─────────────────────────────────────────────────────────────────────
+// Search skills — thin wrappers over the existing search nodes
+// ─────────────────────────────────────────────────────────────────────
+const SearchQueriesInput = zod_1.z.object({
+    queries: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    maxResults: zod_1.z.number().int().positive().optional(),
+});
+const handleTavilySearch = async (input) => {
+    const parsed = SearchQueriesInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const apiKey = process.env.TAVILY_API_KEY;
+    if (!apiKey) {
+        return { ok: false, reason: 'tavily-api-key-missing' };
+    }
+    try {
+        const res = await (0, tavily_search_1.runTavilySearch)({
+            apiKey,
+            queries: parsed.data.queries,
+            maxResultsPerQuery: parsed.data.maxResults,
+        });
+        return { ok: true, envelopes: res.envelopes, results: res.results };
+    }
+    catch (err) {
+        return { ok: false, reason: `tavily-failed: ${err.message}` };
+    }
+};
+const handleArxivSearch = async (input) => {
+    const parsed = SearchQueriesInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    try {
+        const res = await (0, arxiv_search_1.runArxivSearch)({
+            queries: parsed.data.queries,
+            maxResultsPerQuery: parsed.data.maxResults,
+        });
+        return { ok: true, envelopes: res.envelopes, results: res.results };
+    }
+    catch (err) {
+        return { ok: false, reason: `arxiv-failed: ${err.message}` };
+    }
+};
+const handleUsptoSearch = async (input) => {
+    const parsed = SearchQueriesInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const apiKey = process.env.USPTO_API_KEY;
+    if (!apiKey) {
+        return { ok: false, reason: 'uspto-api-key-missing' };
+    }
+    try {
+        const res = await (0, uspto_search_1.runUsptoSearch)({
+            apiKey,
+            queries: parsed.data.queries,
+            maxResultsPerQuery: parsed.data.maxResults,
+        });
+        return { ok: true, envelopes: res.envelopes, results: res.results };
+    }
+    catch (err) {
+        return { ok: false, reason: `uspto-failed: ${err.message}` };
+    }
+};
+const handleHackerNewsSearch = async (input) => {
+    const parsed = SearchQueriesInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    try {
+        const res = await (0, hackernews_search_1.runHackerNewsSearch)({
+            queries: parsed.data.queries,
+            hitsPerQuery: parsed.data.maxResults,
+        });
+        return { ok: true, envelopes: res.envelopes, results: res.results };
+    }
+    catch (err) {
+        return { ok: false, reason: `hackernews-failed: ${err.message}` };
+    }
+};
+// ─────────────────────────────────────────────────────────────────────
+// Pure skills — dedupe + format
+// ─────────────────────────────────────────────────────────────────────
+const ProviderResultSchema = zod_1.z.object({
+    provider: zod_1.z.string(),
+    fromQuery: zod_1.z.string(),
+    title: zod_1.z.string(),
+    url: zod_1.z.string(),
+    content: zod_1.z.string(),
+    score: zod_1.z.number(),
+    publishedDate: zod_1.z.string().optional(),
+    authors: zod_1.z.array(zod_1.z.string()).optional(),
+});
+const DedupeAndRankInput = zod_1.z.object({
+    results: zod_1.z.array(zod_1.z.array(ProviderResultSchema)),
+    topN: zod_1.z.number().int().positive().optional(),
+});
+const handleDedupeAndRank = async (input) => {
+    const parsed = DedupeAndRankInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const flat = parsed.data.results.flat();
+    const ranked = (0, dedupe_and_rank_1.dedupeAndRank)({ results: flat, topN: parsed.data.topN ?? 50 });
+    const providerCounts = {};
+    for (const r of ranked) {
+        providerCounts[r.provider] = (providerCounts[r.provider] ?? 0) + 1;
+    }
+    return { ok: true, rankedSources: ranked, providerCounts };
+};
+const RankedSourceSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    provider: zod_1.z.string(),
+    title: zod_1.z.string(),
+    url: zod_1.z.string(),
+    retrieved_at: zod_1.z.string(),
+    salience_score: zod_1.z.number(),
+    excerpt: zod_1.z.string(),
+    published_at: zod_1.z.string().optional(),
+    authors: zod_1.z.array(zod_1.z.string()).optional(),
+});
+const FormatIssueUpdateInput = zod_1.z.object({
+    topic: zod_1.z.string(),
+    runId: zod_1.z.string(),
+    rankedSources: zod_1.z.array(RankedSourceSchema),
+    providerCounts: zod_1.z.record(zod_1.z.string(), zod_1.z.number()),
+    gapSignals: zod_1.z.array(zod_1.z.string()).optional(),
+    meshContext: zod_1.z.object({
+        platformId: zod_1.z.string().optional(),
+        barIds: zod_1.z.array(zod_1.z.string()).optional(),
+    }),
+});
+const COMMENT_BYTE_CAP = 60_000;
+/**
+ * `format-research-issue-update` — render the OKR issue comment that the
+ * market-research-agent posts after each iteration. Pure markdown; no LLM.
+ * Truncates with a footer when over 60kB (GitHub issue cap is ~65k).
+ */
+const handleFormatResearchIssueUpdate = async (input) => {
+    const parsed = FormatIssueUpdateInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const { topic, runId, rankedSources, providerCounts, gapSignals = [], meshContext } = parsed.data;
+    const lines = [];
+    lines.push(`## 🔍 Market research update — ${topic}`);
+    lines.push('');
+    lines.push(`Run \`${runId}\` — platform \`${meshContext.platformId ?? '—'}\`, BARs \`${(meshContext.barIds ?? []).join(', ') || '—'}\`.`);
+    lines.push('');
+    lines.push('| Provider | Ranked |');
+    lines.push('|---|---:|');
+    for (const [provider, count] of Object.entries(providerCounts)) {
+        lines.push(`| ${provider} | ${count} |`);
+    }
+    lines.push('');
+    if (gapSignals.length > 0) {
+        lines.push('### Gap signals');
+        lines.push('');
+        for (const g of gapSignals) {
+            lines.push(`- \`${g}\``);
+        }
+        lines.push('');
+    }
+    lines.push('### Top-ranked sources');
+    lines.push('');
+    for (const s of rankedSources) {
+        const date = s.published_at ? ` _(${s.published_at.slice(0, 10)})_` : '';
+        lines.push(`- \`${s.id}\` **[${s.title}](${s.url})** — ${s.provider}, score ${s.salience_score.toFixed(2)}${date}`);
+        if (s.excerpt) {
+            lines.push(`  > ${s.excerpt.replace(/\s+/g, ' ').trim().slice(0, 400)}`);
+        }
+    }
+    let markdown = lines.join('\n');
+    let byteCount = Buffer.byteLength(markdown, 'utf8');
+    if (byteCount > COMMENT_BYTE_CAP) {
+        markdown = markdown.slice(0, COMMENT_BYTE_CAP) + '\n\n> _Truncated — original exceeded GitHub issue-comment byte cap._';
+        byteCount = Buffer.byteLength(markdown, 'utf8');
+    }
+    return { ok: true, markdown, byteCount };
+};
+// ─────────────────────────────────────────────────────────────────────
+// Audit skill — hash-chained JSONL append, cross-process-safe
+// ─────────────────────────────────────────────────────────────────────
+const AuditEmitInput = zod_1.z.object({
+    okrId: zod_1.z.string().min(1),
+    runId: zod_1.z.string().min(1),
+    eventKind: zod_1.z.enum(['skill_call', 'llm_call', 'artifact_written', 'review_received', 'state_transition', 'human_gate']),
+    payload: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    phase: zod_1.z.enum(['why', 'how', 'what']),
+    intentThreadUuid: zod_1.z.string().min(1),
+});
+const LOCK_RETRY_LIMIT = 3;
+const LOCK_RETRY_BASE_MS = 50;
+/** Recursive key-sorted JSON stringify so the event hash is canonical. */
+function canonicalStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(canonicalStringify).join(',') + ']';
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalStringify(obj[k])).join(',') + '}';
+}
+function sha256(text) {
+    return (0, node_crypto_1.createHash)('sha256').update(text, 'utf8').digest('hex');
+}
+async function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * `audit-emit-event` — append one hash-chained event to
+ * `<mesh>/okrs/<id>/audit/events/<runId>.jsonl`.
+ *
+ * Cross-process serialization: we use an exclusive-create lock file
+ * (`<jsonl>.lock`) with bounded retries. Each call reads the existing
+ * tail, computes prev_event_hash + event_id, writes the new line, then
+ * releases the lock. On terminal contention returns `{ok: false,
+ * reason: 'audit-write-failed-after-retries'}` per the SKILL.md
+ * contract — agents treat this as non-blocking.
+ */
+const handleAuditEmitEvent = async (input) => {
+    const parsed = AuditEmitInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const { okrId, runId, eventKind, payload, phase, intentThreadUuid } = parsed.data;
+    const dir = path.join(meshPath(), 'okrs', okrId, 'audit', 'events');
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, `${runId}.jsonl`);
+    const lockPath = `${filePath}.lock`;
+    for (let attempt = 0; attempt < LOCK_RETRY_LIMIT; attempt++) {
+        let lockFd = null;
+        try {
+            lockFd = fs.openSync(lockPath, 'wx');
+        }
+        catch (err) {
+            if (err.code === 'EEXIST') {
+                await sleep(LOCK_RETRY_BASE_MS * (attempt + 1));
+                continue;
+            }
+            return { ok: false, reason: `audit-lock-failed: ${err.message}` };
+        }
+        try {
+            let prevHash = null;
+            let nextEventId = 1;
+            if (fs.existsSync(filePath)) {
+                const existing = fs.readFileSync(filePath, 'utf8').split('\n').filter(l => l.trim().length > 0);
+                if (existing.length > 0) {
+                    const last = JSON.parse(existing[existing.length - 1]);
+                    prevHash = last.event_hash;
+                    nextEventId = last.event_id + 1;
+                }
+            }
+            const draft = {
+                event_id: nextEventId,
+                ts: new Date().toISOString(),
+                okr_id: okrId,
+                run_id: runId,
+                intent_thread_uuid: intentThreadUuid,
+                phase,
+                event_kind: eventKind,
+                payload,
+                prev_event_hash: prevHash,
+                event_hash: '',
+            };
+            const hash = sha256(canonicalStringify(draft));
+            const finalEvent = { ...draft, event_hash: hash };
+            fs.appendFileSync(filePath, JSON.stringify(finalEvent) + '\n', 'utf8');
+            return { ok: true, chainHead: hash, eventId: nextEventId };
+        }
+        finally {
+            if (lockFd !== null) {
+                fs.closeSync(lockFd);
+            }
+            try {
+                fs.unlinkSync(lockPath);
+            }
+            catch { /* lock already gone */ }
+        }
+    }
+    return { ok: false, reason: 'audit-write-failed-after-retries' };
+};
+// ─────────────────────────────────────────────────────────────────────
+// Registry + dispatcher
+// ─────────────────────────────────────────────────────────────────────
+exports.SKILLS = {
+    'knowledge-okr': handleKnowledgeOkr,
+    'knowledge-mesh-bar': handleKnowledgeMeshBar,
+    'knowledge-mesh-platform': handleKnowledgeMeshPlatform,
+    'knowledge-mesh-threats': handleKnowledgeMeshThreats,
+    'knowledge-mesh-adrs': handleKnowledgeMeshAdrs,
+    'knowledge-research': handleKnowledgeResearch,
+    'tavily-search': handleTavilySearch,
+    'arxiv-search': handleArxivSearch,
+    'uspto-search': handleUsptoSearch,
+    'hackernews-search': handleHackerNewsSearch,
+    'dedupe-and-rank': handleDedupeAndRank,
+    'format-research-issue-update': handleFormatResearchIssueUpdate,
+    'audit-emit-event': handleAuditEmitEvent,
+};
+function isSkillName(name) {
+    return Object.prototype.hasOwnProperty.call(exports.SKILLS, name);
+}
+async function runSkill(name, input) {
+    const handler = exports.SKILLS[name];
+    if (!handler) {
+        return { ok: false, reason: `unknown-skill: ${name}` };
+    }
+    return handler(input);
+}
+/**
+ * Read all of stdin as a UTF-8 string. Returns '' immediately on TTY
+ * (no piped input) — handlers will reject via zod with a helpful message.
+ */
+async function readStdin() {
+    if (process.stdin.isTTY) {
+        return '';
+    }
+    return new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', chunk => { data += chunk; });
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', reject);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maintainabilityai/research-runner",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Research + PRD agent runner — orchestrates the Archeologist and PRD pipelines for the MaintainabilityAI governance mesh",
   "license": "MIT",
   "author": "MaintainabilityAI",