@vpxa/aikit 0.1.307 → 0.1.309

package/scaffold/dist/definitions/skills/repo-access.mjs

@@ -1,6 +1,6 @@
 var e=[{file:`references/error-patterns.md`,content:'# Repo Access Error Patterns\n\nUse this reference to distinguish missing repositories from authentication and policy failures when probing Git hosts.\n\n## HTTP Status Code Matrix\n\n| Platform | No auth (private repo) | Wrong credentials | Rate limited | SSO required |\n|---|---|---|---|---|\n| GitHub REST API | `404` (TRAP!) | `401` -> `403` | `403` + rate limit body | `403` + `X-GitHub-SSO` header |\n| GitHub Web | HTML "Page not found" or login redirect | Login redirect | - | - |\n| GitLab | `401` | `401` | `429` | `401` (PAT mandatory) |\n| Bitbucket | `403` | `403` | `429` | `403` |\n| Azure DevOps | `401` | `401` | - | `401` |\n\n## CRITICAL: The GitHub 404 Trap\n\nGitHub deliberately returns `404`, not `401`, for private repositories accessed without authentication.\nThis is by design to avoid leaking whether a repository exists.\n\n- Never conclude a GitHub repository does not exist from an unauthenticated `404`.\n- `GET https://api.github.com/repos/{owner}/{repo}` without auth returns `404` for both "repo truly missing" and "repo exists but is private".\n- The only reliable disambiguation is an authenticated probe.\n- If the same request still returns `404` with valid auth, the repository is truly missing.\n\nProbe order:\n\n1. Try the authenticated API request first.\n2. If it returns `200`, access works.\n3. If it returns `404` without auth context, treat it as ambiguous and recover.\n4. If it returns `404` with known-good auth, treat the repo as missing.\n\n## Git CLI Stderr Patterns\n\n| Error Text Pattern | Platform | Diagnosis | Action |\n|---|---|---|---|\n| `remote: Repository not found.` | GitHub | Auth failure, not proof the repo is missing | Try auth strategies |\n| `git@github.com: Permission denied (publickey).` | GitHub | SSH key not recognized | Check SSH keys, try HTTPS |\n| `remote: HTTP Basic: Access denied.` | GitLab | Auth failure, 2FA likely | Use PAT; password auth is blocked with 2FA |\n| `error: The requested URL returned error: 403` | Bitbucket | Auth failure | Try app password |\n| `TF401019: The Git repository with name or identifier X does not exist` | Azure DevOps | Auth failure or missing repo | Try PAT with Code:Read scope |\n| `fatal: Authentication failed for \'https://...\'` | Any (HTTPS) | General auth failure | Escalate through the strategy ladder |\n| `Permission denied (publickey).` | Any (SSH) | SSH key not recognized | Check `~/.ssh/`, run `ssh-add`, try HTTPS |\n| `fatal: Could not read from remote repository.` | Any (SSH) | SSH access denied | Verify the SSH key is added to the platform |\n| `unable to access \'...\': SSL certificate problem` | Any | Self-signed or enterprise CA issue | Ask about local cert config; skip to local clone if needed |\n\nTreat these stderr strings as direct signals from tool output. Do not reinterpret GitHub\'s `Repository not found` as a clean existence check.\n\n## web_fetch / http Tool Detection\n\n- `web_fetch` against a private GitHub repo URL often returns HTML with "Page not found" or a login page.\n- GitHub web responses can be `200` with a 404-looking body, so `web_fetch` is unreliable for auth diagnosis.\n- `http` against the platform API gives machine-readable bodies and real status codes, so use it for probes.\n- For `web_fetch` on `github.com`, inspect the body for `Page not found`, `Sign in`, or `/login` links. If present, assume private or auth-gated access and trigger recovery.\n\nRecommended diagnostic probe:\n\n```text\nhttp GET https://api.github.com/repos/{owner}/{repo}\n-> 404 + no auth header -> might be private\n-> 401 -> explicit auth failure\n-> 200 -> repo is public, access works\n```\n\n## Edge Cases\n\n| Edge Case | Signal | Response |\n|---|---|---|\n| GitHub.com SAML SSO | `403` + `X-GitHub-SSO: required; url=...` | PAT needs SSO authorization for the org |\n| GHE SAML SSO (web_fetch) | `200` + body contains `Initiating SAML single sign-on`, redirect to `login.microsoftonline.com` or other IdP | Repo EXISTS and is auth-gated. NOT inaccessible. Use PAT + `http` with auth headers, or `gh auth login --hostname <host>` |\n| GHE SAML SSO (http) | `302` redirect to `/login?return_to=...` or IdP URL | Same — repo exists, needs auth. Walk the Strategy Ladder |\n| GHE SAML SSO (git CLI) | `fatal: Authentication failed` or credential prompt | `gh auth login --hostname <host>` or PAT via credential helper |\n\n## SAML SSO — Detailed Pattern\n\nGitHub Enterprise instances commonly use SAML SSO via Azure AD (Entra ID), Okta, or other IdPs. When `web_fetch` hits a GHE URL without auth:\n\n1. GHE returns `200 OK` (not 401/403!) with an HTML page\n2. The HTML contains `Initiating SAML single sign-on` and a redirect URL to the IdP\n3. The redirect URL includes `SAMLRequest=`, `RelayState=`, and often `login.microsoftonline.com`\n4. The agent sees HTML content and may conclude the repo is "inaccessible" or "behind SSO"\n\n**Detection strings** (check `web_fetch` output for ANY of these):\n```\nInitiating SAML single sign-on\nlogin.microsoftonline.com\nYou are being redirected to your identity provider\n/login?return_to=\nSAMLRequest=\nRelayState=\n```\n\n**Correct response:** The repo exists. The `web_fetch` path will never work for SSO-protected GHE. Switch to:\n- `gh auth login --hostname <ghe-host>` (if `gh` CLI available)\n- PAT + `http` with `Authorization: token <PAT>` against `<ghe-host>/api/v3/repos/{owner}/{repo}/contents/{path}`\n- Ask user for local clone if no token can be obtained\n| GitLab 2FA enabled | `401` on password auth | PAT is mandatory; 2FA blocks password auth |\n| Expired token | `401` after providing a valid-looking PAT | Generate a new token and check expiry |\n| GitHub rate limit | `403` + body contains `rate limit` | Not an auth failure; wait or authenticate for a higher limit |\n| IP allowlisting | `403` + body mentions IP or org policies | Cannot be fixed programmatically; skip to local clone (Step 5) |\n| Fine-grained PAT scope | `403` + `insufficient scope` | Switch to a classic PAT for org repos |\n| SSH key not in agent | `Permission denied (publickey)` + key file exists | Run `ssh-add ~/.ssh/id_ed25519` |\n| Wrong SSH username | `Permission denied` | Use `git@host`, not `username@host` |\n| Deploy key conflict | `key is already in use` | Use a user SSH key or PAT instead |\n\n## Escalation Decision Rules\n\n- Retry the same step for transient failures such as DNS failure, timeout, or `5xx` responses.\n- Escalate to the next strategy step for `401`, `403`, `404`, `Permission denied`, `Authentication failed`, or `Access denied`.\n- Skip directly to Step 5 (local clone) for IP allowlisting, enterprise SSL certificate issues, or org policy blocks.\n\nDefault interpretation order:\n\n1. Prefer API probes over web page fetches.\n2. Treat GitHub `404` as ambiguous until valid auth disproves privacy.\n3. Treat SSH `publickey` errors as key-distribution failures, not repo absence.\n4. Separate rate limits and org policy blocks from authentication failures before escalating.'},{file:`references/platform-matrix.md`,content:"# Platform Matrix\n\nUse this reference when a repository URL reveals the hosting platform and the skill needs platform-specific authentication or cloning guidance. Prefer platform CLI login flows or OS-backed credential helpers over raw PAT handling.\n\n## Platform Detection\n\n| URL Pattern | Platform | CLI Tool (optional) | Auth Command | No-CLI Alternative |\n|---|---|---|---|---|\n| `github.com` | GitHub | `gh` | `gh auth login` | PAT + `http` with `Authorization: token <PAT>` |\n| Any custom domain (e.g. `ghe.corp.com`, `github.corp.com`) | GitHub Enterprise | `gh` | `gh auth login --hostname <host>` | PAT + `http` against `<host>/api/v3` |\n| `gitlab.com` | GitLab | `glab` | `glab auth login` | PAT + `http` with `PRIVATE-TOKEN` header |\n| Self-hosted GitLab | GitLab Self-Managed | `glab` | `glab auth login --hostname <host>` | PAT + `http` with `PRIVATE-TOKEN` header |\n| `bitbucket.org` | Bitbucket Cloud | None | N/A | App password + `http` with `Authorization: Bearer` |\n| `dev.azure.com` or `*.visualstudio.com` | Azure DevOps | `az` + GCM | `az login` | PAT + `http` with Basic auth |\n| Gitea instances | Gitea | `tea` (optional) | `tea login add` | PAT + `http` with `Authorization: token` |\n| Unknown or custom domain | Ask user which platform | N/A | N/A | Probe `http` or ask before assuming generic Git |\n\n> **Note:** Platform CLIs (`gh`, `glab`, `az`, `tea`) are native binaries, not npm packages. Do NOT use `npx` to install them — it will fail or install unrelated/unofficial packages. When the CLI is unavailable, use the No-CLI Alternative column.\n\n## GitHub / GitHub Enterprise\n\n- CLI: `gh auth login` uses a browser or device code flow and can open the browser automatically.\n- GitHub Enterprise CLI: `gh auth login --hostname <host>`.\n- PAT creation: `https://github.com/settings/tokens` for classic tokens.\n- PAT creation: `https://github.com/settings/personal-access-tokens` for fine-grained tokens.\n- Minimum scopes: `repo` for classic PATs (NOTE: `repo` grants read and write — prefer fine-grained PATs with `Contents: Read` for read-only access).\n- Minimum scopes: `Contents: Read` for fine-grained PATs.\n- SSH: `git@github.com:owner/repo.git`.\n- Credential helper: `gh auth setup-git` configures Git to use the GitHub credential flow.\n- Note: Fine-grained PATs may not cover organization-level access or every repo path; classic PATs are still required for some org repos.\n- SAML SSO: PATs often require explicit org authorization from `https://github.com/settings/tokens` after creation.\n- Enterprise note: PAT URLs and token policy can vary by host; reuse the same auth pattern with the enterprise hostname and instance settings pages.\n- Enterprise detection: GHE instances use fully custom domains (e.g. `ghe.coxautoinc.com`, `github.acme.com`). If unsure, probe `https://<host>/api/v3` — a GitHub Enterprise instance returns a JSON response with `installed_version`. Use `gh auth login --hostname <host>` with any custom GHE domain.\n\n## GitLab / GitLab Self-Managed\n\n- CLI: `glab auth login` uses a browser-backed OAuth flow.\n- Self-managed CLI: `glab auth login --hostname <host>`.\n- PAT creation: `https://gitlab.com/-/user_settings/personal_access_tokens`.\n- Minimum scopes: `read_repository`.\n- SSH: `git@gitlab.com:owner/repo.git`.\n- Credential helper: `glab auth setup-git` configures Git credential handling.\n- Note: If 2FA is enabled, username/password Git auth is blocked; a PAT is mandatory for HTTPS auth.\n- Self-managed note: PAT URL is typically `https://<host>/-/user_settings/personal_access_tokens` unless the instance customizes settings paths.\n\n## Bitbucket Cloud\n\n- CLI: No official first-party CLI OAuth flow for repo auth.\n- PAT/App Password creation: `https://bitbucket.org/{workspace}/settings/app-passwords`.\n- Minimum permissions: `Repositories: Read`.\n- SSH: `git@bitbucket.org:owner/repo.git`.\n- Note: Bitbucket Cloud uses App Passwords rather than standard PAT terminology.\n- Note: HTTPS auth requires both the Bitbucket username and the app password, delivered through a credential helper or `GIT_ASKPASS` script — never embedded in the clone URL.\n\n## Azure DevOps\n\n- CLI: `az login` authenticates to Microsoft Entra ID; Git Credential Manager then handles Git credentials automatically.\n- PAT-based auth remains the fallback when Entra ID or GCM is unavailable.\n- PAT creation: `https://dev.azure.com/{org}/_usersSettings/tokens`.\n- Minimum scopes: `Code: Read`.\n- SSH: `git@ssh.dev.azure.com:v3/{org}/{project}/{repo}`.\n- Note: Microsoft Entra ID tokens are generally preferred over PATs in enterprise environments.\n- Credential helper: Git Credential Manager via `git-credential-manager configure`.\n- Legacy host note: Azure DevOps may also appear under `*.visualstudio.com` URLs.\n\n## Gitea / Forgejo\n\n- CLI: `tea login add` is available but optional and not universally installed.\n- PAT creation: `https://{host}/user/settings/applications`.\n- Minimum scopes: `repo`.\n- SSH: `git@{host}:owner/repo.git`.\n- Note: Forgejo commonly mirrors the same applications-token path and PAT model as Gitea.\n- Note: Some self-hosted instances rename scopes or disable API token creation, so confirm the instance policy if `repo` is rejected.\n\n## Generic Git (Self-Hosted)\n\n- Platform CLI: None assumed.\n- Auth path: Prefer SSH keys first, then PAT if the host documents HTTPS token auth.\n- PAT creation: Ask the user for the platform's PAT or application-token settings URL.\n- SSH: Use the host's documented SSH remote format; do not assume GitHub-style shortcuts if the server advertises a different pattern.\n\n## API File-Read Endpoints (for web-based code access)\n\nWhen agents need to read individual files without cloning, use these authenticated API endpoints.\n\n### GitHub / GitHub Enterprise\n\n```text\n# Read file contents (returns JSON with base64 content)\nGET https://api.github.com/repos/{owner}/{repo}/contents/{path}?ref={branch}\nAuthorization: token <PAT>\n\n# GHE: replace api.github.com with <ghe-host>/api/v3\nGET https://<ghe-host>/api/v3/repos/{owner}/{repo}/contents/{path}?ref={branch}\n\n# Or use gh CLI (auto-authenticated):\ngh api repos/{owner}/{repo}/contents/{path}?ref={branch} --jq '.content' | base64 -d\n```\n\n### GitLab / GitLab Self-Managed\n\n```text\n# URL-encode the file path (/ becomes %2F)\nGET https://gitlab.com/api/v4/projects/{project-id}/repository/files/{url-encoded-path}/raw?ref={branch}\nPRIVATE-TOKEN: <PAT>\n\n# Or use project path instead of ID:\nGET https://gitlab.com/api/v4/projects/{url-encoded-namespace%2Fproject}/repository/files/{url-encoded-path}/raw?ref={branch}\n```\n\n### Azure DevOps\n\n```text\nGET https://dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/items?path={path}&api-version=7.0\nAuthorization: Basic {base64(:PAT)}\n```\n\n### Bitbucket Cloud\n\n```text\nGET https://api.bitbucket.org/2.0/repositories/{workspace}/{repo}/src/{commit-or-branch}/{path}\nAuthorization: Bearer <app-password-or-token>\n```\n- Note: Self-hosted products often customize auth policy, token names, and minimum scopes.\n\n## Safe Credential Delivery Patterns\n\n| Method | Command | Safety |\n|---|---|---|\n| Platform CLI | `gh auth login` / `glab auth login` | Best — handles credential storage |\n| Git Credential Manager | `git credential-manager configure` | Good — OS keychain storage |\n| Environment variable | `GH_TOKEN=xxx gh repo clone ...` | OK — ephemeral; safer than URL tokens but visible to same-user processes |\n| Git askpass | `GIT_ASKPASS=script git clone ...` | OK — no shell history exposure |\n| Inline in URL | `git clone https://token@host/...` | FORBIDDEN — leaks in history/logs |\n\n## Operational Notes\n\n- Prefer SSH when the user already has working keys and the host advertises a stable SSH remote format.\n- Prefer platform CLI login for GitHub and GitLab because it also wires Git credential storage.\n- Prefer Git Credential Manager for Azure DevOps and other HTTPS-heavy enterprise setups.\n- When recommending PAT creation, always suggest setting a short expiry (7-30 days for task-specific work). Prefer fine-grained or short-lived tokens.\n- Never recommend pasting tokens inline into clone URLs, scripts checked into the repo, or long-lived shell profiles."},{file:`SKILL.md`,content:`---
 name: repo-access
-description: "Progressive repository access recovery for private and enterprise git repositories. Triggered when: (1) git clone/fetch/pull fails with auth errors (401, 403, 404, Permission denied), (2) web_fetch or http tool returns auth failure on repository URLs, (3) user mentions private repo, enterprise repo, or internal repo, (4) user asks to access code from GitHub Enterprise, GitLab Self-Managed, Bitbucket Server, Azure DevOps. Guides through 6-step progressive strategy: anonymous HTTPS, SSH keys, CLI OAuth, PAT, local clone fallback, browser-based auth recovery (via browser-use skill)."
+description: "Progressive repository access recovery for private and enterprise git repositories. Triggered by clone/fetch/pull auth errors, repo URL web_fetch/http auth failures, private/internal repo mentions, or requests involving GitHub Enterprise, GitLab Self-Managed, Bitbucket Server, or Azure DevOps. Guides safe recovery from anonymous HTTPS through SSH/CLI/PAT/local clone/browser auth."
 metadata:
   category: cross-cutting
   domain: general
@@ -14,185 +14,40 @@ argument-hint: "Repository URL or error message"
 
 # Repository Access Recovery
 
-Progressively recover repository access for private, enterprise, and internal git hosts without leaking credentials.
+Recover repo access without leaking credentials. Use when git/http/web_fetch indicates private, enterprise, SSO, or auth failure.
 
-## When to Activate
+## Detect
 
-### Reactive triggers
-
-- \`git clone\`, \`git fetch\`, or \`git pull\` fails with \`401\`, \`403\`, \`404\`, \`Authentication failed\`, or \`Permission denied (publickey)\`.
-- \`http\` diagnostics against a repo endpoint show auth failure or ambiguous private-repo responses.
-- \`web_fetch\` returns login page HTML, SSO redirect, "Sign in", "Page not found", or empty/truncated content for a repo URL.
-- Any tool output contains "behind SSO", "SSO required", "SAML", "requires authentication", or similar auth-gate language about a repository.
-- A repository URL works in a browser for the user but fails from agent tools or terminal commands.
-- **You are about to declare a repo "inaccessible" or "unreachable"** — STOP and activate this skill first.
-
-### Proactive triggers
-
-- The user says the repo is private, enterprise, self-managed, internal, or SSO-protected.
-- The repo is hosted on GitHub Enterprise, GitLab Self-Managed, Bitbucket Server/Data Center, Azure DevOps, Gitea, or another custom git host.
-- The environment may need browser sign-in, SSH agent setup, or token-based recovery before any code access can work.
-
-## When NOT to Activate
-
-- Public repositories that already clone or read successfully over HTTPS.
-- Local-only repositories where no remote auth is involved.
-- Problems caused by branch protection, merge conflicts, or rate limiting rather than repository access.
-
-## Step 0: Platform Detection & Capability Gate
-
-Detect platform from the URL, then decide what recovery options are possible in this environment.
-
-| URL pattern | Platform |
-| --- | --- |
-| \`github.com\`, or any GHE host (e.g. \`ghe.*\`, \`github.*\`, custom domain) | GitHub / GitHub Enterprise |
-| \`gitlab.com\`, \`gitlab.<corp-host>\` | GitLab / GitLab Self-Managed |
-| \`bitbucket.org\`, \`bitbucket.<corp-host>\` | Bitbucket Cloud / Server |
-| \`dev.azure.com\`, \`visualstudio.com\`, \`/_git/\` | Azure DevOps |
-| anything else with git over HTTPS/SSH | Unknown — ask the user which platform before assuming generic Git |
-
-- Capability gate: has terminal, has browser, or conversation-only.
-- If terminal is unavailable, skip directly to PAT guidance or local clone fallback.
-- If browser is unavailable, prefer SSH or pre-created credentials over CLI OAuth.
-- If only the \`http\` tool is available (no terminal, no CLI): use PAT + authenticated API reads (see "Web-Based Code Access" below). This is the zero-dependency path — no \`gh\`, \`glab\`, or \`az\` installation needed.
-
-For platform-specific details, read \`references/platform-matrix.md\`.
+Triggers: 401, 403, 404 on private repo, Authentication failed, Permission denied (publickey), SSO required, login HTML, empty repo page, enterprise host, internal/private repo wording.
 
 ## Strategy Ladder
 
-### Step 1: Try HTTPS Anonymous Access
-
-- Goal: prove the repo is public or already reachable without extra auth.
-- What to do: normalize the remote to an HTTPS URL and run \`git ls-remote https://...\`. If it succeeds, use HTTPS and stop. If it fails with auth-like errors, continue instead of assuming the repo is missing.
-- Verify: \`git ls-remote <url>\`; SUCCESS -> stop, FAIL -> Step 2.
-
-### Step 2: Check Existing SSH Keys
-
-- Goal: reuse working SSH credentials before asking for new secrets.
-- What to do: inspect \`~/.ssh/\` for key files, run \`ssh-add -l\`, then test host auth with \`ssh -T git@{host}\`. If SSH works, switch the remote to the SSH URL and continue with that transport.
-- Verify: \`git ls-remote <ssh-url>\`; SUCCESS -> stop, FAIL -> Step 3.
-
-### Step 3: Platform CLI OAuth
-
-- Goal: use the platform's interactive login flow with stored credentials.
-- What to do: check whether the matching CLI exists, for example \`which gh\`, \`which glab\`, or \`which az\` (or platform equivalent). If installed, run \`{cli} auth login\` and let it complete browser or device OAuth, then retry git access.
-- **If the CLI is not installed**: do NOT try \`npx\` — platform CLIs (\`gh\`, \`glab\`, \`az\`) are native binaries, not npm packages. Skip straight to Step 4 (PAT). For file-read-only tasks, the \`http\` tool with a PAT header is a zero-dependency alternative to any CLI.
-- Verify: \`git ls-remote <url>\`; SUCCESS -> stop, FAIL -> Step 4.
-
-### Step 4: Personal Access Token
-
-- Goal: recover access when SSH and CLI OAuth are unavailable or blocked.
-- What to do: ask the user to create a PAT or app password at the platform-specific URL with minimum read scopes only. Have the user provide it through an env var or credential helper, then configure git credentials without embedding the token in the remote URL.
-- Verify: \`git ls-remote <url>\`; SUCCESS -> stop, FAIL -> Step 5.
-
-### Step 5: Local Clone Fallback
-
-- Goal: unblock work when remote auth cannot be completed from the current environment.
-- What to do: ask the user to clone the repository on their machine using their normal workflow, then provide the local filesystem path. Use the local checkout as the source of truth for code access.
-- Verify: local repo exists and \`git rev-parse --show-toplevel\` succeeds; SUCCESS -> stop, FAIL -> Step 6.
-
-### Step 6: Browser-Based Auth Recovery
-
-- Goal: use the AI Kit browser tool to authenticate through login walls, SAML SSO, or OAuth flows that block all CLI paths.
-- Prerequisite: **load the \`browser-use\` skill** before proceeding.
-- What to do:
-  1. \`browser({ action: 'open', url: repoUrl, mode: 'ui' })\` — open the target resource in the browser.
-  2. \`browser({ action: 'read', pageId })\` — check if login form, SSO redirect, or content appears.
-  3. If SSO/OAuth login form → interact using \`browser({ action: 'act', pageId, kind: 'click' | 'type', ... })\` (ask user for credentials, NEVER guess).
-  4. If 2FA prompt → ask user for code via elicitation → \`browser({ action: 'act', pageId, kind: 'type', ... })\` to enter it.
-  5. Once authenticated → extract content via \`browser({ action: 'read', pageId })\` or \`browser({ action: 'eval', pageId, code })\`.
-  6. For ongoing CLI access → extract session cookies:
-     \`\`\`javascript
-     browser({ action: 'session', sessionAction: 'cookies', pageId })
-     \`\`\`
-  7. Use extracted cookies with the \`http\` tool: \`http({ url, headers: { Cookie: '...' } })\`.
-- Verify: content is accessible via browser tools; SUCCESS -> stop.
-- If browser-based auth also fails → the resource genuinely requires manual user intervention outside the agent workflow. Inform the user.
-
-> **Security:** Never store extracted cookies in code, commits, or logs. Warn the user that cookies are auth tokens that expire.
-
-## Security Rules (HARD GATE)
-
-- NEVER include a PAT in a git URL; it leaks into shell history, process lists, logs, and config.
-- NEVER repeat a user's token value in chat output, summaries, examples, or when relaying tool output that may contain credentials.
-- Use env vars, credential helpers, or platform login tools for token delivery.
-- Recommend minimum scopes only: read-only repo scopes, not broad write/admin scopes.
-- Prefer ephemeral credentials, OAuth/device flows, or short-lived tokens over long-lived PATs.
-- When guiding PAT creation, recommend the shortest feasible expiry (7–30 days for task-specific work).
-
-## After Access Is Established
-
-- Remind the user to revoke single-use PATs once the task is complete.
-- If credentials were stored via a credential helper, note that they persist until manually removed or the token expires.
-
-## Web-Based Code Access (web_fetch / http)
-
-Agents often use \`web_fetch\` or \`http\` to read individual files without a full clone. These requests fail silently on private repos — GitHub returns \`404\` or login HTML, not an auth error.
-
-### Common URL Patterns That Fail on Private Repos
-
-| URL Pattern | Platform | What Happens |
-|---|---|---|
-| \`raw.githubusercontent.com/{owner}/{repo}/{ref}/{path}\` | GitHub | \`404\` — no auth header accepted |
-| \`github.com/{owner}/{repo}/blob/{ref}/{path}\` | GitHub web view | \`200\` with login HTML, not code |
-| \`api.github.com/repos/{owner}/{repo}/contents/{path}\` | GitHub API | \`404\` (the GitHub 404 trap) |
-| \`<ghe-host>/{owner}/{repo}/*\` (any GHE URL) | GitHub Enterprise | \`200\` with SAML SSO redirect page — body contains "Initiating SAML single sign-on" and redirect to \`login.microsoftonline.com\` or other IdP |
-| \`gitlab.com/{owner}/{repo}/-/raw/{ref}/{path}\` | GitLab | \`401\` or login redirect |
-| \`dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/items\` | Azure DevOps | \`401\` or \`203\` non-authoritative |
-
-### SAML SSO Detection (CRITICAL)
-
-GHE instances with SAML SSO return \`200 OK\` with an HTML body that is NOT the requested content. **This is the most common false-"inaccessible" scenario.** Detect it by checking \`web_fetch\` output for ANY of these strings:
-
-- \`Initiating SAML single sign-on\`
-- \`login.microsoftonline.com\` (Azure AD / Entra ID)
-- \`You are being redirected to your identity provider\`
-- \`/login?return_to=\`
-- \`SAMLRequest=\`
-- \`RelayState=\`
-
-If ANY of these appear → the repo exists and is accessible, it just needs authentication. This is NOT "inaccessible" — follow the Strategy Ladder.
-
-### Recovery: Authenticated API Reads
-
-When \`web_fetch\` fails on a private repo URL, switch to authenticated \`http\` calls:
-
-1. **Ensure auth is established first** — walk the Strategy Ladder (Steps 1-4) to get working credentials.
-2. **Use the platform API with auth headers**, not raw/web URLs:
+1. Normalize URL and identify host/platform.
+2. Try anonymous HTTPS/read-only when public access may work.
+3. Check local clone/workspace before remote auth work.
+4. Try SSH if keys are available and host supports it.
+5. Try platform CLI auth when installed/configured.
+6. Ask user for PAT/token only when needed; never echo it.
+7. If browser login/SSO is required, load browser-use.
 
-| Platform | Authenticated file-read endpoint | Auth header |
-|---|---|---|
-| GitHub / GHE | \`http GET https://api.github.com/repos/{owner}/{repo}/contents/{path}?ref={branch}\` | \`Authorization: token <PAT>\` or use \`gh api\` |
-| GitLab | \`http GET https://gitlab.com/api/v4/projects/{id}/repository/files/{path}/raw?ref={branch}\` | \`PRIVATE-TOKEN: <PAT>\` |
-| Azure DevOps | \`http GET https://dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/items?path={path}&api-version=7.0\` | \`Authorization: Basic <base64(:PAT)>\` |
-| Bitbucket | \`http GET https://api.bitbucket.org/2.0/repositories/{owner}/{repo}/src/{ref}/{path}\` | \`Authorization: Bearer <token>\` |
+Stop climbing once access works. Record working method and scope.
 
-3. **Prefer \`http\` over \`web_fetch\`** for private repos — \`http\` sends proper headers and returns machine-readable JSON; \`web_fetch\` gets HTML login pages.
-4. **For bulk reads**, prefer \`git clone --depth 1\` over many individual API calls — it's faster and avoids rate limits.
-5. **NEVER embed tokens in URLs** — use auth headers via the \`http\` tool or \`gh api\` CLI wrapper.
+## Safety
 
-### Quick Decision: Clone vs API Read
+- Never print secrets, cookies, tokens, or full auth headers.
+- Prefer least privilege: read-only before write scopes.
+- Ask before changing git remotes or credential helpers.
+- Do not bypass org policy or SSO controls.
+- Treat 404 on private hosts as possible auth failure, not proof repo is absent.
 
-| Situation | Preferred method |
-|---|---|
-| Need 1-3 specific files | Authenticated API via \`http\` |
-| Need to browse/search the repo | \`git clone --depth 1\` (shallow) |
-| Need file history or blame | \`git clone\` |
-| No terminal available | Authenticated API via \`http\` with PAT |
-| Rate-limited on API | \`git clone --depth 1\` |
+## Diagnostics
 
-## Tool Routing
+Capture command/tool, URL host (not secret), status/error, auth method attempted, and next safe option. Use http/web_fetch before browser unless page requires JS/login.
 
-| Tool | Use |
-| --- | --- |
-| \`git_context\` | Check local repo state and confirm a clone or fallback checkout is usable |
-| \`http\` | Probe platform APIs for auth diagnostics AND read file contents from private repos with auth headers |
-| \`web_fetch\` | Only for public repos or after confirming access works; unreliable for private repos (returns HTML, not code) |
-| \`web_search\` | Find current platform-specific auth documentation when the host is unusual or self-managed |
-| Terminal | Run git commands, SSH tests, CLI auth flows, and credential-helper setup |
+## References
 
-For detailed error patterns, read \`references/error-patterns.md\`.
+Load references/error-patterns.md for exact failure mapping. Load references/platform-matrix.md for GitHub/GitLab/Bitbucket/Azure differences.
 
-## CRITICAL: The GitHub 404 Trap
+## Output
 
-GitHub commonly returns \`404 Not Found\` for private repositories when the caller is unauthenticated or under-authenticated. NEVER conclude that a GitHub repository does not exist from a \`404\` alone. Treat that response as an authentication signal first, then walk the ladder before declaring the repo missing.`}];export{e as default};
+Return access status, method used or blocker, safe next step, and any user action needed.`}];export{e as default};

package/scaffold/dist/definitions/skills/requirements-clarity.mjs

@@ -12,38 +12,46 @@ metadata:
 
 # Requirements Clarity
 
-## When to Skip
+Use before planning/implementation when requirements are vague, large, cross-team, user-facing, or likely to fork. Skip for clear bug fixes, exact file edits, or mechanical changes.
 
-Do NOT activate when:
-- Specific file paths mentioned (e.g., "auth.go:45")
-- Code snippets or existing functions/classes referenced
-- Bug fixes with clear reproduction steps
-- Task is a single-file change with obvious scope
+## First Questions
 
-## Mindset
+Ask early unless already answered:
+1. Why is this needed now? (YAGNI)
+2. What simpler version would still solve it? (KISS)
 
-Requirements engineering is detective work, not stenography. Your job is NOT to write down what the user says - it's to uncover what they haven't said yet.
+Then ask only critical missing questions.
 
-The user knows their PROBLEM but often conflates it with a specific SOLUTION. Separate these. The problem is the requirement; the solution is a design decision.
+## Score
 
-Before asking questions, mentally model:
-- **Stakeholders** - Who else cares? Who gets paged at 2am? Who pays?
-- **Failure modes** - What breaks? What's the blast radius? What's unrecoverable?
-- **Boundaries** - What's explicitly OUT of scope? What's "phase 2"?
+0-39: unclear goal or user.
+40-69: goal known, major behavior/scope gaps remain.
+70-89: mostly clear, some edge cases/acceptance gaps.
+90-100: implementable with acceptance criteria, scope, constraints, and validation path.
 
-## Protocol
+Do not proceed to plan/implementation below 90 unless user explicitly accepts risk.
 
-### 1. YAGNI/KISS Gate
+## Clarify Dimensions
 
-Before ANY scoring, ask:
-- **Why?** — Is this needed now? YAGNI check.
-- **Simpler?** — Is there a simpler approach? KISS check.
+- User/persona and job-to-be-done.
+- Exact behavior and non-goals.
+- Inputs/outputs/data ownership.
+- Error/empty/loading/security/privacy cases.
+- Success metrics and acceptance tests.
+- Constraints: deadline, compatibility, migration, dependencies.
+- Rollout/rollback and observability.
 
-If the answers show the feature is not needed now, should be deferred, or has a trivial solution, advise that directly instead of continuing to scoring.
+## Output
 
-### 2. Score (0-100)
+Return current score, knowns, unknowns, 1-3 questions, and simplest viable scope. When score reaches 90+, provide implementation-ready brief and hand off to brainstorming/planning if design choices remain.
 
-Assess the requirement against this rubric:
+## References
+
+Load on demand:
+- references/scoring-guide.md — Full scoring rubric (0-100), calibration examples per category, expert probing techniques, iterate-until flow.
+`},{file:`references/scoring-guide.md`,content:`# Scoring Guide
+
+## Full Scoring Rubric (0-100)
 
 | Category | Points | Criteria |
 |----------|--------|----------|
@@ -52,7 +60,7 @@ Assess the requirement against this rubric:
 | Implementation Completeness | /25 | Edge cases (8), error handling (9), data validation (8) |
 | Business Context | /20 | Problem statement (7), target users (7), success metrics (6) |
 
-### Calibration Examples
+## Calibration Examples
 
 **Functional Clarity 10/10:**
 "User clicks Submit -> system validates email format (RFC 5322), checks uniqueness against users table, returns 201 with serialized user object (id, email, createdAt) or 422 with field-level errors array [{field, code, message}]"
@@ -72,9 +80,7 @@ Assess the requirement against this rubric:
 **Edge Cases 2/8:**
 "Handle errors appropriately"
 
-### Expert Probing Techniques
-
-For each gap category, ask focused questions that reveal hidden requirements:
+## Expert Probing Techniques
 
 **For edge cases:** Ask about empty states, concurrent access, partial failures, permission boundaries, rate limits, timezone/locale behavior, offline/degraded mode, data migration from existing state.
 
@@ -86,9 +92,8 @@ For each gap category, ask focused questions that reveal hidden requirements:
 
 **For business context:** Ask "Who loses money if this breaks?", "What's the rollback plan?", "How will you know this is working in production?"
 
-### 3. Iterate Until ≥ 90
+## Iterate Until >= 90
 
-For each clarification round:
 1. Score the current requirement.
 2. Identify the 2-3 highest-impact gaps.
 3. Ask focused questions for one category at a time.
@@ -96,76 +101,22 @@ For each clarification round:
 5. Capture clarified details in a working outline.
 6. Repeat until the score is at least 90.
 
-Prefer short, targeted questions over long questionnaires. Build on previous answers instead of repeating the whole requirement.
-
-**HARD RULE:** Do not generate the requirements document with a score below 90.
+Prefer short, targeted questions over long questionnaires. Build on previous answers.
 
-## NEVER
+HARD RULE: Do not generate the requirements document with a score below 90.
 
-- **NEVER accept vague acceptance criteria** like "it should work" or "user-friendly" - demand measurable outcomes (response time, error rate, specific user action -> specific system response)
-- **NEVER skip the YAGNI check** - 40% of requirements are premature. Ask "what happens if we ship without this?" first
-- **NEVER ask more than 3 questions per round** - cognitive overload causes shallow answers. Depth > breadth.
-- **NEVER accept "edge cases: handle errors appropriately"** - this means "I haven't thought about it." Push for specific scenarios.
-- **NEVER generate the document below score 90** - incomplete requirements cause more rework than taking time to clarify
-- **NEVER repeat questions the user already answered** - build on previous responses, reference what they said
-- **NEVER score above 80 without concrete acceptance criteria** - if you can't write a test for it, it's not a requirement
+## Generating the Document
 
-### 4. Generate Requirements Document
-
-**Output path (flow-aware):**
-- If a flow is active: \`flow({ action: 'status' })\` → write to \`{{artifacts_path}}/requirements.md\`
-- If no flow active: write to \`.spec/{feature_name}/requirements.md\`
-
-To detect active flow:
-\`\`\`
-const flowStatus = flow({ action: 'status' });
-if (flowStatus.active) {
-  // Output to: .flows/{topic}/.spec/requirements.md
-  outputPath = \`\${flowStatus.artifactsPath}/requirements.md\`;
-} else {
-  outputPath = \`.spec/\${featureName}/requirements.md\`;
-}
-\`\`\`
-
-Use \`create_file\` to save the document after the score reaches 90 or higher.
+When score reaches 90+:
+- Flow-aware: write to \`{{artifacts_path}}/requirements.md\`
+- No flow: write to \`.spec/{feature_name}/requirements.md\`
 
 Required structure:
-- **Requirements Description**
-  - Background
-  - Feature overview
-  - Detailed requirements
-  - Edge cases
-- **Design Decisions**
-  - Technical approach
-  - Constraints
-  - Risk assessment
-- **Acceptance Criteria**
-  - Functional acceptance checkboxes
-  - Quality standards
-  - User acceptance
-- **Execution Phases**
-  - Preparation
-  - Core development
-  - Integration and testing
-  - Deployment
-
-Each section must contain concrete, implementation-ready content. Do not leave placeholders.
-
-Footer fields:
-- Document Version
-- Created timestamp
-- Clarification Rounds count
-- Quality Score /100
-
-**After writing:** Also store a compact summary in flow-scoped knowledge for downstream step consumption:
-\`\`\`
-knowledge({ 
-  action: "remember", 
-  scope: "flow", 
-  category: "context",
-  title: "Requirements: <feature>",
-  content: "Score: <X>/100\\nKey Requirements:\\n- <req1>\\n- <req2>\\nAcceptance Criteria:\\n- <criteria1>\\nConstraints:\\n- <constraint1>"
-})
-\`\`\`
-This ensures downstream steps (Spec, Plan, Implementation) can access requirements via \`withdraw\` even without reading the file.
+- Requirements Description (background, feature overview, detailed requirements, edge cases)
+- Design Decisions (technical approach, constraints, risk assessment)
+- Acceptance Criteria (functional, quality, user acceptance)
+- Execution Phases (preparation, core dev, integration, deployment)
+- Footer: version, timestamp, clarification rounds, quality score
+
+Also store compact summary in flow-scoped knowledge for downstream consumption.
 `}];export{e as default};