@event4u/agent-config 7.5.0 → 8.1.0

package/docs/contracts/command-clusters.md

@@ -56,6 +56,7 @@ column 1 of this table.
 | `image` | — | `analyse` · `create` · `verify` | new cluster 2026-05-31 (`road-to-character-image-fidelity` Phase 4) — character-image fidelity surface mirroring `/video:*`. `:analyse` extracts a per-feature spec from an image and diffs it against a Canon Spec down to the smallest mole (OCR for lettered tattoos, per-section severity scores, canon-breaking hard gate); `:create` assembles a max-fidelity anchors-first generation prompt from the Canon Spec, governance- + provider-gated, `AIV_DRYRUN=true` default; `:verify` runs the analyser in loop mode against a candidate and reports the gate verdict + remaining diff with plateau/oscillation/budget stop conditions. Skills: [`image-analyser`](../../skills/image-analyser/SKILL.md) + [`image-creator`](../../skills/image-creator/SKILL.md); schema/rubric/loop in [`canon-spec.md`](../../skills/image-analyser/canon-spec.md). |
 | `brand` | — | `strategy` · `identity` · `tokens` · `review` · `voice` | new cluster 2026-06-17 (`road-to-image-brand-followups` Phase 3) — brand-as-first-class-UX surface for `pack-brand`, consulted before `design-intelligence` so brand bounds style. `:strategy` (positioning/archetype/voice/messaging over the brand corpus), `:identity` (logo/colour/type/imagery direction — defines the tokens downstream generation consumes), `:tokens` (derive a DTCG `.tokens.json` source of truth → CSS/Tailwind, no Node), `:review` (audit emitted UI/copy/assets against active brand tokens + voice per the `brand-consistency` gate), `:voice` (voice-and-tone profile). Skills: [`brand-strategy`](../../skills/brand-strategy/SKILL.md) · [`brand-identity`](../../skills/brand-identity/SKILL.md) · [`brand-to-tokens`](../../skills/brand-to-tokens/SKILL.md) · [`brand-audit`](../../skills/brand-audit/SKILL.md) · [`voice-and-tone-design`](../../skills/voice-and-tone-design/SKILL.md). The companion `/imagegen:*` generation cluster (pack-ai-image) is deferred until its adapters' live submit/poll/fetch is wired. |
 
