@event4u/agent-config 2.15.0 → 2.17.0

package/docs/contracts/write-engine.md

@@ -0,0 +1,142 @@
+---
+stability: beta
+keep-beta-until: 2026-08-13
+---
+
+# Write-engine contract (v1)
+
+> **Status:** beta — shared procedural contract consumed by
+> `/ghostwriter:write`, `/post-as:ghostwriter` (alias), and
+> `/post-as:me`. Locked alongside the ghostwriter cluster roadmap.
+
+The **write engine** is the deterministic procedure that produces a
+copyable markdown draft in a captured voice. It deliberately has no
+implementation file — the engine is a sequence of steps the host
+agent follows verbatim. The same steps are referenced by every
+consumer command; the **only** axis of variation is:
+
+1. **Style source** — which file the engine reads to load the voice.
+2. **Disclosure footer** — appended when the style source is *external*
+   (a ghostwriter profile), omitted when the style source is *self*
+   (`.agent-user.md`).
+
+## Style sources
+
+| Consumer command | Style source | Footer |
+|---|---|---|
+| `/ghostwriter:write` | `agents/ghostwriter/<slug>.md` (selected) | **Mandatory** |
+| `/post-as:ghostwriter` | Same as above (thin alias) | **Mandatory** |
+| `/post-as:me` | `.agent-user.md` (project root) | **Omitted** — user is the author |
+
+No other style source is permitted in v1. Consuming `personas/*.md`
+voices is explicitly out of scope — personas are review lenses, not
+author voices.
+
+## Procedure (followed verbatim by every consumer)
+
+### 1. Resolve the style source
+
+Each consumer command resolves a single style source before invoking
+the engine. The engine receives a fully populated style object with:
+
+- `identity.name` (for the footer when applicable)
+- `style.fingerprint.*` (sentence length, register, opener / closer
+  patterns, hashtag / emoji rules, paragraph cadence)
+- `style.free_form_notes` (or `voice_sample` for `/post-as:me`)
+- `taboos` (ghostwriter only — empty list for `/post-as:me`)
+
+Missing style source → consumer command aborts with a pointer at the
+appropriate setup command (`/ghostwriter:fetch` or `/agents user init`).
+
+### 2. Collect the topic + modifiers
+
+One question per turn, in this order:
+
+1. **Topic** — required. Plain prose, no quoting.
+2. **Tone** — optional. Enum: `formal | casual | neutral`. Default
+   inherits `style.fingerprint.vocab_register` mapped per the table
+   below.
+3. **Length** — optional. Integer word count. Default: see the
+   per-channel defaults table.
+4. **Channel** — optional. Enum: `linkedin-post | tweet | blog | freeform`.
+   Default: `freeform`.
+5. **Audience** — optional. Free-form one-line descriptor.
+
+Modifiers may be supplied via flags (`--tone=casual --length=200
+--channel=linkedin-post --audience="early-stage founders"`) to skip
+the interactive interview. `--as=<slug>` selects the ghostwriter
+non-interactively for `/ghostwriter:write` and the alias.
+
+#### Per-channel defaults
+
+| Channel | Length default | Cadence guidance |
+|---|---|---|
+| `tweet` | 50 words | One paragraph, no lists. |
+| `linkedin-post` | 180 words | 2–4 short paragraphs. Hashtags only if `style.fingerprint.hashtag_rules` allows. |
+| `blog` | 600 words | Inherits `style.fingerprint.paragraph_cadence`. |
+| `freeform` | 250 words | Inherits `style.fingerprint.paragraph_cadence`. |
+
+#### Vocab-register → tone mapping (default inheritance)
+
+| `vocab_register` | Default `tone` |
+|---|---|
+| `casual` / `conversational` | `casual` |
+| `professional` / `literary` | `neutral` |
+| `academic` | `formal` |
+
+### 3. Apply negative-constraint pass (ghostwriter only)
+
+Before drafting, the engine surfaces the loaded `taboos` list and
+explicitly excludes those moves from the draft (no political
+endorsements, no profanity, no hashtag-driven posts, etc.). For
+`/post-as:me`, the negative-constraint pass is skipped (the user does
+not pre-declare taboos in v1).
+
+### 4. Draft
+
+Emit the body as a single fenced markdown block. The body MUST:
+
+- Match `style.fingerprint.sentence_length_avg` within ±25%.
+- Honour `style.fingerprint.opener_patterns` for the first sentence.
+- Honour `style.fingerprint.closer_patterns` for the last sentence.
+- Respect `style.fingerprint.hashtag_rules` and `emoji_rules`.
+- Stay within ±15% of the requested length.
+
+### 5. Append the disclosure footer (ghostwriter only)
+
+For ghostwriter consumers, append on its own line, separated by a
+blank line:
+
+```
+Written in the style of <identity.name>, not by them.
+```
+
+The footer is appended **by the command's output template** as a
+literal string — it is not generated by the model and has no opt-out
+flag. For `/post-as:me` the footer is omitted entirely (the user is
+the author).
+
+### 6. Print the draft
+
+Print the fenced markdown block. No commit, no save, no file write.
+The user copies the output manually. The engine performs no side
+effects on disk.
+
+## Rules
+
+- **No `--no-disclosure` flag.** For any ghostwriter consumer, the
+  footer is mandatory and deterministic. `task lint-skills` greps the
+  ghostwriter command sources for the literal string `no-disclosure`
+  and fails CI on a hit.
+- **No multi-voice draft in v1.** One style source per invocation;
+  blending voices is deferred.
+- **No file writes.** The engine prints; the user copies. Saving the
+  output to `agents/` or anywhere else is a future feature.
+
+## See also
+
+- [`ghostwriter-schema`](ghostwriter-schema.md) — the source schema
+  for `/ghostwriter:write`.
+- [`agent-user-schema`](agent-user-schema.md) — the source schema
+  for `/post-as:me`.
+- [`command-clusters`](command-clusters.md) — cluster registration.

