docs: define RunContract harness core-adapter boundary

[devkade]

Status

Design-sensitive documentation issue. This is the source-of-truth boundary slice for the RunContract Harness track; it should land before implementation issues #98-#102.

Summary

Document RunContract Harness as a generic, pre-workflow substrate over Kapi/Ilchul run state before adding projection, criteria, scoring, rendering, or GitHub/Ragna adapter code.

Context

Kapi already has workflow state, artifacts, evidence, workers, quality probes, and supervisor surfaces. The next track introduces a more generic RunContract vocabulary so these concepts can be inspected without assuming coding-specific workflows.

The previous stabilization prerequisites noted in this issue's comments have now been reconciled in related PRs/issues (#78-#81, #87-#88, #15), so this docs boundary is the next safe slice.

Problem

The current docs describe Kapi's durable modes and supervisor runtime, but they do not yet define the RunContract layer split. Without that boundary, later implementation slices could accidentally move GitHub issues, PR review, Discord lanes, or Kade/Ragna authority rules into generic core types.

Scope

• Define RunContract Harness as a generic run/contract/evidence/artifact/completion view over existing Kapi state.
• Clarify that Ilchul is product/documentation branding only; reusable code/API/tool identifiers should use semantic names such as run, contract, preset, harness, evidence, score, and steer instead of ilchul.
• Explain the intended layer split:
  • Layer 1: Ilchul/Kapi Core / RunContract Harness.
  • Layer 2: Runtime and presentation adapters.
  • Layer 3: Hermes/Ragna workflow adapters.
• Capture the implementation rhythm for feat: add generic RunContract projection without workflow-specific assumptions #98-feat: map RunContract status into Hermes/Ragna GitHub workflow adapters #102: docs boundary first, projection second, evidence/completion primitives third, advisory quality hints fourth, supervisor rendering fifth, GitHub/Ragna adapter mapping last.
• Keep the change documentation-only unless a follow-up issue explicitly asks for code.

Non-goals

• No runtime behavior changes.
• No new core PolicyModule system in this slice.
• No GitHub issue/PR, kapi-agent, Discord lane, dev merge, tracker cleanup, or Kade/Ragna authority semantics in the generic core layer.
• No replacement of existing Kapi modes or workflow artifacts.

Acceptance criteria

• Source-of-truth docs explain RunContract Harness as generic and pre-workflow, not GitHub/PR-specific.
• Docs state what core owns: run state, evidence model, artifact references, contract preset shape, completion criteria, quality hints, and generic steering hints.
• Docs state what core does not own: GitHub/PR semantics, repository/code-review assumptions, Discord lane semantics, kapi-agent review policy, merge/tracker cleanup, and Kade/Ragna authority rules.
• Docs identify ContractPreset, EvidenceExpectation, CompletionCriteria, and ScoringHint as candidate vocabulary without making PolicyModule the first-slice primitive.
• Documentation preserves the additive, behavior-preserving migration constraint for feat: add generic RunContract projection without workflow-specific assumptions #98-feat: map RunContract status into Hermes/Ragna GitHub workflow adapters #102.
• Docs clarify that Ilchul is product/documentation branding only; reusable code/API/tool identifiers should use semantic names such as run, contract, preset, harness, evidence, score, and steer instead of ilchul.

Verification

• git diff --check
• Run docs-related tests if touched by the change.
• Search the new docs for accidental framing that makes GitHub/PR workflows mandatory for RunContract core.

References

• Follow-up implementation track: feat: add generic RunContract projection without workflow-specific assumptions #98, feat: model EvidenceExpectation and CompletionCriteria for RunContract #99, feat: add soft quality scoring hints for RunContract status #100, feat: render RunContract status through existing supervisor surfaces #101, feat: map RunContract status into Hermes/Ragna GitHub workflow adapters #102
• Existing source anchors: README.md, GOAL.md, src/domain/types.ts, src/domain/workflows.ts, src/domain/quality-probe.ts, src/cli/kapi-cli.ts

[devkade]

Sequencing note

Kade called out that the pre-existing stabilization issues should be considered before this RunContract refactor track.

Recommended order:

1. Resolve or explicitly defer the existing control-plane/correctness bugs first:
   • Harden kapi start registry slug paths and attach command quoting #78 registry slug path trust + attach command quoting
   • Keep kapi list and doctor usable when a registry entry JSON is corrupt #79 corrupt registry entry should not break list / doctor
   • Normalize --from consistently for live kapi start and dry-run #81 live vs dry-run --from normalization
   • Use ledger-derived best-so-far consistently in Autoresearch loop and validation #80 Autoresearch ledger-derived best-so-far correctness
2. Then land this docs rhythm issue (docs: define RunContract harness core-adapter boundary #97), because it is source-of-truth alignment and should stay additive/behavior-preserving.
3. Then proceed with RunContract implementation issues feat: add generic RunContract projection without workflow-specific assumptions #98-feat: map RunContract status into Hermes/Ragna GitHub workflow adapters #102.

#87 and #88 are related to the Hermes/Ragna GitHub adapter/supervisor surface. They are not prerequisites for the generic RunContract core, but they should be reconciled before or alongside #102 so GitHub/PR semantics stay in the adapter layer rather than leaking into core.