@guiho/runx 0.4.1 → 0.5.1

package/docs/architecture/cli-architecture.md

@@ -20,13 +20,18 @@ owner: runx-architecture
 
 ## Flow
 
-`cli.ts` defines a Citty command tree. Citty parses options and positionals,
-resolves nested commands and aliases, and renders ordinary usage. A bounded
-command-map adapter preserves the legacy `runx <selector>` shorthand while
-known Citty commands retain precedence. Manifest commands use `manifest.ts` to
-discover the nearest `runx.yaml`, parse YAML, validate a strict TypeBox schema,
-and resolve a selector. `render.ts` presents text or JSON. `executor.ts` spawns
-exactly one configured shell command only for a real run.
+`cli.ts` defines one Citty command tree. Citty parses options and positionals,
+resolves nested commands, and renders usage. Manifest commands use
+`configuration.ts` to resolve `runx.yaml` by explicit path, effective cwd, then
+global fallback; TypeBox validates the complete shape. `render.ts` presents
+text or JSON. `executor.ts` spawns exactly one configured shell command only for
+a real `runx run`.
+
+After an ordinary command routes through Citty, `agent-maintenance.ts` receives
+the decoded effective cwd and detaches a hidden worker. The worker compares
+embedded skill content with both global copies and atomically reconciles one
+nearest `AGENTS.md` block. Explicit agent-resource and uninstall commands are
+excluded so intentional removal is not reversed.
 
 ## Boundaries
 
@@ -34,8 +39,12 @@ exactly one configured shell command only for a real run.
 - Help, version, and CLI usage failures do not discover a manifest.
 - `source/flags.ts` no longer exists; RunX has no second token parser or manual
   execution router behind Citty.
-- `agents.ts` copies the embedded or packaged skill into the requested standard
-  or Claude-compatible skill location.
+- `agents.ts` owns explicit dual-tool actions plus idempotent, legacy-aware
+  automatic skill and instruction reconciliation.
+- `storage.ts` performs same-directory temporary writes and atomic replacement
+  for automatic resource maintenance.
+- Hidden update and agent-maintenance routes never appear in public help and
+  cannot recursively schedule themselves.
 - `self-management.ts` queries GitHub Releases and only replaces/removes a
   native executable, never a Bun development process.
 - Native builds register `embedded-resources.ts`, which includes the skill.

package/docs/decisions/decisions.xdocs.md

@@ -7,6 +7,7 @@ files:
   alpha-boundaries.md: Captures accepted alpha scope, safety, distribution, and compatibility decisions.
   citty-cli-migration.md: Defines the accepted full migration from handwritten parsing and routing to Citty.
   interactive-init-manifest.md: Defines interactive initialization, Semantic Versioning, the public group, and the scripts directory contract.
+  markdown-release-assets-and-version-scoped-notes.md: Defines .md agent release filenames, downloaded-resource validation, and exact-version idempotent GitHub Release notes.
   mirror-automatic-push.md: Defines automatic Mirror release pushes with a synchronized protected-main gate.
   npm-trusted-publishing.md: Defines the accepted npm OIDC publishing workflow and protected-branch patch-release trial.
   windows-self-upgrade.md: Defines synchronous Windows executable replacement, verification, rollback, and cleanup.
@@ -14,6 +15,7 @@ documents:
   alpha-boundaries.md: Decision record for RunX alpha boundaries.
   citty-cli-migration.md: Decision record for the complete Citty CLI parser and router migration.
   interactive-init-manifest.md: Accepted manifest and interactive initialization decision for runx init.
+  markdown-release-assets-and-version-scoped-notes.md: Accepted public asset filename, validation, and release-description policy.
   mirror-automatic-push.md: Accepted release-policy decision for Mirror push=true and protected delivery ordering.
   npm-trusted-publishing.md: Decision record for GitHub Actions npm trusted publishing and the first automated patch release.
   windows-self-upgrade.md: Accepted design for synchronous and recoverable Windows native self-upgrade.
@@ -25,6 +27,8 @@ keywords:
   - runx init
   - scripts directory
   - mirror push
+  - markdown release assets
+  - version-scoped release notes
   - windows self-upgrade
 flags: []
 status: stable

package/docs/decisions/markdown-release-assets-and-version-scoped-notes.md

@@ -0,0 +1,84 @@
+---
+name: RunX Markdown Release Assets And Version-Scoped Notes
+purpose: Preserve the accepted RunX GitHub Release filename and release-description policy.
+description: Records the project override requiring .md agent asset filenames and exact-version changelog sections for idempotent GitHub Release notes.
+created: 2026-07-19
+flags:
+  - accepted
+  - release-policy
+tags:
+  - decisions
+  - releases
+  - cli
+keywords:
+  - guiho-s-runx.md
+  - guiho-i-runx.md
+  - GitHub Release notes
+  - changelog extraction
+owner: runx-decisions
+---
+
+# RunX Markdown Release Assets And Version-Scoped Notes
+
+## Status
+
+Accepted by the developer on 2026-07-19.
+
+## Context
+
+The bundled RFC 0034 skill originally named the two Markdown release artifacts
+without extensions. That makes their content type less obvious and conflicts
+with the explicit RunX release contract chosen by the developer. The publish
+workflow also passed the complete changelog to GitHub, causing one release to
+describe unrelated versions.
+
+## Decision
+
+Every RunX GitHub Release contains exactly fourteen assets: twelve native
+binaries plus `guiho-s-runx.md` and `guiho-i-runx.md`.
+
+The `.md` suffixes are public filename requirements. Installers download those
+names, install the skill content as `SKILL.md`, and use the instruction asset
+content for managed instruction blocks.
+
+Release notes contain only the exact `## <version> - <date>` section from
+`CHANGELOG.md`, ending before the next `## ` heading. Publishing fails closed
+when the exact section is missing or empty. Rerunning a tag updates the existing
+release notes before replacing its assets.
+
+Downloaded agent artifacts are treated as untrusted release inputs. Installers
+reject empty payloads, Windows executable headers, NUL-containing binary data,
+invalid UTF-8, missing YAML frontmatter, and mismatched resource identities
+before writing any global skill or project instruction file.
+
+## Alternatives Considered
+
+- Extensionless agent assets: rejected because the developer explicitly
+  requires recognizable Markdown filenames.
+- Full-changelog release notes: rejected because they include unrelated release
+  history.
+- Creating notes only on first publish: rejected because reruns must repair
+  stale release descriptions idempotently.
+- Trusting the filename extension alone: rejected because a `.md` download can
+  still contain an executable or corrupted payload.
+
+## Consequences
+
+- RunX intentionally differs from the original extensionless RFC asset spelling.
+- All build, verification, workflow, installer, test, and public documentation
+  surfaces must use the `.md` filenames.
+- Every version tag requires an exact matching changelog heading before its
+  protected publish workflow can succeed.
+- Installer validation must complete before any downloaded agent resource is
+  copied or applied.
+
+## Reversal Or Revisit Conditions
+
+Revisit only through an explicit developer decision that changes the public
+release contract and migrates all consumers together.
+
+## References
+
+- [RFC migration plan](../plans/rfc-0034-cli-compliance-migration.md)
+- [RFC task specification](../todo/rfc-0034-cli-compliance-migration.md)
+- [RunX documentation](../../DOCS.md)

package/docs/plans/automatic-agent-maintenance.md

@@ -0,0 +1,120 @@
+---
+name: RunX Automatic Agent Maintenance Plan
+purpose: Define executable units for GitHub issue 11 automatic skill and AGENTS.md maintenance.
+description: Sequences atomic resource reconciliation, a hidden worker, startup integration, regression coverage, documentation, review, and validation.
+created: 2026-07-19
+flags:
+  - approved
+  - implementation-ready
+  - implemented
+tags:
+  - planning
+  - cli
+  - agents
+keywords:
+  - RunX
+  - issue 11
+  - background worker
+  - atomic writes
+  - AGENTS.md
+owner: runx-plans
+---
+
+# RunX Automatic Agent Maintenance Plan
+
+## Outcome
+
+Every ordinary RunX invocation schedules a hidden, non-blocking,
+failure-isolated worker that reconciles the bundled `guiho-s-runx` skill in
+both global tool locations and one compact managed block in the nearest
+applicable `AGENTS.md`. Current resources remain untouched, stale or legacy
+resources converge to bundled content, and foreground text, JSON, help,
+version, command execution, and exit behavior remain deterministic.
+
+## Authority
+
+- GitHub issue [#11](https://github.com/CGuiho/runx/issues/11) is the accepted
+  behavior requirement.
+- `guiho-a-0001-swe` coordinates execution.
+- `guiho-s-0034-cli-engineer`, `guiho-s-0023-plan-executor`,
+  `guiho-s-0015-bun`, `guiho-s-0019-typescript`, `guiho-s-0011-typebox`, and
+  `guiho-s-xdocs` govern implementation.
+- The approved RFC breaking boundary remains: the namespace is singular
+  `runx agent`; no plural compatibility alias will be restored.
+
+## Unit AM-01 - Atomic Reconciliation Primitives
+
+- Goal: reconcile only missing or stale agent resources without partial writes.
+- Expected files: `source/storage.ts`, `source/agents.ts`, colocated tests.
+- Actions:
+  1. Add same-directory temporary-file writes followed by atomic replacement.
+  2. Compare both global skill targets with the bundled skill before writing.
+  3. Find the nearest existing `AGENTS.md` from effective cwd; create one at
+     effective cwd only when no ancestor contains it.
+  4. Replace current or legacy RunX blocks without duplicating them.
+  5. Preserve user-authored content outside recognized markers.
+- Acceptance:
+  - Missing and stale resources are repaired.
+  - Current resources report no change and are not rewritten.
+  - Concurrent reconciliations converge to identical content.
+  - Failures do not leave a truncated destination.
+
+## Unit AM-02 - Hidden Worker Lifecycle
+
+- Goal: schedule maintenance without blocking or polluting foreground output.
+- Expected files: new `source/agent-maintenance.ts`, `source/cli.ts`, tests.
+- Dependencies: AM-01.
+- Actions:
+  1. Add one hidden exact worker route absent from public help/tree/docs.
+  2. Pass the Citty-decoded effective cwd to the detached worker.
+  3. Disable recursive scheduling in the worker process.
+  4. Ignore worker stdout/stderr and isolate spawn/worker failures.
+  5. Exclude explicit agent-resource and uninstall commands so explicit removal
+     is not immediately reversed.
+- Acceptance:
+  - Plain RunX and ordinary catalog commands schedule the worker.
+  - The foreground does not wait for reconciliation.
+  - Text and JSON output and exit codes remain unchanged.
+  - Hidden worker execution cannot recursively spawn itself.
+
+## Unit AM-03 - Acceptance Regressions
+
+- Goal: prove every issue criterion with temporary homes and projects.
+- Expected files: `source/agent-maintenance.spec.ts`, `source/cli.spec.ts`.
+- Dependencies: AM-01 and AM-02.
+- Tests:
+  - missing, current, and outdated skills in both global tool locations;
+  - nearest `AGENTS.md` insertion and stale/legacy block replacement;
+  - preservation of user-authored content;
+  - two concurrent reconciliations;
+  - worker spawn failure and maintenance failure isolation;
+  - plain invocation scheduling and effective `--cwd` routing;
+  - stable text/JSON output and hidden help tree.
+- Acceptance:
+  - The full suite exits cleanly with no real global mutation.
+
+## Unit AM-04 - Documentation, Review, And Validation
+
+- Goal: close durable state and provide issue-resolution evidence.
+- Dependencies: AM-03.
+- Actions:
+  1. Document automatic behavior and explicit-command boundaries.
+  2. Review implementation against every issue checkbox.
+  3. Run typecheck, tests, build, native smoke, prohibited-import scan, and
+     narrow XDocs checks.
+  4. Commit one file at a time, push main, comment factual evidence on issue
+     #11, and close only after GitHub contains the implementation.
+- Acceptance:
+  - No review finding remains.
+  - Pushed commit and validation evidence precede closure.
+
+## Release Boundary
+
+This externally observable capability requires a final Mirror `minor` plan
+after all open issues are resolved. Do not version or tag during this unit.
+
+## References
+
+- [Task specification](../todo/automatic-agent-maintenance.md)
+- [CLI architecture](../architecture/cli-architecture.md)
+- [RFC migration plan](./rfc-0034-cli-compliance-migration.md)

package/docs/plans/plans.xdocs.md

@@ -5,6 +5,7 @@ parent: runx-docs
 children: []
 files:
   alpha-implementation.md: Breaks the accepted alpha into implementation and validation units.
+  automatic-agent-maintenance.md: Implements non-blocking automatic global skill and nearest AGENTS.md reconciliation for issue 11.
   citty-cli-migration.md: Executes the full Citty command-tree migration, compatibility validation, protected delivery, and patch release.
   interactive-init-manifest.md: Sequences the SemVer manifest, public group, scripts directory, and interactive initializer delivery.
   mirror-automatic-push.md: Enables automatic Mirror release pushes with a synchronized protected-main safety gate.
@@ -14,6 +15,7 @@ files:
   upgrade-reliability-implementation.md: Sequences release discovery, streamed progress, transactional replacement, recovery, installers, and validation.
 documents:
   alpha-implementation.md: Plan used for the initial RunX implementation.
+  automatic-agent-maintenance.md: Approved automatic agent-maintenance implementation plan.
   citty-cli-migration.md: Active plan for replacing handwritten CLI parsing and routing with Citty and delivering its patch release.
   interactive-init-manifest.md: Approved implementation plan for the RunX interactive init manifest feature.
   mirror-automatic-push.md: Approved plan for configuring, validating, and merging Mirror push=true without applying another release.

package/docs/plans/rfc-0034-cli-compliance-migration.md

@@ -447,13 +447,17 @@ execution session rather than assuming it remains active from an earlier unit.
   4. Validate integrity and architecture.
   5. Transactionally install and verify the binary.
   6. Add the global binary directory to PATH when missing.
-  7. Download/extract `guiho-s-runx` into both global skill locations.
-  8. Download `guiho-i-runx`, discover instruction files, and reconcile their
+  7. Download `guiho-s-runx.md` and install it as `SKILL.md` in both global
+     skill locations.
+  8. Download `guiho-i-runx.md`, discover instruction files, and reconcile their
      managed blocks.
-  9. Log every action and final `runx --version` verification.
+  9. Reject empty, executable, binary, invalid UTF-8, missing-frontmatter, or
+     wrong-identity agent assets before any skill or instruction write.
+  10. Log every action and final `runx --version` verification.
 - Acceptance:
   - Isolated Windows and POSIX installer tests cover success, fallback,
-    corruption, rollback, PATH, both skills, instructions, and progress.
+    binary Markdown rejection, rollback, PATH, both skills, instructions, and
+    progress.
 
 ### Unit RX-13 - Replace The Npm Launcher With A Node-Compatible Bootstrap
 
@@ -494,18 +498,23 @@ execution session rather than assuming it remains active from an earlier unit.
   - `runx-windows-x64-baseline.exe`
   - `runx-windows-x64-modern.exe`
 - Agent asset names:
-  - `guiho-s-runx`
-  - `guiho-i-runx`
+  - `guiho-s-runx.md`
+  - `guiho-i-runx.md`
 - Actions:
   1. Replace every `macos` name and selector with `darwin`.
   2. Use Bun APIs in the binary builder rather than Node filesystem/path
      imports.
   3. Package the skill directory and instruction/prompt artifact reproducibly.
-  4. Upload only the fourteen expected assets.
-  5. Make CI fail for missing, duplicate, extra, wrongly suffixed, or legacy
+  4. Treat the `.md` suffixes as part of both public agent-asset filenames.
+  5. Extract only the exact version heading and body from `CHANGELOG.md` for
+     GitHub Release notes; fail closed if it is missing and update existing
+     releases idempotently.
+  6. Upload only the fourteen expected assets.
+  7. Make CI fail for missing, duplicate, extra, wrongly suffixed, or legacy
      assets.
 - Acceptance:
   - Automated verification observes exactly fourteen unique names.
+  - Release notes exclude changelog frontmatter and every older/newer version.
 
 ### Unit RX-15 - Align Documentation, Skill, TODO, And XDocs
 

package/docs/plans/upgrade-reliability-implementation.md

@@ -5,7 +5,7 @@ description: Implementation plan for release discovery, progress reporting, tran
 created: 2026-07-15
 flags:
   - approved
-  - in-progress
+  - implemented
 tags:
   - plans
   - cli

package/docs/reviews/implementation/automatic-agent-maintenance-review.md

@@ -0,0 +1,63 @@
+---
+name: RunX Automatic Agent Maintenance Implementation Review
+purpose: Review the delivered GitHub issue 11 behavior against every accepted criterion.
+description: Findings-first review of atomic reconciliation, nearest instructions, worker isolation, tests, docs, and release boundaries.
+created: 2026-07-19
+flags:
+  - accepted
+tags:
+  - review
+  - cli
+  - agents
+keywords:
+  - RunX
+  - issue 11
+  - implementation review
+owner: runx-implementation-reviews
+---
+
+# RunX Automatic Agent Maintenance Implementation Review
+
+## Verdict
+
+Accepted.
+
+## Findings
+
+No blocker, high, medium, or low finding remains.
+
+Review identified one boundary worth making explicit: automatic maintenance
+must never reverse a deliberate `runx agent ... remove|uninstall` or
+`runx uninstall` action. The final CLI test executes both explicit agent
+removals with maintenance enabled, waits beyond worker startup, and proves the
+resources remain absent.
+
+## Acceptance Criteria Check
+
+- Missing and stale skills in both global locations: accepted.
+- Current skills are compared and not rewritten: accepted.
+- Nearest ancestor `AGENTS.md` selection and cwd fallback: accepted.
+- Current and legacy block convergence with user-content preservation:
+  accepted.
+- Same-directory temporary writes and failed-write cleanup: accepted.
+- Concurrent-worker convergence: accepted.
+- Hidden exact worker route and TypeBox input decoding: accepted.
+- Detached ignored streams, recursion prevention, and spawn isolation:
+  accepted.
+- Citty-decoded effective cwd: accepted.
+- Text, JSON, help, version, and exit behavior stability: accepted.
+- Explicit agent-resource and executable removal boundaries: accepted.
+- Documentation, XDocs, native builds, and exact assets: accepted.
+
+## Residual Risk
+
+The worker intentionally reports no foreground failure. Filesystem permission
+errors therefore remain silent and are retried by a later ordinary invocation.
+This is the required failure-isolation contract, not an unresolved finding.
+
+## References
+
+- [Implementation plan](../../plans/automatic-agent-maintenance.md)
+- [Implementation notes](../../todo/automatic-agent-maintenance-implementation.md)
+- [Validation](../../validation/automatic-agent-maintenance.md)
+- [GitHub issue #11](https://github.com/CGuiho/runx/issues/11)

package/docs/reviews/implementation/bash-installer-review.md

@@ -0,0 +1,42 @@
+---
+name: RunX Bash Installer Implementation Review
+purpose: Review the GitHub issue 15 Bash conversion against all invocation and test surfaces.
+description: Findings-first review of shebang, strict mode, recovery commands, docs, source-only piping, exact versions, and executable verification.
+created: 2026-07-19
+flags:
+  - accepted
+tags:
+  - review
+  - installer
+  - bash
+keywords:
+  - RunX
+  - issue 15
+  - install.sh
+owner: runx-implementation-reviews
+---
+
+# RunX Bash Installer Implementation Review
+
+## Verdict
+
+Accepted.
+
+## Findings
+
+The current installer no longer contained the historical invalid
+`set -o pipefail` under `sh`, but the public shebang, README command, and
+recovery generator still selected `sh`. That did not satisfy the issue title.
+
+All canonical surfaces now select Bash. Strict mode is enabled, unset `SHELL`
+is handled safely, and a real Bash runtime validates syntax, piped source-only
+startup, exact stable/prerelease normalization, and executable version
+verification.
+
+No blocker, high, medium, or low finding remains.
+
+## References
+
+- [Task specification](../../todo/bash-installer.md)
+- [Validation](../../validation/bash-installer.md)
+- [GitHub issue #15](https://github.com/CGuiho/runx/issues/15)

package/docs/reviews/implementation/implementation.xdocs.md

@@ -4,15 +4,25 @@ description: Delivery-readiness reviews of implemented RunX plans and behavior c
 parent: runx-reviews
 children: []
 files:
+  bash-installer-review.md: Accepts the canonical Bash shebang, strict mode, recovery invocation, and executable shell tests for GitHub issue 15.
   citty-cli-migration-review.md: Reviews the implemented Citty command tree, compatibility adapter, tests, documentation, packaging, and release readiness.
   interactive-init-manifest-review.md: Reviews the implemented RunX initializer, strict manifest contract, tests, documentation, and delivery readiness.
   windows-self-upgrade-review.md: Reviews synchronous Windows replacement, rollback, cleanup, tests, CI coverage, and release readiness.
   rfc-0034-cli-compliance-migration-review.md: Accepts the RFC 0034 migration after independent upgrade-routing, cached-notice, prompt-output, asset, and release-readiness corrections.
+  automatic-agent-maintenance-review.md: Accepts atomic global skill and nearest AGENTS.md reconciliation, detached failure isolation, command boundaries, and regression evidence.
+  upgrade-reliability-issue-12-review.md: Accepts synchronous verified replacement and the corrected complete, single-document release listing for GitHub issue 12.
+  upgrade-reliability-issue-13-review.md: Accepts exact recovery across all outcomes and executable direct-installer version verification for GitHub issue 13.
+  unicode-help-tree-review.md: Accepts the Unicode nested and aligned help tree plus explicit legacy ASCII regression coverage for GitHub issue 17.
 documents:
+  bash-installer-review.md: Accepted implementation review for the RunX Bash installer.
   citty-cli-migration-review.md: Accepted implementation review for the full Citty CLI migration.
   interactive-init-manifest-review.md: Accepted implementation review for the RunX interactive init manifest feature.
   windows-self-upgrade-review.md: Accepted implementation review for the Windows native self-upgrade fix.
   rfc-0034-cli-compliance-migration-review.md: Accepted implementation and independent correction review for RX-01 through RX-16.
+  automatic-agent-maintenance-review.md: Accepted implementation review for GitHub issue 11 automatic agent maintenance.
+  upgrade-reliability-issue-12-review.md: Accepted implementation review for GitHub issue 12 upgrade reliability.
+  upgrade-reliability-issue-13-review.md: Accepted implementation review for GitHub issue 13 recovery reliability.
+  unicode-help-tree-review.md: Accepted implementation review for the RunX Unicode help tree.
 tags:
   - reviews
   - implementation

package/docs/reviews/implementation/rfc-0034-cli-compliance-migration-review.md

@@ -51,8 +51,11 @@ cover each path.
 - Output/exit codes and delegated exit preservation: accepted.
 - Upgrade selection, catalog, replacement, rollback, and reconciliation:
   accepted.
-- Direct installers and Node-only npm bootstrap: accepted.
-- Twelve native binaries plus two named agent assets: accepted.
+- Direct installers, including downloaded Markdown identity/binary validation,
+  and Node-only npm bootstrap: accepted.
+- Twelve native binaries plus `guiho-s-runx.md` and `guiho-i-runx.md`: accepted.
+- Exact-version GitHub Release note extraction and idempotent note refresh:
+  accepted.
 - Docs, TODO, xdocs, tests, and build evidence: accepted.
 
 ## Residual Risk

package/docs/reviews/implementation/unicode-help-tree-review.md

@@ -0,0 +1,41 @@
+---
+name: RunX Unicode Help Tree Implementation Review
+purpose: Review current help rendering against GitHub issue 17.
+description: Findings-first review of Unicode branches, nesting, alignment, descriptions, depth, hidden routes, and regression coverage.
+created: 2026-07-19
+flags:
+  - accepted
+tags:
+  - review
+  - cli
+  - help
+keywords:
+  - RunX
+  - issue 17
+  - help tree
+owner: runx-implementation-reviews
+---
+
+# RunX Unicode Help Tree Implementation Review
+
+## Verdict
+
+Accepted.
+
+## Findings
+
+The current Citty-based renderer already implemented the requested visual
+behavior. The remaining gap was explicit regression coverage: the broad help
+test checked only the header and one depth-limited branch.
+
+The strengthened CLI test now asserts both branch endings, a nested vertical
+guide, description alignment, and absence of the legacy ASCII `|-` form. No
+renderer change was required.
+
+No blocker, high, medium, or low finding remains.
+
+## References
+
+- [Task specification](../../todo/unicode-help-tree.md)
+- [Validation](../../validation/unicode-help-tree.md)
+- [GitHub issue #17](https://github.com/CGuiho/runx/issues/17)

package/docs/reviews/implementation/upgrade-reliability-issue-12-review.md

@@ -0,0 +1,62 @@
+---
+name: RunX Upgrade Reliability Issue 12 Implementation Review
+purpose: Review current-main self-upgrade and complete release listing behavior against GitHub issue 12.
+description: Findings-first review of synchronous replacement, rollback, output ordering, complete catalog routing, JSON, tests, and delivery readiness.
+created: 2026-07-19
+flags:
+  - accepted
+tags:
+  - review
+  - cli
+  - reliability
+keywords:
+  - RunX
+  - issue 12
+  - upgrade list
+  - transactional replacement
+owner: runx-implementation-reviews
+---
+
+# RunX Upgrade Reliability Issue 12 Implementation Review
+
+## Verdict
+
+Accepted after correction.
+
+## Findings
+
+Two public-list findings were corrected before acceptance:
+
+- the default view truncated the complete release catalog to twenty entries and
+  hid prereleases unless `--pre-releases` was supplied;
+- Citty executed the selected `upgrade list` leaf and then also executed the
+  parent `upgrade` action, appending a second JSON document and failure result.
+
+The default list now returns every normalized published release, including
+labeled prereleases. Pagination occurs only when the user explicitly supplies
+`--page` or `--per-page`. The parent action checks the resolved Citty command
+identity and does not execute after `upgrade list` or `upgrade check`.
+
+No blocker, high, medium, or low finding remains.
+
+## Acceptance Criteria Check
+
+- Immediate canonical replacement before success: accepted.
+- Exact canonical `--version` verification: accepted.
+- Backup rollback on replacement or verification failure: accepted.
+- Mapped Windows executable replacement and deferred cleanup only: accepted.
+- Visible plan and ordered download/validate/replace/verify phases: accepted.
+- Every GitHub release page, SemVer order, channels, dates, current/latest, and
+  missing compatible assets: accepted.
+- Complete prerelease-inclusive default list: accepted after correction.
+- One parseable JSON document with equivalent metadata: accepted after
+  correction.
+- Windows swap, permission/rename failure, rollback, version mismatch,
+  pagination, labels, and missing-asset regressions: accepted.
+
+## References
+
+- [Approved design](../../superpowers/specs/2026-07-15-upgrade-reliability-design.md)
+- [Implementation plan](../../plans/upgrade-reliability-implementation.md)
+- [Validation](../../validation/upgrade-reliability-issue-12.md)
+- [GitHub issue #12](https://github.com/CGuiho/runx/issues/12)

package/docs/reviews/implementation/upgrade-reliability-issue-13-review.md

@@ -0,0 +1,63 @@
+---
+name: RunX Upgrade Reliability Issue 13 Implementation Review
+purpose: Review exact-version recovery and installer behavior against GitHub issue 13.
+description: Findings-first review of recovery coverage, target pinning, separate stop commands, installer version verification, JSON, and delivery readiness.
+created: 2026-07-19
+flags:
+  - accepted
+tags:
+  - review
+  - cli
+  - reliability
+keywords:
+  - RunX
+  - issue 13
+  - recovery install
+  - exact version
+owner: runx-implementation-reviews
+---
+
+# RunX Upgrade Reliability Issue 13 Implementation Review
+
+## Verdict
+
+Accepted.
+
+## Findings
+
+No blocker, high, medium, or low implementation finding remains.
+
+The implementation already generated recovery from the resolved plan before
+mutation and retained it through failure envelopes. This audit strengthened
+the release gate with an explicit matrix for all five terminal outcomes and an
+executable PowerShell installer test for stable/prerelease normalization,
+successful `--version` verification, and mismatch rejection.
+
+## Acceptance Criteria Check
+
+- Recovery after success, failure, already current, dry run, and rollback:
+  accepted.
+- Exact stable and prerelease target preservation: accepted.
+- Copyable installer command generated from supported installer flags:
+  accepted.
+- Separate Windows and POSIX process-stop commands: accepted.
+- Fallback-current repair when discovery cannot resolve a target: accepted.
+- Text ordering and JSON recovery parity: accepted.
+- Direct installer version arguments, canonical verification, and nonzero
+  mismatch behavior: accepted.
+- Download, replacement, verification, and already-current regressions:
+  accepted.
+
+## Platform Note
+
+The current Windows gate executes PowerShell normalization and version
+verification directly. Git for Windows Bash executes the Linux/macOS installer
+syntax, piped startup, exact-version normalization, and executable verification
+locally; Ubuntu CI remains the native Linux gate.
+
+## References
+
+- [Approved design](../../superpowers/specs/2026-07-15-upgrade-reliability-design.md)
+- [Implementation plan](../../plans/upgrade-reliability-implementation.md)
+- [Validation](../../validation/upgrade-reliability-issue-13.md)
+- [GitHub issue #13](https://github.com/CGuiho/runx/issues/13)