Merge remote-tracking branch 'origin/main' into tml-2733-migration-list-graph-review-followups

wmadden · wmadden · commit 7fb1b71b883d · 2026-05-30T16:36:23.000+02:00
Signed-off-by: Will Madden &lt;madden@prisma.io&gt;
diff --git a/package.json b/package.json
@@ -38,8 +38,9 @@
     "lint:docs": "node scripts/validate-package-readmes.mjs",
     "lint:manifests": "node scripts/validate-package-manifests.mjs",
     "lint:workflows": "node scripts/lint-workflow-triggers.mjs",
-    "test:scripts": "node --test scripts/lint-workflow-triggers.test.mjs scripts/validate-skills.test.mjs scripts/determine-version-utils.test.ts scripts/check-upgrade-coverage.test.mjs scripts/set-version-utils.test.ts scripts/check-publish-deps-pn-pins.test.mjs scripts/publish-packages-utils.test.mjs scripts/check-clean-tree.test.mjs scripts/lint-casts.test.mjs scripts/sync-agent-rules.test.mjs skills-contrib/drive-diagnose-run/test/load.test.ts skills-contrib/drive-diagnose-run/test/metrics.test.ts skills-contrib/drive-diagnose-run/test/invariants.test.ts skills-contrib/drive-diagnose-run/test/cascade-brief.test.ts skills-contrib/drive-diagnose-run/test/report.test.ts skills-contrib/drive-diagnose-run/test/posthoc.test.ts",
+    "test:scripts": "node --test scripts/lint-workflow-triggers.test.mjs scripts/validate-skills.test.mjs scripts/determine-version-utils.test.ts scripts/check-upgrade-coverage.test.mjs scripts/set-version-utils.test.ts scripts/check-publish-deps-pn-pins.test.mjs scripts/publish-packages-utils.test.mjs scripts/check-clean-tree.test.mjs scripts/lint-casts.test.mjs scripts/sync-agent-rules.test.mjs skills-contrib/drive-diagnose-run/test/load.test.ts skills-contrib/drive-diagnose-run/test/metrics.test.ts skills-contrib/drive-diagnose-run/test/invariants.test.ts skills-contrib/drive-diagnose-run/test/cascade-brief.test.ts skills-contrib/drive-diagnose-run/test/report.test.ts skills-contrib/drive-diagnose-run/test/posthoc.test.ts skills-contrib/drive-record-traces/test/emit.test.ts",
     "drive:diagnose": "node skills-contrib/drive-diagnose-run/cli.ts",
+    "drive:emit": "node skills-contrib/drive-record-traces/emit.ts",
     "bump-minor": "node scripts/bump-minor.ts",
     "check:publish-deps": "node scripts/check-publish-deps.mjs",
     "check:upgrade-coverage": "node scripts/check-upgrade-coverage.mjs",
diff --git a/skills-contrib/drive-diagnose-run/SKILL.md b/skills-contrib/drive-diagnose-run/SKILL.md
@@ -12,7 +12,7 @@ A **deterministic, LLM-free tool** that reads an emitted Drive `trace.jsonl` and
 
 ## What it is
 
-- `schema.ts` — arktype schemas for all 17 trace-event types, transcribed from the `drive-record-traces` skill (the source of truth for the vocabulary).
+- arktype schemas — imported directly from the canonical `skills-contrib/drive-record-traces/schema.ts` (the single source of truth for the trace-event vocabulary).
 - `load.ts` — JSONL loader: parses + validates each line; collects errors with line numbers instead of throwing.
 - `metrics.ts` — diagnostic-metric functions over a `TraceEvent[]` (rework rate, brief reissues, spec amendments, plan amendments, I12 halts, tier mix, wall-clock, etc.). Metric names count instability: lower is better, `0` means the artefact held.
 - `assertions/` — one checker per Drive invariant (I1–I12), cascade-redesign rule, and brief-discipline anti-pattern; each returns `pass | fail | not-checkable` with evidence refs.
@@ -56,4 +56,4 @@ A zero-dependency validator is a possible future improvement; for now `arktype`
 
 ## Relationship to the trace vocabulary
 
