Skip to content

armelhbobdad/oh-my-skills / .claude/skills/skf-campaign

skf-campaign

Verified

Campaign orchestration — multi-library skill production with dependency tracking, file-based state, and resume. Use when the user asks to "run a campaign" or "orchestrate skills."

scripts/campaign-state.py

View on GitHub
# /// script
# requires-python = ">=3.11"
# dependencies = ["pyyaml", "jsonschema>=4.0"]
# ///
"""Campaign State: every write to _campaign-state.yaml, and the resume point.

The campaign's progress lives in one YAML file that must survive a session
dying at any moment. The step files used to re-type the whole file on every
change: copy it to .bak, edit it in memory, type a timestamp with no clock to
read, write it back, and check it only when the next step loaded it. A bad
write for one skill was then copied over the last good .bak by the next
write, and resume found both files invalid. This script owns every write, so
the step files name an operation and its inputs and never touch the YAML.

Each write operation, in this order:

  1. reads the state and validates it (campaign-validate-state.py's schema
     check, date-time fields included): an invalid state is never rotated
     into .bak, and nothing is written (exit 3);
  2. applies the operation, sets `campaign.current_stage` when --stage is
     given, and stamps `campaign.last_updated` (and any started_at or
     completed_at the operation sets) from the system clock, in UTC;
  3. validates the result: a change that would make the state invalid is
     refused and nothing is written (exit 3);
  4. copies the primary it read, which validated, to the .bak beside it,
     then writes the new state; each file is written to a temporary file
     and renamed over the old one, so a crash leaves the old file or the
     new one, never half of one.

Operations:

  init              Create the state (step-01). Reads the parsed targets
                    (campaign-parse-manifest.py's JSON output, a file or `-`
                    for stdin) and settles the quality gate through
                    campaign-quality-gate.py's check (a brief's
                    quality_gate wins when --brief-file names one). Refuses
                    a state file or backup that already exists. With
                    --brief-out it also writes campaign-brief.yaml from
                    --brief-template (the template's mapping, its keys in
                    their order, after its leading comment block): the
                    campaign name, created_at (the state's started_at), the
                    same targets[] with every field each one carries
                    (repo_url, which the state has no place for, and any
                    hint), the settled quality_gate, architecture_doc_path
                    and notes (--notes, else the --brief-file's notes, else
                    empty). The template is read before anything is written;
                    the brief is written right after the state, and a resume
                    that finds the state without it halts (missing-brief).
  set-stage         Write current_stage alone: a stage's final write when it
                    records nothing else.
  set-skill         Set the status, quality_score, skill_path or brief_path
                    of one or more skills (--skill repeats). `active` stamps
                    started_at when it is not set yet (an interrupted run
                    keeps its start); `completed` stamps completed_at;
                    `pending` (a reset for a re-run) clears both and the
                    export outcome. --export records the Export stage's
                    outcome (step-10) as `export`: `exported`, or `failed`
                    with --export-halt-reason and --export-exit-code from
                    the skf-export-skill call.
  apply-plan        Write the execution order and the cycle flag that
                    campaign-deps.py --compute gives for the state (step-02);
                    refuses a plan the stages cannot follow (exit 4).
  apply-pins        Write the resolved pins from campaign-validate-pins.py's
                    output (step-03); refuses output with an invalid pin
                    (exit 5).
  apply-provenance  Write each commit SHA from campaign-provenance.py's
                    output (step-04); refuses output with an inaccessible
                    repository (exit 6).
  apply-batch       The Tier B batch (step-06), from the line-to-skill map
                    campaign-render-batch.py wrote: --start marks the map's
                    skipped_by_directive skills `skipped` and its batched
                    skills `active`; --results-file records the joined
                    results (campaign-render-batch.py --record output);
                    --no-results fails every batched skill.
  append-workarounds
                    Append entries to one skill's workarounds_applied; an
                    entry it already holds is not added twice.
  set-campaign      Write campaign-level fields: the architecture document
                    path, and the capstone, verification or refinement
                    summary read from the sub-skill's result envelope line
                    (a file or `-`; the line's SKF_*_RESULT_JSON: prefix is
                    optional). A success envelope is recorded; an error
                    envelope, or --no-capstone and the like (a stage
                    skipped on purpose), records null. A line that does
                    not parse, is not a JSON object, or has no string
                    `status` or integer `exit_code` records null with halt
                    reason result-unreadable in its not_recorded row (an
                    empty line, or a file it cannot read or decode, is
                    still exit 2). --no-result <field> (repeatable) records
                    a sub-skill that printed no result line: null, with
                    halt reason no-result in its not_recorded row; it does
                    not go with that field's --<field> or --no-<field>.
                    Each field it writes also sets
                    campaign.stage_outcomes.<field>: `completed` with the
                    envelope's exit_code, `skipped` for --no-<field>, or
                    `failed` with the not_recorded row's halt_reason and
                    exit_code. A recorded verification also sets
                    capstone.verified.
  recover           Copy a .bak that validates over the primary (step-resume).
  archive           Move the state, its .bak and the brief, each one that
                    exists, into archive/<campaign name>-<UTC stamp>/ beside
                    the state (SKILL.md's overwrite), so step-01's init can
                    start a new campaign. The name comes from the state, else
                    the .bak, else "campaign"; an existing folder is refused.
  log               Append one typed entry to the decision log: decision (an
                    operator's choice), auto (a default a headless run took)
                    or event (a failure, a recovery, a skip), stamped from
                    the clock. The log is append-only.
  halt-payload      Print the payload of a HARD HALT's error envelope for
                    skf-emit-result-envelope.py emit-halt (read-only): the
                    phase, the halt reason, the halt message read from stdin,
                    the completed and failed counts of the state (0 when it
                    cannot be read) and the decision log beside it (null
                    before the campaign workspace exists).
  resume            Compute the resume point (read-only): the stage and step
                    file to chain to, from the state and --from.

Resume rule. Without --from: an active skill resumes its own stage (Tier A
at stage 4, the skill loop; Tier B at stage 5, the batch, whose script
batches the active skills an interrupted batch left), with no +1; otherwise
the next stage is current_stage + 1, because current_stage is the highest
completed stage, capped at 10 (the report stage reruns, never a stage 11).
The campaign is complete when current_stage is 10 and no skill is pending or
active. With --from: an unknown skill is an error; a pending or active skill
resumes its tier's stage; a completed, failed or skipped one needs the
operator's choice (needs_choice), unless --next takes the next pending or
active skill after it in the execution order (complete when there is none).

CLI:
  uv run campaign-state.py init --state-file <p> --targets-file <p|-> --name <name> \\
      --hard <value> --soft-target <N> --soft-fallback <N> [--brief-file <p>] \\
      [--directive-path <p>] [--architecture-doc-path <p>] \\
      [--brief-out <p> [--brief-template <p>] [--notes <text>]]
  uv run campaign-state.py set-stage --state-file <p> --stage <N>
  uv run campaign-state.py set-skill --state-file <p> --skill <name> [--skill <name> ...] \\
      [--status <status>] [--quality-score <N>] [--skill-path <p>] [--brief-path <p>] \\
      [--export exported|failed [--export-halt-reason <r>] [--export-exit-code <N>]] [--stage <N>]
  uv run campaign-state.py apply-plan --state-file <p> [--stage <N>]
  uv run campaign-state.py apply-pins --state-file <p> --results-file <p|-> [--stage <N>]
  uv run campaign-state.py apply-provenance --state-file <p> --results-file <p|-> [--stage <N>]
  uv run campaign-state.py apply-batch --state-file <p> --map-file <p> \\
      (--start | --results-file <p|-> | --no-results) [--stage <N>]
  uv run campaign-state.py append-workarounds --state-file <p> --skill <name> \\
      --entry <text> [--entry <text> ...] [--stage <N>]
  uv run campaign-state.py set-campaign --state-file <p> [--architecture-doc-path <p>] \\
      [--capstone <p|-> | --no-capstone] [--verification <p|-> | --no-verification] \\
      [--refinement <p|-> | --no-refinement] \\
      [--no-result capstone|verification|refinement ...] [--stage <N>]
  uv run campaign-state.py recover --state-file <p>
  uv run campaign-state.py archive --state-file <p> --brief-file <p>
  uv run campaign-state.py log --log-file <p> --type <decision|auto|event> --text <entry>
  uv run campaign-state.py halt-payload --state-file <p> --phase <slug> --halt-reason <class> < <message>
  uv run campaign-state.py resume --state-file <p> [--from <skill>] [--next]

The backup is always <state-file>.bak.

Output (one JSON object on stdout):
  writes:   {"op", "state_file", "backup_file", "backup_rotated",
             "last_updated", "current_stage", "changed": [...]} plus the
             operation's own keys (init: "quality_gate", "brief_file", null
             without --brief-out; apply-batch: "activated", "skipped",
             "completed", "failed"; set-campaign: "recorded", and
             "not_recorded", one {"field", "status", "halt_reason",
             "exit_code"} row for each field it set to null)
  recover:  {"op", "state_file", "backup_file", "recovered", "last_updated",
             "current_stage"}
  archive:  {"op", "archive_dir", "moved": [...]}
  log:      {"op", "log_file", "entry"}
  halt-payload:
            {"phase", "reason", "halt_reason", "skills_completed",
             "skills_failed", "decision_log"}
  resume:   {"complete", "stage", "step_file", "reason", "skill",
             "needs_choice", "from_status", "active_other"}
Errors: {"error", "code", "errors": [...]} on stderr.

Exit codes (each is the campaign's HALT code for the same class):
  0  written, recovered, archived, logged or computed
  2  invalid input: a missing or unreadable input file, an unknown skill,
     output from another script that holds an error, a gate the gate script
     rejects, a state that init would overwrite, a brief template that is
     no YAML mapping, export flags or set-campaign flags that do not go
     together, or an archive folder that exists
  3  invalid state: the state is missing, malformed or fails the schema, or
     the change would make it fail (nothing written)
  4  apply-plan: a plan the stages cannot follow (circular-deps)
  5  apply-pins: an invalid pin (invalid-pin)
  6  apply-provenance: an inaccessible repository (inaccessible-repo)
  9  recover: the backup is missing or fails validation too
"""

