@guiho/runx 0.2.7 → 0.4.0

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

@@ -7,10 +7,12 @@ files:
   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 complete RFC 0034 runtime, CLI, agent, installer, packaging, documentation, and release migration.
 documents:
   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 review for RX-01 through RX-16.
 tags:
   - reviews
   - implementation

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

@@ -0,0 +1,59 @@
+---
+name: RunX RFC 0034 CLI Compliance Migration Implementation Review
+purpose: Review the delivered migration against all RX units and RFC completion gates.
+description: Findings-first delivery review of runtime, CLI, agents, upgrades, installers, packaging, tests, docs, and release assets.
+created: 2026-07-18
+flags:
+  - accepted
+tags:
+  - review
+  - cli
+keywords:
+  - RFC 0034
+  - implementation review
+  - RunX
+owner: runx-implementation-reviews
+---
+
+# RunX RFC 0034 CLI Compliance Migration Implementation Review
+
+## Verdict
+
+Accepted.
+
+## Findings
+
+No blocker, high, medium, or low finding remains.
+
+The review found and corrected three implementation-stage issues before
+acceptance: nested Citty execution initially allowed the root banner to pollute
+JSON output, directory existence checking initially rejected valid command
+working directories, and legacy Windows cleanup tests waited indefinitely.
+Focused tests now cover each corrected behavior.
+
+## Acceptance Criteria Check
+
+- Mandatory Bun, TypeScript, Citty, and TypeBox stack: accepted.
+- Core prohibited-import scan: accepted.
+- YAML precedence and configuration exit behavior: accepted.
+- Exact startup banner and detached cache worker: accepted.
+- Complete help modes at every public scope: accepted.
+- Singular agent namespace and idempotent resources: accepted.
+- 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.
+- Docs, TODO, xdocs, tests, and build evidence: accepted.
+
+## Residual Risk
+
+Publishing and GitHub Release creation are intentionally outside this delivery.
+The workflows are validated locally and will execute only on a protected
+Mirror-managed version tag.
+
+## References
+
+- [Implementation plan](../../plans/rfc-0034-cli-compliance-migration.md)
+- [Implementation notes](../../todo/rfc-0034-cli-compliance-migration-implementation.md)
+- [Validation report](../../validation/rfc-0034-cli-compliance-migration.md)

package/docs/reviews/plans/plans.xdocs.md

@@ -8,13 +8,17 @@ files:
   interactive-init-manifest-review.md: Reviews the RunX init manifest schema, terminal workflow, tests, XDocs, and pull-request delivery.
   mirror-automatic-push-review.md: Reviews synchronized-main safeguards, read-only validation, protected delivery, and release side effects.
   npm-trusted-publishing-release-review.md: Reviews sequencing, acceptance criteria, safety gates, and validation for the RunX 0.2.1 trusted-publishing plan.
+  rfc-0034-cli-compliance-migration-review.md: Reviews the full breaking RunX RFC 0034 migration for sequencing, command/agent coverage, distribution, validation, and approval gates.
   windows-self-upgrade-review.md: Reviews synchronous replacement, rollback, regression coverage, issue closure, and patch delivery.
+  upgrade-reliability-implementation-review.md: Reviews execution readiness for complete release discovery, transactional upgrades, recovery, installers, and validation.
 documents:
   citty-cli-migration-review.md: Ready-for-execution review of the full Citty CLI migration plan.
   interactive-init-manifest-review.md: Ready-for-execution review of the RunX interactive init manifest plan.
   mirror-automatic-push-review.md: Ready-for-execution review of the Mirror automatic-push configuration plan.
   npm-trusted-publishing-release-review.md: Ready-for-execution review of the npm trusted-publishing release plan.
+  rfc-0034-cli-compliance-migration-review.md: Ready-for-execution review of the complete RFC 0034 migration plan.
   windows-self-upgrade-review.md: Ready-for-execution review of the Windows native self-upgrade fix plan.
+  upgrade-reliability-implementation-review.md: Ready-for-execution review for GitHub issues 12 and 13.
 tags:
   - reviews
   - plans
@@ -26,6 +30,8 @@ keywords:
   - scripts directory
   - mirror push
   - trusted publishing
+  - RFC 0034
+  - cli compliance
   - windows self-upgrade
 flags: []
 status: stable

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

