arcgentic 0.2.2a3__tar.gz

arcgentic-0.2.2a3/.gitignore

@@ -0,0 +1,38 @@
+# macOS
+.DS_Store
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Claude Code agent state (worktree metadata + per-session settings)
+.claude/
+
+# Logs
+*.log
+
+# Node (for tooling)
+node_modules/
+
+# Python (for tooling / tests)
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Dogfood state (gitignore by default; projects opt-in to committing it)
+.agentic-rounds/
+
+# Local-only references (huge, gitignored per arcgentic ref-first discipline)
+references/
+# But skill reference docs inside the plugin itself ARE tracked
+!skills/*/references/
+!skills/*/references/**

arcgentic-0.2.2a3/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: arcgentic
+Version: 0.2.2a3
+Summary: Agentic harness for rigorous round-driven development — Python CLI for the arcgentic Claude Code plugin
+Project-URL: Homepage, https://github.com/Arch1eSUN/Arcgentic
+Project-URL: Repository, https://github.com/Arch1eSUN/Arcgentic
+Author: Arc Studio
+License: MIT
+Keywords: agentic-harness,claude-code,ide-adapter,round-driven-development
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.13
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# arcgentic toolkit
+
+Python CLI + adapter layer for the `arcgentic` Claude Code plugin.
+
+This is the **toolkit surface** of the arcgentic hybrid monorepo (see
+[Spec Amendment 01](../docs/plans/2026-05-13-arcgentic-v0.2.0-spec-amendment-01-layout.md)
+for why). The plugin surface (`skills/`, `agents/`, `hooks/`, `.githooks/` at repo root)
+provides markdown contracts discoverable by Claude Code; this toolkit provides the
+Python implementation that markdown skills shell out to.
+
+## Install (dev)
+
+```bash
+cd toolkit
+pip install -e ".[dev]"
+arcgentic --help
+```
+
+## CLI commands
+
+```bash
+arcgentic plan-round-impl --round R1.0 --type substrate-touching --anchor <sha40>
+arcgentic execute-round-impl --round R1.0 --handoff docs/superpowers/plans/R1.0.md
+arcgentic audit-check docs/audits/R1.0.md --strict-extended
+arcgentic quality-gate-enforce --repo-root .
+arcgentic validate-handoff docs/superpowers/plans/R1.0.md
+arcgentic codify-lesson --audit-dir docs/audits
+arcgentic track-refs add references/example --owner-repo owner/repo --round R1 --usage-evidence '{"pattern_only": true}'
+arcgentic cross-session-handoff read
+```
+
+## Quality gates (run from `toolkit/`)
+
+```bash
+mypy --strict src/ tests/
+pytest --tb=no
+ruff check .
+```
+
+## Layout
+
+- `src/arcgentic/adapters/` — IDE adapter Protocol + implementations
+- `src/arcgentic/skills_impl/` — skill implementation backends
+- `src/arcgentic/audit_check.py` — mechanical audit fact checker
+- `src/arcgentic/source_rules.py` — Moirai-derived source-rule contract validators
+- `src/arcgentic/utils/pattern_detection.py` — repeated audit-pattern clustering for lessons
+- `src/arcgentic/cli.py` — command-line bridge for skills, gates, and validators
+- `tests/unit/`, `tests/integration/` — pytest suites

arcgentic-0.2.2a3/README.md

@@ -0,0 +1,48 @@
+# arcgentic toolkit
+
+Python CLI + adapter layer for the `arcgentic` Claude Code plugin.
+
+This is the **toolkit surface** of the arcgentic hybrid monorepo (see
+[Spec Amendment 01](../docs/plans/2026-05-13-arcgentic-v0.2.0-spec-amendment-01-layout.md)
+for why). The plugin surface (`skills/`, `agents/`, `hooks/`, `.githooks/` at repo root)
+provides markdown contracts discoverable by Claude Code; this toolkit provides the
+Python implementation that markdown skills shell out to.
+
+## Install (dev)
+
+```bash
+cd toolkit
+pip install -e ".[dev]"
+arcgentic --help
+```
+
+## CLI commands
+
+```bash
+arcgentic plan-round-impl --round R1.0 --type substrate-touching --anchor <sha40>
+arcgentic execute-round-impl --round R1.0 --handoff docs/superpowers/plans/R1.0.md
+arcgentic audit-check docs/audits/R1.0.md --strict-extended
+arcgentic quality-gate-enforce --repo-root .
+arcgentic validate-handoff docs/superpowers/plans/R1.0.md
+arcgentic codify-lesson --audit-dir docs/audits
+arcgentic track-refs add references/example --owner-repo owner/repo --round R1 --usage-evidence '{"pattern_only": true}'
+arcgentic cross-session-handoff read
+```
+
+## Quality gates (run from `toolkit/`)
+
+```bash
+mypy --strict src/ tests/
+pytest --tb=no
+ruff check .
+```
+
+## Layout
+
+- `src/arcgentic/adapters/` — IDE adapter Protocol + implementations
+- `src/arcgentic/skills_impl/` — skill implementation backends
+- `src/arcgentic/audit_check.py` — mechanical audit fact checker
+- `src/arcgentic/source_rules.py` — Moirai-derived source-rule contract validators
+- `src/arcgentic/utils/pattern_detection.py` — repeated audit-pattern clustering for lessons
+- `src/arcgentic/cli.py` — command-line bridge for skills, gates, and validators
+- `tests/unit/`, `tests/integration/` — pytest suites

arcgentic-0.2.2a3/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "arcgentic"
+version = "0.2.2-alpha.3"
+description = "Agentic harness for rigorous round-driven development — Python CLI for the arcgentic Claude Code plugin"
+readme = "README.md"
+requires-python = ">=3.13"
+license = { text = "MIT" }
+authors = [{ name = "Arc Studio" }]
+keywords = ["agentic-harness", "round-driven-development", "claude-code", "ide-adapter"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "pyyaml>=6.0",
+    "jsonschema>=4.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.14",
+    "pytest>=8.0",
+    "ruff>=0.15",
+]
+
+[project.scripts]
+arcgentic = "arcgentic.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Arch1eSUN/Arcgentic"
+Repository = "https://github.com/Arch1eSUN/Arcgentic"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/arcgentic"]
+
+# === Quality gates per spec § 17 ===
+
+[tool.mypy]
+strict = true
+python_version = "3.13"
+files = ["src/", "tests/"]
+exclude = ["build/", "dist/"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "--strict-markers"
+markers = [
+    "integration: slow integration tests (deselect with '-m \"not integration\"')",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+exclude = ["build/", "dist/"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W", "F",   # default
+    "I",             # isort
+    "UP",            # pyupgrade
+    "B",             # bugbear
+    "A",             # builtins shadowing
+    "N",             # pep8-naming
+]
+ignore = []

arcgentic-0.2.2a3/src/arcgentic/__init__.py

@@ -0,0 +1,5 @@
+"""arcgentic — agentic harness for rigorous round-driven development."""
+
+from __future__ import annotations
+
+__version__ = "0.2.2-alpha.3"

arcgentic-0.2.2a3/src/arcgentic/adapters/__init__.py

@@ -0,0 +1,77 @@
+"""IDE adapter auto-detection.
+
+`detect_adapter()` inspects environment variables, filesystem markers, and
+binary availability to select the appropriate adapter for the current host.
+Falls back to InlineAdapter if no LLM host can be confidently identified.
+
+Detection rules (each: env-var checks use Python truthiness — empty-string
+env-var values fall through, which is the intended behavior since empty-string
+markers are semantically equivalent to unset):
+  1. Claude Code  — CLAUDE_CODE_SESSION (non-empty) OR ~/.claude/skills dir exists (home-relative)
+  2. Cursor       — CURSOR_SESSION (non-empty) OR .cursor/rules dir exists (CWD-relative)
+  3. VSCode+Codex — VSCODE_PID (non-empty) AND `codex` binary on PATH
+  4. Codex CLI    — CODEX_SESSION (non-empty) OR `codex` binary on PATH
+  5. Inline       — fallback when no LLM host can be identified
+
+Public API:
+  detect_adapter() -> IDEAdapter
+  IDEAdapter (re-export from .base for convenience)
+  AgentDispatchResult (re-export from .base)
+
+Spec reference: docs/plans/2026-05-13-arcgentic-v0.2.0-spec.md § 3.6
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from shutil import which
+
+from .base import AgentDispatchResult, IDEAdapter
+
+__all__ = ["detect_adapter", "IDEAdapter", "AgentDispatchResult"]
+
+
+def detect_adapter() -> IDEAdapter:
+    """Return the IDEAdapter best matching the current runtime environment.
+
+    Falls back to InlineAdapter if no LLM host can be detected. Callers should
+    NOT assume the returned adapter can dispatch agents (InlineAdapter can't
+    actually dispatch — it's a degraded fallback for dry-run / headless use).
+    """
+    # 1. Claude Code
+    if os.environ.get("CLAUDE_CODE_SESSION") or _has_dir("~/.claude/skills"):
+        from .claude_code import ClaudeCodeAdapter
+        return ClaudeCodeAdapter()
+
+    # rule 2 — Cursor (.cursor/rules is project-local, CWD-relative;
+    # detect_adapter() picks up the marker only when called from project root)
+    if os.environ.get("CURSOR_SESSION") or _has_dir(".cursor/rules"):
+        from .cursor import CursorAdapter
+        return CursorAdapter()
+
+    # 3. VSCode + Codex (must have BOTH a VSCode env marker AND codex binary)
+    if os.environ.get("VSCODE_PID") and which("codex"):
+        from .vscode_codex import VSCodeCodexAdapter
+        return VSCodeCodexAdapter()
+
+    # 4. Codex CLI standalone (CODEX_SESSION env, OR codex binary without VSCode)
+    if os.environ.get("CODEX_SESSION") or which("codex"):
+        from .codex_cli import CodexCLIAdapter
+        return CodexCLIAdapter()
+
+    # 5. Fallback
+    from .inline import InlineAdapter
+    return InlineAdapter()
+
+
+def _has_dir(path: str) -> bool:
+    """Return True if `path` is a directory (after ~-expansion).
+
+    Paths starting with `~` are home-relative (expand to $HOME).
+    Other paths are interpreted relative to the current working directory.
+    Used by detect_adapter() for both home-scoped markers (e.g. ~/.claude/skills,
+    Claude Code installation) and project-scoped markers (e.g. .cursor/rules,
+    Cursor project rules).
+    """
+    return Path(path).expanduser().is_dir()

arcgentic-0.2.2a3/src/arcgentic/adapters/_local_env.py

@@ -0,0 +1,125 @@
+"""Shared local-environment helpers for IDEAdapter implementations.
+
+These functions implement filesystem / shell / git operations that are identical
+across all non-canonical IDE adapters (Cursor / VSCode-Codex / Codex CLI / Inline).
+The canonical ClaudeCodeAdapter inlines these directly; a future cleanup task may
+unify it with this module.
+
+These are module-level functions (NOT a class) because they have no state — each
+call is a fresh subprocess or filesystem op. Adapters call them as
+`_local_env.read_file(path)` etc.
+
+Spec reference: docs/plans/2026-05-13-arcgentic-v0.2.0-spec.md § 3.3–§ 3.5
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def read_file(path: str) -> str:
+    """Read a file and return its text content (utf-8)."""
+    return Path(path).read_text(encoding="utf-8")
+
+
+def write_file(path: str, content: str) -> None:
+    """Write `content` to `path` (utf-8); creates or overwrites."""
+    Path(path).write_text(content, encoding="utf-8")
+
+
+def edit_file(path: str, old: str, new: str) -> None:
+    """Replace exactly one occurrence of `old` with `new`.
+
+    Raises ValueError on zero or multi-match (identical contract to
+    ClaudeCodeAdapter.edit_file per spec § 3 IDEAdapter Protocol).
+    """
+    p = Path(path)
+    text = p.read_text(encoding="utf-8")
+    count = text.count(old)
+    if count == 0:
+        raise ValueError(f"edit_file: `old` not found in {path}")
+    if count > 1:
+        raise ValueError(f"edit_file: `old` appears {count} times in {path} (ambiguous)")
+    p.write_text(text.replace(old, new, 1), encoding="utf-8")
+
+
+def shell(command: str, timeout_seconds: int = 120) -> tuple[str, int]:
+    """Run a shell command; return (stdout, exit_code).
+
+    On TimeoutExpired returns ('', 124) — same POSIX timeout convention as
+    ClaudeCodeAdapter.shell.
+    """
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=timeout_seconds,
+            check=False,
+        )
+        return result.stdout, result.returncode
+    except subprocess.TimeoutExpired:
+        return "", 124
+
+
+def _run_git(args: list[str], timeout_seconds: int = 60) -> tuple[str, str, int]:
+    """Run `git <args>` via list-form subprocess (no shell=True).
+
+    Returns (stdout, stderr, exit_code). Used by git_diff_staged / git_commit
+    which need stderr for error diagnostics — shell() can't return stderr
+    without breaking the IDEAdapter Protocol's tuple[str, int] signature.
+
+    Underscore-prefix signals this is an internal helper; callers should use
+    git_diff_staged() and git_commit() (the public surface).
+    """
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            capture_output=True,
+            text=True,
+            timeout=timeout_seconds,
+            check=False,
+        )
+        return result.stdout, result.stderr, result.returncode
+    except subprocess.TimeoutExpired:
+        return "", f"git {args[0] if args else ''} timed out", 124
+
+
+def git_diff_staged() -> str:
+    """Return the output of `git diff --staged`.
+
+    Raises RuntimeError if git exits non-zero (e.g., not in a git repo).
+    """
+    stdout, stderr, code = _run_git(["diff", "--staged"])
+    if code != 0:
+        raise RuntimeError(f"git diff --staged failed (exit {code}): {stderr.strip()}")
+    return stdout
+
+
+def git_commit(message: str, files: list[str] | None = None) -> str:
+    """Stage `files` (if provided) then commit; return the new SHA.
+
+    If `files` is None, commits whatever is already in the index.
+    Does NOT use --no-verify / --no-gpg-sign / --amend per Protocol contract.
+    """
+    if files is not None:
+        for f in files:
+            _, stderr, code = _run_git(["add", "--", f])
+            if code != 0:
+                raise RuntimeError(f"git add {f} failed (exit {code}): {stderr.strip()}")
+
+    _, stderr, code = _run_git(["commit", "-m", message])
+    if code != 0:
+        raise RuntimeError(f"git commit failed (exit {code}): {stderr.strip()}")
+
+    stdout, stderr, code = _run_git(["rev-parse", "HEAD"])
+    if code != 0:
+        raise RuntimeError(f"git rev-parse HEAD failed (exit {code}): {stderr.strip()}")
+    return stdout.strip()
+
+
+def shquote(s: str) -> str:
+    """POSIX single-quote escape for safe shell=True interpolation."""
+    return "'" + s.replace("'", "'\\''") + "'"

arcgentic-0.2.2a3/src/arcgentic/adapters/base.py

@@ -0,0 +1,108 @@
+"""IDE Adapter Protocol — the abstraction surface arcgentic skills/CLI use to talk
+to whatever AI agent platform is hosting them (Claude Code / Cursor / VSCode-Codex /
+Codex CLI / inline fallback).
+
+Adding a new platform = implementing this Protocol; arcgentic skills/CLI then work
+unchanged.
+
+Anti-contamination invariant (spec § 1.5): adapter methods MUST NOT inject
+`tools=` or `tool_choice=` at the agent level. Those belong one layer down
+in the LLM-client layer.
+
+Spec reference: docs/plans/2026-05-13-arcgentic-v0.2.0-spec.md § 3.1
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class AgentDispatchResult:
+    """Result of dispatching a sub-agent through an IDE adapter.
+
+    `output`        : the agent's stdout / response text
+    `exit_code`     : 0 = success; non-zero = failure
+    `duration_ms`   : wall-clock ms from dispatch to result
+    `agent_type`    : the agent_name that was dispatched (echoed back for trace)
+    `error`         : optional error message (None on success)
+    """
+
+    output: str
+    exit_code: int
+    duration_ms: int
+    agent_type: str
+    error: str | None = None
+
+
+@runtime_checkable
+class IDEAdapter(Protocol):
+    """Adapter for an AI IDE/agent platform.
+
+    Each platform (claude-code / cursor / vscode-codex / codex-cli / inline)
+    implements this Protocol. arcgentic skills + CLI invoke platform-agnostic
+    methods; the adapter translates to platform-specific tool calls.
+
+    Anti-contamination invariant (spec § 1.5): adapter methods MUST NOT inject
+    `tools=` or `tool_choice=` at the agent level. Those belong one layer down
+    in the LLM-client layer.
+    """
+
+    platform_name: str  # "claude-code" / "cursor" / "vscode-codex" / "codex-cli" / "inline"
+
+    def dispatch_agent(
+        self,
+        agent_name: str,
+        prompt: str,
+        timeout_seconds: int = 600,
+        isolation: Literal["worktree"] | None = None,
+    ) -> AgentDispatchResult:
+        """Dispatch a sub-agent.
+
+        `agent_name` maps to a markdown file at agents/<name>.md.
+        `prompt` is the full self-contained brief; agent has zero session context.
+        Returns the agent's response wrapped in AgentDispatchResult.
+        """
+        ...
+
+    def invoke_skill(self, skill_name: str, args: str = "") -> str:
+        """Invoke an arcgentic skill in-process.
+
+        `skill_name` maps to a markdown file at skills/<name>/SKILL.md.
+        `args` is the optional argument string for the skill.
+        Returns the skill's textual output.
+        """
+        ...
+
+    def read_file(self, path: str) -> str: ...
+
+    def write_file(self, path: str, content: str) -> None: ...
+
+    def edit_file(self, path: str, old: str, new: str) -> None:
+        """Replace exactly one occurrence of `old` with `new` in file at `path`.
+
+        Match is exact-string (no regex). Implementations MUST raise an error if
+        `old` is not found, or if `old` appears more than once (ambiguous match).
+        For multi-occurrence replacement, callers should invoke `edit_file` multiple
+        times with disambiguating context, or use a higher-level batch API.
+        """
+        ...
+
+    def shell(self, command: str, timeout_seconds: int = 120) -> tuple[str, int]:
+        """Run a shell command; return (output, exit_code)."""
+        ...
+
+    def git_diff_staged(self) -> str: ...
+
+    def git_commit(self, message: str, files: list[str] | None = None) -> str:
+        """Commit staged changes; return the commit SHA.
+
+        If `files` is provided (non-None), stage those files first via `git add <file>...`
+        then commit. If `files` is None, commit whatever is currently in the index without
+        staging anything (caller has already staged).
+
+        Implementations must NOT use `--no-verify`, `--no-gpg-sign`, or `--amend` unless
+        the adapter explicitly documents otherwise.
+        """
+        ...