@brainervirus/workit-core 0.6.0 → 0.7.0

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": false,
   "description": "Workit — workflow rails for agentic coding: specs, plans, YouTrack, CI-gated commits (shared core)",
-  "license": "MIT",
   "keywords": [
-    "opencode",
+    "agent",
     "cursor",
-    "workflow",
     "mcp",
-    "youTrack",
-    "agent"
+    "opencode",
+    "workflow",
+    "youTrack"
   ],
   "bugs": {
     "url": "https://github.com/BrainerVirus/workit/issues"
   },
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/BrainerVirus/workit.git"
@@ -27,24 +27,20 @@
     "vendor/superpowers/skills/",
     "templates/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "!scripts/verify-project.sh"
   ],
   "type": "module",
   "main": "./src/core.ts",
   "exports": {
-    "./src/tools": "./src/tools/index.ts",
     "./src/*.ts": "./src/*.ts",
     "./src/*": "./src/*.ts",
     "./package.json": "./package.json"
   },
-  "scripts": {
-    "typecheck": "tsc --noEmit"
-  },
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^3.24.0"
+  "scripts": {
+    "typecheck": "tsc --noEmit"
   }
 }

package/scripts/doctor-check.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env bun
+// DG-09: installers run the shared offline doctor after writing configuration and
+// return nonzero when a required registration/config check fails. `installer:
+// true` limits the enforced checks to the ones the installer just guaranteed, so
+// a dev/stub checkout without built assets does not fail a post-install run.
+import { runDoctor } from "../src/core/doctor";
+
+const host = process.argv[2] === "cursor" ? "cursor" : "opencode";
+const report = runDoctor({ host, installer: true });
+
+if (report.exitCode !== 0) {
+  for (const check of report.checks) {
+    if (check.status === "fail") {
+      process.stderr.write(`FATAL: workit doctor ${check.id}: ${check.detail}\n`);
+      if (check.fix) process.stderr.write(`  fix: ${check.fix}\n`);
+    }
+  }
+  process.exit(1);
+}
+process.exit(0);

package/scripts/install-cursor-plugin.sh

@@ -10,7 +10,8 @@ FROM_GITHUB=0
 LOCAL_ROOT=""
 if [ -n "${BASH_SOURCE[0]:-}" ] && [ -f "${BASH_SOURCE[0]}" ]; then
   SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
-  LOCAL_ROOT="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)"
+  # RR-05: LOCAL_ROOT is the checkout root (scripts live under <root>/packages/workit-core/scripts)
+  LOCAL_ROOT="$(CDPATH= cd -- "$SCRIPT_DIR/../../.." && pwd)"
 else
   FROM_GITHUB=1
 fi
@@ -33,7 +34,7 @@ if [ "$FROM_GITHUB" -eq 1 ]; then
     git -C "$SHARE" pull --ff-only origin main
   else
     rm -rf "$SHARE"
-    git clone --depth 1 "git@github.com:${REPO_SLUG}.git" "$SHARE"
+    git clone --depth 1 "https://github.com/${REPO_SLUG}.git" "$SHARE"
   fi
   ROOT="$SHARE"
 else
@@ -42,42 +43,64 @@ fi
 
 chmod +x "$ROOT/packages/workit-core/scripts/sync-runtime.sh" "$ROOT/packages/workit-core/scripts/"*.sh
 # Prefer syncing from this ROOT (dev or freshly cloned share)
-WORKFLOW_TOOLKIT_DEV="$ROOT" "$ROOT/packages/workit-core/scripts/sync-runtime.sh"
+export WORKFLOW_TOOLKIT_DEV="$ROOT"
+"$ROOT/packages/workit-core/scripts/sync-runtime.sh"
 
 # Drop stale CLI skill symlinks (duplicate /wf-* and /wk-* entries)
 if [ -d "$SKILLS_DIR" ]; then
   rm -f "$SKILLS_DIR"/wf-* "$SKILLS_DIR"/wk-*
 fi
 
-CURSOR_SETTINGS="$HOME/.cursor/settings.json" bun -e '
+PLUGIN_DIR="$HOME/.cursor/plugins/local/workflow-toolkit"
+REGISTRATION_TS="$ROOT/packages/workit-core/src/core/registration.ts"
+CURSOR_SETTINGS="$HOME/.cursor/settings.json" CURSOR_MCP="$HOME/.cursor/mcp.json" PLUGIN_DIR="$PLUGIN_DIR" REGISTRATION_TS="$REGISTRATION_TS" bun -e '
 import fs from "node:fs";
-import os from "node:os";
-const path = process.env.CURSOR_SETTINGS!;
-let data = {};
-if (fs.existsSync(path)) data = JSON.parse(fs.readFileSync(path, "utf8"));
-const prev = data.enabled_plugins && typeof data.enabled_plugins === "object" ? data.enabled_plugins : {};
-const plugin = `${os.homedir()}/.cursor/plugins/local/workflow-toolkit`;
-data.enabled_plugins = { ...prev, "workflow-toolkit": true, "local/workflow-toolkit": true };
-data.plugin_dirs = [plugin];
-fs.writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
-'
+import path from "node:path";
+const { mergeCursorSettings, mergeCursorMcp, mergeCursorHooks, cursorMcpServerEntry } =
+  await import(process.env.REGISTRATION_TS!);
 
-CURSOR_MCP="$HOME/.cursor/mcp.json" bun -e '
-import fs from "node:fs";
-const path = process.env.CURSOR_MCP!;
-const data = fs.existsSync(path) ? JSON.parse(fs.readFileSync(path, "utf8")) : { mcpServers: {} };
-data.mcpServers = data.mcpServers ?? {};
-data.mcpServers["workflow-toolkit"] = {
-  command: "bash",
-  args: [
-    "-lc",
-    "exec \"$HOME/.local/share/workflow-toolkit/packages/workit-core/scripts/run-cursor-mcp.sh\" \"$0\"",
-    "${workspaceFolder}",
-  ],
-};
-fs.writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
+// RR-06: collapse current + legacy identities; never replace unrelated settings.
+const settingsPath = process.env.CURSOR_SETTINGS!;
+const settings = fs.existsSync(settingsPath)
+  ? JSON.parse(fs.readFileSync(settingsPath, "utf8"))
+  : {};
+const merged = mergeCursorSettings(settings, process.env.PLUGIN_DIR!);
+fs.writeFileSync(settingsPath, JSON.stringify(merged.config, null, 2) + "\n");
+
+// RR-06: one portable workit MCP registration (node dist when present, bash
+// shim in a dist-less dev checkout); stale "workflow-toolkit" entries removed.
+const server = cursorMcpServerEntry(process.env.PLUGIN_DIR!);
+const mcpPath = process.env.CURSOR_MCP!;
+const mcp = fs.existsSync(mcpPath)
+  ? JSON.parse(fs.readFileSync(mcpPath, "utf8"))
+  : { mcpServers: {} };
+const mergedMcp = mergeCursorMcp(mcp, "workit", server);
+fs.writeFileSync(mcpPath, JSON.stringify(mergedMcp.config, null, 2) + "\n");
+
+// Keep the synced plugin manifests consistent with the current checkout state:
+// only in a dist-less dev checkout, point them at the shims so Cursor still
+// launches MCP/hooks (the shipped manifests already reference dist).
+const distMcp = path.join(process.env.PLUGIN_DIR!, "dist", "mcp-server.js");
+const pluginMcp = path.join(process.env.PLUGIN_DIR!, "mcp.json");
+if (!fs.existsSync(distMcp) && fs.existsSync(pluginMcp)) {
+  const inPkg = JSON.parse(fs.readFileSync(pluginMcp, "utf8"));
+  const patched = mergeCursorMcp(inPkg, "workit", server);
+  fs.writeFileSync(pluginMcp, JSON.stringify(patched.config, null, 2) + "\n");
+}
+const pluginHooks = path.join(process.env.PLUGIN_DIR!, "hooks", "hooks-cursor.json");
+if (!fs.existsSync(path.join(process.env.PLUGIN_DIR!, "dist", "cursor-session-start.js")) && fs.existsSync(pluginHooks)) {
+  const inPkg = JSON.parse(fs.readFileSync(pluginHooks, "utf8"));
+  const patched = mergeCursorHooks(inPkg, { command: "./hooks/session-start" });
+  fs.writeFileSync(pluginHooks, JSON.stringify(patched.config, null, 2) + "\n");
+}
 '
 
