@event4u/agent-config 1.14.0 → 1.15.0

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

@@ -73,7 +73,7 @@ Show the handoff prompt in a fenced code block and say:
   and without any persistent file.
 - [`/chat-history-resume`](chat-history-resume.md) is **pull-based**: the
   new chat reads `.agent-chat-history` from disk (written by the
-  [`chat-history`](../rules/chat-history.md) rule). Works only on the
+  [`chat-history`](../rules/chat-history-ownership.md) rule). Works only on the
   same machine and same repo, but captures more detail (every phase /
   tool call / decision the prior session logged).
 

package/.agent-src/commands/bug-fix.md

@@ -75,8 +75,8 @@ RISIKO-CHECK:
 For each change:
 
 1. **Read the file** before modifying.
-2. **Make the change** using `str-replace-editor`.
-3. **Check for downstream effects** — use `codebase-retrieval` to find callers.
+2. **Make the change** with the file-edit tool available to the agent.
+3. **Check for downstream effects** — search the codebase for callers.
 4. **Update related code** if signatures or behavior changed.
 
 ### 4. Quality checks

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

@@ -104,7 +104,7 @@ If the helper returned `skipped_cadence`, surface it:
 
 - The command writes through the same ownership-state machine as
   hooks — a `foreign` log triggers the
-  [`chat-history`](../rules/chat-history.md) Foreign-Prompt before any
+  [`chat-history`](../rules/chat-history-ownership.md) Foreign-Prompt before any
   append. This is intentional; the checkpoint must not silently
   hijack another session's log.
 - The `phase` payload key is required. Other keys are accepted but
@@ -117,7 +117,7 @@ If the helper returned `skipped_cadence`, surface it:
 
 ## See also
 
-- [`chat-history`](../rules/chat-history.md) — the rule defining the
+- [`chat-history`](../rules/chat-history-ownership.md) — the rule defining the
   conditional Iron Law (HOOK platforms vs CHECKPOINT/MANUAL platforms)
 - [`/chat-history`](chat-history.md) — read-only status display
 - [`/chat-history-resume`](chat-history-resume.md) — adopt + load

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

@@ -96,7 +96,7 @@ effect — this command is scoped to the file on disk only.
 
 ## See also
 
-- [`chat-history`](../rules/chat-history.md) — the rule that writes the file
+- [`chat-history`](../rules/chat-history-ownership.md) — the rule that writes the file
 - [`/chat-history`](chat-history.md) — status inspection
 - [`/chat-history-resume`](chat-history-resume.md) — load + adopt instead of wipe
 - [`agent-settings` template](../templates/agent-settings.md) — `chat_history.*` reference

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

@@ -17,7 +17,7 @@ flow: silent summarize, adopt, merge, or replace.
 
 Use after a crashed chat, after switching tools (Augment → Claude Code),
 or when the agent showed the foreign- or returning-session prompt from
-the [`chat-history`](../rules/chat-history.md) rule and the user picked
+the [`chat-history`](../rules/chat-history-ownership.md) rule and the user picked
 "resume".
 
 ## When NOT to use
@@ -174,7 +174,7 @@ the user decides what to do next.
 
 ## See also
 
-- [`chat-history`](../rules/chat-history.md) — the rule that triggers
+- [`chat-history`](../rules/chat-history-ownership.md) — the rule that triggers
   this command via the foreign- and returning-session prompts
 - [`/chat-history`](chat-history.md) — status inspection without adopting
 - [`/chat-history-clear`](chat-history-clear.md) — wipe instead of adopt

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

@@ -12,7 +12,7 @@ suggestion:
 # /chat-history
 
 Inspect `.agent-chat-history` — the JSONL log maintained by the
-[`chat-history`](../rules/chat-history.md) rule for crash recovery.
+[`chat-history`](../rules/chat-history-ownership.md) rule for crash recovery.
 
 Shows:
 
@@ -100,7 +100,7 @@ append may trigger overflow handling.
 
 ## See also
 
-- [`chat-history`](../rules/chat-history.md) — the rule that writes the file
+- [`chat-history`](../rules/chat-history-ownership.md) — the rule that writes the file
 - [`/chat-history-resume`](chat-history-resume.md) — adopt + load
 - [`/chat-history-clear`](chat-history-clear.md) — wipe
 - [`agent-settings` template](../templates/agent-settings.md) — `chat_history.*` reference

package/.agent-src/commands/check-current-md.md

@@ -9,23 +9,23 @@ suggestion:
 
 # check-current-md
 
-Manual runner for [`md-language-check`](../skills/md-language-check/SKILL.md).
-Use to spot-check an `.md` file the agent did not just edit, or to audit
-before opening a PR.
+Manual runner for the [`md-language-check`](../skills/md-language-check/SKILL.md)
+skill. Use to spot-check an `.md` file the agent did not just edit, or to
+audit a file before opening a PR.
 
 ## Instructions
 
 ### 1. Resolve target paths
 
-User passed paths → use those. Else default to the file currently open
-in the editor (per `personal.ide` open-file context). No file open and
-no path passed:
+If the user passed one or more paths, use those. Otherwise, default to
+the file currently open in the editor (per `personal.ide` open-file
+context). If no file is open and no path was passed:
 
 ```
 > ❌  No target file. Pass a path: /check-current-md path/to/file.md
 ```
 
-Stop.
+Stop here.
 
 ### 2. Run the checker
 
@@ -33,8 +33,11 @@ Stop.
 python3 scripts/check_md_language.py <path> [<path> …] --format json
 ```
 
-Exit codes: `0` clean, `1` violations (continue to step 3), `3`
-internal error (surface stderr, stop).
+Exit codes:
+
+- `0` → no findings; report and stop
+- `1` → findings present; continue to step 3
+- `3` → internal error; surface stderr and stop
 
 ### 3. Display findings
 
@@ -46,7 +49,7 @@ internal error (surface stderr, stop).
   Found: {count} violation(s) across {files} file(s)
 ```
 
-Per violation:
+For each violation:
 
 ```
   {file}:{line} — kind: {umlaut|de_word} — match: `{matched_text}`
@@ -57,14 +60,16 @@ Group by file when multiple files are scanned.
 
 ### 4. Classify and propose fixes
 
+For each violation, propose one of:
+
 | Cause | Proposed fix |
 |---|---|
-| German sentence in body prose | Translate to English |
+| German sentence in body prose | Translate the line to English |
 | Quoted German token used as example | Move into a labeled `DE: … · EN: …` block |
-| Meta-doc that documents trigger words | Append `<!-- md-language-check: ignore -->` to the line |
-| Intentionally bilingual but unlabeled | Reformat as labeled anchor block |
+| Meta-documentation that documents trigger words | Append `<!-- md-language-check: ignore -->` to the line |
+| Line is intentionally bilingual but unlabeled | Reformat as labeled anchor block |
 
-Summary:
+Present a summary:
 
 ```
   Proposed fixes:
@@ -76,20 +81,21 @@ Summary:
 > 3. Skip — report only
 ```
 
-Recommendation: **2 — Apply interactively** when ≥3 findings,
-**1 — Apply all fixes** for ≤2 findings or all-translation diffs.
+Recommendation: **2 — Apply interactively** when ≥3 findings, **1 —
+Apply all fixes** for ≤2 findings or when all are pure translations.
 
 ### 5. Apply fixes
 
 Edit only the source-of-truth file:
 
-- `.agent-src.uncompressed/` → edit directly
-- `.agent-src/` → edit the matching `.agent-src.uncompressed/` file,
-  then `bash scripts/compress.sh --sync`
-- `.augment/` → same as `.agent-src/` (it's a projection)
-- `agents/` → edit directly (no compression layer)
+- Path under `.agent-src.uncompressed/` → edit there directly
+- Path under `.agent-src/` → edit the matching
+  `.agent-src.uncompressed/` file instead, then run
+  `bash scripts/compress.sh --sync`
+- Path under `.augment/` → same as `.agent-src/` (it's a projection)
+- Path under `agents/` → edit directly (no compression layer)
 
-Re-run after fixes:
+After all fixes, re-run:
 
 ```bash
 python3 scripts/check_md_language.py <path> [<path> …]
