@leing2021/super-pi 0.19.1 → 0.19.3

package/README.md

@@ -35,7 +35,7 @@ Super Pi's answers:
 
 Each step has a dedicated skill + tool pair. Not just prompts — structured toolchains.
 
-### New: Stage model routing + optional auto-continue
+### New: Stage model routing
 
 Configure once in `.pi/settings.json`:
 
@@ -48,24 +48,22 @@ Configure once in `.pi/settings.json`:
     "04-review": "claude-sonnet-4-20250514",
     "05-learn": "claude-haiku-4-20250414",
     "default": "claude-sonnet-4-20250514"
-  },
-  "pipeline": {
-    "autoContinue": false
   }
 }
 ```
 
 How it works:
-- Each stage picks `modelStrategy[stage]`, or `modelStrategy.default` as fallback.
+- Model switching is handled automatically by the ce-core extension `input` hook — no manual `/model` needed.
+- When you type `/skill:01-brainstorm` through `/skill:05-learn`, the extension reads `modelStrategy[stage]` (or `modelStrategy.default`) and switches before the skill runs.
+- Supported formats: full reference (`"anthropic/claude-opus-4-1"`) or bare model id (`"claude-opus-4-1"`, reuses current provider).
 - Every stage prints a `📊 Pipeline Status` block with `Current / Output / Next`.
-- If `pipeline.autoContinue=true`, super-pi can trigger the next stage automatically.
-- Auto-continue is gate-aware: it will NOT skip required approvals (brainstorm approval, plan/review A/B/C choices).
+- A `Switched model for <stage>: <provider>/<model>` notification appears when the model changes.
 
 Quick example:
-1. Run `/skill:01-brainstorm`
+1. Run `/skill:01-brainstorm` — model auto-switches to the configured brainstorm model
 2. Approve the design
-3. If `autoContinue=true`, it moves to `/skill:02-plan` automatically
-4. If `autoContinue=false`, it stops after status output and waits for your command
+3. Run `/skill:02-plan` — model auto-switches to the configured plan model
+4. Continue through each stage — model switches automatically at each step
 
 ---
 
@@ -180,7 +178,7 @@ Single `npm install` output filtered once pays for the entire overhead. Full eva
 
 ## Code Scale
 
-~2500 lines of TypeScript implementing 15 tools, 22 Markdown reference files + 78 rule files driving 10 skills, 162 tests covering all tool logic.
+~2800 lines of TypeScript implementing 16 tools, 22 Markdown reference files + 78 rule files driving 10 skills, 170 tests covering all tool logic.
 
 Not a heavy framework. Each tool has a single responsibility, each skill works independently, and together they form a complete workflow.
 
@@ -383,6 +381,24 @@ Not a fork. Not a wrapper. Methodologies extracted and rebuilt with Pi's native
 
 ## Changelog
 
+### 0.19.3 — Terminate fix + runtime model routing + autoContinue removal
+- Fixed 6 ce-core tools (`brainstorm_dialog`, `workflow_state`, `review_router`, `session_checkpoint`, `session_history`, `pattern_extractor`) incorrectly returning `terminate: true`, which caused agent turns to end prematurely (brainstorm questions not shown, "type continue to proceed" interruptions).
+- Implemented runtime stage model routing via ce-core extension `input` hook: reads `.pi/settings.json` `modelStrategy`, auto-switches model before skill execution. Supports full reference (`anthropic/claude-opus-4-1`) and bare model id (`claude-opus-4-1`).
+- Removed `pipeline.autoContinue` configuration (never had runtime implementation; Pi lacks `skill_end` event for auto-continue).
+- Updated `skills/references/pipeline-config.md`, `README.md`, `README_CN.md` to reflect runtime model routing behavior.
+- Added 4 new tests covering terminate regression, input hook model routing, and bare model id parsing.
+
+### 0.19.2 — Evidence-first handoff-lite + docs tracking rule
+- Added `context_handoff` with evidence-first default handoff-lite generation when markdown is omitted.
+- Standardized the shared handoff-lite template across 01-05 workflow handoffs via `skills/references/pipeline-config.md`.
+- Added tests protecting default handoff generation and the shared handoff docs contract.
+- Updated docs tracking so Git only uploads `docs/token-cost-evaluation.md` while other `docs/` artifacts stay local.
+
+### 0.19.1 — Pipeline config + typecheck baseline fix
+- Added shared pipeline config (`skills/references/pipeline-config.md`) for stage model routing via `.pi/settings.json`.
+- Added runtime stage model routing via ce-core extension `input` hook (reads `modelStrategy` from `.pi/settings.json`, auto-switches model before skill execution).
+- Fixed TypeScript baseline issues so `bunx tsc --noEmit` passes.
+
 ### 0.19.0 — 0.69.0 alignment + learn rename
 - TypeBox migration: `@sinclair/typebox` → `typebox` (zero old-path imports)
 - Peer/dev dependency upgrade: pi-coding-agent `0.67.6` → `0.69.0`

package/extensions/ce-core/index.ts

@@ -1,3 +1,5 @@
+import { readFile } from "node:fs/promises"
+import path from "node:path"
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent"
 import { Type } from "typebox"
 import { createArtifactHelperTool, type ArtifactType } from "./tools/artifact-helper"
@@ -20,6 +22,65 @@ import { AsyncMutex } from "./tools/async-mutex"
 import type { SubagentExecOptions, SubagentRunner } from "./tools/subagent"
 
 const _subagentEnvMutex = new AsyncMutex()
+const PIPELINE_STAGE_KEYS = new Set([
+  "01-brainstorm",
+  "02-plan",
+  "03-work",
+  "04-review",
+  "05-learn",
+])
+
+interface ModelStrategySettings {
+  modelStrategy?: Record<string, string>
+}
+
+async function readProjectSettings(cwd: string): Promise<ModelStrategySettings | null> {
+  const settingsPath = path.join(cwd, ".pi", "settings.json")
+  try {
+    const content = await readFile(settingsPath, "utf8")
+    return JSON.parse(content) as ModelStrategySettings
+  } catch {
+    return null
+  }
+}
+
+function parseStageSkillName(text: string): string | null {
+  const trimmed = text.trim()
+  const match = trimmed.match(/^\/skill:([^\s]+)/)
+  if (!match) {
+    return null
+  }
+
+  const skillName = match[1]
+  return PIPELINE_STAGE_KEYS.has(skillName) ? skillName : null
+}
+
+function parseModelRef(
+  modelRef: string,
+  currentProvider?: string,
+): { provider: string, id: string } | null {
+  const trimmed = modelRef.trim()
+  if (!trimmed) {
+    return null
+  }
+
+  const slashIndex = trimmed.indexOf("/")
+  if (slashIndex > 0 && slashIndex < trimmed.length - 1) {
+    return {
+      provider: trimmed.slice(0, slashIndex),
+      id: trimmed.slice(slashIndex + 1),
+    }
+  }
+
+  if (!currentProvider) {
+    return null
+  }
+
+  return {
+    provider: currentProvider,
+    id: trimmed,
+  }
+}
 
 /**
  * Create a subagent runner that handles env injection with mutex protection
@@ -223,6 +284,62 @@ const patternExtractorParams = Type.Object({
 })
 
 export default function ceCoreExtension(pi: ExtensionAPI) {
+  pi.on("input", async (event, ctx) => {
+    if (event.source === "extension") {
+      return { action: "continue" as const }
+    }
+
+    const stageKey = parseStageSkillName(event.text)
+    if (!stageKey) {
+      return { action: "continue" as const }
+    }
+
+    const settings = await readProjectSettings(ctx.cwd)
+    const modelStrategy = settings?.modelStrategy
+    if (!modelStrategy) {
+      return { action: "continue" as const }
+    }
+
+    const targetModelRef = modelStrategy[stageKey] ?? modelStrategy.default
+    if (!targetModelRef) {
+      return { action: "continue" as const }
+    }
+
+    const parsed = parseModelRef(targetModelRef, ctx.model?.provider)
+    if (!parsed) {
+      if (ctx.hasUI) {
+        ctx.ui.notify(`Invalid modelStrategy entry for ${stageKey}: ${targetModelRef}`, "warning")
+      }
+      return { action: "continue" as const }
+    }
+
+    if (ctx.model?.provider === parsed.provider && ctx.model?.id === parsed.id) {
+      return { action: "continue" as const }
+    }
+
+    const model = ctx.modelRegistry.find(parsed.provider, parsed.id)
+    if (!model) {
+      if (ctx.hasUI) {
+        ctx.ui.notify(`Configured model not found for ${stageKey}: ${targetModelRef}`, "warning")
+      }
+      return { action: "continue" as const }
+    }
+
+    const switched = await pi.setModel(model)
+    if (switched) {
+      if (ctx.hasUI) {
+        ctx.ui.notify(`Switched model for ${stageKey}: ${model.provider}/${model.id}`, "info")
+      }
+      return { action: "continue" as const }
+    }
+
+    if (ctx.hasUI) {
+      ctx.ui.notify(`No API key available for configured model: ${model.provider}/${model.id}`, "warning")
+    }
+
+    return { action: "continue" as const }
+  })
+
   const artifactHelper = createArtifactHelperTool()
   const askUserQuestion = createAskUserQuestionTool()
   const subagent = createSubagentTool()
@@ -338,7 +455,6 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         details: result,
-        terminate: true,
       }
     },
   })
@@ -393,7 +509,6 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         details: result,
-        terminate: true,
       }
     },
   })
@@ -449,7 +564,6 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         details: result,
-        terminate: true,
       }
     },
   })
@@ -489,7 +603,6 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         details: result,
-        terminate: true,
       }
     },
   })
@@ -531,7 +644,6 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         details: result,
-        terminate: true,
       }
     },
   })
@@ -553,7 +665,6 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         details: result,
-        terminate: true,
       }
     },
   })

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

@@ -0,0 +1,357 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises"
+import { existsSync } from "node:fs"
+import path from "node:path"
+import { normalizeSlug } from "../utils/name-utils"
+
+export type ContextHealth = "good" | "watch" | "heavy" | "critical"
+
+export interface ContextHandoffInput {
+  operation: "save" | "load" | "latest" | "status"
+  repoRoot: string
+  currentStage?: string
+  nextStage?: string
+  contextHealth?: ContextHealth
+  activeFiles?: string[]
+  blocker?: string
+  verification?: string
+  artifacts?: Record<string, string | undefined>
+  handoffMarkdown?: string
+  handoffPath?: string
+}
+
+export interface ContextStateEntry {
+  currentStage: string
+  nextStage?: string
+  contextHealth: ContextHealth
+  latestHandoffPath?: string
+  latestDatedHandoffPath?: string
+  activeFiles: string[]
+  blocker?: string
+  verification?: string
+  artifacts: Record<string, string | undefined>
+  recommendNewSession: boolean
+  updatedAt: string
+}
+
+export interface ContextHandoffResult {
+  operation: string
+  found?: boolean
+  path?: string
+  latestPath?: string
+  currentStage?: string
+  nextStage?: string
+  contextHealth?: ContextHealth
+  activeFiles?: string[]
+  blocker?: string
+  verification?: string
+  artifacts?: Record<string, string | undefined>
+  recommendNewSession?: boolean
+  handoffMarkdown?: string
+  updatedAt?: string
+}
+
+function ceDir(repoRoot: string): string {
+  return path.join(repoRoot, ".context", "compound-engineering")
+}
+
+function handoffDir(repoRoot: string): string {
+  return path.join(ceDir(repoRoot), "handoffs")
+}
+
+function stateFilePath(repoRoot: string): string {
+  return path.join(ceDir(repoRoot), "context-state.json")
+}
+
+function latestHandoffPath(repoRoot: string): string {
+  return path.join(handoffDir(repoRoot), "latest.md")
+}
+
+function toRepoRelative(repoRoot: string, filePath: string): string {
+  return path.relative(repoRoot, filePath)
+}
+
+function resolveRepoPath(repoRoot: string, filePath: string): string {
+  return path.isAbsolute(filePath) ? filePath : path.join(repoRoot, filePath)
+}
+
+function stageSlug(value?: string): string {
+  if (!value || value.trim().length === 0) return "unknown"
+  return normalizeSlug(value)
+}
+
+function buildDatedHandoffPath(repoRoot: string, currentStage?: string, nextStage?: string): string {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-")
+  const fileName = `${timestamp}-${stageSlug(currentStage)}-to-${stageSlug(nextStage)}.md`
+  return path.join(handoffDir(repoRoot), fileName)
+}
+
+function computeRecommendNewSession(currentStage?: string, nextStage?: string, contextHealth: ContextHealth = "watch"): boolean {
+  const isCrossPhase = Boolean(currentStage && nextStage && currentStage !== nextStage)
+  const isHeavy = contextHealth === "heavy" || contextHealth === "critical"
+  return isCrossPhase && isHeavy
+}
+
+function formatBullets(items: string[]): string {
+  if (items.length === 0) return "- N/A"
+  return items.map(item => `- ${item}`).join("\n")
+}
+
+function formatArtifacts(artifacts: Record<string, string | undefined>): string {
+  const lines = Object.entries(artifacts)
+    .filter(([, value]) => Boolean(value && value.trim().length > 0))
+    .map(([key, value]) => `- ${key}: ${value}`)
+
+  if (lines.length === 0) return "- N/A"
+  return lines.join("\n")
+}
+
+function buildDefaultHandoffMarkdown(input: {
+  currentStage: string
+  nextStage?: string
+  activeFiles: string[]
+  artifacts: Record<string, string | undefined>
+  blocker?: string
+  verification?: string
+}): string {
+  const currentTask = input.nextStage
+    ? `Continue from ${input.currentStage} to ${input.nextStage}.`
+    : `Continue ${input.currentStage}.`
+
+  const hotContext = formatBullets(input.activeFiles.slice(0, 5))
+
+  const verifiedFacts = formatBullets([
+    `Current stage: ${input.currentStage}`,
+    `Next stage: ${input.nextStage ?? "N/A"}`,
+  ])
+
+  const activeFiles = formatBullets(input.activeFiles.slice(0, 5))
+  const artifacts = formatArtifacts(input.artifacts)
+  const blocker = input.blocker ?? "N/A"
+  const verification = input.verification ?? "Not run"
+  const nextMinimalStep = input.nextStage ? `/skill:${input.nextStage}` : "N/A"
+
+  return [
+    "## Current Task",
+    currentTask,
+    "",
+    "## Hot Context",
+    hotContext,
+    "",
+    "## Verified Facts",
+    verifiedFacts,
+    "",
+    "## Active Files",
+    activeFiles,
+    "",
+    "## Artifacts",
+    artifacts,
+    "",
+    "## Current Blocker",
+    `- ${blocker}`,
+    "",
+    "## Verification",
+    `- ${verification}`,
+    "",
+    "## Do Not Repeat",
+    "- Do not reload full history unless the handoff lacks required evidence.",
+    "",
+    "## Next Minimal Step",
+    `- ${nextMinimalStep}`,
+    "",
+  ].join("\n")
+}
+
+async function readState(repoRoot: string): Promise<ContextStateEntry | null> {
+  const filePath = stateFilePath(repoRoot)
+  if (!existsSync(filePath)) return null
+
+  try {
+    const content = await readFile(filePath, "utf8")
+    return JSON.parse(content) as ContextStateEntry
+  } catch {
+    return null
+  }
+}
+
+async function writeState(repoRoot: string, state: ContextStateEntry): Promise<void> {
+  const filePath = stateFilePath(repoRoot)
+  await mkdir(path.dirname(filePath), { recursive: true })
+  await writeFile(filePath, JSON.stringify(state, null, 2), "utf8")
+}
+
+export function createContextHandoffTool() {
+  return {
+    name: "context_handoff",
+    async execute(input: ContextHandoffInput): Promise<ContextHandoffResult> {
+      switch (input.operation) {
+        case "save":
+          return save(input)
+        case "load":
+          return load(input)
+        case "latest":
+          return latest(input)
+        case "status":
+          return status(input)
+        default:
+          throw new Error(`Unknown operation: ${input.operation}`)
+      }
+    },
+  }
+}
+
+async function save(input: ContextHandoffInput): Promise<ContextHandoffResult> {
+  const currentStage = input.currentStage ?? "unknown"
+  const nextStage = input.nextStage
+  const contextHealth = input.contextHealth ?? "watch"
+  const activeFiles = input.activeFiles ?? []
+  const blocker = input.blocker
+  const verification = input.verification
+  const artifacts = input.artifacts ?? {}
+  const handoffMarkdown = input.handoffMarkdown?.trim().length
+    ? input.handoffMarkdown
+    : buildDefaultHandoffMarkdown({
+      currentStage,
+      nextStage,
+      activeFiles,
+      artifacts,
+      blocker,
+      verification,
+    })
+
+  const recommendNewSession = computeRecommendNewSession(currentStage, nextStage, contextHealth)
+  const latestPath = latestHandoffPath(input.repoRoot)
+  const datedPath = buildDatedHandoffPath(input.repoRoot, currentStage, nextStage)
+  const relativeLatestPath = toRepoRelative(input.repoRoot, latestPath)
+  const relativeDatedPath = toRepoRelative(input.repoRoot, datedPath)
+
+  await mkdir(path.dirname(latestPath), { recursive: true })
+  await writeFile(latestPath, handoffMarkdown, "utf8")
+  await writeFile(datedPath, handoffMarkdown, "utf8")
+
+  const state: ContextStateEntry = {
+    currentStage,
+    nextStage,
+    contextHealth,
+    latestHandoffPath: relativeLatestPath,
+    latestDatedHandoffPath: relativeDatedPath,
+    activeFiles,
+    blocker,
+    verification,
+    artifacts,
+    recommendNewSession,
+    updatedAt: new Date().toISOString(),
+  }
+
+  await writeState(input.repoRoot, state)
+
+  return {
+    operation: "save",
+    found: true,
+    path: relativeDatedPath,
+    latestPath: relativeLatestPath,
+    currentStage,
+    nextStage,
+    contextHealth,
+    activeFiles,
+    blocker,
+    verification,
+    artifacts,
+    recommendNewSession,
+    updatedAt: state.updatedAt,
+  }
+}
+
+async function load(input: ContextHandoffInput): Promise<ContextHandoffResult> {
+  const state = await readState(input.repoRoot)
+  if (!state) {
+    return {
+      operation: "load",
+      found: false,
+      contextHealth: "watch",
+      recommendNewSession: false,
+    }
+  }
+
+  const targetPath = input.handoffPath ?? state.latestHandoffPath ?? latestHandoffPath(input.repoRoot)
+  const absoluteTargetPath = resolveRepoPath(input.repoRoot, targetPath)
+  let markdown = ""
+  if (existsSync(absoluteTargetPath)) {
+    markdown = await readFile(absoluteTargetPath, "utf8")
+  }
+
+  return {
+    operation: "load",
+    found: true,
+    path: targetPath,
+    latestPath: state.latestHandoffPath,
+    currentStage: state.currentStage,
+    nextStage: state.nextStage,
+    contextHealth: state.contextHealth,
+    activeFiles: state.activeFiles,
+    blocker: state.blocker,
+    verification: state.verification,
+    artifacts: state.artifacts,
+    recommendNewSession: state.recommendNewSession,
+    handoffMarkdown: markdown,
+    updatedAt: state.updatedAt,
+  }
+}
+
+async function latest(input: ContextHandoffInput): Promise<ContextHandoffResult> {
+  const state = await readState(input.repoRoot)
+  if (!state || !state.latestHandoffPath) {
+    return {
+      operation: "latest",
+      found: false,
+      contextHealth: "watch",
+      recommendNewSession: false,
+    }
+  }
+
+  return {
+    operation: "latest",
+    found: true,
+    path: state.latestDatedHandoffPath,
+    latestPath: state.latestHandoffPath,
+    currentStage: state.currentStage,
+    nextStage: state.nextStage,
+    contextHealth: state.contextHealth,
+    activeFiles: state.activeFiles,
+    blocker: state.blocker,
+    verification: state.verification,
+    artifacts: state.artifacts,
+    recommendNewSession: state.recommendNewSession,
+    updatedAt: state.updatedAt,
+  }
+}
+
+async function status(input: ContextHandoffInput): Promise<ContextHandoffResult> {
+  const state = await readState(input.repoRoot)
+
+  if (!state) {
+    return {
+      operation: "status",
+      found: false,
+      contextHealth: "watch",
+      recommendNewSession: false,
+      activeFiles: [],
+      artifacts: {},
+    }
+  }
+
+  return {
+    operation: "status",
+    found: true,
+    path: state.latestDatedHandoffPath,
+    latestPath: state.latestHandoffPath,
+    currentStage: state.currentStage,
+    nextStage: state.nextStage,
+    contextHealth: state.contextHealth,
+    activeFiles: state.activeFiles,
+    blocker: state.blocker,
+    verification: state.verification,
+    artifacts: state.artifacts,
+    recommendNewSession: state.recommendNewSession,
+    updatedAt: state.updatedAt,
+  }
+}

package/package.json

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

package/skills/01-brainstorm/references/handoff.md

@@ -6,3 +6,6 @@ When the requirements artifact is ready:
 2. Summarize the recommended direction in 2-3 bullets.
 3. Recommend `02-plan` as the next step.
 4. If key ambiguity remains, say so before handing off.
+5. Provide `🧠 Context Status` (health, handoff path, active files, new-session recommendation).
+6. Save/mention handoff-lite path under `.context/compound-engineering/handoffs/` using the shared `Handoff-lite template` in `skills/references/pipeline-config.md`.
+7. Recommend new session only when cross-phase + health is heavy/critical, and include a copyable prompt.

package/skills/02-plan/references/handoff.md

@@ -6,3 +6,6 @@ When the plan is ready:
 2. Summarize the main implementation units.
 3. Recommend `03-work` as the next step.
 4. Call out any remaining assumptions or open risks.
+5. Provide `🧠 Context Status` (health, handoff path, active files, new-session recommendation).
+6. Save/mention handoff-lite path under `.context/compound-engineering/handoffs/` using the shared `Handoff-lite template` in `skills/references/pipeline-config.md`.
+7. Recommend new session only when cross-phase + health is heavy/critical, and include a copyable prompt.

package/skills/03-work/references/handoff.md

@@ -6,3 +6,7 @@ When execution reaches a meaningful checkpoint:
 2. Report the latest verification results.
 3. Recommend `04-review` as the next step.
 4. Mention any remaining implementation risk.
+5. Include checkpoint fields: `activeFiles`, `currentUnit`, `blocker`, `verification`, `contextTiers`, `handoffPath`.
+6. Provide `🧠 Context Status` (health, handoff path, active files, new-session recommendation).
+7. Save/mention handoff-lite path under `.context/compound-engineering/handoffs/` using the shared `Handoff-lite template` in `skills/references/pipeline-config.md`.
+8. Recommend new session only when cross-phase + health is heavy/critical, and include a copyable prompt.

package/skills/04-review/references/handoff.md

@@ -8,6 +8,8 @@ When the review is complete:
 4. After autofix, report what was changed and whether re-review confirms the fix.
 5. Recommend `05-learn` when the review surfaced a reusable learning or newly solved problem.
 6. Mention any relevant plan or solution artifacts referenced during review.
+7. Provide `🧠 Context Status` (health, handoff path, active files, new-session recommendation).
+8. Save/mention handoff-lite path under `.context/compound-engineering/handoffs/` using the shared `Handoff-lite template` in `skills/references/pipeline-config.md`.
 
 ## Autofix loop
 

package/skills/05-learn/SKILL.md

@@ -32,5 +32,7 @@ See [shared pipeline instructions](../references/pipeline-config.md) for model r
 5. Choose the correct category using `references/category-map.md`.
 6. Write or update the solution artifact under `docs/solutions/<category>/`.
 7. Mention how future `02-plan` and `04-review` runs should benefit from the new learning.
+8. Include `🧠 Context Status` (health, handoff path, active files, new-session recommendation) for workflow closure.
+9. Save/mention handoff-lite path under `.context/compound-engineering/handoffs/` using the shared `Handoff-lite template` in `skills/references/pipeline-config.md`.
 
 Before finishing this skill, apply the completion checklist in [shared pipeline instructions](../references/pipeline-config.md).

package/skills/references/pipeline-config.md

@@ -4,23 +4,23 @@ Use these rules in all Phase 1 skills: `01-brainstorm` → `02-plan` → `03-wor
 
 ## Start of skill: model routing
 
