feat(swarm): Wave 2 CI config + Wave 5 Rust splits + version regression guard

.markdownlint.json

@@ -0,0 +1,11 @@
+{
+  "MD013": false,
+  "MD024": false,
+  "MD028": false,
+  "MD033": false,
+  "MD036": false,
+  "MD041": false,
+  "MD047": false,
+  "MD056": false,
+  "MD060": false
+}

.markdownlintignore

@@ -0,0 +1,13 @@
+# Third-party skill reference files (not maintained by this project)
+.agents/skills/*/references/**
+.opencode/**
+.claude/**
+.blackbox/**
+.blackboxcli/**
+
+# Auto-generated / external
+CHANGELOG.md
+cli/ui/node_modules/**
+cli/target/**
+web/node_modules/**
+.cache/**

.pre-commit-config.yaml

@@ -31,15 +31,15 @@ repos:
     rev: v0.10.0.1
     hooks:
       - id: shellcheck
-        args: ['--severity=warning']
+        args: ['--severity=error']
         files: \.(sh|bash)$
 
   # Markdown linting
   - repo: https://github.com/igorshubovych/markdownlint-cli
     rev: v0.39.0
     hooks:
       - id: markdownlint
-        args: ['--config', 'markdownlint.toml']
+        args: ['--config', '.markdownlint.json']
 
   # Type checking
   - repo: https://github.com/pre-commit/mirrors-mypy

AGENTS.md

@@ -3,7 +3,7 @@
 > **Primary Integration Guide** — This file is the main entry point for AI
 > agents and developers integrating the resolver as a skill. For deep
 > technical reference, see **[agents-docs/](agents-docs/README.md)**.
-
+>
 > **do-web-doc-resolver** — resolves queries or URLs into clean Markdown via a
 > provider cascade.
 > Supported by: Claude Code, Windsurf, Gemini CLI, Codex, Copilot, OpenCode,
@@ -39,9 +39,45 @@ readonly MAX_PR_TITLE_LENGTH=72
 
 ## Version Management
 
-This repository uses `pyproject.toml`, `cli/Cargo.toml`, and `web/package.json`
-for versioning.
-Run `./scripts/sync_versions.py` to ensure all versions are in sync.
+This repository uses 4 canonical version files that MUST always be in sync:
+
+| File | Field | Purpose |
+|------|-------|---------|
+| `pyproject.toml` | `[project] version` | **Source of truth** (Python package) |
+| `cli/Cargo.toml` | `[package] version` | Rust crate version |
+| `web/package.json` | `"version"` | NPM package version |
+| `cli/src/cli.rs` | `#[command(version = "...")]` | CLI `--version` output |
+
+### Sync All Version Files
+
+```bash
+python scripts/sync_versions.py           # check only (exit 1 if drift)
+python scripts/sync_versions.py --fix     # auto-fix all 4 targets to pyproject.toml
+python scripts/sync_versions.py --set 1.2.0  # set specific version everywhere
+```
+
+### Release Version Bumping
+
+Use the release script — it calls `sync_versions.py` internally:
+
+```bash
+./scripts/release.sh patch   # 0.3.3 → 0.3.4
+./scripts/release.sh minor   # 0.3.3 → 0.4.0
+./scripts/release.sh major   # 0.3.3 → 1.0.0
+```
+
+### Guard Against Version Regression
+
+CI enforces `validate-version` job on every PR: the manifest version in
+`pyproject.toml` MUST be >= the latest GitHub tag. This prevents old branches
+from overwriting release versions when merged.
+
+**If CI fails with "Version regression detected"**:
+
+```bash
+LATEST_TAG=$(git tag -l "v*.*.*" --sort=-version:refname | head -1)
+python scripts/sync_versions.py --set "${LATEST_TAG#v}"
+```
 
 ## Quality Gate (Required Before Commit)
 
@@ -53,7 +89,7 @@ Run `./scripts/sync_versions.py` to ensure all versions are in sync.
 
 - Python: `pytest -m "not live"`
 - Rust: `cd cli && cargo test`
-- Web: `cd web && npx playwright test --project=desktop`
+- Web: \`cd web && npx playwright test --project=desktop --project=mobile --project=tablet\`
 
 **Guard Rails:**
 
@@ -126,6 +162,7 @@ Run `./scripts/sync_versions.py` to ensure all versions are in sync.
 - Markdown linting passes (`markdownlint`)
 - No new secrets committed (Gitleaks)
 - `AGENTS.md` updated if repository structure or skills change
+- **Version**: `pyproject.toml` version >= latest GitHub tag (enforced by CI)
 
 ## Project Documentation
 

agents-docs/RELEASES.md

@@ -4,41 +4,66 @@ Releases follow [Semantic Versioning](https://semver.org/) with conventional com
 
 ## Version Source Of Truth
 
-The release version is sourced from the package manifests used by `scripts/release.sh`:
+The release version is sourced from `pyproject.toml`.
 
-- `pyproject.toml`
-- `cli/Cargo.toml`
-- `web/package.json`
+There are 4 canonical version files that MUST always be in sync:
 
-If GitHub release tags drift from those package versions, align the next release tag to the manifest versions instead of continuing the stale tag line.
+| File | Field |
+|------|-------|
+| `pyproject.toml` | `[project] version` |
+| `cli/Cargo.toml` | `[package] version` |
+| `web/package.json` | `"version"` |
+| `cli/src/cli.rs` | `#[command(version = "...")]` |
+
+Use `scripts/sync_versions.py` to sync all 4:
+
+```bash
+python scripts/sync_versions.py           # check only
+python scripts/sync_versions.py --fix     # fix all to match pyproject.toml
+python scripts/sync_versions.py --set 1.2.0  # set specific version
+```
+
+**Important**: If GitHub release tags drift from manifest versions, sync manifests TO the tags
+(not the other way around):
+
+```bash
+LATEST_TAG=$(git tag -l "v*.*.*" --sort=-version:refname | head -1)
+python scripts/sync_versions.py --set "${LATEST_TAG#v}"
+```
 
 ## Automated Release Scripts
 
-Use the release script to automate version bumping, changelog generation, and tagging:
+Use the release script to automate version bumping, changelog generation, and tagging.
+It calls `sync_versions.py --set` internally, so all 4 files stay in sync:
 
 ### Patch release (0.1.0 → 0.1.1)
+
 ```bash
 ./scripts/release.sh patch
 ```
 
 ### Minor release (0.1.1 → 0.2.0)
+
 ```bash
 ./scripts/release.sh minor
 ```
 
 ### Major release (0.2.0 → 1.0.0)
+
 ```bash
 ./scripts/release.sh major
 ```
 
 ### Specific version
+
 ```bash
 ./scripts/release.sh 1.2.3
 ```
 
 ## Changelog Generation
 
 Generate a changelog for a specific version:
+
 ```bash
 ./scripts/changelog.sh v0.2.0
 ```
@@ -52,4 +77,23 @@ Generate a changelog for a specific version:
    - Build binaries for Linux, macOS, and Windows.
    - Create a GitHub Release with the generated changelog and assets.
 
+## Version Regression Guard
+
+CI enforces a `validate-version` job on every PR: the manifest version in
+`pyproject.toml` MUST be >= the latest git tag. This prevents old branches
+from overwriting release versions when merged.
+
+If CI fails with "Version regression detected":
+
+```bash
+LATEST_TAG=$(git tag -l "v*.*.*" --sort=-version:refname | head -1)
+python scripts/sync_versions.py --set "${LATEST_TAG#v}"
+```
+
+## History of Version Drift
+
+A previous version regression (PR #270, commit `c283dfa`) merged an old branch
+onto v0.3.3, reverting all 4 manifests back to 0.3.1 and deleting CHANGELOG
+entries. The regression guard prevents this from recurring.
+
 See [`do-wdr-release` skill](.agents/skills/do-wdr-release/SKILL.md) for more details.

cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "do-wdr"
-version = "0.3.1"
+version = "0.3.4"
 edition = "2024"
 rust-version = "1.85"
 description = "Web Documentation Resolver CLI"

cli/src/cli.rs

@@ -8,7 +8,7 @@ use clap::{Parser, Subcommand};
 #[derive(Parser, Debug)]
 #[command(name = "do-wdr")]
 #[command(about = "Web Documentation Resolver - Resolve URLs and queries into documentation", long_about = None)]
-#[command(version = "0.3.1")]
+#[command(version = "0.3.4")]
 pub struct Cli {
     #[command(subcommand)]
     pub command: Commands,