feat(lint): add warning-only doc-policy lint

.changelog/unreleased/70-doc-policy-lint.md

@@ -0,0 +1,3 @@
+## Added
+
+- Add the warning-only `doc-policy-lint` reusable workflow and caller example for document-policy warnings.

.claude/friction.md

@@ -1,4 +1,5 @@
 <!-- Log non-bug workflow hiccups here; category = tooling | docs | skill | hook | ci | env; cost = rerun | blocked | context-burn | none. Keep each cell one line. -->
-| date | category | what happened | cost | suggested fix |
-|---|---|---|---|---|
-| 2026-06-15 | hook | verified friction ledger append path during #238 rollout | none | keep hook allowlist synced with repo-template |
+
+| date       | category | what happened                                            | cost | suggested fix                                 |
+| ---------- | -------- | -------------------------------------------------------- | ---- | --------------------------------------------- |
+| 2026-06-15 | hook     | verified friction ledger append path during #238 rollout | none | keep hook allowlist synced with repo-template |

.github/workflows/doc-policy-lint.yml

@@ -0,0 +1,117 @@
+name: Doc Policy Lint (reusable)
+
+# Warning-only document-policy lint for durable docs. This workflow reports
+# status-header drift, charter budget overages, dangling supersession links,
+# placeholder tokens in active docs, index coherence, and stale active-doc
+# terms near changed current-truth registers.
+#
+# Promotion into `.agent/check-map.yml` docs requirements is intentionally
+# deferred. Findings here are warnings only, following the PR-template
+# drift-guard precedent.
+
+on:
+  workflow_call:
+    inputs:
+      workflow-library-ref:
+        description: |
+          Git ref (tag, branch, or SHA) of ArchonVII/github-workflows used to
+          source scripts/doc-policy-lint.mjs. MUST match the ref the caller
+          pins this reusable workflow to (for example @v1 plus v1 here).
+        type: string
+        default: v1
+      max-warnings:
+        description: "Maximum number of warning annotations to emit before truncating."
+        type: number
+        default: 200
+      readme-max-lines:
+        description: "README.md charter budget."
+        type: number
+        default: 150
+      agents-max-lines:
+        description: "AGENTS.md charter budget."
+        type: number
+        default: 300
+      tool-stub-max-lines:
+        description: "CLAUDE.md/GEMINI.md tool-stub charter budget."
+        type: number
+        default: 25
+      vision-max-lines:
+        description: "VISION.md charter budget."
+        type: number
+        default: 120
+
+jobs:
+  doc-policy-lint:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Check out caller repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check out github-workflows for doc-policy helper scripts
+        uses: actions/checkout@v4
+        with:
+          repository: ArchonVII/github-workflows
+          ref: ${{ inputs.workflow-library-ref }}
+          path: __github-workflows__
+
+      - name: Collect changed files
+        shell: bash
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before || '' }}
+        run: |
+          set -uo pipefail
+
+          : > .doc-policy-changed-files.txt
+
+          if [ -z "$BASE_SHA" ]; then
+            echo "No base SHA available; stale active-doc term signal will run without PR-change context."
+            exit 0
+          fi
+
+          case "$BASE_SHA" in
+            0000000000000000000000000000000000000000)
+              echo "Base SHA is empty push sentinel; stale active-doc term signal will run without PR-change context."
+              exit 0
+              ;;
+          esac
+
+          if git cat-file -e "${BASE_SHA}^{commit}" 2>/dev/null; then
+            if ! git diff --name-only "$BASE_SHA"...HEAD > .doc-policy-changed-files.txt; then
+              echo "::warning title=Doc policy lint context::Could not diff $BASE_SHA...HEAD; stale active-doc term signal will run without PR-change context."
+              : > .doc-policy-changed-files.txt
+            fi
+          else
+            echo "::warning title=Doc policy lint context::Could not resolve base SHA $BASE_SHA; stale active-doc term signal will run without PR-change context."
+          fi
+
+      - name: Run doc-policy lint
+        shell: bash
+        run: |
+          set -uo pipefail
+
+          echo "Doc policy lint is warning-only; findings never fail this job."
+          node __github-workflows__/scripts/doc-policy-lint.mjs \
+            --repo . \
+            --changed-files .doc-policy-changed-files.txt \
+            --github-annotations \
+            --summary .doc-policy-lint-summary.md \
+            --max-warnings "${{ inputs.max-warnings }}" \
+            --readme-max-lines "${{ inputs.readme-max-lines }}" \
+            --agents-max-lines "${{ inputs.agents-max-lines }}" \
+            --tool-stub-max-lines "${{ inputs.tool-stub-max-lines }}" \
+            --vision-max-lines "${{ inputs.vision-max-lines }}"
+
+          status="$?"
+          if [ "$status" -ne 0 ]; then
+            echo "::warning title=Doc policy lint skipped::doc-policy-lint exited with $status; warning-only workflow will not fail."
+          fi
+
+          if [ -f .doc-policy-lint-summary.md ]; then
+            cat .doc-policy-lint-summary.md >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+          exit 0

README.md

@@ -50,7 +50,7 @@ full immutability can pin to a commit SHA instead of `@v1`.
 
 ## Workflow Inventory
 
-This repo currently contains 18 reusable `workflow_call` workflows and 2
+This repo currently contains 19 reusable `workflow_call` workflows and 2
 provider self-test workflows.
 
 ### Required Gate And PR Policy
@@ -85,6 +85,7 @@ provider self-test workflows.
 | --- | --- | --- |
 | [`changelog-fragment.yml`](.github/workflows/changelog-fragment.yml) | Requires an added `.changelog/unreleased/*.md` fragment when configured source paths change, with a label-based opt-out. | [`examples/changelog-fragment.yml`](examples/changelog-fragment.yml) |
 | [`doc-orphan-detector.yml`](.github/workflows/doc-orphan-detector.yml) | Scheduled backstop for committed docs stranded on pushed branches with no open PR. Reports path-only tracking issues and never commits or pushes. | [`examples/doc-orphan-detector.yml`](examples/doc-orphan-detector.yml) |
+| [`doc-policy-lint.yml`](.github/workflows/doc-policy-lint.yml) | Warning-only document-policy lint for durable docs: status headers, charter budgets, supersession links, active-doc placeholders, index coherence, and stale active-doc terms. | [`examples/doc-policy-lint.yml`](examples/doc-policy-lint.yml) |
 | [`anomaly-triage.yml`](.github/workflows/anomaly-triage.yml) | Reads a per-PR anomalies file, classifies entries as PR-related or unrelated, posts sticky review comments, and can open downstream issues. | [`examples/anomaly-triage.yml`](examples/anomaly-triage.yml) |
 | [`anomaly-to-issue.yml`](.github/workflows/anomaly-to-issue.yml) | On merge, promotes files under `.anomalies/` into GitHub issues with parsed frontmatter. | [`examples/anomaly-to-issue.yml`](examples/anomaly-to-issue.yml) |
 | [`labeler.yml`](.github/workflows/labeler.yml) | Thin wrapper around `actions/labeler@v5`. | [`examples/labeler.yml`](examples/labeler.yml) |
@@ -143,9 +144,10 @@ repo-required-gate / decision
 
 Add specialized callers only when the repo needs them. For example, use
 `doc-orphan-detector.yml` on repos that allow doc-sweep recovery, use
-`auto-merge-dependabot.yml` only where Dependabot auto-merge is acceptable, and
-use standalone `actionlint.yml` when workflow validation should run outside the
-required gate.
+`doc-policy-lint.yml` when document-policy warnings should be visible without
+blocking merges, use `auto-merge-dependabot.yml` only where Dependabot
+auto-merge is acceptable, and use standalone `actionlint.yml` when workflow
+validation should run outside the required gate.
 
 ## PR Contract And Role Separation
 

docs/repo-update-log.md

@@ -15,6 +15,15 @@ This log records agent-visible repository changes that should be easy to audit l
 - **Propagation:** none | pending <repo/path> | completed <repo/path>
 ```
 
+## 2026-06-15 - Warning-only document policy lint workflow
+
+- **Issue/PR:** #70 / (pending)
+- **Branch:** agent/codex/70-doc-policy-lint
+- **Changed paths:** .github/workflows/doc-policy-lint.yml, examples/doc-policy-lint.yml, scripts/doc-policy-lint.mjs, scripts/doc-policy-lint.test.mjs, scripts/workflow-structure.test.mjs, README.md, .changelog/unreleased/70-doc-policy-lint.md, docs/repo-update-log.md
+- **What changed:** Added a warning-only reusable `doc-policy-lint` workflow and caller example. The helper checks durable docs status headers, OD4 charter budgets, supersession links, active-doc placeholders, index coherence, and stale active-doc terms near changed current-truth registers without failing the job for findings.
+- **Verification:** `npm test` passed 129/129 tests. `C:\Users\josep\go\bin\actionlint.exe .github\workflows\doc-policy-lint.yml examples\doc-policy-lint.yml` exited 0 with no findings.
+- **Propagation:** pending `v1` tag movement after merge; consumer required-check promotion is explicitly deferred.
+
 ## 2026-06-15 - Friction ledger wiring
 
 - **Issue/PR:** #78 / #79

examples/doc-policy-lint.yml

@@ -0,0 +1,29 @@
+# Copy to `.github/workflows/doc-policy-lint.yml`.
+#
+# Warning-only document-policy lint. It emits annotations for durable docs/**
+# status headers, charter budgets, supersession links, active-doc placeholders,
+# index coherence, and stale active-doc terms. Do not make this a required
+# branch-protection check during the warning-first rollout.
+
+name: Doc Policy Lint
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - ".changelog/**"
+      - "README.md"
+      - "AGENTS.md"
+      - "CLAUDE.md"
+      - "GEMINI.md"
+      - "VISION.md"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  doc-policy-lint:
+    uses: ArchonVII/github-workflows/.github/workflows/doc-policy-lint.yml@v1
+    with:
+      workflow-library-ref: v1