sia-package 0.2.0__py3-none-any.whl

sia/__init__.py

@@ -0,0 +1,3 @@
+"""SIA's host-neutral orchestration runtime."""
+
+__version__ = "0.2.0"

sia/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

sia/adapters.py

@@ -0,0 +1,136 @@
+"""Opt-in host adapter templates.
+
+Adapters only expose SIA's shared state packet. They intentionally contain no
+host-specific copy of the workflow and never modify a project's root agent
+instructions.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+MARKER = "<!-- managed-by-sia-adapter-v1 -->"
+
+ADAPTERS: dict[str, tuple[Path, str]] = {
+    "claude": (
+        Path(".claude/skills/sia/SKILL.md"),
+        """---
+name: sia
+description: Continue the SIA workflow when the user explicitly invokes /sia.
+disable-model-invocation: true
+---
+
+# SIA
+
+<!-- managed-by-sia-adapter-v1 -->
+Run `sia next --json` in the project root. Read `sia/AGENT.md` when SIA is
+vendored, otherwise use the installed package's workflow contract. Follow the
+returned stage and mode. Keep every task's native subagent run ID in SIA with
+`sia task dispatch`; do not implement a dispatched task in the controller.
+Other skills and plugins remain available and keep ownership of their files.
+""",
+    ),
+    "codex": (
+        Path(".agents/skills/sia/SKILL.md"),
+        """---
+name: sia
+description: Continue the SIA workflow only when the user explicitly asks for SIA or invokes this skill.
+---
+
+# SIA
+
+<!-- managed-by-sia-adapter-v1 -->
+Run `sia next --json` in the project root and follow the returned stage and
+mode. Read `sia/AGENT.md` if it is vendored. Use Codex native subagents for
+independent implementation/review work and record their run IDs with
+`sia task dispatch`. Do not replace `AGENTS.md` or interfere with other skills.
+""",
+    ),
+    "kiro": (
+        Path(".kiro/steering/sia.md"),
+        """---
+inclusion: manual
+---
+
+# SIA
+
+<!-- managed-by-sia-adapter-v1 -->
+Run `sia next --json` in the project root and follow the returned stage and
+mode. Read `sia/AGENT.md` if it is vendored. In orchestrator mode, delegate
+prepared tasks to Kiro subagents and persist each returned run/agent ID with
+`sia task dispatch`. Keep BMAD, Superpowers, steering, skills, and hooks active;
+SIA owns only `.sia/` and explicitly generated SIA artifacts.
+""",
+    ),
+    "antigravity": (
+        Path(".agents/workflows/sia.md"),
+        """---
+description: Continue the persistent SIA workflow for this project
+---
+
+# SIA workflow
+
+<!-- managed-by-sia-adapter-v1 -->
+When the user invokes `/sia`, run `sia next --json` in the project root and
+follow the returned stage and mode. Read `sia/AGENT.md` if vendored. Use
+Antigravity's native agents for prepared implementation and review tasks, then
+record their run IDs with `sia task dispatch`. Do not alter other `.agents/`
+workflows, skills, or agent definitions.
+""",
+    ),
+}
+
+ALIASES = {"claude-code": "claude", "openai-codex": "codex", "google-antigravity": "antigravity"}
+
+
+def normalize_host(host: str) -> str:
+    value = ALIASES.get(host.lower(), host.lower())
+    if value not in ADAPTERS:
+        raise ValueError(f"unsupported host {host!r}; choose: {', '.join(ADAPTERS)}")
+    return value
+
+
+def _safe_target(root: Path, relative: Path, create_parent: bool) -> Path:
+    resolved_root = root.resolve()
+    candidate = root / relative
+    current = resolved_root
+    for part in relative.parent.parts:
+        current = current / part
+        if current.exists():
+            try:
+                current.resolve().relative_to(resolved_root)
+            except ValueError as exc:
+                raise PermissionError(f"adapter path escapes project through redirected directory: {current}") from exc
+    if create_parent:
+        candidate.parent.mkdir(parents=True, exist_ok=True)
+    if candidate.parent.exists():
+        try:
+            candidate.parent.resolve().relative_to(resolved_root)
+            candidate.resolve(strict=False).relative_to(resolved_root)
+        except ValueError as exc:
+            raise PermissionError(f"adapter target escapes project root: {candidate}") from exc
+    return candidate
+
+
+def install_adapter(root: Path, host: str) -> tuple[str, Path]:
+    host = normalize_host(host)
+    relative, content = ADAPTERS[host]
+    target = _safe_target(root, relative, create_parent=True)
+    if target.exists():
+        existing = target.read_text(encoding="utf-8")
+        if existing == content:
+            return "unchanged", target
+        raise FileExistsError(f"refusing to overwrite existing adapter: {target}")
+    target.write_text(content, encoding="utf-8")
+    return "installed", target
+
+
+def remove_adapter(root: Path, host: str) -> tuple[str, Path]:
+    host = normalize_host(host)
+    relative, content = ADAPTERS[host]
+    target = _safe_target(root, relative, create_parent=False)
+    if not target.exists():
+        return "absent", target
+    if target.read_text(encoding="utf-8") != content:
+        raise PermissionError(f"refusing to remove modified or unmanaged file: {target}")
+    target.unlink()
+    return "removed", target

sia/cli.py

@@ -0,0 +1,166 @@
+"""Command-line entry point for SIA."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .adapters import ADAPTERS, install_adapter, remove_adapter
+from .core import MODES, Project, SiaError
+from .policy import render_policy
+
+
+def emit(value: Any, as_json: bool = False) -> None:
+    if as_json or isinstance(value, (dict, list)):
+        print(json.dumps(value, indent=2, sort_keys=True))
+    else:
+        text = str(value)
+        encoding = sys.stdout.encoding or "utf-8"
+        print(text.encode(encoding, errors="replace").decode(encoding))
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(prog="sia", description="Persistent, host-neutral SIA orchestration")
+    root.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    root.add_argument("--root", default=".", help="project root (default: current directory)")
+    root.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    commands = root.add_subparsers(dest="command", required=True)
+
+    init = commands.add_parser("init", help="initialize durable SIA state")
+    init.add_argument("--mode", choices=MODES, default="orchestrator")
+    init.add_argument("--force", action="store_true", help="reset workflow state but keep existing evidence files")
+
+    commands.add_parser("status", help="show persisted workflow position")
+    next_command = commands.add_parser("next", help="emit the next host-neutral action packet")
+    next_command.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help="emit machine-readable JSON")
+    commands.add_parser("guide", help="print the installed workflow contract")
+    commands.add_parser("doctor", help="diagnose package and project integration")
+
+    owner = commands.add_parser("owner", help="assign a workflow stage to SIA or another framework")
+    owner.add_argument("--stage", required=True)
+    owner.add_argument("--to", required=True, dest="stage_owner")
+
+    advance = commands.add_parser("advance", help="complete the current stage after validating evidence")
+    advance.add_argument("--evidence", action="append", default=[], help="project-local artifact path; repeatable")
+
+    record = commands.add_parser("record", help="record a PASS or DEVIATION proposal outcome")
+    record.add_argument("--outcome", required=True, choices=("pass", "deviation"))
+    _event_arguments(record, deviation=False)
+
+    capture = commands.add_parser("capture", help="capture a DEVIATION using the feedback interface")
+    _event_arguments(capture, deviation=True)
+
+    commands.add_parser("convergence", help="compute persisted deviation rates")
+
+    preflight = commands.add_parser("preflight", help="load applicable active rules before work")
+    preflight.add_argument("--scope", action="append", required=True, help="file or glob; repeatable")
+    preflight.add_argument("--acknowledge", action="append", default=[], help="approved medium/high rule ID")
+
+    rule = commands.add_parser("rule", help="manage provenance-bearing feedback rules").add_subparsers(dest="rule_command", required=True)
+    add_rule = rule.add_parser("add", help="add an approved active rule")
+    add_rule.add_argument("--text", required=True)
+    add_rule.add_argument("--scope", required=True)
+    add_rule.add_argument("--severity", required=True, choices=("low", "medium", "high"))
+    add_rule.add_argument("--error-class", required=True)
+    add_rule.add_argument("--source-event", required=True)
+    retire = rule.add_parser("retire", help="retire, but do not erase, a rule")
+    retire.add_argument("--id", required=True)
+    retire.add_argument("--reason", required=True)
+
+    adapter = commands.add_parser("adapter", help="manage explicit host launchers").add_subparsers(dest="adapter_command", required=True)
+    for action in ("install", "remove"):
+        item = adapter.add_parser(action)
+        item.add_argument("--host", required=True, choices=tuple(ADAPTERS))
+
+    task = commands.add_parser("task", help="record native subagent execution evidence").add_subparsers(dest="task_command", required=True)
+    prepare = task.add_parser("prepare")
+    prepare.add_argument("--task", required=True)
+    prepare.add_argument("--brief", required=True, type=Path)
+    prepare.add_argument("--files", action="append", required=True)
+    dispatch = task.add_parser("dispatch")
+    dispatch.add_argument("--task", required=True)
+    dispatch.add_argument("--host", required=True)
+    dispatch.add_argument("--agent-id", required=True)
+    dispatch.add_argument("--native-run-id", required=True)
+    finish = task.add_parser("finish")
+    finish.add_argument("--task", required=True)
+    finish.add_argument("--report", required=True, type=Path)
+    finish.add_argument("--review", required=True, type=Path)
+    finish.add_argument("--reviewer-agent-id", required=True)
+    finish.add_argument("--review-native-run-id", required=True)
+
+    integration = commands.add_parser("integration", help="record final combined validation and review")
+    integration.add_argument("--evidence", required=True, type=Path)
+    return root
+
+
+def _event_arguments(command: argparse.ArgumentParser, deviation: bool) -> None:
+    command.add_argument("--signal", required=True)
+    command.add_argument("--context", required=True)
+    command.add_argument("--severity", required=True, choices=("low", "medium", "high"))
+    command.add_argument("--error-class", required=deviation)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    project = Project(args.root)
+    try:
+        result: Any
+        if args.command == "init":
+            result = project.initialize(args.mode, args.force)
+        elif args.command == "status":
+            result = project.status()
+        elif args.command == "next":
+            result = project.next_packet()
+        elif args.command == "guide":
+            emit(render_policy(), False)
+            return 0
+        elif args.command == "doctor":
+            result = project.doctor()
+            emit(result, args.json)
+            return 0 if result["ok"] else 1
+        elif args.command == "advance":
+            result = project.advance(args.evidence)
+        elif args.command == "owner":
+            result = project.set_stage_owner(args.stage, args.stage_owner)
+        elif args.command in {"record", "capture"}:
+            outcome = args.outcome if args.command == "record" else "deviation"
+            result = project.record_event(outcome, args.signal, args.context, args.severity, args.error_class)
+        elif args.command == "convergence":
+            result = project.convergence()
+        elif args.command == "preflight":
+            result, clear = project.preflight(args.scope, set(args.acknowledge))
+            emit(result, args.json)
+            return 0 if clear else 2
+        elif args.command == "rule":
+            if args.rule_command == "add":
+                result = project.add_rule(args.text, args.scope, args.severity, args.error_class, args.source_event)
+            else:
+                result = project.retire_rule(args.id, args.reason)
+        elif args.command == "adapter":
+            action = install_adapter if args.adapter_command == "install" else remove_adapter
+            status, path = action(project.root, args.host)
+            result = {"status": status, "host": args.host, "path": str(path.relative_to(project.root))}
+        elif args.command == "task":
+            if args.task_command == "prepare":
+                result = project.prepare_task(args.task, args.brief, args.files)
+            elif args.task_command == "dispatch":
+                result = project.dispatch_task(args.task, args.host, args.agent_id, args.native_run_id)
+            else:
+                result = project.finish_task(args.task, args.report, args.review, args.reviewer_agent_id, args.review_native_run_id)
+        elif args.command == "integration":
+            result = project.record_integration(args.evidence)
+        else:  # pragma: no cover - argparse prevents this
+            raise SiaError(f"unknown command: {args.command}")
+        emit(result, args.json)
+        return 0
+    except (SiaError, FileExistsError, PermissionError, ValueError) as exc:
+        print(f"sia: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())