@brainervirus/workit-core 1.0.9 → 1.0.11

package/src/core/external-action.ts

@@ -7,12 +7,15 @@ import {
   type Result,
   type Revision,
   type Decision,
+  type Entry,
+  type TaskRecord,
   refSchema,
   sha256,
 } from "./task-contract";
 import { WorkitCore } from "./task-engine";
 import { TaskStore } from "./task-store";
 import * as z from "zod";
+import { execFileSync } from "node:child_process";
 
 export type AuthorizedActionInput = {
   core: WorkitCore;
@@ -53,7 +56,13 @@ const externalActionSchema = z.discriminatedUnion("operation", [
   z
     .object({
       operation: z.literal("git.commit"),
-      payload: z.object({ message: z.string().min(1) }).strict(),
+      payload: z
+        .object({
+          message: z.string().min(1).optional(),
+          plan_steps: z.array(z.string().min(1)).optional(),
+          plan_branch: z.string().min(1).optional(),
+        })
+        .strict(),
     })
     .strict(),
   z
@@ -206,7 +215,7 @@ export const externalActionDescriptor = (operation: string, payload: unknown): s
 
 /** Compact host-facing help for the fixed optional-action surface. */
 export const externalActionHelp =
-  "Fixed actions: git.branch_setup {action?,sdd_dir?,target_branch?,stash?}; git.commit {message}; git.push {branch?}; hosting.pull_request {title,body?,draft?,target_branch?,babysit?}; youtrack.update {issueId,markdown,minutes?}; youtrack.time {issueId,minutes,text?,dateMs?}; youtrack.meeting {issueId,minutes,text}; changelog.apply {entries?,path?,normalize_only?}; context.read {kind,range?,issueId?,issueUrl?,issueRef?,mode?,specPath?,planPath?}. context.read is read-only and needs no approval; all other operations require native approval (CLI uses a TTY; caller-unattested MCP cannot mutate).";
+  "Fixed actions: git.branch_setup {action?,sdd_dir?,target_branch(required unless reapply_stash; the working branch to create or switch to),stash?}; git.commit {message}; git.push {branch?}; hosting.pull_request {title,body?,draft?,target_branch?,babysit?}; youtrack.update {issueId,markdown,minutes?}; youtrack.time {issueId,minutes,text?,dateMs?}; youtrack.meeting {issueId,minutes,text}; changelog.apply {entries?,path?,normalize_only?}; context.read {kind,range?,issueId?,issueUrl?,issueRef?,mode?,specPath?,planPath?}. context.read is read-only and needs no approval; all other operations require native approval (CLI uses a TTY; caller-unattested MCP cannot mutate).";
 
 export const externalActionRef = (
   host: "opencode" | "pi" | "workit_cli",
@@ -311,6 +320,151 @@ export const priorExternalAction = (
   return success(workspace.data.revision, null, { ...candidates[0], workspace: workspace.data });
 };
 
+/** Parse a plan-commit authorization descriptor (one approved list per plan). */
+export const planCommitDescriptor = (
+  content: string,
+): { steps: string[]; branch: string } | null => {
+  try {
+    const value = JSON.parse(content) as {
+      operation?: unknown;
+      payload?: { plan_steps?: unknown; plan_branch?: unknown };
+    };
+    if (value.operation !== "git.commit" || !value.payload) return null;
+    const steps = 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 };
+  } catch {
+    return null;
+  }
+};
+
+export type PlanCommitAuthorization = {
+  task: TaskRecord;
+  entry: Entry<Decision>;
+  steps: string[];
+  branch: string;
+  completed: string[];
+};
+
+/**
+ * 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.
+ */
+export const approvedPlanCommit = (
+  store: TaskStore,
+  host: string,
+  actor: string,
+  message: string,
+): Result<PlanCommitAuthorization> => {
+  if (typeof message !== "string" || !message)
+    return failure("invalid_input", "commit message is required");
+  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 ??
+        [];
+      if (plan.steps[completed.length] !== message) return [];
+      return [{ task, entry, steps: plan.steps, branch: plan.branch, completed: [...completed] }];
+    });
+  });
+  if (matches.length !== 1)
+    return failure(
+      "permission_denied",
+      matches.length === 0
+        ? "no plan commit authorization matches this message"
+        : "multiple plan authorizations match this message",
+    );
+  return success(workspace.data.revision, null, matches[0]);
+};
+
+export const commitMessageFromDescriptor = (operation: string): string | undefined => {
+  try {
+    const descriptor = JSON.parse(operation) as {
+      operation?: unknown;
+      payload?: { message?: unknown };
+    };
+    return descriptor.operation === "git.commit" && typeof descriptor.payload?.message === "string"
+      ? descriptor.payload.message
+      : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/** Resolve a plan-commit authorization into the exact binding an adapter needs
+ * to run one listed commit under the approved list. */
+export const planCommitBinding = (
+  store: TaskStore,
+  host: string,
+  actor: string,
+  operation: string,
+): {
+  taskId: Id;
+  decisionId: Id;
+  binding: Decision["binding"];
+  expectedRevision: Revision;
+  expectedWorkspaceRevision: Revision;
+  step: string;
+} | null => {
+  const message = commitMessageFromDescriptor(operation);
+  if (!message) return null;
+  const plan = approvedPlanCommit(store, host, actor, message);
+  if (!plan.ok) return null;
+  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 !== plan.data.branch) return null;
+  const workspace = store.readWorkspace();
+  if (!workspace.ok || !workspace.data) return null;
+  return {
+    taskId: plan.data.task.id,
+    decisionId: plan.data.entry.id,
+    binding: plan.data.entry.data.binding,
+    expectedRevision: plan.data.task.revision,
+    expectedWorkspaceRevision: workspace.data.revision,
+    step: message,
+  };
+};
+
 export const approvedExternalAction = (
   store: TaskStore,
   host: string,
@@ -318,17 +472,190 @@ export const approvedExternalAction = (
   operation: string,
 ) => {
   const selected = externalActionState(store, host, actor, operation);
-  if (!selected.ok) return selected;
-  if (selected.data.entry.data.consumption !== null)
+  if (selected.ok) {
+    if (selected.data.entry.data.consumption !== null)
+      return failure(
+        selected.data.entry.data.consumption.state === "uncertain"
+          ? "external_outcome_unknown"
+          : "permission_denied",
+        selected.data.entry.data.consumption.state === "uncertain"
+          ? "previous external action outcome is unknown"
+          : "external action was already settled",
+      );
+    return selected;
+  }
+  // Intent carry for branch setup: an approval binds (target, base) intent,
+  // so unrelated HEAD or dirt moves between approval and execution re-resolve
+  // instead of demanding re-approval. Remote, existence, and target drift
+  // still fail closed through priorResolvedDrift.
+  const intent = approvedBranchSetupIntent(store, host, actor, operation);
+  if (intent.ok) {
+    if (intent.data.entry.data.consumption !== null)
+      return failure(
+        intent.data.entry.data.consumption.state === "uncertain"
+          ? "external_outcome_unknown"
+          : "permission_denied",
+        intent.data.entry.data.consumption.state === "uncertain"
+          ? "previous external action outcome is unknown"
+          : "external action was already settled",
+      );
+    return intent;
+  }
+  return selected;
+};
+
+/** Intent identity for a branch-setup descriptor: target and base bind the
+ * effect; head and dirt are execution-time state that re-resolves. */
+export const branchSetupIntent = (
+  descriptor: string,
+): { target: string; base: string; remoteBase: string | null; targetExists: boolean } | null => {
+  try {
+    const value = JSON.parse(descriptor) as {
+      operation?: unknown;
+      payload?: {
+        target_branch?: unknown;
+        resolved?: {
+          base_branch?: unknown;
+          remote_base?: unknown;
+          target_exists?: unknown;
+        };
+      };
+    };
+    if (value.operation !== "git.branch_setup" || !value.payload) return null;
+    const { target_branch, resolved } = value.payload;
+    if (typeof target_branch !== "string" || !target_branch || !resolved) return null;
+    if (typeof resolved.base_branch !== "string" || typeof resolved.target_exists !== "boolean")
+      return null;
+    return {
+      target: target_branch,
+      base: resolved.base_branch,
+      remoteBase: typeof resolved.remote_base === "string" ? resolved.remote_base : null,
+      targetExists: resolved.target_exists,
+    };
+  } catch {
+    return null;
+  }
+};
+
+/** Find the single unconsumed branch-setup approval with the same intent as
+ * the current descriptor, regardless of head or dirt moves since approval. */
+export const approvedBranchSetupIntent = (
+  store: TaskStore,
+  host: string,
+  actor: string,
+  operation: string,
+) => {
+  const current = branchSetupIntent(operation);
+  if (!current) return failure("permission_denied", "no approved action is bound to this session");
+  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 candidates = listed.data.flatMap((task) => {
+    if (
+      task.status !== "active" ||
+      task.workspaceId !== workspace.data!.id ||
+      task.intent.provenance.session?.kind !== "host" ||
+      task.intent.provenance.session.host !== host ||
+      task.intent.provenance.session.handle !== actor
+    )
+      return [];
+    return task.decisions
+      .filter(
+        (entry) =>
+          entry.data.purpose === "action" &&
+          entry.data.response === "approved" &&
+          entry.data.revoked === null,
+      )
+      .map((entry) => ({ task, entry }));
+  });
+  const matches = candidates.filter(({ entry }) => {
+    const intent = branchSetupIntent(entry.data.binding.approvedContent);
+    return (
+      intent !== null &&
+      intent.target === current.target &&
+      intent.base === current.base &&
+      intent.remoteBase === current.remoteBase &&
+      intent.targetExists === current.targetExists
+    );
+  });
+  if (matches.length !== 1)
     return failure(
-      selected.data.entry.data.consumption.state === "uncertain"
-        ? "external_outcome_unknown"
-        : "permission_denied",
-      selected.data.entry.data.consumption.state === "uncertain"
-        ? "previous external action outcome is unknown"
-        : "external action was already settled",
+      "permission_denied",
+      matches.length === 0
+        ? "no approved action is bound to this session"
+        : "multiple approved actions match this session",
     );
-  return selected;
+  return success(workspace.data.revision, null, { ...matches[0], workspace: workspace.data });
+};
+
+/**
+ * Re-resolve guard: when a prior approval exists for the same requested
+ * operation/payload, the intent baseline must still match. For branch setup
+ * only (target, base, remote base, existence) bind the effect — head and
+ * dirt moves re-resolve instead of demanding re-approval. Drift names the
+ * moved element and returns not_started so the agent re-presents the
+ * current state instead of executing a stale effect.
+ */
+export const priorResolvedDrift = (
+  store: TaskStore,
+  host: string,
+  actor: string,
+  operation: string,
+  payload: unknown,
+  currentResolved: unknown,
+): Result<null> => {
+  const prior = priorExternalAction(store, host, actor, operation, payload);
+  if (!prior.ok) return success(null, null, null);
+  let baseline: unknown;
+  try {
+    const parsed = JSON.parse(prior.data.entry.data.binding.approvedContent) as {
+      payload?: { resolved?: unknown };
+    };
+    baseline = parsed.payload?.resolved;
+  } catch {
+    return success(null, null, null);
+  }
+  if (baseline === undefined || baseline === null) return success(null, null, null);
+  if (operation === "git.branch_setup") {
+    const before = branchSetupIntent(prior.data.entry.data.binding.approvedContent);
+    let after: ReturnType<typeof branchSetupIntent> = null;
+    try {
+      after = branchSetupIntent(
+        JSON.stringify({
+          operation,
+          payload: { ...(payload as Record<string, unknown>), resolved: currentResolved },
+        }),
+      );
+    } catch {
+      after = null;
+    }
+    if (before && after) {
+      const moved =
+        before.target !== after.target
+          ? "target_branch"
+          : before.base !== after.base
+            ? "base_branch"
+            : before.remoteBase !== after.remoteBase
+              ? "remote_base"
+              : before.targetExists !== after.targetExists
+                ? "target_exists"
+                : null;
+      if (moved === null) return success(null, null, null);
+      return failure(
+        "invalid_input",
+        `repository state changed since approval (${moved} moved); show the current state and approve the action again`,
+        { outcome: "not_started", operation },
+      );
+    }
+  }
+  if (canonicalJson(baseline) === canonicalJson(currentResolved)) return success(null, null, null);
+  return failure(
+    "invalid_input",
+    "repository state changed since approval; show the current state and approve the action again",
+    { outcome: "not_started", operation },
+  );
 };
 
 export const createAuthorizedExternalActionRunner =

package/src/core/methods.ts

@@ -18,7 +18,7 @@ type MethodDefinition = {
 export const METHODS: Readonly<Record<MethodId, MethodDefinition>> = {
   "workit-challenge": { dimensions: ["challenge", "decisions"] },
   "workit-behavioral-tdd": { dimensions: ["testing"] },
-  "workit-review": { dimensions: ["review"] },
+  "workit-review": { dimensions: ["review"], ruleIds: ["fresh-context-review"] },
   "workit-plan": { dimensions: ["artifacts", "continuity"] },
   "workit-implement": { dimensions: ["delegation"] },
   "workit-debug": { ruleIds: ["root-cause-investigation"] },
@@ -107,7 +107,18 @@ decision.record {binding with taskId/workspaceId from inspect plus presented and
 approvedContent} only through a native approval question asked receipt-shaped:
 header Workit decision: <purpose>, the same label repeated in the question
 text (some host UIs do not render headers), exactly two options approved and
-rejected; ask once, never re-ask to mint a receipt. task.close {outcome,
+rejected; ask once, never re-ask to mint a receipt. Before asking, present the
+item in the conversation (durable artifacts: complete digest plus exact path;
+inline plans: the content) and keep the question to one short scoped sentence;
+never ask to approve something unseen. An answer with custom text is steering,
+not approval: adjust, re-present, then ask a new scoped question. After the user
+approves a spec or plan, execute the remaining tasks continuously with one
+atomic commit per task and do not ask whether to continue; stop only for a new
+product decision, a failed safety or verification gate, a conflicting edit, or
+missing authority. Record the plan's commit list once through the plan-scoped
+action approval (git.commit with plan_steps and plan_branch) so each listed
+commit executes without a new question; an unlisted message needs a fresh
+approval. task.close {outcome,
 summary, decisionIds}. A completed native subagent run stops its bound worker
 by itself; if a worker strands in cancelling with its run verifiably over,
 repeat worker.cancel {reason} to confirm the stop. Check and review evidence

package/src/core/policy-resolver.ts

@@ -306,7 +306,7 @@ function resolveRequirements(input: NormalizedResolverInput): Requirement[] {
         satisfaction:
           "An observed or inferred fact resolves the uncertainty and records its supporting references.",
         before: "dependent_action",
-        dependentAction: "dependent-action",
+        dependentAction: null,
         acceptanceAllowed: false,
       }),
     );
@@ -321,7 +321,7 @@ function resolveRequirements(input: NormalizedResolverInput): Requirement[] {
         satisfaction:
           "Present the material alternatives and record the user's decision before the dependent action.",
         before: "dependent_action",
-        dependentAction: "dependent-action",
+        dependentAction: null,
         acceptanceAllowed: false,
       }),
     );

package/src/core/route-intent.ts

@@ -1,3 +1,5 @@
+import { TaskStore } from "./task-store";
+
 export type ShellRouteIntent = {
   route: "git.branch_setup" | "hosting.pull_request";
   guidance: string;
@@ -49,3 +51,29 @@ export function shellRouteIntent(command: string): ShellRouteIntent | null {
   }
   return null;
 }
+
+/**
+ * Session-scoped enforcement: the denial protects live Workit coordination,
+ * so it fires only where an active or paused task exists. Any filesystem or
+ * storage failure means "no live task" — never deny on uncertainty.
+ */
+export function hasLiveWorkitTask(dir: string): boolean {
+  try {
+    if (typeof dir !== "string" || dir === "") return false;
+    const listed = new TaskStore(dir).listTasks();
+    if (!listed.ok) return false;
+    return listed.data.some((task) => task.status === "active" || task.status === "paused");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Single core gate for the shell route denial. Adapters pass their
+ * session/project directory and delete local deny duplication; outside
+ * attributed sessions the command is silently allowed.
+ */
+export function shouldDenyShellRoute(dir: string, command: string): ShellRouteIntent | null {
+  if (!hasLiveWorkitTask(dir)) return null;
+  return shellRouteIntent(command);
+}

package/src/core/task-context.ts

@@ -1,3 +1,4 @@
+import { isUncertainWorker } from "./workers";
 import {
   POLICY_VERSION,
   failure,
@@ -42,11 +43,7 @@ export function reconcileResume(
     .filter((entry) => entry.status === "stale")
     .map((entry) => entry.evidenceId);
   const blockers = [...view.task.progress.blockers];
-  if (
-    view.task.workers.some((entry) =>
-      ["dispatching", "running", "cancelling", "unknown"].includes(entry.data.state),
-    )
-  )
+  if (view.task.workers.some((entry) => isUncertainWorker(entry.data.state)))
     blockers.push({
       reason: "worker state requires reconciliation",
       dependentAction: "resume",

package/src/core/task-contract.ts

@@ -453,11 +453,13 @@ export const decisionSchema = z
         scope: scopeSchema,
         presented: text,
         approvedContent: text,
+        displayed: text.optional(),
         contentRefs: z.array(refSchema),
+        statedChoice: z.object({ ref: text, text: text }).strict().optional(),
       })
       .strict(),
     digest,
-    response: z.enum(["approved", "rejected"]),
+    response: z.enum(["approved", "rejected", "stated"]),
     requirementIds: z.array(digest),
     revoked: z.object({ at: utc, reason: text }).strict().nullable(),
     consumption: z
@@ -471,6 +473,29 @@ export const decisionSchema = z
   })
   .strict();
 export type Decision = z.infer<typeof decisionSchema>;
+
+/** Show-before-ask guard: binding questions are single-sentence and never
+ * carry the artifact, descriptor, or payload body in the question UI. */
+export const BINDING_QUESTION_BUDGET = 300;
+const bindingQuestionHeader = /^Workit decision: (design|action|limitation|preference)$/;
+export const workitBindingQuestionIssue = (questions: unknown): string | null => {
+  if (!Array.isArray(questions) || questions.length !== 1) return null;
+  const question = questions[0] as { header?: unknown; question?: unknown; options?: unknown };
+  if (!question || typeof question !== "object") return null;
+  if (typeof question.header !== "string" || !bindingQuestionHeader.test(question.header.trim()))
+    return null;
+  const over = (label: string, value: string) =>
+    `invalid_input: ${label} is ${value.length} characters; Workit binding questions must stay within ${BINDING_QUESTION_BUDGET}. present the item in the conversation first, then ask a short scoped question.`;
+  if (typeof question.question === "string" && question.question.length > BINDING_QUESTION_BUDGET)
+    return over("the question text", question.question);
+  if (Array.isArray(question.options))
+    for (const option of question.options) {
+      const description = (option as { description?: unknown }).description;
+      if (typeof description === "string" && description.length > BINDING_QUESTION_BUDGET)
+        return over("an option description", description);
+    }
+  return null;
+};
 export const findingSchema = z
   .object({
     claim: text,
@@ -565,6 +590,13 @@ export const actionProgressListSchema = z.array(actionProgressSchema).check((ctx
       path: ["decisionId"],
     });
 });
+export const runtimeSchema = z
+  .object({
+    createdWith: text.nullable(),
+    updatedWith: text,
+  })
+  .strict();
+export type RuntimeInfo = z.infer<typeof runtimeSchema>;
 export const taskRecordSchema = z
   .object({
     schemaVersion: z.literal(1),
@@ -579,6 +611,8 @@ export const taskRecordSchema = z
     status: z.enum(["active", "paused", "closed"]),
     closure: closureSchema.nullable(),
     progress: progressSchema,
+    pauseReason: text.nullable().optional(),
+    runtime: runtimeSchema.optional(),
     assessments: z.array(entrySchema(assessmentSchema)),
     policy: policySchema.nullable(),
     policyChanges: z.array(policyChangeSchema),
@@ -597,6 +631,7 @@ export const workspaceRecordSchema = z
     id,
     revision,
     root: nonEmpty,
+    runtime: runtimeSchema.optional(),
     writer: z
       .object({ state: z.enum(["held", "uncertain"]), owner: ownerSchema, acquiredAt: utc })
       .strict()
@@ -639,6 +674,9 @@ export const taskSummarySchema = z
     id,
     revision,
     workspaceRevision: revision,
+    createdAt: utc,
+    updatedAt: utc,
+    runtime: runtimeSchema.nullable(),
     objective: text,
     status: z.enum(["active", "paused", "closed"]),
     closure: closureSchema.nullable(),
@@ -720,7 +758,7 @@ const taskOperations = {
     expectedWorkspaceRevision: revision.optional(),
     outcome: outcomeSchema,
     summary: text,
-    decisionIds: z.array(id),
+    decisionIds: z.array(id).optional(),
   }),
 };
 const policyOperations = {
@@ -813,13 +851,14 @@ const writerOperations = {
     expectedRevision: revision.optional(),
     expectedWorkspaceRevision: revision.optional(),
     workerId: nullableId.optional(),
+    reason: text.optional(),
   }),
   release: operation({
     action: z.literal("release"),
     ...taskId,
     expectedRevision: revision.optional(),
     expectedWorkspaceRevision: revision.optional(),
-    reason: text,
+    reason: text.optional(),
   }),
 };
 const stateOperations = {
@@ -891,6 +930,22 @@ export type ErrorDetails = {
   path?: string;
   operation?: string;
   outcome?: "not_started" | "pending" | "unknown";
+  /** Present when a native approval must be asked from a concise proposal. */
+  proposal?: {
+    presented: string;
+    approvedContent: string;
+    descriptorDigest: string;
+  };
+  guidance?: string;
+  /** Structured remedy for unsatisfied requirements: rule, reason, and
+   * satisfaction text instead of opaque requirement hashes alone. */
+  requirements?: {
+    requirementId: string;
+    ruleId: string;
+    reason: string;
+    satisfaction: string;
+    dependentAction: string | null;
+  }[];
 };
 export type Result<T> =
   | {