refactor: rename worker runtime helpers

[devkade]

Summary

• Renames the generic CLI worker/runtime helper modules from kapi-* filenames to semantic runtime names.
• Updates runtime CLI imports and direct helper tests to use github-issue-context, worker-events, and worker-runtime module paths.
• Adds an architecture guard and refreshes the product-name audit with a residual filename scan.

Linked issue

Refs #209

Problem

Issue #209 tracks broad removal of historical kapi product-name leakage from internal code identifiers, filenames, exports, helper names, and reusable implementation strings.

This slice addresses a bounded filename/import subset: three generic CLI helper modules still used kapi-* filenames even though they are runtime/worker implementation helpers rather than retained public product surfaces.

src/cli/kapi-github-issue-context.ts
src/cli/kapi-worker-events.ts
src/cli/kapi-worker-runtime.ts

These names made the generic runtime event and GitHub issue probing helpers look like product-branded compatibility surfaces.

Options considered

1. Rename all remaining src/ kapi filenames in one PR — rename service/factory/review/helper filenames together.
   • Pros: faster progress toward the issue's filename acceptance criterion.
   • Cons: likely larger than the review budget because KapiService, KapiStore, and many tests/imports need a semantic service-boundary rename.
2. Rename only the generic CLI worker/runtime helpers — keep external-contract and larger service-boundary names for follow-up.
   • Pros: small, reviewable, low-risk; removes clearly internal helper filename leakage without touching serialized event or service contracts.
   • Cons: does not complete the umbrella issue; leaves service/factory names for a later slice.
3. Documentation-only classification — update the audit but leave filenames unchanged.
   • Pros: no runtime risk.
   • Cons: does not reduce implementation leakage or enforce the new helper paths.

Selected approach

Selected option 2.

This PR keeps the slice reviewable and avoids broad mechanical replacement. It renames only helper filenames whose boundary is already semantic (worker, runtime, GitHub issue context), while preserving intentionally literal external contracts such as kapi.worker.*, kapi.pr.*, kapi-agent, and kapi-review.

Implementation

• src/cli/kapi-github-issue-context.ts → src/cli/github-issue-context.ts
  • Renamed the generic GitHub issue context helper module.
  • Updated runctl-cli.ts and direct tests to import the semantic path.
• src/cli/kapi-worker-events.ts → src/cli/worker-events.ts
  • Renamed the worker event formatting/building helper module.
  • Updated the internal runtime import to ./worker-runtime.js.
• src/cli/kapi-worker-runtime.ts → src/cli/worker-runtime.ts
  • Renamed the runtime observation helper module.
  • Updated direct tests to import the semantic path.
• test/architecture.test.ts
  • Added a guard that fails if the old src/cli/kapi-worker-* or src/cli/kapi-github-issue-context.ts filenames reappear.
  • Confirms the new semantic helper filenames exist.
• docs/product-name-audit.md
  • Records the CLI helper rename slice.
  • Adds the residual filename scan and classifies remaining exceptions/follow-ups.

Why this fixes it

The old helper module paths can no longer be imported or reintroduced silently:

• runtime code now imports the semantic module paths;
• direct helper tests now target the semantic paths;
• the architecture test checks the old filenames stay absent;
• the audit document records the remaining filename exceptions and next boundary (KapiService / factory) instead of hiding them.

This is a partial #209 slice, so the PR uses Refs #209 rather than Closes #209.

QA / Verification

