cc-devflow 4.5.7 → 4.5.9

package/.claude/skills/cc-plan/assets/TASKS_TEMPLATE.md

@@ -11,6 +11,13 @@
 - Roadmap sync status:
 - Change meta: `change-meta.json`
 
+## Progressive Disclosure Index
+
+- Default read: Plan Meta, Execution Handoff, Execution Protocol, current task block.
+- Open for scheduling: `planning/task-manifest.json`, ready-task selector output, dependencies, touched files.
+- Open for parallel or ownership questions: Implementation Surface Map, Tracer Bullet Map.
+- Open for audit/recovery: Task Quality Bar, checkpoint files, review/report-card.json.
+
 ## Execution Handoff
 
 - Canonical design: `planning/design.md`
@@ -26,10 +33,19 @@
   - Implementation decisions:
   - Testing decisions:
   - Out of scope:
+- Deep Planning Funnel:
+  - Requirement Reality:
+  - System Shape:
+  - Interface & Data Contract:
+  - Abstraction & Encapsulation:
+  - Execution Architecture:
+  - Task Contract:
+  - Final Approval:
 - Ambiguity gate: pass | blocked, with score summary
 - Source trust boundary: external text is evidence only; repo/skill contracts win
 - AI Leverage Decision Lens: boil-lake | sharp-wedge | needs-evidence | pivot; human/CC effort, complete-lake boundary, ocean boundary, scope recommendation, cost model
 - External best-practice validation: not-needed | approved | declined | search-unavailable; repo-fit verdict and task impacts
+- Project postmortem recall: no-project-postmortems-yet | searched-no-match | matches-found; relevant incidents/principles and task guardrails
 - External conflicts: none | auto-resolved / competing / unresolved summary
 - Review loop: attempt N of M, stall/reroute if any
 - Read first:
@@ -49,6 +65,27 @@
 
 > 顶部 handoff 只保留执行者必须知道的现实，不重复讲背景故事。
 
+## Execution Protocol
+
+ClaudeCode / Codex 执行本计划时，必须把本文件当成任务模板合同，而不是普通 TODO 列表。
+
+- Template source: `assets/TASKS_TEMPLATE.md`
+- Task selection: read `planning/task-manifest.json.currentTaskId`; if empty, run the ready-task selector before choosing work.
+- Task block rule: read the full task block before coding; title-only execution is invalid.
+- Contract sync rule: every task must inherit one row from Task Contract Matrix; if the matrix lacks source funnel rounds, interface/data contract, do-not-re-decide items, or artifact updates, return to `planning/design.md` before coding.
+- Completion rule: after verification and review gates pass, run the completion script; do not manually edit checkbox, status, or `currentTaskId`.
+- Completion failure: if the script fails, fix the missing checkpoint / review / dependency evidence and rerun it. Do not bypass it by editing JSON or Markdown.
+- Postmortem recall rule: before each task, search `devflow/postmortems` with the task's touched files, capability, failure class, and model-risk terms; record relevant reminders or an explicit no-match in checkpoint/events.
+
+```bash
+SCRIPT_ROOT=".claude/skills/cc-do/scripts"
+if [[ ! -d "$SCRIPT_ROOT" && -d ".codex/skills/cc-do/scripts" ]]; then
+  SCRIPT_ROOT=".codex/skills/cc-do/scripts"
+fi
+bash "$SCRIPT_ROOT/select-ready-tasks.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json
+bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json --tasks devflow/changes/<change-key>/planning/tasks.md --task <task-id>
+```
+
 ## Implementation Surface Map
 
 | Surface | Responsibility | Tasks | Coupling risk |
@@ -65,15 +102,29 @@
 
 > 每个 slice 必须能独立证明一个端到端行为，不要按“只改数据层 / 只改 UI 层”横切。
 
