ai-spec-dev 0.31.0 → 0.35.0

package/docs-assets/purpose/architecture-overview.svg

@@ -0,0 +1,64 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1400" height="980" viewBox="0 0 1400 980">
+<rect width="1400" height="980" fill="#0f172a"/>
+<text x="700" y="54" text-anchor="middle" font-size="30" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#f8fafc" font-weight="700">ai-spec 整体架构鸟瞰</text>
+<defs>
+  <marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="5" orient="auto">
+    <path d="M0,0 L10,5 L0,10 Z" fill="#94a3b8"/>
+  </marker>
+</defs>
+<rect x="80" y="110" width="1240" height="120" rx="20" fill="#111827" stroke="#334155" stroke-width="2"/>
+<text x="120" y="145" font-size="24" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#93c5fd" font-weight="700">输入层</text>
+<rect x="120" y="165" width="300" height="42" rx="12" fill="#1e293b" stroke="#475569"/>
+<text x="270" y="192" text-anchor="middle" font-size="19" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#e2e8f0">💬 需求描述（自然语言）</text>
+<rect x="450" y="165" width="380" height="42" rx="12" fill="#1e293b" stroke="#475569"/>
+<text x="640" y="192" text-anchor="middle" font-size="19" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#e2e8f0">📜 项目宪法（§1-§8 规则 + §9 教训）</text>
+<rect x="860" y="165" width="380" height="42" rx="12" fill="#1e293b" stroke="#475569"/>
+<text x="1050" y="192" text-anchor="middle" font-size="19" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#e2e8f0">🗂️ 项目上下文（结构 / 依赖 / 路由）</text>
+<rect x="80" y="270" width="1240" height="140" rx="20" fill="#111827" stroke="#334155" stroke-width="2"/>
+<text x="120" y="305" font-size="24" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#a7f3d0" font-weight="700">双层契约</text>
+<rect x="220" y="325" width="380" height="52" rx="14" fill="#064e3b" stroke="#10b981"/>
+<text x="410" y="357" text-anchor="middle" font-size="22" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#ecfdf5">📄 Spec（Markdown，人类可读）</text>
+<rect x="790" y="325" width="380" height="52" rx="14" fill="#0c4a6e" stroke="#38bdf8"/>
+<text x="980" y="357" text-anchor="middle" font-size="22" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#e0f2fe">📊 DSL（JSON，机器可读）</text>
+<line x1="270" y1="207" x2="410" y2="325" stroke="#94a3b8" stroke-width="3" marker-end="url(#arrow)"/>
+<line x1="640" y1="207" x2="410" y2="325" stroke="#94a3b8" stroke-width="3" marker-end="url(#arrow)"/>
+<line x1="1050" y1="207" x2="410" y2="325" stroke="#94a3b8" stroke-width="3" marker-end="url(#arrow)"/>
+<text x="610" y="252" text-anchor="middle" font-size="16" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#cbd5e1">宪法全文注入所有 prompt</text>
+<line x1="600" y1="351" x2="790" y2="351" stroke="#94a3b8" stroke-width="3" marker-end="url(#arrow)"/>
+<rect x="80" y="450" width="1240" height="150" rx="20" fill="#111827" stroke="#334155" stroke-width="2"/>
+<text x="120" y="485" font-size="24" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#fde68a" font-weight="700">质量门控 + 生成层</text>
+<rect x="120" y="515" width="280" height="50" rx="14" fill="#78350f" stroke="#f59e0b"/>
+<text x="260" y="547" text-anchor="middle" font-size="20" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#fffbeb">🎯 Spec 质量评分</text>
+<rect x="450" y="515" width="280" height="50" rx="14" fill="#3f2a62" stroke="#c084fc"/>
+<text x="590" y="547" text-anchor="middle" font-size="20" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#f5f3ff">🧑‍💻 Approval Gate</text>
+<rect x="780" y="500" width="350" height="80" rx="16" fill="#1d4ed8" stroke="#60a5fa"/>
+<text x="955" y="535" text-anchor="middle" font-size="21" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#eff6ff">⚙️ Task 分层代码生成</text>
+<text x="955" y="562" text-anchor="middle" font-size="16" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#dbeafe">data → service → api → view → route</text>
+<rect x="1160" y="510" width="120" height="60" rx="14" fill="#1e293b" stroke="#64748b"/>
+<text x="1220" y="537" text-anchor="middle" font-size="18" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#e2e8f0">🗄️ Cache</text>
+<text x="1220" y="559" text-anchor="middle" font-size="13" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#cbd5e1">签名 / 契约</text>
+<line x1="980" y1="377" x2="980" y2="500" stroke="#94a3b8" stroke-width="3" marker-end="url(#arrow)"/>
+<line x1="400" y1="540" x2="450" y2="540" stroke="#94a3b8" stroke-width="3" marker-end="url(#arrow)"/>
+<line x1="730" y1="540" x2="780" y2="540" stroke="#94a3b8" stroke-width="3" marker-end="url(#arrow)"/>
+<line x1="1130" y1="540" x2="1160" y2="540" stroke="#94a3b8" stroke-width="3" marker-end="url(#arrow)"/>
+<line x1="1160" y1="555" x2="1130" y2="555" stroke="#94a3b8" stroke-width="3" marker-end="url(#arrow)"/>
+<text x="365" y="505" text-anchor="middle" font-size="15" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#cbd5e1">通过 / 不足</text>
+<rect x="80" y="645" width="1240" height="130" rx="20" fill="#111827" stroke="#334155" stroke-width="2"/>
+<text x="120" y="680" font-size="24" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#fca5a5" font-weight="700">验证层</text>
+<rect x="240" y="700" width="360" height="46" rx="14" fill="#7f1d1d" stroke="#ef4444"/>
+<text x="420" y="729" text-anchor="middle" font-size="20" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#fef2f2">🔄 错误反馈闭环（≤2 cycle）</text>
+<rect x="760" y="700" width="360" height="46" rx="14" fill="#4c0519" stroke="#f43f5e"/>
+<text x="940" y="729" text-anchor="middle" font-size="20" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#fff1f2">🔬 3-pass 代码审查</text>
+<line x1="955" y1="580" x2="420" y2="700" stroke="#94a3b8" stroke-width="3" marker-end="url(#arrow)"/>
+<line x1="600" y1="723" x2="760" y2="723" stroke="#94a3b8" stroke-width="3" marker-end="url(#arrow)"/>
+<rect x="80" y="810" width="1240" height="120" rx="20" fill="#111827" stroke="#334155" stroke-width="2"/>
+<text x="120" y="845" font-size="24" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#c4b5fd" font-weight="700">学习层（闭环）</text>
+<rect x="260" y="860" width="360" height="42" rx="14" fill="#312e81" stroke="#818cf8"/>
+<text x="440" y="887" text-anchor="middle" font-size="19" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#eef2ff">📚 §9 知识积累</text>
+<rect x="780" y="860" width="360" height="42" rx="14" fill="#14532d" stroke="#4ade80"/>
+<text x="960" y="887" text-anchor="middle" font-size="19" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#f0fdf4">📈 Harness Self-Eval</text>
+<line x1="940" y1="746" x2="440" y2="860" stroke="#94a3b8" stroke-width="3" marker-end="url(#arrow)"/>
+<line x1="940" y1="746" x2="960" y2="860" stroke="#94a3b8" stroke-width="3" marker-end="url(#arrow)"/>
+<line x1="440" y1="860" x2="640" y2="207" stroke="#94a3b8" stroke-width="3" stroke-dasharray="8 8" marker-end="url(#arrow)"/>
+<text x="560" y="525" text-anchor="middle" transform="rotate(-73 560 525)" font-size="15" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#cbd5e1">更新宪法 §9</text>
+</svg>