-Run this checklist before normal skill workflow:
+Model routing is handled automatically by the ce-core extension's `input` hook.
+When a user types `/skill:01-brainstorm` through `/skill:05-learn`, the extension:
 
-1. Read `.pi/settings.json` from the project root.
-2. Parse `modelStrategy` (if missing, skip switching).
-3. Resolve current stage key:
-   - `01-brainstorm`
-   - `02-plan`
-   - `03-work`
-   - `04-review`
-   - `05-learn`
-4. Pick `targetModel = modelStrategy[stageKey] ?? modelStrategy.default`.
-5. If `targetModel` exists and differs from the current model, run `/model <targetModel>`.
-6. If switching fails, continue with current model and mention the failure once.
+1. Reads `.pi/settings.json` from the project root.
+2. Parses `modelStrategy[stageKey]` or falls back to `modelStrategy.default`.
+3. If the target model differs from the current model, calls `pi.setModel()`.
+4. If switching fails, notifies the user and continues with the current model.
 
-## End of skill: status + optional auto-continue
+No manual `/model` command is needed. The skill itself does not need to handle model switching.
 
-Before final completion, always output this block (replace placeholders with real values, never output angle-bracket placeholders literally):
+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
+
+Before final completion, always output these blocks (replace placeholders with real values, never output angle-bracket placeholders literally):
 
 ```
 ---
@@ -29,6 +29,13 @@ Before final completion, always output this block (replace placeholders with rea
 - Output: <main artifact path or N/A>
 - Next: <next skill command or Completed>
 ---
+
+🧠 Context Status
+- Health: good | watch | heavy | critical
+- Handoff: <path or N/A>
+- Active: <1-5 active files or N/A>
+- New session: recommended | not needed
+---
 ```
 
 Next step mapping:
