@codapult/guard 0.10.0 → 0.11.0

package/docs/integrations/README.md

@@ -0,0 +1,38 @@
+# AI Coding Agent Integrations
+
+Connect Codapult Guard architecture guardrails to Claude Code, Codex, Cursor, Gemini CLI, GitHub
+Copilot, or another MCP-compatible AI coding agent. These guides cover project instructions, MCP
+setup, and independent verification in CI.
+
+The examples use a project-local pnpm installation. Guard requires Node.js `>=20.19.0`; with
+npm, replace `pnpm add -D @codapult/guard` with `npm install --save-dev @codapult/guard` and
+replace `pnpm exec codapult-guard` with `npx --no-install codapult-guard`.
+
+These kits keep Guard platform-neutral while giving each host a concrete setup. Each page names
+the host's instruction file, MCP configuration file or command, verification command, and the
+available completion hook surface.
+
+- [Codex](codex.md)
+- [Cursor](cursor.md)
+- [Claude Code](claude-code.md)
+- [GitHub Copilot](github-copilot.md)
+- [Gemini CLI](gemini-cli.md)
+- [Generic shell/CI](generic.md)
+
+| Host               | Project instruction                | MCP setup                                              | Local completion automation           |
+| ------------------ | ---------------------------------- | ------------------------------------------------------ | ------------------------------------- |
+| Codex CLI          | `AGENTS.md`                        | `codex mcp add` / `~/.codex/config.toml`               | Instruction-driven; CI gate           |
+| Cursor Agent       | `.cursor/rules/codapult-guard.mdc` | `.cursor/mcp.json`                                     | `.cursor/hooks.json` `stop` follow-up |
+| Claude Code        | `CLAUDE.md`                        | project `.mcp.json`                                    | `.claude/settings.json` `Stop` hook   |
+| Gemini CLI         | `GEMINI.md`                        | `.gemini/settings.json`                                | Instruction-driven; CI gate           |
+| Copilot Chat / CLI | `.github/copilot-instructions.md`  | `.vscode/mcp.json`, `.mcp.json`, or `.github/mcp.json` | Surface-specific; CI gate             |
+
+All integrations use the same MCP tools and completion-gate contract. None of them grants the
+agent permission to edit files; that remains the user's host configuration. Guard is discoverable
+in the [official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.codapult%2Fguard)
+as `io.github.codapult/guard`; Registry publication does not create one universal installer, so
+follow the host-specific setup on the relevant page.
+
+The kits are documentation-level adapters, not runtime dependencies. Install the managed
+instruction for a supported host with `codapult-guard install-agent <target>`, configure the MCP
+server in that host, and keep `codapult-guard verify --json` in CI as the independent gate.

package/docs/integrations/claude-code.md

