Agent-Argus (argus-agent) 🛡️👁️

Does your test suite actually test anything?

Agent-Argus audits a repository and answers that with an exit code your CI can act on. It looks for the ways code comes to look finished without being finished: tests that assert nothing, functions nothing calls, assertions that cannot fail, and secret warnings that were suppressed rather than fixed.

pip install "argus-agent @ git+https://github.com/Inan15/Agent-Argus.git@v1.0.0"
argus audit .

See it in 90 seconds — python examples/demo.py builds a repository whose test suite is green under pytest, watches Argus block the release (exit 2) because the test asserts a value it invented rather than the one the code returned, then fixes the test and watches it clear (exit 0). Hermetic, no network, and nothing in it is pre-recorded. See examples/.

Which findings can block, stated plainly. Only an AST-corroborated finding is allowed to move a verdict to blocking. Orphan code, hardcoded secrets and tool-runner findings are advisory by contract — they are reported and they never fail your build on their own. That is deliberate: a wrong 🔴 is the failure that gets a tool deleted from a pipeline, so Argus would rather tell you about something than block you over a guess.

No API key. No account. No network call at all on the default path, and zero LLM tokens — the verdict is a pure function of what was measured, so the same commit gives the same answer on any machine, in any order, on any host.

Measured against 8 production repositories — 4,659 source files and 16,940 test functions — with 0 blocking false positives. That is a false-alarm measurement on a named corpus, which is the number that matters for a tool you intend to block a pipeline with. What it does and does not cover is stated in full under Instrument status below, not buried.

🔍 Ten languages, really parsed	Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby, PHP — all grounded against a real tree-sitter AST, all in the default install.
📊 An honest remainder	Every file is graded audited_deep / audited_shallow / skipped and counted, never averaged. A file it could not assess stays in the denominator.
🧾 Evidence, not opinion	Findings cite the AST span they came from. The verdict is a hash-chained, append-only artifact you can diff and re-derive.
🔒 Nothing leaves your machine	The deep, LLM-backed pass is opt-in behind one flag and discloses itself before the first byte moves.
⚖️ It says what it did not check	INSUFFICIENT_COVERAGE is a first-class verdict. Argus would rather tell you it could not judge than guess.

Never run it before? → docs/first-run.md — install, your first audit, reading the ledger, what each verdict and exit code means. Four sections, nothing else.

Wiring it into a pipeline? → CHANGELOG.md records every consumer-visible change to exit codes, artifact schemas, defaults, rendered strings and the public API — and what deliberately did not change.

Want to help? → CONTRIBUTING.md lists six specific jobs, including the one that matters most: finding a case where Argus is wrong.

---

🛡️ Instrument status

FR34 Disclosed Tier — mechanically enforced on every user-facing surface.

Argus's audit is deterministic and reproducible by construction. Argus's finding precision has not been independently validated, so treat a finding as a prompt to look rather than as a verdict; its findings rest on the Argus dogfood corpus, a self-audit of this repository. The >=80% precision gate has not been EVALUATED rather than evaluated and missed: its precision condition is UNEVALUABLE because the ratified corpus was read and no finding was promoted to verdict-eligible, so the ratio has an empty denominator rather than a low value. This notice is removed only when the >=80% precision gate is met; nothing else removes it.

What the 0-false-positive figure covers. Empirically verified across 8 production repositories (4,659 source files, 16,940 test functions): no finding that would block a release was raised on code that did not warrant it. It is a statement about that corpus, and the corpus is named rather than summarised — which is the only form of that claim worth anything.

What it does not cover. It is not a precision measurement, and it is not independent. Precision asks "of the findings raised, how many were real?", and answering it needs findings to adjudicate; on mature repositories Argus raises almost none, which is why the precision condition is currently UNEVALUABLE rather than low. Argus does not claim its findings are validated, and no verdict it issues is an attestation that code is correct — it reports the absence of detected blocking findings within an assessed scope, which is a narrower and more honest claim.

(Provenance note, kept for auditors rather than first-time readers: the docs/first-run.md link above was added 2026-08-15 by Story 12.8 — until then this README was the only integrator-shaped document in the repository and linked to docs/ nowhere at all, measured, zero occurrences, so a first-time reader met the full integration surface or nothing. That page is repository documentation and is not packaged in the wheel, which is why the link is its whole delivery mechanism.)

---

🌟 Key Features

