aaronrene / knowtation public
docs flow feat/flow-v0-spec #3 / 3
aaronrene · 3 days ago · Jun 20, 2026 · Diff

docs(flow): author canonical Flow v0 spec (7A-2)

Turn the running-start outline into the canonical Flow v0 spec on feat/flow-v0-spec. Ratify the five wire schemas against scooling/docs/FLOW-PLATFORM-ARCHITECTURE.md and pin enums, id formats, and the run step-state shape.

- v0 = ordered step list (not DAG) - storage: Option A (Hub index primary + optional vault mirror) - API parity contract across CLI / MCP / Hub REST (routes gated, spec only) - projection generator contract (dogfood: own repo guidance) + staleness/fidelity - capture flywheel contract + thresholds (inert in v0) - defaults confirmed; seven-tier test plan written - security/privacy checklist fully signed off

Scope: spec only. Starter Flows = 7A-3; generator impl = 7A-10/11; live authoring/capture/execution = gated 7A-L1..L5.

sha256:b688370aae6be861872265137452097e5527c2bf2d88a941066a9ae6b661661c sha
sha256:94ec65bd2b200240ac785a97cf14c5db066832bd608a24d6a9c151f17b918b02 parent
+52 symbols
1 changed · 854 in snapshot files
sha256:4a16434e7725d1d46a440f6ba7fcda26c0168a7bf56753b4123be8e56f4b4367 snapshot
+52
symbols added
1
file changed
854
files in snapshot
0
dead code introduced
Semantic Changes 52 symbols
~ docs/FLOW-V0-SPEC.md .md 52 symbols added
+ Flow v0 — Canonical Spec (Knowtation) section Flow v0 — Canonical Spec (Knowtation) L1–443
+ Purpose and scope section 0. Purpose and scope L50–75
+ md) section 1. Data model and wire schemas (ratified vs FLOW-PLATFORM-ARCHITECTURE.md) L75–197
+ 1 Pinned enums (v0) section 1.1 Pinned enums (v0) L81–97
+ table section table L83–96
+ 2 Pinned id formats (v0) section 1.2 Pinned id formats (v0) L97–109
+ table section table L99–105
+ flow/v0 — definition section 1.3 knowtation.flow/v0 — definition L109–126
+ table section table L111–125
+ flow_step/v0 — one step (full skill-primitive anatomy) section 1.4 knowtation.flow_step/v0 — one step (full skill-primitive anatomy) L126–150
+ table section table L128–146
+ flow_run/v0 — execution instance (canonical run state) section 1.5 knowtation.flow_run/v0 — execution instance (canonical run state) L150–166
+ table section table L152–163
+ flow_candidate/v0 — flywheel proposal (never an auto-Flow) section 1.6 knowtation.flow_candidate/v0 — flywheel proposal (never an auto-Flow) L166–182
+ table section table L168–181
+ flow_projection/v0 — derived, read-only harness rendering section 1.7 knowtation.flow_projection/v0 — derived, read-only harness rendering L182–197
+ table section table L184–194
+ Open items / decisions section 10. Open items / decisions L402–416
+ table section table L404–413
+ Storage section 2. Storage L197–240
+ 1 Index (primary) section 2.1 Index (primary) L202–211
+ table section table L204–210
+ 2 Vault mirror (optional, type: flow) section 2.2 Vault mirror (optional, type: flow) L211–230
+ code[yaml] variable variable code[yaml] L215–226
+ 3 Retention / deletion section 2.3 Retention / deletion L230–240
+ table section table L232–237
+ API surfaces (triple-exposed, identical contract) section 3. API surfaces (triple-exposed, identical contract) L240–289
+ 1 CLI section 3.1 CLI L251–263
+ code variable variable code L253–262
+ 2 MCP tools (role-gated) section 3.2 MCP tools (role-gated) L263–273
+ table section table L265–272
+ 3 Hub REST section 3.3 Hub REST L273–289
+ table section table L275–283
+ Projection generator (dogfood target) section 4. Projection generator (dogfood target) L289–307
+ The capture flywheel (inert-first) section 5. The capture flywheel (inert-first) L307–345
+ 1 Detection signals (observational, content-minimized) section 5.1 Detection signals (observational, content-minimized) L314–327
+ table section table L316–323
+ 2 Recommended thresholds (v0 defaults; tunable) section 5.2 Recommended thresholds (v0 defaults; tunable) L327–336
+ table section table L329–335
+ 3 Guardrails (must hold) section 5.3 Guardrails (must hold) L336–345
+ Security and privacy checklist (signed off — 7A-2) section 6. Security and privacy checklist (signed off — 7A-2) L345–363
+ table section table L347–360
+ Defaults (confirmed for v0) section 7. Defaults (confirmed for v0) L363–376
+ table section table L365–373
+ Starter Flow definitions — deferred to 7A-3 (not authored here) section 8. Starter Flow definitions — deferred to 7A-3 (not authored here) L376–385
+ Test plan — seven tiers section 9. Test plan — seven tiers L385–402
+ table section table L390–399
+ Acceptance criteria for this spec (7A-2) section Acceptance criteria for this spec (7A-2) L416–426
+ Handoff notes (for the next step, 7A-3) section Handoff notes (for the next step, 7A-3) L435–443
+ Non-goals (v0) section Non-goals (v0) L426–435
+ Simple summary section Simple summary L19–32
+ Technical summary section Technical summary L32–50
Files Changed
+1
854 in snapshot
+ docs/FLOW-V0-SPEC.md .md
← Older Oldest on feat/flow-v0-spec
All commits Newer feat(flow): author 7A-3 starter Flow set (knowtation.flow/v0 + f… sha256:45df842f79e78cfb7aebe19d88e2d86e2527e3db4d087297ee853c40c543e830

0 comments

No comments yet. Be the first to start the discussion.

To add a comment, use the Muse CLI: muse hub commit comment sha256:b688370aae6be861872265137452097e5527c2bf2d88a941066a9ae6b661661c --body "your comment"