@event4u/agent-config 6.1.0 → 7.0.1

package/docs/decisions/ADR-102-ticket-handoff-paste-and-mcp.md

@@ -0,0 +1,72 @@
+---
+adr: 102
+status: accepted
+date: 2026-06-16
+decision: ticket-handoff-paste-and-mcp
+supersedes: —
+superseded_by: —
+phase: ticket-bundles (rework)
+type: structural
+---
+
+# ADR-102 — Ticket handoff is paste/MCP, not an API export
+
+## Status
+
+**Accepted** · 2026-06-16. Supersedes the **transport decision** of
+[ADR-101](ADR-101-ticket-bundle-emission.md) (its R2/R4 GraphQL-export +
+idempotency, and the `linear_state` part of R3). The rest of ADR-101 — the
+bundle format, the buildability gate, `model_tier` per ticket, the traceability
+spine, v1-immutable — stands unchanged.
+
+## Context
+
+ADR-101 specified that a roadmap-materialised ticket bundle projects into Linear
+via a GraphQL exporter (`build_ticket_export.py`) with query/map-first
+idempotency tracked in a manifest `linear_state` map (CSV as a bootstrap).
+
+The maintainer's actual requirement is simpler: **be able to copy/paste an MD
+ticket into a Linear (or Jira) issue.** An automatic API export is unwanted —
+"the agent can do that via MCP anyway; we don't need to wire it through an API."
+The GraphQL client, the idempotency map, the transport spike, and the drift
+check were solving a problem that does not exist.
+
+## Decision
+
+1. **No bundled API client, no automatic export.** Remove
+   `build_ticket_export.py` and the planned `tickets:export` CLI.
+   The package ships zero Linear/Jira API wiring.
+2. **The MD ticket is the handoff artifact.** Its frontmatter `title` is the
+   issue title; its Markdown body is the issue description (renders in
+   Linear/Jira). A human pastes it; the body is authored render-ready.
+3. **MCP is the programmatic surface.** To create issues without pasting, the
+   agent uses a tracker **MCP server** (Linear/Jira) with the ticket as input.
+   Integration lives at the MCP layer, not in this package.
+4. **No tracker state in the bundle.** Drop `linear_state` from the manifest +
+   its schema. A tracker issue is a one-way copy; nothing is read back. The
+   bundle is the source of truth (ADR-101 D7, unchanged).
+
+## Consequences
+
+- **Positive.** Far less machinery to maintain (no API client, no idempotency
+  map, no transport spike, no drift check). No token dependency — the whole
+  thing works offline. Matches how the maintainer actually moves tickets.
+- **Negative / cost.** No one-command bulk import; bulk creation is paste-by-paste
+  or an MCP loop. Acceptable — bundles are small and the agent can drive MCP.
+- **Neutral.** Re-creating an edited ticket in the tracker is a re-paste / MCP
+  update; there is no automatic reconciliation (there was none worth keeping).
+
+## Alternatives considered
+
+1. **Keep the GraphQL exporter (ADR-101 R2).** Rejected by the maintainer —
+   unwanted API surface; MCP already covers programmatic creation.
+2. **CSV bootstrap.** Rejected — same "automatic export" we are removing.
+3. **A thin "render paste-ready" helper.** Not needed — the ticket body is
+   already paste-ready Markdown; a helper would be ceremony.
+
+## References
+
+- [ADR-101](ADR-101-ticket-bundle-emission.md) — the bundle format (transport
+  decision superseded here).
+- [`ticket-bundle-format`](../contracts/ticket-bundle-format.md) §8 — the
+  paste/MCP handoff (rewritten).

package/docs/decisions/ADR-103-global-knowledge-default-off-until-measured.md

