@event4u/agent-config 5.6.1 → 5.8.0

package/.agent-src/skills/prediction-pool-optimizer/reference/odds-and-bonus.md

@@ -0,0 +1,109 @@
+# Odds aggregation + bonus-question taxonomy
+
+Lookup material for `prediction-pool-optimizer`. Two parts:
+
+- **A — Multi-book consensus**: which books to read, how to weight them, how
+  to fold them into one calibration probability.
+- **B — Bonus / award / special questions**: a type → method table so every
+  open question in the pool reaches an answer.
+
+Not betting advice; how to read a public market as a probability prior for a
+fun pool.
+
+---
+
+## A. Multi-book consensus — read several, weight by sharpness
+
+### Why not one book
+
+A single bookmaker's line can be stale, regionally shaded, or carry a fat
+margin. A consensus across several books is a far better probability estimate,
+and cross-book agreement tells you the market's confidence. **Never mirror one
+portal.**
+
+### Which books (5–10, publicly viewable)
+
+Availability varies by region and over time — this list is **illustrative,
+refresh it at run time** and use whatever is publicly viewable from the current
+locale. Fastest way to see many at once = an **odds-comparison aggregator**:
+
+- **Aggregators (many books on one page):** Oddschecker, Oddsportal,
+  Betexplorer, OddsAlert.
+- **Sharp / low-margin reference books (weight higher):** Pinnacle, Betfair
+  Exchange (an exchange = closest thing to a true market price).
+- **Large recreational books (weight lower):** bet365, Bwin, William Hill,
+  Unibet, Betano, Tipico, Interwetten, bet-at-home, 888sport, Winamax.
+
+Aim for **5–10** spanning both groups. If only recreational books are viewable,
+say so in the run note — the consensus is then softer.
+
+### The recipe
+
+1. **Per market, per book**: collect decimal odds (1X2, exact-score, each
+   outright, each special/award market a bonus question needs).
+2. **De-vig each book independently.** For 1X2 decimal odds `o_H, o_D, o_A`,
+   raw implied probs `1/o` sum to `>1` (overround); normalise:
+   `p_i = (1/o_i) / Σ(1/o)`. Per book — never aggregate raw odds.
+3. **Sharpness-weight and combine.** Sharp books > recreational; **weighted
+   mean** — or **trimmed median** when books disagree a lot (robust to one
+   outlier). A defensible weighting:
+
+   - Pinnacle / Betfair Exchange → weight 3
+   - large recreational books → weight 1
+   - aggregator "average" column → weight 1 (already blends many)
+
+   `p_consensus = Σ(wᵢ · pᵢ) / Σwᵢ` per outcome, then re-normalise the outcome
+   set to sum to 1.
+4. **Outlier handling.** One book far off the others = **flag, not truth**:
+   check for a reason (priced-in injury, stale line) before moving the
+   consensus. Cross-book agreement = signal; one disagreeing book = investigate.
+5. **Healthy weighting overall.** The consensus is a **prior**. Blend it with
+   the per-sport model (Poisson / Gaussian) and override only with *current*
+   info the market has not absorbed (confirmed lineup, late injury,
+   suspension, manager change). The pool answer is EV under the rules on top of
+   this blended probability — the market informs, it does not dictate.
+
+### Worked mini-example (1X2)
+
+Two books, home/draw/away decimal odds:
+
+- Book S (sharp, w=3): 1.80 / 3.60 / 4.50 → raw 0.556/0.278/0.222 (sum 1.056)
+  → de-vig 0.526/0.263/0.210
+- Book R (recreational, w=1): 1.75 / 3.50 / 4.20 → raw 0.571/0.286/0.238
+  (sum 1.095) → de-vig 0.522/0.261/0.217
+
+Weighted mean (3:1), per outcome, then renormalise:
+≈ **Home 0.525 / Draw 0.262 / Away 0.212**. That is the calibration base for
+the per-match EV grid — not either book's raw number.
+
+---
+
+## B. Bonus / award / special questions — type → method
+
+Every entry on the step-1 checklist gets an answer. Match the question to a
+row; real market where one exists, a **labelled** model estimate where none
+does. Optimize each on expected points under its point weight.
+
+| Question type | Example | Method |
+|---|---|---|
+| **Outright winner** | "Who wins the tournament?" | Outright "to win" market, consensus per A; or `poisson_sim.py` `title_pct`. EV-max under the question's points. |
+| **Group / stage** | "Who wins group X?", "Who advances?" | "To win group" / "to qualify" markets; or `advance_pct` from the simulator. |
+| **Finalists / matchup** | "Who reaches the final?" | "To reach final" market per team; simulator pairing is approximate — prefer the market. |
+| **Top scorer (player)** | "Tournament top scorer?" | "Top goalscorer" outright market, consensus per A; EV-max player (favourite unless rarity scoring rewards a longer shot). |
+| **Team of the top scorer** | "Which team supplies the top scorer?" | Aggregate per-player top-scorer probabilities **by team** (sum each squad); pick the highest-summed team. |
+| **Most assists / cards / etc.** | "Most yellow cards?" | Matching special market if offered; else a labelled model estimate (discipline/aggression proxy). |
+| **Binary special** | "Will there be a red card in match X?" | De-vig the yes/no line to a probability; EV-max side under the points. No market → labelled base-rate estimate. |
+| **Over / under total** | "Over/under total goals / cards?" | De-vig the totals line at the offered threshold; higher-EV side. |
+| **Exact stat** | "How many goals in the final?" | Market totals distribution if available; else per-match Poisson on consensus xG. State the model. |
+
+### Rules for bonus answers
+
+- **Answer all of them.** The output's bonus table must have the same number
+  of rows as the step-1 checklist. A missing row = a dropped question.
+- **Market first, labelled model second.** Prefer a real special market; none
+  exists → derive from a stated model and mark `Source: model`.
+- **Rarity rules apply here too.** Under quote/rarity scoring, a
+  plausible-but-rarer answer can out-score the favourite when
+  `payout × probability` is higher — same EV logic as the scores.
+- **No hallucinated numbers.** Outright/award probabilities come from real
+  markets or the executed simulator — never a claimed-but-unrun simulation.

package/.agent-src/skills/rtk-output-filtering/SKILL.md

@@ -1,5 +1,5 @@
 ---
-model_tier: inherit
+model_tier: medium
 name: rtk-output-filtering
 description: "Use when running verbose CLI commands — wraps them with rtk (Rust Token Killer) for 60-90% token savings. Covers installation, configuration, and usage patterns."
 domain: process

package/.agent-src/skills/script-writing/SKILL.md

@@ -1,5 +1,5 @@
 ---
-model_tier: inherit
+model_tier: medium
 name: script-writing
 description: "Use when adding or editing any script under `scripts/` — `--quiet` flag, `_lib/script_output` helpers, silent Taskfile wiring, Iron-Law carve-outs — even when you just say 'add a check script for X'."
 domain: process

package/.agent-src/skills/token-optimizer/SKILL.md

@@ -1,5 +1,5 @@
 ---
-model_tier: inherit
+model_tier: medium
 name: token-optimizer
 description: "Use BEFORE any verbose CLI run, large file read, doc conversion, or near-context handoff — single decision tree keyed by intent that cites the canonical token-saving asset. Consult before the action."
 domain: process

package/.agent-src/skills/using-git-worktrees/SKILL.md

@@ -1,5 +1,5 @@
 ---
-model_tier: inherit
+model_tier: medium
 name: using-git-worktrees
 description: "Use when starting parallel work in isolation from the current branch — spawn a git worktree with ignore-safety checks and a clean test baseline — even when the user says 'try this on the side'."
 domain: process

package/.agent-src/templates/agent-settings.md

@@ -6,7 +6,7 @@ settings.
 
 ## File format
 
-**YAML**, with a single top-level scalar (`cost_profile`) plus one level of
+**YAML**, with a single top-level scalar (`rule_loading_tier`) plus one level of
 grouped sections (`personal`, `project`, `github`, `eloquent`, `pipelines`,
 `subagents`). Comments with `#`.
 
@@ -57,7 +57,7 @@ made by the user directly or by the agent on request, following the
 #            highest token cost. Pick this when working on agent-config
 #            itself or when you need every behavioural rule active.
 # custom   = ignore profile — every matrix value must be set explicitly.
-cost_profile: balanced
+rule_loading_tier: balanced
 
 # --- Personal preferences ---
 personal:
@@ -132,7 +132,7 @@ eloquent:
 # agent session can be resumed. See scripts/chat_history.py for the API.
 #
 # Defaults below are placeholders — scripts/install.py substitutes them
-# per cost_profile (see config/profiles/*.ini).
+# per rule_loading_tier (see config/profiles/*.ini).
 chat_history:
   # Log chat events to disk (true, false)
   enabled: true
@@ -199,7 +199,7 @@ pipelines:
   # Skill improvement pipeline (true, false)
   # true  = after meaningful tasks, propose learning capture and improvements (default)
   # false = silent, no post-task analysis
-  # Included by every cost_profile except `custom`.
+  # Included by every rule_loading_tier except `custom`.
   skill_improvement: true
 
 # --- Roadmap execution ---
@@ -460,7 +460,7 @@ the canonical narrative lives in
 
 | Key path | Values | Default | Description |
 |---|---|---|---|
-| `cost_profile` | `minimal`, `balanced`, `full`, `custom` | `minimal` | Selects which agent surfaces are active. See [Cost profiles](#cost-profiles). |
+| `rule_loading_tier` | `minimal`, `balanced`, `full`, `custom` | `minimal` | Selects which agent surfaces are active. See [Cost profiles](#cost-profiles). |
 | `personal.ide` | `code`, `phpstorm`, `cursor` | _(empty)_ | CLI command to open files in the IDE |
 | `personal.open_edited_files` | `true`, `false` | `false` | Auto-open edited files in the IDE after edits |
 | `personal.user_name` | first name | _(empty)_ | User's first name, used to address the user personally. Captured by `/onboard`. |
@@ -527,7 +527,7 @@ Applied automatically when `scripts/install` finds a legacy `.agent-settings`
 
 | Legacy flat key | New YAML path |
 |---|---|
-| `cost_profile` | `cost_profile` |
+| `rule_loading_tier` | `rule_loading_tier` |
 | `ide` | `personal.ide` |
 | `open_edited_files` | `personal.open_edited_files` |
 | `user_name` | `personal.user_name` |
@@ -550,7 +550,7 @@ so nothing is silently dropped; the migration log points them out.
 
 ## Cost profiles
 
-The `cost_profile` setting selects which agent surfaces are active. See
+The `rule_loading_tier` setting selects which agent surfaces are active. See
 `docs/customization.md` for the authoritative description.
 
 | Profile | Description |

package/.agent-src/templates/agents/agent-project-settings.example.yml

@@ -7,7 +7,7 @@
 # Precedence (lowest → highest):
 #   1. Package defaults (shipped by event4u/agent-config)
 #   2. ~/.event4u/agent-config/agent-settings.yml — user-global DX-comfort
-#      defaults (whitelist: name, ide, cost_profile, personal.bot_icon,
+#      defaults (whitelist: name, ide, rule_loading_tier, personal.bot_icon,
 #      personal.autonomy, telegraph.speak_scope). Created on opt-in via
 #      /onboard; project-local files always win. Legacy
 #      ~/.config/agent-config/agent-settings.yml is read as a fallback.
@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.py (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "4.3.0"
+agent_config_version: "5.7.0"
 
 # --- Project identity ---
 project:

package/.agent-src/templates/scripts/work_engine/_lib/agent_settings.py

@@ -76,6 +76,45 @@ def _local_settings_path(project_root: Path) -> Path:
     return project_root.joinpath(*LOCAL_PROJECT_SUBDIR, LOCAL_PROJECT_FILE)
 
 
+def _canonical_settings_path(project_root: Path) -> Path:
+    """Canonical project settings file: ``<root>/agents/settings/.agent-settings.yml``.
+
+    The project settings file lives in the project's settings layer
+    (``agents/settings/``, alongside ``contexts/`` and ``policies/`` and
+    the ``.agent-settings.local.yml`` override), NOT at the repo root.
+    The repo-root ``.agent-settings.yml`` is a legacy location read only
+    as a back-compat fallback (see :func:`project_settings_path`).
+    """
+    return project_root.joinpath(*LOCAL_PROJECT_SUBDIR, DEFAULT_PROJECT_FILE)
+
+
+def project_settings_path(project_root: Path) -> Path:
+    """Resolve the project settings file for **reading**.
+
+    Returns the canonical ``agents/settings/.agent-settings.yml`` when it
+    exists; otherwise the legacy repo-root ``.agent-settings.yml`` when
+    that exists (back-compat for installs predating the relocation);
+    otherwise the canonical path (so the caller still names the right
+    target on a fresh repo). Existence-checked, never writes.
+    """
+    canonical = _canonical_settings_path(project_root)
+    if canonical.exists():
+        return canonical
+    legacy = project_root / DEFAULT_PROJECT_FILE
+    if legacy.exists():
+        return legacy
+    return canonical
+
+
+def canonical_settings_write_path(project_root: Path) -> Path:
+    """Always the canonical **write** target: ``agents/settings/.agent-settings.yml``.
+
+    Writers (install, sync, migrate) target this unconditionally; the
+    legacy root file is migrated into it, never written afresh.
+    """
+    return _canonical_settings_path(project_root)
+
+
 DEFAULT_TEAM_FILE = ".agent-project-settings.yml"
 USER_GLOBAL_FILENAME = "agent-settings.yml"
 
@@ -100,7 +139,8 @@ def _resolve_user_global_file() -> Path:
 MERGEABLE_KEYS: tuple[str, ...] = (
     "name",
     "ide",
-    "cost_profile",
+    "rule_loading_tier",
+    "memory.cadence",
     "personal.bot_icon",
     "personal.autonomy",
     "telegraph.speak_scope",
@@ -430,12 +470,14 @@ def _resolve_cascade_paths(
     """
     if cwd is None:
         legacy = Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE)
-        return [legacy, _local_settings_path(legacy.parent)]
+        return [legacy, _canonical_settings_path(legacy.parent),
+                _local_settings_path(legacy.parent)]
 
     root = find_project_root(cwd)
     if root is None:
         legacy = Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE)
-        return [legacy, _local_settings_path(legacy.parent)]
+        return [legacy, _canonical_settings_path(legacy.parent),
+                _local_settings_path(legacy.parent)]
 
     cwd_resolved = cwd.resolve()
     # Build the chain root → … → cwd (shallowest first, deepest last).
@@ -450,9 +492,15 @@ def _resolve_cascade_paths(
             break
         cursor = parent
     chain.reverse()
-    # Committed cascade root → cwd, then the single project-level local override
-    # under agents/settings/ as the deepest (winning) layer.
-    return [d / DEFAULT_PROJECT_FILE for d in chain] + [_local_settings_path(root)]
+    # Legacy per-dir cascade root → cwd (repo-root .agent-settings.yml is the
+    # shallowest, back-compat), then the canonical project settings file under
+    # agents/settings/ (wins over the legacy root location), then the
+    # per-machine local override under agents/settings/ as the deepest (winning)
+    # layer.
+    return (
+        [d / DEFAULT_PROJECT_FILE for d in chain]
+        + [_canonical_settings_path(root), _local_settings_path(root)]
+    )
 
 
 def load_agent_settings(

package/.agent-src/templates/scripts/work_engine/hook_bootstrap.py

@@ -64,7 +64,7 @@ def _build_hook_registry(args: argparse.Namespace) -> HookRegistry:
         gate_hook.register(registry)
     if settings.memory_visibility:
         MemoryVisibilityHook(
-            cost_profile=settings.cost_profile,
+            memory_cadence=settings.memory_cadence,
             visibility_off=settings.memory_visibility_off,
         ).register(registry)
     if settings.chat_history_enabled:

package/.agent-src/templates/scripts/work_engine/hooks/builtin/memory_visibility.py

@@ -43,10 +43,12 @@ class MemoryVisibilityHook:
 
     Parameters
     ----------
-    cost_profile:
-        Cadence profile from ``.agent-settings.yml`` (``lean`` /
-        ``standard`` / ``verbose``). ``lean`` suppresses the line
-        unless ``asks ≥ 3`` per the contract's cadence table.
+    memory_cadence:
+        Cadence from ``memory.cadence`` in ``.agent-settings.yml``
+        (``auto`` / ``always`` / ``never``). ``auto`` suppresses the
+        line unless ``asks ≥ 3``; ``never`` suppresses it entirely;
+        ``always`` (default) emits whenever ``asks ≥ 1`` per the
+        contract's cadence table.
     visibility_off:
         When ``True``, the hook stays silent — used to mirror
         ``memory.visibility: off`` in the consumer settings.
@@ -59,11 +61,11 @@ class MemoryVisibilityHook:
     def __init__(
         self,
         *,
-        cost_profile: str = "standard",
+        memory_cadence: str = "always",
         visibility_off: bool = False,
         asked_types: Iterable[str] | None = None,
     ) -> None:
-        self._cost_profile = cost_profile
+        self._memory_cadence = memory_cadence
         self._visibility_off = visibility_off
         self._asked_types = (
             tuple(asked_types) if asked_types is not None else DEFAULT_ASKED_TYPES
@@ -81,7 +83,7 @@ class MemoryVisibilityHook:
         summary = summarise_visibility(memory, asked_types=self._asked_types)
         if not should_emit(
             summary,
-            cost_profile=self._cost_profile,
+            memory_cadence=self._memory_cadence,
             visibility_off=self._visibility_off,
         ):
             return

package/.agent-src/templates/scripts/work_engine/hooks/settings.py

@@ -16,7 +16,7 @@ settings.py``):
 
 Per road-to-portable-dev-preferences P3, the YAML read goes through
 :func:`work_engine._lib.agent_settings.load_agent_settings`, which
-cascades the whitelisted ``cost_profile`` (and other DX-comfort keys)
+cascades the whitelisted ``rule_loading_tier`` (and other DX-comfort keys)
 from ``~/.event4u/agent-config/agent-settings.yml`` (legacy
 ``~/.config/agent-config/agent-settings.yml`` read as fallback) when
 the project file omits them. Project values always win.
@@ -61,7 +61,7 @@ class HookSettings:
     decision_trace: bool = False
     memory_visibility: bool = False
     memory_visibility_off: bool = False
-    cost_profile: str = "standard"
+    memory_cadence: str = "always"
     chat_history_enabled: bool = False
     chat_history_script: str = DEFAULT_CHAT_HISTORY_SCRIPT
     decision_engine: DecisionEngineSettings = DecisionEngineSettings()
@@ -82,8 +82,8 @@ def load_hook_settings(
     ``~/.event4u/agent-config/agent-settings.yml`` (with a read fallback
     to the legacy ``~/.config/agent-config/agent-settings.yml``) and
     only cascades the whitelisted DX-comfort keys (currently
-    ``cost_profile``) when the project file omits them. See
-    road-to-portable-dev-preferences P3.
+    ``rule_loading_tier`` and ``memory.cadence``) when the project file
+    omits them. See road-to-portable-dev-preferences P3.
     """
     path = Path(settings_path) if settings_path else Path(DEFAULT_SETTINGS_FILE)
     raw = load_agent_settings(
@@ -133,12 +133,16 @@ def _settings_from_raw(data: dict[str, Any]) -> HookSettings:
 
     memory_section = data.get("memory")
     visibility_off = False
+    memory_cadence = "always"
     if isinstance(memory_section, dict):
         raw = memory_section.get("visibility")
         if isinstance(raw, str) and raw.strip().lower() == "off":
             visibility_off = True
         elif isinstance(raw, bool) and raw is False:
             visibility_off = True
+        cadence_raw = memory_section.get("cadence")
+        if cadence_raw is not None:
+            memory_cadence = str(cadence_raw).strip().lower() or "always"
 
     memory_hooks = hooks.get("memory_visibility")
     if isinstance(memory_hooks, dict):
@@ -148,11 +152,6 @@ def _settings_from_raw(data: dict[str, Any]) -> HookSettings:
     else:
         memory_visibility_on = True
 
-    cost_profile_raw = data.get("cost_profile") or "standard"
-    cost_profile = (
-        str(cost_profile_raw).strip().lower() or "standard"
-    )
-
     return HookSettings(
         enabled=True,
         trace=_coerce_bool(hooks.get("trace"), False),
@@ -168,7 +167,7 @@ def _settings_from_raw(data: dict[str, Any]) -> HookSettings:
         decision_trace=decision_trace_on,
         memory_visibility=memory_visibility_on,
         memory_visibility_off=visibility_off,
-        cost_profile=cost_profile,
+        memory_cadence=memory_cadence,
         chat_history_enabled=chat_block_enabled and global_chat_on,
         chat_history_script=chat_script,
         decision_engine=decision_engine_settings,

package/.agent-src/templates/scripts/work_engine/scoring/memory_visibility.py

@@ -242,17 +242,30 @@ def format_changed_decisions_block(
 def should_emit(
     summary: dict[str, Any],
     *,
-    cost_profile: str = "standard",
+    memory_cadence: str = "always",
     visibility_off: bool = False,
 ) -> bool:
-    """Apply the cadence + opt-out gates from the contract."""
+    """Apply the cadence + opt-out gates from the contract.
+
+    ``memory_cadence`` is the ``memory.cadence`` cadence key:
+
+    * ``always`` (default) — emit whenever ``asks >= 1``.
+    * ``auto`` — emit only when ``asks >= 3`` (reduces noise on
+      shallow-retrieval steps).
+    * ``never`` — suppress the line entirely.
+
+    ``visibility_off`` is the legacy ``memory.visibility: off`` master
+    switch and still wins over any ``memory_cadence`` value.
+    """
     if visibility_off:
         return False
     asks = int(summary.get("asks", 0) or 0)
     if asks <= 0:
         return False
-    profile = (cost_profile or "standard").strip().lower()
-    if profile == "lean":
+    status = (memory_cadence or "always").strip().lower()
+    if status == "never":
+        return False
+    if status == "auto":
         return asks >= 3
     return True