I1981 — A command's effect class is declared per subcommand and flag, and live scenarios judge the whole argv
Declare read-only or state-mutating per subcommand and per flag in share/commands.yaml where a command has both, and make live use-case validation and runs judge the full argument vector against that declaration.
DONE wave 0 · p0 · implementation profile · parallel safe
Objective
Declare read-only or state-mutating per subcommand and per flag in share/commands.yaml where a command has both, and make live use-case validation and runs judge the full argument vector against that declaration.
Why
share/commands.yaml classes `knowledge` state-mutating as a whole, so live scenarios refuse its read-only edges, nodes and sources. OSCILLA cb79d27 had to copy its tracked tree into a fixture to prove a knowledge edge. It classes `check` read-only with writes [], yet `check --checkpoint` writes .ai/local/state/current.yaml, so a live step can change state while being admitted as read-only.
Current state
lib/usecase.sh:383-386 admits a live step when the top-level command's class is read-only (commands.sh:27). The registry has no per-subcommand or per-flag effect.
Desired state
The registry carries an effect per subcommand and flag where they differ. lib/usecase.sh validate and run refuse a live step whose argv reaches a writing path and admit one that only reads. doctor reconciles the declaration with the dispatch as it does today.
Scope
- share/commands.yaml
- lib/usecase.sh
- lib/commands.sh
- docs/CLI.md
- test/cases/359_live_scenarios.sh
- test/fixtures/commands
Dependencies
None. This issue is a root of the graph.
What waits on this
Acceptance criteria
- A live scenario step `knowledge edges` validates and runs
- A live scenario step `check --checkpoint` is refused at validate time, naming the flag
- The command-registry reconciliation in doctor covers the new per-subcommand declarations
Validation
- bin/majordomus plan validate
- MJ_TEST_JOBS=4 bash test/run.sh <the case this issue adds>
Evidence required
- live_scenario_reads_knowledge
- live_scenario_refuses_writing_flag
Evidence
| covers | type | command | result | at commit |
|---|---|---|---|---|
| live_scenario_reads_knowledge | test | MJ_TEST_JOBS=2 bash test/run.sh 359_live_scenarios | pass: knowledge edges and nodes --json validate and run live, knowledge derive is refused by command | 1393d9e |
| live_scenario_refuses_writing_flag | test | MJ_TEST_JOBS=2 bash test/run.sh 359_live_scenarios | pass: check --checkpoint refused at validate naming flag '--checkpoint'; doctor rejects an effect flag the syntax lacks and a read-only flag | 1393d9e |
| live_scenario_reads_knowledge | test | MJ_TEST_JOBS=2 bash test/run.sh 359_live_scenarios | tests: 1 passed, 0 failed, 0 skipped (run 2026-10-14 before 07:36Z on master ce5959db59) | ce5959d |
| live_scenario_refuses_writing_flag | test | MJ_TEST_JOBS=2 bash test/run.sh 359_live_scenarios | tests: 1 passed, 0 failed, 0 skipped (run 2026-10-14 before 07:36Z on master ce5959db59) | ce5959d |
Timeline
- started
- 2026-10-11T05:05:14Z
- verified
- 2026-10-11T05:05:29Z
- completed
- 2026-10-14T07:39:39Z
Those three fields, the evidence above and the state of the dependencies are all the status is made of. There is no status field to disagree with them.
Canonical record: .ai/repo/project/issues/I1981.yaml. Read it back with majordomus plan show I1981.