Skip to content

chore: release v2.7.0 — archetype notes from the bundle pin diff; orphan tags get their release - #68

Merged
mabry1985 merged 4 commits into
mainfrom
feat/bundle-pin-notes
Oct 12, 2026
Merged

mabry1985 merged 4 commits into
mainfrom
feat/bundle-pin-notes

Conversation

@mabry1985

@mabry1985 mabry1985 commented Oct 12, 2026 •

Copy link
Copy Markdown
Member

Version bump to 2.7.0. Merging as chore: release v2.7.0 — … fires the release. Merge it after #67: #67 creates the GitHub release before npm publish, so an npm failure can't leave another tag with no release page.

1. Archetype notes stop dropping the pin bumps

rewrite-release-notes dropped chore: bump… and chore: release… subjects before the model saw them. In an archetype those commits are the release, so PM v0.7.0's notes named an intermediate pin (projectBoard v0.47.0, though it ships v0.65.0) and left out github v0.9.1.

New --bundle-manifest <file> (env RELEASE_NOTES_BUNDLE_MANIFEST, action input bundle-manifest):

  • keeps the bump and release commits;
  • diffs the manifest's member pins between the two tags (lib/bundle-pins.mjs, no YAML dependency, handles flow- and block-style members), covering changed, added and removed members plus verified_against;
  • gives that diff to the model as the only authority on member versions (a system-prompt addendum);
  • appends it verbatim as a **Member pins** section, so a model can't misstate the part readers act on. The section is also appended to the fallback notes, and a release whose only change is a pin move still gets notes.

plugin-release.yml passes bundle-manifest when the detected kind is archetype. Plugin releases are unchanged.

Dry-run against the real project-manager-archetype v0.6.0..v0.7.0:

- `project_board` v0.42.0 → v0.65.0
- `github` v0.6.0 → v0.9.1
- Verified against protoAgent 0.145.0 → 0.200.0

2. The generator ships through git, not npm

action.yml ran npx -p @protolabsai/release-tools@latest. npm is stuck at 2.4.1 (see #67), so no generator change could reach consumers. The action now runs node "$GITHUB_ACTION_PATH/bin/rewrite-release-notes.mjs". The code matches the ref the caller pinned (@v2 = the newest v2 release) and ships when the tag moves. The CLI has no runtime dependencies.

3. Orphan tags get their release

The exists gate checked only the tag (Vera's follow-up on #66). A run that pushed the tag and then died at gh release create left an orphan tag that every re-run skipped. Now tag_exists and release_exists are checked separately. The tag is created if missing. The release, notes and Discord post are created if the release is missing (gh release create --verify-tag). Only a tag that already has a release is a no-op. The previous tag is now the newest tag that sorts below the release tag. Before, an orphan re-run would have diffed the tag against itself.

Several archetype repos carry orphan tags today: cowork v0.2.0, design-system v0.1.0, frontend v0.1.0, portfolio-manager v0.1.0 and product v0.2.0.

QA panel round 1 (WARN), addressed

  • Shell injection (major, pre-existing): getCommitsBetween and getCommitsFromDev now run git through execFileSync. The remaining run() calls take constant strings only.
  • Placeholder notes unrecoverable: a release whose body is still Generating release notes… sets needs_notes=true, so a re-run regenerates its notes. Only a tag with a finished release is a no-op.
  • Discord retry: network-level fetch errors are retried, matching callLLM.
  • docs/reference/cli.md: now lists --bundle-manifest and RELEASE_NOTES_BUNDLE_MANIFEST.
  • Not changed: the files array shipping the reusable workflows (intentional; they are documented as shipped) and the test/*.mjs glob (no nested test dirs exist).

Tests

npm test: 92 pass (88 on main), including new test/bundle-pins.test.mjs and a bundle-mode CLI test that reproduces the intermediate-pin case. biome lint is clean. zizmor's finding count on plugin-release.yml and action.yml is unchanged from main (all findings pre-existing).

🤖 Generated with Claude Code

… release

- rewrite-release-notes --bundle-manifest (and RELEASE_NOTES_BUNDLE_MANIFEST):
  keep chore: bump / chore: release commits (in a bundle they ARE the changes),
  diff the manifest's member pins between the two tags, hand that diff to the
  model as the only authority on versions, and append it verbatim as a
  'Member pins' section. PM v0.7.0's notes named an intermediate projectBoard
  pin and omitted github v0.9.1 because the bump commits were filtered out.
- The composite action runs the generator from its own checkout
  ($GITHUB_ACTION_PATH) instead of npx @latest, so @v2 consumers get the code
  of the release they pinned, independent of npm publishing.
- plugin-release.yml passes bundle-manifest for archetypes, and checks the tag
  and the GitHub release separately: a tag without a release (an orphan from a
  run that died after the push) now gets its release, notes and Discord post
  on re-run instead of being skipped forever. The previous tag is the newest
  one BELOW the release tag, so an orphan re-run doesn't diff a tag against
  itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@protoreview protoreview Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

QA panel review — WARN

code-review-structural · head 6252bccdd1d1 · formal

All six findings were verified and confirmed at head — no refutations, no uncertainty. The one thing to fix first is the shell-injection vector in bin/rewrite-release-notes.mjs (major, security): tag values flow from CLI args into execSync without sanitization. The remaining five are minor/nit and can be addressed in follow-up. No panel disagreement; the structural pass (protopatch) raised all findings and the LLM finders found no additional defects in the new logic. Coverage note: lib/bundle-pins.mjs (new ~100-line file) drew zero findings across all finders, consistent with it being a clean utility module.

Findings

Severity Location Finding Verified
🟠 major bin/rewrite-release-notes.mjs:133 Shell command injection via user-supplied tag values interpolated into execSync string in getCommitsBetween and getCommitsFromDev. confirmed · nearby, not gating
🟡 minor .github/workflows/plugin-release.yml:167 Unrecoverable placeholder release notes: if notes-generation fails after release creation, re-runs skip regeneration because release_exists=true. confirmed
🟡 minor bin/rewrite-release-notes.mjs:308 Discord post retry loop does not catch transient network errors from fetch(), unlike the analogous callLLM retry which does. confirmed · nearby, not gating
🟡 minor package.json:31 Published files array includes internal CI workflow definitions that are unrelated to the package's runtime functionality. confirmed · nearby, not gating
🟡 minor docs/reference/cli.md The CLI reference doc, which promises to list 'every command, flag, exit code, env var', is not updated for the new --bundle-manifest flag and RELEASE_NOTES_BU… confirmed
⚪ nit package.json:41 Test glob node --test test/*.mjs only matches immediate test/ directory, silently skipping any future nested test files. confirmed · nearby, not gating
findings JSON (machine-readable)
[
  {
    "file": "bin/rewrite-release-notes.mjs",
    "line": 133,
    "severity": "major",
    "category": "security",
    "claim": "Shell command injection via user-supplied tag values interpolated into execSync string in getCommitsBetween and getCommitsFromDev.",
    "evidence": "The `run()` helper (line 94) uses `execSync` which invokes a shell. Both `getCommitsBetween` (line 120) and `getCommitsFromDev` (line 137) interpolate `fromTag`/`toTag` directly into the shell command string. These values originate from CLI positional args (`positional[0]`, `positional[1]` at line 492-493) or from workflow inputs in the GitHub Action use case. Git ref names permit shell metacharacters. Flagged by both protoPatch structural pass (two independent reports at lines 133 and 492).",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Verified at head: line 94 `return execSync(cmd, { encoding: 'utf8' }).trim();`, line 120 `run(\\`git log ${fromTag}..${toTag} --pretty=format:...\\`)`, line 137 `run(\\`git log ${fromTag}..origin/dev --pretty=format:...\\`)`. Values flow from `positional[0]`/`positional[1]` (line 492-493). execSync spawns /bin/sh; a tag like `v1.0;rm -rf /` would inject. Real vector. \u2014 nearby: in code this PR did not change (outside its changed lines and the functions they sit in) \u2014 reported, not gated (#232)",
    "nearby": true
  },
  {
    "file": ".github/workflows/plugin-release.yml",
    "line": 167,
    "severity": "minor",
    "category": "correctness",
    "claim": "Unrecoverable placeholder release notes: if notes-generation fails after release creation, re-runs skip regeneration because release_exists=true.",
    "evidence": "Line 145\u2013146 creates the GitHub release with the literal placeholder body 'Generating release notes\u2026'. If the downstream notes-generation step (line 148\u2013164) fails or emits empty output, the step at line 166\u2013181 is skipped because of the condition `steps.notes.outputs.notes != ''` on line 167. On any subsequent re-run, `gh release view` succeeds (line 118), so `release_exists=true` and both the tag and release steps are skipped.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Verified at head: line 145 `gh release create \"$TAG\" --verify-tag --title \"$TAG\" --notes \"Generating release notes\u2026\"`. The 'Generate notes' step (line 148) and 'Set the GitHub release body' step (line 166) both gate on `release_exists == 'false'`. On re-run, `gh release view` succeeds \u2192 `release_exists=true` \u2192 both skipped. Release is stuck with placeholder text permanently.",
    "line_original": 145,
    "line_corrected": true
  },
  {
    "file": "bin/rewrite-release-notes.mjs",
    "line": 308,
    "severity": "minor",
    "category": "correctness",
    "claim": "Discord post retry loop does not catch transient network errors from fetch(), unlike the analogous callLLM retry which does.",
    "evidence": "The `callLLM` function wraps `fetch` in a try/catch (lines 308-332) that catches network-level failures (DNS, connection reset, timeout) and retries with backoff. The `postToDiscord` retry loop (lines 377-397) has no such guard: if `fetch` throws a network error, the exception propagates out of `postToDiscord` through `emitNotes` to the top-level, crashing the process on the first transient blip.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Verified at head: `callLLM` (line ~310) wraps `await fetch(...)` in `try { ... } catch (e) { lastErr = e; continue; }`. `postToDiscord` (line ~385) calls `const res = await fetch(webhook, {...})` bare inside the for-loop with no try/catch. A DNS failure or connection reset throws out of the function. Asymmetric error handling confirmed. \u2014 nearby: in code this PR did not change (outside its changed lines and the functions they sit in) \u2014 reported, not gated (#232)",
    "nearby": true
  },
  {
    "file": "package.json",
    "line": 31,
    "severity": "minor",
    "category": "conventions",
    "claim": "Published `files` array includes internal CI workflow definitions that are unrelated to the package's runtime functionality.",
    "evidence": "\".github/workflows/tauri-release.yml\", \".github/workflows/plugin-release.yml\"",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Verified at head: package.json `files` array includes `\".github/workflows/tauri-release.yml\"` and `\".github/workflows/plugin-release.yml\"`. These are the repo's own release CI workflows, not runtime dependencies of the npm package. They ship to consumers who don't need them. \u2014 nearby: in code this PR did not change (outside its changed lines and the functions they sit in) \u2014 reported, not gated (#232)",
    "nearby": true
  },
  {
    "file": "docs/reference/cli.md",
    "line": 0,
    "severity": "minor",
    "category": "conventions",
    "claim": "The CLI reference doc, which promises to list 'every command, flag, exit code, env var', is not updated for the new --bundle-manifest flag and RELEASE_NOTES_BUNDLE_MANIFEST env var this PR adds.",
    "evidence": "docs/reference/cli.md (base ref, unchanged by this PR): 'Every command, flag, exit code, env var.' and its rewrite-release-notes flag table lists --post-discord/--out/--changelog/--changelog-format/--date/--notes-file/--dry-run/--model/--base-url/--repo but no --bundle-manifest; its Env line lists 'GATEWAY_API_KEY \u2026 RELEASE_NOTES_FOOTER' but not RELEASE_NOTES_BUNDLE_MANIFEST. The PR adds the flag ('+  bundle-manifest:' in action.yml; '+ *   RELEASE_NOTES_BUNDLE_MANIFEST  Same as --bundle-manifest (the flag wins).' in bin/rewrite-release-notes.mjs) and updates README.md, but docs/reference/cli.md is not in the diff.",
    "verdict": "confirmed",
    "note": "Verified at head SHA: docs/reference/cli.md flag table ends at `--repo <owner/name>` with no `--bundle-manifest` row; Env line lists `RELEASE_NOTES_FOOTER` as last entry with no `RELEASE_NOTES_BUNDLE_MANIFEST`. The PR diff adds both (action.yml + bin/rewrite-release-notes.mjs) but does not touch this file. Stale doc confirmed."
  },
  {
    "file": "package.json",
    "line": 41,
    "severity": "nit",
    "category": "tests",
    "claim": "Test glob `node --test test/*.mjs` only matches immediate test/ directory, silently skipping any future nested test files.",
    "evidence": "The test script uses `node --test test/*.mjs`, a single-level shell glob. If any test files are organized into subdirectories under test/ (e.g., test/unit/, test/integration/), they will not be matched and will be silently excluded from the test run.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Verified at head: package.json line 41 `\"test\": \"node --test test/*.mjs\"`. Shell glob `test/*.mjs` matches only direct children of test/, not subdirectories. Factual claim about glob semantics is correct. Nit-level: no nested test dirs exist today. \u2014 nearby: in code this PR did not change (outside its changed lines and the functions they sit in) \u2014 reported, not gated (#232)",
    "nearby": true
  }
]

1 finding(s) excluded from the verdict by in-diff confinement (file not among this PR's changed paths):

  • docs/reference/cli.md (minor) — The CLI reference doc, which promises to list 'every command, flag, exit code, env var', is not updated for the new --bundle-manifest flag and RELEASE_NOTES_BUN

4 structural finding(s) are nearby notes, not part of the verdict: they sit in code this PR did not change (outside its changed lines and the functions those lines are in). Worth a look; not a request for this PR.

  • bin/rewrite-release-notes.mjs:133 (major) — Shell command injection via user-supplied tag values interpolated into execSync string in getCommitsBetween and getCommitsFromDev.
  • bin/rewrite-release-notes.mjs:308 (minor) — Discord post retry loop does not catch transient network errors from fetch(), unlike the analogous callLLM retry which does.
  • package.json:31 (minor) — Published files array includes internal CI workflow definitions that are unrelated to the package's runtime functionality.
  • package.json:41 (nit) — Test glob node --test test/*.mjs only matches immediate test/ directory, silently skipping any future nested test files.

protoreview[bot]
protoreview Bot previously approved these changes Oct 12, 2026

@protoreview protoreview Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Promoting the WARN verdict for head 6252bccdd1d1: all checks terminal-green, zero unresolved review threads. (approve-on-green)

Open findings carried by this approval — non-blocking, but they did not go away:

  • major bin/rewrite-release-notes.mjs:133 — Shell command injection via user-supplied tag values interpolated into execSync string in getCommitsBetween and getCommitsFromDev.
  • minor .github/workflows/plugin-release.yml:167 — Unrecoverable placeholder release notes: if notes-generation fails after release creation, re-runs skip regeneration because release_exists=true.
  • minor bin/rewrite-release-notes.mjs:308 — Discord post retry loop does not catch transient network errors from fetch(), unlike the analogous callLLM retry which does.
  • minor package.json:31 — Published files array includes internal CI workflow definitions that are unrelated to the package's runtime functionality.
  • minor docs/reference/cli.md:0 — The CLI reference doc, which promises to list 'every command, flag, exit code, env var', is not updated for the new --bundle-manifest flag and RELEASE_NOTES_BUNDLE_MANIFEST env var this PR adds.
  • nit package.json:41 — Test glob node --test test/*.mjs only matches immediate test/ directory, silently skipping any future nested test files.

Approving a WARN does not resolve its findings (issue #22).

mabry1985 and others added 2 commits October 11, 2026 23:58
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- getCommitsBetween/getCommitsFromDev run git via execFileSync: tag values from
  CLI args / workflow inputs were interpolated into a shell string.
- plugin-release.yml: a release whose body is still the placeholder gets its
  notes regenerated on re-run (needs_notes), instead of keeping the
  placeholder forever.
- postToDiscord retries network-level fetch errors like callLLM does.
- docs/reference/cli.md lists --bundle-manifest and RELEASE_NOTES_BUNDLE_MANIFEST.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
protoreview[bot]
protoreview Bot previously requested changes Oct 12, 2026

@protoreview protoreview Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

QA panel review — FAIL

code-review-structural · head 2994e81885ce · formal

Overall risk is moderate: one major correctness bug (missing-manifest produces a false "all members removed" section) and three minor issues (irreversible changelog wipe on parse failure, silent placeholder on empty notes, shell-interpreting helper). Fix the line-633 guard first — it will post incorrect release notes to both Discord and GitHub on any tag lacking the manifest file. The panel disagreed on nothing. Verification confirmed all eight findings with no changes; no findings were refuted or downgraded. No gaps: the verifier annotated all 8 of 8.

Findings

Severity Location Finding Verified
🟠 major bin/rewrite-release-notes.mjs:632 When the bundle manifest is missing at the version tag, the pin section incorrectly reports all members as removed instead of being skipped. confirmed
🟡 minor bin/rewrite-release-notes.mjs:455 upsertJsonChangelog irreversibly drops all prior entries when the file fails to parse confirmed · nearby, not gating
🟡 minor .github/workflows/plugin-release.yml:177 Workflow completes silently when notes generation yields empty output, leaving placeholder release body confirmed
🟡 minor bin/rewrite-release-notes.mjs:117 run() uses shell-interpreting execSync, contradicting the file's own safe git() pattern confirmed
⚪ nit bin/rewrite-release-notes.mjs:472 Fixed GITHUB_OUTPUT delimiter can collide with LLM-generated content confirmed · nearby, not gating
⚪ nit .github/workflows/plugin-release.yml:124 The placeholder release-notes string is hardcoded in two separate step env blocks, and the new idempotency detection depends on them staying byte-identical — a… confirmed
⚪ nit package.json:25 Missing 'main' or 'exports' field despite shipping lib/ directory confirmed · nearby, not gating
⚪ nit package.json:41 Test glob only matches top-level test files, silently skipping nested subdirectories confirmed · nearby, not gating
findings JSON (machine-readable)
[
  {
    "file": "bin/rewrite-release-notes.mjs",
    "line": 632,
    "severity": "major",
    "category": "correctness",
    "claim": "When the bundle manifest is missing at the version tag, the pin section incorrectly reports all members as removed instead of being skipped.",
    "evidence": "The `if (!after)` check at line 628 only logs a warning but does not prevent the subsequent `const diff = diffBundlePins(before, after);` at line 633. When `after` is `''` (file not found at the tag), `parseBundleManifest('')` returns an empty manifest, so the diff reports every member from `before` as removed, and `formatPinChanges` produces a '**Member pins**' section listing all members as 'removed (was vX.Y.Z)' \u2014 which is then appended verbatim to the release notes via `notes = `${notes.trim()}\\n\\n${pinSection}``.",
    "verdict": "confirmed",
    "note": "Verified at head: line 628 `if (!after)` only calls `console.warn`; line 633 `diffBundlePins(before, after)` executes unconditionally. `parseBundleManifest` (lib/bundle-pins.mjs:38) returns `{plugins: new Map()}` when input is falsy, so all `before` members land in `diff.removed`. `formatPinChanges` renders them as 'removed (was \u2026)' and line 693 appends the section to notes.",
    "line_original": 633,
    "line_corrected": true
  },
  {
    "file": "bin/rewrite-release-notes.mjs",
    "line": 455,
    "severity": "minor",
    "category": "data-loss",
    "claim": "upsertJsonChangelog irreversibly drops all prior entries when the file fails to parse",
    "evidence": "When JSON.parse throws or the result is not an array, the function starts with an empty array and the prior content is permanently discarded. In a CI pipeline the file is committed back to the repo; a partial write from a prior crashed run (e.g., disk full, OOM kill mid-write) corrupts the file, and the next release silently wipes the entire changelog history. The console.warn is the only safeguard.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Verified at head: lines 443\u2013465 show `arr` stays `[]` on parse failure or non-array result; line 464 `arr.filter(...)` yields `[]`; return is `[entry]` only. The `console.warn` at lines 457\u2013461 is the sole safeguard. \u2014 nearby: in code this PR did not change (outside its changed lines and the functions they sit in) \u2014 reported, not gated (#232)",
    "nearby": true
  },
  {
    "file": ".github/workflows/plugin-release.yml",
    "line": 177,
    "severity": "minor",
    "category": "build-release",
    "claim": "Workflow completes silently when notes generation yields empty output, leaving placeholder release body",
    "evidence": "When the notes-generation action succeeds but produces an empty `outputs.notes`, the 'Set the GitHub release body' step is skipped due to the `!= ''` guard. The workflow then completes with a green checkmark, but the GitHub release body remains the placeholder 'Generating release notes\u2026' set on line 157. No warning, no failure, no signal is emitted.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Verified at head: line 177 `if: steps.v.outputs.needs_notes == 'true' && steps.notes.outputs.notes != ''` \u2014 when notes is empty the step is skipped, the placeholder from line 153 (`--notes \"$PLACEHOLDER\"`) persists, and the workflow exits 0."
  },
  {
    "file": "bin/rewrite-release-notes.mjs",
    "line": 117,
    "severity": "minor",
    "category": "security",
    "claim": "run() uses shell-interpreting execSync, contradicting the file's own safe git() pattern",
    "evidence": "run() wraps execSync, which spawns a shell. The file's own git() helper (lines 117-127) uses execFileSync with an args array and carries an explicit comment explaining why shell interpolation is dangerous for ref names. run() is currently only called with hardcoded strings (lines 99, 110, 179), so there is no active injection. However, it is a module-level helper sitting two functions above the safe pattern, inviting future call sites to pass untrusted refs.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Verified at head: line 93 `function run(cmd) { return execSync(cmd, \u2026) }` vs. lines 117\u2013122 `function git(...args) { return execFileSync('git', args, \u2026) }` with the comment 'refs \u2026 must never be interpolated into a shell command string.' Call sites (lines 99, 110) use hardcoded strings only."
  },
  {
    "file": "bin/rewrite-release-notes.mjs",
    "line": 472,
    "severity": "nit",
    "category": "bug",
    "claim": "Fixed GITHUB_OUTPUT delimiter can collide with LLM-generated content",
    "evidence": "The heredoc delimiter is the fixed string 'RELNOTES_EOF'. If the LLM (or a --notes-file source) produces a line containing exactly that string, the heredoc terminates early and the remainder is parsed as additional key=value assignments by the Actions runner, corrupting or truncating the notes output. The probability is low for LLM-generated markdown, but the --notes-file path allows arbitrary user content.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Verified at head: line 472 `const D = 'RELNOTES_EOF'`; line 474 writes `notes<<${D}\\n${notes}\\n${D}\\n\u2026`. A line in `notes` equal to `RELNOTES_EOF` would terminate the heredoc early per the GitHub Actions runner spec. \u2014 nearby: in code this PR did not change (outside its changed lines and the functions they sit in) \u2014 reported, not gated (#232)",
    "nearby": true
  },
  {
    "file": ".github/workflows/plugin-release.yml",
    "line": 124,
    "severity": "nit",
    "category": "conventions",
    "claim": "The placeholder release-notes string is hardcoded in two separate step env blocks, and the new idempotency detection depends on them staying byte-identical \u2014 a single-source-of-truth violation that silently breaks orphan/placeholder detection if only one is edited.",
    "evidence": "Line 68 (in the `v` step, consumed by `[ \"$BODY\" = \"$PLACEHOLDER\" ]`): `PLACEHOLDER: \"Generating release notes\u2026\"`; line 153 (in the \"Create GitHub release\" step, consumed by `gh release create \"$TAG\" --verify-tag --title \"$TAG\" --notes \"$PLACEHOLDER\"`): `PLACEHOLDER: \"Generating release notes\u2026\"`. If the create-side text is changed without the compare-side, a release carrying the new text is treated as finished and its notes are never regenerated.",
    "verdict": "confirmed",
    "note": "Verified at head: line 68 `PLACEHOLDER: \"Generating release notes\u2026\"` (compare-side, used in `[ \"$BODY\" = \"$PLACEHOLDER\" ]`) and line 153 `PLACEHOLDER: \"Generating release notes\u2026\"` (create-side, used in `--notes \"$PLACEHOLDER\"`). Both are independent env declarations in different steps.",
    "line_original": 153,
    "line_corrected": true
  },
  {
    "file": "package.json",
    "line": 25,
    "severity": "nit",
    "category": "api-contract",
    "claim": "Missing 'main' or 'exports' field despite shipping lib/ directory",
    "evidence": "The 'files' array includes 'lib/' (line 27), meaning the lib directory is published to the npm tarball. However, there is no 'main' or 'exports' field declaring a package entry point. Consumers who need to import from this package programmatically must use deep relative imports like '@protolabsai/release-tools/lib/index.mjs', which is fragile and undocumented.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Verified at head: package.json has `\"files\": [\"bin/\", \"lib/\", \u2026]` (line 27) but no `main` or `exports` key anywhere in the 46-line file. \u2014 nearby: in code this PR did not change (outside its changed lines and the functions they sit in) \u2014 reported, not gated (#232)",
    "nearby": true
  },
  {
    "file": "package.json",
    "line": 41,
    "severity": "nit",
    "category": "test-gap",
    "claim": "Test glob only matches top-level test files, silently skipping nested subdirectories",
    "evidence": "The script `node --test test/*.mjs` relies on shell glob expansion which only matches files directly under `test/`. If test files are organized into subdirectories (e.g., `test/llm/*.mjs`), they will be silently excluded from the test run.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Verified at head: line 41 `\"test\": \"node --test test/*.mjs\"`. The `*` glob in POSIX shell does not cross directory boundaries, so `test/sub/file.mjs` would not match. \u2014 nearby: in code this PR did not change (outside its changed lines and the functions they sit in) \u2014 reported, not gated (#232)",
    "nearby": true
  }
]

4 structural finding(s) are nearby notes, not part of the verdict: they sit in code this PR did not change (outside its changed lines and the functions those lines are in). Worth a look; not a request for this PR.

  • bin/rewrite-release-notes.mjs:455 (minor) — upsertJsonChangelog irreversibly drops all prior entries when the file fails to parse
  • bin/rewrite-release-notes.mjs:472 (nit) — Fixed GITHUB_OUTPUT delimiter can collide with LLM-generated content
  • package.json:25 (nit) — Missing 'main' or 'exports' field despite shipping lib/ directory
  • package.json:41 (nit) — Test glob only matches top-level test files, silently skipping nested subdirectories

Addressed since the last round (2 minor/nit): .github/workflows/plugin-release.yml:167, docs/reference/cli.md:0 — no longer raised, and the PR changed the code around them since they were raised.

@protoreview
protoreview Bot dismissed their stale review October 12, 2026 07:16

Withdrawn — a later QA panel round FAILed this PR (see the newest verdict).

- A bundle manifest missing at the release tag skips the pin section instead
  of reporting every member as removed (+ test).
- run() is gone; every git call goes through the shell-free git() helper.
- plugin-release.yml: the placeholder is defined once (job env), and an empty
  generator result writes a 'maintenance release' body instead of leaving the
  placeholder (which re-runs would otherwise keep treating as unfinished).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@protoreview protoreview Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

QA panel review — PASS

code-review-structural · head f3a6c168dae1 · formal

All six synthesized findings were confirmed by the verifier; none were refuted or marked uncertain. The carried-forward major from round 2 (bundle-manifest-missing path at line 632) remains open — no finding in this round addresses it and no fix is visible. Three minor open priors from round 2 (workflow silent-completion, execSync pattern, placeholder dedup) also remain unaddressed by this round's findings. No coverage gaps: the verifier annotated all 6 findings it was given.

Prior requests

Prior finding Disposition Why
✅ bin/rewrite-release-notes.mjs:632 cleared at this head — re-verified No finding in this round addresses the bundle-manifest-missing path; the LLM lanes came back clean on the new code but did not flag this specific defect, and n…

Findings

Severity Location Finding Verified
🟡 minor bin/rewrite-release-notes.mjs:441 JSON changelog history is lost permanently when the existing file is unparseable — the code warns but proceeds to overwrite with a fresh array containing only … confirmed · nearby, not gating
🟡 minor .github/workflows/plugin-release.yml:37 PAT token bypasses the workflow permissions block, granting wider access than the declared permissions: contents: write suggests. confirmed · nearby, not gating
🟡 minor package.json:31 Internal GitHub workflow files are published to the npm registry, exposing CI/CD pipeline details to the public. confirmed · nearby, not gating
⚪ nit bin/rewrite-release-notes.mjs:178 detectRepoSlug regex fails for GitHub repos with a dot in the name, capturing only the portion before the dot. confirmed
⚪ nit package.json:25 Library code is shipped in the files array without a main or exports entry point, making it unimportable by consumers. ⚠️ uncertain
⚪ nit README.md:30 README documents a different default for --required-checks than the code implements (4 items vs 3). ⚠️ uncertain
findings JSON (machine-readable)
[
  {
    "file": "bin/rewrite-release-notes.mjs",
    "line": 441,
    "severity": "minor",
    "category": "correctness",
    "claim": "JSON changelog history is lost permanently when the existing file is unparseable \u2014 the code warns but proceeds to overwrite with a fresh array containing only the new entry.",
    "evidence": "When the existing changelog file cannot be parsed as JSON (corruption, partial write from a prior failed CI run, encoding issue), all prior release entries are discarded. The code emits a console.warn but proceeds to write a fresh array containing only the new entry.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Read lines 430\u2013460 at head: the catch block at ~line 455 emits `console.warn('WARNING: could not parse the existing changelog as JSON \u2026 prior entries are dropped.')` then falls through to `arr = [entry]` and writes the file. Data loss is real and only warned, not aborted. \u2014 nearby: in code this PR did not change (outside its changed lines and the functions they sit in) \u2014 reported, not gated (#232)",
    "nearby": true
  },
  {
    "file": ".github/workflows/plugin-release.yml",
    "line": 37,
    "severity": "minor",
    "category": "security",
    "claim": "PAT token bypasses the workflow permissions block, granting wider access than the declared `permissions: contents: write` suggests.",
    "evidence": "The workflow declares `permissions: contents: write` (line 37\u201338), which constrains the `GITHUB_TOKEN` to write-only access to contents. However, lines 62, 69, 153, and 184 all use `${{ secrets.GH_PAT || secrets.GITHUB_TOKEN }}`. The GitHub `permissions:` block only governs the auto-generated `GITHUB_TOKEN`; it has no effect on a user-supplied personal access token.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Confirmed `permissions: contents: write` at line 37 and `secrets.GH_PAT || secrets.GITHUB_TOKEN` at lines 62, 69, 153, 184. GitHub docs: the `permissions` key only scopes the auto-generated GITHUB_TOKEN; a PAT retains its creation-time scopes regardless. \u2014 nearby: in code this PR did not change (outside its changed lines and the functions they sit in) \u2014 reported, not gated (#232)",
    "nearby": true
  },
  {
    "file": "package.json",
    "line": 31,
    "severity": "minor",
    "category": "conventions",
    "claim": "Internal GitHub workflow files are published to the npm registry, exposing CI/CD pipeline details to the public.",
    "evidence": "The `files` array includes `.github/workflows/tauri-release.yml` and `.github/workflows/plugin-release.yml`. These are CI/CD workflow definitions that describe how the project builds and releases its own products. Publishing them to a public npm registry exposes internal release pipelines, branch names, environment variable expectations, and potentially internal URLs or service endpoints.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Read package.json at head: `files` array explicitly lists both workflow files, and `publishConfig` declares `\"access\": \"public\"` to `registry.npmjs.org`. The factual claim is accurate. \u2014 nearby: in code this PR did not change (outside its changed lines and the functions they sit in) \u2014 reported, not gated (#232)",
    "nearby": true
  },
  {
    "file": "bin/rewrite-release-notes.mjs",
    "line": 178,
    "severity": "nit",
    "category": "correctness",
    "claim": "detectRepoSlug regex fails for GitHub repos with a dot in the name, capturing only the portion before the dot.",
    "evidence": "`detectRepoSlug` in rewrite-release-notes.mjs uses the regex `/github\\.com[:/]([^/]+\\/[^/.]+)/` \u2014 the character class `[^/.]+` stops at a literal dot, so a remote URL like `git@github.com:protoLabsAI/my.repo.git` captures only `protoLabsAI/my` instead of `protoLabsAI/my.repo`.",
    "source": "protopatch",
    "verdict": "confirmed",
    "note": "Read line 178 at head: regex is `/github\\.com[:/]([^/]+\\/[^/.]+)/`. Tracing `git@github.com:protoLabsAI/my.repo.git`: `[^/.]+` after the slash matches `my` and stops at `.` \u2014 captures `protoLabsAI/my`, not `protoLabsAI/my.repo`."
  },
  {
    "file": "package.json",
    "line": 25,
    "severity": "nit",
    "category": "conventions",
    "claim": "Library code is shipped in the `files` array without a `main` or `exports` entry point, making it unimportable by consumers.",
    "evidence": "The `files` array includes `lib/`, indicating library code is intended to be distributed. However, there is no `main` or `exports` field. With `\"type\": \"module\"`, a consumer running `import { foo } from '@protolabsai/release-tools'` will fail because Node cannot resolve the module.",
    "source": "protopatch",
    "verdict": "uncertain",
    "note": "Read package.json at head: `files` includes `lib/`, no `main` or `exports` field present, `\"type\": \"module\"` set. Without an entry point, Node's ESM resolution cannot determine what to load for a bare import. \u2014 evidence not found at the reviewed head \u2014 downgraded to uncertain, cannot gate a merge (issue #25)",
    "ungrounded": true
  },
  {
    "file": "README.md",
    "line": 30,
    "severity": "nit",
    "category": "conventions",
    "claim": "README documents a different default for --required-checks than the code implements (4 items vs 3).",
    "evidence": "The README flag table states the default for `--required-checks` is `build,test,checks,ci-complete` (4 items). The code defines `DEFAULT_REQUIRED_CHECKS = ['build', 'test', 'checks']` (3 items, no `ci-complete`).",
    "source": "protopatch",
    "verdict": "uncertain",
    "note": "Read README.md line 30 at head: `| \\`--required-checks\\` | \\`build,test,checks,ci-complete\\` |`. Read bin/rewrite-release-notes.mjs line 12: `const DEFAULT_REQUIRED_CHECKS = ['build', 'test', 'checks'];`. Discrepancy confirmed \u2014 README lists 4 items, code has 3. \u2014 evidence not found at the reviewed head \u2014 downgraded to uncertain, cannot gate a merge (issue #25)",
    "ungrounded": true
  }
]

2 finding(s) downgraded to uncertain: the code they quote as evidence does not appear in the file at the reviewed head, nor in this PR's patch for it. A finding that cannot be grounded does not gate a merge (issue #25) — it still stands for a human to judge.

  • package.json (nit) — quoted evidence not found at this head: import { foo } from "@protolabsai/release-tools"
  • README.md (nit) — quoted evidence not found at this head: DEFAULT_REQUIRED_CHECKS = ["build", "test", "checks"]

5 structural finding(s) are nearby notes, not part of the verdict: they sit in code this PR did not change (outside its changed lines and the functions those lines are in). Worth a look; not a request for this PR.

  • bin/rewrite-release-notes.mjs:441 (minor) — JSON changelog history is lost permanently when the existing file is unparseable — the code warns but proceeds to overwrite with a fresh array containing only t
  • .github/workflows/plugin-release.yml:37 (minor) — PAT token bypasses the workflow permissions block, granting wider access than the declared permissions: contents: write suggests.
  • package.json:31 (minor) — Internal GitHub workflow files are published to the npm registry, exposing CI/CD pipeline details to the public.
  • package.json:25 (nit) — Library code is shipped in the files array without a main or exports entry point, making it unimportable by consumers.
  • README.md:30 (nit) — README documents a different default for --required-checks than the code implements (4 items vs 3).

Prior finding(s) cleared by re-verification. The verifier re-read the code at this head and refuted these; each had either never been verified, or its file changed since it was raised (#218, #220):

  • bin/rewrite-release-notes.mjs:632 (major) — When the bundle manifest is missing at the version tag, the pin section incorrectly reports all members as removed instead of being skipped. (verifier: The code at head uses if (!after) { warn } else { diffBundlePins(...) } — the diff call is in the else branch and is NOT reached when after is falsy. The finding's quoted evidence (sequential if +)

Addressed since the last round (3 minor/nit): .github/workflows/plugin-release.yml:177, bin/rewrite-release-notes.mjs:117, .github/workflows/plugin-release.yml:124 — no longer raised, and the PR changed the code around them since they were raised.

@protoreview
protoreview Bot dismissed their stale review October 12, 2026 07:32

Superseded — a later head cleared the QA panel (see the newest verdict).

@protoreview protoreview Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Promoting the PASS verdict for head f3a6c168dae1: all checks terminal-green, zero unresolved review threads. (approve-on-green)

Open findings carried by this approval — non-blocking, but they did not go away:

  • minor bin/rewrite-release-notes.mjs:441 — JSON changelog history is lost permanently when the existing file is unparseable — the code warns but proceeds to overwrite with a fresh array containing only the new entry.
  • minor .github/workflows/plugin-release.yml:37 — PAT token bypasses the workflow permissions block, granting wider access than the declared permissions: contents: write suggests.
  • minor package.json:31 — Internal GitHub workflow files are published to the npm registry, exposing CI/CD pipeline details to the public.
  • nit bin/rewrite-release-notes.mjs:178 — detectRepoSlug regex fails for GitHub repos with a dot in the name, capturing only the portion before the dot.
  • nit package.json:25 — Library code is shipped in the files array without a main or exports entry point, making it unimportable by consumers.
  • nit README.md:30 — README documents a different default for --required-checks than the code implements (4 items vs 3).

Approving a WARN does not resolve its findings (issue #22).

@mabry1985
mabry1985 merged commit e84d2e9 into main Oct 12, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant