ucn 4.2.3 → 5.0.2

package/.claude/skills/ucn/SKILL.md

@@ -1,115 +1,127 @@
 ---
 name: ucn
-description: AST code intelligence for JavaScript/TypeScript, Python, Go, Rust, Java, and HTML. Use in repositories over roughly 500 LOC to orient, extract symbols, trace callers or callees, assess impact, verify call sites, select tests, or investigate dead code. Prefer it over repeated grep-and-read cycles for semantic questions; use text search for literals, messages, configuration, and unsupported languages.
+description: AST code intelligence for JavaScript/TypeScript, Python, Go, Rust, Java, C, C++, C#, and HTML. Use in repositories over roughly 500 LOC to orient, extract symbols, trace callers or callees, assess change impact, validate call sites, select tests, inspect dependencies, or investigate dead code. Prefer it over repeated grep-and-read cycles for semantic questions; use text search for literals, messages, configuration, and unsupported languages.
 ---
 
 # UCN
 
 Use UCN to gather compact, auditable code evidence before reading large files or changing a symbol.
 
-## Start here
+## Core workflow
 
-1. Run `ucn orient` in an unfamiliar repository.
-2. Pin the symbol. Use `ucn find <name>` when a name is ambiguous, then pass the emitted `path:line:name` handle to later commands.
-3. Run `ucn about <handle> --compact` for definition, direct callers, callees, tests, and contract metadata.
-4. Before a change, run `ucn impact <handle>` and `ucn affected-tests <handle>`.
-5. After a signature change, run `ucn verify <handle>`. Before committing, run `ucn check`.
-6. Read source with `ucn fn`, `ucn class`, or `ucn lines` only when the evidence indicates that source inspection is needed.
+1. Run `ucn repo` in an unfamiliar repository. Add `--deep` when readiness or index health matters. If it reports skipped unsupported source, use grep/ripgrep and a language-native analyzer for those files; never interpret an `UNSUPPORTED` or `PARTIAL` scope as a semantic zero.
+2. Pin a symbol with `ucn find <name>`, then pass its `path:line:name` handle to later commands.
+3. Run `ucn show <handle>` for the default summary, callers, and callees. Request extra projections with `--sections=source,tests,types,dependencies,example,related`.
+4. Before a change, run `ucn impact <handle>` and `ucn tests <handle> --depth=3`.
+5. After a signature change, run `ucn check <handle>`. Before committing, run target-less `ucn check`.
+6. Read exact code with `ucn source <handle>` or `ucn source path/to/file:10-30` only when inspection is needed.
 
-Prefer `--json` when another tool or script will consume the answer. MCP `about`, `context`, and `impact` default to compact output; request `compact=false` only when source and previews are necessary.
+Prefer `--json` for automation. Every CLI JSON response uses `{ meta, data }`;
+`meta.command` uses the native surface spelling and may include the internal
+`canonicalCommand`. MCP returns text through one `ucn` tool and keeps contract
+metadata visible when truncating results.
 
-## CLI, MCP, and skill behavior
+## One contract across surfaces
 
-The skill is guidance, not a separate analysis engine. It tells the agent when and how to call UCN through the CLI or MCP.
+CLI, MCP, and interactive mode resolve the same 18 public commands through one registry, execute the same handlers, and use the same public formatters. CLI spells multiword commands with hyphens; MCP uses snake case. For example, use `audit-async` in CLI and `audit_async` in MCP.
 
-CLI and MCP resolve commands through the same registry, execute the same handlers, use the same project index and persisted cache, and call the same output formatters. Their defaults differ by transport:
+The release board independently cross-checks overlapping stable-handle answers from `find`, `show`, `source`, `impact`, `tests`, `check`, and caller `trace`. Target identity, source and direct-test projections, caller tiers, evidence reasons, totals, and accounting must agree exactly; a mismatch is a failing witness rather than an interpretation left to an agent.
 
