docs: establish Ilchul naming and compatibility policy

[devkade]

Summary

Establish the Ilchul naming and compatibility policy so product branding can move forward without unsafe code/API/storage churn.

Parent roadmap: #114
Track: B — Ilchul product/brand migration
Tier: 2 — design-sensitive next

Problem

Ilchul is the intended product/documentation brand, but reusable code/API/tool identifiers should stay semantic. Without an explicit policy, future changes may accidentally perform broad kapi -> ilchul replacements or conflate brand naming with compatibility-breaking API/storage changes.

Scope

Document:

• where Ilchul appears as product/docs/brand vocabulary;
• where kapi remains stable for compatibility;
• preferred reusable core vocabulary: run, contract, preset, harness, evidence, score, steer, worker, runtime;
• deprecated/retained names and public compatibility expectations;
• relationship between .kapi existing local folders and forward .ilchul direction.

Non-goals

• No code rename.
• No storage migration implementation.
• No CLI command rename.
• No broad string replacement.

Acceptance criteria

• Naming policy is documented in the repo.
• Policy explicitly says Ilchul is product/docs/brand vocabulary, not a reusable core identifier prefix.
• Policy explicitly forbids broad kapi -> ilchul replacement.
• Policy records that existing local .kapi folders must remain compatible and must not be destructively/eagerly renamed.
• Kapi → Ilchul RunContract Harness roadmap #114 can link to this policy for future sub-issue decisions.

Verification

• Documentation review against Kapi → Ilchul RunContract Harness roadmap #114.
• Search the docs change for ambiguous migration wording.

References

• Kapi → Ilchul RunContract Harness roadmap #114
• Obsidian design note: kapi-run-contract-refactor-loop-and-ragna-review.md

Decision update — 2026-05-15

Kade updated the naming/storage direction:

• .kapi is to be replaced by .ilchul as the local workspace/storage root.
• New worktree/workspace activity should use .ilchul going forward, including ~/.ilchul for local worktree operations.
• .kapi and .ilchul are not intended to coexist as dual canonical roots.
• Existing .kapi folders are not preserved as a long-term compatibility target; cleanup/migration must be explicit and reviewed rather than silent or accidental.
• The naming policy still forbids broad identifier churn: do not blindly rename reusable code/API identifiers from kapi to ilchul; use semantic identifiers unless a public compatibility decision explicitly authorizes a rename.