@blxzer/cursor-trellis 0.3.4 → 0.3.5

package/dist/templates/common/bundled-skills/smart-search-cli/references/cli-contract.md

@@ -21,14 +21,13 @@
 - `smart-search fetch URL [--format json|markdown|content] [--output PATH]`
 - `smart-search exa-search QUERY [--num-results N] [--search-type neural|keyword|auto] [--include-text] [--include-highlights] [--start-published-date YYYY-MM-DD] [--include-domains DOMAIN...] [--exclude-domains DOMAIN...] [--category NAME] [--format json|markdown|content] [--output PATH]`
 - `smart-search exa-similar URL [--num-results N] [--format json|markdown|content] [--output PATH]`
-- `smart-search zhipu-search QUERY [--count N] [--search-engine NAME] [--search-recency-filter VALUE] [--search-domain-filter DOMAIN] [--content-size medium|high] [--format json|markdown|content] [--output PATH]` — **DEPRECATED**: emits a stderr warning on every invocation; the subcommand, the `research_discovery` zhipu branch, and `providers/zhipu.py` will be removed on the schedule in README § "Deprecation notices".
 - `smart-search context7-library NAME [QUERY] [--format json|markdown|content] [--output PATH]`
 - `smart-search context7-docs LIBRARY_ID QUERY [--format json|markdown|content] [--output PATH]`
 - `smart-search research QUERY [--budget quick|standard|deep] [--locale-scope cn|en|both] [--evidence-dir PATH] [--fallback auto|off] [--dry-run] [--progress] [--format json|markdown|content] [--output PATH]`
 - `smart-search map URL [--instructions TEXT] [--max-depth N] [--max-breadth N] [--limit N] [--timeout SECONDS] [--format json|markdown|content] [--output PATH]`
 - `smart-search doctor [--format json|markdown|content] [--output PATH]`
 - `smart-search diagnose openai-compatible [--timeout SECONDS] [--format json|markdown] [--output PATH]`
-- `smart-search setup [--lang zh|en] [--advanced] [--non-interactive] [--openai-compatible-api-url URL] [--openai-compatible-api-key KEY] [--openai-compatible-model ID] [--openai-compatible-stream true|false] [--validation-level fast|balanced|strict] [--fallback-mode auto|off] [--minimum-profile standard|off] [--exa-key KEY] [--context7-key KEY] [--zhipu-key KEY] [--zhipu-api-url URL] [--zhipu-search-engine ENGINE] [--jina-key KEY] [--jina-reader-api-url URL] [--jina-respond-with MODE] [--jina-timeout SECONDS] [--tavily-api-url URL] [--tavily-key KEY] [--firecrawl-api-url URL] [--firecrawl-key KEY] [--format json|markdown|content] [--output PATH]`
+- `smart-search setup [--lang zh|en] [--advanced] [--non-interactive] [--openai-compatible-api-url URL] [--openai-compatible-api-key KEY] [--openai-compatible-model ID] [--openai-compatible-stream true|false] [--validation-level fast|balanced|strict] [--fallback-mode auto|off] [--minimum-profile standard|off] [--exa-key KEY] [--context7-key KEY] [--jina-key KEY] [--jina-reader-api-url URL] [--jina-respond-with MODE] [--jina-timeout SECONDS] [--tavily-api-url URL] [--tavily-key KEY] [--firecrawl-api-url URL] [--firecrawl-key KEY] [--format json|markdown|content] [--output PATH]`
 - `smart-search config path [--format json|markdown|content] [--output PATH]`
 - `smart-search config list [--format json|markdown|content] [--output PATH]`
 - `smart-search config set KEY VALUE [--format json|markdown|content] [--output PATH]`
@@ -47,7 +46,6 @@ Top-level aliases must normalize to the same service behavior as their full comm
 | `map` | `m` |
 | `exa-search` | `exa`, `x` |
 | `exa-similar` | `xs` |
-| `zhipu-search` | `z`, `zp` |
 | `context7-library` | `c7`, `ctx7` |
 | `context7-docs` | `c7d`, `c7docs`, `ctx7-docs` |
 | `research` | `rs` |
@@ -71,7 +69,7 @@ Successful search output includes `ok`, `query`, `primary_api_mode`, `content`,
 
 `--format json` is the stable machine-readable contract for agents and scripts. JSON output remains parseable and uses readable non-ASCII text when the terminal encoding supports it.
 
