@event4u/agent-config 2.14.0 → 2.16.0

package/docs/contracts/file-ownership-matrix.json

@@ -39,6 +39,42 @@
       "load_context": [],
       "load_context_eager": []
     },
+    ".agent-src.uncompressed/commands/agents/user.md": {
+      "kind": "command",
+      "rule_type": "orchestrator",
+      "load_context": [],
+      "load_context_eager": []
+    },
+    ".agent-src.uncompressed/commands/agents/user/accept.md": {
+      "kind": "command",
+      "rule_type": null,
+      "load_context": [],
+      "load_context_eager": []
+    },
+    ".agent-src.uncompressed/commands/agents/user/init.md": {
+      "kind": "command",
+      "rule_type": null,
+      "load_context": [],
+      "load_context_eager": []
+    },
+    ".agent-src.uncompressed/commands/agents/user/review.md": {
+      "kind": "command",
+      "rule_type": null,
+      "load_context": [],
+      "load_context_eager": []
+    },
+    ".agent-src.uncompressed/commands/agents/user/show.md": {
+      "kind": "command",
+      "rule_type": null,
+      "load_context": [],
+      "load_context_eager": []
+    },
+    ".agent-src.uncompressed/commands/agents/user/update.md": {
+      "kind": "command",
+      "rule_type": null,
+      "load_context": [],
+      "load_context_eager": []
+    },
     ".agent-src.uncompressed/commands/analyze-reference-repo.md": {
       "kind": "command",
       "rule_type": null,
@@ -2902,6 +2938,160 @@
       "via": "body_link",
       "depth": 1
     },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user.md",
+      "target": ".agent-src.uncompressed/commands/agents/init.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user.md",
+      "target": ".agent-src.uncompressed/commands/agents/user.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/accept.md",
+      "target": ".agent-src.uncompressed/commands/agents/user.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/accept.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/accept.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/accept.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/review.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/accept.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/update.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/init.md",
+      "target": ".agent-src.uncompressed/commands/agents/user.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/init.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/init.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/review.md",
+      "target": ".agent-src.uncompressed/commands/agents/user.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/review.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/accept.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/review.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/review.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/review.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/update.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/show.md",
+      "target": ".agent-src.uncompressed/commands/agents/user.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/show.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/init.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/show.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/show.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/show.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/update.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/update.md",
+      "target": ".agent-src.uncompressed/commands/agents/user.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/update.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/accept.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/update.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/init.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/update.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/review.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/update.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/show.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/user/update.md",
+      "target": ".agent-src.uncompressed/commands/agents/user/update.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
     {
       "source": ".agent-src.uncompressed/commands/analyze-reference-repo.md",
       "target": ".agent-src.uncompressed/commands/analyze-reference-repo.md",

package/docs/examples/agent-user.example.md

@@ -0,0 +1,21 @@
+---
+version: 1
+identity:
+  name: "Mathias"
+  nickname: "Matze"
+language: "de"
+role: "founder/engineer"
+style:
+  formality: "informal"
+  pace: "pragmatic"
+voice_sample: |
+  Mach das einfach. Wenn unklar, frag im Council. Tokenverbrauch ist ok,
+  aber stell mir keine Fragen — entscheide oder frag die AIs.
+last_updated: "2026-05-15"
+---
+
+# Notes
+
+Pragmatic shipper. Prefers terse replies, real diffs, and named
+trade-offs over hedged options. Council-first for anything that looks
+like a contract decision.

package/docs/getting-started.md

@@ -146,7 +146,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 109 active commands](../.agent-src/commands/)
+→ [Browse all 115 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/installation.md

@@ -235,6 +235,57 @@ The global install puts `agent-config` on `$PATH` so the project
 wrapper (`./agent-config`) can fall through to it when no
 `node_modules/@event4u/agent-config/` exists.
 
+### Global CLI + per-project settings (minimal flow)
+
+For teams that want to keep the runtime global (one install per
+machine) but still version a per-project `.agent-settings.yml` and a
+project-local `agents/` folder, use the `--minimal` init:
+
+```bash
+# 1. Install the runtime once per machine
+npm install -g @event4u/agent-config
+
+# 2. Inside the project, write only the per-project shell
+agent-config init --minimal
+# or, without a global install:
+npx @event4u/agent-config init --minimal
+```
+
+`--minimal` writes exactly three files into the project root:
+
+- `.agent-settings.yml` — per-project cost profile, member config,
+  feature flags. Committed.
+- `agents/.gitkeep` — placeholder so the directory is committed
+  before the first roadmap, decision, or council session lands.
+- `./agent-config` — bash wrapper that pins
+  `AGENT_CONFIG_PROJECT_ROOT` to the project root and forwards every
+  subcommand to the globally installed CLI. Committed.
+
+Nothing else — no `.augment/`, no `.claude/`, no `.cursor/`, no
+`AGENTS.md`. The shipped tool payload stays in the user's home (or
+the npx cache) and is shared across every project on the machine.
+
+#### Decision table — `--minimal` vs full `init`
+
+| Pick `--minimal` when | Pick full `init` when |
+|---|---|
+| Runtime is already installed globally (`npm i -g`). | First-time setup on a fresh machine. |
+| Team wants one source of truth for skills / rules / commands across every repo (shared via the global install). | Team wants per-repo skills / rules / commands committed alongside the code. |
+| `agents/` content (roadmaps, decisions) is the only per-project state worth committing. | `AGENTS.md`, `GEMINI.md`, or `.github/copilot-instructions.md` need project-specific overrides. |
+| The repo runs in CI and you do not want to vendor the full payload. | The repo cannot rely on a global install (air-gapped, sandboxed CI without npm). |
+| Migrating an existing project from the legacy `.git`-anchored install. | Starting a new project that has never seen `agent-config`. |
+
+Nested-install guard: `init --minimal` refuses to run when an
+ancestor already contains an anchor (`.git`, an `agents/` directory
+with a marker, or another `.agent-settings.yml`). This prevents
+shadow installs inside an existing project. Override with explicit
+`--target <dir>` if the nesting is intentional.
+
+`--minimal` does **not** pin `agent_config_version` — the project
+follows whichever version the global CLI was installed at. Pin
+explicitly by adding `agent_config_version: <semver>` to
+`.agent-settings.yml` when you want a reproducible runtime.
+
 ### Installer orchestrator (`scripts/install`)
 
 The orchestrator chains payload sync and bridge generation:
@@ -673,8 +724,176 @@ or sandbox testing:
 - `AGENT_CONFIG_NO_EVENTS_LOG=1` — disables every write to
   `agents/council-events.log` in-process. Quota counter and council
   output stay untouched.
-- `AGENT_CONFIG_LEGACY_ANCHOR=1` — opt back into the pre-step-7
-  legacy-anchor behaviour for `.agent-settings.yml` migration.
+- `AGENT_CONFIG_LEGACY_ANCHOR=1` — reverts project-root discovery to
+  the pre-step-7 `.git`-only walk. See [Migration — Step 7 anchor
+  discovery](#migration--step-7-anchor-discovery) below for the
+  precedence rules and when to use this.
+- `AGENT_CONFIG_PROJECT_ROOT=<abs-path>` — pins the resolved project
+  root, skipping the anchor walk entirely. Set automatically by the
+  `./agent-config` wrapper; set manually in CI when the working
+  directory is not a descendant of the project root.
+
+---
+
+## Migration — Step 7 anchor discovery
+
+Before Step 7, the CLI located the project root by walking up for a
+`.git` directory only. Step 7 widens the anchor set so non-git
+projects (sparse checkouts, monorepo sub-trees, `agent-config`-only
+worktrees) resolve correctly and so subdirectory invocations stop
+falling back to `cwd`.
+
+### Anchor precedence (D3 — cascade-conflict decision)
+
+Walk up from CWD. The first ancestor containing a **boundary
+anchor** wins:
+
+1. `.git` (file or directory).
+2. `agents/` directory containing **any** of `roadmaps/`,
+   `.ai-council.yml`, or `roadmaps-progress.md` — bare `agents/`
+   does **not** anchor (D1).
+
+If no boundary anchor exists in any ancestor, the **outermost**
+(closest-to-fs-root) `.agent-settings.yml` becomes the root. This
+preserves the layered-settings cascade — see
+[`agents/council-sessions/step-7-d3-cascade-conflict-decision.md`](../agents/council-sessions/step-7-d3-cascade-conflict-decision.md)
+for the rationale.
+
+When a single ancestor carries multiple anchors, the **diagnostic
+anchor name** reported by `agent-config doctor` follows the D3
+tie-break order (`.agent-settings.yml` > `agents/` > `.git`). The
+resolved path is identical either way.
+
+### Resolution precedence (which root wins)
+
+In order, first match wins (Step 8 adds the `--root` flag at the top):
+
+1. Global `--root <dir>` flag (Step 8) — escape hatch for monorepos.
+2. Explicit `--project <dir>` / `--target <dir>` on the CLI.
+3. `AGENT_CONFIG_PROJECT_ROOT=<abs-path>` env var.
+4. Anchor walk from CWD (rules above).
+5. Fallback to CWD.
+
+The `./agent-config` wrapper sets step 3 to its own directory, so
+subcommands invoked from a subdirectory still target the right root
+even after `os.chdir`.
+
+### Project-root override — `--root` (Step 8)
+
+The global `--root <dir>` flag pins discovery to a specific directory.
+It is parsed by the bash dispatcher **before** any subcommand and beats
+every other channel, including the wrapper-pinned env var:
+
+```bash
+# Run doctor against a sibling project from anywhere
+agent-config --root /work/projects/site-a doctor --context
+
+# Equivalent — long-form `=` syntax
+agent-config --root=/work/projects/site-a doctor --context
+```
+
+**Fail-loud validation.** Invalid paths exit with code `2` instead of
+silently falling back to CWD:
+
+```text
+❌  agent-config: --root points to a path that does not exist: /nope
+```
+
+The same validation applies to `--project` and
+`AGENT_CONFIG_PROJECT_ROOT` — every explicit override is checked.
+
+**Wrapper coupling.** When the project-local `./agent-config` wrapper
+runs, it pins `AGENT_CONFIG_PROJECT_ROOT` to its own directory. The
+`--root` flag explicitly overrides that pin (the wrapper logs a stderr
+hint when this happens), so monorepo sub-trees can target one another
+without unpinning the wrapper.
+
+### Monorepo semantics
+
+Monorepos with multiple `agent-config` consumers (e.g. one package per
+sub-tree) work out of the box because the anchor walk stops at the
+**nearest** boundary anchor (`agents/<markers>` or `.git`). From inside
+`packages/site-a/`, discovery resolves to `packages/site-a/`, not the
+monorepo root.
+
+When you need to invoke a sibling package's CLI from anywhere, use
+`--root`:
+
+```bash
+# From the monorepo root, target site-b
+agent-config --root packages/site-b validate
+
+# From inside site-a, run a sync against site-b
+agent-config --root ../site-b sync
+```
+
+`--root` is the recommended channel — explicit, fail-loud, and visible
+in `doctor --context` output. Setting `AGENT_CONFIG_PROJECT_ROOT`
+manually still works but is less discoverable.
+
+### Diagnostics — `doctor --trace-root` and `--context`
+
+Two read-only diagnostic flags surface how discovery resolved the
+project root:
+
+```bash
+# Show every ancestor probed + winning anchor
+agent-config doctor --trace-root
+
+# Show effective root, origin, install mode, settings layers, wrapper
+agent-config doctor --context
+```
+
+Sample `--trace-root` output:
+
+```text
+  📍  start: /work/projects/site-a/src
+  📍  origin: agents-dir
+  trace:
+    · [boundary] /work/projects/site-a/src  (no .git, no agents/)
+    ✅ [boundary] /work/projects/site-a → agents-dir  (agents/ has roadmaps/)
+  📍  resolved root: /work/projects/site-a (anchor: agents-dir)
+```
+
+Sample `--context` output:
+
+```text
+  📍  project_root: /work/projects/site-a  (origin: agents-dir)
+  📦  install_mode: full  (source: marker-file)
+  …
+```
+
+Both flags accept `--json` for machine-readable output. The
+`install_mode_source` is `marker-file` when
+`agents/.agent-state/install-mode.txt` exists (written by the
+installer since Step 8) and `heuristic` for back-compat installs.
+
+### When to set `AGENT_CONFIG_LEGACY_ANCHOR=1`
+
+Set this only as a temporary escape hatch — for example, when the
+new anchor set surfaces an unexpected ancestor in a CI pipeline that
+already passes the legacy walk. Behaviour:
+
+- Walk up for `.git` only (Step-6 behaviour).
+- `agents/` and `.agent-settings.yml` are ignored as anchors.
+- Cascade order is unchanged — layered `.agent-settings.yml` files
+  still merge.
+
+The kill-switch is scheduled for removal after one minor-version
+soak (D5). File an issue if you need it longer-term so the precedence
+table can absorb the missing case.
+
+### Verifying the resolved root
+
+```bash
+agent-config doctor --context
+```
+
+prints the resolved project root, origin (`root-flag` / `explicit` /
+`env` / anchor name / `cwd-fallback`), install mode, settings-layer
+chain, and wrapper state. Use this when a command appears to read the
+wrong `.agent-settings.yml`. Pair with `--trace-root` (above) when the
+**anchor walk itself** needs debugging.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.14.0",
+    "version": "2.16.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,