feat(plugins): per-skill compaction contracts + advisorModel sync

Two capabilities plus bundled in-flight tree changes, committed together at the user's request. Every touched plugin takes a minor (new-capability) bump: foundry 0.31.6→0.32.0, oss 0.17.8→0.18.0, develop 0.11.7→0.12.0, research 0.9.5→0.10.0.

Per-skill compaction contracts — survive auto-compaction losslessly:
- Context auto-compacts at 85% and previously preserved only modified-file paths, so a compaction landing mid-workflow (parallel fan-out, iteration loop, large gather) could drop the distilled hand-off the next phase needs. There is no skill-invokable /compact, so the design rides auto-compact: skills keep a contract file fresh at expanding-phase boundaries and the hook stages it verbatim.
- The PreCompact hook (plugins/foundry/hooks/task-log.js) now reads .claude/state/skill-contract.md and appends it verbatim under a "## Skill Compaction Contract" section of session-context.md, which CLAUDE.md re-reads after compaction and now treats as an authoritative skill hand-off. Same change also fixes a pre-existing bug where the hook's full rewrite clobbered foundry:session's "## Parked items" — those are now carried over idempotently.
- New shared convention: plugins/foundry/rules/compaction.md (the verbatim-file principle, placement, clear-on-completion) and plugins/foundry/skills/_shared/compaction-contract.md (the block template + acceptance criteria).
- Adopted in 19 phased skills, each with a custom checkpoint tuned to its flow — fan-out→consolidate (oss:review, develop:review, foundry:audit, foundry:calibrate), iteration loops (research:run/sweep/fortify/kaggle, oss:resolve), discovery→edit→review (develop:feature/fix/refactor/debug), and gather→synthesize (oss:analyse, research:topic/judge, foundry:brainstorm/investigate/distill). Each gains a "# loads:" ref, a <compaction> block, boundary contract-writes, an optional --keep "<items>" arg to pin extra preserve items per invocation, and clear-on-completion. Single-shot/mechanical skills (codemap:*, foundry:session/setup/profile, research:plan/verify/retro) are excluded.

advisorModel sync via /foundry:setup:
- /advisor writes advisorModel only to the global ~/.claude/settings.json; sync.sh never propagated it. foundry:setup gains a Step 8 that reads a project-pinned advisorModel from ./.claude/settings.json and merges it into global, so the preference now travels with the repo. Pinned in this project's .claude/settings.json ("fable").

Bundled maintenance (in-flight tree work, committed together — not individually reviewed as part of the compaction change):
- chore: pre-commit toolchain upgrade — ruff v0.11.4→v0.15.20, eslint v10.2.0→v10.6.0, check-added-large-files maxkb 125→250 — plus the resulting ruff auto-formatting/fixes across plugin bin/ and tests/ files.
- fix: hardened shared flag parsing (develop dev_parse_args.py and peers) — full flag-token match via negative lookbehind so e.g. `--planets` no longer satisfies `--plan` and a flag is not consumed as another flag's value.
- test: additional benchmark tests under benchmarks/tests/ (~380 lines).

Verification (compaction): 16 hook tests pass; all 19 skills pass marker + tag-balance + orphan-safety checks; cross-plugin propagation in sync; --keep frontmatter valid. Contract survival is deterministic once written; timing rides auto-compact (a compaction before a skill's first boundary keeps only the generic files breadcrumb — stated limitation).

---
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

Author: Borda

.claude/README.md

@@ -67,7 +67,7 @@ claude plugin install codemap@borda-ai-rig
 /foundry:setup
 ```
 
-This merges `statusLine`, `permissions.allow`, and `enabledPlugins` (codex plugin) into `~/.claude/settings.json`; symlinks `rules/*.md` and `TEAM_PROTOCOL.md` into `~/.claude/`. Agents, skills, and hooks are exposed natively by the Claude Code plugin system — no symlinks needed.
+This merges `statusLine`, `permissions.allow`, `enabledPlugins` (codex plugin), and `advisorModel` into `~/.claude/settings.json`; symlinks `rules/*.md` and `TEAM_PROTOCOL.md` into `~/.claude/`. Agents, skills, and hooks are exposed natively by the Claude Code plugin system — no symlinks needed.
 
 **What is restored:** `~/.claude/rules/*.md` and `~/.claude/TEAM_PROTOCOL.md` become symlinks into the installed foundry plugin. `~/.claude/settings.json` is updated in-place. All other plugin files (agents, skills, hooks, CLAUDE.md) are served directly by the plugin system. The only local-machine files are `settings.local.json` and `settings.json` (project prefs + permissions).
 
@@ -92,7 +92,7 @@ plugins/foundry/           ← source of truth
 
 ```text
 /foundry:setup   # symlink rules/*.md + TEAM_PROTOCOL.md → ~/.claude/;
-                # merge statusLine, permissions.allow, enabledPlugins → ~/.claude/settings.json
+                # merge statusLine, permissions.allow, enabledPlugins, advisorModel → ~/.claude/settings.json
                 # (re-run after plugin upgrade to refresh stale rule symlinks)
 ```
 
@@ -495,7 +495,6 @@ A native research harness for questions that need real sourcing rather than a si
 - **Don't use it** for a single-fact lookup (a normal web search or an inline answer is faster) or for anything answerable from the codebase (use `/codemap:query-code`, grep, or a direct read).
 - **Scope first** — if the question is underspecified (e.g. "what car should I buy" with no budget / use-case / region), it will ask 2-3 clarifying questions before spending the search budget. Giving those constraints up front produces a sharper report.
 
-
 ## 🗺️ Plugin dependency matrix
 
 <details>

.claude/settings.json

@@ -1,4 +1,5 @@
 {
+  "advisorModel": "fable",
   "autoUpdatesChannel": "stable",
   "effortLevel": "high",
   "env": {

.pre-commit-config.yaml

@@ -34,7 +34,7 @@ repos:
         name: 🔤 check-case-conflict
       - id: check-added-large-files
         name: 📦 check-added-large-files
-        args: ["--maxkb=125", "--enforce-all"]
+        args: ["--maxkb=250", "--enforce-all"]
       - id: detect-private-key
         name: 🔐 detect-private-key
       - id: check-merge-conflict
@@ -56,7 +56,7 @@ repos:
         args: ["--print-width=120"]
 
   - repo: https://github.com/pre-commit/mirrors-eslint
-    rev: v10.2.0
+    rev: v10.6.0
     hooks:
       - id: eslint
         name: 🛡️ eslint
@@ -66,10 +66,10 @@ repos:
           - "@eslint/js@9.21.0"
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.4
+    rev: v0.15.20
     hooks:
-      - id: ruff
-        name: 🦀 ruff
+      - id: ruff-check
+        name: 🦀 ruff-check
         args: ["--fix"]
       - id: ruff-format
         name: 🦀 ruff-format

README.md

@@ -461,7 +461,7 @@ claude plugin install research@borda-ai-rig
 claude plugin install codemap@borda-ai-rig
 ```
 
-Re-run `/foundry:setup` only if permissions or `enabledPlugins` changed. Re-run `/foundry:setup` if you previously used the link mode — symlinks point to the old plugin cache after an upgrade.
+Re-run `/foundry:setup` only if permissions, `enabledPlugins`, or `advisorModel` changed. Re-run `/foundry:setup` if you previously used the link mode — symlinks point to the old plugin cache after an upgrade.
 
 ### Session-only (no install, for development)
 

benchmarks/generate-tasks-bench.py

@@ -1124,8 +1124,16 @@ def _validate_oss(task: dict, sq: Path, index: Path, repo: Path) -> tuple[bool,
         data = run_scan_query(sq, ["undocumented"] + q.get("args", []), index, repo)
         if data is None:
             return False, None, "scan-query undocumented returned None"
+        if not isinstance(data.get("total"), int):
+            return False, None, "undocumented total is missing or not an int"
+        if not isinstance(data.get("undocumented"), list):
+            return False, None, "undocumented result is missing or not a list"
+        if any(not isinstance(e, dict) for e in data["undocumented"]):
+            return False, None, "undocumented result contains non-object entries"
         scan_count = data.get("total", 0)
         scan_syms = [e.get("qualified_name", "") for e in data.get("undocumented", [])]
+        if scan_count != len(scan_syms):
+            return False, None, "undocumented total conflicts with symbol count"
         if check == "undocumented":
             # AST oracle is authoritative (review C-2) — scan-query is the tool under test.
             module = next((a for a in q.get("args", []) if not str(a).startswith("-")), None)
@@ -1149,8 +1157,16 @@ def _validate_oss(task: dict, sq: Path, index: Path, repo: Path) -> tuple[bool,
         data = run_scan_query(sq, ["uncovered"] + q.get("args", []), index, repo)
         if data is None:
             return False, None, "scan-query uncovered returned None"
+        if not isinstance(data.get("total"), int):
+            return False, None, "uncovered total is missing or not an int"
+        if not isinstance(data.get("uncovered"), list):
+            return False, None, "uncovered result is missing or not a list"
+        if any(not isinstance(e, dict) for e in data["uncovered"]):
+            return False, None, "uncovered result contains non-object entries"
         scan_count = data.get("total", 0)
         scan_syms = [e.get("qualified_name", "") for e in data.get("uncovered", [])]
+        if scan_count != len(scan_syms):
+            return False, None, "uncovered total conflicts with symbol count"
         if check == "uncovered":
             # AST oracle is authoritative (review C-2 remainder) — scan-query is the tool under test.
             module = next((a for a in q.get("args", []) if not str(a).startswith("-")), None)
@@ -1189,9 +1205,13 @@ def _validate_oss(task: dict, sq: Path, index: Path, repo: Path) -> tuple[bool,
         if data is None:
             return False, None, "scan-query coupled returned None"
         coupled = data.get("coupled", [])
+        if not isinstance(coupled, list):
+            return False, None, "coupled result is not a list"
         if not coupled:
             return False, None, "coupled result is empty"
         top = coupled[0]
+        if not isinstance(top, dict):
+            return False, None, "coupled top result is not an object"
         live_gt["top_module"] = top.get("name", "")
         live_gt["top_dep_count"] = top.get("dep_count", 0)
         live_gt["top_internal_dep_count"] = top.get("internal_dep_count", 0)
@@ -1222,7 +1242,15 @@ def _validate_oss(task: dict, sq: Path, index: Path, repo: Path) -> tuple[bool,
         if data is None:
             return False, None, "scan-query xrefs returned None"
         broken = data.get("broken", [])
+        if not isinstance(broken, list):
+            return False, None, "xrefs broken result is not a list"
+        if any(not isinstance(b, dict) for b in broken):
+            return False, None, "xrefs broken result contains non-object entries"
         live_count = data.get("count", len(broken))
+        if not isinstance(live_count, int):
+            return False, None, "xrefs broken count is not an int"
+        if live_count != len(broken):
+            return False, None, "xrefs broken count conflicts with target count"
         live_targets = [{"target": b.get("target", ""), "line": b.get("line", 0)} for b in broken]
         live_gt["broken_count"] = live_count
         live_gt["broken_targets"] = live_targets

benchmarks/run-codemap-bench.py

@@ -549,10 +549,13 @@ def _parse_scan_query_subcommand(command: str) -> Optional[str]:
         tokens = shlex.split(command)
     except ValueError:
         tokens = command.split()
-    # Locate the scan-query token (may be a path like .../bin/scan-query).
+    # Locate the scan-query executable token (may be a path like .../bin/scan-query).
     start = None
+    allowed_prefix = {"env", "command", "time"}
     for i, tok in enumerate(tokens):
         if tok == "scan-query" or tok.endswith("/scan-query"):
+            if any(prev not in allowed_prefix and "=" not in prev for prev in tokens[:i]):
+                continue
             start = i + 1
             break
     if start is None:
@@ -561,11 +564,12 @@ def _parse_scan_query_subcommand(command: str) -> Optional[str]:
     while i < len(tokens):
         tok = tokens[i]
         if tok.startswith("-"):
-            # Skip a flag; if its value is a separate token (not another flag), skip it too.
-            if "=" not in tok and i + 1 < len(tokens) and not tokens[i + 1].startswith("-"):
+            if tok == "--index" and i + 1 < len(tokens) and not tokens[i + 1].startswith("-"):
                 i += 2
-            else:
+            elif tok.startswith("--index="):
                 i += 1
+            else:
+                return None
             continue
         return tok if tok in _SCAN_QUERY_SUBCOMMANDS else None
     return None
@@ -736,7 +740,7 @@ def _ri_file_matches(file_path: str, region: str) -> bool:
     if len(parts) >= 2:
         candidates.add(f"{parts[-2]}/{parts[-1]}")
         candidates.add(f"{parts[-2]}/{stem}")
-    return any(cand in region for cand in candidates)
+    return any(re.search(r"(?<![\w/.-])" + re.escape(cand) + r"(?![\w/.-])", region) for cand in candidates)
 
 
 def _extract_int(text: str, patterns: list[str]) -> Optional[int]:
@@ -802,7 +806,7 @@ def _int_close(got: Optional[int], expected: int, tolerance: float = 0.10) -> bo
         >>> _int_close(None, 40)
         False
     """
-    if got is None:
+    if got is None or not isinstance(expected, (int, float)):
         return False
     return abs(got - expected) / max(expected, 1) <= tolerance
 

benchmarks/run-codemap-cli.py

@@ -1055,14 +1055,20 @@ def validate_central_json(data: dict) -> ValidationResult:
         :class:`ValidationResult` with ``ok=True`` on success, or ``ok=False``
         and a reason string describing the first structural violation found.
     """
+    if not isinstance(data, dict):
+        return ValidationResult(ok=False, reason="response is not an object")
     if "central" not in data:
         return ValidationResult(ok=False, reason="missing 'central' key")
     central = data["central"]
     if not isinstance(central, list) or len(central) == 0:
         return ValidationResult(ok=False, reason="'central' is empty or not a list")
     for item in central:
+        if not isinstance(item, dict):
+            return ValidationResult(ok=False, reason="central item is not an object")
         if "rdep_count" not in item:
             return ValidationResult(ok=False, reason="central item missing 'rdep_count'")
+        if not isinstance(item["rdep_count"], int):
+            return ValidationResult(ok=False, reason="central item 'rdep_count' is not an int")
     return ValidationResult(ok=True, reason="")
 
 
@@ -1078,10 +1084,16 @@ def validate_rdeps_json(data: dict) -> ValidationResult:
         :class:`ValidationResult` with ``ok=True`` on success, or ``ok=False``
         and a reason string describing the missing key.
     """
+    if not isinstance(data, dict):
+        return ValidationResult(ok=False, reason="response is not an object")
     if "imported_by" not in data:
         return ValidationResult(ok=False, reason="missing 'imported_by' key")
     if "module" not in data:
         return ValidationResult(ok=False, reason="missing 'module' key")
+    if not isinstance(data["imported_by"], list):
+        return ValidationResult(ok=False, reason="'imported_by' is not a list")
+    if not isinstance(data["module"], str):
+        return ValidationResult(ok=False, reason="'module' is not a string")
     return ValidationResult(ok=True, reason="")
 
 
@@ -1097,10 +1109,16 @@ def validate_deps_json(data: dict) -> ValidationResult:
         :class:`ValidationResult` with ``ok=True`` on success, or ``ok=False``
         and a reason string describing the missing key.
     """
+    if not isinstance(data, dict):
+        return ValidationResult(ok=False, reason="response is not an object")
     if "direct_imports" not in data:
         return ValidationResult(ok=False, reason="missing 'direct_imports' key")
     if "module" not in data:
         return ValidationResult(ok=False, reason="missing 'module' key")
+    if not isinstance(data["direct_imports"], list):
+        return ValidationResult(ok=False, reason="'direct_imports' is not a list")
+    if not isinstance(data["module"], str):
+        return ValidationResult(ok=False, reason="'module' is not a string")
     return ValidationResult(ok=True, reason="")
 
 

benchmarks/tests/test_generate_tasks_bench.py

@@ -1050,6 +1050,57 @@ def test_scan_query_failure_returns_none(self, script_gen_bench: Any, tmp_path:
         assert ok is False
         assert live_gt is None
 
+    @pytest.mark.parametrize(
+        "task,payload,reason_fragment",
+        [
+            (
+                _task_undocumented(None, 0, []),
+                {"undocumented": []},
+                "total",
+            ),
+            (
+                _task_uncovered(None, 0, []),
+                {"total": 0, "uncovered": "not a list"},
+                "list",
+            ),
+            (
+                _task_undocumented(None, 2, ["A", "B"]),
+                {"total": 2, "undocumented": [{"qualified_name": "A"}]},
+                "conflicts",
+            ),
+            (
+                _task_coupled(None, "mod", 1, 0),
+                {"coupled": "not a list"},
+                "not a list",
+            ),
+            (
+                _task_coupled(None, "mod", 1, 0),
+                {"coupled": [1]},
+                "not an object",
+            ),
+            (
+                _task_xrefs(None, 2, [{"target": "mod::Fn", "line": 1}, {"target": "mod::Other", "line": 2}]),
+                {"count": 2, "broken": [{"target": "mod::Fn", "line": 1}]},
+                "conflicts",
+            ),
+        ],
+    )
+    def test_malformed_scan_query_payloads_fail_cleanly(
+        self,
+        script_gen_bench: Any,
+        tmp_path: Path,
+        task: dict,
+        payload: dict,
+        reason_fragment: str,
+    ) -> None:
+        """Missing keys, wrong types, and count/list conflicts return failures, not crashes."""
+        with patch.object(script_gen_bench, "run_scan_query", return_value=payload):
+            ok, live_gt, reason = script_gen_bench._validate_oss(task, MagicMock(), tmp_path / "idx.json", tmp_path)
+
+        assert ok is False
+        assert live_gt is None
+        assert reason_fragment in reason
+
     def test_combined_health_validates_both_counts(self, script_gen_bench: Any, tmp_path: Path) -> None:
         """Validates both undocumented and uncovered fields for combined_health check.
 

benchmarks/tests/test_generate_tasks_real_issues.py

@@ -726,3 +726,72 @@ def test_no_warning_when_closing_pr_available(
         result = script_gen_real_issues.resolve_merged_pr([101], 1, 5, issue_number=42)
         assert result.closes_issue is True
         assert "weak provenance" not in capsys.readouterr().err
+
+
+# ===========================================================================
+# class TestInspectPrSourceFiltering
+# ===========================================================================
+
+
+class TestInspectPrSourceFiltering:
+    """Tests for _inspect_pr source-file filtering using mocked GitHub data."""
+
+    def test_filters_test_files_and_records_source_change_sizes(
+        self, script_gen_real_issues: Any, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Only non-test Python files become source ground truth; change sizes are retained."""
+
+        def _fake_gh_json(args: list[str], timeout: int = 60) -> dict:
+            return {
+                "state": "MERGED",
+                "mergedAt": "2026-01-01T00:00:00Z",
+                "body": "Fixes #42",
+                "files": [
+                    {"path": "src/pkg/core.py", "additions": 3, "deletions": 2},
+                    {"path": "tests/test_core.py", "additions": 100, "deletions": 0},
+                    {"path": "docs/guide.md", "additions": 9, "deletions": 1},
+                ],
+            }
+
+        monkeypatch.setattr(script_gen_real_issues, "_gh_json", _fake_gh_json)
+
+        result = script_gen_real_issues._inspect_pr(123, min_py=1, max_py=5, issue_number=42)
+
+        assert result is not None
+        assert result.source_files == ["src/pkg/core.py"]
+        assert result.py_file_count == 2
+        assert result.source_changes == {"src/pkg/core.py": 5}
+        assert result.closes_issue is True
+
+    def test_all_test_files_returns_none(self, script_gen_real_issues: Any, monkeypatch: pytest.MonkeyPatch) -> None:
+        """A PR with Python changes only in tests is not a source-backed task."""
+
+        def _fake_gh_json(args: list[str], timeout: int = 60) -> dict:
+            return {
+                "state": "MERGED",
+                "mergedAt": "2026-01-01T00:00:00Z",
+                "body": "Fixes #42",
+                "files": [
+                    {"path": "tests/test_core.py", "additions": 10, "deletions": 0},
+                    {"path": "src/pkg/core_test.py", "additions": 1, "deletions": 1},
+                ],
+            }
+
+        monkeypatch.setattr(script_gen_real_issues, "_gh_json", _fake_gh_json)
+
+        assert script_gen_real_issues._inspect_pr(123, min_py=1, max_py=5, issue_number=42) is None
+
+    def test_no_python_files_returns_none(self, script_gen_real_issues: Any, monkeypatch: pytest.MonkeyPatch) -> None:
+        """A PR without Python files cannot produce Python source ground truth."""
+
+        def _fake_gh_json(args: list[str], timeout: int = 60) -> dict:
+            return {
+                "state": "MERGED",
+                "mergedAt": "2026-01-01T00:00:00Z",
+                "body": "Fixes #42",
+                "files": [{"path": "README.md", "additions": 10, "deletions": 0}],
+            }
+
+        monkeypatch.setattr(script_gen_real_issues, "_gh_json", _fake_gh_json)
+
+        assert script_gen_real_issues._inspect_pr(123, min_py=1, max_py=5, issue_number=42) is None