bjwanneng/veriflow-cc / src/claude_skills/vf-rtl
vf-rtl
Verifiedcore/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")
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |