Flow v0 — Canonical Spec (Knowtation)

Status: DRAFT for acceptance — step 7A-2. Authored on branch feat/flow-v0-spec (Thinking). This is the canonical spec for the Flow procedure layer: schemas, storage, API contract, projection generator, capture flywheel, defaults, seven-tier test plan, and the signed-off security/privacy checklist. The Scooling-side architecture/consumer doc is scooling/docs/FLOW-PLATFORM-ARCHITECTURE.md and the five wire schemas here are ratified against its § Wire schemas.

Cross-repo note: Flow is canonical in Knowtation (store, schemas, CLI/MCP/Hub APIs, projection generator). Scooling is a consumer. MuseHub enrichment (versioning/releases/provenance) is specified in MUSE_HUB/musehub/docs/FLOW-ENRICHMENT-CONTRACT-7A-L5.md (7A-L5a frozen; 7A-L5b impl). See scooling/docs/CROSS-REPO-COORDINATION.md.

Scope fence for this step (7A-2): spec only. No code, no routes, no live effects. Starter Flow definitions = 7A-3; projection-generator implementation = 7A-10/7A-11; live authoring/capture/ automatable execution = gated 7A-L1..L5.

---

Simple summary

A Flow is a saved, reusable procedure — an ordered checklist of steps that says how a job gets done, what each step needs, and how you know it is actually finished (the proof, not just a checkbox). Flows live in one canonical place (Knowtation), the same way notes and the calendar already do. The command line, the MCP plug-in, the Hub website, and Scooling all read and run the same Flows — change one once and every surface sees the update, with no copying and no drift.

This document is the precise contract: the data shapes, where they are stored, the identical API on all three surfaces, how a canonical Flow is projected into harness files (Cursor rules, AGENTS.md), how repeated work is proposed (never auto-saved) as a new Flow, the safe defaults, and the proof (tests + security sign-off) required before any of it is built.

Technical summary

• Canonical owner: Knowtation (definitions, steps, verification contracts, run state, candidates, projections, scope policy). Scooling is a consumer/UI; never a second store.
• Wire schemas (v0, open, versioned): knowtation.flow/v0, knowtation.flow_step/v0, knowtation.flow_run/v0, knowtation.flow_candidate/v0, knowtation.flow_projection/v0 — each carries a schema discriminator so clients detect capability without sniffing.
• Step model: v0 is an ordered list, not a DAG. Branching/parallel steps are deferred.
• Storage: Option A (calendar parity) — structured records in the Hub/canister index (for scope/range/version queries) plus an optional vault Markdown mirror (type: flow) for portability/offline.
• API parity: identical read/list/run/propose/project contract on CLI, MCP tools, and Hub REST, mirroring AGENT-INTEGRATION.md. Scope is enforced server-side; deny by default.
• Defaults: scope personal; external/automatable effects off; v0 verification kinds human_review + artifact_exists active first (others reserved, parse-accepted, runtime-gated).

---

0. Purpose and scope

Flow is a canonical, versioned, scoped procedure substrate owned by Knowtation and exposed over the existing three agent surfaces (CLI, MCP, Hub REST) plus a harness-projection layer. It mirrors the calendar architecture: canonical store + open wire schema + scoped retrieval + Scooling as consumer. Knowtation already holds what you know (notes, summaries, memory); Flow adds how you work (procedure), so an agent never has to relearn a workflow each session.

In scope for v0

• Definitions, steps (full skill-primitive anatomy), runs, candidates, projections — as open schemas.
• Read / list / get / propose; export / import (bundle round-trip).
• One projection target as the dogfood proof (own repo guidance — AGENTS.md / .cursor/rules / .cursorrules).
• Scope enforcement (personal | project | org) server-side; review-before-write for durable changes.

Out of scope for v0 (each a separate later gate)

• Live automatable step execution (7A-L3); hosted projection + external-agent bundles (7A-L2); live capture flywheel detection (7A-L4); MuseHub enrichment — step-level history, semver-typed change impact, releases, reviewed merge, provenance-anchored evidence, social discovery (7A-L5).
• DAG / branching / parallel steps (a later schema version).

---

1. Data model and wire schemas (ratified vs FLOW-PLATFORM-ARCHITECTURE.md)

All five shapes are open, versioned, and discriminated by a schema field. They are ratified field-for-field against the architecture doc's § Wire schemas jsonc blocks; differences below are pins this spec adds (enums, id format, step-state shape), not divergences.

1.1 Pinned enums (v0)

Enum	Field	Values (v0)	Notes
Scope	flow.scope, run.scope, candidate.scope_hint	personal | project | org	Aligns with WorkspaceScopeAdapter; default personal
VerificationKind	flow_step.verification.kind	human_review | artifact_exists | value_match | test_pass | agent_check	Active in v0: human_review, artifact_exists. Others parse-valid but runtime-gated (deny until their gate)
Automatable	flow_step.automatable	manual | agent_assisted | automatable	automatable is inert in v0 (execution gate 7A-L3)
RunStatus	flow_run.status	pending | in_progress | blocked | done | abandoned
StepStateStatus	flow_run.step_states[].status	pending | in_progress | blocked | done | skipped	done requires verified: true when the step's contract sets evidence_required
SkillRefKind	flow_step.skill_refs[].kind	mcp_prompt | skill_pack | cli | external_tool	external_tool is inert in v0 (external-agent gate 7A-L2)
RequiresKind	flow_step.requires[].kind	vault_scope | tool | file | artifact	Pointers/handles only — never inline secrets
TriggerSignal	flow_candidate.trigger_signal	repetition | re_explanation | repeated_correction | review_debt | session_extraction
Confidence	flow_candidate.confidence	low | medium | high	Suppress low unless explicitly requested
CandidateStatus	flow_candidate.status	pending_review | promoted | rejected | merged_into:<flow_id>
Harness	flow_projection.harness	cursor_rule | cursor_skill | mcp_prompt | cli_runbook | agent_bundle

1.2 Pinned id formats (v0)

Object	*_id format	Example
Flow	flow_<slug> — slug is [a-z0-9_]{1,64}	flow_weekly_review
Step	<flow_id>#<ordinal> — ordinal is a 1-based integer	flow_weekly_review#1
Run	run_<token> — token is [a-z0-9_]{1,48}	run_2026w25
Candidate	cand_<token> — token is [a-z0-9]{4,32}	cand_7f3a

flow.version is semver (MAJOR.MINOR.PATCH); a flow_run pins flow_version; a flow_projection carries the flow_version it was generated from (used for staleness).

1.3 knowtation.flow/v0 — definition

Field	Type	Req	Description
schema	const knowtation.flow/v0	yes	Discriminator
flow_id	string (flow_<slug>)	yes	Stable id
title	string	yes	Human title
version	semver	yes	Bump on step/contract change
scope	Scope	yes	personal default
summary	string	yes	One-line purpose
tags	string[]	no	Light taxonomy (tags-first, see §7)
steps	string[] (step ids)	yes	Ordered refs; v0 = list, not DAG
inputs	{name, type, required}[]	no	Flow-level inputs
vault_mirror_path	string	no	Optional Markdown mirror location
updated	ISO8601	yes	Last change
truncated	boolean	yes	Content-minimization flag for retrieval

1.4 knowtation.flow_step/v0 — one step (full skill-primitive anatomy)

