program-context-protocol 0.12.4__py3-none-any.whl

pcp/narrative_lint.py

@@ -0,0 +1,229 @@
+"""Narrative-lint — flags CLAUDE.md-family narrative prose that has drifted
+from PCP's own tracked state (current_state.md/architecture.md).
+
+Fleet evidence (2026-07-24 context-hygiene pass across Project E/
+Project W/Project A/Project M): narrative prose in CLAUDE.md — stage
+descriptions, "Open Decisions," "Pending" lists — drifted from tracked
+state 3-for-3 in projects checked, because nothing checks free-text
+against it. `~/.claude/scripts/session-hygiene-check.sh` already covers
+the two purely mechanical checks (stale dates, missing referenced files)
+as a SessionStart hook; this ports those into PCP's own enforcement
+lifecycle (telemetry, CTRL-036) and adds the piece a bash regex can't do
+— semantic contradiction between a narrative status claim and current_
+state.md/architecture.md, which needs a judge call (rung 6, same posture
+as CTRL-020's rung-necessity check: one batched call, advisory, fail-open).
+"""
+
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+STALE_DAYS_DEFAULT = 90
+
+_DATE_RE = re.compile(r"\b(\d{4})-(\d{2})-(\d{2})\b")
+_BACKTICK_PATH_RE = re.compile(r"`([^`]*(?:/[^`]+)+)`")
+_SKIP_DIRS = {".git", "node_modules", ".venv", "venv", "__pycache__", ".pcp"}
+
+_STATUS_KEYWORDS = [
+    "pending", "open decision", "planned", "pre-build", "not yet built",
+    "not yet implemented", "coming soon", "todo:", "in progress", "wip",
+    "not started", "deferred",
+]
+
+NARRATIVE_CONTRADICTION_SYSTEM_PROMPT = """You are a documentation-drift auditor. \
+You are given status-shaped lines pulled from a project's CLAUDE.md-family files \
+(narrative context docs) alongside excerpts of that project's auto-generated \
+ground-truth state (current_state.md / architecture.md). Flag any narrative line \
+that is CONTRADICTED by the tracked state — e.g. a line claims something is \
+"Pending"/"Planned"/"Pre-build" but the tracked state shows it already built or \
+decided; a tech-stack claim contradicted by the actual stack; an "Open Decision" \
+already answered. Do not flag lines that are merely unrelated to the tracked \
+state, or that are still accurate. Respond with JSON: \
+{"contradictions": [{"index": <int, index of the narrative line>, \
+"reason": "<short explanation citing the tracked-state evidence>"}]}. \
+Empty list if none found."""
+
+
+def find_claude_md_files(project_root: Path) -> list[Path]:
+    """CLAUDE.md-family files: any CLAUDE.md/CLAUDE.local.md (path-scoped or
+    root) plus .claude/*.md — same scope session-hygiene-check.sh already
+    covers, ported to Python so PCP's own enforcement lifecycle can wire it
+    in instead of only ever reaching a human via a SessionStart hook print."""
+    found = []
+    for p in project_root.rglob("*"):
+        if p.is_dir() or any(seg in _SKIP_DIRS for seg in p.parts):
+            continue
+        if p.name in ("CLAUDE.md", "CLAUDE.local.md"):
+            found.append(p)
+    claude_dir = project_root / ".claude"
+    if claude_dir.is_dir():
+        found += [p for p in claude_dir.glob("*.md") if p.is_file()]
+    return sorted(set(found))
+
+
+def check_stale_dates(files: list[Path], stale_days: int = STALE_DAYS_DEFAULT) -> list[str]:
+    """Deterministic — a dated reference (e.g. "RESOLVED 2026-01-01") older
+    than stale_days nobody cleaned up."""
+    findings = []
+    now = datetime.now(timezone.utc)
+    for f in files:
+        try:
+            text = f.read_text(errors="replace")
+        except OSError:
+            continue
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            for m in _DATE_RE.finditer(line):
+                try:
+                    d = datetime(int(m.group(1)), int(m.group(2)), int(m.group(3)), tzinfo=timezone.utc)
+                except ValueError:
+                    continue
+                age_days = (now - d).days
+                if age_days > stale_days:
+                    findings.append(
+                        f"{f}:{lineno}: date {m.group(0)} is {age_days}d old (>{stale_days}d threshold): "
+                        f"{line.strip()[:140]}"
+                    )
+    return findings
+
+
+def _looks_like_non_path(p: str) -> bool:
+    if any(c in p for c in (" ", ":", "<", ">", "*")):
+        return True
+    if "://" in p:
+        return True
+    if any(seg in p for seg in (".com/", ".org/", ".io/", ".net/", ".dev/")) or p.endswith(".git"):
+        return True
+    if p.startswith("/") and "/" not in p[1:] and "." not in p:
+        return True  # bare slash-command like /pcp, not a filesystem path
+    return False
+
+
+def check_missing_files(files: list[Path], project_root: Path) -> list[str]:
+    """Deterministic — a backtick-quoted path referenced in a CLAUDE.md-family
+    file that no longer exists on disk."""
+    findings = []
+    for f in files:
+        try:
+            text = f.read_text(errors="replace")
+        except OSError:
+            continue
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            for m in _BACKTICK_PATH_RE.finditer(line):
+                p = m.group(1)
+                if _looks_like_non_path(p) or "*" in p:
+                    continue
+                expanded = Path(p).expanduser()
+                if not expanded.is_absolute():
+                    expanded = project_root / expanded
+                if not expanded.exists():
+                    findings.append(f"{f}:{lineno}: referenced path not found on disk: `{p}`")
+    return findings
+
+
+def collect_status_lines(files: list[Path]) -> list[tuple[str, int, str]]:
+    """Deterministic pre-filter — only status-shaped lines get sent to the
+    judge call (Token Discipline: never paste whole CLAUDE.md files)."""
+    hits = []
+    for f in files:
+        try:
+            text = f.read_text(errors="replace")
+        except OSError:
+            continue
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            low = line.lower()
+            if any(k in low for k in _STATUS_KEYWORDS):
+                hits.append((str(f), lineno, line.strip()))
+    return hits
+
+
+def _tracked_state_excerpt(pcp_dir: Path, max_chars: int) -> str:
+    parts = []
+    for name in ("current_state.md", "architecture.md"):
+        p = pcp_dir / name
+        if p.exists():
+            parts.append(f"### {name}\n{p.read_text(errors='replace')}")
+    excerpt = "\n\n".join(parts)
+    return excerpt[:max_chars]
+
+
+def check_narrative_contradictions(
+    pcp_dir: Path, status_lines: list[tuple[str, int, str]],
+    max_state_chars: int = 8000,
+) -> list[str]:
+    """ONE batched judge call (rung 6 — semantic contradiction is the one
+    irreducibly judgment-shaped part of this lint, same posture CTRL-020's
+    rung-necessity check already uses). Advisory; fails open on any error
+    or if there's nothing tracked to compare against."""
+    if not status_lines:
+        return []
+    state_excerpt = _tracked_state_excerpt(pcp_dir, max_state_chars)
+    if not state_excerpt.strip():
+        return []
+
+    from pcp.llm import client as llm
+
+    numbered = "\n".join(f"[{i}] {path}:{lineno}: {text}" for i, (path, lineno, text) in enumerate(status_lines))
+    user_prompt = f"Narrative lines:\n{numbered}\n\nTracked state:\n{state_excerpt}"
+    findings: list[str] = []
+    try:
+        res = llm.call_json(
+            NARRATIVE_CONTRADICTION_SYSTEM_PROMPT, user_prompt, model=llm.JUDGE_MODEL,
+            pcp_dir=pcp_dir, command="narrative-lint",
+        )
+        for c in res.get("contradictions", []):
+            if not isinstance(c, dict):
+                continue
+            i = c.get("index")
+            if isinstance(i, int) and 0 <= i < len(status_lines):
+                path, lineno, text = status_lines[i]
+                findings.append(
+                    f"{path}:{lineno}: narrative claim contradicted by tracked state — "
+                    f"{c.get('reason', '')[:200]} (claim: {text[:140]!r})"
+                )
+    except Exception:
+        pass  # advisory judge call — fail open, same posture as every other wave-merge judge check
+    return findings
+
+
+def run(pcp_dir: Path, stale_days: int = STALE_DAYS_DEFAULT, skip_llm: bool = False) -> dict:
+    """Full lint: deterministic checks always run; the semantic contradiction
+    check is skippable (CI/cost-sensitive callers) via skip_llm."""
+    project_root = pcp_dir.parent
+    files = find_claude_md_files(project_root)
+    stale = check_stale_dates(files, stale_days)
+    missing = check_missing_files(files, project_root)
+    contradictions: list[str] = []
+    if not skip_llm:
+        status_lines = collect_status_lines(files)
+        contradictions = check_narrative_contradictions(pcp_dir, status_lines)
+    return {
+        "files_scanned": [str(f) for f in files],
+        "stale_dates": stale,
+        "missing_files": missing,
+        "contradictions": contradictions,
+    }
+
+
+def render_markdown(result: dict, timestamp: str) -> str:
+    lines = [
+        "# Narrative Lint",
+        f"Generated: {timestamp}",
+        "",
+        f"CLAUDE.md-family files scanned: {len(result['files_scanned'])}",
+        "",
+    ]
+    sections = [
+        ("Stale dated references", result["stale_dates"]),
+        ("Missing referenced files", result["missing_files"]),
+        ("Narrative vs. tracked-state contradictions (advisory judge call)", result["contradictions"]),
+    ]
+    for title, findings in sections:
+        lines.append(f"## {title}")
+        lines.append("")
+        if findings:
+            for f in findings:
+                lines.append(f"- {f}")
+        else:
+            lines.append("_None found._")
+        lines.append("")
+    return "\n".join(lines)

pcp/nav_graph.py

@@ -0,0 +1,226 @@
+"""Measured navigation reachability — is a screen actually reachable, and how deep.
+
+The Feature Exposure Ladder previously classified a criterion by whether it
+carried a `design_justification` field. Measured 2026-07-27 on Project O,
+that produced 101 "Built, Hidden" and 24 "Exposed, Enriched" with **zero** at
+rungs 2 and 3 -- a binary condition wearing a four-rung costume. "101 hidden
+features" was really "101 criteria lack an optional field": a statement about
+PCP's own paperwork presented as a statement about the product, and the exact
+Goodhart shape `coverage_audit.py` exists to guard against elsewhere.
+
+This module measures the artifact instead. It builds a page/route graph from the
+UI source actually on disk and computes shortest-path depth from the app's entry
+point. Deterministic, rung 1, no LLM.
+
+Two navigation styles are recognised, both by reading what is there:
+
+* multi-page (Vite `rollupOptions.input`, or bare `*.html`) with `href` edges --
+  Project O's canvas-next is this: `index.html` and `query.html` linking
+  to each other.
+* single-page router (`<Route path=...>`) with `<Link to=...>` / `navigate(...)`
+  edges.
+
+The honest part is the fallback. When the graph cannot be determined -- no UI
+source, no pages found, or a criterion that cannot be tied to a screen -- the
+answer is `None`, meaning "not determinable", NOT "hidden". Reporting an absent
+measurement as a bad measurement is how the previous version produced a
+discoverability crisis out of an unpopulated field.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections import deque
+from pathlib import Path
+
+_SKIP_DIRS = {"node_modules", ".venv", "venv", "dist", "build", ".git", "__pycache__"}
+
+# Multi-page: Vite's own registry of entry documents.
+_VITE_INPUT_BLOCK = re.compile(r"input\s*:\s*\{(.*?)\}", re.DOTALL)
+_VITE_INPUT_ENTRY = re.compile(r"""["']?(\w+)["']?\s*:\s*resolve\([^,]+,\s*["']([^"']+)["']\)""")
+
+# Edges.
+_HREF = re.compile(r"""href\s*=\s*["']([^"'#?]+)""")
+_LINK_TO = re.compile(r"""<Link[^>]*\bto\s*=\s*["']([^"']+)["']""")
+_NAVIGATE = re.compile(r"""navigate\(\s*["']([^"']+)["']""")
+_LOCATION = re.compile(r"""location\.(?:href|assign|replace)\s*=?\s*\(?\s*["']([^"']+)["']""")
+
+# Single-page routes.
+_ROUTE = re.compile(r"""<Route[^>]*\bpath\s*=\s*["']([^"']+)["']""")
+
+
+def _source_files(root: Path) -> list[Path]:
+    out: list[Path] = []
+    if not root.is_dir():
+        return out
+    for p in root.rglob("*"):
+        if not p.is_file() or p.suffix not in {".tsx", ".ts", ".jsx", ".js", ".html", ".vue", ".svelte"}:
+            continue
+        if _SKIP_DIRS & set(p.parts):
+            continue
+        out.append(p)
+    return out
+
+
+def _ui_roots(project_root: Path) -> list[Path]:
+    """Directories that look like a front end, without hardcoding a layout."""
+    roots: list[Path] = []
+    for cand in project_root.rglob("vite.config.*"):
+        if not (_SKIP_DIRS & set(cand.parts)):
+            roots.append(cand.parent)
+    if roots:
+        return roots
+    for name in ("web", "frontend", "ui", "client"):
+        d = project_root / name
+        if d.is_dir():
+            roots.append(d)
+    return roots
+
+
+def discover_pages(ui_root: Path) -> tuple[list[str], str | None]:
+    """(page ids, entry page) for one UI root. Entry is None if undecidable."""
+    pages: list[str] = []
+    entry: str | None = None
+
+    for cfg in ui_root.glob("vite.config.*"):
+        block = _VITE_INPUT_BLOCK.search(cfg.read_text(errors="ignore"))
+        if not block:
+            continue
+        for name, path in _VITE_INPUT_ENTRY.findall(block.group(1)):
+            page = Path(path).name
+            pages.append(page)
+            # Vite convention: `main` (or the only entry) is the app's front door.
+            if name in {"main", "index"} or entry is None:
+                entry = page
+
+    if not pages:
+        for html in ui_root.glob("*.html"):
+            pages.append(html.name)
+        if "index.html" in pages:
+            entry = "index.html"
+        elif len(pages) == 1:
+            entry = pages[0]
+
+    if not pages:
+        routes: set[str] = set()
+        for f in _source_files(ui_root):
+            routes.update(_ROUTE.findall(f.read_text(errors="ignore")))
+        if routes:
+            pages = sorted(routes)
+            entry = "/" if "/" in routes else None
+
+    return sorted(set(pages)), entry
+
+
+def _normalise(target: str, pages: list[str]) -> str | None:
+    """Map a raw href/route to a known page id, or None if it leaves the app."""
+    t = target.strip()
+    if not t or t.startswith(("http://", "https://", "mailto:", "tel:", "javascript:")):
+        return None
+    base = Path(t).name or t
+    if base in pages:
+        return base
+    if t in pages:
+        return t
+    if not t.startswith("/"):
+        cand = "/" + t.lstrip("./")
+        if cand in pages:
+            return cand
+    return None
+
+
+def build_link_graph(ui_root: Path, pages: list[str]) -> dict[str, set[str]]:
+    """page -> pages it links to, from hrefs / <Link to> / navigate() / location.
+
+    A file's edges are attributed to every page whose name it matches, and to
+    every page when the file is shared (a component imported by several pages).
+    Erring toward MORE edges makes the depth estimate optimistic, so an
+    "unreachable" verdict is conservative -- the direction worth erring in when
+    the output is "this feature is hidden".
+    """
+    graph: dict[str, set[str]] = {p: set() for p in pages}
+    for f in _source_files(ui_root):
+        text = f.read_text(errors="ignore")
+        targets = set()
+        for pat in (_HREF, _LINK_TO, _NAVIGATE, _LOCATION):
+            targets.update(pat.findall(text))
+        resolved = {r for t in targets if (r := _normalise(t, pages))}
+        if not resolved:
+            continue
+        owner = f.name if f.name in pages else None
+        for src in ([owner] if owner else pages):
+            graph.setdefault(src, set()).update(resolved - {src})
+    return graph
+
+
+def reachability(graph: dict[str, set[str]], entry: str) -> dict[str, int]:
+    """Shortest-path depth from `entry`. Absent key == not reachable."""
+    depths = {entry: 0}
+    q = deque([entry])
+    while q:
+        cur = q.popleft()
+        for nxt in graph.get(cur, ()):  # noqa: SIM118
+            if nxt not in depths:
+                depths[nxt] = depths[cur] + 1
+                q.append(nxt)
+    return depths
+
+
+def analyse(project_root: Path) -> dict:
+    """{"available": bool, "pages": [...], "entry": str, "depths": {page: int}}.
+
+    `available: False` means the front end could not be located or its entry
+    could not be determined -- callers MUST treat that as "not measured", never
+    as "nothing is reachable".
+    """
+    # A project can hold several front ends (Project O has `web/` and
+    # `web/canvas-next/`, both with a vite config). First-match-wins picked the
+    # thinner one and reported a single unreachable-from-nothing page, so pick
+    # the most substantive graph and record that others exist rather than
+    # silently analysing a stub.
+    candidates = []
+    for ui_root in _ui_roots(project_root):
+        pages, entry = discover_pages(ui_root)
+        if not pages or not entry:
+            continue
+        graph = build_link_graph(ui_root, pages)
+        depths = reachability(graph, entry)
+        candidates.append({
+            "available": True,
+            "ui_root": str(ui_root.relative_to(project_root)) if ui_root != project_root else ".",
+            "pages": pages,
+            "entry": entry,
+            "depths": depths,
+            "unreachable": sorted(set(pages) - set(depths)),
+        })
+    if not candidates:
+        return {"available": False, "reason": "no front end with a determinable entry page found"}
+    candidates.sort(key=lambda c: (len(c["pages"]), len(c["depths"])), reverse=True)
+    best = candidates[0]
+    others = [c["ui_root"] for c in candidates[1:]]
+    if others:
+        best["other_ui_roots"] = others
+    return best
+
+
+def screen_for_target(target: str, analysis: dict) -> str | None:
+    """Which page a criterion's declared `target` file belongs to, if knowable.
+
+    A target that IS a page resolves directly. A component file resolves only
+    when its name matches a page stem; otherwise None -- import-graph tracing is
+    deliberately not attempted here, because guessing which screen a shared
+    component belongs to would reintroduce exactly the fabricated precision this
+    module exists to remove.
+    """
+    if not target or not analysis.get("available"):
+        return None
+    pages = analysis.get("pages", [])
+    direct = _normalise(target, pages)
+    if direct:
+        return direct
+    stem = Path(target).stem.lower()
+    for page in pages:
+        if Path(page).stem.lower() == stem:
+            return page
+    return None

pcp/objective_conflicts.py

@@ -0,0 +1,129 @@
+"""Objective-conflict gate.
+
+Closes a real incident, 2026-07-22 (Project O dogfood): a business
+decision to stop storing business-transaction instances was made and agreed
+2026-07-20; objective.md/target_state.md (human-AUTHORIZED, Hard Rule 2 — see
+`pcp correct-objective` for the propose/diff/approve path) never
+got rewritten; two days later a 30+-agent, multi-million-token `pcp build`
+cycle built exactly the rejected shape end-to-end (storage layer, agent tools,
+UI) — every gate passed, because every gate validates the build against
+objective.md as given, never against whether objective.md is still true.
+
+`capture.py`'s classifier already sets `drift_flag` on a brd_items.yaml entry
+when a captured business item conflicts with objective.md's text — that
+machinery existed and, if it had run, would have caught this. But the flag was
+purely advisory (buried in brd.md prose, three days before the incident, in a
+session nobody reread). This module gives it teeth: an active item with a live
+drift_flag hard-blocks `pcp build` until objective.md/target_state.md is
+actually edited (verified by content hash — proof of an edit, not a checkbox a
+human can click without doing the work) or a human explicitly dismisses it
+with a reason.
+"""
+
+import hashlib
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+_TS_FMT = "%Y-%m-%dT%H:%M:%SZ"
+
+
+def objective_hash(pcp_dir: Path) -> str:
+    """Deterministic fingerprint of the immutable spec files a business
+    correction would need to change. Comparing this at flag-time vs.
+    check-time is the proof an edit actually happened."""
+    parts = []
+    for name in ("objective.md", "target_state.md"):
+        p = pcp_dir / name
+        parts.append(p.read_text() if p.exists() else "")
+    return hashlib.sha256("\x00".join(parts).encode()).hexdigest()
+
+
+def _load_items(pcp_dir: Path) -> list[dict]:
+    path = pcp_dir / "brd_items.yaml"
+    if not path.exists():
+        return []
+    try:
+        data = yaml.safe_load(path.read_text()) or {}
+    except yaml.YAMLError:
+        return []
+    items = data.get("items", [])
+    return items if isinstance(items, list) else []
+
+
+def _save_items(pcp_dir: Path, items: list[dict]) -> None:
+    (pcp_dir / "brd_items.yaml").write_text(yaml.dump({"items": items}, default_flow_style=False))
+
+
+def is_unresolved_conflict(item: dict) -> bool:
+    """One definition of "this conflict is still open", shared by the build
+    gate and every renderer.
+
+    It existed only inside reconcile()'s loop until 2026-07-25, when a real
+    divergence surfaced: `pcp objective-conflicts --dismiss` writes
+    drift_dismissed_at/_reason but deliberately leaves drift_flag set (the flag
+    is the historical record of what was flagged). The gate honoured the
+    dismissal; capture._write_brd_md() filtered on drift_flag alone, so a
+    dismissed item kept rendering under "Drift Flags" in brd.md forever —
+    reporting an open conflict the build no longer had. Any new consumer must
+    call this rather than re-deriving the predicate."""
+    if item.get("status") != "active" or not item.get("drift_flag"):
+        return False
+    return not (item.get("drift_resolved_at") or item.get("drift_dismissed_at"))
+
+
+def reconcile(pcp_dir: Path) -> list[dict]:
+    """Auto-clears drift flags whose objective_hash_at_flag no longer matches
+    current objective.md/target_state.md content -- the file actually got
+    edited since the conflict was raised. Deterministic, no LLM judgment
+    involved in the resolution itself (only in the original flagging, inside
+    capture.py). Returns the still-unresolved conflicts: active, drift_flag
+    set, neither hash-cleared nor dismissed.
+
+    An item with a drift_flag but no objective_hash_at_flag (written before
+    this mechanism existed, or by any other path) is treated as unresolved —
+    fails loud rather than silently trusting an unstamped flag, same posture
+    as this project's other fail-open-gate fixes."""
+    items = _load_items(pcp_dir)
+    current_hash = objective_hash(pcp_dir)
+    now = datetime.now(timezone.utc).strftime(_TS_FMT)
+    changed = False
+    unresolved = []
+
+    for item in items:
+        if not is_unresolved_conflict(item):
+            continue
+        flagged_hash = item.get("objective_hash_at_flag")
+        if flagged_hash and flagged_hash != current_hash:
+            item["drift_resolved_at"] = now
+            item["drift_resolved_reason"] = "objective.md/target_state.md edited since this conflict was flagged"
+            changed = True
+            continue
+        unresolved.append(item)
+
+    if changed:
+        _save_items(pcp_dir, items)
+    return unresolved
+
+
+def dismiss(pcp_dir: Path, item_id: str, reason: str) -> bool:
+    """Human explicitly dismisses a flagged conflict without editing
+    objective.md -- for real false positives (classifier flagged something
+    that doesn't actually require a spec change). Requires a non-empty
+    reason -- same accountability posture as `[pcp-bypass: reason]`. Returns
+    True if a matching active, undismissed, unresolved item was found."""
+    if not reason or not reason.strip():
+        raise ValueError("dismiss requires a non-empty reason")
+    items = _load_items(pcp_dir)
+    now = datetime.now(timezone.utc).strftime(_TS_FMT)
+    found = False
+    for item in items:
+        if item.get("id") == item_id and item.get("drift_flag") and not item.get("drift_resolved_at") and not item.get("drift_dismissed_at"):
+            item["drift_dismissed_at"] = now
+            item["drift_dismissed_reason"] = reason.strip()
+            found = True
+            break
+    if found:
+        _save_items(pcp_dir, items)
+    return found

pcp/operational.py

@@ -0,0 +1,70 @@
+"""Files PCP itself generates while running — never subject matter for a gate.
+
+These are machine-written records *about* the code (telemetry, ledgers, scans,
+audit trails). They are not code, nobody authored them, and no rule should ever
+be evaluated against their contents.
+
+`build.py` already excluded them from criterion diffs. `check.py` did not, and
+that gap produced a real Layer 1 failure on Project O, 2026-07-30:
+
+    reason: R008 matched its own rule text quoted inside generated
+            telemetry.jsonl, not a real property_hints persistence
+
+An `ast_pattern` rule searched `.pcp/telemetry.jsonl` and found its own pattern
+there — because telemetry records the findings of the rules, so a rule's pattern
+text is written into the very file the next commit stages and scans. The gate
+flagged its own audit trail.
+
+The consequence was worse than one false finding. A `[pcp-bypass]` is
+all-or-nothing across rules, so that single self-match caused **R001-R010 to be
+bypassed together** for that commit, in an unattended run, with nobody reading it.
+One false positive from a generated file voided the whole Layer 1 gate.
+
+Kept in its own module because `build.py` imports `check.py`, so the constants
+cannot live in either without a cycle. Any NEW file PCP writes under `.pcp/`
+during a run must be added here at the same time it starts being written.
+"""
+
+OPERATIONAL_PATHS: tuple[str, ...] = (
+    ".pcp/token_ledger.yaml", ".pcp/telemetry.jsonl", ".pcp/decision_log.jsonl",
+    ".pcp/brd.md", ".pcp/brd_items.yaml", ".pcp/coverage_audit.jsonl",
+    ".pcp/escalations.yaml", ".pcp/prune_log.yaml", ".pcp/current_state.md",
+    ".pcp/diff.md", ".pcp/notify_heartbeat.yaml", ".pcp/build_progress.yaml",
+    ".pcp/bypass_log.yaml", ".pcp/audit_trend.jsonl", ".pcp/attestations.jsonl",
+    ".pcp/symbol_fingerprints.json", ".pcp/install_approvals.yaml",
+    ".pcp/run_ledger.jsonl", ".pcp/pressure_test_log.jsonl",
+    ".pcp/audit.md", ".pcp/provenance.md", ".pcp/control_audit.md",
+    ".pcp/build_report.md", ".pcp/design_audit.md", ".pcp/narrative_lint.md",
+    ".pcp/architecture_justification.md",
+    "pcp.md",
+)
+
+OPERATIONAL_DIRS: tuple[str, ...] = (".pcp/evidence/", ".pcp/transcripts/")
+
+
+def is_operational(path: str) -> bool:
+    """Is this a file PCP wrote about itself, rather than project content?
+
+    Note the prefix strip is deliberate and `lstrip` would be wrong here:
+    `lstrip("./")` removes a character SET, so it turns `.pcp/telemetry.jsonl`
+    into `pcp/telemetry.jsonl` and every path stops matching. That is exactly
+    what the first version did, and it silently made this whole module a no-op —
+    the tests caught it, the code read fine.
+    """
+    norm = str(path).replace("\\", "/")
+    while norm.startswith("./"):
+        norm = norm[2:]
+    return norm in OPERATIONAL_PATHS or any(norm.startswith(d) for d in OPERATIONAL_DIRS)
+
+
+def filter_operational(paths: list[str]) -> tuple[list[str], list[str]]:
+    """(paths to gate, paths skipped as PCP's own output).
+
+    Returns both halves rather than silently dropping: a gate that quietly
+    narrows its own scope is indistinguishable from one that found nothing, and
+    that conflation is the single most repeated defect in this codebase.
+    """
+    keep, skipped = [], []
+    for p in paths:
+        (skipped if is_operational(p) else keep).append(p)
+    return keep, skipped