Rename Concept

/rename-concept

C# semantic branch

Run the sibling _csharp-semantic provider from its guide, then enter through scripts/assess_csharp_rename.py; knowledge/csharp-v1.md gives the exact consumer command. This is selected-source, Roslyn-resolved assessment only. Reflection/runtime names, dynamic and virtual dispatch, generated/vendor inputs, external consumers, serialization, frameworks, binary compatibility, codemod safety, and mutation remain outside the claim.

Kotlin/JVM 2.4.10 branch

Trigger this assess-only branch only for an exact kotlin-semantic-project.json target. Keep sibling _kotlin-semantic, read ../_kotlin-semantic/GUIDE.md, produce its pinned fact pack, then enter through scripts/assess_kotlin_rename.py. Exact selected-source declarations and resolved references come from a deprecated K1 API, not a stable Analysis API, and do not cover strings, reflection/callable references, aliases, named arguments, overrides or delegation, generated/plugin sources, Gradle variants, Java/external callers, runtime/framework compatibility, ABI, codemod safety, or mutation.

Swift 6.3.3 semantic branch

Use scripts/swift_identifier_evidence.py only with one current complete swift-semantic-facts-v2 pack from sibling _swift-semantic-readonly. The assessment separates exact selected-target old/new declarations and references from comments, strings, excluded roles, and unrelated lexical matches; it applies no edit. Conditional compilation, reflection, Objective-C/dynamic or protocol dispatch, generated inputs, external modules, frameworks, ABI, codemod safety, and mutation remain unresolved.

C++20 branch

Use scripts/assess_cpp_rename.py with _cpp-semantic; run the script with --help for the exact CLI. It is assessment-only across a current complete C++20 compiler-owned graph and separates exact namespace/signature/overload identity from macro/string residue. ODR/ABI/linkage, specializations, ADL, dynamic dispatch, external variants, codemod safety, and mutation are refused.

C17 branch

Use scripts/assess_c_rename.py with the sibling _c-semantic provider; run the script with --help for the exact CLI. This external-library branch is assessment-only. Macros, strings, inactive variants, external consumers, ABI compatibility, arbitrary build variants, codemod safety, and mutation remain unresolved.

PHP and Ruby

For a selected PHP or Ruby assessment, load ../_php-semantic/GUIDE.md or ../_ruby-semantic/GUIDE.md. These branches assess bounded declared identifier evidence only; reflection, strings, frameworks, runtime consumers, codemods, and rename safety remain unresolved.

Dart v1

Dart v1 is assess-only. It uses the sibling map-subsystem SDK-LSP provider for bounded public old/new identifier authority and preserves strict-text prose/string evidence as deferred. It never applies the LSP rename edits it probes. Package imports require a pre-existing hashed package configuration.

SKILL_ROOT=".agents/skills/on-demand/rename-concept"
python3 "${SKILL_ROOT}/scripts/assess_dart_rename.py" \
  "${OLD_CONCEPT:?Set the old concept}" \
  "${NEW_CONCEPT:?Set the new concept}" \
  --project-root "$PWD" --target . \
  --output "$PWD/reports/rename-concept/assessment.json"

Parts, generated APIs, conditional configurations, reflection/string linkage, external compatibility, codemod safety, and Flutter assets/routes are explicit non-claims.

Rust v1 assessment

Rust adds read-only identifier authority to the existing lifecycle and strict text gate. It resolves bounded public top-level old/new type declarations and references, but never applies a rename or claims macro, associated-item, reflection-string, cfg, generated, external-API, or compatibility coverage. The copied closure includes sibling map-subsystem and the existing find-concept-divergence companion.

Run the normal scripts/assess.py command. It discovers Rust sources and invokes scripts/rust_identifier_evidence.py; a Rust assessment cannot be complete when native authority or deferred reference evidence is unresolved.

Read-only assessment of a domain-concept rename against its lifecycle and a two-band completeness gate. Renaming a concept in a glossary-backed codebase is a multi-step lifecycle (decide → glossary → identifier sweep → guard lint → cross-tool mirror sync → correct old prose/docs) that, executed from tribal knowledge with no completeness gate, predictably lands half-applied. This skill sequences and verifies the existing mechanisms; it does not reimplement them.

The canonical glossary is .claude/contracts/concepts.yaml; the detector this skill drives is /find-concept-divergence.

Mode: assess — read-only lifecycle status + completeness gate

.venv/bin/python .claude/skills/rename-concept/scripts/assess.py <old> <new> \
  [--min-blast N] [--project-root DIR] \
  [--output reports/rename-concept/<assessment>.json]

Install this skill together with its detector companion, find-concept-divergence. Its installed scan.py is the single authority for both lexical bands; rename-concept does not copy or fork its matching logic. Repository development may use the source-tree sibling. A copied rename-concept without that installed companion is inconclusive.

On-demand library (default)

When a router supplies this guide from the non-discovered library, use the router's exact guide, bundled_tooling, and companion paths. Run scripts/assess.py from this guide's directory and locate find-concept-divergence beside it in the library. Do not substitute the .agents/skills/ path shown in the optional installed example below.

