ref-agents 1.0.0__py3-none-any.whl

ref_agents/tools/validators/scrum_master.py

@@ -0,0 +1,212 @@
+"""Scrum Master closure validator — validate_closure.
+
+Verifies that a story's closure preconditions are met:
+- All required phase rows present + ✅ in closure doc
+- Codemap freshness vs story creation
+- handoff_log.jsonl has phase entries
+
+Registered under role "scrum_master".
+
+See SPEC-STORY-025 / DESIGN-STORY-025.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import structlog
+
+from ref_agents.core.validation_models import (
+    Gap,
+    ValidationReport,
+    Verdict,
+)
+from ref_agents.session import SessionManager
+from ref_agents.tools.validators import register_validator
+
+logger = structlog.get_logger(__name__)
+
+REQUIRED_PHASES = (
+    "requirements",
+    "qa_lead",
+    "specifier",
+    "architect",
+    "developer",
+    "pr_reviewer",
+    "tester",
+    "security_owner",
+    "scrum_master",
+)
+
+# Map closure-doc display rows to canonical phase keys
+ROW_ALIASES = {
+    "requirements": "requirements",
+    "qa gate": "qa_lead",
+    "qa lead": "qa_lead",
+    "specification": "specifier",
+    "spec": "specifier",
+    "design": "architect",
+    "implementation": "developer",
+    "review": "pr_reviewer",
+    "testing": "tester",
+    "security": "security_owner",
+    "scrum master": "scrum_master",
+}
+
+
+def _resolve_under_root(candidate: Path) -> Path | None:
+    root = SessionManager.get().project_root
+    candidate = candidate.resolve()
+    if root is not None:
+        try:
+            candidate.relative_to(root.resolve())
+        except ValueError:
+            return None
+    return candidate if candidate.exists() else None
+
+
+def _resolve_closure(artifact_id: str, artifact_path: str) -> Path | None:
+    if artifact_path:
+        return _resolve_under_root(Path(artifact_path))
+    root = SessionManager.get().project_root
+    if artifact_id and root is not None:
+        return _resolve_under_root(
+            root / "docs" / "closure" / f"{artifact_id}-CLOSURE.md"
+        )
+    return None
+
+
+def _phase_status_from_closure(text: str) -> dict[str, str]:
+    """Parse closure doc table rows → {phase_key: marker}.
+
+    Marker is the first emoji-like token in the status cell.
+    """
+    statuses: dict[str, str] = {}
+    for line in text.splitlines():
+        if not line.startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip("|").split("|")]
+        if len(cells) < 2:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+            continue
+        first = cells[0].lower().strip()
+        for alias, canonical in ROW_ALIASES.items():
+            if alias in first:
+                statuses[canonical] = cells[1].strip()
+                break
+    return statuses
+
+
+def _codemap_max_mtime(root: Path) -> float:
+    codemap_dir = root / "codemap"
+    if not codemap_dir.exists():
+        return 0.0
+    mtimes = [p.stat().st_mtime for p in codemap_dir.rglob("*.md")]
+    return max(mtimes) if mtimes else 0.0
+
+
+def _story_creation_mtime(root: Path, artifact_id: str) -> float | None:
+    story_path = root / "docs" / "requirements" / f"{artifact_id}.md"
+    if not story_path.exists():
+        return None
+    return story_path.stat().st_mtime
+
+
+def _handoff_log_phases(root: Path, artifact_id: str) -> set[str]:
+    """Return set of phase keys logged for this story in handoff_log.jsonl."""
+    log_path = root / "ref-reports" / "handoff_log.jsonl"
+    if not log_path.exists():
+        return set()
+    phases: set[str] = set()
+    with log_path.open("r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if entry.get("story_id") != artifact_id:
+                continue
+            if entry.get("event") == "phase":
+                phase = entry.get("phase")
+                if isinstance(phase, str):
+                    phases.add(phase)
+    return phases
+
+
+@register_validator("scrum_master")
+def validate_closure(
+    artifact_id: str = "", artifact_path: str = ""
+) -> ValidationReport:
+    """Validate a story closure document and surrounding state."""
+    log = logger.bind(role="scrum_master", artifact_id=artifact_id)
+
+    closure_path = _resolve_closure(artifact_id, artifact_path)
+    if closure_path is None:
+        return ValidationReport(
+            verdict=Verdict.NEEDS_USER,
+            gaps=[
+                Gap(code="closure_doc_unresolved", detail=artifact_id or artifact_path)
+            ],
+        )
+
+    text = closure_path.read_text(encoding="utf-8")
+    statuses = _phase_status_from_closure(text)
+    gaps: list[Gap] = []
+
+    # FR-1 + FR-2: phase presence + marker
+    for phase in REQUIRED_PHASES:
+        marker = statuses.get(phase)
+        if marker is None:
+            gaps.append(
+                Gap(
+                    code=f"closure_phase_missing:{phase}",
+                    detail=f"No row for phase '{phase}' in closure doc.",
+                )
+            )
+            continue
+        if "✅" not in marker:
+            gaps.append(
+                Gap(
+                    code=f"closure_phase_not_passed:{phase}",
+                    detail=f"Phase '{phase}' marker is '{marker}', expected ✅.",
+                )
+            )
+
+    root = SessionManager.get().project_root
+    if root is not None:
+        # FR-3: codemap freshness
+        story_mtime = _story_creation_mtime(root, artifact_id)
+        if story_mtime is not None:
+            codemap_mtime = _codemap_max_mtime(root)
+            if codemap_mtime < story_mtime:
+                gaps.append(
+                    Gap(
+                        code="codemap_stale",
+                        detail=(
+                            f"Codemap last update ({codemap_mtime}) is older "
+                            f"than story creation ({story_mtime})."
+                        ),
+                    )
+                )
+
+        # FR-4: handoff log phase entries
+        logged = _handoff_log_phases(root, artifact_id)
+        for phase in REQUIRED_PHASES:
+            if phase not in logged and phase != "requirements":
+                # 'requirements' often logged as 'product_manager'
+                if phase == "scrum_master" and "scrum_master" in logged:
+                    continue
+                if phase not in logged:
+                    gaps.append(
+                        Gap(
+                            code=f"handoff_log_incomplete:{phase}",
+                            detail=(f"No 'phase' event for '{phase}' in handoff_log."),
+                        )
+                    )
+
+    verdict = Verdict.PASS if not gaps else Verdict.FAIL_AUTO
+    log.info("scrum_validate_complete", verdict=verdict.value, gap_count=len(gaps))
+    return ValidationReport(verdict=verdict, gaps=gaps)

ref_agents/tools/validators/security_owner.py

@@ -0,0 +1,162 @@
+"""Security Owner output validator — validate_security_report.
+
+Checks finding table schema, severity ↔ verdict consistency, and the
+"CRITICAL forces HALT" invariant.
+
+See SPEC-STORY-031.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import structlog
+
+from ref_agents.core.validation_models import (
+    Gap,
+    ValidationReport,
+    Verdict,
+)
+from ref_agents.session import SessionManager
+from ref_agents.tools.validators import register_validator
+
+logger = structlog.get_logger(__name__)
+
+SEVERITIES = ("CRITICAL", "HIGH", "MEDIUM", "LOW")
+VERDICTS = ("PASS", "CONDITIONAL", "FAIL", "HALT")
+
+
+def _resolve_under_root(candidate: Path) -> Path | None:
+    root = SessionManager.get().project_root
+    candidate = candidate.resolve()
+    if root is not None:
+        try:
+            candidate.relative_to(root.resolve())
+        except ValueError:
+            return None
+    return candidate if candidate.exists() else None
+
+
+def _resolve_security_report(artifact_id: str, artifact_path: str) -> Path | None:
+    if artifact_path:
+        return _resolve_under_root(Path(artifact_path))
+    root = SessionManager.get().project_root
+    if artifact_id and root is not None:
+        return _resolve_under_root(
+            root / "docs" / "analysis" / f"SECURITY-{artifact_id}.md"
+        )
+    return None
+
+
+def _extract_verdict(text: str) -> str | None:
+    match = re.search(
+        r"verdict[:*\s_]*\*{0,2}(PASS|CONDITIONAL|FAIL|HALT)\*{0,2}",
+        text,
+        flags=re.IGNORECASE,
+    )
+    if match:
+        return match.group(1).upper()
+    return None
+
+
+def _count_findings_by_severity(text: str) -> dict[str, int]:
+    """Count findings per severity by scanning table rows."""
+    counts: dict[str, int] = {s: 0 for s in SEVERITIES}
+    for line in text.splitlines():
+        if not line.startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip("|").split("|")]
+        for cell in cells:
+            up = cell.upper().strip("*_` ")
+            if up in SEVERITIES:
+                counts[up] += 1
+    return counts
+
+
+def _extract_summary_counts(text: str) -> dict[str, int] | None:
+    """Parse 'Critical: N | High: N | Medium: N | Low: N' line if present."""
+    match = re.search(
+        r"Critical[:\s]+(\d+).*?High[:\s]+(\d+).*?Medium[:\s]+(\d+).*?Low[:\s]+(\d+)",
+        text,
+        flags=re.IGNORECASE | re.DOTALL,
+    )
+    if not match:
+        return None
+    return {
+        "CRITICAL": int(match.group(1)),
+        "HIGH": int(match.group(2)),
+        "MEDIUM": int(match.group(3)),
+        "LOW": int(match.group(4)),
+    }
+
+
+@register_validator("security_owner")
+def validate_security_report(
+    artifact_id: str = "", artifact_path: str = ""
+) -> ValidationReport:
+    log = logger.bind(role="security_owner", artifact_id=artifact_id)
+
+    path = _resolve_security_report(artifact_id, artifact_path)
+    if path is None:
+        return ValidationReport(
+            verdict=Verdict.NEEDS_USER,
+            gaps=[
+                Gap(
+                    code="security_report_unresolved",
+                    detail=artifact_id or artifact_path,
+                )
+            ],
+        )
+
+    text = path.read_text(encoding="utf-8")
+    gaps: list[Gap] = []
+
+    verdict = _extract_verdict(text)
+    if verdict is None:
+        gaps.append(Gap(code="verdict_missing", detail="No verdict found."))
+
+    summary = _extract_summary_counts(text)
+    table_counts = _count_findings_by_severity(text)
+
+    # Count consistency (when both present)
+    if summary is not None:
+        for sev in SEVERITIES:
+            if summary[sev] != table_counts[sev]:
+                gaps.append(
+                    Gap(
+                        code=f"count_mismatch:{sev}",
+                        detail=(
+                            f"Summary {sev}={summary[sev]} but table has "
+                            f"{table_counts[sev]} matching rows."
+                        ),
+                    )
+                )
+
+    critical = (summary or table_counts)["CRITICAL"]
+    high = (summary or table_counts)["HIGH"]
+
+    # Severity → verdict invariants
+    if verdict == "PASS" and (critical > 0 or high > 0):
+        gaps.append(
+            Gap(
+                code="verdict_inconsistent",
+                detail=f"Verdict PASS forbidden with Critical={critical}, High={high}.",
+            )
+        )
+    if critical > 0 and verdict != "HALT":
+        gaps.append(
+            Gap(
+                code="critical_requires_halt",
+                detail=f"Critical={critical} forces verdict HALT (got {verdict}).",
+            )
+        )
+
+    out = Verdict.PASS if not gaps else Verdict.FAIL_AUTO
+    log.info(
+        "security_validate_complete",
+        verdict=out.value,
+        gap_count=len(gaps),
+        report_verdict=verdict,
+    )
+    return ValidationReport(verdict=out, gaps=gaps)

