Metadata-Version: 2.4
Name: taar-agent-taskforce
Version: 0.1.0
Summary: TAAR — Thirsty's Active Agent Runner: a local-first governed agent taskforce for Project-AI, with a GitHub Workflow Guardian.
Author-email: Jeremy 'Thirsty' Karrick <iamsothirsty@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/IAmSoThirsty/TAAR
Project-URL: Issues, https://github.com/IAmSoThirsty/TAAR/issues
Keywords: governance,agents,automation,audit,evidence,github-actions,security,project-ai
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Security
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: typer>=0.12.5
Requires-Dist: rich>=13.9.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# TAAR — Thirsty's Active Agent Runner

**A local-first, governed agent taskforce.** Part of the Project-AI
constitutional architecture. TAAR runs micro-agents against a repository
under strict registry law: one task per agent, minimal authority, maximum
evidence, fail closed, everything classified. Includes a **GitHub Workflow
Guardian** that verifies GitHub Actions workflows before they run.

## What TAAR does

- Runs reader agents that inspect your repo and facility (git state,
  secrets, stale paths, lint/type/test surface, GitHub workflows) and
  produce **hash-sealed evidence bundles**.
- Runs writer agents that turn validated evidence into Markdown reports
  and digests — every report cites its source evidence hash.
- Keeps an **append-only audit spine** (JSONL, hash per record) of every
  admission, denial, success, failure, and classification escalation.
- Classifies everything: `OPEN < CONTROLLED < RESTRICTED < SECRET <
  PHANTOM < BLACK`. Secrets are redacted at capture. Artifacts with no
  producing run record are phantoms and turn the lane BLACK.
- Detects unsafe GitHub Actions patterns: broad permissions, secret
  echoing, `pull_request_target` risk, unpinned actions, shell injection,
  self-hosted/privileged runners, ungated deploys.

## What TAAR does NOT do

The first swarm is report-only. It cannot and will not: merge, push,
publish, deploy, delete, apply patches, create branches, or mutate source.
These capabilities are rejected at registry validation — the constraint is
structural. `taar workflows harden` prints draft suggestions and writes no
patch files.

## Install

    pip install taar-agent-taskforce

Not yet on PyPI — until the first release ships, install from a checkout:

    pip install .

Python 3.12+. Dependencies: pyyaml, typer, rich.

## Quick start

    cd your-repo
    taar init                      # seed registry/ + taar.toml (explicit, refuses overwrite)
    taar status                    # facility mode, 44 agents, validation state
    taar run heartbeat-reader      # evidence bundle
    taar run heartbeat-report-writer   # report citing the evidence hash
    taar evidence                  # list bundles
    cat .project-ai/automation/reports/facility/heartbeat-latest.md

## Workflow Guardian

    taar workflows explain         # what your workflows can do
    taar workflows scan            # findings (exit 1 on critical)
    taar workflows classify        # one-word risk verdict
    taar workflows harden          # draft suggestions, nothing applied
    taar workflows evidence        # governed run with full evidence bundle

Or in CI via the composite action — see `action.yml` and
`docs/TAAR_FOR_GITHUB_ACTIONS.md`.

## First swarm demo

    for a in heartbeat-reader heartbeat-report-writer git-status-reader \
             git-status-writer phantom-reader phantom-report-writer \
             governance-reader governance-digest-writer workflow-reader \
             workflow-report-writer; do taar run "$a"; done
    taar status && taar quarantine

## How governance works

Every run passes one gate (`taar/executor.py`): registry valid → agent and
task known and enabled → facility mode permits → capabilities granted →
every command declared, allowed, and granted (exact match) → output paths
in bounds → writer evidence present, hash-valid, and classification
admissible → no lock conflict. Any failure denies, and the denial is
audited. BLACK/PHANTOM evidence feeds no writer except the explicitly
granted handler. SECRET evidence feeds only the declared secret writer,
redacted.

## Layout

    taar/       runtime and CLI          registry/   the governed universe
    checks/     reader built-ins         writers/    writer built-ins
    tests/      87 contract tests        docs/       the canon
    examples/   real evidence samples + workflow examples
    scripts/    registry generator + Windows scheduler scripts

## Docs

Start with `docs/TAAR_REBUILD_DIRECTIVE.md`, then
`docs/LOCAL_AGENT_RULEBOOK.md`, `docs/RUNNER_CONTRACT.md`,
`docs/CLASSIFICATION_MODEL.md`, and
`docs/GITHUB_WORKFLOW_GUARDIAN.md`.

## License

MIT. Author: Jeremy "Thirsty" Karrick — Project-AI / Thirsty's Projects LLC.
