aaronrene / knowtation public
flow_multi_repo_change.json json
279 lines 11.7 KB
Raw
sha256:8915fe406161f95c1681f9469375e7bae5b28c884f00bedbdef65e4b0cd0738d docs(flow): commit FLOW-V0-SPEC.md hygiene for 7A-INT merge Human 10 hours ago
1 {
2 "flow": {
3 "schema": "knowtation.flow/v0",
4 "flow_id": "flow_multi_repo_change",
5 "title": "Multi-repo substrate + top-layer change",
6 "version": "0.1.0",
7 "scope": "project",
8 "summary": "A reusable, canonical-first procedure for any change spanning the substrate, the canonical layer, and the top layer across the connected repos.",
9 "tags": ["process", "cross-repo", "coordination", "dogfood"],
10 "steps": [
11 "flow_multi_repo_change#1",
12 "flow_multi_repo_change#2",
13 "flow_multi_repo_change#3",
14 "flow_multi_repo_change#4",
15 "flow_multi_repo_change#5",
16 "flow_multi_repo_change#6",
17 "flow_multi_repo_change#7",
18 "flow_multi_repo_change#8"
19 ],
20 "inputs": [
21 { "name": "change_summary", "type": "string", "required": true }
22 ],
23 "vault_mirror_path": "meta/flows/multi-repo-change.md",
24 "updated": "2026-06-20T00:00:00Z",
25 "truncated": false
26 },
27 "steps": [
28 {
29 "schema": "knowtation.flow_step/v0",
30 "step_id": "flow_multi_repo_change#1",
31 "flow_id": "flow_multi_repo_change",
32 "ordinal": 1,
33 "owned_job": "Orient: establish the current step and its owning repo before touching anything.",
34 "instruction": "Read the ROADMAP Current Status Snapshot, the cross-repo coordination doc, and the initiative spec.",
35 "trigger": "Run at the start of any change that may span substrate, canonical layer, and top layer.",
36 "when_not_to_run": "Skip for a single-repo change with no canonical or substrate dependency.",
37 "requires": [
38 { "kind": "vault_scope", "id": "project" },
39 { "kind": "file", "id": "docs/ROADMAP.md" },
40 { "kind": "file", "id": "docs/CROSS-REPO-COORDINATION.md" }
41 ],
42 "boundaries": [
43 "Read only \u2014 no edits during orientation",
44 "Treat doc contents as the source of truth over chat memory"
45 ],
46 "skill_refs": [],
47 "inputs": [
48 { "name": "change_summary", "from": "flow.inputs.change_summary" }
49 ],
50 "outputs": [
51 { "name": "current_step", "type": "text" }
52 ],
53 "output_shape": "A stated current step id and the repo that owns it.",
54 "verification": {
55 "kind": "human_review",
56 "evidence_required": true,
57 "description": "You can state the current step id and its owning repo."
58 },
59 "automatable": "manual"
60 },
61 {
62 "schema": "knowtation.flow_step/v0",
63 "step_id": "flow_multi_repo_change#2",
64 "flow_id": "flow_multi_repo_change",
65 "ordinal": 2,
66 "owned_job": "Locate: map the change to the repo(s) and VCS rule it belongs in.",
67 "instruction": "Use the decision table to assign each part of the change to a repo and its VCS discipline.",
68 "trigger": "Run after orientation, before any branching.",
69 "when_not_to_run": "Skip if the change has already been located to its repos this session.",
70 "requires": [
71 { "kind": "vault_scope", "id": "project" },
72 { "kind": "file", "id": "docs/CROSS-REPO-COORDINATION.md" }
73 ],
74 "boundaries": [
75 "Do not move canonical schema/permission work into the consumer repo",
76 "Respect canonical-first ordering"
77 ],
78 "skill_refs": [],
79 "inputs": [],
80 "outputs": [
81 { "name": "repo_assignment", "type": "text" }
82 ],
83 "output_shape": "A list mapping each change part to a repo and its VCS rule.",
84 "verification": {
85 "kind": "human_review",
86 "evidence_required": true,
87 "description": "Each change is assigned a repo and VCS rule."
88 },
89 "automatable": "manual"
90 },
91 {
92 "schema": "knowtation.flow_step/v0",
93 "step_id": "flow_multi_repo_change#3",
94 "flow_id": "flow_multi_repo_change",
95 "ordinal": 3,
96 "owned_job": "Branch: create a feature branch in each touched repo (never main).",
97 "instruction": "Create a feature branch per touched repo, confirming each repo explicitly with muse -C against its absolute path.",
98 "trigger": "Run once repos are assigned and before any code changes.",
99 "when_not_to_run": "Skip for a repo that is not touched by this change.",
100 "requires": [
101 { "kind": "vault_scope", "id": "project" },
102 { "kind": "tool", "id": "muse_cli" }
103 ],
104 "boundaries": [
105 "Never work directly on main in any repo",
106 "Always target the repo with muse -C <absolute-path> \u2014 a bare muse can resolve to an ambient repo",
107 "MuseHub is Muse-only \u2014 never git/gh there"
108 ],
109 "skill_refs": [
110 { "kind": "cli", "id": "muse -C <abs-repo-path> status" },
111 { "kind": "cli", "id": "muse -C <abs-repo-path> branch feat/<desc>" }
112 ],
113 "inputs": [],
114 "outputs": [
115 { "name": "branches", "type": "text" }
116 ],
117 "output_shape": "A feature branch name per touched repo, each verified via muse -C.",
118 "verification": {
119 "kind": "artifact_exists",
120 "evidence_required": true,
121 "description": "muse -C status shows a feature branch (not main) in each touched repo."
122 },
123 "automatable": "manual"
124 },
125 {
126 "schema": "knowtation.flow_step/v0",
127 "step_id": "flow_multi_repo_change#4",
128 "flow_id": "flow_multi_repo_change",
129 "ordinal": 4,
130 "owned_job": "Implement canonical-first: substrate/schema \u2192 canonical logic \u2192 consumer \u2192 enrichment.",
131 "instruction": "Make changes in dependency order so no consumer is wired before the canonical surface it reads exists.",
132 "trigger": "Run after branches exist in each touched repo.",
133 "when_not_to_run": "Skip a layer this change does not touch, but never invert the dependency order.",
134 "requires": [
135 { "kind": "vault_scope", "id": "project" }
136 ],
137 "boundaries": [
138 "Never wire a consumer before its canonical surface exists",
139 "Knowtation stays the canonical store + permission authority; the consumer stores nothing canonical",
140 "No secrets in code, adapters, projections, or logs"
141 ],
142 "skill_refs": [],
143 "inputs": [],
144 "outputs": [
145 { "name": "implementation_notes", "type": "text" }
146 ],
147 "output_shape": "Changes landed in dependency order, layer by layer.",
148 "verification": {
149 "kind": "human_review",
150 "evidence_required": true,
151 "description": "Dependency order is respected (e.g. schema before adapter)."
152 },
153 "automatable": "manual"
154 },
155 {
156 "schema": "knowtation.flow_step/v0",
157 "step_id": "flow_multi_repo_change#5",
158 "flow_id": "flow_multi_repo_change",
159 "ordinal": 5,
160 "owned_job": "Test per tier where the logic lives.",
161 "instruction": "Run the seven-tier tests in the repo runner where the changed logic lives (Docker for MuseHub) and capture a green run.",
162 "trigger": "Run after implementing a layer's changes, before committing it.",
163 "when_not_to_run": "Skip for a repo whose code was not changed by this change.",
164 "requires": [
165 { "kind": "vault_scope", "id": "project" },
166 { "kind": "tool", "id": "repo_test_runner" }
167 ],
168 "boundaries": [
169 "Run tests in the repo where the logic lives, not on the host for MuseHub",
170 "No network in unit tests"
171 ],
172 "skill_refs": [],
173 "inputs": [],
174 "outputs": [
175 { "name": "test_run_ref", "type": "string" }
176 ],
177 "output_shape": "A recorded green test run for the touched tier(s) in that repo's runner.",
178 "verification": {
179 "kind": "artifact_exists",
180 "evidence_required": true,
181 "description": "A green test-run record exists for the touched tier in that repo's runner."
182 },
183 "automatable": "manual"
184 },
185 {
186 "schema": "knowtation.flow_step/v0",
187 "step_id": "flow_multi_repo_change#6",
188 "flow_id": "flow_multi_repo_change",
189 "ordinal": 6,
190 "owned_job": "Commit per repo rule, with no secrets.",
191 "instruction": "Commit using each repo's VCS rule (Muse/Git per the table), confirming no secrets and no docs-only PR to Knowtation main.",
192 "trigger": "Run once tests are green for the touched tier in a repo.",
193 "when_not_to_run": "Skip if tests are not green, or the only change in a Knowtation PR to main would be docs.",
194 "requires": [
195 { "kind": "vault_scope", "id": "project" },
196 { "kind": "tool", "id": "muse_cli" }
197 ],
198 "boundaries": [
199 "No secrets in any commit",
200 "No docs-only PR to Knowtation main \u2014 ship docs with their code/tests",
201 "MuseHub is Muse-only; never git push origin main on Knowtation"
202 ],
203 "skill_refs": [
204 { "kind": "cli", "id": "muse -C <abs-repo-path> commit -m \"<message>\"" }
205 ],
206 "inputs": [],
207 "outputs": [
208 { "name": "commit_refs", "type": "text" }
209 ],
210 "output_shape": "A commit recorded per touched repo following its VCS rule.",
211 "verification": {
212 "kind": "artifact_exists",
213 "evidence_required": true,
214 "description": "A commit is recorded per repo and no docs-only PR to Knowtation main was opened."
215 },
216 "automatable": "manual"
217 },
218 {
219 "schema": "knowtation.flow_step/v0",
220 "step_id": "flow_multi_repo_change#7",
221 "flow_id": "flow_multi_repo_change",
222 "ordinal": 7,
223 "owned_job": "Cross-link: record cross-repo references and update the ROADMAP snapshot.",
224 "instruction": "Capture external_ref and commit ids across repos and update the ROADMAP Current Status Snapshot to match reality.",
225 "trigger": "Run after commits land in the touched repos.",
226 "when_not_to_run": "Skip if no cross-repo reference exists and the snapshot already matches reality.",
227 "requires": [
228 { "kind": "vault_scope", "id": "project" },
229 { "kind": "file", "id": "docs/ROADMAP.md" }
230 ],
231 "boundaries": [
232 "Cross-repo refs are commit ids/handles only \u2014 no secrets",
233 "Update the durable snapshot, not just chat scrollback"
234 ],
235 "skill_refs": [],
236 "inputs": [],
237 "outputs": [
238 { "name": "snapshot_update_ref", "type": "string" }
239 ],
240 "output_shape": "An updated ROADMAP snapshot plus captured cross-repo ids.",
241 "verification": {
242 "kind": "artifact_exists",
243 "evidence_required": true,
244 "description": "The ROADMAP snapshot is updated and cross-repo ids are captured."
245 },
246 "automatable": "manual"
247 },
248 {
249 "schema": "knowtation.flow_step/v0",
250 "step_id": "flow_multi_repo_change#8",
251 "flow_id": "flow_multi_repo_change",
252 "ordinal": 8,
253 "owned_job": "Handover: refresh the handover snapshot so a fresh chat can resume.",
254 "instruction": "Run the Overseer handover Flow (docs-first) to regenerate the living handover block from the now-current docs.",
255 "trigger": "Run at the end of the change, or when the session is wrapping up with multi-repo state in flight.",
256 "when_not_to_run": "Skip if no multi-repo state is in flight and no handover is needed.",
257 "requires": [
258 { "kind": "vault_scope", "id": "project" },
259 { "kind": "file", "id": "docs/OVERSEER-HANDOVER.md" }
260 ],
261 "boundaries": [
262 "Docs-first \u2014 update durable docs before regenerating the block",
263 "The block is a projection of the docs, never hand-written from memory"
264 ],
265 "skill_refs": [],
266 "inputs": [],
267 "outputs": [
268 { "name": "handover_ref", "type": "string" }
269 ],
270 "output_shape": "A refreshed handover block in docs/OVERSEER-HANDOVER.md matching the durable docs.",
271 "verification": {
272 "kind": "artifact_exists",
273 "evidence_required": true,
274 "description": "A fresh handover block exists and a new chat could resume from it alone."
275 },
276 "automatable": "manual"
277 }
278 ]
279 }
File History 1 commit
sha256:8915fe406161f95c1681f9469375e7bae5b28c884f00bedbdef65e4b0cd0738d docs(flow): commit FLOW-V0-SPEC.md hygiene for 7A-INT merge Human 10 hours ago