@fro.bot/systematic 3.25.2 → 3.26.1

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
@@ -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 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. 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.
47
47
 
48
48
  ## Claude Code — Tier 1 shipped adapter
49
49
 
@@ -90,6 +90,51 @@ layouts are proven by package-tree execution under real Node, not by running the
90
90
  harness. This is package-tree execution plus one real OpenCode scripted host,
91
91
  not cross-harness runtime parity.
92
92
 
93
+ ## PR attachments helper — packaged paths
94
+
95
+ The `pr-attachments` skill ships one self-contained Node helper,
96
+ `skills/pr-attachments/scripts/pr-attachments.mjs`. It imports only `node:` builtins and has no
97
+ relative imports. Eight subcommands (`classify`, `splice`, `extract`, `urls`, `repin-rewrite`,
98
+ `pins`, `cleanup-set`, `verify`) each read one JSON object on stdin and write one JSON object on
99
+ stdout, with exit code 0 for success, 1 for a domain failure and 2 for a usage error. The skill
100
+ invokes the helper as `node "$SKILL_DIR/scripts/pr-attachments.mjs"`, so the file mode bit is not
101
+ part of the contract. The helper needs `node` 18+ on PATH. A Bun-only OpenCode install does not
102
+ have it, and the skill stops with its state reported rather than running the helper's work by hand.
103
+ Recorded execution evidence for this surface:
104
+
105
+ - **npm / OpenCode / Pi package layout** — real Node execution from an extracted
106
+ `npm pack --ignore-scripts` archive, resolving the helper through its packaged
107
+ `skills/pr-attachments` directory [PA-1].
108
+ - **OCX-selected tree** — real Node execution from the `pr-attachments` component's declared file
109
+ selection, with a negative control for a selection that omits the helper [PA-1].
110
+ - **Claude Code generated bundle** — real Node execution from the output written by
111
+ `generatePluginFiles`/`writePluginFiles`, with the helper byte-identical to source [PA-1].
112
+ - **Skill contract** — `SKILL.md` is parsed as data: the mode and dispatch tables, the `SKILL_DIR`
113
+ anchor in every fenced block, the publishing order, and the bans on force-pushes, blanket staging,
114
+ inline bodies and hand-run `git rm` [PA-2].
115
+ - **Offline dry run** — the fenced blocks of `SKILL.md` run against a temporary repository with a
116
+ local bare remote and the real helper: the pathspec commit, the file-set assertion, the explicit
117
+ refspec push, the rejected non-fast-forward push, carry mode and cleanup [PA-3]. Git attributes are
118
+ covered the same way: `docs/evidence/** text eol=lf` stops at the guard, `core.autocrlf` and a
119
+ rewriting commit hook are caught by the staged and committed blob checks, and none of them reaches
120
+ the remote. A merge that resolved an image selects the merge as the pin, not its parent. The
121
+ private-repository blob check runs against a stand-in `gh` that answers from the local repository:
122
+ match, mismatch, absent file, bounded retries and the `local` expectation used by re-pin mode.
123
+
124
+ One live OpenCode session ran a build of this branch, loaded as a `file://` plugin with isolated
125
+ config and no user-global plugins. It loaded `systematic:pr-attachments` through `systematic_skill`,
126
+ ran `classify` against a public pull request, and asked the scrub confirmation before any commit or
127
+ push. It stopped there. The remote branch and the pull request body were unchanged afterwards. The
128
+ PR flow, re-pin, the `--body-file` round trip and the private-repository blob form were also run by
129
+ hand against real GitHub repositories, which exercised GitHub's raw-content serving. None of that
130
+ live evidence is reproduced by the test suite.
131
+
132
+ The offline dry run uses no real `gh` and no network. The helper's `verify` subcommand is tested
133
+ against a local HTTP server (`tests/unit/pr-attachments-verify.test.ts`). No live Pi, OCX or Claude
134
+ Code host was executed. `SKILL_DIR` resolution on Pi and Claude Code is evidenced from the package
135
+ tree only. These layouts are proven by package-tree execution under real Node and by a scripted run
136
+ of the skill's own commands, plus one live OpenCode run, not cross-harness runtime parity.
137
+
93
138
  ## Codex CLI — Tier 2 documented portability target
94
139
 
95
140
  The supplied evidence verifies only `request_user_input`: its definition names the tool [CX-1], and its handler blocks while restricting use to the root thread, rejecting subagents [CX-2]. Delegation, task tracking, skill loading, and skills-file support were not checked and remain **UNVERIFIED**. Systematic ships no Codex adapter or profile.
@@ -157,3 +202,6 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
157
202
  - **GH-8** — [Copilot `AGENTS.md` support](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/).
158
203
  - **RV-1** — `tests/unit/ce-review-validator-packaging.test.ts` (real Node execution from the npm/OpenCode/Pi package tree, the OCX-selected tree, and the Claude Code generated bundle).
159
204
  - **RV-2** — `tests/integration/ce-review-return-validation.test.ts` (real OpenCode scripted host invoking the packaged `skills/ce-review/scripts/validate-review.mjs` through its `SKILL_DIR` anchor).
205
+ - **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
+ - **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
+ - **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).
package/README.md CHANGED
@@ -29,7 +29,7 @@ You want AI that follows your process, not just your prompts. You want repeatabl
29
29
 
30
30
  ## What You Get
31
31
 
32
- Systematic is a compound-engineering loop: brainstorm, plan, work, review — each phase a structured skill that guides the AI through requirements exploration, implementation planning, execution, and code review, capturing what was learned along the way. It ships 31 bundled skills and 37 specialized agents for architecture, security, performance, design, and code review.
32
+ Systematic is a compound-engineering loop: brainstorm, plan, work, review — each phase a structured skill that guides the AI through requirements exploration, implementation planning, execution, and code review, capturing what was learned along the way. It ships 33 bundled skills and 37 specialized agents for architecture, security, performance, design, and code review.
33
33
 
34
34
  The workflow runs on three harnesses from one source: [OpenCode](https://opencode.ai/), [Pi](https://github.com/earendil-works/pi-coding-agent), and Claude Code. Each gets a native install path; skill and agent content is identical across all three.
35
35
 
package/dist/cli.js CHANGED
@@ -35,7 +35,7 @@ import {
35
35
  findCommandsInDir,
36
36
  findSkillsInDir,
37
37
  discoverSkills
38
- } from "./index-bmsgc2em.js";
38
+ } from "./index-1dyb2x0z.js";
39
39
  var __defProp = Object.defineProperty;
40
40
  var __returnValue = (v) => v;
41
41
  function __exportSetter(name, newValue) {
@@ -1491,6 +1491,7 @@ var BUNDLED_SKILL_NAMES = [
1491
1491
  "lfg",
1492
1492
  "onboarding",
1493
1493
  "orchestrating-subagents",
1494
+ "pr-attachments",
1494
1495
  "report-bug-ce",
1495
1496
  "reproduce-bug",
1496
1497
  "resolve-pr-feedback",
package/dist/index.js CHANGED
@@ -15,7 +15,7 @@ import {
15
15
  extractCommandFrontmatter,
16
16
  findSkillsInDir,
17
17
  discoverSkills
18
- } from "./index-bmsgc2em.js";
18
+ } from "./index-1dyb2x0z.js";
19
19
 
20
20
  // src/index.ts
21
21
  import fs6 from "fs";
@@ -1,5 +1,5 @@
1
1
  export declare const BUNDLED_AGENT_NAMES: readonly ['adversarial-document-reviewer', 'adversarial-reviewer', 'agent-native-reviewer', 'api-contract-reviewer', 'architecture-strategist', 'best-practices-researcher', 'bug-reproduction-validator', 'cli-readiness-reviewer', 'code-simplicity-reviewer', 'coherence-reviewer', 'correctness-reviewer', 'data-migrations-reviewer', 'deployment-verification-agent', 'design-iterator', 'design-lens-reviewer', 'feasibility-reviewer', 'framework-docs-researcher', 'git-history-analyzer', 'issue-intelligence-analyst', 'kieran-typescript-reviewer', 'learnings-researcher', 'maintainability-reviewer', 'pattern-recognition-specialist', 'performance-reviewer', 'pr-comment-resolver', 'previous-comments-reviewer', 'product-lens-reviewer', 'project-standards-reviewer', 'reliability-reviewer', 'repo-research-analyst', 'scope-guardian-reviewer', 'security-lens-reviewer', 'security-reviewer', 'slack-researcher', 'spec-flow-analyzer', 'systematic-implementer', 'testing-reviewer'];
2
2
  export declare const BUNDLED_AGENT_QUALIFIED_IDS: readonly ['design/design-iterator', 'document-review/adversarial-document-reviewer', 'document-review/coherence-reviewer', 'document-review/design-lens-reviewer', 'document-review/feasibility-reviewer', 'document-review/product-lens-reviewer', 'document-review/scope-guardian-reviewer', 'document-review/security-lens-reviewer', 'research/best-practices-researcher', 'research/framework-docs-researcher', 'research/git-history-analyzer', 'research/issue-intelligence-analyst', 'research/learnings-researcher', 'research/repo-research-analyst', 'research/slack-researcher', 'review/adversarial-reviewer', 'review/agent-native-reviewer', 'review/api-contract-reviewer', 'review/architecture-strategist', 'review/cli-readiness-reviewer', 'review/code-simplicity-reviewer', 'review/correctness-reviewer', 'review/data-migrations-reviewer', 'review/deployment-verification-agent', 'review/kieran-typescript-reviewer', 'review/maintainability-reviewer', 'review/pattern-recognition-specialist', 'review/performance-reviewer', 'review/previous-comments-reviewer', 'review/project-standards-reviewer', 'review/reliability-reviewer', 'review/security-reviewer', 'review/testing-reviewer', 'workflow/bug-reproduction-validator', 'workflow/pr-comment-resolver', 'workflow/spec-flow-analyzer', 'workflow/systematic-implementer'];
3
- export declare const BUNDLED_SKILL_NAMES: readonly ['agent-browser', 'agent-native-architecture', 'agent-native-audit', 'ce:brainstorm', 'ce:compound', 'ce:compound-refresh', 'ce:ideate', 'ce:plan', 'ce:review', 'ce:review-cleanup', 'ce:work', 'compound-docs', 'deepen-plan', 'deploy-docs', 'document-review', 'frontend-design', 'git-clean-gone-branches', 'git-commit', 'git-commit-push-pr', 'git-worktree', 'lfg', 'onboarding', 'orchestrating-subagents', 'report-bug-ce', 'reproduce-bug', 'resolve-pr-feedback', 'slfg', 'test-browser', 'test-driven-development', 'todos', 'using-systematic', 'writing-skills'];
3
+ export declare const BUNDLED_SKILL_NAMES: readonly ['agent-browser', 'agent-native-architecture', 'agent-native-audit', 'ce:brainstorm', 'ce:compound', 'ce:compound-refresh', 'ce:ideate', 'ce:plan', 'ce:review', 'ce:review-cleanup', 'ce:work', 'compound-docs', 'deepen-plan', 'deploy-docs', 'document-review', 'frontend-design', 'git-clean-gone-branches', 'git-commit', 'git-commit-push-pr', 'git-worktree', 'lfg', 'onboarding', 'orchestrating-subagents', 'pr-attachments', 'report-bug-ce', 'reproduce-bug', 'resolve-pr-feedback', 'slfg', 'test-browser', 'test-driven-development', 'todos', 'using-systematic', 'writing-skills'];
4
4
  export type BundledAgentName = (typeof BUNDLED_AGENT_NAMES)[number];
5
5
  export type BundledSkillName = (typeof BUNDLED_SKILL_NAMES)[number];
package/dist/pi.js CHANGED
@@ -3546,6 +3546,7 @@ var BUNDLED_SKILL_NAMES = [
3546
3546
  "lfg",
3547
3547
  "onboarding",
3548
3548
  "orchestrating-subagents",
3549
+ "pr-attachments",
3549
3550
  "report-bug-ce",
3550
3551
  "reproduce-bug",
3551
3552
  "resolve-pr-feedback",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fro.bot/systematic",
3
- "version": "3.25.2",
3
+ "version": "3.26.1",
4
4
  "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
5
5
  "type": "module",
6
6
  "homepage": "https://fro.bot/systematic",
@@ -103,8 +103,8 @@
103
103
  }
104
104
  },
105
105
  "devDependencies": {
106
- "@biomejs/biome": "2.5.15",
107
- "@earendil-works/pi-coding-agent": "1.3.0",
106
+ "@biomejs/biome": "2.6.2",
107
+ "@earendil-works/pi-coding-agent": "1.4.0",
108
108
  "@opencode-ai/plugin": "1.19.3",
109
109
  "@opencode-ai/sdk": "1.19.3",
110
110
  "@semantic-release/exec": "7.1.0",
@@ -129,10 +129,11 @@
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",
136
+ "dompurify": "~3.4.17",
136
137
  "fast-uri": "~3.1.7",
137
138
  "markdown-it": "~14.3.3",
138
139
  "smol-toml": "~1.9.0",
@@ -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:
@@ -63,34 +63,43 @@ Use the current branch and existing PR check from context. If the current branch
63
63
 
64
64
  ### DU-3: Write and apply the updated description
65
65
 
66
- Read the current PR description to drive the compare-and-confirm step later:
66
+ Read the current PR description. It drives the compare-and-confirm step later, and it is saved to an old body file for the carry:
67
67
 
68
68
  ```bash
69
- gh pr view --json body --jq '.body'
69
+ OLD_BODY_FILE=$(mktemp) && gh pr view "<PR URL>" --json body --jq '.body' > "$OLD_BODY_FILE" && cat "$OLD_BODY_FILE" && echo saved
70
70
  ```
71
71
 
72
+ When the command does not print `saved`, the temp file could not be created or the `gh` read failed. Stop and apply nothing, because the current description was never saved. Tell the user why, remove the old file, and ask how to proceed.
73
+
72
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:
73
75
 
74
76
  ```bash
75
- BODY_FILE=$(mktemp /tmp/pr-body-XXXXXX.md)
76
- cat > "$BODY_FILE" << 'EOF'
77
+ BODY_FILE=$(mktemp) && cat > "$BODY_FILE" << 'EOF' && echo "saved $BODY_FILE"
77
78
  <generated body>
78
79
  EOF
79
80
  ```
80
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
+
81
84
  If the PR is not open or the commit range cannot be resolved, report the issue and stop.
82
85
 
83
- **Evidence decision:** Preserve any existing `## Demo` or `## Screenshots` block from the current body by default. If the user's focus asks to refresh or remove evidence, honor that intent.
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:
87
+
88
+ ```bash
89
+ rm -f "$OLD_BODY_FILE"
90
+ ```
91
+
92
+ Do not offer to publish images here. If the user asks to attach local images, route that request to `systematic:pr-attachments` in PR mode, with the image paths as its only tokens. PR mode writes the Demo section itself, and a later rewrite carries it through.
84
93
 
85
94
  **Compare and confirm** — briefly explain what the new description covers differently from the old one. This helps the user decide whether to apply; the description itself does not narrate these differences. Summarize from the body already in context (from the bash call that wrote `body_file`); do not `cat` the temp file, which would re-emit the body.
86
95
 
87
96
  - If the user provided a focus, confirm it was addressed.
88
97
  - Ask the user to confirm before applying.
89
98
 
90
- 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:
91
100
 
92
101
  ```bash
93
- gh pr edit --title "<returned title>" --body "$(cat "<returned body_file>")"
102
+ gh pr edit --title "<returned title>" --body-file "<returned body_file>"
94
103
  ```
95
104
 
96
105
  Report the PR URL.
@@ -147,7 +156,8 @@ If the PR check returned `state: OPEN`, note the URL -- this is the existing-PR
147
156
 
148
157
  1. If on the default branch, create a feature branch first with `git checkout -b <branch-name>`.
149
158
  2. Scan changed files for naturally distinct concerns. If files clearly group into separate logical changes, create separate commits (2-3 max). Group at the file level only (no `git add -p`). When ambiguous, one commit is fine.
150
- 3. Stage and commit each group in a single call. Avoid `git add -A` or `git add .`. Follow conventions from Step 2:
159
+ 3. Never stage an untracked image file without asking. Image files are PNG, JPEG, GIF and WebP, such as `.png` or `.jpg`. A screenshot meant for the PR description is evidence, not part of the change, so it stays out of the feature commit. When untracked images exist, ask the evidence-source question from Step 6 first, and do not ask again in Step 6. Stage an image only when the user says it is part of the change.
160
+ 4. Stage and commit each group in a single call. Avoid `git add -A` or `git add .`. Follow conventions from Step 2:
151
161
  ```bash
152
162
  git add file1 file2 file3 && git commit -m "$(cat <<'EOF'
153
163
  commit message here
@@ -199,8 +209,24 @@ Use this branch diff (not the working-tree diff) for the evidence decision. If t
199
209
  **Evidence decision (before delegation).** If the branch diff changes observable behavior (UI, CLI output, API behavior with runnable code, generated artifacts, workflow output) and evidence is not otherwise blocked (unavailable credentials, paid services, deploy-only infrastructure, hardware), ask: "This PR has observable behavior. Capture evidence for the PR description?"
200
210
 
201
211
  - **Use existing evidence** -- ask for the URL or markdown embed, then splice it into the PR body as a `## Demo` section before applying.
212
+ - **Publish local images** -- publish image files from this machine as commit-pinned embeds. Ask for the image paths, or offer the untracked images found in Step 4. Then load the `systematic:pr-attachments` skill in embed mode. State the tokens in the instruction text only, because some hosts pass no skill arguments and the same tokens in two places would be read twice. For example: `mode:embed shots/a.png "shots/b c.png"`. Wrap a path that has spaces in double quotes.
202
213
  - **Skip** -- proceed with no evidence section.
203
214
 
215
+ The skill ends with one status line:
216
+
217
+ ```text
218
+ pr-attachments: status=ok evidence_sha=<40-hex> demo_file=<path> images=<count>
219
+ pr-attachments: status=failed evidence=<pushed|local|none> reason=<reason>
220
+ ```
221
+
222
+ - `status=ok`: take `demo_file` from the line. The file holds the Demo section. Keep it for the splice below. The narrative range below does not use `evidence_sha`.
223
+ - `status=failed` with `evidence=pushed`: the evidence files are pushed but unreferenced. Tell the user the reason, and keep the image paths for the retry command in Step 8. Then continue without evidence.
224
+ - `status=failed` with `evidence=local`: the evidence commit is local and unpushed. It exists only on this machine, and the remote does not hold it. Tell the user the reason and that the branch needs a push (after a fetch and a rebase or merge, when the push was rejected) before the images can be published. Then continue without evidence.
225
+ - `status=failed` with `reason=blob-mismatch`: the exception to the push advice above. The local evidence commit holds an image that git changed on its way in, for example through a `.gitattributes` setting or a hook. Tell the user it must not be pushed as it is, and continue without evidence.
226
+ - `status=failed` with `evidence=none`: nothing was published. Tell the user the reason, then continue without evidence.
227
+
228
+ **Fallback.** If loading `systematic:pr-attachments` fails, or it loads but sees no `mode:` token and stops without a status line, offer only the two existing options: **Use existing evidence** and **Skip**.
229
+
204
230
  When evidence is not possible (docs-only, markdown-only, changelog-only, release metadata, CI/config-only, test-only, or pure internal refactors), skip without asking.
205
231
 
206
232
  **Generate title and body.** Using the branch diff and commit log, write a PR title and body directly:
@@ -208,12 +234,24 @@ When evidence is not possible (docs-only, markdown-only, changelog-only, release
208
234
  - **Title**: conventional-commit format, under 72 characters, describing the value delivered (not the implementation).
209
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:
210
236
  ```bash
211
- BODY_FILE=$(mktemp /tmp/pr-body-XXXXXX.md)
212
- cat > "$BODY_FILE" << 'EOF'
237
+ BODY_FILE=$(mktemp) && cat > "$BODY_FILE" << 'EOF' && echo "saved $BODY_FILE"
213
238
  <generated body>
214
239
  EOF
215
240
  ```
216
- - Splice any captured evidence as a `## Demo` section into the body file before applying.
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.
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:
243
+ ```bash
244
+ printf '\n' >> "<body_file>" && cat "<demo_file>" >> "<body_file>" && rm -f "<demo_file>"
245
+ ```
246
+
247
+ **Narrative range after publishing.** An evidence commit on the branch is housekeeping, not part of the change. Use the same two commands on every path: `status=ok`, `status=failed` with `evidence=pushed`, and no publish at all. Both leave `docs/evidence/**` out by path, so a commit that touches only evidence files drops out of the log on its own, and later feature commits stay in:
248
+
249
+ ```bash
250
+ git log --oneline <base-remote>/<base-branch>..HEAD -- . ':(exclude)docs/evidence/**'
251
+ git diff <base-remote>/<base-branch>...HEAD -- . ':(exclude)docs/evidence/**'
252
+ ```
253
+
254
+ Fill in the real values each time. No shell variable carries values from one call to the next.
217
255
 
218
256
  If the branch diff is empty or the base ref is unresolved, report the issue and stop — do not create or edit the PR.
219
257
 
@@ -224,19 +262,33 @@ If the branch diff is empty or the base ref is unresolved, report the issue and
224
262
  Using the title and body file generated in Step 6:
225
263
 
226
264
  ```bash
227
- gh pr create --title "<title>" --body "$(cat "<body_file>")"
265
+ gh pr create --title "<title>" --body-file "<body_file>"
228
266
  ```
229
267
 
230
- 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.
231
269
 
232
270
  #### Existing PR (found in Step 3)
233
271
 
234
272
  The new commits are already on the PR from Step 5. Report the PR URL, then ask whether to rewrite the description.
235
273
 
236
- - If **yes**, run Step 6 now to generate the title and body file (passing the existing PR URL for context), then apply:
274
+ - If **yes**, run Step 6 now to generate the title and body file (passing the existing PR URL for context), then carry the Demo section and apply.
275
+
276
+ **Carry the Demo section.** The rewrite replaces the whole description, so a `## Demo` section in the current one has to be carried into the new one. The carry always runs; do not gate it on a heading check, because the helper decides whether a Demo section exists. Skip it only when the new body already holds a `## Demo` section from Step 6. Save the current description to a file:
237
277
 
238
278
  ```bash
239
- gh pr edit --title "<title>" --body "$(cat "<body_file>")"
279
+ OLD_BODY_FILE=$(mktemp) && gh pr view "<PR URL>" --json body --jq '.body' > "$OLD_BODY_FILE" && echo saved
280
+ ```
281
+
282
+ When the command does not print `saved`, the temp file could not be created or the `gh` read failed. Stop the carry and do not apply the new body file, because the current description was never saved. Tell the user why, remove the old file, and ask how to proceed, with the options listed in Carrying the Demo section. Otherwise follow Carrying the Demo section, with `old=` set to the old body file and `new=` set to the new body file. Then remove the old file:
283
+
284
+ ```bash
285
+ rm -f "$OLD_BODY_FILE"
286
+ ```
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:
289
+
290
+ ```bash
291
+ gh pr edit --title "<title>" --body-file "<body_file>"
240
292
  ```
241
293
 
242
294
  - If **no** -- skip Step 6 entirely and finish. Do not run evidence capture when the user declined the rewrite.
@@ -244,3 +296,25 @@ The new commits are already on the PR from Step 5. Report the PR URL, then ask w
244
296
  ### Step 8: Report
245
297
 
246
298
  Output the PR URL.
299
+
300
+ When this run published evidence images, print the command that fits the outcome. Take `<N>` from the PR URL:
301
+
302
+ - `status=ok`: print the zero-path command, marked as recommended before merge:
303
+
304
+ > Recommended before merge: load `systematic:pr-attachments` with no tokens (or with `pr:<N>`). It re-checks the embed pins and offers to remove the evidence images from the branch.
305
+
306
+ - `status=failed` with `evidence=pushed` and `reason=verify-failed`, or any other pushed state in which the Demo section was not written: print a retry command instead. The zero-path command re-pins and cleans up, and there is nothing to re-pin yet. The retry is to load `systematic:pr-attachments` with the same image paths and `pr:<N>`. It reuses the pushed commit, verifies the embeds and writes the description. Do not print the zero-path command until a publish succeeds.
307
+ - `status=failed` with `evidence=local`: say that the evidence commit is local and unpushed, so the branch needs a push first, and print no re-run command. For `reason=blob-mismatch` say instead that the local evidence commit holds an altered image and must not be pushed as it is.
308
+
309
+ ---
310
+
311
+ ## Carrying the Demo section
312
+
313
+ A description rewrite replaces the whole body, so a `## Demo` section in the current description has to be carried into the new one. Both rewrite paths, the Description Update workflow and the existing-PR path of Step 7, first save the current description to an old body file, and then follow this section. The carry always runs, whatever the old description holds: `status=absent` is a success and leaves the new file untouched.
314
+
315
+ Load the `systematic:pr-attachments` skill in carry mode. State the tokens in the instruction text only, because some hosts pass no skill arguments and the same tokens in two places would be read twice: `mode:carry old=<old body file> new=<new body file>`, with the real paths from this run. Wrap a path that has spaces in double quotes. Carry mode edits the new body file in place. It never touches the PR.
316
+
317
+ The skill ends with one status line, `pr-attachments: status=<ok|absent|failed> [reason=<reason>]`.
318
+
319
+ - `status=ok` or `status=absent`: apply the new body file.
320
+ - `status=failed`, a skill that fails to load, a skill that prints no status line, or the setup stops: the carry failed. Do not apply the rewritten body, and do not write a `## Demo` section by hand. The PR description stays as it is. Report the reason (the `reason` on the status line, or what stopped the setup) and ask the user how to proceed. Offer only these options: retry the carry, apply the rewritten body without a Demo section after an explicit yes, or keep the current description.