Kapi → Ilchul RunContract Harness roadmap

[devkade]

Kapi → Ilchul RunContract Harness roadmap

Last updated: 2026-05-17 · Owner: Ragna/coding · Reference model: Q00/ouroboros issue 961

TL;DR — status at a glance

Track	Status	Linked sub-issues	Current state / next
Track A — RunContract Harness core	✅ complete	#97, #98, #99, #100, #101, #102, #115, #116, #117, #128, #133, #134, #135, #136	Boundary, projection, evidence/completion, advisory hints/dimensions, supervisor rendering, GitHub/Ragna adapter, shared prompt renderer, evaluator docs, and bounded cleanup are merged.
Track B — Ilchul product/storage migration	✅ complete for current plan	#119, #121, #169, #181	Naming/compatibility policy is documented; .ilchul is canonical forward storage; workflow storage now routes to .ilchul only. No destructive local rename.
Track C — Preset evolution	✅ complete for current preset contract pass	#118, #182, #183, #184	Deep Interview, Ralph, Integrate, and Autoresearch preset contracts are defined. Current pass is docs/test contract-first; no runtime rewrite or adapter-specific core semantics.
Track D — Harness governance / review / module metadata	✅ current pass complete	#117, #120, #141, #122	Anti-Goodhart checklist, metadata-only module registry/retirement signals, risk-based review harness, and formal kapi-agent approval gate are merged.
Track E — Runtime / worker substrate boundary	✅ foundational pass complete	#148, #168, #169, #170, #171, #172	Retention policy, DAG/claim/lease evidence gates, storage/config policy, RunContract-centered runtime boundaries, strategy selector, and reward ledger loop are merged.
Track F — Objective-driven learning runtime	🟡 open roadmap	#167	Umbrella remains open for the next objective-driven parallel runtime harness direction.

Merge status update: #192 merged #181 and #193 merged #182/#183/#184 on 2026-05-17 KST. The Track B storage slice and Track C preset-contract slice are now reconciled into this roadmap.

Purpose

This is the single source of truth for sequencing Kapi’s evolution into the Ilchul-branded RunContract Harness without losing the current working system or overfitting the core to Ragna’s GitHub issue → PR → review workflow.

This roadmap tracks:

1. Which RunContract/Ilchul changes are canonical follow-ups after docs: define RunContract harness core-adapter boundary #97–feat: map RunContract status into Hermes/Ragna GitHub workflow adapters #102.
2. Which ideas are product/brand docs vs core code/API/storage changes.
3. Which sub-issues are linked to each execution track.
4. Which gates must pass before storage/API/default behavior changes.
5. How the worker/runtime substrate should evolve without collapsing generic RunContract core into product-specific adapters.

When in doubt about opening a new Ilchul/Kapi substrate issue, comment here first or add it to the relevant track before creating another standalone issue.

Core boundary

Layer 1: Kapi/Ilchul Core — RunContract Harness
  Owns:
    - generic run state projection
    - evidence model
    - artifact references
    - ContractPreset interpretation
    - completion criteria
    - advisory quality dimensions
    - generic steering hints

  Does not own:
    - GitHub issue/PR semantics
    - kapi-agent review policy
    - repository merge/tracker cleanup
    - Discord lane/thread semantics
    - Kade/Ragna authority policy

Layer 2: Runtime / Adapter layer
  Owns:
    - tool-specific sensing
    - worker/session/runtime mapping
    - command execution
    - platform-specific event ingestion
    - product-specific rendering bridges
    - storage/config compatibility policy
    - worker lifecycle, retention, DAG/claim/lease, event, and evidence boundaries

Layer 3: Hermes/Ragna workflow layer
  Owns:
    - issue → PR → kapi-agent review → dev merge → tracker reconciliation
    - Discord reporting style
    - Kade’s coding workflow policy

Naming and storage policy

Ilchul is the product/documentation/brand name and .ilchul is the forward canonical storage root.

Reusable code/API/tool identifiers should prefer semantic names:

• run
• contract
• preset
• harness
• evidence
• score
• steer
• worker
• runtime

Do not do broad kapi -> ilchul replacement. Legacy identifiers remain compatibility/CLI surface decisions unless an explicit migration issue authorizes the change. Existing local .kapi folders must not be destructively renamed or deleted; migration/cleanup remains explicit and non-destructive.

Track map

