@mmnto/totem 1.14.10 → 1.14.12

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 };
+        }
+        if (!exampleHitPresent) {
+            manualResult.rule.unverified = true;
         }
-        return { status: 'compiled', rule: manualResult.rule };
+        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,17 +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');
-            return { status: 'skipped', hash: lesson.hash, reason: parsed.reason };
+            trace.push({
+                layer: 2,
+                action: 'result',
+                outcome: 'skipped',
+                reasonCode: 'out-of-scope',
+            });
+            return {
+                status: 'skipped',
+                hash: lesson.hash,
+                reason: parsed.reason,
+                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.
@@ -474,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);
@@ -492,54 +635,339 @@ 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 };
+        }
+        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 };
+        return { status: 'compiled', rule: ruleResult.rule, trace };
     }
-    // ── Pipeline 2: LLM compilation ──────────────────
-    // The compilerPrompt (ast-grep manual + few-shot examples, ~50KB) is the
-    // persistent system context — same bytes across every Pipeline 2 call within
-    // a session. Pass it as systemPrompt so the orchestrator can cache it
-    // (mmnto/totem#1291 Phase 3). The user prompt carries only the per-lesson
-    // body and the optional telemetry directive (which is per-rule, not cacheable).
+    // ── Pipeline 2 / Layer 3: LLM compilation with verify-retry loop ──
+    // ADR-088 Phase 1 (mmnto-ai/totem#1479). The compilerPrompt (ast-grep
+    // manual + few-shot examples, ~50KB) is the persistent system context —
+    // same bytes across every call within a session. Pass it as systemPrompt
+    // so the orchestrator can cache it (mmnto/totem#1291 Phase 3). The user
+    // prompt carries only the per-lesson body, the optional telemetry
+    // directive (per --upgrade target, not cacheable), and on retries the
+    // prior-attempt feedback block.
     //
-    // Optional telemetry directive (mmnto/totem#1131) — nudges Sonnet toward ast-grep
-    // when the existing rule is firing in strings/comments instead of code. Lives
-    // in the user prompt because it varies per --upgrade target.
-    const userPromptParts = [];
-    if (deps.telemetryPrefix) {
-        userPromptParts.push('## Telemetry-Driven Refinement Directive', deps.telemetryPrefix);
-    }
-    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' };
-    const parsed = parseCompilerResponse(response);
-    if (!parsed) {
-        callbacks?.onWarn?.(lesson.heading, 'Failed to parse LLM response — skipping');
-        return { status: 'failed' };
-    }
-    if (!parsed.compilable) {
-        callbacks?.onDim?.(lesson.heading, 'Not compilable (conceptual/architectural) — skipping');
-        return { status: 'skipped', hash: lesson.hash, reason: parsed.reason };
-    }
-    // mmnto/totem#1408: Pipeline 2 enforces the smoke gate. Rules without a
-    // badExample, or whose badExample fails to match the pattern, are rejected
-    // with a clear reason before landing in compiled-rules.json. The compile
-    // prompt rewrite in mmnto/totem#1409 teaches Sonnet to emit the field.
-    const ruleResult = buildCompiledRule(parsed, lesson, existingByHash, {
-        enforceSmokeGate: true,
-    });
-    if (!ruleResult.rule) {
-        callbacks?.onWarn?.(lesson.heading, `${ruleResult.rejectReason ?? 'Unknown error'} — skipping`);
-        return { status: 'failed' };
+    // Retry semantics:
+    //   - On smoke-gate zero-match, rebuild the user prompt with a
+    //     "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 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 'out-of-scope'.
+    const MAX_VERIFY_ATTEMPTS = 3;
+    let previousFailure = null;
+    for (let attempt = 1; attempt <= MAX_VERIFY_ATTEMPTS; attempt++) {
+        const userPromptParts = [];
+        if (deps.telemetryPrefix) {
+            userPromptParts.push('## Telemetry-Driven Refinement Directive', deps.telemetryPrefix);
+        }
+        if (previousFailure) {
+            userPromptParts.push('## Previous Attempt Failed Verification', buildRetryDirective(previousFailure, attempt, MAX_VERIFY_ATTEMPTS));
+        }
+        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) {
+            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');
+            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: '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
+        // outcome into one of four buckets:
+        //   success          — rule built AND Example Hit/Miss verify passed
+        //   retry-eligible   — smoke-gate zero-match OR verifyRuleExamples failure
+        //   missing-badexample — LLM omitted a required field (structural)
+        //   validator-failure  — invalid regex / ast-grep parse error / self-
+        //                        suppression guard; retrying would produce more
+        //                        invalid patterns, so the lesson stays pending
+        const ruleResult = buildCompiledRule(parsed, lesson, existingByHash, {
+            enforceSmokeGate: true,
+        });
+        let retryReason;
+        let retrySnippet;
+        if (ruleResult.rule) {
+            const testResult = verifyRuleExamples(ruleResult.rule, lesson.body);
+            if (!testResult || testResult.passed) {
+                // 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
+            // is empty but the test still failed (false-positive-only case),
+            // fall back to the badExample so the directive has something
+            // concrete to anchor on.
+            retrySnippet =
+                testResult.missedFails.length > 0
+                    ? testResult.missedFails.join('\n')
+                    : (parsed.badExample ?? '(no snippet available)');
+        }
+        else {
+            const rejectReason = ruleResult.rejectReason ?? 'Unknown error';
+            // Missing-badExample is a structural-output failure. Retrying won't
+            // teach the LLM to emit a field it just omitted — the compiler
+            // system prompt already requires it (mmnto-ai/totem#1409).
+            // 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.
+            // 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} — 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 (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-rule-rejected',
+                trace,
+            };
+        }
+        if (attempt < MAX_VERIFY_ATTEMPTS) {
+            previousFailure = {
+                pattern: extractPatternString(parsed),
+                snippet: retrySnippet,
+                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,
+        };
     }
-    const testResult = verifyRuleExamples(ruleResult.rule, lesson.body);
-    if (testResult && !testResult.passed) {
-        callbacks?.onWarn?.(lesson.heading, formatExampleFailure(testResult));
-        return { status: 'failed' };
+    // Unreachable: every path inside the loop returns. Kept to satisfy the
+    // 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
+ * compound ast-grep rule is JSON-serialized so the LLM can see the
+ * structure that produced zero matches.
+ */
+function extractPatternString(parsed) {
+    if (typeof parsed.pattern === 'string' && parsed.pattern.length > 0)
+        return parsed.pattern;
+    if (typeof parsed.astGrepPattern === 'string' && parsed.astGrepPattern.length > 0) {
+        return parsed.astGrepPattern;
     }
-    return { status: 'compiled', rule: ruleResult.rule };
+    if (parsed.astGrepYamlRule)
+        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
+ * the LLM so it can correct its output.
+ */
+function buildRetryDirective(failure, attempt, maxAttempts) {
+    return [
+        `This is attempt ${attempt} of ${maxAttempts}. The previous attempt produced a pattern that failed verification.`,
+        '',
+        '**Previous pattern:**',
+        '```',
+        failure.pattern,
+        '```',
+        '',
+        '**Code snippet the pattern had to match:**',
+        '```',
+        failure.snippet,
+        '```',
+        '',
+        `**Failure reason:** ${failure.reason}`,
+        '',
+        'Generate a corrected pattern that satisfies the requirements. Keep the lesson intent unchanged; only fix the pattern so it triggers correctly.',
+    ].join('\n');
 }
 //# sourceMappingURL=compile-lesson.js.map