V48 (specification-implementation): VCS hierarchy as vcs-generics + generic-vcs/*

Reorganize VCS like measurements/pipelines: packages/vcs-generics holds
AbstractVCSProvider primitives; packages/generic-vcs/{github,gitlab,bitbucket,git}
hold provider implementations. Keep @bitcode/vcs|github|gitlab|bitbucket|git as
compatibility re-exports. Wire workspaces, tsconfig, factory lazy-loads, and docs.

Author: geraldarthurdavis

BITCODE_SPEC_V48_NOTES.md

@@ -1584,3 +1584,18 @@ Prepared catalogs (`ASSET_PACK_ABSOLUTES_CATALOG`, lens catalogs) live in
 `@bitcode/asset-packs-synthesis`. `agent-generics` re-exports measure factories
 for compatibility; prefer package-direct imports in new code.
 
+## VCS hierarchy modularization (Garrett, 2026-07-13)
+
+```
+@bitcode/vcs-generics                      # packages/vcs-generics (was packages/vcs)
+  → @bitcode/generic-vcs-github            # packages/generic-vcs/github
+  → @bitcode/generic-vcs-gitlab
+  → @bitcode/generic-vcs-bitbucket
+  → @bitcode/generic-vcs-git               # Git operation bridge
+```
+
+Compatibility shims remain at `@bitcode/vcs`, `@bitcode/github`, `@bitcode/gitlab`,
+`@bitcode/bitbucket`, `@bitcode/git`. Prefer hierarchy package names in new code.
+`generic-tools/vcs` and `generic-agents-vcs` are tools/agents over the VCS layer,
+not provider packages.
+

FAMILIARIZATION.md

@@ -173,6 +173,20 @@ inside `agent-generics` until inverted onto pure Execution + LLM registry.
 
 Factories: `factoryAgent`, `factoryAgentWithPTRR` in `agent-generics`.
 
+### 3.2.0 VCS
+
+```
+@bitcode/vcs-generics                      VCS primitives (AbstractVCSProvider, factory, service)
+        ↑
+@bitcode/generic-vcs-{github|gitlab|bitbucket}   Provider implementations
+@bitcode/generic-vcs-git                   Git-shaped bridge over providers
+        ↑
+@bitcode/generic-tools-vcs / generic-agents-vcs   Tools + agent over VCS
+```
+
+Package paths: `packages/vcs-generics/`, `packages/generic-vcs/*`.
+Compatibility shims: `@bitcode/vcs`, `@bitcode/github`, …
+
 ### 3.2 Tools
 
 ```
@@ -346,7 +360,11 @@ public entries remain stable (`./deposit-asset-pack-options`, `./depository-sear
 | --- | --- |
 | `auth` | Wallet local identity, Bitcoin wallet client, OAuth provider, Supabase auth redirect, QA telemetry |
 | `github` / `gitlab` / `bitbucket` | VCS providers |
-| `vcs` + `generic-tools/vcs` | VCS abstraction + tools |
+| `vcs-generics` | VCS primitives (`AbstractVCSProvider`, factory, service) |
+| `generic-vcs-github` / `-gitlab` / `-bitbucket` | Nested provider implementations |
+| `generic-vcs-git` | Git operation bridge over providers |
+| `vcs` / `github` / … | BC re-exports of vcs-generics / generic-vcs-* |
+| `generic-tools/vcs` + `generic-agents-vcs` | VCS tools and agent (not providers) |
 | `git` | Git operation bridge |
 | `supabase` | Supabase clients |
 | `notion`, `figma`, `jira`, `circleci`, … | External service adapters |

internal-docs/BITCODE_SOURCE_LAYOUT.md

@@ -210,6 +210,8 @@ packages/generic-<family>/          # README only (no package.json)
 | `generic-llms/` | `xAI/`, `OpenAI/`, `Anthropic/`, `Google/`, `defaults/`, `registry/` | `@bitcode/generic-llms-*` (+ aggregator `@bitcode/generic-llms`) |
 | `generic-generations/` | `failsafes/`, `thinkings/` | `@bitcode/generic-generations-failsafes`, `-thinkings` |
 | `generic-measurements/` | `measure-agent/`, `absolutes/`, `needinesses/` | `@bitcode/generic-measurements-*` |
+| `generic-vcs/` | `github/`, `gitlab/`, `bitbucket/`, `git/` | `@bitcode/generic-vcs-*` |
+| `vcs-generics/` | (package root) | `@bitcode/vcs-generics` |
 | `asset-packs/` | `synthesis/`, `settle/` | `@bitcode/asset-packs-synthesis`, `-settle` |
 | `generic-doc-comment-plugins/` | `doc-developing/` | `@bitcode/doc-comment-developing` |
 

package.json

@@ -15,6 +15,7 @@
     "packages/generic-llms/*",
     "packages/generic-generations/*",
     "packages/generic-measurements/*",
+    "packages/generic-vcs/*",
     "packages/asset-packs/*",
     "packages/generic-doc-comment-plugins/*",
     "packages/pipelines/*",

packages/bitbucket/package.json

@@ -1,25 +1,11 @@
 {
   "name": "@bitcode/bitbucket",
   "version": "1.0.0",
-  "description": "Bitbucket provider implementation, OAuth, and MCP tools",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "test": "jest",
-    "test:coverage": "jest --coverage",
-    "test:watch": "jest --watch",
-    "type-check": "tsc --noEmit"
-  },
+  "description": "Compatibility re-export of @bitcode/generic-vcs-bitbucket",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": { ".": "./src/index.ts" },
   "dependencies": {
-    "@bitcode/vcs": "workspace:*",
-    "@bitcode/logger": "workspace:*",
-    "@bitcode/supabase": "workspace:*"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.5.0",
-    "jest": "^29.5.0",
-    "ts-jest": "^29.1.0",
-    "typescript": "^5.0.0"
+    "@bitcode/generic-vcs-bitbucket": "workspace:*"
   }
-}
+}

packages/bitbucket/src/index.ts

@@ -1,21 +1,6 @@
 /**
- * Bitbucket - Bitbucket VCS provider implementation
- * 
- * Provides Bitbucket integration via the unified VCS abstraction.
- * Clean provider export without former dependency seams.
- * 
- * @doc-package
- * version: 1.0.0
- * pattern: vcs-provider
- * philosophy: "One provider, clean interface"
+ * @deprecated Prefer `@bitcode/generic-vcs-bitbucket`.
+ * Compatibility re-export of packages/generic-vcs/bitbucket.
  */
-
-import BitbucketProvider from './providers/bitbucket-provider';
-export { BitbucketAuth } from './auth';
-export { BitbucketConnections } from './connections';
-
-// Export the provider class for direct usage
-export { BitbucketProvider };
-
-// Default export for VCS factory pattern
-export default BitbucketProvider;
+export * from '@bitcode/generic-vcs-bitbucket';
+export { default } from '@bitcode/generic-vcs-bitbucket';

packages/generic-vcs/README.md

@@ -0,0 +1,29 @@
+# generic-vcs
+
+Nested VCS **provider** implementations of `@bitcode/vcs-generics` primitives.
+
+## Hierarchy
+
+```
+@bitcode/vcs-generics                 # types, AbstractVCSProvider, factory, service, cache
+        ↑
+@bitcode/generic-vcs-github           # github/
+@bitcode/generic-vcs-gitlab           # gitlab/
+@bitcode/generic-vcs-bitbucket        # bitbucket/
+@bitcode/generic-vcs-git              # git/  (operation bridge over providers)
+```
+
+## Packages
+
+| Path | Package | Role |
+| --- | --- | --- |
+| `github/` | `@bitcode/generic-vcs-github` | GitHub provider (+ App auth) |
+| `gitlab/` | `@bitcode/generic-vcs-gitlab` | GitLab provider |
+| `bitbucket/` | `@bitcode/generic-vcs-bitbucket` | Bitbucket provider |
+| `git/` | `@bitcode/generic-vcs-git` | Git-shaped operation bridge via VCS providers |
+
+Compatibility shims at `packages/{github,gitlab,bitbucket,git,vcs}/` re-export the
+new package names (`@bitcode/github`, `@bitcode/vcs`, …). Prefer hierarchy package names in new code.
+
+Related (not providers): `@bitcode/generic-tools-vcs` / `@bitcode/generic-agents-vcs`
+are tools/agents over the VCS layer, not provider implementations.

packages/bitbucket/README.md packages/generic-vcs/bitbucket/README.mdpackages/bitbucket/README.md renamed to packages/generic-vcs/bitbucket/README.md

@@ -1,5 +1,5 @@
 const path = require('path');
-const { createJestConfig } = require('../../jest.base.cjs');
+const { createJestConfig } = require('../../../jest.base.cjs');
 
 module.exports = createJestConfig(__dirname, {
   collectCoverageFrom: ['src/**/*.{ts,tsx}', '!src/**/*.d.ts'],