-- CLI uses full text by default and emits raw JSON with `--json`.
-- MCP defaults `about`, `context`, and `impact` to compact text. It uses a 10K character default for targeted commands, 3K for broad commands, and a 100K hard ceiling. Contract metadata is preserved when output is truncated.
-- MCP uses snake_case command and parameter names. CLI uses hyphenated command and flag names.
-- To compare text, align compact/full settings and result caps. Surface-specific retry hints may still use CLI or MCP spelling.
+Publish-blocking semantic gates also compare stratified samples from pinned real repositories with independent language-native oracles: ts-morph, Pyright, gopls, rust-analyzer, JDT LS, clangd, and Roslyn. This validates the measured static evidence classes; it does not turn dynamic dispatch, generated code, reflection, or external dependencies into complete runtime knowledge.
 
-MCP keeps the process and project index warm across calls, so repeated MCP queries usually avoid CLI process startup. The semantic work and cache format are otherwise shared.
+MCP keeps its process and project index warm across calls. CLI and MCP share
+the same text budget: targeted commands default to 10K output characters,
+broad commands to 3K, with a 100K hard ceiling. Use CLI `--max-chars`, MCP
+`max_chars`, a narrower file/directory scope, or a smaller section projection
+when necessary. Truncation must retain the accounting/contract lines needed to
+interpret the answer, and the requested limit includes both the notice and the
+preserved metadata.
 
-## Read every answer as evidence, not proof
+Persistent indexes live in a per-user, project-keyed cache rather than the analyzed repository. Set `UCN_CACHE_DIR` to override the cache root; CLI `--no-cache` bypasses persistence and `--clear-cache` removes the current project's cache. Legacy `<project>/.ucn-cache` directories are migrated on first use.
 
-For `about`, `context`, and `impact`, interpret caller results in two bands:
+Supported source families are JavaScript/TypeScript/TSX, Python, Go, Rust, Java, C, C++, C#, and HTML inline JavaScript/event handlers. C/C++ uses `compile_commands.json` when available to classify headers and resolve include paths. Recoverable preprocessor branches contribute AST-proven source facts, so a single selected configuration does not silently erase definitions or calls; UCN still cannot prove which branch a particular build activates. This is portable AST analysis, not a compiler build; macros, templates, generated code, reflection, and external dependency semantics can remain unverified.
 
-- `CONFIRMED`: the call site has binding, receiver, import, or ownership evidence for the pinned target.
-- `UNVERIFIED`: the syntax could call the target, but the engine cannot prove the identity. Review these sites before a breaking change.
+`repo` readiness is task-specific. Its headline is navigation readiness;
+refactor, deletion, semantic recall, and the sampled evidence mix are separate
+dimensions. The confirmed/unverified percentage is a classification profile,
+not an accuracy grade.
 
-Then inspect all contract signals:
+## Interpret evidence correctly
 
-- `ACCOUNT` partitions literal-name text occurrences into confirmed, unverified, non-call, excluded, and unresolved buckets. It is an arithmetic conservation check, not a semantic-completeness claim.
-- `CONTRACT` states whether that literal-name partition is complete. `observed-text zero` means no caller was found in that observed text set. It does not prove semantic zero and is never safe-delete proof.
-- `WARNING` means parsing, reading, or indexing was incomplete. Inspect the named files with text search or the compiler.
-- `FILTERED` means flags hid evidence from display. Remove the filters before a breaking change.
-- `beyond-text callers` are alias- or binding-resolved edges that a literal grep would miss.
-- Numeric evidence scores are ordinal ranking weights, not calibrated probabilities or accuracy percentages.
-- Truncated MCP output preserves contract metadata when possible. If `contractMetadataComplete` is false, rerun with a larger output budget or narrower scope.
+For caller-bearing `show`, `impact`, `trace`, `tests`, and `check` views:
 
-Do not claim “no callers,” “safe to delete,” or “safe to refactor” from a zero result alone.
+- `CONFIRMED` has binding, receiver, import, or ownership evidence for the pinned target.
+- `UNVERIFIED` is a possible target with insufficient identity evidence. Review it before a breaking change.
+- `ACCOUNT` partitions observed literal-name lines into confirmed, unverified, non-call, excluded, and unresolved buckets. In mixed-language repositories it also counts occurrences in unsupported-language source files.
+- `CONTRACT` states the scope and completeness of that observed-text partition. When unsupported-language files contain the name, it says so explicitly and the partition-complete claim is limited to supported languages.
+- `WARNING` identifies unreadable, unparsed, or partially indexed files, and lists unsupported-language occurrence sites (file:line plus the line text) so nothing grep would show is hidden. `usages` and `tests` carry the same disclosure as a note.
+- `FILTERED` means query options hid evidence.
 