-Event schemas in `schema.ts` are transcribed from the **`drive-record-traces`** skill, which is the single source of truth for the trace-event vocabulary and emission protocol. If a schema changes, update `schema.ts` to match `drive-record-traces`.
+`drive-diagnose-run` imports schemas directly from the canonical `skills-contrib/drive-record-traces/schema.ts`, which is the single source of truth for the trace-event vocabulary and emission protocol. Schema changes go in `drive-record-traces`.
diff --git a/skills-contrib/drive-diagnose-run/assertions/brief.ts b/skills-contrib/drive-diagnose-run/assertions/brief.ts
@@ -1,4 +1,4 @@
-import type { TraceEvent } from '../schema.ts';
+import type { TraceEvent } from '../../drive-record-traces/schema.ts';
 import type { AssertionResult, TraceRef } from './types.ts';
 
 function eventsOfType<T extends TraceEvent['event_type']>(
diff --git a/skills-contrib/drive-diagnose-run/assertions/cascade.ts b/skills-contrib/drive-diagnose-run/assertions/cascade.ts
@@ -1,4 +1,4 @@
-import type { TraceEvent } from '../schema.ts';
+import type { TraceEvent } from '../../drive-record-traces/schema.ts';
 import type { AssertionResult, TraceRef } from './types.ts';
 
 function eventsOfType<T extends TraceEvent['event_type']>(
diff --git a/skills-contrib/drive-diagnose-run/assertions/index.ts b/skills-contrib/drive-diagnose-run/assertions/index.ts
@@ -1,4 +1,4 @@
-import type { TraceEvent } from '../schema.ts';
+import type { TraceEvent } from '../../drive-record-traces/schema.ts';
 import { checkBriefDiscipline } from './brief.ts';
 import { checkCascadeRules } from './cascade.ts';
 import { checkInvariants } from './invariants.ts';
diff --git a/skills-contrib/drive-diagnose-run/assertions/invariants.ts b/skills-contrib/drive-diagnose-run/assertions/invariants.ts
@@ -1,4 +1,4 @@
-import type { TraceEvent } from '../schema.ts';
+import type { TraceEvent } from '../../drive-record-traces/schema.ts';
 import type { AssertionResult, TraceRef } from './types.ts';
 
 function eventsOfType<T extends TraceEvent['event_type']>(
diff --git a/skills-contrib/drive-diagnose-run/cli.ts b/skills-contrib/drive-diagnose-run/cli.ts
@@ -1,11 +1,11 @@
 import { writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import type { TraceEvent } from '../drive-record-traces/schema.ts';
 import { runAssertions } from './assertions/index.ts';
 import { loadTrace } from './load.ts';
 import { computeMetrics } from './metrics.ts';
 import { parseTranscript } from './posthoc.ts';
 import { renderReport } from './report.ts';
-import type { TraceEvent } from './schema.ts';
 
 function getProjectRunIds(events: TraceEvent[]): string[] {
   const ids = new Set<string>();
diff --git a/skills-contrib/drive-diagnose-run/load.ts b/skills-contrib/drive-diagnose-run/load.ts
@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { type } from 'arktype';
-import type { TraceEvent } from './schema.ts';
-import { KNOWN_EVENT_TYPES, Slice1TraceEvent } from './schema.ts';
+import type { TraceEvent } from '../drive-record-traces/schema.ts';
+import { KNOWN_EVENT_TYPES, Slice1TraceEvent } from '../drive-record-traces/schema.ts';
 
 export type LoadError = { line: number; raw: string; problem: string };
 
diff --git a/skills-contrib/drive-diagnose-run/metrics.ts b/skills-contrib/drive-diagnose-run/metrics.ts
@@ -1,4 +1,4 @@
-import type { TraceEvent } from './schema.ts';
+import type { TraceEvent } from '../drive-record-traces/schema.ts';
 
 // Narrows the event union to the events of the requested type using a type
 // predicate, so no bare `as` cast is needed at call sites.
diff --git a/skills-contrib/drive-diagnose-run/test/cascade-brief.test.ts b/skills-contrib/drive-diagnose-run/test/cascade-brief.test.ts
@@ -1,11 +1,11 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import { fileURLToPath } from 'node:url';
+import type { TraceEvent } from '../../drive-record-traces/schema.ts';
 import { checkBriefDiscipline } from '../assertions/brief.ts';
 import { checkCascadeRules } from '../assertions/cascade.ts';
 import { runAssertions } from '../assertions/index.ts';
 import { loadTrace } from '../load.ts';
-import type { TraceEvent } from '../schema.ts';
 
 const TRACE_PATH = fileURLToPath(new URL('./fixtures/sample-trace.jsonl', import.meta.url));
 
diff --git a/skills-contrib/drive-diagnose-run/test/invariants.test.ts b/skills-contrib/drive-diagnose-run/test/invariants.test.ts
@@ -1,9 +1,9 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import { fileURLToPath } from 'node:url';
+import type { TraceEvent } from '../../drive-record-traces/schema.ts';
 import { checkInvariants } from '../assertions/invariants.ts';
 import { loadTrace } from '../load.ts';
-import type { TraceEvent } from '../schema.ts';
 
 const TRACE_PATH = fileURLToPath(new URL('./fixtures/sample-trace.jsonl', import.meta.url));
 
diff --git a/skills-contrib/drive-diagnose-run/test/metrics.test.ts b/skills-contrib/drive-diagnose-run/test/metrics.test.ts
@@ -1,9 +1,9 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import { fileURLToPath } from 'node:url';
+import type { TraceEvent } from '../../drive-record-traces/schema.ts';
 import { loadTrace } from '../load.ts';
 import { computeMetrics } from '../metrics.ts';
-import type { TraceEvent } from '../schema.ts';
 
 const TRACE_PATH = fileURLToPath(new URL('./fixtures/sample-trace.jsonl', import.meta.url));
 
diff --git a/skills-contrib/drive-record-traces/SKILL.md b/skills-contrib/drive-record-traces/SKILL.md
@@ -14,12 +14,17 @@ description: >
 
 # Drive: Record Traces
 
-A **library skill** — it is not invoked to *do* work; it is read by other skills that emit trace events, and by tooling that reads them. It carries two reference documents and the rules that bind them.
+A **library skill** — it is not invoked to *do* work; it is read by other skills that emit trace events, and by tooling that reads them. It carries two reference documents, an executable emitter, and the rules that bind them.
 
 ## What this skill owns
 
-- [`events.md`](./events.md) — the versioned **trace-event vocabulary**: the common envelope, every event type, its trigger condition, its emitting skill(s), its payload schema (with arktype types), and JSONL examples. This is the source of truth for *what an event is*.
-- [`emission.md`](./emission.md) — the shared **emission protocol**: trace-file path resolution (in-project / orphan-slice / direct-change), append-only JSONL conventions, the canonical `Shell` + `printf … >>` append mechanic, and the existence-check pattern that selects `*-authored` vs `*-amended` events.
+- [`events.md`](./events.md) — the versioned **trace-event vocabulary**: the common envelope, every event type, its trigger condition, its emitting skill(s), its payload schema, and JSONL examples. This is the source of truth for *what an event is*. The machine-readable arktype schema lives in [`schema.ts`](./schema.ts).
+- [`emission.md`](./emission.md) — the shared **emission protocol**: trace-file path resolution (in-project / orphan-slice / direct-change), append-only JSONL conventions, the deterministic `emit.ts` invocation that appends events, and the existence-check pattern that selects `*-authored` vs `*-amended` events.
+- [`emit.ts`](./emit.ts) — the **deterministic emitter CLI** that enforces the vocabulary and protocol. It owns the envelope (`event_id`, `schema_version`, `ts`), validates each fully-merged event against `schema.ts` fail-closed (a malformed event exits non-zero and writes nothing), and appends exactly one compact JSON line. Instrumented skills invoke it instead of hand-appending. In this repo, `pnpm drive:emit` is the shortcut.
+
+## Prerequisites (for the emitter)
+
+`emit.ts` requires Node with native TypeScript execution (Node 24+) and the `arktype` package. In this repo `arktype` is already available via the workspace root `node_modules` — no extra install needed. In another repo, install it before emitting (`npm install arktype`).
 
 ## Why a library skill (not project-local docs)
 
@@ -29,7 +34,7 @@ Instrumentation is a property of the **skills**, not of any one project. When th
 
 An instrumented skill carries a one-to-three-line **Emit** blockquote at each workflow transition point. The blockquote names the event type, lists the payload fields the orchestrator must compute, and refers to this skill **by name** (the runtime resolves and loads it) for the schema + mechanics — no relative path:
 
-> **Emit `{event_type}`:** Build the envelope (`event_id`, `schema_version: "1"`, `ts`, `project_run_id`, `orchestrator_agent_id`) plus this event's payload fields (see the `drive-record-traces` skill — `events.md` § `{event_type}`). Append one JSON line per the same skill's `emission.md` § Append protocol.
+> **Emit `{event_type}`:** Compute this event's payload fields (see the `drive-record-traces` skill — `events.md` § `{event_type}`), then invoke that skill's emitter per its `emission.md` § Append protocol: `--event {event_type} --payload '<payload-only fields>'` with `--trace-file` and `--project-run-id` from session context. The emitter owns the envelope and validates before appending.
 
 For spec/plan writes that pick between `*-authored` and `*-amended`, the Emit step also applies the existence-check pattern in [`emission.md`](./emission.md) § Existence-check pattern.
 
diff --git a/skills-contrib/drive-record-traces/emission.md b/skills-contrib/drive-record-traces/emission.md
diff --git a/skills-contrib/drive-record-traces/emit.ts b/skills-contrib/drive-record-traces/emit.ts
diff --git a/skills-contrib/drive-record-traces/events.md b/skills-contrib/drive-record-traces/events.md
diff --git a/skills-contrib/drive-record-traces/schema.ts b/skills-contrib/drive-record-traces/schema.ts
diff --git a/skills-contrib/drive-record-traces/test/emit.test.ts b/skills-contrib/drive-record-traces/test/emit.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import type { TraceEvent } from '../schema.ts';`
	`1`	`+import type { TraceEvent } from '../../drive-record-traces/schema.ts';`
`2`	`2`	`import type { AssertionResult, TraceRef } from './types.ts';`
`3`	`3`
`4`	`4`	`function eventsOfType<T extends TraceEvent['event_type']>(`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import type { TraceEvent } from './schema.ts';`
	`1`	`+import type { TraceEvent } from '../drive-record-traces/schema.ts';`
`2`	`2`
`3`	`3`	`// Narrows the event union to the events of the requested type using a type`
`4`	`4`	// predicate, so no bare `as` cast is needed at call sites.