Skip to content

aiops: release-agent - Deliver portable preparation #1563

Open

Description

@ashleyshaw

AI Ops Summary

Extend the existing release-agent implementation for portable, read-only preparation across the control plane, WordPress plugins and WordPress themes. Confirm its canonical location against adopted agent standards; do not create a parallel implementation from the historical directory reference.

Build Summary

Deliver bounded preparation and evidence reporting, not release execution.

Linked Stories/Tasks/PRs/Epic

Parent #1546; specification #1555 / PR #3883; consolidation #3880 / PR #3881; changelog verification #2653.

Milestones & Timeline

First implementation priority. No new deadline or milestone commitment.

Problem / Opportunity

Release automation needs a reusable agent that can identify the repository type and apply the appropriate version-handling behaviour.

Approach / Solution

Reuse the existing implementation and verified WordPress utilities. Implement repository-root confinement, target-specific detection, configuration and version-source validation. Automatic version edits remain outside this issue.

Acceptance Criteria

  • Approved four-file root-entry preparation slice implemented and verified; canonical runtime relocation and full package hardening remain separately scoped.
  • Repository type detection implemented
  • Configuration schema defined
  • Version sources discovered and validated per target repository without automatic writes.
  • Documentation complete
  • All repository types tested
  • Code merged to develop

Additional Context

  • Depends on the related release-agent specification.
  • Related release workflow, plugin version-handling, theme version-handling, rollback, changelog-agent, and release-utilities work should remain aligned.

Definition of Ready (DoR)

  • AI ops goal, area/action, and acceptance criteria mapped
  • Related specification available

Definition of Done (DoD)

  • Criteria met
  • Agent behaviour verified across repository types
  • Documentation updated

Portable preparation delivery contract — spec 022

Outcome: extend the existing release implementation for explicitly selected repositories. Do not create a parallel implementation solely because the older description names a different directory.

Scope: repository-root confinement; target-specific instructions and required checks; plugin/theme detection; authoritative version-source discovery; conflicting or missing evidence; dirty-tree refusal; read-only readiness results.

Reuse WordPress release utilities after verifying their callers and tests. Plugin/theme version changes remain separately bounded work; do not silently absorb every existing version-handling issue.

Acceptance evidence

  • Operations use the selected repository root, not the process working directory.
  • Version sources and required checks come from target evidence, without imposing a mandatory VERSION file.
  • Missing checks, ambiguous versions, unsafe paths and dirty trees produce explicit blocking results.
  • Read-only checks and dry runs leave files, commits, branches, tags, PRs and releases unchanged.
  • Any edit operation requires separately approved changes and demonstrated validation/recovery safeguards.
  • Precheck success is distinguished from final readiness; final readiness requires the agreed changelog verification.
  • Focused failure-path tests and local usage instructions ship with the implementation.

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

Use the live AI Ops PR template, preserving its sections. Proposed primary GitHub label: type:aiops; resolve the exact available review, area, changelog-disposition and shipping labels against current governance before applying them. Preserve Ash’s issue ownership; verify the PR assignee mapping.

No automatic stack. A stack on PR aiops: release agents - Consolidate release and changelog agent guidance requires a demonstrated code dependency and an approved base/merge/retarget plan. Close GitHub lightspeedwp/.github#1563 only when its accepted scope is complete; never close the epic through this PR.

Excluded: workflow restoration, automatic version writes, tagging, publication, live deployment and unrelated agent restructuring.

Approved initial slice and closure boundary

Implement the approved Release preparation handoff:
https://linear.app/lightspeedwp/issue/GIT-1310/aiops-release-agent-deliver-portable-preparation#comment-be60c834

Exact tracked allowlist:

  • scripts/agents/release.agent.js
  • scripts/agents/__tests__/release.agent.test.js
  • scripts/agents/__tests__/release.agent.mcp.test.js
  • agents/release-agent/README.md

Validators remain inline; fixtures are temporary only. No fifth tracked schema/fixture, canonical library edit, executable relocation, policy amendment, provider dispatch or workflow restoration.

Use release-preparation/v1, release-preparation-evidence/v1 and changelog-verification/v1. Inspect and dry-run perform audited filesystem/Git reads only. Reject mutating operations before activity; imports have no side effects. Reports retain proposedEdits: [], writeSet: [], writes: 0.

Unverified supplied checks or handback cannot establish readiness. Prechecks may pass while final status remains not-ready; missing response within the same invocation blocks readiness.

Verify current-revision safety, refusal and schema cases, with unchanged target bytes, index, refs and input objects. Document deferred unsafe canonical entry surfaces in the README.

Closure requires the approved four-file outcome and attributable evidence—not full package migration, approved version edits, host compatibility or epic completion.

Delivery-evidence review — 13 October 2026