@@ -38,12 +45,83 @@ Next step mapping:
 - `04-review` → `/skill:05-learn`
 - `05-learn` → `Completed`
 
-Then read `.pi/settings.json` → `pipeline.autoContinue`:
-- If `false` or missing, stop after the status block and wait for user input.
-- If current stage is `05-learn`, stop after status block.
-- If `true` and current stage is not `05-learn`, auto-continue is allowed only after stage-specific gates are satisfied:
-  - `01-brainstorm`: user has explicitly approved the design handoff.
-  - `02-plan`: review choice is resolved (A/B/C flow completed) and user confirmed to proceed.
-  - `04-review`: optional QA choice is resolved (A/B/C flow completed) and user confirmed to proceed.
-  - Any unclear/ambiguous state: do not auto-continue; stop and ask.
-- When gates are satisfied, automatically trigger the mapped next skill command.
+### Handoff-lite template
+
+When a stage produces or updates handoff-lite, use this evidence-first structure and keep it concise (target <= 1500 tokens):
+
+```md
+## Current Task
+
+## Hot Context
+- 1-5 must-know facts for the next step
+
+## Verified Facts
+- already validated facts (do not re-prove)
+
+## Active Files
+- 1-5 file paths only
+
+## Artifacts
+- requirements: <path or N/A>
+- plan: <path or N/A>
+- checkpoint: <path or N/A>
+- proof: <path or N/A>
+
+## Current Blocker
+- <blocker or N/A>
+
+## Verification
+- <latest command + result or Not run>
+
+## Do Not Repeat
+- what should not be re-read/re-run unless needed
+
+## Next Minimal Step
+- exact next command/action
+```
+
+Rules:
+- Use `N/A` instead of inventing facts.
+- Keep broad history in artifact paths, not expanded narrative.
+- If `context_handoff` is unavailable, manually write this shape to `.context/compound-engineering/handoffs/latest.md` and mention the path.
+
+### New-session recommendation rule
+
+Recommend a new session only when both are true:
+
+1. Phase is changing (`Current` != next stage)
+2. Context health is `heavy` or `critical`
+
+When recommending a new session, include a directly copyable prompt:
+
+```md
+## 建议新开 Session
+
+原因：当前 `<current stage>` 已完成，下一步将进入 `<next stage>`。当前窗口已经包含较多已完成阶段上下文，继续执行会降低 Token ROI，并增加旧上下文干扰后续判断的风险。
+
+建议：新开一个窗口，把下面这段 Prompt 复制进去即可继续。
+
+```text
+继续这个 Super Pi workflow，不要重新开始。
+
+Repo: <repo path>
+
+请先读取：
+- <latest plan/requirements artifact>
+- <latest handoff-lite path>
+- <latest checkpoint path or summary>
+
+然后继续：
+- 执行 <next skill command>
+
+上下文策略：
+- hot: 仅保留当前执行必须文件（1-5）
+- warm: 通过 artifact path 按需回读
+- cold: 不进入当前窗口，除非明确需要
+
+核心原则：
+- 不重复已完成阶段
+- 优先验证当前阶段输出
+- 控制 token，保持高 ROI
+```
+```