Field	Type	Req	Description
schema	const knowtation.flow_step/v0	yes
step_id	string (<flow_id>#<n>)	yes
flow_id	string	yes	Parent
ordinal	int (1-based)	yes	Position in the ordered list
owned_job	string	yes	The one thing the step is responsible for
instruction	string	yes	Imperative step text (untrusted input)
trigger	string	yes	When to use
when_not_to_run	string	yes	Anti-trigger
requires	{kind:RequiresKind, id}[]	no	Required tools/files/scope (handles only)
boundaries	string[]	yes	Must-not-do
skill_refs	{kind:SkillRefKind, id}[]	no	Composed primitives (opaque ids)
inputs	{name, from}[]	no	Bound from flow.inputs.* or prior step outputs
outputs	{name, type}[]	no	Declared outputs
output_shape	string	yes	What "the result" looks like
verification	{kind:VerificationKind, evidence_required:boolean, description}	yes	Done = proven
automatable	Automatable	yes	manual default; automatable inert in v0

Anatomy completeness rule: a record missing trigger, when_not_to_run, output_shape, or verification is a doc, not a Flow step, and MUST fail schema validation.

1.5 knowtation.flow_run/v0 — execution instance (canonical run state)

Field	Type	Req	Description
schema	const knowtation.flow_run/v0	yes
run_id	string (run_<token>)	yes
flow_id	string	yes
flow_version	semver	yes	Pinned; in-flight runs finish on the pinned version
scope	Scope	yes
status	RunStatus	yes
step_states	{step_id, status:StepStateStatus, evidence_ref?, verified:boolean}[]	yes	Per-step progress
started	ISO8601	yes
provenance	{actor, harness}	yes	Hashed actor id + harness label only

evidence_ref is a pointer (proposal id, run id, artifact id, hash) — never raw content.

1.6 knowtation.flow_candidate/v0 — flywheel proposal (never an auto-Flow)

Field	Type	Req	Description
schema	const knowtation.flow_candidate/v0	yes
candidate_id	string (cand_<token>)	yes
suggested_title	string	yes	Untrusted text
scope_hint	Scope	yes	Inferred; user confirms before promotion
trigger_signal	TriggerSignal	yes	Why it surfaced
observed_count	int	yes	e.g. recurred in N sessions
evidence_refs	string[]	yes	Pointers only — no raw content
draft_steps	string[]	no	Structural outline only (untrusted)
confidence	Confidence	yes	Suppress low unless asked
status	CandidateStatus	yes
provenance	{actor, harness}	yes	Hashes/labels only

1.7 knowtation.flow_projection/v0 — derived, read-only harness rendering

Field	Type	Req	Description
schema	const knowtation.flow_projection/v0	yes
flow_id	string	yes
flow_version	semver	yes	Projection is stale if it lags the source version
harness	Harness	yes	Target format
rendered	string	yes	Harness-specific text (no secrets)
generated_from_canonical	const true	yes
editable	const false	yes	A hand-edited projection is drift, not a source
fidelity	{dropped_fields: string[], notes?}	no	What a weaker harness could not express (see §4)

---

2. Storage

Decision: Option A (calendar parity). Primary = structured records in the Hub/canister index; secondary = an optional vault Markdown mirror for portability/offline.

2.1 Index (primary)

Concern	Decision
Index keys	flow_id, scope, vault_id, version, tags, updated
Query patterns	by scope, by tag, by id+version, "latest per flow_id within scope"
Records indexed	flow, flow_step, flow_run, flow_candidate, flow_projection (each by flow_id)
Scope enforcement	server-side via retrieval policy + WorkspaceScopeAdapter; deny by default

2.2 Vault mirror (optional, type: flow)

When vault_mirror_path is set, a Markdown note mirrors the definition for export/offline. Frontmatter:

---
type: flow
flow_id: flow_weekly_review
version: 1.4.0
scope: personal
tags: [review, weekly]
updated: 2026-06-20T00:00:00Z
canonical: hub        # the index is source of truth; the mirror is a projection of it
---

The mirror body is human-readable steps; it is derived from the index, never the reverse. A hand-edited mirror is reconciled as a proposal (review-before-write), not silently promoted.

2.3 Retention / deletion

Action	Effect
Deprecate a version	Mark non-latest; existing pinned runs/projections keep working
Delete a Flow	Tombstone the flow_id; runs retained as historical records (pointers only); projections invalidated
Delete the mirror note	Loses nothing — regenerable from the index

---

3. API surfaces (triple-exposed, identical contract)

Same contract across CLI / MCP / Hub REST, mirroring AGENT-INTEGRATION.md. v0 ships read/list/get/propose/project + export/import; run advancement and live authoring are gated (7A-L1/L3). Scope is enforced server-side on every surface; X-Vault-Id + role required; deny by default.

Spec-only note for 7A-2: routes are specified here, not implemented. Per the no-docs-only-PR rule, the OpenAPI shapes in docs/openapi.yaml are added in the same change as the routes (step 7A-10), not in this spec step.

3.1 CLI

knowtation flow list   [--scope personal|project|org] [--tag <t>] [--json]
knowtation flow get    <flow_id> [--version <semver>] [--json]
knowtation flow propose <bundle.json>          # review-before-write
knowtation flow export <flow_id> [--out <path>]
knowtation flow import <bundle.json>            # scope-checked; fails closed
knowtation flow project <flow_id> --harness <harness> [--out <path>]
# gated (not v0): knowtation flow run <flow_id> ...   (execution gate 7A-L3)

3.2 MCP tools (role-gated)

Tool	Purpose	v0
flow_list	List flows in scope	active (read)
flow_get	Get one flow + steps	active (read)
flow_propose	Propose a flow/edit (review tray)	active (proposal only)
flow_project	Render a projection for a harness	active (read/derive)
flow_run	Start/advance a run	gated (7A-L3)

3.3 Hub REST

Method + path	Purpose	v0
GET /api/v1/flows	List (scope/tag filters)	active
GET /api/v1/flows/{id}	Get definition + steps	active
POST /api/v1/flows	Propose new flow (review)	active (proposal)
GET /api/v1/flows/{id}/projection?harness=	Derived projection	active
GET /api/v1/flows/{id}/runs	List runs	active (read)
POST /api/v1/flows/{id}/runs	Start a run	gated (7A-L3)

All durable changes route through Knowtation proposals (intent, base_state_id, external_ref) — no new write path; no adapter writes canonical knowledge directly.

---

4. Projection generator (dogfood target)

A canonical Flow → harness artifact. Projections are derived, read-only, regenerable.

• v0 dogfood target: generate our own repo guidance — AGENTS.md, .cursor/rules/*, .cursorrules — as projections of canonical Flows. (Generator implementation is 7A-10/7A-11; this spec fixes the contract.)
• Anti-drift demo (acceptance for the pilot): edit canonical Flow → regenerate projection → diff shows no manual drift; deleting a projection loses nothing.
• Fidelity report: when a harness cannot express a field (e.g. anti-triggers), the projection's fidelity.dropped_fields records exactly what was dropped so the user knows.
• Staleness: a projection is stale when flow_projection.flow_version < the latest flow.version; surfaced via FlowProjectionAdapter.projectionStaleness.
• Drift: a hand-edited projection (editable:false violated) is detected as drift and never fed back as a write source.

---

5. The capture flywheel (inert-first)

Turns repeated work into a reviewable candidate — never silently. Detection produces a flow_candidate/v0 proposal; a human approves/edits/rejects; only on approval does a flow/v0 exist. Detection is inert in v0 (live detection is gate 7A-L4); this spec fixes the contract + thresholds.

5.1 Detection signals (observational, content-minimized)

Signal (trigger_signal)	Observes	Suggests
repetition	Same ordered step/skill-ref sequence across ≥ N sessions	A stable procedure is being re-derived
re_explanation	User re-types the same standing instruction	A missing captured procedure
repeated_correction	User corrects the agent the same way repeatedly	A missing boundary/anti-trigger
review_debt	A step type reaches "done" but fails human inspection	A missing verification contract
session_extraction	End-of-session opt-in check: "recurring, non-obvious procedure worth saving?"	Explicit capture moment (usually "no")

Signals derive from session metadata + bounded structural patterns (ids, hashes, counts) — never raw prompts, completions, or note bodies.

5.2 Recommended thresholds (v0 defaults; tunable)

Knob	Default	Rationale
N repetitions before surfacing	3	High bar; most sessions produce no candidate
Minimum confidence surfaced	medium	Suppress low unless explicitly asked
Per-session candidate cap	2	Prevent candidate spam / prompt-bloat-in-a-new-place
Dedup	merge into existing flow when ≥ 0.8 structural overlap	Offer "merge into" over "create parallel"

5.3 Guardrails (must hold)

• No silent promotion — review-before-write is mandatory.
• Privacy — pointers/hashes/bounded enums only; scope inferred then user-confirmed, never widened.
• Untrusted input — candidate titles/draft steps are untrusted prompt content.
• Opt-in — end-of-session extraction is user-controlled; classroom/minor policy may disable capture.

---

6. Security and privacy checklist (signed off — 7A-2)

#	Gate	Status	Notes
1	Scope is authorization, enforced server-side; deny by default	Accepted	WorkspaceScopeAdapter + Knowtation retrieval policy; client filters never trusted; truncated for content-minimized reads
2	Step text + skill refs treated as untrusted input (prompt-injection)	Accepted	instruction/boundaries/draft_steps are data, not commands; cannot escalate permissions or widen scope from inside a Flow
3	Imported / community Flows sandboxed	Accepted	Import enforces tool allowlist + scope; review required before an imported Flow runs with any privilege; external_tool skill-ref inert in v0
4	Verification evidence = pointers/hashes/bounded enums, never raw private content/secrets	Accepted	evidence_ref, evidence_refs[], provenance carry ids/hashes/labels only
5	Durable edits + run outcomes route through proposals (review-before-write)	Accepted	flow_propose / POST /flows → proposals (intent, base_state_id, external_ref); no direct canonical write
6	No secrets in definitions, projections, logs, provenance, responses	Accepted	requires/skill_refs reference handles; projections carry no secrets; OAuth/token shapes never appear in Flow objects
7	Automatable steps gated by model consent + cost caps	Accepted	automatable inert in v0; execution behind ModelRuntimeAdapter consent + BillingAdapter caps at gate 7A-L3; classroom/minor may forbid
8	Projections derived/read-only; hand-edited projection = drift	Accepted	generated_from_canonical:true, editable:false; drift detected, never used as write source
9	Classroom / minors policy may cap Flow/step kinds	Accepted	Org policy may forbid automatable steps; student personal Flows not visible to teacher/class agents by default
10	Run/version skew is safe	Accepted	Run pins flow_version; in-flight runs finish on the pinned version; migration offered, never forced
11	Seven-tier test matrix before any live capability	Accepted	See §9; scope-denial, injection, redaction, no-secrets are mandatory security-tier cases

---

7. Defaults (confirmed for v0)

Default	Value	Notes
flow.scope for new flows	personal	Private by default
External / automatable effects	off	automatable inert until gate 7A-L3
Active verification kinds	human_review, artifact_exists	Others parse-valid, runtime-gated
Step model	ordered list	DAG deferred to a later version
Taxonomy	tags first	Formal categories only if needed (see open items)
Storage	Hub index primary + optional vault mirror	Option A

---

8. Starter Flow definitions — deferred to 7A-3 (not authored here)

Authoring the concrete starter set (user-owned knowtation.flow/v0 records composing existing primitives, including the two project-scoped process Flows from CROSS-REPO-COORDINATION.md: "Multi-repo substrate + top-layer change" and "Overseer handover") is step 7A-3. This spec only fixes the schema they must satisfy. Listed here so the scope boundary is explicit.

---

9. Test plan — seven tiers

Per RULE #0, every later implementation slice ships all seven tiers. v0 spec-step authors the plan; adapter/store slices (7A-5..7A-10) implement it. No network in unit tests.

Tier	What it proves	Representative v0 cases
unit	Schema parse/validate per object	Required-field + enum validation for all five schemas; anatomy-completeness rejection (missing trigger/verification); id-format regex; semver parse
integration	CLI / MCP / Hub return the same contract	flow_list/flow_get parity across all three surfaces; scope filter applied identically; proposal path on each
e2e	Author → retrieve → project round-trip	Propose a flow → approve → get → project --harness cursor_rule → projection matches canonical
stress	Many flows/steps/runs	10k flows, 100-step flows, deep step_states; list/get stay correct under load
data-integrity	Export/import round-trip with no field loss	Bundle export → import into a second vault preserves steps, skill refs, verification, scope, version, lineage byte-for-byte
performance	List/get latency budgets	flow list (scope-filtered) and flow get within target p95; projection generation bounded
security	Scope denial, injection, redaction, no-secrets	Personal flow never returned to a project/org context; malicious instruction/draft_step cannot escalate; evidence/provenance carry no raw content; no secret ever serialized in any object or projection

---

10. Open items / decisions

#	Item	Recommendation
1	flow_run ↔ Phase 2G task record	Decided (7A-4 / SD-2, 2026-06-20): linked records, both canonical in Knowtation, one portable store. Link by id (task.run_ref ↔ run.task_ref, reusing the external_ref lineage bridge); never a Scooling-only store. Implementation rides 7A-5/7A-10. See scooling/docs/CROSS-REPO-COORDINATION.md → Standing Decisions
2	First projection target for the pilot	CLI runbook or Cursor rule; recommend own repo guidance (dogfood) as the convincing anti-drift case
3	Semver classification rules for procedures	Remove step / tighten verification = MAJOR; add optional step = MINOR; reword = PATCH (drives MuseHub typed-commit mapping at 7A-L5)
4	Category taxonomy	Tags first; formal categories only if needed
5	DAG vs ordered list	Ordered list for v0; revisit when branching/parallel is worth the complexity
6	Flow-candidate thresholds	Start N=3, confidence medium, cap 2/session (see §5.2); tune to keep the bar high
7	External-agent bundle token/allowlist shape	Defer to external-agent gate 7A-L2

---

Acceptance criteria for this spec (7A-2)

• The five wire schemas are ratified against scooling/docs/FLOW-PLATFORM-ARCHITECTURE.md with enums, id formats, and the step-state shape pinned (§1).
• Storage (Option A), API parity contract, projection-generator contract, capture-flywheel contract + thresholds, and defaults are complete (§2–§7).
• The security/privacy checklist is fully signed off (§6) and the seven-tier test plan is written (§9).
• No live capability is implied by acceptance; each live slice (7A-L1..L5) remains a separate gate.

Non-goals (v0)

• Live automatable step execution; hosted projection; external-agent Flow bundles.
• DAG / branching / parallel steps.
• MuseHub enrichment (step-level history, releases, provenance-anchored evidence, social discovery).
• Scooling becoming a second canonical procedure store.

---

Handoff notes (for the next step, 7A-3)

1. Branch is feat/flow-v0-spec (created from main @ 94ec65bd); this spec is Muse-committed here.
2. 7A-3 authors the starter Flow set as concrete knowtation.flow/v0 records against §1 (Thinking → Auto), including the two process Flows from CROSS-REPO-COORDINATION.md.
3. Add OpenAPI shapes to docs/openapi.yaml in the same change as the routes (7A-10) — no docs-only PR to Knowtation main.
4. Always target the repo explicitly with muse -C ~/knowtation ….