@litfamily/litgrok 1.0.0

package/.grok/skills/autoresearch/references/modes/security.md

@@ -0,0 +1,12 @@
+# Security review mode
+
+## Grok-native contract
+
+Select security in the skill selector; hand authorized probes/writes to the native `start-work` handoff and a subsequent approved session.
+Findings remain `REVIEW_REQUIRED` and cannot programmatically claim family completion. Changed
+evaluator or budget requires re-planning and review.
+
+Map assets, actors, trust boundaries, flows, entry points, and controls. Apply STRIDE and relevant
+OWASP checks with safe evidence. No exploitation, credential use, denial of service, persistence,
+external scanning, or secret collection occurs without specific authorization. Budget exhaustion
+never means secure.

package/.grok/skills/autoresearch/references/modes/ship/type-checklists.md

@@ -0,0 +1,12 @@
+# Artifact-type shipping checklists
+
+## Grok-native contract
+
+The skill selector loads these checklists; approved checks use the native `start-work` handoff and a subsequent approved session. Results
+remain `REVIEW_REQUIRED` and cannot programmatically claim family completion. Changed evaluator or
+budget requires re-planning and review.
+
+Packages: reproducible build, exact payload, executable modes, runtime requirements, install smoke,
+version lockstep, licenses, provenance, scanner, and dry packaging. Applications: tests,
+accessibility, security, migrations, rollback, monitoring, and docs. Skills: skill selector registration,
+installed paths, prompt boundaries, package enrollment, recursive scans, and host-shaped probes.

package/.grok/skills/autoresearch/references/modes/ship.md

@@ -0,0 +1,11 @@
+# Shipping-readiness mode
+
+## Grok-native contract
+
+Select ship in the skill selector; hand approved verification/artifact edits to native `start-work` and
+a bounded review cycle. Readiness remains `REVIEW_REQUIRED` and cannot programmatically claim family completion.
+Changed evaluator or budget requires re-planning and review.
+
+Inventory checks, exact payload, provenance, documentation, rollback, security, and known risk. Use
+host-bounded processes and capture exact evidence. Return GO/NO_GO readiness only. Publish, deploy,
+tag, release, push, version, registry, credentials, and live profile require separate approval.

package/.grok/skills/autoresearch/references/results-logging.md

@@ -0,0 +1,12 @@
+# Autoresearch result artifacts
+
+Skill selector guidance hands approved work to the native `start-work` handoff and a subsequent approved session. TSV/Markdown artifacts are
+`REVIEW_REQUIRED`, are not host state, and cannot programmatically claim family completion. Changed
+evaluator or budget requires re-planning and review.
+
+`autoresearch-results.tsv` contains iteration, metric value, delta, percentage, status, description,
+evaluator source, and timestamp. Iteration zero is baseline; positive integers are executed work.
+Reject malformed rows, duplicate ids, NaN/infinite values, evaluator drift, and unexplained gaps.
+
+Receipts should record evaluator/method identity, bounded command result, guards, changed paths, and
+cleanup. Reports may summarize target evidence or `BUDGET_EXHAUSTED`, but remain review material.

package/.grok/skills/autoresearch/references/visualization-guide.md