from __future__ import annotations

import argparse
import contextlib
import copy
import importlib.util
import io
import json
import os
import re
import secrets
import sys
import time
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Callable

import yaml

HERE = Path(__file__).resolve().parent
VALIDATE_SCRIPT = HERE / "campaign-validate-state.py"
DEPS_SCRIPT = HERE / "campaign-deps.py"
GATE_SCRIPT = HERE / "campaign-quality-gate.py"
BRIEF_TEMPLATE = HERE.parent / "templates" / "campaign-brief-template.yaml"
STATUSES = ("pending", "active", "completed", "failed", "skipped")
SETTLED = ("completed", "failed", "skipped")
OPEN = ("pending", "active")
LOG_TYPES = ("decision", "auto", "event")
EXPORT_STATUSES = ("exported", "failed")
FINAL_STAGE = 10
# Stage N runs step-(N+1); SKILL.md's Stages table.
STEP_FILES = {
    0: "step-01-setup.md",
    1: "step-02-strategy.md",
    2: "step-03-pins.md",
    3: "step-04-provenance.md",
    4: "step-05-skill-loop.md",
    5: "step-06-batch.md",
    6: "step-07-capstone.md",
    7: "step-08-verify.md",
    8: "step-09-refine.md",
    9: "step-10-export.md",
    10: "step-11-maintenance.md",
}
TIER_STAGE = {"A": 4, "B": 5}
DECISION_LOG = "_campaign-decision-log.md"
EXIT_INPUT = 2
EXIT_STATE = 3
EXIT_CIRCULAR = 4
EXIT_PIN = 5
EXIT_REPO = 6
EXIT_NO_BACKUP = 9
_IS_WINDOWS = os.name == "nt"
_REPLACE_WAIT_SECONDS = 5.0
_REPLACE_POLL_SECONDS = 0.05
_modules: dict[str, Any] = {}


class StateError(Exception):
    """A failure reported as {"error", "code", "errors"} on stderr with its exit code."""

    def __init__(self, exit_code: int, code: str, message: str, errors: list | None = None) -> None:
        super().__init__(message)
        self.exit_code = exit_code
        self.code = code
        self.errors = errors or []


def _module(path: Path) -> Any:
    """A sibling script, loaded once."""
    key = path.name
    if key not in _modules:
        spec = importlib.util.spec_from_file_location(path.stem.replace("-", "_"), path)
        module = importlib.util.module_from_spec(spec)
        spec.loader.exec_module(module)
        _modules[key] = module
    return _modules[key]


