@bitkentech/shipsmooth-opencode 0.3.27 → 0.3.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitkentech/shipsmooth-opencode",
-  "version": "0.3.27",
+  "version": "0.3.28",
   "description": "Agent coding workflow with plan-before-implement discipline, TDD, vertical slices, Linear integration, and immutable git-based plan versioning.",
   "type": "module",
   "main": "plugin/index.js",

package/plugin/dist/session-start-config.json

@@ -1,4 +1,4 @@
 {
-  "version" : "0.3.27",
+  "version" : "0.3.28",
   "name" : "shipsmooth"
 }

package/plugin/index.js

@@ -27,10 +27,15 @@
 // The version + skill name come from the rendered config JSON next to the
 // compiled module (dist/session-start-config.json), so a version bump re-renders
 // one file and this source is untouched.
-import { existsSync } from "node:fs";
-import { moduleDir, readConfig, startCommandId, startCommandTemplate, installerPath, safeLog, } from "./lib/internal.js";
-export const ShipsmoothPlugin = async ({ client, $ }) => {
-    const base = moduleDir(import.meta.url);
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { moduleDir, readConfig, skillName, startCommandId, startCommandTemplate, installerPath, installSkill, safeLog, } from "./lib/internal.js";
+export const ShipsmoothPlugin = async ({ client, $, worktree }, options) => {
+    // The module dir holds the bundled config/installer/skills. Tests may override it
+    // (via `__baseDir`) so they can stage fixtures in a tmp dir instead of polluting
+    // the real src/; production always uses the compiled module's own location.
+    const override = options?.__baseDir;
+    const base = typeof override === "string" ? override : moduleDir(import.meta.url);
     let cfg;
     try {
         cfg = readConfig(base);
@@ -45,6 +50,10 @@ export const ShipsmoothPlugin = async ({ client, $ }) => {
         if (bootstrapped)
             return;
         bootstrapped = true;
+        await installRuntime();
+        await stageSkill();
+    }
+    async function installRuntime() {
         const installer = installerPath(base);
         if (!existsSync(installer)) {
             await safeLog(client, "error", `shipsmooth: installer not found at ${installer}`);
@@ -65,6 +74,52 @@ export const ShipsmoothPlugin = async ({ client, $ }) => {
             await safeLog(client, "error", `shipsmooth: bootstrap failed: ${e.message}`);
         }
     }
+    // Stage the bundled SKILL.md into an OpenCode-scanned skills/ dir, mirroring the
+    // plugin's install scope. Non-fatal: a failure leaves the slash command pointing at
+    // an undiscovered skill (degraded), but never crashes the session.
+    async function stageSkill() {
+        try {
+            const path = await client.path.get();
+            const configDir = path?.data?.config;
+            if (!configDir) {
+                await safeLog(client, "error", "shipsmooth: no config dir from path.get(); skipping skill staging");
+                return;
+            }
+            const res = installSkill({
+                baseDir: base,
+                skill: skillName(cfg.name),
+                version: cfg.version,
+                pkgName: packageName(base),
+                configDir,
+                worktree,
+            });
+            if (res.action === "staged") {
+                await safeLog(client, "info", `shipsmooth: skill staged at ${res.dest}`);
+            }
+            else if (res.action === "noop") {
+                await safeLog(client, "error", `shipsmooth: skill not staged (${res.reason})`);
+            }
+        }
+        catch (e) {
+            await safeLog(client, "error", `shipsmooth: skill staging failed: ${e.message}`);
+        }
+    }
+    // The npm package name as it appears in opencode.json's `plugin` array — read from
+    // the plugin's own package.json (one dir above the compiled module's plugin/ root).
+    // Falls back to cfg.name if unreadable (scope inference then defaults to global).
+    function packageName(baseDir) {
+        for (const candidate of [join(baseDir, "package.json"), join(baseDir, "..", "package.json")]) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
+                if (pkg.name)
+                    return pkg.name;
+            }
+            catch {
+                // try the next candidate
+            }
+        }
+        return cfg.name;
+    }
     const hooks = {
         config: async (config) => {
             config.command = config.command ?? {};

package/plugin/lib/internal.js

@@ -9,7 +9,7 @@
 // "fails to load". Keeping them here (imported by index.ts, never re-exported)
 // means the entry module exposes only the real factory. The unit suite imports
 // these directly from this module.
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, copyFileSync, mkdirSync, existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 export const CONFIG_FILE = "session-start-config.json";
@@ -36,9 +36,17 @@ export function readConfig(baseDir) {
     }
     throw new Error(`shipsmooth: ${CONFIG_FILE} not found near ${baseDir}`);
 }
-/** The skill the start command delegates to: `start` (prod) or `start-dev` (dev). */
+/**
+ * The skill the start command delegates to, and the dir name it is staged under:
+ * `shipsmooth-start` (prod) or `shipsmooth-start-dev` (dev).
+ *
+ * Namespaced (not bare `start`) because OpenCode's skills/ namespace is shared
+ * host-wide and flat — a bare `start` would collide with any other `start` skill
+ * (first discovered wins + warns). This must match the rendered skill dir basename
+ * and its frontmatter `name:` (set in the opencode render spec).
+ */
 export function skillName(pluginName) {
-    return pluginName.endsWith("-dev") ? "start-dev" : "start";
+    return pluginName.endsWith("-dev") ? "shipsmooth-start-dev" : "shipsmooth-start";
 }
 /** Thin launcher template — points the agent at the canonical skill, no inlined workflow. */
 export function startCommandTemplate(pluginName) {
@@ -63,3 +71,97 @@ export async function safeLog(client, level, message) {
         // logging is best-effort
     }
 }
+// ── Skill staging (plan-88) ─────────────────────────────────────────────────
+//
+// OpenCode discovers SKILL.md ONLY from filesystem dirs it scans (~/.config/
+// opencode/skills, <project>/.opencode/skills, ~/.claude/skills, .agents/skills,
+// …) — NEVER from inside a node_modules package. So the bundled skills/<name>/
+// SKILL.md the plugin ships is invisible until we copy it into a scanned dir.
+//
+// We stage it ourselves, mirroring how the plugin was installed: a project-scoped
+// install (package listed in <worktree>/opencode.json) → <worktree>/.opencode/
+// skills/; a global install (listed in <config>/opencode.json) → <config>/skills/;
+// and global as the fallback when scope can't be determined. A version marker beside
+// the staged skill makes re-staging idempotent across sessions and fresh across
+// version bumps (OpenCode has no per-version skill dirs).
+/** Marker file (beside the staged SKILL.md) recording the staged plugin version. */
+export const SKILL_VERSION_MARKER = ".shipsmooth-version";
+/**
+ * Resolve the bundled source SKILL.md for `skillName`. In the assembled payload the
+ * compiled module lives under `plugin/` but the bundled `skills/` sits at the payload
+ * ROOT (next to plugin/, where OpenCode itself discovers a dev filesystem load) — so
+ * `<base>/../skills` is the real location. We also accept `<base>/skills` (co-located)
+ * for layouts/tests that bundle skills beside the module. First existing wins; if
+ * neither exists, return the root candidate (installSkill then reports a clear noop).
+ */
+export function bundledSkillPath(baseDir, skill) {
+    const root = join(baseDir, "..", "skills", skill, "SKILL.md");
+    const colocated = join(baseDir, "skills", skill, "SKILL.md");
+    if (existsSync(root))
+        return root;
+    if (existsSync(colocated))
+        return colocated;
+    return root;
+}
+/** True if `opencode.json` at `configDir` lists `pkgName` in its `plugin` array. */
+function configListsPlugin(configDir, pkgName) {
+    const file = join(configDir, "opencode.json");
+    if (!existsSync(file))
+        return false;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf-8"));
+        const arr = Array.isArray(parsed.plugin) ? parsed.plugin : [];
+        // Entries are either "name" or ["name", options]; match the name in both forms.
+        return arr.some((e) => {
+            const name = Array.isArray(e) ? e[0] : e;
+            return name === pkgName;
+        });
+    }
+    catch {
+        return false; // unreadable/malformed config → treat as "not listed"
+    }
+}
+/**
+ * Pick the skills/ destination ROOT mirroring install scope:
+ *   - project: `<worktree>/.opencode/skills` when the project opencode.json lists us
+ *   - global:  `<configDir>/skills` when the global opencode.json lists us
+ *   - fallback: global, when neither lists us (plugins-dir install, unreadable config)
+ */
+export function resolveSkillsRoot(pkgName, configDir, worktree) {
+    if (worktree && configListsPlugin(worktree, pkgName)) {
+        return join(worktree, ".opencode", "skills");
+    }
+    // global match OR fallback both land in the global config skills dir.
+    return join(configDir, "skills");
+}
+/**
+ * Stage the bundled SKILL.md into a scope-appropriate, OpenCode-scanned skills/ dir.
+ * Idempotent (skips when the marker already records this version) and pure-ish: all
+ * effects are filesystem writes the caller has consented to. Returns what it did.
+ * Throws only on genuine IO failure — the caller wraps this non-fatally.
+ */
+export function installSkill(args) {
+    const { baseDir, skill, version, pkgName, configDir, worktree } = args;
+    const src = bundledSkillPath(baseDir, skill);
+    if (!existsSync(src)) {
+        return { action: "noop", reason: `bundled skill not found at ${src}` };
+    }
+    const destDir = join(resolveSkillsRoot(pkgName, configDir, worktree), skill);
+    const dest = join(destDir, "SKILL.md");
+    const marker = join(destDir, SKILL_VERSION_MARKER);
+    // Already staged at this version → nothing to do.
+    if (existsSync(dest) && existsSync(marker)) {
+        try {
+            if (readFileSync(marker, "utf-8").trim() === version) {
+                return { action: "skipped", dest };
+            }
+        }
+        catch {
+            // unreadable marker → fall through and re-stage
+        }
+    }
+    mkdirSync(destDir, { recursive: true });
+    copyFileSync(src, dest);
+    writeFileSync(marker, version);
+    return { action: "staged", dest };
+}

package/skills/{start → shipsmooth-start}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: start
+name: shipsmooth-start
 description: Use when starting any task — applies the shipsmooth agent coding workflow.
 ---
 
-# start — Agent Coding Workflow
+# shipsmooth-start — Agent Coding Workflow
 
 ## When to apply this skill
 Apply this skill whenever you are:
@@ -55,7 +55,7 @@ This workflow supports two task tracking modes. Choose one at the start of each
 
 Throughout this skill, instructions marked `[Linear]` apply only in Linear mode; instructions marked `[Local]` apply only in Local mode. Unmarked instructions apply to both.
 
-`[Local]` Script invocations use `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth <subcommand>`. All scripts read/write `.shipsmooth/plans/plan-{N}-tasks.xml` relative to the repo root.
+`[Local]` Script invocations use `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth <subcommand>`. All scripts read/write `.shipsmooth/plans/plan-{N}-tasks.xml` relative to the repo root.
 
 ---
 
@@ -90,19 +90,19 @@ Plans are markdown files. They contain: narrative, design decisions, architectur
 Every time a plan file is committed, immediately create and push a version tag:
 
 ```bash
-${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth plan tag --plan {N} --kind version
+${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth plan tag --plan {N} --kind version
 # prints: git push origin plan-{N}-v{K}  — run that line to push
 ```
 
 On clean completion:
 ```bash
-${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth plan tag --plan {N} --kind complete
+${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth plan tag --plan {N} --kind complete
 # prints: git push origin plan-{N}-complete
 ```
 
 On abandonment:
 ```bash
-${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth plan tag --plan {N} --kind abandoned
+${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth plan tag --plan {N} --kind abandoned
 # prints: git push origin plan-{N}-abandoned
 ```
 
@@ -151,16 +151,16 @@ one:
 
 - find the plans directory first — in **external** mode (the default) it is not
   `.shipsmooth/plans/` but a separate state dir. Ask the CLI:
-  `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth store info --json` reports `plansDir` (when `status` is `ready`).
+  `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth store info --json` reports `plansDir` (when `status` is `ready`).
   List `plansDir`'s `plan-*-tasks.xml` (the highest plan number is the most likely
   candidate); if `status` is **not** `ready`, state is not set up yet — run the
   **first-run handshake** below before going further (there is no active plan to resume).
 - check that plan's state with
-  `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth plan resume --plan {N}` — a plan-level status of `active` /
+  `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth plan resume --plan {N}` — a plan-level status of `active` /
   `in-review` with tasks still `pending` / in-progress means work is unfinished.
 
 
-> **First-run handshake `[Local]`.** When a `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth` command reports that state is
+> **First-run handshake `[Local]`.** When a `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth` command reports that state is
 > not set up — `store info --json` returns a `status` other than `ready`, or a
 > state-dependent command exits with a `status:"needs-decision"` / `status:"unresolvable"`
 > JSON line (exit 10 / 11) — do **not** treat it as a normal error. Run this handshake. The
@@ -180,13 +180,13 @@ one:
 >    option:
 >    ```bash
 >    # external (recommended) — accept the proposed folder:
->    ${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth store init --choice external --json
+>    ${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth store init --choice external --json
 >    # external — a different folder the user named:
->    ${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth store init --choice external --path <user's folder> --json
+>    ${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth store init --choice external --path <user's folder> --json
 >    # keep it inside this repo:
->    ${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth store init --choice in-repo --json
+>    ${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth store init --choice in-repo --json
 >    # a configured external folder went missing — recreate it:
->    ${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth store init --choice recreate --path <path from the option> --json
+>    ${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth store init --choice recreate --path <path from the option> --json
 >    ```
 >    `store init` creates the chosen location, writes the config entry, and prints the
 >    `ready` shape — read its `plansDir` for where plan files now live.
@@ -225,7 +225,7 @@ that he will add detail later or work exploratorily. **Do not slow him down.**
 Run **one** command and hand back:
 
 ```bash
-${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth plan quick --desc "{short-description}"
+${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth plan quick --desc "{short-description}"
 # derives the next plan number, creates + checks out t/{N}-{slug},
 # and writes a stub .shipsmooth/plans/plan-{N}.md.
 # It does NOT commit — that is intentional.
@@ -259,7 +259,7 @@ fleshed out the stub.
 
 Kickoff: *"start a new plan, feature is X"* — no spec, no prior planning.
 
-- ✅ **Target:** run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth plan quick --desc "X"` → relay its
+- ✅ **Target:** run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth plan quick --desc "X"` → relay its
   output (branch + stub created, uncommitted) → **stop**.
 - ❌ **Anti-target #1:** run several rounds of repo investigation, then fire a
   multi-part questionnaire asking the user to choose the approach, before
@@ -296,12 +296,12 @@ is already rich, or after the user has fleshed out a Phase 0 stub.
    ```
 6. **Verify Preconditions:**
    ```bash
-   ${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth plan preflight --plan {N}
+   ${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth plan preflight --plan {N}
    # Exits 0 (PASS) or 1 (FAIL: dirty tree / missing version tag). Warns on unpushed branch.
    ```
 7. **Create Task Tracking Infrastructure:**
    - `[Linear]` Create the `[agent]` Linear project. Create Linear issues from the **risk-sorted** plan tasks. Each issue description must include the **Risk Level** ($L/M/H$) and the tag-based GitHub URL of the specific plan version that generated it.
-   - `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth plan init --plan {N} --tasks-from .shipsmooth/plans/plan-{N}.md` to generate `.shipsmooth/plans/plan-{N}-tasks.xml`. Commit the XML file immediately after creation. **Never hand-write this XML file — always generate it via the CLI. The format uses child elements, not attributes.** The CLI requires task headings in the form `### Task N: Name [Risk]` where `N` is a positive integer — alphanumeric IDs (e.g. `01-A`) are not supported. To express a dependency between tasks, add a `*Depends-on: P[,Q...]*` line anywhere in the task body before the next heading (e.g. `*Depends-on: 1,3*`). The CLI parses this line and writes `<depends-on>` into the XML automatically.
+   - `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth plan init --plan {N} --tasks-from .shipsmooth/plans/plan-{N}.md` to generate `.shipsmooth/plans/plan-{N}-tasks.xml`. Commit the XML file immediately after creation. **Never hand-write this XML file — always generate it via the CLI. The format uses child elements, not attributes.** The CLI requires task headings in the form `### Task N: Name [Risk]` where `N` is a positive integer — alphanumeric IDs (e.g. `01-A`) are not supported. To express a dependency between tasks, add a `*Depends-on: P[,Q...]*` line anywhere in the task body before the next heading (e.g. `*Depends-on: 1,3*`). The CLI parses this line and writes `<depends-on>` into the XML automatically.
    - Organise tasks as **thin vertical slices** in both modes.
 8. **Final Review & Go-ahead:**
    - `[Linear]` **Stop.** Post to the Linear project that the risk-sorted plan is ready for review.
@@ -315,7 +315,7 @@ is already rich, or after the user has fleshed out a Phase 0 stub.
 **Session-resume pre-flight `[Local]`** — If you are picking up a plan that was started in a previous session, run this before doing anything else:
 
 ```bash
-${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth plan resume --plan {N}
+${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth plan resume --plan {N}
 # Prints: XML file present check and task state summary.
 ```
 
@@ -327,7 +327,7 @@ repo stays untouched and the plan files live in a separate state directory. Ask
 where to read them — it is the source of truth — rather than guessing:
 
 ```bash
-${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth store info --json
+${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth store info --json
 # -> {"status":"ready","mode":"external","stateRoot":"...","plansDir":"<dir>/plans"}
 #    Read plan narratives (plan-{N}.md) and task XML from the reported `plansDir`.
 #    If status is not "ready", state is not set up yet — handle per first-run (Phase 0).
@@ -342,7 +342,7 @@ as you would for an in-repo plan — `mode: in-repo` simply reports the in-repo
 
 Create a branch named after the primary issue for this plan:
 ```bash
-${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth plan branch --issue {issue-id} --desc "{short-description}"
+${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth plan branch --issue {issue-id} --desc "{short-description}"
 # prints: git push -u origin t/{issue-id}-{slug}  — run that line to push
 ```
 All task commits go on this branch. The `t/` prefix stands for "task". Usernames are omitted — the task identity is what matters long-term.
@@ -352,7 +352,7 @@ All task commits go on this branch. The `t/` prefix stands for "task". Usernames
 
 > **Commit-message convention (code commits in the project repo).** How you word a code
 > commit depends on the resolved storage mode. Check it once per session with
-> `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth store info --json` and read `mode`.
+> `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth store info --json` and read `mode`.
 >
 > - **`in-repo` mode:** keep the prefixed convention — `task(N): <short description>` and
 >   `draft(N): de-risk <task name>`. The plan/task history is shipsmooth's own and lives
@@ -395,7 +395,7 @@ Core Invariant #6).
 - Implement just enough to prove the approach works. Focus on the core complexity.
 - Commit per the **commit-message convention**: `draft(N): de-risk [task name]` in in-repo mode; in standalone mode a plain feature message with no `draft(N)`/`task(N)` reference.
 - `[Linear]` Post a comment on the Linear issue notifying the human the draft is ready.
-- `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth task status --plan {N} --task {id} --status de-risked` and `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth task comment --plan {N} --task {id} --message "De-risk draft ready for review"`.
+- `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth task status --plan {N} --task {id} --status de-risked` and `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth task comment --plan {N} --task {id} --message "De-risk draft ready for review"`.
 - **Wait for explicit approval of the approach.**
 
 ##### Step B: Hardening (Quality Phase)
@@ -419,7 +419,7 @@ quality conforms to its instructions):
 - `[Linear]` Mark the Linear issue **Agent Coded**.
 
 
-- `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth task status --plan {N} --task {id} --status agent-coded` and `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth task set-commit --plan {N} --task {id} --commit $(git rev-parse HEAD)`.
+- `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth task status --plan {N} --task {id} --status agent-coded` and `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth task set-commit --plan {N} --task {id} --commit $(git rev-parse HEAD)`.
 
 
 #### Low risk tasks — Single-pass (current behavior)
@@ -440,17 +440,17 @@ quality conforms to its instructions):
    - `[Linear]` Mark the Linear issue **Agent Coded**. No draft review needed.
 
 
-   - `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth task status --plan {N} --task {id} --status agent-coded` and `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth task set-commit --plan {N} --task {id} --commit $(git rev-parse HEAD)`. No draft review needed.
+   - `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth task status --plan {N} --task {id} --status agent-coded` and `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth task set-commit --plan {N} --task {id} --commit $(git rev-parse HEAD)`. No draft review needed.
 
 
 ---
 
 - **Minor deviation** (task split, reorder, clarification):
   - `[Linear]` Update the Linear issue(s), add a deviation comment explaining why, continue.
-  - `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth task deviation --plan {N} --task {id} --type minor --message "..."`, continue.
+  - `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth task deviation --plan {N} --task {id} --type minor --message "..."`, continue.
 - **Major deviation** (fundamental plan problem, architecture issue, blocked): Stop immediately.
   - `[Linear]` Post a Linear project update. Set project health to **"At Risk"**.
-  - `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth plan update --plan {N} --blocked --message "..."`.
+  - `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth plan update --plan {N} --blocked --message "..."`.
   - Wait for the human to revise the plan file, commit, push, and give a new go-ahead.
 
 Never autonomously modify the `.shipsmooth/plans/` file during execution. If a plan change is needed, surface it and wait.
@@ -465,11 +465,11 @@ git tag plan-07-complete
 git push origin plan-07-complete
 ```
 - `[Linear]` Close all Linear issues in the `[agent]` project. Mark `[agent]` project complete and archive it. Update the permanent backlog feature issue to reflect delivery (link to completing PR, note what was delivered).
-- `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth plan update --plan {N} --status complete --message "Plan complete."`. Commit the final XML state. Update the permanent backlog feature issue (if tracked externally) or note delivery in the plan file.
+- `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth plan update --plan {N} --status complete --message "Plan complete."`. Commit the final XML state. Update the permanent backlog feature issue (if tracked externally) or note delivery in the plan file.
 
 ### Completion with Loose Ends
 - `[Linear]` Label unresolved issues `needs-triage`. Set `[agent]` project to **"In Review"**. Post a project update listing each open issue and why it's unresolved. Wait for human to review: they will promote worthy issues to the permanent backlog or discard them. Human marks the project complete and archives it.
-- `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth task status --plan {N} --task {id} --status needs-triage` for each unresolved task. Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth plan update --plan {N} --status in-review --message "..."`. Commit the XML. Wait for human to review.
+- `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth task status --plan {N} --task {id} --status needs-triage` for each unresolved task. Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth plan update --plan {N} --status in-review --message "..."`. Commit the XML. Wait for human to review.
 
 ### Abandonment
 - Human commits a plan file deletion with a commit message referencing the superseding plan number
@@ -480,7 +480,7 @@ git push origin plan-07-complete
   ```
 - **Do not delete any earlier tags** (`plan-07-v1`, `plan-07-v2`, etc.) — they are the audit trail
 - `[Linear]` Surface all open tasks for human triage. Migrate worthy tasks to the permanent backlog with a note: "Partial delivery — see plan-07-abandoned, superseded by plan-{M}". Archive the `[agent]` project with a closing note referencing the deletion commit hash and the superseding plan.
-- `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.27/bin/shipsmooth plan update --plan {N} --status abandoned --message "Superseded by plan-{M}."`. Commit the final XML state.
+- `[Local]` Run `${XDG_CACHE_HOME:-~/.cache}/shipsmooth/0.3.28/bin/shipsmooth plan update --plan {N} --status abandoned --message "Superseded by plan-{M}."`. Commit the final XML state.
 
 ---