aaronrene / knowtation public
transcript.txt text
573 lines 40.7 KB
Raw
sha256:8915fe406161f95c1681f9469375e7bae5b28c884f00bedbdef65e4b0cd0738d docs(flow): commit FLOW-V0-SPEC.md hygiene for 7A-INT merge Human 14 hours ago
1 === Anti-drift diff demo (7A-12) ===
2 store: /var/folders/1h/h0k1lcss0fdc_2rvzffnlq040000gp/T/tmp.bU3kwzUMxg/data
3 seed v1 {"seeded":2,"skipped":0}
4
5 ### 1a. generate cursor_rule @ v0.1.0
6 $ node cli/index.mjs flow project flow_overseer_handover --harness cursor_rule --out docs/evidence/7A-12/artifacts/overseer.v0.1.0.mdc
7 ---
8 description: "Docs-first handover of the cross-repo overseer role: snapshot truth per repo, update durable docs, then regenerate the living handover block as a projection of them."
9 globs: "**/*process*, **/*handover*, **/*coordination*, **/*dogfood*"
10 alwaysApply: false
11 ---
12
13 <!-- GENERATED FROM CANONICAL FLOW [email protected] (generator v1) — DO NOT EDIT; regenerate via knowtation flow project -->
14
15 ## Step 1: Snapshot truth per repo, confirmed via muse -C (not ambient).
16
17 **Instruction:** Run muse -C &lt;abs path&gt; status and log for each repo (Scooling, Knowtation, MuseHub) and capture branch, HEAD sha, and dirty state.
18
19 **Trigger:** Run when a chat is getting long, a chat switch is needed, or a session ends with multi-repo state in flight.
20
21 **Boundaries:**
22 - Always target each repo with muse -C &lt;absolute-path&gt; — a bare muse can report an ambient repo
23 - Read only — do not commit or checkout during the snapshot
24 - No secrets in captured output
25
26 **Output shape:** A per-repo line for each repo with real branch, HEAD sha, and dirty flag, each confirmed via -C.
27
28 **Verification:** artifact_exists — Each repo is confirmed via -C (not ambient) and every repo line carries a real branch and sha. (evidence required: yes)
29
30 **Skill refs:** cli:muse -C &lt;abs-repo-path&gt; status, cli:muse -C &lt;abs-repo-path&gt; log
31
32 ## Step 2: Record the current step, next action, and open gates/blockers.
33
34 **Instruction:** Write down the current initiative step, the unambiguous next action, and any open gates or blockers.
35
36 **Trigger:** Run after per-repo truth is captured.
37
38 **Boundaries:**
39 - State the next action so it needs no chat history to interpret
40
41 **Output shape:** A current-step line, a next-action line, and an open-gates/blockers list.
42
43 **Verification:** human_review — The next action is unambiguous. (evidence required: yes)
44
45 ## Step 3: List the boundaries and the cross-repo wiring touched this session.
46
47 **Instruction:** Enumerate the boundaries to honor and the cross-repo wiring touched this session.
48
49 **Trigger:** Run after the step and gates are recorded.
50
51 **Boundaries:**
52 - Boundaries are stated explicitly, not assumed
53
54 **Output shape:** An explicit boundaries list and a cross-repo wiring list for the session.
55
56 **Verification:** human_review — Boundaries are explicit and the cross-repo wiring touched is listed. (evidence required: yes)
57
58 ## Step 4: Update the durable docs FIRST.
59
60 **Instruction:** Update the ROADMAP snapshot, the next-session plan, and the coordination doc so they match reality before any block is written.
61
62 **Trigger:** Run after truth, step/gates, and boundaries are captured.
63
64 **Boundaries:**
65 - Update durable docs before regenerating any handover block
66 - Docs are the source of truth, the block is a projection of them
67
68 **Output shape:** Updated ROADMAP snapshot, next-session plan, and coordination doc reflecting reality.
69
70 **Verification:** artifact_exists — The durable docs are updated and match reality before any block is written. (evidence required: yes)
71
72 ## Step 5: Regenerate the handover block into the living file from the now-current docs.
73
74 **Instruction:** Overwrite docs/OVERSEER-HANDOVER.md with a block regenerated from the updated durable docs, not from memory.
75
76 **Trigger:** Run only after the durable docs are updated.
77
78 **Boundaries:**
79 - The block is a projection of the docs — never hand-written ahead of them
80 - No secrets in the block
81
82 **Output shape:** An overwritten docs/OVERSEER-HANDOVER.md whose block matches the durable docs.
83
84 **Verification:** artifact_exists — The living file is overwritten and its block matches the docs, not memory. (evidence required: yes)
85
86 ## Step 6: Emit the block as the first message of the next chat.
87
88 **Instruction:** Paste the regenerated handover block as the first message of the new chat so the overseer role resumes with no prior history.
89
90 **Trigger:** Run once the living file holds the current block.
91
92 **Boundaries:**
93 - Emit only the projected block — do not add scope beyond the durable docs
94
95 **Output shape:** The handover block, emitted as the first message of the next chat.
96
97 **Verification:** human_review — A new overseer can resume from the emitted block with no prior chat history. (evidence required: yes)
98
99
100 staleness: fresh (0.1.0 vs latest 0.1.0)
101 dropped fields: inputs, outputs, requires, when_not_to_run
102 fidelity: cursor_rule has no anti-trigger slot
103 wrote: docs/evidence/7A-12/artifacts/overseer.v0.1.0.mdc
104 [exit=0]
105
106 ### 1b. generate cli_runbook @ v0.1.0
107 $ node cli/index.mjs flow project flow_overseer_handover --harness cli_runbook --out docs/evidence/7A-12/artifacts/overseer.AGENTS.v0.1.0.md
108 # Overseer handover
109
110 <!-- GENERATED FROM CANONICAL FLOW [email protected] (generator v1) — DO NOT EDIT; regenerate via knowtation flow project -->
111
112 Docs-first handover of the cross-repo overseer role: snapshot truth per repo, update durable docs, then regenerate the living handover block as a projection of them.
113
114 ## Step 1
115
116 - **Owned job:** Snapshot truth per repo, confirmed via muse -C (not ambient).
117 - **Instruction:** Run muse -C &lt;abs path&gt; status and log for each repo (Scooling, Knowtation, MuseHub) and capture branch, HEAD sha, and dirty state.
118 - **Trigger:** Run when a chat is getting long, a chat switch is needed, or a session ends with multi-repo state in flight.
119 - **When not to run:** Skip if no multi-repo state is in flight and no handover is needed.
120 - **Requires:** vault_scope:project, tool:muse_cli
121 - **Boundaries:**
122 - Always target each repo with muse -C &lt;absolute-path&gt; — a bare muse can report an ambient repo
123 - Read only — do not commit or checkout during the snapshot
124 - No secrets in captured output
125 - **Skill refs:** cli:muse -C &lt;abs-repo-path&gt; status, cli:muse -C &lt;abs-repo-path&gt; log
126 - **Outputs:** per_repo_state:text
127 - **Output shape:** A per-repo line for each repo with real branch, HEAD sha, and dirty flag, each confirmed via -C.
128 - **Verification:** artifact_exists — Each repo is confirmed via -C (not ambient) and every repo line carries a real branch and sha. (evidence required: yes)
129
130 ## Step 2
131
132 - **Owned job:** Record the current step, next action, and open gates/blockers.
133 - **Instruction:** Write down the current initiative step, the unambiguous next action, and any open gates or blockers.
134 - **Trigger:** Run after per-repo truth is captured.
135 - **When not to run:** Skip if the next action and gates are already recorded and unchanged.
136 - **Requires:** vault_scope:project
137 - **Boundaries:**
138 - State the next action so it needs no chat history to interpret
139 - **Inputs:** per_repo_state (from flow_overseer_handover#1.outputs.per_repo_state)
140 - **Outputs:** step_and_gates:text
141 - **Output shape:** A current-step line, a next-action line, and an open-gates/blockers list.
142 - **Verification:** human_review — The next action is unambiguous. (evidence required: yes)
143
144 ## Step 3
145
146 - **Owned job:** List the boundaries and the cross-repo wiring touched this session.
147 - **Instruction:** Enumerate the boundaries to honor and the cross-repo wiring touched this session.
148 - **Trigger:** Run after the step and gates are recorded.
149 - **When not to run:** Skip if no cross-repo wiring was touched and boundaries are already listed.
150 - **Requires:** vault_scope:project
151 - **Boundaries:**
152 - Boundaries are stated explicitly, not assumed
153 - **Outputs:** boundaries_and_wiring:text
154 - **Output shape:** An explicit boundaries list and a cross-repo wiring list for the session.
155 - **Verification:** human_review — Boundaries are explicit and the cross-repo wiring touched is listed. (evidence required: yes)
156
157 ## Step 4
158
159 - **Owned job:** Update the durable docs FIRST.
160 - **Instruction:** Update the ROADMAP snapshot, the next-session plan, and the coordination doc so they match reality before any block is written.
161 - **Trigger:** Run after truth, step/gates, and boundaries are captured.
162 - **When not to run:** Never skip when handing off — docs-first ordering is mandatory.
163 - **Requires:** vault_scope:project, file:docs/ROADMAP.md, file:docs/PRODUCT-SURFACES-NEXT-SESSION-PLAN.md, file:docs/CROSS-REPO-COORDINATION.md
164 - **Boundaries:**
165 - Update durable docs before regenerating any handover block
166 - Docs are the source of truth, the block is a projection of them
167 - **Outputs:** docs_update_ref:string
168 - **Output shape:** Updated ROADMAP snapshot, next-session plan, and coordination doc reflecting reality.
169 - **Verification:** artifact_exists — The durable docs are updated and match reality before any block is written. (evidence required: yes)
170
171 ## Step 5
172
173 - **Owned job:** Regenerate the handover block into the living file from the now-current docs.
174 - **Instruction:** Overwrite docs/OVERSEER-HANDOVER.md with a block regenerated from the updated durable docs, not from memory.
175 - **Trigger:** Run only after the durable docs are updated.
176 - **When not to run:** Skip if the docs have not yet been updated this handover.
177 - **Requires:** vault_scope:project, file:docs/OVERSEER-HANDOVER.md
178 - **Boundaries:**
179 - The block is a projection of the docs — never hand-written ahead of them
180 - No secrets in the block
181 - **Inputs:** docs_update_ref (from flow_overseer_handover#4.outputs.docs_update_ref)
182 - **Outputs:** handover_block_ref:string
183 - **Output shape:** An overwritten docs/OVERSEER-HANDOVER.md whose block matches the durable docs.
184 - **Verification:** artifact_exists — The living file is overwritten and its block matches the docs, not memory. (evidence required: yes)
185
186 ## Step 6
187
188 - **Owned job:** Emit the block as the first message of the next chat.
189 - **Instruction:** Paste the regenerated handover block as the first message of the new chat so the overseer role resumes with no prior history.
190 - **Trigger:** Run once the living file holds the current block.
191 - **When not to run:** Skip if no new chat is being started.
192 - **Requires:** vault_scope:project, file:docs/OVERSEER-HANDOVER.md
193 - **Boundaries:**
194 - Emit only the projected block — do not add scope beyond the durable docs
195 - **Inputs:** handover_block_ref (from flow_overseer_handover#5.outputs.handover_block_ref)
196 - **Outputs:** emitted_block:text
197 - **Output shape:** The handover block, emitted as the first message of the next chat.
198 - **Verification:** human_review — A new overseer can resume from the emitted block with no prior chat history. (evidence required: yes)
199
200
201 staleness: fresh (0.1.0 vs latest 0.1.0)
202 wrote: docs/evidence/7A-12/artifacts/overseer.AGENTS.v0.1.0.md
203 [exit=0]
204
205 ### 1c. --check baseline cli_runbook (expect drift=false, exit 0)
206 $ node cli/index.mjs flow project flow_overseer_handover --harness cli_runbook --out docs/evidence/7A-12/artifacts/overseer.AGENTS.v0.1.0.md --check
207 drift: false (clean)
208 stale: false
209 [exit=0]
210 seed v2 {"seeded":1,"skipped":1}
211
212 ### 2a. regenerate cursor_rule @ latest (v0.2.0)
213 $ node cli/index.mjs flow project flow_overseer_handover --harness cursor_rule --out docs/evidence/7A-12/artifacts/overseer.v0.2.0.mdc
214 ---
215 description: "Docs-first handover of the cross-repo overseer role: snapshot truth per repo, update the durable docs (ROADMAP snapshot, next-session plan, coordination doc), then regenerate the living handover block as a projection of them."
216 globs: "**/*process*, **/*handover*, **/*coordination*, **/*dogfood*"
217 alwaysApply: false
218 ---
219
220 <!-- GENERATED FROM CANONICAL FLOW [email protected] (generator v1) — DO NOT EDIT; regenerate via knowtation flow project -->
221
222 ## Step 1: Snapshot truth per repo, confirmed via muse -C (not ambient).
223
224 **Instruction:** Run muse -C &lt;abs path&gt; status and log for each repo (Scooling, Knowtation, MuseHub) and capture branch, HEAD sha, and dirty state.
225
226 **Trigger:** Run when a chat is getting long, a chat switch is needed, or a session ends with multi-repo state in flight.
227
228 **Boundaries:**
229 - Always target each repo with muse -C &lt;absolute-path&gt; — a bare muse can report an ambient repo
230 - Read only — do not commit or checkout during the snapshot
231 - No secrets in captured output
232
233 **Output shape:** A per-repo line for each repo with real branch, HEAD sha, and dirty flag, each confirmed via -C.
234
235 **Verification:** artifact_exists — Each repo is confirmed via -C (not ambient) and every repo line carries a real branch and sha. (evidence required: yes)
236
237 **Skill refs:** cli:muse -C &lt;abs-repo-path&gt; status, cli:muse -C &lt;abs-repo-path&gt; log
238
239 ## Step 2: Record the current step, next action, and open gates/blockers.
240
241 **Instruction:** Write down the current initiative step, the unambiguous next action, and any open gates or blockers.
242
243 **Trigger:** Run after per-repo truth is captured.
244
245 **Boundaries:**
246 - State the next action so it needs no chat history to interpret
247
248 **Output shape:** A current-step line, a next-action line, and an open-gates/blockers list.
249
250 **Verification:** human_review — The next action is unambiguous. (evidence required: yes)
251
252 ## Step 3: List the boundaries and the cross-repo wiring touched this session.
253
254 **Instruction:** Enumerate the boundaries to honor and the cross-repo wiring touched this session.
255
256 **Trigger:** Run after the step and gates are recorded.
257
258 **Boundaries:**
259 - Boundaries are stated explicitly, not assumed
260
261 **Output shape:** An explicit boundaries list and a cross-repo wiring list for the session.
262
263 **Verification:** human_review — Boundaries are explicit and the cross-repo wiring touched is listed. (evidence required: yes)
264
265 ## Step 4: Update the durable docs FIRST.
266
267 **Instruction:** Update the ROADMAP snapshot, the next-session plan, and the coordination doc so they match reality before any block is written.
268
269 **Trigger:** Run after truth, step/gates, and boundaries are captured.
270
271 **Boundaries:**
272 - Update durable docs before regenerating any handover block
273 - Docs are the source of truth, the block is a projection of them
274
275 **Output shape:** Updated ROADMAP snapshot, next-session plan, and coordination doc reflecting reality.
276
277 **Verification:** artifact_exists — The durable docs are updated and match reality before any block is written. (evidence required: yes)
278
279 ## Step 5: Regenerate the handover block into the living file from the now-current docs.
280
281 **Instruction:** Overwrite docs/OVERSEER-HANDOVER.md with a block regenerated from the updated durable docs, not from memory.
282
283 **Trigger:** Run only after the durable docs are updated.
284
285 **Boundaries:**
286 - The block is a projection of the docs — never hand-written ahead of them
287 - No secrets in the block
288
289 **Output shape:** An overwritten docs/OVERSEER-HANDOVER.md whose block matches the durable docs.
290
291 **Verification:** artifact_exists — The living file is overwritten and its block matches the docs, not memory. (evidence required: yes)
292
293 ## Step 6: Emit the block as the first message of the next chat.
294
295 **Instruction:** Paste the regenerated handover block as the first message of the new chat so the overseer role resumes with no prior history.
296
297 **Trigger:** Run once the living file holds the current block.
298
299 **Boundaries:**
300 - Emit only the projected block — do not add scope beyond the durable docs
301
302 **Output shape:** The handover block, emitted as the first message of the next chat.
303
304 **Verification:** human_review — A new overseer can resume from the emitted block with no prior chat history. (evidence required: yes)
305
306
307 staleness: fresh (0.2.0 vs latest 0.2.0)
308 dropped fields: inputs, outputs, requires, when_not_to_run
309 fidelity: cursor_rule has no anti-trigger slot
310 wrote: docs/evidence/7A-12/artifacts/overseer.v0.2.0.mdc
311 [exit=0]
312
313 ### 2b. regenerate cli_runbook @ latest (v0.2.0)
314 $ node cli/index.mjs flow project flow_overseer_handover --harness cli_runbook --out docs/evidence/7A-12/artifacts/overseer.AGENTS.v0.2.0.md
315 # Overseer handover
316
317 <!-- GENERATED FROM CANONICAL FLOW [email protected] (generator v1) — DO NOT EDIT; regenerate via knowtation flow project -->
318
319 Docs-first handover of the cross-repo overseer role: snapshot truth per repo, update the durable docs (ROADMAP snapshot, next-session plan, coordination doc), then regenerate the living handover block as a projection of them.
320
321 ## Step 1
322
323 - **Owned job:** Snapshot truth per repo, confirmed via muse -C (not ambient).
324 - **Instruction:** Run muse -C &lt;abs path&gt; status and log for each repo (Scooling, Knowtation, MuseHub) and capture branch, HEAD sha, and dirty state.
325 - **Trigger:** Run when a chat is getting long, a chat switch is needed, or a session ends with multi-repo state in flight.
326 - **When not to run:** Skip if no multi-repo state is in flight and no handover is needed.
327 - **Requires:** vault_scope:project, tool:muse_cli
328 - **Boundaries:**
329 - Always target each repo with muse -C &lt;absolute-path&gt; — a bare muse can report an ambient repo
330 - Read only — do not commit or checkout during the snapshot
331 - No secrets in captured output
332 - **Skill refs:** cli:muse -C &lt;abs-repo-path&gt; status, cli:muse -C &lt;abs-repo-path&gt; log
333 - **Outputs:** per_repo_state:text
334 - **Output shape:** A per-repo line for each repo with real branch, HEAD sha, and dirty flag, each confirmed via -C.
335 - **Verification:** artifact_exists — Each repo is confirmed via -C (not ambient) and every repo line carries a real branch and sha. (evidence required: yes)
336
337 ## Step 2
338
339 - **Owned job:** Record the current step, next action, and open gates/blockers.
340 - **Instruction:** Write down the current initiative step, the unambiguous next action, and any open gates or blockers.
341 - **Trigger:** Run after per-repo truth is captured.
342 - **When not to run:** Skip if the next action and gates are already recorded and unchanged.
343 - **Requires:** vault_scope:project
344 - **Boundaries:**
345 - State the next action so it needs no chat history to interpret
346 - **Inputs:** per_repo_state (from flow_overseer_handover#1.outputs.per_repo_state)
347 - **Outputs:** step_and_gates:text
348 - **Output shape:** A current-step line, a next-action line, and an open-gates/blockers list.
349 - **Verification:** human_review — The next action is unambiguous. (evidence required: yes)
350
351 ## Step 3
352
353 - **Owned job:** List the boundaries and the cross-repo wiring touched this session.
354 - **Instruction:** Enumerate the boundaries to honor and the cross-repo wiring touched this session.
355 - **Trigger:** Run after the step and gates are recorded.
356 - **When not to run:** Skip if no cross-repo wiring was touched and boundaries are already listed.
357 - **Requires:** vault_scope:project
358 - **Boundaries:**
359 - Boundaries are stated explicitly, not assumed
360 - **Outputs:** boundaries_and_wiring:text
361 - **Output shape:** An explicit boundaries list and a cross-repo wiring list for the session.
362 - **Verification:** human_review — Boundaries are explicit and the cross-repo wiring touched is listed. (evidence required: yes)
363
364 ## Step 4
365
366 - **Owned job:** Update the durable docs FIRST.
367 - **Instruction:** Update the ROADMAP snapshot, the next-session plan, and the coordination doc so they match reality before any block is written.
368 - **Trigger:** Run after truth, step/gates, and boundaries are captured.
369 - **When not to run:** Never skip when handing off — docs-first ordering is mandatory.
370 - **Requires:** vault_scope:project, file:docs/ROADMAP.md, file:docs/PRODUCT-SURFACES-NEXT-SESSION-PLAN.md, file:docs/CROSS-REPO-COORDINATION.md
371 - **Boundaries:**
372 - Update durable docs before regenerating any handover block
373 - Docs are the source of truth, the block is a projection of them
374 - **Outputs:** docs_update_ref:string
375 - **Output shape:** Updated ROADMAP snapshot, next-session plan, and coordination doc reflecting reality.
376 - **Verification:** artifact_exists — The durable docs are updated and match reality before any block is written. (evidence required: yes)
377
378 ## Step 5
379
380 - **Owned job:** Regenerate the handover block into the living file from the now-current docs.
381 - **Instruction:** Overwrite docs/OVERSEER-HANDOVER.md with a block regenerated from the updated durable docs, not from memory.
382 - **Trigger:** Run only after the durable docs are updated.
383 - **When not to run:** Skip if the docs have not yet been updated this handover.
384 - **Requires:** vault_scope:project, file:docs/OVERSEER-HANDOVER.md
385 - **Boundaries:**
386 - The block is a projection of the docs — never hand-written ahead of them
387 - No secrets in the block
388 - **Inputs:** docs_update_ref (from flow_overseer_handover#4.outputs.docs_update_ref)
389 - **Outputs:** handover_block_ref:string
390 - **Output shape:** An overwritten docs/OVERSEER-HANDOVER.md whose block matches the durable docs.
391 - **Verification:** artifact_exists — The living file is overwritten and its block matches the docs, not memory. (evidence required: yes)
392
393 ## Step 6
394
395 - **Owned job:** Emit the block as the first message of the next chat.
396 - **Instruction:** Paste the regenerated handover block as the first message of the new chat so the overseer role resumes with no prior history.
397 - **Trigger:** Run once the living file holds the current block.
398 - **When not to run:** Skip if no new chat is being started.
399 - **Requires:** vault_scope:project, file:docs/OVERSEER-HANDOVER.md
400 - **Boundaries:**
401 - Emit only the projected block — do not add scope beyond the durable docs
402 - **Inputs:** handover_block_ref (from flow_overseer_handover#5.outputs.handover_block_ref)
403 - **Outputs:** emitted_block:text
404 - **Output shape:** The handover block, emitted as the first message of the next chat.
405 - **Verification:** human_review — A new overseer can resume from the emitted block with no prior chat history. (evidence required: yes)
406
407
408 staleness: fresh (0.2.0 vs latest 0.2.0)
409 wrote: docs/evidence/7A-12/artifacts/overseer.AGENTS.v0.2.0.md
410 [exit=0]
411
412 ### 2c. diff v0.1.0 -> v0.2.0 (cursor_rule) — expect only marker version + verification line
413 --- docs/evidence/7A-12/artifacts/overseer.v0.1.0.mdc 2026-06-20 15:15:11
414 +++ docs/evidence/7A-12/artifacts/overseer.v0.2.0.mdc 2026-06-20 15:15:11
415 @@ -1,10 +1,10 @@
416 ---
417 -description: "Docs-first handover of the cross-repo overseer role: snapshot truth per repo, update durable docs, then regenerate the living handover block as a projection of them."
418 +description: "Docs-first handover of the cross-repo overseer role: snapshot truth per repo, update the durable docs (ROADMAP snapshot, next-session plan, coordination doc), then regenerate the living handover block as a projection of them."
419 globs: "**/*process*, **/*handover*, **/*coordination*, **/*dogfood*"
420 alwaysApply: false
421 ---
422
423 -<!-- GENERATED FROM CANONICAL FLOW [email protected] (generator v1) — DO NOT EDIT; regenerate via knowtation flow project -->
424 +<!-- GENERATED FROM CANONICAL FLOW [email protected] (generator v1) — DO NOT EDIT; regenerate via knowtation flow project -->
425
426 ## Step 1: Snapshot truth per repo, confirmed via muse -C (not ambient).
427
428 [diff captured: docs/evidence/7A-12/artifacts/overseer.cursor.v1-to-v2.diff]
429
430 ### 2d. diff v0.1.0 -> v0.2.0 (cli_runbook) — expect only marker version + verification line
431 --- docs/evidence/7A-12/artifacts/overseer.AGENTS.v0.1.0.md 2026-06-20 15:15:11
432 +++ docs/evidence/7A-12/artifacts/overseer.AGENTS.v0.2.0.md 2026-06-20 15:15:12
433 @@ -1,8 +1,8 @@
434 # Overseer handover
435
436 -<!-- GENERATED FROM CANONICAL FLOW [email protected] (generator v1) — DO NOT EDIT; regenerate via knowtation flow project -->
437 +<!-- GENERATED FROM CANONICAL FLOW [email protected] (generator v1) — DO NOT EDIT; regenerate via knowtation flow project -->
438
439 -Docs-first handover of the cross-repo overseer role: snapshot truth per repo, update durable docs, then regenerate the living handover block as a projection of them.
440 +Docs-first handover of the cross-repo overseer role: snapshot truth per repo, update the durable docs (ROADMAP snapshot, next-session plan, coordination doc), then regenerate the living handover block as a projection of them.
441
442 ## Step 1
443
444 [diff captured: docs/evidence/7A-12/artifacts/overseer.runbook.v1-to-v2.diff]
445
446 ### 3a. regenerate deleted cursor_rule @ v0.2.0
447 $ node cli/index.mjs flow project flow_overseer_handover --harness cursor_rule --out docs/evidence/7A-12/artifacts/overseer.v0.2.0.mdc
448 ---
449 description: "Docs-first handover of the cross-repo overseer role: snapshot truth per repo, update the durable docs (ROADMAP snapshot, next-session plan, coordination doc), then regenerate the living handover block as a projection of them."
450 globs: "**/*process*, **/*handover*, **/*coordination*, **/*dogfood*"
451 alwaysApply: false
452 ---
453
454 <!-- GENERATED FROM CANONICAL FLOW [email protected] (generator v1) — DO NOT EDIT; regenerate via knowtation flow project -->
455
456 ## Step 1: Snapshot truth per repo, confirmed via muse -C (not ambient).
457
458 **Instruction:** Run muse -C &lt;abs path&gt; status and log for each repo (Scooling, Knowtation, MuseHub) and capture branch, HEAD sha, and dirty state.
459
460 **Trigger:** Run when a chat is getting long, a chat switch is needed, or a session ends with multi-repo state in flight.
461
462 **Boundaries:**
463 - Always target each repo with muse -C &lt;absolute-path&gt; — a bare muse can report an ambient repo
464 - Read only — do not commit or checkout during the snapshot
465 - No secrets in captured output
466
467 **Output shape:** A per-repo line for each repo with real branch, HEAD sha, and dirty flag, each confirmed via -C.
468
469 **Verification:** artifact_exists — Each repo is confirmed via -C (not ambient) and every repo line carries a real branch and sha. (evidence required: yes)
470
471 **Skill refs:** cli:muse -C &lt;abs-repo-path&gt; status, cli:muse -C &lt;abs-repo-path&gt; log
472
473 ## Step 2: Record the current step, next action, and open gates/blockers.
474
475 **Instruction:** Write down the current initiative step, the unambiguous next action, and any open gates or blockers.
476
477 **Trigger:** Run after per-repo truth is captured.
478
479 **Boundaries:**
480 - State the next action so it needs no chat history to interpret
481
482 **Output shape:** A current-step line, a next-action line, and an open-gates/blockers list.
483
484 **Verification:** human_review — The next action is unambiguous. (evidence required: yes)
485
486 ## Step 3: List the boundaries and the cross-repo wiring touched this session.
487
488 **Instruction:** Enumerate the boundaries to honor and the cross-repo wiring touched this session.
489
490 **Trigger:** Run after the step and gates are recorded.
491
492 **Boundaries:**
493 - Boundaries are stated explicitly, not assumed
494
495 **Output shape:** An explicit boundaries list and a cross-repo wiring list for the session.
496
497 **Verification:** human_review — Boundaries are explicit and the cross-repo wiring touched is listed. (evidence required: yes)
498
499 ## Step 4: Update the durable docs FIRST.
500
501 **Instruction:** Update the ROADMAP snapshot, the next-session plan, and the coordination doc so they match reality before any block is written.
502
503 **Trigger:** Run after truth, step/gates, and boundaries are captured.
504
505 **Boundaries:**
506 - Update durable docs before regenerating any handover block
507 - Docs are the source of truth, the block is a projection of them
508
509 **Output shape:** Updated ROADMAP snapshot, next-session plan, and coordination doc reflecting reality.
510
511 **Verification:** artifact_exists — The durable docs are updated and match reality before any block is written. (evidence required: yes)
512
513 ## Step 5: Regenerate the handover block into the living file from the now-current docs.
514
515 **Instruction:** Overwrite docs/OVERSEER-HANDOVER.md with a block regenerated from the updated durable docs, not from memory.
516
517 **Trigger:** Run only after the durable docs are updated.
518
519 **Boundaries:**
520 - The block is a projection of the docs — never hand-written ahead of them
521 - No secrets in the block
522
523 **Output shape:** An overwritten docs/OVERSEER-HANDOVER.md whose block matches the durable docs.
524
525 **Verification:** artifact_exists — The living file is overwritten and its block matches the docs, not memory. (evidence required: yes)
526
527 ## Step 6: Emit the block as the first message of the next chat.
528
529 **Instruction:** Paste the regenerated handover block as the first message of the new chat so the overseer role resumes with no prior history.
530
531 **Trigger:** Run once the living file holds the current block.
532
533 **Boundaries:**
534 - Emit only the projected block — do not add scope beyond the durable docs
535
536 **Output shape:** The handover block, emitted as the first message of the next chat.
537
538 **Verification:** human_review — A new overseer can resume from the emitted block with no prior chat history. (evidence required: yes)
539
540
541 staleness: fresh (0.2.0 vs latest 0.2.0)
542 dropped fields: inputs, outputs, requires, when_not_to_run
543 fidelity: cursor_rule has no anti-trigger slot
544 wrote: docs/evidence/7A-12/artifacts/overseer.v0.2.0.mdc
545 [exit=0]
546
547 ### 3b. byte-identical after delete+regenerate (expect no output / identical)
548 IDENTICAL: regenerated artifact == pre-delete artifact (lossless)
549
550 ### 4. --check hand-edited cli_runbook (expect drift=true edited, exit 1)
551 $ node cli/index.mjs flow project flow_overseer_handover --harness cli_runbook --out docs/evidence/7A-12/artifacts/overseer.AGENTS.handedited.md --check
552 drift: true (edited)
553 stale: false
554 [exit=1]
555
556 ### 5. --check pinned v0.1.0 vs latest v0.2.0 (expect stale=true, exit 1)
557 $ node cli/index.mjs flow project flow_overseer_handover --harness cli_runbook --version 0.1.0 --out docs/evidence/7A-12/artifacts/overseer.AGENTS.v0.1.0.md --check
558 drift: false (clean)
559 stale: true
560 versions: projection 0.1.0 < latest 0.2.0
561 [exit=1]
562
563 ### 6a. cursor_rule fidelity (expect when_not_to_run dropped)
564 $ node cli/index.mjs flow project flow_overseer_handover --harness cursor_rule --json
565 {"schema":"knowtation.flow_project/v0","vault_id":"default","projection":{"schema":"knowtation.flow_projection/v0","flow_id":"flow_overseer_handover","flow_version":"0.2.0","harness":"cursor_rule","rendered":"---\ndescription: \"Docs-first handover of the cross-repo overseer role: snapshot truth per repo, update the durable docs (ROADMAP snapshot, next-session plan, coordination doc), then regenerate the living handover block as a projection of them.\"\nglobs: \"**/*process*, **/*handover*, **/*coordination*, **/*dogfood*\"\nalwaysApply: false\n---\n\n<!-- GENERATED FROM CANONICAL FLOW [email protected] (generator v1) — DO NOT EDIT; regenerate via knowtation flow project -->\n\n## Step 1: Snapshot truth per repo, confirmed via muse -C (not ambient).\n\n**Instruction:** Run muse -C &lt;abs path&gt; status and log for each repo (Scooling, Knowtation, MuseHub) and capture branch, HEAD sha, and dirty state.\n\n**Trigger:** Run when a chat is getting long, a chat switch is needed, or a session ends with multi-repo state in flight.\n\n**Boundaries:**\n- Always target each repo with muse -C &lt;absolute-path&gt; — a bare muse can report an ambient repo\n- Read only — do not commit or checkout during the snapshot\n- No secrets in captured output\n\n**Output shape:** A per-repo line for each repo with real branch, HEAD sha, and dirty flag, each confirmed via -C.\n\n**Verification:** artifact_exists — Each repo is confirmed via -C (not ambient) and every repo line carries a real branch and sha. (evidence required: yes)\n\n**Skill refs:** cli:muse -C &lt;abs-repo-path&gt; status, cli:muse -C &lt;abs-repo-path&gt; log\n\n## Step 2: Record the current step, next action, and open gates/blockers.\n\n**Instruction:** Write down the current initiative step, the unambiguous next action, and any open gates or blockers.\n\n**Trigger:** Run after per-repo truth is captured.\n\n**Boundaries:**\n- State the next action so it needs no chat history to interpret\n\n**Output shape:** A current-step line, a next-action line, and an open-gates/blockers list.\n\n**Verification:** human_review — The next action is unambiguous. (evidence required: yes)\n\n## Step 3: List the boundaries and the cross-repo wiring touched this session.\n\n**Instruction:** Enumerate the boundaries to honor and the cross-repo wiring touched this session.\n\n**Trigger:** Run after the step and gates are recorded.\n\n**Boundaries:**\n- Boundaries are stated explicitly, not assumed\n\n**Output shape:** An explicit boundaries list and a cross-repo wiring list for the session.\n\n**Verification:** human_review — Boundaries are explicit and the cross-repo wiring touched is listed. (evidence required: yes)\n\n## Step 4: Update the durable docs FIRST.\n\n**Instruction:** Update the ROADMAP snapshot, the next-session plan, and the coordination doc so they match reality before any block is written.\n\n**Trigger:** Run after truth, step/gates, and boundaries are captured.\n\n**Boundaries:**\n- Update durable docs before regenerating any handover block\n- Docs are the source of truth, the block is a projection of them\n\n**Output shape:** Updated ROADMAP snapshot, next-session plan, and coordination doc reflecting reality.\n\n**Verification:** artifact_exists — The durable docs are updated and match reality before any block is written. (evidence required: yes)\n\n## Step 5: Regenerate the handover block into the living file from the now-current docs.\n\n**Instruction:** Overwrite docs/OVERSEER-HANDOVER.md with a block regenerated from the updated durable docs, not from memory.\n\n**Trigger:** Run only after the durable docs are updated.\n\n**Boundaries:**\n- The block is a projection of the docs — never hand-written ahead of them\n- No secrets in the block\n\n**Output shape:** An overwritten docs/OVERSEER-HANDOVER.md whose block matches the durable docs.\n\n**Verification:** artifact_exists — The living file is overwritten and its block matches the docs, not memory. (evidence required: yes)\n\n## Step 6: Emit the block as the first message of the next chat.\n\n**Instruction:** Paste the regenerated handover block as the first message of the new chat so the overseer role resumes with no prior history.\n\n**Trigger:** Run once the living file holds the current block.\n\n**Boundaries:**\n- Emit only the projected block — do not add scope beyond the durable docs\n\n**Output shape:** The handover block, emitted as the first message of the next chat.\n\n**Verification:** human_review — A new overseer can resume from the emitted block with no prior chat history. (evidence required: yes)\n","generated_from_canonical":true,"editable":false,"fidelity":{"dropped_fields":["inputs","outputs","requires","when_not_to_run"],"notes":"cursor_rule has no anti-trigger slot"}},"staleness":{"stale":false,"projection_version":"0.2.0","latest_version":"0.2.0"},"generator":{"generator_version":"1","content_hash":"sha256:0ec0576498384bc056a440ccb19d56468704d6da4356f60d52d229c865be03a1","generated_at":"2026-06-20T22:15:12.353Z"}}
566 [exit=0]
567
568 ### 6b. cli_runbook fidelity (expect when_not_to_run expressed, not dropped)
569 $ node cli/index.mjs flow project flow_overseer_handover --harness cli_runbook --json
570 {"schema":"knowtation.flow_project/v0","vault_id":"default","projection":{"schema":"knowtation.flow_projection/v0","flow_id":"flow_overseer_handover","flow_version":"0.2.0","harness":"cli_runbook","rendered":"# Overseer handover\n\n<!-- GENERATED FROM CANONICAL FLOW [email protected] (generator v1) — DO NOT EDIT; regenerate via knowtation flow project -->\n\nDocs-first handover of the cross-repo overseer role: snapshot truth per repo, update the durable docs (ROADMAP snapshot, next-session plan, coordination doc), then regenerate the living handover block as a projection of them.\n\n## Step 1\n\n- **Owned job:** Snapshot truth per repo, confirmed via muse -C (not ambient).\n- **Instruction:** Run muse -C &lt;abs path&gt; status and log for each repo (Scooling, Knowtation, MuseHub) and capture branch, HEAD sha, and dirty state.\n- **Trigger:** Run when a chat is getting long, a chat switch is needed, or a session ends with multi-repo state in flight.\n- **When not to run:** Skip if no multi-repo state is in flight and no handover is needed.\n- **Requires:** vault_scope:project, tool:muse_cli\n- **Boundaries:**\n - Always target each repo with muse -C &lt;absolute-path&gt; — a bare muse can report an ambient repo\n - Read only — do not commit or checkout during the snapshot\n - No secrets in captured output\n- **Skill refs:** cli:muse -C &lt;abs-repo-path&gt; status, cli:muse -C &lt;abs-repo-path&gt; log\n- **Outputs:** per_repo_state:text\n- **Output shape:** A per-repo line for each repo with real branch, HEAD sha, and dirty flag, each confirmed via -C.\n- **Verification:** artifact_exists — Each repo is confirmed via -C (not ambient) and every repo line carries a real branch and sha. (evidence required: yes)\n\n## Step 2\n\n- **Owned job:** Record the current step, next action, and open gates/blockers.\n- **Instruction:** Write down the current initiative step, the unambiguous next action, and any open gates or blockers.\n- **Trigger:** Run after per-repo truth is captured.\n- **When not to run:** Skip if the next action and gates are already recorded and unchanged.\n- **Requires:** vault_scope:project\n- **Boundaries:**\n - State the next action so it needs no chat history to interpret\n- **Inputs:** per_repo_state (from flow_overseer_handover#1.outputs.per_repo_state)\n- **Outputs:** step_and_gates:text\n- **Output shape:** A current-step line, a next-action line, and an open-gates/blockers list.\n- **Verification:** human_review — The next action is unambiguous. (evidence required: yes)\n\n## Step 3\n\n- **Owned job:** List the boundaries and the cross-repo wiring touched this session.\n- **Instruction:** Enumerate the boundaries to honor and the cross-repo wiring touched this session.\n- **Trigger:** Run after the step and gates are recorded.\n- **When not to run:** Skip if no cross-repo wiring was touched and boundaries are already listed.\n- **Requires:** vault_scope:project\n- **Boundaries:**\n - Boundaries are stated explicitly, not assumed\n- **Outputs:** boundaries_and_wiring:text\n- **Output shape:** An explicit boundaries list and a cross-repo wiring list for the session.\n- **Verification:** human_review — Boundaries are explicit and the cross-repo wiring touched is listed. (evidence required: yes)\n\n## Step 4\n\n- **Owned job:** Update the durable docs FIRST.\n- **Instruction:** Update the ROADMAP snapshot, the next-session plan, and the coordination doc so they match reality before any block is written.\n- **Trigger:** Run after truth, step/gates, and boundaries are captured.\n- **When not to run:** Never skip when handing off — docs-first ordering is mandatory.\n- **Requires:** vault_scope:project, file:docs/ROADMAP.md, file:docs/PRODUCT-SURFACES-NEXT-SESSION-PLAN.md, file:docs/CROSS-REPO-COORDINATION.md\n- **Boundaries:**\n - Update durable docs before regenerating any handover block\n - Docs are the source of truth, the block is a projection of them\n- **Outputs:** docs_update_ref:string\n- **Output shape:** Updated ROADMAP snapshot, next-session plan, and coordination doc reflecting reality.\n- **Verification:** artifact_exists — The durable docs are updated and match reality before any block is written. (evidence required: yes)\n\n## Step 5\n\n- **Owned job:** Regenerate the handover block into the living file from the now-current docs.\n- **Instruction:** Overwrite docs/OVERSEER-HANDOVER.md with a block regenerated from the updated durable docs, not from memory.\n- **Trigger:** Run only after the durable docs are updated.\n- **When not to run:** Skip if the docs have not yet been updated this handover.\n- **Requires:** vault_scope:project, file:docs/OVERSEER-HANDOVER.md\n- **Boundaries:**\n - The block is a projection of the docs — never hand-written ahead of them\n - No secrets in the block\n- **Inputs:** docs_update_ref (from flow_overseer_handover#4.outputs.docs_update_ref)\n- **Outputs:** handover_block_ref:string\n- **Output shape:** An overwritten docs/OVERSEER-HANDOVER.md whose block matches the durable docs.\n- **Verification:** artifact_exists — The living file is overwritten and its block matches the docs, not memory. (evidence required: yes)\n\n## Step 6\n\n- **Owned job:** Emit the block as the first message of the next chat.\n- **Instruction:** Paste the regenerated handover block as the first message of the new chat so the overseer role resumes with no prior history.\n- **Trigger:** Run once the living file holds the current block.\n- **When not to run:** Skip if no new chat is being started.\n- **Requires:** vault_scope:project, file:docs/OVERSEER-HANDOVER.md\n- **Boundaries:**\n - Emit only the projected block — do not add scope beyond the durable docs\n- **Inputs:** handover_block_ref (from flow_overseer_handover#5.outputs.handover_block_ref)\n- **Outputs:** emitted_block:text\n- **Output shape:** The handover block, emitted as the first message of the next chat.\n- **Verification:** human_review — A new overseer can resume from the emitted block with no prior chat history. (evidence required: yes)\n","generated_from_canonical":true,"editable":false,"fidelity":{"dropped_fields":[]}},"staleness":{"stale":false,"projection_version":"0.2.0","latest_version":"0.2.0"},"generator":{"generator_version":"1","content_hash":"sha256:b841812d147bce0d0818e17a3e420c985656ccb83e85ef9eeadba9a992be789c","generated_at":"2026-06-20T22:15:12.428Z"}}
571 [exit=0]
572
573 === demo complete — artifacts + diffs + transcript under docs/evidence/7A-12/artifacts ===
File History 1 commit
sha256:8915fe406161f95c1681f9469375e7bae5b28c884f00bedbdef65e4b0cd0738d docs(flow): commit FLOW-V0-SPEC.md hygiene for 7A-INT merge Human 14 hours ago