@guiho/runx 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -15,6 +15,37 @@ owner: runx
 
 # Changelog
 
+## 0.2.7 - 2026-07-15
+
+### Added
+
+- Added an interactive `runx init` command that collects the project name and
+  scripts directory, previews the generated catalog, and confirms before writing.
+- Added safe cancellation and explicit overwrite confirmation so initialization
+  never leaves a partial manifest or replaces an existing catalog silently.
+
+### Changed
+
+- Initialized catalogs now use the SemVer-compatible manifest version `1.0.0`,
+  configure `scripts.directory`, include the required `public` group, and begin
+  with an empty command list.
+- `runx init` creates only `runx.yaml`; the configured `scripts` directory is
+  created later with the first real script.
+
+## 0.2.6 - 2026-07-14
+
+### Added
+
+- Added Windows CI coverage for replacing a running executable, verifying the
+  installed target version, cleaning the old image, and rolling back failures.
+
+### Fixed
+
+- Fixed `runx upgrade` on Windows so it replaces and verifies `runx.exe` before
+  reporting success instead of returning a detached `scheduled: true` state.
+- Failed Windows replacements now restore the previous executable, report a
+  non-zero error, and clean `.new` and `.old` update files safely.
+
 ## 0.2.4 - 2026-07-14
 
 ### Added

package/DOCS.md

@@ -28,6 +28,7 @@ lists its commands, and runs exactly one selected command.
 | `runx` | Show the home page and usage without loading a manifest. |
 | `runx -h`, `runx --help` | Show Citty-generated usage without loading a manifest. Append help to a command for command-specific usage. |
 | `runx -v`, `runx --version` | Show the installed version without loading a manifest. |
+| `runx init [--cwd <path>]` | Interactively create an empty `runx.yaml` catalog in the selected directory. |
 | `runx list` | List all manifest commands. Add `--format json` for structured output. |
 | `runx describe <selector>` | Show one command's description and operational metadata. |
 | `runx check` | Validate discovery and the manifest without execution. |
@@ -48,6 +49,13 @@ Global flags: `--cwd <path>`, `--file <path>`, `--format <text|json>`,
 Unknown options and missing required arguments produce command usage instead
 of falling through to manifest discovery.
 
+`runx init` is intentionally an interactive text workflow: it accepts `--cwd`
+to select the target project, but rejects `--file` (the target is always
+`runx.yaml`) and `--format json`. It previews the exact file, requires a final
+confirmation, asks before replacing an existing file, and leaves no partial
+file when cancelled. It creates the manifest only; the configured scripts
+directory is created later when the first script is added.
+
 Citty is the CLI parser, command router, alias registry, and ordinary usage
 renderer. RunX keeps its home page, extended command tree, and manifest guide
 as the explicit `runx`, `--help-tree`, and `--help-docs` surfaces.
@@ -58,10 +66,14 @@ RunX searches upward from the current directory for `runx.yaml`. Use `--file`
 to select an explicit manifest. RunX does not merge files.
 
 ```yaml
-version: 1
+version: "1.0.0"
 project:
   name: example
+scripts:
+  directory: scripts
 groups:
+  public:
+    summary: Default public project commands.
   development:
     summary: Local development work.
   release:
@@ -85,14 +97,22 @@ commands:
     confirm: always
 ```
 
-Required fields are `uid`, `id`, `group`, `summary`, `description`, and
-`command`. `uid` and `id` begin with a lowercase letter and use lowercase
+`version` is a Semantic Versioning string. RunX currently supports major
+version `1`, including valid prerelease and build metadata forms. Every manifest
+also requires `scripts.directory`, which must be a relative subdirectory inside
+the manifest directory, and a `public` group with a non-empty summary. A
+catalog may start with `commands: []`; every command added later must explicitly
+name an existing group (normally `public`).
+
+Required command fields are `uid`, `id`, `group`, `summary`, `description`,
+and `command`. `uid` and `id` begin with a lowercase letter and use lowercase
 letters, digits, and hyphens. `uid` is globally unique; the group and ID pair
 is also unique.
 
