psyclaw 0.27.22 → 0.28.0

package/vendor/ars/scripts/check_pipeline_integrity.py

@@ -0,0 +1,340 @@
+#!/usr/bin/env python3
+"""Advisory verifier for ARS pipeline phase scope (v3.9.2).
+
+Spec: docs/design/2026-05-18-ars-v3.9.2-phase-boundary-spec.md Phase 4
+Issue: #133 (phase scope inflation hot-fix)
+Forward note: v3.10 active conductor (#134) replaces this with deterministic
+provenance-based verification via task envelope; this v3.9.2 advisory is
+heuristic and FP-prone by design.
+
+Usage:
+    python scripts/check_pipeline_integrity.py [workdir]
+    python scripts/check_pipeline_integrity.py --json [workdir]
+
+Default workdir: current directory.
+
+This script SCANS a working directory for `phaseN_*/` subdirectories (where
+N is 1-6 per the ARS pipeline phase convention) and flags advisory signals
+that suggest #133-class scope inflation. Output is ADVISORY ONLY — it does
+NOT block any workflow. User reviews findings and decides.
+
+Detection rules (v3.9.2 lite):
+
+1. **Phase 5 missing independent reviewer attribution** (HIGH-VALUE structural rule)
+   When `phase5_*/` exists but contains no separate files matching the
+   independent-reviewer naming convention (devils_advocate / editor_in_chief /
+   ethics_review / eic / methodology / domain / perspective / editorial_synthesizer),
+   flag INTEGRITY-ADVISORY. This catches the exact #133 reported pattern:
+   a single agent producing phase5_*/ output that looks like a review but was
+   never actually crosschecked by independent reviewer agents.
+
+   **NORMATIVE FILENAME CONVENTION:** This rule is filename-based regex matching
+   over a closed set of agent stem names. For the verifier to recognize a
+   reviewer report, the filename MUST contain one of the canonical agent stems:
+   - `devils_advocate` (or `devil-s_advocate` / `devils-advocate`)
+   - `editor_in_chief` or `eic`
+   - `ethics_review` (the full stem; bare `ethics` does NOT match)
+   - `methodology_review` / `domain_review` / `perspective_review`
+   - `editorial_synth` (matches editorial_synthesizer family)
+
+   Orchestrator runs that emit terse filenames like `round1_ethics.md` (without
+   `_review` suffix) WILL produce a false-positive STRUCTURAL finding here.
+   Resolution options: (a) rename file to match convention, or (b) ignore the
+   advisory finding (verifier exits 0; advisory does not block). The verifier
+   trades filename-convention discipline for zero-dependency cross-platform
+   simplicity in v3.9.2. v3.10 conductor (#134) replaces filename matching
+   with task envelope author provenance.
+
+2. **Multi-phase same-call generation heuristic** (LOWER-VALUE, FP-prone)
+   When files in phaseN_*/ and phase{N+1}_*/ share creation timestamps within
+   a configurable window (default 5 minutes), flag as POSSIBLE same-call
+   inflation. Acknowledged FP risk: legitimate fast orchestrator runs trigger
+   this. Use --strict to enable, default OFF.
+
+Exit codes:
+    0  No findings, or only --strict findings without --strict flag
+    0  Findings produced (advisory output, NOT a hard gate); printed to stdout
+    1  Script error (invalid workdir, IO failure)
+
+The verifier intentionally fails open (exit 0) on findings — it is advisory,
+not a CI gate. CI should not rely on this for v3.9.2.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable
+
+PHASE_DIR_RE = re.compile(r"^phase([1-6])(?:_.*)?$")
+
+# Phase 5 reviewer file-name heuristics. A phase5_*/ directory should contain
+# files whose names match at least one of these per independent crosscheck
+# (Devil's Advocate, Editor-in-Chief, Ethics Review). Missing all three →
+# advisory flag per #133 root pattern.
+PHASE5_REVIEWER_PATTERNS = {
+    "devils_advocate": re.compile(r"devils?[_-]?advocate", re.IGNORECASE),
+    "editor_in_chief": re.compile(r"(?:editor[_-]?in[_-]?chief|^eic|[_-]eic[_-])", re.IGNORECASE),
+    "ethics_review": re.compile(r"ethics?[_-]?review", re.IGNORECASE),
+    "methodology_reviewer": re.compile(r"methodology[_-]?review", re.IGNORECASE),
+    "domain_reviewer": re.compile(r"domain[_-]?review", re.IGNORECASE),
+    "perspective_reviewer": re.compile(r"perspective[_-]?review", re.IGNORECASE),
+    "editorial_synthesizer": re.compile(r"editorial[_-]?synth", re.IGNORECASE),
+}
+
+# Required minimum reviewer attributions for a valid Phase 5 output per
+# academic-pipeline Stage 3 review protocol. At least one from each category
+# must appear in phase5_*/ filenames.
+PHASE5_REQUIRED_CATEGORIES = [
+    ("devil's advocate", ["devils_advocate"]),
+    ("editorial/EIC", ["editor_in_chief", "editorial_synthesizer"]),
+    ("ethics or panel reviewer", ["ethics_review", "methodology_reviewer", "domain_reviewer", "perspective_reviewer"]),
+]
+
+DEFAULT_SAME_CALL_WINDOW_SECONDS = 300  # 5 minutes
+
+
+@dataclass
+class Finding:
+    rule: str
+    severity: str  # ADVISORY (default), STRUCTURAL (high-value), HEURISTIC (FP-prone)
+    phase: int | None
+    path: str
+    message: str
+
+
+@dataclass
+class Report:
+    workdir: str
+    phase_dirs: dict[int, list[str]] = field(default_factory=dict)  # phase → list of dir paths
+    findings: list[Finding] = field(default_factory=list)
+
+
+def scan_workdir(workdir: Path) -> Report:
+    """Locate all phase{1-6}_*/ subdirectories under workdir."""
+    report = Report(workdir=str(workdir))
+    if not workdir.is_dir():
+        return report
+
+    for entry in workdir.iterdir():
+        if not entry.is_dir():
+            continue
+        match = PHASE_DIR_RE.match(entry.name)
+        if not match:
+            continue
+        phase = int(match.group(1))
+        report.phase_dirs.setdefault(phase, []).append(str(entry))
+    return report
+
+
+def check_phase5_attribution(report: Report) -> None:
+    """Rule 1 — STRUCTURAL: phase5_*/ must contain independent reviewer files."""
+    phase5_dirs = report.phase_dirs.get(5, [])
+    if not phase5_dirs:
+        return
+
+    for dir_path in phase5_dirs:
+        path = Path(dir_path)
+        try:
+            # Skip hidden files (.DS_Store, Thumbs.db, .gitkeep, etc.) — they're
+            # never reviewer reports and would clutter advisory output noise.
+            files = [
+                p.name for p in path.rglob("*")
+                if p.is_file() and not p.name.startswith(".")
+            ]
+        except OSError as exc:
+            report.findings.append(Finding(
+                rule="phase5_attribution_io_error",
+                severity="ADVISORY",
+                phase=5,
+                path=dir_path,
+                message=f"Could not read phase5 directory: {exc}",
+            ))
+            continue
+
+        if not files:
+            report.findings.append(Finding(
+                rule="phase5_empty",
+                severity="ADVISORY",
+                phase=5,
+                path=dir_path,
+                message="phase5_*/ directory is empty — Phase 5 should produce review reports",
+            ))
+            continue
+
+        # Tally which reviewer categories are present
+        matched_agents: set[str] = set()
+        for fname in files:
+            for agent, pattern in PHASE5_REVIEWER_PATTERNS.items():
+                if pattern.search(fname):
+                    matched_agents.add(agent)
+
+        missing_categories: list[str] = []
+        for category_label, agent_list in PHASE5_REQUIRED_CATEGORIES:
+            if not any(agent in matched_agents for agent in agent_list):
+                missing_categories.append(category_label)
+
+        if missing_categories:
+            report.findings.append(Finding(
+                rule="phase5_missing_independent_reviewer",
+                severity="STRUCTURAL",
+                phase=5,
+                path=dir_path,
+                message=(
+                    f"phase5_*/ missing independent reviewer attribution for categories: "
+                    f"{', '.join(missing_categories)}. "
+                    f"Files found: {files[:5]}{'...' if len(files) > 5 else ''}. "
+                    f"#133 pattern: Phase 5 deliverable was likely produced by a single agent "
+                    f"that inflated past its scope, skipping mandatory independent crosschecks "
+                    f"(DA / EIC / Ethics). Re-run via orchestrator-driven Mode A with "
+                    f"`/ars-full` or invoke each reviewer agent separately."
+                ),
+            ))
+
+
+def _file_mtime(path: Path) -> float | None:
+    try:
+        return path.stat().st_mtime
+    except OSError:
+        return None
+
+
+def check_same_call_heuristic(report: Report, window_seconds: int) -> None:
+    """Rule 2 — HEURISTIC (--strict only): adjacent-phase same-window timestamps."""
+    phases_present = sorted(report.phase_dirs.keys())
+    if len(phases_present) < 2:
+        return
+
+    # Collect (phase, file_path, mtime) tuples
+    file_records: dict[int, list[tuple[Path, float]]] = {}
+    for phase, dirs in report.phase_dirs.items():
+        records: list[tuple[Path, float]] = []
+        for dir_path in dirs:
+            path = Path(dir_path)
+            for file_path in path.rglob("*"):
+                if not file_path.is_file():
+                    continue
+                mtime = _file_mtime(file_path)
+                if mtime is None:
+                    continue
+                records.append((file_path, mtime))
+        if records:
+            file_records[phase] = records
+
+    # For each adjacent (N, N+1) pair, find files with mtime within window
+    for phase in phases_present:
+        next_phase = phase + 1
+        if next_phase not in file_records:
+            continue
+        for file_a, mtime_a in file_records.get(phase, []):
+            for file_b, mtime_b in file_records[next_phase]:
+                delta = abs(mtime_a - mtime_b)
+                if delta <= window_seconds:
+                    report.findings.append(Finding(
+                        rule="adjacent_phase_same_window",
+                        severity="HEURISTIC",
+                        phase=phase,
+                        path=str(file_a),
+                        message=(
+                            f"phase{phase} file {file_a.name} and phase{next_phase} file "
+                            f"{file_b.name} share mtime within {int(delta)}s "
+                            f"(window={window_seconds}s). POSSIBLE same-call inflation. "
+                            f"Note: legitimate fast orchestrator runs also trigger this "
+                            f"heuristic — verify against orchestrator state ledger before "
+                            f"treating as #133-class violation."
+                        ),
+                    ))
+
+
+def format_text(report: Report) -> str:
+    lines = [f"ARS pipeline integrity check (v3.9.2 advisory)"]
+    lines.append(f"Workdir: {report.workdir}")
+    lines.append(f"Phase dirs found: {dict(sorted(report.phase_dirs.items()))}")
+    lines.append("")
+    if not report.findings:
+        lines.append("No advisory findings.")
+        return "\n".join(lines)
+
+    lines.append(f"Findings ({len(report.findings)}):")
+    for i, finding in enumerate(report.findings, 1):
+        lines.append("")
+        lines.append(f"  [{i}] {finding.severity} — {finding.rule}")
+        if finding.phase is not None:
+            lines.append(f"      Phase: {finding.phase}")
+        lines.append(f"      Path:  {finding.path}")
+        lines.append(f"      {finding.message}")
+
+    lines.append("")
+    lines.append("Reminder: this output is ADVISORY. Findings do NOT block any workflow.")
+    lines.append("See docs/design/2026-05-18-ars-v3.9.2-phase-boundary-spec.md for rationale.")
+    return "\n".join(lines)
+
+
+def format_json(report: Report) -> str:
+    payload = {
+        "workdir": report.workdir,
+        "phase_dirs": {str(k): v for k, v in sorted(report.phase_dirs.items())},
+        "findings": [
+            {
+                "rule": f.rule,
+                "severity": f.severity,
+                "phase": f.phase,
+                "path": f.path,
+                "message": f.message,
+            }
+            for f in report.findings
+        ],
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=False)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Advisory check for ARS pipeline phase scope inflation (v3.9.2)"
+    )
+    parser.add_argument(
+        "workdir",
+        nargs="?",
+        default=".",
+        help="Working directory to scan (default: current directory)",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Enable heuristic same-call timestamp check (FP-prone, default OFF)",
+    )
+    parser.add_argument(
+        "--window-seconds",
+        type=int,
+        default=DEFAULT_SAME_CALL_WINDOW_SECONDS,
+        help=f"Same-call window for --strict heuristic (default: {DEFAULT_SAME_CALL_WINDOW_SECONDS}s)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output JSON instead of human-readable text",
+    )
+    args = parser.parse_args(argv)
+
+    workdir = Path(args.workdir).resolve()
+    if not workdir.is_dir():
+        print(f"ERROR: workdir not found or not a directory: {workdir}", file=sys.stderr)
+        return 1
+
+    report = scan_workdir(workdir)
+    check_phase5_attribution(report)
+    if args.strict:
+        check_same_call_heuristic(report, args.window_seconds)
+
+    if args.json:
+        print(format_json(report))
+    else:
+        print(format_text(report))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/vendor/ars/scripts/check_policy_anchor_protocol.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""#108 policy_anchor_disclosure_protocol.md static lint.
+
+Decision Doc reference:
+  docs/design/2026-05-14-ai-disclosure-schema-decision.md §4.1 (item 6) +
+  §4.3 invariants + §4.4 11 open concerns + §3 G10 7-row precedence table.
+
+Implementation spec reference:
+  docs/design/2026-05-14-ai-disclosure-impl-spec.md §3 (resolved-paths table).
+
+This lint enforces presence-of-required-content invariants on the protocol
+doc the LLM reads at runtime when in `disclosure` mode with
+`--policy-anchor=<a>` selector.
+
+Checks
+------
+1. All 8 §4.3 invariants are named verbatim (G1 / G2 / G3 / G10 / G4 / G5 /
+   G7 / G8 / G9 — G3 and G10 combined into a single composite invariant).
+2. All 11 §4.4 concerns have a resolution clause referenced by number
+   (`concern #1` through `concern #11`).
+3. The §3 G10 7-row precedence table is present with all 7 rows
+   (numbered 1..7).
+4. The auto-promotion forbiddance clause is present (G3/G10 invariant
+   load-bearing constraint).
+5. The 4 canonical anchor slugs are enumerated in the lookup mechanism
+   section.
+6. The Nature ↔ v3.2 venue dedup pointer
+   (`shared/policy_data/nature_policy.md`) is referenced.
+
+Exit codes
+----------
+  0 - all checks pass
+  1 - one or more violations
+  2 - invocation error
+
+Usage
+-----
+  python scripts/check_policy_anchor_protocol.py academic-paper/references/policy_anchor_disclosure_protocol.md
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+REQUIRED_INVARIANTS = (
+    "G1 invariant",
+    "G2 invariant",
+    "G3 / G10 invariant",
+    "G4 invariant",
+    "G5 invariant",
+    "G7 invariant",
+    "G8 invariant",
+    "G9 invariant",
+)
+REQUIRED_CONCERN_NUMBERS = tuple(range(1, 12))
+REQUIRED_CONCERNS = tuple(f"concern #{i}" for i in REQUIRED_CONCERN_NUMBERS)
+REQUIRED_ANCHOR_SLUGS = ("prisma-trAIce", "icmje", "nature", "ieee")
+DEDUP_POINTER = "shared/policy_data/nature_policy.md"
+# The auto-promotion clause is the load-bearing G3/G10 invariant; both
+# tokens MUST be present so a partial deletion (heading word but not the
+# prohibition sentence, or vice versa) cannot silently satisfy the lint.
+AUTO_PROMOTION_REQUIRED_TOKENS = (
+    "auto-promotion",
+    "MUST NOT be rendered as though USED",
+)
+
+CONCERN_PATTERN = re.compile(r"concern\s+#(\d+)\b")
+TABLE_ROW_PATTERN = re.compile(r"^\s*\|\s*(\d+)\s*\|", re.MULTILINE)
+ANCHOR_INVENTORY_PATTERN = re.compile(
+    r"^\*\*Anchor inventory\*\*:\s*`([^`]+)`", re.MULTILINE
+)
+
+
+def lint_text(text: str) -> list[str]:
+    violations: list[str] = []
+
+    for inv in REQUIRED_INVARIANTS:
+        if inv not in text:
+            violations.append(f"missing required invariant reference: {inv}")
+
+    # Word-boundary match prevents `concern #1` from matching against
+    # `concern #10` / `concern #11`.
+    found_concern_numbers = {int(m.group(1)) for m in CONCERN_PATTERN.finditer(text)}
+    for n in REQUIRED_CONCERN_NUMBERS:
+        if n not in found_concern_numbers:
+            violations.append(f"missing §4.4 concern #{n} resolution clause")
+
+    # Match real markdown table rows (`| N |` at line start); a prose
+    # `row 4` mention elsewhere in the doc does not satisfy the check.
+    found_rows = {int(m.group(1)) for m in TABLE_ROW_PATTERN.finditer(text)}
+    for row in range(1, 8):
+        if row not in found_rows:
+            violations.append(
+                f"missing G10 7-row precedence row {row} (no `| {row} |` markdown row found)"
+            )
+
+    for token in AUTO_PROMOTION_REQUIRED_TOKENS:
+        if token not in text:
+            violations.append(
+                "missing auto-promotion forbiddance clause "
+                f"(G3/G10 UNCERTAIN-not-USED invariant); token missing: '{token}'"
+            )
+
+    inventory_line = ANCHOR_INVENTORY_PATTERN.search(text)
+    if not inventory_line:
+        violations.append("missing `**Anchor inventory**: ...` line in protocol doc")
+    else:
+        inventory_slugs = {
+            s.strip() for s in inventory_line.group(1).split(",") if s.strip()
+        }
+        canonical = set(REQUIRED_ANCHOR_SLUGS)
+        missing = canonical - inventory_slugs
+        extra = inventory_slugs - canonical
+        for slug in sorted(missing):
+            violations.append(
+                f"missing canonical anchor slug from inventory: {slug} "
+                f"(found inventory: {sorted(inventory_slugs)})"
+            )
+        for slug in sorted(extra):
+            violations.append(
+                f"unexpected anchor slug in inventory: {slug} (closed enum is "
+                f"{sorted(canonical)}; remove it from the inventory line or "
+                "expand the canonical enum first)"
+            )
+
+    if DEDUP_POINTER not in text:
+        violations.append(
+            f"missing Nature ↔ v3.2 venue dedup pointer: {DEDUP_POINTER}"
+        )
+
+    return violations
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default="academic-paper/references/policy_anchor_disclosure_protocol.md",
+        help="path to policy_anchor_disclosure_protocol.md (default: %(default)s)",
+    )
+    args = parser.parse_args(argv)
+    target = Path(args.path)
+    if not target.exists():
+        print(f"error: file not found: {target}", file=sys.stderr)
+        return 2
+    text = target.read_text(encoding="utf-8")
+    violations = lint_text(text)
+    if violations:
+        for v in violations:
+            print(f"{target}: {v}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())