---
name: spec-driven-w3-compliance
description: >
  W3 compliance scanning with structural anti-skip enforcement. Detects auto-skill
  chaining violations (skills/commands that auto-invoke other skills without user approval)
  using the Execute-Verify-Record pattern at every step. Designed to prevent token
  optimization bias through lean orchestration and binary CLI gate enforcement. Scans
  subagent files, skill files, and command files for unauthorized Skill() invocations.
  Use when auditing W3 compliance, checking for auto-skill chaining violations, or
  preparing for release validation. Always use this skill when the user runs /audit-w3
  or mentions W3 compliance, skill chaining, or auto-invocation scanning.
allowed-tools:
  - Read
  - Glob
  - Grep
  - AskUserQuestion
  - Bash(devforgeai-validate:*)
model: opus
effort: High
---

# Spec-Driven W3 Compliance

Scan for W3 violations (auto-skill chaining without user control) through strict 4-phase workflow with structural anti-skip enforcement.

**W3 Definition:** Skills/commands that auto-invoke other skills without user approval, causing token overflow and violating lean orchestration principles.

**Reference:** BRAINSTORM-001 (line 85), STORY-135, ADR-020

**If ambiguous or conflicts detected: HALT and use AskUserQuestion**

---

## Execution Model

See **`.claude/rules/core/anti-skip-behavior.md`** for the canonical execution contract (expand inline; do not wait passively or offer execution options; honor every step of every phase; Self-Check violation taxonomy; Token-Optimization-Bias prohibition; governed by ADR-076). After invocation, execute Phase State Initialization immediately.

---

## Anti-Skip Enforcement Contract

Enforced structurally outside LLM control, not by this prose — by the framework's deterministic gates wired for this workflow: the `devforgeai-validate` phase gates, the `settings.json`-registered `.claude/hooks/` scripts, and `.claude/hooks/phase-steps-registry.json` (ADR-076). Behavioral residue: `.claude/rules/core/anti-skip-behavior.md`.

---

## Parameter Extraction

Extract scan parameters from command context markers set by `/audit-w3`:

| Context Marker | Set By | Default | Description |
|----------------|--------|---------|-------------|
| `$MODE` | /audit-w3 | `"normal"` | Scan mode (normal/verbose) |
| `$QUIET` | /audit-w3 | `false` | Suppress detailed output |
| `$FIX_HINTS` | /audit-w3 | `false` | Show remediation patterns |

If context markers are not found, use defaults.

---

## Phase State Initialization [MANDATORY FIRST]

Generate `$SESSION_ID` from the current timestamp: `W3-{YYYYMMDD}-{HHMMSS}` (e.g., `W3-20260601-143000`). Set it ONCE here and reuse the same `${SESSION_ID}` for every gate call in every phase. Each `/audit-w3` run gets a fresh id, so concurrent or repeat runs never collide on one state file.

```bash
devforgeai-validate phase-init ${SESSION_ID} --workflow=w3-compliance --project-root=.
```

| Exit Code | Meaning | Action |
|-----------|---------|--------|
| 0 | New workflow | State file created. Set CURRENT_PHASE = "01". (Expected: a fresh timestamp id is new each run.) |
| 1 | Existing workflow (same-second id reuse) | Resume from last completed phase. |
| 2 | Invalid ID | HALT. Must match `W3-YYYYMMDD-HHMMSS`. |
| 127 | CLI not installed | Continue without enforcement (backward compatibility). |

---

## Phase Orchestration Loop

```
FOR phase_num in [01, 02, 03, 04]:
    phase_id = phase_num

    1. ENTRY GATE: devforgeai-validate phase-check ${SESSION_ID} --workflow=w3-compliance --from={prev} --to={phase_id} --project-root=.
       IF exit != 0: HALT

    2. LOAD: Read(file_path=".claude/skills/spec-driven-w3-compliance/phases/{phase_files[phase_id]}")

    3. EXECUTE: Follow every step in the phase file (EXECUTE-VERIFY-RECORD triplets)
       - Each step's EXECUTE instruction tells you exactly what to do
       - Each step's VERIFY instruction tells you how to confirm it happened
       - Each step's RECORD instruction tells you what CLI command to call

    4. RECORD: devforgeai-validate phase-record ${SESSION_ID} --workflow=w3-compliance --phase={phase_id} --project-root=.

    5. EXIT GATE: devforgeai-validate phase-complete ${SESSION_ID} --workflow=w3-compliance --phase={phase_id} --checkpoint-passed --project-root=.
       IF exit != 0: HALT
```

| Phase | Name | File |
|-------|------|------|
| 01 | Setup | `phases/phase-01-setup.md` |
| 02 | Scanning | `phases/phase-02-scanning.md` |
| 03 | Reporting | `phases/phase-03-reporting.md` |
| 04 | Completion | `phases/phase-04-completion.md` |

---

## Required Subagents Per Phase

| Phase | Required Subagents | Enforcement |
|-------|-------------------|-------------|
| 01 | (none) | N/A |
| 02 | (none) | N/A |
| 03 | (none) | N/A |
| 04 | (none) | N/A |

This skill is read-only scanning. No subagents are required.

**Deviation Protocol:** Any skip requires explicit user consent via AskUserQuestion.

---

## Workflow Completion Validation

```
IF completed_count < 4: HALT "WORKFLOW INCOMPLETE - {completed_count}/4 phases"
IF completed_count == 4: "All 4 phases completed - W3 compliance audit passed"
```

---

## Success Criteria

- Detects subagent Skill() invocations (CRITICAL)
- Detects non-orchestration skill auto-chaining (HIGH)
- Flags missing W3 compliance documentation (MEDIUM)
- Identifies auto-invoke language patterns (INFO)
- Excludes legitimate orchestration and backup files
- CRITICAL violations return exit code 1
- Quiet mode works for release integration
- Report format matches other audit commands

---

## Reference Files Index

**Local references** (loaded per-phase on demand, NOT consolidated):

| Phase | Reference Files (load via Read from src/claude/skills/spec-driven-w3-compliance/references/) |
|-------|-------------------------------------------------------------------------------------------|
| 01 | (none -- setup uses inline logic) |
| 02 | `scanning-patterns.md`, `w3-rules.md` |
| 03 | `report-templates.md`, `w3-rules.md` |
| 04 | (none -- completion uses inline logic) |

---

## Integration Notes

**Invoked by:** /audit-w3 command
**Invokes:** None (read-only scanning)
**Output:** Display report to user, exit code for CI/CD
**W3 Compliance:** This skill does NOT auto-invoke other skills.
