@event4u/agent-config 3.2.0 → 3.3.0

package/docs/decisions/ADR-028-root-layout.md

@@ -0,0 +1,147 @@
+---
+adr: 028
+status: accepted
+date: 2026-05-25
+decision: root-layout
+supersedes: —
+superseded_by: —
+phase: v3.x · root-layout-cleanup Phase 1
+type: structural
+review_date: 2027-05-25
+---
+
+# ADR-028 — Root layout — targeted prune now, multi-workspace deferred behind four audits
+
+## Status
+
+**Accepted** · 2026-05-25. Encodes the AI Council verdict from
+[`root-cleanup-organizing-principle-2026-05-25.synthesis.md`](../../agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md)
+and opens
+[`road-to-root-layout-cleanup.md`](../../agents/roadmaps/archive/road-to-root-layout-cleanup.md) (archived; complete).
+Time-boxed: review on **2027-05-25** or earlier if any trigger below fires.
+
+## Context
+
+A request to move "everything not needed at root into `./src/`" failed
+the reality check on three counts:
+
+1. **`./src/` is occupied** — the TypeScript application (CLI · Server · UI · shared) per
+   [`ADR-012`](ADR-012-typescript-cli-shell.md) / [`ADR-016`](ADR-016-installer-architecture.md).
+   Moving general tooling into `./src/` collides with the app boundary.
+2. **`router.json` is not at root** — lives under `./dist/`, governed by
+   [`ADR-019`](ADR-019-router-json-dist-location.md). Out of scope.
+3. **`setup.sh` is the curl entry point** — referenced by external installers
+   (`bash <(curl …setup.sh)`). Discovery surface, immovable.
+
+A council session (2 members, $0.13 actual) reframed the problem:
+
+> "Root noise" is not a *discoverability* problem (GitHub paginates
+> anyway, npm consumers never see it). It is a *maintainability*
+> problem — "where do new internal tools belong?"
+
+With that reframe, the cheap-and-safe move (Option 1 — targeted prune)
+becomes obvious, and the deep restructure (multi-workspace) drops to a
+conditional follow-up gated by evidence the package does not yet have.
+
+### Consumer-contract surface check (Phase 1 scope)
+
+Re-audit of `bench/`, `evals/`, `workers/`, `user-types/` against the
+installer / projector / CI:
+
+| Dir | `scripts/install.py` | `scripts/compress.py` projection | `.github/workflows/*` | Verdict |
+|---|---|---|---|---|
+| `bench/` | — | — | `bench-drift.yml` (path filter) | **movable** |
+| `evals/` | — | — | — | **movable** |
+| `workers/` | — | — | `deploy-mcp-worker.yml` (working-dir, 6+ refs) | **movable** (CI updates only) |
+| `user-types/` | `USER_TYPES_DIR = "user-types"` (line 52) | `AUGMENT_SYMLINK_DIRS` includes `"user-types"` | — | **immovable — public contract** |
+
+`user-types/` is dropped from Phase 1 — installer + projector reference
+it as a stable root path. Surfaced during execution, not in the
+council's original scope (the council recommended all four; the audit
+narrowed it).
+
+## Decision
+
+**Two-phase strategy.** Phase 1 ships now; Phases 2–3 are conditional.
+
+### Phase 1 — Targeted Prune (immediate, ≤ 1 day, no version bump)
+
+Move into a new `./internal/` umbrella:
+
+- `bench/` → `internal/bench/`
+- `evals/` → `internal/evals/`
+- `workers/` → `internal/workers/`
+
+Update:
+
+- `.github/workflows/bench-drift.yml` — path filter.
+- `.github/workflows/deploy-mcp-worker.yml` — `working-directory` + `cache-dependency-path`.
+- `taskfiles/engine.yml`, `taskfiles/mcp.yml` — `dir:` references.
+- `AGENTS.md` — placement rule pointer.
+
+Outcome: 3 fewer root entries; zero consumer risk; precedent for
+"maintainer-internal → `./internal/`".
+
+### Phase 2 — Pre-audits (gates Phase 3, no time-box)
+
+Four audits must complete and pass before Phase 3 opens:
+
+1. **Consumer-contract audit** — GitHub code search +
+   `node_modules/@event4u/agent-config/` path probing for
+   `scripts/`, `templates/`, `config/`, `schemas/` references.
+2. **Symlink-mobility test** — verify Cursor / Claude / Windsurf
+   honor symlinked projections (`.cursor/` → `./projections/.cursor/`).
+3. **Hash-sequencing audit** — confirm `.compression-hashes.json`
+   uses paths that survive `.agent-src/` relocation (or document the
+   regeneration migration).
+4. **CI-path audit** — every hardcoded path in
+   `.github/workflows/*.yml` and `taskfiles/*.yml`.
+
+Each audit produces a verdict file under
+`agents/evidence/audits/2026-XX-root-layout-phaseN/`.
+
+### Phase 3 — Conditional multi-workspace (deferred, gated)
+
+Only if **all four audits pass**: restructure to npm-workspaces with
+`tooling/` (Python maintainer scripts), `runtime/` (TS app), and
+optionally `projections/` (host-agent configs). If any audit fails,
+Phase 3 closes as "not feasible" and a successor ADR documents the
+blocker.
+
+## Consequences
+
+- New top-level `./internal/` directory becomes the home for
+  maintainer-only tooling. `AGENTS.md` documents this with one line.
+- `.gitignore` and `eslint`/`pyproject` ignore rules updated as
+  needed.
+- The four Phase 2 audits are pre-requirements, not work. They are
+  *not* sprint tasks — they run on demand when someone wants to
+  re-open multi-workspace.
+- Review on **2027-05-25** or earlier if any trigger fires:
+  1. A new maintainer-only dir is added at root (signal: `./internal/`
+     convention is breaking down).
+  2. Phase 2 audits all return clean (signal: Phase 3 is ready).
+  3. A consumer reports breakage from a Phase 1 path change (signal:
+     audit missed a contract).
+  4. Council session re-opens the question with new evidence.
+
+## Alternatives considered
+
+| Option | Why rejected |
+|---|---|
+| Move everything into `./src/` (original request) | `./src/` is the TS app per ADR-012/016. Collision. |
+| Option 2 — `./tooling/` umbrella with `templates/` / `config/` / `schemas/` | Council: cost underestimated (duplicate-then-deprecate + 2-month window + major bump); installer paths in those dirs are unaudited. |
+| Option 3 — full category-coded migration | Council hard-reject: projection mobility unproven; compression-hash sequencing risk; unshippable without symlink test. |
+| Option 4 — `MAP.md` documentation | Council: adds 51st entry; documentation-as-apology; AGENTS.md already serves this role. |
+| Skip Phase 1, jump to multi-workspace prototype | Loses the cheap visible win; Phase 2 audits unfunded; risks scope creep into Phase 3. |
+
+## References
+
+- [`agents/runtime/council/questions/root-cleanup-organizing-principle-2026-05-25.md`](../../agents/runtime/council/questions/root-cleanup-organizing-principle-2026-05-25.md) — council brief.
+- [`agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md`](../../agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md) — full synthesis.
+- [`agents/roadmaps/archive/road-to-root-layout-cleanup.md`](../../agents/roadmaps/archive/road-to-root-layout-cleanup.md) — execution roadmap (archived; Phase 1 ✅, Phase 2 ✅, Phase 3 closed).
+- [`agents/evidence/audits/2026-05-root-layout-phase2/`](../../agents/evidence/audits/2026-05-root-layout-phase2/) — Phase 2 audit verdict bundle.
+- [`ADR-029`](ADR-029-multi-workspace-deferred.md) — Phase 3 close-out (multi-workspace deferred indefinitely).
+- [`ADR-012`](ADR-012-typescript-cli-shell.md), [`ADR-016`](ADR-016-installer-architecture.md) — `./src/` is the TS app.
+- [`ADR-019`](ADR-019-router-json-dist-location.md) — `router.json` lives in `./dist/`.
+- `scripts/install.py:52` (`USER_TYPES_DIR`), `scripts/compress.py:1106` (`AUGMENT_SYMLINK_DIRS`) — evidence pinning `user-types/` to root.

package/docs/decisions/ADR-029-multi-workspace-deferred.md

@@ -0,0 +1,122 @@
+---
+adr: 029
+status: accepted
+date: 2026-05-25
+decision: multi-workspace-deferred
+supersedes: —
+superseded_by: —
+phase: v3.x · root-layout-cleanup Phase 3 close-out
+type: structural
+review_date: 2027-05-25
+---
+
+# ADR-029 — Multi-workspace restructure deferred; Phase 3 closed pending L0 symlink-mobility evidence
+
+## Status
+
+**Accepted** · 2026-05-25. Successor to
+[`ADR-028`](ADR-028-root-layout.md) Phase 3. Closes the multi-workspace
+restructure (Option 5 from the original council session) as **not
+feasible today**, with a re-open path documented below. Time-boxed:
+review on **2027-05-25** or earlier if any re-open trigger fires.
+
+## Context
+
+[`ADR-028`](ADR-028-root-layout.md) defined a three-phase strategy:
+
+1. **Phase 1** — move `bench/`, `evals/`, `workers/` to `internal/`. **Shipped.**
+2. **Phase 2** — run four pre-audits that gate Phase 3.
+3. **Phase 3** — conditional multi-workspace restructure
+   (`tooling/` · `runtime/` · `projections/`), only if all four
+   Phase 2 audits return clean.
+
+Phase 2 ran in the same PR as Phase 1 (under maintainer mandate).
+Verdict bundle:
+[`agents/evidence/audits/2026-05-root-layout-phase2/`](../../agents/evidence/audits/2026-05-root-layout-phase2/).
+
+| # | Audit | Verdict |
+|---|---|---|
+| 1 | Consumer-contract | ✅ Pass — published surface enumerated |
+| 2 | Symlink-mobility | ⚠️ Partial — subdirectory symlinks proven, top-level untested |
+| 3 | Hash-sequencing | ✅ Pass — source-relative keys, idempotent regeneration |
+| 4 | CI-path inventory | ✅ Pass — ~27 edit points enumerated |
+
+Audit 2 is the blocker. The multi-workspace option requires
+**L0 symlinks** (tool root directory itself becomes a symlink, e.g.
+`.cursor/ → projections/.cursor/`). The package today only proves
+**L1 symlinks** (subdirectory level, e.g. `.augment/skills/ →
+../.agent-src/skills/`). L0 has never been tested against current
+Cursor, Claude Code, or Windsurf builds — and one of those three
+(Augment Code) is already known to refuse symlinked rule files at L1,
+which is the precedent that motivates the audit in the first place.
+
+Without L0 evidence, executing Phase 3 would either ship a broken
+projection for at least one host agent or force a fallback to
+per-directory copies that defeat the "single source of truth" win the
+multi-workspace shape is meant to deliver.
+
+## Decision
+
+**Defer Phase 3 indefinitely.** Close the Phase 3 roadmap step as "not
+feasible today". Keep the audit bundle as the canonical evidence base
+so that a future maintainer can re-open the question without redoing
+the work.
+
+The four root-layout claims survive Phase 1 unchanged:
+
+- `bench/`, `evals/`, `workers/` are gone from root (under `internal/`).
+- `user-types/` stays at root (immovable per Audit 1 + ADR-028).
+- Top-level tool roots (`.augment/`, `.cursor/`, `.claude/`, `.clinerules/`)
+  stay as real directories with L1 symlinks pointing at `.agent-src/`.
+- The "maintainer-internal → `./internal/`" precedent is the new
+  placement rule for new internal dirs (already in `AGENTS.md`).
+
+## Re-open conditions
+
+Phase 3 becomes eligible when **all** of these hold:
+
+1. A maintainer (or community contributor) runs the L0 symlink test
+   documented in
+   [`02-symlink-mobility.md`](../../agents/evidence/audits/2026-05-root-layout-phase2/02-symlink-mobility.md)
+   against current Cursor + Claude Code + Windsurf, captures the
+   result, and amends Audit 2 to ✅ or ❌.
+2. If Audit 2 lands ✅: the ~27 CI-path edit points from Audit 4 are
+   accepted as in-scope for the migration window; no new hardcoded
+   paths added in the interim invalidate the inventory.
+3. A council session synthesizes the updated verdict bundle and
+   produces a fresh recommendation (multi-workspace vs. stay-as-is).
+4. The maintainer accepts the deprecation cycle cost (installer
+   version bump + dual-write window for the projection contract).
+
+## Consequences
+
+- The root layout stabilizes at the Phase 1 shape for ≥ 1 year (the
+  `2027-05-25` review date).
+- New maintainer-internal directories go under `internal/`. New
+  tooling that needs to ship to consumers goes under `scripts/`,
+  `config/`, or a new top-level entry that earns its own ADR.
+- The `projections/` umbrella idea is **not dead** — it is gated on
+  fresh L0 evidence, not on a new design decision.
+- The four audit files are reusable: Audit 1 (consumer surface),
+  Audit 3 (hash portability), and Audit 4 (CI path inventory) remain
+  valid until a structural change invalidates them; only Audit 2
+  needs runtime re-verification.
+
+## Alternatives considered
+
+| Option | Why rejected |
+|---|---|
+| Execute Phase 3 anyway with L0 untested | Ships projection breakage to one of three host agents in the worst case; the win (single source of truth) collapses if any agent forces a fallback to copies. |
+| Run the L0 test in CI | The L0 test requires the host agent's runtime (Cursor / Claude Code IDE plugins); CI cannot exercise it. |
+| Defer **all** of Phase 3 to a separate roadmap | Phase 2 already produced the audit bundle; closing Phase 3 with an ADR captures the verdict without leaving a stale roadmap open. |
+| Re-shape Phase 3 as L1-only | The council's recommendation specifically called out the `projections/` umbrella, which requires L0. Re-shaping to L1-only is a different decision the council did not weigh; would need a fresh council session. |
+
+## References
+
+- [`ADR-028`](ADR-028-root-layout.md) — parent decision.
+- [`agents/evidence/audits/2026-05-root-layout-phase2/`](../../agents/evidence/audits/2026-05-root-layout-phase2/) —
+  full audit bundle (4 verdict files + README).
+- [`agents/roadmaps/archive/road-to-root-layout-cleanup.md`](../../agents/roadmaps/archive/road-to-root-layout-cleanup.md) —
+  execution roadmap, archived (Phase 1 ✅, Phase 2 ✅, Phase 3 closed via this ADR).
+- [`agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md`](../../agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md) —
+  original council synthesis that proposed the multi-workspace shape.

package/docs/decisions/INDEX.md

@@ -25,6 +25,14 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-019](ADR-019-router-json-dist-location.md) | Router Json Dist Location | accepted | 2026-05-23 | — |
 | [ADR-020](ADR-020-global-only-consumer-scope.md) | Global Only Consumer Scope | accepted | 2026-05-23 | — |
 | [ADR-021](ADR-021-deployment-shape.md) | Deployment Shape | accepted | 2026-05-24 | — |
+| [ADR-022](ADR-022-daily-workspace-decomposition.md) | Daily Workspace Decomposition | accepted | 2026-05-24 | — |
+| [ADR-023](ADR-023-host-agent-protocol.md) | Host Agent Protocol | accepted | 2026-05-24 | — |
+| [ADR-024](ADR-024-workspace-v0-feature-floor.md) | Workspace V0 Feature Floor | accepted | 2026-05-24 | — |
+| [ADR-025](ADR-025-workspace-chrome.md) | Workspace Chrome | accepted | 2026-05-24 | — |
+| [ADR-026](ADR-026-explain-mode-translation.md) | Explain Mode Translation | accepted | 2026-05-24 | — |
+| [ADR-027](ADR-027-changelog-machine-vs-manual.md) | Changelog Machine Vs Manual | accepted | 2026-05-25 | — |
+| [ADR-028](ADR-028-root-layout.md) | Root Layout | accepted | 2026-05-25 | — |
+| [ADR-029](ADR-029-multi-workspace-deferred.md) | Multi Workspace Deferred | accepted | 2026-05-25 | — |
 
 ## Unnumbered (legacy)
 

package/docs/mcp-server.md

@@ -13,7 +13,7 @@ coexist:
   over JSON-RPC. Used by clients that speak MCP natively. Default for personal
   installs.
 - **Remote MCP** *(experimental, opt-in)* — a Cloudflare-hosted TypeScript
-  Worker (`workers/mcp/`) serves the same wire surface over HTTP/SSE for
+  Worker (`internal/workers/mcp/`) serves the same wire surface over HTTP/SSE for
   hosted-agent platforms. URL shapes pinned in
   [`docs/setup/mcp-cloud-endpoints.md`](setup/mcp-cloud-endpoints.md);
   safety contract in

package/docs/parity/bench-ruflo.json

@@ -11,11 +11,11 @@
     "type": "claimed_upstream_not_verified_in_repo"
   },
   "measurement_protocol": {
-    "corpus": "bench/corpus/* (25-prompt corpus owned by step-4-measurement-and-benchmark.md)",
+    "corpus": "internal/bench/corpus/* (25-prompt corpus owned by step-4-measurement-and-benchmark.md)",
     "tracker": "scripts/cost/track.mjs",
-    "pricing": "bench/pricing.yaml",
+    "pricing": "internal/bench/pricing.yaml",
     "session_source": "~/.claude/projects/*/sessions/*.jsonl (Claude Code-native, no manual tracking)",
-    "tokens_to_dollars": "track.mjs multiplies input/output/cache-read/cache-write tokens by per-1M pricing from bench/pricing.yaml, separated by model id",
+    "tokens_to_dollars": "track.mjs multiplies input/output/cache-read/cache-write tokens by per-1M pricing from internal/bench/pricing.yaml, separated by model id",
     "headline_output": "average dollar cost per 25-prompt run, with min / max / p50 / p90 across N reports"
   },
   "current_window": {

package/docs/parity/ruflo.md

@@ -23,7 +23,7 @@ soak in [`bench.json`](bench.json) flips from `warmup` to `baseline_ready`
 
 | # | Ruflo pattern | Verdict | Evidence |
 |---|---|---|---|
-| 1 | **Cost-tracker plugin** — real model pricing, per-1M, separated input/output/cache | `[x] covered by` | [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs) + [`bench/pricing.yaml`](../../bench/pricing.yaml) (Haiku/Sonnet/Opus per-1M, input/output/cache-read/cache-write split). Step-11 Phase 1. |
+| 1 | **Cost-tracker plugin** — real model pricing, per-1M, separated input/output/cache | `[x] covered by` | [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs) + [`internal/bench/pricing.yaml`](../../bench/pricing.yaml) (Haiku/Sonnet/Opus per-1M, input/output/cache-read/cache-write split). Step-11 Phase 1. |
 | 2 | **Auto-capture from session jsonl** — reads Claude Code log, no manual tracking | `[x] covered by` | [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs) reads `~/.claude/projects/*/sessions/*.jsonl` automatically. Step-11 Phase 1 Step 1. |
 | 3 | **50/75/90/100 % budget ladder with hard stop** | `[x] covered by` | [`scripts/cost/budget.mjs`](../../scripts/cost/budget.mjs) — exit codes 0/1/2/3 per tier; opt-in fail-closed via `cost.enforcement` setting. Fixtures: `tests/fixtures/cost/budget/{under-50,at-100,over-100}/`. Step-11 Phase 2. |
 | 4 | **Measured-vs-claimed disclaimer** — every percentage tagged "claimed upstream" | `[x] covered by` | One-line `**Measured-vs-claimed disclaimer:**` header block on all 9 active roadmaps in `agents/roadmaps/`. Verified 2026-05-16. Step-11 Phase 5 Step 4. |

package/docs/setup/mcp-client-config.md

@@ -5,7 +5,7 @@ Worker. Read-only, identity-stable per release. Optional Bearer-token
 auth — see [§ Bearer auth](#bearer-auth) below.
 
 > **No public endpoint.** This package ships the Worker source under
-> `workers/mcp/`, but does **not** operate a shared hosted MCP server.
+> `internal/workers/mcp/`, but does **not** operate a shared hosted MCP server.
 > Deploy your own per [`mcp-cloud-setup.md`](mcp-cloud-setup.md) — your
 > URL will be `https://agent-config-mcp.<your-account>.workers.dev`
 > (or a custom domain you wire up in Step 7).

package/docs/setup/mcp-cloud-endpoints.md

@@ -69,7 +69,7 @@ curl -s -X POST https://mcp.<your-domain>/ \
 ```
 
 After DNS is live, uncomment the `routes` block in
-`workers/mcp/wrangler.toml` and redeploy via `wrangler deploy` (or let
+`internal/workers/mcp/wrangler.toml` and redeploy via `wrangler deploy` (or let
 the GitHub Action pick it up on the next release).
 
 The fallback `*.workers.dev` URL stays live for free; the custom

package/docs/setup/mcp-cloud-setup.md

@@ -82,7 +82,7 @@ Dashboard → **My Profile → API Tokens → Create Token → Custom token**:
 | Account · Workers R2 Storage | your account | Edit |
 | User · User Details | — | Read |
 
-If you uncomment the `routes` block in `workers/mcp/wrangler.toml`
+If you uncomment the `routes` block in `internal/workers/mcp/wrangler.toml`
 (custom domain cutover, Phase 5.2), add **Zone · DNS · Edit** on the
 relevant zone.
 
@@ -180,4 +180,4 @@ setup. Until cutover, the Worker serves on the free
 - [`docs/contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md) — A0-cloud contract
 - [`docs/setup/mcp-r2-bootstrap.md`](mcp-r2-bootstrap.md) — R2 layout & break-glass
 - [`docs/setup/mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md) — URL shapes & DNS
-- [`workers/mcp/README.md`](../../workers/mcp/README.md) — Worker source overview
+- [`internal/workers/mcp/README.md`](../../internal/workers/mcp/README.md) — Worker source overview

package/docs/setup/mcp-r2-bootstrap.md

@@ -44,7 +44,7 @@ npx wrangler r2 bucket create agent-config-mcp
 npx wrangler r2 bucket list | grep agent-config-mcp
 ```
 
-The Worker binding is declared in `workers/mcp/wrangler.toml` under
+The Worker binding is declared in `internal/workers/mcp/wrangler.toml` under
 `[[r2_buckets]]`. The pipeline reads/writes via the wrangler CLI in CI,
 not via the Worker — A0-cloud invariant 2 forbids the Worker from
 issuing R2 writes.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "3.2.0",
+    "version": "3.3.0",
     "description": "Universal AI Agent OS \u2014 audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/scripts/_lib/bench_caveman.py

@@ -1,6 +1,6 @@
 # Caveman compression bench — step-16 Phase 1 Step 4.
 #
-# Three-arm live bench against bench/corpora/caveman/prompts.yaml:
+# Three-arm live bench against internal/bench/corpora/caveman/prompts.yaml:
 #   compressed     — system prompt embeds caveman-speak rule (aggressive).
 #   terse_control  — system prompt = "Answer concisely. …" (carve-out-free baseline).
 #   uncompressed   — generic helpful-assistant system prompt.
@@ -131,7 +131,7 @@ class PromptResult:
 # ── corpus + runner ────────────────────────────────────────────────────
 
 def load_corpus(corpus_path: Path) -> list[dict[str, Any]]:
-    """Read bench/corpora/caveman/prompts.yaml → list of prompt dicts."""
+    """Read internal/bench/corpora/caveman/prompts.yaml → list of prompt dicts."""
     data = yaml.safe_load(corpus_path.read_text(encoding="utf-8")) or {}
     prompts = data.get("prompts") or []
     if not prompts:

package/scripts/_lib/bench_caveman_report.py

@@ -144,7 +144,7 @@ def render_caveman_markdown(report: dict[str, Any]) -> str:
         "## Notes",
         "",
         f"- corpus: `{report['corpus']['path']}`",
-        f"- pricing: `bench/pricing.yaml` (sourced {cost.get('pricing_sourced_on') or '—'})",
+        f"- pricing: `internal/bench/pricing.yaml` (sourced {cost.get('pricing_sourced_on') or '—'})",
         f"- schema: `caveman-v1` (see `docs/contracts/benchmark-report-schema.md`)",
         f"- bench_run version: `{report['runner']['bench_run_version']}`",
         "",

package/scripts/_lib/bench_cost.py

@@ -2,7 +2,7 @@
 #
 # Reads Claude Code session jsonl summaries (one summary line per session)
 # from agents/cost-tracking/sessions.jsonl — produced by scripts/cost/track.mjs
-# — and aggregates totals using model rates from bench/pricing.yaml.
+# — and aggregates totals using model rates from internal/bench/pricing.yaml.
 #
 # Returns the dict shape declared in docs/contracts/benchmark-report-schema.md
 # § JSON schema (v1) `cost`. When the source jsonl is missing, returns the
@@ -24,7 +24,7 @@ TIER_KEYS = ("haiku", "sonnet", "opus", UNKNOWN_TIER)
 
 
 def load_pricing(pricing_path: Path) -> tuple[dict[str, dict[str, float]], str | None]:
-    """Return ({tier: rates}, oldest_sourced_on) from bench/pricing.yaml."""
+    """Return ({tier: rates}, oldest_sourced_on) from internal/bench/pricing.yaml."""
     if yaml is None or not pricing_path.is_file():
         return {}, None
     data = yaml.safe_load(pricing_path.read_text(encoding="utf-8")) or {}

package/scripts/_lib/bench_report.py

@@ -2,7 +2,7 @@
 #
 # Serializes the unified report dict to JSON + Markdown per
 # docs/contracts/benchmark-report-schema.md. Filename format:
-# `bench/reports/<UTC ISO-8601 with : -> ->-<corpus_id>.{json,md}`.
+# `internal/bench/reports/<UTC ISO-8601 with : -> ->-<corpus_id>.{json,md}`.
 """Report emitter for the bench runner."""
 from __future__ import annotations
 
@@ -133,7 +133,7 @@ def render_markdown(report: dict[str, Any]) -> str:
     notes = (
         "## Notes\n\n"
         f"- corpus path: `{corpus['path']}` · prompts: **{corpus['prompt_count']}**\n"
-        f"- pricing: `bench/pricing.yaml`\n"
+        f"- pricing: `internal/bench/pricing.yaml`\n"
         f"- baseline collector: `{report['runner']['baseline_collector']}`\n"
     )
     return "\n\n".join([

package/scripts/audit_mcp_tools.py

@@ -105,7 +105,7 @@ def _render(catalog: dict, handlers: dict[str, int], cat_lines: dict[str, int])
     lines.append("## Glossary")
     lines.append("")
     lines.append("- **Side-effect** — `ro` (read-only) · `fs-write` (filesystem write) · `shell` (spawns processes).")
-    lines.append("- **Transports** — `stdio` (`scripts/mcp_server/`) · `worker` (`workers/mcp/`). A tool may live on both.")
+    lines.append("- **Transports** — `stdio` (`scripts/mcp_server/`) · `worker` (`internal/workers/mcp/`). A tool may live on both.")
     lines.append("- **Stub** — catalog-listed for discovery; returns the `not_implemented` envelope from")
     lines.append("  [`mcp-tool-stub-envelope.md`](mcp-tool-stub-envelope.md) until promoted.")
     lines.append("")

package/scripts/bench_baseline_ready.py

@@ -2,7 +2,7 @@
 """Baseline-closure check — step-4 Phase 3 Step 4.
 
 Returns exit 0 iff the 60-day clock has elapsed since
-`bench/baseline-start.txt` AND `bench/reports/` contains at least
+`internal/bench/baseline-start.txt` AND `internal/bench/reports/` contains at least
 `--min-reports` complete runs for the named corpus (default 30).
 
 Read by P2 enforcement roadmaps as their precondition (G1 gate in
@@ -50,8 +50,8 @@ def main(argv: list[str] | None = None) -> int:
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     ap.add_argument("--corpus", default="dev")
-    ap.add_argument("--reports-dir", default="bench/reports")
-    ap.add_argument("--baseline-file", default="bench/baseline-start.txt")
+    ap.add_argument("--reports-dir", default="internal/bench/reports")
+    ap.add_argument("--baseline-file", default="internal/bench/baseline-start.txt")
     ap.add_argument("--min-days", type=int, default=60)
     ap.add_argument("--min-reports", type=int, default=30)
     ap.add_argument("--json", action="store_true")

package/scripts/bench_compress_memory.py

@@ -3,10 +3,10 @@
 
 Runs `compress_memory.py` over a fixed corpus of memory-target files, records
 pre/post char counts, approximates input-token savings (chars / 4 — the
-GPT-4 / Claude rule of thumb), and emits `bench/reports/caveman-v2.{json,md}`.
+GPT-4 / Claude rule of thumb), and emits `internal/bench/reports/caveman-v2.{json,md}`.
 
 Offline (no API calls). Cadence-aligned with `docs/benchmarks.md`. Citation
-in `bench/reports/caveman-v2.md` notes the chars→tokens approximation and
+in `internal/bench/reports/caveman-v2.md` notes the chars→tokens approximation and
 points at upstream tiktoken / claude-tokenizer if a calibrated number is
 later needed.
 """
@@ -23,8 +23,8 @@ from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 COMPRESS_SCRIPT = REPO_ROOT / "scripts" / "compress_memory.py"
-REPORT_JSON = REPO_ROOT / "bench" / "reports" / "caveman-v2.json"
-REPORT_MD = REPO_ROOT / "bench" / "reports" / "caveman-v2.md"
+REPORT_JSON = REPO_ROOT / "internal" / "bench" / "reports" / "caveman-v2.json"
+REPORT_MD = REPO_ROOT / "internal" / "bench" / "reports" / "caveman-v2.md"
 
 CORPUS: list[tuple[str, str]] = [
     ("AGENTS.md", "thin-root-package"),

package/scripts/bench_drift_check.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Drift detector for the bench corpus — step-4 Phase 3 Step 2.
 
-Compares the latest `bench/reports/<stamp>-<corpus>.json` against the
+Compares the latest `internal/bench/reports/<stamp>-<corpus>.json` against the
 previous N reports (default 5) for the same corpus. Drift defined as:
 
     - selection-accuracy: latest is more than `accuracy_drop_pp` below
@@ -99,7 +99,7 @@ def _check(latest: dict[str, Any], baseline: list[dict[str, Any]],
 def main(argv: list[str] | None = None) -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("--corpus", default="dev")
-    ap.add_argument("--reports-dir", default="bench/reports")
+    ap.add_argument("--reports-dir", default="internal/bench/reports")
     ap.add_argument("--window", type=int, default=5, help="rolling window size (default 5)")
     ap.add_argument("--accuracy-drop-pp", type=float, default=5.0)
     ap.add_argument("--cost-increase-pct", type=float, default=20.0)

package/scripts/bench_per_tool.py

@@ -43,7 +43,7 @@ from bench_runner import rank_skills  # type: ignore  # noqa: E402
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 CORPUS_DIR = REPO_ROOT / "tests" / "eval"
-REPORTS_DIR = REPO_ROOT / "bench" / "reports"
+REPORTS_DIR = REPO_ROOT / "internal" / "bench" / "reports"
 
 # tool_id -> (skills_root, kind). kind = "skills" | "rules_only" | "single_file".
 SURFACES: dict[str, tuple[Path, str]] = {
@@ -185,7 +185,7 @@ def main(argv=None) -> int:
     ap.add_argument("--threshold", type=float, default=0.85)
     ap.add_argument("--json", action="store_true")
     ap.add_argument("--write-report", action="store_true",
-                    help="emit bench/reports/<ts>-<corpus>-projection.{json,md}")
+                    help="emit internal/bench/reports/<ts>-<corpus>-projection.{json,md}")
     args = ap.parse_args(argv)
 
     corpus_path = CORPUS_DIR / f"corpus-{args.corpus}.yaml"

package/scripts/bench_run.py

@@ -5,7 +5,7 @@ Wraps the selection-accuracy baseline collector (`scripts/bench_runner.py`),
 captures token / cost data from `agents/cost-tracking/sessions.jsonl` if
 present (per ruflo pattern, external-findings § 2), runs structural
 quality assertions per prompt, and emits a versioned JSON + Markdown
-report under `bench/reports/` per
+report under `internal/bench/reports/` per
 `docs/contracts/benchmark-report-schema.md`.
 
 Usage:
@@ -46,11 +46,11 @@ except ImportError:
     sys.exit(2)
 
 BENCH_RUN_VERSION = "0.2.0"
-PRICING_PATH = REPO_ROOT / "bench" / "pricing.yaml"
+PRICING_PATH = REPO_ROOT / "internal" / "bench" / "pricing.yaml"
 SESSIONS_JSONL = REPO_ROOT / "agents" / "cost-tracking" / "sessions.jsonl"
-REPORTS_DIR = REPO_ROOT / "bench" / "reports"
+REPORTS_DIR = REPO_ROOT / "internal" / "bench" / "reports"
 CORPUS_DIR = REPO_ROOT / "tests" / "eval"
-CAVEMAN_CORPUS = REPO_ROOT / "bench" / "corpora" / "caveman" / "prompts.yaml"
+CAVEMAN_CORPUS = REPO_ROOT / "internal" / "bench" / "corpora" / "caveman" / "prompts.yaml"
 BASELINE_COLLECTOR = REPO_ROOT / "scripts" / "bench_runner.py"
 
 

package/scripts/build_mcp_registry_manifest.py

@@ -4,7 +4,7 @@
 Reads three on-disk sources:
   * `package.json`                          — name, version, description, homepage, repository
   * `.github/topics.yml`                    — topics list (for registries that accept tags)
-  * `workers/mcp/content.json`              — `tool_catalog` (tools_count, install_hint_stdio)
+  * `internal/workers/mcp/content.json`     — `tool_catalog` (tools_count, install_hint_stdio)
   * `dist/discovery/discovery-manifest.json` — artefact_count + scanner_version (HARD prereq per AI-Council R5)
 
 Emits:
@@ -37,7 +37,7 @@ import yaml
 ROOT = Path(__file__).resolve().parents[1]
 PKG_FILE = ROOT / "package.json"
 TOPICS_FILE = ROOT / ".github" / "topics.yml"
-CONTENT_FILE = ROOT / "workers" / "mcp" / "content.json"
+CONTENT_FILE = ROOT / "internal" / "workers" / "mcp" / "content.json"
 DISCOVERY_FILE = ROOT / "dist" / "discovery" / "discovery-manifest.json"
 OUT_DIR = ROOT / "dist" / "mcp"
 OUT_MANIFEST = OUT_DIR / "registry-manifest.json"

package/scripts/mcp_server/__init__.py

@@ -2,7 +2,7 @@
 
 mcp_scope: full — local stdio access can be extended to tool execution
 under the Phase 7 wake-up triggers in `docs/contracts/mcp-cloud-scope.md`.
-The hosted Worker (`workers/mcp/`) is `mcp_scope: lite` and is
+The hosted Worker (`internal/workers/mcp/`) is `mcp_scope: lite` and is
 intentionally narrower.
 
 Exposes a hand-picked subset of `.agent-src/skills/` as MCP `prompts`

package/scripts/mcp_server/catalog.py

@@ -108,7 +108,7 @@ def not_implemented_envelope(
 ) -> dict[str, Any]:
     """Wire-shape error envelope used when a stub is invoked.
 
-    Mirrored verbatim by the Cloud Worker (`workers/mcp/src/stubs.ts`).
+    Mirrored verbatim by the Cloud Worker (`internal/workers/mcp/src/stubs.ts`).
     """
     return {
         "code": NOT_IMPLEMENTED_CODE,

package/scripts/mcp_server/consumer_tool_catalog.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "description": "Source-of-truth catalog of consumer-relevant MCP tools. Read by the stdio server (scripts/mcp_server/) and packed into the Cloud Worker bundle (workers/mcp/). Phase 1 of road-to-mcp-full-coverage: tools without 'implemented' transports return the 'not_implemented' envelope defined in docs/contracts/mcp-tool-stub-envelope.md. The 'implemented_on' field lists transports where the real handler is wired; everything else is a discovery stub. See agents/roadmaps/archive/road-to-mcp-full-coverage.md.",
+  "description": "Source-of-truth catalog of consumer-relevant MCP tools. Read by the stdio server (scripts/mcp_server/) and packed into the Cloud Worker bundle (internal/workers/mcp/). Phase 1 of road-to-mcp-full-coverage: tools without 'implemented' transports return the 'not_implemented' envelope defined in docs/contracts/mcp-tool-stub-envelope.md. The 'implemented_on' field lists transports where the real handler is wired; everything else is a discovery stub. See agents/roadmaps/archive/road-to-mcp-full-coverage.md.",
   "install_hint_stdio": "pip install agent-config[mcp] && ./agent-config mcp:run",
   "tools": [
     {

package/scripts/mcp_server/tools.py

@@ -43,7 +43,7 @@ from .catalog import (
 from .telemetry import Outcome, record_call
 
 # Stable transport tag for the stub envelope. Mirrored verbatim by
-# `workers/mcp/src/stubs.ts` with ``"worker"``.
+# `internal/workers/mcp/src/stubs.ts` with ``"worker"``.
 STDIO_TRANSPORT = "stdio"
 
 # Allowlisted directories (relative to consumer_root) where tool writes