@exaudeus/workrail 3.61.0 → 3.63.0

package/dist/v2/durable-core/schemas/session/events.d.ts

@@ -17,7 +17,7 @@ export declare const DomainEventEnvelopeV1Schema: z.ZodObject<{
         nodeId?: string | undefined;
     }>>;
     data: z.ZodType<unknown, z.ZodTypeDef, unknown>;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
     kind: string;
     v: 1;
@@ -25,12 +25,12 @@ export declare const DomainEventEnvelopeV1Schema: z.ZodObject<{
     eventIndex: number;
     eventId: string;
     dedupeKey: string;
+    timestampMs: number;
     scope?: {
         runId?: string | undefined;
         nodeId?: string | undefined;
     } | undefined;
     data?: unknown;
-    timestampMs?: number | undefined;
 }, {
     kind: string;
     v: 1;
@@ -38,12 +38,12 @@ export declare const DomainEventEnvelopeV1Schema: z.ZodObject<{
     eventIndex: number;
     eventId: string;
     dedupeKey: string;
+    timestampMs: number;
     scope?: {
         runId?: string | undefined;
         nodeId?: string | undefined;
     } | undefined;
     data?: unknown;
-    timestampMs?: number | undefined;
 }>;
 export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
     v: z.ZodLiteral<1>;
@@ -61,7 +61,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         runId?: string | undefined;
         nodeId?: string | undefined;
     }>>;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"session_created">;
     data: z.ZodObject<{
@@ -81,11 +81,11 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
     data: {
         parentSessionId?: string | undefined;
     };
+    timestampMs: number;
     scope?: {
         runId?: string | undefined;
         nodeId?: string | undefined;
     } | undefined;
-    timestampMs?: number | undefined;
 }, {
     kind: "session_created";
     v: 1;
@@ -96,18 +96,18 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
     data: {
         parentSessionId?: string | undefined;
     };
+    timestampMs: number;
     scope?: {
         runId?: string | undefined;
         nodeId?: string | undefined;
     } | undefined;
-    timestampMs?: number | undefined;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"observation_recorded">;
     scope: z.ZodUndefined;
@@ -208,8 +208,8 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         key: "git_branch" | "git_head_sha" | "repo_root_hash" | "repo_root";
         confidence: "low" | "med" | "high";
     };
+    timestampMs: number;
     scope?: undefined;
-    timestampMs?: number | undefined;
 }, {
     kind: "observation_recorded";
     v: 1;
@@ -234,15 +234,15 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         key: "git_branch" | "git_head_sha" | "repo_root_hash" | "repo_root";
         confidence: "low" | "med" | "high";
     };
+    timestampMs: number;
     scope?: undefined;
-    timestampMs?: number | undefined;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"run_started">;
     scope: z.ZodObject<{
@@ -284,7 +284,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         workflowSourceKind: "bundled" | "user" | "project" | "remote" | "plugin";
         workflowSourceRef: string;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }, {
     kind: "run_started";
     v: 1;
@@ -301,14 +301,14 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         workflowSourceKind: "bundled" | "user" | "project" | "remote" | "plugin";
         workflowSourceRef: string;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"node_created">;
     scope: z.ZodObject<{
@@ -354,7 +354,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         parentNodeId: string | null;
         workflowHash: never;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }, {
     kind: "node_created";
     v: 1;
@@ -372,14 +372,14 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         parentNodeId: string | null;
         workflowHash: string;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"edge_created">;
     scope: z.ZodObject<{
@@ -455,7 +455,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             eventId: string;
         };
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }, {
     kind: "edge_created";
     v: 1;
@@ -475,14 +475,14 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             eventId: string;
         };
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"advance_recorded">;
     scope: z.ZodObject<{
@@ -836,7 +836,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             toNodeId: string;
         };
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }, {
     kind: "advance_recorded";
     v: 1;
@@ -880,14 +880,14 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             toNodeId: string;
         };
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"validation_performed">;
     scope: z.ZodObject<{
@@ -965,7 +965,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             suggestions: readonly string[];
         };
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }, {
     kind: "validation_performed";
     v: 1;
@@ -987,14 +987,14 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             suggestions: readonly string[];
         };
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"node_output_appended">;
     scope: z.ZodObject<{
@@ -1122,7 +1122,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         };
         supersedesOutputId?: string | undefined;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }, {
     kind: "node_output_appended";
     v: 1;
@@ -1149,14 +1149,14 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         };
         supersedesOutputId?: string | undefined;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"assessment_recorded">;
     scope: z.ZodObject<{
@@ -1240,7 +1240,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         }[];
         summary?: string | undefined;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }, {
     kind: "assessment_recorded";
     v: 1;
@@ -1265,14 +1265,14 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         }[];
         summary?: string | undefined;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"assessment_consequence_applied">;
     scope: z.ZodObject<{
@@ -1354,7 +1354,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             guidance: string;
         };
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }, {
     kind: "assessment_consequence_applied";
     v: 1;
@@ -1378,14 +1378,14 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             guidance: string;
         };
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"preferences_changed">;
     scope: z.ZodObject<{
@@ -1513,7 +1513,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             riskPolicy: "conservative" | "balanced" | "aggressive";
         };
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }, {
     kind: "preferences_changed";
     v: 1;
@@ -1540,14 +1540,14 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             riskPolicy: "conservative" | "balanced" | "aggressive";
         };
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"capability_observed">;
     scope: z.ZodObject<{
@@ -1809,7 +1809,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             enforcementGrade: "weak";
         };
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }, {
     kind: "capability_observed";
     v: 1;
@@ -1850,14 +1850,14 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             enforcementGrade: "weak";
         };
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"gap_recorded">;
     scope: z.ZodObject<{
@@ -2049,7 +2049,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             outputId: string;
         })[] | undefined;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }, {
     kind: "gap_recorded";
     v: 1;
@@ -2092,14 +2092,14 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
             outputId: string;
         })[] | undefined;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"context_set">;
     scope: z.ZodObject<{
@@ -2137,7 +2137,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         contextId: string;
         context?: unknown;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }, {
     kind: "context_set";
     v: 1;
@@ -2153,14 +2153,14 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         contextId: string;
         context?: unknown;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"divergence_recorded">;
     scope: z.ZodObject<{
@@ -2206,7 +2206,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         divergenceId: string;
         relatedStepId?: string | undefined;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }, {
     kind: "divergence_recorded";
     v: 1;
@@ -2224,14 +2224,14 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         divergenceId: string;
         relatedStepId?: string | undefined;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }>, z.ZodObject<{
     v: z.ZodLiteral<1>;
     eventId: z.ZodString;
     eventIndex: z.ZodNumber;
     sessionId: z.ZodString;
     dedupeKey: z.ZodString;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodNumber;
 } & {
     kind: z.ZodLiteral<"decision_trace_appended">;
     scope: z.ZodObject<{
@@ -2427,7 +2427,7 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         }[];
         traceId: string;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }, {
     kind: "decision_trace_appended";
     v: 1;
@@ -2459,6 +2459,6 @@ export declare const DomainEventV1Schema: z.ZodDiscriminatedUnion<"kind", [z.Zod
         }[];
         traceId: string;
     };
-    timestampMs?: number | undefined;
+    timestampMs: number;
 }>]>;
 export type DomainEventV1 = z.infer<typeof DomainEventV1Schema>;

package/dist/v2/durable-core/schemas/session/events.js

@@ -36,7 +36,7 @@ exports.DomainEventEnvelopeV1Schema = zod_1.z.object({
     })
         .optional(),
     data: json_zod_js_1.JsonValueSchema,
-    timestampMs: zod_1.z.number().int().positive().optional(),
+    timestampMs: zod_1.z.number().int().positive(),
 });
 const WorkflowSourceKindSchema = zod_1.z.enum(['bundled', 'user', 'project', 'remote', 'plugin']);
 const RunStartedDataV1Schema = zod_1.z.object({

package/docs/authoring-v2.md

@@ -217,6 +217,57 @@ Important implementation detail:
 - The default durable output is a short recap in `output.notesMarkdown` (recorded by the agent when advancing or checkpointing).
 - Structured artifacts are **optional** and must never be required for a workflow to be usable.
 
+### Session analytics context keys (`metrics_*`)
+
+The `projectSessionMetricsV2` projection (planned -- not yet implemented) reads a set of `metrics_*` context keys to build session attribution data. These keys are not validated by the engine -- nothing will fail if they are absent or malformed. But absent or wrong data produces permanently incorrect analytics with no error or warning.
+
+Set these keys in your step's `Capture:` footer.
+
+**SHA accumulation rule (critical)**
+
+`context_set` uses shallow merge: each key is replaced, not merged. If you set `metrics_commit_shas: ["abc123"]` at step 5 and then set `metrics_commit_shas: ["def456"]` at step 9, the value at step 9 is `["def456"]` -- `abc123` is permanently gone.
+
+Every step that adds commits must send the **full accumulated list** -- read the current value from context, append new SHAs, and send the complete list.
+
+```
+Example (correct): metrics_commit_shas: ["abc123", "def456", "ghi789"]
+Example (wrong):   metrics_commit_shas: ["ghi789"]  -- loses abc123 and def456
+```
+
+**Commit step `Capture:` footer** (copy this into every step that creates commits):
+
+```
+Capture (every time you commit code):
+- `metrics_commit_shas`: full accumulated list of ALL commit SHAs this session (read
+  current value from context, append new SHAs, send complete list)
+
+  WARNING: context uses shallow merge -- sending only the new SHAs will overwrite and
+  permanently lose earlier ones. Always send the full accumulated list.
+
+  Example (correct): metrics_commit_shas: ["abc123", "def456", "ghi789"]
+  Example (wrong):   metrics_commit_shas: ["ghi789"]  -- loses abc123 and def456
+```
+
+**Final handoff `Capture:` footer** (copy this into your final step):
+
+```
+Capture (at final handoff only):
+- `metrics_outcome`: one of 'success' | 'partial' | 'abandoned' | 'error'
+  - success: all acceptance criteria met, PR opened or merged
+  - partial: some criteria met but scope was reduced or items deferred
+  - abandoned: session stopped before meaningful completion
+  - error: session failed due to an unrecoverable error
+- `metrics_pr_numbers`: array of integer PR numbers created or updated (e.g. [123, 456])
+  - Must be integers, not URLs or strings
+- `metrics_files_changed`: integer count of files modified across all commits
+- `metrics_lines_added`: integer count of lines added across all commits
+- `metrics_lines_removed`: integer count of lines removed across all commits
+- `metrics_commit_shas`: final complete accumulated list of ALL commit SHAs this session
+  (same accumulation rule as commit steps -- full list, not just final-step SHAs)
+```
+
+Note: adding these keys to existing workflow JSON files (`coding-task-workflow-agentic.json` and others) is a separate follow-on PR. The templates above let you add them to new or custom workflows now.
+
 ### Assessment-gate authoring (v1)
 
 Assessment gates are now a shipped authoring/runtime feature, but the first slice is intentionally narrow.

package/docs/authoring.md

@@ -710,6 +710,28 @@ Canonical current rules for authoring good WorkRail workflows. workflow.schema.j
 - Saying a workflow is valid because the file parses even though registry resolution or runtime compilation can still fail
 
 
+## Context key conventions
+### metrics-context-accumulation
+- **Level**: recommended
+- **Status**: active
+- **Scope**: step.context-capture
+- **Rule**: When a step captures metrics_commit_shas, send the FULL accumulated SHA list every time -- not just the SHAs from the current step. context_set uses shallow merge: each key is replaced, not merged. Sending a partial list silently loses earlier SHAs.
+- **Why**: mergeContext uses shallow merge: metrics_commit_shas: ['abc'] at step 5 followed by ['def'] at step 9 permanently loses 'abc'. Flat keys require accumulation discipline to produce correct analytics attribution.
+- **Enforced by**: advisory
+
+**Checks**
+- Any step that adds new commits must first read the current metrics_commit_shas from context, append the new SHAs, and send the complete accumulated list.
+- metrics_outcome must be set only at final handoff steps, not at intermediate commit steps.
+- metrics_pr_numbers must be an array of integers (PR numbers), not URLs or strings.
+- Use flat top-level keys (metrics_commit_shas, not context.metrics.commit_shas) to exploit per-key merge semantics.
+- When starting to track mid-session, capture what you have and accumulate forward from that point.
+
+**Anti-patterns**
+- Sending only the current step's commits: metrics_commit_shas: ['def456'] when 'abc123' was set at an earlier step
+- Using a nested key context.metrics.commit_shas instead of the flat key metrics_commit_shas
+- Setting metrics_outcome at intermediate steps before the session outcome is known
+
+
 ## Artifacts and planning surfaces
 ### artifact-canonicality
 - **Level**: recommended

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "3.61.0",
+  "version": "3.63.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {

package/spec/authoring-spec.json

@@ -3,7 +3,7 @@
   "version": 3,
   "title": "WorkRail Authoring Rules",
   "purpose": "Canonical current rules for authoring good WorkRail workflows. workflow.schema.json remains the source of truth for legal structure.",
-  "lastReviewed": "2026-04-16",
+  "lastReviewed": "2026-04-22",
   "principles": [
     "Schema defines what is valid. These rules define what is good.",
     "Prefer current authoring rules over design rationale or historical notes.",
@@ -1361,6 +1361,33 @@
         }
       ]
     },
