feat(cli)!: require canonical config discovery - #619
Merged
Conversation
LukeMathWalker
force-pushed
the
amp/canonical-config-discovery
branch
from
August 28, 2026 17:32
7fc9cbb to
4ff42c5
Compare
luca-iachini
force-pushed
the
amp/canonical-config-discovery
branch
2 times, most recently
from
September 1, 2026 16:29
7ea2199 to
2135a80
Compare
LukeMathWalker
force-pushed
the
amp/canonical-config-discovery
branch
from
September 1, 2026 16:56
2135a80 to
747da4f
Compare
luca-iachini
approved these changes
Sep 1, 2026
github-merge-queue
Bot
removed this pull request from the merge queue because a pull request earlier in the stack was removed
Sep 2, 2026
luca-iachini
added a commit
that referenced
this pull request
Sep 2, 2026
## Why `firma sidecar` bound `--config` to `FIRMA_SIDECAR_CONFIG_FILE`, `authority` bound no env, and the stack-inspection commands bound `FIRMA_CONFIG` — all selecting the same unified `firma.toml`. The `FIRMA_SIDECAR_CONFIG_FILE` name was also overloaded as a `firma run` autostart sidecar-template source, so setting it for one purpose silently affected the other. This unifies unified-config selection under one canonical flag and env. ## What Changed - Add a global `-c` / `--config` bound to `FIRMA_CONFIG` on the top-level `firma` command (accepted before or after any subcommand); `main.rs` threads the resolved path into each consumer. - Remove the per-command unified-config `--config` from `control`, `doctor`, `monitor`, `sidecar` (serve/start/stop), and `authority`. `firma run --config` keeps working via the global (it was already the unified-config selector). - Fully retire `FIRMA_SIDECAR_CONFIG_FILE`, including the `firma run` autostart template fallback (`TemplateSource::Env` removed; selection is now `--sidecar-config` → `./firma_sidecar.toml` → synthesized minimal). - Update docs (cli.md, README, manage-the-stack, firma-run, examples) and extend the `--help` contract test to sidecar/authority. ## Risks / Notes - **Breaking (`feat!`)**: `FIRMA_SIDECAR_CONFIG_FILE` is removed. Migration: export `FIRMA_CONFIG` to select the unified `firma.toml`; use `--sidecar-config <path>` (or `./firma_sidecar.toml`) for a `firma run` autostart template. - Config resolution precedence and fail-closed behavior are unchanged (still owned by `firma-config-loader` `ConfigResolver`); the path — not a pre-resolved config — is threaded because `doctor` reports resolution, `run` may scaffold, and `sidecar start` uses a different resolver. - As a clap global, `--config` is also accepted (and ignored) by commands that do not consume the unified config (`token`, `policy`, internal `__*`). - Design/rationale: `docs/architecture/config-env-unification-plan.md`. - Stacked on top of #619 (`amp/canonical-config-discovery`); base retargets to `main` once that merges. ## AI Assistance Claude Opus 4.8 (claude-opus-4-8).
LukeMathWalker
force-pushed
the
amp/canonical-config-discovery
branch
from
September 3, 2026 07:08
fa500cb to
1868504
Compare
LukeMathWalker
pushed a commit
that referenced
this pull request
Sep 3, 2026
## Why `firma sidecar` bound `--config` to `FIRMA_SIDECAR_CONFIG_FILE`, `authority` bound no env, and the stack-inspection commands bound `FIRMA_CONFIG` — all selecting the same unified `firma.toml`. The `FIRMA_SIDECAR_CONFIG_FILE` name was also overloaded as a `firma run` autostart sidecar-template source, so setting it for one purpose silently affected the other. This unifies unified-config selection under one canonical flag and env. ## What Changed - Add a global `-c` / `--config` bound to `FIRMA_CONFIG` on the top-level `firma` command (accepted before or after any subcommand); `main.rs` threads the resolved path into each consumer. - Remove the per-command unified-config `--config` from `control`, `doctor`, `monitor`, `sidecar` (serve/start/stop), and `authority`. `firma run --config` keeps working via the global (it was already the unified-config selector). - Fully retire `FIRMA_SIDECAR_CONFIG_FILE`, including the `firma run` autostart template fallback (`TemplateSource::Env` removed; selection is now `--sidecar-config` → `./firma_sidecar.toml` → synthesized minimal). - Update docs (cli.md, README, manage-the-stack, firma-run, examples) and extend the `--help` contract test to sidecar/authority. ## Risks / Notes - **Breaking (`feat!`)**: `FIRMA_SIDECAR_CONFIG_FILE` is removed. Migration: export `FIRMA_CONFIG` to select the unified `firma.toml`; use `--sidecar-config <path>` (or `./firma_sidecar.toml`) for a `firma run` autostart template. - Config resolution precedence and fail-closed behavior are unchanged (still owned by `firma-config-loader` `ConfigResolver`); the path — not a pre-resolved config — is threaded because `doctor` reports resolution, `run` may scaffold, and `sidecar start` uses a different resolver. - As a clap global, `--config` is also accepted (and ignored) by commands that do not consume the unified config (`token`, `policy`, internal `__*`). - Design/rationale: `docs/architecture/config-env-unification-plan.md`. - Stacked on top of #619 (`amp/canonical-config-discovery`); base retargets to `main` once that merges. ## AI Assistance Claude Opus 4.8 (claude-opus-4-8).
Move config_commands_expose_only_canonical_environment_variable out of the doctor integration test into cli_help, alongside the other --help surface assertions. doctor keeps only its doctor-specific JSON-output test.
The monitor flags table said --config does not participate in resolution and listed no env var; control's section omitted it entirely. Both now bind FIRMA_CONFIG and select the config used for audit-log and policy discovery, failing closed on an unreadable file. Mirror the doctor guide's table.
## Why `firma sidecar` bound `--config` to `FIRMA_SIDECAR_CONFIG_FILE`, `authority` bound no env, and the stack-inspection commands bound `FIRMA_CONFIG` — all selecting the same unified `firma.toml`. The `FIRMA_SIDECAR_CONFIG_FILE` name was also overloaded as a `firma run` autostart sidecar-template source, so setting it for one purpose silently affected the other. This unifies unified-config selection under one canonical flag and env. ## What Changed - Add a global `-c` / `--config` bound to `FIRMA_CONFIG` on the top-level `firma` command (accepted before or after any subcommand); `main.rs` threads the resolved path into each consumer. - Remove the per-command unified-config `--config` from `control`, `doctor`, `monitor`, `sidecar` (serve/start/stop), and `authority`. `firma run --config` keeps working via the global (it was already the unified-config selector). - Fully retire `FIRMA_SIDECAR_CONFIG_FILE`, including the `firma run` autostart template fallback (`TemplateSource::Env` removed; selection is now `--sidecar-config` → `./firma_sidecar.toml` → synthesized minimal). - Update docs (cli.md, README, manage-the-stack, firma-run, examples) and extend the `--help` contract test to sidecar/authority. ## Risks / Notes - **Breaking (`feat!`)**: `FIRMA_SIDECAR_CONFIG_FILE` is removed. Migration: export `FIRMA_CONFIG` to select the unified `firma.toml`; use `--sidecar-config <path>` (or `./firma_sidecar.toml`) for a `firma run` autostart template. - Config resolution precedence and fail-closed behavior are unchanged (still owned by `firma-config-loader` `ConfigResolver`); the path — not a pre-resolved config — is threaded because `doctor` reports resolution, `run` may scaffold, and `sidecar start` uses a different resolver. - As a clap global, `--config` is also accepted (and ignored) by commands that do not consume the unified config (`token`, `policy`, internal `__*`). - Design/rationale: `docs/architecture/config-env-unification-plan.md`. - Stacked on top of #619 (`amp/canonical-config-discovery`); base retargets to `main` once that merges. ## AI Assistance Claude Opus 4.8 (claude-opus-4-8).
LukeMathWalker
force-pushed
the
amp/canonical-config-discovery
branch
from
September 3, 2026 07:14
1868504 to
8836aab
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
OpenFirma has one current configuration-file selection contract.
firma doctor,firma control, andfirma monitorstill exposed a separate environment input, while duplicated documentation obscured the difference between file selection, section overlays, and Run-only profile inheritance.What Changed
doctor,control, andmonitorto canonicalFIRMA_CONFIG; explicit--configremains highest precedence and nearest.firma/firma.tomlremains the project fallback.FIRMA_STACK_CONFIGcompletely and remove it from public help and current-product documentation.docs/configuration.md, with aligned links andllms.txtguidance.Breaking Contract
FIRMA_STACK_CONFIGno longer selects configuration. UseFIRMA_CONFIGor explicit--config.Plan and Independent Review
3f41248e.8c87cfb7. The final exact candidate had no actionable findings.4ff42c53. No plan Markdown remains at the tip or in the PR diff.Atomic Revisions
3f41248e— accepted plan and independent plan-review disposition.5ec3d34d— canonical command selection and compiled behavior proof.95ce03e2— concise canonical resolution documentation.8c87cfb7— independent implementation-review record and dispositions.4ff42c53— immediate plan removal.