@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/skills/autoconference/scripts/init_conference.py

@@ -0,0 +1,656 @@
+"""
+init_conference.py — Scaffold a new autoconference-skill project directory.
+
+Usage:
+    python init_conference.py --goal "..." --metric "..." --direction {maximize|minimize} \
+        [--target "..."] [--researchers 3] [--strategy assigned] \
+        [--devils-advocate {yes|no}] [--output ./conference/]
+
+    python init_conference.py --goal "..." --mode qualitative --criteria "..." \
+        [--researchers 3] [--output ./conference/]
+"""
+
+import argparse
+import math
+import os
+import re
+import secrets
+import stat
+import string
+import sys
+import textwrap
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+
+CONFERENCE_TEMPLATE_METRIC = """\
+# Conference: {title}
+
+## Goal
+{goal}
+
+## Mode
+metric
+
+## Success Metric
+- **Metric:** {metric}
+- **Target:** {target}
+- **Direction:** {direction}
+
+## Researchers
+- **Count:** {researchers}
+- **Iterations per round:** {iterations_per_round}
+- **Max rounds:** {max_rounds}
+
+## Pre-Flight Gate
+- **Researcher count:** {researchers}
+- **Iterations per round:** {iterations_per_round}
+- **Max rounds:** {max_rounds}
+- **Max total iterations:** {max_total_iterations}
+- **Success definition:** {gate_success_definition}
+- **Critic / Devil's Advocate:** {critic_setting}
+- **Final confirmation:** pending — Conference Chair must summarize these conditions and get explicit user confirmation before execution.
+- **Missing or vague values:** ask the user for exact values first, then recalculate this gate and request final confirmation. Do not start Phase 1 until confirmation is explicit.
+
+## Search Space
+- **Allowed changes:** _Define what researchers can modify._
+- **Forbidden changes:** _Define what must NOT change (e.g., test data, eval scripts)._
+
+## Search Space Partitioning
+- **Strategy:** {strategy}
+
+{researcher_sections}
+
+## Guard
+{guard}
+
+## Noise Handling
+- **Noise runs:** {noise_runs}
+- **Min consensus delta:** {min_delta}
+
+## Constraints
+- **Max total iterations:** {max_total_iterations}
+- **Time budget:** 2h
+- **Researcher timeout:** 30m
+
+## Current Approach
+_Describe the baseline. What exists now?_
+
+## Shared Knowledge
+<!-- Auto-populated after each round with validated findings -->
+
+## Context & References
+_Add relevant papers, docs, or URLs here._
+
+---
+
+## Conference Log
+<!-- Auto-maintained by Conference Chair. Do not edit manually. -->
+| Round | Researcher | Best Metric | Key Finding | Status |
+|-------|-----------|-------------|-------------|--------|
+"""
+
+CONFERENCE_TEMPLATE_QUALITATIVE = """\
+# Conference: {title}
+
+## Goal
+{goal}
+
+## Mode
+qualitative
+
+## Success Criteria
+{criteria}
+
+## Researchers
+- **Count:** {researchers}
+- **Iterations per round:** {iterations_per_round}
+- **Max rounds:** {max_rounds}
+
+## Pre-Flight Gate
+- **Researcher count:** {researchers}
+- **Iterations per round:** {iterations_per_round}
+- **Max rounds:** {max_rounds}
+- **Max total iterations:** {max_total_iterations}
+- **Success definition:** {gate_success_definition}
+- **Critic / Devil's Advocate:** {critic_setting}
+- **Final confirmation:** pending — Conference Chair must summarize these conditions and get explicit user confirmation before execution.
+- **Missing or vague values:** ask the user for exact values first, then recalculate this gate and request final confirmation. Do not start Phase 1 until confirmation is explicit.
+
+## Search Space
+- **Allowed changes:** _Define what researchers can modify._
+- **Forbidden changes:** _Define what must NOT change._
+
+## Search Space Partitioning
+- **Strategy:** {strategy}
+
+{researcher_sections}
+
+## Guard
+{guard}
+
+## Noise Handling
+- **Noise runs:** {noise_runs}
+- **Min consensus delta:** {min_delta}
+
+## Constraints
+- **Max total iterations:** {max_total_iterations}
+- **Time budget:** 2h
+- **Researcher timeout:** 30m
+
+## Current Approach
+_Describe the baseline. What exists now?_
+
+## Shared Knowledge
+<!-- Auto-populated after each round with validated findings -->
+
+## Context & References
+_Add relevant papers, docs, or URLs here._
+
+---
+
+## Conference Log
+<!-- Auto-maintained by Conference Chair. Do not edit manually. -->
+| Round | Researcher | Best Metric | Key Finding | Status |
+|-------|-----------|-------------|-------------|--------|
+"""
+
+LOG_TEMPLATE = """\
+# Researcher {rid} Log
+
+> Auto-generated by init_conference.py on {date}
+> Conference goal: {goal}
+
+---
+
+"""
+
+RESEARCHER_TSV_HEADER = "iteration\tmetric_value\tdelta\tdelta_pct\tstatus\tdescription\tevaluator_source\ttimestamp\n"
+RESEARCHER_TSV_BASELINE = "0\tTBD\t-\t-\tbaseline\tInitial state\tmanual\t{date}\n"
+
+CONFERENCE_TSV_HEADER = (
+    "round\tresearcher\titeration\tmetric_value\tdelta\tdelta_pct\t"
+    "status\tdescription\tevaluator_source\tpeer_review_verdict\ttimestamp\n"
+)
+
+STATIC_MANAGED_FILE_LEAVES = (
+    "conference.md",
+    "conference_results.tsv",
+    "conference_events.jsonl",
+    "synthesis.md",
+    "conference_report.md",
+    "autoconference-run-state.json",
+    ".autoconference-loop.pid",
+)
+RESEARCHER_LEAF = re.compile(r"researcher_[A-Z]_(?:log\.md|results\.tsv)\Z")
+
+
+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 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 index, part in enumerate(parts[1:], start=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 = os.open(part, flags | nofollow, dir_fd=fd)
+            try:
+                verify_directory_identity(
+                    Path(os.path.join(*parts[: index + 1])),
+                    next_fd,
+                    info,
+                    compare_ctime=index == len(parts) - 1,
+                )
+            except BaseException:
+                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 _directory_identity(
+    info: os.stat_result,
+    *,
+    include_ctime: bool = True,
+) -> Tuple[int, int, Optional[int], Optional[int]]:
+    identity = (info.st_dev, info.st_ino, getattr(info, "st_birthtime_ns", None))
+    return (*identity, info.st_ctime_ns if include_ctime else None)
+
+
+def verify_directory_identity(
+    path: Path,
+    fd: int,
+    expected: Optional[os.stat_result] = None,
+    *,
+    compare_ctime: bool = True,
+) -> None:
+    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 expected is not None:
+        # The parent descriptor anchors this component.  Comparing the stale
+        # pre-open snapshot with the opened descriptor catches a replacement
+        # without rejecting an unrelated ctime change in an ancestor while
+        # the path is being walked.
+        if _directory_identity(expected, include_ctime=compare_ctime) != _directory_identity(
+            opened,
+            include_ctime=compare_ctime,
+        ):
+            fail("UNSAFE_OUTPUT_SWAP", f"output directory identity changed: {path}")
+        return
+    if _directory_identity(named) != _directory_identity(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:
+    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:
+    words = goal.split()
+    short = " ".join(words[:8])
+    if len(words) > 8:
+        short += "..."
+    return short.title()
+
+
+def researcher_ids(count: int) -> List[str]:
+    return [string.ascii_uppercase[i] for i in range(count)]
+
+
+def make_researcher_sections(rids: List[str], strategy: str) -> str:
+    if strategy != "assigned":
+        return ""
+    lines = []
+    for rid in rids:
+        lines.append(f"### Researcher {rid} Focus")
+        lines.append(f"_Describe Researcher {rid}'s exploration area._")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Scaffold a new autoconference-skill project.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=textwrap.dedent("""\
+            Examples:
+              # Metric mode
+              python init_conference.py \\
+                --goal "Optimize inference latency" \\
+                --metric "p95_latency_ms" \\
+                --direction minimize \\
+                --target "< 50" \\
+                --researchers 3 \\
+                --devils-advocate yes \\
+                --strategy assigned \\
+                --output ./my-conference/
+
+              # Qualitative mode
+              python init_conference.py \\
+                --goal "Survey LLM agent papers" \\
+                --mode qualitative \\
+                --criteria "Comprehensive taxonomy with 15+ papers" \\
+                --researchers 2 \\
+                --output ./lit-review/
+        """),
+    )
+    parser.add_argument("--goal", required=True, help="Conference goal description.")
+    parser.add_argument(
+        "--mode",
+        default="metric",
+        choices=["metric", "qualitative"],
+        help="Conference mode. Default: metric",
+    )
+    parser.add_argument(
+        "--metric",
+        default=None,
+        help="Metric name to track (required for metric mode).",
+    )
+    parser.add_argument(
+        "--direction",
+        default=None,
+        choices=["maximize", "minimize"],
+        help="Whether to maximize or minimize the metric (required for metric mode).",
+    )
+    parser.add_argument(
+        "--target",
+        default=None,
+        help="Target value or expression (e.g. '> 0.9', '< 50'). Required for metric mode.",
+    )
+    parser.add_argument(
+        "--criteria",
+        default=None,
+        help="Success criteria text (required for qualitative mode).",
+    )
+    parser.add_argument(
+        "--researchers",
+        type=int,
+        default=3,
+        metavar="N",
+        help="Number of researchers. Default: 3",
+    )
+    parser.add_argument(
+        "--strategy",
+        default="free",
+        choices=["assigned", "free"],
+        help="Search space partitioning strategy. Default: free",
+    )
+    parser.add_argument(
+        "--iterations-per-round",
+        type=int,
+        default=5,
+        metavar="N",
+        help="Iterations per round per researcher. Default: 5",
+    )
+    parser.add_argument(
+        "--max-rounds",
+        type=int,
+        default=4,
+        metavar="N",
+        help="Maximum number of rounds. Default: 4",
+    )
+    parser.add_argument(
+        "--devils-advocate",
+        default=None,
+        choices=["yes", "no"],
+        help=(
+            "Whether one researcher should be assigned as a Devil's Advocate. "
+            "If omitted, conference.md marks this as a required user prompt before running."
+        ),
+    )
+    parser.add_argument(
+        "--guard",
+        default=None,
+        help="Safety constraint applied to all researchers (e.g., 'Do not modify the test set').",
+    )
+    parser.add_argument(
+        "--noise-runs",
+        type=int,
+        default=1,
+        metavar="N",
+        help="Repeated evaluations to average for noise reduction. Default: 1",
+    )
+    parser.add_argument(
+        "--min-delta",
+        type=float,
+        default=0.0,
+        metavar="F",
+        help="Minimum average improvement across kept researchers to advance. Default: 0.0",
+    )
+    parser.add_argument(
+        "--output",
+        default="./conference/",
+        metavar="PATH",
+        help="Output directory. Default: ./conference/",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite existing output directory without prompting.",
+    )
+    return parser.parse_args()
+
+
+def validate_args(args: argparse.Namespace) -> None:
+    if args.mode == "metric":
+        if not args.metric:
+            print("Error: --metric is required when --mode is metric.", file=sys.stderr)
+            sys.exit(1)
+        if not args.direction:
+            print("Error: --direction is required when --mode is metric.", file=sys.stderr)
+            sys.exit(1)
+        normalized_target = args.target.strip().lower() if args.target else ""
+        if not normalized_target or normalized_target in {"tbd", "todo", "unknown"}:
+            print("Error: --target is required when --mode is metric.", file=sys.stderr)
+            sys.exit(1)
+    elif args.mode == "qualitative":
+        if not args.criteria:
+            print("Error: --criteria is required when --mode is qualitative.", file=sys.stderr)
+            sys.exit(1)
+
+    if args.researchers < 1:
+        fail("INVALID_BUDGET", "--researchers must be >= 1")
+
+    if args.researchers > 26:
+        fail("INVALID_BUDGET", "--researchers must be <= 26")
+
+    if args.iterations_per_round < 1:
+        fail("INVALID_BUDGET", "--iterations-per-round must be >= 1")
+
+    if args.max_rounds < 1:
+        fail("INVALID_BUDGET", "--max-rounds 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")
+
+
+def scaffold(args: argparse.Namespace) -> None:
+    date = datetime.now().strftime("%Y-%m-%d")
+    title = goal_to_title(args.goal)
+    output = Path(args.output)
+    rids = researcher_ids(args.researchers)
+    max_total_iterations = args.researchers * args.iterations_per_round * args.max_rounds
+    researcher_sections = make_researcher_sections(rids, args.strategy)
+    guard_text = args.guard if args.guard else "_No guard constraint. Leave blank or define a safety invariant._"
+    noise_runs = args.noise_runs
+    min_delta = args.min_delta
+    if args.devils_advocate == "yes":
+        critic_setting = "enabled"
+    elif args.devils_advocate == "no":
+        critic_setting = "disabled"
+    else:
+        critic_setting = "ask user before run"
+
+    fd, output = open_safe_directory(output)
+    try:
+        entries = os.listdir(fd)
+        if entries and not args.force:
+            fail(
+                "OUTPUT_NOT_EMPTY",
+                f"output directory '{output}' already exists and is not empty. Use --force to overwrite.",
+            )
+        reject_unsafe_leaf(fd, "workspace", directory=True)
+        managed = list(STATIC_MANAGED_FILE_LEAVES)
+        managed.extend(entry for entry in entries if RESEARCHER_LEAF.fullmatch(entry))
+        for leaf in managed:
+            reject_unsafe_leaf(fd, leaf)
+        if args.force:
+            for leaf in managed:
+                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)
+
+        if args.mode == "metric":
+            gate_success_definition = f"metric {args.metric} ({args.direction}) target {args.target}"
+            conf_text = CONFERENCE_TEMPLATE_METRIC.format(
+                title=title,
+                goal=args.goal,
+                metric=args.metric,
+                target=args.target,
+                direction=args.direction,
+                researchers=args.researchers,
+                iterations_per_round=args.iterations_per_round,
+                max_rounds=args.max_rounds,
+                strategy=args.strategy,
+                researcher_sections=researcher_sections,
+                max_total_iterations=max_total_iterations,
+                guard=guard_text,
+                noise_runs=noise_runs,
+                min_delta=min_delta,
+                gate_success_definition=gate_success_definition,
+                critic_setting=critic_setting,
+            )
+        else:
+            gate_success_definition = f"criteria: {args.criteria}"
+            conf_text = CONFERENCE_TEMPLATE_QUALITATIVE.format(
+                title=title,
+                goal=args.goal,
+                criteria=args.criteria,
+                researchers=args.researchers,
+                iterations_per_round=args.iterations_per_round,
+                max_rounds=args.max_rounds,
+                strategy=args.strategy,
+                researcher_sections=researcher_sections,
+                max_total_iterations=max_total_iterations,
+                guard=guard_text,
+                noise_runs=noise_runs,
+                min_delta=min_delta,
+                gate_success_definition=gate_success_definition,
+                critic_setting=critic_setting,
+            )
+        write_new_leaf(fd, output, "conference.md", conf_text)
+
+        for rid in rids:
+            log = LOG_TEMPLATE.format(rid=rid, date=date, goal=args.goal)
+            write_new_leaf(fd, output, f"researcher_{rid}_log.md", log)
+            tsv = RESEARCHER_TSV_HEADER + RESEARCHER_TSV_BASELINE.format(date=date)
+            write_new_leaf(fd, output, f"researcher_{rid}_results.tsv", tsv)
+
+        write_new_leaf(fd, output, "conference_results.tsv", CONFERENCE_TSV_HEADER)
+        write_new_leaf(fd, output, "conference_events.jsonl", "")
+        verify_directory_identity(output, fd)
+    finally:
+        os.close(fd)
+
+    # Print success
+    print(f"\nConference project scaffolded at: {output.resolve()}")
+    print(f"\nFiles created:")
+    print(f"  conference.md")
+    for rid in rids:
+        print(f"  researcher_{rid}_log.md")
+        print(f"  researcher_{rid}_results.tsv")
+    print(f"  conference_results.tsv")
+    print(f"  conference_events.jsonl")
+    print(f"  workspace/")
+    print(f"\nPre-flight gate:")
+    print(f"  Researcher count: {args.researchers}")
+    print(f"  Max total iterations: {max_total_iterations}")
+    print(f"  Success definition: {gate_success_definition}")
+    print(f"  Critic / Devil's Advocate: {critic_setting}")
+    print("  Final confirmation: pending before Phase 1")
+    print(f"\nNext steps:")
+    print(f"  1. Open conference.md and fill in 'Current Approach' and 'Search Space'.")
+    print(f"  2. Edit researcher focus areas if using 'assigned' strategy.")
+    print("  3. Select $litcodex:autoconference and provide the generated conference.md path.")
+    print("  4. Approve the plan, then select $litcodex:start-work for the root-owned conference.")
+
+
+def main() -> None:
+    args = parse_args()
+    validate_args(args)
+    preflight_capabilities()
+    scaffold(args)
+
+
+if __name__ == "__main__":
+    main()