-`--format markdown` is the human-readable report format. `doctor --format markdown` must render a detailed diagnostic report with overall status, active/default/legacy config paths, log path resolution, evidence path resolution, file-logging status, masked config values with sources, minimum profile, capability status, main-search provider checks, provider connectivity checks, model metadata, and full long error/message detail instead of falling back to raw JSON. `diagnose openai-compatible --format markdown` must render a short copy-pasteable troubleshooting report with masked config, quick chat check, real search-shape `stream=false` and `stream=true` checks, a plain-language summary, and a next command. Provider list commands such as `exa-search`, `exa-similar`, `zhipu-search`, `context7-library`, and `map` render result lists or a clear no-results message.
+`--format markdown` is the human-readable report format. `doctor --format markdown` must render a detailed diagnostic report with overall status, active/default/legacy config paths, log path resolution, evidence path resolution, file-logging status, masked config values with sources, minimum profile, capability status, main-search provider checks, provider connectivity checks, model metadata, and full long error/message detail instead of falling back to raw JSON. `diagnose openai-compatible --format markdown` must render a short copy-pasteable troubleshooting report with masked config, quick chat check, real search-shape `stream=false` and `stream=true` checks, a plain-language summary, and a next command. Provider list commands such as `exa-search`, `exa-similar`, `context7-library`, and `map` render result lists or a clear no-results message.
 
 `--format content` prints only the `content` field for content-bearing commands such as `search`, `fetch`, `context7-docs`, and `research`. Commands without a `content` field, including `doctor` and `config`, must print a compact non-empty text summary rather than an empty stdout.
 
@@ -90,17 +88,9 @@ Exa domain filters:
 
 Fetch output includes `ok`, `url`, `provider`, `content`, `provider_attempts`, `fallback_used`, and `elapsed_ms`.
 
-Zhipu Web Search API legacy setup:
-
-- `ZHIPU_API_URL` defaults to `https://open.bigmodel.cn/api`.
-- `ZHIPU_SEARCH_ENGINE` defaults to `search_std`.
-- Official Web Search API service values include `search_std`, `search_pro`, `search_pro_sogou`, and `search_pro_quark`.
-- `smart-search setup --zhipu-api-url URL --zhipu-search-engine ENGINE` saves these values in non-interactive mode.
-- Interactive setup no longer recommends or prompts for Zhipu in the default flow. Use `config set` or non-interactive flags only for explicit manual legacy compatibility.
-- `config set ZHIPU_SEARCH_ENGINE VALUE` must remain free-form so newly added official services do not require a CLI release.
-- `zhipu-search` corresponds to Zhipu Web Search API, not Zhipu Chat Completions `tools=[web_search]`, not Search Agent, and not the MCP Server.
-- `zhipu-search` is deprecated and not used by default routing because quota may be unavailable. Default source discovery uses bilingual `search` through Tavily / Firecrawl when configured.
-- `TAVILY_API_URL` only affects Tavily and does not proxy Zhipu.
+Tavily setup notes:
+
+- `TAVILY_API_URL` only affects Tavily.
 - `TAVILY_TIMEOUT_SECONDS` controls the Tavily `doctor` connectivity timeout. It defaults to `60` so slower pooled/community endpoints are not incorrectly marked unhealthy by the diagnostic check.
 
 Jina Reader setup:
