docs(agents): restore and enforce progressive disclosure (#1888)

* docs(agents): restore and enforce progressive disclosure

* test(maestro): pin typed selector fallback signal

* docs(agents): address progressive disclosure review

* docs(agents): restore orphaned traps and close guidance-gate bypasses

- AGENTS.md: skills carry a minimal start/routing card; command semantics
  stay in versioned CLI help (the skills contract enumerates two skills by
  hand, so prose retains ownership for the rest)
- testing.md: restore the two local-only XCTest snags CI never hits
  (unsigned-bundle policy refusal signature + first-run automation permission)
- scripts/gate/routing.ts: record GitHub's 300-changed-file path-filter limit
  at the paths-ignore assertion it bounds
- agent-guidance-contract.test.ts: recurse docs/agents so nested guidance
  cannot evade the byte budgets while the gate stays green

Author: thymikee

.github/workflows/agent-guidance.yml

@@ -0,0 +1,46 @@
+name: Agent Guidance
+
+on:
+  pull_request:
+    paths:
+      - 'AGENTS.md'
+      - 'CONTEXT.md'
+      - 'docs/agents/**'
+      - 'scripts/__tests__/agent-guidance-contract.test.ts'
+      - 'scripts/check-affected/**'
+      - 'package.json'
+      - '.github/actions/run-gate/action.yml'
+      - '.github/actions/setup-node-pnpm/action.yml'
+      - '.github/workflows/agent-guidance.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'AGENTS.md'
+      - 'CONTEXT.md'
+      - 'docs/agents/**'
+      - 'scripts/__tests__/agent-guidance-contract.test.ts'
+      - 'scripts/check-affected/**'
+      - 'package.json'
+      - '.github/actions/run-gate/action.yml'
+      - '.github/actions/setup-node-pnpm/action.yml'
+      - '.github/workflows/agent-guidance.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  contract:
+    name: Ownership and context budgets
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup Node and pnpm
+        uses: ./.github/actions/setup-node-pnpm
+
+      - name: Check agent guidance
+        uses: ./.github/actions/run-gate
+        with: { gate: agent-guidance }

AGENTS.md

@@ -95,4 +95,4 @@ modules must move those contracts before their client methods can stop returning
 `CommandRequestResult`.
 
 This ADR owns the decision and its constraints; the roadmap that prototyped it has been retired, with
-the delivered end-state recorded in [CONTEXT.md](../../CONTEXT.md) (Architecture).
+the delivered end-state enforced by the descriptor projections and parity gates below.

CONTEXT.md

@@ -29,8 +29,8 @@ Model Apple OSes with an **`AppleOS` discriminant** (`ios | ipados | tvos | watc
 under a single `apple` Platform — **not** six `Platform` literals. The OS-agnostic Apple engine consolidates
 under `src/platforms/apple/core/`, with genuinely per-OS code in `src/platforms/apple/os/<os>/` leaves;
 the Apple plugin is the first instance of the platform-plugin registry (the platform axis of the
-completed perfect-shape refactor; see [CONTEXT.md](../../CONTEXT.md) Architecture). Per-OS capability
-differences become data keyed by `AppleOS`. The additive,
+completed perfect-shape refactor; the registry and enforcement paths below are authoritative).
+Per-OS capability differences become data keyed by `AppleOS`. The additive,
 non-breaking `appleOs` discriminant — the groundwork for this — shipped in #896.
 
 ## Alternatives Considered

docs/adr/0008-command-descriptor-registry.md

@@ -1,8 +1,8 @@
 # Domain Docs
 
 Single-context repo. Before architecture, diagnosis, TDD, triage, PRD, or roadmap work, read
-`CONTEXT.md` for domain vocabulary and the capture-reliability contract, plus the relevant ADRs in
-`docs/adr/`.
+`CONTEXT.md` for domain vocabulary and the relevant ADRs in `docs/adr/`. Selector-capture work also
+reads `docs/agents/selector-capture.md`.
 
 Use `CONTEXT.md` vocabulary in issue titles, refactor proposals, test names, and architecture notes.
 If a proposed change contradicts an ADR, say so explicitly and explain why the decision should be