Issue: #205 — normalize reusable identifiers away from product names.
This audit records the current kapi / ilchul surface classification for the first migration slice. It is intentionally not a mechanical replacement list: each remaining occurrence should keep a reason or move in a scoped follow-up.
git grep -n -i -E 'kapi|ilchul' -- ':!package-lock.json' ':!node_modules'| Surface | Current state | Classification | Follow-up direction |
|---|---|---|---|
| Package metadata | package.json is still named ka-pi; package bins include only public ilchul; review automation is owned by the external kapi-agent github-bot adapter, and there is no kapi runtime bin. |
package brand / external review integration | Do not retain a kapi runtime CLI alias. Prefer ilchul for public runtime docs and examples; reserve runctl for internal runtime implementation naming. Do not add an Ilchul package review bin; keep kapi-agent and kapi-agent/review as GitHub integration names while the GitHub App uses them. |
| CLI runtime entrypoint | src/cli/runctl-cli.ts and related tests use semantic runtime names. This slice keeps the public ilchul command wired through the internal bin/runctl.mjs wrapper and semantic parseRuntimeArgs / runRuntimeCli exports, removes the old bin/kapi.mjs shim, and verifies package-local/prefix installs do not expose kapi. |
public brand command with internal semantic implementation | Internal runtime callers should import from src/cli/runctl-cli.ts and use semantic runtime exports; product-named runtime command aliases must not be reintroduced at the package/bin edge. |
| CLI setup helper | setup:cli still invokes scripts/setup-runctl-cli.mjs, but its completion text now points to ilchul --help. |
internal semantic filename plus brand-facing user guidance | Keep output brand-facing where users see it and implementation filename semantic internally. |
| Slash commands and workflow IDs | /kapi-*, kapi-ralph, kapi-autoresearch, and related state fields remain serialized workflow contracts. |
persisted compatibility identifiers | Do not rename without an explicit compatibility/deprecation migration. |
| Storage/config | .ilchul, ~/.ilchul, .kapi historical references, and ILCHUL_* environment variables appear in docs/tests/runtime setup. |
storage/config namespace | .ilchul is active storage; .kapi is legacy evidence only and must not be deleted by this issue. |
| GitHub review integration | kapi-agent and kapi-agent/review remain literal GitHub integration names; deterministic review-gate automation is owned by the github-bot adapter, not an Ilchul package bin. |
external integration | Keep literal names while the GitHub App and required checks use them. |
| Documentation/history | README, policy docs, references, and historical explanations still mention Kapi and Ilchul. | documentation/history | New public runtime examples should use ilchul; internal implementation examples may use runctl / runtime; historical and compatibility prose may keep product names with context. |
| Core/domain/application identifiers | The registry entry type now uses WorkflowRegistryEntry; the store interface/class now use WorkflowStore / FileWorkflowStore; the service class and active tests now use WorkflowService without the temporary KapiService compatibility export. |
reusable-code leakage removed from the active service/store surface | Keep future reusable service/store imports on the semantic Workflow* names. |
| Application service filenames | The service implementation and factory now use semantic filenames: src/application/workflow-service.ts and src/adapters/workflow-service-factory.ts; the primary exported service class is now WorkflowService. |
internal semantic implementation | Keep imports on the semantic service paths; do not reintroduce a product-named service alias for reusable internal code. |
| CLI worker/runtime helper filenames | Worker event, runtime observation, and GitHub issue context helpers now use semantic filenames: src/cli/worker-events.ts, src/cli/worker-runtime.ts, and src/cli/github-issue-context.ts. |
internal semantic implementation | Keep imports on the semantic helper paths; remaining worker event payload names such as kapi.worker.* are external event contracts, not filenames. |
ilchul --helpis tested as the canonical public CLI help surface.- The primary parser/runner exports now have semantic names (
parseRuntimeArgs,runRuntimeCli); product-named TypeScript export aliases are removed from internal code. - CLI worker/runtime helper import paths no longer use
kapi-*filenames for generic runtime observation, worker event formatting, or GitHub issue context probing. - Application service implementation import paths no longer use
kapi-*filenames for the generic workflow service and local service factory. - The local service factory export uses the semantic
createLocalWorkflowServicename instead ofcreateLocalKapiService. - Presentation helper exports use semantic workflow/tool names for generic helpers (
WorkflowToolDefinition,shouldBlockWorkflowToolCall,formatWorkflowError). - PR review state helpers use generic pull-request / agent-review names (
PullRequestReviewState,PullRequestReviewView,latestAgentReview,reviewCheckConclusion). - Registry entry types now use the semantic
WorkflowRegistryEntryname across the domain, adapter, CLI, presentation, and tests. - Store abstractions now use semantic
WorkflowStore/FileWorkflowStorenames across application ports, adapters, and runtime probe scripts; compatibility imports have been migrated and the temporary store alias has been removed. - Service source surfaces now use semantic
WorkflowServicein the implementation, local factory, presentation layer, runtime probe scripts, and active tests; the temporaryKapiServiceexport has been removed after migrating the large remaining test clusters. - Presentation registration/UI action helpers now use semantic workflow names (
registerWorkflowExtension,registerWorkflowCommandsAndTools,registerWorkflowTools,WorkflowUiActionContext,installWorkflowAutocomplete,toggleWorkflowWidgetExpanded) while leaving publickapi_*tool names and/kapi-*contracts intact. - Adapter/domain private helper names now use semantic state/workflow naming for symlink guards, managed autoresearch symlinks, worker branch validation, and prompt rule rendering while preserving user-facing Kapi contract text.
- Review-gate package/source ownership moved out of Ilchul to the github-bot
kapi-agentadapter. Ilchul keeps only the branch-protection and revision-comment documentation for the external review integration. - Runtime package metadata now exposes only the
ilchulruntime bin;kapi,kapi-review, andilchul-revieware absent frompackage.json/package-lock.json,bin/kapi.mjsis removed, andtest/cli-bin.test.tsasserts package-local and isolated-prefix installs do not expose retired runtime/review commands.
git ls-files 'src/*kapi*' 'src/**/*kapi*' | sort
# no tracked filename hits
node -e 'const p=require("./package.json"); console.log(JSON.stringify(p.bin,null,2))'
{
"ilchul": "./bin/runctl.mjs"
}
rg -n '"kapi"\\s*:|"kapi-review"|"ilchul-review"|bin/kapi|bin/ilchul-review|npm exec -- kapi|kapi compatibility alias|kapi --help' package.json package-lock.json README.md docs test bin src scripts
# hits are limited to negative assertions in test/cli-bin.test.ts plus documentation of retired command names
Tracked src/ filename scans no longer include kapi filenames from the review-gate compatibility shim. Runtime package metadata exposes only the ilchul bin: kapi, kapi-review, and ilchul-review are not package bins, and the old direct bin/kapi.mjs shim is removed. Review-gate automation now belongs to the github-bot kapi-agent adapter. Local ignored/generated fixture state under src/.kapi may exist in developer worktrees, but it is not part of the committed source tree scan.
The final issue #209 residual scans were run against the committed runtime-alias-retirement tree. Active src/ content counts exclude only ignored/generated fixture state so the evidence is reproducible from a clean checkout:
rg -n -i 'kapi' src --glob '!src/.kapi/**' --glob '!src/.git/**'
# 497 matching lines / 586 matches across 36 active src files
rg -n 'Kapi[A-Z]|\bkapi[A-Z_-]|kapi-' src test docs package.json package-lock.json
# 1292 matching lines / 1476 matches across source, tests, docs, and package metadata
rg -n '\b(class|interface|type|function|const|let|var|enum)\s+[A-Za-z0-9_]*Kapi[A-Za-z0-9_]*|\b(class|interface|type|function|const|let|var|enum)\s+kapi[A-Za-z0-9_]*' src
# no internal reusable declaration-name hits
Active src/ residual category counts:
| Category | Lines | Matches | Files | Why retained |
|---|---|---|---|---|
| User-facing compatibility text | 228 | 240 | 25 | Status/help/diagnostic wording still describes the existing Kapi workflow contract exposed to users. |
| Serialized workflow/event contracts | 124 | 147 | 20 | Workflow IDs, event kinds, run-contract source kinds, and persisted state keys remain compatibility contracts. |
| Slash commands / public tool contracts | 99 | 126 | 12 | /kapi-*, kapi_*, and @kapi: surfaces are public contract names pending a separate migration plan. |
| External review integration | 20 | 44 | 6 | kapi-agent, kapi-agent/review, PR review-state helpers, and GitHub review-check literals are external integration boundaries; package review CLI exposure moved to github-bot. |
| Environment/runtime compatibility | 10 | 11 | 7 | KAPI_* environment variables remain compatibility inputs for runtime dispatch and tests. |
| Other compatibility literals | 16 | 18 | 10 | Shell labels, fixture command strings, and small compatibility literals that are not reusable implementation identifiers. |
| Acceptance criterion | Status | Evidence |
|---|---|---|
src/ contains no kapi in filenames except explicitly justified boundary exceptions. |
Met | Tracked filename scan has no src/*kapi* hits; ignored/generated local src/.kapi fixture state is not part of the committed source tree. |
Internal reusable exports/types/functions/classes no longer use Kapi* / kapi* naming. |
Met | Declaration-name scan returns no active src hits. Remaining exported literals are serialized contracts, event names, or external integration strings. |
Remaining kapi hits in src/ are limited to documented compatibility contracts, serialized workflow IDs, slash-command literals, or intentionally named external integrations. |
Met | Category table above classifies all 497 active src matching lines / 586 matches. |
Public runtime command examples remain ilchul; internal implementation names remain generic. |
Met | Package bins expose only ilchul; runtime internals use runctl / runtime / workflow / worker names where reusable. |
Tests prove package/runtime CLI does not expose a kapi runtime alias. |
Met | test/cli-bin.test.ts covers package-local npm exec -- kapi --help failure and isolated-prefix absence of a kapi shim. |
| Final scan report includes remaining exception categories and counts. | Met | This section records filename, content, semantic scan, declaration scan, and residual category counts. |
- External review integration:
kapi-agent,kapi-agent/review, and historical docs that explain retired review CLI names. - Persisted contracts:
/kapi-*slash commands,kapi-*workflow IDs,kapi.worker.*/kapi.pr.*event names,kapi-workflowrun-contract source kind, and existing serialized state expectations. - Public tool / command contracts:
kapi_*tool names and@kapi:UI completion syntax. - User-facing compatibility text: status, help, validation, and diagnostic strings that describe the still-public Kapi workflow contract.
- Storage/config namespace:
.ilchul,~/.ilchul,ILCHUL_*, legacy.kapireferences, and compatibilityKAPI_*environment inputs. - Documentation/history: prose explaining migration context or historical behavior.
- No destructive storage migration.
- No broad
kapi -> ilchulreplacement. - Public runtime CLI compatibility commands are intentionally removed; serialized workflow IDs remain unchanged.