internal-audit

internal-audit is a small local-first CLI that checks whether a repository matches a declared intent.yaml contract.

It does not call any cloud service, LLM, or telemetry endpoint.

5-Minute Quick Start

Source checkout:

git clone <repo-url>
cd internal-audit
pip install -e .
python scripts/smoke_test.py

Source checkout usage:

If you have not installed IA as a package, run commands with PYTHONPATH=src.

PowerShell:

$env:PYTHONPATH="src"
python -m ia.cli check

macOS/Linux:

PYTHONPATH=src python -m ia.cli check

Or install from the repo:

python -m pip install -e .
ia check

Verify a target repository:

cd /path/to/your/project
ia init
ia check

Do not run ia check from the internal-audit repo root unless you intentionally want to scan IA's own demo and validation fixtures. Run IA from the project you want to verify.

Expected output:

Wrote audit_receipt.md
Wrote audit_receipt.json
Final decision: PASS

Source Checkout Workflow

Use this when you are working directly from the IA source tree:

git clone <repo-url>
cd internal-audit
pip install -e .
python scripts/smoke_test.py
python scripts/hardening_validation.py
python scripts/adversarial_validation.py
python scripts/break_corpus.py

From the IA source checkout, you can also run the CLI module directly:

python -m ia.cli verify
python -m ia.cli check
python -m ia.cli demo

Installed Workflow

Use this when you want IA available as a normal command in another repository after installing it from this repo or another package source you control:

pip install /path/to/internal-audit
cd /path/to/target-repo
ia scaffold
ia check

If intent.yaml does not exist yet:

ia init
ia check

Commands

Initialize a contract:

ia init

Verify the current repository:

ia verify

Agent-friendly alias:

ia check

Create Codex-ready scaffolding:

ia scaffold

Run the built-in drift demo:

ia demo

Agent Integration

IA is designed to sit after code generation, not before it.

Recommended workflow:

1. Agent generates or edits code.
2. Agent runs ia check.
3. If IA returns FAIL, the agent stops, reads audit_receipt.md, repairs drift, and reruns ia check.
4. If IA returns PASS, the agent continues.

Agent setup docs:

• Using Codex
• Using Claude Code
• Using Cursor

Ready-to-paste prompts:

• Codex prompt
• Claude Code prompt

Auto-setup prototype:

• IA v0.2 Auto Setup Feasibility Spike
• This is a prototype only.
• It is not current v0.1 default behavior.
• It requires Codex or another cooperating agent to follow AGENTS.md or equivalent startup instructions.

Architecture

              +-------------------+
              |   intent.yaml     |
              | declared contract |
              +---------+---------+
                        |
                        v
              +-------------------+
              |   ia verify/check |
              | parse + scan repo |
              +---------+---------+
                        |
         +--------------+--------------+
         |              |              |
         v              v              v
   telemetry       local-first      shell/delete
    detector         detector         detectors
         \              |              /
          \             |             /
           +------------+------------+
                        |
                        v
              +-------------------+
              | audit_receipt.md  |
              | audit_receipt.json|
              +-------------------+

Default Intent

ia init creates this file when intent.yaml is missing:

no_telemetry: true
local_first: true
read_only: false
no_shell_execution: true

The parser is intentionally small for v0.1. It supports only flat boolean lines like key: true or key: false, ignores blank lines and # comments, and rejects nested YAML.

Verified Smoke Test

• pass_repo => PASS
• fail_repo => FAIL
• receipts generated: audit_receipt.md and audit_receipt.json

IA v0.1 intentionally uses a minimal boolean-only intent.yaml parser to remain offline and dependency-free.