@codapult/guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codapult
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,290 @@
+# @codapult/guard
+
+[![CI](https://github.com/codapult/codapult-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/codapult/codapult-guard/actions/workflows/ci.yml)
+[![Fixtures](https://github.com/codapult/codapult-guard/actions/workflows/guard-fixtures.yml/badge.svg)](https://github.com/codapult/codapult-guard/actions/workflows/guard-fixtures.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js >=20.19](https://img.shields.io/badge/node-%3E%3D20.19-339933.svg?logo=node.js&logoColor=white)](package.json)
+[![TypeScript](https://img.shields.io/badge/TypeScript-first-3178C6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+## Architecture guardrails for AI coding agents
+
+`@codapult/guard` is a local-first, model-agnostic architecture guard for JavaScript and
+TypeScript projects.
+
+It learns what already exists, records the project’s architectural memory, and protects future
+changes from introducing regressions.
+
+> **Guard does not tell every project to use the same architecture.**
+> It discovers the architecture that is already there, then lets the team decide what becomes policy.
+
+The core is universal. The strongest first-class scenarios are Next.js SaaS and AI-assisted
+development, including server/client boundaries, routes, persistence, authentication, billing,
+background jobs, environment configuration, and AI integrations.
+
+## Part of the Codapult ecosystem
+
+Guard is an independent open-source project from [Codapult](https://codapult.dev). It does not
+require Codapult and can be installed in any JavaScript or TypeScript repository.
+
+The relationship is complementary:
+
+| Project               | Role                                                                                     |
+| --------------------- | ---------------------------------------------------------------------------------------- |
+| **`@codapult/guard`** | Universal architecture guardrails, project memory, contracts, MCP, and AI-agent context. |
+| **`@codapult/cli`**   | Codapult SaaS project CLI that includes Guard through a thin adapter.                    |
+| **Codapult**          | Full-source Next.js SaaS foundation with conventions Guard can discover and protect.     |
+
+Use standalone Guard for any compatible project. Use the Codapult CLI when working on a Codapult
+SaaS project and you want project management, database, plugins, deployment, MCP, and Guard in one
+CLI.
+
+```text
+        Existing project
+              │
+              ▼
+       deterministic discovery
+     AST · files · imports · Git
+              │
+              ▼
+        project architecture
+  capabilities · graph · impact paths
+              │
+              ▼
+       approved project policy
+  rules · contracts · conventions · baseline
+              │
+              ▼
+          change verification
+   check · review packet · verify · CI
+```
+
+## Why Guard exists
+
+AI agents can produce syntactically valid code that still violates the architecture of a real
+project: a client component imports server-only code, a new action bypasses the established auth
+boundary, a route writes to the database directly, or a change duplicates a service that already
+exists.
+
+Existing tools remain essential, but they solve different problems:
+
+| Tool category              | Primary question                                   | Guard’s relationship                                                  |
+| -------------------------- | -------------------------------------------------- | --------------------------------------------------------------------- |
+| TypeScript                 | Is the code type-correct?                          | Uses the project’s typecheck as an optional gate.                     |
+| ESLint / Biome             | Does code follow language and style rules?         | Does not duplicate their lint rules.                                  |
+| Tests                      | Does behavior match executable expectations?       | Runs configured checks when enabled; does not replace tests.          |
+| SAST / dependency scanners | Is there a known security or dependency risk?      | Can connect adapters; focuses on architecture and change impact.      |
+| PR review services         | What semantic concerns should a reviewer consider? | Produces a bounded, redacted review packet for the selected AI host.  |
+| **Guard**                  | Is the project becoming architecturally worse?     | Maintains project-specific architectural memory and regression gates. |
+
+## Install
+
+Requirements: Node.js `>=20.19` and a JavaScript or TypeScript project.
+
+```bash
+pnpm add -D @codapult/guard
+# or
+npm install --save-dev @codapult/guard
+```
+
+The package exposes the `codapult-guard` binary:
+
+```bash
+pnpm exec codapult-guard init
+```
+
+The npm package is scoped as `@codapult/guard`; the executable intentionally remains
+`codapult-guard` for discoverability and consistency with the standalone product name.
+
+## 60-second quick start
+
+Run from the project root:
+
+```bash
+# 1. Build the initial project model and baseline
+pnpm exec codapult-guard init
+
+# 2. Inspect only new and changed architecture findings
+pnpm exec codapult-guard check --changed
+
+# 3. Prepare deterministic context for an AI review
+pnpm exec codapult-guard review --requirement docs/acceptance.md
+
+# 4. Run the configured completion gate
+pnpm exec codapult-guard verify --json
+```
+
+`init` is protected and refuses to overwrite an existing baseline. Use `init --force` only when
+deliberately replacing the project memory. Use `analyze` to refresh discovered facts without
+resetting the baseline.
+
+## The operating model
+
+Guard separates facts, policy, verification, and decision:
+
+| Layer            | Contains                                                                           | How it is produced                             |
+| ---------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------- |
+| **Facts**        | AST, files, imports, dependencies, routes, calls, capabilities, graph, Git history | Deterministic local discovery                  |
+| **Policy**       | Rules, contracts, conventions, baseline                                            | Observed proposals plus explicit team approval |
+| **Verification** | Changed-file checks, impact analysis, contracts, project checks, review packet     | Local CLI, MCP, CI, and existing project tools |
+| **Decision**     | Pass, fail, warning, needs-review, not-configured                                  | Developer or AI host using Guard evidence      |
+
+Guard does not assume a fixed `UI → actions → services → repositories → database` architecture.
+It can discover that shape when the project exhibits it, but observed patterns become enforceable
+only after explicit approval.
+
+## What Guard discovers
+
+The model is framework-aware without being framework-dependent:
+
+| Area                    | Examples of discovered evidence                                                    |
+| ----------------------- | ---------------------------------------------------------------------------------- |
+| JavaScript / TypeScript | AST modules, declarations, calls, directives, aliases, re-exports, dynamic imports |
+| Next.js / React         | App Router routes, route methods, Server Actions, client/server boundaries         |
+| API boundaries          | Route handlers, API modules, entrypoints, impact paths                             |
+| Data                    | ORM packages, schemas, migrations, repositories, persistence boundaries            |
+| Capabilities            | Auth, payments, email, AI/RAG, queues, storage, cache, search, analytics, content  |
+| Operations              | Environment references, configs, deployment, observability, webhooks               |
+| Repository shape        | Workspaces, package scripts, dependencies, cycles, import hotspots, Git history    |
+| Testing                 | Test files, test scripts, workspace checks, changed files                          |
+
+Capabilities are evidence, not requirements. A Vite app, Express service, Hono project, Node
+package, monorepo, or Next.js SaaS can all use the same Guard core.
+
+## The normal loop
+
+```text
+init once → edit → check --changed → review → verify → commit / merge
+                         ↘ analyze after structural changes
+```
+
+1. `init` builds project memory and establishes the initial baseline.
+2. `check --changed` is the fast deterministic architecture gate.
+3. `review` prepares a bounded and redacted diff packet for an AI host; it does not call an LLM.
+4. `verify` runs Guard policy, configured project checks, adapters, runtime diagnostics, and
+   contract validation.
+5. `audit` inspects the complete current state, including findings accepted by the baseline.
+
+Guard state is stored in `.codapult/guard/`:
+
+```text
+.codapult/guard/
+├── project.json       discovered project model
+├── architecture.json  observed architecture and capabilities
+├── conventions.json   recurring project conventions
+├── rules.json         active and proposed deterministic rules
+├── contracts.json     project-specific boundaries and required calls
+├── proposals.json     evidence and approval history
+├── baseline.json      accepted pre-existing findings
+├── agent.json         AI-host completion-gate configuration
+└── history/           project snapshots for comparison
+```
+
+Commit policy and baseline files when the team wants shared guardrails. Treat cache artifacts as
+disposable according to the project’s policy, and never commit secrets.
+
+## AI agents and MCP
+
+Guard is deliberately model-agnostic. It does not send source code to a remote LLM and does not
+edit source files by itself. The AI host owns the model call, permissions, repair loop, and final
+decision.
+
+Start the standalone MCP server over stdio:
+
+```bash
+pnpm exec codapult-guard mcp-server
+```
+
+Recommended agent loop:
+
+```text
+task finished
+  → codapult_guard_context
+  → codapult_guard_review(requirement, diff)
+  → codapult_guard_verify
+  → repair reported failures
+  → repeat until pass or bounded iteration limit
+```
+
+For Cursor, Claude Code, Codex, Gemini CLI, GitHub Copilot, and generic hosts, see
+[`docs/integrations/`](docs/integrations/).
+
+## CI
+
+Copy the consumer workflow into a project that has installed and initialized Guard:
+
+```bash
+cp node_modules/@codapult/guard/docs/guard-ci.yml .github/workflows/guard.yml
+```
+
+Or copy it from [`docs/guard-ci.yml`](docs/guard-ci.yml). It runs project verification and exports
+Guard findings as SARIF for GitHub code scanning.
+
+The package repository separately runs its own unit, typecheck, build, and packaging checks in
+[`.github/workflows/ci.yml`](.github/workflows/ci.yml), while the fixture workflow tests Guard on
+real project shapes.
+
+## CLI surface
+
+| Command                    | Purpose                                                         |
+| -------------------------- | --------------------------------------------------------------- |
+| `init`                     | Create project memory and the initial baseline.                 |
+| `analyze`                  | Refresh facts without changing policy or baseline.              |
+| `propose`                  | Generate evidence-based rule and contract proposals.            |
+| `check --changed`          | Enforce active policy on changed and untracked files.           |
+| `audit`                    | Scan the complete current project, including baseline findings. |
+| `review`                   | Create a bounded semantic-review packet for an AI host.         |
+| `verify`                   | Run the configured completion gate.                             |
+| `doctor`                   | Diagnose invalid or missing Guard artifacts.                    |
+| `history` / `history-diff` | Inspect project model evolution.                                |
+| `rules` / `contracts`      | Approve or reject proposed policy.                              |
+| `baseline`                 | Review or intentionally accept existing findings.               |
+
+Run `pnpm exec codapult-guard <command> --help` for command-specific options.
+
+## Security and data handling
+
+- Deterministic discovery and checks run locally.
+- Review packets are bounded and redact common secrets before they are returned to an AI host.
+- Guard does not invoke an LLM or require a provider API key.
+- Project commands and external adapters run only when enabled by the project configuration.
+- Existing findings can be baselined, but new regressions remain visible.
+
+## Verification and proof
+
+The repository validates the product through multiple layers:
+
+- unit and integration tests for discovery, policy, baseline, verification, MCP, and output;
+- AST adversarial cases for aliases, re-exports, dynamic imports, and route boundaries;
+- golden end-to-end flow from violation to repair;
+- mutation regression checks across real Next.js, React/Vite, Node, Hono, monorepo, and Express
+  repositories;
+- npm pack checks to ensure the published artifact contains only the intended build output.
+
+Run the maintainer checks locally:
+
+```bash
+pnpm test
+pnpm test:guard:golden
+pnpm test:guard:fixtures
+pnpm test:guard:fixtures:regression
+pnpm release:check
+```
+
+## Documentation
+
+- [Complete Guard guide](docs/guard.md)
+- [AI-agent integration](docs/guard-agent-integration.md)
+- [Host integrations](docs/integrations/)
+- [CI consumer workflow](docs/guard-ci.yml)
+- [Fixture matrix](docs/guard-fixtures.md)
+- [Release process](docs/releasing.md)
+
+## Project status
+
+`@codapult/guard` starts at `0.1.0` as a public alpha. The deterministic core is usable, tested,
+and intended for real projects, while policy schema and integration surfaces may still evolve
+before `1.0.0`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/adapters/agents/agent-integration.d.ts

@@ -0,0 +1,9 @@
+export type GuardAgentTarget = 'generic' | 'codex' | 'cursor' | 'claude' | 'copilot' | 'gemini';
+export interface GuardAgentInstallResult {
+    target: GuardAgentTarget;
+    path: string;
+    action: 'created' | 'updated';
+}
+export declare function installGuardAgentInstructions(root: string, target: GuardAgentTarget): GuardAgentInstallResult;
+export declare function installGuardAgentTargets(root: string, targetsToInstall: GuardAgentTarget[]): GuardAgentInstallResult[];
+export declare const guardAgentTargets: GuardAgentTarget[];

package/dist/adapters/agents/agent-integration.js

@@ -0,0 +1,62 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+const START_MARKER = '<!-- codapult-guard:start -->';
+const END_MARKER = '<!-- codapult-guard:end -->';
+const instruction = `${START_MARKER}
+## Codapult Guard completion gate
+
+After completing a coding task, read the project Guard context, review the requirement and diff,
+then run Guard verification. Use the host's Guard MCP tools when available:
+
+1. Call \`codapult_guard_context\`.
+2. Call \`codapult_guard_review\` with the requirement and changed diff.
+3. Call \`codapult_guard_verify\`.
+4. If an error is reported, fix it and repeat steps 2–3 up to \`completionGate.maxIterations\`.
+5. Report warnings and unresolved requirements; never hide them or activate proposals silently.
+
+Guard does not edit source files or invoke an LLM. The host agent owns the repair loop. CI remains
+the independent final gate.
+${END_MARKER}`;
+const targets = {
+    generic: { path: 'AGENTS.md' },
+    codex: { path: 'AGENTS.md' },
+    cursor: {
+        path: '.cursor/rules/codapult-guard.mdc',
+        prefix: '---\ndescription: Codapult Guard completion workflow\nalwaysApply: false\n---\n\n# Codapult Guard\n\n',
+    },
+    claude: { path: 'CLAUDE.md' },
+    copilot: { path: '.github/copilot-instructions.md' },
+    gemini: { path: 'GEMINI.md' },
+};
+function renderContent(target) {
+    return `${targets[target].prefix ?? ''}${instruction}\n`;
+}
+export function installGuardAgentInstructions(root, target) {
+    const relativePath = targets[target].path;
+    const path = resolve(root, relativePath);
+    const nextBlock = instruction;
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    const start = existing.indexOf(START_MARKER);
+    const end = existing.indexOf(END_MARKER);
+    const content = start >= 0 && end >= start
+        ? `${existing.slice(0, start)}${nextBlock}${existing.slice(end + END_MARKER.length)}`
+        : existing.length > 0
+            ? `${existing.trimEnd()}\n\n${renderContent(target)}`
+            : renderContent(target);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content, 'utf8');
+    return { target, path: relativePath, action: existing ? 'updated' : 'created' };
+}
+export function installGuardAgentTargets(root, targetsToInstall) {
+    const seenPaths = new Set();
+    return targetsToInstall
+        .filter((target) => {
+        const path = targets[target].path;
+        if (seenPaths.has(path))
+            return false;
+        seenPaths.add(path);
+        return true;
+    })
+        .map((target) => installGuardAgentInstructions(root, target));
+}
+export const guardAgentTargets = Object.keys(targets);

package/dist/adapters/command.d.ts

@@ -0,0 +1,21 @@
+export interface CommandResult {
+    command: string;
+    status: 'passed' | 'failed' | 'not-configured';
+    passed: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+    truncated?: boolean;
+}
+export declare function runProjectCommand(command: string, cwd: string, options?: {
+    timeout?: number;
+    env?: NodeJS.ProcessEnv;
+}): CommandResult;
+export declare function commandResponse(result: CommandResult): {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError: boolean;
+};

package/dist/adapters/command.js

@@ -0,0 +1,60 @@
+import { execSync } from 'node:child_process';
+const MAX_OUTPUT_CHARS = 20_000;
+const MAX_BUFFER_BYTES = 2_000_000;
+function redactOutput(value) {
+    return value
+        .replace(/-----BEGIN [A-Z ]+-----[\s\S]*?-----END [A-Z ]+-----/g, '[REDACTED PRIVATE KEY]')
+        .replace(/\b(?:sk_(?:live|test)_|pk_(?:live|test)_|AKIA|gh[pousr]_|github_pat_)[A-Za-z0-9_-]+/g, '[REDACTED TOKEN]')
+        .replace(/((?:api[_-]?key|secret|token|password|authorization|database[_-]?url)\s*[:=]\s*["']?)[^\s"'`,}]+/gi, '$1[REDACTED]');
+}
+function captureOutput(value) {
+    const redacted = redactOutput(value);
+    return redacted.length > MAX_OUTPUT_CHARS
+        ? { value: `${redacted.slice(0, MAX_OUTPUT_CHARS)}\n[output truncated]`, truncated: true }
+        : { value: redacted, truncated: false };
+}
+export function runProjectCommand(command, cwd, options = {}) {
+    try {
+        const stdout = execSync(command, {
+            cwd,
+            env: { ...process.env, ...options.env },
+            stdio: 'pipe',
+            timeout: options.timeout ?? 120_000,
+            maxBuffer: MAX_BUFFER_BYTES,
+        }).toString();
+        const captured = captureOutput(stdout);
+        return {
+            command,
+            status: 'passed',
+            passed: true,
+            exitCode: 0,
+            stdout: captured.value,
+            stderr: '',
+            truncated: captured.truncated,
+        };
+    }
+    catch (error) {
+        const execError = error;
+        const exitCode = execError.status ?? 1;
+        const passed = exitCode === 0;
+        const stdout = captureOutput(execError.stdout?.toString() ?? '');
+        const stderr = captureOutput(execError.stderr?.toString() ?? '');
+        const timedOut = execError.code === 'ETIMEDOUT' || execError.signal === 'SIGTERM';
+        return {
+            command,
+            status: passed ? 'passed' : 'failed',
+            passed,
+            exitCode,
+            stdout: stdout.value,
+            stderr: timedOut ? `${stderr.value}\n[command timed out]` : stderr.value,
+            timedOut,
+            truncated: stdout.truncated || stderr.truncated,
+        };
+    }
+}
+export function commandResponse(result) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        isError: !result.passed,
+    };
+}

package/dist/adapters/project-checks.d.ts

@@ -0,0 +1,37 @@
+import { type CommandResult } from './command.js';
+export type ProjectCheck = 'lint' | 'typecheck' | 'test' | 'build';
+export type GuardAdapter = 'dependency-graph' | 'security' | 'dependency-hygiene';
+export type ExternalToolMode = 'auto' | 'on' | 'off';
+export type ProjectCheckResults = Partial<Record<ProjectCheck, CommandResult>>;
+export interface ProjectRuntimeDiagnostics {
+    node: string;
+    packageManager: string;
+    declaredPackageManager?: string;
+    declaredNode?: string;
+    compatible: boolean;
+    issues: string[];
+}
+export declare function inspectProjectRuntime(root: string): ProjectRuntimeDiagnostics;
+export declare function runProjectChecks(root: string, checks: ProjectCheck[], options?: {
+    timeout?: number;
+}): ProjectCheckResults;
+/**
+ * Runs checks for workspace packages only when the root package does not own
+ * the corresponding check. Root orchestration remains the source of truth.
+ */
+export declare function runWorkspaceProjectChecks(root: string, packages: {
+    path: string;
+    scripts: Record<string, string>;
+}[], checks: ProjectCheck[], options?: {
+    timeout?: number;
+    rootResults?: ProjectCheckResults;
+}): Record<string, ProjectCheckResults>;
+/** Runs only explicitly configured project scripts; Guard does not recreate these tools. */
+export declare function runProjectAdapters(root: string, options?: {
+    mode?: Exclude<ExternalToolMode, 'off'>;
+    timeout?: number;
+    tooling?: Partial<Record<GuardAdapter, {
+        script: string;
+        enabled: boolean;
+    }>>;
+}): Partial<Record<GuardAdapter, CommandResult>>;

package/dist/adapters/project-checks.js

@@ -0,0 +1,149 @@
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { runProjectCommand } from './command.js';
+const require = createRequire(import.meta.url);
+const { satisfies } = require('semver');
+function notConfigured(check) {
+    return {
+        command: '',
+        status: 'not-configured',
+        passed: false,
+        exitCode: 0,
+        stdout: '',
+        stderr: `${check} script is not configured`,
+    };
+}
+function readPackageMetadata(root) {
+    try {
+        return JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function packageManager(root, declared) {
+    const name = declared?.split('@', 1)[0];
+    if (name === 'pnpm' || name === 'yarn' || name === 'npm' || name === 'bun')
+        return name;
+    for (const [lockfile, manager] of [
+        ['pnpm-lock.yaml', 'pnpm'],
+        ['yarn.lock', 'yarn'],
+        ['package-lock.json', 'npm'],
+        ['bun.lockb', 'bun'],
+        ['bun.lock', 'bun'],
+    ]) {
+        if (existsSync(resolve(root, lockfile)))
+            return manager;
+    }
+    return 'pnpm';
+}
+export function inspectProjectRuntime(root) {
+    const metadata = readPackageMetadata(root);
+    const manager = packageManager(root, metadata.packageManager);
+    const issues = [];
+    const declaredNode = metadata.engines?.node;
+    let nodeCompatible = true;
+    if (declaredNode) {
+        try {
+            nodeCompatible = satisfies(process.versions.node, declaredNode);
+        }
+        catch {
+            nodeCompatible = false;
+        }
+    }
+    if (declaredNode && !nodeCompatible) {
+        issues.push(`Node ${process.versions.node} does not satisfy engines.node "${declaredNode}".`);
+    }
+    const declaredManager = metadata.packageManager?.split('@', 1)[0];
+    if (declaredManager && declaredManager !== manager) {
+        issues.push(`Detected package manager ${manager}, but packageManager declares ${declaredManager}.`);
+    }
+    return {
+        node: process.versions.node,
+        packageManager: manager,
+        ...(metadata.packageManager ? { declaredPackageManager: metadata.packageManager } : {}),
+        ...(declaredNode ? { declaredNode } : {}),
+        compatible: issues.length === 0,
+        issues,
+    };
+}
+function commandFor(root, manager, check, scripts) {
+    const run = (script, suffix = '') => manager === 'npm' ? `npm run ${script}${suffix}` : `${manager} run ${script}${suffix}`;
+    if (check === 'typecheck' && !scripts.typecheck && !scripts['type-check']) {
+        if (!existsSync(resolve(root, 'tsconfig.json')))
+            return undefined;
+        return manager === 'npm' ? 'npx --no-install tsc --noEmit' : `${manager} exec tsc --noEmit`;
+    }
+    if (check === 'typecheck')
+        return run(scripts.typecheck ? 'typecheck' : 'type-check');
+    if (!scripts[check])
+        return undefined;
+    return run(check);
+}
+export function runProjectChecks(root, checks, options = {}) {
+    const metadata = readPackageMetadata(root);
+    const manager = packageManager(root, metadata.packageManager);
+    const scripts = metadata.scripts ?? {};
+    const results = {};
+    for (const check of checks) {
+        const command = commandFor(root, manager, check, scripts);
+        results[check] = command
+            ? runProjectCommand(command, root, {
+                timeout: options.timeout ?? (check === 'build' ? 300_000 : 120_000),
+            })
+            : notConfigured(check);
+    }
+    return results;
+}
+function hasCheck(scripts, check) {
+    return check === 'typecheck'
+        ? Boolean(scripts.typecheck || scripts['type-check'])
+        : Boolean(scripts[check]);
+}
+/**
+ * Runs checks for workspace packages only when the root package does not own
+ * the corresponding check. Root orchestration remains the source of truth.
+ */
+export function runWorkspaceProjectChecks(root, packages, checks, options = {}) {
+    const rootResults = options.rootResults ?? runProjectChecks(root, checks, options);
+    const missingAtRoot = new Set(checks.filter((check) => rootResults[check]?.status === 'not-configured'));
+    return Object.fromEntries(packages
+        .filter((workspace) => checks.some((check) => missingAtRoot.has(check) && hasCheck(workspace.scripts, check)))
+        .map((workspace) => [
+        workspace.path,
+        runProjectChecks(resolve(root, workspace.path), [...missingAtRoot], options),
+    ]));
+}
+const adapterScriptPatterns = {
+    'dependency-graph': /(?:dep(?:endency)?[-:]?(?:check|graph|cruise)|madge|architecture)/i,
+    security: /(?:security|semgrep|gitleaks|snyk|trivy|audit)/i,
+    'dependency-hygiene': /(?:knip|dep(?:endency)?[-:]?(?:unused|hygiene))/i,
+};
+/** Runs only explicitly configured project scripts; Guard does not recreate these tools. */
+export function runProjectAdapters(root, options = {}) {
+    const metadata = readPackageMetadata(root);
+    const manager = packageManager(root, metadata.packageManager);
+    const scripts = metadata.scripts ?? {};
+    const results = {};
+    for (const [adapter, pattern] of Object.entries(adapterScriptPatterns)) {
+        const configured = options.tooling?.[adapter];
+        const script = configured?.enabled
+            ? configured.script
+            : configured?.enabled === false
+                ? undefined
+                : Object.keys(scripts).find((name) => pattern.test(name));
+        if (!script && options.mode !== 'on') {
+            continue;
+        }
+        if (!script) {
+            results[adapter] = notConfigured(adapter);
+            continue;
+        }
+        const command = manager === 'npm' ? `npm run ${script}` : `${manager} run ${script}`;
+        results[adapter] = runProjectCommand(command, root, {
+            timeout: options.timeout ?? 120_000,
+        });
+    }
+    return results;
+}