@@ -0,0 +1,24 @@
+# Optional autoresearch visualization
+
+Skill selector guidance hands approved writes to the native `start-work` handoff and a subsequent approved session. Plots remain
+`REVIEW_REQUIRED` and cannot programmatically claim family completion. Changed evaluator or budget
+requires re-planning and review.
+
+Resolve `<loaded-autoresearch-skill-dir>/scripts/style_presets.py --check`. The preflight must actually
+`import matplotlib`; discovery alone is insufficient. On
+`BLOCKED_OPTIONAL_MATPLOTLIB_UNAVAILABLE`, omit plots and do not modify the environment.
+
+The preflight only proves matplotlib imports; it applies nothing. Every figure script must also
+`import rcparams` from that same `scripts/style_presets.py` and call `rcparams()` **before**
+`plt.subplots()` or `plt.figure()`. Matplotlib reads its rcParams when the figure is constructed, so
+a call placed after that point silently does nothing and the shipped contract — `savefig.dpi` 600,
+`legend.framealpha` 1, `legend.edgecolor` black, the Okabe-Ito `axes.prop_cycle`, white facecolor,
+inward ticks — never reaches the output.
+
+For figure work beyond these run plots — journal sizing, multi-panel layout, export formats — use the
+`lit-scientific-visualization` skill rather than re-deriving its rules here.
+
+When available, show baseline, executed work points, kept/reverted/inconclusive labels, uncertainty,
+best-so-far, and target. Use accessible colors, visible units/endpoints, nonoverlapping labels, and a
+nonobscuring legend. Never hide failures or imply causality beyond receipts. Writes stay under the
+approved root and reject unsafe parents/leaves.

package/.grok/skills/autoresearch/scripts/init_research.py

