Drift detection

What drift means

Drift is the gap that opens when your project changes but the files Paqad keeps about it do not. A new framework appears in package.json, rules are edited, a module folder is renamed, and the AI may now be working from an outdated picture.

Paqad tracks three kinds of drift, each with its own check. All three are scripts that compare files; none of them asks an AI.

Kind	What is compared	Where the result goes
Stack drift	Your current packages against the last recorded stack snapshot	.paqad/stack-drift.json
Rule drift	The rules in docs/instructions/rules/ against Paqad's compiled copy of them	The doctor check "Compiled rules are current"
Module-map drift	module-map.yml and docs/modules/ against your source folders	.paqad/module-map/drift.json

Stack drift: how changes to your dependencies are caught

Every time detection runs (during paqad-ai onboard, paqad-ai join, paqad-ai refresh --stack and the documentation workflow), Paqad compares the fresh result with the previous .paqad/stack-snapshot.json and lists these changes:

• framework-added and framework-removed, for example React added to a project;
• trait-added and trait-removed, for example Tailwind or Docker;
• version-band-changed, when a key package moves to a new major version, such as ^10 to ^11;
• toolchain-changed, when package managers or lock files change.

If there are changes, the report's status is drift-detected; otherwise no-drift. The report also lists review_targets: the documentation likely to need an update. A framework change points at docs/instructions/architecture/**, docs/instructions/stack/** and the module UI and API docs; a version-band change points at docs/instructions/stack/version-rules.md and the architecture docs.

A detected change stays in the report until a later run finds a new change. A run that finds nothing new does not clear it, so check the report's generated_at time to see when the recorded change happened.

How to see stack drift

• Open .paqad/stack-drift.json. It is a per-machine file that git ignores.
• After paqad-ai refresh --stack, read docs/instructions/stack/drift-report.md, a readable version with the changes and review targets.
• In paqad-ai dashboard, the "Stack drift" section shows the status, the number of changes and how old the report is.

What to do about stack drift

1. Run paqad-ai refresh --stack to record the current stack and rewrite the stack documents.
2. If frameworks or traits changed, run paqad-ai refresh --rules to see which rule files would change, and --rules --force to apply it (this replaces edited rules; commit first).
3. Ask your AI tool to update the documents listed in review_targets, for example with create documentation. This part is AI work, so review the result.

Rule drift: when the AI could see outdated rules

Paqad compiles the rules in docs/instructions/rules/ into a store, .paqad/compiled-rules.json, and serves rule text to the AI from it. The store records a fingerprint of the rule files. When you edit a rule, the fingerprint no longer matches and paqad-ai doctor fails "Compiled rules are current", because the AI could be given rule text that differs from what is on disk. Run paqad-ai rag refresh-context to recompile the store.

Module-map drift: when modules and code stop matching

The module map, docs/instructions/rules/module-map.yml, lists your project's modules and features and is created by the documentation workflow. To compare it with your code, run:

paqad-ai refresh --reconcile-module-map

Paqad scans the source folders your stack pack names and writes findings to .paqad/module-map/drift.json. Findings have codes such as MM-ADD (code with no module in the map), MM-REMOVE (a module whose code is gone), MM-DOC-MISSING and MM-DOC-ORPHAN (module docs missing, or docs for a module that no longer exists). The command exits with an error code when it finds anything, so you can use it in CI. It never edits the map; changes to the map go through your review. paqad-ai module-map reconcile offers more options, such as --source-roots and --json.

What drift checks do not cover

None of these checks reads your documentation to judge whether it still describes the code correctly. They detect that something changed and point at what to review. Deciding whether a document is wrong, and rewriting it, is done by the AI in the documentation workflow or by you. Keeping Paqad's files current lists which command to run after each kind of change.