specjam 0.0.1__tar.gz

specjam-0.0.1/MANIFEST.in

@@ -0,0 +1,3 @@
+global-exclude *.py[cod]
+global-exclude __pycache__
+prune src/specjam/**/__pycache__

specjam-0.0.1/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: specjam
+Version: 0.0.1
+Summary: A harness-neutral agentic engineering workspace built around flow graphs and RWSA skills.
+Author: Fernando Costa
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://github.com/nandoligeiro/SpecJam
+Project-URL: Repository, https://github.com/nandoligeiro/SpecJam
+Project-URL: Issues, https://github.com/nandoligeiro/SpecJam/issues
+Keywords: agents,engineering-workflow,flow-graphs,rws,cli
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# SpecJam
+
+SpecJam is an installable, harness-neutral agentic engineering workspace. It turns a natural-language request into a durable, auditable flow instead of allowing an agent to jump directly from ambiguity to implementation.
+
+The first release combines three ideas:
+
+- **Flow graphs**: declarative stages, artifact gates, conditional routing, bounded reviewers, and a pure routing function.
+- **RWSA skills**: Routing, Workflow, Semantics, and Attachments as an executable contract for reusable agent capabilities.
+- **A local workspace**: a standard-library-only CLI that installs, verifies, inspects, updates, and scaffolds the method in any repository.
+
+## Quick start
+
+Run SpecJam directly from PyPI with `uvx`, or install it persistently with `uv tool`:
+
+```bash
+uvx specjam install
+uv tool install specjam
+specjam install
+```
+
+To pin this release explicitly:
+
+```bash
+uvx --from 'specjam==0.0.1' specjam --help
+```
+
+For a source checkout, `uv run` keeps the package isolated and reproducible:
+
+```bash
+uv run specjam install
+uv run specjam verify
+uv run specjam inspect
+uv run specjam classify "Add a new payment capability"
+uv run specjam flow scaffold --flow delivery --slug payment-capability
+```
+
+The installer creates `.specjam/` and a minimal root `AGENTS.md` bridge. Existing bridge files are preserved unless `--force` is supplied. Runtime state is ignored; the lockfile and managed definitions remain inspectable.
+
+## Architecture
+
+```text
+  natural language -----> discovery graph
+       |
+       +-----------------> delivery graph
+       |
+       +-----------------> postmortem graph
+
+graph + state --> pure route --> decision --> append-only trail
+                                      |
+                                      +--> bounded read-only reviewers
+                                      |
+                                      +--> one synthesis writer
+```
+
+The route function never writes files, invokes tools, or calls a model. Persistence belongs to the trail adapter. This split makes the highest-risk policy easy to test.
+
+## First-class flows
+
+SpecJam keeps each flow explicit and data-driven:
+
+- **Discovery** turns uncertainty into a problem statement, evidence, options, and a decision.
+- **Delivery** runs SDD: `SPEC → DESIGN? → BUILD → VALIDATE`.
+- **Postmortem** turns an incident record into root cause, actions, and follow-up.
+
+The daily engineering loop is a supporting L0–L3 classification mechanism, not a fourth flow graph.
+
+The three graphs are `graphs/discovery-graph.json`, `graphs/delivery-graph.json`, and `graphs/postmortem-graph.json`; organizations can add or replace graphs without changing the routing engine.
+
+## RWSA contract
+
+The skill representation follows the routing-aware decomposition described in [Workflow-to-Skill: Skill Creation via Routing-Workflow-Semantics-Attachments Decomposition](https://arxiv.org/abs/2606.06893):
+
+```text
+Skill = Routing + (Workflow + Semantics + Attachments)
+```
+
+`src/specjam/rws.py` validates this contract without requiring a YAML or AI dependency. The bundled authoring skills render the contract into the portable `SKILL.md` format described by [Agent Skills](https://agentskills.io/specification).
+
+## Development
+
+```bash
+uv run --no-sync python -m unittest discover -s tests -v
+uv run specjam graph validate src/specjam/payload/workspace/graphs/delivery-graph.json
+uv build --no-sources
+```
+
+The release workflow builds both wheel and source distribution on a `v*` tag and publishes them through PyPI Trusted Publishing. Configure the `pypi` GitHub environment and the matching PyPI trusted publisher before pushing a release tag.
+
+```bash
+uv version 0.0.1
+uv build --no-sources
+uv publish
+```
+
+The project intentionally keeps the engine dependency-free. Packaging helpers may use the Python standard library only; third-party model, agent, tracker, and cloud integrations are extension points.
+
+## Status
+
+This is the initial public foundation: graph engine, RWSA contract, reviewers, classification, installer, archive packaging, core skills, and test coverage. Organization-specific domain packs and tracker adapters stay outside the core as required by the PRD.

specjam-0.0.1/README.md

@@ -0,0 +1,99 @@
+# SpecJam
+
+SpecJam is an installable, harness-neutral agentic engineering workspace. It turns a natural-language request into a durable, auditable flow instead of allowing an agent to jump directly from ambiguity to implementation.
+
+The first release combines three ideas:
+
+- **Flow graphs**: declarative stages, artifact gates, conditional routing, bounded reviewers, and a pure routing function.
+- **RWSA skills**: Routing, Workflow, Semantics, and Attachments as an executable contract for reusable agent capabilities.
+- **A local workspace**: a standard-library-only CLI that installs, verifies, inspects, updates, and scaffolds the method in any repository.
+
+## Quick start
+
+Run SpecJam directly from PyPI with `uvx`, or install it persistently with `uv tool`:
+
+```bash
+uvx specjam install
+uv tool install specjam
+specjam install
+```
+
+To pin this release explicitly:
+
+```bash
+uvx --from 'specjam==0.0.1' specjam --help
+```
+
+For a source checkout, `uv run` keeps the package isolated and reproducible:
+
+```bash
+uv run specjam install
+uv run specjam verify
+uv run specjam inspect
+uv run specjam classify "Add a new payment capability"
+uv run specjam flow scaffold --flow delivery --slug payment-capability
+```
+
+The installer creates `.specjam/` and a minimal root `AGENTS.md` bridge. Existing bridge files are preserved unless `--force` is supplied. Runtime state is ignored; the lockfile and managed definitions remain inspectable.
+
+## Architecture
+
+```text
+  natural language -----> discovery graph
+       |
+       +-----------------> delivery graph
+       |
+       +-----------------> postmortem graph
+
+graph + state --> pure route --> decision --> append-only trail
+                                      |
+                                      +--> bounded read-only reviewers
+                                      |
+                                      +--> one synthesis writer
+```
+
+The route function never writes files, invokes tools, or calls a model. Persistence belongs to the trail adapter. This split makes the highest-risk policy easy to test.
+
+## First-class flows
+
+SpecJam keeps each flow explicit and data-driven:
+
+- **Discovery** turns uncertainty into a problem statement, evidence, options, and a decision.
+- **Delivery** runs SDD: `SPEC → DESIGN? → BUILD → VALIDATE`.
+- **Postmortem** turns an incident record into root cause, actions, and follow-up.
+
+The daily engineering loop is a supporting L0–L3 classification mechanism, not a fourth flow graph.
+
+The three graphs are `graphs/discovery-graph.json`, `graphs/delivery-graph.json`, and `graphs/postmortem-graph.json`; organizations can add or replace graphs without changing the routing engine.
+
+## RWSA contract
+
+The skill representation follows the routing-aware decomposition described in [Workflow-to-Skill: Skill Creation via Routing-Workflow-Semantics-Attachments Decomposition](https://arxiv.org/abs/2606.06893):
+
+```text
+Skill = Routing + (Workflow + Semantics + Attachments)
+```
+
+`src/specjam/rws.py` validates this contract without requiring a YAML or AI dependency. The bundled authoring skills render the contract into the portable `SKILL.md` format described by [Agent Skills](https://agentskills.io/specification).
+
+## Development
+
+```bash
+uv run --no-sync python -m unittest discover -s tests -v
+uv run specjam graph validate src/specjam/payload/workspace/graphs/delivery-graph.json
+uv build --no-sources
+```
+
+The release workflow builds both wheel and source distribution on a `v*` tag and publishes them through PyPI Trusted Publishing. Configure the `pypi` GitHub environment and the matching PyPI trusted publisher before pushing a release tag.
+
+```bash
+uv version 0.0.1
+uv build --no-sources
+uv publish
+```
+
+The project intentionally keeps the engine dependency-free. Packaging helpers may use the Python standard library only; third-party model, agent, tracker, and cloud integrations are extension points.
+
+## Status
+
+This is the initial public foundation: graph engine, RWSA contract, reviewers, classification, installer, archive packaging, core skills, and test coverage. Organization-specific domain packs and tracker adapters stay outside the core as required by the PRD.

specjam-0.0.1/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "specjam"
+version = "0.0.1"
+description = "A harness-neutral agentic engineering workspace built around flow graphs and RWSA skills."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Fernando Costa" }]
+license = "LicenseRef-Proprietary"
+keywords = ["agents", "engineering-workflow", "flow-graphs", "rws", "cli"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/nandoligeiro/SpecJam"
+Repository = "https://github.com/nandoligeiro/SpecJam"
+Issues = "https://github.com/nandoligeiro/SpecJam/issues"
+
+[project.scripts]
+specjam = "specjam.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["specjam", "specjam.*"]
+exclude = ["specjam.payload.__pycache__", "specjam.payload.__pycache__.*"]
+
+[tool.setuptools.package-data]
+"specjam.payload" = [
+  "ignore-rules.txt",
+  "bridge/*.md",
+  "workspace/*.md",
+  "workspace/*.json",
+  "workspace/graphs/*.json",
+  "workspace/references/*.md",
+  "workspace/runtime/*.md",
+  "workspace/skills/*/*.md",
+  "workspace/skills/*/*.json",
+  "workspace/skills/*/references/*.md",
+]
+
+[tool.setuptools.exclude-package-data]
+"specjam.payload" = ["**/__pycache__/*", "**/*.py[cod]"]
+
+[tool.uv]
+package = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

specjam-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

specjam-0.0.1/src/specjam/__init__.py

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

specjam-0.0.1/src/specjam/__main__.py

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

specjam-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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())