@event4u/agent-config 1.21.0 → 1.23.0

package/scripts/cost/budget.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// cost-budget — set / get / check the project's cost budget against
+// accumulated session spend in agents/cost-tracking/sessions.jsonl.
+//
+// Forked from ruvnet/ruflo plugins/ruflo-cost-tracker/scripts/budget.mjs.
+// Local-JSONL swap replaces the upstream `mcp__claude-flow__memory_store`
+// dependency. Budget config lives next to the sessions store as budget.json.
+//
+// Usage: node scripts/cost/budget.mjs {set <usd>|get|check}
+// Env: BUDGET_STORE, BUDGET_CONFIG, BUDGET_PERIOD={today|week|month|all}, BUDGET_QUIET=1
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const STORE = process.env.BUDGET_STORE || 'agents/cost-tracking/sessions.jsonl';
+const CONFIG = process.env.BUDGET_CONFIG || 'agents/cost-tracking/budget.json';
+
+function loadConfig() {
+  if (!existsSync(CONFIG)) return null;
+  try { return JSON.parse(readFileSync(CONFIG, 'utf-8')); } catch { return null; }
+}
+
+function saveConfig(cfg) {
+  mkdirSync(dirname(CONFIG), { recursive: true });
+  writeFileSync(CONFIG, JSON.stringify(cfg, null, 2));
+}
+
+function loadSessions() {
+  if (!existsSync(STORE)) return [];
+  const out = [];
+  for (const line of readFileSync(STORE, 'utf-8').split('\n')) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { /* skip malformed line */ }
+  }
+  return out;
+}
+
+function periodFilter(period) {
+  const now = Date.now();
+  const day = 24 * 3600 * 1000;
+  if (period === 'today') return (ts) => ts && new Date(ts).toDateString() === new Date().toDateString();
+  if (period === 'week')  return (ts) => ts && (now - new Date(ts).getTime()) < 7 * day;
+  if (period === 'month') return (ts) => ts && (now - new Date(ts).getTime()) < 30 * day;
+  return () => true;
+}
+
+function alertLevel(u) {
+  if (u >= 1.00) return { level: 'HARD_STOP', emoji: '🛑', threshold: 100 };
+  if (u >= 0.90) return { level: 'CRITICAL',  emoji: '🔴', threshold: 90 };
+  if (u >= 0.75) return { level: 'WARNING',   emoji: '🟠', threshold: 75 };
+  if (u >= 0.50) return { level: 'INFO',      emoji: '🟡', threshold: 50 };
+  return { level: 'OK', emoji: '🟢', threshold: 0 };
+}
+
+function recommendedAction(level) {
+  return ({
+    OK: 'within budget — no action.',
+    INFO: '50% consumed — log notification, no UX disruption.',
+    WARNING: '75% consumed — suggest /set-cost-profile balanced→minimal.',
+    CRITICAL: '90% consumed — recommend model downgrades, consider /set-cost-profile minimal.',
+    HARD_STOP: '100% consumed — halt non-essential work; review /cost:report before continuing.',
+  }[level]);
+}
+
+function cmdSet(args) {
+  const amount = parseFloat(args[0]);
+  if (!Number.isFinite(amount) || amount <= 0) {
+    console.error('usage: budget.mjs set <usd-amount>  (positive number)');
+    process.exit(2);
+  }
+  const config = {
+    budget_usd: amount,
+    setAt: new Date().toISOString(),
+    thresholds: { info: 0.50, warning: 0.75, critical: 0.90, hard_stop: 1.00 },
+  };
+  saveConfig(config);
+  if (process.env.BUDGET_QUIET === '1') {
+    console.log(JSON.stringify(config));
+  } else {
+    console.log(`✓ Budget set: $${amount.toFixed(2)} (config: ${CONFIG})`);
+    console.log('  Alerts: 50% INFO · 75% WARNING · 90% CRITICAL · 100% HARD_STOP');
+  }
+}
+
+function cmdGet() {
+  const cfg = loadConfig();
+  if (process.env.BUDGET_QUIET === '1') {
+    console.log(JSON.stringify(cfg || { error: 'no budget configured' }));
+    return;
+  }
+  if (!cfg) {
+    console.log(`No budget configured (config: ${CONFIG}).`);
+    console.log('Set one with: node scripts/cost/budget.mjs set <usd>');
+    return;
+  }
+  console.log(`Budget: $${cfg.budget_usd?.toFixed(2)}  (set ${cfg.setAt})`);
+  console.log('Thresholds: 50/75/90/100%');
+}
+
+function cmdCheck() {
+  const cfg = loadConfig();
+  const period = process.env.BUDGET_PERIOD || 'all';
+  const filt = periodFilter(period);
+  const filtered = loadSessions().filter((r) => filt(r.capturedAt || r.endedAt));
+  const totalSpend = filtered.reduce((s, r) => s + (r.total_cost_usd || 0), 0);
+  if (!cfg || !Number.isFinite(cfg.budget_usd)) {
+    const out = { period, totalSpend, recordCount: filtered.length, error: 'no budget configured' };
+    if (process.env.BUDGET_QUIET === '1') return console.log(JSON.stringify(out));
+    console.log(`Period: ${period}`);
+    console.log(`Spent so far: $${totalSpend.toFixed(2)} across ${filtered.length} sessions`);
+    console.log('No budget set — run `node scripts/cost/budget.mjs set <usd>` to enable alerts.');
+    return;
+  }
+  const utilization = totalSpend / cfg.budget_usd;
+  const alert = alertLevel(utilization);
+  const out = {
+    period,
+    budget_usd: cfg.budget_usd,
+    spent_usd: totalSpend,
+    remaining_usd: Math.max(0, cfg.budget_usd - totalSpend),
+    utilization_pct: utilization * 100,
+    level: alert.level,
+    threshold: alert.threshold,
+    recommended_action: recommendedAction(alert.level),
+    sessionCount: filtered.length,
+  };
+  if (process.env.BUDGET_QUIET === '1') return console.log(JSON.stringify(out));
+  console.log(`# Budget check (period: ${period})\n`);
+  console.log('| Metric | Value |\n|---|---:|');
+  console.log(`| Budget | $${cfg.budget_usd.toFixed(2)} |`);
+  console.log(`| Spent | $${totalSpend.toFixed(2)} |`);
+  console.log(`| Remaining | $${out.remaining_usd.toFixed(2)} |`);
+  console.log(`| Utilization | ${out.utilization_pct.toFixed(1)}% |`);
+  console.log(`| Sessions counted | ${filtered.length} |`);
+  console.log(`| **Alert** | **${alert.emoji} ${alert.level}** |`);
+  console.log(`\nAction: ${out.recommended_action}`);
+  if (alert.level === 'HARD_STOP') process.exit(1);
+}
+
+function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  switch (cmd) {
+    case 'set':   return cmdSet(rest);
+    case 'get':   return cmdGet();
+    case 'check': return cmdCheck();
+    default:
+      console.error('usage: budget.mjs {set <usd>|get|check}');
+      process.exit(2);
+  }
+}
+
+main();

package/scripts/cost/track.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// cost-track — auto-capture token usage from a Claude Code session jsonl
+// and append a structured record to agents/cost-tracking/sessions.jsonl.
+//
+// Forked from ruvnet/ruflo plugins/ruflo-cost-tracker/scripts/track.mjs.
+// Local-JSONL swap replaces the upstream `mcp__claude-flow__memory_store`
+// dependency. Pricing constants are kept in sync with REFERENCE.md.
+//
+// Env:
+//   TRACK_CWD=<path>          override which project's sessions to scan
+//   TRACK_SESSION=<file>      pin to a specific session jsonl
+//   TRACK_OUT=<path>          also write the JSON summary to this path
+//   TRACK_DRY_RUN=1           skip the JSONL append
+//   TRACK_QUIET=1             suppress markdown summary
+//   TRACK_STORE=<path>        override (default: agents/cost-tracking/sessions.jsonl)
+
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+const PROJECTS_DIR = join(homedir(), '.claude', 'projects');
+const DEFAULT_STORE = 'agents/cost-tracking/sessions.jsonl';
+
+// USD per 1M tokens.
+const PRICING = {
+  haiku:  { input: 0.25,  output: 1.25,  cache_write: 0.30,  cache_read: 0.03 },
+  sonnet: { input: 3.00,  output: 15.00, cache_write: 3.75,  cache_read: 0.30 },
+  opus:   { input: 15.00, output: 75.00, cache_write: 18.75, cache_read: 1.50 },
+};
+
+function modelTier(model) {
+  if (!model) return 'unknown';
+  const m = String(model).toLowerCase();
+  if (m.includes('haiku')) return 'haiku';
+  if (m.includes('sonnet')) return 'sonnet';
+  if (m.includes('opus')) return 'opus';
+  return 'unknown';
+}
+
+function costForUsage(tier, u) {
+  const p = PRICING[tier];
+  if (!p || !u) return 0;
+  return (u.input_tokens || 0) / 1e6 * p.input
+       + (u.output_tokens || 0) / 1e6 * p.output
+       + (u.cache_creation_input_tokens || 0) / 1e6 * p.cache_write
+       + (u.cache_read_input_tokens || 0) / 1e6 * p.cache_read;
+}
+
+function encodeProjectPath(cwd) { return cwd.replace(/\//g, '-'); }
+
+function findProjectDir(cwd) {
+  const c = join(PROJECTS_DIR, encodeProjectPath(cwd));
+  return existsSync(c) ? c : null;
+}
+
+function findActiveSession(dir) {
+  const e = readdirSync(dir).filter((f) => f.endsWith('.jsonl'))
+    .map((f) => ({ f, mtime: statSync(join(dir, f)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime);
+  return e[0] ? join(dir, e[0].f) : null;
+}
+
+function summarizeSession(jsonlPath) {
+  const lines = readFileSync(jsonlPath, 'utf-8').split('\n').filter(Boolean);
+  const byModel = {};
+  const byTier = { haiku: 0, sonnet: 0, opus: 0, unknown: 0 };
+  let messageCount = 0, totalCost = 0, firstTs = null, lastTs = null;
+  let sessionId = null, cwd = null;
+  for (const line of lines) {
+    let m; try { m = JSON.parse(line); } catch { continue; }
+    if (!sessionId && m.sessionId) sessionId = m.sessionId;
+    if (!cwd && m.cwd) cwd = m.cwd;
+    if (m.timestamp) {
+      if (!firstTs || m.timestamp < firstTs) firstTs = m.timestamp;
+      if (!lastTs || m.timestamp > lastTs) lastTs = m.timestamp;
+    }
+    if (m.type !== 'assistant' || !m.message?.usage) continue;
+    messageCount++;
+    const model = m.message.model || 'unknown';
+    const tier = modelTier(model);
+    const u = m.message.usage;
+    const cost = costForUsage(tier, u);
+    const slot = byModel[model] || { tier, input_tokens: 0, output_tokens: 0,
+      cache_creation_input_tokens: 0, cache_read_input_tokens: 0, messages: 0, cost_usd: 0 };
+    slot.input_tokens += u.input_tokens || 0;
+    slot.output_tokens += u.output_tokens || 0;
+    slot.cache_creation_input_tokens += u.cache_creation_input_tokens || 0;
+    slot.cache_read_input_tokens += u.cache_read_input_tokens || 0;
+    slot.messages++; slot.cost_usd += cost;
+    byModel[model] = slot; byTier[tier] += cost; totalCost += cost;
+  }
+  return { sessionId, cwd, startedAt: firstTs, endedAt: lastTs, messageCount,
+    byModel, byTier, total_cost_usd: totalCost, capturedAt: new Date().toISOString() };
+}
+
+function persistJsonl(summary, store) {
+  mkdirSync(dirname(store), { recursive: true });
+  appendFileSync(store, JSON.stringify(summary) + '\n');
+  return { ok: true, path: store };
+}
+
+function main() {
+  const targetCwd = process.env.TRACK_CWD || process.cwd();
+  const projectDir = findProjectDir(targetCwd);
+  if (!projectDir) {
+    console.error(`cost-track: no Claude Code project dir for cwd=${targetCwd}`);
+    console.error(`looked under ${PROJECTS_DIR}/${encodeProjectPath(targetCwd)}`);
+    process.exit(2);
+  }
+  const sessionPath = process.env.TRACK_SESSION || findActiveSession(projectDir);
+  if (!sessionPath || !existsSync(sessionPath)) {
+    console.error(`cost-track: no session jsonl in ${projectDir}`); process.exit(2);
+  }
+  const summary = summarizeSession(sessionPath);
+  if (process.env.TRACK_OUT) writeFileSync(process.env.TRACK_OUT, JSON.stringify(summary, null, 2));
+  const store = process.env.TRACK_STORE || DEFAULT_STORE;
+  let res = { ok: false, reason: 'dry-run' };
+  if (process.env.TRACK_DRY_RUN !== '1') res = persistJsonl(summary, store);
+  if (process.env.TRACK_QUIET === '1') return;
+
+  console.log(`# cost-track — session ${(summary.sessionId || '').slice(0, 8) || 'unknown'}`);
+  console.log('');
+  console.log('| Metric | Value |\n|---|---:|');
+  console.log(`| Session ID | \`${summary.sessionId}\` |`);
+  console.log(`| Project | \`${summary.cwd}\` |`);
+  console.log(`| First message | ${summary.startedAt} |`);
+  console.log(`| Last message | ${summary.endedAt} |`);
+  console.log(`| Assistant messages | ${summary.messageCount} |`);
+  console.log(`| **Total cost** | **$${summary.total_cost_usd.toFixed(6)}** |`);
+  console.log(`| Persisted | ${res.ok ? `\`${res.path}\`` : `**FAILED** (${res.reason})`} |`);
+  console.log('\n## Per-model breakdown\n');
+  console.log('| Model | Tier | Messages | Input | Output | Cache write | Cache read | Cost |');
+  console.log('|---|---|---:|---:|---:|---:|---:|---:|');
+  for (const [m, s] of Object.entries(summary.byModel).sort((a, b) => b[1].cost_usd - a[1].cost_usd)) {
+    console.log(`| \`${m}\` | ${s.tier} | ${s.messages} | ${s.input_tokens} | ${s.output_tokens} | ${s.cache_creation_input_tokens} | ${s.cache_read_input_tokens} | $${s.cost_usd.toFixed(6)} |`);
+  }
+  console.log('\n## Per-tier breakdown\n');
+  console.log('| Tier | Cost |\n|---|---:|');
+  for (const [t, c] of Object.entries(summary.byTier).sort((a, b) => b[1] - a[1])) {
+    if (c > 0) console.log(`| ${t} | $${c.toFixed(6)} |`);
+  }
+}
+
+main();

package/scripts/council_cli.py

@@ -63,6 +63,7 @@ def build_members(
     *,
     invocation_mode: str | None = None,
     model_overrides: dict[str, str] | None = None,
+    siblings_overrides: dict[str, list[str]] | None = None,
 ) -> list[ExternalAIClient]:
     """Construct enabled council members from settings.
 
@@ -73,6 +74,13 @@ def build_members(
     `model_overrides` is a per-invocation `{member_name: model_id}`
     map that wins over the per-member `model` in settings. Members not
     listed fall back to the settings value, then the per-client default.
+
+    `siblings_overrides` is a per-invocation `{member_name: [model, ...]}`
+    map that fans the named provider out to multiple sibling models in
+    one run (e.g. claude-sonnet-4-5 + claude-opus-4-1). Each model
+    becomes its own billable member with independent cost tracking.
+    Mutually exclusive with `model_overrides` for the same provider;
+    requires `mode=api`; provider must be enabled in settings.
     """
     ai = (settings.get("ai_council") or {}) if isinstance(settings, dict) else {}
     if not ai.get("enabled"):
@@ -83,16 +91,34 @@ def build_members(
     members_cfg = ai.get("members") or {}
     global_mode = ai.get("mode")
     overrides = model_overrides or {}
+    siblings = siblings_overrides or {}
     unknown = set(overrides) - set(members_cfg)
     if unknown:
         raise CouncilDisabledError(
             f"--model targets unknown member(s) {sorted(unknown)!r}; "
             f"known members: {sorted(members_cfg)!r}."
         )
+    unknown_sib = set(siblings) - set(members_cfg)
+    if unknown_sib:
+        raise CouncilDisabledError(
+            f"--siblings targets unknown member(s) {sorted(unknown_sib)!r}; "
+            f"known members: {sorted(members_cfg)!r}."
+        )
+    conflict = set(overrides) & set(siblings)
+    if conflict:
+        raise CouncilDisabledError(
+            f"--model and --siblings target the same member(s) {sorted(conflict)!r}; "
+            f"pick one per provider per invocation."
+        )
     members: list[ExternalAIClient] = []
     for name, cfg in members_cfg.items():
         cfg = cfg or {}
         if not cfg.get("enabled"):
+            if name in siblings:
+                raise CouncilDisabledError(
+                    f"--siblings targets member {name!r} but it is not "
+                    f"enabled in .agent-settings.yml (ai_council.members.{name}.enabled)."
+                )
             continue
         mode = resolve_mode(
             name,
@@ -100,13 +126,17 @@ def build_members(
             member_settings=cfg,
             global_mode=global_mode,
         )
+        if name in siblings:
+            if mode != "api":
+                raise CouncilDisabledError(
+                    f"--siblings requires mode=api for member {name!r} (got {mode!r})."
+                )
+            for sib_model in siblings[name]:
+                members.append(_construct_api_member(name, sib_model))
+            continue
         model = overrides.get(name) or cfg.get("model")
-        if mode == "api" and name == "anthropic":
-            members.append(AnthropicClient(model=model or "claude-sonnet-4-5",
-                                           api_key=load_anthropic_key()))
-        elif mode == "api" and name == "openai":
-            members.append(OpenAIClient(model=model or "gpt-4o",
-                                        api_key=load_openai_key()))
+        if mode == "api" and name in {"anthropic", "openai"}:
+            members.append(_construct_api_member(name, model))
         elif mode == "manual":
             members.append(ManualClient(name=name, model=model or "manual"))
         elif mode == "playwright":
@@ -125,6 +155,19 @@ def build_members(
     return members
 
 
+def _construct_api_member(name: str, model: str | None) -> ExternalAIClient:
+    """Build an api-mode client for a known provider name."""
+    if name == "anthropic":
+        return AnthropicClient(model=model or "claude-sonnet-4-5",
+                               api_key=load_anthropic_key())
+    if name == "openai":
+        return OpenAIClient(model=model or "gpt-4o",
+                            api_key=load_openai_key())
+    raise CouncilDisabledError(
+        f"member {name!r} has no api transport (known: anthropic, openai)."
+    )
+
+
 def build_question(
     *,
     input_path: Path,
@@ -164,6 +207,29 @@ def format_estimate_table(
 # ── subcommands ─────────────────────────────────────────────────────
 
 
+def _resolve_rounds(args: argparse.Namespace, ai_cfg: dict[str, Any]) -> int:
+    """Resolve effective debate round count from CLI args + settings.
+
+    Resolution chain (highest priority first):
+      1. ``--rounds N`` — explicit user override, any value.
+      2. ``--depth deep`` — uses ``ai_council.deep_min_rounds``,
+         floored at ``min_rounds`` so the deep tier is monotonic.
+      3. ``ai_council.min_rounds`` — default 2.
+
+    Sub-commands (rule/skill/command) declare ``council_depth: deep``
+    in their frontmatter; the host agent reads that and translates it
+    to ``--depth deep`` on the CLI invocation. The CLI itself stays
+    unaware of frontmatter — the contract is the flag.
+    """
+    if getattr(args, "rounds", None) is not None:
+        return int(args.rounds)
+    min_rounds = int(ai_cfg.get("min_rounds", 2))
+    if getattr(args, "depth", "standard") == "deep":
+        deep = int(ai_cfg.get("deep_min_rounds", min_rounds))
+        return max(deep, min_rounds)
+    return min_rounds
+
+
 def cmd_estimate(
     args: argparse.Namespace,
     *,
@@ -179,6 +245,7 @@ def cmd_estimate(
             settings,
             invocation_mode=args.mode_override,
             model_overrides=_parse_model_overrides(getattr(args, "model", None)),
+            siblings_overrides=_parse_siblings_overrides(getattr(args, "siblings", None)),
         )
     if table is None:
         table = load_prices()
@@ -239,6 +306,7 @@ def cmd_run(
             settings,
             invocation_mode=args.mode_override,
             model_overrides=_parse_model_overrides(getattr(args, "model", None)),
+            siblings_overrides=_parse_siblings_overrides(getattr(args, "siblings", None)),
         )
     if table is None:
         table = load_prices()
@@ -271,7 +339,7 @@ def cmd_run(
         max_calls=int(cost_cfg.get("max_calls", 10)),
         max_total_usd=float(cost_cfg.get("max_total_usd", 0.0) or 0.0),
     )
-    rounds = args.rounds if args.rounds is not None else int(ai_cfg.get("min_rounds", 2))
+    rounds = _resolve_rounds(args, ai_cfg)
     responses = consult(
         members, question, budget,
         table=table, project=project,
@@ -339,6 +407,38 @@ def _parse_model_overrides(items: list[str] | None) -> dict[str, str]:
     return out
 
 
+def _parse_siblings_overrides(items: list[str] | None) -> dict[str, list[str]]:
+    """Parse repeated `--siblings name=model1,model2[,...]` flags.
+
+    Requires ≥ 2 distinct, non-empty models per provider — sibling
+    mode without diversity has no purpose. Repeating the same provider
+    flag is rejected as ambiguous.
+    """
+    out: dict[str, list[str]] = {}
+    for raw in items or []:
+        if "=" not in raw:
+            raise argparse.ArgumentTypeError(
+                f"--siblings expects '<member>=<model1>,<model2>[,...]', got {raw!r}."
+            )
+        name, models_csv = raw.split("=", 1)
+        name = name.strip()
+        models = [m.strip() for m in models_csv.split(",") if m.strip()]
+        if not name or not models:
+            raise argparse.ArgumentTypeError(
+                f"--siblings member and model list must both be non-empty: {raw!r}."
+            )
+        if len(set(models)) < 2:
+            raise argparse.ArgumentTypeError(
+                f"--siblings requires ≥ 2 distinct models for {name!r}, got {models!r}."
+            )
+        if name in out:
+            raise argparse.ArgumentTypeError(
+                f"--siblings repeated for member {name!r}; combine into one flag."
+            )
+        out[name] = models
+    return out
+
+
 def _add_common_input_args(p: argparse.ArgumentParser) -> None:
     p.add_argument("question", type=str,
                    help="Path to the question file (text or roadmap).")
@@ -356,6 +456,16 @@ def _add_common_input_args(p: argparse.ArgumentParser) -> None:
                         "Wins over `ai_council.members.<name>.model` in "
                         ".agent-settings.yml; the settings file is not "
                         "modified.")
+    p.add_argument("--siblings", action="append", default=None, dest="siblings",
+                   metavar="MEMBER=MODEL1,MODEL2[,...]",
+                   help="Fan one provider out to ≥ 2 sibling models in a "
+                        "single run, e.g. --siblings anthropic=claude-sonnet-4-5,"
+                        "claude-opus-4-1. Each model becomes its own billable "
+                        "member with independent cost tracking. Mutually "
+                        "exclusive with --model for the same provider; "
+                        "requires the provider to be enabled with mode=api. "
+                        "Single-provider degraded-run strategy per ai-council "
+                        "skill.")
     p.add_argument("--original-ask", default="",
                    help="The user's framing sentence (flows into handoff).")
 
@@ -377,9 +487,16 @@ def build_parser() -> argparse.ArgumentParser:
     p_run.add_argument("--confirm", action="store_true",
                        help="Required to actually invoke the council.")
     p_run.add_argument("--rounds", type=int, default=None,
-                       help="Number of debate rounds (1-3). Defaults to "
-                            "ai_council.min_rounds in .agent-settings.yml "
-                            "(or 2 if unset).")
+                       help="Number of debate rounds (1-3). Explicit override; "
+                            "wins over --depth. Defaults to ai_council.min_rounds "
+                            "in .agent-settings.yml (or 2 if unset).")
+    p_run.add_argument("--depth", choices=["standard", "deep"], default="standard",
+                       help="Reasoning-depth tier. 'deep' floors rounds at "
+                            "ai_council.deep_min_rounds (max'd with min_rounds) "
+                            "for architecture, refactoring, or bug-diagnosis "
+                            "artefacts. Set by the host agent when the consuming "
+                            "rule/skill/command declares council_depth: deep. "
+                            "Overridden by explicit --rounds.")
 
     p_ren = sub.add_parser("render", help="Re-render a saved responses JSON.")
     p_ren.add_argument("responses",

package/scripts/first-run.sh

@@ -5,9 +5,7 @@ SETTINGS_FILE=".agent-settings.yml"
 LEGACY_SETTINGS_FILE=".agent-settings"
 
 echo ""
-echo "========================================"
-echo "  Agent Config — First Run"
-echo "========================================"
+echo "Agent Config — First Run"
 echo ""
 
 # --- Profile detection ---
@@ -63,9 +61,7 @@ echo "  ✅  Zero token overhead in minimal mode"
 echo ""
 
 # --- 3 test prompts ---
-echo "========================================" 
-echo "  Try these 3 prompts now"
-echo "========================================"
+echo "Try these 3 prompts now:"
 echo ""
 
 echo "1️⃣  Refactoring check"
@@ -94,9 +90,7 @@ echo "   → Agent challenges weak requirements"
 echo ""
 
 # --- Next steps ---
-echo "========================================"
-echo "  Next steps"
-echo "========================================"
+echo "Next steps:"
 echo ""
 echo "Cost profiles:"
 echo "  minimal   rules, skills, commands only"

package/scripts/install-hooks.sh

@@ -39,7 +39,9 @@ echo "✅  Pre-push hook installed."
 cat > "$HOOKS_DIR/pre-commit" << 'EOF'
 #!/usr/bin/env bash
 # Pre-commit hook: verify .claude-plugin/marketplace.json lists every skill
-# that exists on disk under .claude/skills/.
+# that exists on disk under .claude/skills/, AND verify
+# agents/roadmaps-progress.md is in sync with the current state of
+# agents/roadmaps/ (roadmap-progress-sync Iron Law).
 
 python3 scripts/lint_marketplace.py
 status=$?
@@ -52,6 +54,22 @@ if [ $status -ne 0 ]; then
     echo "       git commit --no-verify"
     exit 1
 fi
+
+# Roadmap dashboard sync — only fires when staged changes touch a roadmap
+# file or the dashboard itself, so unrelated commits stay fast.
+if git diff --cached --name-only | grep -qE '^agents/roadmaps(-progress\.md|/)'; then
+    python3 .augment/scripts/update_roadmap_progress.py --check
+    rstatus=$?
+    if [ $rstatus -ne 0 ]; then
+        echo ""
+        echo "❌  Commit blocked — agents/roadmaps-progress.md is stale."
+        echo "   Run './agent-config roadmap:progress' (or"
+        echo "   'python3 .augment/scripts/update_roadmap_progress.py'),"
+        echo "   stage agents/roadmaps-progress.md, then re-commit."
+        echo "   To bypass for an unrelated WIP commit: git commit --no-verify"
+        exit 1
+    fi
+fi
 EOF
 
 chmod +x "$HOOKS_DIR/pre-commit"

package/scripts/install.py

@@ -1280,6 +1280,7 @@ def main(argv: list[str]) -> int:
         fail(f"Unsupported profile: {opts.profile}. Supported: {', '.join(SUPPORTED_PROFILES)}")
 
     project_root = Path(opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()).resolve()
+    is_first_run = not (project_root / SETTINGS_FILE).exists()
 
     if opts.package:
         package_root = Path(opts.package).resolve()
@@ -1335,18 +1336,22 @@ def main(argv: list[str]) -> int:
     if not QUIET:
         print()
         success("Done.")
-        print()
-        print("  Try these 3 prompts with your agent:")
-        print('    1. "Refactor this function"   → agent analyzes first')
-        print('    2. "Add caching to this"      → agent asks instead of guessing')
-        print('    3. "Implement this feature"   → agent respects your codebase')
-        print()
-        print("  Next steps:")
-        print("    • Commit .agent-settings.yml and bridge files to your repo")
-        print("    • New team members just run composer install / npm install — done")
-        print("    • Inspect hook coverage: ./agent-config hooks:status")
-        print("    • Full walkthrough: https://github.com/event4u-app/agent-config/blob/main/docs/getting-started.md")
-        print()
+        if is_first_run:
+            print()
+            print("  Try these 3 prompts with your agent:")
+            print('    1. "Refactor this function"   → agent analyzes first')
+            print('    2. "Add caching to this"      → agent asks instead of guessing')
+            print('    3. "Implement this feature"   → agent respects your codebase')
+            print()
+            print("  Next steps:")
+            print("    • Commit .agent-settings.yml and bridge files to your repo")
+            print("    • New team members just run composer install / npm install — done")
+            print("    • Inspect hook coverage: ./agent-config hooks:status")
+            print("    • Full walkthrough: https://github.com/event4u-app/agent-config/blob/main/docs/getting-started.md")
+            print()
+        else:
+            print("  Re-run complete. Walkthrough: https://github.com/event4u-app/agent-config/blob/main/docs/getting-started.md")
+            print()
     return 0