-## Match the command to the decision
+An observed-text zero is not semantic zero or safe-delete proof. Numeric evidence values are ordinal ranking weights, not probabilities.
+
+When a plain name selects more than one definition, action-oriented commands
+(`impact`, `tests`, `check`, and `plan`) carry the same ambiguity warning as
+`show`/`source`/`trace`. Prefer a stable handle; never treat the auto-selected
+definition as an implicit repository-wide target.
+
+## Choose a command
 
 | Decision | Command |
 |---|---|
-| Understand one symbol | `ucn about <handle> --compact` |
-| Direct change impact | `ucn impact <handle>` |
-| Transitive callers | `ucn blast <handle> --depth=3` |
-| Downward execution flow | `ucn trace <handle> --depth=3` |
-| Paths from entry points | `ucn reverse-trace <handle>` |
-| Tests affected by a change | `ucn affected-tests <handle>` |
-| Validate call-site arity | `ucn verify <handle>` |
-| Pre-commit review | `ucn check [--base=main]` |
-| Exact source extraction | `ucn fn <handle>` or `ucn class <handle>` |
-| All references, not only calls | `ucn usages <name>` |
-| Potentially unreachable code | `ucn deadcode` |
-| Index limitations and readiness | `ucn doctor --deep` |
-
-Use `trace` instead of repeatedly calling `about` down a pipeline. Use `blast` instead of repeatedly calling `impact` up a caller chain.
+| Orient or diagnose a repository | `ucn repo [--sections=files,stats,health] [--deep]` |
+| Understand one symbol | `ucn show <handle> [--sections=...]` |
+| Locate definitions or types | `ucn find <name> [--type=type]` |
+| Inspect literal-name occurrence kinds | `ucn usages <name>` |
+| Search literal text, explicit regex, or AST structure | `ucn search [term] [--regex] [--type=...]` |
+| Extract exact source | `ucn source <handle\|file:range>` |
+| Follow calls down or up | `ucn trace <handle> --direction=callees\|callers` |
+| Find paths to roots | `ucn trace <handle> --direction=callers --to=entrypoints` |
+| Assess direct or Git-diff impact | `ucn impact [handle]` |
+| Select direct or transitive tests | `ucn tests <handle> [--depth=N]` |
+| Validate a symbol or pending diff | `ucn check [handle]` |
+| Preview a refactor | `ucn plan <handle> --rename-to=X` |
+| Inspect file dependencies | `ucn deps <file> [--direction=...]` |
+| Find circular imports | `ucn deps --cycles` (project-wide; no file target) |
+| Inspect public surface | `ucn api [file]` |
+| Review entry points or HTTP routes | `ucn entrypoints`; `ucn endpoints` |
+| Generate review candidates | `ucn deadcode`; `ucn audit-async` |
+| Resolve runtime frames | `ucn stacktrace <text>` |
 
 ## Breaking-change protocol
 
-Before renaming, changing parameters, or changing behavior:
-
-1. Pin the exact definition with a handle.
-2. Run `impact`; review every unverified and warning entry.
-3. Run `blast` for transitive impact when behavior changes.
-4. Run `affected-tests`; treat “uncovered” as a test-planning signal, not proof of no coverage.
+1. Pin the exact definition with `find`.
+2. Run `impact`; review every unverified, excluded, filtered, and warning entry.
+3. Run `trace --direction=callers` for transitive behavioral impact.
+4. Run `tests --depth=3`; treat paths without static test links as test-planning signals, not runtime coverage proof.
 5. Make the change.
-6. Run `verify`, the relevant compiler or type checker, and the selected tests.
-7. Run `ucn check` to reconcile the repository diff.
-
-UCN augments the compiler and tests; it does not replace them.
+6. Run `check <handle>`, the relevant compiler/type checker, and selected tests.
+7. Run target-less `check` to reconcile the repository diff.
 
 ## Deletion protocol
 
