agent-governance 1.0.0

Agent governance tooling

Bounded Agent Framework

This repository defines a repo-local, enforceable framework for using AI sub-agents as bounded workers.

This is not an application. This is not an orchestration service. This is not an autonomy experiment.

This is infrastructure.

---

What this system is

• Agents are roles defined in Markdown
• Agents are instantiated per model call
• Nothing is persistent
• Nothing runs automatically
• Nothing is trusted without artifacts

The framework exists to:

• force correct task decomposition
• prevent scope creep
• require evidence for completion
• make agent behavior reproducible and auditable

---

Core invariants

1. Repo-local

   • All agent rules, schemas, and tools live in the repo
   • No systemwide installs
   • No hidden dependencies

2. Separation of concerns

   • Agent roles (Markdown) change frequently
   • Schemas change occasionally
   • Tooling changes rarely

3. Artifacts over prose

   • Diffs, logs, commands, tests are required
   • Narrative text is secondary

4. Orchestrator ≠ implementer

   • Orchestrator plans and validates
   • Workers produce changes
   • Single-writer rule per scope

5. No schema, no run

   • Tasks and outputs must validate
   • Invalid packets are rejected

---

Repository layout (expected)

agents/ roles/ contracts/ checklists/ tools/ logs/ reports/ adr/

---

Usage summary

1. Create a task packet (YAML)
2. Validate it against schema
3. Run the agent with role + task
4. Collect output packet + artifacts
5. Validate output
6. Gate before merge

Tooling baseline: use agent-governance>=1.0.0.

Repo introspection

agentctl init scans the current repo to generate a policy overlay plus an evidence-backed report. It never edits repo files unless --write is set, and it never calls an LLM.

What it never does:

• no network access
• no repo mutation (except writing the three outputs when --write is set)
• no heuristic guesses without a cited file + line range

Outputs (when --write):

• .agents/generated/AGENTS.repo.overlay.yaml
• .agents/generated/init_report.md
• .agents/generated/init_facts.json

At runtime, the orchestrator merges the overlay with the base policy to add repo-specific verify commands and risk paths before dispatching work. This lets one global role set adapt to local tooling without changing the core policy.

Deterministic + auditable:

• each detected fact includes a source file and line range
• output ordering is stable for diff-friendly review
• dry-runs show planned writes without touching disk

Update checks

The CLI can optionally warn if a newer agent_governance version exists. Defaults: once per 24h, skipped in CI, and never blocks command execution.

Disable with --update-check=off or AGENT_UPDATE_CHECK=off. Repos may set update_check: off in agents/repo_profile.yaml to fully disable network use.

This system replaces trust with structure.