@event4u/agent-config 6.1.0 → 7.0.0

package/docs/decisions/ADR-200-python-to-typescript-migration.md

@@ -0,0 +1,193 @@
+---
+adr: 200
+status: accepted
+date: 2026-06-11
+decision: python-to-typescript-migration
+supersedes: —
+superseded_by: —
+phase: py2ts · migration-infrastructure
+type: structural
+---
+
+# ADR-200 — Full Python → TypeScript migration: execution model, branch strategy, dispatcher, parity gates
+
+> Provisional number 200 (reserved, out-of-band). main ADRs grow sequentially; the migration ADR is renumbered to a high reserved slot to stop recurring collisions on the long-lived `python2ts` branch. Final number is assigned at the `python2ts`→`main` merge.
+
+## Status
+
+**Accepted** · 2026-06-11. Records the locked design of the TypeScript-only
+scripts roadmap (Phase 1, Step 1). Driven by the AI-council convergence of
+2026-06-11 (claude-sonnet-4-5 + gpt-4o, design mode, deep): both members
+converged on migration infrastructure before any porting, the installer as
+consumer trust boundary, pytest→vitest 1:1 ports plus golden replay as the
+parity contract, sequential gated phasing instead of a parallel-agent control
+plane, same-PR deletion of each Python original, and a documented
+intentional-divergence process.
+
+## Context
+
+The package is a hybrid Python + TypeScript system. The Python side spans
+~952 source `.py` files (~204k LOC): `src/scripts/` 419 files (linters/checks
+~17.4k LOC incl. `skill_linter.py` 3.7k, condense/sync pipeline ~3.8k incl.
+the comment-preserving `sync_yaml_rt.py`, ai_council ~17k, hooks ~2.6k,
+memory/telemetry, `install.py` 5.1k, `_lib/` ~6.2k, misc ~44.5k), `tests/`
+413 files (pytest), and `src/agent-src/templates/scripts/` ~100
+consumer-shipped files. The call surface is wide: 60+ `python3` invocations in
+`taskfiles/*.yml`, 40+ in `.github/workflows/*.yml`, 3 in `package.json`,
+15+ doc references in `src/rules` + `src/skills`, and git hooks via
+`hooks/hooks.json`.
+
+The target is a single-language TypeScript codebase: zero tracked `.py` in
+source, no `pyproject.toml`, no `.venv`, no `python3` runtime requirement —
+while every quality gate (linter finding counts, CI green floor, golden
+behavior, consumer-facing CLI contracts) stays provably at or above today's
+level. TS infrastructure already exists (`src/cli/`, `src/server/`,
+`src/shared/`, `src/install/`, strict ES2022 tsconfig, vitest, Node >= 20.11,
+typescript 5.9 + tsx 4.22).
+
+The risk profile is asymmetric: internal lint tooling can tolerate iteration,
+but the installer, git hooks, and consumer-shipped template scripts are trust
+boundaries where a silent behavior change ships to consumers. That asymmetry
+drives every decision below.
+
+## Decision
+
+### 1. Scope — full migration
+
+Migrate all ~952 Python source files to TypeScript. The phased inventory and
+sequencing live in the TypeScript-only scripts roadmap (prerequisites
+section); this ADR locks the architecture, not the schedule. Bench fixture
+clones under `internal/bench/` are test data, not source — out of scope.
+
+### 2. Execution model — sequential gated phasing, subagent fan-out within a phase
+
+- **Across phases: sequential and gated.** A phase starts only when the
+  previous phase's exit criteria are green on the integration branch. No
+  separate control plane — state tracking is the roadmap checkbox layer plus
+  the migration dashboard.
+- **Within a phase: parallel subagent fan-out.** An orchestrator session
+  splits the phase's cluster into dependency-free batches of ~5–15 scripts
+  and dispatches them to parallel porting subagents. Each subagent works in
+  an isolated git worktree on a `feat/py2ts-<phase>-<batch>` branch; each
+  batch lands as one PR.
+- **Verification is independent of porting.** A verification subagent re-runs
+  the parity harness on each batch before the PR is marked ready — the porter
+  never green-lights its own parity claim.
+- **Merge order is foundation-first** within a phase (libs before
+  dependents). Subagents produce ready PRs; they do not merge.
+
+### 3. Branch strategy — `python2ts` integration branch
+
+- A long-lived integration branch **`python2ts`** is cut from `main` in
+  Phase 1 and lives until the migration completes.
+- **Every migration PR targets `python2ts`, never `main`.** A guard check
+  fails any `py2ts`-prefixed PR whose base is not `python2ts`.
+- A **scheduled `main → python2ts` sync** merges mainline changes into the
+  integration branch continuously, so the migration absorbs drift instead of
+  diverging toward a big-bang conflict. `main` stays the consumer-facing
+  trunk and keeps receiving normal work.
+- The **final `python2ts → main` merge is a user-owned delivery decision**
+  outside the roadmap (Hard Floor: production-trunk merge requires explicit
+  per-turn confirmation).
+
+### 4. Dispatcher design — `src/scripts/run.ts`
+
+A dispatch wrapper resolves a script path without extension: prefer
+`<path>.ts` (via tsx in dev, compiled in CI) and fall back to `<path>.py`
+(via `python3`), passing argv, stdin, stdout/stderr, and the exit code
+through unchanged. Consequences:
+
+- **All call sites switch once** (taskfiles, workflows, package.json, hooks,
+  doc references) — before any script is ported.
+- **Per-script migration = add the `.ts` + delete the `.py` in the same
+  PR.** The dispatcher resolves the new `.ts` automatically.
+- **Rollback = `git revert` of the porting PR.** The dispatcher then
+  resolves the restored `.py` again — no call-site churn in either
+  direction.
+
+### 5. Parity strategy — four stacked gates
+
+1. **pytest→vitest 1:1 ports are the behavioral specification.** Mechanical
+   translation only (`parametrize` → `test.each`, `monkeypatch` → `vi.mock`,
+   fixtures → `beforeEach`) — never "redefine test intent".
+2. **Golden replay.** Execute the Python and TS versions on identical
+   fixtures; compare stdout/stderr/exit code/written files byte-exact, with
+   an opt-in JSON/YAML normalization layer.
+3. **Coverage-diff gate.** `vitest --coverage` must be ≥ the `pytest --cov`
+   baseline per ported cluster, on both line and branch coverage.
+4. **Error parity for consumer-facing scripts.** A fixture corpus of failure
+   scenarios (bad input, missing file, invalid flags) comparing error text,
+   output channel, and exit code.
+
+Python style (snake_case CLI flags, exit codes, stdout/stderr split) is part
+of the contract — TS ports keep them identical unless a documented divergence
+says otherwise.
+
+### 6. Intentional-divergence process
+
+Every golden-parity mismatch requires a divergence doc in
+`docs/migration/divergences/` (symptom, root cause, bug-fix-vs-regression
+verdict, evidence, approval) before the porting PR can pass CI. The quality
+floor reads: **quality must not degrade; documented improvements are allowed
+and explicitly approved.** An undocumented difference is a regression by
+definition. See `docs/migration/divergences/README.md` for the process.
+
+### 7. Runtime model
+
+- **Internal tooling runs via tsx** (no precompile; acceptable startup for
+  lint/CI tasks).
+- **Consumer-shipped templates and git-hook entry points ship as compiled
+  esbuild single-file bundles** — consumers need Node only (no tsx, no
+  node_modules resolution inside consumer projects), and hooks keep their
+  cold-start budget and exit-0 guarantee.
+
+## Consequences
+
+- Phase 1 (dispatcher, parity harness, YAML round-trip spike, branch +
+  sync + drift infrastructure, divergence process, phase-gate CI) is a hard
+  blocker — nothing ports before it is green.
+- The same-PR deletion rule prevents a drifting dual-source window per
+  script; the cost is that each porting PR must clear all four parity gates
+  before merge.
+- Later-phase Python scripts must not import half-migrated libs across
+  languages; Python `_lib` files needed by an unported importer stay in
+  place until that importer's own phase deletes them.
+- The `python2ts` branch carries the full migration risk away from `main`;
+  consumers see no change until the user-owned final merge.
+- Business-logic refactors are forbidden while porting (minimal safe diff
+  per script): port first, improve via documented divergence or follow-up.
+
+## Alternatives considered
+
+- **Parallel-agent control plane** (a coordinator service tracking migration
+  state outside the repo) — rejected: the roadmap checkbox layer plus a
+  dashboard script gives the same visibility with zero extra infrastructure,
+  and sequential phase gates remove the coordination problem the control
+  plane would solve.
+- **Migration PRs against `main`** — rejected: every porting PR would put
+  consumer-facing trunk at risk and force the full migration gate set onto
+  unrelated mainline work; the integration branch isolates both directions.
+- **Big-bang cutover** (port everything on a branch, switch call sites at
+  the end) — rejected: the dispatcher makes incremental per-script cutover
+  free, with `git revert` rollback per script instead of an all-or-nothing
+  merge.
+- **Keeping Python originals alongside TS ports** ("soak window") — rejected:
+  a dual-source window invites silent drift; git history is the soak window,
+  and the dispatcher's `.py` fallback makes a revert behave identically.
+- **Rewriting tests idiomatically during the port** — rejected: the pytest
+  suite is the behavioral spec; redefining intent while porting destroys the
+  only oracle the migration has.
+
+## References
+
+- The TypeScript-only scripts roadmap (full phase plan, inventory, exit
+  criteria) — referenced by name; roadmaps are a transient layer and are not
+  linked from stable artifacts.
+- AI-council convergence 2026-06-11 (claude-sonnet-4-5 + gpt-4o, design
+  mode, deep) — inline summary above; council artifacts are local-only.
+- `docs/migration/divergences/README.md` — divergence process.
+- `docs/migration/divergences/_template.md` — divergence doc template.
+- [ADR-012](ADR-012-typescript-cli-shell.md) — TypeScript CLI shell (the
+  existing TS infrastructure this migration extends).
+- [ADR-087](ADR-087-installer-e2e-test-strategy.md) — installer container
+  e2e (the golden corpus base for the dual-mode installer phase).