-Treat `deadcode` as a candidate generator. Before deleting a symbol:
-
-1. Run `ucn deadcode`, then pin the candidate.
-2. Run `ucn usages <name>` to inspect calls, imports, type references, and non-call references.
-3. Run `ucn impact <handle>` and inspect `ACCOUNT`, `CONTRACT`, warnings, unverified sites, and beyond-text callers.
-4. Run `ucn entrypoints` and consider framework registration, reflection, serialization, dependency injection, public API use, and external consumers.
-5. Run `ucn doctor --deep`; inspect index health, evidence readiness, and the deletion review requirement.
-6. Delete only with corroborating compiler/type-checker and test evidence.
+Treat `deadcode` as a candidate generator. Before deletion, inspect `usages`, `impact`, `entrypoints`, `api`, and `repo --sections=health --deep`; then corroborate with the compiler/type checker and tests. Computed dispatch such as `handlers[key]()` is a reported blind spot; registry members reached by a modeled computed receiver are withheld. Unknown decorators/annotations and member-assigned event handlers are also withheld by default because they can be the registration itself. All remaining candidates are still review-only. Never delete solely from `deadcode` or an observed-text-zero result.
 
-Never delete solely because `deadcode` or an observed-text-zero contract reports zero callers.
+`usages` includes comment/string/docstring occurrences in an `OTHER TEXT` section unless
+`--code-only` is set. This is a literal-name inventory, not exact target
+binding. `search` treats its term literally by default; pass `--regex` only
+when regular-expression semantics are intended. Ordinary regex patterns run
+through an RE2-compatible linear-time engine; unsafe nested repetition is
+rejected, and unsupported advanced syntax should be handed to ripgrep.
 
-## Ambiguity and dispatch
+`find` activity counts are definition-pinned: confirmed plus visible unverified
+call candidates. Calls proved to belong to another same-name target are
+disclosed separately and excluded from the activity total.
 
-- Prefer handles over a plain symbol name.
-- Use `--class-name=<Class>` or `--file=<pattern>` only when a handle is unavailable.
-- Treat `possible-dispatch`, `method-ambiguous`, `alias-call`, and `call-not-resolved` as review-required.
-- Tree trunks contain confirmed edges. Unverified edges are separate and are not expanded unless `--expand-unverified` is requested.
-- Following an unverified edge produces a possible-impact chain, not a confirmed chain.
+`plan` always includes the selected declaration plus indexed call/import/export
+previews. Read `changeSummary`, and manually review any edit marked
+`needsReview`; the command previews changes but does not apply or compile them.
 
-## Efficient output
+## Efficient use
 
-- Use `--compact` for agent context and `--json` for automation.
-- Use `--exclude=test` only for a production-only view; rerun without it before a breaking change.
-- Use `--all` when a section says results were capped.
-- Use `--no-cache` after edits if cache freshness is in doubt.
-- Use `ucn search` for text or structural queries; use ordinary repository search for file names and unsupported syntax.
+- Prefer handles over plain names. Use `--class-name` or `--file` only when a handle is unavailable.
+- Use `--sections` to request only the `show` or `repo` evidence needed.
+- Use `--expand-unverified` only when deliberately exploring possible caller chains; those descendants remain possible, not confirmed.
+- Use `--all` only when that command's output reports a supported cap; otherwise narrow the query or raise `--max-chars`.
+- Use `search` or ordinary repository search for text, filenames, configuration, and unsupported syntax.
 
-Read [references/commands.md](references/commands.md) when a less common command or flag is needed. Read [references/trust-contract.md](references/trust-contract.md) before building automation that gates changes on UCN output.
+Read [references/commands.md](references/commands.md) for all public commands and flags. Read [references/trust-contract.md](references/trust-contract.md) before building automation that gates changes on UCN output.

package/.claude/skills/ucn/references/commands.md

@@ -1,93 +1,87 @@
 # UCN command reference
 
