Metadata-Version: 2.4
Name: project-guard
Version: 0.6.0
Summary: Small, local-first AI coding governance CLI
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12
Requires-Dist: pydantic>=2
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"

# Project Guard

Project Guard is a local-first governance layer for AI coding agents.

Its goal is to help a Coding Agent satisfy the user's actual requirement with
the **Smallest Safe Change**: a change that is local, controlled, safe for
future maintenance, and appropriate to the request. Project Guard helps find
or prevent scope expansion, duplicate implementation, unnecessary
architecture or dependencies, requirement drift, and risky repository
changes.

Project Guard is not an AI architect, a semantic-correctness verifier, or a
security sandbox. It does not prove that code is correct, complete, or free of
security issues.

**v0.6.0 is the current release candidate.** v0.5.0 is published on PyPI;
several platform integrations remain Experimental because their behavior
depends on the platform's Hook or Plugin runtime.

## Installation

Requires Python 3.12 or newer.

Install the published package:

```bash
pip install project-guard
```

Verify the installation:

```bash
project-guard --version
project-guard --help
```

The version command should report:

```text
0.6.0
```

Project Guard does not install or authenticate Claude Code, Codex, Cline,
TRAE, or GitHub Copilot. Install and authenticate those platform tools
separately according to their own documentation.

## Quick Start

From a Git repository that you want to govern:

```bash
cd your-project
project-guard inspect .
project-guard context .
project-guard prepare . "Add a --limit option to this CLI"
```

`prepare` does not modify production code. It records repository facts,
engineering boundaries, and a Coding Agent handoff in these Guard-owned files:

```text
.project-guard-plan.json
.project-guard-contract.json
.project-guard-instructions.md
.project-guard-skill.md
.project-guard-agent-prompt.md
```

The `.project-guard-task-contract.json` file is different: it is created and
maintained by the Coding Agent during the governed task.

## How It Works

```text
User request
    -> Project Guard prepare
    -> Engineering Contract and Coding Skill
    -> Coding Agent
    -> Agent-owned Task Contract
    -> implementation and focused tests
    -> Git Diff
    -> Project Guard Review
```

The user defines the requirement. Project Guard provides repository facts,
boundaries, and structured artifacts. The Coding Agent performs the semantic
interpretation and implementation. Review independently audits the resulting
diff.

## Language-aware Repository Intelligence

Project Guard keeps Python's AST-based indexing and adds lightweight
structural indexing for:

- Python - AST-based symbols and imports
- Java - classes, interfaces, methods, imports, and inheritance signals
- JavaScript / TypeScript - classes, functions, imports, exports, and type/interface signals
- Go - named types, functions, methods, imports, and CLI entry hints
- Rust - structs, enums, traits, functions, `use` relationships, and entry hints
- HTML - script, stylesheet, form, id, and class references
- Other text files - filename and text-search fallback

This is lightweight heuristic repository intelligence, not full compiler
semantic analysis. It does not provide type resolution, a call graph, or
complete understanding of every language construct. Malformed or complex
source may therefore produce only text-level evidence.

## Core Commands

Run `project-guard <command> --help` for the exact options supported by the
installed version.

```text
project-guard inspect PATH
    Print a repository health overview.

project-guard context PATH
    Generate compact Markdown context for a Coding Agent.

project-guard plan PATH REQUEST
    Check a request's structure, scope, and repository signals before coding.

project-guard prepare PATH REQUEST
    Generate the five Guard artifacts and an Agent handoff.

project-guard run PATH REQUEST
    Run a governed local Claude Code task and review the result.

project-guard review PATH
    Independently audit the current Git Diff against Guard and Task Contracts.

project-guard score PATH
    Print an AI coding readiness score.
```

The most explicit manual review command is:

```bash
project-guard review .
```

Before using review options, confirm the installed syntax with:

```bash
project-guard review --help
```

## Guard Artifacts

The five files generated by `prepare` represent the Guard's view of the
request:

- `.project-guard-plan.json` - plan and candidate-scope signals
- `.project-guard-contract.json` - the Engineering Contract
- `.project-guard-instructions.md` - task-specific governance instructions
- `.project-guard-skill.md` - the fixed Coding Skill
- `.project-guard-agent-prompt.md` - the Agent handoff

The Agent-owned `.project-guard-task-contract.json` records explicit
requirements, inferences, assumptions, planned production files, and scope
amendments. `prepare` does not create it.

## Platform Integrations

Most integrations use a one-time project-level command:

```text
project-guard init-<platform> .
```

The generated configuration stays in the target repository. Project Guard
does not require its own remote governance service or daemon. Platform trust,
authentication, and enablement remain platform-specific.

### Support Matrix

| Platform | Initialization | Status |
| --- | --- | --- |
| Claude Code | `project-guard init-claude .` | Verified - real coding E2E |
| Codex CLI | `project-guard init-codex .` | Experimental - real coding E2E verified |
| Codex Desktop | `project-guard init-codex .` | Experimental - real coding E2E verified |
| Cline CLI Plugin | `project-guard init-cline-plugin .` | Experimental - real coding E2E verified |
| TRAE IDE | `project-guard init-trae .` | Experimental - real coding E2E verified |
| GitHub Copilot CLI | `project-guard init-copilot .` | Experimental - real coding E2E verified |
| GitHub Copilot IDE | `project-guard init-copilot .` | Experimental - limited integration |
| Cline file Hook | `project-guard init-cline .` | Legacy experimental |

Windsurf and Cursor were investigated but are not integrated platforms in
this release.

The example used in the platform E2E records is:

```text
Add a --limit option that controls how many items are displayed.
Keep the change minimal and add a focused test if appropriate.
```

After initialization, users continue to enter a normal natural-language
request in the platform. The following sections describe the platform
specific steps and limits.

### Claude Code

Initialize the repository once:

```bash
cd your-project
project-guard init-claude .
claude
```

Then use Claude Code normally. The project-level flow is:

```text
UserPromptSubmit
    -> Project Guard prepare
    -> governance context
    -> Claude Code
    -> Task Contract
    -> coding and Review
```

All prompts in an opted-in repository currently trigger preparation,
including ordinary questions. There is no coding-intent classifier. A real
coding E2E has been verified. The explicit `project-guard run` workflow remains
available as a fallback; because Claude Code remains interactive, it may
require `/exit` before the final Review resumes.

### Codex CLI

Initialize and start Codex:

```bash
project-guard init-codex .
codex
```

The first use may show:

```text
Hooks need review
```

Inspect the project Hook and explicitly trust it through Codex's own security
flow. Do not bypass the prompt.

The verified path is:

```text
UserPromptSubmit
    -> Project Guard prepare
    -> Hook context
    -> Codex reads Guard artifacts
    -> Task Contract
    -> coding
```

Codex CLI real coding E2E has been verified, but the integration remains
Experimental because Hook trust and compatibility can vary by environment and
version.

### Codex Desktop

Use the same project initialization:

```bash
project-guard init-codex .
```

Then open the repository in Codex Desktop, create a new Agent task, and enter
the request normally.

The tested Desktop flow generated Guard artifacts, exposed the governance
context, and completed a real coding task. An earlier experiment did not
observe the project Hook; a later task in the same repository did. This does
not prove that CLI trust is required for Desktop or that trust is shared
between CLI and Desktop.

### Cline CLI Plugin

The recommended Cline CLI integration is the project-local Plugin:

```bash
project-guard init-cline-plugin .
cline
```

This installs:

```text
.cline/plugins/project-guard.js
```

The Plugin uses Cline's `beforeModel` runtime to run `prepare` and add a short
governance message to the current model request. A real Cline CLI coding E2E
has been verified.

The Plugin currently has no `beforeTool`, shell, or MCP enforcement and no
automatic `TaskComplete` Review. Task Contract creation remains
Agent/model-guided.

Detailed evidence: [docs/cline-plugin-e2e.md](docs/cline-plugin-e2e.md).

#### Legacy Cline file Hook

The older file Hook remains available for compatibility and historical tests:

```bash
project-guard init-cline .
```

It installs `.cline/hooks/` files. Automatic discovery was not reliably
observed in the tested Cline CLI environment, so it is not recommended for
new setups.

### TRAE IDE

Initialize the repository:

```bash
project-guard init-trae .
```

This creates:

```text
.trae/hooks.json
```

In the tested Windows TRAE environment, the configuration was recognized but
was not enabled automatically. After initialization, open:

```text
TRAE -> Settings -> Hooks -> Project
```

Enable the configured project Hooks manually. Only then should you use the
TRAE Agent normally.

The verified path is:

```text
UserPromptSubmit
    -> Project Guard prepare
    -> governance context
    -> TRAE Agent
```

Read-only and coding E2E were verified in the tested Windows TRAE environment.

Detailed evidence: [docs/trae-e2e.md](docs/trae-e2e.md).

### GitHub Copilot CLI

Install and authenticate GitHub Copilot CLI separately. Project Guard does
not install Copilot, log in to GitHub, manage tokens, or manage a subscription.

Initialize the repository:

```bash
project-guard init-copilot .
copilot
```

This installs:

```text
.github/hooks/project-guard.json
```

The current transparent path is:

```text
userPromptTransformed
    -> Project Guard prepare
    -> modifiedTransformedPrompt
    -> Copilot CLI Agent
```

Read-only and coding E2E were verified for GitHub Copilot CLI on Windows.
However, in the coding E2E the Agent recognized the Task Contract requirement
but created `.project-guard-task-contract.json` after the production edits.
Task Contract ordering therefore remains model-guided, not enforced.

Detailed evidence: [docs/copilot-cli-e2e.md](docs/copilot-cli-e2e.md).

### GitHub Copilot IDE

The repository initialization command is the same:

```bash
project-guard init-copilot .
```

The IDE remains **Experimental - limited integration**. The Copilot CLI
transparent E2E result must not be extrapolated to the IDE. A full transparent
governance loop has not been verified there.

## Manual Governance Workflow

For a platform without a verified transparent integration, or when you want
an explicit handoff, use:

```text
User request
    -> project-guard prepare
    -> Coding Agent reads .project-guard-agent-prompt.md
    -> Agent Task Contract
    -> coding and focused tests
    -> Git Diff
    -> project-guard review
```

Example:

```bash
project-guard prepare . "Add CSV export support"
```

Provide `.project-guard-agent-prompt.md` and the generated governance files to
the Coding Agent. When coding is complete, run:

```bash
project-guard review .
```

Use `project-guard review --help` before adding optional Contract, Plan,
Instructions, Skill, or Task Contract paths.

## Scope Amendments

If the Agent discovers that a necessary production file is outside the
approved scope, it should not silently expand the scope. The intended flow is:

```text
Scope Amendment
    -> reason
    -> user approval
    -> Task Contract update
    -> continue
```

`possible` scope means a file may be used if necessary; it does not mean the
Agent should modify it automatically. Review checks approved amendments and
the actual Git Diff.

## Review

Project Guard Review is an independent governance audit based on:

```text
Engineering Contract
    + Agent Task Contract
    + approved Scope Amendments
    + actual Git Diff
```

Depending on the current findings, output can include `PASS`, `WARNING`, or
`VIOLATION`, together with risk levels such as `LOW`, `MEDIUM`, or `HIGH`.
Review does not prove code correctness, test completeness, absence of bugs, or
absence of security vulnerabilities.

## Known Limitations

- Project Guard does not prove semantic correctness.
- Task Contract creation and adherence remain Agent/model-guided.
- Task Contract ordering can differ by platform.
- There is no universal `preToolUse` or `beforeTool` enforcement.
- There is no shell enforcement or MCP enforcement.
- There is no automatic universal Review lifecycle.
- Hook trust and enablement differ by platform.
- Copilot IDE remains a limited integration.
- Cline file Hook is a legacy experiment.
- Platform updates may change Hook or Plugin behavior.
- Project Guard does not provide a remote governance service, but the Agent
  platform may have its own data handling and privacy behavior.

## E2E Verification Records

Detailed records are kept separately:

- [Codex E2E](docs/codex-e2e.md)
- [Cline CLI Plugin E2E](docs/cline-plugin-e2e.md)
- [TRAE IDE E2E](docs/trae-e2e.md)
- [GitHub Copilot CLI E2E](docs/copilot-cli-e2e.md)

## Development Installation

Regular users do not need to clone Project Guard or use an editable install.
Use the development installation when developing Project Guard itself,
modifying its source, or running its test suite:

```bash
git clone https://github.com/wangboning757-creator/project-guard.git
cd project-guard
pip install -e ".[dev]"
python -m pytest
python -m ruff check .
```

## Release and Distribution

Project Guard v0.6.0 is the next release candidate. v0.5.0 is published as
`project-guard` on PyPI. The release uses the local-first CLI and does not add
a remote Project Guard server.

Publishing workflow details are documented in
[docs/publishing.md](docs/publishing.md). Future changes should preserve the
published package's version immutability and use a new release version for
package-content changes.
