@brainervirus/workit-core 1.0.8 → 1.0.10

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,
@@ -331,6 +485,40 @@ export const approvedExternalAction = (
   return selected;
 };
 
+/**
+ * Re-resolve guard: when a prior approval exists for the same requested
+ * operation/payload, the freshly resolved baseline (source state and remote
+ * base) must still match the approved descriptor. Drift 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 (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 =
   (core: WorkitCore, bind: ExternalActionBinding): ExternalActionEffect =>
   async <T>(

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

@@ -0,0 +1,51 @@
+export type ShellRouteIntent = {
+  route: "git.branch_setup" | "hosting.pull_request";
+  guidance: string;
+};
+
+const GUIDANCE: Record<ShellRouteIntent["route"], string> = {
+  "git.branch_setup":
+    "use the Workit git.branch_setup action (workit_external_action in hosts, or `workit action git.branch_setup --payload '{}' --confirm --json` in the CLI)",
+  "hosting.pull_request":
+    "use the Workit hosting.pull_request action (workit_external_action in hosts, or `workit action hosting.pull_request --payload '{...}' --confirm --json` in the CLI), then drive the created PR through workit-babysit",
+};
+
+const unbalancedQuotes = (segment: string): boolean => {
+  const text = segment.replace(/\\./gu, "");
+  return (text.match(/"/gu)?.length ?? 0) % 2 !== 0 || (text.match(/'/gu)?.length ?? 0) % 2 !== 0;
+};
+
+const segmentTokens = (segment: string): string[] | null => {
+  if (segment.includes("`") || segment.includes("$(")) return null;
+  if (unbalancedQuotes(segment)) return null;
+  const parts = segment.trim().split(/\s+/u);
+  while (parts.length > 0 && /^[A-Za-z_][A-Za-z0-9_]*=/u.test(parts[0])) parts.shift();
+  return parts.length > 0 ? parts : null;
+};
+
+const unquote = (token: string): string => token.replace(/^['"]|['"]$/gu, "");
+
+/**
+ * Narrow recognizer for direct branch and PR creation commands. It returns null
+ * for everything it cannot classify unambiguously, so hosts deny only the exact
+ * routes that must go through the shared action reservation.
+ */
+export function shellRouteIntent(command: string): ShellRouteIntent | null {
+  if (typeof command !== "string" || command.trim() === "") return null;
+  for (const raw of command.split(/&&|\|\||;|\n/u)) {
+    const parts = segmentTokens(raw);
+    if (!parts) continue;
+    const head = unquote(parts[0]);
+    const second = unquote(parts[1] ?? "");
+    const third = unquote(parts[2] ?? "");
+    if (head === "git" && second === "switch" && (third === "-c" || third === "--create"))
+      return { route: "git.branch_setup", guidance: GUIDANCE["git.branch_setup"] };
+    if (head === "git" && second === "checkout" && (third === "-b" || third === "-B"))
+      return { route: "git.branch_setup", guidance: GUIDANCE["git.branch_setup"] };
+    if (head === "gh" && second === "pr" && third === "create")
+      return { route: "hosting.pull_request", guidance: GUIDANCE["hosting.pull_request"] };
+    if (head === "glab" && second === "mr" && third === "create")
+      return { route: "hosting.pull_request", guidance: GUIDANCE["hosting.pull_request"] };
+  }
+  return null;
+}

package/src/core/task-context.ts

@@ -1,3 +1,4 @@
+import { isUncertainWorker } from "./workers";
 import {
   POLICY_VERSION,
   failure,
@@ -13,6 +14,7 @@ import {
   type Utc,
 } from "./task-contract";
 import { captureCandidate, evaluateEvidence } from "./task-evaluation";
+import { selectMethods, type SelectedMethod } from "./methods";
 import type { NativeWorkerObservation } from "./workers";
 
 export type ResumeObservation = {
@@ -41,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) =>
-      ["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",
@@ -71,10 +69,12 @@ type CompactDecision = {
   digest: string;
   references: CompactReference[];
 };
+type CompactMethod = Pick<SelectedMethod, "id" | "assurance"> & { reason: string };
 export type CompactTaskContext = {
   objective: string;
   status: TaskView["task"]["status"];
   decisions: CompactDecision[];
+  methods: CompactMethod[];
   gaps: string[];
   nextAction: string | null;
 };
@@ -127,6 +127,13 @@ export function compactTaskContext(view: TaskView): string {
       digest: entry.data.digest,
       references: entry.data.binding.contentRefs.slice(0, 1).map(compactReference),
     }));
+  const methods: CompactMethod[] = view.task.policy
+    ? selectMethods(view.task.policy, view.capabilities).map((method) => ({
+        id: method.id,
+        assurance: method.assurance,
+        reason: compactText(method.reason, COMPACT_TEXT_BYTES) ?? "",
+      }))
+    : [];
   const gaps = Array.from(
     new Set([
       ...view.evidence
@@ -145,16 +152,18 @@ export function compactTaskContext(view: TaskView): string {
     objective: compactText(view.task.intent.data.objective, COMPACT_TEXT_BYTES) ?? "",
     status: view.task.status,
     decisions,
+    methods,
     gaps,
     nextAction: compactText(view.task.progress.nextAction, COMPACT_TEXT_BYTES),
   };
   let encoded = JSON.stringify(context);
   while (
     compactBytes(encoded) > COMPACT_MAX_BYTES &&
-    (context.decisions.length || context.gaps.length)
+    (context.decisions.length || context.methods.length || context.gaps.length)
   ) {
     if (context.gaps.length) context.gaps.pop();
-    else context.decisions.pop();
+    else if (context.decisions.length) context.decisions.pop();
+    else context.methods.pop();
     encoded = JSON.stringify(context);
   }
   if (compactBytes(encoded) > COMPACT_MAX_BYTES) {

package/src/core/task-contract.ts

@@ -453,6 +453,7 @@ export const decisionSchema = z
         scope: scopeSchema,
         presented: text,
         approvedContent: text,
+        displayed: text.optional(),
         contentRefs: z.array(refSchema),
       })
       .strict(),
@@ -471,6 +472,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,
@@ -510,7 +534,7 @@ export type WorkerReport = z.infer<typeof workerReportSchema>;
 export const workerSchema = z
   .object({
     assignment: assignmentSchema,
-    state: z.enum(["assigned", "running", "cancelling", "stopped", "unknown"]),
+    state: z.enum(["assigned", "dispatching", "running", "cancelling", "stopped", "unknown"]),
     session: refSchema.nullable(),
     report: workerReportSchema.nullable(),
   })
@@ -565,6 +589,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 +610,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 +630,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 +673,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 +757,7 @@ const taskOperations = {
     expectedWorkspaceRevision: revision.optional(),
     outcome: outcomeSchema,
     summary: text,
-    decisionIds: z.array(id),
+    decisionIds: z.array(id).optional(),
   }),
 };
 const policyOperations = {
@@ -813,13 +850,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 +929,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> =
   | {