claude-code-session-manager 0.37.2 → 0.38.1

package/plugins/session-manager-dev/skills/blog-for-project-feature/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: blog-for-project-feature
+description: Produce a self-contained, interactive HTML "feature showcase" for one project + one feature — Project Mission & Description, Feature Description (with an optional generated companion illustration), and a Click-Through Demo built from REAL screenshots (never mockups) — one aspect revealed at a time. Output is a single portable HTML file uploadable anywhere (no server, no build step). Distinct from blog-from-git (which drafts narrative bilko.run changelog posts from git history) — this is an evergreen, per-feature product page, not a dated post. Orchestrates 8 nested sub-skills (blog-for-project-feature:select, :research, :storyboard, :capture, :draft-copy, :illustrate, :compose, :review) so each step is independently invokable and inspectable. Use for "make a feature page for X", "showcase this feature", "/blog-for-project-feature", "interactive demo of X", or turning a shipped feature in Session Manager / Social Signal Builder (or any project) into something you can hand someone a link to.
+---
+
+# blog-for-project-feature (orchestrator)
+
+Project-agnostic. Runs against whatever project the current working directory (or a named
+project path) points to — built first for **Session Manager** and **Social Signal Builder**,
+but nothing here is hardcoded to either.
+
+**Not `blog-from-git`.** That skill drafts a dated, narrative bilko.run post from git activity
+("here's what shipped this week"). This skill produces an **evergreen, single-feature product
+page** — no date, no changelog framing, not tied to a publishing cadence. One project, one
+feature, three things: what the project is for, what this feature does, and a real click-through
+demo of it working. The two skills never share output or ledger state.
+
+**`feature.config.yaml` in this folder is the grounding authority** for output conventions
+(where the HTML lands, image size/compression limits, single-file-vs-folder default, theme
+tokens). Read it first, before any sub-skill file. If prose here ever disagrees with the config,
+the config wins.
+
+## Pipeline DAG
+
+```
+project (+ optional feature name)
+              │
+              ▼
+┌───────────────────────────────┐
+│ 0. blog-for-project-feature:select │──▶ one confirmed project + one confirmed feature
+└───────────────────────────────┘
+              │
+              ▼
+┌───────────────────────────────┐
+│ 1. :research                       │──▶ mission, feature description, key files/entry points
+└───────────────────────────────┘
+              │
+              ▼
+┌───────────────────────────────┐
+│ 2. :storyboard                     │──▶ ordered demo steps (action, expected screen, caption)
+└───────────────────────────────┘
+              │
+              ▼
+┌───────────────────────────────┐
+│ 3. :capture                        │──▶ real screenshots per step (+ storyboard corrections)
+└───────────────────────────────┘        │ no real screenshot obtainable for a step
+              │ all steps captured        ▼
+              ▼                    STOP — report which step blocked, don't fabricate
+┌───────────────────────────────┐
+│ 4. :draft-copy                     │──▶ FINAL mission/feature text + one-sentence "essence" line
+└───────────────────────────────┘
+              │
+              ▼
+┌───────────────────────────────┐
+│ 5. :illustrate                     │──▶ one companion illustration from the essence line
+└───────────────────────────────┘        (or a clean "omitted" note — never blocks the pipeline)
+              │
+              ▼
+┌───────────────────────────────┐
+│ 6. :compose                        │──▶ one self-contained interactive HTML file
+└───────────────────────────────┘
+              │
+              ▼
+┌───────────────────────────────┐
+│ 7. :review                         │──── fails a check ────┐
+└───────────────────────────────┘                            │
+              │ passes                                        │
+              ▼                                                │
+     report path, wait for explicit                            │
+     "publish/upload" instruction          loop back to :compose / :capture / :illustrate
+```
+
+| Step | Input | Output | On failure |
+|---|---|---|---|
+| 0. `:select` | project (cwd or named) + optional feature hint | one confirmed project + one confirmed feature name + why it's demo-worthy | **STOP** — report if no clear feature can be confirmed (don't guess) |
+| 1. `:research` | confirmed project + feature | mission/description (project-level), feature description, key files, how it actually works | n/a — always produces notes, flags gaps explicitly rather than inventing claims |
+| 2. `:storyboard` | mission + feature notes | ordered list of `{step, action, expected_screen, caption}` — one aspect per step | n/a — storyboard is a draft, `:capture` is allowed to correct it |
+| 3. `:capture` | storyboard | one real screenshot file per step + any corrected captions | **STOP** on that step — report what's missing; never substitute a placeholder/mockup image |
+| 4. `:draft-copy` | research notes + captured captions | final Mission & Feature Description prose + one-sentence essence line | n/a — always produces final text, gaps stay explicit |
+| 5. `:illustrate` | the essence line (text must exist first) | one companion illustration, tagged distinct from screenshots — or an explicit omission note | never blocks — skips cleanly if no image generator is configured, or after one off-brief retry |
+| 6. `:compose` | final copy + captured steps + optional illustration | one self-contained HTML file (or html+images folder per config) | loop back to `:capture` if a required image is missing, else fix and retry |
+| 7. `:review` | the composed HTML | pass/fail against the gate below | loop back to `:compose` (content), `:capture` (screenshot), or `:illustrate` (mislabeled companion image) — never ship on a failed gate |
+
+## Golden rule: screenshots are real or the step doesn't exist
+
+This skill exists specifically because "feature demo" content is worthless if the images are
+invented, stale, or from the wrong build. `:capture` uses `mcp__playwright__*` (or the project's
+own screenshot tooling if `run`/a project skill already drives it — check for one first) against
+a running instance of the actual project. If a step can't be captured for real (app won't start,
+feature is behind auth you don't have, flow requires data that doesn't exist locally), **that
+step is dropped and reported, not faked.** A shorter, honest demo beats a complete, fabricated one.
+
+## Output
+
+Default: one self-contained `.html` file (inline CSS/JS, base64-embedded images) written to
+`docs/feature-showcase/<feature-slug>.html` inside the target project — see
+`feature.config.yaml` for the exact path convention, size ceiling, and the single-file vs.
+folder fallback (used when embedded images would blow past the size ceiling). This is what
+"uploadable anywhere" means: no server, no relative asset paths, no build step — open the file
+or drop it on any static host and it works.
+
+**Only push, deploy, or upload when explicitly asked.** Report the local path and a one-line
+description of what the page shows, and wait — same convention as `blog-from-git`'s seed gate
+and `issue-address`'s "only push when asked" rule.
+
+## Why nested skills instead of one inline pass
+
+Same reasoning as `issue-address` and `pr-review-sweep`: each phase is a real, independently
+invokable `SKILL.md` so progress is visible step by step ("storyboard produced 5 steps, capture
+got 4 real screenshots, 1 dropped") instead of one opaque generation pass, and a single phase
+(e.g. swapping the screenshot tool, changing the HTML theme) can be edited without touching the
+others. If a step is still doing too much once this ships, decompose it further the same way
+`issue-address:select` was (nested sub-DAG) — continuously, wherever one file covers too much to
+inspect as one unit.
+
+## Folder map
+
+```
+blog-for-project-feature/
+  feature.config.yaml ← output path convention, size ceiling, theme tokens — read first
+  SKILL.md             ← this file: pipeline, DAG, output contract
+  0-select/SKILL.md
+  1-research/SKILL.md
+  2-storyboard/SKILL.md
+  3-capture/SKILL.md
+  4-draft-copy/SKILL.md
+  5-illustrate/SKILL.md
+  6-compose/SKILL.md
+  7-review/SKILL.md
+```
+
+## What this skill is not
+
+- Not `blog-from-git` — no dated post, no rotation ledger, no git-diff scan. This is
+  feature-scoped and evergreen; that skill is time-scoped and narrative.
+- Not a marketing copy generator — every claim in `:research`'s output must trace to real code,
+  docs, or a live screenshot, same evidentiary bar as `blog-from-git`'s `ground.md`.
+- Not a full site generator — one feature, one page, per run. A project with N features worth
+  showcasing gets N runs (and, if wanted later, a separate index/landing skill — not built yet,
+  don't invent one inline).

package/plugins/session-manager-dev/skills/blog-for-project-feature/feature.config.yaml

@@ -0,0 +1,74 @@
+# Grounding authority for blog-for-project-feature. Read this before any sub-skill file.
+# If prose in a SKILL.md ever disagrees with this file, this file wins.
+
+output:
+  # Path is relative to the TARGET project's repo root (the project being showcased),
+  # not this plugin's own repo.
+  path_template: "docs/feature-showcase/{feature-slug}.html"
+  feature_slug_rule: "kebab-case, derived from the confirmed feature name in :select"
+  # Prefer one self-contained file. Only fall back to a folder when the size ceiling
+  # below would be exceeded by inlining images.
+  default_mode: single_file          # single_file | folder
+  folder_fallback_layout:
+    html: "docs/feature-showcase/{feature-slug}/index.html"
+    images: "docs/feature-showcase/{feature-slug}/screenshots/"
+  single_file_size_ceiling_mb: 8       # switch to folder_fallback_layout above this
+  never_upload_or_deploy_without_explicit_ask: true
+
+images:
+  format: png
+  max_width_px: 1600                  # downscale before embedding; demo clarity, not pixel-perfect
+  compression: "reasonable lossy ok for PNG->WebP if it keeps text legible; never so lossy captions become unreadable"
+  source_of_truth: "mcp__playwright__browser_take_screenshot against a real running instance"
+  placeholder_or_mockup_images: forbidden   # a dropped step beats a fabricated one
+
+illustration:
+  # The ONE companion image, generated by :illustrate — a distinct image class from the
+  # click-through screenshots above. Optional: omitted cleanly if no generator is configured.
+  runs_after: draft-copy               # never generate from anything but finalized copy
+  generator: "project-local generator if the target project has one, else Gemini
+    (gemini-2.5-flash-image via google-genai — same provider/pattern as Burrow's
+    app/shared/image_gen.py) using GEMINI_API_KEY / GOOGLE_API_KEY from the environment"
+  count: 1
+  placement: "Feature Description section header only — never inside the Click-Through Demo"
+  format: png
+  max_width_px: 1200
+  style: "conceptual/editorial illustration — mood/palette should follow the project's own
+    theme tokens above if it has brand colors, otherwise a clean flat/geometric style"
+  must_not_resemble: "a UI mockup, screenshot, or contain invented interface text/window chrome
+    — must be visually distinguishable from a real captured screen at a glance"
+  max_regeneration_attempts: 1
+  on_no_generator_available: "skip silently, no page-visible note, report to the operator only"
+
+content:
+  sections_required:
+    - "Project Mission & Description"   # 2-4 sentences, from :research, project-level not feature-level
+    - "Feature Description"             # what it does, why it matters, 1-2 short paragraphs
+    - "Click-Through Demo"              # the storyboard steps, one aspect revealed at a time
+  demo_interaction: "one-step-at-a-time reveal (next/prev controls or numbered tabs) — never a single long scroll dump of every screenshot at once"
+  tone: "same plain, non-salesy, show-don't-tell bar as blog-from-git/voice.md bot-tell blocklist — no 'excited to share', no grand-implication filler"
+  caption_rule: "every screenshot has a one-sentence caption naming what changed on screen, not what the code does internally"
+
+theme:
+  # Minimal neutral tokens so every showcase looks consistent without importing a design system.
+  # Swap these per-project only if the project has its own documented brand tokens.
+  font_stack: "system-ui, -apple-system, 'Segoe UI', sans-serif"
+  bg: "#0b0d10"
+  surface: "#15181d"
+  text: "#e8eaed"
+  text_muted: "#9aa0a6"
+  accent: "#5b9dff"
+  radius_px: 10
+  max_width_px: 900
+
+gates:
+  # Checked in step 7 (:review). All must pass before reporting the page ready.
+  - "every image referenced actually loads (no broken src, no 404 in a local file:// open)"
+  - "zero placeholder/mockup images — every screenshot traces to a real :capture run"
+  - "if present, the companion illustration sits only in the Feature Description header and is
+    visually distinguishable from a real screenshot (no UI chrome/invented interface text)"
+  - "all three required sections present and non-empty (illustration is optional, never gates)"
+  - "demo is click-through (has working next/prev or tab controls), not a flat scroll"
+  - "file opens correctly via file:// with no console errors (network calls, external CDN fonts/JS forbidden — must be fully offline-capable)"
+  - "single_file_size_ceiling_mb respected, or folder fallback used instead"
+  - "no invented claims — every sentence in Mission/Feature sections traces to :research notes"

package/plugins/session-manager-dev/skills/develop/standards.md

@@ -88,6 +88,7 @@ Data-driven from 400+ scheduler runs: long hangs (not bad code) are the dominant
 - **Negative-assertion checks must exit 0 when clean.** A check that verifies the *absence* of something (a `grep` that should find nothing, "no leftover X", `diff` expecting no change) must return exit 0 on the clean case. A bare `grep` exits **1 on no-match** — so the *success* path surfaces as `is_error=true` and the verifier downgrades a perfect run to `needs_review`. Always invert: `if <detector>; then echo "HALT: <what was found>"; exit 1; fi; echo clean`. Never let the no-match/empty path carry the non-zero exit.
 - **Recover or annotate every error — don't strand a Traceback in the transcript.** The verifier downgrades an otherwise-perfect run to `needs_review` when a `Traceback`/`Error` appears with *no visible recovery within ~10 lines* (the `transcript_errors` heuristic — the single most common false-positive on green deliverables). Two executor habits cause it: (1) **throwaway probes that error** — an inline `python -c` with a quoting/f-string slip, a wrong kwarg, a bad path. When a probe errors, immediately re-run the corrected version *or* print one line `# expected/handled: <why>` right after, so recovery is adjacent. Don't move on leaving a bare error as the last thing in that step. Prefer a small temp `.py` file over a fragile multi-quote `python -c` one-liner (inline f-string errors are the top source of stranded tracebacks). (2) See the timeout rule below.
 - **An *expected* bounded-timeout (exit 124) must be annotated, not bare.** `timeout`-capping a genuinely long task you expect to hit the cap (a full-universe ingest, a long scan) is correct — but a bare `Exit code 124` reads as a failure to the verifier. Wrap it so the cap is a success-with-note: `timeout 120 <cmd> || { rc=$?; [ $rc -eq 124 ] && echo "hit time cap — idempotent/partial, rows persist incrementally; OK" || { echo "HALT: <cmd> failed rc=$rc"; exit 1; }; }`. (Distinguish 124 = expected cap from a real non-zero.) For work that legitimately needs longer than a safe cap, run it in the background and poll a bounded number of times rather than capping the foreground command.
+- **Polling remote CI/job status: never `sleep N && <cmd>`, and annotate the pending exit code.** The harness hard-blocks a `sleep` chained to another command (`Blocked: sleep 90 followed by: gh pr checks ...`) and that block lands in the transcript as a bare `is_error=true` — usually in the last 20% of the run, right where the verifier weighs errors most. To wait for a remote run, use the tool's own blocking watcher under a hard cap: `timeout 600 gh run watch <run-id> --repo <owner>/<repo> --exit-status`. Also note `gh pr checks` is a **negative-assertion-shaped command**: it exits `8` while checks are pending and `1` when a check failed or none are reported — so the ordinary "still running" path is non-zero. Wrap it so the expected cases print a clean token rather than a bare error: `if out=$(timeout 60 gh pr checks <n> --repo <r> 2>&1); then echo "CI GREEN"; else rc=$?; echo "gh pr checks rc=$rc (8=pending, 1=fail/none) — expected/handled"; fi`. (Incident: PRD 745 fixed PR #188's Lint + Docs-integrity failures, pushed, and CI went fully green — but its `sleep 20 && gh pr checks` (exit 8) and `sleep 90 && gh pr checks` (harness-blocked) sat unannotated at the very end of the transcript and the run was flagged despite a truthful PASS and a landed commit.)
 - **Finish so the verifier auto-clears you.** The scheduler appends a finish protocol that requires you to COMMIT your work and emit `SCHEDULER_VERDICT: PASS` (or `FAIL <reason>` + `exit 1`) as the literal last line. Honor it exactly: a *truthful* PASS plus a commit that landed during the run is what lets the verifier override incidental transcript noise (a grep hit containing "Error", a TDD red-phase run, a debug Traceback) instead of parking the job in `needs_review` for a human. A job that exits 0 with **uncommitted** changes, or with no PASS sentinel, is the #1 cause of needless `needs_review`. Never print PASS on a red gate — a lying PASS turns the verifier into a silent-failure shipper.
 - **Don't leak expected-error text into tool output.** The verifier pattern-matches transcript content for `Traceback`/`FAIL`/`Error:`. When a step is *expected* to error (a TDD red-phase test, an availability/existence probe, a "should raise" assertion), don't let the raw exception land verbatim — capture it and surface a clean token instead: `if python -c '…' 2>/dev/null; then echo PROBE_OK; else echo PROBE_ABSENT; fi`, or pipe the noisy run through a matcher that prints only `RED (expected)` / `GREEN`. When you retry a transient failure, re-run the **same command with the same description** — the verifier's self-recovery detector pairs a failed call with a later identical-description call that succeeds and clears it.
 - **End green: run the acceptance/test gate LAST, and let nothing error after it.** The post-run verifier scans the transcript and downgrades to `needs_review` on error markers — and weighs the *final* portion of the run most heavily (a tool error in the last ~20% trips it even if everything actually passed). So order the run so the last command is the green AC gate: do any intentionally-failing step (e.g. a TDD red test, an expected-nonzero probe) **early**, never after the gate. If you must demonstrate a failure late, capture it so it doesn't surface as a raw `is_error`/`Traceback` (`… 2>&1 | tail` inside a conditional, or assert on the captured text) rather than letting it hit the transcript bare.

package/plugins/session-manager-dev/skills/issue-address/0-select/0-fetch-pool/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: issue-address:select:fetch-pool
+description: Fetch the FULL open-issue pool on the current project's repo with bodies, with verified completeness (not just a fixed --limit guess). First sub-step of issue-address:select.
+---
+
+# issue-address:select:fetch-pool
+
+## Steps
+
+1. **Fetch with a generous limit, then verify nothing was truncated** — don't trust a
+   single fixed `--limit` the way an earlier version of this skill (and, separately,
+   `pr-review-sweep`'s original GraphQL query) did; both silently truncated real data on
+   this repo before. Converge instead of guessing:
+   ```bash
+   LIMIT=100
+   while true; do
+     COUNT=$(gh issue list --repo "$(gh repo view --json nameWithOwner -q .nameWithOwner)" --state open --limit "$LIMIT" --json number --jq 'length')
+     if [ "$COUNT" -lt "$LIMIT" ]; then break; fi   # got everything — count came in under the cap
+     LIMIT=$((LIMIT * 2))                            # cap was hit exactly — double and re-check
+   done
+   gh issue list --repo "$(gh repo view --json nameWithOwner -q .nameWithOwner)" --state open --limit "$LIMIT" \
+     --json number,title,body,labels,assignees,comments,createdAt,reactionGroups
+   ```
+   `COUNT == LIMIT` is the tell that you hit the ceiling, not the true end of the list —
+   never treat that as "done." Only stop once a fetch returns fewer results than it was
+   capped at.
+
+2. **Fetch bodies, not just titles.** Title-only scanning is what let issue #180 get
+   picked without anyone reading its file/line citations first. `body` and `comments` are
+   required output fields, not optional — the next sub-steps depend on them.
+
+3. **Also fetch `reactionGroups`** (👍/👎 counts) — a real, if imperfect, community-signal
+   input for `issue-address:select:rank-impact` later, beyond just label text.
+
+## Output
+
+The full, verified-complete list of open issues with bodies, labels, assignees, comments,
+and reaction counts — handed to `issue-address:select:reject-fixed` next.

package/plugins/session-manager-dev/skills/issue-address/0-select/1-reject-fixed/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: issue-address:select:reject-fixed
+description: Reject candidates from issue-address:select:fetch-pool's pool that are already fixed in current code, by checking the actual file/behavior each issue cites against a freshly-fetched origin/main — semantically, not just a literal string grep. Second sub-step of issue-address:select.
+---
+
+# issue-address:select:reject-fixed
+
+The check that would have caught issue #180 before any other work started — its body
+cited `apps/web/app/app.css` around specific line numbers, and the current code already
+had the exact fix (`min-width: 0`) the issue was reporting the absence of.
+
+## Steps
+
+0. **Fetch fresh before checking anything.** `git fetch origin main` first, and read
+   against `origin/main`, not a local branch — a local checkout can be stale or on an
+   unrelated feature branch, and a stale read produces a false "still broken" verdict.
+   (Found live: `#194` looked unfixed against a stale local branch, but `origin/main` had
+   merged the fix days earlier.)
+
+1. **For each candidate whose body cites a specific file, line, function, or CSS
+   selector/rule**, read the actual current code at that location:
+   ```bash
+   git show origin/main:<cited-path> | sed -n '<start>,<end>p'
+   ```
+   or grep for the cited selector/function name if line numbers have drifted (files get
+   reorganized — issue #180's citation was for `apps/web/app/app.css`, which had since
+   been split into `apps/web/app/styles/*.css`; searching by class/function name across
+   the styles directory found the real current location).
+
+2. **Check the behavior semantically, not just for the literal string the issue used.** A
+   fix can land in a different code *shape* than the issue's own words. (Found live: `#57`
+   asked for a `<link rel="canonical">` tag; a literal grep for `rel="canonical"` found
+   nothing, so the naive check would have called it unfixed — but the actual fix was a
+   data-driven React Router `meta()` descriptor, `{ tagName: 'link', rel: 'canonical', href
+   }`, which produces the same tag at render time without ever containing that literal
+   string in source.) Before concluding "not fixed" on a bare grep miss:
+   - Search one level broader — the surrounding directory/module, a shared
+     helper/util file, a `meta.ts`/`config.ts`-style indirection layer — for the *behavior*
+     the issue describes, not just its exact wording.
+   - If the issue names a concrete symptom (a missing tag, a wrong computed value, a
+     missing gate), look for whatever code *produces* that output, however it's
+     structured, before deciding the symptom is still present.
+
+3. **Compare what the issue describes as broken against what the code currently does.**
+   If the issue's own hypothesized fix (or an equivalent one, per step 2) is already
+   present — reject, log as `already-fixed`, cite the exact current file:line as evidence.
+   Don't spend a full `issue-address:reproduce` pass confirming what a direct code read
+   already answered.
+
+4. **If the citation is vague, or the file has moved/renamed and a reasonably broadened
+   search (step 2) still finds nothing**, don't reject on inconclusive evidence — mark the
+   candidate `unconfirmed` and let it pass through to the next sub-step. This step only
+   rejects on positive evidence of an existing fix, never on failure-to-locate.
+
+5. **If the git history around that file shows the fix landed suspiciously close to the
+   issue's `createdAt`** (within a day or two, either direction), note that explicitly —
+   it's a strong signal the report and the fix crossed in flight (exactly what happened
+   with #180: fix committed 2026-06-29, issue filed 2026-06-30).
+
+## Output
+
+Two lists: `already-fixed` (rejected, with evidence) and `survives` (candidates to pass to
+`issue-address:select:reject-claimed` next, tagged `unconfirmed` where this step couldn't
+conclusively check).

package/plugins/session-manager-dev/skills/issue-address/0-select/2-reject-claimed/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: issue-address:select:reject-claimed
+description: Reject candidates already covered by a PR (open, OR closed-but-superseded-by-a-merged-successor) or already claimed by an assignee/comment/supersede-note — with every text-search hit manually confirmed before being trusted. Third sub-step of issue-address:select.
+---
+
+# issue-address:select:reject-claimed
+
+## Steps
+
+1. **Search for a PR that might already cover each surviving candidate — open AND
+   closed, not just open:**
+   ```bash
+   gh pr list --repo "$(gh repo view --json nameWithOwner -q .nameWithOwner)" --state all --search "<N> in:body"
+   gh api search/issues -f q='repo:$(gh repo view --json nameWithOwner -q .nameWithOwner) is:pr <N>'
+   ```
+   Also skim PR titles for matching subject matter (same file area, same symptom) — a PR
+   can fix an issue's bug without a formal `Closes #N` link. Searching only `state:open`
+   misses the real case found live: `#194` had two closed (not merged) PRs, `#203`/`#215`,
+   each superseded — but the actual fix landed in a *third*, later PR (`#251`) that neither
+   text-search-by-issue-number pass would find unless the closed ones are read first and
+   followed to what replaced them (step 3).
+
+2. **Never trust a text-search hit without reading it.** This already produced a false
+   positive once: searching `"180 in:body"` matched PR #239 ("add automated price-anomaly
+   screen"), which had nothing to do with issue #180 — the digit string almost certainly
+   matched a line number or unrelated number elsewhere in that PR's body. For every
+   text-search hit:
+   - Open the matched PR's actual title + description.
+   - Confirm it genuinely addresses the same file area / same symptom the issue describes
+     — not just that the issue number appears somewhere in the text.
+   - If it's a false positive (number coincidence, unrelated context), **discard the match
+     and keep the candidate as unclaimed** — don't reject on a search artifact.
+
+3. **For every closed-but-not-merged PR found in step 1, read its closing comment before
+   deciding the candidate survives.** A PR closed without merging is not automatically
+   "unclaimed again" — read why it closed:
+   ```bash
+   gh pr view <PR#> --repo "$(gh repo view --json nameWithOwner -q .nameWithOwner)" --json state,mergedAt,closedAt,comments
+   ```
+   - If the closing comment says the work was split/replaced ("затварям... но не защото
+     работата е отпаднала", "closing in favor of #N", "superseded by #N", "merged into
+     #N"), **follow the chain to whatever PR(s) it names**, and check *their* merge state
+     the same way. Keep following until you reach a terminal state (merged = reject as
+     already-fixed; still open = reject as already-covered; abandoned with no successor =
+     candidate survives).
+   - This chain can be more than one hop deep (found live: `#194`'s PR `#203` was split
+     into `#251`/`#252`/`#253`; a sibling PR `#215` was independently closed in favor of
+     the same `#251`) — don't stop at the first successor if its own comments point
+     further.
+
+4. **Reject candidates already claimed by a person, or already noted as superseded in the
+   issue's OWN comments** (not just a linked PR's). Check `assignees` (non-empty =
+   explicit claim) and skim the issue's `comments` for:
+   - Claim language: "работя по това", "assigned to me", "I'll pick this up".
+   - Supersede/decompose language: "предлагам да се затвори в полза на", "closing in
+     favor of", "split into #N / #M / #P", "superseded by". (Found live: `#154`'s own
+     comment thread explicitly proposed closing it in favor of child issues `#156`/`#158`/
+     `#163` — a signal that lives in the issue's comments, not in any PR search at all.)
+   Reject on either signal — don't take work someone else already started or already
+   restructured, even informally.
+
+5. **Search for a duplicate open issue** describing the same underlying bug under a
+   different number — `gh issue list --state open --search "<keywords>"`, same
+   confirm-before-trusting rule as step 2 applies here too. If a better-established
+   duplicate exists, flag it rather than silently picking one.
+
+## Output
+
+`survives` list (candidates cleared of PR/claim/supersede/duplicate overlap — including
+resolved multi-hop PR chains — with any false-positive search hits explicitly noted as
+discarded) handed to `issue-address:select:rank-impact`.

package/plugins/session-manager-dev/skills/issue-address/0-select/3-rank-impact/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: issue-address:select:rank-impact
+description: Rank surviving candidates by a composite impact signal (priority label + community reactions + cross-references + repro quality), not label text alone, and output exactly one issue number. Final sub-step of issue-address:select.
+---
+
+# issue-address:select:rank-impact
+
+## Steps
+
+1. **Score each surviving candidate on multiple signals, not just its `priority:` label**
+   (a label-only heuristic silently mis-ranks an unlabeled-but-severe issue below a
+   labeled-but-minor one):
+   - **Priority label**: `high` > `medium` > `low` > none (weakest single signal alone).
+   - **Category label**: `bug`/`security`/`data-quality` outrank `enhancement`/
+     `discussion`/`docs` for this skill's purpose (fixing something broken, not building
+     something new).
+   - **Community reaction count** (from `fetch-pool`'s `reactionGroups`) — more 👍 reactions
+     is a real signal of user-felt impact independent of whatever label was applied at
+     triage time.
+   - **Cross-references** — check `gh issue view <N> --json timelineItems` (or equivalent)
+     for how many other issues/PRs reference this one; a heavily-cross-referenced issue is
+     blocking or informing other work, raising its effective priority above its label.
+   - **Repro quality** — concrete repro steps / cited file-line locations beat a vague
+     report; cheaper to reproduce reliably, lower risk of another #180-style dead end.
+
+2. **Combine into a ranked order** — no single signal should override all others (e.g.
+   don't let one 👍 reaction alone outrank an explicit `priority: high` label; use
+   priority + category as the primary sort, reaction count + cross-references as
+   tie-breakers within a tier, repro quality as the final tie-breaker).
+
+3. **Output exactly one issue number** — the top of the ranked list — with a one-line
+   justification citing which signals won, plus the full ranked list (not just the
+   winner) and the rejected list from the earlier two sub-steps, so the whole selection
+   is auditable, not just its conclusion.
+
+## Output
+
+Hand off the single selected issue number to `issue-address:confirm-open`, which
+re-verifies it fresh (state, PR/duplicate claims) immediately before work starts.

package/plugins/session-manager-dev/skills/issue-address/0-select/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: issue-address:select
+description: Step 0 of issue-address — select exactly ONE open issue on the current project's repo to work, by orchestrating 4 nested sub-skills (fetch-pool, reject-fixed, reject-claimed, rank-impact) in sequence. Only invoked when the caller hasn't already named a specific issue number.
+---
+
+# issue-address:select (sub-orchestrator)
+
+Only runs when `issue-address` is invoked without a specific issue number already named
+(if the caller already has one, skip straight to `issue-address:confirm-open` — that step
+re-verifies the single chosen issue right before work starts, as a freshness guard; this
+skill's job is choosing which issue out of many, cheaply and verifiably, across the whole
+pool).
+
+Exists because of a real incident: issue #180 was picked by title/label alone, and 2 full
+`issue-address` steps ran before discovering — only once `issue-address:reproduce`
+actually tried to reproduce it — that the fix had already shipped a day before the issue
+was even filed. The information needed to catch that (the issue's own cited file/line + a
+grep of current code) was available for free at selection time and simply wasn't checked.
+
+This skill is itself further decomposed into 4 nested sub-skills, for the same reason
+`issue-address` is decomposed: so each check is independently invokable and its result
+inspectable, instead of one opaque scan-and-pick pass. It also closes two gaps found after
+the first version shipped: an unverified fetch limit (the same class of silent-truncation
+bug that hit `pr-review-sweep`), and an unconfirmed PR-search false positive (seen live in
+the #180 trial — a text search on "180" matched an unrelated PR by number coincidence).
+
+**Naming convention:** sub-directories are prefixed `0-`, `1-`, `2-`, `3-` in execution
+order (see `issue-address/SKILL.md` for the repo-wide rule) — a plain directory listing of
+this folder sorts in DAG order without opening any file.
+
+## Pipeline DAG
+
+```
+open-issue pool
+      │
+      ▼
+┌─────────────────────────────┐
+│ 0. select:fetch-pool         │  verified-complete fetch (no silent truncation)
+└─────────────────────────────┘
+      │ full pool w/ bodies, labels, assignees, comments, reactions
+      ▼
+┌─────────────────────────────┐
+│ 1. select:reject-fixed       │  grep current code at each cited file/line
+└─────────────────────────────┘
+      │ survives (already-fixed candidates dropped, evidence logged)
+      ▼
+┌─────────────────────────────┐
+│ 2. select:reject-claimed     │  PR-search hits confirmed, not trusted blind
+└─────────────────────────────┘
+      │ survives (PR'd/claimed/duplicate candidates dropped, evidence logged)
+      ▼
+┌─────────────────────────────┐
+│ 3. select:rank-impact        │  composite score, not label text alone
+└─────────────────────────────┘
+      │
+      ▼
+one issue number + full audit trail (ranked list, rejected list, why)
+      │
+      ▼
+issue-address:confirm-open  (next skill up the chain, outside this sub-orchestrator)
+```
+
+| Step | Input | Output | On failure/empty |
+|---|---|---|---|
+| 0. `select:fetch-pool` | none (repo-wide `gh issue list`) | full open-issue pool, verified-complete | n/a — loops its own fetch until verified complete |
+| 1. `select:reject-fixed` | full pool | `already-fixed` list (w/ evidence) + `survives` list | if pool empties out here, report "no candidates, all already fixed" |
+| 2. `select:reject-claimed` | `survives` from step 1 | `already-claimed` list (w/ evidence) + `survives` list | if pool empties out here, report "no candidates, all claimed/PR'd" |
+| 3. `select:rank-impact` | `survives` from step 2 | one issue number + ranked list + justification | if `survives` was already empty, report the empty pool rather than fabricating a pick |
+
+## Output
+
+Hand off the single selected issue number to `issue-address:confirm-open`, which
+re-verifies it fresh (state, PR/duplicate claims) immediately before work starts — this
+skill's checks are about narrowing a big pool cheaply and verifiably; confirm-open's
+checks are about not acting on stale information for the one issue actually chosen.

package/plugins/session-manager-dev/skills/issue-address/1-confirm-open/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: issue-address:confirm-open
+description: Step 1 of issue-address — confirm a named GitHub issue on the current project's repo is genuinely OPEN and not already claimed/fixed by another PR or duplicate issue, before any work starts. Returns a clear go/no-go.
+---
+
+# issue-address:confirm-open
+
+Called with one issue number `<N>`. Produces a go/no-go verdict before any code work begins.
+
+## Steps
+
+1. **Fetch the issue.**
+   ```bash
+   gh issue view <N> --repo "$(gh repo view --json nameWithOwner -q .nameWithOwner)" --json state,title,body,comments,url
+   ```
+   If `state` is not `OPEN` — **stop, no-go.** Report the actual state (closed/merged
+   reference) and why. Do not proceed to reproduce or fix a closed issue.
+
+2. **Search for an existing open PR that already covers it** — check both explicit links
+   and subject-matter overlap, since a PR can fix the bug without a formal `Closes #N`:
+   ```bash
+   gh pr list --repo "$(gh repo view --json nameWithOwner -q .nameWithOwner)" --state open --search "<N> in:body"
+   gh api search/issues -f q='repo:$(gh repo view --json nameWithOwner -q .nameWithOwner) is:pr is:open <N>'
+   ```
+   Also skim open PR titles for matching subject matter (same file area, same symptom).
+   If found — **stop, no-go.** Report which PR number and why it looks like a match; don't
+   duplicate work already in flight.
+
+3. **Search for a duplicate open issue** covering the same underlying bug (different
+   number, same root cause) — `gh issue list --repo "$(gh repo view --json nameWithOwner -q .nameWithOwner)" --state open --search
+   "<keywords>"`. If a duplicate exists and is a better-established report, flag it — the
+   caller decides which one to actually work.
+
+4. **Verdict.** Return one of:
+   - **GO** — issue is open, unclaimed, no duplicate blocking it. Include the issue title,
+     body, and any repro steps mentioned in comments, so the next step doesn't have to
+     re-fetch them.
+   - **NO-GO** — state why (closed / already covered by PR #X / duplicate of #Y), and stop
+     the whole `issue-address` sequence here. Do not continue to reproduce/fix.

package/plugins/session-manager-dev/skills/issue-address/2-claim/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: issue-address:claim
+description: Step 2 of issue-address — claim a confirmed-open, confirmed-unclaimed issue on the current project's repo before reproducing/fixing it, by self-assigning and posting a claim comment via the gh CLI (no dedicated GitHub MCP server is connected in this environment — gh is the actual mechanism). Closes the race condition where two runs could pick the same issue.
+---
+
+# issue-address:claim
+
+Runs immediately after `issue-address:confirm-open` returns GO, and before
+`issue-address:reproduce` starts any work. Exists because confirming an issue is
+open/unclaimed and then *starting work on it* are two different moments in time — without
+an explicit claim in between, a second concurrent run of this same skill (or a human
+contributor) could pick the same issue, and nothing in `issue-address:select`'s
+`reject-claimed` check would have caught it, since that check only looks for assignees and
+existing claim-language comments — which don't exist yet for an issue nobody has started.
+
+**No dedicated GitHub/issue-tracking MCP server is connected in this environment** — every
+GitHub interaction in this whole skill chain (and everywhere else this session) goes
+through the `gh` CLI via Bash. If a GitHub MCP server becomes available later, swap the
+commands below for its equivalent calls; until then, `gh` is the actual mechanism, not a
+gap to work around.
+
+## Steps
+
+1. **Self-assign**, so the issue shows a claim to anyone else's `select:reject-claimed`
+   pass or manual look:
+   ```bash
+   gh issue edit <N> --repo "$(gh repo view --json nameWithOwner -q .nameWithOwner)" --add-assignee "@me"
+   ```
+   If self-assignment fails (e.g. insufficient repo permissions — a common case for
+   external contributors on a repo they don't have write access to), don't halt the
+   sequence on that alone; fall back to step 2's comment as the claim signal, and note in
+   the report that assignment wasn't possible so a human knows to check.
+
+2. **Post a claim comment** — visible even to someone who doesn't check assignees,
+   and consistent with the claim-language `select:reject-claimed` already scans for
+   ("I'll pick this up", "working on this"; a project with a non-English contributor base,
+   e.g. `midt-bg/sigma`'s Bulgarian-speaking reviewers, may localize this string — check
+   the project's own `AGENTS.md`/`CLAUDE.local.md` for a house phrase before defaulting to
+   English):
+   ```bash
+   gh issue comment <N> --repo "$(gh repo view --json nameWithOwner -q .nameWithOwner)" --body "Working on this issue (issue-address skill chain). Will link the PR here after fix + verify."
+   ```
+
+3. **Re-confirm the claim actually landed** before proceeding — read the issue back and
+   check the assignee list and/or the posted comment are present:
+   ```bash
+   gh issue view <N> --repo "$(gh repo view --json nameWithOwner -q .nameWithOwner)" --json assignees,comments
+   ```
+   If neither the assignment nor the comment is visible, don't silently proceed as if
+   claimed — report the failure; a claim that didn't actually post protects nobody.
+
+## Output
+
+Hand off to `issue-address:reproduce` — same issue number, now with a real claim on
+record. If this step's own re-confirmation fails (step 3), stop the sequence and report,
+same severity as a `confirm-open` NO-GO — proceeding to reproduce/fix on an issue that
+isn't actually marked claimed defeats the point of adding this step.