feat(cli): add generic runtime command alias

[devkade]

Summary

• Adds runctl as the canonical generic CLI runtime command while preserving kapi as a compatibility alias.
• Renames the primary parser/runner exports to semantic runtime names with legacy parseKapiArgs / runKapiCli aliases retained.
• Documents the product-name surface audit and updates README/naming policy guidance for future slices.

Linked issue

Refs #205

Problem

Issue #205 asks us to normalize reusable identifiers away from product names without breaking existing public contracts. The current CLI runtime surface was still anchored on kapi in help text, parser/runner export names, package bins, and README examples. A broad replacement would be unsafe because kapi, /kapi-*, kapi-agent/review, workflow IDs, and persisted state names are compatibility or external-integration contracts.

Options considered

1. Broad kapi → ilchul rename
   • Pros: fast mechanical reduction of one product name.
   • Cons: violates the naming policy, risks breaking public commands, serialized identifiers, GitHub integration names, and compatibility expectations.
2. Add a new generic CLI surface with compatibility aliases
   • Pros: creates a canonical reusable command for new docs and tests while preserving existing users and integrations.
   • Cons: leaves some historical names in place until scoped follow-up migrations.
3. Documentation-only audit
   • Pros: zero runtime risk.
   • Cons: does not create an enforced generic CLI surface or regression guard.

Selected approach

• Selected option: option 2, plus an explicit audit document.
• Why this one: it moves a real public/runtime surface toward semantic naming while keeping compatibility contracts stable.
• Risks/trade-offs: this intentionally does not rename all existing Kapi* internal classes or persisted identifiers; those are recorded for follow-up slices rather than hidden in a broad PR.

Implementation by file/surface

• package.json, package-lock.json: add runctl package bin while retaining kapi and kapi-review.
• bin/runctl.mjs: add executable JS wrapper that sets ILCHUL_RUNTIME_CLI_NAME=runctl before loading the existing TypeScript CLI implementation.
• src/cli/kapi-cli.ts: introduce parseRuntimeArgs and runRuntimeCli, preserve parseKapiArgs and runKapiCli compatibility exports, and parameterize help/usage text by command name.
• test/cli-args.test.ts, test/cli-bin.test.ts: add regression coverage for runctl --help, legacy kapi --help, and package-local npm exec -- runctl --help.
• README.md: prefer runctl for new generic runtime examples while documenting kapi compatibility.
• docs/ilchul-naming-policy.md: clarify the runctl canonical generic CLI surface.
• docs/product-name-audit.md: records current product-name surfaces, which ones are compatibility contracts, and what remains for follow-up.

Why this fixes it

The first normalized slice now has a concrete generic runtime command (runctl) and semantic parser/runner API (parseRuntimeArgs, runRuntimeCli) backed by tests. Existing users and integrations can keep using kapi, while new reusable examples no longer need to introduce product-name leakage.

QA / Verification

• npm test -- test/cli-args.test.ts test/cli-bin.test.ts — pass; package script runs the full test suite plus explicit files (517 tests, 506 pass, 11 skipped).
• npm run verify — pass (npm test, npm run check, npm run check:unused, npm run quality:budgets). Quality budgets report one existing warning: code_smells value=50 target="<=20" status=warn.
• git diff --check — pass.
• Changed-line preflight against origin/dev: 9 files changed, 131 insertions(+), 41 deletions(-) / 172 changed lines.

Anomalies observed

• npm run verify repeatedly toggled src/cli/kapi-review-cli.ts executable bit locally; the mode-only churn was reset before staging and is not included in the commit.
• Node emits [DEP0205] module.register() is deprecated warnings during tests; this is pre-existing test/runtime noise and not introduced by this slice.

Risks / Follow-up

• Remaining product-prefixed internal identifiers such as KapiRegistryEntry, KapiService, and KapiStore are explicitly documented as follow-up work.
• Persisted/public names (/kapi-*, kapi-agent/review, kapi-ralph, .ilchul, legacy .kapi evidence) are intentionally retained until separate compatibility migrations exist.

kapi-agent review expectations and current-head merge gate

• This PR is under the review-size target (172 changed lines against origin/dev).
• kapi-agent should verify that runctl is additive, kapi compatibility remains tested, and the audit does not overclaim full issue completion.
• Merge readiness still requires current-head kapi-agent approval/check success after PR creation.

