@opencodehub/cli 0.2.2 → 0.2.3

package/dist/plugin-assets/skills/codehub-document/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: codehub-document
+description: "Use when the user asks to generate, regenerate, or refresh long-form codebase documentation, an architecture book, a module map, or a per-repo reference — especially after `codehub analyze` finishes or after a large merge. Examples: \"document this repo\", \"regenerate the architecture docs\", \"write a module map for the monorepo\", \"produce a group-wide portfolio doc\". DO NOT use if the repo is not indexed — run `codehub analyze` first and confirm `mcp__opencodehub__list_repos` returns the repo. DO NOT use for PR descriptions (use `codehub-pr-description`), onboarding docs (use `codehub-onboarding`), or cross-repo contract maps alone (use `codehub-contract-map`)."
+allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(codehub:*), mcp__opencodehub__list_repos, mcp__opencodehub__project_profile, mcp__opencodehub__query, mcp__opencodehub__context, mcp__opencodehub__impact, mcp__opencodehub__dependencies, mcp__opencodehub__owners, mcp__opencodehub__risk_trends, mcp__opencodehub__route_map, mcp__opencodehub__tool_map, mcp__opencodehub__list_dead_code, mcp__opencodehub__list_findings, mcp__opencodehub__verdict, mcp__opencodehub__group_list, mcp__opencodehub__group_query, mcp__opencodehub__group_status, mcp__opencodehub__group_contracts, mcp__opencodehub__group_cross_repo_links, mcp__opencodehub__sql, Task"
+argument-hint: "[output-dir] [--group <name>] [--committed] [--refresh] [--section <name>]"
+color: indigo
+model: sonnet
+---
+
+# codehub-document
+
+Primary artifact generator. Produces a tree of cross-linked Markdown under `.codehub/docs/` (single-repo) or `.codehub/groups/<name>/docs/` (group mode) using a three-phase orchestration: **Phase 0 parallel precompute waves** → **Phase 1 file-level subagent fan-out** (one packet = one output file) → **Phase 2 deterministic cross-reference assembly**.
+
+**Model policy.** This skill runs on Sonnet by default. Bump to Opus in two cases:
+
+1. `--refresh --group` combined — the pruning + partial fan-out across members needs the extra judgment.
+2. Any individual packet may set `model: opus` in its frontmatter to opt into Opus for synthesis-heavy roles. The cross-repo skeletons (`doc-cross-repo-*`) and `doc-analysis-risk-hotspots` typically do this; full-scan single-repo packets stay on Sonnet.
+
+## Preconditions (check before Phase 0)
+
+1. `mcp__opencodehub__list_repos` returns the target. If not, emit `Run codehub analyze first — repo <name> is not indexed.` and stop.
+2. `codehub status` reports fresh. If stale, emit `Run 'codehub analyze' first — index is stale` and stop.
+3. Group mode only: `mcp__opencodehub__group_status({group})` must return `fresh: true` for every member. If any member is stale, abort and name each stale repo.
+
+## Arguments
+
+- `[output-dir]` (optional positional) — where to write. Default is `.codehub/docs/` (gitignored). With `--committed`, default flips to `docs/codehub/` and the skill does not add a `.gitignore` entry.
+- `--group <name>` — enable group mode. Phase 0 calls `group_list` + `group_status` + `group_contracts` + `group_query`. Phase CD dispatches `doc-cross-repo`.
+- `--committed` — write under `docs/codehub/` (or user-supplied path) instead of `.codehub/docs/`. Does not touch `.gitignore`.
+- `--refresh` — consult `.docmeta.json`, identify stale sections by comparing `max(mtime(section.sources[]))` against `section.mtime`, and dispatch exactly one file-level subagent per stale section (re-seeding its packet from `templates/agents/<role>.md`). Phase 2 always re-runs.
+- `--section <name>` — regenerate one named section (e.g., `architecture/system-overview`). Dispatches exactly one subagent with one skeleton and re-runs Phase 2. Useful for targeted updates.
+
+## Four-phase orchestration
+
+### Phase 0 — Precompute shared context (parallel waves, no subagent)
+
+Phase 0 writes `<docs-root>/.context.md` and `<docs-root>/.prefetch.md` so Phase 1 subagents read cached data instead of re-calling tools. It runs as three waves — **two of them are single-message tool-call batches**, so the MCP fan-out parallelizes.
+
+**Wave 0a — independent precompute (one message, parallel)**. Issue all of these in a single tool-use batch:
+
+- `mcp__opencodehub__list_repos`
+- `mcp__opencodehub__project_profile`
+- `mcp__opencodehub__sql` — schema probe: `SELECT table_name, column_name FROM information_schema.columns WHERE table_name IN ('nodes','relations') ORDER BY table_name, column_name`
+- `mcp__opencodehub__route_map`
+- `mcp__opencodehub__tool_map`
+- `mcp__opencodehub__dependencies`
+- `mcp__opencodehub__risk_trends`
+- `mcp__opencodehub__list_dead_code`
+- `mcp__opencodehub__list_findings`
+- Group mode only: `mcp__opencodehub__group_list`, `mcp__opencodehub__group_status`, `mcp__opencodehub__group_contracts`
+
+**Wave 0b — depends on 0a (one message, parallel)**. Needs schema column names + profile entry points from 0a, so it is a second batch. Issue in one message:
+
+- `mcp__opencodehub__sql` — top communities (`SELECT … FROM nodes WHERE kind='Community' ORDER BY cohesion DESC LIMIT 10`)
+- `mcp__opencodehub__sql` — top processes (`SELECT … FROM nodes WHERE kind='Process' ORDER BY step_count DESC LIMIT 10`)
+- `mcp__opencodehub__sql` — relations slice for diagrams (filtered per the schema probe)
+- `mcp__opencodehub__owners` × top-5 folders (derived from `project_profile` entry points + file-count heuristic)
+- Group mode only: `mcp__opencodehub__group_query` for any canonical cross-repo search terms
+
+**Wave 0c — inline Write (no tool batch)**. Deterministic post-processing; no MCP calls:
+
+1. Assemble `<docs-root>/.context.md` (hard 200-line cap; per-section `truncated: true` when the raw output exceeds the cap). Sections: repo profile, schema probe, top communities, top processes, routes, MCP tools, owners summary, dependencies summary, dead-code counts, findings summary, risk trends. Group mode appends: group manifest, contracts matrix, freshness table.
+2. Write `<docs-root>/.prefetch.md` — newline-delimited JSON, one record per tool call with `{tool, args, sha256, keys, cached_at, truncated}`. Example:
+
+    ```json
+    {"tool":"project_profile","args":{"repo":"opencodehub"},"sha256":"…","keys":["languages","stacks","entryPoints"],"cached_at":"2026-04-27T18:04:11Z","truncated":false}
+    ```
+
+The full layout of both files, plus the schema-preflight rationale and the Phase 0 pseudocode, live in `references/data-source-map.md`.
+
+### Phase 1 — File-level subagent fan-out
+
+One packet = one output file. The orchestrator seeds packets by copying `templates/agents/<role>.md` to `<docs-root>/.packets/<role>.md`, substituting the placeholders listed in `templates/agents/README.md § Placeholders`, and spawning a `general-purpose` subagent per packet with the prompt from `templates/orchestrator-prompt.md`.
+
+**Skeletons (single-repo)**. Ten are always seeded; four are conditional on triggers observed in Phase 0:
+
+| Role | Always / Conditional | Trigger |
+|------|----------------------|---------|
+| `doc-architecture-system-overview` | always | — |
+| `doc-architecture-module-map` | always | — |
+| `doc-architecture-data-flow` | always | — |
+| `doc-reference-public-api` | always | — |
+| `doc-behavior-processes` | always | — |
+| `doc-analysis-risk-hotspots` | always | — |
+| `doc-analysis-ownership` | always | — |
+| `doc-analysis-dead-code` | always | — |
+| `doc-diagrams-components` | always | — |
+| `doc-diagrams-dependency-graph` | always | — |
+| `doc-reference-cli` | conditional | CLI detected in `project_profile` entry points |
+| `doc-reference-mcp-tools` | conditional | `tool_map` returns ≥ 1 row |
+| `doc-behavior-state-machines` | conditional | ≥ 2 `StateMachine` nodes in the graph |
+| `doc-diagrams-sequences` | conditional | ≥ 1 process with ≥ 3 steps |
+
+**Group mode** adds three cross-repo skeletons seeded from `{{ group_docs_root }}/.packets/`:
+
+- `doc-cross-repo-portfolio-map`
+- `doc-cross-repo-contracts-matrix`
+- `doc-cross-repo-dependency-flow`
+
+**Dispatch priority (citation magnetism)**. Single-repo, up to ~10 packets per message, two messages back-to-back (no gate — this is purely how Claude Code's concurrent-Agent ceiling is managed):
+
+1. **Message 1 (high-magnetism first)**: `system-overview`, `public-api`, `processes`, `components`, `module-map`, `data-flow`, plus up to four of the remaining always/conditional skeletons.
+2. **Message 2 (immediately after)**: every remaining seeded skeleton.
+
+**Group mode dispatch**. Sort all seeded packets by `(priority_class, repo_index)` and greedily fill batches of ≤ 10. Example: 3 repos × ~12 per-repo skeletons + 3 cross-repo skeletons ≈ 39 packets → 4 messages of ≤ 10, dispatched back-to-back.
+
+**Spawn parameters** (per `templates/orchestrator-prompt.md § Usage at the orchestrator`):
+
+- `subagent_type`: `general-purpose`
+- `name`: the role (e.g. `doc-architecture-system-overview`)
+- `description`: 3–5 words
+- `model`: read from the packet's `model:` frontmatter (default `sonnet`, individual packets may request `opus`)
+- `run_in_background`: `true`
+- `prompt`: the canonical text from `templates/orchestrator-prompt.md`, with `{{ packet_path }}` substituted
+
+**Monitoring**. Orchestrator tails `.packets/*.md` with `wc -l` at 30 s, 2 m, 5 m, then every 5 m — identical to the erpaval Act monitoring rhythm. A packet whose line count stops growing but whose `status:` line is still `IN_PROGRESS` is the signal to `SendMessage` a nudge or mark it failed.
+
+### Phase 2 — Cross-reference assembler (inline, deterministic)
+
+No LLM call. Pure regex + join. See `references/cross-reference-spec.md` for the full algorithm. Summary:
+
+1. Extract every backtick `<path>:<LOC>` (or `<repo>:<path>:<LOC>`) citation from every generated Markdown file.
+2. Build a co-occurrence index: `source_file → [docs_citing_it]`.
+3. For any two docs sharing ≥ 2 common sources, append `## See also` (3–5 links) to both.
+4. **Group mode — sourced cross-repo links (v2)**: call `mcp__opencodehub__group_cross_repo_links` with the current `--group` value. The tool returns a deterministic, alpha-sorted `links[]` array (each entry: `source_repo_uri`, `target_repo_uri`, `source_doc_path`, `target_doc_path`, `relation`, optional `evidence`). Embed that array **verbatim** into `.docmeta.json.cross_repo_links[]` (schema v2). Then render the `## See also (other repos in group)` footer by grouping links by `source_doc_path`, emitting one bullet per target, labelled by `relation` (e.g. `depends_on → orders-api/architecture.md`). Do NOT re-compute links heuristically; the tool is the single source of truth.
+5. Write `<docs-root>/README.md` (landing page with the structure-is-deterministic disclaimer) and `<docs-root>/.docmeta.json` with `schema_version: 2`. `.docmeta.json.sections[i].agent` records the file-role (e.g. `doc-architecture-system-overview`) for `--refresh` traceability. Pre-v2 `.docmeta.json` files on disk remain readable; the orchestrator lazily upgrades them on the next regeneration by writing v2.
+
+## `--refresh` algorithm
+
+See `references/cross-reference-spec.md § --refresh algorithm` for the full procedure. One-line summary: compare `max(mtime(section.sources[]))` against `section.mtime`, dispatch exactly one file-level subagent per stale section (re-seeding its packet from the skeleton), then always re-run Phase 2.
+
+## Progressive disclosure — references/
+
+| Reference                          | When to consult                                          |
+| ---------------------------------- | -------------------------------------------------------- |
+| `references/document-templates.md` | Per-file structural templates (what goes in each section)|
+| `references/data-source-map.md`    | Which MCP tools feed which subagent                      |
+| `references/cross-reference-spec.md` | Phase E algorithm + `.docmeta.json` schema + `--refresh` |
+| `references/mermaid-patterns.md`   | Mermaid idioms for each diagram type                     |
+
+## Quality checklist
+
+- [ ] Phase 0 ran waves 0a and 0b as single-message tool batches; `.context.md` is ≤ 200 lines; `.prefetch.md` has one JSON line per tool call including the schema probe.
+- [ ] Phase 1 seeded one packet per output file under `<docs-root>/.packets/`, with placeholders substituted and `status: IN_PROGRESS`.
+- [ ] Phase 1 dispatched packets in batches of ≤ 10 per message, priority-first (system-overview, public-api, processes, components, module-map, data-flow before the rest).
+- [ ] Every generated file has H1 = identifier, no YAML frontmatter (the frontmatter lives in the packet, not the output).
+- [ ] Every factual claim in every output has a backtick citation (`path:LOC` or `repo:path:LOC`).
+- [ ] Every packet has `status: COMPLETE` and a populated Work log / Validation / Summary section before Phase 2 starts.
+- [ ] Phase 2 wrote `.docmeta.json` validating against the schema in `references/cross-reference-spec.md`, with `sections[i].agent` set to the file-role.
+- [ ] `See also` footers appear on every doc with ≥ 2 shared citations.
+- [ ] Group mode: outputs from `doc-cross-repo-*` packets use `repo:path:LOC` citations exclusively.
+- [ ] `codehub status` is fresh before this skill starts; otherwise the preconditions caught the stale state.

package/dist/plugin-assets/skills/codehub-document/references/cross-reference-spec.md

@@ -0,0 +1,142 @@
+# cross-reference-spec — Phase E algorithm + `.docmeta.json` schema + `--refresh`
+
+Phase E is **deterministic Markdown assembly**. No LLM call. Pure regex + join + write.
+
+## Citation grammar
+
+Every factual claim carries an inline backtick citation. Two forms, both recognized by the assembler:
+
+- **Single-repo**: `` `<path>:<LOC>` `` or `` `<path>:<start>-<end>` ``. File-level cites append ` (N LOC)`.
+- **Group-qualified**: `` `<repo>:<path>:<LOC>` `` — **mandatory** in any file under `cross-repo/` or `contracts.md`.
+
+### The Phase E regex
+
+```
+(?P<repo>[a-zA-Z0-9_-]+:)?(?P<path>[^\s`:]+\.[a-zA-Z0-9]+)(?::(?P<start>\d+)(?:-(?P<end>\d+))?)?(?:\s*\((?P<loc>\d+)\s*LOC\))?
+```
+
+The assembler scans only between backtick pairs — never raw prose.
+
+## Algorithm
+
+1. **Walk** every `.md` file under the output tree (excluding the precompute files).
+2. **Extract** every citation matching the regex between backtick pairs.
+3. **Build** the co-occurrence index: `source_file → [docs_citing_it]`.
+4. **For each doc**, compute its set of siblings: docs that share ≥ 2 common source citations.
+5. **Rank** siblings by shared-citation count, then alphabetically. Take the top 3–5.
+6. **Append** a `## See also` footer to every doc with ≥ 1 sibling. Use Markdown reference-style links, not inline URLs.
+7. **Group mode**: for every `cross-repo/*.md` file, additionally append `## See also (other repos in group)` listing relative paths into sibling repos' generated docs (e.g., `../../billing/.codehub/docs/reference/public-api.md`).
+8. **Dedup** sibling paths across both footer sections.
+9. **Strip** any YAML frontmatter blocks on generated docs and record a `frontmatter_removed: [<path>]` entry in `.docmeta.json`.
+10. **Write** `README.md` (landing page with the "Prose is LLM-generated; structure is graph-derived" disclaimer) and `.docmeta.json` (schema below).
+
+## `.docmeta.json` schema
+
+The file carries a `schema_version` integer. **v2 is the current schema**; v1 files on disk remain readable — the orchestrator lazily upgrades them on the next regeneration by re-running Phase E and writing v2. v2 adds one new field — `cross_repo_links[]` — populated in group mode from the `group_cross_repo_links` MCP tool. All v1 fields carry through unchanged.
+
+```json
+{
+  "$schema": "https://opencodehub.dev/schemas/docmeta-v2.json",
+  "schema_version": 2,
+  "generated_at": "2026-04-27T18:12:04Z",
+  "codehub_graph_hash": "sha256:a1b2c3…",
+  "mode": "single-repo",
+  "repo": "opencodehub",
+  "group": null,
+  "staleness_at": "2026-04-27T18:12:04Z",
+  "sections": [
+    {
+      "path": "architecture/system-overview.md",
+      "agent": "doc-architecture",
+      "sources": [
+        "packages/mcp/src/server.ts",
+        "packages/mcp/src/index.ts"
+      ],
+      "mtime": "2026-04-27T18:11:58Z",
+      "citation_count": 18,
+      "mermaid_count": 1
+    }
+  ],
+  "cross_repo_refs": [],
+  "cross_repo_links": [],
+  "frontmatter_removed": []
+}
+```
+
+Group mode populates `cross_repo_refs[]` (as in v1):
+
+```json
+{
+  "cross_repo_refs": [
+    {
+      "repo": "billing",
+      "from_doc": "cross-repo/contracts-matrix.md",
+      "to_doc": "../../../billing/.codehub/docs/reference/public-api.md",
+      "contract_count": 4
+    }
+  ]
+}
+```
+
+And `cross_repo_links[]` (new in v2, sourced from `group_cross_repo_links`):
+
+```json
+{
+  "cross_repo_links": [
+    {
+      "source_repo_uri": "github.com/org/frontend",
+      "target_repo_uri": "github.com/org/orders-api",
+      "source_doc_path": "frontend/architecture.md",
+      "target_doc_path": "orders-api/architecture.md",
+      "relation": "depends_on",
+      "evidence": "GET /orders/{id}"
+    },
+    {
+      "source_repo_uri": "github.com/org/orders-api",
+      "target_repo_uri": "github.com/org/frontend",
+      "source_doc_path": "orders-api/architecture.md",
+      "target_doc_path": "frontend/architecture.md",
+      "relation": "consumer_of",
+      "evidence": "GET /orders/{id}"
+    }
+  ]
+}
+```
+
+`cross_repo_links[]` is the sourced, deterministic, alpha-sorted link graph emitted by `group_cross_repo_links`. The engine owns the data (one record per matched contract, emitted in both directions — `depends_on` from consumer to producer, `consumer_of` from producer to consumer). The skill owns the file — it embeds the tool's output verbatim during Phase E and renders the `## See also (other repos in group)` footer from it. Backward-compat: pre-v2 files without `cross_repo_links` are fine to read; the orchestrator writes v2 on next regeneration.
+
+**Relation vocabulary**:
+
+- `depends_on` — source repo consumes target repo (consumer → producer). The target is an upstream API.
+- `consumer_of` — source repo is consumed BY target repo (producer → consumer). The target is a known downstream.
+- `see_also` — reserved for a later AC. Bidirectional doc link inferred from non-contract cross-repo references.
+
+`staleness_at` is copied from the `_meta.codehub/staleness` envelope on the last MCP response the assembler observed.
+
+## `--refresh` algorithm
+
+1. Load `.docmeta.json` from the existing output tree.
+2. Fetch the current `codehub_graph_hash` from `mcp__opencodehub__list_repos`. If it matches the manifest's hash exactly, skip to step 5.
+3. For each `section` in the manifest:
+   - Compute `max(mtime(source))` across `sections[i].sources[]` via `stat`.
+   - If `max(source_mtime) > sections[i].mtime`: mark the section stale.
+4. Collect the union of stale sections and their owners (`section.agent`). Dispatch only those subagents; pass them a `sections_to_refresh` list so they write only those files.
+5. Always re-run Phase E over the full tree (cross-reference assembly is cheap and idempotent).
+
+The algorithm is **tolerant of the common case** where `codehub analyze` updates the graph but touches only a few files. Falling back to a full regen when `graph_hash` churns avoids subtle staleness when node IDs shift.
+
+## Determinism call-outs
+
+- **Deterministic**: file list, directory layout, section ordering, diagram node set, citation targets, `.docmeta.json` structure.
+- **Non-deterministic**: prose sentences, diagram edge ordering within a node, choice of which 3 processes get sequence diagrams among ties.
+
+Generated `README.md` includes the one-line disclaimer: *"Prose is LLM-generated; structure is graph-derived. Phase E cross-references are deterministic."*
+
+## Common failure modes
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `See also` footer points at a missing file | Phase AB wrote a partial file, Phase E saw the citation but the target was orphaned | Re-run `--refresh` on the owning section |
+| A group-mode `cross-repo/` file has a plain `path:LOC` citation | `doc-cross-repo` slipped on the grammar rule | Update the subagent's Quality Checklist enforcement; add the bad line to the agent's prompt |
+| `.docmeta.json.frontmatter_removed` is non-empty | A subagent emitted YAML frontmatter despite the rule | The assembler stripped it; no user action needed, but fix the subagent |
+| `--refresh` regenerated everything unexpectedly | `graph_hash` changed (node IDs shifted) | Expected behavior on re-analyze; not a bug |

package/dist/plugin-assets/skills/codehub-document/references/data-source-map.md

@@ -0,0 +1,139 @@
+# data-source-map — which tools feed which subagent
+
+Phase 0 precomputes a shared context from these sources. Subagents read the precompute from disk; they do not re-call tools whose digest is in `.prefetch.md`.
+
+## `.context.md` (200-line cap)
+
+```markdown
+# Codehub context — <repo-or-group-name>
+generated_at: <ISO-8601>
+graph_hash: <from list_repos>
+
+## Repo profile                      # from project_profile
+- languages: TypeScript 87%, Rust 11%, Python 2%
+- stacks: Node 22, pnpm 10, DuckDB, Vitest
+- entry points: packages/mcp/src/index.ts, packages/cli/src/bin.ts
+
+## Top communities (≤ 10)            # from sql: SELECT name, inferred_label, cohesion, symbol_count
+                                      # FROM nodes WHERE kind='Community' ORDER BY cohesion DESC LIMIT 10
+| name | inferred_label | cohesion | symbols |
+
+## Top processes (≤ 10)              # from sql: SELECT name, entry_point, step_count
+                                      # FROM nodes WHERE kind='Process' ORDER BY step_count DESC LIMIT 10
+| name | entry_point | step_count |
+
+## Routes                            # from route_map — truncated to 25 rows
+| method | path | handler |
+
+## MCP tools                         # from tool_map — truncated to 25 rows
+| tool | summary |
+
+## Owners summary                    # from owners on top 5 folders
+| path | top_owner | share |
+
+## Staleness envelope                # from list_repos._meta.codehub/staleness
+- graph_hash: …
+- indexed_at: …
+- staleness_level: fresh | stale
+```
+
+**Group mode adds:**
+
+```markdown
+## Group manifest                    # from group_list
+- group: <name>
+- repos: [<list>]
+
+## Group contracts matrix            # from group_contracts
+| producer | consumer | count |
+
+## Group freshness                   # from group_status
+| repo | fresh | last_indexed |
+```
+
+## `.prefetch.md` (no cap, ledger)
+
+Newline-delimited JSON. One line per tool call. Example:
+
+```json
+{"tool":"project_profile","args":{"repo":"opencodehub"},"sha256":"8c5f…","keys":["languages","stacks","entryPoints"],"cached_at":"2026-04-27T18:04:11Z","truncated":false}
+{"tool":"tool_map","args":{"repo":"opencodehub"},"sha256":"1b9e…","keys":["tools"],"cached_at":"2026-04-27T18:04:12Z","truncated":true}
+```
+
+Subagents use the ledger two ways:
+
+1. **Skip re-call.** If an agent would call a tool whose digest is here, it reads `.prefetch.md` + `.context.md` instead.
+2. **Know when data is truncated.** Sections with `truncated: true` signal that raw tool output is larger than what's in `.context.md`. The agent may re-call the tool for a targeted slice if needed.
+
+## Per-role input table
+
+File-level fan-out means one role may seed multiple packets (for example, `doc-architecture` seeds `system-overview`, `module-map`, `data-flow`; `doc-diagrams` seeds `components`, `sequences`, `dependency-graph`). This table is indexed by role — the `codehub-document` orchestrator reads it when deciding which cached digests to mention in each packet's Input specification.
+
+| Role               | Primary tools (Phase 0 cached)                              | Mid-run tools (not cached; agent may call)                |
+|--------------------|-------------------------------------------------------------|-----------------------------------------------------------|
+| `doc-architecture` | `project_profile`, `sql` (communities, processes)           | `context`, `query`, `dependencies`, `sql` for deeper joins |
+| `doc-reference`    | `tool_map`, `route_map`, `project_profile`                  | `signature`, `context`, `sql` for export filtering        |
+| `doc-behavior`     | `sql` (processes), `route_map`, `tool_map`                  | `context` per process, `query` to disambiguate names      |
+| `doc-analysis`     | `owners`, `risk_trends`, `list_findings`, `list_dead_code`  | `verdict` (optional), `sql` for drill-down                |
+| `doc-diagrams`     | `sql` (relations), `dependencies`                           | `context` per process, `query` for actor labels           |
+| `doc-cross-repo`   | `group_list`, `group_status`, `group_contracts`             | `group_query`, `route_map` per member                     |
+
+## Schema preflight (non-optional)
+
+**Before composing any SQL query over `nodes`, `relations`, or any other
+graph table, Phase 0 MUST probe the schema once and cache the result in
+`.prefetch.md`.** Subagents then consult the cached schema instead of
+guessing column names, which would fail with `Binder Error: Referenced
+column "X" not found in FROM clause`.
+
+The probe is one SQL call:
+
+```
+sql("SELECT table_name, column_name FROM information_schema.columns
+     WHERE table_name IN ('nodes','relations') ORDER BY table_name, column_name")
+```
+
+Write the result as a dedicated `.context.md § Schema` subsection (top 30
+rows, no cap) and as a digest line in `.prefetch.md` with
+`keys: ["table_name","column_name"]`.
+
+Historical note: `nodes` does not have a `path` column — routes store their
+endpoint under `name` (as `"METHOD /path"`), and the file path is
+`file_path`. Observed during a 2026-04-27 dogfood when subagent prompts
+blindly referenced `path` and hit a Binder Error on an otherwise fresh
+graph. The preflight prevents this class of bug across every subagent.
+
+## Phase 0 algorithm (pseudocode)
+
+Steps marked `# wave 0a` and `# wave 0b` each run as a single parallel tool-use batch — every line inside a wave issues concurrently in one message.
+
+```
+# wave 0a — independent precompute (one parallel batch)
+1.  staleness = list_repos → entry for this repo → _meta.codehub/staleness
+2.  profile = project_profile({repo})
+3.  schema = sql("SELECT table_name, column_name FROM information_schema.columns …")
+4.  routes = route_map({repo})
+5.  tools = tool_map({repo})
+6.  deps = dependencies({repo})
+7.  risk = risk_trends({repo})
+8.  dead = list_dead_code({repo})
+9.  findings = list_findings({repo})
+10. if --group: group_manifest = group_list
+                group_freshness = group_status({group})
+                group_contracts_matrix = group_contracts({group})
+                // precondition check: every member fresh; abort otherwise
+
+# wave 0b — depends on schema + profile (one parallel batch)
+11. communities = sql("SELECT … FROM nodes WHERE kind='Community' …")
+12. processes   = sql("SELECT … FROM nodes WHERE kind='Process' …")
+13. relations   = sql("SELECT … FROM relations …")   # for diagrams
+14. top_folders = top-5 folders by file count (from profile.entryPoints + glob)
+15. owners_summary = [owners({path}) for path in top_folders]
+16. if --group: group_hits = group_query({group, canonical_terms})
+
+# wave 0c — inline deterministic post-processing (no MCP calls)
+17. write .context.md (enforce 200-line cap; truncate per-section, mark flags)
+18. write .prefetch.md (one JSON line per tool call with sha256 of response)
+```
+
+The algorithm is **deterministic** given the same `graph_hash` — the file list and section structure are identical across runs; only the exact content varies.