@event4u/agent-config 1.18.0 → 1.20.0

package/docs/contracts/hook-architecture-v1.md

@@ -0,0 +1,220 @@
+---
+stability: beta
+---
+
+# Hook architecture v1
+
+**Purpose.** Pin the contract that the universal hook dispatcher
+implements, so concern scripts and per-platform trampolines can be
+written, tested, and refactored against a stable surface.
+
+**Scope.** Defines the dispatcher's stdin/stdout shape, exit-code
+semantics, the `hook_manifest.yaml` schema, the concurrency contract
+for `agents/state/` writes, and the Copilot fallback pattern. Does
+**not** specify per-platform install paths — those live in
+[`chat-history-platform-hooks.md`](../../agents/contexts/chat-history-platform-hooks.md).
+
+Last refreshed: 2026-05-04.
+
+## Vocabulary
+
+| Term | Meaning |
+|---|---|
+| **Platform** | Host agent surface — one of `augment`, `claude`, `cowork`, `cursor`, `cline`, `windsurf`, `gemini`, `copilot`. The `claude` value covers both Claude Code (CLI) and Claude.ai Web; `cowork` covers the Claude desktop app's local-agent-mode runtime separately so chat-history entries can attribute events to Cowork vs CLI Claude Code via the `agent` field. Cowork shares Claude Code's lifecycle vocabulary and payload shape but is upstream-blocked from reading any settings source as of writing (anthropics/claude-code#40495, #27398). The canonical platform identifier is `claude` for the CLI/IDE surface and `cowork` for the desktop sandbox (both match `chat_history.PLATFORM_EVENT_MAP`). |
+| **Concern** | A single agent-config behaviour wired to one or more lifecycle events — e.g. `chat-history`, `roadmap-progress`, `verify-before-complete`. Lives as a Python script under `scripts/hooks/concerns/<name>.py`. |
+| **Event** | The agent-config-internal event vocabulary the dispatcher exposes — `session_start`, `session_end`, `user_prompt_submit`, `pre_tool_use`, `post_tool_use`, `stop`, `pre_compact`, `agent_error`. Per-platform native names map to these. `agent_error` is synthetic — fired by the agent (or wrapper) when the host crashes outside a concern, so chat-history can checkpoint partial sessions on abnormal exit. (Added in Round 2 — 2026-05-04.) |
+| **Trampoline** | A 5–10 line per-platform shell script that reads the platform's native payload, calls the dispatcher with `--platform <name>`, and forwards the platform's exit-code semantics. |
+| **Dispatcher** | `scripts/hooks/dispatch_hook.py` — single Python entrypoint that reads the manifest, resolves which concerns fire on `(platform, event)`, runs each one with the contract envelope below, and reduces their exit codes. |
+
+## Dispatcher invocation
+
+```
+python3 scripts/hooks/dispatch_hook.py \
+    --platform <name> \
+    --event <agent-config-event> \
+    [--native-event <platform-event>] \
+    < platform-payload.json
+```
+
+`--native-event` is informational; the dispatcher does not branch on
+it. The trampoline is responsible for translating the platform's
+native event name to the agent-config vocabulary before invocation.
+
+## Stdin contract — concern envelope
+
+The dispatcher writes a single JSON object to each concern's stdin:
+
+```json
+{
+  "schema_version": 1,
+  "platform": "augment",
+  "event": "stop",
+  "native_event": "Stop",
+  "session_id": "…",
+  "workspace_root": "/abs/path",
+  "payload": { /* opaque, platform-native */ },
+  "settings": { /* materialized .agent-settings.yml subset */ }
+}
+```
+
+Concerns MUST treat unknown top-level keys as forward-compat extensions
+and MUST NOT raise on them. `payload` is passed through verbatim from
+the platform — concerns extract what they need via their own helpers
+(see `scripts/chat_history.py` `_extract_*` for the pattern).
+
+## Stdout contract — concern reply
+
+A concern MAY write a single JSON object to stdout. The dispatcher
+reads it; non-JSON or empty stdout is treated as no-op (decision
+inferred from exit code only).
+
+```json
+{
+  "decision": "allow" | "block" | "warn",
+  "reason": "human-readable, ≤ 200 chars",
+  "additional_context": "optional — surfaces back to the model on platforms that support it",
+  "state_writes": ["agents/state/chat-history.json", "…"]
+}
+```
+
+`state_writes` is advisory; concerns still write the files themselves
+under the concurrency rules below.
+
+## Exit-code semantics
+
+| Code | Meaning | Dispatcher action |
+|---|---|---|
+| `0` | allow | no-op; pass through |
+| `1` | block | dispatcher exits 1, surfaces `reason` to platform's deny channel |
+| `2` | warn | dispatcher exits 0, logs `reason` to stderr, sets `additionalContext` if platform supports it |
+| `≥ 3` | error | dispatcher logs full traceback, exits 0 (fail-open) unless `concerns.<name>.fail_closed: true` in settings |
+
+## Reduction across multiple concerns
+
+When a `(platform, event)` tuple maps to ≥ 2 concerns, the dispatcher
+runs them **sequentially** in manifest order and reduces:
+
+- Any `block` → final decision is `block` (most-restrictive merge).
+- Else any `warn` → final decision is `warn`.
+- Else `allow`.
+
+`additional_context` strings are concatenated with `\n\n` separators,
+in manifest order. Concerns are never run in parallel — concurrency
+guarantees rely on serial state writes.
+
+## Feedback channel — `agents/state/.dispatcher/<session_id>/`
+
+Exit-code reduction collapses the severity ladder to a single
+platform-native code, which can hide a `warn` behind a `block` or
+mask non-actioned reasons entirely. To preserve per-concern detail
+without re-routing control flow, the dispatcher writes a feedback
+directory per invocation:
+
+```
+agents/state/.dispatcher/<session_id>/
+  <concern>.json     — one file per concern that ran
+  summary.json       — rollup written after the last concern
+```
+
+Each `<concern>.json` carries:
+
+```json
+{
+  "concern": "chat-history",
+  "exit_code": 0,
+  "raw_exit_code": 0,
+  "severity": "allow",
+  "decision": "allow",
+  "reason": "appended turn 12",
+  "duration_ms": 47,
+  "started_at": "2026-05-04T12:34:56Z",
+  "completed_at": "2026-05-04T12:34:56Z",
+  "fail_closed": false
+}
+```
+
+`summary.json` carries the platform / event tuple, the reduced
+`final_exit_code` + `final_severity`, and a trimmed list of all
+concern entries. `session_id` falls back to
+`dispatch-<unix_ts>-<pid>` when the envelope omits one. Path
+traversal in `session_id` is collapsed (`/`, `\`, `..` → `_`).
+
+Feedback writes are non-fatal — IO errors log to stderr but never
+change the dispatcher's exit code. The directory is gitignored and
+consumed by `task hooks-status` (Phase 7.11). Added in Round 2
+(2026-05-04) per Q1 of `tmp/council_round2/q1_feedback_channel.md`.
+
+## Manifest schema — `scripts/hook_manifest.yaml`
+
+```yaml
+schema_version: 1
+concerns:
+  chat-history:
+    script: scripts/hooks/concerns/chat_history.py
+    fail_closed: false
+roadmap-progress:
+    script: scripts/hooks/concerns/roadmap_progress.py
+    fail_closed: false
+
+platforms:
+  augment:
+    session_start: [chat-history]
+    stop:          [chat-history, roadmap-progress]
+    post_tool_use: [chat-history]
+  claude:
+    session_start: [chat-history]
+    user_prompt_submit: [chat-history]
+    stop:          [chat-history, roadmap-progress]
+  copilot:
+    # No dispatcher — see "Copilot fallback" below.
+```
+
+Validated by `scripts/lint_hook_manifest.py` (Phase 7.10): every
+concern script must exist on disk, every platform key must be a known
+platform, every event key must be in the agent-config event vocabulary.
+
+## Concurrency — atomic state writes
+
+Concerns that write under `agents/state/` MUST use the pattern:
+
+1. Acquire `fcntl.flock(LOCK_EX)` on `agents/state/.dispatcher.lock`.
+2. Write to a sibling `<dest>.tmp.<pid>` file in the same directory.
+3. `os.replace(tmp, dest)` — POSIX-atomic on the same filesystem.
+4. Release the lock.
+
+The single `.dispatcher.lock` is intentional: serialising state
+writes across concerns is cheaper than per-file locks, and concerns
+already run sequentially within one dispatcher invocation. The lock
+file is gitignored.
+
+Phase 7.4 ships a regression test that spawns two concurrent
+dispatcher invocations against the same event and asserts no torn
+writes (file ends with valid JSON, last-writer-wins).
+
+## Copilot fallback pattern
+
+Copilot has no hook surface. Concerns whose source rule cites
+`agents/state/<concern>.json` MUST gain a "Copilot fallback" section
+that:
+
+- Names the state file the concern would have written.
+- Names a manual command or task that reproduces the side effect
+  (e.g. `task chat-history:append`).
+- Includes no Iron-Law-changing prose.
+
+The dispatcher silently no-ops when called with `--platform copilot`;
+the fallback is consumed by reading the rule, not by hook invocation.
+
+## Stability
+
+Beta. Breaking changes between v1 and v2 are allowed in a minor
+release if the change appears in `CHANGELOG.md` under a `### Breaking`
+heading. Concerns MUST gate on `schema_version` and refuse unknown
+majors.
+
+## See also
+
+- [`docs/hook-payload-capture.md`](../hook-payload-capture.md) —
+  operational how-to for capturing redacted live payloads to upgrade
+  a platform's chat-history extractor from `docs-verified` to
+  `payload-verified`.

package/docs/contracts/memory-visibility-v1.md

@@ -0,0 +1,122 @@
+---
+stability: beta
+---
+
+# Memory-visibility v1
+
+**Purpose.** Pin the format of the user-facing visibility line that
+every memory-using `/work` and `/implement-ticket` run prints, so the
+user can tell what the agent retrieved and what it ignored.
+Complements [`agent-memory-contract.md`](agent-memory-contract.md):
+that doc describes the **CLI surface and backend states**; this doc
+describes the **operator-facing surface** the engine emits per turn.
+
+**Scope.** Defines the line shape, the privacy floor, and the opt-out
+toggle. Does **not** define how memory entries are scored or routed —
+that is the sibling agent-memory package.
+
+Last refreshed: 2026-05-04.
+
+## Line shape
+
+A single one-line ASCII record, prefixed with the memory icon `🧠`
+and a single space:
+
+```
+🧠 Memory: <hits>/<asks> · ids=[<comma-separated-ids>]
+```
+
+Examples:
+
+```
+🧠 Memory: 3/4 · ids=[mem_42, mem_57, mem_91]
+🧠 Memory: 0/2 · ids=[]
+🧠 Memory: 5/5 · ids=[mem_a01, mem_a02, mem_a03, …+2]
+```
+
+Cap at 5 ids inline; remainder rendered as `…+N`. The full id list
+lives in the decision-trace JSON
+([`decision-trace-v1.md`](decision-trace-v1.md)).
+
+## Field semantics
+
+| Field | Meaning |
+|---|---|
+| `hits` | Count of `memory_retrieve_*` calls during this turn that returned ≥ 1 entry. |
+| `asks` | Count of `memory_retrieve_*` calls during this turn — both successful and empty. |
+| `ids` | Stable memory entry ids returned across all calls, deduped, ordered by retrieval timestamp. |
+
+`hits ≤ asks` is invariant. If `asks == 0`, the engine MUST suppress
+the line entirely — no `0/0` noise.
+
+## Privacy floor
+
+The visibility line and the JSON it derives from MUST NOT contain:
+
+- Entry **bodies**, summaries, or quoted snippets.
+- Secrets, tokens, environment values, or paths outside the
+  package's `agents/state/` and `tests/` allowlist.
+- User identifiers beyond what is already public in the working
+  directory's `.agent-settings.yml` (e.g. developer name).
+
+The privacy floor is enforced by
+`tests/contracts/test_memory_visibility_redaction.py` — any new
+content path that ships memory output adds a fixture there.
+
+## Opt-out
+
+On by default whenever memory is asked at all in a turn. Users can
+suppress the visibility line via:
+
+```yaml
+memory:
+  visibility: off
+```
+
+Off-mode does not silence the underlying memory calls; it only stops
+the line from rendering. The decision-trace JSON still records the
+counts and ids for downstream metrics.
+
+## Cadence interaction
+
+| Cost profile | Visibility line |
+|---|---|
+| `lean` | suppress unless `asks ≥ 3` |
+| `standard` | always when `asks ≥ 1` |
+| `verbose` | always when `asks ≥ 1` |
+
+Cost-profile lookup respects `.agent-settings.yml`'s `cost_profile`
+key. Default is `standard`.
+
+## Audit-as-memory feed
+
+The visibility output produced by the engine is the input to the
+audit-as-memory pipeline (consumed by the sibling distribution +
+adoption work). Concretely:
+
+- The engine emits the line + the underlying counts to the
+  decision-trace JSON.
+- A consumer hook reads `agents/state/work/<work-id>/decision-trace-*.json`,
+  rolls counts up to the session level, and feeds the result back
+  into the agent-memory store as an audit entry.
+
+This contract pins the **producer** side. The audit-feed consumer
+lives outside the package's stable surface and must read this
+contract before parsing.
+
+## Stability
+
+Beta. Breaking changes between v1 and v2 are allowed in a minor
+release if the change appears in `CHANGELOG.md` under a `### Breaking`
+heading. Engines MUST gate on the visibility line shape — clients
+parsing the stream MUST treat unknown trailing fields as forward-
+compat extensions.
+
+## Cross-references
+
+- CLI surface and backend states:
+  [`agent-memory-contract.md`](agent-memory-contract.md).
+- Decision-trace JSON consumes the same counts:
+  [`decision-trace-v1.md`](decision-trace-v1.md).
+- Privacy regression test path:
+  `tests/contracts/test_memory_visibility_redaction.py`.

package/docs/contracts/one-off-script-lifecycle.md

@@ -0,0 +1,109 @@
+---
+stability: beta
+---
+
+# One-off-script lifecycle
+
+**Purpose.** Pin the naming, location, age, and purge policy for
+**one-off scripts** so the package does not accumulate a graveyard
+under `scripts/`. One-off here means: a script written for a
+specific migration, retrofit, audit, or council run, with no ongoing
+caller and no place in the durable Taskfile.
+
+**Scope.** Defines the file pattern, the directory, the maximum age,
+the TTL extension mechanism, and the CI purge gate. Does **not**
+specify the content of any specific one-off — that belongs to the
+script itself or the cleanup-mechanics context.
+
+Last refreshed: 2026-05-04.
+
+## Naming
+
+One-off scripts MUST match this regex:
+
+```
+^_one_off_[a-z0-9-]+\.py$
+```
+
+The `_one_off_` prefix is the load-bearing signal. Files outside
+this prefix are treated as durable scripts and MUST be referenced by
+the Taskfile or by another script.
+
+## Location
+
+```
+scripts/_one_off/<YYYY-MM>/_one_off_<slug>.py
+```
+
+`<YYYY-MM>` is the UTC month the script was first committed. The
+month directory groups one-offs for archival sweeps. Scripts MUST
+NOT live at `scripts/_one_off/_one_off_*.py` (no month) or under
+`scripts/` directly (no `_one_off/`).
+
+## TTL
+
+| State | Action |
+|---|---|
+| Age ≤ 60 days from month-directory date | active, no warning |
+| 60 < Age ≤ 90 days | warning emitted by `lint_one_off_age.py`, no failure |
+| Age > 90 days | `lint_one_off_age.py` fails CI; the script is purged in the next housekeeping pass |
+
+Age = `today − first-of-month(<YYYY-MM>)` in UTC days. The 60-day
+soft floor and 30-day grace window are intentional — they cover one
+release cycle plus a sprint of grace.
+
+## TTL extension
+
+A one-off MAY extend its TTL exactly once, by adding a frontmatter
+block at the top of the script:
+
+```python
+"""
+---
+ttl_extended_until: 2026-08-31
+ttl_reason: blocked on PROJ-123 — re-runs after cutover
+---
+"""
+```
+
+The linter respects `ttl_extended_until` if it is ≤ 180 days from
+the file's `<YYYY-MM>` directory date. Beyond 180 days, the linter
+hard-fails — no second extension. The intent is: if a "one-off" is
+still live at six months, it is a durable concern and belongs in
+`scripts/` or a Taskfile group.
+
+## Purge mechanism
+
+`lint_one_off_age.py` runs in `task ci`. On a clean working tree, it
+prints purge candidates as a list. Purge itself is a separate human-
+or-CI action — `task purge-one-offs` removes flagged files. The
+linter does not auto-delete.
+
+## Allowed exceptions
+
+Two patterns are exempt from the prefix requirement:
+
+- **Bundler / orchestrator helpers** under `scripts/ai_council/`
+  that exist to support the council CLI — they are not one-offs even
+  though council *runs* are one-offs.
+- **`scripts/_one_off/<YYYY-MM>/README.md`** — a free-form readme is
+  allowed in each month directory documenting why the scripts exist.
+
+Council run scripts that wrap a question and write the response file
+DO live under `scripts/_one_off/<YYYY-MM>/` and DO follow the prefix
+rule.
+
+## Cross-references
+
+- The contract that defines council CLI surface (and so what gets
+  archived as a one-off): the council CLI section of the package's
+  command catalog.
+- The cleanup-mechanics context for housekeeping passes:
+  `agents/contexts/cleanup-mechanics.md`.
+- Linter implementation: `scripts/lint_one_off_age.py`.
+
+## Stability
+
+Beta. Breaking changes (e.g. raising the age cap, changing the
+prefix, or removing TTL extensions) require a minor-version bump and
+a `### Breaking` entry in `CHANGELOG.md`.

package/docs/contracts/rule-interactions.yml

@@ -221,6 +221,28 @@ pairs:
       - .agent-src.uncompressed/rules/ask-when-uncertain.md#iron-law--one-question-per-turn-always
       - .agent-src.uncompressed/rules/direct-answers.md#iron-law-3--brevity-by-default
 
+  - id: scope-x-verify-before-complete
+    rules: [verify-before-complete, scope-control]
+    relation: complements
+    conflict: >-
+      Agent has just finished a change that touches user-permission-gated
+      operations (push, branch, PR, tag) and is preparing to claim "done"
+      in the same turn. Both rules can fire: `verify-before-complete`
+      gates the completion claim on fresh evidence; `scope-control`
+      gates the git operation on explicit permission this turn.
+    resolution: >-
+      Both rules apply independently and compose. The
+      `verify-before-complete` Iron Law still requires fresh
+      verification output in this message before any "done" claim,
+      regardless of whether the user has authorised the next git op.
+      Conversely, verification passing does not authorise pushing or
+      merging — those stay behind the `scope-control` permission gate.
+      Skipping either is a rule violation; satisfying one does not
+      satisfy the other.
+    evidence:
+      - .agent-src.uncompressed/rules/verify-before-complete.md#the-iron-law
+      - .agent-src.uncompressed/rules/scope-control.md#git-operations--permission-gated
+
   - id: language-x-direct-answers
     rules: [language-and-tone, direct-answers]
     relation: complements

package/docs/customization.md

@@ -53,7 +53,7 @@ those sections.
 | `personal.open_edited_files` | `false` | Open edited files in IDE |
 | `personal.ide` | *(empty)* | IDE for file opening (`cursor`, `code`, `phpstorm`) |
 | `pipelines.skill_improvement` | `true` | Post-task learning capture. Included in every profile except `custom`. |
-| `chat_history.enabled` | `true` | Persistent JSONL log at `.agent-chat-history` for crash recovery. |
+| `chat_history.enabled` | `true` | Persistent JSONL log at `agents/.agent-chat-history` for crash recovery. |
 | `chat_history.frequency` | per profile | Logging granularity: `per_turn`, `per_phase`, or `per_tool` (see matrix below). |
 | `chat_history.max_size_kb` | per profile | Max file size before overflow handling (see matrix below). |
 | `chat_history.on_overflow` | per profile | `rotate` drops oldest, `compress` marks for summarization (see matrix below). |
@@ -66,6 +66,7 @@ those sections.
 | `ai_council.cost_budget.max_calls` | `10` | Maximum council members per invocation. |
 | `ai_council.cost_budget.max_total_usd` | `0.0` | Per-invocation USD ceiling. `0` disables (token caps still apply). |
 | `ai_council.cost_budget.daily_limit_usd` | `0.0` | Rolling 24h USD ceiling across all `/council` calls. `0` disables. Ledger lives at `~/.config/agent-config/council-spend.jsonl` (mode 0600). |
+| `ai_council.session_retention_days` | `14` | Auto-prune for `agents/council-sessions/` audit folders. Older session directories are removed on the next `save()`. `0` disables (keep forever). |
 
 > **Experimental.** AI Council is not yet validated by external users. API costs apply per consultation.
 

package/docs/development.md

@@ -17,7 +17,10 @@
 
 ## Task Commands
 
-All commands use [Task](https://taskfile.dev/). See `Taskfile.yml` for the full list.
+All commands use [Task](https://taskfile.dev/). The root `Taskfile.yml` orchestrates
+`ci`/`_ci-*` and includes the four task groups under `taskfiles/`
+(`ci-fast.yml`, `content.yml`, `engine.yml`, `release.yml`) with `flatten: true`,
+so every task stays in the root namespace. Run `task --list` for the full list.
 
 ### CI & Verification
 

package/docs/getting-started.md

@@ -115,7 +115,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 58 rules. No configuration needed.
+This is enforced automatically by 56 rules. No configuration needed.
 
 ---
 
@@ -151,41 +151,33 @@ Your agent now understands slash commands:
 | `/optimize skills` | Audit skills, find duplicates, run linter |
 | `/feature plan` | Interactively plan a feature |
 | `/quality-fix` | Run and fix all quality checks |
-| `/chat-history` | Inspect the persistent chat-history log |
-| `/chat-history-resume` | Recover context after a crashed or switched session |
-| `/chat-history-clear` | Wipe the chat-history log (with confirmation) |
+| `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 95 active commands](../.agent-src/commands/)
+→ [Browse all 94 active commands](../.agent-src/commands/)
 
 ---
 
-## Crash recovery — `.agent-chat-history`
+## Crash recovery — `agents/.agent-chat-history`
 
 When `chat_history.enabled: true` in `.agent-settings.yml` (on by default
 for every profile), the agent keeps a JSONL log of your conversation in
-`.agent-chat-history` at the project root. The file is git-ignored and
-rotates at the size configured in the profile (`128 KB` on `minimal`,
-`256 KB` on `balanced`, `512 KB` on `full`).
-
-When a chat opens and finds an existing log, the host agent is
-instructed to run a 4-state ownership check and choose the right
-flow:
-
-- **match** — this chat already owns the file. Append silently.
-- **foreign** — a different session's file. You get 3 options:
-  Resume (adopt), New start (archive + init), Ignore (skip logging).
-- **returning** — this chat once owned the file, but another session
-  took over in between. You get 3 options: Merge (your history in front
-  of the foreign entries), Replace (wipe foreign entries, keep yours
-  only), Continue (just leave the file and append from now on).
-- **missing** — no file yet. Init and proceed.
-
-Run `/chat-history-resume` to walk through the prompts explicitly, or
-let the agent ask on the first turn of a new chat. All merge/replace/
-resume paths read the on-disk entries into context before any write.
-
-See the [`chat-history` rule](../.agent-src/rules/chat-history-ownership.md) and
-[`scripts/chat_history.py`](../scripts/chat_history.py) for the mechanics.
+`agents/.agent-chat-history`. The file is git-ignored and rotates at the
+size configured in the profile (`128 KB` on `minimal`, `256 KB` on
+`balanced`, `512 KB` on `full`).
+
+Logging is **hook-only**: a structural Augment hook fires on
+`session_start` and binds the log to the current session via auto-adopt
+— no agent prompts, no ownership questions. The file is rewritten
+transparently if the fingerprint does not match (fresh chat) and
+otherwise appended to.
+
+Run `/chat-history` (a.k.a. `/chat-history show`) any time to inspect
+the log size, last entries, and current fingerprint. For the rare case
+where auto-adopt misfires (corrupted file, hook misconfiguration), run
+`./agent-config chat-history:adopt` as the manual recovery lever.
+
+See [`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+and [`scripts/chat_history.py`](../scripts/chat_history.py) for the mechanics.
 
 ---
 

package/docs/guidelines/agent-infra/ask-when-uncertain-demos.md

@@ -106,7 +106,7 @@ Agent: Bevor ich die Roadmap übergebe:
 - Welcher Branch?
 - Soll ich PRs erwähnen?
 - Welches Modell für die Fortsetzung?
-- Soll ich .agent-chat-history zitieren?
+- Soll ich agents/.agent-chat-history zitieren?
 
 Antworte als 1, 2, 3, 4.
 ```

package/docs/guidelines/agent-infra/layered-settings.md

@@ -152,27 +152,46 @@ MUST follow these rules. Initial file creation and legacy migration
 are owned by `scripts/install.py`; these rules govern every edit
 after that.
 
+The contract is **additive merge with user-line preservation** —
+the user's file is the ground truth, the template only contributes
+keys the user is missing. Round-trip parser and merger live in
+[`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py); the
+supported YAML subset (block-mappings, scalars, lists, comments,
+CRLF/LF) is documented in its module docstring. The stdlib-only
+choice (vs. `ruamel.yaml`) and its revisit triggers are recorded in
+[`docs/contracts/adr-settings-sync-engine.md`](../../contracts/adr-settings-sync-engine.md).
+
 For each section in the template
-([`agent-settings.md`](../../templates/agent-settings.md)), walked in
-template order:
+([`agent-settings.md`](../../templates/agent-settings.md)):
 
-- Keep the section header and its comments verbatim from the template.
 - For each key under the section:
-  - **Key exists in user's file** → use the user's current value.
-  - **Key missing** → use the template default.
-- **Unknown sections/keys** the user has added → preserve at the end
-  of the section (or in a trailing `_user:` block if no matching
-  section exists).
+  - **Key exists in user's file** → keep the user's line **verbatim**
+    (value, quoting, inline comment, indent — all preserved).
+  - **Key missing** → insert the template's line at the position
+    after the user's last preceding sibling that is also in the
+    template (max-index insertion).
+- **Unknown sections/keys** the user has added → preserved verbatim
+  at their existing position. They are not moved to a trailing
+  `_user:` block, not re-prefixed, not flattened.
 
 Invariants:
 
-- Template section **order** always wins — reorder existing keys to
-  match.
+- **User order wins.** Template order is only consulted to decide
+  where to insert missing keys; existing user keys are never
+  reordered.
 - Existing scalar values are **never overwritten** unless the user
   asked for that specific change.
-- New keys added to the template land with their default value.
-- Comments from the template replace user comments in the same
-  position — comments are documentation, not user data.
+- New keys added to the template land with their default value and
+  the template's leading comments.
+- **User comments are preserved verbatim** on every existing key.
+  Template comments only land with keys the merger inserts; once a
+  key is in the user's file, its surrounding comments are owned by
+  the user.
+- Legacy `_user._user.foo` corruption (accumulated by older buggy
+  syncs) heals on the next sync — the leading `_user.` chain is
+  stripped and the leaf is re-homed at its template path, or kept
+  as a single-level orphan under `_user:` if no template home
+  exists.
 - Write with 2-space indent, no tabs, no trailing whitespace.
 - Never commit — `.agent-settings.yml` is git-ignored.
 - If a legacy flat `.agent-settings` (key=value) is still present,