claude-dev-env 1.92.1 → 1.93.1

package/skills/pr-loop-cloud-transport/reference/substitution-matrix.md

@@ -0,0 +1,48 @@
+# gh-to-MCP operation substitution matrix
+
+Route every `gh` operation a PR-loop skill names through its cloud path. Load the MCP schemas first (SKILL.md Step 1) — a call before its schema loads fails with `InputValidationError`. Every row traces to a live probe or the operation inventory recorded in `docs/references/cloud-pr-loop-compatibility.md` in the source repo.
+
+## Contents
+
+- The operation matrix
+- Pagination rules
+- The REST fallback and its scope
+
+## The operation matrix
+
+| Operation | Local mechanism | Cloud path |
+|---|---|---|
+| Read PR / mergeability / draft state | `gh pr view`, `gh api pulls/N` | `mcp__github__pull_request_read(method="get")` |
+| PR diff / files / commits / checks | `gh pr diff`, `gh api ...` | `mcp__github__pull_request_read(method="get_diff"/"get_files"/"get_commits"/"get_check_runs")` |
+| List reviews / review threads | `gh api --paginate --slurp \| jq` | `mcp__github__pull_request_read(method="get_reviews"/"get_review_comments")` |
+| Post / update / close issue | `gh issue create/edit/close` | `mcp__github__issue_write(method="create"/"update")`; close an issue with `method="update", state="closed"` |
+| Post issue or PR comment | `gh issue comment`, `gh pr comment` | `mcp__github__add_issue_comment` |
+| Post review with inline comments | `gh api pulls/N/reviews` POST | `mcp__github__pull_request_review_write(method="create")` → `mcp__github__add_comment_to_pending_review` per finding → `mcp__github__pull_request_review_write(method="submit_pending", event="COMMENT")` |
+| Reply to a review comment | `gh api pulls/N/comments/ID/replies` | `mcp__github__add_reply_to_pull_request_comment` (numeric `discussion_r` id) |
+| Resolve / unresolve a thread | `gh api graphql resolveReviewThread` | `mcp__github__pull_request_review_write(method="resolve_thread"/"unresolve_thread", threadId="PRRT_...")` |
+| Request the Copilot reviewer | `gh api POST pulls/N/requested_reviewers` | `mcp__github__request_copilot_review`. The call completes with no output and no in-band confirmation either way; confirm by a Copilot review landing on the PR. |
+| Mark ready / send to draft | `gh pr ready`, `gh pr ready --undo` | `mcp__github__update_pull_request(draft=false / draft=true)`, with a read-back confirming the draft state each way |
+| Create a PR | `gh pr create --draft` | `mcp__github__create_pull_request(draft=true)` |
+| Edit a PR body or title | `gh pr edit` | `mcp__github__update_pull_request(body=..., title=...)` |
+| Cross-repo PR search | `gh search prs --owner X --state open` | `mcp__github__search_pull_requests(query="user:X is:open", perPage=30)` |
+| Check runs on a SHA | `gh api commits/SHA/check-runs` | `mcp__github__pull_request_read(method="get_check_runs")`, or REST for owners the app connection covers |
+| CI logs | `gh run view --log` | `mcp__github__actions_list` / `mcp__github__actions_get` / `mcp__github__get_job_logs` |
+| Clone another repo | `gh repo clone` | `git clone https://github.com/owner/repo` (session-scoped), or `mcp__Claude_Code_Remote__add_repo` first |
+| Copilot quota | `gh api copilot_internal/user` | None. Treat quota as unknown; call `mcp__github__request_copilot_review`, then read `copilot_down` from what lands on the PR (SKILL.md Step 5). |
+| Second reviewer identity | `gh auth switch`, `BUGTEAM_REVIEWER_ACCOUNT` | None. One MCP identity — the `mcp__github__get_me` login. `COMMENT` reviews on own PRs work; `APPROVE`/`REQUEST_CHANGES` on own PRs are blocked by GitHub. |
+
+## Pagination rules
+
+- `mcp__github__pull_request_read(method="get_reviews")` paginates with `page` + `perPage`.
+- `mcp__github__pull_request_read(method="get_review_comments")` paginates with `perPage` + an `after` cursor.
+- Always pass `perPage` on `mcp__github__search_pull_requests`: an unpaginated owner-wide search overflows the tool-result limit.
+
+## The REST fallback and its scope
+
+Raw REST through the agent proxy works only for owners the Claude GitHub App connection covers; a repo outside that coverage answers 403. The client shape:
+
+```
+curl -H "Authorization: Bearer $GH_TOKEN" --cacert /root/.ccr/ca-bundle.crt https://api.github.com/repos/<owner>/<repo>/...
+```
+
+GraphQL through the proxy is pinned to a served set of PR-review operations, so a hand-written `gh api graphql` query has no cloud path — read review threads through `mcp__github__pull_request_read(method="get_review_comments")` and resolve them through `mcp__github__pull_request_review_write(method="resolve_thread", ...)`.

package/skills/pr-loop-lifecycle/SKILL.md

@@ -1,15 +1,11 @@
 ---
 name: pr-loop-lifecycle
 description: >-
-  Opens and closes a PR-loop run: the .claude/** permission grant (with the
-  auto-mode AskUserQuestion escalation when the classifier blocks it),
-  worktree preflight and cwd routing, then the ordered close — conditional
-  TeamDelete for team callers, worktree teardown, working-tree clean, PR
-  description rewrite composed by the lead, the always-run permission
-  revoke, and the caller-parameterized final report. Invoked by PR-loop
-  orchestrators (bugteam, pr-converge, autoconverge, qbug) at run start and
-  run end, including error exits; not for general git cleanup or permission
-  management outside a PR loop.
+  Opens and closes a PR-loop run: the .claude/** permission grant, worktree
+  preflight, and cwd routing at the start; teardown, permission revoke, and
+  final report at the end. Invoked by PR-loop orchestrators (bugteam,
+  pr-converge, autoconverge, qbug); not for general git cleanup outside a PR
+  loop.
 ---
 
 # PR Loop Lifecycle

package/skills/pr-scope-resolve/SKILL.md

@@ -2,12 +2,9 @@
 name: pr-scope-resolve
 description: >-
   Resolves the audit/fix target for a PR-loop skill: owner, repo, PR number,
-  head ref, base ref, PR URL, and starting head SHA — via
-  pull_request_read(method="get"), a search_pull_requests branch fallback, then a
-  git merge-base upstream-diff fallback, ending in the canonical refusal line
-  when no target exists. Invoked by PR-loop orchestrators (pr-converge,
-  bugteam, qbug, findbugs, fixbugs) as their first step; not for general git
-  questions or branch management.
+  head and base refs, PR URL, and head SHA, with a canonical refusal when no
+  target exists. Invoked by PR-loop orchestrators (pr-converge, bugteam, qbug,
+  findbugs, fixbugs) first; not for general git questions.
 ---
 
 # PR Scope Resolve

package/skills/privacy-hygiene/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: privacy-hygiene
+description: Full-repo sweep for personal data and secrets before commit or durable GitHub post. Use when preparing a PR, cleaning a leak, or when `pii_prevention_blocker` denies a write, post, or commit. Triggers on "privacy hygiene", "personal data", "secret sweep", "sanitize repository", "/privacy-hygiene".
+---
+
+# privacy-hygiene
+
+## Overview
+
+Find and remove personal data and high-confidence secrets before they land in git history or a durable GitHub post. The `pii_prevention_blocker` hook blocks the common cases at write, post, and commit time. This skill is the full sweep when you need a broader pass or a remediation plan.
+
+**Announce at start:** "Running privacy-hygiene sweep."
+
+## When to run a full sweep
+
+- Before the first push of a branch that touched logs, screenshots, config samples, or machine-local paths
+- After a hook block on email, home path, LAN address, or secret material
+- Before opening a PR to a repository that is public (or will be made public)
+- After pasting support tickets, env dumps, or terminal transcripts into the tree
+
+## What the automated gate blocks
+
+| Category | Blocked examples | Allowed residual |
+|---|---|---|
+| Email | `person@company.io` | `user@example.com`, `user@example.org`, `user@example.net` |
+| Home path | `C:/Users/realname/...`, `/Users/realname/...`, `/home/realname/...` | `C:/Users/example/...`, `C:/Users/<you>/...`, `/Users/alice/...` |
+| LAN address | Unlisted `10.x` / `172.16–31.x` / `192.168.x` | Public addresses; your NAS host from `CLAUDE_NAS_HOST` or `~/.claude/local-identity.json`; entries in `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` |
+| Secret | `ghp_…`, `github_pat_…`, `AKIA…`, PEM private-key headers | Public keys, redacted `***`, env var names without values |
+
+Surfaces:
+
+1. **Write / Edit / MultiEdit** — payload text about to land on disk (via PreToolUse dispatcher)
+2. **Durable posts** — `gh pr/issue create|comment|edit|review` bodies and GitHub MCP body/comment fields (Bash and PowerShell)
+3. **git commit** — staged blob text (non-exempt paths) on Bash and PowerShell, including `git.exe` and flag forms (`--no-verify`, `-c`, `-C`). Commit message bodies (`-m` / `-F`) are out of scope for the automated gate
+
+## Sweep procedure
+
+### 1. Scope the tree
+
+```
+git status -sb
+git diff --stat
+git diff --cached --stat
+```
+
+Prefer the branch diff vs `origin/main` for PR prep:
+
+```
+git fetch origin main
+git diff --name-only origin/main...HEAD
+```
+
+### 2. Search for high-confidence patterns
+
+Run from the repo root (PowerShell-friendly example):
+
+```
+rg -n --hidden -g '!node_modules' -g '!.git' -e '@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' -e 'Users[/\\][^/\\]+' -e '/home/[^/]+' -e '\b(10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[0-1])\.\d+\.\d+)\b' -e '\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b' -e '\bgithub_pat_[A-Za-z0-9_]{20,}\b' -e '\bAKIA[0-9A-Z]{16}\b' -e '-----BEGIN [A-Z ]*PRIVATE KEY-----'
+```
+
+Review each hit. Ignore:
+
+- Test fixtures under `test_*.py` / `*_test.py` / `/tests/` (synthetic only)
+- `LICENSE` / copyright notice identity that is intentional and public
+- This package's own `pii_scanner` / `pii_prevention_constants` modules
+- Documented placeholders (`user@example.com`, `C:/Users/<you>/`)
+
+### 3. Remediate
+
+| Hit | Fix |
+|---|---|
+| Real email | Replace with `user@example.com` or remove |
+| Home path | Use `Path.home()`, `~`, or `C:/Users/<you>/` |
+| LAN address | Remove, use a hostname, or — for your own NAS — set the host in `CLAUDE_NAS_HOST` or `~/.claude/local-identity.json`, both of which stay out of git |
+| Credential material | Remove from the tree; rotate the credential; load from env/secret store |
+| Already committed | Rewrite is not enough if already pushed — rotate secrets; scrub history only with explicit user approval |
+
+### 4. Re-check before commit / post
+
+- Stage only clean files
+- Prefer `--body-file` for `gh` posts (also required by the gh-body-file rule)
+- Let `pii_prevention_blocker` re-run on the next Write / commit / post
+
+## Accepted residual (do not over-scrub)
+
+- LICENSE copyright lines naming a legal person or org that owns the work
+- Intentional public maintainer identity published on purpose
+- Example domains reserved for documentation (`example.com` and siblings)
+- Placeholder home users (`example`, `user`, `alice`, `<you>`, `YOUR_USER`)
+- The NAS host you configure locally (allowlisted at scan time, never committed)
+- Public addresses and docs that name private ranges without a live host (still prefer hostnames)
+
+## Enable on any machine / public repository
+
+Install or reinstall the package so hooks and this skill land under `~/.claude/`:
+
+```
+cd packages/claude-dev-env
+node bin/install.mjs
+```
+
+Hooks register via `hooks/hooks.json` into `~/.claude/settings.json`. Once installed, the same gates apply in every repository the agent touches — private or public.
+
+## Open knobs
+
+- **NAS / LAN allowlist:** Unlisted private IPs are blocked. The scanner resolves your NAS host from `CLAUDE_NAS_HOST`, then `~/.claude/local-identity.json` (`nas.host`), and allowlists it when it is a private address, so the committed tree holds no real host. `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` in `hooks_constants` holds the static allowlist for any host every machine must share.
+- **Public maintainer identity:** when a real email or name is intentional product surface, keep it and note that in the PR body so reviewers do not treat it as a leak.
+
+## What this skill does not do
+
+- Does not rewrite git history without explicit user approval
+- Does not rotate credentials for you
+- Does not replace the write-time hook — it complements it
+- Does not scan commit-message text (`-m` / `-F`); keep messages free of secrets yourself

package/skills/qbug/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: qbug
 description: >-
-  Required baseline review for every new PR. Runs the /bugteam audit → fix →
-  commit → push cycle via one clean-coder subagent (not a full team), looping
-  until convergence or stuck. Uses the same CODE_RULES gate, A–P category
-  rubric, and per-loop PR review shape as /bugteam — without TeamCreate,
-  teammates, per-loop clean-room, or a loop cap. Invoke /bugteam instead for
-  larger PRs that need per-loop bias isolation or a hard loop cap. Triggers:
-  '/qbug', 'quick bug audit', 'solo bug audit', 'baseline PR review',
-  'bugteam without a team'.
+  Required baseline review for every new PR: runs the /bugteam audit, fix,
+  commit, and push cycle through one clean-coder subagent (not a full team),
+  looping until convergence or stuck. Triggers: '/qbug', 'quick bug audit',
+  'solo bug audit', 'baseline PR review', 'bugteam without a team'.
 ---
 
 # qbug
@@ -25,6 +21,10 @@ Shared artifacts with /bugteam are referenced below by path, using the `${CLAUDE
 - **Audit contract** (finding schema, proof-of-absence, adversarial pass, Haiku secondary, post-fix self-audit, diagnostics JSON): [`_shared/pr-loop/audit-contract.md`](../../_shared/pr-loop/audit-contract.md)
 - PR comment lifecycle shape: [`bugteam/SKILL.md`](../bugteam/SKILL.md#audit-posting)
 
+## Transport check (before any GitHub step)
+
+Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push` and take `true` as the pass. When any check fails, run the `pr-loop-cloud-transport` skill first and route every `gh` operation in this skill through its substitution matrix.
+
 ## When this skill applies
 
 `/qbug` once authorizes the full cycle (no loop cap — runs until `converged` or `stuck`; user can interrupt at any time).

package/skills/rebase/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: rebase
-description: Rebase a branch onto its base ref with the verification gates needed to catch logically broken results before pushing. Use when the user invokes `/rebase`, says "rebase this branch", "PR has merge conflicts", "rebase onto main", or asks for a force-push to update a remote branch's history. Critical for stacked PRs where the base merged via squash, and for any rebase that includes deletions or renames.
+description: >-
+  Rebases a branch onto its base ref with the verification gates that catch
+  logically broken results before pushing. Use when the user invokes `/rebase`,
+  says 'rebase this branch', 'PR has merge conflicts', or 'rebase onto main', or
+  asks for a force-push to update a remote branch's history.
 ---
 
 # /rebase

package/skills/refine/SKILL.md

@@ -1,11 +1,10 @@
 ---
 name: refine
 description: >-
-  Interview-driven plan refiner with built-in audit loop: fans out research agents,
-  interviews via AskUserQuestion (mandatory — survives no-question directives), writes
-  the plan to the Obsidian vault under Research/<topic>/<slug>.md, then loops audit and
-  fix until clean. Triggers: /refine, "refine this", "turn this into a plan", "flesh
-  this out", "make a spec for this", "let's plan this out", or any vague idea to mature
+  Interview-driven plan refiner: fans out research agents, interviews through
+  AskUserQuestion, writes to the Obsidian vault, then loops audit and fix.
+  Triggers: /refine, 'refine this', 'turn this into a plan', 'flesh this out',
+  'make a spec for this', 'let's plan this out', or any vague idea to mature
   into a plan.
 ---
 

package/skills/reviewer-gates/SKILL.md

@@ -1,16 +1,10 @@
 ---
 name: reviewer-gates
 description: >-
-  Runs the availability gates a PR-loop orchestrator checks before engaging an
-  external reviewer: the CLAUDE_REVIEWS_DISABLED opt-out parse (bugbot,
-  bugteam, and copilot tokens via reviews_disabled.py), the once-per-run
-  Copilot premium-quota pre-check (copilot_quota.py with copilot_down
-  semantics), and the Cursor Bugbot trigger/acknowledge/CI-detect flow
-  (check_bugbot_ci.py with the literal `bugbot run` comment). Invoked by
-  PR-loop orchestrators — pr-converge, autoconverge, bugteam, qbug, findbugs,
-  copilot-review, monitor-open-prs — at run start and at each reviewer
-  engagement point. Not a general code-review skill; it decides whether a
-  reviewer runs, never what the reviewer finds.
+  Runs the availability gates a PR-loop orchestrator checks before it starts an
+  external reviewer: the CLAUDE_REVIEWS_DISABLED opt-out, the once-per-run
+  Copilot quota pre-check, and the Cursor Bugbot trigger, acknowledge, and
+  CI-detect flow. Decides whether a reviewer runs, never what it finds.
 ---
 
 # Reviewer Gates
@@ -34,13 +28,15 @@ The `CLAUDE_REVIEWS_DISABLED` environment variable is a comma-separated token li
 | `bugbot` | Cursor Bugbot triggering and polling |
 | `copilot` | GitHub Copilot review requests and polling |
 
+Cursor Bugbot is off by default: it runs only when `CLAUDE_REVIEWS_ENABLED` lists `bugbot`, and a `bugbot` token in `CLAUDE_REVIEWS_DISABLED` keeps it off even when the opt-in lists it.
+
 Run the shared parser — never an inline shell parse:
 
 ```bash
 python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer <bugbot|bugteam|copilot>
 ```
 
-- **Exit 0** — the named reviewer is opted out. A skill whose whole run depends on that reviewer responds with its refusal line and stops. The template: `/<caller> is disabled via CLAUDE_REVIEWS_DISABLED.` A loop that merely includes the reviewer as one gate marks the reviewer down (`bugbot_down = true`, `copilot_down = true`) and continues on its remaining signals.
+- **Exit 0** — the named reviewer is disabled for this run (opted out, or, for Bugbot, off by default without the `CLAUDE_REVIEWS_ENABLED` opt-in). A skill whose whole run depends on that reviewer responds with its refusal line and stops. A copilot- or bugteam-dependent caller names the opt-out: `/<caller> is disabled via CLAUDE_REVIEWS_DISABLED.` A Bugbot-dependent caller off by default names the opt-in the run needs: `/<caller> is disabled: Cursor Bugbot needs a bugbot token in CLAUDE_REVIEWS_ENABLED.` A loop that merely includes the reviewer as one gate marks the reviewer down (`bugbot_down = true`, `copilot_down = true`) and continues on its remaining signals.
 - **Exit 1** — the reviewer is available; continue.
 
 ## Gate 2: Copilot quota pre-check (once per run)

package/skills/session-log/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: session-log
 description: >-
-  Log a session report by composing a self-contained HTML page and publishing it with the Artifact tool, then track vault context, extract unrecorded decisions, tidy the project's session folder, and output a /rename command. Use when the user says /session-log, journal this session, log this work, session report, or any variation of "summarize/log/record this session". Also triggers on "save session", "capture session", or "document what we did".
+  Logs a session report as an HTML page, tracks vault context, extracts
+  decisions, and outputs a /rename command. Use for /session-log, 'journal this
+  session', 'log this work', 'session report', 'summarize/log/record this
+  session', 'save session', 'capture session', or 'document what we did'.
 ---
 
 # Session Log

package/skills/skill-builder/SKILL.md

@@ -1,12 +1,9 @@
 ---
 name: skill-builder
 description: >-
-  Orchestrates the complete skill-building lifecycle using best-practice-driven
-  development. Routes through type classification, folder scaffolding, skill
-  writing (via skill-writer), self-audit against a 38-point checklist, and
-  iterative refinement from real usage observations. Use when creating new
-  skills, improving existing skills, or optimizing skill descriptions.
-  Triggers: 'build a skill', 'new skill workflow', 'improve this skill',
+  Runs the skill-building lifecycle: type classification, scaffolding, writing
+  through skill-writer, self-audit against a checklist, and refinement from real
+  usage. Triggers: 'build a skill', 'new skill workflow', 'improve this skill',
   'optimize skill description', 'skill development lifecycle'.
 ---
 

package/skills/structure-prompt/SKILL.md

@@ -1,11 +1,10 @@
 ---
 name: structure-prompt
 description: >-
-  Restructure a user-provided prompt: order blocks, replace persona framing with task
-  constraints, enforce per-category dispositions, expand placeholder tokens via the
-  sibling rubric or AskUserQuestion, add file:line citations, mark the canonical
-  sub-bucket, sharpen adversarial-pass phrasing. Triggers: /structure-prompt, "optimize
-  this prompt", "minimally invasive edit" to a prompt artifact, "tighten this prompt".
+  Restructures a user-provided prompt: orders blocks, swaps persona framing for
+  task constraints, expands placeholder tokens, and adds file:line citations.
+  Triggers: /structure-prompt, 'optimize this prompt', 'minimally invasive edit'
+  to a prompt artifact, or 'tighten this prompt'.
 ---
 
 # structure-prompt

package/skills/team-advisor/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: team-advisor
+description: >-
+  Spawn one warm session-advisor at the strongest reachable tier and consult
+  it before big decisions, completion, commits, or when stuck. Triggers:
+  'team-advisor', 'team advisor', 'second opinion', 'advisor', 'consult',
+  'verify', 'validate', 'commit', 'push'.
+---
+
+# Team Advisor
+
+## Principle
+
+One warm, addressable advisor available at the strongest model tier the session can reach. The session sends concise briefs when a decision benefits from a second opinion: before acting on a plan, at completion, before commits, when stuck, when reconsidering the approach, or when an agent deems it necessary and beneficial to the user's goals.
+
+## Follow the shared protocol
+
+**Detect the host profile first** (Host profiles in
+[`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
+— e.g. `ADVISOR_HOST_PROFILE` or `GROK_BUILD`). Do not start a model-floor
+walk until the host is known.
+
+This session is the shared advisor's sole consumer, so its model floor is
+simply this session's own tier — no routing table to take a max against.
+
+**Claude host:** follow the shared protocol for the model-floor walk, the
+warm-up spawn and charter, the consult format and cadence, drift-respawn, and
+the CLI fallback — using `team-advisor-agent` as the name and this session as
+the only consumer (skip the "who you are and your assignment" opener in each
+consult; a single-consumer session doesn't need it).
+
+**Grok host:** use the self-as-advisor path in the shared protocol: this
+session answers ENDORSE / CORRECTION / PLAN / STOP itself. Do not spawn a
+Claude `session-advisor` subagent and do not walk the Claude multi-tier
+ladder.
+
+## Constraints
+
+- One `team-advisor-agent` per session, owned by this session for its whole
+  lifecycle (spawn, drift-respawn, shutdown) — see
+  [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md).
+- Never spawn the warm agent, or its CLI fallback, at a tier below this
+  session's own tier.
+- The warm agent (or its CLI equivalent) only answers. It never edits a
+  file, never runs a build or test, and never posts anything on the
+  session's behalf.
+
+## File Index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Pointer to the shared advisor protocol; this session's consumer-specific wiring and constraints. |
+
+## Folder Map
+
+- `SKILL.md` — complete team-advisor workflow instructions.

package/skills/test_markdown_link_integrity.py

@@ -1,9 +1,10 @@
-"""Link-integrity check for the skills tree and the shared pr-loop docs.
+"""Link-integrity check for the skills tree and shared protocol docs.
 
-Walks every markdown file under ``skills/`` and ``_shared/pr-loop/`` and
-resolves each relative markdown link target against the linking file's
-directory. A link whose target file or directory does not exist on disk is
-reported with its source file and line number, and the test fails.
+Walks every markdown file under ``skills/``, ``_shared/pr-loop/``, and
+``_shared/advisor/`` and resolves each relative markdown link target against
+the linking file's directory. A link whose target file or directory does not
+exist on disk is reported with its source file and line number, and the test
+fails.
 """
 
 from __future__ import annotations
@@ -14,6 +15,7 @@ from pathlib import Path
 
 SKILLS_ROOT = Path(__file__).parent
 SHARED_PR_LOOP_ROOT = SKILLS_ROOT.parent / "_shared" / "pr-loop"
+SHARED_ADVISOR_ROOT = SKILLS_ROOT.parent / "_shared" / "advisor"
 
 MARKDOWN_LINK_PATTERN = re.compile(r"\]\(([^)\s]+)\)")
 FENCE_MARKER = "```"
@@ -34,10 +36,12 @@ def _iter_markdown_files() -> list[Path]:
     """List every markdown file the integrity check covers.
 
     Returns:
-        All ``.md`` files under the skills tree and the shared pr-loop tree.
+        All ``.md`` files under the skills tree, the shared pr-loop tree, and
+        the shared advisor tree.
     """
     all_markdown_files = sorted(SKILLS_ROOT.rglob("*.md"))
     all_markdown_files.extend(sorted(SHARED_PR_LOOP_ROOT.rglob("*.md")))
+    all_markdown_files.extend(sorted(SHARED_ADVISOR_ROOT.rglob("*.md")))
     return all_markdown_files
 
 

package/skills/update/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: update
-description: Fast-forwards a local git repository's main branch to a remote's main, after confirming both the local repo path and the source remote through AskUserQuestion. Fetches the chosen remote, checks that the move is a true fast-forward (never a force, never a merge commit), and updates main whether or not main is the checked-out branch. When main is not the checked-out branch, it then offers to switch the checkout to main so the update reaches the files on disk. Use when the user says "/update", "update main", "fast-forward main", "sync main from origin", "pull latest main into <path>", or "bring main up to date". Triggers on "/update", "update main", "fast-forward main", "sync main".
+description: >-
+  Fast-forwards a local repository's main branch to a remote's main after
+  confirming the repo path and source remote through AskUserQuestion. Use when
+  the user says '/update', 'update main', 'fast-forward main', 'sync main from
+  origin', 'pull latest main into <path>', or 'bring main up to date'.
 ---
 
 # update

package/skills/usage-pause/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: usage-pause
-description: Waits out the account's 5-hour usage window in ScheduleWakeup stages that keep every agent context warm. Resolves the window's reset time and remaining headroom by probing the OAuth usage endpoint, or takes a manual override ('/usage-pause 10:20pm', '/usage-pause 74m'). Warns and stops when the weekly limit is near its cap. Each wakeup pings live and idle-warm agents with a one-line no-new-work checkpoint and records finished results; the final wakeup restores the crons the skill cancelled at pause time. Triggers: '/usage-pause', 'pause until the usage window resets', 'wait out the usage limit', 'usage limit pause'.
+description: >-
+  Waits out the account's 5-hour usage window in ScheduleWakeup stages that keep
+  every agent context warm. Accepts a manual override like '/usage-pause
+  10:20pm' or '/usage-pause 74m'. Triggers: '/usage-pause', 'pause until the
+  usage window resets', 'wait out the usage limit', 'usage limit pause'.
 argument-hint: "[reset time like 10:20pm | duration like 74m]"
 ---
 
@@ -39,16 +43,21 @@ On exit 2 the script prints `{"error": ...}`. Ask the user for a manual reset ti
 
 ### Probe mechanism
 
-The resolver reads the Claude Code CLI's OAuth access token from `~/.claude/.credentials.json` (`claudeAiOauth.accessToken`, honored only while its `expiresAt` sits in the future) and sends `GET https://api.anthropic.com/api/oauth/usage` with `Authorization: Bearer <token>` and `anthropic-beta: oauth-2025-04-20`. This is the same endpoint the interactive `/usage` panel reads. The response carries a `five_hour` bucket and a `seven_day` bucket, each with `utilization` (percent spent) and `resets_at`.
+The resolver gets a bearer token from one of two sources and sends `GET https://api.anthropic.com/api/oauth/usage` with `Authorization: Bearer <token>` and `anthropic-beta: oauth-2025-04-20`. This is the same endpoint the interactive `/usage` panel reads. The response carries a `five_hour` bucket and a `seven_day` bucket, each with `utilization` (percent spent) and `resets_at`.
 
-Fallbacks, in order: an expired or unreadable stored token, a failed request, or a response with no readable `five_hour` reset time all end in exit 2 — the manual-override ask above. The manual path works with no probe at all, so the skill functions even when the credential file is stale.
+Token sources, in order:
+
+- The Claude Code CLI's OAuth access token in `~/.claude/.credentials.json` (`claudeAiOauth.accessToken`, honored only while its `expiresAt` sits in the future).
+- The session ingress token in the file named by the `CLAUDE_SESSION_INGRESS_TOKEN_FILE` environment variable, read when the credential file token is unavailable. Claude Code cloud sessions set this variable and omit the credential file.
+
+Fallbacks, in order: no usable token from either source, a failed request, or a response with no readable `five_hour` reset time all end in exit 2 — the manual-override ask above. The manual path works with no probe at all, so the skill functions even when both token sources are stale.
 
 Why this probe and not the others:
 
 - The interactive `/usage` panel shows the same data but has no scriptable output.
 - `claude -p --output-format json` spends usage to answer and its metadata reports per-call token counts, not the account window clock.
 - `anthropic-ratelimit-*` response headers cover API-key Messages traffic, not the subscription session window, and reading them also costs a request.
-- Refreshing the OAuth token from a script is out of scope: token rotation would desync the refresh token the CLI has on disk and log the CLI out. The resolver only ever reads the credential file.
+- Refreshing the OAuth token from a script is out of scope: token rotation would desync the refresh token the CLI has on disk and log the CLI out. The resolver only ever reads its token sources.
 
 ## Weekly limit guard
 
@@ -101,7 +110,7 @@ Fill each `<slot>` at schedule time: `<remaining_stage_durations>` is the tail o
 | `SKILL.md` | This flow: resolve, weekly guard, stage chain, templates |
 | `scripts/resolve_usage_window.py` | The window resolver and stage planner CLI |
 | `scripts/test_resolve_usage_window.py` | Behavioral tests for parsing, staging, token reading, extraction, CLI |
-| `scripts/usage_pause_constants/resolve_usage_window_constants.py` | Endpoint, credential keys, stage sizing, thresholds, result keys |
+| `scripts/usage_pause_constants/resolve_usage_window_constants.py` | Endpoint, credential keys, the session ingress token env var, stage sizing, thresholds, result keys |
 
 ## Gotchas