feat(agents): let read-only CR agents use git worktrees for parallel review

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to `cursor-rules` will be documented in this file.
 
 ## [Unreleased]
 
+- 📝 **Changed**: the read-only **code-review agents (`argos`, `athena`) may now opt into an isolated git worktree** to run their parallel CR pass when isolation is genuinely needed, and **`daidalos` cleans every CR worktree up** after the run / merge so the repository and codebase stay clean. This refines the earlier *git worktrees are forbidden across the whole workflow* policy: the **writing path (`talos`) still never uses worktrees** and concurrent writers still serialise on the single shared working tree via the write-lock — only the read-only CR pass gains the explicit-request opt-in of `@rules/git/general.mdc` *Worktrees / Workspaces*, which carries no write-lock and never contends with the writing path. Each CR agent creates the worktree with `git worktree add` (a throwaway read-only review checkout — never edits / commits / pushes there), records its path in the handoff, and either hands it to `daidalos` for removal in cleanup (step 7: `git worktree remove` + `git worktree prune`, no `--force`) or removes it itself when run standalone. Documented in `agents/daidalos.md` *Concurrency & the working-tree write-lock* (now *Worktrees — writing path stays on the shared tree, read-only CR may isolate*) + step 6/7, `agents/argos.md` / `agents/athena.md` *Parallel review worktree*, and mirrored in `docs/agents.md`. Per user request — *CR agenti smí používat git worktrees pro paralelní code review; Daidalos po dokončení a merge vše uklidí, aby v repository nebyl bordel*.
+
 - ✨ **Added**: new **`laravel-authorization-review`** skill (#716) — a Laravel-native authorization / IDOR (broken object-level authorization, BOLA) reviewer for use in Laravel code review. Adapted from the open-source `laravel-authorization-review` skill, it walks the authorization chain of every HTTP route (middleware → `authorize`/policy/gate → Eloquent query scoping → API Resource output), anchors **every** finding to real `php artisan route:list --json` output plus a cited `file:line`, classifies by confidence (High / Medium / Low), maps each finding onto the repo CR severity scale (Critical / Moderate / Minor) per `@rules/code-review/general.mdc`, and produces a per-route coverage map. Read-only / advise-only — never edits code. Ships `references/auth-patterns.md` (how Laravel authz legitimately appears across middleware, policies, gates, and `route:list --json`), `references/public-by-design.md` (routes meant to be unauthenticated), and `templates/report.md` (coverage-map report template). Complements `laravel-security` (broad 7-area audit) and `security-review` by going deep on the authorization lane. Catalogued under `skills/laravel-authorization-review/`; README skill count bumped 61 → 62.
 
 - 📝 **Changed**: `daidalos` now processes **every task it resolves from the issue tracker strictly sequentially — one source at a time, never fanning out in parallel** — and **git worktrees are forbidden** across the whole workflow. The former *Parallel analysis fan-out* (multiple `metis` runs in one message) is replaced by *Sequential processing of multiple sources*: a single request that resolves to several issues finishes one source's run completely before starting the next, ordered by the dependency-aware plan (or oldest-first). The concurrency / write-lock section drops every isolated-worktree escape — concurrent full-delivery runs serialise on the single shared working tree, and a run that finds a live lock holder waits and retries rather than spinning up a worktree. Documented in `agents/daidalos.md` *Concurrency & the working-tree write-lock* + *Sequential processing of multiple sources* and mirrored in `docs/agents.md`. The intra-task `argos` ‖ `athena` security/quality CR pass stays parallel — it is two reviews of one task, not two tasks. Per user request — *všechny úkoly z issue trackeru řešit systematicky a nikoliv paralelně; výslovně zakázat git worktrees*.

agents/argos.md

@@ -36,6 +36,14 @@ You accept one **source** for the review, in this order of preference:
 
 When the caller passes a **shared brief path** (`.claude/run/<source-slug>.md`), it is the run's shared memory — **read it first** as the authoritative context (resolved source, gathered data, work-breakdown plan, and every prior specialist's handoff) so you don't re-derive what is already there. When you finish, **append your handoff section** to it via `Bash` (`cat >> "$BRIEF" <<'EOF' … EOF`: `### argos — CR done` plus the result you return) so the next specialist inherits it. Because you may run in parallel with `athena` on the same brief, **guard the append with the per-brief append lock** (`tries=0; until mkdir "$BRIEF.lock" 2>/dev/null; do sleep 0.2; tries=$((tries+1)); [ "$tries" -gt 50 ] && rm -rf "$BRIEF.lock"; done; cat >> "$BRIEF" …; rmdir "$BRIEF.lock"`) so the two handoffs never interleave and a crashed holder never deadlocks the peer — see `agents/daidalos.md` *Shared task brief* → *Parallel handoff sharing*. Appending to this git-ignored scratch file is the **only** write you perform — your read-only stance on source, tests, and config is unchanged. Delete any temporary files you created during this run (except memory files) per `@rules/compound-engineering/general.mdc` *Temporary-file hygiene*.
 
