@soleri/core 9.0.4 → 9.2.0

package/src/planning/gap-passes.test.ts

@@ -0,0 +1,372 @@
+/**
+ * Tests for gap-passes.ts — passes 5-8 (clarity, semantic quality,
+ * knowledge depth, alternative analysis).
+ */
+
+import { describe, it, expect } from 'vitest';
+import type { Plan, PlanAlternative } from './planner.js';
+import {
+  analyzeClarity,
+  analyzeSemanticQuality,
+  analyzeKnowledgeDepth,
+  analyzeAlternatives,
+  AMBIGUOUS_WORDS,
+  GENERIC_OBJECTIVE_PATTERNS,
+  RATIONALE_INDICATORS,
+  SHALLOW_INDICATORS,
+  KNOWLEDGE_INDICATORS,
+  NAMED_PATTERN_REGEX,
+} from './gap-passes.js';
+
+function makePlan(overrides: Partial<Plan> = {}): Plan {
+  return {
+    id: 'plan-test',
+    objective: 'Implement user authentication with JWT tokens and session management',
+    scope: 'Auth module, middleware, and user service. Does not include OAuth providers.',
+    status: 'draft',
+    decisions: [
+      { decision: 'Use JWT for stateless auth', rationale: 'Because it scales horizontally without shared session store' },
+    ],
+    tasks: [
+      { id: 'task-1', title: 'Add JWT signing', description: 'Implement JWT sign/verify using built-in crypto module', status: 'pending', updatedAt: Date.now() },
+      { id: 'task-2', title: 'Add auth middleware', description: 'Create Express middleware that validates JWT from Authorization header', status: 'pending', updatedAt: Date.now() },
+      { id: 'task-3', title: 'Add login endpoint', description: 'POST /auth/login returns JWT after verifying credentials', status: 'pending', updatedAt: Date.now() },
+      { id: 'task-4', title: 'Add test coverage', description: 'Test JWT signing, middleware rejection, and login flow end-to-end', status: 'pending', updatedAt: Date.now() },
+    ],
+    checks: [],
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    ...overrides,
+  };
+}
+
+function makeAlternative(overrides: Partial<PlanAlternative> = {}): PlanAlternative {
+  return {
+    approach: 'Use session cookies instead of JWT',
+    pros: ['Simpler implementation'],
+    cons: ['Requires shared session store'],
+    rejected_reason: 'JWT is stateless and scales better for our architecture',
+    ...overrides,
+  };
+}
+
+describe('Pattern constants (passes 5-8)', () => {
+  it('AMBIGUOUS_WORDS contains common vague terms', () => {
+    expect(AMBIGUOUS_WORDS).toContain('maybe');
+    expect(AMBIGUOUS_WORDS).toContain('probably');
+    expect(AMBIGUOUS_WORDS).toContain('etc');
+  });
+
+  it('GENERIC_OBJECTIVE_PATTERNS matches simple verb-noun objectives', () => {
+    expect(GENERIC_OBJECTIVE_PATTERNS.some((p) => p.test('Create something'))).toBe(true);
+    expect(GENERIC_OBJECTIVE_PATTERNS.some((p) => p.test('Fix bug'))).toBe(true);
+  });
+
+  it('GENERIC_OBJECTIVE_PATTERNS does not match detailed objectives', () => {
+    expect(GENERIC_OBJECTIVE_PATTERNS.some((p) => p.test('Create a user auth module with JWT'))).toBe(false);
+  });
+
+  it('RATIONALE_INDICATORS contains reasoning words', () => {
+    expect(RATIONALE_INDICATORS).toContain('because');
+    expect(RATIONALE_INDICATORS).toContain('due to');
+  });
+
+  it('SHALLOW_INDICATORS contains subjective words', () => {
+    expect(SHALLOW_INDICATORS).toContain('better');
+    expect(SHALLOW_INDICATORS).toContain('good');
+  });
+
+  it('KNOWLEDGE_INDICATORS match domain patterns', () => {
+    expect(KNOWLEDGE_INDICATORS.some((p) => p.test('vault pattern'))).toBe(true);
+    expect(KNOWLEDGE_INDICATORS.some((p) => p.test('WCAG 2.1'))).toBe(true);
+    expect(KNOWLEDGE_INDICATORS.some((p) => p.test('aria-label'))).toBe(true);
+  });
+
+  it('NAMED_PATTERN_REGEX matches hyphenated identifiers', () => {
+    expect(NAMED_PATTERN_REGEX.test('zod-form-validation')).toBe(true);
+    expect(NAMED_PATTERN_REGEX.test('simple')).toBe(false);
+  });
+});
+
+describe('Pass 5: Clarity', () => {
+  it('flags ambiguous language in objective', () => {
+    const plan = makePlan({
+      objective: 'Maybe implement some authentication features probably with JWT',
+      scope: 'Auth module. Not including OAuth.',
+    });
+    const gaps = analyzeClarity(plan);
+    expect(gaps.some((g) => g._trigger?.startsWith('ambiguous_words:'))).toBe(true);
+  });
+
+  it('does not flag clear language', () => {
+    const plan = makePlan();
+    const gaps = analyzeClarity(plan);
+    expect(gaps.some((g) => g._trigger?.startsWith('ambiguous_words:'))).toBe(false);
+  });
+
+  it('flags tasks with very short descriptions', () => {
+    const plan = makePlan({
+      tasks: [
+        { id: 't1', title: 'Do thing', description: 'Short', status: 'pending', updatedAt: Date.now() },
+        { id: 't2', title: 'Do other', description: '', status: 'pending', updatedAt: Date.now() },
+      ],
+    });
+    const gaps = analyzeClarity(plan);
+    expect(gaps.some((g) => g._trigger === 'short_task_descriptions')).toBe(true);
+  });
+
+  it('does not flag tasks with adequate descriptions', () => {
+    const plan = makePlan();
+    const gaps = analyzeClarity(plan);
+    expect(gaps.some((g) => g._trigger === 'short_task_descriptions')).toBe(false);
+  });
+
+  it('limits ambiguous words shown to 5', () => {
+    const plan = makePlan({
+      objective: 'Maybe perhaps we might could possibly somehow probably do various several things soon with some easy simple appropriate changes etc',
+      scope: 'Everything. Not limited.',
+    });
+    const gaps = analyzeClarity(plan);
+    const ambiguousGap = gaps.find((g) => g._trigger?.startsWith('ambiguous_words:'));
+    expect(ambiguousGap).toBeDefined();
+    // Description should mention (+N more) when more than 5 words found
+    if (ambiguousGap) {
+      expect(ambiguousGap.description).toContain('+');
+    }
+  });
+});
+
+describe('Pass 6: Semantic Quality', () => {
+  it('flags generic objective', () => {
+    const plan = makePlan({ objective: 'Create something' });
+    const gaps = analyzeSemanticQuality(plan);
+    expect(gaps.some((g) => g._trigger === 'generic_objective')).toBe(true);
+  });
+
+  it('flags short objective (< 5 words)', () => {
+    const plan = makePlan({ objective: 'Fix the auth bug' });
+    const gaps = analyzeSemanticQuality(plan);
+    expect(gaps.some((g) => g._trigger === 'generic_objective')).toBe(true);
+  });
+
+  it('does not flag detailed objective', () => {
+    const plan = makePlan();
+    const gaps = analyzeSemanticQuality(plan);
+    expect(gaps.some((g) => g._trigger === 'generic_objective')).toBe(false);
+  });
+
+  it('flags too few tasks', () => {
+    const plan = makePlan({
+      tasks: [
+        { id: 't1', title: 'Single task', description: 'Do everything in one task', status: 'pending', updatedAt: Date.now() },
+      ],
+    });
+    const gaps = analyzeSemanticQuality(plan);
+    expect(gaps.some((g) => g._trigger === 'too_few_tasks')).toBe(true);
+  });
+
+  it('flags too many tasks (> 20)', () => {
+    const tasks = Array.from({ length: 21 }, (_, i) => ({
+      id: `t${i}`, title: `Task ${i}`, description: `Description for task ${i} with enough detail`, status: 'pending' as const, updatedAt: Date.now(),
+    }));
+    const plan = makePlan({ tasks });
+    const gaps = analyzeSemanticQuality(plan);
+    expect(gaps.some((g) => g._trigger === 'too_many_tasks')).toBe(true);
+  });
+
+  it('flags shallow rationale in decisions', () => {
+    const plan = makePlan({
+      decisions: [{ decision: 'This approach is better', rationale: 'It is good and nice' }],
+    });
+    const gaps = analyzeSemanticQuality(plan);
+    expect(gaps.some((g) => g._trigger === 'shallow_rationale')).toBe(true);
+  });
+
+  it('does not flag decisions with proper rationale', () => {
+    const plan = makePlan({
+      decisions: [{ decision: 'Use JWT', rationale: 'This is better because it scales horizontally' }],
+    });
+    const gaps = analyzeSemanticQuality(plan);
+    expect(gaps.some((g) => g._trigger === 'shallow_rationale')).toBe(false);
+  });
+
+  it('flags duplicate task titles', () => {
+    const plan = makePlan({
+      tasks: [
+        { id: 't1', title: 'Implement feature', description: 'First implementation', status: 'pending', updatedAt: Date.now() },
+        { id: 't2', title: 'Implement feature', description: 'Duplicate title', status: 'pending', updatedAt: Date.now() },
+        { id: 't3', title: 'Test feature', description: 'Test the feature with assertions', status: 'pending', updatedAt: Date.now() },
+      ],
+    });
+    const gaps = analyzeSemanticQuality(plan);
+    expect(gaps.some((g) => g._trigger === 'duplicate_task_titles')).toBe(true);
+  });
+
+  it('flags no decisions for multi-task plans', () => {
+    const plan = makePlan({ decisions: [] });
+    const gaps = analyzeSemanticQuality(plan);
+    expect(gaps.some((g) => g._trigger === 'no_decisions')).toBe(true);
+  });
+
+  it('does not flag no decisions for < 3 tasks', () => {
+    const plan = makePlan({
+      decisions: [],
+      tasks: [
+        { id: 't1', title: 'Single task', description: 'Do the thing', status: 'pending', updatedAt: Date.now() },
+      ],
+    });
+    const gaps = analyzeSemanticQuality(plan);
+    expect(gaps.some((g) => g._trigger === 'no_decisions')).toBe(false);
+  });
+});
+
+describe('Pass 7: Knowledge Depth', () => {
+  it('awards bonus for 5+ vault pattern references', () => {
+    const plan = makePlan({
+      tasks: [
+        { id: 't1', title: 'Apply patterns', description: 'Use zod-form-validation and react-query-caching and error-boundary-pattern', status: 'pending', updatedAt: Date.now() },
+        { id: 't2', title: 'More patterns', description: 'Use accessibility-focus-ring and semantic-token-usage and component-variant-pattern', status: 'pending', updatedAt: Date.now() },
+        { id: 't3', title: 'Testing', description: 'Test with vitest-snapshot-testing approach', status: 'pending', updatedAt: Date.now() },
+      ],
+    });
+    const gaps = analyzeKnowledgeDepth(plan);
+    expect(gaps.some((g) => g._trigger === 'vault_pattern_refs_high')).toBe(true);
+    expect(gaps.some((g) => g._trigger === 'vault_pattern_density')).toBe(true);
+  });
+
+  it('awards bonus for 2-4 vault pattern references', () => {
+    const plan = makePlan({
+      tasks: [
+        { id: 't1', title: 'Apply patterns', description: 'Use zod-form-validation and react-query-caching', status: 'pending', updatedAt: Date.now() },
+        { id: 't2', title: 'Build', description: 'Build the component', status: 'pending', updatedAt: Date.now() },
+        { id: 't3', title: 'Test', description: 'Run the test suite', status: 'pending', updatedAt: Date.now() },
+      ],
+    });
+    const gaps = analyzeKnowledgeDepth(plan);
+    expect(gaps.some((g) => g._trigger === 'vault_pattern_refs_medium')).toBe(true);
+  });
+
+  it('awards bonus for high acceptance criteria coverage', () => {
+    const plan = makePlan({
+      tasks: [
+        { id: 't1', title: 'T1', description: 'Desc 1', status: 'pending', updatedAt: Date.now(), acceptanceCriteria: ['Criteria A'] },
+        { id: 't2', title: 'T2', description: 'Desc 2', status: 'pending', updatedAt: Date.now(), acceptanceCriteria: ['Criteria B'] },
+        { id: 't3', title: 'T3', description: 'Desc 3', status: 'pending', updatedAt: Date.now(), acceptanceCriteria: ['Criteria C'] },
+        { id: 't4', title: 'T4', description: 'Desc 4', status: 'pending', updatedAt: Date.now(), acceptanceCriteria: ['Criteria D'] },
+        { id: 't5', title: 'T5', description: 'Desc 5', status: 'pending', updatedAt: Date.now(), acceptanceCriteria: ['Criteria E'] },
+      ],
+    });
+    const gaps = analyzeKnowledgeDepth(plan);
+    expect(gaps.some((g) => g._trigger === 'high_acceptance_criteria')).toBe(true);
+  });
+
+  it('does not award acceptance criteria bonus below 80% threshold', () => {
+    const plan = makePlan({
+      tasks: [
+        { id: 't1', title: 'T1', description: 'Desc', status: 'pending', updatedAt: Date.now(), acceptanceCriteria: ['A'] },
+        { id: 't2', title: 'T2', description: 'Desc', status: 'pending', updatedAt: Date.now() },
+        { id: 't3', title: 'T3', description: 'Desc', status: 'pending', updatedAt: Date.now() },
+      ],
+    });
+    const gaps = analyzeKnowledgeDepth(plan);
+    expect(gaps.some((g) => g._trigger === 'high_acceptance_criteria')).toBe(false);
+  });
+
+  it('awards bonus for rich task descriptions (avg >= 80 chars)', () => {
+    const longDesc = 'This is a very detailed task description that provides specific technical context about what needs to be implemented.';
+    const plan = makePlan({
+      tasks: [
+        { id: 't1', title: 'T1', description: longDesc, status: 'pending', updatedAt: Date.now() },
+        { id: 't2', title: 'T2', description: longDesc, status: 'pending', updatedAt: Date.now() },
+        { id: 't3', title: 'T3', description: longDesc, status: 'pending', updatedAt: Date.now() },
+      ],
+    });
+    const gaps = analyzeKnowledgeDepth(plan);
+    expect(gaps.some((g) => g._trigger === 'rich_task_descriptions')).toBe(true);
+  });
+
+  it('awards bonus for domain knowledge indicators', () => {
+    const plan = makePlan({
+      tasks: [
+        { id: 't1', title: 'A11y audit', description: 'Check WCAG 2.1 compliance and aria-label usage with vault patterns', status: 'pending', updatedAt: Date.now() },
+        { id: 't2', title: 'Contrast', description: '4.5:1 contrast ratio for all text, anti-pattern detection', status: 'pending', updatedAt: Date.now() },
+        { id: 't3', title: 'Touch', description: '44px touch target minimum, acceptance criteria for all buttons', status: 'pending', updatedAt: Date.now() },
+      ],
+    });
+    const gaps = analyzeKnowledgeDepth(plan);
+    expect(gaps.some((g) => g._trigger === 'domain_knowledge_indicators')).toBe(true);
+  });
+
+  it('returns no bonuses for basic plan', () => {
+    const plan = makePlan({
+      tasks: [
+        { id: 't1', title: 'Do thing', description: 'Do it', status: 'pending', updatedAt: Date.now() },
+      ],
+    });
+    const gaps = analyzeKnowledgeDepth(plan);
+    const bonuses = gaps.filter((g) => g.severity === 'bonus');
+    expect(bonuses).toHaveLength(0);
+  });
+
+  it('excludes common hyphenated words from pattern refs', () => {
+    const plan = makePlan({
+      tasks: [
+        { id: 't1', title: 'T1', description: 'Use front-end and back-end and real-time and client-side and server-side', status: 'pending', updatedAt: Date.now() },
+      ],
+    });
+    const gaps = analyzeKnowledgeDepth(plan);
+    expect(gaps.some((g) => g._trigger === 'vault_pattern_refs_medium')).toBe(false);
+    expect(gaps.some((g) => g._trigger === 'vault_pattern_refs_high')).toBe(false);
+  });
+});
+
+describe('Pass 8: Alternative Analysis', () => {
+  it('flags no alternatives', () => {
+    const plan = makePlan();
+    const gaps = analyzeAlternatives(plan);
+    expect(gaps.some((g) => g._trigger === 'no_alternatives')).toBe(true);
+    expect(gaps[0].severity).toBe('major');
+  });
+
+  it('flags fewer than 2 alternatives', () => {
+    const plan = makePlan({ alternatives: [makeAlternative()] });
+    const gaps = analyzeAlternatives(plan);
+    expect(gaps.some((g) => g._trigger === 'few_alternatives')).toBe(true);
+  });
+
+  it('returns no gaps for 2+ well-formed alternatives', () => {
+    const plan = makePlan({
+      alternatives: [
+        makeAlternative(),
+        makeAlternative({ approach: 'Use OAuth2', rejected_reason: 'Too complex' }),
+      ],
+    });
+    const gaps = analyzeAlternatives(plan);
+    expect(gaps).toHaveLength(0);
+  });
+
+  it('flags missing rejection rationale', () => {
+    const plan = makePlan({
+      alternatives: [
+        makeAlternative(),
+        makeAlternative({ approach: 'Basic auth', rejected_reason: '' }),
+      ],
+    });
+    const gaps = analyzeAlternatives(plan);
+    expect(gaps.some((g) => g._trigger === 'missing_rejection_rationale')).toBe(true);
+  });
+
+  it('handles undefined alternatives', () => {
+    const plan = makePlan();
+    delete (plan as Record<string, unknown>).alternatives;
+    const gaps = analyzeAlternatives(plan);
+    expect(gaps.some((g) => g._trigger === 'no_alternatives')).toBe(true);
+  });
+
+  it('returns early after no-alternatives gap', () => {
+    const plan = makePlan();
+    const gaps = analyzeAlternatives(plan);
+    // Should only have the one "no alternatives" gap, not also "few alternatives"
+    expect(gaps).toHaveLength(1);
+  });
+});

