| name | qa-fix-routing |
| description | Repo/tracker routing library for the vc-fix plugin โ decides which external product repo owns a bug (client vs platform), whether the fix delivers as a direct PR, a fork-PR, or an upstream issue, and which VCS/tracker host to talk to. Used by /qa-fix and /project-init. Self-contained โ no dependency on the ci/ directory. |
qa-fix-routing โ repo + tracker routing library
Self-contained TypeScript library extracted from ci/lib/ so the vc-fix plugin
does not depend on the ci/ directory (the headless CI regression/fix pipeline)
persisting or being installed. /qa-fix and /project-init invoke these modules
directly (via a tsx/node one-off script, same pattern the original ci/lib
files used) rather than authoring routing logic inline.
Files
| File | Role |
|---|
skill-dir.ts | SKILL_DIR โ this directory's own path via fileURLToPath(import.meta.url), CWD-independent. Shared by repo-router.ts and module-registry.ts so the pattern isn't duplicated. |
repo-router.ts | Core routing: repoKind, repoOwnership, isAllowedRepo, repoProfile (build/test cmd per kind), contributionPlan (direct / fork / issue), suggestRepo, checkoutForFix. Reads fix-repos.json (allowlist + routing hints) and the deployment profile (project-profile.json via loadProjectProfile). |
module-registry.ts | Live VC module dependency graph via the Platform API (BACK_URL) โ repoFromProjectUrl, moduleIdToRepoGuess. Caches to .module-registry.cache.json (gitignored) next to this file. |
provenance.ts | Pure logic, no I/O โ classifyFrontendProvenance / frontendDeliveryPlan for Gate 1b (telling a client's storefront-fork customization from an unmodified-platform bug). Depends only on repo-router.ts's RepoOwnership type. |
ado-rest.ts | Azure DevOps REST auth helpers (PAT or az login) shared by the Azure tracker/VCS. |
vcs/ | Vcs interface + github-vcs.ts (gh CLI) + azure-repos-vcs.ts (ADO REST) implementations + index.ts factory (getVcs/getUpstreamVcs). |
trackers/ | Tracker interface + jira-tracker.ts + azure-tracker.ts implementations + index.ts factory. |
fix-repos.json | Data: allowed-repo patterns/denylist/explicit kinds + routing keyword table. Override path via FIX_REPOS_CONFIG; org override via FIX_REPO_ORG. |
Why extracted (not referencing ci/lib/ in place)
The original ci/lib/repo-router.ts etc. back the headless ci/run-fix-cycle.ts
CI twin. vc-fix only needs the routing/checkout logic, not the CI orchestration
โ so it carries its own copy here. The fix-repos.json / .module-registry.cache.json
default paths resolve off this directory's own path (SKILL_DIR, from skill-dir.ts)
rather than process.cwd() โ still overridable via FIX_REPOS_CONFIG /
MODULE_REGISTRY_CACHE. If ci/ is ever removed from this repo, or this plugin
is installed on its own with no ci/ present at all, vc-fix keeps working
unaffected.
Fully self-contained (not repo-coupled)
vc-fix does not assume it lives inside a full checkout of this repo. Claude
Code plugin installs don't reliably give a plugin's own commands/skills a
resolvable "project root" to reference shared files from (no documented
${CLAUDE_PLUGIN_ROOT}-equivalent, and bare relative paths resolve against
whatever the user's current working directory happens to be โ see the
plugin's own knowledge/, .claude/rules/, scripts/lib/ etc., which are
duplicated into plugins/vc-fix/ rather than referenced at the parent
repo's root, precisely to avoid that dependency). scripts/lib/project-profile.mjs
and scripts/lib/resolve-test-env.js are copied to plugins/vc-fix/scripts/lib/
(not shared with the root copy) โ see the ../../scripts/lib/project-profile.mjs
imports in repo-router.ts and the one-deeper ../../../scripts/lib/... in the
vcs//trackers/ files.
The rest of vc-fix (its command/agent/skill markdown) still resolves file
references as bare relative paths, which inherits the same undocumented-CWD
risk described above for any tool call the model issues at runtime โ that's a
broader /project-init-level concern tracked separately, not something this
one skill's file layout can fix on its own.
Consumers
commands/qa-fix.md (Gate 1 routing, Gate 1b provenance, Phase 5 PR delivery, Phase 6 CI-check-contract-by-ownership)commands/project-init.md / skills/project-init/*.mjs (writes project-profile.json that repoOwnership/contributionPlan read)agents/fullstack-backend.md, agents/fullstack-frontend.md (checkout + repo profile for the fix)
