@event4u/agent-config 9.8.0 → 9.10.0

package/CONTRIBUTING.md

@@ -235,13 +235,12 @@ The setting flip is the easy part. Before enabling it, confirm:
 ## Installer and Python tooling
 
 - Primary installer entry point: `scripts/install` (bash orchestrator).
-  It chains `scripts/install.sh` (payload sync) and `scripts/install.py`
-  (bridge files). `bin/install.php` and `scripts/postinstall.sh` are
-  thin wrappers that route through the orchestrator.
+  It chains `scripts/install.sh` (payload sync) and `scripts/install.ts`
+  (bridge files; run via the bundled `dist/install/install.mjs`).
 - Each stage stays independently callable (`bash scripts/install.sh`,
-  `python3 scripts/install.py`) and has its own CLI.
-- Python scripts must work on Python 3.10+ with only the standard library.
-  No third-party runtime dependencies.
+  `npx tsx scripts/install.ts`) and has its own CLI.
+- The retired Python installer is gone (ADR-200); no Python runtime is
+  required anywhere on the install path.
 - Add integration tests to `tests/test_install.sh` (payload sync) or
   `tests/test_install_orchestrator.sh` (orchestrator + wrappers), and
   Python unit tests under `tests/`.
@@ -314,6 +313,11 @@ which never reach a consumer.
 > recovery — live in [`docs/release-runbook.md`](docs/release-runbook.md), with
 > the secret/operator-gated dependencies in [`docs/succession.md`](docs/succession.md).
 > The summary below is orientation; the runbook is the source of truth.
+>
+> **Cadence contract:** release *types* (security patch anytime · minors
+> batched ~weekly · breaking rare + migration note) and the `latest`/`next`
+> dist-tag split are pinned in [`docs/releases.md`](docs/releases.md); the
+> publish workflow routes by version shape.
 
 Releases are driven by a single command that owns the entire pipeline from
 version bump to npm publish:
@@ -413,6 +417,16 @@ asserts agreement with the README. **Never edit Topics, description,
 or homepage in the GitHub UI** — those edits are overwritten on the
 next sync.
 
+Changing the manifests in a PR is allowed and expected: the
+`check-visibility-drift` workflow recognizes a PR whose net diff
+touches `topics.yml` / `about.yml` as an **intentional pending
+change** and reports the remote diff in advisory mode instead of
+failing. Strict failure is reserved for the weekly sweep, manual
+dispatch, and tooling-only PRs — there, observed drift means someone
+edited the GitHub UI directly. After the PR merges, a maintainer
+applies the pending change once via `sync-visibility.yml`
+(`workflow_dispatch`, `dry_run=false`).
+
 Sources of truth:
 
 - [`.github/topics.yml`](.github/topics.yml) — the topic list +
@@ -431,7 +445,9 @@ Tooling:
   `npm prepack` so every published tarball carries the manifest.
 - `task lint-mcp-registry-manifest` — schema + payload-shape gate.
 - `task lint-positioning` — asserts the README H1 anchor
-  (*"Universal AI Agent OS"*) appears in `package.json.description`
+  (the text after the em-dash in the README H1, currently *"every
+  claim machine-checked, including \"zero runtime daemon\""*) appears
+  in `package.json.description`
   and `.github/about.yml`, and that every topic in
   `.github/topics.yml` is discoverable in the README body (literal
   or via the optional `equivalents:` map).

package/MIGRATION.md

@@ -1,3 +1,23 @@
+# Migrating past 9.8 — scoped projection is the default for NEW installs
+
+`projection.mode` in the settings template flipped from `legacy-all` to
+`scoped` (road-to-credible-install Phase 2). What this means:
+
+- **Fresh installs** project only the engineering surface: the active
+  profile's packs (default `developer` → `engineering-base` + always-on
+  `meta`), expanded over the `requires` graph. Creative/media/fun packs are
+  opt-in.
+- **Existing installs are untouched.** Your `.agent-settings.yml` is never
+  rewritten on update, and a *missing* `projection.mode` key still means
+  `legacy-all` — upgrades preserve your prior mode.
+- **Full catalog back in one step:** set `projection.mode: legacy-all` in
+  `.agent-settings.yml` (or pick a broader profile / add packs via
+  `agent-config use --profile=<id>` and the `runtime.active_packs` overlay).
+
+Escalation rule (pre-registered): if this flip breaks a documented consumer
+contract or CI gate, the flip stops and goes back to a council round
+(potential lock-revisit) instead of being forced.
+
 # Migrating off the Claude Code marketplace plugin (single-surface model)
 
 The marketplace plugin for Claude Code is deprecated. The npx/npm global

package/README.md

@@ -2,7 +2,9 @@
 
 # Agent Config — every claim machine-checked, including "zero runtime daemon"
 
-[![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config)
+[![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config) [![MCP Toplist](https://mcptoplist.com/badge/glama%2Fevent4u-app%2Fagent-config.svg)](https://mcptoplist.com/server/glama%2Fevent4u-app%2Fagent-config)
+
+[![Skills](https://img.shields.io/badge/Skills-286-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-111-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-191-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-101-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
 
 **Try it in 30 seconds** — drop one read-only subagent into any repo and watch it gate "done": `@production-validator check this branch is actually done`. No wizard, no lock-in, nothing else installed — the [30-second wedge ↓](#quickstart) is the whole first step. Start at the proof, not the catalog: **[event4u-app.github.io/agent-config/proof/](https://event4u-app.github.io/agent-config/proof/)**.
 
@@ -12,8 +14,6 @@
 
 > **Choose your experience — developer · founder · content · agency · finance · ops. Add packs. Get a focused command set, not a 500-artefact dump.** Bring your own AI provider.
 
-[![Skills](https://img.shields.io/badge/Skills-281-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-107-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-190-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-101-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
-
 **A deep library of skills, commands and governed rules** — plus a capability router that loads the right skill on intent and multi-agent orchestration with consensus review. The whole layer is compiled into **20 host agents** — of 23 detected, 3 being export-only<!-- claim:host-agent-count --> (Claude Code, Cursor, Augment, Cline, Windsurf, Copilot, Gemini CLI, Codex, Continue, Zed, JetBrains, Aider and more) — with **zero runtime daemon**.<!-- claim:no-runtime-daemon --> Six role-shaped entry paths sit on top, so any host becomes a reliable team member — without locking you to a single model or vendor.
 
 ### What's different
@@ -25,7 +25,7 @@ It is both deep **and** disciplined — and honest about what it deliberately is
 - **Surgical uninstall** — removes only its own keys from a shared host config (matched by JSON-pointer + SHA-256), never a neighbour tool's entries.<!-- claim:surgical-uninstall -->
 - **Pack-scoped install** — writes the active pack only, not a 500-artefact dump.
 
-**What it deliberately is *not*** — a content + governance layer, not a runtime: **no background daemon, no separate state database, no self-rewriting memory, no auto-build pipeline.** The host agent runs the loop; every learned change is human-reviewed; the same layer stays portable across tools. Capability without a process to babysit.
+**What it deliberately is *not*** — the core is a governance layer with optional, individually opt-in embedded engines (code intelligence, gated reach, the setup GUI, the bench lab — [ADR-124](docs/decisions/ADR-124-embedded-engine-doctrine.md)): **no background daemon, no separate state database, no self-rewriting memory, no auto-build pipeline.** Engines are never mandatory, never default-on without measured lift, and terminate with the command that invoked them. The host agent runs the loop; every learned change is human-reviewed; the same layer stays portable across tools. Capability without a process to babysit.
 
 > **Where this comes from (honest provenance).** The skills, rules and personas
 > are distilled from real production work on TypeScript and PHP codebases. The
@@ -170,7 +170,7 @@ full suite:
 
 ```bash
 # 1. Install — on a terminal with a display, the browser wizard launches
-#    automatically; the same install.py runs the real install behind it.
+#    automatically; the same TypeScript installer runs the real install behind it.
 npx -y @event4u/agent-config init
 
 # 2. Pick your profile + tools in the wizard, click Finish.
@@ -180,7 +180,7 @@ npx -y @event4u/agent-config init
 /work "your first real task"
 ```
 
-**Headless / CI:** `init` skips the GUI automatically when `CI` is set, stdout is not a TTY, `--no-ui` is passed, **or** an explicit `--tools=` selection is given — it then runs the non-interactive installer directly. Pass flags (`--profile=developer --tools=claude-code,cursor`); add `--dry-run` to preview writes. The GUI and the CLI share one installer (`scripts/install.py`), so both produce identical results. Reference: [`docs/wizard.md`](docs/wizard.md).
+**Headless / CI:** `init` skips the GUI automatically when `CI` is set, stdout is not a TTY, `--no-ui` is passed, **or** an explicit `--tools=` selection is given — it then runs the non-interactive installer directly. Pass flags (`--profile=developer --tools=claude-code,cursor`); add `--dry-run` to preview writes. The GUI and the CLI share one installer (`scripts/install.ts`), so both produce identical results. Reference: [`docs/wizard.md`](docs/wizard.md).
 
 **Pick specific AIs:** `--tools=claude-code,cursor,augment,windsurf,cline,gemini-cli,copilot,roocode,aider,codex,claude-desktop,continue` (any subset). Visual picker: add `--gui` (loopback-bound, CSRF-gated; contract [`gui-wizard`](docs/contracts/gui-wizard.md)).
 
@@ -414,6 +414,21 @@ For platforms where the package's scripts cannot run, artefacts are built for pa
 
 ---
 
+## Works with agent-switch
+
+[`agent-switch`](https://github.com/event4u-app/agent-switch) is the companion
+CLI for running several agent accounts on one machine: it isolates each account
+in its own profile (`CLAUDE_CONFIG_DIR` per profile), so switching accounts
+never means logging out and back in. The two compose — **agent-switch isolates
+the accounts, agent-config governs what the agents do inside them**. When
+agent-config runs under an agent-switch profile it says so in the settings hub,
+warns before writes that would land in a shared (cross-profile) tree, and
+accepts a host-supplied config root so its own settings stay profile-scoped.
+
+→ [How the two compose →](docs/guides/works-with-agent-switch.md)
+
+---
+
 ## Who this is for
 
 Stack-agnostic governance core (orchestration · role modes · command clusters · quality gates · audit-discipline) plus parallel stack-specific skill sets:
@@ -438,6 +453,20 @@ The same orchestration core drives non-software trades via [`user-types/`](src/a
 
 Three domain-safety rules ([`domain-safety-pii`](src/rules/domain-safety-pii.md), [`domain-safety-disclaimer`](src/rules/domain-safety-disclaimer.md), [`domain-safety-retention`](src/rules/domain-safety-retention.md)) act as per-domain output floors across ~12 areas — PII redaction (support / finance / recruiting / marketing), advice disclaimers (legal / financial / medical / consulting), retention guidance (finance / support), ops floors (logging / export). Full surface → rule → floor matrix: [`docs/safety.md`](docs/safety.md). Beta contracts: [`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) · [`decision-trace-v1`](docs/contracts/decision-trace-v1.md).
 
+### Code provenance & license governance
+
+Every diff is checked against a **license policy derived from the target repo's own detected license** (`LICENSE`/`package.json`/`composer.json`, precedence-ordered; sources disagree → escalate, never guess) and a **strict linter over our own borrow ledger** ([`provenance/borrows.jsonl`](provenance/) → [`docs/THIRD-PARTY-NOTICES.md`](docs/THIRD-PARTY-NOTICES.md)) that fails a deny-class license, an unknown license, a missing transformation note or a rename-only-phrased one — wired into `ci`/`ci-strict` from day one. A third piece, `license-compliance-audit`, runs an offline/online similarity scan on demand — a human invokes it deliberately, never a pipeline. This is **provenance-governed**, **license-policy-enforced** borrow discipline backed by an **audited borrow trail** — not a copy detector.
+
+<!-- provenance-scope-box -->
+#### Scope & limits
+
+- **Unconscious training-data reproduction is not detectable at this layer.** No tool here — or anywhere — can see what a model's training data contained; this system governs what gets consciously borrowed and recorded, never what a model silently recalls.
+- **Detection, where it exists, covers a knowledge base of known OSS only** — a subset of all code that has ever existed, never a model's training corpus.
+- **No CI-facing detection gate exists.** A deterministic scanner (jscpd offline + SCANOSS online) was built and measured against a frozen synthetic corpus, but missed its own pre-registered thresholds (measured: recall 12/16, false positives 2/12, SCANOSS rename-only recall 0/8) — see [`docs/CLAIMS.md`](docs/CLAIMS.md#claim-provenance-gate-effectiveness). It ships in **no form** in CI, not even advisory — only as the on-demand skill above.
+- **Rename-only laundering is not detected** by anything we ship or evaluated. The ledger's transformation-note check rejects a rename-only-*phrased* note, but it cannot catch an undisclosed rename-only copy that was never logged.
+
+Reduces and documents risk — never eliminates it.
+
 ### Maintainer telemetry (opt-in, default-off)
 
 Local-only artefact-engagement log. Set `telemetry.artifact_engagement.enabled: true` in `.agent-settings.yml`. Records which skills / rules / commands / guidelines the agent consults during `/implement-ticket` / `/work`. JSONL under the project root, nothing uploaded. Reports: `npx @event4u/agent-config telemetry:report`.
@@ -568,10 +597,27 @@ task dev:setup        # boot the onboarding wizard against the working tree
 
 ## Requirements
 
-- **Node ≥ 18** — `npx @event4u/agent-config init` is the canonical install path.
-- **Python 3.10+** — bridge stage only; missing → installer skips bridges.
-- **Platform:** macOS 12.3+, Linux, WSL2. Git Bash needs Developer Mode for symlinks; native PowerShell / cmd unsupported. Contributors rebuilding `.augment/` also need [Task](https://taskfile.dev/).
+- **Node ≥ 20.11** — `npx @event4u/agent-config init` is the canonical install path. No Python anywhere on the install path (the Python installer retired with the TypeScript migration).
+- **Platform:** macOS 12.3+, Linux, WSL2. Git Bash needs Developer Mode for symlinks. Contributors rebuilding `.augment/` also need [Task](https://taskfile.dev/).
+
+### Windows
+
+Native PowerShell / cmd is **not supported for the file install** — use WSL2
+for the full installed tree. The supported native-Windows surface is the
+**MCP stdio server**: point any MCP client at
+
+```bash
+npx -y @event4u/agent-config mcp-server
+```
+
+and the governance content (prompts, resources, tools) is available without
+the file install. Porting the bash dispatcher to native Windows is
+**demand-gated**: a named Windows adopter who cannot use WSL2 or the MCP
+path reopens it (see `agents/roadmaps/` — road-to-credible-install Phase 3).
 
 ## License
 
 [MIT](LICENSE).
+
+<!-- Official MCP Registry package validation marker -->
+mcp-name: io.github.event4u-app/agent-config

package/dist/agent-src/commands/agent-status.md

@@ -57,9 +57,9 @@ the last record from `agents/cost-tracking/sessions.jsonl`. If the file
 does not exist (tracker never run for this project), skip this step and
 note `cost ledger: not initialised` in the dashboard.
 
-Extract from latest record:
+Extract from the latest record:
 
-- `total_usd` — dollars spent in current session
+- `total_usd` — dollars spent in the current session
 - `by_model[]` — per-tier (haiku / sonnet / opus) input / output / cache split
 - `budget.tier` — `under` / `50` / `75` / `90` / `100` (from `node scripts/cost/budget.mjs check`)
 
@@ -68,19 +68,20 @@ implementation: [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs).
 
 ### 3b. Read telegraph delta + per-conversation cost lens
 
-Run two read-only Python helpers (stdlib-only, no-op safe if JSONL missing):
+Run two read-only Python helpers (both stdlib-only, both no-op safe if the
+JSONL is missing):
 
 - `./scripts-run src/scripts/telegraph_stats --format json` — per-session +
-  per-conversation + lifetime telegraph delta. Honors suspended
-  multiplier (see [`docs/contracts/telegraph-telemetry.md`](../docs/contracts/telegraph-telemetry.md)) — delta reads `0` while suspended; display version + ACTIVE/SUSPENDED state regardless.
+  per-conversation + lifetime telegraph delta. Honors the suspended
+  multiplier (see [`docs/contracts/telegraph-telemetry.md`](../docs/contracts/telegraph-telemetry.md)) — delta reads `0` while suspended; display the version + ACTIVE/SUSPENDED state regardless.
 - `./scripts-run src/scripts/cost_by_conversation --format json` — per-conversation
-  total cost + model breakdown for current conversation, sourced
-  from same `agents/cost-tracking/sessions.jsonl` ledger.
+  total cost + model breakdown for the current conversation, sourced
+  from the same `agents/cost-tracking/sessions.jsonl` ledger.
 
-Surface in dashboard as one line:
+Surface in the dashboard as one line:
 `[telegraph: {lifetime.delta_tokens:+,} tok lifetime · {current_conv.delta_tokens:+,} this conv · multiplier v{multiplier_version} {ACTIVE|SUSPENDED}] · [conv cost: ${current_conv.total_cost_usd:.4f}]`.
 
-If both JSONLs missing or empty, omit line silently.
+If both JSONLs are missing or empty, omit the line silently.
 
 ### 4. Calculate freshness thresholds
 
@@ -113,7 +114,7 @@ Use Markdown tables and headings — NOT ASCII box art (breaks in non-monospace
 
 **💵 Session cost (measured)**
 
-If ledger exists, render:
+If the ledger exists, render:
 
 | | |
 |---|---|
@@ -122,7 +123,7 @@ If ledger exists, render:
 | 🎯 Budget tier | {emoji} {tier} ({utilization_pct}% of cap) |
 
 Tier-emoji map: `under` / `50` → ✅ · `75` → ⚠️ · `90` → ⚠️⚠️ · `100` → ❌.
-If ledger does not exist, render `Session cost: not initialised — run \`task cost:track\` to start measuring`.
+If the ledger does not exist, render `Session cost: not initialised — run \`task cost:track\` to start measuring`.
 
 **⚡ Freshness**
 

package/dist/agent-src/commands/agents/audit.md

@@ -25,7 +25,7 @@ duplicate triggers, verifies the Thin-Root contract, and flags stale references.
 **Suggest only — never auto-apply.** Fixes happen via `/agents optimize` (file
 refactor) or rule-/skill-level commands.
 
-**Source of truth:** `.agent-src.uncondensed/` — never read or edit
+**Source of truth:** `src/` — never read or edit
 `dist/agent-src/` or `.augment/` directly.
 
 ## Steps

package/dist/agent-src/commands/agents/optimize.md

@@ -54,7 +54,7 @@ Default: the AGENTS.md the user is editing right now. If unclear,
 ask:
 
 > 1. project root — `AGENTS.md`
-> 2. consumer template — `.agent-src.uncondensed/templates/AGENTS.md`
+> 2. consumer template — `src/agent-src/templates/AGENTS.md`
 > 3. package root — `AGENTS.md` of `event4u/agent-config` itself
 > 4. monorepo package — `<path>/AGENTS.md` (specify path)
 
@@ -170,7 +170,7 @@ final reply per
 ## What this command does NOT do
 
 - **No edits to** `.augment/` **or** `dist/agent-src/` — those regenerate
-  from `.agent-src.uncondensed/`. Edit the source.
+  from `src/`. Edit the source.
 - **No commits, no push, no PR** — finishing the refactor is a user
   decision; cite [`commit-policy`](../../rules/commit-policy.md).
 - **No broader agent-infra audit** — for token overhead, rule

package/dist/agent-src/commands/agents/user/accept.md

@@ -7,7 +7,7 @@ visibility: internal
 cluster: agents
 sub: user
 skills: [agents]
-description: Apply a buffered observation to .agent-user.md after explicit user confirmation; bumps last_updated and drops the applied observations from the buffer.
+description: Apply a buffered observation to .agent-user.md or the global profile.md after explicit user confirmation; bumps last_updated and drops the applied observations from the buffer.
 argument-hint: "[field]"
 suggestion:
   eligible: false
@@ -20,9 +20,16 @@ packs:
 
 # /agents user accept
 
-Apply a buffered observation from
-[`.agent-user.observations.jsonl`](../../../../../docs/contracts/agent-user-schema.md#observation-buffer)
-to `.agent-user.md` after explicit confirmation.
+Apply a buffered observation from either
+[the project-local or the global observation buffer](../../../../../docs/contracts/agent-user-schema.md#observation-buffer)
+to the matching profile file — `.agent-user.md` for a project-local
+observation, the global `~/.event4u/agent-config/user/profile.md` for a
+global one (ADR-138, road-to-global-user-memory Phase 2) — after
+explicit confirmation.
+
+This is the **only** step in the learning channel that writes a profile
+file. Everything upstream (the miner, the buffers, `/agents user review`)
+only ever proposes.
 
 Use when:
 
@@ -40,34 +47,77 @@ ls .agent-user.md 2>/dev/null
 ls .agent-user.observations.jsonl 2>/dev/null
 ```
 
-Either missing → print "Run `/agents user init` and accumulate
-observations first." and stop.
+Resolve the global buffer/profile paths via
+`user_global_observations.resolveGlobalObservationsPath()` /
+`agent_user_profile.resolveGlobalProfilePath()`.
+
+Both the project-local file/buffer AND the global profile/buffer
+missing → print "Run `/agents user init` and accumulate observations
+first." and stop. Otherwise proceed with whichever layer(s) have a
+buffered observation.
 
-### 2. Resolve target field
+### 2. Resolve target field + layer
 
-| Invocation | Resolved field |
+| Invocation | Resolved field + layer |
 |---|---|
-| Handed off from `/agents user review` option 1 | The most-frequent field |
-| `/agents user accept <field>` | `<field>` (must match the schema enum) |
-| `/agents user accept` with no arg | Print the field list, ask which |
+| Handed off from `/agents user review` option 1 | The most-frequent field, with the layer `review` reported it under |
+| Handed off from `/agents user review` option 4 (a promotion candidate) | The candidate's `suggest` text, layer `global` — see § 2b below, skip straight to step 4 with the promotion framing |
+| `/agents user accept <field>` | `<field>` (must match the schema enum); if both layers have an observation for it, ask which layer |
+| `/agents user accept` with no arg | Print the field list (both layers), ask which |
 
 Invalid field → print the schema enum and stop.
 
-### 3. Compute proposed change
+### 2b. Promotion candidates need a `promotion_reason` (road-to-global-user-memory Phase 3)
+
+A candidate handed off from review option 4 has `seen_count ≥ 3` and a
+`seen_in[]` project list — human-confirmed recurrence across that many
+DIFFERENT projects (per
+[`findPromotionCandidates`](../../../../../src/scripts/_lib/user_global_observations.ts)).
+Crossing that threshold is candidacy only; it never auto-promotes
+(mirroring ADR-121's rule that a knowledge card has no auto-`shareable`
+path). Before step 4's confirmation, collect one additional line from the
+user:
+
+```
+This observation recurred in {seen_count} projects: {seen_in joined by ", "}.
+
+Why should this generalise to your global profile?
+> {free-text promotion_reason — required, no default}
+```
 
-For the resolved field:
+An empty answer is not accepted — re-ask once, then fall back to
+"Cancel" if the user still declines to give a reason. The
+`promotion_reason` is shown in step 4's confirmation block (below) but is
+**never written to `profile.md`** — see § 3 write below; it exists to make
+the human's judgment call visible in this transcript, not to persist
+alongside the fact.
 
-1. Read every matching observation from the buffer.
-2. Pick the **latest** `suggest` value (most recent `ts` wins).
-3. Read the current value from `.agent-user.md`.
+### 3. Compute proposed change
+
+For the resolved field + layer — or, for a promotion candidate (§ 2b),
+the single matched buffer entry:
+
+1. Read every matching observation from that layer's buffer only —
+   `.agent-user.observations.jsonl` for `project`,
+   `user_global_observations.readGlobalObservations()` for `global`.
+2. Pick the **latest** `suggest` value (most recent `ts` wins). For a
+   promotion candidate, the proposed value is
+   [`promotionValueFor(candidate)`](../../../../../src/scripts/_lib/user_global_observations.ts) —
+   the fact text ONLY, never the `context` or `seen_in` metadata attached
+   to it.
+3. Read the current value from that layer's profile file
+   (`.agent-user.md` or the global `profile.md`) — NOT the merged
+   effective value, so the confirmation shows exactly what this layer
+   will change.
 4. If they match, print "No change — current value already matches
    the latest observation." and skip to step 6.
 
 ### 4. Confirm
 
 ```
-Apply this change to .agent-user.md?
+Apply this change to {.agent-user.md | the global profile}?
 
+  layer   : {project | global}
   field   : {field}
   current : "{current_value}"
   proposed: "{proposed_value}"
@@ -76,7 +126,15 @@ Apply this change to .agent-user.md?
 
 > 1. Apply
 > 2. Skip — keep current value, drop these observations from the buffer
-> 3. Cancel — leave .agent-user.md and buffer untouched
+> 3. Cancel — leave the profile and buffer untouched
+```
+
+For a promotion candidate, append two lines above `> 1. Apply` instead of
+`source`/`evidence`:
+
+```
+  seen in : {seen_count} projects ({seen_in joined by ", "})
+  reason  : "{promotion_reason from § 2b}"
 ```
 
 One question per turn. Wait for the user's number.
@@ -85,24 +143,40 @@ One question per turn. Wait for the user's number.
 
 On `1. Apply`:
 
-1. Rewrite the targeted field in `.agent-user.md` frontmatter.
-   Preserve every other field byte-for-byte (use a YAML round-trip
-   loader that keeps formatting).
-2. Bump `last_updated` to today (ISO `YYYY-MM-DD`).
-3. Validate the result: schema present, ≤100 lines, privacy floor
-   clean. Any violation → roll back and print the error.
-4. Drop **all** applied observations for that field from the buffer
-   (rewrite the JSONL minus matching lines).
-
-On `2. Skip`: leave `.agent-user.md` untouched but still drop the
-observations for that field from the buffer.
+- **`project` layer:** rewrite the targeted field in `.agent-user.md`
+  frontmatter, preserving every other field (a YAML round-trip loader
+  that keeps formatting), bump `last_updated` to today (ISO
+  `YYYY-MM-DD`), validate ≤100 lines + privacy floor clean — any
+  violation rolls back and prints the error.
+- **`global` layer:** call
+  [`applyObservationToGlobalProfile(field, value, { today })`](../../../../src/scripts/_lib/agent_user_profile.ts) —
+  it round-trips the existing `profile.md` (or starts from empty),
+  sets the field, bumps `last_updated`, and throws (never partially
+  writes) if the result would exceed the global layer's own 100-line
+  cap. A thrown error is the roll-back signal — print it and stop. For a
+  promotion candidate, `value` is `promotionValueFor(candidate)` — the
+  `promotion_reason` collected in § 2b is shown in step 4's confirmation
+  only; it is **never** passed to `applyObservationToGlobalProfile` and
+  never appears in `profile.md`, alongside `context`/`seen_in`, which are
+  likewise never written. This is the only generalisation path, and it
+  leaves the durable profile with zero project references (see
+  [`agent-user-schema.md § Project attribution`](../../../../../docs/contracts/agent-user-schema.md#project-attribution-road-to-global-user-memory-phase-3)).
+
+Either layer: drop **all** applied observations for that field from
+**that layer's own buffer only** (rewrite the JSONL minus matching
+lines) — never touch the other layer's buffer. For a promoted candidate,
+this drops only the ONE matched buffer entry (identified in § 2b), not
+every `notes`-field entry in the buffer.
+
+On `2. Skip`: leave the profile untouched but still drop the
+observations for that field from that layer's buffer.
 
 On `3. Cancel`: stop without any write.
 
 ### 6. Confirm
 
 ```
-✅  .agent-user.md updated ({field}: "{old}" → "{new}", last_updated: YYYY-MM-DD).
+✅  {layer} profile updated ({field}: "{old}" → "{new}", last_updated: YYYY-MM-DD).
    Buffer: {n} observations removed, {m} remaining.
 ```
 
@@ -115,11 +189,22 @@ Do NOT commit. Do NOT auto-chain to a second field.
 - Never write without explicit confirmation in step 4.
 - Never bypass the privacy-floor scan, even if the buffer writer
   already redacted.
+- Never write to the layer the observation did NOT come from — an
+  observation buffered as `global` writes `profile.md`, never
+  `.agent-user.md`, and vice versa.
+- Never accept a promotion candidate without a non-empty
+  `promotion_reason` (§ 2b) — a `seen_count ≥ 3` tally is candidacy, not
+  authorization.
+- Never write `context` or `seen_in` to `profile.md` — a promotion writes
+  `promotionValueFor(candidate)`, the fact text only.
 - Mirror the user's language for prompts per
   [`language-and-tone`](../../../../dist/agent-src/rules/language-and-tone.md).
 
 ## See also
 
 - Schema + buffer contract: [`agent-user-schema § Observation buffer`](../../../../../docs/contracts/agent-user-schema.md#observation-buffer).
+- Project attribution + promotion: [`agent-user-schema § Project attribution`](../../../../../docs/contracts/agent-user-schema.md#project-attribution-road-to-global-user-memory-phase-3).
+- Global write primitive: [`agent_user_profile.applyObservationToGlobalProfile`](../../../../src/scripts/_lib/agent_user_profile.ts).
+- Promotion primitives: [`findPromotionCandidates`, `promotionValueFor`](../../../../../src/scripts/_lib/user_global_observations.ts).
 - Parent: [`/agents user`](../user.md).
 - Sibling: [`/agents user review`](review.md), [`/agents user update`](update.md).