@brainervirus/workit-core 0.6.1 → 0.7.0

package/src/core/youtrack-tools.ts

@@ -0,0 +1,228 @@
+import { readFileSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fail, ok, type Result } from "../core";
+import { configDir, isConfigObject } from "./config";
+import {
+  context as legacyContext,
+  logTime as legacyLogTime,
+  parseDuration as legacyParseDuration,
+  postUpdate as legacyPostUpdate,
+  verifyYouTrackToken,
+} from "./youtrack";
+
+export const ISSUE_RE = /^[A-Z]+-\d+$/;
+export const message = (error: unknown) => (error instanceof Error ? error.message : String(error));
+
+// Both override names point at the config dir itself, same precedence as
+// src/core/config.ts and scripts/init/status.sh: WORKFLOW_TOOLKIT_CONFIG → WORKFLOW_TOOLKIT_CONFIG_DIR → XDG.
+// Default env (no args) routes through configDir() so the legacy migration runs.
+export const configPath = (env: NodeJS.ProcessEnv = process.env, home = os.homedir()) =>
+  path.join(
+    env === process.env
+      ? configDir()
+      : (env.WORKFLOW_TOOLKIT_CONFIG ??
+          env.WORKFLOW_TOOLKIT_CONFIG_DIR ??
+          path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "workit")),
+    "youtrack.json",
+  );
+
+export function readCredentials(env: NodeJS.ProcessEnv = process.env, home = os.homedir()) {
+  const resolvedConfig = configPath(env, home);
+  // AR-07/CA-37: a parseable non-object youtrack.json is malformed — exact-path
+  // error, never a raw TypeError or a silent tokenFile default.
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(resolvedConfig, "utf8"));
+  } catch {
+    throw new Error(`${resolvedConfig} is not valid JSON`);
+  }
+  if (!isConfigObject(parsed)) {
+    throw new Error(`${resolvedConfig} is not a JSON object`);
+  }
+  const config = parsed as { tokenFile?: string };
+  const tokenFile = config.tokenFile ?? "youtrack.token";
+  const tokenPath = path.resolve(path.dirname(resolvedConfig), tokenFile.replace(/^~(?=\/)/, home));
+  if (process.platform !== "win32" && (statSync(tokenPath).mode & 0o777) !== 0o600)
+    throw new Error("youtrack.token mode must be 0600");
+  const token = readFileSync(tokenPath, "utf8").trim();
+  if (!token) throw new Error("youtrack.token is empty");
+  return { configPath: resolvedConfig, token };
+}
+
+export const redact = (text: string, token: string) =>
+  token ? text.split(token).join("[REDACTED]") : text;
+
+type MaybePromise<T> = T | Promise<T>;
+export type LegacyValue = Record<string, unknown> | void;
+export type NotApplied = { ok: false; error: string; outcome: "not_applied" };
+
+export type YouTrackOperations = {
+  verifyToken(): MaybePromise<LegacyValue>;
+  context(input: Record<string, unknown>): MaybePromise<LegacyValue>;
+  parseDuration(text: string, workspaceRoot: string): MaybePromise<LegacyValue>;
+  postComment(issueId: string, markdown: string, workspaceRoot?: string): MaybePromise<LegacyValue>;
+  logTime(input: Record<string, unknown>): MaybePromise<LegacyValue>;
+};
+
+export const unwrap = (value: LegacyValue) => {
+  if (!value) return {};
+  if (value.error) throw new Error(String(value.error));
+  if (value.ok === false) throw new Error(String(value.error ?? "YouTrack operation failed"));
+  return (value.data as Record<string, unknown> | undefined) ?? value;
+};
+
+export const defaultOperations: YouTrackOperations = {
+  verifyToken: () => unwrap(verifyYouTrackToken()),
+  context: (input) => legacyContext(input as never),
+  parseDuration: (text, workspaceRoot) => legacyParseDuration(text, workspaceRoot),
+  postComment: async (issueId, markdown, workspaceRoot) =>
+    unwrap(
+      await legacyPostUpdate({
+        confirmed: true,
+        issueId,
+        markdown,
+        workspace_root: workspaceRoot,
+      } as never),
+    ),
+  logTime: async (input) => unwrap(await legacyLogTime(input as never)),
+};
+
+type PostInput = {
+  confirmed: boolean;
+  issueId: string;
+  markdown: string;
+  minutes?: number;
+  workspace_root?: string;
+};
+
+type PostData = {
+  issueId: string;
+  postedComment: boolean;
+  loggedMinutes: number;
+  outcome?: "unknown" | "not_applied";
+  instructions?: string;
+  retry?: "workflow_youtrack_post" | "workflow_youtrack_log_time";
+};
+
+const notApplied = (value: LegacyValue): value is NotApplied =>
+  value?.ok === false && value.outcome === "not_applied";
+
+export async function postUpdate(
+  input: PostInput,
+  operations: Pick<YouTrackOperations, "postComment" | "logTime"> = defaultOperations,
+): Promise<Result<PostData>> {
+  if (input.confirmed !== true) return fail("confirmed: true required");
+  if (!ISSUE_RE.test(input.issueId)) return fail("invalid issueId");
+  if (!input.markdown?.trim()) return fail("markdown required");
+  if (input.minutes != null && input.minutes <= 0) return fail("minutes must be positive");
+
+  try {
+    const comment = await operations.postComment(
+      input.issueId,
+      input.markdown,
+      input.workspace_root,
+    );
+    if (notApplied(comment))
+      return fail(comment.error, {
+        issueId: input.issueId,
+        postedComment: false,
+        loggedMinutes: 0,
+        outcome: "not_applied",
+        retry: "workflow_youtrack_post",
+      });
+    unwrap(comment);
+  } catch (error) {
+    return fail(message(error), {
+      issueId: input.issueId,
+      postedComment: false,
+      loggedMinutes: 0,
+      outcome: "unknown",
+      instructions: "Check YouTrack comments manually; do not retry while the outcome is unknown.",
+    });
+  }
+
+  if (input.minutes != null) {
+    try {
+      const time = await operations.logTime({
+        issueId: input.issueId,
+        minutes: input.minutes,
+        text: "workit update",
+        workspace_root: input.workspace_root,
+      });
+      if (notApplied(time))
+        return fail(time.error, {
+          issueId: input.issueId,
+          postedComment: true,
+          loggedMinutes: 0,
+          outcome: "not_applied",
+          retry: "workflow_youtrack_log_time",
+        });
+      unwrap(time);
+    } catch (error) {
+      return fail(message(error), {
+        issueId: input.issueId,
+        postedComment: true,
+        loggedMinutes: 0,
+        outcome: "unknown",
+        instructions:
+          "Check YouTrack time entries manually; do not retry while the outcome is unknown.",
+      });
+    }
+  }
+
+  return ok({
+    issueId: input.issueId,
+    postedComment: true,
+    loggedMinutes: input.minutes ?? 0,
+  });
+}
+
+export async function logTimeUpdate(
+  input: Record<string, unknown>,
+  operation: Pick<YouTrackOperations, "logTime"> = defaultOperations,
+): Promise<Result<Record<string, unknown>>> {
+  try {
+    const value = await operation.logTime(input);
+    if (notApplied(value))
+      return fail(value.error, {
+        issueId: input.issueId,
+        loggedMinutes: 0,
+        outcome: "not_applied",
+        retry: "workflow_youtrack_log_time",
+      });
+    return ok(unwrap(value));
+  } catch (error) {
+    return fail(message(error), {
+      issueId: input.issueId,
+      loggedMinutes: 0,
+      outcome: "unknown",
+      instructions:
+        "Check YouTrack time entries manually; do not retry while the outcome is unknown.",
+    });
+  }
+}
+
+export function normalizeContext(value: LegacyValue, mode?: string): LegacyValue {
+  if (!value || mode !== "meetings") return value;
+  const config = value.config as Record<string, unknown> | undefined;
+  const issue = String(config?.meetingIssue || "IRPT-12");
+  const { meetingIssues: _meetingIssues, ...singleMeetingConfig } = config ?? {};
+  const options = Array.isArray(value.meetingOptions)
+    ? (value.meetingOptions as Array<Record<string, unknown>>)
+    : [];
+  const selected = options.find((option) => option.issue === issue) ?? {
+    key: "general",
+    issue,
+    label: issue,
+    workItemText: "Reuniones",
+  };
+  return {
+    ...value,
+    config: singleMeetingConfig,
+    meetingOptions: [selected],
+    requiresMeetingChoice: false,
+    issueId: issue,
+    workItemText: selected.workItemText ?? "Reuniones",
+  };
+}

