Metadata-Version: 2.5
Name: HomericIntelligence-Hephaestus
Version: 0.11.0
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: sigstore<5,>=4.5; extra == 'all'
Provides-Extra: automation
Requires-Dist: markdown-it-py<5,>=4.0; extra == 'automation'
Requires-Dist: pydantic<3,>=2.12.5; extra == 'automation'
Requires-Dist: sigstore<5,>=4.5; extra == 'automation'
Provides-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

[![Required Checks](https://github.com/HomericIntelligence/Hephaestus/actions/workflows/_required.yml/badge.svg)](https://github.com/HomericIntelligence/Hephaestus/actions/workflows/_required.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.
- The `[github]` extra is an empty compatibility extra. GitHub commands use the
  external `gh` command and this extra installs no Python dependency.
- Individual dependency-bearing extras (e.g. `[nats]`, `[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, observability, prompts, scripts_lib, version,
  agents}`. Loaded lazily by
  `import hephaestus`.
- **Product** — `hephaestus.automation`. Opt-in via
  `pip install HomericIntelligence-Hephaestus[automation]`. Implements
  the queue pipeline for planning, implementation, review, merge, learning,
  and cleanup. Claude Code, Codex, OpenCode, and admitted Pi providers run
  agent jobs through the shared runtime.

`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. |
| [ci/](ci/) | Container build inputs for the pinned CI image (Containerfile). |
| [.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 the fast pre-commit and pull-request test selection
just test

# Run the full nightly normal-test complement
just test-nightly

# Run the fast unit selection
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

#### Explicit configuration

Hephaestus does not overlay `HEPH_*` or `HEPHAESTUS_*` environment variables
onto application configuration. Load a configuration file, parse command-line
options at the application boundary, and merge those explicit values:

```python
from hephaestus.config import load_config, merge_configs

file_config = load_config("hephaestus.yml")
cli_overrides = {"database": {"host": args.database_host}}
config = merge_configs(file_config, cli_overrides)
```

See the [environment-variable registry](docs/environment-variables.md) for the
remaining narrowly approved runtime variables and the deny-by-default policy.

### 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 57 console scripts are declared in `[project.scripts]` in
[`pyproject.toml`](pyproject.toml).

### Automation

Codex implementation uses the native direct runner when no isolation adapter
is selected. This temporary path uses shared host state in `HOME/.codex`.
An explicit adapter selection still requires complete, valid deployment
evidence and never falls back after failure. See
[ADR-0043](docs/adr/0043-optional-codex-adapter-until-production-ready.md) and
[the production adapter issue](https://github.com/HomericIntelligence/Hephaestus/issues/3062).

| Command | Description |
|---|---|
| `hephaestus-automation-loop` | Run all six main queues and the auxiliary learning and cleanup queues |
| `hephaestus-fleet-worker` | Run the private Codex worker and inspect Fleet execution receipts |
| `hephaestus-fleet-build-artifacts` | Serve registered retained build logs over private loopback HTTPS |
| `hephaestus-plan-issues` | Run `planning → plan_review` through the same coordinator |
| `hephaestus-implement-issues` | Run `implementation → pr_review → merge_wait` through the same coordinator |
| `hephaestus-review-prs` | Run the `pr_review` scope through the same coordinator |
| `hephaestus-install-pi-plugins` | Install and check the pinned Pi packages; provider admission remains required |
| `hephaestus-ensure-state-labels` | Create the required planning and repository labels |
| `hephaestus-reconcile-implementation-labels` | Clear a stale `state:implementation-go` label when the current-head verdict is `NO-GO` |

The [Fleet worker contract](docs/fleet-worker.md) describes the separate
app-server adapter, private attachment, and recovery limits. Fleet does not
change the existing queue's label or publication authority.

The [private build-log service](docs/fleet-build-artifacts.md) supplies retained
output to Agamemnon. Its operator configuration binds existing evidence; it
does not grant build execution or prove producer deployment.

The four queue commands use one parser in `pipeline_cli.py`. The full loop
accepts `--stages` with contiguous main stage names in queue order. Learning
and cleanup are implicit. Use `--merge-attempts` for the merge request budget
and `--max-workers` for main worker capacity. Use `--learning-workers` and
`--learning-queue-capacity` for the separate auxiliary lane.

The implementation stage owns all branch changes, tests, commits, pushes, and
implementation replies. PR review owns a detached source checkout and review
evidence. Before merge, the pipeline requires review proof from the current
process, passing required checks for that exact head, complete thread state,
and the server merge route required by repository policy. A recovered label
or publication receipt cannot replace fresh review proof.

This queue migration removes old command names, option aliases, and legacy
record readers. Stop old coordinators before the upgrade. Preserve unresolved
publication effects, local commits, worktrees, and current journals. Do not
run old and new owners against the same state directory. See the
[queue cutover decision](docs/adr/0050-queue-owned-automation-cutover.md) and
[queue recovery runbook](docs/runbooks/ci-driver-stall.md).

#### 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, then
write a private, mode-`0600` TOML alias file containing exactly `provider` and
`model` strings. Pass its path with `--pi-alias-config`; aliases are parsed in
process and are never forwarded through the parent environment, subprocess
arguments, logs, or Slurm exports. See
[`docs/pi-private-provider.md`](docs/pi-private-provider.md) for the sanitized
setup and denylist guard. 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 `--pi-isolation-adapter ENTRY_POINT`. That adapter
enforces the resolved filesystem and network policy; the local setup otherwise
supports only the explicit adapter-smoke seam.

Use `--disable-pi-automation` when a run must omit Pi. That flag leaves
host-owned Athena `advise` and `learn` unchanged. See
[`docs/runbooks/pi-rollout.md`](docs/runbooks/pi-rollout.md) for enable, omit,
and recovery steps.

For independent tool selection, literal model names, and migration from aliases,
`MODEL[:EFFORT]` controls, and external server requirements, see
[`docs/ifm-models.md`](docs/ifm-models.md).

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

For recovery from an older installed package, use the
[fixed-revision runtime procedure](docs/runbooks/automation-runtime-recovery.md).
Repository synchronization does not update the package that runs the coordinator.
On macOS, host verification requires a virtual environment. A Conda base
environment is not supported for this operation.

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-tidy` | Clean merged branches; `--rebase-all` enables rebases and agent 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 |

### 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-environment-variables` | Enforce the exact deny-by-default runtime environment registry |
| `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 |

### 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

# Inspect the queue command options
hephaestus-automation-loop --help

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

## Development Guidelines

Follow the [ASD-STE100 writing standard](docs/asd-ste100.md) for all English
technical prose that you create or revise.

1. Follow the principles in [AGENTS.md](AGENTS.md)
2. Write comprehensive unit tests for all new functionality
3. Run each new or changed test and verify that it passes before you create a PR
4. Document all public functions with Google-style docstrings
5. Use type hints for all function parameters and return values
6. 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. Prefer `<issue-number>-<description>`; this format
   is a recommendation, not a requirement.
   (`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. Run each new or changed test. Verify that pytest collects it and reports
   success. The full suites run in required CI/CD, not in pre-commit.
4. Push the branch (`git push -u origin 123-amazing-feature`).
5. 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`.
6. 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.
