Spec: Present every CLI operation through one HI-native contract

User Input

in @linear project https://linear.app/devpunks/project/harness-intelligence-23aceec78aca/issues we have new modules M7 M8 M9 for the refactor and re architecture around effect v4. so now please start a $delivery-phase FOR EACH SINGLE ONE of the EPICS. complete all epics and their inner stories with a delivery phase per epic

DO NOT MISS ON ANY OF THE STORIES

do this in full parallel. dont merge on main the subsequent pr

The supplied backlog handoff additionally requires one epic-level spec at a time, preserves the already-materialized Linear scope, and forbids implementation before explicit delivery routing.

Context

CLI operators, scripts, and agents currently encounter presentation decisions distributed across commands, help text, prompt paths, JSON output, and terminal helpers. The same operation needs one authoritative set of facts and one discovery contract so interactive, redirected plain, and JSON consumers receive predictable behavior without product code embedding terminal policy.

IP-321 unifies the full scope of IP-337, IP-338, and IP-339: structured operation results, metadata-derived discovery, and one HI-native human presentation boundary with a safe developer-only review catalog.

Non-Goals

• Separate domain result models for interactive, plain, and JSON modes.
• Renderer-owned product or domain decisions.
• Moving command execution policy into metadata.
• A second documentation-only command registry.
• Copying another product's visual identity.
• A generic terminal widget framework beyond actual HI flows.
• Shipping the developer renderer catalog as a user feature or allowing it to become a second renderer.
• Selecting exact primitive names, palette values, spacing, or incidental implementation structure in this specification.

Acceptance Criteria

IP-337 — One Structured Result

• Operation results can express status, planned or completed changes, warnings, degradations, per-action conflicts or handled failures, and next actions.
• Interactive, plain, and JSON presentation consume the same underlying result.
• Prompts remain input concerns rather than result or presentation policy.
• Command-stopping expected failures remain typed until the outer presentation boundary.
• Domain and application behavior contains no terminal prose, glyphs, styling, progress, or exit-code policy.
• Output mode is selected once at the CLI root.
• Redirected plain output is deterministic, non-interactive, and free of ANSI, color, and animation.
• JSON mode is non-interactive and emits exactly one valid document, including structured expected failures with nonzero status.
• Diagnostics do not corrupt JSON stdout, and missing non-interactive input is an actionable typed failure.

IP-338 — Metadata-Derived Discovery

• Every command has one colocated metadata declaration covering name, group, summary, options, examples, interaction requirements, and supported output modes.
• Root help, command listings, examples, and generated reference views derive from that declaration.
• Adding, renaming, or removing a command changes every discovery surface through the same source.
• No handwritten duplicate command catalog remains.
• Command metadata owns discovery and presentation facts only and does not own product behavior.

IP-339 — One HI-Native Renderer and Safe Catalog

• Commands send semantic facts to one shared human renderer and do not construct layout or terminal prose.
• The renderer alone owns semantic states, layout, wrapping, theme, glyphs, and interactive or plain presentation policy.
• Prompts share semantic theme rules while a separate interaction boundary owns keyboard input, raw-terminal lifecycle, and cleanup.
• The large gradient HI title appears only on root help, the root screen, or an explicit welcome flow.
• Normal subcommands use compact or no headings, and plain and JSON output never show the title.
• Renderer primitives are added only for actual flows and do not form a generic widget framework.
• A developer-only catalog exercises every production state, layout, and prompt frame across light, dark, no-color, and narrow-width conditions.
• The catalog imports production presentation one way, has no command side effects, is not shipped as a user command, and never becomes a second renderer.

Constraints

• IP-330 must first classify affected public outcomes and provide public-seam evidence for exact, semantic, or intentional-change behavior.
• IP-337 blocks IP-339. IP-338 may proceed independently only after the shared IP-330 gate and within the coordinated breadth-first migration.
• Interactive terminals may use HI styling, prompts, and progress. Redirected non-JSON output remains deterministic and non-interactive. JSON bypasses human rendering completely.
• Expected failures remain typed until the CLI boundary maps them; unexpected diagnostics may use stderr but cannot corrupt machine-readable stdout.
• Commands read inputs, invoke application behavior, and present results; application and domain behavior remain independent of terminal lifecycle and rendering.
• The final repository contains only the new contract and renderer path, with no shipped compatibility layer, feature flag, dual presentation architecture, or temporary catalog scaffolding.
• Work remains on one unmerged, undeployed branch until packaged CLI help/command/JSON checks, renderer-catalog checks, the comprehensive repository suite, and representative consumer gates all pass.

Dependency Readiness

• Status: No Stack Required
• Dependency: IP-330 — Classify and characterize every public behavior seam
• Evidence: IP-330 characterization is satisfied by the public behavior-contract suite carried into the current convergence branch.
• Reason: IP-337 still precedes IP-339 as internal execution order, not PR topology.

Coordinated Delivery Intent

• Delivery branch: team/stefan/m7-m9-effect-v4-convergence.
• PR state: draft PR #87, based on team/stefan/refactor-cli-architecture.
• Base intent: continue the current parent-based convergence PR. This record makes no stack, merge, commit, or deployment claim.
• Ordering: IP-330, then breadth-first work across IP-337 and IP-338, with IP-339 following IP-337.

Review State

• Requirements authority: completed CLI context architecture grill, with Q1-Q58 closed and all branches at 100%.
• Backlog authority: full IP-321 parent, all three Linear child stories, and native relations read on 2026-07-14.
• Spec status: implemented; product acceptance for IP-337, IP-338, and IP-339 is represented in code and focused evidence.
• Delivery closeout: code, docs, repository checks, and identified blocker repairs are ready. T11 remains pending for final independent acceptance, commit, push, and the parent-owned post-push stack gate. The aggregate runner cleanup EPERM belongs to IP-324.
• Human approval state: delivery was authorized; parent closeout still owns review, commit, and PR updates.

Decision Log