Doctor: detect settings.local.json drift

[bguidolim]

Context

With #45 resolved, mcs doctor now detects content drift in CLAUDE.local.md sections via SHA-256 hash comparison. The same approach should be extended to settings.local.json, which is composed from multiple packs.

Complexity

Unlike single-file artifacts, settings.local.json is a composed file where multiple packs contribute entries (hook groups, settings keys). Drift detection requires either:

• Option A: Hash the entire composed file and re-compose at doctor time for comparison
• Option B: Track per-pack contribution hashes and verify each pack's contributions independently

Option A is simpler but may false-positive on key ordering differences. Option B is more precise but requires decomposing the file.

Acceptance criteria

• Doctor check detects when settings.local.json has been manually edited
• Changes to user-owned keys (outside pack-managed keys) are not flagged
• --fix restores pack-managed portions while preserving user additions
• Tests cover: matching state, drifted pack keys, user-added keys preserved

[bguidolim]

Assessment (2026-03-06)

Still valid?

Yes. Settings drift detection does not exist — the Doctor system has zero settings-related checks. The content drift infrastructure from PR #229 covers installed files (hooks, skills, commands, agents) via FileContentCheck + fileHashes, but settings.local.json is a composed file and was left out.

Foundation exists

PackArtifactRecord.settingsKeys already tracks which keys each pack contributes. This provides the "which keys are pack-managed" half of the problem. What's missing is recording the expected values so drift can be detected.

Complexity assessment

This is genuinely harder than file drift detection because:

• Multiple packs contribute to the same composed file
• User-owned keys must not be flagged
• JSON key ordering could cause false positives with whole-file hashing
• --fix must re-compose pack portions while preserving user additions

Option B (per-pack contribution hashes) from the issue description is the more robust approach.

Recommendation

Keep open at P2. The issue is well-scoped and the acceptance criteria are clear. It should wait until the file-level drift detection (PR #229) has been battle-tested, or until a user reports a real-world issue caused by settings drift going undetected.

[bguidolim]

Assessment (2026-03-21)

Prerequisite met

File-level drift detection (PR #229) is now in place and battle-tested — FileContentCheck + fileHashes covers hooks, skills, commands, and agents. The "wait for file-level drift to stabilize" blocker from the previous assessment is cleared.

Still valid

Settings drift detection still does not exist. settings.local.json remains unchecked by doctor.

Core complexity unchanged

settings.local.json is a composed file (multiple packs contribute keys), so the file-level FileContentCheck pattern doesn't apply directly. Per-pack contribution tracking is needed:

• PackArtifactRecord.settingsKeys already tracks which keys each pack contributes (key names only)
• Missing: recording expected values per pack so drift can be detected
• Option B (per-pack contribution hashes) remains the more robust approach

Recommendation

Ready for implementation when prioritized. The prerequisite infrastructure is in place, the design direction is clear (Option B), and the acceptance criteria are well-defined. Bump to P1 when there's capacity, or if a user reports a real-world settings drift issue.