@litfamily/litopencode 1.0.0

package/skills/autoconference/scripts/init_conference.py

@@ -0,0 +1,625 @@
+"""
+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 os
+import shutil
+import stat
+import string
+import sys
+import tempfile
+import textwrap
+from datetime import datetime
+from pathlib import Path
+from typing import Callable, List
+
+
+CONFERENCE_TEMPLATE_METRIC = """\
+# Conference: {title}
+
+> **Scaffold status: INCOMPLETE.** This file contains labeled placeholders. It is not an approved
+> conference plan. Complete and validate every placeholder through explicit /start-work before any
+> mutation, evaluator execution, or task dispatch.
+
+## 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}
+
+> **Scaffold status: INCOMPLETE.** This file contains labeled placeholders. It is not an approved
+> conference plan. Complete and validate every placeholder through explicit /start-work before any
+> mutation, evaluator execution, or task dispatch.
+
+## 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"
+)
+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:
+    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 remove_known_run_artifacts(output: Path) -> List[str]:
+    """Remove only prior-run files owned by this workflow."""
+    candidates = [
+        output / "synthesis.md",
+        output / "final_report.md",
+        output / "results.png",
+        output / ".autoconference-loop.pid",
+    ]
+    for pattern in [
+        "researcher_*_log.md",
+        "researcher_*_results.tsv",
+        "poster_session_round_*.md",
+        "peer_review_round_*.md",
+    ]:
+        candidates.extend(output.glob(pattern))
+
+    candidates = sorted(set(candidates), key=lambda item: item.name)
+    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 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=(
+            "Reinitialize managed scaffold files while preserving regular user files "
+            "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:
+        print("Error: --researchers must be >= 1.", file=sys.stderr)
+        sys.exit(1)
+
+    if args.researchers > 26:
+        print("Error: --researchers must be <= 26.", file=sys.stderr)
+        sys.exit(1)
+
+    if args.iterations_per_round < 1:
+        print("Error: --iterations-per-round must be >= 1.", file=sys.stderr)
+        sys.exit(1)
+
+    if args.max_rounds < 1:
+        print("Error: --max-rounds must be >= 1.", file=sys.stderr)
+        sys.exit(1)
+
+    if args.noise_runs < 1:
+        print("Error: --noise-runs must be >= 1.", file=sys.stderr)
+        sys.exit(1)
+
+
+def scaffold(args: argparse.Namespace, output: Path) -> tuple:
+    date = datetime.now().strftime("%Y-%m-%d")
+    title = goal_to_title(args.goal)
+    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"
+
+    # Create workspace subdirectory
+    (output / "workspace").mkdir(exist_ok=True)
+
+    # Write conference.md
+    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,
+        )
+    (output / "conference.md").write_text(conf_text)
+
+    # Write per-researcher files
+    for rid in rids:
+        log = LOG_TEMPLATE.format(rid=rid, date=date, goal=args.goal)
+        (output / f"researcher_{rid}_log.md").write_text(log)
+
+        tsv = RESEARCHER_TSV_HEADER + RESEARCHER_TSV_BASELINE.format(date=date)
+        (output / f"researcher_{rid}_results.tsv").write_text(tsv)
+
+    # Write conference_results.tsv (header only)
+    (output / "conference_results.tsv").write_text(CONFERENCE_TSV_HEADER)
+
+    # Write conference_events.jsonl (empty)
+    (output / "conference_events.jsonl").write_text("")
+
+    return (rids, max_total_iterations, gate_success_definition, critic_setting)
+
+
+def print_success(output: Path, details: tuple) -> None:
+    rids, max_total_iterations, gate_success_definition, critic_setting = details
+    print(f"\nINCOMPLETE scaffold created at: {output.resolve()}")
+    print("\nFiles created:")
+    print("  conference.md")
+    for rid in rids:
+        print(f"  researcher_{rid}_log.md")
+        print(f"  researcher_{rid}_results.tsv")
+    print("  conference_results.tsv")
+    print("  conference_events.jsonl")
+    print("  workspace/")
+    print("\nPre-flight gate:")
+    print(f"  Researcher count: {len(rids)}")
+    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("\nNext steps — this is an incomplete scaffold with placeholders:")
+    print("  1. Through explicit /start-work, fill in 'Current Approach' and 'Search Space'.")
+    print("  2. Edit researcher focus areas if using 'assigned' strategy.")
+    print("  3. Validate every placeholder, evaluator receipt, root, and task packet.")
+    print("  4. Only then may the approved finite conference continue through explicit /start-work.")
+
+
+def main() -> None:
+    args = parse_args()
+    validate_args(args)
+    output = validate_output_tree(Path(args.output))
+    if output.exists() and any(output.iterdir()) and not args.force:
+        print(
+            f"Error: output directory '{output}' already exists and is not empty. "
+            "Use --force to reinitialize managed scaffold files.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    removed = []
+    details = []
+    def populate(stage: Path) -> None:
+        removed.extend(remove_known_run_artifacts(stage))
+        details.append(scaffold(args, stage))
+
+    atomic_publish(output, populate)
+    if removed:
+        print(f"Removed stale run artifacts: {', '.join(removed)}")
+    print_success(output, details[0])
+
+
+if __name__ == "__main__":
+    main()