Add label-gated CI and documentation dependency map

.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,131 @@
+---
+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
+
+Display results in priority order:
+
+1. **METHODOLOGY (always warn)**: All docs with `type: methodology`, regardless of `drift_risk`.
+   These are shown first because undocumented methodology deviations are P1 in AI review.
+2. **HIGH DRIFT RISK**: Remaining docs (non-methodology) with `drift_risk: high`.
+3. **MEDIUM DRIFT RISK**: Docs with `drift_risk: medium` (excluding methodology, already shown).
+4. **LOW DRIFT RISK**: Docs with `drift_risk: low` (excluding methodology, already shown).
+
+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>
+
+METHODOLOGY (always warn):
+  docs/methodology/REGISTRY.md -- <section hints>
+
+HIGH DRIFT RISK:
+  [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 check: CHANGELOG.md, ROADMAP.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,29 @@ 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 docs that were NOT changed as warnings:
+   - ALL docs with `type: methodology` (regardless of `drift_risk`) — methodology deviations
+     are P1 in AI review, so this warning must always fire
+   - All HIGH `drift_risk` docs (any type)
 
-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:
+  [METHODOLOGY] docs/methodology/REGISTRY.md -- <section hint>
+  [HIGH] docs/survey-roadmap.md
+  [MEDIUM] README.md -- <section hint> (N more -- 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,17 @@ 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. Warn about:
+   - ALL docs with `type: methodology` (regardless of `drift_risk`)
+   - All HIGH `drift_risk` docs (any type)
+   ```
+   Documentation impact: source files changed but related docs were not updated:
+     [METHODOLOGY] 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 +171,16 @@ 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. Warn about:
+   - ALL docs with `type: methodology` (regardless of `drift_risk`)
+   - All HIGH `drift_risk` docs (any type)
+   ```
+   Documentation impact: source files changed but related docs were not updated:
+     [METHODOLOGY] 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 +283,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 +298,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,20 @@ 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. Warn about:
+   - ALL docs with `type: methodology` (regardless of `drift_risk`)
+   - All HIGH `drift_risk` docs (any type)
+   ```
+   Documentation impact: source files changed but related docs were not updated:
+     [METHODOLOGY] 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 +358,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/**'
@@ -20,8 +21,23 @@ on:
     - cron: '0 6 * * 0'
 
 jobs:
+  # Lightweight gate: fails on PRs without the ready-for-ci label.
+  ci-gate:
+    name: CI Gate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require ready-for-ci label on PRs
+        if: >-
+          github.event_name == 'pull_request'
+          && !contains(github.event.pull_request.labels.*.name, 'ready-for-ci')
+        run: |
+          echo "::error::The 'ready-for-ci' label is required to run CI tests."
+          echo "Add the label to trigger CI."
+          exit 1
+
   execute-notebooks:
     name: Execute tutorial notebooks
+    needs: [ci-gate]
     runs-on: ubuntu-latest
 
     steps: