Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

fix(governance): validate inline ADR successors

Seekers200103ca6c39e04a
diff --git a/.agents/skills/docs-governance/scripts/audit-docs.py b/.agents/skills/docs-governance/scripts/audit-docs.py
index 65af06a8d..53f35ee36 100644
--- a/.agents/skills/docs-governance/scripts/audit-docs.py
+++ b/.agents/skills/docs-governance/scripts/audit-docs.py
@@ -38,6 +38,9 @@ ENTRY_RE = re.compile(
CODE_PATH_RE = re.compile(r"`([^`\n]+)`")
TEST_ID_RE = re.compile(r"\bTEST-[A-Z0-9][A-Z0-9-]*\b")
ADR_TARGET_RE = re.compile(r"\b(?:ADR-)?\d{3,4}-[a-z0-9-]+\.md\b", re.IGNORECASE)
+ADR_INLINE_SUCCESSOR_RE = re.compile(
+ r"(?im)^(?:[-*]\s+)?(?:\*\*(?:status|状态)\*\*|(?:status|状态))\s*[::]\s*`?superseded`?\s+by\s+(ADR-\d{3,4})\s*$"
+)
IGNORED_DIRS = {".git", ".governance", ".venv", "node_modules", "vendor", "__pycache__"}
IGNORED_REFERENCE_MARKERS = ("*", "{", "}", "<", ">", "…", "...")
GIT_TIMEOUT_SECONDS = 5
@@ -442,6 +445,16 @@ def parse_adr_status(text: str) -> str | None:
return None
+def inline_adr_successor(text: str) -> str | None:
+ match = ADR_INLINE_SUCCESSOR_RE.search(text)
+ return match.group(1).upper() if match else None
+
+
+def adr_identifier(text: str) -> str | None:
+ match = re.search(r"(?im)^#\s+(ADR-\d{3,4})\b", text)
+ return match.group(1).upper() if match else None
+
+
def indexed_adr_paths(
root: Path, index: Path, index_text: str, report: Report
) -> set[Path]:
@@ -520,6 +533,16 @@ def check_adr_lifecycle(
"ADR status is unsupported: "
f"{diagnostic(path.relative_to(root))} -> {status}"
)
+ successor = inline_adr_successor(text)
+ if successor and successor not in {
+ identifier
+ for source_text in sources.values()
+ if (identifier := adr_identifier(source_text)) is not None
+ }:
+ report.fail(
+ "ADR inline successor does not exist: "
+ f"{diagnostic(path.relative_to(root))} -> {successor}"
+ )
supersedes = re.search(
r"(?ims)^##\s+Supersedes\s*\n(?P<body>.*?)(?:\n## |\Z)", text
)
diff --git a/skills/docs-governance/scripts/audit-docs.py b/skills/docs-governance/scripts/audit-docs.py
index 65af06a8d..53f35ee36 100644
--- a/skills/docs-governance/scripts/audit-docs.py
+++ b/skills/docs-governance/scripts/audit-docs.py
@@ -38,6 +38,9 @@ ENTRY_RE = re.compile(
CODE_PATH_RE = re.compile(r"`([^`\n]+)`")
TEST_ID_RE = re.compile(r"\bTEST-[A-Z0-9][A-Z0-9-]*\b")
ADR_TARGET_RE = re.compile(r"\b(?:ADR-)?\d{3,4}-[a-z0-9-]+\.md\b", re.IGNORECASE)
+ADR_INLINE_SUCCESSOR_RE = re.compile(
+ r"(?im)^(?:[-*]\s+)?(?:\*\*(?:status|状态)\*\*|(?:status|状态))\s*[::]\s*`?superseded`?\s+by\s+(ADR-\d{3,4})\s*$"
+)
IGNORED_DIRS = {".git", ".governance", ".venv", "node_modules", "vendor", "__pycache__"}
IGNORED_REFERENCE_MARKERS = ("*", "{", "}", "<", ">", "…", "...")
GIT_TIMEOUT_SECONDS = 5
@@ -442,6 +445,16 @@ def parse_adr_status(text: str) -> str | None:
return None
+def inline_adr_successor(text: str) -> str | None:
+ match = ADR_INLINE_SUCCESSOR_RE.search(text)
+ return match.group(1).upper() if match else None
+
+
+def adr_identifier(text: str) -> str | None:
+ match = re.search(r"(?im)^#\s+(ADR-\d{3,4})\b", text)
+ return match.group(1).upper() if match else None
+
+
def indexed_adr_paths(
root: Path, index: Path, index_text: str, report: Report
) -> set[Path]:
@@ -520,6 +533,16 @@ def check_adr_lifecycle(
"ADR status is unsupported: "
f"{diagnostic(path.relative_to(root))} -> {status}"
)
+ successor = inline_adr_successor(text)
+ if successor and successor not in {
+ identifier
+ for source_text in sources.values()
+ if (identifier := adr_identifier(source_text)) is not None
+ }:
+ report.fail(
+ "ADR inline successor does not exist: "
+ f"{diagnostic(path.relative_to(root))} -> {successor}"
+ )
supersedes = re.search(
r"(?ims)^##\s+Supersedes\s*\n(?P<body>.*?)(?:\n## |\Z)", text
)
diff --git a/tests/test_docs_governance_audit.py b/tests/test_docs_governance_audit.py
index f3b067ad3..72daa2688 100644
--- a/tests/test_docs_governance_audit.py
+++ b/tests/test_docs_governance_audit.py
@@ -374,15 +374,32 @@ def test_adr_scope_accepts_superseded_status_with_successor(project: Path) -> No
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)
(adr_dir / "README.md").write_text(
- "[decision](0001-storage.md)\n", encoding="utf-8"
+ "[old](0001-storage.md)\n[new](0002-storage.md)\n", encoding="utf-8"
)
(adr_dir / "0001-storage.md").write_text(
"# ADR-0001\n\n**Status**: superseded by ADR-0002\n", encoding="utf-8"
)
+ (adr_dir / "0002-storage.md").write_text(
+ "# ADR-0002\n\n**Status**: accepted\n", encoding="utf-8"
+ )
result = run_audit(project, "adr")
assert result.returncode == 0, result.stdout
+def test_adr_scope_rejects_missing_inline_superseded_successor(project: Path) -> None:
+ adr_dir = project / "docs" / "adr"
+ adr_dir.mkdir(parents=True)
+ (adr_dir / "README.md").write_text(
+ "[decision](0001-storage.md)\n", encoding="utf-8"
+ )
+ (adr_dir / "0001-storage.md").write_text(
+ "# ADR-0001\n\n**Status**: superseded by ADR-9999\n", encoding="utf-8"
+ )
+ result = run_audit(project, "adr")
+ assert result.returncode == 1
+ assert "ADR inline successor does not exist" in result.stdout
+
+
def test_adr_scope_audits_common_adr_prefixed_filenames(project: Path) -> None:
adr_dir = project / "docs" / "adr"
adr_dir.mkdir(parents=True)