Add label-gated CI and documentation dependency map

Two process improvements:

1. Label-gated CI: rust-test.yml and notebooks.yml jobs now require
   the `ready-for-ci` label on PRs before running. AI review still
   runs on every push. This eliminates wasted CI runs during the
   iterative AI review phase. The `unlabeled` event type ensures
   removing the label clears passing CI status.

2. Documentation dependency map: docs/doc-deps.yaml maps all 47
   source files to their dependent documentation. New /docs-impact
   skill surfaces impacted docs. Wired into /pre-merge-check,
   /submit-pr, and /push-pr-update for automatic enforcement.
   /docs-check gains a `map` validation mode.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: igerber

.claude/commands/docs-check.md

@@ -1,6 +1,6 @@
 ---
 description: Verify documentation completeness including scholarly references
-argument-hint: "[all | readme | refs | api | tutorials]"
+argument-hint: "[all | readme | refs | api | tutorials | map]"
 ---
 
 # Documentation Completeness Check
@@ -11,11 +11,12 @@ Verify that documentation is complete and includes appropriate scholarly referen
 
 The user may provide an optional argument: `$ARGUMENTS`
 
-- If empty or "all": Run all checks
+- If empty or "all": Run all checks (including map validation)
 - If "readme": Check README.md sections only
 - If "refs" or "references": Check scholarly references only
 - If "api": Check API documentation (RST files) only
 - If "tutorials": Check tutorial coverage only
+- If "map": Validate docs/doc-deps.yaml integrity only
 
 ## Estimators and Required Documentation
 
