IP-321 Implementation Notes
IP-321 Implementation Notes
Current State
IP-337, IP-338, and IP-339 product acceptance is implemented on team/stefan/m7-m9-effect-v4-convergence. Draft PR #87 targets its parent branch, team/stefan/refactor-cli-architecture. These notes do not claim a stack, merge, commit, deployment, or PR update.
The implementation preserves one semantic result, the IP322 operator data contract, IP323 baseline selectors, the Effect v4 root presentation boundary, and one production renderer. The developer catalog is review evidence, not a shipped command or alternate renderer.
Acceptance Map
| Story | Implemented evidence |
|---|---|
| IP-337 | One OperationResult; typed expected failures; root-owned mode, presentation, diagnostics, and exit status; deterministic plain output; one JSON document; prompts remain input-only. |
| IP-338 | One recursive executable/metadata graph; ten root commands and six nested paths; help and generated references share it; no scaffold children; IP323 selectors preserved. |
| IP-339 | One semantic renderer; root-only large title; separate prompt lifecycle; developer-only catalog covers 6 anchors x 11 frames and is excluded from the dry package. |
Validation Evidence
| Surface | Current result |
|---|---|
| Focused final blocker suite | 119 tests passed. |
| Effect | 93 tests and 1,353 expectations passed. |
| Type and build | Standard type check passed; build completed 535 modules. |
| Distribution | Distribution assertions passed. |
| Catalog | 5 tests passed; 66 frames and 6 screenshots generated. |
| Dry package | 663 files; hi and hint present; zero catalog files. |
| Repository | check:repo 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/vitest it.for load error. They are not classified as IP-321 product failures.
The root suite passed the behavior contract 4/4 and backoffice browser 8/8, then exited during cleanup with EPERM at process.kill(-pid). The runner repair belongs to IP-324.
Direct Fumadocs generation and Next type generation succeeded, and standard tsc --noEmit passed. Native TypeScript 7 reports .source/server.ts is not a module. Direct wiki build reaches only seven older pages missing required title frontmatter.
Autoreview was clean before a final independent review identified discovery, exit-ownership, and required-output-mode blockers. Those blockers were repaired. A final independent PASS has not yet been claimed.
UI Evidence
There is no before screenshot: the developer catalog is a new review surface. Current repo evidence is under apps/cli/test-fixtures/ui-catalog/screenshots/; commit-specific GitHub links remain pending the convergence commit SHA.
| Fixture | SHA-256 |
|---|---|
after-dark-standard.png | 498449ad703bc258c7de372b12bbf5f4a11a2df40812e5f86c58ae739f7bcf1a |
after-dark-narrow.png | 7acd81e159a785a236e5e78a8f2c12960735291545d2ce57d624f45b227b5187 |
after-light-standard.png | 2edfaf7574167059b8c5c429aacb036f33e0e67ad9d3f781af5a2f326500d292 |
after-light-narrow.png | e9a18717e52ea7b0e4a028b6e78bcac6ccb25dbc5417d3ab3ee0c84674e95a39 |
after-no-color-standard.png | f77a445ec597e11949853d84626af221ad27f499f372d6c7d00d8dba7c58dd5d |
after-no-color-narrow.png | 52ec0b9801afe2ffbbeb374c3735c3ec731a2b0aef055ca186e10fc096a214b1 |
- Deterministic catalog HTML:
ae14ab85e30d9d2e80ee72892ea1e4cc1a54be7e617e01a9afc35cfc38bfd177. - Terminal fixture:
c3a420644c884c3ef8b4991daae84b13906981d7d9b2d9bc4a64f75cb365ed9a.
Runtime Cleanup Evidence
- Runtime provenance:
ip321-catalog-20260720-1511bathttps://hi-catalog-ip321.localhost. - Browser sessions closed.
- Run-owned directory
/tmp/hi-catalog-ip321-rsMV2uremoved. - Port 4056 and its route are absent.
- The shared portless proxy was retained.
Manual Checklist
- Root and nested command graph matches ten roots and six nested paths.
- Interactive, redirected plain, and JSON modes share semantic facts.
- JSON output stays one document and plain output stays ANSI-free.
- IP322 operator identity, compatibility, roots, bindings, mixed outcomes, barriers, retry facts, and reload guidance remain present.
- IP323
stable,bundled, and exact-version selectors remain present. - Six catalog anchors cover dark, light, no-color, standard, and narrow presentation.
- Dry package contains
hiandhintand excludes catalog files. - Routed flow and concept pages link back to the delivery artifacts.
- Remove stale unused CLI symbols and rerun
check:repo. - Repair the final discovery, exit-ownership, and required-output-mode blockers.
- Refresh current routed CLI docs from the live ten-root/six-nested registry.
- Commit and push the reviewed convergence result.
- Run the parent-owned post-push stack gate and record its real evidence.
Pending Stack Evidence
No pre-push stack status, synchronization result, or merge claim is recorded. The parent owns that gate after push.
2026-07-22 Codex review follow-up
update and check now bridge command-specific payloads through RootPresentationSink while
retaining the shared OperationResult for exit policy. Leaf and global JSON modes preserve the full
public update/check payload. Human check output uses a typed human payload on the same root sink,
so CLI, changelog, version-pin, remediation, and check summaries remain command-specific without
direct prompt output or duplicate generic rendering.
Mutation-sensitive command-boundary tests cover leaf/global JSON for both commands and human check
summaries. Root presentation tests lock the typed human payload and operation-based exit policy.
The routed IP-317 through IP-324 spec folders now also have matching apps/wiki/specs/cli source
folders, so sync preserves their linked routes.