workspai 0.43.0

package/docs/policies.workspace.example.yml

@@ -0,0 +1,23 @@
+version: "1.0"
+mode: warn # "warn" or "strict"
+dependency_sharing_mode: isolated # "isolated" or "shared-runtime-caches" or "shared-node-deps"
+# change profile (recommended): npx workspai bootstrap --profile polyglot
+# change mode/dependency manually: edit this file and rerun npx workspai init
+
+rules:
+  enforce_workspace_marker: true
+  enforce_toolchain_lock: false
+  disallow_untrusted_tool_sources: false
+  enforce_compatibility_matrix: false
+  require_mirror_lock_for_offline: true
+
+# preferred policy management commands:
+# npx workspai workspace policy show
+# npx workspai workspace policy set mode strict
+# npx workspai workspace policy set dependency_sharing_mode shared-runtime-caches
+# npx workspai workspace policy set rules.enforce_toolchain_lock true
+
+# dependency_sharing_mode options:
+# - isolated               (default, safest)
+# - shared-runtime-caches  (share Node/Python/Go caches at workspace level)
+# - shared-node-deps       (compat alias for Node shared mode)

package/docs/workspace-operations.md

@@ -0,0 +1,160 @@
+# Workspace Operations
+
+Behavioral guide for import, adoption, snapshots, archives, contracts, collaboration bundles, and local infra sidecars.
+
+Command syntax: [commands-reference.md](./commands-reference.md).
+
+## Import and adoption
+
+Use `import` to copy or clone an existing project into a Workspai workspace.
+Use `adopt` when the project must stay where it already lives but should become visible to RapidKit and Workspai workspace intelligence.
+
+```bash
+npx workspai import ../orders-api
+npx workspai import https://github.com/acme/orders-api.git --git
+npx workspai import ../orders-api --workspace ./my-workspace --name orders-api --json
+npx workspai adopt ../marketing-web --workspace ./my-workspace
+npx workspai adopt --json
+```
+
+### Import behavior
+
+- Local folders are copied; git sources are cloned with shallow history.
+- Outside any workspace (no `--workspace`), Workspai auto-creates/reuses the managed workspace at `~/.workspai/workspaces/workspai`.
+- Existing workspaces under `~/rapidkit/workspaces/*` and `~/Workspai/rapidkits/*` remain registered after upgrade.
+- CLI prints a next-step `cd ...` hint (`suggestedCdCommand` in JSON mode).
+- Failed workspace sync rolls back imported files and registry entries.
+
+### Adopt behavior
+
+- Source files are not moved or copied.
+- Default workspace resolution matches import (`workspai` under `~/.workspai/workspaces/`).
+- Writes `.workspai/project.json`, `.workspai/adopt.json`, and `.workspai/adopt-readiness.json`.
+- Registry and contract sync include adopted projects for `workspace model`, `workspace context`, Dashboard, and agents.
+- `--dry-run --json` previews detection without writing metadata.
+
+### JSON output (`--json`)
+
+- `workspacePath`, `workspaceResolution` (`explicit` | `nearest` | `default-auto`)
+- `defaultWorkspaceCreated`, `suggestedCdCommand`
+- `importedProject` or `adoptedProject` (`name`, `path`, `stack`, `runtime`, `framework`, `supportTier`, `moduleSupport`, `confidence`, `source`)
+
+Imported projects receive `.workspai/import-readiness.json`. Adopted projects add frontend-aware detection for Next.js, React, Vite, Vue, Angular, SvelteKit, Nuxt, Astro, Remix, and Solid.
+
+## Workspace snapshots and safe project operations
+
+```bash
+npx workspai snapshot create before-upgrade --reason "before dependency upgrade"
+npx workspai snapshot list
+npx workspai snapshot inspect before-upgrade
+npx workspai snapshot restore before-upgrade --dry-run
+npx workspai snapshot restore before-upgrade --force
+```
+
+Project delete is safe-by-default:
+
+```bash
+npx workspai project archive orders-api --reason "replaced by orders-v2"
+npx workspai project archives
+npx workspai project restore orders-api
+npx workspai project delete orders-api
+npx workspai project delete orders-api --permanent --confirm orders-api
+```
+
+Lifecycle safety:
+
+- `project delete` archives by default; permanent removal requires `--permanent --confirm <exact-name>`.
+- `snapshot restore` requires `--force` unless dry-run.
+- Restore, archive, and permanent delete create pre-operation metadata snapshots.
+- Archive manifests live under `.workspai/archive/projects`.
+- Audit records append to `.workspai/audit/events.jsonl`.
+- Workspace policy can require reasons, safety snapshots, or block permanent delete via `.workspai/policies.yml`.
+
+## Workspace collaboration bundle
+
+```bash
+npx workspai workspace share
+npx workspai workspace share --output ./team-share.json
+npx workspai workspace share --include-paths
+npx workspai workspace share --no-doctor
+```
+
+Bundle includes workspace metadata, discovered projects, report index, and latest doctor evidence (unless `--no-doctor`). `--include-paths` is for internal teams only (absolute paths).
+
+## Workspace contract registry
+
+```bash
+npx workspai workspace contract init
+npx workspai workspace contract inspect
+npx workspai workspace contract verify --strict
+npx workspai workspace contract graph
+```
+
+Contract file: `.workspai/workspace.contract.json`. Verification checks schema, duplicate slugs, port collisions, and unknown dependencies.
+
+Workspai keeps the contract alive during `create project` and `workspace sync` without overwriting manual API/event/owner declarations.
+
+## Portable workspace archives
+
+```bash
+npx workspai workspace export --output team-workspace.workspai-archive.zip
+npx workspai workspace archive inspect team-workspace.workspai-archive.zip
+npx workspai workspace archive verify team-workspace.workspai-archive.zip --strict
+npx workspai workspace archive doctor team-workspace.workspai-archive.zip
+npx workspai workspace hydrate team-workspace.workspai-archive.zip --output ./team-workspace
+```
+
+Export excludes dependency folders, build output, git history, logs, `.env`, and private keys by default. Use `--include-env` only for trusted internal handoffs. Hydrate accepts legacy `.rapidkit-workspace` and `.rapidkit/*` archive entries, but restores them as canonical `.workspai-workspace` and `.workspai/*` paths.
+
+## Workspace infrastructure (sidecar)
+
+Discovery sources: Core module slugs, project `.env.example`, workspace contract env, and `.workspai/infra/overrides.json`.
+
+```bash
+cd my-workspace
+npx workspai infra plan
+npx workspai infra up
+npx workspai infra status --strict
+npx workspai infra down
+```
+
+Artifacts:
+
+- `.workspai/infra/docker-compose.yml`
+- `.workspai/reports/infra-plan.json`
+- `.workspai/infra/.env.example`
+
+## Command ownership
+
+| Command family                                              | Owner                  | Notes                                              |
+| ----------------------------------------------------------- | ---------------------- | -------------------------------------------------- |
+| `create workspace`, `workspace`, `cache`, `mirror`, `infra` | Workspai CLI           | Platform orchestration                             |
+| `init`                                                      | Wrapper orchestrated   | Project init; full-init alias at workspace root    |
+| `dev`, `test`, `build`, `start`                             | Runtime aware          | Delegates to active project/runtime                |
+| `readiness`                                                 | Wrapper release gate   | Env + doctor + analyze + verify + dependency gates |
+| `pipeline`                                                  | Wrapper orchestrator   | sync → doctor → analyze → readiness → autopilot    |
+| `autopilot release`                                         | Wrapper orchestrator   | End-to-end release gate evidence                   |
+| `import`                                                    | Workspace ingestion    | Rollback-safe sync                                 |
+| `adopt`                                                     | Workspace adoption     | In-place linking + registry sync                   |
+| `workspace model/context/diff/impact/verify`                | Workspace intelligence | Model, context packs, blast radius                 |
+| `snapshot`                                                  | Workspace recovery     | Metadata or full snapshots                         |
+| `project archive/restore/delete`                            | Project lifecycle      | Safe delete with confirmation                      |
+| `doctor` / `doctor workspace` / `doctor project`            | Wrapper health         | Host, workspace, and project scopes                |
+| `workspace run`                                             | Workspace orchestrator | Fleet stage execution                              |
+| `infra`                                                     | Workspace sidecar      | Contract-driven local dependencies                 |
+
+## Verification evidence freshness
+
+`workspace verify` treats evidence as release-gate material, not just as a file
+presence check. Required project evidence must match the affected project in
+`workspace-run-last.json`, and evidence generated before the current impact
+report is treated as stale and blocking. Re-run the recommended commands from
+`workspace impact --json` before using `workspace verify --strict` in CI.
+
+For doctor CI exit codes and JSON evidence fields, see [doctor-command.md](./doctor-command.md).
+
+## See also
+
+- [Documentation index](./README.md)
+- [commands-reference.md](./commands-reference.md)
+- [doctor-command.md](./doctor-command.md)

