@event4u/agent-config 6.0.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

@@ -93,6 +93,21 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-087](ADR-087-installer-e2e-test-strategy.md) | Installer E2E Test Strategy | accepted | 2026-06-11 | — |
 | [ADR-088](ADR-088-no-external-runtime-federation.md) | No External Runtime Federation | accepted | 2026-06-11 | — |
 | [ADR-089](ADR-089-lean-local-plugin-install.md) | Lean Local Plugin Install | accepted | 2026-06-12 | — |
+| [ADR-090](ADR-090-visibility-command-frontmatter-field.md) | Visibility Command Frontmatter Field | accepted | 2026-06-13 | — |
+| [ADR-091](ADR-091-split-meta-capability-packs.md) | Split Meta Capability Packs | accepted | 2026-06-13 | — |
+| [ADR-092](ADR-092-defer-command-tier-alias-removal.md) | Defer Command Tier Alias Removal | accepted | 2026-06-13 | — |
+| [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/development.md

@@ -8,7 +8,7 @@
 
 ## Editing content
 
-1. **Always edit in `.agent-src.uncondensed/`** — never in `dist/agent-src/` or `.augment/` directly
+1. **Always edit in `src/`** — never in `dist/agent-src/` or `.augment/` directly
 2. Run `task sync` to copy non-`.md` files
 3. Use the `/condense` command to condense changed `.md` files
 4. Run `task ci` to verify everything passes before pushing
@@ -33,7 +33,7 @@ task consistency-fix           # Regenerate all derived outputs from source
 ### Sync & Condensation
 
 ```bash
-task sync                      # .agent-src.uncondensed/ → dist/agent-src/, then project → .augment/
+task sync                      # src/ → dist/agent-src/, then project → .augment/
 task sync-changed              # List .md files changed since last condensation
 task sync-check                # Check if dist/agent-src/ is in sync (for CI)
 task sync-check-hashes         # Verify condensed .md hashes match source
@@ -202,13 +202,11 @@ tests/
 └── consistency.yml            ← Sync + hash + tool verification
 src/templates/consumer-settings/   ← Settings templates for consumer projects
 
-.agent-src.uncondensed/         ← Source of truth (human-readable, verbose)
+src/                            ← Source of truth (human-readable, verbose)
 ├── rules/                     ← Behavior rules
 ├── skills/                    ← Skill definitions (SKILL.md per skill)
-├── commands/                  ← Slash command definitions
-├── guidelines/                ← Coding guidelines by language
-├── templates/                 ← Document scaffolds
-└── contexts/                  ← System knowledge documents
+├── domains/                   ← Slash command definitions (per pack)
+└── agent-src/                 ← Contexts, templates, profiles, personas, …
 
 dist/agent-src/                    ← Condensed output (token-efficient, shipped)
 ├── (same structure)           ← Condensed .md + copied non-.md files

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 79 rules. No configuration needed.
+This is enforced automatically by 88 rules. No configuration needed.
 
 ---
 
@@ -167,9 +167,9 @@ Your agent now understands slash commands:
 | `/optimize skills` | Audit skills, find duplicates, run linter |
 | `/feature plan` | Interactively plan a feature |
 | `/quality-fix` | Run and fix all quality checks |
-| `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
+| `/chat-history import` | Pull a prior session into the current chat (resume) |
 
-→ [Browse all 150 active commands](../dist/agent-src/commands/)
+→ [Browse all 161 active commands](../dist/agent-src/commands/)
 
 ---
 
@@ -188,7 +188,7 @@ Logging is **hook-only**: a structural Augment hook fires on
 transparently if the fingerprint does not match (fresh chat) and
 otherwise appended to.
 
-Run `/chat-history` (a.k.a. `/chat-history show`) any time to inspect
+Use your host's native transcript / session view any time to inspect
 the log size, last entries, and current fingerprint. For the rare case
 where auto-adopt misfires (corrupted file, hook misconfiguration), run
 `./agent-config chat-history:adopt` as the manual recovery lever.

package/docs/guidelines/agent-infra/5w2h-analysis.md

@@ -257,4 +257,4 @@ Inversion → For each W / H, ask "what if it's missing?"
 
 ## ADOPT citation
 
-Adopted from [`ginobefun/deep-reading-analyst-skill`](https://github.com/ginobefun/deep-reading-analyst-skill) @ commit `26cd7dc9` · `src/deep-reading-analyst/references/5w2h_analysis.md` · MIT License.
+Adapted from an external reference.

package/docs/guidelines/agent-infra/comparison-matrix.md

@@ -176,4 +176,4 @@ unresolved and needs more evidence.
 
 ## ADOPT citation
 
-Adopted from [`ginobefun/deep-reading-analyst-skill`](https://github.com/ginobefun/deep-reading-analyst-skill) @ commit `26cd7dc9` · `src/deep-reading-analyst/references/comparison_matrix.md` · MIT License.
+Adapted from an external reference.

package/docs/guidelines/agent-infra/corpus-grounding-authoring.md

@@ -84,7 +84,7 @@ selection*, architecture-pattern selection. Watch note:
 
 | Domain | Skill / manifest | Tier | Source pin |
 |---|---|---|---|
-| Frontend design | `design-intelligence/data/manifest.json` | conditional-grounding | ui-ux-pro-max @ b7e3af80 |
+| Frontend design | `design-intelligence/data/manifest.json` | conditional-grounding | external reference @ b7e3af80 |
 | Security / threat-modeling | `threat-modeling/data/manifest.json` | conditional-grounding | MITRE ATT&CK v16 + OWASP ASVS 4.0 (derived) |
 | API design | `api-design/data/manifest.json` | lookup-only | RFC 9110/9457 + field-standard practice (derived) |
 | DB-query tuning | `database/data/manifest.json` | lookup-only | PostgreSQL 16 / MySQL 8 docs (derived) |

package/docs/guidelines/agent-infra/critical-thinking.md

@@ -152,5 +152,5 @@ This prevents attacking strawmen and ensures fair evaluation.
 
 ## ADOPT citation
 
-Adopted from [`ginobefun/deep-reading-analyst-skill`](https://github.com/ginobefun/deep-reading-analyst-skill) @ commit `26cd7dc9` · `src/deep-reading-analyst/references/critical_thinking.md` · MIT License.
+Adapted from an external reference.
 

package/docs/guidelines/agent-infra/engineering-memory-data-format.md

@@ -22,7 +22,6 @@ that prefer one file per type.
 | Type | Single-file path | Sharded path |
 |---|---|---|
 | Domain invariants | `agents/memory/domain-invariants.yml` | `agents/memory/domain-invariants/<hash>.yml` |
-| Architecture decisions | `agents/memory/architecture-decisions.yml` | `agents/memory/architecture-decisions/<hash>.yml` |
 | Incident learnings | `agents/memory/incident-learnings.yml` | `agents/memory/incident-learnings/<hash>.yml` |
 | Product rules | `agents/memory/product-rules.yml` | `agents/memory/product-rules/<hash>.yml` |
 
@@ -50,7 +49,7 @@ rejects entries missing any required field.
 
 The `priority` field controls how aggressively `/memory:load` surfaces
 an entry. The three-tier enum is intentional — see
-`road-to-dream-skill-adoption.md` § B2 and the Phase 2 council brief
+an internal roadmap (local-only) § B2 and the Phase 2 council brief
 for why a fourth `high` tier was rejected.
 
 | Value | Meaning | Reader behaviour |
@@ -103,9 +102,6 @@ templates for the full shape:
 
 - [`domain-invariants.example.yml`](../../templates/agents/memory/domain-invariants.example.yml)
   adds `rule`, `boundary`, `scope.paths`, `violation_contract`.
-- [`architecture-decisions.example.yml`](../../templates/agents/memory/architecture-decisions.example.yml)
-  adds `title`, `context`, `decision`, `alternatives_rejected`,
-  `trade_offs`, `paths`, `superseded_by`.
 - [`incident-learnings.example.yml`](../../templates/agents/memory/incident-learnings.example.yml)
   adds `pattern`, `trigger_conditions`, `consequence`, `guardrail`,
   `enforcement`, `severity`.

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/first-principles.md

@@ -189,4 +189,4 @@ This exposes weak arguments and strengthens valid ones.
 
 ## ADOPT citation
 
-Adopted from [`ginobefun/deep-reading-analyst-skill`](https://github.com/ginobefun/deep-reading-analyst-skill) @ commit `26cd7dc9` · `src/deep-reading-analyst/references/first_principles.md` · MIT License.
+Adapted from an external reference.

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

@@ -0,0 +1,169 @@
+# Frontier-Grade Reasoning — Operating Profile
+
+> Source dossier for the **Reasoning Discipline Protocol (RDP)** — the durable,
+> sourced rationale behind the RDP gate context, rule, and skills. It documents what a
+> frontier reasoning model (Anthropic's Fable 5 / Mythos 5, June 2026) does that
+> 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
+> but are never the primary evidence for a transferable-behavior line. A
+> line-by-line audit (2026-06-13) corrected five rows; the load-bearing claims
+> (over-prescription degrades, reasoning-in-response → refusal) are verbatim in
+> Anthropic's prompting doc and stand.
+
+## The one boundary that frames everything
+
+```
+CAPABILITY DOES NOT TRANSFER. DISCIPLINE DOES.
+```
+
+A frontier model's edge lives in its **weights** — gains spread across the whole
+training stack, with no single copyable prompt (the explicit framing is Nathan
+Lambert / Interconnects [lam]; Anthropic's docs support only the weaker "needs
+less scaffolding" [pf]). No skill, rule, or workflow makes Sonnet/Opus/GPT
+*equal* Fable 5, and anyone promising that is selling the hallucinated analysis
+this suite refuses to produce.
+
+What *does* transfer is the **operating discipline**: the steps a frontier model
+takes on its own that weaker models skip unless forced. On under-specified and
+long-horizon tasks, that discipline gap is the largest part of the *visible*
+quality difference. RDP transplants the discipline; it never claims the
+capability.
+
+> **Background (dates, precise):** Anthropic's own banner dates the **access
+> suspension of Fable 5 / Mythos 5 to 2026-06-12** [an]; the related US
+> export-control directive / Reuters report is **2026-06-13** [re]. Either way
+> the model is currently inaccessible, so we cannot A/B against it — our own
+> falsifiable eval is the only ground truth, which makes the discipline-transplant
+> approach *more* relevant, not less.
+
+## Sources (with dignity)
+
+- **[an]** Anthropic — *Claude Fable 5 and Mythos 5* announcement. Primary, but
+  several quotes on the page are **customer testimonials** (labeled per-row), not
+  Anthropic capability statements.
+- **[pf]** Anthropic docs — *Prompting Claude Fable 5*. Primary; the transferable
+  prompting playbook. Load-bearing claims live here.
+- **[in]** Anthropic docs — *Introducing Fable 5 / Mythos 5*. Primary; adaptive
+  thinking + effort parameter + memory tool + refusals.
+- **[ve]** Vellum — benchmark breakdown. **Third-party**; benchmark numbers are
+  not verifiable in Anthropic prose and must be labeled third-party or pulled to
+  the system card.
+- **[cr]** CodeRabbit model review. **Third-party**; source of the
+  "explore-environment-first" observation (not Anthropic-documented).
+- **[lam]** Nathan Lambert / Interconnects. **Third-party analysis**; "whole
+  training stack, no copyable prompt".
+- **[re]** Reuters — export-control report (2026-06-13).
+- Two external model analyses (Claude + GPT), provenance untracked in
+  `agents/.harvest-local/` — **corroboration only**, never primary.
+
+## Transferable-behavior catalog
+
+Each row: behavior → **source + dignity** → transplant mechanism → carrier.
+
+| Behavior | Source (dignity) | Transplant | Carrier |
+|---|---|---|---|
+| Audit progress against real tool results | **[pf] ✓ primary** | every claim cites a tool result | shipped: `verify-before-complete` |
+| Act when you have enough; no overplanning; outcome-first | **[pf] ✓ primary** | shipped | `direct-answers`, `autonomous-execution` |
+| Pause only when genuinely needed | **[pf] ✓ primary** | shipped | `no-cheap-questions` |
+| No over-refactor / minimal diff (at higher effort) | **[pf] ✓ primary** | shipped | `minimal-safe-diff` |
+| Parallel async subagents, dispatched readily | **[pf] ✓ primary** | default async dispatch | extend `subagent-orchestration` |
+| Fresh-context verifier beats self-critique (for **long-running** tasks) | **[pf] ✓ primary** | verifier subagent on a **structural-complexity** gate (not blanket) | extend `adversarial-review` |
+| Persistent **cross-run** notes (file memory = 3× vs Opus 4.8 on Slay the Spire) | **[an] ✓ primary (direct)** | lessons across runs, one per file | extend memory / `memory-consolidation` |
+| Infer the underlying goal (standard host only) | **[an] testimonial (Lovable); direction note** | infer goal, give **one** recommendation — NO "2–3 framings"; standard host only (a strong-reasoning host self-infers) | extend `improve-before-implement` |
+| Multi-hypothesis / "killing incorrect beliefs" | **[an] testimonial (Sean Ward); "multi-hypothesis" is our framing** | hypotheses + killed-beliefs in the notes file | `notes-first-reasoning` |
+| Adaptive effort (depth scales with hardness) | **[in],[pf] = API knob, not a scaffold** | strong-reasoning host: set `effort: high`; standard host w/o the knob: scaffold the effort/stop discipline | extend `autonomous-execution` (standard-host-only) |
+| Explore the environment first, then build | **[cr] third-party (NOT Anthropic-documented)** | enumerate constraints/tools/info-gaps, close by query/test before designing | extend `think-before-action` |
+| Risk-first decomposition (hardest/load-bearing unknown first) | **OUR DERIVATION — general engineering discipline, NOT Fable-documented** ([pf]'s "top of difficulty range" means **task selection**, not intra-task order) | resolve load-bearing uncertainties before dependent work | new skill `complexity-first-planning` |
+
+Adopted from GPT review (frontier-implicit behaviors; our adoption, corroboration
+only — all cost-gateable notes components):
+
+| Behavior | Source | Transplant | Carrier |
+|---|---|---|---|
+| Prediction tracking (calibration) | GPT review | prediction + confidence + result + lesson in notes | `notes-first` component `prediction_tracking` |
+| Uncertainty budget | GPT review | per-dimension uncertainty score → feeds adaptive effort | `notes-first` component `uncertainty_budget` |
+| Decision ledger | GPT review | decision + alternatives + reason + revisit-if in notes; **escalates to `decision-record`/ADR** when cross-task or structural | `notes-first` component `decision_ledger` |
+
+The ordered chain the orchestrator enforces:
+`ground → intent → notes → gather → audit → verify`.
+
+## Deferred to the Phase-8 audit (likely already covered)
+
+Two transferable [pf] behaviors are **not** given new artifacts up front — the
+Phase-8 de-prescriptivize audit checks existing coverage first and adds only
+verified gaps (HIGH priority):
+
+- **Re-ground the final summary** — write the closing summary for a reader who
+  saw none of the working thread; outcome first; drop working shorthand. Likely
+  covered by `language-and-tone` + `direct-answers`.
+- **Report findings and stop** — when the user is thinking out loud, don't apply
+  a fix. Likely covered by `scope-control`.
+
+## What does NOT transfer (and must not be faked)
+
+- **Raw capability** — vision SOTA, document/chart reasoning, codebase-scale
+  migrations. Benchmark deltas (e.g. SWE-Bench Pro 80.3 vs 69.2) are **[ve]
+  third-party**, not verifiable in Anthropic prose — label third-party or pull to
+  the system card; note "SWE-Bench Pro" is not named in [an] (which cites
+  FrontierCode/Cognition + Hebbia-Finance). These are weights, not prompts.
+- **"Show your work" in the response.** [pf] warns that reasoning-in-response can
+  trigger a `reasoning_extraction` refusal, and that over-prescriptive skills
+  *degrade* strong models. **Both verbatim in [pf] — the gating foundation.** RDP
+  keeps reasoning in notes + verifier subagents, never in the response, and
+  tier-gates prescription.
+- **Pokémon FireRed vision-only harness** — **[an] only** ([pf] does not mention
+  it).
+
+## Cost / benefit by host reasoning strength (the gating lens)
+
+RDP is **not** free — scaffolding costs tokens and, on strong-reasoning hosts,
+*degrades* output. So it engages only where it pays, via **table-free** signals.
+Per **ADR-035** the suite maintains no runtime model→band table, and `model_tier`
+is the *skill's* needed band (lite/medium/high), **not** the host's. Host strength
+is therefore **agent self-assessed**, never looked up (roadmap L10/L17):
+
+| Host / task | Self-coordination | RDP engagement | Why |
+|---|---|---|---|
+| standard host | low | **full** scaffolding | biggest discipline gap → biggest lift |
+| strong-reasoning host | high | **light / off** (use native `effort: high`) | over-scaffolding degrades + wastes tokens |
+| trivial / short task (any host) | n/a | **off** | no discipline gap to close; pure overhead |
+| verifier subagent (any host) | — | **only** on the structural-complexity gate (≥2 of: branching, ≥3 constraints, stateful, irreversibility) + token floor ≥1k | a full extra inference pass — the most expensive primitive |
+
+**One** constraint-light scaffold ships — no heavy/light content variants, since
+two variants would be a hidden model→band table. A standard host **expands it on
+request**. Two gates, both default-on: automatic (task signal + agent
+self-assessment) + the user `reasoning:` settings toggle (global + per-component
++ hard off).
+
+## Notes template grounding
+
+The session-notes template is grounded in Anthropic's **documented cross-run
+lessons memory** [pf] (one lesson per file; corrections + confirmed approaches;
+why they mattered). The in-task sections (`## In-Task Hypothesis Log`,
+`## Predictions`, `## Decisions`, `## Uncertainty`) are a clearly-marked **local
+derivation** for within-task scope — useful, but not claimed as Anthropic-
+documented, and kept on the notes side of the `reasoning_extraction` line.
+
+## Naming
+
+Neutral, no brand/capability claim. Umbrella: **Reasoning Discipline Protocol
+(RDP)**. Artifacts: `reasoning-orchestrator`, `notes-first-reasoning`,
+`complexity-first-planning`, `environment-grounding`. "Fable" / "Mythos" never
+appear in an artifact identifier.
+
+[an]: https://www.anthropic.com/news/claude-fable-5-mythos-5
+[pf]: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5
+[in]: https://platform.claude.com/docs/en/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5
+[ve]: https://www.vellum.ai/blog/claude-fable-5-and-mythos-5-benchmarks-explained
+[re]: https://www.reuters.com/technology/us-blocks-foreign-access-anthropics-most-advanced-ai-models-axios-reports-2026-06-13/
+[cr]: https://www.coderabbit.ai/blog/fable-5-model-review
+[lam]: https://www.interconnects.ai/p/claude-fable-5-and-new-ai-safety

package/docs/guidelines/agent-infra/inversion-thinking.md

@@ -385,4 +385,4 @@ Before any plan, do 15-minute pre-mortem:
 
 ## ADOPT citation
 
-Adopted from [`ginobefun/deep-reading-analyst-skill`](https://github.com/ginobefun/deep-reading-analyst-skill) @ commit `26cd7dc9` · `src/deep-reading-analyst/references/inversion_thinking.md` · MIT License.
+Adapted from an external reference.