@guiho/runx 0.2.6 → 0.4.0

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

@@ -5,16 +5,22 @@ parent: runx-reviews
 children: []
 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
 keywords:
   - runx
   - citty
+  - runx init
+  - scripts directory
   - implementation review
   - windows self-upgrade
 flags: []

package/docs/reviews/implementation/interactive-init-manifest-review.md

@@ -0,0 +1,69 @@
+---
+name: RunX Interactive Init Manifest Implementation Review
+purpose: Assess the delivered RunX initializer and manifest contract against the accepted decision and plan.
+description: Reviews Citty routing, strict SemVer and group validation, terminal safety, tests, documentation, and delivery boundaries.
+created: 2026-07-14
+flags:
+  - accepted
+tags:
+  - reviews
+  - implementation
+  - cli
+keywords:
+  - runx init
+  - runx.yaml
+  - semantic versioning
+  - public group
+  - scripts directory
+owner: runx-implementation-reviews
+---
+
+# RunX Interactive Init Manifest Implementation Review
+
+## Verdict
+
+Accepted. No blocking, high, medium, or low findings remain.
+
+## Acceptance Criteria Check
+
+- `runx init` is a first-class Citty command, appears in the home/help tree,
+  and is reserved from selector shorthand.
+- The manifest accepts Semantic Versioning `1.x` strings, requires an in-root
+  `scripts.directory` and `public` group, and permits `commands: []` while
+  retaining strict command-group validation.
+- The initializer uses a guided terminal adapter with project and scripts
+  prompts, an exact YAML preview, confirmation, overwrite confirmation, and
+  cancellation behavior. It writes only `runx.yaml`, not `scripts/`.
+- Writes use a same-directory temporary file, validate the temporary manifest,
+  then rename it into place. No configured command is read for execution or
+  spawned by this path.
+- `--file` and `--format json` fail explicitly for `init`; `--cwd` selects the
+  target directory.
+- The README, canonical documentation, source XDocs metadata, and package
+  metadata align with the implementation. The bundled agent skill is unchanged
+  by design; the separate agent-integration follow-up remains issue #11.
+
+## Verification Evidence
+
+- `bun run typecheck` passed.
+- `bun test` passed: 22 tests and 180 assertions, including initialization,
+  cancellation, overwrite, empty-catalog list/check, and non-interactive CLI
+  coverage.
+- `bun run build` and `bun run binary` passed.
+- The compiled `bin/runx.exe --help-tree` includes `init`.
+- XDocs strict metadata checks for `source`, plans, and plan reviews passed;
+  the XDocs tree is intact.
+
+## Residual Risk
+
+The automated environment has no interactive TTY, so the live terminal frame
+was exercised through the injected prompt contract rather than a human session.
+The native binary build and its command-tree smoke check confirm that the
+initializer is included in the compiled executable.
+
+## References
+
+- [Decision](../../decisions/interactive-init-manifest.md)
+- [Plan](../../plans/interactive-init-manifest.md)
+- [Plan Review](../plans/interactive-init-manifest-review.md)
+- GitHub issues [#10](https://github.com/CGuiho/runx/issues/10) and [#11](https://github.com/CGuiho/runx/issues/11)

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/interactive-init-manifest-review.md

@@ -0,0 +1,82 @@
+---
+name: RunX Interactive Init Manifest Plan Review
+purpose: Verify that the interactive-init implementation plan is executable, safe, and traceable.
+description: Reviews manifest constraints, terminal workflow boundaries, test coverage, XDocs work, and pull-request delivery for runx init.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - reviews
+  - plans
+  - cli
+keywords:
+  - runx init
+  - runx.yaml
+  - semantic versioning
+  - public group
+  - scripts directory
+owner: runx-plan-reviews
+---
+
+# RunX Interactive Init Manifest Plan Review
+
+## Verdict
+
+Ready for execution.
+
+## Findings
+
+No blocker, high, medium, or low findings remain.
+
+The plan is traceable to the accepted interactive-init decision, the existing
+command-catalog requirement, and the Citty CLI architecture. The only review
+finding was resolved in the plan: `runx init` is an interactive terminal
+workflow, so `--format json` and `--file` must fail clearly rather than create
+ambiguous output or target files.
+
+## Sequencing and Safety
+
+- Manifest schema changes precede the initializer, so generated YAML is
+  validated by the same strict contract that later commands use.
+- The initializer is isolated from the executor and is explicitly prohibited
+  from spawning configured manifest commands.
+- The prompt boundary is injectable for tests; an interactive terminal is
+  required for the real user interface.
+- Existing-file confirmation, cancellation, and atomic writes prevent silent
+  replacement and partial manifests.
+- The `scripts` directory is configured but not created until a real script is
+  added, matching the accepted file-only initialization boundary.
+- Manifest evolution is constrained to supported SemVer major `1`; no legacy
+  numeric compatibility or migration policy is hidden in the implementation.
+
+## Coverage Review
+
+- Tests cover SemVer, public-group, scripts-directory, empty-catalog, command
+  group-reference, creation, cancellation, overwrite, non-interactive, and
+  unsupported-option behavior.
+- The full Bun typecheck, test, library build, local native compilation, XDocs
+  subtree validation, and diff hygiene are named.
+- Native compilation of the terminal prompt dependency is an explicit stop
+  condition.
+- No API, database, authentication, authorization, cache, cloud, secret,
+  deployment, release, tag, or package-publication work is in scope.
+
+## Documentation and TODO Alignment
+
+The plan updates public CLI documentation and the affected XDocs descriptors.
+The bundled RunX agent skill is deliberately deferred to the separate
+agent-integration feature tracked in issue #11, as directed by the project
+owner. The work is one focused package session, so no additional long-running
+TODO entry is required.
+
+## First Executable Unit
+
+Update `source/manifest.ts` and its tests/fixtures to establish the SemVer,
+scripts-directory, mandatory-public-group, and empty-catalog contract.
+
+## References
+
+- [Plan](../../plans/interactive-init-manifest.md)
+- [Decision](../../decisions/interactive-init-manifest.md)
+- [Requirements](../../requirements/alpha-command-catalog.md)
+- [CLI Architecture](../../architecture/cli-architecture.md)

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

@@ -5,14 +5,20 @@ parent: runx-reviews
 children: []
 files:
   citty-cli-migration-review.md: Reviews completeness, compatibility, safety invariants, native packaging, and release sequencing for the Citty migration.
+  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
@@ -20,8 +26,12 @@ keywords:
   - runx
   - plan review
   - citty
+  - runx init
+  - 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)