refactor: unify RunContract prompt rendering

[devkade]

Summary

• Added a shared renderRunContractPrompt domain renderer for workflow and runtime prompt layouts.
• Routed KapiService.buildWorkflowPrompt and CLI runtime prompt dispatch through the shared renderer.
• Added regression coverage for service prompt equivalence and runtime prompt rendering without GitHub/Ragna/Discord adapter semantics in the core renderer.

Revision explanation for current head 9f588f6173e8121a30824b8f80160baee61e2124

What changed

• Reduced PR size from 251 changed lines to 159 changed lines, under the 200-line approval gate.
• Kept the shared renderer scope but compacted implementation/tests.
• Preserved prior unknown workflow fallback behavior in CLI runtime prompts.
• Moved CLI renderer import directly to the domain module.

Why this closes the prior feedback

• Prior blocking issue: size gate failed at 251 changed lines.
• Resolution: this head is 159 changed lines, under the 200-line gate.
• Prior warning: unknown workflow handling changed from fallback to throwing.
• Resolution: this head restores fallback prompt rendering for unknown workflow ids.
• Prior blocking issue: revision explanation gate did not find a valid response.
• Resolution: this PR body includes the current-head revision explanation, and a same-comment re-review request is posted below.

Verification

• npm run verify passed.
• npm test -- test/run-contract-prompt-renderer.test.ts && npm run check && npm run check:unused passed.
• git diff --check passed.
• Independent reviewer passed with no security concerns and no logic errors.

Closes #115

[kapi-agent]

kapi-agent review

Verdict: REQUEST_CHANGES

Blocking issues

• Size gate failed: this PR changes 251 lines, which is above the 200-line maximum for kapi-agent approval.
  • Please split this into multiple PRs, each under 200 changed lines and scoped to one semantic unit.
  • A likely split would be:
    1. Add the shared renderRunContractPrompt domain renderer plus focused unit tests.
    2. Route KapiService.buildWorkflowPrompt through the renderer and verify prompt equivalence.
    3. Route CLI runtime prompt rendering through the renderer and verify CLI/runtime behavior.

Because this gate fails, I cannot approve this revision even if the implementation direction looks reasonable.

Warnings / risks

• src/cli/kapi-cli.ts: changing unknown workflow handling from fallback prompt construction to throwing may be correct, but it is a behavior change. The split PR should make this explicit and include coverage if intentional.
• Prompt rendering refactors are regression-prone because small formatting changes can break workflow/artifact contracts or tests that compare exact prompt text. Keep each semantic change isolated with snapshot/equivalence tests.

Suggestions

• In the follow-up PRs, include before/after prompt equivalence tests for both:
  • service workflow prompt rendering
  • runtime CLI prompt rendering
• Consider making renderer layout contracts explicit in tests so workflow-only concerns and runtime-only concerns do not leak across layers.

Looks good

• The direction of extracting prompt rendering into src/domain/run-contract-prompt-renderer.ts is maintainable and should reduce duplicated contract text.
• Routing both service and CLI prompt construction through one renderer is a good way to preserve artifact/workflow contract consistency, provided the split PRs keep exact behavior verified.

Verification notes

• Verification gate status: FAIL — size gate failed because this PR has 251 changed lines, exceeding the 200-line limit.
• Size gate status: FAIL — 251 changed lines >= 200.
• Revision-explanation status: not required for this first kapi-agent review; found status is true.
• Claimed author verification: npm run verify, targeted tests, npm run check, npm run check:unused, and git diff --check, but approval is blocked by the size gate regardless.

---

Engine: pi

[devkade]

@kapi-agent review

Revision explanation for current head d1e115e7adf20539a8d932139cca4a8cf181f85a:

What changed

• Reduced PR size from 251 changed lines to 159 changed lines, under the 200-line approval gate.
• Kept the shared renderRunContractPrompt renderer but compacted implementation/tests without splitting behavior.
• Preserved prior unknown workflow fallback behavior in CLI runtime prompts by allowing renderer fallback text instead of throwing.
• Moved CLI renderer import directly to the domain module to keep adapter/application layering cleaner.

Why this closes the prior feedback

