<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-07-14-1-canonical-cli-console-seam/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-07-14-1-canonical-cli-console-seam/</id>
  <title>ADR: Canonical CliConsole seam — one CLI output object, plain --json, object-not-env determinism</title>
  <updated>2026-07-14T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-07-14-1-canonical-cli-console-seam/"/>
  <summary>Why Spec Kitty routes all CLI output through a single CliConsole seam: plain --json by construction, colour toggled on the object (never os.environ), no shim, CLI-layer scope.</summary>
  <content type="html">&lt;h2 id=&quot;canonical-cliconsole-seam--one-cli-output-object-plain---json-object-not-env-determinism&quot;&gt;Canonical CliConsole seam — one CLI output object, plain &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt;, object-not-env determinism&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-07-14&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (operator), Claude (Opus 4.8)&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; Fixes &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2632&quot;&gt;#2632&lt;/a&gt;; shipped in mission #2620 / PR #2629. Deferred non-CLI scope tracked as &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2634&quot;&gt;#2634&lt;/a&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The Claude Code harness (and many developer shells / CI agents) exports &lt;code dir=&quot;auto&quot;&gt;FORCE_COLOR=3&lt;/code&gt;. Rich honours &lt;code dir=&quot;auto&quot;&gt;FORCE_COLOR&lt;/code&gt; &lt;strong&gt;above&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;NO_COLOR&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;TERM=dumb&lt;/code&gt; and decides colour at &lt;em&gt;render&lt;/em&gt; time, and every command module constructed its own module-level &lt;code dir=&quot;auto&quot;&gt;console = Console()&lt;/code&gt; that &lt;strong&gt;snapshots the ambient colour environment at import time&lt;/strong&gt;. Two failures fell out of this (#2632, ~81 pre-existing red tests across ~15 files):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;(a) &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; corruption.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;console.print_json(json.dumps(payload))&lt;/code&gt; syntax-highlights the JSON, so under forced colour the machine output carries ANSI escapes and &lt;code dir=&quot;auto&quot;&gt;json.loads(result.output)&lt;/code&gt; raises &lt;code dir=&quot;auto&quot;&gt;Expecting value: line 1 column 1&lt;/code&gt;. This is a real user-facing bug, not just a test artefact: any caller piping &lt;code dir=&quot;auto&quot;&gt;spec-kitty … --json | jq&lt;/code&gt; under a colour-forcing harness gets corrupt output.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;(b) substring brittleness.&lt;/strong&gt; Styled human output splits literal substrings (&lt;code dir=&quot;auto&quot;&gt;&quot;delivered 1&quot;&lt;/code&gt; renders as &lt;code dir=&quot;auto&quot;&gt;delivered \x1b[0m\x1b[1;32m1\x1b[0m&lt;/code&gt;), so &lt;code dir=&quot;auto&quot;&gt;assert &quot;x&quot; in result.output&lt;/code&gt; false-REDs even though the behaviour is identical to CI’s plain environment.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;An existing fix existed but was scoped to exactly one directory (&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/cli/commands/agent/conftest.py&lt;/code&gt;), and it worked by &lt;em&gt;enumerating and monkeypatching each module’s console&lt;/em&gt; — the fragile whack-a-mole this ADR eliminates.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; must be plain by construction&lt;/strong&gt;, independent of terminal, env, or harness — machine output is data, never a styled display.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Determinism must be a property of the object, not the environment.&lt;/strong&gt; Mutating &lt;code dir=&quot;auto&quot;&gt;os.environ[&quot;NO_COLOR&quot;]&lt;/code&gt; in a fixture &lt;em&gt;works&lt;/em&gt; but leaks into subprocesses and sibling tests — rejected by the operator.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No shim, no new debt.&lt;/strong&gt; This lands inside a debt-&lt;em&gt;reduction&lt;/em&gt; mission; the shared console is to be &lt;em&gt;moved&lt;/em&gt;, not shadowed by a back-compat re-export.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Single seam.&lt;/strong&gt; One object every module shares, so colour policy (and future output policy) is changed in one place — not re-derived per module.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Drop-in compatibility.&lt;/strong&gt; The seam is passed to &lt;code dir=&quot;auto&quot;&gt;Live(console=…)&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;Progress(console=…)&lt;/code&gt;, and functions typed &lt;code dir=&quot;auto&quot;&gt;console: Console&lt;/code&gt;, so it must &lt;em&gt;be&lt;/em&gt; a &lt;code dir=&quot;auto&quot;&gt;rich.console.Console&lt;/code&gt;, not a proxy.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Harden the ~81 assertions&lt;/strong&gt; to strip ANSI / parse structured output. Rejected: 81 spot-fixes, masks the product &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; bug, and the next styled-output test re-hits it.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Suite-level conftest that sets &lt;code dir=&quot;auto&quot;&gt;NO_COLOR&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;os.environ&lt;/code&gt;.&lt;/strong&gt; Rejected: env mutation leaks into subprocesses and neighbouring tests, and does not fix the product bug for real &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; consumers.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Pin/downgrade &lt;code dir=&quot;auto&quot;&gt;rich&lt;/code&gt;.&lt;/strong&gt; Rejected: chases a moving dependency, doesn’t encode the invariant, and doesn’t address &lt;code dir=&quot;auto&quot;&gt;FORCE_COLOR&lt;/code&gt; semantics (which are correct — the app was wrong to route machine output through a styled console).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;A canonical &lt;code dir=&quot;auto&quot;&gt;CliConsole&lt;/code&gt; seam (chosen).&lt;/strong&gt; One shared &lt;code dir=&quot;auto&quot;&gt;Console&lt;/code&gt; subclass whose &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; output is plain by construction and whose colour is toggled &lt;em&gt;in place on the object&lt;/em&gt; for tests.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;For the seam’s home we considered &lt;code dir=&quot;auto&quot;&gt;src/kernel/cli/&lt;/code&gt;, but &lt;code dir=&quot;auto&quot;&gt;kernel&lt;/code&gt; is the zero-dependency import floor (its README forbids CLI/rich concerns and any spec-kitty-package imports). CLI output is a &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt; concern — so the seam lives at &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/console.py&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; a single canonical &lt;code dir=&quot;auto&quot;&gt;CliConsole&lt;/code&gt; seam, because it fixes both the product &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; corruption and the test brittleness at one point, with no env mutation and no shim.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/console.py&lt;/code&gt; defines &lt;code dir=&quot;auto&quot;&gt;class CliConsole(Console)&lt;/code&gt; and the shared singletons &lt;code dir=&quot;auto&quot;&gt;console&lt;/code&gt; (stdout) and &lt;code dir=&quot;auto&quot;&gt;err_console&lt;/code&gt; (stderr).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;emit_json(payload)&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;print_json(...)&lt;/code&gt; &lt;strong&gt;bypass Rich’s highlighter and write plain JSON&lt;/strong&gt; — so every existing &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; call site becomes safe simply by routing through the seam.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;set_plain(bool)&lt;/code&gt; toggles colourless rendering &lt;strong&gt;in place&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;no_color=True&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_color_system=None&lt;/code&gt;). Because it subclasses &lt;code dir=&quot;auto&quot;&gt;Console&lt;/code&gt;, it is a drop-in for &lt;code dir=&quot;auto&quot;&gt;Live&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;Progress&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;console: Console&lt;/code&gt;; and because every module imports the &lt;em&gt;same&lt;/em&gt; singleton, one &lt;code dir=&quot;auto&quot;&gt;set_plain(True)&lt;/code&gt; call in a single autouse fixture neutralises colour across the whole suite — no &lt;code dir=&quot;auto&quot;&gt;os.environ&lt;/code&gt; involved.&lt;/li&gt;