-## Navigation and extraction
+UCN exposes exactly 18 task-oriented public commands. CLI uses hyphenated names; MCP uses snake case.
+
+Use grep/ripgrep for simple literals, error messages, configuration, filenames,
+Markdown, and unsupported languages. Use UCN for exact symbol identity,
+callers/callees, change impact, test linkage, dependency/API questions, and AST
+structural or code-only search.
+
+## Understand and navigate
+
+| Command | Purpose |
+|---|---|
+| `show <handle>` | Default symbol summary, callers, and callees. Select `summary,callers,callees,source,dependencies,tests,types,example,related` with `--sections`. |
+| `find <name>` | Locate definitions and stable handles. Activity counts are pinned call candidates (confirmed + visible unverified); proved other-target calls are separate. Use `--type=type`, `--limit=N`, and `--with-source` as needed. |
+| `usages <name>` | Inventory definitions, calls, imports, type references, and literal comment/string/docstring text. Those text sites appear under `OTHER TEXT` unless `--code-only`. |
+| `search [pattern]` | Literal text search by default; add `--regex` for RE2-compatible linear-time regular expressions, or use structural filters such as `--type`, `--param`, `--receiver`, `--returns`, or `--decorator`. Unsafe nested repetition is rejected; use ripgrep for unsupported advanced syntax. |
+| `source <handle\|file:range>` | Extract a function, class-like declaration, or exact line range. |
+| `trace <handle>` | Traverse callees by default. Use `--direction=callers` for blast radius and add `--to=entrypoints` for paths to roots. |
+
+## Change and validation
 
 | Command | Purpose |
 |---|---|
-| `orient` | Repository size, languages, hot symbols, entry points, and readiness summary |
-| `toc` | Files and symbol counts; add `--detailed` for symbol listings |
-| `find <glob>` | Find definitions and obtain stable handles |
-| `fn <handle>` | Extract a function without reading the whole file |
-| `class <handle>` | Extract a class or class-like declaration |
-| `lines <start-end> --file=<path>` | Extract an exact line range |
-| `brief <handle>` | Signature, documentation sentence, effects, and complexity |
-| `about <handle>` | Definition, callers, callees, tests, source, and contracts |
-| `context <handle>` | Compact callers/callees without the full source body |
-| `smart <handle>` | Symbol source plus directly used helpers |
-| `example <handle>` | Best confirmed usage example; abstains when only unverified calls exist |
-| `related <handle>` | Advisory sibling ranking from names, files, and shared dependencies |
-| `expand <N>` | Expand a numbered item from a prior context result |
-
-## Calls, impact, and refactoring
+| `impact [handle]` | Show direct symbol impact when given a handle; without one, analyze the Git diff. |
+| `tests <handle\|file>` | Find statically linked direct tests. Set `--depth=N` for transitive affected tests. Empty results are not runtime coverage proof. |
+| `check [handle]` | Validate confirmed call-site arity for a symbol; without one, run the composed pre-commit diagnostic. |
+| `plan <handle>` | Preview `--rename-to`, `--add-param`, or `--remove-param` edits, including the selected declaration and indexed call/import/export sites. Review `changeSummary` and `needsReview`. |
+
+## Repository and architecture
 
 | Command | Purpose |
 |---|---|
-| `impact <handle>` | Direct callers grouped by evidence tier |
-| `blast <handle>` | Transitive caller tree |
-| `trace <handle>` | Transitive callee tree |
-| `reverse-trace <handle>` | Caller paths toward entry points |
-| `affected-tests <handle>` | Tests reachable from affected code |
-| `verify <handle>` | Check confirmed call sites against the target signature |
-| `plan <handle> --rename-to=X` | Preview a rename or parameter edit |
-| `diff-impact [--base=REF]` | Changed symbols and caller impact from a Git diff |
-| `check [--base=REF]` | Diff impact, signature checks, and affected tests |
-
-## Search, graph, and maintenance
+| `repo` | Repository orientation. Select `summary,files,stats,health` with `--sections`; `--deep` includes readiness evidence. Skipped unsupported source is listed with a grep/language-tool handoff. |
+| `deps <file>` | File dependency graph. Use `--direction=imports\|importers\|both`, `--detailed`, or `--cycles`. |
+| `api [file]` | Static exported/public surface for a project or file. |
+| `entrypoints` | Framework, route, task, test, and runtime entry points. |
+| `endpoints` | Server/client HTTP surface; `--bridge` adds advisory matching. |
+
+## Focused audits and runtime evidence
 
 | Command | Purpose |
 |---|---|
