@event4u/agent-config 5.2.0 → 5.4.0

package/scripts/check_artefact_checksums.py

@@ -32,15 +32,22 @@ DEFAULT_MANIFEST = ROOT / "dist" / "discovery" / "discovery-manifest.json"
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 # Import the same hashing primitive the builder uses so normalisation
 # stays in lockstep with the generator. (ADR-015 §Phase 6.)
-from build_discovery_manifest import _artefact_checksum  # noqa: E402
-from validate_frontmatter import parse_frontmatter  # noqa: E402
+from build_discovery_manifest import _CATEGORY_SCHEMA, _artefact_checksum  # noqa: E402
+from validate_frontmatter import apply_schema_defaults, load_schema, parse_frontmatter  # noqa: E402
 
 
-def _frontmatter(path: Path) -> dict | None:
+def _frontmatter(path: Path, category: str | None = None) -> dict | None:
     if not path.exists():
         return None
     text = path.read_text(encoding="utf-8", errors="replace")
     fm, _ = parse_frontmatter(text)
+    # Inject the same schema defaults the builder injects, so the recomputed
+    # checksum matches the committed manifest byte-for-byte even when the
+    # artefact omits a defaulted field (preflight Decision B).
+    if isinstance(fm, dict):
+        schema_name = _CATEGORY_SCHEMA.get(category or "")
+        if schema_name is not None:
+            apply_schema_defaults(fm, load_schema(schema_name))
     return fm
 
 
@@ -64,7 +71,7 @@ def _check(manifest_path: Path) -> tuple[int, list[str]]:
         if not src.exists():
             errors.append(f"{rel}: source file missing")
             continue