@@ -124,15 +114,13 @@ Exa HTTP `400` or `422` failures are returned as `ok=false` with `error_type=par
 
 Exa similar output includes `ok`, `url`, `results`, `total`, and `elapsed_ms` when successful.
 
-Zhipu search output includes `ok`, `query`, `provider`, `search_engine`, `results`, `total`, and `elapsed_ms` when successful.
-
 Context7 library output includes `ok`, `query`, `provider`, `results`, `total`, and `elapsed_ms` when successful. Context7 docs output includes `ok`, `library_id`, `query`, `provider`, `results`, `total`, `content`, and `elapsed_ms` when successful.
 
 Map output includes `ok`, `base_url`, `results`, `response_time`, `url`, and `elapsed_ms` when successful.
 
 Research executor output includes `ok`, `mode=deep_research_execution`, `query_mode=research`, `question`, `budget`, `research_plan`, `routing_decision`, `stage_results`, `discovery_sources`, `final_answer`, `content`, `citations`, `evidence_items`, `gap_check`, `provider_attempts`, `providers_used`, `fallback_used`, `degraded`, `route_policy_version`, `evidence_dir`, `minimum_profile_ok`, `capability_status`, and `elapsed_ms`. The embedded `research_plan` carries `intent_signals`, `decomposition`, `capability_plan`, `evidence_policy`, `steps`, and `gap_check`. Citations must come only from fetched/read `evidence_items`; discovery sources are candidates until fetched. If evidence cannot close, `research` returns degraded gaps instead of unsupported claims.
 
-Diagnostic output masks keys, reports `config_file` / `config_dir` / `config_dir_source` / `default_config_file` / Windows legacy config metadata / `config_dir_override_value` / `config_dir_override_matches_default` / `log_dir_config_value` / `resolved_log_dir` / `evidence_dir_config_value` / `resolved_evidence_dir` / `file_logging_enabled` / `config_sources` / `primary_api_mode` / `primary_api_mode_source` / provider timeout values / `capability_status` / `minimum_profile_ok`, and includes `main_search_connection_tests` plus connection test objects for Exa, Tavily, Zhipu, Context7, and Firecrawl. `primary_connection_test` remains as a backward-compatible alias for the first configured main provider check. OpenAI-compatible provider health must be validated through `/chat/completions`; `/models` is supplementary metadata and must not be the health gate. Firecrawl currently reports whether `FIRECRAWL_API_KEY` is configured; it is not a live Firecrawl request.
+Diagnostic output masks keys, reports `config_file` / `config_dir` / `config_dir_source` / `default_config_file` / Windows legacy config metadata / `config_dir_override_value` / `config_dir_override_matches_default` / `log_dir_config_value` / `resolved_log_dir` / `evidence_dir_config_value` / `resolved_evidence_dir` / `file_logging_enabled` / `config_sources` / `primary_api_mode` / `primary_api_mode_source` / provider timeout values / `capability_status` / `minimum_profile_ok`, and includes `main_search_connection_tests` plus connection test objects for Exa, Tavily, Context7, and Firecrawl. `primary_connection_test` remains as a backward-compatible alias for the first configured main provider check. OpenAI-compatible provider health must be validated through `/chat/completions`; `/models` is supplementary metadata and must not be the health gate. xAI Responses health is validated through `/responses` (a lightweight probe in `doctor`; `diagnose xai` adds a search-shape probe with server-side tools). Firecrawl currently reports whether `FIRECRAWL_API_KEY` is configured; it is not a live Firecrawl request.
 
 When a Windows user reports that different versions seem to use different config paths, diagnose in this order: `config_dir_source`, `config_dir_override_value`, `config_dir_override_matches_default`, then `legacy_windows_config_exists`. A source of `environment` with `config_dir_override_matches_default=true` means the active path is pinned by `SMART_SEARCH_CONFIG_DIR` but is functionally the same as the current default. Do not delete either config file or the user-level override until the upgraded CLI has been verified with `config path` and `doctor` checks.
 
@@ -163,7 +151,6 @@ Each `steps[]` item must include `id`, `subquestion_id`, `tool`, `purpose`, `com
 Capability boundaries:
 
 - `search`: broad bilingual discovery and synthesis through `main_search`; use returned `routing_decision`, `provider_attempts`, `fallback_used`, and `source_warning` as orchestration signals, not as claim proof.
-- `zhipu-search`: deprecated manual compatibility command. Do not include it in default research plans.
 - `context7-library` and `context7-docs`: library, SDK, API, framework, and documentation intent. Prefer Context7 before Exa for docs/API questions.
 - `exa-search`: low-noise source discovery for official domains, papers, product pages, known domains, and trusted pages. It is not the default second hop for every high-risk or verification task.
 - `exa-similar`: adjacent-source discovery when a known reliable URL is available.
@@ -258,15 +245,15 @@ Agent timeout handling contract:
 
 ## Provider Routing
 
-- `search` builds `main_search` from `OPENAI_COMPATIBLE_API_URL` + `OPENAI_COMPATIBLE_API_KEY`, which registers OpenAI-compatible Chat Completions.
+- `search` builds `main_search` from `XAI_API_KEY` (xAI Responses with server-side `web_search`/`x_search` tools) and/or `OPENAI_COMPATIBLE_API_URL` + `OPENAI_COMPATIBLE_API_KEY` (Chat Completions). One is enough; when both are configured, `SMART_SEARCH_MAIN_SEARCH_ROUTE` (ordered CSV of `xai-responses,openai-compatible`) sets priority, and a single entry disables cross-route fallback.
 - OpenAI-compatible relays/gateways use Chat Completions `/chat/completions` through `OPENAI_COMPATIBLE_*`.
 - `OPENAI_COMPATIBLE_STREAM` and `search --stream/--no-stream` affect only the OpenAI-compatible Chat Completions transport for search/fetch. They do not change provider-internal ranking/URL description tasks.
 - Legacy `SMART_SEARCH_API_URL`, `SMART_SEARCH_API_KEY`, `SMART_SEARCH_API_MODE`, and `SMART_SEARCH_MODEL` are unsupported config keys. `config set` / `config unset` must return a parameter error for them.
 - Standard minimum profile requires `main_search`, `docs_search`, and fetch capability. Missing required capabilities produce a configuration error.
 - Jina satisfies fetch capability only when `JINA_API_KEY` is configured. Anonymous Jina Reader does not satisfy `standard`.
 - Same-capability fallback is allowed; cross-capability fallback is not. Context7 is not used for unrelated broad web queries, and page extraction providers are not used as docs search providers.