def now() -> str:
    """The clock's time in UTC, as ISO-8601 with its offset."""
    return datetime.now(timezone.utc).isoformat(timespec="seconds")


# --------------------------------------------------------------------------
# Reading, validating and writing the state
# --------------------------------------------------------------------------


def _schema() -> dict:
    validator = _module(VALIDATE_SCRIPT)
    return json.loads(validator.DEFAULT_SCHEMA_PATH.read_text(encoding="utf-8"))


def validation_errors(state: Any) -> list[dict]:
    """campaign-validate-state.py's errors for a state already loaded."""
    if not isinstance(state, dict):
        return [{"field": "(root)", "message": "State root must be a mapping"}]
    return _module(VALIDATE_SCRIPT).validate_state(state, _schema())["errors"]


def read_state(path: Path) -> tuple[dict, bytes]:
    """The state and its bytes; StateError (exit 3) unless it validates."""
    if not path.is_file():
        raise StateError(EXIT_STATE, "state-missing", f"State not found at `{path.as_posix()}`.")
    try:
        raw = path.read_bytes()
        text = raw.decode("utf-8")
    except (OSError, UnicodeDecodeError) as exc:
        raise StateError(EXIT_STATE, "state-malformed", f"State unreadable: {exc}") from exc
    state, problem = _module(VALIDATE_SCRIPT)._load_yaml_text(text)
    if problem is not None:
        raise StateError(EXIT_STATE, "state-malformed", problem)
    errors = validation_errors(state)
    if errors:
        raise StateError(EXIT_STATE, "state-invalid", "The state fails validation: nothing was written.", errors)
    return state, raw


def dump_state(state: dict) -> bytes:
    text = yaml.safe_dump(state, sort_keys=False, default_flow_style=False, allow_unicode=True)
    return text.encode("utf-8")


def _replace(source: Path, target: Path) -> None:
    """os.replace, retried on Windows while a reader holds either file open."""
    deadline = time.monotonic() + _REPLACE_WAIT_SECONDS
    while True:
        try:
            os.replace(source, target)
            return
        except PermissionError:
            if not _IS_WINDOWS or time.monotonic() >= deadline:
                raise
            time.sleep(_REPLACE_POLL_SECONDS)


def write_atomic(path: Path, data: bytes) -> None:
    """Write a temporary file beside path, then rename it over path.

    A reader holding the file open on Windows makes the rename fail with
    PermissionError for a moment, so the rename is retried there.
    """
    path.parent.mkdir(parents=True, exist_ok=True)
    tmp = path.with_name(f"{path.name}.{os.getpid()}-{secrets.token_hex(4)}.skf-tmp")
    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
    fd = os.open(tmp, flags, 0o644)
    try:
        with open(fd, "wb") as fh:
            fh.write(data)
            fh.flush()
            os.fsync(fh.fileno())
        _replace(tmp, path)
    except BaseException:
        with contextlib.suppress(OSError):
            tmp.unlink()
        raise


def backup_path(state_file: Path) -> Path:
    return state_file.with_name(state_file.name + ".bak")


def _set_stage(state: dict, stage: int | None, changed: list[str]) -> None:
    if stage is None:
        return
    state["campaign"]["current_stage"] = stage
    changed.append(f"campaign.current_stage={stage}")


def mutate(
    state_file: str,
    op: str,
    change: Callable[[dict, str, list[str]], dict | None],
    stage: int | None = None,
) -> dict:
    """Read, validate, change, stamp, validate again, rotate .bak, write.

    `change(state, stamp, changed)` edits the state in place, appends a short
    description of each change to `changed`, and may return extra output
    keys. It raises StateError to refuse the operation before anything is
    written.
    """
    path = Path(state_file)
    state, raw = read_state(path)
    new_state = copy.deepcopy(state)
    stamp = now()
    changed: list[str] = []
    extra = change(new_state, stamp, changed) or {}
    _set_stage(new_state, stage, changed)
    new_state["campaign"]["last_updated"] = stamp
    errors = validation_errors(new_state)
    if errors:
        raise StateError(EXIT_STATE, "state-change-invalid",
                         "The change would make the state invalid: nothing was written.", errors)
    bak = backup_path(path)
    write_atomic(bak, raw)
    write_atomic(path, dump_state(new_state))
    return {
        "op": op,
        "state_file": path.as_posix(),
        "backup_file": bak.as_posix(),
        "backup_rotated": True,
        "last_updated": stamp,
        "current_stage": new_state["campaign"]["current_stage"],
        "changed": changed,
        **extra,
    }


# --------------------------------------------------------------------------
# Input files
# --------------------------------------------------------------------------


def read_text(source: str, label: str) -> str:
    """A file's text, or stdin's for `-`, in the encoding it was written in.

    A shell redirect on Windows PowerShell writes UTF-16 with a byte-order
    mark, so one is honoured.
    """
    try:
        raw = sys.stdin.buffer.read() if source == "-" else Path(source).read_bytes()
    except OSError as exc:
        raise StateError(EXIT_INPUT, "input-unreadable", f"{label} unreadable: {exc}") from exc
    try:
        if raw.startswith((b"\xff\xfe", b"\xfe\xff")):
            return raw.decode("utf-16")
        return raw.decode("utf-8-sig")
    except UnicodeDecodeError as exc:
        raise StateError(EXIT_INPUT, "input-unreadable", f"{label} is not UTF-8 text: {exc}") from exc


def read_json(source: str, label: str) -> dict:
    text = read_text(source, label)
    if not text.strip():
        raise StateError(EXIT_INPUT, "input-unreadable", f"{label} is empty")
    try:
        data = json.loads(text)
    except json.JSONDecodeError as exc:
        raise StateError(EXIT_INPUT, "input-unreadable", f"{label} is not JSON: {exc}") from exc
    if not isinstance(data, dict):
        raise StateError(EXIT_INPUT, "input-unreadable", f"{label} is not a JSON object")
    return data