@@ -0,0 +1,80 @@
+---
+name: RunX RFC 0034 CLI Compliance Migration Plan Review
+purpose: Verify that the RunX RFC 0034 migration plan is sequenced, explicit, testable, and safe to execute.
+description: Reviews the breaking migration plan against the CLI contract, current RunX architecture, TODO tracking, documentation duties, and release approval gates.
+created: 2026-07-18
+flags:
+  - approved
+  - ready-for-execution
+tags:
+  - review
+  - plan
+  - cli
+keywords:
+  - runx
+  - RFC 0034
+  - plan readiness
+  - breaking migration
+owner: runx-plan-reviews
+---
+
+# RunX RFC 0034 CLI Compliance Migration Plan Review
+
+## Verdict
+
+Ready for execution.
+
+## Findings
+
+No blocker or high-severity finding remains.
+
+- Medium, resolved: Earlier RunX requirements and decisions require `runx r`,
+  root selector shorthand, `--file`, upward discovery, and a home page. The new
+  plan records the developer-approved breaking boundary and requires conflicting
+  durable documents to be superseded.
+- Medium, resolved: Current agent code only installs/updates one selected tool,
+  writes AGENTS only, uses non-RFC markers, and has no prompt catalog. RX-09
+  explicitly covers both skill paths, all actions, instruction resolution,
+  idempotency, prompts, embedding, and isolated tests.
+- Medium, resolved: Current release work builds twelve `macos` binaries but no
+  agent assets. RX-12 through RX-14 sequence installer, bootstrap, naming,
+  packaging, workflow, and exact-set verification.
+- Medium, resolved: The npm launcher requirement could conflict with Bun-only
+  core source. RX-13 names `scripts/runx-bin.mjs` as the isolated Node exception.
+- Low, resolved: Creating plans/specs/reviews requires xdocs companion metadata.
+  The affected descriptors are included in this planning unit.
+
+## Sequencing Risks
+
+The Bun-only source foundation and TypeBox boundaries correctly precede
+configuration, startup, agent, and upgrade behavior. The command tree precedes
+generated help. Agent resources precede installers and release packaging.
+Documentation follows stable behavior and precedes final validation.
+
+## Acceptance Criteria Review
+
+Every unit states a goal, dependencies, files or modules, actions, acceptance
+signals, and stop/approval conditions where risk exists. The validation unit
+covers source, CLI, native binaries, npm bootstrap, installers, prohibited
+imports, fourteen assets, xdocs, review, and release boundaries.
+
+## TODO Alignment
+
+RunX TODO task `1` links the task specification and executable plan. It remains
+`todo` and cannot become completed until validation evidence proves every RFC
+completion-gate item.
+
+## First Executable Unit
+
+RX-01: record baseline commands, checks, prohibited imports, agent behavior, and
+release assets in an understood worktree.
+
+## Recommended Next Skill
+
+Use `guiho-s-0023-plan-executor` with `guiho-s-0034-cli-engineer`.
+
+## References
+
+- [Migration plan](../../plans/rfc-0034-cli-compliance-migration.md)
+- [Task specification](../../todo/rfc-0034-cli-compliance-migration.md)
+- [TODO.md](../../../TODO.md)

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

@@ -0,0 +1,65 @@
+---
+name: RunX Upgrade Reliability Implementation Plan Review
+purpose: Establish whether the upgrade reliability plan is safe and specific enough for uninterrupted execution.
+description: Reviews traceability, sequencing, failure handling, tests, documentation, and release boundaries for GitHub issues 12 and 13.
+created: 2026-07-15
+flags:
+  - approved
+tags:
+  - reviews
+  - plans
+  - reliability
+keywords:
+  - runx upgrade
+  - plan review
+  - issue 12
+  - issue 13
+owner: runx-plan-reviews
+---
+
+# RunX Upgrade Reliability Implementation Plan Review
+
+## Verdict
+
+Ready for execution.
+
+## Findings
+
+No blocker or high-severity findings remain.
+
+- Medium, resolved in the plan: installer validation could otherwise be deferred as a platform concern. Unit 4 now requires contract tests and records unavailable live platform checks without weakening verification semantics.
+- Medium, resolved in the plan: CLI recovery output could be lost at the generic error boundary. Units 2 and 3 explicitly require command-specific failure envelopes, concise stderr, stdout recovery, and a single JSON document.
+- Low, accepted: the release catalog may expose invalid SemVer tags. The approved design deliberately keeps them after valid SemVer entries with channel `other`, preserving complete publication visibility.
+
+## Sequencing Risks
+
+The sequence is correct: release normalization and recovery are prerequisites for the planner, reporter, CLI, and installers. Documentation follows implemented behavior, and full validation is last. Each unit is bounded to one repository and names its affected modules.
+
+## Acceptance Criteria Coverage
+
+- Plan before download and ordered phases: Units 2 and 3.
+- Immediate canonical replacement, exact verification, rollback, and deferred backup cleanup only: Unit 2.
+- Complete paginated SemVer catalog with channel/date/current/latest/asset metadata: Units 1 and 3.
+- Recovery and stop commands after every outcome: Units 1-3.
+- Exact-version direct installers with rollback: Unit 4.
+- Help, public docs, skill, XDocs, and release gates: Units 5 and 6.
+
+No database, authentication, permission, or persistent cache behavior exists in scope. The plan explicitly marks the upgrade cache phase skipped instead of inventing storage.
+
+## TODO and XDocs Alignment
+
+Task 2 in `TODO.md` links the approved design, executable plan, and GitHub issues. The plan and task spec are registered in their owning XDocs descriptors. Unit 5 requires affected source, devops, root-doc, and skill metadata to be synchronized before completion.
+
+## Stop Conditions
+
+The plan correctly stops on release naming contradictions, Citty bypass, architecture changes, destructive operations, or publication/version mutations. The user has already approved uninterrupted implementation within these boundaries.
+
+## First Executable Unit
+
+Unit 1: implement and test the release catalog and recovery contract.
+
+## References
+
+- [Implementation plan](../../plans/upgrade-reliability-implementation.md)
+- [Approved design](../../superpowers/specs/2026-07-15-upgrade-reliability-design.md)
+- [Task specification](../../todo/upgrade-reliability.md)