Read-only inspection used develop commit 65a013b25eb4f81806496965adad8e3f458a34e5; no tests were rerun. The existing Release executable retained mutation paths. Confined preparation, blocking refusals and the versioned handoff were not demonstrated at that revision.

No attributable implementation PR or executed focused acceptance results were found in the inspected records. PR #3881’s Release executable changes were comment references, not preparation implementation.

This is dated evidence, not proof that unpublished or subsequent work does not exist. Preserve the approved four-file closure boundary and separately allocated migration, compatibility, version-edit and publication work.

Release preparation acceptance-evidence checklist

Authority and evidence status

This checklist derives from the approved four-file preparation handoff. It organises acceptance evidence; it does not authorise implementation, execute tests or certify completion.

The handoff’s approval prefix and current issue description identify the approved planning decisions. Historical “proposed” wording remains preserved, not treated as implementation evidence.

All checks below remain unchecked pending attributable evidence. The dated 13 October repository review found no attributable preparation implementation PR or executed focused acceptance results; it does not establish that subsequent or unpublished work is absent.

1. Exact scope

  • Tracked changes are confined to:
    • scripts/agents/release.agent.js
    • scripts/agents/__tests__/release.agent.test.js
    • scripts/agents/__tests__/release.agent.mcp.test.js
    • agents/release-agent/README.md
  • Validators remain inline; test fixtures are temporary. No fifth tracked schema or fixture is introduced.
  • No canonical-library edits, executable relocation, policy amendments, provider dispatch, networking, workflow restoration or publication are included.

Evidence: attributable PR, complete changed-file list and reviewed diff at an exact head commit.

2. CLI, API and compatibility refusals

  • inspect is the default; dry-run and its approved aliases perform real read-only checks.
  • Unknown/duplicate flags, --dry-run=false, conflicting scope/version, provider selection and apply/publication operations are rejected.
  • Exit codes match the handoff: 0 final ready; 1 valid invocation not-ready; 2 invalid arguments/schema/unsupported operation; 3 unexpected internal failure. Help exits 0 without target inspection.
  • Named prepareRelease(input) and run(input) return the same Report contract. run(input) does not read process.argv; API calls never invoke process.exit.
  • Imports cause no inspection, execution, logging, credential loading or writes.
  • Existing mutating exports refuse with operation-deferred before filesystem, Git or network activity. Retained pure helpers remain non-mutating and correctly target-bound.
  • Caller input objects remain unchanged.

Evidence: focused assertions, refusal regressions and CLI/API results tied to the implementation commit.

3. Contracts and evidence binding

  • Inline validation implements the exact saved release-preparation/v1, release-preparation-evidence/v1 and changelog-verification/v1 contracts, including required fields, enums and explicit nullable values.
  • Unknown fields, duplicate paths/check IDs, invalid hashes, invalid source-line ranges and invalid required integers are rejected.
  • File hashes use exact bytes; snapshot digests use the saved canonical JSON and file-ordering rules.
  • Strict SemVer and valid calendar dates are enforced without implicit v prefixes or clock-inferred dates.
  • Every Report retains proposedEdits: [], writeSet: [] and writes: 0.
  • Handback matching checks request, repository snapshot, version, date, content and expected engine/rules provenance.
  • Missing, invalid, stale, forged or incomplete required evidence blocks readiness.
  • Supplied hashes or success assertions do not establish authentic execution. Prechecks may pass while final status remains not-ready.
  • The snapshot is rechecked before return; changed evidence produces stale-evidence.

Evidence: schema boundary tests, handback regressions and representative reports. The saved handoff remains authoritative for complete field definitions.

4. Target authority and version discovery

  • Descriptor candidates are independently checked against actual target sources; matching hashes/quotes alone do not establish authority.
  • Unsupported or ambiguous declarations remain unconfirmed and not-ready.
  • No mandatory VERSION, automatic package preference, first-plugin-header selection or repository-name-based component assumption is introduced.
  • Competing version candidates are reported; explicit source-backed selection resolves ambiguity. Enhancements require their own component/version declaration.
  • Scope arithmetic occurs only in memory after identifying one authoritative stable current version; unsupported prerelease advancement blocks.
  • Missing intent/date prevents a verification request, not inspection. Tag names come from target policy.
  • Local tag conflicts block; unavailable required remote-tag evidence produces missing-check without fetching or probing remotely.

Evidence: temporary fixtures covering control-plane, plugin, theme, enhancement and ambiguous/unknown targets.

5. Read-only confinement

  • The root is canonicalised once with realpath; a genuine selected root symlink is allowed and reported.
  • Git top-level matches the canonical root; descendant symlinks, path escapes and nested-repository substitution are rejected.
  • Descriptor/evidence files remain confined to the target root.
  • Git uses argument arrays and explicit -C, with no shell interpolation.
  • Inherited GIT_* settings are cleared; reviewed read settings include GIT_OPTIONAL_LOCKS=0 and disabled fsmonitor.
  • No arbitrary scripts, npm commands, hooks, engine dispatch, checkout, staging, refresh, fetch or publication run.
  • Dirty-state checks include staged, unstaged and untracked changes.
  • Target bytes, index, refs and caller inputs remain unchanged across success and refusal paths.

Evidence: mutation-denial assertions and fixtures for root symlinks, descendant escapes, differing working directories, hostile Git environments and dirty targets.

6. Focused execution evidence

  • Both approved test files pass against the recorded implementation commit using Node 24.20.0, pre-existing dependencies and enabled global Jest safeguards.
  • Results cover missing checks, invalid versions/dates/tags, ambiguous authority and forged/stale/incomplete handbacks.
  • Execution records include repository/head, Node version, exact command, exit status, test totals and complete output.

Saved focused command—not executed by this checklist:

JEST_ENVIRONMENT=node JEST_COLLECT_COVERAGE=false \
node node_modules/jest/bin/jest.js --config .jest.config.cjs \
  --runInBand --coverage=false --runTestsByPath \
  scripts/agents/__tests__/release.agent.test.js \
  scripts/agents/__tests__/release.agent.mcp.test.js

No dependency installation, hook bypass or configuration edits are implied.

7. Documentation and closure

  • README documents exact commands, contracts, refusal behaviour, readiness limitations and deferred unsafe canonical entry surfaces.
  • Reviewed implementation and focused acceptance evidence are attributable to the accepted scope.
  • The accepted changes are merged to develop, with merge evidence recorded.
  • Closure is explicitly limited to this four-file outcome; it does not certify package-wide hardening or complete the delivery epic.

Deferred—not four-file closure requirements

Trusted producer execution, canonical runtime relocation, full packaging, host/provider compatibility, version edits/apply/recovery, script-placement policy changes, workflow restoration, tagging, publication and live deployment remain separately scoped.

No retirement, deletion or wider migration authority follows from this checklist.

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.

Release preparation evidence review — 19 October 2026

Confirmed at inspected revision: develop commit 8f28eca80bff198879f7aaf496717dc0551bb32e retains the older release executor. All four allowlisted files remain unchanged from the previously reviewed baseline. Required preparation APIs, versioned contracts, confinement, early mutation refusals and acceptance coverage are not demonstrated.

Evidence gaps: No attributable four-file implementation PR, executed focused acceptance results or accepted implementation merge was found in the inspected records. Searches were not exhaustive; unpublished work may exist. No tests, installations or changes were performed.

Needs confirmation: Whether an unpublished implementation branch exists; its exact head and changed-file list; attributable acceptance results and merge evidence; completion of specification 022 migration, including catalogue, links and feature settings. The inspected specification PR still retained release 020 references.

Recommendation—not implementation authority: The operator should identify any existing implementation first. Review it against the saved four-file checklist; otherwise, prepare a bounded implementation brief for fresh approval. Operator/reviewer ownership needs confirmation. Acceptance and closure remain unestablished; wider migration and publication remain separately scoped.

Activity

  1. linear-code commented on Aug 5, 2026

    @linear-code
  2. github-actions commented on Aug 5, 2026

    @github-actions
    Contributor

    ⏱️ Aging and SLA annotation

    • Age: 0 day(s)
    • SLA state: Within SLA
    • Thresholds: warn at 7 days, breach at 14 days
    • Last updated: 2026-08-05T09:02:46.459Z

    Maintained by project-meta-sync workflow.

  3. github-actions commented on Aug 5, 2026

    @github-actions
    Contributor

    ✅ Template check passed after update. Thanks for fixing the issue body.

  4. 23 remaining items

  5. changed the title [-]aiops: release-agent - Build portable agent[/-] [+]aiops: release-agent - Deliver portable preparation MVP[/+] on Oct 10, 2026
  6. changed the title [-]aiops: release-agent - Deliver portable preparation MVP[/-] [+]aiops: release-agent - Deliver portable preparation[/+] on Oct 10, 2026
  7. removed their assignment
    on Oct 19, 2026
  8. linear-code commented on Oct 19, 2026

    @linear-code

    @krugazul (@krugazul) — Portable Release and Changelog agents are assigned specification 022. Rename .github/specs/020-portable-changelog-release-agents/ to .github/specs/022-portable-changelog-release-agents/ on the existing branch and reconcile catalogue, internal links, feature-directory settings and active references. Database migration remains 020; repository restructuring remains 021. This supersedes the earlier instruction to retain release 020; preserve historical evidence and task IDs. Schema audit's competing 021 needs a separately agreed replacement number—none is assigned. This records the requested migration, not completed repository changes or validation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

Fields

Priority

None yet

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions