@sentry/junior-github 0.104.1 → 0.105.0

package/SETUP.md

@@ -98,8 +98,8 @@ Use `additionalUserScopes` only when a human-identity integration flow requires
 ## 3) Runtime behavior
 
 - When either GitHub skill is active, authenticated `gh` and `git` commands cause the runtime to inject GitHub credentials automatically for the current turn.
-- The plugin classifies GitHub traffic from the forwarded HTTP request. Reads use `installation-read`, while `GET /user` uses `user-read`. Allowlisted App-owned mutations and Git smart-HTTP pushes share the repository-scoped `installation-write` grant. User-attachment uploads to `uploads.github.com/user-attachments/assets` use `user-write`. Unknown REST writes and GraphQL mutations are denied.
-- `user-read` and the remaining explicitly human `user-write` operations require the actor, or an explicitly delegated user subject, to authorize the GitHub App through the private OAuth flow. Junior-owned issue, pull request, and branch operations do not fall back to user OAuth.
+- The plugin classifies GitHub traffic from the forwarded HTTP request. Reads use `installation-read`, while `GET /user` uses `user-read`. Allowlisted App-owned mutations, Git smart-HTTP pushes, and user-attachment uploads to `uploads.github.com/user-attachments/assets` use repository-scoped `installation-write`. Unknown REST writes and GraphQL mutations are denied.
+- `user-read` and explicitly human `user-write` operations require the actor, or an explicitly delegated user subject, to authorize the GitHub App through the private OAuth flow. Junior-owned issue, pull request, branch, and asset-upload operations do not fall back to user OAuth.
 - Headless resource-event turns use the `resource-event` system actor and may receive the same repository-scoped installation grants. This lets Junior respond to subscribed pull request events by committing and pushing fixes without inheriting a subscriber's OAuth credential.
 - Git commits use Junior as author and committer. Resolvable human run actors are credited once with `Co-Authored-By` trailers.
 - Issued credentials are reused only within the current turn, credential leases are cached by plugin grant and repository lease scope, and upstream 403 permission denials clear the cached lease before the next retry.

package/dist/index.js

@@ -857,7 +857,7 @@ var USER_WRITE_REQUIREMENTS = [
   "requesting GitHub user permission to perform this operation"
 ];
 var GITHUB_CREDENTIAL_DOMAINS = ["api.github.com", "github.com"];