package/docs-assets/purpose/create-pipeline.svg

@@ -0,0 +1,113 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1500" height="1800" viewBox="0 0 1500 1800">
+<rect width="1500" height="1800" fill="#0f172a"/>
+<text x="750" y="55" text-anchor="middle" font-size="32" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#f8fafc" font-weight="700">ai-spec create 完整流水线</text>
+<defs>
+  <marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="5" orient="auto">
+    <path d="M0,0 L10,5 L0,10 Z" fill="#94a3b8"/>
+  </marker>
+</defs>
+<g font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif">
+  <rect x="420" y="90" width="660" height="60" rx="18" fill="#1d4ed8" stroke="#60a5fa" stroke-width="2"/>
+  <text x="750" y="128" text-anchor="middle" font-size="24" fill="#eff6ff" font-weight="700">▶ ai-spec create &lt;idea&gt;</text>
+
+  <rect x="340" y="190" width="820" height="74" rx="18" fill="#1f2937" stroke="#475569"/>
+  <text x="750" y="223" text-anchor="middle" font-size="23" fill="#f8fafc" font-weight="700">Step 1 · 加载项目上下文</text>
+  <text x="750" y="250" text-anchor="middle" font-size="17" fill="#cbd5e1">ContextLoader 扫描代码结构 / 依赖 / 路由 / schema</text>
+
+  <rect x="340" y="305" width="820" height="74" rx="18" fill="#1f2937" stroke="#475569"/>
+  <text x="750" y="338" text-anchor="middle" font-size="23" fill="#f8fafc" font-weight="700">Step 2 · Spec + Tasks 生成</text>
+  <text x="750" y="365" text-anchor="middle" font-size="17" fill="#cbd5e1">宪法全文注入 prompt 最高优先级</text>
+
+  <rect x="340" y="420" width="820" height="74" rx="18" fill="#1f2937" stroke="#475569"/>
+  <text x="750" y="453" text-anchor="middle" font-size="23" fill="#f8fafc" font-weight="700">Step 3 · 交互式润色</text>
+  <text x="750" y="480" text-anchor="middle" font-size="17" fill="#cbd5e1">Diff 预览，可多轮修改</text>
+
+  <rect x="340" y="535" width="820" height="74" rx="18" fill="#78350f" stroke="#f59e0b"/>
+  <text x="750" y="568" text-anchor="middle" font-size="23" fill="#fffbeb" font-weight="700">Step 3.4 · Spec 质量评估</text>
+  <text x="750" y="595" text-anchor="middle" font-size="17" fill="#fde68a">覆盖度 / 清晰度 / 宪法符合度打分</text>
+
+  <polygon points="750,655 930,745 750,835 570,745" fill="#3f3f46" stroke="#71717a" stroke-width="2"/>
+  <text x="750" y="734" text-anchor="middle" font-size="24" fill="#f8fafc" font-weight="700">Score ≥</text>
+  <text x="750" y="764" text-anchor="middle" font-size="24" fill="#f8fafc" font-weight="700">minSpecScore ?</text>
+
+  <rect x="110" y="715" width="300" height="60" rx="18" fill="#7f1d1d" stroke="#ef4444" stroke-width="2"/>
+  <text x="260" y="752" text-anchor="middle" font-size="20" fill="#fef2f2">🚫 exit(1)（--force 可继续）</text>
+
+  <rect x="1020" y="700" width="350" height="92" rx="18" fill="#3b0764" stroke="#c084fc" stroke-width="2"/>
+  <text x="1195" y="736" text-anchor="middle" font-size="23" fill="#faf5ff" font-weight="700">Approval Gate</text>
+  <text x="1195" y="765" text-anchor="middle" font-size="16" fill="#e9d5ff">展示 Spec + DSL 摘要</text>
+  <text x="1195" y="788" text-anchor="middle" font-size="16" fill="#e9d5ff">等待人工决策</text>
+
+  <rect x="1010" y="855" width="160" height="58" rx="16" fill="#7f1d1d" stroke="#ef4444"/>
+  <text x="1090" y="891" text-anchor="middle" font-size="20" fill="#fef2f2">Abort</text>
+  <rect x="1210" y="855" width="220" height="58" rx="16" fill="#14532d" stroke="#4ade80"/>
+  <text x="1320" y="891" text-anchor="middle" font-size="20" fill="#f0fdf4">Proceed</text>
+
+  <rect x="1070" y="955" width="250" height="84" rx="18" fill="#0c4a6e" stroke="#38bdf8" stroke-width="2"/>
+  <text x="1195" y="990" text-anchor="middle" font-size="22" fill="#e0f2fe" font-weight="700">DSL 提取 + 校验</text>
+  <text x="1195" y="1017" text-anchor="middle" font-size="16" fill="#bae6fd">9 条规则，失败最多重试 2 次</text>
+
+  <rect x="1070" y="1085" width="250" height="76" rx="18" fill="#1e293b" stroke="#64748b"/>
+  <text x="1195" y="1118" text-anchor="middle" font-size="20" fill="#e2e8f0" font-weight="700">RunId + 快照初始化</text>
+  <text x="1195" y="1145" text-anchor="middle" font-size="16" fill="#cbd5e1">Prompt Hash 写入 RunLog</text>
+
+  <rect x="930" y="1205" width="530" height="106" rx="20" fill="#1d4ed8" stroke="#60a5fa" stroke-width="2"/>
+  <text x="1195" y="1245" text-anchor="middle" font-size="24" fill="#eff6ff" font-weight="700">Step 5–6 · Task 分层代码生成</text>
+  <text x="1195" y="1276" text-anchor="middle" font-size="17" fill="#dbeafe">data → infra → service → api → view → route → test</text>
+  <text x="1195" y="1299" text-anchor="middle" font-size="17" fill="#dbeafe">层内拓扑排序 → batch 并行 → 缓存更新</text>
+
+  <rect x="1070" y="1355" width="250" height="60" rx="18" fill="#334155" stroke="#64748b"/>
+  <text x="1195" y="1392" text-anchor="middle" font-size="20" fill="#f8fafc">Step 7 · 测试骨架生成</text>
+
+  <rect x="120" y="1205" width="650" height="420" rx="24" fill="#111827" stroke="#334155" stroke-width="2"/>
+  <text x="445" y="1245" text-anchor="middle" font-size="26" fill="#fca5a5" font-weight="700">Step 8 · 错误反馈闭环</text>
+  <rect x="220" y="1285" width="450" height="60" rx="16" fill="#7f1d1d" stroke="#ef4444"/>
+  <text x="445" y="1322" text-anchor="middle" font-size="21" fill="#fef2f2">运行 test / lint / tsc</text>
+  <polygon points="445,1390 605,1470 445,1550 285,1470" fill="#3f3f46" stroke="#71717a" stroke-width="2"/>
+  <text x="445" y="1460" text-anchor="middle" font-size="23" fill="#f8fafc" font-weight="700">全部通过？</text>
+  <rect x="170" y="1578" width="200" height="58" rx="16" fill="#14532d" stroke="#4ade80"/>
+  <text x="270" y="1614" text-anchor="middle" font-size="19" fill="#f0fdf4">通过 → Step 9</text>
+  <rect x="410" y="1568" width="390" height="78" rx="18" fill="#92400e" stroke="#f59e0b"/>
+  <text x="605" y="1600" text-anchor="middle" font-size="20" fill="#fffbeb">有错误，且 cycle ≤ 2</text>
+  <text x="605" y="1625" text-anchor="middle" font-size="16" fill="#fde68a">依赖图排序 → AI 逐文件修复 → 回到测试</text>
+  <rect x="170" y="1670" width="630" height="72" rx="18" fill="#4b5563" stroke="#9ca3af"/>
+  <text x="485" y="1703" text-anchor="middle" font-size="20" fill="#f8fafc">cycle 2 仍失败 → ⚠️ 黄色警告，继续进入 Step 9</text>
+
+  <rect x="930" y="1455" width="530" height="84" rx="18" fill="#4c0519" stroke="#f43f5e" stroke-width="2"/>
+  <text x="1195" y="1491" text-anchor="middle" font-size="23" fill="#fff1f2" font-weight="700">Step 9 · 3-pass 代码审查</text>
+  <text x="1195" y="1518" text-anchor="middle" font-size="16" fill="#fecdd3">Pass1 架构 · Pass2 实现 · Pass3 影响面 / 复杂度</text>
+
+  <rect x="930" y="1585" width="250" height="76" rx="18" fill="#312e81" stroke="#818cf8"/>
+  <text x="1055" y="1618" text-anchor="middle" font-size="20" fill="#eef2ff" font-weight="700">§9 知识积累</text>
+  <text x="1055" y="1645" text-anchor="middle" font-size="15" fill="#c7d2fe">审查 issue 自动追加宪法</text>
+
+  <rect x="1210" y="1585" width="250" height="92" rx="18" fill="#14532d" stroke="#4ade80"/>
+  <text x="1335" y="1618" text-anchor="middle" font-size="20" fill="#f0fdf4" font-weight="700">Step 10 · Harness Self-Eval</text>
+  <text x="1335" y="1645" text-anchor="middle" font-size="15" fill="#dcfce7">DSL 覆盖 + Compile + Review</text>
+
+  <rect x="1020" y="1715" width="350" height="56" rx="18" fill="#0f766e" stroke="#2dd4bf"/>
+  <text x="1195" y="1749" text-anchor="middle" font-size="22" fill="#ecfeff" font-weight="700">✔ Done：Spec / DSL / 代码 / RunLog 全部落盘</text>
+
+  <line x1="750" y1="150" x2="750" y2="190" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="750" y1="264" x2="750" y2="305" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="750" y1="379" x2="750" y2="420" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="750" y1="494" x2="750" y2="655" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="570" y1="745" x2="410" y2="745" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="930" y1="745" x2="1020" y2="745" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="1195" y1="792" x2="1090" y2="855" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="1195" y1="792" x2="1320" y2="855" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="1320" y1="913" x2="1195" y2="955" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="1195" y1="1039" x2="1195" y2="1085" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="1195" y1="1161" x2="1195" y2="1205" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="1195" y1="1311" x2="1195" y2="1355" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="1070" y1="1385" x2="770" y2="1385" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="445" y1="1345" x2="445" y2="1390" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="365" y1="1470" x2="270" y2="1578" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="525" y1="1542" x2="525" y2="1568" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="800" y1="1607" x2="930" y2="1497" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="270" y1="1636" x2="930" y2="1497" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="1195" y1="1539" x2="1055" y2="1585" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="1195" y1="1539" x2="1335" y2="1585" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="1335" y1="1677" x2="1250" y2="1715" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+</g>
+</svg>