@@ -97,27 +103,32 @@ python3 scripts/check_md_language.py <path> [<path> …]
 
 ### 6. Mark hashes (only if `.agent-src.uncompressed/` was edited)
 
+For each modified source file:
+
 ```bash
 python3 scripts/compress.py --mark-done "{relative_path}"
 ```
 
-Keeps `.compression-hashes.json` consistent.
+This keeps `.compression-hashes.json` consistent with the new content.
 
 ## Rules
 
-- **Never edit `.augment/` directly** — it's a generated projection
-  ([`augment-source-of-truth`](../rules/augment-source-of-truth.md))
-- **Per-line ignore marker** is reserved for meta-documentation that
-  must quote German tokens; not a generic mute
-- **Frontmatter is exempt** — checker skips it; don't try to "fix" it
-- **Do NOT commit or push** — leave the working tree to the user
+- **Never edit `.augment/` directly** — it's a generated projection.
+  Per [`augment-source-of-truth`](../rules/augment-source-of-truth.md),
+  the source is `.agent-src.uncompressed/`.
+- **Per-line ignore marker is reserved** for meta-documentation that
+  must quote German tokens; do NOT use it as a generic mute.
+- **Frontmatter is exempt** — the checker skips YAML frontmatter at
+  the head of the file; do not try to "fix" frontmatter.
+- **Do NOT commit or push** — finishing the check leaves the working
+  tree to the user.
 
 ## When NOT to use
 
 - Project content outside `.agent-src*/`, `.augment/`, or `agents/`
-  follows a different language policy
-- During autonomous edits the [`md-language-check`](../skills/md-language-check/SKILL.md)
-  skill already gates saves; this command is for **manual** spot-checks
+  follows a different language policy — do not enforce English there.
+- During autonomous edits, the [`md-language-check`](../skills/md-language-check/SKILL.md)
+  skill already gates saves; this command is for **manual** spot-checks.
 
 ## See also
 

package/.agent-src/commands/commit-in-chunks.md

@@ -11,10 +11,10 @@ suggestion:
 
 # commit-in-chunks
 
-Auto-split and commit all local changes in one go. Use when you want
-commits made without being asked to confirm each batch. Sibling of
-[`/commit`](commit.md), which waits for approval; this command skips
-that step.
+Auto-split and commit all local changes in one go. Use this when you
+want commits made without being asked to confirm each batch. Sibling
+of [`/commit`](commit.md), which presents the plan and waits for
+approval. This command skips the approval step.
 
 Per [`autonomous-execution`](../rules/autonomous-execution.md), the
 agent does **not** commit on its own initiative — invoking this
@@ -30,29 +30,36 @@ git diff --stat
 git diff --cached --stat
 ```
 
-No uncommitted changes → report "Nothing to commit." and stop.
+If there are no uncommitted changes (staged or unstaged), report
+"Nothing to commit." and stop.
 
 ### 2. Determine the ticket number
 
-- Extract ticket ID from current branch (e.g. `feat/DEV-1234/...` → `DEV-1234`).
-- No ticket ID → omit scope: write `chore: ...` not `chore(): ...`. Do **not** ask the user.
+- Extract the ticket ID from the current branch name (e.g. `feat/DEV-1234/...`
+  → `DEV-1234`).
+- If no ticket ID is found, omit the scope from the messages — write
+  `chore: ...` not `chore(): ...`. Do **not** ask the user for one.
 
 ### 3. Analyze and split
 
-Group changed files into logical units per [`/commit`](commit.md) step 3:
+Group changed files into logical units following [`/commit`](commit.md)
+step 3 grouping rules:
 
 - Same feature / fix → one commit.
 - Migration + corresponding model/seeder → one commit.
-- Test + class under test → one commit.
-- Style-only (ECS/Rector/formatter) → separate `style:` / `chore:` commit when mixed with logic.
+- Test + the class under test → one commit.
+- Style-only changes (ECS/Rector/formatter) → separate `style:` /
+  `chore:` commit when mixed with logic changes.
 - Truly unrelated change → its own commit.
 
 Splitting rules:
-- **Do NOT split arbitrarily** — only when logically independent.
+- **Do NOT split arbitrarily** — only when the changes are logically
+  independent.
 - **Prefer fewer, coherent commits** over many tiny ones.
-- **Tests go with the code they test** unless test-only changes are large and noisy.
+- **Tests go with the code they test** unless test-only changes are
+  large and noisy.
 
-Generate messages per [`commit-conventions`](../rules/commit-conventions.md).
+Generate commit messages per [`commit-conventions`](../rules/commit-conventions.md).
 
 ### 4. Commit immediately
 
@@ -63,10 +70,13 @@ git add {files...}
 git commit -m "{message}"
 ```
 
-No "looks good?" prompt. No confirmation. User invoked the command knowing the plan would execute.
+No "looks good?" prompt. No confirmation step. The user invoked this
+command knowing the plan would be executed.
 
 ### 5. Report
 
+Show a summary:
+
 ```
 Created N commits:
 1. {sha1}  feat(DEV-1234): {summary}
@@ -80,19 +90,29 @@ Include `git log --oneline -N` output for verification.
 
 - **Never push** — pushing remains explicit per [`scope-control`](../rules/scope-control.md#git-operations--permission-gated).
 - **Never modify files** — only stage and commit existing changes.
-- **Do NOT add untracked files** unless clearly part of the change (check `git status` first).
-- **Follow commit conventions** per [`commit-conventions`](../rules/commit-conventions.md).
-- **Stop on first failure** — if `git commit` fails (hook rejection, pre-commit lint error), stop, report, leave staged files for the user. Do not continue with remaining commits.
-- **No interactive prompts** — fail fast over hanging on input.
+- **Do NOT add untracked files** unless they are clearly part of the
+  change (check with `git status` first).
+- **Follow commit conventions** as defined in [`commit-conventions`](../rules/commit-conventions.md).
+- **Stop on first failure** — if `git commit` fails (hook rejection,
+  pre-commit lint error), stop, report the error, and do not continue
+  with the remaining planned commits. Leave staged files for the user
+  to inspect.
+- **No interactive prompts** — fail fast over hanging waiting for
+  input.
 
 ## When NOT to use
 
-- User hasn't seen the diff and would benefit from review → use [`/commit`](commit.md).
-- Diff includes large unrelated changes the user might want to reorganise → use [`/commit`](commit.md).
-- Repo has a pre-commit hook requiring manual response → fix the hook or use `/commit`.
+- The user has not seen the diff yet and would benefit from review →
+  use [`/commit`](commit.md) instead.
+- The diff includes large unrelated changes the user might want to
+  reorganise → use [`/commit`](commit.md).
+- The repo has a pre-commit hook that requires manual response → fix
+  the hook or use `/commit`.
 
 ## See also
 
 - [`/commit`](commit.md) — split + present plan + wait for approval
-- [`autonomous-execution`](../rules/autonomous-execution.md) — the rule that defines the no-ask commit default this command opts out of
-- [`commit-conventions`](../rules/commit-conventions.md) — message format
+- [`autonomous-execution`](../rules/autonomous-execution.md) — the
+  rule that defines the no-ask commit default this command opts out of
+- [`commit-conventions`](../rules/commit-conventions.md) — message
+  format

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

@@ -34,7 +34,8 @@ bash scripts/compress.sh --changed
 This lists only `.md` files whose source has changed since the last compression (based on
 stored SHA-256 hashes). If no files changed → you're done.
 
-If you need to see ALL files regardless of change status: `bash scripts/compress.sh --list`.
+If you need to see ALL files regardless of change status:
+`bash scripts/compress.sh --list`.
 
 ## Step 3: Compress each changed .md file
 
@@ -71,6 +72,7 @@ For each changed `.md` file:
    - Concrete validation checks
    - Gotchas based on real failure patterns
    - Anti-patterns that prevent recurring failures
+   - **Iron Law sections** — see "Iron Laws — do not touch" below
 5. **Enrich (SKILL.md files only):** During compression, also improve agent-effectiveness:
    - **Validation steps:** If a Procedure ends with a vague validation ("check if it works"),
      replace with concrete checks (expected output, commands to verify, specific conditions)
@@ -140,9 +142,39 @@ Show a summary table with per-category stats (files compressed, avg savings).
   (useful after an initial full compression or when bootstrapping the hash file).
 - A file with no stored hash is always treated as "changed".
 
+## Iron Laws — do not touch
+
+Sections under headings matching `Iron Law`, `Iron Laws`, or `The Iron Law` (any
+heading level, numbered variants like `Iron Law 1` included) are **load-bearing
+behavioral rules**. Compression rules above do **not** apply to them.
+
+For every Iron Law section in a source file:
+
+- **Copy the heading verbatim**, exact text, exact `#` level. NEVER downgrade
+  `## Iron Law` to `### Iron Law` or to inline `**Iron Law:**`.
+- **Copy the fenced code block byte-for-byte**, including capitalization, line
+  breaks, and trailing punctuation.
+- **Copy the negation clauses verbatim** — `NO X`, `NEVER Y`, `NOT Z`. These
+  are the law's exception denials; stripping them weakens the rule.
+- **Caveman the prose, keep every passage** — every paragraph, every list
+  item, and every fenced code block from the source must appear in the
+  compressed output, in order. Drop articles, shorten phrasing, primitive
+  grammar, terse cave-speak — all encouraged. What's forbidden is dropping
+  whole sentences, merging two paragraphs into one, or skipping a bullet.
+  One paragraph → one paragraph; one bullet → one bullet.
+- **No word-count budget** — compress the prose as hard as caveman style
+  allows. The check is structural (passage count), not quantitative.
+
+`scripts/check_compression.py` enforces these mechanically — `iron_law_missing`,
+`iron_law_passage_dropped`, and `iron_law_heading_downgrade` are `error`-level
+and block CI.
+
+If an Iron Law section genuinely contains filler (rare): edit the SOURCE in
+`.agent-src.uncompressed/`, not the compressed copy. Source is the truth.
+
 ## Compression quality checklist
 
-**Also apply the `preservation-guard` rule** — strongest validation, example, anti-pattern, and decision hints must survive compression.
+**Also apply the `preservation-guard` rule** — strongest validation, example, anti-pattern, and decision hints must survive compression. Iron Laws are non-negotiable.
 
 After compressing each file, verify:
 

package/.agent-src/commands/feature-roadmap.md

@@ -176,8 +176,8 @@ What's next?
 ### Rules
 
 - **Do NOT commit or push.**
-- **Do NOT include commit steps** unless user explicitly requested them.
-  See [`commit-policy`](../rules/commit-policy.md#never-write-commit-steps-into-roadmaps-unsolicited).
+- **Do NOT include commit steps in the roadmap** unless the user explicitly
+  requested them. See [`commit-policy`](../rules/commit-policy.md#never-write-commit-steps-into-roadmaps-unsolicited).
 - **Do NOT modify the feature plan** beyond updating the Roadmaps section and status.
 - **Always link roadmaps back to the feature** and vice versa.
 - **Use the roadmap template** from `agents/roadmaps/template.md`.

package/.agent-src/commands/fix-portability.md

@@ -92,8 +92,8 @@ python3 scripts/compress.py --mark-done "{relative_path}"
 
 ## Rules
 
-- **Always fix in `.agent-src.uncompressed/`** — never edit `.agent-src/` or `.augment/` directly.
-- **Run `bash scripts/compress.sh --sync`** after fixing to regenerate `.agent-src/` and `.augment/`.
+- **Always fix in `.agent-src.uncompressed/`** — never edit `.augment/` directly.
+- **Copy to `.augment/`** after fixing.
 - **Do NOT commit or push.**
 - **`agents/` directory is allowed** to have project-specific references — skip it.
 - **Do NOT fix references in code blocks** unless the code block is clearly a template.

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

@@ -8,6 +8,8 @@ suggestion:
   rationale: "Gated by the onboarding-gate rule already; never inferred from prose."
 ---
 
+<!-- cloud_safe: noop -->
+
 # /onboard
 
 Centralized first-run flow. Bundles what used to be scattered "ask once"
@@ -158,10 +160,10 @@ you ask it to change a value.
 
 ### 9. Maintainer-only feature pointer
 
-One-screen hint after the summary — no question, no prompt. Pointer for
-maintainers who want to opt into artefact-engagement telemetry. Consumers
-can ignore it; the feature is **default-off** and stays off unless
-explicitly enabled.
+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.
 
 ```
 ℹ️  Maintainer telemetry (opt-in)
@@ -172,7 +174,7 @@ explicitly enabled.
 
   The log is local-only JSONL — nothing uploaded, nothing shared across
   projects. Reports: ./agent-config telemetry:report
-  Contract + privacy floor: agents/contexts/artifact-engagement-flow.md
+  Contract + privacy floor: docs/contracts/artifact-engagement-flow.md
 ```
 
 Skip this block in cloud surfaces (no settings file, no log path).
@@ -187,6 +189,13 @@ Skip this block in cloud surfaces (no settings file, no log path).
 - Never overwrite a non-empty value without asking (applies to `user_name`
   and `ide`).
 
+## 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.
+
 ## See also
 
 - [`onboarding-gate`](../rules/onboarding-gate.md) — rule that triggers this command

package/.agent-src/commands/optimize-augmentignore.md

@@ -8,6 +8,8 @@ suggestion:
   rationale: "Niche maintenance tool with no recurring NL trigger."
 ---
 
+<!-- cloud_safe: noop -->
+
 # /optimize-augmentignore
 
 Scans the project to find files that waste tokens in Augment's retrieval index
@@ -263,3 +265,10 @@ echo "Rules ignored: $rules_count"
 - **Never ignore always-active rules** — only auto-loaded rules (those with `description` frontmatter) may be ignored.
 - **Never ignore meta/agent-system skills** — `agent-docs-writing-writing`, `commands`, `context-create`, `override-management`, `guidelines`, `project-docs`, `roadmap-management`, `naming`, `skill-reviewer`, `file-editor`, `copilot-config`, `copilot-agents-optimization`.
 - **Restore previously ignored skills** when the stack changes (e.g., Vue added to project → restore `vue` skill).
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) this command is **fully inert** —
+`.augmentignore` is an Augment-Code-specific retrieval-index config; it has
+no equivalent on the cloud surfaces and no file to write. Index pruning is
+a local-agent concern.

package/.agent-src/commands/refine-ticket.md

@@ -34,16 +34,18 @@ If no input resolves: ask **one** focused question:
 
 ### 2. Pick the output language
 
-Apply the skill's language-strategy block. First hit wins:
+Apply the skill's language-strategy block. Fallback order, first hit wins:
 
 1. **User-message language** — latest user message decides. Honours
    the global `language-and-tone` iron law.
-2. **Ticket body language** — minimal invocation (`/refine-ticket PROJ-123`
-   with no prose) mirrors the ticket's own language.
-3. **`.agent-settings.yml` default** — fallback when both silent; English
-   when absent.
-
-Quoted identifiers stay native; only prose mirrors the picked language.
+2. **Ticket body language** — when the invocation is minimal
+   (`/refine-ticket PROJ-123` with no prose), mirror the ticket's
+   own language (summary + description).
+3. **`.agent-settings.yml` default** — fallback when both are silent;
+   English when the setting is absent.
+
+Quoted identifiers (keys, paths, commands) stay native; only the
+prose mirrors the picked language.
 
 ### 3. Run the refine-ticket skill
 

package/.agent-src/commands/review-changes.md

@@ -1,6 +1,6 @@
 ---
 name: review-changes
-skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality]
+skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality, git-workflow]
 description: Self-review local changes before creating a PR — dispatches to four specialized judges (bug, security, tests, quality) and consolidates verdicts
 disable-model-invocation: true
 suggestion:
