@workit-dev/core 0.0.1 → 1.0.0

package/src/core/task-evaluation.ts

@@ -0,0 +1,1147 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import {
+  POLICY_VERSION,
+  candidateDigest,
+  candidateSchema,
+  failure,
+  scopeCovers as contractScopeCovers,
+  success,
+  type Candidate,
+  type Capability,
+  type Caller,
+  type Decision,
+  type Entry,
+  type Evidence,
+  type EvidenceEvaluation,
+  type Outcome,
+  type Requirement,
+  type TaskBrief,
+  type TaskSummary,
+  type Result,
+  type Scope,
+  type TaskRecord,
+  type TaskView,
+  type WorkspaceRecord,
+} from "./task-contract";
+import {
+  CHECKS_FILE,
+  checkCommand,
+  gateCheckNames,
+  loadCheckConfig,
+  matchesNamedCheck,
+  type CheckConfig,
+} from "../check-config";
+import { worktreeSignal, worktreeTree } from "../git/rev";
+import { runtimeVersion } from "./task-store";
+import { derivedRuleStatus, ledgerView } from "./policy/derive";
+
+export type CandidateEnvironment =
+  | readonly (string | { name: string; value?: string | null })[]
+  | Record<string, string | null | undefined>;
+
+const digestBytes = (value: string | Buffer): string =>
+  createHash("sha256").update(value).digest("hex");
+const inside = (root: string, candidate: string): boolean =>
+  candidate === root || candidate.startsWith(`${root}${path.sep}`);
+const relative = (root: string, candidate: string): string =>
+  path.relative(root, candidate).split(path.sep).join("/") || ".";
+const canonicalPath = (value: string): string | null => {
+  if (typeof value !== "string" || !value) return null;
+  if (value.includes("\\") || value.split("/").includes("..")) return null;
+  const normalized = path.posix.normalize(value);
+  if (normalized === ".." || normalized.startsWith("../") || normalized.startsWith("/"))
+    return null;
+  return normalized === "." ? "." : normalized.replace(/\/$/, "");
+};
+const canonicalScope = (scope: Scope): Scope | null => {
+  const paths = scope.paths.length ? scope.paths : ["."];
+  const normalizedPaths = paths.map(canonicalPath);
+  const normalizedExclusions = scope.exclusions.map(canonicalPath);
+  if (
+    normalizedPaths.some((value) => value === null) ||
+    normalizedExclusions.some((value) => value === null)
+  )
+    return null;
+  return {
+    description: scope.description,
+    paths: [...new Set(normalizedPaths as string[])],
+    exclusions: [...new Set(normalizedExclusions as string[])],
+  };
+};
+const excluded = (value: string, exclusions: string[]): boolean =>
+  exclusions.some((item) => item === value || (item !== "." && value.startsWith(`${item}/`)));
+const scopeMatches = (value: string, scope: Scope): boolean => {
+  const normalized = canonicalScope(scope);
+  if (!normalized) return false;
+  const paths = normalized.paths;
+  return (
+    paths.some((item) => item === "." || value === item || value.startsWith(`${item}/`)) &&
+    !excluded(value, normalized.exclusions)
+  );
+};
+const pathRelevant = (value: string, scope: Scope): boolean => scopeMatches(value, scope);
+const compareCodeUnits = (left: string, right: string): number => {
+  const length = Math.min(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = left.charCodeAt(index) - right.charCodeAt(index);
+    if (difference !== 0) return difference;
+  }
+  return left.length - right.length;
+};
+
+type Inventory = { paths: string[]; uncertain: boolean; git: boolean };
+const gitPaths = (root: string): Inventory => {
+  const result = spawnSync(
+    "git",
+    ["ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+    {
+      cwd: root,
+      encoding: "buffer",
+    },
+  );
+  if (result.status !== 0) {
+    const stderr = result.stderr?.toString("utf8") ?? "";
+    return {
+      paths: [],
+      uncertain: !/not a git repository/i.test(stderr),
+      git: !/not a git repository/i.test(stderr),
+    };
+  }
+  const paths = result.stdout
+    ? result.stdout
+        .toString("utf8")
+        .split("\0")
+        .filter(Boolean)
+        .map((item) => item.split(path.sep).join("/"))
+    : [];
+  const stagedDeleted = spawnSync(
+    "git",
+    ["diff", "--cached", "--name-only", "--diff-filter=D", "-z"],
+    { cwd: root, encoding: "buffer" },
+  );
+  if (stagedDeleted.status !== 0) {
+    const stderr = stagedDeleted.stderr?.toString("utf8") ?? "";
+    if (!/not a git repository/i.test(stderr)) return { paths, uncertain: true, git: true };
+  } else if (stagedDeleted.stdout) {
+    paths.push(
+      ...stagedDeleted.stdout
+        .toString("utf8")
+        .split("\0")
+        .filter(Boolean)
+        .map((item) => item.split(path.sep).join("/")),
+    );
+  }
+  return { paths: [...new Set(paths)], uncertain: false, git: true };
+};
+
+const walk = (root: string, directory: string, output: Set<string>): boolean => {
+  let names: string[];
+  try {
+    names = fs.readdirSync(directory);
+  } catch {
+    return true;
+  }
+  let uncertain = false;
+  for (const name of names) {
+    if (name === ".git" || name === ".workit") continue;
+    const target = path.join(directory, name);
+    let stat: fs.Stats;
+    try {
+      stat = fs.lstatSync(target);
+    } catch {
+      uncertain = true;
+      continue;
+    }
+    const item = relative(root, target);
+    output.add(item);
+    if (stat.isDirectory() && !stat.isSymbolicLink())
+      uncertain = walk(root, target, output) || uncertain;
+  }
+  return uncertain;
+};
+
+const scopeRoots = (root: string, scope: Scope): Result<string[]> => {
+  const roots: string[] = [];
+  for (const item of scope.paths.length ? scope.paths : ["."]) {
+    const target = path.resolve(root, item);
+    if (!inside(root, target))
+      return failure(
+        "invalid_input",
+        `candidate scope escapes checkout: ${item} — keep one task per repository and coordinate a separate linked task in the other checkout`,
+        { fields: [{ path: "scope.paths", reason: `${item} is outside the checkout` }] },
+      );
+    let ancestor = target;
+    while (!fs.existsSync(ancestor) && ancestor !== root) ancestor = path.dirname(ancestor);
+    try {
+      if (!inside(root, fs.realpathSync(ancestor)))
+        return failure(
+          "invalid_input",
+          `candidate scope escapes checkout through a symlink: ${item} — keep one task per repository and coordinate a separate linked task in the other checkout`,
+          { fields: [{ path: "scope.paths", reason: `${item} resolves outside the checkout` }] },
+        );
+    } catch {
+      return failure("invalid_input", `candidate scope cannot be inspected: ${item}`);
+    }
+    roots.push(target);
+  }
+  return success(null, null, roots);
+};
+
+export function captureCandidate(
+  root: string,
+  scope: Scope,
+  environment: CandidateEnvironment = [],
+): Result<Candidate> {
+  let checkout: string;
+  try {
+    checkout = fs.realpathSync(root);
+  } catch {
+    return failure("invalid_input", "candidate root does not exist");
+  }
+  const normalizedScope = canonicalScope(scope);
+  if (!normalizedScope)
+    return failure(
+      "invalid_input",
+      "candidate scope is invalid: paths must be checkout-relative — to work in another repository, keep this task here and coordinate a separate linked task in that checkout",
+      { fields: [{ path: "scope.paths", reason: "must be checkout-relative" }] },
+    );
+  const roots = scopeRoots(checkout, normalizedScope);
+  if (!roots.ok) return roots;
+  const git = gitPaths(checkout);
+  const names = new Set<string>();
+  let uncertain = git.uncertain;
+  for (const target of roots.data) {
+    const item = relative(checkout, target);
+    if (item === ".git" || item === ".workit") continue;
+    names.add(item);
+    if (!fs.existsSync(target)) continue;
+    let stat: fs.Stats;
+    try {
+      stat = fs.lstatSync(target);
+    } catch {
+      uncertain = true;
+      continue;
+    }
+    if (!git.git && stat.isDirectory() && !stat.isSymbolicLink())
+      uncertain = walk(checkout, target, names) || uncertain;
+  }
+  for (const item of git.paths) if (scopeMatches(item, normalizedScope)) names.add(item);
+
+  const files: Candidate["files"] = [];
+  let completeness: Candidate["completeness"] = uncertain ? "uncertain" : "known";
+  for (const item of [...names].toSorted()) {
+    if (!scopeMatches(item, normalizedScope)) continue;
+    const target = path.join(checkout, item);
+    try {
+      const stat = fs.lstatSync(target);
+      if (stat.isSymbolicLink()) {
+        const link = fs.readlinkSync(target);
+        files.push({ path: item, kind: "symlink", digest: digestBytes(link), executable: null });
+      } else if (stat.isFile()) {
+        files.push({
+          path: item,
+          kind: "file",
+          digest: digestBytes(fs.readFileSync(target)),
+          executable: (stat.mode & 0o111) !== 0,
+        });
+      } else if (!stat.isDirectory()) {
+        completeness = "uncertain";
+      } else if (git.git && git.paths.includes(item)) {
+        // A Git link/submodule is an inventory boundary; its contents are not
+        // represented by the parent repository's path list.
+        completeness = "uncertain";
+      }
+    } catch (error: any) {
+      if (error?.code === "ENOENT") {
+        files.push({ path: item, kind: "absent", digest: null, executable: null });
+      } else completeness = "uncertain";
+    }
+  }
+  const supplied = Array.isArray(environment)
+    ? environment.map((value) =>
+        typeof value === "string"
+          ? { name: value, value: process.env[value] ?? null }
+          : { name: value.name, value: value.value ?? null },
+      )
+    : Object.keys(environment as Record<string, string | null | undefined>).map((name) => ({
+        name,
+        value: (environment as Record<string, string | null | undefined>)[name] ?? null,
+      }));
+  const namesByEnvironment = supplied.map(({ name }) => name);
+  if (
+    new Set(namesByEnvironment).size !== namesByEnvironment.length ||
+    namesByEnvironment.some((name) => typeof name !== "string" || !name)
+  )
+    return failure("invalid_input", "candidate environment names must be unique and non-empty");
+  const values = supplied
+    .toSorted((left, right) => compareCodeUnits(left.name, right.name))
+    .map(({ name, value }) => ({ name, value, refs: [] }));
+  if (values.some(({ value }) => value === null)) completeness = "uncertain";
+  const headResult = spawnSync("git", ["rev-parse", "HEAD"], { cwd: checkout, encoding: "utf8" });
+  if (headResult.status !== 0 && !/not a git repository/i.test(headResult.stderr ?? ""))
+    completeness = "uncertain";
+  const head = headResult.status === 0 ? headResult.stdout.trim() : null;
+  const partial: Candidate = {
+    id: "0".repeat(64),
+    scope: normalizedScope,
+    completeness,
+    files,
+    environment: values,
+    head,
+  };
+  const candidate = { ...partial, id: candidateDigest(partial) };
+  const parsed = candidateSchema.safeParse(candidate);
+  return parsed.success
+    ? success(null, null, parsed.data)
+    : failure("invalid_input", "captured candidate is invalid");
+}
+
+const fileMap = (candidate: Candidate): Map<string, Candidate["files"][number]> =>
+  new Map(candidate.files.map((file) => [file.path, file]));
+const changedPaths = (before: Candidate, after: Candidate): string[] => {
+  const paths = new Set([...before.files, ...after.files].map((file) => file.path));
+  const left = fileMap(before);
+  const right = fileMap(after);
+  const changed = [...paths].filter(
+    (item) => JSON.stringify(left.get(item) ?? null) !== JSON.stringify(right.get(item) ?? null),
+  );
+  if (before.head !== after.head) changed.push(".");
+  if (JSON.stringify(before.environment) !== JSON.stringify(after.environment)) changed.push(".");
+  return changed;
+};
+
+const sessionFromRef = (value: unknown): { host: string; handle: string } | null => {
+  if (typeof value !== "object" || value === null || (value as any).kind !== "host") return null;
+  return typeof (value as any).host === "string" && typeof (value as any).handle === "string"
+    ? { host: (value as any).host, handle: (value as any).handle }
+    : null;
+};
+const sameSession = (left: { host: string; handle: string } | null, right: unknown): boolean => {
+  const other = sessionFromRef(right);
+  return (
+    left !== null && other !== null && left.host === other.host && left.handle === other.handle
+  );
+};
+
+const evidenceScopes = (task: TaskRecord, ids: string[]): Scope[] =>
+  (task.policy?.requirements ?? [])
+    .filter((requirement) => ids.includes(requirement.id))
+    .map((requirement) => requirement.scope);
+
+/**
+ * How observed checks are judged fresh (§2.2). `tree`: the exact worktree tree
+ * key (worktreeTree hashes changed files into the object store, so it is only
+ * for paths that decide: close, inspect, evidence). `signal`: the cheap
+ * stat-cached worktreeSignal for per-turn context, which writes nothing.
+ * `current` is computed at most once and is null outside git.
+ */
+export type Freshness = { mode: "tree" | "signal"; current: () => string | null };
+
+const memo = (compute: () => string | null): (() => string | null) => {
+  let value: string | null | undefined;
+  return () => {
+    if (value === undefined) value = compute();
+    return value;
+  };
+};
+export const treeFreshness = (root: string): Freshness => ({
+  mode: "tree",
+  current: memo(() => worktreeTree(root)?.key ?? null),
+});
+export const signalFreshness = (root: string): Freshness => ({
+  mode: "signal",
+  current: memo(() => worktreeSignal(root)),
+});
+
+/** Evidence the workit CLI itself observed (`workit check`), as opposed to an agent's report. */
+export const isObservedCheck = (entry: Entry<Evidence>): boolean =>
+  entry.data.kind === "check" &&
+  entry.data.observation?.observer === "workit_cli" &&
+  entry.provenance?.kind === "host_observed" &&
+  entry.provenance.host === "workit_cli";
+
+/**
+ * Evidence status against the current state. Observed checks keyed to a tree
+ * are fresh while the worktree is unchanged (§2.2), judged by `freshness`
+ * (exact tree key, or the cheap signal on per-turn paths); a check that
+ * changed the worktree itself is stale (fail safe), and a closed task keeps
+ * the recorded status. Without `freshness` they read stale.
+ */
+export function evaluateEvidence(
+  task: TaskRecord,
+  candidate: Candidate | null,
+  freshness?: Freshness,
+): EvidenceEvaluation[] {
+  const current = candidate ?? task.candidates.at(-1) ?? null;
+  return task.evidence.map((entry) => {
+    const evidence = entry.data;
+    if (evidence.result === "failed")
+      return {
+        evidenceId: entry.id,
+        status: "failed" as const,
+        reason: "failed evidence remains historical",
+      };
+    const observation = isObservedCheck(entry) ? evidence.observation : undefined;
+    if (observation && observation.tree !== null) {
+      if (task.status === "closed")
+        return { evidenceId: entry.id, status: evidence.result, reason: "recorded before close" };
+      if (observation.modifiedWorktree)
+        return {
+          evidenceId: entry.id,
+          status: "stale" as const,
+          reason: "the check changed the worktree while it ran; ignore or clean its outputs",
+        };
+      const recorded = freshness?.mode === "signal" ? observation.signal : observation.tree;
+      if (recorded !== null && freshness && recorded === freshness.current())
+        return { evidenceId: entry.id, status: evidence.result, reason: "worktree is unchanged" };
+      return {
+        evidenceId: entry.id,
+        status: "stale" as const,
+        reason:
+          freshness?.mode === "signal"
+            ? "the worktree may have changed since the check ran (quick signal; inspect re-checks exactly)"
+            : "the worktree changed since the check ran",
+      };
+    }
+    if (evidence.kind === "check" || evidence.kind === "review") {
+      if (!evidence.beforeCandidateId || !evidence.candidateId)
+        return {
+          evidenceId: entry.id,
+          status: "stale",
+          reason: "check or review evidence lacks start and end candidates",
+        };
+      if (evidence.beforeCandidateId !== evidence.candidateId)
+        return {
+          evidenceId: entry.id,
+          status: "stale",
+          reason: "candidate changed during the check or review",
+        };
+    }
+    if (!evidence.candidateId || !current)
+      return {
+        evidenceId: entry.id,
+        status: evidence.result,
+        reason: "evidence has no candidate binding",
+      };
+    const observed =
+      task.candidates.find((item) => item.id === evidence.candidateId) ??
+      (current.id === evidence.candidateId ? current : undefined);
+    if (!observed || observed.completeness === "uncertain" || current.completeness === "uncertain")
+      return { evidenceId: entry.id, status: "stale", reason: "candidate is missing or uncertain" };
+    if (observed.id === current.id)
+      return { evidenceId: entry.id, status: evidence.result, reason: "candidate is unchanged" };
+    const scopes = evidenceScopes(task, evidence.requirementIds);
+    const changed = changedPaths(observed, current);
+    const environmentChanged =
+      JSON.stringify(observed.environment) !== JSON.stringify(current.environment);
+    if (
+      !scopes.length ||
+      environmentChanged ||
+      changed.some((item) => scopes.some((scope) => pathRelevant(item, scope)))
+    )
+      return { evidenceId: entry.id, status: "stale", reason: "relevant candidate state changed" };
+    return {
+      evidenceId: entry.id,
+      status: evidence.result,
+      reason: "candidate changed outside evidence scope",
+    };
+  });
+}
+
+export const scopeCovers = contractScopeCovers;
+
+/** One shared pin check for evidence and finding records: an unpinned
+ * assignment accepts anything in scope; a pinned one accepts the pin on
+ * either candidate slot. Absent IDs behave as null. */
+export const checkPin = (
+  assignment: { candidateId?: string | null },
+  beforeCandidateId: string | null | undefined,
+  candidateId: string | null | undefined,
+): boolean => {
+  const pin = assignment.candidateId ?? null;
+  if (pin === null) return true;
+  return (beforeCandidateId ?? null) === pin || (candidateId ?? null) === pin;
+};
+
+/** Resolve effective evidence binding: explicit IDs win; otherwise a pinned
+ * worker defaults to its pin and everyone else to the current candidate
+ * (checks and reviews) or null. Callers validate and pin-check the resolved
+ * values — never the caller's possibly-empty fields. */
+export const resolveBinding = (
+  evidence: {
+    beforeCandidateId?: string | null;
+    candidateId?: string | null;
+    kind: string;
+  },
+  pin: string | null | undefined,
+  currentCandidateId: string | null,
+): { beforeCandidateId: string | null; candidateId: string | null } => {
+  const bound = evidence.kind === "check" || evidence.kind === "review";
+  const fallback = bound ? (pin ?? currentCandidateId) : null;
+  return {
+    beforeCandidateId: evidence.beforeCandidateId ?? fallback,
+    candidateId: evidence.candidateId ?? fallback,
+  };
+};
+
+/** Evidence evaluation establishes freshness against the current tree;
+ * the finding's original candidate identifies where the defect was found. */
+export const findingVerificationPasses = (
+  findingCandidateId: string | null | undefined,
+  evidence: { kind: string; candidateId: string | null | undefined; status: string },
+): boolean =>
+  evidence.status === "passed" &&
+  (evidence.kind === "check" || evidence.kind === "review") &&
+  ((findingCandidateId ?? null) === null || evidence.candidateId != null);
+/** A decision about a document stays current only while its bytes are unchanged. */
+export const verifyDecisionContentAtRoot = (
+  checkoutRoot: string,
+  binding: Decision["binding"],
+): Result<null> => {
+  let root: string;
+  try {
+    root = fs.realpathSync(checkoutRoot);
+  } catch {
+    return failure("permission_denied", "checkout root is unavailable");
+  }
+  for (const reference of binding.contentRefs) {
+    if (reference.kind !== "file") continue;
+    if (!reference.digest)
+      return failure("invalid_input", "document references require a byte digest");
+    const target = path.resolve(root, reference.path);
+    if (target !== root && !target.startsWith(`${root}${path.sep}`))
+      return failure(
+        "invalid_input",
+        "document reference escapes checkout; cite it as an external file:// reference instead",
+        {
+          fields: [
+            { path: "contentRefs.path", reason: `${reference.path} is outside the checkout` },
+          ],
+        },
+      );
+    try {
+      const below = path.relative(root, target);
+      let current = root;
+      for (const segment of below.split(path.sep)) {
+        if (!segment) continue;
+        current = path.join(current, segment);
+        const stat = fs.lstatSync(current);
+        const real = fs.realpathSync(current);
+        if (real !== root && !real.startsWith(`${root}${path.sep}`))
+          return failure(
+            "invalid_input",
+            "document reference escapes checkout; cite it as an external file:// reference instead",
+            {
+              fields: [
+                {
+                  path: "contentRefs.path",
+                  reason: `${reference.path} resolves outside the checkout`,
+                },
+              ],
+            },
+          );
+        if (stat.isSymbolicLink())
+          return failure("invalid_input", "document reference uses a symlink");
+        if (current === target && !stat.isFile())
+          return failure("invalid_input", "document reference is not a regular file");
+        if (current !== target && !stat.isDirectory())
+          return failure("invalid_input", "document reference ancestor is not a directory");
+      }
+      if (digestBytes(fs.readFileSync(target)) !== reference.digest)
+        return failure("permission_denied", "decision document bytes have changed");
+    } catch {
+      return failure("invalid_input", "decision document is unavailable");
+    }
+  }
+  return success(null, null, null);
+};
+
+export const applicableDecision = (
+  task: TaskRecord,
+  workspace: WorkspaceRecord,
+  requirement: Requirement,
+  checkoutRoot?: string,
+): Decision[] =>
+  task.decisions
+    .filter((entry) => entry.provenance.kind !== "imported")
+    .map((entry) => entry.data)
+    .filter(
+      (decision) =>
+        decision.purpose === "limitation" &&
+        decision.response === "approved" &&
+        decision.revoked === null &&
+        decision.binding.taskId === task.id &&
+        decision.binding.workspaceId === workspace.id &&
+        decision.requirementIds.includes(requirement.id) &&
+        decision.binding.scope &&
+        scopeCovers(decision.binding.scope, requirement.scope) &&
+        (checkoutRoot
+          ? verifyDecisionContentAtRoot(checkoutRoot, decision.binding).ok
+          : decision.binding.contentRefs.every((reference) => reference.kind !== "file")),
+    );
+
+const applicableRequirementDecision = (
+  task: TaskRecord,
+  workspace: WorkspaceRecord,
+  requirement: Requirement,
+  checkoutRoot?: string,
+): { id: string }[] =>
+  task.decisions
+    .filter(
+      ({ data, provenance }) =>
+        provenance.kind !== "imported" &&
+        data.purpose !== "limitation" &&
+        (data.response === "approved" || data.response === "stated") &&
+        data.revoked === null &&
+        data.binding.taskId === task.id &&
+        data.binding.workspaceId === workspace.id &&
+        data.requirementIds.includes(requirement.id) &&
+        scopeCovers(data.binding.scope, requirement.scope) &&
+        (checkoutRoot
+          ? verifyDecisionContentAtRoot(checkoutRoot, data.binding).ok
+          : data.binding.contentRefs.every((reference) => reference.kind !== "file")),
+    )
+    .map(({ id }) => ({ id }));
+
+const evidenceMatchesRequirement = (
+  kind: EvidenceEvaluation["status"],
+  evidenceKind: string,
+  dimension: Requirement["dimension"],
+  ruleId?: string,
+): boolean => {
+  if (kind !== "passed") return false;
+  if (dimension === "testing" || dimension === "verification")
+    return evidenceKind === "check" || (ruleId === "pre-pr-cleanup" && evidenceKind === "artifact");
+  if (dimension === "review") return evidenceKind === "review";
+  if (dimension === "investigation" || dimension === "challenge")
+    return evidenceKind === "investigation";
+  if (dimension === "artifacts" || dimension === "continuity") return evidenceKind === "artifact";
+  return false;
+};
+
+/** Human-readable evidence kinds each requirement dimension accepts, used
+ * so kind mismatches fail with the expected kind instead of silence. */
+const expectedKinds = (dimension: Requirement["dimension"], ruleId?: string): string => {
+  if (dimension === "testing") return "check";
+  if (dimension === "verification")
+    return ruleId === "pre-pr-cleanup" ? "check or artifact" : "check";
+  if (dimension === "review") return "review";
+  if (dimension === "investigation" || dimension === "challenge") return "investigation";
+  if (dimension === "artifacts" || dimension === "continuity") return "artifact";
+  if (dimension === "decisions") return "decision";
+  return "worker report";
+};
+
+/** Close-time testing/verification gates accept only CLI-observed checks (D5, D14). */
+const observedGate = (requirement: Requirement): boolean =>
+  (requirement.dimension === "testing" || requirement.dimension === "verification") &&
+  requirement.before === "close";
+
+type GateResult = { satisfied: string[]; considered: string[]; reason: string };
+
+/**
+ * A close gate over CLI-observed checks. Only a fresh passing run of one of
+ * the gate's named checks whose argv is still its configured command
+ * satisfies it; ad-hoc runs never do, and with no named check for the gate
+ * the reason says how to configure one. Agent-reported checks are notes and
+ * never count. A broken check config fails closed.
+ */
+function evaluateObservedGate(
+  task: TaskRecord,
+  requirement: Requirement,
+  statuses: Map<string, EvidenceEvaluation["status"]>,
+  config: CheckConfig,
+): GateResult {
+  const names = gateCheckNames(config, requirement.dimension);
+  const observed = task.evidence.filter(isObservedCheck);
+  const fresh = observed.filter(
+    (entry) => statuses.get(entry.id) === "passed" && entry.data.observation?.exitCode === 0,
+  );
+  const named = (entry: Entry<Evidence>): boolean => {
+    const observation = entry.data.observation!;
+    return (
+      observation.configured &&
+      !observation.shell &&
+      names.includes(observation.name ?? "") &&
+      matchesNamedCheck(config, observation.name, observation.argv, observation.cwd)
+    );
+  };
+  const considered = observed.map((entry) => entry.id);
+  const run = checkCommand(names[0] ?? "<name>", runtimeVersion());
+  if (config.error)
+    return {
+      satisfied: [],
+      considered,
+      reason: `check config is invalid (${config.error}); fix it, then run ${run}`,
+    };
+  if (!names.length)
+    return {
+      satisfied: [],
+      considered,
+      reason:
+        requirement.dimension === "testing" && config.checks.length
+          ? `no \`test\` check is configured; add one (or gates.testing) to ${CHECKS_FILE}, then run ${checkCommand("test", runtimeVersion())}`
+          : `no checks are configured or detected; add ${CHECKS_FILE}, e.g. {"checks":{"test":"<your test command>"}}, then run ${checkCommand("test", runtimeVersion())}`,
+    };
+  const satisfied = fresh.filter(named);
+  if (satisfied.length)
+    return {
+      satisfied: satisfied.map((entry) => entry.id),
+      considered,
+      reason: `a fresh passing configured check (${names.join("|")}) was observed by workit check`,
+    };
+  const reported = task.evidence.some(
+    (entry) =>
+      entry.data.kind === "check" &&
+      !isObservedCheck(entry) &&
+      entry.data.requirementIds.includes(requirement.id),
+  );
+  const reason = fresh.length
+    ? `ad-hoc checks do not satisfy a configured gate; run ${run}`
+    : observed.some((entry) => statuses.get(entry.id) === "stale")
+      ? `observed checks are stale (the worktree changed); run ${run}`
+      : observed.some((entry) => statuses.get(entry.id) === "failed")
+        ? `the observed check failed; fix it and run ${run}`
+        : reported
+          ? `agent-reported checks are notes, not evidence; run ${run}`
+          : `no CLI-observed check (needs kind:check observed by workit check); run ${run}`;
+  return { satisfied: [], considered, reason };
+}
+
+export function evaluateRequirements(
+  task: TaskRecord,
+  workspace: WorkspaceRecord,
+  capabilities: Capability[],
+  candidate: Candidate | null,
+  checkoutRoot: string,
+  _caller?: Caller,
+  freshness: Freshness = treeFreshness(checkoutRoot),
+) {
+  const evidence = evaluateEvidence(task, candidate, freshness);
+  const statuses = new Map(evidence.map((item) => [item.evidenceId, item.status]));
+  let checkConfig: CheckConfig | undefined;
+  const configFor = (): CheckConfig => (checkConfig ??= loadCheckConfig(checkoutRoot));
+  if (task.policy && task.policy.policyVersion !== POLICY_VERSION)
+    return task.policy.requirements.map((requirement) => ({
+      requirementId: requirement.id,
+      status: "unsatisfied" as const,
+      evidenceIds: [],
+      decisionIds: [],
+      reason: "stored policy version is unsupported; reassessment is required",
+    }));
+  const ledger = ledgerView(checkoutRoot);
+  return (task.policy?.requirements ?? []).map((requirement) => {
+    // Verdict, product-decision and plan rules read the ledger or the plan (S17).
+    const derived = derivedRuleStatus(task, requirement, checkoutRoot, ledger);
+    if (derived) {
+      if (derived.met)
+        return {
+          requirementId: requirement.id,
+          status: "satisfied" as const,
+          evidenceIds: [],
+          decisionIds: derived.decisionIds,
+          reason: derived.reason,
+        };
+      const waived = requirement.acceptanceAllowed
+        ? applicableDecision(task, workspace, requirement, checkoutRoot)
+        : [];
+      if (waived.length)
+        return {
+          requirementId: requirement.id,
+          status: "accepted_limitation" as const,
+          evidenceIds: [],
+          decisionIds: waived.map(
+            (decision) => task.decisions.find((entry) => entry.data === decision)!.id,
+          ),
+          reason: "an applicable approved limitation permits the missing evidence",
+        };
+      return {
+        requirementId: requirement.id,
+        status: "unsatisfied" as const,
+        evidenceIds: [],
+        decisionIds: [],
+        reason: derived.reason,
+      };
+    }
+    const gate = observedGate(requirement)
+      ? evaluateObservedGate(task, requirement, statuses, configFor())
+      : null;
+    if (gate?.satisfied.length)
+      return {
+        requirementId: requirement.id,
+        status: "satisfied" as const,
+        evidenceIds: gate.satisfied,
+        decisionIds: [],
+        reason: gate.reason,
+      };
+    const related = task.evidence
+      .map((entry, index) => ({ entry, evaluation: evidence[index] }))
+      .filter(({ entry }) => entry.data.requirementIds.includes(requirement.id));
+    const passed = related.filter(({ entry, evaluation }) => {
+      // A gated requirement was decided above: reported checks are only notes.
+      if (gate) return false;
+      if (
+        !evidenceMatchesRequirement(
+          evaluation.status,
+          entry.data.kind,
+          requirement.dimension,
+          requirement.ruleId,
+        )
+      )
+        return false;
+      if (
+        (entry.data.kind === "check" || entry.data.kind === "review") &&
+        (!entry.data.beforeCandidateId ||
+          !entry.data.candidateId ||
+          entry.data.beforeCandidateId !== entry.data.candidateId)
+      )
+        return false;
+      if (requirement.dimension !== "review") return true;
+      const reviewSession = sessionFromRef(entry.data.reviewContext);
+      const sameImplementation = sameSession(reviewSession, task.intent.provenance.session);
+      // Reviewer-session uniqueness is per candidate, not per task: the
+      // same session may re-verify after the candidate changes, but never
+      // manufacture two reviews for one candidate.
+      const sameEvidenceSession = related.some(
+        ({ entry: other }) =>
+          other.id !== entry.id &&
+          other.data.kind === "review" &&
+          other.data.candidateId !== null &&
+          other.data.candidateId === entry.data.candidateId &&
+          sameSession(reviewSession, other.provenance.session),
+      );
+      return (
+        entry.data.kind === "review" &&
+        reviewSession !== null &&
+        sameSession(reviewSession, entry.provenance.session) &&
+        (requirement.ruleId === "self-review" || (!sameImplementation && !sameEvidenceSession))
+      );
+    });
+    if (passed.length) {
+      // RED-first, scoped to fresh claims: a testing pass bound to the
+      // current candidate needs a preceding recorded failure, unless a
+      // passing baseline already exists from earlier work — a check that
+      // passed (when recorded) against a different candidate. Stale passes
+      // count as baselines: green on an older tree is exactly what "prior
+      // passing baseline" means. A GREEN with neither is indistinguishable
+      // from code-then-tests.
+      const currentId = candidate?.id ?? null;
+      const withRed =
+        requirement.dimension === "testing"
+          ? passed.filter(
+              ({ entry }) =>
+                related.some(
+                  (other) =>
+                    other.entry.data.kind === "check" &&
+                    other.evaluation.status === "failed" &&
+                    other.entry.data.requirementIds.includes(requirement.id) &&
+                    other.entry.recordedAt <= entry.recordedAt,
+                ) ||
+                related.some(
+                  (baseline) =>
+                    baseline.entry.id !== entry.id &&
+                    baseline.entry.data.kind === "check" &&
+                    baseline.entry.data.result === "passed" &&
+                    baseline.entry.data.candidateId !== null &&
+                    currentId !== null &&
+                    baseline.entry.data.candidateId !== currentId,
+                ),
+            )
+          : passed;
+      if (withRed.length)
+        return {
+          requirementId: requirement.id,
+          status: "satisfied" as const,
+          evidenceIds: withRed.map(({ entry }) => entry.id),
+          decisionIds: [],
+          reason: "fresh applicable evidence passed",
+        };
+      if (requirement.dimension === "testing")
+        return {
+          requirementId: requirement.id,
+          status: "unsatisfied" as const,
+          evidenceIds: [],
+          decisionIds: [],
+          reason: "testing requirement has GREEN evidence but no preceding RED",
+        };
+    }
+    if (requirement.dimension === "delegation") {
+      // A bounded helper used for the requirement whose completed report is
+      // recorded reconciles the delegation: the lead closes on that result.
+      // Empty scope paths mean the whole checkout on both sides. Explicit
+      // requirement linkage wins for narrow requirements; scope coverage is
+      // the usual path since assignments live inside the requirement scope.
+      const dot = (scope: Scope): Scope =>
+        scope.paths.length > 0 ? scope : { ...scope, paths: ["."] };
+      const reconciled = task.workers.some(
+        (worker) =>
+          worker.data.report?.outcome === "completed" &&
+          (worker.data.assignment.requirementIds.includes(requirement.id) ||
+            scopeCovers(dot(requirement.scope), dot(worker.data.assignment.scope))),
+      );
+      if (reconciled)
+        return {
+          requirementId: requirement.id,
+          status: "satisfied" as const,
+          evidenceIds: [],
+          decisionIds: [],
+          reason: "bounded helper completed and its result is recorded",
+        };
+    }
+    const decisions =
+      requirement.dimension === "decisions"
+        ? applicableRequirementDecision(task, workspace, requirement, checkoutRoot)
+        : [];
+    if (decisions.length)
+      return {
+        requirementId: requirement.id,
+        status: "satisfied" as const,
+        evidenceIds: [],
+        decisionIds: decisions.map((decision) => decision.id),
+        reason: "an applicable approved or stated decision satisfies the requirement",
+      };
+    const limitations = requirement.acceptanceAllowed
+      ? applicableDecision(task, workspace, requirement, checkoutRoot)
+      : [];
+    if (limitations.length)
+      return {
+        requirementId: requirement.id,
+        status: "accepted_limitation" as const,
+        evidenceIds: [],
+        decisionIds: limitations.map(
+          (decision) => task.decisions.find((entry) => entry.data === decision)!.id,
+        ),
+        reason: "an applicable approved limitation permits the missing evidence",
+      };
+    const unavailable = capabilities.some(
+      (capability) =>
+        capability.assurance === "unavailable" &&
+        (capability.name === requirement.dimension || capability.surface === requirement.dimension),
+    );
+    if (gate)
+      return {
+        requirementId: requirement.id,
+        status: unavailable ? ("unavailable" as const) : ("unsatisfied" as const),
+        evidenceIds: [...new Set([...gate.considered, ...related.map(({ entry }) => entry.id)])],
+        decisionIds: [],
+        reason: unavailable ? "required capability is unavailable" : gate.reason,
+      };
+    if (!unavailable && related.length > 0 && !passed.length)
+      return {
+        requirementId: requirement.id,
+        status: "unsatisfied" as const,
+        evidenceIds: related.map(({ entry }) => entry.id),
+        decisionIds: [],
+        reason: `no passing evidence (needs kind:${expectedKinds(requirement.dimension, requirement.ruleId)})`,
+      };
+    return {
+      requirementId: requirement.id,
+      status: unavailable ? ("unavailable" as const) : ("unsatisfied" as const),
+      evidenceIds: related.map(({ entry }) => entry.id),
+      decisionIds: [],
+      reason: unavailable ? "required capability is unavailable" : "no fresh passing evidence",
+    };
+  });
+}
+
+export type ClosureEvaluation = {
+  outcome: Outcome;
+  evidenceIds: string[];
+  decisionIds: string[];
+  requirementIds: string[];
+};
+
+export function evaluateClosure(
+  requestedOutcome: Outcome,
+  view: TaskView,
+): Result<ClosureEvaluation> {
+  if (requestedOutcome !== "stopped" && !view.task.policy)
+    return failure("requirements_unsatisfied", "task has not been assessed");
+  if (
+    view.task.policy &&
+    (view.task.policy as { policyVersion: string }).policyVersion !== POLICY_VERSION
+  )
+    return failure(
+      "requirements_unsatisfied",
+      "stored policy version is unsupported; reassessment is required",
+    );
+  const evaluations = view.requirements;
+  const openFindings = view.task.findings.filter((entry) => entry.data.disposition === "open");
+  if (requestedOutcome !== "stopped" && openFindings.length)
+    return failure("requirements_unsatisfied", "open findings must be resolved before closure");
+  if (requestedOutcome !== "stopped") {
+    const evidenceById = new Map(view.evidence.map((entry) => [entry.evidenceId, entry.status]));
+    for (const entry of view.task.findings) {
+      if (entry.data.disposition === "fixed") {
+        const verified = entry.data.resolution?.evidenceIds.some((id) => {
+          const evidence = view.task.evidence.find((item) => item.id === id);
+          if (!evidence) return false;
+          return findingVerificationPasses(entry.data.candidateId, {
+            kind: evidence.data.kind,
+            candidateId: evidence.data.candidateId,
+            status: evidenceById.get(id) ?? "missing",
+          });
+        });
+        if (!verified)
+          return failure("requirements_unsatisfied", "fixed findings require current verification");
+      }
+      if (entry.data.disposition === "deferred") {
+        const valid = entry.data.resolution?.decisionIds.some((id) => {
+          const decisionEntry = view.task.decisions.find((item) => item.id === id);
+          const decision = decisionEntry?.data;
+          return Boolean(
+            decision &&
+            decisionEntry?.provenance.kind !== "imported" &&
+            decision.purpose === "limitation" &&
+            decision.response === "approved" &&
+            decision.revoked === null &&
+            verifyDecisionContentAtRoot(view.workspace.root, decision.binding).ok &&
+            decision.binding.taskId === view.task.id &&
+            decision.binding.workspaceId === view.workspace.id &&
+            scopeCovers(decision.binding.scope, entry.data.scope) &&
+            decision.requirementIds.some((requirementId) =>
+              view.task.policy?.requirements.some(
+                (requirement) => requirement.id === requirementId && requirement.acceptanceAllowed,
+              ),
+            ),
+          );
+        });
+        if (!valid)
+          return failure(
+            "requirements_unsatisfied",
+            "deferred findings require an approved limitation decision that references an acceptanceAllowed requirement and covers the finding scope",
+          );
+      }
+    }
+  }
+  // Close is gated only by close-timed requirements. Dependent-action gates
+  // (e.g. deslop before hosting.pull_request) block their named action at
+  // reservation time, never the close itself.
+  const blocking = evaluations.filter((item) => {
+    if (item.status !== "unsatisfied" && item.status !== "unavailable") return false;
+    const requirement = view.task.policy?.requirements.find(
+      (candidate) => candidate.id === item.requirementId,
+    );
+    return !requirement || requirement.before === "close";
+  });
+  if (requestedOutcome !== "stopped" && blocking.length)
+    return failure("requirements_unsatisfied", "applicable requirements are unsatisfied", {
+      requirementIds: blocking.map((item) => item.requirementId),
+      requirements: blocking.map((item) => {
+        const requirement = view.task.policy?.requirements.find(
+          (candidate) => candidate.id === item.requirementId,
+        );
+        return {
+          requirementId: item.requirementId,
+          ruleId: requirement?.ruleId ?? "unknown",
+          reason: item.reason,
+          satisfaction: requirement?.satisfaction ?? "",
+          dependentAction: requirement?.dependentAction ?? null,
+        };
+      }),
+    });
+  const accepted = evaluations.filter((item) => item.status === "accepted_limitation");
+  if (requestedOutcome === "verified" && accepted.length)
+    return failure(
+      "requirements_unsatisfied",
+      "accepted limitations cannot be reported as verified",
+      {
+        requirementIds: accepted.map((item) => item.requirementId),
+      },
+    );
+  const evidenceIds = [
+    ...new Set([
+      ...evaluations.flatMap((item) => item.evidenceIds),
+      ...view.task.findings.flatMap((item) => item.data.resolution?.evidenceIds ?? []),
+    ]),
+  ];
+  const decisionIds = [
+    ...new Set([
+      ...evaluations.flatMap((item) => item.decisionIds),
+      ...view.task.findings.flatMap((item) => item.data.resolution?.decisionIds ?? []),
+    ]),
+  ];
+  return success(null, null, {
+    outcome:
+      requestedOutcome === "stopped"
+        ? "stopped"
+        : accepted.length
+          ? "accepted_limitations"
+          : "verified",
+    evidenceIds,
+    decisionIds,
+    requirementIds: evaluations.map((item) => item.requirementId),
+  });
+}
+
+export const TASK_BRIEF_MAX_BYTES = 4096;
+const BRIEF_TEXT = 250;
+const BRIEF_BLOCKERS = 3;
+const BRIEF_OPEN = 8;
+
+/** Cut `value` until its JSON-escaped form fits `BRIEF_TEXT` bytes. */
+const clip = (value: string): string => {
+  const fits = (text: string) => Buffer.byteLength(JSON.stringify(text)) <= BRIEF_TEXT;
+  if (fits(value)) return value;
+  let length = Math.min(value.length, BRIEF_TEXT);
+  while (length > 0 && !fits(`${value.slice(0, length)}…`)) length -= 1;
+  return `${value.slice(0, length)}…`;
+};
+
+/**
+ * Bound a task summary for `inspect --view summary`: text is clipped, lists
+ * capped and the policy reduced to the requirements still owed, so the JSON
+ * stays under {@link TASK_BRIEF_MAX_BYTES} however long the task history is.
+ */
+export function boundTaskSummary(summary: TaskSummary): TaskBrief {
+  const rules = new Map((summary.policy?.requirements ?? []).map((item) => [item.id, item]));
+  const unmet = summary.requirements.filter(
+    (item) => item.status === "unsatisfied" || item.status === "unavailable",
+  );
+  const { progress, closure } = summary;
+  const next = progress.nextAction;
+  const open = unmet.slice(0, BRIEF_OPEN).map((item) => ({
+    dimension: rules.get(item.requirementId)?.dimension ?? "verification",
+    before: rules.get(item.requirementId)?.before ?? "close",
+    status: item.status,
+  }));
+  const brief: TaskBrief = {
+    id: summary.id,
+    revision: summary.revision,
+    workspaceRevision: summary.workspaceRevision,
+    updatedAt: summary.updatedAt,
+    objective: clip(summary.objective),
+    status: summary.status,
+    closure: closure && {
+      outcome: closure.outcome,
+      at: closure.at,
+      summary: clip(closure.summary),
+    },
+    progress: {
+      summary: clip(progress.summary),
+      nextAction: next && clip(next),
+      blockers: progress.blockers.slice(0, BRIEF_BLOCKERS).map((item) => ({
+        reason: clip(item.reason),
+        dependentAction: clip(item.dependentAction),
+      })),
+    },
+    requirements: { total: summary.requirements.length, unmet: unmet.length, open },
+    truncated: false,
+  };
+  brief.truncated =
+    JSON.stringify(brief).includes("…") ||
+    progress.blockers.length > BRIEF_BLOCKERS ||
+    unmet.length > BRIEF_OPEN;
+  return brief;
+}
+
+/** For a child or unattested caller: `task inspect` with the summary view returns the brief. */
+export function briefInspectResult(request: unknown, result: Result<unknown>): Result<unknown> {
+  const { action, view } = (request ?? {}) as { action?: unknown; view?: unknown };
+  return result.ok && action === "inspect" && (view ?? "summary") === "summary"
+    ? { ...result, data: boundTaskSummary(result.data as TaskSummary) }
+    : result;
+}