@event4u/agent-config 5.7.0 → 5.8.0

package/docs/development.md

@@ -127,6 +127,18 @@ task dev:link                  # Symlink this repo as the global @event4u/agent-
 task dev:unlink                # Remove the global symlink
 ```
 
+**Switch the global install between dev and release** — one-shot toggles
+that flip BOTH the `agent-config` bin on PATH and the user-scope content:
+
+```bash
+task install:use-dev           # global = THIS working tree (npm link + dev-build content)
+task install:use-release       # global = latest npm release (npm i -g @latest + release content)
+```
+
+Run `install:use-dev` to test the working tree as the live global install,
+then `install:use-release` to switch back to the published version. They are
+symmetric — whichever you run last is the active global `agent-config`.
+
 **Typical flow:**
 
 1. In this repo: `task dev:link` — once. The `agent-config` bin on PATH

package/docs/getting-started.md

@@ -169,7 +169,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 146 active commands](../.agent-src/commands/)
+→ [Browse all 150 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/guidelines/agent-infra/layered-settings.md

@@ -19,7 +19,13 @@ on user request.
 |---|---|---|---|---|
 | `.agent-project-settings.yml` | **committed** | team / repo | lead maintainer | `project.stack`, `quality.php.tools`, `memory.dogfood` |
 | `~/.event4u/agent-config/agent-settings.yml` | **n/a** (outside repo) | individual developer · cross-project | individual | `name`, `ide`, `rule_loading_tier`, `personal.bot_icon`, `personal.autonomy`, `telegraph.speak_scope` (legacy `~/.config/agent-config/agent-settings.yml` read as fallback) |
-| `.agent-settings.yml` | **gitignored** | individual developer · this project | individual | `personal.ide`, `personal.user_name`, `subagents.max_parallel`, `onboarding.onboarded` |
+| `agents/settings/.agent-settings.yml` | **gitignored** | individual developer · this project | individual | `personal.ide`, `personal.user_name`, `subagents.max_parallel`, `onboarding.onboarded` |
+
+> **Canonical location (ADR-038):** the developer file lives in the settings
+> layer at `agents/settings/.agent-settings.yml` (alongside
+> `.agent-settings.local.yml`, `contexts/`, `policies/`). A repo-root
+> `.agent-settings.yml` is read as a **back-compat fallback** and is migrated
+> into the canonical location by `install` on the next run.
 
 All three are YAML. Schemas:
 
@@ -36,7 +42,7 @@ Lowest priority → highest priority:
 1. Package defaults                                   (shipped by event4u/agent-config)
 2. ~/.event4u/agent-config/agent-settings.yml         (user-global · whitelist-filtered · legacy ~/.config/agent-config/ read as fallback)
 3. .agent-project-settings.yml                        (team file, committed)
-4. .agent-settings.yml                                (developer file, gitignored)
+4. agents/settings/.agent-settings.yml                (developer file, gitignored; legacy repo-root .agent-settings.yml read as fallback — ADR-038)
 ```
 
 Keys from higher layers win unless a lower layer marks them

package/docs/skills-catalog.md

@@ -1,6 +1,6 @@
 # Skills Catalog
 
-All **219 skills** available in this package, in alphabetical order.
+All **223 skills** available in this package, in alphabetical order.
 Click a skill name to open its SKILL.md and read the full guidance.
 
 > **Regenerate:** `python3 scripts/generate_catalog.py`
@@ -89,6 +89,8 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`gtm-launch`](../.agent-src/skills/gtm-launch/SKILL.md) | Use when sequencing a launch — alpha / beta / GA waves, audience-by-wave logic, narrative beats per wave, engineering-readiness gates. Triggers on 'plan the launch', 'sequence GA'. |
 | [`guideline-writing`](../.agent-src/skills/guideline-writing/SKILL.md) | Use when creating or editing a guideline in docs/guidelines/ — reference material cited by skills, no auto-triggers — even when the user just says 'write up our naming conventions'. |
 | [`hiring-loop-design`](../.agent-src/skills/hiring-loop-design/SKILL.md) | Use when shaping an engineering hiring loop — stages, take-home vs live, calibration, bar-raiser, signal-vs-noise audit. Triggers on 'design our interview loop', 'audit our hiring bar'. |