package/docs/decisions/INDEX.md

@@ -99,6 +99,15 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-093](ADR-093-ai-council-config-user-global.md) | Ai Council Config User Global | accepted | 2026-06-13 | — |
 | [ADR-094](ADR-094-agent-memory-layer-removal.md) | Agent Memory Layer Removal | accepted | 2026-06-14 | — |
 | [ADR-095](ADR-095-workspace-boundary-contract.md) | Workspace Boundary Contract | accepted | 2026-06-14 | — |
+| [ADR-096](ADR-096-analysis-workbench.md) | Analysis Workbench | accepted | 2026-06-15 | — |
+| [ADR-097](ADR-097-mission-recipe-privilege-boundary.md) | Mission Recipe Privilege Boundary | accepted | 2026-06-15 | — |
+| [ADR-098](ADR-098-evidence-first-structure-discovery.md) | Evidence First Structure Discovery | accepted | 2026-06-15 | — |
+| [ADR-099](ADR-099-file-first-pattern-library.md) | File First Pattern Library | accepted | 2026-06-15 | — |
+| [ADR-100](ADR-100-global-knowledge-card-sharing.md) | Global Knowledge Card Sharing | accepted | 2026-06-15 | ADR-098 |
+| [ADR-101](ADR-101-ticket-bundle-emission.md) | Ticket Bundle Emission | proposed | 2026-06-15 | — |
+| [ADR-102](ADR-102-ticket-handoff-paste-and-mcp.md) | Ticket Handoff Paste And Mcp | accepted | 2026-06-16 | — |
+| [ADR-103](ADR-103-global-knowledge-default-off-until-measured.md) | Global Knowledge Default Off Until Measured | accepted | 2026-06-16 | — |
+| [ADR-200](ADR-200-python-to-typescript-migration.md) | Python To Typescript Migration | accepted | 2026-06-11 | — |
 
 ## Unnumbered (legacy)
 

