agentic-harness 0.2.0__tar.gz

agentic_harness-0.2.0/.agent-harness.yml

@@ -0,0 +1,17 @@
+# AI Harness configuration
+# Detected stacks: python
+stacks: [python]
+
+# exclude:
+#   - _archive/
+#   - vendor/
+
+# python:
+#   coverage_threshold: 95
+#   line_length: 140
+
+# javascript:
+#   coverage_threshold: 80
+
+# docker:
+#   own_image_prefix: "ghcr.io/myorg/"

agentic_harness-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install tools
+        run: |
+          uv sync
+          uv tool install -e .
+
+          # Install external tools
+          # conftest
+          CONFTEST_VERSION=0.56.0
+          curl -sL "https://github.com/open-policy-agent/conftest/releases/download/v${CONFTEST_VERSION}/conftest_${CONFTEST_VERSION}_Linux_x86_64.tar.gz" | tar xz -C /usr/local/bin conftest
+
+          # hadolint
+          HADOLINT_VERSION=2.12.0
+          curl -sL "https://github.com/hadolint/hadolint/releases/download/v${HADOLINT_VERSION}/hadolint-Linux-x86_64" -o /usr/local/bin/hadolint
+          chmod +x /usr/local/bin/hadolint
+
+          # yamllint
+          uv tool install yamllint
+
+          # gitleaks
+          GITLEAKS_VERSION=8.21.2
+          curl -sL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" | tar xz -C /usr/local/bin gitleaks
+
+          # osv-scanner
+          OSV_VERSION=1.9.1
+          curl -sL "https://github.com/google/osv-scanner/releases/download/v${OSV_VERSION}/osv-scanner_linux_amd64" -o /usr/local/bin/osv-scanner
+          chmod +x /usr/local/bin/osv-scanner
+
+      - name: Lint
+        run: agent-harness lint
+
+      - name: Test
+        run: uv run pytest tests/ -v
+
+      - name: Rego tests
+        run: conftest verify -p src/agent_harness/policies/ --no-color
+
+      - name: Security audit
+        run: agent-harness security-audit

agentic_harness-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,71 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install tools
+        run: |
+          uv sync
+          uv tool install -e .
+
+          CONFTEST_VERSION=0.56.0
+          curl -sL "https://github.com/open-policy-agent/conftest/releases/download/v${CONFTEST_VERSION}/conftest_${CONFTEST_VERSION}_Linux_x86_64.tar.gz" | tar xz -C /usr/local/bin conftest
+
+          HADOLINT_VERSION=2.12.0
+          curl -sL "https://github.com/hadolint/hadolint/releases/download/v${HADOLINT_VERSION}/hadolint-Linux-x86_64" -o /usr/local/bin/hadolint
+          chmod +x /usr/local/bin/hadolint
+
+          uv tool install yamllint
+
+          GITLEAKS_VERSION=8.21.2
+          curl -sL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" | tar xz -C /usr/local/bin gitleaks
+
+          OSV_VERSION=1.9.1
+          curl -sL "https://github.com/google/osv-scanner/releases/download/v${OSV_VERSION}/osv-scanner_linux_amd64" -o /usr/local/bin/osv-scanner
+          chmod +x /usr/local/bin/osv-scanner
+
+      - name: Full quality gate
+        run: |
+          agent-harness lint
+          uv run pytest tests/ -v
+          conftest verify -p src/agent_harness/policies/ --no-color
+          agent-harness security-audit
+
+  publish:
+    needs: check
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agentic_harness-0.2.0/.gitignore