-var GITHUB_USER_CREDENTIAL_DOMAINS = [
+var GITHUB_ASSET_UPLOAD_CREDENTIAL_DOMAINS = [
   ...GITHUB_CREDENTIAL_DOMAINS,
   "uploads.github.com"
 ];
@@ -1318,7 +1318,7 @@ function createCredentialLease(input) {
       ...input.account ? { account: input.account } : {},
       ...input.authorization ? { authorization: input.authorization } : {},
       expiresAt: new Date(input.expiresAtMs).toISOString(),
-      headerTransforms: (input.authorization ? GITHUB_USER_CREDENTIAL_DOMAINS : GITHUB_CREDENTIAL_DOMAINS).map((domain) => ({
+      headerTransforms: (input.domains ?? (input.authorization ? GITHUB_ASSET_UPLOAD_CREDENTIAL_DOMAINS : GITHUB_CREDENTIAL_DOMAINS)).map((domain) => ({
         domain,
         headers: {
           Authorization: authorizationFor(domain, input.token)
@@ -1405,6 +1405,28 @@ function githubRepositoryFromLeaseScope(leaseScope) {
   }
   return { owner: match[1], name: match[2] };
 }
+function githubRepositoryIdFromUploadUrl(upstreamUrl) {
+  const repositoryId = Number(upstreamUrl.searchParams.get("repository_id"));
+  if (!Number.isSafeInteger(repositoryId) || repositoryId <= 0) {
+    throw new EgressPolicyDenied(
+      "GitHub asset upload request is missing a valid repository_id."
+    );
+  }
+  return repositoryId;
+}
+function githubRepositoryIdLeaseScope(repositoryId) {
+  return `repository-id:${repositoryId}`;
+}
+function githubRepositoryIdFromLeaseScope(leaseScope) {
+  const match = /^repository-id:(\d+)$/.exec(leaseScope ?? "");
+  const repositoryId = Number(match?.[1]);
+  if (!Number.isSafeInteger(repositoryId) || repositoryId <= 0) {
+    throw new GitHubPluginSetupError(
+      "GitHub asset upload grant is missing a repository id lease scope."
+    );
+  }
+  return repositoryId;
+}
 async function resolveUserAccount(tokens) {
   const account = await githubRequest("https://api.github.com", "/user", {
     token: tokens.accessToken
@@ -1582,7 +1604,7 @@ async function issueInstallationCredential(options) {
     throw new GitHubPluginSetupError(`Invalid ${options.installationIdEnv}`);
   }
   const appJwt = createAppJwt(appId, options.privateKeyEnv);
-  const body = "repositories" in options ? { repositories: options.repositories } : {
+  const body = "repositories" in options ? { repositories: options.repositories } : "repositoryIds" in options ? { repository_ids: options.repositoryIds } : {
     permissions: "permissions" in options ? options.permissions : await options.loadPermissions({ appJwt, installationId })
   };
   const accessTokenResponse = await githubRequest(
@@ -1600,6 +1622,7 @@ async function issueInstallationCredential(options) {
     Date.now() + MAX_LEASE_MS
   );
   return createCredentialLease({
+    ...options.domains ? { domains: options.domains } : {},
     token: parsedToken.token,
     expiresAtMs
   });
@@ -1918,7 +1941,13 @@ async function githubGrantForEgress(ctx) {
     upstreamUrl
   });
   if (isGitHubAssetUploadRequest(method, upstreamUrl)) {
-    return grantForAccess("write", "github.asset-upload", "user-write");
+    const repositoryId = githubRepositoryIdFromUploadUrl(upstreamUrl);
+    return grantForAccess(
+      "write",
+      "github.asset-upload",
+      "installation-write",
+      githubRepositoryIdLeaseScope(repositoryId)
+    );
   }
   const smartHttpAccess = githubSmartHttpAccess(upstreamUrl);
   if (smartHttpAccess) {
@@ -2109,6 +2138,18 @@ function githubPlugin(options = {}) {
             });
           }
           if (ctx.grant.name === "installation-write") {
+            if (ctx.grant.reason === "github.asset-upload") {
+              const repositoryId = githubRepositoryIdFromLeaseScope(
+                ctx.grant.leaseScope
+              );
+              return await issueInstallationCredential({
+                appIdEnv,
+                domains: GITHUB_ASSET_UPLOAD_CREDENTIAL_DOMAINS,
+                privateKeyEnv,
+                installationIdEnv,
+                repositoryIds: [repositoryId]
+              });
+            }
             const repository = githubRepositoryFromLeaseScope(
               ctx.grant.leaseScope
             );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-github",
-  "version": "0.104.1",
+  "version": "0.105.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -25,7 +25,7 @@
   "dependencies": {
     "@sinclair/typebox": "^0.34.49",
     "zod": "^4.4.3",
-    "@sentry/junior-plugin-api": "0.104.1"
+    "@sentry/junior-plugin-api": "0.105.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",

package/skills/attach-github-assets/SOURCES.md

@@ -13,7 +13,7 @@
 
 - **Adopted:** preserve the upstream one-file-per-upload behavior, supported formats, markdown output, and upload endpoint.
 - **Adopted:** preserve the upstream MIT license in the skill directory as explicitly required.
-- **Replaced:** direct `gh auth token` access with Junior's host-managed user credential injection so credentials never enter script output or files.
+- **Replaced:** direct `gh auth token` access with Junior's host-managed, repository-scoped installation credential injection so credentials never enter script output or files.
 - **Replaced:** numeric repository-id override with explicit `owner/repo`; the script resolves the id through authenticated `gh api`.
 - **Narrowed:** automatic activation requires a concrete local path and GitHub destination.
 - **Deferred:** live upload verification because it would create an external GitHub asset; deterministic mocked validation is sufficient for implementation checks.

package/skills/attach-github-assets/SPEC.md

@@ -23,7 +23,7 @@ Out of scope:
 - Run `scripts/upload.sh` once per local file.
 - Return image markdown or a bare video URL.
 - Surface per-file failures exactly enough for the user to act.
-- Use the GitHub plugin's host-managed credential injection; do not retrieve tokens in the script.
+- Use the GitHub plugin's repository-scoped installation credential injection; do not retrieve tokens in the script.
 
 ## Reference Architecture
 
@@ -40,7 +40,7 @@ Out of scope:
 ## Known Limitations
 
 - GitHub's user-attachment endpoint is not part of the documented public REST API.
-- A real upload requires GitHub to accept the active user credential for the target repository.
+- A real upload requires GitHub to accept the repository-scoped installation credential for the target repository.
 
 ## Maintenance Notes
 

package/skills/github-code/SKILL.md

@@ -1,180 +1,87 @@
 ---
 name: github-code
-description: Work with GitHub repositories, source code, branches, commits, pushes, pull requests, reviews, diffs, CI runs, and GitHub App credentials for branch and PR workflows. Use for repo implementation tasks, source-code investigation, cloning/fetching, branch and push workflows, PR creation or updates, PR review feedback, GitHub credential or permission failures involving repositories, pushes, or PRs, and GitHub Actions checks. Prefer this skill for repository and code tasks even when the repo concerns Sentry products.
+description: Work with GitHub repositories, source code, branches, commits, pull requests, reviews, diffs, CI, and repository credentials. Use for implementation, source investigation, clone/fetch/branch workflows, PR creation or updates, review feedback, GitHub Actions checks, and repository permission failures. Prefer this skill for repository tasks even when they concern a Sentry product.
 ---
 
 # GitHub Code Operations
 
-## Credential contract
-
-- Supported App-owned GitHub operations require no user-managed credential. Junior automatically mints and injects a repository-scoped GitHub App `installation-write` credential.
-- For a pull request from an existing branch, push the branch first, then call `github_createPullRequest`; both operations receive the automatic installation credential.
-- Do not ask the user to authorize GitHub, provide a token, or grant Contents/Pull requests permissions before trying a supported operation.
-- Request remediation only after a supported operation returns evidence of an upstream provider denial. A Junior tool-routing denial means retry with the required tool, not request permissions.
-
-Use `gh` and `git` for repository checkout, source investigation, code changes, commits, and pull request inspection or mutation. Use Junior's `github_createPullRequest` tool instead of `gh pr create` for new pull requests.
+Use `git` and `gh` for repository work. Use `github_createPullRequest`, not `gh pr create`, for new PRs.
 
 ## References
 
-| Need                                | Load                                                                                   |
-| ----------------------------------- | -------------------------------------------------------------------------------------- |
-| Command syntax, permissions, config | [references/api-surface.md](references/api-surface.md)                                 |
-| Failed commands, permission errors  | [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md) |
+| 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) |
 
-## Core rules
+## Non-negotiable rules
 
-- Resolve the target repo: explicit request wins, then `github.repo` config. Run `jr-rpc config get github.repo` standalone — never chain with `cd`, pipes, `gh`, or `git`.
-- Keep `--repo owner/repo` explicit on all `gh` commands; use `git -C PATH` for local repos.
-- Do not treat this skill's files or `/skills/...` as target repository source.
-- Read repo-local instructions (`AGENTS.md`, `.github/AGENTS.md`, nested equivalents) before editing. When repo, task-specific, and skill instructions conflict, follow the narrower rule.
-- Do not overwrite or revert unrelated user changes.
-- Do not guess architecture, upstream intent, or feedback validity without reading the relevant code, comments, or failing output.
-- Do not claim checks ran unless they did. Do not declare a fix complete without running the chosen check or stating why no credible check was available.
-- Stop on: missing repo access, ambiguous target, destructive op without confirmation, or unresolved permission failure.
+- Resolve the repo from the explicit 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.
+- Base conclusions on repository evidence. Do not claim a check ran unless it did.
+- Supported App-owned writes use an automatically injected repository-scoped credential. Try the operation before requesting remediation; ask for no user token.
+- Stop for ambiguous targets, missing access, destructive operations, or unresolved upstream permission failures.
 
 ## Workflow
 
-### 1. Resolve target and state
-
-Identify `owner/repo`, local checkout path, default branch, and current branch.
-
-For edit operations, also check:
-
-- current branch and uncommitted changes
-- package manager, build tool, monorepo structure
-- relevant test/lint/typecheck commands
-- repo-local instructions that override this skill
-
-Choose a validation path before editing:
-
-- changed-file or package-scoped checks before broad suites
-- targeted tests before full runs
-- repo-native scripts, fixtures, playgrounds, or smoke checks before one-off scaffolding
-
-For risky, user-visible, or long-running changes, capture a baseline before editing. If the baseline already fails, record it as pre-existing.
-
-Prefer existing local checkouts over cloning. Default to shallow clones.
-
-### 2. Investigate before editing
-
-Before changing code, establish:
-
-- where the behavior lives
-- what the current vs. requested behavior is
-- root cause or gap the change addresses
-- what smallest check can prove the result
-
-Rules:
-
-- Prefer narrow evidence: file reads, grep, tests, existing issues/PRs, command output.
-- Read referenced issues, PRs, specs, policies, designs, or incidents when the task points to them.
-- For product copy, docs, design, or UI work, inspect the real product/project context before inventing wording or layout.
-- Before editing a bug, know the failure shape: what breaks, where, and under what condition.
-- After a failed fix attempt or strong correction, stop patching symptoms — re-read the evidence and restate the root cause before editing again.
-- If the task is investigation-only, answer from evidence without editing.
-
-**Advisor planning checkpoint:** For a non-trivial implementation — especially architecture or API changes, security-sensitive behavior, concurrency, migrations, broad cross-file edits, or work following failed attempts — call the advisor after gathering enough evidence and before editing. Provide the requirements, relevant code and output, constraints, proposed plan, alternatives considered, risks, and intended validation path. Resolve or explicitly account for material concerns before implementing.
-
-### 3. Edit safely
-
-- Smallest coherent change that satisfies the request.
-- Follow repo-local style, patterns, and API boundaries.
-- Keep interfaces, exports, config, and public surfaces no broader than the requirement needs.
-- When the change touches related call sites or representations, remove duplication or split logic introduced by the change before finalizing.
-- No drive-by refactors or speculative cleanup.
-- Do not optimize only for passing tests; solve the requested behavior.
-- After meaningful edits, run the smallest relevant repo-real check.
-- On check failure, inspect root cause before patching again.
-
-For multi-step or risky work, keep a compact checklist of intent, touched files, verification state, next step, and blockers.
-
-### 4. Verify before packaging
-
-Before committing and creating a PR for code, config, or docs-as-code changes:
-
-- Run the chosen validation path. Separate pre-existing failures from regressions.
-- For docs or instruction-only changes, do a content consistency review instead of claiming automated validation.
-- If no credible check exists, say so explicitly.
-
-**Advisor review checkpoint:** For a non-trivial implementation, call the advisor after inspecting the final diff and running the initial validation path, but before committing, opening or updating a PR, or reporting completion. Provide the diff, relevant surrounding code, requirements, validation results, known limitations, and any remaining risks. Ask specifically for correctness issues, regressions, missed cases, and testing gaps. Investigate material findings, revise as needed, and rerun affected checks before packaging.
-
-### 5. Commit
-
-Default format when the repo does not specify otherwise:
-
-```
-<type>(<scope>): <Subject>
-```
-
-Types: `feat`, `fix`, `ref`, `docs`, `test`, `build`, `ci`, `chore`. Imperative present tense, no trailing period, no agent/tool branding. Keep lines under 100 characters.
-
-Body only when it helps reviewers understand _why_.
-
-Footer order: `Fixes`/`Refs` lines.
-
-### 6. Create or update PR
-
-Before creating:
-
-1. Changes committed on a non-default branch.
-2. Push the branch explicitly: `git push -u origin BRANCH`.
-3. Resolve the actual default branch: `gh repo view owner/repo --json defaultBranchRef --jq .defaultBranchRef.name`.
-4. Create with explicit targeting, using that default branch as `base`: `github_createPullRequest({ repo: "owner/repo", head: "BRANCH", base: "<DEFAULT_BRANCH>", title: "...", body: "...", draft: true })`.
+### 1. Resolve and inspect
 
-Defaults:
+Identify the repo, checkout, default/current branches, worktree state, repo instructions, package manager, and relevant checks. Prefer an existing checkout; otherwise clone shallowly.
 
-- Draft PRs unless the user or repo says otherwise.
-- Reuse an existing PR for the branch; only open a new one when explicitly asked or the work is materially distinct.
-- After new commits, re-evaluate title and body against the current diff.
+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.
 
-**Title:** `<type>(<scope>): <Subject>` — same rules as commits, no agent branding.
+For edits, choose the smallest credible validation path before changing files. Capture a baseline when a failure may be pre-existing.
 
-**Body:**
+### 2. Investigate
 
-- Reviewer-facing prose, not diff narration.
-- What changed and why; what was verified; what remains unverified or risky.
-- Issue references when relevant.
-- No checkbox boilerplate, no PII or customer data in public repos.
+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. If the request is investigation-only, report evidence without editing.
 
-**Footers** (in order):
+For non-trivial architecture, API, security, concurrency, migration, or broad cross-file work, use the available advisor after gathering evidence and before editing. Resolve material concerns in the plan.
 
-1. Issue references (`Fixes #N`, `Refs SENTRY-N`), if any.
+### 3. Edit
 
-**Assignment:** resolve GitHub handles from evidence (`gh api search/users`, org membership, repo history) before assigning requested reviewers or assignees. Skip assignment when the handle cannot be confirmed.
+Make the smallest coherent change. Follow local patterns and avoid speculative cleanup. After a failed attempt, re-check the root cause before patching again.
 
-### 7. Subscribe to PR lifecycle
+Before running repo checks, ensure project dependencies are available:
 
-After `github_createPullRequest` succeeds, check whether the result includes a subscribable resource hint. If it does, call `subscribeToResourceEvents` immediately before reporting.
+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.
 
-- Use the suggested events from the hint; when absent, request review and CI events.
-- Write a **self-contained intent** that captures repo, PR number, branch, and a single goal: resolve any review concerns and keep the build green. When an event fires, read the signal, address it, push, and report.
-- **Only post an update when there is something meaningful to say.** Report when feedback has been addressed, a build failure has been fixed, the PR is fully green and ready to merge, or the PR has been merged. Stay silent on intermediate CI passes, queued checks, and informational events with no action taken.
+Do not install or repair the GitHub plugin runtime itself; that is manifest-owned setup.
 
-If no subscribable hint is present, skip this step.
+### 4. Verify and review
 
-### 8. Report result
+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.
 
-Return: repo, branch, PR URL/number (when applicable), checks run with results, pre-existing failures if any, checks not run and why.
+For non-trivial work, review the final diff and initial results with the available advisor before packaging. Address material correctness, regression, and testing concerns, then rerun affected checks.
 
-On failure, report the exact command and error. Do not claim success from partial state.
+### 5. Package every completed edit
 
-Before finishing, reconcile any plan or checklist stated earlier — mark items as done, blocked, or cancelled.
+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.
 
-## Operation-specific notes
+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; otherwise call `github_createPullRequest` with explicit repo, head, base, title, body, and `draft: true` unless the user or repo explicitly requires ready-for-review.
 
-**Clone** — shallow by default; deepen only when history is needed. Read repo instructions after cloning, before editing.
+The PR body should explain what changed and why, checks run, and remaining risks or unverified areas. Never include customer data, PII, secrets, or sensitive thread context, especially in public repositories. Re-evaluate its title/body after material follow-up commits. Resolve requested assignee/reviewer handles from evidence; skip unconfirmed identities.
 
-**Source investigation** — use local files first, otherwise clone shallowly or use `gh`. Cite evidence: file paths, symbols, PRs, issues, command output.
+If PR creation is blocked, report the exact failed command/tool call and leave the committed branch intact.
 
-**PR inspection** — read-only `gh pr` and `gh api` commands. Query both conversation comments (`--json comments`) and review comments (`gh api .../pulls/{n}/comments` and `.../reviews`).
+### 6. Follow and report
 
-**PR mutation** — push before create. Use only the allowlisted REST endpoints in the API reference. Merge, close-with-delete, REST ref mutation, and admin operations are unsupported. Git smart HTTP does not independently prevent force updates or ref deletion; rely on GitHub rulesets and do not request destructive pushes.
+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.
 
-**Workflow dispatch** — `gh workflow run` is supported for workflows that declare `workflow_dispatch`. Workflow reruns, cancellations, and other Actions mutations remain unsupported.
+Return: repo, branch, PR URL/number, checks and results, pre-existing failures, and anything not run with the reason.
 
-## Guardrails
+## Operation notes
 
-- Default shallow clones; deepen only when needed.
-- Do not attempt destructive merges, force pushes, or ref deletion.
-- Answer source questions from repo evidence, not product framing or memory.
-- Stop and return concrete remediation on missing access or permissions.
+- **Clone/history:** clone shallowly by default; deepen before any operation that relies on omitted ancestry.
+- **PR inspection:** read conversation comments, inline review comments, reviews, diff, and checks.
+- **PR mutation:** push before create; use only supported endpoints in the API reference.
+- **Workflow dispatch:** `gh workflow run` is supported only for workflows declaring `workflow_dispatch`.
+- **Permissions:** a tool-routing denial requires the named tool; only an upstream denial justifies permission remediation.

package/skills/github-code/SPEC.md

@@ -0,0 +1,42 @@
+# github-code skill contract
+
+## Intent
+
+Guide evidence-first GitHub repository work from inspection through a reviewable result without duplicating command and troubleshooting detail in runtime context.
+
+## 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.
+- Report exact validation and permission failures without claiming partial work is complete.
+
+## Runtime architecture
+
+- `SKILL.md`: compact workflow and decision rules.
+- `references/api-surface.md`: command and permission lookup.
+- `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.
+
+## Trigger expectations
+
+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.
+
+## 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.
+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.

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

@@ -25,12 +25,14 @@ Treat explicit repo flags as command-targeting safety rails, not as a credential
 | Operation                          | Command                                                                                                                  |
 | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
 | Clone repository (default shallow) | `gh repo clone owner/repo [DIRECTORY] -- --depth=1`                                                                      |
-| Deepen shallow clone               | `git -C DIRECTORY fetch --depth=N origin`                                                                                |
-| Convert shallow clone to full      | `git -C DIRECTORY fetch --unshallow`                                                                                     |
+| 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 BASE..HEAD --oneline`                                                                              |
-| Diff against base                  | `git -C DIRECTORY diff BASE...HEAD`                                                                                      |
+| 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"`                                                        |
@@ -66,6 +68,7 @@ jr-rpc config set github.repo owner/repo
 - 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.
 - Merge, fork creation, workflow reruns or cancellations, REST contents/Git database writes, and repository administration are outside the current write allowlist.
 - 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.

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

@@ -2,24 +2,27 @@
 
 Use this table to recover quickly while keeping operations deterministic.
 
-| 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`.                                 |
-| `git blame`, long log history, or old commits are missing after clone | Repo was cloned shallow by design.                                               | Deepen incrementally with `git -C DIRECTORY fetch --depth=N origin`, or `git -C DIRECTORY fetch --unshallow` when full history is required.                                          |
-| `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.                                                                      |
+| 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`.                                                   |
+| `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 guidance