package/docs/distribution/mcp-submission-checklist.md

@@ -11,9 +11,9 @@
    land on a hijacked release.
 2. Re-run the builder so payloads reflect the current package:
    ```bash
-   python3 scripts/build_discovery_manifest.py --write --strict
-   python3 scripts/build_mcp_registry_manifest.py --write --strict
-   python3 scripts/lint_mcp_registry_manifest.py
+   ./scripts-run src/scripts/build_discovery_manifest --write --strict
+   ./scripts-run src/scripts/build_mcp_registry_manifest --write --strict
+   ./scripts-run src/scripts/lint_mcp_registry_manifest
    ```
 3. Confirm `dist/mcp/registry-manifest.json` `package.version`
    matches the latest published npm version (or the version about to

package/docs/featured-commands.md

@@ -12,7 +12,7 @@ A curated subset of the 124 active commands. Full set lives in
 | [`/work`](../dist/agent-src/commands/work.md) | Same end-to-end loop for a free-form prompt — confidence-band gated |
 | [`/fix ci`](../dist/agent-src/commands/fix.md) | Fetch CI failures from GitHub Actions and fix them |
 | [`/review-changes`](../dist/agent-src/commands/review-changes.md) | Self-review local changes before creating a PR (five judges) |
-| [`/create-pr`](../dist/agent-src/commands/create-pr.md) | Create a GitHub PR with Jira-linked description |
+| [`/pr:create`](../dist/agent-src/commands/pr/create.md) | Create a GitHub PR with Jira-linked description |
 
 ## For everyone
 

package/docs/featured-skills.md

@@ -87,7 +87,7 @@ Every entry above MUST resolve in [`dist/discovery/discovery-manifest.json`](../
 ```bash
 task lint-featured-skills
 # or directly:
-python3 scripts/lint_featured_skills.py
+./scripts-run src/scripts/lint_featured_skills
 ```
 
 CI runs this in `taskfiles/ci-fast.yml`. Stale entries (renamed / removed skill or command) fail the build. See [`scripts/lint_featured_skills.py`](../src/scripts/lint_featured_skills.py) for the matcher.

package/docs/getting-started-by-role.md

@@ -4,6 +4,8 @@
 
 `agent-config` ships ~210 skills, ~67 rules, and ~124 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
 
+> **Taglines at a glance →** [`docs/role-experiences.md`](role-experiences.md) — the one-line pitch per role experience, in one table.
+
 > **Quickstart for every role.** Run `npx -y @event4u/agent-config init` — the browser wizard auto-launches and walks you through role, ready-made setup, and identity. Headless install path lives at [`docs/wizard.md`](wizard.md#headless--ci--no-browser). The wizard writes `.agent-settings.yml`, `.augment/`, and `.claude/` atomically; nothing leaves your disk.
 
 > **Eval-gated messaging note.** Until `task bench --corpus non-dev` reports `selection_accuracy >= 0.60` (step-12 Phase 1 exit), this page is documentation, not marketing. The skills listed below are the candidates the corpus tests against; their description quality is what the eval validates.

package/docs/getting-started.md

@@ -129,7 +129,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 83 rules. No configuration needed.
+This is enforced automatically by 88 rules. No configuration needed.
 
 ---
 
@@ -169,7 +169,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history import` | Pull a prior session into the current chat (resume) |
 
-→ [Browse all 147 active commands](../dist/agent-src/commands/)
+→ [Browse all 161 active commands](../dist/agent-src/commands/)
 
 ---
 

package/docs/guidelines/agent-infra/failure-signatures.md

@@ -0,0 +1,35 @@
+# Failure signatures — symptom → likely cause → first check
+
+A file-first lookup the [`systematic-debugging`](../../../src/skills/systematic-debugging/SKILL.md)
+skill reads when a failure shows a recognisable signature. It does **not**
+replace the 6-phase loop — it shortcuts **Phase 2 (Isolate)** by pointing at the
+*first* check for a known shape, so you stop guessing and start with the highest-
+probability cause.
+
+> File-first by design (council 2026-06-15): kept as a reference table the skill
+> reads, **not** hardcoded into the skill body — so it grows without bloating the
+> always-loaded skill and stays one edit away from current.
+
+## Lookup
+
+| Signature (what you see) | Likely cause | First check |
+|---|---|---|
+| **Tool/agent loop** — same tool called >2× with near-identical args, no progress | Missing stop condition; reading without acting; ambiguous state | Stop. State the hypothesis in one line. Act or ask — do not re-read. (`context-hygiene` 15/25 rule) |
+| **HTTP 429 / "rate limit" / "quota"** | Too-frequent calls; shared quota; missing backoff | Inspect response headers (`Retry-After`, `X-RateLimit-*`); add exponential backoff; check if a loop is firing the calls |
+| **`ECONNREFUSED` / connection refused** | Service not up; wrong host/port; container not started | Is the service running? (`docker compose ps`, health endpoint); is the port right? (`lsof -i :PORT`); is it bound to `127.0.0.1` vs `0.0.0.0`? |
+| **`ENOENT` / "no such file or directory"** | Wrong cwd; path relative vs absolute; file not generated yet | Print the *resolved absolute* path; check cwd; confirm a prior step actually wrote the file |
+| **Timeout / hang** | Blocking I/O; deadlock; awaiting a condition that never holds | What is it waiting on? Add a log right before the blocking call; bound the wait; check for a missing `await`/`return` |
+| **`OOM` / killed (137) / heap out of memory** | Unbounded collection; loading all rows; leak in a loop | What grows per iteration? Stream/paginate instead of loading all; check `--max-old-space-size` only after finding the growth |
+| **`EACCES` / permission denied** | Wrong file mode; running as wrong user; read-only mount | `ls -l` the target; check the process user; is the path a read-only volume? |
+| **Flaky test (passes alone, fails in suite)** | Shared state; order dependence; real clock/random; unawaited async | Run the test in isolation vs in suite; look for shared fixtures, global state, `Date.now()`/random, missing `await` |
+| **Works locally, fails in CI** | Env/config drift; missing service; absent secret; path/case sensitivity | Diff env (`printenv`); is the service/secret present in CI? Linux is case-sensitive — check filename casing |
+| **Intermittent / "sometimes"** | Race; timing; network; non-deterministic order | Reproduce with condition-based waiting, not fixed sleeps (`systematic-debugging` § Condition-based waiting); log timestamps |
+
+## How to use
+
+1. Match the symptom to a signature above.
+2. Run the **first check** — it is the highest-probability isolation step, not a fix.
+3. If it confirms the cause → fix + add a regression test. If not → fall back to
+   the full `systematic-debugging` loop from Phase 1.
+
+No signature matches → this table earned nothing; debug from first principles.

package/docs/guidelines/agent-infra/frontier-reasoning-operating-profile.md

@@ -6,6 +6,11 @@
 > weaker models skip — the **transferable operating discipline** — and the
 > boundary of what is *not* transferable.
 >
+> **User entry point:** for the one-screen "what it does / when it fires / how to
+> turn it off" contract, see
+> [`docs/contracts/reasoning-discipline-protocol.md`](../../contracts/reasoning-discipline-protocol.md).
+> This dossier holds the depth; that contract is where users start.
+>
 > Citation discipline: every catalog row names its source **and its dignity**
 > (Anthropic primary doc · third-party review · customer testimonial · our own
 > derivation). Two independent external model analyses (Claude + GPT) corroborate

package/docs/guidelines/agent-infra/size-and-scope.md

@@ -106,6 +106,23 @@ Guidelines are reference — not execution.
 
 ---
 
+## Knowledge cards
+
+Committed knowledge cards (`agents/knowledge/<source>.md`) are a size-bounded,
+evidence-disciplined context type:
+
+- Hard bound: **≤ 150 lines** — a card is a thin distillation, never a mirror.
+- **Mandatory** `links.authoritative` pointer (path or URL).
+- Enforced by `check_knowledge_cards.py` (pointer-resolution CI + size +
+  trust-tag + multi-evidence git-ancestry consistency; `--strict` adds a
+  content-compare). Durable content = negative facts + pointers; positive
+  structure is a per-line, last-verified hypothesis.
+
+See [`source-discovery`](../../../src/skills/source-discovery/SKILL.md) and the
+`evidence-discipline` context for the full model.
+
+---
+
 # Component responsibilities
 
 ## Rules

package/docs/guidelines/agent-infra/skill-quality-checklist.md

@@ -25,7 +25,7 @@ Every skill MUST have: `When to use`, `Procedure`, `Gotcha`, `Output format`, `D
 
 Every skill's YAML frontmatter MUST validate against `scripts/schemas/skill.schema.json`.
 Violations are reported by `scripts/skill_linter.py` as `schema_<rule>` errors
-and fail `python3 scripts/validate_frontmatter.py` and the full CI pipeline.
+and fail `./scripts-run src/scripts/validate_frontmatter` and the full CI pipeline.
 
 ### Omit fields equal to their schema default
 
@@ -41,7 +41,7 @@ A field that carries the schema `default` (e.g. `trust.level: core`,
 every consumer (validator, discovery manifest, drift checksum). Writing it
 anyway is boilerplate that `scripts/lint_frontmatter_boilerplate.py` rejects
 (wired into `task ci-fast`). To strip it across the tree, run
-`python3 scripts/migrate_frontmatter_defaults.py`. Background:
+`./scripts-run src/scripts/migrate_frontmatter_defaults`. Background:
 `road-to-abstraction-reduction.md` +
 `agents/evidence/analysis/abstraction-reduction-preflight.md`.
 

package/docs/guides/frontend-design-corpus-refresh.md

@@ -0,0 +1,83 @@
+# Corpus refresh runbook — trigger-eval recording (ADR-061 §6 DoD)
+
+How to refresh a corpus-backed skill (`design-intelligence`, and any future
+SHA-pinned corpus) and keep its trigger-eval provenance current. This is the
+**corpus-refresh Definition of Done**: a refresh that bumps the upstream SHA or
+edits the routing description is not done until a live trigger-eval has been
+re-run and recorded against the new pin.
+
+> **Scope.** Applies to a skill whose `data/manifest.json` has an
+> `upstream` block with a real `sha`. Original-authored corpora (`upstream:
+> null`, e.g. `brand`) have no SHA to pin an eval to and are out of scope —
+> `lint_eval_freshness.py` skips them.
+
+## When a refresh fires
+
+- The upstream SHA is bumped (new corpus content adopted), OR
+- The skill's `description` (its routing trigger surface) is edited, OR
+- The quarterly refresh cadence in the manifest comes due.
+
+Any of these can change which queries the description fires on, so the recorded
+recall/precision must be re-measured.
+
+## The refresh steps
+
+1. **Bump the pin / edit the corpus** in `src/skills/<skill>/data/` and update
+   `upstream.sha` + `upstream.last_checked` in the manifest.
+
+2. **Run the live trigger-eval** (token spend — interactive, gated):
+
+   ```bash
+   task setup-evals            # once: bootstrap .venv with the pinned anthropic SDK
+   task install-anthropic-key  # once: install ~/.event4u/agent-config/anthropic.key
+   .venv/bin/python3 src/scripts/skill_trigger_eval.py \
+     --skill <skill> --output /tmp/<skill>-eval.json
+   ```
+
+   The runner enforces a tty + an explicit `yes` at the cost preview. It writes
+   the `EvalResult` JSON (router, model, metrics) to `--output`.
+
+3. **Record the result into the manifest:**
+
+   ```bash
+   agent-config eval:record \
+     --eval-json /tmp/<skill>-eval.json \
+     --manifest src/skills/<skill>/data/manifest.json
+   ```
+
+   This stamps `upstream.last_eval` with the measured precision/recall, the
+   `sha_at_eval` (= the current `upstream.sha`), the domain-specific floor, and
+   `passed`. Exit codes: `0` pass · `1` recorded-but-floor-missed · `2`
+   integrity error (nothing written). A `--dry-run` / MockRouter result is
+   refused unless `--allow-mock` (plumbing only) — a mock number is never
+   provenance.
+
+4. **Re-condense + commit** the manifest change through the normal `src/` →
+   `/condense` flow.
+
+## Definition of Done
+
+A corpus-refresh PR does **not** merge unless, for every in-scope skill it
+touches:
+
+- `upstream.last_eval.passed: true`, AND
+- `upstream.last_eval.sha_at_eval == upstream.sha`.
+
+`src/scripts/lint_eval_freshness.py` (deterministic, no token spend) enforces
+this. It is run standalone today (`task lint-eval-freshness`); it moves into the
+blocking `task ci-fast` aggregate once the in-scope corpora carry a recorded
+`last_eval` (the one-time live backfill below).
+
+## One-time backfill
+
+Every already-shipped, SHA-pinned corpus skill needs its first recording. Run
+steps 2–3 once per skill — `design-intelligence` first, then any other
+SHA-pinned corpus that ships `evals/triggers.json`. Because step 2 is a live,
+spend-bearing run, do the backfill as a deliberate, confirmed pass — not
+autonomously.
+
+## See also
+
+- [`recordTriggerEval.ts`](../../src/cli/commands/recordTriggerEval.ts) — the `eval:record` implementation + domain-specific floors.
+- [`lint_eval_freshness.py`](../../src/scripts/lint_eval_freshness.py) — the deterministic freshness gate.
+- [`corpus-grounding`](../../src/skills/corpus-grounding/SKILL.md) + [ADR-061](../decisions/ADR-061-corpus-grounding-layer.md) §6 — the provenance discipline this DoD enforces.

package/docs/guides/skill-preview.md

@@ -18,7 +18,7 @@ Find a candidate with [`/skills:discover`](skill-discovery.md), then look before
 Under the hood:
 
 ```bash
-python3 scripts/skill_preview.py competitive-positioning
+./scripts-run src/scripts/skill_preview competitive-positioning
 ```
 
 ## 2. Read the summary

package/docs/hook-payload-capture.md

@@ -55,7 +55,7 @@ ls -1 "$AGENT_HOOK_CAPTURE_DIR" | head
 
 # 5. Redact (replaces user-content fields with <REDACTED>;
 #    envelope keys preserved).
-python3 scripts/redact_hook_capture.py "$AGENT_HOOK_CAPTURE_DIR" --strict
+./scripts-run src/scripts/redact_hook_capture "$AGENT_HOOK_CAPTURE_DIR" --strict
 
 # 6. Pick the smallest representative file.
 ls -1Sr "$AGENT_HOOK_CAPTURE_DIR"/*.redacted.json | head -1
@@ -174,9 +174,9 @@ After pasting and flipping the checkbox:
 
 ```bash
 # Lint gates must stay green.
-python3 scripts/lint_hook_manifest.py
-python3 scripts/check_references.py
-python3 scripts/check_portability.py
+./scripts-run src/scripts/lint_hook_manifest
+./scripts-run src/scripts/check_references
+./scripts-run src/scripts/check_portability
 
 # Tests still green.
 python3 -m pytest tests/hooks/ -q

package/docs/mcp.md

@@ -68,7 +68,7 @@ task mcp:check
 Or invoke the script directly (maintainer workflow, inside the package repo):
 
 ```bash
-python3 scripts/mcp_render.py [--source PATH] [--claude-desktop] [--check]
+./scripts-run src/scripts/mcp_render [--source PATH] [--claude-desktop] [--check]
 ```
 
 Default output paths:

package/docs/migration/consumer-template-consumption-model.md

@@ -0,0 +1,145 @@
+# Consumer Template Consumption Model
+
+> Phase 1 Step 11 of `agents/roadmaps/road-to-typescript-only-scripts.md`.
+> Question: how does `dist/agent-src/templates/scripts/` content reach a consumer
+> project — copied, referenced in place, or symlinked — and what does that mean
+> for the Phase 9 TS migration of the consumer-shipped scripts?
+
+## Verdict: hybrid — in-place execution is primary, copies are secondary
+
+The template scripts are **executed in place from the installed package root**
+as the primary channel, with **two copy channels** layered on top (one
+installer-driven, one manual). Nothing is ever symlinked into a consumer tree —
+the installer explicitly dereferences symlinks on copy
+(`src/scripts/install.py:3201-3264`, rationale at `install.py:1950-1953`:
+"Council Round 3 Q1 rejected cross-scope symlinks").
+
+### Channel 1 — in-place from the package root (primary)
+
+The consumer CLI (`agent-config`, master entrypoint
+`src/scripts/_dispatch.bash`) derives `PACKAGE_ROOT` from its own location —
+`node_modules/@event4u/agent-config/` or the global npm install — and resolves
+symlinks first (`_dispatch.bash:24-32`).
+
+- The work engine (`/work`, `/implement-ticket`) runs **exclusively** in place:
+  `cmd_implement_ticket` and `cmd_work` hard-code
+  `engine_root="$PACKAGE_ROOT/dist/agent-src/templates/scripts"` and exec
+  `python3 -m work_engine` with `PYTHONPATH=$engine_root`
+  (`_dispatch.bash:393-420`). There is **no consumer-override tier** for the
+  engine.
+- The memory/telemetry CLI surface (`memory:lookup`, `memory:signal`,
+  `memory:hash`, `telemetry:record|status|report`, `check_memory`,
+  `check_memory_proposal`) resolves through `resolve_template_script`
+  (`_dispatch.bash:318-337`, call sites `:422-478`) with a three-tier chain:
+
+  1. `$CONSUMER_ROOT/scripts/<name>` — local copy / customization (wins)
+  2. `$CONSUMER_ROOT/.augment/templates/scripts/<name>` — installer-shipped
+     (legacy project-scope projection)
+  3. `$PACKAGE_ROOT/dist/agent-src/templates/scripts/<name>` — package-internal
+     fallback (the path every fresh consumer actually hits)
+
+### Channel 2 — installer-driven copies (user scope, Augment only)
+
+Consumer installs are **global-only** per ADR-020: both front doors gate
+`--scope=project` behind `AGENT_CONFIG_DEV_MODE=1`
+(`src/scripts/install:188-196` and `install.py:2142-2163`,
+`_enforce_consumer_global_only` called from `main()` at `install.py:4745`).
+
+In global scope, only the **Augment** deploy plan copies the templates tree:
+`("dist/agent-src/templates", "templates")` in `GLOBAL_DEPLOY_SOURCES`
+(`install.py:1993-2002`) lands `templates/scripts/` under `~/.augment/templates/`
+(anchor `install.py:1841`). The Claude Code skill bundle
+(`_CLAUDE_SKILL_BUNDLE`, `install.py:1977-1992`) ships rules/skills/commands/
+personas but **not** templates. Source paths always reference `dist/agent-src/`
+because that is the only asset tree in the npm tarball
+(`install.py:1973-1976`, `package.json#files`).
+
+Note the asymmetry: the dispatcher's tier-2 lookup reads the **project-local**
+`.augment/templates/scripts/` (written only by the legacy/maintainer
+project-scope install), not the global `~/.augment/templates/`. The global
+Augment copy exists for the Augment tool surface itself, not for the
+dispatcher.
+
+The wizard is the same engine, not a separate one: `src/server/routes/wizard.ts`
+spawns `scripts/install.py --apply-payload` (`wizard.ts:325`, `:371`, `:953`),
+so all GUI installs converge on the copy semantics above.
+
+### Channel 3 — documented manual copies (opt-in features)
+
+`src/agent-src/templates/scripts/README.md:21-36` and `:171-178` instruct
+consumers to `cp` selected scripts into their own tree: `pr_risk_review.py`,
+`pr_review_routing.py` → consumer `scripts/`; YAML examples → `.github/`. The
+shipped GitHub workflow templates depend on those copies
+(`src/agent-src/templates/github-workflows/memory-hygiene.yml:14`,
+`pr-risk-review.yml:9`). These copies are consumer-owned the moment they are
+made.
+
+## (b) Can consumers modify the scripts locally? Do re-installs overwrite?
+
+- **Installer-deployed copies are always overwritten.** `_resolve_file_conflict`
+  (`install.py:229-243`) unconditionally returns `"write"` — "deploys always
+  overwrite; the flag never gates a write". Edits inside `~/.augment/templates/`
+  (or a legacy project `.augment/`) are clobbered on the next
+  `init`/`sync`/`refresh`. Orphans are never deleted, though — the copier only
+  writes, so files removed upstream linger in the anchor.
+- **The sanctioned customization point is the consumer's own `scripts/` dir.**
+  Tier 1 of `resolve_template_script` ("Consumer customization wins so projects
+  can patch behavior locally without losing the upstream default",
+  `_dispatch.bash:316-317`) plus the README `cp` flow. The installer never
+  touches `$CONSUMER_ROOT/scripts/`, so these copies survive re-installs —
+  and silently pin an old version until the consumer re-copies.
+- **The work engine cannot be customized at all** (no override tier).
+
+## (c) What invokes the template scripts at runtime?
+
+1. **Dispatcher subcommands** — `./agent-config work | implement-ticket |
+   memory:* | telemetry:* | check_memory*` (`_dispatch.bash:393-478`). Hook
+   trampolines installed by `install.py` call the **global binary**, which is
+   this same dispatcher (ADR-020); the hook scripts themselves live under
+   `src/scripts/hooks/`, not under `templates/scripts/`.
+2. **Rules/skills markdown** — always-loaded artifacts tell the agent to run
+   the scripts directly, e.g. `src/rules/security-sensitive-stop.md`
+   (`from scripts.memory_lookup import retrieve` — assumes the tier-1 consumer
+   copy), `src/rules/ui-audit-gate.md` and `src/skills/flux/SKILL.md` (link to
+   `templates/scripts/work_engine/directives/...`), and
+   `src/agent-src/contexts/contracts/artifact-engagement-flow.md:218`
+   (`sys.path.insert(0, ...)` onto the templates dir).
+3. **Consumer GitHub workflows** — the copied workflow templates execute the
+   consumer-copied `scripts/*.py` in the consumer's CI.
+
+## (d) Consequences for Phase 9 (TS migration of consumer templates)
+
+Phase 9 must treat `templates/scripts/` as **three independent surfaces**:
+
+1. **In-place engine + dispatcher fallback (easy).** Because fresh consumers
+   execute tier 3 (`PACKAGE_ROOT/dist/...`), migrating a script is: ship the
+   `.ts` in the tarball, repoint the dispatcher subcommand (`python3 <script>` →
+   the TS runner), delete the `.py`. No consumer-side migration needed; the
+   next package update flips everyone atomically. The work engine is the
+   cleanest case — single call site, no override tier.
+2. **Stale copies the installer must detect (the real work).** The TS installer
+   (Phase 3 Step 2 already plans a dual-mode transition layer) must:
+   - detect tier-1/tier-2 Python copies (`$CONSUMER_ROOT/scripts/<name>.py`,
+     `.augment/templates/scripts/`) that shadow a migrated script — the
+     resolution chain is keyed by **exact filename**, so a leftover
+     `memory_lookup.py` keeps winning forever if the dispatcher still probes
+     for it, or silently stops being found if the probe name changes to `.ts`;
+     either way the installer must warn and offer migration/removal;
+   - clean up **orphaned** `.py` files in deployed anchors (the always-overwrite
+     copier never deletes), ideally manifest-driven (the install manifest
+     already records written paths, `install.py:3208-3210`);
+   - keep honoring consumer-owned copies under `$CONSUMER_ROOT/scripts/` as
+     customizations — warn, never delete.
+3. **Lockstep doc/markdown updates.** Every rule/skill/workflow template that
+   names a `.py` path (channel 3 and the markdown references in (c)) must flip
+   in the same PR as the script, or agents will instruct consumers to run
+   files that no longer exist.
+
+**Recommended Phase 9 mechanics:** migrate per script-cluster behind the
+dispatcher — (1) land the TS implementation in the tarball, (2) change the
+dispatcher to probe `<name>.ts` (tier 1/2) before falling back to the packaged
+TS, keeping a one-release deprecation warning when a consumer-local `.py`
+shadow is detected, (3) update the referencing markdown in the same PR,
+(4) have the TS installer's dual-mode layer flag/clean stale `.py` copies, and
+(5) drop the Python fallback once the dashboard shows the
+`consumer-templates` bucket at zero.