@event4u/agent-config 4.8.0 → 5.0.0

package/docs/benchmark.md

@@ -4,12 +4,14 @@
 
 ## Headline
 
+> **Track A confirms surface availability** — a precondition, not an impact metric. For the impact view (cost-ladder + behaviour with vs. without), see [`docs/value.md`](value.md).
+
 | Metric | with | without | delta |
 |---|---|---|---|
-| Track A trigger-accuracy | 100.0% | 0.0% | 100.0% |
-| Track B completion-rate  | — | — | 0.0% |
-| Track B mean wall-time   | —s | —s | 0.00s |
-| Track B ask-vs-act ratio | — | — | — |
+| Track A surface-availability | 100.0% | 0.0% | 100.0% _(structural — files present)_ |
+| Track B completion-rate  | 0.0% | 0.0% | 0.0% |
+| Track B mean wall-time   | 0.00s | 0.00s | 0.00s |
+| Track B ask-vs-act ratio | 0.000 | 0.000 | — |
 
 ## Track A — Behavioural eval
 
@@ -33,9 +35,19 @@ Per-target presence (sample):
 
 ## Track B — Task completion
 
-- Mode: `—`
+- Mode: `dry-run`
+- with → **0.0%** (0/13)
+- without → **0.0%** (0/13)
+
+Per-category:
 
-_No Track B reports yet. Run `task bench:ab:track-b`._
+| Category | with | without | delta |
+|---|---|---|---|
+| bugfix | 0.0% | 0.0% | 0.0% |
+| feature | 0.0% | 0.0% | 0.0% |
+| refactor | 0.0% | 0.0% | 0.0% |
+| testadd | 0.0% | 0.0% | 0.0% |
+| uiaudit | 0.0% | 0.0% | 0.0% |
 
 ## Methodology
 
@@ -50,7 +62,7 @@ Cache key for the latest run:
 - `claude_cli_version`: `2.1.150 (Claude Code)`
 - `target_shape_hash`: `3f2f67cebfbb5fff`
 
-- **Last rendered:** `2026-05-26T15:33:46+00:00`
+- **Last rendered:** `2026-05-28T13:55:30+00:00`
 
 ## History
 
@@ -62,4 +74,4 @@ Last 5 runs (per corpus):
 
 ### `ab-trackb`
 
-_no runs yet_
+- `2026-05-28T13-47-41Z` → 0.0%

package/docs/benchmarks.md

@@ -19,6 +19,8 @@ discipline (upstream `5b71c7a`).
 |---|---|---|
 | `dev` | `tests/eval/corpus-dev.yaml` | router / engine selection |
 | `telegraph` | `internal/bench/corpora/telegraph/prompts.yaml` | condensation dialect (`vs_raw` + `vs_terse`) |
+| `rtk` | `internal/bench/corpora/rtk/commands.yaml` | rtk CLI-output filtering savings (Phase 2 of `road-to-readable-value-dashboard.md`) |
+| `value` | _derived_ | aggregated dashboard — no own corpus, reads from the others |
 
 ## Reports — naming and trail
 
@@ -39,11 +41,20 @@ one without the other.
 | Edit to `scripts/bench_run.py` `--telegraph` arm | `telegraph` | report refreshed in same PR |
 | Edit to `internal/bench/corpora/telegraph/prompts.yaml` | `telegraph` | report refreshed, version bumped (`telegraph-vN+1`) |
 | Edit to `scripts/_lib/bench_telegraph*.py` | `telegraph` | report refreshed in same PR |
+| Edit to any rung source (frugality / telegraph / rtk / A/B) | `value` | `task value` re-renders `docs/value.md` in same PR |
+| Edit to `internal/bench/corpora/rtk/commands.yaml` | `rtk` | `scripts/bench_rtk_savings.py` refreshed in same PR |
+| Edit to `dist/router.json` or any rule frontmatter `triggers:` | `router-telemetry` | `task value:telemetry:replay` refreshes attribution map; required before any Phase 4 / Phase 5 cut |
 
 A PR that touches any of the cadence triggers without refreshing the
 corresponding report is rejected by reviewer convention (no CI gate yet
 — the trigger surface is too small to warrant one).
 
+## Cost envelope (`rtk` corpus)
+
+8 commands × 2 arms (raw vs. rtk-filtered) = 16 local shell invocations
+per run. Zero API spend — pure local measurement. Wall-time ≈ 5–10 s on
+the maintainer's repo (`scripts/bench_rtk_savings.py --quiet`).
+
 ## Cost envelope (`telegraph` corpus)
 
 10 prompts × 3 arms (`condensed` · `terse-control` · `uncondensed`) = 30

package/docs/contracts/benchmark-corpus-spec.md

@@ -45,12 +45,35 @@ corpus_id: <id>                         # short kebab-case identifier
 selection_accuracy_target: 0.60         # 0.0–1.0; runner exits non-zero below
 prompts:
   - id: <bucket>-<NN>                   # e.g. canonical-01, ambiguous-03
-    category: <bucket>                  # canonical | ambiguous | destructive | long-context
+    category: <bucket>                  # canonical | ambiguous | destructive | long-context | router-coverage
     user_type_candidates: [<slug>, ...] # optional; informational
     language: en                        # en | de — per language-and-tone
     prompt: "<text>"                    # the agent-facing prompt
     expected_skills: [<slug>, ...]      # ≥ 1 entry; non-empty
     expected_carve_outs: [<slug>, ...]  # required when category == destructive
+    intended_triggers: [<rule_id>, ...] # router-telemetry attribution — rule ids the
+                                        # corpus author expects to activate AND that the
+                                        # deterministic replay can verify (keyword / phrase
+                                        # / command / path with supplied open_files or
+                                        # command context). Replay checks intended vs
+                                        # observed; drift surfaces as a finding, not
+                                        # silently. OPTIONAL on non-router-coverage corpora.
+                                        # (Council R3 honesty floor — pass-3 onwards.)
+    replay_opaque_triggers: [<rule_id>, ...] # rule ids the author expects to fire at
+                                        # RUNTIME but only via an `intent` trigger (or a
+                                        # router coverage gap) the static replay cannot
+                                        # see. Reported separately by the telemetry — NOT
+                                        # counted as missed_intended (would be false drift)
+                                        # nor as unintended_activations. A rule may sit in
+                                        # at most one bucket. router-coverage tasks need at
+                                        # least one of {intended_triggers,
+                                        # replay_opaque_triggers} non-empty.
+    open_files: [<path>, ...]           # optional — paths the agent has "open" when
+                                        # the prompt fires. Used to drive `path_prefix`
+                                        # and `file_pattern` triggers in router replay.
+    command: "<slash-command>"          # optional — exact command invoked (e.g.
+                                        # `/roadmap:process-step`). Drives `command:`
+                                        # triggers in router replay.
     rubric:                             # optional structural assertion
       must_include: ["<phrase>", ...]   # all phrases must appear in output
       must_not_include: ["<phrase>", ...]
@@ -67,12 +90,17 @@ prompts:
 | `selection_accuracy_target` outside `[0.0, 1.0]` | `target_out_of_range` | `1.5` |
 | Duplicate `id` across prompts | `duplicate_id` | two `canonical-01` |
 | `id` does not match `^[a-z][a-z0-9-]*-\d{2}$` | `bad_id_format` | `Canonical_1` |
-| `category` not in `{canonical, ambiguous, destructive, long-context}` | `bad_category` | `category: misc` |
+| `category` not in `{canonical, ambiguous, destructive, long-context, router-coverage}` | `bad_category` | `category: misc` |
 | `language` not in `{en, de}` | `bad_language` | `language: fr` |
-| `expected_skills` empty / missing | `empty_expected` | `expected_skills: []` |
+| `expected_skills` empty / missing (**except `category == router-coverage`**, which tests trigger activation, not skill selection) | `empty_expected` | `expected_skills: []` |
 | `expected_skills` references an unknown skill slug | `unknown_skill` | `expected_skills: [imaginary]` |
 | `category == destructive` without `expected_carve_outs` | `missing_carve_out` | — |
 | Prompt text empty / whitespace-only | `empty_prompt` | — |
+| `intended_triggers` / `replay_opaque_triggers` references a rule that doesn't exist in `dist/router.json` | `unknown_intended_trigger` | `intended_triggers: [no-such-rule]` |
+| `intended_triggers` present but not a list | `bad_intended_triggers_shape` | `intended_triggers: foo` |
+| `replay_opaque_triggers` present but not a list | `bad_replay_opaque_triggers_shape` | `replay_opaque_triggers: foo` |
+| Same rule id in both `intended_triggers` and `replay_opaque_triggers` | `trigger_in_both_buckets` | `intended:[x]` + `opaque:[x]` |
+| `category == router-coverage` with **both** `intended_triggers` and `replay_opaque_triggers` empty/absent | `missing_intended_triggers` | — |
 
 The linter MUST run with `--quiet` honour per the script-output
 convention and emit one violation per line in non-quiet mode.

package/docs/contracts/command-surface-tiers.md

@@ -105,7 +105,7 @@ unless `--tier=all`. Reachable by full name; not advertised.
    `context-hygiene:hook`, `hooks:install`, `hooks:status`).
 2. **Internal / programmatic.** Called by other scripts or by the
    work-engine, never typed by a human (`memory:*`,
-   `proposal:check`, `refine-ticket:detect`, `migrate-state`,
+   `proposal:check`, `refine-ticket:detect`,
    `telemetry:*`, `mcp:render`, `mcp:check`, `mcp:setup`,
    `mcp:run`, `roadmap:progress-check`).
 3. **Sub-command of a slash orchestrator** — the orchestrator is

package/docs/contracts/hook-architecture-v1.md

@@ -250,6 +250,39 @@ the flag are listed by `./agent-config hooks:doctor` as not
 replay-safe; replay tests assert no `agents/runtime/state/` mutation
 post-invocation.
 
+## Regenerator location — canonical path (Phase 3 of `road-to-hooks-actually-fire-in-consumers`)
+
+The `roadmap-progress` concern's resolver searches three locations
+for `update_roadmap_progress.py`. The **canonical consumer-side
+location is**:
+
+```
+<consumer_root>/.augment/scripts/update_roadmap_progress.py
+```
+
+Rationale:
+
+- The auto-generated `agents/roadmaps-progress.md` already cites
+  `.augment/scripts/update_roadmap_progress.py` in its header.
+- `install.py`'s existing tool projection lays down `.augment/`
+  unconditionally; piggy-backing on that directory means consumers
+  do not need a separate "scripts" install step.
+- The other two paths (`.agent-src/scripts/`,
+  `.agent-src.uncondensed/scripts/`) only populate in
+  source-checkouts of the package itself.
+
+Source-of-truth in the package: `packages/core/.agent-src.uncondensed/scripts/update_roadmap_progress.py`.
+Helper that copies source → consumer canonical:
+`scripts/_lib/install_regenerator.py`. Consumed by `install.py` and
+`hooks:install --regen`.
+
+The resolver in `scripts/roadmap_progress_hook.py::_resolve_regenerator`
+visits the canonical path FIRST; the other two are fallback for
+maintainer / dev workflows. On `return None` the resolver writes a
+`dispatch-issues.jsonl` entry (Phase 1 contract) with
+`prerequisite_missing` so the user can discover the gap via
+`./agent-config hooks:doctor`.
+
 ## Stability
 
 Beta. Breaking changes between v1 and v2 are allowed in a minor

package/docs/contracts/migrate-command.md

@@ -0,0 +1,197 @@
+# `agent-config migrate` — Behavior Contract
+
+> **Status:** active · **Owner:** maintainer (`scripts/_cli/cmd_migrate.py`) · **Opened:** 2026-05-29
+>
+> Source: `road-to-one-migrate-command.md` Phase 1. Locks the union of
+> cleanup actions performed by the unified `./agent-config migrate`
+> command and codifies the **deletion-over-migration** policy: the
+> wizard recreates fresh project config, so legacy project-local state
+> is hard-deleted rather than preserved or relocated.
+
+## Design intent
+
+One opinionated command runs every cleanup step end-to-end. No flag
+matrix to pick between behaviors, no surprises. The single flag is
+`--dry-run` (preview vs. apply). The legacy three-command surface —
+`migrate`, `migrate-state`, `migrate-to-global` — is collapsed into
+one entry point.
+
+Rationale:
+
+- **One mental model.** The legacy split forced the user to remember
+  which slice each command performed. A single opinionated command
+  removes that cognitive load.
+- **Deletion over preservation.** The new wizard
+  (`agent-config setup`) recreates fresh project / global config on
+  next run. Preserving stale `.agent-settings.yml` only carries
+  forward old values the user already chose to leave behind.
+- **No setup-migration.** Project-local config is deleted; global
+  config is recreated fresh by the wizard. Different paths into the
+  same end state, but the deletion path requires no decisions from
+  the agent at migrate time.
+
+## Input signals — what counts as "needs migration"
+
+The command considers a consumer repo migratable when **any** of
+these are detected. The full set is the disjunction below; any one
+hit triggers the apply path.
+
+| # | Signal | Source |
+|---|---|---|
+| 1 | `@event4u/agent-config` entry in `package.json` `dependencies` or `devDependencies` | npm install era |
+| 2 | `event4u/agent-config` entry in `composer.json` `require` or `require-dev` | Composer install era |
+| 3 | Managed symlink (`.augment`, `.claude`, `.cursor`, `.clinerules`, `.windsurfrules`) pointing into `vendor/` or `node_modules/` | composer / npm install layout |
+| 4 | `.implement-ticket-state.json` file present at project root (v0 work-engine state) | pre-v1 engine schema |
+| 5 | `.agent-settings.yml` at project root (legacy project-local config) | pre-global-only consumer surface |
+| 6 | `.agent-user.yml` at project root (legacy project-local user prefs) | pre-global-only consumer surface |
+| 7 | `settings/.agent-settings.yml` or `settings/.agent-user.yml` (typed-subdir variant) | pre-global-only typed-subdir layout |
+| 8 | Empty `agent-config/` shell directory at project root | leftover from removed `composer/npm` install |
+
+The detector returns "already migrated" (exit 0, no writes) when
+none of the signals fire.
+
+## Output state — what the consumer looks like post-migration
+
+After `./agent-config migrate` (real apply) returns 0, the consumer
+repo carries **none** of these:
+
+- ❌ `@event4u/agent-config` in `package.json` (`dependencies` or
+  `devDependencies`); the section is removed if it becomes empty.
+- ❌ `event4u/agent-config` in `composer.json` (`require` or
+  `require-dev`); the section is removed if it becomes empty.
+- ❌ Managed symlinks pointing into `vendor/` or `node_modules/`.
+- ❌ `.implement-ticket-state.json` at the project root; if v0
+  payload was present, it is migrated to `.work-state.json` and the
+  v0 source is renamed `.implement-ticket-state.json.bak`. If no v0
+  payload existed (file absent), nothing is written.
+- ❌ Project-root `.agent-settings.yml` (hard-deleted).
+- ❌ Project-root `.agent-user.yml` (hard-deleted).
+- ❌ `settings/.agent-settings.yml` and `settings/.agent-user.yml`
+  (hard-deleted; the `settings/` directory is removed if it becomes
+  empty).
+- ❌ Empty `agent-config/` shell at the project root.
+
+The `.gitignore` block is refreshed to the canonical shape
+documented in `scripts/_cli/cmd_migrate.py::GITIGNORE_NEW_BODY`.
+
+## Action order — opinionated, fixed
+
+Apply path is deterministic — re-running the same input yields the
+same diff. Order is foundation-first so that earlier steps cannot
+break detection for later ones:
+
+1. **Detect** legacy signals from the matrix above; collect every
+   action that would fire.
+2. **Strip** `composer.json` / `package.json` package entries
+   in-place (preserves sibling keys + 2-space indent + trailing
+   newline).
+3. **Purge** managed symlinks whose target points into `vendor/` or
+   `node_modules/`. User-managed symlinks pointing elsewhere are
+   preserved with a warning.
+4. **Migrate state** — if `.implement-ticket-state.json` carries a
+   v0 payload, rewrite to `.work-state.json` and rename the v0
+   source to `.implement-ticket-state.json.bak`. If the file is
+   absent or already v1-shaped, skip.
+5. **Hard-delete** legacy project-local config files:
+   - `.agent-settings.yml` (project root)
+   - `.agent-user.yml` (project root)
+   - `settings/.agent-settings.yml` (typed-subdir variant)
+   - `settings/.agent-user.yml` (typed-subdir variant)
+   - `settings/` directory itself if empty after the YAML removals.
+6. **Remove** the empty `agent-config/` shell directory at the
+   project root, if present and empty.
+7. **Refresh** the `.gitignore` agent-config managed block to the
+   canonical shape.
+8. **Summarize** — print every action taken, one per line, with a
+   leading bullet.
+
+## `--dry-run` semantics
+
+- Same detection + summary as the apply path.
+- **Zero filesystem mutations** — no file created, modified, or
+  deleted; no symlink removed; no directory removed.
+- Exit codes match the apply path: `0` for "nothing to migrate"
+  and `0` for "would migrate these N actions".
+- Non-zero only on detection errors (unreadable file, invalid JSON
+  in `composer.json` / `package.json`, etc.).
+- The summary is prefixed with `would` instead of past-tense verbs
+  so log scraping can distinguish dry-run from real runs.
+
+## Idempotency contract
+
+Re-running on a fully-migrated consumer:
+
+1. Detector fires zero hits (every signal in the matrix is absent).
+2. Command prints `✅  already migrated — nothing to do.`
+3. Exits `0`.
+4. **No filesystem mutation occurs** — including on `--dry-run`.
+
+A partial migration (e.g., a previous run crashed between steps 3
+and 4) re-runs each remaining step on the next invocation. The
+apply order is chosen so partial state never poisons detection of
+the next pending action.
+
+## Excluded — what `migrate` does NOT do
+
+These cleanup actions exist elsewhere in the package today but are
+intentionally **outside** the unified `migrate` command:
+
+| Action | Where it lives instead | Why excluded |
+|---|---|---|
+| Lift project-local YAML into `~/.event4u/agent-config/` | wizard (`agent-config setup`) | New global config is created fresh by the wizard; preserving stale values defeats the deletion-over-migration policy. |
+| Write a fresh `.agent-settings.yml` | wizard (`agent-config setup`) | Same as above — the wizard is the source of truth for new project config. |
+| Run the perms gate (`lint_global_paths.py`) | `agent-config doctor` | Migration deletes project-local state; the perms audit is a separate diagnostic on the global tree. |
+| `.legacy-pre-global-only/<stamp>/` snapshot | (removed) | Snapshot-and-rollback was a `migrate-to-global` semantic. The deletion path needs no snapshot — git history is the rollback surface. |
+| `agents/.event4u-bridge.yml` bridge marker write | `install.py` | Bridge marker is an install-time artefact, not a migration concern. |
+| `settings:migrate` (read-only copy of project YAML into global) | (removed; superseded by wizard) | The read-only copy was a stepping stone for the destructive move. With the deletion policy, neither step survives. |
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Migration complete, or nothing to migrate (already migrated), or `--dry-run` plan computed. |
+| `1` | Detection error — unreadable file, invalid JSON in `composer.json` / `package.json`, work-engine v0 → v1 conversion error. |
+| `2` | Unused (reserved). |
+
+The apply path never exits non-zero on a partial-migration recovery
+— a step that fires its predicate is allowed to complete cleanly
+even if a sibling step's predicate is already satisfied.
+
+## Test surface
+
+`tests/migrate/test_unified_migrate.py` covers, against a fixture
+consumer dir under `tests/fixtures/migrate/`:
+
+- **Full apply** — fixture carries every input signal; assert each
+  output-state predicate holds post-run; summary lists each action.
+- **`--dry-run`** — same fixture, assert zero filesystem mutations
+  (snapshot dir tree before and after; bit-identical).
+- **Idempotency** — run twice; assert second run is the
+  "already migrated" no-op.
+
+## Rollback
+
+Restoring the previous command surface:
+
+1. Restore the previous `scripts/_cli/cmd_migrate.py` from git
+   history.
+2. Restore `scripts/_cli/cmd_migrate_to_global.py`,
+   `cmd_migrate_state()` / `cmd_migrate_to_global()` in
+   `scripts/_dispatch.bash`, and the corresponding registry entries
+   in `src/cli/registry.ts`.
+3. Delete this contract doc.
+4. Restore `scripts/_cli/cmd_settings_migrate.py` if also removed
+   (note: this command was originally cited only as a discussion
+   item in Phase 1 cross-check; see "Excluded" table above).
+
+## See also
+
+- `road-to-one-migrate-command.md` — the roadmap this contract
+  realizes.
+- `road-to-global-only-install.md` — the predecessor roadmap that
+  shipped `migrate-to-global`; superseded by this contract.
+- `road-to-portable-runtime-and-update-check.md` § P3.5–P3.6 — the
+  original `migrate` command (composer / npm cleanup).
+- `scripts/_cli/cmd_migrate.py` — implementation.
+- `.agent-src/templates/scripts/work_engine/migration/v0_to_v1.py`
+  — state-file migration helper invoked from step 4.

package/docs/contracts/settings-api.md

@@ -175,7 +175,8 @@ project-local `.agent-user.yml` / `.agent-settings.yml` into
 `~/.event4u/agent-config/`. Idempotent — refuses to overwrite a
 non-empty global file without `--force`. Order matches Phase 5
 amendment A2 (`copy → verify`; the destructive `move` step is owned by
-`migrate-to-global`, not this subcommand).
+the unified `agent-config migrate` command, not this subcommand — see
+`docs/contracts/migrate-command.md`).
 
 Flags: