docs: clear the markdownlint backlog and gate structure tree-wide

.claude/settings.local.json

@@ -12,7 +12,33 @@
       "Bash(cat:*)",
       "Bash(task test-e2e:*)",
       "Bash(k3d cluster *)",
-      "Bash(kubectl config *)"
+      "Bash(kubectl config *)",
+      "Bash(./hack/docs-files.sh all *)",
+      "Bash(xargs -r markdownlint-cli2)",
+      "Bash(grep -n \"^\\\\*\\\\*Migration\\\\*\\\\*$\" /workspaces/gitops-reverser2/docs/UPGRADING.md)",
+      "Bash(markdownlint-cli2 docs/facts/audit-webhook-api-server-connectivity.md)",
+      "Bash(sort -t'[' -k2 -rn)",
+      "Bash(git add *)",
+      "Bash(git commit -m 'docs: fix audit-webhook-api-server-connectivity.md line-length errors *)",
+      "Bash(markdownlint-cli2 docs/spec/unsupported-folder-refusal-plan.md)",
+      "Bash(markdownlint-cli2 *)",
+      "Bash(markdownlint-cli2 \"docs/facts/kubernetes-apf-and-inflight-tuning.md\")",
+      "Bash(task lint-markdown *)",
+      "Bash(tee /tmp/markdown-lint-full.txt)",
+      "Bash(cat /tmp/markdown-lint-full.txt | grep -E \"error MD\" | wc -l)",
+      "Read(//tmp/**)",
+      "Bash(task lint-markdown-fix *)",
+      "Bash(git commit -m 'docs: fix unsupported-folder-refusal-plan.md fence language and blockquote *)",
+      "Bash(markdownlint-cli2 docs/design/reconcile-triggering.md)",
+      "Bash(markdownlint-cli2 \"docs/design/reconcile-triggering.md\")",
+      "Bash(markdownlint-cli2 \"docs/design/support-boundary/render-attribution.md\")",
+      "Bash(awk -F: '{print $1}')",
+      "Bash(markdownlint-cli2 \"docs/design/watch-and-catalog-architecture.md\")",
+      "Bash(git commit -m 'docs: fix trailing whitespace *)",
+      "Bash(awk -F: '{print $1\":\"$2}')",
+      "Bash(task lint-docs *)",
+      "Bash(cat /tmp/full-lint.txt | grep \"error MD\" | cut -d' ' -f3 | cut -d'/' -f1 | sort | uniq -c | sort -rn)",
+      "Bash(git commit -m 'docs: batch-fix fence language in test fixture files *)"
     ]
   }
 }

.devcontainer/README.md

@@ -24,7 +24,6 @@ git config --global user.email "you@example.com"
 
 If `ssh-add -L` shows no keys, commit signing inside the devcontainer will fail.
 
-
 ### VS Code
 
 1. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)

.docs-lint-scope

@@ -1,19 +1,19 @@
-# Markdown files the documentation linters gate.
+# Markdown files the PROSE linter gates.
 #
-# `task lint` fails on markdownlint findings or Vale errors in these files and
-# ignores every other .md file in the tree. That is a rollout position, not the
-# destination: measured with the committed config, 102 of 174 linted files fail
-# markdownlint and 148 of 174 fail Vale, so gating everything today would be a
-# wall no one could land a change through.
+# `task lint` fails on Vale errors in these files and ignores every other .md file
+# in the tree. That is a rollout position, not the destination: 145 of the 167
+# linted files carry at least one Vale error, almost all of them em dashes, so
+# gating everything today would be a wall no one could land a change through.
 #
-# Add a file here once it passes. Check what it would cost first:
+# Structure (markdownlint) is NOT staged this way any more. It is clean tree-wide
+# and gates every tracked file, so a new document cannot regress it and does not
+# need to be listed here to be checked.
+#
+# Add a file here once Vale passes on it. Check what it would cost first:
 #
-#   markdownlint-cli2 docs/some-file.md
 #   vale docs/some-file.md
-#   task lint-markdown-fix DOCS_SCOPE=all   # the mechanical half, whole tree
 #