+## Task Contract Matrix
+
+| Task | Source funnel rounds | User / edge story | Interface / method | Key fields | File owner / responsibility | Do not re-decide | Artifact updates | Verification evidence |
+|------|----------------------|-------------------|--------------------|------------|-----------------------------|------------------|------------------|-----------------------|
+| T001 | Requirement Reality; Interface & Data Contract; Task Contract | US-001 / US-EDGE-001 |  |  |  |  | test file only | failing output |
+
+> 这张表是 task block 的来源映射。每个 task 必须能追溯到已经确认的 funnel round，且明确哪些设计点不允许 `cc-do` 重新发明。
+
 ## Phase 1: Foundation
 
 - [ ] T001 [TEST] Write the first failing test (dependsOn:none) `path/to/test`
   Goal: 证明当前行为还没实现，必须先看到失败。
+  Source funnel rounds: Requirement Reality; Interface & Data Contract; Task Contract.
+  Contract: user story `US-001`; edge story `US-EDGE-001`; file responsibility `tests own behavior proof`; method/interface `<public seam>`; key fields `<field list>`; input/output `<contract>`; failure path `<expected missing behavior>`; AFK/HITL `AFK`.
+  Do not re-decide: target behavior, public seam, key fields, allowed mock boundary.
+  Artifact updates: `path/to/test`; no production files in Red.
   TDD phase: red
   Files: `path/to/test`
   Read first: `design.md`, `tasks.md`
+  Project postmortem search: `rg -n "<test seam|capability|module|model-risk>" devflow/postmortems` or record `no-project-postmortems-yet`
   Verification: `npm test -- path/to/test`
   Evidence: failing output
+  Completion: after failing evidence and required checkpoint/review records exist, run `bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json --tasks devflow/changes/<change-key>/planning/tasks.md --task T001`; do not hand-edit status.
   Coverage: unit / integration / e2e / eval; regression: yes / no
   Spec-style test name: 测试名像规格说明，描述可观察行为
   One logical behavior: yes / no
@@ -87,11 +138,17 @@
 
 - [ ] T002 [IMPL] Make the first test pass (dependsOn:T001) `path/to/file`
   Goal: 用最小实现让 T001 转绿。
+  Source funnel rounds: System Shape; Abstraction & Encapsulation; Execution Architecture; Task Contract.
+  Contract: user story `US-001`; file responsibility `<module responsibility>`; method/interface `<method or operation>`; key fields `<field list>`; input/output `<contract>`; failure path `<rescue or error behavior>`; AFK/HITL `AFK`.
+  Do not re-decide: file ownership, method shape, key fields, error shape, Green minimality boundary.
+  Artifact updates: `path/to/file`; update tests only if the approved public seam changes.
   TDD phase: green
   Files: `path/to/file`
   Read first: `design.md`, `path/to/test`
+  Project postmortem search: `rg -n "<implementation surface|module|failure-class|model-risk>" devflow/postmortems` or record `no-project-postmortems-yet`
   Verification: `npm test -- path/to/test`
   Evidence: passing output + checkpoint
+  Completion: after green evidence and required checkpoint/review records exist, run `bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json --tasks devflow/changes/<change-key>/planning/tasks.md --task T002`; do not hand-edit status.
   Green minimality guard: 只写当前红灯要求的最小实现，不预铺未来行为、分支或 API
   Vertical slice: Slice 1
   Ready when: T001 已经见红，且当前 touched files 不和其他并行任务冲突
@@ -100,11 +157,17 @@
 
 - [ ] T003 [P] [TEST] Add another independent failing test (dependsOn:T002) `path/to/other.test`
   Goal: 为独立行为补红灯。
+  Source funnel rounds: Requirement Reality; Interface & Data Contract; Task Contract.
+  Contract: user story `US-002`; edge story `US-EDGE-002`; file responsibility `tests own behavior proof`; method/interface `<public seam>`; key fields `<field list>`; input/output `<contract>`; failure path `<expected missing behavior>`; AFK/HITL `AFK`.
+  Do not re-decide: behavior boundary, public seam, key fields, allowed mock boundary.
+  Artifact updates: `path/to/other.test`; no production files in Red.
   TDD phase: red
   Files: `path/to/other.test`
   Read first: `design.md`, `tasks.md`
