sequant 2.2.0 → 2.3.0

package/templates/skills/assess/SKILL.md

@@ -52,6 +52,20 @@ Every issue gets exactly ONE action:
 
 ### Step 1: Context Gathering
 
+**Concurrency check (#625, read-only):**
+
+Probe the per-issue concurrency lock so the dashboard can flag issues another session is actively working on. `/assess` never acquires the lock — it only reports.
+
+```bash
+# Single batch call. Empty output = no issues are locked. Held issues print one
+# pre-formatted `⚠ #<N> held by ...` line each, ready to paste above the dashboard.
+npx sequant locks check-batch <N1> <N2> ... 2>/dev/null || true
+```
+
+If the output is non-empty, paste every line verbatim above the dashboard table (or, in single-issue detail mode, immediately above the action verdict). Do not gate the recommendation — `/assess` is read-only and must still produce its action verdict even when an issue is locked.
+
+The orchestrator/MCP mode (`SEQUANT_ORCHESTRATOR` set) returns no output, so the call is safe to make unconditionally.
+
 **From GitHub (parallel for all issues):**
 
 ```bash
@@ -78,6 +92,27 @@ gh pr list --search "<N> in:title" --json number,title,state,headRefName,mergeab
 - Grep for TODOs: `Grep(pattern="TODO.*#<N>")`
 - Check files referenced in issue body exist
 - Identify modified files if branch exists
+- For predicted-collision detection (see Step 5), pass each PROCEED candidate's body through `extractPathsFromIssueBody` from `src/lib/assess-collision-detect.ts` to build the issue → paths map used in Step 5
+
+#### Prior Assessment Detection
+
+Before generating output, scan the issue's existing comments for prior `<!-- assess:action=... -->` markers. The parser exposes four pure functions in `src/lib/assess-comment-parser.ts`:
+
+| Function | Purpose |
+|----------|---------|
+| `findAllAssessComments(comments)` | Returns prior assess comments in chronological order (oldest first). |
+| `buildSupersessionHeader(priors)` | Returns `Supersedes prior assess from <date> (<action>)` for 1 prior, `Supersedes N prior assessments (most recent: <date>)` for ≥2, or `null` for 0. |
+| `detectChurn(priors, allComments)` | Returns `{ isChurn, count, firstDate }`. Fires (`isChurn=true`) only when ≥3 priors exist AND no exec phase marker (`<!-- SEQUANT_PHASE: {"phase":"exec",...} -->`) appears in any comment dated after the first prior. |
+| `shouldPromptOnConflict(prior, new)` | Returns `true` only when prior action ∈ {`PROCEED`, `REWRITE`} AND differs from the new action. |
+
+**Supersession protocol:**
+
+1. **No priors** → omit the supersession header entirely.
+2. **1+ priors** → prepend the header line returned by `buildSupersessionHeader` to the new comment body, immediately above the `→ ACTION — reason` line.
+3. **Churn detected** (`detectChurn(...).isChurn === true`) → emit a dashboard warning: `⚠ #<N>  Re-assessed N times since <firstDate> without execution — possible blocker or low priority`.
+4. **Conflict detected** (`shouldPromptOnConflict(prior, new) === true`) → confirm with the user via `AskUserQuestion` before posting. Skip the prompt when actions match or when the prior was `CLOSE`/`PARK`/`CLARIFY`/`MERGE`.
+
+**This pass is read-only — never edit or delete prior assess comments.** The append-only history is the audit trail; new comments add context, they do not rewrite it.
 
 ### Step 2: Health Checks
 
@@ -117,14 +152,14 @@ Surface red flags. Only track signals that change the recommendation.
 | complex, refactor, breaking, major | Modifier | `spec → exec → qa` + `-q` |
 | (ui/frontend) + (enhancement/feature), or testable-AC signals | Modifier | inserts `testgen` before `exec` (see Testgen detection below) |
 | enhancement, feature (default) | Generic | `spec → exec → qa` |
-| bug, fix, hotfix, patch | Generic | `exec → qa` |
-| docs, documentation, readme | Generic | `exec → qa` |
+| bug, fix, hotfix, patch | Generic | `spec → exec → qa` |
+| docs, documentation, readme | Generic | `spec → exec → qa` |
 
-**Label priority:** Domain labels take precedence over generic labels. When an issue has both a domain label and a generic label (e.g., `bug` + `auth`), use the domain-specific workflow. Example: an issue labeled `bug` + `auth` gets `spec → security-review → exec → qa`, not `exec → qa`. Similarly, `bug` + `ui` gets `spec → exec → test → qa`.
+**Label priority:** Domain labels take precedence over generic labels. When an issue has both a domain label and a generic label (e.g., `bug` + `auth`), the domain label adds its extra phase. Example: an issue labeled `bug` + `auth` gets `spec → security-review → exec → qa` (adds `security-review` from `auth`); `bug` + `ui` gets `spec → exec → test → qa` (adds `test` from `ui`).
 
 **Valid phases (from `PhaseSchema` in `src/lib/workflow/types.ts`):** `spec`, `security-review`, `exec`, `testgen`, `test`, `verify`, `qa`, `loop`, `merger`
 
-**Skip spec when:** (bug/docs label AND no domain labels like security/auth/ui/frontend), OR spec comment already exists on issue.
+**Skip spec when:** a prior `spec` phase marker already exists on the issue. Otherwise, always include spec — bug and docs issues often contain design decisions (scope boundaries, edge cases, test-strategy shifts) that benefit from a spec pass.
 
 **Resume detection:** Branch exists with commits ahead of main → mark as resume (`◂`).
 
@@ -153,12 +188,31 @@ Flag references:
 
 ### Step 5: Conflict Detection
 
+**Active-worktree overlap.** For each in-flight worktree, check whether its diff overlaps with files the assessed issues are likely to touch.
+
 ```bash
 git worktree list --porcelain 2>/dev/null | grep "^worktree" | cut -d' ' -f2 || true
 ```
 
 For each active worktree, check `git diff --name-only main...HEAD` for file overlap with assessed issues.
 
+**Predicted file-collision (PROCEED issues).** Step 5 also runs a heuristic across the bodies of unstarted PROCEED issues to predict pairs that will modify the same file once executed in parallel. The detector lives in `src/lib/assess-collision-detect.ts` and exposes three pure functions:
+
+| Function | Purpose |
+|----------|---------|
+| `extractPathsFromIssueBody(body)` | Strips fenced code blocks and HTML comments, then returns the set of canonical paths the body names. Backtick-quoted paths under `.claude/`, `templates/`, `skills/`, `src/`, `bin/`, `docs/` matching `*.md`, `*.ts`, `*.tsx`, `*.json`, `*.sh` are extracted; skill-mirror prefixes (`.claude/skills/`, `templates/skills/`, `skills/`) are normalized away so `qa/SKILL.md` is the canonical form. When the body also mentions "3-dir sync" (or "across all three skill directories"), bare `<name>/SKILL.md` references and `/<skill>` slash-command mentions are also added. Globally excluded paths (`CHANGELOG.md`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`) are stripped. |
+| `detectFileCollisions(issuePaths)` | Computes pairwise file-path intersections across the PROCEED issues. Returns one `CollisionResult` per shared file: `{ issues: number[], file: string }`. When N issues share a file, that's a single result with `issues.length === N`. Because paths are canonical, mirrored skill files emit one collision, not three. |
+| `formatCollisionAnnotations(results)` | Returns `{ orderLines, warnings, chainSuggestion? }`. Each pair (or group) emits an `Order: A → B (path)` line and one `⚠ #N  Modifies <path> (overlaps #M); land sequentially` per affected issue. When ≥3 issues collide on the same file, a `Chain:` suggestion is also returned (suggest-only — never auto-applied). |
+
+**Output integration:**
+
+1. Step 1 (Context Gathering) already calls `extractPathsFromIssueBody` per PROCEED candidate to build the issue → paths map.
+2. After Step 4 produces the PROCEED set, pass the map to `detectFileCollisions`.
+3. Render the formatted annotations in the dashboard alongside the active-worktree overlap warnings — same `Order:` / `⚠` / `Chain:` blocks defined in "Annotation Rules" below.
+4. The bare-filename `Order:` exception (e.g. `Order: 551 → 552 (qa/SKILL.md)`) applies here — predicted collisions are file-collision reasons by definition.
+
+False-positive guards and tunables (excluded paths, the path regex, the slash-command-skill derivation rule) are documented in [`references/predicted-collision-detection.md`](references/predicted-collision-detection.md) so they can change without editing this skill.
+
 ---
 
 ## Output Format
@@ -208,7 +262,7 @@ Cleanup:
 | Symbol | Meaning | Example |
 |--------|---------|---------|
 | `spec → exec → qa` | Full workflow | Standard feature |
-| `exec → qa` | Skip spec | Bug, docs, or spec exists |
+| `exec → qa` | Skip spec | Prior spec marker exists |
 | `◂ exec → qa` | Resume existing work | Branch has commits |
 | `◂ qa` | PR needs review/QA | Open PR, impl done |
 | `⟳ spec → exec → qa` | Restart (fresh) | Stale PR abandoned |
@@ -228,6 +282,7 @@ The commands block is headed by `Commands:` — no box-drawing, no character cou
 5. Chain mode issues use `--chain` flag (see `Chain:` annotation rules below)
 6. If ALL issues share the same workflow, emit a single command
 7. **Line splitting:** When a single command would contain more than 6 issue numbers, split into multiple commands of at most 6 issues each, grouped by compatible workflow. Example: 11 issues → two commands (6 + 5)
+8. **Minimal flags:** Omit `--phases` when the resulting workflow equals the CLI default (registered at `bin/cli.ts:186`, defined as `DEFAULT_PHASES` in `src/lib/workflow/types.ts`). Prefer additive flags over restating phases — additive flags: `--testgen` and `--security-review` (`bin/cli.ts:208-209`). Use `--testgen` instead of `--phases spec,testgen,exec,qa` (or `…,testgen,…,test,qa` for ui-labelled issues, since `phase-mapper.determinePhasesForIssue` auto-adds `test` from the ui label). Use `--security-review` instead of `--phases spec,security-review,exec,qa`. The posted marker (`<!-- assess:phases=… -->`) records the full resolved workflow regardless — markers are machine-readable, displayed commands are human shorthand. This intentional divergence is fine: parsers consume markers, humans copy commands.
 
 #### Annotation Rules
 
@@ -238,6 +293,7 @@ Emit annotations in this order between the separators that follow `Commands:`:
   - Good: `Order: 185 → 186 (185 changes fetchApi error format that 186 consumes)`
   - Good: `Order: 460 → 461 (460 adds batch-executor tests that 461's label matching depends on)`
   - Avoid bare filenames when a reason is clearer.
+  - **Exception:** When the sequencing reason **is** a file collision (two issues both modify the same file), the filename **is** the reason and is acceptable verbatim. Example: `Order: 460 → 461 (qa/SKILL.md)` — the bare filename communicates the conflict directly.
 
 - **`⚠` warnings** — Only non-obvious signals (complexity, staleness, dual concerns, partial-AC satisfaction). One line each, prefixed with issue number. Warnings can note when part of an AC is already satisfied in the codebase:
   - `⚠ #185  Domain errors already exist in repository layer — scope may be smaller than expected`
@@ -265,19 +321,18 @@ Not all issues have explicit `- [ ]` checkboxes, so the `ACs` column is omitted.
 ```
  #    Action     Reason                              Run
  462  PARK       Manual measurement task              ‖
- 461  PROCEED    Exact label matching                  exec → qa
- 460  PROCEED    batch-executor tests                  exec → qa
+ 461  PROCEED    Exact label matching                  spec → exec → qa
+ 460  PROCEED    batch-executor tests                  spec → exec → qa
  458  PROCEED    Parallel UX + race condition          spec → exec → qa
  447  CLOSE      PR #457 merged                        —
  443  PROCEED    Consolidate gh calls                  spec → exec → qa
- 412  PROCEED    Auth bug (domain: auth overrides bug) spec → security-review → exec → qa
+ 412  PROCEED    Auth bug (domain: auth adds review)   spec → security-review → exec → qa
  411  PROCEED    Config path normalization              ◂ exec → qa
  405  REWRITE    PR #380 200+ commits behind           ⟳ spec → exec → qa
 ────────────────────────────────────────────────────────────────
 Commands:
-  npx sequant run 461 460 -q --phases exec,qa
-  npx sequant run 458 443 -q
-  npx sequant run 412 -q --phases spec,security-review,exec,qa
+  npx sequant run 461 460 458 443 -q
+  npx sequant run 412 -q --security-review
   npx sequant run 411 -q --phases exec,qa     # resume
   npx sequant run 405 -q                      # restart
 ────────────────────────────────────────────────────────────────
@@ -285,11 +340,12 @@ Order: 460 → 461 (460 adds batch-executor tests that 461's label matching depe
 
 ⚠ #458  Dual concern (UX + race) across 4 files
 ⚠ #405  Stale 30+ days, ACs still valid
-⚠ #412  bug + auth labels — domain label (auth) takes priority over bug
+⚠ #412  bug + auth labels — auth (domain) adds security-review phase
 
 Flags:
-  -q                   multi-file scope across most PROCEED issues
-  --phases spec,...    spec phase added for 458/443/412/405 (standard features)
+  -q                              multi-file scope across most PROCEED issues
+  --security-review               #412 auth label → security review required
+  --phases exec,qa                #411 resume — prior spec marker already exists
 ────────────────────────────────────────────────────────────────
 Cleanup:
   git worktree remove .../447-...      # merged, stale worktree
@@ -298,8 +354,8 @@ Cleanup:
 ────────────────────────────────────────────────────────────────
 
 <!-- #462 assess:action=PARK -->
-<!-- #461 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
-<!-- #460 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
+<!-- #461 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
+<!-- #460 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
 <!-- #458 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
 <!-- #447 assess:action=CLOSE -->
 <!-- #443 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
@@ -319,19 +375,18 @@ All issues have explicit checkbox ACs, so the `ACs` column is shown. A dependenc
 ────────────────────────────────────────────────────────────────
 Commands:
   npx sequant run 185 -q
-  npx sequant run 186 -q --phases spec,testgen,exec,test,qa
+  npx sequant run 186 -q --testgen
 ────────────────────────────────────────────────────────────────
 Order: 185 → 186 (185 changes fetchApi error format that 186 consumes)
 
 ⚠ #185  Domain errors already exist in repository layer — scope may be smaller than expected
 ⚠ #186  @tanstack/react-query not installed; large scope (9 hooks + optimistic updates)
 
-Chain: npx sequant run 185 186 --chain --qa-gate -q --phases spec,testgen,exec,test,qa
+Chain: npx sequant run 185 186 --chain --qa-gate -q --testgen
        # alternative — use if 186 should branch from 185's work
 
 Flags:
-  --testgen             #186 has testable ACs (UI hooks + API integration)
-  --phases ...,test     #186 ui label → browser verification
+  --testgen             #186 testable ACs (UI hooks + API integration); ui label auto-adds test phase
 ────────────────────────────────────────────────────────────────
 
 <!-- #185 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
@@ -344,17 +399,16 @@ When every issue is PROCEED with no warnings, no dependencies, and no non-defaul
 
 ```
  #    Action     Reason                              Run
- 461  PROCEED    Exact label matching                  exec → qa
- 460  PROCEED    batch-executor tests                  exec → qa
+ 461  PROCEED    Exact label matching                  spec → exec → qa
+ 460  PROCEED    batch-executor tests                  spec → exec → qa
  443  PROCEED    Consolidate gh calls                  spec → exec → qa
 ────────────────────────────────────────────────────────────────
 Commands:
-  npx sequant run 461 460 -q --phases exec,qa
-  npx sequant run 443 -q
+  npx sequant run 461 460 443 -q
 ────────────────────────────────────────────────────────────────
 
-<!-- #461 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
-<!-- #460 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
+<!-- #461 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
+<!-- #460 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
 <!-- #443 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
 ```
 
@@ -366,53 +420,50 @@ When assessing 9+ issues, commands are split per Rule 7 (max 6 issue numbers per
 
 ```
  #    Action     Reason                                   Run
- 503  PROCEED    Fix typo in error output                   exec → qa
- 502  PROCEED    Update deprecated API call                 exec → qa
- 501  PROCEED    Add retry logic to API client              exec → qa
+ 503  PROCEED    Fix typo in error output                   spec → exec → qa
+ 502  PROCEED    Update deprecated API call                 spec → exec → qa
+ 501  PROCEED    Add retry logic to API client              spec → exec → qa
  500  PROCEED    Fix token refresh race condition           spec → security-review → exec → qa
  499  PROCEED    Dashboard chart rendering bug              spec → exec → test → qa
- 498  PROCEED    Update error messages                      exec → qa
+ 498  PROCEED    Update error messages                      spec → exec → qa
  497  PROCEED    Refactor batch executor                    spec → exec → qa
  496  PARK       Blocked on #490 schema migration           ‖
- 495  PROCEED    CLI help text improvements                 exec → qa
- 494  PROCEED    Assess batch formatting fix                exec → qa
+ 495  PROCEED    CLI help text improvements                 spec → exec → qa
+ 494  PROCEED    Assess batch formatting fix                spec → exec → qa
  493  CLOSE      Duplicate of #491                          —
  492  PROCEED    Add export command                         spec → exec → qa
- 491  PROCEED    Normalize config paths                     exec → qa
+ 491  PROCEED    Normalize config paths                     spec → exec → qa
 ────────────────────────────────────────────────────────────────
 Commands:
-  npx sequant run 503 502 501 498 495 494 -q --phases exec,qa
-  npx sequant run 491 -q --phases exec,qa
-  npx sequant run 499 -q --phases spec,exec,test,qa
-  npx sequant run 500 -q --phases spec,security-review,exec,qa
-  npx sequant run 497 492 -q
+  npx sequant run 503 502 501 499 498 497 -q
+  npx sequant run 495 494 492 491 -q
+  npx sequant run 500 -q --security-review
 ────────────────────────────────────────────────────────────────
 Order: 497 → 492 (497 refactors batch-executor internals that 492's export command uses)
 
-⚠ #500  bug + auth labels — domain label takes priority
-⚠ #499  bug + ui labels — domain label triggers test phase
+⚠ #500  bug + auth labels — auth (domain) adds security-review phase
+⚠ #499  bug + ui labels — ui (domain) adds test phase
 
 Flags:
-  --phases ...,security-review   #500 auth label → security review required
-  --phases ...,test              #499 ui label → browser verification
+  --security-review     #500 auth label → security review required
 ────────────────────────────────────────────────────────────────
 Cleanup:
   gh issue close 493                   # duplicate of #491
 ────────────────────────────────────────────────────────────────
 
-<!-- #503 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
-<!-- #502 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
-<!-- #501 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
+<!-- #503 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
+<!-- #502 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
+<!-- #501 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
 <!-- #500 assess:action=PROCEED assess:phases=spec,security-review,exec,qa assess:quality-loop=true -->
 <!-- #499 assess:action=PROCEED assess:phases=spec,exec,test,qa assess:quality-loop=true -->
-<!-- #498 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
+<!-- #498 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
 <!-- #497 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
 <!-- #496 assess:action=PARK -->
-<!-- #495 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
-<!-- #494 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
+<!-- #495 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
+<!-- #494 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
 <!-- #493 assess:action=CLOSE -->
 <!-- #492 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
-<!-- #491 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
+<!-- #491 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
 ```
 
 ---
@@ -599,6 +650,7 @@ Every separator and section is conditional. If there are no warnings, no chain,
 After displaying output, prompt the user to save using `AskUserQuestion` with options "Yes (Recommended)" and "No".
 
 If confirmed, post a structured comment to each issue via `gh issue comment`. Each posted comment should include:
+- **Supersession header** (when priors exist): If `findAllAssessComments` returned ≥1 prior, prepend `buildSupersessionHeader(priors)` immediately above the `→ ACTION — reason` line. When `detectChurn(...).isChurn === true`, also emit a `⚠ Re-assessed N times since <firstDate> without execution — possible blocker or low priority` warning in the dashboard. When `shouldPromptOnConflict(prior, new) === true`, confirm with the user via `AskUserQuestion` before posting. See "Prior Assessment Detection" in Step 1 for full protocol.
 - The action headline (`→ ACTION — reason`)
 - The workflow (for PROCEED/REWRITE)
 - Standard HTML markers on separate lines:
@@ -634,5 +686,7 @@ If confirmed, post a structured comment to each issue via `gh issue comment`. Ea
 - [ ] Separators appear between every shown section; omitted when adjacent section is omitted
 - [ ] Annotations/sections omitted when not applicable (silence = healthy)
 - [ ] HTML markers present for every assessed issue
+- [ ] Supersession header prepended when prior assess comments exist (`buildSupersessionHeader`)
+- [ ] Churn warning included in dashboard when `detectChurn(...).isChurn === true`
 - [ ] Batch mode: table is the primary output, no per-issue detail sections
 - [ ] Single mode: focused summary with separators between sections

package/templates/skills/assess/references/predicted-collision-detection.md

@@ -0,0 +1,109 @@
+# Predicted file-collision detection
+
+`/assess` Step 5 inspects two sources of overlap between PROCEED issues:
+
+1. **Active-worktree overlap.** For each running worktree, `git diff --name-only main...HEAD` is intersected with the assessed issues' likely-touched files. Catches in-flight work.
+2. **Predicted file-collision (this document).** For each pair of unstarted PROCEED issues, the detector reads issue bodies and predicts which pairs will modify the same file once both run in parallel worktrees.
+
+This document is the tunable surface for the predicted-collision heuristic. The skill prose in `SKILL.md` names the detection functions; the patterns and the exclusion list live here so they can change without skill edits.
+
+## Trigger
+
+The detector runs automatically during Step 5 whenever ≥2 PROCEED issues are present in the assessment. Single-issue assessments skip it.
+
+## Path-extraction heuristics
+
+For each issue body, paths are extracted in this order:
+
+### 1. Strip code blocks and HTML comments
+
+Fenced code blocks (```` ``` … ``` ````) and HTML comments (`<!-- … -->`) are removed before any path matching. This is the **AC-5 false-positive guard**: paths quoted as code in prose count, paths inside a code block don't.
+
+### 2. Backtick-quoted source paths (PATH_REGEX)
+
+Backtick-quoted paths starting with one of the tracked roots and ending in a known source extension are extracted verbatim:
+
+```
+`(.claude|templates|skills|src|bin|docs)/<path-segment>+\.(md|ts|tsx|json|sh)`
+```
+
+Examples that match:
+
+- `` `.claude/skills/assess/SKILL.md` ``
+- `` `src/lib/foo.ts` ``
+- `` `templates/scripts/dev/foo.sh` ``
+
+Examples that **don't** match:
+
+- `` `phase-mapper.ts` `` — no directory prefix; too generic to disambiguate
+- `` `.claude/skills/**/*.md` `` — glob, not a literal path
+- `` `references/foo.md` `` — `references` is not a tracked root (it lives under `skills/<name>/`)
+
+### 3. Canonical bare form for skill files
+
+Skill files have three byte-identical mirrors at `.claude/skills/<name>/...`, `templates/skills/<name>/...`, `skills/<name>/...`. Treating the mirrors as separate paths would produce 3× the `Order:` lines and 6× the warnings for one logical conflict.
+
+The detector normalizes all three mirror prefixes to the bare subpath at extraction time:
+
+| Input (in issue body) | Canonical |
+|-----------------------|-----------|
+| `` `.claude/skills/qa/SKILL.md` `` | `qa/SKILL.md` |
+| `` `templates/skills/qa/SKILL.md` `` | `qa/SKILL.md` |
+| `` `skills/qa/SKILL.md` `` | `qa/SKILL.md` |
+| `` `qa/SKILL.md` `` (under 3-dir sync) | `qa/SKILL.md` |
+
+This is the form that appears in `Order:` lines and `⚠` warnings.
+
+### 4. Bare `<name>/SKILL.md` references (gated on 3-dir sync)
+
+When the body also signals "3-dir sync" (regex below), bare skill-file mentions like `` `qa/SKILL.md` `` and `` `spec/SKILL.md` `` are added to the path set in canonical form. The 3-dir-sync gate prevents over-extraction from incidental skill-file references in prose.
+
+3-dir-sync language is matched by:
+
+```
+/3[- ]dir(?:ectory)?\s+sync|across\s+all\s+three\s+skill\s+directories|across\s+(?:the\s+)?three\s+skill\s+directories/i
+```
+
+### 5. Slash-command-skill derivation (gated on 3-dir sync)
+
+When the body signals 3-dir sync, every `/<skill>` slash-command mention is also added as `<skill>/SKILL.md` (canonical bare form) — provided `<skill>` matches a known skill name. This catches issues that describe section changes via `/qa Section 6c`-style notation rather than naming the file path.
+
+The known-skill-name list lives in `KNOWN_SKILL_NAMES` in `src/lib/assess-collision-detect.ts`. Keep it in sync with the actual skill set under `skills/`. Adding a new skill? Append its name here.
+
+Slash-command derivation requires the same fenced-code-block / HTML-comment stripping — `/qa` mentioned only inside a code block does **not** trigger derivation.
+
+## False-positive guards
+
+### Globally excluded paths
+
+These paths are stripped from every issue's path set before pairwise intersection. They are paths that virtually every PROCEED issue tends to touch — including them would flag every batch as colliding and train users to ignore the warning.
+
+- `CHANGELOG.md` — every PROCEED issue updates the unreleased section
+- `package-lock.json` — alphabetically merged in practice; collisions are rare in practice
+- `yarn.lock`
+- `pnpm-lock.yaml`
+
+`EXCLUDED_PATHS` in `src/lib/assess-collision-detect.ts` is the canonical list. To add or remove an entry, edit that constant; this document and the skill prose pick up the change automatically.
+
+### Code block / HTML comment stripping
+
+Step 1 of the extraction (above) removes all fenced code blocks and HTML comments before path matching. A path mentioned **only** inside one of those will not contribute to the issue's path set.
+
+### Path-shape constraints
+
+The PATH_REGEX requires a directory prefix (one of the six tracked roots) and a known source extension. Bare filenames in prose (e.g. "phase-mapper.ts behavior") and glob patterns (`**/*.md`) are not extracted.
+
+## Tuning notes
+
+- **Proximity weighting** is not implemented. The original feature design proposed weighting paths inside `- [ ] **AC-N:**` bullets higher than paths in "Motivation" or "Additional context". Adding it is a follow-up if the false-positive rate becomes a problem in practice; leave it out until evidence demands it.
+- **Cost.** For 13 issues (the realistic batch ceiling), pairwise comparison is 78 pairs — cheap, no real performance concern. Don't optimize prematurely.
+
+## Output rules
+
+The detector returns `CollisionResult[]` from `detectFileCollisions`. The formatter (`formatCollisionAnnotations`) renders annotations in the dashboard format:
+
+- `Order: A → B (path)` per pair (or `Order: A → B → C (path)` for 3+ on the same file). `path` is the canonical bare form (e.g. `qa/SKILL.md`).
+- `⚠ #N  Modifies <path> (overlaps #M); land sequentially` per affected issue.
+- `Chain: npx sequant run A B C --chain --qa-gate -q   # alternative — N issues modify <path> (chain length≥3 historically 1/6 = 17%; see docs/reference/chain-mode-analysis-2026-05.md)` only when ≥3 issues collide on the same file (suggest-only). The historical-rate annotation comes from the #604 forensic write-up; users see the suggestion alongside the parallel default and can weigh the trade-off.
+
+The bare-filename `Order:` exception (defined in the skill's "Annotation Rules") applies here — predicted collisions are file-collision reasons by definition, so the filename in parentheses is the reason verbatim.