release: heavy-coder 0.3.1 - orchestration width policy and hook routing

Author: codegraphtheory

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.3.1
+
+- **Orchestration:** centralize council width policy in `width_policy.py`; align triage and `team_coordinator.py` defaults with shipped `council_width` / `default_width` **8** (Grok Heavy phrases still widen to **16**).
+- **Hooks:** `should_trigger_team_plan` skips read-only inspect/audit turns unless the user also asks to implement or improve; shared width parsing in `hook_lib` inline plan build.
+- **Bootstrap:** advisory `recommended_flow` documents widths **3|5|8|16** with default council **8**.
+- **Tests:** triage width expectations, `test_hook_lib.py`, width policy parsing.
+
 ## 0.3.0
 
 - **Coordinator skills:** add eight strategic skills for routing, dispatch discipline, pre-dispatch enrich, candidate JSON, hook phases, repair waves, context budget, and single mode: `heavy-scope-router`, `heavy-swarm-dispatch`, `heavy-pre-dispatch-enrich`, `heavy-leaf-candidate-output`, `heavy-hook-phases`, `heavy-repair-wave`, `heavy-context-budget`, `heavy-single-mode`.

RELEASE_NOTES.md

@@ -1,10 +1,10 @@
-## heavy-coder 0.3.0
+## heavy-coder 0.3.1
 
 ### Highlights
 
-- **Strategic coordinator skills (8 new):** route tasks before spending swarm tokens (`heavy-scope-router`), dispatch full-width batches once (`heavy-swarm-dispatch`), enrich slim hook context (`heavy-pre-dispatch-enrich`), require candidate-result JSON (`heavy-leaf-candidate-output`), obey hook phases (`heavy-hook-phases`), narrow repair waves (`heavy-repair-wave`), token discipline (`heavy-context-budget`), explicit single mode (`heavy-single-mode`).
-- **`heavy-team-default` v0.6.0:** single phase table linking explore → enrich → dispatch → synthesize → ship gate.
-- **Profile alignment:** `.hermes.md` / `SOUL.md` updated for default council width **8** and per-turn routing.
+- **Orchestration alignment:** one width policy module feeds triage, `team_coordinator.py`, and hook inline plan build so default Composer swarms stay at **8** leaves unless the task explicitly requests Grok Heavy-style **16**.
+- **Smarter hook triggers:** pure inspect/audit/review messages no longer inject a full council plan; mixed messages (e.g. inspect **and** improve) still do.
+- **Docs/diagnostics:** bootstrap advisory flow mentions **8** as the default council width.
 
 ### Install / update (local tree or GitHub)
 
@@ -16,10 +16,10 @@ heavy-coder chat
 Pin a tagged checkout:
 
 ```bash
-git checkout v0.3.0
+git checkout v0.3.1
 hermes profile install . --name heavy-coder --alias --force --yes
 ```
 
 Hermes install URLs do not support `@tag` suffixes; use a local checkout to pin.
 
-Full changelog: [CHANGELOG.md](https://github.com/codegraphtheory/heavy-coder/blob/v0.3.0/CHANGELOG.md)
+Full changelog: [CHANGELOG.md](https://github.com/codegraphtheory/heavy-coder/blob/v0.3.1/CHANGELOG.md)

agent-hooks/hook_lib.py

@@ -26,6 +26,16 @@
     re.IGNORECASE,
 )
 
+READ_ONLY_TASK_RE = re.compile(
+    r"\b(inspect|audit|explore|check out|review|opportunities|what's wrong with|explain)\b",
+    re.IGNORECASE,
+)
+
+IMPLEMENTATION_TASK_RE = re.compile(
+    r"\b(implement|improvements?|fix|add|build|patch|refactor|debug|migrate|ship|update|remove)\b",
+    re.IGNORECASE,
+)
+
 PHASE_IDLE = "IDLE"
 PHASE_AWAITING_DELEGATE = "AWAITING_DELEGATE"
 PHASE_AWAITING_SYNTHESIS = "AWAITING_SYNTHESIS"
@@ -118,7 +128,9 @@ def should_trigger_team_plan(text: str) -> bool:
         return False
     if is_single_mode(text):
         return False
-    return not TRIVIAL_RE.search(text.strip())
+    if TRIVIAL_RE.search(text.strip()):
+        return False
+    return not (READ_ONLY_TASK_RE.search(text) and not IMPLEMENTATION_TASK_RE.search(text))
 
 
 def emit_json(payload: dict[str, Any]) -> None:
@@ -153,19 +165,10 @@ def run_team_plan(task: str, repo: Path) -> dict[str, Any]:
             mapping = load_yaml_mapping(resolve_config_path(root))
             block = mapping.get("heavy_coder")
             heavy = block if isinstance(block, dict) else {}
-            default_raw = heavy.get("default_width", 3)
-            default_width = default_raw if isinstance(default_raw, int) else 3
-            allowed = (3, 5, 8, 16)
-            raw_widths = heavy.get("candidate_widths")
-            if isinstance(raw_widths, list):
-                widths = []
-                for item in raw_widths:
-                    if isinstance(item, int):
-                        widths.append(item)
-                    elif isinstance(item, str) and item.strip().isdigit():
-                        widths.append(int(item.strip()))
-                if widths:
-                    allowed = tuple(widths)
+            from heavy_coder.profile_config import coerce_candidate_widths, parse_default_width
+
+            default_width = parse_default_width(heavy)
+            allowed = coerce_candidate_widths(heavy.get("candidate_widths"))
 
             return build_council_plan(
                 task,

distribution.yaml

@@ -1,5 +1,5 @@
 name: heavy-coder
-version: 0.3.0
+version: 0.3.1
 description: "Hermes profile with shell-hook enforced multi-candidate coding teams (Plan 1A)."
 hermes_requires: ">=0.12.0"
 author: "CodeGraphTheory"

pyproject.toml

@@ -41,5 +41,5 @@ strict = true
 mypy_path = "src"
 
 [[tool.mypy.overrides]]
-module = ["jsonschema", "yaml"]
+module = ["jsonschema", "yaml", "hook_lib"]
 ignore_missing_imports = true

scripts/bootstrap_heavy_team.py

@@ -82,7 +82,7 @@ def main() -> int:
                 {
                     "status": "OK",
                     "hook": "bootstrap_heavy_team.py",
-                    "recommended_flow": "triage -> delegate_task(width=3|5|16) -> critique -> synthesize -> verify",
+                    "recommended_flow": "triage -> delegate_task(width=3|5|8|16, default council 8) -> critique -> synthesize -> verify",
                     "enforcement": enforcement,
                     "heavy_council_plugin": plugin_result,
                     "note": "Advisory only; coordinator must follow heavy-team-default skill.",

scripts/team_coordinator.py

@@ -7,47 +7,39 @@
 import sys
 from pathlib import Path
 
-from heavy_coder.profile_config import load_profile_config
+from heavy_coder.profile_config import (
+    coerce_candidate_widths,
+    load_profile_config,
+    parse_default_width,
+)
 from heavy_coder.team_plan import build_team_plan
 from heavy_coder.triage import is_single_mode
 
 
-def _coerce_widths(raw: object) -> tuple[int, ...]:
-    if not isinstance(raw, list):
-        return (3, 5, 16)
-    widths: list[int] = []
-    for item in raw:
-        if isinstance(item, int):
-            widths.append(item)
-        elif isinstance(item, str) and item.strip().isdigit():
-            widths.append(int(item.strip()))
-    return tuple(widths) if widths else (3, 5, 16)
-
-
 def _load_team_plan_kwargs(repo: Path) -> dict[str, object]:
     try:
         profile = load_profile_config(repo)
     except (FileNotFoundError, RuntimeError, ValueError):
+        from heavy_coder.width_policy import DEFAULT_CANDIDATE_WIDTHS, DEFAULT_TRIAGE_WIDTH
+
         return {
             "heavy_council_always": False,
-            "heavy_council_width": 16,
-            "default_width": 3,
-            "allowed_widths": (3, 5, 16),
+            "heavy_council_width": 8,
+            "default_width": DEFAULT_TRIAGE_WIDTH,
+            "allowed_widths": DEFAULT_CANDIDATE_WIDTHS,
         }
 
     from heavy_coder.profile_config import load_yaml_mapping, resolve_config_path
 
     mapping = load_yaml_mapping(resolve_config_path(repo))
     heavy = mapping.get("heavy_coder")
     block = heavy if isinstance(heavy, dict) else {}
-    default_raw = block.get("default_width", 3)
-    default_width = default_raw if isinstance(default_raw, int) else 3
 
     return {
         "heavy_council_always": profile.heavy_council_always,
         "heavy_council_width": profile.council_width,
-        "default_width": default_width,
-        "allowed_widths": _coerce_widths(block.get("candidate_widths")),
+        "default_width": parse_default_width(block),
+        "allowed_widths": coerce_candidate_widths(block.get("candidate_widths")),
     }
 
 
@@ -56,7 +48,7 @@ def main() -> int:
     parser.add_argument("task", nargs="?", help="Task description (or use --task-file)")
     parser.add_argument("--task-file", type=Path, help="Read task from a file")
     parser.add_argument("--repo", type=Path, default=Path("."), help="Target repository root")
-    parser.add_argument("--width", type=int, help="Override triage width (3, 5, or 16 heavy council)")
+    parser.add_argument("--width", type=int, help="Override triage width (must be in candidate_widths, e.g. 3, 5, 8, 16)")
     parser.add_argument(
         "--heavy-council",
         action="store_true",

src/heavy_coder/profile_config.py

@@ -12,10 +12,31 @@
     yaml = None
 
 from heavy_coder.council_injection import CouncilPresentation, parse_council_presentation
+from heavy_coder.width_policy import (
+    DEFAULT_CANDIDATE_WIDTHS,
+    DEFAULT_COUNCIL_WIDTH,
+    DEFAULT_MIN_DELEGATE_TASKS,
+    DEFAULT_TRIAGE_WIDTH,
+    coerce_candidate_widths,
+    parse_default_width,
+)
+
+# Re-export for callers that import from profile_config.
+__all__ = [
+    "DEFAULT_CANDIDATE_WIDTHS",
+    "DEFAULT_COUNCIL_WIDTH",
+    "DEFAULT_MIN_DELEGATE_TASKS",
+    "DEFAULT_TRIAGE_WIDTH",
+    "ProfileConfig",
+    "coerce_candidate_widths",
+    "load_profile_config",
+    "load_yaml_mapping",
+    "parse_default_width",
+    "parse_heavy_coder_block",
+    "resolve_config_path",
+]
 
-DEFAULT_MIN_DELEGATE_TASKS = 8
 DEFAULT_HEAVY_COUNCIL_ALWAYS = False
-DEFAULT_COUNCIL_WIDTH = 8
 
 
 @dataclass(frozen=True)

src/heavy_coder/triage.py

@@ -5,6 +5,8 @@
 import re
 from dataclasses import dataclass
 
+from heavy_coder.width_policy import DEFAULT_CANDIDATE_WIDTHS, DEFAULT_COUNCIL_WIDTH
+
 HIGH_RISK_PATTERNS: tuple[re.Pattern[str], ...] = tuple(
     re.compile(p, re.IGNORECASE)
     for p in (
@@ -63,17 +65,17 @@ def is_single_mode(text: str) -> bool:
 def classify_task(
     task: str,
     *,
-    default_width: int = 3,
-    allowed_widths: tuple[int, ...] = (3, 5, 16),
-    heavy_council_width: int = HEAVY_COUNCIL_WIDTH,
+    default_width: int = DEFAULT_COUNCIL_WIDTH,
+    allowed_widths: tuple[int, ...] = DEFAULT_CANDIDATE_WIDTHS,
+    heavy_council_width: int = DEFAULT_COUNCIL_WIDTH,
     heavy_council_always: bool = False,
 ) -> TriageResult:
     text = task.strip()
     reasons: list[str] = []
     council_w = heavy_council_width if heavy_council_width in allowed_widths else max(allowed_widths)
 
     if any(p.search(text) for p in HEAVY_COUNCIL_PATTERNS):
-        width = council_w
+        width = HEAVY_COUNCIL_WIDTH if HEAVY_COUNCIL_WIDTH in allowed_widths else council_w
         reasons.append("heavy council / Grok Heavy emulation signals in task text")
     elif heavy_council_always and not is_single_mode(text):
         width = council_w

src/heavy_coder/width_policy.py

@@ -0,0 +1,33 @@
+"""Shared council width constants and config parsing (no heavy_coder import cycles)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+DEFAULT_MIN_DELEGATE_TASKS = 8
+DEFAULT_COUNCIL_WIDTH = 8
+DEFAULT_CANDIDATE_WIDTHS: tuple[int, ...] = (3, 5, 8, 16)
+DEFAULT_TRIAGE_WIDTH = 8
+
+
+def coerce_candidate_widths(raw: object) -> tuple[int, ...]:
+    """Parse ``heavy_coder.candidate_widths`` from config (shared by CLI and hooks)."""
+    if not isinstance(raw, list):
+        return DEFAULT_CANDIDATE_WIDTHS
+    widths: list[int] = []
+    for item in raw:
+        if isinstance(item, int) and not isinstance(item, bool):
+            widths.append(item)
+        elif isinstance(item, str) and item.strip().isdigit():
+            widths.append(int(item.strip()))
+    return tuple(widths) if widths else DEFAULT_CANDIDATE_WIDTHS
+
+
+def parse_default_width(block: dict[str, Any] | None, *, fallback: int = DEFAULT_TRIAGE_WIDTH) -> int:
+    heavy = block if isinstance(block, dict) else {}
+    default_raw = heavy.get("default_width", fallback)
+    if isinstance(default_raw, int) and not isinstance(default_raw, bool):
+        return default_raw
+    if isinstance(default_raw, str) and default_raw.strip().isdigit():
+        return int(default_raw.strip())
+    return fallback