@guiho/runx 0.4.1 → 0.5.2

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,29 @@ 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.
+  linux-installer-latest-release-review.md: Accepts latest-download alias resolution, exact-version preservation, transactional safeguards, tests, and GitHub issue 20 release readiness.
+  platform-aware-startup-greeting-review.md: Accepts centralized Windows, Linux, and macOS startup labels, deterministic tests, documentation, and GitHub issue 21 release 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.
+  linux-installer-latest-release-review.md: Accepted implementation review for GitHub issue 20.
+  platform-aware-startup-greeting-review.md: Accepted implementation review for GitHub issue 21.
   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/linux-installer-latest-release-review.md

@@ -0,0 +1,49 @@
+---
+name: Latest RunX Bash Installer Implementation Review
+purpose: Review the GitHub issue 20 installer correction against its approved plan and acceptance signals.
+description: Confirms latest-download URL resolution, exact version preservation, transactional safeguards, tests, and release readiness.
+created: 2026-07-20
+flags:
+  - accepted
+tags:
+  - review
+  - installer
+keywords:
+  - issue 20
+  - latest release
+  - install.sh
+owner: runx-implementation-reviews
+---
+
+# Latest RunX Bash Installer Implementation Review
+
+## Verdict
+
+Accepted for patch release.
+
+## Findings
+
+No blocking findings.
+
+## Acceptance Criteria Check
+
+- Latest binaries and Markdown assets use
+  `releases/latest/download/<asset>`.
+- Explicit stable and prerelease versions retain encoded RunX tag URLs.
+- Redirect `url_effective` parsing was removed.
+- Transactional replacement, rollback, native validation, Markdown validation,
+  dual skill installation, instruction reconciliation, PATH setup, and final
+  executable verification remain present.
+- Focused and full regression suites pass.
+
+## Residual Risk
+
+The Windows host cannot execute the Linux binary locally. Public Linux
+installation and greeting behavior must be verified after the patch assets are
+published.
+
+## References
+
+- [Task specification](../../todo/linux-installer-latest-release.md)
+- [Implementation plan](../../plans/linux-installer-latest-release.md)
+- [GitHub issue 20](https://github.com/CGuiho/runx/issues/20)

package/docs/reviews/implementation/platform-aware-startup-greeting-review.md

@@ -0,0 +1,51 @@
+---
+name: Platform-Aware RunX Greeting Implementation Review
+purpose: Review the GitHub issue 21 greeting correction against its approved plan and acceptance signals.
+description: Confirms centralized platform labels, deterministic coverage, update-notice ordering, and release readiness.
+created: 2026-07-20
+flags:
+  - accepted
+tags:
+  - review
+  - cli
+keywords:
+  - issue 21
+  - platform greeting
+  - startup
+owner: runx-implementation-reviews
+---
+
+# Platform-Aware RunX Greeting Implementation Review
+
+## Verdict
+
+Accepted for patch release.
+
+## Findings
+
+No blocking findings.
+
+## Acceptance Criteria Check
+
+- One pure renderer maps Windows, Linux, and macOS deterministically.
+- The no-argument Citty route uses the renderer.
+- Cached update notices remain before the greeting.
+- Version, help, routing, diagnostics, and exit behavior are unchanged.
+- Tests assert all three supported operating-system labels and runtime
+  child-process behavior.
+- Repository instructions and CLI documentation describe the new contract.
+
+## Deviation
+
+The historical RFC 0034 literal-Windows banner is intentionally superseded by
+the developer-approved platform-aware contract.
+
+## Residual Risk
+
+The released Linux binary must be smoke-tested after publication.
+
+## References
+
+- [Task specification](../../todo/platform-aware-startup-greeting.md)
+- [Implementation plan](../../plans/platform-aware-startup-greeting.md)
+- [GitHub issue 21](https://github.com/CGuiho/runx/issues/21)

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)

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)