feat: add runcontract quality dimensions

Author: devkade

src/domain/run-contract.ts

@@ -5,6 +5,8 @@ export type RunContractCompletionStatus = "not-started" | "in-progress" | "block
 export type RunContractCriteriaStatus = "satisfied" | "needs-evidence" | "unknown";
 export type RunContractQualityStatus = "ready" | "attention" | "blocked" | "unknown";
 export type ScoringHintLevel = "ok" | "attention" | "blocked" | "unknown";
+export type RunContractQualityDimensionId = "alignment" | "evidence" | "completeness" | "simplicity" | "risk";
+export type RunContractQualityDimensionStatus = "pass" | "warn" | "fail";
 
 export interface ScoringHint {
   id: string;
@@ -13,6 +15,14 @@ export interface ScoringHint {
   evidenceBacked: boolean;
 }
 
+export interface RunContractQualityDimension {
+  id: RunContractQualityDimensionId;
+  label: string;
+  status: RunContractQualityDimensionStatus;
+  reasons: string[];
+  evidenceBacked: boolean;
+}
+
 export interface EvidenceExpectation {
   id: string;
   summary: string;
@@ -68,6 +78,7 @@ export interface RunContractView {
   quality: {
     status: RunContractQualityStatus;
     summary: string;
+    dimensions: RunContractQualityDimension[];
     hints: ScoringHint[];
   };
 }
@@ -140,28 +151,66 @@ function isExpectationSatisfied(state: WorkflowState, expectation: EvidenceExpec
 }
 
 export function buildQualityHints(state: WorkflowState, results: CompletionCriteriaResult[]): RunContractView["quality"] {
-  const hints: ScoringHint[] = [];
+  const dimensions = buildQualityDimensions(state, results);
+  const hints = dimensionsToHints(dimensions);
+  const status = summarizeQualityStatus(hints);
+  return { status, summary: summarizeQuality(status, dimensions), dimensions, hints };
+}
+
+export function buildQualityDimensions(state: WorkflowState, results: CompletionCriteriaResult[]): RunContractQualityDimension[] {
   const missingRequired = results.filter((result) => result.required && result.status === "needs-evidence");
-  if (state.status === "blocked" || state.status === "failed") {
-    hints.push({ id: "lifecycle-blocked", level: "blocked", reason: state.blocker ?? `Workflow lifecycle is ${state.status}; supervisor review should resolve the blocker before treating quality as ready.`, evidenceBacked: Boolean(state.blocker || state.evidence.length) });
-  } else if (missingRequired.length) {
-    hints.push({ id: "evidence-readiness", level: "attention", reason: `Required evidence is missing (${missingRequired.flatMap((result) => result.missingExpectationIds).join(", ")}); evidence-backed completion remains the target, not superficial score passing.`, evidenceBacked: false });
-  } else if (state.evidence.length) {
-    hints.push({ id: "evidence-readiness", level: "ok", reason: "Required evidence expectations are satisfied by recorded validation evidence; keep completion authority with workflow validation and review.", evidenceBacked: true });
-  } else {
-    hints.push({ id: "evidence-readiness", level: "unknown", reason: "No validation evidence is available yet; quality is unknown until evidence is recorded.", evidenceBacked: false });
-  }
-
-  if (state.pendingDecision) {
-    hints.push({ id: "pending-decision", level: "blocked", reason: `Pending decision remains unresolved: ${state.pendingDecision.prompt}`, evidenceBacked: false });
-  }
-
-  if (state.risks.length) {
-    hints.push({ id: "unresolved-risk", level: "attention", reason: `Unresolved risks remain (${state.risks.length}); do not optimize this hint away without addressing the underlying risk evidence.`, evidenceBacked: state.evidence.length > 0 });
-  }
+  const missingExpectationIds = missingRequired.flatMap((result) => result.missingExpectationIds);
+  const hasBlockingLifecycle = state.status === "blocked" || state.status === "failed";
+  const hasTerminalFailure = state.status === "failed" || state.status === "cancelled";
+  const goal = typeof state.task === "string" ? state.task.trim() : "";
+  const simplicityRisk = state.risks.find((risk) => /abstraction|complex|complicated|scope|broad|clever|over[- ]?engineer/i.test(risk));
 
-  const status = summarizeQualityStatus(hints);
-  return { status, summary: summarizeQuality(status, hints), hints };
+  return [
+    qualityDimension("alignment", "Alignment", hasTerminalFailure ? "fail" : goal ? "pass" : "warn", [
+      hasTerminalFailure ? `Workflow lifecycle is ${state.status}; confirm the current work still aligns with the requested goal before continuing.` : goal ? "Workflow goal is present and remains tied to the generic RunContract source workflow." : "Workflow goal is missing or empty; advisory alignment cannot be confirmed.",
+    ], state.evidence.some((evidence) => Boolean(evidence.acceptanceCriteria?.length))),
+    qualityDimension("evidence", "Evidence", missingRequired.length ? "warn" : state.evidence.length ? "pass" : "warn", [
+      missingRequired.length ? `Required evidence is missing (${missingExpectationIds.join(", ")}); evidence quality is degraded without changing completion authority.` : state.evidence.length ? "Required evidence expectations are satisfied by recorded validation evidence." : "No validation evidence is available yet; record concrete evidence before treating quality as ready.",
+    ], !missingRequired.length && state.evidence.length > 0),
+    qualityDimension("completeness", "Completeness", hasBlockingLifecycle ? "fail" : state.pendingDecision || missingRequired.length ? "warn" : "pass", [
+      hasBlockingLifecycle ? state.blocker ?? `Workflow lifecycle is ${state.status}; resolve the blocker before considering the work complete.` : state.pendingDecision ? `Pending decision remains unresolved: ${state.pendingDecision.prompt}` : missingRequired.length ? "Completion criteria still need required evidence; validation remains authoritative." : "No pending decision or missing required completion evidence is visible.",
+    ], !missingRequired.length && state.evidence.length > 0),
+    qualityDimension("simplicity", "Simplicity", simplicityRisk ? "warn" : "pass", [
+      simplicityRisk ? `Risk calls out possible complexity or over-broad scope: ${simplicityRisk}` : "No explicit complexity, scope, or over-engineering risk is recorded.",
+    ], state.evidence.length > 0),
+    qualityDimension("risk", "Risk", hasBlockingLifecycle ? "fail" : state.risks.length || state.pendingDecision ? "warn" : "pass", [
+      hasBlockingLifecycle ? state.blocker ?? `Workflow lifecycle is ${state.status}; risk remains blocking.` : state.risks.length ? `Unresolved risks remain (${state.risks.length}); address the underlying risk evidence rather than optimizing the hint.` : state.pendingDecision ? "Pending decision keeps residual risk open until resolved." : "No unresolved risks or blockers are recorded.",
+    ], state.evidence.length > 0 || Boolean(state.blocker)),
+  ];
+}
+
+function qualityDimension(id: RunContractQualityDimensionId, label: string, status: RunContractQualityDimensionStatus, reasons: string[], evidenceBacked: boolean): RunContractQualityDimension {
+  return { id, label, status, reasons, evidenceBacked };
+}
+
+function dimensionsToHints(dimensions: RunContractQualityDimension[]): ScoringHint[] {
+  return dimensions
+    .filter((dimension) => dimension.status !== "pass" || dimension.id === "evidence")
+    .map((dimension) => ({
+      id: hintIdForDimension(dimension),
+      level: hintLevelForDimension(dimension),
+      reason: `${dimension.label}: ${dimension.reasons.join(" ")}`,
+      evidenceBacked: dimension.evidenceBacked,
+    }));
+}
+
+function hintIdForDimension(dimension: RunContractQualityDimension): string {
+  if (dimension.id === "evidence") return "evidence-readiness";
+  if (dimension.id === "risk") return dimension.status === "fail" ? "lifecycle-blocked" : "unresolved-risk";
+  if (dimension.id === "completeness" && dimension.reasons.some((reason) => reason.startsWith("Pending decision"))) return "pending-decision";
+  return `${dimension.id}-dimension`;
+}
+
+function hintLevelForDimension(dimension: RunContractQualityDimension): ScoringHintLevel {
+  if (dimension.status === "fail") return "blocked";
+  if (hintIdForDimension(dimension) === "pending-decision") return "blocked";
+  if (dimension.status === "warn") return "attention";
+  return "ok";
 }
 
 function summarizeQualityStatus(hints: ScoringHint[]): RunContractQualityStatus {
@@ -171,9 +220,11 @@ function summarizeQualityStatus(hints: ScoringHint[]): RunContractQualityStatus
   return "ready";
 }
 
-function summarizeQuality(status: RunContractQualityStatus, hints: ScoringHint[]): string {
-  if (status === "ready") return "Advisory quality hints are ready; evidence-backed workflow validation remains authoritative.";
-  return `Advisory quality hints need ${status === "blocked" ? "blocker resolution" : status}; ${hints.length} hint(s) explain evidence-backed readiness without becoming completion authority.`;
+function summarizeQuality(status: RunContractQualityStatus, dimensions: RunContractQualityDimension[]): string {
+  const failing = dimensions.filter((dimension) => dimension.status === "fail").length;
+  const warning = dimensions.filter((dimension) => dimension.status === "warn").length;
+  if (status === "ready") return "All five advisory quality dimensions pass; evidence-backed workflow validation remains authoritative.";
+  return `Five advisory quality dimensions need attention (${failing} fail, ${warning} warn); signals explain quality without becoming completion authority.`;
 }
 
 function projectPendingDecision(pendingDecision: NonNullable<WorkflowState["pendingDecision"]>): NonNullable<WorkflowState["pendingDecision"]> {

test/run-contract.test.ts

@@ -35,9 +35,13 @@ test("projects existing workflow state into a generic RunContract view", () => {
   assert.equal(view.expectations.find((expectation) => expectation.id === "evidence:any")?.required, true);
   assert.equal(view.completion.results.find((result) => result.id === "required-evidence")?.status, "needs-evidence");
   assert.equal(view.quality.status, "blocked");
+  assert.deepEqual(view.quality.dimensions.map((dimension) => dimension.id), ["alignment", "evidence", "completeness", "simplicity", "risk"]);
+  assert.equal(view.quality.dimensions.find((dimension) => dimension.id === "evidence")?.status, "warn");
+  assert.equal(view.quality.dimensions.find((dimension) => dimension.id === "completeness")?.status, "warn");
+  assert.equal(view.quality.dimensions.find((dimension) => dimension.id === "risk")?.status, "warn");
   assert.equal(view.quality.hints.find((hint) => hint.id === "evidence-readiness")?.level, "attention");
   assert.equal(view.quality.hints.find((hint) => hint.id === "pending-decision")?.level, "blocked");
-  assert.match(view.quality.summary, /Advisory quality hints/);
+  assert.match(view.quality.summary, /Five advisory quality dimensions/);
 });
 
 test("projection stays derived from existing state and does not alias mutable arrays", () => {
@@ -94,7 +98,9 @@ test("projection exposes completion and advisory quality surfaces", () => {
   const completeView = projectRunContract({ ...completed, artifacts: [], evidence: [{ at: now, kind: "review" as const, summary: "accepted", verdict: "pass" as const }] }, getWorkflowDefinition(completed.workflowId));
   assert.equal(completeView.completion.status, "complete");
   assert.equal(completeView.quality.status, "ready");
-  assert.match(completeView.quality.hints[0]?.reason ?? "", /evidence expectations are satisfied/);
+  assert.equal(completeView.quality.dimensions.find((dimension) => dimension.id === "evidence")?.status, "pass");
+  assert.equal(completeView.quality.hints.find((hint) => hint.id === "evidence-readiness")?.level, "ok");
+  assert.match(completeView.quality.hints.find((hint) => hint.id === "evidence-readiness")?.reason ?? "", /evidence expectations are satisfied/);
   assert.equal(projectRunContract(blocked, getWorkflowDefinition(blocked.workflowId)).completion.summary, "waiting for approval");
   assert.equal(projectRunContract(blocked, getWorkflowDefinition(blocked.workflowId)).quality.status, "blocked");
 });
@@ -114,6 +120,33 @@ test("advisory quality hints surface stale evidence and risk without becoming co
 
   assert.equal(view.completion.status, "complete");
   assert.equal(view.quality.status, "attention");
+  assert.equal(view.quality.dimensions.find((dimension) => dimension.id === "risk")?.status, "warn");
+  assert.equal(view.quality.dimensions.find((dimension) => dimension.id === "simplicity")?.status, "warn");
   assert.equal(view.quality.hints.find((hint) => hint.id === "unresolved-risk")?.level, "attention");
-  assert.match(view.quality.hints.find((hint) => hint.id === "unresolved-risk")?.reason ?? "", /do not optimize this hint away/);
+  assert.match(view.quality.hints.find((hint) => hint.id === "unresolved-risk")?.reason ?? "", /address the underlying risk evidence/);
+});
+
+test("five advisory quality dimensions warn and fail without changing completion authority", () => {
+  const missingEvidence = {
+    ...createWorkflowState({ workspace: "/workspace/local-notes", workflowId: "kapi-deep-interview", task: "Summarize interview notes", now }),
+    pendingDecision: undefined,
+    artifacts: [],
+  };
+  const missingView = projectRunContract(missingEvidence, getWorkflowDefinition(missingEvidence.workflowId));
+  assert.equal(missingView.completion.status, "needs-evidence");
+  assert.equal(missingView.quality.dimensions.find((dimension) => dimension.id === "evidence")?.status, "warn");
+  assert.equal(missingView.quality.dimensions.find((dimension) => dimension.id === "completeness")?.status, "warn");
+
+  const blocked = {
+    ...missingEvidence,
+    status: "blocked" as const,
+    blocker: "local operator decision needed",
+    risks: ["scope is too broad for one pass"],
+    evidence: [{ at: now, kind: "manual" as const, summary: "operator noted blocker", verdict: "recorded" as const }],
+  };
+  const blockedView = projectRunContract(blocked, getWorkflowDefinition(blocked.workflowId));
+  assert.equal(blockedView.completion.status, "blocked");
+  assert.equal(blockedView.quality.dimensions.find((dimension) => dimension.id === "completeness")?.status, "fail");
+  assert.equal(blockedView.quality.dimensions.find((dimension) => dimension.id === "risk")?.status, "fail");
+  assert.equal(blockedView.quality.dimensions.find((dimension) => dimension.id === "simplicity")?.status, "warn");
 });