minicode-ai 0.11.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (221) hide show
  1. package/CHANGELOG.md +98 -0
  2. package/LICENSE +21 -21
  3. package/README.md +4 -4
  4. package/cli/args.ts +46 -0
  5. package/cli/commands/acp.ts +163 -10
  6. package/cli/commands/config.ts +33 -18
  7. package/cli/commands/daemon.ts +515 -0
  8. package/cli/commands/exec.ts +145 -53
  9. package/cli/commands/openwork.ts +986 -0
  10. package/cli/commands/sessions.ts +4 -1
  11. package/cli/commands/stats.ts +34 -4
  12. package/cli/commands.ts +217 -2
  13. package/cli/index.ts +146 -14
  14. package/cli/recovery-warning.ts +115 -0
  15. package/cli/router.ts +32 -1
  16. package/cli/setup.ts +2332 -171
  17. package/cli/tui.ts +113 -7
  18. package/docs/OUTPUT_ARCHITECTURE_AUDIT.md +489 -0
  19. package/docs/OUTPUT_EVENT_MODEL.md +289 -0
  20. package/docs/OUTPUT_IMPLEMENTATION_PLAN.md +391 -0
  21. package/docs/OUTPUT_PROTOCOL_SPEC.md +285 -0
  22. package/docs/OUTPUT_RENDERING_SPEC.md +248 -0
  23. package/docs/OUTPUT_UX_RULES.md +449 -0
  24. package/docs/PLAN_UIUX_V6.md +2 -2
  25. package/docs/README.md +4 -3
  26. package/docs/TERMINAL_CONTRACT.md +278 -66
  27. package/docs/architecture.md +89 -7
  28. package/docs/changelog.md +1 -1
  29. package/docs/choosing-mode.md +2 -2
  30. package/docs/cli.md +9 -5
  31. package/docs/concepts.md +1 -1
  32. package/docs/contributing.md +9 -2
  33. package/docs/environment.md +6 -2
  34. package/docs/exec.md +46 -5
  35. package/docs/memory-sessions.md +2 -0
  36. package/docs/policy-sandbox.md +1 -1
  37. package/docs/pricing-budget.md +1 -1
  38. package/docs/quickstart.md +2 -2
  39. package/docs/repl.md +6 -2
  40. package/docs/security-model.md +1 -1
  41. package/docs/security.md +1 -1
  42. package/docs/skills.md +2 -2
  43. package/docs/terminal.md +9 -5
  44. package/docs/tools.md +1 -1
  45. package/package.json +35 -5
  46. package/src/app/session.ts +261 -15
  47. package/src/app/tool-layer.ts +94 -7
  48. package/src/daemon/approvals.ts +361 -0
  49. package/src/daemon/capability.ts +145 -0
  50. package/src/daemon/children.ts +142 -0
  51. package/src/daemon/client.ts +267 -0
  52. package/src/daemon/control.ts +350 -0
  53. package/src/daemon/discovery.ts +234 -0
  54. package/src/daemon/feed.ts +155 -0
  55. package/src/daemon/framing.ts +94 -0
  56. package/src/daemon/host.ts +316 -0
  57. package/src/daemon/protocol.ts +217 -0
  58. package/src/daemon/resource.ts +170 -0
  59. package/src/daemon/sanitize.ts +57 -0
  60. package/src/daemon/server.ts +627 -0
  61. package/src/daemon/store.ts +317 -0
  62. package/src/daemon/subscription.ts +270 -0
  63. package/src/daemon/telemetry.ts +81 -0
  64. package/src/hooks/run.ts +12 -1
  65. package/src/lib/atomic-write.ts +29 -3
  66. package/src/lib/db-path.ts +26 -0
  67. package/src/lib/keystore.ts +544 -42
  68. package/src/lib/net.ts +43 -1
  69. package/src/lib/safe-open.ts +116 -1
  70. package/src/lib/session-id.ts +15 -0
  71. package/src/lsp/client.ts +123 -5
  72. package/src/mcp/client.ts +139 -17
  73. package/src/mcp/server.ts +177 -50
  74. package/src/mcp/transport.ts +16 -19
  75. package/src/memory/vector.ts +770 -55
  76. package/src/policy/allowlist.ts +14 -2
  77. package/src/policy/bash-guard.ts +105 -10
  78. package/src/policy/compaction.ts +82 -5
  79. package/src/policy/consequence-engine.ts +220 -0
  80. package/src/policy/context.ts +132 -0
  81. package/src/policy/executor.ts +187 -121
  82. package/src/policy/no-progress.ts +559 -0
  83. package/src/policy/permission.ts +4 -8
  84. package/src/policy/pricing.ts +17 -3
  85. package/src/policy/scrub.ts +69 -2
  86. package/src/policy/tool-contract.ts +515 -0
  87. package/src/policy/usage.ts +310 -24
  88. package/src/policy/verifier.ts +6 -3
  89. package/src/policy/work-mode.ts +182 -0
  90. package/src/presentation/adapter.ts +533 -26
  91. package/src/presentation/events.ts +151 -0
  92. package/src/presentation/model.ts +180 -27
  93. package/src/presentation/projection.ts +858 -0
  94. package/src/presentation/reducer.ts +645 -310
  95. package/src/presentation/store.ts +12 -7
  96. package/src/providers/anthropic.ts +18 -10
  97. package/src/providers/responses.ts +17 -7
  98. package/src/runtime/capability.ts +409 -0
  99. package/src/runtime/child-execution.ts +274 -0
  100. package/src/runtime/composition.ts +958 -0
  101. package/src/runtime/dispatch.ts +591 -0
  102. package/src/runtime/execution-backend.ts +632 -0
  103. package/src/runtime/execution-events.ts +272 -0
  104. package/src/runtime/execution-id.ts +230 -0
  105. package/src/runtime/execution-journal.ts +926 -0
  106. package/src/runtime/execution-kernel.ts +456 -0
  107. package/src/runtime/execution-registry.ts +379 -0
  108. package/src/runtime/process-supervision.ts +276 -0
  109. package/src/runtime/production-execution.ts +551 -0
  110. package/src/runtime/production-runtime.ts +217 -0
  111. package/src/runtime/recovery-safety.ts +70 -0
  112. package/src/runtime/recovery.ts +477 -0
  113. package/src/runtime/runtime-capabilities.ts +179 -0
  114. package/src/runtime/runtime-diagnostics.ts +141 -0
  115. package/src/runtime/runtime-host.ts +365 -0
  116. package/src/runtime/runtime-status-facts.ts +222 -0
  117. package/src/runtime/runtime-status-provider.ts +74 -0
  118. package/src/runtime/runtime-status.ts +459 -0
  119. package/src/runtime/runtime-task-admission.ts +101 -0
  120. package/src/runtime/supervisor.ts +444 -0
  121. package/src/session/authority.ts +168 -0
  122. package/src/session/checkpoint.ts +88 -1
  123. package/src/session/context-adapter.ts +251 -0
  124. package/src/session/context-assembly.ts +242 -0
  125. package/src/session/context-identity.ts +389 -0
  126. package/src/session/context-projection.ts +248 -0
  127. package/src/session/context-selector.ts +500 -0
  128. package/src/session/cross-session-adoption.ts +249 -0
  129. package/src/session/full-history-fold.ts +171 -0
  130. package/src/session/identity.ts +192 -0
  131. package/src/session/journal.ts +805 -102
  132. package/src/session/open-work-intent.ts +732 -0
  133. package/src/session/open-work.ts +767 -0
  134. package/src/session/pending-tools.ts +94 -0
  135. package/src/session/persistence.ts +3569 -127
  136. package/src/session/runtime-header.ts +208 -0
  137. package/src/session/shadow-git.ts +13 -5
  138. package/src/session/verification.ts +1623 -0
  139. package/src/task/assignment.ts +136 -0
  140. package/src/task/autonomous-adapter.ts +168 -0
  141. package/src/task/autonomous-context.ts +630 -0
  142. package/src/task/autonomous-policy.ts +490 -0
  143. package/src/task/continuity.ts +179 -0
  144. package/src/task/execution-cancellation.ts +165 -0
  145. package/src/task/graph-validate.ts +379 -0
  146. package/src/task/graph.ts +305 -0
  147. package/src/task/identity.ts +230 -0
  148. package/src/task/model.ts +417 -0
  149. package/src/task/production-scheduler.ts +293 -0
  150. package/src/task/readiness.ts +229 -0
  151. package/src/task/scheduler-observability.ts +387 -0
  152. package/src/task/scheduler.ts +1197 -0
  153. package/src/task/scheduling-policy.ts +165 -0
  154. package/src/task/session-authority.ts +148 -0
  155. package/src/task/session-ownership.ts +211 -0
  156. package/src/task/store.ts +2887 -0
  157. package/src/task/sync.ts +343 -0
  158. package/src/task/trigger.ts +260 -0
  159. package/src/tools/bash.ts +377 -211
  160. package/src/tools/code_run.ts +1 -1
  161. package/src/tools/delete_file.ts +1 -1
  162. package/src/tools/edit.ts +33 -6
  163. package/src/tools/evidence.ts +30 -0
  164. package/src/tools/git.ts +4 -4
  165. package/src/tools/glob.ts +12 -3
  166. package/src/tools/grep.ts +1 -1
  167. package/src/tools/lsp.ts +4 -4
  168. package/src/tools/mcp_call.ts +11 -4
  169. package/src/tools/memory.ts +153 -18
  170. package/src/tools/move_file.ts +1 -1
  171. package/src/tools/patch.ts +1 -1
  172. package/src/tools/read_file.ts +1 -1
  173. package/src/tools/read_image.ts +1 -1
  174. package/src/tools/submit_result.ts +1 -1
  175. package/src/tools/task.ts +437 -41
  176. package/src/tools/todo.ts +662 -35
  177. package/src/tools/web_fetch.ts +4 -2
  178. package/src/tools/web_search.ts +9 -3
  179. package/src/tools/write_file.ts +1 -1
  180. package/src/ui/assistant/simple.ts +123 -50
  181. package/src/ui/assistant/turn-status.ts +17 -3
  182. package/src/ui/contract.ts +184 -0
  183. package/src/ui/footer.ts +54 -18
  184. package/src/ui/i18n/en.ts +62 -6
  185. package/src/ui/i18n/id.ts +62 -6
  186. package/src/ui/input/prompt-engine.ts +120 -25
  187. package/src/ui/render/errors.ts +39 -1
  188. package/src/ui/render/markdown-table.ts +455 -0
  189. package/src/ui/render/markdown.ts +22 -1
  190. package/src/ui/render/table-grid.ts +184 -0
  191. package/src/ui/render/table.ts +15 -76
  192. package/src/ui/runtime/screen.ts +7 -2
  193. package/src/ui/runtime/statusline.ts +25 -6
  194. package/src/ui/tui/app.ts +598 -133
  195. package/src/ui/tui/transcript.ts +531 -89
  196. package/vendor/minicore/VENDOR.md +1 -1
  197. package/vendor/minicore/src/core/budget.ts +25 -25
  198. package/vendor/minicore/src/core/compact.ts +75 -75
  199. package/vendor/minicore/src/core/errors.ts +59 -59
  200. package/vendor/minicore/src/core/events.ts +73 -73
  201. package/vendor/minicore/src/core/executor.ts +139 -139
  202. package/vendor/minicore/src/core/history.ts +31 -31
  203. package/vendor/minicore/src/core/index.ts +41 -41
  204. package/vendor/minicore/src/core/loop.ts +355 -355
  205. package/vendor/minicore/src/core/permission.ts +22 -22
  206. package/vendor/minicore/src/core/provider.ts +39 -39
  207. package/vendor/minicore/src/core/recovery.ts +35 -35
  208. package/vendor/minicore/src/core/session.ts +327 -327
  209. package/vendor/minicore/src/core/snapshot.ts +146 -146
  210. package/vendor/minicore/src/core/tokens.ts +107 -107
  211. package/vendor/minicore/src/core/tool.ts +115 -115
  212. package/vendor/minicore/src/core/types.ts +50 -50
  213. package/vendor/minicore/src/providers/openai-compat.ts +417 -417
  214. package/AGENTS.md +0 -45
  215. package/PLAN.md +0 -491
  216. package/docs/ARCHITECTURE.html +0 -1248
  217. package/docs/CONTROL-PLANE-MAP.md +0 -139
  218. package/docs/HARNESS.md +0 -150
  219. package/docs/SUMMARY.md +0 -52
  220. package/docs/UI_RENDER_PIPELINE.md +0 -165
  221. package/docs/USAGE.md +0 -11
@@ -0,0 +1,289 @@
1
+ # Output Event Model
2
+
3
+ **Status:** Phase 2 core state/replay contract landed; renderer/wire protocol masih target
4
+ **Tanggal:** 2026-09-25
5
+ **Audit sumber:** `docs/OUTPUT_ARCHITECTURE_AUDIT.md`
6
+
7
+ ## Status implementasi
8
+
9
+ Phase 1 mengimplementasikan `user.message`, exhaustive bridge payload, dan marker
10
+ `PROPOSED_EVENT_TYPES` untuk event yang belum memiliki producer. Phase 2 core kini
11
+ menyimpan collection semantic lengkap, menghitung summary dari evidence, lalu
12
+ memuat ulang dari `presentation_events`; renderer dan machine protocol belum
13
+ dipindahkan penuh.
14
+
15
+ ## 1. Tujuan
16
+
17
+ Model ini mendefinisikan fakta semantic yang boleh melewati runtime → policy →
18
+ renderer. Model ini bukan renderer contract dan bukan terminal output. TTY, linear,
19
+ JSONL, ACP, dan consumer masa depan harus membaca event yang sama lalu memilih
20
+ proyeksi yang berbeda.
21
+
22
+ ```text
23
+ runtime fact
24
+ → semantic event
25
+ → deterministic reducer
26
+ → presentation state
27
+ → policy projection
28
+ → renderer
29
+ ```
30
+
31
+ ## 2. Envelope kanonik
32
+
33
+ Implementasi internal dapat memakai nama field yang sudah ada (`eventSeq`, `ts`).
34
+ Bentuk wire eksternal harus versioned:
35
+
36
+ ```ts
37
+ interface OutputEventEnvelope {
38
+ schema: "minicode.output.v1"
39
+ eventId: string
40
+ type: OutputEventType
41
+ timestamp: string
42
+ sessionId: string
43
+ turnId?: number
44
+ stepId?: number
45
+ correlationId?: string
46
+ parentId?: string
47
+ source: "runtime" | "app" | "derived"
48
+ severity: "info" | "warning" | "error" | "critical"
49
+ status: "started" | "active" | "completed" | "failed" | "denied" | "cancelled" | "interrupted" | "partial" | "recovered"
50
+ visibility: Array<"normal" | "verbose" | "debug" | "machine">
51
+ payload: OutputEventPayload
52
+ }
53
+ ```
54
+
55
+ ### Aturan field
56
+
57
+ - `eventId` adalah identitas stabil event untuk consumer; bukan renderer-generated
58
+ string. Implementasi awal boleh memakai session/event sequence yang deterministik.
59
+ - `eventSeq` internal tetap urutan observasi per sesi, bukan causality.
60
+ - `correlationId` menunjuk tool call, approval, atau operasi mayor yang sedang berjalan.
61
+ - `parentId` hanya diisi untuk causality eksplisit: retry, child tool, atau turn parent.
62
+ - `source` membedakan fakta kernel, app-layer event, dan derived projection.
63
+ - `severity` tidak sama dengan `status`: `denied` adalah status, bukan severity.
64
+ - `visibility` dapat memiliki lebih dari satu mode; machine projection tidak boleh
65
+ bergantung pada scraping human text.
66
+ - `payload` tidak boleh menyimpan secret, credential, raw ANSI yang tidak perlu, atau
67
+ payload besar. Payload besar memakai `ContentRef`.
68
+
69
+ ## 3. Taxonomy
70
+
71
+ ### Session dan user
72
+
73
+ | Tipe | Producer | Meaning | Durable | Visibility default |
74
+ |---|---|---|---|---|
75
+ | `session.started` | composition root | sesi aplikasi siap | ya | machine/debug |
76
+ | `session.ended` | composition root | sesi ditutup/cleanup | ya | machine/debug |
77
+ | `user.message.received` | controller | input user dan prompt sanitized | ya sesuai session | normal |
78
+ | `user.approval.requested` | policy | approval harus diputuskan | ya | normal/machine |
79
+ | `user.approval.settled` | policy | keputusan allow/deny/cancel | ya | normal/machine |
80
+
81
+ `user.message.received` adalah semantic event, bukan string yang ditambahkan langsung
82
+ ke transcript. TUI boleh tetap melakukan echo visual, tetapi echo tersebut harus
83
+ merujuk pada entry yang sama.
84
+
85
+ ### Task dan plan
86
+
87
+ | Tipe | Producer | Meaning | Durable |
88
+ |---|---|---|---|
89
+ | `task.started` | adapter/driver | satu `session.run` dimulai | ya |
90
+ | `task.progress` | policy/tool/app | perubahan status yang bermakna | tidak; state terakhir tetap durable |
91
+ | `task.completed` | adapter/driver | turn selesai normal | ya |
92
+ | `task.failed` | adapter/driver | turn gagal dengan cause | ya |
93
+ | `task.cancelled` | adapter/driver | user/timeout/budget/parent cancel | ya |
94
+ | `plan.created` | planner/tool | rencana kerja yang akan datang | ya bila adopted |
95
+ | `plan.updated` | planner/tool | perubahan langkah/urutan | ya |
96
+ | `plan.step.started` | planner/tool | langkah aktif | ya |
97
+ | `plan.step.completed` | planner/tool | langkah selesai | ya |
98
+
99
+ `plan.*` tidak boleh merekam “membaca file”, “menjalankan grep”, atau “berpikir”.
100
+ Itu adalah activity. Plan hanya menyatakan future work yang sudah diputuskan.
101
+
102
+ ### Model dan reasoning
103
+
104
+ | Tipe | Producer | Meaning | Durable |
105
+ |---|---|---|---|
106
+ | `assistant.message.delta` | provider loop | potongan teks live | tidak |
107
+ | `assistant.message.completed` | adapter dari final result | assistant final message | ya |
108
+ | `assistant.message.truncated` | derived/content policy | final message dipotong oleh cap | ya |
109
+ | `assistant.reasoning.delta` | provider loop | potongan reasoning live | tidak |
110
+ | `assistant.reasoning.completed` | adapter/provider finalization | reasoning final/ref | ya; full payload best effort |
111
+ | `context.compacted` | MiniCore loop | context model dipadatkan | ya sebagai system event |
112
+
113
+ Delta tidak boleh menjadi satu-satunya bukti completion. Jika proses berhenti setelah
114
+ delta, rebuild harus menandai state sebagai `interrupted` atau `partial`, bukan
115
+ mengarang final message.
116
+
117
+ ### Tool dan filesystem
118
+
119
+ | Tipe | Producer | Meaning | Durable |
120
+ |---|---|---|---|
121
+ | `tool.started` | adapter dari execution | operasi tool dimulai | ya |
122
+ | `tool.progress` | tool/app, opsional | status internal berubah | tidak |
123
+ | `tool.completed` | adapter | operasi sukses | ya |
124
+ | `tool.failed` | adapter | operasi gagal | ya |
125
+ | `tool.denied` | adapter/policy | policy/permission menolak | ya |
126
+ | `tool.cancelled` | adapter | operasi dibatalkan | ya |
127
+ | `file.changed` | journal/checkpoint | ada paths yang committed | ya |
128
+ | `test.completed` | adapter/tool evidence | hasil test terstruktur | ya |
129
+ | `finding.detected` | `submit_result` terstruktur | temuan/evidence semantic eksplisit | ya bila berasal dari agent |
130
+ | `result.produced` | task finalizer | hasil/actionable conclusion | ya |
131
+ | `checkpoint.created` | checkpoint adapter | checkpoint evidence dan linkage turn | ya |
132
+ | `plan.updated` | planner/tool | rencana dan status langkah | ya bila adopted |
133
+ | `diagnostic.raised` | adapter/policy | diagnostic actionable | ya |
134
+
135
+ Tool `completed` harus membawa `summary`, `durationMs`, `expandRef`, dan bila ada
136
+ `receipt`. Tool `failed` harus membawa `cause`, `message`, `hint`, dan `expandRef`.
137
+ Tool `denied` harus membawa `reason`; `denied` tidak boleh berubah menjadi generic
138
+ `failed` hanya karena satu renderer tidak tahu policy.
139
+
140
+ ### Error, recovery, dan lifecycle
141
+
142
+ | Tipe | Meaning | Normal | Verbose | Debug/machine |
143
+ |---|---|---|---|---|
144
+ | `diagnostic.raised` | warning/configuration/recovery | ringkas | kategori + next action | cause/trace |
145
+ | `error.raised` | kegagalan yang perlu tindakan | actionable | source + detail | payload scrubbed |
146
+ | `recovery.started` | retry/fallback/compaction | “recovering” | strategi | reason/delay |
147
+ | `recovery.completed` | berhasil pulih | “recovered” | hasil | result |
148
+ | `recovery.failed` | strategi habis | status terminal | cause | full category |
149
+
150
+ Kategori error yang harus dibedakan:
151
+
152
+ - `USER_ERROR`
153
+ - `CONFIGURATION_ERROR`
154
+ - `PERMISSION_ERROR`
155
+ - `TOOL_ERROR`
156
+ - `FILESYSTEM_ERROR`
157
+ - `NETWORK_ERROR`
158
+ - `PROVIDER_ERROR`
159
+ - `MODEL_ERROR`
160
+ - `AGENT_ERROR`
161
+ - `INTERNAL_ERROR`
162
+
163
+ Recoverability adalah field terpisah:
164
+
165
+ - `RECOVERABLE`
166
+ - `RETRYABLE`
167
+ - `ACTION_REQUIRED`
168
+ - `FATAL`
169
+ - `UNKNOWN`
170
+
171
+ ## 4. State machine
172
+
173
+ ### Task
174
+
175
+ ```text
176
+ started → active → completed
177
+ ├────→ failed
178
+ ├────→ cancelled
179
+ └────→ partial → active | completed | failed
180
+ ```
181
+
182
+ `cancelled`, `failed`, dan `interrupted` tidak boleh saling menggantikan.
183
+ `interrupted` hanya boleh muncul dari rebuild ketika durable evidence menunjukkan
184
+ proses berhenti sebelum terminal event.
185
+
186
+ ### Tool
187
+
188
+ ```text
189
+ started → running → completed
190
+ ├→ failed
191
+ ├→ denied
192
+ └→ cancelled
193
+ ```
194
+
195
+ First-terminal-wins: terminal kedua untuk `toolCallId` yang sama diabaikan dan
196
+ dicatat sebagai anomaly. Tool yang tidak punya `started` tetap boleh direkonstruksi
197
+ sebagai `incomplete`, tetapi harus ditandai di diagnostics.
198
+
199
+ ### Approval
200
+
201
+ ```text
202
+ requested → settled { allow | allow-always | deny | cancelled }
203
+ ```
204
+
205
+ Saat parent task settle, approval `requested` yang masih terbuka harus di-force-close
206
+ menjadi `cancelled(parent-ended)`. Saat rebuild/crash, hal yang sama terjadi dengan
207
+ alasan parent-ended; outcome tidak boleh tetap `requested`.
208
+
209
+ ## 5. Ordering, correlation, causality, hierarchy
210
+
211
+ Empat concept dipisahkan:
212
+
213
+ 1. **Ordering:** urutan observasi event. Adaptor menetapkan `eventSeq`; ini bukan
214
+ urutan penyebab.
215
+ 2. **Correlation:** ID yang stabil: `toolCallId`, `approvalId`, `correlationId`.
216
+ 3. **Causality:** link eksplisit `supersedes`, `parentToolCallId`, atau approval link.
217
+ 4. **Hierarchy:** `sessionId → turnId → stepId → toolCallId`; child session membawa
218
+ parent link.
219
+
220
+ Tidak boleh menyimpulkan “B menyebabkan A” hanya karena `B.eventSeq > A.eventSeq`.
221
+ Tool paralel boleh tiba/selesai dalam urutan berbeda; setiap call tetap punya ID dan
222
+ duration sendiri.
223
+
224
+ ## 6. Durable versus live
225
+
226
+ | Kategori | Contoh | Simpan | Rebuild |
227
+ |---|---|---|---|
228
+ | Lifecycle | task/tool terminal, approval | ya | ya |
229
+ | Final semantic content | message, result, plan, finding | ya | ya |
230
+ | Evidence ringkas | receipt, test summary, checkpoint | ya | ya |
231
+ | Live stream | model/reasoning delta, progress | tidak | tidak diperlukan |
232
+ | Derived heartbeat | spinner, elapsed tick | tidak | dihitung dari timestamp |
233
+ | Large content | tool output penuh | ref/store best effort | resolver bila tersedia |
234
+
235
+ `eventSeq` boleh dipotong pada delta, tetapi harus tetap menghasilkan replay yang
236
+ deterministik untuk event durable. Rebuild tidak boleh memerlukan token-by-token history.
237
+
238
+ ## 7. Trust dan sanitasi
239
+
240
+ - Event internal boleh menyimpan diagnostic context, tetapi payload machine/wire harus
241
+ melalui `scrubSecrets()` dan JSON-safe encoding.
242
+ - Nama tool, path, command, provider label, dan output model adalah untrusted display
243
+ data. Sanitasi control sequence dilakukan di boundary ingestion atau projection,
244
+ bukan hanya di satu renderer.
245
+ - `NO_COLOR` dan non-TTY berarti SGR tidak boleh menjadi makna. Status tetap punya
246
+ glyph + kata atau struktur teks.
247
+ - Selection/copy payload berasal dari source map yang sudah disanitasi; tidak boleh
248
+ menyalin escape, padding, atau border tabel.
249
+ - Event diagnostic internal default `debug`; warning yang actionable default
250
+ `normal`; payload mentah default `debug/machine` dengan scrub.
251
+
252
+ Phase 2 now wires producers for `reasoning.completed`, `plan.updated`,
253
+ `finding.detected`, `result.produced`, `diagnostic.raised`, `test.completed`, and
254
+ `checkpoint.created`. Only `tool.progress` remains proposed because it is
255
+ intentionally live-only.
256
+
257
+ ## 8. Invariant
258
+
259
+ - I-A01: renderer tidak memiliki kebenaran runtime maupun presentation.
260
+ - I-A02: setiap execution user-visible membawa `toolCallId` stabil end-to-end.
261
+ - I-A03: setiap tool terminal memiliki tepat satu final status.
262
+ - I-A04: state tidak menyimpan terminal geometry, timer, widget, atau payload besar.
263
+ - I-A05: reducer murni; event yang sama menghasilkan state yang sama.
264
+ - I-A06: payload besar selalu `ContentRef` dan evict selalu ber-marker.
265
+ - I-A07: retry adalah call baru dengan link `supersedes`, bukan attempt ID buatan.
266
+ - I-A08: approval tidak boleh tetap requested setelah parent settle/rebuild.
267
+ - I-A09: causality hanya melalui link eksplisit.
268
+ - I-A10: TUI/linear/exec/ACP memakai status, identity, duration, cause, receipt, dan
269
+ lifecycle yang sama.
270
+ - I-A11: context compaction tidak menghapus presentation history.
271
+ - I-A12: `interrupted`, `failed`, dan `cancelled` eksplisit berbeda.
272
+
273
+ ## 9. Status migrasi dari implementasi sekarang
274
+
275
+ | Implementasi sekarang | Target event | Migrasi |
276
+ |---|---|---|
277
+ | `turn:started` | `task.started` | adapter map, pertahankan turn ID |
278
+ | `turn:completed` | `task.completed` | tambahkan summary/receipt-derived fields |
279
+ | `noteRunSettled` | `task.failed/cancelled` | jadikan satu settlement path |
280
+ | `provider:text` | `assistant.message.delta` | stream policy di projection |
281
+ | `TurnResult.finalText` | `assistant.message.completed` | event final eksplisit |
282
+ | `execution:*` | `tool.*` | normalisasi di adapter |
283
+ | permission hooks | `approval.requested/settled` | outcome enum tunggal |
284
+ | journal callback | `file.changed` | link ke activity/turn |
285
+ | `tool.progress` | `tool.progress` | optional live-only, jangan durable |
286
+ | `context:compacted` | `context.compacted` | system entry, bukan compaction history |
287
+
288
+ Selama migrasi, raw event tetap boleh dibaca untuk diagnostics; setiap surface
289
+ user-facing baru harus berasal dari canonical projection.
@@ -0,0 +1,391 @@
1
+ # Output Architecture Implementation Plan
2
+
3
+ **Status:** Phase 1–8 landed; canonical presentation policy is active on all user-facing surfaces. Legacy ACP `type:"tool"` remains a compatibility window.
4
+ **Tanggal:** 2026-09-25
5
+ **Related:** `docs/OUTPUT_ARCHITECTURE_AUDIT.md`, `docs/OUTPUT_EVENT_MODEL.md`, `docs/OUTPUT_PROTOCOL_SPEC.md`, `docs/OUTPUT_RENDERING_SPEC.md`, `docs/OUTPUT_UX_RULES.md`
6
+
7
+ ## 1. Keputusan
8
+
9
+ Migrasi bersifat incremental dan dapat dibalik:
10
+
11
+ ```text
12
+ raw runtime events
13
+ → canonical semantic events
14
+ → pure PresentationState
15
+ → policy projection
16
+ → TUI / linear / exec / ACP
17
+ ```
18
+
19
+ Tidak melakukan rewrite `vendor/minicore/**`, tidak mengganti terminal primitives,
20
+ dan tidak menghapus jalur lama sebelum parity contract serta satu rollout flag-on
21
+ terbukti.
22
+
23
+ ## 2. Baseline saat plan dibuat
24
+
25
+ - Mouse wheel/drag app-level selection, `/copy [n]`, Esc-only abort, popup lifecycle,
26
+ sanitasi, width, and terminal ownership are already implemented in the working tree.
27
+ - Current baseline after Phase 2–8: 2587 pass, 22 skip, 0 fail; coverage 84.52% funcs /
28
+ 85.53% lines; pack 23/23; web build/check pass.
29
+ - `PresentationAdapter`/reducer drive all user-facing surfaces through the
30
+ canonical state; raw ledger TUI and the rollback flag were removed in Phase 8.
31
+ - `rebuildFromDurable()` is production-wired from the durable presentation event
32
+ table, with child-session event persistence and interrupted-state recovery.
33
+ - The pack size guard is 3.5 MiB (re-baselined from 2.25 MiB with owner approval in Quality Remediation Stage 8.1, because the runtime payload itself grew past the old 2.25 MiB line — see `scripts/pack-budget.ts` for the measurement basis): six required audit artifacts add about 80 KB; the guard still rejects forbidden runtime/test content and accidental dependency inclusion.
34
+ - OAP-001, OAP-002, OAP-004–OAP-010, OAP-012, and OAP-013 remain carried forward;
35
+ Phase 2 closes the state/receipt/replay slice, not renderer migration.
36
+
37
+ ## 3. Hasil Phase 1
38
+
39
+ - `user.message` sekarang durable di `DomainEvent` dan direduksi ke
40
+ `ConversationEntry` tanpa menggandakan turn.
41
+ - `toPresentationEvent()` di `cli/setup.ts` memetakan seluruh 20
42
+ `DomainEventType`, termasuk model/reasoning/file/test/context/progress.
43
+ - `PROPOSED_EVENT_TYPES` menandai `reasoning.completed`, `tool.progress`, dan
44
+ `test.completed` sebagai event tanpa producer; mapper tidak mengarangnya.
45
+ - `unsupportedProjection` diagnostics dan fixture exhaustive menjaga bridge
46
+ agar event baru tidak diam-diam dropped.
47
+ - Historical Phase 1 snapshot: 2581 pass / 22 skip / 0 fail. At that point the
48
+ renderer still used the raw bus and Phase 4 had not started.
49
+
50
+ ## 3.1 Hasil Phase 2 core
51
+
52
+ - `PresentationState` sekarang memiliki collection conversation, reasoning, system,
53
+ plan, finding, result, diagnostic, serta marker eviction bounded.
54
+ - `deriveTurnSummary()` menghitung status tool, unique normalized paths, test
55
+ aggregate, checkpoint, duration dari timestamp, dan late evidence tanpa clock/IO.
56
+ - `file.changed`/`test.completed` yang tiba sebelum atau sesudah activity terminal
57
+ tetap masuk sebagai evidence; checkpoint callback sekarang memancarkan
58
+ `checkpoint.created` semantic event.
59
+ - `presentation_events` SQLite table menyimpan durable event idempotent, scrubbed,
60
+ dan TERMINAL/branch/TTL/delete-aware; setup memuat dan rebuild-nya sebelum
61
+ adapter-seq baru dibuat.
62
+ - Historical migration detail: before Phase 8,
63
+ `MINICODE_PRESENTATION_V2=0` disabled shadow projection/replay while the raw
64
+ content stream remained available. Child sessions also wrote their own
65
+ semantic event log.
66
+ - Regression tests: semantic collections, summary late evidence, cross-session
67
+ identity, bounded eviction, persistence idempotency/scrubbing, checkpoint bridge,
68
+ adapter provider, branch/child/delete/TTL lifecycle, dan resume rebuild.
69
+ - Setiap event terminal kini memakai `eventSeq` unik; basis bersama sebelumnya
70
+ membuat `INSERT OR IGNORE` durable melewatkan event berikutnya.
71
+ - Phase 2 parity landed: contract restart/child/resume/branch/delete/TTL diuji;
72
+ `finding.detected` terbit dari `result.findings` eksplisit pada
73
+ `submit_result`; `test.completed` hanya terbit dari verify output yang memiliki
74
+ hitungan pass/fail terstruktur.
75
+
76
+ ## 3.2 Hasil Phase 3–8
77
+
78
+ - Phase 3: modul policy murni `src/presentation/projection.ts` (seleksi node per
79
+ mode, deskripsi activity/turn, running pin + ambang elapsed, envelope
80
+ `minicode.output.v1`, kategori error machine, digest divergensi) + 14 test
81
+ policy tabel-driven.
82
+ - Phase 4/5: TUI dan linear memakai keputusan policy via injeksi `cli/`
83
+ (`PresentationPolicy`); parity test policy-vs-legacy identik; label turn-status
84
+ via `activityFor`; test inventaris writer OAP-008.
85
+ - Phase 6: `exec --json` streaming envelope kanonik + summary berversi + setup
86
+ failure selalu ber-envelope; ACP lifecycle penuh + cancel terminal + persist
87
+ headless; sanitasi ANSI + scrub di tepi mesin.
88
+ - Phase 7: `persistCurrent` di jalur headless exec/ACP; resume notice tetap
89
+ stderr mesin-aman; ambang coverage naik ke 84/85.
90
+ - Phase 8: rollback flag dihapus, raw ledger TUI + `targetForFallback` dihapus
91
+ (3 test dimigrasi ke event presentasi); legacy `type:"tool"` ACP dipertahankan
92
+ satu jendela kompat; queue durable dibatasi, result generic diringkas, dan
93
+ buffer/render TUI dibatasi; full gate hijau.
94
+
95
+ ## 4. Fase migrasi
96
+
97
+ Every phase has a rollback boundary. A phase is complete only when its tests and
98
+ the repository gates are green.
99
+
100
+ ### Phase 0 — Baseline and contract lock
101
+
102
+ **Goal:** make the current behavior measurable before changing its source.
103
+
104
+ **Files/modules:** `test/presentation-*.test.ts`, `test/tui-*.test.ts`,
105
+ `test/acp.test.ts`, `test/exec-json-envelope.test.ts`, `test/pty.test.ts`,
106
+ `docs/TERMINAL_CONTRACT.md`.
107
+
108
+ **Dependencies:** none.
109
+
110
+ **Behavior changes:** none.
111
+
112
+ **Risks:** flaky fake TTY/ConPTY tests may hide platform-specific output drift.
113
+
114
+ **Tests/gates:** capture golden fixtures for normal/verbose/exec/ACP; run full test,
115
+ coverage, pack, and web check; record skip reasons explicitly.
116
+
117
+ **Migration/rollback:** documentation/test-only; revert isolated fixture commit if
118
+ fixture is unstable.
119
+
120
+ ### Phase 1 — Canonical event boundary and exhaustive projection
121
+
122
+ **Goal:** make all semantic events explicit and stop silent bridge drops.
123
+
124
+ **Files/modules:** `src/presentation/events.ts`, `src/presentation/adapter.ts`,
125
+ `src/ui/contract.ts`, `cli/setup.ts`; approval hooks in
126
+ `src/ui/approval/prompt.ts` and policy path only as needed.
127
+
128
+ **Dependencies:** OAP-002/OAP-003 decisions; preserve raw event compatibility.
129
+
130
+ **Behavior changes:** add `user.message`, `reasoning.completed`, file/test/context/
131
+ diagnostic projection where a real producer exists; retain current raw event names
132
+ during migration. Missing producer events are marked proposed, not fabricated.
133
+
134
+ **Risks:** double-emission if adapter and existing sinks both publish terminal lines;
135
+ exhaustive mapper may expose existing anomalies.
136
+
137
+ **Tests/gates:** every DomainEvent has producer-or-proposed status; every event type
138
+ has a consumer/projection test; duplicate/late/out-of-order fixtures; no throw from
139
+ mapper.
140
+
141
+ **Migration/rollback:** flag and raw TUI ledger were removed in Phase 8; the
142
+ runtime EventBus remains only for streaming content and debug/trace transport.
143
+
144
+ ### Phase 2 — Complete presentation state and truthful summaries
145
+
146
+ **Status:** landed; state/reducer is replayable and renderer authority is wired.
147
+
148
+ **Goal:** make `PresentationState` a replayable semantic model, not a partial index.
149
+
150
+ **Files/modules:** `src/presentation/model.ts`, `reducer.ts`, `store.ts`,
151
+ `label.ts`, `adapter.ts`, `src/tools/submit_result.ts`, journal/checkpoint
152
+ adapters in `cli/setup.ts`, dan child wiring di `cli/index.ts`.
153
+
154
+ **Dependencies:** Phase 1; durable store format.
155
+
156
+ **Behavior changes:** add user/conversation, reasoning, system, plan, finding, result,
157
+ and diagnostic collections; compute `filesChanged`, receipts, test summary, and
158
+ checkpoint from events/journal rather than constants.
159
+
160
+ **Risks:** increased memory and migration of `/expand`/copy semantics; payload cap must
161
+ remain explicit.
162
+
163
+ **Tests/gates:** replay durable == live minus deltas; state bounded; evict marker;
164
+ receipt counts truthful; restart test from session/journal evidence; reducer purity
165
+ and no clock/IO grep.
166
+
167
+ **Migration/rollback:** keep old `getPresentationSnapshot()` output as a compatibility
168
+ adapter until all consumers pass.
169
+
170
+ ### Phase 3 — Shared projection policy
171
+
172
+ **Status:** landed (`src/presentation/projection.ts` + `test/presentation-policy.test.ts` + parity harness TUI/linear).
173
+
174
+ **Goal:** one state to normal/verbose/debug/machine projections.
175
+
176
+ **Files/modules:** new pure projection module under `src/presentation/`, label/format
177
+ boundaries; no import from `src/ui` into `src/presentation`.
178
+
179
+ **Dependencies:** Phase 2; i18n keys and status vocabulary.
180
+
181
+ **Behavior changes:** visual verbosity and disclosure become policy decisions; TUI
182
+ layout, linear wrapping, and machine JSON remain different renderers but share
183
+ semantic node selection.
184
+
185
+ **Risks:** normal output becoming too sparse or verbose output becoming noisy.
186
+
187
+ **Tests/gates:** table-driven node policy tests; normal/verbose/debug/machine
188
+ snapshots; semantic parity assertions; no renderer status parsing.
189
+
190
+ **Migration/rollback:** projection ran beside the legacy path during rollout and
191
+ reported divergence; Phase 8 removed the rollout seam after parity.
192
+
193
+ ### Phase 4 — TUI projection (completed rollout)
194
+
195
+ **Status:** landed (policy di-inject via `cli/tui.ts`; raw TUI ledger and its rollback path were removed in Phase 8; parity tests remain as regression protection).
196
+
197
+ **Goal:** move TUI transcript/activity/selection to canonical state without breaking
198
+ current screen ownership.
199
+
200
+ **Files/modules:** `src/ui/tui/transcript.ts`, `src/ui/tui/app.ts`,
201
+ `src/ui/runtime/screen.ts` only where lifecycle wiring needs an explicit snapshot;
202
+ `cli/tui.ts` composition.
203
+
204
+ **Dependencies:** Phases 1–3; current selection/source-map tests; frozen terminal
205
+ contract.
206
+
207
+ **Behavior changes:** canonical terminal activity, summary, error, reasoning state;
208
+ existing transcript cap, evict marker, prompt/footer geometry, popup, wheel, drag,
209
+ Ctrl+C, Esc, and busy rules remain unchanged.
210
+
211
+ **Risks:** live deltas may arrive before durable model completion; selection anchors
212
+ can be evicted; resize may re-render different text source.
213
+
214
+ **Tests/gates:** existing TUI tests plus canonical-vs-legacy fixture; stream+resize+
215
+ abort+popup+selection fuzz; PTY on POSIX; transparent ConPTY skip.
216
+
217
+ **Migration/rollback:** the rollout flag was removed in Phase 8 after the parity
218
+ gate and release 0.12.0.
219
+
220
+ ### Phase 5 — Linear/one-shot projection and writer policy
221
+
222
+ **Status:** landed (keputusan status/suffix linear dari policy; `turn-status` label via `activityFor` DI; `test/writer-inventory.test.ts` mengunci OAP-008).
223
+
224
+ **Goal:** remove semantic decisions from `simple.ts` while preserving stdout/stderr
225
+ behavior and copy contents.
226
+
227
+ **Files/modules:** `src/ui/assistant/simple.ts`, `turn-status.ts`,
228
+ `src/ui/runtime/statusline.ts`, approval/command controllers, `cli/commands.ts`.
229
+
230
+ **Dependencies:** Phase 3; stream ownership inventory; i18n/table/selection contract.
231
+
232
+ **Behavior changes:** activity, error, summary, reasoning, and table disclosure from
233
+ projection; writer category decides stdout/stderr/transient.
234
+
235
+ **Risks:** duplicate ledger lines, reasoning duplication, non-TTY SGR regression,
236
+ answer `/copy` mismatch, direct console output from builtin commands.
237
+
238
+ **Tests/gates:** normal/verbose text fixtures, `NO_COLOR`, non-TTY, split stream,
239
+ abort/EOF, copy equivalence, table parity, direct-writer guard.
240
+
241
+ **Migration/rollback:** the rollout flag was removed after the parity gate in
242
+ Phase 8; raw handlers remain only where they carry streaming content, not
243
+ semantic status decisions.
244
+
245
+ ### Phase 6 — Exec and ACP machine projection
246
+
247
+ **Status:** landed (`exec --json` = envelope `minicode.output.v1` + summary berversi; ACP lifecycle penuh + cancel terminal + persist headless; legacy `type:"tool"` hanya bila lifecycle absen).
248
+
249
+ **Goal:** give CI/IDE consumers a stable semantic protocol.
250
+
251
+ **Files/modules:** `cli/commands/exec.ts`, `cli/commands/acp.ts`,
252
+ `src/ui/contract.ts`, `src/presentation/` machine mapper, `src/policy/scrub.ts` use.
253
+
254
+ **Dependencies:** Phase 1 event envelope; Phase 2 snapshots; protocol spec.
255
+
256
+ **Behavior changes:** versioned `minicode.output.v1`; canonical lifecycle in exec/ACP;
257
+ human semantic raw event output is debug-only while text deltas remain a transport;
258
+ setup failure always emits terminal machine summary; ACP cancel/shutdown guarantees
259
+ explicit terminal response.
260
+
261
+ **Risks:** breaking existing integrations; duplicate text/lifecycle records; scrub
262
+ changes alter payload shape.
263
+
264
+ **Tests/gates:** wire-level JSON/ACP fixtures, malformed input, setup failure, cancel
265
+ race, shutdown race, secret/control-byte scrub, no ANSI/stdout contamination, exit
266
+ codes 0/1/2.
267
+
268
+ **Migration/rollback:** support legacy event names for one compatibility window;
269
+ switch machine flag independently from TUI/linear only if contract tests allow.
270
+
271
+ ### Phase 7 — Durable resume and legacy direct-writer migration
272
+
273
+ **Status:** landed (`persistCurrent` di jalur headless exec/ACP; setup-failure selalu ber-envelope; writer inventory test; resume notice tetap stderr mesin-aman).
274
+
275
+ **Goal:** make crash/restart observable through the same semantic model and centralize
276
+ permanent/diagnostic writer categories.
277
+
278
+ **Files/modules:** `session/persistence`, `session/journal`, `turn-marker`,
279
+ `checkpoint`, `cli/setup.ts`, CLI controllers, popup/form/input fallbacks.
280
+
281
+ **Dependencies:** Phase 2; chosen durable event format; no changes to kernel vendor.
282
+
283
+ **Behavior changes:** resume rebuilds state; interrupted/partial markers visible;
284
+ new direct writes require category/owner.
285
+
286
+ **Risks:** migration from existing session files; old sessions lack event metadata;
287
+ foreign stderr writer compatibility.
288
+
289
+ **Tests/gates:** crash marker + pending journal + resume; exit/signal cleanup; writer
290
+ inventory test; machine/non-TTY safety.
291
+
292
+ **Migration/rollback:** old session path remains fallback; disable only new writer
293
+ route, not persistence.
294
+
295
+ ### Phase 8 — Shadow removal and cleanup
296
+
297
+ **Status:** landed — flag `MINICODE_PRESENTATION_V2` dihapus, raw ledger TUI dihapus (migrasi 3 test ke event presentasi), parity policy-vs-legacy tetap hijau; legacy `type:"tool"` ACP dipertahankan satu jendela kompat.
298
+
299
+ **Goal:** after rollout, eliminate duplicate truth and dead paths.
300
+
301
+ **Files/modules:** remove raw presentation subscriptions from user-facing surfaces,
302
+ retire legacy label/collapse/diagnostic classification only after usage inventory.
303
+
304
+ **Dependencies:** one release or equivalent validated rollout; all gates green.
305
+
306
+ **Behavior changes:** output remains same as canonical projection; direct diagnostic
307
+ fallback only for explicitly external writers.
308
+
309
+ **Risks:** hidden consumers or scripts relying on legacy raw output.
310
+
311
+ **Tests/gates:** full suite, PTY, protocol compatibility fixtures, `git diff --check`,
312
+ architecture/UI boundary tests, pack/web checks.
313
+
314
+ **Migration/rollback:** revert the isolated removal commit; do not combine cleanup with
315
+ semantic changes.
316
+
317
+ ## 5. Finding-to-phase map
318
+
319
+ | Finding | Primary phase | Secondary gate |
320
+ |---|---:|---|
321
+ | OAP-001 dual truth | 1–4 | parity fixtures |
322
+ | OAP-002 lifecycle loss | 1 | adapter failure/cancel tests |
323
+ | OAP-003 partial bridge | 1 | exhaustive projection test |
324
+ | OAP-004 incomplete model | 2 | replay/model tests |
325
+ | OAP-005 summary/receipt | 2 | journal/checkpoint test |
326
+ | OAP-006 machine protocol | 6 | wire contract |
327
+ | OAP-007 durable rebuild | 7 | resume/crash test |
328
+ | OAP-008 direct writers | 5/7 | writer inventory |
329
+ | OAP-009 visibility | 3 | mode fixtures |
330
+ | OAP-010 classification | 1/3 | canonical outcome tests |
331
+ | OAP-011 unused vocabulary | 1 | producer inventory |
332
+ | OAP-012 user/plan/finding | 2/3 | semantic node tests |
333
+ | OAP-013 docs drift | 0/10 | docs link/protection test |
334
+
335
+ ## 6. Validation scenarios
336
+
337
+ | # | Scenario | Required verification |
338
+ |---:|---|---|
339
+ | 1 | Simple coding task | one final message, no duplicate completion, machine summary |
340
+ | 2 | Multi-file edit | receipt paths, truthful file count, chronological order |
341
+ | 3 | Tool success | tool completed + duration + expand ref |
342
+ | 4 | Tool failure | failed cause/hint, no generic success |
343
+ | 5 | Permission denial | denied category/reason, headless explicit |
344
+ | 6 | Cancellation | task/tool cancelled, stream flushed/discarded once |
345
+ | 7 | Retry | new call + deterministic supersedes relation |
346
+ | 8 | Long-running task | active state, elapsed, no fake spam |
347
+ | 9 | Parallel analysis | grouped/aggregated, independent IDs |
348
+ | 10 | Large tool output | cap marker, content ref, expand behavior |
349
+ | 11 | Narrow terminal | 20/30/80 columns, no overflow, cursor safe |
350
+ | 12 | Resize | 120→30→80, transcript/source mapping stable |
351
+ | 13 | Ctrl+C | TUI copy-or-noop, Esc cancellation, raw cleanup |
352
+ | 14 | No-color/limited ANSI | status words, ASCII fallback, no meaning loss |
353
+ | 15 | Verbose | useful detail without internal dump |
354
+ | 16 | Debug | scrubbed IDs/payloads and anomaly counters |
355
+ | 17 | Machine-readable | versioned NDJSON/ACP, no human stream contamination |
356
+
357
+ For every scenario verify semantic correctness, hierarchy, scrollback, error clarity,
358
+ noise, copyability, and mode consistency.
359
+
360
+ ## 7. Rollout and rollback
361
+
362
+ - The rollout is complete: policy is injected at the composition root, raw TUI
363
+ semantic ledger and the feature flag are removed, and streaming content remains
364
+ a transport concern.
365
+ - Before any future semantic cleanup, run the parity and writer-inventory gates;
366
+ do not reintroduce a second status authority.
367
+ - If a protocol field is consumed, preserve compatibility aliases for one window.
368
+ - Update `docs/TERMINAL_CONTRACT.md` only when observable terminal behavior changes;
369
+ update its test map in the same change.
370
+ - Update `docs/ARCHITECTURE.html` when structure/dependencies change.
371
+
372
+ ## 8. Completion criteria
373
+
374
+ The architecture is complete only when:
375
+
376
+ - semantic events are independent from rendering;
377
+ - runtime state is not accidentally exposed as normal UI;
378
+ - normal/verbose/debug/machine projections use one model;
379
+ - findings, plans, activities, errors, and results are distinct;
380
+ - permission, cancellation, timeout, partial, and interrupted states are explicit;
381
+ - parallel work is aggregated;
382
+ - TUI scrollback, copy/paste, Windows, no-color, and resize contracts remain intact;
383
+ - machine output is structured and versioned;
384
+ - durable resume can rebuild semantic state;
385
+ - legacy direct-print paths are inventoried and removed only after parity;
386
+ - all mandatory repository gates pass.
387
+
388
+ ## 9. Current next action
389
+
390
+ Phase 1–8 landed. The current follow-up is limited to documentation drift and
391
+ post-change validation; keep future cleanup isolated from semantic changes.