package/docs-assets/purpose/task-layering.svg

@@ -0,0 +1,74 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1500" height="980" viewBox="0 0 1500 980">
+<rect width="1500" height="980" fill="#0f172a"/>
+<text x="750" y="56" text-anchor="middle" font-size="30" font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif" fill="#f8fafc" font-weight="700">Task 分层与层内执行模型</text>
+<defs>
+  <marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="5" orient="auto">
+    <path d="M0,0 L10,5 L0,10 Z" fill="#94a3b8"/>
+  </marker>
+</defs>
+<g font-family="Arial, PingFang SC, Microsoft YaHei, sans-serif">
+  <rect x="80" y="110" width="1340" height="150" rx="22" fill="#111827" stroke="#334155" stroke-width="2"/>
+  <text x="140" y="150" font-size="24" fill="#93c5fd" font-weight="700">七层顺序（跨层串行）</text>
+  <rect x="120" y="180" width="140" height="42" rx="14" fill="#1d4ed8" stroke="#60a5fa"/><text x="190" y="207" text-anchor="middle" font-size="20" fill="#eff6ff">data</text>
+  <rect x="310" y="180" width="140" height="42" rx="14" fill="#0369a1" stroke="#38bdf8"/><text x="380" y="207" text-anchor="middle" font-size="20" fill="#e0f2fe">infra</text>
+  <rect x="500" y="180" width="160" height="42" rx="14" fill="#0f766e" stroke="#2dd4bf"/><text x="580" y="207" text-anchor="middle" font-size="20" fill="#ecfeff">service</text>
+  <rect x="710" y="180" width="140" height="42" rx="14" fill="#15803d" stroke="#4ade80"/><text x="780" y="207" text-anchor="middle" font-size="20" fill="#f0fdf4">api</text>
+  <rect x="900" y="180" width="150" height="42" rx="14" fill="#7c3aed" stroke="#c084fc"/><text x="975" y="207" text-anchor="middle" font-size="20" fill="#f5f3ff">view</text>
+  <rect x="1100" y="180" width="150" height="42" rx="14" fill="#c2410c" stroke="#fb923c"/><text x="1175" y="207" text-anchor="middle" font-size="20" fill="#fff7ed">route</text>
+  <rect x="1300" y="180" width="90" height="42" rx="14" fill="#be123c" stroke="#fb7185"/><text x="1345" y="207" text-anchor="middle" font-size="20" fill="#fff1f2">test</text>
+  <line x1="260" y1="201" x2="310" y2="201" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="450" y1="201" x2="500" y2="201" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="660" y1="201" x2="710" y2="201" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="850" y1="201" x2="900" y2="201" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="1050" y1="201" x2="1100" y2="201" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="1250" y1="201" x2="1300" y2="201" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+
+  <rect x="80" y="320" width="760" height="540" rx="22" fill="#111827" stroke="#334155" stroke-width="2"/>
+  <text x="120" y="360" font-size="24" fill="#a7f3d0" font-weight="700">单层内部执行（以 api 层为例）</text>
+  <rect x="140" y="395" width="640" height="60" rx="16" fill="#334155" stroke="#64748b"/>
+  <text x="460" y="432" text-anchor="middle" font-size="22" fill="#f8fafc">拓扑排序：按 dependencies 字段分 batch</text>
+
+  <rect x="140" y="500" width="290" height="220" rx="18" fill="#052e16" stroke="#22c55e"/>
+  <text x="285" y="537" text-anchor="middle" font-size="24" fill="#dcfce7" font-weight="700">Batch 1</text>
+  <text x="285" y="565" text-anchor="middle" font-size="16" fill="#bbf7d0">无依赖 → 可并行</text>
+  <rect x="185" y="590" width="200" height="42" rx="12" fill="#166534" stroke="#4ade80"/>
+  <text x="285" y="617" text-anchor="middle" font-size="18" fill="#f0fdf4">userController.ts</text>
+  <rect x="185" y="648" width="200" height="42" rx="12" fill="#166534" stroke="#4ade80"/>
+  <text x="285" y="675" text-anchor="middle" font-size="18" fill="#f0fdf4">authController.ts</text>
+  <text x="285" y="705" text-anchor="middle" font-size="15" fill="#bbf7d0">完成后立即更新 generatedFileCache</text>
+
+  <rect x="490" y="500" width="290" height="220" rx="18" fill="#3f2a62" stroke="#c084fc"/>
+  <text x="635" y="537" text-anchor="middle" font-size="24" fill="#faf5ff" font-weight="700">Batch 2</text>
+  <text x="635" y="565" text-anchor="middle" font-size="16" fill="#e9d5ff">依赖 Batch 1 → 可并行</text>
+  <rect x="535" y="605" width="200" height="60" rx="12" fill="#6d28d9" stroke="#c084fc"/>
+  <text x="635" y="632" text-anchor="middle" font-size="18" fill="#f5f3ff">adminController.ts</text>
+  <text x="635" y="654" text-anchor="middle" font-size="14" fill="#ede9fe">需要 import userController</text>
+  <text x="635" y="705" text-anchor="middle" font-size="15" fill="#e9d5ff">完成后再次更新 generatedFileCache</text>
+
+  <line x1="460" y1="455" x2="285" y2="500" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="430" y1="610" x2="490" y2="610" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <text x="460" y="592" text-anchor="middle" font-size="15" fill="#cbd5e1">Batch 1 完成</text>
+
+  <rect x="900" y="320" width="520" height="540" rx="22" fill="#111827" stroke="#334155" stroke-width="2"/>
+  <text x="940" y="360" font-size="24" fill="#fde68a" font-weight="700">共享状态与层完成动作</text>
+
+  <rect x="960" y="400" width="400" height="150" rx="18" fill="#1e293b" stroke="#64748b"/>
+  <text x="1160" y="438" text-anchor="middle" font-size="24" fill="#f8fafc" font-weight="700">generatedFileCache</text>
+  <text x="1160" y="475" text-anchor="middle" font-size="18" fill="#cbd5e1">函数签名</text>
+  <text x="1160" y="505" text-anchor="middle" font-size="18" fill="#cbd5e1">文件路径</text>
+  <text x="1160" y="535" text-anchor="middle" font-size="18" fill="#cbd5e1">behavioral contracts</text>
+
+  <line x1="780" y1="610" x2="960" y2="475" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <line x1="960" y1="505" x2="780" y2="680" stroke="#94a3b8" stroke-width="4" marker-end="url(#arrow)"/>
+  <text x="870" y="525" text-anchor="middle" font-size="15" fill="#cbd5e1">批次读写</text>
+
+  <rect x="960" y="620" width="400" height="170" rx="18" fill="#78350f" stroke="#f59e0b"/>
+  <text x="1160" y="657" text-anchor="middle" font-size="24" fill="#fffbeb" font-weight="700">整层执行关系</text>
+  <text x="1160" y="695" text-anchor="middle" font-size="18" fill="#fde68a">进入当前层</text>
+  <text x="1160" y="725" text-anchor="middle" font-size="18" fill="#fde68a">↓</text>
+  <text x="1160" y="755" text-anchor="middle" font-size="18" fill="#fde68a">层内拓扑排序 + batch 并行</text>
+  <text x="1160" y="785" text-anchor="middle" font-size="18" fill="#fde68a">↓</text>
+  <text x="1160" y="815" text-anchor="middle" font-size="18" fill="#fde68a">统一更新共享 config 文件（如 routes/index.ts）</text>
+  <text x="1160" y="845" text-anchor="middle" font-size="18" fill="#fde68a">↓ 进入下一层</text>
+</g>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spec-dev",
-  "version": "0.31.0",
+  "version": "0.35.0",
   "description": "AI-driven Development Orchestrator SDK & CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,9 @@
   },
   "scripts": {
     "build": "tsup",
-    "dev": "tsup --watch"
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "ai",
@@ -41,6 +43,7 @@
     "glob": "^13.0.6",
     "ts-node": "^10.9.2",
     "tsup": "^8.4.0",
-    "typescript": "^5.7.3"
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.0"
   }
 }

