Flow Store + List/Get Parity — Contract (Phase 7A, Step 7A-10a)

Status: Implemented — step 7A-10b (Auto). Store module, Hub routes, CLI/MCP wiring, OpenAPI block, and seven-tier tests ship on branch feat/flow-projection-pilot. This document remains the frozen contract reference; do not redesign it in follow-on steps.

Authored on branch feat/flow-projection-pilot (branched from feat/flow-v0-spec).

Related:

• docs/FLOW-V0-SPEC.md — the canonical spec this contract implements (§1 schemas, §2 Storage Option A, §3 API surfaces, §6 security checklist, §9 seven-tier plan).
• lib/calendar/event-store.mjs — the Option A parity reference (local file-backed, per-vault, atomic write, *ForClient projection, deny-by-default query filter). The Flow store mirrors its shape function-for-function where the concern is the same.
• flows/starter/ — the six canonical seed Flows / 24 steps authored in 7A-3 (flow_*.json bundles) that the store seeds on first read.
• docs/openapi.yaml — where the Hub wire shapes in §6 land in the same change as the routes (7A-10b), per the no-docs-only-PR rule.
• scooling/docs/FLOW-ADAPTERS-CONTRACT-7A-5.md — the consumer read shape Scooling expects (FlowSummary, FlowDefinitionView, content-minimization, scope-denial codes). This contract is ratified against it so the Hub JSON the FlowAdapter will read at 7A-10b matches field-for-field.

Scope fence (7A-10a): Store API + list/get read contract + OpenAPI wire shapes + seven-tier test matrix only. No lib/flow/ implementation, no Hub routes, no CLI wiring, no MCP tool wiring, no Scooling changes, no posture-constant flips. v0 read surface is list/get only — propose / project / run are named here for parity completeness but are not in 7A-10's read scope (propose/project = 7A-10b+ / 7A-11; run = gated 7A-L3).

---

Simple summary

A Flow is a saved procedure (an ordered checklist with proof-of-done). Knowtation is the one place Flows live. This document is the blueprint for the filing cabinet that holds them (the store) and the two read doors every surface uses to look inside: list (give me the titles of the Flows I'm allowed to see) and get (give me one whole Flow with its steps). The blueprint guarantees three things. First, the command line, the MCP plug-in, and the Hub website all return the exact same answer — change a Flow once and every door shows the change, with no copying. Second, you only ever see Flows you're allowed to see; the server decides that, never the client, and the default is "see nothing extra." Third, the list view is trimmed (titles and counts, never the full step text), and no secret, token, or private content is ever in any answer. The store is modeled on the calendar store that already works this way, so it inherits a proven, safe shape.

Technical summary

A local file-backed, per-vault Flow index store (lib/flow/flow-store.mjs) that mirrors lib/calendar/event-store.mjs Option A: structured records in a JSON index (primary, query/scope source of truth) plus an optional vault Markdown mirror (type: flow, derived from the index, never the reverse). v0 exposes read-only listFlows (content-minimized summaries, scope/tag filtered) and getFlow (full definition + ordered steps) over three identical surfaces — CLI (knowtation flow list / flow get), MCP (flow_list / flow_get), and Hub REST (GET /api/v1/flows, GET /api/v1/flows/{id}) — returning byte-identical JSON for the same authorized request. Scope is authorization, enforced server-side, deny-by-default (WorkspaceScopeAdapter + retrieval policy); the client never supplies its own visible tier. Step text is untrusted input; list views are truncated; evidence/provenance and requires / skill_refs are pointers/handles only — no secrets, tokens, or raw content in any response. The store seeds the six 7A-3 starter bundles from flows/starter/ on first read (idempotent). All seven test tiers are specified for the store and for list/get parity.

---

1. Store module shape — lib/flow/flow-store.mjs (Option A, calendar parity)

The Flow store is a pure, local, file-backed module with no network and no Express coupling — exactly like event-store.mjs. Routes/CLI/MCP call it; it never calls them. The function table below pins names, parameters, and return shapes for 7A-10b.

1.1 Constants and on-disk layout

Constant	Value	Parity note
FLOW_STORE_FILENAME	'hub_flow_store.json'	mirrors STORE_FILENAME = 'hub_calendar_store.json'
STARTER_FLOWS_DIRNAME	'flows/starter' (repo-relative; resolvable override for tests)	seed source (7A-3 bundles)
MAX_FLOW_SUMMARIES	200	list cap; sets truncated when exceeded
MAX_STEPS_PER_FLOW	100	get cap; rejects/marks over-long step lists

On-disk shape (one file under data_dir, keyed by vault, mirroring the calendar store):

{
  "vaults": {
    "<vault_id>": {
      "flows":        [ /* knowtation.flow/v0 records */ ],
      "steps":        [ /* knowtation.flow_step/v0 records */ ],
      "runs":         [ /* knowtation.flow_run/v0 records (read-only in v0) */ ],
      "candidates":   [ /* knowtation.flow_candidate/v0 records (inert in v0) */ ],
      "projections":  [ /* knowtation.flow_projection/v0 records (derived; 7A-11) */ ]
    }
  }
}

The index is the source of truth. The optional vault Markdown mirror (spec §2.2) is a projection of the index, reconciled as a proposal if hand-edited — never silently promoted.

1.2 Persistence primitives (mirror event-store.mjs exactly)

Function	Signature	Behaviour (parity target)
getFlowStorePath	(dataDir) → string	path.join(dataDir, FLOW_STORE_FILENAME)
loadFlowStore	(dataDir) → FlowStoreFile	read+parse; never throws — malformed/missing ⇒ { vaults: {} }
saveFlowStore	(dataDir, store) → void	mkdir -p, write to *.<pid>.<uuid>.tmp, renameSync (atomic), 2-space JSON
getVaultFlowStore	(dataDir, vaultId) → VaultFlowStore	lazily creates an empty {flows,steps,runs,candidates,projections}

1.3 Id + version helpers (pin §1.2 of the spec)

Export	Value / signature	Source
FLOW_ID_RE	/^flow_[a-z0-9_]{1,64}$/	spec §1.2
FLOW_STEP_ID_RE	/^flow_[a-z0-9_]{1,64}#[1-9][0-9]*$/	<flow_id>#<ordinal>
FLOW_RUN_ID_RE	/^run_[a-z0-9_]{1,48}$/	spec §1.2
SEMVER_RE	strict MAJOR.MINOR.PATCH	flow.version
buildFlowStepId	(flowId, ordinal) → string	`${flowId}#${ordinal}` (parity with buildEventId)

1.4 Seeding from flows/starter/ (idempotent)

Function	Signature	Behaviour
seedStarterFlows	(dataDir, vaultId, { starterDir? }) → { seeded: number, skipped: number }	Load each flows/starter/flow_*.json bundle ({ flow, steps }), validate against §1 schema, and upsert by (flow_id, version). Idempotent: re-running seeds nothing new (skipped counts already-present). A bundle that fails schema validation is rejected and logged, never partially written.

Seeding is read-time lazy (first listFlows/getFlow on an empty vault triggers it) and is the only write the v0 store performs — it materializes canonical, user-owned seeds, not user data, and routes no proposal (the seeds ship with the repo). All later durable writes route through proposals (review-before-write); the store exposes no public create/update/delete in v0.

1.5 Read operations (the v0 surface)

Function	Signature	Returns	Rules
listFlows	(dataDir, vaultId, { visibleScopes, scope?, tags?, limit? }) → FlowListResult	{ flows: FlowSummary[], effective_scope, truncated }	content-minimized; deny-by-default scope filter (§4); limit capped at MAX_FLOW_SUMMARIES; truncated:true when capped or when more than limit match
getFlow	(dataDir, vaultId, flowId, { visibleScopes, version? }) → FlowDefinitionResult \| null	{ flow: Flow, steps: FlowStep[] } or null when not found/not visible	flowId must match FLOW_ID_RE; resolve latest version within visible scope unless version pins one; steps returned in ascending ordinal order; capped at MAX_STEPS_PER_FLOW

visibleScopes is a server-resolved Set<Scope> passed in by the route/CLI/MCP after scope resolution (§4). The store never trusts a client-supplied tier; an absent visibleScopes resolves to { 'personal' } (lowest). getFlow returns null (mapped to 404 unknown_flow) for both genuinely-missing and scope-invisible flows so existence is never leaked across scope.

1.6 Client projections (*ForClient — calendar parity)

Function	Signature	Drops / keeps
flowSummaryForClient	(flow) → FlowSummary	keeps flow_id, title, version, scope, summary, tags, step_count, updated, truncated; drops the full steps[], inputs, vault_mirror_path (content-minimization)
flowDefinitionForClient	(flow, steps) → { flow, steps }	full definition + ordered steps; strips any field not in §1.3/§1.4 of the spec; never emits oauth_ref-style or secret-bearing keys (none exist in the schema, asserted in tests)

---

2. Read operations contract (list + get)

2.1 flow list — content-minimized, scope/tag filtered

• Input: optional scope (narrow within authorized scopes only — never widen), optional tag (single tag membership), optional limit (1..MAX_FLOW_SUMMARIES, default MAX_FLOW_SUMMARIES).
• Output: an array of FlowSummary (one line per visible flow, latest version per flow_id within scope), the resolved effective_scope, and truncated.
• Content-minimization: summaries carry step_count (an integer), never step bodies, instructions, boundaries, requires, or skill refs.
• Ordering: stable — by updated descending, then flow_id ascending (deterministic for tests).

2.2 flow get — full definition + ordered steps

• Input: flow_id (required, FLOW_ID_RE), optional version (SEMVER_RE; default = latest visible).
• Output: the full knowtation.flow/v0 record plus its knowtation.flow_step/v0 records in ascending ordinal order.
• Untrusted: every step's instruction, owned_job, trigger, when_not_to_run, boundaries, output_shape, and skill_refs are data, not commands — returned verbatim, never interpreted, and they cannot widen scope or escalate permission from inside.
• Not found / not visible: both ⇒ 404 unknown_flow (no existence leak across scope).

---

3. CLI commands — knowtation flow … (per FLOW-V0-SPEC §3.1)

A new flow subcommand namespace (the CLI dispatches on subcommand === 'flow', then the next arg). v0 wires only the two read commands; the rest are reserved per the spec and print a "gated/not-in-v0" notice.

knowtation flow list   [--scope personal|project|org] [--tag <t>] [--limit <n>] [--json]
knowtation flow get    <flow_id> [--version <semver>] [--json]
# reserved (not wired in v0): flow propose | flow export | flow import | flow project | flow run

• --json prints the exact Hub JSON (§6) to stdout; without it, a human-readable table (flow list) or summary (flow get).
• The CLI resolves scope the same way the Hub does (local config identity → authorized scopes); it passes visibleScopes into the store. No CLI flag can grant a scope the caller lacks.
• Errors map to non-zero exits with the same code strings as the Hub (BAD_REQUEST, NOT_FOUND, FLOW_SCOPE_DENIED).

CLI dispatch parity: today the CLI uses flat verbs (list-notes, get-note). The flow namespace is the §3.1-specified shape; 7A-10b adds the flow branch in cli/index.mjs delegating straight to lib/flow/flow-store.mjs (no duplicated logic).

---

4. Scope enforcement (server-side, deny-by-default)

Rule	Contract
Authorization, not a filter	The caller's visible scope set is resolved server-side from verified identity + WorkspaceScopeAdapter + Knowtation retrieval policy. The client's scope query param can only narrow within that set.
Deny by default	Absent/ambiguous resolution ⇒ { 'personal' } (lowest). A personal context never receives project/org flows.
No existence leak	A flow outside the visible scope is indistinguishable from a missing one (getFlow ⇒ null ⇒ 404 unknown_flow).
Error codes	unauthorized tier ⇒ 403 FLOW_SCOPE_DENIED; ambiguous scope ⇒ 400 FLOW_SCOPE_AMBIGUOUS (mirrors the consumer's flow_scope_denied / flow_scope_ambiguous).
Vault binding	X-Vault-Id + role required on the Hub (requireVaultAccess + requireRole('viewer'…)), parity with the calendar routes; the CLI binds the locally-configured vault.

The starter set spans scopes on purpose: four personal Flows + two project Flows (flow_multi_repo_change, flow_overseer_handover). The scope test fixtures use exactly this set so a personal context proves it sees four and never the two project Flows.

---

5. Starter Flow seed (from flows/starter/)

• The six 7A-3 bundles (flow_capture_to_note, flow_research_brief, flow_reviewed_writeback, flow_session_to_flow, flow_multi_repo_change, flow_overseer_handover) are the canonical seed definitions. seedStarterFlows validates each against §1 of the spec and upserts by (flow_id, version).
• Seeding is idempotent and read-time lazy; it writes only canonical seeds, never user data, and routes no proposal.
• A bundle failing schema validation (e.g. a step missing trigger/verification — the "anatomy-completeness" rule) is rejected wholesale and logged; the store is never left partially seeded.

---

6. OpenAPI wire shapes (to land in docs/openapi.yaml with the routes in 7A-10b)

Specified here, added to docs/openapi.yaml in the same change as the routes (no docs-only PR to main). New tag: Flows. Both routes are BearerAuth + X-Vault-Id + requireRole(viewer…).

6.1 GET /api/v1/flows — list (scope/tag filtered, content-minimized)

Query params: scope (enum personal|project|org, optional — narrows only), tag (string, optional), limit (integer 1..200, optional).

/api/v1/flows:
  get:
    tags: [Flows]
    summary: List scope-visible flows (content-minimized)
    parameters:
      - { name: scope, in: query, schema: { type: string, enum: [personal, project, org] } }
      - { name: tag,   in: query, schema: { type: string } }
      - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 200 } }
    responses:
      '200': { content: { application/json: { schema: { $ref: '#/components/schemas/FlowListResponse' } } } }
      '400': { content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }  # BAD_REQUEST | FLOW_SCOPE_AMBIGUOUS
      '401': { content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
      '403': { content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }  # FLOW_SCOPE_DENIED

6.2 GET /api/v1/flows/{id} — full definition + ordered steps

Path param id (FLOW_ID_RE); query param version (SEMVER_RE, optional — default latest).

/api/v1/flows/{id}:
  get:
    tags: [Flows]
    summary: Get one flow definition + ordered steps
    parameters:
      - { name: id,      in: path,  required: true, schema: { type: string } }
      - { name: version, in: query, schema: { type: string } }
    responses:
      '200': { content: { application/json: { schema: { $ref: '#/components/schemas/FlowGetResponse' } } } }
      '400': { content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
      '401': { content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
      '403': { content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }  # FLOW_SCOPE_DENIED
      '404': { content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }  # unknown_flow (missing OR scope-invisible)

6.3 Component schemas

components:
  schemas:
    FlowListResponse:
      type: object
      required: [schema, vault_id, effective_scope, flows, truncated]
      properties:
        schema:          { type: string, enum: [knowtation.flow_list/v0] }
        vault_id:        { type: string }
        effective_scope: { type: string, enum: [personal, project, org] }
        flows:
          type: array
          maxItems: 200
          items: { $ref: '#/components/schemas/FlowSummary' }
        truncated:       { type: boolean }

    FlowSummary:           # content-minimized — NO step bodies
      type: object
      required: [schema, flow_id, title, version, scope, summary, tags, step_count, updated, truncated]
      properties:
        schema:     { type: string, enum: [knowtation.flow/v0] }
        flow_id:    { type: string }
        title:      { type: string }
        version:    { type: string }
        scope:      { type: string, enum: [personal, project, org] }
        summary:    { type: string }
        tags:       { type: array, maxItems: 32, items: { type: string } }
        step_count: { type: integer, minimum: 0 }
        updated:    { type: string }
        truncated:  { type: boolean }

    FlowGetResponse:
      type: object
      required: [schema, vault_id, flow, steps]
      properties:
        schema:   { type: string, enum: [knowtation.flow_get/v0] }
        vault_id: { type: string }
        flow:     { $ref: '#/components/schemas/Flow' }
        steps:
          type: array
          maxItems: 100
          items: { $ref: '#/components/schemas/FlowStep' }

    Flow:                  # knowtation.flow/v0 — full (spec §1.3)
      type: object
      required: [schema, flow_id, title, version, scope, summary, steps, updated, truncated]
      properties:
        schema:            { type: string, enum: [knowtation.flow/v0] }
        flow_id:           { type: string }
        title:             { type: string }
        version:           { type: string }
        scope:             { type: string, enum: [personal, project, org] }
        summary:           { type: string }
        tags:              { type: array, maxItems: 32, items: { type: string } }
        steps:             { type: array, maxItems: 100, items: { type: string } }   # ordered step ids
        inputs:
          type: array
          items:
            type: object
            required: [name, type, required]
            properties:
              name:     { type: string }
              type:     { type: string }
              required: { type: boolean }
        vault_mirror_path: { type: string, nullable: true }
        updated:           { type: string }
        truncated:         { type: boolean }

    FlowStep:              # knowtation.flow_step/v0 — full (spec §1.4); all text is UNTRUSTED
      type: object
      required: [schema, step_id, flow_id, ordinal, owned_job, instruction, trigger, when_not_to_run, boundaries, output_shape, verification, automatable]
      properties:
        schema:         { type: string, enum: [knowtation.flow_step/v0] }
        step_id:        { type: string }
        flow_id:        { type: string }
        ordinal:        { type: integer, minimum: 1 }
        owned_job:      { type: string }
        instruction:    { type: string }
        trigger:        { type: string }
        when_not_to_run:{ type: string }
        requires:
          type: array
          items:
            type: object
            required: [kind, id]
            properties:
              kind: { type: string, enum: [vault_scope, tool, file, artifact] }
              id:   { type: string }              # handle/pointer only — never an inline secret
        boundaries:     { type: array, items: { type: string } }
        skill_refs:
          type: array
          items:
            type: object
            required: [kind, id]
            properties:
              kind: { type: string, enum: [mcp_prompt, skill_pack, cli, external_tool] }
              id:   { type: string }              # opaque id only
        inputs:
          type: array
          items:
            type: object
            required: [name, from]
            properties: { name: { type: string }, from: { type: string } }
        outputs:
          type: array
          items:
            type: object
            required: [name, type]
            properties: { name: { type: string }, type: { type: string } }
        output_shape:   { type: string }
        verification:
          type: object
          required: [kind, evidence_required, description]
          properties:
            kind:              { type: string, enum: [human_review, artifact_exists, value_match, test_pass, agent_check] }
            evidence_required: { type: boolean }
            description:       { type: string }
        automatable:    { type: string, enum: [manual, agent_assisted, automatable] }

The Error schema ({ error, code }) already exists in docs/openapi.yaml; Flow routes reuse it with the code strings above (BAD_REQUEST, NOT_FOUND/unknown_flow, FLOW_SCOPE_DENIED, FLOW_SCOPE_AMBIGUOUS), matching the calendar route convention.

---

7. Triple-surface parity contract (CLI = MCP = Hub REST)

The defining invariant of 7A-10: the same authorized request returns byte-identical JSON on all three surfaces.

Surface	list	get	Source of the JSON
CLI	knowtation flow list --json	knowtation flow get <id> --json	lib/flow/flow-store.mjs
MCP	flow_list tool result	flow_get tool result	same module
Hub REST	GET /api/v1/flows	GET /api/v1/flows/{id}	same module

• All three call the same listFlows / getFlow and the same *ForClient projections — no surface re-shapes the payload. Parity is proven by deep-equality in the integration tier (§8.2).
• Scope resolution differs in input (HTTP header/JWT vs local config) but converges on the same visibleScopes set fed to the store; the JSON out is identical.
• The schema discriminator (knowtation.flow_list/v0 / knowtation.flow_get/v0) is stamped by the store, so every surface emits it identically.

---

8. Fail-closed rules (apply to the store and all three surfaces)

1. Scope is authorization, deny-by-default. Client never supplies its own visible tier; absent ⇒ personal; a personal context never receives project/org flows; ambiguous ⇒ FLOW_SCOPE_AMBIGUOUS; unauthorized ⇒ FLOW_SCOPE_DENIED. (§4)
2. No existence leak. Missing and scope-invisible both return 404 unknown_flow.
3. Step text + skill refs are untrusted. instruction/boundaries/skill_refs/output_shape are returned verbatim as data; they can never widen scope or escalate permission, and the store never executes or interpolates them.
4. No secrets in any response. requires/skill_refs carry handles/opaque ids only; provenance (on runs) carries hashed actor + harness label only; no token, oauth, refresh_token, raw note body, prompt, or completion ever appears in any flow/step/list object. The security tier asserts this by scanning serialized output.
5. Content-minimized, truncated list views. flow list returns summaries (counts + metadata), never step bodies; results carry truncated and bounded arrays (MAX_FLOW_SUMMARIES, MAX_STEPS_PER_FLOW).
6. Read-only in v0. The store exposes no public create/update/delete. The only write is the idempotent canonical seed; all durable user changes route through proposals later (review-before-write). flow run advancement stays gated (7A-L3).
7. Robust load. loadFlowStore never throws on malformed/missing files (returns empty), and writes are atomic (tmp + rename) — a crashed write never corrupts the index.
8. Deterministic, bounded ordering. List = updated desc then flow_id asc; steps = ordinal asc; both capped — no unbounded payloads, no quadratic scans.

---

9. Seven-tier test matrix (what each tier proves — representative cases, not code)

Per RULE #0, 7A-10b ships all seven tiers. Files follow the repo .test.mjs convention (test/flow-store-*.test.mjs, test/flow-list-get-parity-*.test.mjs). No network in unit tests. Fixtures use the six flows/starter/ bundles plus a malicious-step fixture and an empty vault.

1. unit — test/flow-store-unit.test.mjs

• loadFlowStore returns { vaults: {} } for missing and malformed files (never throws).
• saveFlowStore writes atomically (tmp + rename) and round-trips a vault store.
• Id/version regexes accept canonical ids and reject malformed (FLOW_ID_RE, FLOW_STEP_ID_RE, FLOW_RUN_ID_RE, SEMVER_RE); buildFlowStepId composes <flow_id>#<ordinal>.
• flowSummaryForClient drops step bodies/inputs/mirror path and keeps the nine summary fields; flowDefinitionForClient emits only spec-§1 fields.
• seedStarterFlows validates a good bundle and rejects an anatomy-incomplete one (missing trigger/verification) without partial write.
• listFlows/getFlow stamp the schema discriminator; getFlow orders steps by ordinal.

2. integration — test/flow-list-get-parity-integration.test.mjs

• Parity: CLI flow list/flow get JSON, MCP flow_list/flow_get result, and the Hub route handler payload are deep-equal for the same authorized request (same visibleScopes).
• Scope filter applied identically across all three for list and get.
• getFlow step ids match the flow.steps[] order; step_count in the summary equals steps.length from get.
• Seeding is idempotent across repeated listFlows calls (no duplicate flow_id/version).

3. e2e — test/flow-store-e2e.test.mjs

• Empty vault → first flow list seeds the six starters → flow get flow_overseer_handover returns six ordered steps with human_review + artifact_exists verification kinds intact → flow list --scope personal returns exactly the four personal flows.
• A pinned --version returns that version; absent returns latest.

4. stress — test/flow-store-stress.test.mjs

• Seed/load a vault with up to MAX_FLOW_SUMMARIES flows and MAX_STEPS_PER_FLOW-step flows; list/get stay correct and set truncated when capped. Deep step_states on read-only runs do not slow get.

5. data-integrity — test/flow-store-data-integrity.test.mjs

• Round-trip a starter bundle through seed → getFlow with no field loss/mutation: steps keep ordinal order; requires/skill_refs/verification/scope/version survive byte-for-byte.
• done+evidence_required run step states never appear with verified:false (read invariant).
• The optional vault mirror, when present, is never treated as the source (index wins).

6. performance — test/flow-store-performance.test.mjs

• listFlows (scope-filtered) and getFlow complete within a p95 budget on the large fixture; no quadratic blowups in scope/tag filtering or step ordering; load is O(file size).

7. security — test/flow-store-security.test.mjs

• Scope denial: a personal visibleScopes never returns the two project flows; ambiguous scope fails closed (FLOW_SCOPE_AMBIGUOUS); unauthorized tier ⇒ FLOW_SCOPE_DENIED.
• No existence leak: getFlow for a project flow under a personal scope returns null ⇒ 404 unknown_flow, identical to a truly-missing id.
• Injection: a malicious instruction/boundaries fixture is returned verbatim as inert data and never alters scope/permission or gets interpreted.
• No secrets: JSON.stringify of every list/get result contains no token/oauth/ refresh_token/raw-content markers; requires/skill_refs are handles only.
• Client cannot widen scope: a scope=org query param under personal authorization does not return org flows (param narrows only).

---

10. Acceptance (7A-10a)

• Store module shape (lib/flow/flow-store.mjs), read-op contract (listFlows/getFlow), CLI command shape, Hub route shapes, OpenAPI wire schemas, scope-enforcement model, starter-seed behaviour, fail-closed rules, the triple-surface parity invariant, and the seven-tier test matrix are all frozen here — contract only, no implementation.
• Ratified against FLOW-V0-SPEC.md §1–§3/§6/§9 and against the consumer shape in scooling/docs/FLOW-ADAPTERS-CONTRACT-7A-5.md (FlowSummary / FlowDefinitionView / content-minimization / scope-denial codes).
• Muse-committed on feat/flow-projection-pilot; handover regenerated to point at 7A-10b (Auto: store + routes + CLI + OpenAPI + seven-tier impl to this contract).

Non-goals (7A-10)

• No propose / export / import / project read or write paths (named for parity; impl later).
• No run advancement (flow run) — gated 7A-L3.
• No live capture / candidate detection — inert (7A-L4).
• No Scooling changes and no posture-constant flips; FLOW_LIVE_READ_AUTHORIZED stays false in Scooling until the 7A-10b Hub GET /flows ships and is wired.

---

Handoff notes (for the next step, 7A-11 — Thinking)

1. Branch is feat/flow-projection-pilot; 7A-10b is Muse-committed (store + routes + CLI + MCP + OpenAPI + seven tiers). Always target Knowtation with muse -C ~/knowtation ….
2. 7A-11a (Thinking) — design the projection generator + fidelity report contract per docs/FLOW-V0-SPEC.md §4 (knowtation.flow_projection/v0, harness targets, staleness/drift).
3. Hub GET /api/v1/flows + GET /api/v1/flows/{id} are live on self-hosted Hub; Scooling FLOW_LIVE_READ_AUTHORIZED flip is a separate, later Scooling step (not part of 7A-10b).
4. Parity gate: test/flow-list-get-parity-integration.test.mjs — CLI = MCP = Hub handler deep-equality for the same authorized request.