+# DG-09: verify the just-written Cursor registration with the shared offline doctor.
+if ! bun "$ROOT/packages/workit-core/scripts/doctor-check.ts" cursor; then
+  echo "FATAL: post-install doctor found an unhealthy Cursor registration" >&2
+  exit 1
+fi
+
 echo "Cursor plugin installed + auto-sync enabled (sessionStart)."
 echo "Share: $SHARE"
 ls "$HOME/.cursor/plugins/local/workflow-toolkit/skills" | grep '^wk-' || true

package/scripts/install-opencode-plugin.sh

@@ -3,14 +3,14 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
-ROOT="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)"
+ROOT="$(CDPATH= cd -- "$SCRIPT_DIR/../../.." && pwd)"
+CORE_SCRIPTS="$ROOT/packages/workit-core/scripts"
 SHARE="${HOME}/.local/share/workflow-toolkit"
-DEV_DEFAULT="${HOME}/Documents/projects/personal/workflow-toolkit"
-DEV="${WORKFLOW_TOOLKIT_DEV:-$DEV_DEFAULT}"
+DEV="${WORKFLOW_TOOLKIT_DEV:-$ROOT}"
 CONFIG="${HOME}/.config/opencode/opencode.json"
 
-chmod +x "$ROOT/scripts/sync-runtime.sh"
-WORKFLOW_TOOLKIT_DEV="$ROOT" "$ROOT/scripts/sync-runtime.sh"
+chmod +x "$CORE_SCRIPTS/sync-runtime.sh"
+WORKFLOW_TOOLKIT_DEV="$ROOT" "$CORE_SCRIPTS/sync-runtime.sh"
 
 # Prefer monorepo with .git. file:// pins skip opencode's bundled npm installer —
 # git+file:// installs an EMPTY cache dir and fails silently, so the plugin never
@@ -23,7 +23,10 @@ else
   # Last resort: ensure share is a clone, then pin it
   if [ ! -d "${SHARE}/.git" ]; then
     TMP=$(mktemp -d)
-    git clone --depth 1 "git@github.com:${WORKFLOW_TOOLKIT_REPO:-BrainerVirus/workit}.git" "$TMP"
+    if ! git clone --depth 1 "https://github.com/${WORKFLOW_TOOLKIT_REPO:-BrainerVirus/workit}.git" "$TMP"; then
+      echo "FATAL: could not clone https://github.com/${WORKFLOW_TOOLKIT_REPO:-BrainerVirus/workit}.git" >&2
+      exit 1
+    fi
     rsync -a --delete --exclude node_modules --exclude cursor/mcp/node_modules "$TMP/" "$SHARE/"
     rm -rf "$TMP"
   fi
@@ -33,24 +36,18 @@ fi
 mkdir -p "$(dirname "$CONFIG")"
 [ -f "$CONFIG" ] || printf '%s\n' "{}" >"$CONFIG"
 
-CONFIG_PATH="$CONFIG" PIN_PATH="$PIN" bun -e '
+# Merge/dedupe registrations via the shared core helper (RR-06): one dev pin,
+# no legacy/current duplicates, unrelated user settings preserved.
+CONFIG_PATH="$CONFIG" PIN_PATH="$PIN" REGISTRATION_TS="$ROOT/packages/workit-core/src/core/registration.ts" bun -e '
 import fs from "node:fs";
+const { mergeOpenCodeConfig } = await import(process.env.REGISTRATION_TS!);
 const path = process.env.CONFIG_PATH!;
-const pin = process.env.PIN_PATH!;
 const data = JSON.parse(fs.readFileSync(path, "utf8"));
-let plugins = data.plugin || [];
-if (typeof plugins === "string") plugins = [plugins];
-// Drop stale workflow-toolkit pins — the new file:// pin is written fresh.
-data.plugin = plugins.filter((p) => !String(p).includes("workflow-toolkit"));
-data.plugin.push(pin);
-// Drop share skills.paths — native ~/.config/opencode/skills links avoid triple-load dups
-const skills = data.skills;
-if (skills && typeof skills === "object") {
-  skills.paths = (skills.paths || []).filter((p) => !String(p).includes("workflow-toolkit"));
-  data.skills = skills;
-}
-fs.writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
-console.log("Pinned:", pin);
+const { config, changed } = mergeOpenCodeConfig(data, process.env.PIN_PATH!);
+fs.writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+console.log("Pinned:", process.env.PIN_PATH!);
+if (changed.includes("plugin")) console.log("Deduplicated Workit plugin entries");
+if (changed.includes("skills.paths")) console.log("Dropped share skill paths");
 console.log("Native skills/commands via ~/.config/opencode/{skills,commands}");
 '
 
@@ -73,4 +70,10 @@ if [ ! -s "$PLUGIN_ENTRY" ]; then
   exit 1
 fi
 
-echo "OpenCode install done. Fully quit all opencode processes, then restart."
+# DG-09: verify the just-written registration with the shared offline doctor.
+if ! bun "$ROOT/packages/workit-core/scripts/doctor-check.ts" opencode; then
+  echo "FATAL: post-install doctor found an unhealthy OpenCode registration" >&2
+  exit 1
+fi
+
+echo "OpenCode install done. Fully quit all opencode processes, then restart."

package/scripts/rewrite-workspace-deps.ts

@@ -1,21 +1,27 @@
 #!/usr/bin/env bun
-// Release-sync before publish: rewrite workspace:* core deps to ^<released
-// version> in the platform packages, and mirror the core version + canonical
-// URLs into the cursor plugin/marketplace manifests. Neither npm nor bun
-// rewrites workspace:*, so a packed tarball with it silently drops the core
-// dependency. Runs as semantic-release prepareCmd (after the version bumps,
-// before the npm publish phase); the writes stay in CI and never reach the
-// repo (semantic-release does not commit back).
+// Release-sync before publish: rewrite every internal workspace:* dependency to
+// ^<released version> in the platform packages, and mirror the core version +
+// canonical URLs into the cursor plugin/marketplace manifests. Neither npm nor
+// bun rewrites workspace:*, so a packed tarball with it silently drops the
+// dependency (RR-01/AR-03). Runs as semantic-release prepareCmd (after the
+// version bumps, before the npm publish phase); the writes stay in CI and never
+// reach the repo (semantic-release does not commit back).
 import { readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 const root = process.argv[2] ? resolve(process.argv[2]) : resolve(import.meta.dir, "..", "..", "..");
 const core = JSON.parse(readFileSync(resolve(root, "packages/workit-core/package.json"), "utf8"));
+if (!core.version || typeof core.version !== "string") {
+  throw new Error(`workit-core version missing in ${resolve(root, "packages/workit-core/package.json")}`);
+}
 for (const pkg of ["workit-opencode", "workit-cursor", "workit-cli"]) {
   const file = resolve(root, `packages/${pkg}/package.json`);
   const data = JSON.parse(readFileSync(file, "utf8"));
-  if (data.dependencies?.["@brainervirus/workit-core"] !== "workspace:*") continue;
-  data.dependencies["@brainervirus/workit-core"] = `^${core.version}`;
+  const deps = data.dependencies;
+  if (!deps) continue;
+  for (const name of Object.keys(deps)) {
+    if (name.startsWith("@brainervirus/")) deps[name] = `^${core.version}`;
+  }
   writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
 }
 for (const file of [

package/scripts/sync-runtime.sh

@@ -14,26 +14,87 @@ DEV="${WORKFLOW_TOOLKIT_DEV:-$DEV_DEFAULT}"
 REPO_SLUG="${WORKFLOW_TOOLKIT_REPO:-BrainerVirus/workit}"
 LOCK="${XDG_RUNTIME_DIR:-/tmp}/workflow-toolkit-sync.lock"
 
+# RR-05: missing required tools, an unacquirable lock, or a failed clone must
+# never look like a successful sync.
+if ! command -v flock >/dev/null 2>&1; then
+  echo "FATAL: sync-runtime requires flock (util-linux) — not found in PATH" >&2
+  exit 1
+fi
 exec 9>"$LOCK"
 if ! flock -n 9; then
-  exit 0
+  echo "sync-runtime: another process holds $LOCK — state unverified, failing" >&2
+  exit 1
 fi
 
 SRC=""
 if [ -f "${DEV}/packages/workit-opencode/src/plugin.ts" ] && [ -d "${DEV}/packages/workit-cursor/.cursor-plugin" ]; then
   SRC="$DEV"
 elif [ -d "${SHARE}/.git" ]; then
-  git -C "$SHARE" fetch --quiet origin 2>/dev/null || true
-  git -C "$SHARE" pull --ff-only --quiet origin main 2>/dev/null || true
+  # RR-05: a failed update of an existing share clone must not look like a
+  # successful sync — propagate fetch/pull failures to a FATAL nonzero exit.
+  if ! git -C "$SHARE" fetch --quiet origin; then
+    echo "FATAL: could not fetch updates for $SHARE" >&2
+    exit 1
+  fi
+  if ! git -C "$SHARE" pull --ff-only --quiet origin main; then
+    echo "FATAL: could not update $SHARE from origin/main" >&2
+    exit 1
+  fi
   SRC="$SHARE"
 elif [ ! -d "${SHARE}/packages/workit-core/src" ]; then
   mkdir -p "$(dirname "$SHARE")"
-  git clone --depth 1 "git@github.com:${REPO_SLUG}.git" "$SHARE" 2>/dev/null || exit 0
+  if ! git clone --depth 1 "https://github.com/${REPO_SLUG}.git" "$SHARE"; then
+    echo "FATAL: could not clone https://github.com/${REPO_SLUG}.git into $SHARE" >&2
+    exit 1
+  fi
   SRC="$SHARE"
 else
   SRC="$SHARE"
 fi
 
+CURSOR_SRC="$SRC/packages/workit-cursor"
+BUN_BIN=""
+if [ -n "${BUN:-}" ]; then
+  BUN_BIN="$BUN"
+  if [ ! -x "$BUN_BIN" ]; then
+    echo "FATAL: BUN is set but unusable: $BUN_BIN" >&2
+    exit 1
+  fi
+elif [ -x "$HOME/.bun/bin/bun" ]; then
+  BUN_BIN="$HOME/.bun/bin/bun"
+elif command -v bun >/dev/null 2>&1; then
+  BUN_BIN="$(command -v bun)"
+else
+  echo "FATAL: Bun is required to build the Cursor adapter" >&2
+  exit 1
+fi
+
+for DEP in @brainervirus/workit-core @modelcontextprotocol/sdk zod; do
+  if [ ! -e "$SRC/node_modules/$DEP" ]; then
+    if [ ! -f "$SRC/bun.lock" ]; then
+      echo "FATAL: dependency install requires $SRC/bun.lock" >&2
+      exit 1
+    fi
+    if ! (cd "$SRC" && "$BUN_BIN" install --frozen-lockfile); then
+      echo "FATAL: root dependency install failed in $SRC" >&2
+      exit 1
+    fi
+    break
+  fi
+done
+
+if ! (cd "$SRC" && PATH="$(dirname "$BUN_BIN"):$PATH" "$BUN_BIN" "$CURSOR_SRC/scripts/build.ts"); then
+  echo "FATAL: Cursor adapter build failed in $CURSOR_SRC" >&2
+  exit 1
+fi
+for ENTRY in mcp-server.js cursor-session-start.js; do
+  DIST_ENTRY="$CURSOR_SRC/dist/$ENTRY"
+  if [ ! -f "$DIST_ENTRY" ] || [ ! -s "$DIST_ENTRY" ] || [ "$(IFS= read -r LINE <"$DIST_ENTRY"; printf '%s' "$LINE")" != '#!/usr/bin/env node' ]; then
+    echo "FATAL: Cursor adapter invalid dist entry: $DIST_ENTRY" >&2
+    exit 1
+  fi
+done
+
 if [ "$SRC" != "$SHARE" ]; then
   mkdir -p "$SHARE"
   # Keep .git if share is a clone; never wipe it when syncing from the monorepo
@@ -51,15 +112,15 @@ mkdir -p "$PLUGIN_DIR"
 rsync -a --delete \
   --exclude 'mcp/node_modules' \
   "$SHARE/packages/workit-cursor/" "$PLUGIN_DIR/"
-# Vendored skills for Cursor (same folder layout as OpenCode registration)
-mkdir -p "$PLUGIN_DIR/vendor/superpowers"
-if [ -d "$SHARE/packages/workit-core/vendor/superpowers/skills" ]; then
-  rsync -a --delete "$SHARE/packages/workit-core/vendor/superpowers/skills" "$PLUGIN_DIR/vendor/superpowers/"
+
+if ! "$BUN_BIN" "$SHARE/packages/workit-core/src/core/skill-manifests.ts" "$PLUGIN_DIR"; then
+  echo "FATAL: Cursor skill validation failed: $PLUGIN_DIR" >&2
+  exit 1
 fi
 # Canonical user rules -> Cursor .mdc (compiled by the shared core)
 CONFIG_RULES_DIR="$(resolve_config_dir)/rules"
 if [ -d "$CONFIG_RULES_DIR" ]; then
-  "$HOME/.bun/bin/bun" -e "
+  "$BUN_BIN" -e "
     import('${SHARE}/packages/workit-core/src/core/rules.ts').then(async ({ writeCompiledCursorRules }) => {
       writeCompiledCursorRules('${PLUGIN_DIR}/rules');
     });
@@ -68,22 +129,13 @@ fi
 printf '%s\n' "$SHARE/packages/workit-core" >"$PLUGIN_DIR/.workflow-toolkit-root"
 chmod +x "$PLUGIN_DIR/hooks/session-start" "$PLUGIN_DIR/mcp/run-server.sh" 2>/dev/null || true
 
-if [ ! -d "$PLUGIN_DIR/mcp/node_modules" ]; then
-  (cd "$PLUGIN_DIR/mcp" && npm install --silent) || true
-fi
-
-# Share MCP also needs deps when launched via run-cursor-mcp fallback
-if [ ! -d "$SHARE/packages/workit-cursor/mcp/node_modules" ]; then
-  (cd "$SHARE/packages/workit-cursor/mcp" && npm install --silent) || true
-fi
-
 # Remove broken TLA live-loader if present (OpenCode ignored it; /wk-* vanished)
 rm -f "${OPENCODE_PLUGINS}/workflow-toolkit.ts"
 
 # Ensure OpenCode has plugin peer dep
 PKG="${HOME}/.config/opencode/package.json"
 if [ -f "$PKG" ]; then
-  PKG_PATH="$PKG" bun -e '
+  PKG_PATH="$PKG" "$BUN_BIN" -e '
 import fs from "node:fs";
 const path = process.env.PKG_PATH!;
 const data = JSON.parse(fs.readFileSync(path, "utf8"));

package/scripts/vendor-assets.ts

@@ -0,0 +1,37 @@
+import { cpSync, existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+const vendorFilter = (source: string): boolean => {
+  if (source.endsWith(".sh")) return false;
+  const stat = statSync(source);
+  return (
+    stat.isDirectory() ||
+    ((stat.mode & 0o111) === 0 && readFileSync(source).subarray(0, 2).toString("latin1") !== "#!")
+  );
+};
+
+export const copySanitizedVendor = (source: string, dest: string): void => {
+  cpSync(source, dest, { recursive: true, filter: vendorFilter });
+
+  const companion = path.join(dest, "brainstorming/visual-companion.md");
+  if (!existsSync(companion)) return;
+  let md = readFileSync(companion, "utf8");
+  const fromStart = md.indexOf("## Starting a Session");
+  const toLoop = md.indexOf("## The Loop", fromStart);
+  const fromCleanup = md.indexOf("## Cleaning Up");
+  const toReference = md.indexOf("## Reference", fromCleanup);
+  if (fromStart !== -1 && toLoop !== -1 && fromCleanup !== -1 && toReference !== -1) {
+    md =
+      md.slice(0, fromStart) +
+      "The packaged browser-companion runtime is not shipped with this package; its\n" +
+      "launcher scripts are excluded as vendored shell. Consult the upstream skill\n" +
+      "source for launch instructions.\n\n" +
+      md.slice(toLoop, fromCleanup) +
+      md.slice(toReference);
+  }
+  md = md.replace(
+    /If it has shut down, restart it with `start-server\.sh` using the \*\*same `--project-dir`\*\*[\s\S]*?you don't need to send a new URL\. /,
+    "",
+  );
+  writeFileSync(companion, md);
+};

package/skills/wk-implement/SKILL.md

@@ -16,11 +16,11 @@ The parent agent is coordinator-only. It must not edit product code or perform d
 4. Initialize native `todowrite` from returned tasks and mark ledger-completed task IDs completed.
 5. Call `workflow_resolve_branch`, then show the current branch, target branch, and stash behavior before any branch checkout/setup mutation.
 6. Always use native `question` before that mutation. For a clean tree, ask whether to proceed or cancel. For a dirty tree, add the stash choice and state what will be stashed; allow a custom answer.
-7. Call `workflow_branch_setup` with `confirmed: true` only after approval; never use worktrees.
+7. Call `workflow_branch_setup` with `confirmed: true` only after approval; never use worktrees. Flow-tool confirmations are never agent-typed booleans and never caller-supplied evidence: the plugin records your native-`question` answer as a host-observed one-use receipt (`attested: true`, `callID`, `selectedLabel`, `recordedAt`) consumed by the approval/menu tools — no evidence argument exists. Delegated worker status comes from host session parentage (`parentID`), never a caller `role` field.
 8. Report any setup failure stage or partial result; never infer success.
 9. Fill specs/plans from the quality templates: `templates/spec-template.md` for specs, `templates/plan-template.md` for plans. After `workflow_docs_validate`, surface the returned `quality` findings: hard findings (missing required section, missing CA-XX) block task start unless the user explicitly waives them; warnings are advisory.
 
-State lives only in tracked `docs/<slug>/sdd/<slug>/`. Never use an untracked or legacy SDD directory. Load the package-neutral execution contract by name, not an installation-specific path.
+Working state lives only in gitignored `docs/<slug>/sdd/` — never `.superpowers/sdd`, never an extra nested slug level. Load the package-neutral execution contract by name, not an installation-specific path.
 
 ## Per-task loop
 

package/skills/wk-pr/SKILL.md

@@ -16,7 +16,7 @@ disable-model-invocation: true
 
 ## GitHub issue linking
 
-When the resolved workspace is github with `link_on_pr` — `bash scripts/vcs/config.sh resolve` returns `issues_provider: "github"` and `link_on_pr: true` — and no issue is derivable (no `WORKFLOW_GH_ISSUE` env, no numeric branch id like `feature/42-title`, which auto-links without asking), ask with native `question` before creation, exactly three options:
+When the resolved workspace is github with `link_on_pr` — the `workflow_pr_context` tool's `vcs_config` returns `issues_provider: "github"` and `link_on_pr: true` — and no issue is derivable (no `WORKFLOW_GH_ISSUE` env, no numeric branch id like `feature/42-title`, which auto-links without asking), ask with native `question` before creation, exactly three options:
 
 1. **Use an existing issue** — the user provides the number (extract it from a URL if pasted); verify it exists with `gh issue view <n>` before proceeding.
 2. **Create a new issue** — via `gh issue create --title "<title>" --body "<body>"`; on success pass the returned number. Reuse the missing-CLI guard: if `gh` is not installed, surface the structured error with the install link and ask the user to confirm once installed.

package/src/core/boundary.ts

@@ -0,0 +1,27 @@
+import type { JsonValue } from "./logger";
+
+// Named diagnostic boundary events (DG-04) shared by all adapters so event
+// names stay consolidated across OpenCode, Cursor, and the CLI.
+export const EVENT = {
+  initialization: "initialization",
+  provenance: "provenance",
+  assets: "assets",
+  configurationSource: "configuration_source",
+  hooks: "hooks",
+  mcpConnection: "mcp_connection",
+  migration: "migration",
+  installSteps: "install_steps",
+  uncaughtFailure: "uncaught_failure",
+  toolsFailed: "tools_failed",
+  doctor: "doctor",
+} as const;
+
+// Safe error metadata for log events: name + message only. The message passes
+// through the logger's value redaction (tokens, key=value secrets, URL queries,
+// home prefixes); the raw stack never enters a context.
+export const errorDetail = (err: unknown): Record<string, JsonValue> => {
+  if (err instanceof Error) {
+    return { error_name: err.name, error: err.message };
+  }
+  return { error_name: "unknown", error: String(err) };
+};

package/src/core/branch-policy.ts

@@ -0,0 +1,63 @@
+import { spawnSync } from "node:child_process";
+import { PRESETS, type BranchPreset } from "./config";
+import type { IntegrationMode } from "./workspaces";
+
+const PREFIXES = {
+  feature: "feature/*",
+  bugfix: "bugfix/*",
+  release: "release/*",
+  hotfix: "hotfix/*",
+};
+
+export const detectBranchPolicy = (workspaceRoot: string) => {
+  const branchExists = (name: string): boolean => {
+    const r = spawnSync("git", ["branch", "--list", name], {
+      cwd: workspaceRoot,
+      encoding: "utf8",
+    });
+    return r.status === 0 && (r.stdout ?? "").trim() !== "";
+  };
+  const develop = branchExists("develop");
+  const main = branchExists("main");
+  const master = branchExists("master");
+  const root = main ? "main" : master ? "master" : null;
+
+  if (develop) {
+    return {
+      preset: "gitflow" as BranchPreset,
+      developBranch: "develop",
+      integration: "merge" as IntegrationMode,
+      protected: root ? [root, "develop"] : ["develop"],
+      allowed: [...PRESETS.gitflow.allowed],
+      prefixes: PREFIXES,
+    };
+  }
+  if (root === "main") {
+    return {
+      preset: "github-flow" as BranchPreset,
+      developBranch: null,
+      integration: "pr" as IntegrationMode,
+      protected: [root],
+      allowed: ["*"],
+      prefixes: PREFIXES,
+    };
+  }
+  if (root === "master") {
+    return {
+      preset: "trunk-based" as BranchPreset,
+      developBranch: null,
+      integration: "pr" as IntegrationMode,
+      protected: [root],
+      allowed: ["*"],
+      prefixes: PREFIXES,
+    };
+  }
+  return {
+    preset: "gitflow" as BranchPreset,
+    developBranch: null,
+    integration: "merge" as IntegrationMode,
+    protected: [],
+    allowed: [],
+    prefixes: PREFIXES,
+  };
+};