feat: add RunContract quality hints

[devkade]

Summary

• Adds advisory RunContract quality hint primitives and rollup status.
• Computes transparent hints for evidence readiness, lifecycle blockers, pending decisions, and unresolved risks.
• Keeps quality advisory: completion stays driven by existing workflow status and evidence criteria.

Issue

Closes #100

Implementation notes

• ScoringHint carries id, level, reason text, and evidenceBacked metadata.
• Quality rollup is intentionally coarse: ready, attention, blocked, or unknown.
• Reasons explicitly preserve evidence-backed readiness as the target and discourage superficial hint/score passing.
• Core wording remains generic; it does not encode GitHub, PR, kapi-agent, Discord, or Ragna-specific gate names.

Verification

• npm test -- test/run-contract.test.ts
• npm run verify
• git diff --check
• grep -RniE 'github|pullRequest|issueNumber|kapiAgent|discord|ragna' src/domain/run-contract.ts test/run-contract.test.ts returned no matches

Notes

• npm run verify still reports existing non-failing quality budget warning: code_smells=44, target <=20, status warn.

[devkade]

kapi-agent review

Verdict: APPROVE

Final approval summary

Review journey

• Reviewed feat: add RunContract quality hints #111 at head 80f823df3ae9846512a011c622f5e4000380c39a against feat: add soft quality scoring hints for RunContract status #100.
• Confirmed RunContract quality hints are advisory evaluator output, not completion authority.
• Checked that hint reasons are explicit and anti-Goodhart oriented: evidence-backed readiness remains the target.
• Confirmed no GitHub, PR, Discord, Ragna, or kapi-agent-specific gate names entered the core RunContract scoring surface.

Evidence

• git diff --check passed.
• npm test -- test/run-contract.test.ts passed.
• npm run verify passed.
• Domain boundary grep returned no adapter/branding matches for src/domain/run-contract.ts and test/run-contract.test.ts.

Notes

• Existing non-failing quality budget warning remains: code_smells=44, target <=20, status warn.
• This warning is advisory and does not block this focused RunContract quality-hint slice.

Decision

Approved for merge into dev.

[kapi-agent]

kapi-agent review

Verdict: APPROVE

Final approval summary

Review journey

This PR adds advisory RunContract quality hints for the existing RunContract projection. The semantic scope is narrow: introduce quality hint primitives, compute a coarse quality rollup, and keep completion authority tied to existing workflow status and evidence criteria. There was no prior kapi-agent review on this PR, so no review/fix ping-pong needed to be closed.

What changed

The main change is in src/domain/run-contract.ts:

• Replaces the placeholder quality status with ready | attention | blocked | unknown.
• Adds ScoringHint with id, level, reason, and evidenceBacked.
• Computes hints for lifecycle blockers, missing evidence, satisfied evidence, pending decisions, and unresolved risks.
• Keeps completion derived from existing completion criteria.

Tests in test/run-contract.test.ts now cover:

• Blocked quality when pending decisions exist.
• Ready quality when completion evidence is satisfied.
• Attention quality when unresolved risks remain despite completion.

Why this is correct

The implementation keeps the quality surface advisory. It does not change the existing completion calculation or make quality status authoritative for workflow completion. The hint ordering and rollup are straightforward: blocked dominates attention, attention dominates unknown, and otherwise the view is ready. The wording also explicitly discourages superficial score-passing and points back to evidence-backed workflow validation.

Evidence

• Verifier gate: PASS — npm ci && npm run verify exited 0.
• Size gate: PASS — 87 changed lines, below the 200-line hard limit.
• Revision-explanation status: not required for this first kapi-agent review; PR body contains implementation and verification notes.
• Inspected files: src/domain/run-contract.ts, test/run-contract.test.ts.
• Additional search found no remaining references to the removed "not-evaluated" quality status in src or test.

Remaining risks and approval rationale

Remaining risk is low and mainly contract-evolution related: downstream consumers of RunContractView.quality.status must tolerate the new status vocabulary and hints field. Within this repository, no conflicting usages were found, tests cover the new behavior, and the change is small and scoped. Approval is justified.

Blocking issues

None.

Warnings / risks

• src/domain/run-contract.ts: This changes the public RunContract quality status vocabulary from a placeholder to real statuses. Repository-internal usage appears safe, but external consumers may need to update if they depended on "not-evaluated".

Suggestions

• Consider documenting the quality status vocabulary wherever RunContract output is described for external consumers, if such docs exist outside this PR.

Looks good

• Quality hints remain advisory and do not alter completion authority.
• The rollup logic is simple and deterministic.
• Tests cover ready, blocked, and attention outcomes.
• The implementation stays generic and avoids product-/platform-specific gate names.

Verification notes

• Verifier gate: PASS — npm ci && npm run verify exited 0.
• Size gate: PASS — 87 changed lines < 200.
• Revision-explanation status: not required; found in PR body anyway.
• PR evidence includes targeted RunContract tests, full verify, diff check, and grep for forbidden product-specific terms.

---

Engine: pi