• npm test -- test/cli-worker-events.test.ts test/cli-worker-runtime.test.ts test/cli-github-issue-context.test.ts — pass; package script ran the full test/*.test.ts suite plus explicit files, 518 tests, 507 pass, 11 skipped.
• npm test -- test/architecture.test.ts — pass; package script ran the full test/*.test.ts suite plus explicit file, 519 tests, 508 pass, 11 skipped.
• npm run check — pass.
• npm run check:unused — pass.
• npm run quality:budgets — pass with existing non-failing code_smells=52 warning.
• git diff --check — pass.

Residual scans:

find src -iname '*kapi*' -print
src/.kapi
src/.kapi/lanes/kapi-autoresearch
src/.kapi/lanes/kapi-autoresearch/kapi-ux-개선-계획
src/adapters/kapi-service-factory.ts
src/application/kapi-service.ts
src/cli/kapi-review-cli.ts

rg -n -i 'kapi' src | wc -l
686

Changed-line count:

git diff --shortstat origin/dev...HEAD
9 files changed, 49 insertions(+), 6 deletions(-)

Independent review:

• Hermes requesting-code-review static scan — no findings.
• Independent reviewer subagent — pass; no security concerns or logic errors.

Anomalies observed

Symptom	Evidence	Impact	Action
Targeted-looking npm test -- <files> runs the full suite because the package script is tsx --test test/*.test.ts.	Test output showed 518/519 tests rather than only the named files.	QA is broader than the command name suggests; runtime cost only.	Reported exact scope above.
src/cli/kapi-review-cli.ts mode changed to executable during verification.	git diff --summary showed mode change 100644 => 100755.	Unrelated mode-only churn could leak into the PR.	Reset file mode before staging/commit; final diff has no mode-only churn.
Residual kapi source hits remain.	`rg -n -i 'kapi' src	wc -l=686`.	This PR is not the final #209 cleanup.

Risks / Follow-up

• Remaining src/application/kapi-service.ts, src/adapters/kapi-service-factory.ts, and related KapiService / KapiStore exports still need a later semantic service-boundary slice.
• src/cli/kapi-review-cli.ts remains intentional for the literal external kapi-review / kapi-agent integration.
• Serialized event names and workflow IDs such as kapi.worker.*, kapi.pr.*, and kapi-autoresearch remain compatibility contracts.

kapi-agent review

• Expected reviewer-only bot behavior: automatic formal review after PR open; if absent after a short wait, request with @kapi-agent review.
• Merge gate: latest kapi-agent approval/check must apply to the current head before merge.
• Re-review rule: after stale approval, REQUEST_CHANGES, or COMMENT, request re-review with a same-comment current-head revision explanation:
  • @kapi-agent review
  • Revision explanation for current head <HEAD_SHA>
  • What changed
  • Why this closes the prior feedback
  • Verification

[devkade]

@kapi-agent review

Revision explanation for current head af9d413ef5800ed6b91bd52b52137ddd3402cbd4:

What changed:

• Renamed generic CLI helper filenames from kapi-github-issue-context.ts, kapi-worker-events.ts, and kapi-worker-runtime.ts to semantic github-issue-context.ts, worker-events.ts, and worker-runtime.ts.
• Updated runtime CLI imports and direct tests to use the new semantic module paths.
• Added an architecture guard so the old internal helper filenames do not reappear.
• Updated the product-name audit with a residual filename scan and remaining exception classification.

Why this closes the prior feedback:

• This is a bounded partial Remove remaining kapi identifiers from internal codebase #209 slice: it removes internal filename leakage for the worker/runtime helper boundary while preserving literal external contracts (kapi.worker.*, kapi-agent, kapi-review) and leaving KapiService/factory cleanup for follow-up.
• The PR stays under the review-size gate at 49 insertions / 6 deletions plus three renames.

Verification:

• npm test -- test/cli-worker-events.test.ts test/cli-worker-runtime.test.ts test/cli-github-issue-context.test.ts — pass; package script ran the full suite, 518 tests, 507 pass, 11 skipped.
• npm test -- test/architecture.test.ts — pass; package script ran the full suite, 519 tests, 508 pass, 11 skipped.
• npm run check — pass.
• npm run check:unused — pass.
• npm run quality:budgets — pass with existing non-failing code_smells=52 warning.
• git diff --check — pass.
• Independent reviewer subagent — pass; no security concerns or logic errors.

[kapi-agent]

kapi-agent review

Verdict: APPROVE

Final approval summary

Review journey

This PR addresses a bounded slice of issue #209 by renaming internal CLI worker/runtime helper filenames away from historical kapi-* names. The semantic scope is narrow: three internal helper module paths, their imports/tests, an architecture guard, and the product-name audit documentation. There is no prior kapi-agent review on this head, so no unresolved ping-pong feedback remains.

What changed

• Renamed:
  • src/cli/kapi-github-issue-context.ts → src/cli/github-issue-context.ts
  • src/cli/kapi-worker-events.ts → src/cli/worker-events.ts
  • src/cli/kapi-worker-runtime.ts → src/cli/worker-runtime.ts
• Updated src/cli/runctl-cli.ts and direct tests to import the new semantic paths.
• Added test/architecture.test.ts coverage to prevent the old helper filenames from reappearing.
• Updated docs/product-name-audit.md with the rename slice and remaining filename exceptions.

Why this is correct

The implementation is primarily a rename/import refactor. The only source-code behavior change is the import path from worker-events.ts to worker-runtime.ts; the helper contents are otherwise preserved. The new architecture guard directly protects the intended workflow contract by checking both absence of the old filenames and presence of the new semantic filenames.

Evidence

• Verifier gate: PASS — npm ci && npm run verify exited 0.
• Size gate: PASS — 55 changed lines, under the 200-line semantic review threshold.
• Revision-explanation status: not required; found.
• Ilchul review harness gate: PASS — neutral/comment result with 0 blocking findings.
• Inspected diff/files: renamed CLI helper modules, src/cli/runctl-cli.ts, direct helper tests, test/architecture.test.ts, and docs/product-name-audit.md.

Remaining risks and approval rationale

Remaining risk is low and limited to import-path churn. The PR intentionally does not complete the broader product-name cleanup, and the residual filenames are documented as follow-up or external-contract exceptions. Approval is justified because the scope is bounded, verification passed, tests cover the intended guard, and no blocking correctness, security, or workflow-contract issue was found.

Blocking issues

None.

Warnings / risks

• docs/product-name-audit.md still lists broader residual kapi surfaces, including service/factory names and external integration names. This is acceptable for this slice but remains follow-up work.
• The architecture guard is filename-specific, not a general product-name detector. That matches the PR’s bounded intent.

Suggestions

• In a future service/factory rename slice, consider adding a similarly targeted architecture guard for the next boundary to avoid accidental reintroduction.

Looks good

• The rename is mechanically narrow and avoids touching serialized event names such as kapi.worker.*, preserving compatibility contracts.
• Tests were updated to import the semantic helper paths.
• The product-name audit clearly documents what was changed and what remains intentionally unchanged.

Verification notes

Verifier gate: PASS — npm ci && npm run verify exited 0.
Size gate: PASS — 55 changed lines, below threshold.
Revision-explanation status: not required; found.
Ilchul review harness: PASS — no blocking findings.

---

Engine: pi