Metadata-Version: 2.5
Name: HomericIntelligence-Hephaestus
Version: 0.10.4
Summary: Shared utilities and tooling for the HomericIntelligence ecosystem
Project-URL: Homepage, https://github.com/HomericIntelligence/Hephaestus
Project-URL: Repository, https://github.com/HomericIntelligence/Hephaestus
Project-URL: Issues, https://github.com/HomericIntelligence/Hephaestus/issues
Author: Micah Villmow <research@villmow.us>
License-Expression: BSD-3-Clause
License-File: LICENSE
License-File: NOTICE
Keywords: helpers,homericintelligence,tooling,utilities
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: <3.14,>=3.13
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: packaging<27,>=21.0
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: tzdata<2027,>=2026.2; platform_system == 'Windows'
Provides-Extra: all
Requires-Dist: defusedxml<1,>=0.7; extra == 'all'
Requires-Dist: jsonschema<5,>=4.0; extra == 'all'
Requires-Dist: markdown-it-py<5,>=4.0; extra == 'all'
Requires-Dist: nats-py<3,>=2.6; extra == 'all'
Requires-Dist: pydantic<3,>=2.12.5; extra == 'all'
Requires-Dist: pygithub<3,>=2.9.1; extra == 'all'
Provides-Extra: automation
Requires-Dist: markdown-it-py<5,>=4.0; extra == 'automation'
Requires-Dist: pydantic<3,>=2.12.5; extra == 'automation'
Provides-Extra: github
Requires-Dist: pygithub<3,>=2.9.1; extra == 'github'
Provides-Extra: nats
Requires-Dist: nats-py<3,>=2.6; extra == 'nats'
Provides-Extra: schema
Requires-Dist: jsonschema<5,>=4.0; extra == 'schema'
Provides-Extra: toml
Provides-Extra: xml
Requires-Dist: defusedxml<1,>=0.7; extra == 'xml'
Description-Content-Type: text/markdown

# Hephaestus

