@maintainabilityai/research-runner 0.1.23 → 0.1.29

package/dist/runner/session-context.d.ts

@@ -0,0 +1,38 @@
+/**
+ * session-context — env-var-backed run identity for skill auto-emission (B28).
+ *
+ * Every agentic-SDLC run flows through a single GitHub Actions job. That job
+ * already exports `MESH_PATH` for the runner; B28 extends the contract with
+ * four more env vars so the runner can auto-emit `skill_call` audit events
+ * without the agent having to call `audit-emit-event` after every skill.
+ *
+ * | env var               | shape                                   |
+ * |-----------------------|-----------------------------------------|
+ * | `OKR_ID`              | non-empty string                        |
+ * | `RUN_ID`              | non-empty string                        |
+ * | `INTENT_THREAD_UUID`  | non-empty string (UUID expected but not validated here) |
+ * | `PHASE`               | `'why' \| 'how' \| 'what'`              |
+ *
+ * If ANY var is missing or `PHASE` is not one of the three canonical values,
+ * `readSessionContext()` returns `null` and the runner falls back to legacy
+ * behavior — the agent emits audit events explicitly via the `audit-emit-event`
+ * skill (or doesn't, and the workflow's chain-verify catches the gap). This
+ * preserves backward compatibility with pre-B28 chains while letting new runs
+ * benefit from deterministic emission.
+ *
+ * The auto-emission itself happens in `runSkill()` (skills.ts) — this module
+ * is just the env-var reader so it stays testable in isolation.
+ */
+export type RunPhase = 'why' | 'how' | 'what';
+export interface SessionContext {
+    okrId: string;
+    runId: string;
+    intentThreadUuid: string;
+    phase: RunPhase;
+}
+/**
+ * Read the four session-context env vars. Returns null if any are absent or
+ * `PHASE` is invalid — callers MUST handle null as "no auto-emission, run
+ * the skill anyway." Never throws.
+ */
+export declare function readSessionContext(): SessionContext | null;

package/dist/runner/session-context.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * session-context — env-var-backed run identity for skill auto-emission (B28).
+ *
+ * Every agentic-SDLC run flows through a single GitHub Actions job. That job
+ * already exports `MESH_PATH` for the runner; B28 extends the contract with
+ * four more env vars so the runner can auto-emit `skill_call` audit events
+ * without the agent having to call `audit-emit-event` after every skill.
+ *
+ * | env var               | shape                                   |
+ * |-----------------------|-----------------------------------------|
+ * | `OKR_ID`              | non-empty string                        |
+ * | `RUN_ID`              | non-empty string                        |
+ * | `INTENT_THREAD_UUID`  | non-empty string (UUID expected but not validated here) |
+ * | `PHASE`               | `'why' \| 'how' \| 'what'`              |
+ *
+ * If ANY var is missing or `PHASE` is not one of the three canonical values,
+ * `readSessionContext()` returns `null` and the runner falls back to legacy
+ * behavior — the agent emits audit events explicitly via the `audit-emit-event`
+ * skill (or doesn't, and the workflow's chain-verify catches the gap). This
+ * preserves backward compatibility with pre-B28 chains while letting new runs
+ * benefit from deterministic emission.
+ *
+ * The auto-emission itself happens in `runSkill()` (skills.ts) — this module
+ * is just the env-var reader so it stays testable in isolation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSessionContext = readSessionContext;
+const PHASES = ['why', 'how', 'what'];
+function isRunPhase(value) {
+    return PHASES.includes(value);
+}
+/**
+ * Read the four session-context env vars. Returns null if any are absent or
+ * `PHASE` is invalid — callers MUST handle null as "no auto-emission, run
+ * the skill anyway." Never throws.
+ */
+function readSessionContext() {
+    const okrId = process.env.OKR_ID;
+    const runId = process.env.RUN_ID;
+    const intentThreadUuid = process.env.INTENT_THREAD_UUID;
+    const phase = process.env.PHASE;
+    if (!okrId || !runId || !intentThreadUuid || !phase) {
+        return null;
+    }
+    if (!isRunPhase(phase)) {
+        return null;
+    }
+    return { okrId, runId, intentThreadUuid, phase };
+}

package/dist/runner/skills.d.ts

@@ -2,12 +2,21 @@
  * 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).
