Metadata-Version: 2.4
Name: gendd-governance-cli
Version: 2.0.0
Summary: GenDD Agentic Governance — multi-agent SDLC governance engine (LangGraph)
Author: Hatchworks
License: MIT
License-File: LICENSE
Keywords: governance,langgraph,sdlc,security
Requires-Python: >=3.11
Requires-Dist: argcomplete>=3.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: langchain-anthropic>=0.3.0
Requires-Dist: langchain-aws>=0.2.0
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langchain-google-vertexai>=2.0.0
Requires-Dist: langchain-openai>=0.2.0
Requires-Dist: langchain>=0.3.0
Requires-Dist: langgraph>=0.2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyfiglet>=1.0.0
Requires-Dist: python-frontmatter>=1.0.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: publish
Requires-Dist: build>=1.2.0; extra == 'publish'
Requires-Dist: twine>=5.0; extra == 'publish'
Description-Content-Type: text/markdown

# GenDD Agentic Governance

Portable, multi-agent SDLC governance engine: **diff-based** analysis, organizational rules from the repo’s `**.cursor/rules`** and project `**SKILL.md**` files under `**.cursor/skills**` and `**.claude/skills**`, **OSV.dev** signals, **LangGraph** wiring, distributed as a **Python CLI** with **GitHub Actions** examples.

**Published Python package name:** `gendd-governance-cli` on [PyPI](https://pypi.org/). The import package remains `gendd_governance`.

## Features

- **CLI**: install once and run all governance actions locally. Primary entry point: `**gendd**` (short name). Same program is also exposed as `gendd-governance-cli`, `gendd-governance`, `gendd-agentic-governance`, and `gendd-agentic-governance-cli`.
- **First-time setup**: `gendd init` (interactive wizard) or `gendd init --defaults` (commented template). Writes `**.gendd-agentic-governance/.env**` at the Git repo root and ensures `**.gendd-agentic-governance/**` is in `.gitignore`. See [docs/configuration.md](docs/configuration.md).
- **Run** subcommand: `gendd run <command> …` or shorthand `gendd <command> …` where `<command>` is any of the 16 `ai-*` specialist commands in [docs/agents.md](docs/agents.md); use **`gendd select`** to run several specialists in one pass
- **Last-run snapshot**: each `**run**` or `**select**` writes a best-effort `**.gendd-agentic-governance/last-run.json**` (for tooling or inspection). **`repeat`** reuses that file (version 2+) to run the **same governance command** and **same diff scope** as the last completed run, so you do not have to pass `--base` / `--head` / scope flags again.
- Outputs: console (Rich), JSON, SARIF; optional GitHub PR comments (`--post-pr`)
- Gating: severity thresholds via env (`GENDD_GATE_MAX_*`, `GENDD_ADVISORY_MODE`)
- Default LLM: **Vertex AI** (`GENDD_MODEL_PROVIDER=vertex`); also OpenAI, Azure OpenAI, **AWS Bedrock**, **Anthropic API**
- `**--offline`**: uses an **offline stub LLM** (no GCP / OpenAI calls); still loads `**.cursor` rules and repo skills** from disk for smoke tests

---

## CLI reference

Same program is installed under several names; `**gendd**` is the short name. Use `**gendd --help**`, `**gendd init --help**`, `**gendd run --help**`, and `**gendd repeat --help**` for the full flag list on your installed version.

### Subcommands


| Subcommand   | When to use it                                                                                   | How                                                                                                                                                                                                                                                                                 |
| ------------ | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `**init**`   | First-time setup in a Git repo; refresh local provider/credentials; regenerate a template `.env` | `gendd init` (interactive wizard), or `gendd init --defaults` (commented template, no prompts). Add `**--force**` to overwrite an existing `**.gendd-agentic-governance/.env**`. Ensures `**.gendd-agentic-governance/**` is listed in `.gitignore` and writes **CONFIG.md** there. |
| `**run**`    | Analyze a **diff** with one or more governance agents (default base/ref or PR context in CI)     | `gendd run <agent> [options]` — see [Governance agent commands](#governance-agent-commands) and [Run options](#run-options).                                                                                                                                                        |
| `**select**` | Choose a subset of specialist agents, then the same pipeline as `**run**`                        | `gendd select [options]` — interactive checklist or `**--agents**` (comma-separated labels).                                                                                                                                                                                        |
| `**repeat**` | Re-run the **last** `**run**` or `**select**` with the same agent command and diff scope         | `gendd repeat [run options…]` — reads `**.gendd-agentic-governance/last-run.json**` (must be **version 2+**, written after a successful `**run**` / `**select**`). Accepts the same output and gating flags as `**run**` (for example `**--format**`, `**--offline**`). If the snapshot says the last run used a **GitHub PR** diff, `**repeat**` needs the same PR environment (for example GitHub Actions variables or local `**gh**` context). |


**Shorthand:** if the first argument is already an agent name (`ai-`*), `run` is inserted for you:

```text
gendd ai-review --format json
```

is equivalent to:

```text
gendd run ai-review --format json
```

### Governance agent commands

These are the values for `<agent>` in `gendd run <agent>`. Each one loads `**.cursor/rules**` and `**SKILL.md**` trees under `**.cursor/skills**` / `**.claude/skills**`, attaches an **OSV** summary for the diff where relevant (and deterministic hints for license, infra, performance, telemetry, and a11y where applicable), and runs the LangGraph pipeline for that single specialist. To run **multiple** specialists in parallel on the same diff, use `**gendd select**` (see [docs/agents.md](docs/agents.md)).


| Command                  | When to use it                                                                                                                                                                                      |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `**ai-review**`          | General code review: standards, correctness, and logic issues in the changed lines.                                                                                                                 |
| `**ai-security**`        | Security flaws and unsafe patterns; consumes OSV signals for dependency context.                                                                                                                    |
| `**ai-dependency**`      | Third-party / lockfile changes, upgrade and risk notes.                                                                                                                                             |
| `**ai-test**`            | Test gaps and quality around the diff (does **not** execute the test suite).                                                                                                                        |
| `**ai-maintainability`** | Complexity, readability, and refactor suggestions.                                                                                                                                                  |
| `**ai-architecture**`    | Boundaries, coupling, and structural impact.                                                                                                                                                        |
| `**ai-documentation**`   | Missing or insufficient docs for public or complex changes.                                                                                                                                         |
| `**ai-api-contract**`    | Public API / schema / semver and breaking-change risk.                                                                                                                                              |
| `**ai-migration**`       | Rollout safety: migrations, flags, ordering, rollback.                                                                                                                                              |
| `**ai-performance**`     | Performance and resource risks grounded in the diff.                                                                                                                                                |
| `**ai-telemetry**`       | Product logging, metrics, tracing; sensitive data in telemetry.                                                                                                                                     |
| `**ai-accessibility**`   | UI accessibility when markup or styles change.                                                                                                                                                      |
| `**ai-infra**`           | CI/CD pipelines and Terraform/HCL delivery semantics.                                                                                                                                               |
| `**ai-changelog**`       | User-facing release notes as structured findings.                                                                                                                                                   |
| `**ai-build-hygiene**`   | CI determinism, caching, and flaky-test patterns.                                                                                                                                                   |
| `**ai-compliance**`      | Org policy: licenses, headers, PII/retention rules.                                                                                                                                                 |


### Run options


| Option                   | Default                                                                  | When / how to use                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `**--base**`             | `origin/main`                                                            | Git ref (or name) for the **start** of the diff. Point at your default branch or merge base for PR-style review.                         |
| `**--head**`             | `HEAD`                                                                   | Git ref for the **end** of the diff (usually your branch tip). Use `**--base HEAD --head HEAD**` for a no-op diff smoke test.            |
| `**--format**`           | `console,json`                                                           | Comma-separated outputs: `**console**` (Rich), `**json**`, `**sarif**`. Example: `console,json,sarif`.                                   |
| `**--json-out**` *path*  | *(none)*                                                                 | Write the JSON report to a file. If omitted but `json` is in `--format`, JSON is **printed to stdout** (alongside console if requested). |
| `**--sarif-out*`* *path* | `**governance-result.sarif*`* if `sarif` is selected and this is omitted | SARIF file path for SARIF consumers (CI, security dashboards).                                                                           |
| `**--post-pr**`          | off                                                                      | Post a summary comment on the **GitHub pull request** when the environment indicates a PR (for example in Actions).                      |
| `**--offline**`          | off                                                                      | **Stub LLM**: no cloud model calls; use for CI smoke tests and verifying rules/context loading. Still resolves diff and rules from disk. |


**Gating:** exit code `**0**` if the severity gate passes, `**1**` if it fails (unless advisory mode relaxes this — see [docs/configuration.md](docs/configuration.md)). `**2**` is used for configuration or runtime errors (for example rules load or model init). `**130**` on interrupt.

---

## Install from PyPI

**Prerequisites:** Python 3.11+

**pip** (inside a virtual environment)

```bash
pip install gendd-governance-cli
```

**pipx** (global `gendd` on `PATH` without a project venv)

```bash
pipx install gendd-governance-cli
```

**uv** (`uv tool install`)

```bash
uv tool install gendd-governance-cli
```

**Verify**

```bash
gendd --help
```

---

## Publish a new version (maintainers)

Releases are published to **public PyPI** with **[Trusted Publishing](https://docs.pypi.org/trusted-publishers/)** (OIDC from GitHub Actions — `pypa/gh-action-pypi-publish`). No long-lived PyPI API token is stored in this repository.

1. On **[pypi.org](https://pypi.org/)**, for project **`gendd-governance-cli`**: **Manage → Publishing** → add a **trusted publisher** of type **GitHub** with this **repository**, workflow file **`ci.yml`**, and the **environment** name **`prod`** (must match the `environment:` on the `publish` job in [`.github/workflows/ci.yml`](.github/workflows/ci.yml)). See [adding a trusted publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/). For the first project published via OIDC, follow [creating a project through OIDC](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) as needed.
2. **Bump version** in [`pyproject.toml`](pyproject.toml) (`[project].version`) following your semver policy. **PyPI rejects re-uploads** of the same version, so each release needs a **new** version string.
3. **Open a PR and merge to `main`** (or `master`). [`.github/workflows/ci.yml`](.github/workflows/ci.yml) runs `ruff check`, `pytest`, `build`, and `twine check` on PRs; it **publishes to PyPI** only on **push** (including merge commits) to `main`/`master`, or **manual** `workflow_dispatch` on that branch.
4. **After any legacy Google Artifact Registry stack for this project is fully decommissioned**, remove GitHub **secrets/variables** that only supported the old private publish path (for example `GCP_WORKLOAD_IDENTITY_PROVIDER`, `GCP_SERVICE_ACCOUNT_EMAIL`, `GCP_PROJECT_ID`, `GCP_ARTIFACT_REGISTRY_*`). The workflow no longer reads them. See [terraform/README.md](terraform/README.md) for decommissioning context.

---

## Use the CLI in another GitHub repository (consumer CI)

Install from PyPI in the workflow; no private index or Google auth is required for the public package.

```yaml
permissions:
  contents: read

jobs:
  governance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }

      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }

      - run: pip install gendd-governance-cli

      - run: gendd ai-review --offline --format json
```

---

## Quickstart (local development from source)

```bash
python -m venv .venv
.venv\Scripts\activate   # or source .venv/bin/activate

# Windows: py -3.12 -m venv .venv  then  source .venv/Scripts/activate

pip install -e ".[dev]"
python -m gendd_governance help
```

Configure the model provider and credentials via `**gendd init**` (writes `**.gendd-agentic-governance/.env**`) and/or environment variables as described in [docs/configuration.md](docs/configuration.md). Organizational rules live in the repository under analysis (see [docs/configuration.md](docs/configuration.md) § project rules).

### Offline smoke (no cloud LLM)

```bash
python -m gendd_governance help --offline --format json --base HEAD --head HEAD
```

---

## GitHub Actions in this repo


| Workflow                                                                     | Purpose                                                                                                                                                                                            |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[.github/workflows/ci.yml](.github/workflows/ci.yml)`                       | `ruff check`, `pytest`, `build`, `twine check` on every PR and on pushes to `main`/`master`; **publish to PyPI** (Trusted Publishing / OIDC) on push or `workflow_dispatch` to `main`/`master`     |
| `[.github/workflows/ai-governance.yml](.github/workflows/ai-governance.yml)` | Example offline `gendd ai-review` smoke run                                                                                                                                                        |


---

## Troubleshooting


| Issue                                       | What to check                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Package not found** on `pip install`   | [PyPI project](https://pypi.org/project/gendd-governance-cli/) published and name spelling is `gendd-governance-cli`.                                                                                                                                                                                                                                                                                                                                                                       |
| **Dependency resolution failures**         | Public dependencies resolve from PyPI with a normal `pip install gendd-governance-cli`. If you are behind a strict proxy, ensure PyPI and dependency wheels are allowed.                                                                                                                                                                                                                                                                                                                      |
| **Publish fails in GitHub Actions**        | [Trusted publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/) on PyPI: repository, workflow file `ci.yml`, and environment `prod` must match. Version in `pyproject.toml` must be new. Job needs `id-token: write` (already set). **Fork PRs:** use merge-to-`main` so the base repo’s `push` workflow runs with secrets.                                                                                                                                            |
| `**importlib.metadata` / version unknown**  | Install the distribution named `gendd-governance-cli`; logs use that name by default (`GENDD_SERVICE_NAME` overrides).                                                                                                                                                                                                                                                                                                                                                                       |


---

## Documentation

- [Architecture](docs/architecture.md)
- [Configuration](docs/configuration.md)
- [Agents](docs/agents.md)
- [Adoption](docs/adoption.md)
- [Observability](docs/observability.md) (structured logs for CI and log shippers, `GENDD_LOG_*`)
- [terraform/README.md](terraform/README.md) (notes after GCP decommission; Terraform definitions were removed from this tree)

## License

MIT — see [LICENSE](LICENSE).