-Optional fields are `cwd`, `shell`, `tags`, and `confirm`. `cwd` is relative to
-the manifest and cannot escape its directory. Shell values are `auto`, `bash`,
-`sh`, `powershell`, and `cmd`. Confirmation values are `never` and `always`.
+Optional command fields are `cwd`, `shell`, `tags`, and `confirm`. `cwd` is
+relative to the manifest and cannot escape its directory. Shell values are
+`auto`, `bash`, `sh`, `powershell`, and `cmd`. Confirmation values are `never`
+and `always`.
 
 ## Selectors and Safety
 
@@ -122,9 +142,11 @@ runx agents install local
 
 `devops/install.ps1` installs Windows assets and `devops/install.sh` installs
 macOS/Linux assets from GitHub Releases into the user's local bin directory.
-`runx upgrade` uses the matching release asset and replaces a native executable;
-on Windows replacement is scheduled after RunX exits. `runx uninstall` removes
-the same native executable and supports `--dry-run`.
+`runx upgrade` uses the matching release asset and replaces a native executable.
+On Windows it renames the running executable, installs and verifies the target
+version at the original path, and restores the previous executable if replacement
+fails. Only cleanup of the renamed old image is deferred until RunX exits.
+`runx uninstall` removes the same native executable and supports `--dry-run`.
 
 When the latest GitHub Release matches the installed version, `runx upgrade` prints `Already up to date.` and exits successfully without downloading or scheduling executable replacement. JSON output reports `upToDate: true`.
 

package/README.md

@@ -39,11 +39,29 @@ curl -fsSL https://raw.githubusercontent.com/CGuiho/runx/main/devops/install.sh
 
 ## Quick Start
 
-Create `runx.yaml` in a project root:
+Start with the interactive initializer:
+
+```text
+runx init
+```
+
+It writes only `runx.yaml`—not an empty `scripts/` directory. The resulting
+catalog starts with a SemVer `1.x` manifest version, a configurable scripts
+directory, the required `public` group, and no commands. Add commands directly
+or ask an agent to add a script under the configured directory and its command
+entry together.
+
+For example, a catalog with a development command can look like this:
 
 ```yaml
-version: 1
+version: "1.0.0"
+project:
+  name: example
+scripts:
+  directory: scripts
 groups:
+  public:
+    summary: Default public project commands.
   development:
     summary: Local development commands.
 commands:
@@ -52,7 +70,7 @@ commands:
     group: development
     summary: Start the application locally.
     description: Starts the application in local development mode until interrupted.
-    command: bun run dev
+    command: bash scripts/dev.sh
     shell: bash
     tags: [local, watch]
 ```
@@ -63,6 +81,7 @@ Then use RunX:
 runx                         Show the home page and usage.
 runx -h                      Show Citty-generated command help.
 runx -v                      Show the installed version without loading a manifest.
+runx init                    Interactively create an empty runx.yaml catalog.
 runx list                    List commands in the nearest manifest.
 runx describe app-dev        Explain one command without execution.
 runx run app-dev --dry-run   Inspect the execution plan.

package/docs/decisions/decisions.xdocs.md

@@ -6,19 +6,26 @@ 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.
+  interactive-init-manifest.md: Defines interactive initialization, Semantic Versioning, the public group, and the scripts directory contract.
   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.
+  windows-self-upgrade.md: Defines synchronous Windows executable replacement, verification, rollback, and cleanup.
 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.
+  interactive-init-manifest.md: Accepted manifest and interactive initialization decision for runx init.
   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.
+  windows-self-upgrade.md: Accepted design for synchronous and recoverable Windows native self-upgrade.
 tags:
   - decisions
 keywords:
   - runx
   - decisions
+  - runx init
+  - scripts directory
   - mirror push
+  - windows self-upgrade
 flags: []
 status: stable
 ---

package/docs/decisions/interactive-init-manifest.md

@@ -0,0 +1,187 @@
+---
+name: RunX Interactive Init Manifest
+purpose: Preserve the accepted manifest structure and initialization behavior for runx init.
+description: Defines the Semantic Versioning manifest field, mandatory public group, configurable scripts directory, and empty interactive initialization contract.
+created: 2026-07-14
+flags:
+  - accepted
+  - decision
+tags:
+  - decisions
+  - cli
+  - manifest
+keywords:
+  - runx init
+  - runx.yaml
+  - semantic versioning
+  - public group
+  - scripts directory
+owner: runx-decisions
+---
+
+# RunX Interactive Init Manifest
+
+## Status
+
+Accepted by the project owner on 2026-07-14.
+
+## Context
+
+RunX needs an interactive `runx init` command so a project can establish its
+single `runx.yaml` command catalog before any commands exist. The repository
+already defines groups and documented commands as the core catalog model. The
+initializer must preserve that model without inventing framework-specific
+commands, creating a second configuration file, or forcing a placeholder
+command into the catalog.
+
+Projects may later store executable Bash, PowerShell, or other script files in
+a manifest-owned scripts directory. The manifest must identify that directory
+so agents and developers use one predictable location when adding scripts.
+
+## Decision
+
+### Initialized manifest
+
+`runx init` creates this shape, using the current directory name as the default
+project name:
+
+```yaml
+version: "1.0.0"
+
+project:
+  name: my-project
+
+scripts:
+  directory: scripts
+
+groups:
+  public:
+    summary: Default public project commands.
+
+commands: []
+```
+
+The initializer creates only `runx.yaml`. It does not create an empty `scripts`
+directory because the directory is created when the first script is written.
+
+### Manifest version
+
+- `version` is a valid Semantic Versioning 2.0.0 string with a
+  `MAJOR.MINOR.PATCH` core and optional prerelease or build metadata.
+- The first supported manifest contract is `"1.0.0"`.
+- RunX accepts manifest versions whose major version is `1` and rejects
+  unsupported major versions.
+- Numeric `version: 1` manifests are invalid. RunX is still under development
+  and has no deployed numeric-version compatibility requirement.
+- Future backward-incompatible manifest changes require a major version change.
+
+### Scripts directory
+
+- Every manifest contains `scripts.directory`; it configures the project script
+  location.
+- The initializer's default value is `scripts` relative to the directory
+  containing `runx.yaml`.
+- The path must remain inside the manifest directory and cannot escape through
+  an absolute path or parent traversal.
+- Existing and future command strings may invoke any suitable script type from
+  this directory; RunX remains language-agnostic.
+- The manifest command entry is the script descriptor. No sidecar RunX config
+  or per-script descriptor file is introduced.
+
+### Groups and commands
+
+- `groups` is a first-class catalog concept.
+- Every manifest contains a `public` group, analogous to PostgreSQL's default
+  `public` schema.
+- Additional groups may organize commands by domain or responsibility.
+- Every command explicitly names an existing group. Missing and unknown group
+  references are invalid.
+- Authoring workflows place a new command in `public` unless the user requests
+  or selects another group, but the stored command still contains
+  `group: public` explicitly.
+- An initialized catalog may contain no commands. Once present, every command
+  retains the required `uid`, `id`, `group`, `summary`, `description`, and
+  executable `command` fields.
+
+### Interactive behavior
+
+- `runx init` is a first-class Citty command that never requires an existing
+  manifest.
+- The interactive flow collects or confirms the project name and scripts
+  directory, renders a YAML preview, and requests confirmation before writing.
+- The interface should use a polished terminal presentation with clear
+  progress, validation, cancellation, and success states.
+- No framework-specific templates or automatic package-script imports are
+  offered.
+- An existing `runx.yaml` is never overwritten without explicit confirmation.
+- Cancellation leaves no partial file, and non-interactive invocation fails
+  clearly instead of hanging.
+
+## Alternatives Considered
+
+### Require a first command during initialization
+
+Rejected. Initialization establishes the catalog so commands can be added later
+from explicit developer requests. A fabricated starter command would make the
+manifest less truthful.
+
+### Offer framework-specific templates or scan package scripts
+
+Rejected. RunX is language-agnostic, and the project owner explicitly excluded
+framework-specific starter templates from the initializer.
+
+### Keep numeric `version: 1` compatibility
+
+Rejected. RunX has not been used outside development, so there is no legacy
+manifest population to migrate. Supporting two version shapes would add
+unnecessary schema and documentation complexity.
+
+### Store the scripts directory in a separate config file
+
+Rejected. `runx.yaml` remains the single source of truth for the command
+catalog and its script location.
+
+### Create the scripts directory eagerly
+
+Rejected for initialization. An empty directory is not useful to the catalog
+and is not preserved by Git. The directory should be created with the first
+real script.
+
+## Consequences
+
+- The manifest TypeBox schema must accept only supported Semantic Versioning
+  strings, require `scripts.directory`, and allow an empty command array.
+- Semantic validation must require the `public` group and continue requiring
+  every command to reference a declared group.
+- Script-directory validation must enforce a relative path within the manifest
+  root.
+- Existing fixtures and documentation using numeric `version: 1` must move to
+  `version: "1.0.0"` and include `public`.
+- Listing and checking an empty initialized manifest must succeed without
+  attempting command execution.
+- The initializer needs an isolated prompt boundary so interactive behavior can
+  be tested without depending on a real terminal.
+- The bundled agent skill update is intentionally deferred to the process that
+  delivers the complete agent-integration request.
+
+## Reversal Or Revisit Conditions
+
+Revisit this decision only if real-world manifest migration requires a
+compatibility policy, the command catalog needs multiple script roots, or a
+future major manifest version replaces the group model. Such a change must be
+recorded as a new decision and reflected in the manifest's major version.
+
+## Follow-up Work
+
+- Implement the manifest schema and semantic validation changes.
+- Implement and test the interactive `runx init` command.
+- Update canonical CLI and manifest documentation.
+- Update XDocs descriptors for every changed module or companion document.
+- Leave agent-skill content changes for the complete agent-integration work.
+
+## References
+
+- [Alpha boundaries](./alpha-boundaries.md)
+- [Alpha command-catalog requirements](../requirements/alpha-command-catalog.md)
+- [CLI architecture](../architecture/cli-architecture.md)
+- [GitHub issue #10](https://github.com/CGuiho/runx/issues/10)

package/docs/decisions/windows-self-upgrade.md

@@ -0,0 +1,98 @@
+---
+name: RunX Windows Self-Upgrade
+purpose: Define synchronous and recoverable replacement of the running RunX executable on Windows.
+description: Records the accepted Windows executable-swap, verification, rollback, cleanup, testing, and patch-release behavior.
+created: 2026-07-14
+flags:
+  - accepted
+  - implemented
+tags:
+  - decisions
+  - cli
+  - windows
+keywords:
+  - runx upgrade
+  - windows self-upgrade
+  - executable replacement
+  - rollback
+owner: runx-decisions
+---
+
+# RunX Windows Self-Upgrade
+
+## Context
+
+RunX 0.2.5 downloads a Windows update to `runx.exe.new`, starts a detached
+`cmd.exe` process, reports `scheduled: true`, and exits without confirming that
+the installed executable was replaced. The detached move can fail silently and
+leave later invocations on the previous version.
+
+Windows permits the running executable to be renamed while its image remains
+mapped. A new executable can then be installed at the original path before the
+current RunX process exits. Only deletion of the renamed, still-running image
+must wait until the process releases it.
+
+## Decision
+
+`runx upgrade` on Windows will complete the executable swap synchronously:
+
+1. Download the selected release asset to `runx.exe.new`.
+2. Remove any stale backup that is not in use.
+3. Rename the installed `runx.exe` to `runx.exe.old`.
+4. Rename `runx.exe.new` to the canonical installed path.
+5. Execute the newly installed path with `--version` and require the expected
+   target version and a zero exit code.
+6. If installation or verification fails, remove the failed replacement and
+   restore `runx.exe.old` to the canonical path.
+7. After successful verification, delete the backup immediately when possible;
+   when Windows still locks the running image, schedule only that backup cleanup
+   for after the current process exits.
+
+The upgrade result reports `scheduled: false`. Deferred deletion of the old,
+renamed image is cleanup and does not defer or weaken successful replacement.
+
+## Error Handling
+
+- A replacement failure must throw a concise `RunXError` and produce a non-zero
+  CLI exit code.
+- Rollback must be attempted whenever the installed executable was renamed but
+  the new executable was not verified.
+- If rollback also fails, the error must report both the replacement and
+  recovery failures and identify the affected installed path.
+- The `.new` file must be removed after failures and must not remain after a
+  successful rename.
+- A locked stale `.old` file must stop a new upgrade before the current
+  executable is modified.
+
+## Testing
+
+Automated coverage must prove that:
+
+- the configured Windows self path contains the downloaded replacement before
+  `upgradeSelf()` resolves;
+- successful Windows upgrades report `scheduled: false`;
+- no `.new` file remains after success;
+- a failed replacement restores the original executable;
+- the equal-version no-op remains unchanged;
+- `runx -h` continues to work outside a manifest directory.
+
+The full release gate is `bun run typecheck`, `bun test`, `bun run build`,
+`bun run binary`, `bun run binaries`, and strict XDocs validation.
+
+## Release
+
+After implementation and validation, use Mirror to plan and apply the next
+patch. Update the changelog before applying the Mirror-managed version. Do not
+hand-edit the package version or create the release tag manually.
+
+## Acceptance Criteria
+
+- When `runx upgrade` succeeds, the executable at the installed path is already
+  the target release.
+- A same-terminal or new-terminal invocation immediately reports the target
+  version.
+- The command never reports `scheduled: true` for upgrade replacement.
+- Replacement and verification failures are visible and recover the old binary.
+- Temporary update files are cleaned up safely.
+- Issue #9 has automated Windows regression coverage and issue #1 remains
+  covered by the Citty help tests.

package/docs/plans/interactive-init-manifest.md

@@ -0,0 +1,177 @@
+---
+name: RunX Interactive Init Manifest Plan
+purpose: Sequence implementation of the accepted runx init workflow and manifest contract.
+description: Defines the schema, interactive terminal UI, validation, documentation, and pull-request work for RunX initialization.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - plans
+  - cli
+  - manifest
+keywords:
+  - runx init
+  - runx.yaml
+  - semantic versioning
+  - public group
+  - scripts directory
+owner: runx-plans
+---
+
+# RunX Interactive Init Manifest Plan
+
+## Sources
+
+- [Interactive Init Manifest Decision](../decisions/interactive-init-manifest.md)
+- [Alpha Command Catalog Requirements](../requirements/alpha-command-catalog.md)
+- [CLI Architecture](../architecture/cli-architecture.md)
+- GitHub issue [#10](https://github.com/CGuiho/runx/issues/10)
+
+## Unit 1: Establish the Manifest Contract
+
+- Goal: Make the current manifest validator enforce the accepted `1.x.x`
+  Semantic Versioning, scripts directory, public group, and empty catalog
+  contract.
+- Owner: `C:\GUIHO\runx`.
+- Dependencies: Accepted interactive-init decision.
+- Files:
+  - `source/manifest.ts`
+  - `source/types.ts` when TypeScript inference exposes the new manifest shape
+  - `source/guiho-runx.spec.ts`
+  - `source/cli.spec.ts` fixtures that construct manifests
+- Behavior:
+  - Replace numeric `version: 1` with a Semantic Versioning string and accept
+    only supported major version `1`.
+  - Require `scripts.directory` as a non-empty relative path inside the
+    manifest root.
+  - Require the `public` group with a non-empty summary.
+  - Permit an empty `commands` array while keeping every populated command
+    explicit about its existing group.
+  - Preserve strict unknown-property rejection and existing selector and
+    execution safety behavior.
+- Data, auth, permissions, and cache: Local YAML contract only. No remote data,
+  authentication, authorization, cache, or secret changes.
+- Tests:
+  - Accept `"1.0.0"` and prerelease/build SemVer forms with major `1`.
+  - Reject numeric versions, malformed SemVer, unsupported major versions,
+    missing scripts configuration, escaping script paths, missing public, and
+    commands that name unknown groups.
+  - Prove empty initialized catalogs check and list without execution.
+- Acceptance: `readManifest()` returns a strict manifest with `scripts` and
+  `public`, and invalid configurations fail with actionable `RunXError`
+  messages.
+- Stop conditions: Stop if SemVer support would require a migration policy,
+  scripts need more than one root, or the change weakens command safety.
+
+## Unit 2: Implement the Interactive Initializer
+
+- Goal: Add a beautiful, cancellable `runx init` Citty command that creates a
+  valid empty `runx.yaml` without ever executing a configured command.
+- Dependencies: Unit 1.
+- Files:
+  - `package.json`
+  - `bun.lock`
+  - `source/init.ts`
+  - `source/init.spec.ts`
+  - `source/cli.ts`
+  - `source/cli.spec.ts`
+  - `source/help.ts`
+- Behavior:
+  - Use a dependency-free Bun terminal prompt adapter with clear visual states,
+    so the initializer remains portable across native and Windows builds.
+  - Isolate prompt interactions behind an injected interface so prompt flow and
+    filesystem behavior can be tested without a real terminal.
+  - In an interactive terminal, welcome the user, collect a project name
+    defaulting to the selected directory name, collect a scripts directory
+    defaulting to `scripts`, preview the exact YAML, and request confirmation.
+  - Write only `runx.yaml`; create `scripts/` later when the first real script
+    is added.
+  - Detect an existing `runx.yaml` in the selected directory and require a
+    second explicit overwrite confirmation.
+  - Use an atomic temporary-file write and leave no partial manifest on
+    cancellation or failure.
+  - Fail clearly outside an interactive terminal; do not hang and do not emit
+    interactive ANSI frames into JSON output.
+  - Accept `--cwd` as the target directory, reject `--file` because the
+    initializer always creates `runx.yaml`, and reject `--format json` because
+    initialization is an interactive terminal workflow.
+  - Register `init` as a first-class Citty command, include it in help/home and
+    command-tree output, and reserve the word from selector shorthand.
+- Tests:
+  - Successful creation exactly matches the accepted YAML shape.
+  - Cancellation leaves no file.
+  - Existing-file rejection and confirmed overwrite are safe.
+  - Default and custom project/scripts values validate.
+  - CLI help works outside a manifest and non-interactive invocation exits with
+    a clear error.
+  - `--file` and `--format json` report clear unsupported-option errors without
+    creating files.
+  - The generated file passes `runx check` and `runx list`.
+- Acceptance: `runx init` produces a polished, deterministic creation flow and
+  never executes a manifest command.
+- Stop conditions: Stop if the terminal prompt adapter fails Bun tests or native
+  compile, if Citty cannot route `init` without conflicting with selector shorthand, or
+  if atomic replacement is not portable on Windows.
+
+## Unit 3: Align Canonical Documentation and XDocs
+
+- Goal: Make public and structured documentation accurately describe the new
+  manifest and initializer without modifying the bundled agent skill.
+- Dependencies: Units 1 and 2.
+- Files:
+  - `README.md`
+  - `DOCS.md`
+  - `source/source.xdocs.md`
+  - `runx.xdocs.md` when its package description needs updating
+  - `docs/plans/plans.xdocs.md`
+- Behavior:
+  - Document `runx init`, Semantic Versioning, `scripts.directory`, mandatory
+    `public`, empty catalog initialization, and command-to-script examples.
+  - Keep the bundled `skills/guiho-s-runx/SKILL.md` unchanged; its update belongs
+    to the separate agent-integration delivery requested by the project owner.
+  - Update the source descriptor for the initializer module and changed CLI /
+    manifest responsibilities.
+- Checks:
+  - `xdocs meta docs\plans --documents --strict --format json`
+  - `xdocs meta source --strict --format json`
+  - `xdocs tree`
+- Acceptance: User-facing docs, XDocs metadata, and implementation agree.
+- Stop conditions: Stop if XDocs requires unrelated coverage cleanup; validate
+  only the affected subtrees and report wider pre-existing findings.
+
+## Unit 4: Validate, Review, Commit, Push, and Open a Pull Request
+
+- Goal: Produce evidence that the implementation satisfies the accepted
+  decision, then deliver it as a draft pull request from `codex/runx-init`.
+- Dependencies: Units 1 through 3.
+- Checks:
+  - `bun run typecheck`
+  - `bun test`
+  - `bun run build`
+  - `bun run binary`
+  - `xdocs meta docs\plans --documents --strict --format json`
+  - `xdocs meta source --strict --format json`
+  - `xdocs tree`
+  - `git diff --check`
+- Delivery:
+  - Write an implementation review and validation report with XDocs metadata.
+  - Commit coherent code, tests, documentation, and validation artifacts.
+  - Push only the feature branch and create a draft pull request that links
+    issue #10 and states that agent-skill automation is intentionally tracked
+    separately in issue #11.
+- Acceptance: All applicable checks pass, the worktree is clean, the branch is
+  pushed, and the draft pull request is reviewable without a release, tag, or
+  package publication.
+- Stop conditions: Stop before push/PR if validation fails, unrelated changes
+  appear, GitHub rejects authentication, or the branch diverges unexpectedly.
+
+## TODO Alignment
+
+This is one approved, focused package implementation and does not need a new
+long-running TODO entry. The decision, plan, review, and validation records are
+the durable delivery trail.
+
+## First Executable Unit
+
+Unit 1: update `source/manifest.ts` and its fixtures/tests to enforce the
+accepted manifest contract.