@@ -17,7 +17,29 @@ Review all uncommitted and committed-but-not-pushed changes against
 the default branch (`main`) by dispatching to four specialized judge
 sub-skills and consolidating their verdicts.
 
-### 1. Gather the diff
+### 1. Update the current branch
+
+Before gathering the diff, run [`/prepare-for-review`](prepare-for-review.md)
+to make sure the current branch is up to date with its base chain:
+
+- Detect the current branch with `git rev-parse --abbrev-ref HEAD`.
+- If the branch is `main` → skip this step (nothing to prepare).
+- Otherwise, search for an open GitHub PR whose head is the current
+  branch.
+  - If exactly one open PR is found → invoke `/prepare-for-review`
+    with that PR number. It will update `main`, fetch and merge the
+    full branch chain into the current branch, and leave the current
+    branch checked out.
+  - If no open PR is found → fall back to a minimal local update:
+    `git fetch origin main` and `git merge origin/main --no-edit` on
+    the current branch. Abort on conflict and report.
+  - If multiple PRs are found → ask the user which PR to use before
+    proceeding.
+- If `/prepare-for-review` aborts (merge conflict, network error,
+  etc.) → stop the review here and surface the error. Do **not**
+  continue with stale data.
+
+### 2. Gather the diff
 
 - `git diff origin/main..HEAD --stat` — overview of changed files
 - `git diff origin/main..HEAD` — full committed-but-not-pushed diff
