mesilov · mesilov · Sep 3, 2026 · Sep 3, 2026 · Sep 3, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [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/<issue>-<slug>` checkout branched off `origin/<base>`, 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.
@@ -24,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/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
@@ -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
@@ -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
@@ -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
@@ -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`.