def read_envelope(source: str, label: str) -> dict | None:
    """A sub-skill's result envelope: the last SKF_*_RESULT_JSON line, or bare JSON.

    None when that payload does not parse or is not a JSON object, which
    set-campaign records as result-unreadable. json.loads raises ValueError
    on a payload it cannot parse (JSONDecodeError is one, an integer of more
    than 4,300 digits another) and RecursionError on nesting too deep for
    it; both read as a payload that does not parse. An empty payload, or
    input it cannot read or decode, is still exit 2.
    """
    text = read_text(source, label)
    lines = [line for line in text.splitlines() if "_RESULT_JSON:" in line and "SKF_" in line]
    payload = lines[-1].split("_RESULT_JSON:", 1)[1].strip() if lines else text.strip()
    if not payload:
        raise StateError(EXIT_INPUT, "input-unreadable", f"{label} holds no result envelope")
    try:
        data = json.loads(payload)
    except (ValueError, RecursionError):
        return None
    return data if isinstance(data, dict) else None


def _skills_by_name(state: dict) -> dict[str, dict]:
    return {s["name"]: s for s in state.get("skills", [])}


def _known(state: dict, names: list[str]) -> dict[str, dict]:
    skills = _skills_by_name(state)
    unknown = [n for n in names if n not in skills]
    if unknown:
        raise StateError(EXIT_INPUT, "unknown-skill",
                         f"Unknown skill(s): {', '.join(unknown)}. Known skills: {', '.join(skills)}.")
    return skills


# --------------------------------------------------------------------------
# Operations
# --------------------------------------------------------------------------


def _brief_template(source: str) -> tuple[str, dict]:
    """The template's leading comment block and its mapping (empty for an empty template)."""
    text = read_text(source, "Brief template")
    try:
        mapping = yaml.safe_load(text)
    except yaml.YAMLError as exc:
        raise StateError(EXIT_INPUT, "brief-template-invalid", f"Brief template is not YAML: {exc}") from exc
    if mapping is None:
        mapping = {}
    if not isinstance(mapping, dict):
        raise StateError(EXIT_INPUT, "brief-template-invalid", "Brief template is not a YAML mapping")
    header = []
    for line in text.splitlines():
        if not line.startswith("#"):
            break
        header.append(line)
    return "".join(f"{line}\n" for line in header), mapping


def render_brief(template: tuple[str, dict], fields: dict) -> bytes:
    """campaign-brief.yaml: the template's header, then its mapping with `fields` laid over it."""
    header, mapping = template
    brief = {**copy.deepcopy(mapping), **fields}
    body = yaml.safe_dump(brief, sort_keys=False, default_flow_style=False, allow_unicode=True)
    return ((header + "\n" if header else "") + body).encode("utf-8")


def op_init(args: argparse.Namespace) -> dict:
    path = Path(args.state_file)
    bak = backup_path(path)
    for existing in (path, bak):
        if existing.exists():
            raise StateError(EXIT_INPUT, "state-exists",
                             f"`{existing.as_posix()}` already exists: archive the campaign before starting a new one.")
    if not args.brief_out and (args.brief_template or args.notes is not None):
        raise StateError(EXIT_INPUT, "input-invalid", "--brief-template and --notes go with --brief-out")
    parsed = read_json(args.targets_file, "Targets")
    if parsed.get("errors"):
        raise StateError(EXIT_INPUT, "targets-invalid", "The targets hold errors: fix them and parse again.",
                         list(parsed["errors"]))
    targets = parsed.get("targets")
    if not isinstance(targets, list) or not targets:
        raise StateError(EXIT_INPUT, "no-targets", "A campaign needs at least one target.")

    gate_module = _module(GATE_SCRIPT)
    try:
        brief = gate_module._load_brief(args.brief_file) if args.brief_file else None
        gate = gate_module.check(args.hard, args.soft_target, args.soft_fallback, brief)
    except gate_module.GateError as exc:
        raise StateError(EXIT_INPUT, exc.code, str(exc), list(exc.extra.get("errors", []))) from exc

    template = _brief_template(args.brief_template or str(BRIEF_TEMPLATE)) if args.brief_out else None
    stamp = now()
    campaign: dict[str, Any] = {
        "name": args.name,
        "started_at": stamp,
        "last_updated": stamp,
        "current_stage": 0,
    }
    if args.directive_path:
        campaign["directive_path"] = args.directive_path
    if args.architecture_doc_path:
        campaign["architecture_doc_path"] = args.architecture_doc_path
    campaign["quality_gate"] = {key: gate[key] for key in ("hard", "soft_target", "soft_fallback")}

    skills = []
    for target in targets:
        if not isinstance(target, dict) or not target.get("name"):
            raise StateError(EXIT_INPUT, "targets-invalid", "A target has no name: parse the targets again.")
        skills.append({
            "name": target["name"],
            "status": "pending",
            "depends_on": list(target.get("depends_on") or []),
            "tier": target.get("tier") or "A",
            "pin": target.get("pin"),
            "brief_path": None,
            "skill_path": None,
            "quality_score": None,
            "workarounds_applied": [],
            "started_at": None,
            "completed_at": None,
            "commit_sha": None,
        })
    state = {
        "campaign": campaign,
        "skills": skills,
        "dependency_graph": {"execution_order": [], "circular_deps_detected": False},
    }
    errors = validation_errors(state)
    if errors:
        raise StateError(EXIT_STATE, "state-change-invalid",
                         "The new state would be invalid: nothing was written.", errors)
    brief_data = None
    if template is not None:
        notes = args.notes if args.notes is not None else (brief or {}).get("notes")
        brief_data = render_brief(template, {
            "campaign_name": args.name,
            "created_at": stamp,
            "targets": copy.deepcopy(targets),
            "quality_gate": dict(campaign["quality_gate"]),
            "architecture_doc_path": args.architecture_doc_path or "",
            "notes": notes if isinstance(notes, str) else "",
        })
    write_atomic(path, dump_state(state))
    changed = [f"skills={len(skills)}", "campaign.quality_gate"]
    brief_file = Path(args.brief_out) if brief_data is not None else None
    if brief_file is not None:
        write_atomic(brief_file, brief_data)
        changed.append("brief")
    return {
        "op": "init",
        "state_file": path.as_posix(),
        "backup_file": bak.as_posix(),
        "backup_rotated": False,
        "last_updated": stamp,
        "current_stage": 0,
        "changed": changed,
        "quality_gate": campaign["quality_gate"],
        "brief_file": brief_file.as_posix() if brief_file else None,
    }


def op_set_stage(args: argparse.Namespace) -> dict:
    return mutate(args.state_file, "set-stage", lambda state, stamp, changed: None, args.stage)


def _export_outcome(args: argparse.Namespace) -> dict | None:
    """The `export` record --export gives, or None without it."""
    detail = args.export_halt_reason is not None or args.export_exit_code is not None
    if args.export is None:
        if detail:
            raise StateError(EXIT_INPUT, "input-invalid", "--export-halt-reason and --export-exit-code go with --export")
        return None
    if args.export == "exported":
        if detail:
            raise StateError(EXIT_INPUT, "input-invalid",
                             "--export-halt-reason and --export-exit-code go with --export failed")
        return {"status": "exported", "halt_reason": None, "exit_code": 0}
    return {"status": "failed", "halt_reason": args.export_halt_reason or None, "exit_code": args.export_exit_code}


def op_set_skill(args: argparse.Namespace) -> dict:
    outcome = _export_outcome(args)

    def change(state: dict, stamp: str, changed: list[str]) -> None:
        skills = _known(state, args.skill)
        for name in args.skill:
            skill = skills[name]
            if args.status is not None:
                skill["status"] = args.status
                changed.append(f"{name}.status={args.status}")
                if args.status == "active" and not skill.get("started_at"):
                    skill["started_at"] = stamp
                    changed.append(f"{name}.started_at")
                elif args.status == "completed":
                    skill["completed_at"] = stamp
                    changed.append(f"{name}.completed_at")
                elif args.status == "pending":
                    skill["started_at"] = None
                    skill["completed_at"] = None
                    skill.pop("export", None)
            for field in ("quality_score", "skill_path", "brief_path"):
                value = getattr(args, field)
                if value is not None:
                    skill[field] = value
                    changed.append(f"{name}.{field}")
            if outcome is not None:
                skill["export"] = dict(outcome)
                changed.append(f"{name}.export={outcome['status']}")

    return mutate(args.state_file, "set-skill", change, args.stage)


def computed_plan(state_file: str) -> list[str]:
    """campaign-deps.py --compute's execution order for the state file.

    StateError (exit 4) when the graph cannot be followed: a cycle, a
    dangling depends_on name or a Tier A skill on a Tier B one.
    """
    out, err = io.StringIO(), io.StringIO()
    with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
        rc = _module(DEPS_SCRIPT).compute(state_file)
    if rc == 0:
        return json.loads(out.getvalue())["execution_order"]
    details = [line for line in (out.getvalue() + err.getvalue()).splitlines() if line.strip()]
    raise StateError(EXIT_CIRCULAR, "plan-unorderable",
                     "The dependency graph cannot be followed: campaign-deps.py --compute says why.", details)


def op_apply_plan(args: argparse.Namespace) -> dict:
    def change(state: dict, stamp: str, changed: list[str]) -> dict:
        order = computed_plan(args.state_file)
        state["dependency_graph"] = {"execution_order": order, "circular_deps_detected": False}
        changed.append("dependency_graph.execution_order")
        return {"execution_order": order}

    return mutate(args.state_file, "apply-plan", change, args.stage)


def _results(source: str, label: str) -> list[dict]:
    data = read_json(source, label)
    results = data.get("results")
    if not isinstance(results, list) or not all(isinstance(r, dict) for r in results):
        raise StateError(EXIT_INPUT, "input-unreadable", f"{label} holds no results[] list")
    return results


def op_apply_pins(args: argparse.Namespace) -> dict:
    results = _results(args.results_file, "Pin results")
    invalid = [r.get("name") for r in results if r.get("status") not in ("valid", "resolved")]
    if invalid:
        raise StateError(EXIT_PIN, "invalid-pin", f"Invalid pin(s): {', '.join(map(str, invalid))}: nothing was written.")

    def change(state: dict, stamp: str, changed: list[str]) -> None:
        skills = _known(state, [r.get("name") for r in results])
        for result in results:
            ref = result.get("resolved_ref")
            skill = skills[result["name"]]
            if ref and ref != skill.get("pin"):
                skill["pin"] = ref
                changed.append(f"{result['name']}.pin={ref}")

    return mutate(args.state_file, "apply-pins", change, args.stage)


def op_apply_provenance(args: argparse.Namespace) -> dict:
    results = _results(args.results_file, "Provenance results")
    inaccessible = [r.get("name") for r in results if r.get("status") != "accessible" or not r.get("commit_sha")]
    if inaccessible:
        raise StateError(EXIT_REPO, "inaccessible-repo",
                         f"Inaccessible repositories: {', '.join(map(str, inaccessible))}: nothing was written.")

    def change(state: dict, stamp: str, changed: list[str]) -> None:
        skills = _known(state, [r.get("name") for r in results])
        for result in results:
            skills[result["name"]]["commit_sha"] = result["commit_sha"]
            changed.append(f"{result['name']}.commit_sha")

    return mutate(args.state_file, "apply-provenance", change, args.stage)


def op_apply_batch(args: argparse.Namespace) -> dict:
    batch_map = read_json(args.map_file, "Batch map")
    lines = batch_map.get("lines")
    if not isinstance(lines, list):
        raise StateError(EXIT_INPUT, "input-unreadable", "Batch map holds no lines[] list")
    batched = [entry.get("skill") for entry in lines if isinstance(entry, dict)]
    skipped = [e for e in batch_map.get("skipped_by_directive") or [] if isinstance(e, dict)]
    rows: list[dict] = []
    if args.results_file:
        rows = _results(args.results_file, "Batch results")
        unmapped = [r.get("skill") for r in rows if r.get("skill") not in batched]
        if unmapped:
            raise StateError(EXIT_INPUT, "input-unreadable",
                             f"Batch results name skills the map does not: {', '.join(map(str, unmapped))}")

    def change(state: dict, stamp: str, changed: list[str]) -> dict:
        skills = _known(state, batched + [e.get("name") for e in skipped])
        out: dict[str, list] = {"activated": [], "skipped": [], "completed": [], "failed": []}
        if args.start:
            for entry in skipped:
                skills[entry["name"]]["status"] = "skipped"
                out["skipped"].append({"name": entry["name"], "reason": entry.get("reason")})
            for name in batched:
                skill = skills[name]
                skill["status"] = "active"
                if not skill.get("started_at"):
                    skill["started_at"] = stamp
                out["activated"].append(name)
        elif args.no_results:
            for name in batched:
                skills[name]["status"] = "failed"
                out["failed"].append({"skill": name, "error_code": "no-batch-result"})
        else:
            for row in rows:
                skill = skills[row["skill"]]
                if row.get("status") == "completed":
                    skill["status"] = "completed"
                    skill["completed_at"] = stamp
                    skill["quality_score"] = row.get("quality_score")
                    skill["skill_path"] = row.get("skill_path")
                    out["completed"].append(row["skill"])
                else:
                    skill["status"] = "failed"
                    out["failed"].append({"skill": row["skill"], "error_code": row.get("error_code")})
        for key, values in out.items():
            if values:
                changed.append(f"{key}={len(values)}")
        return out

    return mutate(args.state_file, "apply-batch", change, args.stage)


