@sentry/junior-github 0.183.0 → 0.185.0

package/dist/testing.js

@@ -1,6 +1,6 @@
 import {
   normalizeGitHubResourceEvents
-} from "./chunk-KXAUXJ3Q.js";
+} from "./chunk-QWTU33O7.js";
 export {
   normalizeGitHubResourceEvents
 };

package/dist/tools/footer.d.ts

@@ -1,9 +1,9 @@
 export declare const GITHUB_SESSION_FOOTER_START = "<!-- junior-session-footer:start -->";
 export declare const GITHUB_SESSION_FOOTER_END = "<!-- junior-session-footer:end -->";
 export declare function sentryConversationUrl(conversationId: string): string | undefined;
-/** Build the Junior session footer, preferring a host-provided dashboard link. */
+/** Build the conversation session footer, preferring a host-provided dashboard link. */
 export declare function githubConversationFooter(conversationId: string, dashboardUrl?: string): string | undefined;
-/** Read opaque native conversation ids from Junior-owned GitHub footers. */
+/** Read opaque native conversation ids from runtime-owned GitHub footers. */
 export declare function githubConversationIds(body: string | null | undefined): string[];
 /** Read same- and cross-repository issue references from a pull request body. */
 export declare function githubLinkedIssues(body: string | null | undefined, repositoryFullName: string): {
@@ -11,7 +11,7 @@ export declare function githubLinkedIssues(body: string | null | undefined, repo
     repositoryFullName: string;
 }[];
 /**
- * Append (or replace an existing) Junior session footer to a GitHub body string.
+ * Append (or replace an existing) conversation session footer to a GitHub body string.
  * Without a dashboard or Sentry link, returns the body unchanged (existing footer stripped).
  */
 export declare function appendGitHubFooter(body: string, conversationId: string, dashboardUrl?: string): string;

package/dist/tools/resolve-pull-request-review-thread.d.ts

@@ -1,5 +1,5 @@
 import { type PluginEgress } from "@sentry/junior-plugin-api";
-/** Resolve one review thread after GitHub proves it belongs to a Junior-authored PR. */
+/** Resolve one review thread after GitHub proves it belongs to a bot-authored PR. */
 export declare function createGitHubResolvePullRequestReviewThreadTool(ctx: {
     egress: PluginEgress;
 }, botEmail: string | undefined): import("@sentry/junior-plugin-api").PluginToolDefinition<{

package/dist/tools/update-issue.d.ts

@@ -1,5 +1,5 @@
 import { type Identity, type User, type Actor, type PluginLogger, type PluginEgress } from "@sentry/junior-plugin-api";
-/** Update mutable issue metadata while preserving Junior-owned body attribution. */
+/** Update mutable issue metadata while preserving runtime-owned body attribution. */
 export declare function createGitHubUpdateIssueTool(ctx: {
     actor?: Actor;
     conversationId?: string;

package/dist/tools/update-pull-request.d.ts

@@ -1,5 +1,5 @@
 import { type Identity, type User, type Actor, type PluginLogger, type PluginEgress } from "@sentry/junior-plugin-api";
-/** Update mutable PR metadata while preserving Junior-owned body attribution. */
+/** Update mutable PR metadata while preserving runtime-owned body attribution. */
 export declare function createGitHubUpdatePullRequestTool(ctx: {
     actor?: Actor;
     conversationId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-github",
-  "version": "0.183.0",
+  "version": "0.185.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -31,7 +31,7 @@
     "@sinclair/typebox": "^0.34.49",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@sentry/junior-plugin-api": "0.183.0"
+    "@sentry/junior-plugin-api": "0.185.0"
   },
   "devDependencies": {
     "@oxlint/plugins": "1.79.0",

package/skills/github-code/SKILL.md

@@ -5,80 +5,34 @@ description: Work with GitHub repositories, source code, branches, commits, pull
 
 # GitHub Code Operations
 
-Use `git` and `gh` for repository work. Use `github_createPullRequest`, not `gh pr create`, for new PRs. Use `github_updatePullRequest`, not raw `gh api`/`gh pr edit`, when changing PR title, body, base, or open/closed state. Use `github_resolvePullRequestReviewThread`, not raw `gh api graphql` `resolveReviewThread`, when resolving review threads on Junior-authored PRs.
+Use `git` and `gh` for repository work.
 
-## References
+| Action | Tool / command |
+| --- | --- |
+| Create PR | `github_createPullRequest` (not `gh pr create`) |
+| Update PR title/body/base/state | `github_updatePullRequest` (not raw PATCH / `gh pr edit`) |
+| Resolve review thread | `github_resolvePullRequestReviewThread` (not raw GraphQL) |
+| Clone missing repo | `github_cloneRepository`; on Workspace match error use `switchWorkspace` |
 
-| Open when you need                     | Read                                                                                   |
-| -------------------------------------- | -------------------------------------------------------------------------------------- |
-| Command syntax, permissions, config    | [references/api-surface.md](references/api-surface.md)                                 |
-| Failed commands or permission recovery | [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md) |
+## Open when needed
 
-## Non-negotiable rules
+| Need | Read |
+| --- | --- |
+| Commands, permissions, allowlist | [references/api-surface.md](references/api-surface.md) |
+| Edit → verify → PR packaging | [references/workflow.md](references/workflow.md) |
+| Failed command or permission recovery | [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md) |
 
-- Resolve the repo from the explicit request, then `github.repo`. Run `jr-rpc config get github.repo` standalone.
+## Always
+
+- Resolve repo from the request, then `github.repo`. Run `jr-rpc config get github.repo` standalone.
 - Keep `--repo owner/repo` explicit on `gh`; use `git -C PATH` for local repos.
-- Read applicable `AGENTS.md` files before editing. Narrower repo/task instructions win.
-- Preserve unrelated work. Never force-push, delete refs, or perform destructive merges.
+- Read applicable `AGENTS.md` before editing. Narrower repo/task instructions win.
+- Preserve unrelated work. Never force-push, delete refs, or do destructive merges.
 - Base conclusions on repository evidence. Do not claim a check ran unless it did.
-- For Junior-owned pull requests, push the branch before creating the PR. The runtime supplies repository-scoped GitHub App credentials for both; try the operations before requesting remediation and never ask for a user token.
-- Use `github_cloneRepository` instead of shelling out to `git clone` when a repository is not already available in the sandbox.
-- If `github_cloneRepository` returns a tool input error about matching Workspaces, call `switchWorkspace`. The checkout is already present after a successful switch. Pass `allowAdHoc=true` only for an intentional ad-hoc checkout.
-- A tool-routing denial requires the named tool; only an upstream denial justifies permission remediation.
-- Stop for ambiguous targets, missing access, destructive operations, or unresolved upstream permission failures.
-
-## Workflow
-
-### 1. Resolve and inspect
-
-Identify the repo, checkout, default/current branches, worktree state, repo instructions, package manager, and relevant checks. Prefer an existing checkout or matching Workspace; otherwise clone shallowly. If clone returns a Workspace tool input error, switch Workspace instead of cloning again, or pass `allowAdHoc=true`.
-
-A shallow clone is for fast inspection, not history rewriting. Before rebasing, merge-base analysis, blame/history work, or comparing against a base absent locally, fetch the needed refs and deepen incrementally. Use `--unshallow` only when bounded deepening is insufficient. Never use a force push to compensate for incomplete history.
-
-For edits, choose the smallest credible validation path before changing files. Capture a baseline when a failure may be pre-existing.
-
-### 2. Investigate
-
-Establish where the behavior lives, current versus requested behavior, root cause or gap, and the smallest proof of correctness. Read linked issues, PRs, specs, and failing output when provided. For pull requests, inspect conversation comments, inline review comments, reviews, the diff, and checks. If the request is investigation-only, report evidence without editing.
-
-### 3. Edit
-
-Make the smallest coherent change. Follow local patterns and avoid speculative cleanup. After a failed attempt, re-check the root cause before patching again.
-
-Before running repo checks, ensure project dependencies are available:
-
-1. Detect the package manager and lockfile from repo evidence.
-2. If dependencies are missing or the check reports missing packages, run the repo-native frozen/immutable install (`pnpm install --frozen-lockfile`, `npm ci`, `yarn install --immutable`, `bun install --frozen-lockfile`, or the documented equivalent).
-3. Do not regenerate or modify a lockfile merely to make verification run. If the locked install fails, report the exact failure unless dependency changes are part of the task.
-
-Do not install or repair the GitHub plugin runtime itself; that is manifest-owned setup.
-
-### 4. Verify and review
-
-Run targeted changed-file/package checks before broad suites. Separate regressions from baseline failures. For instruction-only changes, run available structural checks and perform a content-consistency review.
-
-### 5. Package every completed edit
-
-Unless the user explicitly says not to create a PR, every completed repository edit must end in a pushed branch and PR. Default to draft; honor an explicit user or repo instruction to open it ready for review. Do not stop at local changes or a commit.
-
-1. Reuse the current non-default branch or create a focused branch.
-2. Commit using repo conventions; otherwise use `<type>(<scope>): <Subject>` in imperative present tense, with no agent branding.
-3. Push explicitly with `git push -u origin BRANCH`.
-4. Resolve the actual default branch.
-5. Reuse and update an existing PR for the branch with `github_updatePullRequest`; otherwise call `github_createPullRequest` with explicit repo, head, base, title, body, and `draft: true` unless the user or repo explicitly requires ready-for-review.
-
-PR titles use the same conventional form as commits: `<type>(<scope>): <Subject>` or `<type>: <Subject>`. Match the current dominant change, not the latest commit or a stale title.
-
-Write the PR body for a reviewer who knows the product but not this change. Use ASD-STE100 English: short sentences, common words, active voice, and one idea per sentence. Avoid dense academic prose and unnecessary jargon.
-
-Explain what this PR changes and why it matters. Add only context the diff cannot show. Keep the body short by default; add structure only when it helps. Omit empty or `N/A` sections, file-by-file narration, copied commit logs, and redundant diff summaries. Do not put `Checks`, `Verification`, `Test plan`, or similar validation sections in the PR body; put local check results only in the final user report.
-
-Treat the current title, body, and commit messages as fallible context. After material follow-up commits, re-check the title and rewrite the body against the current diff with `github_updatePullRequest`. Never include customer data, PII, secrets, or sensitive thread context, especially in public repositories. Resolve requested assignee/reviewer handles from evidence; skip unconfirmed identities.
-
-If PR creation or update is blocked, report the exact failed command/tool call and leave the committed branch intact.
-
-### 6. Follow and report
-
-When PR creation returns a subscribable resource hint, subscribe to suggested review/CI events. Report only actionable feedback addressed, build failures fixed, fully green/ready state, or merge.
+- Push the branch before creating a bot-owned PR. Runtime injects installation credentials; never ask for a user token for bot pushes.
+- Tool-routing denials need the named tool. Only upstream denials justify permission remediation.
+- Stop for ambiguous targets, missing access, destructive ops, or unresolved upstream permission failures.
+- Unless the user opts out, finish completed edits with a pushed branch and PR (draft by default).
+- Report to the user: repo, branch, PR URL/number, local check results, and anything not run.
 
-Return to the user (not the PR body): repo, branch, PR URL/number, local check results, pre-existing failures, and anything not run with the reason.
+Do not install or repair the GitHub plugin runtime from this skill. The plugin manifest owns that.

package/skills/github-code/SPEC.md

@@ -2,44 +2,40 @@
 
 ## Intent
 
-Guide evidence-first GitHub repository work from inspection through a reviewable result without duplicating command and troubleshooting detail in runtime context.
+Guide evidence-first GitHub repository work from inspection through a reviewable result without loading command and packaging detail on every run.
 
 ## Behavioral contract
 
 - Resolve and inspect the repository before acting.
-- Preserve unrelated work and reject destructive Git operations.
-- Treat shallow clones as inspection checkouts; fetch/deepen before history-dependent operations and never force-push around missing ancestry.
-- Install repository dependencies with the detected package manager's locked/frozen mode before verification when dependencies are absent.
-- For every completed repository edit, create or update a pushed PR unless the user explicitly opts out; default new PRs to draft while honoring explicit ready-for-review instructions.
-- Write conventional PR titles that match the current dominant change.
-- Write short reviewer-facing PR bodies in ASD-STE100 English; explain what changed and why, add only context the diff cannot show, omit empty ceremony or fixed templates, and keep Checks/Verification/Test plan style sections out of the PR body (report local checks to the user instead).
-- Treat existing PR metadata and commit messages as fallible context, and refresh the title/body against the current diff after material changes.
-- Report exact validation and permission failures without claiming partial work is complete.
+- Preserve unrelated work; reject destructive Git operations.
+- Treat shallow clones as inspection checkouts; deepen before history work; never force-push around missing ancestry.
+- Install dependencies with the lockfile frozen mode before verification when needed.
+- Finish completed edits with a pushed PR unless the user opts out; default draft.
+- Write conventional PR titles and short plain-English bodies; keep check results out of the PR body.
+- Report exact validation and permission failures.
 
 ## Runtime architecture
 
-- `SKILL.md`: compact workflow and decision rules.
+- `SKILL.md`: always-on rules and reference router.
 - `references/api-surface.md`: command and permission lookup.
+- `references/workflow.md`: edit, verify, and PR packaging.
 - `references/troubleshooting-workarounds.md`: failure recovery.
 
-Do not move provider runtime installation, OAuth, or environment setup into this skill; the GitHub plugin manifest owns those concerns.
+The GitHub plugin manifest owns runtime install, OAuth, and env setup. Do not move those into this skill.
 
-## Trigger expectations
+## Triggers
 
 Should trigger for implementation, source inspection, clone/fetch/branch work, commits, PRs, reviews, CI, and repository credential failures.
 
-Should not trigger for GitHub issue-only operations, non-GitHub ticketing, product telemetry, or general product documentation with no repository task.
+Should not trigger for issue-only ops, non-GitHub ticketing, product telemetry, or docs with no repository task.
 
 ## Validation
 
-After material edits:
-
 1. Run the repository skill validator.
-2. Run formatting or package checks applicable to changed Markdown.
-3. Confirm all referenced files exist.
+2. Confirm all referenced files exist.
+3. Confirm `SKILL.md` stays a router (workflow detail lives in references).
 4. Confirm code-edit completion defaults to a draft PR.
-5. Confirm dependency installation and shallow-history recovery do not permit lockfile mutation or force-push shortcuts.
 
 ## Maintenance
 
-Keep workflow policy in `SKILL.md`; move syntax matrices and failure details to the routed references. Remove duplicated rules rather than restating them across sections.
+Keep always-on policy in `SKILL.md`. Move syntax matrices, packaging steps, and failure tables to routed references. Delete duplicates instead of restating them.

package/skills/github-code/references/api-surface.md

@@ -1,86 +1,56 @@
-# GitHub API Surface — code & pull requests
-
-PR creation uses Junior's `github_createPullRequest` tool. PR title, body, base, and open/closed state updates use `github_updatePullRequest` so Junior keeps requester attribution and the conversation footer. Review-thread resolve uses `github_resolvePullRequestReviewThread` because GitHub exposes only the GraphQL `resolveReviewThread` mutation (no REST endpoint and no first-class `gh pr` subcommand). Other supported mutations use allowlisted REST endpoints through `gh api`; generic GraphQL-backed `gh pr` mutations are not supported.
-
-## Repo scoping
-
-When the user omits `owner/repo`, resolve `github.repo` first with `jr-rpc config get github.repo`, then pass the resolved repo explicitly on the actual `gh` or `git` command.
-Run `jr-rpc config get github.repo` as a standalone bash command. Never chain it with `cd`, `&&`, pipes, or a provider command.
-Treat explicit repo flags as command-targeting safety rails, not as a credential-scoping mechanism.
-
-## GitHub App permission guidance
-
-| Permission capability        | Commands                                                                             |
-| ---------------------------- | ------------------------------------------------------------------------------------ |
-| `github.actions.read`        | `gh run list`, `gh run view`, `gh run watch`, `gh workflow list`, `gh workflow view` |
-| `github.actions.write`       | `gh workflow run`, `gh run rerun`, `gh run cancel`                                   |
-| `github.contents.read`       | `gh repo clone`, `git fetch`                                                         |
-| `github.contents.write`      | Git smart-HTTP `git push` only                                                       |
-| `github.workflows.write`     | Workflow-file changes carried by Git smart-HTTP push                                 |
-| `github.pull-requests.read`  | `gh pr view`, `gh pr list`, `gh pr diff`, `gh pr checks`                             |
-| `github.pull-requests.write` | Typed PR creation and allowlisted REST PR lifecycle endpoints                        |
-
-## Command matrix
-
-| Operation                          | Command                                                                                                                  |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| Clone repository (default shallow) | `gh repo clone owner/repo [DIRECTORY] -- --depth=1`                                                                      |
-| Fetch bounded base history         | `git -C DIRECTORY fetch --depth=N origin BASE:refs/remotes/origin/BASE`                                                  |
-| Deepen base history                | `git -C DIRECTORY fetch --deepen=N origin BASE:refs/remotes/origin/BASE`                                                 |
-| Convert shallow clone to full      | `git -C DIRECTORY fetch --unshallow origin`                                                                              |
-| Check shallow state                | `git -C DIRECTORY rev-parse --is-shallow-repository`                                                                     |
-| Check branch                       | `git -C DIRECTORY branch --show-current`                                                                                 |
-| Check worktree state               | `git -C DIRECTORY status --short --branch`                                                                               |
-| View commit log against base       | `git -C DIRECTORY log origin/BASE..HEAD --oneline`                                                                       |
-| Diff against base                  | `git -C DIRECTORY diff origin/BASE...HEAD`                                                                               |
-| Resolve default branch             | `gh repo view owner/repo --json defaultBranchRef --jq .defaultBranchRef.name`                                            |
-| Create branch                      | `git -C DIRECTORY checkout -b BRANCH`                                                                                    |
-| Stage and commit                   | `git -C DIRECTORY add -A && git -C DIRECTORY commit -m "message"`                                                        |
-| Push branch before PR creation     | `git -C DIRECTORY push -u origin BRANCH`                                                                                 |
-| Dispatch workflow                  | `gh workflow run WORKFLOW --repo owner/repo --ref REF [-f key=value]`                                                    |
-| Rerun workflow run                 | `gh run rerun RUN_ID -R owner/repo [--failed]`                                                                          |
-| Rerun workflow job                 | `gh run rerun --job JOB_ID -R owner/repo`                                                                               |
-| Cancel workflow run                | `gh run cancel RUN_ID -R owner/repo`                                                                                     |
-| Create pull request (draft)        | `github_createPullRequest({ repo: "owner/repo", head: "BRANCH", base: "BASE", title: "...", body: "...", draft: true })` |
-| Update pull request                | `github_updatePullRequest({ repo: "owner/repo", number: NUMBER, title?: "...", body?: "...", base?: "BASE", state?: "open" \| "closed" })` |
-| Mark ready for review              | `gh api repos/owner/repo/pulls/NUMBER/ready_for_review --method POST`                                                    |
-| Request reviewers                  | `gh api repos/owner/repo/pulls/NUMBER/requested_reviewers --method POST --input reviewers.json`                          |
-| Remove requested reviewers         | `gh api repos/owner/repo/pulls/NUMBER/requested_reviewers --method DELETE --input reviewers.json`                        |
-| Close pull request                 | `github_updatePullRequest({ repo: "owner/repo", number: NUMBER, state: "closed" })`                                      |
-| Submit pull request review         | `gh api repos/owner/repo/pulls/NUMBER/reviews --method POST --input review.json`                                         |
-| Post inline review comment         | `gh api repos/owner/repo/pulls/NUMBER/comments --method POST --input comment.json`                                       |
-| Reply to inline review comment     | `gh api repos/owner/repo/pulls/NUMBER/comments/COMMENT_ID/replies --method POST --input reply.json`                      |
-| Resolve review thread              | `github_resolvePullRequestReviewThread({ repo: "owner/repo", threadId: "PRRT_..." })` (GraphQL `resolveReviewThread` substitute; Junior-authored PRs only) |
-| View pull request                  | `gh pr view NUMBER --repo owner/repo [--json ...]`                                                                       |
-| List pull requests                 | `gh pr list --repo owner/repo [--state open \| closed \| merged]`                                                        |
-| Diff pull request                  | `gh pr diff NUMBER --repo owner/repo`                                                                                    |
-| Check pull request status          | `gh pr checks NUMBER --repo owner/repo`                                                                                  |
-| View PR review comments            | `gh api repos/{owner}/{repo}/pulls/{number}/comments`                                                                    |
-| View PR reviews                    | `gh api repos/{owner}/{repo}/pulls/{number}/reviews`                                                                     |
-| List workflow runs                 | `gh run list -R owner/repo --workflow WORKFLOW [--limit N] [--json ...]`                                                 |
-| View workflow run                  | `gh run view RUN_ID -R owner/repo [--json ...] [--log-failed]`                                                           |
-| Watch workflow run                 | `gh run watch RUN_ID -R owner/repo --exit-status`                                                                        |
-
-## Config helpers
-
-```bash
-jr-rpc config get github.repo
-jr-rpc config set github.repo owner/repo
-```
-
-## Behavior notes
-
-- Prefer `--json` output for machine-readable parsing where available.
-- Pass extra `git clone` flags after `--` (e.g. `gh repo clone owner/repo -- --depth=1`).
-- A local `git commit` does not call GitHub. Pushing that commit uses Junior's repository-scoped installation credential and requires `github.contents.write` on the target repo.
-- If the commit changes workflow files under `.github/workflows`, the App installation needs Workflows write in addition to Contents write.
-- Before rebasing, merge-base analysis, blame/history inspection, or a base comparison, check whether the repository is shallow. Fetch a bounded depth of the base into `refs/remotes/origin/BASE`, deepen incrementally until the needed ancestry is present, and compare against `origin/BASE`; use `--unshallow` only when bounded deepening is insufficient. Never force-push to work around missing ancestry.
-- Before `github_createPullRequest`, push the head branch explicitly and resolve the target repo's default branch for `base`. That push requires GitHub write access to the remote.
-- Use `github_updatePullRequest` for title, body, base, or open/closed state changes. Do not raw-`PATCH` `/repos/.../pulls/NUMBER`; that path is denied so Junior can keep the conversation footer.
-- Merge, fork creation, REST contents/Git database writes, and repository administration are outside the current write allowlist.
-- Pull request reviews and inline review comments use the same repository-scoped `installation-write` credential as other bot-owned PR writes, so they post as Junior even on headless turns. Merge remains denied.
-- Resolve review threads with `github_resolvePullRequestReviewThread`. That tool is the Junior equivalent of `gh api graphql` `resolveReviewThread`; raw GraphQL mutations stay denied, and the tool only succeeds on Junior-authored PRs.
-- If the explicit `git push` fails with 401/403 or another access/permission error, verify the repo context and retry once. If it still fails, load troubleshooting guidance and report the exact command failure.
-- PR comments, labels, and assignees use GitHub's issue endpoints; use the `github-issues` REST guidance for those operations. All allowlisted bot writes share the same repository-scoped `installation-write` credential.
-- To embed a local image in a GitHub issue, pull request, review, or comment, call `publishImage` first. That tool returns a durable public URL. The published image is public to anyone on the internet who has the URL. Embed the URL with normal GitHub Markdown. Do not use private Slack file links or conversation attachment URLs.
-- Return actionable errors for access, permission, not-found, and validation failures.
+# GitHub API surface — code and pull requests
+
+PR create/update and review-thread resolve use the tools named in `SKILL.md`. Other supported mutations use allowlisted REST through `gh api`. Generic GraphQL-backed `gh pr` mutations are not supported.
+
+## Repo targeting
+
+When the user omits `owner/repo`, resolve with standalone `jr-rpc config get github.repo`, then pass `--repo owner/repo` on the next `gh`/`git` command. Explicit repo flags target the command; they are not a credential scope.
+
+## Permissions
+
+| Capability | Commands |
+| --- | --- |
+| `github.actions.read` | `gh run list`, `gh run view`, `gh run watch`, `gh workflow list`, `gh workflow view` |
+| `github.actions.write` | `gh workflow run`, `gh run rerun`, `gh run cancel` |
+| `github.contents.read` | `gh repo clone`, `git fetch` |
+| `github.contents.write` | Git smart-HTTP `git push` only |
+| `github.workflows.write` | Workflow-file changes on push |
+| `github.pull-requests.read` | `gh pr view`, `gh pr list`, `gh pr diff`, `gh pr checks` |
+| `github.pull-requests.write` | Typed PR create and allowlisted REST PR lifecycle |
+
+## Commands
+
+| Operation | Command |
+| --- | --- |
+| Clone (default shallow) | `gh repo clone owner/repo [DIR] -- --depth=1` |
+| Fetch bounded base | `git -C DIR fetch --depth=N origin BASE:refs/remotes/origin/BASE` |
+| Deepen base | `git -C DIR fetch --deepen=N origin BASE:refs/remotes/origin/BASE` |
+| Unshallow | `git -C DIR fetch --unshallow origin` |
+| Shallow check | `git -C DIR rev-parse --is-shallow-repository` |
+| Branch / status | `git -C DIR branch --show-current` / `git -C DIR status --short --branch` |
+| Log / diff vs base | `git -C DIR log origin/BASE..HEAD --oneline` / `git -C DIR diff origin/BASE...HEAD` |
+| Default branch | `gh repo view owner/repo --json defaultBranchRef --jq .defaultBranchRef.name` |
+| Create branch | `git -C DIR checkout -b BRANCH` |
+| Commit | `git -C DIR add -A && git -C DIR commit -m "message"` |
+| Push | `git -C DIR push -u origin BRANCH` |
+| Workflow dispatch | `gh workflow run WORKFLOW --repo owner/repo --ref REF [-f key=value]` |
+| Rerun / cancel | `gh run rerun RUN_ID -R owner/repo [--failed]` / `gh run cancel RUN_ID -R owner/repo` |
+| Ready for review | `gh api repos/owner/repo/pulls/NUMBER/ready_for_review --method POST` |
+| Request reviewers | `gh api repos/owner/repo/pulls/NUMBER/requested_reviewers --method POST --input reviewers.json` |
+| Submit review | `gh api repos/owner/repo/pulls/NUMBER/reviews --method POST --input review.json` |
+| Inline review comment | `gh api repos/owner/repo/pulls/NUMBER/comments --method POST --input comment.json` |
+| View PR / checks | `gh pr view NUMBER --repo owner/repo` / `gh pr checks NUMBER --repo owner/repo` |
+| Diff PR | `gh pr diff NUMBER --repo owner/repo` |
+| List runs | `gh run list -R owner/repo --workflow WORKFLOW` |
+| View / watch run | `gh run view RUN_ID -R owner/repo` / `gh run watch RUN_ID -R owner/repo --exit-status` |
+
+## Notes
+
+- Prefer `--json` where available. Pass clone flags after `--`.
+- Local commit does not call GitHub. Push uses installation credentials (`contents.write`; workflow files also need `workflows.write`).
+- Before history-dependent git work, deepen shallow clones; never force-push around missing ancestry.
+- Push head and resolve default `base` before `github_createPullRequest`.
+- Denied: merge, forks, REST contents/Git database writes, repo admin, raw PR PATCH, raw GraphQL mutations.
+- Reviews and inline comments post as the App bot via `installation-write`.
+- PR comments/labels/assignees use issue endpoints; load `github-issues` for those.
+- Embed local images with `publishImage` first (public URL). Do not use private Slack file links.

package/skills/github-code/references/troubleshooting-workarounds.md

@@ -1,37 +1,33 @@
-# GitHub CLI Troubleshooting — code & pull requests
+# GitHub CLI troubleshooting — code and pull requests
 
-Use this table to recover quickly while keeping operations deterministic.
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `unknown command` from `gh` | Runtime `gh` missing or too old | Report GitHub plugin runtime dependency unavailable |
+| `unknown flag: --depth` on clone | Clone flags before `--` | `gh repo clone owner/repo -- --depth=1` |
+| Missing `--repo` | No explicit target | Resolve `github.repo`, pass `--repo owner/repo` |
+| Wrong repo authenticated | Stale default | Pass `--repo owner/repo` or update `github.repo` |
+| GraphQL: could not resolve repository | Bad slug or no access | Validate `owner/repo` and App install |
+| 401 Unauthorized | Credential rejected | Confirm target; distinguish user OAuth vs installation setup |
+| `junior-auth-required` `user-write` | Missing/stale user OAuth | Follow private OAuth prompt; never ask for pasted tokens |
+| `git push` 401/403 | Install scope, remote, or permissions | Verify remote/repo, retry once, then report install scope |
+| `permission_denied` `source: "upstream"` | GitHub 403 after inject | Not a local runtime block; use grant/account/SSO fields |
+| 403 without upstream `permission_denied` | Local policy denial | Read body; follow required-tool guidance |
+| `Token scopes: none` on `gh auth status` | Normal for App user tokens | Use App permissions / accepted-permissions headers |
+| `github_createPullRequest` 401/403 | Install/repo lacks write | Report install scope; do not fall back to user OAuth |
+| Create PR 422 on `head` | Branch not pushed | Push branch; retry with explicit head/base |
+| Create/update PR 422 on `base` | Base missing | Resolve default branch; retry |
+| 403 names `github_updatePullRequest` | Raw PR PATCH blocked | Use `github_updatePullRequest` |
+| GraphQL mutations not enabled | Raw resolve blocked | Use `github_resolvePullRequestReviewThread` (bot-authored PRs only) |
+| Missing blame/old history | Shallow clone | Deepen needed refs; `--unshallow` only if required |
+| Odd ancestry / rebase fails | Base ref missing locally | Fetch `BASE:refs/remotes/origin/BASE`, deepen, use `origin/BASE` |
+| Missing deps in tests | Not installed | Frozen/immutable install for the lockfile; do not rewrite lockfile |
+| Frozen install fails | Drift or registry | Report exact failure |
+| `dnf install gh failed` | Plugin bootstrap | Report runtime bootstrap failure; do not repair from skill |
 
-| Symptom                                                                            | Likely cause                                                                        | Fix                                                                                                                                                                                                    |
-| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `unknown command "..."` from `gh`                                                  | CLI version too old or wrong binary in the plugin runtime.                          | Verify `gh --version`; if it is unavailable or too old, report that the GitHub plugin runtime dependency is not available.                                                                             |
-| `unknown flag: --depth` from `gh repo clone`                                       | `git clone` flags were passed before `--`.                                          | Pass clone flags after `--`, for example `gh repo clone owner/repo -- --depth=1`.                                                                                                                      |
-| `Missing required option --repo`                                                   | Repo not passed and no default was resolved.                                        | Resolve with `jr-rpc config get github.repo`; pass `--repo owner/repo` explicitly when missing.                                                                                                        |
-| Command affects or authenticates against the wrong repo                            | Stale `github.repo` default or authenticated command missing explicit repo.         | Pass `--repo owner/repo` for the target repository, or update `github.repo` before retrying.                                                                                                           |
-| `GraphQL: Could not resolve to a Repository`                                       | Repo slug is wrong or inaccessible.                                                 | Validate `owner/repo` and confirm app installation on target repository.                                                                                                                               |
-| 401 Unauthorized                                                                   | Issued GitHub credentials were rejected upstream.                                   | Verify the target repo, then use the grant/auth signal to distinguish stale user OAuth from app installation or host env setup.                                                                        |
-| `junior-auth-required provider=github grant=user-write`                            | User-to-server OAuth is missing or stale for a human-identity operation.            | Follow the private OAuth prompt; do not ask the user to paste or manage tokens manually.                                                                                                               |
-| `git push` fails with 401/403 or auth/permission output                            | Write permission is missing, app installation is too narrow, or remote is wrong.    | Verify the remote and repo context, retry once, then confirm app permissions and installation scope if it still fails.                                                                                 |
-| Bash result includes `permission_denied` with `source: "upstream"`                 | GitHub returned 403 after Junior injected the named grant.                          | Do not call this a Junior runtime block. Use the message, connected account, upstream target, grant requirements, accepted-permissions, and SSO fields to explain the GitHub denial.                   |
-| 403 without `permission_denied` where `source: "upstream"`                         | Junior may have rejected an unsupported route before contacting GitHub.             | Read the response body. Follow any required-tool instruction; do not ask for GitHub permissions unless the failure is confirmed upstream.                                                              |
-| `gh auth status` shows `Token scopes: none`                                        | Expected for GitHub App user-to-server tokens.                                      | Do not treat this as read-only proof. Use the failed command, `permission_denied.acceptedPermissions`, and GitHub App permissions instead.                                                             |
-| `github_createPullRequest` returns upstream 401/403                                | The App installation or target repository does not permit the operation.            | Use the structured upstream denial to verify installation scope and accepted permissions; do not request user OAuth for this bot-owned operation.                                                      |
-| `github_createPullRequest` returns 422 for `head`                                  | The head branch was not pushed or the explicit head ref is wrong.                   | Push the branch, then retry with explicit `repo`, `head`, and `base` values.                                                                                                                           |
-| `github_createPullRequest` fails with 422 validation on `base`                     | The `base` branch does not exist in the target repo.                                | Resolve the default branch with `gh repo view owner/repo --json defaultBranchRef --jq .defaultBranchRef.name`, then retry with that value as `base`.                                                   |
-| `403` names `github_updatePullRequest`                                             | Raw PR title/body/base/state PATCH was blocked so Junior can own the footer.        | Retry with `github_updatePullRequest`; do not use `gh api .../pulls/NUMBER --method PATCH` or `gh pr edit`.                                                                                            |
-| `GraphQL mutations are not enabled` / resolve thread denied                        | Raw `gh api graphql` `resolveReviewThread` is blocked.                              | Retry with `github_resolvePullRequestReviewThread({ repo, threadId })`. Only Junior-authored PRs are allowed.                                                                                          |
-| `github_updatePullRequest` returns upstream 401/403                                | The App installation or target repository does not permit the operation.            | Use the structured upstream denial to verify installation scope and accepted permissions; do not request user OAuth for this bot-owned operation.                                                      |
-| `git blame`, long log history, or old commits are missing after clone              | Repo was cloned shallow by design.                                                  | Fetch the required ref and deepen it incrementally; use `--unshallow` only when bounded deepening is insufficient.                                                                                     |
-| Rebase, merge-base, or `origin/BASE...HEAD` comparison fails or gives odd ancestry | Required ancestry or the remote-tracking base ref is absent from the shallow clone. | Fetch a bounded depth into `BASE:refs/remotes/origin/BASE`, deepen that base ref until the merge base exists, and compare or rebase against `origin/BASE`. Never force-push around incomplete history. |
-| Tests fail because dependencies or executables are missing                         | Repository dependencies were not installed.                                         | Detect the lockfile and run the repo-native frozen/immutable install. Do not rewrite the lockfile unless dependency changes are part of the task.                                                      |
-| Frozen/immutable dependency install fails                                          | Lockfile drift, unavailable registry, incompatible runtime, or environment issue.   | Report the exact install failure. Do not fall back to a lockfile-updating install unless the requested work intentionally changes dependencies.                                                        |
-| `sandbox setup failed (dnf install gh failed ...)`                                 | `gh` package not available from the plugin runtime dependency bootstrap.            | Report the plugin runtime bootstrap failure; do not try to repair package installation from the skill workflow.                                                                                        |
+## Retry rules
 
-## Retry guidance
-
-- Retry once for transient transport failures after verifying repo context.
-- Do not loop retries on repeated 401/403/404 validation errors.
-- Treat missing or stale `user-read`/`user-write` grants as private GitHub App OAuth work. Treat all `installation-*` failures as App permission, installation scope, or host environment setup; they do not fall back to user OAuth.
-- Do not describe `permission_denied` with `source: "upstream"` as Junior blocking the request. It means the egress proxy injected a credential, forwarded the request, and recorded GitHub's upstream 403. Prefer its `account` and `grant.requirements` fields over inference when explaining what to fix.
-- Do not infer permission level from OAuth scopes. GitHub App user tokens report no OAuth scopes; GitHub App permissions and accepted-permissions headers are the useful evidence.
-- For persistent permission problems, return explicit remediation and stop.
+- Retry once for transient transport after verifying repo context.
+- Do not loop on repeated 401/403/404 validation errors.
+- `user-read`/`user-write` gaps → private App OAuth. `installation-*` failures → App permission/install/host setup only.
+- Prefer `permission_denied` structured fields over guessing.
+- Persistent permission problems: report remediation and stop.

package/skills/github-code/references/workflow.md

@@ -0,0 +1,47 @@
+# Edit and PR packaging
+
+Open this when making repository edits, not for read-only inspection.
+
+## Resolve and inspect
+
+1. Identify repo, checkout, branches, worktree, package manager, and relevant checks.
+2. Prefer an existing checkout or matching Workspace; otherwise clone shallowly.
+3. If clone returns a Workspace match error, switch Workspace or pass `allowAdHoc=true`.
+4. Shallow clones are for fast inspection. Before rebase, merge-base, blame, or base comparison, fetch/deepen the needed refs. Never force-push around missing history.
+5. For edits, pick the smallest credible validation path. Capture a baseline when a failure may be pre-existing.
+
+## Investigate
+
+1. Find where the behavior lives, current vs requested, root cause or gap, and the smallest proof.
+2. Read linked issues, PRs, specs, and failing output when provided.
+3. For PRs, inspect conversation, inline comments, reviews, diff, and checks.
+4. Investigation-only requests: report evidence; do not edit.
+
+## Edit
+
+1. Make the smallest coherent change. Follow local patterns. Avoid speculative cleanup.
+2. After a failed attempt, re-check root cause before patching again.
+3. Before repo checks, ensure dependencies with the lockfile-native frozen install. Do not rewrite the lockfile unless dependency changes are part of the task.
+
+## Verify
+
+1. Run targeted changed-file/package checks before broad suites.
+2. Separate regressions from baseline failures.
+3. Instruction-only changes: structural checks plus content review.
+
+## Package
+
+1. Reuse the current non-default branch or create a focused branch.
+2. Commit with repo conventions, else `<type>(<scope>): <Subject>` imperative present, no agent branding.
+3. Push with `git push -u origin BRANCH`.
+4. Resolve the actual default branch.
+5. Update an existing PR for the branch with `github_updatePullRequest`, or create with `github_createPullRequest` (`draft: true` unless ready-for-review is required).
+6. PR title matches the current dominant change, same conventional form as commits.
+7. PR body: short, plain English, what changed and why. Only context the diff cannot show. No empty sections, file lists, commit logs, or Checks/Verification/Test plan blocks. Put local check results in the user report only.
+8. After material follow-up commits, refresh title and body against the current diff.
+9. Never put customer data, PII, secrets, or sensitive thread context in public PR text.
+10. If PR create/update is blocked, report the exact failure and leave the committed branch intact.
+
+## Follow
+
+When PR creation returns a subscribable hint, subscribe to suggested review/CI events. Report only actionable feedback fixed, build failures fixed, green/ready, or merge.

package/skills/github-issues/SKILL.md

@@ -92,8 +92,8 @@ Run [references/issue-quality-checklist.md](references/issue-quality-checklist.m
 
 ### 5. Execute
 
-- Use `github_createIssue` for new issues so Junior owns idempotency and session-link footers.
-- Use `github_updateIssue` for issue title, body, or state changes so Junior preserves requester attribution and the session footer.
+- Use `github_createIssue` for new issues so the runtime owns idempotency and session-link footers.
+- Use `github_updateIssue` for issue title, body, or state changes so the runtime preserves requester attribution and the session footer.
 - Use `gh` commands from [references/api-surface.md](references/api-surface.md) for comments, labels, assignees, and read-only operations.
 - For issue listing or other read-only inspection, prefer `--json` output so empty results still produce deterministic stdout.
 - Check duplicates silently before creating a new issue. Do not mention this check in the final reply unless a duplicate blocks creation.

package/skills/github-issues/references/api-surface.md

@@ -1,6 +1,6 @@
 # GitHub Issue API Surface
 
-Issue creation uses `github_createIssue`. Issue title, body, and state updates use `github_updateIssue` so Junior keeps requester attribution and the conversation footer. Comments, labels, assignees, and reads use allowlisted REST endpoints through `gh api`; generic GraphQL-backed `gh issue` mutations are not supported.
+Issue creation uses `github_createIssue`. Issue title, body, and state updates use `github_updateIssue` so the runtime keeps requester attribution and the conversation footer. Comments, labels, assignees, and reads use allowlisted REST endpoints through `gh api`; generic GraphQL-backed `gh issue` mutations are not supported.
 
 ## Repo scoping
 

package/skills/github-issues/references/troubleshooting-workarounds.md

@@ -10,7 +10,7 @@ Use this table to recover quickly while keeping operations deterministic.
 | `GraphQL: Could not resolve to a Repository`               | Repo slug is wrong or inaccessible.                                         | Validate `owner/repo` and confirm app installation on target repository.                                                                  |
 | 401 Unauthorized                                           | Issued GitHub credentials were rejected upstream.                           | Verify the target repo, then use the grant/auth signal to distinguish stale user OAuth from app installation or host env setup.           |
 | `junior-auth-required provider=github grant=user-write`    | User-to-server OAuth is missing or stale for a human-identity operation.    | Follow the private OAuth prompt; do not ask the user to paste or manage tokens manually.                                                  |
-| 403 without `permission_denied` where `source: "upstream"` | Junior may have rejected an unsupported route before contacting GitHub.     | Read the response body. Follow any required-tool instruction; do not ask for GitHub permissions unless the failure is confirmed upstream. |
+| 403 without `permission_denied` where `source: "upstream"` | The runtime may have rejected an unsupported route before contacting GitHub. | Read the response body. Follow any required-tool instruction; do not ask for GitHub permissions unless the failure is confirmed upstream. |
 | `permission_denied` with `source: "upstream"`              | GitHub rejected the injected installation credential.                       | Verify the target, accepted permissions, and App installation scope; do not request user OAuth for a bot-owned issue operation.           |
 | 404 Not Found                                              | Issue number or repo is wrong.                                              | Validate repo + issue ID with `gh issue view NUMBER --repo owner/repo`.                                                                   |
 | Issue label mutation fails                                 | Wrong REST payload or wrong repo context.                                   | Use the allowlisted issue labels endpoint with an explicit `owner/repo` path and valid JSON input.                                        |