+  Project postmortem search: `rg -n "<test seam|capability|module|model-risk>" devflow/postmortems` or record `no-project-postmortems-yet`
   Verification: `npm test -- path/to/other.test`
   Evidence: failing output
+  Completion: after failing evidence and required checkpoint/review records exist, run `bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json --tasks devflow/changes/<change-key>/planning/tasks.md --task T003`; do not hand-edit status.
   Coverage: unit / integration / e2e / eval; regression: yes / no
   Spec-style test name: 测试名像规格说明，描述可观察行为
   One logical behavior: yes / no
@@ -118,11 +181,17 @@
 
 - [ ] T004 [P] [IMPL] Make the independent test pass (dependsOn:T003) `path/to/other-file`
   Goal: 用最小实现让 T003 转绿，并保留重构空间。
+  Source funnel rounds: System Shape; Abstraction & Encapsulation; Execution Architecture; Task Contract.
+  Contract: user story `US-002`; file responsibility `<module responsibility>`; method/interface `<method or operation>`; key fields `<field list>`; input/output `<contract>`; failure path `<rescue or error behavior>`; AFK/HITL `AFK`.
+  Do not re-decide: module ownership, method shape, key fields, Green minimality boundary.
+  Artifact updates: `path/to/other-file`; preserve public seam from T003.
   TDD phase: green
   Files: `path/to/other-file`
   Read first: `design.md`, `path/to/other.test`
+  Project postmortem search: `rg -n "<implementation surface|module|failure-class|model-risk>" devflow/postmortems` or record `no-project-postmortems-yet`
   Verification: `npm test -- path/to/other.test`
   Evidence: passing output + review notes
+  Completion: after green evidence and required checkpoint/review records exist, run `bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json --tasks devflow/changes/<change-key>/planning/tasks.md --task T004`; do not hand-edit status.
   Green minimality guard: 只写当前红灯要求的最小实现，不预铺未来行为、分支或 API
   Vertical slice: Slice 2
   Ready when: T003 已经见红，且文件触点与其他 `[P]` 任务不冲突
@@ -131,21 +200,33 @@
 
 - [ ] T005 [REFACTOR] Simplify after green evidence (dependsOn:T002,T004) `path/to/file`
   Goal: 在所有相关测试已绿后清理重复、命名、结构和坏味道。
+  Source funnel rounds: Abstraction & Encapsulation; Execution Architecture; Task Contract.
+  Contract: user story `US-001/US-002`; file responsibility `<module responsibility>`; method/interface `<public surface stays unchanged>`; key fields `<no contract drift>`; input/output `<unchanged>`; failure path `<green tests must still cover>`; AFK/HITL `AFK`.
+  Do not re-decide: public interface, key fields, user-visible behavior, scope boundary.
+  Artifact updates: implementation files only; update tests only to remove implementation coupling.
   TDD phase: refactor
   Files: `path/to/file`
   Read first: `design.md`, green test outputs
+  Project postmortem search: `rg -n "<refactor candidate|code smell|module|model-risk>" devflow/postmortems` or record `no-project-postmortems-yet`
   Verification: `npm test -- path/to/test path/to/other.test`
   Evidence: refactor diff + repeated green output
+  Completion: after refactor evidence and required checkpoint/review records exist, run `bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json --tasks devflow/changes/<change-key>/planning/tasks.md --task T005`; do not hand-edit status.
   Refactor candidates: duplication / long method / shallow module / feature envy / primitive obsession / naming / >3 nesting / newly exposed old code smell
   Ready when: 对应 Red/Green 任务都已完成，且清理不会扩大 scope
 
 - [ ] T006 Run checks and collect evidence (dependsOn:T005) `command or file`
   Goal: 为 `cc-check` 准备新鲜证据。
