mtk-agent-toolkit: Skill for Claude Code

Spec-Drift Detection

Overview

Verify that the implementation actually delivered what the spec promised — nothing more, nothing less. Drift between spec and implementation is a compliance risk in regulated environments: it means the approval gate at Phase 2.5 did not cover the final code. Detect divergence before review.

When To Use

• After implementation batches complete
• Before handing to compliance-reviewer in Phase 4
• When a spec manifest exists at docs/specs/<date>-<slug>.json
• Whenever a change was supposed to follow a spec-driven flow and the reviewer wants to confirm the scope was honored

When NOT To Use

• Quick fixes that ran through the fix workflow without a spec
• Typo fixes and config updates
• Sessions where no spec manifest was ever produced

Workflow

1. Locate the spec manifest.

   • Default: the latest docs/specs/*.json on the current branch.
   • Override: accept an explicit path if the engineer supplies one.
   • If no manifest exists, STOP and report BLOCKED — no spec manifest found; drift cannot be checked. Either generate one via spec-driven-development or confirm this change is quick-fix scope.

2. Load the manifest schema fields:

   • scope — classification string
   • change_manifest — array of { path, action, purpose }
   • public_contracts — array of { kind, signature, change }
   • success_criteria — array of { id, description, verification }
   • out_of_scope — array of strings
   • security_impact — enum string

3. Collect actual change data:

   • Preferred (deterministic): run bash scripts/validate-handoff.sh docs/specs/<date>-<slug>.json to compute file-level and security-impact drift against the manifest. Treat its output as authoritative for those axes.
   • If the handoff has an implement.actual_files array, diff it against change_manifest[].path directly — no git invocation needed.
   • Otherwise, fall back to git diff --name-status <base>...HEAD.
   • For contract-level drift (not covered by the script): grep the diff for added/modified public contracts (controller routes, handler classes, exported functions, etc., per active tech stack).