@fro.bot/systematic 3.26.0 → 3.26.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/HARNESSES.md CHANGED
@@ -26,14 +26,14 @@ Compatibility is direct: OpenCode consumes the concrete invocation language in t
26
26
 
27
27
  ## Pi — Tier 1 shipped adapter
28
28
 
29
- Pi's profile records degraded or unavailable native capabilities and explicit fallbacks [PI-P]. The adapter registers `systematic_skill` in `src/pi.ts:187-206` and `systematic_delegate` in `src/pi.ts:207-232` [PI-3]. Delegation is explicitly sequential (`executionMode: 'sequential'`), capped at `MAX_DELEGATE_TURNS = 20`, and guarded against re-entry in `src/lib/pi-delegate-tool.ts:14-18,245-249` [PI-1]. The child is spawned with `noExtensions: true`, bounding `systematic_delegate`'s own recursion; this does not bound end-to-end depth across a combined pi-subagents + Systematic path.
29
+ Pi's profile records degraded or unavailable native capabilities and explicit fallbacks [PI-P]. The adapter registers `systematic_skill` in `src/pi.ts:217-236` and `systematic_delegate` in `src/pi.ts:238-263` [PI-3]. Delegation is explicitly sequential (`executionMode: 'sequential'`), capped at `MAX_DELEGATE_TURNS = 20`, and guarded against re-entry in `src/lib/pi-delegate-tool.ts:14-18,245-249` [PI-1]. The child is spawned with `noExtensions: true`, bounding `systematic_delegate`'s own recursion; this does not bound end-to-end depth across a combined pi-subagents + Systematic path.
30
30
 
31
31
  Optional mature delegation is available via [pi-subagents](https://github.com/tintinweb/pi-subagents). It is outside Systematic's bounded-delegate guarantees and governed by pi-subagents' own configuration. Tested against pi-subagents 0.22.0 on Pi 1.3.0; versions outside the tested range are unsupported but nonfatal. pi-subagents reaches Systematic's personas by two paths:
32
32
 
33
33
  - **Installed package.** The package declares `pi.subagents.agents` at `package.json:24-28`, pointing at `dist/pi-subagents/agents/`. `scripts/build-pi-package-agents.ts` writes that directory at build time from the same render the export uses, so the 29 curated personas it ships are byte-equal to the committed fixtures (`tests/unit/package-exports.test.ts:289-344`) [PI-7]. pi-subagents 0.22 is the first release that reads package-declared agents. It reads them from the packages in Pi's `settings.json` `packages[]`, global and project, and never from `node_modules`, because the only scan is Pi's own configured-package list (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:327-341`). It sees a project-scope package only after the project is trusted: the trust flag starts `false` (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:90`), is passed to `SettingsManager.create` when the package list is read (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:332`), and keys the scan (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:432`). An installed Systematic therefore exposes `systematic-<name>` types with plain defaults and no export step. `pi -e` does not, because it is not in `packages[]`, and neither does a git install, which has no built `dist/`. `tests/integration/pi.test.ts:1550-1652` pins dispatch from the package at project and global scope, the `packageAgents: false` switch in `subagents.json`, and local precedence [PI-7].
34
34
  - **Export.** `systematic pi-subagents <preview|export|refresh|cleanup> --scope project|global` writes flat files that carry `systematic.json` overlays. Package agents load first, so a local file of the same name outranks the packaged one (`node_modules/@tintinweb/pi-subagents/dist/custom-agents.js:36-39,59-64`). No files are written without an explicit command [PI-7].
35
35
 
36
- Packaged personas are config-blind. The only function that sets pi-subagents' agent registry, `registerAgents` (`node_modules/@tintinweb/pi-subagents/dist/agent-types.js:65`), is called only from its own `dist/index.js:361`, so another extension cannot register or filter agent types. Overlays, `disabled_agents` and `agents.<name>.disable` therefore cannot reach a packaged file. `src/pi.ts:143-155` warns once at startup when either is configured. pi-subagents' own `/agents → Disable` turns off one packaged persona, and `packageAgents: false` in `subagents.json` turns off all of them (`node_modules/@tintinweb/pi-subagents/dist/settings.js:133-135`). A top-level `Agent` call runs in the background unless it passes `run_in_background: false` (`node_modules/@tintinweb/pi-subagents/dist/index.js:1187`).
36
+ Packaged personas are config-blind. The only function that sets pi-subagents' agent registry, `registerAgents` (`node_modules/@tintinweb/pi-subagents/dist/agent-types.js:65`), is called only from its own `dist/index.js:361`, so another extension cannot register or filter agent types. Overlays, `disabled_agents` and `agents.<name>.disable` therefore cannot reach a packaged file. `src/pi.ts:165-179` warns once at startup when either is configured. pi-subagents' own `/agents → Disable` turns off one packaged persona, and `packageAgents: false` in `subagents.json` turns off all of them (`node_modules/@tintinweb/pi-subagents/dist/settings.js:133-135`). A top-level `Agent` call runs in the background unless it passes `run_in_background: false` (`node_modules/@tintinweb/pi-subagents/dist/index.js:1187`).
37
37
 
38
38
  Export writes are governed by a manifest (`.systematic-personas.json`) and an exclusive per-root mutation lock (`.systematic-personas.lock`) held for the duration of `export`/`refresh`/`cleanup`; a pre-existing lock is never auto-deleted — a reported lock requires manual verification that no operation is actually running before removal. The export honors the same disable settings as the rest of Systematic: a persona disabled by `disabled_agents` (bare name or `category/name`) or by an `agents.<name>.disable` overlay is not exported [PI-6].
39
39
 
@@ -43,7 +43,7 @@ Every export/refresh/cleanup operation walks every path component from a scope-a
43
43
 
44
44
  The package manifest exposes the extension and skills at `package.json:17-23` (and the packaged personas at `package.json:24-28`), with tests verifying both manifest entries and their packaged paths `tests/unit/package-exports.test.ts:64-84,268-288` [PI-4]. Pi's RPC/JSONL test fixture isolates its environment (`tests/integration/pi.test.ts:349-388`), and the installed runtime exposes environment-specific agent/session directories `node_modules/@earendil-works/pi-coding-agent/dist/config.js:396-398` [PI-5].
45
45
 
46
- Pi honors Systematic's disable settings. `src/pi.ts` loads the merged config once at extension start and passes `disabled_skills` to the skill resolver, so a disabled skill is absent from the `systematic_skill` description and parameter hint and fails to load as unknown. It filters the `systematic_delegate` catalog with `isAgentDisabled`, so a persona disabled by `disabled_agents` (bare name or `category/name`) or by an `agents.<name>.disable` overlay disappears from the tool's description, hint and lookup. The pi-subagents export applies the same predicate, and `tests/unit/disable-parity.test.ts` pins it to what OpenCode's config handler omits [PI-6]. Settings are read at extension start, so a Pi restart applies a change. Pi's `systematic_skill` takes a single `name` parameter and no arguments (`src/pi.ts:215-219`) [PI-3], so a skill that needs arguments, such as `mode:embed` and image paths for `pr-attachments`, reads them from the invoking instruction text instead; OpenCode and Claude Code can also pass skill arguments. Pi's own skill discovery is a separate path: `pi.skills` ships the whole `./skills` directory and Pi's `/skill:name` commands, so those still list and load disabled skills [PI-4], [PI-5]. Pi's skill loading also has no OpenCode-style permission gate — OpenCode's `skill-tool.ts` calls `context.ask({ permission: 'skill', ... })` before returning skill content, but Pi 0.80.6's extension API has no equivalent hook and Systematic's Pi tool implementation does not call one [PI-6]. Those are deliberate honesty boundaries, not implied parity.
46
+ Pi honors Systematic's disable settings. `src/pi.ts` loads the merged config once at extension start and passes `disabled_skills` to the skill resolver, so a disabled skill is absent from the `systematic_skill` description and parameter hint and fails to load as unknown. The same list reaches Pi's bootstrap, which drops the worktree placement rule when `git-worktree` is disabled; nothing else from the config reaches the bootstrap, so Pi still ignores `bootstrap.enabled` and `bootstrap.file` and carries the rule even when `bootstrap.file` is set [PI-8]. It filters the `systematic_delegate` catalog with `isAgentDisabled`, so a persona disabled by `disabled_agents` (bare name or `category/name`) or by an `agents.<name>.disable` overlay disappears from the tool's description, hint and lookup. The pi-subagents export applies the same predicate, and `tests/unit/disable-parity.test.ts` pins it to what OpenCode's config handler omits [PI-6]. Settings are read at extension start, so a Pi restart applies a change. Pi's `systematic_skill` takes a single `name` parameter and no arguments (`src/pi.ts:222-226`) [PI-3], so a skill that needs arguments, such as `mode:embed` and image paths for `pr-attachments`, reads them from the invoking instruction text instead; OpenCode and Claude Code can also pass skill arguments. Pi's own skill discovery is a separate path: `pi.skills` ships the whole `./skills` directory and Pi's `/skill:name` commands, so those still list and load disabled skills [PI-4], [PI-5]. Pi's skill loading also has no OpenCode-style permission gate — OpenCode's `skill-tool.ts` calls `context.ask({ permission: 'skill', ... })` before returning skill content, but Pi 0.80.6's extension API has no equivalent hook and Systematic's Pi tool implementation does not call one [PI-6]. Those are deliberate honesty boundaries, not implied parity.
47
47
 
48
48
  ## Claude Code — Tier 1 shipped adapter
49
49
 
@@ -60,7 +60,17 @@ Behavioral enforcement rides a plugin output style (`force-for-plugin: true`), w
60
60
  | Workflow | Native skills | Skill content and instructions, discovered natively |
61
61
  | Agents | Native subagents | Persona dispatch by name |
62
62
 
63
- Honest capability boundary: output-style enforcement is real and applies automatically on install, but it operates at the system-prompt level — the same layer as any other instruction the model receives — so it is strong guidance, not a hard gate the model cannot violate. Coverage also differs by surface: plugin-bundled hooks fire app-wide, including in Cowork, while a project-local `.claude/settings.json` hook fires in the Code tab but not in Cowork — state or enforcement reaching Cowork sessions has to come through the plugin, not a project-local hook. Integration coverage lives in `tests/integration/claude-code.test.ts` [CC-10].
63
+ Honest capability boundary: output-style enforcement is real and applies automatically on install, but it operates at the system-prompt level — the same layer as any other instruction the model receives — so it is strong guidance, not a hard gate the model cannot violate. Coverage also differs by surface: plugin-bundled hooks fire app-wide, including in Cowork, while a project-local `.claude/settings.json` hook fires in the Code tab but not in Cowork — state or enforcement reaching Cowork sessions has to come through the plugin, not a project-local hook. The output style is also static and the build reads no user config, so it cannot follow `disabled_skills`: it always carries the worktree placement rule, even when `git-worktree` is disabled [CC-13]. Integration coverage lives in `tests/integration/claude-code.test.ts` [CC-10].
64
+
65
+ ## Worktree placement rule — bootstrap paths
66
+
67
+ One short rule ships in the shared bootstrap: create a worktree at `.worktrees/<branch>` under the main repository root with the `git-worktree` skill's script, and follow a different location or tool when the user or a project instruction names one. The script (`skills/git-worktree/scripts/worktree-manager.sh`) is small and non-interactive: `create`, `list`, `switch`, `copy-env` and `cleanup`, with exit codes 0 ok, 1 error, 2 usage and 3 refused, and no stdin reads. `create` places the worktree at `.worktrees/<branch>` under the main root, writes `.worktrees/.gitignore` and never edits the root `.gitignore`, and fails closed on a bare, separate-git-dir or submodule layout; `cleanup` reports and removes only named clean worktrees [WT-2]. The rule lives in `skills/using-systematic/references/worktree-placement.md` and holds no harness identifiers [WT-1]. Each adapter composes it differently:
68
+
69
+ - **OpenCode.** `src/index.ts` always supplies the rule, and `getBootstrapContent` omits it when `git-worktree` is in `disabled_skills`. It sits after the usage template and before the capability profile. `bootstrap.enabled: false` returns no bootstrap, and an existing `bootstrap.file` is returned verbatim with no rule, because the user owns that file [OC-8].
70
+ - **Pi.** The extension supplies the rule and passes `disabled_skills`, and nothing else from the config. The rule is therefore present unless `git-worktree` is disabled, including when `bootstrap.file` is set, because Pi never reads that setting [PI-8].
71
+ - **Claude Code.** The output style is static, so it always carries the rule between the using-systematic body and the profile. The build fails when the rule file is missing [CC-13].
72
+
73
+ Tests drive the real OpenCode plugin init and the real Pi extension init under an isolated home and the real config loader, and pin the built Claude Code output style byte for byte. The script's behavior is covered by unit tests against real throwaway git repositories, also run under stock macOS `/bin/bash` 3.2 [WT-2]. Together these are package-level evidence: no live OpenCode, Pi or Claude Code session has created a worktree from a build carrying the rule.
64
74
 
65
75
  ## Review synthesis pipeline validator — packaged paths
66
76
 
@@ -167,16 +177,18 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
167
177
  - **OC-3** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/todowrite.ts:1-10`.
168
178
  - **OC-4** — `src/lib/config-handler.ts:467-485`.
169
179
  - **OC-5** — `src/lib/skill-tool.ts:41-101`.
170
- - **OC-6** — `ARCHITECTURE.md:75-85` and `agents/`.
180
+ - **OC-6** — `ARCHITECTURE.md:158-164` and `agents/`.
171
181
  - **OC-7** — `src/lib/config-handler.ts:276-289`.
182
+ - **OC-8** — `src/index.ts:60-70` (the rule is always supplied to `getBootstrapContent` together with the loaded config); `src/lib/bootstrap.ts:142-157` (`readWorktreePlacementRule`), `:241-250` (`bootstrap.enabled` and `bootstrap.file` return before the rule is composed), `:262-266` (the rule is omitted when `disabled_skills` contains `git-worktree`), `:276` (placement after the usage template and before the profile); `tests/unit/bootstrap.test.ts:979-1178` (real `loadConfig`: default, `git-worktree` disabled, another skill disabled, qualified name rejected, `bootstrap.enabled: false`, existing and missing `bootstrap.file`); `tests/unit/plugin.test.ts:1400-1499` (real plugin init).
172
183
  - **PI-P** — [Pi profile](skills/using-systematic/references/pi-profile.md#L3-L8).
173
184
  - **PI-1** — `src/lib/pi-delegate-tool.ts:14-18,245-249,279-291`.
174
185
  - **PI-2** — [Pi profile](skills/using-systematic/references/pi-profile.md#L5-L8).
175
- - **PI-3** — `src/pi.ts:187-232`.
186
+ - **PI-3** — `src/pi.ts:217-263`.
176
187
  - **PI-4** — `package.json:17-23`; `tests/unit/package-exports.test.ts:64-84,268-288`.
177
188
  - **PI-5** — `tests/integration/pi.test.ts:349-388`; installed Pi source `node_modules/@earendil-works/pi-coding-agent/dist/config.js:396-398`.
178
- - **PI-6** — `src/pi.ts:157-162` (merged `disabled_skills` passed to the skill resolver); `src/pi.ts:208-221` (`systematic_delegate` catalog filtered with `isAgentDisabled`); `src/lib/config.ts:2103-2115` (`isAgentDisabled`); `src/lib/pi-subagents-export.ts:857-893` (`generateEntries` applies it to the export); `tests/unit/disable-parity.test.ts` (parity with OpenCode's config handler); OpenCode's contrasting permission gate at `src/lib/skill-tool.ts:191-196`.
189
+ - **PI-6** — `src/pi.ts:181-186` (merged `disabled_skills` passed to the skill resolver); `src/pi.ts:242-251` (`systematic_delegate` catalog filtered with `isAgentDisabled`); `src/lib/config.ts:2103-2115` (`isAgentDisabled`); `src/lib/pi-subagents-export.ts:857-893` (`generateEntries` applies it to the export); `tests/unit/disable-parity.test.ts` (parity with OpenCode's config handler); OpenCode's contrasting permission gate at `src/lib/skill-tool.ts:191-196`.
179
190
  - **PI-7** — `package.json:24-28` (the `pi.subagents.agents` declaration); `scripts/build-pi-package-agents.ts` (writes `dist/pi-subagents/agents/` at build time); `tests/unit/package-exports.test.ts:76-83,289-344` (manifest key, `pi-package` keyword, packed files byte-equal to the fixtures); `tests/integration/pi.test.ts:1550-1652` (real Pi host: dispatch from the package at project and global scope, the `packageAgents: false` fallback to `general-purpose`, and a local file outranking the packaged one); `node_modules/@tintinweb/pi-subagents/dist/package-resources.js:90,327-341,432` (which packages are read, trust), `node_modules/@tintinweb/pi-subagents/dist/custom-agents.js:36-39,59-64` (precedence), `node_modules/@tintinweb/pi-subagents/dist/settings.js:133-135` (`packageAgents` gate), `node_modules/@tintinweb/pi-subagents/dist/index.js:361,1187` (registry setter and background default), `node_modules/@tintinweb/pi-subagents/dist/agent-types.js:65` (`registerAgents`); `src/lib/pi-subagents-export.ts` (export lifecycle, manifest, rollback, stale-file removal and retention); `src/lib/pi-subagents-personas.ts` (curated persona list, compatibility screening); `src/cli.ts:1080-1106` (CLI surface: `pi-subagents preview|export|refresh|cleanup`). Tested interop contract: pi-subagents 0.22.0 on Pi 1.3.0.
191
+ - **PI-8** — `src/pi.ts:188-203` (rule supplied, `piConfig.disabled_skills` the only config passed); `src/lib/bootstrap.ts:175-195` (`computeBootstrapContentSafe` keeps `bootstrap.enabled` and `bootstrap.file` at their defaults); `tests/unit/pi.test.ts:1314-1444` (real extension init: default, `git-worktree` disabled, `bootstrap.file` set, `bootstrap.enabled: false`, foreign prompt text kept and not doubled).
180
192
  - **CC-P** — [Claude Code profile](skills/using-systematic/references/claude-code-profile.md#L5-L10).
181
193
  - **CC-1** — [Claude Code skills](https://code.claude.com/docs/en/skills) (`context: fork`); name-based subagent dispatch verified via `claude-code/agents/` and the plugin's invocation convention [CC-9].
182
194
  - **CC-2** — [Claude Code tools reference](https://code.claude.com/docs/en/tools-reference).
@@ -184,10 +196,11 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
184
196
  - **CC-4** — [Claude Code todo tracking](https://code.claude.com/docs/en/agent-sdk/todo-tracking.md).
185
197
  - **CC-5** — [Claude Code skills](https://code.claude.com/docs/en/skills).
186
198
  - **CC-6** — [Claude Code Agent SDK skills](https://code.claude.com/docs/en/agent-sdk/skills.md).
187
- - **CC-9** — `scripts/build-claude-code-plugin.ts:5-27,253-291,345-379` (builder, identifier translation, integrity gate); `.gitignore` (`claude-code/` gitignored build staging).
199
+ - **CC-9** — `scripts/build-claude-code-plugin.ts:5-28,256-368,374-418` (builder, identifier translation, integrity gate); `.gitignore` (`claude-code/` gitignored build staging).
188
200
  - **CC-10** — `tests/integration/claude-code.test.ts`.
189
201
  - **CC-11** — `.github/workflows/main.yaml:263-338` (`publish-claude-code-plugin` job: builds, guards required artifacts, publishes to the orphan `claude-code-plugin` branch on push to `main`).
190
202
  - **CC-12** — `.claude-plugin/marketplace.json:1-18` (marketplace catalog; `systematic` plugin entry sourced from the `claude-code-plugin` branch ref).
203
+ - **CC-13** — `scripts/build-claude-code-plugin.ts:129-157` (the rule file is read after the using-systematic and profile checks, fails the build when missing, and sits between the body and the profile); `tests/unit/build-claude-code-plugin.test.ts:491-514` and the byte-exact output-style fixture in the same file; `tests/integration/claude-code.test.ts:140-162` (real build: the rule appears exactly once between the body and the profile).
191
204
  - **CX-1** — [Codex request_user_input definition](https://github.com/openai/codex/blob/35aaa5d9/codex-rs/tools/src/request_user_input_tool.rs).
192
205
  - **CX-2** — [Codex request_user_input handler](https://github.com/openai/codex/blob/d47b755a/codex-rs/core/src/tools/handlers/request_user_input.rs).
193
206
  - **GE-1** — [Gemini ask-user documentation](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/ask-user.md).
@@ -205,3 +218,5 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
205
218
  - **PA-1** — `tests/unit/pr-attachments-packaging.test.ts` (real Node execution of `skills/pr-attachments/scripts/pr-attachments.mjs` from the npm-packed archive, the OCX-selected tree and the Claude Code generated bundle; nothing under `docs/evidence/` ships).
206
219
  - **PA-2** — `tests/unit/pr-attachments-contract.test.ts` (`skills/pr-attachments/SKILL.md` contract: modes, argument dispatch, `SKILL_DIR` anchor, publishing order, bans).
207
220
  - **PA-3** — `tests/unit/pr-attachments-dry-run.test.ts` (the skill's fenced blocks run offline against a temporary repository and a local bare remote, with the real helper).
221
+ - **WT-1** — `skills/using-systematic/references/worktree-placement.md` (the rule text); `tests/unit/bootstrap.test.ts:1043-1092` (exact text, at most 350 bytes, names `git-worktree` and `.worktrees/<branch>`, keeps the raw-add ban and the carve-out sentence, no harness identifiers, no `CLAUDE.md` literal).
222
+ - **WT-2** — `skills/git-worktree/scripts/worktree-manager.sh` (the script); `tests/unit/git-worktree-manager.test.ts` and `tests/unit/git-worktree-cleanup.test.ts` (placement from the root, a subdirectory and a linked worktree, refused layouts, ignore policy, base resolution, `--no-track`, `list`, `switch`, `copy-env`, `cleanup`; real git in throwaway repositories with a bare `origin`, `TEST_BASH=/bin/bash` runs them under bash 3.2); `tests/unit/git-worktree-skills-contract.test.ts` (the safety and routing terms in `skills/git-worktree/SKILL.md` and the pointers in `ce-review`, `orchestrating-subagents` and `git-clean-gone-branches`). Package probe: the plugin-init, Pi-init and built-output-style tests cited by WT-1, OC-8, PI-8 and CC-13. No live session has run.
package/dist/index.js CHANGED
@@ -91,6 +91,15 @@ function readHarnessProfile(bundledSkillsDir, name) {
91
91
  return null;
92
92
  }
93
93
  }
94
+ function readWorktreePlacementRule(bundledSkillsDir) {
95
+ const rulePath = path.join(bundledSkillsDir, "using-systematic/references/worktree-placement.md");
96
+ try {
97
+ return fs.readFileSync(rulePath, "utf8").trim();
98
+ } catch (error) {
99
+ console.error(`Failed to read worktree placement rule ${rulePath}: ${error instanceof Error ? error.message : String(error)}`);
100
+ return null;
101
+ }
102
+ }
94
103
  function getSkillUsageTemplate() {
95
104
  return `**Skills naming:**
96
105
  - Systematic bundled skills use the \`systematic:\` prefix (e.g., \`systematic:onboarding\`)
@@ -105,7 +114,12 @@ function getSkillUsageTemplate() {
105
114
  Bundled skills ship with the Systematic plugin and are discoverable via \`systematic_skill\`.`;
106
115
  }
107
116
  function getBootstrapContent(config, deps) {
108
- const { bundledSkillsDir, usageTemplate, profileBlock } = deps;
117
+ const {
118
+ bundledSkillsDir,
119
+ usageTemplate,
120
+ worktreePlacementRule,
121
+ profileBlock
122
+ } = deps;
109
123
  if (!config.bootstrap.enabled)
110
124
  return null;
111
125
  if (config.bootstrap.file) {
@@ -121,6 +135,9 @@ function getBootstrapContent(config, deps) {
121
135
  const { body } = parseFrontmatter(fullContent);
122
136
  const content = body.trim();
123
137
  const skillUsage = usageTemplate ?? getSkillUsageTemplate();
138
+ const ruleSection = worktreePlacementRule === undefined || config.disabled_skills.includes("git-worktree") ? "" : `
139
+
140
+ ${worktreePlacementRule}`;
124
141
  const profileSection = profileBlock === undefined ? "" : `
125
142
 
126
143
  ${profileBlock}`;
@@ -131,7 +148,7 @@ You have access to structured engineering workflows via the Systematic plugin.
131
148
 
132
149
  ${content}
133
150
 
134
- ${skillUsage}${profileSection}
151
+ ${skillUsage}${ruleSection}${profileSection}
135
152
  </SYSTEMATIC_WORKFLOWS>`;
136
153
  }
137
154
 
@@ -1058,6 +1075,7 @@ var initializePlugin = async ({ client, directory }) => {
1058
1075
  const config = loadConfig(directory);
1059
1076
  const bootstrapContent = getBootstrapContent(config, {
1060
1077
  bundledSkillsDir,
1078
+ worktreePlacementRule: readWorktreePlacementRule(bundledSkillsDir) ?? undefined,
1061
1079
  profileBlock: readHarnessProfile(bundledSkillsDir, "opencode") ?? undefined
1062
1080
  });
1063
1081
  const configHandler = createConfigHandler({
@@ -21,13 +21,28 @@ export declare const applyBootstrapContent: (output: {
21
21
  export interface BootstrapDeps {
22
22
  bundledSkillsDir: string;
23
23
  usageTemplate?: string;
24
+ /**
25
+ * Placement rule text. Callers pass it whenever the packaged file reads; when
26
+ * the read fails (`readWorktreePlacementRule` returns null after a logged
27
+ * error) they pass nothing and the rule is left out, as with
28
+ * `readHarnessProfile`. `getBootstrapContent` also omits it when
29
+ * `git-worktree` is in `disabled_skills`, so OpenCode and Pi cannot drift.
30
+ */
31
+ worktreePlacementRule?: string;
24
32
  profileBlock?: string;
25
33
  }
26
34
  /** Reads a harness capability profile from the packaged using-systematic references. */
27
35
  export declare function readHarnessProfile(bundledSkillsDir: string, name: string): string | null;
36
+ /** Reads the shared worktree placement rule from the packaged using-systematic references. */
37
+ export declare function readWorktreePlacementRule(bundledSkillsDir: string): string | null;
28
38
  type BootstrapContentConfig = Pick<SystematicConfig, 'bootstrap' | 'disabled_skills'>;
29
- /** Safely computes default bootstrap content, returning null instead of throwing. */
30
- export declare function computeBootstrapContentSafe(deps: BootstrapDeps, reportError?: (error: unknown) => void): string | null;
39
+ /**
40
+ * Safely computes default bootstrap content, returning null instead of throwing.
41
+ *
42
+ * Only `disabledSkills` reaches the composition. `bootstrap.enabled` and
43
+ * `bootstrap.file` stay at their defaults, so Pi keeps ignoring both.
44
+ */
45
+ export declare function computeBootstrapContentSafe(deps: BootstrapDeps, reportError?: (error: unknown) => void, disabledSkills?: readonly string[]): string | null;
31
46
  /** Composes an existing system prompt with nullable bootstrap content; returns null when bootstrapContent is null. */
32
47
  export declare function composeSystemPromptWithBootstrap(existingSystemPrompt: string, bootstrapContent: string | null): string | null;
33
48
  export declare function getBootstrapContent(config: BootstrapContentConfig, deps: BootstrapDeps): string | null;
package/dist/pi.js CHANGED
@@ -3362,13 +3362,22 @@ function readHarnessProfile(bundledSkillsDir, name) {
3362
3362
  return null;
3363
3363
  }
3364
3364
  }
3365
+ function readWorktreePlacementRule(bundledSkillsDir) {
3366
+ const rulePath = path2.join(bundledSkillsDir, "using-systematic/references/worktree-placement.md");
3367
+ try {
3368
+ return fs3.readFileSync(rulePath, "utf8").trim();
3369
+ } catch (error) {
3370
+ console.error(`Failed to read worktree placement rule ${rulePath}: ${error instanceof Error ? error.message : String(error)}`);
3371
+ return null;
3372
+ }
3373
+ }
3365
3374
  var DEFAULT_BOOTSTRAP_CONFIG = {
3366
3375
  bootstrap: { enabled: true },
3367
3376
  disabled_skills: []
3368
3377
  };
3369
- function computeBootstrapContentSafe(deps, reportError) {
3378
+ function computeBootstrapContentSafe(deps, reportError, disabledSkills = []) {
3370
3379
  try {
3371
- return getBootstrapContent(DEFAULT_BOOTSTRAP_CONFIG, deps);
3380
+ return getBootstrapContent({ ...DEFAULT_BOOTSTRAP_CONFIG, disabled_skills: [...disabledSkills] }, deps);
3372
3381
  } catch (error) {
3373
3382
  if (reportError !== undefined) {
3374
3383
  try {
@@ -3404,7 +3413,12 @@ function getSkillUsageTemplate() {
3404
3413
  Bundled skills ship with the Systematic plugin and are discoverable via \`systematic_skill\`.`;
3405
3414
  }
3406
3415
  function getBootstrapContent(config, deps) {
3407
- const { bundledSkillsDir, usageTemplate, profileBlock } = deps;
3416
+ const {
3417
+ bundledSkillsDir,
3418
+ usageTemplate,
3419
+ worktreePlacementRule,
3420
+ profileBlock
3421
+ } = deps;
3408
3422
  if (!config.bootstrap.enabled)
3409
3423
  return null;
3410
3424
  if (config.bootstrap.file) {
@@ -3420,6 +3434,9 @@ function getBootstrapContent(config, deps) {
3420
3434
  const { body } = parseFrontmatter(fullContent);
3421
3435
  const content = body.trim();
3422
3436
  const skillUsage = usageTemplate ?? getSkillUsageTemplate();
3437
+ const ruleSection = worktreePlacementRule === undefined || config.disabled_skills.includes("git-worktree") ? "" : `
3438
+
3439
+ ${worktreePlacementRule}`;
3423
3440
  const profileSection = profileBlock === undefined ? "" : `
3424
3441
 
3425
3442
  ${profileBlock}`;
@@ -3430,7 +3447,7 @@ You have access to structured engineering workflows via the Systematic plugin.
3430
3447
 
3431
3448
  ${content}
3432
3449
 
3433
- ${skillUsage}${profileSection}
3450
+ ${skillUsage}${ruleSection}${profileSection}
3434
3451
  </SYSTEMATIC_WORKFLOWS>`;
3435
3452
  }
3436
3453
 
@@ -11939,8 +11956,9 @@ async function systematicPiExtension(pi, deps = defaultPiExtensionDependencies)
11939
11956
  const bootstrapContent = computeBootstrapContentSafe({
11940
11957
  bundledSkillsDir,
11941
11958
  usageTemplate: PI_BOOTSTRAP_USAGE_TEMPLATE,
11959
+ worktreePlacementRule: readWorktreePlacementRule(bundledSkillsDir) ?? undefined,
11942
11960
  profileBlock: readHarnessProfile(bundledSkillsDir, "pi") ?? undefined
11943
- }, reportPiBootstrapFailure);
11961
+ }, reportPiBootstrapFailure, piConfig.disabled_skills);
11944
11962
  pi.on("before_agent_start", (event) => {
11945
11963
  const systemPrompt = composeSystemPromptWithBootstrap(event.systemPrompt, bootstrapContent);
11946
11964
  if (systemPrompt === null)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fro.bot/systematic",
3
- "version": "3.26.0",
3
+ "version": "3.26.2",
4
4
  "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
5
5
  "type": "module",
6
6
  "homepage": "https://fro.bot/systematic",
@@ -103,10 +103,10 @@
103
103
  }
104
104
  },
105
105
  "devDependencies": {
106
- "@biomejs/biome": "2.5.15",
107
- "@earendil-works/pi-coding-agent": "1.3.0",
108
- "@opencode-ai/plugin": "1.19.3",
109
- "@opencode-ai/sdk": "1.19.3",
106
+ "@biomejs/biome": "2.6.2",
107
+ "@earendil-works/pi-coding-agent": "1.4.0",
108
+ "@opencode-ai/plugin": "1.19.4",
109
+ "@opencode-ai/sdk": "1.19.4",
110
110
  "@semantic-release/exec": "7.1.0",
111
111
  "@tintinweb/pi-subagents": "0.22.0",
112
112
  "@types/bun": "latest",
@@ -120,7 +120,7 @@
120
120
  "rimraf": "6.1.3",
121
121
  "semantic-release": "25.0.9",
122
122
  "semantic-release-export-data": "1.2.0",
123
- "typebox": "1.4.2",
123
+ "typebox": "1.4.3",
124
124
  "typescript": "7.0.2"
125
125
  },
126
126
  "dependencies": {
@@ -129,7 +129,7 @@
129
129
  "zod": "4.6.7"
130
130
  },
131
131
  "overrides": {
132
- "@earendil-works/pi-ai": "1.3.0",
132
+ "@earendil-works/pi-ai": "1.4.0",
133
133
  "brace-expansion": "^5.0.8",
134
134
  "conventional-changelog-writer": ">=9",
135
135
  "devalue": "^5.9.3",
@@ -57,7 +57,7 @@ All tokens are optional. Each one present means one less thing to infer. When ab
57
57
  - **Never edit files or externalize work.** Do not write `.context/systematic/ce-review/<run-id>/`, do not create todo files, and do not commit, push, or create a PR.
58
58
  - **Report-only runs in memory.** Run raw-return structural validation, synthesis, and reporting without writing a run directory, artifact, or ignore file.
59
59
  - **Safe for parallel read-only verification.** `mode:report-only` is the only mode that is safe to run concurrently with browser testing on the same checkout.
60
- - **Do not switch the shared checkout.** If the caller passes an explicit PR or branch target, `mode:report-only` must run in an isolated checkout/worktree or stop instead of running `gh pr checkout` / `git checkout`.
60
+ - **Do not switch the shared checkout.** If the caller passes an explicit PR or branch target, `mode:report-only` must run in an isolated checkout/worktree or stop instead of running `gh pr checkout` / `git checkout`. Create that worktree with the `git-worktree` skill, which places it at `.worktrees/<branch>` under the main repository root.
61
61
  - **Do not overlap mutating review with browser testing on the same checkout.** If a future orchestrator wants fixes, run the mutating review phase after browser testing or in an isolated checkout/worktree.
62
62
 
63
63
  ### Headless mode rules
@@ -68,7 +68,7 @@ All tokens are optional. Each one present means one less thing to infer. When ab
68
68
  - **Return all non-auto findings as structured text output.** Use the headless output envelope format (see Stage 6 below) preserving severity, autofix_class, owner, requires_verification, confidence, pre_existing, and suggested_fix per finding. Enrich with detail-tier fields (why_it_matters, evidence[]) from the validated inline persona returns (see Detail enrichment in Stage 6).
69
69
  - **Write a run artifact** under `.context/systematic/ce-review/<run-id>/` summarizing findings, applied fixes, and advisory outputs. Include the artifact path in the structured output.
70
70
  - **Do not create todo files.** The caller receives structured findings and routes downstream work itself.
71
- - **Do not switch the shared checkout.** If the caller passes an explicit PR or branch target, `mode:headless` must run in an isolated checkout/worktree or stop instead of running `gh pr checkout` / `git checkout`. When stopping, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.`
71
+ - **Do not switch the shared checkout.** If the caller passes an explicit PR or branch target, `mode:headless` must run in an isolated checkout/worktree or stop instead of running `gh pr checkout` / `git checkout`. Create that worktree with the `git-worktree` skill, which places it at `.worktrees/<branch>` under the main repository root. When stopping, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.`
72
72
  - **Not safe for concurrent use on a shared checkout.** Unlike `mode:report-only`, headless mutates files (applies `safe_auto` fixes). Callers must not run headless concurrently with other mutating operations on the same checkout.
73
73
  - **Never commit, push, or create a PR** from headless mode. The caller owns those decisions.
74
74
  - **End with "Review complete" as the terminal signal** so callers can detect completion. If all reviewers fail or time out, emit `Code review degraded (headless mode). Reason: 0 of N reviewers returned results.` followed by "Review complete".
@@ -181,7 +181,7 @@ This path works with any ref — a SHA, `origin/main`, a branch name. Automated
181
181
 
182
182
  **If a PR number or GitHub URL is provided as an argument:**
183
183
 
184
- If `mode:report-only` or `mode:headless` is active, do **not** run `gh pr checkout <number-or-url>` on the shared checkout. For `mode:report-only`, tell the caller: "mode:report-only cannot switch the shared checkout to review a PR target. Run it from an isolated worktree/checkout for that PR, or run report-only with no target argument on the already checked out branch." For `mode:headless`, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.` Stop here unless the review is already running in an isolated checkout.
184
+ If `mode:report-only` or `mode:headless` is active, do **not** run `gh pr checkout <number-or-url>` on the shared checkout. For `mode:report-only`, tell the caller: "mode:report-only cannot switch the shared checkout to review a PR target. Run it from an isolated worktree/checkout for that PR, or run report-only with no target argument on the already checked out branch." For `mode:headless`, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.` Stop here unless the review is already running in an isolated checkout. Create that worktree with the `git-worktree` skill, which places it at `.worktrees/<branch>` under the main repository root.
185
185
 
186
186
  First, verify the worktree is clean before switching branches:
187
187
 
@@ -235,7 +235,7 @@ Extract PR title/body, base branch, and PR URL from `gh pr view`, then extract t
235
235
 
236
236
  Check out the named branch, then diff it against the base branch. Substitute the provided branch name (shown here as `<branch>`).
237
237
 
238
- If `mode:report-only` or `mode:headless` is active, do **not** run `git checkout <branch>` on the shared checkout. For `mode:report-only`, tell the caller: "mode:report-only cannot switch the shared checkout to review another branch. Run it from an isolated worktree/checkout for `<branch>`, or run report-only on the current checkout with no target argument." For `mode:headless`, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.` Stop here unless the review is already running in an isolated checkout.
238
+ If `mode:report-only` or `mode:headless` is active, do **not** run `git checkout <branch>` on the shared checkout. For `mode:report-only`, tell the caller: "mode:report-only cannot switch the shared checkout to review another branch. Run it from an isolated worktree/checkout for `<branch>`, or run report-only on the current checkout with no target argument." For `mode:headless`, emit `Review failed (headless mode). Reason: cannot switch shared checkout. Re-invoke with base:<ref> to review the current checkout, or run from an isolated worktree.` Stop here unless the review is already running in an isolated checkout. Create that worktree with the `git-worktree` skill, which places it at `.worktrees/<branch>` under the main repository root.
239
239
 
240
240
  First, verify the worktree is clean before switching branches:
241
241
 
@@ -19,41 +19,41 @@ required_fields:
19
19
  problem_type:
20
20
  type: enum
21
21
  values:
22
- - build_error # Rails, bundle, compilation errors
23
- - test_failure # Test failures, flaky tests
24
- - runtime_error # Exceptions, crashes during execution
25
- - performance_issue # Slow queries, memory issues, N+1 queries
26
- - database_issue # Migration, query, schema problems
27
- - security_issue # Authentication, authorization, XSS, SQL injection
28
- - ui_bug # Frontend, Stimulus, Turbo issues
29
- - integration_issue # External service, API integration problems
30
- - logic_error # Business logic bugs
22
+ - build_error # Rails, bundle, compilation errors
23
+ - test_failure # Test failures, flaky tests
24
+ - runtime_error # Exceptions, crashes during execution
25
+ - performance_issue # Slow queries, memory issues, N+1 queries
26
+ - database_issue # Migration, query, schema problems
27
+ - security_issue # Authentication, authorization, XSS, SQL injection
28
+ - ui_bug # Frontend, Stimulus, Turbo issues
29
+ - integration_issue # External service, API integration problems
30
+ - logic_error # Business logic bugs
31
31
  - developer_experience # DX issues: workflow, tooling, seed data, dev setup
32
- - workflow_issue # Development process, missing steps, unclear practices
33
- - best_practice # Documenting patterns and practices to follow
34
- - documentation_gap # Missing or inadequate documentation
32
+ - workflow_issue # Development process, missing steps, unclear practices
33
+ - best_practice # Documenting patterns and practices to follow
34
+ - documentation_gap # Missing or inadequate documentation
35
35
  description: "Primary category of the problem"
36
36
 
37
37
  component:
38
38
  type: enum
39
39
  values:
40
- - rails_model # ActiveRecord models
41
- - rails_controller # ActionController
42
- - rails_view # ERB templates, ViewComponent
43
- - service_object # Custom service classes
44
- - background_job # Sidekiq, Active Job
45
- - database # PostgreSQL, migrations, schema
46
- - frontend_stimulus # Stimulus JS controllers
47
- - hotwire_turbo # Turbo Streams, Turbo Drive
48
- - email_processing # Email handling, mailers
49
- - brief_system # Brief generation, summarization
50
- - assistant # AI assistant, prompts
51
- - authentication # Devise, user auth
52
- - payments # Stripe, billing
40
+ - rails_model # ActiveRecord models
41
+ - rails_controller # ActionController
42
+ - rails_view # ERB templates, ViewComponent
43
+ - service_object # Custom service classes
44
+ - background_job # Sidekiq, Active Job
45
+ - database # PostgreSQL, migrations, schema
46
+ - frontend_stimulus # Stimulus JS controllers
47
+ - hotwire_turbo # Turbo Streams, Turbo Drive
48
+ - email_processing # Email handling, mailers
49
+ - brief_system # Brief generation, summarization
50
+ - assistant # AI assistant, prompts
51
+ - authentication # Devise, user auth
52
+ - payments # Stripe, billing
53
53
  - development_workflow # Dev process, seed data, tooling
54
- - testing_framework # Test setup, fixtures, VCR
55
- - documentation # README, guides, inline docs
56
- - tooling # Scripts, generators, CLI tools
54
+ - testing_framework # Test setup, fixtures, VCR
55
+ - documentation # README, guides, inline docs
56
+ - tooling # Scripts, generators, CLI tools
57
57
  description: "CORA component involved"
58
58
 
59
59
  symptoms:
@@ -69,47 +69,47 @@ required_fields:
69
69
  root_cause:
70
70
  type: enum
71
71
  values:
72
- - missing_association # Incorrect Rails associations
73
- - missing_include # Missing eager loading (N+1)
74
- - missing_index # Database performance issue
75
- - wrong_api # Using deprecated/incorrect Rails API
76
- - scope_issue # Incorrect query scope or filtering
77
- - thread_violation # Real-time unsafe operation
78
- - async_timing # Async/background job timing
79
- - memory_leak # Memory leak or excessive allocation
80
- - config_error # Configuration or environment issue
81
- - logic_error # Algorithm/business logic bug
82
- - test_isolation # Test isolation or fixture issue
83
- - missing_validation # Missing model validation
84
- - missing_permission # Authorization check missing
72
+ - missing_association # Incorrect Rails associations
73
+ - missing_include # Missing eager loading (N+1)
74
+ - missing_index # Database performance issue
75
+ - wrong_api # Using deprecated/incorrect Rails API
76
+ - scope_issue # Incorrect query scope or filtering
77
+ - thread_violation # Real-time unsafe operation
78
+ - async_timing # Async/background job timing
79
+ - memory_leak # Memory leak or excessive allocation
80
+ - config_error # Configuration or environment issue
81
+ - logic_error # Algorithm/business logic bug
82
+ - test_isolation # Test isolation or fixture issue
83
+ - missing_validation # Missing model validation
84
+ - missing_permission # Authorization check missing
85
85
  - missing_workflow_step # Skipped or undocumented workflow step
86
86
  - inadequate_documentation # Missing or unclear documentation
87
- - missing_tooling # Lacking helper scripts or automation
88
- - incomplete_setup # Missing seed data, fixtures, or config
87
+ - missing_tooling # Lacking helper scripts or automation
88
+ - incomplete_setup # Missing seed data, fixtures, or config
89
89
  description: "Fundamental cause of the problem"
90
90
 
91
91
  resolution_type:
92
92
  type: enum
93
93
  values:
94
- - code_fix # Fixed by changing source code
95
- - migration # Fixed by database migration
96
- - config_change # Fixed by changing configuration
97
- - test_fix # Fixed by correcting tests
98
- - dependency_update # Fixed by updating gem/dependency
99
- - environment_setup # Fixed by environment configuration
94
+ - code_fix # Fixed by changing source code
95
+ - migration # Fixed by database migration
96
+ - config_change # Fixed by changing configuration
97
+ - test_fix # Fixed by correcting tests
98
+ - dependency_update # Fixed by updating gem/dependency
99
+ - environment_setup # Fixed by environment configuration
100
100
  - workflow_improvement # Improved development workflow or process
101
101
  - documentation_update # Added or updated documentation
102
- - tooling_addition # Added helper script or automation
103
- - seed_data_update # Updated db/seeds.rb or fixtures
102
+ - tooling_addition # Added helper script or automation
103
+ - seed_data_update # Updated db/seeds.rb or fixtures
104
104
  description: "Type of fix applied"
105
105
 
106
106
  severity:
107
107
  type: enum
108
108
  values:
109
- - critical # Blocks production or development (build fails, data loss)
110
- - high # Impairs core functionality (feature broken, security issue)
111
- - medium # Affects specific feature (UI broken, performance impact)
112
- - low # Minor issue or edge case
109
+ - critical # Blocks production or development (build fails, data loss)
110
+ - high # Impairs core functionality (feature broken, security issue)
111
+ - medium # Affects specific feature (UI broken, performance impact)
112
+ - low # Minor issue or edge case
113
113
  description: "Impact severity"
114
114
 
115
115
  optional_fields:
@@ -29,7 +29,7 @@ If the script outputs `__NONE__`, report that no stale branches were found and s
29
29
 
30
30
  ### Step 2: Present branches and ask for confirmation
31
31
 
32
- Show the user the list of branches that will be deleted. Format as a simple list:
32
+ Show the user the list of branches that will be deleted, and say what happens to their worktrees. Format as a simple list:
33
33
 
34
34
  ```
35
35
  These local branches have been deleted from the remote:
@@ -38,6 +38,8 @@ These local branches have been deleted from the remote:
38
38
  - bugfix/resolved-issue
39
39
  - experiment/abandoned
40
40
 
41
+ Any of them that has a worktree with modified or untracked files, or a locked worktree, is skipped and kept. Ignored files (such as .env files and node_modules) in the worktrees that are removed are deleted.
42
+
41
43
  Delete all of them? (y/n)
42
44
  ```
43
45
 
@@ -47,21 +49,29 @@ This is a yes-or-no decision on the entire list -- do not offer multi-selection
47
49
 
48
50
  ### Step 3: Delete confirmed branches
49
51
 
50
- If the user confirms, delete each branch. For each branch:
52
+ If the user confirms, run `git worktree list --porcelain` once. Each entry has a `worktree <path>` line and, for a branch checkout, a `branch refs/heads/<name>` line. The first entry is the main checkout. For each branch:
51
53
 
52
- 1. Check if it has an associated worktree (`git worktree list | grep "\\[$branch\\]"`)
53
- 2. If a worktree exists and is not the main repo root, remove it first: `git worktree remove --force "$worktree_path"`
54
- 3. Delete the branch: `git branch -D "$branch"`
54
+ 1. Find its worktree by exact match: the entry whose `branch` line is exactly `branch refs/heads/<branch>`. Do not use grep or a substring match, so `feature/a` never matches `feature/ab`.
55
+ 2. If that entry is the main checkout, report `skipped: checked out in main checkout` and go to the next branch. Never switch the main checkout to another branch.
56
+ 3. If that entry is another worktree and `pwd -P` is the worktree or inside it, report `skipped: current worktree`, keep its branch, and go to the next branch.
57
+ 4. If the entry is another worktree that step 3 did not skip, remove it with `git worktree remove "$path"`. Never use the force option. If git refuses, report `skipped: <git reason>` and do not run `git branch -D` for that branch, because the worktree still has it checked out.
58
+ 5. If the branch has no worktree, or the removal succeeded, delete the branch: `git branch -D "$branch"`
55
59
 
56
60
  Report results as you go:
57
61
 
58
62
  ```
59
63
  Removed worktree: .worktrees/feature/old-thing
60
64
  Deleted branch: feature/old-thing
61
- Deleted branch: bugfix/resolved-issue
65
+ skipped: .worktrees/bugfix/resolved-issue contains modified or untracked files
62
66
  Deleted branch: experiment/abandoned
63
67
 
64
- Cleaned up 3 branches.
68
+ Cleaned up 2 branches, skipped 1.
65
69
  ```
66
70
 
71
+ The `git-worktree` skill creates worktrees under `.worktrees/<branch>` at the main repository root. Its cleanup command is the place to remove one of those worktrees with its stricter checks.
72
+
73
+ This skill finds worktrees anywhere, so it does not call that script.
74
+
75
+ `git branch -D` also deletes an unmerged gone branch. Checking merge state is out of scope for this skill.
76
+
67
77
  If the user declines, acknowledge and stop without deleting anything.
@@ -74,12 +74,13 @@ When the command does not print `saved`, the temp file could not be created or t
74
74
  **Generate the updated title and body** — using the PR URL from DU-2 and the commit range it covers, write an updated PR title and body. The URL preserves repo/PR identity even when invoked from a worktree or subdirectory. If the user provided a focus (e.g., "include the benchmarking results"), incorporate it into the generated content. Write the body to an OS temp file:
75
75
 
76
76
  ```bash
77
- BODY_FILE=$(mktemp /tmp/pr-body-XXXXXX.md)
78
- cat > "$BODY_FILE" << 'EOF'
77
+ BODY_FILE=$(mktemp) && cat > "$BODY_FILE" << 'EOF' && echo "saved $BODY_FILE"
79
78
  <generated body>
80
79
  EOF
81
80
  ```
82
81
 
82
+ When the command does not print `saved` and the path, the temp file could not be created or written. Stop and apply nothing. Tell the user why, remove the old file, and ask how to proceed. Use the printed path as the body file below.
83
+
83
84
  If the PR is not open or the commit range cannot be resolved, report the issue and stop.
84
85
 
85
86
  **Evidence decision:** Preserve any existing `## Demo` or `## Screenshots` block from the current body by default. Carry the `## Demo` section with `mode:carry`, by following Carrying the Demo section: `old=` is the old body file saved above, and `new=` is the body file written above. The carry always runs, and it runs before the compare-and-confirm step. If the user's focus asks to refresh or remove evidence, honor that intent and skip the carry. When the carry ends, remove the old file:
@@ -95,10 +96,10 @@ Do not offer to publish images here. If the user asks to attach local images, ro
95
96
  - If the user provided a focus, confirm it was addressed.
96
97
  - Ask the user to confirm before applying.
97
98
 
98
- If confirmed, apply with the returned title and body file:
99
+ If confirmed, apply with the returned title and body file. `--body-file` makes `gh` read the file as written, so trailing newlines and shell-special characters in the body survive:
99
100
 
100
101
  ```bash
101
- gh pr edit --title "<returned title>" --body "$(cat "<returned body_file>")"
102
+ gh pr edit --title "<returned title>" --body-file "<returned body_file>"
102
103
  ```
103
104
 
104
105
  Report the PR URL.
@@ -233,11 +234,11 @@ When evidence is not possible (docs-only, markdown-only, changelog-only, release
233
234
  - **Title**: conventional-commit format, under 72 characters, describing the value delivered (not the implementation).
234
235
  - **Body**: value-first narrative scaled to the change size. Apply the writing principles, commit classification, sizing, and narrative framing described in this skill. Write the body to an OS temp file:
235
236
  ```bash
236
- BODY_FILE=$(mktemp /tmp/pr-body-XXXXXX.md)
237
- cat > "$BODY_FILE" << 'EOF'
237
+ BODY_FILE=$(mktemp) && cat > "$BODY_FILE" << 'EOF' && echo "saved $BODY_FILE"
238
238
  <generated body>
239
239
  EOF
240
240
  ```
241
+ When the command does not print `saved` and the path, the temp file could not be created or written. Stop, and do not create or edit the PR, because there is no body to apply. Use the printed path as `<body_file>` below.
241
242
  - Splice any captured evidence as a `## Demo` section into the body file before applying. For the file that **Publish local images** returned, append it with the shell and delete it once it is appended, so no SHA is retyped:
242
243
  ```bash
243
244
  printf '\n' >> "<body_file>" && cat "<demo_file>" >> "<body_file>" && rm -f "<demo_file>"
@@ -261,10 +262,10 @@ If the branch diff is empty or the base ref is unresolved, report the issue and
261
262
  Using the title and body file generated in Step 6:
262
263
 
263
264
  ```bash
264
- gh pr create --title "<title>" --body "$(cat "<body_file>")"
265
+ gh pr create --title "<title>" --body-file "<body_file>"
265
266
  ```
266
267
 
267
- Keep the title under 72 characters.
268
+ Keep the title under 72 characters. Pass the body with `--body-file`, never through command substitution, which strips trailing newlines.
268
269
 
269
270
  #### Existing PR (found in Step 3)
270
271
 
@@ -287,7 +288,7 @@ The new commits are already on the PR from Step 5. Report the PR URL, then ask w
287
288
  **Apply.** Only after `status=ok` or `status=absent`. The carry step edits the body file in place, so the apply step is the same:
288
289
 
289
290
  ```bash
290
- gh pr edit --title "<title>" --body "$(cat "<body_file>")"
291
+ gh pr edit --title "<title>" --body-file "<body_file>"
291
292
  ```
292
293
 
293
294
  - If **no** -- skip Step 6 entirely and finish. Do not run evidence capture when the user declined the rewrite.