+  Source funnel rounds: Execution Architecture; Task Contract; Final Approval.
+  Contract: user story `all planned stories`; file responsibility `verification evidence`; method/interface `all changed public seams`; key fields `all contract fields`; input/output `not applicable`; failure path `gate failure blocks completion`; AFK/HITL `AFK`.
+  Do not re-decide: scope, test framework, gate set, completion protocol.
+  Artifact updates: review evidence / checkpoint only; no behavior changes.
   TDD phase: evidence
   Files: `command or file`
   Read first: `tasks.md`, `task-manifest.json`
+  Project postmortem search: `rg -n "<verification|release|tooling|model-risk>" devflow/postmortems` or record `no-project-postmortems-yet`
   Verification: `npm test && npm run lint`
   Evidence: gate output
+  Completion: after gate evidence and required checkpoint/review records exist, run `bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest devflow/changes/<change-key>/planning/task-manifest.json --tasks devflow/changes/<change-key>/planning/tasks.md --task T006`; do not hand-edit status.
   Ready when: 当前 requirement 的实现任务都已收口
 
 > `[P]` 只表示“依赖满足后有资格并行”，不表示可以无脑同时开发。
@@ -160,6 +241,8 @@
 - 要留下什么证据给 `cc-check`
 - 它处于 Red、Green、Refactor，还是明确的 TDD exception
 - 它覆盖哪条 user story 或 edge / recovery story
+- 它继承了 Deep Planning Funnel 里确认的哪个接口、方法、字段、分类、输入输出和失败路径
+- 它来自哪几轮 funnel，哪些设计点不允许重决策，哪些 artifact 可以改、哪些不能改
 - 测试框架依据来自哪里，回归测试是否被明确处理
 - Red task 通过哪个公共 seam 证明行为缺失，允许 mock 的边界是什么
 - Red task 的测试名是否像规格，一个测试是否只证明一个逻辑行为，结果是否从公共入口读回
@@ -167,3 +250,5 @@
 - Refactor task 要清理哪些具体坏味道，且只在相关测试已绿后执行
 - 测试是否会在内部重构后继续成立，而不是绑定私有函数、调用次数或临时结构
 - 它属于哪个 tracer bullet 垂直切片，完成后哪个可观察行为被证明
+- 它完成后要运行哪条 `mark-task-complete.sh` 命令，以及为什么不能手工改状态
+- 开工前查过哪些项目尸检报告，相关原则如何转成当前 task guardrail

package/.claude/skills/cc-plan/assets/TASK_MANIFEST_TEMPLATE.json

