@surlymochan/evalid 0.0.0-stage → 0.3.1

package/xflow/atoms/j4a_spec_consistency_structural.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""
+J4a.spec_consistency.structural — Deterministic structural drift check.
+Extends doctor.py with proposal/plan/AHA consistency checks.
+Catches ~80% of drifts deterministically. Semantic drift stays LLM-driven (J4b).
+"""
+import sys, os, json, argparse, re
+
+def load_json_if_exists(path):
+    if os.path.exists(path):
+        try:
+            return json.loads(open(path).read())
+        except Exception:
+            return None
+    return None
+
+def load_text_if_exists(path):
+    if os.path.exists(path):
+        return open(path).read()
+    return None
+
+def extract_section_headings(md_text):
+    """Extract all ## and ### headings from markdown."""
+    if not md_text:
+        return []
+    return re.findall(r'^#{1,3} (.+)$', md_text, re.MULTILINE)
+
+def extract_task_items(md_text):
+    """Extract task checklist items from markdown."""
+    if not md_text:
+        return []
+    return re.findall(r'- \[[ x]\] (.+)', md_text)
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument('--project-root', default='.')
+    p.add_argument('--change-id', required=True)
+    p.add_argument('--json', action='store_true')
+    args = p.parse_args()
+
+    change_dir = os.path.join(args.project_root, 'specs', 'changes', args.change_id)
+    issues = []
+    warnings = []
+
+    # 1. Required files exist
+    for fname in ['proposal.md', 'plan.md', 'tasks.md', 'status.json']:
+        fpath = os.path.join(change_dir, fname)
+        if not os.path.exists(fpath):
+            issues.append(f'Missing required file: {fpath}')
+
+    # 2. status.json fields
+    status = load_json_if_exists(os.path.join(change_dir, 'status.json'))
+    if status:
+        for field in ['change_id', 'title', 'change_type', 'status', 'current_stage']:
+            if not status.get(field):
+                issues.append(f'status.json missing field: {field}')
+        if status.get('change_id') != args.change_id:
+            issues.append(f'status.json change_id mismatch: {status.get("change_id")} != {args.change_id}')
+
+    # 3. proposal.md has minimum structure
+    proposal_text = load_text_if_exists(os.path.join(change_dir, 'proposal.md'))
+    if proposal_text:
+        headings = extract_section_headings(proposal_text)
+        for required_h in ['Problem', 'Scope']:
+            if not any(required_h.lower() in h.lower() for h in headings):
+                warnings.append(f'proposal.md missing expected section: "{required_h}" (found: {headings})')
+    else:
+        issues.append('proposal.md is empty or missing')
+
+    # 4. plan.md may coexist with tasks.md, but plan itself stays reusable
+    plan_text = load_text_if_exists(os.path.join(change_dir, 'plan.md'))
+    tasks_text = load_text_if_exists(os.path.join(change_dir, 'tasks.md'))
+    if plan_text and len(plan_text.strip()) < 100:
+        warnings.append('plan.md seems too short (< 100 chars)')
+    if tasks_text:
+        task_items = extract_task_items(tasks_text)
+        if len(task_items) == 0:
+            warnings.append('tasks.md has no checklist items')
+
+    # 5. AHA.md keyword collision check (if AHA.md exists at root)
+    aha_path = os.path.join(args.project_root, 'AHA.md')
+    aha_text = load_text_if_exists(aha_path)
+    if aha_text and proposal_text:
+        # Simple heuristic: look for any "must not" or "avoid" rules in AHA that match keywords in proposal
+        must_not = re.findall(r'(?:must not|avoid|do not)\s+(.+?)(?:\.|$)', aha_text, re.IGNORECASE)
+        for rule in must_not:
+            rule_lower = rule.lower().strip()
+            if len(rule_lower) > 10 and rule_lower in proposal_text.lower():
+                warnings.append(f'Proposal may conflict with AHA rule: "{rule_lower}"')
+
+    ok = len(issues) == 0
+    result = {
+        'ok': ok,
+        'gate': 'J4a.spec_consistency.structural',
+        'verdict': 'pass' if ok else 'fail',
+        'issues': issues,
+        'warnings': warnings,
+        'change_id': args.change_id,
+    }
+
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if ok else 1)
+
+if __name__ == '__main__':
+    main()

package/xflow/atoms/j4b_spec_delta_review.py

@@ -0,0 +1,316 @@
+#!/usr/bin/env python3
+"""
+J4b.spec_delta.review - Generate a deterministic spec delta review.
+
+This is intentionally not an LLM judge. It creates a reviewer-facing summary of
+proposal, plan, tasks, verification commands, and merge-spec snippets so humans
+and agents can inspect the change at the spec layer before reading code.
+"""
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import tdd_lib
+
+
+ROOT_SPEC_FILES = ["product.md", "architecture.md", "workflow.md", "README.md"]
+MERGE_SPEC_FILES = [
+    "merge-product.md",
+    "merge-architecture.md",
+    "merge-workflow.md",
+    "merge-aha.md",
+]
+
+
+def read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+
+
+def headings(text: str) -> list[str]:
+    return [match.strip() for match in re.findall(r"^#{1,4}\s+(.+)$", text, re.MULTILINE)]
+
+
+def bullets(text: str) -> list[str]:
+    return [match.strip() for match in re.findall(r"^\s*[-*]\s+(.+)$", text, re.MULTILINE)]
+
+
+def requirement_statements(text: str) -> list[dict]:
+    statements = []
+    for line_number, raw in enumerate(text.splitlines(), start=1):
+        line = raw.strip()
+        if not line:
+            continue
+        normalized = re.sub(r"^\s*(?:[-*]|\d+\.)\s+", "", line)
+        normalized = re.sub(r"^\[[ xX]\]\s+", "", normalized).strip()
+        if not normalized:
+            continue
+        marker_match = re.search(
+            r"\b(MUST|SHOULD|REQUIRED|REQUIRES|ACCEPTANCE|VERIFY|VALIDATE|PROOF|GATE)\b",
+            normalized,
+            re.IGNORECASE,
+        )
+        if marker_match:
+            statements.append({
+                "line": line_number,
+                "marker": marker_match.group(1).upper(),
+                "text": normalized,
+            })
+    return statements
+
+
+def tasks(text: str) -> list[dict]:
+    items = []
+    for done, body in re.findall(r"^\s*[-*]\s+\[([ xX])\]\s+(.+)$", text, re.MULTILINE):
+        items.append({"done": done.lower() == "x", "text": body.strip()})
+    return items
+
+
+def verification_commands(text: str) -> list[str]:
+    commands = []
+    for block in re.findall(r"```(?:bash|sh|shell)?\n(.*?)```", text, re.DOTALL):
+        for line in block.splitlines():
+            candidate = line.strip()
+            if candidate and not candidate.startswith("#"):
+                commands.append(candidate)
+    return commands
+
+
+def first_nonempty_lines(text: str, limit: int = 5) -> list[str]:
+    lines = []
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped:
+            lines.append(stripped)
+        if len(lines) >= limit:
+            break
+    return lines
+
+
+def spec_touchpoints(change_dir: Path) -> list[dict]:
+    touchpoints = []
+    for filename in MERGE_SPEC_FILES:
+        path = change_dir / filename
+        if not path.exists():
+            continue
+        text = read_text(path)
+        touchpoints.append({
+            "file": filename,
+            "headings": headings(text),
+            "bullets": bullets(text)[:12],
+            "requirements": requirement_statements(text)[:12],
+            "preview": first_nonempty_lines(text, 4),
+        })
+    return touchpoints
+
+
+def root_spec_presence(project_root: Path) -> list[dict]:
+    specs_dir = project_root / "specs"
+    return [
+        {
+            "file": f"specs/{filename}",
+            "exists": (specs_dir / filename).exists(),
+        }
+        for filename in ROOT_SPEC_FILES
+    ]
+
+
+def requirements_delta(proposal_text: str, plan_text: str, touchpoints: list[dict]) -> dict:
+    proposal_requirements = requirement_statements(proposal_text)
+    plan_requirements = requirement_statements(plan_text)
+    touchpoint_requirements = [
+        {
+            "file": touchpoint["file"],
+            "line": requirement["line"],
+            "marker": requirement["marker"],
+            "text": requirement["text"],
+        }
+        for touchpoint in touchpoints
+        for requirement in touchpoint.get("requirements", [])
+    ]
+    return {
+        "proposal": proposal_requirements[:20],
+        "plan": plan_requirements[:20],
+        "touchpoints": touchpoint_requirements[:20],
+        "counts": {
+            "proposal": len(proposal_requirements),
+            "plan": len(plan_requirements),
+            "touchpoints": len(touchpoint_requirements),
+        },
+    }
+
+
+def render_markdown(review: dict) -> str:
+    lines = [
+        "# Spec Delta Review",
+        "",
+        f"- Change: `{review['change_id']}`",
+        f"- Verdict: `{review['verdict']}`",
+        f"- Recorded: `{review['recorded_at']}`",
+        "",
+        "## Summary",
+        "",
+        f"- Proposal sections: {', '.join(review['proposal']['headings']) or '(none)'}",
+        f"- Plan sections: {', '.join(review['plan']['headings']) or '(none)'}",
+        f"- Task count: {review['tasks']['total']} ({review['tasks']['done']} done)",
+        f"- Verification commands: {len(review['plan']['verification_commands'])}",
+        f"- Merge spec snippets: {len(review['spec_touchpoints'])}",
+        f"- Requirement statements: {review['requirements_delta']['counts']['proposal']} proposal / {review['requirements_delta']['counts']['plan']} plan / {review['requirements_delta']['counts']['touchpoints']} touchpoint",
+        "",
+        "## Issues",
+        "",
+    ]
+    if review["issues"]:
+        lines.extend([f"- {issue}" for issue in review["issues"]])
+    else:
+        lines.append("- None")
+
+    lines.extend(["", "## Warnings", ""])
+    if review["warnings"]:
+        lines.extend([f"- {warning}" for warning in review["warnings"]])
+    else:
+        lines.append("- None")
+
+    lines.extend(["", "## Spec Touchpoints", ""])
+    if review["spec_touchpoints"]:
+        for touchpoint in review["spec_touchpoints"]:
+            lines.append(f"### {touchpoint['file']}")
+            if touchpoint["bullets"]:
+                lines.extend([f"- {bullet}" for bullet in touchpoint["bullets"]])
+            else:
+                lines.append("- No bullet summary found.")
+            lines.append("")
+    else:
+        lines.append("- No merge spec snippets found.")
+
+    lines.extend(["", "## Requirements Delta", ""])
+    for bucket in ["proposal", "plan", "touchpoints"]:
+        lines.append(f"### {bucket.title()}")
+        items = review["requirements_delta"][bucket]
+        if items:
+            for item in items:
+                source = f"{item['file']}:" if "file" in item else ""
+                lines.append(f"- {source}L{item['line']} `{item['marker']}` {item['text']}")
+        else:
+            lines.append("- None")
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--project-root", default=".")
+    parser.add_argument("--change-id", required=True)
+    args = parser.parse_args()
+
+    project_root = Path(args.project_root).resolve()
+    change_dir = project_root / "specs" / "changes" / args.change_id
+    proposal_text = read_text(change_dir / "proposal.md")
+    plan_text = read_text(change_dir / "plan.md")
+    tasks_text = read_text(change_dir / "tasks.md")
+    task_items = tasks(tasks_text)
+
+    issues = []
+    warnings = []
+    if not proposal_text.strip():
+        issues.append("proposal.md is missing or empty")
+    if not plan_text.strip():
+        issues.append("plan.md is missing or empty")
+    if task_items and not any(item["done"] for item in task_items):
+        warnings.append("tasks.md has checklist items, but none are marked done")
+    if not verification_commands(plan_text):
+        warnings.append("plan.md has no fenced verification commands")
+
+    touchpoints = spec_touchpoints(change_dir)
+    req_delta = requirements_delta(proposal_text, plan_text, touchpoints)
+    if not touchpoints:
+        warnings.append("No merge spec snippets found; archive may have no durable spec delta")
+    if req_delta["counts"]["proposal"] and not req_delta["counts"]["plan"]:
+        warnings.append("proposal.md has requirement statements, but plan.md has no requirement-level mapping")
+
+    clause_groups = [
+        ("proposal.md", proposal_text),
+        ("plan.md", plan_text),
+        ("tasks.md", tasks_text),
+    ]
+    for filename in MERGE_SPEC_FILES:
+        clause_groups.append((filename, read_text(change_dir / filename)))
+    diff = subprocess.run(
+        ["git", "diff", "--name-only", "HEAD"],
+        cwd=project_root,
+        text=True,
+        capture_output=True,
+    )
+    untracked = subprocess.run(
+        ["git", "ls-files", "--others", "--exclude-standard"],
+        cwd=project_root,
+        text=True,
+        capture_output=True,
+    )
+    relatives = []
+    if diff.returncode == 0:
+        relatives.extend(line.strip() for line in diff.stdout.splitlines() if line.strip())
+    if untracked.returncode == 0:
+        relatives.extend(line.strip() for line in untracked.stdout.splitlines() if line.strip())
+    for relative in relatives:
+        if tdd_lib.is_test_file(relative):
+            clause_groups.append((relative, read_text(project_root / relative)))
+    issues.extend(tdd_lib.contradictory_requirements(clause_groups))
+
+    review = {
+        "ok": len(issues) == 0,
+        "gate": "J4b.spec_delta.review",
+        "verdict": "pass" if len(issues) == 0 else "fail",
+        "change_id": args.change_id,
+        "proposal": {
+            "exists": bool(proposal_text.strip()),
+            "headings": headings(proposal_text),
+            "bullets": bullets(proposal_text)[:12],
+        },
+        "plan": {
+            "exists": bool(plan_text.strip()),
+            "headings": headings(plan_text),
+            "verification_commands": verification_commands(plan_text),
+        },
+        "tasks": {
+            "exists": bool(tasks_text.strip()),
+            "total": len(task_items),
+            "done": sum(1 for item in task_items if item["done"]),
+            "items": task_items[:20],
+        },
+        "root_specs": root_spec_presence(project_root),
+        "spec_touchpoints": touchpoints,
+        "requirements_delta": req_delta,
+        "issues": issues,
+        "warnings": warnings,
+        "recorded_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+    change_dir.mkdir(parents=True, exist_ok=True)
+    json_path = change_dir / "spec_delta_review.json"
+    md_path = change_dir / "spec_delta_review.md"
+    json_path.write_text(json.dumps(review, indent=2) + "\n", encoding="utf-8")
+    md_path.write_text(render_markdown(review), encoding="utf-8")
+
+    print(json.dumps({
+        "ok": review["ok"],
+        "verdict": review["verdict"],
+        "json_file": str(json_path),
+        "markdown_file": str(md_path),
+        "warnings": len(warnings),
+        "issues": len(issues),
+        "issue_texts": issues,
+    }))
+    sys.exit(0 if review["ok"] else 1)
+
+
+if __name__ == "__main__":
+    main()

package/xflow/atoms/j4c_openspec_migration_map.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""
+J4c.openspec.migration_map - Map an OpenSpec project to evalid surfaces.
+
+This atom is intentionally read-only. It reports how `openspec/specs` and
+`openspec/changes` would map into `specs/` and `specs/changes/` without copying
+or rewriting user files.
+"""
+import argparse
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def slugify(value: str) -> str:
+    value = value.strip().lower()
+    value = re.sub(r"[^a-z0-9]+", "-", value)
+    return re.sub(r"-+", "-", value).strip("-") or "change"
+
+
+def markdown_files(root: Path) -> list[Path]:
+    if not root.exists():
+        return []
+    return sorted(path for path in root.rglob("*.md") if path.is_file())
+
+
+def map_change(change_dir: Path, openspec_root: Path) -> dict:
+    files = {path.name: path for path in markdown_files(change_dir)}
+    change_id = slugify(change_dir.name)
+    proposal = files.get("proposal.md")
+    design = files.get("design.md")
+    tasks = files.get("tasks.md")
+    spec_files = [
+        str(path.relative_to(openspec_root))
+        for path in markdown_files(change_dir)
+        if "spec" in path.name.lower() or "specs" in path.parts
+    ]
+
+    return {
+        "openspec_change": str(change_dir.relative_to(openspec_root)),
+        "xflow_change_id": change_id,
+        "target_dir": f"specs/changes/{change_id}",
+        "proposal": str(proposal.relative_to(openspec_root)) if proposal else None,
+        "design": str(design.relative_to(openspec_root)) if design else None,
+        "tasks": str(tasks.relative_to(openspec_root)) if tasks else None,
+        "spec_files": spec_files,
+        "recommended_xflow_files": {
+            "proposal": f"specs/changes/{change_id}/proposal.md",
+            "plan": f"specs/changes/{change_id}/plan.md",
+            "tasks": f"specs/changes/{change_id}/tasks.md",
+            "spec_delta_review": f"specs/changes/{change_id}/spec_delta_review.json",
+        },
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--project-root", default=".")
+    parser.add_argument("--openspec-root", default="openspec")
+    args = parser.parse_args()
+
+    project_root = Path(args.project_root).resolve()
+    openspec_root = (project_root / args.openspec_root).resolve()
+    specs_root = openspec_root / "specs"
+    changes_root = openspec_root / "changes"
+
+    issues = []
+    if not openspec_root.exists():
+        issues.append(f"OpenSpec root not found: {openspec_root}")
+
+    root_specs = [
+        {
+            "openspec_file": str(path.relative_to(openspec_root)),
+            "recommended_target": f"specs/{path.name}",
+        }
+        for path in markdown_files(specs_root)
+    ]
+
+    changes = [
+        map_change(path, openspec_root)
+        for path in sorted(changes_root.iterdir()) if changes_root.exists() and path.is_dir()
+    ]
+
+    report = {
+        "ok": len(issues) == 0,
+        "gate": "J4c.openspec.migration_map",
+        "project_root": str(project_root),
+        "openspec_root": str(openspec_root),
+        "root_specs": root_specs,
+        "changes": changes,
+        "command_mapping": {
+            "/opsx:new <change>": "xflow init --project-root .; xflow:plan",
+            "/opsx:ff": "xflow:plan creates/refreshes plan.md",
+            "/opsx:apply": "xflow workflow run yolo|corps --project-root .",
+            "/opsx:archive": "xflow archive phase via A5.archive.commit_push_close",
+            "openspec validate": "xflow workflow validate yolo|corps plus J4a/J4b gates",
+        },
+        "issues": issues,
+        "recorded_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+    output_dir = project_root / ".as-xflow"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    output_path = output_dir / "openspec-migration.json"
+    output_path.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+
+    print(json.dumps({
+        "ok": report["ok"],
+        "report_file": str(output_path),
+        "root_specs": len(root_specs),
+        "changes": len(changes),
+        "issues": issues,
+    }))
+    sys.exit(0 if report["ok"] else 1)
+
+
+if __name__ == "__main__":
+    main()