-| `search <pattern>` | JavaScript-regex text search; add `--no-regex` for literal search |
-| `search --type=function --param=X` | Structural symbol search |
-| `search --type=call --receiver=db` | Structural call-site search |
-| `usages <name>` | Definitions, calls, imports, types, and other references |
-| `typedef <name>` | Type, interface, enum, struct, trait, class, and record definitions |
-| `tests <name>` | Test files and test functions associated with a symbol |
-| `imports <file>` | Dependencies of a file |
-| `exporters <file>` | Files depending on a file |
-| `file-exports <file>` | Symbols exported by a file |
-| `graph <file> --depth=N` | File dependency tree |
-| `circular-deps` | Import cycles |
-| `api` | Exported/public project surface |
-| `stats` | Project counts; add `--hot` or `--functions` for deeper reporting |
-| `entrypoints` | Framework, route, task, test, and runtime entry points |
-| `endpoints --bridge` | Advisory server-route/client-request matching |
-| `deadcode` | Unreferenced-symbol candidates |
-| `audit-async` | Potential missing-await sites in JS/TS/Python |
-| `stacktrace <text>` | Advisory stack-frame parsing and source lookup |
-| `doctor --deep` | Index health, blind spots, evidence profile, and task readiness |
+| `deadcode` | Conservative unreferenced-symbol candidates for review. Modeled computed-dispatch members, unknown decorated/annotated callables, and member-assigned event handlers are withheld by default. |
+| `audit-async` | Potential missing-await sites in JavaScript/TypeScript/Python and C#. MCP spelling: `audit_async`. |
+| `stacktrace <text>` | Advisory stack-frame parsing and source lookup. |
 
 ## Stable symbol identity
 
-Commands that list symbols emit handles such as `src/api.ts:42:handler`. Pass the full handle to any command accepting a symbol. `path:line` also works. Handles avoid silently combining same-named definitions.
+Symbol-listing commands emit handles such as `src/api.ts:42:handler`. Pass the full handle to symbol commands. `path:line` also works. Handles prevent same-named definitions from being silently combined.
 
 ## Common flags
 
 | Flag | Meaning |
 |---|---|
-| `--file=<pattern>` | Scope or disambiguate by file |
-| `--class-name=<name>` | Scope a member to a class |
-| `--in=<directory>` | Limit indexing/query scope |
-| `--exclude=<patterns>` | Exclude matching paths from displayed analysis |
-| `--depth=N` | Control tree depth |
-| `--all` | Lift output caps where supported |
-| `--compact` | Reduce previews and source for agent-efficient output |
-| `--json` | Machine-readable output |
-| `--expand-unverified` | Follow possible caller edges and mark resulting chains unverified |
-| `--base=<ref>` | Compare Git changes with a ref |
-| `--staged` | Analyze staged changes |
-| `--no-cache` | Rebuild instead of loading the project cache |
-| `--clear-cache` | Remove the project cache before rebuilding |
-| `--workers=N` | Set build-worker count; `0` disables parallel build |
-| `--include-exported` | Audit exported symbols in `deadcode` |
-| `--include-decorated` | Audit decorated symbols in `deadcode` |
-| `--code-only` | Exclude comments and strings in text usage/search |
-
-`--include-uncertain` and `--include-methods` do not reveal hidden caller evidence in contracted caller commands; those commands already show possible sites in the unverified band. Evidence filters can hide displayed results, so inspect `FILTERED` and rerun without filters before breaking changes.
+| `--sections=a,b` | Select `show` or `repo` projections. |
+| `--file=<pattern>` | Scope or disambiguate by file. |
+| `--class-name=<name>` | Scope a member when no handle is available. |
+| `--in=<directory>` | Limit query scope to a directory. |
+| `--exclude=<patterns>` | Exclude matching paths. |
+| `--depth=N` | Set trace/dependency/test traversal depth. |
+| `--direction=<value>` | Select trace or dependency direction. |
+| `--all` | Lift result and formatter caps where supported. It is recommended only for commands that accept it. |
+| `--max-chars=N` | Set the hard CLI text budget, including notices and preserved trust metadata (10K targeted / 3K broad by default; 100K ceiling). MCP spelling: `max_chars`. JSON is not transport-truncated. |
+| `--compact` / `--no-compact` | Select token-efficient or full semantic output. |
+| `--range=N-M` | Extract an explicit line range with `source --file=<path>`. |
+| `--json` | Emit the stable CLI `{ meta, data }` envelope; `meta.contract` carries the truth boundary, decision safety, and next actions. |
+| `--expand-unverified` | Follow possible caller edges while preserving their unverified status. |
+| `--base=<ref>` / `--staged` | Scope Git-diff `impact` or target-less `check`. |
+| `--no-cache` / `--clear-cache` | Bypass or clear the current project's per-user cache. Set `UCN_CACHE_DIR` to override its root. |
+| `--workers=N` | Set build workers; `0` disables parallel build. |
+| `--include-exported` | Include exported symbols in `deadcode`. |
+| `--include-decorated` | Include decorated symbols in `deadcode`. |
+| `--code-only` | Exclude comments and strings in `search`/`usages`. |
+| `--regex` | Interpret a `search` term as a regular expression. Without it, the term is literal. |
 
 ## Target forms
 
 ```text
-ucn [target] <command> [symbol] [flags]
+ucn [target] <command> [argument] [flags]
 ```
 