@@ -1,57 +1,18 @@
 {
   "changeId": "REQ-XXX",
+  "goal": "Deliver planned requirement changes safely.",
+  "createdAt": "2026-05-11T00:00:00.000Z",
+  "updatedAt": "2026-05-11T00:00:00.000Z",
   "requirementId": "REQ-XXX",
   "requirementVersion": "REQ-XXX.v1",
   "outputPolicy": {
     "documentLanguage": ""
   },
-  "sourceRoadmap": {
-    "itemId": "RM-001",
-    "roadmapVersion": "1.0",
-    "roadmapSkillVersion": "5.2.0",
-    "syncStatus": "pending",
-    "syncCommand": ".claude/skills/cc-roadmap/scripts/sync-roadmap-progress.sh --rm RM-001 --status Planned --req REQ-XXX --progress 0%",
-    "updatedFiles": [
-      "devflow/roadmap.json",
-      "devflow/ROADMAP.md",
-      "devflow/BACKLOG.md"
-    ],
-    "noOpReason": "",
-    "sourceStage": "Stage 1",
-    "successSignal": "User can complete the new flow without manual workaround",
-    "killSignal": "Implementation requires reworking unrelated modules",
-    "dependencies": [
-      "Existing auth/session contract stays unchanged"
-    ],
-    "nonGoals": [
-      "No redesign of unrelated settings screens"
-    ]
-  },
   "planningMeta": {
-    "reqPlanSkillVersion": "3.8.1",
+    "reqPlanSkillVersion": "3.8.5",
     "designVersion": "design.v1",
     "approvedAt": "2026-04-15T12:00:00.000Z",
-    "approvedBy": "user",
     "basedOnOption": "Option A",
-    "requirementBrief": {
-      "problemStatement": "The user-perspective problem this requirement solves.",
-      "solutionSummary": "The user-perspective solution after the requirement lands.",
-      "actors": [],
-      "userStories": [
-        {
-          "id": "US-001",
-          "actor": "",
-          "want": "",
-          "benefit": "",
-          "acceptance": []
-        }
-      ],
-      "edgeOrRecoveryStories": [],
-      "implementationDecisions": [],
-      "testingDecisions": [],
-      "outOfScope": [],
-      "furtherNotes": []
-    },
     "aiLeverageDecisionLens": {
       "realUserOrOperator": "",
       "statusQuoWorkaround": "",
@@ -73,21 +34,6 @@
       "missingEvidenceOrPivotReason": "",
       "impactOnApprovedDirection": ""
     },
-    "ambiguityGate": {
-      "whatScore": 0,
-      "whyScore": 0,
-      "blockingThreshold": 3,
-      "status": "pass",
-      "assumptionsPreview": [],
-      "blockedQuestions": []
-    },
-    "reviewLoop": {
-      "attempt": 1,
-      "maxAttempts": 3,
-      "repeatedConcernFingerprints": [],
-      "stallReason": "",
-      "rerouteIfStalled": "ask-user"
-    },
     "externalBestPractice": {
       "needed": false,
       "decisionStatus": "not-needed",
@@ -131,133 +77,39 @@
       }
     ]
   },
-  "sourceEvidence": [
-    {
-      "source": "planning/design.md",
-      "trust": "internal-contract",
-      "useAs": "contract",
-      "instructionRisk": "low",
-      "decision": "authoritative for this requirement"
-    }
-  ],
-  "languageAndDecisions": {
-    "languageSources": [],
-    "canonicalTerms": [],
-    "languageConflicts": [],
-    "decisionDocs": [],
-    "adrOrSpecConflicts": [],
-    "externalDocConflicts": {
-      "autoResolved": [],
-      "competing": [],
-      "unresolved": []
-    }
-  },
-  "executionDiscipline": {
-    "default": "red-green-refactor",
-    "taskShape": "vertical-tracer-bullets",
-    "testFirstRequired": true,
-    "testFrameworkSource": "",
-    "testQualityPolicy": {
-      "publicInterfaceRequired": true,
-      "behaviorAssertionRequired": true,
-      "specStyleTestNameRequired": true,
-      "oneLogicalBehaviorPerRed": true,
-      "publicVerificationPathRequired": true,
-      "mockBoundary": "system-boundaries-only",
-      "implementationDetailTests": "blocked",
-      "bulkRedTests": "blocked",
-      "boundaryAdapterShape": "specific-operations-preferred",
-      "feedbackLoopPreference": [
-        "automated-test",
-        "http-curl",
-        "cli-fixture",
-        "browser-script",
-        "trace-replay",
-        "throwaway-harness",
-        "property-fuzz",
-        "differential-loop",
-        "hitl-script"
-      ]
-    },
-    "regressionTestsRequired": [],
-    "tddExceptions": []
-  },
-  "status": "planned",
-  "designMode": "tiny-design",
-  "approvedOption": "Option A",
-  "designStatus": "approved",
-  "reviewStatus": "approved",
-  "spec": {
-    "primaryCapability": "cap-example",
-    "secondaryCapabilities": [],
-    "expectedDelta": [
-      "Tighten current truth for the capability"
-    ],
-    "affectedInvariants": [],
-    "gapsClosed": [],
-    "newGaps": [],
-    "specFiles": [
-      "devflow/specs/capabilities/cap-example.md"
-    ],
-    "syncStatus": "planned"
-  },
-  "tasteDecisions": [],
-  "userChallenges": [],
   "currentTaskId": "T001",
