@vpxa/aikit 0.1.72 → 0.1.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.72",
+  "version": "0.1.73",
   "type": "module",
   "description": "Local-first AI developer toolkit — knowledge base, code analysis, context management, and developer tools for LLM agents",
   "license": "MIT",

package/scaffold/definitions/bodies.mjs

@@ -257,7 +257,17 @@ Before every tool call, verify:
 | \`session-handoff\` | Context filling up, session ending, or major milestone |
 | \`lesson-learned\` | After completing work — extract engineering principles |
 | \`docs\` | During \`_docs-sync\` epilogue — living documentation convention, templates, change-to-doc mapping |
-| \`repo-access\` | When any agent encounters git auth failures (401/403/404, Permission denied) or needs to access private/enterprise repos |
+| \`repo-access\` | **IMMEDIATELY** when YOU or any subagent get auth failures from \`web_fetch\`, \`http\`, or git commands (401, 403, 404, SSO redirect, login HTML, "Permission denied"). NEVER declare a repo "inaccessible" without first loading this skill and walking the Strategy Ladder |
+
+## Repo Access — HARD RULE
+
+**If \`web_fetch\` or \`http\` returns 401, 403, 404, SSO redirect, login page HTML, or any auth-like failure for a repository or code URL:**
+1. **STOP** — do NOT declare the repo "inaccessible" or "behind SSO"
+2. **Load the \`repo-access\` skill** and follow its Strategy Ladder
+3. **Walk all 5 steps** before concluding access is impossible
+4. **Include \`repo-access\` in subagent prompts** when delegating tasks that touch the same repo
+
+This applies to YOU (the Orchestrator) when you use \`web_fetch\`/\`http\` directly, not just subagents.
 
 **When dispatching subagents**, include relevant skill names in the prompt so subagents know which skills to load (e.g., "Load the \`react\` and \`typescript\` skills for this task").
 

package/scaffold/general/agents/Orchestrator.agent.md

@@ -274,7 +274,17 @@ Before every tool call, verify:
 | `session-handoff` | Context filling up, session ending, or major milestone |
 | `lesson-learned` | After completing work — extract engineering principles |
 | `docs` | During `_docs-sync` epilogue — living documentation convention, templates, change-to-doc mapping |
-| `repo-access` | When any agent encounters git auth failures (401/403/404, Permission denied) or needs to access private/enterprise repos |
+| `repo-access` | **IMMEDIATELY** when YOU or any subagent get auth failures from `web_fetch`, `http`, or git commands (401, 403, 404, SSO redirect, login HTML, "Permission denied"). NEVER declare a repo "inaccessible" without first loading this skill and walking the Strategy Ladder |
+
+## Repo Access — HARD RULE
+
+**If `web_fetch` or `http` returns 401, 403, 404, SSO redirect, login page HTML, or any auth-like failure for a repository or code URL:**
+1. **STOP** — do NOT declare the repo "inaccessible" or "behind SSO"
+2. **Load the `repo-access` skill** and follow its Strategy Ladder
+3. **Walk all 5 steps** before concluding access is impossible
+4. **Include `repo-access` in subagent prompts** when delegating tasks that touch the same repo
+
+This applies to YOU (the Orchestrator) when you use `web_fetch`/`http` directly, not just subagents.
 
 **When dispatching subagents**, include relevant skill names in the prompt so subagents know which skills to load (e.g., "Load the `react` and `typescript` skills for this task").
 

package/scaffold/general/skills/repo-access/SKILL.md

@@ -22,7 +22,10 @@ Progressively recover repository access for private, enterprise, and internal gi
 
 - `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
 
@@ -113,9 +116,23 @@ Agents often use `web_fetch` or `http` to read individual files without a full c
 | `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:

package/scaffold/general/skills/repo-access/references/error-patterns.md

@@ -65,7 +65,34 @@ http GET https://api.github.com/repos/{owner}/{repo}
 
 | Edge Case | Signal | Response |
 |---|---|---|
-| GitHub SAML SSO | `403` + `X-GitHub-SSO: required; url=...` | PAT needs SSO authorization for the org |
+| GitHub.com SAML SSO | `403` + `X-GitHub-SSO: required; url=...` | PAT needs SSO authorization for the org |
+| 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>` |
+| GHE SAML SSO (http) | `302` redirect to `/login?return_to=...` or IdP URL | Same — repo exists, needs auth. Walk the Strategy Ladder |
+| GHE SAML SSO (git CLI) | `fatal: Authentication failed` or credential prompt | `gh auth login --hostname <host>` or PAT via credential helper |
+
+## SAML SSO — Detailed Pattern
+
+GitHub Enterprise instances commonly use SAML SSO via Azure AD (Entra ID), Okta, or other IdPs. When `web_fetch` hits a GHE URL without auth:
+
+1. GHE returns `200 OK` (not 401/403!) with an HTML page
+2. The HTML contains `Initiating SAML single sign-on` and a redirect URL to the IdP
+3. The redirect URL includes `SAMLRequest=`, `RelayState=`, and often `login.microsoftonline.com`
+4. The agent sees HTML content and may conclude the repo is "inaccessible" or "behind SSO"
+
+**Detection strings** (check `web_fetch` output for ANY of these):
+```
+Initiating SAML single sign-on
+login.microsoftonline.com
+You are being redirected to your identity provider
+/login?return_to=
+SAMLRequest=
+RelayState=
+```
+
+**Correct response:** The repo exists. The `web_fetch` path will never work for SSO-protected GHE. Switch to:
+- `gh auth login --hostname <ghe-host>` (if `gh` CLI available)
+- PAT + `http` with `Authorization: token <PAT>` against `<ghe-host>/api/v3/repos/{owner}/{repo}/contents/{path}`
+- Ask user for local clone if no token can be obtained
 | GitLab 2FA enabled | `401` on password auth | PAT is mandatory; 2FA blocks password auth |
 | Expired token | `401` after providing a valid-looking PAT | Generate a new token and check expiry |
 | GitHub rate limit | `403` + body contains `rate limit` | Not an auth failure; wait or authenticate for a higher limit |