AIV quick-start tutorial

This page gets the current source build running on one repository. For a guided lab that exercises all 16 gates one by one, continue to AIV Hello World.

AIV deployment path

Figure 1: Start small and move the same verdict into CI. The developer path gives fast local feedback. CI adds trusted-policy enforcement and machine reports. Agents and AI-DLC call the same core through aiv verify.

1. Build the current source version

Release 2.0.0 includes the policy snapshot, schema-v2 verify, strict JSON, the AI-DLC plugin, and the hardened Action. Build tag v2.0.0, or download aiv-cli-2.0.0.jar when that coordinate is on Maven Central.

git clone https://github.com/vaquarkhan/aiv-integrity-gate.git
cd aiv-integrity-gate
mvn clean verify
export AIV_JAR="$(pwd)/aiv-cli/target/aiv-cli-2.0.0.jar"
java -jar "$AIV_JAR" verify --capabilities

Expected capability output includes strict-options, trusted-policy, policy-tree-digest, external-input-disclosure, and audit-chain.

2. Choose a starting profile

# smallest: syntax + invariant only
java -jar "$AIV_JAR" init --preset minimal --workspace /path/to/project

# balanced Java repository
java -jar "$AIV_JAR" init --preset java-ci --workspace /path/to/project

# broad generated-change checks
java -jar "$AIV_JAR" init --preset agent-paste-strict --workspace /path/to/project

Every shipped preset explicitly names all 16 gates. Read MODULE-ADOPTION-GUIDE.md before enabling optional network/model/tool-backed gates.

3. Commit policy to the primary branch

cd /path/to/project
git add .aiv
git commit -m "Add AIV integrity policy"

Policy-bearing files belong under .aiv/:

.aiv/
  config.yaml
  design-rules.yaml
  doc-rules.yaml
  baseline.txt
  rules/team.yaml

AIV pins the base ref to one commit, snapshots these files, and makes policy-bearing gates consume the frozen copy.

4. Run locally

java -jar "$AIV_JAR" --workspace . --diff origin/main --head HEAD

Exit codes:

5. Write machine reports

java -jar "$AIV_JAR" --workspace . --diff origin/main --head HEAD \
  --output-json aiv-report.json \
  --output-sarif aiv-results.sarif

JSON carries every gate, finding, severity, and notice. SARIF maps blockers to error, advisory findings to warning, and visible unverified evidence to note.

6. Enable strict CI policy

java -jar "$AIV_JAR" --workspace . --diff origin/main --head HEAD \
  --require-trusted-config \
  --output-json aiv-report.json \
  --output-sarif aiv-results.sarif

Strict mode refuses fallback, ignored/untracked .aiv extras, symlinks, path escapes, and any policy-tree mismatch. A pull request cannot replace its own yardstick.

Immutable policy and evidence

Figure 2: Strict policy comes from a pinned commit, not the proposed change. The same snapshot is used for design, generic rules, documentation rules, baselines, evidence digests, and audit metadata.

7. Call AIV from an agent or tool

java -jar "$AIV_JAR" verify \
  --request change.json \
  --workspace . \
  --policy-ref origin/main \
  --require-trusted-policy \
  --audit-log .aiv/audit.log

Stdout is one schema-v2 JSON object. Diagnostics stay on stderr. Full request/response contract: MCP.md.

8. Verify audit evidence

java -jar "$AIV_JAR" audit verify .aiv/audit.log
java -jar "$AIV_JAR" report --audit-log .aiv/audit.log --out aiv-evidence.html

Store the returned head outside the log when independent tamper evidence is required.

9. Add AI-DLC

python "$AIV_SOURCE/integrations/aidlc/aiv_aidlc_sensor.py" \
  --aiv-jar "$AIV_JAR" \
  --request change.json \
  --workspace . \
  --policy-ref origin/main \
  --blocking

The complete plugin provides advisory and fail-closed manifests. See AIDLC.md.

10. Learn every gate

The full lab includes runnable examples for syntax, invariant, dependency, package existence, test adequacy, security, design, generic rules, density, cohesion, duplication, external SARIF, documentation integrity, PR metadata, license headers, and Jev:

Continue to AIV Hello World

Reference paths

Author: Viquar Khan