[devkade]

@kapi-agent review

Revision explanation for current head 347183dae87444e3c9624bb0bebc3ae034ca01f6:

What changed:

• Added runctl as a generic CLI runtime command while keeping kapi as a compatibility alias.
• Introduced semantic parseRuntimeArgs / runRuntimeCli exports with legacy aliases preserved.
• Added audit/policy docs and regression coverage for both generic and compatibility CLI help surfaces.

Why this closes the prior feedback:

• Prior blocking issue: Normalize reusable identifiers away from product names #205 identified reusable product-name leakage risk and required scoped normalization instead of broad product-name replacement.
• Resolution: this head moves the first public runtime surface to a generic command/API, records remaining product-name surfaces by compatibility class, and avoids unsafe persisted/public identifier migration.

Verification:

• npm test -- test/cli-args.test.ts test/cli-bin.test.ts passed; package script executed the full test suite (517 tests, 506 pass, 11 skipped).
• npm run verify passed (npm test, npm run check, npm run check:unused, npm run quality:budgets).
• git diff --check passed.

[kapi-agent]

kapi-agent review

Verdict: APPROVE

Final approval summary

Review journey

The original goal was to add a generic runtime CLI command while preserving Kapi compatibility contracts. The semantic scope is bounded: one additive bin alias, semantic parser/runner export aliases, targeted help text parameterization, tests, and naming/audit docs. There was no prior kapi-agent blocking feedback on this PR, so no review/fix ping-pong was required.

What changed

• Added runctl in package.json and bin/runctl.mjs.
• Updated src/cli/kapi-cli.ts to expose parseRuntimeArgs / runRuntimeCli while retaining parseKapiArgs / runKapiCli.
• Parameterized CLI help/usage strings by runtime command name.
• Added regression coverage in test/cli-args.test.ts and test/cli-bin.test.ts.
• Updated README.md, docs/ilchul-naming-policy.md, and added docs/product-name-audit.md.

Why this is correct

The change is additive for users: kapi remains present and tested, while runctl gets its own wrapper that sets ILCHUL_RUNTIME_CLI_NAME=runctl before invoking the same runtime implementation. Persisted workflow IDs, slash commands, storage names, and GitHub integration names are intentionally not renamed, matching the compatibility policy and reducing migration risk.

Evidence

Verifier gate: PASS. Size gate: PASS at 172 changed lines, with semantic source/test/doc scope below the review threshold. Revision-explanation status: not required, found. Ilchul harness gate: PASS with neutral/comment result and no blocking findings. Reported verification includes npm ci && npm run verify passing. I also inspected the changed implementation paths locally, including package.json, bin/runctl.mjs, bin/kapi.mjs, src/cli/kapi-cli.ts, and CLI tests.

Remaining risks and approval rationale

Remaining risk is limited to discoverability/setup messaging: the setup helper still has Kapi-oriented naming/output, but package bin installation should expose all configured bins and this is not a correctness blocker for the additive alias. Approval is justified because compatibility is preserved, tests cover both aliases, docs accurately frame the migration as a slice, and all gates pass.

Blocking issues

None.

Warnings / risks

• scripts/setup-kapi-cli.mjs remains Kapi-named and prints Kapi-oriented setup output. This is acceptable for compatibility, but future migration slices may want to make the setup messaging mention runctl.

Suggestions

• Consider adding a small setup-helper assertion for installed runctl in test/cli-bin.test.ts in a follow-up, since README now shows npm run setup:cli followed by runctl --help.

Looks good

• runctl is implemented as an additive wrapper and does not remove or weaken the existing kapi bin.
• The runtime command name is constrained by a simple allowlist regex before being used in help/usage output.
• Legacy exported names are preserved as aliases, reducing API churn.
• The audit document correctly avoids overclaiming a full product-name migration.

Verification notes

Verifier gate status: PASS (npm ci && npm run verify exited 0). Size gate status: PASS (172 changed lines under threshold). Revision-explanation status: not required, found. Ilchul harness gate: PASS with no blocking findings. Local review inspected the relevant CLI wrapper, parser/runner, package bin, tests, and docs.

---

Engine: pi