+    {
+      "id": "context-capture",
+      "title": "Context key conventions",
+      "rules": [
+        {
+          "id": "metrics-context-accumulation",
+          "status": "active",
+          "level": "recommended",
+          "scope": ["step.context-capture"],
+          "rule": "When a step captures metrics_commit_shas, send the FULL accumulated SHA list every time -- not just the SHAs from the current step. context_set uses shallow merge: each key is replaced, not merged. Sending a partial list silently loses earlier SHAs.",
+          "why": "mergeContext uses shallow merge: metrics_commit_shas: ['abc'] at step 5 followed by ['def'] at step 9 permanently loses 'abc'. Flat keys require accumulation discipline to produce correct analytics attribution.",
+          "enforcement": ["advisory"],
+          "checks": [
+            "Any step that adds new commits must first read the current metrics_commit_shas from context, append the new SHAs, and send the complete accumulated list.",
+            "metrics_outcome must be set only at final handoff steps, not at intermediate commit steps.",
+            "metrics_pr_numbers must be an array of integers (PR numbers), not URLs or strings.",
+            "Use flat top-level keys (metrics_commit_shas, not context.metrics.commit_shas) to exploit per-key merge semantics.",
+            "When starting to track mid-session, capture what you have and accumulate forward from that point."
+          ],
+          "antiPatterns": [
+            "Sending only the current step's commits: metrics_commit_shas: ['def456'] when 'abc123' was set at an earlier step",
+            "Using a nested key context.metrics.commit_shas instead of the flat key metrics_commit_shas",
+            "Setting metrics_outcome at intermediate steps before the session outcome is known"
+          ]
+        }
+      ]
+    },
     {
       "id": "artifacts",
       "title": "Artifacts and planning surfaces",