From 093f3cec1f2332d2e3e1436beb7e49b51f3ee7cc Mon Sep 17 00:00:00 2001
From: BattleTag <hychen3637.com>
Date: Thu, 21 May 2026 02:26:12 -1000
Subject: [PATCH] feat(strategist) S6: config.example.yaml schema for
 strategist + budgets
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

DESIGN_STRATEGIST.md §6. Document the strategist loop's tunables so
operators can override defaults without code changes.

config.yaml itself is gitignored (it carries the API key), so this
commit adds config.example.yaml as the tracked schema reference.
The runtime reads config.yaml; operators copy the example as a
starting point.

  strategist.enabled       — default true; false routes Phase 3 through
                             the legacy fixed-round loop instead.
  strategist.max_rounds    — orchestrator cap (default 10).
  strategist.hard_stop_marginal_yield_zero_rounds — safety net for
                             over-eager strategist + zero-yielding
                             workers (default 3).
  budgets.tool_calls_total — global tool-call hard cap.
  budgets.strategist_rounds_max — informational, surfaced via
                             budget_status (orchestrator enforces
                             via strategist.max_rounds instead).
  budgets.wall_clock_minutes_max — wall-clock hard cap.

Comment out any budget cap to make it unbounded — Orchestrator's
_budget_exceeded treats missing caps as no-op.

Legacy max_investigation_rounds is kept as the fallback used only when
strategist.enabled is false; documented inline.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 config.example.yaml | 71 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 config.example.yaml

diff --git a/config.example.yaml b/config.example.yaml
new file mode 100644
index 0000000..29c8ecb
--- /dev/null
+++ b/config.example.yaml
@@ -0,0 +1,71 @@
+# MASForensics Configuration — template.
+#
+# Copy this file to `config.yaml` and fill in your API key. config.yaml is
+# git-ignored so secrets don't land in commits. The two files share schema;
+# only this template is tracked.
+
+agent:
+  base_url: "https://api.deepseek.com"
+  api_key: "YOUR-API-KEY-HERE"
+  model: "deepseek-v4-pro"
+  max_tokens: 16384
+  reasoning_effort: "high"      # DeepSeek/o1-style reasoning depth; omit to disable
+  thinking_enabled: true         # DeepSeek extra_body.thinking switch
+
+# Maximum rounds of hypothesis-directed investigation (Phase 3).
+# Only consulted when strategist.enabled is false (legacy fallback path).
+max_investigation_rounds: 1
+
+# Phase 3 strategist loop (DESIGN_STRATEGIST.md). When enabled, the
+# InvestigationStrategist agent decides each round whether to propose new
+# leads or declare the investigation complete. When disabled, the legacy
+# fixed-round investigation loop runs instead.
+strategist:
+  enabled: true
+  max_rounds: 10
+  # Safety net: if the strategist keeps proposing leads but yield (new
+  # phenomena + edges + status flips) is zero for this many consecutive
+  # rounds, the orchestrator force-stops Phase 3 regardless.
+  hard_stop_marginal_yield_zero_rounds: 3
+
+# Hard caps that bound the whole run. The strategist's budget_status tool
+# reads these to pace its proposals; the orchestrator also enforces them
+# as hard stops (DESIGN_STRATEGIST.md §4.2 step 7). Comment out any cap
+# to make it unbounded.
+budgets:
+  tool_calls_total: 5000
+  strategist_rounds_max: 10
+  wall_clock_minutes_max: 480
+
+# Optional: override the per-edge-type log₁₀(LR) calibration table.
+# Confidence updates accumulate these in odds space (additive, order-
+# independent), then map back to probability via sigmoid. Single edge
+# magnitudes: ≥ +0.602 lifts confidence above the 0.8 supported threshold,
+# ≤ −0.602 drops it below the 0.2 refuted threshold.
+# If omitted, evidence_graph._DEFAULT_LOG_LR is used.
+# hypothesis_log_lr:
+#   direct_evidence: 2.0
+#   supports: 1.0
+#   consequence_observed: 1.0
+#   prerequisite_met: 0.5
+#   weakens: -0.5
+#   contradicts: -2.0
+
+# Optional: manually specify initial hypotheses. If omitted, the
+# HypothesisAgent auto-generates them from Phase 1 findings.
+# hypotheses:
+#   - title: "..."
+#     description: "..."
+
+# Investigation areas — LLM-derived from active hypotheses after Phase 2.
+# Each entry below acts as a MANUAL OVERRIDE: it is seeded into the graph
+# before the LLM derives areas, so manual entries always survive (slug-based
+# dedupe; LLM only augments keyword/tool lists, never overwrites).
+#
+# investigation_areas:
+#   - area: shutdown_time
+#     description: "Last recorded shutdown time"
+#     agent: registry
+#     priority: 3
+#     keywords: [shutdown, last shutdown]
+#     tools: [get_shutdown_time]