package/docs/getting-started-by-role.md

@@ -0,0 +1,89 @@
+# Getting started — by role
+
+> Pick the entry that matches what you do day-to-day. Each section names the three skills you will reach for first and shows whether MCP (no terminal) or CLI (terminal) is the simpler install path for that role.
+
+`agent-config` ships ~210 skills, ~67 rules, and ~124 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
+
+> **Eval-gated messaging note.** Until `task bench --corpus non-dev` reports `selection_accuracy >= 0.60` (step-12 Phase 1 exit), this page is documentation, not marketing. The skills listed below are the candidates the corpus tests against; their description quality is what the eval validates. See [`agents/roadmaps/step-12-universal-os-reframe.md`](../agents/roadmaps/step-12-universal-os-reframe.md).
+
+---
+
+## Creator (writer, marketer, indie content shop)
+
+**You want this if:** you draft blog posts, marketing emails, launch copy, or release announcements and want a writing assistant that holds a defined brand voice across surfaces. You need brand-voice discipline more than code-quality enforcement. You will spend most of your time in Claude Desktop / ChatGPT, not in a terminal.
+
+- [`voice-and-tone-design`](../.agent-src/skills/voice-and-tone-design/SKILL.md) — define and audit brand voice (voice attributes, tone-by-context matrix).
+- [`messaging-architecture`](../.agent-src/skills/messaging-architecture/SKILL.md) — primary message + supporting proofs + audience-by-message matrix.
+- [`editorial-calendar`](../.agent-src/skills/editorial-calendar/SKILL.md) — evergreen vs campaign vs reactive cadence across channels.
+
+**Install path:** **MCP recommended.** Claude Desktop is the lowest-friction entry; no terminal required. See [`docs/mcp.md`](mcp.md). CLI install works too if you already use a code editor.
+
+---
+
+## Founder (early-stage operator wearing every hat)
+
+**You want this if:** you switch between investor pitch, hiring decision, product spec, and unit-economics modeling in the same week. You need cross-domain skills that respect your time budget, not depth-first specialists. Decisions need to be defensible to a board.
+
+- [`runway-cognition`](../.agent-src/skills/runway-cognition/SKILL.md) — cash runway, burn shape, fundraise triggers, cut-vs-grow.
+- [`unit-economics-modeling`](../.agent-src/skills/unit-economics-modeling/SKILL.md) — CAC, LTV, payback, contribution margin per customer.
+- [`fundraising-narrative`](../.agent-src/skills/fundraising-narrative/SKILL.md) — why-now / why-us / why-this framing, market-size reasoning.
+
+**Install path:** **MCP for advisory work, CLI when you touch code.** Claude Desktop covers strategy / finance / narrative; CLI is needed only when you sit in the repo with the dev team.
+
+---
+
+## Developer (the original audience)
+
+**You want this if:** you write code daily — Laravel, Symfony, Next.js, Node, or stack-agnostic — and want testing / quality / git / CI guardrails baked into the agent's behavior. You will use commands like `/work`, `/commit`, `/create-pr`, `/quality-fix` constantly.
+
+- [`laravel`](../.agent-src/skills/laravel/SKILL.md) — Laravel-flavored PHP (Eloquent, Artisan, FormRequests, jobs, policies). See [`docs/getting-started-laravel.md`](getting-started-laravel.md) for the deep dive.
+- [`nextjs-patterns`](../.agent-src/skills/nextjs-patterns/SKILL.md) — App Router, Server Components, Server Actions, caching.
+- [`quality-tools`](../.agent-src/skills/quality-tools/SKILL.md) — PHPStan, Rector, ECS error triage and fix loop.
+
+**Install path:** **CLI.** Run `npx @event4u/agent-config init --tools=claude-code,cursor` in the project root. MCP works too but loses git / file-system tooling that the IDE-integrated path gives you.
+
+---
+
+## Consultant (advisory, freelance, fractional)
+
+**You want this if:** you sell discovery, positioning, competitive analysis, or roadmap audits. Output is briefs and slide content for a client, not code. You need defensible methodology behind every deliverable.
+
+- [`discovery-interview`](../.agent-src/skills/discovery-interview/SKILL.md) — switch-event JTBD guides, bias audit, falsifiable hypothesis.
+- [`competitive-moat-analysis`](../.agent-src/skills/competitive-moat-analysis/SKILL.md) — moat reasoning, where-to-play / where-not-to-play.
+- [`stakeholder-tradeoff`](../.agent-src/skills/stakeholder-tradeoff/SKILL.md) — per-lens framing, trade-off matrix with cost per choice.
+
+**Install path:** **MCP recommended.** Most consulting work is doc + slide drafting; the terminal adds friction without payback. Switch to CLI only if you also write code for the client.
+
+---
+
+## Go-To-Market (sales, marketing ops, RevOps)
+
+**You want this if:** you own pipeline shape, forecast accuracy, launch sequencing, or post-launch comms. You need deal-level rigor (MEDDIC, exit criteria) and narrative skills (release comms, messaging) in the same agent.
+
+- [`pipeline-strategy`](../.agent-src/skills/pipeline-strategy/SKILL.md) — stage exit criteria, per-cell conversion, leak diagnosis.
+- [`deal-qualification-meddic`](../.agent-src/skills/deal-qualification-meddic/SKILL.md) — MEDDIC slots with evidence, inversion test, disqualification heuristic.
+- [`release-comms`](../.agent-src/skills/release-comms/SKILL.md) — value-not-feature framing, audience-segmented surfaces.
+
+**Install path:** **MCP recommended.** GTM artifacts are documents, decks, and Notion pages; Claude Desktop is the natural home.
+
+---
+
+## Finance / Ops (CFO, controller, ops lead, founder-finance)
+
+**You want this if:** you build forecasts, model scenarios, and review data-handling for compliance. You need the agent to keep accounting / regulatory framing straight, not invent numbers.
+
+- [`forecasting`](../.agent-src/skills/forecasting/SKILL.md) — top-down vs bottom-up shape, confidence bands, retro-loop.
+- [`scenario-modeling`](../.agent-src/skills/scenario-modeling/SKILL.md) — base / upside / downside, three-statement modeling, sensitivity.
+- [`privacy-review`](../.agent-src/skills/privacy-review/SKILL.md) — GDPR / CCPA / HIPAA fit, cross-border transfer, breach-impact triage.
+
+**Install path:** **MCP recommended.** Finance / ops workflows are spreadsheet- and document-heavy; the CLI buys nothing here unless you also export models into a code repo.
+
+---
+
+## What is the same regardless of role
+
+A short universal-skills allowlist (`git`, `refine-ticket`, `proofread`, `threat-model`, etc.) loads in every profile. The list will live at `docs/contracts/universal-skills.md` once step-12 Phase 3 lands; until then the package loads all skills and the host agent's semantic search picks what the prompt needs.
+
+## What this page does not promise
+
+This page lists **candidate** skill / role pairings. Whether each skill's `description:` is sharp enough for the agent to retrieve it without manual hint is exactly what `tests/eval/corpus-non-dev.yaml` tests. If a prompt in your role above falls flat, that is a skill-description bug — file an issue or open a PR with a sharper description, do not work around it by naming the skill manually.

