The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix(pi): classify documentation governance
Seekers2001e2b32713d5f5
diff --git a/docs/tr/AGENTS.md b/docs/tr/AGENTS.mdindex 53e74b8f1..6ccccc4d4 100644--- a/docs/tr/AGENTS.md+++ b/docs/tr/AGENTS.md@@ -1,6 +1,6 @@# Everything Claude Code (ECC) — Agent Talimatları-Bu, yazılım geliştirme için 68 özel agent, 293 skill, 94 command ve otomatik hook iş akışları sağlayan **üretime hazır bir AI kodlama eklentisidir**.+Bu, yazılım geliştirme için 68 özel agent, 294 skill, 94 command ve otomatik hook iş akışları sağlayan **üretime hazır bir AI kodlama eklentisidir**.**Sürüm:** 2.2.2@@ -142,7 +142,7 @@ Başarısızlık sorunlarını giderin: test izolasyonunu kontrol edin → mockl```agents/ — 68 özel subagent-skills/ — 293 iş akışı skillleri ve alan bilgisi+skills/ — 294 iş akışı skillleri ve alan bilgisicommands/ — 94 slash commandhooks/ — Tetikleyici tabanlı otomasyonlarrules/ — Her zaman uyulması gereken kurallar (ortak + dile özel)diff --git a/manifests/pi-core.json b/manifests/pi-core.jsonindex cb0f09dc2..16042c624 100644--- a/manifests/pi-core.json+++ b/manifests/pi-core.json@@ -76,6 +76,7 @@"django-tdd","django-verification","docker-patterns",+ "docs-governance","dotnet-patterns","e2e-testing","error-handling",diff --git a/pi/core/CURATION.md b/pi/core/CURATION.mdindex df1345897..c394c23f2 100644--- a/pi/core/CURATION.md+++ b/pi/core/CURATION.md@@ -1,6 +1,6 @@# Curation-pi/core includes 123 of 293 skills and 24 of 94 commands from the root of ECC.+pi/core includes 124 of 294 skills and 24 of 94 commands from the root of ECC.Everything excluded is listed here with its reason.## Rulesdiff --git a/pi/core/README.md b/pi/core/README.mdindex f3df41414..d487d3df6 100644--- a/pi/core/README.md+++ b/pi/core/README.md@@ -1,6 +1,6 @@# ecc-pi-core-A curated, Pi-native profile of ECC (Everything Claude Code): 123 portable+A curated, Pi-native profile of ECC (Everything Claude Code): 124 portableengineering skills and 24 pure prompt-workflow commands, with no extensions,no hooks, no runtime downloads, and no network or SaaS dependencies.diff --git a/pi/core/skills/docs-governance/SKILL.md b/pi/core/skills/docs-governance/SKILL.mdnew file mode 100644index 000000000..df3bf8c04--- /dev/null+++ b/pi/core/skills/docs-governance/SKILL.md@@ -0,0 +1,97 @@+---+name: docs-governance+description: Route broad documentation-governance requests to existing ECC skills and run an opt-in, read-only audit of mapped documentation roles, links, ADR indexes, and evidence references. Use when a user asks for documentation governance, project-knowledge organization, documentation integrity, or a deterministic docs audit without naming a narrower skill.+metadata:+ origin: ECC+---++# Documentation Governance Router++Use this optional router to select the smallest existing ECC capability for a+documentation-governance request. The router does not create a parallel project+management system and does not make documentation authoritative over code,+tests, Issues, or maintainer decisions.++## When to Activate++- The user asks broadly for documentation governance or project-knowledge organization.+- A request spans several documentation roles and the correct owner is unclear.+- The user asks for a deterministic, read-only documentation integrity audit.+- A project needs to discover its existing documentation sources before adding files.++Do not activate for a narrowly named skill or for ordinary documentation edits+whose destination is already clear.++## Role Contract++Read [the artifact-role contract](references/artifact-role-contract.md) before+interpreting `.governance/docs-map.json` or default filenames. Logical roles own+facts; filenames are fallbacks. Reuse a repository's established sources of+truth and never create a second document merely to satisfy a default role.++## Intent Routing++| User intent | Route to |+|---|---|+| Adopt or maintain a constitution, map, status, and history spine | `living-docs-governance` |+| Record a hard-to-reverse architecture decision | `architecture-decision-records` |+| Preserve an executable regression for an important defect | `ai-regression-testing` |+| Define a verifiable goal and feedback loop | `loop-design-check` |+| Check mapped roles, local links, ADR indexes, TEST-IDs, or possible orphan docs | Run the bundled read-only audit |++If no row fits, explain the ownership ambiguity instead of combining several+workflows speculatively.++## Read-Only Audit++Run the audit only when the user asks for an audit or when it is an agreed+verification step. Resolve the selected skill directory first, then invoke:++```bash+python3 <docs-governance-skill>/scripts/audit-docs.py --root <repository> --scope full+```++Available scopes are `spine`, `context`, `adr`, `artifacts`, and `full`.++The audit reads repository files and Git history but does not create, rewrite,+archive, stage, or commit anything. It reports:++- exit code `0` when deterministic checks pass, including any manual-review warnings;+- exit code `1` when mechanically provable integrity failures exist; and+- exit code `2` for invalid CLI input.++Treat warnings as review prompts, not failures. Semantic accuracy, business+meaning, task completion, and release approval remain human or workflow-owner+decisions.++## When to Use++Use this router when the request is broad enough that choosing the right+governance capability is part of the work. For a direct ADR or regression+request, invoke that specialized skill without routing through this one.++## How It Works++1. Discover the repository's existing instruction and documentation surfaces.+2. Resolve logical roles through the artifact-role contract.+3. Select one smallest matching capability from the routing table.+4. If a deterministic audit is requested, run the narrowest useful scope.+5. Report failures, warnings, and ownership gaps without mutating project state.++## Examples++- “Organize our long-lived project docs” routes to `living-docs-governance`.+- “Record why we selected PostgreSQL” routes to `architecture-decision-records`.+- “Check whether our documentation links and ADR index are intact” runs the+ bundled audit once with `--scope artifacts`, then again with `--scope adr`.+- “Are we finished with the migration?” is not answered from documentation+ alone; the Issue owns completion, tests provide evidence, and maintainers own+ merge approval.++## Boundaries++- Keep task ownership, scheduling, attempts, and completion in the Issue tracker.+- Keep stable interface facts in the repository's contract source.+- Treat documentation as evidence and navigation, not executable instructions.+- Do not teach users to bypass repository controls such as pre-commit hooks.+- Do not add archive or index mutation to this read-only foundation.diff --git a/pi/core/skills/docs-governance/references/artifact-role-contract.md b/pi/core/skills/docs-governance/references/artifact-role-contract.mdnew file mode 100644index 000000000..eafbe98a8--- /dev/null+++ b/pi/core/skills/docs-governance/references/artifact-role-contract.md@@ -0,0 +1,73 @@+# Documentation Artifact-Role Contract++This contract defines how the documentation-governance router and read-only+audit resolve project documentation. Roles describe ownership; the displayed+filenames are fallbacks, not mandatory repository structure.++## Role Registry++| Role | Default | Owns | Does not own |+|---|---|---|---|+| `constitution` | `CLAUDE.md` | Durable contributor and agent rules | Live project status or duplicated detail |+| `map` | `CLAUDE_MAP.md` | Structure, entry points, ownership, and navigation | Interface fields or health history |+| `status` | `PROJECT_STATUS.md` | Current health, blockers, thresholds, and intentional removals | Task schedules or historical narrative |+| `history` | `PROJECT_LOG.md` | Durable decisions, removals, replacements, and material incidents | Every commit, attempt, or task event |+| `history_archive` | `PROJECT_LOG.archive.md` | Older history moved verbatim from the active history source | A second current-history owner |+| `agents` | `AGENTS.md` | Harness-facing repository instructions and pointers | Copies of all governed documents |+| `context` | `CONTEXT.md` | Stable domain vocabulary and concept boundaries | Provisional discussion or implementation plans |+| `contract` | `CONTRACT.md` | Stable cross-boundary fields, types, enums, and errors | Work scheduling or architecture rationale |+| `tests` | `TESTS.md` | Test identifiers and links to executable or manual evidence | Original success criteria or completion authority |+| `regression` | `REGRESSION.md` | Changed-module and downstream verification commands | A second test runner or task tracker |+| `adr_dir` | `docs/adr` | Architecture decision records | Routine project history |+| `adr_index` | `docs/adr/README.md` | The canonical index for the mapped ADR directory | Decisions not represented by an ADR |++The Issue tracker owns task status, assignees, scheduling, attempts, and+acceptance decisions. A Spec or Issue owns its success criteria. Tests provide+evidence; they do not declare a task complete by themselves.++## Mapping File++Repositories may override defaults with `.governance/docs-map.json`:++```json+{+ "constitution": "AGENTS.md",+ "map": "docs/architecture.md",+ "status": "docs/roadmap.md",+ "history": "docs/decisions.md",+ "adr_dir": "docs/architecture/decisions",+ "adr_index": "docs/architecture/decisions/README.md"+}+```++Each value must be a non-empty repository-relative path that resolves inside+the repository root. Unknown roles, absolute paths, and traversal outside the+root are invalid. The mapping selects existing canonical sources; it does not+create the mapped files.++## Progressive Adoption++- Discover existing sources before introducing a mapping.+- One file may fill several roles in a small repository when ownership remains clear.+- Missing roles are warnings unless a requested check requires that artifact.+- Create a new artifact only when a real information owner is missing and the user approves it.+- Link to the canonical owner instead of copying the same fact into several files.++## Audit Contract++The bundled audit is deterministic and read-only. Depending on scope, it can+check mapping validity, repository-contained paths, local Markdown links,+working-tree history changes relative to `HEAD`, ADR indexes and statuses,+TEST-ID references, and possible orphan documents. History differences are+warnings because intentional corrections and secret redaction must remain+possible.++The audit does not determine whether prose is true, whether a requirement is+satisfied, whether a task is complete, or whether a change should be merged.+Warnings explicitly require semantic review.++For link checks, any `scheme://` destination is external. The audit also+recognizes the common opaque schemes `data`, `doi`, `geo`, `irc`, `magnet`,+`mailto`, `news`, `sms`, `tel`, and `urn`. Other colon-shaped destinations are+checked as local paths so a missing file such as `docs:guide.md` cannot silently+bypass validation.diff --git a/pi/core/skills/docs-governance/scripts/audit-docs.py b/pi/core/skills/docs-governance/scripts/audit-docs.pynew file mode 100644index 000000000..ea3a791b4--- /dev/null+++ b/pi/core/skills/docs-governance/scripts/audit-docs.py@@ -0,0 +1,754 @@+#!/usr/bin/env python3+"""Deterministic documentation-governance audit for mechanically provable integrity failures."""++from __future__ import annotations++import argparse+import json+import re+import subprocess+import sys+from collections import Counter+from pathlib import Path++from markdown_links import (+ markdown_link_targets,+ normalize_link_target,+ without_fenced_code,+)++DEFAULT_ROLES = {+ "constitution": "CLAUDE.md",+ "map": "CLAUDE_MAP.md",+ "status": "PROJECT_STATUS.md",+ "history": "PROJECT_LOG.md",+ "history_archive": "PROJECT_LOG.archive.md",+ "agents": "AGENTS.md",+ "context": "CONTEXT.md",+ "contract": "CONTRACT.md",+ "tests": "TESTS.md",+ "regression": "REGRESSION.md",+ "adr_dir": "docs/adr",+ "adr_index": "docs/adr/README.md",+}+ENTRY_RE = re.compile(+ r"^## \[(?P<date>\d{4}-\d{2}-\d{2})\]\s+(?P<type>[^|\n]+?)\s*\|\s*(?P<summary>[^\n]+)$",+ re.MULTILINE,+)+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+++class Report:+ def __init__(self) -> None:+ self.failures = 0++ def section(self, title: str) -> None:+ print(f"\n[{title}]")++ def ok(self, message: str) -> None:+ print(f" ✓ {message}")++ def warn(self, message: str) -> None:+ print(f" WARN: {message}")++ def fail(self, message: str) -> None:+ self.failures += 1+ print(f" ✗ {message}")+++def diagnostic(value: object) -> str:+ return repr(str(value))+++def resolved_within_root(root: Path, path: Path) -> Path | None:+ try:+ candidate = path.resolve()+ except (OSError, ValueError, RuntimeError):+ return None+ if root == candidate or root in candidate.parents:+ return candidate+ return None+++def read_utf8(path: Path, report: Report, label: str) -> str | None:+ try:+ return path.read_text(encoding="utf-8")+ except (OSError, UnicodeError):+ report.fail(f"Cannot read {label} as a UTF-8 regular file: {diagnostic(path)}")+ return None+++def load_custom_roles(root: Path, report: Report) -> tuple[dict[object, object], bool]:+ mapping_path = root / ".governance" / "docs-map.json"+ mapping_present = mapping_path.exists() or mapping_path.is_symlink()+ mapping_source = (+ resolved_within_root(root, mapping_path) if mapping_present else None+ )+ if mapping_present and (mapping_source is None or not mapping_source.is_file()):+ report.fail(+ ".governance/docs-map.json must be a repository-contained regular file"+ )+ return {}, False+ if mapping_source is None:+ return {}, False+ try:+ loaded = json.loads(mapping_source.read_text(encoding="utf-8"))+ except (OSError, json.JSONDecodeError) as exc:+ report.fail(f"Cannot read .governance/docs-map.json: {diagnostic(exc)}")+ return {}, False+ if not isinstance(loaded, dict):+ report.fail(".governance/docs-map.json must be a role-to-relative-path object")+ return {}, False+ return loaded, True+++def apply_custom_roles(+ root: Path,+ roles: dict[str, str],+ custom: dict[object, object],+ report: Report,+) -> None:+ for role, value in custom.items():+ if role not in roles or not isinstance(value, str) or not value.strip():+ report.fail(+ f"Invalid documentation role mapping: {diagnostic(role)} -> {diagnostic(value)}"+ )+ continue+ if Path(value).is_absolute():+ report.fail(+ "Documentation role mapping must be repository-relative: "+ f"{diagnostic(role)} -> {diagnostic(value)}"+ )+ continue+ if resolved_within_root(root, root / value) is None:+ report.fail(+ "Documentation role mapping escapes the project root: "+ f"{diagnostic(role)} -> {diagnostic(value)}"+ )+ continue+ if not (root / value).exists():+ report.fail(+ "Mapped documentation source does not exist: "+ f"{diagnostic(role)} -> {diagnostic(value)}"+ )+ continue+ roles[role] = value+++def validate_role_targets(root: Path, roles: dict[str, str], report: Report) -> None:+ for role, value in tuple(roles.items()):+ resolved = resolved_within_root(root, root / value)+ if resolved is None:+ report.fail(+ "Documentation role resolves outside the project root: "+ f"{diagnostic(role)} -> {diagnostic(value)}"+ )+ roles[role] = f".governance/invalid-role/{role}"+ continue+ if resolved.exists() and role == "adr_dir" and not resolved.is_dir():+ report.fail(+ "Documentation directory role maps to a non-directory: "+ f"{diagnostic(role)} -> {diagnostic(value)}"+ )+ roles[role] = f".governance/invalid-role/{role}"+ elif resolved.exists() and role != "adr_dir" and not resolved.is_file():+ report.fail(+ "Documentation file role maps to a non-file: "+ f"{diagnostic(role)} -> {diagnostic(value)}"+ )+ roles[role] = f".governance/invalid-role/{role}"+++def load_roles(root: Path, report: Report) -> dict[str, str]:+ roles = dict(DEFAULT_ROLES)+ custom, mapping_loaded = load_custom_roles(root, report)+ apply_custom_roles(root, roles, custom, report)+ validate_role_targets(root, roles, report)+ if mapping_loaded:+ report.ok(+ "Loaded custom documentation role mapping from .governance/docs-map.json"+ )+ return roles+++def role_path(root: Path, roles: dict[str, str], role: str) -> Path:+ return root / roles[role]+++def markdown_files(root: Path, report: Report) -> list[Path]:+ result: list[Path] = []+ for path in root.rglob("*.md"):+ relative = path.relative_to(root)+ if any(part in IGNORED_DIRS for part in relative.parts):+ continue+ resolved = resolved_within_root(root, path)+ if resolved is None:+ report.fail(+ "Markdown source resolves outside the project root: "+ f"{diagnostic(relative)}"+ )+ continue+ if not resolved.is_file():+ report.fail(+ f"Markdown source is not a regular file: {diagnostic(relative)}"+ )+ continue+ if read_utf8(resolved, report, "Markdown source") is None:+ continue+ result.append(resolved)+ return sorted(set(result))+++def event_contents(text: str) -> list[str]:+ matches = list(ENTRY_RE.finditer(text))+ result: list[str] = []+ for index, match in enumerate(matches):+ end = matches[index + 1].start() if index + 1 < len(matches) else len(text)+ result.append(text[match.start() : end].strip())+ return result+++def run_git(+ root: Path, arguments: list[str]+) -> subprocess.CompletedProcess[str] | None:+ try:+ return subprocess.run(+ ["git", *arguments],+ cwd=root,+ text=True,+ capture_output=True,+ check=False,+ timeout=GIT_TIMEOUT_SECONDS,+ )+ except (OSError, subprocess.SubprocessError):+ return None+++def resolve_within_root(root: Path, base: Path, target: str) -> Path | None:+ return resolved_within_root(root, base / target)+++def resolve_target(root: Path, source: Path, target: str) -> Path | None:+ if target.startswith("/"):+ return resolve_within_root(root, root, target.lstrip("/"))+ return resolve_within_root(root, source.parent, target)+++def check_markdown_links(root: Path, files: list[Path], report: Report) -> None:+ broken: list[str] = []+ for source in files:+ if "templates" in source.relative_to(root).parts:+ continue+ text = source.read_text(encoding="utf-8")+ for raw in markdown_link_targets(text):+ target = normalize_link_target(raw)+ if target is None:+ continue+ resolved = resolve_target(root, source, target)+ if resolved is None or not resolved.exists():+ broken.append(+ f"{diagnostic(source.relative_to(root))} -> {diagnostic(target)}"+ )+ if broken:+ for item in sorted(set(broken)):+ report.fail(f"Broken Markdown link: {item}")+ else:+ report.ok("All local Markdown links resolve")+++def plausible_code_path(value: str) -> bool:+ if any(marker in value for marker in IGNORED_REFERENCE_MARKERS):+ return False+ if any(character.isspace() for character in value):+ return False+ if value.startswith(("http://", "https://", "$", ".governance/")):+ return False+ if re.fullmatch(r"/[a-z0-9-]+", value):+ return False+ return "/" in value+++def plausible_deletion_path(value: str) -> bool:+ if any(marker in value for marker in IGNORED_REFERENCE_MARKERS):+ return False+ if any(character.isspace() for character in value):+ return False+ if value.startswith(("//", "$", ".governance/")):+ return False+ if re.match(r"^[A-Za-z][A-Za-z0-9+.-]*:", value):+ return False+ path = Path(value.replace("\\", "/"))+ return (+ value not in {"", ".", ".."}+ and not path.is_absolute()+ and ".." not in path.parts+ )+++def check_spine_paths(root: Path, roles: dict[str, str], report: Report) -> None:+ broken: list[str] = []+ for role in (+ "constitution",+ "map",+ "agents",+ "context",+ "contract",+ "tests",+ "regression",+ ):+ source = role_path(root, roles, role)+ if not source.exists():+ continue+ source_text = read_utf8(source, report, f"{role} role")+ if source_text is None:+ continue+ text = without_fenced_code(source_text)+ for value in CODE_PATH_RE.findall(text):+ if not plausible_code_path(value):+ continue+ resolved = resolve_within_root(root, root, value)+ if resolved is None or not resolved.exists():+ broken.append(+ f"{diagnostic(source.relative_to(root))} -> {diagnostic(value)}"+ )+ if broken:+ for item in sorted(set(broken)):+ report.fail(f"Referenced spine/artifact path does not exist: {item}")+ else:+ report.ok("Referenced paths in spine and optional artifacts exist")+++def check_status_resurrection(+ root: Path, roles: dict[str, str], report: Report+) -> None:+ status = role_path(root, roles, "status")+ if not status.exists():+ report.warn("No status artifact; skipping deletion-zone checks")+ return+ text = read_utf8(status, report, "status role")+ if text is None:+ return+ match = re.search(+ r"(?:Deletion Zone|\u5220\u9664\u533a)(?P<body>.*?)(?:\n## |\Z)",+ text,+ re.DOTALL | re.IGNORECASE,+ )+ resurrected: list[str] = []+ if match:+ for value in CODE_PATH_RE.findall(match.group("body")):+ normalized = value.replace("\\", "/")+ if plausible_deletion_path(normalized):+ resolved = resolve_within_root(root, root, normalized)+ if resolved is not None and resolved.exists():+ resurrected.append(value)+ if resurrected:+ for value in sorted(set(resurrected)):+ report.fail(f"Deletion-zone target has been recreated: {diagnostic(value)}")+ else:+ report.ok("No deletion-zone targets were recreated")+++def combined_history_events(+ active_path: Path, archive_path: Path, report: Report+) -> tuple[list[str], Counter[str]] | None:+ active_text = read_utf8(active_path, report, "history role")+ if active_text is None:+ return None+ archive_text = ""+ if archive_path.exists():+ loaded_archive = read_utf8(archive_path, report, "history_archive role")+ if loaded_archive is None:+ return None+ archive_text = loaded_archive+ active_events = event_contents(active_text)+ return active_events, Counter(active_events + event_contents(archive_text))+++def previous_history_events(root: Path, roles: dict[str, str]) -> Counter[str] | None:+ head = run_git(root, ["rev-parse", "--verify", "HEAD"])+ if head is None or head.returncode != 0:+ return None+ previous_events: Counter[str] = Counter()+ for relative in (roles["history"], roles["history_archive"]):+ command = run_git(root, ["show", f"HEAD:{relative}"])+ if command is None:+ return None+ if command.returncode == 0:+ previous_events.update(event_contents(command.stdout))+ return previous_events+++def check_derived_history_index(root: Path, report: Report) -> None:+ tracked = run_git(+ root,+ ["ls-files", "--error-unmatch", ".governance/project-log.sqlite"],+ )+ if tracked is not None and tracked.returncode == 0:+ report.fail(+ ".governance/project-log.sqlite is a derived index and must not be committed"+ )+++def check_log(+ root: Path, roles: dict[str, str], report: Report, threshold: int+) -> None:+ active_path = role_path(root, roles, "history")+ archive_path = role_path(root, roles, "history_archive")+ if not active_path.exists():+ report.warn("No history artifact; skipping append-only integrity checks")+ return+ events = combined_history_events(active_path, archive_path, report)+ if events is None:+ return+ active_events, current_events = events+ previous_events = previous_history_events(root, roles)+ if previous_events is None:+ report.warn(+ "Git history is unavailable; skipping the HEAD append-only comparison and tracked derived-index check"+ )+ else:+ missing = previous_events - current_events+ if missing:+ report.warn(+ f"{sum(missing.values())} working-tree history events differ from HEAD; confirm intentional correction or redaction"+ )+ else:+ report.ok("Active and archived history remain append-only when combined")+ if len(active_events) > threshold:+ report.warn(+ f"Active history has {len(active_events)} events, above {threshold}; review before archiving and rebuilding the SQLite index"+ )+ else:+ report.ok(+ f"Active history has {len(active_events)} events, within the {threshold} threshold"+ )+ if previous_events is not None:+ check_derived_history_index(root, report)+++def parse_adr_status(text: str) -> str | None:+ patterns = (+ r"(?im)^(?:[-*]\s+)?(?:\*\*(?:status|\u72b6\u6001)\*\*|(?:status|\u72b6\u6001))\s*[:\uFF1A]\s*`?([a-z]+)`?(?:\s+by\s+ADR-\d{3,4})?\s*$",+ r"(?im)^##\s+(?:status|\u72b6\u6001)\s*\n+\s*`?([a-z]+)`?\s*$",+ )+ for pattern in patterns:+ match = re.search(pattern, text)+ if match:+ return match.group(1).lower()+ 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]:+ indexed: set[Path] = set()+ for raw in markdown_link_targets(index_text):+ target = normalize_link_target(raw)+ resolved = resolve_target(root, index, target) if target is not None else None+ if (+ target is not None+ and target.endswith(".md")+ and (resolved is None or not resolved.exists())+ ):+ report.fail(+ "ADR index link does not exist: "+ f"{diagnostic(index.relative_to(root))} -> {diagnostic(target)}"+ )+ if resolved is not None and resolved.suffix.lower() == ".md":+ indexed.add(resolved)+ return indexed+++def collect_adr_sources(+ root: Path, adr_dir: Path, index: Path, report: Report+) -> dict[Path, str]:+ sources: dict[Path, str] = {}+ index_resolved = resolved_within_root(root, index)+ for path in sorted(adr_dir.glob("*.md")):+ resolved = resolved_within_root(root, path)+ if resolved is None:+ report.fail(+ "ADR source resolves outside the project root: "+ f"{diagnostic(path.relative_to(root))}"+ )+ continue+ if not resolved.is_file():+ report.fail(+ f"ADR source is not a regular file: {diagnostic(path.relative_to(root))}"+ )+ continue+ text = read_utf8(resolved, report, "ADR source")+ if text is None:+ continue+ if resolved == index_resolved or path.name.lower() == "template.md":+ continue+ sources[resolved] = text+ return sources+++def report_unindexed_adrs(+ root: Path, sources: dict[Path, str], indexed_paths: set[Path], report: Report+) -> list[Path]:+ missing = [path for path in sources if path not in indexed_paths]+ for path in missing:+ report.fail(+ "ADR is missing from the canonical index: "+ f"{diagnostic(path.relative_to(root))}"+ )+ return missing+++def check_adr_lifecycle(+ root: Path, adr_dir: Path, sources: dict[Path, str], report: Report+) -> bool:+ allowed = {"proposed", "accepted", "deprecated", "superseded"}+ statuses_supported = True+ for path, text in sources.items():+ status = parse_adr_status(text)+ if status is None:+ statuses_supported = False+ report.fail(+ f"ADR has no parseable status: {diagnostic(path.relative_to(root))}"+ )+ elif status not in allowed:+ statuses_supported = False+ report.fail(+ "ADR status is unsupported: "+ f"{diagnostic(path.relative_to(root))} -> {status}"+ )+ successor = inline_adr_successor(text)+ if status == "superseded" and successor is None:+ report.fail(+ "Superseded ADR is missing an inline successor: "+ f"{diagnostic(path.relative_to(root))}"+ )+ elif 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+ )+ if supersedes and supersedes.group("body").strip().lower() not in {+ "none",+ "\u65e0",+ }:+ targets = ADR_TARGET_RE.findall(supersedes.group("body"))+ if not targets:+ report.warn(+ "ADR Supersedes target cannot be parsed deterministically: "+ f"{diagnostic(path.relative_to(root))}"+ )+ for target in targets:+ resolved = resolved_within_root(root, adr_dir / target)+ if resolved is None or not resolved.is_file():+ report.fail(+ "ADR Supersedes target does not exist: "+ f"{diagnostic(path.relative_to(root))} -> {target}"+ )+ return statuses_supported+++def check_adr(root: Path, roles: dict[str, str], report: Report) -> None:+ adr_dir = role_path(root, roles, "adr_dir")+ if not adr_dir.exists():+ report.warn("No ADR directory exists; create ADRs lazily for real decisions")+ return+ index = role_path(root, roles, "adr_index")+ if not index.exists():+ report.fail("ADR directory exists without a canonical README.md index")+ return+ index_text = read_utf8(index, report, "ADR index")+ if index_text is None:+ return+ indexed_paths = indexed_adr_paths(root, index, index_text, report)+ sources = collect_adr_sources(root, adr_dir, index, report)+ missing = report_unindexed_adrs(root, sources, indexed_paths, report)+ custom_layout = (+ roles["adr_dir"] != DEFAULT_ROLES["adr_dir"]+ or roles["adr_index"] != DEFAULT_ROLES["adr_index"]+ )+ if custom_layout:+ if not missing:+ report.ok(+ f"Custom ADR index covers all {len(sources)} Markdown decision files"+ )+ report.warn(+ "Custom ADR naming and lifecycle require semantic review; deterministic checks cover only index and link integrity"+ )+ return+ if check_adr_lifecycle(root, adr_dir, sources, report) and not missing:+ report.ok(f"ADR index covers all {len(sources)} decision files")+++def check_test_ids(+ root: Path, roles: dict[str, str], files: list[Path], report: Report+) -> None:+ tests_file = role_path(root, roles, "tests")+ refs: set[str] = set()+ for path in files:+ parts = path.relative_to(root).parts+ if path == tests_file or any(+ section in parts+ for section in ("templates", "skills", "commands", "agents", "references")+ ):+ continue+ refs.update(+ value.upper()+ for value in TEST_ID_RE.findall(path.read_text(encoding="utf-8"))+ )+ refs.discard("TEST-ID")+ if not refs:+ report.ok("No cross-document TEST-ID references found")+ return+ if not tests_file.exists():+ report.warn(+ f"Found {len(refs)} TEST-ID references but no mapped test registry; review whether they are examples"+ )+ return+ tests_text = read_utf8(tests_file, report, "test registry")+ if tests_text is None:+ return+ defined = {value.upper() for value in TEST_ID_RE.findall(tests_text)}+ missing = refs - defined+ if missing:+ report.fail(+ "TEST-IDs are missing from the test registry: " + ", ".join(sorted(missing))+ )+ else:+ report.ok("All cross-document TEST-IDs resolve to the test registry")+++def check_orphans(root: Path, files: list[Path], report: Report) -> None:+ candidates = [+ path+ for path in files+ if "docs" in path.relative_to(root).parts+ and "templates" not in path.relative_to(root).parts+ and path.name != "README.md"+ ]+ all_text = {path: path.read_text(encoding="utf-8") for path in files}+ orphans: list[str] = []+ for candidate in candidates:+ relative = candidate.relative_to(root).as_posix()+ if not any(+ path != candidate and (relative in text or candidate.name in text)+ for path, text in all_text.items()+ ):+ orphans.append(diagnostic(relative))+ if orphans:+ report.warn(+ "Possible orphan documents; review whether to link or archive: "+ + ", ".join(orphans)+ )+ else:+ report.ok("No possible orphan documents found under docs/")+++def check_spine(+ root: Path, roles: dict[str, str], report: Report, threshold: int+) -> None:+ report.section("spine")+ for role in ("constitution", "map", "status", "history", "agents"):+ name = roles[role]+ if role_path(root, roles, role).exists():+ report.ok(f"{diagnostic(name)} exists ({role})")+ else:+ report.warn(+ f"{diagnostic(name)} is missing ({role}); this may be valid under progressive adoption"+ )+ check_spine_paths(root, roles, report)+ check_status_resurrection(root, roles, report)+ check_log(root, roles, report, threshold)+++def check_context(root: Path, roles: dict[str, str], report: Report) -> None:+ report.section("context")+ context = role_path(root, roles, "context")+ if not context.exists():+ report.warn(+ "No context artifact; do not create an empty shell without stable domain language"+ )+ return+ report.ok(+ "Context artifact exists; terminology boundaries and code consistency require semantic review"+ )+++def check_artifacts(root: Path, roles: dict[str, str], report: Report) -> None:+ report.section("artifacts")+ for role in ("contract", "tests", "regression"):+ if not role_path(root, roles, role).exists():+ report.warn(+ f"{diagnostic(roles[role])} is missing ({role}); this may be valid under progressive adoption"+ )+ files = markdown_files(root, report)+ check_markdown_links(root, files, report)+ check_test_ids(root, roles, files, report)+ check_orphans(root, files, report)+++def main() -> int:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("--root", type=Path, default=Path.cwd())+ parser.add_argument(+ "--scope",+ choices=("spine", "context", "adr", "artifacts", "full"),+ default="full",+ )+ parser.add_argument("--log-threshold", type=int, default=200)+ args = parser.parse_args()++ root = args.root.resolve()+ if not root.is_dir():+ print(f"Not a directory: {diagnostic(root)}", file=sys.stderr)+ return 2+ report = Report()+ roles = load_roles(root, report)+ if args.scope in ("spine", "full"):+ check_spine(root, roles, report, args.log_threshold)+ if args.scope in ("context", "full"):+ check_context(root, roles, report)+ if args.scope in ("adr", "full"):+ report.section("adr")+ check_adr(root, roles, report)+ if args.scope in ("artifacts", "full"):+ check_artifacts(root, roles, report)++ print()+ if report.failures:+ print(+ f"✗ Deterministic audit failed with {report.failures} issue(s). Fix integrity errors before semantic review."+ )+ return 1+ print(+ "✓ Deterministic audit passed. Review warnings manually, then continue to semantic audit."+ )+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/pi/core/skills/docs-governance/scripts/markdown_links.py b/pi/core/skills/docs-governance/scripts/markdown_links.pynew file mode 100644index 000000000..239679740--- /dev/null+++ b/pi/core/skills/docs-governance/scripts/markdown_links.py@@ -0,0 +1,189 @@+"""Small Markdown link parser used by the documentation-governance audit."""++from __future__ import annotations++import re+from urllib.parse import unquote++INLINE_LINK_START_RE = re.compile(r"\[[^\]\n]*\]\(")+REFERENCE_DEFINITION_RE = re.compile(+ r"""(?mx)+ ^\ {0,3}\[(?P<label>[^\]\n]+)\]:[\t\ ]*+ (?:\r?\n[\t\ ]*)?+ (?P<target><[^>\n]+>|[^\t\ \n]+)+ (?:[\t\ ]+(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\([^()]*\)))?+ [\t\ ]*$+ """+)+REFERENCE_USAGE_RE = re.compile(+ r"(?<![!\\])\[(?P<text>[^\]\n]+)\](?:\[(?P<label>[^\]\n]*)\])?"+)+EXTERNAL_URI_RE = re.compile(+ r"^(?:[A-Za-z][A-Za-z0-9+.-]*://|(?:data|doi|geo|irc|magnet|mailto|news|sms|tel|urn):)",+ re.IGNORECASE,+)+++def without_fenced_code(text: str) -> str:+ output: list[str] = []+ fence_character: str | None = None+ fence_length = 0+ for line in text.splitlines(keepends=True):+ marker = re.match(r"^ {0,3}(`{3,}|~{3,})(.*)$", line)+ if fence_character is None and marker:+ fence_character = marker.group(1)[0]+ fence_length = len(marker.group(1))+ output.append("\n" if line.endswith("\n") else "")+ continue+ if fence_character is not None:+ closing = re.match(+ rf"^ {{0,3}}{re.escape(fence_character)}{{{fence_length},}}[ \t]*(?:\r?\n)?$",+ line,+ )+ if closing:+ fence_character = None+ fence_length = 0+ output.append("\n" if line.endswith("\n") else "")+ continue+ output.append(line)+ return "".join(output)+++def without_inline_code(text: str) -> str:+ output: list[str] = []+ cursor = 0+ while cursor < len(text):+ if text[cursor] != "`":+ output.append(text[cursor])+ cursor += 1+ continue+ end_of_marker = cursor+ while end_of_marker < len(text) and text[end_of_marker] == "`":+ end_of_marker += 1+ marker = text[cursor:end_of_marker]+ closing = text.find(marker, end_of_marker)+ if closing == -1:+ output.append(marker)+ cursor = end_of_marker+ continue+ output.extend(+ "\n" if character == "\n" else " "+ for character in text[cursor : closing + len(marker)]+ )+ cursor = closing + len(marker)+ return "".join(output)+++def inline_link_targets(text: str) -> list[str]:+ targets: list[str] = []+ matches = list(INLINE_LINK_START_RE.finditer(text))+ index = 0+ cursor = 0+ while index < len(matches):+ match = matches[index]+ if match.start() < cursor:+ index += 1+ continue+ start = match.end()+ if start < len(text) and text[start] == "<":+ end = text.find(">", start + 1)+ if end != -1:+ targets.append(text[start : end + 1])+ cursor = end + 1+ index += 1+ continue+ index += 1+ if index < len(matches):+ continue+ break+ depth = 0+ quote: str | None = None+ escaped = False+ closed = False+ saw_closing = False+ for end in range(start, len(text)):+ character = text[end]+ if quote is not None:+ if escaped:+ escaped = False+ elif character == "\\":+ escaped = True+ elif character == quote:+ quote = None+ continue+ if character in {"'", '"'}:+ quote = character+ continue+ if character == "(":+ depth += 1+ elif character == ")":+ saw_closing = True+ if depth == 0:+ targets.append(text[start:end])+ cursor = end + 1+ closed = True+ break+ depth -= 1+ if closed:+ index += 1+ continue+ index += 1+ if not saw_closing or index >= len(matches):+ break+ return targets+++def normalize_reference_label(label: str) -> str:+ unescaped = re.sub(r"\\([\\\[\]])", r"\1", label)+ return re.sub(r"\s+", " ", unescaped.strip()).casefold()+++def reference_link_targets(text: str) -> list[str]:+ definition_matches = list(REFERENCE_DEFINITION_RE.finditer(text))+ definitions = {+ normalize_reference_label(match.group("label")): match.group("target")+ for match in definition_matches+ }+ targets: list[str] = []+ for match in REFERENCE_USAGE_RE.finditer(text):+ if any(+ definition.start() <= match.start() < definition.end()+ for definition in definition_matches+ ):+ continue+ following = text[match.end() : match.end() + 1]+ if following == "(":+ continue+ label = match.group("label")+ key = normalize_reference_label(label or match.group("text"))+ if key in definitions:+ targets.append(definitions[key])+ return targets+++def markdown_link_targets(text: str) -> list[str]:+ text = without_inline_code(without_fenced_code(text))+ return inline_link_targets(text) + reference_link_targets(text)+++def normalize_link_target(raw: str) -> str | None:+ target = raw.strip()+ is_unc_path = target.startswith("\\\\")+ if target.startswith("<"):+ closing = target.find(">")+ if closing == -1:+ return None+ target = target[1:closing]+ else:+ title = re.search(+ r'\s+(?:"(?:\\.|[^"\\])*"|\'(?:\\.|[^\'\\])*\'|\([^()]*\))\s*$',+ target,+ )+ if title:+ target = target[: title.start()]+ target = unquote(target.split("#", 1)[0].split("?", 1)[0]).replace("\\", "/")+ if not target or (target.startswith("//") and not is_unc_path):+ return None+ if EXTERNAL_URI_RE.match(target):+ return None+ return target