@leing2021/super-pi 0.23.2 → 0.23.4

package/extensions/ce-core/index.ts

@@ -310,6 +310,7 @@ const contextHandoffParams = Type.Object({
     Type.Literal("load"),
     Type.Literal("latest"),
     Type.Literal("status"),
+    Type.Literal("validate"),
   ], { description: "Handoff operation" }),
   repoRoot: Type.String({ description: "Repository root" }),
   currentStage: Type.Optional(Type.String({ description: "Current pipeline stage (e.g. 02-plan)" })),
@@ -331,6 +332,7 @@ const contextHandoffParams = Type.Object({
   openDecisions: Type.Optional(Type.Array(Type.String(), { description: "Pending decisions that affect next steps" })),
   recentlyAccessedFiles: Type.Optional(Type.Array(Type.String(), { description: "Files recently read or edited (defaults to activeFiles)" })),
   compressionRisk: Type.Optional(Type.Array(Type.String(), { description: "Context compression risks to watch for" })),
+  activeRules: Type.Optional(Type.Array(Type.String(), { description: "1-5 must-know rules for continuation (TDD gates, constraints, do-not-repeat)" })),
 })
 
 const patternExtractorParams = Type.Object({
@@ -393,18 +395,21 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     if (thinkingStrategy) {
       const targetThinking = thinkingStrategy[stageKey] ?? thinkingStrategy.default
       if (targetThinking) {
-        const levelMap: Record<string, "low" | "medium" | "high"> = {
+        const levelMap: Record<string, ReturnType<ExtensionAPI["getThinkingLevel"]>> = {
+          off: "off",
+          minimal: "minimal",
           low: "low",
           medium: "medium",
           high: "high",
+          xhigh: "xhigh",
           "0": "low",
           "1": "medium",
           "2": "high",
         }
         const normalized = levelMap[targetThinking.toLowerCase()] ?? "medium"
-        const currentLevel = ctx.getThinkingLevel?.() ?? "medium"
+        const currentLevel = pi.getThinkingLevel()
         if (currentLevel !== normalized) {
-          ctx.setThinkingLevel?.(normalized)
+          pi.setThinkingLevel(normalized)
           if (ctx.hasUI) {
             ctx.ui.notify(`Switched thinking level for ${stageKey}: ${normalized}`, "info")
           }
@@ -748,7 +753,7 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
   pi.registerTool({
     name: contextHandoff.name,
     label: "Context Handoff",
-    description: "Manage cross-stage context handoffs with evidence-first templates. Supports save (write handoff + state), load (read handoff + state), latest (read latest dated handoff), and status (read current state).",
+    description: "Manage cross-stage context handoffs with evidence-first templates. Supports save (write handoff + state), load (read handoff + state), latest (read latest dated handoff), status (read current state), and validate (check continuation readiness with deterministic probes).",
     parameters: contextHandoffParams,
     async execute(_toolCallId, params) {
       const result = await contextHandoff.execute({
@@ -768,6 +773,7 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
         openDecisions: params.openDecisions,
         recentlyAccessedFiles: params.recentlyAccessedFiles,
         compressionRisk: params.compressionRisk,
+        activeRules: params.activeRules,
       })
 
       return {
@@ -887,4 +893,4 @@ export {
 export { normalizeSlug } from "./utils/name-utils"
 export { filterBashOutput } from "./tools/bash-output-filter"
 export { filterReadOutput } from "./tools/read-output-filter"
-export { COMPACTION_FOCUS_INSTRUCTIONS, TURN_PREFIX_FOCUS_INSTRUCTIONS } from "./tools/compaction-optimizer"
+export { COMPACTION_FOCUS_INSTRUCTIONS } from "./tools/compaction-optimizer"

package/extensions/ce-core/tools/compaction-optimizer.ts

@@ -27,12 +27,4 @@ export const COMPACTION_FOCUS_INSTRUCTIONS = `Additional focus for this summary:
 6. If any tests were run, summarize results by: file, pass/fail count, and specific failure messages
 7. Note any blocked items and their exact error state`
 
-/**
- * Additional instructions for turn-prefix summaries (split turns).
- * These are more concise since the turn suffix is retained.
- */
-export const TURN_PREFIX_FOCUS_INSTRUCTIONS = `Focus the turn-prefix summary on:
-- What the user originally asked for
-- Key decisions made in the prefix
-- Exact file paths and identifiers needed to understand the retained suffix
-Skip reasoning details — only keep actionable context.`
+

package/extensions/ce-core/tools/context-handoff.ts

@@ -5,8 +5,23 @@ import { normalizeSlug } from "../utils/name-utils"
 
 export type ContextHealth = "good" | "watch" | "heavy" | "critical"
 
+export type ContextHandoffRecommendedAction = "continue" | "save_handoff" | "fill_required_context"
+
+export interface ContextHandoffValidationCheck {
+  name: string
+  passed: boolean
+  reason: string
+}
+
+export interface ContextHandoffValidationProbes {
+  recall: boolean
+  continuation: boolean
+  artifact: boolean
+  decision: boolean
+}
+
 export interface ContextHandoffInput {
-  operation: "save" | "load" | "latest" | "status"
+  operation: "save" | "load" | "latest" | "status" | "validate"
   repoRoot: string
   currentStage?: string
   nextStage?: string
@@ -22,6 +37,7 @@ export interface ContextHandoffInput {
   openDecisions?: string[]
   recentlyAccessedFiles?: string[]
   compressionRisk?: string[]
+  activeRules?: string[]
 }
 
 export interface ContextStateEntry {
@@ -39,6 +55,7 @@ export interface ContextStateEntry {
   openDecisions: string[]
   recentlyAccessedFiles: string[]
   compressionRisk: string[]
+  activeRules: string[]
   recommendNewSession: boolean
   updatedAt: string
 }
@@ -62,7 +79,15 @@ export interface ContextHandoffResult {
   openDecisions?: string[]
   recentlyAccessedFiles?: string[]
   compressionRisk?: string[]
+  activeRules?: string[]
   updatedAt?: string
+  // Validation fields
+  ok?: boolean
+  probes?: ContextHandoffValidationProbes
+  checks?: ContextHandoffValidationCheck[]
+  missing?: string[]
+  warnings?: string[]
+  recommendedAction?: ContextHandoffRecommendedAction
 }
 
 function ceDir(repoRoot: string): string {
@@ -132,6 +157,7 @@ function buildDefaultHandoffMarkdown(input: {
   openDecisions: string[]
   recentlyAccessedFiles: string[]
   compressionRisk: string[]
+  activeRules: string[]
 }): string {
   const currentTask = input.nextStage
     ? `Continue from ${input.currentStage} to ${input.nextStage}.`
@@ -172,6 +198,9 @@ function buildDefaultHandoffMarkdown(input: {
     "## Active Files",
     activeFiles,
     "",
+    "## Active Rules",
+    formatBullets(input.activeRules),
+    "",
     "## Recently Accessed Files",
     formatBullets(input.recentlyAccessedFiles),
     "",
@@ -223,6 +252,7 @@ function normalizeStateEntry(raw: unknown): ContextStateEntry | null {
       ? toStringArray(state.recentlyAccessedFiles)
       : activeFiles.slice(0, 5),
     compressionRisk: toStringArray(state.compressionRisk),
+    activeRules: toStringArray(state.activeRules),
     recommendNewSession: typeof state.recommendNewSession === "boolean" ? state.recommendNewSession : false,
     updatedAt: typeof state.updatedAt === "string" ? state.updatedAt : new Date(0).toISOString(),
   }
@@ -268,6 +298,8 @@ export function createContextHandoffTool() {
           return latest(input)
         case "status":
           return status(input)
+        case "validate":
+          return validate(input)
         default:
           throw new Error(`Unknown operation: ${input.operation}`)
       }
@@ -290,6 +322,7 @@ async function save(input: ContextHandoffInput): Promise<ContextHandoffResult> {
     ? input.recentlyAccessedFiles
     : activeFiles.slice(0, 5)
   const compressionRisk = input.compressionRisk ?? []
+  const activeRules = input.activeRules ?? []
 
   const handoffMarkdown = input.handoffMarkdown?.trim().length
     ? input.handoffMarkdown
@@ -305,6 +338,7 @@ async function save(input: ContextHandoffInput): Promise<ContextHandoffResult> {
       openDecisions,
       recentlyAccessedFiles,
       compressionRisk,
+      activeRules,
     })
 
   const recommendNewSession = computeRecommendNewSession(currentStage, nextStage, contextHealth)
@@ -332,6 +366,7 @@ async function save(input: ContextHandoffInput): Promise<ContextHandoffResult> {
     openDecisions,
     recentlyAccessedFiles,
     compressionRisk,
+    activeRules,
     recommendNewSession,
     updatedAt: new Date().toISOString(),
   }
@@ -355,6 +390,7 @@ async function save(input: ContextHandoffInput): Promise<ContextHandoffResult> {
     openDecisions,
     recentlyAccessedFiles,
     compressionRisk,
+    activeRules,
     recommendNewSession,
     updatedAt: state.updatedAt,
   }
@@ -395,6 +431,7 @@ async function load(input: ContextHandoffInput): Promise<ContextHandoffResult> {
     openDecisions: state.openDecisions,
     recentlyAccessedFiles: state.recentlyAccessedFiles,
     compressionRisk: state.compressionRisk,
+    activeRules: state.activeRules,
     recommendNewSession: state.recommendNewSession,
     handoffMarkdown: markdown,
     updatedAt: state.updatedAt,
@@ -429,11 +466,278 @@ async function latest(input: ContextHandoffInput): Promise<ContextHandoffResult>
     openDecisions: state.openDecisions,
     recentlyAccessedFiles: state.recentlyAccessedFiles,
     compressionRisk: state.compressionRisk,
+    activeRules: state.activeRules,
     recommendNewSession: state.recommendNewSession,
     updatedAt: state.updatedAt,
   }
 }
 
+const PLACEHOLDER_VALUES = new Set(["n/a", "na", "not run", "none", "", "-"])
+const PLACEHOLDER_PREFIXES = ["- n/a", "- na", "- not run", "- none", "- "]
+
+function isPlaceholder(text: string): boolean {
+  const trimmed = text.trim().toLowerCase()
+  if (PLACEHOLDER_VALUES.has(trimmed)) return true
+  for (const prefix of PLACEHOLDER_PREFIXES) {
+    if (trimmed === prefix) return true
+  }
+  return false
+}
+
+function isMeaningfulText(value?: string): boolean {
+  return Boolean(value && !isPlaceholder(value))
+}
+
+function toPublicHandoffPath(repoRoot: string, filePath: string): string {
+  return path.isAbsolute(filePath) ? toRepoRelative(repoRoot, filePath) : filePath
+}
+
+function extractSection(markdown: string, heading: string): string {
+  const lines = markdown.split("\n")
+  const sectionLines: string[] = []
+  let inSection = false
+
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      if (inSection) break
+      if (line.slice(3).trim() === heading) {
+        inSection = true
+      }
+      continue
+    }
+    if (inSection) {
+      sectionLines.push(line)
+    }
+  }
+
+  return sectionLines.join("\n").trim()
+}
+
+function sectionHasMeaningfulContent(markdown: string, heading: string): boolean {
+  const section = extractSection(markdown, heading)
+  if (!section) return false
+
+  const lines = section.split("\n")
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+    if (!isPlaceholder(trimmed)) return true
+  }
+  return false
+}
+
+function hasMeaningfulArray(arr: string[]): boolean {
+  return arr.some(item => isMeaningfulText(item))
+}
+
+function hasMeaningfulRecord(rec: Record<string, string | undefined>): boolean {
+  return Object.values(rec).some(isMeaningfulText)
+}
+
+function isMeaningfulStage(value?: string): boolean {
+  return Boolean(value && value.trim().length > 0 && value !== "unknown" && !isPlaceholder(value))
+}
+
+async function validate(input: ContextHandoffInput): Promise<ContextHandoffResult> {
+  const checks: ContextHandoffValidationCheck[] = []
+  const missing: string[] = []
+  const warnings: string[] = []
+
+  // Read state
+  const state = await readState(input.repoRoot)
+  const hasState = state !== null
+
+  // Read markdown
+  let markdown = ""
+  let hasMarkdown = false
+  let handoffFile = ""
+
+  if (input.handoffPath) {
+    const absolutePath = resolveRepoPath(input.repoRoot, input.handoffPath)
+    if (existsSync(absolutePath)) {
+      markdown = await readFile(absolutePath, "utf8")
+      hasMarkdown = markdown.trim().length > 0
+      handoffFile = toPublicHandoffPath(input.repoRoot, input.handoffPath)
+    }
+  }
+
+  if (!hasMarkdown && state?.latestHandoffPath) {
+    const absolutePath = resolveRepoPath(input.repoRoot, state.latestHandoffPath)
+    if (existsSync(absolutePath)) {
+      markdown = await readFile(absolutePath, "utf8")
+      hasMarkdown = markdown.trim().length > 0
+      handoffFile = toPublicHandoffPath(input.repoRoot, state.latestHandoffPath)
+    }
+  }
+
+  if (!hasMarkdown) {
+    const latestPath = latestHandoffPath(input.repoRoot)
+    if (existsSync(latestPath)) {
+      markdown = await readFile(latestPath, "utf8")
+      hasMarkdown = markdown.trim().length > 0
+      handoffFile = toRepoRelative(input.repoRoot, latestPath)
+    }
+  }
+
+  const found = hasState || hasMarkdown
+
+  checks.push({
+    name: "state_exists",
+    passed: hasState,
+    reason: hasState ? "Found context-state.json" : "No context-state.json found",
+  })
+
+  checks.push({
+    name: "handoff_exists",
+    passed: hasMarkdown,
+    reason: hasMarkdown ? "Found handoff markdown" : "No handoff markdown found",
+  })
+
+  // --- Recall probe ---
+  const hasCurrentTruth = state ? hasMeaningfulArray(state.currentTruth) : false
+  const hasCurrentStage = state ? isMeaningfulStage(state.currentStage) : false
+  const hasCurrentTaskSection = hasMarkdown && sectionHasMeaningfulContent(markdown, "Current Task")
+
+  const recallPass = hasCurrentTruth || (hasCurrentStage && (hasMarkdown || (state?.nextStage !== undefined))) || hasCurrentTaskSection
+
+  checks.push({
+    name: "recall_current_truth",
+    passed: hasCurrentTruth,
+    reason: hasCurrentTruth ? `Found ${state!.currentTruth.length} current truth entries` : "No current truth entries",
+  })
+
+  checks.push({
+    name: "recall_current_task",
+    passed: hasCurrentTaskSection,
+    reason: hasCurrentTaskSection ? "Current Task section has meaningful content" : "Current Task section is missing or placeholder",
+  })
+
+  checks.push({
+    name: "recall_current_stage",
+    passed: hasCurrentStage,
+    reason: hasCurrentStage ? `Current stage: ${state!.currentStage}` : "No meaningful current stage",
+  })
+
+  if (!recallPass) {
+    missing.push("recall: current task or goal evidence")
+  }
+
+  // --- Continuation probe ---
+  // Tightened: only actionable next-step evidence passes
+  const hasNextStage = state ? isMeaningfulStage(state.nextStage) : false
+  const hasNextMinimalStep = hasMarkdown && sectionHasMeaningfulContent(markdown, "Next Minimal Step")
+
+  const continuationPass = hasNextMinimalStep || hasNextStage
+
+  checks.push({
+    name: "continuation_next_stage",
+    passed: hasNextStage,
+    reason: hasNextStage ? `Next stage: ${state!.nextStage}` : "No meaningful next stage",
+  })
+
+  checks.push({
+    name: "continuation_next_minimal_step",
+    passed: hasNextMinimalStep,
+    reason: hasNextMinimalStep ? "Next Minimal Step has meaningful content" : "Next Minimal Step is missing or placeholder",
+  })
+
+  // Diagnostic checks (do not affect continuation pass)
+  const hasBlocker = state ? Boolean(state.blocker && !isPlaceholder(state.blocker)) : false
+  const hasVerification = state ? Boolean(state.verification && !isPlaceholder(state.verification)) : false
+  const hasVerificationSection = hasMarkdown && sectionHasMeaningfulContent(markdown, "Verification")
+
+  checks.push({
+    name: "continuation_blocker",
+    passed: hasBlocker,
+    reason: hasBlocker ? `Blocker: ${state!.blocker}` : "No blocker information",
+  })
+
+  checks.push({
+    name: "continuation_verification",
+    passed: hasVerification || hasVerificationSection,
+    reason: (hasVerification || hasVerificationSection) ? "Verification evidence present" : "No verification information",
+  })
+
+  if (!continuationPass) {
+    missing.push("continuation: next minimal step or next stage evidence")
+  }
+
+  // --- Artifact probe ---
+  const hasActiveFiles = state ? hasMeaningfulArray(state.activeFiles) : false
+  const hasRecentlyAccessed = state ? hasMeaningfulArray(state.recentlyAccessedFiles) : false
+  const hasArtifacts = state ? hasMeaningfulRecord(state.artifacts) : false
+  const hasActiveFilesSection = hasMarkdown && sectionHasMeaningfulContent(markdown, "Active Files")
+  const hasRecentlyAccessedSection = hasMarkdown && sectionHasMeaningfulContent(markdown, "Recently Accessed Files")
+  const hasArtifactsSection = hasMarkdown && sectionHasMeaningfulContent(markdown, "Artifacts")
+
+  const artifactPass = hasActiveFiles || hasRecentlyAccessed || hasArtifacts
+    || hasActiveFilesSection || hasRecentlyAccessedSection || hasArtifactsSection
+
+  checks.push({
+    name: "artifact_active_files",
+    passed: hasActiveFiles || hasActiveFilesSection,
+    reason: (hasActiveFiles || hasActiveFilesSection) ? "Active files present" : "No active files",
+  })
+
+  if (!artifactPass) {
+    warnings.push("artifact: active files or artifacts are missing")
+  }
+
+  // --- Decision probe ---
+  const hasOpenDecisions = state ? hasMeaningfulArray(state.openDecisions) : false
+  const hasInvalidatedAssumptions = state ? hasMeaningfulArray(state.invalidatedAssumptions) : false
+  const hasOpenDecisionsSection = hasMarkdown && sectionHasMeaningfulContent(markdown, "Open Decisions")
+  const hasInvalidatedSection = hasMarkdown && sectionHasMeaningfulContent(markdown, "Invalidated Assumptions")
+  const hasCurrentTruthSection = hasMarkdown && sectionHasMeaningfulContent(markdown, "Current Truth")
+
+  const decisionPass = hasOpenDecisions || hasInvalidatedAssumptions || hasCurrentTruth
+    || hasOpenDecisionsSection || hasInvalidatedSection || hasCurrentTruthSection
+
+  checks.push({
+    name: "decision_open_decisions",
+    passed: hasOpenDecisions || hasOpenDecisionsSection,
+    reason: (hasOpenDecisions || hasOpenDecisionsSection) ? "Open decisions present" : "No open decisions",
+  })
+
+  if (!decisionPass) {
+    warnings.push("decision: decisions or invalidated assumptions are missing")
+  }
+
+  // --- ok derivation ---
+  const ok = recallPass && continuationPass
+
+  // --- recommended action ---
+  let recommendedAction: ContextHandoffRecommendedAction
+  if (!found) {
+    recommendedAction = "save_handoff"
+  } else if (!ok) {
+    recommendedAction = "fill_required_context"
+  } else {
+    recommendedAction = "continue"
+  }
+
+  return {
+    operation: "validate",
+    found,
+    ok,
+    path: handoffFile || undefined,
+    probes: {
+      recall: recallPass,
+      continuation: continuationPass,
+      artifact: artifactPass,
+      decision: decisionPass,
+    },
+    checks,
+    missing,
+    warnings,
+    recommendedAction,
+    currentStage: state?.currentStage,
+    nextStage: state?.nextStage,
+    contextHealth: state?.contextHealth,
+    updatedAt: state?.updatedAt,
+  }
+}
+
 async function status(input: ContextHandoffInput): Promise<ContextHandoffResult> {
   const state = await readState(input.repoRoot)
 
@@ -465,6 +769,7 @@ async function status(input: ContextHandoffInput): Promise<ContextHandoffResult>
     openDecisions: state.openDecisions,
     recentlyAccessedFiles: state.recentlyAccessedFiles,
     compressionRisk: state.compressionRisk,
+    activeRules: state.activeRules,
     recommendNewSession: state.recommendNewSession,
     updatedAt: state.updatedAt,
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leing2021/super-pi",
-  "version": "0.23.2",
+  "version": "0.23.4",
   "private": false,
   "type": "module",
   "description": "Pi-native Compound Engineering package for iterative development workflows",

package/skills/02-plan/SKILL.md

@@ -39,13 +39,14 @@ Every unit follows **RED → GREEN → REFACTOR**:
 
 ## Planning flow
 
-1. Read relevant brainstorm from `docs/brainstorms/`
-2. Run solution search (keywords → grep frontmatter → read top 3)
-3. Gather repository context
-4. If plan exists: use `plan_diff` `compare` → review with user → `patch`
-5. If no plan: write new plan under `docs/plans/` using `references/plan-template.md`
-6. Structure work using `references/implementation-unit-template.md`
-7. Verify every unit follows TDD gates
+1. **Load context**: consume latest handoff before any broad file reads — `context_handoff load` or read `.context/compound-engineering/handoffs/latest.md`. If found, use `activeFiles` and `blocker` as starting point. If not found, proceed normally (new project).
+2. Read relevant brainstorm from `docs/brainstorms/`
+3. Run solution search (keywords → grep frontmatter → read top 3)
+4. Gather repository context
+5. If plan exists: use `plan_diff` `compare` → review with user → `patch`
+6. If no plan: write new plan under `docs/plans/` using `references/plan-template.md`
+7. Structure work using `references/implementation-unit-template.md`
+8. Verify every unit follows TDD gates
 
 ## Optional: CEO Review
 

package/skills/03-work/SKILL.md

@@ -41,16 +41,18 @@ Every step follows **RED → GREEN → REFACTOR**:
 
 ## Workflow
 
-1. Detect input type (plan path vs bare prompt)
-2. Read implementation units if plan path
-3. Load `session_checkpoint` to skip completed units
-4. Use `task_splitter` for dependency analysis
-5. Execute: **inline mode** by default, `ce_parallel_subagent` for independent units
-6. Follow TDD per unit: RED → minimal code → GREEN → refactor → unit-level **verification**
-7. Record progress via `references/progress-update-format.md`
-8. Save `session_checkpoint` after each unit
-9. On failure: `session_checkpoint` `fail` → `retry` → follow strategy
-10. Provide completion report (see `references/completion-report.md`)
-11. Handoff to `04-review` using `references/handoff.md`
+1. **Load context**: consume latest handoff before any broad file reads — `context_handoff load` or read `.context/compound-engineering/handoffs/latest.md`. If found, use `activeFiles`, `blocker`, `verification`, `activeRules` as starting point. If not found, proceed normally.
+2. Detect input type (plan path vs bare prompt)
+3. Read implementation units if plan path
+4. Load `session_checkpoint` to skip completed units
+5. Use `task_splitter` for dependency analysis
+6. Execute: **inline mode** by default, `ce_parallel_subagent` for independent units
+7. Follow TDD per unit: RED → minimal code → GREEN → refactor → unit-level **verification**
+8. Record progress via `references/progress-update-format.md`
+9. Save `session_checkpoint` after each unit
+10. On failure: `session_checkpoint` `fail` → `retry` → follow strategy
+11. Provide completion report (see `references/completion-report.md`)
+12. **Save handoff**: `context_handoff save` with current stage, next stage, activeFiles, blocker, verification, activeRules
+13. Handoff to `04-review` using `references/handoff.md`
 
 Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/04-review/SKILL.md

@@ -46,14 +46,15 @@ Code review is **technical evaluation**, not social performance:
 
 ## Workflow
 
-1. Determine diff scope from branch or explicit target
-2. Collect stats (files, insertions, deletions) → call `review_router`
-3. Read matching plan artifact
-4. Run solution search
-5. Apply each reviewer persona from `review_router`
-6. Merge into structured findings
-7. Verify each finding against codebase
-8. Apply autofixes, re-run tests, re-review if needed
+1. **Load context**: consume latest handoff before any broad file reads — `context_handoff load` or read `.context/compound-engineering/handoffs/latest.md`. If found, use `activeFiles`, `artifacts.plan` as starting point. If not found, proceed normally.
+2. Determine diff scope from branch or explicit target
+3. Collect stats (files, insertions, deletions) → call `review_router`
+4. Read matching plan artifact
+5. Run solution search
+6. Apply each reviewer persona from `review_router`
+7. Merge into structured findings
+8. Verify each finding against codebase
+9. Apply autofixes, re-run tests, re-review if needed
 
 ## Optional: QA Test Mode
 

package/skills/06-next/SKILL.md

@@ -22,8 +22,9 @@ Use this skill when the user wants to know what to run next in the Compound Engi
 When the user asks "what should I do next?", "continue", or runs `/skill:06-next`:
 
 1. Call `workflow_state` with the repo root
-2. Apply recommendation logic from `references/recommendation-logic.md`
-3. Return: skill name, reason (1-2 lines), brief workflow state summary
+2. Inspect `workflow_state.context` first — apply **context-first priority chain** from `references/recommendation-logic.md` (health → blocker → recommendNewSession → nextStage → mismatch → fallback)
+3. If no context signals trigger, fall back to artifact-count rules
+4. Return: skill name, reason (1-2 lines), brief workflow state summary
 
 ### Verbose mode: "full status"
 
@@ -31,7 +32,8 @@ When the user asks "show status", "what's the current state", or uses `--verbose
 
 1. Call `workflow_state` with the repo root
 2. Call `session_history` with `latest` operation
-3. Return: latest artifacts (path + summary), status of each phase, recommended next step
+3. Include context health assessment from `workflow_state.context` in the status report
+4. Return: latest artifacts (path + summary), status of each phase, context health, recommended next step
 
 ## Artifact locations
 

package/skills/06-next/references/recommendation-logic.md

@@ -1,6 +1,51 @@
 # Recommendation logic
 
-Apply these rules in order. Return the first match.
+Apply these rules in strict priority order. Return the first match.
+
+## Context-first priority chain
+
+`06-next` must call `workflow_state` and inspect `workflow_state.context` **before** applying artifact-count rules. Context health and runtime state override stale artifact counts.
+
+Field mapping: the requirement uses `context.health` as a conceptual alias. Use the actual field name `workflow_state.context.contextHealth`.
+
+### Priority 1: Critical context health
+
+If `context.contextHealth` is `"critical"`:
+- Recommend: save a `context_handoff` with full handoff-lite template, then open a **new session**.
+- Reason: Current session context is critically inflated. Continuing will degrade decision quality and waste tokens.
+- Output: handoff-save guidance + copyable new-session prompt with repo path and artifact references.
+
+### Priority 2: Active blocker
+
+If `context.blocker` exists and is not `"N/A"` or a placeholder:
+- Recommend: return to the current stage (`context.currentStage`) and resolve the blocker before advancing.
+- Reason: A known blocker exists in the current pipeline stage.
+- Output: `/skill:<currentStage>` with blocker description.
+
+### Priority 3: New session recommended
+
+If `context.recommendNewSession === true`:
+- Recommend: open a new Pi session.
+- Reason: The previous stage determined that context health + phase transition warrant a fresh session.
+- Output: copyable new-session prompt referencing `context.latestHandoffPath`, artifacts, and next stage.
+
+### Priority 4: Explicit next stage
+
+If `context.nextStage` exists, is meaningful, and differs from `context.currentStage`:
+- Recommend: `/skill:<context.nextStage>`.
+- Reason: The previous stage explicitly requested this transition.
+- Output: recommended skill command.
+
+### Priority 5: Stage mismatch detection
+
+If `context.currentStage` does not match the most recent artifact state (e.g. a plan exists but context says `"01-brainstorm"`):
+- Recommend: the skill that matches the most recent artifact, or ask the user to clarify.
+- Reason: Runtime context and artifact state are out of sync.
+- Output: suggested correction with explanation of the mismatch.
+
+### Priority 6: Fallback — artifact-count rules
+
+If none of the above context rules triggered, fall back to the artifact-count rules below.
 
 ## Rule 1: No brainstorm artifacts
 

package/skills/references/pipeline-config.md

@@ -18,7 +18,34 @@ Supported `modelStrategy` formats in `.pi/settings.json`:
 - Full reference: `"02-plan": "anthropic/claude-opus-4-1"`
 - Bare model id (reuses current provider): `"02-plan": "claude-opus-4-1"`
 
-## End of skill: status + context
+## Start of skill: context loading
+
+Before reading any project files or running repository-wide scans, load the most recent handoff:
+
+1. Try `context_handoff load` or `context_handoff latest` first.
+2. Fallback: `read .context/compound-engineering/handoffs/latest.md` if tool is unavailable.
+3. **Handoff found?** Consume its `activeFiles`, `blocker`, `verification`, `currentTruth`, `activeRules` before any broad project reads.
+4. **No handoff?** Proceed normally — this is a new project or first run. Do not block.
+
+Core principle: **consume handoff before broad project file reads** — a single handoff read (~500 tokens) avoids 5-10 project file scans (~5K-10K tokens).
+
+## End of skill: save handoff + status + context
+
+Every Phase 1 skill (02-plan through 05-learn) must save context handoff at completion:
+
+```
+context_handoff save
+  currentStage: <stageKey>
+  nextStage: <next stage>
+  contextHealth: good | watch | heavy | critical
+  activeFiles: [1-5 currently active paths]
+  blocker: <blocker or N/A>
+  verification: <latest command + result>
+  activeRules: [1-5 rules critical for continuation]
+  currentTruth: [validated truths]
+```
+
+If `context_handoff` is unavailable, manually write the Handoff-lite template to `.context/compound-engineering/handoffs/latest.md`.
 
 Before final completion, always output these blocks (replace placeholders with real values, never output angle-bracket placeholders literally):