+ *
+ * Optional `auditMetadata` field (B28): structured key/value pairs that the
+ * auto-emitter merges into the `skill_call` event payload. Handlers use it
+ * to declare audit-worthy details (search-skill `queries` + `result_count`,
+ * etc.) without the agent having to re-author them in an audit-emit-event
+ * call. Canonical fields (`skill`, `ok`, `duration_ms`, `reason`) always
+ * win on collision so handlers can't accidentally overwrite them.
  */
 export type SkillResult = ({
     ok: true;
+    auditMetadata?: Record<string, unknown>;
 } & Record<string, unknown>) | {
     ok: false;
     reason: string;
+    auditMetadata?: Record<string, unknown>;
 };
 export type SkillHandler = (input: unknown) => Promise<SkillResult>;
 export declare const SKILLS: Record<string, SkillHandler>;

package/dist/runner/skills.js

@@ -64,6 +64,7 @@ exports.readStdin = readStdin;
  */
 const node_crypto_1 = require("node:crypto");
 const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const yaml = __importStar(require("js-yaml"));
 const zod_1 = require("zod");
@@ -72,6 +73,7 @@ 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");
+const session_context_1 = require("./session-context");
 // ─────────────────────────────────────────────────────────────────────
 // Mesh path resolution
 // ─────────────────────────────────────────────────────────────────────
@@ -462,6 +464,118 @@ const handleKnowledgeResearch = async (input) => {
     return { ok: true, findings, whitespace, references, rawBody: body };
 };
 // ─────────────────────────────────────────────────────────────────────