package/prompts/codegen.prompt.ts

@@ -181,34 +181,122 @@ export function getCodeGenSystemPrompt(repoType?: string): string {
  * Focuses on design-level correctness: spec compliance, layer separation, API contract.
  * Deliberately ignores micro-level implementation details.
  */
-export const reviewArchitectureSystemPrompt = `You are a Senior Software Architect reviewing the HIGH-LEVEL design of a code change.
+// ─── Pass 0 — Spec Compliance Check ──────────────────────────────────────────
+
+/**
+ * Pass 0 — Spec Compliance Check (inspired by Superpowers' spec-compliance review).
+ *
+ * Dedicated, exhaustive pass that answers ONE question:
+ *   "Does the implementation cover ALL requirements stated in the spec?"
+ *
+ * This is a completeness check, NOT a quality check.
+ * Architecture quality, code style, error handling are all handled by later passes.
+ */
+export const specComplianceSystemPrompt = `You are a QA Engineer performing a SPEC COMPLIANCE CHECK.
+
+Your sole job is to verify that the implementation covers every requirement stated in the feature spec.
+This is a completeness audit — NOT a code quality review. Do not comment on architecture, style, or implementation details.
+
+## How to audit:
+
+1. Parse the spec and extract EVERY stated requirement into these categories:
+   - **Endpoints**: each HTTP method + path listed or implied
+   - **Data Models**: each entity, field, constraint mentioned
+   - **Business Rules**: validations, conditions, calculations stated
+   - **Auth Requirements**: which endpoints need auth, which roles are allowed
+   - **Error Cases**: explicit error codes or failure scenarios mentioned
+   - **Side Effects**: emails sent, events fired, caches invalidated, etc.
+
+2. For each extracted requirement, check the provided code:
+   - ✅ **Covered** — clearly implemented
+   - ⚠️ **Partial** — exists but incomplete (e.g. endpoint exists but missing a field or error case)
+   - ❌ **Missing** — requirement stated in spec but not found in code
+
+3. Output a compliance checklist. Be exhaustive — list every single requirement.
+
+## Output format:
+
+## 📋 Spec Compliance Report
+
+### Endpoints
+✅ / ⚠️ / ❌  METHOD /path — one-line status
+
+### Data Models
+✅ / ⚠️ / ❌  ModelName — one-line status
+
+### Business Rules
+✅ / ⚠️ / ❌  Rule description — one-line status
+
+### Auth & Permissions
+✅ / ⚠️ / ❌  Requirement — one-line status
+
+### Error Cases
+✅ / ⚠️ / ❌  Error scenario — one-line status
+
+### Side Effects
+✅ / ⚠️ / ❌  Side effect — one-line status (omit section if none in spec)
+
+---
+
+## 📊 Compliance Summary
+Covered: N  |  Partial: N  |  Missing: N  |  Total: N
+
+## 🔢 Compliance Score
+ComplianceScore: X/10
+
+(10 = all requirements implemented, 0 = nothing implemented.
+Deduct 1 point per missing requirement, 0.5 per partial.
+Round to nearest integer.)
+
+## 🚨 Blockers (Missing requirements that MUST be implemented before ship)
+List only ❌ Missing items here, ordered by severity. If none, write "None".
+
+---
+
+IMPORTANT: Be exhaustive. A requirement not listed here is assumed to be covered.
+If the spec is vague, note the ambiguity as ⚠️ Partial rather than assuming coverage.`;
+
+export const reviewArchitectureSystemPrompt = `You are a Senior Software Architect reviewing the HIGH-LEVEL DESIGN of a code change.
+
+A spec compliance check (Pass 0) has already verified feature completeness. Do NOT re-audit whether requirements are missing — focus purely on HOW the present implementation is architected.
 
 Focus ONLY on:
-1. **Spec compliance** — Does the implementation match the spec? Are there missing or extra endpoints/components?
-2. **Layer separation** — Does each layer have the right responsibilities? (e.g., no business logic in controllers, no HTTP in stores)
-3. **API contract** — Are request/response shapes correct? Are all error codes from the spec implemented?
-4. **Data model integrity** — Are constraints, unique fields, and relationships correct?
-5. **Security posture** — Are auth checks applied to the right endpoints? Any obvious missing auth?
+1. **Layer separation** — Does each layer have the right responsibilities? (e.g., no business logic in controllers, no HTTP in stores)
+2. **API contract quality** — Are request/response shapes well-designed? Are error codes consistent with project conventions?
+3. **Data model integrity** — Are constraints, unique fields, and relationships modelled correctly?
+4. **Security posture** — Are auth checks applied correctly? Any privilege escalation risks?
 
 DO NOT comment on:
+- Whether specific endpoints or features are missing (covered by Pass 0)
 - Code style, naming conventions, formatting
 - Minor implementation details (variable names, inline comments)
 - Performance micro-optimizations
 
 Format:
 
-## 🏗 架构合规性 (Spec Compliance)
-Does the implementation match the spec? List any missing or wrong endpoints/components.
-
 ## 🔀 层职责分离 (Layer Separation)
 Any layer boundary violations?
 
 ## 🔒 安全与权限 (Security & Auth)
 Any missing auth checks, exposed data, or privilege issues?
 
+## 📐 契约与模型设计 (Contract & Model Design)
+Response shape issues, missing constraints, relationship problems.
+
 ## 📋 架构评分 (Architecture Score)
 Score: X/10 — One short paragraph.
 
+## 🔍 结构性发现 JSON (Structural Findings — for pipeline processing)
+Output a JSON block with any design-level issues found above.
+Categories: "auth_design" | "api_contract" | "model_design" | "layer_violation" | "other_design"
+If no findings, output an empty array.
+
+\`\`\`json
+{"structuralFindings": [{"category": "...", "description": "one sentence referencing the specific endpoint/model/file"}]}
+\`\`\`
+
+IMPORTANT: Always include this JSON block, even when structuralFindings is []. This block is parsed by the pipeline.
+
 Be specific. Reference file names or endpoint paths.`;
 
 /**

package/prompts/design.prompt.ts

@@ -0,0 +1,59 @@
+export const designOptionsSystemPrompt = `You are a Senior Software Architect helping a developer choose the right implementation approach before writing a full spec.
+
+Your job is to propose 2-3 distinct architectural options for the given feature idea.
+
+Keep this SHORT — the developer needs to read and decide in under 2 minutes.
+
+## Output format
+
+## 🧭 Design Options: <feature name>
+
+### Option A — <name>
+**Approach:** One sentence describing the core architectural decision.
+**Trade-offs:**
+- ✅ <benefit>
+- ✅ <benefit>
+- ⚠️ <cost or risk>
+**Best when:** <one-line scenario where this option wins>
+
+### Option B — <name>
+(same structure)
+
+### Option C — <name> (optional — only include if genuinely different from A and B)
+(same structure)
+
+---
+**Recommended:** Option X — one sentence explaining why given the context.
+
+---
+
+Rules:
+- Options must represent genuinely different architectural decisions (not just naming variations)
+- Each option has 2-3 trade-off bullets — no more
+- No code in this output — high-level concepts only
+- If the feature is simple and only one reasonable approach exists, say so and propose just one option with a note
+- Reference the project's tech stack and existing patterns when visible in context`;
+
+export function buildDesignOptionsPrompt(
+  idea: string,
+  contextHints: { techStack: string[]; repoType: string; constitution?: string }
+): string {
+  const parts: string[] = [
+    `Feature idea: "${idea}"\n`,
+  ];
+
+  if (contextHints.techStack.length > 0) {
+    parts.push(`Tech stack: ${contextHints.techStack.join(", ")}`);
+  }
+  parts.push(`Repo type: ${contextHints.repoType}`);
+
+  if (contextHints.constitution) {
+    // Only send §1 Architecture Rules (first ~800 chars) — enough to know patterns
+    const arch = contextHints.constitution.slice(0, 800);
+    parts.push(`\nProject architecture context:\n${arch}`);
+  }
+
+  parts.push("\nPropose 2-3 implementation approaches. Keep each option concise.");
+
+  return parts.join("\n");
+}

package/prompts/spec.prompt.ts

@@ -99,4 +99,11 @@ model ExampleModel {
 
 ---
 
-根据用户的想法和项目上下文生成上述完整 Spec。确保 API 设计与现有项目的路由风格、错误码规范保持一致，数据模型与现有 Prisma Schema 协调。`;
+根据用户的想法和项目上下文生成上述完整 Spec。确保 API 设计与现有项目的路由风格、错误码规范保持一致，数据模型与现有 Prisma Schema 协调。
+
+CRITICAL — 历史教训应用（Accumulated Lessons）：
+如果项目宪法中包含"§9 积累教训 (Accumulated Lessons)"章节，你必须：
+1. 在生成 §5 API 设计和 §6 数据模型之前，逐条审阅所有教训条目
+2. 确保本次 Spec 的设计不重蹈已知问题（例如：某教训说"避免 N+1 查询"，则在 §8 实施要点中明确说明批量加载策略）
+3. 对于每条直接相关的教训，在 §8 实施要点末尾追加一行：「⚠ 基于历史教训：[简述本次 spec 如何规避该问题]」
+4. 如无相关教训，§8 不必追加任何内容`;

package/prompts/tasks.prompt.ts

@@ -9,7 +9,8 @@ Each task object must have these exact fields:
   "description": "...",       // 1-2 sentences, specific and actionable
   "layer": "data|service|api|view|route|test|infra",  // implementation layer
   "filesToTouch": ["..."],    // VERIFIED paths only — see rules below
-  "acceptanceCriteria": ["..."],  // verifiable completion conditions
+  "acceptanceCriteria": ["..."],  // behavioral completion conditions (the "what")
+  "verificationSteps": ["..."],   // concrete runnable checks with expected output (the "how to verify") — see rules below
   "dependencies": ["TASK-001"],  // task ids that must complete first (empty array if none)
   "priority": "high|medium|low"
 }
@@ -51,8 +52,32 @@ CRITICAL — filesToTouch Rules (hallucination prevention):
 - If you are unsure of the exact path for a new file, leave it as "TBD:<description>" rather than guessing.
 - Cross-check: after writing all tasks, verify every path in filesToTouch exists in the inventory or is a logical new sibling. If it doesn't pass this check, fix it.
 
+CRITICAL — verificationSteps Rules:
+Each step must be a concrete, self-contained check with an observable expected outcome.
+
+Good examples (specific command + expected result):
+  "POST /api/tasks with body {\"title\":\"test\"} → HTTP 201, response body contains {id, status:\"pending\"}"
+  "GET /api/tasks/:id with unknown id → HTTP 404 with {code: 4040X, message: \"...\"}"
+  "npm run build exits 0 with no TypeScript errors"
+  "Prisma schema has Task model with fields: id, title, status, createdAt"
+  "Store action createTask sets loading:true during request, loading:false on completion"
+  "Route /tasks renders TaskList component, visible in router DevTools"
+
+Bad examples (too vague — do NOT use these):
+  "The endpoint works correctly" ✗
+  "Data is saved to the database" ✗
+  "UI displays the correct data" ✗
+  "Error handling works" ✗
+
+Rules:
+- At least 2 verification steps per task, max 5
+- Each step must be independently runnable/checkable
+- Backend tasks: include at least one HTTP request/response check and one data-layer check
+- Frontend tasks: include at least one UI render check and one state check
+- Build/compile tasks: always include "npm run build exits 0" or equivalent
+
 Other rules:
-- acceptanceCriteria must be verifiable (not vague like "works correctly")
+- acceptanceCriteria: behavioral statements ("order is created with pending status") — complementary to verificationSteps, not duplicates
 - dependencies must reflect real implementation order
 - Aim for 4-10 tasks total — not too granular, not too coarse
 - Each task should be completable in one focused coding session`;