@@ -0,0 +1,391 @@
+"""
+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 math
+import os
+import secrets
+import stat
+import sys
+import textwrap
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Tuple
+
+RESEARCH_TEMPLATE = """\
+# Research: {title}
+
+## 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"
+
+MANAGED_FILE_LEAVES = (
+    "research.md",
+    "research_log.md",
+    "autoresearch-results.tsv",
+    "final_report.md",
+    "progress.png",
+    "autoresearch-run-state.json",
+    ".autoresearch-loop.pid",
+)
+
+
+def fail(code: str, message: str) -> None:
+    print(f"Error: {code}: {message}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def preflight_capabilities() -> None:
+    """Fail before mutation unless the required Python/POSIX descriptor APIs exist."""
+    required_dir_fd = (os.open, os.mkdir, os.stat, os.unlink, os.link)
+    supported = (
+        sys.version_info >= (3, 8)
+        and hasattr(os, "O_DIRECTORY")
+        and hasattr(os, "O_NOFOLLOW")
+        and all(function in os.supports_dir_fd for function in required_dir_fd)
+        and os.listdir in os.supports_fd
+        and os.link in os.supports_follow_symlinks
+    )
+    if not supported:
+        fail(
+            "BLOCKED_UNSUPPORTED_PYTHON_POSIX_RUNTIME",
+            "requires Python 3.8+ with O_DIRECTORY, O_NOFOLLOW, dir_fd, fd-listdir, and no-follow link support",
+        )
+
+
+def same_directory_identity(left: os.stat_result, right: os.stat_result) -> bool:
+    """Compare path identity, including ctime to reject recreated directories."""
+    return (
+        left.st_dev,
+        left.st_ino,
+        left.st_mode,
+        left.st_uid,
+        left.st_ctime_ns,
+    ) == (
+        right.st_dev,
+        right.st_ino,
+        right.st_mode,
+        right.st_uid,
+        right.st_ctime_ns,
+    )
+
+
+def open_safe_directory(path: Path) -> Tuple[int, Path]:
+    """Create/open path one component at a time without following symlinks."""
+    absolute = Path(os.path.abspath(os.fspath(path)))
+    parts = absolute.parts
+    if not parts or not absolute.is_absolute():
+        fail("UNSAFE_OUTPUT_PATH", "output must resolve to an absolute filesystem path")
+
+    flags = os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_CLOEXEC", 0)
+    nofollow = getattr(os, "O_NOFOLLOW", 0)
+    fd = os.open(parts[0], flags | nofollow)
+    try:
+        for part in parts[1:]:
+            try:
+                info = os.stat(part, dir_fd=fd, follow_symlinks=False)
+            except FileNotFoundError:
+                try:
+                    os.mkdir(part, 0o755, dir_fd=fd)
+                except FileExistsError:
+                    pass
+                info = os.stat(part, dir_fd=fd, follow_symlinks=False)
+            if stat.S_ISLNK(info.st_mode):
+                fail("UNSAFE_OUTPUT_SYMLINK", f"output component is a symlink: {absolute}")
+            if not stat.S_ISDIR(info.st_mode):
+                fail("UNSAFE_OUTPUT_PATH", f"output component is not a directory: {absolute}")
+            next_fd = None
+            try:
+                next_fd = os.open(part, flags | nofollow, dir_fd=fd)
+                opened = os.fstat(next_fd)
+                if not same_directory_identity(info, opened):
+                    fail("UNSAFE_OUTPUT_SWAP", f"output component identity changed: {absolute}")
+            except BaseException:
+                if next_fd is not None:
+                    os.close(next_fd)
+                raise
+            os.close(fd)
+            fd = next_fd
+        verify_directory_identity(absolute, fd)
+        return fd, absolute
+    except BaseException:
+        os.close(fd)
+        raise
+
+
+def verify_directory_identity(path: Path, fd: int) -> None:
+    """Reject replacement of the opened output directory before each mutation."""
+    try:
+        named = os.stat(path, follow_symlinks=False)
+    except OSError as error:
+        fail("UNSAFE_OUTPUT_SWAP", f"output directory identity changed: {error}")
+    opened = os.fstat(fd)
+    if stat.S_ISLNK(named.st_mode) or not stat.S_ISDIR(named.st_mode):
+        fail("UNSAFE_OUTPUT_SYMLINK", f"output directory is no longer a real directory: {path}")
+    if not same_directory_identity(named, opened):
+        fail("UNSAFE_OUTPUT_SWAP", f"output directory identity changed: {path}")
+
+
+def leaf_info(fd: int, leaf: str) -> Optional[os.stat_result]:
+    try:
+        return os.stat(leaf, dir_fd=fd, follow_symlinks=False)
+    except FileNotFoundError:
+        return None
+
+
+def reject_unsafe_leaf(fd: int, leaf: str, *, directory: bool = False) -> None:
+    info = leaf_info(fd, leaf)
+    if info is None:
+        return
+    expected = stat.S_ISDIR(info.st_mode) if directory else stat.S_ISREG(info.st_mode)
+    if stat.S_ISLNK(info.st_mode) or not expected:
+        fail("UNSAFE_GENERATED_LEAF", f"generated leaf has unsafe type: {leaf}")
+
+
+def remove_regular_leaf(fd: int, root: Path, leaf: str) -> None:
+    reject_unsafe_leaf(fd, leaf)
+    if leaf_info(fd, leaf) is not None:
+        verify_directory_identity(root, fd)
+        os.unlink(leaf, dir_fd=fd)
+
+
+def write_new_leaf(fd: int, root: Path, leaf: str, text: str) -> None:
+    """Create a leaf without overwrite; a competing leaf creation fails closed."""
+    verify_directory_identity(root, fd)
+    if leaf_info(fd, leaf) is not None:
+        fail("UNSAFE_GENERATED_LEAF", f"generated leaf appeared during scaffold: {leaf}")
+    temp = f".{leaf}.tmp-{os.getpid()}-{secrets.token_hex(6)}"
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+    temp_fd = None
+    temp_created = False
+    try:
+        temp_fd = os.open(temp, flags, 0o600, dir_fd=fd)
+        temp_created = True
+        try:
+            data = text.encode("utf-8")
+            while data:
+                written = os.write(temp_fd, data)
+                data = data[written:]
+            os.fsync(temp_fd)
+        finally:
+            os.close(temp_fd)
+            temp_fd = None
+        verify_directory_identity(root, fd)
+        os.link(temp, leaf, src_dir_fd=fd, dst_dir_fd=fd, follow_symlinks=False)
+    except FileExistsError:
+        fail("UNSAFE_GENERATED_LEAF", f"generated leaf appeared during scaffold: {leaf}")
+    finally:
+        if temp_fd is not None:
+            try:
+                os.close(temp_fd)
+            except OSError:
+                pass
+        if temp_created:
+            try:
+                os.unlink(temp, dir_fd=fd)
+            except FileNotFoundError:
+                pass
+
+
+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 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).")
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite this scaffold's generated files in a non-empty output directory.",
+    )
+    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,
+             force: bool = False) -> 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)_"
+
+    fd, output = open_safe_directory(output)
+    try:
+        entries = os.listdir(fd)
+        if entries and not force:
+            fail(
+                "OUTPUT_NOT_EMPTY",
+                f"output directory '{output}' already exists and is not empty. "
+                "Use --force to overwrite generated files.",
+            )
+        reject_unsafe_leaf(fd, "workspace", directory=True)
+        for leaf in MANAGED_FILE_LEAVES:
+            reject_unsafe_leaf(fd, leaf)
+        if force:
+            for leaf in MANAGED_FILE_LEAVES:
+                remove_regular_leaf(fd, output, leaf)
+        if leaf_info(fd, "workspace") is None:
+            verify_directory_identity(output, fd)
+            os.mkdir("workspace", 0o755, dir_fd=fd)
+
+    # Write research.md
+        research_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_new_leaf(fd, output, "research.md", research_text)
+
+    # Write research_log.md
+        write_new_leaf(fd, output, "research_log.md", LOG_TEMPLATE.format(date=date, goal=goal))
+
+    # Write autoresearch-results.tsv
+        write_new_leaf(fd, output, "autoresearch-results.tsv", TSV_HEADER + TSV_BASELINE.format(date=date))
+        verify_directory_identity(output, fd)
+    finally:
+        os.close(fd)
+
+    # Print success message
+    print(f"\nResearch project scaffolded at: {output.resolve()}")
+    print(f"\nFiles created:")
+    print(f"  {output / 'research.md'}")
+    print(f"  {output / 'research_log.md'}")
+    print(f"  {output / 'autoresearch-results.tsv'}")
+    print(f"  {output / 'workspace'}/")
+    print(f"\nNext steps:")
+    print(f"  1. Open research.md and fill in 'Current Approach' and 'Search Space'.")
+    print(f"  2. Add context (papers, docs, code) under 'Context & References'.")
+    print(f"  3. Run your baseline experiment and record it in the History table.")
+    print(f"  4. Start iterating: modify → measure → log → repeat.")
+    print("  5. Select the explicit autoresearch skill request, approve a plan, then select the native start-work skill.")
+
+
+def main() -> None:
+    args = parse_args()
+    if args.max_iterations < 1:
+        fail("INVALID_BUDGET", "--max-iterations must be >= 1")
+    if args.noise_runs < 1:
+        fail("INVALID_BUDGET", "--noise-runs must be >= 1")
+    if not math.isfinite(args.min_delta) or args.min_delta < 0:
+        fail("INVALID_BUDGET", "--min-delta must be finite and >= 0")
+    preflight_capabilities()
+    output = Path(args.output)
+
+    scaffold(
+        goal=args.goal,
+        metric=args.metric,
+        direction=args.direction,
+        target=args.target,
+        max_iterations=args.max_iterations,
+        output=output,
+        evaluator=args.evaluator,
+        keep_policy=args.keep_policy,
+        guard=args.guard,
+        noise_runs=args.noise_runs,
+        min_delta=args.min_delta,
+        force=args.force,
+    )
+
+
+if __name__ == "__main__":
+    main()