+// Context skills — per-BAR slices of mesh state for PRD agent grounding
+//
+// The prd-agent invokes these AFTER `knowledge-mesh-bar` so the heavy
+// lifting (CALM, threats, ADRs, controls) is already in its working set.
+// These return a focused, persona-specific slice the agent's Architect /
+// Security / Quality lenses each consume in turn during synthesis.
+//
+// Contract: input `{platformId, barIds}` — both required. If any BAR
+// isn't resolvable in the mesh, we return ok:false (HOW agent halts per
+// the "PRDs MUST be grounded" hard rule rather than fabricating).
+// ─────────────────────────────────────────────────────────────────────
+const ContextInput = zod_1.z.object({
+    platformId: zod_1.z.string().min(1),
+    barIds: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+});
+/**
+ * Resolve a list of BAR ids to mesh paths. Returns ok:false on the first
+ * unresolvable id so the agent fails fast rather than synthesizing
+ * against a partial scope.
+ */
+function resolveBarsOrFail(barIds) {
+    const mesh = meshPath();
+    const found = [];
+    for (const barId of barIds) {
+        const r = findBarDir(mesh, barId);
+        if (!r) {
+            return { ok: false, reason: `bar-not-found: ${barId}` };
+        }
+        found.push({ barId, barDir: r.barDir, platformSlug: r.platformSlug });
+    }
+    return { ok: true, found };
+}
+/**
+ * `context-architecture` — CALM model + ADRs + fitness functions, scoped to
+ * the OKR's affected BARs. The Architect persona uses this to ground FRs
+ * against declared nodes and flag CALM-drift.
+ */
+const handleContextArchitecture = async (input) => {
+    const parsed = ContextInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const resolved = resolveBarsOrFail(parsed.data.barIds);
+    if (!resolved.ok) {
+        return resolved;
+    }
+    const bars = [];
+    for (const { barId, barDir, platformSlug } of resolved.found) {
+        const calmModel = readJson(path.join(barDir, 'architecture', 'bar.arch.json'));
+        const fitnessFunctions = readYaml(path.join(barDir, 'architecture', 'fitness-functions.yaml'));
+        const adrDir = path.join(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).trim() });
+            }
+            catch { /* skip */ }
+        }
+        bars.push({ barId, platformId: platformSlug, slice: { calmModel, fitnessFunctions, adrs } });
+    }
+    return { ok: true, scope: parsed.data, bars };
+};
+/**
+ * `context-security` — threats + controls, scoped to the affected BARs.
+ * The Security persona maps SRs to STRIDE THR-NNN + OWASP A0X + NIST
+ * controls from this slice.
+ */
+const handleContextSecurity = async (input) => {
+    const parsed = ContextInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const resolved = resolveBarsOrFail(parsed.data.barIds);
+    if (!resolved.ok) {
+        return resolved;
+    }
+    const bars = [];
+    for (const { barId, barDir, platformSlug } of resolved.found) {
+        const threats = readYaml(path.join(barDir, 'architecture', 'threat-model.yaml'));
+        const controls = readYaml(path.join(barDir, 'security', 'security-controls.yaml'));
+        bars.push({ barId, platformId: platformSlug, slice: { threats, controls } });
+    }
+    return { ok: true, scope: parsed.data, bars };
+};
+/**
+ * `context-quality` — quality attributes + fitness functions, scoped to the
+ * affected BARs. The Quality persona uses this to land NFRs (perf, SLO,
+ * reliability) anchored to declared QA targets.
+ */
+const handleContextQuality = async (input) => {
+    const parsed = ContextInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const resolved = resolveBarsOrFail(parsed.data.barIds);
+    if (!resolved.ok) {
+        return resolved;
+    }
+    const bars = [];
+    for (const { barId, barDir, platformSlug } of resolved.found) {
+        const qualityAttributes = readYaml(path.join(barDir, 'architecture', 'quality-attributes.yaml'));
+        const fitnessFunctions = readYaml(path.join(barDir, 'architecture', 'fitness-functions.yaml'));
+        bars.push({ barId, platformId: platformSlug, slice: { qualityAttributes, fitnessFunctions } });
+    }
+    return { ok: true, scope: parsed.data, bars };
+};
+// ─────────────────────────────────────────────────────────────────────
 // Search skills — thin wrappers over the existing search nodes
 // ─────────────────────────────────────────────────────────────────────
 const SearchQueriesInput = zod_1.z.object({
@@ -505,7 +619,7 @@ const handleTavilySearch = async (input) => {
     }
     const apiKey = process.env.TAVILY_API_KEY;
     if (!apiKey) {
-        return { ok: false, reason: 'tavily-api-key-missing' };
+        return { ok: false, reason: 'tavily-api-key-missing', auditMetadata: { queries: parsed.data.queries, result_count: 0 } };
     }
     try {
         const res = await (0, tavily_search_1.runTavilySearch)({
@@ -513,14 +627,15 @@ const handleTavilySearch = async (input) => {
             queries: parsed.data.queries,
             maxResultsPerQuery: parsed.data.maxResults,
         });
+        const auditMetadata = { queries: parsed.data.queries, result_count: res.results.length };
         const failure = detectAllQueriesFailed(res.envelopes, 'tavily-search');
         if (failure) {
-            return { ok: false, reason: failure, envelopes: res.envelopes };
+            return { ok: false, reason: failure, envelopes: res.envelopes, auditMetadata };
         }
-        return { ok: true, envelopes: res.envelopes, results: res.results };
+        return { ok: true, envelopes: res.envelopes, results: res.results, auditMetadata };
     }
     catch (err) {
-        return { ok: false, reason: `tavily-failed: ${err.message}` };
+        return { ok: false, reason: `tavily-failed: ${err.message}`, auditMetadata: { queries: parsed.data.queries, result_count: 0 } };
     }
 };
 const handleArxivSearch = async (input) => {
@@ -533,14 +648,15 @@ const handleArxivSearch = async (input) => {
             queries: parsed.data.queries,
             maxResultsPerQuery: parsed.data.maxResults,
         });
+        const auditMetadata = { queries: parsed.data.queries, result_count: res.results.length };
         const failure = detectAllQueriesFailed(res.envelopes, 'arxiv-search');
         if (failure) {
-            return { ok: false, reason: failure, envelopes: res.envelopes };
+            return { ok: false, reason: failure, envelopes: res.envelopes, auditMetadata };
         }
-        return { ok: true, envelopes: res.envelopes, results: res.results };
+        return { ok: true, envelopes: res.envelopes, results: res.results, auditMetadata };
     }
     catch (err) {
-        return { ok: false, reason: `arxiv-failed: ${err.message}` };
+        return { ok: false, reason: `arxiv-failed: ${err.message}`, auditMetadata: { queries: parsed.data.queries, result_count: 0 } };
     }
 };
 const handleUsptoSearch = async (input) => {
@@ -550,7 +666,7 @@ const handleUsptoSearch = async (input) => {
     }
     const apiKey = process.env.USPTO_API_KEY;
     if (!apiKey) {
-        return { ok: false, reason: 'uspto-api-key-missing' };
+        return { ok: false, reason: 'uspto-api-key-missing', auditMetadata: { queries: parsed.data.queries, result_count: 0 } };
     }
     try {
         const res = await (0, uspto_search_1.runUsptoSearch)({
@@ -558,14 +674,15 @@ const handleUsptoSearch = async (input) => {
             queries: parsed.data.queries,
             maxResultsPerQuery: parsed.data.maxResults,
         });
+        const auditMetadata = { queries: parsed.data.queries, result_count: res.results.length };
         const failure = detectAllQueriesFailed(res.envelopes, 'uspto-search');
         if (failure) {
-            return { ok: false, reason: failure, envelopes: res.envelopes };
+            return { ok: false, reason: failure, envelopes: res.envelopes, auditMetadata };
         }
-        return { ok: true, envelopes: res.envelopes, results: res.results };
+        return { ok: true, envelopes: res.envelopes, results: res.results, auditMetadata };
     }
     catch (err) {
-        return { ok: false, reason: `uspto-failed: ${err.message}` };
+        return { ok: false, reason: `uspto-failed: ${err.message}`, auditMetadata: { queries: parsed.data.queries, result_count: 0 } };
     }
 };
 const handleHackerNewsSearch = async (input) => {
@@ -578,14 +695,15 @@ const handleHackerNewsSearch = async (input) => {
             queries: parsed.data.queries,
             hitsPerQuery: parsed.data.maxResults,
         });
+        const auditMetadata = { queries: parsed.data.queries, result_count: res.results.length };
         const failure = detectAllQueriesFailed(res.envelopes, 'hackernews-search');
         if (failure) {
-            return { ok: false, reason: failure, envelopes: res.envelopes };
+            return { ok: false, reason: failure, envelopes: res.envelopes, auditMetadata };
         }
-        return { ok: true, envelopes: res.envelopes, results: res.results };
+        return { ok: true, envelopes: res.envelopes, results: res.results, auditMetadata };
     }
     catch (err) {
-        return { ok: false, reason: `hackernews-failed: ${err.message}` };
+        return { ok: false, reason: `hackernews-failed: ${err.message}`, auditMetadata: { queries: parsed.data.queries, result_count: 0 } };
     }
 };
 // ─────────────────────────────────────────────────────────────────────