1. Deterministic Assurance Kernel (argus/):

   • Pure Verdict Gate: Mathematical, zero-LLM-token release readiness calculation (RELEASE_READY, NOT_READY_FOR_RELEASE, INSUFFICIENT_COVERAGE).
   • AST Indexing & Grounding: tree-sitter AST parsing and structural search validating deep audit claims against real code definitions.
   • Graph-Derived Partitioning: Auto-partitions large repositories into bounded audit units ($\le 40$ files / $15\text{k}$ LOC) to eliminate context rot.
   • Content-Addressed Memoization: Byte-identical execution across hosts via canonical JSON serialization and full closure hashing.
   • Prosecutor Cut-Edge Pass: Adversarial second pass ensuring seam-spanning defects across partitions move the verdict to $\color{red}{\text{NOT READY}}$.
   • Defect Cartridges & Self-Audit Harness: CI-blocking true-negative clean control cartridges and hidden holdouts.

2. Packaged assistant commands (argus/assets/commands/) — shipped in the wheel, placed by argus install-commands, see Slash Commands:

   • Verified host: Claude Code. One host, not a list of aspirations. Each host is a single entry in the closed registry at argus/commands/hosts.py, and an entry exists only once its exact configuration directory and its exact resulting command spelling have been verified. Additional hosts are each one reviewed registry entry away.

3. RAM Workflow Framework (audit/, phases/, templates/) — repository-only; these directories are not part of the argus-agent distribution, see Quickstart:

   • 12 Audit Phases: Guided markdown workflows from Orientation (00) to Verdict (11).
   • 8 Developer Report Templates, of which 4 are rendered by argus audit --report-dir: final-verdict, coverage-ledger, security-review and architecture-review.

---

🚀 Quickstart & Installation

Install as a dependency (no clone required)

Superseded, kept on the record (§3.4). Until 2026-08-29 this section read: "argus-agent is not on PyPI or any other package index, and this repository has published no release yet. What it does have is a release workflow — committed, and never executed … ⚠️ This command does not resolve today. Tag v0.1.0 has not been created or pushed — git tag -l is empty at this commit … Unresolvable until v0.1.0 exists." 🔴 CORRECTED 2026-08-29. v0.1.0 was never created; the first tag this project pushed was v1.0.0, on 2026-08-28, and it carries a published Release with built artifacts. The caveats above stayed literally true about a version that never existed while the version that did exist went unnamed — and git tag -l reads a local clone, which is empty in any checkout that has not run git fetch --tags, so the evidence they cited could not have detected the change. The release workflow has since executed and refused (see CHANGELOG 1.0.0); "never executed" is retired.

argus-agent is not on PyPI or any other package index — that part is unchanged, and the VCS pin below is the whole resolution story:

pip install "argus-agent @ git+https://github.com/Inan15/Agent-Argus.git@v1.0.0"

In a pyproject.toml:

dependencies = [
    "argus-agent @ git+https://github.com/Inan15/Agent-Argus.git@v1.0.0",
]

Prefer a standalone binary? The v1.0.0 Release attaches Linux x64, macOS arm64 and Windows x64 packages; install.sh (Unix) and install.ps1 (Windows) at the repository root fetch and place them, no Python toolchain required.

Authentication. No credential is required if and only if github.com/Inan15/Agent-Argus is a public repository.

Superseded, kept on the record. This previously read: ⚠️ This repository's visibility was not measured when this line was written — no network call was made from the working tree — so treat "public" as the thing to CHECK, not as a stated fact. It has since been measured, and it is the worse case. Struck rather than deleted, because the record that the gap existed is what makes the correction auditable.

This is the single source of that fact; TC-ArgusAgent-DOCS-001-71 asserts it appears verbatim here, in CHANGELOG.md and in docs/first-run.md, so the three cannot drift apart:

Repository visibility, MEASURED 2026-08-29 by gh repo view Inan15/Agent-Argus --json visibility,isPrivate -> PUBLIC / isPrivate: false. What that buys a consumer, stated plainly: the pinned install resolves for anybody with no credential, and the GitHub Release and its attached packages are publicly downloadable. This SUPERSEDES the 2026-08-15 measurement, which read PRIVATE / isPrivate: true and said the pinned install cannot resolve for anybody — tag or no tag — without a read credential carried in the URL (git+https://<credential>@github.com/...) — accurate on its date, never re-run for fourteen days, and false for an unknown part of them. That is the whole hazard of this sentence: it is a dated measurement, not a standing claim, and re-running the command above before relying on it is the only thing that keeps it true.

This pin is INTERIM. It resolves a git ref rather than an immutable index artifact, which means it depends on the repository staying reachable and the tag staying put (the release workflow refuses a tag move for exactly this reason). It moves to a package index under one named condition:

when argus-agent is claimed on PyPI and a PyPI Trusted Publisher (OIDC) is configured for this repository — at which point the publish step is added to .github/workflows/release.yml directly (trusted publishing cannot be used from inside a reusable workflow) with permissions: id-token: write and no stored token, and the pin above is replaced by a plain index install of the distribution name.

Publishing to PyPI is deliberately not attempted by the current workflow: a released name+version on an index can never be replaced, which makes it an operator decision taken with credentials in hand. Re-affirmed 2026-08-15 (Story 12.9 / DN-1): still not attempted, and the exit condition above still has a named end rather than becoming permanent by silence.

Release status: what evidence backs this, stated rather than implied

A release status here cites an executed gate — a GitHub Actions run together with the sha that run covers — or it records NOT ESTABLISHED, which is a first-class recordable state and not a gap (architecture.md §H, Story 10.1). The sentence below is derived, not typed: scripts/release_notes.py::derive_release_status computes it from the observed run, its sha, its conclusion and the commit being released, and TC-ArgusAgent-DOCS-001-25 asserts that this file and CHANGELOG.md carry exactly that value. The same function renders it into the GitHub Release note, so the three cannot disagree.

CI evidence: NOT ESTABLISHED. No executed gate covers the commit being released — the most recent audit-ci.yml run is run 33235322979, which covers sha ac1265e6ffabe0a6cb3b7633dc3107bd3556b274 and therefore evidences a different tree; a run id quoted without the sha it covers is a half-truth, so it is named here as SUPERSEDED rather than cited. Observed 2026-08-29 through the GitHub API. The human step that would establish one, and the only one: push master to origin and let audit-ci.yml run to success on the released commit, then re-derive this sentence from that run. A local pytest/mypy/bandit run is necessary, not sufficient, and is recorded as LOCAL (architecture.md §H).

Auditing a non-Python repository: nothing extra to install

The default install grounds every language Argus claims to support — Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby and PHP. All ten tree-sitter grammars are ordinary dependencies of the distribution, so the plain install command is the whole story:

Superseded, kept on the record (§3.4). A caveat below this command previously read: "⚠️ Same interim caveat as above — the tag does not exist yet, so the first command does not resolve today. The clone form works now." Corrected 2026-08-29: the pin named v0.1.0, which was never created, and v1.0.0 has existed since 2026-08-28. Both forms work.

pip install "argus-agent @ git+https://github.com/Inan15/Agent-Argus.git@v1.0.0"
# or, from a clone:
pip install -e .

Superseded, kept on the record. This section previously read: The default install grounds Python only. Nine further tree-sitter grammars ship in an optional extra, and installing it is what lets Argus check claims against the real AST of a JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby or PHP file. The nine grammars moved into the base dependencies on 2026-08-15, because NFR-P3 classifies coverage lost to a grammar missing from the default install as a packaging defect, not a user error. The [languages] extra is retained so pip install "argus-agent[languages]" keeps working; it now resolves to requirements the default install already carries, and a test pins the two lists equal.

Which languages, and where that list actually lives. The languages Argus reads are the suffixes in argus/shared/source_languages.py — that module is the single source of truth, not this paragraph, and tests/test_multilanguage_audit.py fails if a language in it has no grounding fixture. TC-ArgusAgent-DOCS-001-61 asserts the default dependency list grounds exactly that set, so a language added to the tool but not to the install turns red at edit time.

A grammar can still be missing at run time, and Argus tells you so where it costs you. An uninstalled, vendored, or broken grammar — or a tree-sitter core that fails Argus's own self-check — still degrades a file, so the run states the reason at the point the file is downgraded rather than leaving a coverage number to be misread as a judgement about the code:

	Grammar usable	Grammar unusable
The file is enumerated and graded	✅	✅
It can reach audited_deep	✅	❌ — capped at audited_shallow
What the report says	the deep grade it earned	the file, the depth it reached, the exact package (e.g. tree-sitter-go) and the pip install command that restores deep grounding

The remedy is per failure class, never blended: a package that is absent is a pip install, a package that is present but unrecognised is an Argus defect you should report rather than reinstall, and a tree-sitter core that is missing or unvalidated affects every language at once and says so.

Enumerable is not the same as deeply auditable, and a missing grammar is never a silent drop. A file whose grammar is absent is still counted, still graded, and still reported — it simply cannot reach audited_deep, so it lowers the coverage ratio instead of quietly disappearing from it. That is the point of enumerating it: an audit that cannot examine a file has to say so. Argus will not emit a deep claim it could not verify.

Measured limits, so you can plan around them rather than discover them. All ten languages ground (ast_eligible=True), including .tsx via the JSX-aware grammar. But structure extraction is narrower than grounding: C, C++, Ruby and Rust currently yield no function/class definitions, because the definition vocabulary was written against Python's node names. A file in those four parses cleanly and is graded, but has no definition for the depth gate to stand on. Pinned language-by-language by TC-ArgusAgent-INTAKE-003-09 and tracked as DF-10-2-A in _bmad-output/design-artifacts/ArgusAgent/deferred-work.md.

What the distribution contains, and what needs the git repository

MEASURED from the built wheel (argus_agent-1.0.0-py3-none-any.whl, 116 entries) and sdist (argus_agent-1.0.0.tar.gz, 115 files), not inferred — argus_agent-0.1.0-…, 104 entries / 103 files struck, not deleted (§3.4): the filenames moved with the 1.0.0 bump and the counts with Epic 20: [tool.flit.module] name = "argus" packages the argus Python package and nothing else — which, since Story 12.7, includes the command assets under argus/assets/commands/: flit_core walks the whole argus/ directory and ships every file in it, so a .md there reaches the wheel with no pyproject.toml change, and reaches the sdist because it is tracked in version control. The sdist additionally carries pyproject.toml, README.md, LICENSE and PKG-INFO. Both figures are re-derived from a freshly built pair of artifacts by TC-ArgusAgent-DOCS-001-54, which fails if this paragraph and the artifact ever disagree — in either direction. This paragraph is the one place this README states those two numbers; everything else below refers to it rather than restating them, because two remembered statements of one measurement is how they came to contradict each other (see the struck sentence under Slash Commands).

Capability	From the installed distribution	Needs the git repository
argus / argus-agent / repo-audit console scripts (all three run argus.cli:main)	✅
argus-mcp console script (argus.mcp.server:main) — the same audit over MCP on stdin/stdout	✅
argus audit <repo> — the full deterministic audit, verdict and exit-code contract	✅
Report generation (--report-dir)	✅
argus install-commands — places the packaged assistant commands into your assistant's configuration directory (and --remove takes them away)	✅
The packaged command assets themselves (argus/assets/commands/*.md)	✅ they ship in the wheel and the sdist as data
The RAM workflow framework — audit/, phases/, templates/	❌ not packaged — these are sibling top-level directories, not part of the argus module	✅
install.sh / install.ps1 — convenience wrappers that pip install -e . and then delegate to argus install-commands; they copy nothing themselves	❌ not packaged	✅
The test suite and the defect cartridges under tests/	❌ not packaged	✅
Argus's own dogfood proof generator (argus.dogfood.*, argus.precision.*)	✅ imports; generating a proof still needs the repository — see the note below	✅ for the proof run

Measured limitation, stated rather than discovered later — and now measured away. On a freshly built wheel, with this repository removed from sys.path and one clean subprocess per module, 108 of the 108 shipped modules import. None fail. (108, not 96, since 2026-08-29: Epic 20 added twelve modules across three packages — argus/parsers (3, Story 20.1), argus/remediation (4, Story 20.2) and argus/adapters/lsp (5, Story 20.3). They IMPORT, which is all this sentence measures; none of the three is reachable from any entry point, so nothing an operator can invoke moved. 96, not 95, since 2026-08-25: Story 17.3 added argus/detectors/assertion_strength.py, which GRADES what each assertion in a flagged test span constrains and lands the successor vacuity predicate S1 as code. It is ADVISORY and promotes nothing: no finding becomes verdict-eligible, no threshold moves, and the externalization gate stays BLOCKED. Like the two below it resolves NO repository path at module level, which is the property that decides whether a wheel can import it. 95, not 94, since 2026-08-23: Story 16.7 added argus/precision/silent_class.py, which DERIVES the class of test spans that reach the system under test, discard the result and assert NOTHING AT ALL, and publishes it as a QUESTION for a named human to judge. It promotes nothing: no finding becomes verdict-eligible, no threshold moves, and the externalization gate stays BLOCKED. Like its sibling below it resolves NO repository path at module level, which is the property that decides whether a wheel can import it. 94, not 93, since 2026-08-23: Story 16.5 added argus/precision/gate_independence.py, which DERIVES from the committed adjudication record whether the adjudication behind the precision figure was independent of the tool's authors, and publishes the answer ON the same sentence as the figure. It is a DISCLOSURE and gates nothing: protocol §5 still carries seven conditions, and today's derived answer is NOT_INDEPENDENT — which is the correct output, not a failure. 93, not 92, since 2026-08-22: the DF-15-2-D cohesion split moved the two assertion vocabularies and the mock table out of argus/detectors/vacuous_test.py — which stood at 1,196 of 1,200 — into argus/detectors/vacuous_vocabulary.py. Names only, no scoring, no threshold and no behaviour change: all three tables hash identically to before the split, and every moved name is re-exported from the original module, so no import path changed. 92, not 91, since 2026-08-20: Story 16.3 added argus/precision/gate_yield.py, protocol §5's SEVENTH condition — the YIELD floor under the precision ratio's denominator, which is what stops a ratio over three findings being published as a cleared 80% gate — pure, resolving no repository path at module level, and structurally asserted to reference no recall term and no bench-content quantity. 91, not 90, since 2026-08-20: Story 16.2 added argus/precision/gate_seal.py, protocol §5's SEAL condition and the partition rule it rests on — pure, and resolving no repository path at module level. 90, not 88, since 2026-08-20: Story 16.2 discharged DF-16-1-B by splitting argus/precision/gate_decision.py — 1,197 of NFR-M1's 1,200 lines — along its cohesion boundary into argus/precision/gate_conditions.py (what a §5 condition IS) and argus/precision/gate_evidence.py (what one is MEASURED FROM). A pure move: every symbol is re-exported and no import line anywhere changed. 88, not 87, since 2026-08-20: Story 16.1 added argus/precision/gate_breadth.py, protocol §5's breadth condition — pure, and resolving no repository path at module level. 87, not 86, since 2026-08-17: Story 14.1 split argus/detectors/provenance_scan.py out of the vacuous-test detector — the line-oriented source-text scan that answers "do the asserted values derive from the SUT output?"; it is pure and resolves no repository path at module level, so it imports from the wheel like the rest; 86, not 84, since 2026-08-17: Story 13.3 added argus/precision/gate_decision.py and argus/precision/gate_disclosure.py — the gate-decision instrument and the renderer that states its outcome; neither resolves a repository path at module level, so both import from the wheel like the rest; 84, not 83, since 2026-08-16: Story 13.2 added argus/precision/adjudication.py, the adjudication record the >=80%-precision gate is measured from — it resolves no repository path at module level, so it imports from the wheel like the rest; 83, not 78, since 2026-08-15: Story 12.7 added argus/assets/ and argus/assets/commands/ — the packaged command-asset tree, which is a real package so importlib.resources can resolve it from a built distribution — plus argus/commands/ with its closed host registry and the installer behind argus install-commands; 78, not 75, since 2026-08-15: Story 12.6 added argus/mcp/ — __init__.py, protocol.py and server.py, the MCP stdio adapter behind the argus-mcp entry point; 75, not 74, since 2026-08-13, when Story 12.3 added argus/cache/stage_memo.py, the production call site that wires the FR27/NFR-D1 memoization store; 74, not 73, since Story 12.2 added argus/audit/deep_pass.py, the opt-in deep pass. The figure is DERIVED from the freshly built artifact by TC-ArgusAgent-DOCS-001-54 — the artifact is the fact — so it moves with the tree rather than being remembered.)

Until 2026-08-12 five did — argus/precision/__init__.py, argus/precision/replay_harness.py, argus/dogfood/proof_types.py, argus/dogfood/proof_render.py and argus/dogfood/proof_run.py — all with ModuleNotFoundError: No module named '_registry', because argus/precision/replay_harness.py imported the labelled-cartridge registry from tests/cartridges/ at module import time and the distribution does not (and should not) contain it. That registry is now resolved lazily, so importing the module from the wheel succeeds; running the precision replay or the dogfood proof generator still needs the git repository, because that is where the labelled cartridges live. Those are Argus's self-audit and precision-measurement tools, not consumer features. DF-9-2-A in _bmad-output/design-artifacts/ArgusAgent/deferred-work.md is CLOSED.

What holds this claim. TC-ArgusAgent-RELEASE-001-20 (tests/test_built_distribution.py) builds the wheel and the sdist and imports every shipped module out of the built artifact, so the count above cannot drift from what actually ships. It replaces a claim that used to be made here for TC-ArgusAgent-RELEASE-001-11, which was false: -11 walks the source tree with ast, cannot tell a module-level import from a lazy one, and stayed green across the entire fix while the published figures rotted from "66 of 71" to a measured 67 of 72 underneath it. A guard that inspects the source tree cannot hold a claim about the distribution.

Clone-based installation (for the RAM framework and development)

# Unix / macOS
./install.sh

# Windows PowerShell
.\install.ps1

Both scripts do the same two things and nothing else: an editable install, then a delegation to argus install-commands. You do not need either of them to get the commands — that step ships in the distribution, so a pip install user runs it directly:

# Preview the plan, then place the commands.
argus install-commands --dry-run
argus install-commands

There is exactly one placement mechanism, it ships in the wheel, and --remove takes back exactly what it wrote.

Or, for an editable development install with no command placement at all:

pip install -e .

---

💻 Slash Commands & Usage

What pip install argus-agent actually installs — measured on the built wheel, not assumed. Four console aliases across two entry points: argus, argus-agent and repo-audit, all three entry points for argus.cli:main; and argus-mcp, which is argus.mcp.server:main. And, since Story 12.7, the command assets themselves: the wheel carries the argus/assets/commands/*.md files as data, the argus install-commands sub-command places them into a supported assistant's configuration directory, and --remove takes back exactly what it wrote. The wheel's entry count is stated once, in What the distribution contains above.

Using it from a coding agent (argus-mcp). The argus-mcp alias starts an MCP server that speaks JSON-RPC 2.0 over stdin/stdout only — it binds no port, opens no listener, and accepts no key, token or account. It publishes exactly one tool, audit_repository, whose arguments are the argus audit flags and whose result is the same verdict, exit code and coverage figures the command line returns for the same arguments. Configure it as a stdio server in your assistant:

{"mcpServers": {"argus": {"command": "argus-mcp", "args": []}}}

It takes no arguments; its entire input is the message stream, and it exits when stdin closes:

argus-mcp

The assistant commands that ship, and the step that places them. Install the distribution, then run the sub-command:

# Print exactly what would be written, and write nothing.
argus install-commands --dry-run

# Place them for every supported host whose configuration directory is detected.
argus install-commands

# Delete exactly what the step wrote, and nothing else.
argus install-commands --remove

It accepts --host <name> (repeatable), --dest <dir> (override the configuration root), --dry-run and --remove, and nothing more. Hosts covered: Claude Code, whose commands directory is ~/.claude/commands/; each supported host is one entry in the closed registry at argus/commands/hosts.py. The three commands it places are:

/argus-audit             # Run the full deterministic audit and report the verdict
/argus-audit-security    # Run the security pass alone (secret scan + containment)
/argus-audit-report      # Run the audit and render the four developer markdown reports

Each of those is a packaged asset carrying a description and the literal argus audit … line it instructs your assistant to run — no shell beyond that invocation, no network call, no credential and no interpolation construct. The FR34 instrument-status disclosure is rendered into each file at install time from the one constant that declares it, so the copy on your disk is never a stale transcription; re-run the step to refresh it. The spellings above are DERIVED from the shipped asset names and the host registry by TC-ArgusAgent-ASSETS-001-06, never hand-typed here, and that guard fails in both directions — a command documented with no shipped asset, or an asset absent from this list.

From terminal CLI — the audit sub-command is required, and every flag below is the real spelling:

# The whole contract in one line: audit this repo at HEAD, no ceiling, default passes.
argus audit .

# Release-gate mode, as a CI step would run it.
argus audit . --commit HEAD --strict --budget 500 --materiality-bar critical

# Write the Markdown reports (--reports renders nothing unless --report-dir is set).
argus audit . --report-dir ./argus-reports --reports final-verdict,coverage-ledger

Every argus … command line committed in this README, in action.yml and in the workflows is parsed by the real parser in CI (TC-ArgusAgent-DOCS-001-28), so a documented invocation that would fail for a reader fails the build first.

---

🤖 LLM & LLM API Key Configuration (Optional)

Pure Deterministic Default: The default run (argus audit .) is 100% offline, pure-deterministic, requiring zero LLM tokens, zero API keys, and zero network access.

LLM dispatch is strictly opt-in and is engaged only when you pass the --deep-audit flag to run deep semantic audit passes. Credentials are read strictly from environment variables (never from CLI flags or configuration files, preventing secrets from being logged to shell history or committed to git).

🔑 Environment Variables Reference

Environment Variable	Description	Default if Unset
OPENAI_BASE_URL / OLLAMA_HOST / OLLAMA_URL	Provider endpoint URL (The required switch for LLM dispatch). Omit trailing /v1.	None — LLM pass degrades gracefully
OPENAI_API_KEY	Bearer token sent in Authorization header.	"mock-key"
ARGUS_LLM_MODEL / OLLAMA_MODEL	Model identifier (e.g., gpt-4o-mini, llama3.1, claude-3-5-sonnet, deepseek-coder).	gpt-4o-mini

💡 Quick Examples

1. OpenAI or OpenAI-Compatible API (DeepSeek, Groq, OpenRouter)

export OPENAI_BASE_URL=https://api.openai.com
export OPENAI_API_KEY=sk-...
export ARGUS_LLM_MODEL=gpt-4o-mini
argus audit . --deep-audit

2. Local Ollama (100% Offline & Private)

export OLLAMA_HOST=http://localhost:11434
export ARGUS_LLM_MODEL=llama3.1
argus audit . --deep-audit

For complete details on LLM dispatch behavior, response degradation rules, and privacy guarantees, see docs/first-run.md.

---

📁 Repository Structure

ArgusAgent/
├── argus/                 # Standalone Python Assurance Engine Core
│   ├── assets/commands/   # The ONE command-asset tree — packaged DATA, shipped in the wheel
│   ├── commands/          # `argus install-commands`: the closed host registry + the installer
│   ├── intake/            # Repository intake & stack detection
│   ├── index/             # tree-sitter AST indexer & partitioner
│   ├── ledger/            # Coverage ledger & depth semantics
│   ├── detectors/         # Vacuous test, secret scan, orphan code, radon
│   ├── verdict/           # Pure verdict gate & Prosecutor pass
│   ├── store/             # Canonical serializer & envelope writer
│   ├── cache/             # Content-addressed memoization
│   ├── audit/             # LLM dispatch port & provider adapters
│   ├── cost/              # Budget governor & resumability
│   ├── governance/        # Escalation manager & decision records
│   └── precision/         # Ground-truth replay harness
├── audit/                 # RAM Skill definitions & Evidence Models
├── phases/                # 12 Audit Phase Markdown Guides (00 to 11)
├── templates/             # 8 Developer Report Templates (4 of which are rendered)
├── tests/                 # Comprehensive Test Suite & Defect Cartridges
├── pyproject.toml         # Package definition
├── install.sh / .ps1      # Convenience wrappers; they delegate to `argus install-commands`
└── README.md              # Project documentation

argus/assets/commands/ is the single command-asset tree. Every argus … line inside it is parsed by the real parser in CI (TC-ArgusAgent-DOCS-001-28), and TC-ArgusAgent-ASSETS-001-07 fails if a second tree ever appears in the repository.

---

🙏 Acknowledgements & Credits

Agent-Argus is built on the shoulders of giants in the open-source software community:

• BMAD Method (bmad-code-org/BMAD-METHOD): Special thanks to the BMAD Method team for their breakthrough framework and methodology in agile AI-driven software development.
• Tree-sitter: Concrete syntax tree parsing engine underpinning Argus's multi-language AST inspection and grounding.
• Pydantic: Data validation and schema management using Python type annotations.
• HTTPX & AnyIO: Asynchronous HTTP client runtime and concurrency primitives.
• Radon: Code metrics engine calculating cyclomatic complexity and maintainability index.
• Rich & Pygments: Terminal rendering, syntax highlighting, and CLI formatting.
• Python Open Source Ecosystem: Gratitude to PyPA, Pytest, and the broader open-source community.

---

🛡️ License

MIT License. See LICENSE for details.