package/docs/getting-started-laravel.md

@@ -0,0 +1,72 @@
+# Getting started — Laravel
+
+> Laravel is the deepest reference stack in the package today. This page collects the Laravel-specific guidance previously embedded in the root README. The relocation is part of step-12 Phase 2; the root README continues to surface Laravel under the dev role until the Phase 6 identity rewrite lands.
+
+## Why Laravel is the reference stack
+
+Laravel ships with the broadest, battle-tested skill coverage in the package — Pest, PHPStan, Rector, Eloquent, Livewire / Flux, Horizon, Pulse, Reverb, Pennant. That coverage exists because the package was originally extracted from a Laravel monorepo (Galawork). Symfony and Next.js are the second tier (`symfony-workflow`, `nextjs-patterns`); other stacks ship as they are battle-tested, not second-class.
+
+## Laravel-flavored skills
+
+| Skill | What it covers |
+|---|---|
+| [`laravel`](../.agent-src/skills/laravel/SKILL.md) | Eloquent, Artisan controllers, FormRequests, jobs, events, policies, providers |
+| [`eloquent`](../.agent-src/skills/eloquent/SKILL.md) | Models, relationships, scopes, query patterns |
+| [`artisan-commands`](../.agent-src/skills/artisan-commands/SKILL.md) | Console command structure, signatures, safe execution |
+| [`jobs-events`](../.agent-src/skills/jobs-events/SKILL.md) | Queued workflows, listeners, retry / failure handling |
+| [`laravel-validation`](../.agent-src/skills/laravel-validation/SKILL.md) | Form Requests, rules, custom rule objects |
+| [`laravel-middleware`](../.agent-src/skills/laravel-middleware/SKILL.md) | Request / response filtering, groups, priority |
+| [`laravel-notifications`](../.agent-src/skills/laravel-notifications/SKILL.md) | Mail, Slack, database, custom channels |
+| [`laravel-mail`](../.agent-src/skills/laravel-mail/SKILL.md) | Mailables, Markdown templates, queued sending |
+| [`laravel-scheduling`](../.agent-src/skills/laravel-scheduling/SKILL.md) | Cron expressions, overlap prevention, maintenance mode |
+| [`laravel-horizon`](../.agent-src/skills/laravel-horizon/SKILL.md) | Worker supervision, job metrics, balancing strategies |
+| [`laravel-pulse`](../.agent-src/skills/laravel-pulse/SKILL.md) | Real-time dashboard, custom recorders, performance insights |
+| [`laravel-reverb`](../.agent-src/skills/laravel-reverb/SKILL.md) | First-party WebSocket server, Pusher protocol compatibility |
+| [`laravel-pennant`](../.agent-src/skills/laravel-pennant/SKILL.md) | Feature flags, gradual rollouts, A/B testing |
+
+## Quality pipeline
+
+The Laravel quality pipeline runs PHPStan + Rector + ECS, with Pest as the test runner:
+
+- [`quality-tools`](../.agent-src/skills/quality-tools/SKILL.md) — PHPStan output triage, Rector apply, ECS fix.
+- [`pest-testing`](../.agent-src/skills/pest-testing/SKILL.md) — Pest test authoring patterns.
+- [`/quality-fix`](../.agent-src/commands/quality-fix.md) — runs the full pipeline and fixes reported errors.
+
+## Docker and dev environment
+
+- [`docker`](../.agent-src/skills/docker/SKILL.md) — Dockerfile, compose, dual-container (fast + Xdebug) setup.
+- [`php-debugging`](../.agent-src/skills/php-debugging/SKILL.md) — Xdebug breakpoints, dual-container, header-based routing.
+- [`traefik`](../.agent-src/skills/traefik/SKILL.md) — local reverse proxy, real domains on 127.0.0.1, mkcert HTTPS.
+
+## Multi-tenancy and database
+
+- [`multi-tenancy`](../.agent-src/skills/multi-tenancy/SKILL.md) — customer DB switching, FQDN routing, tenant isolation.
+- [`database`](../.agent-src/skills/database/SKILL.md) — MariaDB / MySQL tuning, indexing, multi-connection patterns.
+- [`sql-writing`](../.agent-src/skills/sql-writing/SKILL.md) — raw SQL, parameterization, raw migrations.
+
+## Project analysis
+
+- [`project-analysis-laravel`](../.agent-src/skills/project-analysis-laravel/SKILL.md) — boot flow, request lifecycle, container usage, async systems, Laravel-specific failure patterns.
+
+## Install for a Laravel project
+
+```bash
+cd path/to/your/laravel/app
+npx @event4u/agent-config init --tools=claude-code,cursor
+```
+
+The installer detects `composer.json` + `artisan` + the Laravel framework dependency, enables stack-aware skills, and writes `.agent-settings.yml` with sensible defaults. The first `/onboard` run captures your name, preferred IDE, and cost profile.
+
+## Other PHP stacks
+
+| Stack | Coverage |
+|---|---|
+| **Symfony** | [`symfony-workflow`](../.agent-src/skills/symfony-workflow/SKILL.md) — DI, Doctrine, Messenger, voters, Twig; [`project-analysis-symfony`](../.agent-src/skills/project-analysis-symfony/SKILL.md) |
+| **Zend / Laminas** | [`project-analysis-zend-laminas`](../.agent-src/skills/project-analysis-zend-laminas/SKILL.md) + shared PHP coder / quality skills |
+| **Framework-free PHP** | [`php-coder`](../.agent-src/skills/php-coder/SKILL.md) — modern idioms, SOLID refactors, type hints without framework lock-in |
+
+## See also
+
+- [`docs/getting-started-by-role.md`](getting-started-by-role.md) — pick the entry that matches your day-to-day.
+- [`docs/getting-started.md`](getting-started.md) — generic three-step quickstart.
+- [`docs/installation.md`](installation.md) — detailed install variants (npx, curl, global npm).

