@litfamily/litopencode 1.0.0

package/skills/autoresearch/scripts/init_research.py

@@ -0,0 +1,330 @@
+"""
+init_research.py — Scaffold a new autoresearch-skill project directory.
+
+Usage:
+    python init_research.py --goal "..." --metric "..." --direction {maximize|minimize} \
+        [--target "..."] [--max-iterations 10] [--output ./my-research/]
+"""
+
+import argparse
+import os
+import shutil
+import stat
+import tempfile
+import textwrap
+from datetime import datetime
+from pathlib import Path
+from typing import Callable, Optional
+
+RESEARCH_TEMPLATE = """\
+# Research: {title}
+
+> **Scaffold status: INCOMPLETE.** This file contains labeled placeholders. It is not an approved
+> experiment plan. Complete and validate every placeholder through explicit /start-work before any
+> mutation or evaluator execution.
+
+## Goal
+{goal}
+
+## Success Metric
+- **Metric:** {metric}
+- **Target:** {target}
+- **Direction:** {direction}
+
+## Constraints
+- **Max iterations:** {max_iterations}
+- **Time budget per experiment:** 5 minutes
+- **Pause for review every:** never
+- **Evaluator:** {evaluator}
+- **Keep policy:** {keep_policy}
+- **Guard:** {guard}
+- **Noise runs:** {noise_runs}
+- **Min delta:** {min_delta}
+
+## Current Approach
+_Describe your current baseline here._
+
+## Search Space
+- **Allowed changes:** _Define what the agent can modify._
+- **Forbidden changes:** _Define what must NOT change._
+
+## Context & References
+_Add relevant papers, docs, or URLs here._
+
+---
+
+## History
+| # | Change | Metric | Result | Timestamp |
+|---|--------|--------|--------|-----------|
+| 0 | Baseline | TBD | -- | {date} |
+"""
+
+LOG_TEMPLATE = """\
+# Research Log
+
+> Auto-generated by init_research.py on {date}
+> Goal: {goal}
+
+---
+
+"""
+
+TSV_HEADER = "iteration\tmetric_value\tdelta\tdelta_pct\tstatus\tdescription\tevaluator_source\ttimestamp\n"
+TSV_BASELINE = "0\tTBD\t-\t-\tbaseline\tInitial state\tagent\t{date}\n"
+SYSTEM_PATH_ALIASES = {
+    "/etc": "/private/etc",
+    "/tmp": "/private/tmp",
+    "/var": "/private/var",
+}
+
+
+def _identity(path: Path):
+    try:
+        value = path.lstat()
+    except FileNotFoundError:
+        return None
+    return (
+        value.st_dev,
+        value.st_ino,
+        stat.S_IFMT(value.st_mode),
+        value.st_ctime_ns,
+        getattr(value, "st_birthtime_ns", 0),
+    )
+
+
+def _allowed_system_alias(path: Path) -> bool:
+    expected = SYSTEM_PATH_ALIASES.get(str(path))
+    return expected is not None and os.path.realpath(str(path)) == expected
+
+
+def validate_output_tree(output: Path) -> Path:
+    """Reject symlink ancestors, symlink roots, and non-regular tree entries."""
+    absolute = Path(os.path.abspath(str(output)))
+    for ancestor in reversed(absolute.parents):
+        try:
+            mode = ancestor.lstat().st_mode
+        except FileNotFoundError:
+            continue
+        if stat.S_ISLNK(mode) and not _allowed_system_alias(ancestor):
+            raise RuntimeError(f"refusing symlink output ancestor: {ancestor}")
+        if not stat.S_ISLNK(mode) and not stat.S_ISDIR(mode):
+            raise RuntimeError(f"refusing non-directory output ancestor: {ancestor}")
+
+    root_identity = _identity(absolute)
+    if root_identity is None:
+        return absolute
+    root_mode = absolute.lstat().st_mode
+    if stat.S_ISLNK(root_mode):
+        raise RuntimeError(f"refusing symlink output root: {absolute}")
+    if not stat.S_ISDIR(root_mode):
+        raise RuntimeError(f"refusing non-directory output root: {absolute}")
+
+    for current, directories, files in os.walk(str(absolute), followlinks=False):
+        for name in directories + files:
+            candidate = Path(current) / name
+            mode = candidate.lstat().st_mode
+            if stat.S_ISLNK(mode):
+                raise RuntimeError(f"refusing symlink output entry: {candidate}")
+            if not (stat.S_ISDIR(mode) or stat.S_ISREG(mode)):
+                raise RuntimeError(f"refusing special output entry: {candidate}")
+    return absolute
+
+
+def atomic_publish(output: Path, populate: Callable[[Path], None]) -> None:
+    """Populate a sibling staging tree and publish it with rollback."""
+    output = validate_output_tree(output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output = validate_output_tree(output)
+    stage = Path(tempfile.mkdtemp(prefix=f".{output.name}.stage-", dir=str(output.parent)))
+    parent_identity = _identity(output.parent)
+    output_identity = _identity(output)
+    backup = None
+    published = False
+    try:
+        if output_identity is not None:
+            shutil.copytree(str(output), str(stage), dirs_exist_ok=True, symlinks=True)
+            validate_output_tree(stage)
+        populate(stage)
+        validate_output_tree(stage)
+        if _identity(output.parent) != parent_identity or _identity(output) != output_identity:
+            raise RuntimeError("output identity changed before publication")
+
+        if output_identity is not None:
+            backup = Path(tempfile.mkdtemp(prefix=f".{output.name}.backup-", dir=str(output.parent)))
+            backup.rmdir()
+            os.replace(str(output), str(backup))
+            try:
+                os.replace(str(stage), str(output))
+            except BaseException:
+                os.replace(str(backup), str(output))
+                backup = None
+                raise
+            shutil.rmtree(str(backup))
+            backup = None
+        else:
+            os.replace(str(stage), str(output))
+        published = True
+    finally:
+        if not published and stage.exists():
+            shutil.rmtree(str(stage))
+
+
+def goal_to_title(goal: str) -> str:
+    """Convert a goal string to a short title (first 8 words, title-cased)."""
+    words = goal.split()
+    short = " ".join(words[:8])
+    if len(words) > 8:
+        short += "..."
+    return short.title()
+
+
+def remove_known_run_artifacts(output: Path) -> list:
+    """Remove only prior-run files owned by this workflow."""
+    candidates = [output / name for name in ["final_report.md", "results.png", ".autoresearch-loop.pid"]]
+    for artifact in candidates:
+        if artifact.is_symlink():
+            raise RuntimeError(f"refusing to remove symlink run artifact: {artifact}")
+        if artifact.exists() and not artifact.is_file():
+            raise RuntimeError(f"refusing to remove non-file run artifact: {artifact}")
+
+    removed = []
+    for artifact in candidates:
+        if artifact.is_file():
+            artifact.unlink()
+            removed.append(artifact.name)
+    return removed
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Scaffold a new autoresearch-skill project.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=textwrap.dedent("""\
+            Example:
+              python init_research.py \\
+                --goal "Optimize sorting algorithm performance" \\
+                --metric "execution_time_seconds" \\
+                --direction minimize \\
+                --target "< 0.5" \\
+                --max-iterations 20 \\
+                --output ./sort-research/
+        """),
+    )
+    parser.add_argument("--goal", required=True, help="Research goal description.")
+    parser.add_argument("--metric", required=True, help="Metric name to track (e.g. accuracy, execution_time_seconds).")
+    parser.add_argument(
+        "--direction",
+        required=True,
+        choices=["maximize", "minimize"],
+        help="Whether to maximize or minimize the metric.",
+    )
+    parser.add_argument("--target", default="TBD", help="Target value or expression (e.g. '> 0.9', '< 0.5'). Default: TBD")
+    parser.add_argument("--max-iterations", type=int, default=20, metavar="N", help="Maximum number of iterations. Default: 20")
+    parser.add_argument("--output", default="./research/", metavar="PATH", help="Output directory. Default: ./research/")
+    parser.add_argument("--evaluator", default=None, metavar="CMD",
+        help="Evaluator command (e.g. 'python evaluate.py'). Must output JSON {pass:bool, score?:number}.")
+    parser.add_argument("--keep-policy", default="score_improvement",
+        choices=["score_improvement", "pass_only"],
+        help="Keep policy: score_improvement (default) or pass_only.")
+    parser.add_argument("--guard", default=None, metavar="CONDITION",
+        help="Guard condition that must remain true (e.g. 'all unit tests pass'). Hard stop if violated.")
+    parser.add_argument("--noise-runs", type=int, default=1, metavar="N",
+        help="Number of runs to median over for noisy metrics. Default: 1")
+    parser.add_argument("--min-delta", type=float, default=0.0, metavar="DELTA",
+        help="Minimum improvement required to keep a change. Default: 0 (any improvement counts).")
+    return parser.parse_args()
+
+
+def scaffold(goal: str, metric: str, direction: str, target: str, max_iterations: int, output: Path,
+             evaluator: Optional[str] = None, keep_policy: str = "score_improvement",
+             guard: Optional[str] = None, noise_runs: int = 1, min_delta: float = 0.0) -> None:
+    date = datetime.now().strftime("%Y-%m-%d")
+    title = goal_to_title(goal)
+    evaluator_str = f"`{evaluator}`" if evaluator else "_(none — agent judges manually)_"
+    guard_str = guard if guard else "_(none)_"
+
+    # Create workspace subdirectory
+    workspace = output / "workspace"
+    workspace.mkdir(exist_ok=True)
+
+    # Write research.md
+    research_md = output / "research.md"
+    research_md.write_text(
+        RESEARCH_TEMPLATE.format(
+            title=title,
+            goal=goal,
+            metric=metric,
+            target=target,
+            direction=direction,
+            max_iterations=max_iterations,
+            evaluator=evaluator_str,
+            keep_policy=keep_policy,
+            guard=guard_str,
+            noise_runs=noise_runs,
+            min_delta=min_delta,
+            date=date,
+        )
+    )
+
+    # Write research_log.md
+    log_md = output / "research_log.md"
+    log_md.write_text(LOG_TEMPLATE.format(date=date, goal=goal))
+
+    # Write autoresearch-results.tsv
+    tsv_file = output / "autoresearch-results.tsv"
+    tsv_file.write_text(TSV_HEADER + TSV_BASELINE.format(date=date))
+    (output / "autoresearch_events.jsonl").write_text("")
+
+
+def print_success(output: Path) -> None:
+    print(f"\nINCOMPLETE scaffold created at: {output.resolve()}")
+    print("\nFiles created:")
+    for name in ["research.md", "research_log.md", "autoresearch-results.tsv", "autoresearch_events.jsonl"]:
+        print(f"  {(output / name).resolve()}")
+    print(f"  {(output / 'workspace').resolve()}/")
+    print("\nNext steps — this is an incomplete scaffold with placeholders:")
+    print("  1. Through explicit /start-work, fill in 'Current Approach' and 'Search Space'.")
+    print("  2. Add context (papers, docs, code) under 'Context & References'.")
+    print("  3. Run your baseline experiment and record it in the History table.")
+    print("  4. Validate that every placeholder is resolved and record the baseline receipt.")
+    print("  5. Only then may the approved finite loop continue through explicit /start-work.")
+
+
+def main() -> None:
+    args = parse_args()
+    output = validate_output_tree(Path(args.output))
+
+    if output.exists() and any(output.iterdir()):
+        print(f"Warning: output directory '{output}' already exists and is not empty.")
+        answer = input(
+            "Reinitialize managed scaffold files while preserving regular user files? [y/N] "
+        ).strip().lower()
+        if answer != "y":
+            print("Aborted.")
+            return
+
+    removed = []
+    def populate(stage: Path) -> None:
+        removed.extend(remove_known_run_artifacts(stage))
+        scaffold(
+            goal=args.goal,
+            metric=args.metric,
+            direction=args.direction,
+            target=args.target,
+            max_iterations=args.max_iterations,
+            output=stage,
+            evaluator=args.evaluator,
+            keep_policy=args.keep_policy,
+            guard=args.guard,
+            noise_runs=args.noise_runs,
+            min_delta=args.min_delta,
+        )
+
+    atomic_publish(output, populate)
+    if removed:
+        print(f"Removed stale run artifacts: {', '.join(removed)}")
+    print_success(output)
+
+
+if __name__ == "__main__":
+    main()

