@leing2021/super-pi 0.19.1 → 0.19.2

package/README.md

@@ -180,7 +180,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 +383,18 @@ Not a fork. Not a wrapper. Methodologies extracted and rebuilt with Pi's native
 
 ## Changelog
 
+### 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 gated auto-continue rules (`pipeline.autoContinue`) so automation does not skip required approval/review-choice steps.
+- Added explicit README usage examples for `modelStrategy` and `pipeline.autoContinue`.
+- 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/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.2",
   "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

@@ -18,9 +18,9 @@ Run this checklist before normal skill workflow:
 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.
 
-## End of skill: status + optional auto-continue
+## End of skill: status + context + optional auto-continue
 
-Before final completion, always output this block (replace placeholders with real values, never output angle-bracket placeholders literally):
+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:
@@ -47,3 +54,84 @@ Then read `.pi/settings.json` → `pipeline.autoContinue`:
   - `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
+```
+```