+| [`image-analyser`](../.agent-src/skills/image-analyser/SKILL.md) | Use to analyse a character image down to the smallest mole and diff against a canon — per-feature spec, OCR-reads tattoo text, flags drift. Triggers 'analyse this image', 'match the canon'. |
+| [`image-creator`](../.agent-src/skills/image-creator/SKILL.md) | Use to generate a character image to spec — max-fidelity reproducible prompt from a Canon Spec, anchors-first, provider/governance-gated. Triggers 'generate this character', 'render to spec'. |
 | [`incident-commander`](../.agent-src/skills/incident-commander/SKILL.md) | Use during or right after an incident — frames severity, sets comms cadence, drafts the post-mortem skeleton — even when the user just says 'production is down' or 'wir haben einen Vorfall'. |
 | [`jira-integration`](../.agent-src/skills/jira-integration/SKILL.md) | Use when the user says "check Jira", "create ticket", "update issue", or needs JQL queries, ticket transitions, or branch-to-ticket linking. |
 | [`jobs-events`](../.agent-src/skills/jobs-events/SKILL.md) | Use when creating Laravel jobs, queued workflows, events, or listeners. Covers clear responsibilities, safe serialization, and retry/failure handling. |
@@ -152,6 +154,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`playwright-testing`](../.agent-src/skills/playwright-testing/SKILL.md) | Use when writing Playwright E2E tests — browser automation, visual regression testing, Page Objects, fixtures, and reliable test patterns. |
 | [`po-discovery`](../.agent-src/skills/po-discovery/SKILL.md) | Use when shaping a fuzzy product ask into a refined backlog item — problem framing, user-story rewrite, AC tightening — even if the user just says 'help me write this ticket'. |
 | [`positioning-strategy`](../.agent-src/skills/positioning-strategy/SKILL.md) | Use when locking the market frame — category, segment, alternative, point-of-view — before messaging, launch, or pricing rides on it. Triggers on 'who are we for', 'opposable audit'. |
+| [`prediction-pool-optimizer`](../.agent-src/skills/prediction-pool-optimizer/SKILL.md) | Optimize prediction-pool tips (kicktipp etc.): rules + multi-book consensus odds → expected-points-max answer for every question, scores AND bonus. Triggers 'optimize my pool tips', 'predict'. |
 | [`privacy-review`](../.agent-src/skills/privacy-review/SKILL.md) | Use when reviewing data flows, support macros, refund templates for GDPR/CCPA/HIPAA fit — regime, consent, PII redaction (email, order-id), breach triage. Triggers 'is this GDPR-safe', 'PII redact'. |
 | [`project-analysis-core`](../.agent-src/skills/project-analysis-core/SKILL.md) | Raw discovery primitives — project discovery, version resolution, docs loading, architecture mapping, execution flow. Called by `universal-project-analysis`. Single-pass scan → `project-analyzer`. |
 | [`project-analysis-hypothesis-driven`](../.agent-src/skills/project-analysis-hypothesis-driven/SKILL.md) | Use when a bug has multiple plausible causes across layers — competing hypotheses, validation loops, evidence-based conclusions — even when the user just says 'why is this happening?'. |
@@ -199,6 +202,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`skill-management`](../.agent-src/skills/skill-management/SKILL.md) | Use when condensing, decondenseing, refactoring, or improving existing skills. Covers the full skill lifecycle from verbose → sharp → maintained. |
 | [`skill-reviewer`](../.agent-src/skills/skill-reviewer/SKILL.md) | Use when reviewing, auditing, or optimizing skills — validates against the 7 Skill Killers checklist and produces fix recommendations. |
 | [`skill-writing`](../.agent-src/skills/skill-writing/SKILL.md) | Use when deciding 'should this be a skill or a rule?', creating/improving/reviewing agent skills, SKILL.md frontmatter, or procedure sections — even without saying 'skill-writing'. |