@@ -197,9 +198,41 @@ Tutorial Coverage:
 Summary: 15/18 checks passed, 3 issues found
 ```
 
+### 8. Dependency Map Validation (if "map" or "all")
+
+Validate the integrity of `docs/doc-deps.yaml`:
+
+1. **Read and parse** `docs/doc-deps.yaml`. If missing or malformed YAML, report error.
+
+2. **Check all doc paths exist**: For every `path` in every `sources` entry, verify the file
+   exists on disk. Report missing files:
+   ```
+   [FAIL] docs/doc-deps.yaml references non-existent: docs/old_name.rst
+   ```
+
+3. **Check all source files have entries**: List all `diff_diff/*.py` and
+   `diff_diff/visualization/*.py` files. For each, verify it appears either as a key in
+   `sources:` or as a member of a `groups:` entry. Report missing:
+   ```
+   [WARN] diff_diff/new_module.py has no entry in docs/doc-deps.yaml
+   ```
+
+4. **Check for orphan doc paths**: Collect all unique doc paths from the map. Check if any
+   doc file referenced in the map no longer exists or has been renamed.
+
+5. **Report summary**:
+   ```
+   Dependency Map (docs/doc-deps.yaml):
+     Sources mapped: 28
+     Groups defined: 9
+     Doc paths referenced: 45
+     [PASS/FAIL] All doc paths exist
+     [PASS/WARN] All source files have entries
+   ```
+
 ## Notes
 
 - This check is especially important after adding new estimators
 - The CONTRIBUTING.md file documents what documentation is required for new features
 - Missing references should cite the original methodology paper, not textbooks
-- When adding new estimators, update this skill's tables accordingly
+- When adding new estimators, update this skill's tables and docs/doc-deps.yaml accordingly

.claude/commands/docs-impact.md

@@ -0,0 +1,122 @@
+---
+description: Show which documentation files may need updating based on changed source files
+argument-hint: "[file1.py file2.py ...]"
+---
+
+# Documentation Impact Report
+
+Identify which documentation files may need updating when source files in `diff_diff/` change.
+Uses the dependency map at `docs/doc-deps.yaml`.
+
+## Arguments
+
+`$ARGUMENTS` is an optional space-separated list of source file paths (e.g., `diff_diff/staggered.py`).
+If empty, auto-detect changed files from git.
+
+## Instructions
+
+### 1. Load Dependency Map
+
+Read `docs/doc-deps.yaml` using the Read tool.
+
+If the file does not exist or cannot be parsed, display:
+```
+Error: docs/doc-deps.yaml not found or malformed. Cannot generate impact report.
+```
+And stop.
+
+### 2. Identify Changed Source Files
+
+**If `$ARGUMENTS` is non-empty**: Use those file paths directly as the changed files list.
+
+**If `$ARGUMENTS` is empty**: Auto-detect from git:
+
+```bash
+# Unstaged changes
+git diff --name-only HEAD 2>/dev/null || true
+# Staged changes
+git diff --cached --name-only 2>/dev/null || true
+# Untracked files
+git ls-files --others --exclude-standard 2>/dev/null || true
+```
+
+Filter results to only files matching `diff_diff/**/*.py`. Deduplicate.
+
+If no source files found, display:
+```
+No changed source files in diff_diff/ detected. Nothing to report.
+```
+And stop.
+
+### 3. Resolve Group Membership
+
+For each changed file, check if it appears in any `groups:` list in the YAML.
+If it does, resolve it to the **first entry** in that group (the primary module).
+This is the key used for doc lookup in the `sources:` section.
+
+Example: if `diff_diff/staggered_bootstrap.py` changed, it resolves to `diff_diff/staggered.py`
+because it is in the `staggered` group.
+
+### 4. Look Up Impacted Docs
+
+For each resolved source entry in the `sources:` section:
+1. Get the `drift_risk` level
+2. Get the list of `docs` entries (path, type, section, note)
+
+Collect all impacted docs across all changed files. Deduplicate by path, but merge
+section hints from different sources (e.g., REGISTRY.md may be referenced by both
+staggered.py and survey.py with different section hints).
+
+### 5. Validate Doc Paths
+
+For each unique doc `path` in the results, verify the file exists on disk using the
+Read tool (or Glob). If a path does not exist, flag it:
+```
+[STALE] docs/doc-deps.yaml references non-existent file: <path>
+```
+
+### 6. Display Report
+
+Group results by drift risk level (HIGH first, then MEDIUM, then LOW).
+Within each group, show the type label and path, with section hints where available.
+
+**Output format:**
+
+```
+=== Documentation Impact Report ===
+Changed: <comma-separated list of changed source files>
+
+HIGH DRIFT RISK:
+  [methodology] docs/methodology/REGISTRY.md -- <section hints>
+  [roadmap] docs/survey-roadmap.md
+
+MEDIUM DRIFT RISK:
+  [user_guide] README.md -- <section hints>
+  [tutorial] docs/tutorials/02_staggered_did.ipynb
+  [performance] docs/benchmarks.rst
+
+LOW DRIFT RISK:
+  [api_reference] docs/api/staggered.rst
+
+No map entry: <files not found in sources or groups, or "(none)">
+Stale references: <invalid paths, or "(none)">
+Always update: CHANGELOG.md
+```
+
+### 7. Flag Missing Entries
+
+List any changed source files that had no entry in the `sources:` section and were not
+members of any group:
+```
+No map entry: diff_diff/new_module.py (consider adding to docs/doc-deps.yaml)
+```
+
+## Examples
+
+```bash
+# Auto-detect from git status
+/docs-impact
+
+# Check specific files
+/docs-impact diff_diff/staggered.py diff_diff/survey.py
+```

.claude/commands/pre-merge-check.md

@@ -109,19 +109,26 @@ git diff HEAD -- <changed-py-files> | grep "^+.*def " | head -10
 
 For each changed function, flag: "Verify docstring Parameters section matches updated signature for: `<function_name>`"
 
-#### 2.5 Methodology Documentation Check
+#### 2.5 Documentation Impact Check
 
-If any methodology files changed, check whether `docs/methodology/REGISTRY.md` was also
-modified in the changed file set (from Section 1).
+If any source files in `diff_diff/` changed, read `docs/doc-deps.yaml` and identify which
+dependent documentation files are NOT also in the changed file set (from Section 1).
 
-If methodology files changed but REGISTRY.md was NOT modified, flag:
-"Methodology files changed but `docs/methodology/REGISTRY.md` was not updated. If your
-changes deviate from reference implementations, document them using a reviewer-recognized
-label (`**Note:**`, `**Deviation from R:**`, or `**Note (deviation from R):**`) —
-undocumented deviations are flagged as P1 by the AI reviewer and cannot be mitigated
-by TODO.md."
+For each changed source file:
+1. Look up its entry in `docs/doc-deps.yaml` (resolving group membership for multi-file modules)
+2. Check each dependent doc's `path` against the changed file set
+3. Report HIGH drift risk docs that were NOT changed as warnings
 
-This is a WARNING, not a blocker — not every methodology change involves a deviation.
+**Report format**:
+```
+Documentation impact: source files changed but related docs were not updated:
+  [HIGH] docs/methodology/REGISTRY.md -- <section hint>
+  [HIGH] docs/survey-roadmap.md
+  [MEDIUM] README.md -- <section hint> (3 more MEDIUM/LOW docs — run /docs-impact for details)
+```
+
+This is a WARNING, not a blocker — not every source change requires a doc update.
+For full details, run `/docs-impact`.
 
 #### 2.6 Secret Scanning Patterns (Canonical Definitions)
 

.claude/commands/push-pr-update.md

@@ -128,13 +128,15 @@ When the working tree is clean but commits are ahead, check for methodology issu
 
    If warnings are found, display them as warnings (non-blocking) since changes are already committed.
 
-3. **REGISTRY.md check**: Check whether `docs/methodology/REGISTRY.md` is also in the committed changes (`git diff --name-only <comparison-ref>..HEAD`).
-   If methodology files changed but REGISTRY.md was NOT modified, warn:
-   "Methodology files changed but `docs/methodology/REGISTRY.md` was not updated.
-   If your changes deviate from reference implementations, document them using a
-   reviewer-recognized label (`**Note:**`, `**Deviation from R:**`, or
-   `**Note (deviation from R):**`) — undocumented deviations are flagged as P1
-   by the AI reviewer."
+3. **Documentation impact check**: Check which source files in `diff_diff/` are in the committed changes.
+   If source files are present, read `docs/doc-deps.yaml` and check which dependent
+   documentation files are NOT also in the committed changes. For HIGH drift risk docs, warn:
+   ```
+   Documentation impact: source files changed but related docs were not updated:
+     [HIGH] docs/methodology/REGISTRY.md — <section hint>
+     [HIGH] docs/survey-roadmap.md
+   Run /docs-impact for full details.
+   ```
    This is a WARNING, not a blocker.
 
 Note: Section 3b checks are informational warnings only — no AskUserQuestion prompt, since changes are already committed and cannot be unstaged. This differs from the staged-changes path (Section 3) which offers a "fix vs continue" choice.
@@ -167,14 +169,14 @@ Note: Section 3b checks are informational warnings only — no AskUserQuestion p
    ```
    Use AskUserQuestion. If user chooses to fix, abort the commit flow.
 