@@ -0,0 +1,136 @@
+.env
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.coverage
+coverage.xml
+.worktrees/
+.DS_Store
+
+# Added by agent-harness
+$RECYCLE.BIN/
+*$py.class
+*.aof
+*.cab
+*.cover
+*.egg
+*.lnk
+*.log
+*.manifest
+*.mo
+*.msi
+*.msix
+*.msm
+*.msp
+*.pid
+*.pot
+*.py.cover
+*.py[codz]
+*.rdb
+*.sage.py
+*.so
+*.spec
+*.stackdump
+*~
+.AppleDB
+.AppleDesktop
+.AppleDouble
+.DocumentRevisions-V100
+.LSOverride
+.Python
+.Spotlight-V100
+.TemporaryItems
+.Trash-*
+.Trashes
+.VolumeIcon.icns
+._*
+.abstra/
+.apdisk
+.cache
+.com.apple.timemachine.donotpresent
+.coverage.*
+.directory
+.dmypy.json
+.eggs/
+.envrc
+.fseventsd
+.fuse_hidden*
+.hypothesis/
+.installed.cfg
+.ipynb_checkpoints
+.mypy_cache/
+.nfs*
+.nox/
+.pdm-build/
+.pdm-python
+.pixi
+.pybuilder/
+.pypirc
+.pyre/
+.pytest_cache/
+.pytype/
+.ropeproject
+.ruff_cache/
+.scrapy
+.spyderproject
+.spyproject
+.streamlit/secrets.toml
+.tox/
+.venv
+.webassets-cache
+/site
+ENV/
+Icon[
+MANIFEST
+Network Trash Folder
+Temporary Items
+Thumbs.db
+Thumbs.db:encryptable
+[Dd]esktop.ini
+]
+__MACOSX/
+__marimo__/
+__pypackages__/
+activemq-data/
+celerybeat-schedule
+celerybeat.pid
+cover/
+cython_debug/
+db.sqlite3
+db.sqlite3-journal
+develop-eggs/
+dmypy.json
+docs/_build/
+downloads/
+eggs/
+ehthumbs.db
+ehthumbs_vista.db
+env.bak/
+env/
+htmlcov/
+instance/
+ipython_config.py
+lib/
+lib64/
+local_settings.py
+marimo/_lsp/
+marimo/_static/
+mnesia/
+nohup.out
+nosetests.xml
+parts/
+pip-delete-this-directory.txt
+pip-log.txt
+profile_default/
+rabbitmq-data/
+rabbitmq/
+sdist/
+share/python-wheels/
+target/
+var/
+venv.bak/
+venv/
+wheels/

agentic_harness-0.2.0/.gitleaks.toml

@@ -0,0 +1,5 @@
+[allowlist]
+description = "Allow test fixtures with intentional fake secrets"
+paths = [
+    '''tests/fixtures/.*''',
+]

agentic_harness-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: local
+    hooks:
+      - id: harness-fix
+        name: auto-fix
+        entry: agent-harness fix
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: harness-lint
+        name: agent-harness lint
+        entry: agent-harness lint
+        language: system
+        pass_filenames: false
+        always_run: true

agentic_harness-0.2.0/.yamllint.yml

@@ -0,0 +1,11 @@
+extends: default
+ignore: |
+  .venv/
+  node_modules/
+rules:
+  line-length:
+    max: 200
+  truthy:
+    check-keys: false
+  document-start: disable
+  indentation: disable

agentic_harness-0.2.0/CLAUDE.md

@@ -0,0 +1,118 @@
+# agent-harness
+
+Deterministic quality gates for AI-assisted development. This project IS a harness — it enforces its own rules.
+
+## Dev Commands
+
+```bash
+make lint             # agent-harness lint (runs all checks)
+make fix              # agent-harness fix (auto-fix, then lint)
+make test             # pytest + conftest verify (all tests)
+make security-audit                   # check deps + secrets in working dir (fast)
+make check                            # full gate: lint + test + security-audit
+agent-harness security-audit-history  # deep scan git history for leaked secrets (run once)
+```
+
+Install dev deps: `uv sync`
+
+## Workflow
+
+Pre-commit hooks run `agent-harness fix` and `agent-harness lint` automatically on every commit.
+Before declaring work done, always run `make check` — it's the full quality gate.
+
+
+## Setup
+
+```bash
+uv tool install -e .          # install CLI globally from source
+uv sync                       # install dev deps (ruff, ty, pytest)
+agent-harness lint             # verify everything passes
+```
+
+## Architecture
+
+```
+src/agent_harness/
+  cli.py               — Click CLI: detect, init, lint, fix, security-audit (thin — delegates)
+  config.py            — Dict-based config from .agent-harness.yml
+  runner.py            — run_check(), CheckResult, tool_available()
+  conftest.py          — Shared conftest runner (used by all Rego checks)
+  exclusions.py        — File exclusion patterns
+  workspace.py         — Discover subproject roots
+  preset.py            — Preset base class + ToolInfo/PresetInfo
+  registry.py          — Explicit preset registration (PRESETS + UNIVERSAL)
+  detect.py            — Thin orchestrator: for preset in PRESETS: preset.detect()
+  lint.py              — Thin orchestrator: for preset in PRESETS: preset.run_checks()
+  fix.py               — Thin orchestrator: for preset in PRESETS: preset.run_fix()
+  init/                — Scaffolding (reads preset.get_info())
+  presets/
+    universal/         — Always runs: yamllint, gitignore, JSON, file length
+    python/            — ruff, ty, conftest on pyproject.toml
+    javascript/        — Biome, framework type checker, conftest on package.json
+    docker/            — hadolint, conftest on Dockerfile + compose
+    dokploy/           — conftest for Traefik/Dokploy conventions
+  security/            — osv-scanner + gitleaks runners, policy engine, CVE ignore
+  policies/            — Rego policies (bundled). Each has WHAT/WHY/FIX.
+
+skills/agent-harness/  — Claude Code plugin (SKILL.md + guidance docs)
+```
+
+## Adding a new preset
+
+1. Create `presets/<name>/` with `__init__.py` implementing `Preset`
+2. Add individual check files (one per tool)
+3. Add `<Name>Preset()` to `registry.py`
+4. Add Rego policies to `policies/<name>/` if needed
+
+## Conventions
+
+- Each preset implements: `detect()`, `run_checks()`, `run_fix()`, `run_setup()`, `get_info()`
+- One check per file, with WHAT/WHY/WITHOUT IT/FIX/REQUIRES docstring
+- One Rego policy per file, with `_test.rego` sibling
+- All conftest checks use shared `conftest.py` (never local `_run_conftest`)
+- Tool fallback: `shutil.which()` → `uv run` (Python) or `npx` (JS)
+
+## Policy Design Strategy
+
+Every check belongs in exactly one place. The boundary:
+
+**"Would any reasonable person agree this is broken?"**
+- YES → lint (Rego `deny` rule in `policies/`)
+- Debatable → init (Python setup check in `presets/*/setup.py`)
+
+### Lint (Rego, every commit)
+- Only `deny` rules. No `warn`.
+- Checks that gates EXIST and aren't objectively broken.
+- Examples: `--strict-markers` missing, `--cov-fail-under` missing, threshold < 30%
+
+### Init (Python, on-demand)
+- `SetupIssue` with severity `critical` (fixable) or `recommendation`.
+- Checks configuration QUALITY. Can auto-fix.
+- Examples: threshold = 50% (recommend 90-95%), missing `-v` flag
+
+### Skill (agent guidance, context-dependent)
+- Actions that require judgment, context, or reading intent.
+- The skill tells the agent WHAT to evaluate and WHY, but the agent decides HOW.
+- Examples: reorganize .gitignore (needs to know which patterns are stale),
+  audit CLAUDE.md (needs project context), replace redundant Makefile targets
+  (needs to understand what the target was for)
+
+### The boundary: init does, skill guides
+Init must be safe to run blindly (`--apply` never breaks a project).
+If an action could destroy user intent (rewriting .gitignore, editing CLAUDE.md),
+init does the safe subset (deduplicated append) and the skill guides the agent
+to do the rest (full cleanup, reorganization).
+
+### Same topic, all three places
+A single topic (e.g., .gitignore completeness) can have:
+- Lint Rego: "are generated files tracked?" (objectively broken)
+- Init Python: "append missing patterns grouped by category" (safe, mechanical)
+- Skill: "review and clean up the full .gitignore — remove stale patterns, reorganize" (judgment)
+
+## Never
+
+- Never embed tool binaries — require them installed externally
+- Never run checks in Docker — must be <500ms local
+- Never duplicate `_run_conftest` — use `agent_harness.conftest.run_conftest()`
+- Never truncate lint/test output with `| tail` or `| head` — output is already optimized
+- Never skip `make check` before declaring a task complete

agentic_harness-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,181 @@
+# Contributing to Agent Harness
+
+Agent Harness enforces its own rules. We use agent-harness to develop agent-harness.
+
+## Development setup
+
+```bash
+git clone https://github.com/agentic-eng/agent-harness
+cd agent-harness
+uv sync                          # install dev deps
+uv tool install -e .             # install CLI globally from source
+agent-harness lint               # verify everything passes
+```
+
+## Quality gate
+
+Before every commit (enforced by pre-commit hooks):
+
+```bash
+make check                       # lint + test + security-audit
+```
+
+This runs:
+- `agent-harness lint` — 10 checks (ruff, ty, conftest, yamllint, etc.)
+- `uv run pytest tests/ -v` — 201 Python tests
+- `conftest verify` — 109 Rego policy tests
+- `agent-harness security-audit` — dependency + secret scanning
+
+## Adding a new Rego policy
+
+One file per concern, one concern per file.
+
+### 1. Decide: is it deterministic?
+
+The harness only contains deterministic controls — tools that produce a pass/fail verdict without human judgment. If a rule requires interpretation, it's guidance (document it in the skill), not a policy.
+
+### 2. Choose the right directory
+
+- `src/agent_harness/policies/dockerfile/` — Dockerfile rules
+- `src/agent_harness/policies/compose/` — Docker Compose rules
+- `src/agent_harness/policies/dokploy/` — Dokploy/Traefik rules
+- `src/agent_harness/policies/python/` — pyproject.toml / Python config rules
+- `src/agent_harness/policies/gitignore/` — .gitignore rules
+
+### 3. Write the .rego file
+
+```rego
+package dockerfile.my_concern
+
+# One-line description.
+# Why this matters for AI agents.
+#
+# Input: <describe the parsed data structure>
+
+import rego.v1
+
+default _exceptions := []
+
+_exceptions := data.exceptions if {
+    data.exceptions
+}
+
+deny contains msg if {
+    not "dockerfile.my_concern" in _exceptions
+    # your logic here
+    msg := "Actionable error message — what's wrong and how to fix it"
+}
+```
+
+**Conventions:**
+- One file per concern (e.g., `layers.rego`, `cache.rego`)
+- Package name matches directory + filename: `policies/dockerfile/layers.rego` → `package dockerfile.layers`
+- Only `deny` rules. No `warn`.
+- Error messages must be actionable — tell the agent what to do
+- WHAT/WHY/WITHOUT IT/FIX comment block at top
+- Always include `_exceptions` guard so policies can be skipped via `conftest_skip`
+
+### 4. Write the test file
+
+Every policy needs a `_test.rego` sibling with at least:
+
+```rego
+package dockerfile.my_concern_test
+
+import rego.v1
+import data.dockerfile.my_concern
+
+test_bad_input_fires if {
+    my_concern.deny with input as [...]
+}
+
+test_good_input_passes if {
+    count(my_concern.deny) == 0 with input as [...]
+}
+
+test_exception_skips if {
+    count(my_concern.deny) == 0 with input as [...]
+        with data.exceptions as ["dockerfile.my_concern"]
+}
+```
+
+### 5. Write fixture files
+
+Place in `tests/fixtures/<directory>/`:
+- `bad_*.Dockerfile` — triggers the deny
+- `good_*.Dockerfile` — passes clean
+
+Bad fixtures should ONLY fail on the rule being tested. Include USER, HEALTHCHECK, cache mount, etc. so they don't trigger unrelated rules.
+
+### 6. Verify
+
+```bash
+# Rego unit tests
+conftest verify --policy src/agent_harness/policies/dockerfile/
+
+# Fixture tests
+conftest test tests/fixtures/dockerfile/*.Dockerfile \
+  --parser dockerfile \
+  -p src/agent_harness/policies/dockerfile/ \
+  --all-namespaces
+
+# Full quality gate
+make check
+```
+
+### 7. Update exception ID table
+
+Add the new exception ID to `skills/agent-harness/SKILL.md` in the Conftest Exceptions table.
+
+## Adding a new preset
+
+1. Create `presets/<name>/` with `__init__.py` implementing `Preset`
+2. Add individual check files (one per tool, with WHAT/WHY/WITHOUT IT/FIX docstring)
+3. Add `<Name>Preset()` to `registry.py`
+4. Add Rego policies to `policies/<name>/` if needed
+5. Run `make check`
+
+## Adding a new check module
+
+Create a new file in `src/agent_harness/presets/<stack>/`. Follow the existing pattern:
+
+- Function takes `project_dir: Path` and returns `CheckResult` (or `list[CheckResult]`)
+- Use `run_check()` from `agent_harness.runner` for subprocess execution
+- Wire the call into the preset's `run_checks()` method
+
+## Evaluating community rules
+
+Before writing a custom Rego rule, check if an existing tool covers it:
+
+1. **Does hadolint cover it?** (Dockerfile shell practices) → Don't duplicate
+2. **Does ruff cover it?** (Python code patterns) → Don't duplicate
+3. **Does yamllint cover it?** (YAML syntax) → Don't duplicate
+4. **Does a conftest community policy exist?** → Evaluate for adoption
+5. **Does Trivy's built-in check cover it?** → Note the DS-* ID, write our own (Trivy is too slow)
+
+If an existing tool covers it, don't duplicate in Rego.
+
+### When NOT to write a rule
+
+- **It requires file existence checks** — conftest parses content, not filesystem
+- **It requires cross-file analysis** — conftest checks one file at a time
+- **It's a judgment call** — document as guidance in the skill, not as a Rego policy
+- **An existing tool does it better** — hadolint, ruff, yamllint have years of battle-tested rules
+
+## Tool stack
+
+| Tool | Purpose | Why this one |
+|------|---------|-------------|
+| conftest | Rego policies for any config file | Only tool that parses TOML + Dockerfile + YAML + JSON + .gitignore |
+| hadolint | Dockerfile shell best practices | 12K stars, maintained, comprehensive |
+| yamllint | YAML syntax + duplicate key detection | Catches duplicate keys conftest's parser silently merges |
+| ruff | Python lint + format | 46K stars, fastest Python linter |
+| ty | Python type checking | Astral's type checker, fast |
+
+## Code style
+
+```bash
+make fix                         # auto-format + lint
+```
+
+Follow existing patterns. Ruff handles formatting automatically.

agentic_harness-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Iorlas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentic_harness-0.2.0/Makefile

@@ -0,0 +1,24 @@
+.PHONY: lint fix test check security-audit bootstrap
+
+lint:
+	agent-harness lint
+
+fix:
+	agent-harness fix
+
+test:
+	uv run pytest tests/ -v
+	conftest verify -p src/agent_harness/policies/ --no-color
+
+security-audit:
+	agent-harness security-audit
+
+check: lint test security-audit
+
+bootstrap: ## First-time setup after clone
+	uv sync
+	agent-harness init --apply
+	@if command -v prek >/dev/null; then prek install; \
+	elif command -v pre-commit >/dev/null; then pre-commit install; \
+	else echo "Install prek (brew install prek) or pre-commit for git hooks"; fi
+	@echo "Done. Run 'make check' to verify."