activememory/ctx/ctx-drift

Detect context drift at two layers: structural (stale paths, missing files, constitution violations) via ctx drift, and semantic (outdated conventions, superseded decisions, irrelevant learnings) via agent analysis. The semantic layer is where the real value is: the CLI cannot do it.

When to Use

• At session start to verify context health before working
• After refactors, renames, or major structural changes
• When the user asks "is our context clean?", "anything

stale?", or "check for drift"

• Proactively when you notice a path in ARCHITECTURE.md or

CONVENTIONS.md that does not match the actual file tree

• Before a release or milestone to ensure context is accurate

When NOT to Use

• When you just ran /ctx-status and everything looked fine

(status already shows drift warnings)

• Repeatedly in the same session without changes in between
• When the user is mid-flow on a task; do not interrupt with

unsolicited maintenance

Usage Examples

/ctx-drift
/ctx-drift (after the refactor)

Execution

Drift detection has two layers: structural (programmatic) and semantic (agent-driven). Always do both.

Layer 1: Structural Checks

Run the CLI tool for fast, programmatic checks:

ctx drift

This catches dead paths, missing files, staleness indicators, and constitution violations. These are necessary but insufficient: they only detect structural problems.

Layer 2: Semantic Analysis

After the structural check, read the context files yourself and compare them to what you know about the codebase. This is where you add real value: the CLI tool cannot do this.

Check for:

• Outdated conventions: Does CONVENTIONS.md describe patterns

the code no longer follows? Read a few source files in the relevant area to verify.

• Superseded decisions: Does DECISIONS.md contain entries that

were implicitly overridden by later work? Look for decisions whose rationale no longer applies.

• Stale architecture descriptions: Does ARCHITECTURE.md

describe module purposes that have changed? A path can still exist while its description is wrong.

• Irrelevant learnings: Does LEARNINGS.md contain entries

about bugs that were since fixed or patterns that no longer apply?

• Contradictions: Do any context files contradict each other

or contradict the actual code?

Reporting

After both layers, do not dump raw output. Instead:

1. Summarize findings by severity (structural warnings,

semantic issues) in plain language

1. Explain each finding: what file, what line, why it

matters

1. Distinguish structural from semantic: structural issues

can be auto-fixed; semantic issues need the user's judgment

1. Offer to auto-fix structural issues:

"I can run ctx drift --fix to clean up the dead path references. Want me to?"

1. Propose specific edits for semantic issues:

"CONVENTIONS.md still says 'use fmt.Printf for output' but we switched to cmd.Printf three weeks ago. Want me to update it?"

1. Suggest follow-up commands when appropriate:

• Many stale paths after a refactor → suggest ctx sync
• Heavy task clutter → suggest ctx compact --archive
• Old files untouched for weeks → suggest reviewing content

Interpreting Results

Auto-Fix

When the user agrees to auto-fix:

ctx drift --fix

After fixing, run ctx drift again to confirm remaining issues need manual attention. Report what was fixed and what still needs the user's judgment.

Skill Template Drift

After running ctx drift, check whether the project's installed skills (.claude/skills/) match the canonical templates shipped with ctx.

Procedure

1. Create a temp directory and run ctx init --reset inside

it to get the latest templates:

``bash CTX_TPL_DIR=$(mktemp -d) cd "$CTX_TPL_DIR" && ctx init --reset 2>/dev/null ``

1. Compare each skill in the project against the template:

``bash diff -ru "$CTX_TPL_DIR/.claude/skills/" .claude/skills/ 2>/dev/null ``

1. Clean up the temp directory:

``bash rm -rf "$CTX_TPL_DIR" ``

Interpreting Skill Drift

When reporting skill drift, distinguish between:

• ctx-managed skills (present in the template): these

should generally match; differences mean the user's copy is outdated or was customized intentionally

• Custom skills (only in the project): these are user

additions and should not be flagged as drift

If a skill was intentionally customized, note it and move on. Offer to update only ctx-managed skills, and always show the diff before overwriting.

Permission Drift

After checking skills, verify that .claude/settings.local.json has the expected ctx permissions. This file is gitignored, so it drifts independently from the codebase.

Procedure

1. Read .claude/settings.local.json and extract the allow list.

1. Check for missing ctx defaults. Every entry in

DefaultAllowPermissions() (defined in internal/assets/permissions/allow.txt) should be present. The current expected set is:

• Bash(ctx:*): covers all ctx subcommands
• Skill(ctx-*): one entry per ctx-shipped skill

To get the authoritative list:

``bash ctx init --reset 2>/dev/null # in a temp dir ``

Then compare permissions from the generated settings.local.json against the project's copy.

1. Check for stale skill permissions. If a Skill(ctx-*)

entry references a skill that no longer exists in .claude/skills/, flag it.

1. Check for missing skill permissions. If a ctx-* skill

exists in .claude/skills/ but has no corresponding Skill(ctx-*) in the allow list, flag it.

Interpreting Permission Drift

Important

Do not edit settings.local.json directly. Report findings and let the user make changes. This file controls agent permissions: self-modification is a security concern. Refer users to docs/operations/runbooks/sanitize-permissions.md for the manual cleanup procedure.

Proactive Use

Run drift detection without being asked when:

• You load context at session start and notice a path

reference that does not match the file tree

• The user just completed a refactor that renamed or moved

files

• TASKS.md has obviously heavy clutter (20+ completed items

visible when you read it)

When running proactively, keep the report brief:

I ran a quick drift check after the refactor. Two stale

path references in ARCHITECTURE.md. Want me to clean

them up?

Quality Checklist

After running drift detection, verify:

• [ ] Summarized findings in plain language (did not just

paste raw CLI output)

• [ ] Explained why each finding matters
• [ ] Offered auto-fix for fixable issues before running it
• [ ] Suggested appropriate follow-up commands
• [ ] Did not run --fix without user confirmation