SpecsCLIIP-321 HI-Native CLI Presentation Contract
IP-321 Delivery Plan
IP-321 Delivery Plan
Plan State
- Product implementation and routed documentation: complete for IP-337, IP-338, and IP-339.
- Closeout: code, docs, and blocker repairs are ready. T11 remains pending for commit, push, and the parent-owned post-push stack gate.
- Delivery vehicle: draft PR #87 from
team/stefan/m7-m9-effect-v4-convergencetoteam/stefan/refactor-cli-architecture. - Topology claim: none. This plan does not claim a stack, merge, commit, deployment, or PR update.
Interface Decisions
- Commands and application services produce one presentation-neutral
OperationResult. - Effect v4 command execution does not return a leaf result through
Command.runWith; semantic leaves publish once to a root-owned result sink. - The root selects interactive, plain, or JSON mode and owns presentation, diagnostics, and exit status.
- Prompt input remains separate from operation results and owns terminal lifecycle cleanup.
- One recursive executable graph is also the discovery/reference source.
- IP322 operator facts and IP323 baseline selectors remain lossless.
- One production renderer owns human output. The developer catalog imports it one way and is excluded from the package.
Tasks
| Task | Outcome | Status |
|---|---|---|
| T1 | Define the structured operation-result contract and public behavior evidence. | Complete |
| T2 | Define colocated command discovery metadata. | Complete |
| T3 | Project all current commands through the shared result contract. | Complete |
| T4 | Preserve scaffold, tools, and skills behavior. | Complete |
| T5 | Preserve complete IP322 operator outcomes and sequential action semantics. | Complete |
| T6 | Build one recursive executable and reference graph. | Complete |
| T7 | Move mode selection and presentation to the CLI root boundary. | Complete |
| T8 | Centralize renderer and prompt semantics without mixing input and output. | Complete |
| T9 | Add and verify the developer-only renderer catalog and package exclusion. | Complete |
| T10 | Ingest the command-discovery flow and presentation-contract concept. | Complete |
| T11 | Commit and push the reviewed convergence result, then run the parent-owned post-push stack gate. | Pending |
Verification Gate
- Focused final blocker suite: 119/119 passed.
- Effect: 93 tests and 1,353 expectations passed.
- Standard CLI type check passed; build completed with 535 modules.
- Distribution assertions passed.
- Catalog: 5 tests, 66 frames, and 6 screenshots passed with deterministic hashes recorded in the implementation notes.
- Dry package: 663 files;
hiandhintpresent; zero catalog files shipped. - Repository check passed.
- Wiki: 2 files, 6 tests passed.
- One post-isolation full CLI run recorded 690 passed, 1 failed, and 2 errors across 4,216 tests and 66 files. The isolated failures are pre-existing test-harness conditions: hooks cached-PATH evidence at 5/1 and an
@effect/vitestit.forload error. They are not classified as IP-321 product failures. - Root aggregate evidence: behavior contract 4/4 and backoffice browser 8/8 passed before cleanup failed with
EPERMatprocess.kill(-pid). The runner repair belongs to IP-324. - Direct Fumadocs generation and Next type generation succeeded; standard
tsc --noEmitpassed. Native TypeScript 7 reports.source/server.ts is not a module. Direct wiki build reaches only seven older docs missing title frontmatter. - Autoreview was clean before the final independent review identified discovery/exit/mode blockers. Those blockers were repaired; a final independent PASS has not yet been claimed.
Pending Stack Evidence
Stack status and synchronization evidence are intentionally absent before push. The parent owns the post-push stack gate; this plan makes no pre-push stack claim.