package/src/core/youtrack.ts

@@ -1,9 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
 import { readTemplate } from "./templates";
 import { resolveWorkspaceRoot } from "./scripts";
-import { configDir } from "./config";
+import { configDir, isConfigObject } from "./config";
 
 const ISSUE_RE = /^[A-Z]+-\d+$/;
 const TOKEN_PLACEHOLDER = "YOUR_TOKEN_HERE";
@@ -19,25 +18,45 @@ const youTrackTokenModeOk = (p: string): boolean => {
   return mode === 0o600;
 };
 
+// AR-07/CA-37: the shared shape rule applies here too — a parseable non-object
+// youtrack.json (null, scalar, array) is malformed with the exact path, never
+// missing/unconfigured, never silently defaulted.
 function readYouTrackConfig(
   required: boolean,
-): { config: Record<string, any>; path: string } | { error: string } {
+): { config: Record<string, any>; path: string } | { error: string; path: string } {
   const cfgPath = youTrackConfigPath();
   if (!fs.existsSync(cfgPath)) {
-    return required ? { error: "ERROR: missing youtrack.json" } : { config: {}, path: cfgPath };
+    return required
+      ? { error: "ERROR: missing youtrack.json", path: cfgPath }
+      : { config: {}, path: cfgPath };
   }
+  let parsed: unknown;
   try {
-    const config = JSON.parse(fs.readFileSync(cfgPath, "utf8")) as Record<string, any>;
-    return { config, path: cfgPath };
+    parsed = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
   } catch {
-    return { error: "invalid youtrack.json" };
+    return { error: `${cfgPath} is not valid JSON`, path: cfgPath };
   }
+  if (!isConfigObject(parsed)) {
+    return { error: `${cfgPath} is not a JSON object`, path: cfgPath };
+  }
+  return { config: parsed as Record<string, any>, path: cfgPath };
 }
 
