refactor: unify RunContract prompt rendering across service and CLI runtime

[devkade]

Summary

Unify RunContract prompt rendering across the Pi service path and the CLI runtime path so both surfaces are driven by the same semantic contract renderer.

Parent roadmap: #114
Track: A — RunContract Harness core
Tier: 1 — actionable now

Problem

RunContract is becoming the shared harness surface, but prompt composition is still split between KapiService.buildWorkflowPrompt and the CLI runtime buildRuntimePrompt path. That creates drift between interactive Pi workflow guidance and Kapi CLI worker/runtime prompts.

Proposal

Add a shared renderer module for contract/workflow prompts and route both service and CLI prompt composition through it while preserving current public behavior.

Scope

• Introduce a shared semantic renderer for workflow/RunContract prompt content.
• Keep KapiService.buildWorkflowPrompt as a compatibility wrapper if useful.
• Move CLI runtime prompt construction onto the same renderer path.
• Preserve current prompt intent, skill hints, evidence expectations, and mode-specific guidance.
• Add regression tests for both service and CLI prompt output.

Non-goals

• No rename of WorkflowState, WorkflowDefinition, or existing workflow APIs.
• No durable RunContract schema or storage migration.
• No GitHub/PR/kapi-agent/Ragna semantics in core rendering.
• No broad Kapi→Ilchul identifier rename.

Acceptance criteria

• Service workflow prompts and CLI runtime prompts share a common renderer path.
• Existing public command/API behavior remains backward-compatible.
• RunContract/core renderer code stays free of GitHub/PR/kapi-agent/Ragna/Discord-specific semantics.
• Tests cover both service prompt rendering and CLI runtime prompt rendering.
• npm run verify passes.

Verification

• Run targeted prompt/CLI tests.
• Run npm run verify.
• Search new core renderer code for adapter-specific terms such as GitHub, pullRequest, kapiAgent, Ragna, and Discord.

References

• Kapi → Ilchul RunContract Harness roadmap #114
• docs: define RunContract harness core-adapter boundary #97–feat: map RunContract status into Hermes/Ragna GitHub workflow adapters #102 completed RunContract foundation

[devkade]

Track A execution sequencing / refactor boundary

Decision from review of the current Ilchul codebase: proceed with Track A first, but make the first Track A slice a narrow functional refactor rather than a separate cleanup pass.

Recommended order

1. refactor: unify RunContract prompt rendering across service and CLI runtime #115 first — shared RunContract prompt renderer

   • Treat this as Track A implementation work, not generic cleanup.
   • Unify the duplicated prompt composition paths:
     • KapiService.buildWorkflowPrompt
     • CLI runtime buildRuntimePrompt
   • Preferred shape: a shared semantic renderer with adapter/runtime appendices injected at the edge.
   • Keep GitHub/PR/kapi-agent/Ragna/Discord semantics out of the core renderer.

2. feat: map RunContract quality hints to five advisory dimensions #116 next — five advisory dimensions, additive only

   • Add Alignment, Evidence, Completeness, Simplicity, and Risk as advisory dimensions.
   • Preserve existing quality.status and quality.hints compatibility while dimensions stabilize.
   • Do not turn dimensions into completion authority or tool-call gates.

3. docs: define Kapi harness evaluator and anti-Goodhart checklist #117 next — evaluator / anti-Goodhart boundary

   • Document that RunContract quality is advisory.
   • Keep workflow-validation as authority and runtime readiness probe as runtime health.

4. Cleanup only after the above is grounded

   • Consolidate RunContract compact/detail formatters.
   • Split prompt/report helpers out of src/cli/kapi-cli.ts only where directly justified by refactor: unify RunContract prompt rendering across service and CLI runtime #115/feat: map RunContract quality hints to five advisory dimensions #116.
   • Split src/domain/run-contract.ts only if dimensions/steering logic push it past a maintainability threshold.

Refactor boundaries

Merge / shrink:

• duplicate prompt string assembly;
• duplicate RunContract summary formatting;
• scattered quality wording;
• contract interpretation embedded in service/CLI surfaces.

Do not merge:

• RunContract core with GitHub workflow adapter;
• RunContract completion projection with workflow-validation authority;
• RunContract advisory quality with runtime readiness probe;
• WorkflowState source of truth with a durable contract.json.

Execution rule

Avoid both extremes:

• no large cleanup-before-feature refactor;
• no Track A feature pile-up followed by a risky cleanup sweep.

Instead: #115 should be the first, bounded refactor slice that makes the rest of Track A cheaper and less drift-prone.

[devkade]

Follow-up cleanup checkpoint created as #128. Do not expand #115 into broad cleanup; finish the shared prompt renderer first, then use #128 to consolidate remaining formatter/report/helper duplication based on the final #115 diff.