docs: running field-issue log from building with Ultra - #3
Open
Astrapolis-peasant wants to merge 2 commits into
Open
docs: running field-issue log from building with Ultra#3Astrapolis-peasant wants to merge 2 commits into
Astrapolis-peasant wants to merge 2 commits into
Conversation
added 2 commits
July 27, 2026 17:01
Add docs/FIELD-ISSUES.md, an intake and triage log for defects observed while operating the distributed plugin on a real project. The in-product gap ledger records project baseline gaps, not defects in this package, so field reports had no home. Seven entries, each with the mechanism located in source, a disposition, and open triage questions: - F-001 no revision path for a completed research step; the same-step re-completion allowance is unreachable while any later step is pending - F-002 no transition for rejecting an option set; the only route records a deferral the owner never requested - F-003 decision history is durable but has no user-facing read surface - F-004 greenfield cannot reach code before baseline convergence, and the walking-skeleton rule is unenforced prose - F-005 a session can run to context exhaustion with every gate healthy - F-006 delivery blocked by baseline drift that ordinary development creates; only _STALE is tolerated, _MISSING is fatal - F-007 a blocked baseline disables the read-only review gate that would justify unblocking it No source, contract, or test changes.
Capture the actual blocker codes from the reporting project and replace the earlier source-only triage of F-006. The delivery dead end was not baseline drift: gts-baseline-v2 never converged (status blocked, zero blocking gaps) and the deliver workflow stayed bound to a cancelled change. system doctor names both conditions in terminal_authority_runs while the human-readable status output reports only a workflow count, so the diagnosis never reached the operator. Retitle the entry to the diagnosability defect and record the mis-triage: three mechanisms proposed from source reading were all wrong. Add F-008. The recommended operating mode, a new host session per ultra-dev task, is undocumented, and "session" names both an Ultra task lease and a host conversation. ultra-dev advises reusing an existing session, which is correct for leases and the opposite of the intended practice when read as conversation guidance. Amend F-005 to point at F-008 as its working answer, and add a fourth cross-cutting theme: the runtime often knows more than it says.
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.
This PR stays open and grows. I'm continuing to build with Ultra, so new findings
append to the
## Opensection as I hit them, and entries move to## Resolvedwith acommit and test reference as they get fixed. Merge it whenever the current contents are
useful — I'll open a fresh batch after that rather than letting one PR run forever.
It is a record, not a fix: no source, contract, or test changes. The in-product gap ledger
tracks project baseline gaps rather than defects in this package, so field reports had no
home.
Every entry is reproduced against
1d63892before being called a defect — either byexecuting the runtime against a seeded fixture, or by capturing live state from the
project. Where a mechanism was proposed from source reading and later contradicted by
evidence, the entry says so; see F-006, where all three initially proposed mechanisms
turned out to be wrong.
Current entries
ultra-deliverdead end that the status output cannot explainEach entry records the mechanism with
file:linereferences, a disposition, and an"open question for triage" naming candidate fixes rather than presuming one — several are
contract decisions that belong to you, not implementation details.
Themes so far
1. Ultra models the project's state but not the owner's. State transitions are
rigorous and well guarded. Owner-side events — I changed my mind (F-001), these options
are wrong (F-002), what did I choose before? (F-003) — have no modeled transitions.
Where a path exists it is reachable only by recording something the owner did not do, such
as deferring an unanswered question.
2. Escape hatches exist but are invisible.
decision.supersede(F-002), same-stepre-completion (F-001), and
baselineGateForChange's drift tolerance (F-006) are alldeliberate, well-designed accommodations. Each is gated on a precondition the owner cannot
observe and no Skill explains, so in practice each reads as an arbitrary refusal. Making
existing accommodations legible would likely close more reported pain than adding new
transitions.
3. The guarantees are strongest on integrity and weakest on time. Evidence,
provenance, and digests are enforced. The instructions that protect the owner's hours —
walking skeleton first, avoid unconsumed scaffolding, keep context bounded — are prose or
warnings that no gate checks (F-004, F-005). The most expensive observed failure, six
hours with nothing runnable, passed every gate cleanly.
4. The runtime often knows more than it says. F-006 is the clearest case:
system doctorhas a dedicatedterminal_authority_runsfield that named the exact problem,while the human-readable status output showed only
Workflows: active=2 blocked=1 health=fail. Several findings would have been self-diagnosing if existing internal detailreached the operator.
Suggested order
Rendering and documentation changes are cheap and address most of the reported pain:
surface
terminal_authority_runs(F-006), add a decision-history panel toultra-status(F-003), document the session-per-task operating model (F-008), and exempt read-only
review from baseline-gate blockers (F-007).
The revision contract behind F-001 and F-002 is one design decision rather than two
patches, and is worth settling before either is implemented — otherwise the risk is
several inconsistent escape hatches.
Happy to split any entry into its own issue, supply more detail, re-run a check, or test a
fix against the same project.