+// RL-01: typed load result — malformed carries {ok:false, error, configPath}
+// mirroring vcsConfig, so risky consumers stop on the exact path.
+export type YouTrackConfigResult =
+  | { data: Record<string, any> }
+  | { error: string }
+  | { ok: false; error: string; configPath: string };
+
 /** Load + redact youtrack.json; validates the token file like youtrack/config.sh load. */
-export function youTrackConfigLoad(): { data: Record<string, any> } | { error: string } {
+export function youTrackConfigLoad(): YouTrackConfigResult {
   const loaded = readYouTrackConfig(true);
-  if ("error" in loaded) return loaded;
+  if ("error" in loaded) {
+    // RL-01: malformed (parse failure or non-object) fails closed with the exact
+    // path, mirroring vcsConfig's {ok:false,error,configPath} shape.
+    return { ok: false, error: loaded.error, configPath: loaded.path };
+  }
   const cfgPath = loaded.path;
   const tokenFile = String(loaded.config.tokenFile ?? "");
   const tokenPath = tokenFile
@@ -87,8 +106,23 @@ export function youTrackGreeting(configOverride?: string): {
   stderr: string;
 } {
   const cfgPath = configOverride ?? youTrackConfigPath();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+  } catch {
+    return {
+      stdout: "",
+      exitCode: 1,
+      stderr: fs.existsSync(cfgPath)
+        ? `${cfgPath} is not valid JSON`
+        : `missing youtrack.json: ${cfgPath}`,
+    };
+  }
+  if (!isConfigObject(parsed)) {
+    return { stdout: "", exitCode: 1, stderr: `${cfgPath} is not a JSON object` };
+  }
+  const config = parsed as Record<string, any>;
   try {
-    const config = JSON.parse(fs.readFileSync(cfgPath, "utf8")) as Record<string, any>;
     const tz = String(config.timezone ?? "America/Santiago");
     const now = new Date();
     const { y, m, d, hour, minute } = tzParts(now, tz);
@@ -134,11 +168,20 @@ export function youTrackWorkDateMs(
 ): { data: { dateMs: number; timezone: string; localDate: string } } | { error: string } {
   const cfgPath = youTrackConfigPath();
   let tz = "America/Santiago";
-  try {
-    const config = JSON.parse(fs.readFileSync(cfgPath, "utf8")) as Record<string, any>;
-    tz = String(config.timezone ?? "America/Santiago");
-  } catch {
-    /* defaults */
+  // Missing file is a legitimate unconfigured state (reader: "missing" keeps
+  // defaults); a parseable non-object is malformed and must propagate the
+  // exact-path error instead of silently defaulting the timezone.
+  if (fs.existsSync(cfgPath)) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+    } catch {
+      return { error: `${cfgPath} is not valid JSON` };
+    }
+    if (!isConfigObject(parsed)) {
+      return { error: `${cfgPath} is not a JSON object` };
+    }
+    tz = String((parsed as Record<string, any>).timezone ?? "America/Santiago");
   }
   const raw = dateRaw || "auto";
   try {
@@ -192,16 +235,38 @@ const youTrackToken = (): { token: string; base: string } | { error: string } =>
   return { token, base };
 };
 
-function youTrackCurl(args: string[]): { status: number; stdout: string; stderr: string } {
-  const result = spawnSync("curl", ["-fsS", ...args], { encoding: "utf8" });
-  return { status: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
+// fetch replaces the previous curl -fsS request helper: check res.ok,
+// surface HTTP errors without a token-bearing body, parse JSON on success.
+async function youTrackRequest(
+  url: string,
+  init: { method: string; token: string; body?: unknown },
+): Promise<{ status: number; stdout: string; stderr: string }> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${init.token}`,
+    Accept: "application/json",
+  };
+  let body: string | undefined;
+  if (init.body !== undefined) {
+    headers["Content-Type"] = "application/json";
+    body = JSON.stringify(init.body);
+  }
+  try {
+    const res = await fetch(url, { method: init.method, headers, body });
+    const text = await res.text();
+    if (!res.ok) {
+      return { status: res.status, stdout: "", stderr: text.slice(0, 200) };
+    }
+    return { status: 0, stdout: text, stderr: "" };
+  } catch (err) {
+    return { status: 1, stdout: "", stderr: err instanceof Error ? err.message : "network error" };
+  }
 }
 
 /** Port of scripts/youtrack/api.sh — log-time / post-comment with the WORKFLOW_YT_WRITE guard. */
-export function youTrackApi(
+export async function youTrackApi(
   args: string[],
   writeFlag = process.env.WORKFLOW_YT_WRITE ?? "",
-): { data: Record<string, any> } | { error: string } {
+): Promise<{ data: Record<string, any> } | { error: string }> {
   const cmd = args[0];
   if (cmd === "log-time" || cmd === "post-comment") {
     if (writeFlag !== "1") {
@@ -214,22 +279,20 @@ export function youTrackApi(
   const creds = youTrackToken();
   if ("error" in creds) return creds;
   const { token, base } = creds;
-  const auth = ["-H", `Authorization: Bearer ${token}`, "-H", "Accept: application/json"];
 
   if (cmd === "log-time") {
     const [issue, minutesRaw, text, dateArg] = args.slice(1);
     const minutes = Number(minutesRaw);
     const dateMs = youTrackWorkDateMs(dateArg ?? "auto");
     if ("error" in dateMs) return dateMs;
-    const body = JSON.stringify({ duration: { minutes }, text, date: dateMs.data.dateMs });
-    const out = youTrackCurl([
-      ...auth,
-      "-H",
-      "Content-Type: application/json",
-      "-d",
-      body,
+    const out = await youTrackRequest(
       `${base}/api/issues/${issue}/timeTracking/workItems?fields=id,idReadable`,
-    ]);
+      {
+        method: "POST",
+        token,
+        body: { duration: { minutes }, text, date: dateMs.data.dateMs },
+      },
+    );
     if (out.status !== 0) return { error: "YouTrack HTTP request failed" };
     try {
       const created = JSON.parse(out.stdout) as Record<string, any>;
@@ -248,15 +311,11 @@ export function youTrackApi(
   }
   if (cmd === "post-comment") {
     const [issue, text] = args.slice(1);
-    const body = JSON.stringify({ text });
-    const out = youTrackCurl([
-      ...auth,
-      "-H",
-      "Content-Type: application/json",
-      "-d",
-      body,
-      `${base}/api/issues/${issue}/comments`,
-    ]);
+    const out = await youTrackRequest(`${base}/api/issues/${issue}/comments`, {
+      method: "POST",
+      token,
+      body: { text },
+    });
     if (out.status !== 0) return { error: "YouTrack HTTP request failed" };
     return { data: { ok: true, issueId: issue } };
   }
@@ -264,26 +323,24 @@ export function youTrackApi(
 }
 
 /** Port of scripts/youtrack/verify-token.sh — read-only GET /api/users/me. */
-export function youTrackVerifyToken():
-  | { data: Record<string, any> }
-  | { error: string; http_status?: number; path?: string } {
+export async function youTrackVerifyToken(): Promise<
+  { data: Record<string, any> } | { error: string; http_status?: number; path?: string }
+> {
   const cfgPath = youTrackConfigPath();
   if (!fs.existsSync(cfgPath)) return { error: "missing youtrack.json" };
   const creds = youTrackToken();
   if ("error" in creds) return { error: creds.error };
   const { token, base } = creds;
 
-  const me = youTrackCurl([
-    "-H",
-    `Authorization: Bearer ${token}`,
-    "-H",
-    "Accept: application/json",
-    `${base}/api/users/me?fields=id,login,name,email`,
-  ]);
+  const me = await youTrackRequest(`${base}/api/users/me?fields=id,login,name,email`, {
+    method: "GET",
+    token,
+  });
   if (me.status !== 0) {
-    const body = me.stderr.trim() || me.stdout.trim();
     const err =
-      me.status === 22 ? "authentication failed (401/403)" : `HTTP error: ${body.slice(0, 200)}`;
+      me.status === 401 || me.status === 403
+        ? "authentication failed (401/403)"
+        : `HTTP error: ${me.stderr.slice(0, 200)}`;
     return { error: err, http_status: me.status };
   }
   let user: Record<string, any>;
@@ -304,13 +361,10 @@ export function youTrackVerifyToken():
   const meeting = readYouTrackConfig(false);
   const meetingIssue = "config" in meeting ? meeting.config.meetingIssue : undefined;
   if (meetingIssue) {
-    const issue = youTrackCurl([
-      "-H",
-      `Authorization: Bearer ${token}`,
-      "-H",
-      "Accept: application/json",
+    const issue = await youTrackRequest(
       `${base}/api/issues/${meetingIssue}?fields=id,idReadable,summary`,
-    ]);
+      { method: "GET", token },
+    );
     if (issue.status === 0) {
       try {
         const parsed = JSON.parse(issue.stdout) as Record<string, any>;
@@ -333,8 +387,10 @@ export function youTrackVerifyToken():
 export function youTrackTokenCreateUrl(): { data: Record<string, any> } {
   const tokenName = process.env.WORKFLOW_YT_TOKEN_NAME ?? "workit";
   const loaded = readYouTrackConfig(false);
-  const config = loaded && "config" in loaded ? loaded.config : {};
-  const cfgPath = loaded && "config" in loaded ? loaded.path : youTrackConfigPath();
+  if ("error" in loaded) {
+    return { data: { error: loaded.error } };
+  }
+  const config = loaded.config;
   const defaults = (config.tokenDefaults ?? {}) as Record<string, any>;
   const name = String(defaults.name ?? tokenName);
   const desc = String(
@@ -342,7 +398,9 @@ export function youTrackTokenCreateUrl(): { data: Record<string, any> } {
   );
   const scopes = Array.isArray(defaults.scopes) ? defaults.scopes : ["YouTrack"];
   const base = String(config.baseUrl ?? "https://enghouseamg.youtrack.cloud").replace(/\/+$/, "");
-  const tokenFile = String(config.tokenFile ?? path.join(path.dirname(cfgPath), "youtrack.token"));
+  const tokenFile = String(
+    config.tokenFile ?? path.join(path.dirname(loaded.path), "youtrack.token"),
+  );
   const tab = String(defaults.profileTab ?? "account-security");
   const createUrl = `${base}/users/me?${new URLSearchParams({ tab })}`;
   const docsUrl = "https://www.jetbrains.com/help/youtrack/cloud/manage-permanent-token.html";
@@ -394,7 +452,7 @@ export type YouTrackScripts = {
   config(): Record<string, any>;
   greeting(): { stdout: string; exitCode: number; stderr: string };
   parseDuration(text: string): Record<string, any>;
-  api(args: string[]): Record<string, any>;
+  api(args: string[]): Record<string, any> | Promise<Record<string, any>>;
 };
 
 const defaultScripts: YouTrackScripts = {
@@ -532,7 +590,7 @@ export function parseDuration(
   return out.data;
 }
 
-export function logTime(
+export async function logTime(
   {
     issueId,
     minutes,
@@ -549,13 +607,13 @@ export function logTime(
     workspace_root: string;
   },
   scripts: YouTrackScripts = defaultScripts,
-): Record<string, any> {
+): Promise<Record<string, any>> {
   if (!issueId || !ISSUE_RE.test(issueId)) return { error: "invalid issueId" };
   if (!minutes || minutes <= 0) return { error: "minutes must be positive" };
   const workText = text ?? "workit";
   const dateArg =
     dateMs != null ? String(dateMs) : date && /^\d+$/.test(String(date)) ? String(date) : "auto";
-  const out = scripts.api(["log-time", issueId, String(minutes), workText, dateArg]);
+  const out = await scripts.api(["log-time", issueId, String(minutes), workText, dateArg]);
   if (out.error) return { error: out.error };
   return { issueId, minutes, text: workText, ...out.data, ok: true };
 }
@@ -609,7 +667,7 @@ export function buildDraft({
   return { issueId, markdown };
 }
 
-export function postUpdate(
+export async function postUpdate(
   {
     confirmed,
     issueId,
@@ -624,7 +682,7 @@ export function postUpdate(
     workspace_root?: string;
   },
   operations?: Record<string, any>,
-): Record<string, any> {
+): Promise<Record<string, any>> {
   operations ??= {};
   if (!confirmed) return { error: "confirmed: true required" };
   if (!issueId || !ISSUE_RE.test(issueId)) return { error: "invalid issueId" };
@@ -635,11 +693,11 @@ export function postUpdate(
     ((id: string, text: string, _root: string) =>
       youTrackApi(["post-comment", id, text], process.env.WORKFLOW_YT_WRITE ?? ""));
   const logTimeOperation = operations.logTime ?? logTime;
-  const comment = postComment(issueId, markdown, workspace_root);
+  const comment = await postComment(issueId, markdown, workspace_root);
   if (comment.error) return { error: comment.error };
 
   if (minutes && minutes > 0) {
-    const time = logTimeOperation({
+    const time = await logTimeOperation({
       issueId,
       minutes,
       text: "workit update",

package/templates/execution-contract.md

@@ -9,16 +9,18 @@ Load `using-superpowers`, `subagent-driven-development`, `test-driven-developmen
 
 - The parent is coordinator-only: it does not edit product code or perform delegated exploration.
 - Never use a worktree. Branch changes are in-place through `workflow_branch_setup` on `feature/*` or `bugfix/*`; never commit on protected branches.
-- Tracked state, briefs, ledgers, and review diffs live only under `<SDD_DIR>` in `docs/<slug>/sdd/` and use `workflow_sdd_*` tools.
-- Use native `todowrite` for visible task state as well as the tracked ledger.
-- Use native `question` for branch/stash choices and guarded external mutations; call mutation tools only after approval with `confirmed: true`.
+- Working state, briefs, ledgers, and review diffs live only under gitignored `<SDD_DIR>` in `docs/<slug>/sdd/` and use `workflow_sdd_*` tools.
+- Use native `todowrite` for visible task state as well as the gitignored ledger.
+- Use native `question` for branch/stash choices and guarded external mutations; call mutation tools only after approval with `confirmed: true` (grounded in the recorded NativeChoiceEvidence).
+- Flow-tool confirmations are never agent-typed booleans and never caller-supplied evidence objects: on OpenCode the plugin records the user's native-`question` answer as a host-observed one-use receipt (`attested: true`, `callID`, `selectedLabel`, `recordedAt`) consumed by `workflow_spec_approve` / `workflow_plan_approve` / `workflow_plan_menu` — no evidence argument exists, and delegated worker status comes from host session parentage (`parentID`), never a caller `role` field. On Cursor, confirmations are policy-only (`attested: false`) and subagent-driven execution is rejected as unsupported.
+- On Cursor, for every repository-scoped `workflow_*` call, pass the active Cursor workspace as `workspace_root`; never rely on the MCP process default.
 - Use native `task` with only the built-in `explore` and `general` agents.
 
 ## Flow gates (HARD)
 
 - `wk-implement` refuses to run unless the plan is `approved` (flow.json) and the post-plan menu was presented.
 - `wk-handoff` refuses to run unless both spec and plan are `approved`.
-- Sequence is enforced by tools: `workflow_spec_approve` (×2), `workflow_plan_approve` (×2), `workflow_plan_menu` — never skip a step.
+- Sequence is enforced by tools: `workflow_spec_approve`, `workflow_plan_approve`, `workflow_plan_menu` — never skip a step (the spec/plan self-review runs automatically inside the transition; only the final approval asks for your confirmation).
 
 ## Setup
 
@@ -35,16 +37,16 @@ Load `using-superpowers`, `subagent-driven-development`, `test-driven-developmen
 For each top-level task absent from `completed_task_ids`:
 
 1. Mark it `in_progress` with `todowrite`.
-2. Create a tracked brief with `workflow_sdd_task_brief` and `confirmed: true`.
+2. Create a working-state brief with `workflow_sdd_task_brief` and `confirmed: true`.
 3. Delegate read-only discovery, when needed, to an `explore` agent. Delegate implementation to a fresh `general` agent. Product changes follow TDD.
-4. Create a tracked diff with `workflow_sdd_review_package` and `confirmed: true`.
+4. Create a working-state diff with `workflow_sdd_review_package` and `confirmed: true`.
 5. Delegate spec-compliance review and code-quality review to separate `general` agents.
 6. **Blocking** findings (Critical, Important, or spec-compliance) may trigger at most **two** fix+re-review rounds per task. **Advisory** findings (Minor, style, YAGNI, taste) never pause the loop — append them to `<SDD_DIR>/advisories.md`.
 7. Append the validated ledger entry with `workflow_sdd_append_progress` and `confirmed: true`; mark the todo completed.
 
 ## Final gate
 
-Run a separate full-branch code review, then `workflow_verify`. Present the full `<SDD_DIR>/advisories.md` roll-up once, then use native `question` so the user can choose which advisory items to fix, discuss, or discard. Report exact check results and never infer success. Use `workflow_git_context` for a commit preview and load `wk-commit` through `skill` for an approved commit. If tracked state contains a stash reference, preview reapplication through `question`, then call `workflow_branch_setup` with `confirmed: true` after approval.
+Run a separate full-branch code review, then `workflow_verify`. Present the full `<SDD_DIR>/advisories.md` roll-up once, then use native `question` so the user can choose which advisory items to fix, discuss, or discard. Report exact check results and never infer success. Use `workflow_git_context` for a commit preview and load `wk-commit` through `skill` for an approved commit. If working state contains a stash reference, preview reapplication through `question`, then call `workflow_branch_setup` with `confirmed: true` after approval.
 
 ## Task order
 

package/templates/superpowers-doc-contract.md

@@ -34,8 +34,9 @@ Before writing **Branch:** into a new spec or plan, call `workflow_docs_branch`
 - Implementation uses `wk-implement` and subagent-driven development, with native `todowrite` and `task`.
 - Commits use `wk-commit` after its native `question` confirmation.
 - Continuation uses `wk-handoff`, whose `workflow_handoff_session` creates and seeds the OpenCode session automatically.
-- Never use worktrees. Resolve the declared branch with `workflow_resolve_branch`, preview dirty-tree stash choices with `question`, and apply an approved in-place checkout through `workflow_branch_setup` with `confirmed: true`.
-- Keep all SDD state tracked under `docs/<slug>/sdd/`; use `workflow_sdd_context` and the registered `workflow_sdd_*` tools.
+- Never use worktrees. Resolve the declared branch with `workflow_resolve_branch`, preview dirty-tree stash choices with `question`, and apply an approved in-place checkout through `workflow_branch_setup` with `confirmed: true` (grounded in the recorded NativeChoiceEvidence).
+- Flow-tool confirmations are never agent-typed booleans and never caller-supplied evidence objects: on OpenCode the plugin records the user's native-`question` answer as a host-observed one-use receipt (`attested: true`, `callID`, `selectedLabel`, `recordedAt`) consumed by `workflow_spec_approve` / `workflow_plan_approve` / `workflow_plan_menu` — no evidence argument exists, and delegated worker status comes from host session parentage (`parentID`), never a caller `role` field. On Cursor, confirmations are policy-only (`attested: false`) and subagent-driven execution is rejected as unsupported.
+- Keep all SDD state under the gitignored `docs/<slug>/sdd/`; use `workflow_sdd_context` and the registered `workflow_sdd_*` tools.
 - After implementation, use `question` before an approved stash reapply through `workflow_branch_setup` with `confirmed: true`.
 
 ## YouTrack content
@@ -46,7 +47,7 @@ Chat follows the user's language. YouTrack task comments are Spanish (`es-CL`) a
 
 Before handoff, call `workflow_docs_validate` on the linked spec/plan pair. Hard-fail on any error; never offer execution when validation fails.
 
-Before handoff, verify the saved spec path, plan path, declared branch, top-level task numbering, and tracked SDD directory through the registered read-only workflow tools. Report structured failures; never infer success.
+Before handoff, verify the saved spec path, plan path, declared branch, top-level task numbering, and workflow-managed SDD directory through the registered read-only workflow tools. Report structured failures; never infer success.
 
 ## Post-plan execution choice