mtk-agent-toolkit: Skill for Claude Code

Spec-Drift Detection

Tool discipline: read-only — Read/Grep/Glob and read-only Bash (git diff, the drift scripts). Never Edit/Write code or the spec; report drift, never fix it.

Overview

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

When To Use

• After implementation batches complete, before handing to compliance-reviewer in Phase 4
• A spec manifest exists at docs/specs/<date>-<slug>.json and the reviewer wants to confirm the declared scope was honored

When NOT To Use

• Quick fixes, typo fixes, or config updates that ran without a spec, or 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).