-        actual = _artefact_checksum(src, _frontmatter(src))
+        actual = _artefact_checksum(src, _frontmatter(src, art.get("category")))
         if actual != recorded:
             errors.append(
                 f"{rel}: checksum drift "

package/scripts/check_release_pr_shape.py

@@ -9,6 +9,7 @@ and asserts every changed file matches the version-bump allowlist:
   * `.claude-plugin/marketplace.json`
   * `packages/*/pack.yaml`
   * `packages/*/README.md`
+  * `docs/archive/CHANGELOG-pre-*.md`
 
 Exit codes:
 
@@ -40,6 +41,12 @@ ALLOWLIST_GLOBS = (
     ".claude-plugin/marketplace.json",
     "packages/*/pack.yaml",
     "packages/*/README.md",
+    # `scripts/release.py` auto-splits the CHANGELOG era before bumping
+    # (perform_split / plan_split in `_lib/changelog_eras.py`) whenever the
+    # current era body crosses CURRENT_ERA_BODY_CAP. The split emits a new
+    # `docs/archive/CHANGELOG-pre-X.Y.Z.md` — part of the release surface,
+    # so the shape gate must allow it. Test-enforced by test_changelog_eras.
+    "docs/archive/CHANGELOG-pre-*.md",
 )
 
 

package/scripts/condense.py

@@ -574,7 +574,12 @@ def _parse_trust_and_owner(fm_lines):
     prefix (`finance-basic` → `finance`), then the first workspace,
     then `unknown`.
     """
-    level = None
+    # Default to the schema default `core` so the HUMAN REVIEW banner still
+    # renders if a future artefact sets `human_review_required: true` while
+    # omitting the (defaulted) `trust.level` line (abstraction-reduction
+    # preflight Decision D). The banner only fires when `hrr` is true, so this
+    # never affects artefacts that omit the whole trust block.
+    level = "core"
     hrr = False
     packs: list[str] = []
     workspaces: list[str] = []
@@ -871,8 +876,72 @@ def _iter_commands():
         yield source_file, _command_slug(source_file)
 
 
+# --- Per-skill model auto-switch (ADR-035 / road-to-model-capability-tiers) ---
+
+# The SINGLE generator-owned tier→Claude-model mapping (ADR-035 § 3). Claude
+# Code is the only surface that consumes a native `model:`, so this is the only
+# place a capability tier resolves to a concrete model. `inherit`/absent emit
+# nothing and stay pure symlinks. Non-Claude agents never get a per-vendor
+# table — the rule surfaces the tier name as a suggestion.
+_TIER_TO_CLAUDE_MODEL = {"high": "opus", "medium": "sonnet", "lite": "haiku"}
+_MODEL_TIER_RE = re.compile(r'^model_tier:\s*"?([a-z]+)"?\s*$', re.MULTILINE)
+
+
+def _read_model_auto_switch() -> str:
+    """Read `model.auto_switch` from .agent-settings.yml.
+
+    Returns `auto` | `suggest` | `off`; default `suggest`. Only `auto` makes
+    the generator emit a native Claude `model:` key (ADR-034 § 4) — `suggest`
+    and `off` keep skills/commands as pure symlinks so the package never
+    silently overrides a user's explicit `/model` choice.
+    """
+    try:
+        from scripts._lib.agent_settings import load_agent_settings
+    except ImportError:  # pragma: no cover — script-style invocation
+        import sys as _sys
+        from pathlib import Path as _Path
+        _sys.path.insert(0, str(_Path(__file__).resolve().parent))
+        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
+    data = load_agent_settings(project_path=SETTINGS_FILE)
+    model = data.get("model")
+    value = model.get("auto_switch") if isinstance(model, dict) else None
+    if isinstance(value, str) and value.strip().lower() in ("auto", "suggest", "off"):
+        return value.strip().lower()
+    return "suggest"
+
+
+def _model_tier(skill_md: Path) -> str | None:
+    """Return the `model_tier` frontmatter value, or None if absent."""
+    if not skill_md.exists():
+        return None
+    text = skill_md.read_text(encoding="utf-8", errors="replace")
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return None
+    m = _MODEL_TIER_RE.search(text[4:end])
+    return m.group(1) if m else None
+
+
+def _render_native_model_md(src_md: Path, tier: str) -> str:
+    """Rewrite the source `model_tier: <tier>` line to a native Claude
+    `model: <mapped>` key via the generator-owned mapping (ADR-035 § 3). The
+    rest of the SKILL.md is byte-identical."""
+    text = src_md.read_text(encoding="utf-8")
+    model = _TIER_TO_CLAUDE_MODEL[tier]
+    return _MODEL_TIER_RE.sub(f"model: {model}", text, count=1)
+
+
 def generate_claude_skills() -> int:
-    """Create .claude/skills/ symlinks for ALL skills in .agent-src/skills/.
+    """Create .claude/skills/ entries for ALL skills in .agent-src/skills/.
+
+    Default: a directory symlink → .agent-src/skills/<name> (verbatim).
+    When `model.auto_switch: auto` AND a skill declares
+    `model_tier: lite|medium|high`, the entry becomes a real directory whose
+    sub-files are symlinked but whose SKILL.md is a rendered copy carrying a
+    native Claude `model:` key (ADR-034 Option (b) — only model-bearing skills
+    break the symlink). Idempotent: each entry is rebuilt from scratch.
     """
     if not SKILLS_SOURCE.exists():
         print("  ⚠️  .agent-src/skills/ not found — skipping skills", file=sys.stderr)
@@ -880,26 +949,58 @@ def generate_claude_skills() -> int:
 
     # All skill directories in .agent-src/skills/
     skills = sorted([d.name for d in SKILLS_SOURCE.iterdir() if d.is_dir()])
+    skill_set = set(skills)
     # All command slugs (to protect from stale cleanup)
     command_slugs = {slug for _, slug in _iter_commands()}
 
     CLAUDE_SKILLS_DIR.mkdir(parents=True, exist_ok=True)
+    auto = _read_model_auto_switch() == "auto"
 
-    # Clean stale symlinks (but not converted commands or README)
+    # Clean stale entries (symlinks AND rendered skill dirs) — but never touch
+    # command dirs (real dir whose SKILL.md is a symlink) or the README.
     for item in CLAUDE_SKILLS_DIR.iterdir():
-        if item.is_symlink() and item.name not in skills and item.name not in command_slugs and item.name != "README.md":
+        if item.name in skill_set or item.name in command_slugs or item.name == "README.md":
+            continue
+        if item.is_symlink():
             item.unlink()
+        elif item.is_dir():
+            skill_md = item / "SKILL.md"
+            # A rendered skill dir has a *real* SKILL.md copy; a command dir has
+            # a SKILL.md *symlink* (left for generate_claude_commands to manage).
+            if skill_md.is_file() and not skill_md.is_symlink():
+                shutil.rmtree(item)
 
     count = 0
+    rendered = 0
     for skill in skills:
         link = CLAUDE_SKILLS_DIR / skill
-        if link.exists() or link.is_symlink():
+        src_dir = SKILLS_SOURCE / skill
+        value = _model_tier(src_dir / "SKILL.md") if auto else None
+        # Rebuild from scratch for idempotency (symlink ↔ rendered-dir flips).
+        if link.is_symlink():
             link.unlink()
-        rel_target = Path("../../.agent-src/skills") / skill
-        link.symlink_to(rel_target)
+        elif link.is_dir():
+            shutil.rmtree(link)
+        elif link.exists():
+            link.unlink()
+        if value in _TIER_TO_CLAUDE_MODEL:
+            link.mkdir(parents=True)
+            for entry in sorted(src_dir.iterdir()):
+                if entry.name == "SKILL.md":
+                    (link / "SKILL.md").write_text(
+                        _render_native_model_md(entry, value), encoding="utf-8"
+                    )
+                else:
+                    (link / entry.name).symlink_to(
+                        Path("../../../.agent-src/skills") / skill / entry.name
+                    )
+            rendered += 1
+        else:
+            link.symlink_to(Path("../../.agent-src/skills") / skill)
         count += 1
 
-    info(f"  ✅  Created {count} skill symlinks in .claude/skills/")
+    suffix = f" ({rendered} rendered with native model:)" if rendered else ""
+    info(f"  ✅  Created {count} skill entries in .claude/skills/{suffix}")
     return count
 
 
@@ -940,6 +1041,8 @@ def generate_claude_commands() -> int:
     current_slugs: set[str] = set()
     count = 0
     skipped = 0
+    rendered = 0
+    auto = _read_model_auto_switch() == "auto"
     for source_file, slug in _iter_commands():
         # Skip if a real skill with the same name exists — skill takes priority
         if slug in skill_names:
@@ -948,7 +1051,7 @@ def generate_claude_commands() -> int:
 
         current_slugs.add(slug)
 
-        # Create skill directory (real dir, symlinked SKILL.md inside)
+        # Create skill directory (real dir, SKILL.md symlinked or rendered)
         skill_dir = CLAUDE_SKILLS_DIR / slug
         skill_dir.mkdir(parents=True, exist_ok=True)
 
@@ -956,10 +1059,18 @@ def generate_claude_commands() -> int:
         if skill_file.exists() or skill_file.is_symlink():
             skill_file.unlink()
 
-        # Symlink: .claude/skills/{slug}/SKILL.md → ../../../.agent-src/commands/<rel-path>
         rel_path = source_file.relative_to(COMMANDS_SOURCE)
-        rel_target = Path("../../../.agent-src/commands") / rel_path
-        skill_file.symlink_to(rel_target)
+        value = _model_tier(source_file) if auto else None
+        if value in _TIER_TO_CLAUDE_MODEL:
+            # Render a copy carrying the native Claude model: key (ADR-034).
+            skill_file.write_text(
+                _render_native_model_md(source_file, value), encoding="utf-8"
+            )
+            rendered += 1
+        else:
+            # Symlink: .claude/skills/{slug}/SKILL.md → ../../../.agent-src/commands/<rel-path>
+            rel_target = Path("../../../.agent-src/commands") / rel_path
+            skill_file.symlink_to(rel_target)
         count += 1
 
     # Clean stale command skill directories — real dirs from removed commands.
@@ -971,14 +1082,20 @@ def generate_claude_commands() -> int:
         if item.name in skill_names or item.name in current_slugs:
             continue
         skill_md = item / "SKILL.md"
-        if skill_md.is_symlink():
+        # Stale command dir = exactly one SKILL.md, either symlinked (default)
+        # or a rendered copy (native-model command, ADR-034). Skill-render dirs
+        # are protected above (item.name in skill_names) and via the skills
+        # generator, so this only reaps removed commands.
+        if skill_md.is_symlink() or skill_md.is_file():
             entries = list(item.iterdir())
             if len(entries) == 1 and entries[0].name == "SKILL.md":
                 skill_md.unlink()
                 item.rmdir()
                 removed_dirs += 1
 
-    msg = f"  ✅  Created {count} command symlinks in .claude/skills/"
+    msg = f"  ✅  Created {count} command entries in .claude/skills/"
+    if rendered:
+        msg += f" ({rendered} rendered with native model:)"
     if skipped:
         msg += f" ({skipped} skipped — same-name skill exists)"
     if removed_dirs:
@@ -1075,8 +1192,12 @@ def generate_plugin_hooks() -> int:
     ``settings.local.json``. Claude Code merges plugin-scope and
     settings-scope hooks and dedups by command string.
 
-    The command is rooted at ``$CLAUDE_PROJECT_DIR`` so it resolves from
-    plugin scope regardless of cwd; the universal dispatcher then reads
+    The command resolves the binary project-local-first
+    (``$CLAUDE_PROJECT_DIR/agent-config`` when executable — maintainer dev-loop)
+    and falls back to ``agent-config`` on PATH (global-only consumer per
+    ADR-020, where the repo carries no wrapper). It always passes
+    ``--project-dir "$CLAUDE_PROJECT_DIR"`` so a globally resolved binary still
+    scans the project the event fired in. The universal dispatcher then reads
     ``scripts/hook_manifest.yaml`` at runtime to fan out to the active
     concerns (each a no-op when its feature is disabled).
     """
@@ -1087,6 +1208,7 @@ def generate_plugin_hooks() -> int:
         return 0
 
     manifest = yaml.safe_load(manifest_path.read_text(encoding="utf-8")) or {}
+    hook_spec = manifest.get("schema_version", 1)
     claude_events = manifest.get("platforms", {}).get("claude", {}) or {}
     aliases = manifest.get("native_event_aliases", {}).get("claude", {}) or {}
     # Reverse the native→agent-config map so we can emit native event names.
@@ -1099,9 +1221,17 @@ def generate_plugin_hooks() -> int:
         native = ac_to_native.get(ac_event)
         if native is None:
             continue
+        # Resolve the binary project-local-first, PATH-fallback: a maintainer
+        # dev-loop (or any repo carrying a project-local wrapper) uses its own
+        # ./agent-config; a global-only consumer (ADR-020 — nothing in the
+        # repo) falls back to the globally-installed `agent-config` on PATH.
+        # Either way pass --project-dir "$CLAUDE_PROJECT_DIR" so a globally
+        # resolved binary still scans the project the event fired in.
         command = (
-            '"$CLAUDE_PROJECT_DIR"/agent-config dispatch:hook '
-            f"--platform claude --event {ac_event} --native-event {native}"
+            'BIN="$CLAUDE_PROJECT_DIR/agent-config"; [ -x "$BIN" ] || BIN=agent-config; '
+            f'"$BIN" dispatch:hook --platform claude --event {ac_event} '
+            f'--native-event {native} --project-dir "$CLAUDE_PROJECT_DIR" '
+            f'--min-version {hook_spec}'
         )
         hooks[native] = [{"hooks": [{"type": "command", "command": command}]}]
 

package/scripts/hooks/dispatch_hook.py

@@ -349,8 +349,36 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--manifest", default=str(MANIFEST_PATH))
     parser.add_argument("--dry-run", action="store_true",
                         help="Resolve concerns and print plan; do not invoke them.")
+    parser.add_argument("--project-dir", default="",
+                        help="Project root the event fired in (the Claude "
+                             "plugin passes $CLAUDE_PROJECT_DIR). A globally "
+                             "resolved binary (ADR-020 global-only) has no "
+                             "implicit project context, so concerns are "
+                             "resolved relative to this directory.")
+    parser.add_argument("--min-version", type=int, default=0,
+                        help="Minimum hook-spec (manifest schema_version) the "
+                             "caller — typically the Claude marketplace plugin "
+                             "— was generated against. Plugin and binary update "
+                             "on independent cadences; when the binary's "
+                             "manifest is older than the plugin expects, warn "
+                             "(never block).")
     args = parser.parse_args(argv)
 
+    # Honour --project-dir: chdir so workspace_root (envelope) and every
+    # concern's cwd resolve consumer-local paths (agents/roadmaps/,
+    # agents/runtime/state/) against the project the event fired in, not the
+    # cwd a globally-installed binary happened to inherit. Fail loud (never
+    # block) when the path is bad — a wrong project root is a silent-no-op
+    # trap otherwise.
+    if args.project_dir:
+        project_dir = Path(args.project_dir).expanduser()
+        if project_dir.is_dir():
+            os.chdir(project_dir)
+        else:
+            sys.stderr.write(
+                f"dispatch_hook: --project-dir is not a directory: "
+                f"{project_dir} — resolving against cwd {Path.cwd()}\n")
+
     if args.event not in EVENT_VOCABULARY:
         sys.stderr.write(f"dispatch_hook: unknown event '{args.event}'; allowed: "
                          f"{sorted(EVENT_VOCABULARY)}\n")
@@ -362,6 +390,17 @@ def main(argv: list[str] | None = None) -> int:
         return EXIT_ALLOW
     manifest = _load_yaml(manifest_path)
 
+    # Plugin↔binary drift guard (never blocks). The Claude marketplace plugin
+    # embeds the hook-spec it was generated against; if this globally-installed
+    # binary carries an older manifest, surface a one-line upgrade hint.
+    if args.min_version:
+        local_spec = manifest.get("schema_version") or 0
+        if isinstance(local_spec, int) and local_spec < args.min_version:
+            sys.stderr.write(
+                f"dispatch_hook: plugin expects hook-spec >= {args.min_version} "
+                f"but this agent-config provides {local_spec}; "
+                f"run `agent-config upgrade`.\n")
+
     payload_text = "" if sys.stdin.isatty() else sys.stdin.read()
     _maybe_capture_payload(args, payload_text)
     concerns = _resolve_concerns(manifest, args.platform, args.event)

package/scripts/install

@@ -394,4 +394,18 @@ if ! $SKIP_BRIDGES; then
     run_bridges || RC=$?
 fi
 
+# Post-install PATH advisory. The Claude plugin hook resolves `agent-config`
+# from PATH on a global-only consumer (ADR-020); if it is unreachable every
+# PostToolUse hook silently no-ops — the documented "dashboard never updates"
+# failure. Advisory only: a bad PATH must not fail an otherwise-clean install.
+if [[ $RC -eq 0 ]] && ! command -v agent-config >/dev/null 2>&1; then
+    $QUIET || {
+        echo "  ⚠️   \`agent-config\` is not on your PATH." >&2
+        echo "      Claude plugin hooks resolve it from PATH; without it the" >&2
+        echo "      roadmap-progress dashboard (and other hooks) will not fire." >&2
+        echo "      Add your npm global bin dir (\`npm prefix -g\`/bin) to PATH," >&2
+        echo "      then verify with \`agent-config doctor\`." >&2
+    }
+fi
+
 exit $RC