aaronrene / knowtation public
docs flow feat/flow-projection-pilot #16 / 18
aaronrene · 2 days ago · Jun 20, 2026 · Diff

docs(flow): freeze projection generator + fidelity report contract (7A-11a)

Contract-only step before mechanical implementation. Adds docs/FLOW-PROJECTION-GENERATOR-CONTRACT-7A-11.md per FLOW-V0-SPEC.md §4 and scooling/docs/FLOW-PLATFORM-ARCHITECTURE.md projection sections:

- lib/flow/projection-generator.mjs function table (pure, deterministic, reads canonical via getFlow; no I/O, no network) - knowtation.flow_projection/v0 object (spec §1.7, unchanged) + knowtation.flow_project/v0 response envelope (staleness + generator hash) - staleness (semver lag) + drift (content-hash; editable:false never a write source) + fidelity.dropped_fields report - v0 active harnesses cursor_rule + cli_runbook (dogfood .cursor/rules / AGENTS.md / .cursorrules); cursor_skill/mcp_prompt reserved; agent_bundle inert (7A-L2) - flow project CLI/MCP/Hub read-derive wire shapes + OpenAPI (to land with routes in 11b) - anti-drift demo acceptance criteria + seven-tier test matrix

No generator impl, no routes, no OpenAPI edit, no Scooling changes, no posture flips. Reuses 7A-10b scope/parity machinery unchanged.

sha256:2b6f6f510b7146080eb519309ccf22258e86655371379879e4be094cb58250f4 sha
sha256:f0525edc70a9a0d7ecc0e91868aa2d4254330be61b028ac0eeeb98c754cb8c55 parent
+52 symbols
sha256:5cbf8204940ba5c66165e8f17c33a90a522f3e272113892f35c45c324a8f7001 snapshot
+52
symbols added
0
dead code introduced
Semantic Changes 52 symbols
~ docs/FLOW-PROJECTION-GENERATOR-CONTRACT-7A-11.md .md 52 symbols added
+ Flow Projection Generator + Fidelity Report — Contract (Phase 7A, Step 7A-11a) section Flow Projection Generator + Fidelity Report — Contract (Phase 7A, Step 7A-11a) L1–616
+ mjs (contract, no impl) section 1. Generator module shape — lib/flow/projection-generator.mjs (contract, no impl) L83–138
+ 1 Constants variable section 1.1 Constants L91–105
+ table section table L93–101
+ 2 Core generator functions function section 1.2 Core generator functions L105–123
+ table section table L107–116
+ 3 What the generator does not do (v0) section 1.3 What the generator does not do (v0) L123–138
+ Anti-drift demo — acceptance criteria for the pilot (7A-11 / 7A-12) section 10. Anti-drift demo — acceptance criteria for the pilot (7A-11 / 7A-12) L549–572
+ Acceptance (7A-11a) section 11. Acceptance (7A-11a) L572–588
+ Harness targets (v0 dogfood: our own repo guidance) section 2. Harness targets (v0 dogfood: our own repo guidance) L138–174
+ 1 Rendered-artifact invariants (both active harnesses) section 2.1 Rendered-artifact invariants (both active harnesses) L151–174
+ table section table L143–150
+ flow_projection/v0 section 3. Rendered projection object — knowtation.flow_projection/v0 L174–226
+ 7 — unchanged, no new fields on the canonical shape) section 3.1 Canonical projection object (spec §1.7 — unchanged, no new fields on the canonical shape) L176–193
+ code[jsonc] variable variable code[jsonc] L180–192
+ flow_project/v0 (mirrors how flow_get/v0 wraps flow) section 3.2 Response envelope — knowtation.flow_project/v0 (mirrors how flow_get/v0 wraps flow) L193–226
+ code[jsonc] variable variable code[jsonc] L198–215
+ Staleness and drift section 4. Staleness and drift L226–255
+ 1 Staleness — a pure version lag section 4.1 Staleness — a pure version lag L228–239
+ 2 Drift — a hand-edited artifact is never a source section 4.2 Drift — a hand-edited artifact is never a source L239–255
+ dropped_fields section 5. Fidelity report — fidelity.dropped_fields L255–291
+ 1 Contract section 5.1 Contract L261–275
+ 2 v0 per-harness fidelity baseline (representative, frozen for 11b) section 5.2 v0 per-harness fidelity baseline (representative, frozen for 11b) L275–291
+ table section table L277–285
+ flow project wire shapes (read/derive) — CLI = MCP = Hub REST section 6. flow project wire shapes (read/derive) — CLI = MCP = Hub REST L291–369
+ 1 CLI section 6.1 CLI L303–323
+ code variable variable code L305–308
+ 2 MCP tool section 6.2 MCP tool L323–332
+ table section table L325–328
+ 3 Hub REST section 6.3 Hub REST L332–341
+ table section table L334–337
+ mjs) section 6.4 Shared handler (parity, mirrors flow-handlers.mjs) L341–355
+ 5 Error codes section 6.5 Error codes L355–369
+ table section table L357–364
+ yaml with the routes, 7A-11b) section 7. OpenAPI wire shapes (to land in docs/openapi.yaml with the routes, 7A-11b) L369–450
+ 1 GET /api/v1/flows/{id}/projection section 7.1 GET /api/v1/flows/{id}/projection L373–396
+ code[yaml] variable variable code[yaml] L375–395
+ 2 Component schemas section 7.2 Component schemas L396–450
+ code[yaml] variable variable code[yaml] L398–445
+ Fail-closed rules (generator + all three surfaces) section 8. Fail-closed rules (generator + all three surfaces) L450–476
+ Seven-tier test matrix (what each tier proves — representative cases, not code) section 9. Seven-tier test matrix (what each tier proves — representative cases, not code) L476–549
+ mjs section 1. unit — test/flow-projection-generator-unit.test.mjs L484–497
+ mjs section 2. integration — test/flow-project-parity-integration.test.mjs L497–505
+ mjs section 3. e2e — test/flow-projection-generator-e2e.test.mjs L505–513
+ mjs section 4. stress — test/flow-projection-generator-stress.test.mjs L513–519
+ mjs section 5. data-integrity — test/flow-projection-generator-data-integrity.test.mjs L519–529
+ mjs section 6. performance — test/flow-projection-generator-performance.test.mjs L529–534
+ mjs section 7. security — test/flow-projection-generator-security.test.mjs L534–549
+ Handoff notes (for the next step, 7A-11b — Auto) section Handoff notes (for the next step, 7A-11b — Auto) L601–616
+ Non-goals (7A-11) section Non-goals (7A-11) L588–601
+ Simple summary section Simple summary L43–61
+ Technical summary section Technical summary L61–83
Older feat(flow): implement store + list/get read surface (7A-10b) sha256:f0525edc70a9a0d7ecc0e91868aa2d4254330be61b028ac0eeeb98c754cb8c55 All commits Newer feat(flow): projection generator + flow project surfaces (7A-11b) sha256:ea6d4206210c21ace24693d265830bb0cb3f47efbed8fc46e1b443a082595eb3

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:2b6f6f510b7146080eb519309ccf22258e86655371379879e4be094cb58250f4 --body "your comment"