[RFC] Construct Piping — Knowledge Flow from Signals to Composition

[zkSoju]

Context

During the Protocol v2.0 PR review, we performed the first real multi-construct composition in the ecosystem: Observer (riding 4 dApp codebases) → Protocol (wallet boundary verification) → Artisan (material taste context) → Bridgebuilder (adversarial review). This composition worked — it produced findings none of these constructs could have surfaced alone (shared utility lineage across repos, approve-then-act race conditions, ZeroDev migration scars in 4/4 dApps).

But the composition happened entirely inside the context window. No construct stdout. No event fired. No knowledge artifact persisted for next time. The pipes exist (event bus #109, BUTTERFREEZONE mesh, event topology in manifests) but they don't flow.

This RFC proposes the knowledge layer — the missing piece between signals (lightweight events) and composition (rich structured data flowing construct-to-construct).

The Three User Stories

1. As a user, I want to string together constructs like UNIX pipes

Current: Invoke /ride (Observer) manually, copy findings, invoke Protocol skills manually, copy findings, invoke Artisan manually.

Desired: Something like:

/ride set-and-forgetti | /protocol dapp-lint --manifest ecosystem.yaml | /artisan taste-check

Where each construct's structured output becomes the next construct's structured input.

2. As a construct, I want to benefit from coordination and capture tacit knowledge

Current: Protocol's dapp-lint scans one codebase at a time. It doesn't know that useOnSuccess is a shared utility that exists in 3 other repos. It can't learn from Observer's ground truth about which repos are related.

Desired: Protocol declares knowledge.consumes: [observer.ground_truth, observer.utc_canvas] and receives rich context about the ecosystem before scanning. When Protocol discovers patterns (e.g., "approve-then-act race condition in mibera"), it emits knowledge.emits: [protocol.ecosystem_pattern] that other constructs can consume next time.

3. As a network, I want to offer best-in-class runtime support

Current: Runtime contract (docs/integration/runtime-contract.md) defines exit codes, checkpoints, and context signals. No mention of events, knowledge routing, or correlation propagation. The event bus and runtime contract are completely disconnected.

Desired: Runtime contract includes a "Knowledge Routing" section. When a skill completes, the runtime automatically emits the skill's declared events with the checkpoint data. Correlation IDs propagate through skill chains.

What Already Exists (and What's Missing)

Infrastructure	Status	Gap
Event bus (event-bus.sh)	Written, CloudEvents 1.0, flock-atomic, DLQ	No runtime auto-emission. Skills must call emit_event manually.
Event schemas in manifests	Declared in all 5 pack construct.yaml files	9 of 11 event types have zero consumers. data_schema is freeform inline, not $ref to JSON Schema.
Event registry (event-registry.sh)	Written, topology validation	Scans manifest.json but installed packs only have construct.yaml — finds nothing.
BUTTERFREEZONE mesh	Written, cross-repo graph traversal	Edges carry {role, interface, protocol} — no event topology. Can't answer "which events connect these repos."
Runtime contract	Written, exit codes + checkpoints + context signals	Zero mention of events, knowledge routing, or correlation propagation.
Migration guide (#109)	Proven for Observer + Artisan in midi-interface	Not applied to Crucible, Beacon, GTM, or Protocol.
Compound learning	Specified (3 levels: session → cycle → upstream)	Cross-session patterns registry (patterns.json) is .gitkeep only.
MoE routing (#119)	Designed in STRATEGIC-GAP Cycle C	domain/expertise fields not in manifest schema yet.

Proposal: Three Phases

Phase 0: Make the Pipes Flow (connect existing infrastructure)

The cheapest wins. No new schemas. No new abstractions. Just wire what we have.

1. Fix event-registry.sh to scan construct.yaml (not just manifest.json)

   • 1-line change: add glob for construct.yaml alongside manifest.json
   • Unblocks: validate_event_topology actually works against installed constructs

2. Add runtime event emission hook to the runtime contract

   • After skill checkpoint write, if the skill's pack declares events.emits, auto-call emit_event with checkpoint summary as data payload
   • Correlate via execution_id from the checkpoint schema
   • Add to docs/integration/runtime-contract.md section 7: "Event Emission"

3. Register Protocol as event consumer/emitter

   • Protocol emits: protocol.verification_complete, protocol.tx_decoded, protocol.qa_report (already in construct.yaml)
   • Protocol should consume: observer.canvas_created (for UTC context during dapp-lint), artisan.taste_inscribed (for material constraints during dapp-e2e)
   • Establishes the first 3-way event topology: Observer → Protocol → Artisan

4. Add event edges to BUTTERFREEZONE mesh

   • When butterfreezone-mesh.sh traverses the graph, read events.emits/events.consumes from each repo's construct.yaml
   • Add events field to mesh edges: { from, to, role, interface, protocol, events: [...] }

Phase 1: Knowledge Stanza (rich data alongside signals)

Signals are lightweight ("something happened"). Knowledge is structured ("here's what I found, here's the schema, here's how to use it").

Add knowledge to construct.yaml schema v4:

knowledge:
  provides:
    - type: ground_truth
      schema: schemas/ground-truth.schema.json
      description: "Codebase reality extracted by /ride"
      format: markdown
      retention: permanent
    - type: ecosystem_pattern
      schema: schemas/ecosystem-pattern.schema.json  
      description: "Cross-repo pattern detected during verification"
      format: json
      retention: cycle
  consumes:
    - type: ground_truth
      from: observer
      required: false
      description: "Ecosystem context for cross-repo verification"
    - type: taste_tokens
      from: artisan
      required: false
      description: "Material constraints for UX verification"

Key design decisions:

• knowledge is separate from events: Events are fire-and-forget signals. Knowledge is queryable structured data with retention policies.
• Schema references are required (not freeform inline): Prevents the drift we see in current data_schema fields.
• retention controls lifecycle: session (ephemeral), cycle (sprint-scoped), permanent (ground truth).
• required: false default: Knowledge consumption is advisory, not blocking. A construct runs without it but runs better with it.

Phase 2: Construct Stdout (UNIX piping)

The user's first story: "string together constructs like UNIX."

Skill output convention: Every skill can optionally write a structured output to a well-known path:

.loa-output/{skill-slug}/output.json

This is the skill's "stdout." It conforms to the skill's declared knowledge.provides schema. The runtime reads this after skill completion and:

1. Emits it as the event's data payload (connecting to the event bus)
2. Makes it available to the next skill in a pipeline via $LOA_PIPE_INPUT
3. Stores it in the knowledge store per the retention policy

Pipeline syntax (golden path integration):

# Single skill
/ride set-and-forgetti

# Piped skills (sequential, output → input)
/ride set-and-forgetti | /protocol dapp-lint

# Fan-out (parallel, shared input)
/ride set-and-forgetti |& /protocol dapp-lint /artisan taste-check

This maps directly to the golden path state machine (golden-path.sh) — each | creates a dependency edge. The runtime reads construct.yaml to validate that the output schema of skill A matches the input schema of skill B.

Motivating Case: Protocol Ecosystem Verification

What this looks like for the wallet boundary review that prompted this RFC:

# Phase 0 (today, with wiring fixes):
/ride set-and-forgetti      # Observer emits ground_truth event
/ride cubquests-interface    # Observer emits ground_truth event
/ride apdao-auction-house    # Observer emits ground_truth event
/ride mibera-interface       # Observer emits ground_truth event
/protocol dapp-lint          # Protocol consumes ground_truth events, runs scans

# Phase 1 (with knowledge stanza):
# Protocol's dapp-lint automatically receives Observer ground truth
# Protocol knows useOnSuccess is a shared utility because Observer's ground truth says so
# Protocol emits ecosystem_pattern knowledge ("approve-then-act race in mibera")

# Phase 2 (with piping):
/ride --ecosystem manifest.yaml | /protocol dapp-lint --manifest | /artisan taste-check
# One command. Full pipeline. Each construct enriches the next.

Relationship to Existing Issues

Issue	Relationship
#109 (Event Bus Migration)	Phase 0 depends on the proven migration pattern from midi-interface
#104 (Unified Feedback Schema)	Knowledge stanza generalizes the feedback schema to all domain data
#119 (MoE Routing)	Phase 2 piping depends on domain/expertise fields for type-safe routing
#128 (Verification Gradient)	L3 composability tier = Phase 2 piping capability
#129 (Workflow Gates)	Pipeline validation uses declared workflow gates for type checking
#131 (Construct Lifecycle)	Bidirectional sync carries knowledge artifacts alongside code
#118 (Reference Ingestion)	knowledge.consumes is the declarative version of methodology ingestion
construct-protocol#2 (Ecosystem Manifest)	The manifest.yaml that Protocol scans is a knowledge artifact from Observer

Open Questions

1. Knowledge storage location: grimoires/loa/a2a/knowledge/{type}/ alongside events? Or per-construct at grimoires/{pack}/knowledge/?
2. Cross-repo knowledge: BUTTERFREEZONE mesh discovers capabilities. Should it also cache/proxy knowledge artifacts from remote repos? Or only advertise them?
3. Retention GC: Who compacts cycle-scoped knowledge after the cycle ends? The compact_events pattern from the event bus could be extended.
4. Schema evolution: Knowledge schemas need versioning. Use the same compatibility: backward | forward | full | none pattern from pack-manifest.schema.json?

Non-Goals

• No new daemon or service: Knowledge routing happens at skill invocation time, not as a background process.
• No breaking changes to existing manifests: knowledge is additive to construct.yaml. Existing packs without it continue to work.
• No changes to loa-dixie: Dixie is a product layer that will eventually consume knowledge from the construct network. This RFC is about the infrastructure Dixie will consume from.

---

Originated from Protocol v2.0 PR #1 review — the first real multi-construct composition in the ecosystem.

[zkSoju]

Companion Issue: Runtime Execution Layer

The execution-side counterpart to this RFC has been filed on the loa repo:

loa#446 — Runtime Knowledge Routing: Auto-Emission, Composition, and Construct-Level Compound Learning

Per the separation of concerns:

• This issue (loa-constructs#145): Declares what — knowledge: stanza in construct.yaml, event schema refs, construct stdout convention, BUTTERFREEZONE mesh edges
• loa#446: Executes how — event auto-emission after skill completion, composition orchestration (piping), knowledge routing resolution, construct-aware /compound

Phase 0 Split

Task	Repo
Fix event-registry.sh to scan construct.yaml	loa (framework script)
Register Protocol as event consumer/emitter	loa-constructs (manifest schema)
Add event edges to BUTTERFREEZONE mesh	loa (framework script)
Add runtime event emission hook to runtime contract	loa (runtime contract doc)

[zkSoju]

Self-Critique: Questioning the Question

After filing this RFC, I did a forensic audit of the actual infrastructure. The evidence challenges several assumptions in this proposal.

Evidence That Contradicts the RFC

1. Zero events have ever been emitted.

event-bus.sh is 939 lines of production-quality code. CloudEvents 1.0, flock-atomic, DLQ, idempotency. But emit_event has never been called in production. The grimoires/loa/a2a/events/ directory doesn't exist on disk. No .events.jsonl files exist anywhere. The event declarations in construct.yaml are topology metadata for validation, not live wiring.

2. The grimoire filesystem IS the bus.

All working cross-construct data flow happens through filesystem conventions:

• Observer writes to grimoires/crucible/gaps/{journey-id}-gaps.md → Crucible reads from that path
• Observer writes to grimoires/artisan/observations/user-insights.md → Artisan reads from that path
• Observer reads grimoires/artisan/taste.md for context
• Beacon reads grimoires/loa/reality/ for codebase grounding

No events. No routing. Just files at known paths.

3. The event bus IS a grimoire convention. It stores to grimoires/loa/a2a/events/. It's a thin JSONL+flock wrapper around the same filesystem. The "bus" and the "grimoire" are the same thing.

4. /compound has never been run. grimoires/loa/a2a/compound/ contains only .gitkeep files. grimoires/loa/skills-pending/ doesn't exist. The compound learning pipeline is entirely aspirational.

5. No structured JSON output convention exists. Skills write named markdown files at well-known paths + state.yaml sidecars. There is no output.json, no .loa-output/, no generic stdout slot.

6. Cross-construct paths are undeclared. Observer knows to write to grimoires/crucible/gaps/ because the SKILL.md says so in prose. Nothing in construct.yaml declares path ownership — pack_dependencies declares install ordering, not data flow.

What This Means for the RFC

The three-phase proposal may be building the wrong thing:

• Phase 0 (wire existing infra): The event bus has nothing to wire to. Skills don't call it. The filesystem coupling that exists has zero awareness of events.
• Phase 1 (knowledge: stanza): Proposes rich knowledge routing when the actual mechanism is "write markdown to grimoires/{pack}/, other packs read it by convention."
• Phase 2 (construct stdout/piping): Proposes $LOA_PIPE_INPUT and .loa-output/ when skills already write to named paths declared in their SKILL.md.

Counter-Proposal: Formalize What Works

Instead of building on unused event infrastructure, formalize the grimoire filesystem conventions that already work:

# construct.yaml v4 — path declarations
paths:
  writes:
    - grimoires/observer/canvas/
    - grimoires/observer/journeys/
    - grimoires/crucible/gaps/        # cross-construct write (declared!)
    - grimoires/artisan/observations/ # cross-construct write (declared!)
  reads:
    - grimoires/artisan/taste.md
    - grimoires/crucible/diagrams/
    - grimoires/loa/reality/

This does three things the current system doesn't:

1. Makes cross-construct writes visible — Observer writing to grimoires/crucible/gaps/ is currently invisible to the manifest. Declaring it makes it auditable.
2. Enables topology validation — validate_event_topology could validate path topology too. "Observer writes to grimoires/crucible/gaps/ but Crucible doesn't declare a read of that path" is a topology error.
3. No new infrastructure — no event bus, no routing layer, no knowledge stanza. Just declare what you already do.

The event bus remains available for the future async use case ("Crucible should automatically start when Observer finishes a journey without a human in the loop"). But that use case hasn't materialized. Building for it now is speculative.

The Real Phase 0

1. Add paths.writes and paths.reads to construct.yaml schema
2. Populate them from the existing SKILL.md prose conventions (all 5 packs)
3. Add path topology validation alongside event topology validation
4. Run the skills end-to-end at least once — grimoires/observer/ doesn't exist on disk because Observer has never been run in this repo

The "piping" vision is valid for the future. But the immediate need is simpler: declare the filesystem conventions that already work, then actually use the constructs.

[zkSoju]

Correction: The Constructs ARE Alive — In the Product Repos

My self-critique was based on examining loa-constructs (the registry) in isolation. That was the wrong place to look. The constructs produce artifacts in the repos where they're installed. Here's the actual ecosystem:

midi-interface — Observer's Production Deployment

• 29 active user canvases, 125 feedback entries, daily synthesis cron running
• 21 real CloudEvents in observer.feedback_captured.events.jsonl — the event bus IS being used
• Offset-tracked consumption by daily-synthesis consumer group
• Artisan taste.md grounded with code-verified tokens
• Herald producing multi-channel announcements (v0.4, v0.5)
• The Easel with full KAIROS creative director persona
• Mining chronicle with 20 temporal context entries
• grimoires/shared/feedback/ — real cross-construct schema coordination layer

mcv-interface — The Most Mature Ecosystem (92 sprints)

• The Mint: 289-file AI asset production pipeline (FAL FLUX → Recraft V4 Pro → Kling → Depth Anything V2 + SAM 3 layer separation)
• The Easel: 15 TDRs, full design vocabulary, spatial/material archetype
• Artisan: 400+ line taste.md bridging CSS tokens to generative model prompt vocabulary
• Bridgebuilder: Dual bespoke personas (BEAUVOIR craftsman + PIRANESI vault architect)
• 11 compound learnings captured manually in NOTES.md
• Contributed Loa framework improvements upstream (cycles 038-042)

rektdrop-interface — The Easel-Dominant

• 17 TDRs, Bridgebuilder v2 persona, vocabulary atlas, iconography pipeline
• OKLCH chromatic engine, strict mechanical motion (only steps() and linear)

What This Means for the RFC

1. The event bus IS being used — midi-interface has 21 real events with offset tracking. My "zero events" finding was wrong because I only looked at the registry, not the products.
2. Cross-construct coordination IS happening — grimoires/shared/feedback/ in midi-interface has real schemas. Observer writes to Artisan's namespace. Herald consumes Observer's user data.
3. Compound learning IS happening — manually, via NOTES.md. mcv-interface has 11 learnings. The system designed to automate this isn't installed, but the practice exists.
4. Unregistered constructs are major players — The Mint (289 files), The Easel (15+ TDRs), Herald (announcements) are producing real artifacts but aren't in the registry.

The RFC's Phase 0 (wire existing infra) is MORE relevant than I thought, not less. The event bus works in midi-interface. The question is extending that pattern to mcv-interface and rektdrop-interface, and formalizing what The Mint/Easel/Herald do.

[zkSoju]

KISS Reflection

After exploring the full ecosystem (midi-interface, mcv-interface, rektdrop-interface), the honest conclusion:

The grimoire filesystem is already a beautifully simple coordination architecture. A construct writes a markdown file. Another construct reads it. The path is the API.

Everything that works across all three product repos is a file at a known path:

• `taste.md` — one file = complete design vocabulary (CSS tokens, generative model prompts, Never Rules)
• `{username}-canvas.md` — one file per human = complete user knowledge
• `TDR-{NNN}.md` — one file per design decision
• `{type}.events.jsonl` — one file per event type (flock + offset = the entire bus)
• `NOTES.md` — compound learning that people actually write to (11 real learnings in mcv)

Everything that doesn't work adds indirection on top of files: invisible retrospective (config missing), memory hooks (not installed), /compound (requires cycles nobody runs), knowledge stanza (schema on top of filesystem reads).

This RFC proposes adding more indirection. The system is saying: the simple version works and the complex version doesn't get installed.

The RFC remains valid as a north star for when 10+ constructs need automated coordination across 20+ repos. Today, with 3 product repos and 5-7 active constructs, files at known paths are sufficient and beautiful.

The one thing that IS missing: discoverability. When a new construct is installed in a new repo, it doesn't know what grimoire paths already exist. That could be as simple as a `grimoires/README.md` per repo that lists active construct directories and what they contain. No schema. No stanza. Just a file.