package/src/planning/gap-passes.ts

@@ -0,0 +1,298 @@
+/**
+ * Quality and substance analysis passes (5-8).
+ * These passes examine clarity, semantic quality, knowledge depth,
+ * and alternative analysis of plans.
+ */
+
+import type { Plan } from './planner.js';
+import type { PlanGap } from './gap-types.js';
+import {
+  gap,
+  taskText,
+  decisionText,
+  decisionsText,
+  containsAny,
+} from './gap-patterns.js';
+
+// ─── Pattern Constants (Passes 5-8) ─────────────────────────────
+
+export const AMBIGUOUS_WORDS = [
+  'maybe', 'perhaps', 'might', 'could', 'some', 'etc', 'soon',
+  'simple', 'easy', 'appropriate', 'various', 'several',
+  'probably', 'possibly', 'somehow',
+];
+
+export const GENERIC_OBJECTIVE_PATTERNS = [
+  /^(create|build|implement|add|make|do)\s+\w+$/i,
+  /^fix\s+\w+$/i,
+  /^update\s+\w+$/i,
+];
+
+export const RATIONALE_INDICATORS = [
+  'because', 'since', 'due to', 'in order to',
+  'so that', 'given that', 'as a result',
+];
+
+export const SHALLOW_INDICATORS = ['better', 'good', 'best', 'nice', 'great', 'improved'];
+
+export const KNOWLEDGE_INDICATORS = [
+  /vault\s*pattern/i,
+  /vault\s*patterns/i,
+  /anti-pattern/i,
+  /wcag\s*[\d.]+/i,
+  /aria-[a-z]+/i,
+  /\d+(\.\d+)?:\d+\s*(contrast|ratio)/i,
+  /\d+px\s*(touch|target|minimum|min)/i,
+  /acceptance\s*criteria/i,
+];
+
+/** Checks if task descriptions reference specific named patterns (e.g. "zod-form-validation"). */
+export const NAMED_PATTERN_REGEX = /[a-z]+-[a-z]+-[a-z]+/;
+
+// ─── Pass 5: Clarity ─────────────────────────────────────────────
+
+export function analyzeClarity(plan: Plan): PlanGap[] {
+  const gaps: PlanGap[] = [];
+  const allText = `${plan.objective} ${plan.scope} ${decisionsText(plan)}`;
+  const lower = allText.toLowerCase();
+
+  const found = AMBIGUOUS_WORDS.filter((w) => {
+    const regex = new RegExp(`\\b${w}\\b`, 'i');
+    return regex.test(lower);
+  });
+
+  if (found.length > 0) {
+    gaps.push(
+      gap(
+        'minor', 'clarity',
+        `Ambiguous language detected: ${found.slice(0, 5).join(', ')}${found.length > 5 ? ` (+${found.length - 5} more)` : ''}.`,
+        'Replace vague terms with concrete, specific language.',
+        undefined, `ambiguous_words:${found.join(',')}`,
+      ),
+    );
+  }
+
+  const shortTasks = plan.tasks.filter((t) => !t.description || t.description.trim().length < 10);
+  if (shortTasks.length > 0) {
+    gaps.push(
+      gap(
+        'minor', 'clarity',
+        `${shortTasks.length} task(s) with very short descriptions: ${shortTasks.map((t) => t.id).join(', ')}.`,
+        'Add detailed descriptions to all tasks explaining what needs to be done.',
+        'tasks', 'short_task_descriptions',
+      ),
+    );
+  }
+
+  return gaps;
+}
+
+// ─── Pass 6: Semantic Quality ────────────────────────────────────
+
+export function analyzeSemanticQuality(plan: Plan): PlanGap[] {
+  const gaps: PlanGap[] = [];
+
+  if (plan.objective) {
+    const words = plan.objective.trim().split(/\s+/);
+    const isGeneric = GENERIC_OBJECTIVE_PATTERNS.some((p) => p.test(plan.objective.trim()));
+
+    if (isGeneric || words.length < 5) {
+      gaps.push(
+        gap(
+          'major', 'semantic-quality',
+          `Objective is too generic${words.length < 5 ? ` (${words.length} words)` : ''}: "${plan.objective.trim()}".`,
+          'Expand the objective to describe the specific outcome, context, and constraints.',
+          'objective', 'generic_objective',
+        ),
+      );
+    }
+  }
+
+  if (plan.tasks.length > 0 && plan.tasks.length < 3) {
+    gaps.push(
+      gap(
+        'minor', 'semantic-quality',
+        `Only ${plan.tasks.length} task(s) — plan may lack sufficient breakdown.`,
+        'Break down the work into 3-15 well-defined tasks for better tracking.',
+        'tasks', 'too_few_tasks',
+      ),
+    );
+  } else if (plan.tasks.length > 20) {
+    gaps.push(
+      gap(
+        'major', 'semantic-quality',
+        `${plan.tasks.length} tasks — plan scope may be too large.`,
+        'Split into multiple plans or consolidate related tasks to stay under 20.',
+        'tasks', 'too_many_tasks',
+      ),
+    );
+  }
+
+  for (let i = 0; i < plan.decisions.length; i++) {
+    const d = decisionText(plan.decisions[i]);
+    const hasShallow = containsAny(d, SHALLOW_INDICATORS);
+    const hasRationale = containsAny(d, RATIONALE_INDICATORS);
+    if (hasShallow && !hasRationale) {
+      gaps.push(
+        gap(
+          'minor', 'semantic-quality',
+          `Decision ${i + 1} uses subjective language without justification.`,
+          'Replace "better/good/best" with concrete reasoning using "because/since/due to".',
+          `decisions[${i}]`, 'shallow_rationale',
+        ),
+      );
+    }
+  }
+
+  const titleSet = new Set<string>();
+  const duplicates: string[] = [];
+  for (const t of plan.tasks) {
+    if (titleSet.has(t.title)) duplicates.push(t.title);
+    titleSet.add(t.title);
+  }
+  if (duplicates.length > 0) {
+    gaps.push(
+      gap(
+        'minor', 'semantic-quality',
+        `Duplicate task titles: ${[...new Set(duplicates)].join(', ')}.`,
+        'Give each task a unique, descriptive title.',
+        'tasks', 'duplicate_task_titles',
+      ),
+    );
+  }
+
+  if (plan.tasks.length >= 3 && plan.decisions.length === 0) {
+    gaps.push(
+      gap(
+        'major', 'semantic-quality',
+        `${plan.tasks.length} tasks but no decisions documented.`,
+        'Document key decisions and their rationale — at least 1 per 3 tasks.',
+        'decisions', 'no_decisions',
+      ),
+    );
+  }
+
+  return gaps;
+}
+
+// ─── Pass 7: Knowledge Depth (Substance Bonuses) ────────────────
+
+export function analyzeKnowledgeDepth(plan: Plan): PlanGap[] {
+  const gaps: PlanGap[] = [];
+  const allTaskText = taskText(plan);
+
+  let namedPatternCount = 0;
+  for (const task of plan.tasks) {
+    const desc = task.description || '';
+    const matches = desc.match(/[a-z]+-[a-z]+(-[a-z]+)*/g) || [];
+    const patternRefs = matches.filter(
+      (m) =>
+        m.length > 8 &&
+        NAMED_PATTERN_REGEX.test(m) &&
+        !['front-end', 'back-end', 'real-time', 'client-side', 'server-side'].includes(m),
+    );
+    namedPatternCount += patternRefs.length;
+  }
+
+  if (namedPatternCount >= 5) {
+    gaps.push(
+      gap('bonus', 'knowledge-depth',
+        `${namedPatternCount} vault pattern references across tasks — strong knowledge-informed plan.`,
+        '', 'tasks', 'vault_pattern_refs_high'),
+    );
+    gaps.push(
+      gap('bonus', 'knowledge-depth',
+        'Vault pattern density indicates expert-level domain knowledge.',
+        '', 'tasks', 'vault_pattern_density'),
+    );
+  } else if (namedPatternCount >= 2) {
+    gaps.push(
+      gap('bonus', 'knowledge-depth',
+        `${namedPatternCount} vault pattern references across tasks.`,
+        '', 'tasks', 'vault_pattern_refs_medium'),
+    );
+  }
+
+  let tasksWithCriteria = 0;
+  let totalCriteria = 0;
+  for (const task of plan.tasks) {
+    if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
+      tasksWithCriteria++;
+      totalCriteria += task.acceptanceCriteria.length;
+    }
+  }
+
+  if (plan.tasks.length > 0 && tasksWithCriteria / plan.tasks.length >= 0.8) {
+    gaps.push(
+      gap('bonus', 'knowledge-depth',
+        `${tasksWithCriteria}/${plan.tasks.length} tasks have acceptance criteria (${totalCriteria} total).`,
+        '', 'tasks', 'high_acceptance_criteria'),
+    );
+  }
+
+  let indicatorHits = 0;
+  for (const pattern of KNOWLEDGE_INDICATORS) {
+    if (pattern.test(allTaskText)) indicatorHits++;
+  }
+
+  if (indicatorHits >= 4) {
+    gaps.push(
+      gap('bonus', 'knowledge-depth',
+        `${indicatorHits} domain-specific knowledge indicators found (WCAG, ARIA, contrast ratios, touch targets, etc.).`,
+        '', 'tasks', 'domain_knowledge_indicators'),
+    );
+  }
+
+  if (plan.tasks.length > 0) {
+    const avgDescLength =
+      plan.tasks.reduce((sum, t) => sum + (t.description?.length ?? 0), 0) / plan.tasks.length;
+    if (avgDescLength >= 80) {
+      gaps.push(
+        gap('bonus', 'knowledge-depth',
+          `Task descriptions average ${Math.round(avgDescLength)} chars — detailed and specific.`,
+          '', 'tasks', 'rich_task_descriptions'),
+      );
+    }
+  }
+
+  return gaps;
+}
+
+// ─── Pass 8: Alternative Analysis ────────────────────────────────
+
+export function analyzeAlternatives(plan: Plan): PlanGap[] {
+  const gaps: PlanGap[] = [];
+  const alts = plan.alternatives;
+
+  if (!alts || alts.length === 0) {
+    gaps.push(
+      gap('major', 'alternative-analysis',
+        'No alternatives considered — risk of tunnel vision.',
+        'Add at least 2 rejected alternatives with pros, cons, and rejection rationale.',
+        'alternatives', 'no_alternatives'),
+    );
+    return gaps;
+  }
+
+  if (alts.length < 2) {
+    gaps.push(
+      gap('minor', 'alternative-analysis',
+        `Only ${alts.length} alternative explored — consider at least 2.`,
+        'Add another rejected alternative to strengthen decision rationale.',
+        'alternatives', 'few_alternatives'),
+    );
+  }
+
+  for (let i = 0; i < alts.length; i++) {
+    if (!alts[i].rejected_reason || alts[i].rejected_reason.trim().length === 0) {
+      gaps.push(
+        gap('minor', 'alternative-analysis',
+          `Alternative ${i + 1} ("${alts[i].approach}") missing rejection rationale.`,
+          'Explain why this alternative was rejected.',
+          `alternatives[${i}]`, 'missing_rejection_rationale'),
+      );
+    }
+  }
+
+  return gaps;
+}