package/skills/autoresearch/scripts/run_with_deadline.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Run one argv-safe command with a portable wall-clock deadline."""
+
+import argparse
+import math
+import os
+import signal
+import subprocess
+import sys
+from typing import List, Optional
+
+
+REAP_TIMEOUT_SECONDS = 2.0
+
+
+def parse_args(argv: Optional[List[str]] = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Run a command with a Python standard-library deadline."
+    )
+    parser.add_argument("seconds", type=float, help="Positive wall-clock deadline in seconds.")
+    parser.add_argument("command", nargs=argparse.REMAINDER, help="Command argv after --.")
+    args = parser.parse_args(argv)
+    if not math.isfinite(args.seconds) or args.seconds <= 0:
+        parser.error("seconds must be finite and greater than zero")
+    if not args.command:
+        parser.error("a command is required after --")
+    return args
+
+
+def _spawn(command: List[str]) -> subprocess.Popen:
+    if os.name == "posix":
+        return subprocess.Popen(command, start_new_session=True)
+    if os.name == "nt":
+        return subprocess.Popen(
+            command,
+            creationflags=subprocess.CREATE_NEW_PROCESS_GROUP,
+        )
+    return subprocess.Popen(command)
+
+
+def _reap(process: subprocess.Popen) -> bool:
+    try:
+        process.wait(timeout=REAP_TIMEOUT_SECONDS)
+        return True
+    except subprocess.TimeoutExpired:
+        process.kill()
+        process.wait()
+        return False
+
+
+def _known_posix_descendants(parent_pid: int) -> List[int]:
+    """Return one best-effort snapshot; this is discovery, not containment proof."""
+    try:
+        result = subprocess.run(
+            ["ps", "-axo", "pid=,ppid="],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            timeout=REAP_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return []
+    if result.returncode != 0:
+        return []
+    children = {}
+    for line in result.stdout.splitlines():
+        fields = line.split()
+        if len(fields) != 2:
+            continue
+        try:
+            pid, ppid = (int(field) for field in fields)
+        except ValueError:
+            continue
+        children.setdefault(ppid, []).append(pid)
+    descendants = []
+    pending = list(children.get(parent_pid, []))
+    while pending:
+        pid = pending.pop()
+        if pid in descendants:
+            continue
+        descendants.append(pid)
+        pending.extend(children.get(pid, []))
+    return descendants
+
+
+def _terminate_posix_group(process: subprocess.Popen) -> str:
+    try:
+        os.killpg(process.pid, signal.SIGSTOP)
+    except ProcessLookupError:
+        pass
+    except (OSError, PermissionError):
+        try:
+            process.send_signal(signal.SIGSTOP)
+        except (OSError, PermissionError):
+            pass
+    descendants = _known_posix_descendants(process.pid)
+    try:
+        os.killpg(process.pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+    except (OSError, PermissionError):
+        process.kill()
+    for pid in reversed(descendants):
+        try:
+            os.kill(pid, signal.SIGKILL)
+        except (ProcessLookupError, OSError, PermissionError):
+            pass
+    _reap(process)
+    return f"process-group+{len(descendants)}-known-descendant(s)"
+
+
+def _terminate_windows_tree(process: subprocess.Popen) -> str:
+    try:
+        result = subprocess.run(
+            ["taskkill", "/PID", str(process.pid), "/T", "/F"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=REAP_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        process.kill()
+        _reap(process)
+        return "process-only"
+    _reap(process)
+    return "taskkill-tree" if result.returncode == 0 else "process-only"
+
+
+def _terminate_tree(process: subprocess.Popen):
+    if os.name == "posix":
+        return (False, _terminate_posix_group(process))
+    if os.name == "nt":
+        return (False, _terminate_windows_tree(process))
+    process.kill()
+    _reap(process)
+    return (False, "process-only")
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = parse_args(argv)
+    try:
+        process = _spawn(args.command)
+    except FileNotFoundError as error:
+        print(f"command not found: {error.filename}", file=sys.stderr)
+        return 127
+    try:
+        return process.wait(timeout=args.seconds)
+    except subprocess.TimeoutExpired:
+        cleanup_complete, cleanup_type = _terminate_tree(process)
+        if cleanup_complete:
+            print(f"deadline exceeded after {args.seconds:g} seconds; cleanup={cleanup_type}", file=sys.stderr)
+        else:
+            print(
+                "BLOCKED_PROCESS_TREE_CLEANUP_UNVERIFIED: deadline exceeded after "
+                f"{args.seconds:g} seconds; best-effort cleanup={cleanup_type}; "
+                "manually inspect and stop residual processes",
+                file=sys.stderr,
+            )
+        return 124 if cleanup_complete else 125
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/autoresearch/scripts/style_presets.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""
+Matplotlib style presets for autoresearch-skill visualizations.
+Embedded from /lit-scientific-visualization skill for cross-platform portability.
+
+Usage in any visualize.py:
+    import sys, os
+    sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'scripts'))
+    from style_presets import rcparams
+    rcparams()  # MUST be called before any plt.subplots()
+"""
+
+import matplotlib.pyplot as plt
+import matplotlib as mpl
+from matplotlib import rcParams
+from matplotlib import font_manager
+
+# Okabe-Ito colorblind-friendly palette
+OKABE_ITO = [
+    '#E69F00',  # Orange
+    '#56B4E9',  # Sky Blue
+    '#009E73',  # Bluish Green
+    '#F0E442',  # Yellow
+    '#0072B2',  # Blue
+    '#D55E00',  # Vermillion
+    '#CC79A7',  # Reddish Purple
+    '#000000',  # Black
+]
+
+
+def rcparams():
+    """Apply publication-ready style. Call before any figure creation."""
+    # Font: Pretendard > Arial > system default
+    rcParams['font.family'] = 'sans-serif'
+    available = {f.name for f in font_manager.fontManager.ttflist}
+    if 'Pretendard' in available:
+        rcParams['font.sans-serif'] = ['Pretendard']
+    elif 'Arial' in available:
+        rcParams['font.sans-serif'] = ['Arial']
+
+    # Font sizes
+    rcParams['font.size'] = 14
+    rcParams['axes.titlesize'] = 18
+    rcParams['axes.titleweight'] = 'normal'
+    rcParams['axes.titlepad'] = 10
+    rcParams['axes.labelsize'] = 16
+    rcParams['axes.labelweight'] = 'normal'
+    rcParams['axes.labelpad'] = 8
+    rcParams['xtick.labelsize'] = 12
+    rcParams['ytick.labelsize'] = 12
+
+    # Ticks: inward, minor visible
+    rcParams['xtick.direction'] = 'in'
+    rcParams['ytick.direction'] = 'in'
+    rcParams['xtick.minor.visible'] = True
+    rcParams['ytick.minor.visible'] = True
+    rcParams['xtick.major.width'] = 1
+    rcParams['ytick.major.width'] = 1
+    rcParams['xtick.minor.width'] = 0.5
+    rcParams['ytick.minor.width'] = 0.5
+    rcParams['xtick.major.size'] = 5
+    rcParams['ytick.major.size'] = 5
+    rcParams['xtick.minor.size'] = 3
+    rcParams['ytick.minor.size'] = 3
+    rcParams['xtick.major.pad'] = 7
+    rcParams['ytick.major.pad'] = 7
+    rcParams['xtick.color'] = 'black'
+    rcParams['ytick.color'] = 'black'
+
+    # Axes
+    rcParams['axes.linewidth'] = 1
+    rcParams['axes.edgecolor'] = 'black'
+    rcParams['axes.labelcolor'] = 'black'
+    rcParams['axes.axisbelow'] = True
+    rcParams['axes.grid'] = False
+    rcParams['axes.prop_cycle'] = mpl.cycler(color=OKABE_ITO)
+
+    # Figure: WHITE background
+    rcParams['figure.figsize'] = (5, 4)
+    rcParams['figure.dpi'] = 100
+    rcParams['figure.facecolor'] = 'white'
+    rcParams['figure.autolayout'] = False
+
+    # Lines
+    rcParams['lines.linewidth'] = 1.5
+    rcParams['lines.markersize'] = 5
+    rcParams['lines.markeredgewidth'] = 0.5
+
+    # Legend: black border, fully opaque
+    rcParams['legend.fontsize'] = 12
+    rcParams['legend.frameon'] = True
+    rcParams['legend.edgecolor'] = 'black'
+    rcParams['legend.framealpha'] = 1
+    rcParams['legend.loc'] = 'best'
+
+    # Save: DPI > 500
+    rcParams['savefig.dpi'] = 600
+    rcParams['savefig.bbox'] = 'tight'
+    rcParams['savefig.pad_inches'] = 0.05
+    rcParams['savefig.transparent'] = False
+    rcParams['savefig.facecolor'] = 'white'
+
+    # Colormap
+    rcParams['image.cmap'] = 'viridis'