@@ -0,0 +1,92 @@
+---
+adr: 103
+status: accepted
+date: 2026-06-16
+decision: global-knowledge-default-off-until-measured
+supersedes: —
+superseded_by: —
+phase: evidence-v2
+type: structural
+---
+
+# ADR-103 — Global knowledge sharing defaults OFF until cross-project reuse is measured
+
+## Status
+
+Accepted (2026-06-16). Council-reviewed (claude-sonnet-4-5 + gpt-4o, design mode,
+2 rounds + peer-review) as part of Evidence v2 Phase 0. **Amends
+[ADR-100](ADR-100-global-knowledge-card-sharing.md) Decision-6/Consequences**
+(the `knowledge.global_sharing.enabled` default) only. The rest of ADR-100 — the
+file-first store, origin-tier scoping, redaction-on-write, hybrid promotion,
+kill-switch — stands unchanged.
+
+## Context
+
+[ADR-098](ADR-098-evidence-first-structure-discovery.md) Decision-10 killed the
+global/registry/promotion layer with an explicit gate: *measure cross-project
+reuse over the measurement window, then decide*. [ADR-100](ADR-100-global-knowledge-card-sharing.md)
+reversed that kill on the **same day** and shipped the layer **default-ON**,
+justified by "measured v1 reuse + the cross-project value case".
+
+An independent review of the shipped v1 (claude-sonnet-4-5 + gpt-4o) found that
+justification circular: v1 was ~1 day old, the measurement window was never
+waited out, so there is **no measured reuse** — "measured v1 reuse" is a
+rationale, not a data point. The global layer thus shipped having bypassed the
+very gate that was the point of the gating exercise. Default-ON cross-project
+data movement also sits poorly with the otherwise privacy-first posture of a tool
+**other people install**: the tier-classifier can misclassify, and redaction is
+regex-based (can miss novel formats) — both listed as accepted risks in ADR-100.
+
+## Decision
+
+1. **`knowledge.global_sharing.enabled` defaults to `false`.** The store is
+   opt-in, not opt-out, until cross-project reuse exists as a measured signal.
+   The kill-switch from ADR-100 is excellent; this ADR only inverts its default.
+
+2. **The measure-then-decide gate is restored, concretely.** The default flips
+   back to `true` only when reuse is instrumented across **≥ 2 real projects**
+   and shown positive — the `_lib/knowledge_global_promote.py record-seen`
+   sightings are the instrument that already exists. Until then, opt-in stands.
+
+3. **v1 is byte-for-byte unaffected.** Project-local discipline + cards do not
+   read or write the global store regardless of this default. Only the
+   cross-project layer is gated off.
+
+4. **No new mechanism.** Promotion stays suggest-then-confirm; tier scoping,
+   redaction-on-write, and the purge command are unchanged. This ADR changes one
+   default value and the obligation to measure before flipping it back.
+
+## Consequences
+
+- `knowledge.global_sharing.enabled` default flips `true → false` in
+  `src/config/agent-settings.template.yml`, `src/server/schemas/settings.ts`,
+  and the `src/agent-src/templates/agent-settings.md` settings table.
+- `evidence-discipline.md` § Global layer notes the default-off posture and the
+  reuse-gate condition for flipping it back on.
+- A consuming operator who wants cross-project sharing sets `enabled: true`
+  explicitly — a deliberate, informed opt-in.
+- The reuse measurement (Evidence v2 Phase 5 / global-promotion gate) is the
+  evidence that would justify flipping the default back; until that data exists,
+  the question is not re-litigated.
+
+## Alternatives
+
+- **Keep default-on (do nothing).** Rejected — restates the skipped-gate failure
+  the v1 review flagged; default cross-project data movement on an installed tool
+  is the wrong default before reuse is measured.
+- **`public`-only on, `vendor` off.** Considered; rejected as the default because
+  it still moves data cross-project by default. Off-until-measured is the cleaner
+  privacy-first default. An operator may set `allowed_tiers: [public]` after
+  opting in if they want the narrower surface.
+- **Delete the global layer.** Rejected — ADR-100's file-first design is sound;
+  the issue is the *default*, not the mechanism.
+
+## References
+
+- [ADR-100](ADR-100-global-knowledge-card-sharing.md) — the global layer; Decision-6
+  default amended here.
+- [ADR-098](ADR-098-evidence-first-structure-discovery.md) — the original
+  measure-then-decide gate this ADR restores.
+- `agents/roadmaps/archive/road-to-evidence-v2-project-intelligence.md` — Evidence v2
+  Phase 0 (council convergence inlined in its header; archived on completion).
+- `src/agent-src/contexts/execution/evidence-discipline.md` § Global layer.

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