@@ -25,7 +47,7 @@ sub-skills and consolidating their verdicts.
 
 If both diffs are empty, **stop** — nothing to review.
 
-### 2. Resolve the judge model
+### 3. Resolve the judge model
 
 Read `.agent-settings.yml`:
 
@@ -33,7 +55,7 @@ Read `.agent-settings.yml`:
 
 Unknown alias → stop. Never silently fall back.
 
-### 3. Dispatch to the four judges
+### 4. Dispatch to the four judges
 
 Each judge receives **the same diff plus the task context** (ticket,
 PR body, commit messages) and runs independently. The judges are:
@@ -59,7 +81,7 @@ Pick dispatch mode based on diff size and environment:
 Each judge returns its own `Judge / Model / Target / Verdict /
 Issues` block in the format defined by that skill.
 
-### 4. Consolidate
+### 5. Consolidate
 
 Produce one combined report:
 
@@ -69,7 +91,7 @@ Produce one combined report:
 - Highlight any finding that multiple judges flagged — those are the
   highest-confidence items
 
-### 5. Decide next steps
+### 6. Decide next steps
 
 - If **any** judge returned `reject` → stop; the approach must change
   before proceeding
@@ -77,7 +99,7 @@ Produce one combined report:
   ask before fixing 🟡 findings, report 🟢 as suggestions
 - If all four returned `apply` → the diff is ready; report and stop
 
-### 6. Quality tools (optional)
+### 7. Quality tools (optional)
 
 After the consolidated report, ask:
 
@@ -97,8 +119,12 @@ or the equivalent configured command).
   files still gets coverage feedback — `judge-test-coverage` treats
   "production changed, no test changed" as its primary finding
 - Project-specific syntax checks (e.g. `php -l`, linter pre-pass) are
-  out of scope for the judges and belong in the optional step 6
+  out of scope for the judges and belong in the optional step 7
   quality tools hand-off
+- The new step 1 (`/prepare-for-review`) is **best-effort**: if no
+  open PR exists for the current branch, it falls back to a plain
+  `git fetch && git merge origin/main`. Existing invocations that
+  ran on a fully detached or pre-PR branch keep working
 
 ## Use this command when
 
@@ -119,6 +145,7 @@ or the equivalent configured command).
 
 ## See also
 
+- [`/prepare-for-review`](prepare-for-review.md) — updates `main` and merges the full base-branch chain into the target branch (used by step 1)
 - [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md) — dispatch and model-pairing rules
 - [`/do-and-judge`](do-and-judge.md) — implementer + judge loop for a single change
 - [`/judge`](judge.md) — standalone judge, no review-changes dispatch