Skip to content

Commit 64a3f77

Browse files
ciscoRankushclaudeRankush Kumar
authored
chore: add spec-drift detection commands and pre-commit hook (#649)
Co-authored-by: ciscoRankush <ciscoRankush@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Rankush Kumar <rankkuma+cisco@cisco.com>
1 parent 8642d32 commit 64a3f77

4 files changed

Lines changed: 436 additions & 0 deletions

File tree

‎.claude/commands/spec-drift-changed.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Spec Drift Detection — Changed Files Only
2+
3+
Validate ai-docs affected by any staged/unstaged changes — whether the changes are to ai-docs themselves OR to source code that has corresponding ai-docs. Lightweight mode for pre-commit validation.
4+
5+
## Step 1: Find All Changed Files
6+
7+
Run these commands to find all changed files (staged and unstaged):
8+
9+
```bash
10+
# Get both staged and unstaged changed files
11+
(git diff --name-only HEAD 2>/dev/null; git diff --name-only --cached 2>/dev/null) | sort -u
12+
```
13+
14+
## Step 2: Identify ai-docs That Need Validation
15+
16+
From the changed files, build TWO lists:
17+
18+
### List A: Changed ai-docs files
19+
Filter for files matching `ai-docs/*.md`. These docs changed directly and need validation.
20+
21+
### List B: Source code files with corresponding ai-docs
22+
For each changed source file under `packages/contact-center/` (excluding ai-docs files themselves):
23+
1. Walk up the file's directory path
24+
2. Check if any ancestor directory contains an `ai-docs/` folder
25+
3. If yes, that `ai-docs/` folder needs validation against the updated source code
26+
27+
Use this to discover ai-docs folders:
28+
```bash
29+
find packages/contact-center -type d -name "ai-docs"
30+
```
31+
32+
Build a mapping like:
33+
```
34+
Changed source file → ai-docs to validate
35+
packages/contact-center/store/src/store.ts → packages/contact-center/store/ai-docs/
36+
packages/contact-center/task/src/widgets/CallControl/CallControl.tsx → packages/contact-center/task/ai-docs/widgets/CallControl/
37+
packages/contact-center/cc-components/src/SomeComponent.tsx → packages/contact-center/cc-components/ai-docs/
38+
```
39+
40+
For task widget source files, map to the widget-specific ai-docs dynamically:
41+
- `packages/contact-center/task/src/widgets/{WidgetName}/*` → `packages/contact-center/task/ai-docs/widgets/{WidgetName}/` (if the ai-docs folder exists)
42+
43+
This covers all current and future widgets (e.g., CallControl, IncomingTask, OutdialCall, TaskList, and any new widgets added later).
44+
45+
**Deduplicate**: If multiple source files map to the same ai-docs folder, validate that folder only once.
46+
47+
### Combine Lists A and B
48+
The final set of ai-docs folders to validate is the union of:
49+
- Folders containing files from List A
50+
- Folders identified from List B
51+
52+
If NEITHER list has entries, report: **"No ai-docs affected by current changes — nothing to check."** and stop.
53+
54+
## Step 3: Validate Affected ai-docs
55+
56+
For each ai-docs folder that needs validation, spawn an Explore agent with this prompt:
57+
58+
```
59+
You are validating SDD documentation accuracy against source code.
60+
61+
SOURCE OF TRUTH (actual code): {source_code_directory}
62+
DOCS TO VALIDATE: {ai_docs_folder} (all .md files in this folder)
63+
64+
CHANGED SOURCE FILES (if any): {list of changed source files in this package}
65+
CHANGED DOC FILES (if any): {list of changed ai-docs files}
66+
67+
Read every markdown file in the ai-docs folder. For each document, check these 7 categories:
68+
69+
1. FILE TREE: Read any documented file/directory trees. Glob the actual directory. Report missing/extra files.
70+
71+
2. METHOD/API SIGNATURES: For every method documented, read the actual source and verify: name, params, param types, return type, modifiers. Flag any mismatch. Pay special attention to methods in changed source files — new methods may be missing from docs, or changed signatures may not be reflected.
72+
73+
3. TYPE DEFINITIONS: For every type/enum/interface documented, find the actual definition in source. Compare name, fields, field types, enum values. Check if changed source files introduced new types not yet documented.
74+
75+
4. EVENT NAMES: For every event constant or observable referenced, verify it exists in source with the exact name. For MobX: verify @observable/@computed/@action decorators. For React: verify prop callback names. Check if changed source files added new events not yet documented.
76+
77+
5. ARCHITECTURE PATTERNS: Verify claims about MobX store patterns, React component patterns, singleton vs factory, component hierarchy, store injection.
78+
79+
6. LINK VALIDATION: For every relative link [text](path), verify the target exists on disk.
80+
81+
7. CODE EXAMPLES: For every code block, verify API names, method names, parameter names, import paths, MobX patterns are correct.
82+
83+
For each finding, report:
84+
- File: (path)
85+
- Line/Section: (approximate line or section heading)
86+
- Category: (1-7)
87+
- Severity: Blocking / Important / Medium / Minor
88+
- Blocking = wrong API that would cause runtime errors if an AI agent follows the docs
89+
- Important = wrong params/types that would cause compilation errors
90+
- Medium = incomplete or stale info (e.g., new methods/types/events missing from docs)
91+
- Minor = broken links, cosmetic issues
92+
- What doc says: (quoted)
93+
- What code actually has: (evidence with file:line)
94+
- Suggested fix: (exact replacement text)
95+
```
96+
97+
Run all agents in parallel if multiple ai-docs folders are affected.
98+
99+
## Step 4: Consolidate and Report
100+
101+
Present findings in this format:
102+
103+
```markdown
104+
## Spec Drift Report — Changed Files
105+
Generated: {date}
106+
Trigger: {source code changes / ai-docs changes / both}
107+
ai-docs folders checked: {list}
108+
109+
### Changed Source Files
110+
{list of changed source files and their mapped ai-docs folder}
111+
112+
### Changed ai-docs Files
113+
{list of changed ai-docs files, or "None"}
114+
115+
### Summary
116+
117+
| ai-docs Folder | Findings | Blocking | Important | Medium | Minor |
118+
|----------------|----------|----------|-----------|--------|-------|
119+
| ... | | | | | |
120+
121+
### Blocking Findings
122+
...
123+
124+
### Important Findings
125+
...
126+
127+
### Medium Findings
128+
...
129+
130+
### Minor Findings
131+
...
132+
133+
### Actionable Fixes by File
134+
(grouped by file path, each with exact old text -> new text)
135+
```
136+
137+
## Step 5: Create Verification Marker
138+
139+
After presenting the validation report (regardless of findings), create a verification marker so the pre-commit hook allows the commit:
140+
141+
```bash
142+
# Hash staged content (not just paths) — must match the hook's hash logic exactly
143+
CC_PKG="packages/contact-center"
144+
STAGED_CC=$(git diff --cached --name-only 2>/dev/null | grep "^${CC_PKG}/")
145+
if [ -n "$STAGED_CC" ]; then
146+
HASH=$(git diff --cached -- "$CC_PKG" | (shasum 2>/dev/null || sha256sum) | cut -d' ' -f1)
147+
touch "/tmp/.spec-drift-verified-${HASH}"
148+
echo "Verification marker created: /tmp/.spec-drift-verified-${HASH}"
149+
fi
150+
```
151+
152+
> **Note:** The verification marker covers only currently **staged** content. If you modify and re-stage files after verification, the content hash changes and you will need to re-run `/spec-drift-changed`.
153+
154+
Report to the user: "Verification marker created. The pre-commit hook will allow the next commit for these staged files."
155+
156+
## Rules
157+
158+
- Do NOT auto-fix anything — report findings only
159+
- Always read actual source code to verify — never assume
160+
- Use the Agent tool with `subagent_type: "Explore"` for checker agents
161+
- Run agents in parallel when multiple folders are affected
162+
- If an agent does not return within a reasonable time, note it as "Timed out — manual review needed" in the report and continue with available results
163+
- Always create the verification marker at the end, even if there are findings — this tool is **advisory**: the developer decides whether to fix or commit as-is
164+
- The marker hash MUST match the hook's hash computation — both use `git diff --cached` content (not just file paths)

‎.claude/commands/spec-drift.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Spec Drift Detection — Full Scan
2+
3+
Run a comprehensive validation of all SDD ai-docs against actual source code. Deploys a parallel agent team to catch documentation drift across 7 categories.
4+
5+
## Step 1: Auto-Discovery
6+
7+
Detect repo type and discover all ai-docs:
8+
9+
1. **Repo detection**: This is ccWidgets — `packages/contact-center/` exists (no `@webex` scope)
10+
2. **Root AGENTS.md**: `AGENTS.md` (repo root)
11+
3. **Framework docs**: `ai-docs/` (README, RULES, patterns/*, templates/*)
12+
4. **Package-level ai-docs**: Glob for `packages/contact-center/**/ai-docs/` to find all ai-docs folders
13+
5. **Samples ai-docs**: Check `widgets-samples/**/ai-docs/` as well
14+
15+
For each ai-docs folder found, identify its corresponding source code directory (the parent directory of `ai-docs/`).
16+
17+
Build an inventory (example — actual results will vary based on current branch):
18+
```
19+
ai-docs folder → source directory
20+
packages/contact-center/store/ai-docs/ → packages/contact-center/store/src/
21+
packages/contact-center/cc-components/ai-docs/ → packages/contact-center/cc-components/src/
22+
packages/contact-center/cc-widgets/ai-docs/ → packages/contact-center/cc-widgets/src/
23+
packages/contact-center/station-login/ai-docs/ → packages/contact-center/station-login/src/
24+
packages/contact-center/task/ai-docs/widgets/CallControl/ → packages/contact-center/task/src/widgets/CallControl/
25+
packages/contact-center/task/ai-docs/widgets/IncomingTask/ → packages/contact-center/task/src/widgets/IncomingTask/
26+
packages/contact-center/task/ai-docs/widgets/OutdialCall/ → packages/contact-center/task/src/widgets/OutdialCall/
27+
packages/contact-center/task/ai-docs/widgets/TaskList/ → packages/contact-center/task/src/widgets/TaskList/
28+
packages/contact-center/user-state/ai-docs/ → packages/contact-center/user-state/src/
29+
packages/contact-center/ui-logging/ai-docs/ → packages/contact-center/ui-logging/src/
30+
packages/contact-center/test-fixtures/ai-docs/ → packages/contact-center/test-fixtures/src/
31+
widgets-samples/cc/samples-cc-react-app/ai-docs/ → widgets-samples/cc/samples-cc-react-app/src/
32+
... (discover all that exist on the current branch)
33+
```
34+
35+
## Step 2: Spawn Checker Agents in Parallel
36+
37+
Use the Agent tool to spawn agents. **All agents run in parallel.**
38+
39+
### Per-Package Checker Agents (one per ai-docs folder)
40+
41+
For EACH ai-docs folder discovered, spawn one Explore agent with this prompt:
42+
43+
```
44+
You are validating SDD documentation accuracy.
45+
46+
SOURCE OF TRUTH (actual code): {source_code_directory}
47+
DOCS TO VALIDATE: {ai_docs_folder}
48+
49+
Read every markdown file in the ai-docs folder. For each document, check these 7 categories:
50+
51+
### Category 1: FILE TREE
52+
Read any documented file/directory trees in the docs. Glob the actual directory. Report:
53+
- Files listed in docs but missing on disk
54+
- Files on disk but missing from docs
55+
- Wrong nesting or directory structure
56+
57+
### Category 2: METHOD/API SIGNATURES
58+
For every method, function, or API endpoint documented:
59+
- Read the actual source file
60+
- Verify: method name, parameter names, parameter types, return type, access modifiers (public/private/static)
61+
- Check if method actually exists in the documented file
62+
- Flag any param that is documented but doesn't exist, or exists but isn't documented
63+
64+
### Category 3: TYPE DEFINITIONS
65+
For every type, enum, interface, or constant documented:
66+
- Find the actual definition in source (check package-level types files and shared types)
67+
- Compare: name, fields/members, field types, enum values
68+
- Flag missing fields, wrong types, renamed types
69+
70+
### Category 4: EVENT NAMES
71+
For every event constant or observable referenced:
72+
- Find the actual definition in source
73+
- Verify the exact name matches
74+
- For MobX observables: verify @observable, @computed, @action decorators match docs
75+
- For React events: verify prop callback names match
76+
77+
### Category 5: ARCHITECTURE PATTERNS
78+
For claims about architectural patterns, verify:
79+
- MobX store patterns: Are @observable, @action, @computed correctly documented?
80+
- React component patterns: Are props, state, lifecycle methods correct?
81+
- Singleton vs factory: Is the instantiation pattern correct?
82+
- Component hierarchy: Are parent-child relationships correct?
83+
- Store injection patterns: Are MobX store injections accurately described?
84+
85+
### Category 6: LINK VALIDATION
86+
For every relative markdown link [text](path):
87+
- Resolve the path relative to the document's location
88+
- Verify the target file exists on disk
89+
- For anchor links (#section), verify the heading exists in the target
90+
91+
### Category 7: CODE EXAMPLES
92+
For every inline code block or code snippet:
93+
- Verify API names, method names, parameter names are correct
94+
- Verify import paths are valid
95+
- Check that documented usage patterns match actual API signatures
96+
- Verify MobX patterns use correct decorators and patterns
97+
98+
## Output Format
99+
100+
For each finding, report:
101+
- **File**: (path to the ai-docs file with the issue)
102+
- **Line/Section**: (approximate line number or section heading)
103+
- **Category**: (1-7 from above)
104+
- **Severity**:
105+
- Blocking = wrong API that would cause runtime errors if AI agent follows the docs
106+
- Important = wrong params/types that would cause compilation errors
107+
- Medium = incomplete or stale info that would cause confusion
108+
- Minor = broken links, cosmetic issues
109+
- **What doc says**: (quoted text from the doc)
110+
- **What code actually has**: (evidence from source, with file path and line)
111+
- **Suggested fix**: (exact replacement text)
112+
113+
If no issues found in a category, state "No issues found" for that category.
114+
```
115+
116+
### Framework Agent
117+
118+
Spawn one additional Explore agent for root-level framework validation:
119+
120+
```
121+
Validate the root-level SDD framework documents for ccWidgets:
122+
123+
1. **Root AGENTS.md** (repo root AGENTS.md):
124+
- Package Routing Table: Every package listed must exist on disk at the documented path
125+
- Every actual package directory under packages/contact-center/ should be listed
126+
- Task classification types must be consistent with template directories that exist
127+
- Quick Start Workflow steps must reference files that exist
128+
129+
2. **ai-docs/RULES.md**:
130+
- Test commands: Verify documented commands are correct
131+
- Naming conventions: Verify claims against actual code
132+
- Pattern references: All referenced patterns should exist
133+
134+
3. **ai-docs/README.md**:
135+
- File tree must match actual ai-docs directory structure
136+
- All referenced documents must exist
137+
138+
4. **ai-docs/patterns/*.md** (mobx-patterns, react-patterns, testing-patterns, typescript-patterns):
139+
- Each pattern file's code examples must match actual source conventions
140+
- MobX patterns must match actual decorator usage in stores
141+
- React patterns must match actual component patterns
142+
- Test patterns must reference correct commands and configs
143+
144+
5. **ai-docs/templates/**:
145+
- Cross-references to AGENTS.md sections must be valid
146+
- Referenced file paths in templates must exist
147+
- Workflow steps must be internally consistent
148+
149+
For each finding, report:
150+
- **File**: (path)
151+
- **Line/Section**: (section heading or line)
152+
- **Category**: (1-7: File Tree, Method/API, Type Definition, Event Name, Architecture Pattern, Link Validation, Code Example)
153+
- **Severity**: Blocking / Important / Medium / Minor
154+
- **What doc says**: (quoted)
155+
- **What code actually has**: (evidence with file:line)
156+
- **Suggested fix**: (replacement text)
157+
```
158+
159+
## Step 3: Consolidate Results
160+
161+
After ALL agents complete, consolidate into this report format:
162+
163+
```markdown
164+
## Spec Drift Report — ccWidgets
165+
Generated: {date}
166+
Scanned: {N} ai-docs folders, {M} documents
167+
168+
### Summary
169+
170+
| ai-docs Folder | Findings | Blocking | Important | Medium | Minor |
171+
|----------------|----------|----------|-----------|--------|-------|
172+
| (each folder) | | | | | |
173+
| framework | | | | | |
174+
| **Total** | **N** | | | | |
175+
176+
### Blocking Findings
177+
(must fix — wrong APIs that would cause runtime errors if AI agent follows the docs)
178+
179+
### Important Findings
180+
(wrong params, signatures, types — would cause compilation errors)
181+
182+
### Medium Findings
183+
(incomplete info, stale file trees — would cause confusion)
184+
185+
### Minor Findings
186+
(broken links, cosmetic issues)
187+
188+
### Actionable Fixes by File
189+
(grouped by file path, each with exact old text -> new text)
190+
```
191+
192+
## Rules
193+
194+
- Do NOT auto-fix anything — report findings only
195+
- Always read actual source code to verify — never assume
196+
- Use the Agent tool with `subagent_type: "Explore"` for all checker agents
197+
- Run all agents in parallel for speed
198+
- If an agent does not return within a reasonable time, note it as "Timed out — manual review needed" in the report and continue with available results
199+
- If an ai-docs folder has no corresponding source directory, flag it as a Category 1 (File Tree) finding
200+
- Count findings by severity in the summary table

0 commit comments

Comments
 (0)