@iowarp/clio-coder 0.3.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 (226) hide show
  1. package/CHANGELOG.md +407 -0
  2. package/CODE_OF_CONDUCT.md +21 -0
  3. package/CONTRIBUTING.md +224 -0
  4. package/LICENSE +202 -0
  5. package/NOTICE +9 -0
  6. package/README.md +798 -0
  7. package/SECURITY.md +72 -0
  8. package/assets/clio-coder-logo-128.webp +0 -0
  9. package/damage-control-rules.yaml +419 -0
  10. package/dist/acp-UMLFVA3F.js +92 -0
  11. package/dist/agents-Q4MYPMUW.js +91 -0
  12. package/dist/auth-O6HYIJ6J.js +521 -0
  13. package/dist/chunk-262G75JS.js +35 -0
  14. package/dist/chunk-26BZQOAD.js +1281 -0
  15. package/dist/chunk-2J63S4SF.js +508 -0
  16. package/dist/chunk-3DANZDGR.js +717 -0
  17. package/dist/chunk-4UQA7NCT.js +29 -0
  18. package/dist/chunk-527KG6XR.js +497 -0
  19. package/dist/chunk-5LDRNKX2.js +1063 -0
  20. package/dist/chunk-5N2FG33Q.js +25 -0
  21. package/dist/chunk-67MTHP2E.js +135 -0
  22. package/dist/chunk-6CWDTGUC.js +20 -0
  23. package/dist/chunk-7BHLZB3A.js +2115 -0
  24. package/dist/chunk-7RBKDI66.js +348 -0
  25. package/dist/chunk-AMFR5YA3.js +541 -0
  26. package/dist/chunk-BBUH4VAA.js +1224 -0
  27. package/dist/chunk-BYEU76JP.js +899 -0
  28. package/dist/chunk-CLJ5HLUD.js +458 -0
  29. package/dist/chunk-D5YD55AR.js +116 -0
  30. package/dist/chunk-DXQNI4PC.js +61 -0
  31. package/dist/chunk-E3NYWENM.js +1004 -0
  32. package/dist/chunk-GNGDQYDU.js +34688 -0
  33. package/dist/chunk-GOTUR54M.js +9 -0
  34. package/dist/chunk-HBU5MTAM.js +41 -0
  35. package/dist/chunk-HMYNFFY4.js +28 -0
  36. package/dist/chunk-JPOWPFCU.js +1010 -0
  37. package/dist/chunk-JWHCJDCI.js +1215 -0
  38. package/dist/chunk-KBR4MZZR.js +41 -0
  39. package/dist/chunk-KKKPTZLM.js +93 -0
  40. package/dist/chunk-ME6DNWIU.js +66 -0
  41. package/dist/chunk-NI4DEJMC.js +88 -0
  42. package/dist/chunk-O4EJEDHO.js +659 -0
  43. package/dist/chunk-PIDUD6M2.js +31 -0
  44. package/dist/chunk-PS4PFJQP.js +29459 -0
  45. package/dist/chunk-QV47YRF4.js +48 -0
  46. package/dist/chunk-RQDWMVRB.js +279 -0
  47. package/dist/chunk-TFSSEXL6.js +136 -0
  48. package/dist/chunk-TKHQ4DGZ.js +8290 -0
  49. package/dist/chunk-TPOCL34A.js +2876 -0
  50. package/dist/chunk-UGYAX5YI.js +565 -0
  51. package/dist/chunk-UHTSULZS.js +461 -0
  52. package/dist/chunk-UU3R62TT.js +128 -0
  53. package/dist/chunk-UWIJNAOB.js +3906 -0
  54. package/dist/chunk-VOO7NYPP.js +914 -0
  55. package/dist/chunk-VPAWTYLY.js +117 -0
  56. package/dist/chunk-WD6AJM35.js +1216 -0
  57. package/dist/chunk-X3BR7HWV.js +115 -0
  58. package/dist/chunk-X3NE4WVW.js +120 -0
  59. package/dist/chunk-XNISANGE.js +1395 -0
  60. package/dist/chunk-XV4ZJ6ZM.js +3177 -0
  61. package/dist/cli/index.js +236 -0
  62. package/dist/clio-KIQ5SNDS.js +53 -0
  63. package/dist/components-JVHMUBEB.js +653 -0
  64. package/dist/config-ZFCDBMDC.js +372 -0
  65. package/dist/configure-G4E3A2PG.js +27 -0
  66. package/dist/context-CDXTP2MP.js +293 -0
  67. package/dist/context-E3KIFVXI.js +185 -0
  68. package/dist/context-clear-3F4PLXOS.js +102 -0
  69. package/dist/context-index-Q7YSYTR3.js +106 -0
  70. package/dist/docs-YIETIWZI.js +280 -0
  71. package/dist/doctor-M5HJJZOL.js +61 -0
  72. package/dist/domains/agents/builtins/architect.md +33 -0
  73. package/dist/domains/agents/builtins/coder.md +31 -0
  74. package/dist/domains/agents/builtins/context-bootstrap.md +38 -0
  75. package/dist/domains/agents/builtins/debugger.md +30 -0
  76. package/dist/domains/agents/builtins/documenter.md +31 -0
  77. package/dist/domains/agents/builtins/git-master.md +30 -0
  78. package/dist/domains/agents/builtins/provenance.md +30 -0
  79. package/dist/domains/agents/builtins/researcher.md +71 -0
  80. package/dist/domains/agents/builtins/scout.md +42 -0
  81. package/dist/domains/agents/builtins/tester.md +31 -0
  82. package/dist/domains/agents/builtins/verifier.md +30 -0
  83. package/dist/domains/agents/builtins/wiki-writer.md +41 -0
  84. package/dist/eval-B3KZZESM.js +2674 -0
  85. package/dist/evidence-V67CHM35.js +233 -0
  86. package/dist/evolve-YDZSUQYA.js +518 -0
  87. package/dist/extensions-SRG7XCAH.js +207 -0
  88. package/dist/fleet-CA2CRTVG.js +760 -0
  89. package/dist/fleet-preflight-CLIAX7YR.js +21 -0
  90. package/dist/init-2OZDJE2D.js +227 -0
  91. package/dist/memory-3PIQQAKX.js +207 -0
  92. package/dist/models-DY35XI7Y.js +237 -0
  93. package/dist/paths-5OMXW7Z4.js +57 -0
  94. package/dist/preload-KZVHET2B.js +11 -0
  95. package/dist/reset-PIFYNOS3.js +216 -0
  96. package/dist/run-3VSPP24F.js +735 -0
  97. package/dist/share-D36RQCXM.js +241 -0
  98. package/dist/skills-F2MRLELY.js +445 -0
  99. package/dist/skills-eval-E2ZTW4PL.js +932 -0
  100. package/dist/targets-DZMEZAH4.js +977 -0
  101. package/dist/trace-7NYCUI2J.js +250 -0
  102. package/dist/uninstall-AD3JWHBB.js +322 -0
  103. package/dist/upgrade-WYYBKGDY.js +301 -0
  104. package/dist/usage-ULIDAGFF.js +755 -0
  105. package/dist/version-ROZ6CZKH.js +16 -0
  106. package/dist/wiki-generate-PKFIX6OB.js +377 -0
  107. package/dist/worker/entry.js +1739 -0
  108. package/docs/README.md +93 -0
  109. package/docs/acp.md +120 -0
  110. package/docs/alcf-provider.md +72 -0
  111. package/docs/architecture.md +172 -0
  112. package/docs/artifact-versions.md +54 -0
  113. package/docs/built-in-agents.md +265 -0
  114. package/docs/capacity-and-scheduling.md +97 -0
  115. package/docs/commands-and-modes.md +554 -0
  116. package/docs/config-knobs-audit.md +115 -0
  117. package/docs/configuration-and-targets.md +812 -0
  118. package/docs/context-engine.md +236 -0
  119. package/docs/dispatch-architecture-rationale.md +126 -0
  120. package/docs/documentation-coverage.md +46 -0
  121. package/docs/documentation-guide.md +166 -0
  122. package/docs/environment-variables.md +105 -0
  123. package/docs/eval-runner.md +205 -0
  124. package/docs/evals-internal.md +298 -0
  125. package/docs/evidence-and-memory.md +243 -0
  126. package/docs/evolution.md +143 -0
  127. package/docs/exit-codes-and-output.md +74 -0
  128. package/docs/extensions-and-sharing.md +306 -0
  129. package/docs/fleet-demo-runbook.md +179 -0
  130. package/docs/fleet-dispatch.md +591 -0
  131. package/docs/glossary.md +75 -0
  132. package/docs/html/agents_blueprint.html +936 -0
  133. package/docs/html/alcf_blueprint.html +324 -0
  134. package/docs/html/architecture_blueprint.html +850 -0
  135. package/docs/html/commands_blueprint.html +794 -0
  136. package/docs/html/config_knobs_audit_blueprint.html +178 -0
  137. package/docs/html/configuration_blueprint.html +1080 -0
  138. package/docs/html/context_blueprint.html +603 -0
  139. package/docs/html/documentation_blueprint.html +832 -0
  140. package/docs/html/environment_blueprint.html +404 -0
  141. package/docs/html/eval_blueprint.html +743 -0
  142. package/docs/html/evals_internal_blueprint.html +190 -0
  143. package/docs/html/evolution_blueprint.html +674 -0
  144. package/docs/html/extensions_blueprint.html +2065 -0
  145. package/docs/html/fleet_dispatch_blueprint.html +286 -0
  146. package/docs/html/index.html +919 -0
  147. package/docs/html/lifecycle_blueprint.html +723 -0
  148. package/docs/html/memory_blueprint.html +699 -0
  149. package/docs/html/middleware_blueprint.html +664 -0
  150. package/docs/html/models_blueprint.html +2366 -0
  151. package/docs/html/observability_blueprint.html +683 -0
  152. package/docs/html/provider_adapter_blueprint.html +245 -0
  153. package/docs/html/safety_blueprint.html +1386 -0
  154. package/docs/html/shared.css +571 -0
  155. package/docs/html/shared.js +143 -0
  156. package/docs/html/skills_blueprint.html +671 -0
  157. package/docs/html/soak_blueprint.html +182 -0
  158. package/docs/html/tool_usage_blueprint.html +350 -0
  159. package/docs/html/tools_blueprint.html +2249 -0
  160. package/docs/html/trace_blueprint.html +235 -0
  161. package/docs/html/tui_design_blueprint.html +314 -0
  162. package/docs/html/validation_blueprint.html +961 -0
  163. package/docs/html/worker_dispatch_blueprint.html +231 -0
  164. package/docs/installation-and-lifecycle.md +308 -0
  165. package/docs/middleware-and-components.md +148 -0
  166. package/docs/model-catalog.md +189 -0
  167. package/docs/observability.md +233 -0
  168. package/docs/proactive-memory.md +452 -0
  169. package/docs/prompt-envelope-and-tools.md +142 -0
  170. package/docs/provider-adapter-cookbook.md +148 -0
  171. package/docs/release-cut-checklist.md +138 -0
  172. package/docs/safety-model.md +357 -0
  173. package/docs/scientific-validation.md +105 -0
  174. package/docs/session-lifecycle.md +156 -0
  175. package/docs/skills-marketplace.md +46 -0
  176. package/docs/tool-usage.md +527 -0
  177. package/docs/trace-store.md +132 -0
  178. package/docs/troubleshooting.md +33 -0
  179. package/docs/tui-design.md +239 -0
  180. package/docs/worker-dispatch-mechanics.md +242 -0
  181. package/package.json +132 -0
  182. package/skills/README.md +408 -0
  183. package/skills/git/commit-crafting/SKILL.md +79 -0
  184. package/skills/git/commit-crafting/evals.md +92 -0
  185. package/skills/git/create-pr/SKILL.md +116 -0
  186. package/skills/git/create-pr/evals.md +114 -0
  187. package/skills/git/investigate-issue/SKILL.md +139 -0
  188. package/skills/git/investigate-issue/evals.md +94 -0
  189. package/skills/git/resolve-merge-conflicts/SKILL.md +96 -0
  190. package/skills/git/resolve-merge-conflicts/evals.md +58 -0
  191. package/skills/git/review-changes/SKILL.md +103 -0
  192. package/skills/git/review-changes/evals.md +85 -0
  193. package/skills/git/worktree-create/SKILL.md +92 -0
  194. package/skills/git/worktree-create/evals.md +97 -0
  195. package/skills/git/worktree-create/references/worktree-setup.md +66 -0
  196. package/skills/git/worktree-merge/SKILL.md +95 -0
  197. package/skills/git/worktree-merge/evals.md +114 -0
  198. package/skills/skill-marketplace.json +261 -0
  199. package/skills/workflow/cut-it/SKILL.md +86 -0
  200. package/skills/workflow/cut-it/evals.md +42 -0
  201. package/src/domains/agents/builtins/architect.md +33 -0
  202. package/src/domains/agents/builtins/coder.md +31 -0
  203. package/src/domains/agents/builtins/context-bootstrap.md +38 -0
  204. package/src/domains/agents/builtins/debugger.md +30 -0
  205. package/src/domains/agents/builtins/documenter.md +31 -0
  206. package/src/domains/agents/builtins/git-master.md +30 -0
  207. package/src/domains/agents/builtins/provenance.md +30 -0
  208. package/src/domains/agents/builtins/researcher.md +71 -0
  209. package/src/domains/agents/builtins/scout.md +42 -0
  210. package/src/domains/agents/builtins/tester.md +31 -0
  211. package/src/domains/agents/builtins/verifier.md +30 -0
  212. package/src/domains/agents/builtins/wiki-writer.md +41 -0
  213. package/src/domains/agents/fleets/build-review.md +34 -0
  214. package/src/domains/agents/fleets/build-test.md +35 -0
  215. package/src/domains/agents/fleets/sdlc.md +86 -0
  216. package/src/domains/prompts/fragments/identity/clio-worker.md +11 -0
  217. package/src/domains/prompts/fragments/identity/clio.md +26 -0
  218. package/src/domains/prompts/fragments/operating/contract.md +64 -0
  219. package/src/domains/prompts/fragments/safety/auto-edit.md +14 -0
  220. package/src/domains/prompts/fragments/safety/full-auto.md +14 -0
  221. package/src/domains/prompts/fragments/safety/read-only.md +13 -0
  222. package/src/domains/prompts/fragments/safety/suggest.md +13 -0
  223. package/src/domains/prompts/fragments/wiki/page.md +75 -0
  224. package/src/domains/prompts/fragments/wiki/plan.md +48 -0
  225. package/src/domains/providers/models/cloud-models/alcf.yaml +40 -0
  226. package/src/domains/providers/models/local-models/clio-local-coding-targets.yaml +993 -0
package/docs/html/worker_dispatch_blueprint.html ADDED
@@ -0,0 +1,231 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>Worker Dispatch Mechanics Blueprint (v0.3.0)</title>
7
+ <link rel="stylesheet" href="shared.css">
8
+ <style>
9
+ /* Custom protocol simulator styles */
10
+ .protocol-scroller {
11
+ background: #060913;
12
+ border: 1px solid #1f354f;
13
+ border-radius: 8px;
14
+ padding: 1rem;
15
+ height: 300px;
16
+ overflow-y: auto;
17
+ font-family: var(--font-mono);
18
+ font-size: 0.8rem;
19
+ color: #b0c4de;
20
+ }
21
+ .stream-line {
22
+ margin-bottom: 0.5rem;
23
+ line-height: 1.4;
24
+ display: flex;
25
+ gap: 0.5rem;
26
+ }
27
+ .stream-dir {
28
+ font-weight: 700;
29
+ }
30
+ .dir-in { color: #bd00ff; }
31
+ .dir-out { color: #00d4db; }
32
+ .dir-sys { color: #6a7a85; }
33
+
34
+ .btn-group-grid {
35
+ display: grid;
36
+ grid-template-columns: repeat(auto-fit, minmax(130px, 1fr));
37
+ gap: 0.5rem;
38
+ margin-top: 1rem;
39
+ }
40
+ </style>
41
+ </head>
42
+ <body>
43
+ <div class="container">
44
+ <header>
45
+ <div class="header-left">
46
+ <div class="header-logo">
47
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="color: var(--color-cyan);"><title>Icon</title>
48
+ <path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"></path>
49
+ <circle cx="9" cy="7" r="4"></circle>
50
+ <path d="M23 21v-2a4 4 0 0 0-3-3.87"></path>
51
+ <path d="M16 3.13a4 4 0 0 1 0 7.75"></path>
52
+ </svg>
53
+ </div>
54
+ <div class="header-title-wrapper">
55
+ <h1>Worker Dispatch Mechanics</h1>
56
+ <p>Environment isolation, child process setup, and NDJSON stdin/stdout streams</p>
57
+ <div class="meta-chips-row">
58
+ <span class="chip">Source: docs/worker-dispatch-mechanics.md</span>
59
+ <span class="chip chip-orange">clio-coder docs worker_dispatch</span>
60
+ </div>
61
+ </div>
62
+ </div>
63
+ <div class="header-right">
64
+ <span class="version-badge">Clio Coder v0.3.0</span>
65
+ <a href="index.html" class="back-btn">
66
+ <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><title>Icon</title><line x1="19" y1="12" x2="5" y2="12"></line><polyline points="12 19 5 12 12 5"></polyline></svg>
67
+ Dashboard Hub
68
+ </a>
69
+ </div>
70
+ </header>
71
+
72
+ <div class="page-layout-grid">
73
+ <nav class="sidebar" aria-label="Table of Contents">
74
+ <div class="toc-container">
75
+ <div class="toc-title">On This Page</div>
76
+ <ul class="toc-list">
77
+ <!-- Dynamically populated -->
78
+ </ul>
79
+ </div>
80
+ </nav>
81
+
82
+ <main>
83
+ <div class="glass-card">
84
+ <h2>Overview Summary</h2>
85
+ <p>Dispatched worker processes run completely headlessly in environment-scrubbed isolation, exchanging event payloads with the parent orchestrator via standard stdin/stdout JSON lines.</p>
86
+ </div>
87
+
88
+ <div class="tabs-nav">
89
+ <button type="button" class="tab-btn active" onclick="switchTab('simulator')">
90
+ Protocol Stream Simulator
91
+ </button>
92
+ <button type="button" class="tab-btn" onclick="switchTab('details')">
93
+ Exit Code Reference
94
+ </button>
95
+ </div>
96
+
97
+ <!-- Tab 1: Simulator -->
98
+ <div class="tab-pane active" id="pane-simulator">
99
+ <div class="blueprint-layout">
100
+ <div class="specs-col">
101
+ <div class="glass-card">
102
+ <h3>Sequence Controls</h3>
103
+ <p>Simulate parent-child messages:</p>
104
+
105
+ <div class="btn-group-grid">
106
+ <button type="button" class="tab-btn" onclick="logEvent('spawn')">1. Spawn Worker</button>
107
+ <button type="button" class="tab-btn" onclick="logEvent('spec')">2. Send Spec</button>
108
+ <button type="button" class="tab-btn" onclick="logEvent('heartbeat')">3. Emit Heartbeat</button>
109
+ <button type="button" class="tab-btn" onclick="logEvent('escalate')">4. Escalate Tool</button>
110
+ <button type="button" class="tab-btn" onclick="logEvent('decision')">5. Decision Stdin</button>
111
+ <button type="button" class="tab-btn" onclick="logEvent('finish')">6. Finish Run</button>
112
+ </div>
113
+
114
+ <button type="button" class="tab-btn" style="margin-top:1.5rem; width:100%; border-color:var(--color-rose); color:var(--color-rose);" onclick="clearStream()">Reset Log</button>
115
+ </div>
116
+ </div>
117
+
118
+ <div class="specs-col">
119
+ <div class="glass-card">
120
+ <h3>Live NDJSON Timeline</h3>
121
+ <p>Scroll down to see lines written to standard streams:</p>
122
+
123
+ <div class="protocol-scroller" id="scroller">
124
+ <div class="stream-line"><span class="stream-dir dir-sys">[SYS]</span> Process idle. Click Spawn Worker to begin.</div>
125
+ </div>
126
+ </div>
127
+ </div>
128
+ </div>
129
+ </div>
130
+
131
+ <!-- Tab 2: Details -->
132
+ <div class="tab-pane" id="pane-details">
133
+ <div class="glass-card">
134
+ <h3>Worker Exit Codes Specs</h3>
135
+ <p>Parent checks exit codes when child process terminates:</p>
136
+
137
+ <table class="env-table" style="margin-top:1rem;">
138
+ <thead>
139
+ <tr>
140
+ <th>Exit Code</th>
141
+ <th>Symbolic Name</th>
142
+ <th>Triggering Condition</th>
143
+ </tr>
144
+ </thead>
145
+ <tbody>
146
+ <tr>
147
+ <td><code>0</code></td>
148
+ <td><code>WORKER_EXIT_SUCCESS</code></td>
149
+ <td>Run finished successfully with finish-contract evidence.</td>
150
+ </tr>
151
+ <tr>
152
+ <td><code>1</code></td>
153
+ <td><code>WORKER_EXIT_GENERIC_ERROR</code></td>
154
+ <td>Unhandled exception or parsing crash during chat loop.</td>
155
+ </tr>
156
+ <tr>
157
+ <td><code>3</code></td>
158
+ <td><code>WORKER_EXIT_PERMISSION_REQUIRED</code></td>
159
+ <td>A suggested tool required approval under strict non-interactive policy.</td>
160
+ </tr>
161
+ <tr>
162
+ <td><code>4</code></td>
163
+ <td><code>WORKER_EXIT_SIGTERM</code></td>
164
+ <td>Watchdog timed out or operator aborted execution stream.</td>
165
+ </tr>
166
+ </tbody>
167
+ </table>
168
+ </div>
169
+ </div>
170
+
171
+ <!-- Related Navigation -->
172
+ <nav class="related-nav" aria-label="Related Pages">
173
+ <a href="tui_design_blueprint.html" class="nav-link-card">
174
+ <span class="nav-label">Previous Blueprint</span>
175
+ <span class="nav-title">TUI Design System</span>
176
+ </a>
177
+ <a href="evals_internal_blueprint.html" class="nav-link-card next">
178
+ <span class="nav-label">Next Blueprint</span>
179
+ <span class="nav-title">Internal Eval Suites</span>
180
+ </a>
181
+ </nav>
182
+ </main>
183
+ </div>
184
+
185
+ <footer>
186
+ <p>Clio Coder Worker Dispatch Blueprint &bull; Version 0.3.0 &bull; Gnosis Research Center</p>
187
+ </footer>
188
+ </div>
189
+
190
+ <script src="shared.js"></script>
191
+ <script>
192
+ function clearStream() {
193
+ const scr = document.getElementById("scroller");
194
+ scr.innerHTML = `<div class="stream-line"><span class="stream-dir dir-sys">[SYS]</span> Process reset. Click Spawn to begin.</div>`;
195
+ }
196
+
197
+ function logEvent(type) {
198
+ const scr = document.getElementById("scroller");
199
+ const stamp = Date.now();
200
+ let html = "";
201
+
202
+ if (type === 'spawn') {
203
+ html = `<div class="stream-line"><span class="stream-dir dir-sys">[SYS]</span> node dist/worker/entry.js (pid 48123) spawned with scrubbed process.env</div>`;
204
+ } else if (type === 'spec') {
205
+ html = `<div class="stream-line"><span class="stream-dir dir-in">stdin &gt;</span> <code>{"type":"spec","sessionId":"sess-9f2","autonomy":"suggest","model":"gpt-5.4"}</code></div>`;
206
+ } else if (type === 'heartbeat') {
207
+ html = `<div class="stream-line"><span class="stream-dir dir-out">&lt; stdout</span> <code>{"type":"heartbeat","at":${stamp}}</code></div>`;
208
+ } else if (type === 'escalate') {
209
+ html = `<div class="stream-line"><span class="stream-dir dir-out">&lt; stdout</span> <code>{"type":"permission_escalation","requestId":"req-ab5","tool":"bash","command":"rm -rf tmp"}</code></div>`;
210
+ } else if (type === 'decision') {
211
+ html = `<div class="stream-line"><span class="stream-dir dir-in">stdin &gt;</span> <code>{"type":"permission_decision","requestId":"req-ab5","decision":"approve"}</code></div>`;
212
+ } else if (type === 'finish') {
213
+ html = `<div class="stream-line"><span class="stream-dir dir-out">&lt; stdout</span> <code>{"type":"completion","exitCode":0,"findingsSummary":"Built targets successfully"}</code></div>\n`;
214
+ html += `<div class="stream-line"><span class="stream-dir dir-sys">[SYS]</span> Worker child process terminated with exit code 0.</div>`;
215
+ }
216
+
217
+ scr.innerHTML += html;
218
+ scr.scrollTop = scr.scrollHeight;
219
+
220
+ if (window.initTableOfContents) window.initTableOfContents();
221
+ }
222
+
223
+ // Init
224
+ window.onload = () => {
225
+ // Make functions globally available
226
+ window.clearStream = clearStream;
227
+ window.logEvent = logEvent;
228
+ };
229
+ </script>
230
+ </body>
231
+ </html>
package/docs/installation-and-lifecycle.md ADDED
@@ -0,0 +1,308 @@
1
+ # Installation and Lifecycle Operations
2
+
3
+ Clio Coder is designed to be self-contained and platform-compliant. This document outlines the default directory paths, file purposes, permission levels, and lifecycle commands (`install`, `reset`, `upgrade`, and `uninstall`). The supported alpha install path is a source checkout with a deterministic local symlink; npm distribution of `@iowarp/clio-coder` begins with the first stable v0.3.0 (the CLI already classifies and upgrades npm installs, so nothing here changes shape at that point).
4
+
5
+ > [!TIP]
6
+ > **Interactive Spec Available:** An interactive dashboard with a path simulator and visual flowcharts is located at [docs/html/lifecycle_blueprint.html](html/lifecycle_blueprint.html) (Version: 0.3.0). You can open it directly in any web browser to view details dynamically.
7
+
8
+ ---
9
+
10
+ ## 1. Directory Layout & Platform Defaults
11
+
12
+ Clio Coder follows standard platform specifications for user configurations, databases, and caches, but allows full environment overrides.
13
+
14
+ ### Platform Defaults
15
+ | Operating System | Config (`configDir`) | Data (`dataDir`) | State (`stateDir`) | Cache (`cacheDir`) |
16
+ | :--- | :--- | :--- | :--- | :--- |
17
+ | **Linux / Unix** | `~/.config/clio-coder` | `~/.local/share/clio-coder` | `~/.local/state/clio-coder` | `~/.cache/clio-coder` |
18
+ | **macOS** | `~/Library/Application Support/clio-coder/config` | `~/Library/Application Support/clio-coder/data` | `~/Library/Application Support/clio-coder/state` | `~/Library/Caches/clio-coder` |
19
+ | **Windows** | `%APPDATA%\clio-coder\config` | `%APPDATA%\clio-coder\data` | `%LOCALAPPDATA%\clio-coder\state` | `%LOCALAPPDATA%\clio-coder\cache` |
20
+
21
+ Run `clio-coder paths [--json]` to print the resolved table for the current environment.
22
+
23
+ ### Environment Overrides
24
+ You can redirect Clio Coder's folders using environment variables:
25
+ * `CLIO_CODER_HOME`: Sets a symmetric tree: `$CLIO_CODER_HOME/config`, `$CLIO_CODER_HOME/data`, `$CLIO_CODER_HOME/state`, and `$CLIO_CODER_HOME/cache`.
26
+ * `CLIO_CODER_CONFIG_DIR`: Overrides the configuration directory only (takes precedence over `CLIO_CODER_HOME`).
27
+ * `CLIO_CODER_DATA_DIR`: Overrides the data directory only (takes precedence over `CLIO_CODER_HOME`).
28
+ * `CLIO_CODER_STATE_DIR`: Overrides the state directory only (takes precedence over `CLIO_CODER_HOME`).
29
+ * `CLIO_CODER_CACHE_DIR`: Overrides the cache directory only (takes precedence over `CLIO_CODER_HOME`).
30
+
31
+ ### The Project `.clio-coder/` Directory
32
+
33
+ The tables above cover the per-user roots. A repository Clio works in also grows a
34
+ `.clio-coder/` directory, and everything in it falls into one of three kinds:
35
+
36
+ * **Operator input.** You wrote it. Clio only reads it. Deleting it removes a
37
+ behavior you configured and nothing else.
38
+ * **Runtime state.** Clio wrote it. It is derived from your repository and can be
39
+ regenerated, though not always cheaply.
40
+ * **Overlay.** You wrote it, and it composes with a directory Clio ships. The
41
+ overlay column below says how.
42
+
43
+ | Path | Kind | What it is | Safe to delete? | `context reset` |
44
+ | :--- | :--- | :--- | :--- | :--- |
45
+ | `.clio-coder/settings.yaml`, `.clio-coder/settings.local.yaml` | Operator input | Project settings layered over the user's `settings.yaml`. Precedence is built-in < user < project < project-local. | Yes; the user-level settings apply again. | Kept |
46
+ | `.clio-coder/safety.yaml` | Operator input | Per-repository command allowlist consulted before execute actions. | Yes; approvals return to per-action prompting. | Kept |
47
+ | `.clio-coder/hooks.yaml`, `.clio-coder/hooks.local.yaml` | Operator input | Project-declared hooks. | Yes. | Kept |
48
+ | `.clio-coder/rules/**/*.md` | Operator input | Path-scoped project rules injected into the prompt. | Yes. | Kept |
49
+ | `.clio-coder/profile.yaml` | Operator input | Operator profile; closed enums and bounded path lists. | Yes. | Kept |
50
+ | `.clio-coder/fleets/*.md`, `.clio-coder/fleets/commands.yaml` | Overlay | Fleet contracts and their command registry. Adds to the fleets shipped under `src/domains/agents/fleets/`. | Yes; shipped fleets remain. | Kept |
51
+ | `.clio-coder/agents/*.md` | Overlay | Project agent recipes. Composes with shipped builtins and the user's `~/.config/clio-coder/agents`; a project recipe reusing a builtin id is **ignored**, not applied, with a note on stderr. | Yes; shipped agents remain. | Kept, and named |
52
+ | `.clio-coder/skills/**` | Overlay | Project skills, trusted as repository-local. Composes with skills Clio ships. | Yes; shipped skills remain. | Kept, and named |
53
+ | `CLIO-CODER.md` (repository root) | Runtime state | The generated project handbook. Human-reviewable, but written by `context init`. | Yes; regenerate with `clio-coder context init`. | Kept unless `--all` |
54
+ | `.clio-coder/codewiki.json` | Runtime state | Structural index, schema v5. | Yes; rebuilt by `clio-coder context index`. | **Removed** |
55
+ | `.clio-coder/state.json` | Runtime state | Index fingerprint and freshness stamps. | Yes; forces a rebuild. | **Removed** |
56
+ | `.clio-coder/proposals/` | Runtime state | Ignored handbook drafts from `context init --propose`. | Yes. | **Removed** |
57
+ | `.clio-coder/handoffs/` | Runtime state | Session handoff notes. | Yes. | **Removed** |
58
+ | `.clio-coder/wiki/` | Runtime state | The generated Markdown wiki plus `meta.json`. The most expensive artifact here: one model dispatch per page. | Yes, but regenerating costs a full `clio-coder context wiki` run. | Kept, and named |
59
+ | `.clio-coder/wiki-prev/` | Runtime state | Previous wiki, retained for rollback during generation. | Yes. | Kept, not named |
60
+ | `.clio-coder/worktrees/` | Runtime state | Git worktrees for `compete` candidate groups. | Prefer `git worktree remove`; a plain delete leaves git metadata behind. | Kept, not named |
61
+
62
+ `~/.clio-coder/runtimes/` is a separate, user-level directory for third-party runtime
63
+ plugins. It is not part of any repository.
64
+
65
+ None of `.clio-coder/` is published by Clio's own package. The directories Clio ships
66
+ (`src/domains/agents/builtins/`, `src/domains/agents/fleets/`, `skills/workflow/cut-it/`, `skills/git/`,
67
+ `src/domains/prompts/fragments/`, `src/domains/providers/models/`) are read from
68
+ the installed package root; the `.clio-coder/` entries above compose with them and never
69
+ replace them on disk.
70
+
71
+ ---
72
+
73
+ ## 2. File & Permissions Matrix
74
+
75
+ The core files are created automatically during the first run. `credentials.yaml` is the secret-bearing file and is forced to owner-only read-write permissions. Other initialized files and directories use either the explicit mode shown below or the platform default produced by the writer and process umask.
76
+
77
+ | Directory | File Path | Purpose | Permissions | Lifecycle Action |
78
+ | :--- | :--- | :--- | :--- | :--- |
79
+ | **Config** | `settings.yaml` | Target runtimes, model defaults, keybindings, and theme preferences. | `0o644` (rw-r--r--) | Removed by uninstall / `reset --config`. |
80
+ | **Config** | `credentials.yaml` | Private keys and tokens managed via `clio-coder auth`. | `0o600` (rw-------) | Removed by uninstall / `reset --auth`. |
81
+ | **Config** | `credentials.yaml.lock` | Lockfile used during credentials updates to prevent file corruption. | Ephemeral | Auto-removed. |
82
+ | **State** | `install.json` | Install metadata: Clio version, node, platform, `installedAt` (written once at first install), and `upgradedAt` (stamped on upgrade). | Writer/umask default | Removed by uninstall / `reset --state`. |
83
+ | **State** | `migrations.json` | Log of successfully applied schema/state migrations. | Writer/umask default | Removed by uninstall / `reset --state`. |
84
+ | **Data** | `memory/records.json` | Long-term learning memories (up to 500 records) proposed/approved from runs. | Writer/umask default | Removed by uninstall / `reset --data`. |
85
+ | **State** | `audit/YYYY-MM-DD.jsonl` | Daily safety audit logs showing allowed/blocked tool actions. | Writer/umask default | Removed by uninstall / `reset --state`. |
86
+ | **State** | `sessions/<cwdHash>/<id>/` | Session details: `meta.json`, `current.jsonl`, and fork hierarchies `tree.json`. | Writer/umask default | Removed by uninstall / `reset --state`. |
87
+
88
+ ---
89
+
90
+ ## 3. Bootstrap Initialization
91
+
92
+ When Clio Coder boots (or after a reset), it calls `initializeClioHome()` (see `src/core/init.ts`) to bootstrap missing structures:
93
+ 1. **Directory Tree**: Recursively creates the four roots (`config`, `data`, `state`, `cache`) and their skeletons: `agents` under config, `memory`/`evidence`/`evals` under data, and `sessions`/`audit`/`receipts`/`interviews`/`scratch` under state.
94
+ 2. **Settings Template**: If `settings.yaml` is absent, creates a fresh default config. An existing file is never read, validated, or rewritten by initialization.
95
+ 3. **Credentials Security**: If `credentials.yaml` is absent, creates a YAML file containing a managed-file comment and an empty object (`{}`), then locks its permissions immediately to owner-only read-write (`0o600`).
96
+ 4. **Install Metadata**: Writes `install.json` with `installedAt` exactly once at first install; a later version, platform, or node change preserves `installedAt` and stamps `upgradedAt`.
97
+
98
+ ---
99
+
100
+ ## 4. Source Checkout Install
101
+
102
+ Use the local source installer from the cloned repository:
103
+
104
+ ```bash
105
+ git clone https://github.com/iowarp/clio-coder.git
106
+ cd clio-coder
107
+ npm run install:local
108
+ hash -r
109
+ clio-coder --version
110
+ ```
111
+
112
+ `scripts/install-local.sh` is idempotent and auditable:
113
+
114
+ - verifies `node` satisfies `package.json` `engines.node`;
115
+ - runs `npm ci` unless `node_modules` satisfies the lockfile or `--skip-deps` is passed;
116
+ - runs `npm run build` unless `--no-build` is passed;
117
+ - verifies `dist/cli/index.js` exists and is executable;
118
+ - creates `${CLIO_CODER_BIN_DIR:-$HOME/.local/bin}` and links `clio-coder` there;
119
+ - warns if that bin dir is not on `PATH`, and warns when another `clio-coder`
120
+ earlier on `PATH` shadows the freshly linked one;
121
+ - runs the installed CLI's structure repair (`node dist/cli/index.js doctor
122
+ --fix` with the caller's environment), so a fresh install passes plain
123
+ `clio-coder doctor` with no manual steps.
124
+
125
+ On a machine where Clio has never run, plain `clio-coder doctor` reports the
126
+ missing config structure and exits nonzero by design (it is a read-only
127
+ diagnosis); `clio-coder doctor --fix`, the installer above, or simply launching
128
+ `clio-coder` creates everything.
129
+
130
+ First-run target setup after install:
131
+
132
+ **Option A: Local Model / API Key Target**
133
+ ```bash
134
+ clio-coder configure --list
135
+ clio-coder configure --id local-lmstudio --runtime lmstudio-native --url http://localhost:1234 --model your-model --set-orchestrator --set-fleet-default
136
+ clio-coder targets use local-lmstudio
137
+ clio-coder targets --probe
138
+ clio-coder
139
+ ```
140
+
141
+ **Option B: Subscription Target (OAuth / Claude Code)**
142
+ ```bash
143
+ # Authenticate ChatGPT Plus/Pro or Claude Pro/Max subscription
144
+ clio-coder auth login openai-codex
145
+ clio-coder auth login anthropic-max
146
+
147
+ # Authenticate Claude CLI for worker targets
148
+ claude auth login
149
+
150
+ # Configure OAuth subscription target
151
+ clio-coder configure --id claude-sub --runtime anthropic-max --model your-claude-model --set-orchestrator
152
+
153
+ # Configure Claude Code SDK worker target
154
+ clio-coder configure --id claude-sdk-worker --runtime claude-sdk --model your-claude-model --set-fleet-default
155
+
156
+ clio-coder targets use claude-sub
157
+ clio-coder targets --probe
158
+ clio-coder
159
+ ```
160
+
161
+ If a shell still tries an old removed path such as `~/.local/bin/clio-coder`, clear
162
+ its command cache with `hash -r` in Bash or `rehash` in Zsh.
163
+
164
+ ## 5. Lifecycle Commands
165
+
166
+ Clio Coder provides CLI utilities to manage operations safely. For a complete catalog of operational errors, permission denial handling, and remediation procedures, see [troubleshooting.md](troubleshooting.md).
167
+
168
+ ### A. Integrity Diagnostics (`clio-coder doctor`)
169
+ Runs a series of health sweeps across the environment:
170
+ * Validates `settings.yaml` against the strict schema, reporting exact key paths, read-only.
171
+ * Asserts owner-only permissions on credentials (`0o600`).
172
+ * Reports the installed Clio, Node, platform, and engine package readiness.
173
+ * Checks config, data, state, cache, and state metadata freshness. It also warns when an OpenAI-compatible or Anthropic-compatible target appears to be a native LM Studio or Ollama server that should be converted.
174
+ * *Recovery:* Run `clio-coder doctor --fix` to create missing directories and templates, repair credential permissions, and refresh install metadata. Settings are always validated against the current schema; `--fix` does not rewrite removed keys or migrate an older settings file, so the operator must correct every reported path deliberately.
175
+
176
+ ### B. Upgrades (`clio-coder upgrade`)
177
+ Refreshes state metadata and applies pending data-dir migrations.
178
+ ```bash
179
+ clio-coder upgrade [--dry-run] [--channel=<latest|beta|dev>] [--skip-migrations]
180
+ ```
181
+ The command detects the install method from the running binary. On a source
182
+ checkout it never runs `npm install -g`: it performs its safe local duties
183
+ (migration check, `install.json` refresh) and prints the real update steps,
184
+ `git pull`, `npm run install:local`, `hash -r`. The npm reinstall path applies
185
+ only to a genuinely npm-installed binary, once the package is published.
186
+
187
+ ### C. System Resets (`clio-coder reset`)
188
+ Selective recovery wipes:
189
+ ```bash
190
+ clio-coder reset [--state|--data|--cache|--auth|--config|--all] [--dry-run] [--force]
191
+ ```
192
+ Levels are combinable except `--all`. Each level clears exactly the root or file it names and nothing else, then bootstraps the missing structure again unless `--dry-run` is present. `--force` is required only for destructive execution.
193
+
194
+ Every run lists each selected root and then the entries inside it, read off the
195
+ disk on that run, before removing anything; `--dry-run` prints the identical
196
+ listing. That listing, not this page and not `--help`, is the authoritative
197
+ inventory of what a level covers, because a remembered list drifts as soon as a
198
+ new artifact is written into a root.
199
+
200
+ * `--state` *(Default)*: Deletes the state root only. It holds every session transcript and the audit trail beside it, so a reset is the end of `resume`, `/view`, and their history. This is the level a bare `clio-coder reset` selects, and it carries that note in its preview.
201
+ * `--data`: Deletes the data root only: memory, evidence, evals (durable products).
202
+ * `--cache`: Deletes the cache root only.
203
+ * `--auth`: Deletes `credentials.yaml`. Removes all saved keys.
204
+ * `--config`: Deletes `settings.yaml` to revert preferences to default.
205
+ * `--all`: Wipes all four roots (config, data, state, cache) and automatically reinitializes a fresh environment.
206
+
207
+ ### D. Uninstallation (`clio-coder uninstall`)
208
+ `clio-coder uninstall` is the single uninstall path for every install method. It
209
+ removes all four roots (config, data, state, cache):
210
+
211
+ ```bash
212
+ clio-coder uninstall [--remove-binary] [--dry-run] [--force]
213
+ ```
214
+
215
+ Preview first, then remove:
216
+
217
+ ```bash
218
+ clio-coder uninstall --dry-run
219
+ clio-coder uninstall --remove-binary --force
220
+ hash -r
221
+ ```
222
+
223
+ `--dry-run` prints the roots and the optional launcher action without changing
224
+ anything, and enumerates the same resolved absolute paths the real run would
225
+ remove. It prints binary-removal guidance for the active launcher, npm-global
226
+ installs, npm links, and the local source symlink.
227
+
228
+ #### Per-project `.clio-coder/` directories
229
+
230
+ Uninstall removes the four roots under your home directory. The `.clio-coder/`
231
+ directory Clio writes inside each repository it runs in is not one of them and
232
+ is never removed here. Every project is recorded in the session metadata under
233
+ the state root, so both the real run and `--dry-run` list the surviving
234
+ `.clio-coder/` directories and name the command that clears one:
235
+
236
+ ```bash
237
+ clio-coder context reset --all
238
+ ```
239
+
240
+ That command works on the current directory, so run it from inside each listed
241
+ project. The listing is printed before the roots are removed, because the record
242
+ it reads lives in one of them, and before `--remove-binary` unlinks the launcher,
243
+ because `clio-coder context reset` needs the binary that is about to go. With
244
+ `--remove-binary` the listing says so and tells you to clear the projects first,
245
+ then re-run the uninstall. Neither the preview nor the real run deletes project
246
+ data. To wipe state selectively
247
+ while keeping settings or credentials, use `clio-coder reset` instead of
248
+ uninstalling. If the launcher is already gone but state remains, run the built
249
+ CLI directly from the checkout: `node dist/cli/index.js uninstall --force`.
250
+
251
+ #### What `--remove-binary` will and will not remove
252
+
253
+ Ownership is identity, not shape. The launcher is removed only when it resolves
254
+ to *this* installation's own `dist/cli/index.js`. A path test on the target's
255
+ spelling was three ways too broad: it matched a live symlink into a different
256
+ clio-coder checkout, and it matched a target that is not even a file, so an uninstall
257
+ from one installation could unlink another one's launcher and leave that
258
+ installation on disk with no way to start it.
259
+
260
+ | At `$CLIO_CODER_BIN_DIR/clio-coder` | Outcome |
261
+ | --- | --- |
262
+ | A symlink resolving to this installation's entry | Removed |
263
+ | A symlink resolving to a different clio-coder installation | Kept, with the path it points at and the exact `rm` that removes it |
264
+ | A symlink to a directory named `index.js` | Kept, because a directory is not an entry |
265
+ | A real file | Kept, with a note to remove it through the package manager that put it there |
266
+ | A dangling symlink naming a clio-coder entry | Removed, and reported as dangling. Leaving it would put a broken `clio-coder` on PATH after an uninstall that claimed to finish |
267
+ | A dangling symlink naming anything else | Kept, with the exact `rm` |
268
+
269
+ #### Partial failure
270
+
271
+ A recursive delete can stop halfway: an unwritable parent leaves some children
272
+ removed and some in place. `reset` and `uninstall` collect per-path failures
273
+ instead of throwing the first one. Every selected root still gets its attempt,
274
+ the skeleton is rebuilt, each surviving path is named with the reason it
275
+ resisted, and the command exits 1 with the exact invocation to rerun. Both
276
+ commands are idempotent, so the recovery is always the same: fix the permission
277
+ or release the handle, then run the identical command again and it resumes from
278
+ whatever is left. A partial delete never reports global success.
279
+
280
+ ---
281
+
282
+ ## 6. Residues Checklist for Manual Purging
283
+
284
+ If you are removing Clio Coder completely from your system, verify that all categories of residues are removed:
285
+
286
+ 1. **System Roots**:
287
+ * `~/.config/clio-coder`
288
+ * `~/.local/share/clio-coder`
289
+ * `~/.local/state/clio-coder`
290
+ * `~/.cache/clio-coder`
291
+ 2. **Local Source Bin Link**:
292
+ * `${CLIO_CODER_BIN_DIR:-$HOME/.local/bin}/clio-coder`
293
+ 3. **Global Bin Links**:
294
+ * `clio-coder` executable in your global npm path (for source checkouts, avoid this path unless intentionally debugging npm link behavior).
295
+ 4. **Per-Repository State**:
296
+ * `.clio-coder/` in every repository Clio has worked in, and the generated `CLIO-CODER.md` beside it. See [The Project `.clio-coder/` Directory](#the-project-clio-directory) for what each entry is before deleting.
297
+ * Remove `.clio-coder/worktrees/` with `git worktree remove` rather than `rm -rf`, so git does not keep stale worktree metadata.
298
+
299
+ ---
300
+
301
+ ## 7. Headless and CI Execution Behavior
302
+
303
+ Clio Coder supports headless operation for automation and continuous integration.
304
+
305
+ When executing tasks headlessly using `clio-coder run`, interactive permission prompting is unavailable. The engine resolves permission requests using a deterministic model:
306
+ - **Main-agent auto-denial:** Any main-agent tool call that parks for operator authorization is denied with `clio-coder run cannot confirm permission requests; rerun interactively to approve this action.` The parked call is cancelled with that reason, and the headless turn finishes according to the resulting assistant outcome.
307
+ - **Worker non-stall policy:** Dispatched workers use `workers.onPermission`. The default `deny` turns a permission ask into a structured tool denial and lets the worker continue. `fail` aborts the worker and records the dispatch outcome as `failed/permission_required`.
308
+ - **CI behavior:** Neither path waits for an interactive prompt. Exit status still reflects the final headless or dispatch result rather than the mere fact that a permission ask occurred.