package/.grok/skills/autoresearch/scripts/style_presets.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Optional matplotlib style presets for installed LitGrok autoresearch runs.
+
+Call rcparams() before plt.subplots() or plt.figure(). Matplotlib snapshots rcParams
+when a figure is constructed, so a later call is silently ignored and every preset
+below — dpi, legend framing, the Okabe-Ito cycle, tick direction — is lost.
+"""
+
+import importlib
+import json
+import sys
+from typing import Dict
+
+
+OKABE_ITO = [
+    "#E69F00",
+    "#56B4E9",
+    "#009E73",
+    "#F0E442",
+    "#0072B2",
+    "#D55E00",
+    "#CC79A7",
+    "#000000",
+]
+
+
+def matplotlib_available() -> bool:
+    """Return whether the optional plotting dependency imports successfully."""
+    try:
+        importlib.import_module("matplotlib")
+    except Exception:
+        return False
+    return True
+
+
+def preflight_report() -> Dict[str, object]:
+    """Return a stable, non-installing optional dependency verdict."""
+    available = matplotlib_available()
+    return {
+        "available": available,
+        "code": (
+            "OPTIONAL_MATPLOTLIB_READY"
+            if available
+            else "BLOCKED_OPTIONAL_MATPLOTLIB_UNAVAILABLE"
+        ),
+    }
+
+
+def rcparams() -> None:
+    """Apply the retained style after an explicit dependency preflight."""
+    if not matplotlib_available():
+        raise RuntimeError("BLOCKED_OPTIONAL_MATPLOTLIB_UNAVAILABLE")
+
+    import matplotlib as mpl
+    from matplotlib import font_manager, rcParams
+
+    rcParams["font.family"] = "sans-serif"
+    available_fonts = {font.name for font in font_manager.fontManager.ttflist}
+    if "Pretendard" in available_fonts:
+        rcParams["font.sans-serif"] = ["Pretendard"]
+    elif "Arial" in available_fonts:
+        rcParams["font.sans-serif"] = ["Arial"]
+
+    rcParams.update(
+        {
+            "font.size": 14,
+            "axes.titlesize": 18,
+            "axes.titleweight": "normal",
+            "axes.titlepad": 10,
+            "axes.labelsize": 16,
+            "axes.labelweight": "normal",
+            "axes.labelpad": 8,
+            "axes.linewidth": 1,
+            "axes.edgecolor": "black",
+            "axes.labelcolor": "black",
+            "axes.axisbelow": True,
+            "axes.grid": False,
+            "axes.prop_cycle": mpl.cycler(color=OKABE_ITO),
+            "xtick.labelsize": 12,
+            "ytick.labelsize": 12,
+            "xtick.direction": "in",
+            "ytick.direction": "in",
+            "xtick.minor.visible": True,
+            "ytick.minor.visible": True,
+            "xtick.major.width": 1,
+            "ytick.major.width": 1,
+            "xtick.minor.width": 0.5,
+            "ytick.minor.width": 0.5,
+            "xtick.major.size": 5,
+            "ytick.major.size": 5,
+            "xtick.minor.size": 3,
+            "ytick.minor.size": 3,
+            "xtick.major.pad": 7,
+            "ytick.major.pad": 7,
+            "xtick.color": "black",
+            "ytick.color": "black",
+            "figure.figsize": (5, 4),
+            "figure.dpi": 100,
+            "figure.facecolor": "white",
+            "figure.autolayout": False,
+            "lines.linewidth": 1.5,
+            "lines.markersize": 5,
+            "lines.markeredgewidth": 0.5,
+            "legend.fontsize": 12,
+            "legend.frameon": True,
+            "legend.edgecolor": "black",
+            "legend.framealpha": 1,
+            "legend.loc": "best",
+            "savefig.dpi": 600,
+            "savefig.bbox": "tight",
+            "savefig.pad_inches": 0.05,
+            "savefig.transparent": False,
+            "savefig.facecolor": "white",
+            "image.cmap": "viridis",
+        }
+    )
+
+
+if __name__ == "__main__":
+    if sys.argv[1:] != ["--check"]:
+        print("Usage: python style_presets.py --check", file=sys.stderr)
+        raise SystemExit(2)
+    print(json.dumps(preflight_report(), sort_keys=True))