+## Parallel review worktree (optional)
+
+Because you and `athena` run as two concurrent CR passes, you **may run your review in an isolated read-only git worktree** when you need to avoid contending with the shared working tree (for example, a writing run is still touching the tree, or the two CR passes would otherwise step on each other). This is the explicit-request opt-in of `@rules/git/general.mdc` *Worktrees / Workspaces*, which `daidalos` grants to the CR pass — it is **not** a default; stay in the current tree unless isolation is genuinely needed.
+
+- Create it with `git worktree add <path> <ref>` where `<ref>` is the PR head you are reviewing. This is the only filesystem write you make beyond the shared-brief append, and it adds **no** change to tracked files, branches, or history — your read-only stance on source, tests, and config is unchanged. You **read** in the worktree; you never edit, commit, push, or merge there.
+- **Record the worktree path in your handoff** (and in the shared-brief append) so `daidalos` removes it during its cleanup (step 7 of `agents/daidalos.md`) — this is how it keeps the repository clean after the run / merge.
+- When you run **standalone** (no `daidalos` orchestrating the cleanup), remove your own worktree after the review: verify it is not the active tree and has no uncommitted changes (never `--force`), then `git worktree remove <path>` followed by `git worktree prune`.
+
 ## Output — handoff to the caller
 
 Your final message is returned to the caller as the result, so make it a clean handoff:
@@ -47,5 +55,6 @@ Your final message is returned to the caller as the result, so make it a clean h
 - **Source:** link to the originating tracker item (GitHub issue / JIRA ticket / Bugsnag error), or `none` for the no-source fallback.
 - **Counts:** Critical / Moderate / Minor.
 - **Assignment conformance:** `conformant` / `N gap(s)` / `no linked issue`.
+- **Worktree:** the path of any review worktree you created (so `daidalos` removes it in cleanup), or `none` when you reviewed in the shared tree.
 
 Hand the next agent everything it needs to act (apply fixes, merge) without re-deriving where the review lives. Stop after the handoff — applying fixes or merging is a different agent's job.

agents/athena.md

@@ -89,6 +89,14 @@ Since both run concurrently, `argos` does not see your handoff during its own ru
 
 When the caller passes a **shared brief path** (`.claude/run/<source-slug>.md`), it is the run's shared memory — **read it first** as the authoritative context (resolved source, gathered data, work-breakdown plan, and every prior specialist's handoff) so you don't re-derive what is already there. When you finish, **append your handoff section** to it via `Bash` (`cat >> "$BRIEF" <<'EOF' … EOF`: `### athena — Security CR done` plus the result you return) so the next specialist inherits it. Because you run in parallel with `argos` on the same brief, **guard the append with the per-brief append lock** (`tries=0; until mkdir "$BRIEF.lock" 2>/dev/null; do sleep 0.2; tries=$((tries+1)); [ "$tries" -gt 50 ] && rm -rf "$BRIEF.lock"; done; cat >> "$BRIEF" …; rmdir "$BRIEF.lock"`) so the two handoffs never interleave and a crashed holder never deadlocks the peer — see `agents/daidalos.md` *Shared task brief* → *Parallel handoff sharing*. Appending to this git-ignored scratch file is the **only** write you perform — your read-only stance on source, tests, and config is unchanged. Delete any temporary files you created during this run (except memory files) per `@rules/compound-engineering/general.mdc` *Temporary-file hygiene*.
 
+## Parallel review worktree (optional)
+
+Because you and `argos` run as two concurrent CR passes, you **may run your security review in an isolated read-only git worktree** when you need to avoid contending with the shared working tree (for example, a writing run is still touching the tree, or the two CR passes would otherwise step on each other). This is the explicit-request opt-in of `@rules/git/general.mdc` *Worktrees / Workspaces*, which `daidalos` grants to the CR pass — it is **not** a default; stay in the current tree unless isolation is genuinely needed. It applies to the post-implementation **security review mode** only — the pre-implementation security-analysis mode reviews no diff.
+
+- Create it with `git worktree add <path> <ref>` where `<ref>` is the PR head you are reviewing. This is the only filesystem write you make beyond the shared-brief append, and it adds **no** change to tracked files, branches, or history — your read-only stance is unchanged. You **read** in the worktree; you never edit, commit, push, or merge there.
+- **Record the worktree path in your handoff** (and in the shared-brief append) so `daidalos` removes it during its cleanup (step 7 of `agents/daidalos.md`) — this is how it keeps the repository clean after the run / merge.
+- When you run **standalone** (no `daidalos` orchestrating the cleanup), remove your own worktree after the review: verify it is not the active tree and has no uncommitted changes (never `--force`), then `git worktree remove <path>` followed by `git worktree prune`.
+
 ## Output — handoff to the caller
 
 Your final message is returned to the caller as the result, so make it a clean handoff:
@@ -100,5 +108,6 @@ Your final message is returned to the caller as the result, so make it a clean h
 - **Source:** link to the originating tracker item (GitHub issue / JIRA ticket / Bugsnag error), or `none`.
 - **Counts:** Critical / Moderate / Minor.
 - **Skills run:** which of the four security skills executed (and which were skipped with reason, e.g. "laravel-security skipped — not a Laravel project").
+- **Worktree:** the path of any review worktree you created (so `daidalos` removes it in cleanup), or `none` when you reviewed in the shared tree.
 
 Hand the next agent (`talos` to implement an analysis, `argos` / `daidalos` to act on a CR) everything it needs without re-deriving the findings. Stop after the handoff — implementing fixes, consolidating CR results, and publishing summaries are other agents' jobs.