@event4u/agent-config 1.38.0 → 1.40.0

package/.agent-src/commands/onboard.md

@@ -12,35 +12,68 @@ suggestion:
 
 # /onboard
 
-Centralized first-run flow. Bundles what used to be scattered "ask once"
-prompts (user_name, IDE, rtk install, cost profile, learning loop) into a
-single interactive setup. Ends by setting `onboarding.onboarded: true` in
-`.agent-settings.yml`.
+Centralized first-run flow. Bundles scattered "ask once" prompts (user_name,
+IDE, rtk install, cost profile, learning loop) into one interactive setup.
+Ends by setting `onboarding.onboarded: true` in `.agent-settings.yml`.
 
-Triggered by the [`onboarding-gate`](../rules/onboarding-gate.md) rule when
-`onboarding.onboarded` is `false` or by the user explicitly re-running it.
+Triggered by [`onboarding-gate`](../rules/onboarding-gate.md) when
+`onboarding.onboarded` is `false`, or by explicit re-run.
 
 ## When NOT to use
 
 - Change cost profile only → [`/set-cost-profile`](set-cost-profile.md).
-- Single-value edit → ask the agent to change it, or edit
-  `.agent-settings.yml` directly. The agent follows the merge rules in
-  [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md).
+- Single-value edit → ask agent to change it, or edit `.agent-settings.yml`
+  directly per [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md).
 
 ## Preconditions
 
-`.agent-settings.yml` exists. If missing, tell the user to run
-`scripts/install` (or `python3 scripts/install.py`) first and stop — this
-command assumes the file and its template-derived defaults are in place.
+`.agent-settings.yml` exists. If missing, tell user to run `scripts/install`
+(or `python3 scripts/install.py`) first and stop — command assumes file +
+template defaults are in place.
 
 ## Steps
 
 ### 1. Greet and set expectations
 
-Keep it short. One line explaining this is the one-time setup, six
-questions, one at a time, following the iron law (`user-interaction`).
+One line: one-time setup, six questions, one at a time (iron law from
+`user-interaction`).
 
-### 2. Capture `personal.user_name`
+### 2. Offer user-global cross-project defaults
+
+Detect whether `~/.config/agent-config/agent-settings.yml` exists. Path is
+XDG-style, matches existing `~/.config/agent-config/` dir used for
+`anthropic.key`, `openai.key`, `council-spend.jsonl`.
+
+- **File exists** → skip step entirely. Re-onboarding never overwrites
+  user-global file silently.
+- **File missing AND first-time setup heuristic** — heuristic for "first
+  machine setup": no other `.agent-settings.yml` in any sibling project on
+  disk. Conservative shell probe:
+  `find $(dirname "$PWD") -maxdepth 3 -name .agent-settings.yml 2>/dev/null | grep -v "^$PWD/" | head -1`
+  → non-empty → developer done this before, **skip**.
+  → empty → first-time setup, ask:
+
+```
+> A user-global config at ~/.config/agent-config/agent-settings.yml lets
+> you carry your DX-comfort defaults (name, IDE, autonomy, cost profile,
+> communication style) across every project that uses event4u/agent-config.
+>
+> Project-local .agent-settings.yml always wins. Only six keys are
+> mergeable from the user-global file:
+>   name · ide · cost_profile · personal.bot_icon · personal.autonomy · caveman.speak_scope
+>
+> 1. Yes — create it after this onboarding finishes
+> 2. No — keep settings project-local only
+```
+
+If user picks `1`, **defer write** to tail step (see step 9). Capture choice
+in working memory only; do **not** create file here. File gets written
+**after** project-local values are confirmed, so initial values mirror
+what developer just chose for this project.
+
+If user picks `2`, set working-memory flag to skip step 9.
+
+### 3. Capture `personal.user_name`
 
 Skip if already set (non-empty). Otherwise:
 
@@ -51,11 +84,11 @@ Skip if already set (non-empty). Otherwise:
 > 2. Skip — stay anonymous
 ```
 
-Free-text answer → write to `personal.user_name`. `2` → leave empty.
+Free-text → write to `personal.user_name`. `2` → leave empty.
 
-### 3. Capture `personal.ide` (with auto-detect)
+### 4. Capture `personal.ide` (with auto-detect)
 
-Skip if already set. Otherwise auto-detect first:
+Skip if set. Otherwise auto-detect first:
 
 ```bash
 ps aux | grep -iE '(Visual Studio Code|Code Helper|phpstorm|cursor)' | grep -v grep
@@ -73,13 +106,13 @@ ps aux | grep -iE '(Visual Studio Code|Code Helper|phpstorm|cursor)' | grep -v g
 > 4. Skip — I'll configure it later
 ```
 
-If IDE is set, also ask about `personal.open_edited_files` (`true`/`false`).
+If IDE set, also ask `personal.open_edited_files` (`true`/`false`).
 
-### 4. Capture `personal.pr_comment_bot_icon`
+### 5. Capture `personal.pr_comment_bot_icon`
 
-Personal preference — each developer decides how their own PR replies
-should look. Skip only if the user has already set a non-default value
-deliberately (agent can't tell, so always ask on first run):
+Personal preference — each developer decides how own PR replies look. Skip
+only if user already set non-default deliberately (agent can't tell, so
+always ask on first run):
 
 ```
 > When I reply to PR review comments on your behalf, should I prefix each
@@ -91,7 +124,7 @@ deliberately (agent can't tell, so always ask on first run):
 
 `1` → write `personal.pr_comment_bot_icon: true`. `2` → leave `false`.
 
-### 5. Detect `personal.rtk_installed`
+### 6. Detect `personal.rtk_installed`
 
 Silent `which rtk`.
 
@@ -108,16 +141,17 @@ Silent `which rtk`.
 ```
 
 `1` or `2` → run install, on success set `rtk_installed: true` and apply
-rtk post-install steps (telemetry off, init --global) per the
-[`rtk-output-filtering`](../skills/rtk-output-filtering/SKILL.md) skill.
-`3` → leave `rtk_installed: false` and move on. No "ask again tomorrow"
-logic — `/onboard` is one-shot.
+rtk post-install steps (telemetry off, init --global) per
+[`rtk-output-filtering`](../skills/rtk-output-filtering/SKILL.md).
+`3` → leave `rtk_installed: false`, move on. No "ask again tomorrow" —
+`/onboard` is one-shot.
+
 
-### 6. Confirm `cost_profile` and learning loop
+### 7. Confirm `cost_profile` and learning loop
 
 Read current `cost_profile` and `pipelines.skill_improvement` values.
-Present them plainly (they already have sensible defaults from the
-template — `minimal` + `skill_improvement: true`):
+Present plainly (sensible defaults from template — `minimal` +
+`skill_improvement: true`):
 
 ```
 > Cost profile: {current} (minimal by default — includes the learning loop)
@@ -128,16 +162,54 @@ template — `minimal` + `skill_improvement: true`):
 > 3. Disable learning loop — sets pipelines.skill_improvement=false
 ```
 
-`2` → defer to `/set-cost-profile` and return here. `3` → flip the toggle.
+`2` → defer to `/set-cost-profile` and return here. `3` → flip toggle.
 
-### 7. Mark onboarded
+### 8. Mark onboarded
 
-Write `onboarding.onboarded: true` to `.agent-settings.yml` using the
+Write `onboarding.onboarded: true` to `.agent-settings.yml` using
 section-aware merge rules from
 [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
-(preserve comments, key order, touch only the changed fields).
+(preserve comments, key order, touch only changed fields).
+
+### 9. Write user-global file (only if opted in at step 2)
+
+Skip unless step 2 captured explicit "yes". Re-confirm intent in one line —
+never silent-write a file outside project tree:
+
+```
+> Writing ~/.config/agent-config/agent-settings.yml with the six
+> mergeable keys mirrored from this project's choices:
+>
+>   name: {personal.user_name or ""}
+>   ide: {personal.ide or ""}
+>   cost_profile: {cost_profile}
+>   personal.bot_icon: {personal.pr_comment_bot_icon}
+>   personal.autonomy: {personal.autonomy or "ask"}
+>   caveman.speak_scope: {caveman.speak_scope or "prose_only"}
+>
+> 1. Yes, write it
+> 2. Cancel — keep settings project-local only
+```
+
+`1` → ensure `~/.config/agent-config/` exists (`mkdir -p`, mode `0700`),
+then write file with mode `0600`. Schema is **flat-or-nested YAML keyed on
+dotted paths** in whitelist documented in
+[`scripts/_lib/agent_settings.py`](../scripts/_lib/agent_settings.py).
+Use same section-aware merge rules from
+[`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+**only if file unexpectedly already exists** between step 2 and this step
+(race condition); otherwise create from scratch with exact six keys above
+and a one-line file header comment:
+
+```yaml
+# event4u/agent-config — user-global DX-comfort defaults
+# Whitelist: name · ide · cost_profile · personal.bot_icon · personal.autonomy · caveman.speak_scope
+# Project-local .agent-settings.yml always wins. See docs/customization.md.
+```
+
+`2` → no write, no error, no second ask. Move on.
 