+| `team-knowledge` | — | `consolidate` · `bootstrap` | new cluster 2026-07-05 (`road-to-knowledge-system` Phases 5-6) — the repo-tracked team-knowledge layer under `agents/knowledge/{sessions,concepts,procedures,decisions}/`. Distinct from the pre-existing [`knowledge`](#locked-clusters) cluster (arbitrary local-file ingestion into `agents/memory/knowledge/`) — different namespace, different concern. `:consolidate` reads pending typed-observation events (`consolidate_knowledge_events.ts`), finds the nearest existing page per topic (mechanical similarity), and presents a NEW/EXTEND/CONFIRM/CONFLICT batch for human approval — never writes a page automatically. `:bootstrap` (`bootstrap_knowledge.ts`) stages a one-shot deterministic seed (detected package manifest, top-level directories, known config filenames — never file content, never an LLM-invented claim) to a gitignored staging dir for review-then-commit. |
 | `profile` | — | `activate` · `deactivate` · `show` | new cluster 2026-06-02 (`road-to-session-profile-activation`) — session-profile activation: an ephemeral `runtime.active_packs` overlay that biases the surfaced command/skill set to the active pack closure, with no persistence and no execution-gating (recommendation-bias MVP). `:activate <name…>` resolves an alias (`src/config/discovery/session-profiles.yml`) or a raw pack id, fails fast on a not-installed pack, expands the `requires_hint` closure, and writes the overlay atomically to `agents/settings/.agent-settings.local.yml`; `:deactivate [name…]` clears it (or drops named packs, keeping deps a still-active pack needs); `:show` is the observability surface (active packs + surfaced/hidden counts). Overlay = runtime modulation of the existing `pack` axis, not a fifth axis (ADR-010 addendum). Library: `scripts/config/session_profiles.py`; schema in [`session-profile-overlay`](session-profile-overlay.md). |
 
 **Net change:** Phase 1 collapsed 15 atomics → 3 clusters; Phase 2

package/docs/contracts/command-surface-tiers.md

@@ -41,7 +41,7 @@ The path a new contributor walks on day one. Visible in
 2. **Stable surface.** The command name + flag set has not changed
    in the last two minor releases (or is brand-new with a
    commitment to two-release stability).
-3. **No prerequisite tooling beyond `bash` + `python3`.** Docker,
+3. **No prerequisite tooling beyond `bash` + `node`.** Docker,
    GPG, jq, gh CLI, npm globals are all Tier-1+ territory.
 4. **Cited in the `init → sync → validate → work` outcome path.**
    Setup helpers (`first-run`, `keys:install-*`) and AI-Council entry

package/docs/contracts/conformance.md

@@ -0,0 +1,84 @@
+---
+stability: beta
+keep-beta-until: 2026-10-01
+---
+
+# Conformance contract — green means installed AND firing
+
+> **Status:** active · **Owner:** maintainer · **Siblings:**
+> [`install-layout.md`](install-layout.md) · [`smoke-contracts.md`](smoke-contracts.md)
+
+`task conformance` (equivalently `agent-config conformance`) is the
+consumer-runnable, CI-shaped answer to one question:
+
+> **Is agent-config installed *and firing* in this repo?**
+
+It is deterministic — no LLM, no network — and safe to wire into a
+consumer repo's CI. A green run is the "conformance badge" a repo earns;
+a red run names the exact broken surface and its remedy.
+
+## § 1 — What runs
+
+Two legs, one exit code:
+
+1. **Doctor under the `--ci` contract.** `agent-config doctor --ci` runs
+   the full drift scan plus every registered health check, emits a JSON
+   payload, and — unlike the default doctor run, which keys its exit off
+   drift only — folds **any check failure** into the exit code.
+2. **Five conformance checks** (registered in
+   `src/scripts/_cli/cmd_conformance.ts`):
+
+| id | proves | red when |
+|---|---|---|
+| `txlog-clean` | the last install completed | the install-log tail is an abandoned `abort` |
+| `router-pointers` | the installed rule index is intact | any rule id or `routes_to` target does not resolve on disk |
+| `hook-dispatcher` | hooks actually fire on this host | the dispatcher errors on a synthetic `session_start` / `stop` envelope |
+| `lean-projection` | `lean_projection.mode` matches reality | projected non-kernel rules contradict the configured mode |
+| `host-manifest` | `subagents.host_capabilities` is well-formed | unknown keys / non-boolean values (typo guard) |
+
+Every check returns `ok` / `warn` / `fail` / `skipped` with a one-line
+remedy. `skipped` means "not applicable here", never "silently passed".
+
+## § 2 — Exit-code contract
+
+| Exit | Meaning |
+|---|---|
+| `0` | Green — no check failed, no drift. Warnings allowed. |
+| `1` | Red — at least one check failed, or manifest drift present. |
+| `2` | Environment unresolvable (no project root, corrupt setup). |
+
+The same contract applies to `agent-config doctor --ci` standalone.
+
+## § 3 — Report line (fleet aggregation)
+
+Every run appends exactly one JSONL line — mirroring the install-txlog
+entry shape — to `~/.event4u/agent-config/conformance-log.jsonl`
+(override: `AGENT_CONFIG_CONFORMANCE_LOG`):
+
+```json
+{"ts":"2026-07-07T10:00:00.000Z","kind":"conformance","path":"/repo","sha256":null,"note":"5/5 ok; fails: none"}
+```
+
+Fleet installs (`--fleet`) aggregate these lines into their per-repo
+summary; the line is append-only and never breaks the exit contract.
+
+## § 4 — Pre-install twin: `init --validate-only`
+
+`agent-config init --validate-only` is the **pre-install** gate — the
+typed pre-flight suite (`src/install/preflight.ts`): target-root
+permissions, free-disk floor, conflict detection, host-detection
+sanity. Nothing is written. Exit `0` = clear, `1` = blocking finding,
+`2` = no runner. `--dry-run` (full plan print) and `--minimal`
+(settings-only bootstrap) are the existing siblings; `--validate-only`
+completes the trio.
+
+## § 5 — CI wiring (consumer)
+
+```yaml
+- name: agent-config conformance
+  run: npx @event4u/agent-config conformance
+```
+
+Green conformance in a consumer pipeline is the supported way to assert
+"the OS is installed and firing here" — instead of hand-rolled greps
+over projected files.

package/docs/contracts/creative-pack-boundary.md

@@ -1,3 +1,8 @@
+---
+stability: beta
+keep-beta-until: 2026-08-17
+---
+
 # Creative Pack boundary — video is an optional pack, not core identity
 
 The `ai-video` (Creative) pack is a **bounded, optional** capability: a first-class

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

@@ -151,7 +151,7 @@
       "additionalProperties": false,
       "properties": {
         "path": { "type": "string", "minLength": 1, "description": "POSIX path relative to repo root." },
-        "category": { "type": "string", "enum": ["skill", "rule", "command", "template"] },
+        "category": { "type": "string", "enum": ["skill", "rule", "command", "template", "subagent"] },
         "name": { "type": "string" },
         "pack": { "$ref": "#/$defs/pack_id", "description": "capability-packs.md — canonical OWNER pack (ownership/budget unit). Orthogonal to `packs` (discovery tags); the owner need not appear in `packs`." },
         "tier": { "type": "integer", "enum": [0, 1, 2], "description": "6.0.0-C — command-surface tier surfaced on `category: command` artefacts so the CLI discovery surface reads the manifest, not a parallel catalog. DEPRECATED back-compat alias of `visibility` since ADR-090; still dual-emitted (non-breaking) but announced for removal in the top-level `deprecations` block (road-to-tier-removal Phase 1 / ADR-092). Read `visibility`." },
@@ -160,8 +160,8 @@
         "routes_to": { "type": "array", "items": { "type": "string" }, "description": "6.0.0-C — command routing metadata (skill/cluster-sub/command slugs the intent routes to)." },
         "replaces": { "type": "array", "items": { "type": "string" }, "description": "6.0.0-C — command routing metadata (prior names/aliases this command absorbs; may be empty)." },
         "slug": { "type": "string", "description": "6.0.0-D — canonical path-derived invocation slug (ADR-044; pack-stripped subpath + opt-in slug_prefix). Distinct from `name` (display, may still be colon for renames deferred to 6.1). The identity `commands ls --profile` matches on." },
-        "workspaces": { "type": "array", "items": { "$ref": "#/$defs/workspace_id" }, "minItems": 1 },
-        "packs": { "type": "array", "items": { "$ref": "#/$defs/pack_id" }, "minItems": 1 },
+        "workspaces": { "type": "array", "items": { "$ref": "#/$defs/workspace_id" }, "description": "Non-empty for skill/rule/command/template (enforced by build_discovery_manifest._classify). ADR-109 subagents legitimately carry [] — default-off, opt-in-by-name, never pack/workspace-scoped." },
+        "packs": { "type": "array", "items": { "$ref": "#/$defs/pack_id" }, "description": "Non-empty for skill/rule/command/template (enforced by build_discovery_manifest._classify). ADR-109 subagents legitimately carry [] — recommended for no pack; included only via include: [\"subagent:<name>\"]." },
         "requires": {
           "type": "array",
           "items": { "$ref": "#/$defs/pack_id" },
@@ -218,7 +218,8 @@
             "skill":    { "type": "integer", "minimum": 0 },
             "rule":     { "type": "integer", "minimum": 0 },
             "command":  { "type": "integer", "minimum": 0 },
-            "template": { "type": "integer", "minimum": 0 }
+            "template": { "type": "integer", "minimum": 0 },
+            "subagent": { "type": "integer", "minimum": 0 }
           },
           "required": ["skill", "rule", "command", "template"]
         },