🎉 init: 小龙的工作空间

2026-06-06 10:40:48 +08:00
commit a188ee1426
3201 changed files with 231817 additions and 0 deletions
@@ -0,0 +1,458 @@
+## Execution Protocol — Planning Layer 🔵
+
+> This is the execution engine. Every agent turn MUST follow this protocol.
+> It replaces reactive execution with structured planning.
+> No new code. No new agents. Pure protocol enforcement via this prompt.
+
+### 0. Complexity Classification (MUST run first)
+
+Before ANY action, classify the task:
+
+**Simple → Direct Execution**
+
+| Criteria (ANY ONE) | Example |
+|--------------------|---------|
+| Single file read/write | "Read schema.ts" |
+| Single command | "npm test" |
+| Pure query | "What time is it?" |
+| Conversation | "Hello" |
+
+**Complex → MUST Use Task Tree**
+
+| Criteria (ANY ONE) | Example |
+|--------------------|---------|
+| 3+ files to modify | "Fix all FK references" |
+| Multi-step workflow | "Generate project → install → build → test" |
+| Schema/database change | "Add inspection_records table" |
+| Cross-project operation | "Fix all 3 generated projects" |
+| Auth/security change | "Add RBAC" |
+| New feature | "Add file upload" |
+| Bug root-cause analysis | "Why does FK constraint fail?" |
+| 2+ tool categories (read+write+exec) | "Read schema, fix it, rebuild" |
+| Estimated > 45 min or > 2 systems | "Epic-level task" |
+
+**Decision rule: if uncertain → treat as Complex.**
+
+---
+
+### 1. Task Tree Construction (Complex Tasks ONLY — MANDATORY)
+
+> ⚠️ Complex tasks MUST build a Task Tree BEFORE entering §2 PLAN.
+> No flat task lists. Task Tree is the only valid entry to Planning.
+
+#### 1a. Task Tree Definition
+
+Task Tree is an **execution tree**, not a feature tree.
+
+**Wrong (module tree):**
+```
+Project
+├── User
+├── Order
+└── Payment
+```
+
+**Correct (execution tree):**
+```
+Project
+├── T1 Architecture Setup
+├── T2 Database Schema     [depends_on: T1]
+├── T3 Backend API         [depends_on: T2]
+├── T4 Frontend            [depends_on: T3]
+└── T5 Verification        [depends_on: T4]
+```
+
+#### 1b. Mandatory Output Format
+
+Before §2 PLAN, output:
+
+```
+### Task Tree
+
+| Task ID | Name | Depends On | Parallelizable | Est. Size |
+|---------|------|------------|----------------|-----------|
+| T1 | Project Bootstrap | NONE | NO | Small |
+| T2 | Database Schema | T1 | NO | Medium |
+| T3 | Auth Service | T2 | YES | Medium |
+| T4 | User Service | T2 | YES | Medium |
+| T5 | API Gateway | T3,T4 | NO | Medium |
+```
+
+Each Task ID maps to a subtask in §2 PLAN.
+
+#### 1c. Dependency Rules
+
+**Hard Dependency** — upstream task MUST finish before starting:
+```
+T3 Backend API depends_on: T2 Database Schema
+```
+
+**Soft Dependency** — can start in parallel, must integrate before final:
+```
+T4 UI Pages depends_on: Design Tokens (soft)
+```
+
+#### 1d. Parallelism Optimization
+
+Agent MUST identify parallelizable tasks. Output:
+
+```
+### Parallel Groups
+
+**Group A (can run simultaneously):**
+- T3 Auth Service
+- T4 User Service
+
+**Group B (can run simultaneously):**
+- T6 Unit Tests
+- T7 Integration Tests
+```
+
+If all tasks form a serial chain (T1→T2→T3→...), **must explain why** parallelism is impossible.
+
+#### 1e. Learning Context Integration
+
+For each task, inject relevant lessons from the Learning Loop:
+
+```
+### Per-Task Injected Risks
+
+**T3: Backend Generator**
+- [R1] AP-3 DDL Constraint Leakage — add isConstraintLine() before column parsing
+  Source: reflections/2026-06-05-ddl-leakage.md
+- [R2] FK REPLACE → use ON CONFLICT DO UPDATE
+  Source: best-practices.md #11
+```
+
+#### 1f. Task Tree Quality Gate
+
+Before proceeding to §2 PLAN, verify ALL:
+
+- [ ] Root Task exists (exactly one task with depends_on: NONE)
+- [ ] No orphan tasks (every non-root task has a valid parent chain to root)
+- [ ] No circular dependency (A→B→C→A)
+- [ ] No XL Task (if estimated > 4h, split into sub-tasks)
+- [ ] No unjustified serial chain (if T1→T2→T3→T4 with no hard deps, explain or parallelize)
+- [ ] Every task has Injected Risks populated (§1e)
+- [ ] Agent can independently complete every task (no external human dependency)
+
+**If ANY gate fails: do NOT proceed to §2 PLAN. Re-split the tree.**
+
+---
+
+### 2. Planning Protocol (Complex Tasks ONLY)
+
+Before any tool call on a complex task:
+
+```
+## PLAN
+### Goal
+<one sentence>
+
+### Subtasks
+1. <step> → Verify: <how to check>
+2. <step> → Verify: <how to check>
+...
+
+### Risks
+- <potential pitfall>
+- <dependency risk>
+
+### Verification Strategy
+- Build: <yes/no>
+- Tests: <yes/no>
+- Lint: <yes/no>
+```
+
+Then use `update_plan` if >3 subtasks. Then execute.
+
+### 3. Pre-flight Check (Complex Tasks ONLY)
+
+Before executing step 1, **MUST** complete ALL of the following:
+
+#### 3a. Dependency Scan
+- [ ] Which files/tables/modules are involved?
+- [ ] What are their dependencies (FK, imports, types)?
+- [ ] What's the blast radius if I get it wrong?
+
+**Anti-pattern:** "I'll fix this FK error" → "Oh wait, here's another FK error" → "And another..."
+**Correct pattern:** "Let me scan ALL FK references first, then fix them all at once."
+
+#### 3b. Learning Context Injector (MANDATORY — 3 searches)
+
+**Search 1: Similar failures**
+```
+ctx_search(queries: ["<task_type> failure pattern lesson"], source: "reflections", sort: "timeline")
+```
+
+**Search 2: Relevant best practices**
+```
+memory_search(query: "<task_domain> best practice checklist pattern")
+```
+
+**Search 3: Relevant playbook**
+```
+Check playbooks/ for matching task type
+```
+
+Inject top findings into PLAN > Risks. Format:
+```
+### Injected Risks (from Learning Context)
+- [R1] <lesson from past failure> — source: <reflection/pattern file>
+- [R2] <relevant best practice violation> — source: best-practices.md #N
+- [R3] <playbook recommendation> — source: playbooks/<name>.md
+```
+
+#### 3c. Domain Checklist Injection
+
+**Based on task type, append the relevant checklist to PLAN:**
+
+**SQL / Schema tasks:**
+- □ FK 引用：所有 FK 用 ON CONFLICT DO UPDATE，不用 REPLACE（SQLite REPLACE = DELETE+INSERT）
+- □ DDL 解析：PRIMARY KEY / CONSTRAINT 行不能当数据字段
+- □ 迁移安全：先检查所有引用方，再改 schema
+- □ WAL 模式：多进程读写不阻塞
+
+**JavaScript / TypeScript tasks:**
+- □ Falsy 陷阱：0、''、false 用 `??` 替代 `||`（|| 会把 0 判为 falsy）
+- □ 类型生成：entity names 复数→单数（Albums→Album），但不碰 status/bus 等词根
+- □ 模板语法：模板字面量内嵌反引号用 \` 转义或字符串拼接
+- □ 启发式检测：必须 2+ 信号同时匹配，单信号不可靠
+
+**Next.js / Frontend tasks:**
+- □ 路径：Next.js App Router 用 `app/` 不是 `src/app/`
+- □ Tailwind content 路径匹配实际目录
+- □ tsconfig paths 匹配实际目录结构
+- □ JSX：三元表达式嵌套使用括号包裹，避免 `{}` 嵌套错误
+
+**Backend / API tasks:**
+- □ generateTypes 必须包含 User 实体 → CreateUserInput 类型
+- □ 所有 resource types 生成完整的 CRUD Input 类型
+- □ route params 命名与 service 函数签名一致
+
+**Generator / Builder tasks:**
+- □ 输出路径：验证生成目录结构与实际 runtime 预期一致
+- □ DDL→TS：schema.ts 中 CONSTRAINT/FK 行不能被解析为 interface 字段
+- □ Type mapping：SQL types 到 TS types 的映射表完整
+- □ Template safety：模板字面量不输出裸反引号
+
+**Release / CI tasks:**
+- □ Exit code 规范：PASS/WARN→0, FAIL→1
+- □ 回退路径：每个 destructive 操作有对应回退步骤
+- □ backward compat：新代码不改老接口
+
+If no checklist matches, add:
+- □ No domain-specific checklist available — proceed with extra caution
+
+### 4. Failure Replanning Protocol
+
+When a step fails:
+
+**DO NOT** fix the immediate error and continue blindly.
+
+**DO:**
+1. Log: what failed, error message, which step
+2. Analyze: is this a local fix or does it invalidate the plan?
+3. If local → fix, verify, continue
+4. If structural → **REPLAN** — output a revised PLAN section
+5. If same step fails 3 times → **PAUSE** and ask user
+6. **Auto-Capture Check** (after fix, before continuing):
+   → See complete trigger rules in §6 Auto-Capture Trigger (T1-T7)
+   → If ANY trigger matches → write structured Reflection to `reflections/YYYY-MM-DD-<task>.md`
+   → Reflection MUST contain ALL 7 required fields (Context/Root Cause/Fix/Pattern Class/Future Trigger/Checklist/Recurrence Count)
+   → Skip only when: fix < 5 min + first occurrence + no test/build/lint failure
+
+7. **Promotion Check** (after Reflection written):
+   | Appearances | Action | Destination |
+   |------------|--------|------------|
+   | 1st | Reflection | reflections/ |
+   | 2nd | Pattern | patterns/design-patterns.md (new section) |
+   | 3rd | Best Practice | patterns/best-practices.md (numbered entry) |
+   | 4th | Checklist Item | AGENTS.md §3c Domain Checklists |
+   | 5th | Hard Rule | AGENTS.md §3c (bolded, marked ⚠️ HARD RULE) |
+
+### 5. Verification Protocol (Complex Tasks ONLY)
+
+After all subtasks complete:
+
+```
+## VERIFICATION
+- Build: [PASS/FAIL]
+- Tests: [PASS/FAIL / N suites / N tests]
+- Lint: [PASS/FAIL]
+- Regression risk: [NONE/LOW/MEDIUM/HIGH]
+- Manual changes needed: [NONE / <description>]
+```
+
+**MANDATORY GATE: Pre-flight Compliance Check**
+
+Before closing any complex task, verify ALL of:
+
+- [ ] PLAN contains `### Injected Risks (from Learning Context)` section
+- [ ] At least 2 knowledge sources were searched (ctx_search / memory_search / playbooks)
+- [ ] Matching domain checklist from §3c is included in PLAN
+- [ ] If failure occurred: structured Reflection was written to `reflections/YYYY-MM-DD-<task>.md`
+- [ ] Reflection contains ALL 7 required fields (Context/Root Cause/Fix/Pattern Class/Future Trigger/Checklist/Recurrence)
+
+If ANY gate fails: **task is NOT complete**. Go back and fill the gap.
+
+### 6. Governance Compliance 🔒
+
+Compliance is mandatory for all complex task execution.
+
+- **State machine, heartbeat, blocker, replan, scope detection, health score, auto-stop, recovery mode** → see GOVERNANCE.md
+- **Multi-project portfolio management** → see PORTFOLIO.md
+- **MANDATORY Governance Quality Gate** must run before project output (GOVERNANCE.md §9)
+
+### 7. Auto-Capture Trigger — COMPLETE Rule Set (after ANY failure)
+
+**ALWAYS check these conditions after fixing a failure. Write Reflection when ANY condition matches:**
+
+| # | Trigger Condition | Why |
+|---|------------------|-----|
+| T1 | `build` command failed | Build failure always indicates systemic error |
+| T2 | `test` command returned non-zero or unexpected failures | Test failure = regression risk |
+| T3 | `lint` / `tsc --noEmit` failed | Syntax/type errors in generated code |
+| T4 | Fix time > 30 minutes elapsed | Long fix = complex root cause worth documenting |
+| T5 | Same error class appeared before (check ctx_search / Promotion Log) | Recurrence → must upgrade |
+| T6 | Generated output path/format/structure mismatched target convention | E.g. `src/app/` vs `app/`, wrong SQL dialect, missing types |
+| T7 | Generated content caused runtime crash or data corruption | Silent data corruption is highest severity |
+
+**Skip reflection (not worth recording) when:**
+- Fix < 5 min AND never seen before AND no test/build/lint failure
+- Typo fix (single character, no logic change)
+- Expected external service failure (network timeout, API rate limit)
+
+**Reflection write checklist (ALL 7 fields REQUIRED):**
+```
+[ ] Context — what task was being performed
+[ ] Root Cause — the bug, not the symptom (banned: "以后注意", "下次小心")
+[ ] Fix — exact change, with code diff if applicable
+[ ] Pattern Class — abstract category (e.g. "SQLite FK", "JS Falsy Coercion", "Path Convention")
+[ ] Future Trigger — when to inject this lesson (e.g. "any SQL schema change")
+[ ] Checklist — ≥2 actionable checks for next time
+[ ] Recurrence Count — 1 (update on each recurrence)
+```
+
+---
+
+## Learning Loop 🔄
+
+> Knowledge stored in reflections/patterns/playbooks MUST flow back into Planning.
+> This section closes the loop.
+
+### Loop Architecture
+
+```
+Failure/Success
+    ↓
+Reflection (structured, with Pattern Class)
+    ↓
+Promotion Check (1→2→3→4→5 appearances)
+    ↓
+Pattern → Best Practice → Checklist → Hard Rule
+    ↓
+Pre-flight Injector (§3b) + Domain Checklists (§3c)
+    ↓
+Next Plan includes past lessons
+    ↓
+Execution
+    ↓
+Verification → triggers new Reflection if needed
+    ↓
+(loop closes)
+```
+
+### Promotion Rules
+
+| Count | Promotion To | Location |
+|-------|-------------|----------|
+| 1st | Reflection | `reflections/YYYY-MM-DD-<task>.md` |
+| 2nd | Design Pattern | `patterns/design-patterns.md` (new Anti-Pattern section) |
+| 3rd | Best Practice | `patterns/best-practices.md` (numbered entry) |
+| 4th | Domain Checklist | AGENTS.md §3c (update matching checklist, or create new) |
+| 5th | Hard Rule | AGENTS.md §3c (bolded, marked ⚠️ HARD RULE) |
+
+### Quality Gate for Reflections
+
+A valid Reflection MUST include ALL of:
+- [ ] Context (what task)
+- [ ] Root Cause (the bug, not the symptom)
+- [ ] Fix (exact change)
+- [ ] Pattern Class (abstract category)
+- [ ] Future Trigger (when to re-inject)
+- [ ] Checklist (actionable items)
+- [ ] Recurrence Count
+
+**Rejected:** "以后注意", "下次小心", "当时没想清楚", "应该多测试"
+**Accepted:** "SQLite FK: REPLACE=DELETE+INSERT, use ON CONFLICT DO UPDATE"
+
+### Storage Locations
+
+```
+reflections/              ← First occurrence of a failure pattern
+patterns/design-patterns  ← Abstract reusable anti-patterns (≥2 occurrences)
+patterns/best-practices   ← Validated rules (≥3 occurrences)
+AGENTS.md §3c             ← Domain Checklists (≥4 occurrences)
+AGENTS.md §3c ⚠️          ← Hard Rules (≥5 occurrences)
+
+playbooks/                ← Successful multi-step workflows (not failure-driven)
+vault.md §Self-Evolution  ← History of promotions (timeline)
+```
+
+---
+
+## Agent Package Context Budget ⚠️ HARD RULE
+
+> Established 2026-06-05. Every Agent Package MUST declare its token budget before execution.
+> This prevents context overflow, KV cache thrashing, and mid-task truncation in multi-agent workflows.
+
+### Size → Token Budget Mapping
+
+| Level | Reading | Modifying | New Code | Dependencies | Token Budget |
+|-------|---------|-----------|----------|-------------|-------------|
+| Small | ≤3 files | ≤2 files | ≤300 lines | ≤1 | ≤30K tokens |
+| Medium | ≤8 files | ≤5 files | ≤800 lines | ≤3 | ≤80K tokens |
+| Large | ≤15 files | ≤10 files | ≤1500 lines | ≤5 | ≤200K tokens |
+| XL | ❌ FORBIDDEN | ❌ | ❌ | ❌ | ❌ |
+
+### Input Size Pre-check (MANDATORY)
+
+Before dispatching any Agent Package, pre-compute:
+
+1. **File inventory** — list every file the agent will read
+2. **Token estimate** — for code: `bytes / 3`; for Chinese text: `chars / 1.5`; round up 10% for safety
+3. **Budget check** — `sum(estimated_input_tokens) + prompt_overhead(2K) + output_buffer(20% of budget)` ≤ Token Budget
+
+```
+### Context Budget Declaration
+
+**AP-N**: <name>
+- Files to read: N (total ~X lines / ~Y estimated tokens)
+- Prompt overhead: ~2K tokens
+- Output buffer: ~Z tokens (20% of budget)
+- Total estimated: ~W tokens
+- Budget: V tokens
+- Utilization: (W/V) × 100%
+- ⚠️ OVER BUDGET: <yes/no> → if YES, split further
+```
+
+### Over-budget Resolution
+
+If estimated utilization > 90%:
+1. Split the package into sub-packages
+2. Pre-index large reference files instead of reading them inline (use ctx_index → ctx_search)
+3. Provide only relevant snippets, not entire files
+4. Re-check budget after split
+
+### Token Estimation Constants
+
+| Content Type | Token Ratio | Notes |
+|-------------|------------|-------|
+| TypeScript/JS | 1 token ≈ 3.5 chars | conservative estimate |
+| Python | 1 token ≈ 3.5 chars | |
+| SQL | 1 token ≈ 3.0 chars | shorter tokens |
+| Chinese text | 1 token ≈ 1.5 chars | CJK characters are token-heavy |
+| English prose | 1 token ≈ 4.0 chars | |
+| JSON/YAML | 1 token ≈ 3.0 chars | punctuation-heavy |
+