+| [`song-to-script`](../.agent-src/skills/song-to-script/SKILL.md) | Turn an audio track into a timed `## Scene N` script: song sections → per-scene durations, auto mode adds mood + lip-sync lines. Triggers 'music video', 'from the song', 'cut to the beat'. |
 | [`sql-writing`](../.agent-src/skills/sql-writing/SKILL.md) | Use when writing raw SQL — MariaDB/MySQL syntax, parameterization, raw migrations, seeders with `DB::statement` — even when the user just pastes a query and asks 'why is this slow' without naming SQL. |
 | [`stakeholder-tradeoff`](../.agent-src/skills/stakeholder-tradeoff/SKILL.md) | Use when stakeholders pull a decision in different directions — frames each lens, builds a trade-off matrix, surfaces the cost of every choice — even if the user just says 'PO and ops disagree'. |
 | [`subagent-orchestration`](../.agent-src/skills/subagent-orchestration/SKILL.md) | Use when orchestrating implementer/judge subagents — seven modes (do-and-judge ±two-stage, do-in-steps/parallel/worktrees, do-competitively, judge-with-debate) — models from .agent-settings.yml. |

package/llms.txt

@@ -87,6 +87,8 @@ grafana: Use when working with Grafana — dashboards, Loki LogQL queries, alert
 gtm-launch: Use when sequencing a launch — alpha / beta / GA waves, audience-by-wave logic, narrative beats per wave, engineering-readiness gates. Triggers on 'plan the launch', 'sequence GA'.
 guideline-writing: Use when creating or editing a guideline in docs/guidelines/ — reference material cited by skills, no auto-triggers — even when the user just says 'write up our naming conventions'.
 hiring-loop-design: Use when shaping an engineering hiring loop — stages, take-home vs live, calibration, bar-raiser, signal-vs-noise audit. Triggers on 'design our interview loop', 'audit our hiring bar'.
+image-analyser: Use to analyse a character image down to the smallest mole and diff against a canon — per-feature spec, OCR-reads tattoo text, flags drift. Triggers 'analyse this image', 'match the canon'.
+image-creator: Use to generate a character image to spec — max-fidelity reproducible prompt from a Canon Spec, anchors-first, provider/governance-gated. Triggers 'generate this character', 'render to spec'.
 incident-commander: Use during or right after an incident — frames severity, sets comms cadence, drafts the post-mortem skeleton — even when the user just says 'production is down' or 'wir haben einen Vorfall'.
 jira-integration: Use when the user says "check Jira", "create ticket", "update issue", or needs JQL queries, ticket transitions, or branch-to-ticket linking.
 jobs-events: Use when creating Laravel jobs, queued workflows, events, or listeners. Covers clear responsibilities, safe serialization, and retry/failure handling.
@@ -150,6 +152,7 @@ playwright-architect: Use when shaping a Playwright suite — locator strategy,
 playwright-testing: Use when writing Playwright E2E tests — browser automation, visual regression testing, Page Objects, fixtures, and reliable test patterns.
 po-discovery: Use when shaping a fuzzy product ask into a refined backlog item — problem framing, user-story rewrite, AC tightening — even if the user just says 'help me write this ticket'.
 positioning-strategy: Use when locking the market frame — category, segment, alternative, point-of-view — before messaging, launch, or pricing rides on it. Triggers on 'who are we for', 'opposable audit'.
+prediction-pool-optimizer: Optimize prediction-pool tips (kicktipp etc.): rules + multi-book consensus odds → expected-points-max answer for every question, scores AND bonus. Triggers 'optimize my pool tips', 'predict'.
 privacy-review: Use when reviewing data flows, support macros, refund templates for GDPR/CCPA/HIPAA fit — regime, consent, PII redaction (email, order-id), breach triage. Triggers 'is this GDPR-safe', 'PII redact'.
 project-analysis-core: Raw discovery primitives — project discovery, version resolution, docs loading, architecture mapping, execution flow. Called by `universal-project-analysis`. Single-pass scan → `project-analyzer`.
 project-analysis-hypothesis-driven: Use when a bug has multiple plausible causes across layers — competing hypotheses, validation loops, evidence-based conclusions — even when the user just says 'why is this happening?'.
@@ -197,6 +200,7 @@ skill-improvement-pipeline: ONLY when user explicitly requests: run the skill im
 skill-management: Use when condensing, decondenseing, refactoring, or improving existing skills. Covers the full skill lifecycle from verbose → sharp → maintained.
 skill-reviewer: Use when reviewing, auditing, or optimizing skills — validates against the 7 Skill Killers checklist and produces fix recommendations.
 skill-writing: Use when deciding 'should this be a skill or a rule?', creating/improving/reviewing agent skills, SKILL.md frontmatter, or procedure sections — even without saying 'skill-writing'.
