…sh-gate scope + multi-line drift (#364)

* chore(#358): drop advertised-but-not-wired allowed_tools_override field

PR #357 review caught that the agent-routing v1 schema advertised
`allowed_tools_override` in three places — apply-agent-routing.sh's
parser doc comment, agent-routing.yaml.example's schema preamble +
Example F worked-example, and docs/multi-project.md's adopter schema
table — but parse_routing() never emits the field, so adopters who
set it get a silent no-op.

Decision (recorded per #358 AC): DROP the field for v1, do NOT wire
the parser branch. Rationale:

- The full implementation needs parser emission (3 parsers) + a
  consumer-side `tools:` / `allowed-tools:` line rewrite + drift-guard
  awareness (tools-line differs from dev would need its own escape
  hatch). 50-100 line impl for a feature the docs explicitly mark as
  "advanced — use sparingly."
- Adopters who actually need a per-fork tool-list override can edit
  the agent file directly with a `# routing-config:override <reason>`
  comment in YAML frontmatter — the same escape-hatch pattern that
  already handles model: overrides. Documented in the now-deprecation
  prose.
- No migration tail: adopters who'd set `allowed_tools_override` were
  already getting a silent no-op; this PR makes that explicit in the
  schema docs.

Files changed:

- agent-routing.yaml.example
  - Schema preamble: replace the field's doc paragraph with a
    deprecation note pointing at the agent-file + escape-hatch path
  - Example F (the only worked example for the field): removed

- .claude/hooks/apply-agent-routing.sh:115
  - Parser doc comment: removed from the key-set list, added a one-line
    deprecation note pointing readers at the per-agent frontmatter path

- docs/multi-project.md:549
  - Schema table: removed the `allowed_tools_override` row
  - New post-table paragraph documenting the deprecation + the
    operator-facing escape-hatch alternative

Closes #358

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(#359): reconcile AgDR-0050 § Axis 4 push-gate scope with implementation

PR #357 review flagged a doc/impl mismatch: AgDR-0050 § Axis 4 said the
pre-push guard "sweeps before any push to a public-class remote," but
block-agent-routing-drift.sh fires on ANY push regardless of remote
class. Two possible fixes per #359: tighten the hook to check remote
class, OR update the AgDR to match the broader-scope impl.

Decision: UPDATE the AgDR (option 2, recommended in the ticket).
Rationale:

- The broader scope is actually the right design. Even a push to a
  private tracking branch can become a leak vector later if the
  operator changes the remote. Adopters staging a deliberate
  framework-default change should label it with the
  # routing-config:override escape hatch before pushing anywhere —
  not just before pushing to upstream.
- Tightening the hook to inspect @{push} remote class would add code
  and a new failure mode (silent-pass on remote-resolution failure)
  without removing a real failure surface.

Files changed:

- docs/agdr/AgDR-0050-agent-runtime-overhaul.md § Axis 4
  - Prose changed: "sweeps before any push to a public-class remote"
    → "sweeps before ANY push (not just to public-class remotes)"
  - New blockquote note explaining the resolution + linking to #359

Closes #359

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(#342): add multi-line lookback pass + self-test to test_site_counts.sh

#342 § 2(b) flagged that test_site_counts.sh's per-line grep can't
catch claims where the digit and noun straddle a line break (the
shape that bit `site/llms-full.txt:131-133` before #360 cleaned it up
by hand). This commit adds the missing pass per #342's prescription.

Implementation:

- New check_multiline_count() helper. Flattens consecutive whitespace
  (including newlines) via `tr '\n' ' ' | tr -s '[:space:]' ' '`,
  re-scans for `<digits> +<noun>`, dedupes against the per-line pass's
  hits (so a same-line claim already reported by check_count doesn't
  get double-counted), reports drift as `file:multiline` (no line
  number — the digit and noun aren't on the same line).
- Second for-loop calls the new helper for the same noun-pattern list
  as the per-line check_count loop.
- Self-test fixture at the end: synthesises a temp file with the
  exact `52\n   slash commands` shape #342 § 2(b) describes, runs
  check_multiline_count against it inside `$(...)` (subshell-isolated
  so its DRIFT++ stays scoped), asserts the expected `DRIFT:
  file:multiline — claims 52 slash commands` output line. If absent,
  the detector is broken and the suite fails.

Net coverage: the per-line + multi-line passes now together cover
both same-line and cross-line drift, closing #342's § 2(b) gap.
§ 2(a)'s remaining synonym patterns (`enforcement scripts?` and
`mechanical (enforcement )?(scripts?|hooks?)`) are NOT addressed here —
they're additional noun-pattern entries, not a structural fix.
Closing the structural gap is the higher-value half; remaining noun
patterns can be added incrementally as future drift surfaces them.

Files changed:

- .claude/hooks/tests/test_site_counts.sh:
  - new check_multiline_count() function (~30 lines)
  - new for-loop applying it to the same 9 noun patterns as
    check_count
  - new self-test at end of file (~15 lines) that proves the detector
    fires on a known-bad cross-line fixture

Test passes locally against current site/ files (which were swept
clean post-#360). Sibling tests (test_agent_routing_sync_and_drift.sh
8/8, test_agent_wrap_shape.sh 13+5+19/37) unchanged + still pass.

Closes #342 § 2(b). § 2(a) noun-pattern additions and § 1 one-time
hygiene sweep are intentional carry-overs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…s (Wave 1 PR 2) (#357)

* feat(#351): apply-agent-routing.sh SessionStart hook + framework-defaults snapshot per AgDR-0050 Axis 4

- SessionStart hook rewrites .claude/agents/*.md frontmatter model: lines
  from the adopter's agent-routing.yaml — makes the YAML LIVE on every
  session, closing the loop on Wave 1 PR 1 (#353) which only shipped the
  schema + portfolio_agent_routing resolver
- Parser dispatches yq → python3+PyYAML → awk fallback; awk handles the
  v1 schema's 2/4/6-space indentation without a YAML dependency, so
  adopters without yq or PyYAML still get the routing applied
- Snapshots the framework-default model: line per overridden agent into
  .claude/agents/.framework-defaults.json (gitignored). The drift guard
  reads this to know what model line to expect at commit time, so
  routing-induced rewrites can be told apart from intentional framework
  edits
- Per-agent env files written to .claude/session/agent-env/<name>.env
  (gitignored) for endpoint / env / timeout_seconds entries; v1 is
  session-scoped per AgDR-0050 Axis 5 (mixed remote + local on one
  session deferred to v2)
- Idempotent — second invocation produces same state, no compounded
  writes; env files are filter-then-emit, not blind-append
- One-line banner only when applied > 0; silent on no-op so the
  ≤ 600-char SessionStart budget (Wave 1 invariant) is preserved
- Sources libs from HOOK_DIR first (worktree-local) then walk-up ROOT
  to handle mid-upgrade forks where the parent fork's lib doesn't yet
  carry portfolio_agent_routing

Refs #351

* feat(#351): block-agent-routing-drift.sh pre-commit + pre-push guards

- Pre-commit + pre-push hook refuses to let routing-induced rewrites of
  .claude/agents/*.md escape to a public-class remote (the sibling
  enforcement to apply-agent-routing.sh — together they implement
  AgDR-0050 § Axis 4's "rewrite + drift guard" pattern)
- Detects drift by comparing each staged/to-be-pushed agent file's
  model: line against the framework default. Resolution order:
  framework-defaults.json snapshot → dev:.claude/agents/<name>.md →
  upstream/main → HEAD; silent allow when no baseline resolves (avoids
  false positives on brand-new agent files)
- Escape hatch: agent files carrying `# routing-config:override <reason>`
  in frontmatter or body are accepted — covers the rare framework-level
  intentional change (e.g. switching QA default haiku → sonnet
  organisation-wide). Comment is deliberately visible so the change
  ships with PR review attention
- Detects both shapes: `git commit -m` AND `git push`. Push-time check
  diffs the upstream tracking ref → origin/<branch> → dev → HEAD~5
  fallback ladder, so the guard works on brand-new branches without an
  established upstream
- Blocking message names the specific file(s) + current model + expected
  default + the two unblock paths (revert OR escape-hatch comment) per
  the framework's standard self-correction shape

Refs #351

* test(#351): smoke test for sync hook + drift guard (7 cases)

- 7-case smoke test covers the apply-agent-routing.sh + block-agent-
  routing-drift.sh contracts: empty config no-op, single override
  rewrites + snapshot, orphan entry silently skipped, idempotency, drift
  guard fires on stage-with-drift, drift guard accepts with escape
  hatch, drift guard accepts on no-drift (committed file = framework
  default)
- Pattern mirrors test_portfolio_paths.sh / test_split_portfolio_v2_
  migration.sh — each case builds an isolated sandbox apexyard fork
  under $TMPDIR with real `git init` so drift baseline lookups via
  `git show dev:...` actually run; tests source the hooks from the
  sandbox so version-skew between fork and worktree can't false-pass
- Wave 1 invariant 4 (SessionStart banner ≤ 600 chars) extended to
  include apply-agent-routing.sh in its hook iteration list — the new
  hook is silent on the no-routing-file happy path so the budget is
  preserved (153 chars total, well under the cap)

Refs #351

* chore(#351): wire drift guards into settings.json + flip docs/multi-project.md to live

- .claude/settings.json: add PreToolUse entries for block-agent-routing-drift.sh on
  Bash(git commit *) AND Bash(git push *) so the guard fires on every routing-frontmatter
  mutation BEFORE it can leave local. Pairs with the apply-agent-routing.sh SessionStart
  entry from commit f098d47. Two entries (commit + push) instead of one because the push
  shape can carry a forced commit that the commit-time gate already permitted.
- docs/multi-project.md "Centralised agent routing" section: drop the "Wave 1 PR 1 (this
  PR) — inert until PR 2 lands" status block; replace with "How the overrides get applied"
  describing the SessionStart sync + the two drift guards in the live tense. The "What
  ships next" list narrows from three items to two (PR 3 + PR 4) since PR 2 is now in.

Per AgDR-0050 Axis 4. Closes the v1 acceptance criteria for #351 PR 2:
  - SessionStart sync hook: f098d47
  - Pre-commit + pre-push drift guards: 53f49d4
  - Smoke test (7 cases, all PASS): 2f2a1f3
  - Settings wire-up + docs flip: this commit

Refs #351

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(#351): refresh site-counts copy — hooks 29 → 31 (apply-agent-routing + block-agent-routing-drift)

PR #357 adds two new hooks:
  - .claude/hooks/apply-agent-routing.sh (SessionStart)
  - .claude/hooks/block-agent-routing-drift.sh (PreToolUse, x2 entries)

Bumps the framework hook count in marketing copy (site/index.html, site/index.md.gen,
site/architecture.html, site/architecture.md.gen, site/llms.txt, site/llms-full.txt)
from 29 to 31. test_site_counts.sh now green.

Refs #351

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(#351): close shell-hooks variant + stale layer-claim drift gaps (Rex follow-up)

Rex caught two regression gaps Rex's broader audit found on the prior HEAD:

1. **`shell hooks` variant** — test_site_counts.sh's regex covered
   `hooks`, `shell scripts?`, `shell gates?`, `mechanical gates?` but
   not `shell hooks?`. `site/llms.txt:39` and `site/skill.md:35` were
   carrying `29 shell hooks` claims that survived the prior 29→31 sweep
   because they sat under that uncovered noun-pattern. Adds a
   `check_count "shell +hooks?"` line to the test so future bumps catch
   the variant too.

2. **Multi-line layer claims in `site/llms-full.txt:131-133`** — three
   stale layer-component counts (52 skills, 5 sub-agents, 24 mechanical
   enforcement scripts) survived multiple count refreshes because the
   regex assumes `<digits> <noun>` on the same line. The wrap pushed the
   digit to the previous line. Refreshed to actuals (53 / 12 / 31). Not
   a smoke-test fix — the regex would need cross-line lookback that
   isn't worth the complexity for three references; flagged for manual
   audit during count refreshes via the PR-author checklist.

3. **`site/llms-full.txt:92`** — long-stale `24 shell hooks` (predates
   this PR; only surfaced because of the new `shell hooks?` test pattern).
   Refreshed to 31.

Refs #351
Refs #357 (review)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…sh-gate scope + multi-line drift (#364)

* chore(#358): drop advertised-but-not-wired allowed_tools_override field

PR #357 review caught that the agent-routing v1 schema advertised
`allowed_tools_override` in three places — apply-agent-routing.sh's
parser doc comment, agent-routing.yaml.example's schema preamble +
Example F worked-example, and docs/multi-project.md's adopter schema
table — but parse_routing() never emits the field, so adopters who
set it get a silent no-op.

Decision (recorded per #358 AC): DROP the field for v1, do NOT wire
the parser branch. Rationale:

- The full implementation needs parser emission (3 parsers) + a
  consumer-side `tools:` / `allowed-tools:` line rewrite + drift-guard
  awareness (tools-line differs from dev would need its own escape
  hatch). 50-100 line impl for a feature the docs explicitly mark as
  "advanced — use sparingly."
- Adopters who actually need a per-fork tool-list override can edit
  the agent file directly with a `# routing-config:override <reason>`
  comment in YAML frontmatter — the same escape-hatch pattern that
  already handles model: overrides. Documented in the now-deprecation
  prose.
- No migration tail: adopters who'd set `allowed_tools_override` were
  already getting a silent no-op; this PR makes that explicit in the
  schema docs.

Files changed:

- agent-routing.yaml.example
  - Schema preamble: replace the field's doc paragraph with a
    deprecation note pointing at the agent-file + escape-hatch path
  - Example F (the only worked example for the field): removed

- .claude/hooks/apply-agent-routing.sh:115
  - Parser doc comment: removed from the key-set list, added a one-line
    deprecation note pointing readers at the per-agent frontmatter path

- docs/multi-project.md:549
  - Schema table: removed the `allowed_tools_override` row
  - New post-table paragraph documenting the deprecation + the
    operator-facing escape-hatch alternative

Closes #358

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(#359): reconcile AgDR-0050 § Axis 4 push-gate scope with implementation

PR #357 review flagged a doc/impl mismatch: AgDR-0050 § Axis 4 said the
pre-push guard "sweeps before any push to a public-class remote," but
block-agent-routing-drift.sh fires on ANY push regardless of remote
class. Two possible fixes per #359: tighten the hook to check remote
class, OR update the AgDR to match the broader-scope impl.

Decision: UPDATE the AgDR (option 2, recommended in the ticket).
Rationale:

- The broader scope is actually the right design. Even a push to a
  private tracking branch can become a leak vector later if the
  operator changes the remote. Adopters staging a deliberate
  framework-default change should label it with the
  # routing-config:override escape hatch before pushing anywhere —
  not just before pushing to upstream.
- Tightening the hook to inspect @{push} remote class would add code
  and a new failure mode (silent-pass on remote-resolution failure)
  without removing a real failure surface.

Files changed:

- docs/agdr/AgDR-0050-agent-runtime-overhaul.md § Axis 4
  - Prose changed: "sweeps before any push to a public-class remote"
    → "sweeps before ANY push (not just to public-class remotes)"
  - New blockquote note explaining the resolution + linking to #359

Closes #359

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(#342): add multi-line lookback pass + self-test to test_site_counts.sh

#342 § 2(b) flagged that test_site_counts.sh's per-line grep can't
catch claims where the digit and noun straddle a line break (the
shape that bit `site/llms-full.txt:131-133` before #360 cleaned it up
by hand). This commit adds the missing pass per #342's prescription.

Implementation:

- New check_multiline_count() helper. Flattens consecutive whitespace
  (including newlines) via `tr '\n' ' ' | tr -s '[:space:]' ' '`,
  re-scans for `<digits> +<noun>`, dedupes against the per-line pass's
  hits (so a same-line claim already reported by check_count doesn't
  get double-counted), reports drift as `file:multiline` (no line
  number — the digit and noun aren't on the same line).
- Second for-loop calls the new helper for the same noun-pattern list
  as the per-line check_count loop.
- Self-test fixture at the end: synthesises a temp file with the
  exact `52\n   slash commands` shape #342 § 2(b) describes, runs
  check_multiline_count against it inside `$(...)` (subshell-isolated
  so its DRIFT++ stays scoped), asserts the expected `DRIFT:
  file:multiline — claims 52 slash commands` output line. If absent,
  the detector is broken and the suite fails.

Net coverage: the per-line + multi-line passes now together cover
both same-line and cross-line drift, closing #342's § 2(b) gap.
§ 2(a)'s remaining synonym patterns (`enforcement scripts?` and
`mechanical (enforcement )?(scripts?|hooks?)`) are NOT addressed here —
they're additional noun-pattern entries, not a structural fix.
Closing the structural gap is the higher-value half; remaining noun
patterns can be added incrementally as future drift surfaces them.

Files changed:

- .claude/hooks/tests/test_site_counts.sh:
  - new check_multiline_count() function (~30 lines)
  - new for-loop applying it to the same 9 noun patterns as
    check_count
  - new self-test at end of file (~15 lines) that proves the detector
    fires on a known-bad cross-line fixture

Test passes locally against current site/ files (which were swept
clean post-#360). Sibling tests (test_agent_routing_sync_and_drift.sh
8/8, test_agent_wrap_shape.sh 13+5+19/37) unchanged + still pass.

Closes #342 § 2(b). § 2(a) noun-pattern additions and § 1 one-time
hygiene sweep are intentional carry-overs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>