Skip to content

bjwanneng/veriflow-cc / src/claude_skills/vf-rtl

vf-rtl

Verified

FileKindSize
SELF_IMPROVE.mdmarkdown3.8 KB
SKILL.mdskill md11.2 KB
SKILL_INDEX.mdmarkdown5.5 KB
analysis/bug_pattern_match.pyscript26.9 KB
analysis/corner_case_generator.pyscript4.9 KB
analysis/coverage_analyzer.pyscript5.3 KB
analysis/design_graph.pyscript8.9 KB
analysis/expected_trace_gen.pyscript12.5 KB
analysis/timing_contract_checker.pyscript25.4 KB
analysis/timing_diagnostic.pyscript21.1 KB
analysis/vcd2table.pyscript31.3 KB
bug_patterns.mdmarkdown23.2 KB
coding_style.mdmarkdown9.4 KB
core/init.pyscript13.8 KB
core/rtl_utils.pyscript7.5 KB
core/state.pyscript38.9 KB
design_rules.mdmarkdown2.9 KB
error_recovery.mdmarkdown7.0 KB
kb/knowledge_base.pyscript11.7 KB
kb/reference_kb.pyscript5.6 KB
kb/self_improve.pyscript24.4 KB
references/arbiter_round_robin.vother1.4 KB
references/counter.vother545 B
references/fifo.vother1.3 KB
references/fsm_moore.vother847 B
references/handshake_valid_ready.vother1.1 KB
references/pipeline_aligner.vother760 B
runners/benchmark_runner.pyscript23.6 KB
runners/cocotb_runner.pyscript26.3 KB
runners/iverilog_runner.pyscript26.3 KB
runners/yosys_equiv.pyscript14.2 KB
stage1_spec_golden.mdmarkdown6.1 KB
stage2_codegen.mdmarkdown5.9 KB
stage3_verify_fix.mdmarkdown17.0 KB
stage4_lint_synth.mdmarkdown6.3 KB
templates/cocotb_template.pyscript42.4 KB
templates/golden_model_template.pyscript8.7 KB
templates/spec_template.jsonconfig8.5 KB
templates/tb_integration_template.vother12.4 KB
verify/candidate_selector.pyscript7.0 KB
verify/formal_prove.pyscript12.1 KB
verify/synth_score.pyscript4.4 KB

core/state.py

View on GitHub
"""Pipeline state management - zero external dependencies."""

import contextlib
import json
import os
import subprocess
import sys
import time
from pathlib import Path
from dataclasses import dataclass, field, asdict, fields
from typing import Final, Optional


# Strict execution order — no stage may be skipped. Tuple to prevent mutation
# (init.py + tests import this and iterate; nobody should be able to append).
STAGE_ORDER: Final[tuple[str, ...]] = (
    "spec_golden", "codegen", "verify_fix", "lint_synth"
)

# Prerequisite stages that must all complete before a given stage can run
STAGE_PREREQUISITES: Final[dict[str, tuple[str, ...]]] = {
    "spec_golden":  (),                     # no prerequisites
    "codegen":      ("spec_golden",),       # needs spec.json + golden_model.py
    "verify_fix":   ("codegen",),           # needs RTL + testbench
    "lint_synth":   ("verify_fix",),        # needs verified RTL
}


def next_pending_stage(stages_completed: list) -> str | None:
    """Return the first stage not yet completed. Strict STAGE_ORDER, no skipping."""
    for stage in STAGE_ORDER:
        if stage not in stages_completed:
            return stage
    return None  # all complete


def can_execute(stage: str, stages_completed: list) -> tuple[bool, str]:
    """Check whether a stage can execute (all prerequisites met).

    Returns:
        (can_run, reason) — can_run=True means OK to execute
    """
    prereqs = STAGE_PREREQUISITES.get(stage, ())
    missing = [p for p in prereqs if p not in stages_completed]
    if missing:
        return False, f"Prerequisite stages not completed: {missing}"
    return True, ""


@dataclass
class PipelineState:
    """Pipeline state - serializable to JSON, driven by Claude Code main session."""

    project_dir: str

    current_stage: str = ""
    stages_completed: list = field(default_factory=list)
    stages_failed: list = field(default_factory=list)

    # Per-stage output summaries
    spec_golden_output: Optional[dict] = None
    codegen_output: Optional[dict] = None
    verify_fix_output: Optional[dict] = None
    lint_synth_output: Optional[dict] = None

    # Formal verification (populated by yosys_equiv in Stage 4)
    equivalence_check: Optional[dict] = None  # {"equivalent": bool, "unproven": [...], "report": str}

    # Error recovery
    retry_count: dict = field(default_factory=dict)
    error_history: dict = field(default_factory=dict)
    feedback_source: str = ""
    max_retries_per_stage: int = 3

    # Persistent context summary — new sessions read this field to recover state
    stage_summaries: dict = field(default_factory=dict)

    # Per-stage timing
    stage_timings: dict = field(default_factory=dict)  # {"spec_golden": {"start": ts, "end": ts, "duration_s": float}, ...}

    # Metadata
    start_time: float = field(default_factory=time.time)
    last_updated: float = field(default_factory=time.time)

    def __post_init__(self):
        if isinstance(self.project_dir, Path):
            self.project_dir = str(self.project_dir)

    def mark_complete(self, stage: str, result: dict) -> bool:
        """Mark a stage as complete. Returns False if prerequisites not met."""
        if stage not in STAGE_ORDER:
            print(f"[ERROR] Unknown stage '{stage}'. Valid stages: {list(STAGE_ORDER)}", file=sys.stderr)
            return False
        if stage in STAGE_PREREQUISITES:
            ok, reason = can_execute(stage, self.stages_completed)
            if not ok:
                print(f"[ERROR] Stage '{stage}' blocked — {reason}", file=sys.stderr)
                return False
        if stage not in self.stages_completed:
            self.stages_completed.append(stage)
        setattr(self, f"{stage}_output", result)
        self.current_stage = stage
        self.last_updated = time.time()
        # Save summary for context recovery
        summary = result.get("summary", "")
        if summary:
            self.stage_summaries[stage] = summary
        # Record end time
        self._record_end(stage)
        # Persist immediately — mark_started auto-saves; mark_complete must too
        # so a caller that forgets save() can't silently lose the transition.
        self.save()
        return True

    def mark_failed(self, stage: str, result: dict):
        """Mark a stage as failed."""
        if stage not in self.stages_failed:
            self.stages_failed.append(stage)
        if stage not in self.error_history:
            self.error_history[stage] = []
        self.error_history[stage].append({
            "time": time.time(),
            "errors": result.get("errors", []),
        })
        setattr(self, f"{stage}_output", result)
        self.current_stage = stage
        self.feedback_source = stage
        self.last_updated = time.time()
        # Record end time
        self._record_end(stage)
        # Persist immediately (see mark_complete).
        self.save()

    def mark_started(self, stage: str):
        """Record the start time of a stage."""
        now = time.time()
        if stage not in self.stage_timings:
            self.stage_timings[stage] = {}
        self.stage_timings[stage]["start"] = now
        self.current_stage = stage
        self.last_updated = now
        # Auto-fix: if start is an ISO string from older data, overwrite with float
        self.save()

    def _previous_end(self, stage: str) -> Optional[float]:
        """Most recent `end` among stages before `stage` in STAGE_ORDER.

        Used to infer a stage's start when `--start` was omitted.
        """
        try:
            idx = STAGE_ORDER.index(stage)
        except ValueError:
            return None
        for prev in reversed(STAGE_ORDER[:idx]):
            end = self.stage_timings.get(prev, {}).get("end")
            if end and isinstance(end, (int, float)):
                return end
        return None

    def _record_end(self, stage: str):
        """Record the end time and compute duration for a stage.

        If `--start` was omitted (no `start` recorded), fall back to the previous
        stage's end time so a duration is still captured. Such durations carry
        `duration_inferred: true` so consumers (benchmark/report) can tell them
        apart from directly-measured ones.
        """
        now = time.time()
        if stage not in self.stage_timings:
            self.stage_timings[stage] = {}
        self.stage_timings[stage]["end"] = now
        start = self.stage_timings[stage].get("start")
        inferred = False
        if not (start and isinstance(start, (int, float))):
            prev_end = self._previous_end(stage)
            if prev_end:
                start, inferred = prev_end, True
        if start and isinstance(start, (int, float)):
            self.stage_timings[stage]["duration_s"] = round(now - start, 1)
            if inferred:
                self.stage_timings[stage]["duration_inferred"] = True

    def inc_retry(self, stage: str):
        self.retry_count[stage] = self.retry_count.get(stage, 0) + 1
        if self.retry_count[stage] >= self.max_retries_per_stage:
            print(f"[BUDGET] Stage '{stage}' exhausted {self.max_retries_per_stage} retries. Escalating to user.", file=sys.stderr)

    def is_retry_exhausted(self, stage: str) -> bool:
        """Check if the retry budget has been exhausted for a stage."""
        return self.retry_count.get(stage, 0) >= self.max_retries_per_stage

    def get_output(self, stage: str) -> Optional[dict]:
        return getattr(self, f"{stage}_output", None)

    def is_done(self, stage: str) -> bool:
        return stage in self.stages_completed

    def is_pipeline_complete(self) -> bool:
        return "lint_synth" in self.stages_completed

    # -- Persistence ---------------------------------------------------------

    def save(self) -> Path:
        """Save state to .veriflow/pipeline_state.json (atomic: tmp + rename)."""
        d = Path(self.project_dir) / ".veriflow"
        d.mkdir(parents=True, exist_ok=True)
        p = d / "pipeline_state.json"
        tmp = d / "pipeline_state.json.tmp"
        try:
            # Write to a temp file then atomically rename. A crash mid-write
            # leaves the previous good state intact instead of a truncated file
            # that would silently reset the pipeline on the next load().
            tmp.write_text(json.dumps(asdict(self), indent=2, default=str), encoding="utf-8")
            os.replace(tmp, p)
        except OSError as e:
            print(f"[ERROR] Failed to save pipeline state: {e}", file=sys.stderr)
            with contextlib.suppress(OSError):
                if tmp.exists():
                    tmp.unlink()
        return p

    @classmethod
    def load(cls, project_dir: str) -> "PipelineState":
        """Load from file, create new state if file does not exist.

        Tolerant of extra fields in the JSON (e.g. from newer versions):
        unknown keys are silently ignored so that downgrades don't crash.
        """
        p = Path(project_dir) / ".veriflow" / "pipeline_state.json"
        if p.exists():
            try:
                data = json.loads(p.read_text(encoding="utf-8"))
                if not isinstance(data, dict):
                    raise TypeError(f"state file root is {type(data).__name__}, not object")
                # Filter to only known fields to survive schema evolution
                known = {f.name for f in fields(cls)}
                filtered = {k: v for k, v in data.items() if k in known}
                return cls(**filtered)
            except (TypeError, json.JSONDecodeError, OSError) as e:
                print(f"[WARNING] Corrupted pipeline_state.json, starting fresh: {e}", file=sys.stderr)
        return cls(project_dir=project_dir)

    def reset_stage(self, stage: str):
        """Clear a stage and all subsequent completion records, for rollback."""
        if stage not in STAGE_ORDER:
            return
        idx = STAGE_ORDER.index(stage)
        to_remove = STAGE_ORDER[idx:]
        self.stages_completed = [s for s in self.stages_completed if s not in to_remove]
        self.stages_failed = [s for s in self.stages_failed if s not in to_remove]
        for s in to_remove:
            setattr(self, f"{s}_output", None)
            self.stage_summaries.pop(s, None)
            self.stage_timings.pop(s, None)
            # Clear error history + retry budget for rolled-back stages so
            # --check-loop doesn't fire on pre-rollback errors and the KB
            # fix-attempt count resets for a fresh attempt.
            self.error_history.pop(s, None)
            self.retry_count.pop(s, None)
        # equivalence_check belongs to lint_synth; drop it if lint_synth is
        # being redone so a stale netlist result can't leak forward.
        if "lint_synth" in to_remove:
            self.equivalence_check = None
        self.save()

    def next_stage(self) -> str | None:
        """Return the next stage to execute (strict order, no skipping)."""
        return next_pending_stage(self.stages_completed)

    def validate_before_run(self, stage: str) -> tuple[bool, str]:
        """Pre-execution validation. Must be called before every stage execution."""
        # 1. Check strict ordering
        expected = next_pending_stage(self.stages_completed)
        if expected is None:
            return False, "Pipeline already complete — no pending stages."
        if stage != expected:
            return False, f"Order violation: expected '{expected}', but attempted '{stage}'. Stages cannot be skipped."

        # 2. Check prerequisites
        return can_execute(stage, self.stages_completed)

    def validate_spec_completeness(self, project_dir: str) -> tuple[bool, list[str]]:
        """Validate spec.json completeness after Stage 1.

        Returns:
            (is_complete, missing_items) — is_complete=True means ready to proceed
        """
        missing = []
        spec_path = Path(project_dir) / "workspace/docs/spec.json"

        # Check spec.json
        if not spec_path.exists():
            missing.append("spec.json file missing")
        else:
            try:
                spec = json.loads(spec_path.read_text(encoding="utf-8"))
                if not spec.get("project") and not spec.get("design_name"):
                    missing.append("spec.json: project/design_name missing")
                if not spec.get("modules"):
                    missing.append("spec.json: modules missing")
                else:
                    has_top = False
                    # Support both list format [{"module_name": ..., ...}] and
                    # dict format {"module_name": {"module_type": ..., ...}}
                    modules = spec["modules"]
                    if isinstance(modules, dict):
                        for name, m in modules.items():
                            if not isinstance(m, dict):
                                missing.append(f"spec.json: module {name} is malformed (not an object)")
                                continue
                            if not m.get("ports"):
                                missing.append(f"spec.json: module {name} missing ports")
                            if m.get("module_type") == "top":
                                has_top = True
                    elif isinstance(modules, list):
                        for m in modules:
                            if not isinstance(m, dict):
                                continue
                            mod_name = m.get("module_name", "?")
                            if not m.get("module_name"):
                                missing.append("spec.json: module missing module_name")
                            if not m.get("ports"):
                                missing.append(f"spec.json: module {mod_name} missing ports")
                            if m.get("module_type") == "top":
                                has_top = True
                    if not has_top:
                        missing.append("spec.json: no module with module_type 'top'")
                # Check constraints — support both nested and flat formats
                constraints = spec.get("constraints", {})
                has_freq = False
                if constraints.get("timing", {}).get("target_frequency_mhz") or spec.get("target_frequency_mhz"):
                    has_freq = True
                if not has_freq:
                    missing.append("spec.json: target_frequency_mhz missing")
                num_modules = len(spec.get("modules", {})) if isinstance(spec.get("modules"), dict) else len(spec.get("modules", []))
                if num_modules > 1 and not spec.get("module_connectivity"):
                    missing.append("spec.json: module_connectivity missing for multi-module design")
                # Check timing_convention
                if not spec.get("timing_convention"):
                    missing.append("spec.json: timing_convention missing")
                # Check timing_contract in connectivity entries
                if spec.get("module_connectivity"):
                    conn_iter = spec["module_connectivity"]
                    # Tolerate a dict (legacy/malformed) instead of the expected list.
                    if isinstance(conn_iter, dict):
                        conn_iter = list(conn_iter.values())
                    for i, conn in enumerate(conn_iter):
                        if not isinstance(conn, dict):
                            continue
                        if not conn.get("timing_contract"):
                            missing.append(f"spec.json: module_connectivity[{i}] missing timing_contract")
                # fanout_groups is optional but if present must have valid structure
                if spec.get("fanout_groups"):
                    for i, fg in enumerate(spec["fanout_groups"]):
                        if not fg.get("name") or not fg.get("signals"):
                            missing.append(f"spec.json: fanout_groups[{i}] missing name or signals")
                # Design graph validation — cycle detection and unreachable modules
                try:
                    import importlib.util
                    _skill_root = Path(__file__).resolve().parent
                    while not (_skill_root / "SKILL.md").exists() and _skill_root.parent != _skill_root:
                        _skill_root = _skill_root.parent
                    graph_path = _skill_root / "analysis" / "design_graph.py"
                    if graph_path.exists():
                        spec_mod = importlib.util.spec_from_file_location("design_graph", str(graph_path))
                        dg_mod = importlib.util.module_from_spec(spec_mod)
                        spec_mod.loader.exec_module(dg_mod)
                        graph = dg_mod.DesignGraph(spec)
                        cycles = graph.detect_cycles()
                        if cycles:
                            for c in cycles:
                                missing.append(
                                    f"spec.json: combinational cycle detected: "
                                    f"{' -> '.join(c)}"
                                )
                        unreachable = graph.find_unreachable_modules()
                        if unreachable:
                            missing.append(
                                f"spec.json: unreachable modules: {', '.join(unreachable)}"
                            )
                except Exception:
                    pass  # design_graph check is best-effort
            except (json.JSONDecodeError, KeyError) as e:
                missing.append(f"spec.json: parse error - {e}")

        return (len(missing) == 0, missing)

    def detect_fix_loop(self, stage: str, error_signature: str | tuple) -> bool:
        """Detect if error recovery is cycling on the same error.

        Args:
            stage: Current stage name
            error_signature: Either a legacy string (backwards compatible) or
                a structured tuple (classification, signal_root, cycle_offset).
                Structured signatures ignore line numbers — the same bug class
                on the same signal with the same timing offset is detected even
                if the RTL line numbers shifted after a fix attempt.
                Examples:
                  - "lint:line42:syntax"  (legacy string)
                  - ("B_late", "w_reg", -1)  (structured)

        Returns:
            True if this error has been seen 2+ times in recent history
        """
        if stage not in self.error_history:
            return False

        recent_errors = self.error_history[stage][-3:]  # Last 3 attempts

        if isinstance(error_signature, (tuple, list)):
            # Structured matching: compare (classification, signal_root, cycle_offset)
            # This is robust to code changes that shift line numbers.
            sig_class, sig_signal, sig_offset = error_signature
            signature_count = 0
            for e in recent_errors:
                for err in e.get("errors", []):
                    # Accept tuple OR list: JSON persistence round-trips tuples
                    # to lists, so a signature stored last session reloads as a
                    # list. Without this, structured loop detection is dead for
                    # every cross-process CLI call.
                    if isinstance(err, (tuple, list)) and len(err) == 3:
                        err_class, err_signal, err_offset = err
                        if (sig_class == err_class and
                                sig_signal == err_signal and
                                sig_offset == err_offset):
                            signature_count += 1
                            break
            return signature_count >= 2
        # Legacy exact string match (for non-Stage-3 errors like lint)
        signature_count = sum(
            1 for e in recent_errors
            if any(error_signature == err for err in e.get("errors", []))
        )
        return signature_count >= 2

    def validate_golden_model(self, project_dir: str) -> tuple[bool, list[str]]:
        """Validate golden_model.py after Stage 1 generation.

        Checks syntax, required function, AND runs the golden model self-test
        to verify test vectors pass. If the golden model itself has bugs, any
        RTL comparison is meaningless.

        Returns:
            (is_valid, issues) — is_valid=True means golden model is usable.
            Returns (True, []) if golden_model.py does not exist (it is optional).
        """
        import py_compile

        issues = []
        gm_path = Path(project_dir) / "workspace" / "docs" / "golden_model.py"

        if not gm_path.exists():
            return (True, [])  # golden model is optional

        # Check syntax
        try:
            py_compile.compile(str(gm_path), doraise=True)
        except py_compile.PyCompileError as e:
            issues.append(f"golden_model.py syntax error: {e}")
            return (False, issues)

        # Check it defines run()
        content = gm_path.read_text(encoding="utf-8")
        if "def run(" not in content:
            issues.append("golden_model.py missing run() function")
            return (False, issues)

        # Run the golden model self-test
        try:
            result = subprocess.run(
                [sys.executable, str(gm_path)],
                capture_output=True, text=True, timeout=30,
                cwd=str(gm_path.parent),
            )
            output = result.stdout + result.stderr

            # Check for [FAIL] markers
            fail_lines = [line for line in output.splitlines() if "[FAIL]" in line]
            if fail_lines:
                for fl in fail_lines[:5]:
                    issues.append(f"golden_model.py self-test failed: {fl.strip()}")
                return (False, issues)

            # If no PASS markers and non-zero exit, something is wrong
            pass_lines = [line for line in output.splitlines() if "[PASS]" in line]
            if not pass_lines and result.returncode != 0:
                issues.append(
                    f"golden_model.py exited with code {result.returncode} "
                    f"and produced no [PASS] output"
                )
                return (False, issues)

        except subprocess.TimeoutExpired:
            issues.append("golden_model.py self-test timed out (30s limit)")
            return (False, issues)
        except Exception as e:
            issues.append(f"golden_model.py execution error: {e}")
            return (False, issues)

        # ------------------------------------------------------------------
        # Consistency check: trace mode vs non-trace mode must agree
        # SM3 bug: compute(trace=True) produced wrong per-cycle trace,
        # misleading Stage 3 debug for hours.
        # ------------------------------------------------------------------
        try:
            import importlib.util
            gm_spec = importlib.util.spec_from_file_location("golden_model", str(gm_path))
            gm_module = importlib.util.module_from_spec(gm_spec)
            gm_spec.loader.exec_module(gm_module)

            if hasattr(gm_module, "compute"):
                compute = gm_module.compute
                # Try to call both modes
                try:
                    non_trace = compute(trace=False)
                except TypeError:
                    non_trace = compute()
                trace_result = compute(trace=True)

                if isinstance(trace_result, list) and trace_result:
                    trace_last = trace_result[-1]
                elif isinstance(trace_result, dict):
                    trace_last = trace_result
                else:
                    trace_last = None

                if (
                    isinstance(non_trace, dict)
                    and isinstance(trace_last, dict)
                ):
                    # Compare only common keys — trace mode may include extra
                    # internal signals that non-trace mode omits.
                    common_keys = set(non_trace.keys()) & set(trace_last.keys())
                    mismatches = []
                    for k in sorted(common_keys):
                        v1 = non_trace[k]
                        v2 = trace_last[k]
                        if v1 != v2:
                            mismatches.append(f"{k}: non-trace={v1} trace={v2}")
                    if mismatches:
                        issues.append(
                            "golden_model.py trace mode and non-trace mode produce different "
                            "final results for common keys. This means the per-cycle trace "
                            "is not derived from the same algorithm path as the final output. "
                            "Mismatched keys: "
                            + ", ".join(mismatches[:5])
                        )
                        return (False, issues)
        except Exception:
            # Consistency check is best-effort; if import fails, don't block
            pass

        return (True, [])


# -- CLI entry point (called by SKILL.md state update command) -----------------

def _get_arg(argv: list, flag: str) -> str | None:
    """Extract value for --flag=value or --flag value from argv."""
    for a in argv:
        if a.startswith(f"--{flag}="):
            return a.split("=", 1)[1]
    idx = None
    for i, a in enumerate(argv):
        if a == f"--{flag}":
            idx = i
            break
    if idx is not None and idx + 1 < len(argv):
        val = argv[idx + 1]
        # If the next token looks like another flag, don't consume it —
        # the user should use --flag=value to pass dash-prefixed values.
        if val.startswith("--"):
            return None
        return val
    return None


def evaluate_hook(spec, project_dir: str) -> tuple[bool, str]:
    """Evaluate a structured hook predicate. Pure — no subprocess.

    Cross-platform replacement for shell-based hooks (test/ls/grep). `spec`
    is a JSON string (starts with '{') or a parsed dict. Relative paths are
    resolved against `project_dir` and MUST stay inside it — absolute paths
    and ``..`` traversal are rejected so an LLM-authored hook can't read
    outside the project.

    Predicates:
      {"exists": "relpath"}                          file/dir exists
      {"glob": "pattern", "min": N}                  N glob matches (min default 1)
      {"contains": "relpath", "text": str, "case": bool}
                                                     file contains text (case default True)
    Combinators (short-circuit):
      {"all": [...]}                                 every child passes
      {"any": [...]}                                 at least one child passes

    Returns (passed, detail) where detail is a human string for the journal /
    [HOOK] diagnostics. Never raises on bad input — returns (False, reason).
    """
    import glob as _glob

    def _safe_join(base: Path, rel) -> Path | None:
        """Join base + rel, rejecting non-strings and paths that escape base."""
        if not isinstance(rel, str) or not rel:
            return None
        candidate = (base / rel).resolve()
        try:
            base_resolved = base.resolve()
        except OSError:
            return None
        # Path.is_relative_to is 3.9+; use a prefix check for portability.
        if str(candidate) != str(base_resolved) and not str(candidate).startswith(
            str(base_resolved) + os.sep
        ):
            return None
        return candidate

    if isinstance(spec, str):
        try:
            parsed = json.loads(spec)
        except json.JSONDecodeError as e:
            return (False, f"invalid JSON hook: {e.msg}")
    else:
        parsed = spec

    if not isinstance(parsed, dict):
        return (False, f"hook must be a JSON object, got {type(parsed).__name__}")

    base = Path(project_dir)

    def one(node):
        if not isinstance(node, dict):
            return (False, f"predicate must be object, got {type(node).__name__}")

        if "all" in node:
            seq = node["all"]
            if not isinstance(seq, list) or not seq:
                return (False, "'all' needs a non-empty list")
            for child in seq:
                ok, detail = one(child)
                if not ok:
                    return (False, detail)      # short-circuit
            return (True, "all passed")

        if "any" in node:
            seq = node["any"]
            if not isinstance(seq, list) or not seq:
                return (False, "'any' needs a non-empty list")
            for child in seq:
                ok, detail = one(child)
                if ok:
                    return (True, detail)       # short-circuit
            return (False, "no predicate in 'any' passed")

        if "exists" in node:
            rel = node["exists"]
            p = _safe_join(base, rel)
            if p is None:
                return (False, f"exists: invalid or escaping path {rel!r}")
            return (p.exists(), f"exists: {rel}" if p.exists() else f"missing: {rel}")

        if "glob" in node:
            pattern = node["glob"]
            if not isinstance(pattern, str) or not pattern:
                return (False, f"glob: pattern must be a non-empty string, got {pattern!r}")
            # Same escape guard as exists/contains: reject absolute patterns
            # and `..` components so an LLM-authored hook can't glob outside
            # the project dir (e.g. {"glob": "../../**"}).
            if os.path.isabs(pattern) or ".." in pattern.replace("\\", "/").split("/"):
                return (False, f"glob: absolute or escaping pattern {pattern!r}")
            minimum = node.get("min", 1)
            try:
                minimum = int(minimum)
            except (TypeError, ValueError):
                return (False, f"glob {pattern}: 'min' must be an integer, got {minimum!r}")
            matches = _glob.glob(str(base / pattern))
            ok = len(matches) >= minimum
            return (ok, f"glob {pattern}: {len(matches)} match(es), need {minimum}")

        if "contains" in node:
            rel = node["contains"]
            text = node.get("text", "")
            case = node.get("case", True)
            p = _safe_join(base, rel)
            if p is None:
                return (False, f"contains: invalid or escaping path {rel!r}")
            if not p.exists():
                return (False, f"missing file: {rel}")
            content = p.read_text(errors="ignore")
            hay = content if case else content.lower()
            needle = text if case else text.lower()
            ok = needle in hay
            return (ok, f"contains '{text}' in {rel}" if ok else f"text not found in {rel}")

        return (False, f"unknown predicate: {', '.join(node.keys())}")

    return one(parsed)


def _append_journal(project_dir: str, stage: str, outputs: str = "", notes: str = "",
                    status: str = "completed"):
    """Append a stage journal entry to logs/stage_journal.md."""
    journal_path = Path(project_dir) / "logs" / "stage_journal.md"
    from datetime import datetime
    ts = datetime.now().isoformat()
    entry = f"\n## Stage: {stage}\n**Status**: {status}\n**Timestamp**: {ts}\n"
    if outputs:
        entry += f"**Outputs**: {outputs}\n"
    if notes:
        entry += f"**Notes**: {notes}\n"
    journal_path.parent.mkdir(parents=True, exist_ok=True)
    with open(journal_path, "a", encoding="utf-8") as f:
        f.write(entry)


def _print_usage():
    print("Usage:")
    print("  python state.py <project_dir> <stage_name>            Mark stage complete")
    print("  python state.py <project_dir> <stage_name> --start    Record stage start time")
    print("  python state.py <project_dir> <stage_name> --fail     Mark stage failed")
    print("  python state.py <project_dir> --reset <stage_name>    Rollback from stage onward")
    print("  python state.py <project_dir> <stage_name> --check-loop=<signature>")
    print("                                                       Detect repeated error signature")
    print("                                                       Exits 0 if NOT looping, 2 if looping")
    print("")
    print("  Combined (hook + state + journal in one call):")
    print("  python state.py <project_dir> <stage_name> \\")
    print('    --hook="test -f workspace/docs/spec.json" \\')
    print('    --journal-outputs="spec.json, golden_model.py" \\')
    print('    --journal-notes="Specification generated"')
    sys.exit(1)


def _coerce_sig(raw: str | None):
    """Coerce a CLI error-signature string into a structured list when possible.

    Stage 3 records signatures as Python-repr/JSON sequences, e.g.
    ('B_late', 'data_out', 2). detect_fix_loop's structured matching only
    fires on tuple/list signatures; leaving these as raw strings silently
    degraded loop detection to exact-string matching (dead for structured
    signatures arriving via the command line).
    """
    if not raw:
        return raw
    s = raw.strip()
    is_seq = (s.startswith("[") and s.endswith("]")) or \
             (s.startswith("(") and s.endswith(")"))
    if not is_seq:
        return raw
    try:
        v = json.loads(s)
        if isinstance(v, list):
            return v
    except (json.JSONDecodeError, ValueError):
        pass
    try:
        import ast
        v = ast.literal_eval(s)
        if isinstance(v, (tuple, list)):
            return list(v)
    except (ValueError, SyntaxError):
        pass
    return raw


if __name__ == "__main__":
    if len(sys.argv) < 3:
        _print_usage()

    _project_dir = sys.argv[1]

    # --reset mode: rollback from target stage
    if "--reset" in sys.argv:
        idx = sys.argv.index("--reset")
        if idx + 1 >= len(sys.argv):
            print("ERROR: --reset requires a stage name", file=sys.stderr)
            _print_usage()
        _target = sys.argv[idx + 1]
        if _target not in STAGE_ORDER:
            print(f"ERROR: Unknown stage '{_target}'. Valid stages: {STAGE_ORDER}", file=sys.stderr)
            sys.exit(1)
        _state = PipelineState.load(_project_dir)
        _state.reset_stage(_target)
        print(f"[STATE] Rolled back to '{_target}' — cleared it and all subsequent stages")
        print(f"[STATE] stages_completed: {_state.stages_completed}")
        _next = _state.next_stage()
        print(f"[STATE] Next: {_next}" if _next else "[STATE] Pipeline complete")
        sys.exit(0)

    _stage = sys.argv[2]

    if _stage not in STAGE_ORDER:
        print(f"ERROR: Unknown stage '{_stage}'. Valid stages: {STAGE_ORDER}", file=sys.stderr)
        sys.exit(1)

    # --check-loop: detect repeated error signatures without modifying state
    _check_loop_sig = _coerce_sig(_get_arg(sys.argv, "check-loop"))
    if _check_loop_sig:
        _state = PipelineState.load(_project_dir)
        looping = _state.detect_fix_loop(_stage, _check_loop_sig)
        if looping:
            print(
                f"[LOOP] Stage '{_stage}' is cycling on the same error: "
                f"{_check_loop_sig}"
            )
            print(f"[LOOP] Recommended: state.py {_project_dir} --reset codegen")
            sys.exit(2)
        print(f"[LOOP] OK — '{_check_loop_sig}' not yet a repeat pattern")
        sys.exit(0)

    _is_start = "--start" in sys.argv
    _is_fail = "--fail" in sys.argv
    _is_inc_retry = "--inc-retry" in sys.argv
    _hook_cmd = _get_arg(sys.argv, "hook")
    _journal_outputs = _get_arg(sys.argv, "journal-outputs")
    _journal_notes = _get_arg(sys.argv, "journal-notes")
    _error_sig = _coerce_sig(_get_arg(sys.argv, "error-sig"))

    _state = PipelineState.load(_project_dir)

    if _is_start:
        _state.mark_started(_stage)
        _append_journal(_project_dir, _stage, status="started")
        print(f"[STATE] {_stage} → STARTED")
    elif _is_fail:
        _fail_result = {"success": False, "errors": ["Hook failed"]}
        if _error_sig:
            _fail_result["errors"] = [_error_sig]
        _state.mark_failed(_stage, _fail_result)
        _state.save()
        _append_journal(_project_dir, _stage, status="failed")
        print(f"[STATE] {_stage} → FAILED")
        if _error_sig:
            print(f"[STATE] Error signature recorded: {_error_sig}")
    elif _is_inc_retry:
        # Record a retry attempt for this stage. Used by the Stage 3 fix loop
        # so the retry budget (and Stage 4's --fix-attempts KB count) is
        # accurate; without it, retry_count stays 0 for every project.
        _state.inc_retry(_stage)
        _state.save()
        _count = _state.retry_count.get(_stage, 0)
        print(f"[STATE] {_stage} → RETRY++ (now {_count}/{_state.max_retries_per_stage})")
        if _state.is_retry_exhausted(_stage):
            print(f"[BUDGET] Stage '{_stage}' exhausted {_state.max_retries_per_stage} retries. Escalating to user.",
                  file=sys.stderr)
    else:
        # Run hook if provided
        _hook_passed = True
        if _hook_cmd:
            if _hook_cmd.lstrip().startswith("{"):
                # Structured cross-platform predicate — no shell, no test/ls/grep.
                _hook_passed, _hook_detail = evaluate_hook(_hook_cmd, _project_dir)
                if not _hook_passed:
                    print(f"[HOOK] FAIL — {_hook_detail}", file=sys.stderr)
            else:
                # Back-compat: run as a shell command (legacy `test`/`grep` hooks).
                _hook_cmd_resolved = _hook_cmd.replace("$PROJECT_DIR", _project_dir)
                try:
                    result = subprocess.run(
                        _hook_cmd_resolved,
                        shell=True,
                        capture_output=True, text=True, cwd=_project_dir,
                        env={**os.environ, "PROJECT_DIR": _project_dir},
                    )
                    if result.stdout.strip():
                        print(result.stdout.strip())
                    if result.returncode != 0:
                        _hook_passed = False
                        print(f"[HOOK] FAIL (exit code {result.returncode})")
                        if result.stderr.strip():
                            print(result.stderr.strip(), file=sys.stderr)
                except Exception as e:
                    _hook_passed = False
                    print(f"[HOOK] FAIL (exception: {e})", file=sys.stderr)

        if _hook_passed:
            if _state.mark_complete(_stage, {"success": True, "summary": "Hook passed"}):
                _state.save()
                print(f"[STATE] {_stage} → COMPLETE")
                # Print timing summary
                if _stage in _state.stage_timings:
                    t = _state.stage_timings[_stage]
                    dur = t.get("duration_s", "?")
                    print(f"[STATE] {_stage} duration: {dur}s")
                # Append journal entry if requested
                if _journal_outputs or _journal_notes:
                    _append_journal(_project_dir, _stage, _journal_outputs or "", _journal_notes or "")
                    print(f"[JOURNAL] {_stage} entry appended")
            else:
                print(f"[STATE] {_stage} → BLOCKED (prerequisites not met)", file=sys.stderr)
                sys.exit(1)
        else:
            _state.mark_failed(_stage, {"success": False, "errors": ["Hook failed"]})
            _state.save()
            print(f"[STATE] {_stage} → FAILED (hook)")

    _next = _state.next_stage()
    print(f"[STATE] Next: {_next}" if _next else "[STATE] Pipeline complete")
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall