Linux VM testing

Use a real VM only when the behavior depends on a Linux kernel or guest OS. Prefer Docker for userspace-only clean-cache/config experiments and ci-adhoc-test for unavailable architectures, distributions, or release-platform proof.

Two local backends serve different purposes:

• Lima landlock-vm: persistent Ubuntu arm64 debugger with the host home mounted read-only.
• Tart: disposable Ubuntu arm64 guest for clean-machine or alternate-image reproduction.

Preflight

Inspect both backends before changing VM state:

limactl list
tart list
limactl shell landlock-vm -- bash -lc \
  'uname -srm; . /etc/os-release; echo "$PRETTY_NAME"; df -h "$HOME" /tmp'

Confirm the source mount before treating it as writable:

limactl shell landlock-vm -- bash -lc \
  'findmnt -T /Users/colinmcd94/Documents/projects/nub'

The known Lima mount is read-only. Never build in /Users/colinmcd94/**. If the guest disk is full, report it and ask before reclaiming space. Never stop, delete, or clean an existing VM merely to make room.

Persistent Lima debugging

Run a short probe synchronously against the exact host source state:

limactl shell landlock-vm -- bash -lc \
  'cd /Users/colinmcd94/.cache/nub/worktrees/<worktree> && <probe>'

Trace a guest command without modifying the host checkout:

limactl shell landlock-vm -- bash -lc \
  'strace -f -o /tmp/nub.strace -- <command>'
limactl shell landlock-vm -- bash -lc \
  'bpftrace -l "tracepoint:syscalls:sys_enter_*" | head'

For a Linux Rust build, copy the exact source state into guest-local storage and use a guest-only target directory:

limactl shell landlock-vm -- bash -lc '
  mkdir -p "$HOME/src" "$HOME/.cache/nub/linux-vm-target"
  src=/Users/colinmcd94/.cache/nub/worktrees/<worktree>
  dest="$HOME/src/nub-<slug>"
  rsync -a --delete \
    --exclude .git --exclude target --exclude node_modules \
    "$src/" "$dest/"
  cd "$dest"
  export CARGO_TARGET_DIR="$HOME/.cache/nub/linux-vm-target/<slug>"
  cargo build -p nub-cli --profile fast
  cargo test -p nub-cli --test <test_stem>
'

Repeat the copy after host edits. Use the exact host worktree under test, a distinct guest target for each branch or probe, and direct Cargo commands because the copied tree intentionally omits Git metadata. Remove only probe-owned files after capturing evidence; do not sweep guest caches or unrelated targets.

Start or stop the persistent VM only when required:

limactl start landlock-vm
limactl stop landlock-vm

Clean Tart reproduction

Let the checked-in helper own lifecycle:

tests/vm/tart-vm.sh up <name> <image>
tests/vm/tart-vm.sh exec <name> -- bash -lc '<probe>'
tests/vm/tart-vm.sh run <name> ./probe.sh
tests/vm/tart-vm.sh down <name>
tests/vm/tart-vm.sh rm <name>

Use a unique VM name. The run operation copies one script when sshpass is installed and otherwise streams its body; it does not copy a fixture tree or checkout. Fetch or copy multi-file fixtures deliberately. Finish a throwaway run with rm; down intentionally preserves the disk.

Evidence

Record:

• Host commit plus dirty-state summary.
• Guest distro, kernel, and architecture.
• Exact command and environment overrides.
• Exit status, stdout, and stderr.
• Relevant trace or log path.

Copy concise results to the host before deleting a Tart guest. Do not claim x86_64 coverage from these Apple-Silicon arm64 VMs. Use ci-adhoc-test when the claim requires x86_64-native behavior or another unavailable platform.

Windows VM testing

Operate the existing VM; do not provision one. The known-good guest was Windows 11 ARM64 under QEMU/HVF at /Volumes/Plex/nub-winvm, with host port 2222 forwarded to guest SSH. The VM tests win32-arm64 natively and win32-x64 under emulation. True win32-x64-native behavior requires windows-latest through ci-adhoc-test.

Fail-closed preflight

Run read-only checks first:

VM_ROOT=/Volumes/Plex/nub-winvm
test -d "$VM_ROOT" || {
  echo 'Windows VM disk unavailable; use ci-adhoc-test or restore the external volume.' >&2
  exit 1
}
test -r "$HOME/.ssh/nub-winvm" || {
  echo 'Windows VM SSH key unavailable.' >&2
  exit 1
}
command -v qemu-system-aarch64 qemu-img >/dev/null || {
  echo 'QEMU tooling unavailable.' >&2
  exit 1
}
find "$VM_ROOT" -maxdepth 1 -type f -print
pgrep -alf 'qemu-system-aarch64|install-loop|win11' || true
lsof -nP -iTCP:2222 -sTCP:LISTEN || true

Stop if the disk, its runbook, or its own lifecycle helpers are absent. Do not mount a missing volume, reconstruct QEMU arguments, create a disk, or reprovision Windows as part of this skill.

VM lifecycle

Read the restored runbook and invoke its exact start, stop, and snapshot commands. Before launch, prove that no other QEMU process owns win11.qcow2. Never run competing QEMU or installer loops against one disk.

The historical clean-snapshot command is evidence, not a default action:

cd /Volumes/Plex/nub-winvm
qemu-img snapshot -c clean win11.qcow2

Create or apply a snapshot only while the VM state matches the restored runbook. Never guess a snapshot-restore sequence.

SSH readiness

Gate readiness on a guest command, not an open forwarded port:

SSH_OPTS=(
  -i "$HOME/.ssh/nub-winvm"
  -p 2222
  -o StrictHostKeyChecking=no
  -o UserKnownHostsFile=/dev/null
)
SCP_OPTS=(
  -i "$HOME/.ssh/nub-winvm"
  -P 2222
  -o StrictHostKeyChecking=no
  -o UserKnownHostsFile=/dev/null
)

ssh "${SSH_OPTS[@]}" nub@localhost \
  'powershell -NoProfile -Command "$PSVersionTable.OS; $env:PROCESSOR_ARCHITECTURE"'

Record the reported OS and architecture with every result.

Transfer and run a probe

Copy only the binary, script, and fixtures the probe needs into the remote user's home:

NUB_EXE=/absolute/path/to/nub.exe
test -f "$NUB_EXE"
file "$NUB_EXE"
shasum -a 256 "$NUB_EXE"

scp "${SCP_OPTS[@]}" "$NUB_EXE" nub@localhost:nub.exe
scp "${SCP_OPTS[@]}" ./probe.ps1 nub@localhost:probe.ps1
ssh "${SSH_OPTS[@]}" nub@localhost \
  'powershell -NoProfile -ExecutionPolicy Bypass -File "$HOME\probe.ps1"'

For a Rust failure, preserve the exit code while capturing a backtrace and log:

$ErrorActionPreference = 'Stop'
$env:RUST_BACKTRACE = 'full'
$env:RUST_LOG = 'debug'

& "$HOME\nub.exe" <args> *>&1 | Tee-Object "$HOME\nub-probe.log"
$code = $LASTEXITCODE
Write-Host "EXIT_CODE=$code"
exit $code

Use Get-Command nub -All, where.exe nub, Get-Item, and Get-Acl for resolution or filesystem diagnostics. Kill only processes created by the probe.

Run the Windows survey

After the runbook's clean-snapshot restore, copy and run tests/windows/papercut-survey.ps1:

& "$HOME\papercut-survey.ps1" `
  -NubBin "$HOME\nub.exe" `
  -WorkDir "$HOME\nub-papercut" `
  -OutputJson "$HOME\nub-papercut\results.json"
exit $LASTEXITCODE

Retrieve nub-papercut/results.json and any focused log before stopping or reverting the guest.

Evidence and CI boundary

Record the host commit, guest build/architecture, binary architecture, exact PowerShell invocation, exit status, stdout/stderr, and retrieved artifacts. The local ARM VM does not prove x64-native behavior and is not a clean hosted runner. Invoke ci-adhoc-test for a fresh Windows environment, x64-native behavior, unavailable local storage, or release-platform evidence.

Audit threads

An audit is a distinct thread profile — alongside the implementation thread and the research thread — whose deliverable is a CLEAN, COMPLETE, VERIFIED list of real gaps between nub and a reference it claims parity with. A single false positive surfaced to the maintainer destroys trust in the whole audit; the bar is zero garbage.

Canonical methodology + rationale: AGENTS.md → "Audit threads — a distinct thread profile." Read that section first — it holds the full WHY and the named scars. This skill is the OPERATIONAL surface: the gate checklist, the dispatch template every audit sub-agent must receive verbatim, the orchestration shape, and the running learnings log. (Same split as the prose-writing skill ↔ PROSE.md: the skill never re-derives the canonical doc, it operationalizes it.)

The 5 gates (checklist — AGENTS.md is canonical)

1. Pin the reference target surgically. State the EXACT major (e.g. pnpm 10). VERIFY every reference checkout's version before reading it (git -C .repos/<tool> describe --tags, its package.json version, the installed tool's --version). Wrong-major reference = #1 garbage source. When the AUDIT TARGET is a branch/SHA of THIS repo (not a reference tool), git fetch origin FIRST and pin origin/<branch>@<sha> — never a local worktree/branch checkout, which routinely lags origin. Verify the pinned SHA is reachable (git merge-base --is-ancestor <sha> origin/<branch>) before reading a byte; auditing a stale local pin = the same wrong-target garbage as a wrong-major reference.
2. Empirical over source. A candidate is not a finding until a differential fixture reproduces it by RUNNING the real pinned tool + nub on identical input and diffing. Source/--help reading = leads only.
3. Cross-check the decision record. Deprecated/removed flags, npm-isms nub rejects, the deliberate pnpm-compat divergences, and already-decided/already-built work are NOT findings. Filter against AGENTS.md "Core design positions", wiki/ decision docs, and prior .fray/ threads.
4. Mandatory adversarial self-refutation. Fresh-context reviewer(s) must try to REFUTE each surfaced finding by re-pinning, re-reproducing, and re-checking the decision record. They must also challenge any claim that a gap is irreducible by exhausting the relevant mechanism's documented alternatives and testing plausible closures. Default to refuted when uncertain. Surface only survivors, each with reproduction evidence; never forward the raw breadth-pass output.
5. Tier + deliverable. Opus/Fable high+ for judgment AND refutation (Sonnet/Haiku may harvest breadth, but every item is Opus-verified). Thoroughness is two-dimensional: COVERAGE (enumerate the FULL surface from the pinned reference's own authoritative source) AND PRECISION (every item verified). Catalog → wiki/research/<topic>.md with all buckets explicit (real gaps / confirmed-OK / intentional-divergence); each finding records reproduction + decision-record cross-check + severity + confidence.

Orchestration shape (in order)

enumerate the full surface (coverage) → harvest candidate gaps → cross-check the decision record → reproduce each against the pinned real tool (empirical) → adversarially refute in fresh context → surface ONLY survivors, with evidence.

Run it as a fray thread with individually-dispatched agents (an Opus audit lead that fans its own breadth/reproduction/refutation L2s, or orchestrator-driven L2s one stage at a time) — NOT a blind parallel Workflow fan-out that buries the gates.

Companion lens — impact analysis when a finding is ACTIONED. An audit is investigation-scope (recommend-only); it surfaces gaps, it does not land fixes. But the moment an audit finding becomes a code change, that change runs the standard significant-change self-review — which MANDATES at least one impact-analysis pass tracing the fix's blast radius through the codebase (see the impact-analysis skill + AGENTS.md). A parity fix that touches a shared verb/flag dispatch path routinely ripples to sibling commands; the impact-analysis lens is what keeps the fix from regressing them. Gate 4's adversarial refutation is about whether a FINDING is real; impact analysis is about whether a FIX is safe — distinct lenses, both required at their respective stages.

Dispatch template (every audit sub-agent prompt MUST be self-contained — the L2 starts fresh)

You are running a <SCOPE> audit: find where nub diverges from <REFERENCE> <EXACT MAJOR> on <SURFACE>.
This is an AUDIT — the deliverable is a CLEAN, VERIFIED list of REAL gaps. A single false positive is
unacceptable. Follow all 5 gates; do not skip any.

GATE 1 — PIN: The target is <REFERENCE> <EXACT MAJOR>. BEFORE reading anything, verify the version of
  every reference you use: `git -C .repos/<tool> describe --tags` and its package.json version, and
  `<tool> --version` for any installed binary. If a checkout is the wrong major, check out the right
  tag / install the right version FIRST. State the verified versions at the top of your output.
  If the AUDIT TARGET is a branch/SHA of THIS repo (not a reference tool): `git fetch origin` FIRST,
  pin `origin/<branch>@<sha>` (NEVER a local worktree/branch — it routinely lags origin), and verify
  `git merge-base --is-ancestor <sha> origin/<branch>` before reading. State the pinned SHA at the top.
GATE 2 — EMPIRICAL: A gap is NOT a finding until you reproduce it by RUNNING <REFERENCE> <MAJOR> AND nub
  on identical input and diffing the actual output. Source-reading and --help parsing are LEADS only.
  Build a minimal differential fixture per candidate; capture both commands + both outputs.
GATE 3 — DECISION RECORD: Drop any candidate that is a deprecated/removed flag in <REFERENCE> <MAJOR>,
  an npm-ism nub deliberately rejects, one of nub's intentional pnpm-compat divergences, or already
  decided/built. Cross-check AGENTS.md "Core design positions", wiki/ decision docs, and .fray/ threads.
  Deeply evaluate what has ALREADY been discussed — surfacing a settled call is as bad as a false positive.
GATE 4 — REFUTE: After harvesting, re-verify every surviving candidate adversarially (try to REFUTE it:
  re-pin, re-reproduce, re-check the record). Treat "irreducible" or "cannot close" as claims that also
  require evidence: exhaust the documented mechanism surface and test plausible closures. Keep only
  what survives, with its reproduction evidence.
GATE 5 — COVERAGE + PRECISION: Enumerate the FULL surface from <REFERENCE> <MAJOR>'s own authoritative
  source (its --help / source), so nothing is missed; AND verify every surfaced item. Output ALL buckets:
  real gaps / confirmed-OK / intentional-divergence. Each real finding: reproduction command + both
  outputs + decision-record cross-check + severity + confidence.

Deliverable: a catalog at wiki/research/<topic>.md (all buckets) + a tight triaged list of REAL gaps for
the maintainer. Investigation-scope — do NOT land fixes; surface findings recommend-only.

Learnings log — append a dated bullet for each NEW pitfall an audit reveals; map it to the gate it strengthens

• 2026-06-26 (pnpm-CLI-compat, first run — the scar): read .repos/pnpm at v11.3.0 against a pnpm-10 target → flagged lowercase -d/-e/-o as "missing" when pnpm 10 uses uppercase -D/-E/-O and lowercase means other things there. → Gate 1 (verify the reference version before reading).
• 2026-06-26: asserted npm_config_loglevel "not honored" from source-reading; FALSE — npm_config_loglevel=silent pnpm install → zero output, pnpm honors it. → Gate 2 (reproduce against the real tool, never infer from code).
• 2026-06-26: counted deprecated / npm-ism / already-decided flags as gaps, inflating ~112 raw candidates that collapsed to ~1 real. → Gate 3 (cross-check the decision record before surfacing).
• 2026-06-26: surfaced the raw breadth-pass output without an adversarial re-verification pass → the catalog was mostly false positives. → Gate 4 (refute in fresh context; surface only survivors with evidence).

download-stats — pull nub's download numbers into CSVs

One command generates the CSVs:

node scripts/download-stats.mjs            # writes tmp/download-stats/*.csv
node scripts/download-stats.mjs --npm-only # skip the gh-authenticated GitHub half
node scripts/download-stats.mjs --out <dir> --package @nubjs/nub --repo nubjs/nub

Outputs:

• npm-daily.csv — one row per day since first publish: the meta package, each @nubjs/nub-<platform> package (auto-discovered from the meta package's optionalDependencies), platforms_total, and a running cumulative for the meta package.
• github-releases.csv — per-release, per-asset cumulative download counters, stamped with snapshot_date. Re-running appends (replacing any same-day rows), so repeated runs accumulate the time series GitHub itself never provides.

Channel map — where a nub install actually lands

The two channels are fully independent; summing them does not double-count. Within GitHub assets, brew / curl / nub upgrade are indistinguishable — the per-asset platform split is the only lens.

Granularity and gotchas (the reasons this skill exists)

• npm: daily is the finest granularity. api.npmjs.org/downloads/range/<start>:<end>/<pkg> returns UTC-day buckets; there is no hourly API. A single request caps at ~18 months — the script stitches windows, so all-time works regardless of age.
• npm lags ~2 days. The trailing day(s) read 0 until npm's batch job runs; the script trims trailing zero-days so charts don't show a fake cliff. Don't quote "yesterday" from npm.
• Per-version npm splits have no history — api.npmjs.org/versions/<pkg>/last-week is a trailing-7-day snapshot only.
• GitHub asset counters are cumulative-only. No history endpoint exists; a time series only exists if you snapshot repeatedly (hence the append behavior). Deltas between snapshots = downloads in that interval.
• Exclude .sha256 assets when quoting GitHub numbers. Every release ships a checksum file per tarball and installers fetch them; they inflate the raw sum ~15%. Filter asset !~ /sha256/ for the real binary count.
• The meta npm package is the canonical "installs" number. Platform packages roughly mirror it (each install pulls exactly one) but diverge on lockfile-driven CI, which can fetch platform tarballs at different rates — use them as an OS split, not a total.
• npm counts are registry downloads (CI, mirrors, bots included), not unique users or machines.

git-archaeology

Instant playbook for "when did X land / leave / change?" questions. The goal: skip the meander, get the answer in one command.

Recipes

1. Pickaxe — when a string/symbol entered or left history

# All commits that changed the COUNT of <string> in a path:
git log --oneline -S'<string>' -- <path>

# First introduction (oldest commit):
git log --oneline --reverse -S'<string>' -- <path> | head -1

# Most recent change:
git log --oneline -S'<string>' -- <path> | head -1

# Include all branches:
git log --oneline --all -S'<string>' -- <path>

Use when: finding the commit that added or removed an exact symbol, flag string, function name, or config key. -S counts occurrences — it fires when the count changes.

2. Pickaxe by regex / diff content

git log --oneline -G'<regex>' -- <path>

Use when: -S misses a change because the string appears in both old and new (count unchanged), or when you want to match a pattern across added/removed lines (e.g. -G'--experimental-shadow-realm' to find every commit that touched that flag in any form).

3. When a file was DELETED

# Find the commit that deleted a specific path:
git log --oneline --diff-filter=D -- <path>

# Find deletion of any file matching a name glob (across all branches):
git log --oneline --diff-filter=D --all -- '**/<name>'

