diff options
| -rw-r--r-- | docs/specs/2026-07-10-audio-doctor-input-side-spec.org | 17 |
1 files changed, 9 insertions, 8 deletions
diff --git a/docs/specs/2026-07-10-audio-doctor-input-side-spec.org b/docs/specs/2026-07-10-audio-doctor-input-side-spec.org index 11f61b8..b3bab7f 100644 --- a/docs/specs/2026-07-10-audio-doctor-input-side-spec.org +++ b/docs/specs/2026-07-10-audio-doctor-input-side-spec.org @@ -81,7 +81,7 @@ Facts this spec is built on, verified rather than remembered: ** Scope tiers -- *v1:* the kernel capture tier; PTT-aware source classification; input verdicts and their remedies; the two section-header doctor keys with mutual exclusion; =audio doctor --input= in the CLI. +- *v1:* the kernel capture tier; PTT-aware source classification; input verdicts and their remedies; the two section-header doctor keys with mutual exclusion; explicit =audio doctor --output= / =--input= flags, output aliased as the default. - *Out of scope:* PTT rebuild; per-application routing; hardware diagnosis. - *vNext:* a third sighting of "the graph is fine and one client cannot use it" turns into its own design question, namely whether the doctor should name the application layer explicitly. Logged to =todo.org=, not built here. @@ -175,7 +175,7 @@ Rejected in favor of one doctor per direction, which supplies the missing intent Rejected. The bottom tier should be the one thing in the doctor that cannot fail. -* Decisions [3/7] +* Decisions [4/7] ** DONE A doctor key per direction, on the section headers CLOSED: [2026-07-10 Fri] @@ -256,14 +256,15 @@ Consequences: the verdict table grows from ten to fourteen, and =classify.findin Owner: Craig. By: before Phase 1 lands. -** TODO Does the CLI grow a flag or a subcommand? -Context: the GUI's two keys need a CLI counterpart, since the doctor is CLI-first and the GUI is a face over it. +** DONE The CLI grows explicit =--output= and =--input= flags, output aliased as the default +CLOSED: [2026-07-10 Fri] +Context: =audio doctor= today accepts only =--fix= and =--force=. There is no =--output=, so adding a lone =--input= would read as a special case bolted onto a bare command rather than one of a symmetric pair. -Decision (proposed): =audio doctor= keeps its current meaning (the output side) and gains =--input=. Both accept =--fix= and =--force=. +Decision: we will add both =--output= and =--input= as explicit direction flags, and alias bare =audio doctor= to =audio doctor --output=. Both accept =--fix= and =--force=. The two flags are mutually exclusive; passing both is an error. -Consequences: no existing invocation changes meaning, and a script that branches on the exit code keeps working. Harder: =audio doctor --input --fix --force= is a long line, and "doctor with no flag means output" is a default a reader has to learn. The alternative, =audio doctor input=, reads better and breaks every existing call. +Consequences: the two directions are named symmetrically, and =--input= has a sibling to pair against rather than standing alone. Bare =audio doctor= keeps its current meaning, so nothing that scripts it breaks, and "output is the default" is now a stated alias a reader can see rather than a convention to infer. Harder: =audio doctor --input --fix --force= is a long line, which is the cost of explicitness over =audio doctor input=; the subcommand form was rejected because it would break every existing call. -Owner: Craig. By: before Phase 3 lands. +Craig's call, 2026-07-10: "alias the command and have =audio doctor --output= be the one that is run by default. That way it's symmetrical, and =audio doctor --input= has a place." * Implementation phases @@ -273,7 +274,7 @@ Each phase leaves the tree green and independently useful, as the parent spec's Pure engine, no classifier changes, no UI. =diag.probe_kernel()= reads =/proc/asound=; =diag.gather()= adds =kernel= and =ptt= to the context; =active_streams(graph, direction=None)= filters. =audio diag --json= shows the new context. Fakes: a temp =/proc/asound=-shaped tree via an injectable root, since the real one cannot be faked on PATH. ** TODO Phase 1 — =classify(ctx, side)= and the input verdicts -Pure, fixture-driven. The shared terminal ladder, then the fork. Pairwise over (kernel capture set × graph sources × default source state × PTT armed). =audio doctor --input= read-only prints findings and a verdict. +Pure, fixture-driven. The shared terminal ladder, then the fork. Pairwise over (kernel capture set × graph sources × default source state × PTT armed). This phase adds the direction flags: =--output= and =--input=, mutually exclusive, with bare =audio doctor= aliased to =--output=. =audio doctor --input= read-only prints findings and a verdict, and =audio doctor= keeps printing exactly what it does today. ** TODO Phase 2 — the input remedies and the direction-aware guard Remedies 6, 7, 8, each re-probing its own claim. The guard splits by direction. =audio doctor --input --fix=. The existing guard tests move rather than being deleted. |