def op_append_workarounds(args: argparse.Namespace) -> dict:
    def change(state: dict, stamp: str, changed: list[str]) -> dict:
        skill = _known(state, [args.skill])[args.skill]
        held = skill.setdefault("workarounds_applied", [])
        added = []
        for entry in args.entry:
            if entry.strip() and entry not in held:
                held.append(entry)
                added.append(entry)
        changed.append(f"{args.skill}.workarounds_applied+{len(added)}")
        return {"added": added}

    return mutate(args.state_file, "append-workarounds", change, args.stage)


def _capstone(envelope: dict, stamp: str) -> dict | None:
    if envelope.get("status") != "success":
        return None
    return {
        "skill_path": envelope.get("skill_package"),
        "quality_score": envelope.get("quality_score"),
        "verified": None,
        "completed_at": stamp,
    }


def _verification(envelope: dict, stamp: str) -> dict | None:
    if envelope.get("status") != "success" or envelope.get("exit_code", 0) != 0:
        return None
    return {key: envelope.get(key) for key in
            ("report_path", "overall_verdict", "coverage_percentage", "recommendation_count")}


def _refinement(envelope: dict, stamp: str) -> dict | None:
    if envelope.get("status") != "success" or envelope.get("exit_code", 0) != 0:
        return None
    return {key: envelope.get(key) for key in ("refined_path", "gap_count", "issue_count", "improvement_count")}


SUMMARIES = (("capstone", _capstone), ("verification", _verification), ("refinement", _refinement))


def _readable(envelope: dict | None) -> bool:
    """An envelope set-campaign can read: an object with a string `status` and an integer `exit_code`.

    The SS, VS and RA envelope schemas all require both, so a line missing
    either is recorded result-unreadable, as step-10 records an Export line.
    """
    if not isinstance(envelope, dict):
        return False
    exit_code = envelope.get("exit_code")
    return isinstance(envelope.get("status"), str) and isinstance(exit_code, int) and not isinstance(exit_code, bool)


def _failed_outcome(row: dict) -> dict:
    """The stage outcome of a field set-campaign did not record, from its not_recorded row."""
    reason = row["halt_reason"]
    return {"outcome": "failed", "halt_reason": reason if isinstance(reason, str) else None,
            "exit_code": row["exit_code"]}


def op_set_campaign(args: argparse.Namespace) -> dict:
    no_result = set(args.no_result or ())
    for field, _build in SUMMARIES:
        if field in no_result and (getattr(args, field) is not None or getattr(args, f"no_{field}")):
            raise StateError(EXIT_INPUT, "input-invalid",
                             f"--no-result {field} does not go with --{field} or --no-{field}")
    envelopes = {}
    for field, _build in SUMMARIES:
        source = getattr(args, field)
        if source is not None:
            envelopes[field] = read_envelope(source, f"The {field} envelope")

    def change(state: dict, stamp: str, changed: list[str]) -> dict:
        campaign = state["campaign"]
        recorded, not_recorded = [], []
        if args.architecture_doc_path:
            campaign["architecture_doc_path"] = args.architecture_doc_path
            changed.append("campaign.architecture_doc_path")
        for field, build in SUMMARIES:
            # Each branch decides the stage outcome; a failed one takes its row's halt_reason and exit_code.
            if field in envelopes and not _readable(envelopes[field]):
                value = None
                row = {"field": field, "status": None, "halt_reason": "result-unreadable", "exit_code": None}
                not_recorded.append(row)
                outcome = _failed_outcome(row)
            elif field in envelopes:
                envelope = envelopes[field]
                value = build(envelope, stamp)
                if value is None:
                    row = {"field": field, "status": envelope.get("status"),
                           "halt_reason": envelope.get("halt_reason"), "exit_code": envelope.get("exit_code")}
                    not_recorded.append(row)
                    outcome = _failed_outcome(row)
                else:
                    recorded.append(field)
                    outcome = {"outcome": "completed", "halt_reason": None, "exit_code": envelope["exit_code"]}
            elif getattr(args, f"no_{field}"):
                value = None
                not_recorded.append({"field": field, "status": None, "halt_reason": None, "exit_code": None})
                outcome = {"outcome": "skipped", "halt_reason": None, "exit_code": None}
            elif field in no_result:
                value = None
                row = {"field": field, "status": None, "halt_reason": "no-result", "exit_code": None}
                not_recorded.append(row)
                outcome = _failed_outcome(row)
            else:
                continue
            campaign[field] = value
            campaign.setdefault("stage_outcomes", {})[field] = outcome
            changed.append(f"campaign.{field}")
            if field == "verification" and isinstance(campaign.get("capstone"), dict):
                verdict = (value or {}).get("overall_verdict")
                campaign["capstone"]["verified"] = None if value is None else verdict == "FEASIBLE"
                changed.append("campaign.capstone.verified")
        return {"recorded": recorded, "not_recorded": not_recorded}

    return mutate(args.state_file, "set-campaign", change, args.stage)


def op_recover(args: argparse.Namespace) -> dict:
    path = Path(args.state_file)
    bak = backup_path(path)
    try:
        state, raw = read_state(bak)
    except StateError as exc:
        raise StateError(EXIT_NO_BACKUP, "corrupt-state",
                         f"No usable backup at `{bak.as_posix()}`: {exc}", exc.errors) from exc
    write_atomic(path, raw)
    return {
        "op": "recover",
        "state_file": path.as_posix(),
        "backup_file": bak.as_posix(),
        "recovered": True,
        "last_updated": state["campaign"]["last_updated"],
        "current_stage": state["campaign"]["current_stage"],
    }


def _loose_state(path: Path) -> dict | None:
    """The state as YAML, unvalidated: what an archive or a halt can still read."""
    if not path.is_file():
        return None
    try:
        data = yaml.safe_load(path.read_text(encoding="utf-8"))
    except (OSError, UnicodeDecodeError, yaml.YAMLError):
        return None
    return data if isinstance(data, dict) else None


def _campaign_name(path: Path) -> str | None:
    campaign = (_loose_state(path) or {}).get("campaign")
    name = campaign.get("name") if isinstance(campaign, dict) else None
    return name if isinstance(name, str) and name.strip() else None


def op_archive(args: argparse.Namespace) -> dict:
    path = Path(args.state_file)
    bak = backup_path(path)
    sources = [p for p in (path, bak, Path(args.brief_file)) if p.is_file()]
    if not sources:
        raise StateError(EXIT_INPUT, "nothing-to-archive", "No campaign state, backup or brief to archive.")
    name = _campaign_name(path) or _campaign_name(bak) or "campaign"
    slug = re.sub(r"[^A-Za-z0-9._-]+", "-", name).strip("-.") or "campaign"
    # No colon in a folder name: Windows refuses one.
    stamp = now().replace("+00:00", "Z").replace(":", "")
    folder = path.parent / "archive" / f"{slug}-{stamp}"
    if folder.exists():
        raise StateError(EXIT_INPUT, "archive-exists", f"`{folder.as_posix()}` already exists: nothing was moved.")
    folder.mkdir(parents=True)
    moved = []
    for source in sources:
        target = folder / source.name
        _replace(source, target)
        moved.append(target.as_posix())
    return {"op": "archive", "archive_dir": folder.as_posix(), "moved": moved}


def op_log(args: argparse.Namespace) -> dict:
    text = " ".join(args.text.split())
    if not text:
        raise StateError(EXIT_INPUT, "input-unreadable", "The log entry is empty")
    entry = f"- {now()} ({args.type}) {text}"
    path = Path(args.log_file)
    path.parent.mkdir(parents=True, exist_ok=True)
    with open(path, "a", encoding="utf-8", newline="\n") as fh:
        fh.write(entry + "\n")
        fh.flush()
        os.fsync(fh.fileno())
    return {"op": "log", "log_file": path.as_posix(), "entry": entry}


def op_halt_payload(args: argparse.Namespace) -> dict:
    path = Path(args.state_file)
    reason = " ".join(read_text("-", "The halt message").split())
    if not reason:
        raise StateError(EXIT_INPUT, "input-unreadable", "The halt message is empty")
    skills = (_loose_state(path) or {}).get("skills")
    skills = [s for s in skills if isinstance(s, dict)] if isinstance(skills, list) else []
    return {
        "phase": args.phase,
        "reason": reason,
        "halt_reason": args.halt_reason,
        "skills_completed": sum(1 for s in skills if s.get("status") == "completed"),
        "skills_failed": sum(1 for s in skills if s.get("status") == "failed"),
        "decision_log": (path.parent / DECISION_LOG).as_posix() if path.parent.is_dir() else None,
    }


def resume_point(state: dict, from_skill: str | None = None, take_next: bool = False) -> dict:
    """Where a resumed campaign continues (see the module docstring)."""
    campaign = state["campaign"]
    skills = state.get("skills", [])
    by_name = _skills_by_name(state)
    result: dict[str, Any] = {
        "complete": False, "stage": None, "step_file": None, "reason": None, "skill": None,
        "needs_choice": False, "from_status": None, "active_other": None,
    }

    def route(stage: int, reason: str, skill: str | None = None) -> dict:
        result.update(stage=stage, step_file=STEP_FILES[stage], reason=reason, skill=skill)
        return result

    if from_skill is not None:
        if from_skill not in by_name:
            raise StateError(EXIT_INPUT, "unknown-skill",
                             f"Unknown skill '{from_skill}'. Known skills: {', '.join(by_name)}.")
        target = by_name[from_skill]
        result["from_status"] = target["status"]
        active = [s["name"] for s in skills if s["status"] == "active" and s["name"] != from_skill]
        result["active_other"] = active[0] if active else None
        if target["status"] in OPEN:
            return route(TIER_STAGE[target["tier"]], "from-skill", from_skill)
        if not take_next:
            result.update(needs_choice=True, skill=from_skill)
            return result
        order = state["dependency_graph"].get("execution_order") or [s["name"] for s in skills]
        after = order[order.index(from_skill) + 1:] if from_skill in order else []
        for name in after:
            skill = by_name.get(name)
            if skill is not None and skill["status"] in OPEN:
                return route(TIER_STAGE[skill["tier"]], "from-next", name)
        result.update(complete=True, reason="nothing-after-from")
        return result

    active = [s for s in skills if s["status"] == "active"]
    if active:
        first = min(active, key=lambda s: TIER_STAGE[s["tier"]])
        return route(TIER_STAGE[first["tier"]], "active-skill", first["name"])
    current = campaign["current_stage"]
    if current >= FINAL_STAGE and not any(s["status"] in OPEN for s in skills):
        result.update(complete=True, reason="complete")
        return result
    if current >= FINAL_STAGE:
        return route(FINAL_STAGE, "terminal-cap")
    return route(current + 1, "next-stage")


def op_resume(args: argparse.Namespace) -> dict:
    state, _raw = read_state(Path(args.state_file))
    if args.next and args.from_skill is None:
        raise StateError(EXIT_INPUT, "input-invalid", "--next needs --from")
    return resume_point(state, args.from_skill, args.next)


# --------------------------------------------------------------------------
# CLI
# --------------------------------------------------------------------------


def _stage(value: str) -> int:
    stage = int(value)
    if not 0 <= stage <= FINAL_STAGE:
        raise argparse.ArgumentTypeError(f"a stage is 0 to {FINAL_STAGE}")
    return stage


