popeye-cli 2.2.0 → 2.7.0

package/src/pipeline/phases/recovery-loop.ts

@@ -1,26 +1,45 @@
 /**
  * RECOVERY_LOOP phase — self-heal using RCA, not guesswork.
  * Routes via requires_phase_rewind_to (P1-3). Max 5 iterations.
+ * v2.1: Extracts reviewer feedback from consensus failures and
+ *       builds structured revision directive for sessionGuidance.
  */
 
-import type { PipelinePhase } from '../types.js';
+import { existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { PipelinePhase, ConsensusPacket, GateCheckResult } from '../types.js';
 import type { PhaseContext, PhaseResult } from './phase-context.js';
 import { successResult, failureResult, triggerJournalist } from './phase-context.js';
 import { buildRCAPacket } from '../packets/rca-packet-builder.js';
 
 export async function runRecoveryLoop(context: PhaseContext): Promise<PhaseResult> {
-  const { pipeline, artifactManager, skillLoader } = context;
+  const { pipeline, artifactManager, skillLoader, skillUsageRegistry } = context;
   const artifacts = [];
 
   try {
-    // 1. Load debugger skill
-    const debuggerSkill = skillLoader.loadSkill('DEBUGGER');
+    // 1. Load debugger skill with metadata
+    const { definition: debuggerSkill, meta: debuggerMeta } = skillLoader.loadSkillWithMeta('DEBUGGER');
 
     // 2. Gather failure evidence
     const failedPhase = pipeline.failedPhase;
     const failedGateResult = failedPhase ? pipeline.gateResults[failedPhase] : undefined;
     const failedChecks = failedPhase ? pipeline.gateChecks[failedPhase] ?? [] : [];
 
+    // 2a. Detect missing module errors in stderr — invalidate install marker
+    const combinedStderr = failedChecks
+      .filter((c) => c.status === 'fail')
+      .map((c) => c.stderr_summary ?? '')
+      .join('\n');
+    const missingModule = /Cannot find module|ModuleNotFoundError|Failed to resolve import/
+      .test(combinedStderr);
+    if (missingModule) {
+      try {
+        const markerPath = join(context.projectDir, '.popeye', 'install-marker.json');
+        if (existsSync(markerPath)) unlinkSync(markerPath);
+      } catch { /* non-fatal */ }
+    }
+
     const failureEvidence = [
       `Failed phase: ${failedPhase ?? 'unknown'}`,
       failedGateResult
@@ -31,6 +50,50 @@ export async function runRecoveryLoop(context: PhaseContext): Promise<PhaseResul
         : 'No check failures',
     ].join('\n');
 
+    // 2b. For consensus failures, build revision directive from reviewer feedback
+    if (failedPhase?.startsWith('CONSENSUS_')) {
+      const directive = buildRevisionDirective(pipeline, failedPhase);
+      if (directive) {
+        const existing = pipeline.sessionGuidance ?? '';
+        const marker = '--- REVISION DIRECTIVE ---';
+        const base = existing.includes(marker)
+          ? existing.slice(0, existing.indexOf(marker)).trim()
+          : existing;
+        pipeline.sessionGuidance = [base, '', marker, directive.slice(0, 3000)].join('\n').trim();
+      }
+    }
+
+    // 2c. For QA/build failures, build a targeted fix directive from test stderr
+    // so the implementation phase knows exactly what to fix on rewind.
+    if (failedPhase === 'QA_VALIDATION' || failedPhase === 'PRODUCTION_GATE'
+        || failedPhase === 'IMPLEMENTATION') {
+      const failedCheckDetails = failedChecks
+        .filter((c) => c.status === 'fail')
+        .map((c) => [
+          `**${c.check_type}** (exit code ${c.exit_code}):`,
+          `Command: \`${c.command}\``,
+          c.stderr_summary ? c.stderr_summary.slice(0, 500) : 'No stderr captured',
+        ].join('\n'))
+        .join('\n\n');
+
+      if (failedCheckDetails) {
+        const existing = pipeline.sessionGuidance ?? '';
+        const marker = '--- QA FIX DIRECTIVE ---';
+        const base = existing.includes(marker)
+          ? existing.slice(0, existing.indexOf(marker)).trim()
+          : existing;
+        const directive = [
+          `Fix the following failures (recovery iteration ${pipeline.recoveryCount}):`,
+          '',
+          failedCheckDetails,
+          '',
+          'Apply targeted fixes only. Do not rewrite code that already works.',
+        ].join('\n');
+        pipeline.sessionGuidance = [base, '', marker, directive.slice(0, 3000)]
+          .join('\n').trim();
+      }
+    }
+
     // 3. Generate RCA via Claude with Debugger skill
     const { executePrompt } = await import('../../adapters/claude.js');
     const guidance = pipeline.sessionGuidance;
@@ -54,6 +117,33 @@ export async function runRecoveryLoop(context: PhaseContext): Promise<PhaseResul
     const rcaResult = await executePrompt(rcaPrompt);
     const rcaResponse = rcaResult.response;
 
+    // Record skill usage — debugger skill injected into RCA prompt
+    skillUsageRegistry.record('DEBUGGER', 'RECOVERY_LOOP', 'system_prompt', debuggerMeta.source, debuggerMeta.version);
+
+    // 3b. Build recovery micro-plan from RCA + stderr
+    const microPlan = buildRecoveryMicroPlan(rcaResponse, failedChecks, pipeline.recoveryCount);
+
+    // 3c. Store micro-plan as artifact for traceability
+    const microPlanEntry = artifactManager.createAndStoreText(
+      'recovery_fix_plan',
+      microPlan.plan,
+      'RECOVERY_LOOP',
+    );
+    artifacts.push(microPlanEntry);
+
+    // 3d. Inject micro-plan into sessionGuidance (replaces any prior fix directive)
+    {
+      const existing = pipeline.sessionGuidance ?? '';
+      const markers = ['--- QA FIX DIRECTIVE ---', '--- RECOVERY FIX PLAN ---'];
+      let base = existing;
+      for (const m of markers) {
+        if (base.includes(m)) base = base.slice(0, base.indexOf(m)).trim();
+      }
+      pipeline.sessionGuidance = [
+        base, '', '--- RECOVERY FIX PLAN ---', microPlan.plan.slice(0, 3000),
+      ].join('\n').trim();
+    }
+
     // 4. Build RCA packet
     const rcaPacket = buildRCAPacket({
       incidentSummary: `Gate failure at ${failedPhase ?? 'unknown'} (recovery iteration ${pipeline.recoveryCount})`,
@@ -103,18 +193,150 @@ function determineRewindTarget(
   _rcaResponse: string,
   failedPhase: PipelinePhase | undefined,
 ): PipelinePhase | undefined {
-  // If the failure was in production gate or audit, rewind to implementation
   if (failedPhase === 'PRODUCTION_GATE' || failedPhase === 'AUDIT') {
     return 'IMPLEMENTATION';
   }
-  // If in QA, rewind to implementation
   if (failedPhase === 'QA_VALIDATION') {
     return 'IMPLEMENTATION';
   }
-  // For consensus failures, rewind to the phase being validated
   if (failedPhase === 'CONSENSUS_MASTER_PLAN') return 'INTAKE';
   if (failedPhase === 'CONSENSUS_ARCHITECTURE') return 'ARCHITECTURE';
   if (failedPhase === 'CONSENSUS_ROLE_PLANS') return 'ROLE_PLANNING';
 
   return undefined;
 }
+
+/**
+ * Extract reviewer feedback from the latest consensus artifact and
+ * build a structured revision directive for the planner.
+ *
+ * Uses Set<string> for dedup. Output is capped at 3000 chars by caller.
+ */
+function buildRevisionDirective(
+  pipeline: { artifacts: Array<{ type: string; content?: unknown }> },
+  failedPhase: string,
+): string | null {
+  // Find the latest consensus artifact for this phase
+  const consensusArtifacts = pipeline.artifacts.filter(
+    (a) => a.type === 'consensus' && a.content,
+  );
+  if (consensusArtifacts.length === 0) return null;
+
+  const latest = consensusArtifacts[consensusArtifacts.length - 1];
+  const packet = latest.content as ConsensusPacket | undefined;
+  if (!packet?.reviewer_votes) return null;
+
+  const blockers = new Set<string>();
+  const required = new Set<string>();
+  const suggestions = new Set<string>();
+
+  for (const vote of packet.reviewer_votes) {
+    for (const issue of vote.blocking_issues) {
+      const trimmed = issue.trim();
+      if (trimmed) blockers.add(trimmed);
+    }
+    for (const change of (vote.required_changes ?? [])) {
+      const trimmed = change.trim();
+      if (trimmed) required.add(trimmed);
+    }
+    for (const suggestion of vote.suggestions) {
+      const trimmed = suggestion.trim();
+      if (trimmed) suggestions.add(trimmed);
+    }
+  }
+
+  if (blockers.size === 0 && required.size === 0 && suggestions.size === 0) return null;
+
+  const lines: string[] = [
+    `Revise the plan to address reviewer feedback from ${failedPhase}:`,
+    '',
+  ];
+
+  if (blockers.size > 0) {
+    lines.push('BLOCKING (must fix):');
+    for (const b of blockers) lines.push(`- ${b}`);
+    lines.push('');
+  }
+
+  if (required.size > 0) {
+    lines.push('REQUIRED CHANGES:');
+    for (const r of required) lines.push(`- ${r}`);
+    lines.push('');
+  }
+
+  if (suggestions.size > 0) {
+    lines.push('SUGGESTIONS:');
+    for (const s of suggestions) lines.push(`- ${s}`);
+    lines.push('');
+  }
+
+  lines.push('Keep existing plan structure. Apply targeted revisions only.');
+
+  return lines.join('\n');
+}
+
+/**
+ * Build a structured micro-fix plan from RCA + test failures.
+ * Returns the plan text and a risk assessment for consensus gating.
+ *
+ * Heuristics:
+ *   - Low risk (skip consensus): <=3 files, no schema/dep/config changes
+ *   - Medium risk (consensus): schema, dependency, or build config changes
+ *   - High risk (consensus): API changes, >5 files
+ */
+function buildRecoveryMicroPlan(
+  rcaResponse: string,
+  failedChecks: GateCheckResult[],
+  recoveryCount: number,
+): { plan: string; needsConsensus: boolean; riskLevel: 'low' | 'medium' | 'high' } {
+  const stderrLines = failedChecks
+    .filter((c) => c.status === 'fail')
+    .map((c) => c.stderr_summary ?? '')
+    .join('\n');
+
+  // Combine RCA + stderr for signal extraction
+  const combined = rcaResponse + '\n' + stderrLines;
+  const combinedLower = combined.toLowerCase();
+
+  const touchesSchema = /schema|migration|prisma|drizzle|typeorm|knex/.test(combinedLower);
+  const touchesDeps = /package\.json|requirements\.txt|dependency|npm install|pip install/
+    .test(combinedLower);
+  const touchesConfig =
+    /tsconfig\.json|vite\.config|jest\.config|vitest\.config|docker-compose|\.github\/workflows/
+    .test(combinedLower);
+  const touchesApi = /api route|endpoint|public api|breaking change/.test(combinedLower);
+
+  // Extract file paths from BOTH RCA and stderr
+  const mentionedFiles = combined.match(/[\w/.-]+\.(ts|tsx|js|jsx|py|sql|prisma)/gi) ?? [];
+  const uniqueFiles = [...new Set(mentionedFiles)];
+
+  let riskLevel: 'low' | 'medium' | 'high' = 'low';
+  if (touchesApi || uniqueFiles.length > 5) riskLevel = 'high';
+  else if (touchesSchema || touchesDeps || touchesConfig) riskLevel = 'medium';
+
+  // Only require consensus for medium+ risk on second+ attempt
+  const needsConsensus = riskLevel !== 'low' && recoveryCount >= 2;
+
+  const plan = [
+    `# Recovery Fix Plan (iteration ${recoveryCount})`,
+    '',
+    `**Risk level:** ${riskLevel}`,
+    `**Files likely affected:** ${uniqueFiles.length > 0 ? uniqueFiles.join(', ') : 'unknown'}`,
+    `**Consensus required:** ${needsConsensus ? 'yes' : 'no'}`,
+    '',
+    '## Root Cause Summary',
+    rcaResponse.slice(0, 800),
+    '',
+    '## Test Failures',
+    stderrLines.slice(0, 1000) || 'No stderr captured',
+    '',
+    '## Fix Checklist',
+    '- [ ] Address root cause identified above',
+    '- [ ] Fix failing test assertions',
+    '- [ ] Verify no regressions in passing tests',
+    touchesSchema ? '- [ ] Review schema/migration changes for correctness' : '',
+    touchesDeps ? '- [ ] Verify dependency changes are necessary and compatible' : '',
+  ].filter(Boolean).join('\n');
+
+  return { plan, needsConsensus, riskLevel };
+}

package/src/pipeline/phases/review.ts

@@ -8,12 +8,12 @@ import type { PhaseContext, PhaseResult } from './phase-context.js';
 import { successResult, failureResult } from './phase-context.js';
 import { generateRepoSnapshot, createSnapshotArtifact, diffSnapshots } from '../repo-snapshot.js';
 import type { RepoSnapshot, ChangeRequest } from '../types.js';
-import { buildChangeRequest, formatChangeRequest, routeChangeRequest } from '../change-request.js';
+import { buildChangeRequest, formatChangeRequest, routeChangeRequest, computeDriftKey, isDuplicateCR } from '../change-request.js';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 export async function runReview(context: PhaseContext): Promise<PhaseResult> {
-  const { pipeline, artifactManager, projectDir } = context;
+  const { pipeline, artifactManager, skillLoader, skillUsageRegistry, projectDir } = context;
   const artifacts = [];
   const changeRequests: ChangeRequest[] = [];
 
@@ -24,11 +24,18 @@ export async function runReview(context: PhaseContext): Promise<PhaseResult> {
     artifacts.push(snapshotEntry);
     pipeline.latestRepoSnapshot = artifactManager.toArtifactRef(snapshotEntry);
 
-    // 2. Find role-plan-approval snapshot for drift detection
-    const rolePlanSnapshots = pipeline.artifacts.filter(
-      (a) => a.type === 'repo_snapshot' && a.phase === 'CONSENSUS_ROLE_PLANS',
-    );
-    const baselineSnapshot = rolePlanSnapshots[rolePlanSnapshots.length - 1];
+    // 2. Find baseline snapshot for drift detection
+    // v2.4.9: Check baselineSnapshotOverride first (set after config CR resolved)
+    let baselineSnapshot = pipeline.baselineSnapshotOverride
+      ? pipeline.artifacts.find((a) => a.id === pipeline.baselineSnapshotOverride!.artifact_id)
+      : undefined;
+    // Fallback to CONSENSUS_ROLE_PLANS snapshot
+    if (!baselineSnapshot) {
+      const rolePlanSnapshots = pipeline.artifacts.filter(
+        (a) => a.type === 'repo_snapshot' && a.phase === 'CONSENSUS_ROLE_PLANS',
+      );
+      baselineSnapshot = rolePlanSnapshots[rolePlanSnapshots.length - 1];
+    }
 
     let driftReport = 'No baseline snapshot found for drift detection.';
     let hasDrift = false;
@@ -53,32 +60,62 @@ export async function runReview(context: PhaseContext): Promise<PhaseResult> {
             ].filter(Boolean).join('\n');
 
             // v1.1: Create change requests for detected drift
+            // v2.4.9: Deduplicate — skip if an active CR with the same drift_key exists
             if (diff.changed_configs.length > 0) {
-              const cr = buildChangeRequest({
-                originPhase: 'REVIEW',
-                requestedBy: 'REVIEWER',
-                changeType: 'config',
-                description: `Config files changed during implementation: ${diff.changed_configs.join(', ')}`,
-                justification: 'Detected by snapshot diff during review phase',
-                affectedArtifacts: [artifactManager.toArtifactRef(snapshotEntry)],
-                affectedPhases: ['IMPLEMENTATION', 'QA_VALIDATION'],
-                riskLevel: diff.changed_configs.length > 3 ? 'high' : 'medium',
+              const configHashPairs = diff.changed_configs.map((cfgPath) => {
+                const before = baselineData.config_files?.find((f) => f.path === cfgPath)?.content_hash ?? 'unknown';
+                const after = currentSnapshot.config_files?.find((f) => f.path === cfgPath)?.content_hash ?? 'unknown';
+                return `${cfgPath}:${before}->${after}`;
               });
-              changeRequests.push(cr);
+              const configDriftKey = computeDriftKey(
+                'config',
+                baselineSnapshot!.id,
+                diff.changed_configs,
+                configHashPairs,
+              );
+
+              if (!isDuplicateCR(pipeline.pendingChangeRequests, configDriftKey)) {
+                const cr = buildChangeRequest({
+                  originPhase: 'REVIEW',
+                  requestedBy: 'REVIEWER',
+                  changeType: 'config',
+                  description: `Config files changed during implementation: ${diff.changed_configs.join(', ')}`,
+                  justification: 'Detected by snapshot diff during review phase',
+                  affectedArtifacts: [artifactManager.toArtifactRef(snapshotEntry)],
+                  affectedPhases: ['IMPLEMENTATION', 'QA_VALIDATION'],
+                  riskLevel: diff.changed_configs.length > 3 ? 'high' : 'medium',
+                  driftKey: configDriftKey,
+                });
+                changeRequests.push(cr);
+              }
             }
 
-            if (Math.abs(diff.lines_delta) > 1000) {
-              const cr = buildChangeRequest({
-                originPhase: 'REVIEW',
-                requestedBy: 'REVIEWER',
-                changeType: 'scope',
-                description: `Significant scope drift detected: ${diff.lines_delta > 0 ? '+' : ''}${diff.lines_delta} lines`,
-                justification: 'Large line delta suggests scope changes beyond approved plans',
-                affectedArtifacts: [artifactManager.toArtifactRef(snapshotEntry)],
-                affectedPhases: ['CONSENSUS_MASTER_PLAN', 'IMPLEMENTATION'],
-                riskLevel: 'high',
-              });
-              changeRequests.push(cr);
+            // v2.5.1: Only check scope drift on revision-over-revision passes.
+            // On first pass, baseline = CONSENSUS_ROLE_PLANS (pre-implementation),
+            // so large line deltas are expected from implementation — not scope drift.
+            const isRevisionComparison = !!pipeline.baselineSnapshotOverride;
+            if (isRevisionComparison && Math.abs(diff.lines_delta) > 1000) {
+              const scopeDriftKey = computeDriftKey(
+                'scope',
+                baselineSnapshot!.id,
+                [`lines_delta:${diff.lines_delta}`],
+                [],
+              );
+
+              if (!isDuplicateCR(pipeline.pendingChangeRequests, scopeDriftKey)) {
+                const cr = buildChangeRequest({
+                  originPhase: 'REVIEW',
+                  requestedBy: 'REVIEWER',
+                  changeType: 'scope',
+                  description: `Significant scope drift detected: ${diff.lines_delta > 0 ? '+' : ''}${diff.lines_delta} lines`,
+                  justification: 'Large line delta suggests scope changes beyond approved plans',
+                  affectedArtifacts: [artifactManager.toArtifactRef(snapshotEntry)],
+                  affectedPhases: ['CONSENSUS_MASTER_PLAN', 'IMPLEMENTATION'],
+                  riskLevel: 'high',
+                  driftKey: scopeDriftKey,
+                });
+                changeRequests.push(cr);
+              }
             }
           } else {
             driftReport = 'No drift detected between approved plans and implementation.';
@@ -107,10 +144,15 @@ export async function runReview(context: PhaseContext): Promise<PhaseResult> {
         change_type: cr.change_type,
         target_phase: routeChangeRequest(cr),
         status: 'proposed',
+        drift_key: cr.drift_key,
       });
     }
 
-    // 4. Create review decision artifact
+    // 3b. Load REVIEWER skill and record usage for skill-guided review
+    const { definition: reviewerSkill, meta: reviewerMeta } = skillLoader.loadSkillWithMeta('REVIEWER');
+    skillUsageRegistry.record('REVIEWER', 'REVIEW', 'review_prompt', reviewerMeta.source, reviewerMeta.version);
+
+    // 4. Create review decision artifact (skill-guided)
     const reviewDoc = [
       '# Review Decision',
       '',
@@ -125,6 +167,7 @@ export async function runReview(context: PhaseContext): Promise<PhaseResult> {
       changeRequests.length > 0 ? '## Change Requests\n' + changeRequests.map((cr) => `- ${cr.cr_id}: ${cr.description}`).join('\n') : '',
       '',
       '## Plan Alignment',
+      `Reviewed using ${reviewerSkill.role} skill (v${reviewerSkill.version}).`,
       'Implementation reviewed against approved role plans.',
       '',
       '## Decision',

package/src/pipeline/phases/role-planning.ts

@@ -9,6 +9,7 @@ import { join } from 'node:path';
 import type { PipelineRole } from '../types.js';
 import type { PhaseContext, PhaseResult } from './phase-context.js';
 import { successResult, failureResult } from './phase-context.js';
+import { STRATEGY_ROLES, loadStrategyForRole } from '../strategy-context.js';
 
 /** Roles that produce implementation plans */
 const PLANNING_ROLES: PipelineRole[] = [
@@ -16,11 +17,14 @@ const PLANNING_ROLES: PipelineRole[] = [
   'BACKEND_PROGRAMMER',
   'FRONTEND_PROGRAMMER',
   'WEBSITE_PROGRAMMER',
+  'UI_UX_SPECIALIST',
+  'MARKETING_EXPERT',
+  'SOCIAL_EXPERT',
   'QA_TESTER',
 ];
 
 export async function runRolePlanning(context: PhaseContext): Promise<PhaseResult> {
-  const { pipeline, artifactManager, skillLoader, projectDir } = context;
+  const { pipeline, artifactManager, skillLoader, skillUsageRegistry, projectDir } = context;
   const artifacts = [];
 
   try {
@@ -46,13 +50,16 @@ export async function runRolePlanning(context: PhaseContext): Promise<PhaseResul
 
     const { executePrompt } = await import('../../adapters/claude.js');
 
+    // Load strategy once for all roles
+    const strategyBlock = loadStrategyForRole(projectDir);
+
     // Generate plan for each role (skip roles not in activeRoles)
     for (const role of PLANNING_ROLES) {
       if (!pipeline.activeRoles.includes(role)) {
         continue;
       }
 
-      const skill = skillLoader.loadSkill(role);
+      const { definition: skill, meta } = skillLoader.loadSkillWithMeta(role);
 
       const planPrompt = [
         skill.systemPrompt,
@@ -63,6 +70,10 @@ export async function runRolePlanning(context: PhaseContext): Promise<PhaseResul
         '## Architecture',
         architectureContent.slice(0, 5000),
         '',
+        // Conditionally inject strategy for website/marketing/social roles
+        ...(strategyBlock && STRATEGY_ROLES.includes(role)
+          ? ['## Website Marketing Strategy (authoritative reference)', strategyBlock, '']
+          : []),
         '## Instructions',
         `Create your ${role} implementation plan. Include:`,
         '- Deterministic file-level outputs',
@@ -74,6 +85,14 @@ export async function runRolePlanning(context: PhaseContext): Promise<PhaseResul
       const planResult = await executePrompt(planPrompt);
       const plan = planResult.response;
 
+      // Record skill usage — role skill injected into planning prompt
+      skillUsageRegistry.record(role, 'ROLE_PLANNING', 'planning_prompt', meta.source, meta.version);
+
+      // Record strategy context usage when injected
+      if (strategyBlock && STRATEGY_ROLES.includes(role)) {
+        skillUsageRegistry.record(role, 'ROLE_PLANNING', 'strategy_context', 'disk', '1');
+      }
+
       const entry = artifactManager.createAndStoreText(
         'role_plan',
         `# ${role} Plan\n\n${plan}`,

package/src/pipeline/phases/stuck.ts

@@ -36,6 +36,16 @@ export async function runStuck(context: PhaseContext): Promise<PhaseResult> {
       '- Determine if scope changes are needed',
       '- Decide whether to restart pipeline from a specific phase',
       '',
+      // v2.6.0: Auto-recovery attempt details
+      ...(pipeline.autoRecoveryResult ? [
+        '## Auto-Recovery Attempt',
+        `Result: ${pipeline.autoRecoveryResult}`,
+        (() => {
+          const autoArtifact = pipeline.artifacts.find(a => a.type === 'auto_recovery_guidance');
+          return autoArtifact ? `Guidance: ${autoArtifact.path}` : 'No guidance artifact generated.';
+        })(),
+        '',
+      ] : []),
       '## Artifacts That May Need Update',
       ...pipeline.artifacts
         .filter((a) => a.phase === pipeline.failedPhase)

package/src/pipeline/repo-snapshot.ts

@@ -37,6 +37,8 @@ const CONFIG_FILES = new Set([
   'prisma/schema.prisma', 'alembic.ini',
   'requirements.txt', 'setup.py', 'setup.cfg',
   'Makefile', 'Procfile',
+  'poetry.lock', 'package-lock.json', 'pnpm-lock.yaml',
+  'yarn.lock', 'pnpm-workspace.yaml',
 ]);
 
 const CODE_EXTENSIONS = new Set([
@@ -223,6 +225,7 @@ function extractKeyFields(configName: string, content: string): Record<string, u
         scripts: pkg.scripts,
         dependencies: pkg.dependencies ? Object.keys(pkg.dependencies) : [],
         devDependencies: pkg.devDependencies ? Object.keys(pkg.devDependencies) : [],
+        workspaces: pkg.workspaces,
       };
     }
 

package/src/pipeline/role-execution-adapter.ts

@@ -16,6 +16,8 @@ import type {
   ArtifactEntry,
 } from './types.js';
 import type { SkillLoader, SkillDefinition } from './skill-loader.js';
+import type { SkillUsageRegistry } from './skills/usage-registry.js';
+import { STRATEGY_ROLES, loadStrategyForRole } from './strategy-context.js';
 
 // ─── Types ───────────────────────────────────────────────
 
@@ -65,8 +67,12 @@ export function buildRoleExecutionContext(
   const allowedPaths = extractAllowedPaths(planContent, role);
   const forbiddenPatterns = extractForbiddenPatterns(role);
 
-  // Build system prompt combining skill + role constraints
-  const systemPrompt = buildRoleSystemPrompt(role, skill, planContent, forbiddenPatterns);
+  // Load strategy for roles that need it
+  const strategyBlock = STRATEGY_ROLES.includes(role)
+    ? loadStrategyForRole(projectDir) : undefined;
+
+  // Build system prompt combining skill + role constraints + optional strategy
+  const systemPrompt = buildRoleSystemPrompt(role, skill, planContent, forbiddenPatterns, strategyBlock);
 
   return {
     role,
@@ -114,6 +120,7 @@ export function buildAllRoleContexts(
   pipeline: PipelineState,
   skillLoader: SkillLoader,
   projectDir: string,
+  skillUsageRegistry?: SkillUsageRegistry,
 ): Map<PipelineRole, RoleExecutionContext> {
   const contexts = new Map<PipelineRole, RoleExecutionContext>();
 
@@ -129,8 +136,18 @@ export function buildAllRoleContexts(
     const role = detectRoleFromPlan(content, pipeline.activeRoles);
     if (!role) continue;
 
-    const skill = skillLoader.loadSkill(role);
+    const { definition: skill, meta } = skillLoader.loadSkillWithMeta(role);
     contexts.set(role, buildRoleExecutionContext(role, skill, rolePlan, projectDir));
+
+    // Record skill usage — role skill injected into execution context
+    if (skillUsageRegistry) {
+      skillUsageRegistry.record(role, 'IMPLEMENTATION', 'role_context', meta.source, meta.version);
+
+      // Record strategy context usage for roles that receive it
+      if (STRATEGY_ROLES.includes(role) && loadStrategyForRole(projectDir)) {
+        skillUsageRegistry.record(role, 'IMPLEMENTATION', 'strategy_context', 'disk', '1');
+      }
+    }
   }
 
   return contexts;
@@ -189,6 +206,7 @@ function buildRoleSystemPrompt(
   skill: SkillDefinition,
   planContent: string,
   forbiddenPatterns: string[],
+  strategyContext?: string,
 ): string {
   const lines = [
     `# Role: ${role}`,
@@ -199,9 +217,17 @@ function buildRoleSystemPrompt(
     '## Your Approved Role Plan',
     planContent.slice(0, 4000),
     '',
+  ];
+
+  // Inject strategy after plan, before constraints
+  if (strategyContext) {
+    lines.push('## Website Marketing Strategy', strategyContext, '');
+  }
+
+  lines.push(
     '## Constraints',
     ...skill.constraints.map((c) => `- ${c}`),
-  ];
+  );
 
   if (forbiddenPatterns.length > 0) {
     lines.push(

package/src/pipeline/skill-loader.ts

@@ -9,6 +9,7 @@ import { join } from 'node:path';
 
 import type { PipelineRole } from './types.js';
 import { DEFAULT_SKILLS } from './skills/defaults.js';
+import type { SkillSource } from './skills/usage-registry.js';
 
 // ─── Types ───────────────────────────────────────────────
 
@@ -21,6 +22,14 @@ export interface SkillDefinition {
   depends_on?: PipelineRole[];
 }
 
+export interface SkillLoadResult {
+  definition: SkillDefinition;
+  meta: {
+    source: SkillSource;
+    version?: string;
+  };
+}
+
 // ─── Skill Loader ────────────────────────────────────────
 
 export class SkillLoader {
@@ -54,6 +63,30 @@ export class SkillLoader {
     return merged;
   }
 
+  /**
+   * Load skill definition with metadata about the source.
+   * Returns both the merged skill and info about where it came from.
+   *
+   * Args:
+   *   role: The pipeline role to load a skill for.
+   *
+   * Returns:
+   *   SkillLoadResult with definition and source metadata.
+   */
+  loadSkillWithMeta(role: PipelineRole): SkillLoadResult {
+    const definition = this.loadSkill(role);
+    const override = this.loadMarkdownOverride(role);
+    const source: SkillSource = override?.systemPrompt ? 'project_override' : 'defaults';
+
+    return {
+      definition,
+      meta: {
+        source,
+        version: definition.version,
+      },
+    };
+  }
+
   /** Load all skills for the given roles */
   loadAllSkills(roles: PipelineRole[]): Map<PipelineRole, SkillDefinition> {
     const result = new Map<PipelineRole, SkillDefinition>();