@event4u/agent-config 5.7.0 → 5.9.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.9.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

@@ -23,8 +23,16 @@ mcp-mode · mcp-beta-readiness · offline-readiness · python-runtime ·
 tier-usage-readiness · council-cli · unsupported-combos ·
 wizard-state.
 Each emits a structured ``{id, status, message, remedy}`` record with
-``status`` ∈ ``ok`` / ``warn`` / ``fail`` (rendered ``✅`` / ``⚠️`` /
-``❌``). ``--check <id>`` runs a single check.
+``status`` ∈ ``ok`` / ``warn`` / ``fail`` / ``skipped`` (rendered
+``✅`` / ``⚠️`` / ``❌`` / ``⏭️``). ``--check <id>`` runs a single check.
+
+Checks are split by scope (:data:`GLOBAL_CHECK_IDS` vs
+:data:`MANIFEST_REQUIRED_CHECK_IDS`) so an ADR-020 global-only consumer
+(bridge marker present, no ``agents/installed-tools.lock``) gets a
+green-capable report instead of a hard bail: the global checks run, the
+manifest-required checks report ``skipped``, and ``bridge-drift`` returns
+a scope-aware "drift not applicable" verdict. See :func:`main` for the
+no-manifest branch and exit-code contract.
 
 Repair affordances: ``--repair wizard-state`` resets a malformed or
 orphaned ``state/wizard-state.json`` under the user-global root (the
@@ -55,6 +63,7 @@ from scripts._lib.agent_settings import (
     ROOT_OVERRIDE_ENV,
     ProjectRootError,
     find_project_root_with_trace,
+    project_settings_path,
     resolve_project_root,
 )
 
@@ -131,7 +140,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
@@ -454,6 +463,41 @@ CHECK_IDS = (
     "wizard-state",
 )
 
+#: Checks that need only the project root (or no input at all) and run
+#: regardless of whether a project lockfile exists. Under ADR-020
+#: global-only (bridge marker present, no ``installed-tools.lock``) these
+#: still produce a real verdict. ``scope`` lives here because
+#: :func:`_check_scope` reads only ``project_root`` — the roadmap prose
+#: that grouped it with the manifest checks predates this code reality
+#: (AI council, claude-sonnet-4-5 + gpt-4o, design lens, 2026-06-02).
+GLOBAL_CHECK_IDS: frozenset[str] = frozenset({
+    "scope",
+    "global-binary",
+    "mcp-mode",
+    "mcp-beta-readiness",
+    "offline-readiness",
+    "python-runtime",
+    "tier-usage-readiness",
+    "council-cli",
+    "wizard-state",
+})
+
+#: Checks that genuinely cannot run without the project manifest. Without
+#: a lockfile they report ``skipped`` rather than a misleading verdict.
+#: ``bridge-drift`` is deliberately **not** here: it is scope-aware —
+#: a manifest-derived drift roll-up when the lockfile exists, and a
+#: "drift not applicable (global-only consumer)" verdict when it does
+#: not (computed in :func:`_check_bridge_drift_no_manifest`, keeping
+#: :func:`_check_bridge_drift` a pure roll-up per the council's SRP point).
+MANIFEST_REQUIRED_CHECK_IDS: frozenset[str] = frozenset({
+    "manifest-integrity",
+    "lockfile-freshness",
+    "unsupported-combos",
+})
+
+#: Project-root-relative path of the ADR-020 global-only consumer marker.
+BRIDGE_MARKER_RELATIVE = "agents/.event4u-bridge.yml"
+
 #: Repair targets that ``--repair <id>`` accepts. Each id maps to a
 #: function in :func:`_run_repair` that resets the named artefact and
 #: returns an exit code. Additive set: introduce by adding a new id
@@ -475,7 +519,7 @@ MCP_BETA_GATES: tuple[tuple[str, str], ...] = (
 
 #: Visible status → glyph map. ``warn`` keeps a trailing space so the
 #: rendered output stays in a single visual column with the other glyphs.
-STATUS_SYMBOLS = {"ok": "✅", "warn": "⚠️ ", "fail": "❌"}
+STATUS_SYMBOLS = {"ok": "✅", "warn": "⚠️ ", "fail": "❌", "skipped": "⏭️ "}
 
 #: Minimum Python interpreter the CLI targets. Bumped in lockstep with
 #: ``from __future__ import annotations`` + PEP-604 syntax usage.
@@ -778,7 +822,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():
@@ -1158,6 +1202,131 @@ def _run_checks(
     return out
 
 
+def _skipped_manifest_check(check_id: str) -> dict[str, Any]:
+    """A ``skipped`` verdict for a manifest-required check with no lockfile.
+
+    Explicit machine-readable record (not omitted, not ``null``) so the
+    ``--json`` ``checks`` array keeps a stable shape for a global-only
+    consumer — a council convergence point (2026-06-02).
+    """
+    return {
+        "id": check_id, "status": "skipped",
+        "message": "requires a project lockfile (agents/installed-tools.lock)",
+        "remedy": "run `agent-config init` to create a project lockfile, "
+                  "then re-run this check",
+    }
+
+
+def _check_bridge_drift_no_manifest(bridge_present: bool) -> dict[str, Any]:
+    """Scope-aware ``bridge-drift`` verdict when no project manifest exists.
+
+    Kept out of :func:`_check_bridge_drift` (which stays a pure
+    manifest-derived roll-up) per the council's single-responsibility
+    point. A global-only consumer has no distributed tools to drift, so
+    a bridge-present repo reports ``ok`` ("not applicable"); a repo with
+    neither lockfile nor bridge marker reports ``skipped``.
+    """
+    if bridge_present:
+        return {
+            "id": "bridge-drift", "status": "ok",
+            "message": "no project lockfile → distributed-tool drift not "
+                       "applicable (global-only consumer)",
+            "remedy": "",
+        }
+    return {
+        "id": "bridge-drift", "status": "skipped",
+        "message": "no project lockfile and no bridge marker → drift check "
+                   "not applicable",
+        "remedy": "run `agent-config init` (project install) or "
+                  "`agent-config refresh --project` (global-only consumer)",
+    }
+
+
+def _run_checks_no_manifest(
+    project_root: Path,
+    bridge_present: bool,
+    only: str | None = None,
+) -> list[dict[str, Any]]:
+    """Run the registry with no project manifest available.
+
+    Mirrors :func:`_run_checks` and preserves :data:`CHECK_IDS` order.
+    Global checks (:data:`GLOBAL_CHECK_IDS`) run unchanged; manifest-required
+    checks (:data:`MANIFEST_REQUIRED_CHECK_IDS`) report ``skipped``;
+    ``bridge-drift`` gets the scope-aware no-manifest verdict.
+    """
+    runners: dict[str, Any] = {
+        "scope": lambda: _check_scope(project_root),
+        "global-binary": lambda: _check_global_binary(project_root),
+        "manifest-integrity": lambda: _skipped_manifest_check("manifest-integrity"),
+        "lockfile-freshness": lambda: _skipped_manifest_check("lockfile-freshness"),
+        "bridge-drift": lambda: _check_bridge_drift_no_manifest(bridge_present),
+        "mcp-mode": lambda: _check_mcp_mode(project_root),
+        "mcp-beta-readiness": lambda: _check_mcp_beta_readiness(project_root),
+        "offline-readiness": lambda: _check_offline_readiness(),
+        "python-runtime": lambda: _check_python_runtime(),
+        "tier-usage-readiness": lambda: _check_tier_usage_readiness(project_root),
+        "council-cli": lambda: _check_council_cli(project_root),
+        "unsupported-combos": lambda: _skipped_manifest_check("unsupported-combos"),
+        "wizard-state": _check_wizard_state,
+    }
+    out: list[dict[str, Any]] = []
+    for cid in CHECK_IDS:
+        if only is not None and cid != only:
+            continue
+        out.append(runners[cid]())
+    return out
+
+
+def _run_no_manifest(
+    opts: argparse.Namespace,
+    project_root: Path,
+    origin: str,
+    bridge_present: bool,
+) -> int:
+    """Handle the no-project-lockfile path without the old hard bail.
+
+    Exit-code contract (council-defined, 2026-06-02):
+
+    * ``0`` — bare report for a recognised global-only consumer
+      (bridge marker present), or a single global ``--check`` that passed.
+    * ``1`` — a runnable health check requested via ``--check`` failed.
+    * ``2`` — a requested ``--check`` cannot run (manifest-required check
+      with no lockfile, or ``bridge-drift`` with neither lockfile nor
+      bridge marker), or a bare report in an **uninitialised** repo
+      (neither lockfile nor bridge marker) — preserves the spirit of the
+      pre-existing "run init" signal while still printing a real report.
+    """
+    checks = _run_checks_no_manifest(project_root, bridge_present, only=opts.check)
+    fail_check = any(c["status"] == "fail" for c in checks)
+    skipped_requested = opts.check is not None and any(
+        c["id"] == opts.check and c["status"] == "skipped" for c in checks
+    )
+
+    if opts.json:
+        _emit_json(project_root, [], [], [], [], checks=checks, origin=origin)
+    elif opts.check is None:
+        print(f"  📍  project_root: {project_root} (origin: {origin})")
+        if bridge_present:
+            print("  ℹ️   global-only consumer: bridge marker present, no "
+                  "project lockfile (expected under ADR-020)")
+            print("      project-manifest checks are skipped — they apply only "
+                  "to project-local distributed tools")
+        else:
+            print("  ⚠️   no project lockfile and no bridge marker at "
+                  f"{project_root}", file=sys.stderr)
+            print("      run `agent-config init` (project install) or "
+                  "`agent-config refresh --project` (global-only consumer)",
+                  file=sys.stderr)
+        _emit_checks_text(checks)
+    else:
+        _emit_checks_text(checks)
+
+    if opts.check is not None:
+        if skipped_requested:
+            return 2
+        return 1 if fail_check else 0
+    return 0 if bridge_present else 2
+
 
 def _emit_json(
     project_root: Path,
@@ -1370,17 +1539,12 @@ def main(argv: list[str] | None = None) -> int:
     manifest_pth = installed_tools.manifest_path(project_root)
     manifest = installed_tools.read_manifest(manifest_pth)
     if manifest is None:
-        print(
-            f"❌  doctor: no project lockfile at {manifest_pth}",
-            file=sys.stderr,
-        )
-        print(
-            f"    project_root: {project_root} (origin: {origin})",
-            file=sys.stderr,
-        )
-        print("    run `./agent-config init` to create one",
-              file=sys.stderr)
-        return 2
+        # No project lockfile. Under ADR-020 global-only this is a
+        # legitimate state, not an error — run the lockfile-independent
+        # checks and report consumer state instead of a hard bail. The
+        # per-scope split + exit-code contract live in _run_no_manifest.
+        bridge_present = (project_root / BRIDGE_MARKER_RELATIVE).is_file()
+        return _run_no_manifest(opts, project_root, origin, bridge_present)
 
     records, known = _collect_manifest_entries(project_root, manifest)
     missing, modified, tag_drift = _classify(records)

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"),
     }