def _score(value: str) -> int | float:
    number = float(value)
    return int(number) if number.is_integer() else number


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="campaign-state",
        description="Write _campaign-state.yaml (validated before and after, .bak rotated from a valid "
        "primary, timestamps from the clock, atomic) and compute the resume point.",
    )
    sub = parser.add_subparsers(dest="op", required=True)

    def command(name: str, help_text: str, stage: str | None = "optional") -> argparse.ArgumentParser:
        p = sub.add_parser(name, help=help_text)
        if name != "log":
            p.add_argument("--state-file", required=True, help="path to _campaign-state.yaml")
        if stage is not None:
            p.add_argument("--stage", type=_stage, required=stage == "required",
                           help="write campaign.current_stage (0 to 10) in the same write")
        return p

    p = command("init", "create the state from parsed targets (step-01)", stage=None)
    p.add_argument("--targets-file", required=True, help="campaign-parse-manifest.py output, or - for stdin")
    p.add_argument("--name", required=True, help="campaign name")
    p.add_argument("--hard", required=True, help="quality_gate_hard")
    p.add_argument("--soft-target", required=True, help="quality_gate_soft_target")
    p.add_argument("--soft-fallback", required=True, help="quality_gate_soft_fallback")
    p.add_argument("--brief-file", help="campaign brief whose quality_gate wins over the values above")
    p.add_argument("--directive-path", help="campaign directive file")
    p.add_argument("--architecture-doc-path", help="architecture document for verify and refine")
    p.add_argument("--brief-out", help="also write campaign-brief.yaml here, from the same targets")
    p.add_argument("--brief-template", help="the brief template (default: templates/campaign-brief-template.yaml)")
    p.add_argument("--notes", help="the brief's notes (default: the --brief-file's notes, else empty)")

    command("set-stage", "write campaign.current_stage", stage="required")

    p = command("set-skill", "set fields of one or more skills")
    p.add_argument("--skill", action="append", required=True, help="skill name (repeat for several)")
    p.add_argument("--status", choices=STATUSES)
    p.add_argument("--quality-score", type=_score)
    p.add_argument("--skill-path")
    p.add_argument("--brief-path")
    p.add_argument("--export", choices=EXPORT_STATUSES, help="the skill's skf-export-skill outcome (step-10)")
    p.add_argument("--export-halt-reason", help="with --export failed: the export envelope's halt_reason")
    p.add_argument("--export-exit-code", type=int, help="with --export failed: skf-export-skill's exit code")

    command("apply-plan", "write the execution order campaign-deps.py computes (step-02)")

    p = command("apply-pins", "write resolved pins (step-03)")
    p.add_argument("--results-file", required=True, help="campaign-validate-pins.py output, or -")

    p = command("apply-provenance", "write commit SHAs (step-04)")
    p.add_argument("--results-file", required=True, help="campaign-provenance.py output, or -")

    p = command("apply-batch", "record the Tier B batch (step-06)")
    p.add_argument("--map-file", required=True, help="the line-to-skill map campaign-render-batch.py wrote")
    mode = p.add_mutually_exclusive_group(required=True)
    mode.add_argument("--start", action="store_true", help="mark skipped and batched skills before the batch")
    mode.add_argument("--results-file", help="campaign-render-batch.py --record output, or -")
    mode.add_argument("--no-results", action="store_true", help="fail every batched skill")

    p = command("append-workarounds", "append entries to a skill's workarounds_applied")
    p.add_argument("--skill", required=True)
    p.add_argument("--entry", action="append", required=True, help="one entry (repeat for several)")

    p = command("set-campaign", "write campaign-level fields")
    p.add_argument("--architecture-doc-path")
    for field, _build in SUMMARIES:
        group = p.add_mutually_exclusive_group()
        group.add_argument(f"--{field}", help=f"the {field} sub-skill's result envelope line, a file or -")
        group.add_argument(f"--no-{field}", action="store_true", help=f"record campaign.{field} as null")
    p.add_argument("--no-result", action="append", choices=[f for f, _ in SUMMARIES], metavar="FIELD",
                   help="record the field as null with halt reason no-result: its sub-skill printed no "
                        "result line (repeat for several; not with that field's --FIELD or --no-FIELD)")

    command("recover", "copy a valid .bak over the primary", stage=None)

    p = command("archive", "move the state, its .bak and the brief into archive/ (overwrite)", stage=None)
    p.add_argument("--brief-file", required=True, help="path to campaign-brief.yaml")

    p = command("log", "append a typed entry to the decision log", stage=None)
    p.add_argument("--log-file", required=True, help="path to _campaign-decision-log.md")
    p.add_argument("--type", required=True, choices=LOG_TYPES)
    p.add_argument("--text", required=True)

    p = command("halt-payload", "print a HARD HALT's emit-halt payload; the message on stdin", stage=None)
    p.add_argument("--phase", required=True, help="the kebab slug of the step that halts")
    p.add_argument("--halt-reason", required=True, help="the Exit Codes meaning, such as circular-deps")

    p = command("resume", "compute the resume point (read-only)", stage=None)
    p.add_argument("--from", dest="from_skill", help="resume at this skill")
    p.add_argument("--next", action="store_true", help="with --from at a finished skill: take the next open one")
    return parser


OPERATIONS = {
    "init": op_init,
    "set-stage": op_set_stage,
    "set-skill": op_set_skill,
    "apply-plan": op_apply_plan,
    "apply-pins": op_apply_pins,
    "apply-provenance": op_apply_provenance,
    "apply-batch": op_apply_batch,
    "append-workarounds": op_append_workarounds,
    "set-campaign": op_set_campaign,
    "recover": op_recover,
    "archive": op_archive,
    "log": op_log,
    "halt-payload": op_halt_payload,
    "resume": op_resume,
}


def main(argv: list[str] | None = None) -> int:
    parser = build_parser()
    args = parser.parse_args(argv)
    try:
        result = OPERATIONS[args.op](args)
    except StateError as exc:
        sys.stderr.write(json.dumps({"error": str(exc), "code": exc.code, "errors": exc.errors}) + "\n")
        return exc.exit_code
    except OSError as exc:
        sys.stderr.write(json.dumps({"error": f"Write failed: {exc}", "code": "write-failed", "errors": []}) + "\n")
        return EXIT_INPUT
    sys.stdout.write(json.dumps(result, separators=(",", ":")) + "\n")
    return 0


def _force_utf8(*streams) -> None:
    """Reconfigure the streams to UTF-8, keeping each one's error handler.

    A Windows console pipes them as cp1252, which cannot print every
    character a path or a log entry may hold.
    """
    for stream in streams:
        if hasattr(stream, "reconfigure"):
            errors = getattr(stream, "errors", None)
            if errors is None:
                stream.reconfigure(encoding="utf-8")
            else:
                stream.reconfigure(encoding="utf-8", errors=errors)


if __name__ == "__main__":
    _force_utf8(sys.stdout, sys.stderr)
    sys.exit(main())
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall