@guiho/runx 0.4.1 → 0.5.1

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

@@ -0,0 +1,56 @@
+---
+name: RunX Automatic Agent Maintenance Plan Review
+purpose: Verify the issue 11 implementation plan is safe, sequenced, and testable.
+description: Reviews atomic reconciliation, hidden-worker scheduling, explicit-command boundaries, test isolation, documentation, and delivery gates.
+created: 2026-07-19
+flags:
+  - approved
+  - ready-for-execution
+  - executed
+tags:
+  - review
+  - plan
+  - cli
+keywords:
+  - RunX
+  - issue 11
+  - plan review
+owner: runx-plan-reviews
+---
+
+# RunX Automatic Agent Maintenance Plan Review
+
+## Verdict
+
+Ready for execution.
+
+## Findings
+
+No blocker or high-severity finding remains.
+
+- Resolved: automatic writes follow atomic primitives and content comparison.
+- Resolved: effective cwd comes from Citty state after routing.
+- Resolved: explicit agent/uninstall operations are excluded so removal is not
+  immediately reversed.
+- Resolved: temporary homes and injected spawn behavior protect real installs.
+
+## Sequencing Risks
+
+Worker wiring must not precede atomic reconciliation. Output-isolation and
+concurrency tests must pass before documentation claims completion.
+
+## TODO Alignment
+
+RunX TODO task `2` owns the issue. The implementation and local validation are
+complete; pushed evidence and issue closure are the final external delivery
+steps.
+
+## First Executable Unit
+
+AM-01: atomic text replacement and idempotent global/nearest reconciliation.
+
+## References
+
+- [Plan](../../plans/automatic-agent-maintenance.md)
+- [Task specification](../../todo/automatic-agent-maintenance.md)
+- [GitHub issue #11](https://github.com/CGuiho/runx/issues/11)

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

@@ -4,6 +4,7 @@ description: Execution-readiness reviews for RunX implementation and release pla
 parent: runx-reviews
 children: []
 files:
+  automatic-agent-maintenance-review.md: Reviews the issue 11 automatic agent-maintenance plan for safe execution.
   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.
@@ -12,6 +13,7 @@ files:
   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:
+  automatic-agent-maintenance-review.md: Ready-for-execution review for automatic agent maintenance.
   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.

package/docs/superpowers/specs/2026-07-15-upgrade-reliability-design.md

@@ -464,7 +464,7 @@ powershell.exe -NoProfile -Command "Get-Process runx -ErrorAction SilentlyContin
 Linux and macOS use the supported shell installer with an explicit version:
 
 ```text
-curl -fsSL https://raw.githubusercontent.com/CGuiho/runx/main/devops/install.sh | sh -s -- --version '0.2.7'
+curl -fsSL https://raw.githubusercontent.com/CGuiho/runx/main/devops/install.sh | bash -s -- --version '0.2.7'
 ```
 
 Their separate stop command is:

package/docs/todo/automatic-agent-maintenance-implementation.md

@@ -0,0 +1,55 @@
+---
+name: RunX Automatic Agent Maintenance Implementation
+purpose: Preserve the implemented GitHub issue 11 automatic agent-resource maintenance record.
+description: Records the atomic reconciler, hidden detached worker, command boundaries, regression coverage, and delivery handoff.
+created: 2026-07-19
+flags:
+  - completed
+tags:
+  - implementation
+  - cli
+  - agents
+keywords:
+  - RunX
+  - issue 11
+  - guiho-s-runx
+  - AGENTS.md
+owner: runx-todo
+---
+
+# RunX Automatic Agent Maintenance Implementation
+
+## Summary
+
+Ordinary RunX invocations now schedule a silent detached worker that compares
+the bundled `guiho-s-runx` skill with both global tool installations and
+reconciles one nearest applicable `AGENTS.md`. Foreground command output, JSON,
+help, delegated exit behavior, and startup latency remain independent of the
+maintenance result.
+
+## Implementation Map
+
+- `source/storage.ts` provides same-directory temporary writes followed by
+  replacement and cleanup on failure.
+- `source/agents.ts` compares current skill bytes, repairs missing or stale
+  global skills, finds the nearest ancestor `AGENTS.md`, migrates legacy
+  markers, preserves user content, and emits exactly one current managed block.
+- `source/agent-maintenance.ts` TypeBox-decodes the hidden worker invocation,
+  disables recursion, detaches standard streams, and isolates spawn failures.
+- `source/cli.ts` schedules maintenance after Citty execution with its decoded
+  effective cwd while excluding explicit `agent` and `uninstall` operations.
+- `source/agent-maintenance.spec.ts` and `source/cli.spec.ts` cover missing,
+  current, stale, legacy, concurrent, hidden, failure, output, cwd, and explicit
+  removal behavior without touching real user locations.
+
+## Delivery Boundary
+
+This implementation completes GitHub issue #11. Versioning remains deferred to
+the single final Mirror minor release after the complete open-issue sequence.
+
+## References
+
+- [Task specification](./automatic-agent-maintenance.md)
+- [Implementation plan](../plans/automatic-agent-maintenance.md)
+- [Implementation review](../reviews/implementation/automatic-agent-maintenance-review.md)
+- [Validation](../validation/automatic-agent-maintenance.md)

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

@@ -0,0 +1,86 @@
+---
+name: Add Automatic RunX Agent Maintenance
+purpose: Define the outcome and acceptance signals for RunX GitHub issue 11.
+description: Tracks non-blocking global skill repair, nearest AGENTS.md reconciliation, atomicity, isolation, tests, and delivery evidence.
+created: 2026-07-19
+flags:
+  - approved
+  - completed
+tags:
+  - todo
+  - cli
+  - agents
+keywords:
+  - RunX
+  - GitHub issue 11
+  - guiho-s-runx
+  - AGENTS.md
+owner: runx-todo
+---
+
+# Add Automatic RunX Agent Maintenance
+
+## Todo Index
+
+- Task: `2. Add Automatic RunX Agent Maintenance`
+- Status: completed
+- Index: [TODO.md](../../TODO.md)
+- External: [CGuiho/runx issue #11](https://github.com/CGuiho/runx/issues/11)
+
+## Outcome
+
+Ordinary RunX commands automatically and silently converge the bundled global
+skill and nearest project instruction block without delaying, polluting, or
+failing the requested command.
+
+## Scope
+
+### In scope
+
+- Both global RunX skill targets.
+- Nearest applicable `AGENTS.md`.
+- Current and legacy managed blocks.
+- Atomic, idempotent, concurrent-safe writes.
+- Hidden detached worker startup and failure isolation.
+- Text/JSON/help/version/exit-code stability.
+- Tests, docs, xdocs, review, validation, push, comment, and closure.
+
+### Out of scope
+
+- Reintroducing plural `runx agents` compatibility.
+- Network-based skill discovery.
+- Implicit XDocs or other CLI resource mutations.
+- Versioning before the complete open-issue sequence finishes.
+
+## Acceptance Signals
+
+- Plain RunX schedules the hidden worker.
+- Missing/stale global skills are repaired; current skills are not rewritten.
+- The nearest `AGENTS.md` contains exactly one compact current RunX block.
+- User-authored content remains unchanged outside managed markers.
+- Worker scheduling and reconciliation failures cannot fail the foreground.
+- Concurrent workers converge safely.
+- Public help contains no hidden worker route.
+- Text and JSON output remain deterministic.
+- Tests cover every state named by issue #11.
+- Pushed evidence precedes the resolution comment and closure.
+
+## Watch-outs
+
+- Explicit skill uninstall and RunX uninstall must not trigger reinstallation.
+- Tests must use temporary HOME/USERPROFILE paths and never mutate real global
+  skills or repository instructions.
+- The worker must use Citty-decoded `--cwd`, not a second public flag parser.
+
+## Related Files
+
+- [Implementation plan](../plans/automatic-agent-maintenance.md)
+- [Implementation notes](./automatic-agent-maintenance-implementation.md)
+- [Implementation review](../reviews/implementation/automatic-agent-maintenance-review.md)
+- [Validation](../validation/automatic-agent-maintenance.md)
+- [CLI architecture](../architecture/cli-architecture.md)
+
+## References
+
+- [TODO.md](../../TODO.md)
+- [GitHub issue #11](https://github.com/CGuiho/runx/issues/11)

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/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,23 @@ 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.
+  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.
 documents:
+  bash-installer.md: Completed task specification for the canonical RunX Bash installer.
+  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.
 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/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)