@event4u/agent-config 2.26.0 → 3.1.0

package/.agent-src/templates/hooks/pre-commit-roadmap-progress

@@ -1,60 +1,99 @@
 #!/usr/bin/env bash
-# Pre-commit hook: roadmap progress dashboard sync (event4u/agent-config)
+# Pre-commit hook: roadmap progress + artefact frontmatter
+# (event4u/agent-config — installed by `./agent-config hooks:install`).
 #
-# Installed by `./agent-config hooks:install`. Aborts the commit if
-# `agents/roadmaps-progress.md` is out of date relative to staged
-# changes under `agents/roadmaps/`. Exits silently when no roadmap
-# files are staged — zero overhead on unrelated commits.
+# Two opt-in checks run on relevant staged paths and short-circuit
+# otherwise:
+#   1. agents/roadmaps-progress.md sync (against agents/roadmaps/*.md)
+#   2. ADR-013 per-artefact frontmatter contract (.agent-src.uncompressed/*.md)
 #
 # To run manually:
 #   ./agent-config roadmap:progress-check
+#   python3 scripts/lint_artefact_frontmatter.py
 #
 # To uninstall:
 #   rm .git/hooks/pre-commit
 set -e
 
-# Only act on commits that touch roadmap content.
 staged="$(git diff --cached --name-only --diff-filter=ACMR 2>/dev/null || true)"
