@opencodehub/cli 0.2.2 → 0.2.3

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-analysis-ownership.md

@@ -0,0 +1,101 @@
+---
+role: doc-analysis-ownership
+model: sonnet
+output: "{{ docs_root }}/analysis/ownership.md"
+depends_on:
+  - "{{ context_path }}"
+  - "{{ prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ repo }} · analysis/ownership.md
+
+## 1. Objective
+
+Produce `{{ docs_root }}/analysis/ownership.md`: a ranked table of folders in `{{ repo }}` by top-contributor share, followed by a `## Single points of failure` H2 listing paths where the top owner holds > 70% of commits — each SPOF row gets a one-sentence mitigation suggestion.
+
+## 2. Scope
+
+- Create: `{{ docs_root }}/analysis/ownership.md`
+- Do not touch: `{{ docs_root }}/analysis/risk-hotspots.md`, `{{ docs_root }}/analysis/dead-code.md`, any other file under `{{ docs_root }}/`, any source file in the repo, `.context.md`, `.prefetch.md`, or any `.packets/*.md` other than this one.
+
+## 3. Input specification
+
+| Source | Read how | Cache state |
+|---|---|---|
+| Shared context | `Read {{ context_path }}` | always first |
+| Prefetch ledger | `Read {{ prefetch_path }}` | always first |
+| Owners summary | `{{ context_path }} § Owners summary` | cached |
+| Owners per folder | `{{ prefetch_path }} § owners` or `mcp__opencodehub__owners({path: <folder>})` | cached when present |
+| Folder roster | `mcp__opencodehub__sql({query: "SELECT DISTINCT file_path FROM nodes WHERE kind='File'"})` + folder-prefix grouping | mid-run, only if `.context.md` roster is truncated |
+| Top-contributor share | `owners` response field `share` | cached or mid-run |
+
+## 4. Process
+
+1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm Owners summary and cached owners digest.
+2. Build the folder roster: use `.context.md § Owners summary` when it enumerates folders; otherwise group `File` nodes by top-level folder prefix (`packages/<x>/src`, `src/<module>`, etc.).
+3. For each folder (top 15 by file count): resolve top owner and share from `{{ prefetch_path }} § owners` when present, else call `mcp__opencodehub__owners({path: <folder>})`. Capture top owner, share %, total contributors.
+4. Rank folders by top-owner share, descending. Draft the ranking table with columns `Folder | Top owner | Share | Total contributors`. Every Folder cell is a backtick path.
+5. Identify Single Points of Failure: folders or files where the top owner's share is > 70%. For each SPOF: draft a bullet under the `## Single points of failure` H2 stating the path, the owner's share percentage, and a one-sentence mitigation (pair reviewer, knowledge-transfer session, cross-training target, etc.).
+6. Draft the intro (1-2 paragraphs): what "share" means (commit share, not line share), the window, and what a > 70% share signals for bus factor.
+7. `Write {{ docs_root }}/analysis/ownership.md` with H1 = `{{ repo }} · Ownership`.
+
+## 5. Document format rules
+
+- H1 = `{{ repo }} · Ownership`. No decorative titles.
+- No YAML frontmatter on the output file.
+- Ranking table has exactly these columns: `Folder | Top owner | Share | Total contributors`.
+- Every folder cell is a backtick `path`. Share is a whole-percent integer (e.g., `72%`).
+- `## Single points of failure` exists as an H2 (not H3, not subsection).
+- Each SPOF bullet follows the shape `` - `path` — owner (N%). <one-sentence mitigation>. ``.
+- No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Contributor share per folder | `mcp__opencodehub__owners` | authoritative over git-blame |
+| Cached owners digest | `{{ prefetch_path }} § owners` | precomputed; do not re-call for cached paths |
+| Folder roster | `{{ context_path }} § Owners summary` | precomputed |
+| Folder roster (fallback) | `mcp__opencodehub__sql` over `File` nodes | only when `.context.md` slice is truncated |
+
+## 7. Fallback paths
+
+- If `mcp__opencodehub__owners` fails for a path: cite the top-3 authors from a manual git-log walk and mark the row `*git-log fallback*` in the Top owner cell.
+- If `.context.md § Owners summary` is absent: use the `sql` folder roster and call `owners` per folder. Cite the fallback in the Work log.
+- If no folder crosses the > 70% threshold: still emit the `## Single points of failure` H2 with a single line `No folders exceed the 70% bus-factor threshold.` — the H2 must exist for Phase E cross-references.
+- If owners data is completely missing (new repo, shallow clone): write the gap to the Work log, skip the Write step, and do not emit an empty file with a single-row table.
+
+## 8. Success criteria
+
+- [ ] `{{ docs_root }}/analysis/ownership.md` exists on disk.
+- [ ] H1 line reads `# {{ repo }} · Ownership`.
+- [ ] The ranking table has at least 5 rows.
+- [ ] Every folder row has a backtick `path` in the Folder column.
+- [ ] Every Share cell is a whole-percent integer.
+- [ ] A single `## Single points of failure` H2 exists (always present, even when empty).
+- [ ] Every SPOF bullet includes a one-sentence mitigation suggestion.
+- [ ] No SPOF lists an owner whose share ≤ 70% (verify each bullet).
+- [ ] No YAML frontmatter on the output.
+
+## 9. Anti-goals
+
+- Do not re-call `owners` for paths already cached in `.prefetch.md`. Read the cached slice first.
+- Do not invent contributor names or percentage shares — every name/number must come from `owners` output or the git-log fallback.
+- Do not drop the `## Single points of failure` H2 even when no folder crosses 70% — emit the empty-state line instead.
+- Do not write YAML frontmatter on the output file.
+- Do not emit emojis.
+
+---
+
+## Work log
+
+{{ subagent fills this section per the write protocol }}
+
+## Validation
+
+{{ checks run, outputs pasted, any fixes applied }}
+
+## Summary
+
+{{ one paragraph — what shipped, how many SPOFs surfaced, and any folders that required a git-log fallback }}

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-analysis-risk-hotspots.md

@@ -0,0 +1,105 @@
+---
+role: doc-analysis-risk-hotspots
+model: sonnet
+output: "{{ docs_root }}/analysis/risk-hotspots.md"
+depends_on:
+  - "{{ context_path }}"
+  - "{{ prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ repo }} · analysis/risk-hotspots.md
+
+## 1. Objective
+
+Produce `{{ docs_root }}/analysis/risk-hotspots.md`: a ranked table of the top 12 files in `{{ repo }}` by combined risk score (30-day trend slope + current finding severity), followed by a `## Per-file drill-down` section with one H3 per top-5 hotspot covering what's there, recent activity, owners, and open findings.
+
+## 2. Scope
+
+- Create: `{{ docs_root }}/analysis/risk-hotspots.md`
+- Do not touch: `{{ docs_root }}/analysis/ownership.md`, `{{ docs_root }}/analysis/dead-code.md`, any other file under `{{ docs_root }}/`, any source file in the repo, `.context.md`, `.prefetch.md`, or any `.packets/*.md` other than this one.
+
+## 3. Input specification
+
+| Source | Read how | Cache state |
+|---|---|---|
+| Shared context | `Read {{ context_path }}` | always first |
+| Prefetch ledger | `Read {{ prefetch_path }}` | always first |
+| Owners summary | `{{ context_path }} § Owners summary` | cached |
+| Risk trends | `mcp__opencodehub__risk_trends({repo: "{{ repo }}", window_days: 30})` | mid-run |
+| Current findings | `mcp__opencodehub__list_findings({repo: "{{ repo }}", severity: ">=warn"})` | mid-run |
+| Owners per hotspot | `mcp__opencodehub__owners({path: <file>})` or `{{ prefetch_path }} § owners` | cached when present |
+| Verdict context (optional) | `mcp__opencodehub__verdict({repo: "{{ repo }}"})` | mid-run, optional |
+
+## 4. Process
+
+1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm the Owners summary and any cached findings/trend digests.
+2. Call `mcp__opencodehub__risk_trends({repo: "{{ repo }}", window_days: 30})`. Record the per-community / per-file trend slope (`↑ rising`, `→ flat`, `↓ falling`).
+3. Call `mcp__opencodehub__list_findings({repo: "{{ repo }}", severity: ">=warn"})`. Group findings by `file_path`; compute `N warn, M error` counts per file.
+4. Combine trend slope + severity into a risk score and rank files. Pick the top 12 for the ranking table; the top 5 feed the drill-down.
+5. For each top-12 file: resolve the top owner from `{{ prefetch_path }} § owners` when present, else `mcp__opencodehub__owners({path: <file>})`. Capture percentage share.
+6. Draft the ranked table with columns `File | Trend | Open findings | Top owner | Citation`. Every row cites the file as a backtick `path` with an optional `(N LOC)` suffix; every `Open findings` cell derives from `list_findings` output only.
+7. Draft the intro (2 paragraphs): what "risk" means here, how the scoring is composed, the window. If `risk_trends` returned `status: "insufficient_history"`, note the limitation in the intro and drop the Trend column.
+8. Draft the `## Per-file drill-down` section. One H3 per top-5 hotspot. Each H3 covers: What's there (2-sentence summary from `context`/`Read`), Recent activity (from `risk_trends`), Owners (top 1-2 with percentage share), Findings (counts by severity, each cited to `list_findings`).
+9. `Write {{ docs_root }}/analysis/risk-hotspots.md` with H1 = `{{ repo }} · Risk hotspots`.
+
+## 5. Document format rules
+
+- H1 = `{{ repo }} · Risk hotspots`. No decorative titles.
+- No YAML frontmatter on the output file.
+- Ranking table has exactly these columns: `File | Trend | Open findings | Top owner | Citation`.
+- Every ranking row cites the file via a backtick `path` in the Citation column.
+- Trend column uses `↑ rising` / `→ flat` / `↓ falling` arrows — do not invent other symbols.
+- Drill-down uses H3s (not H2s) under the single `## Per-file drill-down` H2.
+- Owner shares use whole-percent integers (e.g., `68%`), not decimals.
+- No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Risk over time | `mcp__opencodehub__risk_trends` | slope + severity, pre-computed |
+| Open findings per file | `mcp__opencodehub__list_findings` | grouped by path; merges scanners |
+| Contributor share per path | `mcp__opencodehub__owners` | authoritative over git-blame |
+| Hotspot context / summary | `mcp__opencodehub__context` | inbound/outbound for the 2-sentence summary |
+| Severity framing (optional) | `mcp__opencodehub__verdict` | optional — frames the intro severity |
+
+## 7. Fallback paths
+
+- If `risk_trends` returns `status: "insufficient_history"`: drop the Trend column from the ranking table, rank by `list_findings` severity alone, and state the limitation in the 2-paragraph intro. Cite the fallback in the Work log.
+- If `owners` fails for a path: fall back to the cached owners digest in `.prefetch.md` if present; otherwise do a manual git-log walk and mark the row `*git-log fallback*` in the Top owner cell.
+- If `list_findings` returns `[]` for the repo: keep the ranking table but drop the Open findings column, rank by trend slope alone, and state the absence in the intro. Cite the fallback in the Work log.
+- If fewer than 10 files qualify after ranking: lower the threshold to include the full eligible set, note the shortfall in the intro, and still satisfy the ≥ 10-row success criterion by including lower-risk rows.
+
+## 8. Success criteria
+
+- [ ] `{{ docs_root }}/analysis/risk-hotspots.md` exists on disk.
+- [ ] H1 line reads `# {{ repo }} · Risk hotspots`.
+- [ ] The ranking table has at least 10 rows.
+- [ ] Every ranking row has a backtick path citation in the Citation column.
+- [ ] A single `## Per-file drill-down` H2 exists, containing 5 H3s.
+- [ ] Every H3 under drill-down cites at least 2 `path:LOC` references (What's there + Findings).
+- [ ] Every `Open findings` cell count matches a `list_findings` grouping (spot-check 3).
+- [ ] No YAML frontmatter on the output.
+
+## 9. Anti-goals
+
+- Do not re-call any tool whose digest is already cached in `.prefetch.md` (owners, findings grouping, process list). Read the cached slice first.
+- Do not invent finding counts, owner names, or severity numbers — every number must map to a `list_findings` row or an `owners` response.
+- Do not reorder the ranking columns; the downstream README expects the fixed schema.
+- Do not write YAML frontmatter on the output file.
+- Do not emit emojis.
+
+---
+
+## Work log
+
+{{ subagent fills this section per the write protocol }}
+
+## Validation
+
+{{ checks run, outputs pasted, any fixes applied }}
+
+## Summary
+
+{{ one paragraph — what shipped, any fallbacks invoked, and which files made the top-5 drill-down }}

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-architecture-data-flow.md

@@ -0,0 +1,103 @@
+---
+role: doc-architecture-data-flow
+model: sonnet
+output: "{{ docs_root }}/architecture/data-flow.md"
+depends_on:
+  - "{{ context_path }}"
+  - "{{ prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ repo }} · architecture/data-flow.md
+
+## 1. Objective
+
+Produce `{{ docs_root }}/architecture/data-flow.md`: a walk of the top 3 processes in `{{ repo }}`, each rendered as numbered steps plus one Mermaid `sequenceDiagram`. Every step cites `` `path:LOC` `` for the function that advances the flow.
+
+## 2. Scope
+
+- Create: `{{ docs_root }}/architecture/data-flow.md`
+- Do not touch: any other file under `{{ docs_root }}/`, any source file in the repo, `.context.md`, `.prefetch.md`, or any `.packets/*.md` other than this one.
+
+## 3. Input specification
+
+| Source | Read how | Cache state |
+|---|---|---|
+| Shared context | `Read {{ context_path }}` | always first |
+| Prefetch ledger | `Read {{ prefetch_path }}` | always first |
+| Top processes | `{{ context_path }} § Top processes` | cached |
+| Process entry points | `{{ prefetch_path }} § entry points` or `mcp__opencodehub__sql({query: "SELECT p.name, n.name AS entry_name, n.file_path, n.start_line FROM nodes p JOIN nodes n ON p.entry_point_id = n.id WHERE p.kind='Process'"})` | cached if digest present |
+| Symbol neighborhoods along each flow | `mcp__opencodehub__context({symbol: <id>})` | mid-run (only if cache miss) |
+| Query grounding for ambiguous steps | `mcp__opencodehub__query({text: "<concept>", limit: 10})` | mid-run (only if cache miss) |
+| Source spans for step citations | `Read <file>` over `start_line..start_line+20` | mid-run |
+
+## 4. Process
+
+1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Lock the ordered list of top processes; pick the top 3.
+2. For each selected process, pull the entry point from `.prefetch.md § entry points`. If absent, call the `sql` query in the input spec and cache the digest in this packet's Work log.
+3. For each flow, walk from the entry point outward using `context({symbol: <entry>})` (reuse cached digest if present). Record the ordered call chain: caller → callee → downstream participant. Cap at 8 steps per flow.
+4. Resolve each participant to a logical actor (CLI, MCP server, Analysis, Storage, etc.) by cross-referencing its file path against `.context.md § Top communities`. Use the community `inferred_label` as the `participant` name in the Mermaid diagram.
+5. For every step, `Read` the source span at `path:start_line-start_line+20` to confirm the function exists and extract the one-line description. Do not paraphrase beyond that.
+6. Draft the H2 block per flow: `## Flow N: <process-name>`, followed by numbered steps (each citing `` `path:LOC` ``), then a fenced ` ```mermaid ` block containing one `sequenceDiagram`.
+7. `Write {{ docs_root }}/architecture/data-flow.md` with H1 = `{{ repo }} · Data flow`, at most 3 `## Flow N:` H2 sections.
+
+## 5. Document format rules
+
+- H1 = `{{ repo }} · Data flow`. No decorative titles.
+- No YAML frontmatter on the output file.
+- One H2 per flow, in the form `## Flow N: <process-name>`. Maximum 3 H2 flow sections.
+- Each flow body = numbered step list (Markdown ordered list) + exactly one `sequenceDiagram` fenced with ` ```mermaid `.
+- Every numbered step cites `` `path:LOC` ``; the entry-point step must cite the function, not the file.
+- `sequenceDiagram` participants use short labels (≤ 20 chars); participant names must match the community `inferred_label` (or process actor names from `.context.md`).
+- No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Process list + entry points | `{{ context_path }} § Top processes` + `{{ prefetch_path }}` | precomputed; do not re-call `sql` |
+| Symbol neighborhood for call chain | `mcp__opencodehub__context` | inbound/outbound relations grounded in the graph |
+| Concept grounding when a step is ambiguous | `mcp__opencodehub__query` | hybrid BM25+vector, process-grouped |
+| Verifying step text | `Read` at `path:start_line-start_line+20` | avoid paraphrase drift |
+
+## 7. Fallback paths
+
+- If `.context.md § Top processes` lists fewer than 3 processes: render only the processes present. Do not pad with synthetic flows.
+- If a process has no `entry_point_id`: fall back to `query({text: "<process-name> entry", limit: 5})`, pick the highest-ranked symbol, and mark the step `*entry inferred*`.
+- If a `context` call errors mid-chain: truncate the flow at the last verified step and append `> _flow truncated: downstream context unavailable_` under the numbered list. Still emit the `sequenceDiagram` using the verified subset.
+- If a participant's community has no `inferred_label`: use the top-level folder name as the participant label and note the substitution in the Work log.
+
+## 8. Success criteria
+
+- [ ] `{{ docs_root }}/architecture/data-flow.md` exists on disk.
+- [ ] H1 line reads `# {{ repo }} · Data flow`.
+- [ ] Between 1 and 3 H2 sections match `^## Flow \d+:` (verify with grep).
+- [ ] Exactly one ` ```mermaid ` fence per flow section; each fence contains `sequenceDiagram` as the first non-empty line.
+- [ ] Every numbered step has a backtick `` `path:LOC` `` citation (grep each ordered-list line for `` ` ``).
+- [ ] The number of `` `mermaid `` fences equals the number of `## Flow` H2 sections.
+- [ ] No `sequenceDiagram` participant label exceeds 20 characters.
+- [ ] No YAML frontmatter on the output.
+- [ ] No `path:LOC` citation references a file that does not exist (spot-check 3).
+
+## 9. Anti-goals
+
+- Do not re-call any MCP tool whose digest is in `.prefetch.md` — read the cached summary. If the cached slice is truncated, call with a narrower filter, not a blanket re-fetch.
+- Do not invent process names, participants, or call edges — every step must map to a cached relation or a verified `Read` span.
+- Do not write YAML frontmatter on the output file.
+- Do not emit more than 3 `sequenceDiagram` blocks — overflow is for a separate packet.
+- Do not emit emojis. Do not use filler adverbs.
+- Do not paraphrase step bodies beyond a one-line summary of the quoted source span.
+
+---
+
+## Work log
+
+{{ subagent fills this section per the write protocol }}
+
+## Validation
+
+{{ checks run, outputs pasted, any fixes applied }}
+
+## Summary
+
+{{ one paragraph — what shipped, where, why the flow selection went the way it did }}

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-architecture-module-map.md

@@ -0,0 +1,102 @@
+---
+role: doc-architecture-module-map
+model: sonnet
+output: "{{ docs_root }}/architecture/module-map.md"
+depends_on:
+  - "{{ context_path }}"
+  - "{{ prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ repo }} · architecture/module-map.md
+
+## 1. Objective
+
+Produce `{{ docs_root }}/architecture/module-map.md`: one H2 per top module, each with a one-paragraph description and a bullet list of the module's top 8 files cited as `` `path:LOC` `` with `(N LOC)` suffix.
+
+## 2. Scope
+
+- Create: `{{ docs_root }}/architecture/module-map.md`
+- Do not touch: any other file under `{{ docs_root }}/`, any source file in the repo, `.context.md`, `.prefetch.md`, or any `.packets/*.md` other than this one.
+
+## 3. Input specification
+
+| Source | Read how | Cache state |
+|---|---|---|
+| Shared context | `Read {{ context_path }}` | always first |
+| Prefetch ledger | `Read {{ prefetch_path }}` | always first |
+| Top communities | `{{ context_path }} § Top communities` | cached |
+| Community member files | `{{ prefetch_path }} § community members` or `mcp__opencodehub__sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='File' AND community_id = <id> ORDER BY file_path"})` | cached if digest present |
+| Community relations | `mcp__opencodehub__context({symbol: <community-name>})` per module | mid-run (only if cache miss) |
+| File LOC | `Read <file>` then count lines | mid-run |
+
+## 4. Process
+
+1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm `{{ repo }}` profile and the ordered list of top communities.
+2. For each of the top 8 communities, pull the member file list from `.prefetch.md § community members`. If absent, call `sql({query: "SELECT name, file_path, start_line FROM nodes WHERE kind='File' AND community_id = <id> ORDER BY file_path LIMIT 50"})` and cache the digest in this packet's Work log.
+3. For each module, rank files by semantic weight (inbound relation count from cached `context` digest if present, else alphabetical fallback). Keep the top 8.
+4. For every file in the shortlist, `Read` it to compute LOC. Record `path:LOC` + total line count per file in the packet Work log.
+5. Draft the one-paragraph description per module. Anchor the paragraph on the module's `inferred_label` and its highest-weight file, each cited `` `path:LOC` ``.
+6. Collapse any module with fewer than 3 files into a trailing `## Supporting code` H2 that lists those files as flat bullets.
+7. `Write {{ docs_root }}/architecture/module-map.md` with H1 = `{{ repo }} · Module map` and one H2 per module in top-community order.
+
+## 5. Document format rules
+
+- H1 = `{{ repo }} · Module map`. No decorative titles.
+- No YAML frontmatter on the output file.
+- One H2 per module. The H2 text is the community `inferred_label` (or its canonical name if no label).
+- Each module H2 is followed by: one paragraph (≤ 4 sentences) + a bullet list of the top 8 files.
+- Every bullet is a `` `path` `` reference with a trailing `(N LOC)`; every paragraph claim has a `` `path:LOC` `` citation.
+- A trailing `## Supporting code` H2 collects modules with < 3 files as flat bullets.
+- No Mermaid. No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Module list | `{{ context_path }} § Top communities` | precomputed; do not re-call `sql` |
+| Community member files | `{{ prefetch_path }}` or `sql` over `nodes WHERE kind='File' AND community_id=...` | authoritative member set |
+| Module relation counts | `mcp__opencodehub__context` | already cached for top-6 by system-overview packet; reuse digest |
+| File LOC | `Read` then line count | graph does not store LOC |
+
+## 7. Fallback paths
+
+- If `.context.md § Top communities` is empty: fall back to `sql({query: "SELECT file_path FROM nodes WHERE kind='File' ORDER BY file_path LIMIT 500"})`, group by top-level folder, and treat each folder as a synthetic module. Note the fallback in the Work log.
+- If a community's member list is empty: list the community under `## Supporting code` with an `*unresolved*` marker and cite the community node's `file_path` prefix only.
+- If `Read` fails for a file (missing or binary): drop it from the bullet list and log the skip in the Work log. Do not invent a LOC count.
+- If more than 12 communities are seeded: keep the top 8 as full H2 sections and append the remainder as one-line rows under `## Supporting code`.
+
+## 8. Success criteria
+
+- [ ] `{{ docs_root }}/architecture/module-map.md` exists on disk.
+- [ ] H1 line reads `# {{ repo }} · Module map`.
+- [ ] At least 3 H2 sections are present (count `^## ` matches, excluding `## Supporting code`).
+- [ ] Every H2 is followed by a paragraph with at least one `` `path:LOC` `` citation.
+- [ ] Every file bullet has the form `` `path` (N LOC) `` — verify with a grep for `(\d+ LOC)` on every bullet line.
+- [ ] No file bullet references a path that does not exist on disk (spot-check 3).
+- [ ] No module lists more than 8 bulleted files (supporting-code dump excluded).
+- [ ] No YAML frontmatter on the output.
+- [ ] No Mermaid fences in the output.
+
+## 9. Anti-goals
+
+- Do not re-call any MCP tool whose digest is in `.prefetch.md` — read the cached summary. If the cached slice is truncated, call with a narrower filter, not a blanket re-fetch.
+- Do not invent module names, file paths, or LOC counts — every identifier must come from a tool response or a `Read` of the source file.
+- Do not write YAML frontmatter on the output file.
+- Do not emit Mermaid diagrams in this file — the flowchart belongs to `architecture/system-overview.md`.
+- Do not emit emojis. Do not use filler adverbs.
+- Do not exceed 8 file bullets per module; overflow belongs in `## Supporting code`.
+
+---
+
+## Work log
+
+{{ subagent fills this section per the write protocol }}
+
+## Validation
+
+{{ checks run, outputs pasted, any fixes applied }}
+
+## Summary
+
+{{ one paragraph — what shipped, where, why the module ordering went the way it did }}

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-architecture-system-overview.md

@@ -0,0 +1,100 @@
+---
+role: doc-architecture-system-overview
+model: sonnet
+output: "{{ docs_root }}/architecture/system-overview.md"
+depends_on:
+  - "{{ context_path }}"
+  - "{{ prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ repo }} · architecture/system-overview.md
+
+## 1. Objective
+
+Produce `{{ docs_root }}/architecture/system-overview.md`: a 400–600-word narrative of what `{{ repo }}` does and how its top-level pieces fit, with one stack table and one Mermaid `flowchart LR` of the top 6 modules.
+
+## 2. Scope
+
+- Create: `{{ docs_root }}/architecture/system-overview.md`
+- Do not touch: any other file under `{{ docs_root }}/`, any source file in the repo, `.context.md`, `.prefetch.md`, or any `.packets/*.md` other than this one.
+
+## 3. Input specification
+
+| Source | Read how | Cache state |
+|---|---|---|
+| Shared context | `Read {{ context_path }}` | always first |
+| Prefetch ledger | `Read {{ prefetch_path }}` | always first |
+| Project profile | `{{ context_path }} § Repo profile` | cached |
+| Top communities | `{{ context_path }} § Top communities` | cached |
+| Top processes | `{{ context_path }} § Top processes` | cached |
+| External deps | `{{ context_path }} § Stack` or `mcp__opencodehub__dependencies({repo: "{{ repo }}"})` | cached if digest present |
+| Module relations | `mcp__opencodehub__context({symbol: <community-name>})` per top 6 modules | mid-run |
+
+## 4. Process
+
+1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm `{{ repo }}` profile, top-6 community names, top processes.
+2. For each of the top 6 communities (from `.context.md § Top communities`): call `mcp__opencodehub__context({symbol: <community-name>})` to pull inbound/outbound relation counts. Cache the summary in this packet's Work log.
+3. Pull the external dependencies list from `.context.md § Stack` (or call `dependencies` if not cached). Keep the top 15 by usage.
+4. Resolve the stack layers by inspecting `project_profile.entry_points` and cross-referencing the top communities with their `file_path` prefixes.
+5. Draft the narrative (400–600 words). Structure: paragraph 1 = what the repo does, paragraph 2 = how the pieces fit.
+6. Draft the Stack table with columns `Layer | Technology | Source`. Every row cites `path:LOC`.
+7. Draft the Module-map Mermaid `flowchart LR` — ≤ 20 nodes, short labels (≤ 20 chars), edges from relation counts ≥ 1.
+8. `Write {{ docs_root }}/architecture/system-overview.md` with H1 = `{{ repo }} · System overview`.
+
+## 5. Document format rules
+
+- H1 = `{{ repo }} · System overview`. No decorative titles.
+- No YAML frontmatter on the output file.
+- Every factual claim has a backtick `path:LOC` citation; file-level cites append ` (N LOC)`.
+- Mermaid fenced with ` ```mermaid `. Exactly one diagram.
+- No emojis. No filler adverbs.
+- Stack table has 3 columns exactly: `Layer | Technology | Source`.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Module list + cohesion | `{{ context_path }} § Top communities` | precomputed; do not re-call `sql` |
+| Symbol neighborhood | `mcp__opencodehub__context` | inbound/outbound + cochange counts |
+| External dependency list | `{{ context_path }} § Stack` or `dependencies` | authoritative over grepping manifests |
+| File line count for `(N LOC)` | `Read` then line count | graph does not store LOC |
+
+## 7. Fallback paths
+
+- If `.context.md § Top communities` is empty: fall back to `sql({query: "SELECT name, file_path FROM nodes WHERE kind='File' ORDER BY file_path LIMIT 200"})` and group by top-level folder. Cite the fallback in the Work log.
+- If a community's `context` call errors: list the module in the Mermaid diagram but omit its relation counts from the narrative; mark the narrative line `*context unavailable*`.
+- If `dependencies` is unavailable and `.context.md` lacks a Stack section: `Read` the root `package.json` / `Cargo.toml` / `pyproject.toml`, extract the top 15 deps by semantic weight. Mark the Source column `*manifest fallback*`.
+
+## 8. Success criteria
+
+- [ ] `{{ docs_root }}/architecture/system-overview.md` exists on disk.
+- [ ] H1 line reads `# {{ repo }} · System overview`.
+- [ ] Narrative is 400–600 words (use `wc -w` to verify).
+- [ ] Stack table has ≥ 5 rows, every row cites `path:LOC`.
+- [ ] Exactly one Mermaid ` ```mermaid ` fence containing a `flowchart LR`.
+- [ ] Mermaid diagram has 3–20 nodes with labels ≤ 20 chars.
+- [ ] No YAML frontmatter on the output.
+- [ ] No `path:LOC` citation references a file that does not exist (spot-check 3).
+
+## 9. Anti-goals
+
+- Do not re-call `project_profile` or `sql` over communities — those are cached in `.context.md` / `.prefetch.md`.
+- Do not invent community or module names — every node in the Mermaid diagram must map to a row in `.context.md § Top communities`.
+- Do not write YAML frontmatter on the output file.
+- Do not emit more than one Mermaid diagram.
+- Do not exceed 600 words in the narrative; if analysis is longer, move extra detail to `module-map.md` (which another packet produces).
+
+---
+
+## Work log
+
+{{ subagent fills this section per the write protocol }}
+
+## Validation
+
+{{ checks run, outputs pasted, any fixes applied }}
+
+## Summary
+
+{{ one paragraph — what shipped, where, why the module selection went the way it did }}

package/dist/plugin-assets/skills/codehub-document/templates/agents/doc-behavior-processes.md

@@ -0,0 +1,103 @@
+---
+role: doc-behavior-processes
+model: sonnet
+output: "{{ docs_root }}/behavior/processes.md"
+depends_on:
+  - "{{ context_path }}"
+  - "{{ prefetch_path }}"
+status: IN_PROGRESS
+---
+
+# Packet · {{ repo }} · behavior/processes.md
+
+## 1. Objective
+
+Produce `{{ docs_root }}/behavior/processes.md`: one H2 per top process in `{{ repo }}`, each with a numbered step list citing `path:LOC` on every line, entry-point attribution (HTTP route / MCP tool / CLI command / scheduled job), and a `### Related` subsection with backtick citations to handler files.
+
+## 2. Scope
+
+- Create: `{{ docs_root }}/behavior/processes.md`
+- Do not touch: `{{ docs_root }}/behavior/state-machines.md`, any other file under `{{ docs_root }}/`, any source file in the repo, `.context.md`, `.prefetch.md`, or any `.packets/*.md` other than this one.
+
+## 3. Input specification
+
+| Source | Read how | Cache state |
+|---|---|---|
+| Shared context | `Read {{ context_path }}` | always first |
+| Prefetch ledger | `Read {{ prefetch_path }}` | always first |
+| Top processes | `{{ context_path }} § Top processes` | cached |
+| Route inventory | `{{ prefetch_path }} § route_map` | cached |
+| MCP tool inventory | `{{ prefetch_path }} § tool_map` | cached |
+| Step sequence per process | `mcp__opencodehub__context({symbol: <process-name>})` | mid-run |
+| Disambiguation lookup | `mcp__opencodehub__query({text: "<process name>"})` | mid-run, only on collision |
+
+## 4. Process
+
+1. `Read {{ context_path }}` and `Read {{ prefetch_path }}`. Confirm the Top processes list is present; if empty, follow Fallback paths.
+2. Select the top 8 processes from `.context.md § Top processes` (ranked by `step_count`).
+3. For each of the 8: call `mcp__opencodehub__context({symbol: <process-name>})` to pull entry point, ordered outbound calls, and handler files. Cache the per-process digest in this packet's Work log.
+4. Group each process by its initiator using the cached `route_map` / `tool_map` digest: HTTP route, MCP tool, CLI command, scheduled job, or internal.
+5. Draft `processes.md` with H1 = `{{ repo }} · Processes`. One H2 per process (max 8). Under each H2: a single-line `Entry point: <path:LOC>`, a numbered step list where every step cites `path:LOC`, then a `### Related` subsection listing the top 3-6 handler/helper files as backtick citations.
+6. Processes with fewer than 3 concrete steps collapse into a trailing `## Minor flows` H2 (one bullet per flow, not an H2 section of their own).
+7. `Write {{ docs_root }}/behavior/processes.md`.
+
+## 5. Document format rules
+
+- H1 = `{{ repo }} · Processes`. No decorative titles.
+- No YAML frontmatter on the output file.
+- One H2 per process. Max 8 H2s for full processes; everything else goes under `## Minor flows`.
+- Each H2 opens with `Entry point: <backtick path:LOC>` on its own line.
+- Step list is numbered. Every numbered step ends with a backtick `path:LOC` citation.
+- `### Related` subsection lives at the end of each H2; bullets are backtick citations only (no prose).
+- No emojis. No filler adverbs.
+
+## 6. Tool usage guide
+
+| Need | Tool | Why |
+|---|---|---|
+| Process roster + step counts | `{{ context_path }} § Top processes` | precomputed; do not re-call `sql` |
+| Ordered steps per process | `mcp__opencodehub__context` | outbound edges + ordering hints |
+| Initiator attribution | `{{ prefetch_path }} § route_map` / `§ tool_map` | cached inventories |
+| Disambiguate colliding names | `mcp__opencodehub__query` | only when two symbols share a name |
+| Recover stale graph | `Grep` the repo | fallback when `context` returns nothing |
+
+## 7. Fallback paths
+
+- If a process has fewer than 3 steps in `context`: collapse it into the trailing `## Minor flows` H2 rather than giving it its own section. Cite the collapse in the Work log.
+- If `.context.md § Top processes` is empty: fall back to `mcp__opencodehub__sql({query: "SELECT name, file_path, step_count FROM nodes WHERE kind='Process' ORDER BY step_count DESC LIMIT 8"})`. Cite the fallback in the Work log.
+- If `mcp__opencodehub__query` for a process name returns nothing (graph out of sync): `Grep` the repo for the name and cite the Grep hits with an inline `*graph stale for this process*` note.
+- If `context` errors on a named process: omit the process's step list, keep the H2 as a stub with `*context unavailable — see Grep fallback*`, and enumerate its handler files from `Grep` hits.
+
+## 8. Success criteria
+
+- [ ] `{{ docs_root }}/behavior/processes.md` exists on disk.
+- [ ] H1 line reads `# {{ repo }} · Processes`.
+- [ ] At least 3 H2 entries exist for full processes (not counting `## Minor flows`).
+- [ ] At most 8 full-process H2s exist.
+- [ ] Every numbered step in every process has a backtick `path:LOC` citation.
+- [ ] Every H2 contains a `### Related` subsection with at least 1 backtick citation.
+- [ ] No H2 corresponds to a process name absent from the graph (or from the `Grep` fallback).
+- [ ] No YAML frontmatter on the output.
+
+## 9. Anti-goals
+
+- Do not re-call `sql`, `route_map`, or `tool_map` — those digests are cached in `.context.md` / `.prefetch.md`.
+- Do not invent process names — every H2 must map to a graph node or a `Grep`-verified function.
+- Do not document more than 8 full processes; overflow goes to `## Minor flows`.
+- Do not duplicate steps from handler files in prose form — cite them on a numbered line.
+- Do not write YAML frontmatter on the output file.
+- Do not emit emojis.
+
+---
+
+## Work log
+
+{{ subagent fills this section per the write protocol }}
+
+## Validation
+
+{{ checks run, outputs pasted, any fixes applied }}
+
+## Summary
+
+{{ one paragraph — what shipped, where, and which processes landed in Minor flows vs. their own H2 }}