@event4u/agent-config 2.14.0 → 2.16.0

package/CHANGELOG.md

@@ -16,6 +16,101 @@ Entry-shape contract: [`docs/contracts/CHANGELOG-conventions.md`](docs/contracts
 
 ## [Unreleased]
 
+**Discovery polish — `--root` override, doctor diagnostics, install-mode marker (`step-8-discovery-polish`)** —
+follow-up to step-7 driven by AI Council review of PR #157. Adds an
+explicit escape hatch for monorepos, surfaces the resolution decision
+path, and replaces install-mode heuristics with an authoritative
+marker file. New surfaces:
+
+- **Global `--root <dir>` flag** — parsed by the bash dispatcher
+  before any subcommand and wins over every other channel (subcommand
+  `--project`, `AGENT_CONFIG_PROJECT_ROOT` env-pin, anchor walk).
+  Implemented as `AGENT_CONFIG_ROOT_OVERRIDE=1` +
+  `AGENT_CONFIG_PROJECT_ROOT` plus a new `ORIGIN_ROOT_FLAG` so doctor
+  can attribute the resolution. Wrapper-coupling warning emitted on
+  stderr when `--root` overrides a wrapper-pinned env-pin.
+- **Fail-loud root validation** — `--root`, `--project`, and
+  `AGENT_CONFIG_PROJECT_ROOT` all reject non-existent paths and
+  non-directories via `ProjectRootError` mapped to exit code `2`. No
+  silent CWD fallback when the operator explicitly named a path.
+- **`agent-config doctor --trace-root`** — read-only diagnostic that
+  prints every ancestor probed during root discovery, the winning
+  anchor, and the originating channel. `--json` for machine-readable
+  output. Short-circuits the drift report.
+- **`agent-config doctor --context`** — prints effective project
+  root, origin, install mode + source, settings-layer chain, wrapper
+  state, and env-pin/override flags. `--json` available.
+- **Install-mode marker file** — `agents/.agent-state/install-mode.txt`
+  written by `install.py` with `minimal\n` or `full\n`. Doctor uses
+  the marker authoritatively for new installs; back-compat heuristic
+  (`AGENTS.md` + copilot bridges) only fires when the marker is absent.
+- **Minimal-install upgrade hint** — `install.py` emits a stderr
+  hint after a `--minimal` install describing how to upgrade to a
+  full install when the user is ready.
+- **Test coverage** — `tests/test_root_override.py` (precedence,
+  fail-loud for each channel, end-to-end CLI exit-2 check),
+  `tests/test_doctor_trace.py` (text + JSON shape for both flags,
+  marker-vs-heuristic install-mode detection, origin propagation).
+  Twenty new tests, full suite green.
+
+Council artefacts:
+`agents/council-sessions/step-8-discovery-polish-decision.md` — 2
+rounds + peer-review, $0.12. Decision cut `template-gen` (A4) and
+`anchor-freeze AC` (A6), kept `--trace-root` and `--context` as two
+distinct flags (host override of Claude's consolidation proposal),
+and added the install-mode marker file as the hybrid resolution to
+Q5 (marker for new installs, filesystem heuristic for back-compat).
+
+**Agent-folder discovery + `--minimal` init (`step-7-agent-folder-discovery-and-minimal-init`)** —
+project-root discovery widens beyond `.git` so non-git checkouts,
+monorepo sub-trees, and `agent-config`-only worktrees resolve
+correctly, and a new minimal-init payload lets teams keep the
+runtime global while committing only the per-project shell. New
+surfaces:
+
+- **Boundary anchors (D1+D3)** — `.git` plus `agents/` containing
+  **any** of `roadmaps/`, `.ai-council.yml`, `roadmaps-progress.md`.
+  Bare `agents/` is **not** an anchor (false-positive guard). When
+  no boundary anchor exists in any ancestor, the **outermost**
+  `.agent-settings.yml` becomes the root so the layered-settings
+  cascade survives. Same-level tiebreaker:
+  `.agent-settings.yml` > `agents/` > `.git` (diagnostic anchor
+  name only — resolved path is identical).
+- **`resolve_project_root(arg)` helper** (`scripts/_lib/agent_settings.py`)
+  — single entry point used by every `cmd_*.py`. Precedence:
+  explicit `--project`/`--target` → `AGENT_CONFIG_PROJECT_ROOT` env
+  → anchor walk → CWD fallback. Returns `(root, origin)` so doctor
+  can surface which step resolved.
+- **`AGENT_CONFIG_PROJECT_ROOT` env pin** — the `./agent-config`
+  wrapper exports its own directory before forwarding to the master
+  CLI, so subcommands invoked from a subdirectory (or after
+  `os.chdir`) stay pinned to the right root without re-walking.
+- **`agent-config init --minimal`** — writes exactly three files:
+  `.agent-settings.yml`, `agents/.gitkeep`, and the `./agent-config`
+  wrapper. No `.augment/` / `.claude/` / `.cursor/` / `AGENTS.md`.
+  Refuses to run when an ancestor already carries an anchor
+  (nested-install guard); override with explicit `--target`.
+  Does **not** pin `agent_config_version` (D4) — consumer follows
+  the global CLI.
+- **`AGENT_CONFIG_LEGACY_ANCHOR=1` kill-switch (D5)** — reverts
+  discovery to the pre-step-7 `.git`-only walk for one minor-version
+  soak. Scheduled for removal after the soak window unless
+  telemetry surfaces a missing case.
+- **Performance budget (D6)** — anchor walk is `O(depth)` with at
+  most three `Path.exists()` calls per level. Test asserts
+  `< 5 ms` at depth 20 (`tests/test_anchor_perf.py`).
+- **Test coverage** — `tests/test_project_root_anchors.py`
+  (precedence, mixed-anchor edge case, bare `agents/` rejection),
+  `tests/test_kill_switch.py`, `tests/test_minimal_init.py`
+  (payload shape + nested-install refusal), `tests/test_subdir_invocation.py`
+  (env-var precedence, wrapper-pin surviving `chdir`),
+  `tests/test_anchor_perf.py`.
+
+Council artefacts: `agents/council-sessions/step-7-d3-cascade-conflict-{question,decision}.md`
+— D3 strict closest-leaf-wins was relaxed to boundary-vs-layer
+split after the analysis lens flagged four pre-existing cascade
+tests as the contract, not edge cases.
+
 **PR #150 follow-up hardening (`step-9-pr150-feedback-hardening`)** —
 twelve-phase response to the Claude+GPT review findings on PR #150 plus
 three user-requested settings-shape changes (CLI-default, preferred-single
@@ -600,238 +695,92 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
-# Era: 2.11.x — current
+# Era: 2.15.x — current
 
-> Started at `2.11.0` (2026-05-14). Full entries live inline below.
+> Started at `2.15.0` (2026-05-15). Full entries live inline below.
 > The drift test caps this era at 200 lines of entry body; growth past
-> that forces a new era split (`# Era: 2.12.x`, etc.) — see
+> that forces a new era split (`# Era: 2.16.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
-## [2.14.0](https://github.com/event4u-app/agent-config/compare/2.13.0...2.14.0) (2026-05-15)
+## [2.16.0](https://github.com/event4u-app/agent-config/compare/2.15.0...2.16.0) (2026-05-15)
 
 ### Features
 
-* **ai-council:** switch low-impact corpus runtime to YAML lockfile ([c8a4b9c](https://github.com/event4u-app/agent-config/commit/c8a4b9c318f3b0c04b6fcd974790ba2bc2623554))
-* **ai-council:** add corpus YAML compiler and lockfile ([50ffcb8](https://github.com/event4u-app/agent-config/commit/50ffcb809d633aeb760ea0865a90208be431de43))
-* **council:** wire confidence gate into solo dispatch + shadow log ([fcd19d7](https://github.com/event4u-app/agent-config/commit/fcd19d7bd6e12b2c198ec2f3771da5c8c562cd17))
-* **council:** add confidence_gate heuristics module ([acee171](https://github.com/event4u-app/agent-config/commit/acee17182770a7aa31574669b1f74b269ae34c27))
-* **council:** add solo_confidence_floor config knob + Iron Law lock ([2afef0b](https://github.com/event4u-app/agent-config/commit/2afef0b8d853298be6b73da57bb53415acac798d))
-* **audit:** --iron-law flag scans for validator bypasses (step-9 phase 11) ([2e0ef55](https://github.com/event4u-app/agent-config/commit/2e0ef55d625b60ef073b74e9a91a40478e6ff1e3))
-* **ai-council:** airgap detection + installer first-run hook (step-9 phase 11) ([d528d88](https://github.com/event4u-app/agent-config/commit/d528d8832fba6893f52bad587365019016f060aa))
-* **ai-council:** shadow-mode logger + shadow-report CLI (step-9 phase 10) ([052ed1f](https://github.com/event4u-app/agent-config/commit/052ed1f0355fb35277f80d1193cf912d3943753a))
-* **ai-council:** solo-member dispatch via routing fallback chain ([4cf5738](https://github.com/event4u-app/agent-config/commit/4cf5738c209e5fc6ce3c7681112d4f3b4bb89ce9))
-* **ai-council:** config schema for solo dispatch + Iron Law (step-9 phase 8) ([779f302](https://github.com/event4u-app/agent-config/commit/779f3025f3f78b1b275ce1ffb9364ae970d18424))
-* **low-impact:** preview builder for learn-low-impact (step-9 phase 7) ([234647c](https://github.com/event4u-app/agent-config/commit/234647c81336aa30aac648774e0d2fa0416e8dcf))
-* **low_impact:** emit normative fast-path markers per Iron-Law rule ([95b528b](https://github.com/event4u-app/agent-config/commit/95b528ba7dc1ec445c52cbe1844846612afd3d79))
-* **rules:** add fast-path-marker-visibility Iron-Law rule ([82d97c2](https://github.com/event4u-app/agent-config/commit/82d97c206a5b439d535f1cac7777be82ff51269d))
-* **council:** opt-in fuzzy corpus matching with safety vetoes (step-9 P5) ([903b9f1](https://github.com/event4u-app/agent-config/commit/903b9f1f244ee72f6e01ebdc4e8f3be51c76ef23))
-* **council:** harden low-impact corpus parser with typed errors (step-9 P4) ([6e56737](https://github.com/event4u-app/agent-config/commit/6e567375ef8c379ec1696d5f35c41804276f6bbf))
-* **doctor:** add council-cli health check (step-9 P3) ([fcb36f5](https://github.com/event4u-app/agent-config/commit/fcb36f584df423613d353c2119a13e842b52117d))
-* **council:** surface CLI install hints when binary missing (step-9 phase 2) ([2507eea](https://github.com/event4u-app/agent-config/commit/2507eea06d8739bfffe1a036b284f6459ee329e4))
-* **council:** persistent events log with privacy floor (step-8 phase 3) ([e2b30de](https://github.com/event4u-app/agent-config/commit/e2b30de6811b8affedf87c938f32d27d527222d0))
-* **council:** necessity tier split with warn-only default (step-8 phase 2) ([3837299](https://github.com/event4u-app/agent-config/commit/3837299194ae20e09ab076e55f824d596815f1d7))
-* **council:** add CLI quota observability (step-8 phase 1) ([c17d29b](https://github.com/event4u-app/agent-config/commit/c17d29b1ef4113f032ab492a6862aca624c45f48))
-* **council:** enforce canonical output paths at runtime ([9fa50c4](https://github.com/event4u-app/agent-config/commit/9fa50c4d6ea759dd38ff32dbb114163037979b75))
-* **ai-council:** Phase 12 — low-impact decisions corpus ([d82509b](https://github.com/event4u-app/agent-config/commit/d82509bcc91dc4de519a080e44f5aa296de34d5e))
-* **ai-council:** Phase 11 — replay engine + Lightweight-QA fast-path ([8fa5da8](https://github.com/event4u-app/agent-config/commit/8fa5da8b5de982b93c4608c38d95f64ad60c048b))
-* **ai-council:** Phase 10 — impact-based decision routing + cost disclosure ([5dbe837](https://github.com/event4u-app/agent-config/commit/5dbe83743e782351f5eea54a86071b4414208976))
-* **ai-council:** Phase 8-9 — necessity classifier with corpus consultation ([5adfe71](https://github.com/event4u-app/agent-config/commit/5adfe7190f0c379a07c1e51ebe634a7f439ec79b))
-* **ai-council:** Phase 5 — session-trail + negative-test backfill ([dd64874](https://github.com/event4u-app/agent-config/commit/dd648744a5cd3fc3b516851704d943d9625602de))
-* **ai-council:** wire XAI + Perplexity community CLI transports ([4df827c](https://github.com/event4u-app/agent-config/commit/4df827c80c9b6bf51ff41e4e56844c9263dab281))
-* **ai-council:** phase 3 — Codex + Gemini CLI clients wired ([16dd7fe](https://github.com/event4u-app/agent-config/commit/16dd7fe987b685c290d2be2f7594f514979db1fd))
-* **ai-council:** phase 2 — wire AnthropicCliClient end-to-end ([e965ab1](https://github.com/event4u-app/agent-config/commit/e965ab1cf67d5f18b64bafd7370d4ee7d70124af))
-* **ai-council:** phase 1 — CliClient + AnthropicCliClient + daily quota ([df0d88c](https://github.com/event4u-app/agent-config/commit/df0d88c686c02f1e45707787ae196ac7e8371ef6))
-* **ai-council:** phase 0 — extend schema for CLI transport ([cb45344](https://github.com/event4u-app/agent-config/commit/cb45344e6e686af430677a61c2026e972f1bfe45))
-* **readme:** add Personas and Advisors to hero badge ([f11b85e](https://github.com/event4u-app/agent-config/commit/f11b85ea82fd0f0a04b68d18444d4a8c73d86de1))
-
-### Bug Fixes
-
-* **council:** allowlist audit-* dirs in layout linter ([09d6900](https://github.com/event4u-app/agent-config/commit/09d69003204c2a86a2cc9f1193b8c33145d856b4))
-* **rules:** align validator_ignore reason between source and projection ([89b7fac](https://github.com/event4u-app/agent-config/commit/89b7facf48d2a4fe39558028bdf15ff40d98c59a))
-* **rules:** allowlist .agent-src.uncompressed/ back-pointer in fast-path-marker ([e74383b](https://github.com/event4u-app/agent-config/commit/e74383b62253ab990e938d1dfdc631d20db94181))
-* **ask-when-uncertain:** trim AI Council prose to clear 12% concentration cap ([59abb4a](https://github.com/event4u-app/agent-config/commit/59abb4a3f827b4f8ecb24b63568b057462ae7649))
-* **ai-council:** mark skill cloud-safe with degrade tier ([3c568e6](https://github.com/event4u-app/agent-config/commit/3c568e6eed6c50f8fee2c1685d25dc7aef9d82ec))
-* **low-impact-floor:** drop forbidden authoring-tree path from rule ([8962291](https://github.com/event4u-app/agent-config/commit/89622914c375d01629ed3795d37fd7adf7a07c60))
-* **ai-council:** restore Phase 11 sections in compressed SKILL.md ([52e4f14](https://github.com/event4u-app/agent-config/commit/52e4f14177acd90fd63b4c1c283b3dbda41a6437))
+* **install:** install-mode marker + minimal-init upgrade hint (Step 8 P3) ([e028468](https://github.com/event4u-app/agent-config/commit/e028468ed2b58428b99bea5a2e6c2a25e12fc113))
+* **cli:** doctor --trace-root + --context diagnostic surface (Step 8 P2) ([387a626](https://github.com/event4u-app/agent-config/commit/387a626b7795fc40e6e2442c1dde272dfc98f9d7))
+* **cli:** --root override flag + fail-loud root validation (Step 8 P1) ([0c8356e](https://github.com/event4u-app/agent-config/commit/0c8356e9034ca474827de89db5386a04c61f560c))
+* **wrapper:** export AGENT_CONFIG_PROJECT_ROOT pin so subdir invocations skip the walk ([e866cef](https://github.com/event4u-app/agent-config/commit/e866cef14d40269786fb0a88b69d9aafcfab1c88))
+* **agent-settings:** add resolve_project_root helper for Phase 3 subdir hardening ([95bac18](https://github.com/event4u-app/agent-config/commit/95bac187132d35d476716cd38d8c619bccaca6e5))
+* **install:** add --minimal / --settings-only init mode ([4c02743](https://github.com/event4u-app/agent-config/commit/4c02743cd7df6d89f7b7fa6188d654ca1eec983c))
+* **agent_settings:** extend find_project_root with agents/ + .agent-settings.yml anchors ([60dcd11](https://github.com/event4u-app/agent-config/commit/60dcd11c498f25f92bb01482943bfb95d4efef37))
 
 ### Documentation
 
-* add (beta) markers next to beta-stability contract links ([0eb55dc](https://github.com/event4u-app/agent-config/commit/0eb55dc1303eb06b52b7f1a88cb2a137a6cde8f9))
-* **reports:** command-surface inventory + AI Council synthesis ([38c3cc3](https://github.com/event4u-app/agent-config/commit/38c3cc39176cefb1c92431c0485659fa442002cf))
-* **council:** document confidence-gate auto-escalation ([4202dac](https://github.com/event4u-app/agent-config/commit/4202dace49401598bb8b7e3033768c99333d1659))
-* **roadmap:** mark step-9 complete and archive ([1c0ca06](https://github.com/event4u-app/agent-config/commit/1c0ca06495f718cda5d1f7065b2d7b07dd4e63f8))
-* **contracts:** declare stability=beta for low-impact-corpus-format ([2114086](https://github.com/event4u-app/agent-config/commit/21140864621b8c1eb9bdb38a0d6b5146e562915a))
-* CHANGELOG + roadmap step-9 phases 10-12 complete ([9f1a220](https://github.com/event4u-app/agent-config/commit/9f1a220f7b44bb96788898f2662782e0d6b4ec99))
-* **roadmap:** mark step-9 Phase 9 complete + regen dashboard ([ae29fbf](https://github.com/event4u-app/agent-config/commit/ae29fbfe32eaf77d847bc00fcee76210e5f17848))
-* **ai-council:** document solo dispatch + Iron Law contract (step-9 phase 8) ([ed12ca9](https://github.com/event4u-app/agent-config/commit/ed12ca9dabc585b0962f82d740a682206caeb2df))
-* **low-impact:** switch /memory learn-low-impact default to --preview (step-9 phase 7) ([493ef5d](https://github.com/event4u-app/agent-config/commit/493ef5d91024761ee2b7a845b992257b76e71671))
-* **roadmap:** mark step-9 phases 0/1/5 complete + regen dashboard ([5f55bad](https://github.com/event4u-app/agent-config/commit/5f55bad0495532431b2451130a2397c144374b58))
-* **roadmap:** mark step-9 phase 4 complete (corpus parser hardening) ([5b35aaa](https://github.com/event4u-app/agent-config/commit/5b35aaa3ab27dd348ef161c4a78321f886775b6a))
-* **roadmap:** mark step-9 phase 2 complete (CLI install hints) ([11ae2ee](https://github.com/event4u-app/agent-config/commit/11ae2ee97753abf6f1e2a18583b5efd84924f208))
-* **council:** document low-impact council opt-in (step-9 phase 1) ([c0fd395](https://github.com/event4u-app/agent-config/commit/c0fd395423693f525fe628a744e6b324a87cf589))
-* **roadmap:** mark step-8 complete and archive ([e7d328d](https://github.com/event4u-app/agent-config/commit/e7d328d7f85acb1df5ce01c559e2809640ee2096))
-* **council:** document quota/necessity transparency surface (step-8 phase 4) ([ba72154](https://github.com/event4u-app/agent-config/commit/ba72154f02bcb791e2864f8ee7818a946710d630))
-* **roadmap:** add step-9 pr-150 feedback hardening + regen progress dashboard ([bf89e80](https://github.com/event4u-app/agent-config/commit/bf89e80e3e238a449daab1399942b6866de920a6))
-* **roadmap:** add step-8 quota necessity transparency ([8aa2385](https://github.com/event4u-app/agent-config/commit/8aa23857583a7e434e9bca1372ef18436f9933e5))
-* **roadmap:** add step-7 agent-folder discovery + minimal init ([a13c963](https://github.com/event4u-app/agent-config/commit/a13c96335bc8244eeeee9bb3dfb1e30aa292e179))
-* **roadmap:** add step-2 feedback follow-up roadmap ([b9f34d3](https://github.com/event4u-app/agent-config/commit/b9f34d39d94d28d6e2d9eba2748995d579b36373))
-* **roadmap:** expand step-1 with safety net, impact routing, and low-impact corpus ([3925a74](https://github.com/event4u-app/agent-config/commit/3925a74b5cdba6d9c6b92fbaf1c0cf6e05fb1cd3))
+* **changelog:** Step 8 discovery polish entry under Unreleased ([eecaf6a](https://github.com/event4u-app/agent-config/commit/eecaf6a9a2248a877d71dbd33e7db096f94dab3b))
+* **installation:** root override + monorepo semantics + diagnostics (Step 8) ([de3081f](https://github.com/event4u-app/agent-config/commit/de3081fe828cb43c628d922c50d25177d43f267e))
+* **roadmap:** archive step-7 (all phases complete) + sync dashboard ([8f2953e](https://github.com/event4u-app/agent-config/commit/8f2953ee5c867ada29c9f32cf45bd2380504bc12))
+* **step-7:** add minimal-init flow, anchor migration guide, changelog entry ([9ace019](https://github.com/event4u-app/agent-config/commit/9ace01945967e67e98e8855a940801db09de8d17))
+* **roadmap:** mark Step 7 Phase 3 complete (subdir invocation hardening) ([518f9dc](https://github.com/event4u-app/agent-config/commit/518f9dcaf6d71a34cf1700bceb1487f1e8e33175))
+* **roadmap:** mark Step 7 Phase 2 + test items complete ([1bb9b71](https://github.com/event4u-app/agent-config/commit/1bb9b712d866dd509124f7d8502f52957e972b20))
+* **roadmap:** mark Step 7 Phase 1 complete; refresh progress dashboard ([2ba8d5b](https://github.com/event4u-app/agent-config/commit/2ba8d5be1b94bbab87da4270d833697c895cc9c6))
 
 ### Refactoring
 
-* **commands:** nest learn-low-impact under memory cluster ([473dc97](https://github.com/event4u-app/agent-config/commit/473dc9776cd3dfb55f66e06977c1abaf02afcc01))
+* **cli:** route all cmd_*.py entry points through resolve_project_root ([aa7a01a](https://github.com/event4u-app/agent-config/commit/aa7a01a7f27205919193d54339298c0dbd30c43e))
 
 ### Tests
 
-* **install:** sandbox HOME for --global guard test ([189baef](https://github.com/event4u-app/agent-config/commit/189baefe91d72392753ca144ae290a23e253a266))
-* **ai-council:** Iron-Law sentinel for locked dispatch (step-9 phase 11) ([c5b617a](https://github.com/event4u-app/agent-config/commit/c5b617aeae79431ba4071a436f12a7ca35dd144b))
-* **council:** cover step-8 quota + necessity-tier surface (phase 5) ([be4eba3](https://github.com/event4u-app/agent-config/commit/be4eba3dba54c5f6926924e80dd56ff312a4124a))
-
-### Build
-
-* **ai-council:** wire compile-corpus into consistency + sync ([5a35b90](https://github.com/event4u-app/agent-config/commit/5a35b9037ee161f24224b71b2431e1c6bdbe6f86))
+* **cli:** coverage for --root override + doctor trace/context (Step 8) ([9b943aa](https://github.com/event4u-app/agent-config/commit/9b943aa9f002750499738fd36f8a203525fb84da))
+* **subdir:** cover resolve_project_root precedence + wrapper-pinned root ([0693714](https://github.com/event4u-app/agent-config/commit/06937145ac8f4e1160ec9279d3832e4f5397bb1e))
+* **install:** cover --minimal payload + nested-install guard ([5623521](https://github.com/event4u-app/agent-config/commit/56235218624792b487a92f444ff8ee114a5651a3))
+* **agent_settings:** cover anchor extension, kill-switch, perf budget ([37a080c](https://github.com/event4u-app/agent-config/commit/37a080c07ee9238fda45bbda1829764a4232f062))
 
 ### Chores
 
-* **roadmap:** close out + archive step-2-feedback-followup ([fc347d2](https://github.com/event4u-app/agent-config/commit/fc347d28d93b1237300bbc3b31b1877a147857ca))
-* **roadmap:** mark step-2-feedback-followup phases 1-3 complete ([6f8c456](https://github.com/event4u-app/agent-config/commit/6f8c4567993067b039ca9aebf680aaf76bd5e69c))
-* **scripts:** add command-surface audit tool ([e118870](https://github.com/event4u-app/agent-config/commit/e11887001cf0e5bd68ee46164bb8d27a7f9a7a32))
-* **roadmaps:** archive step-10 (corpus YAML lockfile complete) ([1d5ecfa](https://github.com/event4u-app/agent-config/commit/1d5ecfa07f63103456d4647a121a83e662a2d686))
-* **index:** regenerate after auto-rule description trims ([fb39853](https://github.com/event4u-app/agent-config/commit/fb398539a22b82c530ec9cc39adb4343475edf6b))
-* **rules:** trim auto-rule descriptions to fit 150-char Augment cap ([7755665](https://github.com/event4u-app/agent-config/commit/77556655e9db859a3c8bb3ca90931724bb144b9f))
-* **ownership:** regenerate ownership matrix ([3661223](https://github.com/event4u-app/agent-config/commit/3661223dea90d842239a947c8d605ac22257cfc1))
-* **lint:** suppress pre-existing council references with allowed pragma ([3770fb7](https://github.com/event4u-app/agent-config/commit/3770fb76f661a7042fd014ce18537babf6d6a127))
-* **roadmaps:** tag step-7 and step-9 as structural ([99e8801](https://github.com/event4u-app/agent-config/commit/99e88019d2f8352e3c61932433a159c3e9b1136c))
-* **index:** regenerate agents/index.md + docs/catalog.md ([e3adea4](https://github.com/event4u-app/agent-config/commit/e3adea43c1a8a4bf184f4476ef0a158e48a4c7ce))
-* **lint:** clear pre-existing check-no-roadmap-refs violations (step-9 phase 0) ([41284d4](https://github.com/event4u-app/agent-config/commit/41284d4f990d3beb0efbe31dc8b9782a57a528b5))
-* **changelog:** split off pre-2.11.0 era into archive ([913da95](https://github.com/event4u-app/agent-config/commit/913da950c07ab8221e8fc7b96b28fde3ae6aa83f))
-* **roadmap:** archive step-1-ai-council-cli-transport (100% complete) ([2a9eaa5](https://github.com/event4u-app/agent-config/commit/2a9eaa558178349819609cf73f33300dcc3b846f))
-* **index:** regenerate after learn-low-impact cluster move ([6d38afb](https://github.com/event4u-app/agent-config/commit/6d38afbca4ff8b2f75ea6d3669f9a15a1a49b2f4))
-* **counts:** bump documented command count 108 to 109 ([6ada77d](https://github.com/event4u-app/agent-config/commit/6ada77d42b367909c68381f5c1bd9480960dd85f))
-* **index:** regenerate after low-impact-corpus + learn-low-impact ([e256dd0](https://github.com/event4u-app/agent-config/commit/e256dd0d56492fbe390ab60b7902a99d1b509d50))
-* **roadmap:** mark Phase 8-12 complete + regenerate dashboards ([8f14a9c](https://github.com/event4u-app/agent-config/commit/8f14a9c8e5ba16348c45f8ac9cfbeb1f053b26bd))
-* **contracts:** pull keep-beta-until back inside 90-day window ([8b4c8c9](https://github.com/event4u-app/agent-config/commit/8b4c8c9de4fab092e8bc4c7580b2b435de85e973))
-* **docs:** clear pre-existing check-public-links failures ([822c40e](https://github.com/event4u-app/agent-config/commit/822c40e9f90d81ffdcdb1a3fa590dc0d0e89c9f5))
-* **roadmap:** stub agents/low-impact-decisions.md for Phase 12 forward-ref ([3af26f6](https://github.com/event4u-app/agent-config/commit/3af26f67f3ad86afc5a964a75ac3173526772b95))
-* **templates:** bump agent_config_version to 2.13.0 ([1e5ddcd](https://github.com/event4u-app/agent-config/commit/1e5ddcd6d6aeed485253e8476c002262a3e95962))
-* **roadmap:** regenerate roadmaps progress dashboard ([3a33c7e](https://github.com/event4u-app/agent-config/commit/3a33c7eda801c25aacb13ec2e58680f9f856cc91))
-
-Tests: 4340 (+472 since 2.13.0)
-
-## [2.13.0](https://github.com/event4u-app/agent-config/compare/2.12.0...2.13.0) (2026-05-14)
-
-### Features
-
-* **council:** Phase 7 — debate orchestration + CLI wiring ([647a3f0](https://github.com/event4u-app/agent-config/commit/647a3f07698792f41beb7413600d54b2321f4a96))
-* **council:** Phase 7 — /council debate sub-command files ([abbd436](https://github.com/event4u-app/agent-config/commit/abbd43666b7e2c704ab3c46f2901f01eae446139))
-* **council:** Phase 6 — thinking-style advisor personas ([21c8b88](https://github.com/event4u-app/agent-config/commit/21c8b88310a2a65d7ea9082da085d023f813d114))
-* **council:** Phase 5 — Karpathy peer-review opt-in flag ([bce381a](https://github.com/event4u-app/agent-config/commit/bce381ae9c412abf501473fa4154f91d9c0befbf))
-* **council:** analysis lens + lens-adaptive synthesis + consensus scoring ([6d7136a](https://github.com/event4u-app/agent-config/commit/6d7136ad6be31b7627a332600a7623f2cd929e76))
-* **council:** add config loader, overlay, and 3 new provider clients ([0cb5591](https://github.com/event4u-app/agent-config/commit/0cb55914457a62b6f57744d8c8dac16bf777921d))
-* **council:** introduce agents/.ai-council.yml as single source of truth ([043c2d2](https://github.com/event4u-app/agent-config/commit/043c2d23445f2ef7ad8aee880dc83d97c347635f))
-* **governance:** Phase 5 — roadmap trajectory metric + architectural-consensus ADR ([926a632](https://github.com/event4u-app/agent-config/commit/926a63237c3dbe1fcfd7df05c9230809382d8790))
-* **projection:** Phase 4 + 1.4 — multi-tool projection fidelity contract + ci-strict gate ([e18e4ad](https://github.com/event4u-app/agent-config/commit/e18e4ad73595e17889009b0123ebd000254c165b))
-* **routing:** Phase 3 — tighten skill descriptions + 4 tier-3 routing rules for failing clusters ([2a11c70](https://github.com/event4u-app/agent-config/commit/2a11c70b274741e7d98fd814ac39c1d05a1a38c9))
-* **governance:** Phase 1 — credibility (CONTRIBUTING preface, source-projection rename, archive 7 migration scripts) ([2e5cfe0](https://github.com/event4u-app/agent-config/commit/2e5cfe02e1b5f4218d1283108796b0ce43fd9165))
-
-### Bug Fixes
-
-* **docs:** drop transient council-sessions citation from multi-tool-projection ([55dbbb1](https://github.com/event4u-app/agent-config/commit/55dbbb1e599aae2d913dc56a05c9dab0014e2739))
-* **linter:** treat ../docs/contracts/ links as out-of-scope like guidelines ([a2249b0](https://github.com/event4u-app/agent-config/commit/a2249b02b70233e2b13ccf3efeda4188686b6181))
-* **routing:** strip transient roadmap citation from tier-3 routing rules ([2cf745c](https://github.com/event4u-app/agent-config/commit/2cf745cad9beb40c4e6e9eb7f97abbc58a94d9de))
-
-### Documentation
-
-* **roadmap:** rename "rule" to "invariant" for deep_min_rounds reference ([758ea46](https://github.com/event4u-app/agent-config/commit/758ea46568c23ef5518ff61d80700f7559bc54a1))
-* **ai-council:** sync compressed SKILL.md with Phase 6 advisors section ([6d57034](https://github.com/event4u-app/agent-config/commit/6d57034c7b342abdd5d38ff300fa67c51deb3471))
-* **council:** document master/wrapper contract for the council cluster ([7346f34](https://github.com/event4u-app/agent-config/commit/7346f34376b48c02ced3ae939dfff6ea215025ba))
-
-### Tests
-
-* **ai-council:** Phase 8 — negative-test backfill for config loader ([cc3a08c](https://github.com/event4u-app/agent-config/commit/cc3a08c360c94685f9a1efaaa57f84001f78788c))
-
-### Chores
+* **template:** bump agent_config_version pin to 2.15.0 ([093367d](https://github.com/event4u-app/agent-config/commit/093367d3e417a11a28295f2efa574e8c3fef6524))
+* **sync:** propagate Step 8 agent_settings.py to .agent-src/ projection ([7ce92e5](https://github.com/event4u-app/agent-config/commit/7ce92e514a8edbd970a4118b91d2f651bf730070))
+* **roadmap:** archive Step 8 discovery polish ([1c21982](https://github.com/event4u-app/agent-config/commit/1c219825dc413cfe45aefc3b12c08d2720583880))
+* **changelog:** split era 2.11.x → pre-2.15.0 ([c79363c](https://github.com/event4u-app/agent-config/commit/c79363c05d775ecfa95ab6fff5b3bbe706f797c9))
 
-* **roadmaps:** archive step-2-ai-council-consolidation — all phases + ACs done ([c7f0c9c](https://github.com/event4u-app/agent-config/commit/c7f0c9ca7ac300023c5da0b939e0c63554dbcfed))
-* **docs:** bump getting-started command count 106 -> 108 after council debate sub-command ([5e256d7](https://github.com/event4u-app/agent-config/commit/5e256d79d3eea3046900e8afa5be64526b4fc61d))
-* **roadmaps:** retag complexity from "medium" to lint-valid values ([4c5457e](https://github.com/event4u-app/agent-config/commit/4c5457e271f8dcdc03943bac7adff84455388615))
-* regenerate index + catalog for council-debate skill ([3c365a3](https://github.com/event4u-app/agent-config/commit/3c365a375da22f16f97829677c875500e40d436a))
-* **roadmap:** mark Phases 6-7 of step-2-ai-council-consolidation complete ([7e8e557](https://github.com/event4u-app/agent-config/commit/7e8e557505bbf88b486605980a7f5ee2f97bcbb4))
-* **roadmap:** mark Phases 1-4 of step-2-ai-council-consolidation complete ([101a5cf](https://github.com/event4u-app/agent-config/commit/101a5cf70d4fc694f85a270b2bebfb8fe545833a))
-* **roadmap:** mark Phase 0 of step-2-ai-council-consolidation complete ([4fa2734](https://github.com/event4u-app/agent-config/commit/4fa27346c8faad54de582757ce5cfe7216041bda))
-* **template:** bump agent_config_version pin to 2.12.0 ([e5c41fd](https://github.com/event4u-app/agent-config/commit/e5c41fd433105359d6e36b03b0de62415be212f0))
-* regenerate agents/index.md + docs/catalog.md after rule additions ([b7fa4b6](https://github.com/event4u-app/agent-config/commit/b7fa4b6e25cbc55d8b3197f815c00530bd1eee79))
-* **roadmap:** archive completed step-1-v2-feedback-followup (20/20 done) ([88a07ea](https://github.com/event4u-app/agent-config/commit/88a07ea9a983f0b63710e5461c8fddee36b2d378))
+Tests: 4405 (+53 since 2.15.0)
 
-Tests: 3868 (+150 since 2.12.0)
-
-## [2.12.0](https://github.com/event4u-app/agent-config/compare/2.11.0...2.12.0) (2026-05-14)
+## [2.15.0](https://github.com/event4u-app/agent-config/compare/2.14.0...2.15.0) (2026-05-15)
 
 ### Features
 
-* **linter:** evals.json schema validator + meta_skill exemption ([9568510](https://github.com/event4u-app/agent-config/commit/95685109540c7f2dc2643ec24ba9d996467e0645))
-* **skill-writing:** § 7 quantitative eval loop + run_skill_evals.py ([9eda402](https://github.com/event4u-app/agent-config/commit/9eda402dc43b8e14682787fb1cbbc9872eb16fcc))
-* **skills:** add doc-coauthoring from Anthropic ([161b904](https://github.com/event4u-app/agent-config/commit/161b9044743753f2e54bcae45c36a29daaa8058d))
-* **skills:** add canvas-design from Anthropic ([95c247c](https://github.com/event4u-app/agent-config/commit/95c247c08d3c6710c53bfcd7ba7a00f270e0d8d4))
-* **check-refs:** add file/line opt-out markers ([f381bcb](https://github.com/event4u-app/agent-config/commit/f381bcb5a08818e042af35836dd2c4d8965aa98e))
-* make ai-council max_output_tokens configurable ([5976b46](https://github.com/event4u-app/agent-config/commit/5976b4623b94277f6ba49b0e82bb36ab7d5adb50))
+* **agent-user:** add /agents user command cluster (init, show, review, accept, update) ([15d53d8](https://github.com/event4u-app/agent-config/commit/15d53d8d9a2365b044831cd42127e247a70d7e20))
+* **agent-user:** add v1 schema contract for .agent-user.md persona file ([64f4eab](https://github.com/event4u-app/agent-config/commit/64f4eab62ccf6a2606fbca0c56d398372c05a7a0))
 
 ### Bug Fixes
 
-* **marketplace:** register canvas-design + doc-coauthoring ([9fbfe6a](https://github.com/event4u-app/agent-config/commit/9fbfe6af83589bf45b27b72c1b818be9772ae60c))
+* **agent-user:** inline council-reference summary per no-roadmap-references ([ee4d3ce](https://github.com/event4u-app/agent-config/commit/ee4d3cedf9f4429450d21ca5badc2ae5c2ecaaed))
+* **agent-user:** drop roadmap references per no-roadmap-references rule ([c8ade8d](https://github.com/event4u-app/agent-config/commit/c8ade8d7c5b495e0e4295aa0cb801e59076ee0b0))
+* **agent-user:** adjust keep-beta-until to fit 90-day window ([801b365](https://github.com/event4u-app/agent-config/commit/801b365117a2d1efb4505e504bdd730e4cbbc217))
 
 ### Documentation
 
-* **audit:** mark forward-refs in north-star bundle as opt-out ([a1d7c21](https://github.com/event4u-app/agent-config/commit/a1d7c21df3d05c27bacf81344893c4e43ae72a06))
-* **roadmap:** expand step-99 with Total Dominance mandate ([c46cffd](https://github.com/event4u-app/agent-config/commit/c46cffd54214a61230be27ddaae3367053be39a5))
-* **roadmap:** add step-99 north-star restructure (meta · out-of-band) ([8dd18f9](https://github.com/event4u-app/agent-config/commit/8dd18f963742d14dd9d006237ddd93881b198a60))
-* **audit:** correct step-3 filename reference ([ee6bd7f](https://github.com/event4u-app/agent-config/commit/ee6bd7ffc6c6cd363b6207b6ff32aa72f2bc317e))
-* **audit:** add 2026-05-14 north-star audit + council synthesis ([589c2fb](https://github.com/event4u-app/agent-config/commit/589c2fbd3e35b57529ab0f934665d71d611012d4))
-* add roadmaps for council, persona, ghostwriter, user-types axis ([471fae3](https://github.com/event4u-app/agent-config/commit/471fae3a46182d930fea21adb4037a41ec99dcb3))
-* add v2 feedback follow-up roadmap ([23d17cb](https://github.com/event4u-app/agent-config/commit/23d17cb24b33e794f7c1e31e76055cc5c8f1ab6c))
+* **persona:** README section + agent-settings legacy-fallback note ([4da7629](https://github.com/event4u-app/agent-config/commit/4da7629f1f0b5a35a64d0a861040ad8639a66ebe))
+* **roadmap:** mark step-3-agent-user-persona phases as in-progress ([f29d3bc](https://github.com/event4u-app/agent-config/commit/f29d3bce2380c0ea9c67e6094540b88d920ed9ff))
 
 ### Chores
 
-* prefix roadmaps with step-N execution sequence ([de87232](https://github.com/event4u-app/agent-config/commit/de87232213404ad104e07c5ca831d64f4a607f8e))
-
-Tests: 3718 (+0 since 2.11.0)
-
-## [2.11.0](https://github.com/event4u-app/agent-config/compare/2.10.0...2.11.0) (2026-05-14)
-
-### Features
-
-* **stability:** add beta-review marker protocol and CI gate (P5.4) ([9b6cdfe](https://github.com/event4u-app/agent-config/commit/9b6cdfe9f9167e3e80551dfa2a88f80fff85646a))
-* **lint:** add 'type: orchestrator' frontmatter tag for cluster routers (P5.3) ([e6385bb](https://github.com/event4u-app/agent-config/commit/e6385bbaf022dc3763f55c2dd54fe85046c59fd4))
-* **skills:** add nextjs-patterns and symfony-workflow workflow skills (P4) ([038522b](https://github.com/event4u-app/agent-config/commit/038522b7ad2bd2ba1d8d8c4f9a61692694b7ebc8))
-* **onboard:** add Quickstart pointer step and surface balanced default (P3.3) ([5879b4c](https://github.com/event4u-app/agent-config/commit/5879b4cc66fc9f49fa42c99e72794e4c60f43739))
-* **install:** default cost_profile to balanced (P3.2) ([75caac2](https://github.com/event4u-app/agent-config/commit/75caac20fa2986222b5bd45a7cb63f07f9c4179f))
-* **work-engine:** wire decision_gate hook into runner ([c41a89d](https://github.com/event4u-app/agent-config/commit/c41a89d38c7eb4892358b5c931abbe9a5889038c))
-* **work-engine:** add decision_engine schema and gate evaluator ([fd1e8e2](https://github.com/event4u-app/agent-config/commit/fd1e8e2bb2e45e2288727ccd4a3bda4f809c6151))
-* **release:** release-trunk-sync contract and CI gate (P1.2, P1.3) ([a3e0d12](https://github.com/event4u-app/agent-config/commit/a3e0d12c156c367c995e84c7c0bb5d6a21ff6325))
-
-### Bug Fixes
+* **roadmap:** close out + archive step-3-agent-user-persona ([09c0229](https://github.com/event4u-app/agent-config/commit/09c0229efd67af9cad7b2ca8202f4caa351d028d))
+* **ownership:** regenerate file-ownership-matrix for /agents user ([128890d](https://github.com/event4u-app/agent-config/commit/128890d880584704b4842a398555dd979ae54462))
+* **docs:** bump command count from 109 to 115 ([f8c61b1](https://github.com/event4u-app/agent-config/commit/f8c61b1d0ec48034e0d66e8d32534056ca4aa1f0))
+* **template:** bump agent_config_version pin to 2.14.0 ([fcb885f](https://github.com/event4u-app/agent-config/commit/fcb885fd19bdbca46ef91ec4d5e723cc6c186c6d))
+* **index:** regenerate agents/index.md + docs/catalog.md for /agents user ([56b281d](https://github.com/event4u-app/agent-config/commit/56b281d69960d3e57adbd24b9ec6fd24fc1a5aff))
+* **agent-user:** regenerate compressed sources + claude tool stubs ([f79b6d1](https://github.com/event4u-app/agent-config/commit/f79b6d1cfcf1caccde4a723ad779c65d9ed87198))
 
-* **readme:** rename 'For contributors' to 'Development' for linter ([7957274](https://github.com/event4u-app/agent-config/commit/7957274c65895d80fa4801f95df876979362ee86))
-
-### Documentation
+Tests: 4352 (+12 since 2.14.0)
 
-* **roadmap:** close + archive road-to-productization (Level-6) ([7ee50e8](https://github.com/event4u-app/agent-config/commit/7ee50e8b16f1ce7d4461f1466d9a6e46f4138101))
-* **roadmap:** mark P3.1-P3.3 + P3.1a done in road-to-productization ([b0ff24f](https://github.com/event4u-app/agent-config/commit/b0ff24f23cb38d4ac556106c9ed060f104f83c8c))
-* **readme:** add 3-step Quickstart and move contributor detail below the fold (P3.1) ([b98152e](https://github.com/event4u-app/agent-config/commit/b98152eb86607d6b34f63ea9ad4c152951de58a6))
-* **roadmap:** mark P2.1-P2.3 done in road-to-productization ([189c780](https://github.com/event4u-app/agent-config/commit/189c780faef19cfbd9bceb3ad51ec42cb8cb05b7))
+# Era: pre-2.15.0 — archived
 
-### CI
-
-* **install:** add structural Quickstart smoke test (P3.1a) ([228445b](https://github.com/event4u-app/agent-config/commit/228445b97eefb20118bbea2872640c54225a1355))
-* **work-engine:** validate decision_engine block in agent-settings ([1a1f428](https://github.com/event4u-app/agent-config/commit/1a1f428bec4832f8ffb222a8b450719ba6409605))
-
-### Chores
-
-* **generate-tools:** expose nextjs-patterns + symfony-workflow skills ([3422ac7](https://github.com/event4u-app/agent-config/commit/3422ac7e3f273497a0cbb176b2580a0cf1256522))
-* **sync:** align orchestrator frontmatter + hash registry ([0e9ba2d](https://github.com/event4u-app/agent-config/commit/0e9ba2d50463ca99baf86651ea67ed82ca63d7f6))
-* **gitignore:** ignore python coverage artifacts ([e1a3289](https://github.com/event4u-app/agent-config/commit/e1a328921f08fad03325adc256b63a544582efb7))
-
-Tests: 3718 (+55 since 2.10.0)
+> All entries from `2.14.0` through `2.11.0` live in
+> [`docs/archive/CHANGELOG-pre-2.15.0.md`](docs/archive/CHANGELOG-pre-2.15.0.md).
+> The archive is read-only; git tags `2.14.0` and prior remain the
+> canonical source for what shipped. Splitting these out of the main
+> file keeps the active era under the 200-line drift cap enforced by
+> `tests/test_changelog_eras.py`.
 
 # Era: pre-2.11.0 — archived
 

package/README.md

@@ -7,7 +7,7 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>210 Skills</strong> · <strong>67 Rules</strong> · <strong>109 Commands</strong> · <strong>72 Guidelines</strong> · <strong>22 Personas</strong> · <strong>5 Advisors</strong> · <strong>8 AI Tools</strong>
+  <strong>210 Skills</strong> · <strong>67 Rules</strong> · <strong>115 Commands</strong> · <strong>72 Guidelines</strong> · <strong>22 Personas</strong> · <strong>5 Advisors</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -102,6 +102,17 @@ The init writes:
 - per-tool glue: `.claude/`, `.cursor/`, `.clinerules/`,
   `.windsurfrules`, `GEMINI.md`, `.github/copilot-instructions.md`
 
+Want to keep the runtime global and commit only the per-project
+shell (`.agent-settings.yml`, `agents/`, `./agent-config` wrapper —
+no `.augment/` / `.claude/` / `.cursor/` in the repo)?
+
+```bash
+npm install -g @event4u/agent-config && agent-config init --minimal
+```
+
+See [`docs/installation.md § Global CLI + per-project settings`](docs/installation.md#global-cli--per-project-settings-minimal-flow)
+for the decision table and migration notes.
+
 → Migrating from a pre-vX.0 install? See
 [`docs/migration/v1-to-v2.md`](docs/migration/v1-to-v2.md). The one-shot
 `npx @event4u/agent-config migrate` removes the legacy
@@ -524,7 +535,7 @@ kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-member
 | [`/jira-ticket`](.agent-src/commands/jira-ticket.md) | Read ticket from branch, implement feature |
 | [`/compress`](.agent-src/commands/compress.md) | Compress skills for token efficiency |
 
-→ [Browse all 109 active commands](.agent-src/commands/)
+→ [Browse all 115 active commands](.agent-src/commands/)
 
 ---
 
@@ -556,7 +567,7 @@ slash-commands) &nbsp; 📌 = informational marker only (no auto-discovery
 or manual wiring required)
 
 > **What this means in practice:** Claude Code gets the full project-scoped
-> package (rules + 210 skills + 109 native commands); Augment Code gets the
+> package (rules + 210 skills + 115 native commands); Augment Code gets the
 > same content but only from a single global install at `~/.augment/`.
 > Cursor, Cline, Windsurf, Gemini CLI, GitHub Copilot, Roo Code, Codex CLI,
 > and Continue.dev only get the **rules** natively; skills and commands are
@@ -605,6 +616,21 @@ for the per-rule routing.
 
 ---
 
+## User persona (`.agent-user.md`)
+
+A project-root `.agent-user.md` file captures who the user is — name,
+primary language, role, work style, and a single voice sample — so the
+agent can address them correctly from the first turn. The file is
+gitignored by default, paste-only, and contains zero PII beyond what the
+user explicitly volunteers. Schema is locked v1 in
+[`docs/contracts/agent-user-schema.md`](docs/contracts/agent-user-schema.md).
+
+Create it interactively with `/agents user init`. Inspect with
+`/agents user show`. Updates happen only through the explicit
+`review` / `accept` / `update` flow — never silent auto-writes. The
+legacy `personal.user_name` key in `.agent-settings.yml` stays as a
+fallback when `.agent-user.md` is absent.
+
 ## Core Principles
 
 - **Analyze before implementing** — no guessing, no blind edits

package/config/agent-settings.template.yml

@@ -40,6 +40,10 @@ personal:
   open_edited_files: false
 
   # User's first name — used to address the user personally
+  # NOTE (legacy fallback): Source of truth for user identity is now the
+  # project-root `.agent-user.md` file, created via `/agents user init`.
+  # This key is retained for backward compatibility; the agent only falls
+  # back to it when `.agent-user.md` is absent.
   user_name: ""
 
   # rtk (Rust Token Killer) installed for output filtering (true, false)

package/config/gitignore-block.txt

@@ -18,6 +18,17 @@
 .agent-settings
 .agent-settings.backup.key-value
 
+# Agent config — user-persona file (.agent-user.md, written by /agents user init)
+# Contains who the user is and how they want to be addressed. Local-only by
+# default; commit explicitly only via the deferred --shared opt-in.
+# See docs/contracts/agent-user-schema.md.
+.agent-user.md
+.agent-user.md.bak
+
+# Agent config — user-persona observation buffer (append-only JSONL,
+# never shared). Feeds /agents user review / accept only.
+.agent-user.observations.jsonl
+
 # Agent config — persistent chat history (crash recovery, never commit)
 /agents/.agent-chat-history
 /agents/.agent-chat-history.bak

package/docs/architecture.md

@@ -143,7 +143,7 @@ note, package-internal path-swap, description budget, and the
 |---|---|---|
 | **Skills** | 210 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
 | **Rules** | 67 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
-| **Commands** | 109 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
+| **Commands** | 115 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
 | **Guidelines** | 72 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |