@event4u/agent-config 2.13.0 → 2.15.0

package/CHANGELOG.md

@@ -16,6 +16,184 @@ Entry-shape contract: [`docs/contracts/CHANGELOG-conventions.md`](docs/contracts
 
 ## [Unreleased]
 
+**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
+member, low-impact dispatch) under one roadmap. New surfaces:
+
+- **`defaults.member_mode: cli | api`** (default `cli`) — flips the
+  global transport default to CLI-first onboarding (subscription auth,
+  no API key). Per-member explicit `mode:` keeps overriding.
+- **`routing.solo_member_fallback_chain: [provider, ...]`** — ordered
+  preference list for single-member dispatch. Disabled members are
+  skipped; duplicates rejected at config-load time; all-invalid
+  escalates to full council (never fails the decision). 15-minute
+  auth cache, 3-second timeout per probe.
+- **`low_impact.dispatch: full | single`** (default `full`) — opt-in
+  cost-efficient routing for low-impact decisions through
+  `routing.solo_member_fallback_chain`. **Iron Law:** `high_impact`
+  and `user_required` dispatch are NOT configurable — config validator
+  rejects both top-level and `decision_resolution.classes.*` forms,
+  including YAML `<<:` anchor smuggling attempts. Sentinel in
+  `tests/test_iron_law_config.py`.
+- **Shadow-mode safety net** — when `low_impact.dispatch: single` is
+  active, sample (default `0.1`) decisions go to both solo + full
+  council. Disagreements append to `agents/council-shadow-log.jsonl`
+  (privacy-redactor enforced). `agent-config council shadow-report`
+  computes the 7-day rolling SLO (`OK <5%` / `WARN 5–8%` / `BREACH
+  >8%`); pre-flight cost disclosure surfaces the verdict. No auto-
+  revert — humans decide.
+- **Confidence gate — auto-escalation on uncertain solo runs**
+  (`scripts/ai_council/confidence_gate.py`) — every solo response is
+  scored before the verdict is returned. Four escalation reasons in
+  priority order: `refusal` (empty / refusal markers), `split`
+  (two-verdict / option-A-vs-B / Variante 1/2), `short_response`
+  (< 20 chars), `low_confidence` (explicit `Confidence: 0.X` marker
+  or hedge-word density below floor). Zero extra LLM calls —
+  heuristics run in-process. Escalations append `escalated: true` +
+  `escalation_reason` to `agents/council-shadow-log.jsonl`; the SLO
+  banner appends the rolling auto-escalation rate so quiet uncertainty
+  cannot hide behind a flat disagreement rate.
+- **`low_impact.solo_confidence_floor: float`** (default `0.7`,
+  range `[0.0, 1.0]`) — threshold for the confidence gate.
+  **Iron Law:** `solo_confidence_floor` is also rejected on
+  top-level `high_impact:` and `user_required:` — those classes
+  never run solo, so a solo-specific knob there is incoherent.
+- **`AGENT_CONFIG_FORCE_FULL_COUNCIL=1`** — per-invocation kill-switch
+  that forces full council regardless of `low_impact.dispatch`.
+- **Airgap detection** (`scripts/ai_council/airgap.py`) — installer
+  first-run probes DNS for `api.anthropic.com`, `api.openai.com`,
+  `generativelanguage.googleapis.com` with 1s timeout per host. All
+  fail → banner `airgapped environment detected — defaulting to
+  mode: api` and `defaults.member_mode: api` recommendation.
+- **Fast-path marker visibility Iron-Law rule**
+  (`.agent-src.uncompressed/rules/fast-path-marker-visibility.md`,
+  kernel-tier, always-active) — host agents MUST surface
+  `Resolved via low-impact council fast-path: …` markers verbatim;
+  swallowing them is a rule violation.
+- **`/memory learn-low-impact --preview`** (default) / `--apply` —
+  preview shows promoted entries, refused entries with redaction
+  reasons, source-project-stripped diff, and the upstream PR body
+  draft before anything is written.
+- **Corpus parser hardening** — typed `CorpusParseError(reason=...)`
+  replaces silent skip; seven failure-mode fixtures in
+  `tests/fixtures/corpus-robust/` (missing anchor · renamed heading ·
+  bullet-without-quotes · duplicate entry · anti-example wrongly
+  under Validated · malformed ISO timestamp · redactor-bypass).
+  Contract in `docs/contracts/low-impact-corpus-format.md`.
+- **Fuzzy corpus matching (opt-in)** —
+  `low_impact.fuzzy_match.{enabled,threshold}` (defaults `false`,
+  `0.92`) using `difflib.SequenceMatcher`. High-impact trigger veto
+  + anti-example veto preserve the Iron Law.
+- **CLI-binary UX** — pre-flight cost disclosure now prints
+  `member X skipped: binary not found, install via <hint>` per
+  skipped CLI member; hints sourced from
+  `scripts/ai_council/cli_hints.py`.
+- **Doctor CLI checks** — `agent-config doctor --check council-cli`
+  reports per CLI member: binary present · auth probe · parse
+  fixture · quota remaining · billable flag.
+- **Iron-Law bypass linter** — `audit_cloud_compatibility.py
+  --iron-law` scans `scripts/` for raw YAML loads of `ai-council.yml`
+  that skip the config validator; baseline is 0 findings; suppress
+  legitimate cases with `# iron-law-ok: <reason>` on the load line.
+
+Surface delta: **4 new config knobs** (`defaults.member_mode`,
+`routing.solo_member_fallback_chain`, `low_impact.dispatch`,
+`low_impact.solo_confidence_floor`),
+**1 new env-var kill-switch** (`AGENT_CONFIG_FORCE_FULL_COUNCIL`),
+**1 new CLI subcommand** (`council shadow-report`), **1 new CLI flag**
+(`council run --single`), **1 new always-active rule**
+(`fast-path-marker-visibility`), **2 new local-only files**
+(`agents/council-shadow-log.jsonl`, gitignored;
+`scripts/ai_council/airgap.py`). Backward-compat: defaults map the
+existing behaviour (`dispatch=full`, empty chain, `member_mode=cli`
+in fresh installs; existing configs read unchanged). No migration
+script — defaults are silent-safe.
+
+**Low-impact corpus YAML lockfile (`step-10-corpus-yaml-lockfile`)** —
+follow-up to the PR #150 review (Punkt 4): the Markdown parser used to
+be the runtime source-of-truth for the low-impact decisions corpus,
+making every human edit-variation (curly quotes, bullet style,
+whitespace, heading rename) a potential parser bomb on the hot path.
+Switched the runtime to a generated YAML lockfile while keeping
+Markdown as the human-editable source. New surfaces:
+
+- **`scripts/ai_council/compile_corpus.py`** — build tool that runs
+  `parse_corpus_strict()` over `agents/low-impact-decisions.md` and
+  emits `agents/low-impact-decisions.lock.yaml` (schema-v1, sorted
+  keys, deterministic). `--check` mode exits `1` on drift, `2` on
+  parse error.
+- **`agents/low-impact-decisions.lock.yaml`** — generated, **committed**
+  lockfile. Schema `{schema_version: 1, provenance: {source_path,
+  source_sha256, last_upstreamed}, validated, probation, anti_examples}`.
+  Diffed in PR reviews alongside the Markdown source.
+- **`low_impact_corpus.load_corpus_lock()`** — new primitive that
+  loads the YAML lockfile and re-materialises a `CorpusParseResult`.
+  Schema-version mismatch raises `CorpusParseError` with reason
+  `schema_version_mismatch`.
+- **Lenient loaders prefer YAML** — `load_validated_phrases` and
+  `load_anti_example_phrases` (consumed by `necessity.py` and
+  `low_impact.py` on the hot path) check for the sibling `.lock.yaml`
+  first. Missing / malformed lockfile → silent fallback to lenient
+  Markdown parsing, so a fresh clone before `task sync` still works.
+- **CI gate** — `task compile-corpus` runs as part of `task sync` and
+  `task consistency` (before `git diff --quiet`). A stale lockfile
+  fails CI the same way `.agent-src/` drift does.
+- **Preview tool unchanged** — `learn_low_impact_preview.py` keeps
+  reading the Markdown directly via `parse_corpus_strict`; it runs
+  *before* `task sync` rebuilds the lockfile, so it must read whatever
+  the user just edited.
+
+The Markdown parser stays in the repo as a build-time dependency, not
+a runtime dependency — a parser regression breaks `task consistency`,
+never the live council. Privacy floor (`low-impact-corpus-privacy-floor`)
+unchanged: the redactor scans entry text, not file format.
+
+**Council quota & necessity transparency (`step-8-quota-necessity-transparency`)** —
+the council's two pre-flight gates (`cli_call_budget` and
+`necessity_classifier`) become observable and aligned with the
+"Council always active when enabled" mental model. New surfaces:
+
+- `council run` / `council debate` print a one-line
+  `council:quota · <provider> used/limit · …` summary before the
+  first member fires. Only providers with a configured per-day cap
+  appear; uncapped providers are omitted (no false metering).
+- `cli_call_budget.warn_at` (float, default `0.8`) — once
+  `used / max_calls_per_day >= warn_at`, the summary line is
+  prefixed `⚠️` and a `council:quota · WARN` line names the
+  providers near the wall.
+- New `agent-config council quota` subcommand dumps today's
+  `~/.event4u/agent-config/cli-calls.json` state plus the configured
+  caps. `--reset <provider> --confirm` clears today's counter for one
+  provider for manual rollover.
+- **Necessity tier split (D2):** `necessity_classifier.user_explicit_mode`
+  (default `warn-only`) separates the agent and user_explicit tiers.
+  User-typed `/council` calls proceed by default with an annotated
+  stdout line; agent-initiated dispatches keep `educate` behaviour.
+  New `warn-only` mode joins the existing `off | educate | block`
+  enum — annotates the verdict but never skips.
+- **Persistent events log (D3):** every necessity-gate decision
+  (`proceed` / `skip_necessity`) and every quota block
+  (`block_quota`) appends one JSON line to `agents/council-events.log`
+  (gitignored; never committed). Schema v1 with `schema_version`,
+  `ts_utc`, `lens`, `invocation`, `action`, `verdict`,
+  `provider_caps`, `original_ask_hash`. `original_ask` is hashed
+  `sha256[:12]` before write — the raw prompt is never persisted
+  (privacy floor per `agents/low-impact-decisions.md`).
+- **Kill-switch (D5):** `AGENT_CONFIG_NO_EVENTS_LOG=1` disables
+  every events-log write in-process. Mirrors the
+  `AGENT_CONFIG_LEGACY_ANCHOR=1` pattern from step-7.
+
+Surface delta: **1 new subcommand** (`council quota`), **2 new
+config knobs** (`cli_call_budget.warn_at`,
+`necessity_classifier.user_explicit_mode`), **1 new local-only file**
+(`agents/council-events.log`, gitignored). Backward-compat:
+existing `.agent-settings.yml` and `agents/.ai-council.yml` work
+unchanged; new knobs are optional. Docs:
+[`docs/contracts/ai-council-config.md`](docs/contracts/ai-council-config.md)
++ [`docs/installation.md`](docs/installation.md) § AI Council local
+state.
+
 Four roadmaps land in this release.
 
 **Tier-0 trim (`road-to-surface-discipline` Phase 1)** — six CLI
