@guiho/runx 0.2.4 → 0.2.5

package/docs/decisions/decisions.xdocs.md

@@ -6,16 +6,19 @@ children: []
 files:
   alpha-boundaries.md: Captures accepted alpha scope, safety, distribution, and compatibility decisions.
   citty-cli-migration.md: Defines the accepted full migration from handwritten parsing and routing to Citty.
+  mirror-automatic-push.md: Defines automatic Mirror release pushes with a synchronized protected-main gate.
   npm-trusted-publishing.md: Defines the accepted npm OIDC publishing workflow and protected-branch patch-release trial.
 documents:
   alpha-boundaries.md: Decision record for RunX alpha boundaries.
   citty-cli-migration.md: Decision record for the complete Citty CLI parser and router migration.
+  mirror-automatic-push.md: Accepted release-policy decision for Mirror push=true and protected delivery ordering.
   npm-trusted-publishing.md: Decision record for GitHub Actions npm trusted publishing and the first automated patch release.
 tags:
   - decisions
 keywords:
   - runx
   - decisions
+  - mirror push
 flags: []
 status: stable
 ---

package/docs/decisions/mirror-automatic-push.md

@@ -0,0 +1,84 @@
+---
+name: RunX Mirror Automatic Release Push
+purpose: Record the accepted policy that Mirror pushes RunX release commits and tags automatically.
+description: Defines push=true, the synchronized-main precondition, protected GitHub delivery, failure behavior, and rollback boundary.
+created: 2026-07-14
+flags:
+  - accepted
+tags:
+  - decisions
+  - release
+  - mirror
+keywords:
+  - runx
+  - mirror push
+  - protected main
+  - release tags
+owner: runx-decisions
+---
+
+# RunX Mirror Automatic Release Push
+
+## Status
+
+Accepted by the repository owner on 2026-07-14.
+
+## Context
+
+RunX previously configured Mirror with `push = false`. Each release applied the
+version commit and tag locally, then required separate branch delivery and tag
+push commands. The owner wants RunX to match the automatic Mirror release flow
+used by the related GUIHO repositories.
+
+RunX also protects `main` and `@guiho/runx@*` tags. Automatic pushing must not
+allow a release tag to reference a commit that has not reached protected
+`main`.
+
+## Decision
+
+- Set `[git].push = true` in `mirror.config.toml`.
+- Run future `mirror version apply` operations only from a clean, synchronized
+  local `main` whose HEAD equals `origin/main`.
+- Complete implementation changes through protected pull requests before
+  applying Mirror.
+- Treat `mirror version apply` as the single release mutation that writes the
+  version, commits, tags, and pushes the configured refs.
+- Keep package publication behind the GitHub `production` environment approval
+  and npm OIDC trusted publishing.
+
+## Alternatives Considered
+
+- Keep `push = false`: rejected because it preserves the manual release step the
+  owner explicitly asked to remove.
+- Pass `--push` per release: rejected because it makes release behavior depend
+  on operator memory instead of repository configuration.
+- Apply Mirror on a release branch and merge later: rejected because the tag
+  could publish a commit before that commit is part of protected `main`.
+
+## Consequences
+
+- Successful Mirror applies will immediately push release refs and can trigger
+  the public Publish workflow.
+- Operators must treat `mirror version apply` as an externally visible release,
+  not a local preparation step.
+- The synchronized-main gate becomes mandatory; failures stop before apply.
+- Existing GitHub rulesets, environment review, and OIDC remain the enforcement
+  layers for branch, tag, and package publication.
+
+## Reversal Or Revisit Conditions
+
+Return to `push = false` if Mirror cannot push through repository protections
+reliably, if releases need a separate staging phase, or if automatic tag
+publication creates unacceptable operational risk.
+
+## Follow-up Work
+
+- Update repository instructions and XDocs metadata.
+- Validate resolved Mirror configuration and a read-only patch plan.
+- Deliver the configuration through protected `main` without applying another
+  release.
+
+## References
+
+- [Citty CLI Migration Plan](../plans/citty-cli-migration.md)
+- [npm Trusted Publishing Decision](npm-trusted-publishing.md)

package/docs/plans/mirror-automatic-push.md

