@event4u/agent-config 9.9.0 → 9.10.0

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).

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

@@ -0,0 +1,147 @@
+---
+model_tier: medium
+name: agents-user-delete
+pack: meta
+tier: 2
+visibility: internal
+cluster: agents
+sub: user
+skills: [agents]
+description: Delete one buffered global observation, purge every observation attributed to a project, or revoke a field from the global profile.md — each writes an append-only tombstone before deleting.
+argument-hint: "[observation <id> | project <path> | profile-field <field>]"
+suggestion:
+  eligible: false
+  rationale: "Mutates the global observation buffer or profile.md — only run from /agents user review, /agents user show --audit, or explicit user invocation."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /agents user delete
+
+Delete something the learning channel wrote to the **global** layer —
+road-to-global-user-memory Phase 4, the delete counterpart of
+[`/agents user accept`](accept.md). Every deletion writes an
+append-only tombstone to the revocation ledger BEFORE the underlying
+file is rewritten without it — see
+[`agent-user-schema § Delete, revoke, and audit`](../../../../../docs/contracts/agent-user-schema.md#delete-revoke-and-audit-road-to-global-user-memory-phase-4).
+
+Three targets, one per invocation:
+
+| Target | Removes | Backing function |
+|---|---|---|
+| `observation <id>` | ONE buffered line from `observations.jsonl` | [`deleteGlobalObservation`](../../../../../src/scripts/_lib/user_global_observations.ts) |
+| `project <path>` | EVERY observation attributed (`context.project_path`) to that project | [`purgeProjectContext`](../../../../../src/scripts/_lib/user_global_observations.ts) |
+| `profile-field <field>` | A field's value from the global `profile.md` | [`revokeGlobalProfileField`](../../../../../src/scripts/_lib/agent_user_profile.ts) |
+
+Use when:
+
+- [`/agents user show --audit`](show.md) or
+  [`/agents user review`](review.md) surfaced something the user wants
+  gone.
+- A project was deleted and its buffered facts should not linger
+  forever (`project <path>`).
+- A promoted or accepted profile field turned out to be wrong
+  (`profile-field <field>`).
+
+Never runs autonomously — always asks before writing, exactly like
+`accept`.
+
+## Steps
+
+### 1. Resolve the target
+
+| Invocation | Target |
+|---|---|
+| `/agents user delete observation <id>` | The buffered observation whose `observationId` equals `<id>` (shown by `/agents user show --audit` or `/agents user review`) |
+| `/agents user delete project <path>` | Every observation whose `context.project_path` equals `<path>` |
+| `/agents user delete profile-field <field>` | `<field>` in the global `profile.md` (must match the schema enum) |
+| No argument | Print the target-kind table above and ask which; then ask for the id/path/field |
+
+Invalid `<field>` → print the schema enum and stop. No observation
+matches `<id>` → print "No buffered observation with that id." and
+stop (no tombstone is written for a no-op — see the backing functions'
+`deleted: false` / `purgedCount: 0` contract).
+
+### 2. Confirm
+
+```
+Delete this from the global user-memory layer?
+
+  target : {observation <id> | project <path> | profile-field <field>}
+  current: {for profile-field — the current value; for observation/project — the suggest text(s) that will be removed}
+
+> 1. Delete — write a tombstone, then remove
+> 2. Cancel — leave everything untouched
+```
+
+For `project <path>`, list every matched observation's `suggest` text
+before asking, so the user confirms the actual scope, not just a count.
+
+One question per turn. Wait for the user's number.
+
+### 3. Ask for a reason
+
+```
+Why is this being deleted? (one line, becomes the tombstone's `reason`)
+> {free-text reason}
+```
+
+An empty answer is not accepted — re-ask once, then default to `"no
+reason given"` if the user still declines (mirrors
+[`user_global_revocations.appendTombstone`](../../../../../src/scripts/_lib/user_global_revocations.ts)'s
+own fallback, so a user who truly has nothing to say is never blocked).
+
+### 4. Write
+
+On `1. Delete`, call the matching function with today's date and the
+step-3 reason:
+
+- `observation <id>` →
+  [`deleteGlobalObservation(id, reason, { today })`](../../../../../src/scripts/_lib/user_global_observations.ts).
+- `project <path>` →
+  [`purgeProjectContext(path, reason, { today })`](../../../../../src/scripts/_lib/user_global_observations.ts).
+- `profile-field <field>` →
+  [`revokeGlobalProfileField(field, reason, { today })`](../../../../../src/scripts/_lib/agent_user_profile.ts).
+
+Each function writes its tombstone(s) BEFORE the buffer/profile
+rewrite — never call `fs`/the file directly from this command; always
+go through the function so the tombstone-before-delete order holds.
+
+On `2. Cancel`: stop without any write, without any tombstone.
+
+### 5. Confirm
+
+```
+✅  Deleted ({target}). Tombstone recorded: {entity_id}, {revoked_at}.
+```
+
+For `project <path>`, report the count: `✅  Purged {n} observation(s) from {path}. {n} tombstone(s) recorded.`
+
+Do NOT commit. Do NOT auto-chain to a second deletion.
+
+## Rules
+
+- One target per invocation. Run the command again for the next
+  deletion.
+- Never delete without explicit confirmation in step 2 and a reason
+  from step 3.
+- Never write to a file directly — every deletion goes through
+  `deleteGlobalObservation`, `purgeProjectContext`, or
+  `revokeGlobalProfileField` so the tombstone always precedes the
+  delete.
+- Never touch project-local `.agent-user.md` or its buffer from this
+  command — this leaf covers the global layer only. A project-local
+  fact is deleted by editing `.agent-user.md` directly (it never left
+  the project) or via [`/agents user review`](review.md)'s existing
+  "clear a buffer" option.
+- Mirror the user's language for prompts per
+  [`language-and-tone`](../../../../dist/agent-src/rules/language-and-tone.md).
+
+## See also
+
+- Schema: [`agent-user-schema § Delete, revoke, and audit`](../../../../../docs/contracts/agent-user-schema.md#delete-revoke-and-audit-road-to-global-user-memory-phase-4) — the write→delete mapping and the ADR-121 reuse this command exposes.
+- Audit source: [`/agents user show --audit`](show.md) — the read surface that surfaces what there is to delete.
+- Parent: [`/agents user`](../user.md).
+- Sibling: [`/agents user review`](review.md), [`/agents user accept`](accept.md) — the write side this command undoes.

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

@@ -7,7 +7,7 @@ visibility: internal
 cluster: agents
 sub: user
 skills: [agents]
-description: List buffered observations from .agent-user.observations.jsonl with numbered options to inspect or accept individually.
+description: List buffered observations from the project-local and global observation buffers with numbered options to inspect or accept individually.
 suggestion:
   eligible: false
   rationale: "Cluster sub-command — reached via its cluster head's routing or its explicit /cluster:sub name; not independently suggested (surface-consolidation)."
@@ -19,14 +19,17 @@ packs:
 
 # /agents user review
 
-List the buffered observations in `.agent-user.observations.jsonl`
-and let the user choose which to inspect or accept.
+List the buffered observations across BOTH observation buffers —
+project-local `.agent-user.observations.jsonl` and the global
+`~/.event4u/agent-config/user/observations.jsonl` (ADR-138,
+road-to-global-user-memory Phase 2) — and let the user choose which to
+inspect or accept.
 
 Use when:
 
 - You want to see what the agent has learned about your preferences.
-- You suspect `.agent-user.md` is out of date and want a curated
-  diff before editing.
+- You suspect `.agent-user.md` (or the global `profile.md`) is out of
+  date and want a curated diff before editing.
 - You want to dismiss observations the agent collected.
 
 Read-only by itself — actual changes go through
@@ -35,57 +38,90 @@ Read-only by itself — actual changes go through
 
 ## Steps
 
-### 1. Locate buffer
+### 1. Locate buffers
 
 ```bash
 ls .agent-user.observations.jsonl 2>/dev/null
 ```
 
-| State | Action |
+Resolve the global buffer's path via `user_global_observations.
+resolveGlobalObservationsPath()` — it honours the config-home override
+env var and the legacy fallback root exactly like every other global
+artefact, so never hard-code either path here.
+
+| State (either buffer) | Action |
 |---|---|
-| Missing or empty | Print "No buffered observations. The agent has not learned anything new." and stop |
-| Present | Proceed |
+| Both missing or empty | Print "No buffered observations. The agent has not learned anything new." and stop |
+| At least one present | Proceed with whichever buffer(s) exist |
 
 ### 2. Parse + group
 
-Read every line as JSON. Drop malformed lines silently (one-line
-warning at the end with the count). Group by `field`:
+Read every line as JSON from BOTH buffers via
+[`user_global_observations.readGlobalObservations`](../../../../src/scripts/_lib/user_global_observations.ts)
+for the global one, and the equivalent tolerant parse for the
+project-local file. Drop malformed lines silently (one-line warning at
+the end with the combined count; `readGlobalObservations` already
+reports `droppedMalformed` / `droppedUnknownField`). Group by `field`
+ACROSS both buffers, tagging each observation with its layer:
 
 ```
-.agent-user.observations.jsonl — {n} observations across {k} fields
+Buffered observations — {n} across {k} fields ({p} project-local, {g} global)
 
   1. style.pace          ({n}× since {oldest_ts})
-     latest suggest: "rapid" — evidence: user said 'mach kürzer' 3× this session
+     latest suggest: "rapid" [global] — evidence: user said 'mach kürzer' 3× this session
   2. identity.nickname   ({n}× since {oldest_ts})
-     latest suggest: "Matze" — evidence: user signed last 3 messages "— Matze"
+     latest suggest: "Matze" [project] — evidence: user signed last 3 messages "— Matze"
   3. language            ({n}× since {oldest_ts})
-     latest suggest: "de" — evidence: last 12 messages in German, .agent-user.md says "en"
+     latest suggest: "de" [global] — evidence: last 12 messages in German, profile says "en"
+```
+
+Sort by frequency (most observations first, combined across both
+layers), then by recency. When the SAME field has observations in both
+layers, list the most-recent one first and note both counts.
+
+### 2a. Promotion candidates (road-to-global-user-memory Phase 3)
+
+Separately from the field grouping above, call
+[`findPromotionCandidates`](../../../../../src/scripts/_lib/user_global_observations.ts)
+over the global buffer's entries. Any observation with `seen_count ≥ 3`
+(`PROMOTION_SEEN_COUNT_THRESHOLD`) is project-attributed, human-confirmed
+recurring evidence across that many DIFFERENT projects — surface it as
+its own block, ahead of the field list:
+
+```
+Promotion candidates — seen in 3+ projects:
+
+  1. "always use pnpm instead of npm for installs" — seen in 3 projects (acme-web, acme-api, acme-mobile)
 ```
 
-Sort by frequency (most observations first), then by recency.
+This is candidacy only, never a promotion — crossing the threshold makes
+`/agents user accept` able to offer promoting it, nothing more (see
+[`agent-user-schema.md § Project attribution`](../../../../../docs/contracts/agent-user-schema.md#project-attribution-road-to-global-user-memory-phase-3)).
 
 ### 3. Ask
 
 ```
-> 1. Accept the most-frequent suggestion ({field} → {value})
+> 1. Accept the most-frequent suggestion ({field} [{layer}] → {value})
 > 2. Inspect a specific field
-> 3. Clear the buffer (discard all)
-> 4. Cancel
+> 3. Clear a buffer (project-local, global, or both)
+> 4. Promote a candidate from step 2a (only shown when ≥ 1 exists)
+> 5. Cancel
 ```
 
 | Choice | Action |
 |---|---|
-| 1 | Hand off to [`/agents user accept`](accept.md) with the chosen field |
-| 2 | Print every observation for that field with evidence + ts, then re-ask |
-| 3 | Truncate `.agent-user.observations.jsonl` to zero bytes; print confirmation |
-| 4 | Stop without changes |
+| 1 | Hand off to [`/agents user accept`](accept.md) with the chosen field AND layer |
+| 2 | Print every observation for that field (both layers) with evidence + ts, then re-ask |
+| 3 | Ask which buffer(s) to truncate, then truncate the chosen file(s) to zero bytes; print confirmation |
+| 4 | Hand off to [`/agents user accept`](accept.md) with the chosen promotion candidate — `accept` collects the mandatory `promotion_reason` before writing anything |
+| 5 | Stop without changes |
 
 One question per turn. Wait for the user's number.
 
 ### 4. Privacy-floor verify
 
 Before printing any observation's `evidence` text, scan it for the
-[exclusions list](../../../../../../../../docs/contracts/agent-user-schema.md#explicit-exclusions).
+[exclusions list](../../../../../docs/contracts/agent-user-schema.md#explicit-exclusions).
 Match → replace the offending substring with `[redacted]` in the
 rendered output.
 
@@ -100,14 +136,15 @@ turn.
 
 ## Rules
 
-- Read-only on `.agent-user.md`. Only `accept` writes to the persona
-  file.
-- Buffer is the only mutable artefact (truncate via option 3).
+- Read-only on `.agent-user.md` AND the global `profile.md`. Only
+  `accept` writes to either persona file.
+- Both buffers are the only mutable artefacts (truncate via option 3).
 - 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).
+- Schema + buffer contract: [`agent-user-schema § Observation buffer`](../../../../../docs/contracts/agent-user-schema.md#observation-buffer).
+- Global buffer implementation: [`user_global_observations.ts`](../../../../src/scripts/_lib/user_global_observations.ts).
 - Parent: [`/agents user`](../user.md).
 - Sibling: [`/agents user accept`](accept.md), [`/agents user update`](update.md).