@laitszkin/apollo-toolkit 3.8.4 → 3.9.0

package/review-spec-related-changes/SKILL.md

@@ -1,110 +1,77 @@
 ---
 name: review-spec-related-changes
-description: Review recent or user-specified spec-related changes against the governing `docs/plans/...` spec documents, treat unmet business goals as the most severe findings, and then run code-practice cross-checks through `review-change-set`, `discover-edge-cases`, and `harden-app-security`. Use when users ask whether implemented work actually satisfies a spec, wants a spec compliance review, or asks to review changes related to recent or named planning documents.
+description: >-
+  Read-only spec compliance versus governing docs/plans: score each business-oriented requirement Met/Partial/Not-met using code/tests/commands—checked `tasks.md` boxes are never sufficient proof; ambiguity between two plausible plan roots halts execution; when runtime code exists, sequentially run **`review-change-set`**, **`discover-edge-cases`**, and **`harden-app-security`** on the same scoped diff afterward.
+  Use for questions like “does this PR satisfy coordination.md + spec.md R2?” or user pins a `{change}` folder.
+  Do not mutate repositories, reorder reports to bury missing goals, skip the tertiary review bundle on code-bearing diffs, or rely on intent without file evidence **BAD**, lead with refactor comments while R1 failing **FORBIDDEN**… GOOD pair every Not-met cite with `spec.md` ref + concrete path:test gap…
 ---
 
 # Review Spec Related Changes
 
 ## Dependencies
 
-- Required: `review-change-set`, `discover-edge-cases`, and `harden-app-security` for code-affecting spec-related changes.
+- Required: `review-change-set`, `discover-edge-cases`, and `harden-app-security` whenever the scope includes **code-affecting** implementation to assess.
 - Conditional: none.
 - Optional: none.
-- Fallback: If any required review dependency is unavailable for a code-affecting scope, stop and report the missing dependency instead of returning a partial pass.
+- Fallback: If any required dependency is unavailable for a **code-affecting** review, **MUST** stop and report the gap. **MUST NOT** emit a “full pass” verdict without those three passes when code is in scope.
 
-## Standards
+## Non-negotiables
 
-- Evidence: Read the governing spec documents, the related git changes, and the minimum implementation context before deciding whether the business goal was met.
-- Execution: Resolve the spec scope first, review business-goal completion before any secondary code-practice review, then run the required review skills on the same implementation scope.
-- Quality: Treat unmet or partially met business goals as the highest-severity findings, keep secondary edge-case/security/code-review findings outside the business-goal verdict, and avoid speculative issues that are not backed by code or spec evidence.
-- Output: Return a prioritized issue list with business-goal gaps first, followed by edge-case, security, and code-review findings, each tied to specific spec and code evidence.
+- **MUST NOT** edit implementation code, tests, or planning docs during this skill (read-only review).
+- **MUST NOT** archive specs, commit, push, tag, or release from this skill.
+- **MUST** resolve which spec set governs the change **before** concluding; if multiple candidates fit equally and cannot be disambiguated from repo evidence, **MUST** stop and report ambiguity—**MUST NOT** guess.
+- **MUST** classify each business goal / acceptance item as `Met`, `Partially met`, `Not met`, or `Deferred/N/A` **only** using verifiable evidence (code, tests, commands, traces)—checked boxes in `tasks.md` are **not** proof by themselves.
+- **MUST** treat **unmet or partially met required business goals** as **highest severity**. **MUST NOT** let edge-case, security, or style findings **outrank** those gaps in the reported order or implied priority.
+- **MUST** finish the business-goal verdict **before** invoking secondary skills; **MUST** still run `review-change-set`, `discover-edge-cases`, and `harden-app-security` on the **same** implementation scope when code is involved (after step 1 verdict is written).
+- **MUST NOT** rest conclusions on author intent, branch names, or chat memory unless **repository evidence** agrees.
+- Prefer **fewer confirmed findings** over broad speculation; unproven items belong under **Residual uncertainty**, not as faux defects.
 
-## Goal
+## Standards (summary)
 
-Determine whether the implementation actually satisfies the relevant planning documents, then separately assess whether the related code is safe, robust, and maintainable.
+- **Evidence**: Full read of governing docs + minimal code/diff context + spec-named verification commands when safe to run.
+- **Execution**: Scope resolution → business compliance → required secondary reviews → ordered report.
+- **Quality**: Business-first severity; secondary findings separated unless they also block an acceptance criterion.
+- **Output**: Ordered list: business gaps → edge cases → security → code review → passing summary → residual uncertainty.
 
-## Scope Resolution
+## Scope resolution
 
-### User-specified spec documents
+**Chain-of-thought:** Before **`Workflow`**, answer **`Pause →`** for the governing spec you will use; equally plausible paths without disambiguation ⇒ **stop**.
 
-- If the user names a spec directory or file, read every governing document in that spec set, including `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and batch-level `coordination.md` when present.
-- Treat the named spec documents as the authoritative business goal unless the repository contains a newer superseding plan that the user explicitly referenced.
-- Map the spec to implementation changes using task entries, owned files, git diff paths, branch names, commit messages, and code references from the spec.
+**User-named path** — Read `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, and batch `coordination.md` when present unless the user narrowed the list. Treat as authoritative unless the user pointed at a **newer** superseding plan. Map implementation via tasks, owned paths, diff, branch, commits.
+   - **Pause →** Did the user give a **filesystem path** or only a nickname that could map to multiple `docs/plans/...` trees?
+   - **Pause →** For each major business verdict later, what **exact** spec heading or requirement ID will I cite?
 
-### Recent spec-related changes
-
-- If the user asks for recent spec-related review without naming a spec, inspect the current git state first:
-  ```bash
-  git status -sb
-  git diff --name-only
-  git diff --cached --name-only
-  ```
-- Look for changed or recently touched planning documents under `docs/plans/`, `docs/archive/plans/`, or the repository's documented planning location.
-- If no planning document changed, inspect recent commits and active plan directories to identify the most recent spec set that plausibly governs the current implementation.
-- If multiple candidate spec sets remain plausible and cannot be separated by changed files or branch names, stop and report the ambiguity instead of guessing.
+**User did not name a spec** — Inspect `git status -sb`, `git diff --name-only`, `git diff --cached --name-only`; search `docs/plans/`, `docs/archive/plans/`, or repo-documented plan dirs. If no plan file moved, infer from recent commits and plausible plan dirs; **if still ambiguous, stop** (see Non-negotiables).
+   - **Pause →** What **three** independent clues tie this implementation to **one** plan—not chat memory alone?
+   - **Pause →** If I withheld the conversation transcript, could another reviewer replicate my chosen spec folder from repo evidence?
 
 ## Workflow
 
-### 1) Build the spec baseline
-
-- Read the governing spec documents end-to-end.
-- Extract the concrete business goals, acceptance criteria, non-goals, deferred work, and explicit verification requirements.
-- Build a compact checklist of claims that can be proven or disproven from code, tests, docs, or command output.
-- Keep business goals separate from implementation-quality expectations. A clean implementation does not compensate for an unmet business requirement.
-
-### 2) Map implementation evidence
-
-- Read the related diff, staged changes, commits, or changed files that correspond to the spec scope.
-- Follow the minimum dependency chain needed to understand whether the behavior is actually implemented.
-- Run or inspect the verification commands named by the spec when they are available and safe to run.
-- Mark each business goal as:
-  - `Met`: direct implementation and verification evidence exists.
-  - `Partially met`: some required behavior exists, but an acceptance criterion, integration path, or verification proof is missing.
-  - `Not met`: implementation evidence is absent or contradicts the spec.
-  - `Deferred/N/A`: the spec explicitly excludes or defers the item.
-
-### 3) Review business-goal completion first
-
-- Report every `Not met` and `Partially met` business goal before secondary review findings.
-- Assign the highest severity to business-goal failures because they mean the delivered change does not satisfy the requested work.
-- Include exact spec evidence and code evidence for each gap.
-- Do not continue into archival, submission, or release recommendations while business-goal failures remain unresolved.
-
-### 4) Run secondary code-practice reviews
-
-After the business-goal pass is complete, invoke the required review skills on the same code-affecting scope:
-
-- Use `review-change-set` to identify architecture, abstraction, and simplification findings in the related diff.
-- Use `discover-edge-cases` to identify reproducible boundary, failure-path, state, and observability risks.
-- Use `harden-app-security` to identify reproducible vulnerabilities and adversarial trust-boundary failures.
+**Chain-of-thought:** Answer **`Pause →`** after **each** step before moving down the list or calling dependent skills.
 
-Keep these findings separate from the business-goal verdict unless the issue also prevents a required acceptance criterion from being satisfied.
+1. **Spec baseline** — Read governing docs end-to-end. Extract goals, acceptance criteria, non-goals, deferrals, required verifications. Build a compact claim list provable from repo evidence. Keep “what the product must do” separate from “how clean the code is.”
+   - **Pause →** Which items are **mandatory** acceptance vs explicitly **out of scope** or deferred?
+   - **Pause →** What observable failure would make me change a `Met` to `Not met` for the top risk requirement?
 
-### 5) Produce the final review
+2. **Implementation evidence** — Read the relevant diff/staged/commits/files. Trace the minimum code path to validate claims. Run spec-named checks when available and safe.
+   - **Pause →** What is the **smallest** code path I have not yet read that could still falsify a `Met`?
+   - **Pause →** Am I about to score `Met` from **intent** or from **tests/commands** I actually ran or inspected?
 
-Return findings in this order:
+3. **Business-goal verdict first** — Emit every `Not met` / `Partially met` **before** secondary findings, with **exact** spec cites and code/test evidence. While required goals stay failed, **MUST NOT** frame archival, release, or “done” narratives that imply compliance.
+   - **Pause →** If I sorted findings by “interesting” instead of business impact, which line would unfairly rise above a missing goal?
+   - **Pause →** For each `Partially met`, what single **missing proof** (test, wire-up, error path) am I naming explicitly?
 
-1. Business-goal failures
-   - Severity: always highest for unmet or partially met required goals.
-   - Include spec evidence, implementation evidence, and the missing acceptance criterion.
-2. Edge-case findings
-   - Include reproduction or concrete trigger evidence.
-3. Security findings
-   - Include exploit path, protected asset, and reproducibility evidence.
-4. Code-review findings
-   - Include architecture, abstraction, simplification, or maintainability evidence.
-5. Passing evidence
-   - Summarize the business goals that were confirmed met.
-6. Residual uncertainty
-   - List unverified checks, commands not run, ambiguous spec mappings, or external dependencies that could not be proven.
+4. **Secondary reviews (code-affecting)** — On the same scope: `review-change-set` (architecture/simplification), `discover-edge-cases` (reproducible edge/observability risks), `harden-app-security` (reproducible security). Keep outputs labeled so they do not read as business-goal substitutions.
+   - **Pause →** Does this secondary finding **force** a business re-score—if yes, did I revise step 3 before publishing?
+   - **Pause →** Is the diff scope identical to what I used for business mapping (no silent file creep)?
 
-If no actionable issue is found, state that no business-goal, edge-case, security, or code-review findings were identified, and still list the spec documents and verification evidence reviewed.
+5. **Final report (fixed order)** — (1) Business-goal failures (always top severity for required gaps). (2) Edge-case. (3) Security. (4) Code-review / maintainability. (5) Passing evidence for goals confirmed `Met`. (6) Residual uncertainty (skipped commands, unmapped spec text, unverifiable externals). If nothing actionable: state that explicitly **and** still cite docs and evidence reviewed.
+   - **Pause →** What commands or spec paragraphs remain **unverified**—are they all listed under residual uncertainty?
 
-## Working Rules
+## Sample hints
 
-- Do not edit code, tests, or specs during this review.
-- Do not archive specs, commit, push, tag, or release from this skill.
-- Do not let secondary code quality findings bury business-goal failures.
-- Do not treat checked tasks as proof by themselves; verify the implementation.
-- Do not infer success from author intent, branch names, or prior conversation context unless the repository evidence supports it.
-- Prefer fewer confirmed findings over broad speculative feedback.
+- **Business claim record**:
+  - `R3.2 refresh token rotation` → `Not met` — spec `spec.md` §3.2 requires one-time use; `src/auth/refresh.rs:40` still accepts same jti on replay; test `refresh_replay` not present.
+- **Wrong ordering** — starting with “nice simplification in `foo.ts`” while `R1.0` is unmet: **wrong**; lead with the `R1.0` gap.
+- **Tasks checked but behavior missing** — `tasks.md` shows `[x] implement rate limit` but no call site in `src/api/*` and no test: verdict stays **`Not met` / `Partially met`**, not `Met`.
+- **Ambiguous scope** — two directories `docs/plans/2026-05-01/foo/` and `…/batch-a/foo/` both plausible; **stop** with “need user to name path” instead of picking one.

package/solve-issues-found-during-review/SKILL.md

@@ -1,134 +1,74 @@
 ---
 name: solve-issues-found-during-review
-description: Fix issues discovered during a review pass (review-change-set, review-spec-related-changes, review-codebases, discover-edge-cases, harden-app-security, or any structured review), proceeding from the highest-severity finding down to the lowest, until all confirmed issues are resolved. Use when users ask to fix review findings, resolve review issues, implement review feedback on code, or address audit/security review findings.
+description: >-
+  Operate strictly from a structured review/issue list containing confirmed findings: close items in descending severity order (Critical before High/Medium/Low), land the smallest corrective diff per finding, run targeted validation after each fix before continuing, forbid speculative polish or unsolicited doc edits unless a finding explicitly requires them, and document Deferred or Could-not-reproduce outcomes with reproducible rationale.
+  Use when prompts reference concrete review outputs (“fix Bugbot findings”, “resolve security audit bullets”) accompanied by reproducible excerpts—STOP if only vague “there were issues yesterday” survives.
+  Bad pattern: refactoring modules while unresolved Critical SSRF persists… Good pattern: `HIGH SSRF src/net/client.rs…` patched, `cargo test net::fetch` green, hashes recorded…
 ---
 
 # Solve Issues Found During Review
 
 ## Dependencies
 
-- Required: none. This skill reads issues from a review report that must already exist or be supplied by the caller.
-- Conditional: `review-change-set` for re-validation after fixes when the fix set is code-affecting; `systematic-debug` when a fix attempt encounters unexpected test or runtime failures.
-- Conditional: When parallel sub-agents are available, the capability to merge changes from independent workspaces and resolve inter-workspace conflicts after parallel fix work.
-- Optional: `discover-edge-cases` to confirm edge-case coverage after fixing; `harden-app-security` to confirm security fixes are effective.
-- Fallback: If a required re-validation dependency is unavailable after a code-affecting fix, run `git diff --stat` and relevant tests manually and report what was verified.
+- Required: none (caller **MUST** supply an existing review report or reconstructable finding list).
+- Conditional: `review-change-set` for optional re-validation after **code-affecting** fixes; `systematic-debug` when a fix causes unexpected test or runtime failures.
+- Optional: `discover-edge-cases` / `harden-app-security` when the user or report demands post-fix confirmation on those dimensions.
+- Fallback: If `review-change-set` is unavailable after code fixes, **MUST** still verify via targeted tests and `git diff` (or equivalent) and **MUST** document exactly what was run.
 
-## Standards
+## Non-negotiables
 
