psyclaw 0.27.22 → 0.28.0

package/vendor/ars/scripts/test_check_version_consistency.py

@@ -0,0 +1,1462 @@
+"""Unit tests for check_version_consistency.py."""
+from __future__ import annotations
+
+import subprocess
+import textwrap
+import unittest
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from tests.test_helpers import run_script
+
+SCRIPT = Path(__file__).resolve().parent / "check_version_consistency.py"
+
+
+def _run(root: Path) -> subprocess.CompletedProcess:
+    return run_script(SCRIPT, "--path", str(root))
+
+
+def _write_skill(root: Path, name: str, version: str) -> None:
+    skill_dir = root / name
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    (skill_dir / "SKILL.md").write_text(
+        textwrap.dedent(
+            f"""\
+            ---
+            name: {name}
+            description: "fixture"
+            metadata:
+              version: "{version}"
+              last_updated: "2026-04-22"
+              status: active
+              data_access_level: raw
+              task_type: open-ended
+            ---
+
+            # {name}
+            """
+        ),
+        encoding="utf-8",
+    )
+
+
+def _write_claude_md(
+    root: Path,
+    suite_version: str,
+    table_rows: list[tuple[str, str]],
+    last_updated: str | None = "2026-04-22",
+    key_additions: str | None = "derive",
+) -> None:
+    """`last_updated` / `key_additions` default to values aligned with the
+    fixture CHANGELOG (invariants 10 + 11). `key_additions="derive"` writes a
+    `## v<major>.<minor> Key Additions` heading derived from `suite_version`;
+    pass an explicit token (e.g. "v3.4") to drift it, or None to omit."""
+    claude_dir = root / ".claude"
+    claude_dir.mkdir(parents=True, exist_ok=True)
+    rows = "\n".join(
+        f"| `{name}` v{ver} | purpose | modes |" for name, ver in table_rows
+    )
+    if key_additions == "derive":
+        parts = suite_version.split(".")
+        if len(parts) >= 2 and all(p.isdigit() for p in parts[:2]):
+            key_additions = f"v{parts[0]}.{parts[1]}"
+        else:
+            key_additions = None
+    key_additions_block = (
+        f"## {key_additions} Key Additions (fixture)\n\n- fixture addition\n\n"
+        if key_additions is not None
+        else ""
+    )
+    last_updated_line = (
+        f"- **Last Updated**: {last_updated}\n" if last_updated is not None else ""
+    )
+    text = (
+        "# Academic Research Skills\n"
+        "\n"
+        "## Skills Overview\n"
+        "\n"
+        "| Skill | Purpose | Key Modes |\n"
+        "|-------|---------|-----------|\n"
+        f"{rows}\n"
+        "\n"
+        f"{key_additions_block}"
+        "## Version Info\n"
+        f"- **Suite version**: {suite_version} (per CHANGELOG.md)\n"
+        f"{last_updated_line}"
+    )
+    (claude_dir / "CLAUDE.md").write_text(text, encoding="utf-8")
+
+
+def _write_changelog(
+    root: Path,
+    latest_version: str,
+    prior_versions: list[str] | None = None,
+    latest_body: str | None = None,
+    latest_date: str = "2026-04-22",
+) -> None:
+    """Write fixture CHANGELOG with `latest_version` first, then any `prior_versions`.
+
+    The default latest-entry body is long enough to satisfy the >=100-char
+    release-notes invariant (9); pass a short `latest_body` to drift it."""
+    if latest_body is None:
+        latest_body = (
+            "### Added\n"
+            "- fixture entry with enough substantive body text that the latest "
+            "release entry clears the one-hundred-character release-notes "
+            "minimum enforced by invariant 9\n"
+        )
+    entries = [f"## [{latest_version}] - {latest_date}\n\n{latest_body}"]
+    for prev in prior_versions or []:
+        entries.append(f"## [{prev}] - 2026-04-15\n\n### Added\n- prior fixture entry\n")
+    (root / "CHANGELOG.md").write_text(
+        "# Changelog\n\n" + "\n".join(entries),
+        encoding="utf-8",
+    )
+
+
+def _write_plugin_manifests(
+    root: Path, version: str, description: str | None = None
+) -> None:
+    """Fixture .claude-plugin/{plugin,marketplace}.json at `version` (invariant 4).
+    `description` (when given) lands in plugin.json for the invariant-8
+    "N-agent" claim tests."""
+    import json
+    plugin_dir = root / ".claude-plugin"
+    plugin_dir.mkdir(parents=True, exist_ok=True)
+    plugin_obj: dict[str, str] = {"name": "fixture", "version": version}
+    if description is not None:
+        plugin_obj["description"] = description
+    (plugin_dir / "plugin.json").write_text(
+        json.dumps(plugin_obj), encoding="utf-8"
+    )
+    (plugin_dir / "marketplace.json").write_text(
+        json.dumps({"name": "fixture", "plugins": [{"name": "fixture", "version": version}]}),
+        encoding="utf-8",
+    )
+
+
+def _write_readme(root: Path, badge_version: str) -> None:
+    """Fixture README.md with a shields.io version badge (invariant 5).
+
+    The badge encodes the version twice (label + release-tag URL); the lint
+    keys off the `badge/version-vX.Y.Z` label, the canonical surface a user
+    sees. Both are written aligned here so drift tests mutate one explicitly.
+    """
+    (root / "README.md").write_text(
+        "# Academic Research Skills for Claude Code\n"
+        "\n"
+        f"[![Version](https://img.shields.io/badge/version-v{badge_version}-blue)]"
+        f"(https://github.com/x/y/releases/tag/v{badge_version})\n",
+        encoding="utf-8",
+    )
+
+
+def _write_docs(
+    root: Path,
+    en_h2: list[str],
+    zh_h2: list[str] | None = None,
+    extra_version_strings: list[str] | None = None,
+) -> None:
+    """Fixture docs/ tree (invariants 6 + 7).
+
+    `en_h2` / `zh_h2` are H2 heading texts (without the leading '## ').
+    Version-bearing headings like 'Foo (v3.6.4+)' exercise the en<->zh-TW
+    heading-pairing invariant; plain headings are ignored by it. Any
+    `extra_version_strings` are dropped into PERFORMANCE.md body to exercise
+    the 'docs must not cite a future/unknown version' invariant.
+    """
+    docs = root / "docs"
+    docs.mkdir(parents=True, exist_ok=True)
+    en_body = "\n".join(f"## {h}\n\nbody\n" for h in en_h2)
+    if extra_version_strings:
+        en_body += "\n" + "\n".join(f"See v{v} for details.\n" for v in extra_version_strings)
+    (docs / "PERFORMANCE.md").write_text("# Performance\n\n" + en_body, encoding="utf-8")
+    if zh_h2 is not None:
+        zh_body = "\n".join(f"## {h}\n\n內文\n" for h in zh_h2)
+        (docs / "PERFORMANCE.zh-TW.md").write_text("# 效能\n\n" + zh_body, encoding="utf-8")
+
+
+def _write_cff(
+    root: Path, version: str, date_released: str = "2026-04-22"
+) -> None:
+    """Fixture CITATION.cff at `version` (invariant 12). The default
+    date-released matches the fixture CHANGELOG's latest-entry date so the
+    ±7-day window passes unless a test drifts it."""
+    (root / "CITATION.cff").write_text(
+        textwrap.dedent(
+            f"""\
+            cff-version: 1.2.0
+            title: fixture
+            type: software
+            version: {version}
+            date-released: {date_released}
+            """
+        ),
+        encoding="utf-8",
+    )
+
+
+def _write_positioning(root: Path, version: str) -> None:
+    """Fixture POSITIONING.md citation prose at `version` (invariant 12)."""
+    (root / "POSITIONING.md").write_text(
+        "# Positioning\n\n"
+        "Wu, C.-I. (2026). Fixture Suite "
+        f"(Version {version}) [Computer software]. Zenodo.\n",
+        encoding="utf-8",
+    )
+
+
+def _write_aligned_fixture(
+    root: Path,
+    last_updated: str | None = "2026-04-22",
+    key_additions: str | None = "derive",
+) -> None:
+    """Everything lines up — baseline for PASS cases and drift mutations.
+
+    `last_updated` / `key_additions` pass straight through to `_write_claude_md`
+    so invariant-10 / invariant-11 tests can drift a single field without
+    re-specifying the aligned skill table (which would duplicate the very
+    drift this lint exists to catch)."""
+    skills = [
+        ("deep-research", "2.9.0"),
+        ("academic-paper", "3.1.0"),
+        ("academic-paper-reviewer", "1.8.1"),
+        ("academic-pipeline", "3.5.0"),
+    ]
+    for name, ver in skills:
+        _write_skill(root, name, ver)
+    _write_claude_md(
+        root,
+        suite_version="3.5.0",
+        table_rows=skills,
+        last_updated=last_updated,
+        key_additions=key_additions,
+    )
+    _write_changelog(root, latest_version="3.5.0")
+    _write_plugin_manifests(root, "3.5.0")
+    _write_readme(root, "3.5.0")
+    _write_cff(root, "3.5.0")
+    _write_positioning(root, "3.5.0")
+    # en has an extra plain H2 (translation asymmetry is allowed); the
+    # version-bearing heading is present in both and at a past version.
+    _write_docs(
+        root,
+        en_h2=["Token usage", "Corpus ingestion (v3.4.0+)", "Extra EN-only section"],
+        zh_h2=["Token 用量", "語料庫導入 (v3.4.0+)"],
+        extra_version_strings=["3.4.0"],
+    )
+
+
+def _write_aligned_fixture_v351(root: Path) -> None:
+    """v3.5.1 suite: deep-research 2.9.1, academic-pipeline 3.5.1."""
+    skills = [
+        ("deep-research", "2.9.1"),
+        ("academic-paper", "3.1.0"),
+        ("academic-paper-reviewer", "1.8.1"),
+        ("academic-pipeline", "3.5.1"),
+    ]
+    for name, ver in skills:
+        _write_skill(root, name, ver)
+    _write_claude_md(root, suite_version="3.5.1", table_rows=skills)
+    _write_changelog(root, latest_version="3.5.1")
+    _write_plugin_manifests(root, "3.5.1")
+    _write_readme(root, "3.5.1")
+    _write_cff(root, "3.5.1")
+    _write_positioning(root, "3.5.1")
+    _write_docs(
+        root,
+        en_h2=["Token usage", "Corpus ingestion (v3.4.0+)"],
+        zh_h2=["Token 用量", "語料庫導入 (v3.4.0+)"],
+        extra_version_strings=["3.4.0", "3.5.1"],
+    )
+
+
+class TestVersionConsistency(unittest.TestCase):
+    def test_all_aligned_passes(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+    def test_all_aligned_v351_passes(self) -> None:
+        """v3.5.1 suite (deep-research 2.9.1, academic-pipeline 3.5.1) must pass."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture_v351(root)
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+    def test_table_version_drift_fails(self) -> None:
+        """Table lists deep-research v2.9.0 but SKILL.md says 2.8.0 — must fail."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_skill(root, "deep-research", "2.8.0")
+            result = _run(root)
+            self.assertEqual(result.returncode, 1)
+            self.assertIn("deep-research", result.stdout)
+            self.assertIn("2.9.0", result.stdout)
+            self.assertIn("2.8.0", result.stdout)
+
+    def test_suite_version_vs_changelog_drift_fails(self) -> None:
+        """CLAUDE.md suite version != CHANGELOG latest entry — must fail."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_changelog(root, latest_version="3.4.0")
+            result = _run(root)
+            self.assertEqual(result.returncode, 1)
+            self.assertIn("3.5.0", result.stdout)
+            self.assertIn("3.4.0", result.stdout)
+            self.assertIn("CHANGELOG", result.stdout)
+
+    def test_plugin_json_version_drift_fails(self) -> None:
+        """Invariant 4: .claude-plugin/plugin.json version != suite — must fail.
+        (Regression for the v3.10.0 release miss: plugin.json sat at the prior
+        version because no lint covered it.)"""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)  # suite 3.5.0
+            _write_plugin_manifests(root, "3.4.0")  # drift both manifests down
+            result = _run(root)
+            self.assertEqual(result.returncode, 1)
+            self.assertIn("plugin.json", result.stdout)
+            self.assertIn("3.4.0", result.stdout)
+            self.assertIn("3.5.0", result.stdout)
+
+    def test_marketplace_version_drift_fails(self) -> None:
+        """Invariant 4: marketplace.json plugins[].version != suite — must fail.
+        (Regression for marketplace.json silently sitting at 3.7.0 for releases.)"""
+        import json
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)  # suite 3.5.0; plugin.json aligned at 3.5.0
+            # Drift ONLY marketplace, leaving plugin.json correct, to isolate it.
+            (root / ".claude-plugin" / "marketplace.json").write_text(
+                json.dumps({"name": "fixture",
+                            "plugins": [{"name": "fixture", "version": "3.7.0"}]}),
+                encoding="utf-8",
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1)
+            self.assertIn("marketplace.json", result.stdout)
+            self.assertIn("3.7.0", result.stdout)
+
+    def test_pipeline_version_vs_suite_drift_fails(self) -> None:
+        """academic-pipeline version in table must equal suite version."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            # Drop pipeline to 3.4.0 in both table and SKILL.md, keep suite at 3.5.0.
+            # This isolates invariant 3 (pipeline tracks suite) from invariant 1
+            # (SKILL.md == table).
+            _write_skill(root, "academic-pipeline", "3.4.0")
+            _write_claude_md(
+                root,
+                suite_version="3.5.0",
+                table_rows=[
+                    ("deep-research", "2.9.0"),
+                    ("academic-paper", "3.1.0"),
+                    ("academic-paper-reviewer", "1.8.1"),
+                    ("academic-pipeline", "3.4.0"),
+                ],
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1)
+            self.assertIn("academic-pipeline", result.stdout)
+
+    def test_skill_missing_frontmatter_fails(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "deep-research" / "SKILL.md").write_text(
+                "# deep-research\n\nNo frontmatter here.\n",
+                encoding="utf-8",
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1)
+            self.assertIn("deep-research", result.stdout)
+
+    def test_skill_listed_in_table_but_missing_on_disk_fails(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            import shutil
+            shutil.rmtree(root / "academic-paper-reviewer")
+            result = _run(root)
+            self.assertEqual(result.returncode, 1)
+            self.assertIn("academic-paper-reviewer", result.stdout)
+
+    def test_missing_suite_version_in_claude_md_fails(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / ".claude" / "CLAUDE.md").write_text(
+                textwrap.dedent(
+                    """\
+                    # Academic Research Skills
+
+                    ## Skills Overview
+
+                    | Skill | Purpose | Key Modes |
+                    |-------|---------|-----------|
+                    | `deep-research` v2.9.0 | x | y |
+                    | `academic-paper` v3.1.0 | x | y |
+                    | `academic-paper-reviewer` v1.8.1 | x | y |
+                    | `academic-pipeline` v3.5.0 | x | y |
+
+                    ## Version Info
+                    - No suite version line here.
+                    """
+                ),
+                encoding="utf-8",
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1)
+            self.assertIn("Suite version", result.stdout)
+
+    def test_four_segment_suite_vs_changelog_drift_fails(self) -> None:
+        """Regression for #169: 4-segment hotfix versions (e.g. 3.9.4.1 vs 3.9.4.2)
+        must not be silently parsed as a shared 3-segment prefix.
+
+        Scenario: suite claims v3.9.4.2 but CHANGELOG's latest entry is v3.9.4.1.
+        Pre-fix behavior: both got truncated to "3.9.4" and the lint passed silently.
+        """
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            skills = [
+                ("deep-research", "2.9.4"),
+                ("academic-paper", "3.1.2"),
+                ("academic-paper-reviewer", "1.9.1"),
+                ("academic-pipeline", "3.9.4.2"),
+            ]
+            for name, ver in skills:
+                _write_skill(root, name, ver)
+            _write_claude_md(root, suite_version="3.9.4.2", table_rows=skills)
+            # Include the 3-segment ancestor so the pre-fix regex would still find
+            # *something* and silently report a passing 3.9.4 == 3.9.4 comparison.
+            _write_changelog(
+                root, latest_version="3.9.4.1", prior_versions=["3.9.4"],
+            )
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 1,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+            self.assertIn("3.9.4.2", result.stdout)
+            self.assertIn("3.9.4.1", result.stdout)
+            self.assertIn("CHANGELOG", result.stdout)
+
+    def test_five_segment_changelog_does_not_silently_fall_through(self) -> None:
+        """Regression for dual-track review of #169: an N+1 segment latest
+        entry (e.g. 3.9.4.2.1) must not silently skip to the next valid
+        3-or-4 segment predecessor. Pre-fix CHANGELOG_ENTRY_RE failed on
+        the 5-segment heading and `re.search` fell through to a predecessor;
+        if that predecessor happened to equal the suite version, the lint
+        reported PASS even though the actual latest release was a different
+        version."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            skills = [
+                ("deep-research", "2.9.4"),
+                ("academic-paper", "3.1.2"),
+                ("academic-paper-reviewer", "1.9.1"),
+                ("academic-pipeline", "3.9.4.2"),
+            ]
+            for name, ver in skills:
+                _write_skill(root, name, ver)
+            _write_claude_md(root, suite_version="3.9.4.2", table_rows=skills)
+            _write_changelog(
+                root, latest_version="3.9.4.2.1", prior_versions=["3.9.4.2"],
+            )
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 1,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+            self.assertIn("3.9.4.2.1", result.stdout)
+            # Either path is acceptable surfacing: either the suite-vs-CHANGELOG
+            # mismatch (if the new 5-seg token is itself accepted as canonical
+            # under the broadened validator) or an invalid-token report.
+            self.assertTrue(
+                "does not match CHANGELOG latest entry" in result.stdout
+                or "canonical" in result.stdout,
+                msg=f"expected either drift or invalid-token surface: {result.stdout!r}",
+            )
+
+    def test_invalid_table_row_token_is_reported(self) -> None:
+        """Regression for dual-track review of #169: a table row carrying a
+        non-canonical version token (e.g. v3.9.4.2-alpha or v3.9.4.2.1) must
+        surface as an error. Pre-fix: TABLE_ROW_RE failed and the row silently
+        vanished from table_versions, so invariant 3 (pipeline tracks suite)
+        was skipped because `pipeline_in_table` ended up None."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            skills_on_disk = [
+                ("deep-research", "2.9.4"),
+                ("academic-paper", "3.1.2"),
+                ("academic-paper-reviewer", "1.9.1"),
+                ("academic-pipeline", "3.9.4.2"),
+            ]
+            for name, ver in skills_on_disk:
+                _write_skill(root, name, ver)
+            table_rows_with_junk = [
+                ("deep-research", "2.9.4"),
+                ("academic-paper", "3.1.2"),
+                ("academic-paper-reviewer", "1.9.1"),
+                ("academic-pipeline", "3.9.4.2-alpha"),  # invalid token
+            ]
+            _write_claude_md(
+                root, suite_version="3.9.4.2", table_rows=table_rows_with_junk
+            )
+            _write_changelog(
+                root, latest_version="3.9.4.2", prior_versions=["3.9.4"],
+            )
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 1,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+            self.assertIn("academic-pipeline", result.stdout)
+            self.assertIn("3.9.4.2-alpha", result.stdout)
+            self.assertIn("canonical", result.stdout)
+
+    def test_invalid_suite_token_is_reported(self) -> None:
+        """Regression for dual-track review of #169: a non-canonical suite
+        version token (e.g. 3.9.4.2-alpha) must surface as an error rather
+        than being partially captured as 3.9.4.2 via prefix match."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            skills = [
+                ("deep-research", "2.9.4"),
+                ("academic-paper", "3.1.2"),
+                ("academic-paper-reviewer", "1.9.1"),
+                ("academic-pipeline", "3.9.4.2"),
+            ]
+            for name, ver in skills:
+                _write_skill(root, name, ver)
+            _write_claude_md(
+                root, suite_version="3.9.4.2-alpha", table_rows=skills
+            )
+            _write_changelog(
+                root, latest_version="3.9.4.2", prior_versions=["3.9.4"],
+            )
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 1,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+            self.assertIn("3.9.4.2-alpha", result.stdout)
+            self.assertIn("canonical", result.stdout)
+
+    def test_four_segment_table_row_drift_fails(self) -> None:
+        """Regression for #169: the Skills table row regex must also see the 4th
+        segment, so a pipeline row v3.9.4.1 vs suite version 3.9.4.2 is caught."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            # Pipeline SKILL.md and CHANGELOG both at 3.9.4.2, but the table row
+            # in CLAUDE.md still says v3.9.4.1 (forgot to bump one place).
+            skills_on_disk = [
+                ("deep-research", "2.9.4"),
+                ("academic-paper", "3.1.2"),
+                ("academic-paper-reviewer", "1.9.1"),
+                ("academic-pipeline", "3.9.4.2"),
+            ]
+            for name, ver in skills_on_disk:
+                _write_skill(root, name, ver)
+            table_rows_drifted = [
+                ("deep-research", "2.9.4"),
+                ("academic-paper", "3.1.2"),
+                ("academic-paper-reviewer", "1.9.1"),
+                ("academic-pipeline", "3.9.4.1"),  # drift inside the 4th segment
+            ]
+            _write_claude_md(
+                root, suite_version="3.9.4.2", table_rows=table_rows_drifted
+            )
+            _write_changelog(
+                root, latest_version="3.9.4.2", prior_versions=["3.9.4"],
+            )
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 1,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+            self.assertIn("academic-pipeline", result.stdout)
+            self.assertIn("3.9.4.1", result.stdout)
+            self.assertIn("3.9.4.2", result.stdout)
+
+    def test_five_segment_token_rejected_as_non_canonical(self) -> None:
+        """Regression for #178: post-ship codex review of PR #173 flagged that
+        SEMVER_STRICT_RE used `{2,}` (3 or more dot segments) with no upper
+        bound, so a 5-segment token like 3.9.4.2.1 passed the canonical check
+        even though the file-level docstrings and #173 design defined canonical
+        as N.N.N or N.N.N.N. If a 5-segment typo were copied consistently to
+        CLAUDE.md, CHANGELOG.md, and the pipeline table, the lint would have
+        passed despite the malformed shape. Cap to {2,3}: 4 segments max."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            # All four sources self-consistent on a 5-segment typo. Pre-fix:
+            # all three regexes captured "3.9.4.2.1" verbatim, _is_strict_semver
+            # returned True (matched {2,} = 3 or more segments), and every
+            # invariant compared two identical strings — lint reported PASS
+            # even though the shape was malformed. Post-fix: SEMVER_STRICT_RE
+            # rejects 5+ segments, so the suite, table row, and CHANGELOG
+            # entry all surface as "canonical" violations.
+            skills_5seg = [
+                ("deep-research", "2.9.4"),
+                ("academic-paper", "3.1.2"),
+                ("academic-paper-reviewer", "1.9.1"),
+                ("academic-pipeline", "3.9.4.2.1"),
+            ]
+            for name, ver in skills_5seg:
+                _write_skill(root, name, ver)
+            _write_claude_md(
+                root, suite_version="3.9.4.2.1", table_rows=skills_5seg
+            )
+            _write_changelog(
+                root, latest_version="3.9.4.2.1", prior_versions=["3.9.4.2"],
+            )
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 1,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+            self.assertIn("3.9.4.2.1", result.stdout)
+            self.assertIn("canonical", result.stdout)
+
+    # ── Invariant 5: README version badge tracks the suite version ──────────
+    def test_readme_badge_drift_fails(self) -> None:
+        """README shields.io version badge drifts below suite version — must fail."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_readme(root, "3.4.0")  # badge stale vs suite 3.5.0
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("README", result.stdout)
+            self.assertIn("3.4.0", result.stdout)
+
+    def test_readme_missing_fails(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "README.md").unlink()
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("README", result.stdout)
+
+    # ── Invariant 6: docs/ must not cite a version above the suite version ──
+    def test_docs_future_version_fails(self) -> None:
+        """docs/ references v9.9.9 (above suite 3.5.0) — must fail."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_docs(
+                root,
+                en_h2=["Token usage", "Corpus ingestion (v3.4.0+)"],
+                zh_h2=["Token 用量", "語料庫導入 (v3.4.0+)"],
+                extra_version_strings=["9.9.9"],  # future / nonexistent
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("9.9.9", result.stdout)
+
+    def test_docs_at_suite_version_passes_inv6(self) -> None:
+        """A docs version string EQUAL to the suite version is allowed (<=)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_docs(
+                root,
+                en_h2=["Token usage", "Corpus ingestion (v3.4.0+)"],
+                zh_h2=["Token 用量", "語料庫導入 (v3.4.0+)"],
+                extra_version_strings=["3.5.0"],  # == suite, must be OK
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 0, msg=f"stdout={result.stdout!r}")
+
+    def test_docs_superpowers_future_version_exempt_inv6(self) -> None:
+        """docs/superpowers/ holds skill specs/plans that intentionally plan the
+        NEXT release; a future version there is exempt (must PASS). A non-aligned
+        future version anywhere ELSE in docs/ still fails — proves the carve-out
+        is scoped to superpowers/, not a blanket disable."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)  # suite 3.5.0
+            sp = root / "docs" / "superpowers" / "plans"
+            sp.mkdir(parents=True, exist_ok=True)
+            (sp / "next-release-plan.md").write_text(
+                "# Plan\n\nBump suite to v9.9.9 in this release.\n", encoding="utf-8"
+            )
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"superpowers/ future ref should be exempt; stdout={result.stdout!r}",
+            )
+            # control: same future token under a published doc path still fails
+            (root / "docs" / "OTHER.md").write_text(
+                "# Other\n\nSee v9.9.9 here.\n", encoding="utf-8"
+            )
+            result2 = _run(root)
+            self.assertEqual(result2.returncode, 1, msg=f"stdout={result2.stdout!r}")
+            self.assertIn("9.9.9", result2.stdout)
+
+    # ── Invariant 7: en<->zh-TW version-bearing H2 + version-string parity ──
+    def test_zhtw_version_bearing_heading_missing_fails(self) -> None:
+        """en has '(v3.4.0+)' heading; zh-TW drops it — must fail."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_docs(
+                root,
+                en_h2=["Token usage", "Corpus ingestion (v3.4.0+)"],
+                zh_h2=["Token 用量", "語料庫導入"],  # version tag dropped
+                extra_version_strings=["3.4.0"],
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("zh-TW", result.stdout)
+
+    def test_zhtw_version_bearing_heading_drift_fails(self) -> None:
+        """en heading says v3.4.0, zh-TW says v3.3.0 — version drift, must fail."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_docs(
+                root,
+                en_h2=["Token usage", "Corpus ingestion (v3.4.0+)"],
+                zh_h2=["Token 用量", "語料庫導入 (v3.3.0+)"],  # drift
+                extra_version_strings=["3.4.0"],
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+
+    def test_zhtw_plain_heading_asymmetry_allowed(self) -> None:
+        """en may have extra PLAIN (no-version) H2 the zh-TW lacks — must pass."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            # aligned fixture already has en-only 'Extra EN-only section'; assert it passes
+            result = _run(root)
+            self.assertEqual(result.returncode, 0, msg=f"stdout={result.stdout!r}")
+
+    def test_docs_two_segment_version_is_skipped(self) -> None:
+        """inv 6 gates only on full N.N.N tokens; a 2-segment `v9.9` in docs is
+        not a release token this lint adjudicates, so it must NOT fail even
+        though 9.9 > suite 3.5.0 (review test-gap)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            docs = root / "docs"
+            (docs / "PERFORMANCE.md").write_text(
+                "# Performance\n\n## Token usage\n\nSee v9.9 milestone.\n"
+                "## Corpus ingestion (v3.4.0+)\n\nbody\n",
+                encoding="utf-8",
+            )
+            (docs / "PERFORMANCE.zh-TW.md").write_text(
+                "# 效能\n\n## Token 用量\n\n看 v9.9 里程碑。\n"
+                "## 語料庫導入 (v3.4.0+)\n\n內文\n",
+                encoding="utf-8",
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 0, msg=f"stdout={result.stdout!r}")
+
+    def test_docs_prerelease_token_is_skipped(self) -> None:
+        """`v3.12.0-alpha` (above suite) must NOT partial-match to 3.12.0 and
+        fail — non-canonical tokens are dropped entirely (review finding)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "docs" / "PERFORMANCE.md").write_text(
+                "# Performance\n\n## Token usage\n\nWork toward v3.12.0-alpha.\n"
+                "## Corpus ingestion (v3.4.0+)\n\nbody\n",
+                encoding="utf-8",
+            )
+            (root / "docs" / "PERFORMANCE.zh-TW.md").write_text(
+                "# 效能\n\n## Token 用量\n\n邁向 v3.12.0-alpha。\n"
+                "## 語料庫導入 (v3.4.0+)\n\n內文\n",
+                encoding="utf-8",
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 0, msg=f"stdout={result.stdout!r}")
+
+    def test_zhtw_no_english_sibling_fails(self) -> None:
+        """A standalone docs/*.zh-TW.md with no .md sibling — must fail (review test-gap)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "docs" / "ORPHAN.zh-TW.md").write_text(
+                "# 孤兒\n\n## 一節 (v3.4.0+)\n\n內文\n", encoding="utf-8"
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("sibling", result.stdout)
+
+    def test_zhtw_duplicate_same_version_heading_drop_fails(self) -> None:
+        """en has TWO H2s tagged v3.4.0; zh-TW translates only one. Multiset
+        comparison must catch the dropped duplicate (review finding; a
+        {version: heading} dict silently collapsed this and passed)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "docs" / "PERFORMANCE.md").write_text(
+                "# Performance\n\n## Feature A (v3.4.0+)\n\nbody\n"
+                "## Feature B (v3.4.0+)\n\nbody\n",
+                encoding="utf-8",
+            )
+            (root / "docs" / "PERFORMANCE.zh-TW.md").write_text(
+                "# 效能\n\n## 功能 A (v3.4.0+)\n\n內文\n",  # only ONE translated
+                encoding="utf-8",
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("3.4.0", result.stdout)
+
+
+class TestAgentCountClaim(unittest.TestCase):
+    """Invariant 8 (#414): plugin.json description "N-agent" claim equals the
+    tree's unique *_agent.md count (symlinks resolved, not double-counted)."""
+
+    @staticmethod
+    def _write_agents(root: Path, names: list[str]) -> None:
+        agents_dir = root / "deep-research" / "agents"
+        agents_dir.mkdir(parents=True, exist_ok=True)
+        for name in names:
+            (agents_dir / f"{name}_agent.md").write_text(
+                f"# {name}\n", encoding="utf-8"
+            )
+
+    def _claim_case(self, description: str) -> "subprocess.CompletedProcess":
+        """Run the lint against a two-agent fixture tree whose plugin.json
+        carries the given description."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_plugin_manifests(root, "3.5.0", description=description)
+            self._write_agents(root, ["alpha", "beta"])
+            return _run(root)
+
+    def test_agent_claim_drift_fails(self) -> None:
+        result = self._claim_case("fixture, 3-agent ensemble, more")
+        self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+        self.assertIn("agent count of 3", result.stdout)
+        self.assertIn("2", result.stdout)
+
+    def test_prompt_roles_claim_drift_fails(self) -> None:
+        """#753: the "N prompt roles" spelling binds to the same tree count
+        as the legacy "N-agent" spelling."""
+        result = self._claim_case("fixture, 3 prompt roles, more")
+        self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+        self.assertIn("agent count of 3", result.stdout)
+
+    def test_prompt_roles_claim_matching_passes(self) -> None:
+        result = self._claim_case("fixture, 2 prompt roles, more")
+        self.assertEqual(
+            result.returncode, 0,
+            msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+        )
+
+    def test_agent_claim_matching_passes(self) -> None:
+        result = self._claim_case("fixture, 2-agent ensemble, more")
+        self.assertEqual(
+            result.returncode, 0,
+            msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+        )
+
+    def test_every_count_token_checked_not_just_first(self) -> None:
+        """#753: finditer semantics — a correct first token cannot shadow a
+        drifted second one."""
+        result = self._claim_case("fixture, 2-agent core, 5 prompt roles")
+        self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+        self.assertIn("agent count of 5", result.stdout)
+
+    def test_agent_claim_symlink_alias_not_double_counted(self) -> None:
+        """Legacy/transition pin: a symlink alias in the plugin-root agents/
+        dir (the pre-#413 pattern) still counts once — the whole root
+        agents/ mirror is excluded from the count regardless of file kind."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_plugin_manifests(
+                root, "3.5.0", description="fixture, 2-agent ensemble, more"
+            )
+            self._write_agents(root, ["alpha", "beta"])
+            link_dir = root / "agents"
+            link_dir.mkdir()
+            (link_dir / "alpha_agent.md").symlink_to(
+                root / "deep-research" / "agents" / "alpha_agent.md"
+            )
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+    def test_agent_claim_materialized_mirror_not_double_counted(self) -> None:
+        """#413: the plugin-root agents/ mirror holds REAL byte-identical
+        copies (symlinks broke Windows checkouts / zip installs), so resolve()
+        no longer dedups them. The mirror dir is excluded from the count —
+        it is an alias surface pinned byte-identical to its deep-research
+        sources by check_agents_mirror_sync.py, never a source of new
+        agents."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_plugin_manifests(
+                root, "3.5.0", description="fixture, 2-agent ensemble, more"
+            )
+            self._write_agents(root, ["alpha", "beta"])
+            mirror_dir = root / "agents"
+            mirror_dir.mkdir()
+            src = root / "deep-research" / "agents" / "alpha_agent.md"
+            (mirror_dir / "alpha_agent.md").write_bytes(src.read_bytes())
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+    def test_no_agent_claim_skips(self) -> None:
+        """A description without an N-agent token is not gated (the claim is
+        optional; only a stated number must be true)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_plugin_manifests(
+                root, "3.5.0", description="fixture without a count claim"
+            )
+            self._write_agents(root, ["alpha", "beta"])
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+
+class TestChangelogBodyLength(unittest.TestCase):
+    """Invariant 9 (#487): the latest CHANGELOG entry's body must be >= 100
+    characters — a bare heading (or a stub line) is not release notes."""
+
+    def test_short_body_fails(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_changelog(root, latest_version="3.5.0", latest_body="- stub\n")
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("body", result.stdout)
+            self.assertIn("100", result.stdout)
+
+    def test_empty_body_fails(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_changelog(root, latest_version="3.5.0", latest_body="\n")
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("body", result.stdout)
+
+    def test_prior_entry_body_not_gated(self) -> None:
+        """Only the LATEST entry is gated — historical entries may be terse."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_changelog(root, latest_version="3.5.0", prior_versions=["3.4.0"])
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+    def test_fenced_h2_inside_body_not_a_terminator(self) -> None:
+        """A '## ' line inside a fenced code block must NOT truncate the body
+        (codex P2-1): the entry body ends at the next RELEASE heading, not any
+        markdown H2. Otherwise a code sample in the release notes false-fails
+        invariant 9."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            body = (
+                "### Added\n\n"
+                "```md\n"
+                "## not a release heading — just a code sample\n"
+                "```\n\n"
+                "Real release notes continue here with more than one hundred "
+                "characters of substantive text so invariant 9 is satisfied by "
+                "the full body, not the truncated fence prefix.\n"
+            )
+            _write_changelog(
+                root, latest_version="3.5.0", latest_body=body,
+                prior_versions=["3.4.0"],
+            )
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+    def test_fenced_bracketed_h2_not_a_terminator(self) -> None:
+        """A fenced '## [example]' — which even LOOKS like a release heading —
+        must not truncate the body either (codex re-review): the body ends at
+        the next real release heading, past any fenced content."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            body = (
+                "### Added\n\n"
+                "```md\n"
+                "## [example] - 2020-01-01 — a code sample, not a real entry\n"
+                "```\n\n"
+                "Real release notes continue here with more than one hundred "
+                "characters of substantive text so invariant 9 is satisfied by "
+                "the full body, not the truncated fence prefix.\n"
+            )
+            _write_changelog(
+                root, latest_version="3.5.0", latest_body=body,
+                prior_versions=["3.4.0"],
+            )
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+
+class TestLastUpdatedFreshness(unittest.TestCase):
+    """Invariant 10 (#487): .claude/CLAUDE.md "Last Updated" must lie within
+    ±7 days of the latest CHANGELOG entry's date (deterministic baseline —
+    re-running the lint later cannot flip the result)."""
+
+    def test_stale_last_updated_fails(self) -> None:
+        """8 days after the CHANGELOG date (2026-04-22) is out of the window."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root, last_updated="2026-04-30")
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("Last Updated", result.stdout)
+
+    def test_boundary_seven_days_passes(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root, last_updated="2026-04-29")
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+    def test_missing_last_updated_fails(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root, last_updated=None)
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("Last Updated", result.stdout)
+
+    def test_changelog_missing_date_fails(self) -> None:
+        """The latest entry carrying no date breaks the freshness baseline."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            # Strip only the date off the aligned CHANGELOG heading, keeping
+            # the compliant body so invariant 9 doesn't also fire.
+            changelog = root / "CHANGELOG.md"
+            changelog.write_text(
+                changelog.read_text(encoding="utf-8").replace(
+                    "## [3.5.0] - 2026-04-22", "## [3.5.0]"
+                ),
+                encoding="utf-8",
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("date", result.stdout)
+
+    def test_impossible_changelog_date_reports_not_crashes(self) -> None:
+        """A syntactically-shaped but impossible CHANGELOG date (2026-02-30)
+        must produce a lint error, never a traceback (codex P2-2)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_changelog(root, latest_version="3.5.0", latest_date="2026-02-30")
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertNotIn("Traceback", result.stderr)
+            self.assertIn("2026-02-30", result.stdout)
+
+    def test_overlong_changelog_date_not_accepted_as_prefix(self) -> None:
+        """A trailing-digit date like 2026-04-222 must NOT be prefix-captured
+        as 2026-04-22 and silently pass freshness (codex re-review P3): it is
+        malformed and must be flagged."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root, last_updated="2026-04-22")
+            _write_changelog(root, latest_version="3.5.0", latest_date="2026-04-222")
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertNotIn("Traceback", result.stderr)
+
+    def test_non_iso_last_updated_reports_not_crashes(self) -> None:
+        """A non-YYYY-MM-DD Last Updated that date.fromisoformat happens to
+        accept (e.g. compact 20260422) must still be flagged as malformed
+        rather than silently passing (codex P2-2)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root, last_updated="20260422")
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("Last Updated", result.stdout)
+
+
+class TestKeyAdditionsAlignment(unittest.TestCase):
+    """Invariant 11 (#487): the newest "## vX.Y… Key Additions" heading in
+    .claude/CLAUDE.md must match the suite version (compared at the heading's
+    own precision, so `## v3.5 Key Additions` matches suite 3.5.0)."""
+
+    def test_key_additions_drift_fails(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root, key_additions="v3.4")
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("Key Additions", result.stdout)
+
+    def test_key_additions_missing_fails(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root, key_additions=None)
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("Key Additions", result.stdout)
+
+    def test_three_segment_heading_match_passes(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root, key_additions="v3.5.0")
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+    def test_older_headings_below_newest_allowed(self) -> None:
+        """Historical Key Additions sections stay put; only the NEWEST (max
+        version) heading is compared against the suite version."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            claude_md = root / ".claude" / "CLAUDE.md"
+            text = claude_md.read_text(encoding="utf-8")
+            text = text.replace(
+                "## Version Info\n",
+                "## v3.4 Key Additions (older, allowed)\n\n- old\n\n## Version Info\n",
+            )
+            claude_md.write_text(text, encoding="utf-8")
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+
+class TestTagMatch(unittest.TestCase):
+    """Tag gate (#487, invariant 1c): `--tag <ref>` must equal the suite
+    version — the one comparison nothing else performs at tag time."""
+
+    def test_matching_tag_passes(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            result = run_script(SCRIPT, "--path", str(root), "--tag", "v3.5.0")
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+    def test_mismatched_tag_fails(self) -> None:
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            result = run_script(SCRIPT, "--path", str(root), "--tag", "v3.6.0")
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("v3.6.0", result.stdout)
+            self.assertIn("3.5.0", result.stdout)
+
+    def test_tag_without_v_prefix_matches(self) -> None:
+        """A bare `3.5.0` ref compares equal — the leading `v` is cosmetic."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            result = run_script(SCRIPT, "--path", str(root), "--tag", "3.5.0")
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+    def test_tag_supplied_but_suite_version_missing_fails(self) -> None:
+        """The tag gate must NOT silently no-op when .claude/CLAUDE.md has no
+        Suite-version line: the whole point of `--tag` is to guarantee the tag
+        is right at tag time, so a garbage tag co-occurring with a broken
+        CLAUDE.md has to be a non-zero exit (both the suite-missing error AND
+        the tag-uncheckable error surface), never a pass."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            claude_md = root / ".claude" / "CLAUDE.md"
+            text = claude_md.read_text(encoding="utf-8")
+            text = text.replace(
+                "- **Suite version**: 3.5.0 (per CHANGELOG.md)\n", ""
+            )
+            claude_md.write_text(text, encoding="utf-8")
+            result = run_script(SCRIPT, "--path", str(root), "--tag", "v9.9.9")
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            # The tag itself must be named as uncheckable — not just the
+            # generic suite-missing error that would fire even without --tag.
+            self.assertIn("v9.9.9", result.stdout)
+
+
+class TestCitationSurfaces(unittest.TestCase):
+    """Invariant 12: CITATION.cff (YAML-parsed, absence errors) and
+    POSITIONING.md citation prose (optional) track the release. The aligned
+    baseline is exercised by every pass-case test via _write_aligned_fixture,
+    which writes both surfaces."""
+
+    def test_cff_drift_fails(self) -> None:
+        """CITATION.cff stuck below the suite version — the #754 drift class."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_cff(root, "3.4.0")
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("CITATION.cff", result.stdout)
+            self.assertIn("3.4.0", result.stdout)
+
+    def test_cff_quoted_version_passes(self) -> None:
+        """`version: "3.5.0"` is a legitimate CFF spelling — YAML parsing must
+        not report the quotes as drift (regression: the first regex-based
+        draft of this invariant did exactly that)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "CITATION.cff").write_text(
+                'cff-version: 1.2.0\ntitle: fixture\ntype: software\n'
+                'version: "3.5.0"\ndate-released: 2026-04-22\n',
+                encoding="utf-8",
+            )
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+    def test_cff_noncanonical_version_fails_as_noncanonical(self) -> None:
+        """A 2-segment `version: 3.5` must be reported as non-canonical, not
+        as a drift mismatch a maintainer would chase with a version bump."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "CITATION.cff").write_text(
+                "cff-version: 1.2.0\ntitle: fixture\ntype: software\n"
+                "version: 3.5\ndate-released: 2026-04-22\n",
+                encoding="utf-8",
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("canonical", result.stdout)
+
+    def test_cff_missing_version_key_fails(self) -> None:
+        """A present CITATION.cff with no version key is malformed — error,
+        never a silent skip. date-released stays valid so this test fails
+        for the missing-version diagnostic specifically, not the
+        missing-date one (codex round-3 P2: conflated fixtures let a
+        missing-version regression hide behind the date error)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "CITATION.cff").write_text(
+                "cff-version: 1.2.0\ntitle: fixture\ntype: software\n"
+                "date-released: 2026-04-22\n",
+                encoding="utf-8",
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("no 'version' key found", result.stdout)
+
+    def test_cff_absent_fails(self) -> None:
+        """CITATION.cff is outward-facing release metadata like README.md —
+        deleting it must not silently disable the invariant."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "CITATION.cff").unlink()
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("CITATION.cff", result.stdout)
+
+    def test_cff_stale_date_released_fails(self) -> None:
+        """date-released more than 7 days from the CHANGELOG latest-entry date
+        — the second half of the #754 drift (version was bumped by hand while
+        the date sat 6 weeks stale)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_cff(root, "3.5.0", date_released="2026-01-01")
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("date-released", result.stdout)
+
+    def test_cff_missing_date_released_fails(self) -> None:
+        """Omitting (or nulling) date-released must error, not silently skip
+        the freshness check — deleting the field must not disable the
+        invariant (codex review round-2 P2; same posture as file absence)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "CITATION.cff").write_text(
+                "cff-version: 1.2.0\ntitle: fixture\ntype: software\n"
+                "version: 3.5.0\n",
+                encoding="utf-8",
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("date-released", result.stdout)
+
+    def test_cff_impossible_date_fails_cleanly(self) -> None:
+        """`date-released: 2026-02-30` — PyYAML's timestamp constructor raises
+        ValueError, not YAMLError; the lint must emit an error, never crash
+        with a traceback (codex review P2)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_cff(root, "3.5.0", date_released="2026-02-30")
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 1,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+            self.assertNotIn("Traceback", result.stderr)
+            self.assertIn("CITATION.cff", result.stdout)
+
+    def test_cff_timestamp_date_fails_as_nonstrict(self) -> None:
+        """An unquoted `2026-04-22T00:00:00Z` parses as datetime — a date
+        SUBCLASS that would TypeError against the date baseline. It must be
+        rejected as not a strict YYYY-MM-DD, never crash (codex review P2)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_cff(root, "3.5.0", date_released="2026-04-22T00:00:00Z")
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 1,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+            self.assertNotIn("Traceback", result.stderr)
+            self.assertIn("strict YYYY-MM-DD", result.stdout)
+
+    def test_cff_date_within_window_passes(self) -> None:
+        """A date-released within the ±7-day window of the CHANGELOG date
+        (fixture CHANGELOG: 2026-04-22) passes."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_cff(root, "3.5.0", date_released="2026-04-25")
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+    def test_positioning_drift_fails(self) -> None:
+        """POSITIONING.md citation prose stuck below the suite version."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            _write_positioning(root, "3.4.0")
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("POSITIONING.md", result.stdout)
+            self.assertIn("3.4.0", result.stdout)
+
+    def test_positioning_vprefixed_token_fails_as_noncanonical(self) -> None:
+        """`(Version v3.5.0)` — the likeliest human edit of the citation line —
+        must error as non-canonical, not slip through a filtering regex (the
+        pre-#169 pattern this file's header warns about)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "POSITIONING.md").write_text(
+                "# Positioning\n\nCite: Fixture Suite (Version v3.5.0).\n",
+                encoding="utf-8",
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("canonical", result.stdout)
+
+    def test_positioning_malformed_clause_still_validated(self) -> None:
+        """`(Version 3.4.0 )` — a stray space must not drop the clause out of
+        the capture and silently pass a stale citation (codex round-3 P2):
+        the payload is captured whole, stripped, then validated."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "POSITIONING.md").write_text(
+                "# Positioning\n\nCite: Fixture Suite (Version 3.4.0 ).\n",
+                encoding="utf-8",
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("3.4.0", result.stdout)
+
+    def test_positioning_empty_payload_fails(self) -> None:
+        """`(Version )` — deleting the version mid-edit must reach strict
+        validation and error, not fall out of the capture (codex round-4
+        P2)."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "POSITIONING.md").write_text(
+                "# Positioning\n\nCite: Fixture Suite (Version ).\n",
+                encoding="utf-8",
+            )
+            result = _run(root)
+            self.assertEqual(result.returncode, 1, msg=f"stdout={result.stdout!r}")
+            self.assertIn("canonical", result.stdout)
+
+    def test_positioning_absent_passes(self) -> None:
+        """POSITIONING.md is repo-specific prose — absence is a skip."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "POSITIONING.md").unlink()
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+    def test_positioning_without_version_token_passes(self) -> None:
+        """A POSITIONING.md with no `(Version X.Y.Z)` token has nothing to
+        check — the token is the claim; no claim, no drift."""
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _write_aligned_fixture(root)
+            (root / "POSITIONING.md").write_text(
+                "# Positioning\n\nNo citation prose here.\n", encoding="utf-8"
+            )
+            result = _run(root)
+            self.assertEqual(
+                result.returncode, 0,
+                msg=f"stdout={result.stdout!r} stderr={result.stderr!r}",
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()