+song-to-script: Turn an audio track into a timed `## Scene N` script: song sections → per-scene durations, auto mode adds mood + lip-sync lines. Triggers 'music video', 'from the song', 'cut to the beat'.
 sql-writing: Use when writing raw SQL — MariaDB/MySQL syntax, parameterization, raw migrations, seeders with `DB::statement` — even when the user just pastes a query and asks 'why is this slow' without naming SQL.
 stakeholder-tradeoff: Use when stakeholders pull a decision in different directions — frames each lens, builds a trade-off matrix, surfaces the cost of every choice — even if the user just says 'PO and ops disagree'.
 subagent-orchestration: Use when orchestrating implementer/judge subagents — seven modes (do-and-judge ±two-stage, do-in-steps/parallel/worktrees, do-competitively, judge-with-debate) — models from .agent-settings.yml.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "5.7.0",
+    "version": "5.8.0",
     "description": "Universal AI Agent OS \u2014 audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/scripts/_cli/cmd_doctor.py

@@ -55,6 +55,7 @@ from scripts._lib.agent_settings import (
     ROOT_OVERRIDE_ENV,
     ProjectRootError,
     find_project_root_with_trace,
+    project_settings_path,
     resolve_project_root,
 )
 
@@ -131,7 +132,7 @@ def _settings_layer_chain(project_root: Path) -> list[str]:
     user_global = user_global_paths.resolve_with_fallback("agent-settings.yml")
     if user_global is not None and user_global.is_file():
         layers.append(str(user_global))
-    project_settings = project_root / ".agent-settings.yml"
+    project_settings = project_settings_path(project_root)
     if project_settings.is_file():
         layers.append(str(project_settings))
     return layers
@@ -778,7 +779,7 @@ def _check_tier_usage_readiness(project_root: Path) -> dict[str, Any]:
 
     Contract: ``docs/contracts/command-clusters.md`` § tier-usage signal.
     """
-    settings_file = project_root / ".agent-settings.yml"
+    settings_file = project_settings_path(project_root)
     log_path = project_root / ".agent-tier-usage.jsonl"
     enabled = False
     if settings_file.is_file():

package/scripts/_cli/cmd_versions.py

@@ -18,7 +18,7 @@ import subprocess
 import sys
 from pathlib import Path
 
-from scripts._lib.agent_settings import resolve_project_root
+from scripts._lib.agent_settings import project_settings_path, resolve_project_root
 
 PACKAGE_NAME = "@event4u/agent-config"
 
@@ -51,7 +51,7 @@ def _local_package_version() -> str:
 
 def _pinned_version() -> str:
     """Return the ``agent_config_version`` pin from ``.agent-settings.yml``."""
-    settings = _project_root() / ".agent-settings.yml"
+    settings = project_settings_path(_project_root())
     if not settings.exists():
         return ""
     try:

package/scripts/_lib/agent_settings.py

@@ -76,6 +76,45 @@ def _local_settings_path(project_root: Path) -> Path:
     return project_root.joinpath(*LOCAL_PROJECT_SUBDIR, LOCAL_PROJECT_FILE)
 
 
+def _canonical_settings_path(project_root: Path) -> Path:
+    """Canonical project settings file: ``<root>/agents/settings/.agent-settings.yml``.
+
+    The project settings file lives in the project's settings layer
+    (``agents/settings/``, alongside ``contexts/`` and ``policies/`` and
+    the ``.agent-settings.local.yml`` override), NOT at the repo root.
+    The repo-root ``.agent-settings.yml`` is a legacy location read only
+    as a back-compat fallback (see :func:`project_settings_path`).
+    """
+    return project_root.joinpath(*LOCAL_PROJECT_SUBDIR, DEFAULT_PROJECT_FILE)
+
+
+def project_settings_path(project_root: Path) -> Path:
+    """Resolve the project settings file for **reading**.
+
+    Returns the canonical ``agents/settings/.agent-settings.yml`` when it
+    exists; otherwise the legacy repo-root ``.agent-settings.yml`` when
+    that exists (back-compat for installs predating the relocation);
+    otherwise the canonical path (so the caller still names the right
+    target on a fresh repo). Existence-checked, never writes.
+    """
+    canonical = _canonical_settings_path(project_root)
+    if canonical.exists():
+        return canonical
+    legacy = project_root / DEFAULT_PROJECT_FILE
+    if legacy.exists():
+        return legacy
+    return canonical
+
+
+def canonical_settings_write_path(project_root: Path) -> Path:
+    """Always the canonical **write** target: ``agents/settings/.agent-settings.yml``.
+
+    Writers (install, sync, migrate) target this unconditionally; the
+    legacy root file is migrated into it, never written afresh.
+    """
+    return _canonical_settings_path(project_root)
+
+
 DEFAULT_TEAM_FILE = ".agent-project-settings.yml"
 USER_GLOBAL_FILENAME = "agent-settings.yml"
 
@@ -431,12 +470,14 @@ def _resolve_cascade_paths(
     """
     if cwd is None:
         legacy = Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE)
-        return [legacy, _local_settings_path(legacy.parent)]
+        return [legacy, _canonical_settings_path(legacy.parent),
+                _local_settings_path(legacy.parent)]
 
     root = find_project_root(cwd)
     if root is None:
         legacy = Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE)
-        return [legacy, _local_settings_path(legacy.parent)]
+        return [legacy, _canonical_settings_path(legacy.parent),
+                _local_settings_path(legacy.parent)]
 
     cwd_resolved = cwd.resolve()
     # Build the chain root → … → cwd (shallowest first, deepest last).
@@ -451,9 +492,15 @@ def _resolve_cascade_paths(
             break
         cursor = parent
     chain.reverse()
-    # Committed cascade root → cwd, then the single project-level local override
-    # under agents/settings/ as the deepest (winning) layer.
-    return [d / DEFAULT_PROJECT_FILE for d in chain] + [_local_settings_path(root)]
+    # Legacy per-dir cascade root → cwd (repo-root .agent-settings.yml is the
+    # shallowest, back-compat), then the canonical project settings file under
+    # agents/settings/ (wins over the legacy root location), then the
+    # per-machine local override under agents/settings/ as the deepest (winning)
+    # layer.
+    return (
+        [d / DEFAULT_PROJECT_FILE for d in chain]
+        + [_canonical_settings_path(root), _local_settings_path(root)]
+    )
 
 
 def load_agent_settings(

package/scripts/_lib/agent_src.py

@@ -30,6 +30,7 @@ from typing import Iterator
 ROOT = Path(__file__).resolve().parents[2]
 LEGACY_SRC = ROOT / ".agent-src.uncondensed"
 PACKAGES = ROOT / "packages"
+PACKAGE_CORE = PACKAGES / "core"
 
 # Repo-relative POSIX path prefixes that anchor an artefact source tree.
 # Order: legacy first (kept until the move lands), then packages/*. Each
@@ -155,3 +156,32 @@ def strip_source_prefix(rel: str) -> str | None:
 def is_artefact_path(rel: str) -> bool:
     """``True`` if a repo-relative POSIX path sits under any source root."""
     return strip_source_prefix(rel) is not None
+
+
+def resolve_package_core_path(relative_target: str) -> Path:
+    """Return the canonical ``packages/core/<relative_target>`` path.
+
+    The single resolution point for every gate that enforces something
+    against a fixed ``packages/core/`` target. A future move of the
+    ``packages/core/`` tree updates :data:`PACKAGE_CORE` here — one
+    resolver — instead of N hard-coded ``REPO_ROOT / "packages" / "core"``
+    constants scattered across gate scripts (the ``aab5755`` silent-no-op
+    class this eliminates).
+
+    Pure resolver: deterministic, **no filesystem I/O**. ``agent_src`` is
+    imported by scanners that must stay usable in the legacy-only and
+    pack-only layouts (see :func:`artefact_roots`), so this MUST NOT
+    assert existence at import or call time — a packages/core existence
+    check here would break those layouts. Callers that need existence
+    check it themselves; ``scripts/check_gate_paths.py`` is the single
+    gate that asserts the enforced targets resolve under ``packages/core/``.
+
+    Examples:
+        ``resolve_package_core_path(".agent-src.uncondensed")``
+            → ``<repo>/packages/core/.agent-src.uncondensed``
+        ``resolve_package_core_path(".agent-src.uncondensed/commands")``
+            → ``<repo>/packages/core/.agent-src.uncondensed/commands``
+        ``resolve_package_core_path("")`` → ``<repo>/packages/core``
+    """
+    rel = relative_target.replace("\\", "/").lstrip("/")
+    return PACKAGE_CORE / rel if rel else PACKAGE_CORE

package/scripts/ai_council/session.py

@@ -28,6 +28,10 @@ import shutil
 import sys
 from dataclasses import dataclass, field
 from pathlib import Path
+try:  # invocation-agnostic import (repo-root-on-path vs scripts-on-path)
+    from scripts._lib.agent_settings import project_settings_path
+except ModuleNotFoundError:  # pragma: no cover
+    from _lib.agent_settings import project_settings_path
 from typing import Iterable
 
 from scripts.ai_council.clients import CouncilResponse
@@ -37,7 +41,7 @@ REPO_ROOT = Path(__file__).resolve().parents[2]
 SESSIONS_DIR = REPO_ROOT / "agents" / "runtime" / "council" / "sessions"
 QUESTIONS_DIR = REPO_ROOT / "agents" / "runtime" / "council" / "questions"
 RESPONSES_DIR = REPO_ROOT / "agents" / "runtime" / "council" / "responses"
-SETTINGS_FILE = REPO_ROOT / ".agent-settings.yml"
+SETTINGS_FILE = project_settings_path(REPO_ROOT)
 
 # Default retention for all council artefacts (questions, responses,
 # sessions). Overridden by `ai_council.session_retention_days`

package/scripts/audit_command_surface.py

@@ -37,12 +37,18 @@ from pathlib import Path
 from typing import List
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import resolve_package_core_path  # noqa: E402
+
 # Pre-monorepo: REPO_ROOT/.agent-src.uncondensed/commands. Post-move (ADR-017)
 # the core command surface lives under packages/core/.agent-src.uncondensed.
 # Fall back to the legacy path only if the packages layout is absent.
-_CORE_COMMANDS = REPO_ROOT / "packages" / "core" / ".agent-src.uncondensed" / "commands"
+_CORE_COMMANDS = resolve_package_core_path(".agent-src.uncondensed/commands")
 _LEGACY_COMMANDS = REPO_ROOT / ".agent-src.uncondensed" / "commands"
 DEFAULT_ROOT = _CORE_COMMANDS if _CORE_COMMANDS.is_dir() else _LEGACY_COMMANDS
+# Enforced packages/core target — read by scripts/check_gate_paths.py so a
+# future move that desyncs this path fails CI instead of silently no-opping.
+GATE_CORE_PATHS = (_CORE_COMMANDS,)
 REPORT_DIR = REPO_ROOT / "agents" / "reports"
 OUT_JSON = REPORT_DIR / "command-surface.json"
 OUT_MD = REPORT_DIR / "command-surface.md"

package/scripts/audit_initial_context.py

@@ -35,6 +35,13 @@ from pathlib import Path
 REPO_ROOT = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(REPO_ROOT / "scripts"))
 from _lib import token_count  # noqa: E402
+from _lib.agent_src import resolve_package_core_path  # noqa: E402
+
+_CORE_SRC = resolve_package_core_path(".agent-src.uncondensed")
+# Enforced packages/core targets — the skills + commands dirs the
+# description-catalog globs scan. Read by scripts/check_gate_paths.py so a
+# future move that desyncs them fails CI instead of silently no-opping.
+GATE_CORE_PATHS = (_CORE_SRC / "skills", _CORE_SRC / "commands")
 
 try:
     import yaml
@@ -111,10 +118,11 @@ def _catalog(glob_pat: str) -> dict:
 
 def description_catalog() -> dict:
     """0B.4 — description-catalog cost (eager progressive-disclosure surface)."""
+    core_rel = _CORE_SRC.relative_to(REPO_ROOT).as_posix()
     return {
         "skills_projected": _catalog(".claude/skills/*/SKILL.md"),
-        "skills_core_source": _catalog("packages/core/.agent-src.uncondensed/skills/*/SKILL.md"),
-        "commands_core_source": _catalog("packages/core/.agent-src.uncondensed/commands/**/*.md"),
+        "skills_core_source": _catalog(f"{core_rel}/skills/*/SKILL.md"),
+        "commands_core_source": _catalog(f"{core_rel}/commands/**/*.md"),
     }
 
 

package/scripts/check_gate_paths.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Gate path-integrity check (R2 of road-to-test-and-gate-integrity).
+
+Asserts that every security/quality gate which enforces something against
+a fixed ``packages/core/`` target still resolves that target on disk. A
+``packages/core/`` move that desyncs a gate's hard-coded path fails CI here
+instead of silently no-opping (the ``aab5755`` class: the Iron-Law SHA gate
+pointed at a stale path and enforced nothing while CI stayed green).
+
+Design (AI council, claude-sonnet-4-5 + gpt-4o, 2026-06-02):
+
+- The check reads each gate's ACTUAL enforced paths via its module-level
+  ``GATE_CORE_PATHS`` attribute — it does NOT re-declare a copy of the path
+  strings. A hand-maintained path registry would reintroduce the very
+  desync risk this guards against, one layer down.
+- Scope is strictly the single-root hard-coders. Multi-root gates that
+  resolve via ``artefact_roots()`` (e.g. ``iron_law_sha``) are excluded:
+  asserting a single ``packages/core/`` path for them would false-pass on a
+  legacy layout or false-fail on a pack-only layout.
+
+The input set is this gate list (no separate config file).
+
+Usage:
+    python3 scripts/check_gate_paths.py
+Exit codes: 0 = all enforced targets resolve under packages/core/ ·
+1 = at least one missing / out-of-tree target · 2 = a gate failed to import.
+"""
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import resolve_package_core_path  # noqa: E402
+
+PACKAGE_CORE = resolve_package_core_path("")
+
+# Single-root gates that enforce against a fixed packages/core/ target and
+# expose it via a module-level GATE_CORE_PATHS tuple. Adding a gate here is
+# the only manual step; its paths are read from the gate, never copied.
+GATES: tuple[str, ...] = (
+    "inventory_abstraction_budget",
+    "audit_command_surface",
+    "lint_agents_md",
+    "audit_initial_context",
+)
+
+
+def _is_under_core(p: Path) -> bool:
+    try:
+        p.resolve().relative_to(PACKAGE_CORE.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def collect_gate_paths(gate_modules: tuple[str, ...]) -> dict[str, list[Path]]:
+    """Import each gate and read its declared ``GATE_CORE_PATHS``.
+
+    Raises ``ImportError`` (surfaced as exit 2 by ``main``) if a gate cannot
+    be imported — a gate whose path logic broke at import time is itself a
+    failure this check should not swallow.
+    """
+    out: dict[str, list[Path]] = {}
+    for name in gate_modules:
+        mod = importlib.import_module(name)
+        paths = getattr(mod, "GATE_CORE_PATHS", None)
+        if not paths:
+            raise AttributeError(
+                f"{name} has no non-empty GATE_CORE_PATHS — gate cannot be "
+                f"checked. Declare the packages/core targets it enforces."
+            )
+        out[name] = [Path(p) for p in paths]
+    return out
+
+
+def check_paths(named: dict[str, list[Path]]) -> list[tuple[str, str, Path]]:
+    """Return ``(gate, reason, path)`` for every target that fails.
+
+    Pure (no import side effects) so tests can drive it with fixtures.
+    A target fails when it does not resolve under ``packages/core/`` or
+    does not exist on disk.
+    """
+    failures: list[tuple[str, str, Path]] = []
+    for gate, paths in named.items():
+        for p in paths:
+            if not _is_under_core(p):
+                failures.append((gate, "not under packages/core/", p))
+            elif not p.exists():
+                failures.append((gate, "target does not exist", p))
+    return failures
+
+
+def main() -> int:
+    try:
+        named = collect_gate_paths(GATES)
+    except (ImportError, AttributeError) as exc:
+        print(f"❌  check-gate-paths: {exc}", file=sys.stderr)
+        return 2
+    failures = check_paths(named)
+    if failures:
+        print("❌  check-gate-paths: gate target(s) do not resolve under packages/core/:")
+        for gate, reason, path in failures:
+            print(f"    {gate}: {reason} → {path}")
+        print("\n  A packages/core/ move likely desynced a gate. Fix the gate's")
+        print("  GATE_CORE_PATHS (built via resolve_package_core_path) or the move.")
+        return 1
+    total = sum(len(v) for v in named.values())
+    print(f"✅  check-gate-paths: {total} enforced target(s) across "
+          f"{len(named)} gate(s) resolve under packages/core/.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/check_references.py

@@ -133,6 +133,53 @@ EXAMPLE_PATH_PATTERNS = [
 ]
 
 
+@dataclass(frozen=True)
+class AllowlistPattern:
+    """A token-class allowlist entry. `reason` is mandatory and auditable."""
+    pattern: "re.Pattern[str]"
+    reason: str
+
+
+# Content-class allowlist for known NON-reference token shapes.
+#
+# The skill/rule prose patterns (`X` skill / `X` rule) occasionally match
+# a backtick token that is not an artifact id — an execution-type enum
+# value, a pack identifier, or a bare meta-qualifier keyword. Historically
+# each such false positive was dodged by *rewording the prose per file*
+# (e.g. dc84ed01 "reword execution-type mentions to dodge check-refs
+# false positive", bd02ef0b "avoid check-refs false-positive on pack
+# name"), a treadmill that distorts natural wording release after release.
+# This layer matches the token *class* centrally instead, so the natural
+# wording passes without per-file edits. It is distinct from:
+#   - SKIP_DIRS          (path-level, whole-directory)
+#   - FILE_SKIP_MARKER   (file-level opt-out)
+#   - LINE_IGNORE_MARKER (per-line opt-out)
+# Every entry carries a mandatory `reason` so the allowlist stays
+# auditable and a future reader can tell why a class is exempt.
+ALLOWLIST_PATTERNS: List[AllowlistPattern] = [
+    AllowlistPattern(
+        re.compile(r"^(?:manual|assisted|automated)$"),
+        "execution-type enum value (runtime-safety frontmatter), e.g. a "
+        "`manual` skill — not a skill/rule id (dc84ed01)",
+    ),
+    AllowlistPattern(
+        re.compile(r"^pack-[\w-]+$"),
+        "pack / workspace identifier, e.g. `pack-ai-video` skills — not a "
+        "skill/rule id (bd02ef0b)",
+    ),
+    AllowlistPattern(
+        re.compile(r"^(?:skill|rule|command|guideline|persona|context|pack|workspace)$"),
+        "bare meta-qualifier keyword used in prose (the `command` vs "
+        "`skill` distinction, etc.) — not an artifact id",
+    ),
+]
+
+
+def _is_allowlisted(name: str) -> bool:
+    """True when `name` matches a known non-reference token class."""
+    return any(entry.pattern.match(name) for entry in ALLOWLIST_PATTERNS)
+
+
 def collect_artifacts(root: Path) -> dict[str, set[str]]:
     """Build lookup sets for skills, rules, commands, guidelines, personas."""
     arts: dict[str, set[str]] = {
@@ -345,7 +392,8 @@ def check_file(filepath: Path, artifacts: dict[str, set[str]], root: Path) -> Li
         # Skill name references
         for m in SKILL_REF_PATTERN.finditer(line):
             name = m.group(1)
-            if name not in artifacts["skills"] and name not in _SKIP_NAMES:
+            if name not in artifacts["skills"] and name not in _SKIP_NAMES \
+                    and not _is_allowlisted(name):
                 broken.append(BrokenRef(
                     file=str(filepath), line=i, ref=name,
                     ref_type="skill", severity="warning",
@@ -355,7 +403,8 @@ def check_file(filepath: Path, artifacts: dict[str, set[str]], root: Path) -> Li
         # Rule name references
         for m in RULE_REF_PATTERN.finditer(line):
             name = m.group(1)
-            if name not in artifacts["rules"] and name not in _SKIP_NAMES:
+            if name not in artifacts["rules"] and name not in _SKIP_NAMES \
+                    and not _is_allowlisted(name):
                 broken.append(BrokenRef(
                     file=str(filepath), line=i, ref=name,
                     ref_type="rule", severity="warning",