sql-code-graph 1.1.3__tar.gz → 1.2.2__tar.gz

{sql_code_graph-1.1.3 → sql_code_graph-1.2.2}/ARCHITECTURE_REVIEW.md

@@ -478,7 +478,15 @@ both concrete backends override it — the blueprint does not enforce this.
 Risk: HIGH. A failed re-index leaves orphaned graph nodes that produce incorrect
 lineage results until the next full re-index.
 
-### 3.2 [HIGH] `CrossFileAggregator.resolve_pass2` re-opens files without error handling
+### 3.2 ~~[HIGH]~~ **RESOLVED (v1.2.1)** `CrossFileAggregator.resolve_pass2` re-opens files without error handling
+
+**Resolution (2026-06-02, v1.2.1, PR #48):** `resolve_pass2` was deleted entirely. It had
+zero production call sites — the production pass-2 path in `index_repo` reimplements the
+dep-filter + reparse logic inline (worker calls `parse_file(..., dependency_filter=...)`
+in [`pool.py`](src/sqlcg/indexer/pool.py)), and that path already handles file-read errors
+defensively. The dead method (and the four tests that exercised it) were the same
+test-measures-a-dead-path blind-spot class as #40. Tests realigned to drive `index_repo`
+end-to-end. See [`v1_2_1_bugfix.md`](plan/v1_2_1_bugfix.md) Phase 5.
 
 ```python
 def resolve_pass2(self, parser, parsed):
@@ -2947,4 +2955,193 @@ editor owns the stdio process lifecycle and v1.1 has no launcher to re-spawn it
   owner-only, but any same-uid local process can send `stop`/`reindex`).
 - **Freshness on every tool result by default** — v1.1 ships it gated/off to
   protect hot-path latency; default-on pending an overhead measurement.
+
+## 18. v1.2.1 — Lineage recall guards + canonical INSERT target + CTE filter fixes
+
+Review date: 2026-06-02 · Reconciled by: architect-planner · Branch:
+`feat/v1.2.1-bugfix` · PR #48 · Verdict: **PLAN-COMPLIANT (PASS)**
+
+> **Bundled release note (2026-06-02):** the v1.2.1 bugfix scope (this section) and the
+> downstream-sink `file:line` fix (§19.2) ship as a **single `v1.2.2` release** — the
+> lower `v1.2.1` tag is skipped (precedent: v1.1.2→v1.1.3). Both change sets live on
+> `feat/v1.2.1-bugfix` (PR #48, fast-forwarded to `b5bf7a3`); version is `1.2.2`. The
+> combined plan-compliance verdict (PASS, both scopes) is recorded in
+> [`v1_2_1_bugfix.md`](plan/v1_2_1_bugfix.md) → "Bundled v1.2.2 release compliance".
+
+Patch release fixing the residual user-facing lineage defects (#44 canonical-name
+split, #45 `file:line=?` + `cte_*` leak), repairing the v1.2.0 read-proxy filter
+regression (the #39 read-half), deleting the dead `resolve_pass2` (resolves §3.2),
+and landing the #40 user-surface regression-guard suite. Plan:
+[`v1_2_1_bugfix.md`](plan/v1_2_1_bugfix.md) (full phase-by-phase compliance log appended there).
+
+### 18.1 #44 — canonical INSERT-target resolution
+
+A new `CrossFileAggregator.canonical_by_bare` index (bare name → sole DDL `full_id`)
+plus `_ambiguous_bare` (names defined in >1 schema, never rewritten) is built in
+`register_pass1` from DDL tables only. It is threaded `index_repo` →
+`_upsert_file_batch` → `_build_file_rows`, where an unqualified / non-DDL INSERT
+target whose bare name resolves to a sole DDL canonical is rewritten to share that
+node's identity (`qualified` == DDL `full_id`, all fields derived from the canonical),
+keeping `kind:"table"`. The fix lands in the node-emission loop, **not** the deleted
+`resolve_pass2` and **not** the per-column lineage hot path — pure row-dict mutation,
+no new `execute()`. Degrades to a no-op when `canonical_by_bare is None`
+(single-file `reindex_file` / `resync_changed` paths) — known limitation, re-index is
+the migration path per CLAUDE.md.
+
+### 18.2 #45 — `file:line` recall + structural `cte_*` suppression
+
+- **#45.1**: `analyze upstream/downstream` now bind location from the source's
+  *outgoing* `COLUMN_LINEAGE` edge and aggregate `WITH … min(start_line), min(file_path)`
+  **before** `LIMIT 100`, so multi-hop sources carry a real `file:line` and the limit
+  counts distinct sources, not edge-fanout rows.
+- **#45.2**: chosen mechanism is **graph-truth, not a name heuristic** — unresolved
+  synthetic INSERT targets are emitted `kind:"derived"` (the #44 emission change), and
+  the restored `kind IN ['table','external']` read filter excludes them. No name-prefix
+  belt was needed.
+
+### 18.3 Two implementation invariants discovered during the fix
+
+Both are now load-bearing; recorded so a future refactor does not silently undo them.
+
+1. **KuzuDB: a `WHERE` clause inside `OPTIONAL MATCH` filters the match attempt, not
+   the surrounding row.** To filter rows on an optionally-matched node's property, an
+   explicit `WITH <carried>, t WHERE …` must follow. `analyze._kind_filter` uses this
+   form (`OPTIONAL MATCH (t:SqlTable {…}) WITH <alias>, t WHERE t.kind IS NULL OR …`).
+   The `IS NULL` branch is intentional: it keeps node-less physical sources (the #39
+   tail) while CTE/derived intermediates (`kind='cte'`/`'derived'`) are excluded.
+   Guarded by TC1/TC4 in [`test_user_surface_recall_guard.py`](tests/integration/test_user_surface_recall_guard.py).
+2. **`_flush_row_batch` dedup must prefer structural kinds over the default `'table'`.**
+   A CTE alias is emitted twice in a batch — first `kind='table'` (incidental source
+   reference) then `kind='cte'` (CTE destination). The pre-existing first-seen-wins
+   dedup kept the wrong one, defeating #45.2. New Rule 2: `{'cte','derived','external'}`
+   beats default `'table'` (Rule 1 — DDL provenance via `defined_in_file` — still takes
+   precedence). This logic lives in the documented `_flush_row_batch` perf hot path but
+   is pure dict comparison in the existing dedup loop — no change to flush cardinality,
+   batch/scaling guards stay green (CLAUDE.md performance invariants intact).
+
+### 18.4 Resolved / out-of-scope
+
+- **§3.2 `resolve_pass2`** — RESOLVED (deleted; see §3.2 update).
+- **Residual #38 (UNION-ALL sibling CTEs)** — already fixed in 1.1.3; live DWH
+  re-verification (80→47 `cte_insert` islands) recorded in the plan; the surviving 47
+  are likely legitimately source-less computed measures, not a regression. Shape B of
+  the #40 guard now asserts a computed-measure projection so a real gap there reds the guard.
+- **#28 server read-only-by-default + reindex escalation** — out of 1.2.1; recommended
+  as a separate minor (1.3.0). The read half is already handled by the v1.2.0 routing proxy.
 - **`connected_clients` fidelity** — best-effort `1` today; no real counter.
+
+## 19. v1.2.1 live DWH re-verification — two residual findings (2026-06-02)
+
+Source: live verification of the v1.2.1 fixes against the full DWH corpus
+(`../dwh`, 1,335 SQL files, clean index ~1:56). **The v1.2.1 fixes themselves
+PASSED** — both findings below are residual / design-limit behaviour surfaced by
+the run, not regressions in PR #48. Corpus graph snapshot (kind-typed `SqlTable`):
+2,222 `table` / 383 `cte` / 272 `derived`.
+
+### 19.1 [KEEP — LOW] Residual scratch-object leak into the default `analyze` surface
+
+**Measurement.** The #45.2 fix essentially closed the `cte_` leak it targeted:
+of nodes still typed `kind='table'`, only 3 carry a `cte_` prefix (vs 383 now
+correctly `kind='cte'`). The broader leak persists: **495 of 2,222 `table`-kind
+nodes (~22%) carry scratch-object name prefixes** — 471 `tmp_*`, 21 `temp_*`,
+3 `cte_*` — plus ~575 unqualified single-token nodes (a mix of real bare tables
+and CTE aliases). These surface in default (filtered) `analyze` output because the
+filter is correctly kind-based (graph-truth) but these aliases were never classified
+`cte`/`derived` at parse/aggregation time. This is the known #38 islands residual
+(s18.4 / `47 cte_insert islands`); the leak is now `tmp_*`-dominated, not
+`cte_*`-dominated. See memory `project_issue38_cte_filter_regression`.
+
+**Decision: KEEP as a future ticket, LOW priority.** Rationale tied to existing
+decisions:
+- The standing **"no name-prefix filtering"** decision (s18.2; CLAUDE.md) is correct
+  and stays. The fix therefore **cannot** live in the filter — it must happen at
+  **classification time** in the aggregator/parser, exactly like the #44 synthetic
+  INSERT-target → `kind='derived'` emission change (s18.1). A `CREATE [OR REPLACE]
+  TEMP/TRANSIENT TABLE tmp_x AS SELECT …` whose target is a scratch object should be
+  emitted `kind='derived'` at `_build_file_rows` time, the same place #44 already
+  rewrites node identity. 492/495 of the leak (`tmp_*`/`temp_*`) are this CTAS-into-
+  scratch shape — addressable by classifying on the parsed CTAS-into-temp statement
+  kind (DDL-derived structural truth), **not** on the name prefix.
+- **Non-goal for the ticket:** the ~575 unqualified single-token nodes. They are a
+  genuine mix of real bare tables and CTE aliases; auto-classifying them risks
+  hiding real physical tables from the default surface (a false-negative worse than
+  the current cosmetic leak). They stay `kind='table'` until a structural signal
+  (CTE membership, CTAS target) is available — never a name guess.
+
+**Risk/reward.** Reward: cleaner default `analyze` surface, ~22% fewer scratch
+intermediates leaking; closes the visible tail of #38. Risk: medium — must classify
+on parsed statement structure (TEMP/TRANSIENT CTAS target), and must not reclassify
+a real `tmp_`-named physical table that is read by a non-CTAS statement; needs a guard
+asserting a real table named `tmp_*` is still surfaced. Effort: medium (one emission
+site, reuses #44 plumbing, plus a behavioural guard). Below the open HIGH §3.x items
+and Finding 19.2 in the ranking. Recorded here; no plan stub drafted yet (pull when
+a lineage-coverage sprint next touches `_build_file_rows`).
+
+### 19.2 [RESOLVED in v1.2.2] `file:line='?'` on downstream terminal sinks
+
+**Measurement.** The #45.1 fix rebinds a result's location from its **outgoing**
+`COLUMN_LINEAGE` edge ("where is this column used as a source"). For *downstream*
+traces this means terminal sinks render `?`: a sink has no outgoing edge, so
+`min(q.start_line)`/`min(q.file_path)` are NULL. Corpus measurement: of 36,892
+distinct columns reachable as a downstream result, **29,827 (81%) are sinks → render
+`file:line='?'`**. The fix populates only the locatable 19%. Upstream is unaffected
+(an upstream source legitimately has an outgoing edge). The TC6 guard asserts non-null
+`file:line` on one specific *located* case, so it passed despite the 81%.
+
+**Decision: KEEP — pick up next.** This is a genuine bug, **not** deliberate
+semantics. Analysis tied to #45.1's own intent:
+- #45.1 chose the outgoing edge so a *source*'s location reads as "where it is
+  produced/consumed as a source" — correct for the **upstream** direction. The same
+  pattern was copied verbatim into the **downstream** query
+  ([`analyze.py`](src/sqlcg/cli/commands/analyze.py) lines 134–137, fallback 146–149):
+  `OPTIONAL MATCH (dst)-[dstedge]->()`. For a downstream *result*, the natural,
+  user-meaningful location is the query that **produced** the column — i.e. the
+  **incoming** edge `()-[dstedge]->(dst)`, not the outgoing one.
+- **Key lever (confirmed in code):** every one of the 36,892 columns has an incoming
+  `COLUMN_LINEAGE` edge by definition — that is how it became a downstream result —
+  and that producing query carries a real `start_line`/`file_path`. Flipping the two
+  downstream `OPTIONAL MATCH` arrows from `(dst)-[dstedge]->()` to
+  `()-[dstedge]->(dst)` binds location from the producing query, turning ~81% of `?`
+  rows into a real `file:line`. Upstream stays on the outgoing edge unchanged.
+
+**Risk/reward.** Reward: HIGH — ~81% of downstream result rows flip from `?` to a
+real `file:line` on a corpus this shape. Effort: LOW — a ~2-line arrow flip in two
+downstream queries (primary + bare-name fallback), no schema/index/perf change, no
+parser change. Risk: LOW and bounded — only the downstream direction; upstream and
+the kind-filter (s18.3) untouched. The one trap: TC6 passes today on a located case,
+so it does **not** catch the regression — the ticket must add a guard asserting a
+**terminal sink** (no outgoing edge) renders a real `file:line`, not `?`.
+Plan stub drafted: [`fix_downstream_sink_location.md`](plan/fix_downstream_sink_location.md).
+Suggested release: patch (1.2.2) or fold into the next lineage minor.
+
+**RESOLVED — shipped in v1.2.2 (bundled with v1.2.1; see §18 bundled-release note).**
+Both downstream queries in [`analyze.py`](src/sqlcg/cli/commands/analyze.py) (primary
+L134, bare-name fallback L146) now bind location from the **incoming**
+`()-[dstedge:COLUMN_LINEAGE]->(dst)` edge — the producing query — so terminal sinks
+carry a real `file:line`. Upstream (L77/L89) keeps the outgoing-edge binding, unchanged.
+Guarded by the TC6b terminal-sink test in
+[`test_user_surface_recall_guard.py`](tests/integration/test_user_surface_recall_guard.py),
+demonstrably RED on master before the fix.
+
+### 19.3 Cross-finding note
+
+Both findings share the v1.2.1 root theme: the *graph store* is correct (edges intact,
+kinds mostly right); the defects live in the **graph→user presentation layer**
+(filter classification for 19.1, location binding for 19.2) — the same blind-spot
+class as #38/#40 where anchors traversing raw edges pass while the user-facing query
+path is wrong. Any guard for either must drive the **user-facing `analyze` path**,
+not raw `COLUMN_LINEAGE` traversal.
+
+### 19.4 [KEEP — LOW] TC6b guard reconstructs the query instead of running `analyze downstream`
+
+Raised by the plan-reviewer on the §19.2 sink fix. The TC6b terminal-sink guard's helper
+`_downstream_filtered_query()` in
+[`test_user_surface_recall_guard.py`](tests/integration/test_user_surface_recall_guard.py)
+**reconstructs the downstream Cypher query string** rather than invoking
+`analyze.downstream()` end-to-end. It therefore can drift from the production query if
+[`analyze.py`](src/sqlcg/cli/commands/analyze.py) changes and the helper is not updated in
+lockstep — exactly the §19.3 blind-spot (a guard not driving the true user-facing path).
+The fix held for v1.2.2 (the helper mirrors the shipped query), but the divergence risk is
+structural. **Future hardening:** replace the string-reconstruction helper with a
+`CliRunner`-based guard that runs the real `analyze downstream` command and asserts the
+rendered output. LOW priority; below §19.1 and the open §3.x items. No plan stub drafted.

{sql_code_graph-1.1.3 → sql_code_graph-1.2.2}/CLAUDE.md

@@ -59,6 +59,27 @@ This project uses `uv`. Never activate a virtualenv manually, never use `pip`, n
 | Lint | `rtk uv run ruff check src tests` |
 | Format | `uv run ruff format src tests` |
 
+## Releasing (version bump + tag)
+
+Every feature/fix PR that ships bumps the version; after it merges to `master`, tag the release.
+Do **all** of this — the tag is the step most easily forgotten.
+
+1. **Bump the version** (in the feature branch, before the PR merges):
+   - [`pyproject.toml`](pyproject.toml) `version = "X.Y.Z"`
+   - [`src/sqlcg/__init__.py`](src/sqlcg/__init__.py) `__version__ = "X.Y.Z"`
+   - `uv lock` (refreshes the lockfile's own version entry)
+   - **SemVer**: new capability/surface → **minor** (`1.1.x` → `1.2.0`); bug fix only → **patch**.
+     No backward-compat shims, so an additive feature is still minor (not major) when nothing breaks.
+2. **Merge the PR to `master`** (squash or `--merge` per the existing `Merge #NN` history).
+3. **Tag the merge commit on `master`** — **annotated**, `v`-prefixed, message `vX.Y.Z — <one-line summary>`:
+   ```bash
+   git checkout master && git pull --ff-only origin master
+   git tag -a vX.Y.Z -m "vX.Y.Z — <summary>" <merge-commit-sha>
+   git push origin vX.Y.Z
+   ```
+   All existing tags are annotated and look like `v1.1.3` (never bare `1.1.3`). Confirm with
+   `git tag -l --format='%(contents)' vX.Y.Z` and verify it points at the master merge commit.
+
 ## Target scale — serve both ends of the spectrum
 
 This project must work correctly and comfortably at two very different scales:

{sql_code_graph-1.1.3 → sql_code_graph-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-code-graph
-Version: 1.1.3
+Version: 1.2.2
 Summary: SQL code graph analyzer and lineage tracer
 Project-URL: Homepage, https://github.com/Warhorze/sql-code-graph
 Project-URL: Repository, https://github.com/Warhorze/sql-code-graph
@@ -267,6 +267,16 @@ sqlcg mcp restart                      # stop the server (client must respawn it
 sqlcg version                          # show installed version
 ```
 
+### Reads while the server is running (v1.2.0)
+
+KuzuDB allows a single writer, so while the MCP server is live it holds the
+database lock. CLI **read** commands (`find`, `analyze`, `db info`, `list-repos`,
+`gain`) automatically route their query through the running server over its
+control socket and return rows as usual — no flag, no config. When no server is
+running they open the database directly, exactly as before. If the server is
+mid-reindex the read waits for it to finish rather than failing with
+"Database is locked".
+
 ## Supported dialects
 
 sqlcg is built on [sqlglot](https://github.com/tobymao/sqlglot), so other dialects

{sql_code_graph-1.1.3 → sql_code_graph-1.2.2}/README.md

@@ -229,6 +229,16 @@ sqlcg mcp restart                      # stop the server (client must respawn it
 sqlcg version                          # show installed version
 ```
 
+### Reads while the server is running (v1.2.0)
+
+KuzuDB allows a single writer, so while the MCP server is live it holds the
+database lock. CLI **read** commands (`find`, `analyze`, `db info`, `list-repos`,
+`gain`) automatically route their query through the running server over its
+control socket and return rows as usual — no flag, no config. When no server is
+running they open the database directly, exactly as before. If the server is
+mid-reindex the read waits for it to finish rather than failing with
+"Database is locked".
+
 ## Supported dialects
 
 sqlcg is built on [sqlglot](https://github.com/tobymao/sqlglot), so other dialects

{sql_code_graph-1.1.3 → sql_code_graph-1.2.2}/docs/cli.md

@@ -17,7 +17,7 @@ bash scripts/generate_cli_docs.sh
 | `watch` | Watch a directory and re-index on SQL file changes. |
 | `gain` | Show metrics and feedback analytics. |
 | `report` | Generate a metrics report with FP clusters and parse error patterns. |
-| `install` | Register sqlcg as an MCP server in Claude Code (~/.claude/settings.json). |
+| `install` | Register sqlcg as an MCP server in Claude Code. |
 | `uninstall` | Uninstall sqlcg from Claude Code and optionally clean up resources. |
 | `version` | Show version. |
 | `db` | Database management commands |
@@ -71,13 +71,15 @@ Schema aliases (staging schema → canonical schema) can be configured in
 | --- | --- | --- | --- | --- | --- |
 | --dialect, -d | TEXT | No | No |  | SQL dialect (or 'auto' to read from .sqlcg.toml) |
 | --dbt-manifest | PATH | No | No |  | Path to dbt manifest |
-| --timeout-per-file | INTEGER | No | No | 5 | Timeout per file in seconds |
+| --timeout-per-file | INTEGER | No | No | 10 | Timeout per file in seconds |
 | --buffer-pool-size | INTEGER | No | No | 0 | KuzuDB buffer pool size in MB (0 = default). Set to 256-512 on memory-constrained machines. |
 | --batch-size | INTEGER | No | No | 50 | Files per KuzuDB transaction in the upsert pass. Default 50 balances commit-overhead reduction (vs. legacy per-file commits) against per-batch memory cost. Lower values are safer for memory-constrained machines; higher values give marginal speedup at the cost of larger working sets. Set to 1 to reproduce legacy per-file commit behaviour. |
 | --no-ddl | BOOLEAN | No | No | False | Skip table-node upserts for DDL-only files |
 | --quiet, -q | BOOLEAN | No | No | False | Suppress summary console output |
+| --verbose, -v | BOOLEAN | No | No | False | Print parse warnings to stderr instead of log file |
 | --debug | BOOLEAN | No | No | False | Show detailed log output during indexing |
 | --profile / --no-profile | BOOLEAN | No | No | False | Emit per-stage timing after indexing |
+| --include-working-tree | BOOLEAN | No | No | False | Index the working tree including uncommitted changes. Marks freshness as 'indexed with working-tree changes'. |
 
 ## `sqlcg reindex`
 
@@ -106,7 +108,8 @@ build — run 'sqlcg db reset && sqlcg db init && sqlcg index <path>' to re-init
 | --dialect, -d | TEXT | No | No |  | SQL dialect (or 'auto' to read from .sqlcg.toml) |
 | --quiet, -q | BOOLEAN | No | No | False | Suppress summary output |
 | --batch-size | INTEGER | No | No | 50 | Files per KuzuDB transaction (same default as index command) |
-| --timeout-per-file | INTEGER | No | No | 5 | Per-file parse timeout in seconds |
+| --timeout-per-file | INTEGER | No | No | 10 | Per-file parse timeout in seconds |
+| --notify | BOOLEAN | No | No | False | If a server is live on this DB, route the reindex through the server (avoids lock contention). Falls back to direct write if no server is found. |
 
 ## `sqlcg watch`
 
@@ -181,7 +184,10 @@ If no metrics database exists, prints a message and exits 0.
 sqlcg install [OPTIONS]
 ```
 
-Register sqlcg as an MCP server in Claude Code (~/.claude/settings.json).
+Register sqlcg as an MCP server in Claude Code.
+
+Runs ``claude mcp add -s user sql-code-graph <cmd> <args>`` when the
+``claude`` CLI is on PATH; otherwise writes ~/.claude.json directly.
 
 Also provisions a Claude skill file (SKILL.md) at the chosen location.
 Pass --scope project or --scope global to specify where the skill is written.
@@ -333,7 +339,7 @@ Find a table by name.
 
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
-| _none_ |  |  |  |  |  |
+| --raw | BOOLEAN | No | No | False | Disable noise filtering on results |
 
 ## `sqlcg find column`
 
@@ -347,7 +353,7 @@ Find a column by table.column reference.
 
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
-| _none_ |  |  |  |  |  |
+| --raw | BOOLEAN | No | No | False | Disable noise filtering on results |
 
 ## `sqlcg find pattern`
 
@@ -394,6 +400,8 @@ Trace upstream column lineage.
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
 | --depth | INTEGER | No | No | 5 | Maximum traversal depth |
+| --raw | BOOLEAN | No | No | False | Disable noise filtering on results |
+| --include-intermediate | BOOLEAN | No | No | False | Include CTE/derived intermediate nodes |
 
 ## `sqlcg analyze downstream`
 
@@ -408,6 +416,8 @@ Trace downstream column lineage.
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
 | --depth | INTEGER | No | No | 5 | Maximum traversal depth |
+| --raw | BOOLEAN | No | No | False | Disable noise filtering on results |
+| --include-intermediate | BOOLEAN | No | No | False | Include CTE/derived intermediate nodes |
 
 ## `sqlcg analyze impact`
 
@@ -421,7 +431,7 @@ Show all queries impacted by a table.
 
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
-| _none_ |  |  |  |  |  |
+| --raw | BOOLEAN | No | No | False | Disable noise filtering on results |
 
 ## `sqlcg analyze failures`
 
@@ -431,6 +441,9 @@ sqlcg analyze failures [OPTIONS]
 
 List files that failed to parse, with their dominant cause (E-code bucket).
 
+Valid --cause buckets (from highest to lowest severity):
+timeout, E8, E3, E2, E5, E1, qualify_failed, func_fallback, pure_ddl_skip.
+
 Requires a graph indexed with sqlcg >= v3 (schema version 3). Re-index
 with 'sqlcg db reset && sqlcg index <path>' if the graph was built with
 an earlier version.
@@ -439,7 +452,7 @@ an earlier version.
 
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
-| --cause | TEXT | No | No |  | Filter by E-code bucket (e.g. E5, timeout) |
+| --cause | TEXT | No | No |  | Filter by E-code bucket. Valid values: timeout, E8, E3, E2, E5, E1, qualify_failed, func_fallback, pure_ddl_skip |
 | --limit | INTEGER | No | No | 100 | Maximum rows to return |
 
 ## `sqlcg analyze unused`
@@ -455,6 +468,7 @@ Find tables with no query references.
 | Option | Type | Required | Repeatable | Default | Description |
 | --- | --- | --- | --- | --- | --- |
 | --threshold | INTEGER | No | No | 0 | Minimum reference count threshold |
+| --raw | BOOLEAN | No | No | False | Disable noise filtering on results |
 
 ## `sqlcg mcp`
 
@@ -471,6 +485,9 @@ MCP server commands
 | `setup` | Print or write MCP server config JSON. |
 | `start` | Start the MCP server. |
 | `best-practices` | Print MCP tool best-practices (the fact/heuristic boundary). |
+| `status` | Print server status JSON (connects to control socket). |
+| `stop` | Stop the running MCP server gracefully. |
+| `restart` | Stop the server. The client (editor) must respawn. |
 
 ## `sqlcg mcp setup`
 
@@ -480,6 +497,11 @@ sqlcg mcp setup [OPTIONS]
 
 Print or write MCP server config JSON.
 
+--print (default): print the JSON snippet for manual insertion.
+--write: write to ~/.claude.json under mcpServers.user (the correct path
+         for Claude Code — not settings.json, which Claude Code does not read
+         for MCP servers).
+
 ### Options
 
 | Option | Type | Required | Repeatable | Default | Description |
@@ -517,6 +539,72 @@ that have not installed the skill.
 | --- | --- | --- | --- | --- | --- |
 | _none_ |  |  |  |  |  |
 
+## `sqlcg mcp status`
+
+```bash
+sqlcg mcp status [OPTIONS]
+```
+
+Print server status JSON (connects to control socket).
+
+Returns JSON with fields: running, pid, db_path, indexed_sha, head_sha,
+stale_by_commits, connected_clients, uptime when a server is live.
+
+When no server is found: {"running": false}.
+When the PID file exists with a live process but the socket is unavailable:
+{"running": true, "degraded": "socket unavailable", ...}.
+
+R3 (stale socket): if the socket file exists but the server is not
+responding (ConnectionRefusedError / FileNotFoundError), falls through
+to the PID-file probe — never hangs or errors on a dead socket.
+
+### Options
+
+| Option | Type | Required | Repeatable | Default | Description |
+| --- | --- | --- | --- | --- | --- |
+| _none_ |  |  |  |  |  |
+
+## `sqlcg mcp stop`
+
+```bash
+sqlcg mcp stop [OPTIONS]
+```
+
+Stop the running MCP server gracefully.
+
+Sends a ``stop`` op via the control socket; waits up to 5 s for the
+socket file to disappear (confirming clean exit).  Falls back to SIGTERM
+on the PID-file PID if the socket is unavailable.
+
+R3 (stale socket): ``ConnectionRefusedError`` / ``FileNotFoundError`` are
+caught — never hangs on a dead socket.
+
+### Options
+
+| Option | Type | Required | Repeatable | Default | Description |
+| --- | --- | --- | --- | --- | --- |
+| _none_ |  |  |  |  |  |
+
+## `sqlcg mcp restart`
+
+```bash
+sqlcg mcp restart [OPTIONS]
+```
+
+Stop the server. The client (editor) must respawn.
+
+v1.1 cannot re-parent an editor-spawned stdio process.  This command
+stops the current server and prints guidance for the user to restart
+the MCP server via their editor's MCP configuration.
+
+True auto-restart (re-parenting stdio) is deferred to v1.2.
+
+### Options
+
+| Option | Type | Required | Repeatable | Default | Description |
+| --- | --- | --- | --- | --- | --- |
+| _none_ |  |  |  |  |  |
+
 ## `sqlcg git`
 
 ```bash
@@ -542,6 +630,8 @@ Install git hooks for sqlcg integration.
 Writes a post-checkout hook that triggers incremental resync after branch switches
 and a post-merge hook that triggers resync after pulls/merges.
 Idempotent: running multiple times produces one hook entry per hook.
+The hooks embed the absolute path of the installing sqlcg binary so version skew
+between the installed binary and the hook command is avoided.
 
 ### Options
 

sql_code_graph-1.2.2/plan/fix_downstream_sink_location.md

@@ -0,0 +1,119 @@
+# Feature Plan: Downstream sink `file:line` recall
+
+> Status: **plan-reviewed — READY FOR IMPLEMENTATION.**
+> Source: ARCHITECTURE_REVIEW.md §19.2 (v1.2.1 live DWH re-verification, 2026-06-02).
+
+## Summary
+
+`analyze downstream` renders `file:line='?'` for ~81% of result rows (29,827 of
+36,892 distinct downstream columns on the DWH corpus) because terminal sinks have no
+*outgoing* `COLUMN_LINEAGE` edge to bind location from. Bind downstream-result
+location from the **incoming** edge (the producing query) instead, flipping ~81% of
+`?` rows to a real `file:line`.
+
+## Scope
+
+### In Scope
+- The two downstream queries in [`analyze.py`](src/sqlcg/cli/commands/analyze.py)
+  (`downstream` primary + bare-name fallback): change the location-binding
+  `OPTIONAL MATCH` from `(dst)-[dstedge]->()` to `()-[dstedge:COLUMN_LINEAGE]->(dst)`.
+- A behavioural guard asserting a **terminal sink** (a column with no outgoing edge)
+  renders a real `file:line`, not `?`.
+
+### Non-Goals
+- The upstream queries (`<-[…]-(src)` + `(src)-[srcedge]->()`). The outgoing-edge
+  binding is **correct** for upstream — do not touch lines 73–94 of `analyze.py`.
+- Finding 19.1 (scratch-object classification leak) — separate, LOW-priority ticket.
+- Any change to the kind-filter (`_kind_filter`, s18.3), schema, indexes, or parser.
+- Re-binding `q.start_line`/`q.file_path` semantics anywhere else (server tools).
+
+## Design
+
+### Query change (the load-bearing edit)
+
+Current downstream binding ([`analyze.py`](src/sqlcg/cli/commands/analyze.py)
+lines 134–137, and the bare-name fallback 146–149):
+
+```cypher
+OPTIONAL MATCH (dst)-[dstedge:COLUMN_LINEAGE]->()
+OPTIONAL MATCH (q:SqlQuery {id: dstedge.query_id})
+WITH dst, min(q.start_line) AS line, min(q.file_path) AS file
+```
+
+Change the first arrow to bind from the **producing** query (incoming edge):
+
+```cypher
+OPTIONAL MATCH ()-[dstedge:COLUMN_LINEAGE]->(dst)
+OPTIONAL MATCH (q:SqlQuery {id: dstedge.query_id})
+WITH dst, min(q.start_line) AS line, min(q.file_path) AS file
+```
+
+Rationale: every downstream result `dst` has an incoming edge by definition (that is
+how it became reachable), and that edge's `query_id` points at the query that
+produced the column — the user-meaningful "where is this column written" location.
+A terminal sink has no *outgoing* edge (today's `?`) but always has an incoming one.
+
+Keep `OPTIONAL MATCH` (not `MATCH`) so a `dst` whose incoming edge has a NULL/missing
+`query_id` still returns a row (degrades to `?` rather than dropping the row).
+
+### Data Models / Dependencies
+None. No schema, index, or dependency change.
+
+## Implementation Steps
+
+### Phase 1: Query rewrite
+**Step 1.1**: Flip the location-binding arrow in both downstream queries.
+- Files affected: [`analyze.py`](src/sqlcg/cli/commands/analyze.py) (downstream
+  primary ~134, bare-name fallback ~146).
+- Acceptance: both queries bind `()-[dstedge]->(dst)`; upstream queries unchanged
+  (grep confirms `(src)-[srcedge]->()` still present at lines 77 / 89).
+
+### Phase 2: Guard
+**Step 2.1**: Add `test_tc6b_downstream_sink_location_present` to
+[`test_user_surface_recall_guard.py`](tests/integration/test_user_surface_recall_guard.py).
+- The terminal sink to use from the existing A–D corpus is **`mart.fact_kpi.measure`**.
+  It is the final INSERT target — it has no outgoing `COLUMN_LINEAGE` edge (nothing
+  downstream consumes it), but it IS reachable as a downstream result from
+  `staging.src_a.x`. Confirm this via `MATCH (c:SqlColumn {id: 'mart.fact_kpi.measure'})-
+  [:COLUMN_LINEAGE]->() RETURN count(*)` returning 0 before relying on it.
+- Build the downstream query using `_kind_filter("dst", include_intermediate=False)` —
+  the same helper `analyze downstream` calls — so the guard drives the production query
+  path, not raw edge traversal (ARCHITECTURE_REVIEW.md §19.3).
+- Start the traversal from `staging.src_a.x` (a physical source) and assert that the
+  row for `mart.fact_kpi.measure` carries a non-null `file` field. Assert observable
+  output (non-null `file` value), not "no exception raised".
+- Acceptance: the new test is RED against the current outgoing-edge query on master and
+  GREEN after the Step 1.1 flip. Verify by running it before and after the edit.
+
+## Test Strategy
+- Integration: the new TC6b guard on the in-fixture sink (above).
+- Manual/live (optional, recorded in plan postmortem, not committed — DWH e2e is
+  gitignored): re-run `analyze downstream` on a DWH column and confirm the `?` rate
+  drops from ~81% toward ~0% for sinks.
+- Regression: full `uv run pytest` — confirm TC6 (upstream) and the kind-filter
+  guards (TC1/TC4) stay green; no perf/scaling guard touched (query-only change).
+
+## Acceptance Criteria
+- [ ] Both downstream queries bind location from the incoming `COLUMN_LINEAGE` edge.
+- [ ] Upstream queries are unchanged (outgoing-edge binding preserved).
+- [ ] A terminal-sink downstream result renders a real `file:line` (TC6b green).
+- [ ] TC6b is demonstrably RED on `master` before the fix (proves it guards the bug).
+- [ ] Full test suite green; no perf/scaling guard regression.
+- [ ] Version bumped to **1.2.2** (patch) per CLAUDE.md release process.
+      **Bundling decision (2026-06-02, supersedes the original standalone plan):** this
+      sink fix and the v1.2.1 bugfix scope ship together as a single **v1.2.2** release;
+      the lower `v1.2.1` tag is **skipped** (precedent: v1.1.2→v1.1.3). The bundled work
+      lives on `feat/v1.2.1-bugfix` (PR #48, fast-forwarded to `b5bf7a3`). The combined
+      plan-compliance verdict is recorded in
+      [`v1_2_1_bugfix.md`](v1_2_1_bugfix.md) under "Bundled v1.2.2 release compliance".
+
+## Risks and Mitigations
+- **Risk: a `dst` with multiple incoming edges from different queries.** `min()`
+  aggregation already collapses fanout (same pattern as #45.1); pick the
+  lowest-line producing query deterministically. Mitigation: keep the
+  `WITH dst, min(...), min(...)` aggregate-before-`LIMIT` shape exactly as upstream.
+- **Risk: TC6 false-confidence (it passes on a located case).** Mitigation: Phase 2
+  explicitly targets a *sink* — `mart.fact_kpi.measure` with zero outgoing edges —
+  the case TC6 misses; prove RED-on-master before the fix.
+- **Risk: scope creep into server tools.** Out of scope — this ticket is the CLI
+  `analyze downstream` path only.