-### 8. Summary
+### 10. Summary
 
 Echo what was captured, in one block:
 
@@ -152,18 +224,19 @@ Echo what was captured, in one block:
   cost_profile: {value}
   pipelines.skill_improvement: {value}
   onboarding.onboarded: true
+  user-global: {"written" if step 9 wrote · "—" otherwise}
 
 You can re-run this with /onboard anytime, or edit .agent-settings.yml
 directly — the agent follows the merge rules in `layered-settings` when
 you ask it to change a value.
 ```
 
-### 9. Maintainer-only feature pointer
+### 11. Maintainer-only feature pointer
 
-Print a one-screen hint after the summary — no question, no prompt, just a
-pointer for maintainers who want to opt into the artefact-engagement
-telemetry layer. Consumers can ignore it; the feature is **default-off**
-and stays off unless explicitly enabled.
+Print one-screen hint after summary — no question, no prompt, just pointer
+for maintainers who want to opt into artefact-engagement telemetry layer.
+Consumers can ignore; feature is **default-off** and stays off unless
+explicitly enabled.
 
 ```
 ℹ️  Maintainer telemetry (opt-in)
@@ -181,20 +254,27 @@ Skip this block in cloud surfaces (no settings file, no log path).
 
 ## Gotchas
 
-- `.agent-settings.yml` is git-ignored. This command never commits.
-- One question per turn. The iron law from `ask-when-uncertain` applies;
-  do not stack questions 2–6 into a single prompt.
+- `.agent-settings.yml` is git-ignored. Command never commits.
+- One question per turn. Iron law from `ask-when-uncertain` applies; do
+  not stack questions 2–9 into single prompt.
 - Re-running `/onboard` when `onboarded: true` is allowed — walk through
-  all steps again and rewrite the values the user confirms.
-- Never overwrite a non-empty value without asking (applies to `user_name`
-  and `ide`).
+  all steps again and rewrite values user confirms.
+- Never overwrite non-empty value without asking (applies to `user_name`,
+  `ide`).
+- **User-global file is opt-in, one-shot, never silent.** Step 2 captures
+  intent, step 9 re-confirms before actual write. If
+  `~/.config/agent-config/agent-settings.yml` already exists when
+  `/onboard` starts, step 2 is skipped entirely — re-onboarding never
+  silently rewrites developer's cross-project defaults. Use
+  `/sync-agent-settings` (project-scoped only) or edit file manually for
+  mid-life changes.
 
 ## Cloud Behavior
 
 On cloud surfaces (Claude.ai Web, Skills API) this command is **fully inert** —
-there is no `.agent-settings.yml` to write, no `onboarding.onboarded` key to
-flip, and no local IDE/rtk environment to capture. First-run setup is a
-local-agent concern; the cloud agent should proceed without invoking it.
+no `.agent-settings.yml` to write, no `onboarding.onboarded` key to flip,
+no local IDE/rtk env to capture. First-run setup is local-agent concern;
+cloud agent should proceed without invoking it.
 
 ## See also
 
@@ -202,3 +282,4 @@ local-agent concern; the cloud agent should proceed without invoking it.
 - [`set-cost-profile`](set-cost-profile.md) — isolated profile change
 - [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md) — merge rules for mid-life edits
 - [`agent-settings` template](../templates/agent-settings.md) — settings reference
+- [`scripts/_lib/agent_settings.py`](../scripts/_lib/agent_settings.py) — centralized loader + whitelist that consumes the user-global file

package/.agent-src/commands/orchestrate.md

@@ -0,0 +1,123 @@
+---
+name: orchestrate
+cluster: orchestrate
+skills: [subagent-orchestration]
+description: Run a YAML pipeline defined under `.agent-config/orchestrations/` — chains personas / skills / commands / sub-agents per the orchestration-dsl-v1 contract
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "run a saved orchestration / pipeline / chain"
+  trigger_context: "user names a pipeline file or asks to replay a chain"
+---
+
+# orchestrate
+
+## Instructions
+
+Execute a YAML pipeline file from `.agent-config/orchestrations/`
+against the current workspace. Pipelines are deterministic chains of
+personas, skills, commands, and sub-agents pinned by the
+[`orchestration-dsl-v1`](../docs/contracts/orchestration-dsl-v1.md)
+contract.
+
+This command is the **runtime** side of the contract. The schema and
+the linter (`scripts/lint_orchestration_dsl.py`) live on the authoring
+side; this command reads the same shape and dispatches each step.
+
+### 1. Resolve the pipeline file
+
+- The user passes either a pipeline name (`pr-readiness-check`) or a
+  path (`.agent-config/orchestrations/pr-readiness-check.yaml`).
+- Resolve to a path under `.agent-config/orchestrations/`. Refuse
+  paths outside that directory — pipelines live in one place.
+- If the file does not exist, list the available pipelines and stop.
+
+### 2. Validate before run
+
+Run the linter against the resolved file:
+
+```
+python3 scripts/lint_orchestration_dsl.py --file <path>
+```
+
+Exit code ≠ 0 → surface the linter output and stop. **Never** run
+a pipeline that fails its own schema check.
+
+### 3. Collect inputs
+
+For each `inputs[]` entry in the pipeline:
+
+- If the user supplied a value on invocation (`/orchestrate pr-readiness-check diff_target=feature/x`)
+  use it.
+- Else use the `default` field.
+- Else ask **one** question per missing input, in order. Stop after
+  the first unanswered required input — pipelines are batch-friendly
+  by design, but `ask-when-uncertain` still applies.
+
+### 4. Dispatch the steps
+
+Walk `steps[]` in order. For each step:
+
+| `kind` | Dispatch path |
+|---|---|
+| `skill` | Invoke the skill identified by `ref` with the resolved `with` block. |
+| `command` | Run the slash-command identified by `ref` as if the user had typed it. |
+| `persona` | Set `roles.active_role` to `ref` for the next dependent step; does not produce its own `output`. |
+| `subagent` | Delegate to [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md) using `ref` as the mode name. |
+
+Capture each step's output in an in-memory `outputs[step.id]` map.
+`${{ inputs.X }}` and `${{ steps.Y.output }}` are substituted via
+string replacement only — no expressions, no shell-out.
+
+### 5. Honour `when`
+
+If a step has a `when` field, evaluate it as one of:
+
+- `${{ steps.X.output }} == "<literal>"`
+- `steps.X.success` / `steps.X.failure`
+
+Anything else → stop the run with a clear error. The DSL is
+deliberately tiny; richer logic belongs in a skill, not in the
+pipeline file.
+
+### 6. Halt on hard failure
+
+A step failure ends the pipeline immediately. Surface:
+
+- the failing step id and kind/ref
+- the error or non-zero exit
+- the steps that ran cleanly before it
+
+Do **not** continue past a failure unless a downstream step has a
+`when: steps.X.failure` guard explicitly authorizing it.
+
+### 7. Produce the delivery report
+
+When the pipeline reaches the end of `steps[]`:
+
+- Resolve every `outputs[name]` entry by substituting the captured
+  step outputs.
+- Print a Markdown delivery report:
+  - pipeline name + resolved input values
+  - per-step verdict (✅ / ❌, ref, one-line summary)
+  - the resolved `outputs:` map at the bottom
+
+### 8. Audit trail
+
+Per [`audit-log-v1`](../docs/contracts/audit-log-v1.md), append
+one JSONL entry per step boundary to the current month's audit file
+under `agents/state/audit/`. Counts + ids only — never the step's
+output body.
+
+### 9. What this command does NOT do
+
+- Edit the pipeline file. Authoring is human or skill-driven.
+- Commit, push, or open PRs. Those gates live elsewhere.
+- Branch or invent steps. The pipeline file is the source of truth.
+
+## See also
+
+- Contract: [`orchestration-dsl-v1.md`](../docs/contracts/orchestration-dsl-v1.md)
+- Linter: `scripts/lint_orchestration_dsl.py`
+- Subagent runtime: [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md)
+- Audit emission: [`audit-log-v1.md`](../docs/contracts/audit-log-v1.md)

package/.agent-src/commands/sync-gitignore/fix.md

@@ -0,0 +1,135 @@
+---
+name: sync-gitignore:fix
+cluster: sync-gitignore
+sub: fix
+description: Scrub legacy pre-`/agents/` patterns from the consumer's .gitignore (inside or outside the managed block) and re-sync the canonical entries
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "fix .gitignore garbage, clean up legacy agent-config entries, my .gitignore has stale agent entries, /sync-gitignore is not picking up the right paths"
+  trigger_context: "consumer project carries pre-/agents/ runtime patterns (.agent-chat-history, .agent-prices.md) at the root from an older install"
+---
+
+# /sync-gitignore:fix
+
+Cleanup sibling of [`/sync-gitignore`](../sync-gitignore.md). Strips
+legacy root-level patterns (pre-`/agents/` runtime artefacts —
+`.agent-chat-history`, `.agent-chat-history.bak`,
+`.agent-chat-history.*.bak`, `.agent-prices.md`, `.council-tmp/`) from
+**anywhere** in the consumer's `.gitignore` — inside or outside the
+managed block — then re-runs the regular sync so the current canonical
+`/agents/`-prefixed entries land in the block.
+
+Use when:
+
+- An older installer (pre-May 2026) dropped root-level `.agent-chat-history`
+  / `.agent-prices.md` lines that the current scripts no longer recognise.
+- A hand-edit added one of those legacy paths and it now conflicts with
+  the managed `/agents/...` entry.
+- `/sync-gitignore` reports "already in sync" but git is still ignoring
+  files at the wrong paths.
+
+## When NOT to use
+
+- To remove **user-added** lines from inside the block → that is
+  `--replace` on the base command, and it is destructive. This
+  sub-command only touches the legacy pattern list — nothing else.
+- To delete the entire managed block → do it by hand.
+- To migrate runtime files themselves (move `.agent-chat-history` →
+  `agents/.agent-chat-history`) → the installer's
+  `migrate_legacy_root_infra` step handles that. This sub-command only
+  fixes `.gitignore`.
+
+## Steps
+
+### 1. Locate script and target
+
+Same resolution order as [`/sync-gitignore`](../sync-gitignore.md):
+
+1. `./agent-config/scripts/sync_gitignore.py`
+2. `vendor/event4u/agent-config/scripts/sync_gitignore.py`
+3. `node_modules/@event4u/agent-config/scripts/sync_gitignore.py`
+
+Target is `<project_root>/.gitignore`. If no `.gitignore` exists,
+stop — there is nothing to fix:
+
+```
+> 📝 No .gitignore found at <project_root>. Nothing to clean up.
+```
+
+### 2. Dry-run with cleanup
+
+Run:
+
+```bash
+python3 <script> --cleanup-legacy --dry-run
+```
+
+Capture stdout (unified diff) and stderr (summary line listing the
+legacy entries that would be removed). Three outcomes:
+
+- **Nothing legacy + block in sync** → tell the user and stop:
+  ```
+  > ✅ .gitignore already clean — no legacy patterns, block in sync.
+  ```
+- **Diff produced** → show it and ask:
+  ```
+  > 🧹 /sync-gitignore:fix would clean up .gitignore:
+  >
+  > {diff}
+  >
+  > Summary: would remove {N} legacy entr{y|ies}: {names}
+  >          would add {M} entr{y|ies} to the managed block
+  >
+  > 1. Apply — write the changes
+  > 2. Skip — leave .gitignore untouched
+  ```
+- **Script error** (exit 2) → print the error and stop; do not prompt.
+
+### 3. Act on the choice
+
+- `1` (Apply) → re-run **without** `--dry-run`:
+  ```bash
+  python3 <script> --cleanup-legacy
+  ```
+  Confirm with the script's own summary lines (removed-legacy count and
+  added-entries count both surface there).
+- `2` (Skip) → stop. No changes made.
+
+Free-text replies (`"nö"`, `"leave it"`, unrecognized input) count as
+`2`. Never write on ambiguous input.
+
+### 4. Suggest the migration check (informational, do NOT auto-run)
+
+If the cleanup removed `.agent-chat-history` or `.agent-prices.md`,
+mention that the **file** at the root (if still present) may need to
+move to `agents/`. The installer does this automatically via
+[`migrate_legacy_root_infra`](../../../scripts/install.sh); the
+agent does not run it from this command. One line of guidance is
+enough:
+
+```
+> ℹ️  If `.agent-chat-history` still sits at the project root, re-run the installer (or move it to `agents/.agent-chat-history` by hand) so the runtime can find it again.
+```
+
+## Rules
+
+- **Append-only by default** — `--cleanup-legacy` removes legacy
+  patterns only. User-added non-legacy lines (inside or outside the
+  block) survive untouched.
+- **Never combine with `--replace`** — the destructive full-block
+  rewrite is a separate concern; mixing the two surprises users.
+- **Dry-run first, always** — the user must see the diff before any
+  write.
+- **Do NOT push, commit, or modify other files** — this command writes
+  to `.gitignore` only.
+
+## See also
+
+- [`/sync-gitignore`](../sync-gitignore.md) — append-only sync of the
+  managed block (no legacy cleanup)
+- [`scripts/sync_gitignore.py`](../../../scripts/sync_gitignore.py) —
+  the helper (`--cleanup-legacy` flag)
+- [`scripts/install.sh`](../../../scripts/install.sh) —
+  `migrate_legacy_root_infra` (moves the **files**, complement to this
+  command which fixes the **ignore rules**)