[![Test](https://github.com/HomericIntelligence/Hephaestus/actions/workflows/test.yml/badge.svg)](https://github.com/HomericIntelligence/Hephaestus/actions/workflows/test.yml)
[![Security](https://github.com/HomericIntelligence/Hephaestus/actions/workflows/security.yml/badge.svg)](https://github.com/HomericIntelligence/Hephaestus/actions/workflows/security.yml)
[![Release](https://github.com/HomericIntelligence/Hephaestus/actions/workflows/release.yml/badge.svg)](https://github.com/HomericIntelligence/Hephaestus/actions/workflows/release.yml)
[![Auto Tag](https://github.com/HomericIntelligence/Hephaestus/actions/workflows/auto-tag.yml/badge.svg)](https://github.com/HomericIntelligence/Hephaestus/actions/workflows/auto-tag.yml)
[![PyPI](https://img.shields.io/pypi/v/HomericIntelligence-Hephaestus.svg)](https://pypi.org/project/HomericIntelligence-Hephaestus/)
[![Python](https://img.shields.io/pypi/pyversions/HomericIntelligence-Hephaestus.svg)](https://pypi.org/project/HomericIntelligence-Hephaestus/)
[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)

Shared utilities and tooling for the HomericIntelligence ecosystem, powered by [uv](https://uv.sh) for environment management.

## Overview

Hephaestus provides standardized utility functions and tools that can be shared across all HomericIntelligence repositories. Following the principles in [AGENTS.md](AGENTS.md), this project emphasizes:

- **Modularity**: Well-defined, reusable components
- **Simplicity**: KISS (Keep It Simple, Stupid) principle
- **Consistency**: Standardized interfaces and patterns
- **Reliability**: Comprehensive testing and error handling

**Project Status:** See [docs/ROADMAP.md](docs/ROADMAP.md) for the public roadmap and current focus areas.

## Installation

### From PyPI

Hephaestus is published to PyPI under the ecosystem-branded distribution name **`HomericIntelligence-Hephaestus`**. The import name, however, is the short lowercase `hephaestus`:

```bash
pip install HomericIntelligence-Hephaestus
```

```python
import hephaestus
print(hephaestus.__version__)
```

> **Upgrading?** When moving across a major version, read the
> [migration guide](docs/MIGRATION.md) for required consumer changes.
>
> **Note on naming.** `pip install hephaestus` will **not** find this package — the bare name is unowned on PyPI. The `HomericIntelligence-<Name>` prefix is the deliberate naming convention shared across the HomericIntelligence ecosystem (Keystone, Odyssey, etc.) to avoid PyPI namespace collisions; the distribution is `HomericIntelligence-Hephaestus`. Wheel filenames are PEP 625 normalized to lowercase, so you will see `homericintelligence_hephaestus-<version>-py3-none-any.whl` on disk and in release assets.

### Optional dependencies

`pyproject.toml` defines several extras groups. `[all]` is a **runtime** aggregator
and intentionally excludes `[dev]` (which carries test/lint tooling such as
pytest, ruff, and mypy):

- `pip install HomericIntelligence-Hephaestus[all]` — installs all runtime
  extras: `automation`, `github`, `nats`, `toml`, `xml`, `schema`. Note that
  `automation` is the product layer (`hephaestus.automation`) and pulls in
  `pydantic`; see [ADR 0001](docs/adr/0001-automation-library-boundary.md).
- `uv sync` — installs the editable project plus its default development and
  automation dependency groups for contributors.
- `uv sync --all-groups --all-extras --locked` — installs the complete locked
  dependency surface used by CI dependency and license checks.
- Individual extras (e.g. `[github]`, `[schema]`) are available for users who
  only need one integration.

### Development setup

For local development, [install uv](https://uv.sh/install/) and
[`just`](https://just.systems/), then bootstrap the project (installs deps, the
editable package, and pre-commit hooks in one step):

```bash
just bootstrap
```

See [CONTRIBUTING.md → Development Setup](CONTRIBUTING.md#development-setup) for
the full workflow, including the manual fallback if you do not have `just`.

## Library vs product layer

Hephaestus ships two layers from one distribution:

- **Library** — `hephaestus.{utils, io, config, logging, cli, system,
  github, validation, resilience, markdown, ci, benchmarks, datasets,
  discovery, forensics, nats, version, agents}`. Loaded lazily by
  `import hephaestus`.
- **Product** — `hephaestus.automation`. Opt-in via
  `pip install HomericIntelligence-Hephaestus[automation]`. Implements
  the Claude/Codex automation pipeline (Planner, Implementer, CIDriver,
  reviewers, loop runner, curses TUI).

`import hephaestus` does **not** load `hephaestus.automation`, `curses`,
`fcntl`, or `pydantic`, and a base `pip install` no longer pulls `pydantic`
(it ships only in the `[automation]` extra). The boundary is enforced by
`tests/unit/validation/test_import_surface.py` and
`tests/unit/validation/test_automation_boundary.py`. See
[`docs/adr/0001-automation-library-boundary.md`](docs/adr/0001-automation-library-boundary.md).

## Repository navigation

This index covers every tracked top-level path except `README.md` itself and
the legacy compatibility pointer. The navigation guard in
`tests/unit/validation/test_readme_subpackage_tree.py` requires new tracked
root entries to be added here. Checkout-only state and
ignored generated output such as `.git/`, `.venv/`, `.pytest_cache/`, and
`build/` are intentionally outside this index.

### Source and supporting material

| Path | Purpose |
| --- | --- |
| [hephaestus/](hephaestus/) | Python package, including the utility library and optional automation product layer. |
| [tests/](tests/) | Unit and integration test suites. |
| [docs/](docs/) | User documentation, architecture decisions, roadmap, and release guidance. |
| [scripts/](scripts/) | Maintenance, validation, demonstration, and operational scripts. |
| [.github/](.github/) | GitHub templates, ownership rules, dependency automation, and workflows. |
| [.claude/](.claude/) | Repository-scoped Claude settings, security guidance, and development workflow. |
| [.vscode/](.vscode/) | Shared VS Code extensions, settings, and debug configuration. |

### Project and policy documents

| Path | Purpose |
| --- | --- |
| [AGENTS.md](AGENTS.md) | Authoritative repository and agent-development contract. |
| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community conduct expectations. |
| [COMPATIBILITY.md](COMPATIBILITY.md) | Supported versions and compatibility policy. |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Contributor setup, development, and pull-request workflow. |
| [LICENSE](LICENSE) | BSD 3-Clause license terms. |
| [NOTICE](NOTICE) | Attribution and third-party notice information. |
| [PRIVACY.md](PRIVACY.md) | Privacy, retention, and deletion policy. |
| [SECURITY.md](SECURITY.md) | Vulnerability reporting and security-support policy. |

### Build and dependency metadata

| Path | Purpose |
| --- | --- |
| [pyproject.toml](pyproject.toml) | Package metadata, dependencies, entry points, build settings, and Python tool configuration. |
| [uv.lock](uv.lock) | Reproducible resolved dependency set. |
| [justfile](justfile) | Canonical contributor command shortcuts. |
| [coverage.toml](coverage.toml) | Coverage collection, reporting, and omit policy. |

### Repository tool configuration

| Path | Purpose |
| --- | --- |
| [.codexignore](.codexignore) | Paths excluded from Codex context discovery. |
| [.editorconfig](.editorconfig) | Cross-editor formatting defaults. |
| [.fleet.yml](.fleet.yml) | Fleet synchronization organization and repository inventory. |
| [.gitattributes](.gitattributes) | Git text and line-ending normalization. |
| [.gitignore](.gitignore) | Ignored generated, local, and sensitive paths. |
| [.heph-project-denylist](.heph-project-denylist) | Centrally enforced project privacy and PII denylist. |
| [.markdownlint.yaml](.markdownlint.yaml) | Markdown lint policy. |
| [.mcp.json](.mcp.json) | Repository MCP server declarations. |
| [.pip-audit-ignore.txt](.pip-audit-ignore.txt) | Documented dependency-audit suppressions. |
| [.pre-commit-config.yaml](.pre-commit-config.yaml) | Pre-commit quality and policy hooks. |
| [.yamllint.yaml](.yamllint.yaml) | YAML lint policy. |

## Getting Started with uv

This project uses [uv](https://uv.sh) for environment management, which automatically handles dependencies and creates isolated environments.

> **Platform note:** uv supports this project's Python 3.13 development
> environment on Linux, macOS, and Windows. The required GitHub Actions jobs
> currently run on Linux; POSIX-specific tests are marked to skip on native
> Windows. See [CONTRIBUTING.md#platform-support](CONTRIBUTING.md#platform-support).

### Prerequisites

Install uv by following the [official installation guide](https://uv.sh/install/).

### Setup Development Environment

Bootstrap the project in one step (see
[CONTRIBUTING.md → Development Setup](CONTRIBUTING.md#development-setup) for the
full workflow and the no-`just` fallback):

```bash
just bootstrap
```

### Running Tests

```bash
# Run all tests (unit + integration)
just test
uv run pytest

# Run only unit tests (coverage-gated in CI)
just test-unit
uv run pytest tests/unit

# Run only integration tests
just test-integration
uv run pytest tests/integration

# Run all tests except integration
uv run pytest -m "not integration"
```

All integration tests carry `pytest.mark.integration` (module-level `pytestmark`),
so marker-based selection is reliable.

### Development Commands

```bash
# Format code with ruff
just format
uv run ruff format hephaestus scripts tests

# Lint code with ruff
just lint
uv run ruff check hephaestus scripts tests
```

## Usage

### As a Package

After installing with uv:

```python
from hephaestus import slugify, human_readable_size, retry_with_backoff

# Convert text to URL-friendly slug
project_slug = slugify("My Project Name")
print(project_slug)  # Output: my-project-name

# Convert bytes to human readable size
size_str = human_readable_size(1048576)
print(size_str)  # Output: 1.0 MB
```

### Installing in Another Project

Hephaestus is published to PyPI as `homericintelligence-hephaestus`.
The wheel is pure-Python and installs on Linux, macOS, and Windows
(see `requires-python` in [`pyproject.toml`](pyproject.toml)). This is
the supported install path for non-Linux platforms.

**Using pip:**

```bash
pip install homericintelligence-hephaestus
```

**Using uv:**

Add to `pyproject.toml`:

```toml
[project]
dependencies = [
    "homericintelligence-hephaestus>=0.9,<1",
]
```

Then run `uv sync` to resolve the dependency.

After 1.0 ships, bump these constraints to `>=1.0,<2`.

**For local development (path dependency):**

```bash
uv add --editable ../Hephaestus
```

## Key Features

### General Utilities (`hephaestus.utils`)

- `slugify(text)`: Convert text to URL-friendly slug
- `retry_with_backoff(func)`: Decorator for exponential backoff retries
- `human_readable_size(bytes)`: Convert bytes to human readable format
- `flatten_dict(dict)`: Flatten nested dictionaries
- `run_subprocess(cmd)`: Execute shell commands with error handling
- `run_git(args, retries=None)`: Execute Git commands through the shared subprocess adapter with bounded timeout and network retry protection
- `get_setting(config, key_path)`: Get nested dict values with dot notation

Local metadata subprocesses, including the version git-tag probe, default to
10 seconds. `HEPHAESTUS_SUBPROCESS_METADATA_TIMEOUT` accepts integer values
from 1 through 86400 seconds; malformed or out-of-range values emit a bounded
warning and use the 10-second default. Terminal restoration uses a fixed
2-second cleanup timeout and has no override.

### Configuration (`hephaestus.config`)

- `load_config(path)`: Load YAML or JSON configuration files
- `get_setting(config, key_path)`: Dot-notation config access
- `merge_configs(*configs)`: Deep-merge multiple configuration dicts
- `merge_with_env(config, prefix)`: Overlay environment variables onto config

#### Environment Variable Convention

`merge_with_env` maps environment variables to config keys using **double underscore (`__`) as the nesting delimiter**. Single underscores are preserved as part of the key name.

| Environment Variable | Config Key |
|---|---|
| `HEPHAESTUS_DATABASE__HOST` | `{"database": {"host": ...}}` |
| `HEPHAESTUS_MAX_CONNECTIONS` | `{"max_connections": ...}` |
| `HEPHAESTUS_DATABASE__MAX_RETRIES` | `{"database": {"max_retries": ...}}` |

Numeric strings are automatically converted to `int` or `float`. To also convert boolean-like strings (`true`/`false`/`yes`/`no`/`on`/`off`) to Python `bool`, pass `convert_bools=True`:

```python
from hephaestus.config.utils import merge_with_env

# HEPHAESTUS_DEBUG=true → {"debug": True} (not the string "true")
config = merge_with_env({}, convert_bools=True)
```

### I/O Utilities (`hephaestus.io`)

- `read_file(path)` / `write_file(path, content)`: Simple file I/O
- `load_data(path)` / `save_data(path, data)`: Structured data (JSON/YAML)

## CLI Commands

Run any command with `--help` to see full usage.

The package currently installs 57 console scripts from `[project.scripts]`.

### Automation

| Command | Description |
|---|---|
| `hephaestus-automation-loop` | Multi-repo queue-based automation pipeline using Claude Code or Codex (repo → planning → plan_review → implementation → pr_review → merge_wait → finished; restarted implementation-GO inputs re-enter `merge_wait` with their loop-owned approval label) |
| `hephaestus-install-pi-plugins` | Install and preflight the catalog-pinned Pi CLI package set; passing this gate does not bypass #2518 |
| `hephaestus-plan-issues` | Bulk issue planning using Claude Code or Codex |
| `hephaestus-implement-issues` | Bulk issue implementation using Claude Code or Codex in parallel worktrees |
| `hephaestus-review-prs` | PR review/remediation automation using Claude Code or Codex in parallel worktrees; reviewer agents are read-only, while the coordinator may apply implementation fixes and reconcile threads |
| `hephaestus-agent-stage` | Run one Claude or Codex automation stage with prompt and skill context |
| `hephaestus-ensure-state-labels` | Idempotently provision the planning labels (`state:needs-plan`, `state:plan-no-go`, `state:plan-go`, and `state:plan-blocked`) on one or more repos |
| `hephaestus-audit-prs` | Audit ALL open PRs in one coordinator agent invocation |
| `hephaestus-drive-prs-green` | Review directly scoped PRs or PRs linked from discovered issues through the pr_review/merge_wait pipeline slice; it does not sweep unrelated open PRs |

`hephaestus-plan-issues` exits `75` when open-issue discovery is deferred by
a GitHub rate limit. This is a retryable temporary failure, not success. With
`--json`, `reset_epoch` is the known reset epoch or `null`, `affected_issues`
is `null` when discovery could not enumerate them, and
`incomplete_issue_scope` identifies the affected repository selection. Retry
without `--force`; issues already at or past `state:plan-go` remain completed
and are not planned again.

#### Private Pi provider setup

Pi uses operator-local provider configuration only. Do not commit Pi provider
config, endpoint URLs, hostnames, checkpoint names, model identifiers, or local
aliases. Configure the OpenAI-compatible provider in the local Pi config, set
`HEPH_PI_PROVIDER=<operator-local-provider-alias>` and
`HEPH_PI_MODEL=<operator-local-alias>` for the explicit smoke sentinel, and see
[`docs/pi-private-provider.md`](docs/pi-private-provider.md) for the sanitized
setup and denylist guard. That smoke seam does not yet select those values
through Pi's native provider/model contract. Run
`hephaestus-install-pi-plugins --dry-run --json` to inspect the exact package
plan and `hephaestus-install-pi-plugins --global --yes --no-approve` to install
the safe global defaults. Passing package preflight does not admit normal Pi
automation: in a standard installation, `--agent pi` fails before stage or
wrapper dispatch because no OS-isolation adapter is bundled. A trusted host
integration must provide a named `hephaestus.pi_isolation_adapters` entry point,
and the operator must select it with `HEPH_PI_ISOLATION_ADAPTER`. That adapter
enforces the resolved filesystem and network policy; the local setup otherwise
supports only the explicit adapter-smoke seam.

#### Running the automation loop from a source checkout (macOS / Codex)

When `hephaestus-automation-loop` is not installed on `PATH` (fresh source
checkout) and Claude is not installed, invoke the loop through `uv` and pin
Codex as the agent:

```bash
# Prerequisites
command -v uv             # uv installed
command -v codex && codex login status   # Codex authenticated
command -v gh && gh auth status          # gh authenticated

# Title-scoped loop over open "nitpick" / "minor" issues
issues=$(
  gh issue list --state open --limit 500 --json number,title \
    --jq '.[] | select((.title | ascii_downcase) | test("(^|[^a-z0-9_])(nitpick|minor)([^a-z0-9_]|$)")) | .number' \
  | sort -n -u | paste -sd, -
)

test -n "$issues" \
  && uv run hephaestus-automation-loop --issues "$issues" --agent codex \
  || echo "No open nitpick/minor title issues found"
```

If the pre-loop `git fetch` is denied (e.g. macOS sandboxing returns
`error: cannot open .git/FETCH_HEAD: Operation not permitted`) the loop now
logs a WARNING and renders the trunk line as `[Repo] trunk=<sha> (stale)`
so the refresh failure is visible rather than silently treated as a clean
sync (#993).

### GitHub

| Command | Description |
|---|---|
| `hephaestus-fleet-sync` | Sync all PRs across the HomericIntelligence fleet |
| `hephaestus-gh` | Run `gh` through Hephaestus retry, circuit-breaker, and throttle handling |
| `hephaestus-github-stats` | GitHub contribution statistics via the `gh` CLI |
| `hephaestus-label-severity` | Reconcile the `severity:*` label for a GitHub issue from its issue-form Severity answer |
| `hephaestus-merge-prs` | Merge open PRs with successful CI/CD through the shared `gh` adapter |
| `hephaestus-tidy` | Single-repo gh-tidy wrapper with Myrmidon swarm for conflict resolution |
| `hephaestus-prepare-worktree` | Safely create an isolated worktree at an attested start point |
| `hephaestus-audit-worktrees` | Emit a read-only inventory of registered worktrees |
| `hephaestus-remove-worktree` | Remove one approved, clean registered worktree at its audited HEAD |
| `hephaestus-resolve-pr` | Resolve an explicit or current-branch open pull request |
| `hephaestus-collect-pr-evidence` | Collect pull-request metadata, changed paths, and check evidence |
| `hephaestus-pr-diff-context` | Compute author-intent and current-base pull-request diff ranges |
| `hephaestus-repository-evidence` | Collect bounded Git history and source-pattern evidence |

`hephaestus-merge-prs` exits `0` only when every discovered PR was merged,
successfully queued, or intentionally skipped by `--dry-run`. It exits `1`
when any requested PR is blocked, fails, or is unexpectedly left unprocessed,
and exits `130` when interrupted. With `--json`, every outcome—including
failure or interruption before PR discovery—contains `results`, `totals`,
`requested`, and `processed`; pre-discovery outcomes use an empty result list,
zero totals, and zero requested/processed counts.

### System & Data

| Command | Description |
|---|---|
| `hephaestus-agent-stats` | Agent statistics aggregation and reporting |
| `hephaestus-download-dataset` | Dataset downloading utilities for Hephaestus |
| `hephaestus-system-info` | System information collection utilities for Hephaestus |

### Debugging & Forensics

| Command | Description |
|---|---|
| `hephaestus-coredump-handler` | Kernel pipe-mode `core_pattern` handler for capturing cores from containerized crashes |
| `hephaestus-run-under-gdb` | Run any command under `gdb -batch` to capture a real core before a runtime's own signal handler swallows the fault |

`hephaestus-run-under-gdb` limits gdb and `RUN_UNDER_GDB=0` execution to
7200 seconds by default. Pass `--timeout SECONDS` before `<core-dir>` to select
a value from 1 through 86400. On timeout, POSIX platforms kill and boundedly
reap the dedicated process group; platforms without process-group support kill
and boundedly reap the direct child instead. Timeouts exit `124`. Lack of POSIX
process-group support does not prevent normal execution.

### Validation

| Command | Description |
|---|---|
| `hephaestus-audit-doc-policy` | Audit documentation command examples for policy violations |
| `hephaestus-check-api-reference` | Verify generated pdoc API reference output contains subpackage pages |
| `hephaestus-check-api-table-docs` | Enforce per-symbol `__all__` documentation in COMPATIBILITY.md |
| `hephaestus-check-cli-tier-docs` | Enforce console-script stability-tier documentation in COMPATIBILITY.md |
| `hephaestus-check-complexity` | Check cyclomatic complexity against a threshold |
| `hephaestus-check-coverage` | Check test coverage against configurable thresholds |
| `hephaestus-check-doc-config` | Enforce consistency between documentation metric values and authoritative config sources |
| `hephaestus-check-docstrings` | Check Python docstrings for genuine sentence fragments |
| `hephaestus-check-python-version` | Check Python version consistency across project configuration files |
| `hephaestus-check-readmes` | Markdown validation utilities for HomericIntelligence projects |
| `hephaestus-check-stale-scripts` | Detect scripts in `scripts/` with no references in CI configs or other scripts |
| `hephaestus-check-test-structure` | Validate unit test directory structure |
| `hephaestus-check-tier-labels` | Enforce tier label consistency across all project Markdown files |
| `hephaestus-check-type-aliases` | Detect type alias shadowing patterns in Python code |
| `hephaestus-check-unlinked-todo` | Enforce that every TODO/FIXME/HACK marker references a tracking issue |
| `hephaestus-filter-audit` | Validate pip-audit evidence and fail on HIGH, CRITICAL, or unscored advisories |
| `hephaestus-mypy-each-file` | Run mypy on each file individually to avoid duplicate-module-name errors |
| `hephaestus-validate-agents` | YAML frontmatter extraction and validation for agent markdown files |
| `hephaestus-validate-links` | Markdown validation utilities for HomericIntelligence projects |
| `hephaestus-validate-schemas` | Validate YAML configuration files against JSON schemas |

### Markdown

| Command | Description |
|---|---|
| `hephaestus-check-links` | Fix or validate invalid absolute path links in markdown files |
| `hephaestus-fix-markdown` | Markdown linting fixer utilities for Hephaestus |
| `hephaestus-validate-anchors` | Validate anchor fragments in markdown links against actual headings |

### CI / Pre-commit

| Command | Description |
|---|---|
| `hephaestus-bench-precommit` | Pre-commit CI utilities for GitHub Actions integration (benchmark) |
| `hephaestus-check-workflow-inventory` | GitHub Actions workflow validation utilities (inventory check) |
| `hephaestus-validate-workflow-checkout` | GitHub Actions workflow validation utilities (checkout validation) |

### Development Utilities

| Command | Description |
|---|---|
| `hephaestus-scaffold-subpackage` | Scaffold a minimal importable subpackage with a structural unit test and no behavior stubs |

### Configuration & Dependencies

| Command | Description |
|---|---|

### Version Management

| Command | Description |
|---|---|
| `hephaestus-bump-version` | Preview static-project bumps; refuses hatch-vcs state and directs releases to signed tags |
| `hephaestus-check-package-versions` | Check optional package and documentation version references against the canonical tag |
| `hephaestus-check-version-consistency` | Verify an expected version matches the canonical tag and installed distribution |

### Examples

```bash
# Collect system info (JSON output)
hephaestus-system-info --json

# Collect system info without tool version checks
hephaestus-system-info --no-tools

# Download a dataset
hephaestus-download-dataset --help

# Merge open PRs
hephaestus-merge-prs --help

# Run all validation checks
hephaestus-check-coverage --help
hephaestus-check-complexity --help
```

## Development Guidelines

1. Follow the principles in [AGENTS.md](AGENTS.md)
2. Write comprehensive unit tests for all new functionality
3. Document all public functions with Google-style docstrings
4. Use type hints for all function parameters and return values
5. Keep functions small and focused (single responsibility principle)

## Contributing

The `main` branch is protected; all changes go through a pull request. The active
ruleset requires signed commits, while `pr-policy` checks issue references,
Conventional Commit subjects, and DCO trailers. The loop runs
`$athena:pr-review`; its prose and grade are audit evidence, not authorization.
`pr_review` writes `state:implementation-go` only when a structural audit and
fresh live GitHub head, thread, and exclusive-label facts permit that
transition. The GitHub label is the loop's sole durable implementation-state
authority. `merge_wait` revalidates the current-process proof and conditionally
squash-merges that exact head; it does not create, disable, adopt, or poll an
auto-merge request. Normal review may collect CI/CD evidence as context, but
the loop does not change CI/CD. Required CI/CD checks are the merge contract.

1. Create a feature branch named `<issue-number>-description`
   (`git checkout -b 123-amazing-feature`).
2. Commit your changes with both attestations (`git commit -s -S -m "feat(scope): add amazing feature"`),
   using [conventional commit](https://www.conventionalcommits.org/) messages.
3. Push the branch (`git push -u origin 123-amazing-feature`).
4. Open a pull request titled `type(scope): concise description` whose body
   contains the literal line `Closes #123` (capital `C`, no colon, on its own
   line — `Fixes`/`Resolves` are **not** accepted). The title becomes the
   squash-merge subject on `main`.
5. Do not enable auto-merge manually. The automation loop's review, label, and
   `merge_wait` preserves the head-bound approval boundary with a
   SHA-conditional normal merge and never mutates native auto-merge.

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full process.

## uv Environment

`uv sync` creates this checkout's `.venv` and installs the project in editable
mode. The default dependency groups include the development and automation
tools; run repository commands with `uv run <command>` so they use that locked
environment. Use `uv sync --all-groups --all-extras --locked` when a workflow
or local check must exercise the complete dependency surface represented by
`uv.lock`.

## Adding New Dependencies

Use uv to add a runtime dependency, then refresh the environment:

```bash
uv add requests
uv sync
```

## License

BSD 3-Clause License — see [LICENSE](LICENSE) for the full text, and
[NOTICE](NOTICE) for third-party dependency licenses and compatibility notes.
