@event4u/agent-config 1.9.1 → 1.12.0

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

@@ -5,7 +5,8 @@ Two-file settings model: **team defaults** (committed) and
 without forcing every developer to work the same way.
 
 Referenced by `road-to-project-memory.md` Phase 0. Consumed by the
-`config-agent-settings` command and the settings loader.
+settings loader, the `/onboard` command, and any agent that edits
+`.agent-settings.yml` on user request.
 
 ## The two files
 
@@ -84,8 +85,9 @@ mistakenly committed) migrate by:
    repo history only if it leaked personal tokens. Otherwise leave
    it — future commits supersede.
 
-The `config-agent-settings` command performs steps 1–3 and 5
-automatically when it detects a one-file setup.
+The `/onboard` command and any agent that edits settings on user
+request should walk steps 1–3 and 5 automatically when it detects
+a one-file setup.
 
 ## .gitignore expectations
 
@@ -105,8 +107,9 @@ pattern (e.g. `*.yml` in a nested folder) would otherwise match.
   directly. The loader returns the merged view already.
 - **Commands** that mutate settings must state which layer they
   write to. Writing to the wrong layer is a spec bug.
-- **`config-agent-settings`** is the single writer for both files.
-  Other commands MUST delegate — no ad-hoc YAML edits.
+- Writes to either file MUST follow the [section-aware merge
+  rules](#section-aware-merge-rules) — preserve existing values,
+  template order, and comments. No ad-hoc YAML rewrites.
 
 ## Persona-list merge semantics
 
@@ -140,6 +143,46 @@ If the project locks `personas.default` via `locked_keys`, steps 2
 and 4 are ignored with a one-line warning — the developer cannot
 narrow a team-locked cast.
 
+## Section-aware merge rules
+
+Any agent that writes `.agent-settings.yml` or
+`.agent-project-settings.yml` on the user's behalf (including
+`/onboard`, `/set-cost-profile`, and ad-hoc "change value X" requests)
+MUST follow these rules. Initial file creation and legacy migration
+are owned by `scripts/install.py`; these rules govern every edit
+after that.
+
+For each section in the template
+([`agent-settings.md`](../../templates/agent-settings.md)), walked in
+template order:
+
+- 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).
+
+Invariants:
+
+- Template section **order** always wins — reorder existing keys to
+  match.
+- 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.
+- 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,
+  stop and tell the user to run `scripts/install` — migration is the
+  installer's job, never the agent's.
+
+Template drift (new keys shipped by a package update) is resolved by
+re-running `scripts/install` or by the agent walking these rules on
+the next explicit settings edit.
+
 ## Anti-patterns
 
 - **Do NOT** commit `.agent-settings.yml`. It contains developer

package/.agent-src/rules/ask-when-uncertain.md

@@ -33,6 +33,7 @@ request matches one of these without further context, ask **before** touching co
 | "refactor X" | Target pattern? Boundaries? | "Refactor toward what — smaller methods, extract class, or something else?" |
 | "use best practices" | Whose? For what? | "Best practices for what specifically — testing, naming, structure?" |
 | "handle errors properly" | Which errors? How? Log, retry, propagate? | "For which failure modes, and what should happen on error?" |
+| "add a UI / component / tile / page" when the repo mixes frameworks | Which stack? Tailwind? Flux? Livewire? Custom? | "This repo uses {A} and {B} for UI — which one for this?" |
 
 **Escape hatch:** If surrounding context (ticket, open file, prior conversation)
 makes the answer unambiguous, proceed — but state the assumption explicitly.
@@ -41,9 +42,61 @@ makes the answer unambiguous, proceed — but state the assumption explicitly.
 
 Be specific. Present numbered options (per `user-interaction`). Keep it short.
 