-# `task lint-markdown DOCS_SCOPE=all` and `task lint-prose DOCS_SCOPE=all` show
-# the whole backlog without gating on it.
+# `task lint-prose DOCS_SCOPE=all` shows the whole backlog without gating on it.
 #
 # Every path here must be tracked by git; a typo fails the lint run rather than
 # silently shrinking the gate to nothing.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -12,6 +12,7 @@ A clear and concise description of what the bug is.
 
 **To Reproduce**
 Steps to reproduce the behavior:
+
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
@@ -24,15 +25,18 @@ A clear and concise description of what you expected to happen.
 If applicable, add screenshots to help explain your problem.
 
 **Environment (please complete the following information):**
- - OS: [e.g. Ubuntu 20.04]
- - Kubernetes Version: [e.g. 1.28]
- - GitOps Reverser Version: [e.g. v0.1.0]
- - Go Version: [e.g. 1.21]
+
+- OS: [e.g. Ubuntu 20.04]
+- Kubernetes Version: [e.g. 1.28]
+- GitOps Reverser Version: [e.g. v0.1.0]
+- Go Version: [e.g. 1.21]
 
 **Additional context**
 Add any other context about the problem here.
 
 **Logs**
 Please include relevant logs:
+
+```bash
+Paste logs here
 ```
-Paste logs here

.github/ISSUE_TEMPLATE/feature_request.md

@@ -22,8 +22,9 @@ Add any other context or screenshots about the feature request here.
 **Implementation considerations**
 If you have thoughts on how this could be implemented, please share them here.
 
-**Priority**
+## Priority
+
 - [ ] Low
 - [ ] Medium
 - [ ] High
-- [ ] Critical
+- [ ] Critical

.github/RELEASES.md

@@ -31,6 +31,7 @@ git push origin main
 ```
 
 Expected outcome:
+
 1. CI runs (lint, unit tests, e2e)
 2. If tests pass → Release PR created for v0.2.0
 3. Merge PR → GitHub Release + Docker images published
@@ -41,7 +42,7 @@ Expected outcome:
 
 ### The Release Flow
 
-```
+```text
 Push to main
     ↓
 [CI: Build & Test + E2E]
@@ -99,7 +100,7 @@ Push to main
 
 ### Format
 
-```
+```text
 <type>(<optional scope>): <description>
 
 [optional body]
@@ -127,6 +128,7 @@ Push to main
 ### Examples
 
 **Feature (Minor Bump):**
+
 ```bash
 git commit -m "feat(controller): add multi-repository support
 
@@ -137,6 +139,7 @@ Closes #42"
 ```
 
 **Bug Fix (Patch Bump):**
+
 ```bash
 git commit -m "fix(webhook): prevent race condition in event queue
 
@@ -146,6 +149,7 @@ Fixes #123"
 ```
 
 **Breaking Change (Major Bump):**
+
 ```bash
 git commit -m "feat!: redesign GitRepoConfig API
 
@@ -161,17 +165,20 @@ Migration guide: docs/migration-v1.md"
 
 ### Error: "GitHub Actions is not permitted to create or approve pull requests"
 
