DeepLabCut · C-Achard · May 21, 2026 · Apr 9, 2026 · Apr 9, 2026 · Apr 9, 2026
diff --git a/.github/workflows/docs_and_notebooks_checks.yml b/.github/workflows/docs_and_notebooks_checks.yml
@@ -11,7 +11,7 @@ permissions:
 
 jobs:
   staleness:
-    name: Docs and notebooks scan (read-only)
+    name: Docs and notebooks scan (changed docs only)
     runs-on: ubuntu-latest
     timeout-minutes: 5
 
@@ -31,29 +31,74 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install "pydantic>=2,<3" pyyaml "nbformat>=5"
 
+      - name: Collect changed .md/.ipynb files
+        id: changed_docs
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p tmp/docs_nb_checks
+
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            base="${{ github.event.pull_request.base.sha }}"
+            head="${{ github.event.pull_request.head.sha }}"
+          else
+            base="${{ github.event.before }}"
+            head="${{ github.sha }}"
+          fi
+
+          git diff --name-only --diff-filter=ACMR "$base" "$head" \
+            | { grep -iE '\.(md|ipynb)$' || true; } \
+            | sort -u > tmp/docs_nb_checks/changed_docs.txt
+
+          count=$(wc -l < tmp/docs_nb_checks/changed_docs.txt | tr -d ' ')
+          echo "count=$count" >> "$GITHUB_OUTPUT"
+
+          echo "Changed docs files:"
+          if [[ "$count" -eq 0 ]]; then
+            echo "(none)"
+          else
+            sed 's/^/- /' tmp/docs_nb_checks/changed_docs.txt
+          fi
+
       - name: Run staleness report (read-only)
+        if: steps.changed_docs.outputs.count != '0'
+        shell: bash
         run: |
-          python tools/docs_and_notebooks_check.py \
-          --config tools/docs_and_notebooks_report_config.yml \
-          --out-dir tmp/docs_nb_checks \
-          report
+          set -euo pipefail
+          mapfile -t targets < tmp/docs_nb_checks/changed_docs.txt
 
+          python tools/docs_and_notebooks_check.py \
+            --config tools/docs_and_notebooks_report_config.yml \
+            --out-dir tmp/docs_nb_checks \
+            report \
+            --targets "${targets[@]}"
 
-      # Optional: run check mode (will fail only once you populate allowlists in config)
       - name: Run staleness policy check (optional gate)
+        if: steps.changed_docs.outputs.count != '0'
         continue-on-error: true
+        shell: bash
         run: |
+          set -euo pipefail
+          mapfile -t targets < tmp/docs_nb_checks/changed_docs.txt
+
           python tools/docs_and_notebooks_check.py \
-          --config tools/docs_and_notebooks_report_config.yml \
-          --out-dir tmp/docs_nb_checks \
-          --no-step-summary \
-          check
+            --config tools/docs_and_notebooks_report_config.yml \
+            --out-dir tmp/docs_nb_checks \
+            --no-step-summary \
+            check \
+            --targets "${targets[@]}"
+
+      - name: No changed docs to scan
+        if: steps.changed_docs.outputs.count == '0'
+        run: echo "No changed .md or .ipynb files found in the repo. Skipping scan."
 
       - name: Upload staleness artifacts
+        if: steps.changed_docs.outputs.count != '0'
         uses: actions/upload-artifact@v4
         with:
           name: staleness-report
           path: |
             tmp/docs_nb_checks/*.json
             tmp/docs_nb_checks/*.md
+            tmp/docs_nb_checks/changed_docs.txt
           if-no-files-found: error
diff --git a/tests/tools/docs_and_notebooks_checks/test_check_contracts.py b/tests/tools/docs_and_notebooks_checks/test_check_contracts.py
@@ -438,7 +438,7 @@ def test_write_outputs_contract(tool, repo: Path, cfg, tmp_path: Path):
     assert md_path.exists()
 
     payload = json.loads(json_path.read_text(encoding="utf-8"))
-    assert payload["schema_version"] == tool.SCHEMA_VERSION
+    assert payload["schema_version"] == tool.REPORT_SCHEMA_VERSION
     assert "records" in payload and isinstance(payload["records"], list)
     assert md_path.read_text(encoding="utf-8").startswith("#")
 
@@ -550,3 +550,118 @@ def test_main_returns_2_for_invalid_target_selector(tool, repo: Path, monkeypatc
 
     rc = tool.main(["--config", str(cfg_path), "report", "--targets", "./"])
     assert rc == 2
+
+
+@pytest.mark.parametrize(
+    ("rel", "kind"),
+    [
+        ("docs/page.md", "md"),
+        ("docs/nbs/nb.ipynb", "ipynb"),
+    ],
+)
+def test_metadata_sync_warning_populates_report_targets_and_command(tool, repo: Path, cfg, rel: str, kind: str):
+    """
+    Out-of-sync embedded last_content_updated should:
+    - add metadata_sync_needed warning
+    - appear in Report.metadata_sync_targets
+    - generate a non-empty metadata_sync_command
+    """
+    embedded_date = "2000-01-01"
+
+    if kind == "md":
+        _write(
+            repo,
+            rel,
+            f"---\ndeeplabcut:\n  last_content_updated: {embedded_date}\n---\n# hello\n",
+        )
+    else:
+        nb = tool.nbformat.v4.new_notebook(metadata={tool.DLC_NAMESPACE: {"last_content_updated": embedded_date}})
+        _write(
+            repo,
+            rel,
+            tool.nbformat.writes(nb, version=4, indent=2, ensure_ascii=False) + "\n",
+        )
+
+    # Git-derived content date differs from embedded metadata date
+    _git_commit(repo, "docs: add file", "2020-01-01T12:00:00+00:00")
+
+    tool_cfg = cfg(include=[rel])
+    records = tool.scan_files(repo, tool_cfg, targets=[rel])
+
+    assert len(records) == 1
+    rec = records[0]
+
+    # Sanity check: embedded metadata is parsed, but differs from git-derived date
+    assert rec.meta is not None
+    assert rec.meta.last_content_updated == date(2000, 1, 1)
+    assert rec.last_content_updated == date(2020, 1, 1)
+
+    # New warning should be present
+    assert "metadata_sync_needed" in rec.warnings
+
+    metadata_sync_targets = tool.collect_metadata_sync_targets(records)
+    metadata_sync_command = tool.build_metadata_sync_command(
+        "tools/docs_and_notebooks_report_config.yml",
+        metadata_sync_targets,
+    )
+
+    report = tool.Report(
+        generated_at=datetime.now(timezone.utc),
+        repo_root=str(repo),
+        config_path="tools/docs_and_notebooks_report_config.yml",
+        totals=tool.summarize(records),
+        records=records,
+        metadata_sync_targets=metadata_sync_targets,
+        metadata_sync_command=metadata_sync_command,
+    )
+
+    assert report.metadata_sync_targets == [rel]
+    assert report.metadata_sync_command
+    assert "--set-content-date-from-git" in report.metadata_sync_command
+    assert "--targets" in report.metadata_sync_command
+    assert rel in report.metadata_sync_command
+
+    # Optional: also verify the markdown report renders the guidance section
+    rendered = tool.to_markdown(report, tool_cfg)
+    assert "## Metadata sync suggestions" in rendered
+    assert f"- `{rel}`" in rendered
+
+
+@pytest.mark.parametrize(
+    ("rel", "kind"),
+    [
+        ("docs/page.md", "md"),
+        ("docs/nbs/nb.ipynb", "ipynb"),
+    ],
+)
+def test_enforce_fails_when_metadata_sync_needed_is_configured(tool, repo: Path, cfg, rel: str, kind: str):
+    """
+    If policy.fail_if_metadata_sync_needed=True, an out-of-sync file should
+    become a policy violation in check/enforcement mode.
+    """
+    embedded_date = "2000-01-01"
+
+    if kind == "md":
+        _write(
+            repo,
+            rel,
+            f"---\ndeeplabcut:\n  last_content_updated: {embedded_date}\n---\n# hello\n",
+        )
+    else:
+        nb = tool.nbformat.v4.new_notebook(metadata={tool.DLC_NAMESPACE: {"last_content_updated": embedded_date}})
+        _write(
+            repo,
+            rel,
+            tool.nbformat.writes(nb, version=4, indent=2, ensure_ascii=False) + "\n",
+        )
+
+    _git_commit(repo, "docs: add file", "2020-01-01T12:00:00+00:00")
+
+    tool_cfg = cfg(include=[rel], fail_if_metadata_sync_needed=True)
+    records = tool.scan_files(repo, tool_cfg, targets=[rel])
+
+    violations = tool.enforce(tool_cfg, records)
+
+    assert violations == [
+        f"{rel}: embedded last_content_updated is missing or out of sync with git content update date"
+    ]