-- `main_search`: OpenAI-compatible Chat Completions.
-- `web_search`: `search` runs bilingual web_search source discovery through Tavily / Firecrawl when configured. Zhipu is deprecated from default routing and is not selected automatically for Chinese/current/domestic searches.
+- `main_search`: xAI Responses (`XAI_*`) or OpenAI-compatible Chat Completions (`OPENAI_COMPATIBLE_*`), ordered by `SMART_SEARCH_MAIN_SEARCH_ROUTE` when both are configured (default `xai-responses -> openai-compatible`).
+- `web_search`: `search` runs bilingual web_search source discovery through Tavily / Firecrawl when configured.
 - `docs_search`: explicit keyword-based docs/API/library/framework intent. Context7 is first for library/API/docs intent, then Exa for official-domain, paper, product-page, trusted-site, or low-noise supplemental discovery.
 - Fetch capability: Tavily first, then Jina Reader with `JINA_API_KEY`, then Firecrawl.
 - `search --validation strict` uses the same bilingual web_search policy as balanced mode when source discovery providers are configured. Strict queries without primary, docs, fetch, or explicit source evidence can still fail with `evidence_error`; use `--extra-sources N`, source-first commands such as `exa-search`, or `fetch` when citable evidence is required.
@@ -278,17 +265,16 @@ Agent timeout handling contract:
 - `research` uses capability-first plus provider-advantage routing. Fallback remains same-capability only; low-quality fetches, challenge pages, empty content, auth/rate/timeout/provider errors, and runtime errors are failed attempts that may trigger same-capability fallback.
 - `map` uses Tavily only.
 - `exa-search` and `exa-similar` use Exa only.
-- `zhipu-search` uses Zhipu only and is retained as a deprecated manual compatibility command.
 - `context7-library` and `context7-docs` use Context7 only.
 - Runtime config priority is environment variables first, then local config file, then defaults.
 - `setup` and `config` read/write the local Smart Search config file and do not call providers.
-- Use `config set OPENAI_COMPATIBLE_MODEL ...` to change the main-search model.
+- Use `config set OPENAI_COMPATIBLE_MODEL ...` (or `XAI_MODEL ...` for the xAI route) to change the main-search model; use `config set SMART_SEARCH_MAIN_SEARCH_ROUTE ...` to change route priority.
 
 ## Routing Heuristics
 
 - Use `exa-search --include-domains` when official documentation domains are known.
 - Use `context7-library` / `context7-docs` for explicit docs/API/SDK/library/framework intent when Context7 is configured.
-- Use the bilingual `search` pair for Chinese, domestic, current, or mixed-language source discovery. Do not use Zhipu unless the user explicitly asks for the deprecated manual route.
+- Use the bilingual `search` pair for Chinese, domestic, current, or mixed-language source discovery.
 - Use `exa-search --start-published-date` for recency-constrained source discovery.
 - Use `exa-similar` when a known good page is available and adjacent sources are needed.
 - Use `search --format content` when a human wants only the generated answer body.

package/dist/templates/cursor/rules/retrieval-routing.mdc

@@ -56,4 +56,4 @@ Use codegraph for **call chains**, **cross-package trap disambiguation**, **exte
 
 ## External facts
 
-Web/current events: **smart-search** first per `.cstl/spec/guides/retrieval-daily-guide.md`.
+Web/current events: **smart-search** first per `.cstl/spec/guides/retrieval-daily-guide.md` (see **External-knowledge gate** for search-or-not).

package/dist/templates/markdown/agents.md

