aaronrene / knowtation public
flow_overseer_handover.json json
212 lines 8.9 KB
Raw
sha256:8915fe406161f95c1681f9469375e7bae5b28c884f00bedbdef65e4b0cd0738d docs(flow): commit FLOW-V0-SPEC.md hygiene for 7A-INT merge Human 19 hours ago
1 {
2 "flow": {
3 "schema": "knowtation.flow/v0",
4 "flow_id": "flow_overseer_handover",
5 "title": "Overseer handover",
6 "version": "0.1.0",
7 "scope": "project",
8 "summary": "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 "tags": ["process", "handover", "coordination", "dogfood"],
10 "steps": [
11 "flow_overseer_handover#1",
12 "flow_overseer_handover#2",
13 "flow_overseer_handover#3",
14 "flow_overseer_handover#4",
15 "flow_overseer_handover#5",
16 "flow_overseer_handover#6"
17 ],
18 "inputs": [],
19 "vault_mirror_path": "meta/flows/overseer-handover.md",
20 "updated": "2026-06-20T00:00:00Z",
21 "truncated": false
22 },
23 "steps": [
24 {
25 "schema": "knowtation.flow_step/v0",
26 "step_id": "flow_overseer_handover#1",
27 "flow_id": "flow_overseer_handover",
28 "ordinal": 1,
29 "owned_job": "Snapshot truth per repo, confirmed via muse -C (not ambient).",
30 "instruction": "Run muse -C <abs path> status and log for each repo (Scooling, Knowtation, MuseHub) and capture branch, HEAD sha, and dirty state.",
31 "trigger": "Run when a chat is getting long, a chat switch is needed, or a session ends with multi-repo state in flight.",
32 "when_not_to_run": "Skip if no multi-repo state is in flight and no handover is needed.",
33 "requires": [
34 { "kind": "vault_scope", "id": "project" },
35 { "kind": "tool", "id": "muse_cli" }
36 ],
37 "boundaries": [
38 "Always target each repo with muse -C <absolute-path> \u2014 a bare muse can report an ambient repo",
39 "Read only \u2014 do not commit or checkout during the snapshot",
40 "No secrets in captured output"
41 ],
42 "skill_refs": [
43 { "kind": "cli", "id": "muse -C <abs-repo-path> status" },
44 { "kind": "cli", "id": "muse -C <abs-repo-path> log" }
45 ],
46 "inputs": [],
47 "outputs": [
48 { "name": "per_repo_state", "type": "text" }
49 ],
50 "output_shape": "A per-repo line for each repo with real branch, HEAD sha, and dirty flag, each confirmed via -C.",
51 "verification": {
52 "kind": "artifact_exists",
53 "evidence_required": true,
54 "description": "Each repo is confirmed via -C (not ambient) and every repo line carries a real branch and sha."
55 },
56 "automatable": "manual"
57 },
58 {
59 "schema": "knowtation.flow_step/v0",
60 "step_id": "flow_overseer_handover#2",
61 "flow_id": "flow_overseer_handover",
62 "ordinal": 2,
63 "owned_job": "Record the current step, next action, and open gates/blockers.",
64 "instruction": "Write down the current initiative step, the unambiguous next action, and any open gates or blockers.",
65 "trigger": "Run after per-repo truth is captured.",
66 "when_not_to_run": "Skip if the next action and gates are already recorded and unchanged.",
67 "requires": [
68 { "kind": "vault_scope", "id": "project" }
69 ],
70 "boundaries": [
71 "State the next action so it needs no chat history to interpret"
72 ],
73 "skill_refs": [],
74 "inputs": [
75 { "name": "per_repo_state", "from": "flow_overseer_handover#1.outputs.per_repo_state" }
76 ],
77 "outputs": [
78 { "name": "step_and_gates", "type": "text" }
79 ],
80 "output_shape": "A current-step line, a next-action line, and an open-gates/blockers list.",
81 "verification": {
82 "kind": "human_review",
83 "evidence_required": true,
84 "description": "The next action is unambiguous."
85 },
86 "automatable": "manual"
87 },
88 {
89 "schema": "knowtation.flow_step/v0",
90 "step_id": "flow_overseer_handover#3",
91 "flow_id": "flow_overseer_handover",
92 "ordinal": 3,
93 "owned_job": "List the boundaries and the cross-repo wiring touched this session.",
94 "instruction": "Enumerate the boundaries to honor and the cross-repo wiring touched this session.",
95 "trigger": "Run after the step and gates are recorded.",
96 "when_not_to_run": "Skip if no cross-repo wiring was touched and boundaries are already listed.",
97 "requires": [
98 { "kind": "vault_scope", "id": "project" }
99 ],
100 "boundaries": [
101 "Boundaries are stated explicitly, not assumed"
102 ],
103 "skill_refs": [],
104 "inputs": [],
105 "outputs": [
106 { "name": "boundaries_and_wiring", "type": "text" }
107 ],
108 "output_shape": "An explicit boundaries list and a cross-repo wiring list for the session.",
109 "verification": {
110 "kind": "human_review",
111 "evidence_required": true,
112 "description": "Boundaries are explicit and the cross-repo wiring touched is listed."
113 },
114 "automatable": "manual"
115 },
116 {
117 "schema": "knowtation.flow_step/v0",
118 "step_id": "flow_overseer_handover#4",
119 "flow_id": "flow_overseer_handover",
120 "ordinal": 4,
121 "owned_job": "Update the durable docs FIRST.",
122 "instruction": "Update the ROADMAP snapshot, the next-session plan, and the coordination doc so they match reality before any block is written.",
123 "trigger": "Run after truth, step/gates, and boundaries are captured.",
124 "when_not_to_run": "Never skip when handing off \u2014 docs-first ordering is mandatory.",
125 "requires": [
126 { "kind": "vault_scope", "id": "project" },
127 { "kind": "file", "id": "docs/ROADMAP.md" },
128 { "kind": "file", "id": "docs/PRODUCT-SURFACES-NEXT-SESSION-PLAN.md" },
129 { "kind": "file", "id": "docs/CROSS-REPO-COORDINATION.md" }
130 ],
131 "boundaries": [
132 "Update durable docs before regenerating any handover block",
133 "Docs are the source of truth, the block is a projection of them"
134 ],
135 "skill_refs": [],
136 "inputs": [],
137 "outputs": [
138 { "name": "docs_update_ref", "type": "string" }
139 ],
140 "output_shape": "Updated ROADMAP snapshot, next-session plan, and coordination doc reflecting reality.",
141 "verification": {
142 "kind": "artifact_exists",
143 "evidence_required": true,
144 "description": "The durable docs are updated and match reality before any block is written."
145 },
146 "automatable": "manual"
147 },
148 {
149 "schema": "knowtation.flow_step/v0",
150 "step_id": "flow_overseer_handover#5",
151 "flow_id": "flow_overseer_handover",
152 "ordinal": 5,
153 "owned_job": "Regenerate the handover block into the living file from the now-current docs.",
154 "instruction": "Overwrite docs/OVERSEER-HANDOVER.md with a block regenerated from the updated durable docs, not from memory.",
155 "trigger": "Run only after the durable docs are updated.",
156 "when_not_to_run": "Skip if the docs have not yet been updated this handover.",
157 "requires": [
158 { "kind": "vault_scope", "id": "project" },
159 { "kind": "file", "id": "docs/OVERSEER-HANDOVER.md" }
160 ],
161 "boundaries": [
162 "The block is a projection of the docs \u2014 never hand-written ahead of them",
163 "No secrets in the block"
164 ],
165 "skill_refs": [],
166 "inputs": [
167 { "name": "docs_update_ref", "from": "flow_overseer_handover#4.outputs.docs_update_ref" }
168 ],
169 "outputs": [
170 { "name": "handover_block_ref", "type": "string" }
171 ],
172 "output_shape": "An overwritten docs/OVERSEER-HANDOVER.md whose block matches the durable docs.",
173 "verification": {
174 "kind": "artifact_exists",
175 "evidence_required": true,
176 "description": "The living file is overwritten and its block matches the docs, not memory."
177 },
178 "automatable": "manual"
179 },
180 {
181 "schema": "knowtation.flow_step/v0",
182 "step_id": "flow_overseer_handover#6",
183 "flow_id": "flow_overseer_handover",
184 "ordinal": 6,
185 "owned_job": "Emit the block as the first message of the next chat.",
186 "instruction": "Paste the regenerated handover block as the first message of the new chat so the overseer role resumes with no prior history.",
187 "trigger": "Run once the living file holds the current block.",
188 "when_not_to_run": "Skip if no new chat is being started.",
189 "requires": [
190 { "kind": "vault_scope", "id": "project" },
191 { "kind": "file", "id": "docs/OVERSEER-HANDOVER.md" }
192 ],
193 "boundaries": [
194 "Emit only the projected block \u2014 do not add scope beyond the durable docs"
195 ],
196 "skill_refs": [],
197 "inputs": [
198 { "name": "handover_block_ref", "from": "flow_overseer_handover#5.outputs.handover_block_ref" }
199 ],
200 "outputs": [
201 { "name": "emitted_block", "type": "text" }
202 ],
203 "output_shape": "The handover block, emitted as the first message of the next chat.",
204 "verification": {
205 "kind": "human_review",
206 "evidence_required": true,
207 "description": "A new overseer can resume from the emitted block with no prior chat history."
208 },
209 "automatable": "manual"
210 }
211 ]
212 }
File History 1 commit
sha256:8915fe406161f95c1681f9469375e7bae5b28c884f00bedbdef65e4b0cd0738d docs(flow): commit FLOW-V0-SPEC.md hygiene for 7A-INT merge Human 19 hours ago