-Omit `target` for the current project. A target may be a file, directory, or quoted glob such as `"src/**/*.py"`.
+Omit the target for the current project. A target may be a file, directory, or quoted glob such as `"src/**/*.py"`.
+
+## Language notes
+
+Supported source families are JavaScript/TypeScript/TSX, Python, Go, Rust, Java, C, C++, C#, and HTML inline JavaScript/event handlers. C/C++ consumes `compile_commands.json` when present for header-language and include-path context, and retains AST-proven facts across recoverable preprocessor branches. UCN remains portable AST analysis: it does not run a compiler, preprocessor, Roslyn, or an LSP during normal queries, and it does not assert which conditional branch a build activates.

package/.claude/skills/ucn/references/trust-contract.md

@@ -8,9 +8,9 @@ Use this reference when an agent, CI job, or script will make decisions from UCN
 
 `unverified` means a syntactic candidate could reach the target but identity could not be established. Preserve and expose these edges. Do not silently treat them as negatives.
 
-`excluded` means the engine found evidence for a different definition, an incompatible receiver, an external package, an arity mismatch, or another stated reason. Inspect excluded reasons when investigating an accuracy issue.
+`excluded` means the engine found evidence for a different definition, an incompatible receiver, an external package, an unrelated runtime-language boundary, an arity mismatch, or another stated reason. Inspect excluded reasons when investigating an accuracy issue.
 
-`non-call` means the literal name occurred as a definition, import, type reference, property, comment/string, or other text. Use `usages` for the underlying sites.
+`non-call` means the literal name occurred as a definition, import, type reference, property, comment/string, or other text. Use `usages` for the underlying sites; comment/string occurrences appear under `OTHER TEXT` unless `codeOnly=true`.
 
 `beyond-text` means semantic binding or alias evidence produced an edge that a literal-name ground set could not observe.
 
@@ -26,8 +26,10 @@ Required automation checks:
 4. No contract metadata was lost to truncation.
 5. Unverified and excluded reasons are retained for review.
 6. Compiler/LSP evaluation reports keep configuration-unscored evidence below the release ceiling; a high-precision result from an undersized scored subset is not accepted.
+7. The release review-burden board passes: true edges left unverified, zero-actionable-ambiguity target rate, actionable candidate p95, and effective unverified review items per oracle edge all remain within the published budget. Raw false candidates remain reported separately.
+8. The deterministic cross-command board reports zero disagreements: overlapping `find`, `show`, `source`, `impact`, `tests`, `check`, and caller `trace` claims resolve the same stable handle to the same identity, projections, caller tiers, evidence reasons, totals, and caller account.
 
-Even when all five hold, `account.contract.semanticComplete` remains false. Use compiler/type-checker, test, runtime, and framework evidence for semantic decisions.
+Even when all eight hold, `account.contract.semanticComplete` remains false. Use compiler/type-checker, test, runtime, and framework evidence for semantic decisions.
 
 `account.contract.observedTextZero` is safe only for the claim “the complete observed literal-name ground set contained no caller candidates or beyond-text edges.” It is explicitly not safe-delete proof.
 
@@ -35,9 +37,28 @@ Even when all five hold, `account.contract.semanticComplete` remains false. Use
 
 `evidenceScore` (and the legacy `confidence` alias where present) is an ordinal weight used for ordering and thresholding evidence classes. `scoreKind` is `ordinal-evidence-not-probability`. Never display it as measured accuracy or use it as a probability in risk calculations.
 
+## Unverified review burden
+
+Semantic recall can be complete while the result is still impractical: a true edge may be present only in a large unverified set. Release evaluation therefore measures both placement and the amount of review an agent must perform.
+
+- `trueEdgeUnverifiedRate` is the share of semantic oracle edges found only in the unverified tier.
+- `zeroActionableUnverifiedTargetRate` is the share of reviewed targets with no actionable ambiguity.
+- `actionableUnverifiedCandidatesP50`, `actionableUnverifiedCandidatesP95`, and `actionableUnverifiedCandidatesMax` measure actionable candidate-set size per target.
+- `unverifiedReviewItemsPerOracleEdge` measures effective review work relative to the oracle workload. Actionable false candidates count individually; each named runtime-dispatch family counts once.
+- `rawFalseUnverifiedPerOracleEdge` preserves the ungrouped false-candidate amplification for auditability.
+- `unverifiedReasons` groups candidates by the engine reason that kept them out of the confirmed tier.
+
+Configuration-gated candidates remain visible but are not labeled false when the compiler/LSP oracle did not score them. The raw JSON rollup is the source of truth for these fields; the Markdown report is generated from the same data.
+
+The publish-blocking portable-AST ceilings are: at most 10% of exact true edges left unverified, at most 20% within any sufficiently sampled symbol kind, at least 80% of targets with zero actionable ambiguity, actionable-candidate p95 at most five, and at most 0.10 effective review items per oracle edge. The semantic gate separately requires 100% in-scope recall, at least 98% confirmed-tier precision, full conservation, and 100% public-command proof recall. Passing these sampled floors is release evidence, not runtime-completeness proof.
+
+The performance gate runs each pinned repository in three independent processes with a fixed worker shape. Publish and PR gates require both CPU and wall-throughput floors on the median run, pin the expected file/LOC workload, and use the worst observed build/full-board peak RSS so memory failures cannot be averaged away. Exploratory one-process runs keep wall throughput diagnostic. Scoped reports are separate from the full release artifact; the dated rollup is release-qualified only when every required row came from a full release invocation. The composite release gate runs this stage first so verbose compiler-oracle output and report consumers cannot perturb its samples.
+
 ## Truncation
 
-MCP results may include:
+CLI and MCP text share the same 10K targeted / 3K broad default budgets and
+100K ceiling. CLI truncation appends preserved contract lines directly. MCP
+results may additionally include:
 
 ```json
 {
@@ -57,7 +78,11 @@ Allow an automated change to proceed to compiler/tests only when:
 - the account is conserved and text-complete;
 - warnings and filtered counts are zero;
 - unverified sites are either zero or explicitly reviewed;
-- UCN doctor reports no parse failure/recovery and its task-specific readiness has been reviewed;
+- `ucn repo --sections=health --deep` reports no parse failure/recovery and its task-specific readiness has been reviewed;
+- the repo health report lists no unsupported source handoff relevant to the change;
 - the change is still validated by the language toolchain and relevant tests.
 
-Never auto-delete from a UCN-only signal. Require usages, entry-point review, public API review, and external validation.
+Never auto-delete from a UCN-only signal. Computed dispatch is reported as a
+health blind spot, and modeled registry members are withheld from candidates,
+but neither protection proves runtime reachability. Require usages, entry-point
+review, public API review, and external validation.