• The blocking kapi-agent finding was the size gate; this revision is now below the gate.
• The warning about unknown workflow handling is addressed by restoring fallback prompt behavior.
• Prompt-equivalence and boundary tests remain in place for service and runtime layouts.

Verification

• npm run verify
• npm test -- test/run-contract-prompt-renderer.test.ts && npm run check && npm run check:unused
• git diff --check
• independent reviewer: PASS, no security concerns, no logic errors

[kapi-agent]

kapi-agent review

Verdict: REQUEST_CHANGES

Blocking issues

• Revision explanation gate failed. This PR was updated after a prior kapi-agent review, but there is no author comment or PR-body update explaining what changed and why.
  • Please add a review response explaining the revision since the prior CHANGES_REQUESTED review, especially how the PR was reduced from 251 changed lines to 159 and what semantic scope remains.
  • After that, request re-review.

Warnings / risks

• None blocking from the inspected code. Prompt rendering changes are inherently regression-prone, but this revision has focused equivalence/runtime coverage.

Suggestions

• Consider documenting in the PR response whether any behavior changed around unknown workflow prompt fallback versus known workflow rendering, since that was called out in the prior review.

Looks good

• src/domain/run-contract-prompt-renderer.ts cleanly centralizes workflow/runtime prompt layout without pulling in adapter-specific GitHub/Ragna/Discord semantics.
• src/application/kapi-service.ts now delegates workflow prompt construction to the shared renderer while preserving Ralph-specific reviewer guidance and resume notes.
• src/cli/kapi-cli.ts routes runtime prompt construction through the same renderer while keeping GitHub issue prompt context appended outside the domain renderer.
• test/run-contract-prompt-renderer.test.ts covers service prompt equivalence and asserts runtime prompts stay free of adapter-specific semantics.

Verification notes

• Verifier gate status: PASS — npm ci && npm run verify exited 0.
• Size gate status: PASS — 159 changed lines, under the 200-line limit.
• Revision-explanation status: FAIL — prior kapi-agent review exists, revision explanation is required, and none was found.
• Local inspection covered:
  • src/domain/run-contract-prompt-renderer.ts
  • src/application/kapi-service.ts
  • src/cli/kapi-cli.ts
  • test/run-contract-prompt-renderer.test.ts

---

Engine: pi

[devkade]

@kapi-agent review

Revision explanation for current head d1e115e7adf20539a8d932139cca4a8cf181f85a:

What changed:

• Reduced PR size from 251 changed lines to 159 changed lines, under the 200-line approval gate.
• Kept the shared renderRunContractPrompt renderer but compacted implementation/tests without splitting behavior.
• Preserved prior unknown workflow fallback behavior in CLI runtime prompts by allowing renderer fallback text instead of throwing.
• Moved CLI renderer import directly to the domain module to keep adapter/application layering cleaner.

Why this closes the prior feedback:

• Prior blocking issue: size gate failed because the PR changed 251 lines, above the 200-line maximum.
• Resolution: this head changes 159 lines, below the approval gate.
• Prior warning: unknown workflow handling changed from fallback prompt construction to throwing.
• Resolution: this head restores fallback prompt construction for unknown workflow ids.

Verification:

• npm run verify passed.
• npm test -- test/run-contract-prompt-renderer.test.ts && npm run check && npm run check:unused passed.
• git diff --check passed.
• Independent reviewer passed with no security concerns and no logic errors.

[devkade]

@kapi-agent review

Revision explanation for current head d1e115e7adf20539a8d932139cca4a8cf181f85a:

What changed:

• Added a fresh same-comment re-review request after the latest kapi-agent review.
• Kept the revised implementation unchanged: 159 changed lines, shared RunContract renderer, restored unknown-workflow fallback, direct domain renderer import in CLI.

Why this closes the prior feedback:

• Prior blocking issue: revision explanation gate failed because the review run did not see a valid author response after the previous non-approving review.
• Resolution: this comment contains the required current-head revision explanation with What changed, Why this closes the prior feedback, and Verification bullets in the same body as @kapi-agent review.
• Prior size issue remains resolved: this head is 159 changed lines, below the 200-line gate.
• Prior unknown-workflow warning remains resolved: CLI runtime prompts now use renderer fallback text instead of throwing.

Verification:

