ultra-builder-pro-cli 0.5.0

package/commands/ultra-plan.md

@@ -0,0 +1,49 @@
+---
+description: Generate task breakdown from complete specs — walking-skeleton first, vertical slices, via MCP task.create
+argument-hint: [scope]
+allowed-tools: Read, Write, Edit, Bash(mkdir .ultra/*), Grep, Glob, AskUserQuestion
+model: opus
+workflow-ref: "@skills/ultra-plan/SKILL.md"
+mcp_tools_required:
+  - task.create
+cli_fallback: "task create"
+---
+
+# /ultra-plan
+
+## 目标
+
+把 `/ultra-research` 验证过的完整 spec 转成可执行的任务计划：先 Walking
+Skeleton 贯穿所有层，再切 vertical slices，每 3-4 个 feature task 插一个
+Integration Checkpoint。任务写入 state.db（MCP `task.create`），projector
+自动生成 `.ultra/tasks/tasks.json` + contexts/*.md frontmatter。
+
+## 参数
+
+| 位 | 含义 | 缺省 |
+|----|------|------|
+| `$1` | scope 模式（EXPAND / SELECTIVE / HOLD / REDUCE） | 询问用户；默认 SELECTIVE |
+
+## Workflow
+
+完整 8 步流程见 `@skills/ultra-plan/SKILL.md`。
+
+**命令入口做的事**：
+1. 探测 spec 完整度 — 未填充则 block 并转 `/ultra-research`
+2. 使用 Host 原生提问界面交互选 scope 模式
+3. 驱动 skill 跑生成 → 依赖分析 → `task.create` 循环 → 写 context-md 正文
+4. 跑 7 项 verification（requirement coverage / 无环 / trace_to / 复杂度等）
+5. 输出 report + 下一步
+
+## 用法
+
+```bash
+/ultra-plan                 # 交互模式；默认 SELECTIVE
+/ultra-plan EXPAND          # 直接进入"激进扩张"模式
+/ultra-plan REDUCE          # MVP 最小化模式
+```
+
+## 下一步
+
+所有 CRITICAL check 过了 → `/clear` 然后 `/ultra-dev` 开始 TDD。
+单个 task 完成后 `/ultra-status` 看进度。

package/commands/ultra-research.md

@@ -0,0 +1,59 @@
+---
+description: Think-Driven Interactive Discovery — 17-step research with per-step web search and spec-file output
+argument-hint: [topic]
+allowed-tools: Task, Read, Write, WebSearch, WebFetch, Grep, Glob, AskUserQuestion
+model: opus
+workflow-ref: "@skills/ultra-research/SKILL.md"
+---
+
+# Ultra Research v2
+
+**Step-file architecture**: Each research step is a self-contained instruction file loaded just-in-time for maximum LLM attention density.
+
+## How This Works
+
+1. Read the main skill file: `skills/ultra-research/SKILL.md`
+2. Follow the activation sequence (pre-checks → project type detection → step routing)
+3. For each step: Read `skills/ultra-research/steps/step-{NN}-{name}.md` and follow ALL instructions
+4. Each step writes output immediately to spec files, then presents [C] Continue gate
+5. Only proceed to next step after user confirms [C]
+
+## Step Sequence
+
+| Step | File | Focus |
+|------|------|-------|
+| **R0: Product Discovery** | | |
+| 00 | `step-00-problem-validation.md` | Validate the problem is real |
+| 01 | `step-01-opportunity-discovery.md` | Map opportunity space (OST) |
+| 02 | `step-02-market-assessment.md` | TAM/SAM/SOM sizing |
+| 03 | `step-03-competitive-landscape.md` | Competitor analysis |
+| 04 | `step-04-product-strategy.md` | Vision, segments, trade-offs |
+| 05 | `step-05-assumptions-validation.md` | Risk assumptions + experiments |
+| **R1: User & Scenario** | | |
+| 10 | `step-10-user-personas.md` | 2-3 personas |
+| 11 | `step-11-user-scenarios.md` | 3-5 user scenarios |
+| **R2: Feature Definition** | | |
+| 20 | `step-20-user-stories.md` | Stories + acceptance criteria |
+| 21 | `step-21-features-scope.md` | MVP scope + exclusions |
+| 22 | `step-22-success-metrics.md` | KPIs + targets |
+| **R3: Architecture** | | |
+| 30 | `step-30-architecture-context.md` | Quality goals, constraints |
+| 31 | `step-31-solution-strategy.md` | Tech stack decisions |
+| 32 | `step-32-building-blocks.md` | Modules + runtime scenarios |
+| **R4: Quality & Deploy** | | |
+| 40 | `step-40-deployment.md` | Infrastructure + CI/CD |
+| 41 | `step-41-quality-risks.md` | Quality scenarios + risks |
+| **Synthesis** | | |
+| 99 | `step-99-synthesis.md` | Distillate + validation |
+
+## Critical Rules
+
+- **Read SKILL.md first** — it has activation logic and project type detection
+- **One step at a time** — never load multiple step files simultaneously
+- **Write immediately** — every step writes to spec file before presenting to user
+- **Web search mandatory** — factual claims need sources, no exceptions
+- **User gate** — halt at [C] Continue, do not auto-proceed
+
+## Begin
+
+Read `skills/ultra-research/SKILL.md` now and follow the activation sequence.

package/commands/ultra-status.md

@@ -0,0 +1,46 @@
+---
+description: Real-time project status — progress + risks + workflow routing, via MCP task.list
+argument-hint: "[task-id]"
+allowed-tools: Read, Bash(git status), Bash(git log *), Grep, Glob, Task
+model: opus
+workflow-ref: "@skills/ultra-status/SKILL.md"
+mcp_tools_required:
+  - task.list
+  - task.get
+cli_fallback: "task list"
+---
+
+# /ultra-status
+
+## 目标
+
+一次调用拿整个项目近况：任务进度（来自 state.db `task.list`）+ 测试状态（`test-report.json`）+
+发布状态（`delivery-report.json`）+ 风险检测 + 下一步命令路由。只读。
+
+## 参数
+
+| 位 | 含义 | 缺省 |
+|----|------|------|
+| `$1` | 单 task id（只看这个 task） | 不填 → 全局报告 |
+
+## Workflow
+
+完整 5 阶段见 `@skills/ultra-status/SKILL.md`（validation → load → progress → risk → routing）。
+
+**命令入口做的事**：
+1. 环境检查（state.db 可达 + 有 task）
+2. `task.list` 拿全量；读 test-report / delivery-report
+3. 算进度 + 风险（blocked / stalled / overdue / complexity spike / test stale）
+4. 按当前 artifact 组合路由到下一个命令（/ultra-init → /ultra-research → /ultra-plan → /ultra-dev → /ultra-test → /ultra-deliver）
+
+## 用法
+
+```bash
+/ultra-status            # 项目全局报告
+/ultra-status 3          # 只看 task 3
+```
+
+## 下一步
+
+看输出的 `▶ Next Up` 块。常见场景：有 pending → `/ultra-dev`；全绿 → `/ultra-test`；
+test passed → `/ultra-deliver`。

package/commands/ultra-test.md

@@ -0,0 +1,48 @@
+---
+description: Pre-delivery quality audit — Anti-Pattern + Coverage Gap + Wiring + E2E + Perf + Security
+argument-hint: [scope]
+allowed-tools: Bash, Read, Write, Edit, Task, Grep, Glob, AskUserQuestion
+model: opus
+workflow-ref: "@skills/ultra-test/SKILL.md"
+mcp_tools_required:
+  - task.list
+cli_fallback: "task list"
+---
+
+# /ultra-test
+
+## 目标
+
+`/ultra-deliver` 前的项目级质量审计：6 类 gate（Anti-Pattern / Coverage Gap /
+Wiring / E2E / Performance / Security）× auto-fix loop。**只读** state.db，
+写 `.ultra/test-report.json` 作为 `/ultra-deliver` 的准入凭证。
+
+**注意**：这不是跑单测（那是 `/ultra-dev`）。这是交付前的体检。
+
+## 参数
+
+| 位 | 含义 | 缺省 |
+|----|------|------|
+| `$1` | 审计范围（`all`/`anti-pattern`/`coverage`/`e2e`/`perf`/`security`） | `all` |
+
+## Workflow
+
+完整 8 步见 `@skills/ultra-test/SKILL.md`（pre-check → 6 gates → auto-fix → persist → report）。
+
+**命令入口做的事**：
+1. 探测项目类型 + `task.list` 确认 ≥1 completed
+2. 按 scope 跑 gates；失败进 auto-fix（最多 5 轮）
+3. 写 `.ultra/test-report.json`（`passed` + gate-level 明细 + blocking_issues）
+4. 通过 → 提示 `/ultra-deliver`
+
+## 用法
+
+```bash
+/ultra-test                # 全量审计
+/ultra-test security       # 只跑安全审计
+/ultra-test coverage       # 只找覆盖缺口
+```
+
+## 下一步
+
+`passed=true` → `/ultra-deliver`；`passed=false` → 修或跟进 `blocking_issues`。

package/commands/ultra-think.md

@@ -0,0 +1,45 @@
+---
+description: Deep analysis with adversarial reasoning — Evidence-First + Multi-Perspective + Stress-Test + Confidence-Quantified recommendation
+argument-hint: "[problem or decision to analyze]"
+allowed-tools: Read, Grep, Glob, Bash, Write, Task, WebSearch, WebFetch, AskUserQuestion, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, mcp__context7__resolve-library-id, mcp__context7__query-docs
+model: opus
+workflow-ref: "@skills/ultra-think/SKILL.md"
+cli_fallback: "direct user interaction"
+---
+
+# /ultra-think
+
+## 目标
+
+结构化深度分析复杂问题/决策/诊断。Evidence-First 标注（Fact/Inference/Speculation）+
+多视角 + 对抗压测（Steel-Man / Pre-Mortem / Sensitivity / Second-Order）→
+量化置信度的推荐 + 验证计划。
+
+## 参数
+
+<problem>
+$ARGUMENTS
+</problem>
+
+## Workflow
+
+完整 5 步见 `@skills/ultra-think/SKILL.md`（Scope → Evidence → Multi-Perspective →
+Adversarial → Synthesis）。
+
+**命令入口做的事**：
+1. 读 `$ARGUMENTS` 判定问题范围 — 模糊 → 用 Host 原生提问界面最多澄清 3 个问题
+2. 简单问题 → 直接答；复杂 → 跑完整框架
+3. 输出 Markdown 报告（Problem / Analysis / Options / Adversarial / Recommendation /
+   Verification / Next Steps）
+
+## 用法
+
+```bash
+/ultra-think "should we switch from REST to gRPC for the internal API?"
+/ultra-think "why is the deploy pipeline flaky every 3rd run?"
+```
+
+## 下一步
+
+方案进入 spec → `/ultra-research` 补证据或 `/ultra-plan` 直接排任务；
+纯诊断 → 跟着 Verification Plan 走，取证后再定。

package/docs/AGENT-CONTEXT.md

@@ -0,0 +1,143 @@
+# Ultra Builder Pro — Agent Context
+
+Current shared runtime contract for the native Claude Code, OpenCode, and Codex
+plugins. Gemini CLI remains a compatibility adapter and is not the reference
+shape for the three first-class plugins.
+
+## 1. Ownership boundary
+
+Ultra Builder Pro owns only:
+
+- ten public workflows: `learn`, `ultra-init`, `ultra-research`, `ultra-plan`,
+  `ultra-dev`, `ultra-test`, `ultra-review`, `ultra-deliver`, `ultra-status`, and
+  `ultra-think`;
+- four internal agent-only rule skills: `code-review-expert`, `security-rules`,
+  `integration-rules`, and `testing-rules`;
+- the host-specific collaboration companions and `ultra-verify`;
+- bounded review/debug agents, workflow-only hooks, MCP task state, and the
+  portable CLI/orchestrator.
+
+Browser automation, deployment helpers, skill discovery, Vercel guidance, and
+other framework skills are external packages. Adapters build exclusively from
+`adapters/_shared/runtime-assets.cjs`; adding a directory under `skills/` does
+not put it in a plugin until that allowlist classifies it.
+
+## 2. Three-layer architecture
+
+```text
+native command or skill -> MCP workflow-state operation -> CLI fallback
+                                  |
+                                  v
+                         .ultra/state.db
+```
+
+| Layer | Artifact | Contract |
+|---|---|---|
+| Skill/command | `skills/*/SKILL.md`, `commands/*.md` | Model-facing workflow and host-native entry point |
+| MCP | `mcp-server/server.cjs` | Authoritative typed operations over `.ultra/state.db` |
+| CLI | `ultra-tools`, `ubp-orchestrator` | Portable fallback, automation, and diagnostics |
+
+`.ultra/state.db` is the only durable Ultra authority for tasks, sessions,
+events, telemetry, review evidence, and circuit-breaker state. `tasks.json`,
+context Markdown, execution plans, and reports are projections or workflow
+artifacts; never treat them as a second writable authority.
+
+## 3. Live MCP and declared contracts
+
+`spec/mcp-tools.yaml` declares 30 contracts across seven families. The bundled
+server registers 21 tools:
+
+| Family | Live tools |
+|---|---|
+| `task.*` | create, update, list, get, switch_tag, delete, init_project, expand, parse_prd, dependency_topo, append_event, subscribe_events |
+| `session.*` | spawn, close, get, list, admission_check, heartbeat, subscribe_events |
+| `plan.*` | export, get |
+
+The nine declared `review.*`, `impact.*`, `skill.*`, and `ask.*` contracts are
+not advertised by the live server. A generated Codex plugin records their
+native replacements in `spec/codex-capability-map.json`; other hosts use their
+own native review agents, repository discovery, skill loader, and user
+interaction surfaces.
+
+Any new MCP contract starts in `spec/mcp-tools.yaml` with valid and invalid
+fixtures. Do not add an ad-hoc server handler first.
+
+## 4. Native host presentation
+
+| Host | Plugin form | Workflow entry | Hook form | Collaboration companions |
+|---|---|---|---|---|
+| Claude Code | `.claude-plugin/plugin.json`, native commands/skills/agents, `.mcp.json` | `/ultra-*`, `/learn` | native `hooks/hooks.json` | `codex-collab`, `gemini-collab` |
+| Codex | personal plugin with `.codex-plugin/plugin.json`, namespaced skills, TOML agents, `.mcp.json` | `$ultra-builder-pro:ultra-*`, `$ultra-builder-pro:learn` | native `hooks/hooks.json` through the Codex wire adapter | `cc-collab`, `gemini-collab` |
+| OpenCode | config bundle plus native JavaScript plugin | `/ultra-*`, `/learn` | `event`, system transform, compaction, and tool lifecycle handlers | `cc-collab`, `codex-collab`, `gemini-collab` |
+
+The current host remains primary. Collaboration skills call another runtime
+only when explicitly requested, use it as a read-only advisor, and return the
+evidence to the primary host for final verification.
+
+## 5. Hook boundary
+
+The canonical Python hook allowlist contains seven workflow-only adapters:
+
+- `health_check.py` and `workflow_context.py` on session start;
+- `active_task_context.py` before an edit;
+- `workflow_checkpoint.py` before compaction;
+- `workflow_resume.py` after compaction/resume;
+- `pre_stop_check.py` at stop;
+- `subagent_tracker.py` for bounded worker lifecycle evidence.
+
+Every hook is a no-op unless `.ultra/workflow-state.json` describes an active,
+non-terminal workflow. OpenCode expresses the same boundary in its native
+JavaScript plugin. Generic command blocking, post-edit governance, and unrelated
+user hooks are not copied into Ultra Builder Pro.
+
+## 6. Memory boundary
+
+Ultra Builder Pro has no memory MCP family, recall skill, prompt capture,
+transcript capture, observation journal, or session-summary hook. Persistent
+cross-session memory belongs to a separately installed provider such as
+cloud-mem/claude-mem.
+
+Old Ultra data is never deleted during install. The explicit migration path is:
+
+```bash
+ultra-tools legacy-memory inspect
+ultra-tools legacy-memory archive
+ultra-tools legacy-memory prune --confirm DELETE_ULTRA_LEGACY_MEMORY
+```
+
+Archive before prune; the confirmation token is intentionally required.
+
+## 7. Project state layout
+
+```text
+.ultra/
+├── state.db                 # authoritative SQLite store
+├── workflow-state.json      # active workflow/recovery checkpoint
+├── tasks/                   # projections and task contexts
+├── specs/                   # research/product/architecture artifacts
+├── sessions/                # bounded runtime artifacts
+├── reviews/                 # review evidence
+├── test-report.json
+└── delivery-report.json
+```
+
+## 8. User handbook integration
+
+General engineering doctrine remains user-owned in `CLAUDE.md` or `AGENTS.md`.
+Ultra Builder Pro contributes one managed section only. Preview or apply it with:
+
+```bash
+ubp-handbook preview --runtime codex
+ubp-handbook apply --runtime codex
+```
+
+Supported runtime names are `claude`, `codex`, and `opencode`. Apply creates a
+timestamped backup, replaces only the marked block, and can migrate the old
+Codex `## Ultra Builder Pro Runtime Contract` section without touching the next
+user section. Plugin adapters themselves do not silently overwrite handbooks.
+
+## 9. Verification
+
+Run `npm run test:all`, `python3 -m pytest hooks/tests -q`, and `npm audit`.
+Adapter tests assert the allowlisted assets, native manifests, hook boundary,
+MCP visibility, and host-specific skill rendering.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,197 @@
+# Ultra Builder Pro CLI — Architecture
+
+> Single-page entry point for reviewers and contributors. The detailed
+> roadmap and decision log live in [`docs/PLAN.zh-CN.md`](./PLAN.zh-CN.md);
+> this file freezes the architectural shape that the PLAN drives toward.
+>
+> Trace: PLAN §4, decisions D12 / D13 / D18 / D20 / D29 / D32 / D33.
+
+## 1. One sentence
+
+`ultra-builder-pro-cli` is a multi-runtime plugin suite that **distributes** the
+Ultra Builder Pro engineering loop (skills + commands + workflow hooks) as
+native Claude Code, OpenCode, and Codex plugins, with a Gemini compatibility
+adapter, and
+**runs** that loop with isolated sessions sharing one authoritative state
+store (`.ultra/state.db`).
+
+It is not an agent and it is not a memory provider. It is the workflow substrate
+the supported hosts share.
+
+## 2. Three layers
+
+```
+                       ┌──────────────────────────┐
+                       │       runtime CLI        │
+                       │  (claude / opencode /    │
+                       │   codex / gemini)        │
+                       └────────────┬─────────────┘
+                                    │
+                ┌───────────────────┼────────────────────┐
+                │                   │                    │
+                ▼                   ▼                    ▼
+        ╔══════════════╗   ╔════════════════╗   ╔══════════════╗
+        ║   skill/     ║   ║   MCP server   ║   ║ ultra-tools  ║
+        ║  (knowledge) ║   ║  (state ops)   ║   ║   (Bash      ║
+        ║              ║   ║                ║   ║    fallback) ║
+        ╚══════╤═══════╝   ╚════════╤═══════╝   ╚══════╤═══════╝
+               │                    │                  │
+               │ resolve / read     │ task.* etc.      │ same tools
+               │  (D29 read-only)   │                  │ via stdio
+               └────────────┬───────┴──────────────────┘
+                            ▼
+                  ┌─────────────────────┐
+                  │   .ultra/state.db   │
+                  │  (SQLite + WAL)     │  ← single authoritative store
+                  └──────────┬──────────┘
+                             │ projector (Phase 2.6)
+                             ▼
+              .ultra/tasks/tasks.json     (read-only view)
+              .ultra/tasks/contexts/*.md  (read-only header)
+              .ultra/activity-log.json    (optional dump)
+```
+
+| Layer        | Role                                         | Form                                                  |
+|--------------|----------------------------------------------|-------------------------------------------------------|
+| **skill**    | knowledge carrier; tells the runtime *what to do* | `skills/<name>/SKILL.md` discovered natively by all four runtimes |
+| **MCP**      | authoritative workflow-state API             | stdio MCP server exposing seven declared tool families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml); 21 tools are live and nine scheduled contracts map to host-native surfaces |
+| **CLI**      | the lowest common denominator hooks can call  | `ultra-tools <family> <verb>` — same contract, last-line JSON envelope (see [`spec/cli-protocol.md`](../spec/cli-protocol.md)) |
+
+Why three: skills give us behavior portability across runtimes; MCP gives
+us a strongly-typed contract so we can refactor implementations without
+rewriting prompts; CLI gives us a Python-hook-callable fallback when a
+runtime's MCP transport is unavailable. None of the three could carry the
+load alone (D12).
+
+The skill layer is **read-only by design** (D29). We keep `skill.resolve`
+and `skill.manifest` to let the runtime locate a SKILL.md and parse its
+frontmatter; we deliberately removed `skill.invoke` and `skill.list`
+because skills are documentation, not RPC.
+
+## 3. Authoritative state — `.ultra/state.db`
+
+All durable Ultra workflow state lives in one SQLite file with WAL enabled. Schema is
+fixed in [`spec/schemas/state-db.sql`](../spec/schemas/state-db.sql) and
+covers eight tables:
+
+| Table              | Holds                                             | Phase |
+|--------------------|---------------------------------------------------|-------|
+| `tasks`            | task rows — id, status, deps, files_modified, …   | 2     |
+| `events`           | append-only event stream; `id` is subscription cursor (D31) | 2 |
+| `sessions`         | execution sessions, **including lease + heartbeat fields** (D32) | 4.5 |
+| `schema_version`   | applied schema version (cross-version misread guard, D30) | 2 |
+| `migration_history`| one row per migration attempt (audit trail)        | 2     |
+| `telemetry`        | per-session token / cost / tool-call counters     | 6     |
+| `specs_refs`       | spec change tracking → staleness propagation       | 5     |
+| `circuit_breaker`  | bounded retry and halt state for failed tasks       | 5     |
+
+Two rules make this work:
+
+1. **No double source (D32).** lease/heartbeat live only in `sessions`,
+   not in a `lease.json` file. Activity log lives only in `events`, not
+   in JSON files. `tasks.json` and the status header in
+   `contexts/task-*.md` are **projections** generated by the projector;
+   manual edits are overwritten on the next state.db change.
+
+2. **Single writer for mutable tables, multi-writer for `events`.**
+   `.ultra/state.db` opens in WAL with `busy_timeout=5000`. The MCP
+   server holds the single writer connection for `tasks`, `sessions`,
+   `telemetry`, `specs_refs`, and `migration_history`; the CLI calls
+   those tools over stdio rather than opening its own writer. The
+   `events` table is append-only and explicitly multi-writer — CLI and
+   orchestrator processes append directly to it under the same WAL +
+   `busy_timeout` discipline, since independent INSERTs do not conflict.
+   In `spec/mcp-tools.yaml` this split is captured by `writer_role: mcp`
+   (must go through the MCP server) versus `writer_role: any` (any
+   process may execute). Full policy lives in
+   `docs/STATE-DB-ACCESS-POLICY.md` (Phase 2.2 / R25).
+
+Subscribers always pull `events.id > since_id` rather than `max(ts)`,
+because two events may share the same millisecond timestamp (D31).
+
+### Memory ownership is outside Ultra Builder Pro
+
+Ultra Builder Pro does not retain prompts, transcripts, tool observations,
+session summaries, or cross-session memory. It ships no `memory.*` MCP family,
+no recall skill, and no memory-capture hook. A separately installed provider
+such as cloud-mem/claude-mem owns persistent memory and its own lifecycle. The
+only related migration surface is the explicit `ultra-tools legacy-memory`
+archive/prune command for data created by older releases.
+
+## 4. Sessions — the execution unit
+
+A **session** is the standard unit of execution across all four runtimes
+(D20). One session =
+
+- a fresh OS process for the runtime,
+- an isolated `git worktree`,
+- a lease + heartbeat row in `sessions` (D32),
+- an `artifact_dir` under `.ultra/sessions/<sid>/` for logs and scratch.
+
+Spawning a new session for a task is gated by `session.admission_check`
+(D33). If another session already owns an active lease on the same task,
+the caller must pick one of three strategies before proceeding:
+
+- `takeover` — kill the prior process, claim the lease,
+- `resume` — attach to the existing session and continue,
+- `abandon` — give up and let the existing session finish.
+
+This admission gate is the smallest piece that prevents two agents from
+silently double-writing the same task — it is part of the v0.1 minimum
+execution layer, not deferred to Phase 5.
+
+## 5. Two timelines — rule layer vs execution layer
+
+The roadmap separates two concerns that compete for the same surface
+area (D13):
+
+```
+┌─ Rule layer (Phase 1-4.5) ────────────────────────────────┐
+│  contracts, state schema, command shells, runtime         │
+│  installers, smoke flow, execution-lite                   │
+│                                                            │
+│  v0.1 (Week 8)  = rule layer fully wired + execution-lite │
+└────────────────────────────────────────────────────────────┘
+
+┌─ Execution layer (Phase 4.5-8B) ───────────────────────────┐
+│  recovery, staleness, monitoring, intelligence, planning   │
+│  automation, parallel worktree dispatch                    │
+│                                                            │
+│  v0.2 (Week 11) = recovery + monitoring + full conformance │
+│  v0.3 (Week 16) = PRD → execution-plan → parallel factory  │
+│  v1.0 (Week 17-18) = npm + Homebrew + pip distribution     │
+└────────────────────────────────────────────────────────────┘
+```
+
+The rule layer is shipped before the execution layer because users get
+value from "skills + tasks survive across sessions" long before they get
+value from "ten agents in parallel." Each milestone is independently
+shippable; downstream slip never blocks an earlier release.
+
+## 6. Where to look next
+
+| Question                                           | File                                                |
+|----------------------------------------------------|-----------------------------------------------------|
+| What does each MCP tool accept and return?         | [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml)     |
+| How do CLI subcommands map to MCP tools?           | [`spec/cli-protocol.md`](../spec/cli-protocol.md)   |
+| Exact SQLite schema?                               | [`spec/schemas/state-db.sql`](../spec/schemas/state-db.sql) |
+| What does a tasks.json look like after projection? | [`spec/fixtures/valid/tasks.v4.5.json`](../spec/fixtures/valid/tasks.v4.5.json) |
+| Phase-by-phase work breakdown + decision log       | [`docs/PLAN.zh-CN.md`](./PLAN.zh-CN.md)             |
+
+## 7. Verifying the architecture
+
+Every contract on this page is enforced by `npm run test:spec`:
+
+- `validate-mcp-tools.cjs` — meta-schema for the tool manifest, plus
+  per-tool sample input/output fixtures.
+- `validate-state-db.cjs` — schema applies cleanly to a fresh in-memory
+  SQLite, valid fixtures insert, invalid fixtures are rejected by
+  CHECK / NOT NULL / FK constraints.
+- `validate-json-schemas.cjs` — projection schemas for `tasks.json` and
+  `contexts/task-*.md`.
+- `validate-skills.cjs` — every existing skill passes the manifest
+  contract; failures are recorded in `spec/migration-notes.md`.
+- `check-cli-mapping.cjs` — every MCP tool has exactly one CLI
+  subcommand and the doc table never drifts from the YAML manifest.
+
+If any of these fails, the architecture is no longer the architecture.