@mmnto/totem 1.14.11 → 1.14.12

package/dist/compile-lesson.d.ts

@@ -1,4 +1,4 @@
-import type { CompiledRule, CompilerOutput, RegexValidation } from './compiler-schema.js';
+import type { CompiledRule, CompilerOutput, NonCompilableReasonCode, RegexValidation } from './compiler-schema.js';
 import type { RuleTestResult } from './rule-tester.js';
 export interface LessonInput {
     index: number;
@@ -11,20 +11,59 @@ export interface LessonInput {
  * downstream consumers (totem doctor, Layer 4 fallthrough reporting per ADR-088)
  * can distinguish why a lesson produced no rule without string-matching
  * human-readable messages.
+ *
+ * mmnto-ai/totem#1481 aligned this internal type 1:1 with the persisted
+ * `NonCompilableReasonCode` enum so ledger writers can pass the code through
+ * without a mapping table. `'non-compilable'` renamed to `'out-of-scope'`,
+ * `'security-verify-rejected'` renamed to `'security-rule-rejected'`, and
+ * four producer-facing codes joined: `'no-pattern-generated'`,
+ * `'pattern-syntax-invalid'`, `'pattern-zero-match'`, `'no-pattern-found'`.
+ * Fresh compile runs MUST NOT emit `'legacy-unknown'`; that sentinel exists
+ * solely for migrating pre-#1481 2-tuples.
+ */
+export type CompileLessonReasonCode = Exclude<NonCompilableReasonCode, 'legacy-unknown'>;
+/**
+ * Single event inside a lesson's compile pipeline. Appended to a per-lesson
+ * `trace` array on every pipeline step (generate / verify / retry / result)
+ * and surfaced via `CompileLessonResult.trace` for the CLI `--verbose`
+ * renderer (mmnto-ai/totem#1482).
+ *
+ * `layer` numbers align with the ADR-088 staging (1 = manual, 2 = example-
+ * based, 3 = Layer 3 LLM with verify-retry). Consumers MUST tolerate unknown
+ * layer numbers so a future ADR-088 phase (dedicated Layer 1 / Layer 2
+ * telemetry) can emit without breaking the renderer.
+ *
+ * `patternHash` is a stable 16-character sha256 prefix of the emitted
+ * pattern, included only on `generate` events. Callers use it to correlate
+ * retries ("this retry produced the same pattern") without forwarding the
+ * pattern string itself.
+ *
+ * `reasonCode` is only set on the terminal `result` event when the lesson
+ * skipped. A compiled or failed lesson omits the field.
  */
-export type CompileLessonReasonCode = 'non-compilable' | 'missing-badexample' | 'verify-retry-exhausted' | 'security-verify-rejected';
+export interface LayerTraceEvent {
+    layer: number;
+    action: 'generate' | 'verify' | 'retry' | 'result';
+    outcome: string;
+    patternHash?: string;
+    reasonCode?: Exclude<NonCompilableReasonCode, 'legacy-unknown'>;
+}
 export type CompileLessonResult = {
     status: 'compiled';
     rule: CompiledRule;
+    trace?: LayerTraceEvent[];
 } | {
     status: 'skipped';
     hash: string;
     reason?: string;
     reasonCode: CompileLessonReasonCode;
+    trace?: LayerTraceEvent[];
 } | {
     status: 'failed';
+    trace?: LayerTraceEvent[];
 } | {
     status: 'noop';
+    trace?: LayerTraceEvent[];
 };
 export interface CompileLessonCallbacks {
     onWarn?: (heading: string, message: string) => void;
@@ -160,6 +199,23 @@ export declare function formatExampleFailure(result: RuleTestResult): string;
  * Returns { rule, rejectReason } so callers can report why a pattern was rejected.
  */
 export declare function buildManualRule(lesson: LessonInput, existingByHash: Map<string, CompiledRule>): BuildRuleResult;
+/**
+ * Security-context signal for the missing-Example-Hit check. Either the
+ * compile orchestrator asserts the pack is security-scoped
+ * (`deps.securityContext === true`) OR the rule under construction already
+ * carries `immutable: true` (set by the pack manifest, ADR-089). Both
+ * paths trigger the zero-tolerance reject per ADR-088 Decision 3.
+ *
+ * The LLM-emitted `CompilerOutput` does not currently carry an `immutable`
+ * field (packs set it at pack-merge time), so the second signal only
+ * engages on the Pipeline 1 manual-rule path where `buildManualRule`
+ * could synthesize an immutable rule directly. A future change that
+ * threads `immutable` through `CompilerOutput` can wire Pipeline 2/3
+ * into this helper without touching the call sites.
+ */
+export declare function isSecurityContext(deps: CompileLessonDeps, rule?: {
+    immutable?: boolean;
+} | null): boolean;
 /**
  * Compile a single lesson into a rule.
  * Handles both manual patterns (zero LLM) and LLM-compiled patterns.

package/dist/compile-lesson.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile-lesson.d.ts","sourceRoot":"","sources":["../src/compile-lesson.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compile-lesson.d.ts","sourceRoot":"","sources":["../src/compile-lesson.ts"],"names":[],"mappings":"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"}

package/dist/compile-lesson.js

@@ -1,8 +1,13 @@
+import { createHash } from 'node:crypto';
 import { Lang, parse } from '@ast-grep/napi';
 import { runSmokeGate } from './compile-smoke-gate.js';
 import { engineFields, sanitizeFileGlobs, validateRegex } from './compiler.js';
 import { extractBadGoodSnippets, extractManualPattern, extractRuleExamples, } from './lesson-pattern.js';
 import { testRule } from './rule-tester.js';
+/** Produce a stable short hash of a pattern string for trace correlation. */
+function hashPattern(pattern) {
+    return createHash('sha256').update(pattern).digest('hex').slice(0, 16);
+}
 // ─── ast-grep pattern validation ───────────────────
 /**
  * Compile-time validation for ast-grep patterns (#1062, #1339).
@@ -410,6 +415,40 @@ export function buildManualRule(lesson, existingByHash) {
     };
 }
 // ─── Single-lesson compilation ──────────────────────
+/**
+ * Check whether the lesson body carries a non-empty Example Hit block.
+ * ADR-088 Phase 1 Layer 3 (mmnto-ai/totem#1480): rules compiled without an
+ * Example Hit ship as `unverified: true` (non-security) or fail outright
+ * (security). Empty code fences like ```ts\n``` are treated as absent —
+ * `trim()` is applied before the length check.
+ */
+function hasExampleHits(body) {
+    const examples = extractRuleExamples(body);
+    if (!examples)
+        return false;
+    return examples.hits.some((line) => line.trim().length > 0);
+}
+/**
+ * Security-context signal for the missing-Example-Hit check. Either the
+ * compile orchestrator asserts the pack is security-scoped
+ * (`deps.securityContext === true`) OR the rule under construction already
+ * carries `immutable: true` (set by the pack manifest, ADR-089). Both
+ * paths trigger the zero-tolerance reject per ADR-088 Decision 3.
+ *
+ * The LLM-emitted `CompilerOutput` does not currently carry an `immutable`
+ * field (packs set it at pack-merge time), so the second signal only
+ * engages on the Pipeline 1 manual-rule path where `buildManualRule`
+ * could synthesize an immutable rule directly. A future change that
+ * threads `immutable` through `CompilerOutput` can wire Pipeline 2/3
+ * into this helper without touching the call sites.
+ */
+export function isSecurityContext(deps, rule) {
+    if (deps.securityContext === true)
+        return true;
+    if (rule?.immutable === true)
+        return true;
+    return false;
+}
 /**
  * Compile a single lesson into a rule.
  * Handles both manual patterns (zero LLM) and LLM-compiled patterns.
@@ -417,21 +456,79 @@ export function buildManualRule(lesson, existingByHash) {
  */
 export async function compileLesson(lesson, compilerPrompt, deps) {
     const { parseCompilerResponse, runOrchestrator, existingByHash, callbacks } = deps;
+    const exampleHitPresent = hasExampleHits(lesson.body);
+    // Trace buffer (mmnto-ai/totem#1482). Populated unconditionally across all
+    // three pipelines so the CLI can choose to render it under --verbose
+    // without a per-call gate. Cost of empty-or-small arrays per lesson is
+    // negligible; gating would fork the test surface.
+    const trace = [];
     // ── Pipeline 1: Manual pattern (zero LLM) ────────
     const manualResult = buildManualRule(lesson, existingByHash);
     if (manualResult.rule) {
+        // ADR-088 Phase 1 Layer 3 (mmnto-ai/totem#1480): security-scoped manual
+        // rules without an Example Hit are rejected outright.
+        if (!exampleHitPresent && isSecurityContext(deps, manualResult.rule)) {
+            const reason = 'Security rule missing Example Hit block (manual)';
+            callbacks?.onWarn?.(lesson.heading, `${reason} — rejecting`);
+            trace.push({
+                layer: 1,
+                action: 'result',
+                outcome: 'skipped',
+                reasonCode: 'security-rule-rejected',
+            });
+            return {
+                status: 'skipped',
+                hash: lesson.hash,
+                reason,
+                reasonCode: 'security-rule-rejected',
+                trace,
+            };
+        }
         const testResult = verifyRuleExamples(manualResult.rule, lesson.body);
         if (testResult && !testResult.passed) {
+            // A manual rule that failed its own inline examples is authoring
+            // error territory. Keep the existing 'failed' contract so the
+            // lesson stays pending rather than landing in nonCompilable.
+            // Pre-#1480 `verifyRuleExamples` fired on any hit or miss; the
+            // `hasExampleHits` check guards the unverified flag below without
+            // changing the verify gate itself.
             callbacks?.onWarn?.(lesson.heading, formatExampleFailure(testResult));
-            return { status: 'failed' };
+            trace.push({ layer: 1, action: 'result', outcome: 'failed' });
+            return { status: 'failed', trace };
         }
-        return { status: 'compiled', rule: manualResult.rule };
+        if (!exampleHitPresent) {
+            manualResult.rule.unverified = true;
+        }
+        trace.push({ layer: 1, action: 'result', outcome: 'compiled' });
+        return { status: 'compiled', rule: manualResult.rule, trace };
     }
     if (manualResult.rejectReason) {
         callbacks?.onWarn?.(lesson.heading, manualResult.rejectReason);
-        return { status: 'failed' };
+        trace.push({ layer: 1, action: 'result', outcome: 'failed' });
+        return { status: 'failed', trace };
     }
     // manualResult.rule === null && no rejectReason → no manual pattern, proceed to Pipeline 3 or 2
+    // ADR-088 Phase 1 Layer 3 (mmnto-ai/totem#1480): security rules that enter
+    // the LLM path with no Example Hit short-circuit before the orchestrator
+    // call. Compile has no ground truth to verify against, and zero-tolerance
+    // per Decision 3 leaves nothing to retry.
+    if (!exampleHitPresent && deps.securityContext === true) {
+        const reason = 'Security rule missing Example Hit block';
+        callbacks?.onWarn?.(lesson.heading, `${reason} — rejecting`);
+        trace.push({
+            layer: 3,
+            action: 'result',
+            outcome: 'skipped',
+            reasonCode: 'security-rule-rejected',
+        });
+        return {
+            status: 'skipped',
+            hash: lesson.hash,
+            reason,
+            reasonCode: 'security-rule-rejected',
+            trace,
+        };
+    }
     // ── Pipeline 3: Example-based compilation (Bad/Good snippets) ──
     const snippets = extractBadGoodSnippets(lesson.body);
     if (snippets) {
@@ -455,22 +552,53 @@ export async function compileLesson(lesson, compilerPrompt, deps) {
             lesson.body,
         ].join('\n');
         const response = await runOrchestrator(userPrompt, systemPrompt);
-        if (response == null)
-            return { status: 'noop' };
+        if (response == null) {
+            trace.push({ layer: 2, action: 'result', outcome: 'noop' });
+            return { status: 'noop', trace };
+        }
         const parsed = parseCompilerResponse(response);
         if (!parsed) {
             callbacks?.onWarn?.(lesson.heading, 'Pipeline 3: failed to parse LLM response — skipping');
-            return { status: 'failed' };
+            trace.push({
+                layer: 2,
+                action: 'result',
+                outcome: 'skipped',
+                reasonCode: 'pattern-syntax-invalid',
+            });
+            return {
+                status: 'skipped',
+                hash: lesson.hash,
+                reason: 'Pipeline 3: failed to parse LLM response',
+                reasonCode: 'pattern-syntax-invalid',
+                trace,
+            };
         }
         if (!parsed.compilable) {
             callbacks?.onDim?.(lesson.heading, 'Pipeline 3: not compilable — skipping');
+            trace.push({
+                layer: 2,
+                action: 'result',
+                outcome: 'skipped',
+                reasonCode: 'out-of-scope',
+            });
             return {
                 status: 'skipped',
                 hash: lesson.hash,
                 reason: parsed.reason,
-                reasonCode: 'non-compilable',
+                reasonCode: 'out-of-scope',
+                trace,
             };
         }
+        // Only include `patternHash` when the parsed output actually carries a
+        // pattern. Hashing the `(pattern unavailable)` fallback would make a
+        // failed generation look identical to a successful one in verbose output.
+        const pipeline3HasPattern = hasExtractablePattern(parsed);
+        trace.push({
+            layer: 2,
+            action: 'generate',
+            outcome: 'produced',
+            ...(pipeline3HasPattern ? { patternHash: hashPattern(extractPatternString(parsed)) } : {}),
+        });
         // mmnto/totem#1408: Pipeline 3 reuses its Bad snippet as the smoke-gate
         // target. The LLM may or may not echo the snippet back in parsed.badExample;
         // the override guarantees the gate has something to work with regardless.
@@ -479,8 +607,18 @@ export async function compileLesson(lesson, compilerPrompt, deps) {
             badExampleOverride: snippets.bad.join('\n'),
         });
         if (!ruleResult.rule) {
-            callbacks?.onWarn?.(lesson.heading, `Pipeline 3: ${ruleResult.rejectReason ?? 'Unknown error'} — skipping`);
-            return { status: 'failed' };
+            const rejectReason = ruleResult.rejectReason ?? 'Unknown error';
+            callbacks?.onWarn?.(lesson.heading, `Pipeline 3: ${rejectReason} — skipping`);
+            const reasonCode = classifyBuildRejectReason(rejectReason);
+            trace.push({ layer: 2, action: 'verify', outcome: 'rejected' });
+            trace.push({ layer: 2, action: 'result', outcome: 'skipped', reasonCode });
+            return {
+                status: 'skipped',
+                hash: lesson.hash,
+                reason: `Pipeline 3: ${rejectReason}`,
+                reasonCode,
+                trace,
+            };
         }
         // Self-verify: at least one Bad line should trigger, no Good line should trigger
         const virtualPath = deriveVirtualFilePath(ruleResult.rule);
@@ -497,9 +635,20 @@ export async function compileLesson(lesson, compilerPrompt, deps) {
         const badCaught = snippets.bad.length - testResult.missedFails.length;
         if (badCaught === 0 || testResult.falsePositives.length > 0) {
             callbacks?.onWarn?.(lesson.heading, 'Pipeline 3: generated rule failed self-verification against Bad/Good snippets — skipping');
-            return { status: 'failed' };
+            trace.push({ layer: 2, action: 'verify', outcome: 'self-test-failed' });
+            trace.push({ layer: 2, action: 'result', outcome: 'failed' });
+            return { status: 'failed', trace };
         }
-        return { status: 'compiled', rule: ruleResult.rule };
+        trace.push({ layer: 2, action: 'verify', outcome: 'passed' });
+        trace.push({ layer: 2, action: 'result', outcome: 'compiled' });
+        // Pipeline 3 rules are example-based — they always ship with a Bad snippet
+        // by construction. Flag unverified only when the lesson body itself omits
+        // the canonical Example Hit block, keeping the signal aligned with the
+        // lesson-level ground-truth rather than the Pipeline 3 self-test.
+        if (!exampleHitPresent) {
+            ruleResult.rule.unverified = true;
+        }
+        return { status: 'compiled', rule: ruleResult.rule, trace };
     }
     // ── Pipeline 2 / Layer 3: LLM compilation with verify-retry loop ──
     // ADR-088 Phase 1 (mmnto-ai/totem#1479). The compilerPrompt (ast-grep
@@ -515,14 +664,14 @@ export async function compileLesson(lesson, compilerPrompt, deps) {
     //     "Previous Attempt Failed Verification" section that names the
     //     failed pattern and the badExample it could not match, then call
     //     the LLM again. Up to MAX_VERIFY_ATTEMPTS total attempts.
-    //   - Security context (deps.securityContext === true) disables retry:
-    //     a failing verify rejects outright with reasonCode
-    //     'security-verify-rejected' per ADR-088 Decision 3 (zero
-    //     tolerance).
+    //   - Security context (deps.securityContext === true or the LLM-emitted
+    //     rule declared `immutable: true`) disables retry: a failing verify
+    //     rejects outright with reasonCode 'security-rule-rejected' per
+    //     ADR-088 Decision 3 (zero tolerance).
     //   - On attempt exhaustion, fall through to Layer 4 with reasonCode
     //     'verify-retry-exhausted'. The lesson is recorded as skipped
     //     with a machine-readable reason so totem doctor and downstream
-    //     tooling can distinguish this from 'non-compilable'.
+    //     tooling can distinguish this from 'out-of-scope'.
     const MAX_VERIFY_ATTEMPTS = 3;
     let previousFailure = null;
     for (let attempt = 1; attempt <= MAX_VERIFY_ATTEMPTS; attempt++) {
@@ -536,22 +685,53 @@ export async function compileLesson(lesson, compilerPrompt, deps) {
         userPromptParts.push('## Lesson to Compile', `Heading: ${lesson.heading}`, lesson.body);
         const userPrompt = userPromptParts.join('\n\n');
         const response = await runOrchestrator(userPrompt, compilerPrompt);
-        if (response == null)
-            return { status: 'noop' };
+        if (response == null) {
+            trace.push({ layer: 3, action: 'result', outcome: 'noop' });
+            return { status: 'noop', trace };
+        }
         const parsed = parseCompilerResponse(response);
         if (!parsed) {
             callbacks?.onWarn?.(lesson.heading, 'Failed to parse LLM response — skipping');
-            return { status: 'failed' };
+            trace.push({
+                layer: 3,
+                action: 'result',
+                outcome: 'skipped',
+                reasonCode: 'pattern-syntax-invalid',
+            });
+            return {
+                status: 'skipped',
+                hash: lesson.hash,
+                reason: 'Failed to parse LLM response',
+                reasonCode: 'pattern-syntax-invalid',
+                trace,
+            };
         }
         if (!parsed.compilable) {
             callbacks?.onDim?.(lesson.heading, 'Not compilable (conceptual/architectural) — skipping');
+            trace.push({
+                layer: 3,
+                action: 'result',
+                outcome: 'skipped',
+                reasonCode: 'out-of-scope',
+            });
             return {
                 status: 'skipped',
                 hash: lesson.hash,
                 reason: parsed.reason,
-                reasonCode: 'non-compilable',
+                reasonCode: 'out-of-scope',
+                trace,
             };
         }
+        // Only include `patternHash` when the parsed output actually carries a
+        // pattern. Hashing the `(pattern unavailable)` fallback would make a
+        // failed generation look identical to a successful one in verbose output.
+        const currentHasPattern = hasExtractablePattern(parsed);
+        trace.push({
+            layer: 3,
+            action: 'generate',
+            outcome: `attempt-${attempt}`,
+            ...(currentHasPattern ? { patternHash: hashPattern(extractPatternString(parsed)) } : {}),
+        });
         // Smoke gate enforcement lives in buildCompiledRule (mmnto-ai/totem#1408).
         // Rules without a badExample, or whose badExample fails to match the
         // pattern, come back with rule === null and a rejectReason. Classify the
@@ -570,12 +750,21 @@ export async function compileLesson(lesson, compilerPrompt, deps) {
         if (ruleResult.rule) {
             const testResult = verifyRuleExamples(ruleResult.rule, lesson.body);
             if (!testResult || testResult.passed) {
-                return { status: 'compiled', rule: ruleResult.rule };
+                // ADR-088 Phase 1 Layer 3 (mmnto-ai/totem#1480): flag rules compiled
+                // without a non-empty Example Hit as unverified, even when the
+                // lesson carried an Example Miss (the miss still got verified).
+                if (!exampleHitPresent) {
+                    ruleResult.rule.unverified = true;
+                }
+                trace.push({ layer: 3, action: 'verify', outcome: 'MATCH' });
+                trace.push({ layer: 3, action: 'result', outcome: 'compiled' });
+                return { status: 'compiled', rule: ruleResult.rule, trace };
             }
             // Example Hit/Miss verification failed against the lesson's ground
             // truth. ADR-088 AC: "verifies every LLM-generated pattern against
             // the lesson's Example Hit block. Zero-match triggers a retry."
             retryReason = formatExampleFailure(testResult);
+            trace.push({ layer: 3, action: 'verify', outcome: 'example-hit-miss' });
             // The snippet the retry directive should show is the Example Hit
             // line the pattern missed, not the LLM's own badExample (which the
             // pattern did match, since the smoke gate passed). If missedFails
@@ -595,38 +784,64 @@ export async function compileLesson(lesson, compilerPrompt, deps) {
             // Short-circuit to skipped with a distinct reasonCode.
             if (rejectReason.includes('missing badExample')) {
                 callbacks?.onWarn?.(lesson.heading, `${rejectReason} — skipping`);
+                trace.push({ layer: 3, action: 'verify', outcome: 'missing-badexample' });
+                trace.push({
+                    layer: 3,
+                    action: 'result',
+                    outcome: 'skipped',
+                    reasonCode: 'missing-badexample',
+                });
                 return {
                     status: 'skipped',
                     hash: lesson.hash,
                     reason: rejectReason,
                     reasonCode: 'missing-badexample',
+                    trace,
                 };
             }
             // Only smoke-gate zero-match against the LLM's own badExample is
             // retry-eligible. Validator-level rejections — invalid regex,
             // ast-grep parse errors, self-suppression guards — are terminal.
             // Retrying them produces more invalid patterns and wastes tokens.
-            // 'failed' keeps the rule pending for a future recompile rather
-            // than marking it permanently nonCompilable.
+            // Record a machine-readable code in the ledger so `totem doctor`
+            // and downstream telemetry can distinguish syntax rejections from
+            // retry-exhaustion.
             const isZeroMatch = rejectReason.startsWith('smoke gate: zero matches');
             if (!isZeroMatch) {
-                callbacks?.onWarn?.(lesson.heading, `${rejectReason} — failing`);
-                return { status: 'failed' };
+                callbacks?.onWarn?.(lesson.heading, `${rejectReason} — skipping`);
+                const reasonCode = classifyBuildRejectReason(rejectReason);
+                trace.push({ layer: 3, action: 'verify', outcome: 'validator-rejected' });
+                trace.push({ layer: 3, action: 'result', outcome: 'skipped', reasonCode });
+                return {
+                    status: 'skipped',
+                    hash: lesson.hash,
+                    reason: rejectReason,
+                    reasonCode,
+                    trace,
+                };
             }
             retryReason = rejectReason;
             retrySnippet = parsed.badExample ?? '(no badExample emitted)';
+            trace.push({ layer: 3, action: 'verify', outcome: 'smoke-gate-zero-match' });
         }
         // Shared retry path. Triggered by smoke-gate zero-match OR by
         // Example Hit/Miss verify failure. Both carry a retryReason that
         // threads back into the next LLM attempt's user prompt.
         // ADR-088 Decision 3: security rules zero-tolerance. No retry.
-        if (deps.securityContext === true) {
+        if (isSecurityContext(deps, ruleResult.rule)) {
             callbacks?.onWarn?.(lesson.heading, `Security rule rejected on verify failure (no retry): ${retryReason}`);
+            trace.push({
+                layer: 3,
+                action: 'result',
+                outcome: 'skipped',
+                reasonCode: 'security-rule-rejected',
+            });
             return {
                 status: 'skipped',
                 hash: lesson.hash,
                 reason: retryReason,
-                reasonCode: 'security-verify-rejected',
+                reasonCode: 'security-rule-rejected',
+                trace,
             };
         }
         if (attempt < MAX_VERIFY_ATTEMPTS) {
@@ -636,22 +851,68 @@ export async function compileLesson(lesson, compilerPrompt, deps) {
                 reason: retryReason,
             };
             callbacks?.onDim?.(lesson.heading, `Verify failed (attempt ${attempt}/${MAX_VERIFY_ATTEMPTS}): ${retryReason} — retrying`);
+            trace.push({ layer: 3, action: 'retry', outcome: `attempt-${attempt + 1}-scheduled` });
             continue;
         }
         // Attempts exhausted → Layer 4 fallthrough per ADR-088.
         callbacks?.onWarn?.(lesson.heading, `Verify retry exhausted after ${MAX_VERIFY_ATTEMPTS} attempts: ${retryReason} — skipping`);
+        trace.push({
+            layer: 3,
+            action: 'result',
+            outcome: 'skipped',
+            reasonCode: 'verify-retry-exhausted',
+        });
         return {
             status: 'skipped',
             hash: lesson.hash,
             reason: `Verify retry exhausted after ${MAX_VERIFY_ATTEMPTS} attempts: ${retryReason}`,
             reasonCode: 'verify-retry-exhausted',
+            trace,
         };
     }
     // Unreachable: every path inside the loop returns. Kept to satisfy the
-    // return-type checker without using a non-null assertion dance.
-    return { status: 'failed' };
+    // return-type checker without using a non-null assertion dance. Push a
+    // terminal result event defensively so any caller relying on the
+    // terminal-result invariant still sees one even if the loop ever leaks.
+    trace.push({ layer: 3, action: 'result', outcome: 'failed' });
+    return { status: 'failed', trace };
 }
 // ─── Retry loop helpers (ADR-088 Layer 3) ──────────
+/**
+ * Map a `buildCompiledRule` rejectReason string to a machine-readable
+ * `CompileLessonReasonCode`. Substring matching is deliberate: these
+ * strings originate inside `compiler.ts` / `compile-lesson.ts` and the
+ * tests on this module pin them, so prefix drift surfaces as a test
+ * failure rather than a silent reclassification.
+ *
+ *   - 'Missing pattern/message/astQuery/astGrepPattern/astGrepYamlRule'
+ *     → `'no-pattern-generated'`. The LLM emitted a structured response
+ *     without the fields needed to build a rule.
+ *   - 'Rejected regex' / 'Invalid ast-grep pattern' / 'Pattern matches a
+ *     suppression directive' → `'pattern-syntax-invalid'`. The pattern
+ *     exists but cannot be parsed / executed / safely run.
+ *   - 'smoke gate: zero matches' → `'pattern-zero-match'`. The pattern
+ *     compiled fine but did not fire against the badExample. On the
+ *     Pipeline 2 retry-loop path this branch is used for retry fuel;
+ *     the retry-exhausted terminal uses `'verify-retry-exhausted'`.
+ *     Pipeline 3 does not retry, so the gate rejection lands here
+ *     directly.
+ *   - Fallback is `'pattern-syntax-invalid'` so every skipped ledger
+ *     entry carries a specific code per ADR-088 Layer 4.
+ */
+function classifyBuildRejectReason(rejectReason) {
+    if (rejectReason.startsWith('Missing '))
+        return 'no-pattern-generated';
+    if (rejectReason.startsWith('Rejected regex'))
+        return 'pattern-syntax-invalid';
+    if (rejectReason.startsWith('Invalid ast-grep pattern'))
+        return 'pattern-syntax-invalid';
+    if (rejectReason.includes('suppression directive'))
+        return 'pattern-syntax-invalid';
+    if (rejectReason.startsWith('smoke gate: zero matches'))
+        return 'pattern-zero-match';
+    return 'pattern-syntax-invalid';
+}
 /**
  * Render the parsed LLM output's pattern as a printable string for the
  * retry-directive prompt. regex and astGrepPattern are string-native; a
@@ -668,6 +929,23 @@ function extractPatternString(parsed) {
         return JSON.stringify(parsed.astGrepYamlRule, null, 2);
     return '(pattern unavailable)';
 }
+/**
+ * Whether the parsed compiler output carries a concrete pattern we can hash.
+ * Callers emitting a `generate` trace event use this guard so the event
+ * records `patternHash` only when the LLM actually produced a pattern; a
+ * missing-pattern case emits the event without the field rather than
+ * hashing the `(pattern unavailable)` fallback, which would misleadingly
+ * look like a successful generation in verbose output.
+ */
+function hasExtractablePattern(parsed) {
+    if (typeof parsed.pattern === 'string' && parsed.pattern.length > 0)
+        return true;
+    if (typeof parsed.astGrepPattern === 'string' && parsed.astGrepPattern.length > 0)
+        return true;
+    if (parsed.astGrepYamlRule)
+        return true;
+    return false;
+}
 /**
  * Build the "Previous Attempt Failed Verification" user-prompt block that
  * threads the prior-attempt pattern, badExample, and reject reason back to