Wave Summary
| Field | Value |
|---|---|
| purpose | make the factory understandable as a chronological, filterable story; distinguish work that is rejected from work that is accepted but intentionally parked; preserve grounded plans without accidentally scheduling them |
| development window | opened August 7, 2026; this entry records the opening checkpoint rather than a completed exit |
| baseline | 162de6dd on main |
| triggering friction | an AWS-hosted roadmap produced executable plans that were not ready to run; Yesod had no deferred lifecycle state; the existing /viz/live-events.html page exposed a narrow event rail rather than a human-scale activity stream |
| shipped foundation | catalog activity history, note-status history, a standalone live-events page, cursor-based event backfill, and the yesod factory status rollup |
| open work | ys-yes-b3iy adds the deferred lifecycle state; ys-yes-xqhi turns the live-events prototype into a leveled, multi-tool operator stream |
| exit condition | from one page, an operator can tell what happened, at the desired level of detail, for selected tools; accepted parked work is represented as deferred, remains non-dispatchable, and can return to open with its plan and history intact |
Wave 6 asked whether the factory could become quiet without losing durable truth. Wave 7 asks the complementary question: when the factory is active, can a human understand what it is doing without reconstructing the answer from its databases and dashboards?
Yesod already records more state than most software factories. Notes have lifecycle histories. Beads record executable structure and dependencies. Dispatch runs, leases, gates, merge jobs, agents, and mail each expose their own transitions. The problem is not missing state in the abstract. The problem is that state is distributed across surfaces with different vocabularies, retention rules, and levels of detail.
A human does not experience those surfaces as separate subsystems. They ask what just happened, what is running, what is waiting, what was deliberately put aside, and whether a transition matters. Wave 7 treats those questions as a product contract. The factory becomes legible when its durable records form a coherent story at the level of human attention.
This opening checkpoint does not declare Wave 6 complete. Identity hardening, idle shutdown, and transient-message cleanup retain their own exit obligations. Wave 7 begins from the state they helped clarify: durable truth and disposable execution are different things, and an operator surface must say which kind of evidence it is showing.
The Factory Had State but No Story
The command yesod factory status, tracked by ys-yes-q0e7, consolidated an
important set of operational facts. It made queue, supervisor, runner, gate,
and fleet state available through one rollup rather than a sequence of private
queries. That is a major improvement in observability, but a status snapshot
answers only one class of question: what appears to be true now?
An operator also needs causality. Why did a note leave open? Which Beads were
created when it was grounded? Did a worker claim the task, or did a dependency
change make it eligible? Is a gate merely slow, actively running, retrying an
infrastructure failure, or finished red? A snapshot can show the latest state
while concealing the transitions that explain it.
Yesod’s current interfaces make that explanation possible but expensive. The catalog landing page has an activity stream for catalog mutations. Note detail can show lifecycle history. The live-viz event log carries Bead and dependency events. Refineries and run pages expose gate and execution timelines. An operator can assemble the story, but only by knowing which surface owns each piece and mentally joining their identifiers.
Legibility is the removal of that mental join. It does not mean flattening all events into an undifferentiated log. It means giving each event a stable identity, time, subject, actor, tool, kind, and human-readable meaning, then allowing the operator to choose how much machinery to see.
Parked Work Is Not Rejected Work
The AWS-hosted Yesod roadmap exposed a second vocabulary gap. Phase 1 was decomposed into four fresh feature records:
- external PostgreSQL portability (
ys-yes-9xio, root Beadyes-fq93); - authenticated HTTP mutation boundaries (
ys-yes-v4cl,yes-ozj5); - provider-isolated MicroVM runtime flavors (
ys-yes-zkae,yes-0isq); and - a clean-install acceptance path (
ys-yes-81wu,yes-pip6).
Each root has three file-scoped child Beads, an internal dependency chain, acceptance criteria, and a targeted gate. The first three features can proceed independently; the clean-install proof depends on all three. This is executable planning, not a list of aspirations.
It is also work that should not run yet. The roadmap is exploratory, the AWS delivery decision has not been made, and placing twelve well-specified child tasks in front of an autonomous dispatcher would confuse preparedness with authorization.
Yesod’s lifecycle vocabulary had no honest state for that combination. open
means actionable work available for planning or dispatch. wontfix means the
work was rejected or abandoned. A dependency-derived block means the work
would proceed if its prerequisites completed. A hold or missing arm is an
execution-control fact. None means “we accept this direction, have preserved a
good plan, and intentionally do not want it scheduled.”
Until a better state exists, the four AWS records are temporarily wontfix,
with comments saying they should become deferred once ys-yes-b3iy ships.
Their root Beads are closed, while the child trees, tags, dependencies, and
plans remain preserved. The workaround is safe for dispatch, but semantically
wrong. A future reader counting rejected work cannot distinguish an abandoned
idea from a deliberately parked roadmap phase without reading the comments.
The proposed deferred state repairs that meaning. It represents accepted work
that is intentionally outside the active backlog. It must never be claimable,
dispatchable, or automatically armed. Returning it to open must preserve its
tags, Bead linkage, dependency graph, metadata, plan, and history. wontfix
then regains a precise meaning: no current intention to implement.
Grounding Became a Durable Asset
The temporary AWS state reveals a broader design principle: planning and scheduling are separate authorities.
A grounded feature is valuable before a worker is allowed to touch it. The note records the product boundary and acceptance test. Its root Bead gives the feature one merge identity. Three to ten child Beads give an agent concrete, file-level steps. Bead dependencies order work inside that merge boundary; note dependencies order independently mergeable features. Together they make the plan inspectable, reusable, and cheap to revalidate later.
None of that implies permission to spend tokens, launch a MicroVM, write a branch, or alter AWS. Grounding answers “what would we build?” Dispatch answers “should the factory build it now?” Conflating them makes careful roadmap work dangerous: the better the plan, the more likely an autonomous system is to mistake it for an immediate command.
deferred turns a grounded plan into a durable portfolio asset. The plan can
survive a change in priorities, a missing provider capability, or a budget
decision without polluting the active queue or being mislabeled as rejected.
When it is revived, a planner does not start over. The planner revalidates the
baseline, file paths, dependencies, and acceptance gate, then returns the note
to open.
From Event Rail to Activity Stream
The existing page at /viz/live-events.html is the natural surface for the
other half of this wave. Its source, yesod/live-viz/live-events.html, is a
small React page backed by AllBeadsAdapter. It loads snapshot events, opens a
live stream, and renders a newest-first rail. The page recognizes generic
audit events, Bead events, and dependency events. It shows a connection
indicator, relative and wall-clock time, actor, target, and a short message.
That is useful infrastructure, but it is still a prototype rather than a factory activity product. It has no multi-tool selector, no event-kind filter, no expandable structured details, and no distinction between a milestone and a heartbeat. It keeps a client-side window of 500 events. Its pause control stops the relative-time clock but not event ingestion. Its typed-event handler currently risks appending the same event twice. A demo-data toggle remains in the production page.
The feature request ys-yes-xqhi does not call for another page. It names this
page as the implementation target and asks the existing catalog, status,
live-viz, Bead, refinery, and gate sources to converge on a normalized event
envelope. Initial history and live delivery must use the same identity and
filter semantics. Cursor recovery must make retention gaps visible rather than
silently presenting an incomplete story.
The product distinction is selectable detail:
| Level | Operator meaning | Representative events |
|---|---|---|
| high | meaningful milestones | tool onboarded; note created; every note lifecycle change; dispatch, gate, merge, deployment, or major failure |
| medium | work structure and decisions | root or child Bead created, claimed, or closed; dependency changed; planning completed; runner assigned; gate batch formed |
| low | diagnostic mechanics | heartbeat, retry, lease, queue transition, reconciler pass, worker phase, or per-shard gate progress |
The levels are cumulative. High shows only milestones. Medium adds the work structure that explains them. Low adds the machinery needed for diagnosis. This is not merely a severity filter: a successful heartbeat is low-detail but not low-importance when diagnosing liveness, while a routine note transition is high-level because it changes the user’s understanding of the work.
The second control is scope. An All Notes-style multi-select tool filter should let the operator watch one repository, a related group, or the whole factory. The same filter must constrain loaded history and new streamed events. A newest-first catch-up view should coexist with a live-follow mode that does not steal scroll position while the operator is inspecting older evidence.
Attention Became a Control Plane
Raw telemetry optimizes for completeness. Human attention does not. It is bounded, changes with the task, and is easily defeated by an event source that treats every database write as equally prominent.
The high, medium, and low contract is therefore a control-plane decision. It defines which transitions deserve immediate human awareness and which remain available when the operator asks for more resolution. The classification must be canonical per event kind rather than guessed independently by each page. Otherwise a gate retry will be a milestone in one view, a diagnostic in another, and absent from a third.
The activity stream also needs a strict disclosure boundary. Low-level does not mean raw. Event details may contain stable identifiers, structured error classes, durations, counters, and links to bounded logs. They must not contain provider secrets, reusable credentials, raw prompts, or unbounded stdout. The stream is an index into evidence, not a second log archive.
This makes the activity page more than a visualization. It becomes the place
where durable intent and disposable execution meet without being confused.
A deferred transition is a high-level event because it changes portfolio
intent. A MicroVM heartbeat is low-level because it describes one disposable
runtime. Both remain auditable, but they compete for attention differently.
What Has Landed, and What Remains
| Area | Evidence at this checkpoint | Required before wave exit |
|---|---|---|
| current-state rollup | yesod factory status consolidates major operational surfaces (ys-yes-q0e7) |
link status facts to the events that produced them |
| catalog activity | the yesod serve landing page records catalog creation and mutation activity (ys-yes-zsy3) |
normalize catalog events with factory events instead of maintaining a separate story |
| live page | /viz/live-events.html exists and consumes snapshot plus streamed Bead events (ys-yes-u150) |
replace prototype controls and narrow normalization with the leveled, filterable operator experience |
| reconnect safety | cursor/backfill and snapshot recovery infrastructure exists (ys-yes-ih57) |
prove initial history plus reconnect has no silent gaps or duplicate rendering across the unified envelope |
| parked AWS work | four Phase 1 features have grounded three-child trees and explicit cross-feature ordering | represent them as deferred rather than temporary wontfix, then revalidate rather than replan when revived |
| lifecycle vocabulary | wontfix, holds, dependencies, and planning each have distinct existing meanings |
implement deferred across constraints, writers, filters, views, exports, search, distillation, and dispatch exclusion (ys-yes-b3iy) |
The New Exit Criterion
Earlier waves proved that the factory could carry work, survive failure, merge through a remote gate, and stop when no action remained. Wave 7 is complete when the operator no longer needs subsystem archaeology to understand those capabilities in motion.
From one page, the operator must be able to answer:
- What happened, in chronological order?
- Which changes matter at a high, medium, or diagnostic level?
- Which tools and work objects were involved?
- What is running, waiting, completed, or intentionally parked?
- Who or what caused each transition?
- Did the stream reconnect cleanly, or is some history unavailable?
At the same time, the lifecycle must tell the truth about intent. Accepted but
parked work must be deferred, excluded from every execution path, and
recoverable without losing its grounded plan. Rejected work must remain
wontfix. Active work must not become eligible merely because it is detailed.
The durable lesson is that observability is not the accumulation of status pages. A factory becomes legible when its state changes form a coherent, filterable narrative and when its lifecycle vocabulary distinguishes what the system can execute from what the human has authorized it to pursue.