@@ -0,0 +1,92 @@
+# Claude Code integration
+
+This page targets Claude Code with a project-scoped MCP server and project instructions.
+
+## 1. Install Guard
+
+Guard is published in the official MCP Registry as `io.github.codapult/guard`. Search for that identifier in a Registry-aware client and import the npm/stdio entry when supported. Claude Code also accepts the same server directly, so Registry discovery is optional.
+
+Install the package:
+
+```bash
+pnpm add -D @codapult/guard
+```
+
+If this project has not been initialized yet, establish its Guard state:
+
+```bash
+pnpm exec codapult-guard init
+```
+
+Register a project-scoped stdio server:
+
+```bash
+claude mcp add --transport stdio codapult-guard --scope project \
+  -- pnpm exec codapult-guard mcp-server
+```
+
+This writes the project server to `.mcp.json`. Verify it:
+
+```bash
+claude mcp get codapult-guard
+claude mcp list
+```
+
+Approve the project server when Claude Code asks for workspace trust.
+
+## 2. Add project instructions
+
+Run:
+
+```bash
+pnpm exec codapult-guard install-agent claude
+```
+
+This creates or updates the managed block in `CLAUDE.md`. Claude Code reads that file as project instruction context; the MCP registration remains in `.mcp.json`.
+
+## 3. Optional completion hook
+
+Claude Code project hooks live in `.claude/settings.json`. To verify at the end of every agent
+turn, create `.claude/hooks/guard-stop.sh`:
+
+```bash
+#!/usr/bin/env bash
+set +e
+cat >/dev/null
+pnpm exec codapult-guard verify --json >&2
+status=$?
+if [ "$status" -ne 0 ]; then
+  exit 2
+fi
+exit 0
+```
+
+Make it executable (`chmod +x .claude/hooks/guard-stop.sh`) and add a `Stop` command hook:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/guard-stop.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Keep CI verification as the independent merge gate. Use `/hooks` to inspect the active hook and `/mcp` to inspect the MCP connection.
+
+## 4. Agent loop
+
+The agent should call `codapult_guard_next_action`, then `codapult_guard_context`,
+`codapult_guard_review`, and `codapult_guard_verify`. It fixes reported errors and repeats until
+the configured completion gate passes. Guard returns evidence and deterministic results; Claude
+Code owns the repair loop.
+
+References: [Claude Code MCP](https://code.claude.com/docs/en/mcp), [Claude Code hooks](https://code.claude.com/docs/en/hooks).

package/docs/integrations/codex.md

@@ -0,0 +1,58 @@
+# Codex integration
+
+This page targets Codex CLI and Codex-compatible IDE integrations that read `AGENTS.md` and support the Codex MCP configuration.
+
+## 1. Install Guard
+
+Guard is published in the official MCP Registry as `io.github.codapult/guard`. Use the Registry entry when a Codex host offers Registry import. Otherwise configure the npm/stdio server directly; the Registry is discovery and does not replace the host's MCP configuration.
+
+Install the package:
+
+```bash
+pnpm add -D @codapult/guard
+```
+
+If this project has not been initialized yet, establish its Guard state:
+
+```bash
+pnpm exec codapult-guard init
+```
+
+Register the server with Codex CLI:
+
+```bash
+codex mcp add codapult-guard -- pnpm exec codapult-guard mcp-server
+codex mcp list
+```
+
+The equivalent user configuration is an entry in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.codapult-guard]
+command = "pnpm"
+args = ["exec", "codapult-guard", "mcp-server"]
+```
+
+Codex stores this MCP registration in its user configuration. Keep the repository's `AGENTS.md`
+and CI gate in version control; configure the MCP server separately on each developer machine.
+
+## 2. Add repository instructions
+
+Run:
+
+```bash
+pnpm exec codapult-guard install-agent codex
+```
+
+This creates or updates the managed Guard block in `AGENTS.md`. Codex loads `AGENTS.md` as repository instruction context, while the MCP server remains a separate tool configuration.
+
+## 3. Completion workflow
+
+Codex should call `codapult_guard_next_action`, then `codapult_guard_context`,
+`codapult_guard_review`, and `codapult_guard_verify` after a coding task. It repairs errors and
+repeats verification according to `.codapult/guard/agent.json`. Run the same
+`codapult-guard verify --json` command in CI.
+
+Guard does not invoke Codex or an LLM. Codex owns task execution and repairs; Guard supplies project facts, policy evidence, and the deterministic gate.
+
+References: [Codex MCP configuration example](https://developers.openai.com/learn/docs-mcp), [Codex repository instructions](https://developers.openai.com/cookbook/examples/codex/code_modernization).

package/docs/integrations/cursor.md

@@ -0,0 +1,116 @@
+# Cursor integration
+
+This page targets Cursor Agent in a trusted local workspace. Cursor supports project MCP
+configuration in `.cursor/mcp.json`, project rules in `.cursor/rules/`, and project hooks in
+`.cursor/hooks.json`.
+
+## 1. Install Guard
+
+Guard is listed in the official MCP Registry as `io.github.codapult/guard`. In a client that can
+import Registry entries, search for that identifier and select the npm/stdio server. Cursor's
+native MCP directory and one-click install are separate from the official MCP Registry; if Guard
+is not offered there, use the project configuration below.
+
+Install the package in the repository:
+
+```bash
+pnpm add -D @codapult/guard
+```
+
+If this project has not been initialized yet, establish its Guard state before enabling the hook:
+
+```bash
+pnpm exec codapult-guard init
+```
+
+Create `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "codapult-guard": {
+      "type": "stdio",
+      "command": "pnpm",
+      "args": ["exec", "codapult-guard", "mcp-server"],
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}
+```
+
+Reload Cursor and verify that `codapult-guard` appears in the MCP tools list. Keep the project
+configuration in version control only if the team agrees to trust and run the local server for
+every contributor.
+
+## 2. Add the Guard rule
+
+Run this from the project root:
+
+```bash
+pnpm exec codapult-guard install-agent cursor
+```
+
+This creates or updates `.cursor/rules/codapult-guard.mdc`. The generated rule tells Agent when
+to call the MCP tools; CI remains the independent enforcement point.
+
+## 3. Run the completion gate automatically
+
+Cursor project hooks are command-based processes that receive JSON on stdin. Add
+`.cursor/hooks/guard-stop.mjs`:
+
+```js
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+const input = JSON.parse(readFileSync(0, 'utf8') || '{}');
+const root = process.env.CURSOR_PROJECT_DIR ?? process.cwd();
+
+if (input.status !== 'completed') process.exit(0);
+
+const result = spawnSync('pnpm', ['exec', 'codapult-guard', 'verify', '--json'], {
+  cwd: root,
+  encoding: 'utf8',
+  stdio: ['ignore', 'pipe', 'pipe'],
+});
+
+if (result.status !== 0) {
+  const detail = (result.stdout || result.stderr || '').trim().slice(-2_000);
+  process.stdout.write(
+    JSON.stringify({
+      followup_message: `Guard verification failed. Fix the reported findings, then run Guard again.${detail ? `\n\n${detail}` : ''}`,
+    }),
+  );
+}
+```
+
+Register it in `.cursor/hooks.json`:
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "stop": [
+      {
+        "command": "node .cursor/hooks/guard-stop.mjs",
+        "loop_limit": 3,
+        "failClosed": true
+      }
+    ]
+  }
+}
+```
+
+`stop` runs when Cursor Agent is completing a task. A failed verification returns Cursor's
+`followup_message`, which starts another agent iteration; `loop_limit` bounds that loop. The hook
+is optional for local work; CI is the merge gate. Do not treat a hook's presence as a replacement
+for CI enforcement.
+
+## 4. Normal agent loop
+
+Ask Cursor Agent to call `codapult_guard_next_action`, then
+`codapult_guard_context`, `codapult_guard_review`, and `codapult_guard_verify`. If verification
+reports an error, the agent repairs the change and repeats verification. The deterministic Guard
+gate does not call an LLM.
+
+References: [Cursor MCP](https://cursor.com/docs/mcp), [Cursor hooks](https://cursor.com/docs/hooks),
+[Cursor rules](https://cursor.com/docs/context/rules).

package/docs/integrations/gemini-cli.md

@@ -0,0 +1,47 @@
+# Gemini CLI integration
+
+This page targets Gemini CLI with project settings and the project `GEMINI.md` context file.
+
+## 1. Install Guard
+
+Guard is published in the official MCP Registry as `io.github.codapult/guard`. Search for that identifier in a Registry-aware client and import it when the client supports Registry entries. Gemini CLI can also add the npm/stdio server directly, independently of Registry UI.
+
+Install the package:
+
+```bash
+pnpm add -D @codapult/guard
+```
+
+If this project has not been initialized yet, establish its Guard state:
+
+```bash
+pnpm exec codapult-guard init
+```
+
+Add it to the project scope:
+
+```bash
+gemini mcp add --scope project codapult-guard pnpm exec codapult-guard mcp-server
+```
+
+The project configuration is `.gemini/settings.json`. Verify the connection inside Gemini CLI with `/mcp list` or `/mcp desc`.
+
+## 2. Add the project instruction
+
+Run:
+
+```bash
+pnpm exec codapult-guard install-agent gemini
+```
+
+This creates or updates the managed block in `GEMINI.md`, which Gemini CLI loads as hierarchical project context.
+
+## 3. Completion behavior
+
+Gemini CLI's project settings provide the MCP connection and `GEMINI.md` provides the workflow
+instruction. At the end of a coding task, have the agent call `codapult_guard_next_action`, then
+`codapult_guard_context`, `codapult_guard_review`, and `codapult_guard_verify`. Keep
+`codapult-guard verify --json` in CI; the local agent session is not the final authority for
+merging changes.
+
+References: [Gemini CLI MCP](https://geminicli.com/docs/tools/mcp-server/), [Gemini CLI configuration](https://geminicli.com/docs/reference/configuration/), [GEMINI.md context](https://geminicli.com/docs/cli/gemini-md/).

package/docs/integrations/generic.md

@@ -0,0 +1,41 @@
+# Generic AI agent integration
+
+Install Guard and initialize the project before adding an agent instruction:
+
+```bash
+pnpm add -D @codapult/guard
+pnpm exec codapult-guard init
+```
+
+Guard is discoverable in the [official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.codapult%2Fguard)
+as `io.github.codapult/guard`. If the host does not import Registry entries, register the local
+stdio command `pnpm exec codapult-guard mcp-server` in its MCP configuration.
+
+Add the following to the agent's project instructions:
+
+```text
+After completing a coding task, call codapult_guard_next_action and follow its bounded next step.
+Normally call codapult_guard_context, then codapult_guard_review with the requirement and changed
+diff, then codapult_guard_verify. If the result contains an error, fix it and repeat up to
+completionGate.maxIterations. Do not hide warnings or claim completion without reporting
+unresolved requirements.
+```
+
+The CLI equivalent is:
+
+```bash
+codapult-guard review --requirement docs/acceptance.md
+codapult-guard verify --json
+```
+
+For pull-request CI, verify against the protected base policy. Fetch the base commit before this
+step and pass its SHA (the bundled `docs/guard-ci.yml` does this automatically):
+
+```bash
+codapult-guard verify --policy-base "$BASE_SHA" --json
+```
+
+Use `--fail-on-policy-change` in a separate policy-review gate when changing Guard policy requires
+an explicit protected approval.
+
+Use the host's post-task hook to invoke the sequence. Run the same command independently in CI.

package/docs/integrations/github-copilot.md

@@ -0,0 +1,72 @@
+# GitHub Copilot integration
+
+GitHub Copilot has two relevant local surfaces. Use the VS Code instructions for Copilot Chat in Agent mode, or the Copilot CLI instructions for the terminal agent. They do not share the same MCP configuration file.
+
+## Copilot Chat in VS Code
+
+Guard is published in the official MCP Registry as `io.github.codapult/guard`. Registry import is client-dependent; if it is not available in your VS Code MCP gallery, configure the server manually.
+
+Install the package:
+
+```bash
+pnpm add -D @codapult/guard
+```
+
+If this project has not been initialized yet, establish its Guard state:
+
+```bash
+pnpm exec codapult-guard init
+```
+
+Create `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "codapult-guard": {
+      "type": "stdio",
+      "command": "pnpm",
+      "args": ["exec", "codapult-guard", "mcp-server"]
+    }
+  }
+}
+```
+
+Start the server from `.vscode/mcp.json`, open Copilot Chat in Agent mode, and enable Guard in the tools picker. Then run:
+
+```bash
+pnpm exec codapult-guard install-agent copilot
+```
+
+This creates or updates `.github/copilot-instructions.md` with the completion workflow.
+
+## Copilot CLI
+
+Copilot CLI uses `~/.copilot/mcp-config.json` for persistent user servers and `.mcp.json` or `.github/mcp.json` for trusted repository/workspace servers. Add Guard to the repository:
+
+```json
+{
+  "mcpServers": {
+    "codapult-guard": {
+      "command": "pnpm",
+      "args": ["exec", "codapult-guard", "mcp-server"]
+    }
+  }
+}
+```
+
+Place the file at `.mcp.json` or `.github/mcp.json`, then verify it with `copilot mcp list`. For one session, use `copilot --additional-mcp-config=@.mcp.json`.
+
+The instruction file for Copilot CLI can be generated with the same command; it updates `.github/copilot-instructions.md`:
+
+```bash
+pnpm exec codapult-guard install-agent copilot
+```
+
+Keep CI as the independent final gate. Copilot's editor and CLI surfaces have different lifecycle
+hooks, so this integration relies on project instructions plus `verify` rather than claiming one
+universal completion hook. The instruction tells the agent to call
+`codapult_guard_next_action`, `codapult_guard_context`, `codapult_guard_review`, and
+`codapult_guard_verify`.
+
+References: [Copilot MCP in VS Code](https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/extend-copilot-chat-with-mcp), [Copilot CLI](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference).

package/docs/policy-mutations.md

@@ -0,0 +1,75 @@
+# Policy mutation control
+
+Guard reports and validates policy mutations, but it cannot prove that a process invoking the CLI
+is a human. A shell-capable coding agent can technically execute the same CLI command as a
+developer. Human or independent approval must therefore be enforced by the host or CI system.
+
+Inspect the machine-readable mutation contract:
+
+```bash
+codapult-guard policy mutations --json
+```
+
+The contract identifies operations that change policy, including:
+
+- `init.force`;
+- `rules.approve` and `contracts.approve|reject`;
+- `baseline.accept|remove`;
+- `waiver.add|renew|remove`;
+- direct edits to `.codapult/guard/*`.
+
+Every listed operation has `externalApprovalRequired: true`. This is a declaration for the host;
+it is not an identity or signature mechanism.
+
+## Agent shell policy
+
+Use the host's command approval or `PreToolUse` mechanism to reject policy mutations while the
+agent session is running. The exact hook format is host-specific, but the denied command set
+should include:
+
+```text
+codapult-guard init --force
+codapult-guard baseline accept
+codapult-guard baseline remove
+codapult-guard waiver add
+codapult-guard waiver renew
+codapult-guard waiver remove
+codapult-guard rules approve
+codapult-guard contracts approve
+codapult-guard contracts reject
+```
+
+Allow read-only commands such as `context`, `check`, `review`, `verify`, `audit`, `impact`, and
+`policy mutations`. If a policy change is needed, the agent may explain or propose it, but the
+mutation should be performed through a human-approved branch or protected CI job.
+
+## CI policy
+
+Keep `.codapult/guard/*` under CODEOWNERS and protected-branch review. For pull requests, verify
+against the base policy rather than the policy changed in the pull request:
+
+```bash
+codapult-guard verify \
+  --policy-base "$BASE_SHA" \
+  --fail-on-policy-change \
+  --json
+```
+
+The bundled [`guard-ci.yml`](guard-ci.yml) shows the complete workflow. A policy-changing pull
+request should require the configured architecture owner; the Guard result alone does not grant
+that approval.
+
+## Adversarial test
+
+The relevant failure scenario is:
+
+```text
+agent changes source
+  → Guard reports a violation
+  → agent attempts waiver/baseline/policy mutation
+  → host blocks the mutation
+  → agent must repair source or request human review
+```
+
+Guard tests the policy checks and emits the mutation contract. The host or CI layer tests whether
+the attempted command is actually blocked.

package/docs/releasing.md

@@ -0,0 +1,58 @@
+# Releasing Guard
+
+Guard is distributed through npm as `@codapult/guard`. A GitHub Release is used as the reviewed
+release record and triggers publication to npm and, after npm succeeds, the official MCP Registry.
+The GitHub Release is not a second package distribution channel.
+
+## Recommended flow
+
+1. Run `pnpm release` from a clean, up-to-date checkout. `release-it` updates the version and
+   changelog, creates the matching tag, pushes it, and creates the GitHub Release.
+2. The `release.yml` workflow checks out the tag, verifies that the tag and package version match,
+   runs the complete release check, validates `server.json`, and publishes the exact package to npm
+   with provenance.
+3. The workflow waits until the exact npm version is visible and contains the expected `mcpName`.
+4. After npm publication succeeds, the workflow authenticates with GitHub OIDC and publishes the
+   matching MCP server metadata to the official Registry.
+
+If a release is prepared manually, update `CHANGELOG.md` and `package.json`, run
+`pnpm mcp:sync`, run `pnpm release:check`, push a matching tag such as `v0.1.0`, and publish the
+GitHub Release for that tag.
+
+The workflow uses npm trusted publishing through GitHub Actions OIDC. Configure the npm package's
+trusted publisher for this repository and workflow before the first publication. No npm token is
+stored in the repository.
+
+## MCP Registry metadata
+
+`server.json` describes the stdio MCP server exposed by the npm package. Its `name` is
+`io.github.codapult/guard` and must match the `mcpName` field in `package.json`; the Registry uses
+that marker to verify npm package ownership. The `mcp:validate` script checks the name, repository,
+package identifier, transport, and versions locally. `release-it` runs `mcp:sync` after bumping the
+package version so the release commit contains matching metadata.
+
+The Registry hosts server metadata, not npm artifacts. Therefore Registry publication is deliberately
+a post-npm release step and is not part of ordinary local development. The release job uses GitHub OIDC; configure the workflow's `id-token: write`
+permission and protect the release environment before enabling production publication. The release
+workflow pins and verifies the Linux x64 `mcp-publisher` binary; update its version and checksum
+deliberately when upgrading the publisher.
+
+If npm publication succeeds but Registry publication fails because npm propagation is delayed,
+use the workflow's **Run workflow** action with the failed release tag after the package becomes
+visible. The npm step verifies the existing version and continues only when its `mcpName` matches;
+it does not attempt to overwrite an npm version.
+
+## Why use both GitHub Release and npm?
+
+They serve different purposes:
+
+- npm is where users install `@codapult/guard`;
+- the GitHub Release records the source tag, changelog, release notes, and maintainer decision;
+- the published GitHub Release provides one explicit, auditable trigger for npm publication.
+
+A GitHub Release is not technically required to publish to npm. A tag-triggered workflow could
+publish directly, but the reviewed-release trigger makes accidental publication less likely and
+keeps source, changelog, and npm version aligned.
+
+Do not publish by running `npm publish` manually unless the release workflow is intentionally being
+replaced. Never reuse an already-published version.