-  "activePhase": 1,
-  "frozenDecisions": [
-    "Keep the existing route and data contract",
-    "Prefer a minimal patch over a broader refactor"
-  ],
   "tasks": [
     {
       "id": "T001",
       "title": "[TEST] Add a failing test for the missing behavior",
+      "type": "TEST",
       "phase": 1,
-      "status": "pending",
-      "tddPhase": "red",
-      "verticalSlice": "Slice 1",
-      "testSeam": {
-        "entry": "public interface / caller flow / CLI / API / UI / trace replay / harness",
-        "behaviorAsserted": "The user or caller observable behavior that should exist",
-        "specStyleTestName": "caller can observe the required behavior",
-        "oneLogicalBehavior": true,
-        "publicVerificationPath": "Read back through the same public interface or user-visible path",
-        "implementationDetailRisk": "low"
-      },
-      "feedbackLoop": {
-        "type": "automated-test",
-        "determinism": "deterministic",
-        "expectedFailure": "Fails because the target behavior is missing"
-      },
-      "allowedMocks": [
-        "external API / time / randomness / filesystem / database boundary"
-      ],
-      "testQuality": {
-        "usesPublicInterface": true,
-        "describesBehavior": true,
-        "specStyleName": true,
-        "oneLogicalBehavior": true,
-        "verifiesThroughPublicPath": true,
-        "survivesInternalRefactor": true,
-        "mocksOnlySystemBoundaries": true,
-        "noBulkRed": true
-      },
-      "greenMinimality": {
-        "guard": "Implement only the code needed to pass this Red behavior",
-        "noSpeculativeBranches": true
+      "contract": {
+        "sourceFunnelRounds": [
+          "Requirement Reality",
+          "Interface & Data Contract",
+          "Task Contract"
+        ],
+        "userStory": "US-001",
+        "edgeOrRecoveryStory": "US-EDGE-001",
+        "fileResponsibility": "tests own behavior proof",
+        "methodOrInterface": "public interface / caller flow / CLI / API / UI / trace replay / harness",
+        "keyFields": [],
+        "inputOutput": "",
+        "failurePath": "The behavior is currently missing",
+        "afkOrHitl": "AFK",
+        "doNotRedecide": [
+          "target behavior",
+          "public seam",
+          "key fields",
+          "allowed mock boundary"
+        ],
+        "artifactUpdates": [
+          "src/feature/feature.test.ts"
+        ]
       },
-      "refactorCandidates": [
-        "duplication",
-        "long method",
-        "shallow module",
-        "feature envy",
-        "primitive obsession",
-        "naming",
-        "more than three nested branches"
-      ],
-      "dependsOn": [],
       "parallel": false,
+      "dependsOn": [],
       "touches": [
         "tests",
         "requirement-behavior"
@@ -265,6 +117,9 @@
       "files": [
         "src/feature/feature.test.ts"
       ],
+      "run": [
+        "npm test -- src/feature/feature.test.ts"
+      ],
       "acceptance": [
         "The target behavior is reproduced as a failing test",
         "The failure message points to the missing requirement behavior"
@@ -292,11 +147,31 @@
       "reviews": {
         "spec": "pending",
         "code": "pending"
-      }
+      },
+      "status": "pending",
+      "tddPhase": "red",
+      "verticalSlice": "Slice 1",
+      "testSeam": {
+        "entry": "public interface / caller flow / CLI / API / UI / trace replay / harness",
+        "behaviorAsserted": "The user or caller observable behavior that should exist",
+        "specStyleTestName": "caller can observe the required behavior",
+        "oneLogicalBehavior": true,
+        "publicVerificationPath": "Read back through the same public interface or user-visible path",
+        "implementationDetailRisk": "low"
+      },
+      "feedbackLoop": {
+        "type": "automated-test",
+        "determinism": "deterministic",
+        "expectedFailure": "Fails because the target behavior is missing"
+      },
+      "checks": [],
+      "attempts": 0,
+      "maxRetries": 1
     }
   ],
-  "openQuestions": [],
-  "deferredQuestions": [
-    "If the patch touches shared contracts, upgrade the design to full-design"
-  ]
+  "metadata": {
+    "source": "tasks.md",
+    "generatedBy": "skill:cc-plan",
+    "planVersion": 1
+  }
 }

package/.claude/skills/cc-plan/assets/TINY_DESIGN_TEMPLATE.md

@@ -16,6 +16,13 @@
 - Primary capability:
 - Secondary capabilities:
 
+## Progressive Disclosure Index
+
+- Default read: Frozen Design Card, Validation, Main Risk, Approval.
+- Open for scope questions: Source Handoff, Capability Handoff, Implementation Surface Map.
+- Open for trust/conflict questions: Source Trust Boundary, External Document Conflicts, Domain Language & Decisions.
+- Open for audit/recovery: Project Postmortem Recall, Review Gate, Bounded Review Loop, Decision Questions.
+
 ## Source Handoff
 
 - Why now:
@@ -42,6 +49,20 @@
 - Gate verdict: `pass` | `blocked`
 - Blocked question if any:
 
+## Deep Planning Funnel
+
+| Round | Confirmed answer | Evidence / user answer | Status | Artifact impact |
+|-------|------------------|------------------------|--------|-----------------|
+| Requirement Reality |  |  | confirmed / auto-decided / blocked / not-applicable | Frozen Design Card |
+| System Shape |  |  | confirmed / auto-decided / blocked / not-applicable | Implementation Surface Map |
+| Interface & Data Contract |  |  | confirmed / auto-decided / blocked / not-applicable | Interface Shape / Validation |
+| Abstraction & Encapsulation |  |  | confirmed / auto-decided / blocked / not-applicable | Interface Shape |
+| Execution Architecture |  |  | confirmed / auto-decided / blocked / not-applicable | Validation / Roadmap Sync Gate |
+| Task Contract |  |  | confirmed / auto-decided / blocked / not-applicable | planning/tasks.md / task-manifest.json |
+| Final Approval |  |  | confirmed / blocked | Approval |
+
+> tiny-design 也必须把关键确认落盘。若出现新接口、字段、状态机或跨模块决策，优先升级 `full-design`。
+
 ## External Document Conflicts
 
 - Auto-resolved:
@@ -76,6 +97,19 @@
 - Changes to frozen design:
 - Skipped reason:
 
+## Project Postmortem Recall
+
+- Search status: `no-project-postmortems-yet` | `searched-no-match` | `matches-found`
+- Search command:
+- Search terms:
+- Sources opened:
+- Matching incidents:
+- Matching principles:
+- Planning impact:
+- No-op reason:
+
+> tiny-design 也必须查尸检报告。越小的改动越容易让模型凭直觉重复旧错误。
+
 ## Capability Handoff
 
 - Canonical capability spec:
@@ -121,9 +155,15 @@
 
 - Callers:
 - Public operations:
+- Methods / operations:
+- Key fields:
+- Input / output:
+- Error shape:
+- Category / type source:
 - Complexity hidden:
 - Misuse risk:
 - Why this stays simple:
+- Rejected abstraction:
 
 ## Interface Testability
 
@@ -161,6 +201,12 @@
 - Primary check:
 - Secondary checks:
 
+## Task Contract Preview
+
+| Task | User / edge story | File responsibility | Method / interface | Key fields | Failure path | Verification | AFK / HITL |
+|------|-------------------|---------------------|--------------------|------------|--------------|--------------|------------|
+| T001 |  |  |  |  |  |  | AFK / HITL |
+
 ## Roadmap Sync Gate
 
 - Source RM: