Schema-consistency fixes from final whole-branch review (#31)

* docs: schema-consistency fixes from final whole-branch review

* docs: align body-container prose with L1 origin

Author: rahlk

README.md

@@ -24,8 +24,9 @@ the dispatcher automatically (see [How the hook behaves](#how-the-hook-behaves)
 
 The diagram and routing table below are copied verbatim from the dispatcher skill,
 [`using-cldk-devtools`](skills/using-cldk-devtools/SKILL.md) — the same ones an agent reads
-before acting on any codellm-devkit repo. Keep the two in sync; the consistency check in
-`tests/` diffs them.
+before acting on any codellm-devkit repo. Keep the two in sync;
+[`tests/consistency/check-readme-dispatcher-sync.sh`](tests/consistency/check-readme-dispatcher-sync.sh)
+diffs them.
 
 ```
                      using-cldk-devtools  (dispatcher)
@@ -158,6 +159,7 @@ tests/
   scenarios/               # per-skill prompts used to test routing and gates
   baselines/               # RED (no-skill) vs. GREEN (with-skill) evidence, ladder dry-runs
   hooks/                   # hook behavior tests
+  consistency/             # README/dispatcher-skill sync checks
 ```
 
 ## How the hook behaves

skills/cldk-sdk-frontend/references/schema-contract.md

@@ -27,7 +27,8 @@ callers are unchanged.
 ## The schema shape the models load
 
 - **Root is an envelope, not `Application`.** `{ schema_version, language, max_level,
-  k_limit?, application }`. `max_level` is authoritative — read it; never sniff for keys.
+  k_limit?, analyzer{name,version}, application }`. `max_level` is authoritative — read it;
+  never sniff for keys.
 - **`application`** = `{ id: can://<lang>/<app>, kind, symbol_table{path→module},
   call_graph[], param_in[], param_out[] }`. `symbol_table` and `call_graph` live
   **inside** `application`.
@@ -101,8 +102,12 @@ class Application(_NullSafeBase):
     id: str; kind: Literal["application"]="application"
     symbol_table: Dict[str, Module]; call_graph: List[Edge]=[]; param_in: List[Edge]=[]; param_out: List[Edge]=[]
 
+class Analyzer(_NullSafeBase):
+    name: str; version: str
+
 class AnalysisPayload(_NullSafeBase):   # the envelope / manifest — .application is the tree
-    schema_version: str; language: str; max_level: int; k_limit: Optional[int]=None; application: Application
+    schema_version: str; language: str; max_level: int; k_limit: Optional[int]=None
+    analyzer: Optional[Analyzer]=None; application: Application
 ```
 
 Prefer a single `Node` with a **string** `kind` over per-language subclasses or a rigid

skills/codeanalyzer-backend/references/level-2-call-graph.md

@@ -63,7 +63,7 @@ source node's props.
 Run the analyzer at `-a 2` on the fixture and confirm all of:
 
 - **No dangling endpoints** — every edge `src` and `dst` resolves to a real callable id in the symbol
-  table (`for e in call_graph: assert e.src in all_sigs and e.dst in all_sigs`);
+  table (`for e in call_graph: assert e.src in all_ids and e.dst in all_ids`);
 - every edge has a **non-empty `prov`** naming the resolver;
 - **`callee` is backfilled** (non-null id) on successfully resolved call sites, and still `null` on
   the honest-unresolved ones;

skills/codeanalyzer-backend/references/testing-and-validation.md

@@ -66,8 +66,8 @@ Run each level's gate on the fixture; do not build the next level until the curr
    non-eager run.
 
 ### L2 — call-graph gate (`-a 2`)
-1. Every edge endpoint matches a real signature — `for e in call_graph: assert e.src in all_sigs and
-   e.dst in all_sigs` (no dangling).
+1. Every edge endpoint matches a real `can://` id — `for e in call_graph: assert e.src in all_ids and
+   e.dst in all_ids` (no dangling).
 2. Every edge has a **non-empty `prov`** naming the resolver.
 3. **`callee` backfilled** (non-null id) on resolved sites; still `null` on honest-unresolved ones.
 4. A **named expected edge** present (exact `(src, dst)`), plus at least one **cross-package** edge.

skills/designing-cldk-changes/SKILL.md

@@ -13,7 +13,7 @@ shared contract or spans repos — is designed here, as a spec plus a GitHub epi
 ## Entry Preconditions
 
 You are here because the work is structural: a new language, schema v2
-evolution/migration, a new analysis level (L3/L4), a new SDK facade surface, or
+evolution/migration, a new analysis level (L2/L3/L4), a new SDK facade surface, or
 any cross-repo feature. If it arrived as a "small fix" that turned out to move
 the schema v2 output or the public SDK API, **maintaining-cldk**'s contract gate
 escalated it here — say so and continue; it is now a structural change, not a fix.
@@ -32,7 +32,7 @@ Then state the change-type → repos-affected mapping:
 | --- | --- | --- | --- |
 | New language | new `codeanalyzer-<lang>` | `python-sdk` (+ TS SDK) | docs |
 | Schema v2 evolution / migration | every affected `codeanalyzer-*` | every affected SDK | docs |
-| New analysis level (L3/L4) | that `codeanalyzer-<lang>` | SDK only if the surface changes | docs |
+| New analysis level (L2/L3/L4) | that `codeanalyzer-<lang>` | SDK only if the surface changes | docs |
 | New facade surface / SDK feature | — | `python-sdk` (+ TS SDK) | docs |
 | Docs-only structural change | — | — | docs |
 

skills/designing-cldk-changes/references/canonical-schema.md

@@ -58,13 +58,14 @@ application                                   ← the root; carries an id
     module: { types{}, functions{} }          ← L1  (per-file / compilation-unit container)
       type: { callables{}, fields{} }         ← L1
         callable: { body{}, cfg[], cdg[], ddg[], summary[] }
-          body: { <local-id>: node }          ← L3+ (statements, then synthetic vertices)
+          body: { <local-id>: node }          ← L1: call nodes; completes at L3
   call_graph[], param_in[], param_out[]       ← cross-function edges, at the application scope
 ```
 
 - **Above the callable**: name-keyed maps (`types`, `functions`, `callables`) — each node
   carries its full `id`.
-- **At the callable**: `body` is the container that grows at L3+. It is a map keyed by the
+- **At the callable**: `body` is the container that exists from L1 (holding the `call` nodes)
+  and completes at L3. It is a map keyed by the
   node's **local id** (a source position `line:col`, or an `@tag` for synthetic vertices).
 - **Edges live at the lowest common ancestor of their endpoints**: intra-callable edges
   (`cfg`/`cdg`/`ddg`/`summary`) hang on the callable; cross-callable edges
@@ -77,17 +78,18 @@ application → file/module → type (class|struct|interface|enum|…) → calla
             → statement (statement|call|return|branch|loop|…) → [expression, opt]
 ```
 
-plus the **synthetic** vertices introduced at L4: `entry`, `exit`, `formal_in`, `formal_out`,
-`actual_in`, `actual_out`. A node is therefore *either an AST region or a synthetic analysis
-vertex*; both fit the tree (synthetic vertices are children of the callable or of a call-site
-statement).
+plus the **synthetic** vertices: `entry`/`exit` introduced at L3, and `formal_in`/`formal_out`/
+`actual_in`/`actual_out` introduced at L4. A node is therefore *either an AST region or a
+synthetic analysis vertex*; both fit the tree (synthetic vertices are children of the callable or
+of a call-site statement).
 
 ## Identity
 
 Two tiers, and the boundary is the **callable leaf line** — the same line where L1 stops.
 
 - **Durable ids (≥ callable)** — files, modules, types, callables get stable
-  `cldk://`-style URIs (grammar in `skills/cldk-sdk-frontend/references/schema-contract.md`) that
+  `can://` URIs (an extension of the upstream `cldk://` RFC grammar; grammar in
+  `skills/cldk-sdk-frontend/references/schema-contract.md`) that
   survive re-analysis and are what external tools (SCIP export, cross-repo joins) address. The grammar
   is a **containment path** with an application segment so multiple apps in one language don't
   collide:
@@ -214,6 +216,7 @@ Building **both** is a first-class deliverable for every analyzer, not an aftert
 ```jsonc
 {
   "schema_version": "2.0.0", "language": "go", "max_level": 4, "k_limit": 3,
+  "analyzer": { "name": "codeanalyzer-go", "version": "1.4.0" },
   "application": {
     "id": "can://go/myapp", "kind": "application",
     "symbol_table": {
@@ -228,7 +231,7 @@ Building **both** is a first-class deliverable for every analyzer, not an aftert
               "Hash(string)uint64": {
                 "id": "can://go/myapp/src/util.go/Hasher/Hash(string)uint64", "kind": "method",
                 "span": { "start":[14,1], "end":[22,1], "bytes":[42,180] },
-                "body": {                                                          // L3+
+                "body": {                                                 // L1: call nodes; completes at L3
                   "@entry": { "kind":"entry" },
                   "15:2":   { "kind":"statement", "span":{ "start":[15,2],"end":[15,18],"bytes":[84,100] } },
                   "16:2":   { "kind":"call", "span":{...}, "callee":"can://go/myapp/src/fnv.go/New64()" },

skills/designing-cldk-changes/references/schema-design-loop.md

@@ -54,15 +54,17 @@ For every divergence (step 1) and every new language concept (step 2), present i
 use `AskUserQuestion`. Don't batch a whole node into one vague question; ask per real decision,
 with a recommended default first. Use this shape:
 
-> **`callable.decorators`/annotations.** In **Java** these are flat strings
-> (`annotations: List[str]` + `modifiers`). In **Python** they are structured `PyDecorator`
-> objects (name, qualified_name, positional/keyword args). TypeScript has decorators that carry
-> arguments (`@Component({selector: '...'})`).
-> *How do you want to model TS decorators?*
-> 1. **Structured `TSDecorator` (recommended)** — like Python; preserves args so entrypoint
->    finders can read `@Get('/path')` later. Costs a richer model.
-> 2. **Flat strings** — like Java; simplest, but throws away argument structure.
-> 3. **Structured + raw fallback** — structured fields plus the raw source string.
+> **Rust lifetime parameters.** Neither **Java** nor **Python** has a reference precedent —
+> lifetimes are a Rust-only construct (`fn longest<'a>(x: &'a str, y: &'a str) -> &'a str`). The
+> rubric (`references/canonical-schema.md` § Language expansion) offers three shapes for anything
+> with no precedent: a new typed field, folding it into an existing field, or an open-vocab `tags`
+> entry.
+> *How do you want to model lifetime parameters on `callable`?*
+> 1. **Typed field `lifetimes: LifetimeParam[]` (recommended)** — `{ name, bounds[] }` per
+>    callable; preserves borrow-checker-relevant structure for later dataflow work.
+> 2. **Fold into `parameters`** — attach a `lifetime` string to each `param` that borrows;
+>    cheaper, but loses signature-level lifetime bounds (`'a: 'b`).
+> 3. **Open-vocab `tags`** — `tags: ["lifetime:'a"]`; zero schema cost, but not machine-queryable.
 
 Always include *why* each option exists and what it buys/costs, anchored in what the references
 did. When the language adds something with no reference precedent (TS generics, Go receiver types,

skills/maintaining-cldk/references/repo-map.md

@@ -3,15 +3,14 @@
 Where a fix lands, and what pins to what. Enumerated live via
 `gh repo list codellm-devkit --limit 100 --json name,description` (27 returned,
 25 after excluding the two org-meta repos `.github` / `.github-private`). Facts below
-are evidenced from that enumeration plus local checkouts under
-`/Users/rkrsn/workspace/codellm-devkit/`; anything not directly checked is
-marked **verify per repo**.
+are evidenced from that enumeration plus a local sibling checkout of the org's repos,
+if present; anything not directly checked is marked **verify per repo**.
 
 ## Tier 1 — SDKs (frontend)
 
 | Repo | Owns | Evidence |
 | --- | --- | --- |
-| `python-sdk` | The `cldk` PyPI package — the public Python facade (`CLDK(language=...).analysis(...)`). Wires Java, Python, C, and TypeScript backends today (`cldk/analysis/{java,python,c,typescript}`); no Go/Rust wiring yet. | Checked out; `cldk/analysis/` listing. |
+| `python-sdk` | The `cldk` PyPI package — the public Python facade. Canonical surface today is the `CLDK.<lang>(project_path=..., backend=...)` factory, with the legacy `CLDK(language=...).analysis(...)` retained as a compat shim. Wires Java, Python, C, and TypeScript backends today (`cldk/analysis/{java,python,c,typescript}`); no Go/Rust wiring yet. | Checked out; `cldk/analysis/` listing. |
 | `typescript-sdk` | The `@codellm-devkit/cldk` npm package — the TS/JS facade. | No local checkout — **verify per repo**. |
 
 ## Tier 2 — Analysis backends (`codeanalyzer-<lang>`)
@@ -34,7 +33,7 @@ checks.
 | `codeanalyzer-java` | Java, via WALA + JavaParser. Has its own Neo4j `SchemaCatalog` (`SCHEMA_VERSION` constant, currently `1.1.0` in the local checkout) — **verify per repo** whether this has moved to schema v2 by the time you're reading this. | Checked out. |
 | `codeanalyzer-python` | Python, via Jedi + Tree-sitter (+ `codeanalyzer-codeql` for deeper dataflow). Local checkout's `codeanalyzer/core.py` gates its analysis cache on `schema_version == "2.0.0"` — already on schema v2. | Checked out. |
 | `codeanalyzer-typescript` | TypeScript/JavaScript, via ts-morph + Jelly. One repo, multiple in-flight branches: the `main`-tracking checkout sits on `feat/issue-2-program-graphs`; a second worktree of the **same repo** sits on `fix/issue-46-bolt-symbol-labels`, which is where the schema-v2 additive-CPG emitter + Neo4j v2 projection work is landing (`PROGRAM_GRAPHS_SCHEMA_VERSION` in `src/schema/graphs.ts`). Do not mistake the two worktrees for two repos. | Checked out (two worktrees, one `origin`). |
-| `codeanalyzer-go` | Go. **In development** per the org description; the local checkout of `main` is a near-empty stub (`LICENSE`, `README.md` only) — the working analyzer, if any, lives on a feature branch/PR, not `main`. This is also the scenario dry-run cwd: treat anything you find here as real repo state, not an answer key. | Checked out. |
+| `codeanalyzer-go` | Go. **In development** per the org description; the local checkout of `main` is a near-empty stub (`LICENSE`, `README.md` only) — the working analyzer, if any, lives on a feature branch/PR, not `main`. | Checked out. |
 | `codeanalyzer-rust` | Rust, via the Rust compiler's IR. **In development**; local checkout has no source tree yet (just `docs/`, `.devcontainer/`). | Checked out. |
 | `codeanalyzer-kotlin`, `codeanalyzer-swift`, `codeanalyzer-dotnet`, `codeanalyzer-abap` | Kotlin / Swift / .NET / ABAP backends. All **in development**; local checkouts are empty (git metadata only, no source). | Checked out. |
 | `codeanalyzer-clang` | C/C++ family. Has a `CLAUDE.md` and `docs/` but no visible source tree in the checkout — **verify per repo** for current depth. | Checked out. |
@@ -45,7 +44,7 @@ checks.
 
 | Repo | Owns | Evidence |
 | --- | --- | --- |
-| `cldk-devtools` | This plugin — the skills that extend/maintain CLDK itself (this repo, worked in as a git worktree). Note: this repo was renamed from `cldk-forge` (`gh repo view codellm-devkit/cldk-forge` redirects to `cldk-devtools`) — a local checkout still pointing at the old `cldk-forge` remote is this same repo, pre-rename, not a distinct one. | Checked out (this worktree); `git remote`/`gh repo view` redirect confirmed. |
+| `cldk-devtools` | This plugin — the skills that extend/maintain CLDK itself (this repo). Note: this repo was renamed from `cldk-forge` (`gh repo view codellm-devkit/cldk-forge` redirects to `cldk-devtools`) — a local checkout still pointing at the old `cldk-forge` remote is this same repo, pre-rename, not a distinct one. | Checked out (`cldk-devtools`, this repo); `git remote`/`gh repo view` redirect confirmed. |
 | `cocoa` | COCOA (Code Context Agent) — the Python implementation + MCP toolbox server wrapping CLDK for coding agents. | Checked out. |
 | `cocoa-mcp` | A second COCOA/MCP repo; its `gh` description text says "Python Implementation" but `primaryLanguage` reports Java in the enumeration — **verify per repo** which is authoritative before treating this as pure-Python. | Checked out; description/language mismatch observed directly. |
 | `cocoa-ts` | The TypeScript implementation of COCOA + its MCP server. | No local checkout — **verify per repo**. |

tests/consistency/check-readme-dispatcher-sync.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Consistency check: README.md's "## The Ladder" diagram and "## Routing" table
+# must stay byte-identical to skills/using-cldk-devtools/SKILL.md's copies of the
+# same two blocks. Run from repo root: bash tests/consistency/check-readme-dispatcher-sync.sh
+set -u
+
+root="$(cd "$(dirname "$0")/../.." && pwd)"
+readme="$root/README.md"
+skill="$root/skills/using-cldk-devtools/SKILL.md"
+fails=0
+
+for f in "$readme" "$skill"; do
+  if [ ! -f "$f" ]; then
+    echo "FAIL missing file: $f"
+    exit 1
+  fi
+done
+
+# extract_fenced_after_heading FILE HEADING
+# Prints the contents of the first fenced ``` code block that appears after an
+# exact-match heading line.
+extract_fenced_after_heading() {
+  awk -v heading="$2" '
+    $0 == heading { found=1; next }
+    found && /^```/ { if (in_block) { exit } else { in_block=1; next } }
+    found && in_block { print }
+  ' "$1"
+}
+
+# extract_table_after_heading FILE HEADING
+# Prints the contiguous run of `|`-prefixed table rows that appears after an
+# exact-match heading line.
+extract_table_after_heading() {
+  awk -v heading="$2" '
+    $0 == heading { found=1; next }
+    found && /^\|/ { print; seen=1; next }
+    found && seen && $0 !~ /^\|/ { exit }
+  ' "$1"
+}
+
+check_block() {
+  name="$1"; a="$2"; b="$3"
+  if diff -u "$a" "$b" >/tmp/check-readme-dispatcher-sync.diff.$$ 2>&1; then
+    echo "OK   $name"
+  else
+    echo "FAIL $name"
+    cat /tmp/check-readme-dispatcher-sync.diff.$$
+    fails=$((fails+1))
+  fi
+  rm -f /tmp/check-readme-dispatcher-sync.diff.$$
+}
+
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+
+extract_fenced_after_heading "$readme" "## The Ladder" > "$tmp/readme_ladder.txt"
+extract_fenced_after_heading "$skill"  "## The Ladder" > "$tmp/skill_ladder.txt"
+check_block "ladder diagram" "$tmp/readme_ladder.txt" "$tmp/skill_ladder.txt"
+
+extract_table_after_heading "$readme" "## Routing" > "$tmp/readme_routing.txt"
+extract_table_after_heading "$skill"  "## Routing" > "$tmp/skill_routing.txt"
+check_block "routing table" "$tmp/readme_routing.txt" "$tmp/skill_routing.txt"
+
+if [ -s "$tmp/readme_ladder.txt" ]; then :; else
+  echo "FAIL ladder diagram: extracted empty from README.md — extraction is broken"
+  fails=$((fails+1))
+fi
+if [ -s "$tmp/readme_routing.txt" ]; then :; else
+  echo "FAIL routing table: extracted empty from README.md — extraction is broken"
+  fails=$((fails+1))
+fi
+
+if [ "$fails" -eq 0 ]; then
+  echo "All blocks in sync."
+  exit 0
+else
+  echo "$fails block(s) out of sync."
+  exit 1
+fi