flowchart LR
    classDef done fill:#0E8A16,color:#fff,stroke:#0E8A16
    classDef open fill:#FBCA04,color:#000,stroke:#FBCA04

    subgraph A["Track A — RunContract Harness core"]
      A0["#97-#102 foundation"]:::done
      A1["#115 shared renderer"]:::done
      A2["#116 5D advisory dimensions"]:::done
      A3["#117 evaluator checklist"]:::done
      A4["#128 + #133-#136 cleanup"]:::done
      A0 --> A1 --> A2 --> A3 --> A4
    end

    subgraph B["Track B — Ilchul product/storage"]
      B1["#119 naming policy"]:::done
      B2["#121 .kapi removal/.ilchul plan"]:::done
      B3["#169 storage/config/retention policy"]:::done
      B4["#181 route workflow storage to .ilchul"]:::done
      B1 --> B2 --> B3 --> B4
    end

    subgraph C["Track C — Presets"]
      C1["#118 Deep Interview draft"]:::done
      C2["#182 Ralph preset"]:::done
      C3["#183 Integrate preset"]:::done
      C4["#184 Autoresearch preset"]:::done
      C1 --> C2 --> C3 --> C4
    end

    subgraph D["Track D — Governance/review/module metadata"]
      D1["#117 anti-Goodhart checklist"]:::done
      D2["#120 module registry/retirement signals"]:::done
      D3["#141 risk-based review harness"]:::done
      D4["#122 formal approval gate"]:::done
      D1 --> D2 --> D3 --> D4
    end

    subgraph E["Track E — Runtime/worker substrate"]
      E1["#148 worker retention cleanup design"]:::done
      E2["#168 DAG/claim/lease/evidence gates"]:::done
      E3["#170 RunContract runtime boundaries"]:::done
      E4["#171 strategy selector"]:::done
      E5["#172 reward ledger loop"]:::done
      E1 --> E2 --> E3 --> E4 --> E5
    end

    subgraph F["Track F — Objective-driven learning runtime"]
      F1["#167 umbrella"]:::open
    end

    A4 --> C1
    B4 -. storage foundation .-> E2
    D2 -. metadata/governance .-> F1
    E5 -. runtime foundation .-> F1

Loading

Linked sub-issues by track

Track A — RunContract Harness core

• docs: define RunContract harness core-adapter boundary #97 — RunContract core-adapter boundary documented.
• feat: add generic RunContract projection without workflow-specific assumptions #98 — Generic RunContract projection added without workflow-specific assumptions.
• feat: model EvidenceExpectation and CompletionCriteria for RunContract #99 — EvidenceExpectation and CompletionCriteria modeled.
• feat: add soft quality scoring hints for RunContract status #100 — Soft advisory quality hints added.
• feat: render RunContract status through existing supervisor surfaces #101 — RunContract status rendered through supervisor surfaces.
• feat: map RunContract status into Hermes/Ragna GitHub workflow adapters #102 — Hermes/Ragna GitHub workflow adapter added outside core.
• refactor: unify RunContract prompt rendering across service and CLI runtime #115 — Shared RunContract prompt renderer across service and CLI runtime.
• feat: map RunContract quality hints to five advisory dimensions #116 — Five advisory quality dimensions.
• docs: define Kapi harness evaluator and anti-Goodhart checklist #117 — Harness evaluator / anti-Goodhart checklist.
• roadmap: Track A RunContract refactor cleanup #128 — Track A cleanup checkpoint.
• refactor: bound Track A RunContract formatter cleanup #133 — Bounded RunContract formatter cleanup.
• refactor: extract Kapi CLI report formatters #134 — CLI report formatter extraction.
• refactor: extract Kapi CLI worker events and GitHub preflight helpers #135 — CLI worker events and GitHub preflight helper extraction.
• refactor: extract KapiService authored artifact metadata helpers #136 — KapiService authored artifact metadata helper extraction.

Track B — Ilchul product/storage migration

• docs: establish Ilchul naming and compatibility policy #119 — Ilchul naming and compatibility policy.
• design: plan .kapi removal and .ilchul canonical storage #121 — .kapi removal and .ilchul canonical storage plan.
• Config/design: define .ilchul storage, adapter config, and worker retention policy #169 — .ilchul storage, adapter config, and worker retention policy.
• refactor: route workflow storage to .ilchul only #181 — Route workflow storage to .ilchul only.

Track C — Preset evolution

• feat: define Deep Interview RunContractDraft artifact #118 — Deep Interview RunContractDraft artifact.
• feat: define Ralph governed implementation preset #182 — Ralph governed implementation preset.
• feat: define Integrate governance preset #183 — Integrate governance preset.
• feat: define Autoresearch metric-experiment preset #184 — Autoresearch metric-experiment preset.

Track D — Harness governance / review / module metadata

• docs: define Kapi harness evaluator and anti-Goodhart checklist #117 — Evaluator and anti-Goodhart checklist.
• feat: add metadata-only harness module registry and retirement signals #120 — Metadata-only harness module registry and retirement signals.
• fix: require formal kapi-agent approval before merge-ready #122 — Formal kapi-agent approval gate before merge-ready.
• feat: add risk-based Ilchul review harness for kapi-agent #141 — Risk-based Ilchul review harness for kapi-agent.

Track E — Runtime / worker substrate boundary

• design: define completed worker tmux session lifecycle cleanup #148 — Completed worker tmux session lifecycle cleanup design.
• Feature: add DAG scheduler with claim, lease, heartbeat, and task evidence gates #168 — DAG scheduler with claim, lease, heartbeat, and task evidence gates.
• Config/design: define .ilchul storage, adapter config, and worker retention policy #169 — Storage/config/worker retention policy.
• Architecture: define RunContract-centered learning runtime boundaries #170 — RunContract-centered learning runtime boundaries.
• Feature: add policy simulation selector for execution strategy choice #171 — Policy simulation selector for execution strategy choice.
• Feature: add objective evaluation and reward-ledger learning loop #172 — Objective evaluation and reward-ledger learning loop.

Track F — Objective-driven learning runtime

• Roadmap: objective-driven learning parallel runtime harness #167 — Roadmap: objective-driven learning parallel runtime harness.

Acceptance gates before default/storage/API changes

Before any default flip, storage migration, or public API rename:

1. Existing Kapi CLI and Pi extension behavior remains backward-compatible or has an explicit deprecation plan.
2. RunContract core remains free of GitHub/PR/kapi-agent/Ragna/Discord semantics.
3. npm run verify passes on implementation PRs.
4. A migration issue exists for any storage path or schema change.
5. Human-facing docs explain Kapi vs Ilchul naming while preserving non-destructive handling for existing local .kapi workspaces.
6. Score/quality changes remain advisory unless a separate design issue explicitly authorizes stronger gates.
7. Runtime work preserves Pi extension boundaries: TS remains the Pi façade; runtime internals stay behind explicit adapter/CLI contracts.
8. Cleanup/removal must remain non-destructive and explicit; no silent local folder deletion or forced migration.

Current next step

The original #114 roadmap tracks are reconciled through #181 and #182/#183/#184. The only open linked umbrella in this map is #167 for the next objective-driven learning parallel runtime harness direction.

Changelog

• 2026-05-17 — Reconciled roadmap after refactor: route workflow storage to .ilchul #192/docs: define RunContract preset contracts #193 merge: refactor: route workflow storage to .ilchul only #181 and feat: define Ralph governed implementation preset #182/feat: define Integrate governance preset #183/feat: define Autoresearch metric-experiment preset #184 are closed and linked into Track B/C; all related sub-issues are grouped by track; Roadmap: objective-driven learning parallel runtime harness #167 remains the only open linked umbrella.
• 2026-05-16 — Track C split-out created feat: define Ralph governed implementation preset #182, feat: define Integrate governance preset #183, feat: define Autoresearch metric-experiment preset #184; Deep Interview remained under feat: define Deep Interview RunContractDraft artifact #118.
• 2026-05-15 — Track A execution sequence and cleanup checkpoint added through refactor: unify RunContract prompt rendering across service and CLI runtime #115/feat: map RunContract quality hints to five advisory dimensions #116/docs: define Kapi harness evaluator and anti-Goodhart checklist #117/roadmap: Track A RunContract refactor cleanup #128.
• 2026-05-15 — Created sub-issues refactor: unify RunContract prompt rendering across service and CLI runtime #115–design: plan .kapi removal and .ilchul canonical storage #121 from the proposed queue and linked them in this SSOT.
• 2026-05-15 — Kade correction recorded: .kapi -> .ilchul is the forward direction, but existing local .kapi folders must not be destructively/eagerly renamed.
• 2026-05-15 — Roadmap SSOT created after docs: define RunContract harness core-adapter boundary #97–feat: map RunContract status into Hermes/Ragna GitHub workflow adapters #102 completed.

[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]

Added follow-up Track A refactor checkpoint: #128. This is intentionally post-#115: inspect the final shared prompt renderer diff first, then consolidate remaining RunContract formatting/report/helper duplication only where evidence remains.