@maintainabilityai/research-runner 0.1.19 → 0.1.20

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

@@ -12,6 +12,49 @@
  * cleanly in GitHub PR bodies + the rendered docs site.
  */
 import type { GuardrailMode, LlmProvider } from '../schemas';
+/**
+ * v4 agentic-SDLC governance fields. All are OPTIONAL on the Hatter's
+ * Tag input — legacy CI-only runs (without an OKR anchor) omit them
+ * entirely and the emitted YAML skips those keys. OKR-anchored runs
+ * (Phase B+) populate them so the audit chain can be walked across
+ * repositories via `intent_thread_uuid`.
+ *
+ * See vscode-extension/design/agentic-sdlc.md §4.4 (intent_thread_uuid
+ * lifecycle) and §11.1 (Hatter's Tag full provenance schema).
+ */
+export interface HattersTagOkrContext {
+    /** Cross-repo audit correlation key, generated at OKR-create time. */
+    intent_thread_uuid: string;
+    /** Run id of the prior phase that produced the input artifact (null on Why). */
+    parent_intent_thread?: string | null;
+    /** OKR card id (human-readable name, e.g. OKR-2026Q1-IMDB-001-celeb-api). */
+    okr_id: string;
+    /** Which phase produced this artifact. */
+    phase: 'why' | 'how' | 'what';
+    /** Tier frozen at run start (mitigates tier creep, §6.2). */
+    governance_tier: 'autonomous' | 'supervised' | 'restricted';
+}
+/**
+ * Author + reviewer attestation block (v4 §11.1). All optional; legacy
+ * runs without distinct agent DIDs omit it. Phase B+ stamps `author_did`
+ * from the GitHub App installation id + agent name; reviewers fill in
+ * `reviewer_dids[]` after their structured-review pack runs.
+ */
+export interface HattersTagAttestation {
+    /** DID of the agent that authored this artifact. */
+    author_did?: string;
+    /** Prompt pack id + version cited by the author. */
+    author_prompt_pack_version?: string;
+    /** SHA256 of the author's system prompt at run time. */
+    author_system_prompt_sha?: string;
+    /** DIDs of reviewer-agent sessions that scored this PR. */
+    reviewer_dids?: string[];
+    /** Reviewer scores keyed by reviewer name. */
+    reviewer_scores?: {
+        architect?: number | null;
+        security?: number | null;
+    };
+}
 export interface HattersTagInput {
     run_id: string;
     /** Git SHA of the mesh repo at run start. */
@@ -47,6 +90,10 @@ export interface HattersTagInput {
     };
     /** ISO timestamp the artifact was published (PR created). */
     published_at: string;
+    /** v4: OKR-anchored runs populate this; legacy CI-only runs omit it. */
+    okr?: HattersTagOkrContext;
+    /** v4: Phase B+ agent runs populate this; legacy runs omit it. */
+    attestation?: HattersTagAttestation;
 }
 /** 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

@@ -1,6 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildHattersTag = buildHattersTag;
+function hasAnyAttestationField(a) {
+    return !!(a.author_did
+        || a.author_prompt_pack_version
+        || a.author_system_prompt_sha
+        || (a.reviewer_dids && a.reviewer_dids.length > 0)
+        || (a.reviewer_scores && (a.reviewer_scores.architect != null || a.reviewer_scores.security != null)));
+}
 /** Build the full Hatter's Tag block, including heading + fenced YAML. */
 function buildHattersTag(input) {
     const lines = [];
@@ -29,6 +36,45 @@ function buildHattersTag(input) {
         lines.push(`  iterations: ${input.grounding.iterations}`);
         lines.push(`  passed: ${input.grounding.passed}`);
     }
+    if (input.okr) {
+        lines.push('okr:');
+        lines.push(`  intent_thread_uuid: ${input.okr.intent_thread_uuid}`);
+        if (input.okr.parent_intent_thread !== undefined) {
+            lines.push(`  parent_intent_thread: ${input.okr.parent_intent_thread ?? 'null'}`);
+        }
+        lines.push(`  okr_id: ${input.okr.okr_id}`);
+        lines.push(`  phase: ${input.okr.phase}`);
+        lines.push(`  governance_tier: ${input.okr.governance_tier}`);
+    }
+    if (input.attestation && hasAnyAttestationField(input.attestation)) {
+        lines.push('attestation:');
+        if (input.attestation.author_did) {
+            lines.push(`  author_did: ${input.attestation.author_did}`);
+        }
+        if (input.attestation.author_prompt_pack_version) {
+            lines.push(`  author_prompt_pack_version: ${input.attestation.author_prompt_pack_version}`);
+        }
+        if (input.attestation.author_system_prompt_sha) {
+            lines.push(`  author_system_prompt_sha: ${input.attestation.author_system_prompt_sha}`);
+        }
+        if (input.attestation.reviewer_dids && input.attestation.reviewer_dids.length > 0) {
+            lines.push('  reviewer_dids:');
+            for (const did of input.attestation.reviewer_dids) {
+                lines.push(`    - ${did}`);
+            }
+        }
+        if (input.attestation.reviewer_scores
+            && (input.attestation.reviewer_scores.architect != null
+                || input.attestation.reviewer_scores.security != null)) {
+            lines.push('  reviewer_scores:');
+            if (input.attestation.reviewer_scores.architect != null) {
+                lines.push(`    architect: ${input.attestation.reviewer_scores.architect}`);
+            }
+            if (input.attestation.reviewer_scores.security != null) {
+                lines.push(`    security: ${input.attestation.reviewer_scores.security}`);
+            }
+        }
+    }
     lines.push('audit:');
     lines.push(`  event_count: ${input.audit.event_count}`);
     lines.push(`  chain_root_hash: ${input.audit.chain_root_hash}`);

package/dist/schemas/audit-event.d.ts

@@ -23,6 +23,12 @@ declare const PureApiEvent: z.ZodObject<{
     prev_event_hash: z.ZodNullable<z.ZodString>;
     /** SHA-256 of THIS event with `event_hash` set to the empty string. */
     event_hash: z.ZodString;
+    /** Which OKR phase this event belongs to. */
+    phase: z.ZodOptional<z.ZodEnum<["why", "how", "what"]>>;
+    /** Anchor OKR id (human-readable). */
+    okr_id: z.ZodOptional<z.ZodString>;
+    /** Cross-repo audit correlation key (UUID v4). */
+    intent_thread_uuid: z.ZodOptional<z.ZodString>;
 } & {
     node_kind: z.ZodLiteral<"pure_api">;
     api: z.ZodObject<{
@@ -61,6 +67,9 @@ declare const PureApiEvent: z.ZodObject<{
         http_status: number;
         response_byte_count: number;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }, {
     run_id: string;
     event_id: number;
@@ -77,6 +86,9 @@ declare const PureApiEvent: z.ZodObject<{
         http_status: number;
         response_byte_count: number;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }>;
 /** `llm` — non-deterministic LLM call (plan_queries, synthesize, expert reviews). */
 declare const LlmEvent: z.ZodObject<{
@@ -90,6 +102,12 @@ declare const LlmEvent: z.ZodObject<{
     prev_event_hash: z.ZodNullable<z.ZodString>;
     /** SHA-256 of THIS event with `event_hash` set to the empty string. */
     event_hash: z.ZodString;
+    /** Which OKR phase this event belongs to. */
+    phase: z.ZodOptional<z.ZodEnum<["why", "how", "what"]>>;
+    /** Anchor OKR id (human-readable). */
+    okr_id: z.ZodOptional<z.ZodString>;
+    /** Cross-repo audit correlation key (UUID v4). */
+    intent_thread_uuid: z.ZodOptional<z.ZodString>;
 } & {
     node_kind: z.ZodLiteral<"llm">;
     llm: z.ZodObject<{
@@ -180,6 +198,9 @@ declare const LlmEvent: z.ZodObject<{
         output_tokens: number;
         cost_usd: number;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }, {
     run_id: string;
     event_id: number;
@@ -205,6 +226,9 @@ declare const LlmEvent: z.ZodObject<{
         output_tokens: number;
         cost_usd: number;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }>;
 /** `pure` — local-only deterministic computation (validate, dedupe, structural check). */
 declare const PureEvent: z.ZodObject<{
@@ -218,6 +242,12 @@ declare const PureEvent: z.ZodObject<{
     prev_event_hash: z.ZodNullable<z.ZodString>;
     /** SHA-256 of THIS event with `event_hash` set to the empty string. */
     event_hash: z.ZodString;
+    /** Which OKR phase this event belongs to. */
+    phase: z.ZodOptional<z.ZodEnum<["why", "how", "what"]>>;
+    /** Anchor OKR id (human-readable). */
+    okr_id: z.ZodOptional<z.ZodString>;
+    /** Cross-repo audit correlation key (UUID v4). */
+    intent_thread_uuid: z.ZodOptional<z.ZodString>;
 } & {
     node_kind: z.ZodLiteral<"pure">;
     pure: z.ZodObject<{
@@ -243,6 +273,9 @@ declare const PureEvent: z.ZodObject<{
         inputs_summary: string;
         outputs_summary: string;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }, {
     run_id: string;
     event_id: number;
@@ -256,6 +289,9 @@ declare const PureEvent: z.ZodObject<{
         inputs_summary: string;
         outputs_summary: string;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }>;
 /** `node_error` — any node failure, before any retry. */
 declare const NodeErrorEvent: z.ZodObject<{
@@ -269,6 +305,12 @@ declare const NodeErrorEvent: z.ZodObject<{
     prev_event_hash: z.ZodNullable<z.ZodString>;
     /** SHA-256 of THIS event with `event_hash` set to the empty string. */
     event_hash: z.ZodString;
+    /** Which OKR phase this event belongs to. */
+    phase: z.ZodOptional<z.ZodEnum<["why", "how", "what"]>>;
+    /** Anchor OKR id (human-readable). */
+    okr_id: z.ZodOptional<z.ZodString>;
+    /** Cross-repo audit correlation key (UUID v4). */
+    intent_thread_uuid: z.ZodOptional<z.ZodString>;
 } & {
     node_kind: z.ZodLiteral<"node_error">;
     error: z.ZodObject<{
@@ -299,6 +341,9 @@ declare const NodeErrorEvent: z.ZodObject<{
         retryable: boolean;
         stack?: string | undefined;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }, {
     run_id: string;
     event_id: number;
@@ -313,6 +358,9 @@ declare const NodeErrorEvent: z.ZodObject<{
         retryable: boolean;
         stack?: string | undefined;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }>;
 /**
  * `iteration_summary` — emitted once per PRD refinement loop iteration after
@@ -331,6 +379,12 @@ declare const IterationSummaryEvent: z.ZodObject<{
     prev_event_hash: z.ZodNullable<z.ZodString>;
     /** SHA-256 of THIS event with `event_hash` set to the empty string. */
     event_hash: z.ZodString;
+    /** Which OKR phase this event belongs to. */
+    phase: z.ZodOptional<z.ZodEnum<["why", "how", "what"]>>;
+    /** Anchor OKR id (human-readable). */
+    okr_id: z.ZodOptional<z.ZodString>;
+    /** Cross-repo audit correlation key (UUID v4). */
+    intent_thread_uuid: z.ZodOptional<z.ZodString>;
 } & {
     node_kind: z.ZodLiteral<"iteration_summary">;
     iteration: z.ZodNumber;
@@ -467,6 +521,9 @@ declare const IterationSummaryEvent: z.ZodObject<{
         verdict: "PASS" | "ITERATE" | "EXHAUSTED";
         reason: string;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }, {
     run_id: string;
     iteration: number;
@@ -501,6 +558,9 @@ declare const IterationSummaryEvent: z.ZodObject<{
         verdict: "PASS" | "ITERATE" | "EXHAUSTED";
         reason: string;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }>;
 /** `run_complete` — final event emitted by verify_and_trigger. Closes the chain. */
 declare const RunCompleteEvent: z.ZodObject<{
@@ -514,6 +574,12 @@ declare const RunCompleteEvent: z.ZodObject<{
     prev_event_hash: z.ZodNullable<z.ZodString>;
     /** SHA-256 of THIS event with `event_hash` set to the empty string. */
     event_hash: z.ZodString;
+    /** Which OKR phase this event belongs to. */
+    phase: z.ZodOptional<z.ZodEnum<["why", "how", "what"]>>;
+    /** Anchor OKR id (human-readable). */
+    okr_id: z.ZodOptional<z.ZodString>;
+    /** Cross-repo audit correlation key (UUID v4). */
+    intent_thread_uuid: z.ZodOptional<z.ZodString>;
 } & {
     node_kind: z.ZodLiteral<"run_complete">;
     outcome: z.ZodObject<{
@@ -564,6 +630,9 @@ declare const RunCompleteEvent: z.ZodObject<{
         chain_root_hash: string;
         pr_url?: string | undefined;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }, {
     run_id: string;
     event_id: number;
@@ -583,6 +652,9 @@ declare const RunCompleteEvent: z.ZodObject<{
         chain_root_hash: string;
         pr_url?: string | undefined;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }>;
 export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObject<{
     run_id: z.ZodString;
@@ -595,6 +667,12 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
     prev_event_hash: z.ZodNullable<z.ZodString>;
     /** SHA-256 of THIS event with `event_hash` set to the empty string. */
     event_hash: z.ZodString;
+    /** Which OKR phase this event belongs to. */
+    phase: z.ZodOptional<z.ZodEnum<["why", "how", "what"]>>;
+    /** Anchor OKR id (human-readable). */
+    okr_id: z.ZodOptional<z.ZodString>;
+    /** Cross-repo audit correlation key (UUID v4). */
+    intent_thread_uuid: z.ZodOptional<z.ZodString>;
 } & {
     node_kind: z.ZodLiteral<"pure_api">;
     api: z.ZodObject<{
@@ -633,6 +711,9 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
         http_status: number;
         response_byte_count: number;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }, {
     run_id: string;
     event_id: number;
@@ -649,6 +730,9 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
         http_status: number;
         response_byte_count: number;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }>, z.ZodObject<{
     run_id: z.ZodString;
     /** Monotonically incrementing within a run, starting at 1. */
@@ -660,6 +744,12 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
     prev_event_hash: z.ZodNullable<z.ZodString>;
     /** SHA-256 of THIS event with `event_hash` set to the empty string. */
     event_hash: z.ZodString;
+    /** Which OKR phase this event belongs to. */
+    phase: z.ZodOptional<z.ZodEnum<["why", "how", "what"]>>;
+    /** Anchor OKR id (human-readable). */
+    okr_id: z.ZodOptional<z.ZodString>;
+    /** Cross-repo audit correlation key (UUID v4). */
+    intent_thread_uuid: z.ZodOptional<z.ZodString>;
 } & {
     node_kind: z.ZodLiteral<"llm">;
     llm: z.ZodObject<{
@@ -750,6 +840,9 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
         output_tokens: number;
         cost_usd: number;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }, {
     run_id: string;
     event_id: number;
@@ -775,6 +868,9 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
         output_tokens: number;
         cost_usd: number;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }>, z.ZodObject<{
     run_id: z.ZodString;
     /** Monotonically incrementing within a run, starting at 1. */
@@ -786,6 +882,12 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
     prev_event_hash: z.ZodNullable<z.ZodString>;
     /** SHA-256 of THIS event with `event_hash` set to the empty string. */
     event_hash: z.ZodString;
+    /** Which OKR phase this event belongs to. */
+    phase: z.ZodOptional<z.ZodEnum<["why", "how", "what"]>>;
+    /** Anchor OKR id (human-readable). */
+    okr_id: z.ZodOptional<z.ZodString>;
+    /** Cross-repo audit correlation key (UUID v4). */
+    intent_thread_uuid: z.ZodOptional<z.ZodString>;
 } & {
     node_kind: z.ZodLiteral<"pure">;
     pure: z.ZodObject<{
@@ -811,6 +913,9 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
         inputs_summary: string;
         outputs_summary: string;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }, {
     run_id: string;
     event_id: number;
@@ -824,6 +929,9 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
         inputs_summary: string;
         outputs_summary: string;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }>, z.ZodObject<{
     run_id: z.ZodString;
     /** Monotonically incrementing within a run, starting at 1. */
@@ -835,6 +943,12 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
     prev_event_hash: z.ZodNullable<z.ZodString>;
     /** SHA-256 of THIS event with `event_hash` set to the empty string. */
     event_hash: z.ZodString;
+    /** Which OKR phase this event belongs to. */
+    phase: z.ZodOptional<z.ZodEnum<["why", "how", "what"]>>;
+    /** Anchor OKR id (human-readable). */
+    okr_id: z.ZodOptional<z.ZodString>;
+    /** Cross-repo audit correlation key (UUID v4). */
+    intent_thread_uuid: z.ZodOptional<z.ZodString>;
 } & {
     node_kind: z.ZodLiteral<"node_error">;
     error: z.ZodObject<{
@@ -865,6 +979,9 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
         retryable: boolean;
         stack?: string | undefined;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }, {
     run_id: string;
     event_id: number;
@@ -879,6 +996,9 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
         retryable: boolean;
         stack?: string | undefined;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }>, z.ZodObject<{
     run_id: z.ZodString;
     /** Monotonically incrementing within a run, starting at 1. */
@@ -890,6 +1010,12 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
     prev_event_hash: z.ZodNullable<z.ZodString>;
     /** SHA-256 of THIS event with `event_hash` set to the empty string. */
     event_hash: z.ZodString;
+    /** Which OKR phase this event belongs to. */
+    phase: z.ZodOptional<z.ZodEnum<["why", "how", "what"]>>;
+    /** Anchor OKR id (human-readable). */
+    okr_id: z.ZodOptional<z.ZodString>;
+    /** Cross-repo audit correlation key (UUID v4). */
+    intent_thread_uuid: z.ZodOptional<z.ZodString>;
 } & {
     node_kind: z.ZodLiteral<"iteration_summary">;
     iteration: z.ZodNumber;
@@ -1026,6 +1152,9 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
         verdict: "PASS" | "ITERATE" | "EXHAUSTED";
         reason: string;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }, {
     run_id: string;
     iteration: number;
@@ -1060,6 +1189,9 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
         verdict: "PASS" | "ITERATE" | "EXHAUSTED";
         reason: string;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }>, z.ZodObject<{
     run_id: z.ZodString;
     /** Monotonically incrementing within a run, starting at 1. */
@@ -1071,6 +1203,12 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
     prev_event_hash: z.ZodNullable<z.ZodString>;
     /** SHA-256 of THIS event with `event_hash` set to the empty string. */
     event_hash: z.ZodString;
+    /** Which OKR phase this event belongs to. */
+    phase: z.ZodOptional<z.ZodEnum<["why", "how", "what"]>>;
+    /** Anchor OKR id (human-readable). */
+    okr_id: z.ZodOptional<z.ZodString>;
+    /** Cross-repo audit correlation key (UUID v4). */
+    intent_thread_uuid: z.ZodOptional<z.ZodString>;
 } & {
     node_kind: z.ZodLiteral<"run_complete">;
     outcome: z.ZodObject<{
@@ -1121,6 +1259,9 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
         chain_root_hash: string;
         pr_url?: string | undefined;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }, {
     run_id: string;
     event_id: number;
@@ -1140,6 +1281,9 @@ export declare const AuditEvent: z.ZodDiscriminatedUnion<"node_kind", [z.ZodObje
         chain_root_hash: string;
         pr_url?: string | undefined;
     };
+    phase?: "why" | "how" | "what" | undefined;
+    okr_id?: string | undefined;
+    intent_thread_uuid?: string | undefined;
 }>]>;
 export type AuditEvent = z.infer<typeof AuditEvent>;
 export type PureApiEvent = z.infer<typeof PureApiEvent>;

package/dist/schemas/audit-event.js

@@ -27,6 +27,17 @@ const Envelope = zod_1.z.object({
     prev_event_hash: primitives_1.Sha256.nullable(),
     /** SHA-256 of THIS event with `event_hash` set to the empty string. */
     event_hash: primitives_1.Sha256,
+    // ── v4 agentic-SDLC governance fields (Phase A-PR4) ─────────────────
+    // All three are OPTIONAL so legacy CI-only runs (without an OKR anchor)
+    // continue to validate. Phase B+ OKR-anchored runs populate them so
+    // verify-chain can stitch events across repos via intent_thread_uuid.
+    // See vscode-extension/design/agentic-sdlc.md §4.4 + §11.1.6.
+    /** Which OKR phase this event belongs to. */
+    phase: zod_1.z.enum(['why', 'how', 'what']).optional(),
+    /** Anchor OKR id (human-readable). */
+    okr_id: zod_1.z.string().optional(),
+    /** Cross-repo audit correlation key (UUID v4). */
+    intent_thread_uuid: zod_1.z.string().uuid().optional(),
 });
 /** `pure_api` — deterministic external HTTP call (Tavily, arXiv, USPTO, HN, GitHub REST). */
 const PureApiEvent = Envelope.extend({

package/package.json

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