[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M754EYD03HGG6D7YSXC8XDNN":3,"skill-same:01M754EYD03HGG6D7YSXC8XDNN":54},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":32,"commitSha":33,"skillDirectory":34,"forksCount":35,"repositoryHtmlUrl":36,"repositoryHomepageUrl":6,"ownerHtmlUrl":37,"ownerBlogUrl":38,"ownerDescription":39,"updatedAt":40,"install":41,"resources":53},"01M754EYD03HGG6D7YSXC8XDNN","x-validate-docs",null,"Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared\u002Fauto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.","review-bench\u002Federcnj_ia-dev-environment","review-bench","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F286778065?v=4","01M7517F9NTEPDZDAXJBR30FWT","ReviewBench","01M7517FAC9F4P7TGWCNJ8VYVW",0,"MIT","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring-event-driven\u002F.claude\u002Fskills\u002Fx-validate-docs\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: x-validate-docs\ndescription: \"Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared\u002Fauto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.\"\nvisibility: public\nuser-invocable: true\nmodel: sonnet\nallowed-tools: Read, Bash, Grep, Glob\nargument-hint: \"[--story-id STORY-ID] [--pr-number N] [--scope path] [--report-path path]\"\ncontext-budget: medium\nrequires-capabilities: [governance.doc-as-dod]\n---\n\n## Global Output Policy\n\n- **Language**: English ONLY.\n- **Tone**: Technical, Direct, and Concise.\n- **Efficiency**: Remove all conversational fillers and greetings to save tokens.\n\n# Skill: Documentation Freshness Validator\n\n> 🔒 Read-only skill — does NOT modify any files. Produces a structured report and exits with a status code.\n\n## Purpose\n\nValidates that documentation has been updated in sync with code changes introduced by a PR or branch. Consumes `documentation.targets` from `ProjectConfig` (introduced in story-0071-0001) to determine which dimensions to validate — only targets declared or auto-detected for the project stack are checked.\n\nProduces a report at the path specified by `--report-path` (default: stdout). Exits `0` on pass; exits `1` (`DOC_VALIDATION_FAILED`) on any failed dimension.\n\n## Triggers\n\n- `\u002Fx-validate-docs` — validate all active dimensions from `documentation.targets`\n- `\u002Fx-validate-docs --story-id story-XXXX-YYYY` — validate for a specific story's PR\n- `\u002Fx-validate-docs --pr-number 123` — validate against PR #123 diff\n- `\u002Fx-validate-docs --scope src\u002Fmain\u002Fjava\u002F` — limit code change analysis to path\n- `\u002Fx-validate-docs --report-path ai\u002Fepics\u002Fepic-XXXX\u002Freports\u002Fdoc-validate-STORY-ID.md` — persist report\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `--story-id` | String | No | Story ID (e.g., `story-0071-0002`). Used to derive report path if `--report-path` omitted. |\n| `--pr-number` | Integer | No | PR number. Limits diff to merged PR if specified. |\n| `--scope` | String | No | Path prefix to limit change detection (e.g., `src\u002Fmain\u002Fjava\u002F`). |\n| `--report-path` | String | No | Output path for report. Default: print to stdout. |\n| `--freshness-window-hours` | Integer | No | Override freshness window from ProjectConfig (0 = immediate, default). |\n\n## Exit Codes\n\n| Exit | Code | Condition |\n|------|------|-----------|\n| 0 | `OK` | All active dimensions passed or skipped. |\n| 1 | `DOC_VALIDATION_FAILED` | At least one dimension detected staleness. |\n| 2 | `OPERATIONAL_ERROR` | Missing dependency, invalid args, or I\u002FO error. |\n\n## Validation Workflow\n\n```\n1. PARSE       -> Parse args, load ProjectConfig documentation.targets\n2. DETECT      -> Identify changed files (git diff for PR or HEAD)\n3. CLASSIFY    -> Map changed files to documentation dimensions\n4. VALIDATE    -> Run each active dimension validator\n5. WINDOW      -> Apply freshness-window-hours grace period\n6. REPORT      -> Emit structured report, exit with status\n```\n\n### Step 1 — Parse Arguments and Load Targets\n\nParse invocation arguments. Load `documentation.targets` from project YAML:\n\n```bash\n# Read documentation block from project YAML (iadev.yaml or profile.yaml)\ncat iadev.yaml 2>\u002Fdev\u002Fnull | grep -A 20 \"^documentation:\" | head -20\n```\n\nIf `documentation.targets` is empty (auto-detect mode), apply stack-aware defaults:\n\n| Condition | Auto-detected targets |\n|-----------|----------------------|\n| `interfaces[].spec=openapi` present in YAML | `readme`, `openapi`, `adr`, `skill-docs` |\n| `interfaces[].broker` present (event-driven) | `readme`, `asyncapi`, `adr`, `skill-docs` |\n| `interfaces[].spec=proto3` present | `readme`, `grpc-proto`, `adr`, `skill-docs` |\n| CLI-only project (no interfaces) | `readme`, `adr`, `skill-docs` |\n| `docs\u002Farchitecture\u002Fsystem.md` exists | add `system-architecture` to all above |\n\nReject path traversal in targets: any target containing `..` or starting with `\u002F` or not matching `[a-z0-9\u002F_-]+` is rejected with `OPERATIONAL_ERROR`.\n\n### Step 2 — Detect Changed Files\n\n```bash\n# PR diff (when --pr-number given)\ngh pr diff {pr_number} --name-only 2>\u002Fdev\u002Fnull\n\n# Branch diff against base (fallback)\ngit diff --name-only origin\u002Fdevelop..HEAD 2>\u002Fdev\u002Fnull || git diff --name-only HEAD~1..HEAD\n```\n\nIf `--scope` is specified, filter the changed file list to paths under that prefix.\n\n**Security:** Never follow symlinks. Normalize all paths with `realpath --relative-to=.` before processing.\n\n### Step 3 — Classify Changes\n\nMap changed files to documentation dimensions:\n\n| Changed file pattern | Triggers dimension |\n|---------------------|-------------------|\n| `src\u002F**\u002F` Java\u002FTS\u002FPY\u002FGo files | `readme`, `api-specs` (if REST controller detected), `skill-docs` |\n| `*.java` matching `*Controller*\\|*Resource*\\|*Handler*\\|*Endpoint*` | `api-specs` (openapi or asyncapi) |\n| `**\u002F*.proto` | `grpc-proto` |\n| `docs\u002Fadr\u002F**`, story markdown with `ADR Reference:` | `adr` |\n| `.claude\u002Fskills\u002F**` | `skill-docs` |\n| `src\u002F**\u002F` new subdir in `application\u002F\\|domain\u002F\\|adapter\u002F` | `system-architecture` |\n| Only `docs\u002F**` or `*.md` changed (no code) | mark all non-touched dimensions as `skipped (no code change)` |\n\nIf all changed files are documentation-only (no code), set overall result to `PASS` (degenerate case — PR is a docs-only PR).\n\n### Step 4 — Validate Each Active Dimension\n\nRun each dimension that is (a) in `documentation.targets` (or auto-detected) AND (b) triggered by the changed files.\n\n#### Dimension: `readme`\n\n```bash\n# Check if README.md was touched in the diff\ngit diff --name-only {range} | grep -i \"^README\"\n```\n\n- **PASS**: README.md exists in diff AND contains at least one of the new symbols\u002Ffeatures detected in code changes.\n- **FAIL**: Code changes added a new class\u002Fskill\u002Fconfig but README.md was NOT touched.\n- **SKIP**: Code changes did not affect user-facing features (only internal refactors, test changes).\n\nHeuristic for \"user-facing feature\": new public class in `adapter\u002Finbound\u002F`, new `SKILL.md`, or new config key in YAML.\n\n#### Dimension: `api-specs` (OpenAPI \u002F AsyncAPI)\n\n**OpenAPI sub-dimension** (active when `interfaces[].spec=openapi`):\n\n```bash\n# Detect new endpoints in diff\ngit diff {range} -- src\u002F | grep -E \"^\\+.*(@GetMapping|@PostMapping|@PutMapping|@DeleteMapping|@RequestMapping|app\\.(get|post|put|delete))\"\n```\n\nFor each new endpoint detected, verify it appears in `openapi.yaml` \u002F `openapi.json` \u002F `docs\u002Fapi\u002F*.yaml` (by path+method):\n\n```bash\n# Check OpenAPI spec contains the endpoint path\ngrep -r \"{endpoint_path}\" openapi.yaml docs\u002Fapi\u002F 2>\u002Fdev\u002Fnull\n```\n\n- **PASS**: All new endpoints appear in OpenAPI spec.\n- **FAIL**: At least one new endpoint is not documented in OpenAPI spec.\n- **SKIP**: No new endpoints detected in diff.\n\n**AsyncAPI sub-dimension** (active when `interfaces[].broker` present):\n\n```bash\n# Detect new event publishers\u002Fconsumers in diff\ngit diff {range} -- src\u002F | grep -E \"^\\+.*(publish|emit|subscribe|consume|@KafkaListener|@RabbitListener)\"\n```\n\nVerify new event types appear in `asyncapi.yaml` \u002F `docs\u002Fevents\u002F*.yaml`.\n\n#### Dimension: `grpc-proto`\n\nActive when `interfaces[].spec=proto3` in project YAML.\n\n```bash\n# Check if proto files were modified when gRPC service classes changed\ngit diff --name-only {range} | grep \"\\.proto$\"\ngit diff {range} -- src\u002F | grep -E \"^\\+.*(extends.*Grpc|@GrpcService|rpc [A-Z])\"\n```\n\n- **PASS**: New gRPC service methods detected AND corresponding `.proto` file touched.\n- **FAIL**: New gRPC service methods detected but NO `.proto` file in diff.\n- **SKIP**: No gRPC service changes detected.\n\n#### Dimension: `adr`\n\nAlways active.\n\n```bash\n# Check if story file references an ADR and whether that ADR exists\nfind docs\u002Fadr\u002F -name \"ADR-*.md\" | wc -l\n```\n\nFor each story touched in the PR (via `ai\u002Fepics\u002F*\u002Fstory-*.md`), verify:\n- If story contains `ADR Reference: ADR-XXXX`, that ADR file exists in `docs\u002Fadr\u002F`.\n- If architectural decision was made (arch plan present), an ADR covers it.\n\n- **PASS**: All ADR references resolve to existing files.\n- **FAIL**: ADR reference resolves to non-existent file.\n- **SKIP**: No stories or arch plans touched in diff.\n\n#### Dimension: `skill-docs`\n\nAlways active when `.claude\u002Fskills\u002F` exists.\n\n```bash\n# Check new SKILL.md files have required frontmatter\nfind .claude\u002Fskills\u002F -name \"SKILL.md\" -newer HEAD~1 2>\u002Fdev\u002Fnull\ngit diff --name-only {range} | grep \"SKILL\\.md\"\n```\n\nFor each new or modified `SKILL.md`, validate:\n- Frontmatter contains: `name`, `description`, `visibility`, `user-invocable`, `requires-capabilities`.\n- Body contains `## Triggers` section.\n- Body contains at least one usage example.\n\n- **PASS**: All SKILL.md files in diff have valid frontmatter + Triggers section.\n- **FAIL**: Missing required frontmatter field or missing Triggers section.\n- **SKIP**: No SKILL.md files in diff.\n\n#### Dimension: `system-architecture`\n\nActive when `docs\u002Farchitecture\u002Fsystem.md` exists.\n\n```bash\n# Check for new architectural components in diff\ngit diff {range} -- src\u002F | grep -E \"^\\+.*class [A-Z]\" | head -20\nfind src\u002F -newer docs\u002Farchitecture\u002Fsystem.md -name \"*.java\" 2>\u002Fdev\u002Fnull | grep -E \"(application|domain|adapter)\" | head -10\n```\n\nDetect new subdirectories in architectural layers:\n```bash\ngit diff {range} --name-only | grep -E \"^src\u002F.*(application\u002F|domain\u002F|adapter\u002Finbound\u002F|adapter\u002Foutbound\u002F)\" | awk -F'\u002F' '{print $1\"\u002F\"$2\"\u002F\"$3\"\u002F\"$4}' | sort -u\n```\n\n- **PASS**: `docs\u002Farchitecture\u002Fsystem.md` was touched in diff OR no new architectural component was added.\n- **FAIL**: New component detected (new subdir in application\u002Fdomain\u002Fadapter\u002F with ≥1 Java\u002FTS\u002FPY\u002FGo file) but `system.md` was NOT touched.\n- **SKIP**: No architectural changes detected.\n\nWhen fail detected, optionally invoke `x-update-system-architecture --validate-only` (if EPIC-0070 available):\n```\nSkill(skill: \"x-update-system-architecture\", model: \"sonnet\", args: \"--validate-only\")\n```\n[optional]\n\nIf `x-update-system-architecture` is unavailable: log `WARN: x-update-system-architecture unavailable — system-architecture dimension evaluated heuristically`.\n\n### Step 5 — Apply Freshness Window\n\nIf `freshness-window-hours > 0` (from ProjectConfig or `--freshness-window-hours` flag):\n\n```bash\n# Check when code was last committed\ngit log -1 --format=\"%ci\" -- {changed_code_files}\n```\n\nIf the code was committed within the freshness window AND doc was NOT updated:\n- Downgrade FAIL → WARNING: `\"freshness window open — update documentation before merge\"`\n- Exit 0 with warnings surfaced in report.\n\nIf freshness window has expired AND doc was NOT updated:\n- Restore FAIL status → exit 1.\n\n### Step 6 — Emit Report\n\nWrite the structured report using `_TEMPLATE-DOC-VALIDATE-REPORT.md`. If `--report-path` is given, write to that path. Otherwise print to stdout.\n\n```\nDocumentation Validation Report\n  Story: {story-id or N\u002FA}\n  PR:    #{pr-number or N\u002FA}\n  Date:  {ISO-8601}\n\n  Overall: PASS | FAIL | WARNING\n\n  Dimensions:\n    readme              : OK | FAILED | SKIPPED | WARNING\n    api-specs           : OK | FAILED | SKIPPED | N\u002FA (not in stack)\n    grpc-proto          : OK | FAILED | SKIPPED | N\u002FA (not in stack)\n    adr                 : OK | FAILED | SKIPPED\n    skill-docs          : OK | FAILED | SKIPPED\n    system-architecture : OK | FAILED | SKIPPED | N\u002FA (system.md absent)\n\n  Failures:\n    - {dimension}: {reason} (file: {relative-path})\n\n  Warnings:\n    - {dimension}: {message}\n\n  Duration: {seconds}s\n```\n\n**Security:** Never include absolute filesystem paths in report output. Use paths relative to repository root. Never emit environment variables, tokens, or CI runner metadata.\n\n## Error Handling\n\n| Scenario | Action |\n|----------|--------|\n| No git repository | Exit 2 `OPERATIONAL_ERROR: not a git repository` |\n| `--pr-number` but `gh` not on PATH | Fall back to `git diff HEAD~1..HEAD` with WARN |\n| Project YAML not found | Use auto-detect mode for all targets with WARN |\n| Target dimension validator throws error | Mark dimension `ERROR`, continue others, exit 1 |\n| `documentation.targets` contains path traversal | Exit 2 `PATH_TRAVERSAL_REJECTED: {target}` |\n| Symlink encountered in file scan | Skip symlink, log WARN, never follow |\n\n## Performance Contract\n\n- Total validation time: \u003C 30s for repositories with up to 500 changed files and 6 active dimensions.\n- No network calls during validation (all checks are local git + filesystem).\n- Each dimension validator runs independently; no shared mutable state.\n\n## Integration Notes\n\n| Skill | Relationship | Context |\n|-------|-------------|---------|\n| `x-implement-story` | called-by | Phase 3 — mandatory gate (story-0071-0006 wires this) |\n| `x-generate-docs` | precedes (in Phase 3) | generate runs first, validate confirms |\n| `x-update-system-architecture` | optional-delegates-to | system-architecture dimension, EPIC-0070 |\n| `audit-doc-freshness.sh` | CI counterpart | story-0071-0005 wires CI version of same checks |\n","## Global Output Policy\n\n- **Language**: English ONLY.\n- **Tone**: Technical, Direct, and Concise.\n- **Efficiency**: Remove all conversational fillers and greetings to save tokens.\n\n# Skill: Documentation Freshness Validator\n\n> 🔒 Read-only skill — does NOT modify any files. Produces a structured report and exits with a status code.\n\n## Purpose\n\nValidates that documentation has been updated in sync with code changes introduced by a PR or branch. Consumes `documentation.targets` from `ProjectConfig` (introduced in story-0071-0001) to determine which dimensions to validate — only targets declared or auto-detected for the project stack are checked.\n\nProduces a report at the path specified by `--report-path` (default: stdout). Exits `0` on pass; exits `1` (`DOC_VALIDATION_FAILED`) on any failed dimension.\n\n## Triggers\n\n- `\u002Fx-validate-docs` — validate all active dimensions from `documentation.targets`\n- `\u002Fx-validate-docs --story-id story-XXXX-YYYY` — validate for a specific story's PR\n- `\u002Fx-validate-docs --pr-number 123` — validate against PR #123 diff\n- `\u002Fx-validate-docs --scope src\u002Fmain\u002Fjava\u002F` — limit code change analysis to path\n- `\u002Fx-validate-docs --report-path ai\u002Fepics\u002Fepic-XXXX\u002Freports\u002Fdoc-validate-STORY-ID.md` — persist report\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `--story-id` | String | No | Story ID (e.g., `story-0071-0002`). Used to derive report path if `--report-path` omitted. |\n| `--pr-number` | Integer | No | PR number. Limits diff to merged PR if specified. |\n| `--scope` | String | No | Path prefix to limit change detection (e.g., `src\u002Fmain\u002Fjava\u002F`). |\n| `--report-path` | String | No | Output path for report. Default: print to stdout. |\n| `--freshness-window-hours` | Integer | No | Override freshness window from ProjectConfig (0 = immediate, default). |\n\n## Exit Codes\n\n| Exit | Code | Condition |\n|------|------|-----------|\n| 0 | `OK` | All active dimensions passed or skipped. |\n| 1 | `DOC_VALIDATION_FAILED` | At least one dimension detected staleness. |\n| 2 | `OPERATIONAL_ERROR` | Missing dependency, invalid args, or I\u002FO error. |\n\n## Validation Workflow\n\n```\n1. PARSE       -> Parse args, load ProjectConfig documentation.targets\n2. DETECT      -> Identify changed files (git diff for PR or HEAD)\n3. CLASSIFY    -> Map changed files to documentation dimensions\n4. VALIDATE    -> Run each active dimension validator\n5. WINDOW      -> Apply freshness-window-hours grace period\n6. REPORT      -> Emit structured report, exit with status\n```\n\n### Step 1 — Parse Arguments and Load Targets\n\nParse invocation arguments. Load `documentation.targets` from project YAML:\n\n```bash\n# Read documentation block from project YAML (iadev.yaml or profile.yaml)\ncat iadev.yaml 2>\u002Fdev\u002Fnull | grep -A 20 \"^documentation:\" | head -20\n```\n\nIf `documentation.targets` is empty (auto-detect mode), apply stack-aware defaults:\n\n| Condition | Auto-detected targets |\n|-----------|----------------------|\n| `interfaces[].spec=openapi` present in YAML | `readme`, `openapi`, `adr`, `skill-docs` |\n| `interfaces[].broker` present (event-driven) | `readme`, `asyncapi`, `adr`, `skill-docs` |\n| `interfaces[].spec=proto3` present | `readme`, `grpc-proto`, `adr`, `skill-docs` |\n| CLI-only project (no interfaces) | `readme`, `adr`, `skill-docs` |\n| `docs\u002Farchitecture\u002Fsystem.md` exists | add `system-architecture` to all above |\n\nReject path traversal in targets: any target containing `..` or starting with `\u002F` or not matching `[a-z0-9\u002F_-]+` is rejected with `OPERATIONAL_ERROR`.\n\n### Step 2 — Detect Changed Files\n\n```bash\n# PR diff (when --pr-number given)\ngh pr diff {pr_number} --name-only 2>\u002Fdev\u002Fnull\n\n# Branch diff against base (fallback)\ngit diff --name-only origin\u002Fdevelop..HEAD 2>\u002Fdev\u002Fnull || git diff --name-only HEAD~1..HEAD\n```\n\nIf `--scope` is specified, filter the changed file list to paths under that prefix.\n\n**Security:** Never follow symlinks. Normalize all paths with `realpath --relative-to=.` before processing.\n\n### Step 3 — Classify Changes\n\nMap changed files to documentation dimensions:\n\n| Changed file pattern | Triggers dimension |\n|---------------------|-------------------|\n| `src\u002F**\u002F` Java\u002FTS\u002FPY\u002FGo files | `readme`, `api-specs` (if REST controller detected), `skill-docs` |\n| `*.java` matching `*Controller*\\|*Resource*\\|*Handler*\\|*Endpoint*` | `api-specs` (openapi or asyncapi) |\n| `**\u002F*.proto` | `grpc-proto` |\n| `docs\u002Fadr\u002F**`, story markdown with `ADR Reference:` | `adr` |\n| `.claude\u002Fskills\u002F**` | `skill-docs` |\n| `src\u002F**\u002F` new subdir in `application\u002F\\|domain\u002F\\|adapter\u002F` | `system-architecture` |\n| Only `docs\u002F**` or `*.md` changed (no code) | mark all non-touched dimensions as `skipped (no code change)` |\n\nIf all changed files are documentation-only (no code), set overall result to `PASS` (degenerate case — PR is a docs-only PR).\n\n### Step 4 — Validate Each Active Dimension\n\nRun each dimension that is (a) in `documentation.targets` (or auto-detected) AND (b) triggered by the changed files.\n\n#### Dimension: `readme`\n\n```bash\n# Check if README.md was touched in the diff\ngit diff --name-only {range} | grep -i \"^README\"\n```\n\n- **PASS**: README.md exists in diff AND contains at least one of the new symbols\u002Ffeatures detected in code changes.\n- **FAIL**: Code changes added a new class\u002Fskill\u002Fconfig but README.md was NOT touched.\n- **SKIP**: Code changes did not affect user-facing features (only internal refactors, test changes).\n\nHeuristic for \"user-facing feature\": new public class in `adapter\u002Finbound\u002F`, new `SKILL.md`, or new config key in YAML.\n\n#### Dimension: `api-specs` (OpenAPI \u002F AsyncAPI)\n\n**OpenAPI sub-dimension** (active when `interfaces[].spec=openapi`):\n\n```bash\n# Detect new endpoints in diff\ngit diff {range} -- src\u002F | grep -E \"^\\+.*(@GetMapping|@PostMapping|@PutMapping|@DeleteMapping|@RequestMapping|app\\.(get|post|put|delete))\"\n```\n\nFor each new endpoint detected, verify it appears in `openapi.yaml` \u002F `openapi.json` \u002F `docs\u002Fapi\u002F*.yaml` (by path+method):\n\n```bash\n# Check OpenAPI spec contains the endpoint path\ngrep -r \"{endpoint_path}\" openapi.yaml docs\u002Fapi\u002F 2>\u002Fdev\u002Fnull\n```\n\n- **PASS**: All new endpoints appear in OpenAPI spec.\n- **FAIL**: At least one new endpoint is not documented in OpenAPI spec.\n- **SKIP**: No new endpoints detected in diff.\n\n**AsyncAPI sub-dimension** (active when `interfaces[].broker` present):\n\n```bash\n# Detect new event publishers\u002Fconsumers in diff\ngit diff {range} -- src\u002F | grep -E \"^\\+.*(publish|emit|subscribe|consume|@KafkaListener|@RabbitListener)\"\n```\n\nVerify new event types appear in `asyncapi.yaml` \u002F `docs\u002Fevents\u002F*.yaml`.\n\n#### Dimension: `grpc-proto`\n\nActive when `interfaces[].spec=proto3` in project YAML.\n\n```bash\n# Check if proto files were modified when gRPC service classes changed\ngit diff --name-only {range} | grep \"\\.proto$\"\ngit diff {range} -- src\u002F | grep -E \"^\\+.*(extends.*Grpc|@GrpcService|rpc [A-Z])\"\n```\n\n- **PASS**: New gRPC service methods detected AND corresponding `.proto` file touched.\n- **FAIL**: New gRPC service methods detected but NO `.proto` file in diff.\n- **SKIP**: No gRPC service changes detected.\n\n#### Dimension: `adr`\n\nAlways active.\n\n```bash\n# Check if story file references an ADR and whether that ADR exists\nfind docs\u002Fadr\u002F -name \"ADR-*.md\" | wc -l\n```\n\nFor each story touched in the PR (via `ai\u002Fepics\u002F*\u002Fstory-*.md`), verify:\n- If story contains `ADR Reference: ADR-XXXX`, that ADR file exists in `docs\u002Fadr\u002F`.\n- If architectural decision was made (arch plan present), an ADR covers it.\n\n- **PASS**: All ADR references resolve to existing files.\n- **FAIL**: ADR reference resolves to non-existent file.\n- **SKIP**: No stories or arch plans touched in diff.\n\n#### Dimension: `skill-docs`\n\nAlways active when `.claude\u002Fskills\u002F` exists.\n\n```bash\n# Check new SKILL.md files have required frontmatter\nfind .claude\u002Fskills\u002F -name \"SKILL.md\" -newer HEAD~1 2>\u002Fdev\u002Fnull\ngit diff --name-only {range} | grep \"SKILL\\.md\"\n```\n\nFor each new or modified `SKILL.md`, validate:\n- Frontmatter contains: `name`, `description`, `visibility`, `user-invocable`, `requires-capabilities`.\n- Body contains `## Triggers` section.\n- Body contains at least one usage example.\n\n- **PASS**: All SKILL.md files in diff have valid frontmatter + Triggers section.\n- **FAIL**: Missing required frontmatter field or missing Triggers section.\n- **SKIP**: No SKILL.md files in diff.\n\n#### Dimension: `system-architecture`\n\nActive when `docs\u002Farchitecture\u002Fsystem.md` exists.\n\n```bash\n# Check for new architectural components in diff\ngit diff {range} -- src\u002F | grep -E \"^\\+.*class [A-Z]\" | head -20\nfind src\u002F -newer docs\u002Farchitecture\u002Fsystem.md -name \"*.java\" 2>\u002Fdev\u002Fnull | grep -E \"(application|domain|adapter)\" | head -10\n```\n\nDetect new subdirectories in architectural layers:\n```bash\ngit diff {range} --name-only | grep -E \"^src\u002F.*(application\u002F|domain\u002F|adapter\u002Finbound\u002F|adapter\u002Foutbound\u002F)\" | awk -F'\u002F' '{print $1\"\u002F\"$2\"\u002F\"$3\"\u002F\"$4}' | sort -u\n```\n\n- **PASS**: `docs\u002Farchitecture\u002Fsystem.md` was touched in diff OR no new architectural component was added.\n- **FAIL**: New component detected (new subdir in application\u002Fdomain\u002Fadapter\u002F with ≥1 Java\u002FTS\u002FPY\u002FGo file) but `system.md` was NOT touched.\n- **SKIP**: No architectural changes detected.\n\nWhen fail detected, optionally invoke `x-update-system-architecture --validate-only` (if EPIC-0070 available):\n```\nSkill(skill: \"x-update-system-architecture\", model: \"sonnet\", args: \"--validate-only\")\n```\n[optional]\n\nIf `x-update-system-architecture` is unavailable: log `WARN: x-update-system-architecture unavailable — system-architecture dimension evaluated heuristically`.\n\n### Step 5 — Apply Freshness Window\n\nIf `freshness-window-hours > 0` (from ProjectConfig or `--freshness-window-hours` flag):\n\n```bash\n# Check when code was last committed\ngit log -1 --format=\"%ci\" -- {changed_code_files}\n```\n\nIf the code was committed within the freshness window AND doc was NOT updated:\n- Downgrade FAIL → WARNING: `\"freshness window open — update documentation before merge\"`\n- Exit 0 with warnings surfaced in report.\n\nIf freshness window has expired AND doc was NOT updated:\n- Restore FAIL status → exit 1.\n\n### Step 6 — Emit Report\n\nWrite the structured report using `_TEMPLATE-DOC-VALIDATE-REPORT.md`. If `--report-path` is given, write to that path. Otherwise print to stdout.\n\n```\nDocumentation Validation Report\n  Story: {story-id or N\u002FA}\n  PR:    #{pr-number or N\u002FA}\n  Date:  {ISO-8601}\n\n  Overall: PASS | FAIL | WARNING\n\n  Dimensions:\n    readme              : OK | FAILED | SKIPPED | WARNING\n    api-specs           : OK | FAILED | SKIPPED | N\u002FA (not in stack)\n    grpc-proto          : OK | FAILED | SKIPPED | N\u002FA (not in stack)\n    adr                 : OK | FAILED | SKIPPED\n    skill-docs          : OK | FAILED | SKIPPED\n    system-architecture : OK | FAILED | SKIPPED | N\u002FA (system.md absent)\n\n  Failures:\n    - {dimension}: {reason} (file: {relative-path})\n\n  Warnings:\n    - {dimension}: {message}\n\n  Duration: {seconds}s\n```\n\n**Security:** Never include absolute filesystem paths in report output. Use paths relative to repository root. Never emit environment variables, tokens, or CI runner metadata.\n\n## Error Handling\n\n| Scenario | Action |\n|----------|--------|\n| No git repository | Exit 2 `OPERATIONAL_ERROR: not a git repository` |\n| `--pr-number` but `gh` not on PATH | Fall back to `git diff HEAD~1..HEAD` with WARN |\n| Project YAML not found | Use auto-detect mode for all targets with WARN |\n| Target dimension validator throws error | Mark dimension `ERROR`, continue others, exit 1 |\n| `documentation.targets` contains path traversal | Exit 2 `PATH_TRAVERSAL_REJECTED: {target}` |\n| Symlink encountered in file scan | Skip symlink, log WARN, never follow |\n\n## Performance Contract\n\n- Total validation time: \u003C 30s for repositories with up to 500 changed files and 6 active dimensions.\n- No network calls during validation (all checks are local git + filesystem).\n- Each dimension validator runs independently; no shared mutable state.\n\n## Integration Notes\n\n| Skill | Relationship | Context |\n|-------|-------------|---------|\n| `x-implement-story` | called-by | Phase 3 — mandatory gate (story-0071-0006 wires this) |\n| `x-generate-docs` | precedes (in Phase 3) | generate runs first, validate confirms |\n| `x-update-system-architecture` | optional-delegates-to | system-architecture dimension, EPIC-0070 |\n| `audit-doc-freshness.sh` | CI counterpart | story-0071-0005 wires CI version of same checks |\n",{"name":5,"model":24,"visibility":25,"description":7,"allowed-tools":26,"argument-hint":27,"context-budget":28,"user-invocable":29,"requires-capabilities":30},"sonnet","public","Read, Bash, Grep, Glob","[--story-id STORY-ID] [--pr-number N] [--scope path] [--report-path path]","medium",true,[31],"governance.doc-as-dod","main","952a630c6f38d193a349d86fa18db1de8843e837","src\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring-event-driven\u002F.claude\u002Fskills\u002Fx-validate-docs",1,"https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment","https:\u002F\u002Fgithub.com\u002Freview-bench","https:\u002F\u002Freview-bench.ai","An open benchmark for AI code review.","2026-10-27 06:56:37",{"source":8,"skillName":5,"commands":42,"prompt":52,"zipAvailable":29},[43,46,49],{"tool":44,"command":45},"npx","npx skills add review-bench\u002Federcnj_ia-dev-environment --skill x-validate-docs",{"tool":47,"command":48},"bunx","bunx skills add review-bench\u002Federcnj_ia-dev-environment --skill x-validate-docs",{"tool":50,"command":51},"pnpm","pnpm dlx skills add review-bench\u002Federcnj_ia-dev-environment --skill x-validate-docs","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring-event-driven\u002F.claude\u002Fskills\u002Fx-validate-docs\u002FSKILL.md",[],[55,62,69,76,81,88],{"skillNo":56,"name":57,"nameZh":6,"description":58,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M757M8J48TQ1Y3X25GSJBXAS","x-parallel-eval","Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan \u002F x-story-plan, applies the parallelism-heuristics knowledge pack (hard \u002F regen \u002F soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fx-parallel-eval\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M757M57XMR9546S69466HDWT","parallelism-heuristics","Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard \u002F regen \u002F soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fparallelism-heuristics\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M757M11SZ8P1VCQABT08QVYA","x-watch-pr-ci","Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-watch-pr-ci\u002FSKILL.md",[],[],{"skillNo":77,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M757KW53K8KFPGADFB4PH949","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-validate-docs\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M757KQZHSA10MKC0CR571D60","x-update-system-architecture","Incrementally updates docs\u002Farchitecture\u002Fsystem.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component\u002Fintegration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-update-system-architecture\u002FSKILL.md",[],[],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M757KKBT5Q1SVF8DMJBVF46M","x-update-architecture","Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.","https:\u002F\u002Fgithub.com\u002Freview-bench\u002Federcnj_ia-dev-environment\u002Fblob\u002Fmain\u002Fsrc\u002Ftest\u002Fresources\u002Fgolden\u002Fjava-spring\u002Fplatform-claude-code\u002F.claude\u002Fskills\u002Fx-update-architecture\u002FSKILL.md",[],[]]