&lt;li&gt;The whole &lt;strong&gt;CLI layer&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;cli/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;cli/commands&lt;/code&gt;, ~77 ad-hoc &lt;code dir=&quot;auto&quot;&gt;Console()&lt;/code&gt; constructions) is &lt;strong&gt;moved&lt;/strong&gt; onto the seam; the old definitions are deleted, and the 18 &lt;code dir=&quot;auto&quot;&gt;from …cli.helpers import console&lt;/code&gt; importers are repointed to &lt;code dir=&quot;auto&quot;&gt;…cli.console&lt;/code&gt; (no shim). A structural guard (&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_cli_console_single_seam.py&lt;/code&gt;) forbids raw &lt;code dir=&quot;auto&quot;&gt;Console(...)&lt;/code&gt; anywhere under &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/&lt;/code&gt; except the seam module.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; output is plain and &lt;code dir=&quot;auto&quot;&gt;jq&lt;/code&gt;-safe regardless of &lt;code dir=&quot;auto&quot;&gt;FORCE_COLOR&lt;/code&gt;/terminal — a real product-correctness fix, not just green tests.&lt;/li&gt;
&lt;li&gt;Test determinism is achieved by configuring one object; no environment mutation, no per-module console monkeypatching (the fragile &lt;code dir=&quot;auto&quot;&gt;agent/conftest.py&lt;/code&gt; enumeration collapses to one &lt;code dir=&quot;auto&quot;&gt;set_plain&lt;/code&gt; call).&lt;/li&gt;
&lt;li&gt;~77 ad-hoc &lt;code dir=&quot;auto&quot;&gt;Console()&lt;/code&gt; constructions eliminated; the arch guard keeps the seam singular by construction (debt reduction that holds).&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;A large mechanical diff folded into an already-large PR.&lt;/li&gt;
&lt;li&gt;The seam covers the CLI layer only. ~14 non-CLI module-level consoles remain (&lt;code dir=&quot;auto&quot;&gt;sync/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;readiness/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;retrospective/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;core/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;identity/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;charter_runtime/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;template/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;upgrade/&lt;/code&gt;), and &lt;strong&gt;one of them — &lt;code dir=&quot;auto&quot;&gt;retrospective/cli.py:277&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;_console.print_json&lt;/code&gt; — is an active &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; corruption vector&lt;/strong&gt; with the same root cause. These are &lt;strong&gt;deferred to &lt;a href=&quot;https://github.com/Priivacy-ai/spec-kitty/issues/2634&quot;&gt;#2634&lt;/a&gt;&lt;/strong&gt;, not because they are safe, but because migrating them cleanly requires resolving a &lt;strong&gt;layering question&lt;/strong&gt;: those are lower-layer packages, and importing &lt;code dir=&quot;auto&quot;&gt;cli.console&lt;/code&gt; from them would invert the dependency direction. The right fix is likely to relocate the seam to a home both layers can import (e.g. a &lt;code dir=&quot;auto&quot;&gt;specify_cli&lt;/code&gt;-root console module) — a design decision that deserves its own change rather than a rushed rider here.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;The few deliberately-special CLI consoles (&lt;code dir=&quot;auto&quot;&gt;width=200&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;width=120&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;highlight=False&lt;/code&gt;/dynamic &lt;code dir=&quot;auto&quot;&gt;color_system&lt;/code&gt;) remain distinct instances, but of the seam class (&lt;code dir=&quot;auto&quot;&gt;CliConsole(...)&lt;/code&gt;), so they still get plain &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;set_plain&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_cli_console_single_seam.py&lt;/code&gt; (AST guard: no raw &lt;code dir=&quot;auto&quot;&gt;Console(...)&lt;/code&gt; under &lt;code dir=&quot;auto&quot;&gt;cli/&lt;/code&gt; outside the seam) + a non-vacuity companion.&lt;/li&gt;
&lt;li&gt;Fast unit tests for &lt;code dir=&quot;auto&quot;&gt;CliConsole&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;emit_json&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;print_json&lt;/code&gt; plain under &lt;code dir=&quot;auto&quot;&gt;force_terminal=True&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;set_plain&lt;/code&gt; in-place toggle; &lt;code dir=&quot;auto&quot;&gt;err_console&lt;/code&gt; targets stderr).&lt;/li&gt;
&lt;li&gt;The #2632 files pass under &lt;code dir=&quot;auto&quot;&gt;FORCE_COLOR=3&lt;/code&gt;, and a regression constructs a colour-forced &lt;code dir=&quot;auto&quot;&gt;CliConsole&lt;/code&gt; and asserts &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; output carries no &lt;code dir=&quot;auto&quot;&gt;\x1b&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;json.loads&lt;/code&gt; succeeds.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