-   **REGISTRY.md check** (if methodology files are staged):
-   Check whether `docs/methodology/REGISTRY.md` is also in the staged file set.
-   If methodology files changed but REGISTRY.md was NOT staged, warn:
-   "Methodology files changed but `docs/methodology/REGISTRY.md` was not updated.
-   If your changes deviate from reference implementations, document them using a
-   reviewer-recognized label (`**Note:**`, `**Deviation from R:**`, or
-   `**Note (deviation from R):**`) — undocumented deviations are flagged as P1
-   by the AI reviewer."
+   **Documentation impact check** (if source files are staged):
+   If source files in `diff_diff/` are present, read `docs/doc-deps.yaml` and check which
+   dependent documentation files are NOT also in the staged set. For HIGH drift risk docs, warn:
+   ```
+   Documentation impact: source files changed but related docs were not updated:
+     [HIGH] docs/methodology/REGISTRY.md — <section hint>
+   Run /docs-impact for full details.
+   ```
    This is a WARNING, not a blocker.
 
 3. **Capture file count for reporting**:
@@ -277,6 +279,7 @@ Commit: <hash> - <message>
 Files changed: <files-changed-count>
 
 AI code review triggered. Results will appear shortly.
+When AI review is green, add the `ready-for-ci` label to trigger CI tests (if not already added).
 
 PR URL: <url>
 ```
@@ -291,6 +294,7 @@ Files changed: <files-changed-count>
 PR URL: <url>
 
 Tip: Run /ai-review to request AI code review.
+Note: CI tests require the `ready-for-ci` label on the PR.
 ```
 
 ## Error Handling

.claude/commands/submit-pr.md

@@ -154,14 +154,18 @@ Determine if this is a fork-based workflow:
    ```
    Use AskUserQuestion. If user chooses to fix, abort the commit flow and let them address the issues.
 
-3. **REGISTRY.md check** (if methodology files are staged):
-   Check whether `docs/methodology/REGISTRY.md` is also in the staged file set (`git diff --cached --name-only`).
-   If methodology files changed but REGISTRY.md was NOT staged, warn:
-   "Methodology files changed but `docs/methodology/REGISTRY.md` was not updated.
-   If your changes deviate from reference implementations, document them using a
-   reviewer-recognized label (`**Note:**`, `**Deviation from R:**`, or
-   `**Note (deviation from R):**`) — undocumented deviations are flagged as P1
-   by the AI reviewer."
+3. **Documentation impact check** (if source files are staged):
+   ```bash
+   git diff --cached --name-only | grep "^diff_diff/.*\.py$"
+   ```
+   If source files are present, read `docs/doc-deps.yaml` and check which dependent
+   documentation files are NOT also in the staged set. For HIGH drift risk docs, warn:
+   ```
+   Documentation impact: source files changed but related docs were not updated:
+     [HIGH] docs/methodology/REGISTRY.md — <section hint>
+     [HIGH] docs/survey-roadmap.md
+   Run /docs-impact for full details.
+   ```
    This is a WARNING, not a blocker.
 
 ### 6. Commit Changes
@@ -352,7 +356,8 @@ Changes included:
 
 Next steps:
 - Review the PR at the URL above
-- Request reviewers if needed
+- AI code review runs automatically on PR open
+- When AI review is green, add the `ready-for-ci` label to trigger CI tests
 - Run /review-pr <number> to get AI review
 ```
 

.github/workflows/notebooks.yml

@@ -10,6 +10,7 @@ on:
       - '.github/workflows/notebooks.yml'
   pull_request:
     branches: [main]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
     paths:
       - 'docs/tutorials/**'
       - 'diff_diff/**'
@@ -22,6 +23,10 @@ on:
 jobs:
   execute-notebooks:
     name: Execute tutorial notebooks
+    if: >-
+      github.event_name == 'push'
+      || github.event_name == 'schedule'
+      || contains(github.event.pull_request.labels.*.name, 'ready-for-ci')
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/rust-test.yml

@@ -11,6 +11,7 @@ on:
       - '.github/workflows/rust-test.yml'
   pull_request:
     branches: [main]
+    types: [opened, synchronize, reopened, labeled, unlabeled]
     paths:
       - 'rust/**'
       - 'diff_diff/**'
@@ -25,6 +26,9 @@ jobs:
   # Run Rust unit tests on all platforms
   rust-tests:
     name: Rust Unit Tests (${{ matrix.os }})
+    if: >-
+      github.event_name == 'push'
+      || contains(github.event.pull_request.labels.*.name, 'ready-for-ci')
     runs-on: ${{ matrix.os }}
     env:
       PYO3_USE_ABI3_FORWARD_COMPATIBILITY: 1
@@ -58,6 +62,9 @@ jobs:
   # Build and test with Python on multiple platforms
   python-tests:
     name: Python Tests (${{ matrix.os }}, py${{ matrix.python-version }})
+    if: >-
+      github.event_name == 'push'
+      || contains(github.event.pull_request.labels.*.name, 'ready-for-ci')
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -158,6 +165,9 @@ jobs:
   # Test pure Python fallback (without Rust extension)
   python-fallback:
     name: Pure Python Fallback
+    if: >-
+      github.event_name == 'push'
+      || contains(github.event.pull_request.labels.*.name, 'ready-for-ci')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

CLAUDE.md

@@ -135,6 +135,7 @@ category (`Methodology/Correctness`, `Performance`, or `Testing/Docs`):
 | File | Contains |
 |------|----------|
 | `docs/methodology/REGISTRY.md` | Academic foundations, equations, edge cases — **consult before methodology changes** |
+| `docs/doc-deps.yaml` | Source-to-documentation dependency map — **consult when any source file changes** |
 | `CONTRIBUTING.md` | Documentation requirements, test writing guidelines |
 | `.claude/commands/dev-checklists.md` | Checklists for params, methodology, warnings, reviews, bugs (run `/dev-checklists`) |
 | `.claude/memory.md` | Debugging patterns, tolerances, API conventions (git-tracked) |
@@ -145,6 +146,7 @@ category (`Methodology/Correctness`, `Performance`, or `Testing/Docs`):
 ## Workflow
 
 - For non-trivial tasks, use `EnterPlanMode`. Consult `docs/methodology/REGISTRY.md` for methodology changes.
+- When modifying source files in `diff_diff/`, consult `docs/doc-deps.yaml` to identify impacted documentation. Run `/docs-impact` to see the full list.
 - For bug fixes, grep for the pattern across all files before fixing.
 - Follow the relevant development checklists (run `/dev-checklists`).
 - Before submitting: run `/pre-merge-check`, then `/ai-review-local` for pre-PR AI review.