For non-trivial work, the router should give this guide, both skill-local tool paths, the project root, and the task to a fresh non-context sub-agent. The primary agent need not load either skill body.

Optional ambient install

Set ENGINEERING_SKILLS_SOURCE to the published source URI or a local checkout when the user explicitly requests installation. The command below projects the two required skills; assessment remains read-only.

: "${ENGINEERING_SKILLS_SOURCE:?Set this to the engineering-skills source URI or local checkout}"
DO_NOT_TRACK=1 npx --yes skills@1.5.19 add \
  "$ENGINEERING_SKILLS_SOURCE" \
  --skill rename-concept find-concept-divergence --agent codex --copy -y

For a TypeScript/TSX host, the project must pin typescript in its own package.json and lockfile. Install that declared host dependency before assessment; it must resolve from inside the project root. The skill never downloads or substitutes an ancestor compiler.

npm ci --offline --ignore-scripts

PROJECT_ROOT="$PWD"
RENAME_CONCEPT_SKILL="$PROJECT_ROOT/.agents/skills/rename-concept"
(
  cd "$RENAME_CONCEPT_SKILL"
  python3 scripts/assess.py \
  "${OLD_CONCEPT:?Set the deprecated glossary concept}" \
  "${NEW_CONCEPT:?Set its canonical glossary concept}" \
    --project-root "$PROJECT_ROOT" \
    --output "$PROJECT_ROOT/reports/rename-concept/assessment.json"
)

The scanner interprets scan targets and exclusions relative to --project-root. It excludes an ignored directory or file even when passed directly, and never follows a symlink that resolves outside the target project. This protects a host nested under a path named node_modules while still excluding its own node_modules/, dist/, and migration trees.

On a project containing .ts or .tsx, assessment runs the host-pinned Compiler API after the lexical scan. It reports the compiler version, resolved old/new declaration/reference counts, and a classification for every lexical old/new candidate. If the host compiler is unavailable, an old-concept symbol remains, a candidate cannot be resolved, or no new-concept declaration exists, or parsing/relevant resolution diagnostics are present, the verdict stays incomplete. --output persists this exact read-only evidence as JSON; it accepts only logical paths inside <project-root>/reports/rename-concept/. Source paths, paths outside that subtree, and any existing output/ancestor symlink component beneath the logical report path are rejected before parent directories are created — including an in-project symlink that redirects reports/ into source. It never alters a host source file.

Reports, read-only:

• scope-gate — is <old> a glossary concept and/or a wide-blast rename (≥ --min-blast live files, default 3), or a trivial local one the skill should bail on? Anchored at --project-root (default: git toplevel of the cwd, else the cwd) so the verdict never depends on where inside the target repo the caller sits — and never silently inspects the kit's own repo.
• lifecycle status — a per-step table: is concepts.yaml's old entry marked superseded_by: <new>; does a no_<old>_references reintroduction lint exist under scripts/lint/; how many live-code files still mention the old token (allowlisted residue — the ADR tree, the glossary, this skill, the detector, reports, migrations — excluded).
• completeness gate — the two-band /find-concept-divergence result, filtered to this rename. This is the definition of done.

For Go targets, read knowledge/go-v1.md only when needed. assess.py invokes the bundled resolver automatically after the coupled lexical scan; missing, old, partial, or diagnostically unresolved Go evidence prevents completion.

For Java targets, read knowledge/java-v1.md. The copied skill uses JDK 17 compiler tree/type facts for public top-level authority and bounded impact evidence while retaining the companion's strict-text sweep.

--min-blast tunes the scope-gate threshold.

Definition of done = the completeness gate (two bands)

The visible part of a rename (the identifier sweep) is the part a rushed pass stops at. This skill refuses to call a rename complete while EITHER /find-concept-divergence band is dirty, any lifecycle step is unresolved, or TypeScript/TSX identifier completeness is unproven. assess.py requires the host-pinned Compiler API result in addition to a green lexical scan. assess.py runs the coupled detector ONCE and consumes only its two rename-relevant bands for this rename:

• Band 3 — superseded_co_occurrence (lexical old/new candidates): the old name and the new name must not co-occur as glossary terms in a scanned file. This is an actionable text candidate. The Compiler API evidence section maps it to an old-concept symbol, a shadowed local, import alias, property key, string, comment, or unresolved identifier before the verdict uses it. Caveat: when the old concept declares a coverage_lint: in concepts.yaml, /find-concept-divergence skips this band (the lint owns identifier enforcement) — so for a lint-guarded rename band 3 is structurally empty and band 1 is what actually proves the work.
• Band 1 — avoid_term_hit (TERM-level prose): no file may still use a phrasing the glossary's avoid: block forbids for this rename. The avoid: block lives on the new/canonical concept (the new slug carries the retired phrasings the old name used). This band is not skipped for coverage_lint concepts, so it sees the comments / docstrings / strings the lint and band 3 are both blind to. This is the prose-blindness fix: the gate verifies the retired term was corrected, not just the identifier.

For a non-TypeScript project, the lexical gate is GREEN only when both bands ran and are empty. A band-1 hint alone — with band 3 green — turns the verdict to HALF-APPLIED / INCOMPLETE. For a TypeScript/TSX project, both bands must be green and the Compiler API must resolve the expected new declaration with zero old-concept references or unresolved identifier candidates, and no parsing or candidate-resolution diagnostics. The authority surface is intentionally limited: only matching top-level exported declarations can establish the old/new concept symbols. Same-named internal declarations never certify a rename.

Two-tier model for stale prose

The gate verifies the term, not the substance:

• TERM-stale prose — text still uses the old word. This is gate-enforced: /find-concept-divergence band 1 greps the canonical concept's avoid: block, and assess.py turns the verdict RED on any hit.
• SUBSTANCE-stale prose — the explanation is now wrong because the rename changed what the concept IS, even after the old word is gone. The gate does not catch this — it is surfaced by /find-comment-drift and corrected by human / LLM judgment. Running the term gate green is necessary but not sufficient; a substance pass is the human's job.

Deferred (v1 gap): the write half / codemod

This is v0, assess-only. The write half that the lifecycle implies — authoring a dry-run-ready identifier-codemod plan, scaffolding a no_<old>_references reintroduction lint, and emitting a checklist — is not yet ported. It depends on a codemod harness (a tools/rename-style runner) that this ecosystem does not currently ship, so there is nothing to author a plan for. When such a harness exists, a orchestrate.py (propose-only: authors a plan + a lint scaffold, then STOPS before any --apply) is the intended v1 follow-up, gated so a human reviews the plan + the dry-run diff + the long-tail inventory before applying. Until then:

• the identifier sweep is a manual / IDE step the human performs;
• path moves that are part of the rename should use /move-path with a reviewed moves.yml plan; it updates filesystem/path references, not identifier or prose terminology;
• the guard lint (no_<old>_references) is authored by hand and wired into the lint runner by a human;
• the lifecycle steps assess.py reports on but does not author are: the ADR content (via /decide), the cross-tool mirror sync (.augment/ + AGENTS.md and the other symlinked mirrors), and correcting old prose/docs — the term-stale half is gate-enforced (band 1), the substance-stale half is a human /find-comment-drift pass.

Out of scope: --apply

Even when the write half lands, applying a wide identifier sweep is human-approval-gated by design: a human reviews the authored plan, the dry-run diff, and the long-tail inventory, then applies and verifies. The skill authors and proposes; it does not decide and it does not apply.

TypeScript / TSX boundary

Treat .ts and .tsx as a two-stage surface. The lexical bands find a glossary-listed old/new term pair or exact retired phrase, including JSX text and comments. The bundled runner then uses the host's pinned TypeScript Compiler API on root-contained TS/TSX files selected by the coupled scanner's default surface and classifies each lexical old-name candidate: old_concept_symbol, shadowed_local, import_alias, property_key, string_literal, comment_text, or unresolved_identifier.

Only matching top-level exported declarations establish rename authority; internal/unexported declarations are reported but cannot establish completion. The runner reads the host tsconfig.json when available and blocks completion on invalid tsconfig/parser diagnostics or semantic diagnostics that affect candidate/module/name resolution. It never mutates source. It does not make a whole-project type-check pass a completion condition, rewrite identifiers/imports, resolve dynamic behavior, or prove an IDE codemod is safe. Keep code mutation outside this assess-only skill.

Pairs with /find-incomplete-sweep: this assesses whether a rename is done; that catches a half-done sweep after the fact.

Checked JavaScript boundary

The JavaScript evidence runner is available only when the host has its own typescript package and an explicit jsconfig.json or tsconfig.json with allowJs and checkJs enabled. It preserves the same distinction between resolved exported symbols, aliases, shadowed locals, property keys, and unresolved identifiers, while retaining strings/comments as non-identifier boundary evidence. It accepts .js, .jsx, .mjs, and .cjs without framework inference.

The emitted assessment JSON records the selected config, compiler diagnostics, uncovered sources, and separate checked-JavaScript, JSDoc, and inferred evidence. A missing config/compiler is unsupported, malformed selected JS is syntax-error, and unresolved or excluded relevant JS makes completion partial; none is converted to a lexical clean result. The copied skill retains its family-local runner and still requires the declared find-concept-divergence companion for the lexical gate. It never uses npx, a global compiler, or mutates source.

Go boundary

The Go branch combines the companion's bounded strict-text inventory with a skill-local Go 1.22+ go/types resolver. Only matching exported package-scope declarations establish concept authority. Resolved references to those objects are concept-symbol evidence; same-named locals, fields, import aliases, and external symbols remain classified boundary evidence. Tests, generated source, inactive build files, malformed packages, and unavailable tools cannot be silently treated as clean. The branch is assessment-only and never performs a rename or claims codemod safety.

Java boundary

Use JDK 17 JavacTask.parse() plus analyze(). Only one compiler-resolved public top-level TypeElement can establish each concept identity; lexical candidates never establish rename authority. Keep same-spelled locals as unrelated evidence. Defer reflection, strings, dynamic lookup, annotations/framework behavior, generated/test/vendor/build source, symlinks, ambiguous authorities, and incomplete compilation. Emit JSON plus Markdown impact artifacts and never mutate source.