feat: staged-context verification — a subagent declares what its workspace needs, the worker checks it before the agent runs

[BrettNye]

Implements v1 of the staged-context design: contextRequires on subagent.register,
verified by the worker after pangolin-setup.sh and before baseline capture, failing the
dispatch when unmet.

Spec, DAG plan, gate-2 audit record, and implementation are all on this branch. Companion
decision spec in #151 (independent — this plan restates its argument inline).

The problem is drift, not ignorance

Agents are not under-informed; authored briefs are more explicit than any generated
manifest. What was missing is detection when a brief goes stale — bind a new toolchain
bundle and a brief's true statements silently become false. As the consumer put it: "I'll
keep hand-writing briefs; I can't hand-write detection."

Scope was inverted during design on their evidence. The first draft shipped a
declaration manifest with verification optional. contextShape already has five
declaration sites and zero readers — adding a sixth unread declaration to a system whose
problem is unread declarations would be net-negative. v1 is verification only.

Failing before the agent is about misattribution, not false greens

I originally justified this as preventing a verifier from reporting unearned success. The
consumer corrected it: their verifier answered a narrower question truthfully — they
lowered the question rather than getting a wrong answer. The real failure is
misattribution: an unmet requirement surfaces as command not found at agent time and
reads as a plan problem, four layers from the cause. That correction changed what the
feature aims at.

Design

ContextRequirement is observable-only by construction — paths (glob), exec
(binary on PATH), git (worktree / history). It deliberately cannot express
"patch applied", because verifying that means re-doing the apply rather than observing a
property. That is a stated non-goal, not a gap: it leaves half of KNOWN-ISSUES 17 open and
the spec says so plainly, because 17's framing is what invited the conflation.

It lives on the subagent def, which the worker already reads — not on SubagentShape,
which per ADR-0018 D11 the worker is ignorant of. Written only when set, so existing
subagent content hashes do not move.

Gate-2 audit: NOT READY, 8 blocking — all fixed before execution

7 lenses, no downgrades. The worst finding: the check failed open — an elided sibling
left paths/git with no push, so an unchecked requirement read as satisfied. Also: the
ordering pin did not discriminate (captureBaseline never commits, so history was
met:false under both orderings — re-based onto worktree, the only predicate that
flips); a fabricated test fence (five of six named files never call registerSubagent);
and fs.promises.glob, which typechecks on CI's Node 22 and throws on the worker's Node
20.

Execution: 5/5 done, three needed a fix round

Reviewers running code found 7 more the prose audit could not:

• A security finding. The worker spawned git with the full merged agent env,
  contradicting the invariant at runtime-env-filter.ts:24-26. GIT_DIR/GIT_WORK_TREE
  there override -C workspaceDir — the check could report met:true for a workspace
  with no git at all. Now buildGitEnv() + PATH, with a regression test that proves the
  bug first.
• Two of my own plan instructions were wrong — the illustrative .kind — .observed
  snippet would never contain the binary name, failing its own acceptance criterion; and
  the prescribed hash test stayed green when the guard was deliberately broken.
• A comment that lied about performance — readdir(recursive:true) completes the whole
  walk before the loop.

Verification worth naming

Reviewers ran mutations rather than reading assertions: deleting {recursive:true},
moving the check after captureBaseline, reverting the git env — each confirmed exactly
the intended test went red. The ordering constraint is enforced, not asserted.

One suggestion I applied turned out incomplete, caught by measuring in the Linux image:
X_OK rejects a non-executable file but a directory passes X_OK (the bit means
traversable). Added an isFile() stat and a regression test. Local Windows runs cannot
demonstrate either half — X_OK degrades to F_OK there — and the code says so.

Full repo tests green, pnpm -r lint and pnpm -r typecheck clean, docs build with all
internal links valid.

🤖 Generated with Claude Code