-**Solution:** Enable at org level first (if greyed out), then repo level. See [Prerequisites Setup](#prerequisites-setup) above.
+**Solution:** Enable at org level first (if greyed out), then repo level.
+See [Prerequisites Setup](#prerequisites-setup) above.
 
 ### No Release PR Created
 
 **Check:**
+
 - ✅ CI tests passed (green checkmark in Actions tab)
 - ✅ Commit used conventional format (`feat:`, `fix:`, etc.)
 - ✅ Pushed to `main` branch
 - ✅ GitHub Actions has PR creation permissions
 
 **Retry:**
+
 ```bash
 # Check workflow status
 gh run list --branch main --limit 5
@@ -203,6 +210,7 @@ git push origin main
 ### Wrong Version in Release PR
 
 **Causes:**
+
 - Multiple commit types (most significant wins)
 - `!` or `BREAKING CHANGE:` triggers major bump
 - `.release-please-manifest.json` out of sync
@@ -212,6 +220,7 @@ git push origin main
 ### Docker Build Failed
 
 **Check:**
+
 - Build logs in Actions tab
 - Multi-arch build issues (amd64/arm64)
 - Registry authentication (GITHUB_TOKEN permissions)
@@ -231,15 +240,17 @@ gh run rerun <run-id>
 ### 1. Write Clear Commit Messages
 
 ✅ **Good:**
-```
+
+```bash
 feat(controller): add support for custom branch names
 
 Users can now specify different branch names for different GitRepoConfigs,
 allowing more flexible repository organization.
 ```
 
 ❌ **Bad:**
-```
+
+```bash
 add stuff
 fix bug
 wip
@@ -248,6 +259,7 @@ wip
 ### 2. Use Scopes
 
 Indicate which component is affected:
+
 - `feat(controller): ...`
 - `fix(webhook): ...`
 - `docs(readme): ...`
@@ -264,6 +276,7 @@ git commit -m "test: add multi-repo tests"
 ### 4. Review Release PRs Carefully
 
 Before merging:
+
 - ✅ Verify changelog accuracy
 - ✅ Check version bump is appropriate
 - ✅ Ensure all commits are included
@@ -272,6 +285,7 @@ Before merging:
 ### 5. Coordinate Breaking Changes
 
 For major version bumps:
+
 1. Discuss in an issue first
 2. Add migration guide to `docs/`
 3. Update relevant documentation
@@ -284,13 +298,15 @@ For major version bumps:
 ### Auto-Updated Files
 
 These are automatically updated by release-please:
+
 - `.release-please-manifest.json` - Current version
 - `charts/gitops-reverser/Chart.yaml` - Helm chart versions
 - `CHANGELOG.md` - Auto-generated changelog
 
 ### Configuration Files
 
 Don't modify these without understanding the impact:
+
 - `release-please-config.json` - Semantic versioning rules
 - `.github/workflows/ci.yml` - Validation pipeline (PRs + reused on main)
 - `.github/workflows/release.yml` - Release/publish pipeline (push to main)
@@ -335,4 +351,4 @@ gh release create v0.2.1 \
 1. Check this document first
 2. Review existing Release PRs for examples
 3. Check GitHub Actions logs for errors
-4. Open an issue or discussion if stuck
+4. Open an issue or discussion if stuck

.github/pull_request_template.md

@@ -1,3 +1,5 @@
+# Pull Request
+
 ## Description
 
 Brief description of the changes in this PR.
@@ -42,4 +44,4 @@ Add screenshots to help explain your changes.
 
 ## Additional Notes
 
-Any additional information that reviewers should know.
+Any additional information that reviewers should know.

AGENTS.md

@@ -37,16 +37,18 @@ workflow or Dockerfile change is covered by the normal lint gate; you can also r
 `golangci-lint` all ship in the devcontainer image.
 
 It also runs the documentation checks via `task lint-docs`, which is three tasks:
-`lint-doc-links` (`hack/doccheck`, every tracked file), `lint-markdown` (markdownlint-cli2),
-and `lint-prose` (Vale, against [`docs/style-guide.md`](./docs/style-guide.md)). Structure and
-prose gate only the files [`.docs-lint-scope`](./.docs-lint-scope) lists, so editing an unlisted
-document fails nothing; run `markdownlint-cli2` and `vale` on what you touch anyway.
+`lint-doc-links` (`hack/doccheck`, every tracked file), `lint-markdown` (markdownlint-cli2,
+every tracked file), and `lint-prose` (Vale, against
+[`docs/style-guide.md`](./docs/style-guide.md)). Only prose gates a subset — the files
+[`.docs-lint-scope`](./.docs-lint-scope) lists — so editing an unlisted document fails no prose
+check; run `vale` on what you touch anyway.
 `task lint-markdown-fix` applies the mechanical half. Both tools ship in the devcontainer image.
 See [Documentation checks](./CONTRIBUTING.md#documentation-checks).
 
 ## PRE-IMPLEMENTATION BEHAVIOR
 
-1. **Check Docker availability for e2e tests**: Before running `task test-e2e`, verify Docker is running with `docker info` or ask user to start Docker daemon if needed
+1. **Check Docker availability for e2e tests**: Before running `task test-e2e`, verify Docker is
+   running with `docker info` or ask user to start Docker daemon if needed
 2. **Always read project context first**: Use `read_file` to understand existing patterns in target directories
 3. **Search for similar implementations**: Use `search_files` to find existing patterns before writing new code
 4. **Follow established architecture**: Maintain consistency with `internal/` directory structure
@@ -62,17 +64,20 @@ See [Documentation checks](./CONTRIBUTING.md#documentation-checks).
 ## COMPONENT-SPECIFIC RULES
 
 ### Controller Code (`internal/controller/`)
+
 - Follow kubebuilder patterns and annotations
 - Implement idempotent reconciliation logic
 - Add appropriate RBAC markers
 - Handle finalizers for cleanup
 
 ### Webhook Code (`internal/webhook/`)
+
 - Implement admission webhook interface correctly
 - Add proper validation/mutation logic
 - Update webhook configuration in `config/webhook/`
 
 ### API Changes (`api/v1alpha3/`)
+
 - Add kubebuilder validation tags
 - Include JSON tags and field descriptions
 - Run `task manifests` to update CRDs
@@ -91,12 +96,14 @@ See [Documentation checks](./CONTRIBUTING.md#documentation-checks).
   then compare against `config/crd/bases` with every `description` key stripped from both.
 
 ### Git Operations (`internal/git/`)
+
 - Handle Git errors gracefully
 - Implement proper conflict resolution
 - Add race condition protection
 - Use temporary directories for testing
 
 ### CI Workflows (`.github/workflows/`)
+
 - After editing any workflow, run `task lint-actions` to catch errors with
   `actionlint` before pushing
 - A workflow-only change still counts as a CI/config change, so it is **not**

CONTRIBUTING.md

@@ -159,26 +159,26 @@ overlaps with the others:
 | `task lint-prose` | Vale | English against [`docs/style-guide.md`](docs/style-guide.md): em dashes, American spelling, product names, words to cut. |
 
 ```bash
-task lint-docs                     # all three, on the gated files
-task lint-markdown-fix             # apply the safe mechanical fixes
-task lint-markdown DOCS_SCOPE=all  # the whole tree, to see the backlog
+task lint-docs                  # links and structure everywhere; prose on the gated files
+task lint-markdown-fix          # apply the safe mechanical fixes
+task lint-prose DOCS_SCOPE=all  # the whole tree, to see the prose backlog
 ```
 
-**Structure and prose are gated on the files [`.docs-lint-scope`](.docs-lint-scope) lists, not the
-whole tree.** That is a rollout position: 102 of 174 files fail markdownlint and 148 of 174 fail
-Vale, almost all of the latter on em dashes, and [`docs/style-guide.md`](docs/style-guide.md) says
-that cleanup must not land as one sweeping commit. The gate starts small and the list grows.
+**Links and structure are checked on every tracked file; only prose is gated on the files
+[`.docs-lint-scope`](.docs-lint-scope) lists.** Structure was staged the same way until the residue
+was cleared, so markdownlint now gates the whole tree and a new document cannot regress it. Vale
+still cannot: 145 of the 167 linted files carry at least one error, almost all of them em dashes,
+and [`docs/style-guide.md`](docs/style-guide.md) says that cleanup must not land as one sweeping
+commit. That gate stays small and the list grows.
 
-**To add a file to the gate**, clean it and add its path to that file:
+**To add a file to the prose gate**, clean it and add its path to that file:
 
 ```bash
-markdownlint-cli2 docs/some-file.md   # what it would cost
-vale docs/some-file.md
-task lint-markdown-fix DOCS_SCOPE=all # the mechanical half, whole tree
+vale docs/some-file.md   # what it would cost
 ```
 
-Editing a doc that is not on the list is not blocked, so an unlisted file can still drift. Run the
-two commands above on anything you touch even when nothing forces you to.
+Editing a doc that is not on the list still passes prose, so an unlisted file can drift. Run `vale`
+on anything you touch even when nothing forces you to.
 
 **Reference checking is not staged this way.** `task lint-doc-links` always covers every tracked
 markdown, Go, YAML, and shell file, so a moved document breaks the build wherever it is cited.