bigpowers 2.87.7 → 2.88.0

package/scripts/omp-smoke.ts

@@ -0,0 +1,82 @@
+// story: e82s03
+// Runtime smoke for extensions/omp-hooks.ts.
+// Imports the extension, registers a fake ExtensionAPI, calls registered hooks,
+// and asserts the slash-command handler awaits injection.
+
+import bigpowers from "../extensions/omp-hooks.ts";
+
+type AnyObj = Record<string, unknown>;
+type Listener = (...args: unknown[]) => unknown;
+
+function makeZod(): AnyObj {
+  const chainable: AnyObj = {};
+  chainable.optional = () => chainable;
+  chainable.describe = () => chainable;
+  return chainable;
+}
+
+const commands = new Map<string, { description: string; handler: Listener }>();
+const tools: AnyObj[] = [];
+const events = new Map<string, Listener>();
+const sendCalls: AnyObj[] = [];
+
+const pi: AnyObj = {
+  setLabel: () => {},
+  zod: {
+    object: (_shape: AnyObj) => makeZod(),
+    string: () => makeZod(),
+    enum: () => makeZod(),
+  },
+  registerCommand: (name: string, spec: { description: string; handler: Listener }) => {
+    commands.set(name, spec);
+  },
+  registerTool: (tool: AnyObj) => {
+    tools.push(tool);
+  },
+  on: (event: string, handler: Listener) => {
+    events.set(event, handler);
+  },
+  sendUserMessage: async (content: string, opts?: { deliverAs?: string }) => {
+    sendCalls.push({ kind: "sendUserMessage", content, opts });
+    return undefined;
+  },
+  sendMessage: async (msg: AnyObj, opts?: { triggerTurn?: boolean; deliverAs?: string }) => {
+    sendCalls.push({ kind: "sendMessage", msg, opts });
+    return undefined;
+  },
+};
+
+await bigpowers(pi as unknown as never);
+
+console.log(JSON.stringify({
+  commands: commands.size,
+  tool: tools[0]?.name,
+  events: [...events.keys()],
+  firstCommand: [...commands.keys()].slice(0, 5),
+  sendUserMessageAwaitable: typeof pi.sendUserMessage === "function",
+}));
+
+// Exercise the /survey-context handler end-to-end.
+const handler = commands.get("survey-context")?.handler;
+if (!handler) throw new Error("survey-context command not registered");
+await handler("", {});
+
+// Verify a nonexistent command is not present.
+const fallback = commands.get("nonexistent-skill-for-test")?.handler;
+if (fallback) throw new Error("unexpected command registered");
+
+// Test bigpowers_skill run path.
+const skillTool = tools[0];
+if (!skillTool?.execute) throw new Error("bigpowers_skill tool missing execute");
+const runResult = await skillTool.execute(
+  "call-1",
+  { action: "run", skill: "verify-work", args: "ping" },
+  new AbortController().signal,
+  () => {},
+  {},
+);
+
+console.log(JSON.stringify({
+  sendCalls,
+  runDetails: runResult.details,
+}));

package/scripts/test-install-helpers.js

@@ -269,6 +269,94 @@ try {
     }
   }
 
+  // story: BUG-2026-08-31-pi-scripts-provisioning (#116)
+  // A package consumer project needs bigpowers' scripts/ + specs/ scaffolding
+  // so SKILL.md bodies ("bash scripts/run-skill-verify.sh") and verify gates
+  // ("test -f scripts/... && test -d specs/bugs") resolve outside a checkout.
+  {
+    const { initProject, initProjectRemove } = require('../scripts/lib/install-helpers.js');
+    const savedInitCwd = process.cwd();
+    const consumerDir = mkdtempSync(path.join(os.tmpdir(), 'bp-init-project-'));
+    try {
+      process.chdir(consumerDir);
+
+      // (a) init provisions scripts/ + specs/ scaffolding
+      initProject(ROOT);
+      assert.ok(
+        fs.lstatSync(path.join(consumerDir, 'scripts')).isSymbolicLink(),
+        'init must symlink scripts/ into the consumer project'
+      );
+      assert.strictEqual(
+        fs.readlinkSync(path.join(consumerDir, 'scripts')),
+        path.join(ROOT, 'scripts'),
+        'scripts symlink must point at the package scripts tree'
+      );
+      assert.ok(
+        fs.existsSync(path.join(consumerDir, 'scripts', 'run-skill-verify.sh')),
+        'scripts/run-skill-verify.sh must resolve through the link (skill verify gate)'
+      );
+      assert.ok(
+        fs.existsSync(path.join(consumerDir, 'specs', 'bugs')),
+        'init must scaffold specs/bugs (fix-bug verify gate probes it)'
+      );
+      assert.ok(
+        fs.existsSync(path.join(consumerDir, 'specs', 'verifications')),
+        'init must scaffold specs/verifications'
+      );
+
+      // (b) init --remove cleans managed artifacts only
+      initProjectRemove(ROOT);
+      assert.ok(
+        !fs.existsSync(path.join(consumerDir, 'scripts')),
+        'init --remove must remove the managed scripts symlink'
+      );
+      assert.ok(
+        !fs.existsSync(path.join(consumerDir, 'specs')),
+        'init --remove must remove the untouched scaffolded specs tree'
+      );
+
+      // (c) refuses a pre-existing non-managed scripts/ (never clobbers)
+      fs.mkdirSync(path.join(consumerDir, 'scripts'));
+      fs.writeFileSync(path.join(consumerDir, 'scripts', 'mine.sh'), 'echo mine\n');
+      assert.throws(
+        () => initProject(ROOT),
+        /Refusing to replace/,
+        'init must refuse a user-owned scripts/ dir'
+      );
+      assert.ok(
+        fs.existsSync(path.join(consumerDir, 'scripts', 'mine.sh')),
+        'user-owned scripts/ content must survive the refusal'
+      );
+    } finally {
+      process.chdir(savedInitCwd);
+      rmSync(consumerDir, { recursive: true, force: true });
+    }
+
+    // (d) CLI dispatch drift guard: `bigpowers init` must stay wired
+    const bigpowersSrc = fs.readFileSync(path.join(ROOT, 'bin', 'bigpowers.js'), 'utf8');
+    assert.ok(
+      /'init'/.test(bigpowersSrc),
+      "bin/bigpowers.js must dispatch the 'init' command"
+    );
+    assert.ok(
+      fs.existsSync(path.join(ROOT, 'bin', 'init.js')),
+      'bin/init.js must exist'
+    );
+  }
+
+  // story: BUG-2026-08-31-pi-scripts-provisioning (follow-up from PR #114 review)
+  // The managed-symlink check must not treat a string-prefix sibling of the
+  // package root (e.g. <ROOT>-evil) as managed — needs a path-separator boundary.
+  {
+    const dst = path.join(tmpHome, 'prefix-boundary-hook.sh');
+    fs.symlinkSync(path.join(`${ROOT}-evil`, 'x.sh'), dst); // dangling foreign link
+      assert.throws(
+        () => linkHook(rtkSrc, dst),
+        /Refusing to replace/,
+        'managed-symlink check must require a path-separator boundary (prefix sibling is NOT managed)'
+      );
+  }
+
   console.log('test-install-helpers: ALL PASS');
 } finally {
   rmSync(tmpHome, { recursive: true, force: true });

package/scripts/test-project-runtime.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# story: e82s01
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# shellcheck disable=SC1091
+source "$ROOT/scripts/lib/project-runtime.sh"
+
+PASS=0
+FAIL=0
+TMPDIR_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR_ROOT"' EXIT
+
+pass() {
+  echo "  PASS $1"
+  PASS=$((PASS + 1))
+}
+
+fail() {
+  echo "  FAIL $1" >&2
+  FAIL=$((FAIL + 1))
+}
+
+assert_eq() {
+  local name="$1" expected="$2" actual="$3"
+  if [[ "$actual" == "$expected" ]]; then
+    pass "$name"
+  else
+    fail "$name — expected '$expected', got '$actual'"
+  fi
+}
+
+assert_fails_with() {
+  local name="$1" expected="$2"
+  shift 2
+  local output
+  if output="$("$@" 2>&1)"; then
+    fail "$name — command unexpectedly succeeded"
+  elif [[ "$output" == *"$expected"* ]]; then
+    pass "$name"
+  else
+    fail "$name — expected error containing '$expected', got '$output'"
+  fi
+}
+
+make_project() {
+  local name="$1"
+  local project="$TMPDIR_ROOT/$name"
+  mkdir -p "$project/.bigpowers"
+  printf '%s\n' "$project"
+}
+
+DEFAULT_PROJECT="$(make_project default)"
+assert_eq "default specs directory" "specs" "$(bp_specs_dir "$DEFAULT_PROJECT")"
+assert_eq "default specs path" "$DEFAULT_PROJECT/specs/state.yaml" \
+  "$(bp_specs_path "$DEFAULT_PROJECT" state.yaml)"
+assert_eq "repository without VCS" "none" "$(bp_vcs_kind "$DEFAULT_PROJECT")"
+
+CONFIG_PROJECT="$(make_project configured)"
+cat > "$CONFIG_PROJECT/.bigpowers/config.yaml" <<'YAML'
+specs_dir: .specs
+vcs: git
+YAML
+assert_eq "configured specs directory" ".specs" "$(bp_specs_dir "$CONFIG_PROJECT")"
+assert_eq "configured specs path" "$CONFIG_PROJECT/.specs/release-plan.yaml" \
+  "$(bp_specs_path "$CONFIG_PROJECT" release-plan.yaml)"
+assert_eq "configured VCS" "git" "$(bp_vcs_kind "$CONFIG_PROJECT")"
+
+assert_eq "environment specs override" "private-specs" \
+  "$(BIGPOWERS_SPECS_DIR=private-specs bp_specs_dir "$CONFIG_PROJECT")"
+assert_eq "environment VCS override" "jj" \
+  "$(BIGPOWERS_VCS=jj bp_vcs_kind "$CONFIG_PROJECT")"
+
+COLOCATED_PROJECT="$(make_project colocated)"
+mkdir -p "$COLOCATED_PROJECT/.git" "$COLOCATED_PROJECT/.jj"
+assert_eq "auto prefers Jujutsu in colocated repository" "jj" \
+  "$(bp_vcs_kind "$COLOCATED_PROJECT")"
+
+INVALID_PROJECT="$(make_project invalid)"
+printf '%s\n' 'vcs: svn' > "$INVALID_PROJECT/.bigpowers/config.yaml"
+assert_fails_with "invalid VCS is actionable" \
+  "Expected one of: auto, git, jj" bp_vcs_kind "$INVALID_PROJECT"
+
+EMPTY_PROJECT="$(make_project empty)"
+printf '%s\n' 'specs_dir: ""' > "$EMPTY_PROJECT/.bigpowers/config.yaml"
+assert_fails_with "empty specs directory is rejected" \
+  "specs_dir must not be empty" bp_specs_dir "$EMPTY_PROJECT"
+
+echo "---"
+echo "test-project-runtime: $PASS passed, $FAIL failed"
+[[ "$FAIL" -eq 0 ]]

package/scripts/validate-omp-extension.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# story: e82s03
+# OMP extension integrity guard — validates the extension entry is wired
+# correctly and all source skills are discoverable via skills/<name>/SKILL.md.
+# Run before merging any branch that touches extensions/.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+ERRORS=0
+
+fail() {
+  echo "FAIL: $*"
+  ERRORS=$((ERRORS + 1))
+}
+
+pass() {
+  echo "ok  : $*"
+}
+
+# ── 1. Package has exactly one omp.extensions entry ────────────────────────
+echo "--- [OMP] manifest: single extension entry ---"
+EXT_COUNT=$(node -e "const p = require('./package.json'); const exts = p.omp?.extensions; if (!exts) { console.log(0); } else { console.log(exts.length); }")
+if [[ "$EXT_COUNT" -eq 1 ]]; then
+  pass "omp.extensions has exactly 1 entry"
+else
+  fail "omp.extensions has $EXT_COUNT entries (expected 1)"
+fi
+
+# ── 2. Extension file exists ───────────────────────────────────────────────
+echo "--- [OMP] extension file exists ---"
+EXT_PATH=$(node -e "const p = require('./package.json'); console.log(p.omp?.extensions?.[0] || '')")
+if [[ -z "$EXT_PATH" ]]; then
+  fail "No omp.extensions entry found"
+else
+  if [[ -f "$EXT_PATH" ]]; then
+    pass "extension file '$EXT_PATH' exists"
+  else
+    fail "extension file '$EXT_PATH' does not exist"
+  fi
+fi
+
+# ── 3. Extension source contains required symbols ──────────────────────────
+echo "--- [OMP] required runtime symbols in extension ---"
+if [[ -n "$EXT_PATH" && -f "$EXT_PATH" ]]; then
+  for sym in "registerCommand" "registerTool" "tool_call"; do
+    if grep -q "$sym" "$EXT_PATH" 2>/dev/null; then
+      pass "symbol '$sym' found in extension source"
+    else
+      fail "symbol '$sym' NOT found in extension source"
+    fi
+  done
+else
+  fail "Cannot scan extension symbols — file not resolved"
+fi
+
+# ── 4. Skill discovery root is skills/ ────────────────────────────────────
+echo "--- [OMP] source skill discoverability (skills/<name>/SKILL.md) ---"
+SKILLS_ROOT="$REPO_ROOT/skills"
+if [[ ! -d "$SKILLS_ROOT" ]]; then
+  fail "skills/ directory not found at $SKILLS_ROOT"
+else
+  TOTAL=0
+  MISSING=0
+  while IFS= read -r skill_md; do
+    rel="${skill_md#"$SKILLS_ROOT"/}"
+    # Each should be exactly <name>/SKILL.md (one level of nesting).
+    if [[ "$rel" != */SKILL.md || "${rel%%/*}" == "" ]]; then
+      fail "unexpected SKILL.md path: $rel"
+      MISSING=$((MISSING + 1))
+      continue
+    fi
+    TOTAL=$((TOTAL + 1))
+  done < <(find "$SKILLS_ROOT" -maxdepth 2 -name SKILL.md 2>/dev/null | sort)
+
+  if [[ "$TOTAL" -eq 0 ]]; then
+    fail "no skills found under skills/"
+  elif [[ "$MISSING" -eq 0 ]]; then
+    pass "$TOTAL source skills all at skills/<name>/SKILL.md"
+  else
+    fail "$MISSING/$TOTAL skills at unexpected paths"
+  fi
+fi
+
+# ── 5. Extension scans skills/ not the repo root ──────────────────────────
+echo "--- [OMP] extension targets skills/ root ---"
+if [[ -n "$EXT_PATH" && -f "$EXT_PATH" ]]; then
+  if grep -q 'join(pluginRoot(), "skills")' "$EXT_PATH" 2>/dev/null; then
+    pass "extension calls discoverSkills with skills/ subdirectory"
+  else
+    fail "extension does not target skills/ — check discoverSkills call in $EXT_PATH"
+  fi
+fi
+
+# ── Summary ────────────────────────────────────────────────────────────────
+echo "---"
+if [[ "$ERRORS" -eq 0 ]]; then
+  echo "OMP extension validation passed"
+else
+  echo "OMP extension validation FAILED ($ERRORS error(s))"
+  exit 1
+fi

package/skills/commit-message/SKILL.md

@@ -5,6 +5,8 @@ effort: standard
 description: Reviews working-tree changes, then drafts a Conventional Commits title/body and states the semantic-release version bump a single such commit would imply. Also notes which defensive-code categories were touched. Use when the user wants to commit recent work, prepare a Conventional Commits message, or asks for semantic-release / semver-consistent messaging before git commit.
 ---
 
+# story: e82s02
+
 # Commit Message
 > **HARD GATE** — **HARD GATE** — Commits must follow Conventional Commits spec (type(scope): description). Do NOT use vague messages like 'fix' or 'updates.' The message must explain the 'why,' not the 'what.'
 
@@ -16,7 +18,7 @@ description: Reviews working-tree changes, then drafts a Conventional Commits ti
 
 ## What "last chat" means
 
-- **Primary source of truth:** `git status`, `git diff` (unstaged), and `git diff --cached` (staged). Run these in the repo root (or the paths the user changed).
+- **Primary source of truth:** Read `state.yaml` `vcs.kind`. Git uses `git status`, `git diff`, and `git diff --cached`; Jujutsu uses `jj status`, `jj diff`, and `jj log -r @`. Run in the repo root.
 - **Context:** use the current conversation to summarize *intent* and to spot **breaking** API/behavior changes that diff alone may not show.
 - If the user tracks a session baseline (e.g. branch, tag, or `git stash create` at start), you may `git diff <baseline>..HEAD` plus uncommitted diffs; otherwise use only the index and working tree.
 
@@ -31,7 +33,7 @@ description: Reviews working-tree changes, then drafts a Conventional Commits ti
 7. **Deliver** — Output:
    - Proposed **full commit message** (title + optional body + footers).
    - **Release bump** this commit would drive: `patch` | `minor` | `major` | `none`.
-   - Optional `git add …` and `git commit -m` instructions; do **not** run destructive git commands unless the user asked.
+   - Optional native command: Git `git commit -m`; Jujutsu `jj commit -m`. Never omit `-m` or run destructive commands unless asked.
 
 ## Checklist before finalizing
 

package/skills/kickoff-branch/SKILL.md

@@ -2,20 +2,21 @@
 name: kickoff-branch
 model: haiku
 effort: standard
-description: Create a git worktree and feature branch, then verify a clean test baseline before any code is written. Use when starting a new feature or task, when user wants to work in isolation from main, or mentions "start a branch" or "new worktree".
+description: Create an isolated Git worktree/branch or Jujutsu workspace, then verify a clean test baseline before code. Use when starting a feature or task.
 ---
 
 # story: e51s03
 # story: e20s03
+# story: e82s02
 
 
 # Kickoff Branch
 
-> **HARD GATE** — Direct work on `main` or `master` is PROHIBITED. Every task MUST start with this skill to create a feature branch or worktree.
+> **HARD GATE** — Direct Git work on `main`/`master` or reuse of an unrelated Jujutsu change is prohibited. Create a feature branch/worktree or Jujutsu workspace/change.
 >
 > **HARD GATE** — Do NOT proceed with development until **Preflight** passes on the default branch. Red Preflight blocks branch creation and all forward work — invoke `quick-fix` or `fix-bug` per CONVENTIONS § Discovered Defects.
 
-Create an isolated working environment before touching any code. **Preflight must be green** before you write feature code — solo-default owns the whole tree, not just the current task diff.
+Create an isolated Git worktree or Jujutsu workspace before code. **Preflight must be green** first — solo-default owns the whole tree.
 
 ## Process
 
@@ -23,9 +24,13 @@ Create an isolated working environment before touching any code. **Preflight mus
 
 Ask if not already known: "What's the name of this feature or task?" Use it as the branch name slug (kebab-case, max 40 chars).
 
-### 2. Anchor on default branch (main or master)
+### 2. Select the VCS procedure
 
-> **HARD GATE** — Kickoff MUST start from an updated, clean default branch in the **primary** repository root (not a linked worktree).
+Read `state.yaml` `vcs.kind`. For `jj`, do not run the Git blocks below: verify with `jj status` and `jj log -r '::@' -n 5`, create isolation with `jj workspace add ../<task-slug> -r @`, then run `jj -R ../<task-slug> describe -m "feat: <task>"`. Record the new stable change ID. For `git`, continue below.
+
+### 2a. Anchor Git on the default branch (main or master)
+
+> **HARD GATE** — Git kickoff MUST start from an updated, clean default branch in the **primary** repository root (not a linked worktree).
 
 ```bash
 # Detect default branch
@@ -64,7 +69,7 @@ fi
 - **Non-spec dirty files** (src/, scripts/, SKILL.md, …) still enforce the full clean-tree gate.
 - If not on `$DEFAULT` after checkout, stop and fix before continuing.
 
-### 3. Pre-flight & Conflict Resolution
+### 3. Git pre-flight & conflict resolution
 
 Before creating the worktree, verify the target environment is clean:
 
@@ -84,7 +89,7 @@ git worktree list | grep "<task-slug>"
 - **Branch exists:** If the branch exists but no worktree is attached, ask to use the existing branch (`git worktree add ../<task-slug> <task-slug>`) or delete it.
 - **Ghost worktree:** If `git worktree list` shows the path but the directory is missing, run `git worktree prune` to clear the stale metadata. `bash scripts/cleanup-worktrees.sh` does this plus reports any worktree whose branch is already merged or deleted — advisory only, it prints the `git worktree remove`/`git branch -d` commands rather than running them, so review before acting.
 
-### 4. Create worktree + branch
+### 4. Create Git worktree + branch
 
 ```bash
 # From the main repo root (not another worktree)

package/skills/release-branch/SKILL.md

@@ -10,6 +10,7 @@ description: Make the merge/PR/keep/discard decision for a feature branch, verif
 <!-- story: e45s15 -->
 <!-- story: e45s32 -->
 <!-- story: e45s39 -->
+<!-- story: e82s02 -->
 <!-- story: e20s02 -->
 
 
@@ -32,7 +33,7 @@ Read `specs/state.yaml` key `workflow_mode` (`team-pr` | `solo-git`). Fall back
 | **solo-local** | `workflow_mode: solo-git` | Auto: `scripts/land-branch.sh` if present, else fallback (Step 5) |
 | **team-pr** | `workflow_mode: team-pr` (default) | `gh pr create` → `gh pr merge --squash` |
 
-If unsure, prefer **solo-local**.
+If unsure, prefer **solo-local**. Also read `state.yaml` `vcs.kind`: Git follows the procedures below; Jujutsu uses workspaces/bookmarks and must not call Git-only landing scripts.
 
 ## Process
 
@@ -75,16 +76,21 @@ Run `gate-trace` before merge. FAIL blocks merge; CONCERNS requires explicit ove
 
 Options: **Release (solo-local)** / **Open PR** / **Keep branch** / **Discard**
 
-### 5. Solo-local integrate
+### 5. Integrate
 
-Run `commit-message` for the squash subject, then land:
+Run `commit-message` first. Git solo-local uses `land-branch.sh`. Jujutsu team mode explicitly advances and pushes a bookmark; `-m` is mandatory for commit/describe operations:
 
 ```bash
-# Path A (preferred):
+# Git solo-local
 bash scripts/land-branch.sh <task-slug> "feat(scope): description"
-# Path B (fallback if land-branch.sh missing): see REFERENCE.md
+# Jujutsu team PR
+jj describe -m "feat(scope): description"
+jj bookmark set <task-slug> -r @
+jj git push -b <task-slug>
 ```
 
+Jujutsu solo-local landing is unsupported: run `bp_require_vcs_operation "$PWD" land-branch` and stop with its remediation instead of invoking the Git backend.
+
 ### 6. Create PR (team-pr only)
 
 Create the pull request with a **literal provenance marker** in the body so agent-generated PRs are identifiable and do not rot silently:
@@ -133,7 +139,7 @@ bash scripts/wait-for-ci.sh --timeout 600 --interval 30
 
 ### 8. Clean up & return
 
-Worktree prune, branch delete, `git checkout main`. Cycle-time: see [REFERENCE.md](REFERENCE.md#cycle-time).
+Git: prune worktree, delete branch, return to main. Jujutsu: `jj workspace forget <workspace>` only after integration; do not delete its bookmark implicitly. Cycle-time: see [REFERENCE.md](REFERENCE.md#cycle-time).
 
 Report: "Branch released."
 

package/skills/survey-context/SKILL.md

@@ -5,6 +5,8 @@ effort: standard
 description: Per-task context bootstrap — reads existing specs/ and tech-architecture docs to map the current lifecycle phase and suggest the next skill. Use at the start of any task, when returning after a break, or when unsure what to do next. For deriving a tech-stack doc from scratch, use map-codebase first.
 ---
 
+# story: e82s02
+
 # Survey Context
 
 Read the project's current state and give a phase map + next-skill recommendation. This is the "where am I?" skill — run it at the start of every task.
@@ -52,15 +54,18 @@ Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT if
 
 If `CLAUDE.md` exists at the project root, read it for project context (stack, commands, architecture, conventions).
 
-### 4. Check git state
+### 4. Check VCS state
+
+Read `state.yaml` `vcs.kind` (or resolve `auto`). Use native identity:
 
 ```bash
-git status --short
-git log --oneline -5
-git branch --show-current
+# Git
+git status --short; git log --oneline -5; git branch --show-current
+# Jujutsu
+jj status; jj log -r 'mine() & ::@' -n 5
 ```
 
-Note: is there a feature branch active? Are there uncommitted changes? Do they match `specs/state.yaml` `git` block?
+For Jujutsu, compare stable change IDs and bookmarks with the `vcs` block; never interpret colocated Git's detached HEAD as branch state.
 
 ### 5. Map the lifecycle phase
 
@@ -125,7 +130,7 @@ Loop through all `specs/epics/*/epic.yaml` files and print a summary of story co
 
 ### check-gates (absorbed)
 
-Print the current `active_flow` from `specs/state.yaml`, run `bash scripts/validate-specs-yaml.sh` to verify YAML integrity, and show `git status` to report uncommitted changes and branch state. Use before handoffs or context transitions.
+Print `active_flow`, validate YAML, then show `git status` or `jj status` according to `vcs.kind`. Use before handoffs or context transitions.
 
 ## Handoff
 

package/skills-lock.json

@@ -33,7 +33,7 @@
     },
     "commit-message": {
       "description": "Reviews working-tree changes, then drafts a Conventional Commits title/body and states the semantic-release version bump a single such commit would imply. Also notes which defensive-code categories were touched. Use when the user wants to commit recent work, prepare a Conventional Commits message, or asks for semantic-release / semver-consistent messaging before git commit.",
-      "sha256": "1ed4ef65d813a84d",
+      "sha256": "3c1413ae4e3c1476",
       "path": "skills/commit-messageSKILL.md"
     },
     "compose-workflow": {
@@ -187,8 +187,8 @@
       "path": "skills/investigate-bugSKILL.md"
     },
     "kickoff-branch": {
-      "description": "Create a git worktree and feature branch, then verify a clean test baseline before any code is written. Use when starting a new feature or task, when user wants to work in isolation from main, or mentions \"start a branch\" or \"new worktree\".",
-      "sha256": "d94be12d4b29895b",
+      "description": "Create an isolated Git worktree/branch or Jujutsu workspace, then verify a clean test baseline before code. Use when starting a feature or task.",
+      "sha256": "ae1628400f08dc20",
       "path": "skills/kickoff-branchSKILL.md"
     },
     "maintain-wiki": {
@@ -253,7 +253,7 @@
     },
     "release-branch": {
       "description": "Make the merge/PR/keep/discard decision for a feature branch, verify coverage gates, create the PR with gh, and clean up the worktree. Use when a feature is done and ready to ship, or when user says \"release\", \"merge\", or \"open a PR\".",
-      "sha256": "4479807337f84915",
+      "sha256": "aaaf314d6b4f97f6",
       "path": "skills/release-branchSKILL.md"
     },
     "request-review": {
@@ -353,7 +353,7 @@
     },
     "survey-context": {
       "description": "Per-task context bootstrap — reads existing specs/ and tech-architecture docs to map the current lifecycle phase and suggest the next skill. Use at the start of any task, when returning after a break, or when unsure what to do next. For deriving a tech-stack doc from scratch, use map-codebase first.",
-      "sha256": "ef837ae3e822e9a3",
+      "sha256": "30e1fea4e6e9ab63",
       "path": "skills/survey-contextSKILL.md"
     },
     "terse-mode": {