@brainervirus/workit-core 2.5.0 → 2.7.0

package/src/core/task-evaluation.ts

@@ -14,6 +14,8 @@ import {
   type Capability,
   type Caller,
   type Decision,
+  type Entry,
+  type Evidence,
   type EvidenceEvaluation,
   type Outcome,
   type Requirement,
@@ -24,6 +26,16 @@ import {
   type WorkspaceRecord,
 } from "./task-contract";
 import { verifyDecisionContentAtRoot } from "./authority";
+import {
+  CHECKS_FILE,
+  checkCommand,
+  gateCheckNames,
+  loadCheckConfig,
+  matchesNamedCheck,
+  type CheckConfig,
+} from "../check-config";
+import { worktreeSignal, worktreeTree } from "../git/rev";
+import { runtimeVersion } from "./task-store";
 
 export type CandidateEnvironment =
   | readonly (string | { name: string; value?: string | null })[]
@@ -318,9 +330,49 @@ const evidenceScopes = (task: TaskRecord, ids: string[]): Scope[] =>
     .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) => {
@@ -331,6 +383,28 @@ export function evaluateEvidence(
         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 {
@@ -499,6 +573,82 @@ const expectedKinds = (dimension: Requirement["dimension"], ruleId?: string): st
   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} (committed, so it shows in the diff), 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,
@@ -506,8 +656,12 @@ export function evaluateRequirements(
   candidate: Candidate | null,
   checkoutRoot: string,
   _caller?: Caller,
+  freshness: Freshness = treeFreshness(checkoutRoot),
 ) {
-  const evidence = evaluateEvidence(task, candidate);
+  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,
@@ -517,10 +671,23 @@ export function evaluateRequirements(
       reason: "stored policy version is unsupported; reassessment is required",
     }));
   return (task.policy?.requirements ?? []).map((requirement) => {
+    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,
@@ -659,6 +826,14 @@ export function evaluateRequirements(
         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,

package/src/core/uninstall.ts

@@ -10,12 +10,28 @@ import { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from "n
 import os from "node:os";
 import path from "node:path";
 import { isWorkitPlugin } from "./registration";
+import {
+  claudeWorkitInstalls,
+  findHostExecutable,
+  runHostCommand,
+  type HostCommandRunner,
+} from "./host-install";
 
-export type UninstallHost = "opencode" | "cursor" | "codex" | "pi";
+export type UninstallHost = "opencode" | "cursor" | "codex" | "pi" | "claude-code";
 
 export type UninstallAction =
   | { kind: "edit-json-remove"; path: string; detail: string }
-  | { kind: "remove-dir"; path: string; detail: string };
+  | { kind: "remove-dir"; path: string; detail: string }
+  /** A host-native uninstall (Claude Code owns its plugin cache and registry). */
+  | {
+      kind: "host-command";
+      path: string;
+      detail: string;
+      command: "claude";
+      args: string[];
+      /** The project a project/local-scope uninstall must run from; null for user scope. */
+      cwd: string | null;
+    };
 
 export type UninstallHostPlan = {
   host: UninstallHost;
@@ -49,6 +65,10 @@ export type UninstallPaths = {
   cursorSettings?: string;
   cursorMcp?: string;
   cursorPluginDir?: string;
+  /** Injectable host-command runner for host-native uninstall actions. */
+  runHostCommand?: HostCommandRunner;
+  /** Project directory for Claude Code project/local-scope installs (default: process cwd). */
+  cwd?: string;
 };
 
 type ResolvedUninstall = {
@@ -321,7 +341,32 @@ export function planUninstall(paths: UninstallPaths = {}): UninstallPlan {
       : [],
   };
 
-  return { hosts: [opencode, cursor, codex, pi] };
+  // Claude Code: one native `claude plugin uninstall <id> --scope <scope>`
+  // per recorded Workit install that applies here (user scope, plus this
+  // project's project/local scope, run from that project). A --plugin-dir
+  // pin is never recorded.
+  const home = paths.home ?? paths.env?.HOME ?? os.homedir();
+  const claudeInstalls = claudeWorkitInstalls(
+    home,
+    paths.env ?? process.env,
+    paths.cwd ?? process.cwd(),
+  );
+  const claude: UninstallHostPlan = {
+    host: "claude-code",
+    installed: claudeInstalls.length > 0,
+    actions: claudeInstalls.map((install) => ({
+      kind: "host-command" as const,
+      path: install.installPath,
+      detail: `claude plugin uninstall ${install.id} --scope ${install.scope}${
+        install.projectPath ? ` (in ${install.projectPath})` : ""
+      }`,
+      command: "claude" as const,
+      args: ["plugin", "uninstall", install.id, "--scope", install.scope],
+      cwd: install.projectPath,
+    })),
+  };
+
+  return { hosts: [opencode, cursor, codex, pi, claude] };
 }
 
 // CA-14 traversal guard: rm -rf is permitted ONLY on the exact resolved
@@ -390,6 +435,60 @@ const applyEditJsonRemove = (
   return { status: "removed" };
 };
 
+const CLAUDE_PLUGIN_ID = /^workit@[A-Za-z0-9._-]+$/;
+
+/** Runs a reviewed `claude plugin uninstall workit@<marketplace>`; any other
+ *  argv is refused, so a tampered plan cannot run an arbitrary command. */
+const applyClaudeUninstall = (
+  action: Extract<UninstallAction, { kind: "host-command" }>,
+  paths: UninstallPaths,
+): { status: UninstallResultStatus; detail?: string } => {
+  const [verb, sub, id, flag, scope, ...rest] = action.args;
+  const projectScoped = scope === "project" || scope === "local";
+  if (
+    action.command !== "claude" ||
+    verb !== "plugin" ||
+    sub !== "uninstall" ||
+    !CLAUDE_PLUGIN_ID.test(id ?? "") ||
+    flag !== "--scope" ||
+    !(scope === "user" || projectScoped) ||
+    rest.length > 0 ||
+    // user scope runs anywhere; project/local only from their project.
+    (projectScoped ? typeof action.cwd !== "string" : action.cwd !== null)
+  )
+    return {
+      status: "failed",
+      detail: `refusing unreviewed host command: ${action.args.join(" ")}`,
+    };
+  const home = paths.home ?? paths.env?.HOME ?? os.homedir();
+  const env = paths.env ?? process.env;
+  const recorded = claudeWorkitInstalls(home, env, action.cwd).some(
+    (install) =>
+      install.id === id &&
+      install.scope === scope &&
+      (install.projectPath === null
+        ? action.cwd === null
+        : path.resolve(install.projectPath) === path.resolve(action.cwd ?? "")),
+  );
+  if (!recorded)
+    return { status: "skipped", detail: `${id} (${scope} scope) is no longer installed` };
+  const executable = findHostExecutable("claude", { home, env });
+  if (!executable && !paths.runHostCommand)
+    return { status: "failed", detail: "claude executable was not found on PATH" };
+  const step = {
+    command: executable ?? "claude",
+    args: action.args,
+    ...(action.cwd === null ? {} : { cwd: action.cwd }),
+    purpose: `Uninstall the Workit Claude Code plugin ${id} (${scope} scope)`,
+  };
+  const result = paths.runHostCommand
+    ? paths.runHostCommand(step)
+    : runHostCommand(step, { home, env });
+  return result.exitCode === 0
+    ? { status: "removed", detail: action.detail }
+    : { status: "failed", detail: result.stderr || `exit ${result.exitCode}` };
+};
+
 /** Applies ONLY the reviewed plan actions with the given path options. Each
  *  planned action yields exactly one result entry; malformed host JSON fails
  *  its own action untouched while the remaining actions proceed (CA-13). */
@@ -400,7 +499,11 @@ export function applyUninstall(plan: UninstallPlan, paths: UninstallPaths = {}):
     for (const action of hostPlan.actions) {
       let status: UninstallResultStatus;
       let detail: string | undefined;
-      if (action.kind === "remove-dir") {
+      if (action.kind === "host-command") {
+        const outcome = applyClaudeUninstall(action, paths);
+        status = outcome.status;
+        detail = outcome.detail;
+      } else if (action.kind === "remove-dir") {
         // Resolve before comparing so ".."/symlink tricks can never widen the rm.
         const resolved = path.resolve(action.path);
         const allowed =

package/src/git/rev.ts

@@ -296,6 +296,56 @@ export function worktreeTree(
   }
 }
 
+/**
+ * A cheap worktree freshness signal for per-turn paths: sha256 over HEAD and,
+ * for every entry `git status` reports (untracked files listed one by one),
+ * its path, lstat mode, size and mtime. A directory entry (a submodule or an
+ * untracked nested repository) also contributes its own HEAD, so moving a
+ * submodule or committing in a nested repo changes the signal. Git answers
+ * from its stat cache and, with GIT_OPTIONAL_LOCKS=0, never refreshes the
+ * index, and nothing is written to the object store (unlike worktreeTree).
+ * Equal signals mean "probably unchanged": an edit to an already-dirty file
+ * that keeps its mode, size and mtime is not seen, so gates that decide
+ * (close, inspect) use worktreeTree. Null outside a repository.
+ */
+export function worktreeSignal(cwd: string, options: { timeoutMs?: number } = {}): string | null {
+  const top = line(git(cwd, ["rev-parse", "--show-toplevel"]));
+  if (!top) return null;
+  const status = git(
+    top,
+    [
+      "status",
+      "--porcelain=v1",
+      "-z",
+      "--untracked-files=all",
+      "--no-renames",
+      "--ignore-submodules=dirty",
+    ],
+    {
+      env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+      timeoutMs: options.timeoutMs ?? GIT_TIMEOUTS.worktree,
+    },
+  );
+  if (!status.ok) return null;
+  const hash = createHash("sha256");
+  hash.update(`${headSha(top) ?? "unborn"}\0`);
+  for (const entry of status.stdout.split("\0")) {
+    if (entry.length < 4) continue;
+    const file = entry.slice(3);
+    const absolute = path.join(top, file);
+    let stat = "-";
+    try {
+      const info = fs.lstatSync(absolute, { bigint: true });
+      stat = `${info.mode.toString(8)}:${info.size}:${info.mtimeNs}`;
+      if (info.isDirectory()) stat += `:${headSha(absolute) ?? "-"}`;
+    } catch {
+      // Deleted: the status code alone records it.
+    }
+    hash.update(`${entry.slice(0, 2)}\0${file}\0${stat}\0`);
+  }
+  return `sig:${hash.digest("hex")}`;
+}
+
 /** The best common ancestor of two revisions, or null. */
 export function mergeBase(cwd: string, a: string, b: string): string | null {
   if (!safeArg(a) || !safeArg(b)) return null;

package/src/hooks/context.ts

@@ -3,6 +3,8 @@
 import path from "node:path";
 import { invariantBootstrap } from "../core/methods";
 import { canonicalJson } from "../core/task-contract";
+import { isObservedCheck, type Freshness } from "../core/task-evaluation";
+import { worktreeSignal } from "../git/rev";
 import { WorkitCore, type OperationContext } from "../core/task-engine";
 import { fileSignature, racySignature, TaskStore, type TaskIndexEntry } from "../core/task-store";
 import { capabilitiesFor, type HostDescriptor } from "./descriptor";
@@ -80,8 +82,30 @@ const filesKey = (files: string[]): string | null => {
     : signatures.join("\0");
 };
 
-type CachedContext = { key: string; files: string[]; filesKey: string | null; value: string };
+type CachedContext = {
+  key: string;
+  files: string[];
+  filesKey: string | null;
+  /** The worktree signal the value was judged against; null when no observed check depends on it. */
+  signal: string | null;
+  value: string;
+};
 const CACHE_LIMIT = 64;
+
+/** How long a computed worktree signal is reused, so cache hits do not run `git status` each turn. */
+export const SIGNAL_TTL_MS = 1_500;
+const signals = new Map<string, { at: number; value: string | null }>();
+
+/** worktreeSignal for `root`, reused for SIGNAL_TTL_MS. */
+const recentSignal = (root: string): string | null => {
+  const now = Date.now();
+  const cached = signals.get(root);
+  if (cached && now - cached.at < SIGNAL_TTL_MS) return cached.value;
+  const value = worktreeSignal(root);
+  signals.set(root, { at: now, value });
+  if (signals.size > CACHE_LIMIT) signals.delete(signals.keys().next().value!);
+  return value;
+};
 const cache = new Map<string, CachedContext>();
 
 /**
@@ -123,20 +147,35 @@ function entryCompactContext(
     capabilities: context.capabilities,
   });
   const hit = cache.get(slot);
-  if (hit && hit.key === key && hit.filesKey !== null && hit.filesKey === filesKey(hit.files))
+  if (
+    hit &&
+    hit.key === key &&
+    hit.filesKey !== null &&
+    hit.filesKey === filesKey(hit.files) &&
+    // Observed-check freshness changes with the worktree, not the revision.
+    (hit.signal === null || hit.signal === recentSignal(store.root))
+  )
     return hit.value;
   const task = store.readTask(entry.id);
   if (!task.ok) return null;
+  const freshness: Freshness = { mode: "signal", current: () => recentSignal(store.root) };
+  const observed = task.data.evidence.some(isObservedCheck);
   const files = task.data.decisions.flatMap((decision) =>
     decision.data.binding.contentRefs.flatMap((ref) =>
       ref.kind === "file" ? [path.resolve(store.root, ref.path)] : [],
     ),
   );
-  const observed = filesKey(files);
-  const compact = new WorkitCore(store, context).compactContext(entry.id);
+  const observedFiles = filesKey(files);
+  const compact = new WorkitCore(store, context).compactContext(entry.id, freshness);
   if (!compact.ok) return null;
   cache.delete(slot);
-  cache.set(slot, { key, files, filesKey: observed, value: compact.data });
+  cache.set(slot, {
+    key,
+    files,
+    filesKey: observedFiles,
+    signal: observed ? freshness.current() : null,
+    value: compact.data,
+  });
   if (cache.size > CACHE_LIMIT) cache.delete(cache.keys().next().value!);
   return compact.data;
 }

package/src/hooks/handle.ts

@@ -12,6 +12,20 @@ const NONE: HookDecision = { kind: "none" };
 /** Sessions already offered unfinished tasks in this process. */
 const offered = new Set<string>();
 
+/** The Workit plugin's worktree-isolated implementer is the one Claude Code
+ * subagent that writes. Claude namespaces plugin agents, so only the exact
+ * `workit:implementer` is ours: a bare or other-plugin `implementer` is not. */
+const CLAUDE_WORKTREE_IMPLEMENTER = "workit:implementer";
+
+const subagentStartText = (
+  host: HookInput["host"],
+  descriptor: HostDescriptor,
+  event: Extract<HookInput["event"], { kind: "subagent.start" }>,
+): string =>
+  host === "claude_code" && event.agentType === CLAUDE_WORKTREE_IMPLEMENTER
+    ? `Workit observed ${descriptor.label} subagent ${event.agentId} (${event.agentType}) working in its own git worktree: it may edit and commit there, within its brief's scope. Before the first commit, switch to a policy-compliant branch (\`git switch -c <type>/<slug>\`, e.g. feature/<slug>); branch policy hooks still deny protected or non-compliant branches. Never push, open a PR, or merge unless the brief asks for it.`
+    : `Workit observed ${descriptor.label} subagent ${event.agentId} (${event.agentType}) as read-only/agent-guided; writer delegation is unavailable.`;
+
 export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
   const { descriptor } = deps;
   const event = input.event;
@@ -36,10 +50,7 @@ export function handleHook(input: HookInput, deps: HookDeps): HookDecision {
     case "shell.pre":
       return usable(descriptor.shellPolicy.deny) ? shellPolicy(input.cwd, event.command) : NONE;
     case "subagent.start":
-      return {
-        kind: "context",
-        text: `Workit observed ${descriptor.label} subagent ${event.agentId} (${event.agentType}) as read-only/agent-guided; writer delegation is unavailable.`,
-      };
+      return { kind: "context", text: subagentStartText(input.host, descriptor, event) };
     case "compact.pre":
       return {
         kind: "notice",