@event4u/agent-config 3.0.0 → 3.1.1

package/docs/contracts/consumer-bridge.md

@@ -0,0 +1,79 @@
+---
+stability: beta
+keep-beta-until: 2026-08-21
+---
+
+# Consumer Bridge Marker
+
+**Status:** Proposed — road-to-global-only-install Phase 4.1.
+**Pairs with:** [`ADR-020 — global-only consumer scope`](../decisions/ADR-020-global-only-consumer-scope.md), [`ADR-007 § Amendment 2026-05-13`](../decisions/ADR-007-agent-discovery-scopes.md#amendment-2026-05-13--augment-global-only).
+
+## Purpose
+
+After Phase 3 of `road-to-global-only-install` lands, a consumer
+project carries **only** `agents/overrides/` plus this bridge marker.
+Every other agent artefact (rules, skills, commands, personas,
+settings, user identity) is read from `~/.event4u/agent-config/`. The
+bridge marker is the single, declarative pointer that lets per-tool
+adapters (Windsurf, Cline, Gemini-CLI, the Augment workspace
+projector) locate the global root from inside the repo.
+
+## File
+
+`agents/.event4u-bridge.yml` at the consumer project root. <!-- ref-ignore -->
+Written by `scripts/install.py` on every successful consumer install
+(global scope). Idempotent — same file, refreshed `installed_at`.
+
+## Schema
+
+```yaml
+schema: event4u-bridge/v1
+global_root: ~/.event4u/agent-config
+installed_at: 2026-05-23T14:00:00Z
+installer_version: 2.4.0
+```
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `schema` | string | yes | Must equal `event4u-bridge/v1`. Bumped on breaking field changes. |
+| `global_root` | string | yes | Absolute path or `~`-prefixed path to the global install. Readers MUST expand `~` against the current user's `$HOME`. |
+| `installed_at` | string (ISO-8601 UTC) | yes | Timestamp of the last successful install or refresh. |
+| `installer_version` | string (semver) | yes | Version of `@event4u/agent-config` that produced the marker. |
+
+Unknown fields are ignored by `v1` readers (forward-compat).
+
+## Reader contract
+
+Per-tool adapters MUST:
+
+1. Read `agents/.event4u-bridge.yml` from the project root. <!-- ref-ignore -->
+2. Reject `schema != event4u-bridge/v1` with a clear error pointing at this contract.
+3. Expand `~` in `global_root` against the **current process's** `$HOME` (not the writer's).
+4. Fail closed if `global_root` is missing on disk — never silently fall back to project-local lookup.
+5. Treat the marker as **read-only data**. Adapters MUST NOT write back through it.
+
+## Writer contract
+
+`scripts/install.py` MUST:
+
+1. Write the marker atomically (temp file + rename) so a crash never leaves a half-formed pointer.
+2. Refresh `installed_at` + `installer_version` on every consumer-scope install.
+3. Use `0644` permissions (world-readable, owner-writable). The marker contains no secrets.
+4. Skip the write under `AGENT_CONFIG_DEV_MODE=1` — maintainer dev installs never lay the bridge into the source repo (this repo's `agents/` directory is the project surface, not a consumer surface).
+
+## Per-tool anchor strategy
+
+Some AI tools only load rules when an anchor file is **inside** the workspace (Windsurf, Cline, Gemini-CLI). For those IDs, Phase 4.3 plants a thin pointer file under the tool's per-project directory whose body resolves to the bridge marker. Tools that load purely from user-scope (Claude Code, Cursor, Augment) read the marker once and need no per-tool file.
+
+## Out of scope
+
+- Cross-machine sync of `~/.event4u/agent-config/` (the marker is local-only).
+- Editing the marker by hand to swap installs (use `agent-config init --global-root=…` instead, once that flag ships in Phase 5).
+- Multi-tenant `global_root` (one marker = one global install per project).
+
+## References
+
+- [`ADR-020`](../decisions/ADR-020-global-only-consumer-scope.md) — global-only consumer scope; cites the in-flight roadmap for Phase 4 surface design + Phase 5 migration order.
+- [`ADR-007`](../decisions/ADR-007-agent-discovery-scopes.md) — scope precedence and the global-default amendment.

package/docs/contracts/discovery-manifest.md

@@ -0,0 +1,209 @@
+---
+stability: beta
+keep-beta-until: 2026-08-19
+---
+
+# Discovery manifest — worked-example reference
+
+> Companion to [ADR-015](../decisions/ADR-015-discovery-manifest-contract.md)
+> and [`discovery-manifest.schema.json`](discovery-manifest.schema.json).
+> The ADR is the decision; the schema is the contract; this file is the
+> worked-example reference linters, the installer, and contributors
+> cite at runtime.
+
+## Source of truth
+
+The generator
+[`scripts/build_discovery_manifest.py`](../../scripts/build_discovery_manifest.py)
+walks `.agent-src.uncompressed/` and emits the manifest to
+`dist/discovery/discovery-manifest.json` plus a sidecar
+`discovery-manifest.json.sha256` for tamper detection.
+
+```bash
+task build-discovery                  # regenerate the manifest
+task validate-discovery-manifest      # re-build to tempdir + diff committed
+task discovery-stats                  # pretty-print the stats block
+```
+
+`task ci` runs `build-discovery`, `validate-discovery-manifest`,
+`check-discovery-determinism`, and `check-artefact-checksums` so a
+stale committed manifest, a non-deterministic build, or a
+per-artefact checksum drift all fail CI (Phase-6 invariants).
+
+## Top-level shape
+
+```jsonc
+{
+  "version": 1,
+  "generated_at": "2026-05-21T00:00:00Z",
+  "scanner_version": "a1b2c3d4e5f6",
+  "checksum": "sha256:<64 hex>",
+  "workspaces": [ /* one entry per workspace in config/discovery/workspaces.yml */ ],
+  "packs":      [ /* one entry per pack in config/discovery/packs.yml */ ],
+  "artefacts":  [ /* sorted by path, ADR-013 frontmatter projected here */ ],
+  "unassigned": [ /* artefacts that failed assignment; reason required */ ],
+  "documented_unassigned": [ /* explicit skips from config/discovery/unassigned-artefacts.yml */ ],
+  "stats": { /* see below */ }
+}
+```
+
+- `version` — stays `1` for additive changes (ADR-015). Breaking → bump.
+- `generated_at` — UTC ISO-8601. **Only field allowed to differ** between
+  two determinism runs.
+- `scanner_version` — first 12 hex of `sha256(build_discovery_manifest.py)`.
+- `checksum` — `sha256:<hex>` of the JSON with `checksum` zeroed and
+  `generated_at` normalized to `"<normalised>"`.
+
+## Worked artefact entry
+
+```jsonc
+{
+  "path": ".agent-src.uncompressed/skills/laravel/SKILL.md",
+  "category": "skill",
+  "name": "laravel",
+  "workspaces": ["engineering"],
+  "packs": ["laravel"],
+  "requires": ["php"],
+  "lifecycle": "active",
+  "trust": {
+    "level": "professional",
+    "confidence": "high",
+    "human_review_required": false
+  },
+  "install": { "default": false, "removable": true },
+  "checksum": "sha256:<64 hex of normalized file content>"
+}
+```
+
+- `path` is the canonical identity. There is no `id` field — the path
+  is short, unique, and survives renames via git history (ADR-015).
+- `requires` is optional. Empty/absent → no extra pack dependencies
+  beyond the artefact's own `packs[]`.
+- `checksum` covers the on-disk bytes with frontmatter normalized
+  (sorted keys, trailing newline, no trailing whitespace). Used by the
+  Phase-3 installer for drift detection.
+
+## Worked pack entry
+
+```jsonc
+{
+  "id": "laravel",
+  "label": "Laravel",
+  "description": "PHP framework — Eloquent, Artisan, queues, jobs.",
+  "workspaces": ["engineering"],
+  "requires_hint": ["php"],
+  "trust_level_default": "professional",
+  "artefact_count": 18
+}
+```
+
+`requires_hint` is a vocabulary-side hint (lives in
+`config/discovery/packs.yml`); the canonical dependency edges sit on
+the artefact-level `requires` field, which the installer aggregates.
+
+## Stats block
+
+```jsonc
+{
+  "total_artefacts": 419,
+  "by_category":      { "skill": 246, "rule": 91, "command": 76, "template": 6 },
+  "by_lifecycle":     { "active": 405, "experimental": 12, "deprecated": 2, "archived": 0 },
+  "by_trust_level":   { "core": 142, "professional": 220, "experimental": 41, "advisory": 12, "restricted": 4 },
+  "unassigned_count": 0,
+  "documented_unassigned_count": 3
+}
+```
+
+Counts derive from the `artefacts[]` list — no second walk, no desync
+risk. The optional `_count` fields mirror the lengths of the
+`unassigned` and `documented_unassigned` arrays for dashboard ease.
+
+## Published files
+
+`task build-discovery` writes:
+
+| File | Purpose |
+|---|---|
+| `dist/discovery/discovery-manifest.json` | The canonical manifest. |
+| `dist/discovery/discovery-manifest.json.sha256` | Sidecar checksum of the on-disk file bytes. |
+| `dist/discovery/discovery-manifest.summary.md` | Human-readable workspace/pack summary. |
+| `dist/discovery/deprecation-report.md` | Phase-4 lifecycle report — lists every `lifecycle: deprecated` artefact with workspace / pack context. |
+| `dist/discovery/trust-report.md` | Phase-4 trust report — per-workspace breakdown of trust levels and `human_review_required` artefacts. |
+| `dist/discovery/orphan-report.md` | Phase-4 orphan report — non-experimental artefacts whose declared pack has no other members (typo signal). |
+| `dist/discovery/workspaces.json` | Phase-5 flattened workspace sub-view — per workspace, the set of packs + artefact paths visible in it. Lightweight surface for browser wizard previews. |
+| `dist/discovery/packs.json` | Phase-5 flattened pack sub-view — per pack, the artefact paths, plus `by_lifecycle` and `by_trust_level` counts. Lightweight surface for pack-picker UIs. |
+
+### Sub-view shape
+
+`workspaces.json` and `packs.json` carry the parent manifest's
+`checksum`, `generated_at`, and `scanner_version` so consumers can
+pin against the same source-of-truth version. Artefacts are
+referenced by `path` (the stable identity from the main manifest);
+there is no `id` field.
+
+```jsonc
+// workspaces.json
+{
+  "generated_at": "…",
+  "scanner_version": "…",
+  "checksum": "sha256:…",
+  "workspaces": [
+    {
+      "id": "engineering",
+      "label": "Engineering",
+      "description": "…",
+      "default_packs": ["engineering-base", "php", "laravel"],
+      "optional_packs": ["symfony"],
+      "artefact_count": 124,
+      "packs": [
+        { "id": "engineering-base", "artefact_count": 83, "artefacts": [".agent-src.uncompressed/skills/…/SKILL.md", "…"] }
+      ]
+    }
+  ]
+}
+```
+
+```jsonc
+// packs.json
+{
+  "generated_at": "…",
+  "scanner_version": "…",
+  "checksum": "sha256:…",
+  "packs": [
+    {
+      "id": "engineering-base",
+      "label": "Engineering Base",
+      "description": "…",
+      "workspaces": ["engineering"],
+      "requires_hint": [],
+      "trust_level_default": "core",
+      "artefact_count": 83,
+      "artefacts": [".agent-src.uncompressed/skills/…/SKILL.md", "…"],
+      "by_lifecycle":   { "active": 82, "experimental": 1, "deprecated": 0, "archived": 0 },
+      "by_trust_level": { "core": 83, "professional": 0, "experimental": 0, "advisory": 0, "restricted": 0 }
+    }
+  ]
+}
+```
+
+Both sub-views are byte-identical between two consecutive
+`task build-discovery` runs (modulo `generated_at`), same determinism
+guarantee as the main manifest.
+
+## Consumer guide
+
+- **Phase-3 installer** — reads `artefacts[]`, resolves `requires`,
+  verifies each file against its `checksum` before write.
+- **Browser wizard / docs site** — reads `workspaces[]`, `packs[]`,
+  `stats` to render pickers and counts.
+- **Third-party tools** — treat the schema as the contract; pin the
+  schema by `version` and watch for breaking-change ADRs.
+
+## See also
+
+- [ADR-013](../decisions/ADR-013-discovery-frontmatter-contract.md) —
+  the frontmatter contract (input side).
+- [ADR-015](../decisions/ADR-015-discovery-manifest-contract.md) —
+  the manifest contract (output side, this file).
+- [`frontmatter-contract.md`](frontmatter-contract.md) — per-artefact
+  worked frontmatter examples.

package/docs/contracts/discovery-manifest.schema.json

@@ -4,7 +4,7 @@
   "title": "Discovery Manifest",
   "description": "Release-time scan output for @event4u/agent-config. See ADR-013 and agents/roadmaps/archive/automated-pack-workspace-and-skill-discovery.md (archived, status: completed).",
   "type": "object",
-  "required": ["version", "generated_at", "scanner_version", "checksum", "workspaces", "packs", "artefacts", "unassigned"],
+  "required": ["version", "generated_at", "scanner_version", "checksum", "workspaces", "packs", "artefacts", "unassigned", "stats"],
   "additionalProperties": false,
   "properties": {
     "version": {
@@ -49,7 +49,8 @@
       "type": "array",
       "items": { "$ref": "#/$defs/unassigned" },
       "description": "Artefacts explicitly skipped via config/discovery/unassigned-artefacts.yml. Each entry MUST carry a reason."
-    }
+    },
+    "stats": { "$ref": "#/$defs/stats" }
   },
   "$defs": {
     "workspace_id": {
@@ -97,12 +98,29 @@
         "workspaces": { "type": "array", "items": { "$ref": "#/$defs/workspace_id" }, "minItems": 1 },
         "requires_hint": { "type": "array", "items": { "$ref": "#/$defs/pack_id" } },
         "trust_level_default": { "$ref": "#/$defs/trust_level" },
-        "artefact_count": { "type": "integer", "minimum": 0 }
+        "artefact_count": { "type": "integer", "minimum": 0 },
+        "human_review_required": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Phase 5 (ADR-018) — count of artefacts in this pack with trust.human_review_required=true. Zero for core-only packs."
+        },
+        "trust_summary": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Phase 5 (ADR-018) — per-pack artefact counts broken down by trust level. Sum equals artefact_count.",
+          "properties": {
+            "core":         { "type": "integer", "minimum": 0 },
+            "professional": { "type": "integer", "minimum": 0 },
+            "advisory":     { "type": "integer", "minimum": 0 },
+            "restricted":   { "type": "integer", "minimum": 0 },
+            "experimental": { "type": "integer", "minimum": 0 }
+          }
+        }
       }
     },
     "artefact": {
       "type": "object",
-      "required": ["path", "category", "workspaces", "packs", "lifecycle", "trust", "install"],
+      "required": ["path", "category", "workspaces", "packs", "lifecycle", "trust", "install", "checksum"],
       "additionalProperties": false,
       "properties": {
         "path": { "type": "string", "minLength": 1, "description": "POSIX path relative to repo root." },
@@ -110,6 +128,16 @@
         "name": { "type": "string" },
         "workspaces": { "type": "array", "items": { "$ref": "#/$defs/workspace_id" }, "minItems": 1 },
         "packs": { "type": "array", "items": { "$ref": "#/$defs/pack_id" }, "minItems": 1 },
+        "requires": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/pack_id" },
+          "description": "Optional dependency edges — pack IDs the artefact transitively needs at install time. Closed vocabulary."
+        },
+        "checksum": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$",
+          "description": "sha256 of the artefact file content with frontmatter normalized (sorted keys, no trailing whitespace, trailing newline). Drift-detection for the Phase-3 installer."
+        },
         "lifecycle": { "$ref": "#/$defs/lifecycle" },
         "trust": {
           "type": "object",
@@ -141,6 +169,51 @@
         "category": { "type": "string", "enum": ["skill", "rule", "command", "template", "unknown"] },
         "reason": { "type": "string", "minLength": 1 }
       }
+    },
+    "stats": {
+      "type": "object",
+      "required": ["total_artefacts", "by_category", "by_lifecycle", "by_trust_level"],
+      "additionalProperties": false,
+      "description": "Aggregate counts over the manifest. Cheap sanity surface for `task discovery-stats` and downstream dashboards.",
+      "properties": {
+        "total_artefacts": { "type": "integer", "minimum": 0 },
+        "by_category": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "skill":    { "type": "integer", "minimum": 0 },
+            "rule":     { "type": "integer", "minimum": 0 },
+            "command":  { "type": "integer", "minimum": 0 },
+            "template": { "type": "integer", "minimum": 0 }
+          },
+          "required": ["skill", "rule", "command", "template"]
+        },
+        "by_lifecycle": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "active":       { "type": "integer", "minimum": 0 },
+            "experimental": { "type": "integer", "minimum": 0 },
+            "deprecated":   { "type": "integer", "minimum": 0 },
+            "archived":     { "type": "integer", "minimum": 0 }
+          },
+          "required": ["active", "experimental", "deprecated", "archived"]
+        },
+        "by_trust_level": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "core":         { "type": "integer", "minimum": 0 },
+            "professional": { "type": "integer", "minimum": 0 },
+            "experimental": { "type": "integer", "minimum": 0 },
+            "advisory":     { "type": "integer", "minimum": 0 },
+            "restricted":   { "type": "integer", "minimum": 0 }
+          },
+          "required": ["core", "professional", "experimental", "advisory", "restricted"]
+        },
+        "unassigned_count": { "type": "integer", "minimum": 0 },
+        "documented_unassigned_count": { "type": "integer", "minimum": 0 }
+      }
     }
   }
 }

package/docs/contracts/explain-trace.schema.json

@@ -58,7 +58,7 @@
     },
     "route": {
       "type": ["object", "null"],
-      "description": "Rule-router activation snapshot. Null when router.json is absent.",
+      "description": "Rule-router activation snapshot. Null when dist/router.json is absent.",
       "required": ["matched_rules", "kernel_rules", "persona"],
       "additionalProperties": false,
       "properties": {