From b3276bdafd5746e6b8c7dace7b94d2e8b7fd56a6 Mon Sep 17 00:00:00 2001 From: mesilov Date: Thu, 3 Sep 2026 12:12:48 +0600 Subject: [PATCH 1/2] docs: align document-cli-option-reference OpenSpec and changelog with CLI work Address the maintainer-policy gaps raised by Codex on #51: - Update the active `document-cli-option-reference` OpenSpec change so its proposal, design, tasks, and spec cover the review refinements (`--json` scope, `--silent` version) and the generator hardening (single-sourced command list, clear error on a missing optionAllowlist entry). - Add the missing `[Unreleased]` CHANGELOG entries for the generator hardening and the README CLI-reference corrections. Follow-up to Codex review on #51. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01EanqRNh4A3XoojYr7MNFvd --- CHANGELOG.md | 6 ++++++ .../changes/document-cli-option-reference/design.md | 7 ++++++- .../document-cli-option-reference/proposal.md | 10 ++++++---- .../specs/cli-documentation/spec.md | 11 +++++++++++ .../changes/document-cli-option-reference/tasks.md | 13 ++++++++++++- 5 files changed, 41 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c1bdf7..cc72724 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed +- CLI reference generator (`update-cli-reference.sh`) now single-sources the command list from the shell `PROJECT_COMMANDS` array (the Node generator receives it as arguments, with no duplicate hardcoded list) and fails with a clear, actionable message when a command has no `optionAllowlist` entry instead of crashing; the maintainer "Изменения CLI" note is simplified to match. + +### Fixed +- README CLI reference: scoped `--json` to the RARUS Echo commands (it is not available on Symfony's built-in `list`/`help`), added the `--silent` global option, and qualified `--silent` as requiring Symfony Console ≥ 7.2 given the `symfony/console: ^6.4 || ^7.0 || 8.0.*` constraint. + ## [0.4.0] - 2026-09-03 ### Added diff --git a/openspec/changes/document-cli-option-reference/design.md b/openspec/changes/document-cli-option-reference/design.md index 988d991..7b12b19 100644 --- a/openspec/changes/document-cli-option-reference/design.md +++ b/openspec/changes/document-cli-option-reference/design.md @@ -13,7 +13,12 @@ The command definitions in `src/Infrastructure/Console/Command/` are the source - Document the full option set in the README as a structured "Справочник команд и опций" subsection: a global-options table (`--json` plus the common Symfony Console globals) and per-command argument/option tables for `queue`, `submit`, `status`, `transcript`, mirroring the option set enforced in `cli.md`. - Record the alignment obligation in the maintainer skill (`SKILL.md`): a bullet in "Правила реализации" and a dedicated "Изменения CLI" subsection describing the two surfaces, how to regenerate the skill reference, and that the README must be updated by hand. The `.claude/` and `.codex/` skill copies are symlinks to the `.agents/` file, so a single edit updates all three. -- Do not regenerate `cli.md`; it already matches the current command definitions, and no CLI behavior changes here. +- Do not change `cli.md` output; it already matches the current command definitions and stays byte-identical. +- Qualify the README global options by scope and version: `--json` is added by `AbstractEchoCommand` and is only present on the four Echo commands (not Symfony's built-in `list`/`help`); `--silent` was introduced in Symfony Console 7.2, but `composer.json` allows `symfony/console: ^6.4 || ^7.0 || 8.0.*`, so library consumers on older Console will not have it. +- Harden `update-cli-reference.sh` so the reference-generation process is not fragile: + - Pass the shell `PROJECT_COMMANDS` array into the Node generator as arguments and derive `projectCommands` from them, removing the duplicate hardcoded list so the two cannot drift apart. + - When a command in `PROJECT_COMMANDS` has no `optionAllowlist` entry, fail with a clear, actionable message instead of aborting on `undefined is not iterable`. + This keeps the generator's output identical while making the manual steps captured in the maintainer skill smaller and safer. ## Validation diff --git a/openspec/changes/document-cli-option-reference/proposal.md b/openspec/changes/document-cli-option-reference/proposal.md index 117a2ce..d0eca3f 100644 --- a/openspec/changes/document-cli-option-reference/proposal.md +++ b/openspec/changes/document-cli-option-reference/proposal.md @@ -6,7 +6,9 @@ The README `## CLI` section describes usage but does not list every command key - Add a complete "Справочник команд и опций" reference to the README `## CLI` section: global options plus per-command arguments and options (`queue`, `submit`, `status`, `transcript`) with value requirements and defaults. - Add a maintainer-workflow rule: when CLI commands or options change, align documentation in both places — the transcription skill CLI reference (regenerated via `update-cli-reference.sh`, drift-checked by `make lint-agent-plugins`) and the README `## CLI` section. -- Verify documentation and standard project checks, including the CLI reference drift check. +- Qualify the README global-options table by scope and version: `--json` is an Echo-command option (not available on Symfony's built-in `list`/`help`), and `--silent` requires Symfony Console ≥ 7.2 while `composer.json` still allows older Console versions. +- Harden `update-cli-reference.sh` so the maintainer process is not fragile: single-source the command list from the shell `PROJECT_COMMANDS` array (the Node generator receives it as arguments instead of duplicating it), and fail with a clear message when a command has no `optionAllowlist` entry instead of crashing. +- Verify documentation and standard project checks, including the CLI reference drift check (regenerated `cli.md` must stay byte-identical). ## Capabilities @@ -17,6 +19,6 @@ The README `## CLI` section describes usage but does not list every command key ## Impact -- Affected files: `README.md`, `.agents/skills/rarus-echo-maintainer/SKILL.md` (mirrored via symlinks to `.claude/` and `.codex/`). -- Runtime SDK impact: none (documentation and maintainer process only). -- No CLI behavior changes; the generated `cli.md` already matches the current command definitions and is left untouched. +- Affected files: `README.md`, `.agents/skills/rarus-echo-maintainer/SKILL.md` (mirrored via symlinks to `.claude/` and `.codex/`), `.agent-plugins/rarus-echo-transcription/scripts/update-cli-reference.sh`. +- Runtime SDK impact: none (documentation, maintainer process, and reference-generation tooling only). +- No CLI behavior changes; the generated `cli.md` stays byte-identical to the current command definitions. diff --git a/openspec/changes/document-cli-option-reference/specs/cli-documentation/spec.md b/openspec/changes/document-cli-option-reference/specs/cli-documentation/spec.md index 6f1a003..7862c83 100644 --- a/openspec/changes/document-cli-option-reference/specs/cli-documentation/spec.md +++ b/openspec/changes/document-cli-option-reference/specs/cli-documentation/spec.md @@ -15,3 +15,14 @@ The maintainer workflow SHALL require that any change to CLI commands or options - **WHEN** the maintainer adds, removes, or changes a CLI command or option - **THEN** the maintainer skill SHALL instruct regenerating the transcription skill CLI reference via `update-cli-reference.sh` (drift-checked by `make lint-agent-plugins`) - **AND** the maintainer skill SHALL instruct updating the README `## CLI` section by hand, since it is not covered by drift validation + +### Requirement: CLI Reference Generator Is Resilient to Maintenance Mistakes +The `update-cli-reference.sh` generator SHALL derive its command list from a single source and SHALL fail with a clear message rather than crash when a command lacks an option allowlist entry. + +#### Scenario: Command list stays single-sourced +- **WHEN** the generator runs +- **THEN** it SHALL use the shell `PROJECT_COMMANDS` array as the only command list, passed into the Node generator, with no duplicate hardcoded command array + +#### Scenario: Command missing an allowlist entry +- **WHEN** a command is present in `PROJECT_COMMANDS` but has no `optionAllowlist` entry +- **THEN** the generator SHALL fail with an actionable message naming the command instead of aborting with an uncaught runtime error diff --git a/openspec/changes/document-cli-option-reference/tasks.md b/openspec/changes/document-cli-option-reference/tasks.md index b7e353b..37fef32 100644 --- a/openspec/changes/document-cli-option-reference/tasks.md +++ b/openspec/changes/document-cli-option-reference/tasks.md @@ -3,7 +3,18 @@ - [x] 1.1 Add a complete "Справочник команд и опций" reference (global options plus per-command arguments and options) to the README `## CLI` section. - [x] 1.2 Add the CLI-alignment rule to the maintainer skill: a bullet in "Правила реализации" and an "Изменения CLI" subsection. -## 2. Verification +## 2. Review refinements + +- [x] 2.1 Scope `--json` to the Echo commands and add `--silent` to the README global-options table. +- [x] 2.2 Qualify `--silent` with its minimum Symfony Console version (7.2) given the `composer.json` constraint. + +## 3. Generator hardening + +- [x] 3.1 Single-source the command list in `update-cli-reference.sh`: pass `PROJECT_COMMANDS` into the Node generator and remove the duplicate hardcoded array. +- [x] 3.2 Fail with a clear message when a command has no `optionAllowlist` entry instead of crashing. +- [x] 3.3 Simplify the maintainer "Изменения CLI" note to the two remaining lists (`PROJECT_COMMANDS` + `optionAllowlist`). + +## 4. Verification - [x] 2.1 Run `make lint-openspec`. - [x] 2.2 Run `git diff --check`. From eb35aae6083fece489c5a02e8d58d9392878b5fa Mon Sep 17 00:00:00 2001 From: mesilov Date: Thu, 3 Sep 2026 12:19:08 +0600 Subject: [PATCH 2/2] docs: fold CLI-reference changes into 0.4.0 changelog and scope --json in spec - CHANGELOG: move the CLI-reference generator hardening and README-reference corrections from [Unreleased] into the not-yet-released [0.4.0] section (generator hardening under Changed; --json/--silent accuracy folded into the existing CLI-reference Added entry). [Unreleased] is empty again. - OpenSpec spec: align the "README Documents the Complete CLI Option Reference" requirement and scenario with the scoped --json (Echo commands only, not Symfony's built-in list/help), matching the proposal and implementation. Follow-up to Codex review on #52. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01EanqRNh4A3XoojYr7MNFvd --- CHANGELOG.md | 9 ++------- .../specs/cli-documentation/spec.md | 4 ++-- 2 files changed, 4 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cc72724..8a7249e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,16 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -### Changed -- CLI reference generator (`update-cli-reference.sh`) now single-sources the command list from the shell `PROJECT_COMMANDS` array (the Node generator receives it as arguments, with no duplicate hardcoded list) and fails with a clear, actionable message when a command has no `optionAllowlist` entry instead of crashing; the maintainer "Изменения CLI" note is simplified to match. - -### Fixed -- README CLI reference: scoped `--json` to the RARUS Echo commands (it is not available on Symfony's built-in `list`/`help`), added the `--silent` global option, and qualified `--silent` as requiring Symfony Console ≥ 7.2 given the `symfony/console: ^6.4 || ^7.0 || 8.0.*` constraint. - ## [0.4.0] - 2026-09-03 ### Added -- Complete CLI key reference in the README `## CLI` section ("Справочник команд и опций"): global options plus per-command arguments and options for `queue`, `submit`, `status`, and `transcript`, with value requirements and defaults. +- Complete CLI key reference in the README `## CLI` section ("Справочник команд и опций"): global options (with `--json` scoped to the Echo commands and `--silent` noted as requiring Symfony Console ≥ 7.2) plus per-command arguments and options for `queue`, `submit`, `status`, and `transcript`, with value requirements and defaults. - Parallel per-issue worktree tooling (`make worktree-new`, `worktree-remove`, `worktree-list` backed by a maintainer-skill script `.agents/skills/rarus-echo-maintainer/scripts/worktree.sh`): creates a git-ignored `.worktree/-` checkout branched off `origin/`, provisioned with a symlinked `.env.local` and an independent clone-copied `vendor/`, and removes it while keeping the branch. - Cross-agent `rarus-echo-transcription` plugin with a shared transcription skill, marketplace entries, and CLI reference drift validation for agent sessions. - CLI `submit --wait` can now submit audio and poll until terminal transcript results, including JSON, raw transcript, and output-file modes while keeping progress on stderr. @@ -30,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - Maintainer workflow now requires aligning CLI documentation in both places on any CLI change: the generated transcription-skill CLI reference (`update-cli-reference.sh`, drift-checked by `make lint-agent-plugins`) and the README `## CLI` section. +- CLI reference generator (`update-cli-reference.sh`) single-sources the command list from the shell `PROJECT_COMMANDS` array (the Node generator receives it as arguments, with no duplicate hardcoded list) and fails with a clear, actionable message when a command has no `optionAllowlist` entry instead of crashing. - CLI Docker image now builds on the official `php:8.4-cli-alpine` runtime base instead of `php:8.4-cli-bookworm`, reducing published image size while preserving `rarus-echo` behavior, the `curl`/`fileinfo`/`mbstring` extensions, PSR-17/PSR-18 discovery smoke checks, and multi-arch `linux/amd64`/`linux/arm64` publication. - Renamed the local development/CI container from `php-cli` to `dev-php` (directory `docker/dev-php/`, Compose service `dev-php`) so its name reflects its purpose and is distinct from the published `rarus-echo-cli` image; the shell helpers are now `make dev-php-bash` and `make dev-php-root`. - README now displays CI status badges for the Lint and Tests GitHub Actions workflows. diff --git a/openspec/changes/document-cli-option-reference/specs/cli-documentation/spec.md b/openspec/changes/document-cli-option-reference/specs/cli-documentation/spec.md index 7862c83..1ef223c 100644 --- a/openspec/changes/document-cli-option-reference/specs/cli-documentation/spec.md +++ b/openspec/changes/document-cli-option-reference/specs/cli-documentation/spec.md @@ -1,11 +1,11 @@ ## ADDED Requirements ### Requirement: README Documents the Complete CLI Option Reference -The README `## CLI` section SHALL contain a structured reference listing every CLI key: the global options available on all commands, and the arguments and options of each command (`queue`, `submit`, `status`, `transcript`) with their value requirements and defaults. +The README `## CLI` section SHALL contain a structured reference listing every CLI key: the global options available on the RARUS Echo commands (the Echo-added `--json` plus the Symfony Console globals), and the arguments and options of each command (`queue`, `submit`, `status`, `transcript`) with their value requirements and defaults. #### Scenario: User looks up a CLI key - **WHEN** a user reads the README CLI reference -- **THEN** it SHALL list the global options (including `--json`) +- **THEN** it SHALL list the global options, including `--json` scoped to the Echo commands (not Symfony's built-in `list`/`help`) and the Symfony Console globals - **AND** it SHALL list, per command, each argument and option with whether the option takes a value and its default where one exists ### Requirement: Maintainer Workflow Aligns CLI Documentation on CLI Changes