package/.agent-src/commands/sync-gitignore.md

@@ -1,5 +1,6 @@
 ---
 name: sync-gitignore
+cluster: sync-gitignore
 description: Sync the `event4u/agent-config` block in the consumer project's .gitignore — adds missing entries, preserves user-added lines, shows a diff before writing
 disable-model-invocation: true
 suggestion:
@@ -9,6 +10,28 @@ suggestion:
 
 # /sync-gitignore
 
+Top-level entry point for the `/sync-gitignore` family. Bare `/sync-gitignore`
+runs the interactive append-only sync described below. The `:fix`
+sub-command additionally scrubs legacy patterns (pre-`/agents/` layout)
+from anywhere in the consumer's `.gitignore` before re-syncing.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/sync-gitignore` (bare) | this file (`## Default flow`) | Interactive — append-only sync of the managed block, dry-run preview, confirm before write |
+| `/sync-gitignore:fix` | `commands/sync-gitignore/fix.md` | Cleanup — strip legacy root-level patterns (pre-`/agents/` layout) wherever they appear, then sync |
+
+## Dispatch
+
+1. Parse the user's argument: `/sync-gitignore[:<sub>] [args]`.
+2. Bare `/sync-gitignore` → run the `## Default flow` below verbatim.
+3. `/sync-gitignore:fix` → load `commands/sync-gitignore/fix.md` and follow
+   its `## Steps` section verbatim.
+4. Unknown sub-command → print the table above and ask which one.
+
+## Default flow
+
 Ensures the consumer project's `.gitignore` contains every entry the
 package expects to be ignored (symlinked `.augment/` subdirectories,
 `/agent-config` CLI wrapper, `.agent-settings*`, `agents/.agent-chat-history*`).
@@ -23,7 +46,7 @@ Use when:
   setup, or installer ran with `--skip-gitignore`).
 - You want to audit what the block **should** look like without writing.
 
-## When NOT to use
+### When NOT to use
 
 - To disable logging or change what is logged → that is
   `chat_history.enabled` in `.agent-settings.yml`, not `.gitignore`.
@@ -31,8 +54,8 @@ Use when:
   re-remove its own entries.
 - To change what the block contains → edit
   `config/gitignore-block.txt` in the package repo and re-release.
