@guiho/runx 0.4.1 → 0.5.2

package/docs/todo/bash-installer.md

@@ -0,0 +1,45 @@
+---
+name: Use Bash For The RunX Installer
+purpose: Track the canonical shell correction requested by GitHub issue 15.
+description: Records Bash shebang, strict mode, documented invocation, recovery generation, executable tests, and delivery evidence.
+created: 2026-07-19
+flags:
+  - completed
+tags:
+  - todo
+  - installer
+  - bash
+keywords:
+  - RunX
+  - issue 15
+  - install.sh
+  - pipefail
+owner: runx-todo
+---
+
+# Use Bash For The RunX Installer
+
+## Todo Index
+
+- Task: `4. Use Bash For The RunX Installer`
+- Status: completed
+- Index: [TODO.md](../../TODO.md)
+- External: [CGuiho/runx issue #15](https://github.com/CGuiho/runx/issues/15)
+
+## Outcome
+
+RunX declares and invokes the Linux/macOS installer as Bash everywhere. The
+installer uses Bash strict mode and passes syntax, piped startup, exact-version,
+and executable-version checks under a real Bash runtime.
+
+## Completion Signals
+
+- No canonical installer or recovery command pipes `install.sh` to `sh`.
+- The script starts with `#!/usr/bin/env bash` and `set -euo pipefail`.
+- Shell-profile detection remains safe when `SHELL` is unset.
+- Git Bash and Ubuntu-compatible tests exercise the script, not only its text.
+
+## References
+
+- [Implementation review](../reviews/implementation/bash-installer-review.md)
+- [Validation](../validation/bash-installer.md)

package/docs/todo/linux-installer-latest-release.md

@@ -0,0 +1,47 @@
+---
+name: Resolve The Latest RunX Bash Install
+purpose: Track the Linux and macOS latest-release installer correction requested by GitHub issue 20.
+description: Defines stable latest-download resolution, exact version behavior, installer safeguards, regression coverage, and public verification.
+created: 2026-07-20
+flags:
+  - testing
+owner: runx-todo
+tags:
+  - installer
+  - linux
+  - github
+keywords:
+  - issue 20
+  - latest release
+  - install.sh
+---
+
+# Resolve The Latest RunX Bash Install
+
+## Outcome
+
+The Bash installer installs the latest stable RunX release on Linux and macOS
+without parsing a redirected release tag whose package name contains a slash.
+
+## External Tracker
+
+- [CGuiho/runx#20](https://github.com/CGuiho/runx/issues/20)
+
+## Acceptance Signals
+
+- `latest` assets resolve through GitHub's stable
+  `releases/latest/download/<asset>` endpoint.
+- Exact stable and prerelease versions continue to use encoded RunX tags.
+- Binary, skill, and instruction assets use the same release selector.
+- Bash syntax, piped startup, exact-version, and executable-verification tests
+  pass.
+- The public installer succeeds against the released patch before issue
+  closure.
+
+## Watch-Outs
+
+- Do not recover a latest tag from the final redirect URL segment. The RunX tag
+  contains `@guiho/runx@...`; the slash can become a path separator and discard
+  the package scope.
+- Preserve transactional replacement, Markdown validation, PATH setup, dual
+  skill installation, and final executable verification.

package/docs/todo/platform-aware-startup-greeting.md

@@ -0,0 +1,41 @@
+---
+name: Use The Runtime Platform In The RunX Greeting
+purpose: Track the platform-aware no-argument greeting requested by GitHub issue 21.
+description: Defines Windows, Linux, and macOS greeting labels, output ordering, regression coverage, and public verification.
+created: 2026-07-20
+flags:
+  - testing
+owner: runx-todo
+tags:
+  - cli
+  - startup
+keywords:
+  - issue 21
+  - operating system
+  - greeting
+---
+
+# Use The Runtime Platform In The RunX Greeting
+
+## Outcome
+
+`runx` with no arguments names the operating system it is actually running on:
+Windows, Linux, or macOS.
+
+## External Tracker
+
+- [CGuiho/runx#21](https://github.com/CGuiho/runx/issues/21)
+
+## Acceptance Signals
+
+- Windows prints `Hello Windows - runx v<version>`.
+- Linux prints `Hello Linux - runx v<version>`.
+- macOS prints `Hello macOS - runx v<version>`.
+- Cached update notices remain before the greeting.
+- Help, version, command routing, output channels, and exit codes are unchanged.
+- Deterministic tests cover all three supported platform labels.
+
+## Contract Note
+
+This issue intentionally replaces the historical RFC 0034 literal-Windows
+banner. The developer explicitly approved the platform-aware behavior.

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

@@ -26,6 +26,11 @@ cache and release boundaries, complete Developer Context help, the singular
 agent namespace, transactional upgrades, complete installers, a Node-compatible
 npm bootstrap, and the exact fourteen release assets.
 
+The final release contract intentionally overrides the original RFC asset
+spelling: the two public Markdown artifacts are `guiho-s-runx.md` and
+`guiho-i-runx.md`. The publish workflow extracts the exact version section from
+the changelog and creates or updates GitHub Release notes idempotently.
+
 ## Implementation Map
 
 - RX-02-RX-05: `path-utils.ts`, `storage.ts`, `configuration.ts`,
@@ -39,8 +44,8 @@ npm bootstrap, and the exact fourteen release assets.
 - RX-10-RX-11: CLI output, release pagination, upgrade selection, replacement,
   rollback, reconciliation, and cache behavior use stable contracts.
 - RX-12-RX-14: both installers, `scripts/runx-bin.mjs`, the binary builder,
-  asset verifier, and GitHub workflows enforce the installation and fourteen
-  asset contracts.
+  asset verifier, exact-version release-note extractor, and GitHub workflows
+  enforce the installation, release-description, and fourteen-asset contracts.
 - RX-15-RX-16: canonical docs, TODO, xdocs, review, validation, tests, builds,
   and release preparation were aligned to the executable.
 

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

@@ -40,7 +40,7 @@ markers, `macos` asset names, and the Bun-dependent npm launcher is not required
 RunX uses the mandatory Bun/TypeScript/Citty/TypeBox stack, has a Bun-only core,
 implements the exact startup/configuration/help/agent/upgrade/installer/output
 contracts, ships a Node-compatible npm bootstrap, and publishes exactly twelve
-RFC-named binaries plus `guiho-s-runx` and `guiho-i-runx`.
+RFC-named binaries plus `guiho-s-runx.md` and `guiho-i-runx.md`.
 
 ## Scope
 
@@ -84,8 +84,12 @@ RFC-named binaries plus `guiho-s-runx` and `guiho-i-runx`.
   raw/names-only rules.
 - Upgrade, list pagination, pre-release filtering, installers, and the npm
   wrapper pass isolated tests.
-- Release verification finds exactly fourteen correctly named assets and no
-  `macos` names.
+- Release verification finds exactly fourteen correctly named assets, including
+  both `.md` agent artifacts, and no `macos` names.
+- GitHub Release notes contain only the exact matching changelog version section,
+  including when an existing release is rerun.
+- Direct installers reject empty, executable, binary, invalid UTF-8, and
+  misidentified downloaded agent Markdown before writing installation targets.
 - Typecheck, tests, safe builds, xdocs validation, implementation review, and
   validation reporting complete successfully.
 

package/docs/todo/todo.xdocs.md

@@ -4,13 +4,27 @@ description: Linked task specifications for the RunX TODO index.
 parent: runx-docs
 children: []
 files:
+  bash-installer.md: Completes the GitHub issue 15 Bash shebang, invocation, strict-mode, and executable test contract.
+  linux-installer-latest-release.md: Defines GitHub issue 20 latest-release alias resolution and public Bash installer acceptance.
+  automatic-agent-maintenance.md: Defines issue 11 automatic agent-resource maintenance outcomes and acceptance signals.
+  automatic-agent-maintenance-implementation.md: Records the delivered issue 11 reconciler, hidden worker, command boundaries, tests, and release handoff.
   protect-branches-and-tag-creation.md: Records the verified active GitHub branch and release-tag rulesets for RunX.
   rfc-0034-cli-compliance-migration.md: Defines the required breaking migration outcome, scope, constraints, and completion signals for full RFC 0034 compliance.
   rfc-0034-cli-compliance-migration-implementation.md: Records the delivered RX units, implementation map, test-hang diagnosis, and independent audit corrections.
+  upgrade-reliability.md: Completes GitHub issues 12 and 13 for verified replacement, complete listing, exact recovery, and direct installers.
+  unicode-help-tree.md: Completes GitHub issue 17 with Unicode branches, nested guides, aligned descriptions, and legacy ASCII rejection.
+  platform-aware-startup-greeting.md: Defines GitHub issue 21 Windows, Linux, and macOS no-argument greeting behavior.
 documents:
+  bash-installer.md: Completed task specification for the canonical RunX Bash installer.
+  linux-installer-latest-release.md: Task specification for reliable latest RunX Bash installation.
+  automatic-agent-maintenance.md: Task specification for automatic RunX skill and AGENTS.md maintenance.
+  automatic-agent-maintenance-implementation.md: Completed implementation record for automatic RunX agent maintenance.
   protect-branches-and-tag-creation.md: Completed task specification with active RunX ruleset IDs, protected patterns, and verification evidence.
   rfc-0034-cli-compliance-migration.md: Task specification linked from TODO task 1 for the full RunX CLI contract migration.
   rfc-0034-cli-compliance-migration-implementation.md: Completed implementation, independent correction, and validation handoff for TODO task 1.
+  upgrade-reliability.md: Completed task specification for RunX upgrade reliability.
+  unicode-help-tree.md: Completed task specification for the RunX Unicode help tree.
+  platform-aware-startup-greeting.md: Task specification for the platform-aware RunX greeting.
 tags:
   - todo
 keywords:

package/docs/todo/unicode-help-tree.md

@@ -0,0 +1,44 @@
+---
+name: Preserve The RunX Unicode Help Tree
+purpose: Track the human-readable tree contract requested by GitHub issue 17.
+description: Records Unicode branches, nested guides, aligned descriptions, legacy ASCII rejection, tests, and delivery evidence.
+created: 2026-07-19
+flags:
+  - completed
+tags:
+  - todo
+  - cli
+  - help
+keywords:
+  - RunX
+  - issue 17
+  - help tree
+  - Unicode
+owner: runx-todo
+---
+
+# Preserve The RunX Unicode Help Tree
+
+## Todo Index
+
+- Task: `5. Preserve The RunX Unicode Help Tree`
+- Status: completed
+- Index: [TODO.md](../../TODO.md)
+- External: [CGuiho/runx issue #17](https://github.com/CGuiho/runx/issues/17)
+
+## Outcome
+
+`runx --help-tree` renders a `COMMAND TREE` with Unicode branch glyphs, nested
+vertical guides, aligned descriptions, commands, and flags. The legacy ASCII
+`|-` tree cannot regress unnoticed.
+
+## Completion Signals
+
+- Root and every public scope render from the real Citty definitions.
+- Tests assert `├──`, `└──`, `│`, aligned descriptions, and no `|-`.
+- Depth limiting and hidden-command exclusion remain intact.
+
+## References
+
+- [Implementation review](../reviews/implementation/unicode-help-tree-review.md)
+- [Validation](../validation/unicode-help-tree.md)

package/docs/todo/upgrade-reliability.md

@@ -0,0 +1,51 @@
+---
+name: Complete RunX Upgrade Reliability
+purpose: Track the accepted outcomes for GitHub issues 12 and 13.
+description: Records immediate verified replacement, complete listing, exact recovery, direct installers, reviews, validation, and delivery evidence.
+created: 2026-07-15
+updated: 2026-07-19
+flags:
+  - completed
+tags:
+  - todo
+  - cli
+  - reliability
+keywords:
+  - RunX
+  - issue 12
+  - issue 13
+  - self-upgrade
+owner: runx-todo
+---
+
+# Complete RunX Upgrade Reliability
+
+## Todo Index
+
+- Task: `3. Complete RunX Upgrade Reliability`
+- Status: completed
+- Index: [TODO.md](../../TODO.md)
+- External: [issue #12](https://github.com/CGuiho/runx/issues/12) and
+  [issue #13](https://github.com/CGuiho/runx/issues/13)
+
+## Outcome
+
+RunX replaces and verifies the canonical executable before success, lists the
+complete published catalog, and exposes exact-version recovery instructions
+after every upgrade outcome in text and JSON.
+
+## Completion Signals
+
+- Transactional Windows replacement and rollback are tested.
+- Catalog pagination, sorting, channels, assets, and single-leaf routing are
+  tested.
+- Every terminal outcome includes a pinned installer and separate stop command.
+- Direct installers normalize exact stable/prerelease versions and reject
+  installed-version mismatches.
+- Current-main reviews and validation contain pushed evidence for both issues.
+
+## References
+
+- [Approved design](../superpowers/specs/2026-07-15-upgrade-reliability-design.md)
+- [Implementation plan](../plans/upgrade-reliability-implementation.md)
+- [Umbrella validation](../validation/upgrade-reliability.md)

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

@@ -0,0 +1,63 @@
+---
+name: RunX Automatic Agent Maintenance Validation
+purpose: Record direct verification evidence for GitHub issue 11.
+description: Captures focused and full tests, builds, native matrix, exact assets, import scan, XDocs, and Git integrity results.
+created: 2026-07-19
+flags:
+  - validated
+tags:
+  - validation
+  - cli
+  - agents
+keywords:
+  - RunX
+  - issue 11
+  - 48 tests
+  - 14 assets
+owner: runx-validation
+---
+
+# RunX Automatic Agent Maintenance Validation
+
+## Summary
+
+All local completion gates for GitHub issue #11 passed. No validation blocker
+remains.
+
+## Commands Run
+
+| Command or check | Result |
+| --- | --- |
+| `bun run typecheck` | Passed |
+| focused maintenance and CLI tests | Passed: 13 tests, 156 assertions |
+| `bun test --timeout 30000` | Passed: 48 tests, 332 assertions |
+| `bun run build` | Passed |
+| `bun run binary` | Passed |
+| `bun run binaries` | Passed: twelve native targets |
+| `bun run verify-assets` | Passed: exactly fourteen unique assets |
+| Windows x64 `--version` smoke | Passed: `0.4.1` |
+| Windows x64 `--help-tree-depth 2` smoke | Passed; hidden worker absent |
+| prohibited core import scan | Passed: zero matches |
+| strict XDocs metadata for source, docs, and bundled skill | Passed |
+| XDocs doctor for source, docs, and bundled skill | Passed: zero errors and zero warnings |
+| `git diff --check` | Passed |
+
+## Behavioral Evidence
+
+- Plain invocation retained its exact banner while both global skills and the
+  nearest project instructions appeared asynchronously.
+- Catalog JSON remained parseable and diagnostics stayed on stderr.
+- Missing, current, stale, legacy, and concurrent states converged as designed.
+- Spawn and worker filesystem failures did not affect foreground output.
+- Explicit skill uninstall and instruction removal stayed removed.
+
+## Skipped Checks
+
+- No global user skill or real repository instruction was mutated by tests.
+- No package publication or GitHub Release creation was performed.
+- No Mirror version application occurred during this issue unit.
+
+## References
+
+- [Implementation review](../reviews/implementation/automatic-agent-maintenance-review.md)
+- [Implementation notes](../todo/automatic-agent-maintenance-implementation.md)

package/docs/validation/bash-installer.md

@@ -0,0 +1,55 @@
+---
+name: RunX Bash Installer Validation
+purpose: Record direct verification evidence for GitHub issue 15.
+description: Captures Bash syntax, piped startup, exact versions, recovery, executable verification, full suite, native assets, XDocs, and Git checks.
+created: 2026-07-19
+flags:
+  - validated
+tags:
+  - validation
+  - installer
+  - bash
+keywords:
+  - RunX
+  - issue 15
+  - bash -n
+  - 14 assets
+owner: runx-validation
+---
+
+# RunX Bash Installer Validation
+
+## Summary
+
+The canonical RunX Linux/macOS installer and recovery command use Bash. No
+validation blocker remains.
+
+## Commands Run
+
+| Command or check | Result |
+| --- | --- |
+| `bun run typecheck` | Passed |
+| focused recovery and installer tests | Passed: 7 tests, 45 assertions |
+| Git Bash `bash -n devops/install.sh` | Passed |
+| piped source-only Bash fixture | Passed with exit 0 and empty stderr |
+| exact stable/prerelease normalization fixture | Passed |
+| Bash executable-version verification fixture | Passed |
+| `bun test --timeout 30000` | Passed: 53 tests, 363 assertions |
+| build, native matrix, exact assets | Passed: library, single binary, twelve native targets, exactly fourteen assets |
+| canonical `sh` reference scan | Passed: zero matches |
+| strict XDocs metadata and doctor | Passed for source, devops, and docs: zero errors and zero warnings |
+| `git diff --check` | Passed |
+
+## Contract Evidence
+
+- The script declares `#!/usr/bin/env bash` and `set -euo pipefail`.
+- README and generated recovery commands pipe to `bash`, never `sh`.
+- Tests run with Git for Windows Bash locally and resolve the ordinary Bash
+  executable on Linux/macOS CI.
+- The Bash function fixture verifies full prerelease identifiers and executes
+  the installed-version check against a real executable.
+
+## References
+
+- [Implementation review](../reviews/implementation/bash-installer-review.md)
+- [Task specification](../todo/bash-installer.md)

package/docs/validation/linux-installer-latest-release.md

@@ -0,0 +1,50 @@
+---
+name: Latest RunX Bash Installer Validation
+purpose: Record verification evidence for GitHub issue 20.
+description: Captures Bash syntax, installer regression tests, full package checks, release assets, public latest-alias resolution, and remaining live-install verification.
+created: 2026-07-20
+flags:
+  - release-ready
+tags:
+  - validation
+  - installer
+keywords:
+  - issue 20
+  - latest download
+  - fourteen assets
+owner: runx-validation
+---
+
+# Latest RunX Bash Installer Validation
+
+## Summary
+
+The implementation is ready for patch release. Public installation against the
+new patch remains the final closure gate.
+
+## Commands Run
+
+| Check | Result |
+| --- | --- |
+| `bash -n devops/install.sh` | Passed |
+| `bun test devops/installers.spec.ts` | Passed: 5 tests, 39 expectations |
+| `bun run typecheck` | Passed |
+| `bun test` | Passed: 54 tests, 373 expectations |
+| `bun run build` | Passed |
+| `bun run binary` | Passed |
+| `bun run binaries` | Passed: 12 native binaries |
+| `bun run verify-assets` | Passed: exactly 14 assets |
+| Public `releases/latest/download/runx-linux-x64-baseline` headers | Passed: redirects to the current RunX release asset and returns HTTP 200 |
+| XDocs strict metadata, tree, and doctor | Passed |
+
+## Regression Evidence
+
+- The script contains the stable latest-download endpoint.
+- The script does not inspect `url_effective`.
+- Sourced Bash tests prove latest and exact encoded-tag URL shapes.
+- Existing payload, Markdown, and executable checks remain green.
+
+## Remaining Gate
+
+After publication, execute the public Bash installer on Linux, verify the
+reported version, and record the result in issue 20 before closure.

package/docs/validation/platform-aware-startup-greeting.md

@@ -0,0 +1,50 @@
+---
+name: Platform-Aware RunX Greeting Validation
+purpose: Record verification evidence for GitHub issue 21.
+description: Captures deterministic platform assertions, runtime smoke tests, full package checks, and remaining released-Linux verification.
+created: 2026-07-20
+flags:
+  - release-ready
+tags:
+  - validation
+  - cli
+keywords:
+  - issue 21
+  - Windows
+  - Linux
+  - macOS
+owner: runx-validation
+---
+
+# Platform-Aware RunX Greeting Validation
+
+## Summary
+
+The implementation is ready for patch release. The published Linux executable
+is the final platform-specific closure gate.
+
+## Commands Run
+
+| Check | Result |
+| --- | --- |
+| Focused `bun test source/cli.spec.ts` banner assertions | Passed |
+| Independently rerun background-maintenance timing test | Passed |
+| `bun run typecheck` | Passed |
+| `bun test` | Passed: 54 tests, 373 expectations |
+| `bun run build` | Passed |
+| `bun run binaries` | Passed |
+| Compiled `runx-windows-x64-baseline.exe` no arguments | Passed: `Hello Windows - runx v0.5.1` |
+| Compiled Windows `--version` | Passed: `0.5.1` |
+| XDocs strict metadata, tree, and doctor | Passed |
+
+## Deterministic Assertions
+
+- `win32` renders `Hello Windows`.
+- `linux` renders `Hello Linux`.
+- `darwin` renders `Hello macOS`.
+- Cached update output remains before the startup greeting.
+
+## Remaining Gate
+
+After publication, run the released Linux binary without arguments and record
+`Hello Linux - runx v<released-version>` in issue 21 before closure.

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

@@ -10,7 +10,7 @@ tags:
   - cli
 keywords:
   - RFC 0034
-  - 40 tests
+  - 44 tests
   - 14 assets
   - RunX
 owner: runx-validation
@@ -29,17 +29,19 @@ validation blocker remains.
 | Command or check | Result |
 | --- | --- |
 | `bun run typecheck` | Passed |
-| `bun test --timeout 30000` | Passed: 40 tests, 272 assertions |
+| `bun test --timeout 30000` | Passed: 44 tests, 288 assertions |
 | `bun run build` | Passed |
 | `bun run binary` | Passed |
 | `bun run binaries` | Passed: twelve native targets |
 | `bun run verify-assets` | Passed: exactly fourteen unique assets |
+| `bun test devops/extract-release-notes.spec.ts` | Passed: exact heading boundaries, missing-section failure, and frontmatter/older-section exclusion |
 | `node --check scripts/runx-bin.mjs` | Passed |
 | packed npm bootstrap local-server smoke | Passed with Node and Bun removed from PATH |
 | prohibited core Node-import scan | Passed: zero matches |
 | CLI banner/help/config/agent/output/exit smoke tests | Passed in CLI suite |
 | live `upgrade --help`, prompt names, source banner, and compiled version smokes | Passed |
 | PowerShell and POSIX installer contract tests | Passed |
+| disguised-PE Markdown installer regression | Passed: installer rejected `MZ` payload before any resource write |
 | `xdocs doctor --warnings-as-errors` | Passed: zero errors and zero warnings |
 | `git diff --check` | Passed |
 
@@ -59,8 +61,12 @@ validation blocker remains.
 ## Exact Release Asset Evidence
 
 The verifier observed twelve `runx-*` assets using Linux, Darwin, and Windows
-names plus `guiho-s-runx` and `guiho-i-runx`. It found no duplicate, extra,
-missing, or legacy platform name.
+names plus `guiho-s-runx.md` and `guiho-i-runx.md`. It found no duplicate,
+extra, missing, or legacy platform name.
+
+The publish workflow writes a temporary notes file containing only the exact
+version section from `CHANGELOG.md`. Existing releases receive the same notes
+through `gh release edit` before their asset set is refreshed.
 
 ## Skipped Checks
 

package/docs/validation/unicode-help-tree.md

@@ -0,0 +1,43 @@
+---
+name: RunX Unicode Help Tree Validation
+purpose: Record direct verification evidence for GitHub issue 17.
+description: Captures focused and full help tests, native tree smoke, builds, exact assets, XDocs, and Git integrity.
+created: 2026-07-19
+flags:
+  - validated
+tags:
+  - validation
+  - cli
+  - help
+keywords:
+  - RunX
+  - issue 17
+  - Unicode tree
+  - aligned descriptions
+owner: runx-validation
+---
+
+# RunX Unicode Help Tree Validation
+
+## Summary
+
+The RunX help tree matches the requested readable Unicode hierarchy. No
+validation blocker remains.
+
+## Commands Run
+
+| Command or check | Result |
+| --- | --- |
+| `bun run typecheck` | Passed |
+| focused CLI tests | Passed: 11 tests, 140 assertions |
+| explicit root tree assertions | Passed: `├──`, `└──`, `│`, aligned list description, no `|-` |
+| `bun test --timeout 30000` | Passed: 53 tests, 368 assertions |
+| build, native matrix, exact assets | Passed: library, single binary, twelve native targets, exactly fourteen assets |
+| native Windows x64 `--help-tree-depth 2` | Passed: Unicode nesting and aligned descriptions; no `|-` |
+| strict XDocs metadata and doctor | Passed for source and docs: zero errors and zero warnings |
+| `git diff --check` | Passed |
+
+## References
+
+- [Implementation review](../reviews/implementation/unicode-help-tree-review.md)
+- [Task specification](../todo/unicode-help-tree.md)