package/docs/getting-started.md

@@ -106,7 +106,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 67 rules. No configuration needed.
+This is enforced automatically by 79 rules. No configuration needed.
 
 ---
 
@@ -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 115 active commands](../.agent-src/commands/)
+→ [Browse all 124 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/docs/safety.md

@@ -0,0 +1,30 @@
+# Data governance & domain safety
+
+`agent-config` ships **12 domain-safety rules** (`.agent-src.uncompressed/rules/domain-safety-*.md`) that act as a per-domain output floor — PII redaction, disclaimer requirements, and retention guidance. Rules fire automatically via the router when their triggers match.
+
+## Surface → rule(s) → floor
+
+| Surface | Rule(s) | Floor |
+|---|---|---|
+| Support / CRM drafts | `domain-safety-pii-support` · `domain-safety-retention-support` | Redact customer names, emails, phones, account IDs to placeholders before output |
+| Finance / invoicing | `domain-safety-pii-finance` · `domain-safety-retention-finance` | Redact counterparty PII and bank identifiers; flag retention under audit hold |
+| Recruiting | `domain-safety-pii-recruiting` | Redact candidate PII from notes, scorecards, rejection emails |
+| Marketing testimonials | `domain-safety-pii-marketing` | Require consent record before customer-identifying copy ships |
+| Legal · financial · medical · consulting drafts | `domain-safety-disclaimer-*` | "Not legal/financial/medical advice" disclaimers; refuse diagnostic / dosage / specific tax positions |
+| Logs · exports | `domain-safety-logging-pii-floor` · `domain-safety-export-redact` | No raw PII in logs or exports; allowlist-driven structured fields only |
+
+## How the floor is enforced
+
+- Each rule declares `applies_to_user_types:` in frontmatter — rules load only when the matching user-type is active (forward-compatible with the user-types axis shipping in `step-9-user-types-axis`).
+- Each rule routes to `skill:privacy-review` as the baseline deeper-regime check (GDPR · CCPA · HIPAA).
+- The set is opt-in by domain, never overrides higher Iron Laws (`non-destructive-by-default`, `commit-policy`, `scope-control`).
+
+## Related skills
+
+- [`privacy-review`](../.agent-src.uncompressed/skills/privacy-review/SKILL.md) — end-to-end data-flow review for a regulatory regime (GDPR / CCPA / HIPAA).
+- [`data-handling-judgment`](../.agent-src.uncompressed/skills/data-handling-judgment/SKILL.md) — classification, retention, cross-border transfer, DSR workflow.
+
+## See also
+
+- [`non-destructive-by-default`](../.augment/rules/non-destructive-by-default.md) — Hard Floor that overrides every domain-safety carve-out.
+- [`security-sensitive-stop`](../.augment/rules/security-sensitive-stop.md) — threat-model before touching auth / billing / tenant boundaries / uploads.

package/package.json

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