@brainervirus/workit-core 1.0.9 → 1.0.11

package/package.json

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

package/skills/workit-plan/SKILL.md

@@ -22,9 +22,21 @@ selects requirements; do not wait for a rule that can only exist after assess.
    needed, owner, and next action. Keep the plan against the existing system.
 3. If policy separately requires a durable specification, record that behavior
    agreement; otherwise do not invent a spec. A plan without a spec is valid.
-4. Update the shared task progress at meaningful boundaries. Reassess when facts,
+4. Present before asking: show durable artifacts as a complete digest plus the
+   exact path and inline plans as their content. Never ask the user to approve
+   something they have not seen, and keep the question to one short scoped
+   sentence.
+5. Execute an approved plan continuously: one atomic commit per task after its
+   checks pass, no "continue?" prompts. Stop only for a new product decision, a
+   failed safety or verification gate, a conflicting concurrent edit, or missing
+   authority.
+6. 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 runs
+   without a new question; an unlisted message, a branch change, or any change to
+   the plan needs a fresh exact approval.
+7. Update the shared task progress at meaningful boundaries. Reassess when facts,
    dependencies, or scope change; preserve unresolved blockers and decisions.
-5. On steering (new instructions mid-task): apply `workit-steer` — park state
+8. On steering (new instructions mid-task): apply `workit-steer` — park state
    verbatim, classify same-task / new-task / quick-question, handle, re-anchor.
 
 Use shared task/progress and evidence operations. Do not create a universal

package/src/core/authority.ts

@@ -432,7 +432,15 @@ export const verifyDecisionContentAtRoot = (
       return failure("invalid_input", "document references require a byte digest");
     const target = path.resolve(root, reference.path);
     if (target !== root && !target.startsWith(`${root}${path.sep}`))
-      return failure("invalid_input", "document reference escapes checkout");
+      return failure(
+        "invalid_input",
+        "document reference escapes checkout; cite it as an external file:// reference instead",
+        {
+          fields: [
+            { path: "contentRefs.path", reason: `${reference.path} is outside the checkout` },
+          ],
+        },
+      );
     try {
       const relative = path.relative(root, target);
       let current = root;
@@ -442,7 +450,18 @@ export const verifyDecisionContentAtRoot = (
         const stat = fs.lstatSync(current);
         const real = fs.realpathSync(current);
         if (real !== root && !real.startsWith(`${root}${path.sep}`))
-          return failure("invalid_input", "document reference escapes checkout");
+          return failure(
+            "invalid_input",
+            "document reference escapes checkout; cite it as an external file:// reference instead",
+            {
+              fields: [
+                {
+                  path: "contentRefs.path",
+                  reason: `${reference.path} resolves outside the checkout`,
+                },
+              ],
+            },
+          );
         if (stat.isSymbolicLink())
           return failure("invalid_input", "document reference uses a symlink");
         if (current === target && !stat.isFile())

package/src/core/branch.ts

@@ -268,6 +268,18 @@ export const ensureBaseBranch = (cwd: string, base: string): { ok: boolean; erro
   return fastForwardBase(cwd, base);
 };
 
+export type BranchSetupResult =
+  | {
+      action: "setup";
+      ok: true;
+      branch: string;
+      previous_branch: string;
+      stash_ref: string | null;
+      manifest: string;
+    }
+  | { action: "reapply_stash"; ok: true }
+  | { error: string; phase: "preflight" | "post_mutation" };
+
 // Port of scripts/branch/setup-branch.sh
 export const branchSetup = ({
   action,
@@ -283,12 +295,13 @@ export const branchSetup = ({
   stash?: string;
   workspace_root: string;
   log?: (message: string) => void;
-}) => {
+}): BranchSetupResult => {
   const cwd = path.resolve(workspace_root);
   const exec = (args: string[]): string =>
     execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
   const current = gitContext(cwd).branch;
-  if (!current || current === "unknown") return { error: "not in a git repository" };
+  if (!current || current === "unknown")
+    return { error: "not in a git repository", phase: "preflight" };
   const sdd = sdd_dir ?? "docs";
   const manifestPath = path.isAbsolute(sdd)
     ? path.join(sdd, "manifest.json")
@@ -297,7 +310,6 @@ export const branchSetup = ({
     const dir = path.dirname(manifestPath);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o755 });
   };
-  ensureManifestDir();
   const readManifest = (): Record<string, unknown> => {
     try {
       return JSON.parse(readFileSync(manifestPath, "utf8"));
@@ -315,13 +327,16 @@ export const branchSetup = ({
   if (action === "reapply_stash") {
     const manifest = readManifest();
     const ref = manifest.stash_ref;
-    if (!ref) return { error: "no stash_ref in manifest" };
+    if (!ref) return { error: "no stash_ref in manifest", phase: "preflight" };
     journal(`pre-pop: ${String(ref)}`);
     try {
       exec(["stash", "pop", String(ref)]);
     } catch (error) {
       journal("pop: failed");
-      return { error: error instanceof Error ? error.message : "stash pop failed" };
+      return {
+        error: error instanceof Error ? error.message : "stash pop failed",
+        phase: "post_mutation",
+      };
     }
     journal("pop: ok");
     delete manifest.stash_ref;
@@ -331,10 +346,17 @@ export const branchSetup = ({
   }
 
   const target = target_branch ?? "";
-  if (!target) return { error: "target branch required" };
-  if (isProtected(cwd, target)) return { error: `protected branch ${target}` };
+  if (!target)
+    return {
+      error: "target_branch (the working branch to create or switch to) is required for setup",
+      phase: "preflight",
+    };
+  if (isProtected(cwd, target)) return { error: `protected branch ${target}`, phase: "preflight" };
   if (!allowedBranch(cwd, target))
-    return { error: `target branch ${target} is not allowed by the branch policy` };
+    return {
+      error: `target branch ${target} is not allowed by the branch policy`,
+      phase: "preflight",
+    };
 
   // CA-02: resolve the base up front so an unresolvable base fails before
   // any mutation. The origin/<base> validation runs after the stash gate
@@ -348,7 +370,7 @@ export const branchSetup = ({
   }
   if (!targetExists) {
     const baseResolved = baseBranch(cwd);
-    if ("error" in baseResolved) return { error: baseResolved.error };
+    if ("error" in baseResolved) return { error: baseResolved.error, phase: "preflight" };
     base = baseResolved.base;
   }
   journal(`entry: current=${current} target=${target} base=${base ?? "-"}`);
@@ -356,7 +378,10 @@ export const branchSetup = ({
   let stash_ref: string | undefined;
   // Best-effort restore; if the pop itself fails, the caller's error gains a
   // suffix pointing at the stash so stranded work stays discoverable.
-  const failAfterStash = (message: string): { error: string } => {
+  const failAfterStash = (
+    message: string,
+    phase: "preflight" | "post_mutation" = "post_mutation",
+  ): { error: string; phase: "preflight" | "post_mutation" } => {
     let suffix = "";
     if (stash_ref) {
       journal(`pre-pop: ${stash_ref}`);
@@ -369,7 +394,7 @@ export const branchSetup = ({
         suffix = " (changes preserved in stash)";
       }
     }
-    return { error: `${message}${suffix}` };
+    return { error: `${message}${suffix}`, phase: stash_ref ? "post_mutation" : phase };
   };
   if (current !== target) {
     const dirty = Boolean(gitContext(cwd).status_short.trim());
@@ -377,6 +402,7 @@ export const branchSetup = ({
       return {
         error:
           "dirty working tree — ask with native question, then call workit_branch_setup with stash=yes",
+        phase: "preflight",
       };
     }
     // CA-02: validate origin/<base> before ANY mutation (no snapshot, no
@@ -386,14 +412,18 @@ export const branchSetup = ({
     let validatedBase: string | undefined;
     if (!targetExists && base !== undefined) {
       const ready = originBaseReady(cwd, base);
-      if (!ready.ok) return { error: ready.error ?? "ensure-base-branch failed" };
+      if (!ready.ok)
+        return { error: ready.error ?? "ensure-base-branch failed", phase: "preflight" };
       validatedBase = base;
     }
     if (dirty) {
       try {
         exec(["stash", "push", "-u", "-m", `workit: pre-checkout ${target}`]);
       } catch (error) {
-        return { error: error instanceof Error ? error.message : "stash push failed" };
+        return {
+          error: error instanceof Error ? error.message : "stash push failed",
+          phase: "post_mutation",
+        };
       }
       stash_ref = "stash@{0}";
       journal(`stash push: ${stash_ref}`);
@@ -406,13 +436,14 @@ export const branchSetup = ({
       if (/worktree/i.test(message)) {
         return failAfterStash(
           `branch ${target} is locked by an existing git worktree — remove it first (we do not use worktrees)`,
+          "preflight",
         );
       }
       try {
         let effectiveBase = base;
         if (effectiveBase === undefined) {
           const lateResolved = baseBranch(cwd);
-          if ("error" in lateResolved) return failAfterStash(lateResolved.error);
+          if ("error" in lateResolved) return failAfterStash(lateResolved.error, "preflight");
           effectiveBase = lateResolved.base;
         }
         // Pre-validated above when the target was missing: only the

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

@@ -236,6 +236,125 @@ const safePath = (root: string, value: string): string | null => {
   }
 };
 
+/** Read-only baseline bound into a branch-setup proposal: the exact remote
+ * commit the base currently points at, without moving any local ref. */
+const branchCreationBaseline = (
+  root: string,
+  target: string,
+  base: string,
+): { base_branch: string; target_exists: boolean; remote_base: string | null } => {
+  const exists =
+    gitValue(root, ["rev-parse", "--verify", "--quiet", `refs/heads/${target}`]) !== null;
+  if (exists) return { base_branch: base, target_exists: true, remote_base: null };
+  const remote = run(root, ["ls-remote", "origin", `refs/heads/${base}`]);
+  const sha = remote.exitCode === 0 ? remote.stdout.trim().split(/\s+/)[0] : "";
+  return {
+    base_branch: base,
+    target_exists: false,
+    remote_base: /^[0-9a-f]{40}$/.test(sha ?? "") ? (sha as string) : null,
+  };
+};
+
+const shortSha = (value: unknown): string =>
+  typeof value === "string" && value ? value.slice(0, 8) : "unknown";
+
+const isProtectedBranch = (root: string, branch: string): boolean =>
+  resolveBranchPolicyFor(root).protected.has(branch.toLowerCase());
+
+/** Concise, user-facing approval text for one resolved action. The exact
+ * descriptor stays machine-facing; this is what the native question shows. */
+export const actionProposalQuestion = (
+  request: ExternalActionRequest,
+  descriptorPayload: unknown,
+): { presented: string; approvedText: string } => {
+  const payload = (descriptorPayload ?? {}) as Record<string, unknown>;
+  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[];
+    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.`,
+    };
+  }
+  switch (request.operation) {
+    case "git.branch_setup": {
+      if (request.payload.action === "reapply_stash")
+        return {
+          presented:
+            "Workit decision: action — Reapply the pre-checkout stash recorded in the branch manifest?",
+          approvedText: "Reapply the recorded stash.",
+        };
+      const target = String(payload.target_branch ?? "");
+      // A dirty tree binds stash: the approval carries the stash through,
+      // so the question names it instead of failing later at preflight.
+      const stashes = payload.stash === "yes" && resolved.dirty === true;
+      if (resolved.target_exists === true)
+        return stashes
+          ? {
+              presented: `Workit decision: action — Stash the dirty working tree and switch to branch \`${target}\`?`,
+              approvedText: `Stash and switch to \`${target}\`.`,
+            }
+          : {
+              presented: `Workit decision: action — Switch to branch \`${target}\`?`,
+              approvedText: `Switch to \`${target}\`.`,
+            };
+      const base = String(resolved.base_branch ?? "the base branch");
+      return stashes
+        ? {
+            presented: `Workit decision: action — Stash the dirty working tree and create branch \`${target}\` from \`${base}\` (currently ${shortSha(resolved.remote_base)})?`,
+            approvedText: `Stash and create \`${target}\` from \`${base}\` at ${shortSha(resolved.remote_base)}.`,
+          }
+        : {
+            presented: `Workit decision: action — Create branch \`${target}\` from \`${base}\` (currently ${shortSha(resolved.remote_base)})?`,
+            approvedText: `Create \`${target}\` from \`${base}\` at ${shortSha(resolved.remote_base)}.`,
+          };
+    }
+    case "git.commit": {
+      const paths = Array.isArray(resolved.paths) ? (resolved.paths as string[]) : [];
+      return {
+        presented: `Workit decision: action — Commit ${paths.length} staged file(s) as "${String(request.payload.message)}"?`,
+        approvedText: `Commit as "${String(request.payload.message)}".`,
+      };
+    }
+    case "git.push":
+      return {
+        presented: `Workit decision: action — Push branch \`${String(payload.branch ?? "")}\` to origin?`,
+        approvedText: `Push \`${String(payload.branch ?? "")}\` to origin.`,
+      };
+    case "hosting.pull_request":
+      return {
+        presented: `Workit decision: action — Open a PR from \`${String(resolved.source_branch ?? "")}\` to \`${payloadTarget}\` titled "${String(request.payload.title)}"?`,
+        approvedText: `Open the PR: ${String(resolved.source_branch ?? "")} → ${payloadTarget}, "${String(request.payload.title)}".`,
+      };
+    case "changelog.apply":
+      return {
+        presented: `Workit decision: action — Apply changelog changes at \`${String(payload.path ?? "CHANGELOG.md")}\`?`,
+        approvedText: `Apply changelog changes at ${String(payload.path ?? "CHANGELOG.md")}.`,
+      };
+    case "youtrack.update":
+      return {
+        presented: `Workit decision: action — Update YouTrack issue ${String(request.payload.issueId)}${request.payload.minutes ? ` and log ${String(request.payload.minutes)}m` : ""}?`,
+        approvedText: `Update YouTrack issue ${String(request.payload.issueId)}.`,
+      };
+    case "youtrack.time":
+      return {
+        presented: `Workit decision: action — Log ${String(request.payload.minutes)}m to YouTrack issue ${String(request.payload.issueId)}?`,
+        approvedText: `Log time to YouTrack issue ${String(request.payload.issueId)}.`,
+      };
+    case "youtrack.meeting":
+      return {
+        presented: `Workit decision: action — Log meeting time to YouTrack issue ${String(request.payload.issueId)}?`,
+        approvedText: `Log meeting time to YouTrack issue ${String(request.payload.issueId)}.`,
+      };
+    default:
+      return {
+        presented: `Workit decision: action — Approve ${request.operation}?`,
+        approvedText: `Approve ${request.operation}.`,
+      };
+  }
+};
+
 export type ResolvedExternalAction = {
   request: ExternalActionRequest;
   descriptorPayload: unknown;
@@ -697,23 +816,41 @@ export const resolveExternalActionRequest = (
       case "git.branch_setup": {
         const sdd_dir = safePath(root, request.payload.sdd_dir ?? "docs");
         if (!sdd_dir) return failure("invalid_input", "sdd_dir must stay inside the workspace");
+        const action = request.payload.action ?? "setup";
         const policy = resolveBranchPolicyFor(root);
-        const target_branch = request.payload.target_branch ?? policy.defaultTargetBranch;
+        const target_branch = request.payload.target_branch;
+        if (action !== "reapply_stash" && !target_branch)
+          return failure(
+            "invalid_input",
+            "target_branch (the working branch to create or switch to) is required for setup",
+            {
+              outcome: "not_started",
+              fields: [{ path: "target_branch", reason: "required for action=setup" }],
+            },
+          );
         const head = gitValue(root, ["rev-parse", "HEAD"]);
         if (!head) return failure("storage_error", "current Git commit could not be resolved");
+        const dirty = Boolean((gitRaw(root, ["status", "--short"]) ?? "").trim());
+        const creation =
+          action === "reapply_stash" || !target_branch
+            ? { base_branch: policy.defaultTargetBranch }
+            : branchCreationBaseline(root, target_branch, policy.defaultTargetBranch);
         const normalized = {
           operation: request.operation,
           payload: {
             ...request.payload,
-            action: request.payload.action ?? "setup",
+            action,
             sdd_dir,
             stash: request.payload.stash ?? "no",
-            target_branch,
+            ...(target_branch ? { target_branch } : {}),
           },
         } as ExternalActionRequest;
         return success(null, null, {
           request: normalized,
-          descriptorPayload: { ...normalized.payload, resolved: { head, target_branch } },
+          descriptorPayload: {
+            ...normalized.payload,
+            resolved: { head, dirty, ...creation },
+          },
         });
       }
       case "git.push": {
@@ -729,7 +866,46 @@ export const resolveExternalActionRequest = (
           : failure("invalid_input", "git push requires a resolvable current branch");
       }
       case "git.commit": {
+        const planSteps = request.payload.plan_steps;
+        const planBranch = request.payload.plan_branch;
         const head = gitValue(root, ["rev-parse", "HEAD"]);
+        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
+          )
+            return failure(
+              "invalid_input",
+              "plan_steps must be 1-32 unique non-empty commit messages",
+              {
+                outcome: "not_started",
+                fields: [{ path: "plan_steps", reason: "unique strings" }],
+              },
+            );
+          if (typeof planBranch !== "string" || !planBranch.trim() || planBranch !== branch)
+            return failure("invalid_input", "plan_branch must name the current working branch", {
+              outcome: "not_started",
+              fields: [{ path: "plan_branch", reason: "current branch" }],
+            });
+          if (isProtectedBranch(root, planBranch))
+            return failure("invalid_input", "plan_branch must not be a protected branch", {
+              outcome: "not_started",
+              fields: [{ path: "plan_branch", reason: "protected branch" }],
+            });
+          return success(null, null, {
+            request,
+            descriptorPayload: {
+              plan_steps: planSteps,
+              plan_branch: planBranch,
+              resolved: { head, branch, steps: planSteps },
+            },
+          });
+        }
         const staged = gitRaw(root, [
           "diff",
           "--cached",
@@ -740,7 +916,13 @@ export const resolveExternalActionRequest = (
           "HEAD",
         ]);
         const paths = stagedPaths(root);
-        if (!head || staged === null || paths === null)
+        const message = request.payload.message;
+        if (typeof message !== "string" || !message)
+          return failure("invalid_input", "git.commit requires a commit message", {
+            outcome: "not_started",
+            fields: [{ path: "message", reason: "required unless plan_steps is provided" }],
+          });
+        if (staged === null || paths === null)
           return failure("storage_error", "Git state could not be resolved");
         let policy: { preset: string; pattern?: string };
         try {
@@ -757,7 +939,7 @@ export const resolveExternalActionRequest = (
           const detected = detectCommitFlavor((log ?? "").split("\n").filter(Boolean));
           flavor = detected.flavor ?? "conventional";
         }
-        if (!matchCommitFlavor(request.payload.message, flavor as CommitFlavor, policy.pattern))
+        if (!matchCommitFlavor(message, flavor as CommitFlavor, policy.pattern))
           return failure(
             "invalid_input",
             `Commit message does not match the ${flavor} flavor (commitPolicy.preset)`,
@@ -766,7 +948,7 @@ export const resolveExternalActionRequest = (
           request,
           descriptorPayload: {
             ...request.payload,
-            resolved: { head, staged: sha256(staged), paths },
+            resolved: { head, branch, staged: sha256(staged), paths },
           },
         });
       }
@@ -985,10 +1167,24 @@ export const executeConcreteExternalAction = async (
         sdd_dir: request.payload.sdd_dir ?? "docs",
         workspace_root: root,
       });
-      return result.error ? unknown(request.operation) : success(null, null, result);
+      if ("error" in result) {
+        if (result.phase === "preflight")
+          return failure("invalid_input", result.error, {
+            outcome: "not_started",
+            operation: request.operation,
+          });
+        return unknown(request.operation);
+      }
+      return success(null, null, result);
     }
     case "git.commit": {
-      const result = run(root, ["commit", "-m", request.payload.message]);
+      const message = request.payload.message;
+      if (typeof message !== "string" || !message)
+        return failure("invalid_input", "git.commit requires a commit message", {
+          outcome: "not_started",
+          fields: [{ path: "message", reason: "required" }],
+        });
+      const result = run(root, ["commit", "-m", message]);
       return result.exitCode === 0
         ? success(null, null, { stdout: result.stdout.trim() })
         : unknown(request.operation);