Driftlock is an agent skill and a dependency-free Python CLI for keeping project documentation aligned with code as a repository changes.
It detects documentation drift deterministically, propagates review impact through declared dependencies, routes agents through layered indexes, and keeps archives outside the default context.
A change to src/auth/session.py makes the authentication contract STALE and
propagates REVIEW_REQUIRED only through its declared summary chain. The
unrelated billing contract stays CURRENT and out of the update queue.
Long-running projects often accumulate multiple status files, duplicated architecture notes, stale handoffs, and large archives. An AI agent can then read the wrong document, repeat completed work, or spend most of its context on history.
Driftlock makes freshness deterministic. Markdown documents declare their
identity and relationships in a small JSON index block. The CLI records reviewed
content hashes in .driftlock.lock.json and reports computed states:
CURRENTSTALEREVIEW_REQUIREDUNVERIFIED
- Progressive L0/L1/L2 documentation indexes
- One project entry point for agent routing
- SHA-256 freshness checks for documents and watched code paths
- Dependency propagation for summaries, status, and contracts
- Git-aware verification with dirty-path protection
- Read-only discovery and archive planning
- Archive isolation from startup context and active dependency graphs
- Structured JSON output for agents and CI
- Standard-library Python with no runtime dependencies
Driftlock is not tied to one model or coding agent:
- Any agent with shell access can run the Python CLI.
- Agents that support
SKILL.mdpackages can load the repository as a skill. - Agents without a skill system can use
SKILL.mdas project instructions and callscripts/driftlock.pydirectly. - Humans and CI can use the same CLI without an agent.
agents/openai.yaml provides optional OpenAI/Codex interface metadata. The core
skill and CLI do not import or depend on OpenAI libraries.
Clone the repository into the skill or instruction directory used by your agent:
git clone https://github.com/KairosSignal/driftlock.gitThen either register the cloned directory as the driftlock skill or run the
CLI from it. Consult your agent's documentation for its skill discovery
directory.
Ask Codex to install the public skill:
Install the Driftlock skill from https://github.com/KairosSignal/driftlock
Or clone it into the Codex skills directory:
git clone https://github.com/KairosSignal/driftlock.git \
~/.codex/skills/driftlockRestart Codex after installation so the skill is discovered.
For any agent, ask it to read SKILL.md and use the bundled CLI:
Read the Driftlock SKILL.md, audit this repository's documentation, and report
the minimum updates needed. Do not read archives unless required.
Invoke the skill explicitly:
Use $driftlock to audit this repository's documentation and report the minimum
updates needed. Do not read archives unless required.
The skill also triggers for documentation audits, reorganization, freshness validation, archive isolation, project-map creation, and task/report sprawl.
Requirements:
- Python 3.9 or newer
- Git 2.25 or newer for commit-aware verification
- Linux, macOS, or Windows
Git is optional only in explicit hash-only mode. Without Git, verify requires
--allow-hash-only and reports reduced assurance.
Run the CLI directly from the skill directory:
python3 scripts/driftlock.py discover /path/to/project
python3 scripts/driftlock.py check /path/to/project
python3 scripts/driftlock.py impact /path/to/project --since HEAD~1
python3 scripts/driftlock.py verify /path/to/project \
--doc project-entry --status-effect initial
python3 scripts/driftlock.py archive-plan /path/to/projectAdd --format json for automation.
discover, check, impact, and archive-plan are read-only. verify is the
only writing command, and it writes only .driftlock.lock.json atomically.
CLI JSON reports and generated lock files include tool_version. The current
release line is 0.2.0.
Driftlock uses its own v0.2 format:
.driftlock.lock.jsonstores verified document state.driftlock-indexis the Markdown metadata fence.scripts/driftlock.pyis the only CLI implementation.
The target repository is always selected at runtime with project_root; none of these identifiers are a target-project name.
Run the bundled example from any checkout:
python3 examples/run_demo.pyThe demo creates a temporary Git repository, verifies four documents to
CURRENT, changes authentication code, and checks that only the authentication
contract and its summary chain enter the update queue. It also demonstrates the
CI contract: exit code 1 is ordinary stale state, while only 2 and 3
block.
Every managed Markdown file contains one fenced driftlock-index block with
strict JSON. A minimal L0 entry looks like this:
```driftlock-index
{
"schema_version": 2,
"id": "project-entry",
"authority_key": "project.entry",
"level": 0,
"role": "project_entry",
"lifecycle_status": "active",
"startup": [
"docs/current/status.md",
"docs/current/task-board.md"
],
"startup_budget": {
"max_files": 5,
"max_characters": 12000
},
"archive_roots": [
"docs/archive"
]
}
```Use discover first when a repository has no valid L0 entry. It reports
candidates without inventing authority or moving files.
- Run
discoverto understand the existing documentation. - Establish one L0 entry and narrow L1 branches.
- Add indexes and explicit dependency edges.
- Review each document and run
verify. - Commit
.driftlock.lock.jsonwith the reviewed documents. - Run
checkin agent workflows or CI.
Driftlock never automatically rewrites semantic content, assigns authority, moves documents, or deletes archives. Those remain explicit human or agent decisions.
| Code | Meaning |
|---|---|
0 |
Current and structurally valid |
1 |
Ordinary stale, review-required, or unverified state |
2 |
Structural error or refused verification |
3 |
Argument, Git, permission, JSON, or filesystem failure |
CI wrappers should treat 0 and 1 as non-blocking and block only on 2 or
3.
python3 -m unittest discover -s tests -p 'test_*.py'MIT