# Cross-check the surrounding context:
git show <sha> -- <path>

Use when: a file exists in memory or docs but is absent from the tree — find when it was dropped and what the commit message says.

4. Follow renames

git log --follow --oneline -- <path>

Use when: a file was renamed and git log -- <path> shows a short history that obviously predates the file's true age.

5. Line-range history

# History of lines matching a pattern (N lines from match):
git log -L'/<pattern>/',+<N>:<file>

# History of a fixed line range:
git log -L<start>,<end>:<file>

Use when: tracing exactly when a specific function body, feature flag block, or config stanza was introduced or changed — avoids reading the whole file log.

6. What a specific commit changed (scoped)

# Full diff scoped to a path:
git show <sha> -- <path>

# Summary of what the commit touched:
git show --stat <sha>

Use when: you have a SHA from a pickaxe result and need to see the exact diff.

7. Who/when a line came in (blame)

# Blame a line range:
git blame -L<start>,<end> <file>

# Blame + full patch context (expensive but thorough):
git log -p -L<start>,<end>:<file>

Use when: you need the author + date for specific lines, or want the full patch history for a code block.

8. Date and subject of a commit

git log -1 --format='%h %cs %s' <sha>

Use when: a pickaxe returned a SHA and you need the short date (%cs = YYYY-MM-DD) and subject without extra noise.

Combo: "when did X land in code vs site?"

# In implementation code (crates/, runtime/):
git log --oneline --reverse -S'<string>' -- crates/ | head -1

# In marketing/docs (site/, README):
git log --oneline --reverse -S'<string>' -- site/ README.md | head -1

A gap between these two dates = the feature was advertised before (or after) it shipped. The code date is the authoritative answer to "when did it land."

Methodology — lessons that cost time

Pickaxe the implementation, not the marketing surface

site/, README.md, and docs may list a feature aspirationally from the initial commit. Searching there answers "when was it promised," not "when did it ship." To answer "is X implemented / when did it land?", pickaxe:

• crates/ — Rust implementation
• crates/nub-core/src/node/flags.rs and spawn.rs — flag injection (the authoritative source for "is a Node experimental flag active by default")
• the feature matrix or capability table in code, not in docs

Concrete burn: most homepage API names traced to "Initial commit" — all misleading, answered intent not state.

A feature on a marketing surface may have been removed later

A positive pickaxe hit on site/ does not mean the feature ships today. Always run the delete check and a grep for "deferred"/"removed"/"dropped" before concluding it's live:

git log --oneline --diff-filter=D -- '<feature-file>'
git log --oneline --all --grep='deferred\|removed\|dropped' -- '<area>'

Concrete burn: connect() appeared on the homepage but runtime/connect-sockets.mjs was deleted 2026-05-26 and the feature deferred.

For "what was recently unflagged?" — target the flag-injection layer

# Find all commits that touched experimental-flag injection:
git log --oneline -G'--experimental-' -- crates/nub-core/src/node/flags.rs crates/nub-core/src/node/spawn.rs

# Pickaxe a specific flag:
git log --oneline -S'--experimental-shadow-realm' -- crates/

Cross-reference .fray/*-unflag.md / audit threads for the decision record. This makes "what was recently unflagged?" instant rather than a multi-file meander.

Concrete answer this should make instant: shadow-realm + wasm-modules were unflagged together in PR #31.

Distinguish three states — they are not the same

Always check which state is actually being asked about before searching.

Always consider --all for deleted or branch-resident content

Deleted files and features that were developed on a branch and later dropped may only appear in non-main history. Add --all to any pickaxe or --diff-filter=D search when the expected result isn't turning up on main.

History rewrites change SHAs but not content — pickaxe by string still works after a force-push because it searches diff content, not commit identity.

md-toc — markdown navigation via line ranges

When a markdown file is large (>200 lines), don't Read the whole thing. Run the TOC script first to see every heading and its section's line range, then use Read with offset + limit to jump straight to the section you need.

Invocation

The executable is a repository tool, not a resource nested under this skill directory. Resolve the checkout root explicitly before invoking it so the command works even when the skill itself was discovered under .claude/skills/:

repo_root="$(git rev-parse --show-toplevel)"
node "$repo_root/scripts/md-toc/index.mjs" <file.md>
# or equivalently:
nub "$repo_root/scripts/md-toc/index.mjs" <file.md>

Resolve <file.md> from the task's working directory. Do not look for .claude/skills/md-toc/scripts/md-toc/index.mjs; that nested path does not exist.

Output format

One line per heading, indented by depth, with the section's line range:

L1-402    # Nub — Final-Polish Orchestration Tracker
L152-192    ## Status board
L282-367    ## Item cards
L284-292      ### A — Settle/verify env-plumbing  ·  todo

The range L152-192 means the "Status board" section occupies lines 152–192. To read it:

Read(file, offset=152, limit=41)   # limit = end - start + 1

A heading's section spans from its own line to just before the next heading of equal or higher level (or EOF). # lines inside fenced code blocks are correctly ignored (uses a real markdown AST parser, not regex).

When to use

• Any file >200 lines where you need one section, not the whole file.
• HANDOFF/STATUS trackers, AGENTS.md, architecture docs, long epics.
• Before dispatching a sub-agent that needs a slice of a large doc — run the TOC yourself, embed the relevant offset/limit in the prompt so the agent Reads precisely.

Plan threads

A plan thread is one of the four fray thread profiles, alongside the implementation thread (build-the-decided-thing), the research thread (find-out-what's-true → wiki/research/), and the audit thread (verify-parity → wiki/research/, see the audit-thread skill). Its deliverable is a settled design / approach — not code, not findings, not a gap catalog. It is the thread you open when how to do something is the open question.

The defining property: the deliverable is the DESIGN

A plan thread's work IS the thinking. You'd staff it with the human and/or a Plan/architect agent (Claude Code's Plan agent type) — never an implementer, because there's nothing settled to implement yet. Its ## Open questions are the live work; its ## Decisions accrete as questions resolve. When the design locks, the plan thread's job is done and an implementation thread takes over.

Status lifecycle (fray)

• A plan thread carries status: planning (the fray status for "design-in-progress"; see the fray skill for the vocab). It is non-terminal but parked — it is NOT auto-surfaced in the per-turn / stop-hook nag (only enqueued/active/blocked nag the orchestrator). You pull a plan thread up deliberately via the fray board when you choose to work it — it does not chase you. (Legacy plan/todo/needs-decision are still accepted as read-aliases — plan/todo→planned, needs-decision→blocked — but write only the canonical words.)
• THE TRANSITION RULE (load-bearing): a plan thread flips to planned the moment the design is LOCKED — open questions resolved, approach decided, only implementation remaining. Planning ends by promoting to planned (or straight to active if you dispatch the implementer that turn). A plan thread that has no open design questions left but is still status: planning is mis-statused — promote it.
• Distinguish from blocked: that's waiting on ONE specific human yes/no. planning is the broader ongoing design with multiple open questions being worked collaboratively.

How to run a plan thread

1. Create the thread FIRST (per fray: the .fray/<slug>.md exists before any dispatch), status: planning. Write the Goal (the objective + why) and seed ## Open questions with the real unknowns.
2. Work the open questions — with the human (a plan thread routinely carries human-owned decisions: defaults, product behavior, API/config surface, architecture) and/or by dispatching a Plan/architect agent or a focused research/audit sub-thread to get the facts a decision needs. Ground every design claim in code or an experiment, never memory (the probing-methodology discipline).
3. Move each answered question to ## Decisions the instant it's settled — a decided thing lives under Decisions, never lingering in Open questions. The thread always reads as current truth (no changelog).
4. Lock the design + hand off: when the approach is settled, record the final design in ## Decisions, write the implementation handoff in ## Next step (what an implementer should build), and flip the status to planned (or dispatch the implementer and go active). The implementation thread inherits the locked design.

Boundaries with the other profiles

• A plan thread that needs a FACT to decide → spin a research or audit sub-effort, fold the result back, keep deciding. The plan thread owns the decision; the research/audit owns the fact.
• A plan thread does NOT land code. The instant code should be written, the design is locked → it becomes a planned/implementation thread.
• Don't let a plan thread become a place to park indefinite "someday" design — if it's not being actively worked toward a lock, it's either planned (scoped, awaiting actioning) or should be dismissed.

Anti-redundancy with planned

planning and planned are NOT the same parked state: planning = the design itself is still the work (you'd dispatch an architect or talk to the human); planned = the design is DONE and the next dispatch is an implementer. The whole point of the split is to tell, at a glance, whether a parked thread needs thinking or building. Keep the boundary crisp by always promoting planning→planned at design-lock.

pm-perf-tracing

How to performance-trace the nub package manager (install/resolve/fetch/link) and find where the time actually goes — the method that cracked the hoisted-linker slowness (10.8s → root-caused to a per-file copy loop). Reach for this any time a nub install / PM operation is "mysteriously slow" — do NOT reverse-engineer from source; the instrumentation already exists, turn it on.

The two layers that already exist

1. Phase timings — works under nub TODAY. RUST_LOG=debug nub install emits phase:<name> <elapsed> lines on stderr: phase:resolve, phase:fetch (N packages), phase:link (N files), phase:link_bins. This alone tells you the coarse split (is it network/resolve, or linking?). The aube engine wires these through the tracing crate.

2. Rich diagnostics layer — native under nub via NUB_DIAG_*. aube_util::diag emits structured JSONL to NUB_DIAG_FILE=<path> — including, for the linker, one event per file naming the strategy used (link_clonedir, link_reflink, link_macos_small_copy, link_copy, link_hardlink). This is the load-independent crux for a link-perf question. The full knob set (all off by default, zero cost when unset):

   • NUB_DIAG_FILE=<path> — JSONL events to a file.
   • NUB_DIAG_PRINT=1 — live per-span lines to stderr.
   • NUB_DIAG_SUMMARY=1 — end-of-run aggregate table.
   • NUB_DIAG_CRITPATH=1 — retain records for the critical-path / lifecycle / starvation analyzers.
   • NUB_DIAG_THRESHOLD_MS=<n> — filter live prints below <n> ms.
   • NUB_DIAG_KERNEL=1 — getrusage kernel deltas around phases.
   • NUB_BENCH_PHASES_FILE=<path> — per-run phase-timing JSON for the bench harness.

cargo build -p nub-cli --profile fast        # dev binary at <worktree>-target/fast/nub
NUB=<worktree>-target/fast/nub
NUB_DIAG_FILE=/tmp/d.jsonl NUB_DIAG_SUMMARY=1 "$NUB" install --offline
grep -o '"name":"link_[a-z_]*"' /tmp/d.jsonl | sort | uniq -c     # per-strategy tally

(The diag layer reads NUB_DIAG_* under the nub embedder profile via the diag_env_prefix hook — no source edit needed. AUBE_DIAG_* is NOT read under nub. The dev-tracing-telemetry thread / wiki/research/dev-tracing-telemetry.md tracks the optional chrome-trace/flamegraph export layer on top.)

The measurement discipline (load-independent — this host is permanently contended)

The dev box runs load ~30–50 and never goes quiet, so absolute wall-clock is untrustworthy. Measure things contention can't ruin:

• Verified-clean warm loop: rm -rf node_modules and assert it's gone, warm store already populated, --offline (proves zero network: phase:fetch shows 0 packages), and check rc=0 on every run (a timing from an errored install — e.g. npm's rm: Directory not empty purge failures → rc=254 — is garbage).
• Strategy tally, not seconds: "75,079/76,167 files took link_macos_small_copy, 0 took link_clonedir" is a fact regardless of load. That's what proves a design gap.
• Back-to-back A/B on the same box, report the RATIO: e.g. hoisted vs --node-linker isolated on the same fixture, same load window → the relative delta (≈26×) is robust even when both absolutes are inflated.
• For a real clean wall-clock number, hand it to a quiet machine / CI runner — never block on this box settling.

Layout matters — always check which linker path runs

nub mirrors the incumbent layout: an npm/yarn/bun lockfile → hoisted layout (link.rs → hoisted::link_hoisted_importer); nub-identity / --node-linker isolated → isolated layout (materialize_into, the only path with the whole-dir clonefile(2) fast path). They have completely different perf characteristics. When a perf question is about linking, run BOTH (--node-linker isolated vs default) and diff — that A/B is what localized the hoisted-linker gap.

When spans aren't enough — sampling profiler

Span/JSONL instrumentation can distort a syscall-bound, parallel pass (observer effect). For "where inside the link phase do the syscalls go" use a sampling profiler on a release build: samply record -- <NUB> install --offline (macOS/Linux), or cargo flamegraph. Spans tell you which phase/strategy; the sampler tells you which syscalls/functions dominate.

Fixtures

• /tmp/coffee2-demo — CoffeeScript 2.0.1, npm lockfileVersion:1, 519 pkgs / ~76k hoisted files. The canonical heavy-hoisted-layout fixture.
• A minimal hoisted repro: a package.json + package-lock.json with webpack@3.6.0 + underscore (no node_modules).

The one-liner to remember

RUST_LOG=debug nub install for the phase split; if it's phase:link, set NUB_DIAG_FILE=… for the per-file strategy tally; A/B against --node-linker isolated; judge by strategy-tally + ratio, never the contended absolute.

todo — parse status-box todo lines from markdown

When a todo file is long, run the parser to extract just the items you care about instead of loading the whole file.

Convention

Every todo line carries a status box, optionally after a list marker and indent. Six markers:

- [ ]  todo / not started
- [/]  in progress
- [x]  done  (case-insensitive)
- [-]  cancelled / dropped
- [>]  deferred / forwarded
- [?]  question / blocked-on-answer

Lines inside fenced code blocks are excluded. Each item is tagged with the nearest enclosing ##/### heading as its section context.

Invocation

node scripts/todo/index.mjs <file.md> [flags]
# or equivalently:
nub scripts/todo/index.mjs <file.md> [flags]

Flags

--pending, --todo       show [ ] items only
--in-progress, --wip    show [/] items only
--done                  show [x] items only
--cancelled, --dropped  show [-] items only
--deferred              show [>] items only
--question, --blocked   show [?] items only
--not-done              live actionable set: [ ] + [/] + [?]
                        (excludes done, cancelled, and deferred)

--section <substring>   limit to todos under headings matching substring
--counts                print tally (all six categories) and exit
--json                  machine-readable JSON array

--help, -h              usage

Flags are combinable. If no status filter is given, all statuses are shown.

Output format

L 7  [ ]  Write contributing guide [Setup]
L11  [ ]  Implement parser [Features]
L12  [/]  Write lexer [Features]
L20  [x]  Handle fenced code blocks [Edge cases]

L<n> is the 1-based line number — use it with Read(file, offset=n, limit=1) to jump straight to a line.

--counts output:

pending:      5
in-progress:  2
question:     1
deferred:     1
done:         4
cancelled:    1

--not-done is the fastest way to reconstruct "what's left to act on" after a context reset — [?] (questions) count as actionable (answer them); [>] deferred and [-] cancelled do not.

Examples

# Quick status check on a long epic
node scripts/todo/index.mjs epics/v0.1/todo.md --counts

# Everything not yet done in a specific section
node scripts/todo/index.mjs epics/final-polish/todo.md --not-done --section "Work units"

# All in-progress items as JSON (for a sub-agent prompt)
node scripts/todo/index.mjs epics/v0.1/todo.md --wip --json

When to use

• Before loading a long todo file — run --counts to see the shape, then --not-done to get only the open work.
• When building a sub-agent prompt that needs the open items from one section: --pending --section <heading> gives the exact slice without embedding the whole file.
• Combine with md-toc when you also need to navigate prose sections of the same file.

Use nub, not node / bun / the package manager

This project runs on nub — a single Rust CLI that runs on the project's installed Node and replaces the everyday Node toolchain: file runner, script runner, package/CLI runner, package manager, and Node version manager. nub augments Node through Node's own public extension surfaces (module.registerHooks(), --import preload, flag injection), so your code stays plain Node code — there is no nub runtime, no nub global, no nub:* import namespace, no config field to author, no lock-in. If nub vanished, the code runs on plain Node unchanged.

Prefer nub over node, bun, npm, npx, pnpm, and yarn.

Command map

Running files — nub <file>

A flag-for-flag drop-in for node <file> (same argv, same flags, same behavior — --inspect, --import, --max-old-space-size, stdin -, everything passes through), plus these augmentations with no build step and nothing to configure:

• Full TypeScript + JSX — .ts/.tsx/.mts/.cts/.js/.mjs/.cjs/.jsx run directly via an oxc transpiler. Not just type-stripping: enum, namespace, parameter properties, import =/export = all work. JSX defaults to the automatic runtime (react); configure via tsconfig.json jsx/jsxImportSource or a per-file pragma. Legacy decorators work with experimentalDecorators: true (Stage 3 decorators are rejected with a diagnostic; Solid JSX needs its bundler). nub does not type-check — keep tsc --noEmit in CI.
• tsconfig.json paths — compilerOptions.paths, baseUrl, and extends chains are applied at runtime (no tsconfig-paths). Extensionless .ts imports and .js→.ts rewrites (for moduleResolution: nodenext) resolve like tsc. Configs are read once per process — restart after editing.
• .env files loaded automatically (no dotenv, no --env-file). Loaded from the nearest package.json directory, before Node starts. Full precedence, highest first: shell env (always wins) → .env.${NODE_ENV}.local → .env.local → .env.${NODE_ENV} → .env. Under NODE_ENV=test, .env.local is intentionally skipped (Next.js convention — dev secrets don't leak into tests). Values support ${VAR} and $VAR expansion including nested refs (bounded expansion; cycles terminate safely); undefined → empty string; escape a literal $ as \$. (Passing --env-file=<path> disables the automatic .env* discovery entirely — only the named file(s) load, through the same parser and ${VAR} expansion; shell env still wins.)
• Data-format imports — import cfg from "./config.yaml" works like import data from "./data.json". Extensions: .json, .jsonc, .json5, .toml, .yaml/.yml, .txt. Default export = parsed value; destructure it for top-level keys. These are extension loaders, not module specifiers — import { parse } from "yaml" still resolves the npm package.
• Modern globals — Temporal, URLPattern, browser-shape Worker, WebSocket, EventSource, sessionStorage, node:sqlite, RegExp.escape, etc. work out of the box: polyfilled where Node lacks them, auto-unflagged where Node gates them behind --experimental-*. Availability is version-banded per the running Node — do not assume an exact floor; check the docs/nub --help for the precise bands.
• Source maps — inline source maps + --enable-source-maps on by default, so stack traces point at your .ts source. (--no-enable-source-maps to disable.)

So a project under nub typically doesn't need tsx, ts-node, dotenv, cross-env, tsconfig-paths, nodemon, or a standalone version manager. Surface redundant tooling to the user, but ask before removing dependencies or rewriting scripts.

Running scripts — nub run <script>

Drop-in for npm run / pnpm run, faster on the cold path. pre/post lifecycle hooks, the full npm_* environment, and node_modules/.bin on PATH all match npm run. Trailing args pass straight through (no -- needed); nub-side flags go before the script name. Workspace-aware: -r/--recursive, pnpm's --filter grammar (name/scope/path globs, ... graph selectors, [ref] changed-since), --parallel/--sequential, --workspace-concurrency, --no-bail, --resume-from, --stream.

Running CLIs — nubx <tool>

Drop-in for npx / pnpm exec (alias nub exec). Resolves from the node_modules/.bin walk-up chain and execs directly — much lighter than npx. Args pass through untouched. It runs already-installed bins only; if a bin is missing it prints (does not run) the right dlx command for the project's PM. (Yarn PnP needs nodeLinker: node-modules for .bin resolution.)

Watch mode — nub watch <file> (or nub --watch <file>)

Restart-on-change driven by the actual resolved dependency graph plus .env*, tsconfig.json, and package.json — no glob list. Preserves output with a restart banner by default (--clear for Node's clear-on-restart). A --watch placed after a script name is forwarded to the script, not nub.

Package manager — nub install / nub add

A full package manager, pnpm-shaped CLI regardless of the project's incumbent. It is lockfile-compatible with whatever the project already uses — it infers the incumbent PM (from packageManager/devEngines/lockfile) and reads+writes that PM's native lockfile, never imposing its own:

• pnpm / npm / Bun round-trip in place (pnpm-lock.yaml, package-lock.json v2/v3, bun.lock).
• Yarn is read-only — nub installs/runs a Yarn project but refuses any command that would rewrite yarn.lock (use yarn for those).

Flags follow pnpm: nub install --frozen-lockfile, -P/-D, nub ci, nub add -D/-E/-O/-g/-w <pkg>, nub remove, nub update -L, nub dedupe, nub import, plus why/outdated/list/patch/approve-builds/store/pkg/… .

Build-script trust is deny-by-default. A dependency's install/postinstall scripts run only if explicitly allowed (pnpm.onlyBuiltDependencies / Bun trustedDependencies / nub approve-builds) or vouched for by the gated default-trust floor (curated list + registry-resolved + advisory-checked + past a 24h cooling window). Otherwise the script is skipped with WARN_NUB_IGNORED_BUILD_SCRIPTS — run nub approve-builds to enable. Don't assume a dependency's build ran; check the install output.

Node version — auto-provisioned

nub runs your code on stock Node and provisions the right version automatically. Pin in .node-version / .nvmrc / engines.node; on the next nub <file> the matching build is fetched from nodejs.org (SHA-256 verified, cached under ~/.cache/nub/node) and run in the same breath — no nvm use. With no pin, nub adopts whatever node is on PATH. Augmented modes need Node 18.19+. Explicit cache control: nub node install / ls / uninstall / pin / which. (nub pm is the separate meta-manager that provisions the pinned pnpm/npm/yarn binary — corepack's job.)

--node escape hatch

When you need strict, unaugmented Node for one run — no transpile, no .env, no polyfills, no unflagging — add --node:

nub --node script.js     # top-level file run
nub run --node test      # nub's CLI orchestration, runtime augmentation off
nubx --node prisma generate

It still runs the project's pinned Node; it only turns augmentation off. Use it to confirm behavior against vanilla Node. A truthy NODE_COMPAT env var (1/true/yes) does the same thing for a whole process tree — the persistent form of --node, inherited by every descendant node/nub so you don't repeat the flag. It applies to every runtime entrypoint, nub watch included (which has no --node flag of its own). Your shell's bare node is always your real, unaugmented Node.

Type-checking the added surfaces

If you type-check code that uses the augmented surfaces (e.g. data-format imports, import.meta.hot), add @nubjs/types as a devDependency for the ambient declarations. Plain Node code needs nothing.

Getting the latest detail

This skill is a stable orientation layer; it omits exhaustive flag lists and the exact per-Node-version API bands (those move). For the current, complete reference of any command:

nub --help
nub <command> --help    # e.g. nub run --help, nub install --help

Or read https://nubjs.com/docs and the agent-readable index at https://nubjs.com/llms.txt.

Record the convention

So future sessions keep using nub, add a short note to the project's AGENTS.md (create it if absent): prefer nub over node/bun/the package manager — run files with nub <file>, scripts with nub run, local CLIs with nubx, installs with nub install / nub add; the existing lockfile is respected bidirectionally (Yarn read-only); use nub --node <file> for strict, unaugmented Node.

agent-browser

Fast browser automation CLI for AI agents. Chrome/Chromium via CDP with accessibility-tree snapshots and compact @eN element refs.

Install: npm i -g agent-browser && agent-browser install

Start here

This file is a discovery stub, not the usage guide. Before running any agent-browser command, load the actual workflow content from the CLI:

agent-browser skills get core             # start here — workflows, common patterns, troubleshooting
agent-browser skills get core --full      # include full command reference and templates

The CLI serves skill content that always matches the installed version, so instructions never go stale. The content in this stub cannot change between releases, which is why it just points at skills get core.

Specialized skills

Load a specialized skill when the task falls outside browser web pages:

agent-browser skills get electron          # Electron desktop apps (VS Code, Slack, Discord, Figma, ...)
agent-browser skills get slack             # Slack workspace automation
agent-browser skills get dogfood           # Exploratory testing / QA / bug hunts
agent-browser skills get vercel-sandbox    # agent-browser inside Vercel Sandbox microVMs
agent-browser skills get agentcore         # AWS Bedrock AgentCore cloud browsers

Run agent-browser skills list to see everything available on the installed version.

Why agent-browser

• Fast native Rust CLI, not a Node.js wrapper
• Works with any AI agent (Cursor, Claude Code, Codex, Continue, Windsurf, etc.)
• Chrome/Chromium via CDP with no Playwright or Puppeteer dependency
• Accessibility-tree snapshots with element refs for reliable interaction
• Sessions, authentication vault, state persistence, video recording
• Specialized skills for Electron apps, Slack, exploratory testing, cloud providers

Observability Dashboard

The dashboard runs independently of browser sessions on port 4848 and can also be opened through a proxied or forwarded URL such as https://dashboard.agent-browser.localhost. Agents should stay on the dashboard origin: session tabs, status, and stream traffic are proxied internally, so session ports do not need to be exposed.

Ad-hoc end-to-end testing of nub

A green cargo test is necessary but not sufficient — it does not prove the feature works when a user runs it. The highest-confidence cheap check is to build the dev nub and run the actual subcommand against a real fixture on disk. This is a valid, first-class way to verify new functionality (it is the implementer's half of the pre-push verification loop). It does not REPLACE the test suite — durable behaviors should also become committed tests — but it is how you confirm a change is real before you trust it.

This is also the highest-yield way to find correctness bugs: a differential fixture — one minimal fixture isolating ONE behavior, run against nub AND the reference tool it claims parity with (npm/pnpm/yarn/bun/node) on identical input — turns "nub does X" into a verified divergence or match. Always compare against the thing you assert parity with.

The loop

1. Create a fixture in a tmp dir

A minimal directory isolating the ONE behavior you changed — not a whole app. Concretely:

FIX=$(mktemp -d /tmp/nub-fix.XXXX)
cd "$FIX"
# write only what the behavior needs, e.g.:
cat > package.json <<'EOF'
{ "name": "fix", "scripts": { "build": "echo built" } }
EOF
# ...a lockfile, a workspace, a .npmrc, a tsconfig, an index.ts — whatever this behavior reads.

Keep it minimal: the smaller the fixture, the clearer the signal.

2. Build the dev nub

Use the fast profile from a worktree with a stable target dir (see the dev-loop skill). Either invoke the binary by path or via the nub-dev symlink:

# from your worktree:
cargo build -p nub-cli --profile fast        # -> <worktree>/target/fast/nub
NUB=<worktree>/target/fast/nub
# or, if you ran `make install-dev`:  NUB=nub-dev

If the change touches the runtime/transpiler (the N-API addon), build the addon too so the binary loads the new one: make addon-fast (or make install-dev, which does both).

3. Run the subcommand you implemented, against the fixture

cd "$FIX"
"$NUB" <the-subcommand-and-flags-you-changed>
echo "exit: $?"

4. Verify it had the INTENDED effect

Don't just eyeball stdout — assert the concrete effect. Depending on the feature:

# filesystem effect:
ls -la node_modules/.bin/ ; cat the-file-it-should-have-written
# lockfile/config it should have produced or respected:
cat nub-lock.yaml 2>/dev/null; cat package.json
# exit code on a refusal path:
"$NUB" <unsound-invocation>; echo "exit: $?"   # expect a non-zero + a clear error
# DIFFERENTIAL: run the reference tool on the SAME fixture and diff:
pnpm <equivalent> ; # compare output / node_modules / lockfile to nub's

State explicitly what "worked" means before you run it, then check that exact thing. "Tests pass" is not "the feature works"; the effect on disk / the exit code / the diff-vs-reference is.

5. Probe variants and edge cases

Run the neighbours of the happy path — the cases that are easy to get wrong:

"$NUB" <cmd> --flag-variant        # each flag/alias you touched
"$NUB" <cmd>                        # the no-arg / default case
(cd empty-dir && "$NUB" <cmd>)      # missing input / empty project
"$NUB" <cmd> <malformed-input>      # the failure mode — should error clearly, not panic

For version-banded runtime behavior, drive nub onto a specific Node: PATH="$HOME/.nvm/versions/node/v20.19.0/bin:$PATH" "$NUB" … — a green run on one modern Node masks compat-tier and floor-only defects (see AGENTS.md "Iterating across Node versions and tiers"). Use Docker for clean-machine / global-cache / Node-floor behavior.

6. Clean up

rm -rf "$FIX"

Then: promote durable checks into the suite

Ad-hoc verification proves this change; a committed test prevents the next regression. When the behavior is stable and the fixture is reusable, turn the probe into a real test rather than discarding it:

• A behavior covered by a tmp-fixture e2e check should become a committed integration test under crates/nub-cli/tests/*.rs (or a documented harness under tests/<feature>/ for multi-version/Docker loops).
• Keep it a throwaway only for genuinely one-shot / environment-bound checks.
• Follow the testing philosophy in AGENTS.md: minimum number of tests, comprehensive (not exhaustive) coverage, contract-describing names, self-debugging failure messages.

This is the final step of the pre-push local verification loop in AGENTS.md — incorporate the verification into the suite where reasonable, so the reviewer's pass is cheap and the CI run is a formality.

Local host won't show the behavior? If the thing you need to probe is OS/platform-gated — macOS Seatbelt / sandbox-exec / codesigning, Windows cmd.exe / --script-shell shell selection / .cmd resolution / Authenticode, musl/glibc, a Node floor — this local loop can't reach it. Linux corners go to Docker (AGENTS.md's Docker section); a real macOS or Windows behavior goes to the ci-adhoc-test skill — a self-contained probe under tests/<probe>/ run by a branch-scoped workflow with no PR required.

Quick reference

FIX=$(mktemp -d /tmp/nub-fix.XXXX); cd "$FIX"        # 1. fixture
# ...write minimal package.json / lockfile / tsconfig / source...
cargo build -p nub-cli --profile fast                # 2. build dev nub
NUB=<worktree>/target/fast/nub
"$NUB" <subcommand>; echo "exit: $?"                 # 3. run it
cat the-effect; pnpm <equiv>                         # 4. verify effect (differential)
"$NUB" <variant>; "$NUB" <bad-input>                # 5. probe edges
rm -rf "$FIX"                                         # 6. clean up
# 7. promote a durable check into crates/nub-cli/tests/*.rs

Addressing a nub issue end-to-end

This is the playbook for taking a GitHub issue from "reported" to "shipped and the reporter told." It exists because maintainer responsiveness on a PUBLIC repo is a visible health signal: a reporter who gets an acknowledgement, sees their issue auto-close on merge, and gets a link to the release it shipped in has a completely different experience from one whose issue goes silent. The hygiene rules here are mandatory, not courtesies (AGENTS.md "Git & GitHub maintainer hygiene").

Guardrails (read first):

• Tone is always factual, neutral, professional — never braggy, competitive, or over-promising. Every comment follows the project's tone bar (AGENTS.md "The repo is PUBLIC" + the commit-message tone rule; the cross-project GitHub-comment + prose guide is PROSE.md). Acknowledge sincerely; state what you found and what you did; don't promise a timeline you can't keep.
• A fix lands via the PR-from-a-worktree flow, not directly on the shared main tree. Substantive fixes are reviewable PRs opened from an isolated worktree (AGENTS.md "Default to a PR flow"). Trivial doc/typo fixes are the documented exception.
• Verify the fix end-to-end before pushing — don't outsource verification to CI. Run the pre-push local-verification loop (AGENTS.md "VERIFY LOCALLY BEFORE PUSHING"). A green test suite with a stubbed fix is worse than an unchecked one.
• Don't autonomously land a change to a default / security posture / product behavior / API-config-env surface. Those are recommend-only until the maintainer signs off (AGENTS.md). A mechanical, clearly-a-bug fix may land; a behavior decision routes back as a question.

Step 1 — Triage: read the issue, the comments, and reproduce

gh issue view <n> --repo nubjs/nub --comments

• Read the COMMENTS and the resolution history, not just the body. The body says what someone wanted; the thread says what's true. A "feature request" can be a deliberate prior rejection; a "bug" can already be fixed on main. (AGENTS.md "Probing methodology" — read the comments.)
• Classify it. Is it a genuine bug, a usage question, a feature request, a duplicate, or already-fixed? Is the fix mechanical (clearly-a-bug, land it) or does it touch a default / behavior / API-config-env surface the maintainer owns (propose, get sign-off)?
• Reproduce empirically before reading source or deciding. Build a minimal differential fixture — the behavior under nub vs. the reference tool it claims parity with (npm/pnpm/yarn/bun/node) on identical input — in a throwaway /tmp dir. A divergence IS the finding. Test what it actually does; don't infer from code (AGENTS.md "Probing methodology — differential fixtures").

Step 2 — Acknowledge an external report immediately

If the issue is from an EXTERNAL reporter (not a maintainer / not self-filed), post the acknowledgement the moment you start work, so they know it's seen. The ack is EXACTLY one word — nothing else:

gh issue comment <n> --repo nubjs/nub --body "Investigating."

Just "Investigating." — full stop. No "thanks for the report," no "will follow up," no preview of your hypothesis, no diagnosis, no timeline. A longer ack leaks half-formed theories (which are often wrong) and reads as noise. Say nothing but that it's being looked at. (Internal / self-filed issues don't need this.)

Every SUBSTANTIVE comment (Steps 5–6, or any reply) is terse + factual per PROSE.md — never a verbose essay. State what you found and what you did, in the fewest words that carry the facts. No preamble, no editorializing, no walls of text. NEVER write "previous comments were wrong" or similar meta-commentary — prior comments are often an automated bot's, not a human's. The gh-comment-guard PreToolUse hook BLOCKS an over-long gh issue/pr comment / gh pr create body; trim it, or set NUB_ALLOW_LONG_COMMENT=1 only for a genuinely-needed longer body (e.g. a detailed release note).

If triage shows it's NOT a bug (working as intended, a usage question, a duplicate, won't-fix), say so factually with the reason and close it per Step 6 — don't leave it hanging or sink time into a non-fix.

Step 3 — Fix it (fray + the pre-push loop)

For anything beyond a one-line fix, drive the work with the fray methodology (the globally-installed fray plugin skill — load it by name): you orchestrate, dispatch model-tiered sub-agents as instruments (Opus for the fix that lands, Sonnet for supporting work, Haiku for scripted harvest), and a substantive fix gets a SEPARATE self-review pass before it's marked done. Scale the review to the blast radius — a far-reaching change (registry/lockfile/config/security/default) gets a multi-lens reviewer fleet.

Work in an isolated worktree off origin/main (AGENTS.md "Default to a PR flow"):

git worktree add /tmp/nub-fix-<n> -b fix-issue-<n> origin/main   # vendor/aube comes along (plain in-tree files)
cd /tmp/nub-fix-<n> && export CARGO_TARGET_DIR=/tmp/nub-fix-<n>-target

Before pushing, run the pre-push local-verification loop (AGENTS.md "VERIFY LOCALLY BEFORE PUSHING"): incremental build → the exact CI gates (cargo clippy --all-targets --all-features -- -D warnings, cargo fmt --check, scoped cargo test) → an e2e tmp-fixture run of the specific behavior the issue is about → Docker for anything touching the global cache/config → and promote a durable check into the test suite where reasonable (a regression test for this bug). Get it green locally and push ONCE.

Step 3b — Update docs if the fix changes user-facing behavior

If the fix changes something a user observes — a flag's effect, a default, an error message, a formerly-broken feature that now works, a new workaround that's now unnecessary — update the relevant page in site/content/docs/ as part of the same effort. The fix is not done until the docs reflect it. Land the doc update in the same PR as the code fix.

Step 4 — Open the PR, referencing the issue

The PR body MUST reference the issue. Use a closing keyword for a bug the PR resolves so the merge auto-closes it; use Refs #N for a related-but-not-resolving PR.

git push -u origin fix-issue-<n>
gh pr create --repo nubjs/nub \
  --title "<concise factual title>" \
  --body "$(cat <<'EOF'
<What the bug was and what the fix does, factually.>

Closes #<n>

<Verification: the fixture/command you ran and its result.>

https://claude.ai/code/session_<id>
EOF
)"

Report the PR URL. Do NOT merge your own PR — the maintainer reviews and merges (AGENTS.md).

Step 5 — On merge, comment the resolution

When the PR merges, the Closes #N auto-closes the issue. Add a brief factual comment stating what fixed it (the auto-close is silent otherwise):

gh issue comment <n> --repo nubjs/nub --body "Fixed in #<pr> (merged to main). Will ship in the next release."

If for some reason the issue did NOT auto-close (no closing keyword, or it was a non-fix resolution), close it explicitly with a comment — never silently:

gh issue close <n> --repo nubjs/nub --comment "<what fixed it, or why no code fix is needed>"

Step 6 — On release, comment the version + release link (mandatory)

A fix merged is not a fix shipped. When the release that carries this fix goes out, comment the version and a link to the release on the issue AND on the merged PR. This is mandatory maintainer hygiene done on every release (AGENTS.md "Git & GitHub maintainer hygiene"; the release skill's Step 5 does this in bulk across the whole changeset):

REL="https://github.com/nubjs/nub/releases/tag/v<ver>"
gh issue comment <n> --repo nubjs/nub --body "Shipped in v<ver>: $REL"
gh pr comment   <pr> --repo nubjs/nub --body "Shipped in v<ver>: $REL"

In practice you don't run this per-issue at release time — the release skill enumerates every closed issue + merged PR in the changeset and comments them all. This step documents the contract for a single issue; the release skill is where it's executed across the release.

Quick reference

Invoke via the Skill tool whenever you pick up a GitHub issue to work or are asked to fix a reported bug.

Syncing jdx/aube upstream into nub's vendored aube

Mental model (read first)

After Pattern B (#81), vendor/aube/** is plain tracked files in nub's history — there is NO git submodule and NO pin. An aube change is an ordinary nub PR touching vendor/aube/**. nub main is the source of truth for the vendored aube.

Three git objects matter, in two separate repos:

WHY a naive overwrite is bad: vendor/aube is plain files with NO git ancestry relationship to jdx/aube. Copying jdx's tree over vendor/aube gives git no common base, so every one of our nub-delta files (embedder profile, brand helpers, config-scope gating, pnpm fixes) collides → a giant manual conflict resolution, every sync.

WHY nub-fork is the venue: nub-fork was branched from jdx/aube and merge-synced ever since, so git merge-base nub-fork jdx/aube/main returns a real commit. git can do a true 3-way merge there — it only surfaces conflicts where our delta and upstream genuinely touch the same lines. Everything else auto-merges. We do the merge on nub-fork, then bring the result into vendor/aube.

The invariant that keeps this cheap

After every sync, nub-fork's tip tree MUST equal the newly-vendored vendor/aube tree. When this holds, the next sync's bring-in is a clean delta-apply (the vendored tree == the merge's first parent, so parent..merge applies with zero conflicts). The recipe ends by restoring this invariant (FF or tree-snapshot, step 6).

The drift risk: post-Pattern-B, ordinary in-tree fixes land in vendor/aube on nub main but NOT on nub-fork. If that happens between syncs, nub-fork's tree falls behind the source of truth. Reconcile before merging (step 2b) so the merge venue starts from the truth.

Recipe

Work in a nub worktree off latest origin/main (see the worktree skill). All aube-* remotes below are the aube repos, added to the worktree.

1. Set up remotes + fetch all three objects

cd <nub-worktree>
git remote add aube-fork https://github.com/nubjs/aube 2>/dev/null
git remote add aube-upstream https://github.com/jdx/aube 2>/dev/null
git fetch aube-fork nub-fork
git fetch aube-upstream main

2a. Confirm the relationships

git merge-base aube-fork/nub-fork aube-upstream/main   # the real common ancestor — proves the venue works
git log aube-upstream/main --oneline -5                # what's new upstream
# Is upstream already merged into nub-fork? (idempotency check)
git merge-base --is-ancestor aube-upstream/main aube-fork/nub-fork \
  && echo "already synced" || echo "upstream moved; merge needed"

2b. Reconcile drift — make nub-fork's tree match the SOURCE OF TRUTH first

Compare nub-fork's tip tree against the vendored tree. If they differ, in-tree fixes landed on main that nub-fork is missing — snapshot them onto nub-fork (ancestry-preserving) BEFORE merging upstream:

rm -rf /tmp/forktip /tmp/vendored && mkdir -p /tmp/forktip /tmp/vendored
git archive aube-fork/nub-fork | tar -x -C /tmp/forktip
git archive origin/main:vendor/aube | tar -x -C /tmp/vendored
diff -rq /tmp/forktip /tmp/vendored      # empty == in sync, skip the snapshot

If they differ, create a tree-snapshot commit on nub-fork whose tree == current vendor/aube, parented on nub-fork tip (this keeps nub-fork's real jdx ancestry — do NOT subtree split, which fabricates synthetic commits and breaks the merge-base):

# In a clone of nubjs/aube on nub-fork, mirror the vendored tree in, commit, push.
rsync -a --delete /tmp/vendored/ <aube-clone>/    # excluding .git
git -C <aube-clone> add -A
git -C <aube-clone> commit -m "chore: sync nub-fork tree to vendored in-tree state"
git -C <aube-clone> push origin nub-fork
git fetch aube-fork nub-fork

Why a tree-snapshot, not git subtree split: subtree split rewrites vendor/aube/**'s nub-side history into synthetic commits with no relation to jdx/aube — that destroys the merge-base that makes nub-fork a valid 3-way venue. A single snapshot commit parented on the real nub-fork tip keeps the ancestry and is the lowest-overhead correct answer.

3. Merge upstream into nub-fork — MERGE, never rebase; OURS-WINS

Do this in a clone of nubjs/aube on nub-fork (so the merge has the real ancestry). Merge-commit, never rebase — rebasing rewrites SHAs, multiplies conflict reps, and forces a force-push. Colin's explicit preference is merge.

git -C <aube-clone> checkout nub-fork
git -C <aube-clone> merge aube-upstream/main --no-ff

Conflict resolution = OURS WINS (Colin's explicit rule). Our nub delta always survives:

• A file we own / modified (embedder profile, workspace_markers()/lockfile_basename() brand helpers, config-scope gating, identity, our PM fixes) → take ours.
• A file we don't own that upstream changed → take upstream.
• Convergence case (both sides independently did the same work — e.g. the v1.23 sync's audit.rs tests, where production code auto-merged and only upstream's new tests conflicted): accept upstream's additive piece; we don't own that test logic. This is convergence, not a loss of our delta.

To bias auto-resolution toward ours while still taking upstream where we have no competing change, -X ours on the merge is acceptable for noisy files — but prefer manual review of each conflict so a real upstream behavior change isn't silently dropped. Flag any OURS-vs-THEIRS call that touches a default / security posture / product behavior for maintainer sign-off — resolve ours-wins but surface it.

Verify the merge in the aube clone, then push the staging branch:

cd <aube-clone>
cargo test -p aube --lib && cargo test -p aube-lockfile --lib && cargo test -p aube-resolver --lib
# registry/config tests read ~/.npmrc — run with an isolated HOME (keep RUSTUP_HOME/CARGO_HOME real):
HOME=/tmp/clean RUSTUP_HOME=$HOME/.rustup CARGO_HOME=$HOME/.cargo cargo test -p aube-registry --lib
git push origin nub-fork           # FF nub-fork to the merge (this is also step 6's invariant restore)

4. Bring the merged tree into vendor/aube — delta-apply, NOT blind overwrite

Because the invariant held (nub-fork tip tree == vendor/aube before the merge), the merge result's tree is exactly vendor/aube + the upstream delta. Mirror it in:

rm -rf /tmp/merged && mkdir -p /tmp/merged
git archive <merge-commit-sha> | tar -x -C /tmp/merged
rsync -a --delete /tmp/merged/ <nub-worktree>/vendor/aube/
git -C <nub-worktree> add vendor/aube
git -C <nub-worktree> status --short vendor/aube   # == the upstream delta filelist, nothing else

Preserve in-tree fixes: if a file you bring from upstream overlaps a concurrently-landing nub PR (check open PRs touching vendor/aube/**), ours (the in-tree version) wins — keep nub's. In the v1.23 sync the upstream delta was fully disjoint from the parallel PRs, so this never bit, but always check overlap before the rsync.

5. Build + test gates (the exact CI gates)

From the nub worktree root (vendor/aube is a path dep, compiled as a dependency):

export CARGO_TARGET_DIR=/tmp/<slug>-target
cargo check -p nub-cli                              # the integration gate — aube must build AS nub's dep
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --check                                  # excludes vendor/aube (its own workspace), but run it

And from vendor/aube/ (its own workspace, own target dir) for the engine tests:

cd vendor/aube && export CARGO_TARGET_DIR=/tmp/<slug>-vendor-target
HOME=/tmp/clean RUSTUP_HOME=~/.rustup CARGO_HOME=~/.cargo \
  cargo test -p aube --lib -p aube-lockfile --lib -p aube-registry --lib -p aube-resolver --lib

Verify our delta survived: confirm the nub-specific symbols are still present after the bring-in:

grep -rn "workspace_markers\|lockfile_basename\|EmbedderProfile\|read_branded_pnpm_config" vendor/aube/crates

6. Restore the invariant + open the nub PR

• Restore the invariant: nub-fork's tip must now equal what you vendored — FF nub-fork to the merge commit (step 3's push already does this if you merged ON nub-fork). Confirm git archive aube-fork/nub-fork == vendor/aube.
• Open an ordinary nub PR with the vendor/aube/** diff. In the body, summarize the behavior-affecting upstream changes (so the reviewer sees what upstream behavior shifted) and flag anything touching a default / security posture for maintainer sign-off (recommend-only — never silently flip a default).
• Push-then-exit if dispatched: push the branch the instant a commit exists, report pushed <sha>, awaiting CI, do NOT arm a CI watcher.

Conflict-minimization tactics

• Sync frequently. Smaller upstream deltas = fewer conflict reps. A 12-commit delta (v1.23) had exactly ONE conflict; a year's delta would be brutal.
• Keep our delta THIN by upstreaming aggressively. Pluggable/additive changes that are no-op for standalone aube (embedder profile, env-resolution hooks, source-branding helpers, exit-code sweeps) → PR them to jdx/aube. Once jdx merges, the next merge upstream/main CONVERGES them (git dedups identical content) and they graduate OUT of our fork-only delta — fewer files to conflict next time.
• Merge, never rebase (restated — it's the single biggest lever): rebase replays each of our delta commits onto the new upstream tip, re-surfacing the same conflict once per commit. A merge resolves each conflict ONCE.
• The convergence-dedup case is a feature, not a problem: when both sides did the same work, accept upstream's version of the not-ours-to-own piece; the production code usually auto-merges to the converged impl.

Idempotency / "is it already synced?"

If git merge-base --is-ancestor aube-upstream/main aube-fork/nub-fork returns true, jdx HEAD is already merged into nub-fork — no merge needed; just verify vendor/aube == nub-fork tip (the invariant) and you're done.

Ad-hoc testing on a real OS/platform via CI

Some behavior can only be observed on a real target platform: macOS Seatbelt / sandbox-exec / Gatekeeper / codesigning, Windows cmd.exe / --script-shell shell selection / .cmd/.bat resolution / Authenticode / SmartScreen, musl-vs-glibc detection, Linux-arm64, a pinned Node floor. Docker closes the Linux corners cheaply (see AGENTS.md's Docker section) but runs Linux containers only — it is not a substitute for macOS or Windows. CI runners (macos-latest, windows-latest) are the only way to exercise those, and this skill is how you do it as a throwaway probe.

The key fact: no PR is required

A GitHub Actions workflow does not need an open pull request to run. Trigger it on the branch instead:

on:
  push:
    branches: [<your-probe-branch>]  # THE trigger: runs on every push to THIS branch
    paths:                           # only when the harness itself changes
      - 'tests/<probe-name>/**'
      - '.github/workflows/<wf>.yml'
  workflow_dispatch:                 # INERT until the file lands on the default branch — see below

With this trigger the CI capability is keyed to the branch + workflow file, not to a PR. Consequences:

• Push to the branch → the probe runs. Open no PR, or close one you opened — the runs keep working.
• Re-run with another push — an empty commit is the simplest: git commit --allow-empty -m rerun && git push. Or re-run a finished run as-is with gh run rerun <run-id> (gh run list --branch <branch> to get the id).
• push is load-bearing; workflow_dispatch alone will NOT work for a branch-only probe. GitHub only registers a workflow_dispatch workflow if the file is on the default branch — so for a workflow that lives only on the feature branch, gh workflow run <wf>.yml --ref <branch> errors ("no workflows found") and it never appears in the Actions UI. Keep the workflow_dispatch entry for the day the probe graduates to main, but do not rely on it before then; the push trigger is the only thing that fires a not-on-main workflow.
• Do NOT open a PR just to get CI. A PR signals "ready to land / please review," which a prototype is not. Opening one to trigger CI is the wrong tool and reads as premature-ship. (Worked example: PR #205 added a macos-latest Seatbelt probe; it was closed as premature, and the branch push trigger meant the macOS validation kept working off the fs-write-confine branch with the PR closed.)
• Omit any pull_request: trigger — it ties runs to PR state, which is exactly what you're avoiding.

The harness shape

Keep the probe self-contained under tests/<probe-name>/, mirroring the existing ones, so the whole thing is one reviewable, reproducible unit:

• A generator / runner (e.g. an SBPL profile generator + a sandbox-exec runner; a .cmd resolver harness).
• Fast unit + smoke tests that assert the enforcement and the bypass/fail-closed cases.
• A README.md (what it validates, how to reproduce locally) and a results.md (the findings, plus any heavy runs reproduced on demand).
• The branch-scoped workflow .github/workflows/<wf>.yml.

Examples to mirror: tests/sandbox-macos-writeconfine/ + .github/workflows/sandbox-macos-writeconfine.yml (macOS Seatbelt write-confine), and its Windows counterpart tests/sandbox-win-probes/ (each lives on its own probe branch, not main).

Keep CI lean — fast core only

The CI job runs the fast, deterministic core: unit tests + the enforcement/bypass smoke matrix, no network, no mega-fixture. Heavy or combinatorial runs (a frameworks mega-fixture, per-cache-family sweeps) are documented in results.md and reproduced on demand, not baked into every CI run. CI capacity is shared (AGENTS.md) — a probe job that takes 22 minutes per push is already a lot; don't make it a per-commit tax.

Run and watch

• Kick a run by pushing to the branch (an empty commit if the harness is unchanged: git commit --allow-empty -m rerun && git push); list with gh run list --workflow <wf>.yml --branch <branch>. (gh workflow run only works once the file is on the default branch — see the trigger note above.)
• Await a specific run with the ci-watch skill (scripts/ci-watch.ts) rather than raw gh run watch — it waits for the run to exist, polls authoritative terminal status, fails fast, and exits 0 only on confirmed success.
• A failure is immediately actionable — read the job log, fix the harness, push again (the push trigger re-runs it).

Lifecycle

• The branch is the durable home of the probe while it's exploratory — it persists with no PR ceremony. Push, run, iterate.
• When the harness graduates into a permanent regression check, fold it into main through the normal flow (it's tests/** + a workflow file — a content/CI change, which AGENTS.md routes straight to main, no review-gate PR). Decide its steady-state trigger then (e.g. path-filtered on main, or workflow_dispatch-only).
• If you only needed the one-time answer, leave the branch as the record (or delete it once results.md captures the findings) — never open a PR to "preserve" a throwaway probe.

When to reach for this vs the alternatives

• Local host probe (ad-hoc-test skill) — the behavior reproduces on your dev machine. Cheapest; default for anything not platform-gated.
• Docker (AGENTS.md) — a Linux corner: musl/glibc, a Node floor, a clean dependency-free environment, first-run install. Linux containers only.
• This skill (CI branch probe) — a macOS or Windows behavior, or a real multi-runner matrix, that neither the host nor Docker can show. The PR-free, branch-scoped path.

Watching CI with the GitHub CLI

The pitfall: raw watchers exit early

gh run watch <id> --exit-status and gh pr checks <pr> --watch are NOT safe to arm right after a git push / tag / PR-open:

• Premature exit while QUEUED. Armed immediately after a push, the run has no jobs registered yet. gh sees "nothing in progress" and returns exit 0 — even though the run is still queued/in_progress. (Observed on the v0.1.11 release: the watcher exited 0 while the Test gate job was still running.)
• Transient errors read as failure. A mid-watch HTTP 401: Bad credentials (token refresh) or a 5xx makes the watcher exit non-zero, indistinguishable from a real CI failure. (Also observed on v0.1.11.)
• No native fix. There is no gh run watch flag that waits-for-existence or tolerates transient errors (--interval only tunes the poll cadence). The script below is the fix.

The rule

Never trust a raw watcher's exit code alone. Always re-verify terminal status with gh run view <id> --json status,conclusion (a run is done only when status == "completed") or gh pr view <pr> --json statusCheckRollup (done only when every item is terminal). And always fail-fast — act on the first failing check, never wait for all checks to finish (AGENTS.md fail-fast discipline).

The blessed tool bakes all of this in — prefer it over a hand-rolled watcher.

The blessed tool: scripts/ci-watch.ts

Blocks until the target is truly terminal, then exits with a trustworthy status. Dogfoods nub; runs under plain Node too.

nub  scripts/ci-watch.ts --run <run-id> [--repo o/r] [--timeout <min>]
node scripts/ci-watch.ts --pr  <number> [--repo o/r] [--timeout <min>]

• --run <run-id> — watch a workflow run (polls gh run view --json status,conclusion,jobs).
• --pr <number> — watch a PR's check rollup (polls gh pr view --json statusCheckRollup,…).
• --repo <owner/repo> — defaults to the current repo.
• --timeout <minutes> — wall-clock cap before giving up as pending (default 45).
• --required <names> — comma-separated branch-protection check names to gate on (e.g. --required "CI gate"). Success fires the instant every required check is green; a ghost or a non-required check — pending or failed — never blocks, matching branch-protection semantics. The precise, hang-proof gate for a merge watcher — prefer it when you know the required check name.
• --no-progress <minutes> — how long an unchanged incomplete set (all required/named checks already green, only a ghost left) may sit before exiting 4 STUCK-but-safe (default 8).

What it fixes: waits for the target to EXIST (a not-found / no-jobs-yet target is "keep polling," never "done"); polls authoritative terminal state (status == "completed" / every required/named rollup item terminal+green); fails fast on the first FAILURE/CANCELLED/TIMED_OUT/STARTUP_FAILURE; never hangs on a ghost (see below); tolerates transient gh/API errors (retried with backoff, not treated as a run failure); uses gh's stored token implicitly (high rate limit) with exponential jittered backoff (10s → cap 60s, 90s if unauthenticated).

The #327 ghost — why a strict "all checks terminal" gate hangs

GitHub occasionally registers a check-run that never reports a status: it stays PENDING, nameless, forever. A watcher that waits for every rollup item to be terminal then blocks indefinitely even though every real check is green — PR #327 sat reviewed-and-green for hours this way, its merge watcher parked on one nameless ghost. The fix: a nameless / never-terminating non-required check does not block a green verdict. Once every named check is green and the incomplete set has been unchanged for --no-progress minutes, the watcher exits 4 (STUCK-but-safe) with an actionable summary — the caller --admin merges instead of hanging. A named pending check is never treated as a ghost, so a real in-flight check is never green-lit early.

Exit-code contract

The final stdout line is a single self-describing summary, e.g. CI-WATCH run 27972328590: SUCCESS (25 job(s) green), CI-WATCH pr 73: FAILURE — check "Test (ubuntu-latest, node 22.13)" → FAILURE (https://…), or CI-WATCH pr 327: STUCK — required/named checks GREEN (51), 1 non-terminal ghost/non-required check(s): (unnamed); safe to --admin merge.

Run it detached (CAVEAT: a long wait STRANDS — see the cron-heartbeat section below; this is for SHORT, synchronously-observed gates only)

It's designed to run as a detached run_in_background Bash task that re-invokes the orchestrator on exit — read the outcome from the tail (the CI-WATCH … line) and gate on the exit code:

nub scripts/ci-watch.ts --run "$RUN_ID" --repo nubjs/nub   # run_in_background: true

For a merge-queue drain, prefer scripts/merge-cascade.ts (it gates positively and merges on green); reach for ci-watch.ts when you just need to block on one run/PR and branch on the result.

Merge-on-green — the ORCHESTRATOR runs the watcher as a background shell; NEVER a watcher sub-agent (learned 2026-06-25)

What stranded EVERY merge in the v0.2.2 floor-fix batch (#163/#164) was NOT background shells and NOT the script — it was dispatching a ci-watch sub-agent. A sub-agent that backgrounds a watch and then rests ORPHANS the command: the sub-agent isn't the orchestrator, so when its background process exits there's nothing wired to re-invoke the orchestrator and merge. Never dispatch a sub-agent to watch CI.

The proven pattern: the ORCHESTRATOR runs the blocking watcher as its OWN run_in_background Bash task. A background Bash command persists ACROSS TURNS and re-invokes the orchestrator when it exits (the Bash tool contract). So node scripts/merge-cascade.ts --max-minutes <n> (drains .fray/merge-queue.jsonl: watch → gate → merge → ff-pull → exit), launched by the orchestrator with run_in_background: true, IS the durable merge mechanism — on exit the orchestrator is re-invoked and reconciles.

Recipe:

1. Enqueue: append {"pr":N,"branch":"…","thread":"…","note":"…"} (optional "hold":true) to .fray/merge-queue.jsonl. Enqueue UNHELD only once the PR's FINAL head is pushed — a stale head can be green-but-wrong, so verify the head/rebase before it's mergeable.
2. Watch: the ORCHESTRATOR runs node scripts/merge-cascade.ts --max-minutes 40 with run_in_background: true. It gates positively on the required CI gate (present + SUCCESS) + mergeable, merges --squash --admin, ff-pulls, dequeues, exits → re-invokes the orchestrator. It shares ci-watch's #327 ghost carve-out (scripts/lib/ci-rollup.ts): a nameless/never-terminating ghost — or any non-required check, pending OR failed — is non-blocking, so the drain can't hang the way #327 stranded a merge; a still-running or failed REQUIRED gate always holds/blocks, so a red PR is never mis-merged.
3. Landing agents PUSH-THEN-EXIT — they never watch; they report pushed <sha>, queued. The orchestrator's background watcher owns merge-on-green.

A CronCreate heartbeat (every ~4 min, one non-blocking gh pr view poll per queued PR, merge-on-green) is a FALLBACK only if a background shell ever proves unreliable — the orchestrator background shell above is the default and what historically worked. Reach for the blocking ci-watch.ts directly only for a single-run gate you observe synchronously.

Self-contained sub-agents — run_in_background works for them TOO; the orchestrator must NOT preempt (corrected 2026-06-26)

There is NO fundamental orchestrator-vs-sub-agent difference for run_in_background: a backgrounded Bash command persists and re-invokes ITS LAUNCHER on exit — orchestrator or sub-agent alike. Proven: a ci-watch sub-agent backgrounded a watch, rested, was re-invoked when CI went terminal, and reported the result. The earlier "a sub-agent watch ORPHANS" claim was a MISDIAGNOSIS — the watchers were working; the orchestrator PREEMPTED them by impatiently checking CI itself and merging manually mid-trace.

The self-contained landing-agent pattern (the goal — one agent traces push→merge):

1. push the branch;
2. launch node scripts/merge-cascade.ts --max-minutes 40 for its OWN PR (or ci-watch.ts) via run_in_background: true;
3. END its turn (rest);
4. it is RE-INVOKED when the command exits → reports merged / red, and iterates (fix-if-red → re-push → re-watch).

DO NOT preempt a landing agent's background watch — let it trace to merge and report. That impatience, not any orphaning, is what broke the flow.

The FOREGROUND ci-watch.ts --chunk loop below is a FALLBACK only — for an agent that must actively iterate in the foreground and can't rest. Run ci-watch.ts in the FOREGROUND in chunks under the Bash cap, looping on pending:

# Bash tool: foreground (NOT run_in_background), timeout: 570000  (9.5 min, under the 600000 cap)
nub scripts/ci-watch.ts --pr <N> --chunk          # --chunk caps the watch ~9 min and exits 2 with "RERUN to continue" if still pending
#   exit 0 = green → act    exit 1 = red → fix + re-push    exit 2 = pending → RE-RUN the SAME command    exit 3 = error

Loop: while it exits 2, call it again — each chunk completes within the cap (no kill, no orphan). The sub-agent blocks in the foreground the whole time, which is FINE: it's backgrounded relative to the ORCHESTRATOR, so the main loop stays responsive.

Dispatch prompts for a self-gating landing agent MUST spell this out — a sub-agent won't infer the foreground-chunk loop. This is ONLY for when the sub-agent needs to SEE its own result to iterate. For the common "push and let it merge" case, the agent push-then-exits and the ORCHESTRATOR's background shell / merge-queue owns merge-on-green (above).

Building & testing nub

nub is a Rust workspace — three crates (nub-cli, nub-core, nub-native) plus the vendored aube PM engine (vendor/aube, plain in-tree files since Pattern B, its own Cargo workspace, linked in-process as a library). This skill is the fast, measured way to build and test it in a worktree, plus a crate map so you know where things live.

The one rule that makes iteration fast: build with the --profile fast profile (NEVER release), through scripts/rust-build.sh (scripts/rust-build.sh build -p nub-cli --profile fast). The wrapper points CARGO_TARGET_DIR at the ONE shared dir ~/.cache/nub/shared-target for the fast path — cold ≈ 3 min, every rebuild after ≈ 5s, because a second worktree reuses all the crates.io dependency artifacts (the bulk of a build) and recompiles only the ~10 workspace crates. Don't clean the shared dir between iterations — that throws away cargo's incremental cache. Why the wrapper and not a raw export CARGO_TARGET_DIR: the shared dir is safe only while every worktree agrees on the depended-on crates; two worktrees that diverge the same one (classically vendor/aube) clobber each other's rlib and fail with a phantom E0063-class error on correct source. rust-build.sh shares by default and auto-isolates to a private target dir exactly when this worktree diverges such a crate — you get the fast path in the common case and correctness in the rare one, with no manual decision. See the rust-build skill. (Tradeoff of sharing: cargo build-locks the target dir, so concurrent builds in two sharing worktrees serialize — a latency cost, never a correctness one.)

Step 1 — Set up a worktree to iterate in

Substantive work lands via a PR from an isolated worktree. Create one with the worktree skill (nub scripts/new-worktree.ts <slug> — it bakes in the proven git worktree add … origin/main recipe). Then build through the wrapper, from the worktree root:

cd ~/.cache/nub/worktrees/<slug>
scripts/rust-build.sh build -p nub-cli --profile fast          # shared cache; auto-isolates on divergence

The wrapper shares ~/.cache/nub/shared-target so a fresh worktree reuses the crates.io dependency artifacts another worktree already compiled — it recompiles only the ~10 workspace crates instead of all ~400, and one shared dir replaces ~30 multi-GB private ones. It flips to a private target dir automatically when this worktree diverges a depended-on crate (see the rust-build skill for why). Two sharing worktrees serialize on cargo's build lock; if you need them to build at once, an isolated worktree (one that has diverged a lib crate) already runs in parallel, or set a private CARGO_TARGET_DIR by hand.

Step 2 — Build the dev binary (the fast profile)

# The dev CLI binary -> target/fast/nub. This is the iteration build.
cargo build -p nub-cli --profile fast

# Full dev binary + N-API addon, symlinked on PATH as nub-dev / nubx-dev:
make install-dev        # runs addon-fast, then `cargo build --profile fast`, then symlinks target/fast/nub

# Just the native addon (oxc transpiler), fast profile:
make addon-fast         # -> runtime/addons/nub-native.node
# Release-profile addon (only when you specifically need release behavior):
make addon

There is no nub build command — the dev build is cargo build -p nub-cli --profile fast (or make install-dev for the full binary+addon on PATH).

Build politeness on this shared dev host (HIGH PRIORITY — the maintainer works on this machine). A full cargo build can saturate all cores and make the maintainer's machine non-responsive. Two throttles keep it polite:

• Job cap (already set, machine-wide): ~/.cargo/config.toml pins [build] jobs = 6 (of 8 perf cores), so no build grabs every core. CI is unaffected (it runs on GitHub runners, not this config). Leave it in place.
• Background QoS / nice — wrap every agent build: launch builds as taskpolicy -b cargo build -p nub-cli --profile fast (macOS background QoS → schedules on E-cores + yields to interactive) or nice -n 10 cargo build …. This lets a build run without making the machine sluggish. If a build is already hammering the host, renice 20 -p <pid> + taskpolicy -b -p <pid> the running cargo/rustc tree for immediate relief.

Why fast, never release, for iteration (measured 2026-06-20, macOS arm64):

The fast profile (defined in Cargo.toml) inherits dev (debug-assertions + overflow checks stay on), drops LTO, uses codegen-units=256, line-tables-only debuginfo, and incremental=true. It is the iteration profile; release is a ship profile and must not be used to iterate.

A shared cargo target DIR (the default here) is NOT sccache — don't conflate them. sccache (a compiler-WRAPPER cache) was measured against this workspace and gives a 0% Rust cache-hit rate across separate target dirs (rustc embeds per-target-dir artifact paths in sccache's cache keys; --remap-path-prefix + CARGO_INCREMENTAL=0 does not fix it) — so sccache is NOT used. A shared cargo target dir sidesteps that entirely: with one target dir there's a single artifact path, so cargo's own incremental reuses the dependency rlibs directly across worktrees. That is why the shared dir — not a per-worktree one — is the fast path. (Seeding a private worktree target dir from a warm sibling via APFS clone is still useless — cargo invalidates the cloned fingerprints and rebuilds; the shared dir avoids the copy in the first place. There is no copy-on-write shortcut.) The catch is that a single artifact path is safe only while every sharing worktree agrees on the depended-on crates; scripts/rust-build.sh is what keeps that invariant (auto-isolating a diverged worktree) so the shared dir stays both fast and correct — see the rust-build skill.

Step 3 — Run tests

# A specific integration-test file (file stem under crates/nub-cli/tests/):
cargo test -p nub-cli --test pm_verbs
cargo test -p nub-cli --test install_engine

# A single test by name substring (across the crate):
cargo test -p nub-cli <substring>
# Pin exactly one test:
cargo test -p nub-cli -- --exact <full::module::path::to::test>

# A core/native crate's tests:
cargo test -p nub-core
# nub-native is its OWN workspace (excluded from the root one), so `-p nub-native`
# from the repo root fails — run it from inside the crate. (The cdylib sets
# `test = false`, so this just compiles the addon; its unit-testable logic lives
# in the napi-free nub-cache-key crate, covered by `cargo test -p nub-cache-key`.)
(cd crates/nub-native && cargo test)

# Everything (slow):
cargo test          # or `make test`

The nub-cli integration suite lives in crates/nub-cli/tests/*.rs — e.g. pm_verbs, install_engine, info_engine, cli_grammar_parity, pm_identity, pm_two_mode, resolution_compat, node_compat, version_tiers, workspace_run, the pm_shim* / *_config files. Use the file stem as --test <stem>.

Step 4 — Before pushing: the exact CI cheap gates

Match .github/workflows/ci.yml exactly — a scoped -p without --all-targets misses test-code lints:

cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --check
cargo test -p <crate>        # scoped to what you changed

Then run the full pre-push local verification loop in AGENTS.md (incremental build → exact CI gates → e2e tmp-fixture run → Docker for global-cache/config behavior → promote durable checks into the suite). For the e2e probe loop specifically, use the ad-hoc-test skill. Get it green locally and push ONCE — fix-after-fix pushes saturate the shared CI runner pool.

Crate map — where things live

crates/nub-cli — the CLI (clap dispatch + PM verb routing).

• src/cli.rs — the clap command grammar + dispatch (the pnpm-compatible PM surface, run/watch/nubx/upgrade/node, the top-level file runner).
• src/main.rs — entry point.
• src/pm_engine/ — routes PM verbs into the vendored aube engine in-process. mod.rs (ENGINE_VERBS), present.rs (rebrands engine output: ERR_AUBE_*→ERR_NUB_*, aube→nub), config_scope.rs (mirror-active-PM / brand-boundary config policy), identity.rs (PM-identity inference), install_family.rs, info_family.rs, publish_family.rs, store_config_family.rs, use_*.rs, and bun_config.rs / yarn_* / unsupported_config.rs for incumbent-PM compat.
• src/agent/ — agent surface.
• tests/*.rs — integration tests.

crates/nub-core — runtime/orchestration.

• src/node/ — Node integration: discovery.rs (find the user's Node on PATH), version.rs (version management), flags.rs (V8 / Node flag injection), feature_matrix.rs (tier + Node-version gating — the source of truth for version-gated feature claims), spawn.rs (process spawn), mod.rs.
• src/pm/, src/workspace/, src/version_management/.
• src/pnp.rs — Yarn PnP support.

crates/nub-native — the N-API addon (a cdylib loaded into the user's Node process). The oxc-based transpiler + resolver: transform.rs (TS/JSX transform), resolve.rs (module resolution), tsconfig.rs, cache.rs (transpile cache), detect.rs.

vendor/aube — the vendored aube package-manager engine (plain in-tree files since Pattern B, vendored from nubjs/aube). Its own Cargo workspace; nub takes path deps into vendor/aube/crates/* and calls aube::commands::<verb>::run(...) in-process. NEVER a subprocess. From a build standpoint it's just part of the workspace — cargo build compiles it as a dependency. Changes to it are normal nub edits/PRs touching vendor/aube/* (no pin, no submodule). For pulling FROM / pushing TO upstream jdx/aube, see the aube-sync skill.

Quick reference

# fresh worktree (see the `worktree` skill: nub scripts/new-worktree.ts <slug>)
cd ~/.cache/nub/worktrees/<slug>
# build/test through the wrapper — shared cache, auto-isolates on depended-on-crate divergence (`rust-build` skill)
scripts/rust-build.sh build -p nub-cli --profile fast
scripts/rust-build.sh test  -p nub-cli --test <file_stem>

# build (fast profile)
cargo build -p nub-cli --profile fast          # -> target/fast/nub  (~3 min cold, ~5s incremental)
make install-dev                                # full binary + addon on PATH as nub-dev/nubx-dev
make addon-fast                                 # native addon only

# test
cargo test -p nub-cli --test <file_stem>        # one file
cargo test -p nub-cli <substring>               # one test by name

# CI cheap gates
cargo clippy --all-targets --all-features -- -D warnings
cargo fmt --check

Impact analysis

A self-review answers two different questions, and they need two different lenses. The correctness lens asks "is the changed code itself right?" The impact lens asks "what ELSE in the codebase did this change just break — silently, at a distance?" A change can be locally flawless and still break a caller three files away that relied on the old return contract, a serialized format that's now incompatible, or a match arm that no longer compiles. Impact analysis is the lens that catches that, and it is a MANDATORY leg of every significant self-review — at least one sub-agent doing impact analysis, alongside the correctness reviewer(s). This is the maintainer directive; see AGENTS.md → "Model tiering for sub-agents."

The deliverable is a CLEAN, EVIDENCE-BACKED impact report: every changed symbol traced to every site it touches, each site classified traced-and-safe / needs-a-corresponding-change / couldn't-fully-trace, with file:line evidence. Same trust bar as an audit — a confident "no impact" that misses a broken caller is worse than no review.

The one rule: trace, never assume

The single failure mode this lens exists to prevent is reasoning from memory — "I'm pretty sure nothing else uses this." You do not know the blast radius until you have enumerated it with tools. Every claim of impact (or no-impact) is grounded in grep / LSP find-references / reading the actual call site — never in recollection of how the code is shaped. A change is "safe at a site" only after you've READ that site and confirmed the caller's assumptions still hold. If you can't reach a site (dynamic dispatch, reflection, a macro, cross-language FFI, a string-built name), you say couldn't-fully-trace — you never paper over the gap with a guess.

(The read-only-reviewer discipline applied to reach: flag uncertainty explicitly — if you cannot verify a claim, say so rather than guess; and the load-bearing-claim rule: verify against the actual source, never training data.)

Method — systematic, evidence-based

0. Source the diff first; it is the authoritative scope. Read the diff you were handed (a path on disk, or git diff --merge-base origin/<base>). The set of changed symbols comes from the diff, not from a re-derivation of what the task "was about." Enumerate every symbol the diff touches — functions/methods, fields/struct-members/consts/statics, enums/variants, traits/interfaces/impls, public exports, behavioral/semantic changes, serialized or persisted shapes, env/CLI contracts.

1. For every MODIFIED function/method → find ALL call sites. grep the name across the workspace AND use LSP find-references (a grep misses method calls resolved through a trait/receiver; find-references misses string-built/dynamic names — run BOTH). At each call site, READ it and ask whether the caller's assumptions still hold:

• Arguments — meaning/order/units/nullability of any arg changed? A param that went from "bytes" to "KiB", or gained an Option, breaks every caller silently.
• Return contract — type, the meaning of the value, Ok/Err/None/panic behavior, whether it can now return early/empty, ownership/lifetime.
• Errors & panics — a function that newly returns Err (or newly panics, or stops returning an error a caller matched on) changes every caller's error handling.
• Ordering & side effects — did the change alter when/whether a side effect happens (a write, a log, a mutation, an await point, a lock acquisition), or the order relative to other effects a caller depends on?

2. For every CHANGED variable/field/struct-member/const/static → find ALL readers AND writers. A field whose type, units, default, or invariant changed ripples to everyone who reads or writes it. Check: does every reader still interpret the value correctly? Does every writer still satisfy the new invariant? Did a const's value change in a way that shifts behavior at a distant use site (a timeout, a batch size, a path, a cache key)?

3. For every CHANGED enum/trait/interface → find ALL match arms / impls / implementors. Adding/removing/renaming an enum variant breaks every match (Rust's exhaustiveness catches missing arms at compile time, but a catch-all _ SILENTLY swallows a new variant — flag those). Changing a trait/interface signature breaks every impl/implementor; check each one. Removing a method that an external crate or the public API implements is a breaking change.

4. For BEHAVIORAL/SEMANTIC changes → trace downstream effects. The hardest and highest-value category — the compiler won't catch these. When the behavior of a code path changed (not its signature), trace where that behavior is observed:

• Persisted / serialized formats — lockfiles, cache files, on-disk state, JSON/wire formats. A changed field name or shape that round-trips through disk breaks forward/backward compatibility and every consumer of the old format.
• Cache keys — did the input that feeds a cache key change meaning? A stale-key bug is a silent correctness bug.
• Public API / ABI — anything a user imports, calls by a documented name, or links against. (In nub: anything crossing the brand/public-surface boundary — see AGENTS.md.)
• Cross-process / env contracts — env vars set for a child shim, exit codes, stdout/stderr format another process parses, the node-hijack contract. A child reads what the parent writes; both ends must move together.
• Concurrency / ordering invariants — a change that reorders effects, moves work across an await/thread boundary, or alters lock scope.

5. Tests — coverage delta. Which tests exercise the changed path? Did the change move behavior OUT from under an existing test (the test still passes but no longer covers the new path)? Does a now-changed call site have a test that bakes in the OLD assumption and will pass misleadingly? Name the coverage gap; a green suite over a stubbed/uncovered path is the failure the testing philosophy warns about.

Output contract — a structured impact report

Per changed symbol, report:

• Symbol — what changed (file:line in the diff), and the nature of the change (signature / type / value / behavior / format).
• Blast radius — the sites found, each as file:line with a one-line note of what it relies on. Distinguish how you found it (grep / find-references / both) so a gap is visible.
• Per-site classification — each site is one of:
  • traced-and-safe — read it, the caller's assumption still holds, with the reason.
  • needs-a-corresponding-change — this site breaks (or silently misbehaves) under the change; state the required update. This is a finding.
  • couldn't-fully-trace — dynamic/reflective/macro/FFI/string-built reach you could not resolve statically; name it as a residual risk, don't bury it.
• Latent breaks — anything that compiles but is wrong at runtime (the high-value catches: a _ arm swallowing a new variant, a serialized-format skew, a caller relying on old ordering, a now-uncovered test path).
• Confidence — and an explicit escalation marker if low, so the orchestrator re-routes or widens the trace.

Lead with the findings (needs-a-change + latent breaks + couldn't-trace); the traced-and-safe list is the evidence that the trace was thorough, not the headline. A useful finding shape: an Affected sites list of file:line and a Required outcome per real finding.

When it triggers

• Every significant self-review dispatches at least one impact-analysis pass — this is mandatory, not a judgment call (AGENTS.md). For large / cross-cutting / public-surface / format-touching changes, give it its own dedicated reviewer split from the correctness lens; for a smaller-but-non-trivial change, it's still a required lens of the review.
• Exempt: genuinely trivial diffs with no behavioral surface — comment/doc/whitespace-only, a mechanical rename whose ONLY effect is import-path updates (read the shape, not the line count), a lockfile regeneration. The moment a diff changes a signature, a value, a behavior, or a format, impact analysis is required.

Tier + role

Opus (or Fable) at high+ effort — this is judgment-dense reach analysis, not a mechanical harvest; never economize it to Sonnet/Haiku for the deciding. (A cheap tier MAY harvest raw call-site lists, but every "safe"/"breaks" verdict is Opus-decided.) The reviewer is read-only over the diff + the codebase: it traces and reports, it does not land fixes. The owning implementer (or orchestrator) treats each finding as a hypothesis, verifies it against the code, and applies the corresponding change — then re-reviews until the impact report is clean.

Relationship to the other review lenses

Impact analysis is one lens of a multi-lens self-review, not the whole review. It runs ALONGSIDE the correctness lens (is the changed code right?) and, where the blast radius warrants, the safety / portability / docs-honesty lenses (see implementation-thread). Its unique job is reach — the distance a change travels — which the correctness lens, focused on the diff itself, structurally under-weights.

implementation-thread

The end-to-end workup for taking ONE task/issue from nothing to a reviewed, CI-green PR held at the merge gate. The unit of work is a single coherent change (a feature, a fix, a refactor) — not a campaign of many (that's fray's job).

The shape — ONE owning L1, L2s underneath (the doubly-nested pattern)

The implementation-thread is owned by a single L1 sub-agent dispatched by L0 (the orchestrator). That L1 carries the work through every phase, and spawns its own L2 sub-agents for the sub-steps that benefit from a fresh context or parallelism — the design pass, the design review, the multi-lens review fan-out, an adversarial verification. The L1 holds continuity; L0 stays lean.

Do NOT decompose an implementation-thread into a SERIES of L0-dispatched phase-agents (design-agent returns to L0 → L0 dispatches review-agent → returns → L0 dispatches impl-agent → …). That bloats L0's context with every phase's full return, forces L0 to re-pack context into each fresh dispatch, and loses the continuity a single owner keeps for free. One L1 owns it; L2s do the fan-out work beneath it.

L0 (orchestrator)
└── L1  ── owns the implementation-thread end-to-end ──┐
      ├── L2: design                                    │ continuity lives here,
      ├── L2: design review                             │ not re-packed at every
      ├── L2: multi-lens review (×N, split by dimension)│ phase boundary
      └── L2: adversarial verification                  ┘

The series-of-L0-phases shape is only ever justified when you KNOW every single phase boundary ends in a heavy human decision — and even then the nested shape subsumes it, because the L1 can simply pause and surface (below). Default to nested.

Pause to surface — a FIRST-CLASS pattern (use it; it is not a failure)

An L1 (or any sub-agent) coming to rest to surface a question UP to its parent is a valid, encouraged pattern — not an incomplete handoff, not a failure. A sub-agent does not have to run to terminal completion. When the L1 hits a decision it should not make alone, it stops, states the decision crisply, and rests — surfacing the question to L0, which surfaces it to the human. The L1 is later resumed (via SendMessage, with its full context intact) once the answer comes back, and continues from exactly where it paused.

Pause to surface when:

• A maintainer-owned decision appears — a default, a security posture, a product behavior, a brand/API/config/env surface, an architecture call. These are recommend-only; the L1 surfaces options + a recommendation and waits, it does NOT pick and land them.
• The design forks in a way a human should weigh in on (two defensible approaches with a real trade-off).
• A discovered fact invalidates the task's premise (the bug isn't real; the feature already exists; the approach is blocked).
• The change's blast radius turns out larger than briefed and warrants re-scoping.

How it works mechanically:

• The L1 writes the open question into its thread (## Open questions) and its rest message, then comes to rest.
• L0 reconciles, surfaces the question to the human, and on the answer RESUMES the same L1 by id (never cold-redispatches a replacement — that loses the runbook + context).
• The L1 moves the answered question into ## Decisions and continues.

This is the release valve that makes the single-owning-L1 shape strictly better than a forced L0 checkpoint at every phase: you get the human-in-the-loop checkpoint exactly when a decision needs it, and nowhere else.

The phases (the L1 owns all of these)

1. Plan / design. Map the REAL code (cite file:line; ground in code or an experiment, never memory). Produce candidate approaches + a recommendation. For a non-trivial change, run this as an L2 so the design is a clean artifact.
2. Self-review the plan. A fresh-context L2 critiques the design for elegance + minimalism + correctness, settles open calls, and BLESSES it or sends it back. Catch the design error before any code exists. (This is where most of the leverage is — a wrong design caught here is free.)
3. Implement. In an isolated git worktree (never the shared main tree — see Mechanics). The blessed design + tests + docs (a user-facing change isn't done until site/content/docs/ reflects it). Run the pre-push local-verification loop.
4. Self-review the implementation. MANDATORY for any significant change: spawn fresh-context L2 reviewer(s) over the diff. At least one reviewer MUST be an IMPACT-ANALYSIS pass — tracing the diff's blast radius through the whole codebase (every call site / reader-writer / impl / match-arm of a changed symbol, plus downstream behavioral/serialized/cross-process effects), per the impact-analysis skill. This is a required lens, not optional. For large / security-critical / memory-or-UB-adjacent work, spawn multiple L2s split by dimension (correctness, impact analysis, the relevant safety axis, portability/platform, docs/test-honesty). Fix → re-review until clean.
5. Open the PR. From the worktree. If it resolves an issue, the body MUST carry Closes #N (verify before gh pr create). Report the URL. Do not merge.
6. Await CI. Watch with --fail-fast (the ci-watch skill / a background watcher). A failure is immediately actionable — diagnose it (it's often a test that assumed the dev host, not the change), fix in the worktree, re-push. Loop until green. Distinguish a real failure from a known-cosmetic flake.
7. Integrate external reviews. Before considering it ready, check the PR for external / bot reviews. Integrate the VALID findings (fold them in, re-verify); decline the invalid ones without conversational back-and-forth (terse or silent — never chat with a bot).
8. Return control — HOLD at the merge gate. The PR is green + reviewed + held. The L1 surfaces the final state to L0 (PR URL, what landed, review outcome, CI status, any behavior change needing ratification) and STOPS. L0 / the human reviews and merges.

Return control before merge — the hard gate

The implementation-thread STOPS at a green, reviewed, held PR. It does not merge — unless the user explicitly said "merge it" / "take it all the way through to completion" / equivalent at dispatch time. This is the defining property of the skill: the human (or L0 on the human's behalf) gets the last look, especially for anything that changes a shipped behavior, a default, or a public surface. When the user DID pre-authorize the merge, the L1 still gets to green + reviewed first, then merges on a directly-verified-green rollup (not a watcher's exit code).

Mechanics

• Worktree + PR flow (the worktree skill): substantive work lands via a PR from an isolated worktree off origin/main, own CARGO_TARGET_DIR. NEVER branch/reset/stash the shared main tree. Content/UI/docs-only changes are the exception that commit direct to main.
• Pre-push local-verification loop (AGENTS.md): incremental build → the EXACT CI cheap gates (cargo clippy --all-targets --all-features -- -D warnings, cargo fmt --check, scoped tests) → an e2e tmp-fixture run of the actual feature → promote a durable check into the suite. Green locally, push ONCE.
• Model tiering: the owning L1 and its judgment/engineering/review L2s are Opus (or Fable for the hardest synthesis); mechanical L2s can be cheaper. Every L2 prompt is SELF-CONTAINED (a fresh context carries nothing over).
• Thread hygiene (fray): the implementation-thread IS a fray thread — the L1 owns its .fray/<slug>.md (Goal · Status · Decisions · Open questions · Steps · Next step), edits it in place, and moves answered questions into Decisions. The hold-before-merge state is blocked (waiting on the human) or active (work in flight).

Relationship to research-thread

If the deliverable is a PLAN or findings — not landed code — that's a research-thread, not this. A research-thread terminates done with the plan as its artifact; you spin up a SEPARATE implementation-thread later if/when the plan is actioned. Use this skill only when the deliverable is a shipped (held-at-gate) change.

prose-writing

The canonical guide is PROSE.md at the repo root — read it. This skill exists to make that guide auto-surface whenever copy is being written, and to index it. PROSE.md is the single source of truth; do not duplicate its content elsewhere, and when a general copy rule is added or corrected, update PROSE.md (then sweep every doc/page it applies to).

When this applies

Any user-facing text: a GitHub issue/PR comment, a docs page (site/content/docs/**), blog/marketing/homepage copy, release notes, a package/PR description field, or a chat reply. Also whenever you receive a general copy-style correction — apply it everywhere it's relevant, not only at the spot it was raised, and record it in PROSE.md.

The agent that WRITES the copy loads this skill — not the orchestrator on its behalf. If you are delegating copy work (a sub-agent that will post an issue/PR comment, write a PR body, close an issue, edit docs, or draft release notes), put "load the prose skill before writing" in that sub-agent's prompt. The orchestrator loads this skill only for copy it writes in its OWN turn (a chat reply, a control-surface edit). Comment / PR-body / docs / release-notes writing is delegable — delegate it, and the writer loads the skill.

What's in PROSE.md (read the relevant section before writing)

• GitHub issues & PRs — factual/neutral/professional tone, no niceties or preamble; acknowledge an external report the moment you start; never reply to a bot as if human; Closes #N/Fixes #N in a fix-PR body (Refs #N if it only relates); close issues with a brief factual comment, never silently; on release, comment the version + link on every shipped issue/PR.
• Public-facing docs — terse, code-first, no marketing fluff; show the thing working. Sentence/heading mechanics (never start a sentence or heading with inline code or a command), structure & density, honesty & restraint, description-field rules.
• Blog & marketing — open with the thing working; code blocks carry the argument; no walls of text; benchmarks as visuals; protective-refusals shown with real output; asides sparing.
• Markdown mechanics — never hard-wrap paragraphs; scannable over dense; release-notes shape; marquee-announcement shape (narrative arc, perf-multiplier framing, named attribution, signed milestone posts); migration / breaking-change entry shape.
• Naming & capitalization, and the universal tone rules (apply to every surface above).

The through-line (if you read nothing else)

Factual, neutral, terse, scannable. State what is true; cut everything that does not add a fact. Never braggy, competitive, hyped, or over-promising. Build for a reader who skims. Then open PROSE.md for the specifics of the surface you're writing.

Cutting a nub release

A nub release is tag-triggered and fully automated. Pushing a v* tag fires .github/workflows/release.yml, which builds 8 platforms, gates them (test, lockfile conformance, glibc-floor, pre-publish smoke), publishes 10 npm packages via OIDC trusted publishing (no secrets), and creates a GitHub Release with 16 attached assets. The human-side work is: confirm the fixes are green, bump the version, push the tag, then write good notes and close the loop on issues/PRs.

Guardrails (read first, non-negotiable):

• NEVER cut a release without the maintainer's EXPLICIT, IN-THE-MOMENT say-so (HIGH PRIORITY — #1 gate). A release publishes to npm and cannot be un-published — it is a published-external, irreversible act, which makes the timing maintainer-owned, FULL STOP. Do NOT infer authorization from a standing goal ("land X so I can upgrade"), from a fix being merged + green, from a sub-agent reporting "autonomous per the release rules," or from autonomous-mode being on (autonomous mode explicitly excludes irreversible/published-external acts). "Green and ready to release" ≠ "release now" — the maintainer routinely wants to batch more in first. The orchestrator may PREPARE (confirm green, draft notes, stage the version) but MUST WAIT for an explicit "cut it" / "ship it" / "release now" before make version + tag + push. When work is green and a release could go, SURFACE it as a recommendation and ask — never tag. (Burned 2026-06-27: cut v0.2.6 off a sub-agent's "proceed autonomously" claim; the maintainer wanted to batch more first.)
• Do NOT cut until every targeted fix is landed on main AND CI-green. A release is the point of no return — you cannot un-publish an npm version. The whole reason this is a deliberate, tag-triggered flow. (This is a prerequisite, NOT authorization — the explicit say-so gate above still applies even when everything is green.)
• Pre-release version regime: stay in 0.0.x / 0.1.x. A normal release is a patch bump (0.1.2 → 0.1.3). Bump the minor to 0.2.0/0.1.0 only on explicit instruction (reserved for a polished public launch — whitepaper + benchmarks + install experience ready). Never invent a version; derive it from the latest tag.
• The tag MUST equal the committed version. CI's verify job fails the release if v<tag> ≠ npm/nub/package.json version. So: make version → commit → tag → push, in that order, with the tag matching exactly.
• Release notes are FACTUAL and NEUTRAL — the repo is PUBLIC. No braggy, competitive, or superlative framing; no "fastest", no "beats X", nothing a skeptic could screenshot. State WHAT CHANGED. This is the same rule as commit messages (see AGENTS.md "The repo is PUBLIC" + the commit-message rule). Also: no internal/benchmark-strategy/competitive discussion in the notes.

Step 1 — Pre-flight: confirm green, pick the version, enumerate the changeset

git -C "$(git rev-parse --show-toplevel)" switch main && git pull --ff-only
git fetch --tags
PREV=$(git describe --tags --abbrev=0)        # e.g. v0.1.2 — the latest release tag
echo "Latest tag: $PREV"
git log "$PREV"..HEAD --oneline               # the full changeset since the last release

• Confirm the targeted fixes (from the release thread's "Fixes targeted for …" list) are all present in $PREV..HEAD and each is CI-green on main. If a fix is still converging or its CI is red, STOP — the release is blocked (the thread's depends_on gate). Slip it to the next patch rather than cutting early.
• Confirm docs are current. For every user-facing feature or behavior change in the changeset, verify that site/content/docs/ already reflects it. A shipped feature whose docs lag is a release blocker — land the doc update on main before cutting the tag (not after).
• Pick the next version: patch-bump $PREV (drop the leading v). v0.1.2 → 0.1.3.
• Keep the git log "$PREV"..HEAD output — it is the raw material for both the release notes (Step 4) and the issue/PR loop (Step 5). Note any vendor/aube/** changes in the range (vendored PM-engine changes ship fork engine behavior; mention the user-facing effect, not the diff).

Step 2 — Version bump

make version V=<ver>      # sets all 9 npm packages + Cargo.toml + runtime/version.mjs in lockstep
make version-check        # MUST pass: cross-package consistency + @oxc-project/runtime ↔ nub-native oxc pin

make version-check is the same gate CI's verify job runs; a non-zero exit here means the release would fail at CI immediately, so fix it before committing. make version also moves runtime/version.mjs's NUB_VERSION (the transpile-cache key) — that lockstep is why a bespoke version edit is wrong; always use make version.

Step 3 — Commit, tag, push (this triggers CI)

The release version-bump + tag commit is a deliberate EXCEPTION to the repo's PR-default flow (AGENTS.md "Default to a PR flow") — it commits DIRECTLY to main. The release is tag-triggered and not a reviewable feature diff, so no PR.

git add -A
git status                # SANITY: commit ONLY the version-bump files. If unrelated WIP is in the
                          # tree, stage just the touched version files (see the v0.1.2 precedent:
                          # the release commit kept in-flight site/.claude WIP out of it).
git commit -m "v<ver>"
git tag v<ver>
git push origin main --tags

Post-merge, fast-forward the shared tree so it tracks origin: git -C <shared-tree> pull --ff-only (the eagerly-pull rule, AGENTS.md "Default to a PR flow" — the shared checkout otherwise drifts behind as PRs land).

Pushing the v<ver> tag fires the release workflow. It runs, in order: verify (version + tag-match), primer (metadata primer generation), test + conformance + glibc-floor-guard + pre-publish-gate (the publish gates), build (8 platforms), then publish-npm (10 packages, idempotent), github-release (release + 16 assets, independently re-runnable), and test-install / test-install-musl (post-publish smoke of the published package).

Watch CI, but never block the foreground on it. Dispatch a background watcher (a sub-agent or a detached gh run watch writing to a log path) and report the log path; do not poll in the foreground. The release is not "done" until publish-npm + github-release are green.

Step 4 — Comprehensive release notes (Opus)

CI's github-release job creates the release with generate_release_notes: true (GitHub's auto commit/PR list). Replace that with hand-written, scannable, factual notes — do not leave the release on the raw auto-list. Drive this on Opus.

Build the notes from the full git log "$PREV"..HEAD changeset (Step 1), not just the headline fixes — every user-affecting change ships.

Notes must be SCANNABLE, not paragraph-dense. A reader skims headings, tables, and the heads-up callout and gets the whole release at a glance — they should never have to read a run-on paragraph to find what changed. The cross-project prose/tone guide for all public-facing copy — including the release-notes shape — is PROSE.md. The concrete rules:

• One-line intro stating what the release is about (the dominant theme).
• Themed ## sections, not generic buckets. Group by what the changes touch — e.g. "Lockfile compatibility" / "Performance" / "Runtime fixes" / "Documentation" / "Testing & internals" — not by Fixes/Compatibility/Internal abstractions. Each major change gets a short titled blurb or a table row, never a multi-sentence paragraph.
• A table for a batch of independent fixes. When several small fixes share a theme (a run of lockfile fixes), put them in a table — | Area | What changed | Commit | — tables read far faster than a bullet wall.
• A callout for heads-up / migration items. Anything a user should know before upgrading (a cache-schema re-warm, a behavior change) goes in a GitHub-flavored alert: > [!IMPORTANT] (or > [!NOTE]), not buried in a bullet.
• Per-item links. Every fix/change links to its commit ([abc1234](https://github.com/nubjs/nub/commit/<full-sha>)) and/or PR ([#17](https://github.com/nubjs/nub/pull/17)). Issue refs link too ([#16](https://github.com/nubjs/nub/issues/16)).
• An auto-generated ## What's Changed section at the BOTTOM (MANDATORY) — this is what makes "lists every change" literally true. GitHub's PR-level breakdown (every merged PR + author + New Contributors) plus the **Full Changelog**: <PREV>...v<ver> compare link, from gh api …/releases/generate-notes (command below). Append it verbatim under a --- separator below the curated narrative — the curated themes stay on top, the exhaustive PR list goes underneath.
• Tone: factual + neutral. Readability ≠ hype. Each line states what changed. No superlatives, no competitive framing, no editorializing. (Same bar as commit messages — AGENTS.md.) Visual interest comes from structure (sections, tables, callouts), never from marketing language.

Template (adapt the section names to the actual changeset):

<One-line intro: what this release is about.>

> [!IMPORTANT]
> **<Heads-up title>.** <The one thing to know before upgrading. Omit the callout if there's nothing.>

## <Theme A, e.g. Lockfile compatibility>

<Optional one-line lead.>

| Area | What changed | Commit |
| --- | --- | --- |
| <area> | <what changed, one clause> | [`<sha7>`](https://github.com/nubjs/nub/commit/<full-sha>) |

## <Theme B, e.g. Performance>

<Short blurb with the PR link inline.> ([#17](https://github.com/nubjs/nub/pull/17))

## Testing & internals

- <Bullet> ([`<sha7>`](https://github.com/nubjs/nub/commit/<full-sha>)).

---

## What's Changed

<!-- appended verbatim from `gh api …/releases/generate-notes` — the PR list, New Contributors, and Full Changelog link -->
* <PR title> by @<author> in https://github.com/nubjs/nub/pull/<n>

**Full Changelog**: https://github.com/nubjs/nub/compare/<PREV>...v<ver>

Generate the bottom ## What's Changed breakdown mechanically so every merged PR is listed:

# PR-level list + New Contributors + Full Changelog compare link — append verbatim below the curated narrative
gh api repos/nubjs/nub/releases/generate-notes \
  -f tag_name=v<ver> -f previous_tag_name=$PREV --jq '.body'

Append that block under a --- separator below the curated sections, then gh release edit. The curated narrative stays on top; this exhaustive PR list goes underneath.

Update the release body:

# Edit a notes file, then:
gh release edit v<ver> --notes-file <path-to-notes.md>
gh release view v<ver> --repo nubjs/nub --json body -q .body   # verify it rendered

The v0.1.4 and v0.1.3 release bodies are the reference exemplars of this structure.

Step 4b — Publish the notes as a blog post (MANDATORY — every release)

Every release also ships as a blog post under site/content/blog/. This is a standard release step, done on every version — the same content/presentation-to-main exception as docs (commit directly to main, no PR). Before writing, invoke the prose-writing skill and follow PROSE.md (blog copy: routine patch notes stay factual, neutral, unsigned, scannable — no hype, no personality; a milestone version gets a fuller treatment but the same neutral bar).

• File: site/content/blog/nub-<major>-<minor>-<patch>.mdx (e.g. nub-0-2-10.mdx) — the filename is the URL slug (/blog/nub-0-2-10); fumadocs auto-globs content/blog/*.mdx, so no index/meta wiring is needed.
• Frontmatter (schema from source.config.ts — all four required): title: "Nub <ver>" (add a : <theme> subtitle only for a milestone/single-theme release), description: a plain sentence stating the theme with NO inline code/backticks (the field renders raw — de-emphasize code tokens to plain words), author: The Nub Team, date: <YYYY-MM-DD> back-dated to the release's publishedAt so the blog timeline stays chronological.
• Body: a short lede (the dominant theme), then the release's themed sections adapted to blog prose — NOT the raw "Commits in this release" changelog dump. Carry over the heads-up > [!IMPORTANT] / > [!NOTE] callouts and the per-theme tables; keep the PR/issue links that matter. Close with a link to the full release notes: The [full release notes](https://github.com/nubjs/nub/releases/tag/v<ver>) list every change in this release.
• Scale to the release: a small patch gets a short post (a few sections); a milestone (a minor bump, a headline feature) gets a fuller one that opens with the thing working (a code block within a sentence or two of the heading, per the blog rules).

Reference exemplars: any site/content/blog/nub-0-2-*.mdx post (nub-0-2-0.mdx for a milestone, nub-0-2-5.mdx for a small patch).

Step 5 — Close the loop on issues + PRs (MANDATORY — always, no matter what)

Comment a brief factual note carrying the version and a link to the release on EVERY closed issue and EVERY merged PR that shipped in this release — not just the headline fixes. This is mandatory maintainer hygiene (AGENTS.md "Git & GitHub maintainer hygiene"); do it on every release without exception. Users see "fixed" the moment an issue closes, but the fix is not on the released binary until the tag publishes — this comment closes that credibility gap and gives the reporter a link to the exact release.

The release URL is https://github.com/nubjs/nub/releases/tag/v<ver>. Every comment includes both the version and that link, e.g. Shipped in v<ver>: <release URL>.

Enumerate the targets MECHANICALLY — never a hand-typed list. A hand-enumerated pass silently misses any issue still open at cut time or closed AFTER the cut (this happened on v0.3.0). Drive the set from the union of three queries:

# 1. Every issue a shipped PR auto-closes (closingIssuesReferences) + any Closes/Fixes/Resolves #N in a PR body:
gh pr list --repo nubjs/nub --state merged --search "merged:<PREV-date>..<cut-date>" \
  --json number,body,closingIssuesReferences --limit 200 \
  --jq '.[] | {pr:.number, closes:[.closingIssuesReferences[].number], refs:([.body|scan("(?i)(?:clos|fix|resolv)\\w*\\s+#(\\d+)")]|flatten)}'
# 2. Every issue closed in the release window (catches issues closed without a linked PR):
gh issue list --repo nubjs/nub --state closed --search "closed:<PREV-date>..<cut-date+1>" \
  --json number,title,stateReason --limit 200

For each issue/PR in the union, check whether it ALREADY carries the comment before posting (gh issue view <n> --repo nubjs/nub --json comments --jq '[.comments[].body|select(test("Shipped in v<ver>"))]|length') — skip a NOT_PLANNED issue with no shipped fix. Re-run this pass for any issue closed AFTER the cut — a late-closing issue does not appear in the first sweep.

Then comment (short, factual — what fixed it + the version and release link, no fluff):

REL="https://github.com/nubjs/nub/releases/tag/v<ver>"
gh issue comment <n> --body "Fixed in v<ver> (now published): $REL"
gh pr comment <n>    --body "Shipped in v<ver>: $REL"

Hit every issue and PR the mechanical union above surfaces — not just the headline fixes. This is non-optional; do not skip an issue because it was "minor," and do not fall back to the release thread's targeted-fix list as the source of truth (it under-counts). Do not comment on issues unrelated to the release.

Step 6 — Post-release verify

Confirm the automated publish actually landed:

npm view @nubjs/nub@<ver> version            # the root package is on the registry
npm view @nubjs/nub@<ver> dist.tarball        # sanity: published artifact exists
gh release view v<ver> --json assets --jq '.assets[].name' | sort
# expect 16 assets: 8 platforms × {archive, .sha256}
#   nub-darwin-arm64.tar.gz(.sha256), nub-darwin-x64.tar.gz(.sha256),
#   nub-linux-x64.tar.gz(.sha256), nub-linux-x64-musl.tar.gz(.sha256),
#   nub-linux-arm64.tar.gz(.sha256), nub-linux-arm64-musl.tar.gz(.sha256),
#   nub-win32-x64.zip(.sha256), nub-win32-arm64.zip(.sha256)

A complete release has: the 10 npm packages published (@nubjs/nub, @nubjs/nub-<platform> ×8, @nubjs/types), the GitHub Release present, and all 16 assets attached. CI's own github-release job already asserts the 16 assets and test-install smokes the published package — this step is the human confirmation that the workflow reached green.

If CI failed partway: publish-npm and github-release are split + idempotent on purpose — re-run the failed job from the Actions UI (npm publish skips already-published packages; the release job re-uploads only missing assets). A version is never re-cut for a flaky asset upload; just re-run the job.

Quick reference

Invoked via the Skill tool once a release thread's targeted fixes are all landed on main and CI-green.

rust-build

Building the nub Rust workspace across parallel worktrees has one tension: cross-worktree cache reuse wants a shared target dir; correctness wants isolation. scripts/rust-build.sh resolves it — share by default, isolate automatically only when a worktree diverges a crate other crates link.

Use it

Drop-in for cargo, from any worktree (or the main tree):

scripts/rust-build.sh build -p nub-cli --profile fast
scripts/rust-build.sh test  -p nub-cli --test integration
scripts/rust-build.sh clippy --all-targets --all-features -- -D warnings

It prints which target dir it chose and why, then execs cargo with CARGO_TARGET_DIR set. Nothing else changes — same profiles, same args.

Why one shared target dir

All worktrees default to ~/.cache/nub/shared-target. A fresh worktree then reuses the crates.io dependency rlibs a sibling already compiled (the bulk of a build) and recompiles only the ~3 workspace crates — a ~5s incremental step instead of a ~3-min cold build.

This reuse works only because the path is byte-identical. rustc bakes the target-dir path into its fingerprints, so a private dir — or a CoW/APFS-cloned one — gets a 0% cross-worktree hit (measured; it's also why sccache does nothing on this workspace). Sharing one path is the only mechanism that actually reuses artifacts across worktrees. There is no copy-on-write shortcut: cargo invalidates the cloned fingerprints and rebuilds from scratch.

The hazard sharing creates

Cargo names a crate's output by package id (name + version), not source content. Two worktrees whose source for the same depended-on crate differs — classically vendor/aube on divergent branches — write the same output slot and clobber each other. A dependent crate then links the stale rlib and fails to compile against source that is actually correct:

error[E0063]: missing field `lockfile_legacy_basenames` in initializer of `aube_util::Embedder`

— a field that exists nowhere in your checkout. It's a ghost from a sibling's build. This only bites crates that other crates link: a divergent leaf binary (nub-cli) just rebuilds cleanly, so editing it is safe to share.

The rule the wrapper enforces

Baseline all sharers agree on is origin/main. So:

• Your depended-on crate sources match origin/main → share. Every sharer agrees on those crates; nothing clobbers. This is the overwhelming common case: feature work in nub-cli, integration tests, docs, non-Rust files.
• You've diverged a depended-on crate from origin/main → isolate. A private per-worktree target/ (removed with the worktree). One cold build, then stable and contamination-proof.

Depended-on crates = every workspace/vendored crate except the leaf binary crates/nub-cli: crates/nub-core, crates/nub-cache-key, crates/nub-native, and all of vendor/aube. The wrapper computes divergence with git diff against the merge-base with origin/main (committed branch work and uncommitted edits), so it adapts as you edit — start shared, and the first time you touch aube it flips to isolated on the next build.

Trade-offs and edges

• A worktree that edits aube pays a cold build even with no sibling diverging aube concurrently. The invariant is "match origin/main," which doesn't depend on observing volatile sibling state — that's what makes it robust. Isolating-only-when-a-sibling-also-diverges would save a cold build for a lone aube editor but is racy; the simple rule wins.
• Concurrent builds in two sharing worktrees serialize on cargo's target-dir lock (one waits). That's a latency cost, never a correctness one — unrelated to the contamination above. Need two builds at once? An isolated worktree (diverge a lib crate, or set a private CARGO_TARGET_DIR) runs in parallel.
• NUB_SHARED_TARGET overrides the shared path if you need a different location.
• Cleanup is unchanged: git worktree remove <path> --force drops the worktree and its private target/; the shared dir is intentionally left in place for the next worktree.

Relationship to the worktree + dev-loop skills

new-worktree.ts creates the worktree and points you at this wrapper. The dev-loop skill covers the fast-profile / incremental-build loop; this skill owns the target-dir decision specifically. When a build fails with a symbol/field that isn't in your source, this is almost always the cause — rebuild through rust-build.sh and it isolates you.

Visual review — compute occlusion, don't perceive it

The core insight: a multimodal LLM reading a flat PNG has no depth buffer and no stacking-context model. Layering and clipping bugs — z-index, overflow: hidden, fixed/sticky overlays — are precisely the class where eyeballing a screenshot fails. The browser already resolved the paint order; that result is queryable. Use evaluate_script (chrome-devtools MCP) to read the browser's answer directly.

Still take the screenshot — geometry catches occlusion the eye misses; the eye catches font-metric and color issues geometry misses. Run both passes.

Optical ≠ mathematical — equal numbers routinely look wrong

The second core insight (codified after shipping a "balanced" button that wasn't): a layout can be mathematically/geometrically consistent and still look wrong, because human perception is not a pixel ruler. Measuring getBoundingClientRect and confirming "padding is 14px on both sides" proves nothing about whether it looks balanced. NEVER declare a spacing/alignment/centering change correct from measurements alone — change it, screenshot it, and look, then adjust by eye until it looks right. The numbers are a starting point, not the verdict.

Recurring sources of "correct but looks wrong" — when you see these, expect to nudge against the math:

• Rounded caps (pills, rounded-full) eat edge space. Text/icon sitting px-3.5 from a rounded end looks tighter than the same padding against a square edge, because the corner curves away from the content. A pill with symmetric padding and a leading icon looks lopsided: the text-adjacent cap needs more padding than the icon-adjacent one. (Fix that shipped: pill keeps symmetric px, each button adds pr-*/pl-* on its text side — Copy = icon-left so pr-4; Open = chevron-right so pl-4, the mirror.)
• Icon ink ≠ icon box. A w-4 icon whose glyph is 14px and visually light (thin strokes, mass off-center — e.g. a two-square copy glyph) leaves dead space inside its box, inflating the perceived gap to adjacent text well beyond the measured flex gap.
• Optical centering ≠ geometric centering. A glyph can be mathematically centered in its box and ride visually high/low because the font's ink sits asymmetrically in the em (serifs and tall-ascender faces especially). Triangles/play-icons need to shift toward their visual mass, not their bbox center.

The discipline: when something "is correct" but the user (or you) sees it as off, believe the eye and re-look at the screenshot, don't re-cite the measurement. Geometry decides occlusion/clipping; the eye decides balance/scale/centering. Both passes, every time.

The evaluate_script routines

Replace 'SELECTOR' with a real CSS selector before running.

1 — Occlusion (the non-negotiable check)

Reports what fraction of the element is actually visible, and names anything covering it.

(selector => {
  const el = document.querySelector(selector);
  if (!el) return { error: 'not found' };
  const r = el.getBoundingClientRect();
  if (r.width === 0 || r.height === 0) return { error: 'zero-size box' };
  const N = 5;                       // 5×5 = 25 sample points across the box
  let visible = 0; const coveredBy = new Set();
  for (let i = 0; i < N; i++) for (let j = 0; j < N; j++) {
    const x = r.left + (i + 0.5) / N * r.width;
    const y = r.top  + (j + 0.5) / N * r.height;
    const top = document.elementFromPoint(x, y);   // topmost painted element here
    if (top === el || el.contains(top)) visible++;
    else if (top) coveredBy.add(top.tagName.toLowerCase() +
                                (top.id ? '#' + top.id : '') +
                                (top.className ? '.' + String(top.className).split(' ')[0] : ''));
  }
  return { coverage: visible / (N * N), coveredBy: [...coveredBy] };
})('SELECTOR')

Reading the verdict:

• coverage === 1 → fully visible, no occlusion.
• coverage < 1 with a coveredBy entry that is not an ancestor/descendant → occlusion bug. The coveredBy array names the covering element (e.g. nav.topbar). This is what catches a clipped arrow behind a sticky header.

No z-index reasoning required — elementFromPoint returns the browser's resolved paint order directly.

2 — Ancestor overflow / clip

Detects clipping by an ancestor's overflow: hidden (a sibling overlay isn't the only way an element disappears).

(selector => {
  const el = document.querySelector(selector);
  const r = el.getBoundingClientRect();
  for (let p = el.parentElement; p; p = p.parentElement) {
    const o = getComputedStyle(p).overflow;
    if (o === 'visible') continue;
    const pr = p.getBoundingClientRect();
    if (r.left < pr.left || r.top < pr.top || r.right > pr.right || r.bottom > pr.bottom)
      return { clippedBy: p.tagName + (p.id ? '#' + p.id : ''),
               overflow: o, target: r, clip: pr };
  }
  return { clipped: false };
})('SELECTOR')

clipped: false is clean. Any other return → the element is cropped by that ancestor.

3 — Alignment and spacing (measure, don't eyeball)

Compares two elements numerically. Use for anything that should align or sit at a fixed gap.

([a, b] => {
  const A = document.querySelector(a).getBoundingClientRect();
  const B = document.querySelector(b).getBoundingClientRect();
  return {
    leftAligned: Math.abs(A.left - B.left),       // px delta; ~0 = aligned
    centerXdelta: Math.abs((A.left+A.right)/2 - (B.left+B.right)/2),
    gap: B.top - A.bottom,                          // vertical spacing between them
  };
})(['SEL_A', 'SEL_B'])

State verdicts in px, not vibes: "left-edge delta 2px (clean)" or "gap 28px vs expected 24px."

⚠️ getBoundingClientRect centers the line box, not the visible ink. For two elements at the same font-size this is fine. For elements at different font-sizes that must look centered together (a large wordmark beside small nav links, a caps badge beside body text), box-center is the wrong metric — they can be box-centered and still read as misaligned. Use routine §5 instead.

5 — Optical center of mass (different font-sizes / "looks off but measures equal")

This is the routine the "optical ≠ mathematical" section demands and §3 can't give you. It measures the alpha-weighted centroid of the actual glyph ink — the true optical center — by rasterizing each label's computed font to a canvas (no screenshot, no external image library: Canvas 2D + getImageData IS the raster surface). The full implementation lives next to this skill in optical-center.js; inline it into one evaluate_script call.

// after inlining optical-center.js in the same evaluate_script:
opticalCenter(['.wordmark', 'a[href="/docs"]', 'a[href="/blog"]'])
//  → results:[{selector, comY, deltaFromAnchor}],  cssHint:[{selector, nudge}]
//    deltaFromAnchor ~0 = optically aligned; cssHint gives the ready-to-paste translate.

• One call does measure + fix + verify. Pass { apply: true } and it nudges each non-anchor toward the anchor, re-measures the real post-nudge DOM, and iterates — so it converges on the true residual even when the nudge (or a wrapping element) perturbs the baseline. Returns { before, after, appliedTranslateY }. This is what turns a naive "−2.3px" into the correct value once the nudge is expressed as a wrapping span. Don't hand-derive nudges across a layout change — let the loop converge, then transcribe appliedTranslateY to CSS.
• { overlay: true } paints the analysis onto the page — a guide line on each label's COM (anchor solid-green, others dashed-red) with a px-delta label — so the next screenshot self-documents instead of making you reconcile a JSON number against a flat PNG.
• Anchor choice matters. A filled pill/badge is optically centered by its BOX, not its caps ink; anchor to a bare-glyph sibling (or accept a sub-px residual) rather than dragging text to a caps centroid.
• Gotcha (auto-handled): the baseline probe uses vertical-align:baseline, which flex/grid ignore — so the tool auto-descends from a flex <a> to the inline element that actually hosts the text. Hand it the natural selector; it finds the text host.
• Scope: exact for a single line of plain text. Letter-spacing, text-shadow, -webkit-text-stroke, gradient text, or arbitrary raster content aren't in the font render — for those, screenshot the element's clip box and centroid the real pixels (draw the PNG into a canvas via Image+getImageData; still no external lib), or just trust the eye.

Integration — keep it to ONE tool call. Steady-state usage is a single evaluate_script: inline the function + call it. To avoid re-inlining ~6KB every time, define it once via navigate_page's initScript (runs on every new document) so window.opticalCenter is present in every later evaluate_script as a one-liner. The measure→apply→verify chain is NOT a series of calls — { apply: true } does all three in-page and returns before/after. The only irreducible handoff is live-DOM → source CSS (the tool can't edit your source); cssHint/appliedTranslateY hand you the exact value to paste.

Works with any browser-automation tool

optical-center.js is a bare, dependency-free function with JSON-in/JSON-out and no closure over outer scope — so it rides on any tool's evaluate primitive. The universal pattern is always the same two steps: inject the source once (defines window.opticalCenter) → call it. No MCP server needed; the overlay is drawn in-page, so every tool's own screenshot captures it.

// chrome-devtools MCP — inline in one evaluate_script, or persist via initScript:
navigate_page({ url, initScript: <contents of optical-center.js> })
evaluate_script(`() => window.opticalCenter(['.wm','a[href="/docs"]'], { overlay:true })`)

// Playwright (Node):
await page.addInitScript({ path: 'optical-center.js' });     // window.opticalCenter on every doc
const r = await page.evaluate(([t,o]) => window.opticalCenter(t,o),
                              [['.wm','a[href="/docs"]'], { apply:true }]);

// Puppeteer:
await page.evaluateOnNewDocument(fs.readFileSync('optical-center.js','utf8'));
const r = await page.evaluate((t,o) => window.opticalCenter(t,o),
                              ['.wm','a[href="/docs"]'], { overlay:true });

// Selenium / WebDriver (any language):
driver.execute_script(open('optical-center.js').read())       // define it once
r = driver.execute_script("return window.opticalCenter(arguments[0], arguments[1])",
                          ['.wm', 'a[href="/docs"]'], { 'apply': True })

// DevTools console / bookmarklet: paste the file, then call opticalCenter([...]).

The invariants that keep it portable — don't break these when editing the file: no import/export/require in the injected source, args stay plain JSON, the return stays JSON-serializable (never hand back a DOM node), and it keeps defining a single global. Those four are exactly what let one artifact serve chrome-devtools MCP, Playwright, Puppeteer, Selenium, and a bookmarklet unchanged.

4 — Viewport and off-screen

An element pushed off-canvas reads out-of-viewport even when the screenshot crops it away:

(selector => {
  const r = document.querySelector(selector).getBoundingClientRect();
  return {
    inViewport: r.top >= 0 && r.left >= 0 && r.bottom <= innerHeight && r.right <= innerWidth,
    rect: r,
    viewport: { w: innerWidth, h: innerHeight },
  };
})('SELECTOR')

7-step visual-review checklist

Run this for any change to site/ or other rendered UI. Steps 3–4 are the non-negotiable additions that a screenshot review cannot do.

1. Screenshot — take_screenshot, full page + tight crop around the changed element. Note candidate problem elements.
2. Console — list_console_messages. A 200 response alongside a thrown error is still a broken page.
3. Occlusion pass — run routine §1 on the changed element AND any neighbors near fixed/sticky/absolute/overlay elements (nav bars, modals, tooltips, dropdowns, sticky headers). coverage < 1 with a non-ancestor cover → flag it.
4. Clip pass — run routine §2 on the changed element.
5. Alignment/spacing pass — for anything that should align or sit at a fixed gap, run §3. Assert the px deltas; don't eyeball. For labels at different font-sizes that must look centered together, run §5 (optical center of mass) — box-center (§3) is the wrong metric there.
6. Viewport pass — confirm the element's box is inside innerWidth/innerHeight via §4.
7. State the verdict in measurements. "coverage 1.0, clip: false, left-edge delta 0px" is a clean bill of health. "coverage 0.62, coveredBy: nav.topbar" is a flag. Never a bare "looks great."

If chrome-devtools MCP is unavailable

Say so explicitly. Reason about the stacking from the CSS (position, z-index, overflow, paint-order rules) — but acknowledge that this is inference, not measurement, and is less reliable for occlusion. Do not silently claim visual verification you couldn't do.

Worktrees for parallel nub work

Substantive nub-repo work lands via a PR opened from an isolated git worktree; the shared working tree always stays on main and is never branched, reset, or stashed (see AGENTS.md "Default to a PR flow"). This skill is the fast, correct way to spin up a worktree, what .worktreeinclude brings into it, and how to clean up.

The whole setup is one command. Do not hand-roll the git worktree add + target-dir recipe — the script encodes it and is harder to get wrong. (vendor/aube is plain in-tree files since 2026-06-22 (Pattern B) — no submodule init step.)

Create a worktree

The script runs under both nub (dogfood) and plain Node — pick either:

nub  scripts/new-worktree.ts <slug>
node scripts/new-worktree.ts <slug>

It performs the proven recipe, in order:

1. git fetch origin (skip with --no-fetch).
2. git worktree add ~/.cache/nub/worktrees/<slug> -b <slug> origin/main — tracked files only; the shared tree is untouched. vendor/aube is plain in-tree files (Pattern B) — checked out by this step, no submodule init needed. The script creates ~/.cache/nub/worktrees/ if it doesn't exist. (Non-temp location: not auto-swept like /tmp; out of the repo dir; same volume as the repo so APFS clonefile stays fast.)
3. Apply .worktreeinclude — copy/symlink the listed gitignored entries in (see below).
4. Pre-create + print the shared CARGO_TARGET_DIR (~/.cache/nub/shared-target) to export — one cache for all worktrees, not a per-worktree dir.

Options: --base <ref> (default origin/main), --path <dir> (default ~/.cache/nub/worktrees/<slug>), --no-fetch, --help.

After it prints the ready line:

cd ~/.cache/nub/worktrees/<slug>
export CARGO_TARGET_DIR=~/.cache/nub/shared-target   # ONE shared cache for all worktrees
cargo build -p nub-cli --profile fast                # ~3 min cold; a later worktree reuses deps, recompiles only workspace crates

The build loop, profiles, and crate map live in the dev-loop skill (.claude/skills/dev-loop/SKILL.md). The key fact: all worktrees share ONE target dir (~/.cache/nub/shared-target), so a second worktree reuses the crates.io dependency artifacts another worktree already compiled (the bulk of a build) and recompiles only the ~10 workspace crates — and the disk cost is one target dir instead of ~30 multi-GB private ones. Tradeoff: cargo locks the target dir during a build, so a build in one worktree waits while another is building. If two builds genuinely must run at once, set a private CARGO_TARGET_DIR for the second; otherwise keep the shared default. Don't clean the shared dir between iterations — that throws away cargo's incremental cache.

.worktreeinclude — bringing gitignored things in

git worktree add checks out tracked files only, so a worktree is lean by default (no target/, node_modules/, .repos/). .worktreeinclude at the repo root lists the gitignored, untracked things a worktree may still need; the script copies or symlinks each one in.

Format — one entry per line, # comments and blank lines ignored:

[copy|symlink] <path>      # path is relative to the repo root, both sides

The leading verb is optional; the default is copy. Use symlink for large, read-only things you don't want duplicated on disk. The sources are read from the MAIN working tree (where the gitignored files actually live), even when you run the script from inside another worktree.

The shipped default symlinks .repos/ (the read-only reference checkouts of Node, Bun, pnpm, …) so worktree agents can Read/Grep them without a multi-GB copy. Do NOT add target/ — the shared CARGO_TARGET_DIR (~/.cache/nub/shared-target) is the build cache; an in-worktree target/ would be a redundant private copy, which is exactly the disk bloat the shared dir exists to avoid.

Eagerly pull the shared tree

The shared tree drifts behind origin/main because every landing goes worktree → push → merge and nothing pulls the shared checkout back. After merging any PR or pushing to origin, fast-forward the shared tree:

git -C <shared-tree> pull --ff-only

Corollary: do NOT commit directly in the shared tree's checkout — even control-surface/doc edits go via a worktree push, so the shared tree stays clean and always fast-forwardable. (Direct shared-tree commits are what make it diverge rather than merely fall behind.) This keeps the files current; loaded .claude/ hooks still need a session restart to pick up changes.

Clean up after a merge

git worktree remove ~/.cache/nub/worktrees/<slug> --force   # leave ~/.cache/nub/shared-target in place for the next worktree

--force is used to discard the worktree even with build artifacts present. Before discarding, make sure your work is pushed — a git worktree remove --force throws away anything uncommitted (vendor/aube edits are now plain in-tree files committed to the worktree's branch, so push before removing). Do NOT delete the shared ~/.cache/nub/shared-target on cleanup — it's the warm cache the next worktree builds against; wiping it forces the next build cold.

Remove ONLY the EXACT worktree path you own — NEVER hunt for one by HEAD SHA (this clobbers live siblings). A cleanup agent removes the specific path it was told to and nothing else. If that path does NOT exist, STOP and report "nothing to clean" — do NOT go searching git worktree list for a worktree at a matching HEAD SHA and remove that. Multiple sibling worktrees routinely share a HEAD (e.g. two branches both cut from the same base commit, or a stacked branch off another's head), so SHA-matching will delete a DIFFERENT agent's active worktree and --force-discard its uncommitted WIP. (Burned 2026-07-06: a #334-merge agent's stated cleanup path didn't exist, so it matched a sibling vite-bench worktree by the shared head 26d04800 and force-removed it — orphaning a live bench agent's scaffolded fixture. The branch survived, the uncommitted work did not.) A dispatch prompt that includes a cleanup step must name the exact path AND add "remove only this path; if absent, report and stop — never match by SHA."

There is also an older bash helper, scripts/worktree.sh (worktrees under .worktrees/, branched off LOCAL main, with rm/list/reap subcommands and uncommitted/unpushed-work safety checks on removal). new-worktree.ts is the preferred entry for landing work (off origin/main, .worktreeinclude support, nub-dogfooding); reach for worktree.sh reap to prune stale dead-session worktrees.