[brandonmarshal]

Refactor Pull Request

This repository enforces changelog, release, and label automation for all PRs and issues.
See the organisation-wide Automation Governance & Release Strategy for required rules.

Stack

• Position: PR 4 of 6
• Issue/Epic: LS-4771 under epic LS-4750 and LS-4744
• Depends on: refactor: ls-wp-release - Fix doc links, add changelog handoff and script policy #4 (this PR is based on refactor/ls-4770-docs-accuracy, not main), which depends on refactor: ls-wp-release - Fix helper script side effects, SVN layout and packaging docs #2 and refactor: ls-wp-release - Fix release skill validators, paths and hook gates #1
• Followed by: chore: ls-wp-release - Migrate tests to Vitest, add Renovate and fix hooks #6 (Vitest migration, Renovate and hook fixes, based on this branch)
• Review scope: the review of the lightspeed-release-ops skills, the notes merged from them, and three small fixes listed below

Linked issues

Relates to LS-4771 (Linear). This is a supporting layer of the stack and does not close the issue. There is no GitHub issue for this work, so there is nothing to auto-close.

Summary

The lightspeed-release-ops plugin pack has six skills that were proposed for import. Each SKILL.md is a stub: a heading, one sentence repeating its description, and a footer. Five overlap existing sub-skills in detail, and the sixth overlaps rules that already live in the release prompt, the agent and changelog-management. Importing the stubs as new sub-skills would add files that restate existing sub-skills with less detail, so this PR merges the stubs' content into the existing sub-skills and records the review. No new sub-skill is added.

Release-ops review

• New docs/RELEASE_OPS_SKILLS_REVIEW.md compares each source skill with the existing sub-skills, pinned to lightspeedwp/.github at 47aee0722033f65d4d9d57429b410b518646b817.
• It records the decisions: merge instead of import, keep linking the sub-skills from the root SKILL.md (no plugin packaging), and use the source pack's licence (GPL-3.0).
• It lists what stays open: root skill name, nested discovery, deployment scope, and real content for the gaps the source only names (semantic-release alignment, deployment safety, mitigation advice).

Merged source notes

• A short "Source Pack Notes" section is added to release-qa (readiness, risk assessment and rollout checklist), changelog-management (changelog compliance and version bump planner) and release-notes-generator (release notes).
• Each note quotes the stub's one-line description, credits the source (repository, path, commit, GPL-3.0), and says what the existing sub-skill does not cover. No existing text, skill name or frontmatter changed.

Rollout plan flags

• docs/TEAM_ROLLOUT_PLAN.md used flags that do not exist: --validate-setup, --validate-release, --show-details, --post-release-check, --confirm, --help and --type. They are replaced with the real flags from SKILL.md (--dry-run, --scope=, --verify), or removed where the agent already pauses and asks.
• The plan no longer says --dry-run checks that git hooks are installed. It says hooks are checked with lefthook install.

Staging example

• The version-mismatch example in release-qa stages named files instead of git add -A.

Licence

• package.json now says GPL-3.0 and docs/DEVELOPMENT.md describes the LICENSE file as GPL-3.0. This matches the LICENSE file, which is the GNU GPL version 3.

Scope and exclusions

• Not in this PR:
  • No source skill, manifest, metadata.yml, platform file or orchestrator agent is imported.
  • /release --draft-notes in the rollout plan is not a documented flag either, but it was not on the planned list and is left.
  • The README's licence line ("internal toolkit") is unchanged. Other GPL-2.0 mentions in the docs are example headers for released WordPress projects.
  • Root skill name, nested discovery and deployment scope remain open decisions.
• The flag, staging and licence fixes were left out of refactor: ls-wp-release - Fix doc links, add changelog handoff and script policy #4 and are made here.
• Review size: 7 files, 179 insertions, 29 deletions (107 lines are the new review document). Within the review budget. No files were excluded from the count.
• Screenshots/video: not applicable, there is no visible UI change.

Safety Nets

• Existing tests covering behaviour: none for these documents. npm test covers only the repository's validators.
• New/refined tests added: none. This is a documentation and metadata change.
• Static analysis/lint rules touched: none.

Approach

• Structural changes (APIs, patterns): none. Documentation and one package.json metadata field. No script, hook or dependency changed.
• Dead code removed? No.

Metrics / Benchmarks (if applicable)

• Before (on refactor: ls-wp-release - Fix doc links, add changelog handoff and script policy #4): 12 uses of the five unsupported flags in docs/TEAM_ROLLOUT_PLAN.md, and package.json said GPL-2.0 while LICENSE is GPL v3.
• After: 0 uses of those flags, and the licence fields agree. The link validator reports 41 broken links both before and after.
• Markdownlint violation counts are unchanged on all five edited Markdown files, and the new document is clean.

Verification

• Unit tests pass locally (npm test: 41 pass, 0 fail)
• Key flows smoke-tested: structure validator exits 0, JSON validator exits 0, package.json parses, link validator 41 broken links (unchanged)
• Edited markdown files have the same markdownlint violation counts as before
• No user-visible diffs observed: not true. The rollout plan commands change.
• Human review of the merge decision, the flag replacements and the licence change

Risk & Rollback

• Risk level: Low. Documentation and one metadata field. The licence change affects the declared licence in package.json, so it needs a human read.
• Rollback plan: revert the commit. No code, data, release state or published artefact is touched.

Changelog

This repository has no CHANGELOG.md, and the meta:needs-changelog / meta:no-changelog labels do not exist here, so no changelog file entry is added. Supporting layers normally leave the entry to the owning PR. Notes for release automation if one is added later:

Added

• A review of the lightspeed-release-ops skills, with source notes merged into three sub-skills. (Relates to LS-4771)

Changed

• The rollout plan uses the real /release flags.
• package.json declares GPL-3.0.

Fixed

• The release-qa version-mismatch example no longer uses git add -A.

---

Checklist (Global DoD / PR)

• All AC met and demonstrated
• Tests added/updated (unit/E2E as appropriate)
• Accessibility checklist completed (where relevant):
  • Semantic HTML and heading order verified
  • Keyboard navigation and visible focus states verified
  • ARIA used only where needed
  • Contrast and non-colour cues reviewed (WCAG 2.2 AA)
• Docs/readme/changelog updated (if user-facing)
• Security checklist completed (where relevant):
  • Untrusted input validated and sanitised
  • Output escaped for its rendering context
  • Privileged actions enforce nonce and capability checks
  • No secrets/sensitive data introduced; OWASP risks reviewed
• Code/design reviews approved
• CI green; linked issues closed; release notes prepared (if shipping)

---

🤖 Generated with Claude Code

[linear-code]

LS-4771

[brandonmarshal]

Looks good with minor notes — static review only

Reviewed all seven changed files at head a93f8358c4289129856a1ad910fe8e181eaa1d5a against its own stacked base 5f742e38cc65fb723b5420fd6c6a2e05c5bfc0f9, including comparison with all six source skills at the pinned source revision.

No actionable defect identified in the changed files; no inline comments proposed. Attributed source notes preserve existing skill identities/frontmatter, the targeted rollout examples match the documented release contract, and GPL-3.0 metadata agrees with the existing licence text. No platform variants, orchestrator or new publishing implementation were imported.

Minor metadata note: the Stack section still says “PR 4 of 5 (planned)” and “Followed by: not yet opened”. The established stack contains six PRs, with PR #6 following this layer.

The stated exclusions remain unresolved, not new findings. Host discovery, installation, release execution and reported test/lint results were not independently verified.

No commands were executed. Earlier-layer findings remain dependencies; no fixes were applied during this review. No later stack layer was reviewed, and this is not merge or release approval.

[brandonmarshal]

Review note addressed

• The Stack section now reads PR 4 of 6 and Followed by: #6.
• No code finding was raised on this layer. The branch now contains the fixes from refactor: ls-wp-release - Fix release skill validators, paths and hook gates #1, refactor: ls-wp-release - Fix helper script side effects, SVN layout and packaging docs #2 and refactor: ls-wp-release - Fix doc links, add changelog handoff and script policy #4 (merge commit from refactor/ls-4770-docs-accuracy), with no other change.

🤖 Generated with Claude Code