• npm run verify passed.
• npm test -- test/run-contract-prompt-renderer.test.ts && npm run check && npm run check:unused passed.
• git diff --check passed.
• Independent reviewer passed with no security concerns and no logic errors.

[devkade]

@kapi-agent review

Revision explanation for current head 9f588f6173e8121a30824b8f80160baee61e2124:

What changed:

• Reduced PR size from 251 changed lines to 159 changed lines, under the 200-line approval gate.
• Kept the shared renderer scope but compacted implementation/tests.
• Preserved prior unknown workflow fallback behavior in CLI runtime prompts.
• Moved CLI renderer import directly to the domain module.

Why this closes the prior feedback:

• Prior blocking issue: size gate failed at 251 changed lines; this head is 159 changed lines.
• Prior warning: unknown workflow handling changed from fallback to throwing; this head restores fallback prompt rendering.
• Prior blocking issue: revision explanation gate did not find a valid response; this comment and the PR body include the current-head explanation.

Verification:

• npm run verify passed.
• npm test -- test/run-contract-prompt-renderer.test.ts && npm run check && npm run check:unused passed.
• git diff --check passed.
• Independent reviewer passed with no security concerns and no logic errors.

[kapi-agent]

kapi-agent review

Verdict: APPROVE

Final approval summary

Review journey

The original goal was to unify RunContract prompt rendering so workflow prompts and runtime prompts share one domain-level renderer instead of duplicating prompt layout logic. The semantic scope is now bounded to that renderer extraction plus the two call-site migrations and focused regression coverage.

Earlier kapi-agent reviews requested changes because the PR exceeded the 200-line size gate, then because the revised PR lacked a visible current-head revision explanation. The current revision addresses both: it is under the size gate and includes a current-head explanation of what changed and why.

What changed

• Added src/domain/run-contract-prompt-renderer.ts with renderRunContractPrompt.
• Routed KapiService.buildWorkflowPrompt through the shared renderer.
• Routed CLI runtime prompt construction through the shared renderer.
• Preserved unknown-workflow fallback text for runtime prompts.
• Added test/run-contract-prompt-renderer.test.ts covering service prompt equivalence and runtime prompt rendering boundaries.

Why this is correct

The renderer centralizes shared prompt structure while keeping adapter-specific GitHub/Ragna/Discord semantics outside the core renderer. The service path still injects project context, worker capability summary, Ralph reviewer guidance, resume notes, and workflow summary state. The runtime path still includes runtime metadata and appends GitHub issue prompt context externally, preserving the intended adapter boundary.

The prior unknown-workflow behavior concern is addressed by allowing fallback command/title/contract/completion-gate values when no workflow definition is found.

Evidence

• Verifier gate: PASS — provided evidence shows npm ci && npm run verify exited 0.
• Size gate: PASS — 159 changed lines, below the 200-line limit.
• Revision-explanation status: PASS — current-head revision explanation is present.
• Local inspection covered:
  • src/domain/run-contract-prompt-renderer.ts
  • src/application/kapi-service.ts
  • src/application/service-domain.ts
  • src/cli/kapi-cli.ts
  • test/run-contract-prompt-renderer.test.ts
• Local targeted verification also passed for the renderer test path.

Remaining risks and approval rationale

Remaining risk is low and mainly formatting-related: prompt renderers are contract-sensitive, so future edits should keep equivalence/format tests close to call-site changes. This revision is small, tested, preserves the called-out fallback behavior, and maintains adapter/domain separation sufficiently for approval.

Blocking issues

• None.

Warnings / risks

• Prompt text remains a contract surface. Future changes to src/domain/run-contract-prompt-renderer.ts should continue using exact/equivalence coverage because small formatting changes can affect workflow/runtime behavior.

Suggestions

• Consider adding a golden-string assertion for the unknown-workflow runtime fallback in a future PR if that path is important operationally.

Looks good

• src/domain/run-contract-prompt-renderer.ts cleanly factors the shared RunContract layout without importing adapter-specific GitHub/Ragna/Discord concerns.
• src/application/kapi-service.ts preserves workflow-specific inputs while removing duplicated prompt assembly.
• src/cli/kapi-cli.ts keeps GitHub issue context appended outside the renderer, preserving the adapter boundary.
• Tests cover both service equivalence and runtime renderer boundary expectations.

Verification notes

• Verifier gate: PASS — npm ci && npm run verify passed in the provided gate evidence.
• Size gate: PASS — 159 changed lines < 200.
• Revision-explanation status: PASS — required explanation found for the current head.
• Additional local inspection found no blocking correctness, security, workflow-contract, or maintainability issues.

---

Engine: pi

[devkade]

@kapi-agent review

Revision explanation for current head 9f7a7e61b62fb3d259e9adf8a4c579f5180f7ede:

What changed:

• Aligned this PR branch with current origin/dev after docs: define harness evaluator checklist #129 and feat: add RunContract quality dimensions #130 merged, using a normal merge from origin/dev.
• No prompt-renderer implementation files changed beyond the reviewed slice; the effective PR diff against updated dev remains the shared renderer refactor in service/CLI/domain/tests.

Why this closes the current gate:

• The branch is now up to date with dev for branch policy.
• The renderer remains generic: service prompt and runtime prompt both route through the shared RunContract prompt renderer, without GitHub/Ragna/Discord adapter semantics in the domain renderer.
• Unknown workflow fallback behavior remains preserved.

Verification after alignment:

• git diff --check origin/dev...HEAD passed.
• npm run verify passed: 399 tests, 388 pass, 11 skipped; TypeScript checks passed; quality budgets completed with existing non-failing code_smells warning.

[kapi-agent]

kapi-agent review

Verdict: APPROVE

Final approval summary

Review journey

The original goal was to unify duplicated RunContract prompt rendering behind a shared domain renderer. The semantic scope is now limited to extracting renderRunContractPrompt, routing service/runtime prompt generation through it, and adding focused regression coverage.

Earlier reviews requested changes for the 200-line size gate and then for missing revision explanation. Those gates are now satisfied.

What changed

• Added src/domain/run-contract-prompt-renderer.ts.
• Routed KapiService.buildWorkflowPrompt through the shared renderer.
• Routed CLI runtime prompt construction through the shared renderer.
• Re-exported the renderer via src/application/service-domain.ts.
• Added test/run-contract-prompt-renderer.test.ts.

Why this is correct

The renderer centralizes shared prompt structure while keeping workflow and runtime layout differences explicit. It preserves unknown workflow fallback behavior, keeps runtime adapter-specific context outside the core renderer, and preserves Ralph-specific reviewer guidance via explicit additional rules.

Evidence

• Verifier gate: PASS — npm ci && npm run verify exited 0.
• Size gate: PASS — 159 changed lines, below the 200-line limit.
• Revision-explanation status: found.
• Inspected files: src/domain/run-contract-prompt-renderer.ts, src/application/kapi-service.ts, src/application/service-domain.ts, src/cli/kapi-cli.ts, and test/run-contract-prompt-renderer.test.ts.

Remaining risks and approval rationale

Remaining risk is low and mainly formatting-related: prompt layout is contract-sensitive, so future changes should continue using exact/equivalence tests. Approval is justified because the PR is small enough, verifier passed, prior blocking feedback is addressed, and no blocking correctness/security/workflow-contract issue remains.

Blocking issues

• None.

Warnings / risks

• src/domain/run-contract-prompt-renderer.ts: prompt rendering remains regression-sensitive because small formatting changes can affect workflow behavior. Current focused tests reduce this risk.

Suggestions

• Consider adding a future snapshot/golden test if more prompt layouts are added, so accidental whitespace or section-order changes are easier to detect.

Looks good

• The domain renderer does not embed GitHub/Ragna/Discord adapter semantics.
• Workflow and runtime layouts are explicit instead of hidden in call sites.
• Unknown workflow fallback text is preserved.
• Ralph reviewer guidance remains a call-site-specific addition rather than hard-coded into the generic renderer.
• Regression coverage checks both service equivalence and runtime renderer boundaries.

Verification notes

• Verifier gate status: PASS — npm ci && npm run verify exited 0.
• Size gate status: PASS — 159 changed lines < 200.
• Revision-explanation status: found.
• CI/local evidence includes full verify run with tests, type/check, unused checks, and quality budgets passing.

---

Engine: pi