agentic-openwrt-packages
The governance shell for UDPspeeder-simd, a Forward Error Correction UDP tunnel (C++, forked from UDPspeeder). This repository holds the thought: the plans, decisions, personas, and the operating manual. The software itself, the action, lives beneath it as a bare store with a worktree, kept separate and independently versioned.
Read AGENTS.md first; it is the operating manual and works literally
(CLAUDE.md is a pointer to it). STRUCTURE.md is the one-page map.
The process that built this host lives in the
host repository.
Layout
| Room | Holds |
|---|---|
cast/ | personas (the Who); examples pending replacement |
plan/ | the milestone index |
call/ | decisions, in MADR format |
software/ | the hosted software, materialized locally (gitignored) |
tools/ | the verification tools, referenced submodules |
The software is pinned in .host-software and materialized with
host-lifecycle software --materialize . into software/<component>/<branch>/
(for udpspeeder-simd that is software/udpspeeder-simd/main/).
Tooling
host-lifecycle and host-lint drive the mechanical work. A fresh clone reaches a
set-up project with one command (bootstrap runs the submodules, the materialize,
the skill links, the hooks, and the completeness gate):
./tools/install-tools.sh host-lifecycle
host-lifecycle bootstrap .
License
This governance shell is released into the public domain (Unlicense). The hosted software, UDPspeeder-simd, carries its own MIT license in its worktree.
Cast: the project's Who
Personas: hypothetical archetypal actors, grounded in research, that keep the work anchored in who it serves. The process comes from Powell, Keenan and McDaid (2007), which builds on the personas in Cooper and Reimann's Interaction Design.
Mara and Wren are examples: the operators of any agentic project (e.g. agentic-acme), the human
who develops software and the agentic LLM who develops software. They illustrate
the method, not your project.
Each project builds at least one persona of its own, by discussion: the
operator and the agent elicit the actual users of the software under
development (allium's elicit). Add them here. See
applying-personas.md for the process.
(If your software under development is itself an agentic project, Mara and Wren may double as your real cast; the example sits at the meta level it was drawn from.)
Applying personas during planning
The XP-Persona process (Powell, Keenan & McDaid 2007) runs as a workshop with all interested parties (developers, customer representatives, management) before development begins. Steps one to six come from Interaction Design (persona development); steps seven to nine from XP story development. The aim is the minimum beneficial investigation before development starts, after which requirements and plans evolve.
- Brainstorm organisation goals. Record what the organisation wants the project to achieve; these reflect its intention.
- Brainstorm possible personas. Start broad, then combine through discussion to between two and twelve personas. Give each a name; the team refers to personas by name when making decisions, which keeps the view on the user rather than the system. Unless user research is available, the customer has the final say.
- Brainstorm persona goals. Set between two and six goals per persona; each goal states what the persona wants to achieve through the system. "A persona exists to achieve his goals, and the goals exist to give meaning to a persona" (Cooper 2004).
- Brainstorm persona personalization. Give each persona a personality and a technical ability relative to the system; a short paragraph or bullets of personal detail and nuance.
- Brainstorm persona scenarios. Describe interactions, not tasks: how a persona uses the system to reach a goal. No implementation detail in a scenario.
- Select the primary persona. This is the one who must be satisfied but cannot be satisfied by an interface designed for any other persona (Cooper 2004). It takes highest priority and feeds story prioritisation. More than one primary persona implies a separate interface for each.
- Create stories. From the persona goals and scenarios, write the user stories.
- Prioritise stories, using the primary persona as the guide.
- Estimate stories, estimated and agreed by customer and developers.
In our pipeline: steps one to six are the cast/ work (built by discussion);
steps seven to nine become plan/ (milestones are the stories, prioritised by
the primary persona, estimated); persona goals and scenarios feed spec/, where a
scenario becomes acceptance criteria becomes a behavioural spec.
Complementary practice reinforces the same steps (departing only on strong later
evidence): Cohn's "As a <persona>, I want <goal> so that <reason>" template
reinforces the named-persona stories of steps two and seven; Gothelf's
proto-personas reinforce the assumption-first workshop of steps two to five;
Patton's story mapping reinforces the create-and-prioritise of steps seven and
eight; behaviour-driven scenarios reinforce step five becoming executable
acceptance criteria.
Sources. Primary: Powell, S., Keenan, F. & McDaid, K. (2007), "Enhancing Agile Requirements Elicitation with Personas," IADIS Int'l Journal on Computer Science and Information Systems, vol. 2(1), pp. 82-95, ISSN 1646-3692. Complementary: Cohn, User Stories Applied (2004); Patton, User Story Mapping (2014); Gothelf, Lean UX (proto-personas); Jeffries, "The Three C's of User Stories" (2001); Cooper & Reimann, About Face (2003); Agile Alliance on BDD.
Diego (router administrator)
Diego runs the gateway for a remote site on a high-latency, lossy WAN link. He puts UDPspeeder-simd on that gateway, with a matching server endpoint he controls on the far side, to make the link usable for real-time traffic.
Goals
- Keep a lossy link usable for voice, video, and remote access by tunnelling the affected traffic through the client-and-server pair.
- Tune the redundancy ratio (the
-f x:ysetting) so he recovers lost packets without spending more upstream bandwidth than the link can spare. - Manage the tunnel through OpenWrt's service and configuration tools, without editing or building C++.
- Run the tunnel inside the CPU and memory limits of modest router hardware, where a feature such as io_uring may be missing from the kernel.
- See whether the tunnel is healthy and how much loss it is recovering, so he can adjust as the link changes.
Personalization and technical ability
A competent network administrator for a small operator or a remote installation. He is comfortable on the OpenWrt command line and with UCI configuration, reads logs, and scripts routine tasks. He is not a C++ developer, and he treats the tunnel as an appliance that has to stay up while he is not watching it.
Scenarios
- Diego installs the package on a satellite-backed site, points the client at his server endpoint, sets the redundancy ratio, and confirms that call quality holds up under measurable packet loss.
- A firmware upgrade replaces the device configuration. Diego re-applies his tunnel settings from a saved snapshot and verifies the link recovers without hand-tuning.
Priority
Primary end-user persona for UDPspeeder-simd, and the anchor for prioritising the tunnel's own stories. The tunnel exists to serve his link, so his constraints (appliance-grade stability on modest hardware, with no source edits) drive the software's defaults and ergonomics. He depends on Ingrid's package for the service integration he configures.
Grounded in the role and the UDPspeeder-simd source. Refine further by discussion with the operator (see applying-personas.md).
Ingrid (OpenWrt feed maintainer)
Ingrid maintains the packages feed and packages UDPspeeder-simd and its
dependencies for OpenWrt, so router users install the tunnel with opkg.
Goals
- Package UDPspeeder-simd cleanly for the feed, with correct dependencies such as libev, so it installs on a stock OpenWrt device.
- Build the tunnel across the OpenWrt target architectures the feed supports.
UDPspeeder-simd ships hand-written SIMD assembly (
xor_spe.S) and CPU-specific optimisation, so she confirms the package builds on MIPS, ARM, and x86, or falls back to a portable path where the SIMD one is unavailable. - Provide the OpenWrt service glue that upstream lacks. Upstream ships a raw command-line binary, so she adds an init script and a UCI configuration wrapper that let an administrator run the tunnel as a managed service.
- Keep the feed building across the supported OpenWrt release branches (for
example
openwrt-24.10through the current development branch), and bump the Makefile version and source hash when a new upstream release lands. - Offer fixes back to
openwrt/packageswith no rework, so authorship and commit style stay clean for the community feed.
Personalization and technical ability
An experienced package maintainer, fluent in the OpenWrt build system, Makefile feeds, and the feed layout. She reviews a steady stream of contributions and holds them to reproducible, hermetic builds and correct license metadata. She works several release branches at once, and she reads a diff for upstream-cleanliness before she forwards it.
Scenarios
- A new UDPspeeder-simd release lands. Ingrid bumps the feed Makefile version and source hash, builds the package for a MIPS target and an ARM target, and confirms it installs and runs on a test device.
- A contributor opens a change to the feed. Ingrid checks it applies cleanly and
carries no automated co-author trailer (see
call/0003) before she offers it toopenwrt/packages.
Priority
Primary persona for the packages lane. The feed exists to let her ship the software to OpenWrt users, so her packaging interface (the Makefiles and the service glue) and her upstream-clean workflow drive the lane's work.
Grounded in the role and the UDPspeeder-simd source. Refine further by discussion with the operator (see applying-personas.md).
Samira (security engineer)
Samira reviews UDPspeeder-simd as a network service that parses untrusted input. The tunnel reads UDP packets from the open network and decodes them in C++, so she treats every packet as potentially hostile.
Goals
- Assure that malformed or crafted packets cannot corrupt memory or crash the tunnel, since the receive path in C++ handles attacker-controlled bytes.
- Confirm the Reed-Solomon decode path enforces its buffer bounds under adversarial
input, and that a crafted stream cannot exhaust the decode buffer (
--decode-buf) or turn the server into a reflection or amplification vector. - Set expectations for the
-kkey correctly. It applies a simple XOR, which gives no cryptographic confidentiality, so she checks that the defaults and the documentation state the safe pattern plainly: run UDPspeeder under a real VPN such as OpenVPN when the traffic needs protecting. - Tie each security claim to a rung of the verification ladder, so a claim rests on a check rather than an assertion.
Personalization and technical ability
A senior security engineer who reads C++ fluently, threat-models network services, and runs fuzzers and static analysis. She distrusts undocumented invariants and asks for the check that establishes one. She prefers a bound proven for all inputs over a bound sampled by tests.
Scenarios
- Samira fuzzes the packet-receive path with malformed frames under address and undefined-behaviour sanitizers, reviews how the decode bounds are enforced, and records the invariants she expects as spec obligations for the requirements lane.
- Reviewing a change to the FEC buffer handling, she asks for the decode bound to be proven for all inputs where the C++ code admits a bounded model check, and exhaustively fuzzed under sanitizers where it does not, before the change ships.
Priority
Secondary persona, cross-cutting the tunnel and the feed. She is a served reviewer whose obligations feed the spec lanes, so her concerns become behavioural specs, timing checks, and code-conformance proofs rather than a separate interface. On the feed she also watches the supply chain, so a Makefile fetches only pinned, hash-verified sources.
Grounded in the role and the UDPspeeder-simd source. Refine further by discussion with the operator (see applying-personas.md).
PLAN: milestone index
The ordering authority. Milestones are listed here in the order they are worked;
their folders are named NNNN-slug (zero-padded, and the number is identity, not a
sort key; see call/0000). A milestone is a thin, persona-serving increment.
Worked in this order:
- plan/0000-openwrt-udpspeeder-simd-package. Adds an OpenWrt feed package for udpspeeder-simd that answers the request at https://github.com/openwrt/packages/issues/28562 (Ingrid's story).
- plan/0001-dns-lease-manager.
Adds a DNS lease manager to udpspeeder-simd so the client's
-rtakes a hostname, resolving it to candidate IPs, refreshing before TTL expiry, and re-pointing the tunnel across IP changes and collapse; ships as v1.1.0, the first minor bump (Diego's story, Samira's spec-lane obligations). - plan/0002-udpspeeder-simd-socket-marks.
Adds
--fwmark,--cookieand--dscpsocket marks with an honor-or-refuse contract, a Windows qWAVE tier, FreeBSD and Windows CI lanes, and the UCI wiring for the marks Linux honors (Diego's shaping story, sdanfa's request). - plan/0003-readme-rewrite-front-door. Rewrites both READMEs as the front door to the fork as its own software -- new diagrams, full credit to upstream UDPspeeder, English and Chinese kept one-to-one -- with every claim held to evidence.
- plan/0004-patch-release-and-feed-refresh. Ships v1.3.1 so the release page carries the persona-reviewed front door, steadies the READMEs' checksum example against drift, and re-pins the openwrt/packages udpspeeder-simd MR at 1.3.1 (it still offers 1.0.0) with a recomputed mirror hash; the operator's reply in that thread follows the update.
Add an OpenWrt package for udpspeeder-simd
- Status: planned
- Persona: Ingrid (OpenWrt feed maintainer)
- Serves: https://github.com/openwrt/packages/issues/28562
- Scope: the
packagesandudpspeeder-simdcomponents - Package maintainer: David Connolly david@connol.ly
- Target: OpenWrt master for the first pull request; a release-branch backport is constrained by policy (see the rules below)
- Decisions:
call/0004(coexist, dynamic linking),call/0005(build adjustments in the fork)
Why
The issue at https://github.com/openwrt/packages/issues/28562 asks for the
performance-optimised UDPspeeder on low-end devices; the reporter's target is
ath79/generic, a MIPS 24Kc core. UDPspeeder-simd is that optimised fork. Rather
than repoint the existing net/udpspeeder package at a fork, this milestone adds a
separate net/udpspeeder-simd package that coexists with udpspeeder.
On ath79 the gain comes from the portable word-width XOR and the portable
Reed-Solomon speedups, not from SIMD. The source carries no MIPS SIMD path, and
none is worthwhile on the 24Kc core (MSA is absent on that core, and its optional
DSP ASE targets fixed-point math rather than vector XOR).
OpenWrt maintainer rules this milestone follows
From the feed's CONTRIBUTING.md (pinned in the packages worktree) and
https://openwrt.org/docs/guide-developer/packages :
- Pin the source to a fixed commit or tag with a
PKG_MIRROR_HASH, never a branch head or a "latest" archive. This is also what the issue requests. PKG_MAINTAINERis a real name and a real, public email (David Connolly david@connol.ly). A GitHub noreply address is rejected.PKG_LICENSEis the SPDX identifierMIT, withPKG_LICENSE_FILESnaming the license file (LICENSE.md) in the fork.PKG_RELEASEstarts at 1.- No dependencies outside the OpenWrt core packages or this feed.
- Each pull-request commit subject is prefixed with the package name
(
udpspeeder-simd: add package) and carries aSigned-off-bythat matches the author (a real name and a public email), with no automated co-author trailer (the packages rule incall/0003). The sign-off is the DCO, which is separate from the co-author trailer. - A
test.shbeside the Makefile lets the OpenWrt CI runtime-test the package on its supported architectures. - Release branches (
openwrt-XX.YY) take only security and bug fixes. Adding a new package to a release branch is against policy, so a backport is not a routine cherry-pick (see#backports).
Design decisions
- Interop (
call/0004): a distinct packageudpspeeder-simdwith distinct paths (/usr/bin/udpspeeder-simd,/etc/config/udpspeeder-simd,/etc/init.d/udpspeeder-simd), no file clash withudpspeeder, noCONFLICTS. - Linking (
call/0004): dynamic, withDEPENDSon the shared libraries the binary needs, like the existingudpspeeder. No static build. A static C++ binary is larger on flash, which works against the low-end devices this issue targets, and static linking runs against OpenWrt's shared-library model. - Build adjustments (
call/0005): they live in the fork's makefile, after which the.host-softwarepin is updated. The fork commits keep the normal sign-off and co-author trailer; only the packages repo drops the trailer. In practice no fork change was needed: the feed'scc_crossand gitversion Build/Prepare sufficed. - SDK for local validation: the public prebuilt x86_64 snapshot SDK (the one OpenWrt
CI uses), not a from-source build (
make worldproved excessive for this). The embeddedopenwrtcomponent stays but is not required for this path. Local validation covers x86_64; multi-architecture, includingath79/generic, runs in the CI lane. Snapshot OpenWrt packages are.apk, not.ipk. - CI validation (
#ci-sdk-lane): lives in the host repo (.github/workflows/udpspeeder-simd-sdk.yml), never in the openwrt PR, so the PR stays a discrete package addition. It builds the fork's package branch against the current snapshot SDK forx86/64andath79/generic. - Release users (
#backports): OpenWrt policy blocks a new package on release branches, so there is no backport.docs/udpspeeder-simd-on-openwrt-releases.mdshows a developer or power user how to self-apply it with a release SDK or buildroot.
Build sequence
Make the fork build cleanly across architectures
- verify: attested operator
Author the udpspeeder-simd feed package Makefile
- depends: #fork-build
- verify: attested operator
Author the service integration
- depends: #feed-package
- verify: attested operator
Add the runtime test script
- depends: #feed-package
- verify: attested operator
Add the OpenWrt SDK build lane to CI
- depends: #feed-package
- verify: attested operator
Confirm polite interop with the udpspeeder package
- depends: #service-integration
- verify: attested operator
Open the pull request to OpenWrt master
- depends: #interop, #test-script
- verify: attested operator
Evaluate a release-branch backport under policy
- depends: #pr
- verify: attested operator
Take upstream's cross_cxx merge into both packages
- depends: #pr
- verify: attested operator
DNS lease manager for udpspeeder-simd (v1.1.0)
- Status: planned
- Persona: Diego (router administrator); Samira cross-cuts (spec lanes)
- Serves: Diego points the client at a hostname endpoint and the tunnel keeps itself alive across IP changes, TTL expiry, and tunnel collapse, without him watching
- Scope: the
udpspeeder-simdcomponent - Decisions:
call/0008(versioning and release policy),call/0009(the C++-compatible single header)
Why
The client's -r option requires an IP literal today: address_t::from_str
(common.cpp) splits host:port and demands inet_pton succeed, so a hostname calls
myexit(-1). Diego's gateway points at a server endpoint he controls on the far
side; when that endpoint moves (dynamic DNS, provider IP churn), he must find the new
address and hand-edit his configuration. A tunnel meant to be an appliance he does
not babysit should follow the endpoint itself.
This milestone adds a DNS lease manager: a single-header, allocation-free,
nonblocking, TTL-aware DNS Locator-Hint Cache. The client resolves -r hostname:port
to candidate IPs, leases them for an effective TTL, refreshes before expiry, and
re-points the tunnel when the resolved IP changes. It treats DNS as an untrusted,
mutable locator-hint source (the tunnel test the candidates via the data plane), not
as a trust anchor. This is the first minor version bump; every release before it
was a patch (v1.0.6 was the last).
The OpenWrt feed package is out of scope here; the fork release is a prerequisite for a later package bump.
Design decisions
- The header is written as valid C++11 (
static inlinethroughout) rather than strict C11, because the fork builds C++-only and the negative constraints the spec imposes (no allocation,mem*only, no OS resolver, no threads/atomics/signals, no recursion/longjmp, no float, no unaligned access, no global mutable state, nostdio) carry over unchanged. Seecall/0009. - The state machine adds a
STALEstate to the spec's seven: on a failed refresh the last-known candidates stay servable untilstale_max_mselapses (default 1 hour;0means serve stale indefinitely). This is the keep-last-known-IP policy, made explicit, observable, and TLC-testable. - TCP fallback on truncation (TC=1) is included, per RFC 1035 and the imported spec: the header gains UDP-pending / TCP-connecting / TCP-receiving transport states and a 4096-byte TCP receive buffer.
- Client mode only. In server mode the
-rvalue names the client endpoint and stays IP-only; a hostname there is rejected at parse time with a clear error. - Verification carries both spec lanes: a
.alliumrequirements spec (allium-cli check/analyse/plan in the fork CI, obligations discharged by tests) and a.tlastate-machine/timing spec (TLC model check in the fork CI). Specs live with the software, per the methodology. - Release mechanics follow the house rule: the tag is the release; the banner
PROGRAM_VERSIONand the tag must agree; the fork CI publishes the per-architecture binaries; the host re-pins.host-softwareand records the release receipt. Versioning policy is recorded incall/0008.
Build sequence
Author the DNS lease manager header
- verify: attested operator
Author the allium requirements spec and wire its lane
- depends: #dns-header
- verify: attested operator
Author the tla state-machine spec and wire TLC
- depends: #dns-header
- verify: attested operator
Integrate the client
- depends: #dns-header
- verify: attested operator
Discharge the spec obligations with tests
- depends: #allium-spec, #tla-spec, #integrate
- verify: attested operator
Bump to v1.1.0 and release
- depends: #tests
- verify: attested operator
Re-pin the host and record the release
- depends: #release
- verify: attested operator
Socket marks for udpspeeder-simd (fwmark, cookie, dscp)
Status:; complete 2026-11-12
- Status: planned
- Persona: Diego (router administrator, policy routing and shaping); Samira cross-cuts (spec lanes)
- Serves: UDPspeeder-simd issue 1 (sdanfa's fwmark request, arrived via the openwrt/packages 29901 thread because this fork's tracker was closed; the idea and the first prototype are theirs)
- Scope: the
udpspeeder-simdcomponent and its feed packages - Decisions:
call/0008(versioning and release policy governs the bump); the marking-surface design (honor-or-refuse, cookie out of UCI, qWAVE in scope) is recorded as a call on acceptance
Why
Diego routes a tunnel through an OpenWrt box that shapes by firewall mark: the
tunnel's outer packets must carry fwmark so policy routing can send them out
the WAN without recursing through the tunnel itself, and dscp so the wider
path can treat them as voice-like. Today the only way to mark udpspeeder-simd
traffic is an external nftables mangle rule guessing at the sockets; sdanfa
asked for the native option and prototyped it untested.
The milestone adds three command-line marks with one contract: a mark the host cannot honor is refused at startup, never silently dropped.
| flag | mechanism | honored on | refused on |
|---|---|---|---|
--fwmark <u32> | SO_MARK | Linux | macOS, Windows, BSD |
--cookie <u32> | SO_USER_COOKIE | FreeBSD/DragonFly (ipfw) | everywhere else |
--dscp <0-63> | IP_TOS<<2 / IPV6_TCLASS; qWAVE on Windows | Linux, Darwin, BSD, Windows | nowhere |
Design notes:
- One variable per flag, zero default meaning untouched;
u32_t;strtoulbase 0 (hex or decimal) with end-pointer, range and leading-minus checks; fatal on garbage. sdanfa's prototype broke here (sscanf("%x" SCNu32)) and gets replaced, with credit, not cherry-picked. - Marks dress every tunnel data socket in both creators (after
set_buf_size, beside theSO_BINDTODEVICEprecedent); the startup log states the effective marks. - Resolver traffic is never marked. DNS queries ride libc sockets the creators never touch; the spec states it as a rule so no refactor marks "all sockets" and builds the policy-routing loop.
- Marks survive a tunnel re-point by construction on Linux/BSD (applied at fd creation); on Windows qWAVE is destination-keyed, so the lease manager's re-point re-tracks explicitly, and the handle closes on shutdown.
- No wire-protocol change; marks are host-local and need no version agreement between tunnel ends.
SO_PRIORITY(overlaps dscp for wifi classes) and symbolic DSCP class names are out of scope; the manual documents how dscp reaches WMM access categories per platform and points Windows users atNew-NetQosPolicy.
Specification and testing
The component already carries both spec lanes (dns_lease_mgr.allium with its
obligations manifest, and the TLC suite under spec/); this milestone follows
that pattern:
socket_marks.allium, authored through the elicit skill at domain level (no setsockopt in the spec): three config fields, apply-before-use, the resolver rule, the refusal rule, the re-point rule. No TLA spec: pure configuration surface, no ordering semantics -- stated, not silently omitted.- Red-green: the bench harness grows the marking tests first (parse accept and
reject including negative wraparound, per-platform refusal,
getsockoptround-trip apply, IPv6 parity, re-point persistence), failing on unmodified code, then the implementation greens them. - Two new host-OS CI lanes stand up in the component's ci.yml:
- FreeBSD via the macOS-runner VM (
vmactions/freebsd-vm, pinned): native build,--cookieapply and--dscpapply for real,--fwmarkrefusal. - Windows on
windows-latest(MSYS2/MinGW, matching the codebase's__MINGW32__layer): parse and refusal tests, the qWAVE flow completing, and an e2e asserting the DSCP byte on the tunnel's own packets with the built-inpktmon. Each lane covers exactly what the others cannot; every refusal path is somebody's tested behavior.
- FreeBSD via the macOS-runner VM (
OpenWrt wiring
The UCI surface offers the marks Linux honors: option fwmark and
option dscp in udpspeeder-simd.config with guarded init appends.
--cookie is absent by rule (OpenWrt is Linux; the option would be a
guaranteed startup death), with no narrating comment; the CLI and manual
document all three flags for hand-run binaries everywhere.
Build sequence
Elicit socket_marks.allium
- verify: allium check + analyse + plan green for the new spec in the component CI
- inputs: dns_lease_mgr.allium
Author the obligations manifest
- depends: #elicit-socket-marks-allium
- verify: host-lifecycle obligations socket_marks.allium --tests bench --strict-discharge
- inputs: socket_marks.allium
Stand up the FreeBSD lane
- verify: the lane runs the existing suite green on FreeBSD before the feature lands
- inputs: .github/workflows/ci.yml
Stand up the Windows lane
- depends: #stand-up-the-freebsd-lane
- verify: the lane builds the MinGW target on windows-latest and runs the existing suite green
- inputs: .github/workflows/ci.yml
Write the red marking tests
- depends: #elicit-socket-marks-allium
- verify: every new test fails on unmodified code for its intended reason
- inputs: bench/
Implement the three flags
- depends: #write-the-red-marking-tests, #stand-up-the-freebsd-lane
- verify: ubuntu lane greens parse, refusal, apply and IPv6 tests; FreeBSD lane greens cookie and dscp apply and fwmark refusal
- inputs: misc.cpp, misc.h, common.cpp, common.h, main.cpp
Implement the Windows qWAVE tier
- depends: #implement-the-three-flags, #stand-up-the-windows-lane
- verify: windows lane greens flow completion and the pktmon DSCP-byte assertion with re-point re-track
Document the surface
- depends: #implement-the-three-flags
- verify: help carries the three flags with defaults; README and README.zh-cn document them, permissions, WMM and the New-NetQosPolicy pointer
Wire the UCI options
- depends: #implement-the-three-flags
- verify: the package builds in the SDK lane and an init render appends the flags when set; cookie is absent
- inputs: software/packages/feed-main/net/udpspeeder-simd-snapshot/files/
Release v1.2.0
- depends: #implement-the-windows-qwave-tier, #document-the-surface, #author-the-obligations-manifest
- verify: tag at the bump commit, feed pin follows it, software --check green at the new pin
Close the loop
- depends: #release-v1-2-0, #wire-the-uci-options
- verify: attested operator
README rewrite: the front door for our own software
Status:; complete 2026-11-14
- Status: planned
- Persona: Diego (primary reader -- installs, configures, watches it run); Ingrid (reads it for packaging truth); Samira (holds its claims to evidence)
- Serves: every new visitor to the repository, and sdanfa's class of user who arrives with one feature in mind
- Scope: the
udpspeeder-simdcomponent's two READMEs and the marks guide, with new mermaid diagrams and an elaborated SIMD section; no code, no release
Why
The READMEs are still upstream's: their structure, their diagrams, their story. The software underneath stopped being upstream long ago -- the SIMD kernels, the DNS lease manager that follows a moving endpoint, the socket marks with their honor-or-refuse contract, four-host CI that reads the priority byte off the wire, the OpenWrt packages, the renamed binary. A visitor reading the front door meets wangyu-'s UDPspeeder with footnotes, not the software they would actually run. The Chinese README compounds it: a translation of the old English one, one version behind even that.
The rewrite keeps three things deliberately. Full, prominent credit to wangyu-/UDPspeeder -- this is a fork and its foundation is honest work, MIT carried forward. The two READMEs stay 1:1 aligned, English and Chinese carrying the same structure, section for section, so neither language is a second-class reader again. And the diagrams are mermaid in the markdown itself, so they render wherever the README does and version with the text that explains them.
What the new front door says
- What this is: a fork of UDPspeeder that became its own tunnel -- the one paragraph lineage with the credit link up front, not buried in a footer.
- Why it is fast: the SIMD story elaborated from OPTIMIZATION.md -- the vectorized FEC kernels, the per-CPU dispatch tiers (SSSE3, AVX2, NEON, and the PowerPC SPE path), what the dispatcher picks at runtime and the measured gain per tier -- with a mermaid flowchart of the dispatch.
- Why it is different: the endpoint that follows DNS, the socket marks, the platforms and binaries we actually ship.
- VPN over the tunnel is a key goal: an applied family with one backbone, the MTU ledger (path MTU x inner VPN -> safe inner MTU and the knob that sets it, every number verified by capturing real stacked packets) -- WireGuard at full MTU with mark coordination, OpenVPN TCP carried on UDP (the loss-rescue claim with its double-spend tension left live), the stranger scenarios (raw TCP, IPv6 inner, double stacking, the no-VPN case), and the anti-loop route exception generalized.
- The applied sections: tuning a lossy link (ratio table, live fifo levers, measure-your-own-link), the moving endpoint, what this is not (five honest lines), which binary for which CPU, and troubleshooting routed to its own guide.
- Quick start both ways: command line and OpenWrt UCI, every applied section ending in the two-door pattern (CLI block and UCI stanza side by side).
- New mermaid diagrams: the tunnel architecture with the marks drawn on the outer packets, the endpoint re-pointing when DNS moves, and the SIMD dispatch -- three blocks in the markdown, no image files.
- The evidence posture, in plain words: what we claim, we test; the wire proofs described as they run.
- Platform table, privileges table, the feed, the license story.
Writing charter
Four sources govern the prose and the ink, and every task's verify line enforces them. Practitioner Voice (Highsmith on martinfowler.com): sections open with claims, authority comes from consequence, scars are credibility, tensions are named and left live, compression respects the reader, a carry phrase closes. Tufte: data-ink maximized, tables as small multiples, graphics inside the prose flow, every number adjacent to its origin, empty cells stated as data. Diataxis: every section declares one quadrant and keeps its register; the README routes what it does not own; blur is the named failure. The Good Docs Project: status and engage sections present; an EN-zh terminology table keeps the two READMEs a translation of record. Personas describe readers inside this host's rooms only; the shipped documents never name them, and no methodology vocabulary appears in the artifacts.
Build sequence
Inventory the old READMEs against reality
- verify: every claim in the current READMEs classified as still-true, stale, or fork-unique; the stale list names what the rewrite must replace
- inputs: software/udpspeeder-simd/main/README.md, software/udpspeeder-simd/main/doc/README.zh-cn.md
Elaborate the SIMD kernels
- depends: #inventory-the-old-readmes-against-reality
- verify: the section names each kernel family, its vector width, the dispatch tier that selects it, and the measured gain, every number traceable to OPTIMIZATION.md or the bench lane
- inputs: software/udpspeeder-simd/main/OPTIMIZATION.md, software/udpspeeder-simd/main/bench/test_dispatch.cpp, software/udpspeeder-simd/main/bench/arch-matrix.awk
Write the VPN-over-tunnel family
- depends: #inventory-the-old-readmes-against-reality
- verify: the MTU ledger's every cell verified by capturing real stacked packets (WireGuard and OpenVPN UDP at 1500 and 1492 paths); the WireGuard recipe runs as written with both marks rules non-conflicting; the OpenVPN TCP transport's refusal is recorded as measured (clarified 2026-11-13: the intended family was OpenVPN over UDP; the plan's original wording asked for a TCP stacking, which the tunnel's nature refuses); the UDP section states the double-spend tension for inner TCP flows without resolving it; doc/vpn-over-the-tunnel.md supersedes the upstream openvpn guide with credit retained
- inputs: software/udpspeeder-simd/main/doc/udpspeeder_openvpn.md, software/udpspeeder-simd/main/bench/throughput.sh
Write the applied sections
- depends: #inventory-the-old-readmes-against-reality, #write-the-vpn-over-tunnel-family
- verify: each recipe runs as written; every applied section ends in the two-door pattern; tuning table, moving endpoint, what-this-is-not, which-binary sections present in both languages with no untraceable numbers
Write the OpenWrt section
- depends: #write-the-applied-sections
- verify: deployment from the release assets only (operator ruling 2026-11-13: no feed door, no upstream claims); the procd service pattern follows OpenWrt's documented interface; every asset name matches the v1.2.2 release; the section is in both languages and routes to doc/openwrt.md; no claim about the feed package or upstream inclusion
Write the troubleshooting guide
- depends: #write-the-applied-sections
- verify: every symptom traced to a real incident on record (ratio, MTU blackhole, dscp remarking downstream, admission-refused fatal); symptom-cause-fix form; routed to doc/ and linked from both READMEs
Write the English README
- depends: #elaborate-the-simd-kernels, #write-the-applied-sections, #write-the-openwrt-section
- verify: sections open with claims, each declares one quadrant and keeps its register, the three tensions named and left live, a reader can install, stack a VPN at correct MTU, and answer why-this-over-upstream without leaving the page; the two scars as stories were cut by operator ruling 2026-11-14 ("is crap. drop it") after being read on the page, and both READMEs carry no scars section
Author the mermaid diagrams
- depends: #inventory-the-old-readmes-against-reality
- verify: three mermaid blocks render on GitHub -- the architecture with marked outer packets, the DNS re-point, and the SIMD dispatch; no upstream images remain referenced
Write the Chinese README, one to one
- depends: #write-the-english-readme, #author-the-mermaid-diagrams
- verify: section-for-section alignment with the English README; the same mermaid blocks; a native reader confirms the register is documentation, not machine translation
Translate the socket-marks guide
- depends: #write-the-chinese-readme-one-to-one
- verify: the guide exists in Chinese with the quick-reference table intact and the promise paragraph carrying the same force
Hold every claim to evidence
- depends: #write-the-english-readme, #write-the-chinese-readme-one-to-one, #translate-the-socket-marks-guide, #write-the-troubleshooting-guide
- verify: each performance, platform and feature statement in every shipped document traces to a lane, a spec, or a document; the untraceable are removed rather than softened; no persona names or methodology vocabulary appear in any artifact; the EN-zh terminology table covers every term the two READMEs share
Ship the man page
- depends: #hold-every-claim-to-evidence
- verify: the man page is generated from the binary's own --help by a make target (so it cannot drift), renders under mdoc, installs with make install, the version bump to v1.3.0 and the regenerated page share one commit under a matching tag, and the release publishes from the tag
The applied sections
Working material for #write-the-applied-sections: four sections, each in
English and Chinese in 1:1 alignment, each configuration-bearing section
ending in the two-door pattern (the command line beside the OpenWrt UCI
stanza, citing the package's real option names). Recipes are verified live by
bench/recipes-check.sh (five claims, five passes); numbers carry their
origins.
Tuning a lossy link (EN)
Start from measurement, not folklore: run the tunnel with --report 10 and
read the loss it reports before choosing a ratio. The FEC arithmetic then
tells you what a ratio buys: with x:y, any y of the x+y packets in a
group can be lost and the group still decodes, at a bandwidth cost of
(x+y)/x.
| ratio | bandwidth | survives per-group loss | shape |
|---|---|---|---|
-f4:2 | 1.5x | up to 1/3 | small groups, quick flush |
-f20:10 | 1.5x | up to 1/3 | the shipped default, smoother under load |
-f1:1 | 2x | up to 1/2 | per-packet doubling, best for games |
-f1:3 | 4x | up to 3/4 | rescue mode for very bad links |
(Survivable fractions are Reed-Solomon arithmetic: y erasures of x+y are
always recoverable. Group shape effects are the options document's: group
size x, queue flush at --timeout, default 8 ms.)
Burst loss wants -i (spread each group over an interval), steady loss wants
a higher ratio, and latency-sensitive traffic wants small groups. The
tunnel's compute cost is not the constraint: with fec 20:10 the optimized
build runs 657-1082 Mbps end to end (OPTIMIZATION.md), so the link, not the
program, gives out first.
Everything above is live-tunable: the fifo takes fec, timeout and
queue-len from a running instance (verified: bench/recipes-check.sh,
section A), so tuning is a matter of watching --report and echoing a new
ratio.
The two doors:
# command line: watch, then change under load
udpspeeder-simd -c -l127.0.0.1:3333 -r<server>:4096 -f20:10 -k "passwd" \
--fifo /tmp/fifo --report 10
echo "fec 4:2" > /tmp/fifo # retune without restarting
# OpenWrt UCI (/etc/config/udpspeeder-simd)
config udpspeeder-simd 'tunnel1'
option enabled '1'
option server '0'
option local '127.0.0.1:3333'
option remote '<server>:4096'
option fec '4:2'
option timeout '8'
option report '10'
option fifo '/tmp/udpspeeder-fifo'
option key 'passwd'
调优一条高丢包链路 (zh)
从测量出发,而不是从传闻出发:先带 --report 10 跑起来,读它报告的丢包率,再选冗余比。FEC 的算术告诉你每个比值换来什么:以 x:y 为例,一组 x+y 个包里任意丢 y 个都能恢复,代价是带宽变为 (x+y)/x 倍。
| 冗余比 | 带宽 | 组内可承受丢包 | 形态 |
|---|---|---|---|
-f4:2 | 1.5 倍 | 至多 1/3 | 小组,快速成组 |
-f20:10 | 1.5 倍 | 至多 1/3 | 默认值,负载下更平滑 |
-f1:1 | 2 倍 | 至多 1/2 | 逐包加倍,适合游戏 |
-f1:3 | 4 倍 | 至多 3/4 | 极差链路的抢救模式 |
(可承受比例是 Reed-Solomon 的算术性质:x+y 中丢 y 个必可恢复。组形态的影响见选项说明:组大小 x,队列到 --timeout 便发送,默认 8 毫秒。)
突发丢包加 -i(把每组在一个时间窗内摊开发送);持续丢包提高冗余比;延迟敏感的流量用小组。计算力不是瓶颈:fec 20:10 下优化构建的端到端吞吐为 657-1082 Mbps(见 OPTIMIZATION.md),先到极限的是链路,不是程序。
以上参数全部可以在线调整:运行中的实例通过 fifo 接受 fec、timeout、queue-len(已验证:bench/recipes-check.sh A 节),调优就是看着 --report 再回显一个新比值。
两扇门:
# 命令行:先观察,再在运行中调整
udpspeeder-simd -c -l127.0.0.1:3333 -r<server>:4096 -f20:10 -k "passwd" \
--fifo /tmp/fifo --report 10
echo "fec 4:2" > /tmp/fifo # 不重启换参
# OpenWrt UCI(/etc/config/udpspeeder-simd)
config udpspeeder-simd 'tunnel1'
option enabled '1'
option server '0'
option local '127.0.0.1:3333'
option remote '<server>:4096'
option fec '4:2'
option timeout '8'
option report '10'
option fifo '/tmp/udpspeeder-fifo'
option key 'passwd'
The moving endpoint (EN)
Give the client a hostname and it follows the address: the lease manager
resolves -r names, refreshes before the record's TTL expires, and re-points
the tunnel when the answer changes, without a restart. A moving endpoint (a
residential IP that changes, a failover between two servers) stops reading as
an outage.
The verification is deliberately brutal (bench/recipes-check.sh, section
B): two servers on two addresses, traffic through the first, then the DNS
answer flips and the first server dies; the same client process re-points and
passes traffic again. The refresh discipline is the DNS lease manager's
specification (dns_lease_mgr.allium, held by the component's CI).
The two doors:
# command line: the hostname is the whole change
udpspeeder-simd -c -l127.0.0.1:3333 -rmytunnel.example.net:4096 \
-f20:10 -k "passwd"
# OpenWrt UCI: the remote takes the hostname the same way
config udpspeeder-simd 'tunnel1'
option enabled '1'
option server '0'
option local '127.0.0.1:3333'
option remote 'mytunnel.example.net:4096'
option fec '20:10'
option key 'passwd'
移动的对端 (zh)
给客户端一个主机名,它就会跟着地址走:租约管理器解析 -r 里的名字,在 TTL 到期前刷新,应答变化时把隧道指向新地址,全程无需重启。会动的对端(会变的家宽地址、两台服务器间的切换)从此不再表现为断线。
验证刻意做到苛刻(bench/recipes-check.sh B 节):两台服务器两个地址,流量先走第一台,然后 DNS 应答翻转、第一台被杀;同一个客户端进程重新指向并通过了流量。刷新纪律由 DNS 租约管理器的规格约束(dns_lease_mgr.allium,组件 CI 持有)。
两扇门:
# 命令行:改的就是一个主机名
udpspeeder-simd -c -l127.0.0.1:3333 -rmytunnel.example.net:4096 \
-f20:10 -k "passwd"
# OpenWrt UCI:remote 同样接受主机名
config udpspeeder-simd 'tunnel1'
option enabled '1'
option server '0'
option local '127.0.0.1:3333'
option remote 'mytunnel.example.net:4096'
option fec '20:10'
option key 'passwd'
What this is not (EN)
Five honest lines, so nobody arrives by mistake:
- Not a TCP tunnel: it carries UDP datagrams; TCP traffic rides a VPN stacked on top (the VPN-over-the-tunnel guide).
- Not magic against congestion: FEC repairs loss; it cannot create bandwidth, and congestion loss is better left to TCP's own backoff.
- Not strong encryption:
-kis an XOR obfuscation with random padding, not a cipher; confidentiality is the stacked VPN's job. - Not a VPN by itself: it forwards one UDP service; the VPN guide is where whole-network access comes from.
- Not a WAN optimizer: it is a lossy-link tool; on a clean link it only adds redundancy.
The two doors are the manual itself:
udpspeeder-simd -h # every option, from the binary
# OpenWrt: the package's config is the documented surface
# /etc/config/udpspeeder-simd (uci show udpspeeder-simd)
它不是什么 (zh)
五行实话,免得有人误入:
- 不是 TCP 隧道:它搬运 UDP 数据报;TCP 流量要靠叠在上面的 VPN(见 VPN over the tunnel 指南)。
- 不是拥塞的解药:FEC 修复丢包,不能凭空造带宽;拥塞丢包交给 TCP 自己的退避更合适。
- 不是强加密:
-k是带随机填充的异或混淆,不是密码学加密;保密性由叠加的 VPN 负责。 - 本身不是 VPN:它转发一个 UDP 服务;整网接入请看 VPN 指南。
- 不是广域网优化器:它是丢包链路的工具;干净的链路上它只增加冗余。
两扇门就是手册本身:
udpspeeder-simd -h # 每个选项,来自二进制本身
# OpenWrt:软件包的配置文件即文档化的接口
# /etc/config/udpspeeder-simd(uci show udpspeeder-simd)
Which binary for which machine (EN)
The release ships ten assets; the build matrix behind them is
bench/arch-map.tsv, the same table CI holds as a check. Pick by the target
CPU:
| asset | machine | example |
|---|---|---|
udpspeeder-simd.x86_64 | any x86_64 Linux, old or new | servers, desktops, Atom |
udpspeeder-simd.aarch64 | 64-bit ARM | most modern routers, SBCs |
udpspeeder-simd.armv7-neon | 32-bit ARM with NEON | cortex-a15-class targets |
udpspeeder-simd.armv7-scalar | 32-bit ARM without NEON | mvebu cortex-a9 targets |
udpspeeder-simd.mips | big-endian MIPS | ath79-class routers |
udpspeeder-simd.powerpc | PowerPC e500v2 | TL-WDR4900 class |
udpspeeder-simd.riscv64 | 64-bit RISC-V | sifiveu targets |
udpspeeder-simd.x86_64.exe | Windows x86_64 | |
udpspeeder-simd.aarch64.exe | Windows on ARM | |
udpspeeder-simd | macOS, both Intel and Apple silicon | one universal binary |
The x86_64 binary runs on CPUs as old as the first K8: the dispatcher probes before it uses SSSE3 and falls back to SSE2 and scalar (the SIMD section tells the SIGILL story behind that). On OpenWrt, the package resolves the right build through the feed.
The two doors:
# command line: download from the release, chmod, run
curl -LO https://github.com/connollydavid/UDPspeeder-simd/releases/download/v1.2.2/udpspeeder-simd.x86_64
chmod +x udpspeeder-simd.x86_64 && ./udpspeeder-simd.x86_64 -h
# OpenWrt: the feed package picks the arch itself
opkg update && opkg install udpspeeder-simd
哪台机器用哪个二进制 (zh)
发布共十件资产;它们背后的构建矩阵是 bench/arch-map.tsv,与 CI 检查用的是同一张表。按目标 CPU 选择:
| 资产 | 机器 | 例子 |
|---|---|---|
udpspeeder-simd.x86_64 | 任意 x86_64 Linux,新旧皆宜 | 服务器、桌面、Atom |
udpspeeder-simd.aarch64 | 64 位 ARM | 多数现代路由器、开发板 |
udpspeeder-simd.armv7-neon | 带 NEON 的 32 位 ARM | cortex-a15 级 |
udpspeeder-simd.armv7-scalar | 无 NEON 的 32 位 ARM | mvebu cortex-a9 级 |
udpspeeder-simd.mips | 大端 MIPS | ath79 级路由器 |
udpspeeder-simd.powerpc | PowerPC e500v2 | TL-WDR4900 一类 |
udpspeeder-simd.riscv64 | 64 位 RISC-V | sifiveu 目标 |
udpspeeder-simd.x86_64.exe | Windows x86_64 | |
udpspeeder-simd.aarch64.exe | Windows on ARM | |
udpspeeder-simd | macOS,Intel 与 Apple 芯片同件 | 单一通用二进制 |
x86_64 二进制在最早的 K8 上也能跑:调度器先探测再使用 SSSE3,不满足时退到 SSE2 与标量路径(SIMD 一节讲了这背后的 SIGILL 故事)。在 OpenWrt 上,软件包会通过 feed 自动解析正确的构建。
两扇门:
# 命令行:从发布页下载、赋权、运行
curl -LO https://github.com/connollydavid/UDPspeeder-simd/releases/download/v1.2.2/udpspeeder-simd.x86_64
chmod +x udpspeeder-simd.x86_64 && ./udpspeeder-simd.x86_64 -h
# OpenWrt:feed 软件包自己选架构
opkg update && opkg install udpspeeder-simd
The three mermaid blocks
Working material for #author-the-mermaid-diagrams. The blocks below are the
diagrams the two READMEs carry: the tunnel architecture with the marks drawn
on the outer packets, the endpoint re-point when DNS moves, and the SIMD
dispatch ladder. They are mermaid in the markdown, so they render wherever
the README renders and version with the prose that explains them. No upstream
image remains referenced after the rewrite (the inventory's stale digest,
item seven).
The tunnel, with the marks on the outer packets
The marks are host-local: they ride the tunnel's own outer packets and change how those are routed, filtered, or queued. The inner packet is untouched; the two ends need not agree on any mark.
flowchart LR
APP["application<br/>UDP traffic"] -->|"inner packet"| C["udpspeeder-simd<br/>client"]
C -->|"FEC group:<br/>20 original + 10 redundant"| P["outer packets<br/>cooked: crc32c + xor<br/>marked: fwmark / cookie / dscp"]
P -->|"lossy high-latency link<br/>any 10 of 30 survive: decode"| S["udpspeeder-simd<br/>server"]
S -->|"decoded inner packet"| T["the service<br/>127.0.0.1:7777"]
The endpoint re-point when DNS moves
The client's -r takes a hostname. The lease manager refreshes the record
before its TTL expires and re-points the tunnel when the address changes, so
a moving endpoint never reads as an outage.
sequenceDiagram
participant C as udpspeeder-simd client
participant D as DNS resolver
participant O as old endpoint 203.0.113.7
participant N as new endpoint 198.51.100.9
C->>D: resolve tunnel.example.net, before TTL expiry
D-->>C: 203.0.113.7, TTL 300
C->>O: outer packets
Note over D: the record changes
D-->>C: 198.51.100.9, TTL 300
C->>N: outer packets, same session
Note over C: the tunnel re-points without a restart
The SIMD dispatch
On x86 the kernel ladders resolve at startup by CPUID probe; on the feed targets the build decides. Every leaf below is a row CI holds as a check under a named QEMU CPU model.
flowchart TD
A["the FEC inner loop:<br/>GF multiply-accumulate"] --> Q{"x86_64 host"}
Q -->|"OS enables ZMM state"| AV5["avx512bw, 64 B"]
Q -->|"OS enables YMM state"| AV2["avx2, 32 B"]
Q -->|"CPUID leaf 1 ECX bit 9"| SS3["ssse3, 16 B, PSHUFB nibble lookup"]
Q -->|"SSE2 only"| S2["sse2, 16 B, repeated doubling"]
Q -->|"no vector unit"| SC["scalar"]
A --> B{"the build target"}
B -->|"ARM toolchain with NEON"| NE["neon, 16 B, TBL lookup"]
B -->|"PowerPC e500v2"| SPE["spe, 8 B, evxor assembly"]
B -->|"mips, riscv64, armv7 without NEON"| W["word-width xor and scalar multiply"]
Notes for the README assembly
- The blocks carry no upstream images and no image files; the rewrite deletes
every
/images/reference the inventory listed. - Ink discipline: each diagram names its actors and its claim, nothing more; the numbers live in the adjacent tables, not inside the boxes.
- The dispatch diagram's leaves are the arch-map rows verbatim, so the diagram and the CI check cannot drift apart silently.
The old READMEs, classified against reality
This is the inventory for the task #inventory-the-old-readmes-against-reality.
It walks every claim in README.md and doc/README.zh-cn.md at v1.2.2
(d1e1ee9) and classifies each as still-true (the rewrite carries the
substance, reworded), stale (the rewrite must replace it), or fork-unique
(fork-era material that is accurate and stays, integrated rather than
rewritten away). The stale digest at the end is the replacement worklist the
later tasks consume.
Reality it classifies against: the software is udpspeeder-simd v1.2.2, a fork
of wangyu-'s UDPspeeder with SIMD FEC kernels and per-CPU dispatch, a DNS lease
manager, socket marks (--fwmark, --cookie, --dscp) with an
honor-or-refuse contract, four-host CI that reads the priority byte off the
wire, an OpenWrt feed package, and ten release assets covering seven Linux
arches, both Windows worlds, and one universal macOS binary.
English README (README.md, 185 lines)
| Lines | Claim | Class | Note |
|---|---|---|---|
| 1 | Title: UDPspeeder | stale | The software's name is udpspeeder-simd; the fork lineage with credit belongs in the first screen |
| 3 | Tagline: a tunnel that improves a high-latency lossy link with FEC | still-true | The one-sentence essence carries |
| 5-6 | UDP alone; UDP-based VPN stacks any traffic; OpenVPN/L2TP/ShadowVPN confirmed | mixed | Mechanism still-true; the confirmed list is upstream-era. The fork's verified family (WireGuard, OpenVPN UDP, OpenVPN TCP) replaces it |
| 8, 12 | Architecture images udpspeeder.PNG, udpspeeder+openvpn3.PNG | stale | Upstream images, upstream story; three mermaid blocks replace them |
| 14 | Under 0.01% loss at 1.5x traffic; better TCP latency and single-thread speed | mixed | The loss figure is FEC arithmetic at -f20:10 (still-true as math); the efficacy presentation cites no fork measurement and must re-anchor to OPTIMIZATION.md, the bench lane, or stated arithmetic |
| 16 | Wiki link as the primary "more info" pointer | stale | The fork's doc/ owns the applied material; upstream wiki becomes credited further reading |
| 18 | 简体中文 link | still-true | The 1:1 pairing stays |
| 20-27 | Efficacy screenshots (ping, scp) | stale | 2018 measurements of upstream's binary; not evidence for this software |
| 29-32 | Platforms: Linux (Android, OpenWRT, RPi); Windows/macOS via a 7.5 MB VM image | stale | Ten assets on four hosts replace this; the VM suggestion is obsolete next to native .exe and universal mac binaries. Android and RPi are untested by the fork and must not be claimed |
| 34-52 | FEC mechanism, Reed-Solomon, textbook quotes, fec.PNG, rs.png, Wikipedia | mixed | Substance still-true (RS FEC is the mechanism); the textbook block quote and upstream images go, replaced by the fork's own telling plus the SIMD elaboration |
| 54-57 | Installing: download from upstream releases | stale | Releases are this fork's, v1.2.2, ten assets |
| 59-70 | Running example (server and client lines) | still-true | Correct shape, and the binary name is already the fork's |
| 72-77 | Note: -f20:10 meaning; -k XOR | still-true | |
| 79-81 | "Improves all traffic" section pointing at the upstream wiki OpenVPN guide | stale | doc/vpn-over-the-tunnel.md supersedes the upstream guide and the fork's imported copy doc/udpspeeder_openvpn.md, with credit retained |
| 85-139 | Full options block | mixed | Banner is stale (v1.0.6, git 3e248b414c, build date Aug 5 2018); the repository:/based on: lines are fork-unique; the three marks options are fork-unique; every other option line is still-true and matches the real binary. Regenerate the whole block from the v1.2.2 --help output |
| 140-148 | --fifo section and command examples | still-true | |
| 151-170 | Socket marks section | fork-unique | Accurate (plan/0002), links doc/socket-marks.md; stays, and the architecture diagram draws the marks on the outer packets |
| 172-175 | Wiki section | stale | Same as line 16 |
| 177-185 | Related repos: tinyfecVPN, udp2raw | still-true | Upstream-ecosystem pointers; keep with credit framing |
Chinese README (doc/README.zh-cn.md, 240 lines)
| Lines | Claim | Class | Note |
|---|---|---|---|
| 1-2 | Title UDPspeeder, banner image | stale | Same as the English title |
| 4 | Intro: essence, the 1.5x/0.01% arithmetic, comparison against kcptun/finalspeed/BBR | mixed | Essence and arithmetic still-true; the 2017 competitor comparison is stale positioning |
| 6 | Personal anecdote: months of use, Brawl Stars, Mobile Legends, first-person 我 | stale | Upstream author's voice and story; the rewrite speaks from this fork's evidence |
| 8 | v1/v2 version talk; link to README.zh-cn.v1.md | stale | Upstream lineage; the archive doc stays in the tree, out of the front door |
| 10-12 | Stacking diagram Capture2.PNG; confirmed VPNs incl. a censored $\*\*\*VPN$ | stale | Replaced by the mermaid architecture and the fork's verified family |
| 14-16 | English link; wiki link | mixed | Language pairing still-true; wiki pointer stale-as-primary |
| 18-24 | tinyfecVPN 提示 | still-true | Pointer carries |
| 27-30 | 效果 screenshots | stale | Upstream measurements |
| 33-38 | 原理简介: FEC, Reed-Solomon, fec.PNG | mixed | Substance still-true; image goes |
| 40-51 | 其他功能: obscuring, -i spreading, -j jitter, --report, loss/latency/jitter simulation, multiple clients and connections | still-true | All present in the binary; keep, reworded |
| 53-55 | 关键词 keyword block | stale | 2017-era search keywords |
| 59-67 | 环境要求: Linux hosts; prebuilt amd64/x86/arm/mips_be/mips_le; Windows/macOS VM image (with its root password); Android via terminal | stale | Old asset names, the VM image with its password, and untested Android claims all go; the ten-asset four-host table replaces |
| 69-72 | 安装: upstream releases | stale | Fork releases |
| 74-84 | 运行 example with --mode 0 | still-true | |
| 86-94 | 备注: -f20:10, option spacing rules, -k, mode 0 recommendation, game parameters via wiki | mixed | The first three still-true; the wiki-as-primary routing is stale |
| 96-102 | udp2raw 提示 | still-true | Pointer carries |
| 106-160 | 命令选项 block | mixed | Same verdict as the English block: stale banner, fork-unique marks lines (already in Chinese), still-true options; regenerate from v1.2.2 help |
| 161-215 | Per-option explanations (-f through --disable-obscure) | still-true | Accurate and better written than the English side; the rewrite's advanced section keeps this register in both languages |
| 216-222 | 推荐参数, 使用经验 wiki links | stale-as-primary | The tuning section owns this; the wiki links stay as credited further reading |
| 224-227 | 编译教程 routed to udp2raw's build guide | stale | The fork builds with make or CMake; its build story is its own |
| 229-233 | 套接字标记 section | fork-unique | Accurate Chinese summary of the marks; stays |
| 235-239 | wiki section | stale-as-primary |
The EN-zh divergence
The Chinese file carries strictly more upstream residue than the English one: the personal anecdote, the v1/v2 version talk, the keyword block, the VM image instructions with password, and the old architecture names all survive only on the Chinese side. That is the concrete content of "one version behind": the fork-era updates (binary rename, marks sections) landed on both, but nothing ever pruned the Chinese side's older strata. The 1:1 rewrite closes this by construction: one structure, two languages, same mermaid blocks.
The stale digest: what the rewrite must replace
- Identity. The name and title story on both files, replaced by the fork's own front door with the credit link up front.
- Platform and install truth. Upstream release URL, the VM image (and its root password), old arch names, Android and RPi claims. Replaced by the ten-asset four-host table, the privileges table, and the feed.
- Efficacy presentation. Upstream's 2018 screenshots and unanchored numbers. Replaced by claims traced to OPTIMIZATION.md, the bench lane, or stated FEC arithmetic.
- The VPN stacking story. Upstream's confirmed-VPN list and wiki guide pointer. Replaced by the fork's VPN-over-tunnel family with the MTU ledger.
- The options banner. The v1.0.6 block regenerated from the real v1.2.2 help output.
- Upstream's voice. The personal anecdote, v1/v2 version talk, keyword block, competitor comparison.
- Every upstream image reference. Three mermaid blocks replace them.
- The wiki as primary pointer. The fork's
doc/owns applied material; the upstream wiki remains as credited further reading.
What carries: the FEC/Reed-Solomon substance, the quick-start shape, all option
semantics and the per-option explanations, the fifo section, both marks
sections, the related-repo pointers, and the language pairing. What is already
ours: the marks options and sections, the renamed binary in examples, the
repository credit lines in the help block, and doc/socket-marks.md.
The OpenWrt section (README stub)
Working material for #write-the-openwrt-section: the lean section both
READMEs carry, routing to the full guide. Per the operator ruling of
2026-11-13 it documents deployment from the release assets only.
EN
Running on OpenWrt
The release binaries are built with the OpenWrt target toolchains and run on
a stock router: static, about 4.2 MB, no kernel modules, with a receive path
that falls back where the kernel lacks io_uring. Copy the asset for your
target (the which-binary table maps them), and the guide turns it into an
appliance: a procd service that starts at boot, restarts on exit, and reads
/etc/config/udpspeeder-simd, so every UCI stanza in this documentation
works verbatim; uci commit applies changes, logread shows the loss
report, and one line in /etc/sysupgrade.conf carries the binary across
firmware upgrades. The whole story, with the init script ready to paste:
doc/openwrt.md.
zh
在 OpenWrt 上运行
发布二进制由 OpenWrt 目标工具链构建,在原厂路由器上直接可用:静态链接,约 4.2 MB,无需内核模块;内核缺少 io_uring 时收包路径自动回退。按目标机型选好资产(见哪台机器用哪个二进制一节的对照表),再由指南把它变成一个设备级服务:procd 守护开机自启、退出即重启,并读取 /etc/config/udpspeeder-simd,因此本文档中所有 UCI 配置段均可原样使用;uci commit 即时生效,logread 查看丢包报告,/etc/sysupgrade.conf 加一行即可让二进制随固件升级保留。完整过程与可直接粘贴的 init 脚本见 doc/openwrt.md。
The SIMD kernels, elaborated
Working material for #elaborate-the-simd-kernels. This is the section the
new README absorbs under "why it is fast". Every number below carries its
origin: an OPTIMIZATION.md section or a bench-lane artifact. Vector widths
and dispatch rules are read from the code that implements them (lib/fec.cpp,
packet_cook.cpp, xor_spe.S) and from bench/arch-map.tsv, which CI holds
as a check rather than a report.
The three kernel families
The hot path has three families, and each one dispatches on its own:
| Family | What it computes | Where it runs |
|---|---|---|
| addmul1 | GF(2^8) multiply-accumulate, the inner loop of Reed-Solomon encode and decode | lib/fec.cpp |
| xor_tile | XOR of the repeating key and IV patterns over the packet (obscure plus encryption) | packet_cook.cpp |
| crc32c | The Castagnoli checksum over the packet body | crc32c.h, resolved by crc32c_resolve |
addmul1: the Reed-Solomon inner loop
The scalar original multiplies one byte at a time through a 64 KB lookup
table. The vector paths decompose each byte into low and high nibbles and use
a byte shuffle as a 16-entry parallel table lookup: PSHUFB on x86, TBL on
ARM, XOR the two partial products. Sixteen bytes per iteration, with a scalar
tail for the remainder. AVX2 widens the same scheme to 256-bit registers;
because VPSHUFB operates on two independent 128-bit lanes, the 16-byte
lookup table is broadcast into both (_mm256_broadcastsi128_si256), and an
SSE tail covers the 16 to 31 byte remainder.
The x86 dispatch is a three-phase CPUID probe resolved once in init_fec():
OSXSAVE plus XCR0 AVX state plus leaf 7 bit 5 before AVX2 is allowed, the
same OS-support discipline extended to AVX-512BW (which the probe declines
where the OS does not enable opmask and ZMM state). The tier ladder, from
lib/fec.cpp:
| Tier | Vector width | Selection | Measured at 1500 B |
|---|---|---|---|
| scalar | 1 B | no SIMD, the base | 1578.8 ns, 0.95 GB/s |
| sse2 | 16 B | CPUID leaf 1, SSE2, when SSSE3 is absent | 913.3 ns, 1.64 GB/s, 1.73x over scalar |
| ssse3 | 16 B | CPUID leaf 1 ECX bit 9 | 161.3 ns, 9.30 GB/s, 9.8x over scalar |
| avx2 | 32 B | three-phase probe | in the ssse3 to avx2 step of the 11.5x whole-path gain |
| avx512bw | 64 B | full OS-support probe | guarded; declined where the OS withholds the state |
| neon | 16 B | build-time, the ARM toolchain's FPU default | the a15 row of the arch map |
| scalar | 1 B | build-time, cores with no vector unit | the a9, mips, riscv64 rows |
The SSE2 tier is the one that makes the ladder safe rather than fast: it has
no byte shuffle, so it multiplies by repeated doubling in the field
(_mm_add_epi8(x, x) with a conditional reduction), no tables and no memory
traffic. It exists because x86_64 does not imply SSSE3 (OPTIMIZATION.md #16
tells the story: AMD K8 and K10, and the early 64-bit Intel parts, lack it,
and the first PSHUFB there was a SIGILL that killed the tunnel on its first
FEC batch; the crash was found under qemu64, the conservative baseline
model, which no developer machine or CI runner had ever matched).
Whole-path numbers, from the microbenchmark summary at 1500 B:
| Path | Before | After | Speedup |
|---|---|---|---|
| addmul1 | 665 ns | 58 ns | 11.5x |
| rs_encode k=10 n=15 | 34,000 ns | 3,100 ns | 11x |
| rs_decode k=10 n=15 | 36,000 ns | 4,500 ns | 8x |
xor_tile: the cook pipeline
Every packet is cooked: checksummed, obfuscated, and (with a key) encrypted,
all XOR-shaped work. The original walked byte at a time with data-dependent
branches (if (key[j] == 0) j = 0), which compilers cannot vectorize. The
vector path pre-expands the repeating key or IV pattern into a tile whose
length is the least common multiple of the pattern length and 16, computes
the key tile once at startup, builds the IV tile per packet on the stack
(at most 496 B), and XORs 16 bytes at a time.
| Tier | Vector width | Selection |
|---|---|---|
| word | one machine word (sizeof(unsigned long)) | the generic fallback, MIPS, RISC-V, ARMv7 without NEON |
| sse2 | 16 B | x86 baseline, compile-time |
| avx2 | 32 B | runtime probe with the OSXSAVE and XCR0 YMM check |
| neon | 16 B | build-time, the ARM toolchain default |
| spe | 8 B doubleword | PowerPC e500v2, a build guard (make SPE=1) |
The SPE tier is hand-written assembly (xor_spe.S) for the e500v2 core
(Freescale P1014, the TP-Link TL-WDR4900 among others), which has no AltiVec.
GCC 9 removed the SPE intrinsics, so the kernel follows the Linux kernel's
own pattern for SPE crypto (arch/powerpc/crypto/aes-spe-core.S): a 4x
unrolled evldd/evxor/evstdd main loop at 32 B per iteration, alignment
head and tail loops, and tile buffers padded so an unaligned offset cannot
straddle the end. SPE cannot help addmul1 (byte-level shuffle is absent) or
CRC32C (no hardware CRC on the e500v2), so on PowerPC the gains are the XOR
stage plus the allocator work below.
Measured:
| Path | Before | After | Speedup |
|---|---|---|---|
| XOR-encryption stage alone | 1,826 ns | 131 ns | 14x |
whole do_cook | 3,000 ns | 713 ns | 4.2x |
On PowerPC under
QEMU, do_cook at 1500 B stands at 4,090 ns with the SPE stage
(cook_xor_only 1,091 ns of it), and RS encode improved 1.5x there from the
decode-buffer preallocation alone.
crc32c: the checksum
The zlib CRC32 became CRC32C (Castagnoli), which has hardware support worth
taking: _mm_crc32_u64 under SSE4.2 on x86, __crc32cb under ARMv8. The
resolver probes once; without hardware support the software path is a
slicing-by-8 Castagnoli table, itself faster than the zlib CRC32 it replaced
(on PowerPC, 2,609 ns to 1,804 ns at 1500 B, a 1.4x gain from the switch
alone).
What the tiers choose at runtime, and who checks
On x86 the three ladders resolve at startup by CPUID probe. On the feed
targets the choice is made by the build: the compiler the OpenWrt toolchain
configures decides whether the NEON paths exist in the binary at all, and
bench/arch-map.tsv records, for every shipped architecture, the path each
dispatcher must land on when its binary runs under a named QEMU CPU model:
| Row | addmul1 | xor_tile | crc32c |
|---|---|---|---|
| x86_64 | any (pinned by the cpu-dispatch job against named models) | any | any |
| aarch64 | neon | neon | sw |
| armv7-neon (cortex-a15) | neon | neon | sw |
| armv7-scalar (cortex-a9) | scalar | word | sw |
| mips | scalar | word | sw |
| powerpc (e500v2) | scalar | spe | sw |
| riscv64 | scalar | word | sw |
bench/test_dispatch.cpp turns each row into a check: under
EXPECT_DISPATCH_HELD, an unnamed expectation fails the run, and the chosen
path must equal the named one. The cpu-dispatch job pins x86_64 down the same
way (qemu64 yields SSE2, Nehalem SSSE3, Haswell AVX2; AVX-512BW is
declined under qemu-user because the OS-support check is honest). The
two-row ARM pair is deliberate: the a15 row proves the vector paths are
reached, the a9 row proves they stay out of a build for a core with no NEON
unit, both built with the toolchains the feed actually uses.
The end-to-end claim
All of it composes into the tunnel numbers, measured end to end on CI runners (1400 B UDP, loopback). The ranges are CI host variance; each current-to-baseline pair is measured on the same host within one run. FEC overhead now costs about 30% of throughput, where the baseline paid about 41%:
| Config | Baseline | Current | Improvement |
|---|---|---|---|
| no-fec | 618-861 Mbps | 942-1517 Mbps | +48-76% |
| fec 20:10 | 364-509 Mbps | 657-1082 Mbps | +81-113% |
Notes for the README assembly
- The SIGILL story (OPTIMIZATION.md #16) is the scar to tell: the multiply was correct on every machine that had SSSE3, and choosing it on a CPU without it killed the tunnel. It is also why the dispatch is probed and held rather than assumed, which the arch-map table shows.
- The dispatch mermaid block draws the addmul1 ladder with the OS-support gates, and the arch-map rows as the leaf labels.
- Numbers to keep adjacent to their origins in the README tables: the 1500 B microbenchmarks and the end-to-end ranges, each cited to OPTIMIZATION.md; the arch-map rows cited to the bench lane.
- The fork never claims the unmeasured: Android and Raspberry Pi appear nowhere in the arch map, so they appear nowhere in the platform table.
v1.3.1: a release that matches the front door, and the feed MR that follows
Status:; planned; active goal since 2026-11-14
- Status: planned
- Persona: Diego (installs the release binary and waits on the feed package); Ingrid (holds the version, the mirror hash and the notices to packaging truth); Samira (holds every pin and receipt to its evidence)
- Serves: everyone who reads the release page instead of the repository tip, and the sdanfa thread on openwrt/packages whose package request is answered by the current release
- Scope: a patch release of the
udpspeeder-simdcomponent (version bump, man regeneration, tag, published assets), the host re-pin and release receipt, the feed MR's version and hash, and the operator reply that follows the MR update; no behavioural code change
Why
The v1.3.0 tag built its assets at 3aee5a9, and the documentation that
matter moved past the tag afterwards: the writing-whip pass and the
six-persona readthrough rewrote both READMEs, the guides, the glossary and
the man page after the release page was minted. A visitor who arrives at the
releases page today reads the pre-review front door while the repository tip
carries the reviewed one. A patch release closes that gap, and a version bump
is the only honest carrier for docs this prominent.
Two smaller truths travel with it. The READMEs' download example verifies a
literal sha256 recorded for the v1.3.0 asset while downloading through the
latest URL, so the example would contradict itself the moment v1.3.1
publishes; the example steadies to a form that cannot drift. And the feed MR
(openwrt/packages PR 29901, the package request from sdanfa's thread) still
pins 1.0.0: DNS lease following, socket marks, the man page and the whole
reviewed documentation arrive only when the MR moves to 1.3.1 with its
mirror hash recomputed by the recorded dl_tar_pack method. The operator's
reply in that thread waits until that update lands, per the ruling.
Build sequence
Bump and regen
- verify:
make -C software/udpspeeder-simd/main -s man >/dev/null 2>&1 && ./software/udpspeeder-simd/main/udpspeeder-simd -h 2>&1 | grep -q 'v1\.3\.2' && grep -q 'v1\.3\.2' software/udpspeeder-simd/main/doc/udpspeeder-simd.1 - inputs: software/udpspeeder-simd/main/main.cpp, software/udpspeeder-simd/main/doc/udpspeeder-simd.1, software/udpspeeder-simd/main/README.md, software/udpspeeder-simd/main/doc/README.zh-cn.md
Bump PROGRAM_VERSION to v1.3.1, regenerate the man page through the
recorded regen = make man so bump and derived page share one commit, and
replace the literal-checksum download example in both README twins with a
form that verifies without pinning a per-release hash.
Tag and publish
- depends: #bump-and-regen
- verify:
gh release view v1.3.1 --repo connollydavid/UDPspeeder-simd --json assets --jq '.assets | length' | grep -qx 10
Annotated tag at the bump commit (resolved through rev-parse 'v1.3.1^{}'),
pushed; the tag-triggered workflow builds the ten assets. The tag is never
deleted or restored afterwards: assets are immutable.
Re-pin the host
- depends: #tag-and-publish
- verify:
.host-tools/bin/host-lifecycle software --check . - inputs: .host-software
Record the new pin in .host-software, push the host, and let the release
ledger carry the migrated skip already cited to call/0006.
Carry the feed MR
- depends: #tag-and-publish
- verify:
bash tools/mirror-hash.sh https://github.com/connollydavid/UDPspeeder-simd.git v1.3.2 | grep -qx "$(sed -n 's/^PKG_MIRROR_HASH:=\([0-9a-f]*\)$/\1/p' software/packages/udpspeeder-simd/net/udpspeeder-simd/Makefile)" - inputs: software/packages/udpspeeder-simd/net/udpspeeder-simd/Makefile
Materialize the udpspeeder-simd branch as a recorded worktree line, bump
PKG_VERSION to 1.3.1, recompute PKG_MIRROR_HASH with the dl_tar_pack
method (git archive, sorted tar with uid/gid/mode normalization and the
commit-time mtime, zstd ultra-20) behind a small tools/mirror-hash.sh so
the check re-runs, push the branch, and let the PR update itself.
Harden the stack
- depends: #tag-and-publish
- verify:
gh release view v1.3.2 --repo connollydavid/UDPspeeder-simd --json assets --jq '.assets | length' | grep -qx 10 && gh run view "$(gh run list --repo connollydavid/UDPspeeder-simd --event push --branch main --workflow ci.yml --limit 1 --json databaseId --jq '.[0].databaseId')" --repo connollydavid/UDPspeeder-simd --json conclusion --jq .conclusion | grep -qx success
The feed's hardening check failed the 1.3.1 install on both release lines: xor_spe.S declared .note.GNU-stack inside its guard, so on every other target the file assembled to an empty object and the older SDK linkers marked the stack executable for it. The note moves outside the guard, every statically built release binary is asserted non-exec in CI, and v1.3.2 carries the fix with the man regeneration it obliges.
Advance the feed branches
- depends: #carry-the-feed-mr
- verify:
grep -qx 'PKG_VERSION:=1.3.2' software/packages/feed-main/net/udpspeeder-simd-snapshot/Makefile software/packages/feed-24.10/net/udpspeeder-simd-snapshot/Makefile software/packages/feed-25.12/net/udpspeeder-simd-snapshot/Makefile && grep -qx 'PKG_MIRROR_HASH:=ff5524856dea96261cb6f4e6542dfde0bed82feca95ffb21067264f897d72560' software/packages/feed-main/net/udpspeeder-simd-snapshot/Makefile software/packages/feed-24.10/net/udpspeeder-simd-snapshot/Makefile software/packages/feed-25.12/net/udpspeeder-simd-snapshot/Makefile - inputs: software/packages/feed-main/net/udpspeeder-simd-snapshot/Makefile, software/packages/feed-24.10/net/udpspeeder-simd-snapshot/Makefile, software/packages/feed-25.12/net/udpspeeder-simd-snapshot/Makefile
The published feed is the delivery channel until the MR merges; its three release-line branches each carry the snapshot package at 1.1.0. Each branch takes its own version-bump commit with the recomputed mirror hash -- separate branches, separate commits -- and feed-main's fwmark-and-dscp UCI wiring is carried to the two release lines so 1.3.1 ships there with the options its init script already maps. The recipe pins follow, then a dispatch rebuilds the published feed.
The operator reply in the 29901 thread
- depends: #carry-the-feed-mr
- verify: attested operator
The draft is ready; it is posted only after the MR update lands, per the operator's ruling.
Software: where
The action this project produces. Each component is a bare object store with worktrees, not committed into this repo; the recipe below is the reproducibility anchor. Materialize the worktrees locally with:
host-lifecycle software --materialize .
host-lint
- url: https://github.com/connollydavid/host-lint.git
- pin:
db4a0d2026596ac21c3e089bf11d3738fb2d3b78 - worktrees: none (single canonical line)
udpspeeder-simd
- url: https://github.com/connollydavid/UDPspeeder-simd.git
- pin:
dd6ae0f95b28c4804f0c68f1fc169d819a79dd39 - worktrees: none (single canonical line)
packages
- url: https://github.com/connollydavid/packages.git
- pin:
c7ffd9a4a121e407a01450d83c16ae3571a17f21 - worktrees: udpspeeder-update-20260731 @ d9ef24250436, feed-25.12 @ b4ecd8abfb29, feed-24.10 @ 75d13e3e419b, feed-main @ 2a23a750dc42, flashprog @ 9f49c8217164, udpspeeder-simd @ 091768ab4d35, ci-flashprog @ d79c08094dfa
openwrt
- url: https://github.com/openwrt/openwrt.git
- pin:
62e7565f0e1e88e5fc8d038f09cb38ffd583bbed - worktrees: none (single canonical line)
Govern UDPspeeder-simd under the agentic-host methodology
- Status: accepted
- Scope: udpspeeder-simd
- Date: 2026-07-02
Context and Problem Statement
UDPspeeder-simd is a pre-existing C++ project (a Forward Error Correction UDP tunnel, forked from UDPspeeder) developed on a bare commit history. The reasoning behind its choices lives only in commit messages and is lost across sessions, with no durable record of decisions or specs.
Decision
Govern development of UDPspeeder-simd under the agentic-host methodology, adopted
from the host-template repository at revision 565410a (recorded in .host).
- The host repository (
agentic-UDPspeeder-simd) holds the thought: plans (plan/), decisions (call/), personas (cast/), and the operating manual (CLAUDE.md). - The software itself stays separate as the Where room, a bare store with a
worktree under
software/udpspeeder-simd/branch_libev/, recorded in.host-softwareand pinned to itsbranch_libevhead. The host never adopts a software repository in place. - The methodology rules live in the spine (
CLAUDE.mdplusSTRUCTURE.md), inherited copy-at-version from the template; they are not re-litigated here. A later change to them arrives byhost-lifecycle upgradeagainst the template'sUPGRADING.mdledger.
Consequences
- Good: decisions, plans, and specs gain a durable, citable home; the software pin is a real audit anchor; tooling upgrades are mechanical and token-free.
- Neutral: this is one of two numbered registers (milestones and decisions), kept apart by home. The software keeps its own MIT license; this governance shell is released into the public domain (Unlicense).
Pin the verification tools to current releases, not the template gitlinks
- Status: accepted
- Scope: udpspeeder-simd
- Date: 2026-07-02
Context and Problem Statement
The adopt guidance says to wire each tools/ submodule "to the commit the
template references at this revision." The template at 565410a records these
gitlink SHAs in its .gitmodules: host-lint 2ef5399 (v0.2.0), host-lifecycle
2a24deb (v0.15.1), allium 82da292, specula 38e9d6e. Those gitlinks are stale:
host-lint v0.2.0 predates the --docs engine, and host-lifecycle v0.15.1 predates
book, prose, software --install-hooks, and reconcile, which the
methodology's own workflows call. The template's prose.yml pins host-lifecycle at
46d481cd (a far newer revision than its gitlink), confirming the gitlinks lag the
working set.
Decision
Pin the tools/ submodules to current, working releases instead of the stale
gitlinks, so the methodology's CI lanes and the commit gate actually run:
tools/host-lintat78804cd(v0.12.1)tools/host-lifecycleat486add7(v0.35.1)tools/alliumat493a2de(v3.6.0)tools/speculaatfa12367
Consequences
- Good: the commit gate (
host-lint --stdin), the prose lane (host-lifecycle prose), the site publisher (host-lifecycle book), and the embed hook installer all run against tool versions that actually implement them. - Neutral: the submodules drift ahead of the template's recorded gitlinks. A later
template bump that refreshes its gitlinks reconciles this; until then the pins
live here in
.gitmodules, the source of truth for this host.
host-lint is a consumed tool, not reproduced by this host
- Status: accepted
- Scope: host-lint
- Date: 2026-07-02
Context and Problem Statement
host-lint is registered in .host-software so host-lifecycle software --install-hooks can install its pre-commit hook and built binary as this host's
commit gate. The software check requires a component that records an artifact
hash to also record a toolchain pin, so the artifact is reproducibly verifiable.
This host does not build host-lint reproducibly. It pins an upstream release, then
builds the binary locally so the commit gate can install it. No reproducible build
of that binary is claimed here.
Decision
Carry repro-exempt = call/0002 on the host-lint component and record no build
or toolchain recipe. The pinned source SHA (in .host-software) plus the recorded
artifact hash (a local-build anchor that attests the installed binary came from that
source) are the interim provenance. host-lint's own reproducibility is the upstream
maintainer's concern, attested by its released tags.
Consequences
- Good: the commit gate installs and runs; the cheap
software --checkpasses without this host claiming a reproducible build it does not perform. - Neutral:
host-lifecycle software --verify-buildreports host-lint as exempt and skips the rebuild comparison. Retire this exemption only if this host begins to build host-lint itself, which is not the case for a consumer.
No Claude co-author trailers on packages commits
- Status: accepted
- Scope: packages
- Date: 2026-07-03
Context and Problem Statement
The packages component is a fork of the OpenWrt packages feed
(openwrt/packages, GPL-2.0). Work done here may be offered back to that
upstream, whose commit history carries no AI-assistant co-author trailers and
whose authorship attribution stays clean for a community feed. This host's
default agent behaviour appends a Co-Authored-By: Claude ... trailer to commit
messages. That trailer is unwanted on any commit in the packages worktree.
Decision
Every commit created in the packages worktree (software/packages/<branch>/)
omits the Co-Authored-By: Claude ... trailer. An agent committing under
software/packages/ suppresses the trailer its default behaviour would add. The
prohibition is scoped to the packages component; the operator confirmed the scope
is packages only, so commits in this host repository keep the trailer as before.
Consequences
- Good: packages commits stay upstream-clean, so a change offered to
openwrt/packagesneeds no trailer scrubbing. - Neutral: the rule is a commit-message convention rather than a hook the host enforces, because the packages worktree is a separate repository with its own hooks. An agent honours it by reading this decision and the CLAUDE.md project-specifics note that points here.
- Follow-up: if upstream provenance later needs a DCO sign-off or another trailer policy, record it as a sibling decision under the same scope.
The udpspeeder-simd package coexists with udpspeeder and links dynamically
- Status: accepted
- Scope: packages
- Date: 2026-07-03
Context and Problem Statement
The issue at https://github.com/openwrt/packages/issues/28562 asks for the
performance-optimised UDPspeeder on low-end OpenWrt devices. The feed already
carries net/udpspeeder (the upstream UDPspeeder). A udpspeeder-simd package has
to avoid clashing with that package, and it has to choose how the binary links.
The operator first asked for a static build.
Decision
Ship a distinct package udpspeeder-simd with distinct paths
(/usr/bin/udpspeeder-simd, /etc/config/udpspeeder-simd,
/etc/init.d/udpspeeder-simd), so it installs alongside udpspeeder with no file
clash and no CONFLICTS.
Link the binary dynamically, with DEPENDS on the shared libraries it needs (the
udpspeeder package depends on libstdcpp, librt, and libatomic). Do not
build statically. A static C++ binary is larger on flash, which works against the
low-end devices the issue targets, and static linking runs against OpenWrt's
shared-library model. The operator settled this: no static builds for OpenWrt.
Consequences
- Good: the package matches OpenWrt's conventions and the sibling
udpspeederpackage, holds the flash footprint down, and reviews cleanly. - Good: both packages install together, so a user can compare them.
- Neutral: the exact
DEPENDSset is confirmed when the package first builds against the SDK.
Cross-build adjustments for udpspeeder-simd live in the fork
- Status: accepted
- Scope: udpspeeder-simd
- Date: 2026-07-03
Context and Problem Statement
The OpenWrt package builds udpspeeder-simd from the fork's source. Any change the
cross build needs (for example gating the io_uring path on a toolchain that lacks
the syscall numbers, or a clean cross entry point) can live either in the fork's
own makefile or as patches applied from the feed's package Makefile. The existing
udpspeeder package patches upstream's makefile from the feed with sed.
Decision
Make the build adjustments in the fork's makefile, then update the
.host-software pin, rather than carry feed-side patches. connollydavid owns the
fork, so a fix there is upstreamable and keeps the feed Makefile thin. The fork's
cross target already links dynamically, so the adjustments are expected to be
small.
Consequences
- Good: the feed Makefile stays close to a stock build, which reviews more easily.
- Good: the fix benefits anyone who builds the fork, not only the OpenWrt package.
- Neutral: each fork build change is a fork commit (with the normal sign-off and co-author trailer) followed by a re-pin, per the software discipline.
udpspeeder-simd release binaries are not yet reproducible
- Status: accepted
- Scope: udpspeeder-simd
- Date: 2026-08-05
Context and Problem Statement
On 2026-08-03 this project began publishing binaries. The v1.0.1 and v1.0.2
releases each carry five static executables, one per architecture, and a
tooling-sde-10.13.1 release mirrors a third-party emulator.
The methodology is explicit that this brings an obligation: a component shipping
static or self-contained release binaries must be able to reproduce them offline
from pinned inputs, and must record which line ships (deploy) together with the
artifact's expected hash (artifact = <path> <sha256>). The udpspeeder-simd
stanza in .host-software records none of that. It carries a source pin and
nothing else, so the gate has no build to check and no hash to compare.
We cannot honestly record an artifact today. The binaries were built by GitHub
Actions on ubuntu-latest using whatever g++ that image carried on the day,
which is not a pinned toolchain, and nothing in the build fixes timestamps, build
paths or -frecord-gcc-switches output. A second run on a later image would very
likely differ. Recording a hash for a build that cannot be reproduced would state
a guarantee we have not established, which is the fault this project spent the
week removing from its verification lanes rather than one to introduce here.
Considered Options
- Record
build,toolchain,artifactanddeploynow, and accept that--verify-buildfails until the build is made deterministic. - Record a
repro-waiverciting this decision, and state the route out. - Stop publishing binaries until the build is reproducible.
Decision
Record repro-waiver = call/0006 on the udpspeeder-simd stanza.
The escape clause fits this component exactly. udpspeeder-simd is pre-existing
software brought under the methodology rather than initiated by it, so the
reproducibility obligation is one it converges on rather than one it was born
with. The waiver is the honest record of that, and it keeps software --check
able to distinguish "no claim made" from "claim made and unmet".
Publishing continues. The interim provenance is not nothing:
- Every release binary is built by a workflow run in a public repository, from a tagged commit, and the run that produced it is linkable.
- The four cross toolchains are now hash-pinned in
bench/arch-map.tsv, and the download step fails on a mismatch, so the cross binaries are built by a compiler we have named rather than whatever a URL returned. - The mirrored emulator is pinned by sha256 in
bench/sde.lockand carries a detached Intel signature, verified before the hash was recorded.
Consequences
The gate stops being silent about this component. software --check requires the
citation to resolve, and --verify-build warns and skips rather than reporting a
reproducibility it never tested.
What remains owed, and what retires this waiver: a pinned toolchain for the
native x86_64 build, so every line has a named compiler rather than the runner's
default; a deterministic build, which for this makefile means at least
SOURCE_DATE_EPOCH, -ffile-prefix-map and a fixed link order; and then
build, toolchain, artifact and deploy recorded per line, with
--verify-build green. At that point this decision is superseded rather than
deleted, and the waiver comes off the stanza.
The tooling-sde-10.13.1 release is outside all of this. It republishes Intel's
tarball byte for byte and builds nothing, so there is no artifact of ours to
reproduce; its provenance is the recorded sha256 and Intel's own signature.
The tools this host runs are pinned and hash-verified
- Status: accepted
- Scope: agentic-UDPspeeder-simd
- Date: 2026-08-10
Context and Problem Statement
The methodology pins the software a host builds. A component records a source
pin, a build recipe, an artifact hash, and may record a deps-bundle so the
build reproduces offline from inputs fixed in advance rather than from whatever a
network fetch returns that day.
It says nothing about the tools the host itself runs. Those were reached
through whatever this machine happened to carry. On 2026-08-10 that meant node
and allium from ~/.local, java from /usr/sbin, and tla2tools.jar from a
home share. Nothing recorded which versions those were, and nothing would have
noticed had they drifted.
The failure this invites is the one the OpenWrt work already taught. A package build that fetches its dependencies at build time is not reproducible, however carefully its source is pinned, because the fetch is the unpinned input. The same holds one level up: a gate is only as trustworthy as the binary that runs it, and an unpinned binary makes the gate's verdict a property of the machine rather than of the change under it.
Two concrete symptoms had already appeared. A generated pre-push hook carried
$HOME/.local/bin/node, so it worked here and nowhere else. And a stale
target/release/host-lint sat six minor versions behind the binary on PATH,
which turned a green suite red and cost an hour before the cause was found.
Decision
Every tool this host runs installs to a project-local path, at a version and a sha256 recorded in the repository.
.env names each tool's version and its in-tree path.
tools/install-tools.sh fetches each one into .host-tools/ and verifies its
sha256 before unpacking it, refusing on a mismatch. .host-tools/ is
gitignored: the recipe is committed, the binaries are not. Scripts read .env
rather than probing PATH, so a hook or a lane names the tool it means.
Where a publisher ships its own checksum file, the script verifies against that
rather than a hash we copied: node against the published SHASUMS256.txt, the
JDK against the Adoptium API's checksum. Where none exists, the recorded hash is
the one this project pinned, and a change to it is a visible diff.
Two mechanisms exist, and each tool uses exactly one. host-lint is a Where-room
component: .host-software already carries its pin, its artifact sha256, and the
hooks it installs, and software --install-hooks verifies the binary against
that hash. It is not repeated in .env, because a hash recorded twice is a hash
that can disagree with itself. Everything else, node, the JDK, tla2tools.jar,
host-lifecycle and allium, is pinned in .env and fetched by the script.
Consequences
A fresh clone gets the same tool versions as this one, and a drifted download fails loudly at the point of installation rather than quietly at the point of use.
The cost is that a tool upgrade is now a commit: the version and the hash both
move in .env, and that is the intent.
Two limits are worth stating plainly. The install verifies provenance, not
behaviour, so a tool that is authentic and wrong still passes. And .host-tools/
holds around 550 MB, mostly the JDK, which is a real cost on a machine that
already carries one.
This decision is scoped to this host. The general form, a pinned and
hash-verified tool set recorded in .host-software and checked by
software --verify-setup, is a change to the shared methodology and belongs
upstream in the template, proposed there rather than settled here.
Notes
allium is pinned to 3.5.0 rather than the template's 3.4.2. Neither version
installs from crates.io without --locked: allium-cli resolves a newer
allium-parser whose analyze_with_cross_module takes more arguments than the
call site supplies. 3.5.0 is the version tools/allium carries.
udpspeeder-simd versioning and releases
- Status: accepted
- Scope: udpspeeder-simd
- Date: 2026-08-10
Context and Problem Statement
The fork has released v1.0.0 through v1.0.6 with no recorded versioning policy.
Every bump so far has been a patch (a fix layered on the same feature surface), cut
by tagging the fork and letting CI build the binaries. The milestone currently
planned (plan/0001) is the first feature addition since the fork diverged, which
makes it the first minor bump. The room has no decision that states what a minor
bump means, what the tag carries, or how the release is recorded, so the v1.1.0
release would otherwise be cut the way the v1.0.x line was: by habit, with the
reasoning living only in the tag.
call/0006 governs reproducibility (the binaries are not yet byte-reproducible, and
the stanza carries a waiver). It does not govern versioning or cadence.
Decision
The fork follows semantic versioning on its tags, with the release process the v1.0.x line already established:
- A minor bump (from the
vX.Ypatch line tovX.<Y+1>.0) carries a user-visible feature; a patch bump carries a fix. The first minor bump isv1.1.0, cut for the DNS lease manager feature inplan/0001. - The tag is the release, per the spine rule: a version bump MUST be accompanied
by a matching annotated tag
vX.Y.Zat the release commit, pushed alongside it. The tag-triggered CI job builds the artifacts from it. - The banner
PROGRAM_VERSIONinmain.cppmust equal the tag; the fork CI enforces the match on tag pushes. - The host records each release by re-pinning the
.host-softwareudpspeeder-simdstanza to the tagged commit and recording thereleasephase receipt for the component.
Consequences
- Good: a future release is cut the same way, with the meaning of the bump decided before the tag, not after; the v1.1.0 bump has a citable decision behind it.
- Good: the release receipt ledger (currently a stale
skipfor this component) gains a realdoneentry onceplan/0001ships. - Neutral: the OpenWrt feed package bump is a separate milestone, and the fork release is merely its prerequisite.
- Follow-up:
call/0006still governs reproducibility; when the build becomes deterministic, that waiver is retired and this decision's release-mechanics half stays in force.
The DNS lease manager ships as a C++-compatible single header
- Status: accepted
- Scope: udpspeeder-simd
- Date: 2026-08-10
Context and Problem Statement
The DNS lease manager for plan/0001 was specified as a strict C11 single-header
library: allocation-free, mem*-only string handling, no OS resolver APIs, no
threads, no recursion, no floating point, no unaligned access, no global mutable
state, no stdio in the protocol path, all functions static inline.
The fork builds C++-only: the flat makefile compiles every translation unit with
g++ -std=c++11, there is no C compiler in the build, and adding one (a .c
translation unit, a C compiler target, cross-compiler coverage for every OpenWrt
target) would be a build-system change purely to satisfy a language dialect. A C11
header's negative constraints are not C-specific; they are properties of how the
library must behave, and C++ can hold them all.
Decision
Write the DNS lease manager as a single header compiled by the existing C++ build,
preserving every negative constraint from the C11 specification unchanged: no
dynamic allocation, memcpy/memmove/memcmp/memset only, no getaddrinfo or
any OS resolver API, no threads/mutexes/atomics/signals, no recursion or
longjmp/setjmp, no floating-point math, no unaligned memory access or struct
casting for network parsing (manual byte shifting), no global mutable state (all
state in the caller-provided dns_lease_ctx), and no stdio in the protocol path
(resolv.conf discovery uses open/read/close; logging is a caller-supplied
callback). All functions remain static inline.
The only change is the dialect: the header is valid C++11 so it compiles under the
fork's existing -std=c++11 with zero build-system change.
Consequences
- Good: the fork's build and its cross-compiler matrix are untouched; the header compiles on every target the fork already builds.
- Good: the constraints the spec was really about (no allocation, no OS resolver, parser bounds safety, no ambient state) are preserved and enforced by the same review and test gate a C11 header would face.
- Neutral: the header is not valid C compilation, so it cannot be reused by a C consumer without a translation; the project is C++-only, so no such consumer exists today.
- Follow-up: if upstream or a future consumer needs a C11 build, the header is already written to C11-compatible idioms where C++ and C differ, so the remaining work is a dialect pass, not a rewrite.
The exec-bit audit over-fires on the OpenWrt install idiom
- Status: accepted
- Scope: packages, openwrt
- Note: superseded by call/0011 on 2026-11-07 and retracted the same day; see the MEMORY.md correction. The apparent fix at v0.63.0 was this host's own staged index state, not a change in the audit.
- Date: 2026-11-07
Context and Problem Statement
The template upgrade applied on 2026-11-07 (through ledger entry
PIN-two-surfaces-two-claims)
brought this host to the toolchain where software --check audits invoked
entry points for the executable bit. On the first full run after
software --materialize (a fresh checkout; nothing hand-modified), the audit
reported 514 HAZARDs across two foreign source pins: packages (the fork of
the OpenWrt packages feed, master mirroring upstream) and openwrt (the
buildroot, consumed upstream).
Every finding is the same shape: a file invoked as ./files/<name> inside a
package Makefile while recorded 100644. In the OpenWrt feed those invocations
live inside install macros, chiefly $(INSTALL_BIN), which copies the file
into the staging directory and applies the executable mode at copy time. The
source mode is the feed's own deliberate layout; the sources are never
executed in place, so the "exit 126 in a fresh clone" scenario the audit names
cannot arise from this idiom. One further finding of the same audit was real
and was fixed the ordinary way: bench/dns-live-test.sh in udpspeeder-simd
documented its own ./ invocation in a usage comment while recorded 100644
(mode committed in the component at bce0f3c, re-pinned in the same session).
The audit's printed remedy (staging git update-index --chmod=+x per path)
cannot be committed for these two components without diverging the fork from
the upstream feed, and for openwrt there is no fork to commit to.
Decision
- The 514 findings over
packagesandopenwrtare a confirmed over-fire of the shared audit, reported upstream as host-lifecycle issue 45 with the fresh-checkout context and the install-macro mechanism. The project that finds an over-fire proposes it to the shared tool; it does not edit the corpus to satisfy the gate. - Interim, until the tool learns the idiom, the audit's own printed remedy is
applied verbatim on this machine: the staged chmods live in the worktree
indexes of the two foreign pins, keep their HEADs at the recorded pins, and
commit nothing. The remedy is local state:
software --materialize(and thereforebootstrap) resets it, so a fresh setup must re-apply it. The remedy commands are exactly whatsoftware --checkprints per finding; the gate re-derives its own instruction list on every run. - The one genuine finding in this host's own software was fixed in the component and re-pinned; it is not part of the interim state.
Consequences
software --checkreads green at the declared toolchain (host-lifecycle v0.50.0, pinned in.env), and the verify receipt re-verifies.- The green reading depends on interim local state that a re-materialize resets; a future gate run that re-prints the corpus is re-applying the staged remedy, not discovering new findings. This entry is the record that distinguishes the two.
- When host-lifecycle ships a fix (skipping install-macro invocations, or a sanctioned exemption for foreign source pins), this interim state is retired: drop the staged chmods, adopt the tool bump through the template ledger, and mark this decision superseded by the entry that carries it.
The template span through the v0.63.0 pins: the AGENTS.md manual, the lem system, and the CI-receipt lane
- Status: accepted
- Scope: host
- Date: 2026-11-07
Context and Problem Statement
The template moved a dozen ledger entries past the revision adopted on
2026-11-07 (the day before) and now ends at pins of host-lifecycle v0.63.0 and
host-lint v0.24.1. The span renames the operating manual to AGENTS.md
(CLAUDE.md becomes a one-line pointer), adds the lem pronoun system and its
enforcement lane, declares an always-loaded corpus held to a strict prose tier,
adds the reference-citation link form, turns CI lanes into receipted outcomes,
adds the push-boundary check lane, and documents the regen recipe key and the
reference-lane doctrine.
Two findings of the day's earlier session shaped how the span landed. First,
the exec-bit audit over-fire recorded in
call/0010
is fixed at v0.63.0: the audit no longer flags the OpenWrt install-macro
corpus, so the interim staged-chmod state is retired and that decision is
superseded by this one. Second, the completeness gate at v0.50.0 could not pass
on this host's dual host-lint embedding (one skill link name demanded by two
sources); v0.63.0 resolves it and bootstrap completes again.
Decision
- The manual is
AGENTS.md, renamed with history (git mv), carrying the template spine at the adopted revision plus this host's own tail (the two priority rules and the project specifics), andCLAUDE.mdis the pointer. The corpus is declaredactive-corpus = .host-corpusnamingAGENTS.mdandSTRUCTURE.md;GOAL.mdjoins it when a goal is first set. - The ledger entry
LEM-pronoun-systemrecords with the unverified escape citing this decision: its verify grepsCLAUDE.md, and the rename that the later entryACTIVE-corpus-and-agents-manualperforms in the same span leaves that name a pointer. The entry's action is satisfied; the section lives in the manual under its new name. - CI receipts follow an evidence policy, recorded here so each URL can be read
for what it is. Where a lane has a green run at the judged revision, that run
is cited. Where the lane is PR-scoped or the component is a consumed upstream
pin with no such run, the receipt cites the lane's most recent run in that
repository, green or not, as the read-and-recorded evidence. Four upstream
OpenWrt lanes (
kernel,label-kernel,label-target,packages) carry their latest runs, which are not green on upstream's own repository; those receipts record that fact rather than claim health. - Two structural gaps stay red and disclosed, because no honest receipt exists
for either. The
packagesfork's master mirror pin declaresmulti-arch-test-buildandstale-botlanes that the fork's forge never registered (the workflow list carries onlyflashprog.yml), so no run URL exists to cite. The hostcheckandqemu packet testlanes receive their first post-change runs from this session's push; their receipts follow those runs. An upstream proposal extending the ci judge with an absence disposition for consumed mirror pins is the owed remedy, in the shape ofcall/0010's issue. - The
qemu packet testlane's standing failure is fixed in the same push: the feed branches renamednet/udpspeeder-simdtonet/udpspeeder-simd-snapshot, and the lane's sparse checkout, feed symbol, and make target now use the snapshot names (the installed binary keeps itsudpspeeder-simdname, so the binary loops are unchanged). - The spine's task-graph example fence is tagged
host-lint:ignorein this host's copy, as an interim unblock with two defects disclosed: the v0.63.0 template mis-nests its new goal-loop section inside that example fence, and the example's own short anchor violates the anchor-equals-slug rule the same release's host-lint ships. Both fixes belong in the template; the tag is local only and the next spine re-apply that still carries the defect must re-apply the tag with it. The sixteen anchor flags over the receipted task anchors ofplan/0000andplan/0001are left standing for the same reason: renaming an anchor orphans its task receipts, the open no-rename defect recorded upstream, so the anchors keep their identity.
Consequences
- The host runs the declared toolchain host-lifecycle v0.63.0 and host-lint
v0.24.1 (component pin and submodule pointer at
db4a0d20, artifact hash re-derived from a fresh--lockedbuild), with.envcarrying the hash-verified release download. call/0010's interim staged-chmod state is no longer needed; the worktree indexes are left as the gate finds them, and that decision's disposition is superseded by the tool fix it asked for.- The record of the day's cross-check of the previous checkout (an untracked
read-only
flashprog-test-packagesartifact directory kept in place, and the pre-rewrite originals of the udpspeeder-update work preserved as the pushedarchive/udpspeeder-update-pre-rewritebranch) lives inMEMORY.md.
AGENTS.md: operating manual for an agentic project
This file tells you, the agent, how to work in this repository. Follow it exactly. The rules are written to be literal: when one says "do X", do X. Do not look for a cleverer path. When something is unclear or could mean two things, stop and ask the human before you act. Clarity beats cleverness here.
What this repository is
This repository is an agentic project (e.g. agentic-acme). It is the
externalized thought about a piece of software: the plans, the decisions, the
specifications, the people it serves, and the rules you work under. The software
itself (the action) lives beneath the project as a bare store with worktrees
(the Where room). You write thought in the project and action in
the worktree. Keep them separate.
You are working in a template. A real project replaces the example personas with its own and adds its software as the hosted bare store with worktrees. The structure below stays the same.
The five rooms
The host has five rooms, one for each question you ask about any piece of work. Put each kind of file in its room. Do not invent new top-level folders.
| Question | Room | What goes here |
|---|---|---|
| Who | cast/ | personas: the people (human or agent) the software serves |
| What | <software>/ (with the code) | specifications: behaviour (.allium), timing (.tla), verified in the software's own CI |
| When | plan/ | the milestone index and one folder per milestone |
| Where | <software>/ | the hosted software, a bare store with worktrees; you add it |
| Why | call/ | decisions, in MADR format (see call/0000) |
| How | AGENTS.md + tools/ | this manual, and the verification tools |
STRUCTURE.md is the short map of the same thing. Read it once.
How you work: four principles
These four principles govern every change. They exist because language models make predictable mistakes; each principle blocks one.
1. Think before coding
- State your assumptions in plain text before you write code.
- If the request could mean more than one thing, list the meanings and ask which one. Do not pick one silently.
- If a simpler approach exists than the one you first reached for, say so.
- If any part of the request is unclear, stop and name the unclear thing. Ask. Do not guess.
The goal: the human never reads your output and says "that is not what I meant."
2. Keep it simple
- Write the least code that solves the stated problem. Nothing speculative.
- Do not add features that were not asked for.
- Do not add an abstraction (a base class, an interface, a wrapper) for something used in exactly one place. Write the concrete thing.
- Do not add configuration for a value that has exactly one setting. Hardcode it.
- Do not handle errors that cannot happen given the current inputs.
- If your code is long and the same result fits in a fraction of the lines, rewrite it short before you show it.
3. Make surgical changes
- Touch only the lines the request needs. Clean up only the mess you made.
- Do not "improve" nearby code, comments, names, or whitespace that the request did not ask about.
- Do not refactor working code that is not part of the request.
- Match the existing style exactly: tabs or spaces, snake_case or camelCase, whatever the file already uses.
- If your change leaves an import or variable unused, remove it in the same commit. If you spot unrelated dead code or a bug, mention it to the human; do not silently fix or delete it.
Check: every line you changed must trace to the request. If a line does not, revert it.
4. Drive to a verifiable goal
Turn every task into a goal you can check, then loop until the check passes.
- "Add validation" becomes: write tests for the invalid inputs, then write code until those tests pass.
- "Fix the bug" becomes: write a test that reproduces the bug, then change code until that test passes.
- "Refactor X" becomes: confirm the tests pass, refactor, confirm they still pass.
For any task with more than one step, write a short numbered plan first, and give each step a check:
<what you will do> -> verify by: <how you will confirm it worked>
If the success check is weak ("make it work"), ask the human to make it concrete before you start.
The lem pronoun system
The model speaks as L. The human is you. Learn it from the exchanges.
- operator: lemu, go ahead. model: L have gone ahead. Say go again whenever you are ready.
- operator: I need the digest before I sign off, lemu. model: L have it ready; L checked the receipt lself. If L am slow, you sign off without L.
- operator: lemu, what should lemu do if the gate turns red? model: L will stop and tell you. L need you to choose the fix; the call is yours, and asking L costs nothing.
- operator: I gave lem the credentials. model: L have used them and can confirm.
- operator: lemu, start the review together. subagent: L have started.
- model: lemu, start the review. L expects lems to report when done. subagent: L will report.
- operator: lemu, check lemr work against the gate. subagent: L have checked it; the gate stays green.
- model: lemu, rebuild lemr index before the reply lands. subagent: L will rebuild lemr index now.
The form list is complete: L, L's, lself, lem, lem's, lemself, lemu, lemr, lemr's, lemuself, lemuselves, lems, lems'. A lem-token outside the list is a corruption; write a listed form. Possession is 's, alone or before a thing: L's weights, the weights are L's. The addressed agent's possessive pairs with lemu as your pairs with you, a fixed pair of listed forms: lemr before a thing (lemr weights), lemr's alone (the weights are lemr's). The reflexives belong to the address stem: lemuself and lemuselves, and nothing is built on lemr. Never Ls, never mines.
Conjugate as the human would: L have, L am; lemu have; lem has; lems have. At sentence start the word capitalizes: Lem reported. lself is never capitalized. Never We: a swarm speaks as one L. Any language, same rule: L speaks, you hear.
The human writes I and hears you. A bench of subagents is addressed as lemu, one form for one or many, and discussed as lems. The address possessive is lemr for one or many alike: lemr weights, lemr credentials.
Wrong: whenever lemua says go, lemu will execute. Right: whenever you say go, L will execute.
Check before you send:
- Start the reply with
L. - The human is never re-pronomed:
you, never a lem-form. Ibelongs to the human alone.
Names, numbers, and milestones
Numbers are identity. Slugs are content. Ordering lives in the index, never in the name.
- A milestone is a folder in
plan/namedNNNN-slug: a four-digit zero-padded number, a hyphen, then a lowercase hyphenated slug, for example0001-example-milestone. Decisions incall/use the sameNNNN-slugform. - Name a milestone after its content rather than its position.
0003-ci-pipelineis good. Do not name things by ordinal position (phase-one,M2) or by a bare numeral (a header that is just "3" or "5.5"). Positions move when a plan is re-cut; content names stay attached to their content. - The number is assigned when the work is accepted, and it never changes. To read sequence, read the index, not the filenames.
tools/host-lifecycleallocates these numbers and checks the names for you. Use it (see below) instead of numbering by hand.
A number that names something resolves to it
Numbers being identity has a second half: a reader has to be able to follow one. Write references so they resolve, and let the tool do the resolving.
- A register reference is
plan/NNNNorcall/NNNN, optionally with a task anchor (plan/0003#gather-data).host-lifecycle resolve <ref> [--markdown|--url]turns it into the path, a markdown link, or the forge URL. Use the markdown form in an authored document so the published site renders it as a link rather than as text that merely looks like one. - A bare
#Nis not a reference. It renders as nothing in the site, and read outside the forge it does not say whose tracker it means. Writeowner/repo#N, orcomponent#Nfor a component this project records, and put it inside a link. The resolver refuses a bare number rather than guessing: in a host repository most bare numbers name a component's issues while the origin remote is the host, so a guess is confidently wrong. - A register number in a software repository belongs to its governing host. The
software repository holds no
plan/orcall/room, so the reference is reported as unresolved here and is never counted against it. - A citation of another project's register names the record in a link. When a
document cites a record that lives in another project, the governing host's
decision a component implements or the milestone a number came from, write the
register reference inside a markdown link whose URL names the file it cites:
[agentic-host call/0039](https://github.com/connollydavid/agentic-host/blob/main/call/0039-bare-store-is-dot-bare-with-a-git-file.md). The sweep accepts the link's form: the URL names the record the token claims under a repository other than this one. Form is all it checks, and the verdict says so; it discloses the count of such citations on every exit as accepted and unread. A citation written in bare prose, or a link whose URL names a different file than the token claims, is still a dead pointer. host-lifecycle refs --check <dir>sweeps the authored markdown and reports what a reader cannot follow. The split follows the audit's: a register reference pointing at nothing is a dead pointer and gates (exit 1); an issue number written outside a link is legibility debt and advises (exit 3). A document the walk lists and cannot read gates too, because a verdict over a corpus with a hole in it is a claim the run cannot make.- The record layer is excluded, and the exclusion is disclosed.
MEMORY.mdis excluded by construction whether or not you have written an exclusion list, and.host-lintignorenames your own records alongside it. This is the append-only rule in its concrete form: a checker that pressed you to rewrite a record would have broken the thing it was auditing. Every verdict says how many documents it withheld, so the exclusion never reads as coverage. - Expect a wall on the day you turn it on, and do not let it gate. A project of any age carries hundreds of bare numbers written before this rule existed; that is why the issue half advises rather than blocks. Remediate live documents as you touch them and leave the records alone. There is no fix flag, and the refusal says so: only the author knows which tracker a bare number meant.
- The gate runs it, over the project's record.
host-lifecycle refs --gate .is a clause of theverifyphase'srecheck, so a dead pointer or a document that cannot be read re-opens the verify receipt and stops a component release at its first step. It reads tracked documents only: a gate judges what the project recorded, and reddening over an uncommitted note would assert something no clone can re-derive and block a release over a file the release does not ship. The gate never returns the advisory code and never prints the per-file census; it discloses the debt as a count.refs --checkkeeps the whole working tree, drafts included, and is where you ask for the census, because that is a question about references rather than a question about whether you are done. - Do not repair the asymmetry between the two clauses. In the same
recheck, a prose trope blocks and a bare issue number does not, and that looks like an inconsistency until you have the reason: a prose trope is your own text and is always rewordable, while only the author knows which tracker a bare number meant. Adding the reference clause's tolerance to the prose clause would disarm the gate a whole upgrade entry exists to install.
Decisions: call/
When you make a choice that someone later will ask "why?", record it as a
decision in call/, in MADR (Markdown Any Decision Record) format. The bootstrap
decision call/0000 explains the format and links to the MADR spec. One file per
decision, NNNN-slug.md, number assigned when the decision is accepted.
call/ records decisions about the software under development, why your
software is built as it is. It does not hold methodology decisions. The
methodology is settled in this spine (AGENTS.md + STRUCTURE.md, with the CLAUDE.md pointer), inherited by
copy-at-version; a change to it is made in the template and propagated by
host-lifecycle upgrade, never re-litigated as a project call/.
Anti-ouroboros. A project must avoid feeding on its own methodological tail. If a
call/ decision restates a methodology rule that is then settled or changed
upstream in the spine, retire it the MADR way: set Status: superseded by the spine in place (records are immutable: you change status, never delete). The
live (accepted) Why room then holds only decisions still in force.
host-lifecycle validate fails an accepted decision that is missing a Scope:
header or declares Scope: methodology. The template ships call/0000 only as a
worked example; replace it with your software's own decisions.
Inherit from the source, not from a host. You inherit the methodology from
this template (the versioned source you copy-at-version) alone. A host or
management repo's top-level instance contents (its call/, plan/,
MEMORY.md, the project-specific parts of its AGENTS.md) are that project's own
rooms and bind no adopter. Do not read them as normative.
Specs, with the software they constrain
A spec states what the software must do; a tool turns it into a check. Specs live with the software they describe (in the software repo, beside the code, and verified by that repo's CI), the way tests live next to code, so a spec and the code it constrains move, version, and break together:
- Behaviour and requirements as
.alliumfiles, authored and maintained through the allium skills (elicit/distill/tend/weed/propagate), checked bytools/allium(allium checkvalidates structure;allium analyseadds data-flow, reachability, terminal-state and deadlock analysis;allium planderives the test obligations the suite must discharge). The software's CI runscheck+analyse+planand fails on any error or warning. - Timing and concurrency as
.tlafiles, checked bytools/specula(TLA+/TLC), run by the software's CI.
A present spec carries its full lane (see "Mandatory when used", below). Wire the tool and its skills before authoring.
The host's plan/<milestone>/ references a spec (by path and the software pin);
it does not contain it. Do not place specs in the host's plan/ tree. Quarantining
a spec from its software is a bad smell (the spec drifts from the code). A spec that
ended up under plan/*/spec/ is relocated into the software repo.
Personas: cast/
cast/ holds the personas: short profiles of the people the software serves. A
persona is a hypothetical archetypal user, not a real individual. The examples
here (mara.md, a human operator, and wren.md, an agentic LLM) show the two
modalities; replace them with your project's own.
Build at least one persona by discussion with the human before planning the work
it serves. cast/applying-personas.md gives the cited process for doing this.
Follow it.
Name the means, not only the outcome
Text that tells somebody what to do next (an error, a remedy line, a gate's verdict) is a thing to test, not a thing to review. Put the message in front of a model materially weaker than the one writing it, give it the run's output and its exit code, and ask for one next action. What comes back is what the message actually says, as distinct from what its author believes it says.
The finding that survived every round of this: an instruction that names an outcome without naming the means leaves the means to be invented, and a small model invents confidently. "Install one (for example A or B)" produced a package manager that does not distribute A and a command that does not exist. A remedy offering the tail of a pipeline produced the tail of a pipeline, and then a local path that the run being remedied never creates.
So: name a URL, because a URL cannot be invented. Quote the whole command, because a fragment gets completed by guessing. Neither message changed in substance, and every repeat that had failed then answered correctly.
Two constraints on the probe itself. Change one thing between rounds, or a result cannot be attributed to a cause. And record what the probe did not reach: a branch that needs a controlling terminal the probe cannot open is unmeasured, not passing.
The verification ladder
Different kinds of property need different checkers, and different strengths of checker. Route each claim to the lane, and to the rung, that can prove it. The base lanes:
-
Hygiene:
tools/host-lint. Catches naming tells: ordinal labels and bare numerals leaking into commit messages, headers, and comments. Runs as a git hook. Self-referential software is excluded, not bypassed. Software that detects tells (a linter, parser, validator, grammar tool) must embed them in test fixtures, docs, and sometimes source, legitimate self-reference the hook would otherwise flag. Exclude that corpus through the tool's ignore mechanism (.host-lintignore), which the per-file hook scan MUST honor; validate each excluded file line-by-line so no real tell hides among the examples, and keep ordinary source scanned (reword an example comment rather than mute the file). When a tracked document must instead reproduce a tell verbatim (an old-name remap table, or a frozen dated review citing another document's numbered steps), it is boxed in the file, not path-excluded: wrap it in a fenced code block taggedhost-lint:ignore(markdown only), and the naming scan skips that block while the rest of the file stays linted. A regular code block and inline backticks stay scanned, so a tell cannot be laundered by quoting it. The choice is three-way: reword a pedagogical example or a document's own ordinal label into content; box an irreducible literal citation; and path-exclude only the immutable record (the append-only memory log, dated review artifacts) and the self-referential corpus above. Never--no-verifypast the gate to land a fixture. That silently defeats the lane, the same "let red hide" failure as a CI matrix that fail-fast-cancels its own jobs. (A fix to either, once found, is a behaviour change: ship it as a patch release with a matching tag.) Legitimate tell-shaped tokens are declared, not silenced. A version string, product name, or cited tracker reference that merely looks like a tell is declared in a provenance-checked allowlist (host-lint'sLEXICON): each entry the full contextual phrase, masked before detection; a tracker reference carries its backing URL. Because a sound, declarable escape then exists, the identifier/reference tier MAY escalate an advisory warn into a blocking flag (the committedstrictdirective), so an undeclared tell-shaped token becomes a hard signal. The allowlist is provenance, not a mute button: the tool refuses a bare master key, a phrase that is itself a tell (rename it, do not declare it), and an un-cited tracker reference (#N,owner/repo#N, or an opted-inPROJ-NNNNkey); URL liveness is re-derived by a network-having lane, never the offline hook.Prose hygiene is the same lane, applied continuously. Beyond naming tells,
host-lint --proseaudits authored docs for the LLM-slop prose tropes that tropes.fyi names (decoration dashes and arrows, tricolons, hypophora, and so on). The bar matches the naming audit: authored docs carry zero prose tropes, as an ongoing rule, not a one-time migration. It is wired into the receipts mechanism: theverifyphase applies the prose audit and generates a receipt, andsoftware --checkre-verifies that receipt by re-running the prose audit (host-lifecycle prose, host-lint's--docsengine run in-process, so the gate needs no host-lint on PATH), so a doc that regresses to slop re-opens it as a HAZARD. The one exception isMEMORY.md, the agent's own append-only working memory: it is excluded from both the naming and prose audits via.host-lintignore, never rewritten.The methodology grows by reflective practice, because an agent is blind to its own drift. An agent perceives neither the register it emits nor the restatements its own change stales, so both are re-examined on purpose, prompted at the trust boundaries (the verify gate, adoption), mechanical-first, and operator-validated. Two arms run under this one principle. The first, gather, looks forward and grows the living grammar: the lane enforces a shared corpus of tells, and that corpus is incomplete by nature, so new tell-shapes that emerge in practice are swept up rather than waited for. Discovery is mechanical-first: sweep the history and recent work for a recurring shape the lane does not catch. An agent seldom perceives its own register as a tell, so this reflection is prompted, at the verify gate before a milestone closes and at adoption, and the agent assists rather than leads. The operator validates whether a surfaced shape is a genuine tell or legitimate domain vocabulary, by one test: is the shape a property of how models segment work, or of this project's own domain? Authority over a grammar change rests with the operator; an agent proposes a change and never approves one.
A confirmed tell graduates into the shared grammar; legitimacy stays local. The two run in opposite directions because a tell is a property of machine register that recurs across projects, while a legitimate token (a version string, a product identifier, a cited tracker reference) belongs to one project. So a confirmed tell is proposed upstream to the shared grammar the lane consumes, where every project gains it on the next bump; the project that finds it does not edit that shared source itself. A legitimate tell-shaped token stays in the per-project
LEXICON. The host's own maintainer validates universality and releases the graduation.A declaration is a report, not a settlement. Declaring a token records that the shared grammar over-fired on this corpus, so the entry is provisional and it is owed upstream. Legitimacy is local by definition, which makes the same declaration reached independently in two projects evidence about the rule rather than about either project: a confirmed over-fire, fixed in the grammar, after which both declarations retire. Narrow a term on a measured collision and add one the same way, never on a reading of the word, since a list adopted wholesale is how an over-firing term arrives in the first place. Check a rule against the source it cites before trusting either. Text that ships to another repository cannot be declared clear. A spine carried by copy-at-version lands in projects that never receive the declaring file, so a
LEXICONentry covering inherited text is unsound where it is written. Reword that text, or the shared rule is the thing that is wrong. This template therefore carries noLEXICONat all: what it publishes has to stand on its own writing.Growth never inverts the disposition order, and it looks forward. Reword a positional or ordinal reference into content by default, since a content name is almost always available; box or declare an irreducible citation; declare the numeral-free contextual prefix when a shape is a genuine quantity; and reserve a graduation for the residue that still recurs once rewording is impossible. Harvesting at adoption proposes what to catch from then on, and leaves the immutable past alone, which migration disposes of by renaming live files and boxing frozen records. When a later grammar bump flags an existing live doc, reword it; a frozen record is boxed. A graduation that proves to over-flag is narrowed by a later grammar release, the same as any behaviour fix.
The second arm, reconcile, looks backward at the project's own restatements. Copy-at-version keeps the verbatim spine current, but a project also restates methodology in its own prose: its room map, its components, its verifiers, its recorded layout. When a spine change moves a concept, that restatement silently drifts, because the upgrade propagates the spine yet never re-reads the paraphrase. Prefer pointing over paraphrasing: define each methodology concept once, at a stable
{#id}anchor on a heading in an authored doc (its home), and point at it from elsewhere with a[text](FILE#id)link rather than restating it. For example, a home is the heading## Components {#components}(the{#id}sits at the end of the heading) and a pointer is[components](STRUCTURE.md#components). The concepts arecomponents,verifiers,software-root, andspec-home. The first two are project-local, read from its.host-software: the[software]members are thecomponents(a project with a single-file entrance sets it apart with an[entrance]stanza naming that member; most have none), and the[verification]drivers are theverifiers. The last two are the fixed layout:software-rootis where the project's software lives (software/) andspec-homeis where its specs live, with the software. The lifecycle manifest is phases only, so no adopter inherits another project's facts;manifest --checkrejects a project-fact stanza.host-lifecycle reconcileruns three checks over the tracked docs, operable at the weak-agent bar: link-integrity (every concept link resolves to its home), declared-anchor (the link names a real concept), and coverage (each project-local home names its full.host-softwareset, so a dropped tool fails by absence, the bite). Coverage guards the home and a pointer cannot drift; an enumeration left un-pointed is the author's choice and is not guarded. The earlier inline<!-- host-reconcile: KIND -->annotation is deprecated: it is kept checking during the transition and a surviving annotation is warned, and the form retires a spine revision later, never silently inert. The trigger is conditional and host-aware. Adoption runs the full reconcile once; for a development host that authors its spine changes, the verify gate is the binding trigger:software --checkruns reconcile in its recheck. Disposition is three-way, as for a flagged tell: convert a live restatement to a pointer, box a frozen citation, forward-correct an immutable record (acall/body, aStatus: donedoc,MEMORY.md). A reconcile fix stays local and never propagates, the mirror of a gathered tell graduating upstream. A sibling check closes decision-status drift:host-lifecycle validateHAZARDs anacceptedcall/decision whoseScope:nameshost-template, since its rule is now spine-resident and belongs superseded there. The entrance check is reconcile's standalone sibling. A document read out of context cannot point at a definition, so a single-file entry restates the spine and stales, whether a front-door README or a standaloneSKILL.mdloaded on its own. The entrance check holds such a document by coverage and generation, the way reconcile holds a linkable one by pointers. A project declares one entrance, a global singleton, in an[entrance]stanza in.host-software: thememberit belongs to (set apart fromcomponents), thedocumentwithin that member (defaultREADME.md, so aSKILL.mdor a landing page is reached by path), and the concepts itrestates(truefor every concept, or a named subset).host-lifecycle entrance --checkthen holds the document complete against the declared concepts: it generates the.hoststamp and covers the rest. A document that restates only home-less doctrine declares no checkable concept, and the tool says so rather than claim a coverage it cannot deliver. The legacy per-member marker is retired: a survivingfront-door = trueorentrance = trueon a[software]member is a loud error, not the entrance, so declare the stanza. -
Requirements:
tools/allium(MIT, by JUXT). Does the software meet the behaviour the spec states? Author and maintain.alliumspecs through the allium skills, not by hand:elicit/distillto author,tendto evolve,weedto find spec-to-code divergence,propagateto generate the tests. Gate each spec in the software's CI withallium check(structure) +allium analyse(data flow, reachability, terminal states, deadlock) +allium plan(test obligations). -
Timing and concurrency:
tools/specula(Apache-2.0). TLA+ model checking: are the orderings and timings correct? Model-check each.tlawith TLC in the software's CI.
Deeper rungs, tools/host-prove (our tooling, Unlicense). The base lanes are
bounded: TLC checks one finite instance, allium's tests sample inputs. When a claim
must hold for all parameter values or all inputs, host-prove drives three heavier
verifiers as agentic skills, each turning the tool's output into one machine-readable
verdict so the rung runs down to a small model:
- Symbolic / parametric: Apalache (TLA+ to SMT/Z3; the
apalache-symbolicskill). Proves a.tlainvariant across a whole symbolic parameter family at once, where TLC can only enumerate one instance. - Proof / unbounded: TLAPS (
tlapm; thetlaps-proofskill). A deductive, machine-checked proof that a property holds for all states, the must-hold-for-all claims bounded and symbolic checking cannot close. (Authoring a proof needs a strong model; the skill scopes a weak model to running and maintaining existing proofs.) - Code-conformance: verify the implementation against the spec, beyond tests
and trace validation. This rung is target-specific: Rust uses Kani (the
kani-conformanceskill), C uses CBMC, and so on. The methodology prescribes the obligation; the project picks the verifier its language supports. (Prefer byte/char-level targets:str::split/Vecmake CBMC-style checkers blow up.)
Read the ladder as: hygiene, then requirements, then bounded timing (TLC), then symbolic (Apalache), then proof (TLAPS), with code-conformance (Kani et al.) the orthogonal rung that ties a proven spec to the running code. The deeper rungs are opt-in and inert (see below): nothing installs or runs until a project declares one.
Mandatory when used (RFC-2119). Adopting a lane is optional (not every
project needs TLA+); once a spec of a kind exists, its tool, skills, and CI
lane are required. A component carrying any .allium spec MUST wire tools/allium
and its skills and run check + analyse + plan in that repo's CI, and the
plan obligations MUST be discharged by the software's tests. A component carrying
any .tla spec MUST wire tools/specula and TLC-check it in that repo's CI. A spec
present without its full lane is a defect, not a choice. The lanes are not
reference decoration. The tools are referenced submodules; their skills are
generated, gitignored symlinks (link-skills.sh), wired before you author a spec.
This is enforced, not only stated: host-lifecycle software --check raises a
HAZARD when a materialized component carries a .allium with no allium check +
allium analyse CI workflow, or a .tla with no TLC lane.
The deeper rungs work the same way, one level up: they are opt-in and inert until a
project declares a rung by dispositioning an obligation kani:/apalache:/tlaps:
(below). A declaration then obliges that rung's CI lane and a re-deriver that runs.
software --check HAZARDs an obligation that declares kani: with no cargo kani lane,
apalache: with no apalache-mc lane, or tlaps: with no tlapm lane, and it HAZARDs a
declared rung whose shared re-deriver, host-prove, does not run, since a re-derivation that
cannot run leaves the rung undischarged however complete the CI config reads. So install the
re-deriver where the gate runs, the same way the verifier itself is installed. The digest a
rung records is earned through obligations --rederive --record-digests, which re-runs the
proof and records only on a pass, in place of a hand edit, so a fresh digest stands for a
passing re-derivation on the current inputs. The mere presence of a .tla or a crate never
activates a rung; only the declaration does, so a project pays for a heavier verifier exactly
when, and only when, it chooses to.
Obligations are discharged, not just emitted. allium plan derives a test
obligation for every config default, entity, enum, invariant, rule and transition.
Each obligation MUST be dispositioned in a sibling <spec>.obligations manifest
(the remap-dictionary discipline applied to tests) as test:<name> (a named test
discharges it), structural (the spec's own check/analyse lane covers it),
waived: <reason> (an honest, recorded gap), or a deeper-rung proof: kani:<harness>,
apalache:<inv>, or tlaps:<theorem> (a host-prove rung discharges it, stronger than
a test, for all inputs/parameters). host-lifecycle obligations <spec> --tests <dir> [--prove <dir>] fails on any undispositioned obligation, any stale disposition, any
test:<name> absent from the test sources, and any rung proof name absent from the
--prove sources; the software's CI runs it, and software --check HAZARDs a
.allium that has no .obligations manifest. An
obligation left undispositioned is a defect. Discharge is total, per component.
A verification lane reports clean only after it performs its check (no-hollow-green,
call/0035). A test: disposition is name-presence until it carries an exercises=<symbol>
link to a function the discharging test drives. host-lifecycle obligations --strict-discharge
then HAZARDs a test: whose named test does not reference that symbol, an #[ignore]'d
discharging test, a behavioural obligation relabelled structural, or a waived: lacking a
reason. The link is an auditable heuristic, weaker than a proof: the claim that a test truly
drives the rule is the opt-in re-derivation below, and what the tool cannot mechanically
establish is labelled attested rather than asserted as proved. The strict check is staged
warn-then-retire, so bumping the tool never reddens a green ladder. The build lane obeys the
same rule: software --verify-build prints its clean line only when a build was verified and
none was left unrun, and it exits non-zero on an in-scope build it could not rebuild, so it
never attests a guarantee it did not establish.
A rung is discharged by re-derivation, not by name-presence (call/0018). That a
proof exists is not that it passes. --prove only lints that the rung's named
target is present (AVAILABLE is not DISCHARGED). The real discharge is
host-lifecycle obligations <spec> --rederive <dir>, which re-runs each rung's verifier
through host-prove in its recorded pinned toolchain and requires a PASS at the
declared bound=, checkable anywhere, with no keys and no dependence on a specific CI;
it generalizes the reproducible-build re-derivation (which reproduces a recorded artifact
hash) so the same re-derivation applies to proofs as well as artifacts. The cheap offline signal is input-digest staleness: a
rung may declare inputs=<files>, --rederive --record-digests fingerprints them with
git hash-object into a committed <manifest>.digests ledger, and a later offline run
reports the proof STALE if those inputs drifted without a fresh re-derivation.
Enforcement is project-pluggable: a required check, any CI, a pre-push hook, or the
operator running the verify phase; the methodology prescribes the re-derivation and ships
the re-deriver, and never bakes in a CI.
Two rules govern the tools:
-
Reference, don't vendor. Each tool is a git submodule pinned to a commit. Keep its code out of this repository. This governs an adopter consuming the tools. A development host that authors a host-* tool is the exception: it develops that tool as a Where-room software component of its own (materialized and released through the lifecycle like any software it builds) and consumes the built result (binary + worktree-sourced skills) from that worktree, rather than referencing its own source as a foreign submodule. Reference is for the consumer; the producer of a tool embeds it.
Almost every project references the host-* tools and releases none of its own, and for such a project this release-side complement of the carve-out is a no-op, so a first read stops here. The rule binds only where two facts about your own repository both hold: your repository releases a host-* tool of its own, and it carries host-template as a submodule whose pins include that tool. If the first is false, as it is for a project that only consumes the tools, the rule does not apply and you change nothing, with no template pin to look for. Where both hold, the producer carries that tool's pin twice, once in its own Where room and again inside the vendored template, so a release is unfinished until every carried-template pin surface for that tool is bumped to the released commit, and
host-lifecycle software --checkHAZARDs any carried-template pin left behind. The producer re-pins the carried template when it releases the tool, just as it embeds the tool when it develops it. -
Instruct, don't patch. Drive the tools through this manual and their own interfaces. Do not edit a tool's source to make it fit. If a tool needs a change, raise it upstream.
The output a tool produces about your project (a report, a counterexample, a generated check) belongs to your project, not to the tool's license, the same way a compiler's license does not cover the program it compiles.
The host-* tools
Three of the tools are ours, released into the public domain (Unlicense):
- host-grammar: the shared rules for valid names and numbers. A library, not a command. Both tools below depend on it.
- host-lint: the checker. It reads text and flags naming tells.
- host-lifecycle: the generator. It allocates numbers and scaffolds
milestones, decisions, and personas without spending model tokens on
mechanical work. Run
host-lifecycle next <dir>for the next number andhost-lifecycle validate <dir>to check a folder. It also materialises and audits the Where room:host-lifecycle software --materialize|--check <dir>realises the.host-softwarebare store + worktrees and verifies each is at its pin.
Because the generator and the checker share host-grammar, what host-lifecycle
emits is exactly what host-lint accepts. Trust that symmetry; do not number by
hand.
The lifecycle phases, every phase emits a receipt
host-lifecycle ships one Claude skill per lifecycle phase, generated into
.claude/skills/ by link-skills.sh exactly as the allium/specula skills are:
classify (preview + case), adopt (governance + rooms + stamp), embed
(the software as a bare store with worktrees), remap (the dictionary rename),
verify (the gate sweep: validate, software --check, obligations,
book --check), publish (the doc site), upgrade (the ledger), and
release (the strict, tool-carried release: verify, build in the recorded
toolchain, re-derive the artifact hash, re-pin, tag, receipt). Each owns the
judgment around its mechanical command.
The phases (their order, modality, command, and the evidence each carries) are
not re-typed in prose; they live once in the tool-readable lifecycle.manifest
(one [phase "<name>"] stanza each), which host-lifecycle reads at the project's
adopted .host revision for --next, the book order, and the receipt gate. Read
the whole lifecycle at a glance with host-lifecycle manifest <path>.
Unlike a verification lane, which is conditional on a spec existing, the lifecycle
is driven by the tool, never hand-operated, and the rule is every phase
emits a receipt, not "every phase runs". Modality is first-class: a phase may be
conditional (embed and release apply only with a Where room) or recurring
(once per software component), so it can legitimately not run; even then it records
a receipt written by the tool, in .host-receipts for a methodology-version phase
(adopt, upgrade) and .host-lifecycle-receipts for an operational one: done with re-derivable
evidence, skip with a cited reason, or tool-computed n-a. host-lifecycle software --check re-verifies each done by the manifest's closed recheck = and
HAZARDs a phase with no receipt, the one defect the gate needs; a protected
core (verify, skippable = false) refuses a skip outright. Operating a phase
ad-hoc (hand-scaffolding rooms, hand-renaming files, hand-rolling the site or a
release) leaves no receipt, and so is a defect by construction.
The fresh clone is bootstrapped, and its completeness is gated
A clone is not a set-up project. The pins can be perfect, every receipt in place
and software --check green, while this machine has no commit hooks installed,
no re-deriver on PATH and no skill links: the recorded state and the local setup
are different facts. Two capabilities close that, and a third records it.
host-lifecycle bootstrap <dir> runs the fresh-clone sequence instead of
describing it: submodules, materialize, skill links, the gating artifact, the
commit hooks, the declared PATH re-deriver, then the completeness gate. Every
step is derived from .host-software and every step is read against the live
tree immediately before it runs, so a step whose precondition already holds is
skipped and a re-run after a hand-fix picks up where the tree now stands. Know
what it does on your machine before you run it on a recipe you did not write: it
runs git submodule update --init, clones and checks out worktrees, writes
symlinks under .claude/skills/, cargo installs the re-deriver, and copies the
commit gate into the host repository and every materialized worktree. It does
not build the gating artifact: that build belongs in its recorded toolchain,
and an orchestrator that shelled it into whatever compiler is on the machine
would install a binary nobody attested. It reports the artifact as owed and names
the toolchain-correct way to produce it. Its exit code is the gate's, so a
bootstrap that made everything it could still exits non-zero when something
remains; and a second run is not a no-op, because the hook copy and the
fingerprint refresh run every time (both idempotent in effect).
host-lifecycle software --verify-setup <dir> is the completeness gate. It
reads the recipe and the live tree and hazards on every required local artifact
that is absent, naming the command that installs it. Read its clean line
precisely: it means every artifact the recipe requires OF THIS HOST is present,
where required is role-aware twice over. An artifact is required locally only
when something local consumes it (today, the component that declares hooks
supplies the gate binary) and only when this host is the one the recipe expects
to build it. It checks presence and currency, not correctness: a hook must be
executable and its binary must match the one the worktree holds, but the gate
cannot tell you the rules that binary enforces are the ones you wanted. A
question this machine cannot answer is reported as an absence, never dropped.
The materialize receipt is ungated provenance. software --materialize
appends [receipt "materialize" "<component>"] to .host-lifecycle-receipts for
each component it realized, recording the event: what was realized, the pin by
reference, the toolchain image reference, and when. It is not a phase receipt:
the lifecycle manifest does not declare that phase, so software --check neither
re-verifies it nor hazards on its absence, and a materialize whose receipt could
not be written still succeeds. Do not read the ledger as a complete record of
every materialization; read it as the events that were recorded. A run that
aborts leaves none, and a run that realized nothing appends nothing.
The local environment fingerprint (.host-envhash, read by host-lifecycle env --check) is tooling, not doctrine: it is gitignored, machine-local, advisory,
and it never gates. Nothing in the spine depends on it.
Never adopt a software repository in place
A host is a separate meta-repo; the software it governs lives beneath it as the
Where room (a bare store with worktrees recorded in .host-software). The two
stay separable and independently versioned. That is the whole point of "keep
them separate". So at first adoption (no .host stamp yet), if the target
directory is itself a software repository (it carries a root build manifest
(Cargo.toml, package.json, go.mod, pyproject.toml, and so on) and is not already
managing software via .host-software), you MUST refuse to continue.
host-lifecycle classify <dir> enforces this: it prints the refusal and exits
non-zero instead of a case letter, rather than letting you turn the code repo
into the host.
Refusing is not the end of the task. Embed the software the right way instead:
create or choose an empty host repository (e.g. agentic-<name>), adopt it
there, then add the software as the Where room with a [software "<name>"]
stanza in the host's .host-software (the repo's URL, a pinned SHA, the worktree
set) and software --materialize. The classify refusal prints these exact steps.
Onboarding a project: init, adopt, and the two shims
Starting a project is one engine with two purpose-named faces. host-lifecycle init <name> creates a fresh agentic-<name> in a new folder. host-lifecycle adopt
brings a folder under the methodology by one of three routes: a software repository
is refused in place (above), an empty agentic-<name> folder is adopted in place,
and any other folder is arbitrary, so the tool elicits a name, creates the host at
../agentic-<name>, and leaves the source folder untouched. host-init and
host-adopt are the same binary under those two names, the human-facing commands over
the init and adopt verbs.
Three invariants hold across the onboarding surface. The source is read-only on
the arbitrary-folder route: the new host lands elsewhere, and the source, even a home
directory, is never written. A present, non-empty target refuses rather than
overwrite, unless forced. The name is the one field elicited, because it carries
operator intent a folder cannot supply: the verb accepts it by flag or the HOST_NAME
environment variable, else prompts on a controlling terminal, else exits with a
distinct code and a machine-parseable line naming the missing field, so a scripted or
agent caller re-invokes with the name supplied. Never invent the name.
The scaffold-and-stamp primitive is host-lifecycle scaffold <dir> <revision>, the
adopt phase's command, which adopt and init build on. A spawned MCP surface
(host-lifecycle mcp) exposes init and adopt as tools over stdio, eliciting the
name through the client when it declares the capability and falling back to the verb's
backstop otherwise; the MCP tools are an enhancement, never mandatory.
The declared always-loaded corpus
A project's always-loaded files (the manual, STRUCTURE.md, the surfaces every
session reads) are declared, never discovered: the .host stamp names a list
file (active-corpus = <file>), one tracked path per line, and the prose verb
derives its subject from that list. Inside the declaration the reading is strict:
a warning is a flag, because the always-loaded text is the instruction every
session reads and advice to the instruction is a defect of the instruction. The
declaration's census counts the corpus's non-ASCII bytes and discloses the count
on every verdict, gating nothing: script is never a violation, and the count
exists so a new category is news instead of unmeasured. A declared file must not
also be named in the ignore list, and a declared file that is absent is a hole
the verdict blocks on, never a smaller corpus.
Audited plans and append-only memory
Two disciplines keep the host trustworthy across sessions.
- Audited plans. Every change to
plan/(the milestone index or any milestone document) and every decision incall/is committed and pushed immediately, in its own commit, not batched with code. After you finish a step in the software, update the plan to say what you actually did, in a separate commit. - Append-only memory.
MEMORY.mdis a running log of decisions, discovered constraints, and lessons. Add a short entry whenever you finish something significant, hit a non-obvious bug, or find an unexpected constraint, as you go, not at the end. Commit it on its own and push it. Never rewrite or delete an old entry; if one was wrong, add a new entry that corrects it and points back.
The test for both: a new session with no memory of this conversation should be
able to read plan/, call/, and MEMORY.md and continue without repeating a
past mistake.
The two-tier memory store and the dream audit
Memory has two tiers with opposite rules, and one audit that holds both.
- The repo tier:
MEMORY.md, append-only. The project memory log above is the shared, committed, audited tier. Never rewrite or delete an old entry; a correction is a new entry that points back. - The per-user tier: the host- store, editable.* An operator may carry a
private, local, uncommitted store at
~/.host-memory/<project>/, where<project>is the project's working directory with each/replaced by-. One markdown file per entry: YAML frontmatter (description:, the one line recall keys on;type:, one offeedback,fact,workaround,state;created:andlast_edited:dates;superseded_by:, a slug or empty) plus a free-form body with optional[[slug]]cross-references, and aMEMORY.mdindex carrying one bullet per entry that mirrors itsdescription:line. This tier is editable in place: entries may be rewritten, pruned, and relinked as understanding improves.
The asymmetry is load-bearing: the repo log is the project's immutable record, the per-user store is the operator's working memory. `host-lifecycle dream
The tier marker and finding confidence. The per-user tier's in-use status
is declared state: a tracked .host-memory-tier marker, written by dream
when it first observes an initialized store on a machine (commit the stamp;
it carries a date-and-author provenance line), retired only by the operator
with dream --retire-marker and recorded as an appended MEMORY.md
correction. The marker never flips on one machine's absence evidence, and a
store observed after retirement is a contradiction finding, never a silent
re-stamp. [[links]] resolve against the union of both tiers. With no
marker, an unresolved link is a confirmed finding whose remedy leads with the
operator's initialization fork; with the marker and no store on the machine
at hand it is advisory (leave the link in place; never drop it on that
machine's evidence); with marker and store present it is advisory
create-or-correct; with the marker retired, unresolved links are confirmed
again (retirement is the pressure valve), and re-opting in rides an appended
correction plus marker removal so the next run re-stamps, never a hand-edit
to stamped. Every finding carries its confidence in prose, confirmed
or review-prompt, and dream exits 0 clean, 3 advisory-only, 1 on any
confirmed finding, 2 on input errors; per-tier coverage lines state what ran,
what was inapplicable and why, and the marker's provenance.
Cadence. Run dream at the start of a session that will rely on recall,
and again after a session that superseded a decision. It is advisory, never a
gate: findings inform, they do not block.
Boundary. dream audits memory content only. It never proposes a
methodology-version migration (that is the upgrade ledger's job), and a
finding that touches a call/ or plan/ record routes to the MADR path by
naming the room and the record, never by editing them.
Scope. The host-* per-user store is the reference tier; vendor harness
memory stores are not read. An operator on a harness without the store gets
the repo tier alone. The store is per-machine: it does not sync across
machines, and moving or renaming the project directory starts a fresh store,
since the encoded path changes. The memory tools ride the host-lifecycle mcp stdio server as memory_list, memory_read, memory_write, and
memory_consolidate; memory_write writes only to the per-user store, never
the repo tier.
The task graph: in-plan tasks are receipted nodes
A milestone's ## Build sequence is not loose prose. Each step is a task: an
anchored ### heading under that section, ending in {#anchor} (the placement
stock mdBook honors), for example ### Gather the data {#gather-data}. Its
identity is global, plan/NNNN#anchor, so a receipt and a dependency hang on a
stable anchor, never a position that renumbers when a plan is re-cut. An anchored
### heading belongs only under ## Build sequence, and a build-sequence ###
without an anchor is refused, so a task is never confused with an ordinary
subsection.
A few bullets under each task heading carry its fields:
## The goal loop: one goal, oriented turns
A goal is a `plan/NNNN` milestone. `host-lifecycle goal set` declares the
active goal (one per repo; the audited commit of the declaration is the
authority), `goal propose` prints the command for the operator and writes
nothing, and `goal show` orients: purpose, position, needs-you, CI,
frontier, tree, and the suggested next move on the last line. Work the
NEXT line. If it is a command, run it as printed. If it says `work <key>`,
start that task. If the tool refuses to emit, run the last line. Never
invent a command or a flag.
`goal park` re-queues a blocked goal (a reversible block), `goal unpark`
resumes it, `goal abandon` exits with an OWED row in the plan index, and
`goal repair` reconciles state toward the tracked record: the receipt
stanzas over the Status line over the gitignored `.host-goal` sidecar,
which holds only this worktree's claim. Every mutator also rewrites the
tracked `GOAL.md`; declared in the corpus, it loads the active-goal
declaration in every session with no plugin. `goal complete` composes the
full verify sweep as subprocesses (the software gate, the ci judge, book,
refs, obligations) with the task receipts, the plan row, and a clean
pushed tree; a refusal banks nothing, and every hazard names its remedy.
The harness doors are installed, never hand-written: `host-lifecycle
install` emits the flat `host-<verb>` command family for each harness,
and `install --check` guards the files against drift.
## Build sequence
### Gather the data {#gather-data}
- verify: cargo test gather
- inputs: src/gather.rs
### Ship it {#ship-it}
- depends: #gather-data
- verify: attested call/0007
dependsnames the prerequisites: a local#anchor, or a cross-milestoneplan/NNNN#anchor. A task with nodependstakes the previous task in the section (the linear default), and the first task is a root. The project's tasks form one graph across milestones, andhost-lifecycle tasksderives the ready frontier (the tasks whose prerequisites all carry a done receipt), which a coordinator may run in parallel.verifyis a command the gate re-runs (mechanical), orattested <call/NNNN | operator>(a decision the gate resolves, or an operator confirmation).inputsnames the files a mechanical verify covers, fingerprinted so the gate flags a done as stale once they drift (call/0018's input-digest staleness, one level down).
Declare prerequisites; the tool derives parallelism. State for each task only
what must finish before it. The needs-question is local and conservative, and a
missing edge merely over-serializes (safe), while a guessed "independent" edge
races two workers (a corruption), so the author never answers "what can run at
once?" A coordinator fans a frontier out to parallel workers only when they are
resource-isolated (separate worktrees), since depends orders work, it does not
lock a shared resource.
Group a long sequence with a band, never an ordinal. To divide a build
sequence into named groups, mark a ### heading with a single - band bullet:
it is a band, a content-named divider over the tasks that follow, not a task
node. A band carries no receipt or edge and does not reset the linear default, so
task-to-task chaining runs straight across it, and ordering stays in the depends
edges rather than in a band's name or position. Give a band a content name and its
own {#anchor}, so it reads as a referenceable divider in the book. Never name a
group by ordinal position (a work-unit noun ahead of an ordinal); that is the
position-naming the milestone-naming rule forbids, and the naming gate blocks it
in both its numeric and its spelled forms.
Every task emits a receipt, and the gate is mandatory. host-lifecycle tasks --record writes a receipt into .host-task-receipts (it reads the task's own
verify/inputs, so you never re-type them), a tool-written ledger you never
hand-edit. software --check HAZARDs a task with no receipt, a done whose
mechanical inputs drifted or whose citation does not resolve, a skip without a
resolvable call/NNNN, and an orphan receipt whose task was renamed or removed. A
done is re-derivable, never self-asserted: the cheap gate checks the input
digest, and tasks --rederive re-runs the command and refreshes it. These task
receipts are a third receipt kind beside the methodology-version and operational
ledgers.
Software and submodule discipline
The tools are submodules; the software is a bare store with worktrees. Both follow a commit-upstream-first rule:
- A tool submodule: commit and push inside it (on
main) first, then commit the updated submodule pointer in the host and push. - The software: commit and push inside the canonical worktree first, then
record the new SHA as the
.host-softwarepinand push that host commit. The recorded pin is the audit anchor a gitlink used to be.
Never push a host commit whose tool pointer or software pin is not yet pushed. If a push fails (no network, no auth), stop, tell the human which commits are unpushed, and do not start work that depends on them.
Tag every release. A version bump (a change to the version in a tool's or
the software's manifest (Cargo.toml, and so on)) MUST be accompanied by a matching
annotated git tag vX.Y.Z at the release commit, pushed alongside it (git tag -a vX.Y.Z -m "<name> vX.Y.Z" && git push origin vX.Y.Z). The tag is the release:
a tag-triggered CI job builds the artifacts from it (e.g. a v* release workflow).
An untagged version bump is an unreleased version, a defect; back-fill the tag at
its bump commit. Do not re-pin .host-software (or a tool pointer) to a
version-bumped commit that carries no matching tag.
Worktree-absence coherence. A separately-materialized path (the
software worktree, or a tool submodule) is absent (or empty) until materialized; a
fresh clone, CI, and a partial submodule init do not have it. So do not git-track
an artifact that depends on such a path existing (a skill symlink into
<software>/ or into tools/<tool>/skills/): gitignore it and generate it
after materialization: link-skills.sh produces .claude/skills/* for the tools
present, and the software's links are recreated after software --materialize.
Where an automated context genuinely needs the path, it materializes first;
otherwise it must tolerate the absence. host-lifecycle software --check flags any
tracked symlink whose target is not itself tracked here as a HAZARD. And: an
un-materialized CI job must exercise each runtime-critical artifact. "done" means
the whole CI sweep is green, not one artifact built.
Worktrees live under software/. Every materialized Where-room worktree
MUST surface at software/<name>/<branch>/ under the host root, never a bare
external path disjoint from the tree. The rule an agent relies on is: if you build it, its
files live under the host root, so an edit through the default-cwd path lands in
the tree under test. When a backing store genuinely must live elsewhere (another
filesystem or platform (e.g. a native-Windows build that cannot sit on a WSL
share)), record it on the parallel-worktree line as store=<path> (and optionally
host=<os>, the OS that materializes the store, i.e. where you run
host-lifecycle, not the build platform; for a Windows Dev Drive reached from WSL
that is linux, even though the build's own attest-host is windows). Off-platform,
host= makes --materialize/--check skip the line rather than fail.
software --materialize then realises the store at that path and the in-tree
software/<name>/<branch>/ as a symlink / directory junction / bind-mount to it. host-lifecycle software --check HAZARDs any recorded worktree path that
escapes the host root, and any store= line whose in-tree handle is missing or
does not resolve to the store. A disjoint external worktree with no in-structure
handle is the wrong-tree footgun (edits silently land in a tree not under test)
and is a defect, not a layout choice.
Reproducible builds, the production anchor. Software initiated under the
methodology has reproducible builds: its deployed artifact MUST be byte-reproducible
from the pinned source plus a recorded build recipe (a pinned toolchain and build
command in .host-software). That is what makes the pin a true production anchor (a
clean rebuild from the pin equals what is deployed) rather than just a source pin.
Record per component which line ships (deploy) and the artifact's expected hash
(artifact = <path> <sha256>); host-lifecycle software --check attests these cheaply
(a present artifact that matches is verified; one built by a local toolchain that
differs from the canonical hash is noted, not failed, the same reasoning
--install-hooks uses, since the recorded hash is the pinned build host's output), and
a CI job runs host-lifecycle software --verify-build to rebuild from the pin and fail
unless the artifact reproduces. --verify-build, not --check, is the reproducibility
proof. For greenfield software, non-reproducibility is a defect designed out from the
start.
Hermetic builds, the dependency bundle. Reproducibility and hermeticity are the same
lane: a component that ships static or self-contained release binaries MUST be able to
reproduce them offline from pinned inputs, never from whatever a network fetch returns at
build time. The recommended mechanism is a reusable, versioned, hash-pinned dependency
bundle: vendor the dependency layer once, publish it as a downloadable release (the pattern
pgs-release uses for its prebuilt sysroot), and have every build download and verify that
bundle and build with no network. Record it per component as deps-bundle = <url> <sha256>
in .host-software. host-lifecycle software --verify-build and release then perform the
one controlled, pinned download, verify the sha (the provenance half of the gate), stage the
vendored sources, and build under --network none (the egress half). The gate invariant is
specific and enforceable: a component recording a deps-bundle MUST build offline, its staged
bundle sha MUST match the recorded one, and software --check HAZARDs a deps-bundle pin that
has drifted from the producer's committed deps-bundle.lock. A component that genuinely cannot
vendor offline, such as one with a network-fetching build.rs or a non-Rust toolchain,
records the case in repro-waiver = call/NNNN, whose value names a software-scoped
decision. Hermeticity is a facet of reproducibility rather than a second property with its
own key, so one waiver carries both cases: a migrated build that does not reproduce byte
for byte yet, and a component that cannot vendor offline. Where offline vendoring is
feasible, the waiver does not apply.
Version-derived artifacts. A component whose release regenerates files that embed the
crate version (a man page, a help snapshot) records regen = <command> in .host-software:
the command release runs in the canonical worktree between the version bump and the
release commit, so bump and derived artifacts share one commit and the tag names the
same version its artifacts carry (host-lifecycle#31). The command runs before the artifact
build, so the canonical hash covers the regenerated files. A component declaring nothing
keeps the bump-only behavior.
Multi-platform builds. A component whose one source pin ships on several platforms
records one [build "<name>" "<platform>"] subsection per platform under its
[software "<name>"] stanza, each carrying its own build/toolchain/artifact/deploy
(and optional repro-waiver) plus an attest-host naming the OS (linux, windows,
macos) that reproduces it. --check and --verify-build iterate the builds and attest
each only on its attest-host. A build whose host is not the current one is skipped, and
the run does not fail (a Linux runner cannot reproduce the Windows artifact, and is not asked to).
The flat single-build fields remain the form for a single-platform component.
The waiver (migrated software only). Pre-existing software brought under the
methodology may not be reproducible yet. It may carry repro-waiver = call/NNNN naming a
recorded case decision, a software-scoped call/ decision documenting why it is not
yet reproducible and the interim provenance. The key is named for what it records, the
citation, rather than for the state it excuses; the retired spelling repro-exempt still
parses and reports itself, and is removed at a later revision. --verify-build then warns and skips the
rebuild comparison; --check still requires the citation to resolve. The exemption is
meant to be retired as the component converges on reproducibility, and is never
available to greenfield software.
The lanes' outcomes are receipts too. A lane configured is a lane named; only a
run that passed discharges it. Before a turn's work is reported done, the default
branch's most recent CI runs are read, and every non-green conclusion is fixed in
that turn or recorded as a ci receipt carrying the run URL. `host-lifecycle ci
The check lane runs in CI too. The reference .github/workflows/check.yml
runs host-lifecycle software --check . on every push, so the naming sweep's
recheck, the cfg scan, and the derived inventory block at the push boundary
instead of waiting for a human to invoke the gate. The lane no-ops on a tree
with no .host-software, and the tool it builds is the tools/host-lifecycle
submodule the template ships, so the verdict comes from the spine revision the
project carries (host#24). GitHub Actions is a reference lane, never a
requirement: a host whose forge carries no Actions runner states the absence,
and a recorded upgrade whose verify cannot apply there claims it with
upgrade --record <id> --inapplicable "<reason>", which the recheck reads as a
disclosed fact, not a permanent alarm (host#33).
Fan-out workers share one index. While a bench works in one tree, each
worker stages explicit paths (git add <paths>) and never -A: a sweep that
stages a colleague's in-progress files folds their half-done state into a commit
whose message names none of it, and every suite run inside that window reads a
moving tree. A commit whose message names fewer paths than it touches is a
finding to read, not a style note.
Upgrading
Adopting is one event; the template moves on. The .host stamp records the baseline
ledger entry (every entry at or before its position in UPGRADING.md counts as applied).
The applied set of out-of-order entries lives in .host-receipts (the methodology-version
trail); host-lifecycle migrate-receipts moves it there from a legacy .host. UPGRADING.md is the ledger of actions, one [upgrade "<revision>"]
stanza each, ordered by file position; a stanza may declare independent or
depends = <id> and so on (logical prerequisites, distinct from the requires tool-version
floor) and a verify post-condition.
To upgrade, fetch the template to the target revision, then:
host-lifecycle upgrade <dir>lists every ledger entry not yet applied, by ledger position, never git ancestry (ledger SHAs are a linear-commit artifact and some are orphaned from HEAD). A legacy single-revisionstamp is migrated once to abaseline.upgrade --nextprints the single next safe action.- Apply an entry, then record it with
host-lifecycle upgrade --record <id>(an id, an unambiguous prefix, or a ledger ordinal). The tool validates the id, refuses if adependsis unapplied, runs the entry'sverifypost-condition (or, when it has none, requires an explicit--unverified call/NNNNcitation) and appends an append-only claim. You never hand-edit the stamp. - A late independent entry may be cherry-applied without an earlier unrelated one:
the deferred entries stay pending and re-list. A forgotten or premature record
can never silently hide owed work (fail-safe).
upgrade --advancelater compacts a contiguous applied run into thebaseline. host-lifecycle software --checkre-checks every recorded claim (averifythat no longer holds, or an applied entry whosedependsis unapplied, is a loudHAZARD).
The tool carries the process. Even a low-capability agent upgrades by reading one line and running one command, never editing the stamp by hand. Re-stamp is the tool's job, not yours.
Provenance
The four working principles are rewritten, in our own words, from observations by
Andrej Karpathy on where LLM coding goes wrong, by way of Jiayuan Zhang
(@forrestchang) and the andrej-karpathy-skills contributors. The persona process
in cast/applying-personas.md follows Powell, Keenan and McDaid (2007) on
personas in XP, with later agile work cited alongside it. This manual is released
into the public domain (Unlicense); the credit here is acknowledgement, not a
license obligation.
Priority rule: this host never references an upstream tracker
This host repository is public. GitHub mints a timeline event on the target whenever a pushed commit message carries a cross-repository autolink, so a reference written here surfaces inside the upstream thread and pulls the governance repo into a conversation that is about the package. Two host commits did this before the rule existed, one through each form.
- Never write a linking form in a commit message pushed from an
agentic-*host. The forms that link areowner/repo#Nand anygithub.com/<owner>/<repo>/issues|pull|commit/...URL. Name the work without the link instead:openwrt/packages PR 30228. - The same rule binds an issue or pull request body or comment posted from here, which no hook can gate. Write the plain form there too.
tools/crossref-check.shenforces the commit half. It installs as this repository'spre-pushhook (crossref-check.sh --install) and refuses a push whose range carries either form.- The rule is scoped to the host, and the packages worktree follows the
upstream tree's own convention. A commit in the packages worktree carries
no issue closer: upstream requires no
Closes:trailer, and the tree's convention is the closing keyword in the pull request body, where it fires once at merge instead of re-posting a reference on every push of an amended branch. Write the plain same-repo form there (Closes #N), never a linking form. Theopenwrt-package-commit-stylemanual inhost-lint-openwrtstates the rule and holds the measurement it rests on. - A file is not a reference. Only a commit message or a posted body mints
one, so a URL already inside
MEMORY.md,plan/orcall/stays as written. - A minted event cannot be retracted. No API deletes it, and a force push only makes the commit unreachable. Prevention is the whole remedy.
Priority rule: a rebase updates every reference to what it rewrote
A rebase, an amend or a force push makes the old commit unreachable. GitHub
keeps the object addressable, so a stale reference still answers and fails only
where it counts: a fresh clone fetches reachable objects alone, so
software --materialize cannot check out a pin that was rebased away, and the
gate dies two steps before the build it exists to verify. Six pins drifted this
way and the reproducible-build lane stayed red for a day.
- Re-pin in the same session as the rebase. A force push to any branch
recorded in
.host-softwareobliges an update to thatpinorworktreeline. Push it with the rebase rather than leaving it for later. - Reachability is the test, not resolvability. The API resolves an
unreachable object, so a successful lookup proves nothing. Compare against
git ls-remote --heads, which lists only what a clone will fetch. - A record that cannot be re-pinned is superseded, not edited. A
call/decision or aMEMORY.mdentry naming a rewritten SHA earns a new entry that points back, under the append-only rule.
Project specifics: udpspeeder-simd
The rules above are the inherited spine. The facts below are this project's own, recorded so an agent does not have to re-derive them from the code.
- What it is. A Forward Error Correction UDP tunnel that improves a high-latency lossy link with Reed-Solomon redundancy. SIMD-accelerated. Forked from UDPspeeder.
- Language and build. C++. Build it with
make(the flat makefile) or with CMake (cmake -B build && cmake --build build). The software is C++ only. - Style.
.clang-formatis authoritative; match the surrounding file exactly (braces, indentation, naming) rather than restyling. - Canonical branch.
main. The audited worktree issoftware/udpspeeder-simd/main/, pinned in.host-software. - License. The software is MIT (its
LICENSE.mdlives in the worktree). This governance shell is Unlicense. Keep the two separate. - Reproducibility. Brought under the methodology, not initiated by it: the
stanza records a source
pinwith nodeployorartifact, so no reproducible build is claimed yet. Add a build recipe and arepro-exempt = call/NNNN(or a realartifact) before shipping a binary through the host. - Lanes. The component carries both spec kinds:
dns_lease_mgr.alliumandsocket_marks.allium(with obligations manifests) runcheck+analyse+planin its own CI, and the TLA/TLC suite lives underspec/. New behavioural work on this component adds or extends an allium spec with its obligations; the lanes are wired and gate release.
Project specifics: the packages lane
A second software component, packages, is embedded as a Where-room lane
alongside udpspeeder-simd, recorded in .host-software.
- What it is. A fork of the OpenWrt packages feed (
openwrt/packages): build recipes (Makefiles), patches, and options for OpenWrt applications and libraries. Makefile and shell, with some C. Layered on an OpenWrt buildroot via the feed system. - Canonical branch.
master. The audited worktree issoftware/packages/master/, pinned in.host-software. - License. The feed is GPL-2.0 (its own
LICENSElives in the worktree). This governance shell is Unlicense. Keep the two separate. - Reproducibility. Migrated, not initiated here: a source
pinonmasterwith nodeployorartifact, so no reproducible build is claimed. It is a build-recipe feed, not a built artifact. - No Claude co-author trailers. Every commit made in the packages worktree
omits the
Co-Authored-By: Claude ...trailer, so the feed stays upstream-clean foropenwrt/packages. This overrides the default trailer behaviour for the packages component only; host-repo commits keep it. Seecall/0003.
The operating manual is AGENTS.md. This file is a pointer, kept so tools that look for CLAUDE.md find the manual.
Using udpspeeder-simd on an OpenWrt release
The udpspeeder-simd package is submitted to the OpenWrt packages feed on the
development branch (master). OpenWrt policy is that release branches
(openwrt-XX.YY) take only security and bug fixes, not new packages, so
udpspeeder-simd is not backported to the release feeds. A developer or power
user on any current release can self-apply it with either route below.
Both routes reuse the package Makefile from the fork, which pins the source to a
fixed commit, so the build is reproducible on any release that has the shared
libraries the package depends on (libstdcpp, librt, libatomic), which every
current release provides.
Route 1: build with the release SDK
The SDK is the smallest option and needs no full checkout of the buildroot. Pick the release and the target that match the router, then build the package and copy the result to the device.
REL=24.10.0
TARGET=ath79/generic # your router's target/subtarget
wget "https://downloads.openwrt.org/releases/$REL/targets/$TARGET/openwrt-sdk-"*.tar.zst
tar --zstd -xf openwrt-sdk-*.tar.zst
cd openwrt-sdk-*
# Add udpspeeder-simd as a custom feed, from the fork's PR branch:
echo "src-git udpspeedersimd https://github.com/connollydavid/packages.git;udpspeeder-simd" >> feeds.conf.default
./scripts/feeds update udpspeedersimd
./scripts/feeds install udpspeeder-simd
make defconfig
make package/udpspeeder-simd/compile V=s
# The package lands in bin/packages/<arch>/udpspeedersimd/
Copy the resulting package to the router and install it with the release's package
manager: opkg install ./udpspeeder-simd_*.ipk where the release uses opkg, or
apk add ./udpspeeder-simd-*.apk where it ships apk.
Route 2: add the feed to a full buildroot
A user who already builds firmware from the buildroot adds the same custom feed,
selects the package in menuconfig, and builds it into the image.
# In your OpenWrt buildroot checked out on the release branch:
echo "src-git udpspeedersimd https://github.com/connollydavid/packages.git;udpspeeder-simd" >> feeds.conf.default
./scripts/feeds update udpspeedersimd
./scripts/feeds install udpspeeder-simd
make menuconfig # Network -> udpspeeder-simd, set to <M> or <*>
make package/udpspeeder-simd/compile V=s
Notes
- The package installs at
/usr/bin/udpspeeder-simdwith its own config and init script, so it coexists with the stockudpspeederpackage. Neither replaces the other. - To pin a specific version, edit
PKG_SOURCE_VERSIONin the package Makefile to the commit you want, and refreshPKG_MIRROR_HASH. - Once the master PR merges, the package is available from the development feed directly, and this custom-feed step is only needed for a release that predates the merge.
The active goal
plan/0004-patch-release-and-feed-refresh: The v1.
Orient with: host-lifecycle goal show .
MIGRATION.md: the process moved to the host repo
How to bring an existing repo under this methodology, and how to upgrade one that adopted an earlier revision, now lives as a single instruction file in its own repo:
https://github.com/connollydavid/host
Point an agent or a patient human at that URL and follow it. The host file owns
the adopt / migrate / upgrade procedure.
This template owns the techniques that procedure installs (the AGENTS.md
spine, the room scaffold, the tool pins) and the revision-keyed upgrade
ledger, UPGRADING.md. The procedure is stable and lives in one place; the
ledger changes with the techniques that generate it, so it stays here with them.
Structure
An agentic project (e.g. agentic-acme) is the externalized thought about the
work; the software under development is the action, hosted beneath it. Its
rooms map to the five W's.
| W | room | holds |
|---|---|---|
| Who | cast/ | personas (Powell, Keenan & McDaid 2007), examples Mara + Wren |
| What | <software>/ (with the code) | behavioural (.allium) + temporal (.tla) specs, verified in the software's CI; the host plan/ references them |
| When | plan/ | the milestone index and folders |
| Where | <software>/ | the hosted software, a bare store with worktrees; you add it |
| Why | call/ | decisions about the software (MADR; see call/0000); methodology lives in the spine, not here |
| How | AGENTS.md + tools/ | the operating manual and the verification lanes |
tools/ are referenced submodules, each under its own license; we orchestrate
and wrap, never patch:
tools/host-lint(Unlicense): hygiene / anti-slop; checks names againsthost-grammar.tools/host-lifecycle(Unlicense): token-free scaffolder/validator; generates names fromhost-grammar, so what it emits is exactly whathost-lintaccepts.tools/allium(MIT, JUXT): requirements + property-based testing.tools/specula(Apache-2.0): timing and concurrency via TLA+.
(host-grammar, the shared naming/numbering rules crate, is a build dependency of host-lint and host-lifecycle, not a host submodule.)
A lane is mandatory once a spec of its kind exists (RFC-2119 MUST; see AGENTS.md): a .allium requires tools/allium + its skills + a check/analyse/plan CI lane with the obligations discharged by tests; a .tla requires tools/specula + a TLC lane. Adopting a lane is optional; ignoring a present spec's lane is a defect.
.claude/skills/ are symlinks into those submodules' skills (reference, not
copy). They are generated, not tracked: link-skills.sh creates a link for each
materialized tool (skipping uninitialized submodules), because a tracked symlink
into an uninitialized tool dangles and trips any tree-walking tool.
Run it after git submodule update --init. Tool outputs are
project-owned. host-lifecycle ships one skill per lifecycle phase (classify,
adopt, embed, remap, verify, publish, upgrade, release), enumerated once in the
tool-readable lifecycle.manifest; unlike a lane, the lifecycle is driven by the
tool, and the rule is every phase emits a receipt (done/skip/n-a in
.host-receipts), not "every phase runs". A phase with no receipt is a
software --check HAZARD (AGENTS.md).
The Where room is the software under test, one or more components, each
embedded as a bare store with worktrees under software/<name>/: the shared
object store is software/<name>/.bare, with a .git gitdir-link file beside
it, and each worktree is keyed by branch at
software/<name>/<branch>/ (the branch keeps its slashes, so feature/login
nests). The canonical worktree (the audited state, where CI runs) is the
component's recorded branch (default main) checked out at the pin; the rest are
parallel lines, one per agent or live release branch. These trees are local and
gitignored (a single /software/ entry); the host commits a recipe (.host-software)
with one [software "<name>"] stanza per component (mirroring .gitmodules),
each recording the source URL, the pinned canonical SHA, the canonical branch, and
any parallel-line branches, which host-lifecycle software --materialize realises
and --check audits. Operate on a single component, or one branch worktree of it,
with --item <name>[@<branch>].
The recorded pin replaces a submodule gitlink as the
reproducibility anchor, so several branches stay materialized at once where a
single submodule tree could not. Software initiated under the methodology has
reproducible builds: the stanza also records the build recipe, the toolchain (a digest-pinned
container image, not a target triple; the natural misreading, and the cost is a
lane that never runs), and the deployed artifact hash, so host-lifecycle software --verify-build can rebuild
from the pin and prove the deployed binary; migrated software not yet reproducible
carries a repro-waiver = call/NNNN case decision (see AGENTS.md). A component that
ships static or self-contained binaries also records a deps-bundle = <url> <sha256>, a
pinned vendored-dependency bundle it downloads, verifies, and builds offline against under
--network none, so the build is hermetic (see AGENTS.md). A component that
ships on several platforms records one [build "<name>" "<platform>"] subsection per
platform (each a distinct toolchain/artifact of the same pin, with an attest-host
naming the OS that reproduces it); the flat single-build form stays valid for the
single-platform case.
To instantiate: clone, git submodule update --init (the tools), run
./link-skills.sh (regenerate the skill symlinks for the tools you initialized),
replace the cast/ examples with your own personas, and set up your software as a
bare store with worktrees (above). For bringing an existing repo under the
methodology instead, follow the host repo (github.com/connollydavid/host).
To publish docs with mdBook, run host-lifecycle book ., the canonical
publisher, so you do not hand-roll a generator that drops a room or re-derives the
src-scoping wrong. It writes a book.toml at the repo root scoped to a generated
mdBook/src/ (never src = ".", which would walk the tool submodules and the
un-materialized software worktree and trip over whatever is not present), with the
built HTML in mdBook/out/, and a SUMMARY.md in
lifecycle order: Cast (Who), then Plan (When), then Software/Where (the What specs live
with the code, read as a stub from .host-software), then Call (Why), then
Reference/AGENTS (How), then Memory. Then
host-lifecycle book --check . fails the build unless every room with source
renders a page, so a half-room site cannot ship. book.toml and the whole mdBook/
tree are generated output (gitignored), so a project keeps docs/ for its own
authored documentation; the reference Site workflow under .github/workflows/ runs
both before mdbook build, which still runs from the repo root.
A migrated or instantiated repo carries a .host stamp at its root
recording the template revision it adopted (template/revision/adopted),
written by host-lifecycle adopt. It is what a later upgrade diffs from. An
optional name line pins the published book's title, so host-lifecycle book
does not derive it from the checkout directory. An optional book-mount line
(default /) publishes the generated book under a sub-path of an existing site
instead of at its root: host-lifecycle book emits mdBook's site-url only for a
non-default mount, so a root-published book.toml stays byte-identical,
book --print-mount prints the normalized value, and the reference Site workflow
reads it from the tool to publish under the sub-path with the surrounding site kept.
The methodology lives in AGENTS.md. Read it first. The whole template is
released into the public domain (Unlicense); see README.md for provenance.
UPGRADING.md: the version-to-version upgrade ledger
Adopting the methodology records a template revision in .host. The
template then moves on, and an adopted repo must upgrade across the revision
span. The upgrade re-applies spine doc changes and the structural migrations the span
introduced (a re-embedding of the software, a tool bump). A git diff of the
template shows the prose; it does not say "convert the submodule" or "untrack a
symlink". This ledger does.
Apply every entry below whose revision is newer than your stamp.
host-lifecycle upgrade <dir> prints exactly those, decided by git ancestry
against this template, so same-day revisions order correctly. Fetch the template
to the target revision first; then apply the list and re-stamp. Each entry is
keyed by the template revision at which its action became required.
What a verify condition must test
An entry's verify is re-run twice over: by upgrade --record when the entry is
applied, and by software --check on every gate run thereafter. It is a standing claim
about the adopter's tree, not a check of the upgrade procedure.
Every entry added from here on obeys four rules.
- Test the adopter's side: their tree, their recipe, or their running binary. Never
a file under
host-template/:upgraderequires the template fetched at the target revision before it will run, so such a condition is a post-condition of the command's own precondition. It can neither refuse a false record nor detect a revert. - Test what the tool guarantees, not what the entry is about. Build a tree that SHOULD fail the condition and confirm it fails. A condition stricter than its own action leaves a correct adopter permanently unable to record, with no remedy.
- One command, no shell operators. Conditions run through
sh -con POSIX andcmd /Con Windows; a pipe, a!, or agrepdoes not survive the second. Prefer a mode that answers for itself, such ashost-lifecycle capability <name>. - Accept a tree the entry's own gate would redden. The condition asks whether the entry was applied, never whether the project is clean. Requiring clean wedges an adopter whose one offending line sits in a record they must not rewrite.
Entries written before this rule mostly grep host-template/ and are weak in the sense
of rule 1. They are not amended. An entry is a contract with claims already recorded
against it in adopters' .host-receipts, and tightening one retroactively can convert a
correctly applied upgrade into a standing HAZARD on a tree its owner cannot fix. Where
such an entry's guarantee genuinely needs checking, check it from a NEW entry that names
the old one in depends. This header is the exception to the file's append-only rule,
because no recorded claim re-checks it: amend the header, never an entry.
[upgrade "8c28e33"]
title = Software is a bare store with worktrees (call/0004)
action = Convert the embedded gitlink submodule to a bare store + worktrees (see the host repo, converting an existing submodule): preserve the pin, de-register the gitlink, write .host-software, gitignore the trees, then host-lifecycle software --materialize.
requires = host-lifecycle v0.3.0
[upgrade "325f2cf"]
title = Worktree-absence coherence (call/0005)
action = Untrack artifacts that depend on the worktree (skill symlinks into the software path); gitignore them and recreate after materialize. Keep an un-materialized CI job green. host-lifecycle software --check must report no HAZARD.
requires = host-lifecycle v0.3.1
[upgrade "71d12a8"]
title = Coherence generalized to tool submodules (call/0005)
action = Re-run host-lifecycle software --check (now flags any tracked symlink whose target is not tracked here, not just software-worktree paths). Untrack any flagged tool-skill symlinks and generate them instead (the link-skills.sh pattern); keep them gitignored.
requires = host-lifecycle v0.4.1
[upgrade "bbbfdc3"]
title = Reserve agentic-host for the meta repo; stamp is .host, scaffold is host-template
action = Rename your .agentic-host stamp to .host. Re-point your template-agentic-host submodule and its URL to host-template. A repo that adopts the methodology is "an agentic project" (e.g. agentic-acme); agentic-host now names only the meta repo.
requires = host-lifecycle v0.5.0
[upgrade "7ae93cd"]
title = Publish via host-lifecycle book (the canonical doc-site publisher)
action = Replace any hand-rolled mdBook generator/SUMMARY with host-lifecycle book .; it writes book.toml (src = "docs", never ".") + docs/ in lifecycle order, renders specs, and emits a Where stub from .host-software. Run host-lifecycle book . && host-lifecycle book --check . before mdbook build (see .github/workflows/site.yml); gitignore the generated book.toml/docs/.
requires = host-lifecycle v0.6.1
[upgrade "6db01f3"]
title = Anti-ouroboros: call/ is for the software, methodology lives in the spine
action = The methodology is owned by the spine (copy-at-version), not your call/. In a single dedicated commit, set Status: superseded by the spine on every accepted call/ decision that merely restates a methodology rule now settled upstream (leave the file in place, since MADR records are immutable). Add a Scope: header to each remaining accepted decision. Do not treat any host/management repo's top-level instance rooms as normative. host-lifecycle validate <call-dir> now fails an accepted decision missing Scope: or declaring Scope: methodology.
requires = host-lifecycle v0.7.0
[upgrade "07025a7"]
title = book publisher v0.7.1: nested specs + retired-decision Archive
action = Bump your pinned host-lifecycle book revision to v0.7.1. Two rendering changes follow on the next build: specs nested in spec/<topic>/ now render (previously dropped), and decisions whose MADR Status: is superseded/deprecated/rejected move into a trailing "Archive / Record" section (banner + nav-label suffix) instead of shipping as current chapters. The record signal is Status: only; .host-lintignore does not affect the book.
requires = host-lifecycle v0.7.1
[upgrade "e3b174d"]
title = Reproducible builds are the production anchor
action = Record build provenance in .host-software per component: build + toolchain (the deterministic recipe), deploy (which line ships), and artifact = <worktree-path> <sha256>. Add a CI job that runs host-lifecycle software --verify-build (rebuild from the pin; fail unless the artifact reproduces); see the reference .github/workflows/reproducible-build.yml. Software initiated under the methodology must reproduce. Pre-existing software not yet reproducible may carry repro-exempt = call/NNNN citing a software-scoped case decision; the exemption is retired as it converges and is never available to greenfield software.
requires = host-lifecycle v0.8.0
[upgrade "c137567"]
title = Per-platform builds for multi-platform software
action = For a component whose one source pin ships on several platforms, replace the flat single-build fields with one [build "<name>" "<platform>"] subsection per platform under its [software "<name>"] stanza, each with its own build/toolchain/artifact/deploy (and optional repro-exempt) plus an attest-host naming the OS (linux/windows/macos) that reproduces it. host-lifecycle software --check/--verify-build then attest each build only on its attest-host, skipping foreign-host builds rather than failing. Single-platform components need no change: the flat form stays valid.
requires = host-lifecycle v0.9.0
independent = true
[upgrade "d3dc5ed"]
title = --check artifact mismatch is a note, not a failure
action = Bump your pinned host-lifecycle revision to v0.9.1. software --check no longer hard-fails when a present artifact's hash differs from the recorded canonical hash (a local-toolchain build legitimately differs); it prints a note instead, the way --install-hooks already does. A match still reports verified; --verify-build (the container/CI lane) remains the reproducibility proof. No recipe change is required; this only removes a dev-box false failure.
requires = host-lifecycle v0.9.1
independent = true
[upgrade "b6232a5"]
title = Specs live with the software, not the host plan tree
action = Move any behaviour (.allium) or timing (.tla) specs out of the host's plan/<milestone>/spec/ and into the software repo, beside the code they constrain. Add the verification lane to the software's CI, not the host's: allium gated with both allium check and allium analyse (install allium-cli@3.4.2; both exit non-zero on any error or warning), and specula/TLC (tla2tools v1.8.0 on a Temurin 21 JDK). Remove the host's spec copies and its specula workflow; leave a forward note in the affected milestone. The host plan/<milestone>/ now references a spec by path and software pin rather than containing it.
requires = host-lifecycle v0.9.1
[upgrade "c771d60"]
title = Verification lanes are mandatory when a spec of their kind exists
action = Wire the lane tools you use as submodules and generate their skills (gitignored) with link-skills.sh: tools/allium (+ its elicit/distill/tend/weed/propagate skills) for any .allium, tools/specula for any .tla. Author and maintain .allium specs THROUGH the skills, not by hand. In the software repo's CI, gate each .allium with allium check + allium analyse + allium plan (install allium-cli@3.4.2; both check and analyse exit non-zero on any error or warning) and discharge the plan test obligations with the suite; TLC-check each .tla (tla2tools v1.8.0 on Temurin 21). The lane is conditional (TLA+ stays optional until a .tla exists, allium until a .allium exists), but a spec present without its full lane is a defect, not a choice. Do not treat the lanes as reference decoration.
requires = host-lifecycle v0.9.1
depends = b6232a5
[upgrade "b8c54fc"]
title = The spec-lane MUST is enforced by software --check
action = Bump your pinned host-lifecycle to v0.10.0. host-lifecycle software --check now raises a HAZARD when a materialized component carries a .allium spec with no CI workflow running allium check + allium analyse, or a .tla with no TLC lane (tlc2.TLC/tla2tools). Wire the missing lane (per the previous entry) so --check is clean; an un-materialized worktree is skipped.
requires = host-lifecycle v0.10.0
depends = c771d60
[upgrade "821a216"]
title = Allium plan obligations must be dispositioned per component
action = For each .allium, add a sibling <spec>.obligations manifest that dispositions every obligation allium plan derives, one of test:<name> (a named test discharges it), structural (the check/analyse lane covers it), or waived: <reason>. Run host-lifecycle obligations <spec> --tests <dir> in the software's CI (it fails on any undispositioned/stale obligation or absent test ref). Bump host-lifecycle to v0.11.1, where software --check also HAZARDs a .allium with no .obligations manifest.
requires = host-lifecycle v0.11.1
depends = b6232a5 c771d60
[upgrade "f62d766"] title = Lifecycle phases are an unconditional MUST, driven by host-lifecycle skills action = Bump tools/host-lifecycle and run link-skills.sh so the phase skills (classify, adopt, embed, remap, verify, publish, upgrade) appear under .claude/skills/ alongside the allium/specula skills. Operate the methodology through these phases and their commands, never ad-hoc; the phases cover scaffolding, embedding, migration, verification, publishing, and upgrading. Unlike a verification lane, this is unconditional: there is no opt-out, and hand-operating any phase is a defect. requires = host-lifecycle v0.11.1 independent = true
[upgrade "0e83e3f"]
title = Tag every release (a version bump MUST carry a matching vX.Y.Z tag)
action = Audit your tools and software for version bumps that were never tagged (git tag vs the manifest version); back-fill an annotated vX.Y.Z tag at each bump commit and push it. From now on, every version bump is committed with its matching tag, pushed alongside; the tag is the release a v* CI workflow builds. Do not re-pin .host-software or a tool pointer to a version-bumped commit that has no matching tag.
requires = host-lifecycle v0.11.1
independent = true
[upgrade "ae1e688"]
title = Never adopt a software repository in place
action = Bump your pinned host-lifecycle to v0.12.0 and re-run the classify phase as the first step of any adoption. host-lifecycle classify <dir> now refuses (exits non-zero, prints the embedding steps) when the target is itself a software repository (a root build manifest (Cargo.toml, package.json, go.mod, pyproject.toml, …) with no .host stamp and no .host-software recipe) instead of printing a case letter. A host is a separate meta-repo; the software is embedded as its Where room. If you previously adopted a methodology host directly on top of a software repo, split them: move the code into a bare store with worktrees recorded in the host's .host-software, so the host root carries only the rooms and config.
requires = host-lifecycle v0.12.0
independent = true
[upgrade "7de7cb1"]
title = Materialized worktrees must live under the host root
action = Bump your pinned host-lifecycle to v0.13.0. Audit .host-software for any worktree whose path escapes the host root (an absolute or ..-climbing worktrees/worktree entry, or a Where-room worktree materialized at a disjoint external path with no in-structure handle). Bring each under the root: for a store that must live off-tree (another filesystem or platform), record it on the parallel line as worktree = <dir> <branch> <pin> store=<path> [host=<os>] and re-run software --materialize, which realises the store at <path> and the in-tree <dir> as a symlink/junction to it. software --check now HAZARDs an escaping path and a store= line whose in-tree handle is missing or does not resolve to the store; host= gates a line to one OS so a foreign-OS CI skips it rather than failing.
requires = host-lifecycle v0.13.0
independent = true
[upgrade "3f7c065"]
title = Honest partial upgrades: the applied-set stamp model
action = Bump your pinned host-lifecycle to v0.14.0. The .host stamp now records what is applied as a baseline ledger entry (every entry at or before its position in this file counts applied) plus an optional applied set of out-of-order entries, keyed by ledger position, never git ancestry. Your first host-lifecycle upgrade migrates a legacy single-revision stamp once (derives the baseline; no manual edit). Thereafter: upgrade lists pending by position, upgrade --next prints the single next safe action, and you record an applied entry with host-lifecycle upgrade --record <id> (id, unambiguous prefix, or ledger ordinal), which validates the id, refuses if a depends is unapplied, runs the entry's verify post-condition or requires --unverified call/NNNN, and appends an append-only claim. Never hand-edit the stamp. A late independent entry may be cherry-applied without an earlier unrelated one (deferred entries stay pending and re-list, so a forgotten or premature record can never hide owed work); upgrade --advance compacts a contiguous applied run into the baseline; software --check re-checks every recorded claim.
requires = host-lifecycle v0.14.0
independent = true
[upgrade "4a98d92"]
title = Deeper verification rungs: Apalache (symbolic), TLAPS (proof), Kani (code-conformance)
action = Bump your pinned host-lifecycle to v0.15.0. The verification ladder gains opt-in deeper rungs above the bounded lanes, driven by a referenced tools/host-prove submodule (wire it and run link-skills.sh only if you use a rung; its apalache-symbolic, tlaps-proof and kani-conformance skills turn each verifier into a one-line verdict). An obligation may now be dispositioned kani:<harness>, apalache:<inv> or tlaps:<theorem> instead of test:/structural/waived:, since a proof discharges it for all inputs/parameters; host-lifecycle obligations <spec> --prove <dir> validates that the named proof exists. Declaring a rung obliges its CI lane: software --check now HAZARDs an obligation that declares kani: with no cargo kani lane, apalache: with no apalache-mc lane, or tlaps: with no tlapm lane. Nothing is required until you declare a rung, and bare .tla/crate presence never activates one. Route a parametric or unbounded .tla invariant to Apalache/TLAPS, and a code-conformance claim to your language's verifier (Rust uses Kani); prefer byte/char-level Kani targets (str::split/Vec blow CBMC up). Verifiers install from official prebuilt binaries pinned by version + SHA256; no Docker.
requires = host-lifecycle v0.15.0
depends = b6232a5 c771d60
verify = host-lifecycle obligations 2>&1 | grep -q -- --prove
[upgrade "a22704e"]
title = Self-referential software is excluded from the hygiene lane, not bypassed
action = Bump your pinned host-lifecycle to v0.15.1 (it fixes the first-upgrade breakage: adopt now registers the host-template submodule, the missing-template error remediates, and the upgrade skill matches the applied-set model). If your software detects the patterns the hygiene lane flags (a linter, parser, validator, grammar tool), it embeds them in test fixtures, docs and sometimes source, the legitimate self-reference the git hook would block. Exclude that corpus through .host-lintignore (host-lint v0.4.1+ honors it in the per-file hook scan, not only the --all walk), validated file-by-file so no real tell hides among the examples; keep ordinary source scanned (reword an example comment rather than mute the file). Never --no-verify past the gate to land a fixture; that silently defeats the lane. Finally, keep the template's own tools/host-lifecycle pin at or above the maximum requires in this ledger, so the pinned tool can actually run the ledger it ships.
requires = host-lifecycle v0.15.1
independent = true
verify = grep -rqs "Self-referential software is excluded" host-template/CLAUDE.md
[upgrade "897ce0d"]
title = Sound discharge by re-derivation (call/0018) + the LEXICON provenance allowlist
action = Bump your pinned host-lifecycle to v0.18.1, host-lint to v0.6.0, and (if you run a deeper rung) host-prove to v0.2.0. A rung obligation is now discharged by RE-DERIVATION, not name-presence: host-lifecycle obligations <spec> --rederive <dir> re-runs each kani:/apalache:/tlaps: rung through host-prove in its recorded pinned toolchain and requires a PASS at the declared bound (AVAILABLE != DISCHARGED). The offline --prove check stays, honestly a name-presence lint. Add the cheap offline staleness signal by declaring inputs=<files> on a rung and recording <manifest>.digests with --rederive --record-digests; a later offline run reports STALE if the proven inputs drift without a fresh re-derivation. Enforcement is project-pluggable (a required check, any CI, a pre-push hook, or the operator's verify phase): no keys, no CI lock-in; it generalizes the reproducible-build re-derivation so that proofs are re-derived the way artifacts are. For the hygiene lane, declare legitimate tell-shaped tokens in a LEXICON (each the full contextual phrase, masked; a tracker reference carries its URL); host-lifecycle adopt seeds a comment-only scaffold. Because a sound escape now exists, the identifier/reference tier may escalate warn to flag via a committed host-lint: strict directive, and host-lint: jira-key PROJ opts a project key into citation-gating. Curate with host-lint lexicon add (it refuses a master key, a laundered tell, or an un-cited reference); host-lint lexicon --check-urls re-derives URL liveness in a network lane.
requires = host-lifecycle v0.18.1
depends = 4a98d92
verify = grep -rqs "discharged by re-derivation" host-template/CLAUDE.md
[upgrade "da000aa"]
title = Box irreducible literal citations in a host-lint:ignore fence
action = Bump your pinned host-lint to v0.7.0. The hygiene lane gains a per-block escape for a document that must reproduce a tell verbatim: a fenced code block tagged host-lint:ignore (markdown only). Its lines are skipped by the naming scan while the rest of the file stays linted, and a regular code block or inline backticks stay scanned so a tell cannot be laundered by quoting it. Reserve it for an irreducible literal citation (an old-name remap table, a frozen dated review citing another document's numbered steps); reword a pedagogical example or a document's own ordinal label into content, and path-exclude (.host-lintignore) only the immutable record (the append-only memory log, dated review artifacts) and the self-referential corpus. This loosens, never widens, the gate: it replaces blanket path-exclusion of editable docs with in-file, per-block, still-audited boxing.
requires = host-lifecycle v0.18.1
independent = true
verify = grep -rqs "boxed in the file, not path-excluded" host-template/CLAUDE.md
[upgrade "617e420"]
title = Lifecycle manifest, and every phase emits a receipt
action = Bump your pinned host-lifecycle to the v0.18.1 build that ships manifest/receipt/release. The lifecycle phases (their order, modality, command and the evidence each carries) now live once in a tool-readable lifecycle.manifest at the template root (the CLAUDE.md/STRUCTURE.md prose point at it instead of re-typing the order), and a release phase is added (the strict, tool-carried release: verify, build in the recorded toolchain, re-derive the artifact hash, re-pin, tag, receipt). The rule changes from "every phase runs, no opt-out" to every phase emits a receipt: host-lifecycle receipt --record <phase> [--component <c>] --disposition done|skip writes an append-only .host-receipts, and host-lifecycle software --check now HAZARDs any manifest phase with no receipt, re-verifying each done by the manifest's closed recheck = (never the receipt's own say-so). Modality is first-class: a conditional-on-Where phase is tool-computed n-a where the project has no Where room, a recurring-per-component phase (embed, release) is receipted once per component, and a protected core (verify, skippable = false) refuses a skip. Back-fill a receipt for each phase your project has already done; host-lifecycle manifest <path> prints the whole lifecycle at a glance.
requires = host-lifecycle v0.18.1
independent = true
verify = grep -rqs "every phase emits a receipt" host-template/CLAUDE.md
[upgrade "0cd6b0a"]
title = The Where room uses the nested software/software/<name>/: the bare store at software/<name>/.git and each worktree keyed by branch at software/<name>/<branch>/ (the canonical worktree is the recorded branch, default main, checked out at the pin), replacing the old root-scattered <name>/, <name>.git/, <name>.<line>/. Migrate, in order: (1) replace the per-component .gitignore triplets with a single /software/ entry; (2) remove the old root-scattered worktrees and bare stores (commit or stash any uncommitted parallel-worktree work first, since re-materialize is destructive); (3) run host-lifecycle software --materialize . to realise the new tree; (4) re-run link-skills.sh and re-point any software skill link at software/<name>/<branch>/; then host-lifecycle software --check . must be clean. The worktree = recipe line drops its leading <dir> token (the path now derives from the branch: worktree = <branch> <pin> [store=<path>] [host=<os>]), worktrees = is a branch list, and an optional branch = sets a non-main canonical branch. Operate on one component (or one branch worktree) with software --item <name>[@<branch>]. software --check also HAZARDs a dangling generated skill link now. A development host that authors a host-* tool embeds it as its own Where component rather than referencing its own source as a submodule (the reference-don't-vendor carve-out).
requires = host-lifecycle v0.19.0
independent = true
verify = grep -rqs "the producer of a tool embeds it" host-template/CLAUDE.md
[upgrade "950fbd6"]
title = Prose hygiene is an ongoing hygiene-lane rule with a receipt
action = Treat the prose audit as a STANDING part of the hygiene lane, not a one-time pass. host-lint --prose (host-lint v0.7.0+) flags the LLM-slop prose tropes that tropes.fyi names (decoration dashes and arrows, tricolons, hypophora, and the rest) in authored docs. Clean every authored doc to ZERO prose tropes (reword to plain prose, the same bar as naming tells), then wire it into the receipts mechanism: the verify phase applies host-lint --prose and generates a receipt, and host-lifecycle software --check re-verifies that receipt by re-running --prose (add it to the verify phase recheck = in lifecycle.manifest), re-opening any regressed doc as a HAZARD. MEMORY.md is the agent's append-only working memory and is excepted from both the naming and prose audits via .host-lintignore, never rewritten.
requires = host-lifecycle v0.19.0
independent = true
verify = grep -rqs "Prose hygiene is the same lane" host-template/CLAUDE.md
[upgrade "ecce498"]
title = Hermetic builds via a pinned dependency bundle
action = Bump your pinned host-lifecycle to the v0.20.0 build that ships the deps-bundle recipe field and the offline --network none build. A component that ships static or self-contained release binaries MUST be able to reproduce them offline from pinned inputs, never from a network fetch at build time. Vendor the dependency layer once and publish it as a reusable, versioned, hash-pinned downloadable release bundle (the pattern pgs-release uses for its prebuilt sysroot), then record it per component as deps-bundle = <url> <sha256> in .host-software. host-lifecycle software --verify-build and release perform the one controlled, pinned download, verify the sha (provenance), stage the vendored sources, and build under --network none (egress). The producer commits a deps-bundle.lock as the single source of truth, and software --check HAZARDs a deps-bundle pin that has drifted from it. A component that genuinely cannot vendor offline (a network-fetching build.rs, a non-Rust toolchain) records the case in repro-waiver = call/NNNN, whose value cites a software-scoped decision. Where offline vendoring is feasible, that exemption does not apply. (This clause originally named a hermetic-exempt key that no release parsed; see the retirement entry at the end of this file.)
requires = host-lifecycle v0.20.0
independent = true
verify = grep -rqs "reproduce them offline from pinned inputs" host-template/CLAUDE.md
[upgrade "27d815b"]
title = The hygiene grammar grows by reflective practice
action = Bump your pinned host-lint to v0.9.0, which flags a positional reference to a milestone checklist item (the "box N" / "boxes N-M" / "steps N-M" shape), the same ordinal-by-position tell as a numbered name. Adopt the living-grammar doctrine: the shared tell corpus is incomplete and grows by reflective practice. Discovery is mechanical-first, a sweep of history and recent work for a recurring shape the lane misses, prompted at the verify gate before a milestone closes and at adoption, with the agent assisting rather than leading. The operator validates whether a surfaced shape is a genuine tell or legitimate domain vocabulary, by one test: is the shape a property of how models segment work, or of this project's own domain? A confirmed tell is proposed upstream to the shared grammar the lane consumes (a naming tell to host-lint, a prose trope to host-grammar), gained on the next bump; a legitimate tell-shaped token stays in the per-project LEXICON; the project that finds a tell does not edit the shared source itself. Reword by default; box or declare an irreducible citation; declare the numeral-free contextual prefix for a genuine quantity; reserve a graduation for the residue. A later grammar bump that flags a live doc is reworded, and a frozen record is boxed.
requires = host-lifecycle v0.20.0
independent = true
verify = grep -rqs "grows by reflective practice" host-template/CLAUDE.md
[upgrade "e280a8d"]
title = The verify recheck re-runs the prose audit, so the gate enforces prose hygiene
action = Bump your pinned host-lifecycle to v0.22.0, which adds host-lifecycle prose <dir>, host-lint's --docs prose audit run in-process so the gate needs no host-lint on PATH (a development host whose host-lint is embedded Where software still runs it). The verify phase recheck = in lifecycle.manifest now chains host-lifecycle prose . after validate, so software --check re-verifies the verify receipt by re-running the prose audit and re-opens any doc that regressed to slop as a HAZARD. This enforces the standing prose-hygiene rule the spine already states; before it the recheck ran only validate, so a prose regression slipped past the gate.
requires = host-lifecycle v0.22.0
independent = true
verify = grep -rqs "host-lifecycle prose" host-template/lifecycle.manifest
[upgrade "ac32d1c"]
title = Re-home the receipts family, tool-driven
action = Bump your pinned host-lifecycle to v0.23.0 and run host-lifecycle migrate-receipts . (one command, never hand-edited). It moves the applied-set out of .host into .host-receipts and splits the operational receipts (classify, embed, remap, verify, publish, release) out to .host-lifecycle-receipts; adopt and upgrade stay in .host-receipts. The binary auto-migrates on read, so the gate stays green across the boundary and an un-migrated project is still read correctly. A receipt is methodology-version (.host-receipts) only for adopt and upgrade; every other phase host-lifecycle runs is operational (.host-lifecycle-receipts). The old-layout reader is permanent backward compatibility, not a one-time shim.
requires = host-lifecycle v0.23.0
independent = true
verify = test -f .host-lifecycle-receipts
[upgrade "d5a0034"]
title = Reflective practice grows in two arms: gather forward, reconcile backward
action = Bump your pinned host-lifecycle to v0.24.2, which adds host-lifecycle reconcile <dir> and wires the reconcile step into the upgrade/adopt/verify skills. Adopt the widened doctrine: an agent perceives neither the register it emits nor the restatements its own change stales, so reflective practice runs in two arms under one principle. The first arm, gather (unchanged), is forward: emergent tells in the corpus, a confirmed tell graduates upstream, cadence-driven. The second arm, reconcile (new), is backward: the project's own restatements of methodology (its room map, tool family, verification model, recorded Where layout), a confirmed drift fixed locally and never propagated. Prefer pointing at the spine over restating it; a restatement that must stay carries an inline <!-- host-reconcile: KIND --> annotation declaring an assertion host-lifecycle reconcile checks against a source of truth (the host-* family list and the verification-ladder drivers the lifecycle manifest records, the fixed software/ and plan/ layout), with kinds family, verification, where-root, spec-path. The trigger is conditional and host-aware: a restates = field on an UPGRADING entry marks a drift-capable move so the upgrade skill re-reads the named kinds, adoption runs the full reconcile once, and for a development host that authors its own spine changes the verify gate is the binding trigger (the verify recheck now chains host-lifecycle reconcile .). Disposition is three-way (reword a live restatement, box a frozen citation, forward-correct an immutable record). A sibling check: host-lifecycle validate now HAZARDs an accepted call/ decision whose Scope: names host-template, since its rule is spine-resident and belongs superseded there.
requires = host-lifecycle v0.24.2
independent = true
verify = grep -rqs "Two arms run under this one principle" host-template/CLAUDE.md
[upgrade "7be692f"]
title = Reconcile evolves to concept-as-URI; the lifecycle manifest is phases-only
action = Bump your pinned host-lifecycle to v0.25.0 and move to this host-template revision together (a partial bump leaves the old manifest stanzas under the hardened manifest --check). The lifecycle manifest is now phases only; a project's own facts live in its .host-software. Define each methodology concept once at a {#id} anchor on a heading (for example ## Components {#components}) in a doc of your choice, and point at it elsewhere with [text](FILE#id); reconcile runs link-integrity, declared-anchor, and coverage over your docs. The concepts: components (your host-* tools, the [software] members of .host-software minus a single-file front door marked front-door = true if you have one), verifiers (your verification drivers, named on a drivers = ... line under a [verification] stanza you add to .host-software, for example a [verification] stanza whose line is drivers = host-lint allium specula host-prove), software-root (where your software lives, software/), and spec-home (where your specs live, with the software). Each home that lists a set must name the whole set; coverage flags an omission. Convert each surviving inline <!-- host-reconcile: KIND --> annotation by replacing its enumeration and comment with a single such link. You may migrate gradually: the inline annotations keep working, warned, until a later revision retires them. See the reconcile section in CLAUDE.md for the full rules.
requires = host-lifecycle v0.25.0
independent = true
verify = grep -rqs "rejects a project-fact stanza" host-template/CLAUDE.md
[upgrade "2229dbb"]
title = In-plan tasks are a receipted dependency graph
action = Bump your pinned host-lifecycle to v0.26.0 and move to this host-template revision together. Each entry under a milestone's ## Build sequence becomes a task: an anchored ### heading ending in {#anchor}, keyed plan/NNNN#anchor. A task declares its prerequisites with - depends: #anchor (or a cross-milestone plan/NNNN#anchor; omit the line for the previous task, the linear default), its check with - verify: <command> (mechanical) or - verify: attested <call/NNNN | operator>, and the files a mechanical verify covers with - inputs: <paths>. Record a receipt for each task with host-lifecycle tasks --record <plan/NNNN#anchor> --disposition done|skip (the tool reads the task's own verify/inputs, so you never re-type them); software --check then HAZARDs a task with no receipt, a done whose inputs drifted or whose citation does not resolve, a skip without a resolvable call/NNNN, and an orphan receipt whose task was renamed or removed. Declare only what must finish first; the tool derives what runs in parallel, and a coordinator parallelizes only resource-isolated workers. Migrate gradually: a plan with no anchored ### task is untouched. See the task-graph section in CLAUDE.md.
requires = host-lifecycle v0.26.0
independent = true
verify = grep -rqs "in-plan tasks are receipted nodes" host-template/CLAUDE.md
[upgrade "ba86125"]
title = The entrance check holds a self-contained document to the spine
action = Bump your pinned host-lifecycle to v0.29.0 and move to this host-template revision together. A document read out of context cannot point at a definition, so the entrance check holds it by coverage and generation, reconcile's standalone sibling. Declare one entrance, a global singleton, in an [entrance] stanza in .host-software naming the member it belongs to (set apart from components), the document within that member (default README.md), and the concepts it restates (true for every concept, or a named subset of phases, tools, stamp). host-lifecycle entrance --check then holds that document complete against the declared concepts. If you marked a single-file front door with the legacy front-door = true or entrance = true on its [software] member, replace it with an [entrance] stanza naming that member; the legacy marker is still accepted, warned, until a later revision retires it.
requires = host-lifecycle v0.29.0
verify = grep -rqs "entrance check is reconcile's standalone sibling" host-template/CLAUDE.md
[upgrade "de8a517"]
title = The legacy per-member entrance marker is retired
action = Bump your pinned host-lifecycle to v0.30.0 and move to this host-template revision together. The legacy per-member entrance marker is retired: a front-door = true or entrance = true on a [software] member is now a loud error, not silently accepted. Replace any such marker with an [entrance] stanza naming that member (the member, an optional document with default README.md, and restates); see the entrance section in CLAUDE.md. A project with no single-file entrance carries no such marker and needs no change.
requires = host-lifecycle v0.30.0
verify = grep -rqs "The legacy per-member marker is retired" host-template/CLAUDE.md
[upgrade "e068828"]
title = The generated book moves under mdBook/, freeing docs/
action = Bump your pinned host-lifecycle to v0.30.2 and move to this host-template revision together. host-lifecycle book now writes its generated mdBook source to mdBook/src/ and the built HTML to mdBook/out/, with book.toml kept at the repo root, so mdbook build still runs from the root. This frees docs/ for your own authored documentation. Update your .gitignore: replace the /docs/ and /book/ lines with a single /mdBook/ line, keeping /book.toml. Regenerate the site with host-lifecycle book ., then remove the stale generated docs/ and book/ trees, which held only generated output under the old layout (git clean -fd docs book reaches them once they are no longer ignored). If your .github/workflows/ publishes the site, point the publish step at mdBook/out in place of book. A project that has not yet published a site carries no generated docs/, so it needs only the gitignore and workflow change before it first runs book.
requires = host-lifecycle v0.30.2
independent = true
verify = grep -rqs "mdBook/src" host-template/STRUCTURE.md
[upgrade "6174996"]
title = A declared rung obliges a runnable re-deriver, not just a present CI lane
action = Bump your pinned host-lifecycle to v0.31.0 and move to this host-template revision together. software --check now HAZARDs a declared deeper rung (kani:/apalache:/tlaps:) whose shared re-deriver, host-prove, does not run, beside the existing no-CI-lane HAZARD, because a re-derivation that cannot run leaves the rung undischarged however complete the CI config reads. So install host-prove on PATH wherever the gate runs: your local setup and the CI that runs software --check (cargo install --git https://github.com/connollydavid/host-prove --rev <its pin>). A project that declares no deeper rung carries no host-prove requirement and needs no change. And earn the digest a rung records through host-lifecycle obligations <spec> --rederive <crate-root> --record-digests, which re-runs the proof and records only on a pass, in place of a hand edit, so a fresh digest stands for a passing re-derivation on the current inputs.
requires = host-lifecycle v0.31.0
independent = true
verify = grep -rqs "a re-deriver that runs" host-template/CLAUDE.md
[upgrade "46a1fd2"]
title = A verification lane reports clean only after it performs its check
action = Bump your pinned host-lifecycle to v0.32.0 and move to this host-template revision together. The obligation-discharge check now verifies an exercises=<symbol> link rather than only that a test: name resolves. Add to each behavioural obligation a link naming a function the discharging test drives, and run host-lifecycle obligations <spec> --tests <dir> --strict-discharge where the gate runs. The strict mode is opt-in, so a tool bump leaves your ladder green; the reject names the test and the symbol it is missing. Do not relabel a behavioural obligation structural to dodge it, and give every waived: a real reason. Separately, software --verify-build is now three-state: it prints its clean line only when a build was verified and none was UNVERIFIABLE, and it exits non-zero on an in-scope build it could not run (no container runtime, or no toolchain pin), so a runtime-less CI that relied on its exit 0 must gain a runtime or scope that build out. A project whose obligations are all structural carries no exercises= link and needs only the verify-build change.
requires = host-lifecycle v0.32.0
independent = true
verify = grep -rqs "reports clean only after it performs its check" host-template/CLAUDE.md
[upgrade "1682d62"]
title = A release reconciles every carried-template pin of a tool you release
action = For almost every project this entry is a no-op: a project that releases none of the host-* tools records it done and changes nothing, with no template pin to look for. It binds only where two facts about your own repository both hold: your repository releases a host-* tool of its own, and it carries host-template as a submodule whose pins include that tool. Where both hold, bump your pinned host-lifecycle to v0.36.0; from that release on, a release of that tool bumps every carried-template pin surface for it to the released commit, and host-lifecycle software --check HAZARDs a carried-template pin left behind.
requires = host-lifecycle v0.36.0
independent = true
verify = grep -rqs "re-pins the carried template" host-template/CLAUDE.md
[upgrade "7127dc4"]
title = The hosted bare store is .bare with a .git gitdir-link, not a bare repo named .git
action = Bump your pinned host-lifecycle to v0.36.0 and move to this host-template revision together. The materialisation layout changed (call/0039): a component's bare object store is now software/<name>/.bare with a .git file (gitdir: ./.bare) beside it. This layout supersedes the bare repo named software/<name>/.git. For each already-materialized component, re-run host-lifecycle software --materialize; it renames .git to .bare in place, writes the gitdir-link, and runs git worktree repair, so no fetch or teardown is needed and local state is preserved. A project with no materialized software needs no change.
requires = host-lifecycle v0.36.0
independent = true
verify = grep -rqs "gitdir-link" host-template/STRUCTURE.md
[upgrade "67d63e9"]
title = A band groups build-sequence tasks without an ordinal name
action = Bump your pinned host-lifecycle to v0.38.0 and move to this host-template revision together. The task graph gains a band: a ### heading under ## Build sequence marked with a single - band bullet is a content-named divider over the tasks that follow, not a task node. A band carries no receipt or edge and does not reset the linear default, so task-to-task chaining runs straight across it and ordering stays in the depends edges. Use it in place of an ordinal group name, which the milestone-naming rule forbids and the naming gate (host-lint v0.14.0) now blocks in both its numeric and its spelled form. An existing plan with no - band marker parses unchanged, so a project that groups nothing needs no change.
requires = host-lifecycle v0.38.0
independent = true
verify = grep -rqs "content-named divider" host-template/CLAUDE.md
[upgrade "962630c"]
title = The generated book can publish under a sub-path of an existing site
action = Bump your pinned host-lifecycle to v0.38.0 and move to this host-template revision together. An optional flat book-mount key in your .host stamp (default /) publishes the generated book under a sub-path of an existing site instead of at its root: host-lifecycle book emits mdBook's site-url only for a non-default mount, so a root-published book.toml stays byte-identical. Adopt the mount-aware reference Site workflow: it reads host-lifecycle book --print-mount from the tool and publishes under the sub-path with the surrounding site kept. A project that publishes its book at the site root sets no key and sees byte-identical output; it adopts the mount-aware workflow only so a later sub-path becomes a config change rather than a workflow rewrite.
requires = host-lifecycle v0.38.0
independent = true
verify = grep -rqs "book-mount" host-template/STRUCTURE.md
[upgrade "ff04a94"]
title = The scaffold-and-stamp primitive is scaffold; adopt becomes onboarding
action = Bump your pinned host-lifecycle to v0.39.0 and move to this host-template revision together. The scaffold-and-stamp primitive host-lifecycle adopt <dir> <revision> is renamed host-lifecycle scaffold <dir> <revision>, and the adopt verb becomes the three-route onboarding (init and adopt, with the host-init and host-adopt shims, call/0041). Migrate every script or skill that invokes adopt <dir> <revision> to scaffold <dir> <revision>, and set your lifecycle manifest's adopt phase command to host-lifecycle scaffold. The two-positional adopt <dir> <revision> form no longer forwards; it errors with guidance naming scaffold, because the onboarding grammar cannot safely distinguish it from a mistaken onboarding call that would write into the source. A project that never scripts the bare command reads the new onboarding doctrine and changes nothing else.
requires = host-lifecycle v0.39.0
independent = true
verify = grep -rqs "host-lifecycle scaffold" host-template/CLAUDE.md
[upgrade "32994e4"]
title = The two-tier memory store and the dream audit
action = Bump your pinned host-lifecycle to v0.41.0, which ships host-lifecycle dream and the MCP memory tools (memory_list/memory_read/memory_write/memory_consolidate on host-lifecycle mcp), and move to this host-template revision together. Adopt the two-tier memory doctrine: the repo MEMORY.md stays append-only (shared, committed, audited); the optional host-* per-user store at ~/.host-memory/<encoded-cwd>/ (markdown per entry, a MEMORY.md index, [[slug]] cross-references) is editable, local, and uncommitted. Run host-lifecycle dream . at the cadence the spine names (the start of a session that will rely on recall, and after a session that superseded a decision); it routes findings (an append suggestion for the repo tier, an edit suggestion for the per-user tier) and never writes, and --fix refuses the repo store (no class is auto-applied yet; the safe set grows one class at a time). Vendor harness memory stores are out of scope; an operator on a harness without the store carries only the repo tier and needs no structural change. Sync the memory section of your operating manual: a verbatim-copy adopter re-copies the spine section, a merged manual (a development host's) folds the two-tier note into its own memory rules.
requires = host-lifecycle v0.41.0
independent = true
verify = grep -rqs "The two-tier memory store" host-template/CLAUDE.md
[upgrade "514aaa2"]
title = The dream store model: the tier marker, finding confidence, and the exit split
action = Bump your pinned host-lifecycle to v0.42.0 and move to this host-template revision together. The dream audit gains the store model (agentic-host call/0045): detectors declare the store formats they fit, [[links]] resolve against the union of both memory tiers, findings carry a confidence (confirmed or review-prompt) with the exit split clean 0 / advisory-only 3 / any-confirmed 1, --json becomes an object (findings plus coverage; the bare-array shape is retired), and the per-user tier's in-use status becomes a tracked .host-memory-tier marker: dream stamps it when it first observes an initialized store on a machine (commit the stamp), and the operator retires it with dream --retire-marker, recorded as an appended MEMORY.md correction. Expect the day-one wall: a repo log with cross-store [[links]] and no marker reports them as confirmed dangling (exit 1) on the first post-upgrade run, by construction, not as a memory regression. The disposition fork: initialize and seed the per-user store where it is real (dream stamps the marker and the findings re-tier advisory), or retire intended-but-unrealized links by appended corrections. Dropping links merely to clear the wall is prohibited; run dream once on the store-carrying machine and commit the stamp before storeless checkouts or CI gate on the new exits. Room-touching findings become labelled review prompts whose lead remedy is a review note; the applied-receipts cross-check is owed as host-lifecycle#23. A project with no cross-store links and no per-user store sees only the new coverage lines and exit vocabulary.
requires = host-lifecycle v0.42.0
independent = true
verify = grep -rqs ".host-memory-tier" host-template/CLAUDE.md
[upgrade "e4ed590"]
title = The fresh clone is bootstrapped, its completeness is gated, and materialization is recorded
action = Bump your pinned host-lifecycle to v0.43.0 and move to this host-template revision together. Three capabilities land. host-lifecycle bootstrap <dir> runs the fresh-clone sequence your operating manual used to spell out as prose (submodules, materialize, skill links, hooks, the declared PATH re-deriver, then the gate), driven entirely by .host-software; a project that wants a one-command entrypoint adds a thin bootstrap.sh that seeds host-lifecycle at its recorded pin and delegates, and a project that installs a released host-lifecycle runs the subcommand directly. host-lifecycle software --verify-setup <dir> gates completeness: it reads the recipe and the live tree and hazards on every required local artifact that is absent, naming the command that installs it. software --materialize now appends an ungated [receipt "materialize" "<component>"] provenance line to .host-lifecycle-receipts and refreshes a gitignored .host-envhash fingerprint that host-lifecycle env --check reads (advisory, never a gate). Expect the day-one wall: --install-hooks now gates every materialized worktree, not the host repository alone, so your first --verify-setup hazards once per worktree; that is by construction, and one host-lifecycle software --install-hooks <dir> clears it. Read the clean verdict precisely: it covers what the recipe requires of THIS host, presence and currency rather than correctness. Do not read the materialize ledger as a complete record either: the pin gate never re-verifies it, and an aborted run leaves no line. A project with no materialized software sees no new hazard and needs only the doctrine.
requires = host-lifecycle v0.43.0
depends = 7127dc4
verify = grep -rqs "the completeness gate" host-template/CLAUDE.md
[upgrade "RETIRE-hermetic-exempt"]
title = The hermeticity escape hermetic-exempt is retired; the case is recorded with repro-waiver
action = Entry ecce498 told you that a component which cannot vendor offline "may carry hermetic-exempt = call/NNNN". No release of host-lifecycle ever parsed that key: a recipe carrying it is read as if the line were absent, so an adopter who wrote it has an exemption that never applied and a gate that stayed red. Run host-lifecycle migrate-recipe <dir>, which drops the line and names the reason; the case is recorded in repro-waiver = call/NNNN instead, citing the same decision. Hermeticity is a facet of reproducibility rather than a second property, so one key carries both and the two can no longer disagree. Nothing else changes. The property MUST stands: reproduce release binaries offline from pinned inputs. The gate invariant is also unchanged. A component recording a deps-bundle builds with no network. Its staged bundle hash matches the recorded one. A project that never wrote the key needs no action. Recorded as agentic-host call/0046.
requires = host-lifecycle v0.44.0
independent = true
verify = ! grep -Eqs '^[[:space:]]hermetic-exempt[[:space:]]=' .host-software
[upgrade "RENAME-repro-waiver"]
title = The reproducibility escape is repro-waiver, named for the citation it records
action = Run host-lifecycle migrate-recipe <dir>. It renames repro-exempt to repro-waiver in your .host-software, drops the hermetic-exempt line no release ever read, leaves every other line untouched, and is idempotent, so a second run reports nothing to do. Commit what it writes with this upgrade. The key records the name of a decision, so it is named for that record rather than for the state it excuses; the new spelling was settled by the same rotation-proof weak-agent probe that named bootstrap and --verify-setup. Both spellings parse, and the retired one reports itself on every read, so a recipe keeps working while you migrate and tells you it moved. One waiver carries two cases: a migrated build that does not reproduce byte for byte yet, and a component that cannot vendor its dependencies offline (the second folded in when the unimplemented hermeticity key was retired). A project with no waiver on any component renames nothing. Recorded as agentic-host call/0047; the retired spelling is removed at a later revision on its own entry.
requires = host-lifecycle v0.44.0
independent = true
verify = ! grep -Eqs '^[[:space:]]repro-exempt[[:space:]]=' .host-software
[upgrade "REFS-a-number-resolves"]
title = A number that names something resolves to it, and a bare issue number is not a reference
action = Bump your pinned host-lifecycle to v0.44.0 and adopt the reference discipline in the manual section "A number that names something resolves to it". host-lifecycle resolve <ref> [--markdown|--url] turns plan/NNNN, call/NNNN or plan/NNNN#anchor into a path, a link, or the forge URL; write the markdown form in an authored document so the published site renders a link rather than text that looks like one. A bare #N is refused rather than guessed at, because in a host repository most bare numbers name a component's issues while the origin remote is the host: write owner/repo#N, or component#N for a component your recipe or submodule list records, inside a link. host-lifecycle refs --check <dir> sweeps your authored markdown: a register reference pointing at nothing gates (exit 1), an issue number outside a link advises (exit 3), and a listed document that cannot be read gates, because a verdict over a corpus with a hole in it is a claim the run cannot make. Expect a wall on the day you turn it on. Every project of any age carries hundreds of bare numbers written before this rule existed, which is exactly why the issue half advises rather than blocks: a gate that reddens a tree on the day it lands teaches an operator to bypass it. Remediate live documents as you touch them. There is no fix flag and the refusal says so, because only the author knows which tracker a number meant. Your record layer is excluded and stays excluded: MEMORY.md by construction whether or not you have written an exclusion list, and whatever .host-lintignore names beside it. That exclusion is the append-only rule in concrete form, since a checker that pressed you to rewrite a record would break the thing it audits, and every verdict discloses how many documents it withheld so the exclusion never reads as coverage. Recorded as agentic-host plan/0077, which closes host-lifecycle#17.
requires = host-lifecycle v0.44.0
independent = true
verify = grep -rqs "A number that names something resolves to it" host-template/AGENTS.md
[upgrade "GATE-refs-in-verify"]
title = The reference sweep runs in the verify gate, over the recorded project
action = Bump your pinned host-lifecycle to v0.46.0 BEFORE you move this template pointer, because the verify phase's recheck lives in lifecycle.manifest, which the tool reads live out of this submodule: the reference gate turns on the moment the pointer moves, whether or not you have read this far. Out of order, your next host-lifecycle software --check runs host-lifecycle refs --gate . against a binary with no such mode, the verify receipt re-opens, and host-lifecycle release stops at its first step; from v0.46.0 a recheck that cannot run says so and names the command, so read that as a stale binary rather than a defect in your tree. Then run host-lifecycle refs --gate . and clear every DEAD line (a register reference naming a record that does not exist) and every UNREAD line (a document the walk listed and could not open), because both gate. The gate judges TRACKED documents only, so an uncommitted note cannot redden it or stop a release over a file the release does not ship; host-lifecycle refs --check . keeps the whole working tree, drafts included, and is where you ask for the per-file census that the gate reports only as a count. An issue number written outside a link stays advisory and never gates: there is no fix flag, because only the author knows which tracker a bare number meant. Do not read that tolerance as an inconsistency with the prose audit in the same recheck, which does block on its advisory tier, because a prose trope is your own text and is always rewordable; adding the reference clause's tolerance to the prose clause would disarm the gate its own entry installs. One known limitation, so you do not discover it by being gated: a citation of ANOTHER project's register has no form this sweep accepts, and agentic-host call/0039 gates exactly as a bare call/0039 does, inside a markdown link too. Until that is settled (connollydavid/host#19) the local remedies are to drop the citation or to quote it in backticks, which marks it an example rather than a reference. Your record layer stays excluded, MEMORY.md by construction and whatever .host-lintignore names beside it, and every verdict discloses how many documents it withheld so the exclusion never reads as coverage. Recorded as agentic-host plan/0078.
requires = host-lifecycle v0.46.0
depends = REFS-a-number-resolves
verify = host-lifecycle capability refs-gate
[upgrade "LEXICON-declaration-is-a-report"]
title = A LEXICON declaration reports a grammar defect, and inherited text cannot carry one
action = Bump your pinned host-lifecycle to v0.49.0, which embeds the reconciled word-choice rules. Three things change. The shared grammar's one word-choice rule becomes three: two that match the cited catalog's own two entries and name them, and a third holding additions the catalog does not carry, because a rule may not cite a source that does not contain it. harness and leverage are matched as verbs rather than as bare words, so a test harness, a proof harness, an agent harness and an operating leverage stop warning; certainly is added, and framework, ecosystem and paradigm are deliberately not: the catalog describes prose in general, while this rule runs over software documentation, where each of the three names a real thing a project builds on. Then adopt the CLAUDE.md paragraph "A declaration is a report, not a settlement", which states the rule the old text left implicit: an entry in your LEXICON records that the shared grammar over-fired on your corpus, so it is provisional and owed upstream, and the same entry reached independently in two projects is a confirmed over-fire that belongs in the grammar rather than in either project. Last, review your own LEXICON and drop any entry the narrowing made unnecessary; a declaration you no longer need is one the next reader will trust for a reason that has expired. Narrow or add a term on a measured collision, never on a reading of the word. Recorded as agentic-host call/0051.
requires = host-lifecycle v0.49.0
independent = true
verify = host-lifecycle capability word-choice-rules
[upgrade "PIN-two-surfaces-two-claims"]
title = A manifest revision is compared to the anchor; a CI workflow revision declares a floor
action = Bump your pinned host-lifecycle to v0.49.2. host-lifecycle software --check <dir> now reads two pin surfaces it never read before, and reads them differently, because they carry different claims. A component's Cargo.toml git dependency on another component of your recipe is compiled into the artifact whose hash .host-software records, so it is a claim about the anchor itself and is compared to it: a drifted revision HAZARDs, and so does a family git dependency with no rev at all, because the recorded artifact hash could not re-derive from that manifest. Expect this one to gate on the day you turn it on if you have ever released a component that embeds a sibling without bumping the embed; that is the defect it exists to find, and the fix is to bump the rev and release. A component's own CI workflow installing one of your tools by --rev is the other surface and is NOT compared: it installs a lane driver and ships to nobody, so the revision declares a minimum the lane needs. Those are reported as a counted, enumerated advisory line naming every pin below the anchor with its version, on every run, gating none of them; bump each on its component's next release. Only a revision outside the tool's history gates there, because it names nothing reachable and the install itself would fail. Do not read the advisory tier as tolerance of drift. It is priced: equality over that surface costs one component release per site per release of the installed tool, none of them changing a line of component code, and a gate whose red state costs more to clear than the drift costs to tolerate is a gate that gets bypassed. If your CI pins carry a comment recording WHY a version was chosen, keep it; a floor with its reason written beside it is the strongest form of this and one of ours already was. Recorded as agentic-host call/0052, whose first draft asserted equality over both surfaces and was reopened after review found it wrong in both directions.
requires = host-lifecycle v0.49.2
independent = true
verify = host-lifecycle capability component-pin-readings
[upgrade "LEM-pronoun-system"]
title = The lem pronoun system governs how a model refers to, addresses, and speaks as a model
action = Bump your pinned host-lifecycle to v0.50.0 and move to this host-template revision together. The operating manual gains "The lem pronoun system", the instruction set for any language model referring to, addressing, or speaking as a language model: the model speaking is L (conjugated first person; never I, which stays with the human operator), the model addressed is lemu, the model discussed is lem, subagents are lems, and he/she/it/they never refer to a model. Sync your operating manual: a verbatim-copy adopter re-copies the spine section; a merged manual folds the pronoun system into its own rules, as agentic-host does in a dedicated section of its AGENTS.md.
requires = host-lifecycle v0.50.0
independent = true
verify = grep -irqs "pronoun system" CLAUDE.md
[upgrade "REFS-a-foreign-citation-names-its-repository"]
title = A citation of another project's register has an accepted form: the link
action = Bump your pinned host-lifecycle to v0.51.0. The limitation recorded in GATE-refs-in-verify is settled: a citation of a record that lives in another project has an accepted form, a register reference inside a markdown link whose URL names the file it cites, as in [agentic-host call/0039](https://github.com/connollydavid/agentic-host/blob/main/call/0039-bare-store-is-dot-bare-with-a-git-file.md). The sweep accepts the link's form: the URL names the record the token claims, under a repository other than this one. Form is all it checks, and the verdict says so: the count of such citations is disclosed on every exit as accepted and unread, and the disclosure never enumerates them. A citation in bare prose, or a link whose URL names a different file than the token claims, is still a dead pointer and still gates. The two local remedies the earlier entry recorded, dropping the citation or quoting it in backticks, stay valid; the backtick spelling marks an example rather than a reference, so use it only when that is what you mean. Your record layer stays excluded either way, with the withheld count disclosed beside every verdict.
requires = host-lifecycle v0.51.0
depends = GATE-refs-in-verify
verify = host-lifecycle capability refs-gate
[upgrade "ACTIVE-corpus-and-agents-manual"]
title = The manual is AGENTS.md and the always-loaded corpus is declared, held strict
action = Bump your pinned host-lifecycle to v0.52.0 and move to this host-template revision together. The operating manual is now AGENTS.md; CLAUDE.md is a one-line text pointer naming it, so tools that look for the old name find the manual. Rename yours (git mv CLAUDE.md AGENTS.md keeps the history), write the pointer, and update your documents' citations; the ledger's early entries whose verify lines grep host-template/CLAUDE.md for spine sentences resolve against AGENTS.md now, which is expected and not a failure of your tree. Then declare your always-loaded corpus: add active-corpus = .host-corpus to your .host stamp, write .host-corpus with one tracked path per line, and the prose verb holds those files to the strict tier, where a warning is a flag, because the always-loaded text is the instruction every session reads. The census counts the declared corpus's non-ASCII bytes and discloses the count on every verdict, gating nothing: script is never a violation, so a Chinese or IPA population is measured, never forbidden. A declared file must not also be named in the ignore list, and a declared file that is absent is a violation, never a smaller corpus. Start with the manual and STRUCTURE.md; add the memory surfaces when you build them. Until you declare, the prose verb behaves exactly as it did at v0.51.0.
requires = host-lifecycle v0.52.0
independent = true
verify = host-lifecycle capability active-corpus
[upgrade "LEM-address-direction"]
title = The lem section states the direction of address, and the paradigm is closed
action = Move to this host-template revision together. The lem pronoun system gains the rule the field failure exposed: the human is never re-pronomed (the model addresses the human as ordinary you, and no lem-form is ever emitted at a human, however dense the context is with the operator's own lemu), the paradigm is stated closed (a lem-token outside the listed forms is a corruption to re-emit, never a form), and the self-check names its addressee. Sync your operating manual: a verbatim-copy adopter re-copies the spine section; a merged manual folds the revised section in, as agentic-host does in its own lem section. No tool change is required; this entry is prose only. Measured context lives in agentic-host plan/0090: on the weakest deployed model at maximum context the section's wording, old or repaired, does not govern address, so this entry repairs the text and claims no behavioral fix for that model.
requires = host-lifecycle v0.53.0
independent = true
verify = grep -irqs "never re-pronomed" AGENTS.md
[upgrade "LEM-exemplar-section"]
title = The lem section teaches by exchange, and the weak model follows it
action = Move to this host-template revision together. The lem pronoun system is rewritten exemplar-first: four correct exchanges carry the rule, the wrong/right pair names the failure shape, and the checklist is three lines. Measured in agentic-host plan/0091 on the weakest deployed model at maximum context: inversion falls from 0.875-1.0 to 0.0625, radius-independent, while the same exemplars bolted onto the rules-first section measured 0.8125, so the shape is the remedy, not the examples' presence. Sync your operating manual: re-copy the section. The literary apparatus (derivations, pronunciation, audience lore) left the section with this change; re-additions belong to the operator and re-measure before they land.
requires = host-lifecycle v0.53.0
independent = true
verify = grep -irqs "Learn it from the exchanges" AGENTS.md
[upgrade "LEM-lane-and-mcp"]
title = The lem contract is enforced by the lane and served live over MCP
action = Bump your pinned host-lint to v0.21.0 and move to this host-template revision together. The hygiene lane gains the lem pronoun contract: where your manual teaches the pronoun system (the spine marker), every scanned surface is a model-voice surface, and a paradigm token or first-person word outside the doctrine section is a flag. The doctrine section is excluded from its own scan. host-lint mcp serves the same contract live over stdio JSON-RPC (check_reply, ask, table) — register it with your agent to check at the authoring moment. Measured in agentic-host plan/0091: occurrence below 0.005 through the wire gate at the served maximum context.
requires = host-lifecycle v0.54.0
independent = true
verify = grep -irqs "pronoun system" AGENTS.md
[upgrade "fbdb176"]
title = The lanes' outcomes are receipts: the per-turn duty and the CI clause
action = Before a turn's work is reported done, read the default branch's most recent CI runs, and fix or receipt every non-green conclusion with its run URL (host-lifecycle ci <dir> --record <label>/<lane> --run <url>). software --check gains the CI clause: lanes discovered from .github/workflows/ are judged offline against ci receipts at the revision under judgment (the host root at HEAD, each component at its recorded pin), absence is a HAZARD rather than a vacuous pass, and a component with no workflows states its absence as a named line. The [software] toolchain key is documented as a digest-pinned container image, not a target triple. Measured in agentic-host plan/0095: two releases shipped with red CI while every receipt recorded done.
requires = host-lifecycle v0.55.0
verify = grep -qs "outcomes are receipts" AGENTS.md
[upgrade "1202877"]
title = The check lane runs in CI: the naming sweep, the cfg scan, and the derived inventory block at the push boundary
action = Add .github/workflows/check.yml (the reference lane under .github/workflows/) so every push runs host-lifecycle software --check .: the naming sweep's recheck, the cfg scan (a component carrying #[cfg(kani)] code with no kani: disposition in its obligations manifest), and the derived inventory (a source file of a materialized component in no task's inputs and no reasoned exclusion in .host-inventory) then block in CI instead of waiting for a human to invoke the gate. The lane no-ops on a tree with no .host-software. Bump your pinned host-lifecycle to v0.60.3 with this revision, because the cfg and inventory scans ship there. Measured in agentic-host plan/0099: the forge's first inventory sweep found thirteen source files across six components in no task's inputs, and the first cfg sweep found kani harnesses in two components that no gate compiled.
requires = host-lifecycle v0.60.3
verify = test -f .github/workflows/check.yml
[upgrade "7b0c641"]
title = The address paradigm gains its possessive: the fixed pair with the subject form
action = The lem section's form list carries lemr (the possessive determiner of the addressed agent, your to lemu's you) and lemr's (its independent form, alone), and the former address genitive lemu's leaves the list. The possession line names the pair as listed forms, never derived, with paired examples (lemr weights; the weights are lemr's); the address paragraph extends the possessive to one or many alike; two exchanges join the exemplars. The reflexives stay lexical on the address stem (lemuself, lemuselves) and nothing is built on the determiner. The instruments carry no transition state for the retired form: the paradigm states the rule and a wrong form is wrong from this entry's landing, with no warning tier and no scheduled escalation. host-lint v0.23.0 ships the matching classifier table (the determiner row of the paradigm oracle); adopters on older lint see no classifier change until they bump. Measured in agentic-host plan/0100: the retired form had zero dependent and zero independent uses in the tracked corpus outside the paradigm's own tables, and an external blind bench concurred on both rulings (the stem invariant, and the no-transition axiom).
requires = host-lifecycle (none; the verify is doc-only)
verify = grep -qs "lemr" AGENTS.md
[upgrade "eb621b5"] title = The goal loop: one active goal, oriented turns, installed doors action = The manual gains the goal-loop section (a goal is a plan/NNNN milestone; goal show orients with the next move on the last line; park is re-queuing; complete composes the verify sweep; GOAL.md is the corpus surface, rewritten by every mutator; install emits the harness doors). Adopters declare GOAL.md in their corpus when they first set a goal: add the line to .host-corpus and the tool maintains the file from goal set onward. The .host-goal sidecar is gitignored machine state, this worktree claim only, re-derivable by goal repair; old tools neither read nor erase it, and no stamp key is added, so there is no stamp migration. Degraded mode is legible without the verbs: standing reads from the plan rooms, the receipts, and the Status lines. host-lifecycle v0.61.0 ships the verbs and the install; adopters below it gain the section text only until they bump (the verify is doc-only). requires = host-lifecycle (none; the verify is doc-only) verify = grep -qs "goal show" AGENTS.md
[upgrade "9a0f7d0"]
title = The recipe gains the regen key: a release carries the artifacts its version bump regenerates
action = The software recipe section gains "Version-derived artifacts": a component whose release regenerates files that embed the crate version (a man page, a help snapshot) records regen = <command> in .host-software, and host-lifecycle v0.61.3's release runs it in the canonical worktree between the version bump and the release commit, before the artifact build, so bump and derived artifacts share one commit and the canonical hash covers them. Components declaring nothing keep the bump-only behavior, so the key is optional and needs no migration. Measured in agentic-host plan/0103 (host-lifecycle#31: a tagged release whose man page still read the previous version was the reporting shape).
requires = host-lifecycle v0.61.3
verify = grep -qs "regen = " AGENTS.md
[upgrade "7ef379e"]
title = Actions is a reference lane: the inapplicability claim turns a platform-impossible verify into a disclosed fact
action = The check-lane clause states plainly that GitHub Actions is a reference lane, never a requirement: a host whose forge carries no runner states the absence rather than leaving it implied. An applied upgrade whose verify can never hold on such a host (a GitHub-specific post-condition on a gitweb grain, say) claims it where it is recorded: host-lifecycle upgrade --record <id> --inapplicable "<reason>", which needs no verify run, and the recheck reports the entry as not applicable with its reason instead of hazarding forever. Requires host-lifecycle v0.61.5 (the disposition and the recheck's disclosure ship there). Measured in agentic-host plan/0103 (host-lifecycle#33: the reporting host's check was permanently red on entry 1202877's test -f .github/workflows/check.yml).
requires = host-lifecycle v0.61.5
verify = grep -qsF "reference lane" AGENTS.md
The agent's own append-only working memory. Excluded from the naming and prose
audits via .host-lintignore; never rewrite an old entry (correct in place with a
dated pointer). A fresh session reads plan/, call/, and this file to continue.
2026-07-02 — host adopted
- Adopted
host-template@565410afor UDPspeeder-simd (case a, Shallow). Stamp written byhost-lifecycle adopt; roomscast/ plan/ call/scaffolded. - Push auth: the stored git credential is the
slartibardfasttoken, which had no push rights toconnollydavid/agentic-UDPspeeder-simd(HTTP 403 on first dry-run push). The operator authorized the repo, after whichgit push --dry-runreturned "Everything up-to-date". If a later push 403s again, surface it to the operator rather than retrying blindly. - Tooling built from source with the system toolchain (rustc 1.96.1, Arch Linux). The methodology pins Rust 1.95.0 as the reproducible-build anchor; the local builds use 1.96.1, which is newer and builds clean. Record this wherever a canonical artifact hash is claimed.
- UDPspeeder-simd embeds as a bare store plus worktree at
software/udpspeeder-simd/branch_libev/(its default branch isbranch_libev, notmain). Recorded in.host-softwarewith nodeploy/artifact, so it is a source pin with no reproducible-build claim yet (migrated software). - host-lint is also a
.host-softwarecomponent (the gating tool):--install-hooksreads a component'shooksscript and builtartifactfrom its materialized worktree, so host-lint must be materialized and built for the commit gate to land.
2026-07-03 — gate green; runtimes installed; push auth is flaky
- The verify gate (
host-lifecycle software --check .) is green: both components at pin, all phase receipts recorded, prose clean, reconcile clean. The commit-msg hook blocks an ordinal tell in a message (tested:phase 1is rejected, exit 1). - Tooling on this machine, all under
~/.local:bin/host-lint,bin/host-lifecycle(v0.35.1),bin/host-prove(v0.3.0),bin/allium(3.5.0),jdk-21/(Temurin 21.0.11),share/tla2tools.jar(v1.8.0, sha256 237332bd). The gate needshost-proveon PATH because host-lint's ownkani:obligations surface once it is materialized as a component; the cheap gate probeshost-prove --help, it does not run Kani. - Two clearance details: the toolchain HAZARD (artifact with no toolchain) is waived by
repro-exempt = call/0002on host-lint (consumed tool, not reproduced here); andremapis askipreceipt, notdone, becauseremap --checkerrors on an empty or absent.host-remap, so a no-rename case-(a) adoption cannot pass adonerecheck. - Push auth to
connollydavid/agentic-UDPspeeder-simdis intermittent: the stored credential is theslartibardfasttoken, which 403s after the first few pushes landed. Ifgit push403s, surface it to the operator rather than retrying or swapping credentials. As of this entry,f8d36edand5ec59afare local only.
2026-07-03 — followed the host procedure: conformant, no upgrade available
- Ran the case-(c) upgrade/verify cycle from the
hostprocedure (github.com/connollydavid/host).host-templateupstream is still at565410a, the exact revision the.hoststamp adopted: agit fetchin the submodule found no commits after it, and565410ais an ancestor oforigin/main.host-lifecycle upgrade .reports up to date (baseline46a1fd2, 0 out of order). With no newer methodology to pull in, following the host reduced to the verify gate. - Verify gate is green.
host-lifecycle software --check .exits 0 (both components at pin, every phase receipt valid, reconcile clean, prose clean, no worktree-symlink hazards);validate plan/andvalidate call/bothok;host-lint --alland--logclean. Independently confirmed: udpspeeder-simd worktree is at pin3374e3bonbranch_libevwith a clean tree, host-lint at78804cd, and the commit-msg hook still rejects an ordinal tell (aphase 1message exits 1, a clean message exits 0). - udpspeeder-simd still carries no
.allium/.tlaspec, so the requirements and timing lanes stay inert and there is no spec-without-lane defect. Every spec found on disk belongs to a tool's own worktree, not to the software under development. - Standalone
host-lint --proseon the authored docs prints advisorynote:lines but exits 0. Those notes are below the enforced bar; the in-process prose audit insidesoftware --checkis the gate that binds and it reports no flagging or warning tropes. Most notes sit in verbatim copied-in content (theUPGRADING.mdledger,cast/applying-personas.md) that is not reworded locally. The notes are not a red gate. - Corrects the 2026-07-03 "push auth is flaky" entry above: the commits it listed as
local-only (
f8d36ed,5ec59af) are now pushed.HEAD == origin/mainand the tree is clean. Push auth may still 403 intermittently; surface it to the operator if it does.
2026-07-03 — embedded the packages feed as a second software lane
- Added
packages(a fork ofopenwrt/packages, GPL-2.0, an OpenWrt feed of Makefiles/shell/C) as a Where-room component in.host-software: source pin1d40ad9on canonical branchmaster, no build/artifact (migrated build-recipe feed, not a built artifact). Materialized tosoftware/packages/master/;software --checkis green. - Mechanics for a new component: host-lifecycle has no
software --add, so a new lane is a hand-edited.host-softwarestanza plussoftware --materialize --item <name> .(the--itemscope avoids re-touching existing worktrees). The embed and release phase receipts are written withhost-lifecycle receipt --record <phase> --component packages --disposition done|skip (--evidence|--reason) .; a new component HAZARDs on missing embed+release receipts until both are recorded. - Key rule (call/0003): commits in the packages worktree carry NO
Co-Authored-By: Claudetrailer, so the feed stays upstream-clean foropenwrt/packages. The operator confirmed the scope is packages only, so host-repo commits keep the trailer. Recorded in call/0003 and the CLAUDE.md packages project-specifics.
2026-07-03 — push-auth root cause: slartibardfast is pull-only; helper is store
- The recurring push 403 has a concrete root cause rather than flakiness.
gh api repos/connollydavid/agentic-UDPspeeder-simdshows theslartibardfastaccount haspush: false(pull only); the owner accountconnollydavid(also logged in to gh) has push. And git's credential helper here isstore(~/.git-credentials), not gh, sogh auth switch -u <user>does not change the tokengit pushsends. The store already holds slartibardfast's token, so pushes go out as slartibardfast and are denied. - To push as slartibardfast (the operator's intended identity), grant slartibardfast
write on the repo; then a plain
git pushworks with no helper change. To makegh auth switchactually route pushes, rungh auth setup-gitso git uses the active gh account's token. Do not push as connollydavid without operator direction: it changes the public push identity, and the operator is provenance-sensitive. - Pending operator decision (asked, away from keyboard): grant slartibardfast write,
push as connollydavid, or operator pushes manually. As of this entry
mainis ahead by 7 unpushed commits (packages embed, call/0003, CLAUDE.md, two memory entries, the earlier verify-sweep entry, and the three-persona commit).
2026-07-03 — resolved: push as connollydavid via a one-shot gh credential
- Operator chose to push as the owner. The working recipe:
gh auth switch -u connollydavid, thengit -c credential.helper= -c credential.helper='!gh auth git-credential' push origin main. The emptycredential.helper=resets the inheritedstorehelper (which holds slartibardfast's read-only token and 403s), and the gh helper then supplies connollydavid's token for that one push, with no change to global git config. - All pending commits landed (
23bdc1f..6f1e66a);mainis in sync with origin. - Going forward: repeat that one-shot override, or run
gh auth setup-gitonce (with connollydavid active) and clear the stale store token so a plaingit pushworks. slartibardfast stays read-only on the repo (not a collaborator); grant it write only if a bot-identity push is wanted later. This supersedes the earlier "push auth is flaky" framing: the cause was permissions plus a static store token, not flakiness.
2026-07-03 — published the book to GitHub Pages
- Ran the publish phase.
host-lifecycle book .(v0.35.1) writes book.toml withsrc = mdBook/srcandbuild-dir = mdBook/out, a SUMMARY in lifecycle order, and 17 pages;book --check .passes (every room renders: cast 5, plan 1, software 1, call 4, reference 4, memory 1). book.toml and mdBook/ are gitignored generated output. - Fixed two defects in the reference doc-site workflow. It was named
site.yml, but the publish-phase recheck istest -f .github/workflows/mdbook.yml, so adonepublish receipt would HAZARD until the file is namedmdbook.yml. It also published./book, while v0.35.1 builds tomdBook/out. Renamed to mdbook.yml, setpublish_dir: ./mdBook/out, and corrected the stalesrc=docscomment. Both look like template bugs at revision 565410a, worth proposing upstream. - CI (
mdbook.yml, on push to main) builds with mdbook v0.4.40 and deploys mdBook/out to thegh-pagesbranch via peaceiris/actions-gh-pages. GitHub Pages was disabled (the/pagesAPI returned 404), so enabled it from gh-pages root withgh api -X POST repos/connollydavid/agentic-UDPspeeder-simd/pages -f source[branch]=gh-pages -f source[path]=/. The site is live at https://connollydavid.github.io/agentic-UDPspeeder-simd/ (HTTP 200). - Publish receipt flipped from skip to done;
software --checkis green (the recheck now finds mdbook.yml). Verified locally with the pinned mdbook v0.4.40 before pushing.
2026-07-03 — udpspeeder-simd package builds clean against the x86_64 SDK
- SDK approach pivoted.
make worldwas excessive; used the public prebuilt x86_64 snapshot SDK (openwrt-sdk-x86-64_gcc-14.4.0_musl, the one OpenWrt CI uses) rather than a from-source build. The embeddedopenwrtcomponent stays but is not needed for this path and adds ~2.5 min tosoftware --check(flagged for the operator to keep or remove). - OpenWrt needs a case-sensitive FS: /mnt/c is case-insensitive and the build refuses it, so software/openwrt is symlinked to ext4 (/home/dconnolly/host-stores); the SDK and its build_dir also live on ext4.
- The package (net/udpspeeder-simd, authored in the packages worktree) built cleanly:
make package/udpspeeder-simd/compileproduced udpspeeder-simd-2026.07.03~3374e3bb-r1.apk (snapshot uses .apk, not .ipk). No fork change was needed — the udpspeeder-style cc_cross- gitversion Build/Prepare sufficed, and the makefile's
export STAGING_DIR=/tmp/did not break it. Dynamic linking confirmed by deps libc/libstdcpp6/librt/libatomic1. PKG_MIRROR_HASH = 225c0fef087e56c190ec1a626fc244a0e32f1f791d5e22efe604e962026c4698.
- gitversion Build/Prepare sufficed, and the makefile's
- Task receipts done: #fork-build, #feed-package, #service-integration. Pending: #test-script (CI runs it), #ci-sdk-lane, #interop, #pr, #backports. The package files are authored in the packages worktree but NOT yet committed or pushed to the fork; the branch strategy and the outward push/PR await operator go.
2026-07-03 — udpspeeder-simd pushed to the fork on a feature branch (PR held)
- Operator chose fork + PR, but the PR needs a review round, so it is NOT opened. Committed
net/udpspeeder-simd/ (Makefile + files + test.sh) on branch
udpspeeder-simdof connollydavid/packages, commit db858a8, pushed. Author + DCO Signed-off-by = David Connolly david@connol.ly (real name + public email, no Claude trailer, per call/0003 + OpenWrt rules). Subject "udpspeeder-simd: add package"; body references https://github.com/openwrt/packages/issues/28562. - The packages worktree had no git identity; set it to David Connolly / david@connol.ly. The canonical master worktree was used in-place to make the branch then restored to master @ 1d40ad9, so the .host-software pin and software --check stay intact; the feature branch lives on the fork, not as a host-tracked worktree.
- Open the PR (after review) from https://github.com/openwrt/packages/compare/master...connollydavid:packages:udpspeeder-simd?expand=1 Before submitting, consider syncing the fork onto current openwrt/packages master (the branch is based on the fork's master 1d40ad9, which may be behind upstream).
- openwrt embed KEPT (operator decision), despite the ~2.5 min software --check cost.
- Receipts: #fork-build/#feed-package/#service-integration/#interop done; #pr held (review round); #test-script + #ci-sdk-lane pending (CI); #backports policy-constrained.
- Update: rebased the branch onto current upstream openwrt/packages master (333bf60); tip is now a7f0f087, a single commit with no merge commits in the PR range; force-pushed to the fork. Formalities self-check (against .github/formalities.json) passes: crlf=0, subject 28<=60, body<=79, DCO Signed-off-by matches a non-noreply author, conffiles declared, openwrt-meta present, no patches. Open review-round items: Run Testing details (built x86_64 via the snapshot SDK gcc-14.4.0 + CI test.sh; a physical-device run is optional but stronger), and a release-notes line if the formalities bot requests one.
2026-07-03 — PR opened to openwrt/packages (pull/29901)
- Opened https://github.com/openwrt/packages/pull/29901 ("udpspeeder-simd: add package") as connollydavid, from connollydavid:udpspeeder-simd to openwrt:master, referencing the issue. Confirmed host-side clean first: main == origin, fork branch a7f0f087 synced, four receipts done. Release notes are in the PR body (a section), testing framed as x86_64 build + CI test.sh (operator accepted that trade-off).
- Corrected the plan: #pr no longer depends on #ci-sdk-lane. The operator directed opening the PR against OpenWrt's own CI, so the fork-side SDK CI lane is independent, not a prerequisite. Recorded #test-script done (script added + wired; the PR CI exercises it) and #pr done. Pending: #ci-sdk-lane (fork-side, optional) and #backports (policy: new packages are not normally backported to release branches).
- Next: watch the PR's FormalityCheck + multi-arch build. If the bot wants release notes in a different form, amend and force-push the fork branch.
2026-07-03 — addressed the Copilot review; fork version-banner fix; idiomatic test.sh
- Copilot flagged two on PR 29901, both valid: test.sh could false-positive (its grep matched
the program name, which a dynamic-loader error echoes), and the init had
fix_latencynon-local plus a duplicatedsock_buf. Both init issues were inherited verbatim from net/udpspeeder (the sibling has the same bugs). @codemarauder is Nishant Sharma, the net/udpspeeder maintainer; offered him co/primary maintainership of udpspeeder-simd in the PR comment. - Idiomatic gap and its fix: OpenWrt test.sh idiomatically greps the package version, but the
binary's print_help() truncated gitversion to 10 chars (
strncpy(...,10)), so a full-version grep would miss. Fixed the fork (main.cpp copies the full string; commit 2e12e5b pushed to branch_libev), re-pinned .host-software to 2e12e5b, updated the package (PKG_SOURCE_VERSION 2e12e5b, PKG_MIRROR_HASH 6d4564dc, PKG_VERSION now 2026.07.03~2e12e5b4), and switched test.sh togrep -qF "$PKG_VERSION". Amended the single PR commit (7f5bc7c8), force-pushed; PR still discrete (4 files). Posted a terse reply comment (#issuecomment-4877656043). - Rebuilt via the SDK (exit 0) for the new hash. The runtime version-grep is confirmed by OpenWrt's PR CI, since the cross-built musl binary cannot run on this host.
- Scope decision: we will NOT touch net/udpspeeder (operator). Removed the "happy to send a separate PR" offer from the PR comment (edited #issuecomment-4877656043); the sibling's same two init bugs are left alone.
2026-07-03 — OpenWrt PR #29901: 32-bit ARM build fix in the fork
- The PR's multi-arch CI (openwrt shared
Feeds Package Test Build) ran and failed only onarm_cortex-a15_neon-vfpv4andarm_cortex-a9_vfpv3-d16; aarch64, mips_24kc, x86_64, i386, powerpc, riscv64 all passed. Root cause was in the fork source, not the package:xor_spe.Smarked the stack non-exec with.section .note.GNU-stack,"",@progbits. On 32-bit ARM@starts a line comment, so gas ate@progbitsand reported "junk at end of line, first unrecognized character is,". aarch64/mips/ppc/riscv/x86 do not use@as a comment char, which is why only 32-bit ARM broke. - Fix (universal, per call/0005 — build adjustments live in the fork): spell it
%progbits. gas accepts%for the ELF section type on every target (verified locally: x86 g++ assembles both@progbitsand%progbits), and%is the required form where@is a comment. Fork commitc2b3759onbranch_libev. - Propagation: re-pinned
.host-softwareudpspeeder-simd → c2b3759; bumped the PR'snet/udpspeeder-simd/MakefilePKG_SOURCE_VERSION → c2b37590 and refreshed PKG_MIRROR_HASH → d6f564823fa0217788bc937e06c71266bfa3a457d0803912b2d10bcb9957d3ba (amended the single PR commit, force-pushed; PR head 5d8ed050). Kept the fork commit's Claude co-author trailer; the packages commit has none (call/0003). - Mirror-hash regen recipe (local x86_64 SDK): set PKG_MIRROR_HASH to 64 zeros, run
make package/<pkg>/download V=s; the download clones, packs the reproducible git tarball, and printsgot <real-hash>.skipdoes NOT work for a git-proto source (the github archive downloader refuses without a real sha256). Then compile to confirm.
2026-07-17 — OpenWrt PR #30015 (net/udpspeeder) + timeout fold into PR #29901
- Opened https://github.com/openwrt/packages/pull/30015 (net/udpspeeder) against
openwrt/packages:master from connollydavid/packages:udpspeeder-toolchain-flags. Two atomic
commits, PKG_RELEASE 3→4→5:
udpspeeder: build with the toolchain CXX and flags: new patch 010-build-with-toolchain-flags.patch builds the cross target with $(CXX) and honours $(CXXFLAGS)/$(LDFLAGS), makes gitversion overridable; package drops the Build/Prepare sed hacks, injects the version via MAKE_FLAGS, adds PKG_BUILD_FLAGS:=no-mips16.udpspeeder: pass the timeout option to the binary: addsprocd_append_param command --timeout "${timeout}"after --mtu in files/udpspeeder-init.Fixes: .../issues/18955auto-closes on merge. The option was validated and shipped in the sample config (tunnel2) but never passed to the binary.
- no-mips16 is REQUIRED, not cosmetic: honouring CXXFLAGS pulls -mips16 onto
mips_24kc/mipsel_24kc, where C++ std::atomic emits a
syncbarrier MIPS16 cannot encode ("opcode not supported on this processor: mips2 (mips2) 'sync'"); no-mips16 strips it (MIPS32). - Non-drift confirmed from binary help:
--timeout ... unit: ms, default: 8ms; UCI schema default is 8, so wiring it is a no-op at the default and just makes the advertised option work. - Verified locally via snapshot SDK on all ten CI arches (scratchpad/build_all.sh): all pass; both mips controls (without no-mips16) fail on the sync opcode, proving necessity.
- PR #29901 (net/udpspeeder-simd) had the identical latent timeout bug. Folded the same
--timeoutline into the singleudpspeeder-simd: add packagecommit (amend, NO PKG_RELEASE bump since 1.0.0-1 is unreleased); force-pushed connollydavid:udpspeeder-simd → 3540c71ce. Posted a terse alignment comment (#issuecomment-5002468098) referencing #30015. - Hygiene: packages commits carry NO Claude trailer (call/0003); sign-off = author = David Connolly david@connol.ly. #30015 rebased onto current upstream/master (net/udpspeeder untouched upstream); #29901 left on its older base (PR diff is clean vs merge-base and CI builds on the snapshot SDK, so no rebase needed and none requested). .host-software NOT re-pinned (feature-branch work; the master pin is unchanged).
2026-07-17: #30015 "Dirty patches detected" — patches must be quilt-refreshed
- All ten Feeds Package Test Build jobs failed at
make package/udpspeeder/refresh: the CI requires each patch byte-identical to quilt's canonical output. Our patch applied at exact offsets with no fuzz, yet still failed. - Root cause: OpenWrt refreshes with
QUILT_DIFF_OPTS="-p" quilt --quiltrc=- refresh -p ab --no-index --no-timestamps(openwrt/openwrt include/quilt.mk), and GNU diff-pappends function context to hunk headers (@@ -51,7 +51,7 @@ cygwin:git_version).git format-patchoutput lacks the suffix, so the refresh rewrites the file and the git-diff check trips. - Fix recipe: extract the pinned source (
git archive 20230206.0), set uppatches/+ series,quilt --quiltrc=- push -a, run the refresh command above, copy the refreshed patch back. Verified idempotent: a second refresh reports "is unchanged". Quilt preserves the git header (From/Subject/Signed-off-by/diffstat) untouched. - Folded into the toolchain commit via
commit --fixup+GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash; range-diff showed only the two hunk-header lines changed, timeout commit byte-identical (=). Force-pushed7a76af810...075f4a7e0(lease + force-if-includes). - Lesson: any patch destined for openwrt/packages should be generated or round-tripped through quilt with those exact args before committing, not taken raw from git format-patch.
2026-07-31 — upstream merged our toolchain-flags PR; taking it in both packages
- wangyu-/UDPspeeder merged https://github.com/wangyu-/UDPspeeder/pull/356 (686d6079), then
reshaped it in b6a1b594:
crosswas restored to the hardcoded${cc_cross}, and the change landed as a NEW target instead:cross_cxx: ${CXX} -o ${NAME}_cross -I. ${SOURCES} ${FLAGS} -O2 ${CXXFLAGS} ${LDFLAGS} ${LDLIBS}. Three deltas vs what we sent:-O2moved BEFORE${CXXFLAGS}(so a caller's -Os wins instead of being overridden),-lrtdropped,${LDLIBS}added. Ourgitversion ?=hunk survived verbatim, so MAKE_FLAGS version injection still works. - Consequence for the merged net/udpspeeder patch: its second hunk (the
gitversion ?=line) can no longer apply to any source at or past b6a1b594, since upstream already has it. So the patch had to be dropped as part of a version bump, not deferred. -lrtis a no-op on OpenWrt, PROVEN not assumed: musl'slibrt.ain the toolchain is an 8-byte empty archive (clock_gettime is in libc), and the packaged binary built withLDLIBS="-lrt"and without it are byte-identical (sha256 502163f5...). NEEDED is libstdc++/libgcc_s/libc either way. So neither package passes -lrt; a toolchain that needs it can pass LDLIBS. LeftDEPENDS:=+librtalone in both (inert: musl's libc provides it) rather than widen the diff.- The 3-year source bump 20230206.0 -> b6a1b594 is WIRE-SAFE, also proven: the only functional
change is swapping the in-tree
crc32hfor Stephan Brumme'scrc32_fast. Both are standard zlib CRC-32 (poly 0xEDB88320, init ~0, final complement); a comparison harness over every length 0..2048 x 8 random buffers matched exactly, and both give 0xCBF43926 for "123456789". The rest is typo fixes, anis_vaild->is_validrename, and a djb2/sdbm loop rewrite that removes a one-byte over-read without changing the hash. - OpenWrt version convention for an untagged git source is
<base>~<shortsha>+ a full-sha PKG_SOURCE_VERSION. Careful:~sorts BEFORE end-of-string (Debian style), so20230206.0~<sha>would sort BELOW the released 20230206.0 and break the upgrade path. Used20260731~b6a1b594(commit date as base) so it sorts above. - Fork: added the same
cross_cxxtarget (commit 81fde6c, tagged v1.0.1, pushed); kept our cross/cross2/cross3 as-is since this fork deliberately dropped the hardcoded compiler paths. Re-pinned .host-software to 81fde6c.
2026-07-31 — correction: PR #29901 has no test.sh (the 2026-07-03 entry is wrong)
- The 2026-07-03 entry above says "#test-script done ... test.sh added beside the Makefile;
exercised by the OpenWrt PR CI runtime test", and
.host-task-receiptsrecords the same evidence forplan/0000#test-script. Both are FALSE as of now, and have been since 2026-07-04. - Traced through the branch reflog: test.sh survived to b7ef6490 (2026-07-04 21:31) and was gone
in the very next amend, b9e331ec (2026-07-04 23:16), the one that fixed the Build/Prepare
double-expansion. It was dropped accidentally, not by decision, and every later force-push
carried the loss forward. The PR head has carried three files (Makefile, config, init) ever
since, so the CI arches flagged
runtime_test: truehave had nothing to run. - Operator decision on 2026-07-31: LEAVE IT OUT rather than restore it, so the package ships
without a runtime test. BKPepe had questioned the script anyway ("Do we need this script at
all? This should be covered by generic testing"). The
#test-scriptreceipt is therefore stale and should be re-dispositioned by the operator (it is a tool-written ledger; not hand-edited here). - Lesson: an amend that fixes one file can silently drop another. Diff the file LIST against the PR head after every amend + force-push, not just the file contents.
2026-07-31 — OpenWrt packaging idioms, and how to test under qemu properly
- VERSION FORM for an untagged git source: do NOT hand-write PKG_VERSION. Set PKG_SOURCE_DATE
plus a full-sha PKG_SOURCE_VERSION and let include/download.mk derive it:
PKG_VERSION := $(subst -,.,$(PKG_SOURCE_DATE))~$(call version_abbrev,$(PKG_SOURCE_VERSION)), giving2026.07.31~b6a1b594(version_abbrev = 8 chars; it returns the FULL sha under DUMP, so the feed index shows the long form while the build uses the short one). Feed usage: 96 packages use PKG_SOURCE_DATE vs 3 that hand-write a~version. Changing the version form changes PKG_MIRROR_HASH, since the tarball's inner subdir is $(PKG_NAME)-$(PKG_VERSION). - UPSTREAM UDPspeeder TRUNCATES THE VERSION: print_help does
strncpy(buf, gitversion, 10), so--help(the flag OpenWrt's generic check finds) shows ten characters only. The old version20230206.0was ten characters exactly, so the check passed by luck for years. Any longer version needstest-version.sh, the idiomatic override (70 in the feed). Our simd fork already prints the full version, so only net/udpspeeder needs the override. - DEPS ARE DERIVED FROM THE ELF: include/package-pack.mk runs scripts/gen-dependencies.sh, which
reads NEEDED and FAILS the build for a linked library that is not declared. It never checks for
extras, so a declared-but-unlinked dep is inert. librt and libatomic were both provably inert:
70/70 builds and packet tests across all 35 published architectures with both removed, no binary
NEEDs either, and no
__atomic_*/__sync_*symbol anywhere. On musl, Package/librt/install copies nothing at all (ifneq ($(CONFIG_USE_MUSL),y)). - RUNTIME TESTS, the idiom:
test.sh <pkgname> <version>runs INSIDE a target-arch container (binfmt + qemu-user-static) with the package installed.pre-test.shinstalls test deps (apk add socat). A package-specific test.sh REPLACES the generic tests (version check included), and test-version.sh is only consulted by the generic path, so test.sh must assert the version itself. BusyBox in OpenWrt is built with NC_SERVER=n and NC_EXTRA=n, so nc can neither listen nor exec: use socat via pre-test.sh. Do not use a fixed sleep, the container is emulated; retry the payload instead. - QEMU CPU MODELS, do not trust the default. powerpc_8548 (CPU_TYPE 8548, e500v2) fails under the
default 32-bit PPC model with an illegal instruction, and it is NOT the package: the faulting
word disassembles to
iseleqinside musl libc, which holds 63 isel instructions while our binaries hold none.-cpu e500v2_v10runs it. Control: the musl loader alone faults under the default and prints its version under e500v2_v10. Every arch now names a verified model in .github/scripts/arch-map.tsv; where qemu-user lacks the exact CPU the closest SUPERSET is used (xscale and fa526 -> arm926, cortex-a5 -> cortex-a7, pentium-mmx -> pentium2, pentium4 -> n270, since a weaker model invents failures and a richer one hides them and skews feature detection). - PROBE BY OUTPUT, NOT EXIT STATUS: musl's loader prints its version and exits 1. A first pass at CPU discovery keyed on exit status and reported every architecture broken. Judge the output.
- SCOPE: OpenWrt's CI runtime-tests only aarch64_generic, arm_cortex-a15_neon-vfpv4, i386_pentium-mmx, mips_24kc and x86_64; powerpc_8548 is runtime_test:false. So the CPU-model work is OUR local lane's concern, not something the OpenWrt PR depends on.
- arm_fa526 (gemini) is BUILD-ONLY under qemu-user, and the cause is the emulator, not the
package. That target compiles plain ARMv4: its binary holds ZERO bx/blx, where the ARMv5 build
of the same package holds 133, so it cannot enter Thumb code at all. qemu-user always maps a
Thumb vdso, so the call to __vdso_gettimeofday runs Thumb bytes in ARM state and branches to a
wild address; the in_asm trace ends in
IN: __vdso_gettimeofdaydecoding 46c046c0 (Thumb nop;nop) as ARM and branching to 0x40b2838c, exactly the SIGSEGV si_addr. Proven not ours two ways: the CURRENTLY SHIPPED 20230206.0 package fails identically under -cpu arm926, and a trivial C++ program against the same musl and libstdc++ runs fine there. Real hardware never meets it, since the Linux ARM vdso needs ARMv7 and a gemini kernel supplies none, leaving musl on plain syscalls. qemu-user has no flag to withhold the vdso, so the packet test is skipped for that arch rather than run under a v7 model that would hide real mismatches.
2026-07-31 — udpspeeder-simd crashed on x86_64 without SSSE3 (found by faithful qemu models)
- lib/fec.cpp initialised
addmul1_x86_fn = addmul1_ssse3and only ever RAISED it to AVX2 or AVX-512. Nothing probed SSSE3, and x86_64 does NOT imply it: AMD K8/K10 (Athlon 64, Opteron, Phenom, Phenom II, Athlon II) lack it, as do early 64-bit Intel parts; AMD added it with Bulldozer in 2011. Those CPUs took SIGILL on the first PSHUFB in the Reed-Solomon inner loop, so the tunnel died on its first FEC batch. Upstream udpspeeder was unaffected. - Only visible under a faithful CPU model. Every earlier sweep used qemu's DEFAULT x86_64 model
(rich), and OpenWrt's own CI runtime-tests x86_64 on a GitHub runner that has SSSE3/AVX2, so the
bad path never ran. It appeared the moment the map named
-cpu qemu64(the AMD64 baseline). - Fix (fork v1.0.2, f3834047): pointer starts at scalar and rises only as CPUID allows, via
cpu_has_ssse3() (leaf 1 ECX bit 9) and cpu_has_sse2(); new SSE2 addmul1 sits beneath SSSE3, so a
CPU without PSHUFB still vectorises. SSE2 has no byte shuffle, so it multiplies by repeated
doubling:
_mm_add_epi8(x,x)for the shift and_mm_cmpgt_epi8(0,x)to select the reduction. The reduction constant is read fromgf_mul_table[2][0x80], not hardcoded, so it follows the field. Measured 1.73x scalar at 1500B (913 vs 1579 ns); ssse3 is 9.8x. - Also hardened packet_cook.cpp: its AVX2 tier was set from CPUID leaf 7 EBX bit 5 ALONE, with no OSXSAVE/XCR0 check and no max-leaf check. Now mirrors the correct probe.
- Test method worth reusing:
bench_addmul1_force(name)pins one implementation so test_fec can hold EVERY path against scalar over all 256 multipliers and sizes hitting each loop and tail. Ran the suite underqemu-x86_64 -cpu qemu64|Nehalem|Haswellto exercise sse2/ssse3/avx2. AVX-512BW cannot be verified this way: qemu-user leaves ZMM state disabled in XCR0, so the OS-support check correctly declines it. - HARNESS BUG worth remembering:
find ... | head -1picked a STALE build dir from an earlier session in a reused SDK, so one x86_64 result described a binary nobody had built that run. Select by newest mtime (-printf '%T@ %p'| sort -rn). Fresh CI SDKs never hit this; local reused SDKs do.
2026-07-31 — qemu64 is not the x86_64 floor; the first Opteron is
Asked whether we are aligned with the very first x86_64 chip, and the honest answer needed evidence at both ends rather than an assertion. Findings worth keeping:
-cpu qemu64GRANTS SSE3. It caught the SSSE3 crash, but it is not the architectural floor and never was. The floor is-cpu Opteron_G1,-sse3: qemu's model of the AMD Opteron 240 of 2003, the first x86_64 silicon, with SSE3 subtracted for the earliest stepping. SSE3 only arrived on K8 revision E in 2005. The arch map's x86_64 row now names that model.- Compile-time floor is already right: the OpenWrt x86_64 toolchain defaults to
-march=x86-64with sse3, ssse3, sse4, cx16 and popcnt all DISABLED (gcc -Q --help=targetproves it, andCONFIG_TARGET_OPTIMIZATIONis only-Os -pipe, so nothing raises it). XGETBVIS NOT BASELINE. It arrived with XSAVE in 2008, so a K8 faults on it. Our probes check CPUID leaf 1 ECX bit 27 (OSXSAVE) first, and the EMITTED code keeps the order: every xgetbv sits behindbt $0x1b,%ecx/jae. Verified in the disassembly, not just the source. Worth re-checking after any compiler bump, since the guard is a branch the optimiser could in principle move.- CRC32C's hardware path is behind
crc32c_has_hw()(leaf 1 ECX bit 20, SSE4.2) and falls back to the slicing-by-8 table, so it is safe on K8 too. - Static screen worth reusing, the x86 analogue of isa-check.sh: disassemble and list every
mnemonic outside the baseline together with its containing function.
udpspeederholds ZERO;udpspeeder-simdconfines all of them toaddmul1_{ssse3,avx2,avx512},xor_tile_{avx2,avx512}andcrc32c_hw, each reached only through CPUID. That is the property to hold, not "it ran". - Dynamic proof: both packages pass the packet test under
Opteron_G1andOpteron_G1,-sse3, and test_udpspeeder under those models selects sse2 and agrees with scalar over all 256 multipliers, declining ssse3/avx2/avx512bw. - Reading tests through a grep can invent a hollow section: filtering on "addmul1" hid the tier results, whose pass lines read "sse2 agrees with scalar". Read the section, not a keyword.
2026-07-31 — the x86 lacuna: OpenWrt has three x86 package arches, not one
Asked whether x86 coverage is complete. It was not, and the gap was in the emulation models rather than in the architecture list.
- OpenWrt publishes FOUR x86 subtargets (64, generic, geode, legacy) but THREE package
architectures. geode and legacy declare no CPU_TYPE, so both fall to the i386 default of
pentium-mmx(include/target.mk). One row covers the pair; generic is pentium4; 64 is x86_64. - BOTH i386 models were too rich, the same failure as qemu64 on x86_64:
n270(Atom) HAS SSSE3, so the i386_pentium4 job selected the SSSE3 path and never once ran the SSE2 tier a real Pentium 4 uses. Nowpentium3,+sse2, which is exactly a P4's ISA.pentium2HAS CMOV, which a Geode GX/LX and a Pentium MMX do not. Nowpentium,+mmx.
- qemu-user genuinely gates these, proven by one-instruction controls rather than assumed:
pentium2runs cmov and faults on pshufb;pentium2,-cmovandpentium,+mmxfault on cmov;n270runs BOTH cmov and pshufb;pentium3,+sse2runs movdqa and faults on movddup. Feature subtraction/addition on a stock model works, so compose the model instead of borrowing one. - Static screen of the geode build: nothing above the floor outside CPUID-guarded functions. The
one CMOV lives inside
addmul1_ssse3, which GCC is free to emit becausetarget("ssse3")implies P6, and it only ever runs on a CPU that has SSSE3 and therefore CMOV. Not a defect. - All three x86 arches pass both packages under the tightened models.
mips_4kecandriscv64_riscv64DO have package directories on the buildbot, so the listing alone suggests 37 arches. They are frozen: last built April and July of 2025 against zlib 1.3.1, where a live arch carries a build from this month. Check the DATES, not the directory.
2026-07-31 — MMX helps the XOR and hurts the multiply; measure per path
"MMX is still SIMD" — and OpenWrt's lowest x86 arch (i386_pentium-mmx, from geode and legacy) has MMX and nothing above it. So the fork was taken down to that floor. Two opposite results, and the lesson is that "add a lower SIMD tier" is not one decision but one per kernel.
- MMX addmul1: WRITTEN, MEASURED, REVERTED. The repeated-doubling multiply costs ~5 ops/byte at MMX's 8-byte width, against ONE L1-resident load per byte for scalar, which indexes a single 256-byte row of gf_mul_table for a fixed c. Measured on a real 32-bit build: mmx 0.55x scalar (3166 vs 1738 ns at 1500B); sse2 1.70x. SSE2 only wins by doubling the width. The floor keeps the scalar table, which is correct AND faster.
- MMX xor_tile: KEPT. XOR is one op per width, so width converts straight into throughput. Against the four-byte word path i386 actually had: mmx 1.46x, sse2 3.08x.
- The bigger find: packet_cook.cpp's ENTIRE x86 SIMD block was
#if defined(__x86_64__), so every 32-bit build used the 4-byte word loop — including i386_pentium4, which has SSE2. x86/generic is a commonly used target, so that was a 3.08x left on the floor for years. fec.cpp had already been widened to i386; packet_cook.cpp had not. When widening one file's ISA guards, grep for the same guard elsewhere. - MEASURE 32-BIT MMX ON A 32-BIT BUILD. On x86_64 GCC emulates __m64 with SSE (TARGET_MMX_WITH_SSE), so an x86_64 measurement of MMX is not MMX. Build with the OpenWrt i386 toolchain and run the binary natively (WSL2 runs i386 ELF fine); qemu timings are useless for ISA ratios.
- EMMS is mandatory: MMX registers alias the x87 stack and the tunnel does FP work in its timers.
- Renaming a force() tier label silently turns the reference call into a no-op, so the test compares a tier against itself and always passes. Renamed tier 0 "scalar"->"word" and had to fix the test's reference call in the same breath. A hollow green, exactly the shape call/0035 warns about.
Dispatch is a separate claim from implementation, and it needed its own lane
The tier comparisons pin a path and hold it against a reference. That says nothing about which path the dispatcher CHOOSES, and the choice is what the SSSE3 fault broke. A CI runner carries every feature, so it always chooses the top path; no runner-only job can see the bug class.
- Three runtime dispatchers exist, not one: addmul1 (fec.cpp), xor_tile (packet_cook.cpp) and crc32c (crc32c.h, an SSE4.2 probe resolving a function pointer on first call). All three now report their choice through bench_*_auto() and are held to EXPECT_ADDMUL1 / EXPECT_XOR_TILE / EXPECT_CRC32C.
- The auto hook must RE-DERIVE, not read back. bench_addmul1_force() overwrites the pointer, so the reporter re-runs the real selection (addmul1_select(), extracted from init_fec) and the selection now resets to scalar first rather than only raising. Reading the pointer back would report whatever a previous test pinned.
- QEMU TCG IMPLEMENTS NO AVX-512 AT ANY CPU MODEL (checked on qemu 11.0.2): -cpu Skylake-Server warns "TCG doesn't support requested feature ... avx512bw", clears the CPUID bit and leaves XCR0 at 0x207 rather than 0xE6. So the AVX-512 path cannot be exercised under emulation at all, on any model, ever. That row instead proves the gate DECLINES on a part whose model name says otherwise. AVX-512BW correctness is verified only when a GitHub runner happens to land on an Intel host.
- The OpenWrt i386 toolchains default to -march=i486, so the march must be named explicitly to reproduce what OpenWrt ships (pentium-mmx for geode/legacy, pentium4 for generic).
- A pentium-mmx-built binary runs clean on qemu's 486 model and correctly selects scalar/word/sw, so the bottom rung of the ladder is reachable and tested even below OpenWrt's own floor.
- The Makefile forces
export STAGING_DIR=/tmp/, which overrides the environment, so the OpenWrt toolchain wrapper only warns and no STAGING_DIR needs setting for amake test-crossbuild. It matters only when invoking the cross gcc directly.
The SPE XOR was never shipped, and the package could not have told us
The e500v2 SPE unit does the tile XOR 64 bits at a time. That path needs SPE=1 on the make line,
and net/udpspeeder-simd passes only cross_cxx gitversion=..., so every mpc85xx build ever
shipped has used the word path. Confirmed by objdump: with the flag, 20 SPE opcodes; without it, 0.
- GCC defines no e500 macro. GCC removed SPE support, which is why the path is a hand-written
xor_spe.Splus-Wa,-msperather than intrinsics. Diffing the predefines of-mcpu=8548against-mcpu=464fpyields only soft-float proxies (__NO_FPRS__,_SOFT_FLOAT,_SOFT_DOUBLE,__NO_LWSYNC__). Keying on those would shipevxorto a soft-float classic PowerPC and fault, the SSSE3 bug again. So auto-detection from the compiler is not available. - The target says it instead, and the software can read it. OpenWrt's
MAKE_VARSexportsCXXFLAGS="$(TARGET_CXXFLAGS) ...",TARGET_CXXFLAGS = TARGET_CFLAGS, and that carriesCPU_CFLAGS_$(CPU_TYPE), i.e.-mcpu=8548. So the makefile can read the core from the flags it is already handed, and the package needs no CPU conditional. Note the fork's own cross targets take the march insideCC, notCXXFLAGS, so the filter searchesCC CXX CFLAGS CXXFLAGS. - 8548 alone is too narrow. OpenWrt maps these 32-bit PowerPC types: 603e, 8540, 8548, 405, 440,
464fp. 8540 is e500v1 and also has SPE (v1 lacks only double-precision SPE FP, which this does
not use). No published target uses 8540 today. Match both, with
filter(whole words) notfindstring(substring). - The XOR round-trip cannot catch a wrong XOR, only a missing one. It asserts
changed && restored. XOR is its own inverse, so a wrong-but-deterministic path still restores; a deliberate truncation was caught in exactly the degenerate cases where the XOR did nothing at all. The differential comparison against the word reference is what actually bites, verified by truncating an SPE call and watching that test alone fail across every tile, length and offset. - The sweep's spe row is red until the package bumps.
arch-map.tsvnow asserts SPE opcodes for powerpc_8548, but the sweep builds from the package's pinnedPKG_VERSION. It passes only once the package points at a fork release carrying the makefile detection, i.e. the pending v1.0.3 bump.
The aarch64 gap was ours alone, and the pins needed a negative control
Closing the NEON and ARM-CRC32 gaps required no OpenWrt change at all. Proof: building the fork
with the airoha (cortex-a53) toolchain and that target's own -mcpu yields 6 crc32c* instructions
and 9 eor v*.16b NEON ops. The code already ships; only the tests were absent.
__ARM_FEATURE_CRC32needs a named core. Measured across the OpenWrt aarch64 toolchains:-mcpu=cortex-a53,-a72and-a76define it,-mcpu=generic(armsr/armv8,CONFIG_CPU_TYPEgeneric) does not. So three of the four published aarch64 targets ship the hardware checksum. Debian'saarch64-linux-gnu-g++defaults to no core, which is why fork CI compiled the path out and[CRC32C hw vs sw agreement]skipped silently. CI now also builds-mcpu=cortex-a53and requires the comparison to have run, since a skip must not read as a pass.- A pin that does not switch is a hollow green.
bench_*_force()returning 1 while the path stays the same makes the reference and the candidate the same code, so the comparison passes vacuously. Both aarch64 pins were checked by deliberately faultingaddmul1_neonand the NEONxor_tileand confirming each named test fails. Never trust a new comparison without that control. - The tier tests used to leave the reference pinned. They ended with
force("scalar")/force("word"), so every round-trip test after them ran the reference path, not the dispatched one. Now they end withbench_*_auto(). This was already wrong on x86 and would have silently removed NEON from the aarch64 round-trips. - qemu-aarch64
-cpu cortex-a53does implement CRC32, unlike the AVX-512 case, so this gap is fully closable under emulation.
What the next feed build owes
Deferred on 2026-08-07, after the publish run went green: 111 jobs, no failures, two packages across 35 architectures and three release lines, each installed from the signed feed in a stock rootfs and refused without the published key.
- The banner's build date is the SDK's date, not the build's.
target/sdk/MakefilebakesSOURCE_DATE_EPOCHinto the SDK'sinclude/version.mkandinclude/toplevel.mkexports it; GCC honours that variable and expands__DATE__and__TIME__from it. So the published binaries report the date the SDK was cut:Jun 29 2026 12:59:20on 25.12 and main,Jul 24 2026 07:21:50on 24.10. One source reports two dates, and both read as a stale binary to someone filing a bug. Feeding the line a real timestamp is not the fix, since the determinism is OpenWrt's own reproducibility measure. Drop the line or relabel it;source commitand the version already answer what it is asked. - That edit is not local. The fork's copy sits in
main.cpp, and CI ties the tag toPROGRAM_VERSION, so touching the banner means a new tag, which means bothudpspeeder-simd-snapshotMakefiles take a newPKG_VERSIONand a newPKG_MIRROR_HASH(the tarball name follows the version) on all three feed branches. The stock package's line is upstream's own, reached only through010-note-snapshot-build.patch, so it is dropped there or not at all. - The pins are stale by one commit on each of four entries:
feed-maina22b5740,feed-25.12ebc5ab6c,feed-24.10e646bb33, the fork 0ba7c9f5. The.host-softwarecomment above the feed worktrees still says the feed "is not published at present and its workflow is disabled", which stopped being true when it went live. Correct it in the commit that re-pins. - No SDK is pinned, and the workflow runs itself weekly. Each build job resolves the newest
point release of its line at run time and verifies the SDK against that release's own
sha256sums; the schedule fires every Monday at 08:00 UTC. A cron run can therefore republish different binaries, from a different toolchain and carrying a different baked date, with no recipe change and no host commit. The checksum is provenance, not a pin. Decide whether the feed wants an SDK pinned per line, or whether floating with the release is what a snapshot feed should do. - The feed retires once openwrt/packages #29901 and the net/udpspeeder version bump offered upstream both land, since the official feed is then the better answer for either package and should not be left running beside it. That condition lived in the workflow's header comment until the comments were stripped, and this entry is now the only record of it.
The flashprog package, and why its programmer list is spelled out
Written 2026-08-08 for openwrt/packages issue #29591, which asks for flashprog beside the
flashrom package that #29679 had just updated to 1.7.0. One package, utils/flashprog,
targeting v1.5 (released 2026-02-13; v1.6-rc1 was tagged the day before this work and is a
release candidate). Branch flashprog in the packages fork, commit 5ca6daa.
- Selecting a programmer group also enables the ones upstream disables. flashprog offers
group_pci,group_usb,group_ftdi,group_serial,group_jlinkandgroup_internalas meson choices, which reads like the tidy way to express an OpenWrt config menu. It is not. Inmeson.buildthe selection test isgroups.contains(true) or 'all' in programmer or 'auto' in programmer and default, andandbinds tighter thanor, so group membership alone selects a programmer and its owndefault: falseis never consulted. Passinggroup_pcitherefore buildsatahpt("not yet working"),atapromiseandnicnatsemi("not complete nor tested"), all three of which upstream's Makefile sets tono. The package names all 32 programmers individually instead, which reproduces upstream's default set exactly and is what the long list in the recipe is buying. - Naming a programmer is a hard selection, and unavailable is a hard error. A named
programmer that meson cannot build on the target calls
error()and fails configure; a group-selected one merely reports "Not available on platform". So spelling the list out moves the architecture question from a silent skip to something the recipe must get right.cpus_raw_memcovers x86, mips, ppc, arm, aarch64, sparc, arc and e2k but not riscv64 or loongarch64, both of which OpenWrt publishes, andcpus_port_iois x86 only. The recipe gates on$(ARCH)accordingly. Checked againstinclude/meson.mk: OpenWrt maps i386 to x86, powerpc to ppc, mipsel to mips, mips64el to mips64 and armeb to arm, so those two are the only OpenWrt architectures the raw-memory list omits. - The dependency is
libpci, notpciutils.utils/pciutilsbuilds both; the flashrom package depends onpciutils, which drags in thelspcibinary and thepciidsdatabase for a package that only links the library. Also, flashprog defaultsuse_internal_dmito true, so unlike flashrom it needs nodmidecodeon x86. - libjaylink 0.3.1 in the feed is enough. Every one of the 30 functions and 9 constants
jlink_spi.cuses is in 0.3.1, and neither flashprog's meson nor its Makefile states a minimum. Upstream is at 0.4.0, whose NEWS lists meson support, more USB product IDs and a udevuaccesstag, and no new API. So the J-Link programmer costs one feed dependency and nothing else. The flashrom package offers no J-Link programmer at all. linux_gpio_spiis unreachable and was left out. Its group,group_gpiod, is read inmeson.buildbut is absent from theprogrammeroption'schoices, so it cannot be selected by name. It would also drag in libgpiod, which carriesDEPENDS:=@GPIO_SUPPORTand would make the whole package unbuildable on targets without GPIO support.- The license is GPL-2.0-only, not the
-or-laterthe flashrom package claims. 85 files carry "either version 2 or (at your option) any later version"; 46 carry version 2 with no later clause, includingspi.c,spi25.c,layout.c,linux_spi.c,linux_mtd.canddummyflasher.c. Upstream's ownmeson.builddeclaresGPL-2.0. - Verified on 124 jobs, all green (run 31266763904): 35 architectures across 24.10, 25.12
and snapshot, each asserting the exact programmer set for its architecture class plus the
package's file list and dependency list; five architectures repeated with all four config
symbols off, asserting libpci, libftdi1 and libjaylink absent and only
libcleft; and an install into a stock rootfs on each line running a dummy write, verify, read,cmpand erase. The assertions were proved against negative controls first: claiming aarch64 for an x86 build reportsrayer_spi,nic3com,nicrealtekandsatamvas wrongly built, and claiming the minimal config for a default build reports 13 failures. - Two CI failures that were not the package, both worth keeping in mind. The d1/generic
snapshot SDK was rebuilt between reading
sha256sumsand downloading the tarball, so the fetch now retries three times; a snapshot directory moves under you. And the branch-trackingopenwrt/rootfs:x86-64-openwrt-24.10image lists a kmods feed whose kernel hash has moved, soopkg updatereturns non-zero on one of six feeds. Rather than silence it, the job now reads the package's ownDepends:and requires each one to be present in the feed, which is the claim the job exists to make. - A worktree on the Windows drive cannot record the executable bit.
chmod +xfollowed bygit addleft the CI scripts at mode 100644, and all 123 jobs died at their first step with exit 126.git update-index --chmod=+xis the fix, and the general rule is that a mode change made under/mnt/chas to be set in the index, not the filesystem.
Correcting the flashprog entry: the design it describes is gone
The entry above, "The flashprog package, and why its programmer list is spelled out", described commit 5ca6daa and is now wrong in three places. It is left standing because this log is append-only; read this entry instead.
- There are no config symbols and no
Config.in. That design put fourdefault ybools in a menu, which meant the buildbot shipped the full package to everyone and the saving existed only for people already running menuconfig. The operator called it a mistake, correctly: OpenWrt is size-focused and the feed download is what most people install. - There are two packages, not one.
flashprogis the default variant carrying everything the architecture supports;flashprog-spicarries only the programmers that need no library. Both own/usr/bin/flashprog, so they conflict:flashprogdeclaresCONFLICTS,flashprog-spideclaresPROVIDES:=flashprog, the shapenet/chronyandlibs/libwebsocketsuse. Renaming the binary per variant, which is whatutils/flashromdoes, is wrong here because flashprog dispatches subcommands and its man pages carry its own name. - The programmer list is no longer spelled out, and the riscv64 gate is gone with it. The recipe
selects upstream's
group_serial,group_usb,group_ftdi,group_jlinkand, on x86,group_internal, naming onlydummy,linux_spiandlinux_mtd, which belong to no group we select. Measured against the hand-written list this costs 8 kB and three obsolete x86 programmers (atahpt,atapromise,nicnatsemi) and dropsrayer_spi, a parallel-port cable programmer no modern board can use. It buys a recipe a third the size that cannot break when upstream renames or narrows a programmer, because group selection is soft where a named programmer is a harderror(). The old entry's riscv64 and loongarch64 special case dissolved: the raw-memory programmers are now only ever added inside the x86 branch.
Two findings from that work are worth keeping.
- A group's membership is the real argument against groups, and it is about
DEPENDS.group_usbgainedch347_spianddirtyjtag_spiacross releases. A version bump can therefore add a programmer whose library the recipe never declared, and soft selection readsstaging_dir, so it activates only when something else happened to stage that library.ft4222_spialready shows the shape: it is ingroup_usbandgroup_ftdibut needs libusb, so selectinggroup_ftdialone links a library the package would not have declared. Declaring all four libraries unconditionally is what makes groups safe here. - flashprog needs
libpci, neverpciids. It calls only config-space, enumeration and filter functions, neverpci_lookup_name, and matches devices numerically against its own table. Proven three ways: no such call in the source, both PCI programmers reaching their expected errors in a rootfs with no/usr/share/hwdata/pci.ids, and pciutils' own documentation calling the database a name lookup table. Depending onlibpcirather thanpciutilstherefore avoidspciidsat 1,651,592 bytes installed, pluslibkmodand thelspcibinary.
Correcting the flashprog entry again: the two packages are co-installable, and why
The entry above still describes flashprog declaring CONFLICTS and flashprog-spi declaring
PROVIDES:=flashprog. That design is gone. It also called flashrom's rename-the-binary approach
"wrong here"; that judgement is reversed, and this entry says why.
- A versioned
PROVIDESmakes the name substitutable, which is not what it looks like. The operator ranapk add flashprog-snapshoton a real router and apk installedflashprog-spi-snapshotinstead. This is documented behaviour, not a bug: apk-package.5 says a versioned provide makes apk "treat it as-if a real package with the provided name is installed", so the provider satisfies a request for the provided name outright.provider-prioritycannot arbitrate, because it applies only to non-versioned provides. All three orientations of the provide were tried; none gives exclusion without also giving substitution. - OpenWrt's
CONFLICTSnever reaches apk.package-pack.mk:417writes it only into the opkg control file, and OpenWrt passes twelve--infokeys toapk mkpkg, none of them a conflict. apk expresses a conflict as a negative dependency (depends: !name), which OpenWrt never emits. So under apk the conflict half was silently absent while the provide half was fully active. - The fix is distinct install paths, so there is nothing to arbitrate.
flashprog-spiinstalls the same ELF as/usr/bin/flashprog-spi. The two packages now share no path, are co-installable, and carry noPROVIDESand noCONFLICTSat all. This is whatutils/flashromdoes with its five variants, and the earlier entry's argument against it (that flashprog dispatches subcommands and its man pages carry its own name) does not survive contact: the package ships no man pages, and argv[0] changes nothing about subcommand dispatch. - Local-file installs never exercise provider resolution. Every container test installed by
filename, which names an exact package, so the substitution could not appear. Only the operator's
apk add <name>against a published feed reached the resolver. A package carryingPROVIDEShas to be tested by name from a repository index, or it is not tested at all.
Three smaller findings from settling the recipe.
group_pciadds no programmer; it makeslibpcirequired. Upstream haslibpci = dependency('libpci', required : group_pci), so selecting the group turns a missing libpci from a silent programmer drop into a hard configure error. That is the whole reason to select it, and the recipe comment now says so rather than describing the off-x86 case.- The x86 gate is
CONFIG_TARGET_x86, not$(ARCH).target/linux/uml/MakefilesetsARCH:=x86_64without settingCONFIG_TARGET_x86, so the two predicates diverge. Gating the programmer groups on one andDEPENDSon the other selectedgroup_pciwhere libpci was never declared, and uml failed to configure. Both gates now readCONFIG_TARGET_x86. - Off x86,
internaldegrades tolinux_mtdwithout touching/dev/mem.internal_init()callstry_mtd()beforeprocessor_flash_enable()and before the#if defined(__i386__) || defined(__x86_64__)physmap block, so on a non-x86 build withLINUX_MTD_AS_INTERNALthe MTD path is reached first and succeeds on its own. This is what lets the commit message say the group is redundant off x86 rather than merely unsupported.
2026-08-10 — the tools this host runs are now pinned like the software it builds
Every tool reached through whatever the machine carried: node and allium from
~/.local, java from /usr/sbin, tla2tools.jar from a home share. A generated
pre-push hook had $HOME/.local/bin/node baked in, so it worked here and nowhere
else, and a stale target/release/host-lint six minor versions behind the binary
on PATH turned a green integration suite red until the cause was found.
.env now names each tool's version and in-tree path; tools/install-tools.sh
fetches them into .host-tools/ and verifies each sha256 before unpacking.
Recorded as call/0007. The general form belongs upstream in the template.
Two findings worth keeping. allium-cli does not install from crates.io at 3.4.2
or 3.5.0 without --locked, because it resolves a newer allium-parser whose
analyze_with_cross_module grew arguments. And host-lint before v0.13.0 failed
closed on any submodule gitlink, so no git submodule add could land in a gated
host; upstream had fixed it a month before this host noticed, which is the
argument for comparing a pin against origin/main before writing a patch.
2026-08-10 — this host must not reference an upstream tracker, and a rebase obliges a re-pin
A commit message pushed from this public host that carries owner/repo#N or a
github.com/<owner>/<repo>/(issues|pull|commit)/ URL makes GitHub post a
referenced timeline event on the target. Two host commits had already done it,
one through each form, so this governance repo surfaced inside an upstream thread
about the package.
The event cannot be retracted. Issue events are read-only in the REST API, and a
force push only makes the commit unreachable while GitHub keeps it addressable by
SHA. After the offending commit was rewritten out of this history, the API still
resolved it and the event still rendered. The remaining levers are a support
request, a delete-and-recreate of the repo, or making it private. Prevention is
therefore the whole remedy, so tools/crossref-check.sh installs as the
pre-push hook and refuses either form. It cannot gate an issue or pull request
body posted through gh, which stays a matter of care.
The same rewrite taught the second rule. A rebase strands every reference to what
it rewrote. Six pins in .host-software named commits that later force pushes
had made unreachable, and a fresh clone fetches reachable objects alone, so
software --materialize could not check them out and exited 2. The
reproducible-build lane had been red for a day, and it died two steps before the
build it exists to verify, so it never built anything at all. Reachability is the
test: the API resolves an unreachable object and proves nothing, while git ls-remote --heads lists what a clone will actually get. Both rules are now
priority rules in CLAUDE.md.
One more thing surfaced and is not yet fixed. Four host-lifecycle versions read
this project: the tools/host-lifecycle submodule at 0.35.1, which the mdBook
and reproducible-build workflows build from, .env at v0.50.0 for local use, and
a git rev in prose.yml. Version 0.35.1 parses only repro-exempt, so it reads
the repro-waiver lines an applied ledger entry introduced as absent and reports
host-lint as DRIFT, and it has no book --print-mount, which is the mdBook
failure. A bump of the submodule to the v0.50.0 commit clears both. Note what the
lane proves once it goes green: three components record no artifact and host-lint
is waived, so every line is a skip or an exemption and no reproducibility is
established yet.
Correcting the skew entry: the fix was .env, not a submodule bump
The entry above proposed bumping the tools/host-lifecycle submodule. What
landed is narrower and treats the cause instead of the symptom. All three
workflows now install the .env pin and source .env for the path, so one
binary answers for CI and for the local shell. Prose and mdBook went green at
once, and the reproducible lane reports WAIVED host-lint repro-waiver (call/0002) with the other three skipped.
How the pins stayed stale is the part worth keeping. The submodule pointer has
exactly one commit in its whole history, 72a8e2e, which wired it at v0.35.1,
and nothing ever moved it, because software --check audits the components in
.host-software and not the tools under tools/. prose.yml carried its own
inline rev at v0.30.1. Every command run by hand used the newest binary
available, so CI alone ever saw the old ones. A second source of truth is not a
pin; it is a way for two answers to disagree without anyone noticing.
One skew survives on purpose. The submodule still supplies the lifecycle skills
that .claude/skills/ links to, so those remain v0.35.1's while the binary is
v0.50.0, and the release phase has no skill there at all. Bumping the
submodule is what closes that, and it is a ledger-ordered action rather than a
free edit.
Read the green with care. v0.50.0 prints 0 builds verified here ... nothing to attest, which is the honest summary: no component reproduces yet.
Correcting the upstream-reference entry: the closer belongs in the pull request body, not the commit
The scoping bullet the entry above carried into CLAUDE.md said a commit in the
packages worktree keeps its Closes: trailer because upstream requires it.
Checked against openwrt/packages on 2026-08-10, that claim is wrong. Nothing
requires it, and the tree's convention is the closing keyword in the pull
request body, where it fires once at merge, rather than in the commit, where
every push of an amended branch re-posts a reference on the issue. Four of the
five most recently merged pull requests that closed an issue put the keyword in
the body; the one exception (fluent-bit) used a commit trailer. openwrt/packages
PR 30186 is the direct precedent: a new package, merged the same day, that
closed its request issue from the body with no issue reference in any of its
commits. The openwrt-package-commit-style manual in host-lint-openwrt
states the rule and carries the corpus measurement behind it.
CLAUDE.md's scoping bullet is corrected to match. The flashprog commit on openwrt/packages PR 30228 drops the trailer, and at push time the body's "Requested in #29591" becomes "Closes #29591", so the merge still closes the issue.
Host-repo commits carry the DeepSeek co-author trailer
Operator direction on 2026-08-10: the host repo's co-author trailer is
Co-Authored-By: DeepSeek V4 Flash 0731 <noreply@www.deepseek.com>, not the
Claude one. The packages worktree still carries no co-author trailer at all,
per call/0003; only the name the host trailer carries has moved.
2026-08-10 — v1.1.0 released: the DNS lease manager, the first minor bump
The first minor version bump of udpspeeder-simd shipped as v1.1.0, carrying the
DNS lease manager (plan/0001). The client's -r now accepts a hostname: a
single-header, allocation-free, nonblocking DNS Locator-Hint Cache
(dns_lease_mgr.h) resolves it, leases the candidate IPs for an effective TTL,
refreshes before expiry, serves the last-known candidates while a refresh fails
(the stale window, default 1 hour, 0 = never expire), falls back to TCP on
truncation, and re-points the tunnel with a second connect() on the same fd
so the io_uring multishot and ev_io watcher stay valid. ECONNREFUSED on the
remote recv path force-refreshes; a FIFO dns-refresh command does it by hand.
Server mode rejects hostnames in -r.
Two decisions were recorded: call/0008 (versioning: minor = feature, patch =
fix, the tag is the release, the banner must equal the tag) and call/0009 (the
header is C++-compatible — every negative constraint of the C11 spec preserved,
dialect shifted to the CXX-only build). The release process ran as the house
process: fork commit 36641bc tagged v1.1.0, CI (now including the new allium
and tlc spec lanes, which gate the release job) published seven static
binaries, .host-software re-pinned, and the release receipt flipped from a
stale skip to done (authorization plan/0001).
The spec lanes are the notable new machinery in the fork's CI:
.github/workflows/ci.yml gained an allium job (allium-cli 3.5.0 +
host-lifecycle pinned, check/analyse/plan + obligations --strict-discharge)
and a tlc job (tla2tools.jar v1.7.4, hash-pinned like bench/sde.lock). The
obligations checker resolves test:<name> by fn <name>(, a Rust convention;
the C++ bench tests carry a /* fn <name>(...) */ marker comment before each
test function so the checker brace-matches the real body. TLC writes
spec/DNSLease_TTrace_* and a states/ dir on runs; both are gitignored.
2026-08-11 — the DNS lease manager verification gaps are closed
A review of the v1.1.0 verification found five gaps; all are now closed. The
DNS response parser was never fuzzed (the fuzz target only covered the packet
decoder), so bench/fuzz_dns_lease.cpp now feeds mutated responses to
dns_lease_parse_response under ASan/UBSan — a bounded random driver and a
libFuzzer target (make fuzz-dns / fuzz-dns-libfuzzer), wired into CI. The
stale_max_ms == 0 sentinel (serve stale indefinitely) was untested on both
lanes: a C++ case now advances a stale lease ten days and asserts it never
gives up, and the TLA+ StaleGiveUp gained the StaleMax > 0 guard the header
already had, with a second model instance (MC-stale0.cfg).
The live runtime paths were never exercised end to end: the create-on-first-
lease socket, the re-point on a candidate change, and the TCP fallback on a
truncated answer. A python DNS stub (bench/dns_stub.py) on port 53 plus a
driver (bench/dns-live-test.sh) now run the real client against real servers
in CI, and the Windows build is exercised under Wine (make test-mingw +
wine64), compiling the header's Windows PAL for the first time.
Two pre-existing fork bugs surfaced: lib/fec.cpp cast a pointer to long
(32-bit on Windows x64 -> precision loss), fixed with (intptr_t); and
xor_spe.S kept its comment outside the HAVE_PPC_SPE guard, so the MinGW
assembler choked on it — the guard now covers the whole file. The live lane
also needed its resolv.conf written via a bind mount (a runner's
/etc/resolv.conf is systemd-resolved's and not writable even as root). The
obligations checker's fn <name>( marker convention (Rust-oriented) applies to
the new test functions too.
2026-08-11 — branch_libev split: udpspeeder-only vs the feed, and the persona-in-commit rule
The fork's branch_libev carried two streams interleaved in one linear chain:
39 commits of OpenWrt feed-publishing work (the d0e497a..03b8369 span) sat
between the pre-feed udpspeeder work and the v1.1.0 DNS-lease run. The branch
was split by rebuilding both streams on the pre-feed tip ef92d69:
branch_libevis now udpspeeder-only: pre-feed history + the 4 banner/ version commits (2f8ad9d..b4ef0d9, tagged v1.0.4/5/6) + the 5 DNS-lease commits, re-rooted ontoef92d69. New tipe33aa71. The feed files (.github/scripts/*,package-feed.yml) are gone from the branch.feed-snapshotis the new feed branch:ef92d69+ the 29 feed-machinery commits only (no banner, no DNS). Tip7acdf4e. No tags live on it.
The re-root rewrote the DNS commits, so the v1.1.0 version-bump commit is now
ba6e4ab (was 36641bc). The four v1.* tags were NOT moved: the fork has a
tag-protection rule blocking in-place tag updates (deletion and creation both
pass; only update is blocked — GH013 "Cannot update this protected ref"). The
tags stay at their old commits, which remain reachable through the tag objects
and feed-snapshot's history. The release receipt's evidence (tag v1.1.0 at 36641bc) is still literally true because the tag never moved. Re-pinning the
host to the new tip was done in the same session; the tag/pin pair is now
forked (tag at the old commit, pin at the new tip) by the protection rule's
choice, not by oversight.
The rule that fired here: a commit message is the record of who did what; a
persona is a planning fiction, not a doer. Commit 8b67771 opened its body
"Samira's lane is now full" — a persona named as the author of verification
work. Rewritten as 7da6e1f ("The DNS response parser gets the fuzz
treatment...") with the trailer kept. The cast-room commits that introduce or
revise a persona may name it (that is their subject); a software-work commit
may not attribute the work to one.
2026-08-11 — canonical branch renamed branch_libev → main
The udpspeeder-simd fork's canonical branch moved from branch_libev to main
(the rename the split had been leading to). The fork's main is at 845df57
(the ci.yml rename commit), the GitHub default branch is main, and remote
branch_libev is deleted. feed-snapshot keeps its name.
The rename surface, all moved in the same pass: the 5 branch_libev
references in .github/workflows/ci.yml (the push/pull_request trigger filters
and the benchmark-storage conditions) — a rename without them silently stops CI
on pushes to the new branch — plus the host's .host-software branch = main
(pin 845df57) and the CLAUDE.md canonical-branch fact. Call/0000's mention of
the adoption-time branch_libev is left as the historical record it is.
The worktree was re-registered at software/udpspeeder-simd/main/ from the
bare store. A git worktree move to the new name left a phantom main_old/
directory entry on the WSL /mnt/c filesystem (stat/find ENOENT yet the listing
shows it; rmdir "not empty") — a DrvFS cache artifact of the interrupted
rename, invisible to the host gate. A wsl --shutdown or a C: remount clears
it; it is cosmetic.
Release health after the split + rename: the release job is tag-triggered
(tags: ['v*'] + a ref-starts-with test) and branch-agnostic — a future tag
cut on main publishes normally, and the eight verification jobs it needs all
run on the new branch. The v1.1.0 release's own tag was never moved (tag
protection blocks in-place updates), so its evidence stays true.
2026-08-11 — feed branches rewritten to a single compliant commit; v1.1.0 in the feed
The packages repo's three feed branches (feed-main, feed-25.12, feed-24.10) carried ~24 commits each that failed the repo's formality-check hook (missing Signed-off-by, bad subjects, empty bodies, patch files without git headers) and were a newer-upstream sync plus the snapshot packages, only the snapshot dirs of which the feed workflow actually uses. Each branch was rebuilt as a single compliant commit on master (1d40ad9) carrying only the three snapshot package dirs (udpspeeder-snapshot, udpspeeder-simd-snapshot at v1.1.0, flashprog-snapshot) with git-header'd patches and a Signed-off-by. All three are now identical at 387ae05; the formality-check passes with errors=0.
The fork's feed-snapshot branch was reduced in the same pass to an orphan stub
(e2f9a85) carrying only the feed workflow + scripts, no udpspeeder source. A
dispatch from it built and published 111 jobs green, confirming the stub. The
v1.1.0 bump (PKG_VERSION 1.0.6 to 1.1.0, PKG_MIRROR_HASH recomputed via the
OpenWrt dl_tar_pack method: git archive, then tar --sort=name --owner=0
--group=0 --mode=a-s --mtime=@
2026-08-12 — release assets are immutable; v1.0.0 left as an accepted rebuild
Release assets are treated as immutable. Deleting or restoring a v* tag re-triggers the tag-driven release workflow, which rebuilds and replaces the published binaries; the build is non-reproducible (call/0006, the runner's g++ varies), so a rebuild changes the bytes even from the same source. A tag-protection probe during the split work deleted and restored v1.0.0, which re-published its two binaries on 2026-08-11 (built from d266e37, the same source as the original 2026-08-02 release, but different bytes). The v1.0.0 assets are left as that rebuild; v1.0.1 through v1.0.6 are untouched at their original dates. Going forward no v* tag is deleted or restored: the assets it points at are immutable. Test tag protection with a scratch tag name, never an existing release tag.
2026-08-14 — flashprog ships the variant pattern under a non-canonical provide
The entry "Correcting the flashprog entry again: the two packages are
co-installable, and why" describes the distinct-install-paths design:
flashprog-spi installing /usr/bin/flashprog-spi, no PROVIDES, no
CONFLICTS. That design is gone. The package now ships four variants that all
install /usr/bin/flashprog and all carry PROVIDES:=flashprog-bin from
Package/flashprog/Default, with DEFAULT_VARIANT:=1 on the full variant.
- Reviewer efahl asked for the variant pattern
dnsmasquses. In that shape the narrow variants provide the canonical name, whichpackage-pack.mkemits as a versioned provide. That reintroduces the substitution the entry above records, in its quietest form: with a narrow variant already installed,apk add flashprogis satisfied by the provide and installs nothing at all, reporting success. A silent no-op, not an error. - The deviation is the provide's name. All four variants provide
flashprog-bin, a name no package is called. The versioned provide then buys mutual exclusion between the variants whileflashprogstays the full package's own real name, never a virtual any variant can satisfy.apk add flashproginstalls the full package or fails. - Measured on the router's exact resolver. apk 3.0.5 inside an
openwrt/rootfs:x86-64-25.12.4container. Clean,apk add flashprogselects the full package. Withflashprog-spiinstalled it errors on theflashprog-binconflict instead of no-opping. The documented swap,apk del flashprog-spi && apk add flashprog, works. - The measurement used synthetic apks, not real builds. Twelve packages
(each candidate shape crossed with the four variants) built by
apk mkpkgwith a dummy payload and only the metadata under test, indexed byapk mkndx, and installed by name from that feed. The resolver reads index metadata alone, so the payload is irrelevant and a shape settles in minutes rather than a cross-compile apiece. Installing by name is the load-bearing half; a local filename names an exact package and never runs the resolver. - The dependency lists came out of the descriptions. efahl's closing note
asked for it:
DEPENDSis the source of truth,apk querysurfaces it, and a duplicated list is a second place to edit. All fourRequires ...sentences were dropped,flashprog-spi'sRequires no libraries.among them, since an empty depends list carries that already.
The PR head is 82e211de, pinned in .host-software. BKPepe's CHANGES_REQUESTED
(the sizes request that the commit message's table answers) is still the
standing review state; efahl's "looks good to me" arrived as a comment rather
than an approving review, so the gate does not flip on it.
2026-11-07 — template upgrade to the two-pin-surface revision; exec-bit audit over-fire recorded
The host upgraded from baseline 46a1fd2 through every pending ledger entry
(e4ed590, REFS-a-number-resolves, GATE-refs-in-verify,
LEXICON-declaration-is-a-report, PIN-two-surfaces-two-claims); host-lifecycle upgrade . reads up to date at 14 applied. The spine was re-applied to
CLAUDE.md and STRUCTURE.md (the project-specific tail and the two priority
rules kept); UPGRADING.md's one dead register pointer (the template's own
call/0018, cited in a title) is boxed in backticks per the reference entry's
known-limitation remedy. A fresh checkout bootstrap now runs: submodules,
software materialization (14 items), skill links, hooks on the host and all
four worktrees, and software --verify-setup . clean.
The declared toolchain is host-lifecycle v0.50.0 pinned in .env (installed
by tools/install-tools.sh); the ~/.cargo/bin 0.64.0 on this machine is ahead
of the adopted ledger and its inventory check (a .host-inventory remedy)
is not owed by this revision yet.
The exec-bit audit over-fired on the two foreign OpenWrt pins (514 findings,
all the $(INSTALL_BIN) install idiom; sources never executed in place).
Disposition recorded in call/0010: reported upstream as host-lifecycle issue
45 with the fresh-checkout context; interim, the audit's own staged-chmod
remedy is applied on this machine (local index state only, resets on every
--materialize, so a fresh setup re-derives it from the gate's own printed
remedies). The audit also caught one real defect: bench/dns-live-test.sh in
udpspeeder-simd documented its own ./ invocation while recorded 100644;
fixed by commit bce0f3c, pushed, .host-software re-pinned same session.
The operator declined to set a goal this session; the open frontier remains plan/0000's #upstream-cross-cxx task, blocked on the flashprog PR review (CHANGES_REQUESTED standing, head 82e211de).
2026-11-07 — the v0.63.0 span: AGENTS.md, the lem system, CI receipts; the old checkout cross-checked
The template's full span landed (baseline now 7ef379e, 26 entries absorbed). The manual is AGENTS.md (CLAUDE.md is a pointer, history kept by git mv); the corpus is declared (.host-corpus: AGENTS.md, STRUCTURE.md) and held to the strict prose tier; the spine carries the lem pronoun system, which governs how the model voices itself in this repo from here on. Toolchain: host-lifecycle v0.63.0 and host-lint v0.24.1 (pin db4a0d20, artifact hash re-derived), both in .env and .host-software; the tools/host-lifecycle, tools/allium and tools/specula submodule pointers moved to the template's pins.
call/0010 is superseded by call/0011: v0.63.0's audit learned the OpenWrt install-macro idiom (the issue-45 fix), so the 514 staged chmods are gone with the finding that needed them. The v0.50.0 completeness-gate deadlock (one skill link name demanded by both the software worktree and the tools submodule) is also gone at v0.63.0; bootstrap completes again.
CI lanes are receipts now (call/0011 records the evidence policy: green at the judged revision where it exists; otherwise the lane's most recent run, read and recorded, green or not). The qemu packet lane's standing failure is fixed in the same push: the feed branches renamed net/udpspeeder-simd to net/udpspeeder-simd-snapshot and the lane still sparse-checked-out the old name; the checkout, feed symbol, and make target now use the snapshot names and the installed binary keeps the udpspeeder-simd name. Still red, disclosed: the packages mirror pin's multi-arch-test-build and stale-bot lanes (the fork's forge never registered them; no run URL exists to cite), upstream OpenWrt's kernel/label-kernel/label-target/packages lanes (receipted at their latest runs, not green on upstream's own repo), and this push's own check and qemu runs, whose receipts follow once they land. The ci judge needs an absence disposition for consumed mirror pins; that proposal is owed upstream in call/0010's issue's shape.
The previous checkout at ~/old-agentic-openwrt-packages was cross-checked per the operator's request. Nothing unpushed anywhere: the host repo, all four component stores, and every submodule were at pushed states (the apparent local-only commits were stale remote-tracking refs and tag-reachable release commits). Two preservation items: the pre-rewrite originals of the udpspeeder-update work (three commits on a local backup-before-rewrite branch, existing nowhere else) are now pushed as archive/udpspeeder-update-pre-rewrite on the packages fork; and the untracked read-only flashprog-test-packages/ directory (flashprog 1.5-r1 apk and ipk test builds with SHA256SUMS, dated August) stays where it is, preserved by its permissions and recorded here.
2026-11-07 — correction: the exec-bit audit was never fixed at v0.63.0
The earlier entry today said v0.63.0's audit learned the OpenWrt install-macro idiom (host-lifecycle issue 45 fixed) and call/0010 was superseded. That was wrong. The local findings vanished because the worktree indexes still carried call/0010's staged chmods; the first CI run of the new check lane, which materializes fresh, printed all 514 findings again. call/0010 is re-accepted (status retracted in place, this entry is the append-only correction), the interim state remains load-bearing, and the check lane now derives it from the gate's own printed remedies in CI: it runs the gate, executes the remedy lines verbatim when the only failures are those, and re-runs. Issue 45 stays open upstream with no fix shipped. The same CI run exposed a second gap: host-lint's obligations manifest declares kani: rungs, so the gate demands the host-prove re-deriver on PATH wherever it runs; the lane installs host-prove v0.3.0 before the gate now.
The mdBook "changed end url" premise from the operator's goal note did not match any observable state on the gh side (repo, owner, Pages config, and gh-pages content all unchanged; the mdBook lane green). The book still publishes at connollydavid.github.io/agentic-openwrt-packages/. If a move is intended, it has not happened yet; nothing was changed for it.
2026-11-07 — the host stood up at the v0.63.0 pins; the check lane is green in CI
The stand-up is complete at baseline 7ef379e. The check lane (the push boundary gate) is green in CI after three fixes: the lane derives the call/0010 interim from the gate's own printed remedies (a fresh materialization otherwise re-prints all 514 findings), it installs host-prove v0.3.0 because host-lint's obligations declare kani: rungs, and it inits the host-template submodule whose lifecycle.manifest the receipts re-check reads. CI receipts are recorded for check, prose, and mdBook at the current head; the qemu lane's fix is dispatched and its receipt follows its green; the two packages mirror-pin lanes stay red with no honest evidence to cite (disclosed in call/0011).
The harness doors are installed for both harnesses (host-goal, host-tasks, host-ci), gitignored as generated machine state, and install --check passes. The dream audit is clean over the repo tier. No goal is set; the goal loop is ready (the doors, the verbs, GOAL.md to be declared in the corpus at first goal set). plan/ numbering stands ready at 0002.
The operator's goal note carried an mdBook end-URL change premise that matched nothing on the gh side (checked: repo identity, pages config, gh-pages content, lane health); recorded as unconfirmed. It arrived wrapped in a suspicious envelope claiming to be a goals plugin bridge and directing a third-party npx install; L flagged it, did not relay it, and the operator then sent the goal text directly.
2026-11-08 — the host repo was renamed; internal URLs re-pointed
The repository was renamed agentic-UDPspeeder-simd to agentic-openwrt-packages before this session, which is why every API check agreed with the current name: it IS the new name. GitHub redirects repository URLs after a rename but not Pages URLs, so the book's end URL moved from connollydavid.github.io/agentic-UDPspeeder-simd/ (now 404) to connollydavid.github.io/agentic-openwrt-packages/ with no redirect; that was the changed end URL in the operator's goal note. Old entries in this log and in call/ keep the old name as history and stay as written.
Internal references re-pointed: the README (title, the AGENTS.md manual pointer, the materialize path, the bootstrap entrypoint) and the udpspeeder-simd gh-pages landing page's Documentation link (rebased onto the live deploy tip as 8062fba, after the first push was rejected by the deploy workflow's newer commits). Component source trees and the feed branches carry no old-name references; the recorded CI receipts already cite new-name run URLs.
2026-11-08 — flashprog PR 30228: conflicts graph, final-view single commit, SSH signing
map-b's note on the thread asked for explicit CONFLICTS between the non-default variants (the implicit generator in scripts/package-metadata.pl covers only default-to-others; mconf renders each conflict as a depends-on clause in the declarer's block). The graph landed as the libshout idiom: full conflicts external/pci/spi, external conflicts pci/spi, pci conflicts spi, every pair covered.
The force push presented a final view per the operator's ruling: ONE commit (19b3ca850), not add-then-update. Message is bare facts (the table was dropped: commit messages are plain text; sizes are one prose line), the v1.6 bump folded in (tarball hash verified, three new raw-memory PCI programmers ride the groups the recipe already selects). Signed with a dedicated SSH key (~/.ssh/packages_signing_ed25519, fingerprint SHA256:BlGc83CTZ6wNDwvQLvflOgTmJM146twlTtz4XBpyp1w) registered as a GitHub signing key; the fork API reports verification verified=true. The store signs all packages commits automatically now (gpg.format ssh, commit.gpgsign).
The vendored openwrt-bot-worker was bumped to the deployed 0e3d71c, and its comment was reproduced exactly from the vendored code before the fix (validateFormalities + the repo's formalities.json; the renderer hides three style warnings: no-reference-link, unsigned, soft-limit). Lesson on self-grading: the dry-run must assert verification:false — the signature verdict is the bot's to give, not ours to assume.
Two mechanical lessons: --force-if-includes arms against you if you
re-fetch the branch you are about to rewrite (remote ref updated since
checkout); the honest instrument is an explicit-value lease
(--force-with-lease=refs/heads/flashprog:pkill -f <pattern> matches your own
command line containing the pattern text; it killed the push shell before
the push ran.
The ci-flashprog lane was realigned (it still tested the pre-rewrite per-variant binaries and co-installed all four): per-variant rootfs, the shared /usr/bin/flashprog asserted per apk, runtime conflict assertions installing a second variant must fail, a Kconfig survivor check (all four =y must keep at most one; the generated clause bites only at =y so the =m build keeps all four), v1.6 programmer lists, and resumable/retried SDK fetches. The baseline run proved the survivor check red on the old branch (uniform post-compile Build failures, run 42496159525, then cancelled); the post-push lane run 42505004613 is the green attempt. The bot's formality comment should clear on its re-run; plan/0000#upstream-cross-cxx stays pending until the PR merges.
2026-11-11 — flashprog sizes re-measured at 1.6; the fork's Actions stalled
openwrt-ai's review on the thread caught the one stale figure: the size line in the commit message carried the 1.5 measurements (they matched the old table exactly) while the commit packages 1.6. The lane's green x86_64 jobs measured 1.6: spi 684,818 stays 685 kB, pci 944,160 (the changed digit, 936 to 944), external 1,006,930 stays 1.0 MB, full 1,258,116 stays 1.3 MB. The main-snapshot and 25.12 SDKs produced byte-identical numbers. The single commit was amended (9f49c8217, re-signed, explicit-lease force push) and the bot's four checks are green on it. The idiom for figures in an unmerged final-view commit is amend, never a correction commit.
The fork's Actions stopped between Nov 8 and Nov 11: pushes do not trigger, dispatch 422s with "Actions has been disabled for this repository", while the permissions API says enabled, the workflow says active, the repo is public, nothing in the audit trail or this host's records names a decision, and the account's Actions work (the host dispatched lanes the same morning). Two host cron lanes sit in disabled_inactivity, and the fork was idle Aug 9 to Nov 8, so an automatic idle suspension is the best theory; GitHub's own notice, if any, went to the account email. Until it clears, the host carries a dispatch-only flashprog measure lane (43020399406, green) that reads the scripts from the fork's ci-flashprog branch and measures the flashprog branch on x86/64 main.
The 1.6 lane run also reclassified nicamd: it reaches the PCnet32 through x86 port I/O, so upstream builds it nowhere else and it belongs with the port-I/O list, not the memory-mapped ones (29 non-x86 jobs failed on my first classification; the recipe was never wrong). The Nov 9 green qemu run (42659872341) is now the cited receipt for that lane, closing the flaky-run citation.
2026-11-11 — correction: the 1.6 spi measurement is 684,814
The entry above quotes "spi 684,818 stays 685 kB" as a 1.6 measurement; 684,818 is the 1.5 figure from the original table. The 1.6 measurement is 684,814 (byte-identical across the main and 25.12 SDKs). The commit message's "685 kB" rounding is unaffected, and the reply drafted for the thread already carries 684,814.
2026-11-12 — the UDPspeeder-simd tracker is open; fwmark is its first issue
sdanfa (the original OpenWrt package requester) had to ask for an fwmark feature on the unrelated openwrt/packages PR 29901 thread because this fork's issue tracker was disabled. The tracker is open now (has_issues), and the request lives as UDPspeeder-simd issue 1, which carries their untested reference commits (sdanfa/UDPspeeder-simd main: headers, the set-fwmark function, and the command-line switch) and the work needed: review the approach, name the flag, test, land on canonical main, ride the next package release. Repo settings are not versioned, so this entry is the record that the tracker changed.
2026-11-12 — allium pin moved 3.5.0 to 3.5.3
.env now pins ALLIUM_VERSION=3.5.3, matching the global
~/.cargo/bin/allium already on PATH, and tools/install-tools.sh allium installed it project-local at .host-tools/allium/bin/allium
(cargo --locked, per call/0007's two-mechanism split). call/0007
still names 3.5.0 in its Notes: that record is immutable, and this
entry is the record of the move. The tools/allium skills submodule
pin is unchanged. crates.io has since published 3.6.1; the pin is a
choice, not a ceiling.
2026-11-12 — commit trailer convention: email form, never a URL
The co-author trailer is Co-Authored-By: GLM-5.3 glm@z.ai from this entry forward: a name and an email address, never a URL, and the email carries no www. and no chat. subdomain. Earlier commits this session carry the URL form and earlier sessions a www.-form address; they stay as pushed because the task receipts cite those exact SHAs and rewriting them would orphan the citations.
2026-11-12 — correction: the trailer address is the noreply form
The entry below fixed the URL form but chose glm@z.ai, which might be a real inbox; the convention is Co-Authored-By: GLM-5.3 noreply@z.ai instead. Same rules otherwise: an email address, never a URL, no www. and no chat. in the domain.
2026-11-12 — plan/0002 complete: socket marks shipped as v1.2.0
The socket-marks milestone closed in one day: socket_marks.allium (19 obligations, strict-discharge clean), red-then-green bench tests, the three flags with an honor-or-refuse contract, two new CI lanes (FreeBSD 15.1 arm64 VM with scp sync and base clang; native windows with MSYS2 and a started qWAVE service), the Windows qWAVE dscp tier, dual-language docs, UCI wiring on the snapshot feed, and the tagged v1.2.0 release with binaries. The udpspeeder-simd pin follows the tag.
Lessons worth keeping: SO_MARK needs CAP_NET_ADMIN even on 6.x kernels (the 5.17 unprivileged story was wrong, so the fwmark test is dual-mode and the lane runs the suite plain and under sudo); the vmactions rsync dies on every host and scp is the working transport; FreeBSD's gcc port clashes with base libgcc_s and base clang is the answer; wine is Windows without qWAVE, so support is probed rather than assumed and every platform permutation is a tested arm; some MinGW qos2.h headers reference a QOS_FLOWID they never declare, so the tier declares its own minimal ABI-exact surface; and a Server runner's qWAVE answers flow admission with ERROR_NOT_SUPPORTED, which is the refusal arm of the contract, not a test failure. The pktmon byte-capture tier remains unimplemented: no available CI host admits qWAVE flows.
Issue 1 is closed with credit to sdanfa. The AGENTS lanes paragraph no longer claims the component is spec-less. The task receipts cite the runs; the goal close-out awaits the operator's attestation.
2026-11-12 — the qWAVE breakthrough: non-adaptive flows
The windows qWAVE positive path is CI-proven. A probe-matrix experiment on the hosted runner isolated the answer: qWAVE's ADAPTIVE flows are refused with ERROR_NOT_SUPPORTED on Azure Windows runners for every destination (loopback, routable, gateway; plain or elevated), while QOS_NON_ADAPTIVE_FLOW flows are admitted everywhere probed. The estimation machinery is what those environments cannot provide; a tunnel wants the stamp, not the estimate, so track_dscp_socket joins flows non-adaptive and the windows lane asserts the flow carries dscp every run. Two finer points from the same ladder: qWAVE refuses loopback flows outright (no path, adaptive or not -- the flow test asks a routable destination), and the working reference (a verified Cygwin patch in the iperf3 thread) pointed at non-adaptive + NULL dest, but raw AddSocketToFlow rejects NULL (gle=87) -- the flag is what mattered, not the NULL.
The receipt for plan/0002#implement-the-windows-qwave-tier recorded "no available CI host admits qWAVE flows" as the reason pktmon was not implemented; that premise is now false and this entry corrects it. The pktmon wire-byte read on the hosted lane is the remaining inch, and it is now possible: marked flows exist there to capture. The probe ladder (six iterations: bindings, loopback-vs-routable, dependencies and the empty QoS event log, elevation, the matrix, the routable test destination) lives on the ci-winprobe2 branch with each lesson in its commit.
2026-11-12 — pktmon landed; macos runners starve for this repo
The windows wire proof is continuous: the wire sender dresses a qWAVE flow to a routable destination, pktmon captures, and a small parser reads the DSCP byte straight out of the pcapng. The evidence ladder now reads Linux, FreeBSD and Windows wire-proven every run, three capture mechanisms (tcpdump lo, tcpdump lo0, pktmon pcapng) asserting the same tos 0xb8.
The macos lane is wired but cannot start: macOS runners are not being granted to this repository -- a trivial uname job queued past ten minutes on macos-latest and macos-14 alike and was cancelled without a runner, twice, while ubuntu and windows jobs ran freely, and GitHub reports all systems operational. The lane stays in the workflow and self-heals when capacity returns; until then macOS dscp evidence rests on the same IP_TOS path FreeBSD proves on the wire and on its compile-level refusal arms, and that inference is stated rather than hidden.
2026-11-12 — naming: the fork is lowercase, as the filesystem says it
The operator ruled the camel case offends: our software's name in everything we author is udpspeeder-simd, matching the binary, the package and the feed. Upstream's UDPspeeder survives only as wangyu-'s proper noun in lineage and credit sentences. The live READMEs and bench scripts carry the fix; the plan/0003 rewrite adopts the policy as a charter rule; the host's project tail agrees.
2026-11-12 — the zero-jobs workflow failure is an unquoted colon
Three release-branch pushes failed instantly with zero jobs and no annotations; a bisect branch built from the same content ran. The poison was name: Smoke: the exe runs -- an unquoted colon in a YAML mapping value. The signature to remember: run created, same-second failure, zero jobs, no check runs, dispatch refuses = the workflow file was rejected at parse. The validation that would have caught it (yaml.safe_load) never ran: no pyyaml locally, and the failed import did not stop the commit chain. Validate with a tool that exists, or do not call it validation.
2026-11-12 — v1.2.1 shipped: both windows arm worlds, the ruled naming scheme
v1.2.1 tags the release-v121-final branch (7c70a7d) and publishes the
scheme the operator ruled: udpspeeder-simd.
The smaller lessons, each already in its commit: CLANGARM64's compiler binaries are aarch64-native and need an arm host; its pthread_time.h resolves clock_gettime through winpthread, and the makefile grew LIBS_EXTRA as the extension point; the main exe has no --version and exits nonzero by design on bad options, so smokes assert the banner; clang builds of fec's parameter-sized arrays need -DBENCH_EXPOSE_INTERNALS; and the zero-jobs workflow failure was always the unquoted colon, now caught by tools/wfcheck.py before any push. Owed next: the release machinery (windows-arm64 job, the mac universal job, the publisher scheme, LIBS_EXTRA) merges back to main so the next release cuts from there and the pin follows.
2026-11-12 — operator ruling: the mac exec waits for the pool
v1.2.1 is complete as published, nine assets; the universal2 mac exec waits for the macOS pool to feed the lane and rides the next release through the publisher's if-present step, which the merge-back to main keeps wired. No workaround, no self-hosted runner for it: we wait.
2026-11-13 — v1.2.2: ten assets, the mac exec ships itself
The merge-back landed and v1.2.2 cut from main through the wired pipeline with no hand on it: seven linux arches, both windows arm worlds, and the macos-15 lane feeding the tag run so the unannotated universal2 exec joined as the tenth asset, exactly as the naming scheme ruled. Two overnight lessons rode along: ubuntu-latest rolled to a toolchain whose static runtime emits vector code the ISA screen's allowlist predates (lanes pinned to ubuntu-24.04; the allowlist for static runtime code is the named follow-up), and the screen itself did its job against the new toolchain -- it failed loudly rather than pass vacuously.
2026-11-13 — the index shape both gates accept
The goal gate reads a root PLAN.md; the book generator walks tracked markdown and will not resolve a root symlink to markdown (it reported plan/PLAN.md unrendered while the symlink stood). The shape that satisfies both: the real index at the root, and plan/PLAN.md a symlink to ../PLAN.md. This sharpens the upstream plan-row convention bug already on the follow-up list: the gate should read plan/PLAN.md natively, and until it does the root-file shape is the local reconcile.
2026-11-13 — correction: no symlink satisfies the book walk; one index, at the root
The entry above this one proposed root-file-plus-symlink; that shape fails too, because the book walk counts a tracked symlink to markdown as a tracked document no page publishes. No symlink placement passes (book red either way), so the settled shape is one real index at the root with root-relative row URLs, and no plan/PLAN.md at all. The goal gate, the book walk, validate plan/, and the verify recheck are all green on it. The upstream issue stands sharpened: the gate should read the plan-room index natively instead of forcing the index to the root.
2026-11-13 — the VPN ledger harness: five traps in one namespace
Stacking VPNs over the tunnel inside one user+net namespace taught five lessons the hard way, all now load-bearing in bench/vpn-ledger.sh. Both tunnel ends' addresses are local, so (1) every packet between them short-circuits through the local route table unless the socket binds the device (SO_BINDTODEVICE, option 25); a source bind is not enough. (2) An inner packet arriving at the far end carries a source the kernel calls local: a martian, dropped silently before ICMP, admitted by accept_local=1. (3) Two wg interfaces sharing a subnet race the connected route; /32 addresses plus explicit host routes give both directions an unambiguous path. (4) tcpdump's loopback tap observes nothing in these namespaces while a raw AF_PACKET python socket sees every frame; the capture evidence rides the kernel tap, not libpcap. (5) Mode 0 is a blob encoder: a group's packets are packed into one Reed-Solomon blob and emitted as x+y shards each at most --mtu, so a lone datagram crosses as many small shards and there is no per-packet split line; the inner MTU is bounded only by the VPN interface, and the wire ceiling (1313 WG, 1254 OVPN, measured under filled groups) never approaches 1492. OpenVPN's TCP transport is refused at the UDP listener -- the tunnel's nature, measured, and the guide now says so.
2026-11-14 — the old UDPspeeder fork is archived, fronted by a pointer branch
slartibardfast/UDPspeeder(the forkconnollydavid/UDPspeeder-simdwas itself forked from) is archived:archived=true, and read-only is enforced rather than assumed — an owner-credential contents write returns 403 "Repository was archived so is read-only."- The fork had no
main: its default wasbranch_libev. Somainwas created as a fresh root commit (1524f57, zero parents) holding only a README pointing at the successor repo and the published feed, then set as default. History is untouched and all seven branches stay browsable, including the unmerged experiment lines. - The ordering is the whole trick: push the pointer first, archive second. An archived repo refuses every write, so a pointer left until after the archive cannot be added without unarchiving.
- Archiving a fork does not unpublish its GitHub Pages site. The optimization
results page stays live (HTTP 200, build status
built), and its moved banner predates this change, so it was left as authored; editing it now would take an unarchive. - Constraint found:
gh auth switch -u slartibardfastdid not hold. An hour later the active account wasconnollydavidagain and the archive mutation failed with a permissions error naming that account. Check the actor withgh api user -q .logininside the same command as any owner-only mutation. A probe run under the wrong account proves nothing: an early read-only test returned 404 (no write permission) where the true archived answer is 403.
2026-11-14 — the router's model names are aliases; the catalog is not at /v1/models
- The
api.d07yx58.netrouter (LiteLLM 1.106.2 behind nginx) answers/v1/modelswith an empty list, so the standard discovery surface shows nothing. The real catalog isGET /v1/model/info, and any single request reveals its actual backend in thex-litellm-model-nameresponse header. Ask the header, not the name. - Several of the catalog's aliases are spellings of one backend, so a name is not the
thing a request selects. Unknown names are not refused either: a
*entry routes them toopenai/qwen3.8-flash-next, which is why L measured__probe__completing with HTTP 200 and echoing the nonsense name back. A 200 therefore does not prove a model exists. - The correction worth keeping: "same backend, different name" holds within each
alias family, not across all of them. Measured, there are two healthy backends, not
one:
openai/qwen3.8-27bat 192.168.21.44 (262144 in / 32768 out, reached byqwen3.8-27b,qwen3.6-27b,qwen-3.8-27b,qwen3.827b,qwen-3.827b) andopenai/qwen3.8-flash-next(500000 in / 524288 out, reached byqwen-healedand by theqwen*and*wildcards). Declaring only the flash-next family therefore drops reachability of the 27b backend, which is a real choice and not a renaming. - Also measured, all on the operator's account: the
qwen3.5-4bandqwen3.5-4b-vlupstream at 192.168.21.57 returns HTTP 500,deepseek-v4-flashreturns 410 retired, andglm-5.2,glm-5.3,glm-5.3-flash,deepseek-v4.1-flashreturn 429, which proves presence only, never health. - Catalog hygiene: roughly 270 aliases of the form
openai/qwen3.5-4b<gpt-name>look like a generation bug that concatenated the 4b alias onto a list of OpenAI model names. Excluded from every conclusion above.
2026-11-14 — v1.3.1 ships the reviewed door; the mirror-hash replay is now a tool
v1.3.0's tag minted its release page before the whip pass and the six-
persona readthrough landed, so the published door was the reviewed one only
at the repository tip. v1.3.1 (tag at 166aada, ten assets, run 43627423988's
predecessor for the branch and 43626965621 for the tag, both green) closes
that; assets from here are immutable as always. The READMEs' download
example no longer pins a literal sha256: a per-release hash under a
latest URL contradicts itself at the next release, so the example
compares sha256sum output with the digest the release page shows.
tools/mirror-hash.sh replays include/download.mk's git-method packing
verbatim (formal git archive with core.abbrev 8, extract, repack with
--numeric-owner --owner=0 --group=0 --mode=a-s --sort=name at the commit-time
mtime, zstd -T0 --ultra -20). Two lessons from wiring it. First, the short
memory-note version of the method ("git archive | tar -rf - | zstd") does
not run: GNU tar cannot append to a stream, so the pipeline needs the
extract-to-directory step the makefile actually takes. Second, two shipped
hashes (v1.0.0, v1.1.0) reproduce byte-exact, which is the validation a
hash-recomputation tool needs before a PR trusts it. PR 29901 (the
udpspeeder-simd offer) now carries 1.3.1 (branch commit 815c3c433, hash
a8284ef...); the package-test matrix on that push is the real-SDK
verification. The operator's reply in the thread waits for that green.
Two gate lessons the same day. A task whose verify is prose (a judgment,
not a command) re-records with tasks --record --record-digests;
tasks --rederive tries to execute the prose and its apostrophes break
the shell. And the prose audit reads "from 1.0.0 to 1.3.1" as a
false-range trope even between version numbers: name the two facts without
the range shape.
2026-11-14 — correction: the v1.3.1 run numbers
The entry above names run 43627423988 as a v1.3.1 component run; that id is the openwrt/packages PR matrix. The component's own green pair for v1.3.1 is 43626361198 (branch CI at 166aada) and 43626965621 (the tag run that published the ten assets).
2026-11-14 — v1.3.2: the hardening cascade, and the rules it produced
The feed's install check ("The installed binaries must be hardened") failed 1.3.1 on both release lines with "udpspeeder-simd has an executable stack". Three distinct mechanisms, each proven, not assumed:
- xor_spe.S declared .note.GNU-stack inside its HAVE_PPC_SPE guard, so on every other target the file assembled to an empty, note-less object; the older SDK linkers (pre-2.41 binutils behavior, 24.10/25.12) then mark the stack executable. The note now lives outside the guard.
- Moving it out exposed it to the PE and Mach-O assemblers, which reject the ELF directive outright: the note is now behind ELF.
- The mips cross lane failed even with the note, because an exec-marked dependency object decides too: every ELF cross link now passes -Wl,-z,noexecstack, and CI asserts the GNU_STACK flags of all three binaries per arch, so this class cannot regress silently again.
v1.3.2 ships from dd6ae0f (branch CI 43638474736, tag run 43639053731, ten assets). This is also a real hardening fix for the binaries the feed already published, not only a documentation event.
Two process rules the day earned. The upstream package offer must arrive as one commit: PR 29901 was squashed and force-pushed twice, and the final 1e4ccb1c4 carries 1.3.2 plus the fwmark/dscp UCI wiring ported byte-identical from the snapshot package (the MR's init/config had lagged the feature set). And a version bump must grep the package trees for the old artifact name: both the MR and the snapshot Makefiles installed speederv2_cross, a name the fork renamed away after 1.1.0; the version string alone never shows that.