feat(boatstack): flow watch — bounded observe-compare loop over the frontier - #238
Merged
Conversation
…rontier New `flow watch` verb: re-observe the read-only frontier on an interval and exit on the first row-signature change (position, actor, lifecycle, failing checks), immediately when nothing can move, or at the deadline with a distinct exit code (1) so callers can tell change from timeout. Time flows through injectable seams so the loop is provable without real waiting; a failing gh observation degrades rows to Unknown and the loop stays bounded. The watch observes and exits — it never executes a transition and never writes, pinned across ticks including a terminal MERGED observation. SKILL.md and workflow.md document composing watch with the loop (watch exits → next-status → continue). control-law: watch-observes-and-exits-never-acts Disclosure-Reviewed: reviewed — public-safe only, private facet kept out of this commit
bigboateng
force-pushed
the
boatstack/flow-watch
branch
from
July 28, 2026 16:33
1623d81 to
fbab6ba
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Third slice of the published → merged program (stacked on #237). A published PR lives in an asynchronous world — CI runs, reviews land, merges happen — while Boatstack is a synchronous oracle.
flow watchis the smallest waiting primitive that bridges the two: it decides when to ask the oracle again, and hands control back the moment the answer differs.What changed
flow watch(--intervaldefault 30s, floor 5s;--timeoutdefault 30m;--json): each tick re-runs the read-only frontier observation and compares stable per-row signatures (stage, lifecycle, PR phase, actor, operation, failing-check set — deliberately not reason wording).changed(names the rows that moved, exit 0),terminal(nothing on the frontier can move — refuses to wait, exit 0),timeout(exit 1, so scripts and agent loops distinguish "something happened" from "still waiting").flowWatchNow/flowWatchSleep), so conformance runs instantly with a virtual clock.references/workflow.md(PR_OPEN -> WATCH): compose as watch exits →next-status→ continue; observation and actuation stay separate so waiting can never become acting.Boundary conformance
watch-observes-and-exits-never-acts— no writes, no transition execution path reachable, bounded by construction.flow_watch_conformance_test.go— positive (external phase change ends the wait and namesshipped/delivery), negative (no change → timeout outcome, frontier intact, tick count matches the virtual clock), bypass (delivery ledger byte-identical across many ticks including a terminal MERGED tick), failure-state (gh failing every tick → Unknown rows, loop still ends at deadline; all-terminal frontier → refuses to wait, 0 ticks).PR_UNKNOWN; store/config faults exit with the resolver's error.Evidence
go build ./... && go vet ./... && go test ./...— pass.2026-07-28-flow-watch-loop.md.Next slice:
delivery.terminalconfig (publisheddefault |mergedopt-in) + goal threading.