specjam 0.0.1__py3-none-any.whl

specjam/__init__.py

@@ -0,0 +1,3 @@
+"""SpecJam's deterministic agentic engineering primitives."""
+
+__version__ = "0.0.1"

specjam/__main__.py

@@ -0,0 +1,6 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()
+

specjam/archive.py

@@ -0,0 +1,52 @@
+"""Safe validation and extraction for self-contained SpecJam archives."""
+
+from __future__ import annotations
+
+import stat
+import zipfile
+from pathlib import Path
+from re import match
+
+
+class UnsafeArchiveError(ValueError):
+    """Raised before extraction when an archive entry can escape its root."""
+
+
+def _validate_name(name: str) -> None:
+    normalized = name.replace("\\", "/")
+    if normalized.startswith("/") or ".." in Path(normalized).parts:
+        raise UnsafeArchiveError(f"unsafe archive path: {name}")
+    if Path(normalized).drive or match(r"^[A-Za-z]:", normalized) or normalized.startswith("//"):
+        raise UnsafeArchiveError(f"archive path has a drive prefix: {name}")
+
+
+def validate_archive(path: str | Path) -> None:
+    with zipfile.ZipFile(path) as archive:
+        for info in archive.infolist():
+            _validate_name(info.filename)
+            mode = (info.external_attr >> 16) & 0o170000
+            if mode == stat.S_IFLNK:
+                raise UnsafeArchiveError(f"symlink archive entry: {info.filename}")
+
+
+def extract_archive(path: str | Path, destination: str | Path) -> None:
+    """Validate every entry before writing any bytes."""
+
+    validate_archive(path)
+    root = Path(destination).resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(path) as archive:
+        for info in archive.infolist():
+            relative = Path(info.filename.replace("\\", "/"))
+            target = (root / relative).resolve()
+            try:
+                target.relative_to(root)
+            except ValueError as exc:
+                raise UnsafeArchiveError(f"archive entry escapes destination: {info.filename}") from exc
+            if info.is_dir():
+                target.mkdir(parents=True, exist_ok=True)
+                continue
+            target.parent.mkdir(parents=True, exist_ok=True)
+            with archive.open(info) as source, target.open("wb") as sink:
+                while chunk := source.read(1024 * 1024):
+                    sink.write(chunk)

specjam/classification.py

