docs: absorb the field reviews — host-boundary gaps, emu-dev skill, rulings - #516
Merged
Conversation
The PR-421 voice review — the first real consumer of the design principles — surfaced rules the docs should have stated: the null-list-in-concatenation boot-killer joins the Limbo shell gotchas (the review cited it as already present; now it is), the ninep-server skill gains 'the fid is the session' (Clunk/Flush teardown, DMEXCL instead of global busy flags, chatsrv/gpusrv exemplars) and the 'a 9P write can fail — check the reply' client rule, and the smells table gains executing host-authored files at boot (config is data, never code). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017Eo29oZp7mPig1XekwRPsq
…ctual review) A counterfactual audit tested the corpus against PR #421 (the non-compliant voice PR that motivated the guidance): had the docs existed, which defects would they have prevented? The architectural class scored well; the consistent blind spot was every boundary with the host. This closes the eight gaps it filed: - emu-dev skill (new): kproc kill path (oshostintr interrupts syscalls, not condvar waits; osenter/osleave; never hold a QLock across a blocking wait), CONF/mkdevlist wiring (unwired driver = dead code), the incumbent rule, drivers-deliver-events layering. - DESIGN-PRINCIPLES: 'The host boundary' section (pin + checksum everything fetched; installers never build-and-execute unpinned HEAD; boot never executes host-authored files; placement is shipping via the release copy loop); 'Writes are RPCs — on both sides'; smell rows for global busy flags and UI policy in drivers. - LIMBO-FOR-GO-PROGRAMMERS: null-list concatenation and failed-redirection rows hoisted into the shell table as the single lookup point. - Tutorial: caller-side dual of failed-at-the-writer; fid-is-the-session pointer on the blocking-reads bullet. - limbo-test: norms — behavior not source text, a suite that skips in CI guards nothing, the contract test is the durable 'I ran it'. - limbo-dev: pre-image hygiene before opening a PR. - Maintainer ruling applied: dis/tests/*.dis is TRACKED — stale gitignore line dropped, CLAUDE.md/limbo-dev/limbo-test now agree. - Maintainer ruling applied: sketch-first is policy — CONTRIBUTING states interface PRs without a proposal issue are returned; the style-gate workflow adds a soft proposal-link annotation; PR template gains the pinned-and-verified row; style gate documents its style-not-semantics scope. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017Eo29oZp7mPig1XekwRPsq
pdfinn
changed the title
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.
Summary
Two field reviews of the guidance corpus, both triggered by PR #421 (the non-compliant voice PR that motivated the guidance effort), absorbed in two commits:
Commit 1 — lessons implicit in the maintainer review of #421: the null-list-concatenation boot-killer, "the fid is the session", the check-the-9P-reply rule, the config-is-data smell.
Commit 2 — the explicit counterfactual audit of the corpus ("had the contributor followed these docs, which of #421's defects would have been prevented?"). Its verdict: the architectural class is well covered; the blind spot is every boundary with the host. All eight filed gaps closed:
emu-devskill — the C layer had zero coverage. Kill path (oshostintrinterrupts syscalls, not condvar waits;osenter/osleave; never hold a QLock across a blocking wait; bounded-poll shape of the incumbentemu/MacOSX/audio-sdl3.c, with osenter/osleave cited from the live port layer), CONF/mkdevlistwiring (a driver absent from the CONF is dead code — wire it in the same PR or don't ship it), the incumbent rule (read the rival you're replacing for the regressions it fixed), drivers-deliver-events layering.lib/placement a release decision). Plus "Writes are RPCs — on both sides", and smell rows for global busy flags (→ per-fid state,DMEXCL) and UI policy in drivers.Two maintainer rulings applied:
dis/tests/*.disis tracked — the stale.gitignoreline dropped; CLAUDE.md, limbo-dev, and limbo-test now agree with each other and with reality (56 tracked, actively maintained files).*9p.b/module/*.msources with no issue reference in its description; the PR template gains a pinned-and-checksummed row.Acceptance per the audit's own oracle: every finding in the #421 maintainer review now has a citable section (blockers 1.1–1.5 → Writes-are-RPCs / shell table / host boundary / emu-dev / fid-is-the-session; rework items 2.2–2.8 → existing sections plus emu-dev and host boundary).
Watch item, deliberately not changed: DESIGN-PRINCIPLES' speech9p distribution-transparency citation describes master accurately today; revisit if #421 lands helper-direct audio.
Testing
sh -nclean on the gate; local run unchanged (same 5 known legacy findings); workflow YAML validates..claude/skills/.🤖 Generated with Claude Code
https://claude.ai/code/session_017Eo29oZp7mPig1XekwRPsq