@@ -23,6 +23,8 @@ Only a handful of Trellis entry points are meant for **manual `/` invocation**.
 
 For **any external / current / web fact**, run **`python ./.cstl/scripts/run_smart_search.py "<question>" --intent deep-research --json`** first. That script is the **only** Trellis web-research evidence entrypoint (it shells out to the `smart-search` CLI). Do not guess paths under package source trees or sibling repos. Platform built-in web tools (Cursor `WebSearch` / `WebFetch`, or native web tools elsewhere) are **downgrade-only fallbacks**, used solely when smart-search is unavailable (`doctor` not ok, status `not_configured` / `failed`, or search timeout). Do not reach for built-in web search while smart-search is healthy. On Cursor, `smart-search-cli` is an **internal workflow skill name** only (not shipped under `.cursor/skills/`); follow `.cstl/spec/guides/retrieval-daily-guide.md` and `.cursor/rules/retrieval-routing.mdc` for the executable contract.
 
+**External-knowledge gate:** If the answer would be wrong because the **world or a third-party API moved** and that matters → use smart-search (cheap `docs` / `broad-search` when enough; `deep-research` when multi-source). If truth lives only in this workspace → do not default to web. When unsure, prefer a cheap probe over guessing. See retrieval-daily-guide § External-knowledge gate.
+
 Managed by cursor-trellis. Edits outside this block are preserved; edits inside may be overwritten by a future `cstl update`.
 
 <!-- CSTL:END -->

package/dist/templates/markdown/spec/guides/retrieval-daily-guide.md.txt

@@ -6,6 +6,20 @@
 
 For **external / current / web facts**, **smart-search** (`run_smart_search.py`) is the **mandatory first choice**. Platform built-in web tools (Cursor `WebSearch` / `WebFetch`) are **downgrade-only**: use them solely when smart-search is unavailable (`doctor` not ok, `not_configured` / `failed`, or timeout). Never reach for built-in web search while smart-search is healthy. This rule overrides any general "use available tools" instinct — web retrieval strength is routed inside Trellis, not left to the platform default.
 
+## External-knowledge gate (search-or-not)
+
+Ask: *If this answer were wrong because the world or a third-party API moved, would that matter?*
+
+| Decision | Action |
+| --- | --- |
+| **YES** (freshness / third-party surface) | Run `run_smart_search.py` — prefer `docs` / `official-source` / `broad-search` when cheap; use `deep-research` when multi-source or claim-risk is high |
+| **NO** (truth lives in this workspace) | Use rg / codegraph / `.cstl/spec` / task artifacts only — do **not** default to web |
+| **Ambiguous** | Prefer a **cheap** external probe over guessing; do not skip solely to save a call |
+
+**YES examples:** library/SDK current API or version; changelog / release notes; CVE / GitHub issue status; pricing / product status; live URLs; industry practice when designing policy.  
+**NO examples:** symbol location / call chains; in-repo Trellis contracts; behavior of the code you are editing; pure rename/lint inside known files.  
+After search: persist under `{TASK}/research/` with a **provider label**; treat hits as candidates until corroborated (repo, test, or second source).
+
 ## Quick matrix
 
 | Need | Tool | Notes |

package/dist/templates/trellis/scripts/common/codebase_retrieval_router.py

@@ -75,6 +75,16 @@ POLICY_PATTERNS = [
     re.compile(r"\bresponsibilit(y|ies)\b", re.I),
     re.compile(r"不能"),
     re.compile(r"规则"),
+    # Workflow / task-ladder docs (AGENTS.md, workflow.md) — not code-search first
+    re.compile(r"\bFull\s+Task\b", re.I),
+    re.compile(r"\bLite\s+Task\b", re.I),
+    re.compile(r"\bMicro-Grill\b", re.I),
+    re.compile(r"\bParent\s+Task\b", re.I),
+    re.compile(r"\bChild\s+Task\b", re.I),
+    re.compile(r"\bTriage\b"),
+    re.compile(r"\btask\s+ladder\b", re.I),
+    re.compile(r"任务阶梯"),
+    re.compile(r"工作流"),
 ]
 
 CONCEPTUAL_PATTERNS = [
@@ -152,6 +162,10 @@ EXACT_PATTERNS = [
     re.compile(r"`[^`]+`"),
     re.compile(r"\b[\w.-]+\.(ts|tsx|js|jsx|py|rs|go|swift|kt|md|json|yaml|yml)\b", re.I),
     re.compile(r"\b(?:src|packages|extensions)/[\w./-]+", re.I),
+    # Meta / router-implementation queries → lexical exact (not policy docs)
+    re.compile(r"检索(意图)?路由"),
+    re.compile(r"\bintent\s*rout(?:e|ing)?\b", re.I),
+    re.compile(r"codebase[_-]?retrieval[_-]?router", re.I),
 ]
 
 

package/dist/templates/trellis/scripts/common/parent_orchestration.py

@@ -289,6 +289,317 @@ def build_child_prompt(
     return "\n".join(lines), errors
 
 
+
+def _children_by_id(data: dict) -> dict[str, dict]:
+    return {
+        item.get("id"): item
+        for item in data.get("children", [])
+        if isinstance(item, dict) and isinstance(item.get("id"), str)
+    }
+
+
+def _normalize_stages(data: dict) -> tuple[list[dict], list[str], bool]:
+    """Return (stages, errors, used_legacy_default)."""
+    errors: list[str] = []
+    children = _children_by_id(data)
+    raw_stages = data.get("stages") or []
+    if not isinstance(raw_stages, list):
+        return [], ["task-map stages must be a list"], False
+
+    if not raw_stages:
+        units = list(children.keys())
+        return (
+            [{"id": "default", "title": "All children (no stages declared)", "units": units}],
+            [],
+            True,
+        )
+
+    stages: list[dict] = []
+    seen_units: set[str] = set()
+    for idx, stage in enumerate(raw_stages):
+        if not isinstance(stage, dict):
+            errors.append(f"stages[{idx}] must be a mapping")
+            continue
+        stage_id = stage.get("id")
+        if not isinstance(stage_id, str) or not stage_id.strip():
+            errors.append(f"stages[{idx}] missing id")
+            continue
+        units = stage.get("units") or []
+        if not isinstance(units, list):
+            errors.append(f"stage `{stage_id}` units must be a list")
+            continue
+        norm_units: list[str] = []
+        for unit in units:
+            if not isinstance(unit, str) or not unit.strip():
+                errors.append(f"stage `{stage_id}` has invalid unit entry")
+                continue
+            if unit not in children:
+                errors.append(f"stage `{stage_id}` unit `{unit}` not in children[]")
+                continue
+            if unit in seen_units:
+                errors.append(f"unit `{unit}` appears in multiple stages")
+                continue
+            seen_units.add(unit)
+            norm_units.append(unit)
+        stages.append(
+            {
+                "id": stage_id,
+                "title": stage.get("title") if isinstance(stage.get("title"), str) else "",
+                "units": norm_units,
+            }
+        )
+    return stages, errors, False
+
+
+def _unit_readiness(
+    unit_id: str,
+    children_by_id: dict[str, dict],
+) -> tuple[str, list[str]]:
+    entry = children_by_id.get(unit_id) or {}
+    blocked = _unmet_dependencies(entry, children_by_id)
+    return ("ready" if not blocked else "blocked", blocked)
+
+
+def build_publish_pack(
+    parent_dir: Path,
+    *,
+    stage_id: str | None = None,
+    mode: str = "inline",
+    dry_run: bool = False,
+) -> tuple[str | None, list[str]]:
+    """Build campaign PACK index + per-unit prompts under child-prompts/."""
+    errors: list[str] = []
+    repo_root = get_repo_root()
+    parent_rel = _repo_rel(parent_dir, repo_root)
+
+    if not (parent_dir / "task.json").is_file():
+        return None, [f"parent task.json missing: {parent_dir}"]
+
+    data, _ = load_task_map(parent_dir)
+    if data is None:
+        return None, ["parent task-map.md missing or invalid"]
+
+    stages, stage_errors, legacy = _normalize_stages(data)
+    errors.extend(stage_errors)
+    if errors:
+        return None, errors
+
+    if stage_id:
+        stages = [s for s in stages if s.get("id") == stage_id]
+        if not stages:
+            return None, [f"unknown stage id: {stage_id}"]
+
+    children_by_id = _children_by_id(data)
+    prompts_dir = parent_dir / "child-prompts"
+    ready_rows: list[tuple[str, str, str]] = []
+    blocked_rows: list[tuple[str, str, list[str]]] = []
+
+    pack_lines = [
+        f"# Campaign PACK — `{parent_dir.name}`",
+        "",
+        f"- Parent: `{parent_rel}`",
+        f"- Generated: {_utc_now()}",
+        f"- Mode: `{mode}`",
+        "- Path rule: every worker must `task.py select <explicit-child-path>`; "
+        "do not rely on selected_task inheritance across windows.",
+        "",
+        "## Manual window path (PACK)",
+        "",
+        "1. Run `publish-pack` (this file) on the Parent.",
+        "2. For each **ready** unit: IDE **New Chat** or Agents Window → paste `child-prompts/<child>.md`.",
+        "3. In that session run `python ./.cstl/scripts/task.py select <child-path>`.",
+        "4. Parent retains `review-child` / `integrate-child`. PACK is not RUN auto-dispatch.",
+        "",
+        "## Stages",
+        "",
+    ]
+    if legacy:
+        pack_lines.append(
+            "> Warning: no `stages:` in task-map; using implicit `default` stage "
+            "with all children. Declare `stages:` for HYBRID campaign packs."
+        )
+        pack_lines.append("")
+
+    written: list[str] = []
+    for stage in stages:
+        sid = stage["id"]
+        title = stage.get("title") or ""
+        heading = f"### `{sid}`" + (f" — {title}" if title else "")
+        pack_lines.append(heading)
+        pack_lines.append("")
+        for unit in stage.get("units") or []:
+            readiness, blocked = _unit_readiness(unit, children_by_id)
+            child_dir = parent_dir.parent / unit
+            child_rel = _repo_rel(child_dir, repo_root)
+            state = (children_by_id.get(unit) or {}).get("state", "?")
+            if readiness == "ready":
+                prompt, prompt_errors = build_child_prompt(
+                    parent_dir,
+                    child_dir,
+                    include_artifacts=False,
+                    mode=mode,
+                )
+                if prompt_errors or not prompt:
+                    errors.extend(prompt_errors or [f"could not build prompt for `{unit}`"])
+                    continue
+                out_name = f"{unit}.md"
+                out_rel = f"{parent_rel}/child-prompts/{out_name}"
+                if not dry_run:
+                    prompts_dir.mkdir(parents=True, exist_ok=True)
+                    (prompts_dir / out_name).write_text(prompt + "\n", encoding="utf-8")
+                    written.append(out_rel)
+                ready_rows.append((sid, unit, out_rel))
+                pack_lines.append(
+                    f"- `{unit}` — `{state}` — **ready** — prompt: `child-prompts/{out_name}` "
+                    f"(select `{child_rel}`)"
+                )
+            else:
+                blocked_rows.append((sid, unit, blocked))
+                stub = "\n".join(
+                    [
+                        f"# BLOCKED — `{unit}`",
+                        "",
+                        f"- Parent: `{parent_rel}`",
+                        f"- Child: `{child_rel}`",
+                        f"- Stage: `{sid}`",
+                        "- Do not start implementation until dependencies reach "
+                        "`integrated` or `cancelled`.",
+                        "",
+                        "Unmet dependencies:",
+                        *[f"- {item}" for item in blocked],
+                        "",
+                    ]
+                )
+                out_name = f"{unit}.md"
+                out_rel = f"{parent_rel}/child-prompts/{out_name}"
+                if not dry_run:
+                    prompts_dir.mkdir(parents=True, exist_ok=True)
+                    (prompts_dir / out_name).write_text(stub, encoding="utf-8")
+                    written.append(out_rel)
+                pack_lines.append(
+                    f"- `{unit}` — `{state}` — **blocked** — {', '.join(blocked)}"
+                )
+        pack_lines.append("")
+
+    pack_lines.extend(["## Ready", ""])
+    if ready_rows:
+        for sid, unit, path in ready_rows:
+            pack_lines.append(f"- `{sid}` / `{unit}` → `{path}`")
+    else:
+        pack_lines.append("(none)")
+    pack_lines.extend(["", "## Blocked", ""])
+    if blocked_rows:
+        for sid, unit, deps in blocked_rows:
+            pack_lines.append(f"- `{sid}` / `{unit}` — {', '.join(deps)}")
+    else:
+        pack_lines.append("(none)")
+    pack_lines.append("")
+
+    pack_body = "\n".join(pack_lines)
+    pack_rel = f"{parent_rel}/child-prompts/PACK.md"
+    if not dry_run:
+        prompts_dir.mkdir(parents=True, exist_ok=True)
+        (prompts_dir / "PACK.md").write_text(pack_body + "\n", encoding="utf-8")
+        written.append(pack_rel)
+
+    if errors:
+        return None, errors
+
+    summary = [
+        f"# publish-pack — `{parent_dir.name}`",
+        "",
+        f"- Parent: `{parent_rel}`",
+        f"- dry_run: {dry_run}",
+        f"- legacy_no_stages: {legacy}",
+        f"- ready: {len(ready_rows)}",
+        f"- blocked: {len(blocked_rows)}",
+        f"- pack_index: `{pack_rel}`",
+        "",
+    ]
+    if written:
+        summary.append("## Written")
+        summary.append("")
+        for path in written:
+            summary.append(f"- `{path}`")
+        summary.append("")
+    elif dry_run:
+        summary.append("(dry-run: no files written)")
+        summary.append("")
+    summary.append(pack_body)
+    return "\n".join(summary), []
+
+
+def build_parent_status_dict(parent_dir: Path) -> dict | None:
+    """Machine-readable parent orchestration snapshot (campaign UI / MCP)."""
+    repo_root = get_repo_root()
+    parent_rel = _repo_rel(parent_dir, repo_root)
+    data, _ = load_task_map(parent_dir)
+    if data is None:
+        return None
+
+    children_by_id = _children_by_id(data)
+    stages, stage_errors, legacy = _normalize_stages(data)
+
+    stage_rows: list[dict] = []
+    for stage in stages:
+        units: list[dict] = []
+        for unit in stage.get("units") or []:
+            entry = children_by_id.get(unit) or {}
+            readiness, blocked = _unit_readiness(unit, children_by_id)
+            units.append(
+                {
+                    "id": unit,
+                    "state": entry.get("state", "?"),
+                    "readiness": readiness,
+                    "blockedBy": blocked,
+                }
+            )
+        stage_rows.append(
+            {
+                "id": stage["id"],
+                "title": stage.get("title") or "",
+                "units": units,
+            }
+        )
+
+    children_rows: list[dict] = []
+    for child in data.get("children") or []:
+        if not isinstance(child, dict):
+            continue
+        cid = child.get("id")
+        if not isinstance(cid, str):
+            continue
+        child_dir = parent_dir.parent / cid
+        children_rows.append(
+            {
+                "id": cid,
+                "state": child.get("state", "?"),
+                "dependsOn": child.get("depends_on") or [],
+                "touches": child.get("touches") or [],
+                "isolation": child.get("isolation"),
+                "branch": child.get("branch"),
+                "worktreePath": child.get("worktree_path"),
+                "evidence": child.get("evidence"),
+                "ref": child.get("ref"),
+                "verifyMd": (child_dir / "verify.md").is_file(),
+                "handoffMd": (child_dir / "handoff.md").is_file(),
+            }
+        )
+
+    return {
+        "id": parent_dir.name,
+        "path": parent_rel,
+        "contractEpoch": data.get("contract_epoch"),
+        "executionTopology": data.get("execution_topology"),
+        "mergeLimit": data.get("merge_limit"),
+        "stages": stage_rows,
+        "children": children_rows,
+        "integrationQueue": data.get("integration_queue") or [],
+        "stageErrors": stage_errors,
+        "legacyStages": legacy,
+    }
+
+
 def build_parent_status(parent_dir: Path) -> str:
     """Render a parent task-map status summary for the reviewer."""
     repo_root = get_repo_root()
@@ -305,10 +616,37 @@ def build_parent_status(parent_dir: Path) -> str:
         f"- execution_topology: {data.get('execution_topology', '?')}",
         f"- merge_limit: {data.get('merge_limit', '?')}",
         "",
-        "## Children",
-        "",
     ]
 
+    children_by_id = _children_by_id(data)
+    stages, stage_errors, legacy = _normalize_stages(data)
+    lines.append("## Stages")
+    lines.append("")
+    if stage_errors:
+        for err in stage_errors:
+            lines.append(f"- error: {err}")
+        lines.append("")
+    elif legacy:
+        lines.append("stages: (none declared — implicit `default` for publish-pack)")
+        lines.append("")
+    else:
+        for stage in stages:
+            sid = stage["id"]
+            title = stage.get("title") or ""
+            heading = f"### `{sid}`" + (f" — {title}" if title else "")
+            lines.append(heading)
+            for unit in stage.get("units") or []:
+                entry = children_by_id.get(unit) or {}
+                state = entry.get("state", "?")
+                readiness, blocked = _unit_readiness(unit, children_by_id)
+                if readiness == "ready":
+                    lines.append(f"- `{unit}` — `{state}` — ready")
+                else:
+                    lines.append(f"- `{unit}` — `{state}` — blocked ({', '.join(blocked)})")
+            lines.append("")
+
+    lines.extend(["## Children", ""])
+
     children = data.get("children") or []
     if not children:
         lines.append("(no children in task-map)")
@@ -354,6 +692,7 @@ def build_parent_status(parent_dir: Path) -> str:
     lines.append("")
     lines.append("```bash")
     lines.append(f"python ./.cstl/scripts/task.py parent-status {parent_rel}")
+    lines.append(f"python ./.cstl/scripts/task.py publish-pack {parent_rel}")
     lines.append(f"python ./.cstl/scripts/task.py generate-child-prompt {parent_rel} <child> --mode subagent")
     lines.append(f"python ./.cstl/scripts/task.py generate-child-prompt {parent_rel} <child> --mode inline")
     lines.append(f"python ./.cstl/scripts/task.py review-child {parent_rel} <child> --check")