@zigrivers/scaffold 3.29.0 → 3.31.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.
- package/content/guides/AUTHORING.md +146 -0
- package/content/guides/cli/index.html +1855 -0
- package/content/guides/cli/index.md +206 -0
- package/content/guides/concepts/index.html +1970 -0
- package/content/guides/concepts/index.md +347 -0
- package/content/guides/dashboard/index.html +1913 -0
- package/content/guides/dashboard/index.md +264 -0
- package/content/guides/index.html +368 -15
- package/content/guides/install/.diagrams/diagram-0.svg +1 -0
- package/content/guides/install/.diagrams/manifest.json +3 -0
- package/content/guides/install/index.html +1653 -0
- package/content/guides/install/index.md +186 -0
- package/content/guides/knowledge/.diagrams/diagram-0.svg +1 -0
- package/content/guides/knowledge/.diagrams/manifest.json +3 -0
- package/content/guides/knowledge/index.html +1765 -0
- package/content/guides/knowledge/index.md +209 -0
- package/content/guides/knowledge-freshness/.diagrams/diagram-0.svg +1 -0
- package/content/guides/knowledge-freshness/.diagrams/manifest.json +3 -0
- package/content/guides/knowledge-freshness/index.html +2795 -0
- package/content/guides/knowledge-freshness/index.md +893 -0
- package/content/guides/mmr/index.html +407 -36
- package/content/guides/mmr/index.md +39 -16
- package/content/guides/multi-agent/.diagrams/diagram-0.svg +1 -0
- package/content/guides/multi-agent/.diagrams/manifest.json +3 -0
- package/content/guides/multi-agent/index.html +1715 -0
- package/content/guides/multi-agent/index.md +243 -0
- package/content/guides/observability/.diagrams/diagram-0.svg +1 -0
- package/content/guides/observability/.diagrams/diagram-1.svg +1 -0
- package/content/guides/observability/.diagrams/diagram-2.svg +1 -0
- package/content/guides/observability/.diagrams/diagram-3.svg +1 -0
- package/content/guides/observability/.diagrams/manifest.json +6 -0
- package/content/guides/observability/index.html +3257 -0
- package/content/guides/observability/index.md +1097 -0
- package/content/guides/pipeline/.diagrams/diagram-0.svg +1 -0
- package/content/guides/pipeline/.diagrams/diagram-1.svg +1 -0
- package/content/guides/pipeline/.diagrams/manifest.json +4 -0
- package/content/guides/pipeline/index.html +1973 -0
- package/content/guides/pipeline/index.md +387 -0
- package/content/guides/review-workflow/.diagrams/diagram-0.svg +1 -0
- package/content/guides/review-workflow/.diagrams/diagram-1.svg +1 -0
- package/content/guides/review-workflow/.diagrams/manifest.json +4 -0
- package/content/guides/review-workflow/index.html +1790 -0
- package/content/guides/review-workflow/index.md +248 -0
- package/dist/guides/build.d.ts +1 -1
- package/dist/guides/build.d.ts.map +1 -1
- package/dist/guides/build.js +21 -9
- package/dist/guides/build.js.map +1 -1
- package/dist/guides/build.test.js +47 -0
- package/dist/guides/build.test.js.map +1 -1
- package/dist/guides/chrome.d.ts.map +1 -1
- package/dist/guides/chrome.js +83 -12
- package/dist/guides/chrome.js.map +1 -1
- package/dist/guides/dashboard-theme.css +8 -0
- package/dist/guides/directives-cite.test.d.ts +2 -0
- package/dist/guides/directives-cite.test.d.ts.map +1 -0
- package/dist/guides/directives-cite.test.js +26 -0
- package/dist/guides/directives-cite.test.js.map +1 -0
- package/dist/guides/directives-tabs.test.js +47 -0
- package/dist/guides/directives-tabs.test.js.map +1 -1
- package/dist/guides/directives.d.ts +1 -0
- package/dist/guides/directives.d.ts.map +1 -1
- package/dist/guides/directives.js +38 -0
- package/dist/guides/directives.js.map +1 -1
- package/dist/guides/guides.css +268 -0
- package/dist/guides/index-page.d.ts.map +1 -1
- package/dist/guides/index-page.js +41 -8
- package/dist/guides/index-page.js.map +1 -1
- package/dist/guides/links.d.ts +14 -0
- package/dist/guides/links.d.ts.map +1 -0
- package/dist/guides/links.js +56 -0
- package/dist/guides/links.js.map +1 -0
- package/dist/guides/links.test.d.ts +2 -0
- package/dist/guides/links.test.d.ts.map +1 -0
- package/dist/guides/links.test.js +72 -0
- package/dist/guides/links.test.js.map +1 -0
- package/dist/guides/render.d.ts +1 -0
- package/dist/guides/render.d.ts.map +1 -1
- package/dist/guides/render.js +1 -1
- package/dist/guides/render.js.map +1 -1
- package/dist/guides/sanitize.d.ts.map +1 -1
- package/dist/guides/sanitize.js +5 -0
- package/dist/guides/sanitize.js.map +1 -1
- package/dist/guides/template.d.ts.map +1 -1
- package/dist/guides/template.js +7 -2
- package/dist/guides/template.js.map +1 -1
- package/package.json +2 -2
|
@@ -0,0 +1,3257 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en" data-chrome-version="1">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<title>Build Observability</title>
|
|
7
|
+
<!-- scaffold:chrome v1 -->
|
|
8
|
+
<style>/* Scaffold Dashboard Theme
|
|
9
|
+
* All CSS for the generated pipeline dashboard.
|
|
10
|
+
* Embedded into HTML by scripts/generate-dashboard.sh.
|
|
11
|
+
* Design system reference: docs/design-system.md
|
|
12
|
+
*
|
|
13
|
+
* Aesthetic: "Precision Industrial" — Swiss-typographic control room.
|
|
14
|
+
* Deep navy dark mode with indigo accents, clean cool-white light mode.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
/* ─── Design Tokens (Light Mode) ──────────────── */
|
|
18
|
+
:root {
|
|
19
|
+
/* Surface */
|
|
20
|
+
--bg: #f5f6fa;
|
|
21
|
+
--bg-card: #ffffff;
|
|
22
|
+
--bg-hover: #eef0f6;
|
|
23
|
+
--bg-inset: #e8eaf2;
|
|
24
|
+
|
|
25
|
+
/* Text */
|
|
26
|
+
--text: #1a1d2e;
|
|
27
|
+
--text-muted: #6b7294;
|
|
28
|
+
--text-faint: #9ba1c0;
|
|
29
|
+
|
|
30
|
+
/* Borders & Structure */
|
|
31
|
+
--border: #dde0ed;
|
|
32
|
+
--border-light: #eceef5;
|
|
33
|
+
--radius: 10px;
|
|
34
|
+
--radius-sm: 6px;
|
|
35
|
+
|
|
36
|
+
/* Accent */
|
|
37
|
+
--accent: #4f46e5;
|
|
38
|
+
--accent-hover: #4338ca;
|
|
39
|
+
--accent-glow: rgba(79, 70, 229, 0.10);
|
|
40
|
+
|
|
41
|
+
/* Semantic: Status */
|
|
42
|
+
--green: #059669;
|
|
43
|
+
--green-bg: #ecfdf5;
|
|
44
|
+
--green-border: #a7f3d0;
|
|
45
|
+
--blue: #2563eb;
|
|
46
|
+
--blue-bg: #eff6ff;
|
|
47
|
+
--blue-border: #bfdbfe;
|
|
48
|
+
--yellow: #d97706;
|
|
49
|
+
--yellow-bg: #fffbeb;
|
|
50
|
+
--yellow-border:#fde68a;
|
|
51
|
+
--red: #dc2626;
|
|
52
|
+
--red-bg: #fef2f2;
|
|
53
|
+
--red-border: #fecaca;
|
|
54
|
+
--gray: #9ca3af;
|
|
55
|
+
--gray-bg: #f3f4f6;
|
|
56
|
+
--gray-border: #e5e7eb;
|
|
57
|
+
--scrim: rgba(15, 17, 23, 0.45);
|
|
58
|
+
|
|
59
|
+
/* Semantic: Next Banner */
|
|
60
|
+
--next-bg: #eef2ff;
|
|
61
|
+
--next-border: #4f46e5;
|
|
62
|
+
--next-glow: rgba(79, 70, 229, 0.06);
|
|
63
|
+
|
|
64
|
+
/* Semantic: Progress */
|
|
65
|
+
--progress-bg: #e5e7eb;
|
|
66
|
+
--progress-h: 10px;
|
|
67
|
+
|
|
68
|
+
/* Depth */
|
|
69
|
+
--shadow-sm: 0 1px 2px rgba(30, 34, 60, 0.04);
|
|
70
|
+
--shadow: 0 1px 3px rgba(30, 34, 60, 0.07), 0 1px 2px rgba(30, 34, 60, 0.04);
|
|
71
|
+
--shadow-md: 0 4px 12px rgba(30, 34, 60, 0.08), 0 1px 3px rgba(30, 34, 60, 0.05);
|
|
72
|
+
--shadow-lg: 0 8px 24px rgba(30, 34, 60, 0.10), 0 2px 6px rgba(30, 34, 60, 0.04);
|
|
73
|
+
|
|
74
|
+
/* Spacing scale (4px base) */
|
|
75
|
+
--sp-1: 4px;
|
|
76
|
+
--sp-2: 8px;
|
|
77
|
+
--sp-3: 12px;
|
|
78
|
+
--sp-4: 16px;
|
|
79
|
+
--sp-5: 20px;
|
|
80
|
+
--sp-6: 24px;
|
|
81
|
+
--sp-8: 32px;
|
|
82
|
+
--sp-10: 40px;
|
|
83
|
+
|
|
84
|
+
/* Typography */
|
|
85
|
+
--font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
|
|
86
|
+
--font-mono: "SF Mono", "Cascadia Code", "Fira Code", "JetBrains Mono", Menlo, Consolas, monospace;
|
|
87
|
+
--text-xs: 0.75rem;
|
|
88
|
+
--text-sm: 0.8125rem;
|
|
89
|
+
--text-base: 0.9375rem;
|
|
90
|
+
--text-lg: 1.125rem;
|
|
91
|
+
--text-xl: 1.375rem;
|
|
92
|
+
--text-2xl: 1.75rem;
|
|
93
|
+
--lh-tight: 1.25;
|
|
94
|
+
--lh-normal: 1.5;
|
|
95
|
+
--lh-relaxed: 1.625;
|
|
96
|
+
--ls-tight: -0.01em;
|
|
97
|
+
--ls-wide: 0.025em;
|
|
98
|
+
--fw-normal: 400;
|
|
99
|
+
--fw-medium: 500;
|
|
100
|
+
--fw-semi: 600;
|
|
101
|
+
--fw-bold: 700;
|
|
102
|
+
|
|
103
|
+
/* Layout */
|
|
104
|
+
--max-w: 960px;
|
|
105
|
+
--page-pad: 24px;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/* ─── Design Tokens (Dark Mode) ───────────────── */
|
|
109
|
+
[data-theme="dark"] {
|
|
110
|
+
/* Surface */
|
|
111
|
+
--bg: #0f1117;
|
|
112
|
+
--bg-card: #1a1d2e;
|
|
113
|
+
--bg-hover: #252940;
|
|
114
|
+
--bg-inset: #141724;
|
|
115
|
+
|
|
116
|
+
/* Text */
|
|
117
|
+
--text: #e2e5f0;
|
|
118
|
+
--text-muted: #7c82a8;
|
|
119
|
+
--text-faint: #555c80;
|
|
120
|
+
|
|
121
|
+
/* Borders & Structure */
|
|
122
|
+
--border: #2a2f45;
|
|
123
|
+
--border-light: #21253a;
|
|
124
|
+
|
|
125
|
+
/* Accent */
|
|
126
|
+
--accent: #818cf8;
|
|
127
|
+
--accent-hover: #a5b4fc;
|
|
128
|
+
--accent-glow: rgba(129, 140, 248, 0.12);
|
|
129
|
+
|
|
130
|
+
/* Semantic: Status */
|
|
131
|
+
--green: #34d399;
|
|
132
|
+
--green-bg: rgba(6, 78, 59, 0.25);
|
|
133
|
+
--green-border: rgba(52, 211, 153, 0.25);
|
|
134
|
+
--blue: #60a5fa;
|
|
135
|
+
--blue-bg: rgba(30, 58, 95, 0.30);
|
|
136
|
+
--blue-border: rgba(96, 165, 250, 0.25);
|
|
137
|
+
--yellow: #fbbf24;
|
|
138
|
+
--yellow-bg: rgba(120, 53, 15, 0.25);
|
|
139
|
+
--yellow-border:rgba(251, 191, 36, 0.20);
|
|
140
|
+
--red: #f87171;
|
|
141
|
+
--red-bg: rgba(127, 29, 29, 0.25);
|
|
142
|
+
--red-border: rgba(248, 113, 113, 0.22);
|
|
143
|
+
--gray: #6b7294;
|
|
144
|
+
--gray-bg: #252940;
|
|
145
|
+
--gray-border: #363c58;
|
|
146
|
+
--scrim: rgba(0, 0, 0, 0.6);
|
|
147
|
+
|
|
148
|
+
/* Semantic: Next Banner */
|
|
149
|
+
--next-bg: rgba(30, 27, 75, 0.50);
|
|
150
|
+
--next-border: #818cf8;
|
|
151
|
+
--next-glow: rgba(129, 140, 248, 0.08);
|
|
152
|
+
|
|
153
|
+
/* Semantic: Progress */
|
|
154
|
+
--progress-bg: #1f2337;
|
|
155
|
+
|
|
156
|
+
/* Depth */
|
|
157
|
+
--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.20);
|
|
158
|
+
--shadow: 0 1px 3px rgba(0, 0, 0, 0.30), 0 1px 2px rgba(0, 0, 0, 0.15);
|
|
159
|
+
--shadow-md: 0 4px 12px rgba(0, 0, 0, 0.35), 0 1px 3px rgba(0, 0, 0, 0.20);
|
|
160
|
+
--shadow-lg: 0 8px 24px rgba(0, 0, 0, 0.40), 0 2px 6px rgba(0, 0, 0, 0.20);
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/* ─── Theme Toggle ───────────────────────────── */
|
|
164
|
+
.theme-toggle {
|
|
165
|
+
background: var(--bg-inset);
|
|
166
|
+
border: 1px solid var(--border);
|
|
167
|
+
border-radius: var(--radius-sm);
|
|
168
|
+
padding: var(--sp-1) var(--sp-2);
|
|
169
|
+
cursor: pointer;
|
|
170
|
+
font-size: var(--text-base);
|
|
171
|
+
line-height: 1;
|
|
172
|
+
color: var(--text-muted);
|
|
173
|
+
transition: border-color 0.15s ease, color 0.15s ease, background 0.15s ease;
|
|
174
|
+
display: flex;
|
|
175
|
+
align-items: center;
|
|
176
|
+
margin-left: auto;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
.theme-toggle:hover {
|
|
180
|
+
border-color: var(--accent);
|
|
181
|
+
color: var(--accent);
|
|
182
|
+
background: var(--accent-glow);
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/* ─── Base ────────────────────────────────────── */
|
|
186
|
+
*, *::before, *::after {
|
|
187
|
+
margin: 0;
|
|
188
|
+
padding: 0;
|
|
189
|
+
box-sizing: border-box;
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
body {
|
|
193
|
+
font-family: var(--font-sans);
|
|
194
|
+
font-size: var(--text-base);
|
|
195
|
+
line-height: var(--lh-normal);
|
|
196
|
+
color: var(--text);
|
|
197
|
+
background: var(--bg);
|
|
198
|
+
-webkit-font-smoothing: antialiased;
|
|
199
|
+
-moz-osx-font-smoothing: grayscale;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/* ─── Layout ──────────────────────────────────── */
|
|
203
|
+
.wrap {
|
|
204
|
+
max-width: var(--max-w);
|
|
205
|
+
margin: 0 auto;
|
|
206
|
+
padding: var(--sp-8) var(--page-pad);
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/* ─── Header ──────────────────────────────────── */
|
|
210
|
+
.header {
|
|
211
|
+
display: flex;
|
|
212
|
+
align-items: baseline;
|
|
213
|
+
gap: var(--sp-3);
|
|
214
|
+
margin-bottom: var(--sp-2);
|
|
215
|
+
flex-wrap: wrap;
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
h1 {
|
|
219
|
+
font-size: var(--text-2xl);
|
|
220
|
+
font-weight: var(--fw-bold);
|
|
221
|
+
letter-spacing: var(--ls-tight);
|
|
222
|
+
line-height: var(--lh-tight);
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
h2 {
|
|
226
|
+
font-size: var(--text-lg);
|
|
227
|
+
font-weight: var(--fw-semi);
|
|
228
|
+
letter-spacing: var(--ls-tight);
|
|
229
|
+
line-height: var(--lh-tight);
|
|
230
|
+
margin-bottom: var(--sp-3);
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
.header-meta {
|
|
234
|
+
font-size: var(--text-xs);
|
|
235
|
+
color: var(--text-faint);
|
|
236
|
+
margin-bottom: var(--sp-6);
|
|
237
|
+
letter-spacing: var(--ls-wide);
|
|
238
|
+
text-transform: uppercase;
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
/* ─── Badge ───────────────────────────────────── */
|
|
242
|
+
.badge {
|
|
243
|
+
display: inline-block;
|
|
244
|
+
padding: 2px var(--sp-2);
|
|
245
|
+
border-radius: 99px;
|
|
246
|
+
font-size: var(--text-xs);
|
|
247
|
+
font-weight: var(--fw-semi);
|
|
248
|
+
letter-spacing: var(--ls-wide);
|
|
249
|
+
background: var(--accent);
|
|
250
|
+
color: #fff;
|
|
251
|
+
text-transform: uppercase;
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
.badge-optional {
|
|
255
|
+
background: var(--yellow-bg);
|
|
256
|
+
color: var(--yellow);
|
|
257
|
+
border: 1px solid var(--yellow-border);
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/* ─── Progress Bar ────────────────────────────── */
|
|
261
|
+
.progress-bar {
|
|
262
|
+
width: 100%;
|
|
263
|
+
height: var(--progress-h);
|
|
264
|
+
background: var(--progress-bg);
|
|
265
|
+
border-radius: 99px;
|
|
266
|
+
overflow: hidden;
|
|
267
|
+
margin-bottom: var(--sp-6);
|
|
268
|
+
display: flex;
|
|
269
|
+
box-shadow: inset 0 1px 2px rgba(0, 0, 0, 0.06);
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
.progress-bar .seg-done {
|
|
273
|
+
background: linear-gradient(135deg, var(--green), #10b981);
|
|
274
|
+
box-shadow: 0 0 8px rgba(5, 150, 105, 0.3);
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
.progress-bar .seg-likely {
|
|
278
|
+
background: linear-gradient(135deg, var(--blue), #3b82f6);
|
|
279
|
+
box-shadow: 0 0 8px rgba(37, 99, 235, 0.25);
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
.progress-bar .seg-skip {
|
|
283
|
+
background: var(--gray);
|
|
284
|
+
opacity: 0.7;
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
/* ─── Summary Cards ───────────────────────────── */
|
|
288
|
+
.cards {
|
|
289
|
+
display: grid;
|
|
290
|
+
grid-template-columns: repeat(auto-fit, minmax(130px, 1fr));
|
|
291
|
+
gap: var(--sp-3);
|
|
292
|
+
margin-bottom: var(--sp-6);
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
.card {
|
|
296
|
+
background: var(--bg-card);
|
|
297
|
+
border: 1px solid var(--border);
|
|
298
|
+
border-radius: var(--radius);
|
|
299
|
+
padding: var(--sp-4) var(--sp-5);
|
|
300
|
+
box-shadow: var(--shadow);
|
|
301
|
+
transition: box-shadow 0.15s ease, transform 0.15s ease;
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
.card:hover {
|
|
305
|
+
box-shadow: var(--shadow-md);
|
|
306
|
+
transform: translateY(-1px);
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
.card-num {
|
|
310
|
+
font-size: var(--text-2xl);
|
|
311
|
+
font-weight: var(--fw-bold);
|
|
312
|
+
font-family: var(--font-mono);
|
|
313
|
+
letter-spacing: var(--ls-tight);
|
|
314
|
+
line-height: 1;
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
.card-lbl {
|
|
318
|
+
font-size: var(--text-xs);
|
|
319
|
+
color: var(--text-muted);
|
|
320
|
+
margin-top: var(--sp-1);
|
|
321
|
+
letter-spacing: var(--ls-wide);
|
|
322
|
+
text-transform: uppercase;
|
|
323
|
+
font-weight: var(--fw-medium);
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
/* ─── What's Next Banner ──────────────────────── */
|
|
327
|
+
.next-banner {
|
|
328
|
+
background: var(--next-bg);
|
|
329
|
+
border: 1px solid var(--next-border);
|
|
330
|
+
border-left: 4px solid var(--next-border);
|
|
331
|
+
border-radius: var(--radius);
|
|
332
|
+
padding: var(--sp-5) var(--sp-6);
|
|
333
|
+
margin-bottom: var(--sp-6);
|
|
334
|
+
box-shadow: 0 0 0 1px var(--next-glow), var(--shadow);
|
|
335
|
+
position: relative;
|
|
336
|
+
overflow: hidden;
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
.next-banner::before {
|
|
340
|
+
content: "";
|
|
341
|
+
position: absolute;
|
|
342
|
+
top: 0;
|
|
343
|
+
left: 0;
|
|
344
|
+
width: 4px;
|
|
345
|
+
height: 100%;
|
|
346
|
+
background: var(--next-border);
|
|
347
|
+
animation: pulse-border 2.5s ease-in-out infinite;
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
@keyframes pulse-border {
|
|
351
|
+
0%, 100% { opacity: 1; }
|
|
352
|
+
50% { opacity: 0.5; }
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
.next-banner h2 {
|
|
356
|
+
color: var(--accent);
|
|
357
|
+
margin-bottom: var(--sp-1);
|
|
358
|
+
font-size: var(--text-base);
|
|
359
|
+
font-weight: var(--fw-semi);
|
|
360
|
+
letter-spacing: var(--ls-wide);
|
|
361
|
+
text-transform: uppercase;
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
.next-banner p {
|
|
365
|
+
color: var(--text);
|
|
366
|
+
font-size: var(--text-base);
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
.next-cmd {
|
|
370
|
+
font-family: var(--font-mono);
|
|
371
|
+
background: var(--bg-card);
|
|
372
|
+
padding: var(--sp-1) var(--sp-3);
|
|
373
|
+
border-radius: var(--radius-sm);
|
|
374
|
+
font-size: var(--text-sm);
|
|
375
|
+
display: inline-flex;
|
|
376
|
+
align-items: center;
|
|
377
|
+
gap: var(--sp-2);
|
|
378
|
+
margin-top: var(--sp-3);
|
|
379
|
+
border: 1px solid var(--border);
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
/* ─── Phase Headers (Collapsible) ─────────────── */
|
|
383
|
+
.phase {
|
|
384
|
+
margin-bottom: var(--sp-6);
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
.phase-hdr {
|
|
388
|
+
display: flex;
|
|
389
|
+
align-items: center;
|
|
390
|
+
gap: var(--sp-2);
|
|
391
|
+
cursor: pointer;
|
|
392
|
+
padding: var(--sp-2) 0;
|
|
393
|
+
user-select: none;
|
|
394
|
+
border-bottom: 2px solid var(--border);
|
|
395
|
+
margin-bottom: var(--sp-3);
|
|
396
|
+
transition: border-color 0.15s ease;
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
.phase-hdr:hover {
|
|
400
|
+
border-bottom-color: var(--accent);
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
.phase-hdr:hover h2 {
|
|
404
|
+
color: var(--accent);
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
.phase-hdr h2 {
|
|
408
|
+
transition: color 0.15s ease;
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
.phase-hdr .arr {
|
|
412
|
+
transition: transform 0.2s ease;
|
|
413
|
+
font-size: var(--text-xs);
|
|
414
|
+
color: var(--text-muted);
|
|
415
|
+
}
|
|
416
|
+
|
|
417
|
+
.phase-hdr.closed .arr {
|
|
418
|
+
transform: rotate(-90deg);
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
.phase-cnt {
|
|
422
|
+
font-size: var(--text-xs);
|
|
423
|
+
font-family: var(--font-mono);
|
|
424
|
+
color: var(--text-faint);
|
|
425
|
+
margin-left: auto;
|
|
426
|
+
letter-spacing: var(--ls-wide);
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
/* ─── Prompt List ─────────────────────────────── */
|
|
430
|
+
.plist {
|
|
431
|
+
display: flex;
|
|
432
|
+
flex-direction: column;
|
|
433
|
+
gap: var(--sp-2);
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
/* ─── Prompt Cards ────────────────────────────── */
|
|
437
|
+
.pcard {
|
|
438
|
+
background: var(--bg-card);
|
|
439
|
+
border: 1px solid var(--border);
|
|
440
|
+
border-radius: var(--radius);
|
|
441
|
+
padding: var(--sp-3) var(--sp-4);
|
|
442
|
+
box-shadow: var(--shadow-sm);
|
|
443
|
+
display: grid;
|
|
444
|
+
grid-template-columns: auto 1fr auto;
|
|
445
|
+
gap: var(--sp-2) var(--sp-3);
|
|
446
|
+
align-items: start;
|
|
447
|
+
transition: box-shadow 0.15s ease, transform 0.15s ease, border-color 0.15s ease;
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
.pcard:hover {
|
|
451
|
+
box-shadow: var(--shadow);
|
|
452
|
+
transform: translateY(-1px);
|
|
453
|
+
border-color: var(--accent-glow);
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
/* ─── Status Badges ──────────────────────────── */
|
|
457
|
+
.status-badge {
|
|
458
|
+
display: inline-flex;
|
|
459
|
+
align-items: center;
|
|
460
|
+
gap: var(--sp-1);
|
|
461
|
+
font-size: var(--text-xs);
|
|
462
|
+
font-weight: var(--fw-medium);
|
|
463
|
+
padding: 2px var(--sp-2);
|
|
464
|
+
border-radius: 99px;
|
|
465
|
+
white-space: nowrap;
|
|
466
|
+
flex-shrink: 0;
|
|
467
|
+
letter-spacing: var(--ls-wide);
|
|
468
|
+
line-height: var(--lh-tight);
|
|
469
|
+
}
|
|
470
|
+
|
|
471
|
+
.st-completed {
|
|
472
|
+
background: var(--green-bg);
|
|
473
|
+
color: var(--green);
|
|
474
|
+
border: 1px solid var(--green-border);
|
|
475
|
+
}
|
|
476
|
+
|
|
477
|
+
.st-likely-completed {
|
|
478
|
+
background: var(--blue-bg);
|
|
479
|
+
color: var(--blue);
|
|
480
|
+
border: 1px solid var(--blue-border);
|
|
481
|
+
}
|
|
482
|
+
|
|
483
|
+
.st-skipped {
|
|
484
|
+
background: var(--gray-bg);
|
|
485
|
+
color: var(--gray);
|
|
486
|
+
border: 1px solid var(--gray-border);
|
|
487
|
+
}
|
|
488
|
+
|
|
489
|
+
.st-pending {
|
|
490
|
+
background: var(--bg-inset);
|
|
491
|
+
color: var(--text-faint);
|
|
492
|
+
border: 1px solid var(--border);
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
/* ─── Status Legend ──────────────────────────── */
|
|
496
|
+
.status-legend {
|
|
497
|
+
display: flex;
|
|
498
|
+
flex-wrap: wrap;
|
|
499
|
+
gap: var(--sp-2);
|
|
500
|
+
margin-bottom: var(--sp-4);
|
|
501
|
+
padding: var(--sp-2) 0;
|
|
502
|
+
}
|
|
503
|
+
|
|
504
|
+
.status-legend .status-badge {
|
|
505
|
+
cursor: default;
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
/* ─── Prompt Card Inner ───────────────────────── */
|
|
509
|
+
.pinfo {
|
|
510
|
+
min-width: 0;
|
|
511
|
+
}
|
|
512
|
+
|
|
513
|
+
.pname {
|
|
514
|
+
font-weight: var(--fw-semi);
|
|
515
|
+
font-size: var(--text-base);
|
|
516
|
+
}
|
|
517
|
+
|
|
518
|
+
.pstep {
|
|
519
|
+
font-size: var(--text-xs);
|
|
520
|
+
font-family: var(--font-mono);
|
|
521
|
+
color: var(--text-faint);
|
|
522
|
+
letter-spacing: var(--ls-wide);
|
|
523
|
+
}
|
|
524
|
+
|
|
525
|
+
.pdesc {
|
|
526
|
+
font-size: var(--text-sm);
|
|
527
|
+
color: var(--text-muted);
|
|
528
|
+
margin-top: 2px;
|
|
529
|
+
line-height: var(--lh-relaxed);
|
|
530
|
+
}
|
|
531
|
+
|
|
532
|
+
.pdesc-long {
|
|
533
|
+
font-size: var(--text-xs);
|
|
534
|
+
color: var(--text-faint);
|
|
535
|
+
margin-top: 2px;
|
|
536
|
+
}
|
|
537
|
+
|
|
538
|
+
.pdeps {
|
|
539
|
+
font-size: var(--text-xs);
|
|
540
|
+
color: var(--yellow);
|
|
541
|
+
margin-top: var(--sp-1);
|
|
542
|
+
font-weight: var(--fw-medium);
|
|
543
|
+
}
|
|
544
|
+
|
|
545
|
+
/* ─── Copy Command Button ─────────────────────── */
|
|
546
|
+
.pcmd {
|
|
547
|
+
font-family: var(--font-mono);
|
|
548
|
+
font-size: var(--text-xs);
|
|
549
|
+
background: var(--bg-inset);
|
|
550
|
+
padding: 3px var(--sp-2);
|
|
551
|
+
border-radius: var(--radius-sm);
|
|
552
|
+
cursor: pointer;
|
|
553
|
+
border: 1px solid var(--border);
|
|
554
|
+
white-space: nowrap;
|
|
555
|
+
align-self: center;
|
|
556
|
+
color: var(--text-muted);
|
|
557
|
+
transition: border-color 0.15s ease, color 0.15s ease, background 0.15s ease;
|
|
558
|
+
letter-spacing: var(--ls-wide);
|
|
559
|
+
}
|
|
560
|
+
|
|
561
|
+
.pcmd:hover {
|
|
562
|
+
border-color: var(--accent);
|
|
563
|
+
color: var(--accent);
|
|
564
|
+
background: var(--accent-glow);
|
|
565
|
+
}
|
|
566
|
+
|
|
567
|
+
.pcmd.copied {
|
|
568
|
+
border-color: var(--green);
|
|
569
|
+
color: var(--green);
|
|
570
|
+
background: var(--green-bg);
|
|
571
|
+
}
|
|
572
|
+
|
|
573
|
+
/* ─── Prompt Modal ────────────────────────────── */
|
|
574
|
+
.modal-overlay {
|
|
575
|
+
position: fixed;
|
|
576
|
+
inset: 0;
|
|
577
|
+
background: rgba(0, 0, 0, 0.6);
|
|
578
|
+
display: flex;
|
|
579
|
+
align-items: center;
|
|
580
|
+
justify-content: center;
|
|
581
|
+
z-index: 1000;
|
|
582
|
+
padding: var(--sp-4);
|
|
583
|
+
}
|
|
584
|
+
|
|
585
|
+
.modal {
|
|
586
|
+
background: var(--bg-card);
|
|
587
|
+
border: 1px solid var(--border);
|
|
588
|
+
border-radius: var(--radius);
|
|
589
|
+
box-shadow: var(--shadow-lg);
|
|
590
|
+
max-width: 720px;
|
|
591
|
+
width: 100%;
|
|
592
|
+
max-height: 85vh;
|
|
593
|
+
display: flex;
|
|
594
|
+
flex-direction: column;
|
|
595
|
+
}
|
|
596
|
+
|
|
597
|
+
.modal-header {
|
|
598
|
+
display: flex;
|
|
599
|
+
align-items: center;
|
|
600
|
+
gap: var(--sp-3);
|
|
601
|
+
padding: var(--sp-4) var(--sp-5);
|
|
602
|
+
border-bottom: 1px solid var(--border);
|
|
603
|
+
flex-shrink: 0;
|
|
604
|
+
}
|
|
605
|
+
|
|
606
|
+
.modal-header h3 {
|
|
607
|
+
font-size: var(--text-lg);
|
|
608
|
+
font-weight: var(--fw-semi);
|
|
609
|
+
flex: 1;
|
|
610
|
+
min-width: 0;
|
|
611
|
+
}
|
|
612
|
+
|
|
613
|
+
.modal-close {
|
|
614
|
+
background: var(--bg-inset);
|
|
615
|
+
border: 1px solid var(--border);
|
|
616
|
+
border-radius: var(--radius-sm);
|
|
617
|
+
padding: var(--sp-1) var(--sp-2);
|
|
618
|
+
cursor: pointer;
|
|
619
|
+
font-size: var(--text-base);
|
|
620
|
+
color: var(--text-muted);
|
|
621
|
+
line-height: 1;
|
|
622
|
+
transition: border-color 0.15s ease, color 0.15s ease;
|
|
623
|
+
}
|
|
624
|
+
|
|
625
|
+
.modal-close:hover {
|
|
626
|
+
border-color: var(--accent);
|
|
627
|
+
color: var(--accent);
|
|
628
|
+
}
|
|
629
|
+
|
|
630
|
+
.modal-body {
|
|
631
|
+
padding: var(--sp-5);
|
|
632
|
+
overflow-y: auto;
|
|
633
|
+
flex: 1;
|
|
634
|
+
}
|
|
635
|
+
|
|
636
|
+
.modal-body pre {
|
|
637
|
+
font-family: var(--font-mono);
|
|
638
|
+
font-size: var(--text-sm);
|
|
639
|
+
line-height: var(--lh-relaxed);
|
|
640
|
+
white-space: pre-wrap;
|
|
641
|
+
word-break: break-word;
|
|
642
|
+
color: var(--text);
|
|
643
|
+
}
|
|
644
|
+
|
|
645
|
+
.modal-body pre .md-heading {
|
|
646
|
+
font-weight: var(--fw-bold);
|
|
647
|
+
color: var(--accent);
|
|
648
|
+
}
|
|
649
|
+
|
|
650
|
+
.modal-body pre .md-code {
|
|
651
|
+
background: var(--bg-inset);
|
|
652
|
+
padding: 1px 4px;
|
|
653
|
+
border-radius: 3px;
|
|
654
|
+
font-size: var(--text-xs);
|
|
655
|
+
}
|
|
656
|
+
|
|
657
|
+
.modal-footer {
|
|
658
|
+
display: flex;
|
|
659
|
+
gap: var(--sp-2);
|
|
660
|
+
padding: var(--sp-3) var(--sp-5);
|
|
661
|
+
border-top: 1px solid var(--border);
|
|
662
|
+
flex-shrink: 0;
|
|
663
|
+
}
|
|
664
|
+
|
|
665
|
+
.modal-copy-btn {
|
|
666
|
+
background: var(--accent);
|
|
667
|
+
color: #fff;
|
|
668
|
+
border: none;
|
|
669
|
+
border-radius: var(--radius-sm);
|
|
670
|
+
padding: var(--sp-2) var(--sp-4);
|
|
671
|
+
font-size: var(--text-sm);
|
|
672
|
+
font-weight: var(--fw-medium);
|
|
673
|
+
cursor: pointer;
|
|
674
|
+
transition: background 0.15s ease;
|
|
675
|
+
}
|
|
676
|
+
|
|
677
|
+
.modal-copy-btn:hover {
|
|
678
|
+
background: var(--accent-hover);
|
|
679
|
+
}
|
|
680
|
+
|
|
681
|
+
.modal-copy-btn.copied {
|
|
682
|
+
background: var(--green);
|
|
683
|
+
}
|
|
684
|
+
|
|
685
|
+
/* ─── Beads Task Section ─────────────────────── */
|
|
686
|
+
.beads-section {
|
|
687
|
+
margin-top: var(--sp-8);
|
|
688
|
+
margin-bottom: var(--sp-6);
|
|
689
|
+
}
|
|
690
|
+
|
|
691
|
+
.beads-filters {
|
|
692
|
+
display: flex;
|
|
693
|
+
gap: var(--sp-2);
|
|
694
|
+
margin-bottom: var(--sp-3);
|
|
695
|
+
}
|
|
696
|
+
|
|
697
|
+
.beads-filter {
|
|
698
|
+
background: var(--bg-inset);
|
|
699
|
+
border: 1px solid var(--border);
|
|
700
|
+
border-radius: 99px;
|
|
701
|
+
padding: var(--sp-1) var(--sp-3);
|
|
702
|
+
font-size: var(--text-xs);
|
|
703
|
+
font-weight: var(--fw-medium);
|
|
704
|
+
color: var(--text-muted);
|
|
705
|
+
cursor: pointer;
|
|
706
|
+
transition: border-color 0.15s ease, color 0.15s ease, background 0.15s ease;
|
|
707
|
+
letter-spacing: var(--ls-wide);
|
|
708
|
+
}
|
|
709
|
+
|
|
710
|
+
.beads-filter:hover {
|
|
711
|
+
border-color: var(--accent);
|
|
712
|
+
color: var(--accent);
|
|
713
|
+
}
|
|
714
|
+
|
|
715
|
+
.beads-filter.active {
|
|
716
|
+
background: var(--accent);
|
|
717
|
+
color: #fff;
|
|
718
|
+
border-color: var(--accent);
|
|
719
|
+
}
|
|
720
|
+
|
|
721
|
+
/* ─── Beads Status Badges ────────────────────── */
|
|
722
|
+
.st-bead-open {
|
|
723
|
+
background: var(--accent-glow);
|
|
724
|
+
color: var(--accent);
|
|
725
|
+
border: 1px solid var(--accent);
|
|
726
|
+
}
|
|
727
|
+
|
|
728
|
+
.st-bead-progress {
|
|
729
|
+
background: var(--blue-bg);
|
|
730
|
+
color: var(--blue);
|
|
731
|
+
border: 1px solid var(--blue-border);
|
|
732
|
+
}
|
|
733
|
+
|
|
734
|
+
.st-bead-blocked {
|
|
735
|
+
background: var(--yellow-bg);
|
|
736
|
+
color: var(--yellow);
|
|
737
|
+
border: 1px solid var(--yellow-border);
|
|
738
|
+
}
|
|
739
|
+
|
|
740
|
+
.st-bead-deferred {
|
|
741
|
+
background: var(--gray-bg);
|
|
742
|
+
color: var(--gray);
|
|
743
|
+
border: 1px solid var(--gray-border);
|
|
744
|
+
}
|
|
745
|
+
|
|
746
|
+
.st-bead-closed {
|
|
747
|
+
background: var(--green-bg);
|
|
748
|
+
color: var(--green);
|
|
749
|
+
border: 1px solid var(--green-border);
|
|
750
|
+
}
|
|
751
|
+
|
|
752
|
+
/* ─── Beads Filter Separator ─────────────────── */
|
|
753
|
+
.beads-filter-sep {
|
|
754
|
+
width: 1px;
|
|
755
|
+
background: var(--border);
|
|
756
|
+
align-self: stretch;
|
|
757
|
+
margin: 0 var(--sp-1);
|
|
758
|
+
}
|
|
759
|
+
|
|
760
|
+
/* ─── Beads Priority Filter ──────────────────── */
|
|
761
|
+
.beads-prio-filter {
|
|
762
|
+
background: var(--bg-inset);
|
|
763
|
+
border: 1px solid var(--border);
|
|
764
|
+
border-radius: 99px;
|
|
765
|
+
padding: var(--sp-1) var(--sp-3);
|
|
766
|
+
font-size: var(--text-xs);
|
|
767
|
+
font-weight: var(--fw-medium);
|
|
768
|
+
color: var(--text-muted);
|
|
769
|
+
cursor: pointer;
|
|
770
|
+
transition: border-color 0.15s ease, color 0.15s ease, background 0.15s ease;
|
|
771
|
+
letter-spacing: var(--ls-wide);
|
|
772
|
+
}
|
|
773
|
+
|
|
774
|
+
.beads-prio-filter:hover {
|
|
775
|
+
border-color: var(--accent);
|
|
776
|
+
color: var(--accent);
|
|
777
|
+
}
|
|
778
|
+
|
|
779
|
+
.beads-prio-filter.active {
|
|
780
|
+
background: var(--accent);
|
|
781
|
+
color: #fff;
|
|
782
|
+
border-color: var(--accent);
|
|
783
|
+
}
|
|
784
|
+
|
|
785
|
+
/* ─── Beads Task Detail Modal ────────────────── */
|
|
786
|
+
.bead-meta-grid {
|
|
787
|
+
display: grid;
|
|
788
|
+
grid-template-columns: 1fr 1fr;
|
|
789
|
+
gap: var(--sp-3);
|
|
790
|
+
padding: var(--sp-4) 0;
|
|
791
|
+
border-bottom: 1px solid var(--border-light);
|
|
792
|
+
}
|
|
793
|
+
|
|
794
|
+
.bead-meta-item {
|
|
795
|
+
display: flex;
|
|
796
|
+
flex-direction: column;
|
|
797
|
+
gap: 2px;
|
|
798
|
+
}
|
|
799
|
+
|
|
800
|
+
.bead-meta-label {
|
|
801
|
+
font-size: var(--text-xs);
|
|
802
|
+
color: var(--text-faint);
|
|
803
|
+
text-transform: uppercase;
|
|
804
|
+
letter-spacing: var(--ls-wide);
|
|
805
|
+
font-weight: var(--fw-medium);
|
|
806
|
+
}
|
|
807
|
+
|
|
808
|
+
.bead-meta-value {
|
|
809
|
+
font-size: var(--text-sm);
|
|
810
|
+
font-weight: var(--fw-medium);
|
|
811
|
+
color: var(--text);
|
|
812
|
+
}
|
|
813
|
+
|
|
814
|
+
.bead-description {
|
|
815
|
+
padding: var(--sp-4) 0;
|
|
816
|
+
border-bottom: 1px solid var(--border-light);
|
|
817
|
+
white-space: pre-wrap;
|
|
818
|
+
font-size: var(--text-sm);
|
|
819
|
+
line-height: var(--lh-relaxed);
|
|
820
|
+
color: var(--text-muted);
|
|
821
|
+
}
|
|
822
|
+
|
|
823
|
+
.bead-deps {
|
|
824
|
+
padding: var(--sp-4) 0;
|
|
825
|
+
border-bottom: 1px solid var(--border-light);
|
|
826
|
+
}
|
|
827
|
+
|
|
828
|
+
.bead-dep-group {
|
|
829
|
+
display: flex;
|
|
830
|
+
flex-wrap: wrap;
|
|
831
|
+
align-items: center;
|
|
832
|
+
gap: var(--sp-2);
|
|
833
|
+
margin-bottom: var(--sp-2);
|
|
834
|
+
}
|
|
835
|
+
|
|
836
|
+
.bead-dep-group:last-child {
|
|
837
|
+
margin-bottom: 0;
|
|
838
|
+
}
|
|
839
|
+
|
|
840
|
+
.bead-dep-label {
|
|
841
|
+
font-size: var(--text-xs);
|
|
842
|
+
color: var(--text-faint);
|
|
843
|
+
text-transform: uppercase;
|
|
844
|
+
letter-spacing: var(--ls-wide);
|
|
845
|
+
font-weight: var(--fw-medium);
|
|
846
|
+
min-width: 80px;
|
|
847
|
+
}
|
|
848
|
+
|
|
849
|
+
.bead-dep-link {
|
|
850
|
+
display: inline-block;
|
|
851
|
+
font-family: var(--font-mono);
|
|
852
|
+
font-size: var(--text-xs);
|
|
853
|
+
padding: 2px var(--sp-2);
|
|
854
|
+
border-radius: 99px;
|
|
855
|
+
background: var(--accent-glow);
|
|
856
|
+
color: var(--accent);
|
|
857
|
+
border: 1px solid var(--accent);
|
|
858
|
+
cursor: pointer;
|
|
859
|
+
transition: background 0.15s ease, color 0.15s ease;
|
|
860
|
+
text-decoration: none;
|
|
861
|
+
}
|
|
862
|
+
|
|
863
|
+
.bead-dep-link:hover {
|
|
864
|
+
background: var(--accent);
|
|
865
|
+
color: #fff;
|
|
866
|
+
}
|
|
867
|
+
|
|
868
|
+
.bead-timestamps {
|
|
869
|
+
display: flex;
|
|
870
|
+
flex-wrap: wrap;
|
|
871
|
+
gap: var(--sp-4);
|
|
872
|
+
padding: var(--sp-4) 0;
|
|
873
|
+
}
|
|
874
|
+
|
|
875
|
+
.bead-ts-item {
|
|
876
|
+
display: flex;
|
|
877
|
+
flex-direction: column;
|
|
878
|
+
gap: 2px;
|
|
879
|
+
}
|
|
880
|
+
|
|
881
|
+
.bead-ts-label {
|
|
882
|
+
font-size: var(--text-xs);
|
|
883
|
+
color: var(--text-faint);
|
|
884
|
+
text-transform: uppercase;
|
|
885
|
+
letter-spacing: var(--ls-wide);
|
|
886
|
+
font-weight: var(--fw-medium);
|
|
887
|
+
}
|
|
888
|
+
|
|
889
|
+
.bead-ts-value {
|
|
890
|
+
font-size: var(--text-sm);
|
|
891
|
+
color: var(--text-muted);
|
|
892
|
+
}
|
|
893
|
+
|
|
894
|
+
.bead-ts-value[title] {
|
|
895
|
+
border-bottom: 1px dotted var(--text-faint);
|
|
896
|
+
cursor: help;
|
|
897
|
+
}
|
|
898
|
+
|
|
899
|
+
/* ─── Standalone Commands Section ─────────────── */
|
|
900
|
+
.ongoing {
|
|
901
|
+
margin-top: var(--sp-10);
|
|
902
|
+
}
|
|
903
|
+
|
|
904
|
+
.ongoing h2 {
|
|
905
|
+
letter-spacing: var(--ls-wide);
|
|
906
|
+
text-transform: uppercase;
|
|
907
|
+
font-size: var(--text-sm);
|
|
908
|
+
color: var(--text-muted);
|
|
909
|
+
margin-bottom: var(--sp-4);
|
|
910
|
+
border-bottom: 2px solid var(--border);
|
|
911
|
+
padding-bottom: var(--sp-2);
|
|
912
|
+
}
|
|
913
|
+
|
|
914
|
+
/* ─── Footer ──────────────────────────────────── */
|
|
915
|
+
.footer {
|
|
916
|
+
text-align: center;
|
|
917
|
+
font-size: var(--text-xs);
|
|
918
|
+
color: var(--text-faint);
|
|
919
|
+
margin-top: var(--sp-10);
|
|
920
|
+
padding-top: var(--sp-4);
|
|
921
|
+
border-top: 1px solid var(--border-light);
|
|
922
|
+
letter-spacing: var(--ls-wide);
|
|
923
|
+
}
|
|
924
|
+
|
|
925
|
+
/* ─── Utilities ───────────────────────────────── */
|
|
926
|
+
.hidden {
|
|
927
|
+
display: none;
|
|
928
|
+
}
|
|
929
|
+
|
|
930
|
+
/* Build-observability severity + verdict tokens (Plan 4) */
|
|
931
|
+
:root {
|
|
932
|
+
--sev-p0: #dc2626; /* red 600 */
|
|
933
|
+
--sev-p1: #ea580c; /* orange 600 */
|
|
934
|
+
--sev-p2: #ca8a04; /* yellow 600 */
|
|
935
|
+
--sev-p3: #2563eb; /* blue 600 */
|
|
936
|
+
--sev-pass: #16a34a; /* green 600 */
|
|
937
|
+
}
|
|
938
|
+
[data-theme="dark"] {
|
|
939
|
+
--sev-p0: #f87171;
|
|
940
|
+
--sev-p1: #fb923c;
|
|
941
|
+
--sev-p2: #facc15;
|
|
942
|
+
--sev-p3: #60a5fa;
|
|
943
|
+
--sev-pass: #4ade80;
|
|
944
|
+
}
|
|
945
|
+
|
|
946
|
+
/* Build-observability panel layout */
|
|
947
|
+
.panel {
|
|
948
|
+
background: var(--bg-card);
|
|
949
|
+
border: 1px solid var(--border);
|
|
950
|
+
border-radius: var(--radius);
|
|
951
|
+
padding: var(--sp-4) var(--sp-6);
|
|
952
|
+
margin-bottom: var(--sp-6);
|
|
953
|
+
}
|
|
954
|
+
.panel > header {
|
|
955
|
+
display: flex;
|
|
956
|
+
align-items: center;
|
|
957
|
+
gap: var(--sp-3);
|
|
958
|
+
margin-bottom: var(--sp-4);
|
|
959
|
+
flex-wrap: wrap;
|
|
960
|
+
}
|
|
961
|
+
.panel > header h2 {
|
|
962
|
+
margin: 0;
|
|
963
|
+
font-size: var(--text-base);
|
|
964
|
+
font-weight: var(--fw-semi);
|
|
965
|
+
}
|
|
966
|
+
.panel .meta {
|
|
967
|
+
color: var(--text-muted);
|
|
968
|
+
font-size: var(--text-sm);
|
|
969
|
+
}
|
|
970
|
+
.grid { display: grid; gap: var(--sp-4); }
|
|
971
|
+
.grid-2 { grid-template-columns: repeat(2, 1fr); }
|
|
972
|
+
@media (max-width: 640px) { .grid-2 { grid-template-columns: 1fr; } }
|
|
973
|
+
|
|
974
|
+
/* Finding filters */
|
|
975
|
+
.finding-filters {
|
|
976
|
+
display: flex;
|
|
977
|
+
gap: var(--sp-2);
|
|
978
|
+
flex-wrap: wrap;
|
|
979
|
+
margin-bottom: var(--sp-4);
|
|
980
|
+
}
|
|
981
|
+
.finding-filters button {
|
|
982
|
+
padding: var(--sp-1) var(--sp-3);
|
|
983
|
+
border: 1px solid var(--border);
|
|
984
|
+
border-radius: var(--radius-sm);
|
|
985
|
+
background: var(--bg-inset);
|
|
986
|
+
color: var(--text);
|
|
987
|
+
font-size: var(--text-sm);
|
|
988
|
+
cursor: pointer;
|
|
989
|
+
}
|
|
990
|
+
.finding-filters button:hover,
|
|
991
|
+
.finding-filters button.active {
|
|
992
|
+
background: var(--accent);
|
|
993
|
+
border-color: var(--accent);
|
|
994
|
+
color: #fff;
|
|
995
|
+
}
|
|
996
|
+
|
|
997
|
+
/* Findings list */
|
|
998
|
+
.findings {
|
|
999
|
+
list-style: none;
|
|
1000
|
+
padding: 0;
|
|
1001
|
+
margin: 0;
|
|
1002
|
+
display: flex;
|
|
1003
|
+
flex-direction: column;
|
|
1004
|
+
gap: var(--sp-3);
|
|
1005
|
+
}
|
|
1006
|
+
.finding {
|
|
1007
|
+
background: var(--bg-inset);
|
|
1008
|
+
border: 1px solid var(--border-light);
|
|
1009
|
+
border-radius: var(--radius-sm);
|
|
1010
|
+
padding: var(--sp-3) var(--sp-4);
|
|
1011
|
+
}
|
|
1012
|
+
.finding header {
|
|
1013
|
+
display: flex;
|
|
1014
|
+
align-items: center;
|
|
1015
|
+
gap: var(--sp-2);
|
|
1016
|
+
flex-wrap: wrap;
|
|
1017
|
+
margin-bottom: var(--sp-2);
|
|
1018
|
+
}
|
|
1019
|
+
.finding-id {
|
|
1020
|
+
font-family: var(--font-mono, monospace);
|
|
1021
|
+
font-size: var(--text-xs);
|
|
1022
|
+
color: var(--text-muted);
|
|
1023
|
+
background: var(--bg-card);
|
|
1024
|
+
border: 1px solid var(--border);
|
|
1025
|
+
border-radius: 4px;
|
|
1026
|
+
padding: 1px var(--sp-1);
|
|
1027
|
+
}
|
|
1028
|
+
.finding .lens {
|
|
1029
|
+
font-size: var(--text-xs);
|
|
1030
|
+
color: var(--text-muted);
|
|
1031
|
+
}
|
|
1032
|
+
.finding .title {
|
|
1033
|
+
font-size: var(--text-sm);
|
|
1034
|
+
font-weight: var(--fw-semi);
|
|
1035
|
+
flex: 1;
|
|
1036
|
+
}
|
|
1037
|
+
.finding p { margin: 0; font-size: var(--text-sm); color: var(--text-muted); }
|
|
1038
|
+
.empty { color: var(--text-muted); font-size: var(--text-sm); text-align: center; padding: var(--sp-4); }
|
|
1039
|
+
|
|
1040
|
+
/* ── Mermaid diagrams ─────────────────────────────────────────────────────────
|
|
1041
|
+
The build renders mermaid to inline SVG via mmdc, then sanitizeSvg() +
|
|
1042
|
+
rehype-sanitize strip the SVG's own <script>, <foreignObject>, AND <style>
|
|
1043
|
+
for security. Stripping <style> means the diagram arrives unstyled (nodes
|
|
1044
|
+
default to a black fill). These theme-token rules restyle the SVG so nodes,
|
|
1045
|
+
edges, arrowheads, and labels render correctly — and follow light/dark mode.
|
|
1046
|
+
Authors must render with htmlLabels:false (the generator forces this) so node
|
|
1047
|
+
labels are native <text>/<tspan> rather than stripped <foreignObject> HTML. */
|
|
1048
|
+
figure.mermaid { margin: var(--sp-5) 0; text-align: center; }
|
|
1049
|
+
figure.mermaid svg { max-width: 100%; height: auto; }
|
|
1050
|
+
/* Node shapes */
|
|
1051
|
+
figure.mermaid svg .node rect,
|
|
1052
|
+
figure.mermaid svg .node circle,
|
|
1053
|
+
figure.mermaid svg .node ellipse,
|
|
1054
|
+
figure.mermaid svg .node polygon,
|
|
1055
|
+
figure.mermaid svg .node path {
|
|
1056
|
+
fill: var(--bg-inset);
|
|
1057
|
+
stroke: var(--border);
|
|
1058
|
+
stroke-width: 1px;
|
|
1059
|
+
}
|
|
1060
|
+
/* Background helper rects mermaid emits behind labels */
|
|
1061
|
+
figure.mermaid svg .node .label-container { fill: var(--bg-inset); stroke: var(--border); }
|
|
1062
|
+
figure.mermaid svg rect.background { fill: none; stroke: none; }
|
|
1063
|
+
/* Labels (rendered as <text>/<tspan> when htmlLabels:false) */
|
|
1064
|
+
figure.mermaid svg .nodeLabel,
|
|
1065
|
+
figure.mermaid svg .node text,
|
|
1066
|
+
figure.mermaid svg text.nodeLabel,
|
|
1067
|
+
figure.mermaid svg .label text,
|
|
1068
|
+
figure.mermaid svg span.nodeLabel {
|
|
1069
|
+
fill: var(--text);
|
|
1070
|
+
color: var(--text);
|
|
1071
|
+
font-family: var(--font-sans);
|
|
1072
|
+
}
|
|
1073
|
+
/* Edges: thin strokes, not filled blobs */
|
|
1074
|
+
figure.mermaid svg .edgePath path,
|
|
1075
|
+
figure.mermaid svg path.flowchart-link,
|
|
1076
|
+
figure.mermaid svg .flowchart-link {
|
|
1077
|
+
fill: none;
|
|
1078
|
+
stroke: var(--text-faint);
|
|
1079
|
+
stroke-width: 1.5px;
|
|
1080
|
+
}
|
|
1081
|
+
/* Arrowheads */
|
|
1082
|
+
figure.mermaid svg marker path,
|
|
1083
|
+
figure.mermaid svg .marker {
|
|
1084
|
+
fill: var(--text-faint);
|
|
1085
|
+
stroke: var(--text-faint);
|
|
1086
|
+
}
|
|
1087
|
+
figure.mermaid svg .edgeLabel,
|
|
1088
|
+
figure.mermaid svg .edgeLabel text { fill: var(--text-muted); color: var(--text-muted); }
|
|
1089
|
+
|
|
1090
|
+
/* ============================================================================
|
|
1091
|
+
* guides.css — component + layout styles for `scaffold guides` reference pages.
|
|
1092
|
+
*
|
|
1093
|
+
* Pairs with lib/dashboard-theme.css (the token source) and src/guides/chrome.ts
|
|
1094
|
+
* (the behavior). Styles the guide CHROME (.topbar, .layout, .rail, nav.toc,
|
|
1095
|
+
* .content) and the markdown DIRECTIVES (callouts, sev chips, filter-tables,
|
|
1096
|
+
* charts, tabs, citations) plus base prose typography.
|
|
1097
|
+
*
|
|
1098
|
+
* DESIGN SYSTEM: all COLORS come from dashboard-theme.css tokens, and spacing
|
|
1099
|
+
* uses the --sp-* scale wherever it maps. The few structural layout constants
|
|
1100
|
+
* (topbar height, rail/drawer width, chart label column, card min) are declared
|
|
1101
|
+
* as local custom properties below; a handful of sub-scale UI values (chip/bar
|
|
1102
|
+
* sizing, em-based inline-code padding) and the responsive breakpoint are
|
|
1103
|
+
* literal because no token expresses them. Both themes are covered because every
|
|
1104
|
+
* color is a token.
|
|
1105
|
+
* ==========================================================================*/
|
|
1106
|
+
|
|
1107
|
+
:root {
|
|
1108
|
+
--topbar-h: 52px; /* sticky topbar height; rail sticky offset keys off it */
|
|
1109
|
+
--rail-w: 260px; /* desktop TOC sidebar column */
|
|
1110
|
+
--drawer-w: 280px; /* mobile off-canvas TOC drawer */
|
|
1111
|
+
--card-min: 260px; /* index card min track width */
|
|
1112
|
+
--chart-label-w: 90px; /* chart row label column min */
|
|
1113
|
+
}
|
|
1114
|
+
|
|
1115
|
+
/* ── Base / reset on top of the token base in dashboard-theme.css ─────────── */
|
|
1116
|
+
.content a { color: var(--accent); text-decoration: none; }
|
|
1117
|
+
.content a:hover { text-decoration: underline; }
|
|
1118
|
+
.content strong { font-weight: var(--fw-semi); }
|
|
1119
|
+
.content hr { border: 0; border-top: 1px solid var(--border-light); margin: var(--sp-6) 0; }
|
|
1120
|
+
|
|
1121
|
+
/* Consistent keyboard focus for every interactive control (a11y). */
|
|
1122
|
+
.topbar button:focus-visible,
|
|
1123
|
+
.copy-btn:focus-visible,
|
|
1124
|
+
.tab-btn:focus-visible,
|
|
1125
|
+
.filter-input:focus-visible,
|
|
1126
|
+
nav.toc a:focus-visible,
|
|
1127
|
+
.guide-card:focus-visible,
|
|
1128
|
+
.content a:focus-visible {
|
|
1129
|
+
outline: 2px solid var(--accent); outline-offset: 2px; border-radius: var(--radius-sm);
|
|
1130
|
+
}
|
|
1131
|
+
|
|
1132
|
+
/* ── Topbar ────────────────────────────────────────────────────────────────*/
|
|
1133
|
+
.topbar {
|
|
1134
|
+
position: sticky; top: 0; z-index: 60; height: var(--topbar-h);
|
|
1135
|
+
display: flex; align-items: center; gap: var(--sp-3);
|
|
1136
|
+
padding: 0 var(--page-pad);
|
|
1137
|
+
background: var(--bg-card); border-bottom: 1px solid var(--border);
|
|
1138
|
+
}
|
|
1139
|
+
.topbar h1 {
|
|
1140
|
+
flex: 1; min-width: 0; margin: 0;
|
|
1141
|
+
font-size: var(--text-lg); font-weight: var(--fw-bold);
|
|
1142
|
+
letter-spacing: var(--ls-tight);
|
|
1143
|
+
white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
|
|
1144
|
+
}
|
|
1145
|
+
.topbar button {
|
|
1146
|
+
background: var(--bg-card); border: 1px solid var(--border); color: var(--text);
|
|
1147
|
+
border-radius: var(--radius-sm); padding: var(--sp-1) var(--sp-3); font-size: var(--text-base);
|
|
1148
|
+
line-height: 1; cursor: pointer; font-family: inherit;
|
|
1149
|
+
}
|
|
1150
|
+
.topbar button:hover { background: var(--bg-hover); border-color: var(--accent); }
|
|
1151
|
+
.nav-toggle { display: none; }
|
|
1152
|
+
|
|
1153
|
+
/* ── Layout: sticky sidebar TOC + reading-width content ──────────────────── */
|
|
1154
|
+
.layout {
|
|
1155
|
+
max-width: var(--max-w); margin: 0 auto;
|
|
1156
|
+
display: grid; grid-template-columns: var(--rail-w) minmax(0, 1fr);
|
|
1157
|
+
gap: var(--sp-8); padding: 0 var(--page-pad);
|
|
1158
|
+
}
|
|
1159
|
+
.rail {
|
|
1160
|
+
position: sticky; top: var(--topbar-h); align-self: start;
|
|
1161
|
+
height: calc(100vh - var(--topbar-h)); overflow-y: auto;
|
|
1162
|
+
padding: var(--sp-5) 0; border-right: 1px solid var(--border-light);
|
|
1163
|
+
}
|
|
1164
|
+
.content { min-width: 0; padding: var(--sp-6) 0 var(--sp-10); }
|
|
1165
|
+
|
|
1166
|
+
/* Backdrop behind the mobile drawer (toggled with the rail via chrome.ts). */
|
|
1167
|
+
.rail-backdrop { display: none; }
|
|
1168
|
+
/* In-drawer close button — hidden on desktop (the rail is a static sidebar). */
|
|
1169
|
+
.rail-close { display: none; }
|
|
1170
|
+
|
|
1171
|
+
/* ── Table of contents (scrollspy marks a.active) ────────────────────────── */
|
|
1172
|
+
nav.toc ul { list-style: none; margin: 0; padding: 0; }
|
|
1173
|
+
nav.toc li { margin: 0; }
|
|
1174
|
+
nav.toc a {
|
|
1175
|
+
display: block; padding: var(--sp-1) var(--sp-3); line-height: 1.35;
|
|
1176
|
+
color: var(--text-muted); font-size: var(--text-sm);
|
|
1177
|
+
text-decoration: none; border-left: 2px solid transparent;
|
|
1178
|
+
border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
|
|
1179
|
+
}
|
|
1180
|
+
nav.toc a:hover { color: var(--text); background: var(--bg-hover); }
|
|
1181
|
+
nav.toc a.active {
|
|
1182
|
+
color: var(--accent); border-left-color: var(--accent);
|
|
1183
|
+
background: var(--accent-glow); font-weight: var(--fw-medium);
|
|
1184
|
+
}
|
|
1185
|
+
nav.toc li.toc-3 a { padding-left: var(--sp-6); font-size: var(--text-xs); }
|
|
1186
|
+
|
|
1187
|
+
/* ── Prose typography ──────────────────────────────────────────────────────*/
|
|
1188
|
+
.content h2 {
|
|
1189
|
+
font-size: var(--text-xl); letter-spacing: var(--ls-tight);
|
|
1190
|
+
margin: var(--sp-8) 0 var(--sp-3); padding-bottom: var(--sp-2);
|
|
1191
|
+
border-bottom: 1px solid var(--border-light); scroll-margin-top: calc(var(--topbar-h) + var(--sp-3));
|
|
1192
|
+
}
|
|
1193
|
+
.content h3 {
|
|
1194
|
+
font-size: var(--text-lg); margin: var(--sp-5) 0 var(--sp-2);
|
|
1195
|
+
scroll-margin-top: calc(var(--topbar-h) + var(--sp-3));
|
|
1196
|
+
}
|
|
1197
|
+
.content p { margin: var(--sp-3) 0; line-height: var(--lh-relaxed); }
|
|
1198
|
+
.content ul, .content ol { margin: var(--sp-3) 0; padding-left: var(--sp-6); }
|
|
1199
|
+
.content li { margin: var(--sp-1) 0; line-height: var(--lh-relaxed); }
|
|
1200
|
+
.content blockquote {
|
|
1201
|
+
margin: var(--sp-3) 0; padding: var(--sp-1) var(--sp-4);
|
|
1202
|
+
border-left: 3px solid var(--border); color: var(--text-muted);
|
|
1203
|
+
}
|
|
1204
|
+
|
|
1205
|
+
/* ── Inline code + code blocks (chrome.ts wraps <pre> in .code + .copy-btn) ──*/
|
|
1206
|
+
.content code {
|
|
1207
|
+
font-family: var(--font-mono); font-size: 0.85em;
|
|
1208
|
+
background: var(--bg-inset); padding: 0.12em 0.4em; border-radius: var(--radius-sm);
|
|
1209
|
+
}
|
|
1210
|
+
.content .code { position: relative; margin: var(--sp-3) 0; }
|
|
1211
|
+
.content .code pre {
|
|
1212
|
+
margin: 0; padding: var(--sp-3) var(--sp-4); overflow-x: auto;
|
|
1213
|
+
background: var(--bg-inset); border: 1px solid var(--border-light);
|
|
1214
|
+
border-radius: var(--radius-sm); font-family: var(--font-mono);
|
|
1215
|
+
font-size: var(--text-sm); line-height: var(--lh-relaxed);
|
|
1216
|
+
}
|
|
1217
|
+
.content .code pre code { background: none; padding: 0; font-size: inherit; }
|
|
1218
|
+
.copy-btn {
|
|
1219
|
+
position: absolute; top: var(--sp-1); right: var(--sp-1);
|
|
1220
|
+
background: var(--bg-card); border: 1px solid var(--border); color: var(--text-muted);
|
|
1221
|
+
border-radius: var(--radius-sm); font-size: var(--text-xs); padding: var(--sp-1) var(--sp-2);
|
|
1222
|
+
cursor: pointer; opacity: 0.85; font-family: inherit;
|
|
1223
|
+
}
|
|
1224
|
+
.copy-btn:hover { color: var(--accent); border-color: var(--accent); opacity: 1; }
|
|
1225
|
+
|
|
1226
|
+
/* ── Callouts ─ (border-color BEFORE border-left-color so the accent wins) ── */
|
|
1227
|
+
.callout {
|
|
1228
|
+
margin: var(--sp-4) 0; padding: var(--sp-3) var(--sp-4);
|
|
1229
|
+
border: 1px solid var(--border); border-left-width: 3px;
|
|
1230
|
+
border-radius: var(--radius-sm); background: var(--bg-card);
|
|
1231
|
+
}
|
|
1232
|
+
.callout > :first-child { margin-top: 0; }
|
|
1233
|
+
.callout > :last-child { margin-bottom: 0; }
|
|
1234
|
+
.callout-note, .callout-info { background: var(--blue-bg); border-color: var(--blue-border); border-left-color: var(--blue); }
|
|
1235
|
+
.callout-tip { background: var(--green-bg); border-color: var(--green-border); border-left-color: var(--green); }
|
|
1236
|
+
.callout-warning { background: var(--yellow-bg); border-color: var(--yellow-border); border-left-color: var(--yellow); }
|
|
1237
|
+
.callout-danger { background: var(--red-bg); border-color: var(--red-border); border-left-color: var(--red); }
|
|
1238
|
+
|
|
1239
|
+
/* ── Severity chips (:sev) — tight pill, sub-scale vertical padding ───────── */
|
|
1240
|
+
.sev {
|
|
1241
|
+
display: inline-block; font-size: var(--text-xs); font-weight: var(--fw-semi);
|
|
1242
|
+
padding: 1px var(--sp-2); border-radius: 999px; line-height: 1.5;
|
|
1243
|
+
border: 1px solid var(--border); background: var(--bg-inset); color: var(--text-muted);
|
|
1244
|
+
white-space: nowrap;
|
|
1245
|
+
}
|
|
1246
|
+
.sev-p0 { color: var(--sev-p0); border-color: var(--sev-p0); }
|
|
1247
|
+
.sev-p1 { color: var(--sev-p1); border-color: var(--sev-p1); }
|
|
1248
|
+
.sev-p2 { color: var(--sev-p2); border-color: var(--sev-p2); }
|
|
1249
|
+
.sev-p3 { color: var(--sev-p3); border-color: var(--sev-p3); }
|
|
1250
|
+
.sev-pass { color: var(--sev-pass); border-color: var(--sev-pass); }
|
|
1251
|
+
|
|
1252
|
+
/* ── Citations (:cite) — inline provenance refs ──────────────────────────── */
|
|
1253
|
+
.fp, .cite-advisory {
|
|
1254
|
+
font-family: var(--font-mono); font-size: 0.82em;
|
|
1255
|
+
padding: 0.05em 0.35em; border-radius: var(--radius-sm);
|
|
1256
|
+
background: var(--bg-inset); border: 1px solid var(--border-light);
|
|
1257
|
+
}
|
|
1258
|
+
.fp { color: var(--accent); }
|
|
1259
|
+
.cite-advisory { color: var(--text-faint); border-style: dashed; }
|
|
1260
|
+
|
|
1261
|
+
/* ── Tables + filter-tables ──────────────────────────────────────────────── */
|
|
1262
|
+
.content table { width: 100%; border-collapse: collapse; margin: var(--sp-3) 0; font-size: var(--text-sm); }
|
|
1263
|
+
.content th, .content td { text-align: left; padding: var(--sp-2) var(--sp-3); border-bottom: 1px solid var(--border-light); vertical-align: top; }
|
|
1264
|
+
.content th {
|
|
1265
|
+
color: var(--text-muted); font-weight: var(--fw-semi); font-size: var(--text-xs);
|
|
1266
|
+
text-transform: uppercase; letter-spacing: var(--ls-wide); border-bottom-color: var(--border);
|
|
1267
|
+
}
|
|
1268
|
+
.content tbody tr:hover { background: var(--bg-hover); }
|
|
1269
|
+
.content td code { white-space: nowrap; }
|
|
1270
|
+
.filter-table { margin: var(--sp-4) 0; }
|
|
1271
|
+
.filter-input {
|
|
1272
|
+
width: 100%; max-width: 320px; margin-bottom: var(--sp-2);
|
|
1273
|
+
padding: var(--sp-2) var(--sp-3); font-family: inherit; font-size: var(--text-sm);
|
|
1274
|
+
color: var(--text); background: var(--bg-card);
|
|
1275
|
+
border: 1px solid var(--border); border-radius: var(--radius-sm);
|
|
1276
|
+
}
|
|
1277
|
+
.filter-input:focus { border-color: var(--accent); }
|
|
1278
|
+
|
|
1279
|
+
/* ── Charts (:::chart) — label + proportional bar (fill carries inline width%) */
|
|
1280
|
+
.chart-block { margin: var(--sp-4) 0; }
|
|
1281
|
+
.chart-row {
|
|
1282
|
+
display: grid; grid-template-columns: minmax(var(--chart-label-w), 24%) 1fr;
|
|
1283
|
+
align-items: center; gap: var(--sp-3); margin: var(--sp-1) 0;
|
|
1284
|
+
}
|
|
1285
|
+
.chart-label {
|
|
1286
|
+
font-size: var(--text-sm); color: var(--text-muted); text-align: right;
|
|
1287
|
+
white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
|
|
1288
|
+
}
|
|
1289
|
+
.chart-row .chart-bar {
|
|
1290
|
+
height: 0.9em; min-width: 2px; background: var(--accent);
|
|
1291
|
+
border-radius: var(--radius-sm);
|
|
1292
|
+
}
|
|
1293
|
+
|
|
1294
|
+
/* ── Tabs (::::tabs / :::tab) ─────────────────────────────────────────────── */
|
|
1295
|
+
.tabs { margin: var(--sp-4) 0; }
|
|
1296
|
+
.tablist { display: flex; flex-wrap: wrap; gap: var(--sp-1); border-bottom: 1px solid var(--border); margin-bottom: var(--sp-3); }
|
|
1297
|
+
.tab-btn {
|
|
1298
|
+
background: none; border: none; border-bottom: 2px solid transparent; margin-bottom: -1px;
|
|
1299
|
+
padding: var(--sp-2) var(--sp-3); color: var(--text-muted);
|
|
1300
|
+
font-family: inherit; font-size: var(--text-sm); font-weight: var(--fw-medium); cursor: pointer;
|
|
1301
|
+
}
|
|
1302
|
+
.tab-btn:hover { color: var(--text); }
|
|
1303
|
+
.tab-btn.active { color: var(--accent); border-bottom-color: var(--accent); }
|
|
1304
|
+
.tabpane { display: none; }
|
|
1305
|
+
.tabpane.active { display: block; }
|
|
1306
|
+
|
|
1307
|
+
/* ── Mermaid diagrams ────────────────────────────────────────────────────── */
|
|
1308
|
+
.content figure { margin: var(--sp-4) 0; text-align: center; }
|
|
1309
|
+
.content figure svg, .content > svg, .content .mermaid svg { max-width: 100%; height: auto; }
|
|
1310
|
+
|
|
1311
|
+
/* ── Index page: category card grid ──────────────────────────────────────── */
|
|
1312
|
+
.content .lead { color: var(--text-muted); font-size: var(--text-base); max-width: 60ch; margin-top: var(--sp-2); }
|
|
1313
|
+
.guide-cards {
|
|
1314
|
+
display: grid; grid-template-columns: repeat(auto-fill, minmax(min(var(--card-min), 100%), 1fr));
|
|
1315
|
+
gap: var(--sp-4); margin: var(--sp-4) 0 var(--sp-6);
|
|
1316
|
+
}
|
|
1317
|
+
.guide-card {
|
|
1318
|
+
display: flex; flex-direction: column; gap: var(--sp-2);
|
|
1319
|
+
padding: var(--sp-4); background: var(--bg-card);
|
|
1320
|
+
border: 1px solid var(--border); border-radius: var(--radius);
|
|
1321
|
+
color: inherit; text-decoration: none;
|
|
1322
|
+
transition: border-color 0.15s ease, box-shadow 0.15s ease;
|
|
1323
|
+
}
|
|
1324
|
+
.guide-card:hover { border-color: var(--accent); box-shadow: var(--shadow-md); text-decoration: none; }
|
|
1325
|
+
.guide-card-title { font-weight: var(--fw-semi); color: var(--accent); font-size: var(--text-base); }
|
|
1326
|
+
.guide-card-desc { color: var(--text-muted); font-size: var(--text-sm); line-height: var(--lh-normal); }
|
|
1327
|
+
|
|
1328
|
+
/* ── Responsive: TOC becomes an off-canvas drawer (chrome.ts toggles .open) ──*/
|
|
1329
|
+
/* 860px is literal — media queries cannot read custom properties. Revisit it if
|
|
1330
|
+
--topbar-h / --rail-w / --drawer-w change (the drawer sticky offsets key off them). */
|
|
1331
|
+
@media (max-width: 860px) {
|
|
1332
|
+
.nav-toggle { display: inline-flex; align-items: center; }
|
|
1333
|
+
.layout { grid-template-columns: 1fr; gap: 0; }
|
|
1334
|
+
.rail {
|
|
1335
|
+
position: fixed; top: var(--topbar-h); left: 0; bottom: 0; width: var(--drawer-w); z-index: 50;
|
|
1336
|
+
height: auto; background: var(--bg-card); border-right: 1px solid var(--border);
|
|
1337
|
+
padding: var(--sp-4); box-shadow: var(--shadow-lg);
|
|
1338
|
+
transform: translateX(-100%); transition: transform 0.2s ease, visibility 0.2s ease;
|
|
1339
|
+
/* Closed drawer is off-screen AND removed from tab order / pointer events. */
|
|
1340
|
+
visibility: hidden; pointer-events: none;
|
|
1341
|
+
}
|
|
1342
|
+
.rail.open { transform: translateX(0); visibility: visible; pointer-events: auto; }
|
|
1343
|
+
.rail-close {
|
|
1344
|
+
display: block; margin-left: auto; margin-bottom: var(--sp-2);
|
|
1345
|
+
background: var(--bg-card); border: 1px solid var(--border); color: var(--text);
|
|
1346
|
+
border-radius: var(--radius-sm); padding: var(--sp-1) var(--sp-3); font-size: var(--text-base);
|
|
1347
|
+
line-height: 1; cursor: pointer; font-family: inherit;
|
|
1348
|
+
}
|
|
1349
|
+
.rail-close:hover { background: var(--bg-hover); border-color: var(--accent); }
|
|
1350
|
+
.rail-close:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
|
|
1351
|
+
.rail-backdrop {
|
|
1352
|
+
display: block; position: fixed; inset: var(--topbar-h) 0 0 0;
|
|
1353
|
+
background: var(--scrim); z-index: 49;
|
|
1354
|
+
opacity: 0; pointer-events: none; transition: opacity 0.2s ease;
|
|
1355
|
+
}
|
|
1356
|
+
.rail.open ~ .rail-backdrop { opacity: 1; pointer-events: auto; }
|
|
1357
|
+
}
|
|
1358
|
+
</style>
|
|
1359
|
+
<script>(function(){try{var t=localStorage.getItem('guide-theme');if(!t&&window.matchMedia&&matchMedia('(prefers-color-scheme: dark)').matches)t='dark';if(t)document.documentElement.setAttribute('data-theme',t);}catch(e){}})();</script>
|
|
1360
|
+
</head>
|
|
1361
|
+
<body>
|
|
1362
|
+
<header class="topbar">
|
|
1363
|
+
<button data-action="nav" class="nav-toggle" aria-label="Toggle navigation"
|
|
1364
|
+
aria-expanded="false" aria-controls="guide-toc">☰</button>
|
|
1365
|
+
<h1>Build Observability</h1>
|
|
1366
|
+
<button data-action="theme" class="theme-toggle" aria-label="Toggle theme">◐</button>
|
|
1367
|
+
</header>
|
|
1368
|
+
<div class="layout">
|
|
1369
|
+
<aside class="rail" id="guide-toc">
|
|
1370
|
+
<button class="rail-close" data-action="nav" aria-label="Close navigation">✕</button>
|
|
1371
|
+
<nav class="toc" aria-label="Table of contents"><ul><li class="toc-2"><a href="#why-build-observability-exists">Why Build Observability exists</a></li><li class="toc-3"><a href="#what-goes-wrong-without-it">What goes wrong without it</a></li><li class="toc-3"><a href="#what-good-build-observability-produces">What good build observability produces</a></li><li class="toc-2"><a href="#system-map">System map</a></li><li class="toc-2"><a href="#the-ledger">The ledger</a></li><li class="toc-3"><a href="#how-a-write-happens">How a write happens</a></li><li class="toc-3"><a href="#the-nine-event-types">The nine event types</a></li><li class="toc-3"><a href="#building-a-scaffold-observe-event-command">Building a scaffold observe event command</a></li><li class="toc-3"><a href="#redaction-write-time-and-render-time">Redaction — write time and render time</a></li><li class="toc-3"><a href="#worktree-identity">Worktree identity</a></li><li class="toc-2"><a href="#adapters">Adapters</a></li><li class="toc-3"><a href="#source-priority">Source priority</a></li><li class="toc-2"><a href="#the-nine-lens-audit">The nine-lens audit</a></li><li class="toc-3"><a href="#scope-order-and-skips">Scope, order and skips</a></li><li class="toc-3"><a href="#what-feeds-the-doc-graph">What feeds the doc-graph</a></li><li class="toc-3"><a href="#all-nine-at-a-glance">All nine at a glance</a></li><li class="toc-3"><a href="#lens-by-lens">Lens by lens</a></li><li class="toc-2"><a href="#the-observe-audit-cli">The observe audit CLI</a></li><li class="toc-3"><a href="#every-flag">Every flag</a></li><li class="toc-3"><a href="#verdict-taxonomy">Verdict taxonomy</a></li><li class="toc-3"><a href="#companion-verb-scaffold-observe-ack">Companion verb — scaffold observe ack</a></li><li class="toc-3"><a href="#exit-codes-across-observe-verbs">Exit codes across observe verbs</a></li><li class="toc-2"><a href="#progress-replay-stall">Progress, replay & stall</a></li><li class="toc-3"><a href="#fusion-how-the-timeline-is-built">Fusion — how the timeline is built</a></li><li class="toc-3"><a href="#stall-detection-the-six-signals">Stall detection — the six signals</a></li><li class="toc-3"><a href="#flags">Flags</a></li><li class="toc-2"><a href="#phase-boundary-triggers">Phase-boundary triggers</a></li><li class="toc-3"><a href="#the-hook">The hook</a></li><li class="toc-3"><a href="#config-timestamps">Config & timestamps</a></li><li class="toc-2"><a href="#mmr-doc-conformance-channel">MMR doc-conformance channel</a></li><li class="toc-3"><a href="#finding-translation">Finding translation</a></li><li class="toc-3"><a href="#enabling-it">Enabling it</a></li><li class="toc-2"><a href="#the---fix-flow">The --fix flow</a></li><li class="toc-3"><a href="#the-five-phases">The five phases</a></li><li class="toc-3"><a href="#abort-safety">Abort safety</a></li><li class="toc-3"><a href="#config-the-fix-block">Config — the fix: block</a></li><li class="toc-2"><a href="#harvest-recover-teardown">Harvest, recover & teardown</a></li><li class="toc-3"><a href="#commands">Commands</a></li><li class="toc-2"><a href="#renderers">Renderers</a></li><li class="toc-2"><a href="#config-reference">Config reference</a></li><li class="toc-2"><a href="#where-it-lives">Where it lives</a></li><li class="toc-2"><a href="#shipping-history">Shipping history</a></li><li class="toc-2"><a href="#known-divergences">Known divergences</a></li></ul></nav>
|
|
1372
|
+
</aside>
|
|
1373
|
+
<main class="content"><h2 id="why-build-observability-exists">Why Build Observability exists</h2>
|
|
1374
|
+
<p>When several agents (and humans) build a project in parallel worktrees, the
|
|
1375
|
+
<em>reasoning</em> behind the build evaporates. A decision gets made in a throwaway
|
|
1376
|
+
branch, a blocker is hit and worked around, a story is silently dropped — and
|
|
1377
|
+
none of it survives the squash-merge. The docs say one thing; the code drifts to
|
|
1378
|
+
another. Build Observability turns those ephemeral moments into a durable,
|
|
1379
|
+
queryable record, then audits the record against the planning docs.</p>
|
|
1380
|
+
<h3 id="what-goes-wrong-without-it">What goes wrong without it</h3>
|
|
1381
|
+
<ul>
|
|
1382
|
+
<li><strong>Decisions die at teardown.</strong> An agent records "we switched the cache to
|
|
1383
|
+
Redis" in its head, opens a PR, the worktree is removed — and the rationale is
|
|
1384
|
+
gone. The next agent re-litigates it.</li>
|
|
1385
|
+
<li><strong>Blockers go unaddressed.</strong> A dependency block is hit at hour 0 and nobody
|
|
1386
|
+
notices it is still open at hour 6.</li>
|
|
1387
|
+
<li><strong>Phase boundaries pass unaudited.</strong> <code>tech-stack.md</code> is marked complete while
|
|
1388
|
+
it still contradicts the PRD; the contradiction is found three phases later.</li>
|
|
1389
|
+
<li><strong>Doc/code drift accumulates.</strong> A component is used outside its declared
|
|
1390
|
+
layer; an acceptance criterion never gets a test; a coding-standard erodes
|
|
1391
|
+
file by file.</li>
|
|
1392
|
+
</ul>
|
|
1393
|
+
<p>The classic failure mode is a worktree teardown that takes the ledger with it:
|
|
1394
|
+
an agent worktree's <code>.scaffold/activity.jsonl</code> is lost the moment the worktree
|
|
1395
|
+
is removed, <em>unless</em> it is harvested into the primary archive first. The
|
|
1396
|
+
harvester (<code>src/observability/engine/harvester.ts</code>) and
|
|
1397
|
+
<code>scripts/teardown-agent-worktree.sh</code> exist precisely to close this gap — see
|
|
1398
|
+
<a href="#harvest-recover--teardown">Harvest, recover & teardown</a>.</p>
|
|
1399
|
+
<h3 id="what-good-build-observability-produces">What good build observability produces</h3>
|
|
1400
|
+
<ul>
|
|
1401
|
+
<li><strong>Decisions captured</strong> the moment they're made (<code>decision_recorded</code>),
|
|
1402
|
+
surviving teardown via harvest.</li>
|
|
1403
|
+
<li><strong>Blockers surfaced</strong> when they linger past a threshold (stall detection).</li>
|
|
1404
|
+
<li><strong>Phase-boundary audits</strong> that run automatically when a planning doc is
|
|
1405
|
+
completed, non-gating so they never block progress.</li>
|
|
1406
|
+
<li><strong>Doc/code drift caught</strong> by the nine-lens audit and routed into code review
|
|
1407
|
+
via the MMR <code>doc-conformance</code> channel.</li>
|
|
1408
|
+
</ul>
|
|
1409
|
+
<p>The system ships <strong>9 durable event types</strong>, <strong>8 adapters</strong> fusing external
|
|
1410
|
+
signals, a <strong>9-lens audit (A–I)</strong>, and <strong>5 active stall signals</strong> (a 6th reserved) on the "Needs
|
|
1411
|
+
Attention" surface.</p>
|
|
1412
|
+
<div class="callout callout-note"><p><strong>Two subsystems, one config file.</strong> Build Observability and the separate
|
|
1413
|
+
<em>knowledge-freshness</em> system both read <code>.scaffold/observability.yaml</code>. This guide
|
|
1414
|
+
documents Build Observability; the shared config keys are reconciled in
|
|
1415
|
+
<a href="#config-reference">Config reference</a>.</p></div>
|
|
1416
|
+
<h2 id="system-map">System map</h2>
|
|
1417
|
+
<p>One write path, one fusion point, two read paths. Agents write events to the
|
|
1418
|
+
append-only ledger; adapters synthesize events from git, GitHub, MMR and
|
|
1419
|
+
pipeline state; the synthesizer fuses them with correlation-id dedup; the engine
|
|
1420
|
+
API drives the audit lenses and the progress timeline; renderers emit terminal,
|
|
1421
|
+
markdown, dashboard and MMR-findings output.</p>
|
|
1422
|
+
<figure class="mermaid"><svg id="my-svg" width="100%" xmlns="http://www.w3.org/2000/svg" class="flowchart" style="max-width: 2427.98px; background-color: transparent;" viewBox="0 0 2427.984375 825.7999877929688" role="graphics-document document">#my-svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#000000;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#my-svg .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#my-svg .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#my-svg .error-icon{fill:#552222;}#my-svg .error-text{fill:#552222;stroke:#552222;}#my-svg .edge-thickness-normal{stroke-width:1px;}#my-svg .edge-thickness-thick{stroke-width:3.5px;}#my-svg .edge-pattern-solid{stroke-dasharray:0;}#my-svg .edge-thickness-invisible{stroke-width:0;fill:none;}#my-svg .edge-pattern-dashed{stroke-dasharray:3;}#my-svg .edge-pattern-dotted{stroke-dasharray:2;}#my-svg .marker{fill:#666;stroke:#666;}#my-svg .marker.cross{stroke:#666;}#my-svg svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#my-svg p{margin:0;}#my-svg .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#000000;}#my-svg .cluster-label text{fill:#333;}#my-svg .cluster-label span{color:#333;}#my-svg .cluster-label span p{background-color:transparent;}#my-svg .label text,#my-svg span{fill:#000000;color:#000000;}#my-svg .node rect,#my-svg .node circle,#my-svg .node ellipse,#my-svg .node polygon,#my-svg .node path{fill:#eee;stroke:#999;stroke-width:1px;}#my-svg .rough-node .label text,#my-svg .node .label text,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-anchor:middle;}#my-svg .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#my-svg .rough-node .label,#my-svg .node .label,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-align:center;}#my-svg .node.clickable{cursor:pointer;}#my-svg .root .anchor path{fill:#666!important;stroke-width:0;stroke:#666;}#my-svg .arrowheadPath{fill:#333333;}#my-svg .edgePath .path{stroke:#666;stroke-width:1px;}#my-svg .flowchart-link{stroke:#666;fill:none;}#my-svg .edgeLabel{background-color:white;text-align:center;}#my-svg .edgeLabel p{background-color:white;}#my-svg .edgeLabel rect{opacity:0.5;background-color:white;fill:white;}#my-svg .labelBkg{background-color:rgba(255, 255, 255, 0.5);}#my-svg .cluster rect{fill:hsl(0, 0%, 98.9215686275%);stroke:#707070;stroke-width:1px;}#my-svg .cluster text{fill:#333;}#my-svg .cluster span{color:#333;}#my-svg div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(-160, 0%, 93.3333333333%);border:1px solid #707070;border-radius:2px;pointer-events:none;z-index:100;}#my-svg .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#000000;}#my-svg rect.text{fill:none;stroke-width:0;}#my-svg .icon-shape,#my-svg .image-shape{background-color:white;text-align:center;}#my-svg .icon-shape p,#my-svg .image-shape p{background-color:white;padding:2px;}#my-svg .icon-shape .label rect,#my-svg .image-shape .label rect{opacity:0.5;background-color:white;fill:white;}#my-svg .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#my-svg .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#my-svg .node .neo-node{stroke:#999;}#my-svg [data-look="neo"].node rect,#my-svg [data-look="neo"].cluster rect,#my-svg [data-look="neo"].node polygon{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node path{stroke:url(#my-svg-gradient);stroke-width:1px;}#my-svg [data-look="neo"].node .outer-path{filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node .neo-line path{stroke:#999;filter:none;}#my-svg [data-look="neo"].node circle{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node circle .state-start{fill:#000000;}#my-svg [data-look="neo"].icon-shape .icon{fill:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].icon-shape .icon-neo path{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}<g><marker id="my-svg_flowchart-v2-pointEnd" class="marker flowchart-v2" viewBox="0 0 10 10" refX="5" refY="5" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-pointStart" class="marker flowchart-v2" viewBox="0 0 10 10" refX="4.5" refY="5" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" orient="auto"><path d="M 0 5 L 10 10 L 10 0 z" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-pointEnd-margin" class="marker flowchart-v2" viewBox="0 0 11.5 14" refX="11.5" refY="7" markerUnits="userSpaceOnUse" markerWidth="10.5" markerHeight="14" orient="auto"><path d="M 0 0 L 11.5 7 L 0 14 z" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-pointStart-margin" class="marker flowchart-v2" viewBox="0 0 11.5 14" refX="1" refY="7" markerUnits="userSpaceOnUse" markerWidth="11.5" markerHeight="14" orient="auto"><polygon points="0,7 11.5,14 11.5,0" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></polygon></marker><marker id="my-svg_flowchart-v2-circleEnd" class="marker flowchart-v2" viewBox="0 0 10 10" refX="11" refY="5" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-circleStart" class="marker flowchart-v2" viewBox="0 0 10 10" refX="-1" refY="5" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-circleEnd-margin" class="marker flowchart-v2" viewBox="0 0 10 10" refY="5" refX="12.25" markerUnits="userSpaceOnUse" markerWidth="14" markerHeight="14" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-circleStart-margin" class="marker flowchart-v2" viewBox="0 0 10 10" refX="-2" refY="5" markerUnits="userSpaceOnUse" markerWidth="14" markerHeight="14" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-crossEnd" class="marker cross flowchart-v2" viewBox="0 0 11 11" refX="12" refY="5.2" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><path d="M 1,1 l 9,9 M 10,1 l -9,9" class="arrowMarkerPath" style="stroke-width: 2; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-crossStart" class="marker cross flowchart-v2" viewBox="0 0 11 11" refX="-1" refY="5.2" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><path d="M 1,1 l 9,9 M 10,1 l -9,9" class="arrowMarkerPath" style="stroke-width: 2; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-crossEnd-margin" class="marker cross flowchart-v2" viewBox="0 0 15 15" refX="17.7" refY="7.5" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto"><path d="M 1,1 L 14,14 M 1,14 L 14,1" class="arrowMarkerPath" style="stroke-width: 2.5;"></path></marker><marker id="my-svg_flowchart-v2-crossStart-margin" class="marker cross flowchart-v2" viewBox="0 0 15 15" refX="-3.5" refY="7.5" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto"><path d="M 1,1 L 14,14 M 1,14 L 14,1" class="arrowMarkerPath" style="stroke-width: 2.5; stroke-dasharray: 1, 0;"></path></marker><g class="root"><g class="clusters"><g class="cluster" id="my-svg-render"><rect style="" x="400.88671875" y="701.1999969482422" width="949.5" height="116.5999984741211"></rect><g class="cluster-label" transform="translate(851.86328125, 701.1999969482422)"><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">render</tspan></tspan></text></g></g></g><g class="cluster" id="my-svg-adapters"><rect style="" x="566.125" y="149.5999984741211" width="1853.859375" height="116.5999984741211"></rect><g class="cluster-label" transform="translate(1461.8515625, 149.5999984741211)"><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">adapters</tspan></tspan></text></g></g></g><g class="cluster" id="my-svg-write"><rect style="" x="8" y="8" width="538.125" height="258.1999969482422"></rect><g class="cluster-label" transform="translate(258.1796875, 8)"><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">write</tspan></tspan></text></g></g></g></g><g class="edgePaths"><path d="M169.445,99.6L169.445,103.767C169.445,107.933,169.445,116.267,169.445,124.6C169.445,132.933,169.445,141.267,186.561,149.956C203.677,158.645,237.909,167.691,255.025,172.213L272.141,176.736" id="my-svg-L_LW_LF_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M418.023,99.6L418.023,103.767C418.023,107.933,418.023,116.267,418.023,124.6C418.023,132.933,418.023,141.267,416.314,148.999C414.605,156.731,411.187,163.862,409.478,167.427L407.769,170.993" id="my-svg-L_HV_LF_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M390.078,241.2L390.078,245.367C390.078,249.533,390.078,257.867,390.078,266.2C390.078,274.533,390.078,282.867,472.673,297.313C555.268,311.759,720.458,332.317,803.053,342.597L885.648,352.876" id="my-svg-L_LF_SY_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M681.617,232.4L681.617,238.033C681.617,243.667,681.617,254.933,681.617,264.733C681.617,274.533,681.617,282.867,715.635,295.145C749.654,307.423,817.69,323.645,851.708,331.756L885.726,339.868" id="my-svg-L_A1_SY_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M891.523,232.4L891.523,238.033C891.523,243.667,891.523,254.933,891.523,264.733C891.523,274.533,891.523,282.867,896.929,290.818C902.334,298.769,913.145,306.337,918.551,310.122L923.956,313.906" id="my-svg-L_A2_SY_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M1108.352,232.4L1108.352,238.033C1108.352,243.667,1108.352,254.933,1108.352,264.733C1108.352,274.533,1108.352,282.867,1102.946,290.818C1097.541,298.769,1086.73,306.337,1081.324,310.122L1075.919,313.906" id="my-svg-L_A3_SY_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M1334.938,232.4L1334.938,238.033C1334.938,243.667,1334.938,254.933,1334.938,264.733C1334.938,274.533,1334.938,282.867,1298.141,295.37C1261.345,307.874,1187.752,324.547,1150.955,332.884L1114.159,341.221" id="my-svg-L_A4_SY_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M1562.32,232.4L1562.32,238.033C1562.32,243.667,1562.32,254.933,1562.32,264.733C1562.32,274.533,1562.32,282.867,1487.637,297.113C1412.954,311.359,1263.588,331.517,1188.905,341.597L1114.222,351.676" id="my-svg-L_A5_SY_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M999.938,418L999.938,422.167C999.938,426.333,999.938,434.667,999.938,442.333C999.938,450,999.938,457,999.938,460.5L999.938,464" id="my-svg-L_SY_API_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M1109.859,519.139L1151.412,525.882C1192.965,532.626,1276.07,546.113,1317.623,556.356C1359.176,566.6,1359.176,573.6,1359.176,577.1L1359.176,580.6" id="my-svg-L_API_LENS_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M1437.91,651.2L1447.761,655.367C1457.613,659.533,1477.316,667.867,1487.168,676.2C1497.02,684.533,1497.02,692.867,1497.02,700.533C1497.02,708.2,1497.02,715.2,1497.02,718.7L1497.02,722.2" id="my-svg-L_LENS_FIX_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M890.016,514.642L828.281,522.135C766.546,529.628,643.076,544.614,581.34,561.824C519.605,579.033,519.605,598.467,519.605,617.9C519.605,637.333,519.605,656.767,519.605,670.65C519.605,684.533,519.605,692.867,519.605,702C519.605,711.133,519.605,721.067,519.605,726.033L519.605,731" id="my-svg-L_API_R1_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M890.016,527.466L867.516,532.821C845.017,538.177,800.018,548.889,777.519,563.961C755.02,579.033,755.02,598.467,755.02,617.9C755.02,637.333,755.02,656.767,755.02,670.65C755.02,684.533,755.02,692.867,755.02,702C755.02,711.133,755.02,721.067,755.02,726.033L755.02,731" id="my-svg-L_API_R2_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M1004.969,534.6L1005.598,538.767C1006.228,542.933,1007.487,551.267,1008.117,565.15C1008.746,579.033,1008.746,598.467,1008.746,617.9C1008.746,637.333,1008.746,656.767,1008.746,670.65C1008.746,684.533,1008.746,692.867,1008.746,702C1008.746,711.133,1008.746,721.067,1008.746,726.033L1008.746,731" id="my-svg-L_API_R3_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M1290.009,651.2L1281.355,655.367C1272.7,659.533,1255.391,667.867,1246.737,676.2C1238.082,684.533,1238.082,692.867,1238.082,702C1238.082,711.133,1238.082,721.067,1238.082,726.033L1238.082,731" id="my-svg-L_LENS_R4_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path></g><g class="edgeLabels"><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g></g><g class="nodes"><g class="node default" id="my-svg-flowchart-LW-0" transform="translate(169.4453125, 66.29999923706055)"><rect class="basic label-container" style="" x="-126.4453125" y="-33.29999923706055" width="252.890625" height="66.5999984741211"></rect><g class="label" style="" transform="translate(0, -18.299999237060547)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">ledger</tspan><tspan class="text-inner-tspan"> writer</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">ledger-writer.ts</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> 4</tspan><tspan class="text-inner-tspan"> KiB</tspan><tspan class="text-inner-tspan"> cap</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-HV-1" transform="translate(418.0234375, 66.29999923706055)"><rect class="basic label-container" style="" x="-72.1328125" y="-33.29999923706055" width="144.265625" height="66.5999984741211"></rect><g class="label" style="" transform="translate(0, -18.299999237060547)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">harvester</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">harvester.ts</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-LF-2" transform="translate(390.078125, 207.89999771118164)"><rect class="basic label-container" style="" x="-114.0703125" y="-33.29999923706055" width="228.140625" height="66.5999984741211"></rect><g class="label" style="" transform="translate(0, -18.299999237060547)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">.scaffold/activity.jsonl</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">append-only</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> redacted</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-A1-3" transform="translate(681.6171875, 207.89999771118164)"><rect class="basic label-container" style="" x="-80.4921875" y="-24.5" width="160.984375" height="49"></rect><g class="label" style="" transform="translate(0, -9.5)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">git</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> priority</tspan><tspan class="text-inner-tspan"> 3</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-A2-4" transform="translate(891.5234375, 207.89999771118164)"><rect class="basic label-container" style="" x="-79.4140625" y="-24.5" width="158.828125" height="49"></rect><g class="label" style="" transform="translate(0, -9.5)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">gh</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> priority</tspan><tspan class="text-inner-tspan"> 2</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-A3-5" transform="translate(1108.3515625, 207.89999771118164)"><rect class="basic label-container" style="" x="-87.4140625" y="-24.5" width="174.828125" height="49"></rect><g class="label" style="" transform="translate(0, -9.5)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">mmr</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> priority</tspan><tspan class="text-inner-tspan"> 1</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-A4-6" transform="translate(1334.9375, 207.89999771118164)"><rect class="basic label-container" style="" x="-89.171875" y="-24.5" width="178.34375" height="49"></rect><g class="label" style="" transform="translate(0, -9.5)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">state</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> priority</tspan><tspan class="text-inner-tspan"> 4</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-A5-7" transform="translate(1562.3203125, 207.89999771118164)"><rect class="basic label-container" style="" x="-88.2109375" y="-24.5" width="176.421875" height="49"></rect><g class="label" style="" transform="translate(0, -9.5)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">tests</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> priority</tspan><tspan class="text-inner-tspan"> 5</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-A6-8" transform="translate(1808.0546875, 207.89999771118164)"><rect class="basic label-container" style="" x="-107.5234375" y="-24.5" width="215.046875" height="49"></rect><g class="label" style="" transform="translate(0, -9.5)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">pipeline_docs</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> probe</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-A7-9" transform="translate(2044.7421875, 207.89999771118164)"><rect class="basic label-container" style="" x="-79.1640625" y="-24.5" width="158.328125" height="49"></rect><g class="label" style="" transform="translate(0, -9.5)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">beads</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> probe</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-A8-10" transform="translate(2279.4453125, 207.89999771118164)"><rect class="basic label-container" style="" x="-105.5390625" y="-24.5" width="211.078125" height="49"></rect><g class="label" style="" transform="translate(0, -9.5)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">audit_history</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> probe</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-SY-11" transform="translate(999.9375, 367.0999984741211)"><rect class="basic label-container" style="" x="-110.3203125" y="-50.900001525878906" width="220.640625" height="101.80000305175781"></rect><g class="label" style="" transform="translate(0, -35.900001525878906)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">synthesizer</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">composeReplay</tspan><tspan class="text-inner-tspan"> ·</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="2.1em"><tspan class="text-inner-tspan">correlation_id</tspan><tspan class="text-inner-tspan"> dedup</tspan><tspan class="text-inner-tspan"> ·</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="3.2em"><tspan class="text-inner-tspan">source</tspan><tspan class="text-inner-tspan"> priority</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-API-12" transform="translate(999.9375, 501.29999923706055)"><rect class="basic label-container" style="" x="-109.921875" y="-33.29999923706055" width="219.84375" height="66.5999984741211"></rect><g class="label" style="" transform="translate(0, -18.299999237060547)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">engine</tspan><tspan class="text-inner-tspan"> API</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">runAudit</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> runProgress</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-LENS-13" transform="translate(1359.17578125, 617.8999977111816)"><rect class="basic label-container" style="" x="-98.4140625" y="-33.29999923706055" width="196.828125" height="66.5999984741211"></rect><g class="label" style="" transform="translate(0, -18.299999237060547)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">checks</tspan><tspan class="text-inner-tspan"> —</tspan><tspan class="text-inner-tspan"> lenses</tspan><tspan class="text-inner-tspan"> A–I</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">registry</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> runner</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-FIX-14" transform="translate(1497.01953125, 759.4999961853027)"><rect class="basic label-container" style="" x="-111.6328125" y="-33.29999923706055" width="223.265625" height="66.5999984741211"></rect><g class="label" style="" transform="translate(0, -18.299999237060547)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">--fix</tspan><tspan class="text-inner-tspan"> loop</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">plan</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> dispatch</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> verify</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-R1-15" transform="translate(519.60546875, 759.4999961853027)"><rect class="basic label-container" style="" x="-83.71875" y="-24.5" width="167.4375" height="49"></rect><g class="label" style="" transform="translate(0, -9.5)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">terminal</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> ANSI</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-R2-16" transform="translate(755.01953125, 759.4999961853027)"><rect class="basic label-container" style="" x="-101.6953125" y="-24.5" width="203.390625" height="49"></rect><g class="label" style="" transform="translate(0, -9.5)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">markdown</tspan><tspan class="text-inner-tspan"> +</tspan><tspan class="text-inner-tspan"> sidecar</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-R3-17" transform="translate(1008.74609375, 759.4999961853027)"><rect class="basic label-container" style="" x="-102.03125" y="-24.5" width="204.0625" height="49"></rect><g class="label" style="" transform="translate(0, -9.5)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">dashboard</tspan><tspan class="text-inner-tspan"> fragment</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-R4-18" transform="translate(1238.08203125, 759.4999961853027)"><rect class="basic label-container" style="" x="-77.3046875" y="-24.5" width="154.609375" height="49"></rect><g class="label" style="" transform="translate(0, -9.5)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">mmr-findings</tspan></tspan></text></g></g></g></g></g></g><defs></defs><defs></defs></svg></figure>
|
|
1423
|
+
<p>The boxes labelled <em>probe</em> (<code>pipeline_docs</code>, <code>beads</code>, <code>audit_history</code>)
|
|
1424
|
+
contribute availability checks — and, for <code>audit_history</code>, trend data — but do
|
|
1425
|
+
not emit events into the replay timeline. The five remaining adapters (<code>git</code>,
|
|
1426
|
+
<code>gh</code>, <code>mmr</code>, <code>state</code>, <code>tests</code>) synthesize replay events that flow into the
|
|
1427
|
+
synthesizer.</p>
|
|
1428
|
+
<h2 id="the-ledger">The ledger</h2>
|
|
1429
|
+
<p>Every durable observation is one JSON object on one line of
|
|
1430
|
+
<code>.scaffold/activity.jsonl</code>. Writes are append-only and lock-guarded so parallel
|
|
1431
|
+
worktrees never corrupt the file; each event is capped at <strong>4 KiB</strong>; and secrets
|
|
1432
|
+
and home-directory paths are scrubbed both when the event is written and again
|
|
1433
|
+
when output is rendered.</p>
|
|
1434
|
+
<h3 id="how-a-write-happens">How a write happens</h3>
|
|
1435
|
+
<ul>
|
|
1436
|
+
<li><strong>Validate</strong> against the per-type payload allow-list
|
|
1437
|
+
(<code>src/observability/engine/event-schemas.ts</code>). Unknown payload keys are dropped
|
|
1438
|
+
(reported in <code>dropped_fields</code>); a bad <code>ts</code> or missing required field rejects
|
|
1439
|
+
the event.</li>
|
|
1440
|
+
<li><strong>Redact</strong> the payload (<code>src/observability/engine/redact.ts</code>) — see below.</li>
|
|
1441
|
+
<li><strong>Size-check</strong>: <code>Buffer.byteLength(line, 'utf8')</code> must be ≤ 4096, else the
|
|
1442
|
+
write throws (<span class="fp" data-path="src/observability/engine/ledger-writer.ts:10">src/observability/engine/ledger-writer.ts:10</span>,
|
|
1443
|
+
<span class="fp" data-path="src/observability/engine/ledger-writer.ts:58">src/observability/engine/ledger-writer.ts:58</span>).</li>
|
|
1444
|
+
<li><strong>Append</strong> under a <code>proper-lockfile</code> lock (10 retries, exponential backoff) so
|
|
1445
|
+
concurrent agents serialize cleanly.</li>
|
|
1446
|
+
<li><strong>Link (fail-soft)</strong>: a <code>task_claimed</code> event with a <code>task_id</code> also links the
|
|
1447
|
+
task into Beads via <code>bd</code> (<code>beadsAdapter.claimWithEvent</code>); any Beads error is
|
|
1448
|
+
swallowed — the ledger write already succeeded.</li>
|
|
1449
|
+
</ul>
|
|
1450
|
+
<h3 id="the-nine-event-types">The nine event types</h3>
|
|
1451
|
+
<p>Each event carries a common envelope — <code>event_id</code> (ULID), <code>worktree_id</code>,
|
|
1452
|
+
<code>actor_label</code>, <code>branch</code>, <code>task_id</code> (string <em>or null</em>), <code>type</code>, <code>ts</code> (ISO-8601
|
|
1453
|
+
UTC) — plus a type-specific <code>payload</code>. The CLI verb is
|
|
1454
|
+
<code>scaffold observe event <type> …</code>.</p>
|
|
1455
|
+
<div class="filter-table"><input type="text" class="filter-input" placeholder="Filter…" aria-label="Filter table rows" disabled>
|
|
1456
|
+
|
|
1457
|
+
|
|
1458
|
+
|
|
1459
|
+
|
|
1460
|
+
|
|
1461
|
+
|
|
1462
|
+
|
|
1463
|
+
|
|
1464
|
+
|
|
1465
|
+
|
|
1466
|
+
|
|
1467
|
+
|
|
1468
|
+
|
|
1469
|
+
|
|
1470
|
+
|
|
1471
|
+
|
|
1472
|
+
|
|
1473
|
+
|
|
1474
|
+
|
|
1475
|
+
|
|
1476
|
+
|
|
1477
|
+
|
|
1478
|
+
|
|
1479
|
+
|
|
1480
|
+
|
|
1481
|
+
|
|
1482
|
+
|
|
1483
|
+
|
|
1484
|
+
|
|
1485
|
+
|
|
1486
|
+
|
|
1487
|
+
|
|
1488
|
+
|
|
1489
|
+
|
|
1490
|
+
|
|
1491
|
+
|
|
1492
|
+
|
|
1493
|
+
|
|
1494
|
+
|
|
1495
|
+
|
|
1496
|
+
|
|
1497
|
+
|
|
1498
|
+
|
|
1499
|
+
|
|
1500
|
+
|
|
1501
|
+
|
|
1502
|
+
|
|
1503
|
+
|
|
1504
|
+
|
|
1505
|
+
|
|
1506
|
+
|
|
1507
|
+
|
|
1508
|
+
|
|
1509
|
+
|
|
1510
|
+
<table><thead><tr><th>event_type</th><th>payload fields</th><th>key constraints</th></tr></thead><tbody><tr><td><code>task_claimed</code></td><td><code>task_title</code>*, <code>story_id</code>, <code>wave</code>, <code>unplanned</code></td><td>if <code>task_id</code> is null, <code>unplanned</code> must be true</td></tr><tr><td><code>task_completed</code></td><td><code>outcome</code>*, <code>pr_number</code>, <code>commit_sha</code></td><td>outcome ∈ {pr_submitted, dropped, superseded}; <code>pr_number</code> required if pr_submitted</td></tr><tr><td><code>decision_recorded</code></td><td><code>key</code><em>, <code>summary</code></em>, <code>affects</code>* (string[]), <code>links</code></td><td>summary ≤ 500 chars; consumed by Lens G</td></tr><tr><td><code>blocker_hit</code></td><td><code>kind</code><em>, <code>summary</code></em></td><td>kind ∈ {dependency, ambiguity, external, environment}; summary ≤ 500 chars</td></tr><tr><td><code>blocker_resolved</code></td><td><code>summary</code><em>, <code>references</code></em> (string[])</td><td>closes a prior blocker_hit</td></tr><tr><td><code>pr_opened</code></td><td><code>pr_number</code>*</td><td>positive integer</td></tr><tr><td><code>progress_heartbeat</code></td><td><code>note</code>*</td><td>note ≤ 200 chars; resets task_stale clock</td></tr><tr><td><code>finding_acknowledged</code></td><td><code>finding_id</code><em>, <code>status</code></em>, <code>note</code></td><td>task_id must be null; status ∈ {acknowledged, open}; written by <code>observe ack</code></td></tr><tr><td><code>knowledge_gap_signal</code></td><td><code>topic</code><em>, <code>source</code></em>, <code>project_id</code>*, <code>step_name</code>, <code>agent_excerpt</code></td><td>topic kebab-case ≤ 80 chars; consumed by Lens I</td></tr></tbody></table></div>
|
|
1511
|
+
<p><code>*</code> marks required fields. Allow-lists live in <code>EVENT_PAYLOAD_KEYS</code> at
|
|
1512
|
+
<span class="fp" data-path="src/observability/engine/event-schemas.ts:3-13">src/observability/engine/event-schemas.ts:3-13</span>.</p>
|
|
1513
|
+
<div class="callout callout-warning"><p><strong>Naming note.</strong> The PR-opened event is <code>pr_opened</code> (past tense) in code, not
|
|
1514
|
+
<code>pr_open</code> as the CLAUDE.md prose abbreviates it. The ledger never emits
|
|
1515
|
+
<code>pr_open</code>.</p></div>
|
|
1516
|
+
<h3 id="building-a-scaffold-observe-event-command">Building a <code>scaffold observe event</code> command</h3>
|
|
1517
|
+
<p><code>--branch</code> is required; <code>--task-id</code> is optional (it correlates the event to a
|
|
1518
|
+
claimed task) but must be <em>omitted</em> for <code>finding_acknowledged</code> (whose <code>task_id</code>
|
|
1519
|
+
must be null), and a <code>task_claimed</code> without one must pass <code>--unplanned true</code>.
|
|
1520
|
+
Payload keys are passed as <code>--kebab-case</code> flags, snake-cased before validation;
|
|
1521
|
+
unknown keys are dropped.</p>
|
|
1522
|
+
<pre><code class="language-bash">scaffold observe event task_claimed --branch <branch> --task-id <id> \
|
|
1523
|
+
--task-title "<title>" [--story-id <id>] [--wave <n>] [--unplanned true]
|
|
1524
|
+
scaffold observe event task_completed --branch <branch> --task-id <id> \
|
|
1525
|
+
--outcome pr_submitted --pr-number <n> [--commit-sha <sha>]
|
|
1526
|
+
scaffold observe event decision_recorded --branch <branch> --task-id <id> \
|
|
1527
|
+
--key <key> --summary "<text>" --affects "src/**,docs/**" [--links "ADR-1,ADR-2"]
|
|
1528
|
+
scaffold observe event blocker_hit --branch <branch> --task-id <id> \
|
|
1529
|
+
--kind dependency --summary "<text>"
|
|
1530
|
+
scaffold observe event blocker_resolved --branch <branch> --task-id <id> \
|
|
1531
|
+
--summary "<text>" --references "ref1,ref2"
|
|
1532
|
+
scaffold observe event pr_opened --branch <branch> --task-id <id> --pr-number <n>
|
|
1533
|
+
scaffold observe event progress_heartbeat --branch <branch> --task-id <id> --note "<text>"
|
|
1534
|
+
scaffold observe event finding_acknowledged --branch <branch> \
|
|
1535
|
+
--finding-id <id> --status acknowledged [--note "<text>"]
|
|
1536
|
+
scaffold observe event knowledge_gap_signal --branch <branch> \
|
|
1537
|
+
--topic <kebab-slug> --source agent_search --project-id <sha256> \
|
|
1538
|
+
[--step-name <name>] [--agent-excerpt "<text>"]
|
|
1539
|
+
</code></pre>
|
|
1540
|
+
<p><code>finding_acknowledged</code> is normally written by <code>scaffold observe ack</code>, not by
|
|
1541
|
+
hand.</p>
|
|
1542
|
+
<div class="callout callout-note"><p><strong>Value coercion</strong> (<code>src/cli/commands/observe.ts</code>): <code>--pr-number</code> is parsed
|
|
1543
|
+
numeric (a non-number is dropped); <code>--unplanned</code> is boolean (<code>true</code> ⇒ true,
|
|
1544
|
+
anything else ⇒ false); <code>--affects</code>, <code>--links</code>, <code>--references</code> are comma-split
|
|
1545
|
+
into arrays; everything else stays a string. Exit codes: <code>0</code> written · <code>2</code>
|
|
1546
|
+
validation failed / payload > 4 KiB · <code>3</code> other error.</p></div>
|
|
1547
|
+
<h3 id="redaction-write-time-and-render-time">Redaction — write time and render time</h3>
|
|
1548
|
+
<p>Redaction runs twice. <strong>Write-time</strong> redaction (recursive over the payload tree)
|
|
1549
|
+
scrubs the event before it lands on disk; <strong>render-time</strong> redaction
|
|
1550
|
+
(<code>redactEngineOutput</code> / <code>redactRendered</code>) scrubs string values again before any
|
|
1551
|
+
report is shown, catching anything synthesized after the fact.</p>
|
|
1552
|
+
<p>Order matters: a bare <code>ghp_…</code> matches the GitHub-token pattern, but inside a
|
|
1553
|
+
<code>token=…</code> pair the key/value rule wins first — so <code>token=ghp_…</code> redacts to
|
|
1554
|
+
<code>[REDACTED:kv-secret]</code>, not <code>[REDACTED:github-token]</code> (leftmost-match
|
|
1555
|
+
alternation, <span class="fp" data-path="src/observability/engine/redact.ts:16">src/observability/engine/redact.ts:16</span>).</p>
|
|
1556
|
+
|
|
1557
|
+
|
|
1558
|
+
|
|
1559
|
+
|
|
1560
|
+
|
|
1561
|
+
|
|
1562
|
+
|
|
1563
|
+
|
|
1564
|
+
|
|
1565
|
+
|
|
1566
|
+
|
|
1567
|
+
|
|
1568
|
+
|
|
1569
|
+
|
|
1570
|
+
|
|
1571
|
+
|
|
1572
|
+
|
|
1573
|
+
|
|
1574
|
+
|
|
1575
|
+
|
|
1576
|
+
|
|
1577
|
+
|
|
1578
|
+
|
|
1579
|
+
|
|
1580
|
+
|
|
1581
|
+
|
|
1582
|
+
|
|
1583
|
+
|
|
1584
|
+
|
|
1585
|
+
|
|
1586
|
+
|
|
1587
|
+
|
|
1588
|
+
|
|
1589
|
+
|
|
1590
|
+
|
|
1591
|
+
<table><thead><tr><th>pattern</th><th>matches</th><th>replacement</th></tr></thead><tbody><tr><td>AWS key</td><td><code>AKIA[0-9A-Z]{16}</code></td><td><code>[REDACTED:aws-key]</code></td></tr><tr><td>GitHub token</td><td><code>gh[pousr]_[A-Za-z0-9]{36,}</code></td><td><code>[REDACTED:github-token]</code></td></tr><tr><td>key/value secret</td><td>key matches <code>secret|token|password|api[_-]?key</code></td><td><code>[REDACTED:kv-secret]</code> (key + separator preserved)</td></tr><tr><td>sensitive object key</td><td>object key matches the same pattern</td><td>all descendant primitive values masked</td></tr><tr><td>home path</td><td><code>/Users/<name></code>, <code>/home/<name></code>, <code>C:\Users\<name></code></td><td><code>~</code> (Windows keeps the drive: <code>C:\~</code>)</td></tr></tbody></table>
|
|
1592
|
+
<p>A redacted <code>decision_recorded</code> event on disk (one line, shown pretty-printed):</p>
|
|
1593
|
+
<pre><code class="language-json">{
|
|
1594
|
+
"event_id": "01H5ZABCDEFGHJKMNPQRSTVWX",
|
|
1595
|
+
"worktree_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
|
|
1596
|
+
"actor_label": "agent-alice",
|
|
1597
|
+
"branch": "alice-feat/cache",
|
|
1598
|
+
"task_id": "T-014",
|
|
1599
|
+
"type": "decision_recorded",
|
|
1600
|
+
"ts": "2026-05-04T12:00:00Z",
|
|
1601
|
+
"payload": {
|
|
1602
|
+
"key": "cache-backend",
|
|
1603
|
+
"summary": "Switched to Redis; token=[REDACTED:kv-secret]",
|
|
1604
|
+
"affects": ["~/repo/src/cache/**"],
|
|
1605
|
+
"links": ["ADR-021"]
|
|
1606
|
+
}
|
|
1607
|
+
}
|
|
1608
|
+
</code></pre>
|
|
1609
|
+
<h3 id="worktree-identity">Worktree identity</h3>
|
|
1610
|
+
<p>Each worktree gets a stable identity on first write — <code>.scaffold/identity.json</code>
|
|
1611
|
+
holds <code>worktree_id</code> (a UUID), <code>worktree_label</code> (derived from the directory name,
|
|
1612
|
+
or <code>primary</code>), and <code>created_at</code> (<code>src/observability/engine/identity.ts</code>). The id
|
|
1613
|
+
is what lets the harvester tell one worktree's events from another's, and what
|
|
1614
|
+
stamps every event's <code>worktree_id</code>.</p>
|
|
1615
|
+
<h2 id="adapters">Adapters</h2>
|
|
1616
|
+
<p>The ledger only holds what agents <em>chose</em> to record. Adapters fill in the rest by
|
|
1617
|
+
synthesizing events from the surrounding tools — commits, PRs, MMR jobs, pipeline
|
|
1618
|
+
state, test runs. There are eight adapters (<code>AdapterId</code> at
|
|
1619
|
+
<span class="fp" data-path="src/observability/engine/types.ts:69">src/observability/engine/types.ts:69</span>), but only five emit events into the
|
|
1620
|
+
timeline; the other three are availability probes / trend helpers.</p>
|
|
1621
|
+
<div class="callout callout-note"><p><strong>Five emit, three probe.</strong> <code>git</code>, <code>gh</code>, <code>mmr</code>, <code>state</code>, <code>tests</code> each implement
|
|
1622
|
+
<code>replayEvents()</code> and appear in the source-priority chain. <code>pipeline_docs</code>
|
|
1623
|
+
(probes 9 planning-doc roles; 5 of them are the canonical-required set that gates
|
|
1624
|
+
available vs degraded), <code>beads</code> (task-tracker linkage), and <code>audit_history</code>
|
|
1625
|
+
(reads <code>docs/audits/*.json</code> for trends + lens-skip streaks) do <em>not</em> emit replay
|
|
1626
|
+
events.</p></div>
|
|
1627
|
+
|
|
1628
|
+
|
|
1629
|
+
|
|
1630
|
+
|
|
1631
|
+
|
|
1632
|
+
|
|
1633
|
+
|
|
1634
|
+
|
|
1635
|
+
|
|
1636
|
+
|
|
1637
|
+
|
|
1638
|
+
|
|
1639
|
+
|
|
1640
|
+
|
|
1641
|
+
|
|
1642
|
+
|
|
1643
|
+
|
|
1644
|
+
|
|
1645
|
+
|
|
1646
|
+
|
|
1647
|
+
|
|
1648
|
+
|
|
1649
|
+
|
|
1650
|
+
|
|
1651
|
+
|
|
1652
|
+
|
|
1653
|
+
|
|
1654
|
+
|
|
1655
|
+
|
|
1656
|
+
|
|
1657
|
+
|
|
1658
|
+
|
|
1659
|
+
|
|
1660
|
+
|
|
1661
|
+
|
|
1662
|
+
|
|
1663
|
+
|
|
1664
|
+
|
|
1665
|
+
|
|
1666
|
+
|
|
1667
|
+
|
|
1668
|
+
|
|
1669
|
+
|
|
1670
|
+
|
|
1671
|
+
|
|
1672
|
+
|
|
1673
|
+
|
|
1674
|
+
|
|
1675
|
+
|
|
1676
|
+
|
|
1677
|
+
|
|
1678
|
+
|
|
1679
|
+
|
|
1680
|
+
|
|
1681
|
+
|
|
1682
|
+
|
|
1683
|
+
|
|
1684
|
+
|
|
1685
|
+
|
|
1686
|
+
<table><thead><tr><th>adapter</th><th>source of truth</th><th>emits</th><th>correlation_id / dedup</th></tr></thead><tbody><tr><td><code>git</code></td><td><code>git log</code>, <code>git worktree list</code> (30 s timeout)</td><td><code>commit</code></td><td>none (<code>null</code>); per-SHA seen-set within the window</td></tr><tr><td><code>gh</code></td><td><code>gh pr list --state {open,merged,closed}</code> (needs auth)</td><td><code>pr_opened</code>, <code>pr_merged</code>, <code>pr_closed</code></td><td><code>pr:<n>:<state></code> — dedups against the ledger's own PR events</td></tr><tr><td><code>mmr</code></td><td><code>.mmr/jobs/*/result.json</code> (replay keyed on each job's <code>completed_at</code>)</td><td><code>job_completed</code></td><td>none</td></tr><tr><td><code>state</code></td><td><code>.scaffold/state.json</code> + <code>services/*/state.json</code></td><td><code>step_completed</code>, <code>step_in_progress</code></td><td>none; per-step timestamp, mtime fallback</td></tr><tr><td><code>tests</code></td><td><code>.scaffold/last-test-run.json</code></td><td><code>test_run_completed</code>, <code>test_run_failed</code></td><td>none</td></tr><tr><td><code>pipeline_docs</code></td><td>candidate <code>docs/*.md</code> artifact paths</td><td>— (probe: available / degraded / unavailable)</td><td>n/a</td></tr><tr><td><code>beads</code></td><td><code>.beads/</code> + <code>bd</code> CLI (≥ v1.0.0)</td><td>— (task claim ↔ event-id linkage)</td><td>n/a</td></tr><tr><td><code>audit_history</code></td><td><code>docs/audits/*.json</code> (≤ 100 scanned)</td><td>— (trends + <code>lensSkippedStreaks</code>)</td><td>n/a</td></tr></tbody></table>
|
|
1687
|
+
<h3 id="source-priority">Source priority</h3>
|
|
1688
|
+
<p>When two events describe the same thing (same <code>correlation_id</code>), the synthesizer
|
|
1689
|
+
keeps the one from the most authoritative source. The order is fixed in
|
|
1690
|
+
<code>SOURCE_PRIORITY</code> at <span class="fp" data-path="src/observability/engine/synthesizer.ts:254">src/observability/engine/synthesizer.ts:254</span> — lower
|
|
1691
|
+
number wins, ties broken by earliest <code>ts</code>:</p>
|
|
1692
|
+
|
|
1693
|
+
|
|
1694
|
+
|
|
1695
|
+
|
|
1696
|
+
|
|
1697
|
+
|
|
1698
|
+
|
|
1699
|
+
|
|
1700
|
+
|
|
1701
|
+
|
|
1702
|
+
|
|
1703
|
+
|
|
1704
|
+
|
|
1705
|
+
|
|
1706
|
+
|
|
1707
|
+
|
|
1708
|
+
|
|
1709
|
+
|
|
1710
|
+
|
|
1711
|
+
|
|
1712
|
+
|
|
1713
|
+
|
|
1714
|
+
|
|
1715
|
+
|
|
1716
|
+
|
|
1717
|
+
|
|
1718
|
+
|
|
1719
|
+
|
|
1720
|
+
|
|
1721
|
+
|
|
1722
|
+
|
|
1723
|
+
|
|
1724
|
+
|
|
1725
|
+
|
|
1726
|
+
|
|
1727
|
+
|
|
1728
|
+
|
|
1729
|
+
|
|
1730
|
+
|
|
1731
|
+
|
|
1732
|
+
<table><thead><tr><th>rank</th><th>source</th><th>why it wins</th></tr></thead><tbody><tr><td><code>0</code></td><td><code>ledger</code></td><td>the agent said so — first-party intent</td></tr><tr><td><code>1</code></td><td><code>mmr</code></td><td>authoritative build verdict</td></tr><tr><td><code>2</code></td><td><code>gh</code></td><td>GitHub PR state of record</td></tr><tr><td><code>3</code></td><td><code>git</code></td><td>local commit history</td></tr><tr><td><code>4</code></td><td><code>state</code></td><td>pipeline step status</td></tr><tr><td><code>5</code></td><td><code>tests</code></td><td>cached test run</td></tr></tbody></table>
|
|
1733
|
+
<p>The three probe-only adapters are intentionally absent from this table — they
|
|
1734
|
+
never produce a replay event to dedup.</p>
|
|
1735
|
+
<h2 id="the-nine-lens-audit">The nine-lens audit</h2>
|
|
1736
|
+
<p>The audit reads the planning docs (PRD, stories, tech-stack, standards, design
|
|
1737
|
+
system, plan, playbook) into a document graph, then runs a set of independent
|
|
1738
|
+
<em>lenses</em> over the graph, the code, the ledger and adapter data. The design spec
|
|
1739
|
+
calls it the "eight-lens audit" (A–H); a ninth lens — <code>I-knowledge-gaps</code> —
|
|
1740
|
+
joined the suite after v3.26.0.</p>
|
|
1741
|
+
<div class="callout callout-note"><p><strong>8 in the spec, 9 in the code.</strong>
|
|
1742
|
+
<code>docs/superpowers/specs/2026-04-30-build-observability-design.md</code> titles §3 "The
|
|
1743
|
+
Eight Audit Lenses" and its <code>LENS_REGISTRY</code> stops at H. The shipped
|
|
1744
|
+
<span class="fp" data-path="src/observability/engine/checks/registry.ts:44">src/observability/engine/checks/registry.ts:44</span> adds <code>I-knowledge-gaps</code>.
|
|
1745
|
+
Treat Lens I as the ninth lens that joined the suite — documented here as a
|
|
1746
|
+
first-class member.</p></div>
|
|
1747
|
+
<h3 id="scope-order-and-skips">Scope, order and skips</h3>
|
|
1748
|
+
<ul>
|
|
1749
|
+
<li><strong>Scope → lenses</strong> (<span class="fp" data-path="src/observability/engine/api.ts:72">src/observability/engine/api.ts:72</span>): <code>--scope code</code>
|
|
1750
|
+
runs <strong>A–G</strong>; <code>--scope docs</code> runs <strong>H, I</strong>; <code>--scope all</code> runs all nine. An
|
|
1751
|
+
explicit <code>--lens <id></code> overrides the scope selection.</li>
|
|
1752
|
+
<li><strong>Registry order</strong>: A → B → C → D → E → F → G → H → I. <code>G-decisions</code> declares
|
|
1753
|
+
<code>depends_on: ['D-stack']</code> so it runs after D and can consume D's
|
|
1754
|
+
unsanctioned-dependency findings.</li>
|
|
1755
|
+
<li><strong>Missing adapter → skip</strong>: if a lens's <em>required</em> adapters are unavailable it
|
|
1756
|
+
is skipped and emits a <span class="sev sev-p3">P3</span> finding with
|
|
1757
|
+
<code>evidence.kind = lens_skipped</code>. Skipped lenses (not blocking findings) are what
|
|
1758
|
+
turn a <code>pass</code> into a <code>degraded-pass</code>.</li>
|
|
1759
|
+
</ul>
|
|
1760
|
+
<h3 id="what-feeds-the-doc-graph">What feeds the doc-graph</h3>
|
|
1761
|
+
<p>Before any lens runs, the planning docs and the working tree are parsed into a
|
|
1762
|
+
single graph (<code>src/observability/engine/doc-graph/index.ts</code>). Every lens's
|
|
1763
|
+
"Reads:" line refers to nodes and edges built here:</p>
|
|
1764
|
+
|
|
1765
|
+
|
|
1766
|
+
|
|
1767
|
+
|
|
1768
|
+
|
|
1769
|
+
|
|
1770
|
+
|
|
1771
|
+
|
|
1772
|
+
|
|
1773
|
+
|
|
1774
|
+
|
|
1775
|
+
|
|
1776
|
+
|
|
1777
|
+
|
|
1778
|
+
|
|
1779
|
+
|
|
1780
|
+
|
|
1781
|
+
|
|
1782
|
+
|
|
1783
|
+
|
|
1784
|
+
|
|
1785
|
+
|
|
1786
|
+
|
|
1787
|
+
|
|
1788
|
+
|
|
1789
|
+
|
|
1790
|
+
|
|
1791
|
+
|
|
1792
|
+
|
|
1793
|
+
|
|
1794
|
+
|
|
1795
|
+
|
|
1796
|
+
|
|
1797
|
+
|
|
1798
|
+
|
|
1799
|
+
|
|
1800
|
+
|
|
1801
|
+
|
|
1802
|
+
|
|
1803
|
+
|
|
1804
|
+
|
|
1805
|
+
|
|
1806
|
+
|
|
1807
|
+
|
|
1808
|
+
|
|
1809
|
+
|
|
1810
|
+
|
|
1811
|
+
|
|
1812
|
+
|
|
1813
|
+
|
|
1814
|
+
|
|
1815
|
+
|
|
1816
|
+
|
|
1817
|
+
|
|
1818
|
+
|
|
1819
|
+
|
|
1820
|
+
|
|
1821
|
+
|
|
1822
|
+
|
|
1823
|
+
|
|
1824
|
+
<table><thead><tr><th>source</th><th>parser / detector</th><th>graph nodes & edges</th></tr></thead><tbody><tr><td>PRD</td><td><code>parseFeatures</code></td><td><code>features</code> (with priority)</td></tr><tr><td>user-stories</td><td><code>parseStories</code></td><td><code>stories</code>, <code>acceptance_criteria</code>, <code>feature_to_story</code></td></tr><tr><td>tech-stack</td><td><code>parseSanctionedComponents</code></td><td><code>components</code> (with <code>layer</code>)</td></tr><tr><td>coding-standards + tdd-standards</td><td><code>parseRules</code></td><td><code>rules</code></td></tr><tr><td>design-system</td><td><code>parseDesignTokens</code></td><td><code>tokens</code> (priority, category)</td></tr><tr><td>implementation-plan</td><td><code>parsePlanTasks</code></td><td><code>plan_tasks</code>, <code>story_to_plan_task</code></td></tr><tr><td>implementation-playbook</td><td><code>parsePlaybookTasks</code></td><td><code>playbook_tasks</code>, <code>playbook_task_to_story</code></td></tr><tr><td>decision docs (<code>decisions.jsonl</code>, <code>docs/decisions/*.md</code>)</td><td><code>parseDecisions</code></td><td><code>decisions</code></td></tr><tr><td>working tree</td><td><code>discoverTests</code>, <code>discoverFiles</code></td><td><code>tests</code> (with <code>last_status</code>), <code>files</code>, <code>ac_to_test</code></td></tr><tr><td>source files</td><td><code>detectCss/JsxTokenUses</code>, <code>detectComponentUses</code></td><td><code>file_to_token_use</code>, <code>file_to_component_use</code></td></tr></tbody></table>
|
|
1825
|
+
<h3 id="all-nine-at-a-glance">All nine at a glance</h3>
|
|
1826
|
+
<div class="filter-table"><input type="text" class="filter-input" placeholder="Filter…" aria-label="Filter table rows" disabled>
|
|
1827
|
+
|
|
1828
|
+
|
|
1829
|
+
|
|
1830
|
+
|
|
1831
|
+
|
|
1832
|
+
|
|
1833
|
+
|
|
1834
|
+
|
|
1835
|
+
|
|
1836
|
+
|
|
1837
|
+
|
|
1838
|
+
|
|
1839
|
+
|
|
1840
|
+
|
|
1841
|
+
|
|
1842
|
+
|
|
1843
|
+
|
|
1844
|
+
|
|
1845
|
+
|
|
1846
|
+
|
|
1847
|
+
|
|
1848
|
+
|
|
1849
|
+
|
|
1850
|
+
|
|
1851
|
+
|
|
1852
|
+
|
|
1853
|
+
|
|
1854
|
+
|
|
1855
|
+
|
|
1856
|
+
|
|
1857
|
+
|
|
1858
|
+
|
|
1859
|
+
|
|
1860
|
+
|
|
1861
|
+
|
|
1862
|
+
|
|
1863
|
+
|
|
1864
|
+
|
|
1865
|
+
|
|
1866
|
+
|
|
1867
|
+
|
|
1868
|
+
|
|
1869
|
+
|
|
1870
|
+
|
|
1871
|
+
|
|
1872
|
+
|
|
1873
|
+
|
|
1874
|
+
|
|
1875
|
+
|
|
1876
|
+
|
|
1877
|
+
|
|
1878
|
+
|
|
1879
|
+
|
|
1880
|
+
|
|
1881
|
+
|
|
1882
|
+
|
|
1883
|
+
|
|
1884
|
+
|
|
1885
|
+
|
|
1886
|
+
|
|
1887
|
+
|
|
1888
|
+
|
|
1889
|
+
|
|
1890
|
+
|
|
1891
|
+
|
|
1892
|
+
|
|
1893
|
+
|
|
1894
|
+
|
|
1895
|
+
|
|
1896
|
+
|
|
1897
|
+
|
|
1898
|
+
|
|
1899
|
+
|
|
1900
|
+
|
|
1901
|
+
<table><thead><tr><th>lens</th><th>question</th><th>scope</th><th>severities</th><th>ships in</th></tr></thead><tbody><tr><td><code>A-tdd</code></td><td>Are tests being skipped?</td><td>code</td><td>P0 P1</td><td>#331</td></tr><tr><td><code>B-ac-coverage</code></td><td>Is every AC covered by a passing test?</td><td>code</td><td>P0 P1</td><td>#331</td></tr><tr><td><code>C-standards</code></td><td>Are coding standards being violated?</td><td>code</td><td>P0–P3</td><td>#332</td></tr><tr><td><code>D-stack</code></td><td>Unsanctioned deps / out-of-layer use?</td><td>code</td><td>P0 P1</td><td>#332</td></tr><tr><td><code>E-design</code></td><td>Ad-hoc values bypassing design tokens?</td><td>code</td><td>P0 P1</td><td>#332</td></tr><tr><td><code>F-scope</code></td><td>High-priority work without a story/plan?</td><td>code</td><td>P0 P1 P2</td><td>#332</td></tr><tr><td><code>G-decisions</code></td><td>Decisions made but not documented?</td><td>code</td><td>P0 P1 P2</td><td>#332</td></tr><tr><td><code>H-cross-doc</code></td><td>Are the docs internally consistent?</td><td>docs</td><td>P0 P1 P2</td><td>#331 · #336</td></tr><tr><td><code>I-knowledge-gaps</code></td><td>Repeated needs with no KB entry?</td><td>docs</td><td>P1 P2</td><td>#397 · #406</td></tr></tbody></table></div>
|
|
1902
|
+
<h3 id="lens-by-lens">Lens by lens</h3>
|
|
1903
|
+
<p><strong>A-tdd — TDD violations</strong> (<code>src/observability/checks/lens-a-tdd.ts</code>). <em>Are there
|
|
1904
|
+
skipped tests?</em> <strong>Reads:</strong> the doc-graph's discovered tests (with <code>last_status</code>),
|
|
1905
|
+
ACs, stories, and <code>ac_to_test</code> edges. <strong>Tunes:</strong> none. <strong>Severity:</strong>
|
|
1906
|
+
<span class="sev sev-p0">P0</span> skipped test on a must-priority story; <span class="sev sev-p1">P1</span>
|
|
1907
|
+
otherwise.</p>
|
|
1908
|
+
<p><strong>B-ac-coverage — AC completion</strong>
|
|
1909
|
+
(<code>src/observability/checks/lens-b-ac-coverage.ts</code>). <em>Is every acceptance
|
|
1910
|
+
criterion covered by a passing test?</em> <strong>Reads:</strong> ACs, tests, <code>ac_to_test</code> edges;
|
|
1911
|
+
optional <code>tests</code> adapter for live status. <strong>Tunes:</strong> none. <strong>Severity:</strong>
|
|
1912
|
+
<span class="sev sev-p0">P0</span> AC's test is failing; <span class="sev sev-p1">P1</span> AC has no test edge
|
|
1913
|
+
or unknown status.</p>
|
|
1914
|
+
<p><strong>C-standards — coding-standards drift</strong>
|
|
1915
|
+
(<code>src/observability/checks/lens-c-standards.ts</code>). <em>Are coding standards being
|
|
1916
|
+
violated across files?</em> <strong>Reads:</strong> graph <code>rules</code> + <code>files</code>. <strong>Tunes:</strong>
|
|
1917
|
+
<code>lenses.C-standards.rule_overrides</code> (per-rule severity), <code>escalation_threshold</code>
|
|
1918
|
+
(default 5 — more than N violations of a rule escalates to P1).
|
|
1919
|
+
(<code>enforce_via_linter</code> is accepted in config but not read by the lens.)
|
|
1920
|
+
<strong>Severity:</strong> rule-specific <span class="sev sev-p0">P0</span>–<span class="sev sev-p3">P3</span>.</p>
|
|
1921
|
+
<p><strong>D-stack — tech-stack drift</strong>
|
|
1922
|
+
(<code>src/observability/checks/lens-d-stack.ts</code>). <em>Unsanctioned dependencies, or
|
|
1923
|
+
components used outside their layer?</em> <strong>Reads:</strong> <code>file_to_component_use</code> edges,
|
|
1924
|
+
components (with <code>layer</code>), and <code>decision_recorded</code> ledger events (which can
|
|
1925
|
+
sanction a dependency). <strong>Tunes:</strong> <code>lenses.D-stack.path_to_layer</code> (default 7
|
|
1926
|
+
glob→layer mappings). <strong>Severity:</strong> <span class="sev sev-p0">P0</span> unsanctioned dependency;
|
|
1927
|
+
<span class="sev sev-p1">P1</span> out-of-layer use.</p>
|
|
1928
|
+
<p><strong>E-design — design-system drift</strong>
|
|
1929
|
+
(<code>src/observability/checks/lens-e-design.ts</code>). <em>Are ad-hoc design values
|
|
1930
|
+
bypassing tokens?</em> <strong>Reads:</strong> <code>file_to_token_use</code> edges, tokens (with priority +
|
|
1931
|
+
category). <strong>Tunes:</strong> <code>lenses.E-design.ad_hoc_token_threshold</code> (default 3),
|
|
1932
|
+
<code>ui_glob</code> (default <code>src/components/**/*.tsx</code>, consumed by the doc-graph builder).
|
|
1933
|
+
<strong>Severity:</strong> <span class="sev sev-p1">P1</span> ad-hoc count over threshold; <span class="sev sev-p0">P0</span>
|
|
1934
|
+
must-priority token category bypassed.</p>
|
|
1935
|
+
<p><strong>F-scope — missing scope</strong> (<code>src/observability/checks/lens-f-scope.ts</code>). <em>Is
|
|
1936
|
+
high-priority work missing stories/plans, or are planned stories untouched?</em>
|
|
1937
|
+
<strong>Reads:</strong> features, stories, plan-tasks and their edges; <code>task_claimed</code> ledger
|
|
1938
|
+
events; optional <code>state</code> adapter. <strong>Tunes:</strong>
|
|
1939
|
+
<code>lenses.F-scope.untouched_story_grace_hours</code> (default 168 = 7 days). <strong>Severity:</strong>
|
|
1940
|
+
<span class="sev sev-p0">P0</span> must-feature without story/plan; <span class="sev sev-p1">P1</span>
|
|
1941
|
+
should-feature; <span class="sev sev-p2">P2</span> planned-but-untouched story past grace.</p>
|
|
1942
|
+
<p><strong>G-decisions — undocumented decisions</strong>
|
|
1943
|
+
(<code>src/observability/checks/lens-g-decisions.ts</code>). <em>Decisions made in the
|
|
1944
|
+
ledger/commits but not documented (or vice versa)?</em> <strong>Reads:</strong> graph decisions,
|
|
1945
|
+
<code>decision_recorded</code> events, recent git commits (keyword scan), and D-stack's
|
|
1946
|
+
findings. <strong>Tunes:</strong> none effective (see note). <strong>Severity:</strong> <span class="sev sev-p0">P0</span>
|
|
1947
|
+
unsanctioned dep from D with no decision; <span class="sev sev-p1">P1</span> ledger↔doc mismatch;
|
|
1948
|
+
<span class="sev sev-p2">P2</span> decision-keyword commit with no event/doc.</p>
|
|
1949
|
+
<div class="callout callout-warning"><p><strong>Inert override.</strong> The spec advertises a <code>lenses.G-decisions.keywords_file</code>
|
|
1950
|
+
override and ships <code>src/observability/checks/data/decision-keywords.txt</code>, but
|
|
1951
|
+
<code>loadKeywords()</code> hard-codes its keyword list and never reads the config key or
|
|
1952
|
+
the file. The override and the bundled file are currently inert.</p></div>
|
|
1953
|
+
<p><strong>H-cross-doc — cross-doc inconsistency</strong>
|
|
1954
|
+
(<code>src/observability/checks/lens-h-cross-doc.ts</code>). <em>Are features, stories, plans,
|
|
1955
|
+
playbook and decisions internally consistent?</em> <strong>Reads:</strong> the full structural
|
|
1956
|
+
doc-graph + unresolved globs. <strong>Severity:</strong> <span class="sev sev-p0">P0</span> decision supersedes
|
|
1957
|
+
a non-existent decision, or a <em>must</em>-priority story uncovered by plan/playbook;
|
|
1958
|
+
<span class="sev sev-p1">P1</span> feature with no story / orphan story / <em>should</em>-priority
|
|
1959
|
+
uncovered story; <span class="sev sev-p2">P2</span> plan task not in playbook, unresolved glob.</p>
|
|
1960
|
+
<p>Under <code>--profile=full</code> only, Lens H runs three extra checks via an LLM dispatcher
|
|
1961
|
+
(all silently return <code>[]</code> if the dispatcher fails, so the audit never breaks):</p>
|
|
1962
|
+
<ul>
|
|
1963
|
+
<li><strong>tech-stack ↔ PRD</strong> — contradictions (<span class="sev sev-p0">P0</span>) or tensions
|
|
1964
|
+
(<span class="sev sev-p2">P2</span>) between PRD prose and the chosen stack.</li>
|
|
1965
|
+
<li><strong>PRD → stories coverage</strong> — a prose feature with no covering story
|
|
1966
|
+
(<span class="sev sev-p1">P1</span>).</li>
|
|
1967
|
+
<li><strong>terminology drift</strong> — one concept named inconsistently across docs
|
|
1968
|
+
(<span class="sev sev-p2">P2</span>).</li>
|
|
1969
|
+
</ul>
|
|
1970
|
+
<div class="callout callout-danger"><p><strong>Security — the LLM dispatcher command is hard-coded.</strong> Lens H passes the
|
|
1971
|
+
literal <code>claude -p</code> (<span class="fp" data-path="src/observability/checks/lens-h-cross-doc.ts:164">src/observability/checks/lens-h-cross-doc.ts:164</span>) into
|
|
1972
|
+
the shared dispatcher (<code>src/observability/engine/llm-dispatcher.ts</code>, which runs
|
|
1973
|
+
it through a fixed subprocess). The command is <em>deliberately not</em>
|
|
1974
|
+
project-config-overridable, because the audit may run against untrusted
|
|
1975
|
+
third-party repos and a repo-controlled command would be arbitrary code
|
|
1976
|
+
execution. Only <code>llm.timeout_s</code> (and <code>llm.parallel_checks</code>) are configurable.
|
|
1977
|
+
Contrast the <code>--fix</code> dispatcher, which <em>is</em> configurable — see
|
|
1978
|
+
<a href="#the---fix-flow">The --fix flow</a>.</p></div>
|
|
1979
|
+
<p><strong>I-knowledge-gaps — the ninth lens</strong>
|
|
1980
|
+
(<code>src/observability/checks/lens-i-knowledge-gaps.ts</code>). <em>What topics have agents
|
|
1981
|
+
repeatedly needed (over a 90-day window) with no knowledge-base entry?</em> <strong>Reads:</strong>
|
|
1982
|
+
<code>knowledge_gap_signal</code> ledger events + synthetic signals scanned from
|
|
1983
|
+
<code>tasks/lessons.md</code> (<code>src/observability/checks/lens-i-lessons-scanner.ts</code>).
|
|
1984
|
+
<strong>Severity:</strong> <span class="sev sev-p1">P1</span> ≥5 signals from ≥3 projects; <span class="sev sev-p2">P2</span>
|
|
1985
|
+
≥3 signals from ≥2 projects.</p>
|
|
1986
|
+
<div class="callout callout-note"><p><strong>Lens I — <code>--knowledge-root</code> and existing-entry suppression.</strong> The lens resolves
|
|
1987
|
+
the knowledge directory in three tiers (<code>src/observability/knowledge-index.ts</code>):
|
|
1988
|
+
the <code>--knowledge-root</code> CLI flag → <code>lenses.I-knowledge-gaps.knowledge_root</code> in
|
|
1989
|
+
config → auto-detect by walking up for <code>content/knowledge/</code>. If a gap's topic
|
|
1990
|
+
slug already exists in the resolved knowledge index, the finding is
|
|
1991
|
+
<strong>suppressed</strong> (no P1/P2). If no root resolves, suppression is disabled and the
|
|
1992
|
+
lens warns once per audit. Shipped in #397 (lens + lessons scanner) and #406
|
|
1993
|
+
(<code>--knowledge-root</code> + suppression).</p></div>
|
|
1994
|
+
<h2 id="the-observe-audit-cli">The <code>observe audit</code> CLI</h2>
|
|
1995
|
+
<p>One command runs the lenses and reports findings. Its exit code is the verdict
|
|
1996
|
+
gate: <code>0</code> on a non-blocked verdict (or any <code>mmr-findings</code> run), <code>1</code> when blocked
|
|
1997
|
+
or when a <code>--fix</code> pass still failed, <code>3</code> on an audit error.</p>
|
|
1998
|
+
<h3 id="every-flag">Every flag</h3>
|
|
1999
|
+
|
|
2000
|
+
|
|
2001
|
+
|
|
2002
|
+
|
|
2003
|
+
|
|
2004
|
+
|
|
2005
|
+
|
|
2006
|
+
|
|
2007
|
+
|
|
2008
|
+
|
|
2009
|
+
|
|
2010
|
+
|
|
2011
|
+
|
|
2012
|
+
|
|
2013
|
+
|
|
2014
|
+
|
|
2015
|
+
|
|
2016
|
+
|
|
2017
|
+
|
|
2018
|
+
|
|
2019
|
+
|
|
2020
|
+
|
|
2021
|
+
|
|
2022
|
+
|
|
2023
|
+
|
|
2024
|
+
|
|
2025
|
+
|
|
2026
|
+
|
|
2027
|
+
|
|
2028
|
+
|
|
2029
|
+
|
|
2030
|
+
|
|
2031
|
+
|
|
2032
|
+
|
|
2033
|
+
|
|
2034
|
+
|
|
2035
|
+
|
|
2036
|
+
|
|
2037
|
+
|
|
2038
|
+
|
|
2039
|
+
|
|
2040
|
+
|
|
2041
|
+
|
|
2042
|
+
|
|
2043
|
+
|
|
2044
|
+
|
|
2045
|
+
|
|
2046
|
+
|
|
2047
|
+
|
|
2048
|
+
|
|
2049
|
+
|
|
2050
|
+
|
|
2051
|
+
|
|
2052
|
+
|
|
2053
|
+
|
|
2054
|
+
|
|
2055
|
+
|
|
2056
|
+
|
|
2057
|
+
|
|
2058
|
+
|
|
2059
|
+
<table><thead><tr><th>flag</th><th>values / default</th><th>effect</th></tr></thead><tbody><tr><td><code>--scope</code></td><td><code>code</code> · <code>docs</code> · <code>all</code> (default <code>all</code>)</td><td>which lens set runs</td></tr><tr><td><code>--lens <id></code></td><td>repeatable</td><td>run exactly these lenses, overriding scope</td></tr><tr><td><code>--profile</code></td><td><code>fast</code> (default) · <code>full</code></td><td><code>full</code> enables Lens H's LLM-graded sub-checks</td></tr><tr><td><code>--fix</code></td><td>flag</td><td>after auditing, dispatch the fix loop for blocking findings</td></tr><tr><td><code>--fix-threshold</code></td><td><code>P0</code>–<code>P3</code></td><td>override the blocking cutoff for this run</td></tr><tr><td><code>--output=<path></code></td><td>path</td><td>override markdown destination (sidecar unaffected)</td></tr><tr><td><code>--render</code></td><td><code>dashboard-fragment-audit</code></td><td>emit HTML to stdout; skip markdown + sidecar</td></tr><tr><td><code>--output-mode</code></td><td><code>mmr-findings</code></td><td>emit MMR Finding JSON to stdout (always exit 0); skip markdown + sidecar</td></tr><tr><td><code>--knowledge-root=<path></code></td><td>path</td><td>tier-1 knowledge dir for Lens I suppression</td></tr><tr><td><code>--json</code> · <code>--mask-paths</code> · <code>--show-acknowledged</code> · <code>--since-hours</code></td><td>flags / N</td><td>raw JSON output · redact paths · include acked findings · activity window</td></tr></tbody></table>
|
|
2060
|
+
<pre><code class="language-bash"># A docs-only full audit including LLM-graded checks
|
|
2061
|
+
scaffold observe audit --scope docs --profile full
|
|
2062
|
+
|
|
2063
|
+
# Audit, then dispatch a fix agent for each blocking finding
|
|
2064
|
+
scaffold observe audit --fix --fix-threshold P1
|
|
2065
|
+
|
|
2066
|
+
# Lens I only, with an explicit knowledge root for suppression
|
|
2067
|
+
scaffold observe audit --lens I-knowledge-gaps --knowledge-root content/knowledge
|
|
2068
|
+
</code></pre>
|
|
2069
|
+
<h3 id="verdict-taxonomy">Verdict taxonomy</h3>
|
|
2070
|
+
<p>The engine computes exactly three verdicts (<code>Verdict</code> at
|
|
2071
|
+
<span class="fp" data-path="src/observability/engine/types.ts:6">src/observability/engine/types.ts:6</span>):</p>
|
|
2072
|
+
|
|
2073
|
+
|
|
2074
|
+
|
|
2075
|
+
|
|
2076
|
+
|
|
2077
|
+
|
|
2078
|
+
|
|
2079
|
+
|
|
2080
|
+
|
|
2081
|
+
|
|
2082
|
+
|
|
2083
|
+
|
|
2084
|
+
|
|
2085
|
+
|
|
2086
|
+
|
|
2087
|
+
|
|
2088
|
+
|
|
2089
|
+
|
|
2090
|
+
|
|
2091
|
+
|
|
2092
|
+
|
|
2093
|
+
|
|
2094
|
+
|
|
2095
|
+
|
|
2096
|
+
|
|
2097
|
+
<table><thead><tr><th>verdict</th><th>when</th><th>exit</th></tr></thead><tbody><tr><td><span class="sev sev-pass">pass</span></td><td>no blocking findings, no skipped lenses</td><td><code>0</code></td></tr><tr><td><span class="sev sev-p2">degraded-pass</span></td><td>no blocking findings, but ≥1 lens skipped (missing required adapter)</td><td><code>0</code></td></tr><tr><td><span class="sev sev-p0">blocked</span></td><td>≥1 <em>open</em> finding at or above <code>fix_threshold</code></td><td><code>1</code></td></tr></tbody></table>
|
|
2098
|
+
<div class="callout callout-note"><p><strong>"needs-user-decision" is not an engine verdict.</strong> The code-review workflow has
|
|
2099
|
+
a <code>needs-user-decision</code> outcome, but that is an <em>MMR review</em> verdict, not one the
|
|
2100
|
+
audit engine emits. The audit engine's universe is exactly the three above.</p></div>
|
|
2101
|
+
<h4><code>fix_threshold</code></h4>
|
|
2102
|
+
<p>A finding is <em>blocking</em> when its status is <code>open</code> and its severity is at or above
|
|
2103
|
+
the threshold (<code>src/observability/engine/checks/fix-threshold.ts</code>). Resolution
|
|
2104
|
+
order: <code>--fix-threshold</code> flag → <code>.mmr.yaml</code>
|
|
2105
|
+
(<code>audit_fix_threshold</code> / <code>fix_threshold</code>) → default <strong>P2</strong>. The threshold never
|
|
2106
|
+
<em>hides</em> findings — every finding is still reported; it only decides which ones
|
|
2107
|
+
count toward <code>blocked</code>.</p>
|
|
2108
|
+
<div class="callout callout-note"><p><strong>How the counts are computed</strong>
|
|
2109
|
+
(<code>src/observability/engine/checks/findings-aggregator.ts</code>): <code>blocking</code> counts a
|
|
2110
|
+
finding only when <code>status === 'open'</code> <em>and</em> its severity is at or above
|
|
2111
|
+
<code>fix_threshold</code>; <code>acknowledged</code> counts only findings silenced by a
|
|
2112
|
+
<code>finding_acknowledged</code> ledger event (latest event per id wins); <code>skipped</code>
|
|
2113
|
+
findings (missing-adapter lenses) ignore acks entirely. The renderers'
|
|
2114
|
+
<code>(blocking · ack · total)</code> line is this tally.</p></div>
|
|
2115
|
+
<h3 id="companion-verb-scaffold-observe-ack">Companion verb — <code>scaffold observe ack</code></h3>
|
|
2116
|
+
<p>Acknowledge (or reopen) a finding by ID prefix; it writes a
|
|
2117
|
+
<code>finding_acknowledged</code> event the aggregator reads on the next audit.</p>
|
|
2118
|
+
|
|
2119
|
+
|
|
2120
|
+
|
|
2121
|
+
|
|
2122
|
+
|
|
2123
|
+
|
|
2124
|
+
|
|
2125
|
+
|
|
2126
|
+
|
|
2127
|
+
|
|
2128
|
+
|
|
2129
|
+
|
|
2130
|
+
|
|
2131
|
+
|
|
2132
|
+
|
|
2133
|
+
|
|
2134
|
+
|
|
2135
|
+
|
|
2136
|
+
|
|
2137
|
+
|
|
2138
|
+
|
|
2139
|
+
<table><thead><tr><th>arg / flag</th><th>effect</th></tr></thead><tbody><tr><td><code><prefix-or-id></code></td><td>matched against all finding IDs in <code>docs/audits/*.json</code>; an ambiguous prefix exits <code>2</code></td></tr><tr><td><code>--status acknowledged｜open</code></td><td><code>acknowledged</code> (default) silences it; <code>open</code> reopens it</td></tr><tr><td><code>--note "…"</code></td><td>optional rationale recorded on the event</td></tr></tbody></table>
|
|
2140
|
+
<p>Branch is auto-derived (<code>git rev-parse --abbrev-ref HEAD</code>, fallback <code>main</code>); the
|
|
2141
|
+
event's <code>task_id</code> is null.</p>
|
|
2142
|
+
<h3 id="exit-codes-across-observe-verbs">Exit codes across <code>observe</code> verbs</h3>
|
|
2143
|
+
|
|
2144
|
+
|
|
2145
|
+
|
|
2146
|
+
|
|
2147
|
+
|
|
2148
|
+
|
|
2149
|
+
|
|
2150
|
+
|
|
2151
|
+
|
|
2152
|
+
|
|
2153
|
+
|
|
2154
|
+
|
|
2155
|
+
|
|
2156
|
+
|
|
2157
|
+
|
|
2158
|
+
|
|
2159
|
+
|
|
2160
|
+
|
|
2161
|
+
|
|
2162
|
+
|
|
2163
|
+
|
|
2164
|
+
|
|
2165
|
+
|
|
2166
|
+
|
|
2167
|
+
|
|
2168
|
+
|
|
2169
|
+
|
|
2170
|
+
|
|
2171
|
+
|
|
2172
|
+
|
|
2173
|
+
|
|
2174
|
+
|
|
2175
|
+
|
|
2176
|
+
|
|
2177
|
+
|
|
2178
|
+
|
|
2179
|
+
|
|
2180
|
+
|
|
2181
|
+
|
|
2182
|
+
|
|
2183
|
+
|
|
2184
|
+
|
|
2185
|
+
|
|
2186
|
+
|
|
2187
|
+
|
|
2188
|
+
|
|
2189
|
+
|
|
2190
|
+
<table><thead><tr><th>verb</th><th>0</th><th>1</th><th>2</th><th>3</th></tr></thead><tbody><tr><td><code>audit</code></td><td>not blocked, or any <code>mmr-findings</code> run</td><td>blocked, or <code>--fix</code> left a blocker</td><td>—</td><td>audit error (130 on SIGINT mid-<code>--fix</code>, snapshot restored)</td></tr><tr><td><code>event</code></td><td>written</td><td>—</td><td>validation failed / payload > 4 KiB</td><td>other error</td></tr><tr><td><code>ack</code></td><td>written</td><td>—</td><td>no match / ambiguous prefix</td><td>no audit sidecars / write error</td></tr><tr><td><code>progress</code></td><td>ok</td><td>—</td><td>—</td><td>markdown/sidecar write error (with <code>--output</code>)</td></tr><tr><td><code>harvest</code></td><td>harvested / recovered</td><td>—</td><td>—</td><td>no <code>identity.json</code>, or primary root is itself a worktree</td></tr></tbody></table>
|
|
2191
|
+
<h2 id="progress-replay-stall">Progress, replay & stall</h2>
|
|
2192
|
+
<p><code>scaffold observe progress</code> shows what's in flight. With <code>--replay</code> it fuses the
|
|
2193
|
+
ledger with synthesized git/gh/mmr/state/tests events into one timeline; when
|
|
2194
|
+
<code>scaffold observe progress</code> runs it also evaluates stall detection and surfaces a
|
|
2195
|
+
"Needs Attention" panel (suppress with <code>--no-stall-check</code>).</p>
|
|
2196
|
+
<h3 id="fusion-how-the-timeline-is-built">Fusion — how the timeline is built</h3>
|
|
2197
|
+
<p>The synthesizer's <code>composeReplay</code>
|
|
2198
|
+
(<span class="fp" data-path="src/observability/engine/synthesizer.ts:294">src/observability/engine/synthesizer.ts:294</span>) converts each ledger <code>Event</code>
|
|
2199
|
+
to a <code>ReplayEvent</code>, concatenates the adapter events, filters to the time window,
|
|
2200
|
+
then dedups:</p>
|
|
2201
|
+
<ul>
|
|
2202
|
+
<li>Events with a <code>null</code> <code>correlation_id</code> pass through untouched.</li>
|
|
2203
|
+
<li>Events that share a <code>correlation_id</code> collapse to one — the synthesizer keeps
|
|
2204
|
+
the lowest <code>SOURCE_PRIORITY</code> number (<code>ledger</code> 0 → <code>tests</code> 5), breaking ties by
|
|
2205
|
+
earliest <code>ts</code>.</li>
|
|
2206
|
+
<li>The surviving events sort by <code>(ts, source-priority, sort_id)</code>.</li>
|
|
2207
|
+
</ul>
|
|
2208
|
+
<p>So a PR that the agent recorded (<code>pr_opened</code> in the ledger) and that the <code>gh</code>
|
|
2209
|
+
adapter also reports collapses to the single ledger event, because <code>ledger</code> (0)
|
|
2210
|
+
outranks <code>gh</code> (2).</p>
|
|
2211
|
+
<h3 id="stall-detection-the-six-signals">Stall detection — the six signals</h3>
|
|
2212
|
+
<p>When <code>scaffold observe progress</code> runs (unless <code>--no-stall-check</code>) the engine
|
|
2213
|
+
checks for staleness and builds <code>needs_attention</code>
|
|
2214
|
+
(<code>src/observability/engine/stall.ts</code>). The type declares six
|
|
2215
|
+
signals; <strong>five fire today</strong> — <code>pr_review_stale</code> is reserved (deferred pending a
|
|
2216
|
+
per-PR correlation_id on the mmr adapter,
|
|
2217
|
+
<span class="fp" data-path="src/observability/engine/stall.ts:119">src/observability/engine/stall.ts:119</span>). Thresholds accept <code>'Nh'</code>, <code>'Nd'</code>,
|
|
2218
|
+
or <code>'off'</code> under <code>stall.*</code>:</p>
|
|
2219
|
+
|
|
2220
|
+
|
|
2221
|
+
|
|
2222
|
+
|
|
2223
|
+
|
|
2224
|
+
|
|
2225
|
+
|
|
2226
|
+
|
|
2227
|
+
|
|
2228
|
+
|
|
2229
|
+
|
|
2230
|
+
|
|
2231
|
+
|
|
2232
|
+
|
|
2233
|
+
|
|
2234
|
+
|
|
2235
|
+
|
|
2236
|
+
|
|
2237
|
+
|
|
2238
|
+
|
|
2239
|
+
|
|
2240
|
+
|
|
2241
|
+
|
|
2242
|
+
|
|
2243
|
+
|
|
2244
|
+
|
|
2245
|
+
|
|
2246
|
+
|
|
2247
|
+
|
|
2248
|
+
|
|
2249
|
+
|
|
2250
|
+
|
|
2251
|
+
|
|
2252
|
+
|
|
2253
|
+
|
|
2254
|
+
|
|
2255
|
+
|
|
2256
|
+
|
|
2257
|
+
|
|
2258
|
+
|
|
2259
|
+
<table><thead><tr><th>signal</th><th>fires when</th><th>config key · default</th></tr></thead><tbody><tr><td><code>task_stale</code></td><td>task claimed, no commit/heartbeat/completion since</td><td><code>stall.task_stale</code> · <code>4h</code></td></tr><tr><td><code>pr_stale</code></td><td>ledger <code>pr_opened</code> recorded, PR not merged/closed since</td><td><code>stall.pr_stale</code> · <code>48h</code></td></tr><tr><td><code>blocker_unaddressed</code></td><td><code>blocker_hit</code> with no <code>blocker_resolved</code></td><td><code>stall.blocker_unaddressed</code> · <code>2h</code></td></tr><tr><td><code>audit_findings_unresolved</code></td><td>open finding past threshold age, severity at or above <code>fix_threshold</code></td><td><code>stall.audit_findings_unresolved</code> · <code>24h</code></td></tr><tr><td><code>lens_skipped_repeatedly</code></td><td>a lens skipped on ≥3 consecutive audits</td><td>hard-coded streak ≥ 3 (no config key)</td></tr><tr><td><code>pr_review_stale</code> (reserved)</td><td>— not yet emitted —</td><td><code>stall.pr_review_stale</code> · <code>24h</code> (defined, unused)</td></tr></tbody></table>
|
|
2260
|
+
<h3 id="flags">Flags</h3>
|
|
2261
|
+
|
|
2262
|
+
|
|
2263
|
+
|
|
2264
|
+
|
|
2265
|
+
|
|
2266
|
+
|
|
2267
|
+
|
|
2268
|
+
|
|
2269
|
+
|
|
2270
|
+
|
|
2271
|
+
|
|
2272
|
+
|
|
2273
|
+
|
|
2274
|
+
|
|
2275
|
+
|
|
2276
|
+
|
|
2277
|
+
|
|
2278
|
+
|
|
2279
|
+
|
|
2280
|
+
|
|
2281
|
+
|
|
2282
|
+
|
|
2283
|
+
|
|
2284
|
+
|
|
2285
|
+
|
|
2286
|
+
<table><thead><tr><th>flag</th><th>effect</th></tr></thead><tbody><tr><td><code>--replay</code></td><td>include the fused timeline in the output</td></tr><tr><td><code>--no-stall-check</code></td><td>suppress the "Needs Attention" surface (empty <code>needs_attention</code>)</td></tr><tr><td><code>--render=dashboard-fragment</code></td><td>emit the progress HTML panel to stdout; skip markdown + sidecar</td></tr><tr><td><code>--output=<path></code> · <code>--json</code> · <code>--since-hours N</code></td><td>override markdown path · raw JSON · activity window (default 24)</td></tr></tbody></table>
|
|
2287
|
+
<p>Stall thresholds are configurable under <code>stall:</code> in
|
|
2288
|
+
<code>.scaffold/observability.yaml</code> — see <a href="#config-reference">Config reference</a>.</p>
|
|
2289
|
+
<h2 id="phase-boundary-triggers">Phase-boundary triggers</h2>
|
|
2290
|
+
<p>Completing a planning document should re-check the docs for drift —
|
|
2291
|
+
automatically, but never blocking the build. When a pipeline step at a phase
|
|
2292
|
+
boundary is marked complete, the state manager fires a docs audit and prints a
|
|
2293
|
+
one-line summary.</p>
|
|
2294
|
+
<h3 id="the-hook">The hook</h3>
|
|
2295
|
+
<p><code>StateManager.markCompleted()</code> is <strong>async</strong>
|
|
2296
|
+
(<span class="fp" data-path="src/state/state-manager.ts:175">src/state/state-manager.ts:175</span>): it saves state, then awaits
|
|
2297
|
+
<code>runPhaseAudit({ primaryRoot, step })</code> for <em>every</em> completed step — the
|
|
2298
|
+
phase-boundary gate lives inside <code>runPhaseAudit</code>, which returns a no-op result
|
|
2299
|
+
unless the step is one of the six boundaries
|
|
2300
|
+
(<code>src/observability/engine/phase-subsets.ts</code>): <code>user-stories</code>, <code>tech-stack</code>,
|
|
2301
|
+
<code>coding-standards</code>, <code>design-system</code>, <code>implementation-plan</code>,
|
|
2302
|
+
<code>implementation-playbook</code>.</p>
|
|
2303
|
+
<figure class="mermaid"><svg id="my-svg" width="100%" xmlns="http://www.w3.org/2000/svg" class="flowchart" style="max-width: 1273.34px; background-color: transparent;" viewBox="0 0 1273.34375 190.39999389648438" role="graphics-document document">#my-svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#000000;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#my-svg .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#my-svg .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#my-svg .error-icon{fill:#552222;}#my-svg .error-text{fill:#552222;stroke:#552222;}#my-svg .edge-thickness-normal{stroke-width:1px;}#my-svg .edge-thickness-thick{stroke-width:3.5px;}#my-svg .edge-pattern-solid{stroke-dasharray:0;}#my-svg .edge-thickness-invisible{stroke-width:0;fill:none;}#my-svg .edge-pattern-dashed{stroke-dasharray:3;}#my-svg .edge-pattern-dotted{stroke-dasharray:2;}#my-svg .marker{fill:#666;stroke:#666;}#my-svg .marker.cross{stroke:#666;}#my-svg svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#my-svg p{margin:0;}#my-svg .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#000000;}#my-svg .cluster-label text{fill:#333;}#my-svg .cluster-label span{color:#333;}#my-svg .cluster-label span p{background-color:transparent;}#my-svg .label text,#my-svg span{fill:#000000;color:#000000;}#my-svg .node rect,#my-svg .node circle,#my-svg .node ellipse,#my-svg .node polygon,#my-svg .node path{fill:#eee;stroke:#999;stroke-width:1px;}#my-svg .rough-node .label text,#my-svg .node .label text,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-anchor:middle;}#my-svg .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#my-svg .rough-node .label,#my-svg .node .label,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-align:center;}#my-svg .node.clickable{cursor:pointer;}#my-svg .root .anchor path{fill:#666!important;stroke-width:0;stroke:#666;}#my-svg .arrowheadPath{fill:#333333;}#my-svg .edgePath .path{stroke:#666;stroke-width:1px;}#my-svg .flowchart-link{stroke:#666;fill:none;}#my-svg .edgeLabel{background-color:white;text-align:center;}#my-svg .edgeLabel p{background-color:white;}#my-svg .edgeLabel rect{opacity:0.5;background-color:white;fill:white;}#my-svg .labelBkg{background-color:rgba(255, 255, 255, 0.5);}#my-svg .cluster rect{fill:hsl(0, 0%, 98.9215686275%);stroke:#707070;stroke-width:1px;}#my-svg .cluster text{fill:#333;}#my-svg .cluster span{color:#333;}#my-svg div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(-160, 0%, 93.3333333333%);border:1px solid #707070;border-radius:2px;pointer-events:none;z-index:100;}#my-svg .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#000000;}#my-svg rect.text{fill:none;stroke-width:0;}#my-svg .icon-shape,#my-svg .image-shape{background-color:white;text-align:center;}#my-svg .icon-shape p,#my-svg .image-shape p{background-color:white;padding:2px;}#my-svg .icon-shape .label rect,#my-svg .image-shape .label rect{opacity:0.5;background-color:white;fill:white;}#my-svg .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#my-svg .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#my-svg .node .neo-node{stroke:#999;}#my-svg [data-look="neo"].node rect,#my-svg [data-look="neo"].cluster rect,#my-svg [data-look="neo"].node polygon{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node path{stroke:url(#my-svg-gradient);stroke-width:1px;}#my-svg [data-look="neo"].node .outer-path{filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node .neo-line path{stroke:#999;filter:none;}#my-svg [data-look="neo"].node circle{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node circle .state-start{fill:#000000;}#my-svg [data-look="neo"].icon-shape .icon{fill:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].icon-shape .icon-neo path{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}<g><marker id="my-svg_flowchart-v2-pointEnd" class="marker flowchart-v2" viewBox="0 0 10 10" refX="5" refY="5" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-pointStart" class="marker flowchart-v2" viewBox="0 0 10 10" refX="4.5" refY="5" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" orient="auto"><path d="M 0 5 L 10 10 L 10 0 z" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-pointEnd-margin" class="marker flowchart-v2" viewBox="0 0 11.5 14" refX="11.5" refY="7" markerUnits="userSpaceOnUse" markerWidth="10.5" markerHeight="14" orient="auto"><path d="M 0 0 L 11.5 7 L 0 14 z" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-pointStart-margin" class="marker flowchart-v2" viewBox="0 0 11.5 14" refX="1" refY="7" markerUnits="userSpaceOnUse" markerWidth="11.5" markerHeight="14" orient="auto"><polygon points="0,7 11.5,14 11.5,0" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></polygon></marker><marker id="my-svg_flowchart-v2-circleEnd" class="marker flowchart-v2" viewBox="0 0 10 10" refX="11" refY="5" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-circleStart" class="marker flowchart-v2" viewBox="0 0 10 10" refX="-1" refY="5" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-circleEnd-margin" class="marker flowchart-v2" viewBox="0 0 10 10" refY="5" refX="12.25" markerUnits="userSpaceOnUse" markerWidth="14" markerHeight="14" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-circleStart-margin" class="marker flowchart-v2" viewBox="0 0 10 10" refX="-2" refY="5" markerUnits="userSpaceOnUse" markerWidth="14" markerHeight="14" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-crossEnd" class="marker cross flowchart-v2" viewBox="0 0 11 11" refX="12" refY="5.2" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><path d="M 1,1 l 9,9 M 10,1 l -9,9" class="arrowMarkerPath" style="stroke-width: 2; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-crossStart" class="marker cross flowchart-v2" viewBox="0 0 11 11" refX="-1" refY="5.2" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><path d="M 1,1 l 9,9 M 10,1 l -9,9" class="arrowMarkerPath" style="stroke-width: 2; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-crossEnd-margin" class="marker cross flowchart-v2" viewBox="0 0 15 15" refX="17.7" refY="7.5" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto"><path d="M 1,1 L 14,14 M 1,14 L 14,1" class="arrowMarkerPath" style="stroke-width: 2.5;"></path></marker><marker id="my-svg_flowchart-v2-crossStart-margin" class="marker cross flowchart-v2" viewBox="0 0 15 15" refX="-3.5" refY="7.5" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto"><path d="M 1,1 L 14,14 M 1,14 L 14,1" class="arrowMarkerPath" style="stroke-width: 2.5; stroke-dasharray: 1, 0;"></path></marker><g class="root"><g class="clusters"></g><g class="edgePaths"><path d="M196.906,104L201.073,104C205.24,104,213.573,104,221.24,104C228.906,104,235.906,104,239.406,104L242.906,104" id="my-svg-L_CLI_MC_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M476.688,78.291L497.685,73.593C518.682,68.894,560.677,59.497,602.005,54.799C643.333,50.1,683.995,50.1,704.326,50.1L724.656,50.1" id="my-svg-L_MC_RPA_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M962.078,50.1L966.245,50.1C970.411,50.1,978.745,50.1,986.411,50.1C994.078,50.1,1001.078,50.1,1004.578,50.1L1008.078,50.1" id="my-svg-L_RPA_OUT_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M476.688,129.709L497.685,134.407C518.682,139.106,560.677,148.503,610.118,153.201C659.56,157.9,716.448,157.9,744.892,157.9L773.336,157.9" id="my-svg-L_MC_NG_0" class="edge-thickness-normal edge-pattern-dotted edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path></g><g class="edgeLabels"><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel" transform="translate(602.671875, 157.89999771118164)"><g class="label" transform="translate(0, -19.299999237060547)"><g><rect class="background" style="" x="-100.984375" y="-1" width="201.96875" height="40.599998474121094"></rect><text y="-10.1" text-anchor="middle" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"><tspan class="text-inner-tspan">state</tspan><tspan class="text-inner-tspan"> already</tspan><tspan class="text-inner-tspan"> saved</tspan><tspan class="text-inner-tspan"> —</tspan><tspan class="text-inner-tspan"> audit</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em" text-anchor="middle"><tspan class="text-inner-tspan">error</tspan><tspan class="text-inner-tspan"> never</tspan><tspan class="text-inner-tspan"> rolls</tspan><tspan class="text-inner-tspan"> it</tspan><tspan class="text-inner-tspan"> back</tspan></tspan></text></g></g></g></g><g class="nodes"><g class="node default" id="my-svg-flowchart-CLI-0" transform="translate(102.453125, 103.99999809265137)"><rect class="basic label-container" style="" x="-94.453125" y="-24.5" width="188.90625" height="49"></rect><g class="label" style="" transform="translate(0, -9.5)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">scaffold</tspan><tspan class="text-inner-tspan"> complete</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-MC-1" transform="translate(361.796875, 103.99999809265137)"><rect class="basic label-container" style="" x="-114.890625" y="-42.099998474121094" width="229.78125" height="84.19999694824219"></rect><g class="label" style="" transform="translate(0, -27.099998474121094)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">markCompleted</tspan><tspan class="text-inner-tspan"> (async)</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">saveState</tspan><tspan class="text-inner-tspan"> →</tspan><tspan class="text-inner-tspan"> set</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="2.1em"><tspan class="text-inner-tspan">completed_at</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-RPA-3" transform="translate(845.3671875, 50.099998474121094)"><rect class="basic label-container" style="" x="-116.7109375" y="-33.29999923706055" width="233.421875" height="66.5999984741211"></rect><g class="label" style="" transform="translate(0, -18.299999237060547)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">runPhaseAudit</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">H-cross-doc</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> docs</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> fast</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-OUT-5" transform="translate(1138.7109375, 50.099998474121094)"><rect class="basic label-container" style="" x="-126.6328125" y="-42.099998474121094" width="253.265625" height="84.19999694824219"></rect><g class="label" style="" transform="translate(0, -27.099998474121094)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">docs/audits/id.md</tspan><tspan class="text-inner-tspan"> +</tspan><tspan class="text-inner-tspan"> .json</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">PhaseAuditResult</tspan><tspan class="text-inner-tspan"> →</tspan><tspan class="text-inner-tspan"> stdout</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="2.1em"><tspan class="text-inner-tspan">line</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-NG-7" transform="translate(845.3671875, 157.89999771118164)"><rect class="basic label-container" style="" x="-68.03125" y="-24.5" width="136.0625" height="49"></rect><g class="label" style="" transform="translate(0, -9.5)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">non-gating</tspan></tspan></text></g></g></g></g></g></g><defs></defs><defs></defs></svg></figure>
|
|
2304
|
+
<p>The audit is fixed to <code>H-cross-doc</code>, <code>scope=docs</code>, <code>profile=fast</code>
|
|
2305
|
+
(<code>src/observability/engine/phase-audit.ts</code>). It is <strong>non-gating</strong>:
|
|
2306
|
+
<code>markCompleted</code> catches any audit error and returns a result object, so a state
|
|
2307
|
+
transition never fails because of the audit.</p>
|
|
2308
|
+
<p>The stdout line:</p>
|
|
2309
|
+
<pre><code class="language-text"># normal
|
|
2310
|
+
[audit] 3 findings (1 blocking, verdict=blocked) — see docs/audits/audit-…-fast-lens-H-cross-doc-….md
|
|
2311
|
+
# detached (fire-and-forget)
|
|
2312
|
+
[audit] dispatched in background (step: tech-stack)
|
|
2313
|
+
# timed out
|
|
2314
|
+
[audit] timed out after 60500ms — partial findings may not be written
|
|
2315
|
+
</code></pre>
|
|
2316
|
+
<h3 id="config-timestamps">Config & timestamps</h3>
|
|
2317
|
+
|
|
2318
|
+
|
|
2319
|
+
|
|
2320
|
+
|
|
2321
|
+
|
|
2322
|
+
|
|
2323
|
+
|
|
2324
|
+
|
|
2325
|
+
|
|
2326
|
+
|
|
2327
|
+
|
|
2328
|
+
|
|
2329
|
+
|
|
2330
|
+
|
|
2331
|
+
|
|
2332
|
+
|
|
2333
|
+
|
|
2334
|
+
|
|
2335
|
+
|
|
2336
|
+
|
|
2337
|
+
|
|
2338
|
+
|
|
2339
|
+
|
|
2340
|
+
|
|
2341
|
+
|
|
2342
|
+
<table><thead><tr><th>key</th><th>default</th><th>effect</th></tr></thead><tbody><tr><td><code>phase_audit.enabled</code></td><td><code>true</code></td><td>master switch</td></tr><tr><td><code>phase_audit.timeout_s</code></td><td><code>60</code></td><td>race budget; over → <code>timed_out</code></td></tr><tr><td><code>phase_audit.detached</code></td><td><code>false</code></td><td>fire-and-forget when true</td></tr></tbody></table>
|
|
2343
|
+
<p>Step state (<code>src/types/state.ts</code>) now carries <code>completed_at</code> (set once, on first
|
|
2344
|
+
completion) and <code>in_progress_started_at</code> (set on first entry to in-progress). The
|
|
2345
|
+
<code>state</code> adapter's <code>replayEvents</code> prefers these per-step timestamps and only falls
|
|
2346
|
+
back to the file's mtime when they're absent — so the timeline reflects when each
|
|
2347
|
+
step actually transitioned, not when the file was last written.</p>
|
|
2348
|
+
<h2 id="mmr-doc-conformance-channel">MMR <code>doc-conformance</code> channel</h2>
|
|
2349
|
+
<p>The audit plugs into multi-model review as a built-in channel.
|
|
2350
|
+
<code>scaffold observe audit --output-mode=mmr-findings</code> emits findings in MMR's
|
|
2351
|
+
<code>Finding</code> shape (<code>src/observability/renderers/mmr-findings.ts</code>), always exiting 0
|
|
2352
|
+
so the dispatcher captures stdout regardless of verdict. Only <code>open</code> findings are
|
|
2353
|
+
emitted (acknowledged and skipped are dropped).</p>
|
|
2354
|
+
<h3 id="finding-translation">Finding translation</h3>
|
|
2355
|
+
<p>The composite <code>location</code> — <code><source_doc>::<lens_id>::<short_id></code> — gives each
|
|
2356
|
+
finding a stable identity across audit runs, so MMR can track the same defect
|
|
2357
|
+
over time.</p>
|
|
2358
|
+
|
|
2359
|
+
|
|
2360
|
+
|
|
2361
|
+
|
|
2362
|
+
|
|
2363
|
+
|
|
2364
|
+
|
|
2365
|
+
|
|
2366
|
+
|
|
2367
|
+
|
|
2368
|
+
|
|
2369
|
+
|
|
2370
|
+
|
|
2371
|
+
|
|
2372
|
+
|
|
2373
|
+
|
|
2374
|
+
|
|
2375
|
+
|
|
2376
|
+
|
|
2377
|
+
|
|
2378
|
+
|
|
2379
|
+
|
|
2380
|
+
|
|
2381
|
+
|
|
2382
|
+
|
|
2383
|
+
|
|
2384
|
+
|
|
2385
|
+
|
|
2386
|
+
|
|
2387
|
+
<table><thead><tr><th>MMR field</th><th>derived from</th></tr></thead><tbody><tr><td><code>severity</code></td><td><code>finding.severity</code> (P0–P3)</td></tr><tr><td><code>location</code></td><td><code>${source_doc || '(no-source-doc)'}::${lens_id}::${id.slice(0,8)}</code></td></tr><tr><td><code>description</code></td><td><code>[doc-conformance/${lens_id}] ${title}</code> + optional <code>— ${description}</code></td></tr><tr><td><code>suggestion</code></td><td><code>fix_hint?.prompt ?? fix_hint?.target ?? ''</code></td></tr><tr><td><code>category</code></td><td>literal <code>'doc-conformance'</code></td></tr></tbody></table>
|
|
2388
|
+
<p>A Lens-B engine <code>Finding</code> like this:</p>
|
|
2389
|
+
<pre><code class="language-json">{
|
|
2390
|
+
"id": "3a8c1f0211223344", "lens_id": "B-ac-coverage", "severity": "P0",
|
|
2391
|
+
"title": "AC has failing test", "description": "Test refresh.spec.ts is failing.",
|
|
2392
|
+
"source_doc": "docs/user-stories.md#user-auth-1",
|
|
2393
|
+
"fix_hint": { "prompt": "Re-enable the test", "target": "src/auth/test.spec.ts" }
|
|
2394
|
+
}
|
|
2395
|
+
</code></pre>
|
|
2396
|
+
<p>translates to this MMR Finding:</p>
|
|
2397
|
+
<pre><code class="language-json">{
|
|
2398
|
+
"location": "docs/user-stories.md#user-auth-1::B-ac-coverage::3a8c1f02",
|
|
2399
|
+
"severity": "P0",
|
|
2400
|
+
"description": "[doc-conformance/B-ac-coverage] AC has failing test — Test refresh.spec.ts is failing.",
|
|
2401
|
+
"suggestion": "Re-enable the test",
|
|
2402
|
+
"category": "doc-conformance"
|
|
2403
|
+
}
|
|
2404
|
+
</code></pre>
|
|
2405
|
+
<h3 id="enabling-it">Enabling it</h3>
|
|
2406
|
+
<p>The <code>doc-conformance</code> channel is <strong>disabled by default</strong>. Enable it per-project in
|
|
2407
|
+
<code>.mmr.yaml</code> or for a single run with <code>--channels=doc-conformance</code>; if it's
|
|
2408
|
+
globally enabled you can opt a project out via
|
|
2409
|
+
<code>channels_disabled: ["doc-conformance"]</code>.</p>
|
|
2410
|
+
<pre><code class="language-bash">mmr review --channels=doc-conformance --diff <(git diff main...HEAD) --sync --format json
|
|
2411
|
+
</code></pre>
|
|
2412
|
+
<p>Under the hood the built-in channel runs <code>scaffold observe audit --profile=full --scope=all --output-mode=mmr-findings</code> and parses its stdout. See the MMR guide
|
|
2413
|
+
(<a href="../mmr/index.md">../mmr/index.md</a>) for the channel architecture this plugs
|
|
2414
|
+
into.</p>
|
|
2415
|
+
<h2 id="the---fix-flow">The <code>--fix</code> flow</h2>
|
|
2416
|
+
<p><code>scaffold observe audit --fix</code> doesn't just report blocking findings — it
|
|
2417
|
+
dispatches an agent to fix each one, verifies the fix with a single-lens
|
|
2418
|
+
re-audit, and writes a post-fix report. The loop is abort-aware: an interrupt
|
|
2419
|
+
un-stages what the loop staged and re-applies the original stash (see the
|
|
2420
|
+
limitation in <a href="#abort-safety">Abort safety</a>).</p>
|
|
2421
|
+
<figure class="mermaid"><svg id="my-svg" width="100%" xmlns="http://www.w3.org/2000/svg" class="flowchart" style="max-width: 1433.47px; background-color: transparent;" viewBox="0 0 1433.46875 100.19999694824219" role="graphics-document document">#my-svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#000000;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#my-svg .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#my-svg .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#my-svg .error-icon{fill:#552222;}#my-svg .error-text{fill:#552222;stroke:#552222;}#my-svg .edge-thickness-normal{stroke-width:1px;}#my-svg .edge-thickness-thick{stroke-width:3.5px;}#my-svg .edge-pattern-solid{stroke-dasharray:0;}#my-svg .edge-thickness-invisible{stroke-width:0;fill:none;}#my-svg .edge-pattern-dashed{stroke-dasharray:3;}#my-svg .edge-pattern-dotted{stroke-dasharray:2;}#my-svg .marker{fill:#666;stroke:#666;}#my-svg .marker.cross{stroke:#666;}#my-svg svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#my-svg p{margin:0;}#my-svg .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#000000;}#my-svg .cluster-label text{fill:#333;}#my-svg .cluster-label span{color:#333;}#my-svg .cluster-label span p{background-color:transparent;}#my-svg .label text,#my-svg span{fill:#000000;color:#000000;}#my-svg .node rect,#my-svg .node circle,#my-svg .node ellipse,#my-svg .node polygon,#my-svg .node path{fill:#eee;stroke:#999;stroke-width:1px;}#my-svg .rough-node .label text,#my-svg .node .label text,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-anchor:middle;}#my-svg .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#my-svg .rough-node .label,#my-svg .node .label,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-align:center;}#my-svg .node.clickable{cursor:pointer;}#my-svg .root .anchor path{fill:#666!important;stroke-width:0;stroke:#666;}#my-svg .arrowheadPath{fill:#333333;}#my-svg .edgePath .path{stroke:#666;stroke-width:1px;}#my-svg .flowchart-link{stroke:#666;fill:none;}#my-svg .edgeLabel{background-color:white;text-align:center;}#my-svg .edgeLabel p{background-color:white;}#my-svg .edgeLabel rect{opacity:0.5;background-color:white;fill:white;}#my-svg .labelBkg{background-color:rgba(255, 255, 255, 0.5);}#my-svg .cluster rect{fill:hsl(0, 0%, 98.9215686275%);stroke:#707070;stroke-width:1px;}#my-svg .cluster text{fill:#333;}#my-svg .cluster span{color:#333;}#my-svg div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(-160, 0%, 93.3333333333%);border:1px solid #707070;border-radius:2px;pointer-events:none;z-index:100;}#my-svg .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#000000;}#my-svg rect.text{fill:none;stroke-width:0;}#my-svg .icon-shape,#my-svg .image-shape{background-color:white;text-align:center;}#my-svg .icon-shape p,#my-svg .image-shape p{background-color:white;padding:2px;}#my-svg .icon-shape .label rect,#my-svg .image-shape .label rect{opacity:0.5;background-color:white;fill:white;}#my-svg .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#my-svg .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#my-svg .node .neo-node{stroke:#999;}#my-svg [data-look="neo"].node rect,#my-svg [data-look="neo"].cluster rect,#my-svg [data-look="neo"].node polygon{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node path{stroke:url(#my-svg-gradient);stroke-width:1px;}#my-svg [data-look="neo"].node .outer-path{filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node .neo-line path{stroke:#999;filter:none;}#my-svg [data-look="neo"].node circle{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node circle .state-start{fill:#000000;}#my-svg [data-look="neo"].icon-shape .icon{fill:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].icon-shape .icon-neo path{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}<g><marker id="my-svg_flowchart-v2-pointEnd" class="marker flowchart-v2" viewBox="0 0 10 10" refX="5" refY="5" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-pointStart" class="marker flowchart-v2" viewBox="0 0 10 10" refX="4.5" refY="5" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" orient="auto"><path d="M 0 5 L 10 10 L 10 0 z" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-pointEnd-margin" class="marker flowchart-v2" viewBox="0 0 11.5 14" refX="11.5" refY="7" markerUnits="userSpaceOnUse" markerWidth="10.5" markerHeight="14" orient="auto"><path d="M 0 0 L 11.5 7 L 0 14 z" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-pointStart-margin" class="marker flowchart-v2" viewBox="0 0 11.5 14" refX="1" refY="7" markerUnits="userSpaceOnUse" markerWidth="11.5" markerHeight="14" orient="auto"><polygon points="0,7 11.5,14 11.5,0" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></polygon></marker><marker id="my-svg_flowchart-v2-circleEnd" class="marker flowchart-v2" viewBox="0 0 10 10" refX="11" refY="5" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-circleStart" class="marker flowchart-v2" viewBox="0 0 10 10" refX="-1" refY="5" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-circleEnd-margin" class="marker flowchart-v2" viewBox="0 0 10 10" refY="5" refX="12.25" markerUnits="userSpaceOnUse" markerWidth="14" markerHeight="14" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-circleStart-margin" class="marker flowchart-v2" viewBox="0 0 10 10" refX="-2" refY="5" markerUnits="userSpaceOnUse" markerWidth="14" markerHeight="14" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-crossEnd" class="marker cross flowchart-v2" viewBox="0 0 11 11" refX="12" refY="5.2" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><path d="M 1,1 l 9,9 M 10,1 l -9,9" class="arrowMarkerPath" style="stroke-width: 2; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-crossStart" class="marker cross flowchart-v2" viewBox="0 0 11 11" refX="-1" refY="5.2" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><path d="M 1,1 l 9,9 M 10,1 l -9,9" class="arrowMarkerPath" style="stroke-width: 2; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-crossEnd-margin" class="marker cross flowchart-v2" viewBox="0 0 15 15" refX="17.7" refY="7.5" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto"><path d="M 1,1 L 14,14 M 1,14 L 14,1" class="arrowMarkerPath" style="stroke-width: 2.5;"></path></marker><marker id="my-svg_flowchart-v2-crossStart-margin" class="marker cross flowchart-v2" viewBox="0 0 15 15" refX="-3.5" refY="7.5" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto"><path d="M 1,1 L 14,14 M 1,14 L 14,1" class="arrowMarkerPath" style="stroke-width: 2.5; stroke-dasharray: 1, 0;"></path></marker><g class="root"><g class="clusters"></g><g class="edgePaths"><path d="M246.266,50.1L250.432,50.1C254.599,50.1,262.932,50.1,270.599,50.1C278.266,50.1,285.266,50.1,288.766,50.1L292.266,50.1" id="my-svg-L_P1_P2_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M549.031,50.1L553.198,50.1C557.365,50.1,565.698,50.1,573.365,50.1C581.031,50.1,588.031,50.1,591.531,50.1L595.031,50.1" id="my-svg-L_P2_P3_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M821.594,50.1L825.76,50.1C829.927,50.1,838.26,50.1,845.927,50.1C853.594,50.1,860.594,50.1,864.094,50.1L867.594,50.1" id="my-svg-L_P3_P4_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M1121.234,50.1L1125.401,50.1C1129.568,50.1,1137.901,50.1,1145.568,50.1C1153.234,50.1,1160.234,50.1,1163.734,50.1L1167.234,50.1" id="my-svg-L_P4_P5_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path></g><g class="edgeLabels"><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g><g class="edgeLabel"><g class="label" transform="translate(0, 0)"><text y="-10.1" text-anchor="middle"><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"></tspan></text></g></g><g><rect class="background" style="stroke: none"></rect></g></g><g class="nodes"><g class="node default" id="my-svg-flowchart-P1-0" transform="translate(127.1328125, 50.099998474121094)"><rect class="basic label-container" style="" x="-119.1328125" y="-33.29999923706055" width="238.265625" height="66.5999984741211"></rect><g class="label" style="" transform="translate(0, -18.299999237060547)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">1</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> audit</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">collect</tspan><tspan class="text-inner-tspan"> findings</tspan><tspan class="text-inner-tspan"> +</tspan><tspan class="text-inner-tspan"> verdict</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-P2-1" transform="translate(422.6484375, 50.099998474121094)"><rect class="basic label-container" style="" x="-126.3828125" y="-42.099998474121094" width="252.765625" height="84.19999694824219"></rect><g class="label" style="" transform="translate(0, -27.099998474121094)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">2</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> buildFixPlan</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">keep</tspan><tspan class="text-inner-tspan"> open</tspan><tspan class="text-inner-tspan"> &</tspan><tspan class="text-inner-tspan"> ≥</tspan><tspan class="text-inner-tspan"> threshold;</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="2.1em"><tspan class="text-inner-tspan">order</tspan><tspan class="text-inner-tspan"> by</tspan><tspan class="text-inner-tspan"> severity</tspan><tspan class="text-inner-tspan"> then</tspan><tspan class="text-inner-tspan"> lens</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-P3-3" transform="translate(710.3125, 50.099998474121094)"><rect class="basic label-container" style="" x="-111.28125" y="-42.099998474121094" width="222.5625" height="84.19999694824219"></rect><g class="label" style="" transform="translate(0, -27.099998474121094)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">3</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> dispatchFixAgent</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">subprocess,</tspan><tspan class="text-inner-tspan"> prompt</tspan><tspan class="text-inner-tspan"> on</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="2.1em"><tspan class="text-inner-tspan">stdin</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-P4-5" transform="translate(996.4140625, 50.099998474121094)"><rect class="basic label-container" style="" x="-124.8203125" y="-42.099998474121094" width="249.640625" height="84.19999694824219"></rect><g class="label" style="" transform="translate(0, -27.099998474121094)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">4</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> verify</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">re-run</tspan><tspan class="text-inner-tspan"> that</tspan><tspan class="text-inner-tspan"> one</tspan><tspan class="text-inner-tspan"> lens;</tspan><tspan class="text-inner-tspan"> retry</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="2.1em"><tspan class="text-inner-tspan">≤</tspan><tspan class="text-inner-tspan"> 3</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-P5-7" transform="translate(1298.3515625, 50.099998474121094)"><rect class="basic label-container" style="" x="-127.1171875" y="-42.099998474121094" width="254.234375" height="84.19999694824219"></rect><g class="label" style="" transform="translate(0, -27.099998474121094)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">5</tspan><tspan class="text-inner-tspan"> ·</tspan><tspan class="text-inner-tspan"> post-fix</tspan><tspan class="text-inner-tspan"> report</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">docs/audits/id-postfix.{md</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="2.1em"><tspan class="text-inner-tspan">,json}</tspan></tspan></text></g></g></g></g></g></g><defs></defs><defs></defs></svg></figure>
|
|
2422
|
+
<h3 id="the-five-phases">The five phases</h3>
|
|
2423
|
+
<ul>
|
|
2424
|
+
<li><strong>1 · audit</strong> — run the audit to get findings and the verdict
|
|
2425
|
+
(<code>src/observability/engine/fix-flow.ts</code>).</li>
|
|
2426
|
+
<li><strong>2 · <code>buildFixPlan</code></strong> (<code>src/observability/engine/fix-plan.ts</code>) — keep findings
|
|
2427
|
+
that are <code>open</code> and at/above <code>fix_threshold</code>, ordered by severity ascending (P0
|
|
2428
|
+
first) then <code>lens_id</code>.</li>
|
|
2429
|
+
<li><strong>3 · <code>dispatchFixAgent</code></strong> (<code>src/observability/engine/fix-agent-dispatcher.ts</code>)
|
|
2430
|
+
— spawn the dispatcher command, write the per-finding prompt to stdin, stream
|
|
2431
|
+
stdout/stderr to the user.</li>
|
|
2432
|
+
<li><strong>4 · single-lens verify</strong> — re-run only the finding's lens; if the finding is
|
|
2433
|
+
gone, mark fixed; else retry, up to <code>per_finding_max_attempts</code> (default 3).</li>
|
|
2434
|
+
<li><strong>5 · post-fix report</strong> — a final <code>scope=all</code> audit, written to
|
|
2435
|
+
<code>docs/audits/<id>-postfix.{md,json}</code>.</li>
|
|
2436
|
+
</ul>
|
|
2437
|
+
<h3 id="abort-safety">Abort safety</h3>
|
|
2438
|
+
<p>Before dispatching, <code>captureSnapshot</code>
|
|
2439
|
+
(<code>src/observability/engine/abort-snapshot.ts</code>) records a <code>git stash create</code> SHA
|
|
2440
|
+
plus the set of pre-existing staged files. Newly staged paths are tracked per
|
|
2441
|
+
attempt. On <code>SIGINT</code>, <code>restoreSnapshot</code> un-stages the paths the loop recorded as
|
|
2442
|
+
newly staged and re-applies the original stash tree. <strong>Limitation:</strong> edits the
|
|
2443
|
+
dispatcher made but that the loop did not record as staged are not actively
|
|
2444
|
+
reverted and may need manual cleanup — recovery is scoped to the recorded
|
|
2445
|
+
staged paths plus the stash, not a guaranteed full reset.</p>
|
|
2446
|
+
<h3 id="config-the-fix-block">Config — the <code>fix:</code> block</h3>
|
|
2447
|
+
|
|
2448
|
+
|
|
2449
|
+
|
|
2450
|
+
|
|
2451
|
+
|
|
2452
|
+
|
|
2453
|
+
|
|
2454
|
+
|
|
2455
|
+
|
|
2456
|
+
|
|
2457
|
+
|
|
2458
|
+
|
|
2459
|
+
|
|
2460
|
+
|
|
2461
|
+
|
|
2462
|
+
|
|
2463
|
+
|
|
2464
|
+
|
|
2465
|
+
|
|
2466
|
+
|
|
2467
|
+
|
|
2468
|
+
|
|
2469
|
+
|
|
2470
|
+
|
|
2471
|
+
|
|
2472
|
+
<table><thead><tr><th>key</th><th>default</th><th>effect</th></tr></thead><tbody><tr><td><code>fix.dispatcher_command</code></td><td><code>claude -p</code></td><td>the agent command (configurable — see note)</td></tr><tr><td><code>fix.timeout_s</code></td><td><code>300</code></td><td>per-finding subprocess budget</td></tr><tr><td><code>fix.per_finding_max_attempts</code></td><td><code>3</code></td><td>verify retries before giving up</td></tr></tbody></table>
|
|
2473
|
+
<div class="callout callout-note"><p><strong>The fix dispatcher IS configurable — unlike Lens H's.</strong>
|
|
2474
|
+
<code>fix.dispatcher_command</code> is read from project config because the fix loop only
|
|
2475
|
+
runs against the maintainer's own repo, not untrusted third-party code
|
|
2476
|
+
(<code>src/observability/engine/fix-agent-dispatcher.ts</code>). This is the opposite of the
|
|
2477
|
+
Lens H LLM dispatcher, which hard-codes its command for untrusted-repo safety.
|
|
2478
|
+
CLAUDE.md's <code>--fix</code> note describing the dispatcher as "not
|
|
2479
|
+
project-config-overridable" conflates the two.</p></div>
|
|
2480
|
+
<p>Exit code: <code>1</code> if any blocking finding survived the loop, else <code>0</code>.</p>
|
|
2481
|
+
<h2 id="harvest-recover-teardown">Harvest, recover & teardown</h2>
|
|
2482
|
+
<p>A worktree's ledger is local to that worktree. Harvest copies it into the primary
|
|
2483
|
+
repo's archive before the worktree is removed; recover sweeps up ledgers whose
|
|
2484
|
+
worktrees vanished without being harvested; teardown does the whole dance in one
|
|
2485
|
+
command.</p>
|
|
2486
|
+
<figure class="mermaid"><svg id="my-svg" width="100%" xmlns="http://www.w3.org/2000/svg" class="flowchart" style="max-width: 1087.94px; background-color: transparent;" viewBox="0 0 1087.9375 100.19999694824219" role="graphics-document document">#my-svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#000000;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#my-svg .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#my-svg .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#my-svg .error-icon{fill:#552222;}#my-svg .error-text{fill:#552222;stroke:#552222;}#my-svg .edge-thickness-normal{stroke-width:1px;}#my-svg .edge-thickness-thick{stroke-width:3.5px;}#my-svg .edge-pattern-solid{stroke-dasharray:0;}#my-svg .edge-thickness-invisible{stroke-width:0;fill:none;}#my-svg .edge-pattern-dashed{stroke-dasharray:3;}#my-svg .edge-pattern-dotted{stroke-dasharray:2;}#my-svg .marker{fill:#666;stroke:#666;}#my-svg .marker.cross{stroke:#666;}#my-svg svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#my-svg p{margin:0;}#my-svg .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#000000;}#my-svg .cluster-label text{fill:#333;}#my-svg .cluster-label span{color:#333;}#my-svg .cluster-label span p{background-color:transparent;}#my-svg .label text,#my-svg span{fill:#000000;color:#000000;}#my-svg .node rect,#my-svg .node circle,#my-svg .node ellipse,#my-svg .node polygon,#my-svg .node path{fill:#eee;stroke:#999;stroke-width:1px;}#my-svg .rough-node .label text,#my-svg .node .label text,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-anchor:middle;}#my-svg .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#my-svg .rough-node .label,#my-svg .node .label,#my-svg .image-shape .label,#my-svg .icon-shape .label{text-align:center;}#my-svg .node.clickable{cursor:pointer;}#my-svg .root .anchor path{fill:#666!important;stroke-width:0;stroke:#666;}#my-svg .arrowheadPath{fill:#333333;}#my-svg .edgePath .path{stroke:#666;stroke-width:1px;}#my-svg .flowchart-link{stroke:#666;fill:none;}#my-svg .edgeLabel{background-color:white;text-align:center;}#my-svg .edgeLabel p{background-color:white;}#my-svg .edgeLabel rect{opacity:0.5;background-color:white;fill:white;}#my-svg .labelBkg{background-color:rgba(255, 255, 255, 0.5);}#my-svg .cluster rect{fill:hsl(0, 0%, 98.9215686275%);stroke:#707070;stroke-width:1px;}#my-svg .cluster text{fill:#333;}#my-svg .cluster span{color:#333;}#my-svg div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(-160, 0%, 93.3333333333%);border:1px solid #707070;border-radius:2px;pointer-events:none;z-index:100;}#my-svg .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#000000;}#my-svg rect.text{fill:none;stroke-width:0;}#my-svg .icon-shape,#my-svg .image-shape{background-color:white;text-align:center;}#my-svg .icon-shape p,#my-svg .image-shape p{background-color:white;padding:2px;}#my-svg .icon-shape .label rect,#my-svg .image-shape .label rect{opacity:0.5;background-color:white;fill:white;}#my-svg .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#my-svg .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#my-svg .node .neo-node{stroke:#999;}#my-svg [data-look="neo"].node rect,#my-svg [data-look="neo"].cluster rect,#my-svg [data-look="neo"].node polygon{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node path{stroke:url(#my-svg-gradient);stroke-width:1px;}#my-svg [data-look="neo"].node .outer-path{filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node .neo-line path{stroke:#999;filter:none;}#my-svg [data-look="neo"].node circle{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].node circle .state-start{fill:#000000;}#my-svg [data-look="neo"].icon-shape .icon{fill:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg [data-look="neo"].icon-shape .icon-neo path{stroke:url(#my-svg-gradient);filter:drop-shadow( 1px 2px 2px rgba(185,185,185,1));}#my-svg :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}<g><marker id="my-svg_flowchart-v2-pointEnd" class="marker flowchart-v2" viewBox="0 0 10 10" refX="5" refY="5" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-pointStart" class="marker flowchart-v2" viewBox="0 0 10 10" refX="4.5" refY="5" markerUnits="userSpaceOnUse" markerWidth="8" markerHeight="8" orient="auto"><path d="M 0 5 L 10 10 L 10 0 z" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-pointEnd-margin" class="marker flowchart-v2" viewBox="0 0 11.5 14" refX="11.5" refY="7" markerUnits="userSpaceOnUse" markerWidth="10.5" markerHeight="14" orient="auto"><path d="M 0 0 L 11.5 7 L 0 14 z" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-pointStart-margin" class="marker flowchart-v2" viewBox="0 0 11.5 14" refX="1" refY="7" markerUnits="userSpaceOnUse" markerWidth="11.5" markerHeight="14" orient="auto"><polygon points="0,7 11.5,14 11.5,0" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></polygon></marker><marker id="my-svg_flowchart-v2-circleEnd" class="marker flowchart-v2" viewBox="0 0 10 10" refX="11" refY="5" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-circleStart" class="marker flowchart-v2" viewBox="0 0 10 10" refX="-1" refY="5" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 1; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-circleEnd-margin" class="marker flowchart-v2" viewBox="0 0 10 10" refY="5" refX="12.25" markerUnits="userSpaceOnUse" markerWidth="14" markerHeight="14" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-circleStart-margin" class="marker flowchart-v2" viewBox="0 0 10 10" refX="-2" refY="5" markerUnits="userSpaceOnUse" markerWidth="14" markerHeight="14" orient="auto"><circle cx="5" cy="5" r="5" class="arrowMarkerPath" style="stroke-width: 0; stroke-dasharray: 1, 0;"></circle></marker><marker id="my-svg_flowchart-v2-crossEnd" class="marker cross flowchart-v2" viewBox="0 0 11 11" refX="12" refY="5.2" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><path d="M 1,1 l 9,9 M 10,1 l -9,9" class="arrowMarkerPath" style="stroke-width: 2; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-crossStart" class="marker cross flowchart-v2" viewBox="0 0 11 11" refX="-1" refY="5.2" markerUnits="userSpaceOnUse" markerWidth="11" markerHeight="11" orient="auto"><path d="M 1,1 l 9,9 M 10,1 l -9,9" class="arrowMarkerPath" style="stroke-width: 2; stroke-dasharray: 1, 0;"></path></marker><marker id="my-svg_flowchart-v2-crossEnd-margin" class="marker cross flowchart-v2" viewBox="0 0 15 15" refX="17.7" refY="7.5" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto"><path d="M 1,1 L 14,14 M 1,14 L 14,1" class="arrowMarkerPath" style="stroke-width: 2.5;"></path></marker><marker id="my-svg_flowchart-v2-crossStart-margin" class="marker cross flowchart-v2" viewBox="0 0 15 15" refX="-3.5" refY="7.5" markerUnits="userSpaceOnUse" markerWidth="12" markerHeight="12" orient="auto"><path d="M 1,1 L 14,14 M 1,14 L 14,1" class="arrowMarkerPath" style="stroke-width: 2.5; stroke-dasharray: 1, 0;"></path></marker><g class="root"><g class="clusters"></g><g class="edgePaths"><path d="M231.297,50.1L240.193,50.1C249.089,50.1,266.88,50.1,284.005,50.1C301.13,50.1,317.589,50.1,325.818,50.1L334.047,50.1" id="my-svg-L_WT_AA_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path><path d="M596,50.1L615.043,50.1C634.086,50.1,672.172,50.1,709.591,50.1C747.01,50.1,783.763,50.1,802.139,50.1L820.516,50.1" id="my-svg-L_AA_MA_0" class="edge-thickness-normal edge-pattern-solid edge-thickness-normal edge-pattern-solid flowchart-link" style=";" marker-end="url(#my-svg_flowchart-v2-pointEnd)"></path></g><g class="edgeLabels"><g class="edgeLabel" transform="translate(284.671875, 50.099998474121094)"><g class="label" transform="translate(0, -10.5)"><g><rect class="background" style="" x="-28.375" y="-1" width="56.75" height="23"></rect><text y="-10.1" text-anchor="middle" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"><tspan class="text-inner-tspan">harvest</tspan></tspan></text></g></g></g><g class="edgeLabel" transform="translate(710.2578125, 50.099998474121094)"><g class="label" transform="translate(0, -10.5)"><g><rect class="background" style="" x="-89.2578125" y="-1" width="178.515625" height="23"></rect><text y="-10.1" text-anchor="middle" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em" text-anchor="middle"><tspan class="text-inner-tspan">recover</tspan><tspan class="text-inner-tspan"> (worktree</tspan><tspan class="text-inner-tspan"> gone)</tspan></tspan></text></g></g></g></g><g class="nodes"><g class="node default" id="my-svg-flowchart-WT-0" transform="translate(119.6484375, 50.099998474121094)"><rect class="basic label-container" style="" x="-111.6484375" y="-33.29999923706055" width="223.296875" height="66.5999984741211"></rect><g class="label" style="" transform="translate(0, -18.299999237060547)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">worktree</tspan><tspan class="text-inner-tspan"> ledger</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">.scaffold/activity.jsonl</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-AA-1" transform="translate(467.0234375, 50.099998474121094)"><rect class="basic label-container" style="" x="-128.9765625" y="-42.099998474121094" width="257.953125" height="84.19999694824219"></rect><g class="label" style="" transform="translate(0, -27.099998474121094)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">active-archive</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">activity-archive/active/id.j</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="2.1em"><tspan class="text-inner-tspan">sonl</tspan></tspan></text></g></g></g><g class="node default" id="my-svg-flowchart-MA-3" transform="translate(952.2265625, 50.099998474121094)"><rect class="basic label-container" style="" x="-127.7109375" y="-42.099998474121094" width="255.421875" height="84.19999694824219"></rect><g class="label" style="" transform="translate(0, -27.099998474121094)"><rect></rect><g><rect class="background" style="stroke: none"></rect><text y="-10.1" style=""><tspan class="text-outer-tspan row" x="0" y="-0.1em"><tspan class="text-inner-tspan">monthly</tspan><tspan class="text-inner-tspan"> archive</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="1em"><tspan class="text-inner-tspan">activity-archive/YYYY-MM.j</tspan></tspan><tspan class="text-outer-tspan row" x="0" y="2.1em"><tspan class="text-inner-tspan">sonl</tspan></tspan></text></g></g></g></g></g></g><defs></defs><defs></defs></svg></figure>
|
|
2487
|
+
<h3 id="commands">Commands</h3>
|
|
2488
|
+
<ul>
|
|
2489
|
+
<li><strong><code>scaffold observe harvest --worktree=<path></code></strong> — read the worktree's
|
|
2490
|
+
<code>identity.json</code>, then copy its <code>activity.jsonl</code> to
|
|
2491
|
+
<code>.scaffold/activity-archive/active/<worktree_id>.jsonl</code> in the primary repo
|
|
2492
|
+
(atomic temp-file + rename under a lock; keyed by <code>worktree_id</code>, idempotent
|
|
2493
|
+
full-file replace). Requires the primary root to be a real repo, not itself a
|
|
2494
|
+
worktree.</li>
|
|
2495
|
+
<li><strong><code>scaffold observe harvest --recover</code></strong> — list live worktrees
|
|
2496
|
+
(<code>git worktree list --porcelain</code>), read each one's <code>worktree_id</code>, then scan
|
|
2497
|
+
<code>active/</code> for entries whose worktree is no longer live and rotate each into
|
|
2498
|
+
<code>activity-archive/<YYYY-MM>.jsonl</code> (bucketed by the file's mtime), deleting the
|
|
2499
|
+
active entry. Returns the rotated ids.</li>
|
|
2500
|
+
<li><strong><code>scripts/teardown-agent-worktree.sh <path></code></strong> — derives the primary repo via
|
|
2501
|
+
<code>git -C <path> rev-parse --git-common-dir</code> (so it works from anywhere),
|
|
2502
|
+
harvests (fail-soft), runs <code>git worktree remove</code>, then deletes the workspace
|
|
2503
|
+
branch if it differs from the primary HEAD.</li>
|
|
2504
|
+
</ul>
|
|
2505
|
+
<div class="callout callout-note"><p><strong>Empty ledgers are fine.</strong> If a worktree never wrote an <code>activity.jsonl</code>,
|
|
2506
|
+
harvest is a clean no-op and teardown proceeds.</p></div>
|
|
2507
|
+
<h2 id="renderers">Renderers</h2>
|
|
2508
|
+
<p>One <code>EngineOutput</code>, several surfaces. The terminal renderer is for humans at a
|
|
2509
|
+
prompt; the markdown renderer writes a durable report plus a machine-readable
|
|
2510
|
+
JSON sidecar; the dashboard-fragment renderer emits an HTML panel that
|
|
2511
|
+
<code>scripts/generate-dashboard.sh</code> injects at named anchors.</p>
|
|
2512
|
+
<p>Default audit/progress runs write both a markdown report and a JSON sidecar:
|
|
2513
|
+
audits to <code>docs/audits/<id>.{md,json}</code>, progress to
|
|
2514
|
+
<code>docs/build-status/<id>.{md,json}</code> (<code>src/observability/renderers/sidecar.ts</code>).
|
|
2515
|
+
<code>--render</code> and <code>--output-mode</code> bypass the files and print to stdout instead.</p>
|
|
2516
|
+
<p>The same blocked audit renders three ways. As terminal ANSI:</p>
|
|
2517
|
+
<pre><code class="language-text">build observability — audit
|
|
2518
|
+
(profile: fast · scope: all)
|
|
2519
|
+
|
|
2520
|
+
[P0] AC has failing test
|
|
2521
|
+
lens: B-ac-coverage
|
|
2522
|
+
fix: Re-enable the test
|
|
2523
|
+
|
|
2524
|
+
verdict: blocked
|
|
2525
|
+
(blocking 1 · ack 0 · total 1)
|
|
2526
|
+
</code></pre>
|
|
2527
|
+
<p>As markdown (<code>docs/audits/<id>.md</code>):</p>
|
|
2528
|
+
<pre><code class="language-text"># Build Observability — Audit
|
|
2529
|
+
|
|
2530
|
+
**Verdict:** blocked
|
|
2531
|
+
|
|
2532
|
+
## Summary
|
|
2533
|
+
1 findings · 1 blocking (at or above P2) · 0 acknowledged · 0 skipped lenses
|
|
2534
|
+
|
|
2535
|
+
### [P0] B-ac-coverage — AC has failing test
|
|
2536
|
+
`3a8c1f02` · *source:* `…#user-auth-1` · *confidence:* high
|
|
2537
|
+
</code></pre>
|
|
2538
|
+
<p>As a dashboard fragment, an HTML <code><section id="build-audit" data-verdict="blocked"></code>
|
|
2539
|
+
panel injected into the dashboard.</p>
|
|
2540
|
+
|
|
2541
|
+
|
|
2542
|
+
|
|
2543
|
+
|
|
2544
|
+
|
|
2545
|
+
|
|
2546
|
+
|
|
2547
|
+
|
|
2548
|
+
|
|
2549
|
+
|
|
2550
|
+
|
|
2551
|
+
|
|
2552
|
+
|
|
2553
|
+
|
|
2554
|
+
|
|
2555
|
+
|
|
2556
|
+
|
|
2557
|
+
|
|
2558
|
+
|
|
2559
|
+
|
|
2560
|
+
|
|
2561
|
+
|
|
2562
|
+
|
|
2563
|
+
|
|
2564
|
+
|
|
2565
|
+
|
|
2566
|
+
|
|
2567
|
+
|
|
2568
|
+
|
|
2569
|
+
|
|
2570
|
+
|
|
2571
|
+
|
|
2572
|
+
|
|
2573
|
+
|
|
2574
|
+
|
|
2575
|
+
|
|
2576
|
+
|
|
2577
|
+
|
|
2578
|
+
|
|
2579
|
+
|
|
2580
|
+
|
|
2581
|
+
<table><thead><tr><th>renderer</th><th>file</th><th>destination</th><th>notes</th></tr></thead><tbody><tr><td>terminal</td><td><code>src/observability/renderers/terminal.ts</code></td><td>stdout</td><td>ANSI, "Needs Attention" banner + timeline</td></tr><tr><td>markdown</td><td><code>src/observability/renderers/markdown.ts</code></td><td><code>docs/audits/</code> · <code>docs/build-status/</code></td><td>full findings, evidence, fix hints</td></tr><tr><td>sidecar JSON</td><td><code>src/observability/renderers/sidecar.ts</code></td><td>alongside the markdown</td><td>redacted <code>EngineOutput</code>; read by the <code>audit_history</code> adapter</td></tr><tr><td>dashboard fragment</td><td><code>src/observability/renderers/dashboard.ts</code></td><td>stdout → dashboard</td><td>sections <code>build-progress</code> / <code>build-audit</code> injected by <code>scripts/generate-dashboard.sh</code></td></tr><tr><td>mmr-findings</td><td><code>src/observability/renderers/mmr-findings.ts</code></td><td>stdout</td><td>MMR Finding shape</td></tr></tbody></table>
|
|
2582
|
+
<h2 id="config-reference">Config reference</h2>
|
|
2583
|
+
<p>All tunables live in <code>.scaffold/observability.yaml</code>. The file is optional — when
|
|
2584
|
+
absent, <code>DEFAULT_CONFIG</code> applies wholesale
|
|
2585
|
+
(<code>src/observability/engine/checks/observability-config.ts</code>). A malformed or
|
|
2586
|
+
unreadable file <em>silently</em> falls back to defaults. Merging is a deep merge where
|
|
2587
|
+
objects merge key-by-key but <strong>arrays and scalars replace wholesale</strong> — so
|
|
2588
|
+
setting <code>disabled_lenses</code> or <code>rule_overrides</code> overwrites the default rather than
|
|
2589
|
+
extending it.</p>
|
|
2590
|
+
<div class="callout callout-warning"><p><strong>The shipped example file is misleading.</strong> The repo's
|
|
2591
|
+
<code>.scaffold/observability.yaml</code> contains only <code>knowledge_freshness.link_check.skip</code>
|
|
2592
|
+
and a comment claiming "other observability features read configuration from
|
|
2593
|
+
elsewhere." In fact the code reads many more keys — the example file simply omits
|
|
2594
|
+
them because they all have working defaults. The defaults documented here come
|
|
2595
|
+
from the code, which is ground truth.</p></div>
|
|
2596
|
+
<div class="filter-table"><input type="text" class="filter-input" placeholder="Filter…" aria-label="Filter table rows" disabled>
|
|
2597
|
+
|
|
2598
|
+
|
|
2599
|
+
|
|
2600
|
+
|
|
2601
|
+
|
|
2602
|
+
|
|
2603
|
+
|
|
2604
|
+
|
|
2605
|
+
|
|
2606
|
+
|
|
2607
|
+
|
|
2608
|
+
|
|
2609
|
+
|
|
2610
|
+
|
|
2611
|
+
|
|
2612
|
+
|
|
2613
|
+
|
|
2614
|
+
|
|
2615
|
+
|
|
2616
|
+
|
|
2617
|
+
|
|
2618
|
+
|
|
2619
|
+
|
|
2620
|
+
|
|
2621
|
+
|
|
2622
|
+
|
|
2623
|
+
|
|
2624
|
+
|
|
2625
|
+
|
|
2626
|
+
|
|
2627
|
+
|
|
2628
|
+
|
|
2629
|
+
|
|
2630
|
+
|
|
2631
|
+
|
|
2632
|
+
|
|
2633
|
+
|
|
2634
|
+
|
|
2635
|
+
|
|
2636
|
+
|
|
2637
|
+
|
|
2638
|
+
|
|
2639
|
+
|
|
2640
|
+
|
|
2641
|
+
|
|
2642
|
+
|
|
2643
|
+
|
|
2644
|
+
|
|
2645
|
+
|
|
2646
|
+
|
|
2647
|
+
|
|
2648
|
+
|
|
2649
|
+
|
|
2650
|
+
|
|
2651
|
+
|
|
2652
|
+
|
|
2653
|
+
|
|
2654
|
+
|
|
2655
|
+
|
|
2656
|
+
|
|
2657
|
+
|
|
2658
|
+
|
|
2659
|
+
|
|
2660
|
+
|
|
2661
|
+
|
|
2662
|
+
|
|
2663
|
+
|
|
2664
|
+
|
|
2665
|
+
|
|
2666
|
+
|
|
2667
|
+
|
|
2668
|
+
|
|
2669
|
+
|
|
2670
|
+
|
|
2671
|
+
|
|
2672
|
+
|
|
2673
|
+
|
|
2674
|
+
|
|
2675
|
+
|
|
2676
|
+
|
|
2677
|
+
|
|
2678
|
+
|
|
2679
|
+
|
|
2680
|
+
|
|
2681
|
+
|
|
2682
|
+
|
|
2683
|
+
|
|
2684
|
+
|
|
2685
|
+
|
|
2686
|
+
|
|
2687
|
+
|
|
2688
|
+
|
|
2689
|
+
|
|
2690
|
+
|
|
2691
|
+
|
|
2692
|
+
|
|
2693
|
+
|
|
2694
|
+
|
|
2695
|
+
|
|
2696
|
+
|
|
2697
|
+
|
|
2698
|
+
|
|
2699
|
+
|
|
2700
|
+
|
|
2701
|
+
|
|
2702
|
+
|
|
2703
|
+
|
|
2704
|
+
|
|
2705
|
+
|
|
2706
|
+
|
|
2707
|
+
|
|
2708
|
+
|
|
2709
|
+
|
|
2710
|
+
|
|
2711
|
+
|
|
2712
|
+
|
|
2713
|
+
|
|
2714
|
+
|
|
2715
|
+
|
|
2716
|
+
|
|
2717
|
+
|
|
2718
|
+
|
|
2719
|
+
|
|
2720
|
+
|
|
2721
|
+
|
|
2722
|
+
|
|
2723
|
+
|
|
2724
|
+
|
|
2725
|
+
|
|
2726
|
+
|
|
2727
|
+
|
|
2728
|
+
|
|
2729
|
+
|
|
2730
|
+
|
|
2731
|
+
|
|
2732
|
+
|
|
2733
|
+
|
|
2734
|
+
|
|
2735
|
+
|
|
2736
|
+
|
|
2737
|
+
|
|
2738
|
+
|
|
2739
|
+
|
|
2740
|
+
|
|
2741
|
+
|
|
2742
|
+
|
|
2743
|
+
|
|
2744
|
+
|
|
2745
|
+
|
|
2746
|
+
|
|
2747
|
+
|
|
2748
|
+
|
|
2749
|
+
|
|
2750
|
+
|
|
2751
|
+
|
|
2752
|
+
|
|
2753
|
+
|
|
2754
|
+
|
|
2755
|
+
|
|
2756
|
+
|
|
2757
|
+
<table><thead><tr><th>key</th><th>type</th><th>default</th><th>read by</th></tr></thead><tbody><tr><td><code>lenses.C-standards.enforce_via_linter</code></td><td>boolean</td><td><code>true</code></td><td>(accepted, not read)</td></tr><tr><td><code>lenses.C-standards.rule_overrides</code></td><td>map<rule, P0–P3></td><td><code>{}</code></td><td>lenses · Lens C</td></tr><tr><td><code>lenses.C-standards.escalation_threshold</code></td><td>number</td><td><code>5</code></td><td>lenses · Lens C</td></tr><tr><td><code>lenses.D-stack.path_to_layer</code></td><td>{glob,layer}[]</td><td>7 default mappings</td><td>lenses · Lens D</td></tr><tr><td><code>lenses.E-design.ad_hoc_token_threshold</code></td><td>number</td><td><code>3</code></td><td>lenses · Lens E</td></tr><tr><td><code>lenses.E-design.ui_glob</code></td><td>glob</td><td><code>src/components/**/*.tsx</code></td><td>lenses · doc-graph builder</td></tr><tr><td><code>lenses.F-scope.untouched_story_grace_hours</code></td><td>number</td><td><code>168</code></td><td>lenses · Lens F</td></tr><tr><td><code>lenses.G-decisions.keywords_file</code></td><td>path</td><td>— (inert)</td><td>lenses · (no reader)</td></tr><tr><td><code>lenses.H-cross-doc.skip_phase_subsets</code></td><td>string[]</td><td>— (inert)</td><td>lenses · (no reader)</td></tr><tr><td><code>lenses.I-knowledge-gaps.knowledge_root</code></td><td>path</td><td>auto-detect</td><td>lenses · Lens I</td></tr><tr><td><code>disabled_lenses</code></td><td>string[]</td><td><code>[]</code></td><td>lenses · runner</td></tr><tr><td><code>phase_audit.enabled</code></td><td>boolean</td><td><code>true</code></td><td>phase_audit</td></tr><tr><td><code>phase_audit.timeout_s</code></td><td>number</td><td><code>60</code></td><td>phase_audit</td></tr><tr><td><code>phase_audit.detached</code></td><td>boolean</td><td><code>false</code></td><td>phase_audit</td></tr><tr><td><code>stall.task_stale</code></td><td>'Nh'·'Nd'·'off'</td><td><code>4h</code></td><td>stall</td></tr><tr><td><code>stall.pr_stale</code></td><td>'Nh'·'Nd'·'off'</td><td><code>48h</code></td><td>stall</td></tr><tr><td><code>stall.pr_review_stale</code></td><td>'Nh'·'Nd'·'off'</td><td><code>24h</code> (reserved)</td><td>stall (signal not yet emitted)</td></tr><tr><td><code>stall.blocker_unaddressed</code></td><td>'Nh'·'Nd'·'off'</td><td><code>2h</code></td><td>stall</td></tr><tr><td><code>stall.audit_findings_unresolved</code></td><td>'Nh'·'Nd'·'off'</td><td><code>24h</code></td><td>stall</td></tr><tr><td><code>llm.timeout_s</code></td><td>number</td><td><code>60</code></td><td>llm · Lens H dispatcher</td></tr><tr><td><code>llm.parallel_checks</code></td><td>boolean</td><td><code>false</code></td><td>llm · Lens H</td></tr><tr><td><code>fix.dispatcher_command</code></td><td>shell command</td><td><code>claude -p</code></td><td>fix · dispatcher</td></tr><tr><td><code>fix.timeout_s</code></td><td>number</td><td><code>300</code></td><td>fix</td></tr><tr><td><code>fix.per_finding_max_attempts</code></td><td>number</td><td><code>3</code></td><td>fix</td></tr><tr><td><code>knowledge_freshness.link_check.skip</code></td><td>string[]</td><td><code>[]</code></td><td>knowledge-freshness (separate loader)</td></tr></tbody></table></div>
|
|
2758
|
+
<div class="callout callout-note"><p><strong>No <code>llm.dispatcher_command</code>, no <code>F-scope.wave_budget</code>.</strong> Two keys you might
|
|
2759
|
+
expect are deliberately absent. The Lens H LLM command is hard-coded (security) —
|
|
2760
|
+
there is no <code>llm.dispatcher_command</code> key. And there is no wave/phase-budget key at
|
|
2761
|
+
all: <code>F-scope</code> reads only <code>untouched_story_grace_hours</code> from this file, so the
|
|
2762
|
+
"wave budget" CLAUDE.md implies does not exist in the config.</p></div>
|
|
2763
|
+
<p>Example:</p>
|
|
2764
|
+
<pre><code class="language-yaml">lenses:
|
|
2765
|
+
C-standards:
|
|
2766
|
+
enforce_via_linter: true
|
|
2767
|
+
rule_overrides:
|
|
2768
|
+
no-console: P1
|
|
2769
|
+
E-design:
|
|
2770
|
+
ad_hoc_token_threshold: 5
|
|
2771
|
+
disabled_lenses: []
|
|
2772
|
+
phase_audit:
|
|
2773
|
+
enabled: true
|
|
2774
|
+
timeout_s: 60
|
|
2775
|
+
stall:
|
|
2776
|
+
task_stale: '6h'
|
|
2777
|
+
fix:
|
|
2778
|
+
per_finding_max_attempts: 3
|
|
2779
|
+
# shared with the knowledge-freshness subsystem
|
|
2780
|
+
knowledge_freshness:
|
|
2781
|
+
link_check:
|
|
2782
|
+
skip:
|
|
2783
|
+
- platform.openai.com
|
|
2784
|
+
</code></pre>
|
|
2785
|
+
<h2 id="where-it-lives">Where it lives</h2>
|
|
2786
|
+
<p>The whole system lives under <code>src/observability/</code>, plus the state-manager hook
|
|
2787
|
+
and two shell scripts.</p>
|
|
2788
|
+
|
|
2789
|
+
|
|
2790
|
+
|
|
2791
|
+
|
|
2792
|
+
|
|
2793
|
+
|
|
2794
|
+
|
|
2795
|
+
|
|
2796
|
+
|
|
2797
|
+
|
|
2798
|
+
|
|
2799
|
+
|
|
2800
|
+
|
|
2801
|
+
|
|
2802
|
+
|
|
2803
|
+
|
|
2804
|
+
|
|
2805
|
+
|
|
2806
|
+
|
|
2807
|
+
|
|
2808
|
+
|
|
2809
|
+
|
|
2810
|
+
|
|
2811
|
+
|
|
2812
|
+
|
|
2813
|
+
|
|
2814
|
+
|
|
2815
|
+
|
|
2816
|
+
|
|
2817
|
+
|
|
2818
|
+
|
|
2819
|
+
|
|
2820
|
+
|
|
2821
|
+
|
|
2822
|
+
|
|
2823
|
+
|
|
2824
|
+
|
|
2825
|
+
|
|
2826
|
+
|
|
2827
|
+
|
|
2828
|
+
|
|
2829
|
+
|
|
2830
|
+
|
|
2831
|
+
|
|
2832
|
+
|
|
2833
|
+
|
|
2834
|
+
|
|
2835
|
+
|
|
2836
|
+
|
|
2837
|
+
|
|
2838
|
+
|
|
2839
|
+
|
|
2840
|
+
|
|
2841
|
+
|
|
2842
|
+
|
|
2843
|
+
|
|
2844
|
+
|
|
2845
|
+
|
|
2846
|
+
|
|
2847
|
+
|
|
2848
|
+
|
|
2849
|
+
|
|
2850
|
+
|
|
2851
|
+
|
|
2852
|
+
|
|
2853
|
+
|
|
2854
|
+
|
|
2855
|
+
|
|
2856
|
+
|
|
2857
|
+
|
|
2858
|
+
|
|
2859
|
+
|
|
2860
|
+
|
|
2861
|
+
|
|
2862
|
+
|
|
2863
|
+
|
|
2864
|
+
|
|
2865
|
+
|
|
2866
|
+
|
|
2867
|
+
|
|
2868
|
+
|
|
2869
|
+
|
|
2870
|
+
|
|
2871
|
+
|
|
2872
|
+
|
|
2873
|
+
|
|
2874
|
+
|
|
2875
|
+
|
|
2876
|
+
|
|
2877
|
+
|
|
2878
|
+
|
|
2879
|
+
|
|
2880
|
+
|
|
2881
|
+
|
|
2882
|
+
|
|
2883
|
+
|
|
2884
|
+
|
|
2885
|
+
|
|
2886
|
+
|
|
2887
|
+
|
|
2888
|
+
|
|
2889
|
+
|
|
2890
|
+
|
|
2891
|
+
|
|
2892
|
+
|
|
2893
|
+
|
|
2894
|
+
|
|
2895
|
+
|
|
2896
|
+
|
|
2897
|
+
|
|
2898
|
+
|
|
2899
|
+
|
|
2900
|
+
|
|
2901
|
+
|
|
2902
|
+
|
|
2903
|
+
|
|
2904
|
+
|
|
2905
|
+
|
|
2906
|
+
|
|
2907
|
+
|
|
2908
|
+
|
|
2909
|
+
|
|
2910
|
+
|
|
2911
|
+
|
|
2912
|
+
|
|
2913
|
+
|
|
2914
|
+
|
|
2915
|
+
|
|
2916
|
+
|
|
2917
|
+
|
|
2918
|
+
|
|
2919
|
+
|
|
2920
|
+
|
|
2921
|
+
|
|
2922
|
+
|
|
2923
|
+
|
|
2924
|
+
|
|
2925
|
+
|
|
2926
|
+
|
|
2927
|
+
|
|
2928
|
+
|
|
2929
|
+
|
|
2930
|
+
|
|
2931
|
+
|
|
2932
|
+
|
|
2933
|
+
|
|
2934
|
+
|
|
2935
|
+
|
|
2936
|
+
|
|
2937
|
+
|
|
2938
|
+
|
|
2939
|
+
|
|
2940
|
+
|
|
2941
|
+
|
|
2942
|
+
|
|
2943
|
+
|
|
2944
|
+
|
|
2945
|
+
|
|
2946
|
+
|
|
2947
|
+
|
|
2948
|
+
|
|
2949
|
+
|
|
2950
|
+
|
|
2951
|
+
|
|
2952
|
+
|
|
2953
|
+
|
|
2954
|
+
|
|
2955
|
+
|
|
2956
|
+
|
|
2957
|
+
<table><thead><tr><th>file</th><th>purpose</th></tr></thead><tbody><tr><td><code>src/observability/engine/ledger-writer.ts</code></td><td>validate → redact → 4 KiB check → locked append</td></tr><tr><td><code>src/observability/engine/event-schemas.ts</code></td><td>per-type payload allow-lists + validation</td></tr><tr><td><code>src/observability/engine/redact.ts</code></td><td>write-time + render-time secret/path scrubbing</td></tr><tr><td><code>src/observability/engine/identity.ts</code></td><td>worktree identity.json</td></tr><tr><td><code>src/observability/engine/harvester.ts</code></td><td>harvest worktree ledger + <code>--recover</code> rotation</td></tr><tr><td><code>src/observability/engine/synthesizer.ts</code></td><td>composeReplay: fuse + correlation_id dedup + source priority</td></tr><tr><td><code>src/observability/engine/api.ts</code></td><td>runAudit / runProgress; scope→lens; verdict</td></tr><tr><td><code>src/observability/engine/stall.ts</code></td><td>the stall signals + Needs-Attention surface</td></tr><tr><td><code>src/observability/engine/phase-audit.ts</code></td><td>runPhaseAudit + formatPhaseAuditLine</td></tr><tr><td><code>src/observability/engine/phase-subsets.ts</code></td><td>PHASE_BOUNDARY_STEPS + isPhaseBoundary</td></tr><tr><td><code>src/observability/engine/fix-flow.ts</code></td><td>the five-phase <code>--fix</code> loop</td></tr><tr><td><code>src/observability/engine/fix-plan.ts</code></td><td>buildFixPlan: filter + order findings</td></tr><tr><td><code>src/observability/engine/fix-agent-dispatcher.ts</code></td><td>configurable subprocess fix dispatcher</td></tr><tr><td><code>src/observability/engine/abort-snapshot.ts</code></td><td>capture/restore git stash on SIGINT</td></tr><tr><td><code>src/observability/engine/llm-dispatcher.ts</code></td><td>hard-coded <code>claude -p</code> for Lens H full profile</td></tr><tr><td><code>src/observability/engine/types.ts</code></td><td>Verdict, AdapterId, EngineOutput, Finding</td></tr><tr><td><code>src/observability/engine/checks/registry.ts</code></td><td>LENS_REGISTRY (A–I) + implementations</td></tr><tr><td><code>src/observability/engine/checks/fix-threshold.ts</code></td><td>resolve fix_threshold (default P2)</td></tr><tr><td><code>src/observability/engine/checks/findings-aggregator.ts</code></td><td>tally blocking/acked; compute verdict</td></tr><tr><td><code>src/observability/engine/checks/observability-config.ts</code></td><td>DEFAULT_CONFIG + deep-merge loader</td></tr><tr><td><code>src/observability/engine/doc-graph/index.ts</code></td><td>build the doc graph from planning docs</td></tr><tr><td><code>src/observability/checks/lens-a-tdd.ts</code></td><td>A · skipped tests</td></tr><tr><td><code>src/observability/checks/lens-b-ac-coverage.ts</code></td><td>B · AC ↔ test coverage</td></tr><tr><td><code>src/observability/checks/lens-c-standards.ts</code></td><td>C · coding-standards drift</td></tr><tr><td><code>src/observability/checks/lens-d-stack.ts</code></td><td>D · tech-stack drift</td></tr><tr><td><code>src/observability/checks/lens-e-design.ts</code></td><td>E · design-system drift</td></tr><tr><td><code>src/observability/checks/lens-f-scope.ts</code></td><td>F · missing scope</td></tr><tr><td><code>src/observability/checks/lens-g-decisions.ts</code></td><td>G · undocumented decisions</td></tr><tr><td><code>src/observability/checks/lens-h-cross-doc.ts</code></td><td>H · cross-doc consistency + LLM checks</td></tr><tr><td><code>src/observability/checks/lens-i-knowledge-gaps.ts</code></td><td>I · knowledge gaps</td></tr><tr><td><code>src/observability/checks/lens-i-lessons-scanner.ts</code></td><td>scan tasks/lessons.md for gap signals</td></tr><tr><td><code>src/observability/knowledge-index.ts</code></td><td>resolveKnowledgeRoot (3 tiers) + index for Lens I</td></tr><tr><td><code>src/observability/renderers/terminal.ts</code></td><td>ANSI output</td></tr><tr><td><code>src/observability/renderers/markdown.ts</code></td><td>markdown report</td></tr><tr><td><code>src/observability/renderers/dashboard.ts</code></td><td>build-progress / build-audit HTML fragments</td></tr><tr><td><code>src/observability/renderers/sidecar.ts</code></td><td>JSON sidecar + report-id derivation</td></tr><tr><td><code>src/observability/renderers/mmr-findings.ts</code></td><td>MMR Finding shape</td></tr><tr><td><code>src/state/state-manager.ts</code></td><td>async markCompleted → runPhaseAudit hook</td></tr><tr><td><code>scripts/teardown-agent-worktree.sh</code></td><td>harvest → remove → delete branch</td></tr><tr><td><code>scripts/generate-dashboard.sh</code></td><td>injects the dashboard fragments</td></tr></tbody></table>
|
|
2958
|
+
<p>The full design lives in
|
|
2959
|
+
<code>docs/superpowers/specs/2026-04-30-build-observability-design.md</code>.</p>
|
|
2960
|
+
<h2 id="shipping-history">Shipping history</h2>
|
|
2961
|
+
<p>Build Observability shipped as eight plans (Foundation → Fix-flow), released
|
|
2962
|
+
together as <code>v3.26.0 — Build Observability</code> on 2026-05-07, with Lens I and
|
|
2963
|
+
refinements following after.</p>
|
|
2964
|
+
<div class="filter-table"><input type="text" class="filter-input" placeholder="Filter…" aria-label="Filter table rows" disabled>
|
|
2965
|
+
|
|
2966
|
+
|
|
2967
|
+
|
|
2968
|
+
|
|
2969
|
+
|
|
2970
|
+
|
|
2971
|
+
|
|
2972
|
+
|
|
2973
|
+
|
|
2974
|
+
|
|
2975
|
+
|
|
2976
|
+
|
|
2977
|
+
|
|
2978
|
+
|
|
2979
|
+
|
|
2980
|
+
|
|
2981
|
+
|
|
2982
|
+
|
|
2983
|
+
|
|
2984
|
+
|
|
2985
|
+
|
|
2986
|
+
|
|
2987
|
+
|
|
2988
|
+
|
|
2989
|
+
|
|
2990
|
+
|
|
2991
|
+
|
|
2992
|
+
|
|
2993
|
+
|
|
2994
|
+
|
|
2995
|
+
|
|
2996
|
+
|
|
2997
|
+
|
|
2998
|
+
|
|
2999
|
+
|
|
3000
|
+
|
|
3001
|
+
|
|
3002
|
+
|
|
3003
|
+
|
|
3004
|
+
|
|
3005
|
+
|
|
3006
|
+
|
|
3007
|
+
|
|
3008
|
+
|
|
3009
|
+
|
|
3010
|
+
|
|
3011
|
+
|
|
3012
|
+
|
|
3013
|
+
|
|
3014
|
+
|
|
3015
|
+
|
|
3016
|
+
|
|
3017
|
+
|
|
3018
|
+
|
|
3019
|
+
|
|
3020
|
+
|
|
3021
|
+
|
|
3022
|
+
|
|
3023
|
+
|
|
3024
|
+
|
|
3025
|
+
|
|
3026
|
+
|
|
3027
|
+
|
|
3028
|
+
|
|
3029
|
+
|
|
3030
|
+
|
|
3031
|
+
|
|
3032
|
+
|
|
3033
|
+
|
|
3034
|
+
|
|
3035
|
+
|
|
3036
|
+
|
|
3037
|
+
|
|
3038
|
+
|
|
3039
|
+
|
|
3040
|
+
|
|
3041
|
+
|
|
3042
|
+
|
|
3043
|
+
|
|
3044
|
+
|
|
3045
|
+
|
|
3046
|
+
|
|
3047
|
+
|
|
3048
|
+
|
|
3049
|
+
|
|
3050
|
+
|
|
3051
|
+
|
|
3052
|
+
|
|
3053
|
+
|
|
3054
|
+
|
|
3055
|
+
|
|
3056
|
+
|
|
3057
|
+
|
|
3058
|
+
|
|
3059
|
+
|
|
3060
|
+
<table><thead><tr><th>plan</th><th>subsystem</th><th>squash</th><th>PR</th><th>added to the on-disk surface</th></tr></thead><tbody><tr><td>spec + plans</td><td>design doc + 8 plans</td><td><code>5cf689c4</code></td><td>#319</td><td><code>docs/superpowers/specs</code> + 8 plan files</td></tr><tr><td>1 · Foundation</td><td>identity, validation, redaction, ledger, harvester, adapters, synthesizer, API, CLI, renderers</td><td><code>21124010</code> (+ #320–328)</td><td>#320–329</td><td>most of <code>src/observability/engine</code>, <code>adapters</code>, <code>renderers</code>; <code>scaffold observe</code></td></tr><tr><td>2 · Audit MVP</td><td>doc-graph, checks framework, lenses A/B/H, <code>audit</code>+<code>ack</code></td><td><code>8eb70986</code></td><td>#331</td><td><code>engine/doc-graph</code>, <code>engine/checks</code>, <code>lens-a/b/h</code></td></tr><tr><td>3 · Full lens suite</td><td>lenses C/D/E/F/G + registry + config</td><td><code>bd014634</code></td><td>#332</td><td><code>lens-c…g</code>, <code>registry.ts</code>, <code>.scaffold/observability.yaml</code></td></tr><tr><td>4 · Renderers + history</td><td>markdown, JSON sidecars, dashboard fragments, audit-history</td><td><code>37f63ae4</code></td><td>#333</td><td><code>docs/build-status</code>, <code>docs/audits</code>, <code>audit-history</code> adapter</td></tr><tr><td>5 · Replay + stall</td><td>replay timeline, stall detection, Lens G keyword scan</td><td><code>cdbfd1de</code></td><td>#334</td><td><code>synthesizer.composeReplay</code>, <code>stall.ts</code>, Needs-Attention surfaces</td></tr><tr><td>6 · Phase triggers</td><td><code>markCompleted</code> async → <code>runPhaseAudit</code></td><td><code>ff04a1a6</code></td><td>#335</td><td><code>phase-audit.ts</code>, <code>phase-subsets.ts</code>, step timestamps</td></tr><tr><td>7 · MMR channel</td><td><code>doc-conformance</code> channel + Lens H full-profile LLM checks</td><td><code>8b723617</code></td><td>#336</td><td><code>mmr-findings.ts</code>, <code>llm-dispatcher.ts</code>, Lens H sub-checks</td></tr><tr><td>8 · Fix flow + teardown</td><td><code>--fix</code> loop, <code>harvest --recover</code>, teardown script</td><td><code>06fca3ef</code> (v3.26.0)</td><td>#337</td><td><code>fix-flow.ts</code>, <code>fix-plan.ts</code>, <code>fix-agent-dispatcher.ts</code>, <code>abort-snapshot.ts</code>, <code>teardown-agent-worktree.sh</code></td></tr><tr><td>follow-on</td><td>Lens I — knowledge gaps + lessons scanner</td><td><code>31e45f03</code></td><td>#397</td><td><code>lens-i-knowledge-gaps.ts</code>, <code>lens-i-lessons-scanner.ts</code></td></tr><tr><td>follow-on</td><td>Lens I — <code>--knowledge-root</code> + existing-entry suppression</td><td><code>46a47037</code></td><td>#406</td><td><code>knowledge-index.ts</code> resolver tiers</td></tr><tr><td>follow-on</td><td>TypeScript cleanup (<code>as never</code> → typed <code>isOneOf</code>)</td><td><code>362c7f93</code></td><td>#411</td><td>type-safety refactor across observability</td></tr></tbody></table></div>
|
|
3061
|
+
<h2 id="known-divergences">Known divergences</h2>
|
|
3062
|
+
<p>The audit's own rule — "code is ground truth where it disagrees with the spec or
|
|
3063
|
+
the docs" — surfaced these mismatches. They are deferred findings to resolve in
|
|
3064
|
+
the code/docs:</p>
|
|
3065
|
+
<ul>
|
|
3066
|
+
<li><strong>9 lenses, not 8.</strong> The design spec and CLAUDE.md enumerate A–H;
|
|
3067
|
+
<code>I-knowledge-gaps</code> shipped and is registered.</li>
|
|
3068
|
+
<li><strong><code>pr_opened</code> vs <code>pr_open</code>.</strong> CLAUDE.md abbreviates the event type as
|
|
3069
|
+
<code>pr_open</code>; the code only emits <code>pr_opened</code>.</li>
|
|
3070
|
+
<li><strong>Three engine verdicts, not four.</strong> <code>needs-user-decision</code> is an MMR review
|
|
3071
|
+
verdict; the audit engine emits only <code>pass</code> / <code>degraded-pass</code> / <code>blocked</code>.</li>
|
|
3072
|
+
<li><strong>Two dispatchers — don't conflate them.</strong> CLAUDE.md's "not
|
|
3073
|
+
project-config-overridable" note is about the <strong>Lens H LLM dispatcher</strong>
|
|
3074
|
+
(<code>llm-dispatcher.ts</code>, hard-coded <code>claude -p</code> by design). It does <strong>not</strong> apply
|
|
3075
|
+
to the separate <strong><code>--fix</code> agent dispatcher</strong>, whose <code>fix.dispatcher_command</code>
|
|
3076
|
+
<em>is</em> project-configurable. The divergence is that the two are easy to conflate.</li>
|
|
3077
|
+
<li><strong><code>pr_review_stale</code> reserved.</strong> The sixth stall signal has a config default but
|
|
3078
|
+
is not yet emitted (deferred pending a per-PR correlation_id on the mmr
|
|
3079
|
+
adapter).</li>
|
|
3080
|
+
<li><strong>Inert config keys.</strong> <code>lenses.G-decisions.keywords_file</code> and
|
|
3081
|
+
<code>lenses.H-cross-doc.skip_phase_subsets</code> are typed but unread; the bundled
|
|
3082
|
+
<code>decision-keywords.txt</code> is not loaded.</li>
|
|
3083
|
+
<li><strong>No <code>F-scope.wave_budget</code> key.</strong> CLAUDE.md implies a wave budget in
|
|
3084
|
+
<code>observability.yaml</code>; in fact no wave/phase budget is read anywhere — Lens F
|
|
3085
|
+
reads only <code>untouched_story_grace_hours</code>.</li>
|
|
3086
|
+
<li><strong><code>ui_glob</code> default narrower than spec.</strong> Spec default covers
|
|
3087
|
+
<code>{tsx,jsx,vue,svelte}</code> + styles; shipped default is just
|
|
3088
|
+
<code>src/components/**/*.tsx</code>.</li>
|
|
3089
|
+
</ul></main>
|
|
3090
|
+
<div class="rail-backdrop" data-action="nav" aria-hidden="true"></div>
|
|
3091
|
+
</div>
|
|
3092
|
+
<script>(function(){
|
|
3093
|
+
var LS_KEY = 'guide-theme';
|
|
3094
|
+
function applyTheme(t) {
|
|
3095
|
+
document.documentElement.setAttribute('data-theme', t);
|
|
3096
|
+
}
|
|
3097
|
+
|
|
3098
|
+
document.addEventListener('DOMContentLoaded', function() {
|
|
3099
|
+
// ─── Theme toggle ────────────────────────────────────────────────────────
|
|
3100
|
+
document.querySelectorAll('[data-action="theme"]').forEach(function(btn) {
|
|
3101
|
+
btn.addEventListener('click', function() {
|
|
3102
|
+
var current = document.documentElement.getAttribute('data-theme');
|
|
3103
|
+
var next = current === 'dark' ? 'light' : 'dark';
|
|
3104
|
+
applyTheme(next);
|
|
3105
|
+
try { localStorage.setItem(LS_KEY, next); } catch(e) {}
|
|
3106
|
+
});
|
|
3107
|
+
});
|
|
3108
|
+
|
|
3109
|
+
// ─── Mobile nav (drawer + backdrop; aria-expanded + Escape-to-close) ──────
|
|
3110
|
+
function setNav(open) {
|
|
3111
|
+
var rail = document.querySelector('.rail');
|
|
3112
|
+
if (rail) rail.classList.toggle('open', open);
|
|
3113
|
+
var toggle = document.querySelector('.nav-toggle');
|
|
3114
|
+
if (toggle) toggle.setAttribute('aria-expanded', open ? 'true' : 'false');
|
|
3115
|
+
// Modal-drawer focus containment: while open, make the page content inert
|
|
3116
|
+
// (out of tab order + a11y tree) and move focus into the drawer; on close,
|
|
3117
|
+
// restore content and return focus to the toggle.
|
|
3118
|
+
var main = document.querySelector('.content');
|
|
3119
|
+
if (main) main.inert = open;
|
|
3120
|
+
if (open) {
|
|
3121
|
+
var first = rail && rail.querySelector('a, button, [tabindex]:not([tabindex="-1"])');
|
|
3122
|
+
if (first) first.focus();
|
|
3123
|
+
else if (rail) { rail.setAttribute('tabindex', '-1'); rail.focus(); }
|
|
3124
|
+
} else if (toggle) {
|
|
3125
|
+
toggle.focus();
|
|
3126
|
+
}
|
|
3127
|
+
}
|
|
3128
|
+
// If the viewport grows past the mobile breakpoint while the drawer is open,
|
|
3129
|
+
// the rail becomes the desktop sidebar and the toggle hides — clear the open
|
|
3130
|
+
// state so .content doesn't stay inert with no way to close it.
|
|
3131
|
+
if (window.matchMedia) {
|
|
3132
|
+
var mq = window.matchMedia('(max-width: 860px)');
|
|
3133
|
+
var onMq = function() {
|
|
3134
|
+
if (mq.matches) return;
|
|
3135
|
+
var rail = document.querySelector('.rail');
|
|
3136
|
+
if (rail) rail.classList.remove('open');
|
|
3137
|
+
var toggle = document.querySelector('.nav-toggle');
|
|
3138
|
+
if (toggle) toggle.setAttribute('aria-expanded', 'false');
|
|
3139
|
+
var main = document.querySelector('.content');
|
|
3140
|
+
if (main) main.inert = false;
|
|
3141
|
+
};
|
|
3142
|
+
if (mq.addEventListener) mq.addEventListener('change', onMq);
|
|
3143
|
+
else if (mq.addListener) mq.addListener(onMq);
|
|
3144
|
+
}
|
|
3145
|
+
document.querySelectorAll('[data-action="nav"]').forEach(function(btn) {
|
|
3146
|
+
btn.addEventListener('click', function() {
|
|
3147
|
+
var rail = document.querySelector('.rail');
|
|
3148
|
+
setNav(!(rail && rail.classList.contains('open')));
|
|
3149
|
+
});
|
|
3150
|
+
});
|
|
3151
|
+
// Selecting a TOC link closes the drawer (so the now-active content isn't
|
|
3152
|
+
// left inert behind the panel) before the anchor navigation scrolls.
|
|
3153
|
+
var drawerRail = document.querySelector('.rail');
|
|
3154
|
+
if (drawerRail) {
|
|
3155
|
+
drawerRail.querySelectorAll('a').forEach(function(a) {
|
|
3156
|
+
a.addEventListener('click', function() {
|
|
3157
|
+
if (drawerRail.classList.contains('open')) setNav(false);
|
|
3158
|
+
});
|
|
3159
|
+
});
|
|
3160
|
+
}
|
|
3161
|
+
document.addEventListener('keydown', function(e) {
|
|
3162
|
+
var rail = document.querySelector('.rail');
|
|
3163
|
+
if (!rail || !rail.classList.contains('open')) return;
|
|
3164
|
+
if (e.key === 'Escape') { setNav(false); return; } // setNav restores focus to the toggle
|
|
3165
|
+
// Trap Tab within the open drawer (modal pattern).
|
|
3166
|
+
if (e.key !== 'Tab') return;
|
|
3167
|
+
var f = rail.querySelectorAll('a[href], button, [tabindex]:not([tabindex="-1"])');
|
|
3168
|
+
if (!f.length) return;
|
|
3169
|
+
var first = f[0], last = f[f.length - 1];
|
|
3170
|
+
if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
|
|
3171
|
+
else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
|
|
3172
|
+
});
|
|
3173
|
+
|
|
3174
|
+
// ─── Copy buttons ─────────────────────────────────────────────────────────
|
|
3175
|
+
document.querySelectorAll('pre').forEach(function(pre) {
|
|
3176
|
+
if (!pre.parentNode) return;
|
|
3177
|
+
var wrapper = document.createElement('div');
|
|
3178
|
+
wrapper.className = 'code';
|
|
3179
|
+
pre.parentNode.insertBefore(wrapper, pre);
|
|
3180
|
+
wrapper.appendChild(pre);
|
|
3181
|
+
var btn = document.createElement('button');
|
|
3182
|
+
btn.className = 'copy-btn';
|
|
3183
|
+
btn.textContent = 'Copy';
|
|
3184
|
+
btn.addEventListener('click', function() {
|
|
3185
|
+
var text = pre.textContent || '';
|
|
3186
|
+
if (navigator.clipboard && navigator.clipboard.writeText) {
|
|
3187
|
+
navigator.clipboard.writeText(text).then(function() {
|
|
3188
|
+
btn.textContent = 'Copied';
|
|
3189
|
+
setTimeout(function() { btn.textContent = 'Copy'; }, 1200);
|
|
3190
|
+
}, function() {
|
|
3191
|
+
btn.textContent = 'Copy';
|
|
3192
|
+
});
|
|
3193
|
+
}
|
|
3194
|
+
});
|
|
3195
|
+
wrapper.insertBefore(btn, pre);
|
|
3196
|
+
});
|
|
3197
|
+
|
|
3198
|
+
// ─── Tabs (ARIA pattern: aria-selected + roving tabindex + arrow keys) ────
|
|
3199
|
+
function activateTab(group, btn, focus) {
|
|
3200
|
+
var idx = btn.getAttribute('data-tab');
|
|
3201
|
+
group.querySelectorAll('.tab-btn').forEach(function(b) {
|
|
3202
|
+
var on = b === btn;
|
|
3203
|
+
b.classList.toggle('active', on);
|
|
3204
|
+
b.setAttribute('aria-selected', on ? 'true' : 'false');
|
|
3205
|
+
b.setAttribute('tabindex', on ? '0' : '-1');
|
|
3206
|
+
});
|
|
3207
|
+
group.querySelectorAll('.tabpane').forEach(function(pane) {
|
|
3208
|
+
pane.classList.toggle('active', pane.getAttribute('data-tab') === idx);
|
|
3209
|
+
});
|
|
3210
|
+
if (focus) btn.focus();
|
|
3211
|
+
}
|
|
3212
|
+
document.querySelectorAll('.tabs').forEach(function(group) {
|
|
3213
|
+
var btns = [].slice.call(group.querySelectorAll('.tab-btn'));
|
|
3214
|
+
btns.forEach(function(btn, i) {
|
|
3215
|
+
btn.addEventListener('click', function() { activateTab(group, btn, false); });
|
|
3216
|
+
btn.addEventListener('keydown', function(e) {
|
|
3217
|
+
var ni = -1;
|
|
3218
|
+
if (e.key === 'ArrowRight' || e.key === 'ArrowDown') ni = (i + 1) % btns.length;
|
|
3219
|
+
else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') ni = (i - 1 + btns.length) % btns.length;
|
|
3220
|
+
else if (e.key === 'Home') ni = 0;
|
|
3221
|
+
else if (e.key === 'End') ni = btns.length - 1;
|
|
3222
|
+
if (ni >= 0) { e.preventDefault(); activateTab(group, btns[ni], true); }
|
|
3223
|
+
});
|
|
3224
|
+
});
|
|
3225
|
+
});
|
|
3226
|
+
|
|
3227
|
+
// ─── Filter tables ────────────────────────────────────────────────────────
|
|
3228
|
+
document.querySelectorAll('.filter-input').forEach(function(input) {
|
|
3229
|
+
input.addEventListener('input', function() {
|
|
3230
|
+
var q = input.value.toLowerCase();
|
|
3231
|
+
var container = input.closest('.filter-table');
|
|
3232
|
+
if (!container) return;
|
|
3233
|
+
container.querySelectorAll('tbody tr').forEach(function(row) {
|
|
3234
|
+
var text = (row.textContent || '').toLowerCase();
|
|
3235
|
+
row.style.display = text.includes(q) ? '' : 'none';
|
|
3236
|
+
});
|
|
3237
|
+
});
|
|
3238
|
+
});
|
|
3239
|
+
|
|
3240
|
+
// ─── Scrollspy ────────────────────────────────────────────────────────────
|
|
3241
|
+
if (typeof IntersectionObserver === 'undefined') return;
|
|
3242
|
+
var headings = document.querySelectorAll('h2[id],h3[id]');
|
|
3243
|
+
if (!headings.length) return;
|
|
3244
|
+
var observer = new IntersectionObserver(function(entries) {
|
|
3245
|
+
entries.forEach(function(entry) {
|
|
3246
|
+
if (!entry.isIntersecting) return;
|
|
3247
|
+
var id = entry.target.getAttribute('id');
|
|
3248
|
+
document.querySelectorAll('.toc a').forEach(function(a) {
|
|
3249
|
+
a.classList.toggle('active', a.getAttribute('href') === '#' + id);
|
|
3250
|
+
});
|
|
3251
|
+
});
|
|
3252
|
+
}, { rootMargin: '0px 0px -70% 0px', threshold: 0 });
|
|
3253
|
+
headings.forEach(function(h) { observer.observe(h); });
|
|
3254
|
+
});
|
|
3255
|
+
})();</script>
|
|
3256
|
+
</body>
|
|
3257
|
+
</html>
|