docs(agents): ADR 0019 unit checklist, owning-seam mock rule, worktree and rebase guidance - #1836
Conversation
|
Two documentation corrections are needed before readiness. In |
1c6b855 to
d71cd08
Compare
|
Both fixed.
🤖 Addressed by Claude Code |
|
Re-reviewed exact |
…e and rebase guidance Retro follow-up (item 2). Adds docs/agents/adr-0019-unit.md — the order of operations for one command unit with the declaration site for each step, the evidence a unit review must carry, and what 'done' is not — so the pattern rediscovered during the snapshot unit (#1779) is written down once. testing.md: mock the seam the code under test consumes (fake inspectFacts / bindDevice), not the generic dispatchCommand mock; a migrating command moves its tests off the dispatch mock in the same PR. AGENTS.md: fresh-worktree preflight (pnpm install + build in the worktree; layering scan reads tracked files only) and concurrent-agent hygiene (one full gate per host, verify subagent edits with git -C, one PR per worktree). pull-requests.md: two readiness claims (published-and-reported vs merge-ready) and the rebase rule — main has no up-to-date protection; rebase on conflict or when `check:affected --base <merge-base> --head origin/main` names your surface.
…1841 updates the row when it lands
9b0f495 to
b64ccb5
Compare
|
Decoupled in b64ccb5 (rebased onto current main; the The checklist row now documents the API on 🤖 Addressed by Claude Code |
thymikee
added
the
ready-for-human
|
Re-reviewed exact |
|
…on API #1836 documented inspectRequiredRuntimeUse with a forward note pointing here; this PR makes admitRuntimePlan real, so the row now teaches it plus the identity-keyed unwrap the binder uses, and points at the shared snapshot/diff owning interface as the model.
… the R32 syntax policy (#1841) * refactor(daemon): admit-before-bind as an identity-keyed admitted-plan token; retire the R32 syntax policy admitRuntimePlan (was inspectRequiredRuntimeUse) takes the plan and, on success, mints an AdmittedRuntimePlan: a nominal class instance with nothing readable on it. Its payload — a frozen copy of the device the facts were read for, and the plan — lives in a module-private WeakMap keyed by the token's exact identity, and the only way to read it is unwrapAdmittedRuntimePlan, which refuses anything not minted here. The snapshot owning interface (resolveBoundSnapshotCaptureRuntime, #1847) admits through it and its private binder takes only the token: no bare plan, no separate device, and no look-alike — a spread lacks the #private member (not assignable), a Proxy around a real token types as the token but is a different identity (refused at unwrap), Object.assign/defineProperty throw on the frozen instance, and the class value is not exported so its constructor is not nameable. That retires scripts/layering/runtime-command-cutover-snapshot.ts — R32's per-command AST policy (call-shape recognition of the admission and a text sniff for a local admission) — and the source-regex test beside the descriptor tests. The generic row keeps retirement, narrowing, and singular execution; the manufactured-proof column now also rejects casts to AdmittedRuntimePlan. Planted reds: token degraded to a plain public shape → 2 unused @ts-expect-error directives; unwrap reading the token surface via getters → the Proxy regression fails; getter-based branded literal → the runtime retarget test fails. * docs(agents): the ADR 0019 unit checklist teaches the shipped admission API #1836 documented inspectRequiredRuntimeUse with a forward note pointing here; this PR makes admitRuntimePlan real, so the row now teaches it plus the identity-keyed unwrap the binder uses, and points at the shared snapshot/diff owning interface as the model.
1 participant
Summary
Retro follow-up, item 2 of the agreed list. Four agent-facing doc changes; no code.
docs/agents/adr-0019-unit.md(new) — the checklist for one command unit: what to post on refactor(daemon): platform-free daemon — broader migration waves (successor to #1696) #1739 before writing code, one integration owner for the shared spine, the "can this be made impossible at the owning interface?" question before any cutover-row extension, then the unit in order with the declaration site for each step (use → plan → handler admit/bind-once → descriptor flip → platform packages → cutover row → deletions → tests on the runtime seam → facets), the evidence a unit review must carry, and what "done" is not. Linked from the AGENTS.md task table. Everything in it was rediscovered on refactor: migrate snapshot to device runtime #1779; ADR 0019 keeps the why, this keeps the how.docs/agents/testing.md— mock the seam the code under test consumes: fakeinspectFacts/bindDevice(fixture, harness, and facts-builder locations named), notvi.mock('.../core/dispatch.ts'). Sixty-odd files still mock dispatch; retiringdispatchCommand('snapshot')surfaced them one failure at a time. Don't add to the set; a migrating command moves its tests off it in the same PR.AGENTS.md— fresh-worktree preflight (pnpm install --frozen-lockfile && pnpm buildin the worktree, else@agent-device/*/airesolve against another checkout and smoke lanes fail with "Missing dist build"; layering scan reads tracked files only) and concurrent-agent hygiene (one full gate per host — parallel suites are the contention; verify subagent edits withgit -C; one PR per worktree; PRs by URL not recalled number; per-agent scratch dirs).docs/agents/pull-requests.md— two readiness claims that "don't wait for CI" kept blurring: published and reported vs merge-ready. And the rebase rule:mainhas no up-to-date protection, so rebase on conflict or whenpnpm check:affected --base <merge-base> --head origin/mainnames a surface yours depends on; evidence is stamped with the commit it was gathered at, so a rebase dates it rather than invalidating it. Merge queue deferred until migration units regularly overlap.Validation
Docs only; every claim was checked against the tree while writing:
defineUse/resolveSnapshotRuntimePlaninpackages/contracts/src/platform-runtime-operations.ts,inspectRequiredRuntimeUseinsession-runtime-admission.ts, the row model andcutoverRowDefectsinscripts/layering/runtime-command-cutover-*.ts, the fixture/harness/facts-builder paths,check:affected --head(verified ond76e0f94e...origin/main, which correctly lists only the #1826 files). Ran into both worktree traps myself in the same session (unresolvedai, "Missing dist build") before writing them down.check:affectedfails open ontesting.md(selector-owning) by design; no runtime gate applies.