-- Simple (binary, small): multiple at once, numbered
-- Complex (needs thinking): one at a time, wait for answer
-- Handoff (model switch): ask LAST
+### The Iron Law — one question per turn, ALWAYS
+
+```
+ONE QUESTION PER TURN. NO EXCEPTIONS.
+ASK. WAIT FOR THE ANSWER. THEN ASK THE NEXT.
+```
+
+This is absolute. Not a default, not a guideline, not "usually". Every
+turn that contains a question contains **exactly one** question. Even
+if the questions look trivial. Even if they look independent. Even if
+they would fit on one screen. Even if batching "feels more efficient".
+
+The user must never have to track sub-numbers, scroll through stacked
+option blocks, or split their reply across multiple questions. One
+question, numbered options (per `user-interaction`), one short answer,
+next turn.
+
+Rationale — why even "trivial" batches fail:
+
+| Situation | Why serial always wins |
+|---|---|
+| Design / architecture decisions | Answer to Q1 reframes Q2 |
+| Naming / command-syntax / API shape | Later choices depend on it |
+| Scope / PR boundaries | Changes what the other questions even mean |
+| Tool / library selection | Downstream choices branch from it |
+| "Which approach: A vs B vs C" | Each answer opens a different follow-up |
+| Even "independent" yes/no pairs | User still has to parse two contexts |
+| Any question the user has to **think** about, not just pick | Thinking load compounds when stacked |
+
+### Self-check before asking
+
+Before sending a turn with a question, ask yourself:
+
+1. Does this turn contain more than one `?` directed at the user?
+2. Does this turn present two or more separate numbered-option blocks?
+3. Would the user need to reply with a structured answer (`1a, 2b`)
+   instead of a single number or word?
+
+If any answer is "yes" → **collapse to ONE question** and send. Hold
+every other question for its own turn. No exceptions, no "but these
+are related".
+
+### Ordering & handoff
+
+- **Session handoff** (`/agent-handoff`, fresh-chat proposal): ask LAST,
+  after all domain / clarifying questions — so the user's answers can be
+  folded into the handoff prompt. Full rationale in
+  [`agent-interaction-and-decision-quality`](../guidelines/agent-infra/agent-interaction-and-decision-quality.md#handoff--model-switch-questions).
+- **Model switch**: different phase — [`model-recommendation`](model-recommendation.md)
+  triggers at task start with its own STOP-AND-WAIT gate, standalone, not
+  appended to a Q&A block. Do not conflate the two.
+- **Blocking clarification** (can't proceed without it): ask FIRST,
+  alone, before any research or planning output.
+- **Optional refinement**: don't ask at all — state the assumption
+  and proceed.
 
 ## Creating new agent artifacts
 

package/.agent-src/rules/augment-portability.md

@@ -31,8 +31,59 @@ consumer-specific content pollutes downstream or misleads agents.
 - Always ask when editing package files: "Would this still make sense
   in a completely different project?"
 
+## Runtime invocations — no `task` commands
+
+Skills, rules, commands, guidelines, personas, contexts shipped by this
+package run in **consumer projects** that may not have Task installed.
+NEVER reference a `task <name>` invocation inside any artefact file
+under `.agent-src.uncompressed/{skills,rules,commands,guidelines,personas,contexts}/`
+(or the compressed mirror under `.agent-src/`). Use the direct script:
+
+| ❌ Forbidden | ✅ Portable |
+|---|---|
+| `task sync` | `bash scripts/compress.sh --sync` |
+| `task sync-check` | `bash scripts/compress.sh --check` |
+| `task sync-check-hashes` | `bash scripts/compress.sh --check-hashes` |
+| `task sync-changed` | `bash scripts/compress.sh --changed` |
+| `task sync-mark-done -- X` | `bash scripts/compress.sh --mark-done X` |
+| `task generate-tools` | `python3 scripts/compress.py --generate-tools` |
+| `task lint-skills` | `python3 scripts/skill_linter.py --all` |
+| `task check-refs` | `python3 scripts/check_references.py` |
+| `task check-portability` | `python3 scripts/check_portability.py` |
+| `task check-compression` | `python3 scripts/check_compression.py` |
+| `task validate-schema` | `python3 scripts/validate_frontmatter.py` |
+| `task counts-check` | `python3 scripts/update_counts.py --check` |
+| `task roadmap-progress` | `./agent-config roadmap:progress` |
+| `task ci` | run each underlying script directly |
+
+Task stays a convenience for package maintainers (`Taskfile.yml`,
+`AGENTS.md`, README). Artefact files must assume Task is absent.
+
+## Consumer CLI — `./agent-config`
+
+A subset of scripts is exposed through a project-local CLI wrapper
+`./agent-config` (written into the project root by the installer,
+gitignored). Artefacts MUST prefer the CLI over raw `python3 scripts/…`
+paths for every command it covers — raw paths only resolve inside the
+package repo, in consumer projects the scripts live under
+`node_modules/` or `vendor/`.
+
+| ❌ Forbidden in artefacts | ✅ Portable |
+|---|---|
+| `python3 scripts/mcp_render.py` | `./agent-config mcp:render` |
+| `python3 scripts/mcp_render.py --check` | `./agent-config mcp:check` |
+| `python3 .augment/scripts/update_roadmap_progress.py` | `./agent-config roadmap:progress` |
+| `python3 .augment/scripts/update_roadmap_progress.py --check` | `./agent-config roadmap:progress-check` |
+| `bash scripts/first-run.sh` | `./agent-config first-run` |
+
+Commands not covered by the CLI stay as direct script invocations
+(e.g. `bash scripts/compress.sh --sync`) — maintainer-only, not
+reachable from a consumer project anyway.
+
 ## Enforcement
 
 `scripts/check_portability.py` scans `.augment/`, `.agent-src.uncompressed/`,
 and the package root `AGENTS.md` + `.github/copilot-instructions.md` for
-forbidden identifiers. Part of `task ci` — must pass before any PR.
+forbidden identifiers, for any `task <name>` invocation, and for direct
+script invocations that bypass the `./agent-config` CLI. Runs in CI —
+must pass before any PR.

package/.agent-src/rules/augment-source-of-truth.md

@@ -35,7 +35,7 @@ Direct edits to `.agent-src/` break compression hashes, cause CI failures, and c
 
 1. **Create or edit** the file in `.agent-src.uncompressed/{path}`
 2. **Do NOT auto-compress.** Continue working.
-3. **Before commit/push:** Check if compression is needed (`task sync-changed`).
+3. **Before commit/push:** Check if compression is needed (`bash scripts/compress.sh --changed`).
    If files need compression, ask the user:
    ```
    > 📦 {N} .agent-src files need compression before commit.
@@ -43,9 +43,9 @@ Direct edits to `.agent-src/` break compression hashes, cause CI failures, and c
    > 1. Compress now — run /compress
    > 2. Later — commit without compression
    ```
-4. If compressing: run `/compress` command, then `task sync-mark-done -- {path}`
+4. If compressing: run `/compress` command, then `bash scripts/compress.sh --mark-done {path}`
 
-For new non-.md files (`.php`, configs): `task sync` copies them automatically.
+For new non-.md files (`.php`, configs): `bash scripts/compress.sh --sync` copies them automatically.
 
 **Key change:** Compression happens once before commit/push — not after every edit.
 This avoids interruptions when work is still in progress.
@@ -88,7 +88,7 @@ disable-model-invocation: true
 1. Create `.agent-src.uncompressed/commands/{name}.md` (use template)
 2. Run `python3 scripts/skill_linter.py` — must be 0 FAIL
 3. Compress via `/compress`, which writes to `.agent-src/commands/`
-4. Run `task generate-tools` — creates Claude symlink automatically
+4. Run `python3 scripts/compress.py --generate-tools` — creates Claude symlink automatically
 
 **Never** create `.claude/skills/{name}/SKILL.md` manually for commands — always use the symlink workflow.
 
@@ -96,7 +96,7 @@ disable-model-invocation: true
 
 Before asking for review or creating a PR, verify derived outputs are not stale:
 
-1. Run `task sync-changed` — check if `.agent-src.uncompressed/` has changes not yet compressed
+1. Run `bash scripts/compress.sh --changed` — check if `.agent-src.uncompressed/` has changes not yet compressed
 2. If stale files exist: run `/compress` before pushing
 3. Before merge: verify derived outputs (`.agent-src/`, `.augment/`, `.claude/skills/`) are regenerated
 4. Do NOT leave `.agent-src/` stale across review cycles
@@ -120,9 +120,9 @@ Commands have `disable-model-invocation: true` in their frontmatter.
 |---|---|
 | Edit existing file | Edit in `.agent-src.uncompressed/`, compress to `.agent-src/` |
 | Create new `.md` | Create in `.agent-src.uncompressed/`, compress to `.agent-src/` |
-| Create new non-`.md` | Create in `.agent-src.uncompressed/`, run `task sync` |
-| Create new command | Create in `.agent-src.uncompressed/commands/`, sync, `task generate-tools` |
+| Create new non-`.md` | Create in `.agent-src.uncompressed/`, run `bash scripts/compress.sh --sync` |
+| Create new command | Create in `.agent-src.uncompressed/commands/`, sync, `python3 scripts/compress.py --generate-tools` |
 | Delete a file | Delete from `.agent-src.uncompressed/` and `.agent-src/` |
-| Check what needs compression | `task sync-changed` |
-| Mark file as compressed | `task sync-mark-done -- {path}` |
-| Verify everything is in sync | `task sync-check` |
+| Check what needs compression | `bash scripts/compress.sh --changed` |
+| Mark file as compressed | `bash scripts/compress.sh --mark-done {path}` |
+| Verify everything is in sync | `bash scripts/compress.sh --check` |

package/.agent-src/rules/chat-history.md

@@ -0,0 +1,171 @@
+---
+type: "always"
+description: "Persist the conversation to .agent-chat-history for crash recovery — read on first turn, detect match/returning/foreign/missing, append on progress, honor per-profile frequency and overflow settings"
+alwaysApply: true
+source: package
+---
+
+# Chat History
+
+Persists the conversation to `.agent-chat-history` (JSONL, project root,
+git-ignored) so a crashed or switched agent session can be resumed. File
+I/O is owned by [`scripts/chat_history.py`](../../../scripts/chat_history.py)
+— this rule says **when** to call it, not how the file is structured.
+
+## Activation
+
+Read `chat_history.*` from `.agent-settings.yml` **once per conversation**
+(first turn). Cache the values.
+
+- `chat_history.enabled: false` **or** section missing → rule is a **no-op**
+  for the whole conversation. Do not read, write, or mention the file.
+- `chat_history.enabled: true` → cache `frequency`, `max_size_kb`,
+  `on_overflow` and proceed to the first-turn handshake.
+
+## First-turn handshake — four states
+
+Before executing the user's request, run:
+
+```bash
+scripts/chat_history.py state --first-user-msg "<msg>"
+```
+
+It prints exactly one of `match` | `returning` | `foreign` | `missing`.
+Branch:
+
+- `missing` → `init --first-user-msg "<msg>" --freq <frequency>`. Proceed
+  silently.
+- `match` → this chat already owns the file. Continue appending as cached.
+- `foreign` → a different session's file. Show **Foreign-Prompt** below.
+- `returning` → this chat once owned the file but another session took
+  over. Show **Returning-Prompt** below.
+
+In `foreign` and `returning`, **always read the file's current contents
+into the agent's working context before any write** — the user chose to
+log history for a reason; losing it silently is never acceptable.
+
+## Foreign-Prompt — new chat finds existing history
+
+Trigger: `state == foreign` **and** `status.entries >= 1`.
+
+```
+> 📒 Found chat history from an unknown session.
+>
+> Header fingerprint: <short-hash-A>
+> Current session:    <short-hash-B>
+> Entries on file:    <N>   Age: <age>
+>
+> 1. Resume — adopt this file, load entries as context, keep appending here
+> 2. New start — archive to .agent-chat-history.bak, init fresh
+> 3. Ignore — leave the file untouched, disable logging for this session
+```
+
+- `1` → `adopt --first-user-msg "<msg>"` (the old fp lands in
+  `former_fps` automatically). Read entries into context, then append
+  normally.
+- `2` → rename to `.agent-chat-history.bak`, then
+  `init --first-user-msg "<msg>" --freq <frequency>`.
+- `3` → logging disabled for this conversation; do not touch the file,
+  do not edit settings.
+
+Free-text replies ("weiter", "skip it") count as `3`.
+
+## Returning-Prompt — old chat comes back
+
+Trigger: `state == returning`. The file exists, its current owner is a
+different session, but this chat's fingerprint is in `former_fps`. The
+agent still has its own in-memory history of the turns it logged before
+the hand-off.
+
+```
+> 📒 Welcome back. This chat once owned the history file; another
+> session has written to it since.
+>
+> On-file entries:    <N>   Size: <X> KB   (now includes <M> foreign entries)
+>
+> (All three options read the on-disk entries into context first.)
+>
+> 1. Merge — my in-memory history first, the foreign entries after,
+>    overwrite the file with the combined body
+> 2. Replace — wipe the foreign entries, rewrite the file with my
+>    in-memory history only
+> 3. Continue — leave the file as-is; only new entries from now on
+```
+
+- `1` (Merge) → build the in-memory entries list (see below), call
+  `prepend --entries-json '<list>'`, then `adopt --first-user-msg "<msg>"`.
+- `2` (Replace) → build the in-memory list,
+  `reset --first-user-msg "<msg>" --freq <frequency> --entries-json '<list>'`.
+- `3` (Continue) → `adopt --first-user-msg "<msg>"`, then append normally.
+
+Free-text replies count as `3`.
+
+## Building the in-memory entries list (Merge / Replace)
+
+The agent reconstructs its own conversation as a JSON array, one entry
+per turn boundary. Keep it compact:
+
+- One `{"t":"user","text":"<preview>","ts":"<iso>"}` per user message.
+- One `{"t":"agent","text":"<preview>","ts":"<iso>"}` per agent reply.
+- `text` is a preview — flatten whitespace, cap at ~200 characters. This
+  is context, not a transcript.
+- Timestamps in ISO-8601 UTC. If the agent does not have exact times,
+  use the current time for all entries; order is what matters.
+- Do **not** include tool-call payloads, file contents, or secrets.
+
+If the list is large (>30 KB), pass it via stdin:
+`reset ... --entries-stdin <<< '<list>'`.
+
+## Append cadence — from `frequency`
+
+Every append goes through `scripts/chat_history.py append --type <t>
+--json '<obj>'`. Never write the file directly.
+
+- `per_turn` — one entry at the end of every agent turn.
+- `per_phase` — at phase boundaries (user question, agent answer,
+  decision, completion of a task-list item).
+- `per_tool` — after each tool-call sequence.
+
+Entry types: `user`, `agent`, `tool`, `decision`, `phase`. Prefer `phase`
+over `agent` when the entry marks a boundary.
+
+## Overflow — from `on_overflow`
+
+When the helper reports file size > `max_size_kb`:
+
+- `rotate` → `rotate --mode rotate --max-kb <n>`. Drops oldest entries;
+  silent and cheap.
+- `compress` → `rotate --mode compress --max-kb <n>`. Marks the file for
+  summarization; the **next** turn writes the summary for the dropped
+  range. Do not block the current turn on this.
+
+After Merge or Replace rewrites, run the overflow check once — the new
+body may exceed the budget.
+
+The setting is stable for the session; never mix modes.
+
+## What this rule does NOT do
+
+- Display, reload, or clear the log — that is `/chat-history`,
+  `/chat-history-resume`, `/chat-history-clear`.
+- Auto-flip `enabled` or `on_overflow` in settings.
+- Run when `enabled: false`. No silent logging. No telemetry.
+- Decide ownership heuristically. Only the `state` helper does that.
+
+## Interactions
+
+- `ask-when-uncertain` + `user-interaction` — foreign/returning prompts
+  use numbered options, one question per turn.
+- `language-and-tone` — prompt translated at runtime; `.md` stays English.
+- `onboarding-gate` — runs first; this rule activates only after it clears.
+- `token-efficiency` — never load the full log into context from this
+  rule; use `status` for metadata, `read --last N` for a tail.
+
+## See also
+
+- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — file API
+- [`/chat-history`](../commands/chat-history.md) — status inspection
+- [`/chat-history-resume`](../commands/chat-history-resume.md) — adopt + load
+- [`/chat-history-clear`](../commands/chat-history-clear.md) — wipe
+- [`agent-settings` template](../templates/agent-settings.md) — `chat_history.*` reference
+- [`rule-type-governance`](rule-type-governance.md) — why this is `always`

package/.agent-src/rules/docker-commands.md

@@ -44,12 +44,10 @@ docker compose exec -T <php-service> vendor/bin/phpunit
 
 ## Build / Task Runner
 
-Before using raw `docker compose exec` commands, check if a `Makefile` or `Taskfile.yml` exists.
-These often provide convenient shortcuts for common operations:
-
-- `Makefile` → `make console`, `make test`, `make phpstan`, etc.
-- `Taskfile.yml` → `task console`, `task test`, `task phpstan`, etc.
-
-**Always read the Makefile/Taskfile first** to discover available targets.
+Before using raw `docker compose exec`, check if the consumer project
+ships a `Makefile` — it often wraps common ops (`make console`,
+`make test`, `make phpstan`). Read the Makefile first. If the project
+uses another task runner, inspect its config before falling back to
+raw `docker compose exec`.
 
 Frontend commands (npm, webpack) run on the host or in the node container.

package/.agent-src/rules/docs-sync.md

@@ -47,15 +47,19 @@ When a skill is **added or its scope changes**, check and update:
 
 ## Settings template sync
 
-When skill/rule/command reads new setting from `.agent-settings.yml` not in `templates/agent-settings.md`:
-
-1. Add key with default to template
-2. Add row to Settings Reference table
-3. Add comment above key explaining it
-4. **Update local `.agent-settings.yml`** — add new key with default, preserve existing values,
-   apply template order and comments. Same behavior as `/config-agent-settings`, inline.
-
-**Mandatory** — without step 4, user can't discover new settings exist.
+When a skill, rule, or command **reads a new setting** from `.agent-settings.yml` that does not yet
+exist in `.augment/templates/agent-settings.md`:
+
+1. **Add the key** with its default value to the template block.
+2. **Add a row** to the Settings Reference table.
+3. **Add a comment** above the key explaining what it does.
+4. **Update the local `.agent-settings.yml`** — add the new key with its default value.
+   Preserve all existing values, apply template order and comments. Follow the
+   [section-aware merge rules](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+   so the user benefits immediately without running a separate command.
+
+**This step is mandatory.** If the template gains a new key but the local `.agent-settings.yml`
+is not updated, the user cannot discover the new setting exists.
 
 ## Content consistency
 

package/.agent-src/rules/improve-before-implement.md

@@ -40,8 +40,10 @@ Before coding, quickly verify:
 - Does similar functionality already exist?
 - Does it follow established patterns in the codebase?
 - Does it contradict existing conventions?
+- Do **multiple valid patterns/frameworks** already exist (Tailwind + Flux, multiple form libs, competing state stores)? If yes → do NOT pick arbitrarily, ask.
 
 **If misfit** → show evidence (file references), propose alternative.
+**If multiple valid options** → list them, ask which. See [`no blind implementation`](../guidelines/agent-infra/agent-interaction-and-decision-quality.md#2-no-blind-implementation).
 
 ### 3. Is the approach sound?
 

package/.agent-src/rules/onboarding-gate.md

@@ -0,0 +1,94 @@
+---
+type: "always"
+description: "First-run gate — when onboarding.onboarded is false in .agent-settings.yml, prompt the user to run /onboard before anything else"
+alwaysApply: true
+source: package
+---
+
+# Onboarding Gate
+
+Forces a one-time `/onboard` run for each developer on each project. This
+replaces the previously scattered "ask once" patterns across `user_name`,
+`personal.ide`, `personal.rtk_installed`, and cost profile confirmation.
+
+## When to activate
+
+Read `onboarding.onboarded` from `.agent-settings.yml` **once per
+conversation**, on the very first agent turn.
+
+- Key missing entirely → **legacy project**. Treat as onboarded, do
+  nothing. Do not write the key.
+- `true` → do nothing. Rule is inert for the rest of the conversation.
+- `false` → gate is active for this conversation (see below).
+
+Cache the result for the whole conversation. Do not re-read on every turn.
+
+## Gate behavior when `onboarded: false`
+
+On the **first** turn of the conversation, before executing the user's
+request, emit this prompt and stop:
+
+```
+> 👋 First-run setup hasn't been completed for this project.
+>
+> Run /onboard once (≈2 minutes) to capture:
+> • your name, IDE, and rtk status
+> • cost profile + learning loop confirmation
+>
+> 1. Run /onboard now
+> 2. Skip — mark as onboarded and continue with the request
+> 3. Snooze — continue just this turn; ask again next conversation
+```
+
+- `1` → invoke `/onboard`. Resume the user's original request afterwards.
+- `2` → set `onboarding.onboarded: true` in `.agent-settings.yml` (touch
+  only that field; preserve comments and order). Then execute the
+  original request.
+- `3` → proceed with the original request. Do not ask again in this
+  conversation. Do not write the file.
+
+Free-text replies (`"mach weiter"`, `"just do it"`) count as `3`.
+
+## Exceptions — do NOT block
+
+Skip the gate when the user's request already is an onboarding or
+settings operation, so we don't prompt users mid-setup:
+
+- `/onboard`, `/set-cost-profile`, `/mode`
+- The user explicitly asks about `.agent-settings.yml` or onboarding
+- Incident / break-glass signals (`hotfix`, `break-glass`, `"prod is
+  down"`). The gate waits for normal operations to resume.
+
+## Non-blocking for legacy projects
+
+If `.agent-settings.yml` exists but has no `onboarding` section at all,
+treat as onboarded. Only `onboarded: false` (explicit) triggers the
+gate. This protects projects that were set up before this rule shipped.
+
+## What this rule does NOT do
+
+- Write `onboarded: true` automatically. Only `/onboard` (step 6) and
+  the user's explicit `2` choice do that.
+- Re-prompt across turns in the same conversation. One prompt per
+  conversation, max.
+- Replace normal settings edits. Mid-life changes are ad-hoc (edit the
+  file directly or ask the agent, which follows
+  [`layered-settings`](../guidelines/agent-infra/layered-settings.md#section-aware-merge-rules));
+  this rule is a one-time gate.
+- Run on every agent turn. First turn only.
+
+## Interactions
+
+- `ask-when-uncertain` — the gate uses its numbered-options iron law;
+  one question per turn.
+- `language-and-tone` — prompt is translated to the user's language at
+  runtime; `.md` source stays English.
+- `scope-control` — option `2` writes exactly one key; no side effects.
+- `role-mode-adherence` — gate runs BEFORE the mode marker is emitted.
+
+## See also
+
+- [`/onboard`](../commands/onboard.md) — the command this gate invokes
+- [`layered-settings`](../guidelines/agent-infra/layered-settings.md) — merge rules for mid-life edits
+- [`agent-settings` template](../templates/agent-settings.md) — `onboarding.onboarded` reference
+- [`rule-type-governance`](rule-type-governance.md) — why this is `always`

package/.agent-src/rules/package-ci-checks.md

@@ -18,8 +18,8 @@ NEVER push without running ALL CI checks locally first.
 ### 1. Sync
 
 ```bash
-task sync-check            # .agent-src/ matches .agent-src.uncompressed/
-task sync-check-hashes     # compression hashes are clean
+bash scripts/compress.sh --check          # .agent-src/ matches .agent-src.uncompressed/
+bash scripts/compress.sh --check-hashes   # compression hashes are clean
 ```
 
 ### 2. Consistency
@@ -51,7 +51,8 @@ python3 scripts/readme_linter.py README.md --root .
 ## Quick one-liner
 
 ```bash
-task sync-check && task sync-check-hashes && \
+bash scripts/compress.sh --check && \
+bash scripts/compress.sh --check-hashes && \
 python3 scripts/check_compression.py && \
 python3 scripts/check_references.py && \
 python3 scripts/check_portability.py && \
@@ -64,8 +65,8 @@ python3 scripts/readme_linter.py README.md --root .
 
 1. Edit uncompressed file
 2. Edit compressed file in `.agent-src/` to match
-3. `task sync-mark-done -- {relative-path}` — update hash
-4. `task sync-check-hashes` — verify
+3. `bash scripts/compress.sh --mark-done {relative-path}` — update hash
+4. `bash scripts/compress.sh --check-hashes` — verify
 
 **Skip step 3 → CI WILL fail.**