@brainervirus/workit-core 1.3.0 → 1.3.2

package/package.json

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

package/src/core/branch.ts

@@ -711,7 +711,7 @@ export const branchSetup = ({
     if (classifyBranchDirt(cwd) === "stash-required" && stash !== "yes") {
       return {
         error:
-          "dirty working tree — ask with native question, then call workit_branch_setup with stash=yes",
+          "dirty working tree — obtain native host approval before stashing and setting up the branch",
         phase: "preflight",
       };
     }

package/src/core/external-action.ts

@@ -56,7 +56,7 @@ type WithExternalActionLock = <T>(
   operation: () => Promise<ExternalActionResult<T>>,
 ) => Promise<ExternalActionResult<T>>;
 
-const externalActionSchema = z.discriminatedUnion("operation", [
+export const externalActionSchema = z.discriminatedUnion("operation", [
   z
     .object({
       operation: z.literal("git.branch_setup"),
@@ -209,6 +209,13 @@ const externalActionSchema = z.discriminatedUnion("operation", [
 ]);
 export type ExternalActionRequest = z.infer<typeof externalActionSchema>;
 
+/** The complete external-action contract for hosts that register native tools. */
+export const externalActionJsonSchema = (): z.core.JSONSchema.BaseSchema =>
+  ({
+    type: "object",
+    ...z.toJSONSchema(externalActionSchema, { target: "draft-2020-12" }),
+  }) as z.core.JSONSchema.BaseSchema;
+
 export type ExternalActionOperation = ExternalActionRequest["operation"];
 
 export const externalActionRequest = (value: unknown): Result<ExternalActionRequest> => {

package/src/core/methods.ts

@@ -95,6 +95,15 @@ need zero Workit task, assessment, or writer calls. Use one compact tracked
 record only when handoff, dependent steps, concurrent actors, or meaningful
 decisions make continuity useful; similar titles alone never merge tasks.
 
+For a routine user-authorized branch or commit, prefer native host Git/shell
+tools from the outset when managed coordination or outcome reconciliation is
+not needed. Inspect the actual target checkout and its configured conventions;
+use Workit's read-only context/policy tools when needed. Do not start a task,
+acquire a writer, or mint a decision receipt solely for a native Git action.
+Native permissions still apply. Never switch execution paths to evade a denial
+or repeat an uncertain managed effect. A local-commit endpoint does not imply
+PR readiness, a fresh review, or post-commit assessment/closure paperwork.
+
 For tracked work, inspect its current state and use the shared operations for
 task, policy, evidence, finding, decision, worker, writer, and state changes.
 Start a record once for an explicit tracked objective; assess or reassess only
@@ -116,6 +125,11 @@ Preserve uncertain external outcomes and reconcile repository/provider state
 before retrying. Internal reservations prevent duplicate or ambiguous effects;
 they are not permission tickets for every edit.
 
+On OpenCode V1 and V2, use native host tools for external mutations. Workit
+provides read-only workit_context; it has no managed external-action executor.
+Do not create proposals or request Workit approvals merely to invoke native
+tools. Old uncertain managed effects still require evidence before any retry.
+
 Use host-native authorization through the host's supported path. A native
 question receipt records an actual question interaction; it is not automatic
 host permission. Record a meaningful user choice once with provenance when

package/src/core/policy-resolver.ts

@@ -326,6 +326,11 @@ function resolveRequirements(input: NormalizedResolverInput): Requirement[] {
       }),
     );
 
+  const independentBehaviorReview =
+    input.preferences?.thorough === true ||
+    input.assessment.consequences.some((consequence) =>
+      ["security", "data", "public_contract", "operations"].includes(consequence.area),
+    );
   if (signals.behaviorChange.value === true)
     requirements.push(
       requirement({
@@ -340,15 +345,18 @@ function resolveRequirements(input: NormalizedResolverInput): Requirement[] {
         acceptanceAllowed: false,
       }),
       requirement({
-        ruleId: "fresh-context-review",
+        ruleId: independentBehaviorReview ? "fresh-context-review" : "self-review",
         dimension: "review",
         scope,
-        reason: "A non-mechanical behavior change requires fresh-context review.",
-        satisfaction:
-          "A separate review context examines the current candidate and records its result.",
+        reason: independentBehaviorReview
+          ? "Consequential behavior or the thorough preference requires fresh-context review."
+          : "Bounded behavior changes use self-review unless consequential risks or trusted rules require more.",
+        satisfaction: independentBehaviorReview
+          ? "A separate review context examines the current candidate and records its result."
+          : "The lead reviews the resulting diff and records the relevant scope and checks.",
         before: "close",
         dependentAction: null,
-        acceptanceAllowed: false,
+        acceptanceAllowed: !independentBehaviorReview,
       }),
     );
   else if (signals.mechanicalLowRisk.value === true)

package/src/core/repo-context.ts

@@ -363,7 +363,7 @@ const CHANGELOG_RULES = `- Use an [Unreleased] section.
 - Entries should be human-readable and user-facing.
 - Do not use raw commit messages as changelog bullets.
 - MERGE into existing ### Category under [Unreleased] — never append a second ### Added / ### Fixed block.
-- Apply with the native workit_changelog_apply tool only (not hand-edits under Unreleased).
+- Apply with the host-native editor, preserving the repository changelog conventions.
 - If Unreleased already has duplicate category headings, normalize_only first.`;
 
 /** Port of changelog-context.sh — changelog update context. */

package/src/core/task-contract.ts

@@ -1140,8 +1140,61 @@ export const OPERATION_SCHEMA_DEPTH = 1;
 /** Provider nesting limit every advertised Workit schema must stay within. */
 export const OPERATION_SCHEMA_MAX_DEPTH = 10;
 
-export const canonicalFieldsDescription = (fields: string[]): string =>
-  `Canonical object fields: ${fields.join(", ")}. Workit validates the complete nested value.`;
+const schemaShapeDescription = (value: unknown, depth = 0): string => {
+  if (!value || typeof value !== "object") return "value";
+  const schema = value as Record<string, unknown>;
+  if (Array.isArray(schema.oneOf) || Array.isArray(schema.anyOf)) {
+    const options = (Array.isArray(schema.oneOf) ? schema.oneOf : schema.anyOf) as unknown[];
+    return `(${options.map((option) => schemaShapeDescription(option, depth)).join("|")})`;
+  }
+  if (schema.const !== undefined) return `=${JSON.stringify(schema.const)}`;
+  if (Array.isArray(schema.enum)) return `[${schema.enum.map(String).join("|")}]`;
+  const type = Array.isArray(schema.type) ? schema.type.join("/") : schema.type;
+  if (type === "array") return `arr<${schemaShapeDescription(schema.items, depth)}>`;
+  if (type === "object" && schema.properties && typeof schema.properties === "object") {
+    if (depth >= 2) return "obj";
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const properties = schema.properties as Record<string, unknown>;
+    const fields = Object.entries(properties).map(
+      ([name, child]) =>
+        `${name}${required.has(name) ? "!" : ""}:${schemaShapeDescription(child, depth + 1)}`,
+    );
+    return `obj{${fields.join(",")}}`;
+  }
+  if (typeof type !== "string") return "?";
+  return type
+    .split("/")
+    .map((part) => ({ string: "str", boolean: "bool", number: "num", null: "null" })[part] ?? part)
+    .join("|");
+};
+
+export const canonicalFieldsDescription = (
+  value: string[] | Record<string, unknown> | z.ZodType,
+): string => {
+  if (Array.isArray(value))
+    return `Canonical object fields: ${value.join(", ")}. Workit validates the complete nested value.`;
+  const isZodType = (schema: Record<string, unknown> | z.ZodType): schema is z.ZodType =>
+    "_zod" in schema && typeof schema._zod === "object";
+  const schema = isZodType(value)
+    ? (z.toJSONSchema(value, { target: "draft-2020-12" }) as Record<string, unknown>)
+    : value;
+  if (!schema.properties || typeof schema.properties !== "object") {
+    const variants = Array.isArray(schema.oneOf)
+      ? schema.oneOf
+      : Array.isArray(schema.anyOf)
+        ? schema.anyOf
+        : null;
+    return variants
+      ? `Canonical shapes: ${variants.map((variant) => schemaShapeDescription(variant)).join(" | ")}. Full nested value is validated.`
+      : "Canonical nested value; Workit validates the complete value.";
+  }
+  const properties = schema.properties as Record<string, unknown>;
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  const fields = Object.entries(properties).map(
+    ([name, child]) => `${name}${required.has(name) ? "!" : ""}:${schemaShapeDescription(child)}`,
+  );
+  return `Fields (! required): ${fields.join(", ")}. Full nested value is validated.`;
+};
 
 /**
  * Provider-safe projection of an operation JSON schema. Objects deeper than
@@ -1178,11 +1231,12 @@ export function boundedOperationJsonSchema(
     if (typeof node !== "object" || node === null) return node;
     const record = node as Record<string, unknown>;
     if (record.properties && typeof record.properties === "object") {
-      const fields = Object.keys(record.properties as Record<string, unknown>);
+      const properties = record.properties as Record<string, unknown>;
+      const fields = Object.keys(properties);
       if (currentDepth >= maxDepth || fields.length === 0) {
         const description = stringifiedObjects
-          ? `${canonicalFieldsDescription(fields)} A JSON-encoded string is also accepted.`
-          : canonicalFieldsDescription(fields);
+          ? `${canonicalFieldsDescription(record)} A JSON-encoded string is also accepted.`
+          : canonicalFieldsDescription(record);
         return tolerate({ type: "object", description });
       }
       return tolerate({

package/src/core/workspaces.ts

@@ -409,6 +409,43 @@ const canonicalGlob = (glob: string): string => {
   return real + (prefix.endsWith("/") ? "/" : "") + rest;
 };
 
+const globSpecificity = (glob: string): number =>
+  glob
+    .replaceAll("\\", "/")
+    .split("/")
+    .filter((segment) => segment.length > 0 && !/[*?[\]{]/.test(segment)).length;
+
+const selectWorkspaceMatch = <T extends { name: string; glob: string }>(
+  matches: T[],
+  cwd: string,
+  workspaceName?: string,
+): T | undefined => {
+  if (workspaceName !== undefined) {
+    const named = matches.filter((entry) => entry.name === workspaceName);
+    if (named.length === 1) return named[0];
+    if (named.length > 1)
+      throw new Error(`ambiguous workspace ${JSON.stringify(workspaceName)} for ${cwd}`);
+    if (matches.length > 0) {
+      throw new Error(
+        `workspace ${JSON.stringify(workspaceName)} does not match ${cwd}; matching choices: ${matches.map((entry) => entry.name).join(", ")}`,
+      );
+    }
+    throw new Error(`workspace ${JSON.stringify(workspaceName)} does not match ${cwd}`);
+  }
+
+  if (matches.length < 2) return matches[0];
+  const highestSpecificity = Math.max(...matches.map((entry) => globSpecificity(entry.glob)));
+  const mostSpecific = matches.filter(
+    (entry) => globSpecificity(entry.glob) === highestSpecificity,
+  );
+  if (mostSpecific.length > 1) {
+    throw new Error(
+      `ambiguous workspace for ${cwd}; choose one of: ${mostSpecific.map((entry) => entry.name).join(", ")}`,
+    );
+  }
+  return mostSpecific[0];
+};
+
 /** Match a cwd against the workspaces.json under an explicit config dir. */
 export const resolveWorkspaceFrom = (
   cwd: string,
@@ -440,23 +477,7 @@ export const resolveWorkspaceFrom = (
     }
     if (matched) matches.push(ws);
   }
-  if (workspaceName !== undefined) {
-    const selected = matches.find((ws) => ws.name === workspaceName);
-    if (!selected && matches.length > 0) {
-      const matchingNames = matches.map((ws) => ws.name);
-      throw new Error(
-        `workspace ${JSON.stringify(workspaceName)} does not match ${cwd}; matching choices: ${matchingNames.join(", ")}`,
-      );
-    }
-    if (selected) return selected;
-    throw new Error(`workspace ${JSON.stringify(workspaceName)} does not match ${cwd}`);
-  }
-  if (matches.length > 1) {
-    throw new Error(
-      `ambiguous workspace for ${cwd}; choose one of: ${matches.map((ws) => ws.name).join(", ")}`,
-    );
-  }
-  return matches[0] ?? null;
+  return selectWorkspaceMatch(matches, cwd, workspaceName) ?? null;
 };
 
 export const resolveWorkspace = (
@@ -560,22 +581,7 @@ const resolveRuntimeWorkspaceCandidate = (
     );
   });
   const workspaceName = process.env.WORKFLOW_WORKSPACE_NAME?.trim() || undefined;
-  let selected: RuntimeWorkspaceCandidate | undefined;
-  if (workspaceName) {
-    const named = matches.filter((entry) => entry.name === workspaceName);
-    if (named.length === 1) selected = named[0];
-    else if (named.length > 1)
-      throw new Error(`ambiguous workspace ${JSON.stringify(workspaceName)} for ${cwd}`);
-    else if (matches.length)
-      throw new Error(
-        `workspace ${JSON.stringify(workspaceName)} does not match ${cwd}; matching choices: ${matches.map((entry) => entry.name).join(", ")}`,
-      );
-    else throw new Error(`workspace ${JSON.stringify(workspaceName)} does not match ${cwd}`);
-  } else if (matches.length > 1)
-    throw new Error(
-      `ambiguous workspace for ${cwd}; choose one of: ${matches.map((entry) => entry.name).join(", ")}`,
-    );
-  else selected = matches[0];
+  const selected = selectWorkspaceMatch(matches, cwd, workspaceName);
   if (!selected) return null;
   const policy = runtimeWorkspacePolicySchema(kind).safeParse(selected);
   if (!policy.success) {

package/src/core/youtrack-tools.ts

@@ -103,7 +103,7 @@ type PostData = {
   loggedMinutes: number;
   outcome?: "unknown" | "not_applied";
   instructions?: string;
-  retry?: "workit_youtrack_post" | "workit_youtrack_log_time";
+  retry?: "youtrack.update" | "youtrack.time";
 };
 
 const notApplied = (value: LegacyValue): value is NotApplied =>
@@ -130,7 +130,7 @@ export async function postUpdate(
         postedComment: false,
         loggedMinutes: 0,
         outcome: "not_applied",
-        retry: "workit_youtrack_post",
+        retry: "youtrack.update",
       });
     unwrap(comment);
   } catch (error) {
@@ -158,7 +158,7 @@ export async function postUpdate(
           postedComment: true,
           loggedMinutes: 0,
           outcome: "not_applied",
-          retry: "workit_youtrack_log_time",
+          retry: "youtrack.time",
         });
       unwrap(time);
     } catch (error) {
@@ -191,7 +191,7 @@ export async function logTimeUpdate(
         issueId: input.issueId,
         loggedMinutes: 0,
         outcome: "not_applied",
-        retry: "workit_youtrack_log_time",
+        retry: "youtrack.time",
       });
     return ok(unwrap(value));
   } catch (error) {

package/src/core/youtrack.ts

@@ -846,7 +846,7 @@ export async function postUpdate(
         postedComment: true,
         loggedMinutes: 0,
         error: time.error,
-        retry: "workit_youtrack_log_time",
+        retry: "youtrack.time",
       };
     }
     return { ok: true, issueId, postedComment: true, loggedMinutes: minutes };

package/src/core.ts

@@ -124,6 +124,8 @@ export {
   externalActionRef,
   externalActionDescriptor,
   externalActionHelp,
+  externalActionJsonSchema,
+  externalActionSchema,
   planReservationLength,
   externalActionRequest,
   matchesNativeExternalAction,