package/docs/workspace-run.md

@@ -0,0 +1,104 @@
+# Workspace Run — Polyglot Fleet Orchestration
+
+`workspace run` executes CI-safe stages (`init`, `test`, `build`, `start`) across discovered projects in a workspace. Command syntax is in [commands-reference.md](./commands-reference.md).
+
+## Quick start
+
+```bash
+npx workspai workspace run test --parallel
+npx workspai workspace run test --affected --since HEAD~1
+npx workspai workspace run test --affected --blast-radius
+npx workspai workspace run build --json --max-workers 8
+```
+
+`--blast-radius` uses `.workspai/workspace.contract.json` (and legacy `.rapidkit/workspace-dependency-graph.json` as fallback) to expand direct `dependsOn` and publish/consume event relationships.
+
+## Supported runtimes
+
+| Runtime | Frameworks | Status |
+| --- | --- | --- |
+| Node | NestJS, Express, Next.js, Nuxt | Built-in |
+| Go | Fiber, Gin, Echo, Chi | Built-in |
+| Java | Spring Boot, Quarkus, Gradle | Built-in |
+| Python | FastAPI, Django, Flask, Poetry | Built-in |
+| PHP | Laravel, Symfony, Slim | Observed |
+| Rust | Actix, Axum, Rocket, Tokio | Observed |
+| .NET | ASP.NET Core, Entity Framework | Built-in |
+| Elixir | Phoenix, Umbrella | Observed |
+| Ruby | Rails, Sinatra, RSpec | Observed |
+
+Public scaffold/import/lifecycle contract: [contracts/RUNTIME_SUPPORT_MATRIX.md](./contracts/RUNTIME_SUPPORT_MATRIX.md).
+
+## Enterprise configuration
+
+Override stage commands per project via `.workspai/context.json`:
+
+```json
+{
+  "runtime": "php",
+  "framework": "Laravel",
+  "commands": {
+    "test": "php artisan test --parallel=4",
+    "build": "php artisan config:cache && php artisan route:cache",
+    "lint": "php bin/phpstan analyse --level=8"
+  },
+  "environment": "dev"
+}
+```
+
+Enterprise features include command overrides, multi-framework projects, error categorization (setup vs test vs runtime), preflight validation, health checks, custom stages (via `.workspai/context.json` `commands`), stage dependencies (from framework registry), environment variants, result caching (`--reuse-passed`), and composite steps.
+
+### Custom stages
+
+Declare extra fleet stages in `.workspai/context.json`:
+
+```json
+{
+  "commands": {
+    "lint": "php bin/phpstan analyse --level=8"
+  }
+}
+```
+
+Run them with `npx workspai workspace run lint --scope project:<name>`.
+
+### Stage dependencies and caching
+
+Framework registry entries may declare `dependencies` (for example `start` depends on `build`). When `.workspai/reports/workspace-run-last.json` exists, projects skip until dependency stages show `passed`.
+
+Use `--reuse-passed` to skip projects that already passed the requested stage in the cached report:
+
+```bash
+npx workspai workspace run test --reuse-passed --json
+```
+
+## JSON reporting
+
+```bash
+npx workspai workspace run test --json > test-results.json
+cat test-results.json | jq '.projects[] | {path, status, errorCategory}'
+```
+
+`errorCategory` values: `setup`, `test-failure`, `runtime`, `dependency`, `timeout`.
+
+## Command semantics
+
+Workspai has two workspace-level execution surfaces and three equivalent full-init aliases at workspace root:
+
+| Command | Intent | Scope |
+| --- | --- | --- |
+| `init`, `workspace init`, `workspace run init` (at workspace root) | Mirrored full-init (workspace deps + project init) | Workspace + fleet |
+| `workspace run <test\|build\|start>` | Fleet stage execution | Selected projects |
+| `init`, `test`, `build`, `start`, `dev` (inside project dir) | Project primitive | Single project |
+
+At workspace root, `npx workspai init`, `npx workspai workspace init`, and `npx workspai workspace run init` are equivalent aliases.
+
+Inside a project directory, `npx workspai init` remains project-scoped.
+
+`dev` is excluded from `workspace run` — it is a long-running local process, not a CI batch stage.
+
+## See also
+
+- [Documentation index](./README.md)
+- [commands-reference.md](./commands-reference.md)
+- [contracts/RUNTIME_SUPPORT_MATRIX.md](./contracts/RUNTIME_SUPPORT_MATRIX.md)

package/package.json

@@ -0,0 +1,179 @@
+{
+  "name": "workspai",
+  "version": "0.43.0",
+  "type": "module",
+  "description": "Open-source workspace intelligence CLI for software systems: create, adopt, govern, verify, and align polyglot workspaces for humans, CI, IDEs, and AI agents.",
+  "keywords": [
+    "rapidkit",
+    "workspai",
+    "ai",
+    "cli",
+    "create",
+    "workspace",
+    "workspace-intelligence",
+    "governance",
+    "backend",
+    "frontend",
+    "fastapi",
+    "nestjs",
+    "nextjs",
+    "react",
+    "springboot",
+    "spring",
+    "gofiber",
+    "gogin",
+    "microservices",
+    "api",
+    "generator",
+    "scaffold"
+  ],
+  "author": "RapidKit Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rapidkitlabs/workspai.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "workspai": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "contracts",
+    "docs",
+    "templates",
+    "workspai.config.example.cjs",
+    "rapidkit.config.example.cjs",
+    "data/modules-embeddings.json",
+    "scripts/enforce-package-manager.cjs",
+    "scripts/check-cli-resolution.cjs",
+    "scripts/check-agent-customization-drift.mjs",
+    "scripts/enterprise-package-smoke.mjs",
+    "scripts/prepack-enterprise.mjs"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "preinstall": "node scripts/enforce-package-manager.cjs",
+    "postinstall": "node scripts/check-cli-resolution.cjs",
+    "sync-kits": "bash scripts/sync-kits.sh",
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "dev": "tsup --watch",
+    "dev:local": "corepack npm run build && corepack npm link",
+    "install:local": "corepack npm unlink -g workspai || true && corepack npm run build && corepack npm link",
+    "uninstall:local": "corepack npm unlink -g workspai || true",
+    "prepare": "node scripts/prepare-husky.mjs",
+    "test:e2e:first-install": "bash scripts/e2e-first-install.sh",
+    "test:e2e:user-first-install": "bash scripts/e2e-user-first-install.sh",
+    "test": "vitest run",
+    "test:drift": "node scripts/run-drift-guard.mjs",
+    "benchmark:intelligence": "vitest run src/__tests__/workspace-intelligence-benchmark.test.ts",
+    "sync:shared-contracts": "node scripts/sync-shared-contracts.mjs",
+    "check:shared-contracts": "node scripts/sync-shared-contracts.mjs --check",
+    "sync:parity-snapshot": "node scripts/sync-shared-contracts.mjs",
+    "check:parity-snapshot": "node scripts/sync-shared-contracts.mjs --check",
+    "generate:contracts": "node scripts/generate-shared-contracts.mjs",
+    "check:generated-contracts": "node scripts/generate-shared-contracts.mjs --check",
+    "check:agent-customization-drift": "node scripts/check-agent-customization-drift.mjs",
+    "validate:contracts": "corepack npm run check:shared-contracts && vitest run src/__tests__/contracts/",
+    "test:parity-contract": "corepack npm run check:shared-contracts && vitest run src/__tests__/contracts/import-stack-parity.snapshot.test.ts",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:prepare-embeddings": "node scripts/prepare-mock-embeddings.mjs",
+    "generate-embeddings": "npx tsx src/ai/generate-embeddings.ts",
+    "verify:package-cli": "node scripts/verify-package-cli.mjs",
+    "smoke:enterprise-package": "node scripts/enterprise-package-smoke.mjs",
+    "prepack": "node scripts/prepack-enterprise.mjs",
+    "test:e2e": "vitest run src/__tests__/e2e.test.ts",
+    "test:scenarios": "node scripts/run-scenario-matrix-local.mjs",
+    "test:scenarios:full": "node scripts/run-scenario-matrix-local.mjs --full",
+    "test:scenarios:docker": "bash scripts/scenario-matrix.sh",
+    "test:runtime-matrix": "node scripts/runtime-acceptance-matrix.mjs",
+    "test:runtime-matrix:full": "node scripts/runtime-acceptance-matrix.mjs --full",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "validate": "corepack npm run typecheck && corepack npm run lint && corepack npm run format:check && corepack npm test",
+    "security": "npm audit --audit-level=moderate",
+    "security:fix": "npm audit fix",
+    "metrics": "npx tsx scripts/metrics.ts",
+    "validate:docs-examples": "node scripts/validate-doc-examples.mjs",
+    "check:markdown-links": "node scripts/check-markdown-links.mjs",
+    "check:docs-drift": "node scripts/docs-drift-guard.mjs",
+    "smoke:readme": "node scripts/smoke-readme-commands.mjs",
+    "validate:docs": "corepack npm run check:markdown-links && corepack npm run check:docs-drift && corepack npm run validate:docs-examples && corepack npm run smoke:readme",
+    "smoke:frontend-generators": "tsup && node scripts/smoke-frontend-generators.mjs",
+    "smoke:frontend-generators:network": "tsup && node scripts/smoke-frontend-generators.mjs --execute",
+    "sync:contracts": "node scripts/sync-contracts.mjs",
+    "check:contracts": "node scripts/sync-contracts.mjs --check",
+    "bundle-size": "corepack npm run build && node scripts/report-dist-size.mjs",
+    "analyze": "corepack npm run build && node scripts/analyze-dist.mjs",
+    "size-check": "corepack npm run build && size-limit",
+    "bench": "npx tsx scripts/benchmarks.ts",
+    "quality": "corepack npm run typecheck && corepack npm run lint && corepack npm run format:check && corepack npm test && corepack npm run size-check && corepack npm run security && corepack npm run validate:docs && corepack npm run smoke:frontend-generators && corepack npm run check:contracts && corepack npm run check:shared-contracts && corepack npm run check:parity-snapshot && corepack npm run check:agent-customization-drift",
+    "act-matrix": "act -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-22.04 -P macos-latest=ghcr.io/catthehacker/ubuntu:act-22.04 -P windows-latest=ghcr.io/catthehacker/ubuntu:act-22.04 --pull=false -j build-test-matrix",
+    "release:dry": "bash scripts/release.sh --no-publish --yes --allow-dirty",
+    "release:patch": "bash scripts/release.sh patch",
+    "release:minor": "bash scripts/release.sh minor",
+    "release:major": "bash scripts/release.sh major"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "chalk": "^5.3.0",
+    "cli-progress": "^3.12.0",
+    "commander": "^12.1.0",
+    "execa": "^9.3.1",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^13.2.2",
+    "nunjucks": "^3.2.4",
+    "openai": "^6.22.0",
+    "ora": "^8.0.1",
+    "validate-npm-package-name": "^5.0.1"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.3",
+    "@size-limit/preset-big-lib": "^12.0.0",
+    "@types/cli-progress": "^3.11.6",
+    "@types/fs-extra": "^11.0.4",
+    "@types/inquirer": "^9.0.7",
+    "@types/node": "^20.14.0",
+    "@types/nunjucks": "^3.2.6",
+    "@types/validate-npm-package-name": "^4.0.2",
+    "@typescript-eslint/eslint-plugin": "^8.46.2",
+    "@typescript-eslint/parser": "^8.46.2",
+    "@vitest/coverage-v8": "^4.0.15",
+    "@vitest/ui": "^4.0.15",
+    "eslint": "^9.39.2",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.5.2",
+    "prettier": "^3.6.2",
+    "size-limit": "^12.0.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.5.0",
+    "vite-bundle-visualizer": "^1.2.1",
+    "vitest": "^4.0.15"
+  },
+  "optionalDependencies": {
+    "@rollup/rollup-win32-x64-msvc": "*"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  },
+  "overrides": {
+    "minimatch": "^10.2.1",
+    "esbuild": "^0.28.1"
+  },
+  "packageManager": "npm@10.8.2"
+}

package/rapidkit.config.example.cjs

@@ -0,0 +1,62 @@
+/**
+ * Legacy RapidKit Configuration File
+ *
+ * New Workspai projects should prefer workspai.config.cjs or workspai.config.mjs.
+ * This legacy filename remains supported as a fallback during migration.
+ *
+ * Place this file in your project root as:
+ * - rapidkit.config.cjs (CommonJS explicit, safest across package types)
+ * - rapidkit.config.mjs (ES Module, use export default)
+ * - rapidkit.config.js (only when it matches your package.json module type)
+ *
+ * This file is automatically detected when creating workspaces or projects.
+ * CLI arguments override config file settings.
+ */
+
+module.exports = {
+  // Workspace configuration
+  workspace: {
+    // Default author name for new workspaces
+    defaultAuthor: 'Your Name or Team',
+
+    // Default Python version to use
+    // Options: '3.10' | '3.11' | '3.12'
+    pythonVersion: '3.10',
+
+    // Default installation method for RapidKit Core
+    // Options: 'poetry' | 'venv' | 'pipx'
+    installMethod: 'poetry',
+  },
+
+  // Project configuration
+  projects: {
+    // Default kit/template to use when creating projects
+    // Examples: 'fastapi.standard', 'fastapi.ddd', 'nestjs.standard'
+    defaultKit: 'fastapi.standard',
+
+    // Default modules to add to new projects
+    // These modules will be automatically added after project creation
+    addDefaultModules: [
+      // 'prisma',          // Database ORM
+      // 'redis',           // Caching
+      // 'auth-jwt',        // JWT Authentication
+      // 'monitoring',      // Monitoring and logging
+    ],
+
+    // Skip git initialization by default
+    skipGit: false,
+
+    // Skip dependency installation by default
+    skipInstall: false,
+  },
+};
+
+// Example usage:
+// npx workspai my-workspace
+// -> Uses config: author='Your Name or Team', pythonVersion='3.10', installMethod='poetry'
+//
+// npx workspai my-workspace --author "Different Author"
+// -> Overrides: author='Different Author', but still uses pythonVersion='3.10', installMethod='poetry'
+//
+// npx workspai create project my-api
+// -> Uses config: defaultKit='fastapi.standard', adds default modules

package/scripts/check-agent-customization-drift.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+const GENERATED_AGENT_PATHS = [
+  '.workspai/reports/INDEX.json',
+  '.workspai/reports/agent-customization-pack.json',
+  '.workspai/reports/workspai-mcp-design.json',
+  '.workspai/reports/workspace-context-agent.json',
+  '.workspai/reports/workspace-skills-index.json',
+  '.workspai/skills',
+  '.workspai/AGENT-GROUNDING.md',
+  'AGENTS.md',
+  'CLAUDE.md',
+  '.github/copilot-instructions.md',
+  '.github/instructions',
+  '.github/prompts',
+  '.github/skills/workspai-grounding',
+  '.github/skills/workspai-workspace-intelligence',
+  '.github/agents',
+  '.cursor/rules/workspai-grounding.mdc',
+  '.claude/rules/workspai-evidence.md',
+  '.claude/rules/rapidkit-evidence.md',
+  '.vscode/workspai-agent-hooks.json',
+];
+
+function parseWorkspaceArg(argv) {
+  const workspaceIndex = argv.indexOf('--workspace');
+  if (workspaceIndex >= 0 && argv[workspaceIndex + 1]) {
+    return argv[workspaceIndex + 1];
+  }
+  const inline = argv.find((arg) => arg.startsWith('--workspace='));
+  if (inline) {
+    return inline.slice('--workspace='.length);
+  }
+  return process.cwd();
+}
+
+function runGit(workspacePath, args) {
+  return spawnSync('git', ['-C', workspacePath, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+const workspacePath = path.resolve(parseWorkspaceArg(process.argv.slice(2)));
+const gitCheck = runGit(workspacePath, ['rev-parse', '--is-inside-work-tree']);
+
+if (gitCheck.status !== 0 || gitCheck.stdout.trim() !== 'true') {
+  console.warn(
+    `[workspai] Agent customization drift check skipped: ${workspacePath} is not a git work tree.`
+  );
+  process.exit(0);
+}
+
+const status = runGit(workspacePath, ['status', '--porcelain', '--', ...GENERATED_AGENT_PATHS]);
+
+if (status.status !== 0) {
+  console.error('[workspai] Failed to inspect generated agent customization drift.');
+  if (status.stderr.trim()) {
+    console.error(status.stderr.trim());
+  }
+  process.exit(status.status ?? 1);
+}
+
+const drift = status.stdout.trim();
+
+if (drift.length > 0) {
+  console.error('[workspai] Agent customization drift detected.');
+  console.error(
+    'Run `npx workspai workspace agent-sync --write --refresh-context --preset enterprise`, review the generated files, and commit the changes.'
+  );
+  console.error('');
+  console.error(drift);
+  process.exit(1);
+}
+
+console.log('[workspai] Agent customization files are in sync.');