ilchul-naming-policy.md

Ilchul naming and compatibility policy

This policy defines how the project moves from the historical Kapi name toward the Ilchul product name without causing accidental code, API, command, or storage churn.

Policy summary

• Ilchul is the product, documentation, and brand name. Ilchul is product/docs/brand vocabulary, not a reusable core identifier prefix.
• Ilchul is the public runtime CLI command. Kapi remains only where it is a persisted workflow identifier, slash-command family, GitHub integration name, or historical reference until a scoped migration issue changes those surfaces. Internal runtime implementation names should prefer semantic runctl / runtime naming.
• Reusable core code should prefer semantic vocabulary such as run, contract, preset, harness, evidence, score, steer, worker, runtime, registry, and workflow instead of introducing broad ilchul prefixes.
• Do not perform broad kapi -> ilchul replacements. Any rename must identify the public surface, compatibility expectation, migration path, and rollback risk.
• Active workflow/storage routing now uses .ilchul / ~/.ilchul. Legacy .kapi folders may remain on disk as historical local state, but runtime code must not use .kapi as a fallback storage root or delete it implicitly.

Where Ilchul should appear

Use Ilchul for:

• repository/product-level documentation;
• roadmap and issue titles that describe the product direction;
• user-facing prose that explains the harness as a product;
• review guidance for this repository's own review harness;
• future docs for explicitly approved .ilchul storage behavior.

Examples:

• "Ilchul is a Pi-native workflow harness."
• "Ilchul review harness contract"
• "Ilchul naming and compatibility policy"

Where kapi stays stable

Keep kapi when changing it would break an existing integration or stored contract without an approved migration:

• Slash commands and persisted workflow surfaces retained for compatibility such as /kapi-ralph, /kapi-status, and /kapi-clear;
• GitHub workflow/check names such as kapi-agent/review; the former kapi-review and proposed ilchul-review local package bins are not exposed by Ilchul because deterministic review automation now belongs to the github-bot adapter;
• existing workflow IDs and serialized identifiers such as kapi-ralph and kapi-autoresearch;
• existing local workspace state under .kapi/ and historical docs that describe current behavior;
• compatibility docs for existing installations or migration windows.

A future migration may rename one of these surfaces, but it must be scoped, tested, and documented. The default is compatibility preservation.

Reusable core vocabulary

Reusable code, serialized model fields, and APIs should name the concept they own rather than the product brand. Prefer:

Concept	Preferred terms
run state	run, workflow, state, lifecycle
contracts	contract, preset, criteria, expectation
verification	evidence, completion, gate, review
evaluation	score, quality, dimension, hint
steering	steer, recommendation, nextAction
execution	worker, runtime, session, registry
adapters	github, cli, presentation, review

Use Ilchul in code only when the identifier truly names a product-branded adapter, document, or user-facing artifact. Avoid names such as IlchulPolicyModule, IlchulContract, or IlchulScore for reusable core abstractions when PolicyModule, ContractPreset, or ScoringHint is the actual concept.

Storage direction and .kapi retirement

.ilchul is the canonical active workspace/storage root. New workflow artifacts, active pointers, registry records, runtime prompts, and default worker worktrees route to .ilchul / ~/.ilchul directly.

Storage rules:

1. New local worktree/storage operations target ~/.ilchul.
2. Active workflow state uses .ilchul/workflows, .ilchul/active.json, .ilchul/registry, and .ilchul/runtime-prompts.
3. .kapi is legacy local state only. Runtime code must not read it as a fallback root, prefer it by precedence, or create dual-root discovery behavior.
4. Existing .kapi folders must not be silently, eagerly, or destructively deleted. Any cleanup must be explicit, reviewed, reversible where practical, and authorized for the specific cleanup slice.
5. If old .kapi and new .ilchul roots both exist, normal start/status/report paths use .ilchul; .kapi remains historical evidence until separately handled.

This means .ilchul is the active behavior, while .kapi is neither a compatibility routing root nor a cleanup target for normal workflow commands.

Compatibility matrix

Workspace condition	Active behavior	User-facing message
No existing storage root	Create and use .ilchul / ~/.ilchul for new local workflow and worker state.	"Ilchul stores new workflow state under .ilchul."
Existing .kapi only	Ignore .kapi for active routing and create/use .ilchul; do not delete .kapi.	"Legacy .kapi state may exist locally, but active Ilchul state is under .ilchul."
Existing .ilchul only	Treat .ilchul as the canonical storage root.	"Using canonical .ilchul storage."
Both .kapi and .ilchul present	Use .ilchul; preserve .kapi as legacy evidence until explicit cleanup is authorized.	"Using .ilchul; legacy .kapi was not modified."

Safe implementation follow-ups

Remaining storage cleanup work, if needed, should be explicit and non-ambient:

1. Add diagnostics that report legacy .kapi presence without changing routing.
2. Add recovery docs for users who want to inspect or manually archive old .kapi state.
3. Add explicit cleanup only after Kade authorizes the destructive scope for that slice.

No slice should hide deletion behind normal workflow start, status, report, or verification commands.

Deprecated or retained names

• Retained until scoped migration: kapi, /kapi-*, kapi-agent, kapi-agent/review, kapi-ralph, and kapi-autoresearch.
• Canonical public CLI command: ilchul for the runtime; there is no kapi, kapi-review, or ilchul-review CLI compatibility alias in the Ilchul package. Internal runtime modules use runctl / runtime naming. Review automation remains an external kapi-agent / github-bot responsibility, not a public package bin or reusable implementation module.
• Active storage behavior: .ilchul / ~/.ilchul; .kapi is legacy local state only and is not an active fallback root.
• Preferred for new product prose: Ilchul.
• Preferred for new reusable core identifiers: semantic terms from the vocabulary table.
• Deprecated pattern: mechanical brand-prefixing or broad string replacement across source/docs/tests.

Review checklist for naming changes

Before approving a naming or storage change, verify:

• The change identifies the exact public or persisted surface being renamed.
• The PR does not contain broad mechanical kapi -> ilchul replacement.
• Reusable core code uses semantic identifiers unless the product brand is the precise concept.
• Existing .kapi state is preserved unless the issue explicitly authorizes migration/removal, and any .kapi retirement path names its cleanup authorization boundary.
• Docs distinguish current behavior from forward direction.
• Tests cover any compatibility or migration behavior changed by the PR.

Relationship to the roadmap

Issue #114 may link here as the policy source for Track B naming and compatibility decisions. Issues that implement .ilchul storage, command renames, or compatibility retirement should reference this policy and state which rule they intentionally change or instantiate.