-- Evidence: Read the full review report and the affected code before implementing any fix. Every fix must be grounded in a confirmed finding from the review.
-- Execution: Fix issues in strict severity order (Critical → High → Medium → Low). After each fix, validate the change preserves correctness before moving to the next issue. Re-run the original review scope when all fixes are complete to confirm no regression and no remaining finding.
-- Quality: Fix only issues confirmed by the review report. Do not expand scope with speculative improvements, unrelated refactors, or style-only changes. Each fix must be minimal and targeted.
-- Output: Report which findings were fixed, how each was validated, any findings that could not be reproduced or fixed (with reasons), and the final re-validation result.
+- **MUST** read the **full** report and the affected code **before** editing. **MUST** tie every code change to a **confirmed** finding (explicit severity/title/evidence). **MUST NOT** fix speculative, hypothetical, or “nice-to-have” items unless the report elevated them to confirmed findings.
+- **MUST** process findings in strict severity order: complete **all** Critical before **any** High, then Medium, then Low—**MUST NOT** skip ahead for convenience. Within a tier, follow the reviewer’s stated ordering when present; if severities are missing, treat business-goal / correctness breaks as **High–Critical class** and cosmetic simplification as **Low**.
+- **MUST** validate after each finding’s fix (tests, repro steps, or agreed oracle) **before** starting the next finding at the same or lower priority. **MUST NOT** mark a finding fixed without passing validation.
+- **MUST** keep each fix **minimal** and scoped to the finding: **MUST NOT** bundle unrelated refactors, style sweeps, or scope expansion.
+- This skill **defaults to product code**; **MUST NOT** edit specs, docs, or `AGENTS.md`/`CLAUDE.md` unless the **finding text** explicitly requires it.
+- If a finding cannot be reproduced after investigation, **MUST** record `Could not reproduce` with evidence and **MUST** continue the queue without silently dropping the item.
 
-## Workflow
-
-### 1) Read the review report
-
-- Read the review report or finding list that the user provides.
-- If the user did not provide a review report but says "fix the review findings", inspect current git state and recent review outputs to reconstruct the finding list.
-- If no review report can be found, stop and report that no review findings are available to act on.
-- Extract every confirmed finding with its severity, title, evidence (`path:line`), and reproduction evidence.
-
-### 2) Prioritize findings by severity
-
-Group findings into ordered buckets:
-
-1. Critical
-2. High
-3. Medium
-4. Low
-
-Within each bucket, order by the reviewer's stated priority. If the review does not assign severity, treat architecture/business-goal gaps as High and simplification/style suggestions as Low.
-
-### 3) Classify findings by module and business logic chain
-
-Before fixing, group findings by:
-
-- **Module**: which subsystem, component, or layer each finding belongs to.
-- **Business logic chain**: findings along the same data flow, request path, or feature pipeline.
-
-This classification determines which findings can be fixed independently in parallel and which share dependencies that require coordinated treatment.
-
-### 4) Deploy parallel fix work (when sub-agent capability is available)
-
-If the runtime supports spawning sub-agents with isolated workspaces:
-
-**a. Assign each module group to a sub-agent**
+## Standards (summary)
 
-- Group findings by the classification above. Each independent module or business chain becomes a work package.
-- Assign each work package to a sub-agent, giving it the relevant findings, the affected file paths, and the original review context.
-- Each sub-agent works in its own isolated workspace with no risk of interfering with others.
+- **Evidence**: Confirmed finding → code path → minimal patch → validation artifact.
+- **Execution**: Order by severity; optional parallel module groups only when isolation is real; merge without losing fix intent.
+- **Quality**: No speculative hardening; conflicts resolved conservatively unless the finding demands an aggressive change.
+- **Output**: Per-finding status, validation proof, final re-validation summary, residual/deferred items with reasons.
 
-**b. Sub-agents fix and validate their assigned findings**
-
-Each sub-agent independently:
-
-- Reads its assigned findings and the affected code.
-- Applies the minimal fix for each finding in severity order within its scope.
-- Validates correctness (tests, reproduction steps, linting) before marking findings as resolved.
-- Reports back which findings were fixed, deferred, or could not be reproduced, along with a summary of changes.
-
-**c. Consolidate and resolve conflicts**
-
-After all sub-agents complete:
-
-- Merge changes from each isolated workspace back into the main workspace, one at a time.
-- If conflicts arise, resolve them by keeping both sides of the fix intent — do not discard either party's changes unless they are truly contradictory.
-- When two fixes touch the same code, prefer the more conservative change (less behavioral deviation) unless the review finding explicitly demands the more aggressive one.
-- If a conflict cannot be resolved without deviating from the original fix intent, flag it for manual review and move on.
-
-**d. Re-validate after consolidation**
-
-Run all relevant tests across the consolidated changes to confirm the merged result is correct.
-
-If the runtime does **not** support sub-agents with isolated workspaces, fall back to fixing findings sequentially in severity order as described in the next step.
-
-### 5) Fix findings sequentially (fallback when sub-agents are unavailable)
-
-For each finding in priority order, when parallel sub-agent capability is not available:
-
-**a. Understand the finding and the fix target**
+## Workflow
 
-- Read the affected code paths end-to-end.
-- Read the reviewer's reproduction evidence and hardening guidance.
-- Determine the minimal fix that resolves the finding without changing unrelated behavior.
+**Chain-of-thought:** After **each** phase, **`Pause →`** guards against speculative fixes and order violations—answer them before edits or merges.
 
-**b. Apply the fix**
+### 1) Ingest findings
 
-- Make the targeted code change.
-- Keep the fix scoped to the finding. Do not expand scope.
+Read the supplied report. If the user says “fix review findings” but attached nothing, reconstruct from git/recent outputs; if **no** reconstructable list exists, **MUST** stop and report. Extract each finding: severity, title, evidence (`path:line` or equivalent), reproduction notes.
+   - **Pause →** Can I attach **severity + excerpt + repro** per row—is anything still vague “looks bad”?
+   - **Pause →** Is this finding **explicitly confirmed** by the reviewer, or only a hypothesis I must shelve?
 
-**c. Validate the fix**
+### 2) Order and (optional) parallelize
 
-- Run the most specific tests covering the changed code.
-- If tests fail, invoke `$systematic-debug` to resolve the failure before proceeding.
-- If the finding includes reproduction steps, verify the reproduction no longer triggers.
-- Only mark the finding as fixed when validation passes.
+Sort into Critical → High → Medium → Low. Optionally group by **module** or **business chain** for parallel work **only** if sub-agents with **isolated workspaces** exist and groups do not share half-applied state.
 
-**d. Track progress**
+**Parallel path** — One package per independent group; each worker fixes its findings **in severity order locally**, validates, returns branch/diff + status. Merge packages one at a time; on conflict, preserve both fix intents; prefer the **more conservative** behavior unless the finding required aggressiveness; **MUST** flag unresolvable conflicts instead of silently dropping a fix. After merge, run consolidated tests.
 
-Proceed to the next finding. Do not skip severity levels: finish all Critical findings before starting High, etc.
+**Serial path (default)** — For each finding in global severity order: read code and repro → apply minimal fix → validate (`systematic-debug` if failures are unclear) → record status → next finding.
+   - **Pause →** Am I respecting **tier closure**—no High work started until every Critical has a settled status (`Fixed`, `Deferred`, `Could not reproduce`)?
+   - **Pause →** If parallelizing: could two workers touch **overlapping** symbols or files midway through—if unsure, serialize.
 
-### 6) Re-validate the full scope
+### 3) Full-scope re-validation
 
-When all findings have been processed:
+After all findings are processed: run relevant tests over touched areas; if code changed and `review-change-set` is available, run it on the post-fix diff; capture `git diff --stat` (or equivalent). **MUST** confirm no confirmed finding remains open without a recorded reason (`Deferred`, `Could not reproduce`, etc.).
+   - **Pause →** Would the **same** reviewer still see **actionable proof** closed for each `Fixed`, or did I rationalize failures away?
+   - **Pause →** Did my consolidated diff sneak in **bonus** unrelated changes—if yes, peel them back?
 
-- If the fix set is code-affecting, optionally run `$review-change-set` on the updated diff to confirm no new issues were introduced.
-- Run all relevant tests across the changed files.
-- Run `git diff --stat` to produce a summary of what changed.
+### 4) Report
 
-### 7) Report the result
+Deliver: (1) Summary by severity. (2) Per finding: `Fixed` / `Could not reproduce` / `Deferred` + location + validation evidence. (3) Final re-validation (review tool result if any, tests, diff stat). (4) Residual/deferred with reasons. (5) User-facing next checks before merge (manual QA, integration, etc.).
+   - **Pause →** Could the user rerun **exactly one** cited command per `Fixed` to trust me—is that cited?
 
-Return:
+## Notes
 
-1. Summary of all findings processed, grouped by severity.
-2. For each finding: status (`Fixed`, `Could not reproduce`, `Deferred`), path:line, and validation evidence.
-3. Final re-validation: new review result (if run), test results, and git change summary.
-4. Any residual findings that were deferred or could not be fixed, with reasons.
-5. Next steps: what the user should verify before merging (e.g., manual QA, integration tests, deployment review).
+- Hypotheses or “might be risky” lines in a report that were **not** confirmed as findings stay **out of scope** for fixes.
 
-## Notes
+## Sample hints
 
-- This skill fixes code only. It does not update specs, documentation, or project constraints unless the review finding explicitly requires it.
-- If the original review report contained hypotheses or unconfirmed risks, leave those untouched — only confirmed findings are actionable.
-- When a finding cannot be reproduced after inspecting the code, report `Could not reproduce` and move to the next finding.
+- **Inbound finding slice** — `HIGH | SSRF via webhook URL | src/net/fetch.rs:112 | curl user-controlled URL without allowlist`.
+- **Serial flow** — fix `HIGH #1`, run `cargo test net_fetch` (or the project’s narrowest test), mark `Fixed` **only after green** → then proceed to `HIGH #2`; do **not** batch three HIGH fixes then test once unless a single coherent patch is unavoidable and validation still proves each finding closed.
+- **Status line**: `HIGH SSRF fetch · Fixed · fetch.rs:105-128 · Verified: cargo test net::fetch + manual blocklisted host`.
+- **`Could not reproduce`**: reviewer cited `middleware.ts:77` leak; current tree shows no such path/commit — note commit inspected and bail with evidence, do **not** invent a finding to satisfy the report.

package/version-release/SKILL.md

@@ -1,27 +1,41 @@
 ---
 name: version-release
-description: "Guide the agent to prepare and publish a versioned release (version bump, changelog, tag, GitHub release, and push). Use only when users explicitly request version/tag/release work, including direct semver wording such as patch/minor/major updates. Depend directly on `archive-specs` when completed plan sets should become durable docs or when project docs need alignment, and let that skill own the downstream documentation synchronization work."
+description: >-
+  End-to-end semver delivery: prerequisites mirror **`commit-and-push`** gates (**`submission-readiness-check`**, reviews, changelog hygiene, optional `archive-specs`), derive next version/tag from tracked files plus explicit user semver words, relocate `CHANGELOG.md` Unreleased into dated release bump package/project metadata evenly commit tag push **`gh release create`** honoring prerelease/retarget rules verify remote refs **NEVER STOP at tag omitting GitHub release unless user waived publication**.
+  Keywords patch minor major release tag GH publish semver… misroute plain “push” absent release vocabulary **use commit-and-push**… BAD guessing version… GOOD inspect package.json+Cargo.toml… retarget prerelease relocate tag `--force-with-lease`… Unreleased emptiness ⇒ halt curated notes…
 ---
 
 # Version Release
 
 ## Dependencies
 
-- Required: `commit-and-push`, `submission-readiness-check` before version metadata edits, tagging, or release publication.
-- Conditional: `archive-specs` when completed plan sets should be converted or repository docs need alignment; `review-change-set` is required for code-affecting releases before metadata edits and the final commit; `discover-edge-cases` and `harden-app-security` are important review gates that remain conditional, but become required whenever the reviewed scope or risk profile warrants them.
+- Required: **`commit-and-push`** (shared inspect/classify/readiness/commit/push mechanics); **`submission-readiness-check`** **before** version files, tags, or publication mutate.
+- Conditional: **`archive-specs`** when specs/docs need alignment; **`review-change-set`** (+ **`discover-edge-cases`** / **`harden-app-security`** when risk triggers) on **code-affecting** release scope **before** version churn—blocking while findings open.
 - Optional: none.
-- Fallback: If a required release dependency is unavailable, stop and report the missing dependency.
+- Fallback: Missing required skill ⇒ stop and report.
 
-## Standards
+## Non-negotiables
 
-- Evidence: Inspect the active change set, current version files, existing tag format, existing remote tags/releases, and root `CHANGELOG.md` `Unreleased` content before touching version files, tags, or release metadata.
-- Execution: Use this workflow only for explicit release intent, run the required quality gates when applicable, and treat every conditional gate whose scenario is met as blocking before versioning or publication; hand the repository to `submission-readiness-check` before versioning work, invoke `archive-specs` directly whenever completed plan sets should be converted or project docs need alignment, and if the worktree is already clean inspect the current version, local/remote tag state, and existing GitHub release state before deciding whether the request is already satisfied; decide whether the GitHub release is a prerelease only from explicit user instruction or explicit repository convention already documented in the request context, never from tag naming alone; when the user explicitly wants the same prerelease version to point at newer fixes, retarget the existing prerelease tag and GitHub release instead of inventing an extra version bump; when editing an existing GitHub prerelease during that retarget flow, use a GitHub-accepted release target such as the intended branch name if the tool or API rejects a raw commit SHA for `target_commitish`; otherwise cut the release directly from `CHANGELOG.md` `Unreleased`, update versions and docs, commit, tag, push, and publish the GitHub release with actual release tooling rather than PR-surrogate directives; run git mutations sequentially and verify both the branch tip and release tag exist remotely before publishing the GitHub release, and never treat UI git directives such as `::git-stage`, `::git-commit`, or `::git-push` as evidence that the release commit or tag already exists.
-- Quality: Never guess versions, align user-facing docs with actual code, do not bypass readiness blockers from `submission-readiness-check`, do not reconstruct release notes from `git diff` when curated changelog content already exists, and do not report release success until the commit, tag, and GitHub release all exist for the same version.
-- Output: Produce a versioned release commit and tag, publish a matching GitHub release, and keep changelog plus relevant repository documentation synchronized.
+- **ONLY** enter this workflow when release intent is **explicit** (semver bump wording, tag/release request, CI “publish release”—not a bare “push”). Else **`commit-and-push`** only.
+- **MUST NOT** guess versions—read workspace version files + user-stated bump; state **current → next** + exact **tag string** before editing.
+- **MUST NOT** publish if root **`CHANGELOG.md` `Unreleased`** is empty/has nothing to ship—stop or curate notes first.
+- **MUST** align all version-bearing files consistently; formatting-only deltas elsewhere.
+- **Tag format** (`v1.2.3` vs `1.2.3`) inferred from repo history—not invented per release ad hoc unless user dictates.
+- **GitHub Release**: prefer `gh release create` / repo tooling; **MUST NOT** substitute “opened PR URL” as release completion. Draft vs prerelease vs **latest** follows **explicit** user/repo convention—not tag shape alone.
+- **Prerelease retarget**: same version, **move** tag/release to new SHA when user asks; use force-with-lease **for tag only** as needed; if API rejects SHA for `target_commitish`, use branch identifier per GitHub rules.
+- **MUST** verify **remote** has commit + tag before calling release **done**; **MUST NOT** trust UI git shortcuts.
+- **Done** = version files + changelog section + **pushed** commit + **remote** tag + **published** GitHub release (unless user explicitly skips publication—then say so).
 
-## References
+**Repository regression checks:** Before creating release metadata, inspect existing local and remote tags plus any existing GitHub Release for the target version so duplicates are caught early. Do not continue until you can state the current version, the intended next version, and the exact tag name that will be created. **`review-change-set` is required for code-affecting releases**—run `review-change-set` for the same release scope before continuing; treat unresolved review findings as blocking. Any conditional gate whose trigger is confirmed by this classification becomes mandatory before version bumping, tagging, or release publication. Treat every scenario-matched gate as blocking before versioning or release publication. **`discover-edge-cases` and `harden-app-security` are important review gates**—when their scenario is met, treat them as blocking review gates, not optional polish. Never stop after the release commit or tag alone; creating the matching GitHub release is part of done criteria unless the user explicitly says to skip release publication.
+
+## Standards (summary)
 
-Load only when needed:
+- **Evidence**: Version files, tags local/remote, `Unreleased`, existing GH releases.
+- **Execution**: Intent → gates (`commit-and-push` pattern) → semver → files → changelog move → commit/tag → push → GH release.
+- **Quality**: No duplicate releases; notes from curated changelog, not raw diff guesswork.
+- **Output**: Announced version, tag URL, release URL, automation status if any.
+
+## References
 
 - `references/semantic-versioning.md`
 - `references/commit-messages.md`
@@ -31,100 +45,50 @@ Load only when needed:
 
 ## Workflow
 
-### 1. Inspect Current Changes
-
-Use $commit-and-push for the standard git state inspection workflow.
-
-### 2. Confirm Release Intent
-
-- Use this skill only when the user explicitly requests version/tag/release work.
-- Treat explicit semver-delivery wording such as `patch update`, `minor update`, `major update`, `patch release`, `bump the version`, or requests to trigger release-published automation as release intent even when the user does not separately say `make a release`.
-- If no release intent is present, use `commit-and-push` instead.
-
-### 3. Classify Changes and Run Dependencies
+**Chain-of-thought:** Reuse **`commit-and-push`** for git inspection, classification, conditional reviews, **`submission-readiness-check`**, commit discipline, push verification—**do not duplicate** those rules here; **`Pause →`** applies to release-only decisions.
 
-Use $commit-and-push for the standard change classification and code-affecting dependency skills workflow.
+### 1) Inspect git state
 
-Release-specific requirements:
-- For code-affecting changes, run `review-change-set` for the same release scope before continuing; treat unresolved review findings as blocking.
-- Run `discover-edge-cases` and `harden-app-security` for the same release scope when the reviewed risk profile or repository context says their coverage is needed; treat them as blocking review gates, not optional polish, whenever that condition is met.
-- Any conditional gate whose trigger is confirmed by this classification becomes mandatory before version bumping, tagging, or release publication, including review, spec archival, docs synchronization, and changelog readiness.
-- Consolidate all confirmed findings before continuing.
-- Resolve all confirmed findings before changing version files, tags, or release metadata.
+- Follow **`commit-and-push`** step 1 (status/diff/clean semantics).
 
-### 4. Run Shared Submission Readiness
+### 2) Confirm release intent
 
-Use $commit-and-push for the standard submission readiness workflow.
+- Explicit semver/release language—or stop and use **`commit-and-push`**.
+   - **Pause →** Did the user only ask “commit”? If yes, **exit** this skill.
 
-### 5. Decide Version and Tag Format
+### 3) Gates before version churn
 
-- Read existing version files (for example `project.toml`, `package.json`, or repo-specific version files).
-- Infer existing tag format (`vX.Y.Z` or `X.Y.Z`) from repository tags.
-- Inspect existing local and remote tags plus any existing GitHub Release for the target version before creating new release metadata, so duplicate or conflicting releases are caught early.
-- Determine release channel explicitly before publishing: if the user did not say `prerelease`, `draft`, `latest`, or an equivalent repository-specific release state, default to asking or to the repository's already-documented convention instead of inferring from the tag text.
-- If the user explicitly asks to keep the same prerelease version or to `repoint`, `retarget`, or `move` an existing prerelease after follow-up fixes, treat that as a retarget flow: keep the version unchanged, confirm the existing prerelease tag/release name, and plan to move that tag/release to the new commit instead of bumping semver.
-- If the requested version tag and matching published GitHub release already exist and point at the intended commit, report that the release is already complete instead of creating duplicate metadata.
-- If the user provides the target version, use it directly.
-- If it is missing, ask the user for the target version or semver bump type.
-- Provide recommendations only when explicitly requested.
-- Do not continue until you can state the current version, the intended next version, and the exact tag name that will be created.
-- For retarget flows, explicitly state that the intended next version stays unchanged and that the existing tag name will be moved to the new commit.
+- Classify scope; code-affecting ⇒ `review-change-set` (+ conditional edge/security same as **`commit-and-push`**); **`submission-readiness-check`** (+ **`archive-specs`** when indicated). All blocking items closed.
+   - **Pause →** Am I versioning while `Unreleased`/readiness still wrong?
 
-### 6. Update Version Files
+### 4) Decide version & tag
 
-- Update every detected version file consistently.
-- Preserve file formatting; change only version values.
+- Read files; inspect local/remote tags + existing GH release for collision; prerelease vs stable per user/doc; retarget flow leaves version unchanged.
+   - **Pause →** If tag+release already correct on intended SHA—report satisfied, duplicate nothing.
 
-### 7. Update Release Docs
+### 5) Bump files
 
-- Treat root `CHANGELOG.md` `Unreleased` as the canonical pending release content.
-- If `Unreleased` is empty, stop and report that there are no curated release notes to publish yet.
-- Create the new version entry by moving the current `Unreleased` sections under the selected version heading and release date.
-- Reset `Unreleased` to an empty placeholder after the version entry is created.
-- Remove duplicate section headers or bullets only when the move would otherwise create repeated content.
-- Update `README.md` only when behavior or usage changed.
-- Update `AGENTS.md/CLAUDE.md` only when agent workflow/rules changed.
+- Every locator of version bumped consistently.
 
-### 8. Commit and Tag
+### 6) Release docs
 
-Use $commit-and-push for the standard commit mechanics workflow.
+- Move **`Unreleased`** → new dated heading; reset `Unreleased` scaffold; **`README`** / **`AGENTS.md`**/`CLAUDE.md` only if behavior/agent workflow changed materially.
 
-Release-specific commit and tag operations:
-- Create a release-oriented commit message (for example `chore(release): publish 2.12.1`) when applicable.
-- For new-version flows, create the version tag locally after commit.
-- For prerelease retarget flows, move the existing tag locally only after the new fix commit exists, and verify the target commit hash before rewriting the tag.
-- Re-read the version files after editing and before tagging to confirm they all match the intended release version.
+### 7) Commit & tag
 
-### 9. Push
+- Message e.g. `chore(release): publish X.Y.Z` per repo habit; tag after commit; retarget ⇒ move existing tag deliberately with hash discipline.
 
-Use $commit-and-push for the standard push mechanics workflow.
+### 8) Push
 
-Release-specific push operations:
-- Push commit(s) and the release tag to the current branch before publishing the GitHub release when the hosting platform requires the tag to exist remotely.
-- For prerelease retarget flows, push the rewritten tag explicitly (for example `--force-with-lease` for the single tag only), then verify the remote tag hash matches local `HEAD` before touching the GitHub release.
-- After pushing, verify the release tag exists remotely via `git ls-remote --tags <remote> <tag>`.
+- Push branch **and** tag; verify remote refs; retarget ⇒ `--force-with-lease` for tag only where appropriate, then verify.
 
-### 10. Publish the GitHub Release
+### 9) Publish GitHub Release
 
-- Create a non-draft GitHub release that matches the pushed version tag.
-- Set the GitHub release's prerelease flag only when the user explicitly asked for a prerelease or an already-verified repository convention for this exact release channel requires it.
-- For prerelease retarget flows, update the existing GitHub prerelease so it points at the rewritten tag/commit and refresh its notes when the new fix changes the shipped behavior.
-- If the release tool rejects a raw commit SHA while updating `target_commitish`, retry with the authoritative branch name or another GitHub-accepted target identifier, then verify the published release now resolves to the rewritten tag.
-- Use the release notes from the new `CHANGELOG.md` entry unless the repository has a stronger established release-note source.
-- If the repository has publish automation triggered by `release.published`, ensure the GitHub release is actually published rather than left as a draft.
-- Prefer `gh release create <tag>` or the repository's existing release tool when available.
-- Do not use PR-opening tools, PR directives, or placeholder URLs as a substitute for actual release publication.
-- Confirm the GitHub release URL and any triggered publish workflow status in the final report.
-- Never stop after the release commit or tag alone; creating the matching GitHub release is part of done criteria unless the user explicitly says to skip release publication.
+- Create/update matching release body from changelog section; prerelease flag per explicit instruction; confirm non-draft unless automation needs draft—but user asked “publish” ⇒ actually publish.
+   - **Pause →** Can I paste **release URL** + prove tag points at **`HEAD`**?
 
-## Notes
+## Sample hints
 
-- Never guess versions; always read from files and user intent.
-- Treat every scenario-matched gate as blocking before versioning or release publication, not as an optional reminder to maybe do later.
-- Never skip `review-change-set` for code-affecting releases, and do not continue to versioning work while confirmed review findings remain unresolved.
-- Never downgrade `discover-edge-cases` or `harden-app-security` to optional follow-up when the release risk says they apply.
-- Never claim a release is complete without checking the actual release version, creating the matching tag, and publishing the matching GitHub release.
-- Never treat a PR creation step, release-page URL guess, or tag-only push as evidence that the GitHub release exists.
-- Never treat `::git-stage`, `::git-commit`, `::git-push`, or similar UI helpers as proof that the release commit, pushed tag, or remote branch update actually happened.
-- If tests are required by repository conventions, run them before commit.
-- If a new branch is required, follow `references/branch-naming.md`.
+- **`Unreleased` empty** ⇒ cannot ship “2.5.0” with honest notes—curate first.
+- **Duplicate**: Tag `v2.5.0` exists on GH → **inspect SHA** before re-creating.
+- **Retarget**: User “move prerelease to latest fix”—**no** semver bump; rewrite tag carefully.