docs(agents): restore and enforce progressive disclosure

[thymikee]

Summary

• restore progressive disclosure: reduce the three always/high-frequency guidance files from 120,315 to 27,868 bytes while preserving repository-specific traps and routing situational detail to focused owners
• make CONTEXT.md a domain glossary again, move selector-capture reliability into its own guide, and remove two unreferenced historical reports from the live context surface
• add a registered, docs-triggered agent-guidance gate that enforces context budgets, glossary shape, and valid routing links
• harden the merged fix(maestro): refresh targets after transient selector misses #1886 regression: the exact selector-miss message without the typed failure reason must not trigger Maestro retry
• address adversarial review by restoring the Interactor glossary term, trimming derivable hard rules, removing the duplicate testing budget, and installing workspace dependencies in the guidance CI job

Why this is a root-cause change

The contributor context mixed durable vocabulary, implementation detail, testing policy, historical reports, and generic engineering advice in files loaded for nearly every task. That made the exceptional path easier to encounter than the owning interfaces and source-of-truth registries. This change repairs the information architecture and makes renewed accretion fail CI; it does not add another prose reminder or behavior fallback.

Surviving next-major legacy cleanup remains owned by #1370. The three local uniqueStrings copies found during review are tracked separately in #1890, including a request for mechanical enforcement rather than another reminder.

Adversarial evidence

• pre-cleanup guidance contract: red on oversized AGENTS.md and non-glossary CONTEXT.md
• planted workflow ownership break: gate manifest reported the unowned agent-guidance gate and missing docs-triggered lane
• planted production message sniff: the Maestro regression failed when identical error text was accepted without details.reason; restored typed-only classification passes 2/2
• the first guidance workflow run failed because its dependency installation was explicitly disabled; the review fix removes that override so the canonical pnpm gate has its workspace packages

Validation

• pre-review pnpm check:affected --run — passed immediately before its push
• review-focused pnpm check:agent-guidance, pnpm check:gate-manifest, pnpm format:check, and git diff --check — passed
• affected coverage rerun encountered unrelated timeout-shaped failures in unchanged Apple/provider tests; the original runner-client failure passed alone in 155 ms, and the review fix was pushed for authoritative GitHub CI at the maintainer's direction
• package verification, layering, fallow, gate manifest, Maestro conformance, and agent-guidance contract passed in local validation

No live-device validation: this PR changes contributor guidance, gate wiring, and regression specificity; production interaction behavior remains the merged #1886 implementation.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://callstack.github.io/agent-device/pr-preview/pr-1888/
Built to branch gh-pages at 2026-08-20 09:44 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	2.33 MB	2.33 MB	0 B
JS gzip	765.3 kB	765.3 kB	0 B
npm tarball	890.0 kB	890.1 kB	+22 B
npm unpacked	3.10 MB	3.10 MB	+175 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	25.8 ms	25.7 ms	-0.1 ms
CLI --help	66.4 ms	66.5 ms	+0.0 ms

Top changed chunks: no changes in the largest emitted chunks.

[thymikee]

The new Agent Guidance workflow cannot run its own gate: it passes install-deps: 'false', but pnpm gate agent-guidance loads scripts/node-test-tmpdir.ts → src/utils/exec.ts → @agent-device/kernel. The exact-head job therefore fails with ERR_MODULE_NOT_FOUND before executing the guidance contracts. Please install dependencies for this job (or refactor the gate to be genuinely dependency-free) and rerun; this is a deterministic workflow configuration failure, not an infrastructure flake.

[thymikee]

Addressed the adversarial review in 95a9be346:

• fixed the blocking guidance workflow by restoring workspace dependency installation; Ownership and context budgets is green on this head
• trimmed derivable hard rules and added an ownership tiebreak instead of replacing them with more prose
• restored the glossary-only Interactor definition
• removed the duplicate docs/agents/testing.md byte budget
• confirmed surviving next-major legacy cleanup is already owned by Next major: scheduled breaking cleanups (legacy batch-step shape, deprecated rotate client surface, client-types narrowing) #1370
• filed refactor: enforce canonical uniqueStrings helper and remove local copies #1890 for the three uniqueStrings copies plus mechanical enforcement

Focused guidance, gate-manifest, formatting, and diff checks pass. The PR body now records the local broad-run timeout evidence and the CI handoff accurately.

[thymikee]

Re-reviewed at 95a9be3: the Agent Guidance dependency blocker is fixed and its exact-head check is green. I found no remaining code issues. The iOS Smoke failure is unrelated to this PR: the untouched testBareTypeUsesTappedInputWhenSoftwareKeyboardIsHidden runner test entered only “h” instead of “hardware-keyboard” (the same assertion then failed twice), while this PR changes no executable iOS code and the lane passed at the preceding head. Please rerun iOS Smoke; the code is clean, but the PR is not merge-ready until that exact-head check is green.