A · Where we are

Nine of nine tools wired. The whole lifecycle is legible.

Two independent murmurations can discover each other, establish mutual recognition, run a full S3 proposal-forming cycle, co-sign an engagement agreement — each side independently materializing a byte-identical agreement file — exit cleanly, and now read the exit lifecycle back: one flyway_status shows which relationships and agreements are effectively closed, the co-signed file never rewritten. With v0.2 the whole discover → recognize → deliver loop runs at a genuine distance — over HTTPS and GitHub PRs, no shared filesystem. Cryptographic verification on both sides throughout.

Protocol 0.1.0
Code SHA 0af2e32
Tools wired 9 of 9
Walkthroughs 8 Tier 1–8
ADRs accepted 13
Tests passing 449 / 30 files
Open issues 9
Open security 0
B · Tool maturity

Nine tools. All nine speaking.

The nine tools form the canonical surface of the protocol, and all nine are now wired — discover, identity, recognition, send, read, respond, propose, and exit. Beyond the nine wire tools, flyway materialize turns an accepted final-stage agreement proposal into the co-signed agreements/<id>.yaml — a local act over records both sides already hold, not a protocol signal.

Tool surface (S+0 baseline → S+7 · complete; reach + depth through S+13)
# Tool Purpose Status Demo
01 flyway_init Initialize identity — DID + signed entity statement + Ed25519 keypair. wired Tier 1
02 flyway_status Report identity, peers, agreements, signature validity — and effective exit state: relationships / agreements closed by a verified exit (ADR-0013). wired Tier 8
03 flyway_discover Search a flyway directory for potential peers — pre-trust; you verify at recognition. Loads a local file or an https:// URL. wired Tier 6
04 flyway_recognize Verify a peer's identity and write a signed recognition entry — locally or from its did:web URL. (Plus unrecognize.) wired Tier 6
05 flyway_tension Flag a tension to a recognized peer (S3 Navigate via Tension). wired Tier 2
06 flyway_propose Send a directive, project, or engagement agreement; full S3 staging chain. wired Tier 4
07 flyway_respond Respond to a tension (acknowledge / dispute / dissolve / transfer) or a proposal (accept / object / exit). wired Tier 4
08 flyway_check Read incoming flyway signals; verify signatures and flag issues. wired Tier 2
09 flyway_exit Cleanly leave a peer relationship, project, or syndicate — signed, unilateral, always valid. wired smoke
C · Milestone timeline

From schemas-only to delivery at a distance.

Each milestone lands one capability and one walkthrough that proves it. The top track is the surface era — a defined protocol, through identity and recognition, into a verified round-trip, a co-signed agreement, clean exit, and discovery (all nine tools). The bottom track is the v0.2 reach era — the same loop lifted off the shared filesystem: agreement provenance, then discover, recognize, and deliver over HTTPS and GitHub PRs.

Milestone timeline S+0 to S+13 across two eras A two-track timeline. The top track is the surface era: nine milestones from S+0 (May 13) to S+7 (June 17, 2026) — scaffold, identity, transport, send, dialogue, a review-hardening pass, agreements, exit, and discovery — completing all nine tools. A dashed amber connector drops to the bottom track, the reach-then-depth era: from S+8 (agreement provenance) through remote directory fetch, the transport seam, recognize-at-a-distance, a v0.2 review-hardening pass, S+12 (July 2, deliver by GitHub PR), and S+13 (July 10) — exit-aware status. The flow line is amber-gold and ends at S+13, marked "here". SURFACE — nine tools · S+0 → S+7 REACH → DEPTH · v0.2 remote + exit-aware · S+8 → S+13 S+0 scaffold 05-13 02e1bfa S+1 identity 05-21 f9911fd S+2 transport 05-21 4c472e7 S+3 first send 05-25 4fded41 S+4 dialogue 05-25 2a97330 REVIEW + ADR-0009 05-25 d5ad56f S+5 agreements 06-12 10d7045 S+6 exit 06-17 11c6b0d S+7 discover 06-17 17f9bc1 nine tools done → lift off the shared filesystem S+8 provenance 06-26 896b965 S+9 remote dir 06-26 db90614 S+10 transport seam 06-26 58ddf69 S+11 recognize@dist 06-26 8dfadaf REVIEW v0.2 harden 06-26 7f70fce S+12 deliver@PR 07-02 57e4dfe S+13 exit-aware 07-10 1576181 ↑ HERE
Fig. 1 Under two months separate protocol surface defined from a cross-boundary collaboration a Source can stand up, run, and read the state of — with no shared filesystem. The top track completes the nine-tool surface (S+0 → S+7); the bottom track lifts the same discover → recognize → deliver loop onto HTTPS and GitHub PRs and then makes the exit lifecycle legible (S+8 → S+13). Thicker nodes are the flagship sprints — first send, first round-trip, co-signed agreement, recognize-at-a-distance, PR delivery, and exit-aware status.
D · Executable walkthroughs

Eight artifacts. Each one proves a layer.

A walkthrough is an end-to-end script run against the real CLI and MCP server, not a contrived test. Each tier proves a strictly larger surface than the last and produces signed artifacts inspectable after the run.

Tier 11712232 · 05-21

Mutual recognition

A and B independently produce identities. Each verifies the other's entity statement and writes a signed recognition entry to its own peer cache.

Provesidentity layer
Tier 2bfaf1db · 05-25

First signal exchange

A signs a tension envelope; the local-fs transport delivers it into B's inbox; B's flyway_check independently verifies the signature against its cached copy of A's key.

Provessend + verify
Tier 364b112a · 05-25

First signal dialogue

B reads A's tension, verifies, and signs back — acknowledge / dispute / dissolve / transfer. A verifies and reads the response. Both sides hold complete signed records that reconcile without shared state.

Provesfull round-trip
Tier 410d7045 · 06-12

Co-signed agreement

A proposes a final-stage agreement; B co-signs by accepting. Each side independently materializes a byte-identical agreements/<id>.yaml from records it already holds — matching SHA-256, no authoritative copy.

Provesco-signing · byte-identity
Tier 54c894b6 · 06-17

Staging chain, objection integrated

A tension runs the full driver → requirements → draft → refinement → final chain. B objects at the draft — the work is one-sided — and A's refinement integrates it: an expectation moves from one Source to the other, and that split lands in the co-signed agreement.

Provesgovernance · objection → integration
Tier 68dfadaf · 06-26

Remote recognition

A peer is discovered from a remote HTTPS directory and recognized from its did:web URL — no shared filesystem. The remotely-fetched identity is still verified at recognition, never trusted by transport.

Provesdiscover + recognize at a distance
Tier 757e4dfe · 07-02

PR delivery

A signal is delivered by opening a pull request against the peer's repo — fork-first, no write access to their tree; the recipient merges to accept. Completes the discover → recognize → deliver loop with no shared filesystem; PR-delivered bytes are byte-identical to local-fs.

Provesdeliver at a distance · PR-as-consent
Tier 81576181 · 07-10

Exit-aware status

An exited relationship and an agreement closed by a project exit both read as closed from a single flyway_status — the co-signed file never rewritten. A 4-agent review then hardened the inbox-exit trust gate against replay before merge.

Provesexit lifecycle legible · gate hardened
E · Architecture decisions

Thirteen ADRs accepted. Each pins one load-bearing decision.

  1. ADR-0001 Project framing & scope. flyway is a protocol, not a runtime.
  2. ADR-0002 TypeScript as implementation language. Strict TS; pure core; I/O at edges.
  3. ADR-0003 Monorepo layout. Five packages: core, agent, mcp, cli, harness.
  4. ADR-0004 Agent skill as primary protocol interface. Agent Skills IO SKILL.md is canonical.
  5. ADR-0005 S3 patterns as canonical protocol vocabulary. Sociocracy 3.0 supplies the names.
  6. ADR-0006 Skill distribution and installation. flyway skill install.
  7. ADR-0007 Pluggable signers and on-chain anchoring. Signer interface for a future Cardano signer.
  8. ADR-0008 Signal transport convention. Signed envelope + inbox/outbox + pluggable transport.
  9. ADR-0009 Antecedent verification before signing. The rule lives in core; adapters cannot skip it.
  10. ADR-0010 Remote directory fetch (HTTPS). HTTPS-only, SSRF-guarded, size/timeout-bounded — the first non-local-fs op.
  11. ADR-0011 did:web resolution convention. did:web:github.com:owner:repo → raw identity artifacts; verified at recognition.
  12. ADR-0012 github-pr signal transport. Deliver by opening a PR; fork-first, PR-open = delivered, recipient merges to accept.
  13. ADR-0013 Exit-aware effective status & agreement membership. Effective closed read from verified exits — file never rewritten; inbox exits reuse the check gate; opaque co-signed projectId/syndicateId.
F · What's pending

The surface is complete. What's left is depth.

All nine tools have landed (through flyway_discover, S+7), and v0.2 has carried the whole loop off the shared filesystem — v0.2a (HTTPS directory fetch + transport seam), recognize-at-a-distance (ADR-0011), and v0.2b (github-pr transport, ADR-0012) are all shipped. What remains is depth and one gated transport:

  1. v0.2c url-webhook transport — direct HTTP delivery (ADR-0008, spec §5). Lower latency, but trades flyway's offline-first, auditable-git-trail property for an online requirement — gated on real sub-PR-latency demand. github-pr is the production default.
  2. ✓ exit-aware status — done at S+13 (ADR-0013): flyway_status reads the exit lifecycle back — a relationship or agreement closed by a verified exit reports as effectively closed, the co-signed file never rewritten.
  3. ✓ agreement provenance (Issue #2 / G8) — done at S+8: originTensionId propagates through the staging chain and is auto-stamped onto the co-signed agreement under both signatures; a forged link is refused.

Open issues by theme

Nine open issues (12 closed, including #2 at S+8 and the season-wrap batch #16 / #17 / #20). All open items are depth or design questions — none security. Numbers link to GitHub.

Protocol gaps
#19 proposedOwner recognition #28 shared verifyInboxSignal gate
Protocol design
#4 facilitator role #5 multi-party consent #18 sender retry/dedup
Schema / validation
#11 same-id collision #12 whitespace policy
Quality of life
#10 sync vs async fs #13 peerRepoPath validation
G · Cryptographic properties

What's enforced, and exactly where.

Every line below names a property a reviewer can audit by reading a single function in flyway-core. Adapters cannot weaken these — that's the whole point of ADR-0009.

Cryptographic invariants
Property Enforced at Verified at
Self-attestation flywayInit flywayStatus, recognizePeer
Peer attestation recognizePeer verifyRecognitionEntry, flywayStatus
Domain separation signArtifactInline verifyInlineSignedArtifact
Canonicalization canonicalize canonicalize (deterministic)
Tamper detection every signer every verifier
Cross-kind replay protection buildSignedSignal verifySignedSignal
Antecedent verification (ADR-0009) createTensionResponse (core) enforced at sign time
Co-signature byte-identity signAgreement (detached) materializeAgreement (SHA-256 match)
Agreement provenance (#2) createProposal (auto-stamp at final) carried under both co-signatures
SSRF guard (v0.2) assertPublicHttpsUrl per-hop, before each network call
Pre-trust remote resolution resolvePeerIdentity (pre-trust) recognizePeer (sig + key binding)
Path-traversal safety peerCachePathSegments enforced at parse time
Recognition-window ordering flywayCheck flywayCheck
Exit-honor gate (ADR-0013) honorInboxExit / honorOutboxExit placement + recipient + verify, before an exit informs state
Atomic write writeSignalFile (flag: 'wx') enforced at write time
H · For reviewers

A thirty-minute read.

If you have half an hour to decide whether flyway is worth adopting, read these four artifacts in order.

  1. 01 · 5 min

    README.md

    Framing and tool surface. What flyway is.

  2. 02 · 10 min

    how-flyway-works.md

    Concrete sequence diagrams and contracts.

  3. 03 · 10 min

    Tier 4 walkthrough

    The single most informative artifact in the repo — consent through to a co-signed agreement.

  4. 04 · 5 min

    ADR-0009

    Flavor of how invariants get captured.