@@ -422,13 +600,153 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
-# Era: 2.7.x — current
+# Era: 2.11.x — current
 
-> Started at `2.7.0` (2026-05-13). Full entries live inline below.
+> Started at `2.11.0` (2026-05-14). 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.8.x`, etc.) — see
+> that forces a new era split (`# Era: 2.12.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [2.15.0](https://github.com/event4u-app/agent-config/compare/2.14.0...2.15.0) (2026-05-15)
+
+### Features
+
+* **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
+
+* **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
+
+* **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
+
+* **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))
+
+Tests: 4352 (+12 since 2.14.0)
+
+## [2.14.0](https://github.com/event4u-app/agent-config/compare/2.13.0...2.14.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))
+
+### 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))
+
+### Refactoring
+
+* **commands:** nest learn-low-impact under memory cluster ([473dc97](https://github.com/event4u-app/agent-config/commit/473dc9776cd3dfb55f66e06977c1abaf02afcc01))
+
+### 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))
+
+### 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
@@ -544,129 +862,15 @@ Tests: 3718 (+0 since 2.11.0)
 
 Tests: 3718 (+55 since 2.10.0)
 
-## [2.10.0](https://github.com/event4u-app/agent-config/compare/2.9.0...2.10.0) (2026-05-14)
-
-### Features
-
-* **ci:** lint-hook-concern-budget Tier-1 fail-closed gate ([8d60b8a](https://github.com/event4u-app/agent-config/commit/8d60b8ab464c4c5bdc6d072bb2a9b0123942e13b))
-* **cli:** settings:check command + YAML subset contract ([638e740](https://github.com/event4u-app/agent-config/commit/638e74017ffea8d7c08073a949e86fde047db109))
-* **hooks:** hooks:doctor + hooks:replay subcommands + fixture corpus ([3156e25](https://github.com/event4u-app/agent-config/commit/3156e25fd3253fc926a57b92e14b407a9ed54b58))
-* **work-engine:** add decision-trace memory_visibility hook + scoring ([bf056ac](https://github.com/event4u-app/agent-config/commit/bf056ace877a696afa5fe758053ea1eb350e5dff))
-
-### Bug Fixes
-
-* **roadmap:** point productization P6 gate at archived proof-not-features path ([35a1009](https://github.com/event4u-app/agent-config/commit/35a1009cffdfde28c7b0384c890c31a7e62b70cf))
-
-### Documentation
-
-* **roadmap:** complete road-to-proof-not-features 16/16 + sync dashboard ([89af72d](https://github.com/event4u-app/agent-config/commit/89af72d5514b74c19d533b5a2e69ff7ddf16ecbc))
-* **readme:** split README by audience + audience-order contract ([60a87c0](https://github.com/event4u-app/agent-config/commit/60a87c056555a80585d25555f3d5b87d54c7283a))
-
-### Refactoring
-
-* **check-council-references:** structural carve-outs for immutable inputs and decision provenance ([3ed7784](https://github.com/event4u-app/agent-config/commit/3ed77841c42c5e3ebf4191611bb7fa4a52ed2fa0))
-
-### Chores
-
-* **roadmap:** archive road-to-proof-not-features (16/16 done, Phase 1 deferred) ([9d05aed](https://github.com/event4u-app/agent-config/commit/9d05aed79a46023b1e95c5488a1e3d5e78748e67))
-
-Tests: 3663 (+60 since 2.9.0)
-
-## [2.9.0](https://github.com/event4u-app/agent-config/compare/2.8.0...2.9.0) (2026-05-13)
-
-### Features
-
-* tier-usage telemetry settings + report template ([22172f2](https://github.com/event4u-app/agent-config/commit/22172f2a59b530034633ff72226506006c5fd81b))
-* mcp beta-readiness criteria with pending gate tests ([3653788](https://github.com/event4u-app/agent-config/commit/36537880e03546e9baf424b2fdd70aa69d41eb03))
-* expand doctor diagnostic hub to 10 checks ([372c193](https://github.com/event4u-app/agent-config/commit/372c19362f8037c76f919a2d918780ae5ec9cb40))
-* **roadmap:** add road-to-surface-discipline (council-reviewed) ([d9da987](https://github.com/event4u-app/agent-config/commit/d9da9870989ccdb7594cd693e9b18608b957ab79))
-* **linter:** wing-4 cognition-boundary checks + spine slot vocab ([c4d9a4b](https://github.com/event4u-app/agent-config/commit/c4d9a4ba8e5c7184b9be0a58d4d8b220a60cab7c))
-
-### Bug Fixes
-
-* **skills:** clear missing_inspect_step + bare_noun warnings ([0c88c6e](https://github.com/event4u-app/agent-config/commit/0c88c6ee45873e47fd8c7d356ec82b28b63b12c5))
-* **docs:** drop roadmap-file pointers from wing-4 ADRs and handoff ([ccd7624](https://github.com/event4u-app/agent-config/commit/ccd7624127094d0a01eda0901fa41c31319f7bc5))
-* **template:** bump agent_config_version pin to 2.8.0 ([f21e916](https://github.com/event4u-app/agent-config/commit/f21e916c6bb793fa6efe7d264a1e069e11ab4c62))
-* **skills:** spine slot citations + finance-partner polish ([9072783](https://github.com/event4u-app/agent-config/commit/90727831b223bd970d8425d158940bf3e3bc104f))
-
-### Documentation
-
-* archive surface-discipline roadmap + 2.8.0 changelog ([551e306](https://github.com/event4u-app/agent-config/commit/551e306e43fa82fffda9178bdaa690b19d8bec4e))
-* 6-layer architecture refresh + thin-root sync ([91d25a8](https://github.com/event4u-app/agent-config/commit/91d25a80b37fb1c1782c2d5f00f23925ba6ec1b3))
-* **roadmap:** complete road-to-money-strategy-ops phase 1 ([83cf9fe](https://github.com/event4u-app/agent-config/commit/83cf9fe99c034b71e146099eddc9ce5b3137f434))
-* **contracts:** register wing-4 spine slots + marketplace entries ([75b829d](https://github.com/event4u-app/agent-config/commit/75b829d162bc18ab3dc2dda6614d15a087a4f32a))
+# Era: pre-2.11.0 — archived
 
-### Refactoring
-
-* trim tier-0 surface from 13 to 7 commands ([a9eafd1](https://github.com/event4u-app/agent-config/commit/a9eafd1c5226c10209e3dee2b972f38d9c0f3dd9))
-
-### Chores
-
-* **generated:** regenerate derived outputs for wing-4 additions ([54f3779](https://github.com/event4u-app/agent-config/commit/54f3779a6d2161ed06bfb327c3e416ec107b4016))
-
-Tests: 3603 (+26 since 2.8.0)
-
-## [2.8.0](https://github.com/event4u-app/agent-config/compare/2.7.0...2.8.0) (2026-05-13)
-
-### Features
-
-* **linter:** wing-scoped persona line budgets ([81c8cda](https://github.com/event4u-app/agent-config/commit/81c8cdaf08f243a61f848b2e53fad73305ec173d))
-* **personas:** GTM roadmap I1-I4 — Wing-3 personas (CMO, RevOps, CS, Growth-PM) ([a05d49e](https://github.com/event4u-app/agent-config/commit/a05d49e1fd2076effd68dabce7a0789676b2bbf5))
-* **skills:** GTM roadmap H8-H16 — RevOps, CS, Growth-PM clusters ([f79e7a1](https://github.com/event4u-app/agent-config/commit/f79e7a11f5447466c05c6be613a618b9c564a4b1))
-* **gtm:** H3–H7 — complete CMO cluster skills (gtm-launch, editorial-calendar, content-funnel-design, voice-and-tone-design, fundraising-narrative) ([a905bea](https://github.com/event4u-app/agent-config/commit/a905bea811a02d973a682465525ca39d274d3342))
-* **gtm:** H1+H2 — positioning + messaging-architecture senior skills ([00aeb27](https://github.com/event4u-app/agent-config/commit/00aeb279be9924c01dea998df7ee91442fd3ff88))
-* **gtm:** G3 — Wing-3 handoff guideline + Block G closed ([15643da](https://github.com/event4u-app/agent-config/commit/15643da3e2e96a6b00a738e8f4b7ba10edd18187))
-* **gtm:** G2 — Wing-3 cognition-boundary linter ([8445921](https://github.com/event4u-app/agent-config/commit/84459218a914dd5d39c524824e9e0a597c28daec))
-* **gtm:** G1 — extend context-spine with Wing-3 slots ([853e653](https://github.com/event4u-app/agent-config/commit/853e6538fff24429ab0f4136f5eec5d4b992dda4))
-
-### Bug Fixes
-
-* **refs:** drop roadmap-file citations from GTM ADR + handoff guideline ([092a01d](https://github.com/event4u-app/agent-config/commit/092a01d7bcd6b51c85d12bfcf83dc973b35c0fcc))
-* **contracts:** add stability frontmatter to command-surface-tiers.md ([3ab2ffd](https://github.com/event4u-app/agent-config/commit/3ab2ffde4345b4ca30cc4d64926f571bce5ce7dd))
-* **lint:** teach context-spine linter the Wing-3 GTM slots ([5bf81d5](https://github.com/event4u-app/agent-config/commit/5bf81d51864b652301d890eafb0574641d05b71a))
-* **refs:** replace dangling skill backticks with plain phrasing in GTM skills ([9f20b06](https://github.com/event4u-app/agent-config/commit/9f20b0612b58f8ef0273bfbe5f830793f4dca131))
-* **template:** bump agent_config_version to 2.7.0 in agent-project-settings template ([ac65734](https://github.com/event4u-app/agent-config/commit/ac657343a81879c3aee4664728e15233863016a5))
-
-### Refactoring
-
-* **skill:** rename positioning → positioning-strategy ([be1a5c9](https://github.com/event4u-app/agent-config/commit/be1a5c9019ac18fabde14469784db42aa7588a14))
-
-### Chores
-
-* **index:** regenerate after positioning → positioning-strategy rename ([9f42d91](https://github.com/event4u-app/agent-config/commit/9f42d9148f196d30635ae8288e9bba0feda66067))
-* **changelog:** split era 2.2.x → pre-2.7.0 ([7158c30](https://github.com/event4u-app/agent-config/commit/7158c30db391f3464fd74f3c7e193698b869b82d))
-* **generated:** refresh agents/index.md and docs/catalog.md for GTM skills/personas ([649b86e](https://github.com/event4u-app/agent-config/commit/649b86e287ecef7d0d28ce23ed2b0cbf43f2adc6))
-* **generated:** regenerate .claude/ tool output + marketplace + compression hashes for GTM skills/personas ([bb7d56c](https://github.com/event4u-app/agent-config/commit/bb7d56cd8e7cafb9037a4e6ec0078e56154f9d5c))
-* **roadmap:** archive road-to-gtm-and-growth — G+H+I all shipped ([dc48cdd](https://github.com/event4u-app/agent-config/commit/dc48cdd29e236c745e98b5f5fb8b45fa716a4c07))
-
-Tests: 3577 (+11 since 2.7.0)
-
-## [2.7.0](https://github.com/event4u-app/agent-config/compare/2.6.1...2.7.0) (2026-05-13)
-
-### Features
-
-* **install:** make augment global-only per ADR-007 amendment ([ea9a82f](https://github.com/event4u-app/agent-config/commit/ea9a82f2305a2a178b058ee66c40859790620d63))
-* **mcp:** define mcp_scope lite vs full boundary in cloud-scope contract ([15a268c](https://github.com/event4u-app/agent-config/commit/15a268c9f86fabe677b4d70db9fd4e3d1726ef8a))
-* **commands:** tier the slash + CLI command surface (Phase 4 of road-to-distribution-maturity) ([cc0102f](https://github.com/event4u-app/agent-config/commit/cc0102fe9677c936f703fd6e08b75cc99f758071))
-* **distribution:** roadmap phases 1+2 — MCP auth-surface sync + verified-offline install ([a85c1af](https://github.com/event4u-app/agent-config/commit/a85c1afdc457c5fa4d939afc2d91649c67926501))
-
-### Bug Fixes
-
-* **refs:** point evaluation-2-2-2-followups at archived roadmap location ([cde02e6](https://github.com/event4u-app/agent-config/commit/cde02e6fd3bfbb2d67e2a8e3976fe6794ea4de6c))
-
-### Documentation
-
-* **architecture:** split docs/architecture.md into four pipeline sub-pages + drift test ([4f13cf5](https://github.com/event4u-app/agent-config/commit/4f13cf504c0b2d9b92661234a597b5515a7c54e8))
-* **roadmap:** add distribution-maturity roadmap with council verdicts folded in ([14145cf](https://github.com/event4u-app/agent-config/commit/14145cff75ef34065358a2e99ee8c220ab0e59a0))
-
-### Chores
-
-* **ci:** refresh compression hashes after cc0102fe tiering pass ([ca06729](https://github.com/event4u-app/agent-config/commit/ca06729d03bb8bd8d1536b7aecef1d1b134d8333))
-* finalize roadmaps ([bb156ea](https://github.com/event4u-app/agent-config/commit/bb156ea4f52741d511c3e54cd87e3bcab2fbf107))
-* **roadmap:** close road-to-distribution-maturity, archive ([d48e5d6](https://github.com/event4u-app/agent-config/commit/d48e5d64f9396f6b75b47bf336fd6ac129c8e254))
-* **changelog:** split into eras, archive pre-2.2.0 entries ([e54c5cb](https://github.com/event4u-app/agent-config/commit/e54c5cbf0222de7f0f4c84a379118f4ea30b5a07))
+> All entries from `2.10.0` through `2.7.0` live in
+> [`docs/archive/CHANGELOG-pre-2.11.0.md`](docs/archive/CHANGELOG-pre-2.11.0.md).
+> The archive is read-only; git tags `2.10.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`.
 
-Tests: 3566 (+36 since 2.6.1)
 
 # Era: pre-2.7.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>65 Rules</strong> · <strong>108 Commands</strong> · <strong>72 Guidelines</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>
 
 ---
@@ -31,8 +31,8 @@ replay it. [Core Principles](#core-principles) names the four invariants.
 [What this package is — and what it isn't](#what-this-package-is--and-what-it-isnt)
 draws the scope boundary. [Documentation](#documentation) lists the
 contracts the package ships against, including
-[`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) and
-[`decision-trace-v1`](docs/contracts/decision-trace-v1.md).
+[`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) (beta) and
+[`decision-trace-v1`](docs/contracts/decision-trace-v1.md) (beta).
 
 ## Contribute
 
@@ -288,7 +288,7 @@ Install in the same project (dev-only):
 npm install --save-dev @event4u/agent-memory
 ```
 
-→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta) · [Built-in MCP server](docs/mcp-server.md) (experimental — local stdio access from Claude Desktop / Cursor / Zed / Continue, install with `task mcp:setup`; promotion to beta gated on [`mcp-beta-criteria.md`](docs/contracts/mcp-beta-criteria.md))
+→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta) · [Built-in MCP server](docs/mcp-server.md) (experimental — local stdio access from Claude Desktop / Cursor / Zed / Continue, install with `task mcp:setup`; promotion to beta gated on `docs/contracts/mcp-beta-criteria.md`)
 
 ---
 
@@ -524,7 +524,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 108 active commands](.agent-src/commands/)
+→ [Browse all 115 active commands](.agent-src/commands/)
 
 ---
 
@@ -556,7 +556,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 + 108 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 +605,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
@@ -37,6 +48,12 @@
 /agents/council-responses/
 /agents/council-sessions/
 
+# Agent config — AI Council persistent events log (step-8 D3).
+# Local JSONL audit trail for necessity / quota decisions. Hashes
+# original_ask before write but is still considered private. Set
+# AGENT_CONFIG_NO_EVENTS_LOG=1 to disable writes entirely.
+/agents/council-events.log
+
 # Agent config — Tier 1 hook runtime state (context-hygiene.json,
 # onboarding-gate.json). Written by SessionStart / PostToolUse hooks
 # on Augment + Claude Code; regenerated on demand, never commit.