@@ -0,0 +1,30 @@
+"""Deterministic proportional effort classification."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Classification:
+    level: str
+    flow: str
+    reason: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"level": self.level, "flow": self.flow, "reason": self.reason}
+
+
+def classify_request(text: str, *, ambiguous: bool = False, critical: bool = False) -> Classification:
+    normalized = text.strip().lower()
+    if not normalized:
+        return Classification("L3", "discovery", "empty requests are ambiguous and require discovery")
+    lookup_words = ("what is", "how do i", "lookup", "look up", "explain", "compare", "quantos", "qual é")
+    if not ambiguous and not critical and (normalized.endswith("?") or any(word in normalized for word in lookup_words)):
+        return Classification("L0", "daily", "lookup or explanation; no implementation specification required")
+    small_words = ("rename", "typo", "readme", "format", "small", "minor", "documentation")
+    if not ambiguous and not critical and any(word in normalized for word in small_words):
+        return Classification("L1", "daily", "bounded local change with proportional ceremony")
+    if ambiguous or critical or any(word in normalized for word in ("security", "payment", "migration", "breaking", "production")):
+        return Classification("L3", "discovery", "ambiguous or critical work requires discovery before delivery")
+    return Classification("L2", "delivery", "feature-sized work requires specification and implementation gates")

specjam/cli.py

@@ -0,0 +1,124 @@
+"""Command-line interface for SpecJam."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .classification import classify_request
+from .graph_engine import load_graph, record_route
+from .installer import inspect_installation, install, scaffold_flow, update, verify
+from .model import RouteState
+from .rws import load_rwsa, validate_rwsa
+
+
+def _emit(value) -> None:
+    json.dump(value, sys.stdout, indent=2, sort_keys=True)
+    sys.stdout.write("\n")
+
+
+def _flags(values: list[str] | None) -> dict[str, bool]:
+    result: dict[str, bool] = {}
+    for value in values or []:
+        key, separator, raw = value.partition("=")
+        result[key] = raw.lower() not in {"0", "false", "no", "off"} if separator else True
+    return result
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="specjam", description="Deterministic agentic engineering workspace")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    install_parser = commands.add_parser("install", help="install the managed workspace")
+    install_parser.add_argument("--target", default=".")
+    install_parser.add_argument("--force", action="store_true")
+
+    verify_parser = commands.add_parser("verify", help="verify managed files and lockfile")
+    verify_parser.add_argument("--target", default=".")
+
+    update_parser = commands.add_parser("update", help="update unchanged managed files")
+    update_parser.add_argument("--target", default=".")
+    update_parser.add_argument("--remove-stale", action="store_true")
+
+    inspect_parser = commands.add_parser("inspect", help="inspect installation metadata")
+    inspect_parser.add_argument("--target", default=".")
+
+    classify_parser = commands.add_parser("classify", help="classify work into L0-L3")
+    classify_parser.add_argument("text", nargs="+")
+    classify_parser.add_argument("--ambiguous", action="store_true")
+    classify_parser.add_argument("--critical", action="store_true")
+
+    graph = commands.add_parser("graph", help="validate a graph")
+    graph_commands = graph.add_subparsers(dest="graph_command", required=True)
+    graph_validate = graph_commands.add_parser("validate")
+    graph_validate.add_argument("path")
+
+    route = commands.add_parser("route", help="evaluate one graph gate")
+    route.add_argument("--graph", required=True)
+    route.add_argument("--stage", required=True)
+    route.add_argument("--artifact", action="append", default=[])
+    route.add_argument("--flag", action="append", default=[])
+    route.add_argument("--trail")
+    route.add_argument("--run-id", default="local")
+
+    rws = commands.add_parser("rws", help="validate an RWSA contract")
+    rws_commands = rws.add_subparsers(dest="rws_command", required=True)
+    rws_validate = rws_commands.add_parser("validate")
+    rws_validate.add_argument("path")
+
+    flow = commands.add_parser("flow", help="scaffold durable flow artifacts")
+    flow_commands = flow.add_subparsers(dest="flow_command", required=True)
+    scaffold = flow_commands.add_parser("scaffold")
+    scaffold.add_argument("--target", default=".")
+    scaffold.add_argument("--flow", required=True, choices=("discovery", "delivery", "postmortem"))
+    scaffold.add_argument("--slug", required=True)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "install":
+        _emit(install(args.target, force=args.force).to_dict())
+        return 0
+    if args.command == "verify":
+        report = verify(args.target)
+        _emit(report.to_dict())
+        return 0 if not (report.missing or report.modified or report.stale) else 1
+    if args.command == "update":
+        _emit(update(args.target, remove_stale=args.remove_stale).to_dict())
+        return 0
+    if args.command == "inspect":
+        _emit(inspect_installation(args.target))
+        return 0
+    if args.command == "classify":
+        _emit(classify_request(" ".join(args.text), ambiguous=args.ambiguous, critical=args.critical).to_dict())
+        return 0
+    if args.command == "graph" and args.graph_command == "validate":
+        graph = load_graph(args.path)
+        _emit({"valid": True, "graph": graph.id, "nodes": sorted(graph.nodes)})
+        return 0
+    if args.command == "route":
+        graph = load_graph(args.graph)
+        state = RouteState(args.stage, frozenset(args.artifact), _flags(args.flag))
+        if args.trail:
+            decision = record_route(__import__("specjam.graph_engine", fromlist=["TrailStore"]).TrailStore(args.trail), args.run_id, graph, state)
+        else:
+            from .graph_engine import route
+            decision = route(graph, state)
+        _emit(decision.to_dict())
+        return 0 if decision.may_advance or not decision.blocked else 2
+    if args.command == "rws" and args.rws_command == "validate":
+        profile = load_rwsa(args.path)
+        _emit({"valid": True, "skill": profile.routing.name, "workflow_steps": len(profile.workflow)})
+        return 0
+    if args.command == "flow" and args.flow_command == "scaffold":
+        path = scaffold_flow(args.target, args.flow, args.slug)
+        _emit({"flow": args.flow, "path": str(path)})
+        return 0
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

specjam/graph_engine.py

@@ -0,0 +1,211 @@
+"""Pure graph routing and the side-effecting audit trail adapter."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+from .model import FlowGraph, GraphNode, RouteDecision, RouteState
+
+
+class GraphValidationError(ValueError):
+    """Raised when a graph cannot be evaluated safely."""
+
+
+def load_graph(path: str | Path) -> FlowGraph:
+    with Path(path).open(encoding="utf-8") as handle:
+        graph = FlowGraph.from_dict(json.load(handle))
+    validate_graph(graph)
+    return graph
+
+
+def validate_graph(graph: FlowGraph) -> None:
+    errors: list[str] = []
+    if not graph.id:
+        errors.append("graph id is required")
+    if not graph.nodes:
+        errors.append("graph must contain at least one node")
+    if graph.start_stage not in graph.nodes:
+        errors.append(f"unknown start_stage: {graph.start_stage}")
+    for terminal in graph.terminal_stages:
+        if terminal not in graph.nodes:
+            errors.append(f"unknown terminal stage: {terminal}")
+    for node_id, node in graph.nodes.items():
+        if node_id != node.id:
+            errors.append(f"node key {node_id!r} does not match node id {node.id!r}")
+        if not node.agent:
+            errors.append(f"node {node.id!r} is missing agent")
+        if len(set(node.reviewers)) != len(node.reviewers):
+            errors.append(f"node {node.id!r} declares duplicate reviewer roles")
+        if any(not subagent.read_only for subagent in node.subagents):
+            errors.append(f"node {node.id!r} declares a subagent without read_only=true")
+        if node.writer and node.writer in node.reviewers:
+            errors.append(f"node {node.id!r} cannot use a reviewer as its synthesis writer")
+        conditions: set[str | None] = set()
+        for edge in node.transitions:
+            if edge.to not in graph.nodes:
+                errors.append(f"node {node.id!r} targets unknown stage {edge.to!r}")
+            if edge.when in conditions:
+                errors.append(f"node {node.id!r} has duplicate transition condition {edge.when!r}")
+            conditions.add(edge.when)
+        if node.id in graph.terminal_stages and any(edge.to != node.id for edge in node.transitions):
+            errors.append(f"terminal node {node.id!r} may only transition to itself")
+        if node.id not in graph.terminal_stages and not node.transitions:
+            errors.append(f"non-terminal node {node.id!r} must have a transition")
+
+    if graph.start_stage in graph.nodes:
+        reachable = _reachable(graph, graph.start_stage)
+        errors.extend(f"unreachable node: {node_id!r}" for node_id in sorted(set(graph.nodes) - reachable))
+    if errors:
+        raise GraphValidationError("; ".join(errors))
+
+
+def _reachable(graph: FlowGraph, start: str) -> set[str]:
+    found: set[str] = set()
+    pending = [start]
+    while pending:
+        current = pending.pop()
+        if current in found or current not in graph.nodes:
+            continue
+        found.add(current)
+        pending.extend(edge.to for edge in graph.nodes[current].transitions)
+    return found
+
+
+def _matches(condition: str | None, flags: Mapping[str, bool]) -> bool:
+    if condition is None or condition in {"always", "true"}:
+        return True
+    if condition.startswith("!"):
+        return not bool(flags.get(condition[1:], False))
+    return bool(flags.get(condition, False))
+
+
+def route(graph: FlowGraph, state: RouteState) -> RouteDecision:
+    """Evaluate one gate without performing I/O or invoking an agent."""
+
+    validate_graph(graph)
+    try:
+        node = graph.nodes[state.stage]
+    except KeyError as exc:
+        raise GraphValidationError(f"unknown current stage: {state.stage}") from exc
+
+    missing = tuple(sorted(set(node.required_artifacts) - set(state.artifacts)))
+    if missing:
+        reason = node.blocking_reason or (
+            f"Cannot leave stage {node.id!r}; required artifacts are missing: {', '.join(missing)}."
+        )
+        return RouteDecision(
+            graph_id=graph.id,
+            stage=node.id,
+            next_stage=None,
+            next_agent=node.agent,
+            missing_artifacts=missing,
+            may_advance=False,
+            blocked=True,
+            blocking_reason=reason,
+            reviewers=node.reviewers,
+            writer=node.writer,
+            implementation_blocked=node.block_implementation,
+        )
+
+    if node.id in graph.terminal_stages:
+        return RouteDecision(graph.id, node.id, None, None, (), False, False, None, node.reviewers, node.writer, node.block_implementation)
+
+    next_stage = next((edge.to for edge in node.transitions if _matches(edge.when, state.flags)), None)
+    if next_stage is None:
+        return RouteDecision(
+            graph.id,
+            node.id,
+            None,
+            node.agent,
+            (),
+            False,
+            True,
+            f"No transition condition matched for stage {node.id!r}.",
+            node.reviewers,
+            node.writer,
+            node.block_implementation,
+        )
+    return RouteDecision(
+        graph_id=graph.id,
+        stage=node.id,
+        next_stage=next_stage,
+        next_agent=graph.nodes[next_stage].agent,
+        missing_artifacts=(),
+        may_advance=True,
+        blocked=False,
+        blocking_reason=None,
+        reviewers=node.reviewers,
+        writer=node.writer,
+        implementation_blocked=node.block_implementation,
+    )
+
+
+@dataclass(frozen=True)
+class TrailEntry:
+    run_id: str
+    graph_id: str
+    stage: str
+    decision: RouteDecision
+    artifacts: tuple[str, ...]
+    flags: Mapping[str, bool]
+    recorded_at: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "run_id": self.run_id,
+            "graph_id": self.graph_id,
+            "stage": self.stage,
+            "decision": self.decision.to_dict(),
+            "artifacts": list(self.artifacts),
+            "flags": dict(self.flags),
+            "recorded_at": self.recorded_at,
+        }
+
+
+class TrailStore:
+    """Append-only JSONL persistence kept separate from routing."""
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+
+    def append(self, entry: TrailEntry) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(entry.to_dict(), sort_keys=True) + "\n")
+
+    def read(self) -> list[dict[str, Any]]:
+        if not self.path.exists():
+            return []
+        with self.path.open(encoding="utf-8") as handle:
+            return [json.loads(line) for line in handle if line.strip()]
+
+
+def record_route(
+    store: TrailStore,
+    run_id: str,
+    graph: FlowGraph,
+    state: RouteState,
+    decision: RouteDecision | None = None,
+    *,
+    now: datetime | None = None,
+) -> RouteDecision:
+    """Evaluate and append a gate evaluation to the audit trail."""
+
+    selected = decision or route(graph, state)
+    instant = now or datetime.now(timezone.utc)
+    store.append(
+        TrailEntry(
+            run_id=run_id,
+            graph_id=graph.id,
+            stage=state.stage,
+            decision=selected,
+            artifacts=tuple(sorted(state.artifacts)),
+            flags=state.flags,
+            recorded_at=instant.isoformat(),
+        )
+    )
+    return selected