chore: add spec-drift detection commands and pre-commit hook#649
chore: add spec-drift detection commands and pre-commit hook#649ciscoRankush wants to merge 3 commits intonextfrom
Conversation
Add automated SDD documentation drift detection tooling: - /spec-drift: full scan command for validating all ai-docs against source code - /spec-drift-changed: incremental scan for changed files only - Pre-commit hook to block commits when ai-docs drift is unverified Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 17636199d6
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
.claude/hooks/check-ai-docs-drift.sh
Outdated
| case "$COMMAND" in | ||
| git\ commit*) ;; # Continue to check | ||
| *) exit 0 ;; # Not a commit, allow immediately |
There was a problem hiding this comment.
git commit
The hook only enforces validation when the command string starts with git commit, so commit flows like git -c user.name=... commit ..., HUSKY=0 git commit ..., or chained commands such as git add . && git commit ... will bypass this guard and allow unverified contact-center changes to be committed. Since this script is meant to be the blocking gate, matching only one command shape leaves a real enforcement hole.
Useful? React with 👍 / 👎.
| esac | ||
|
|
||
| # Get staged files under the contact-center package | ||
| STAGED_CC=$(git diff --cached --name-only 2>/dev/null | grep "^${CC_PKG}/") |
There was a problem hiding this comment.
The marker hash is derived from git diff --cached --name-only output, which means it changes only when the set of staged file paths changes; if a developer runs /spec-drift-changed, then edits and restages the same files, the existing marker still matches and the commit is allowed without re-validating docs against the new content. This weakens the drift check and can let stale verification pass.
Useful? React with 👍 / 👎.
|
This pull request is automatically being deployed by Amplify Hosting (learn more). |
Shreyas281299
left a comment
Shreyas281299
left a comment
There was a problem hiding this comment.
Review Summary
| Severity | Count |
|---|---|
| High | 3 |
| Medium | 3 |
| Low | 6 |
Recommendation: Request Changes -- The 3 High severity issues should be addressed before merge:
- Register the hook in
settings.json(otherwise the hook is dead code) - Fix "Task tool" -> "Agent tool" references (otherwise the commands will fail)
- Add
python3availability check (otherwise the hook silently becomes a no-op)
Positive Observations
- Well-structured command files with clear step-by-step instructions and output format templates
- The 7-category drift detection framework is comprehensive and well-defined
- Good use of severity levels (Blocking/Important/Medium/Minor) in the drift report
- The incremental scan (
spec-drift-changed) is a practical addition for pre-commit workflows - The shell hook logic is concise and handles the common cases correctly
- Register hook in settings.json (was dead code without it) - Fail-closed when python3 unavailable or JSON parse fails - Use content-based hash (git diff --cached) instead of path-only hash - Don't consume marker in PreToolUse — invalidated naturally by content changes - Precise case pattern to avoid matching git commit-tree - Add shasum/sha256sum portability fallback - Fix "Task tool" → "Agent tool" references in command files - Add agent timeout handling rule - Add staged-only content note for verification marker - Make widget path mappings dynamic instead of hardcoded - Label inventory as example - Document advisory-only nature of verification Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3cf0a3f6e5
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| 1. **Repo detection**: This is ccWidgets — `packages/contact-center/` exists (no `@webex` scope) | ||
| 2. **Root AGENTS.md**: `AGENTS.md` (repo root) | ||
| 3. **Framework docs**: `ai-docs/` (README, RULES, patterns/*, templates/*) | ||
| 4. **Package-level ai-docs**: Glob for `packages/contact-center/**/ai-docs/` to find all ai-docs folders |
There was a problem hiding this comment.
packages/contact-center/**/ai-docs/ only finds directories literally named ai-docs, so in this repo it returns packages/contact-center/task/ai-docs but not packages/contact-center/task/ai-docs/widgets/{CallControl,IncomingTask,OutdialCall,TaskList}. I checked that packages/contact-center/task/ai-docs itself has no markdown files, so /spec-drift would skip every task-widget AGENTS.md/ARCHITECTURE.md and silently miss drift in that scope.
Useful? React with 👍 / 👎.
| From the changed files, build TWO lists: | ||
|
|
||
| ### List A: Changed ai-docs files | ||
| Filter for files matching `ai-docs/*.md`. These docs changed directly and need validation. |
There was a problem hiding this comment.
The literal ai-docs/*.md filter only matches markdown files directly under an ai-docs directory. In this repo the task widget docs are nested at packages/contact-center/task/ai-docs/widgets/*/*.md, so editing something like .../TaskList/AGENTS.md would not enter List A, and because List B only examines source files, /spec-drift-changed can incorrectly report “nothing to check” when the changed files are the docs themselves.
Useful? React with 👍 / 👎.
| 2. **Root AGENTS.md**: `AGENTS.md` (repo root) | ||
| 3. **Framework docs**: `ai-docs/` (README, RULES, patterns/*, templates/*) | ||
| 4. **Package-level ai-docs**: Glob for `packages/contact-center/**/ai-docs/` to find all ai-docs folders | ||
| 5. **Samples ai-docs**: Check `widgets-samples/**/ai-docs/` as well |
There was a problem hiding this comment.
The comprehensive scan only discovers package ai-docs plus widgets-samples/**/ai-docs/, but this repo also contains playwright/ai-docs/AGENTS.md and playwright/ai-docs/ARCHITECTURE.md. As written, /spec-drift never spawns a checker for the Playwright framework docs, so drift in the E2E testing guidance goes undetected even though the root AGENTS.md routes Playwright work to that scope.
Useful? React with 👍 / 👎.
2 participants
This pull request addresses
Adding automated SDD (Spec-Driven Development) documentation drift detection tooling to ensure ai-docs stay in sync with source code.
by making the following changes
.claude/commands/spec-drift.md— Full scan command that auto-discovers all ai-docs folders, spawns parallel checker agents, and validates 7 drift categories (file tree, method/API, types, events, architecture, links, code examples).claude/commands/spec-drift-changed.md— Incremental scan that only validates ai-docs affected by staged/unstaged file changes, with verification marker creation.claude/hooks/check-ai-docs-drift.sh— Pre-commit blocking hook that prevents committing when ai-docs drift is unverifiedChange Type
The following scenarios were tested
The GAI Coding Policy And Copyright Annotation Best Practices
I certified that