@event4u/agent-config 1.20.0 → 1.22.0

package/.agent-src/commands/challenge-me/with-docs.md

@@ -0,0 +1,333 @@
+---
+name: challenge-me:with-docs
+cluster: challenge-me
+sub: with-docs
+description: "Doc-aware /challenge-me — 95%-confidence interview with session glossary vs CONTEXT.md, load-bearing claim-vs-code verification, optional CONTEXT.md patch + ADR candidates in the pitch."
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "challenge me against the docs, grill me with our context, grill me against the docs, grill me against CONTEXT.md, grill me with the project context, frag mich durch und prüf gegen CONTEXT.md, challenge plan with domain docs"
+  trigger_context: "user wants the seed challenged against existing project glossary, CONTEXT.md, or ADRs — not a greenfield interview"
+---
+
+# /challenge-me with-docs
+
+> Same one-question-at-a-time interview as `/challenge-me vision`, plus:
+> a **session glossary** against `CONTEXT.md`, **load-bearing claim-vs-code
+> verification**, and an optional `CONTEXT.md` **patch** + **ADR candidates**
+> appended to the final pitch. Nothing is written to disk — the pitch is
+> the only artefact.
+
+## Welcome
+
+If the user invokes `/challenge-me with-docs` with no body, render once:
+
+```
+Drop the seed and I'll grill it against your project docs. Per turn:
+one question, recommended answer. I'll surface glossary clashes vs
+CONTEXT.md and verify load-bearing claims against the code. At the end
+you get a pitch — plus an optional CONTEXT.md patch and ADR candidates
+to copy / apply yourself.
+
+Stop early any time by typing `!pitch` (or `!Vision pitchen`).
+```
+
+Skip the welcome if the user invokes `/challenge-me with-docs <seed>`
+directly.
+
+## When to use this instead of `vision`
+
+| Condition | Pick |
+|---|---|
+| Project has no `CONTEXT.md` and no ADR dir | `vision` |
+| Seed uses domain terms that may already be defined elsewhere | `with-docs` |
+| User says "check against our docs" / "make sure it matches CONTEXT.md" | `with-docs` |
+| User says "make sure this is consistent with the codebase" | `with-docs` |
+| Greenfield brainstorm, no existing constraints to honour | `vision` |
+
+If neither file exists and the user invoked `with-docs` anyway, fall
+back gracefully to `vision`-style flow and skip the doc inventory; note
+the absence in a single line at the end of Step 0.
+
+## Stop condition, flags, pitch trigger
+
+Inherits **verbatim** from [`vision.md`](vision.md):
+
+- Default stop = the four 95%-conditions (AND, not OR).
+- Load-bearing test = answer changes goal / scope / hard constraint / AC.
+- `--until=95%` (default) · `--until=N` · `--keep-going`.
+- Pitch trigger: `!pitch`, `/pitch`, or whole reply `pitch`.
+- Step 1 question-block shape, Step 4 pitch validation.
+
+The deltas below replace / extend Step 0, Step 1, Step 2, Step 4 and
+Step 5. Steps 3 and 6 are unchanged.
+
+## Steps
+
+### Step 0 — Inspect (read-only doc inventory + codebase)
+
+```
+EXPLORE THE DOCS AND THE CODEBASE BEFORE THE FIRST QUESTION.
+NEVER WRITE TO DISK IN STEP 0. NEVER ASK WHAT view / grep / codebase-retrieval ANSWERS.
+```
+
+1. **Read the seed** (same as `vision`).
+2. **Doc inventory** — read-only:
+   - `view CONTEXT.md` if it exists; init empty **session glossary** in
+     agent state (in-memory only).
+   - `view CONTEXT-MAP.md` if it exists. If the seed touches > 1 listed
+     context, **ask once** (numbered options listing each context) which
+     to focus on; record the choice, do not re-ask.
+   - Autodetect ADR directory by listing `docs/adr/`, `docs/decisions/`,
+     `docs/architecture/decisions/`, `agents/decisions/`. Pick the
+     **most-recently-modified** non-empty dir; if none exist, default to
+     `docs/adr/` for the patch output (do **not** create the dir).
+   - If `agent state` already holds a session glossary from a prior
+     `/challenge-me with-docs` invocation **in this same chat**, load
+     it. Then re-read `CONTEXT.md` — any term in `CONTEXT.md` overrides
+     the session glossary (disk wins over draft). Emit a delta line if
+     non-zero: `Loaded N draft terms; CONTEXT.md already has X — carrying
+     forward the rest as drafts.`
+3. **Codebase lookup** — same as `vision` Step 0.2 (existing routes,
+   model fields, conventions, feature flags).
+4. **List the open dimensions** internally — same as `vision` Step 0.3.
+
+### Step 1 — Glossary-aware questioning
+
+Every question block runs an extra check **before** emit:
+
+- **Glossary conflict** — does the seed (or a prior turn) use a term
+  that conflicts with the existing `CONTEXT.md` glossary, including a
+  case-insensitive match? → first question of the session is the
+  glossary disambiguation:
+
+  > Your `CONTEXT.md` defines **Account** as the billing entity. Your
+  > seed uses "account" for the logged-in person. Which is it?
+  > 1. **Match CONTEXT.md** — rename "account" in the plan to "user".
+  > 2. Override CONTEXT.md — the plan introduces a new meaning; we patch
+  >    the glossary at pitch time.
+  > 3. Skip / not relevant.
+
+- **Fuzzy / overloaded term** — propose a canonical term as option 1.
+
+- **No glossary present** → skip the check; behave like `vision`.
+
+The glossary check is itself **load-bearing only when the term flips an
+AC or scope boundary OR when it conflicts with an existing CONTEXT.md
+entry**. Pure naming preference with no conflict is closed silently
+(same load-bearing test as `vision`, with the conflict-extension).
+
+Otherwise the question-block shape, recommended-option rule, 3–4 option
+cap, and `Why it matters` requirement are identical to
+[`vision.md § Step 1`](vision.md#step-1-ask-one-question-per-turn).
+
+### Step 2 — Apply the answer + session glossary (in-memory)
+
+Adopt-the-answer rules are identical to
+[`vision.md § Step 2`](vision.md#step-2-apply-the-answer).
+
+When a term is resolved, write to **session glossary** (agent state
+only). **Never write to disk in this step.** Every turn's reply ends
+with a compact echo block when the glossary is non-empty:
+
+```
+**Session glossary (draft, not yet written):**
+- **Cancellation** — refund + reversal, excludes disputes (turn 3)
+- **Account** — maps to `User` entity (turn 5)
+```
+
+After the **fifth** session-glossary turn, condense the echo to:
+
+```
+**Session glossary (draft):** N terms · M ADR candidates — see pitch for full list.
+```
+
+If the session glossary is empty, omit the echo block entirely.
+
+### Step 3 — Re-score and continue
+
+Identical to [`vision.md § Step 3`](vision.md#step-3-re-score-and-continue).
+
+### Step 3.5 — ADR candidate check (no write)
+
+After each branch closes, run the three-test on the resolution:
+
+1. **Hard-to-reverse** — would unwinding it require code or schema rollback?
+2. **Surprising-without-context** — would a future contributor read the
+   choice and ask "why this and not the obvious alternative?"
+3. **Result of a real trade-off** — were the rejected options realistic?
+
+If **all three** pass, append the candidate to an in-memory ADR-candidate
+list. Do **not** ask, do **not** write. Surfaces only in Step 5.
+
+### Step 4 — Validate before pitching
+
+Identical to [`vision.md § Step 4`](vision.md#step-4-validate-before-pitching),
+plus:
+
+- Pitch uses the **canonical glossary spelling** for every term in the
+  session glossary.
+- The `CONTEXT.md` patch block is **always** appended when the session
+  glossary is non-empty — agent has no signal whether the user already
+  applied a previous patch in-chat. The patch block carries a header
+  the user reads before applying (see Step 5).
+
+### Step 5 — Emit the pitch with optional doc patches
+
+Emit the same fenced Markdown pitch as `vision`, then append up to two
+optional sections **inside** the same outer four-backtick fence:
+
+`````markdown
+````markdown
+# <one-line vision title>
+
+**Goal:** <verb + object + observable result>
+
+**In scope:**
+- <bullet>
+
+**Out of scope:**
+- <bullet>
+
+**Constraints (hard):**
+- <bullet>
+
+**Acceptance criteria:**
+1. <observable, testable>
+
+**Open assumptions:**
+- assumes: <line>
+
+**Recommended next step:** <one sentence — e.g. "/work \"<pitch goal>\"" >.
+
+---
+
+**CONTEXT.md patch (apply via `patch -p1` or your IDE's Apply Patch — only
+if you haven't already merged these terms):**
+
+```diff
+@@ ... @@
++ ## Cancellation
++ Refund + reversal, excludes disputes.
+```
+
+**ADR candidate(s) — apply only if useful:**
+- `docs/adr/0007-cancellation-semantics.md` — captures the soft-vs-hard
+  delete decision (hard-to-reverse · surprising · real-tradeoff).
+
+**Glossary touched this session:** Cancellation, Account, Refund (3 terms).
+````
+`````
+
+The outer fence uses **five backticks** so the inner four-backtick fence
+(which itself contains a triple-backtick diff) stays literal when the
+user copies the whole block.
+
+Omission rules:
+
+- Session glossary empty → omit the `CONTEXT.md patch`, `Glossary touched`,
+  and the preceding `---` separator entirely.
+- No ADR candidate qualified → omit the `ADR candidate(s)` section.
+- Both empty → pitch is identical to a `vision` pitch.
+
+### Step 6 — Hand back
+
+Identical to [`vision.md § Step 6`](vision.md#step-6-hand-back). Never
+auto-write the patches, never auto-invoke `/work`.
+
+## Code-vs-claim guard (gated)
+
+When the user states "X is implemented as Y" AND the claim is
+**load-bearing** (would change an AC, scope boundary, or hard
+constraint), agent runs `view` / `grep` / `codebase-retrieval` to
+verify. Mismatch → single question block:
+
+> Your seed says X works via Y. The code (`path/to/file.php:123`) shows
+> it via Z. Which is right?
+> 1. **Code is right, my seed was wrong** — recommended.
+> 2. Seed is right, code is stale — separate fix needed.
+> 3. Both — they're both real paths.
+
+Non-load-bearing claims (cosmetic, naming, internal style) — agent
+trusts the user's statement, no lookup. This gate keeps verification
+cost O(load-bearing-decisions), not O(every-statement).
+
+## Output format
+
+1. **Per-turn question block** — one numbered question with a
+   recommended option, until 95% or pitch trigger.
+2. **Session-glossary echo** — appended every turn while the glossary is
+   non-empty (full list in turns 1–5, condensed line from turn 6 on).
+3. **Final pitch** — a single copyable five-backtick fenced block
+   (Step 5 shape) holding the standard pitch + optional `CONTEXT.md`
+   patch + optional ADR candidates.
+
+## Examples
+
+```
+/challenge-me with-docs
+/challenge-me with-docs Add a per-tenant rate limit on the public API
+/challenge-me with-docs --until=5 Migrate cancellations from soft-delete to hard-delete
+/challenge-me with-docs --keep-going Re-architect the notifications pipeline
+```
+
+## Gotchas
+
+- Inherits every gotcha from
+  [`vision.md § Gotchas`](vision.md#gotchas) — confidence inflation,
+  recommendation drift, stacked questions, too many options.
+- **Glossary clutter** — if the agent echoes the full session glossary
+  past turn 5 the reply gets noisy. Condense per Step 2.
+- **Patch redundancy** — agent has no signal whether the user already
+  applied a previous in-chat `CONTEXT.md` patch. Always emit the patch
+  with the "only if you haven't already merged these terms" header so
+  the user can dedupe.
+- **ADR over-eager** — the three-test (hard-to-reverse · surprising ·
+  real-tradeoff) is the gate. A pure naming choice or a default that
+  could flip without rollback is **not** an ADR candidate.
+- **Multi-context confusion** — if `CONTEXT-MAP.md` lists multiple
+  contexts and the seed touches several, ask **once** in Step 0; never
+  re-ask which context to focus on.
+
+## Rules
+
+- Inherits every rule from [`vision.md § Rules`](vision.md#rules) —
+  one question per turn, no auto-execution, no file writes, codebase
+  first, welcome once, mirror the user's language.
+- **No file writes** — even though this variant produces glossary
+  patches and ADR candidates, those go **into the pitch block** for the
+  user to apply. Agent never writes `CONTEXT.md` or any `docs/adr/*`
+  file itself, per `non-destructive-by-default`.
+- **Two-gate verification** — the glossary check fires on AC-flipping
+  terms OR `CONTEXT.md` conflicts; the code-vs-claim check fires only
+  on load-bearing claims. Non-load-bearing trivia → no lookup, no
+  question.
+- **Session glossary persists within a chat** — a second
+  `/challenge-me with-docs` invocation in the same chat inherits draft
+  terms; disk state (`CONTEXT.md`) overrides drafts on every Step 0.
+
+## Do NOT
+
+- Inherits every prohibition from
+  [`vision.md § Do NOT`](vision.md#do-not).
+- Do NOT write to `CONTEXT.md` directly — emit the diff in the pitch.
+- Do NOT create files in `docs/adr/` — emit the path + rationale in the
+  pitch and let the user create the file.
+- Do NOT verify every user statement — only load-bearing claims trigger
+  the code-vs-claim guard.
+- Do NOT echo the full session glossary past turn 5 — condense.
+
+## See also
+
+- [`/challenge-me vision`](vision.md) — sibling without doc inventory,
+  glossary check, or claim verification.
+- [`/refine-prompt`](../refine-prompt.md) — one-shot prompt scoring.
+- [`/refine-ticket`](../refine-ticket.md) — ticket reconstruction.
+- [`ask-when-uncertain`](../../rules/ask-when-uncertain.md) — the
+  one-question-per-turn Iron Law.
+- [`non-destructive-by-default`](../../rules/non-destructive-by-default.md)
+  — why the patches live in the pitch block, not on disk.
+- Inspiration: `mattpocock/skills/skills/engineering/grill-with-docs/SKILL.md`
+  — same intent (interview against domain docs), restructured to honour
+  the project's non-destructive floor (session glossary in-memory,
+  patches emitted as copyable diffs in the pitch).

package/.agent-src/commands/challenge-me.md

@@ -0,0 +1,61 @@
+---
+name: challenge-me
+description: Challenge-me orchestrator — routes to vision, with-docs
+cluster: challenge-me
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "challenge me on this plan, grill me, grill me on this, grill me on this plan, grill me through this, grill me until it's clear, grill me hard, frag mich durch, dreh mich durch die Mangel, challenge against existing docs/glossary"
+  trigger_context: "user has a fuzzy plan/idea/feature draft and wants it sharpened interactively rather than reconstructed in one shot — also reachable via /grill-me alias"
+---
+
+# /challenge-me
+
+Top-level orchestrator for the `/challenge-me` family. Walks a decision
+tree by asking one question at a time until the agent is confident
+enough to emit a copyable Markdown pitch.
+
+> Also reachable as [`/grill-me`](grill-me.md) — thin alias, identical
+> behaviour, identical sub-commands and triggers.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/challenge-me vision` | `commands/challenge-me/vision.md` | Standard variant — interrogate a fuzzy plan / idea / ticket draft to 95% confidence, emit a vision pitch |
+| `/challenge-me with-docs` | `commands/challenge-me/with-docs.md` | Doc-aware variant — same flow plus session glossary against `CONTEXT.md`, load-bearing claim-vs-code verification, optional `CONTEXT.md` patch + ADR candidates in the pitch |
+
+## When to pick which
+
+- **`vision`** — greenfield idea, fresh ticket draft, or a plan with no
+  existing project glossary / domain docs. Default for "challenge me on
+  this plan".
+- **`with-docs`** — the project has `CONTEXT.md`, an ADR directory
+  (`docs/adr/`, `docs/decisions/`, `agents/decisions/`), or the user
+  uses domain terms that may already be defined. The variant catches
+  glossary conflicts and load-bearing claim-vs-code drift before pitch.
+
+## Dispatch
+
+1. Parse the user's argument: `/challenge-me <sub-command> [flags] [seed]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Steps` section
+   verbatim with the remaining flags / seed.
+4. If the sub-command is unknown or missing, print the menu and ask:
+
+   > 1. vision — standard 95%-confidence interview, emits a copyable pitch
+   > 2. with-docs — same flow, but checks the seed against `CONTEXT.md` /
+   >    ADRs and emits an optional doc patch in the pitch
+
+## Rules
+
+- **Do NOT chain sub-commands.** One `/challenge-me <sub>` per turn.
+- If the user invokes `/challenge-me` with no argument, **show the menu**
+  — do not guess which sub-command they meant.
+- **No file writes from either sub-command.** Both variants are
+  conversational; the pitch is the only artefact, and it is copyable
+  Markdown the user pastes elsewhere. `with-docs` emits its `CONTEXT.md`
+  patch and ADR candidates inside the same pitch block — agent does not
+  apply them itself.
+- **Mirror the user's language** — sub-commands inherit the
+  `language-and-tone` Iron Law for question blocks and pitch.

package/.agent-src/commands/chat-history/import.md

@@ -2,31 +2,30 @@
 name: chat-history:import
 cluster: chat-history
 sub: import
-description: Surface prior chat-history sessions as numbered options, let the user pick exactly one, then render its entries verbatim into the current chat — selective, user-driven cross-session import
+description: Surface prior chat-history sessions as a numbered table, let the user pick one, read it silently, and emit a short summary plus a resume offer — selective, user-driven cross-session import
 disable-model-invocation: true
 suggestion:
   eligible: true
   trigger_description: "import a past session into the current chat, pull a prior session into context, pick a session to read"
-  trigger_context: "user wants to selectively pull verbatim context from one earlier session into the current one"
+  trigger_context: "user wants to selectively pull a prior session's context into the current one as a short summary"
 ---
 <!-- cloud_safe: noop -->
 
 # /chat-history import
 
 Read-only, **user-driven** cross-session import. Surfaces prior
-sessions logged in `agents/.agent-chat-history` as numbered options, the
-user picks **one**, the agent reads that session's entries
-**verbatim** and renders them in the chat. Any subsequent
-extraction or summarisation happens in dialogue, user-directed —
-the agent does **not** auto-summarise, auto-import, or rewrite the
-user's context (Council Round 2 / R2-2 — verbatim is the honest v1
-contract).
+sessions logged in `agents/.agent-chat-history` as a numbered table,
+the user picks **one**, the agent reads that session **silently**
+and emits a 2–5 sentence summary, then offers to resume the last
+task from that session. The agent does **not** render entries
+verbatim, auto-import, or rewrite the user's context without an
+explicit instruction.
 
 This is the opt-in counterpart to the read-path filter (Phase 3 of
 `road-to-chat-history-session-isolation`): default reads stay
 session-scoped; `import` is the explicit surface for crossing the
-session boundary verbatim. For project-improving learnings derived
-from a prior session, see [`/chat-history learn`](learn.md).
+session boundary. For project-improving learnings derived from a
+prior session, see [`/chat-history learn`](learn.md).
 
 ## When NOT to use
 
@@ -70,33 +69,35 @@ If the array is empty, stop:
 > 📒 No prior sessions found in agents/.agent-chat-history.
 ```
 
-### 3. Surface as numbered options
+### 3. Surface as a numbered table
 
-Render each session as a numbered option (per the `user-interaction`
-rule — Iron Law: numbered options for any picker). Lead with the
-helper's `summary` field — that is the rough arc the user picks by
-(`<first user msg> → <last user msg>` for normal sessions, or
-`(N entries — no user prompts; t-mix: …)` for tool-only sessions).
-The session `id` is noise to humans; keep it **internal** for step
-5's `read --session <id>` call and never render it in the listing.
+Render the sessions as a markdown table — the row number is the
+option (per `user-interaction` Iron Law: numbered options for any
+picker). The session `id` is noise to humans; keep it **internal**
+for step 5's `read --session <id>` call and never render it.
 Format:
 
 ```
-> Pick a session to import verbatim:
->
-> 1. {summary}
->    {YYYY-MM-DD HH:MM}  ·  {count} entries
-> 2. ...
-> ...
-> N. abort — do not read any session
+Pick a session to import:
+
+| #  | Date             | Entries | Summary |
+|----|------------------|---------|---------|
+| 1  | YYYY-MM-DD HH:MM | N       | {summary} |
+| 2  | YYYY-MM-DD HH:MM | N       | {summary} |
+| …  |                  |         |           |
+| N  | —                | —       | abort — do not read any session |
 ```
 
 Format the timestamp as `YYYY-MM-DD HH:MM` (drop seconds and
-timezone — the listing is for orientation, not forensics). Do
-**not** truncate or rewrite `summary` — the helper already shapes
-it. Always include an explicit abort option as the last numbered
-choice. Track option-number → `id` internally so step 5 can call
-`scripts/chat_history.py read --session <id>` with the right id.
+timezone — the listing is for orientation, not forensics). Lead the
+`Summary` cell with the helper's `summary` field — that is the
+rough arc the user picks by (`<first user msg> → <last user msg>`
+for normal sessions, or `(N entries — no user prompts; t-mix: …)`
+for tool-only sessions). Do **not** truncate or rewrite `summary` —
+markdown table wrap handles long values. Always include an explicit
+`abort` row as the last numbered option. Track option-number → `id`
+internally so step 5 can call `scripts/chat_history.py read
+--session <id>` with the right id.
 
 ### 4. Wait for the pick
 
@@ -106,51 +107,46 @@ default. Wait for the user's response.
 
 If the user picks the abort option, stop without reading.
 
-### 5. Read the picked session verbatim
+### 5. Read the picked session silently
 
-Run `scripts/chat_history.py read --session <id>` with the picked
-`id`. The helper returns the entries as JSON.
+Run `scripts/chat_history.py read --session <id> --last <count>`,
+where `<count>` is the picked row's `count` from step 2. The
+`--last` flag is **required** — the helper defaults to 5 entries,
+which would silently truncate any longer session. The helper returns
+the entries as JSON.
 
-Render them **verbatim** in the chat — do not summarise, do not
-re-format, do not drop fields. One entry per line is acceptable;
-preserve `t`, `text`, `name`, `ts`, and any other fields the helper
-emits. Use a fenced block so timestamps and JSON survive markdown
-rendering:
+**Do not render the entries.** The verbose dump was reversed by the
+user — token cost and scroll fatigue outweighed the verbatim
+contract. Read the JSON in-context, then proceed to step 6.
 
-````
-> 📒 Session {id} — {count} entries
+### 6. Summarise and offer to resume
 
-```json
-{...entry 1...}
-{...entry 2...}
-...
-```
-````
-
-If the session is large (>50 entries), still render verbatim — but
-prepend a one-line note that the listing is long, so the user can
-scroll. Do not silently truncate.
-
-### 6. Hand back
+Emit a **2–5 sentence** summary of the picked session: the topic,
+what was decided or built, and where it left off (the last task in
+progress, if any). Plain prose — no bullets, no headings, no
+verbatim quotes.
 
-After rendering, **do not** auto-act on the content. Hand back to
-the user with a short prompt:
+Then offer the resume choice as numbered options
+(per `user-interaction`), one question per turn:
 
 ```
-> Picked session is rendered above. What would you like to extract?
+1. resume — pick up the last task from that session
+2. stop — keep the summary in context, do nothing else
 ```
 
-Any follow-up (extract decisions, copy specific entries into the
-current session, etc.) is user-directed in subsequent turns. The
-agent does not write to the current session's log on the user's
-behalf without an explicit instruction.
+Wait for the pick. Do **not** auto-resume. If the user picks
+`resume`, hand off to the relevant skill or command for that work;
+do not silently start editing files. The agent does not write to
+the current session's log on the user's behalf without an explicit
+instruction.
 
 ## Gotchas
 
-- **Verbatim, not structured.** Council Round 2 (R2-2) resolved an
-  earlier contradiction in favour of verbatim. Do not "helpfully"
-  pre-summarise — the user reads the source, then directs the
-  extraction.
+- **Summary, not verbatim.** Earlier Council R2-2 favoured verbatim
+  rendering; reversed in practice — too slow, too token-expensive.
+  The agent reads the picked session in-context and emits a 2–5
+  sentence summary. Verbatim rendering is no longer part of the
+  contract.
 - **One pick per invocation.** Multi-pick is v2. If the user wants
   a second session, run `/chat-history import` again.
 - **Read-only.** This command never writes to `agents/.agent-chat-history`

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

@@ -50,6 +50,18 @@ For each changed `.md` file:
      pleasantries, hedging, connective fluff (however, furthermore, additionally),
      redundant wording, obvious framework knowledge, repeated explanations, decorative prose
    - **Shorten:** "in order to" → "to", "make sure to" → "ensure", use short synonyms
+   - **Abbreviate** common terms when context unambiguous: `DB`, `auth`,
+     `config`, `req`, `res`, `fn`, `impl`, `env`, `deps`, `ctx`. Skip on
+     first occurrence of the concept in the file, or when the
+     abbreviation collides with a domain term (`auth` stays
+     `authentication` inside an auth-module file). Never abbreviate
+     inside code blocks, frontmatter, file paths, command strings, or
+     Iron Law fenced blocks.
+   - **Arrows for causality:** `X causes Y` / `X leads to Y` / `X, then Y`
+     → `X → Y`. Keep arrows out of code blocks, frontmatter, and Iron
+     Law fenced blocks; surrounding prose only. (Example phrases
+     backticked on purpose — inline-code protection skips them; never
+     strip the backticks.)
    - **Fragments OK:** "Run tests before commit" not "You should always run tests before committing"
    - **Drop:** "you should", "make sure to", "remember to" — state action directly
    - **Merge** redundant bullets that say the same thing differently

package/.agent-src/commands/context/create.md

@@ -76,9 +76,9 @@ Based on the type, analyze the relevant code area:
 - Identify all models and tables involved
 
 **Service context:**
-- Read the service class and its dependencies
+- Read the service class and its deps
 - Trace call chain (who calls it, what it calls)
-- Identify configuration and env dependencies
+- Identify configuration and env deps
 
 **Integration context:**
 - Find API client classes, HTTP calls

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

@@ -22,7 +22,7 @@ commands with a single entry point + sub-command dispatch.
 | `/context refactor` | `commands/context/refactor.md` | Analyze, update, and extend an existing context document |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch
 

package/.agent-src/commands/copilot-agents.md

@@ -22,7 +22,7 @@ standalone commands with a single entry point + sub-command dispatch.
 | `/copilot-agents optimize` | `commands/copilot-agents/optimize.md` | Refactor existing AGENTS.md and copilot-instructions.md for line budgets |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
 
 ## Dispatch