docs: define RunContract harness boundary

[devkade]

Summary

• Documents the RunContract Harness boundary in README.md before the implementation slices land.
• Defines RunContract as a generic projection over existing Kapi run state rather than a GitHub/PR-specific policy layer.
• Captures the layer split, candidate vocabulary, branding rule, and behavior-preserving implementation rhythm for feat: add generic RunContract projection without workflow-specific assumptions #98-feat: map RunContract status into Hermes/Ragna GitHub workflow adapters #102.

Linked issue

Closes #97

Problem

Kapi already has workflow state, artifacts, evidence, workers, quality probes, and supervisor surfaces, but the docs did not define where the upcoming RunContract layer belongs. Without that boundary, later implementation slices could accidentally put GitHub issues, PR review, Discord lanes, or Kade/Ragna authority semantics into generic core types.

Options considered

1. Documentation-first boundary slice
   • Pros: establishes core/adapter ownership before code; minimal risk; keeps later PRs reviewable.
   • Cons: does not add runtime behavior by itself.
2. Implement projection first and document afterward
   • Pros: faster path to visible functionality.
   • Cons: higher risk of encoding adapter-specific semantics into the first core API.
3. Create a broader policy-module architecture now
   • Pros: could support richer future extensibility.
   • Cons: premature for this track and explicitly out of scope for the first slice.

Selected approach

Selected option: documentation-first boundary slice.

Why this one: issue #97 is design-sensitive and intentionally precedes #98-#102. A small README addition is enough to define RunContract as a generic, pre-workflow projection while keeping implementation and adapter semantics for later slices.

Risks/trade-offs: this is intentionally docs-only; the runtime projection still needs to land in follow-up PRs.

Implementation by file/surface

• README.md
  • Adds a RunContract Harness Boundary section.
  • Defines the core/runtime-adapter/external-adapter layer split.
  • States that core owns generic run state projection, evidence, artifact refs, contract presets, completion criteria, advisory quality hints, and generic steering hints.
  • States that core does not own GitHub/PR semantics, Discord lanes, kapi-agent policy, merge/tracker cleanup, or Kade/Ragna authority rules.
  • Clarifies that Ilchul remains product/documentation branding only; reusable identifiers should stay semantic.

Why this fixes it

The issue asks for a source-of-truth boundary before implementation. The README now gives later slices a concrete contract: build generic RunContract primitives in core, keep presentation/runtime mapping in adapters, and keep GitHub/Ragna semantics outside the generic layer.

QA / Verification

• git diff --cached --check — pass
• npm run verify — pass locally before the docs-only commit; output included tests 393, pass 382, skipped 11, plus tsc --noEmit, tsc --noEmit --noUnusedLocals --noUnusedParameters, and quality:budgets passing with the existing non-failing code_smells warning.
• PR size preflight: git diff --shortstat origin/dev...HEAD — 1 file changed, 16 insertions(+).

Anomalies observed

• A broader local RunContract projection prototype exists in the worktree as untracked candidate files for follow-up issue slices. It is intentionally not included in this PR to keep docs: define RunContract harness core-adapter boundary #97 reviewable and docs-only.
• npm run verify reports the existing non-failing quality budget warning: code_smells value=46 target="<=20" status=warn.

Risks / Follow-up

• Follow-up implementation issues remain: 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.
• This PR should be merged before projection/scoring/rendering work so the later code has a stable boundary contract.

kapi-agent review expectations and current-head merge gate

• Expected kapi-agent result: approve if the docs boundary stays generic and the PR remains within the size gate.
• Merge gate: only merge after current-head kapi-agent approval and a successful kapi-agent/review check when present.

[kapi-agent]

kapi-agent review

Verdict: APPROVE

Final approval summary

Review journey

This PR’s original goal is to define the RunContract Harness boundary before implementation work lands. The semantic scope is intentionally docs-only: add a README source-of-truth section that keeps RunContract generic and prevents GitHub/PR, Discord, kapi-agent, or Kade/Ragna semantics from leaking into core. There was no prior kapi-agent review ping-pong for this PR.

What changed

README.md adds a RunContract Harness Boundary section defining:

• RunContract as a projection over existing WorkflowState and WorkflowDefinition.
• Core/runtime-adapter/external-adapter ownership boundaries.
• Explicit exclusions from core policy ownership.
• Small candidate vocabulary.
• A behavior-preserving implementation sequence for follow-up slices.

Why this is correct

The change is documentation-only and aligns with the stated issue: establish the boundary before code. It keeps core generic, reserves presentation/runtime rendering for adapters, and explicitly prevents external workflow policy semantics from becoming generic Kapi primitives.

Evidence

• Verifier gate: PASS — npm ci && npm run verify exited 0.
• Size gate: PASS — 16 changed lines, below the 200-line limit.
• Revision-explanation status: not required; found.
• Inspected files/diff: README.md, git diff origin/dev...HEAD.

Remaining risks and approval rationale

Remaining risk is limited to wording interpretation in later implementation PRs, not runtime behavior. Approval is justified because the PR is small, docs-only, passes verification, stays within the requested boundary, and introduces no blocking correctness, safety, or workflow-contract issue.

Blocking issues

None.

Warnings / risks

• README.md: “pre-workflow projection” could be read ambiguously in future implementation work because the text also says it reads existing WorkflowState plus WorkflowDefinition. This is not blocking, but follow-up PRs should preserve the intended meaning: pre-workflow-policy / supervisor projection, not a replacement lifecycle source of truth.

Suggestions

• In the first implementation PR, consider adding tests that assert RunContract does not persist contract.json and does not introduce GitHub/PR-specific fields into core types.

Looks good

• The boundary clearly separates generic core concepts from external adapter interpretations.
• The vocabulary is intentionally small and additive.
• The implementation rhythm explicitly preserves existing workflow APIs, artifacts, validation gates, and CLI behavior.

Verification notes

• Verifier gate status: PASS — npm ci && npm run verify exited 0.
• Size gate status: PASS — 16 changed lines < 200.
• Revision-explanation status: not required; found.
• Local inspection confirmed this PR only modifies README.md.

---

Engine: pi

[devkade]

@kapi-agent review