+
+roadmap_relevant=false
+frontmatter_relevant=false
 case "$staged" in
   *agents/roadmaps/*.md*|*agents/roadmaps-progress.md*|*.augment/scripts/update_roadmap_progress.py*)
-    : ;;
-  *)
-    exit 0 ;;
+    roadmap_relevant=true ;;
+esac
+case "$staged" in
+  *.agent-src.uncompressed/*.md*|*config/discovery/*.yml*|*scripts/lint_artefact_frontmatter.py*)
+    frontmatter_relevant=true ;;
 esac
 
-# Resolve the script — prefer the consumer-shipped path, fall back to
-# the source-of-truth copy when run from inside the package itself.
-script=""
-for cand in \
-  ".augment/scripts/update_roadmap_progress.py" \
-  ".agent-src/scripts/update_roadmap_progress.py" \
-  ".agent-src.uncompressed/scripts/update_roadmap_progress.py"; do
-  if [ -f "$cand" ]; then
-    script="$cand"
-    break
-  fi
-done
-
-if [ -z "$script" ]; then
-  echo "⚠️  pre-commit-roadmap-progress: update_roadmap_progress.py not found." >&2
-  echo "    Run \`task install\` (or \`./agent-config install\`) and retry." >&2
-  echo "    Skipping check — letting commit through." >&2
+if ! $roadmap_relevant && ! $frontmatter_relevant; then
   exit 0
 fi
 
-if ! python3 "$script" --check >/dev/null 2>&1; then
-  echo "❌  agents/roadmaps-progress.md is stale relative to your staged changes." >&2
-  echo "" >&2
-  echo "    Regenerate the dashboard with one of:" >&2
-  echo "      ./agent-config roadmap:progress" >&2
-  echo "      task roadmap-progress" >&2
-  echo "      python3 $script" >&2
-  echo "" >&2
-  echo "    Then \`git add agents/roadmaps-progress.md\` and retry the commit." >&2
-  echo "" >&2
-  echo "    To bypass once (NOT recommended):" >&2
-  echo "      git commit --no-verify" >&2
-  exit 1
+resolve() {
+  local cand
+  for cand in "$@"; do
+    if [ -f "$cand" ]; then
+      printf '%s\n' "$cand"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# --- Check 1: roadmap progress dashboard sync --------------------------
+if $roadmap_relevant; then
+  rp_script="$(resolve \
+    ".augment/scripts/update_roadmap_progress.py" \
+    ".agent-src/scripts/update_roadmap_progress.py" \
+    ".agent-src.uncompressed/scripts/update_roadmap_progress.py" || true)"
+
+  if [ -z "$rp_script" ]; then
+    echo "⚠️  pre-commit: update_roadmap_progress.py not found — skipping roadmap check." >&2
+  elif ! python3 "$rp_script" --check >/dev/null 2>&1; then
+    echo "❌  agents/roadmaps-progress.md is stale relative to your staged changes." >&2
+    echo "" >&2
+    echo "    Regenerate the dashboard with one of:" >&2
+    echo "      ./agent-config roadmap:progress" >&2
+    echo "      task roadmap-progress" >&2
+    echo "      python3 $rp_script" >&2
+    echo "" >&2
+    echo "    Then \`git add agents/roadmaps-progress.md\` and retry the commit." >&2
+    echo "" >&2
+    echo "    To bypass once (NOT recommended):" >&2
+    echo "      git commit --no-verify" >&2
+    exit 1
+  fi
+fi
+
+# --- Check 2: ADR-013 artefact frontmatter contract --------------------
+if $frontmatter_relevant; then
+  fm_script="$(resolve \
+    ".augment/scripts/lint_artefact_frontmatter.py" \
+    ".agent-src/scripts/lint_artefact_frontmatter.py" \
+    "scripts/lint_artefact_frontmatter.py" || true)"
+
+  if [ -z "$fm_script" ]; then
+    echo "⚠️  pre-commit: lint_artefact_frontmatter.py not found — skipping frontmatter check." >&2
+  elif ! python3 "$fm_script" --quiet >/dev/null 2>&1; then
+    echo "❌  Artefact frontmatter lint failed (ADR-013 contract violation)." >&2
+    echo "" >&2
+    echo "    Re-run for details:" >&2
+    echo "      python3 $fm_script" >&2
+    echo "      task lint-artefact-frontmatter" >&2
+    echo "" >&2
+    echo "    Common fixes:" >&2
+    echo "      • Add missing workspaces/packs/lifecycle/trust/install keys." >&2
+    echo "      • Pick values from config/discovery/{workspaces,packs}.yml." >&2
+    echo "      • For scaffolds, add the path to" >&2
+    echo "        config/discovery/unassigned-artefacts.yml with a reason." >&2
+    echo "" >&2
+    echo "    To bypass once (NOT recommended):" >&2
+    echo "      git commit --no-verify" >&2
+    exit 1
+  fi
 fi
 
 exit 0

package/.agent-src/templates/rule.md

@@ -31,7 +31,7 @@ both reject the legacy prefix.
 |---|---|
 | `contexts/execution/verification-mechanics.md` | `.agent-src.uncompressed/contexts/execution/verification-mechanics.md` |
 | `contexts/authority/commit-mechanics.md` | `.agent-src.uncompressed/contexts/authority/commit-mechanics.md` |
-| `agents/contexts/local.md` (project-local) | `.agent-src.uncompressed/contexts/...` for project-only material |
+| `agents/settings/contexts/local.md` (project-local) | `.agent-src.uncompressed/contexts/...` for project-only material |
 
 ### `triggers[].path_prefix:` — literal match pattern, not a file path
 

package/.agent-src/templates/scripts/work_engine/_lib/agent_settings.py

@@ -22,7 +22,7 @@ Step 7 the anchor set is (closest-leaf wins; tiebreaker
 ``.agent-settings.yml`` > ``agents/`` > ``.git``):
 
 * ``.agent-settings.yml`` file,
-* ``agents/`` directory containing ``roadmaps/``, ``.ai-council.yml``,
+* ``agents/`` directory containing ``roadmaps/``, ``settings/.ai-council.yml``,
   or ``roadmaps-progress.md`` (bare ``agents/`` does **not** anchor),
 * ``.git`` file or directory (submodule support).
 
@@ -99,11 +99,14 @@ ANCHOR_GIT = "git"
 
 #: Marker subpaths that qualify a bare ``agents/`` directory as a project
 #: anchor (D1). Any one is sufficient. Bare ``agents/`` without a marker
-#: is **not** an anchor.
+#: is **not** an anchor. ``.event4u-bridge.yml`` is the global-only
+#: consumer anchor (ADR-020 § Phase 4.2) — a clean consumer repo only
+#: ever ships ``agents/overrides/`` plus this marker.
 _AGENTS_DIR_MARKERS: tuple[str, ...] = (
     "roadmaps",
-    ".ai-council.yml",
+    "settings/.ai-council.yml",
     "roadmaps-progress.md",
+    ".event4u-bridge.yml",
 )
 
 #: Kill-switch (D5). When set to ``"1"``, :func:`find_project_root` and
@@ -148,7 +151,7 @@ def find_project_root_with_anchor(start: Path) -> tuple[Path, str] | None:
        a boundary anchor wins:
 
        * ``agents/`` containing **any** of ``roadmaps/``,
-         ``.ai-council.yml``, or ``roadmaps-progress.md`` (D1) →
+         ``settings/.ai-council.yml``, or ``roadmaps-progress.md`` (D1) →
          ``"agents-dir"``
        * ``.git`` (file or directory; submodule support) → ``"git"``
 

package/.agent-src/templates/scripts/work_engine/cli.py

@@ -99,7 +99,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         HookContext(state_file=state_file, args=args),
     )
     if halt is not None:
-        return _emit_halt(halt)
+        return _emit_halt(halt, state_file=state_file, event="BEFORE_LOAD")
 
     try:
         work, fmt = _load_or_build(state_file, args)
@@ -112,7 +112,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         HookContext(state_file=state_file, work=work, fmt=fmt, args=args),
     )
     if halt is not None:
-        return _emit_halt(halt)
+        return _emit_halt(halt, work=work, state_file=state_file, event="AFTER_LOAD")
 
     try:
         set_name = select_directive_set(work)
@@ -129,7 +129,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         HookContext(work=work, delivery=delivery, set_name=set_name, args=args),
     )
     if halt is not None:
-        return _emit_halt(halt)
+        return _emit_halt(halt, work=work, state_file=state_file, event="BEFORE_DISPATCH")
 
     final, halting = dispatch(delivery, steps, hooks=runner)
 
@@ -144,7 +144,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         ),
     )
     if halt is not None:
-        return _emit_halt(halt)
+        return _emit_halt(halt, work=work, state_file=state_file, event="AFTER_DISPATCH")
 
     _sync_back(work, delivery)
 
@@ -153,7 +153,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         HookContext(work=work, delivery=delivery, fmt=fmt, args=args),
     )
     if halt is not None:
-        return _emit_halt(halt)
+        return _emit_halt(halt, work=work, state_file=state_file, event="BEFORE_SAVE")
 
     _save(state_file, work, fmt)
 
@@ -163,7 +163,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     )
     if halt is not None:
         # State is already on disk; exit 2 still per the P3 branch table.
-        return _emit_halt(halt)
+        return _emit_halt(halt, work=work, state_file=state_file, event="AFTER_SAVE")
 
     _emit(work, final, halting)
     return 0 if final is Outcome.SUCCESS else 1

package/.agent-src/templates/scripts/work_engine/emitters.py

@@ -8,10 +8,12 @@ on stdout, and the lifecycle-hook halt surface printed on stderr.
 from __future__ import annotations
 
 import sys
+from datetime import datetime, timezone
+from pathlib import Path
 
 from .delivery_state import Outcome
 from .hooks import HookHalt
-from .state import WorkState
+from .state import WorkState, dump
 
 
 def _emit(work: WorkState, final: Outcome, halting: str | None) -> None:
@@ -23,20 +25,43 @@ def _emit(work: WorkState, final: Outcome, halting: str | None) -> None:
         print(line)
 
 
-def _emit_halt(halt: HookHalt) -> int:
+def _emit_halt(
+    halt: HookHalt,
+    *,
+    work: WorkState | None = None,
+    state_file: Path | None = None,
+    event: str | None = None,
+) -> int:
     """Render a :class:`HookHalt` surface to stderr and return exit 2.
 
     Per the P3 halt branch table, every CLI-layer halt yields exit code
     ``2`` regardless of which event fired it. State persistence is
     governed by *where* in ``main`` the halt is detected: the call site
-    decides whether ``_save`` already ran. This helper is the single
-    place that formats the surface so the wire output stays consistent.
+    decides whether ``_save`` already ran.
+
+    When ``work`` + ``state_file`` are provided AND the state file
+    already exists on disk, the halt is appended to ``work.halts[]``
+    and the state is re-saved. This lets ``agent-config explain last``
+    surface the halt reason later. Fresh-run halts before the first
+    ``_save`` (state file absent) still leave no state on disk — the
+    pre-explain-v2 contract is preserved.
     """
     if halt.surface:
         for line in halt.surface:
             print(line, file=sys.stderr)
     else:
         print(f"halt: {halt.reason}", file=sys.stderr)
+    if work is not None and state_file is not None and state_file.exists():
+        work.halts.append({
+            "reason": halt.reason,
+            "step": event or "",
+            "surface": list(halt.surface),
+            "timestamp": datetime.now(tz=timezone.utc).isoformat(),
+        })
+        try:
+            dump(work, state_file)
+        except Exception:  # never let halt persistence mask the halt
+            pass
     return 2
 
 

package/.agent-src/templates/scripts/work_engine/hooks/builtin/decision_trace.py

@@ -13,7 +13,7 @@ Trace layout (matches the contract):
 
 * ``schema_version: 1``
 * ``work_id`` — derived from the state-file directory name when the
-  caller follows the ``agents/state/work/<id>/state.json`` convention,
+  caller follows the ``agents/runtime/state/work/<id>/state.json`` convention,
   else from the state-file stem.
 * ``phase`` — engine ``step_name`` (refine/memory/.../report).
 * ``started_at`` / ``ended_at`` — ISO-8601 UTC timestamps captured on
@@ -56,8 +56,8 @@ class DecisionTraceHook:
     output_dir:
         Optional override for the trace destination. When ``None`` the
         hook writes alongside the WorkState file: if the state file
-        sits under ``agents/state/work/<id>/state.json`` the trace
-        lands at ``agents/state/work/<id>/decision-trace-<phase>.json``;
+        sits under ``agents/runtime/state/work/<id>/state.json`` the trace
+        lands at ``agents/runtime/state/work/<id>/decision-trace-<phase>.json``;
         otherwise the trace lands next to the state file as
         ``<stem>.decision-trace-<phase>.json``.
     """

package/.agent-src/templates/scripts/work_engine/orchestration.py

@@ -57,21 +57,35 @@ class PipelineState:
 def _load_pipeline(path: Path) -> dict[str, Any]:
     """Reuse the linter's loader so the runtime accepts the same shape.
 
-    Walks parents to find a directory containing ``scripts/hooks/``
-    so the loader is reachable both when this module runs from the
-    consumer projection (``.agent-src/templates/scripts/work_engine/``)
-    and from the source-of-truth tree
-    (``.agent-src.uncompressed/templates/scripts/work_engine/``).
+    Walks parents to find ``scripts/hooks/dispatch_hook.py`` so the
+    loader is reachable both when this module runs from the consumer
+    projection (``.agent-src/templates/scripts/work_engine/``) and
+    from the source-of-truth tree
+    (``packages/<pack>/.agent-src.uncompressed/templates/scripts/work_engine/``).
+    Loaded via ``importlib.util`` by file path to avoid namespace
+    collisions with test packages named ``hooks``.
     """
-    import sys
+    import importlib.util
     here = Path(__file__).resolve()
+    candidate: Path | None = None
     for parent in here.parents:
-        candidate = parent / "scripts" / "hooks" / "dispatch_hook.py"
-        if candidate.is_file():
-            sys.path.insert(0, str(parent / "scripts"))
+        probe = parent / "scripts" / "hooks" / "dispatch_hook.py"
+        if probe.is_file():
+            candidate = probe
             break
-    from hooks.dispatch_hook import _load_yaml  # noqa: E402
-    doc = _load_yaml(path)
+    if candidate is None:
+        raise RuntimeError(
+            "could not locate scripts/hooks/dispatch_hook.py from "
+            f"{here}"
+        )
+    spec = importlib.util.spec_from_file_location(
+        "_work_engine_dispatch_hook", candidate
+    )
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot load spec for {candidate}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    doc = module._load_yaml(path)
     if not isinstance(doc, dict):
         raise ValueError(f"{path}: top-level must be a mapping")
     return doc

package/.agent-src/templates/scripts/work_engine/state.py

@@ -49,6 +49,15 @@ The wire format adds five envelope fields on top of the legacy
   ``verdict`` (success / blocked / partial), and the
   ``integration_confirmed`` flag the user sets after reviewing the
   integration evidence.
+- ``halts`` — append-only log of :class:`HookHalt` events the engine
+  persisted into state. Populated by :func:`emitters._emit_halt` when
+  it runs against an already-persisted state file (the P3 branch table
+  is preserved: fresh-run halts before the first ``_save`` still leave
+  no state on disk). The ``explain_last`` trace builder reads the
+  tail entry to fill the ``trace.halt`` slot. Each entry is
+  ``{reason, step, surface, timestamp}``. The list defaults to empty
+  and is omitted from older state files via ``from_dict``'s tolerant
+  reader — no schema-version bump.
 
 All other fields keep their v0 names so the dispatcher can read the
 legacy slice unchanged once Phase 3 wires the steps over.
@@ -153,6 +162,7 @@ class WorkState:
     ui_polish: dict[str, Any] | None = None
     contract: dict[str, Any] | None = None
     stitch: dict[str, Any] | None = None
+    halts: list[dict[str, Any]] = field(default_factory=list)
     version: int = SCHEMA_VERSION
     persona: str = "senior-engineer"
     memory: list[dict[str, Any]] = field(default_factory=list)
@@ -187,6 +197,7 @@ def to_dict(state: WorkState) -> dict[str, Any]:
     _validate_ui_polish(state.ui_polish)
     _validate_contract(state.contract)
     _validate_stitch(state.stitch)
+    _validate_halts(state.halts)
     return {
         "version": state.version,
         "input": {"kind": state.input.kind, "data": state.input.data},
@@ -199,6 +210,7 @@ def to_dict(state: WorkState) -> dict[str, Any]:
         "ui_polish": state.ui_polish,
         "contract": state.contract,
         "stitch": state.stitch,
+        "halts": list(state.halts),
         "persona": state.persona,
         "memory": state.memory,
         "plan": state.plan,
@@ -269,6 +281,9 @@ def from_dict(payload: Any) -> WorkState:
     stitch = payload.get("stitch")
     _validate_stitch(stitch)
 
+    halts = payload.get("halts", [])
+    _validate_halts(halts)
+
     return WorkState(
         input=Input(kind=kind, data=data),
         intent=payload.get("intent", DEFAULT_INTENT),
@@ -280,6 +295,7 @@ def from_dict(payload: Any) -> WorkState:
         ui_polish=dict(ui_polish) if isinstance(ui_polish, dict) else None,
         contract=dict(contract) if isinstance(contract, dict) else None,
         stitch=dict(stitch) if isinstance(stitch, dict) else None,
+        halts=list(halts) if isinstance(halts, list) else [],
         version=version,
         persona=payload.get("persona", "senior-engineer"),
         memory=list(payload.get("memory", [])),
@@ -625,6 +641,43 @@ def _validate_stitch(stitch: Any) -> None:
         )
 
 
+def _validate_halts(halts: Any) -> None:
+    """Reject malformed ``halts`` envelopes; tolerate ``[]``.
+
+    Each entry must be a dict with at minimum ``reason`` (str) and
+    ``surface`` (list of str). ``step`` and ``timestamp`` are optional
+    metadata appended by ``emitters._emit_halt``. The schema enforces
+    only shape — the explain renderer is responsible for fallback
+    rendering when optional fields are absent.
+    """
+    if not isinstance(halts, list):
+        raise SchemaError(
+            f"state.halts must be a list; got {type(halts).__name__}",
+        )
+    for idx, entry in enumerate(halts):
+        if not isinstance(entry, dict):
+            raise SchemaError(
+                f"state.halts[{idx}] must be a JSON object; "
+                f"got {type(entry).__name__}",
+            )
+        reason = entry.get("reason")
+        if not isinstance(reason, str) or not reason:
+            raise SchemaError(
+                f"state.halts[{idx}].reason must be a non-empty string",
+            )
+        surface = entry.get("surface", [])
+        if not isinstance(surface, list):
+            raise SchemaError(
+                f"state.halts[{idx}].surface must be a list; "
+                f"got {type(surface).__name__}",
+            )
+        for j, line in enumerate(surface):
+            if not isinstance(line, str):
+                raise SchemaError(
+                    f"state.halts[{idx}].surface[{j}] must be a string",
+                )
+
+
 __all__ = [
     "DEFAULT_DIRECTIVE_SET",
     "DEFAULT_INTENT",

package/.agent-src/templates/skill-archive-note.md

@@ -1,6 +1,6 @@
 # Skill Archive Note Template
 
-> Template for `agents/archived-skills/<slug>.md`. Created during
+> Template for `agents/evidence/archived-skills/<slug>.md`. Created during
 > `step-2-skill-inventory-rationalization.md`
 > Phase 4 execution. Every skill removed from
 > `.agent-src.uncompressed/skills/` MUST have a matching archive note
@@ -8,7 +8,7 @@
 
 ## Instructions
 
-1. Create the file: `agents/archived-skills/{slug}.md`.
+1. Create the file: `agents/evidence/archived-skills/{slug}.md`.
 2. Copy the template body below and fill every required field.
 3. Commit alongside the SKILL.md removal in the same PR (the linter
    refuses to pass if the pair drifts).
@@ -88,12 +88,12 @@ references the removed slug without pointing at this note.}
 
 `scripts/lint_archived_skills.py` enforces:
 
-1. Every file under `agents/archived-skills/*.md` (except the README)
+1. Every file under `agents/evidence/archived-skills/*.md` (except the README)
    has a frontmatter block with the six required fields.
 2. `reason` is one of the four allowed values.
 3. When `reason ∈ {merged, superseded}`, the `replacement` slug exists
    under `.agent-src.uncompressed/skills/`.
-4. Every slug under `agents/archived-skills/` is *absent* from
+4. Every slug under `agents/evidence/archived-skills/` is *absent* from
    `.agent-src.uncompressed/skills/` (no zombies).
 5. No SKILL.md present under `.agent-src.uncompressed/skills/`
    references an archived slug as a router target.

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "2.26.0",
+    "version": "3.1.0",
     "keywords": [
       "agent-config",
       "skills",
@@ -186,6 +186,7 @@
         "./.claude/skills/hiring-loop-design",
         "./.claude/skills/implement-ticket",
         "./.claude/skills/incident-commander",
+        "./.claude/skills/install-via-agent",
         "./.claude/skills/jira-integration",
         "./.claude/skills/jira-ticket",
         "./.claude/skills/jobs-events",
@@ -243,7 +244,6 @@
         "./.claude/skills/multi-tenancy",
         "./.claude/skills/nextjs-patterns",
         "./.claude/skills/okr-tree-modeling",
-        "./.claude/skills/onboard",
         "./.claude/skills/onboarding-design",
         "./.claude/skills/onboarding-program",
         "./.claude/skills/one-on-one-cadence",

package/AGENTS.md

@@ -4,7 +4,7 @@
 
 ## Source of truth
 
-Edit `.agent-src.uncompressed/` only. Generated trees (`.agent-src/`, `.augment/`, `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`) regenerate from `task sync` + `task generate-tools`; never hand-edit.
+Edit `packages/<pack>/.agent-src.uncompressed/` only. Generated trees (`.agent-src/`, `.augment/`, `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`) regenerate from `task sync` + `task generate-tools`; never hand-edit.
 
 ## Working on this repo
 
@@ -12,23 +12,26 @@ Edit `.agent-src.uncompressed/` only. Generated trees (`.agent-src/`, `.augment/
 task sync              # regenerate .agent-src/, .augment/
 task generate-tools    # regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
 task ci                # full pipeline — green before PR
+# maintainer: AGENT_CONFIG_DEV_MODE=1 opens --scope=project (docs/maintainers/dev-mode.md)
 ```
 
 ## Pointers
 
-- **Package self-orientation** (beta) — identity, four-wing cognition map, repo layout, tech stack, key-rules table, telemetry, command-suggester: [`docs/contracts/package-self-orientation.md`](docs/contracts/package-self-orientation.md).
-- **Kernel + Router** (beta) — 9 always-loaded Iron-Law rules, tier-1 / tier-2 routing, cost profiles, per-rule char caps enforced by `task lint-rule-budget`: [`kernel-membership`](docs/contracts/kernel-membership.md) + [`rule-router`](docs/contracts/rule-router.md).
-- **Content pipelines** — A [source projection](docs/architecture/source-projection.md), B [Augment projection](docs/architecture/augment-projection.md), C [multi-tool projection](docs/architecture/multi-tool-projection.md), D [Claude.ai bundle](docs/architecture/claude-bundle.md). Index: [`docs/architecture.md`](docs/architecture.md).
-- **Editing this repo** — Iron-Law rules (edit-discipline, source-of-truth, skill-quality) + Thin-Root contract: [`augment-edit-discipline`](.agent-src/rules/augment-edit-discipline.md), [`augment-source-of-truth`](.agent-src/rules/augment-source-of-truth.md), [`skill-quality`](.agent-src/rules/skill-quality.md), [`agents-md-thin-root`](.agent-src/skills/agents-md-thin-root/SKILL.md).
-- **Consumer story** — `npx` + `scripts/install.sh` + `.agent-settings.yml` opt-in flags, sandbox/offline install paths, verified-offline manifest: [`README.md`](README.md).
-- **Personas** — 11 review-lens cast (6 core · 5 specialist), `personas:` vs `/mode` axes, citation map, override pattern: [`docs/personas.md`](docs/personas.md), schema [`docs/contracts/persona-schema.md`](docs/contracts/persona-schema.md) (beta).
+- **Package self-orientation** — identity, cognition map, layout, stack, key rules, telemetry: [`package-self-orientation`](docs/contracts/package-self-orientation.md).
+- **Kernel + Router** — 9 Iron-Law rules, tier-1/2 routing, cost profiles, per-rule caps: [`kernel-membership`](docs/contracts/kernel-membership.md) + [`rule-router`](docs/contracts/rule-router.md).
+- **Trust & Safety** — trust-level enum, HRR banner, safety floors, installer confirm: [`trust-and-safety`](docs/contracts/trust-and-safety.md) + [`ADR-018`](docs/decisions/ADR-018-trust-and-safety-layer.md).
+- **Content pipelines** — A→D source / Augment / multi-tool / Claude.ai-bundle projections, indexed at [`docs/architecture.md`](docs/architecture.md); sub-pipelines under [`docs/architecture/`](docs/architecture/).
+- **Editing this repo** — Iron-Law rules + Thin-Root contract govern every change: [`augment-source-of-truth`](.agent-src/rules/augment-source-of-truth.md) + [`agents-md-thin-root`](.agent-src/skills/agents-md-thin-root/SKILL.md).
+- **Consumer story** — `npx` + `scripts/install.sh` opt-in flags, sandbox / offline install paths, verified-offline manifest: [`README.md`](README.md).
+- **Personas** — 11 review-lens cast (6 core · 5 specialist), `personas:` vs `/mode`: [`docs/personas.md`](docs/personas.md).
+- **Discovery** — workspaces / packs / dist manifest; contract [`ADR-013`](docs/decisions/ADR-013-discovery-frontmatter-contract.md), how-to [`customization § Workspaces & packs`](docs/customization.md#workspaces--packs-discovery).
 
 ## Emergency triage — read this when nothing else is reachable
 
 1. **What is this repo?** — `event4u/agent-config`, a governed skill / rule / command suite for AI coding tools (no application runtime).
 2. **What language?** — All `.md` content is English; agents mirror the user's language at runtime.
-3. **Where do I edit?** — `.agent-src.uncompressed/` only. Never the generated trees.
+3. **Where do I edit?** — `packages/<pack>/.agent-src.uncompressed/` only. Never the generated trees.
 4. **Lint / test / sync entry point?** — `task ci` (full pipeline). Subsets: `task sync`, `task generate-tools`, `task lint-skills`, `task test`.
-5. **Where do the always-active rules live?** — `.agent-src/rules/` (kernel = 9 Iron-Law rules; tier-1 / tier-2 routed via `.agent-src/router.json`).
+5. **Where do the always-active rules live?** — `.agent-src/rules/` (kernel = 9 Iron-Law rules; tier-1 / tier-2 routed via `dist/router.json`).