aiops: changelog-agent - Deliver portable changelog operations #2653

AI Ops Summary

Extend the existing canonical agents/changelog-agent/ package for inspect, draft, validate, prepare-release and exact approved-apply operations, preserving history and supplying blocking Release verification.

Build Summary

Deliver the five operations through the existing canonical package and supported interfaces. Reference genuinely shared root skills rather than creating a competing canonical agent or validator; keep target paths and policy repository-specific.

Linked Stories/Tasks/PRs/Epic

Parent: GIT-1293. GitHub counterpart: lightspeedwp/.github#2653.

PR #2655 closed without merging; its documentation and tracking work is not evidence that this shared skill exists.

Milestones & Timeline

Existing milestone: v1.1. Reconfirm sequencing against the current changelog agent.

Problem / Opportunity

Verify the current implementation and agreed portable skill location before adding code. Historical absence at the proposed path is not evidence that equivalent functionality is absent elsewhere.

Approach / Solution

Confirm the portable skill location and contract. Preserve the original operations—inspect changelog state, draft an entry, validate formatting and type, prepare release changes, and report or safely apply approved updates—while separating read-only analysis from writes. Test duplicate entries, missing sections and failed partial updates.

Use the agreed bundled validation-engine copy with a recorded pin/version and drift checks. Verification must identify the target and inspected revision or content, report valid, invalid or missing evidence, and record the engine version. A verification response does not authorise edits.

Apply only separately approved exact changes after rechecking the target content. Validate the result and demonstrate recovery on failure; report unrecoverable failures explicitly rather than claiming success.

Acceptance Criteria

• Five operations and their inputs, outputs and permissions documented.
• Skill works across intended repositories with configured paths and taxonomy.
• Dry-run, approval and recovery boundaries prevent unreviewed changelog edits.
• Validation and representative integration tests pass.
• Existing changelog-agent guidance reconciled rather than duplicated.

Additional Context

Current native status and labels remain unchanged. Historical label commentary and a closed, unmerged PR do not establish current readiness or delivery.

Definition of Ready (DoR)

• Canonical location, operations and write permissions agreed.
• Current agent integration points confirmed.
• AI ops goal described
• Area/action mapped
• Acceptance criteria listed
• Estimate added

Definition of Done (DoD)

• Skill, tests and documentation reviewed and merged.
• Approved integration and safe-write behaviour demonstrated.

Portable changelog delivery contract — spec 022

Outcome: extend existing changelog behaviour through the five operations already described, without duplicating the shipped validation engine.

Acceptance evidence

• Inspect, draft, validate, prepare and approved-apply operations have explicit inputs, outputs and permissions.
• Historical entries and links are preserved; repeated operations do not duplicate entries or Unreleased sections.
• Portable validation uses the agreed bundled engine copy, records its pin/version and detects drift.
• Target paths and policy are configurable and confined to the selected repository.
• Dry runs have no writes; approved updates demonstrate failure and recovery behaviour.
• Verification reports distinguish valid, invalid and missing evidence for the release-agent handoff.
• Focused tests and usage instructions accompany the implementation.

PR strategy: second implementation priority. Proposed branch aiops/changelog-agent-portable-validation, targeting updated develop after required consolidation merges. Proposed title aiops: changelog-agent - Add portable changelog operations. Reuse an existing matching PR if present.

Use the live AI Ops PR template. Proposed primary GitHub label: type:aiops; verify the remaining labels and changelog disposition before application. Preserve Chris’s ownership; do not assign the PR to Ash by assumption.

Prefer an independent PR. Stack only for a demonstrated code dependency with an approved merge/retarget plan. Close GitHub lightspeedwp/.github#2653 only when its accepted scope is complete.

Excluded: REST service implementation, speculative spec 016 features, workflow activation, release publication and unrelated documentation restructuring.

Canonical acceptance and handback allocation

Map C1–C10 in Canonical agent PRD — Changelog Agent to reviewed implementation paths and attributable evidence. Reuse existing definition/generator consolidation where required. Preserve current ownership; decide PR assignment separately.

Implement the shared changelog-verification/v1 producer contract. Bundle the shipped engine with dependency, source-commit, hash, rules and licence provenance, plus refresh/drift verification.

Test blocking findings hidden by warning, exit-zero or empty output. Unavailable required link verification remains missing evidence.

Default operations do not write. Approved-apply requires the exact formatted-byte digest, source recheck, output revalidation, idempotency and per-file recovery or explicit unrecoverable reporting.

Preserve released history, source/compare links, a fresh Unreleased section, Unicode and line endings. Require independent package/host-loading, permission-denial and retained-consumer evidence before retirement.

Executable relocation and new manifests remain gated on human-reviewed policy approval. Freeze exact files and independently reviewable PR slices before coding. This proposal authorises no workflow activation, CI override, publication, deletion or automatic closure.

Delivery-evidence review — 13 October 2026

Inspection at develop commit 65a013b25eb4f81806496965adad8e3f458a34e5 confirmed existing parser, validator and formatting foundations—not acceptance of the five portable operations, trusted verification producer, provenance/drift handling or approved-apply recovery.

PR #3820 delivered specification/skill/index alignment; its reported tests were not independently rerun. No attributable implementation PR or current acceptance results were found in the inspected records.

Exact implementation files and acceptance suites remain unfrozen. Proposed bundled-engine locations and new suites are policy-gated proposals, not approved create actions.

Release specification numbering — 19 October 2026

Portable Release and Changelog agents are assigned specification 022. The planned folder is .github/specs/022-portable-changelog-release-agents/, replacing .github/specs/020-portable-changelog-release-agents/ on the existing branch.

Database migration remains 020. Repository restructuring remains 021. This supersedes the earlier instruction to retain release specification 020; preserve dated historical evidence.

WordPress schema audit also claims 021, but its replacement number remains unresolved. Do not assign it 022 or another number by inference.

Reconcile the catalogue, internal links, feature-directory settings and active references. This records the requested migration—not completed repository changes or validation. Preserve task IDs and existing delivery boundaries.