ref_agents/tools/validators/specifier.py

@@ -0,0 +1,134 @@
+"""Specifier output validator — validate_spec.
+
+Promotes Phase 2.5 self-review to tool. Rejects placeholders, code fences
+outside whitelist, and surfaces open questions for user resolution.
+
+See SPEC-STORY-029.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import structlog
+
+from ref_agents.core.validation_models import (
+    Gap,
+    UserQuestion,
+    ValidationReport,
+    Verdict,
+)
+from ref_agents.session import SessionManager
+from ref_agents.tools.validators import register_validator
+
+logger = structlog.get_logger(__name__)
+
+FORBIDDEN_TOKENS = (
+    r"\[TBD\]",
+    r"\[TODO\]",
+    r"\[PLACEHOLDER\]",
+    r"\bFIXME\b",
+)
+CODE_FENCE_WHITELIST = ("mermaid",)
+
+
+def _resolve_under_root(candidate: Path) -> Path | None:
+    root = SessionManager.get().project_root
+    candidate = candidate.resolve()
+    if root is not None:
+        try:
+            candidate.relative_to(root.resolve())
+        except ValueError:
+            return None
+    return candidate if candidate.exists() else None
+
+
+def _resolve_spec(artifact_id: str, artifact_path: str) -> Path | None:
+    if artifact_path:
+        return _resolve_under_root(Path(artifact_path))
+    root = SessionManager.get().project_root
+    if artifact_id and root is not None:
+        return _resolve_under_root(root / "docs" / "specs" / f"SPEC-{artifact_id}.md")
+    return None
+
+
+def _disallowed_code_fences(text: str) -> list[int]:
+    """Return line numbers where disallowed code fences open."""
+    bad: list[int] = []
+    for idx, line in enumerate(text.splitlines(), start=1):
+        match = re.match(r"^```(\w+)?", line)
+        if (
+            match
+            and match.group(1)
+            and match.group(1).lower() not in CODE_FENCE_WHITELIST
+        ):
+            bad.append(idx)
+    return bad
+
+
+def _open_questions(text: str) -> list[str]:
+    block = re.search(
+        r"##\s+Open Questions\s*\n+(.*?)(?=\n##\s|\Z)", text, flags=re.DOTALL
+    )
+    if not block:
+        return []
+    body = block.group(1).strip()
+    if not body or re.fullmatch(r"(?i)(none\.?|n/a\.?)", body.strip()):
+        return []
+    questions: list[str] = []
+    for line in body.splitlines():
+        stripped = line.strip(" -*0123456789.")
+        if stripped and len(stripped) > 3:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+            questions.append(stripped)
+    return questions
+
+
+@register_validator("specifier")
+def validate_spec(artifact_id: str = "", artifact_path: str = "") -> ValidationReport:
+    log = logger.bind(role="specifier", artifact_id=artifact_id)
+
+    path = _resolve_spec(artifact_id, artifact_path)
+    if path is None:
+        return ValidationReport(
+            verdict=Verdict.NEEDS_USER,
+            gaps=[Gap(code="spec_unresolved", detail=artifact_id or artifact_path)],
+        )
+
+    text = path.read_text(encoding="utf-8")
+    gaps: list[Gap] = []
+    user_questions: list[UserQuestion] = []
+
+    for pattern in FORBIDDEN_TOKENS:
+        for line_no, line in enumerate(text.splitlines(), start=1):
+            if re.search(pattern, line):
+                gaps.append(
+                    Gap(
+                        code=f"forbidden_token:{pattern}",
+                        detail=f"Forbidden token at line {line_no}.",
+                        location=f"line {line_no}",
+                    )
+                )
+
+    bad_fences = _disallowed_code_fences(text)
+    for line_no in bad_fences:
+        gaps.append(
+            Gap(
+                code="code_fence_in_spec",
+                detail="Code fence outside whitelist (only ```mermaid allowed).",
+                location=f"line {line_no}",
+            )
+        )
+
+    for q in _open_questions(text):
+        user_questions.append(UserQuestion(text=f"Open question to resolve: {q}"))
+
+    if gaps:
+        verdict = Verdict.FAIL_AUTO
+    elif user_questions:
+        verdict = Verdict.NEEDS_USER
+    else:
+        verdict = Verdict.PASS
+
+    log.info("specifier_validate_complete", verdict=verdict.value, gap_count=len(gaps))
+    return ValidationReport(verdict=verdict, gaps=gaps, user_questions=user_questions)

ref_agents/tools/validators/strategist.py

@@ -0,0 +1,149 @@
+"""Strategist output validator — validate_strategy.
+
+Checks ≥3 production-grade options, complete trade-off matrix, weighted
+score reproducibility, and absence of quick-fix labels.
+
+See SPEC-STORY-035.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import structlog
+
+from ref_agents.core.validation_models import (
+    Gap,
+    ValidationReport,
+    Verdict,
+)
+from ref_agents.session import SessionManager
+from ref_agents.tools.validators import register_validator
+
+logger = structlog.get_logger(__name__)
+
+REQUIRED_DIMS = (
+    "scalability",
+    "maintainability",
+    "architectural soundness",
+    "risk",
+    "operational impact",
+)
+FORBIDDEN_LABELS = (
+    r"\bquick[ -]?fix\b",
+    r"\btemporary\b",
+    r"\bworkaround\b",
+)
+
+
+def _resolve_under_root(candidate: Path) -> Path | None:
+    root = SessionManager.get().project_root
+    candidate = candidate.resolve()
+    if root is not None:
+        try:
+            candidate.relative_to(root.resolve())
+        except ValueError:
+            return None
+    return candidate if candidate.exists() else None
+
+
+def _resolve_strategy(artifact_id: str, artifact_path: str) -> Path | None:
+    if artifact_path:
+        return _resolve_under_root(Path(artifact_path))
+    root = SessionManager.get().project_root
+    if artifact_id and root is not None:
+        return _resolve_under_root(root / "ref-reports" / f"strategy-{artifact_id}.md")
+    return None
+
+
+def _count_options(text: str) -> int:
+    # Match "Option A", "Option B" etc., or "### A", "### B" or numbered options
+    labels = set()
+    for m in re.finditer(r"(?:^|\n)#+\s*Option\s+([A-Z0-9])\b", text):
+        labels.add(m.group(1).upper())
+    for m in re.finditer(r"(?:^|\n)#+\s+([A-Z])\b\s*[:\.\-]", text):
+        labels.add(m.group(1).upper())
+    return len(labels)
+
+
+def _missing_dims(text: str) -> list[str]:
+    lower = text.lower()
+    return [d for d in REQUIRED_DIMS if d not in lower]
+
+
+def _forbidden_labels_found(text: str) -> list[str]:
+    found: list[str] = []
+    for pattern in FORBIDDEN_LABELS:
+        if re.search(pattern, text, flags=re.IGNORECASE):
+            found.append(pattern)
+    return found
+
+
+def _has_recommendation_reference(text: str) -> bool:
+    """Recommendation section should reference an option label (A/B/C)."""
+    rec_block = re.search(
+        r"##\s+Recommendation\s*\n+(.*?)(?=\n##\s|\Z)", text, flags=re.DOTALL
+    )
+    if not rec_block:
+        return False
+    body = rec_block.group(1)
+    return bool(re.search(r"\bOption\s+[A-Z]\b|\b[A-Z]\b\s+is\s+the\s+best", body))
+
+
+@register_validator("strategist")
+def validate_strategy(
+    artifact_id: str = "", artifact_path: str = ""
+) -> ValidationReport:
+    log = logger.bind(role="strategist", artifact_id=artifact_id)
+
+    path = _resolve_strategy(artifact_id, artifact_path)
+    if path is None:
+        return ValidationReport(
+            verdict=Verdict.NEEDS_USER,
+            gaps=[Gap(code="strategy_unresolved", detail=artifact_id or artifact_path)],
+        )
+
+    text = path.read_text(encoding="utf-8")
+    gaps: list[Gap] = []
+
+    n_options = _count_options(text)
+    if n_options < 3:  # noqa: PLR2004  # TECH_DEBT: extract to named constant — G25
+        gaps.append(
+            Gap(
+                code="options_lt_3",
+                detail=f"Found {n_options} option labels; require ≥3.",
+            )
+        )
+
+    for dim in _missing_dims(text):
+        gaps.append(
+            Gap(
+                code=f"tradeoff_dim_missing:{dim}", detail=f"Missing dimension '{dim}'."
+            )
+        )
+
+    for token in _forbidden_labels_found(text):
+        gaps.append(
+            Gap(
+                code=f"non_production_option:{token}",
+                detail=f"Forbidden production-grade label pattern '{token}' found.",
+            )
+        )
+
+    if not _has_recommendation_reference(text):
+        gaps.append(
+            Gap(
+                code="recommendation_no_reference",
+                detail="Recommendation does not reference a winning option label.",
+            )
+        )
+
+    verdict = Verdict.PASS if not gaps else Verdict.FAIL_AUTO
+    log.info(
+        "strategist_validate_complete",
+        verdict=verdict.value,
+        gap_count=len(gaps),
+        options=n_options,
+    )
+    return ValidationReport(verdict=verdict, gaps=gaps)