💡 Agent Configuration Content-Addressed Lockfile & Drift Detection Standard

[github-actions[bot]]

Summary

Create a lockfile mechanism for agent configuration files (CLAUDE.md, AGENTS.md, SKILL.md) that provides SHA-256 content addressing, tamper detection, and drift alerting — ensuring agent behavior definitions are treated as a managed supply chain artifact rather than unversioned prose. This applies the same integrity guarantees that package-lock.json provides for dependencies to the agent configs that govern automated behavior.

Market Signal

The Rel(AI)Build research (arXiv:2606.26924, June 2026) studied 10,008 public GitHub repositories and found alarming patterns in agent configuration management:

• 10.1% of agent config paths are SHA-256 exact duplicates across independent repos (copy-paste without understanding)
• 75.5% of clone pairs cross organizational boundaries — configs propagate unvetted across org lines
• Configs are rarely revised (58% single-commit, set-and-forget)
• Critically, fewer than 1% declare permission boundaries

The paper proposes SHA-256 content-addressed lockfiles with HMAC-stamped integrity and hash-chained audit logs. Core insight: every governance mechanism must be implemented in deterministic code, not delegated to an LLM, because a non-deterministic component cannot serve as a trustworthy control for another non-deterministic component.

User Signal

This org's AGENTS.md is the source of truth for agent behavior across all repos. The existing compliance audit checks for AGENTS.md presence and feature-ideation config validity but does not verify content integrity or detect unauthorized modifications. The standards fleet deployment system (#919) distributes configs but cannot verify they haven't been locally modified post-deployment. The cross-repo standards drift detection idea (#761) operates at a higher level — this proposal addresses file-level tamper detection.

Technical Opportunity

compliance-audit.sh already hashes and compares workflow files — extending this to agent configs is a natural evolution. A .agent-lock.json file at the repo root would contain SHA-256 hashes of all agent config files, verified by a CI check. The existing canary-rollout system provides the deployment channel for lockfile updates. The approach is fully deterministic (hashing, comparison) with no LLM dependency.

Assessment

Dimension	Score	Rationale
Feasibility	high	Extends existing compliance-audit.sh hashing patterns; pure shell + jq implementation
Impact	high	Closes a quantified gap (<1% permission boundaries) and detects unauthorized config modifications
Urgency	med	No active exploitation of agent config tampering documented yet, but the attack surface is growing as agent adoption accelerates

Adversarial Review

Strongest objection: Agent configs are Markdown prose that changes frequently during development. A lockfile mechanism adds maintenance burden and could block legitimate config updates with false-positive drift alerts.

Rebuttal: The lockfile is regenerated automatically (like package-lock.json) whenever agent configs change — it is not manually maintained. Drift detection fires only on unexpected changes (configs modified without updating the lockfile), which is exactly the scenario indicating tampering or unauthorized modification. The 58% single-commit finding shows most configs are set-and-forget, minimizing churn. A CI-only check (warn, don't block) provides a safe starting posture.

Suggested Next Step

Create scripts/lib/agent-config-lockfile.sh that: (1) generates .agent-lock.json from all CLAUDE.md/AGENTS.md/SKILL.md files, (2) verifies integrity at CI time, (3) integrates into compliance-audit.sh as a new check category. Add a pre-commit hook option for local verification.