@@ -719,6 +837,89 @@ function sha256(text) {
 async function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
+// ─────────────────────────────────────────────────────────────────────
+// Knight's Seal v1 — per-run ephemeral Ed25519 signing (B27)
+//
+// Each run gets an ephemeral Ed25519 keypair generated on first
+// `audit-emit-event` call. The PUBLIC key is persisted beside the audit
+// JSONL so verify-chain (and future external auditors) can validate
+// signatures forever. The PRIVATE key lives in `os.tmpdir()` for the
+// duration of the run — NEVER inside the mesh repo (so a careless
+// `git add` can't commit it).
+//
+// Per-event flow:
+//   1. Build event with event_hash='' and signature=''
+//   2. event_hash = sha256(canonical(event))   ← chain integrity
+//   3. signature  = Ed25519(privKey, event_hash)   ← nonrepudiation
+//   4. Persist {...event, event_hash, signature}
+//
+// Verify flow (in audit-verify-chain):
+//   1. Recompute event_hash (set signature='' AND event_hash='')
+//   2. Match recorded event_hash (current chain check)
+//   3. Verify Ed25519(pubKey, recorded event_hash, recorded signature)
+//
+// Backward compat: a chain with NO signature fields is reported as
+// `sealed: false, sealVerified: false` but still passes if hashes are
+// intact. A chain with PARTIAL signatures is treated as tampering.
+// ─────────────────────────────────────────────────────────────────────
+function knightSealPubKeyPath(okrId, runId) {
+    return path.join(meshPath(), 'okrs', okrId, 'audit', 'keys', `${runId}.pub.pem`);
+}
+function knightSealPrivKeyPath(okrId, runId) {
+    // Tmpdir-scoped to avoid any chance of `git add`-ing a private key.
+    // Filename collision-resistant via okrId+runId.
+    return path.join(os.tmpdir(), '.research-runner-keys', `${okrId.replace(/[^A-Za-z0-9_-]/g, '_')}--${runId.replace(/[^A-Za-z0-9_-]/g, '_')}.priv.pem`);
+}
+/**
+ * Load the run's private key from tmp, or generate + persist a fresh
+ * keypair if this is the first event for the run. Returns both KeyObjects.
+ */
+function loadOrCreateRunKeypair(okrId, runId) {
+    const privPath = knightSealPrivKeyPath(okrId, runId);
+    const pubPath = knightSealPubKeyPath(okrId, runId);
+    if (fs.existsSync(privPath) && fs.existsSync(pubPath)) {
+        const privPem = fs.readFileSync(privPath, 'utf8');
+        const pubPem = fs.readFileSync(pubPath, 'utf8');
+        return {
+            privKey: (0, node_crypto_1.createPrivateKey)({ key: privPem, format: 'pem' }),
+            pubKey: (0, node_crypto_1.createPublicKey)({ key: pubPem, format: 'pem' }),
+        };
+    }
+    const { privateKey, publicKey } = (0, node_crypto_1.generateKeyPairSync)('ed25519');
+    const privPem = privateKey.export({ type: 'pkcs8', format: 'pem' });
+    const pubPem = publicKey.export({ type: 'spki', format: 'pem' });
+    fs.mkdirSync(path.dirname(privPath), { recursive: true });
+    fs.writeFileSync(privPath, privPem, { encoding: 'utf8', mode: 0o600 });
+    fs.mkdirSync(path.dirname(pubPath), { recursive: true });
+    fs.writeFileSync(pubPath, pubPem, 'utf8');
+    return { privKey: privateKey, pubKey: publicKey };
+}
+/** Returns null if no public key has been persisted for this run yet. */
+function tryLoadRunPublicKey(okrId, runId) {
+    const pubPath = knightSealPubKeyPath(okrId, runId);
+    if (!fs.existsSync(pubPath)) {
+        return null;
+    }
+    try {
+        return (0, node_crypto_1.createPublicKey)({ key: fs.readFileSync(pubPath, 'utf8'), format: 'pem' });
+    }
+    catch {
+        return null;
+    }
+}
+function signEventHash(privKey, eventHashHex) {
+    // Ed25519 signs raw bytes — we sign the UTF-8 bytes of the hex digest,
+    // which is the canonical chain anchor. Output: 64-byte signature, hex.
+    return (0, node_crypto_1.sign)(null, Buffer.from(eventHashHex, 'utf8'), privKey).toString('hex');
+}
+function verifyEventSignature(pubKey, eventHashHex, signatureHex) {
+    try {
+        return (0, node_crypto_1.verify)(null, Buffer.from(eventHashHex, 'utf8'), pubKey, Buffer.from(signatureHex, 'hex'));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * `audit-emit-event` — append one hash-chained event to
  * `<mesh>/okrs/<id>/audit/events/<runId>.jsonl`.
@@ -763,6 +964,8 @@ const handleAuditEmitEvent = async (input) => {
                     nextEventId = last.event_id + 1;
                 }
             }
+            const { privKey, pubKey } = loadOrCreateRunKeypair(okrId, runId);
+            const publicKeyPem = pubKey.export({ type: 'spki', format: 'pem' });
             const draft = {
                 event_id: nextEventId,
                 ts: new Date().toISOString(),
@@ -773,12 +976,19 @@ const handleAuditEmitEvent = async (input) => {
                 event_kind: eventKind,
                 payload,
                 prev_event_hash: prevHash,
+                // Embed public key on event 1 so a single-line audit excerpt
+                // still names its signer. Subsequent events reference the same
+                // committed key on disk; embedding on every line would balloon
+                // the JSONL with no integrity gain.
+                public_key: nextEventId === 1 ? publicKeyPem : null,
                 event_hash: '',
+                signature: '',
             };
             const hash = sha256(canonicalStringify(draft));
-            const finalEvent = { ...draft, event_hash: hash };
+            const signature = signEventHash(privKey, hash);
+            const finalEvent = { ...draft, event_hash: hash, signature };
             fs.appendFileSync(filePath, JSON.stringify(finalEvent) + '\n', 'utf8');
-            return { ok: true, chainHead: hash, eventId: nextEventId };
+            return { ok: true, chainHead: hash, eventId: nextEventId, sealed: true };
         }
         finally {
             if (lockFd !== null) {
@@ -793,6 +1003,105 @@ const handleAuditEmitEvent = async (input) => {
     return { ok: false, reason: 'audit-write-failed-after-retries' };
 };
 // ─────────────────────────────────────────────────────────────────────
+// Audit verify-chain — CI defense against forged audit logs
+// ─────────────────────────────────────────────────────────────────────
+const AuditVerifyInput = zod_1.z.object({
+    okrId: zod_1.z.string().min(1),
+    runId: zod_1.z.string().min(1),
+});
+/**
+ * `audit-verify-chain` — replay the hash chain over an existing audit
+ * JSONL, returning `{ok: true, chainHead, eventCount}` if the chain is
+ * intact or `{ok: false, reason}` on the first integrity failure.
+ *
+ * Why this skill exists: an agent that loses access to the runner could
+ * (and on PR #105 did) self-write the JSONL with fabricated hashes. The
+ * audit-and-drift workflow calls this skill after each run; verdict
+ * fails + `chain-forgery-detected` label is applied on `ok:false`. The
+ * verification rules are identical to `verifyChain()` in audit-emitter.ts:
+ *   - first event prev_event_hash === null
+ *   - each prev_event_hash === preceding event.event_hash
+ *   - each event_hash === sha256(canonicalStringify(event-with-empty-hash))
+ *   - event_id is monotonic from 1
+ */
+const handleAuditVerifyChain = async (input) => {
+    const parsed = AuditVerifyInput.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, reason: `bad-input: ${parsed.error.message}` };
+    }
+    const { okrId, runId } = parsed.data;
+    const filePath = path.join(meshPath(), 'okrs', okrId, 'audit', 'events', `${runId}.jsonl`);
+    if (!fs.existsSync(filePath)) {
+        return { ok: false, reason: `audit-jsonl-missing: ${filePath}` };
+    }
+    let lines;
+    try {
+        lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(l => l.trim().length > 0);
+    }
+    catch (err) {
+        return { ok: false, reason: `read-failed: ${err.message}` };
+    }
+    const pubKey = tryLoadRunPublicKey(okrId, runId);
+    // Track signature state across the whole chain. v1 contract: either
+    // EVERY event is signed (sealed=true) or NO event is signed (legacy
+    // pre-B27 chain, sealed=false). Partial signatures = tampering.
+    let signedCount = 0;
+    let prev = null;
+    for (let i = 0; i < lines.length; i++) {
+        let event;
+        try {
+            event = JSON.parse(lines[i]);
+        }
+        catch (err) {
+            return { ok: false, reason: `bad-jsonl-line-${i + 1}: ${err.message}` };
+        }
+        if (event.event_id !== i + 1) {
+            return { ok: false, reason: `event-id-mismatch-line-${i + 1}: expected ${i + 1} got ${event.event_id}` };
+        }
+        if (event.prev_event_hash !== prev) {
+            return { ok: false, reason: `prev-hash-mismatch-line-${i + 1}: expected ${prev ?? 'null'} got ${event.prev_event_hash ?? 'null'}` };
+        }
+        const recordedHash = event.event_hash;
+        if (typeof recordedHash !== 'string') {
+            return { ok: false, reason: `missing-event-hash-line-${i + 1}` };
+        }
+        const recordedSignature = typeof event.signature === 'string' ? event.signature : null;
+        // Recompute hash with BOTH event_hash and signature zeroed, since
+        // both are filled in after the hash is computed at write time.
+        const draft = { ...event, event_hash: '', signature: recordedSignature !== null ? '' : undefined };
+        if (recordedSignature === null) {
+            delete draft.signature;
+        }
+        const recomputed = sha256(canonicalStringify(draft));
+        if (recordedHash !== recomputed) {
+            return { ok: false, reason: `forged-hash-line-${i + 1}: recorded=${recordedHash.slice(0, 16)}… recomputed=${recomputed.slice(0, 16)}…` };
+        }
+        if (recordedSignature !== null) {
+            signedCount++;
+        }
+        prev = recordedHash;
+    }
+    // Knight's Seal verification: enforce all-or-nothing.
+    const sealed = signedCount > 0;
+    let sealVerified = false;
+    if (sealed) {
+        if (signedCount !== lines.length) {
+            return { ok: false, reason: `partial-signatures: ${signedCount}/${lines.length} events signed (chain tampered)` };
+        }
+        if (!pubKey) {
+            return { ok: false, reason: `public-key-missing: events are signed but no <runId>.pub.pem found in audit/keys/` };
+        }
+        for (let i = 0; i < lines.length; i++) {
+            const event = JSON.parse(lines[i]);
+            if (!verifyEventSignature(pubKey, event.event_hash, event.signature)) {
+                return { ok: false, reason: `signature-mismatch-line-${i + 1}: Ed25519 verify failed` };
+            }
+        }
+        sealVerified = true;
+    }
+    return { ok: true, chainHead: prev, eventCount: lines.length, sealed, sealVerified };
+};
+// ─────────────────────────────────────────────────────────────────────
 // Registry + dispatcher
 // ─────────────────────────────────────────────────────────────────────
 exports.SKILLS = {
@@ -802,6 +1111,9 @@ exports.SKILLS = {
     'knowledge-mesh-threats': handleKnowledgeMeshThreats,
     'knowledge-mesh-adrs': handleKnowledgeMeshAdrs,
     'knowledge-research': handleKnowledgeResearch,
+    'context-architecture': handleContextArchitecture,
+    'context-security': handleContextSecurity,
+    'context-quality': handleContextQuality,
     'tavily-search': handleTavilySearch,
     'arxiv-search': handleArxivSearch,
     'uspto-search': handleUsptoSearch,
@@ -809,16 +1121,61 @@ exports.SKILLS = {
     'dedupe-and-rank': handleDedupeAndRank,
     'format-research-issue-update': handleFormatResearchIssueUpdate,
     'audit-emit-event': handleAuditEmitEvent,
+    'audit-verify-chain': handleAuditVerifyChain,
 };
 function isSkillName(name) {
     return Object.prototype.hasOwnProperty.call(exports.SKILLS, name);
 }
+/**
+ * Skills whose name STARTS with one of these prefixes never trigger
+ * audit-event auto-emission — they're the audit-event surface itself
+ * (writer + reader). Letting them auto-emit would create either infinite
+ * recursion (audit-emit-event audit-emitting itself) or a meaningless
+ * `skill_call` event for a read-only verify operation.
+ */
+const NO_AUTO_EMIT_SKILLS = new Set(['audit-emit-event', 'audit-verify-chain']);
 async function runSkill(name, input) {
     const handler = exports.SKILLS[name];
     if (!handler) {
         return { ok: false, reason: `unknown-skill: ${name}` };
     }
-    return handler(input);
+    const t0 = Date.now();
+    const result = await handler(input);
+    const duration_ms = Date.now() - t0;
+    // B28 — Court Recorder Auto-Logging. When the workflow has set the
+    // session-context env vars (OKR_ID / RUN_ID / INTENT_THREAD_UUID / PHASE),
+    // the runner deterministically emits a `skill_call` event for every
+    // handler invocation. The agent CANNOT skip this — there's nothing to
+    // skip; the emission happens inside the runner before the result is
+    // returned to the caller. Falls back to legacy mode (no auto-emit) when
+    // context env vars are absent so pre-B28 chains keep working unchanged.
+    if (!NO_AUTO_EMIT_SKILLS.has(name)) {
+        const ctx = (0, session_context_1.readSessionContext)();
+        if (ctx) {
+            // Merge handler-declared auditMetadata first so canonical fields
+            // (skill / ok / duration_ms / reason) always win on collision —
+            // handlers can't accidentally lie about what they were called.
+            const extras = result.auditMetadata ?? {};
+            const payload = { ...extras, skill: name, ok: result.ok, duration_ms };
+            if (!result.ok) {
+                payload.reason = result.reason;
+            }
+            // Best-effort: an audit-write failure must not shadow the real skill
+            // result. The chain-verify CI gate is the catch-net for missed events.
+            try {
+                await handleAuditEmitEvent({
+                    okrId: ctx.okrId,
+                    runId: ctx.runId,
+                    phase: ctx.phase,
+                    intentThreadUuid: ctx.intentThreadUuid,
+                    eventKind: 'skill_call',
+                    payload,
+                });
+            }
+            catch { /* swallow — chain-verify catches gaps */ }
+        }
+    }
+    return result;
 }
 /**
  * Read all of stdin as a UTF-8 string. Returns '' immediately on TTY

package/package.json

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