-
-## Steps
+- To clean up legacy garbage from older installs → use
+  [`/sync-gitignore:fix`](sync-gitignore/fix.md) instead.
 
 ### 1. Locate script and target
 
@@ -88,9 +111,11 @@ Free-text replies (`"nö"`, `"leave it"`, unrecognized input) count as
 Do **not** suggest `--replace` by default. It rewrites the block in
 full and drops user-added lines inside the block — destructive.
 Mention it only if the user explicitly asks to clean up or reset the
-block, and confirm once more before running it.
+block, and confirm once more before running it. For removing legacy
+root-level patterns (not user-added lines), prefer
+[`/sync-gitignore:fix`](sync-gitignore/fix.md).
 
-## Gotchas
+## Rules
 
 - The script honors the explicit `# event4u/agent-config — END` marker.
   Legacy blocks without it get the marker added automatically on the
@@ -99,6 +124,7 @@ block, and confirm once more before running it.
   They do not survive `--replace`.
 - Changes to `config/gitignore-block.txt` require a package update in
   the consumer project before this command can apply them.
+- **Do NOT chain sub-commands.** One `/sync-gitignore <sub>` per turn.
 
 ## See also
 

package/.agent-src/skills/learning-to-rule-or-skill/SKILL.md

@@ -21,6 +21,11 @@ Use this skill when:
 * Reviewing post-task learnings or retrospectives
 * Deciding whether a learning belongs in a rule or a skill
 * After completing a task — reflecting on what worked or caused friction
+* Mining the audit log (`agents/state/audit/<YYYY-MM>.jsonl`,
+  [`audit-log-v1`](../../../docs/contracts/audit-log-v1.md)) surfaced
+  a repeated phase pattern via
+  [`extract_audit_patterns.py`](../../../scripts/extract_audit_patterns.py)
+  — the pattern's `count` ≥ 2 already satisfies the repetition gate
 
 Do not use this skill when:
 
@@ -206,8 +211,10 @@ Mandatory fields the draft MUST fill:
 * `source_learning` — path to the `agents/learnings/<date>-<slug>.md`
   file this proposal was captured from
 * `evidence` — **at least two independent** references (PR, issue,
-  incident, review-comment, test-failure); entries that all resolve
-  to the same PR are rejected by the gate
+  incident, review-comment, test-failure, **or audit-log line ids**
+  per [`audit-log-v1`](../../../docs/contracts/audit-log-v1.md));
+  entries that all resolve to the same PR or the same audit-log
+  `run_id` are rejected by the gate (independence floor)
 * `Proposed artefact` (§4) — the full draft body, no `TODO` / `TBD`
 * `Success signal` (§7) — one metric, one baseline, one target, one
   evaluation date
@@ -295,6 +302,27 @@ audio) goes through the upstream `markitdown-mcp` server first; only
 write a custom extractor if `markitdown` cannot handle the format and
 the gap is documented in its skill body.
 
+## Audit-derived learnings (optional source)
+
+When the input is a pattern surfaced by
+[`extract_audit_patterns.py`](../../../scripts/extract_audit_patterns.py)
+mining `agents/state/audit/<YYYY-MM>.jsonl`
+([`audit-log-v1`](../../../docs/contracts/audit-log-v1.md)):
+
+1. Treat the script's pattern record as the **State the learning**
+   step input (§1) — `pattern.summary` is the one-sentence
+   statement, `pattern.line_ids` is the evidence.
+2. The repetition gate is already satisfied for `count ≥ 2`. Skip
+   to §3 (decide the target) — overlap check (§4) and proposal
+   draft (§8) remain mandatory.
+3. Independence floor still applies: two line ids from the same
+   `run_id` count as **one** piece of evidence. The mining script
+   already de-duplicates by `run_id`; the gate trusts that output.
+4. Audit-derived proposals MUST set
+   `source_learning: agents/state/audit/<YYYY-MM>.jsonl#<line_ids>`
+   and link the mining-script run id, so the human reviewer can
+   reproduce the pattern from the raw audit log.
+
 ## Environment notes
 
 Prefer updating existing rule/skill when possible.