docs(revamp): reshape Orchestration into Phase 7

plans/backend/revamp/07-orchestration.md

@@ -1,95 +1,123 @@
-# Domain ⑥ — Orchestration / Conversation (the CI-expert subagent) (CI pivot revamp · WIP)
+# Phase 7 — Orchestration / Conversation (the CI-expert subagent)
 
-> **WIP design doc.** Part of the Phase 4 → end revamp. This is the **human-facing brain** that turns
+> **Phase 7** of the CI-pivot revamp — the **human-facing brain** that turns "natural language is the only
-> Decision-0 ("natural language is the only surface", `02-access.md`) into a real deliverable.
+> surface" (`04b`, Decision 0) into a real deliverable. **Build last** — it sits atop `04`–`06`.
+> **Depends on** all prior phases: `04a` verbs, `04b` doors + `deliverable_wait`, `05a`/`05b` Tracker +
+> Timeline, `06` refresh triggers.
 > **Scope guardrail:** the multi-agent chat **runtime** (deepagents, subagent dispatch, streaming,
 > citation middleware, `deliverable_wait`) is SHIPPED/FIXED. What's **net-new here** is one builtin
 > subagent + its tools + its prompt. We *plug into* the runtime; we don't rebuild it.
 
-## Why this is a first-class deliverable
+## Objective
 
-The intent router + verb-composition + Tracker-crafting are where "user-friendly" is won or lost. Treating
+Ship the **`intelligence_agent`** — a net-new builtin CI-expert subagent — so users get the whole product
-the agent prompt/tooling as plumbing would make the product feel rigid. So the orchestration layer gets
+through plain conversation: intent routing (one-shot vs standing concern), verb composition, Tracker
-designed, not assumed.
+crafting, and decision-grounded answering. The intent router + verb-composition + Tracker-crafting are
+where "user-friendly" is won or lost, so the orchestration layer is **designed, not assumed**.
 
-## The pattern we reuse (verbatim)
+## Current state (cited)
 
-Builtin subagents live at `subagents/builtins/<name>/`:
+- **Builtin subagent pattern** — `subagents/builtins/<name>/`: `agent.py` (`build_subagent(...)` →
-```
+  `pack_subagent(name, description, system_prompt, tools, ruleset, …)`), `tools/index.py`
-agent.py            build_subagent(...) → pack_subagent(name, description, system_prompt, tools, ruleset, …)
+  (`NAME · RULESET · load_tools(dependencies)`), `description.md` (router one-liner), `system_prompt.md`
-tools/index.py      NAME · RULESET · load_tools(dependencies)
+  (the playbook), optional middleware (e.g. `citation_state`). Peers: `research`, `deliverables`.
-description.md      one-liner the router uses to delegate
+- **Tool shape** — `research/tools/scrape_webpage.py` already demonstrates **tool = capability executor +
-system_prompt.md    the playbook
+  access door + 03c billing**: calls `WebCrawlerConnector.crawl_url`, bills via the turn accumulator
-(middleware)        e.g. citation_state
+  (`get_current_accumulator()` + `WebCrawlCreditService`), returns a typed dict. CI tools follow this exactly.
-```
+- **Slow-job path** — `deliverable_wait` poll-until-terminal + the podcast-style live card (`04b`).
-`research/tools/scrape_webpage.py` already shows the **tool = capability executor + access door + 03c
-billing** shape: it calls `WebCrawlerConnector.crawl_url`, bills via the turn accumulator
-(`get_current_accumulator()` + `WebCrawlCreditService`), returns a typed dict. Our capability/CI tools
-follow this exactly.
 
-## What's new — the `intelligence_agent` subagent (CI expert)
+## Target design
 
-A new builtin `subagents/builtins/intelligence_agent/` (the competitive-intelligence specialist),
+### The `intelligence_agent` subagent (CI expert)
-peer to `research`/`deliverables`. The **main agent delegates** to it whenever the request is
-CI-flavored (research a competitor, watch something, analyze a place's reviews); `description.md` is
-what makes that routing happen.
 
-It owns the **CI playbook** in `system_prompt.md`:
+A new builtin `subagents/builtins/intelligence_agent/` (the competitive-intelligence specialist), peer to
+`research`/`deliverables`. The **main agent delegates** to it whenever the request is CI-flavored (research
+a competitor, watch something, analyze a place's reviews); `description.md` is what makes that routing
+happen. It owns the **CI playbook** in `system_prompt.md`:
 
-1. **Intent routing (A vs B)** — the Decision-0 rule, in-prompt: one-shot ("compare/find/what is")
+1. **Intent routing (A vs B)** — the Decision-0 rule, in-prompt: one-shot ("compare/find/what is") → call
-   → call verbs & answer; standing concern ("watch/track/notify when/weekly") → run the crafting flow;
+   verbs & answer; standing concern ("watch/track/notify when/weekly") → run the crafting flow; ambiguous →
-   ambiguous → ask the single clarifying question.
+   ask the single clarifying question.
 2. **Verb composition** — the chains: `web.discover → web.scrape`, `maps.search → maps.place →
    maps.reviews`; infer URLs/queries/locations from context so the user never supplies them by hand.
-3. **Tracker crafting** (the "crafting" you flagged) — the conversational schema-design flow from `03`:
+3. **Tracker crafting** — the conversational schema-design flow from `05b`: sample-fetch → propose
-   sample-fetch → propose `field_schema` + materiality + identity → user validates & locks → versioned.
+   `field_schema` + materiality + identity → user validates & locks → versioned.
-4. **Decision-grounded answering** — read the Timeline (`04`) to answer "what changed / is X pulling
+4. **Decision-grounded answering** — read the Timeline (`05a`) to answer "what changed / is X pulling
    ahead?" from stored deltas, not by re-deriving from chat history.
 
-## The toolset (what `load_tools` returns)
+### The toolset (what `load_tools` returns)
 
 | Tool | Wraps | Mode | Billing |
 |------|-------|------|---------|
-| capability verbs (`web.scrape`, `web.discover`, `maps.search`, `maps.place`, `maps.reviews`) | Domain ① executors | inline-or-job (slow → `deliverable_wait`) | `03c` turn accumulator (as `scrape_webpage` already does) |
+| capability verbs (`web.scrape`, `web.discover`, `maps.search`, `maps.place`, `maps.reviews`) | `04a` executors | inline-or-job (slow → `deliverable_wait`) | `03c` turn accumulator (as `scrape_webpage` already does) |
-| `craft_tracker(decision, binding)` | `03` schema-design agent | inline (does the sample-fetch + proposes) | sample crawl billed |
+| `craft_tracker(decision, binding)` | `05b` schema-design agent | inline (sample-fetch + proposes) | sample crawl billed |
-| `lock_tracker(draft)` / `update_tracker` | `03` Tracker persistence | inline | — |
+| `lock_tracker(draft)` / `update_tracker` | `05b` Tracker persistence | inline | — |
-| `refresh_tracker(tracker_id)` | `03` `refresh(tracker)` | job → `deliverable_wait` | per capability call |
+| `refresh_tracker(tracker_id)` | `05b` `refresh(tracker)` (via `06`) | job → `deliverable_wait` | per capability call |
-| `query_timeline(tracker_id, …)` | `04` read API | inline | — |
+| `query_timeline(tracker_id, …)` | `05a` read API | inline | — |
-| `list_trackers()` | `04`/`03` read | inline | — |
+| `list_trackers()` | `05a`/`05b` read | inline | — |
 
-- **Capability verbs are a shared tool module** (generated from the Domain ① registry) — `research`
+- **Capability verbs are a shared tool module** (generated from the `04a` registry) — `research` can load
-  can load the same ones; the `intelligence_agent` additionally loads the Tracker/Timeline tools + the CI prompt.
+  the same ones; the `intelligence_agent` additionally loads the Tracker/Timeline tools + the CI prompt.
   (`scrape_webpage` is the seed; generalize it into the registry-backed set.)
 - **Slow verbs** (`maps.search`, multi-URL `web.scrape`, `refresh_tracker`) dispatch a job and use the
-  existing `deliverable_wait` poll-until-terminal + live-card path (`02-access.md`).
+  existing `deliverable_wait` poll-until-terminal + live-card path (`04b`).
 
-## Boundaries
+### Boundaries
 
-- **Orchestration ≠ Intelligence.** The `intelligence_agent` *drives* `03`/`04` via tools; the hot loop,
+- **Orchestration ≠ Intelligence.** The `intelligence_agent` *drives* `05a`/`05b` via tools; the hot loop,
-  materiality, and Timeline writes live in `03`/`04`, callable headless (so REST/MCP and Triggers reach
+  materiality, and Timeline writes live in `05a`/`05b`, callable headless (so REST/MCP and Triggers reach the
-  the same logic with no agent in the loop).
+  same logic with no agent in the loop).
 - **Humans get the agent; machines get raw verbs.** REST/MCP callers (devs/external agents) skip this
-  subagent entirely and call Domain ① verbs directly — they *want* explicitness.
+  subagent entirely and call `04a` verbs directly — they *want* explicitness.
 
-## MVP cut vs north star
+## Work items
 
-- **MVP:** the `intelligence_agent` subagent + description/prompt · capability verb tools (registry-backed) ·
+1. **Subagent scaffold**: `subagents/builtins/intelligence_agent/` with `agent.py` / `tools/index.py` /
-  `craft_tracker`/`lock_tracker`/`refresh_tracker`/`query_timeline`/`list_trackers` · intent routing in-prompt.
+   `description.md` / `system_prompt.md`, packed via `pack_subagent`.
-- **North star (deferred):** richer multi-step CI playbooks (auto competitor discovery → multi-Tracker
+2. **CI playbook prompt**: intent routing (A/B + one clarifying question), verb chains, crafting flow,
-  setup), proactive "you should watch this" suggestions, cross-Tracker synthesis.
+   decision-grounded answering.
+3. **Shared verb tool module**: registry-backed (`04a`) capability tools, reusable by `research` too.
+4. **Tracker/Timeline tools**: `craft_tracker` / `lock_tracker` / `update_tracker` / `refresh_tracker` /
+   `query_timeline` / `list_trackers`.
+5. **Slow-verb wiring**: route job-mode tools through `deliverable_wait` + the live card.
+6. **Router registration**: `description.md` so the main agent delegates CI-flavored requests here.
 
-## Locked decisions
+## Tests
 
-1. CI orchestration is a **net-new builtin subagent** (`intelligence_agent`) on the existing
+- **Delegation**: a CI-flavored request routes to `intelligence_agent`; a non-CI request does not.
-   runtime — not a runtime rebuild.
+- **One-shot**: "compare X and Y" composes verbs and answers in plain language, persisting nothing.
+- **Standing concern**: "watch X weekly" runs the crafting flow → lock → (refresh via `06`).
+- **Crafting**: `craft_tracker` does a real sample-fetch and proposes a schema; `lock_tracker` versions it.
+- **Answering**: `query_timeline` answers "what changed?" from stored deltas, not chat history.
+- **Slow verb**: a multi-URL scrape surfaces a live card and returns terminal results.
+
+## Risks / trade-offs
+
+- **Prompt quality is the product**: intent-router/composition quality is a first-class deliverable, not
+  plumbing — budget iteration on the prompt.
+- **One-shot ownership**: whether `research` keeps generic scraping or the `intelligence_agent` owns all
+  CI-flavored calls (lean: shared verb tools, CI agent owns the *playbook*).
+- **Pre-frontend lock UX**: "review & lock" must render in pure chat for MVP (ties to `05b`'s open Q).
+
+## Resolved decisions
+
+1. CI orchestration is a **net-new builtin subagent** (`intelligence_agent`) on the existing runtime — not
+   a runtime rebuild.
 2. Tools follow the `scrape_webpage` shape: capability executor + access door + `03c` billing.
-3. Capability verbs are a **shared, registry-generated** tool module; the `intelligence_agent` adds Tracker/Timeline
+3. Capability verbs are a **shared, registry-generated** tool module; the `intelligence_agent` adds
-   tools + the CI prompt.
+   Tracker/Timeline tools + the CI prompt.
-4. Intent routing (A vs B) lives **in the subagent prompt**; the headless logic stays in `03`/`04`.
+4. Intent routing (A vs B) lives **in the subagent prompt**; the headless logic stays in `05a`/`05b`.
 5. Slow verbs reuse `deliverable_wait`; nothing new for chat-async.
 
+## Out of scope (hand-offs)
+
+- **The verbs, doors, engine, state, and triggers** → `04`/`05`/`06` (this phase only *orchestrates* them).
+- **Richer multi-step CI playbooks** (auto competitor discovery → multi-Tracker setup), proactive "you
+  should watch this" suggestions, cross-Tracker synthesis → north star (deferred).
+- **Frontend CI surfaces** (cards, dashboards) → frontend umbrella.
+
 ## Open questions (carry forward)
 
-- Does CI one-shot scraping stay in `research`, or does the `intelligence_agent` own all CI-flavored calls (lean:
+- Does CI one-shot scraping stay in `research`, or does the `intelligence_agent` own all CI-flavored calls
-  shared verb tools, `intelligence_agent` owns the *CI playbook*).
+  (lean: shared verb tools, `intelligence_agent` owns the *CI playbook*).
-- How `craft_tracker`'s "review & lock" renders pre-frontend (pure-chat confirmation — ties to `03`'s open Q).
+- How `craft_tracker`'s "review & lock" renders pre-frontend (pure-chat confirmation — ties to `05b`'s open Q).