@@ -0,0 +1,77 @@
+---
+name: RunX Mirror Automatic Push Plan
+purpose: Execute the accepted push=true release policy through protected main without creating another release.
+description: Sequences configuration, safety instructions, XDocs validation, protected delivery, and post-merge verification.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - plans
+  - release
+  - mirror
+keywords:
+  - runx
+  - mirror push
+  - protected main
+  - configuration
+owner: runx-plans
+---
+
+# RunX Mirror Automatic Push Plan
+
+## Source Decision
+
+- [RunX Mirror Automatic Release Push](../decisions/mirror-automatic-push.md)
+
+## Unit 1: Configure And Document Automatic Push
+
+- Goal: Make automatic release pushing a repository-owned Mirror policy.
+- Owner: RunX repository.
+- Dependencies: Accepted automatic-push decision; `0.2.4` already applied and
+  pushed, so this change must not apply another version.
+- Files:
+  - `mirror.config.toml`
+  - `AGENTS.md`
+  - `runx.xdocs.md`
+- Data, auth, and cache: No application data, authentication, authorization, or
+  cache impact. GitHub credentials and rulesets remain external.
+- Changes:
+  - Set `[git].push = true`.
+  - Require clean synchronized `main` before `mirror version apply`.
+  - Document that apply is an externally visible release mutation.
+- Checks:
+  - `mirror config check`
+  - `mirror config show`
+  - `mirror version plan patch --format json`
+  - Verify the plan reports `pushEnabled: true` and next patch `0.2.5` without
+    applying it.
+  - Strict root XDocs metadata and doctor checks.
+- Acceptance: The resolved config enables push; safety guidance prevents apply
+  from a feature branch or stale main; no version, commit, or tag is created by
+  validation.
+- Stop conditions: Stop if Mirror cannot load the config, the read-only plan
+  mutates state, or the worktree contains unrelated changes.
+
+## Unit 2: Deliver Through Protected Main
+
+- Goal: Merge the configuration policy without bypassing required CI.
+- Dependencies: Unit 1 complete and committed.
+- Delivery:
+  - Push `codex/mirror-auto-push`.
+  - Open a ready pull request to `main`.
+  - Wait for required CI and merge through the repository ruleset.
+  - Synchronize local `main` and confirm `mirror config show` reports
+    `push: true`.
+- Acceptance: `origin/main` owns the configuration and instructions; no new
+  release tag was created.
+- Stop conditions: Stop on CI failure, unresolved protection failure, or an
+  unexpected version/tag mutation.
+
+## TODO Alignment
+
+This is a bounded owner-approved configuration change completed in one session;
+it does not require a separate TODO entry.
+
+## First Executable Unit
+
+Unit 1: set and document the resolved Mirror automatic-push policy.

package/docs/plans/plans.xdocs.md

@@ -6,10 +6,12 @@ children: []
 files:
   alpha-implementation.md: Breaks the accepted alpha into implementation and validation units.
   citty-cli-migration.md: Executes the full Citty command-tree migration, compatibility validation, protected delivery, and patch release.
+  mirror-automatic-push.md: Enables automatic Mirror release pushes with a synchronized protected-main safety gate.
   npm-trusted-publishing-release.md: Sequences workflow implementation, protected delivery, Mirror patching, and public trusted-publishing verification.
 documents:
   alpha-implementation.md: Plan used for the initial RunX implementation.
   citty-cli-migration.md: Active plan for replacing handwritten CLI parsing and routing with Citty and delivering its patch release.
+  mirror-automatic-push.md: Approved plan for configuring, validating, and merging Mirror push=true without applying another release.
   npm-trusted-publishing-release.md: Approved executable plan for the RunX 0.2.1 trusted-publishing release trial.
 tags:
   - plans
@@ -17,6 +19,7 @@ keywords:
   - runx
   - implementation
   - citty
+  - mirror push
 flags: []
 status: stable
 ---

package/docs/reviews/plans/mirror-automatic-push-review.md

@@ -0,0 +1,57 @@
+---
+name: RunX Mirror Automatic Push Plan Review
+purpose: Verify that the automatic-push configuration plan is safe, bounded, and ready for execution.
+description: Reviews synchronized-main safeguards, read-only validation, protected delivery, and release side effects.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - reviews
+  - plans
+  - release
+keywords:
+  - runx
+  - mirror push
+  - plan review
+  - protected main
+owner: runx-plan-reviews
+---
+
+# RunX Mirror Automatic Push Plan Review
+
+## Verdict
+
+Ready for execution.
+
+## Findings
+
+- No blocker or high-severity findings remain.
+- The clean, synchronized `main` precondition is explicit and prevents a
+  release tag from pointing at an unmerged feature or stale commit.
+- Unit 1 uses only read-only Mirror validation and explicitly prohibits another
+  version apply, so the current `0.2.4` release remains unchanged.
+- The plan documents that `push = true` makes every future Mirror apply an
+  externally visible release mutation.
+- No application data, authentication, authorization, or cache behavior is
+  affected. GitHub credentials, rulesets, environment approval, and npm OIDC
+  remain external enforcement layers.
+
+## Delivery Review
+
+- The configuration change must pass the protected pull-request workflow
+  before reaching `main`.
+- Post-merge verification checks the resolved configuration on synchronized
+  `main` and confirms that no `0.2.5` tag was created.
+- A CI failure, protection failure, or unexpected version mutation is an
+  explicit stop condition.
+
+## First Executable Unit
+
+Execute Unit 1 in
+[RunX Mirror Automatic Push Plan](../../plans/mirror-automatic-push.md): set and
+document the resolved automatic-push policy without applying a release.
+
+## References
+
+- [RunX Mirror Automatic Push Plan](../../plans/mirror-automatic-push.md)
+- [RunX Mirror Automatic Release Push](../../decisions/mirror-automatic-push.md)

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

@@ -5,9 +5,11 @@ parent: runx-reviews
 children: []
 files:
   citty-cli-migration-review.md: Reviews completeness, compatibility, safety invariants, native packaging, and release sequencing for the Citty migration.
+  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.
 documents:
   citty-cli-migration-review.md: Ready-for-execution review of the full Citty CLI migration 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.
 tags:
   - reviews
@@ -16,6 +18,7 @@ keywords:
   - runx
   - plan review
   - citty
+  - mirror push
   - trusted publishing
 flags: []
 status: stable

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/runx",
   "description": "A language-agnostic, documented command catalog and local CLI executor.",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "type": "module",
   "main": "./library/guiho-runx.js",
   "types": "./library/guiho-runx.d.ts",