@brainervirus/workit-core 1.0.11 → 1.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/src/core/authority.ts

@@ -181,12 +181,57 @@ export type ReconcileActionInput = {
 
 type Workflow = { steps: string[]; completed: string[] };
 
+/** One typed step of a chain reservation. Plain strings are commit
+ * messages (the historical plan_steps shape); branch and pr steps carry
+ * their match key. Keys are the canonical consumption alphabet. */
+export type ChainStep =
+  | { kind: "commit"; message: string }
+  | { kind: "branch"; target: string }
+  | { kind: "pr" };
+
+export const chainStepKey = (step: ChainStep): string =>
+  step.kind === "commit" ? step.message : step.kind === "branch" ? `branch:${step.target}` : "pr";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Normalize mixed plan steps to typed entries. Returns null for empty,
+ * over-long, malformed, or key-colliding lists (a commit message that
+ * spells exactly like a typed key is rejected rather than misrouted). */
+export const normalizeChainSteps = (steps: unknown): ChainStep[] | null => {
+  if (!Array.isArray(steps) || steps.length === 0 || steps.length > 32) return null;
+  const normalized: ChainStep[] = [];
+  for (const step of steps) {
+    if (typeof step === "string") {
+      if (!step.trim()) return null;
+      normalized.push({ kind: "commit", message: step });
+      continue;
+    }
+    if (!isRecord(step)) return null;
+    if (typeof step.branch === "string" && step.branch.trim() && Object.keys(step).length === 1) {
+      normalized.push({ kind: "branch", target: step.branch });
+      continue;
+    }
+    if (step.pr === true && Object.keys(step).length === 1) {
+      normalized.push({ kind: "pr" });
+      continue;
+    }
+    return null;
+  }
+  const keys = normalized.map(chainStepKey);
+  if (new Set(keys).size !== keys.length) return null;
+  return normalized;
+};
+
 const scopeEqual = (
   left: Decision["binding"]["scope"],
   right: Decision["binding"]["scope"],
 ): boolean => canonicalJson(left) === canonicalJson(right);
 
-const parseSteps = (content: string): string[] | null => {
+/** Parse the durable approved text into typed chain steps. Single commits
+ * and branch/PR operations carry no step list (empty, not an invalid
+ * chain); an invalid list is null and rejected by callers. */
+const parseSteps = (content: string): ChainStep[] | null => {
   let value: unknown;
   try {
     value = JSON.parse(content) as unknown;
@@ -195,7 +240,9 @@ const parseSteps = (content: string): string[] | null => {
   }
   if (typeof value !== "object" || value === null || !("steps" in value)) return [];
   const steps = (value as { steps?: unknown }).steps;
-  return Array.isArray(steps) && steps.every((step) => typeof step === "string") ? steps : null;
+  if (!Array.isArray(steps)) return null;
+  const normalized = normalizeChainSteps(steps);
+  return normalized;
 };
 
 const decisionMatches = (
@@ -543,22 +590,17 @@ const validateAction = (
   if (!content.ok) return content as Result<never>;
   const requestedSteps = parseSteps(decision.binding.approvedContent);
   if (requestedSteps === null)
-    return failure("invalid_input", "bounded action steps must be a string array");
-  if (input.steps && canonicalJson(input.steps) !== canonicalJson(requestedSteps))
+    return failure("invalid_input", "bounded action steps must be a unique non-empty array");
+  if (input.steps && canonicalJson(input.steps) !== canonicalJson(requestedSteps.map(chainStepKey)))
     return failure("permission_denied", "bounded action steps do not match approved content");
-  if (
-    requestedSteps.some((step) => !step || typeof step !== "string") ||
-    new Set(requestedSteps).size !== requestedSteps.length
-  )
-    return failure("invalid_input", "bounded action steps must be unique and non-empty");
   const stored = task.actionProgress?.find((item) => item.decisionId === input.decisionId);
   const workflow = stored
     ? { steps: stored.steps, completed: stored.completedSteps }
-    : { steps: requestedSteps, completed: [] };
+    : { steps: requestedSteps.map(chainStepKey), completed: [] };
   if (
     workflow.steps.length &&
     requestedSteps.length &&
-    canonicalJson(workflow.steps) !== canonicalJson(requestedSteps)
+    canonicalJson(workflow.steps) !== canonicalJson(requestedSteps.map(chainStepKey))
   )
     return failure("permission_denied", "bounded action scope changed");
   return success(null, null, { entry, workflow });

package/src/core/branch.ts

@@ -281,6 +281,43 @@ export type BranchSetupResult =
   | { error: string; phase: "preflight" | "post_mutation" };
 
 // Port of scripts/branch/setup-branch.sh
+export type BranchDirt = "clean" | "carry" | "stash-required";
+
+/**
+ * Classify working-tree dirt for branch setup. Untracked files ride along
+ * (`git switch -c` never touches them), and tracked modifications confined
+ * to `docs/` are branch-owned by construction in this workflow — both
+ * auto-carry with no stash question. Anything else keeps the stash-bound
+ * proposal, since the base-checkout sequence could disturb it. Any
+ * inspection failure reads as clean so a broken git surfaces at its own
+ * error instead of inventing a stash demand.
+ */
+export const classifyBranchDirt = (workspaceRoot: string): BranchDirt => {
+  let raw: string;
+  try {
+    raw = execFileSync("git", ["status", "--porcelain=v1"], {
+      cwd: path.resolve(workspaceRoot),
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch {
+    return "clean";
+  }
+  let dirty = false;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    dirty = true;
+    const code = line.slice(0, 2);
+    if (code === "??") continue;
+    let entry = line.slice(3);
+    const arrow = entry.indexOf(" -> ");
+    if (arrow >= 0) entry = entry.slice(arrow + 4);
+    const unquoted = entry.startsWith('"') && entry.endsWith('"') ? entry.slice(1, -1) : entry;
+    if (unquoted !== "docs" && !unquoted.startsWith("docs/")) return "stash-required";
+  }
+  return dirty ? "carry" : "clean";
+};
+
 export const branchSetup = ({
   action,
   sdd_dir,
@@ -398,7 +435,7 @@ export const branchSetup = ({
   };
   if (current !== target) {
     const dirty = Boolean(gitContext(cwd).status_short.trim());
-    if (dirty && stash !== "yes") {
+    if (classifyBranchDirt(cwd) === "stash-required" && stash !== "yes") {
       return {
         error:
           "dirty working tree — ask with native question, then call workit_branch_setup with stash=yes",
@@ -416,7 +453,7 @@ export const branchSetup = ({
         return { error: ready.error ?? "ensure-base-branch failed", phase: "preflight" };
       validatedBase = base;
     }
-    if (dirty) {
+    if (dirty && stash === "yes") {
       try {
         exec(["stash", "push", "-u", "-m", `workit: pre-checkout ${target}`]);
       } catch (error) {

package/src/core/doctor.ts

@@ -22,6 +22,7 @@ import {
 import os from "node:os";
 import path from "node:path";
 import { SUPPORT_MATRIX } from "./support-matrix";
+import { bundleHashOfFile, isEphemeralCachePath } from "./runtime-identity";
 import { EVENT } from "./boundary";
 import { getDiagnosticLogger, isConfigObject } from "./config";
 import { packageRoot } from "./package-root";
@@ -682,12 +683,7 @@ const checkUtility = (res: Resolved): DoctorCheck => {
 const isFragileCachePin = (entry: string): boolean => {
   const n = entry.replaceAll("\\", "/").toLowerCase();
   if (!n.startsWith("file:")) return false;
-  return (
-    n.includes("/caches/pnpm/dlx/") ||
-    n.includes("/_npx/") ||
-    n.includes("/.pacquet/") ||
-    n.includes("/library/caches/pnpm/")
-  );
+  return isEphemeralCachePath(entry);
 };
 
 const staleEntry = (entry: string): "ok" | "stale" | "missing-file" | "fragile-cache" => {
@@ -936,12 +932,7 @@ const checkStaleInstall = (res: Resolved): DoctorCheck & { registryProbed?: bool
     } catch {
       target = "(unreadable)";
     }
-    const n = target.replaceAll("\\", "/").toLowerCase();
-    const fragile =
-      n.includes("/caches/pnpm/dlx/") ||
-      n.includes("/_npx/") ||
-      n.includes("/.pacquet/") ||
-      n.includes("/library/caches/pnpm/");
+    const fragile = isEphemeralCachePath(target);
     return {
       id: "stale_install",
       status: "fail",
@@ -1013,6 +1004,28 @@ const checkStaleInstall = (res: Resolved): DoctorCheck & { registryProbed?: bool
       fix: "Re-run install-cursor-plugin.sh — it refreshes the plugin directory and rewrites the workit MCP/hook entries",
     };
   }
+  // Same version, different bytes: the install was hand-edited or built from
+  // a dirty tree. Version strings cannot see that; the bundle hash can. The
+  // dev dist is byte-deterministic, so a mismatch heals with reinstall.
+  if (localDist && installed !== null && source !== null && res.dev) {
+    const entry = /^node\s+(.+)$/.exec((hookCmd ?? "").trim())?.[1]?.trim() ?? "";
+    const sourceBundle =
+      entry && path.isAbsolute(entry)
+        ? path.join(res.dev, "packages", "workit-cursor", "dist", path.basename(entry))
+        : "";
+    if (entry && sourceBundle) {
+      const installedHash = bundleHashOfFile(entry);
+      const sourceHash = bundleHashOfFile(sourceBundle);
+      if (installedHash !== null && sourceHash !== null && installedHash !== sourceHash) {
+        return {
+          id: "stale_install",
+          status: "fail",
+          detail: `stale_install: installed workit-cursor ${installed} runs different bytes than the current runtime build (${path.basename(entry)} hash mismatch)`,
+          fix: "Re-run install-cursor-plugin.sh — it refreshes the plugin directory with the current build",
+        };
+      }
+    }
+  }
   if (installed !== null && localDist) {
     const expected = registryLatestVersion(res);
     if (expected === null) {

package/src/core/external-action-effects.ts

@@ -1,4 +1,9 @@
-import { branchSetup, resolveBranchPolicyFor, resolveCommitPolicyFor } from "./branch";
+import {
+  branchSetup,
+  classifyBranchDirt,
+  resolveBranchPolicyFor,
+  resolveCommitPolicyFor,
+} from "./branch";
 import { hostingCliAvailable, prCreate } from "./pr-create";
 import {
   changelogContext,
@@ -24,6 +29,7 @@ import { failure, success, sha256, type Caller, type Result, type Ref } from "./
 import { changelogApply, changelogApplyPreview } from "./changelog";
 import type { ExternalActionRequest } from "./external-action";
 import { externalActionDescriptor, externalActionRequest } from "./external-action";
+import { normalizeChainSteps } from "./authority";
 import { resolveInside, run as coreRun } from "../core";
 import { vcsConfig } from "./vcs-config";
 import { detectCommitFlavor, matchCommitFlavor, type CommitFlavor } from "./commit-flavors";
@@ -271,10 +277,33 @@ export const actionProposalQuestion = (
   const resolved = (payload.resolved ?? {}) as Record<string, unknown>;
   const payloadTarget = String(payload.target_branch ?? "");
   if (request.operation === "git.commit" && Array.isArray(payload.plan_steps)) {
-    const steps = payload.plan_steps as string[];
+    const steps = payload.plan_steps as unknown[];
+    const chain = normalizeChainSteps(steps);
+    if (!chain)
+      return {
+        presented: `Workit decision: action — Approve committing the plan's listed tasks?`,
+        approvedText: `Approve the listed plan commits.`,
+      };
+    const kinds = chain.map((step) => step.kind);
+    if (kinds.every((kind) => kind === "commit"))
+      return {
+        presented: `Workit decision: action — Approve committing the plan's ${steps.length} listed tasks on \`${String(payload.plan_branch ?? "")}\`?`,
+        approvedText: `Approve the ${steps.length} listed plan commits.`,
+      };
+    const summary = [
+      kinds.filter((kind) => kind === "branch").length
+        ? `${kinds.filter((kind) => kind === "branch").length} branch`
+        : null,
+      kinds.filter((kind) => kind === "commit").length
+        ? `${kinds.filter((kind) => kind === "commit").length} commits`
+        : null,
+      kinds.includes("pr") ? "PR" : null,
+    ]
+      .filter(Boolean)
+      .join(", ");
     return {
-      presented: `Workit decision: action — Approve committing the plan's ${steps.length} listed tasks on \`${String(payload.plan_branch ?? "")}\`?`,
-      approvedText: `Approve the ${steps.length} listed plan commits.`,
+      presented: `Workit decision: action — Approve the ${steps.length}-step chain on \`${String(payload.plan_branch ?? "")}\` (${summary})?`,
+      approvedText: `Approve the ${steps.length}-step chain (${summary}).`,
     };
   }
   switch (request.operation) {
@@ -806,6 +835,32 @@ const youTrackWritePreflight = (): Result<null> => {
   return success(null, null, null);
 };
 
+/**
+ * A dirty tree binds stash up front so the proposal names it and one
+ * approval carries the whole effect instead of failing at preflight.
+ * Carry-class dirt (untracked or docs-confined) rides along silently.
+ * Returns the original resolution untouched unless an upgrade applies.
+ */
+export const upgradeBranchSetupForStash = (
+  root: string,
+  parsed: ExternalActionRequest,
+  resolved: Result<ResolvedExternalAction>,
+): Result<ResolvedExternalAction> => {
+  if (!resolved.ok || resolved.data.request.operation !== "git.branch_setup") return resolved;
+  if (
+    (resolved.data.descriptorPayload as { resolved?: { dirty?: unknown } }).resolved?.dirty !==
+      true ||
+    (resolved.data.descriptorPayload as { stash?: unknown }).stash === "yes" ||
+    classifyBranchDirt(root) !== "stash-required"
+  )
+    return resolved;
+  const upgraded = resolveExternalActionRequest(root, {
+    ...parsed,
+    payload: { ...(parsed.payload as Record<string, unknown>), stash: "yes" },
+  } as typeof parsed);
+  return upgraded.ok ? upgraded : resolved;
+};
+
 export const resolveExternalActionRequest = (
   root: string,
   request: ExternalActionRequest,
@@ -872,26 +927,41 @@ export const resolveExternalActionRequest = (
         if (!head) return failure("storage_error", "Git state could not be resolved");
         const branch = gitValue(root, ["branch", "--show-current"]);
         if (planSteps !== undefined || planBranch !== undefined) {
-          if (
-            !Array.isArray(planSteps) ||
-            planSteps.some((step) => typeof step !== "string" || !step.trim()) ||
-            new Set(planSteps).size !== planSteps.length ||
-            planSteps.length === 0 ||
-            planSteps.length > 32
-          )
+          const chain = Array.isArray(planSteps) ? normalizeChainSteps(planSteps) : null;
+          if (!chain)
             return failure(
               "invalid_input",
-              "plan_steps must be 1-32 unique non-empty commit messages",
+              "plan_steps must be 1-32 unique non-empty commit messages, branch targets, or pull_request markers",
               {
                 outcome: "not_started",
-                fields: [{ path: "plan_steps", reason: "unique strings" }],
+                fields: [{ path: "plan_steps", reason: "unique steps" }],
               },
             );
-          if (typeof planBranch !== "string" || !planBranch.trim() || planBranch !== branch)
-            return failure("invalid_input", "plan_branch must name the current working branch", {
+          if (typeof planBranch !== "string" || !planBranch.trim())
+            return failure("invalid_input", "plan_branch must name the working branch", {
               outcome: "not_started",
-              fields: [{ path: "plan_branch", reason: "current branch" }],
+              fields: [{ path: "plan_branch", reason: "required" }],
             });
+          // A chain that creates its own branch names that branch; otherwise
+          // the plan runs on the branch already checked out.
+          const first = chain[0];
+          const createsBranch = first?.kind === "branch";
+          if (createsBranch ? planBranch !== first.target : planBranch !== branch)
+            return failure(
+              "invalid_input",
+              createsBranch
+                ? "plan_branch must name the branch the chain creates"
+                : "plan_branch must name the current working branch",
+              {
+                outcome: "not_started",
+                fields: [
+                  {
+                    path: "plan_branch",
+                    reason: createsBranch ? "chain branch" : "current branch",
+                  },
+                ],
+              },
+            );
           if (isProtectedBranch(root, planBranch))
             return failure("invalid_input", "plan_branch must not be a protected branch", {
               outcome: "not_started",

package/src/core/external-action.ts

@@ -14,6 +14,7 @@ import {
 } from "./task-contract";
 import { WorkitCore } from "./task-engine";
 import { TaskStore } from "./task-store";
+import { chainStepKey, normalizeChainSteps, type ChainStep } from "./authority";
 import * as z from "zod";
 import { execFileSync } from "node:child_process";
 
@@ -323,33 +324,58 @@ export const priorExternalAction = (
 /** Parse a plan-commit authorization descriptor (one approved list per plan). */
 export const planCommitDescriptor = (
   content: string,
-): { steps: string[]; branch: string } | null => {
+): { steps: ChainStep[]; branch: string; snapshotHead: string | null } | null => {
   try {
     const value = JSON.parse(content) as {
       operation?: unknown;
-      payload?: { plan_steps?: unknown; plan_branch?: unknown };
+      payload?: {
+        plan_steps?: unknown;
+        plan_branch?: unknown;
+        resolved?: { head?: unknown; branch?: unknown };
+      };
     };
     if (value.operation !== "git.commit" || !value.payload) return null;
-    const steps = value.payload.plan_steps;
+    const steps = normalizeChainSteps(value.payload.plan_steps);
     const branch = value.payload.plan_branch;
-    if (
-      !Array.isArray(steps) ||
-      steps.some((step) => typeof step !== "string" || !step) ||
-      typeof branch !== "string" ||
-      !branch
-    )
-      return null;
-    return { steps: steps as string[], branch };
+    if (!steps || typeof branch !== "string" || !branch) return null;
+    const head = value.payload.resolved?.head;
+    return { steps, branch, snapshotHead: typeof head === "string" ? head : null };
   } catch {
     return null;
   }
 };
 
+/**
+ * Chain lease: the recorded head must still be an ancestor of the current
+ * HEAD — history only moved forward. Rebase/reset underneath an approved
+ * chain invalidates it instead of executing on rewritten history.
+ */
+export const chainLeaseValid = (store: TaskStore, snapshotHead: string | null): boolean => {
+  if (!snapshotHead) return true;
+  try {
+    const head = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: store.root,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    if (head === snapshotHead) return true;
+    execFileSync("git", ["merge-base", "--is-ancestor", snapshotHead, head], {
+      cwd: store.root,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
 export type PlanCommitAuthorization = {
   task: TaskRecord;
   entry: Entry<Decision>;
-  steps: string[];
+  steps: ChainStep[];
   branch: string;
+  snapshotHead: string | null;
   completed: string[];
 };
 
@@ -357,7 +383,10 @@ export type PlanCommitAuthorization = {
  * Find the single active plan-commit authorization whose next unconsumed step
  * is this exact commit message. Consumption order is enforced so each listed
  * commit executes once, in plan order; unlisted or replayed messages find no
- * authorization and require a fresh exact approval.
+ * authorization and require a fresh exact approval. Typed chain positions
+ * never match messages (a pathological message falls through to a fresh
+ * approval instead of consuming the wrong step), and a rewritten history
+ * breaks the lease.
  */
 export const approvedPlanCommit = (
   store: TaskStore,
@@ -395,8 +424,19 @@ export const approvedPlanCommit = (
       const completed =
         task.actionProgress?.find((progress) => progress.decisionId === entry.id)?.completedSteps ??
         [];
-      if (plan.steps[completed.length] !== message) return [];
-      return [{ task, entry, steps: plan.steps, branch: plan.branch, completed: [...completed] }];
+      const next = plan.steps[completed.length];
+      if (!next || next.kind !== "commit" || next.message !== message) return [];
+      if (!chainLeaseValid(store, plan.snapshotHead)) return [];
+      return [
+        {
+          task,
+          entry,
+          steps: plan.steps,
+          branch: plan.branch,
+          snapshotHead: plan.snapshotHead,
+          completed: [...completed],
+        },
+      ];
     });
   });
   if (matches.length !== 1)
@@ -409,6 +449,80 @@ export const approvedPlanCommit = (
   return success(workspace.data.revision, null, matches[0]);
 };
 
+export type ChainStepQuery =
+  | { operation: "git.branch_setup"; target: string }
+  | { operation: "hosting.pull_request" };
+
+/**
+ * Match one branch or PR step of a chain authorization: same session-bound
+ * search as plan commits, next unconsumed step of the right kind, lease
+ * intact. Commit steps stay on the plan path; this covers the steps plans
+ * could never express.
+ */
+export const approvedChainStep = (
+  store: TaskStore,
+  host: string,
+  actor: string,
+  query: ChainStepQuery,
+): Result<PlanCommitAuthorization> => {
+  const listed = store.listTasks();
+  const workspace = store.readWorkspace();
+  if (!listed.ok || !workspace.ok)
+    return failure("storage_error", "external action state is unavailable");
+  if (!workspace.data) return failure("not_found", "workspace not found");
+  const matches = listed.data.flatMap((task) => {
+    if (task.status !== "active" || task.workspaceId !== workspace.data!.id) return [];
+    if (
+      task.intent.provenance.session?.kind !== "host" ||
+      task.intent.provenance.session.host !== host ||
+      task.intent.provenance.session.handle !== actor
+    )
+      return [];
+    return task.decisions.flatMap((entry) => {
+      const decision = entry.data;
+      if (
+        decision.purpose !== "action" ||
+        decision.response !== "approved" ||
+        decision.revoked !== null
+      )
+        return [];
+      if (entry.provenance.kind !== "host_observed" || entry.provenance.receipts.length === 0)
+        return [];
+      const plan = planCommitDescriptor(decision.binding.approvedContent);
+      if (!plan) return [];
+      const completed =
+        task.actionProgress?.find((progress) => progress.decisionId === entry.id)?.completedSteps ??
+        [];
+      const next = plan.steps[completed.length];
+      if (!next) return [];
+      if (query.operation === "git.branch_setup") {
+        if (next.kind !== "branch" || next.target !== query.target) return [];
+      } else if (next.kind !== "pr") {
+        return [];
+      }
+      if (!chainLeaseValid(store, plan.snapshotHead)) return [];
+      return [
+        {
+          task,
+          entry,
+          steps: plan.steps,
+          branch: plan.branch,
+          snapshotHead: plan.snapshotHead,
+          completed: [...completed],
+        },
+      ];
+    });
+  });
+  if (matches.length !== 1)
+    return failure(
+      "permission_denied",
+      matches.length === 0
+        ? "no chain authorization matches this step"
+        : "multiple chain authorizations match this step",
+    );
+  return success(workspace.data.revision, null, matches[0]);
+};
+
 export const commitMessageFromDescriptor = (operation: string): string | undefined => {
   try {
     const descriptor = JSON.parse(operation) as {
@@ -423,6 +537,69 @@ export const commitMessageFromDescriptor = (operation: string): string | undefin
   }
 };
 
+/** Resolve a chain authorization into the exact binding an adapter needs
+ * to run one branch or PR step under the approved chain. Commit steps stay
+ * on the plan path; this covers the steps plans could never express. */
+export const chainStepBinding = (
+  store: TaskStore,
+  host: string,
+  actor: string,
+  operation: string,
+): {
+  taskId: Id;
+  decisionId: Id;
+  binding: Decision["binding"];
+  expectedRevision: Revision;
+  expectedWorkspaceRevision: Revision;
+  step: string;
+} | null => {
+  let descriptor: { operation?: unknown; payload?: Record<string, unknown> };
+  try {
+    descriptor = JSON.parse(operation) as {
+      operation?: unknown;
+      payload?: Record<string, unknown>;
+    };
+  } catch {
+    return null;
+  }
+  const query: ChainStepQuery | null =
+    descriptor.operation === "git.branch_setup" &&
+    typeof descriptor.payload?.target_branch === "string"
+      ? { operation: "git.branch_setup", target: descriptor.payload.target_branch as string }
+      : descriptor.operation === "hosting.pull_request"
+        ? { operation: "hosting.pull_request" }
+        : null;
+  if (!query) return null;
+  const chain = approvedChainStep(store, host, actor, query);
+  if (!chain.ok) return null;
+  // PR steps run on the chain branch; the branch step itself creates it.
+  if (query.operation === "hosting.pull_request") {
+    let branch: string;
+    try {
+      branch = execFileSync("git", ["branch", "--show-current"], {
+        cwd: store.root,
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    } catch {
+      return null;
+    }
+    if (!branch || branch !== chain.data.branch) return null;
+  }
+  const workspace = store.readWorkspace();
+  if (!workspace.ok || !workspace.data) return null;
+  const next = chain.data.steps[chain.data.completed.length];
+  if (!next) return null;
+  return {
+    taskId: chain.data.task.id,
+    decisionId: chain.data.entry.id,
+    binding: chain.data.entry.data.binding,
+    expectedRevision: chain.data.task.revision,
+    expectedWorkspaceRevision: workspace.data.revision,
+    step: chainStepKey(next),
+  };
+};
+
 /** Resolve a plan-commit authorization into the exact binding an adapter needs
  * to run one listed commit under the approved list. */
 export const planCommitBinding = (

package/src/core/methods.ts

@@ -17,12 +17,14 @@ type MethodDefinition = {
 
 export const METHODS: Readonly<Record<MethodId, MethodDefinition>> = {
   "workit-challenge": { dimensions: ["challenge", "decisions"] },
-  "workit-behavioral-tdd": { dimensions: ["testing"] },
-  "workit-review": { dimensions: ["review"], ruleIds: ["fresh-context-review"] },
+  "workit-behavioral-tdd": { dimensions: ["testing"], ruleIds: ["mechanical-existing-checks"] },
+  "workit-review": { dimensions: ["review"], ruleIds: ["fresh-context-review", "self-review"] },
   "workit-plan": { dimensions: ["artifacts", "continuity"] },
   "workit-implement": { dimensions: ["delegation"] },
-  "workit-debug": { ruleIds: ["root-cause-investigation"] },
-  "workit-handoff": { ruleIds: ["durable-handoff"] },
+  // workit-debug and workit-handoff stay slash-invoked: no generated rule
+  // routes to them, so they never appear spuriously in method selection.
+  "workit-debug": {},
+  "workit-handoff": {},
   "workit-deslop": { ruleIds: ["pre-pr-cleanup"] },
 };
 
@@ -33,12 +35,10 @@ export type SelectedMethod = {
 };
 
 const methodMatches = (
-  id: MethodId,
   definition: MethodDefinition,
   requirement: Policy["requirements"][number],
 ): boolean =>
-  (definition.dimensions?.includes(requirement.dimension) === true &&
-    !(id === "workit-review" && requirement.ruleId === "self-review")) ||
+  definition.dimensions?.includes(requirement.dimension) === true ||
   definition.ruleIds?.includes(requirement.ruleId) === true;
 
 const assuranceFor = (
@@ -71,7 +71,7 @@ const assuranceFor = (
 export function selectMethods(policy: Policy, capabilities: Capability[]): SelectedMethod[] {
   return (Object.entries(METHODS) as [MethodId, MethodDefinition][]).flatMap(([id, definition]) => {
     const requirements = policy.requirements.filter((requirement) =>
-      methodMatches(id, definition, requirement),
+      methodMatches(definition, requirement),
     );
     if (requirements.length === 0) return [];
     const capability = assuranceFor(id, definition, capabilities);