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

AGENTS.md

@@ -70,6 +70,7 @@ cross-language rules change through golden tables under `contracts/fixtures/`.
 - Apple target changes keep the kernel device model, capability admission, dispatch resolution,
   Apple discovery, and xctestrun preparation in sync.
 - iOS simulator-set scoping must never hide the host macOS desktop target.
+- Skills may carry a minimal start/routing card; command semantics belong in versioned CLI help.
 - Do not add compatibility or fallback behavior without explicit approval. Complete migrations and
   remove superseded paths.
 - Keep changes within one command family or module group unless the task explicitly crosses a

docs/agents/testing.md

@@ -41,6 +41,12 @@ Apple runner changes run `pnpm check:xctest-selection` and build the affected ta
 `#if` guard is the XCTest lane classification; do not maintain a second test-name list. Pure runner
 decisions use the macOS host lane, while iOS/XCTest semantics require a simulator lane.
 
+Local host-lane XCTest runs hit two snags CI never does. System policy may refuse the unsigned
+bundle (`library load disallowed by system policy`, surfacing as `Early unexpected exit … crashed
+with signal kill`); rebuild signed, with `CODE_SIGN_IDENTITY="Apple Development"` or a manual
+identity from `security find-identity -v -p codesigning`. The first run also needs XCUITest
+automation permission for the host app.
+
 Live smoke commands and their environment contracts live with their harnesses:
 
 - web: `test/integration/smoke-web-platform.test.ts`

scripts/__tests__/agent-guidance-contract.test.ts

@@ -28,7 +28,9 @@ test('high-traffic guidance stays within its reviewed context budget', async ()
 
 test('task guidance stays focused instead of growing another handbook', async () => {
   const directory = path.join(ROOT, 'docs', 'agents');
-  const files = (await readdir(directory)).filter((file) => file.endsWith('.md'));
+  const files = (await readdir(directory, { recursive: true })).filter((file) =>
+    file.endsWith('.md'),
+  );
   let totalBytes = 0;
 
   for (const file of files) {

scripts/gate/routing.ts

@@ -7,6 +7,10 @@
 // the YAML a derived artifact: over every tracked path, the lane must start whenever the
 // selector says the change can reach it, and must not start on a path the selector places on
 // another family's device-lane surface or classifies as a unit test.
+//
+// One limit is GitHub's, not this assertion's: path filters examine only the first 300 changed
+// files, so a PR larger than that can skip a routed lane on the strength of its first 300 paths
+// alone. The unfiltered `push` to main is the backstop.
 
 import { deviceLanesFor, isDeviceLaneSurface, isUnitTest } from '../check-affected/device-lanes.ts';
 import { isDocs, selectChecks, type CheckId } from '../check-affected/model.ts';