cih-agent 0.1.0__tar.gz

cih_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Huijo Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cih_agent-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: cih-agent
+Version: 0.1.0
+Summary: A hierarchical multi-agent harness that autonomously audits a codebase, finds high-value improvements, and applies them in TDD-gated iterations.
+Author-email: Huijo Kim <huijo.kim@voids.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ccomkhj/continuous-improvement-harness
+Project-URL: Repository, https://github.com/ccomkhj/continuous-improvement-harness
+Project-URL: Issues, https://github.com/ccomkhj/continuous-improvement-harness/issues
+Keywords: agents,tdd,code-improvement,claude,automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# Continuous Improvement Harness (CIH)
+
+A hierarchical multi-agent harness that autonomously **audits a target codebase, finds
+high-value improvements, and applies them in TDD-gated iterations** — runnable both as a
+headless Python runner and as an interactive Claude Code skill, over one shared on-disk JSON
+state format.
+
+The target repo is always a **separate parameter** from the harness itself. CIH never pushes,
+never stages files implicitly, and does all work in disposable per-team git worktrees.
+
+## How it works
+
+Each iteration, a **high-planner** audits the target and decomposes the work into
+non-overlapping **team charters**. Every charter runs in its own isolated worktree through a
+four-agent pipeline, gated by a mechanical pytest verifier and a skeptical reviewer. Passing
+teams are integrated one at a time through a **bounded merge queue** that re-runs the full suite
+before advancing the integration head. An **opportunity ledger** tracks what's been tried and
+drives convergence.
+
+```mermaid
+flowchart TB
+    subgraph scope["scoping (skill only, once)"]
+        QA["Q&A interview<br/>--depth low/med/high<br/>→ fills run.json"]
+    end
+
+    QA --> ORCH
+
+    subgraph loop["per iteration"]
+        ORCH["orchestrator<br/><i>pure control flow + state</i>"]
+        HP["high-planner<br/>audit → ledger → charters"]
+        ORCH --> HP
+
+        subgraph teams["parallel teams · one git worktree each"]
+            direction TB
+            T1["planner → plan-reviewer →<br/>executor → tdd_verifier (pytest) →<br/>execution-reviewer"]
+            T2["team-02 …"]
+            T3["team-NN …"]
+        end
+        HP --> T1 & T2 & T3
+
+        MQ["merge queue<br/>rebase → re-verify → fast-forward<br/><i>(bounded retries)</i>"]
+        T1 & T2 & T3 --> MQ
+        MQ --> DEC{"ledger dry?<br/>/ N reached?"}
+        DEC -->|no| ORCH
+    end
+
+    DEC -->|yes| DONE["stop · final report.html"]
+
+    LED[("opportunity<br/>ledger")]
+    HP <-.-> LED
+    MQ -.-> LED
+```
+
+**Termination** is either `fixed-N` (exactly N iterations) or `until-converged` (stop once the
+ledger has no open opportunity above the value threshold for `convergence_dry_streak`
+iterations). Both are hard-bounded by `--max-iterations` and a budget cap.
+
+## Run (headless)
+
+```bash
+python -m cih.runner --mode fixed-N --iterations 3 \
+  --target-repo /abs/path/to/target --state-dir /abs/path/to/state \
+  --focus tests --focus performance
+```
+
+`until-converged` runs until the ledger is dry, bounded by `--max-iterations`:
+
+```bash
+python -m cih.runner --mode until-converged \
+  --target-repo /abs/path/to/target --state-dir /abs/path/to/state \
+  --max-iterations 25
+```
+
+## Run (interactive)
+
+Invoke the `cih` skill in Claude Code (`.claude/skills/cih/SKILL.md`) with the target repo and
+state dir. The skill renders the same agent contracts and orchestration steps, delegating to the
+Agent/Task tools instead of `claude -p`.
+
+Before the loop starts, the skill runs a short **Q&A scoping interview** to fill `run.json`. A
+`--depth` flag caps how many questions it asks:
+
+| `--depth` | question budget |
+|-----------|-----------------|
+| `low`     | up to 3         |
+| `medium`  | up to 6 (default) |
+| `high`    | up to 10        |
+
+It asks one question at a time about *intent only* (`focus_areas`, `mode` + caps,
+`value_threshold`), stops early once it understands the goal, shows a summary for a single
+confirmation, then runs **fully autonomously** with no further interruptions. `--depth` itself
+is never written to `run.json`.
+
+## Visual report
+
+Generate a self-contained HTML view of a run's state:
+
+```bash
+python -m cih.report --state-dir /abs/path/to/state   # writes <state_dir>/report.html
+```
+
+Or pass `--report` to the runner to (re)write `report.html` after every iteration; open it in a
+browser — it auto-refreshes while the run is `in_progress` and stops once it's `done`/`failed`.
+The page is fully self-contained (inline CSS, no network) and read-only over the state directory.
+
+## Safety
+
+- The harness **never pushes** and **never uses `git add -A`** — staging is explicit-only and
+  the bypass is structurally unreachable, not merely discouraged.
+- `target_repo` and `state_dir` are absolute, distinct, and non-nested; state lives **outside**
+  the target repo, so agents can never stage harness artifacts.
+- All work happens in disposable per-team worktrees; the target's working tree is never dirtied.
+- Every git command is logged.
+
+## Tests
+
+```bash
+python -m pytest -q
+```
+
+> Design specs and implementation plans live locally under `docs/superpowers/` (untracked).

cih_agent-0.1.0/README.md

@@ -0,0 +1,121 @@
+# Continuous Improvement Harness (CIH)
+
+A hierarchical multi-agent harness that autonomously **audits a target codebase, finds
+high-value improvements, and applies them in TDD-gated iterations** — runnable both as a
+headless Python runner and as an interactive Claude Code skill, over one shared on-disk JSON
+state format.
+
+The target repo is always a **separate parameter** from the harness itself. CIH never pushes,
+never stages files implicitly, and does all work in disposable per-team git worktrees.
+
+## How it works
+
+Each iteration, a **high-planner** audits the target and decomposes the work into
+non-overlapping **team charters**. Every charter runs in its own isolated worktree through a
+four-agent pipeline, gated by a mechanical pytest verifier and a skeptical reviewer. Passing
+teams are integrated one at a time through a **bounded merge queue** that re-runs the full suite
+before advancing the integration head. An **opportunity ledger** tracks what's been tried and
+drives convergence.
+
+```mermaid
+flowchart TB
+    subgraph scope["scoping (skill only, once)"]
+        QA["Q&A interview<br/>--depth low/med/high<br/>→ fills run.json"]
+    end
+
+    QA --> ORCH
+
+    subgraph loop["per iteration"]
+        ORCH["orchestrator<br/><i>pure control flow + state</i>"]
+        HP["high-planner<br/>audit → ledger → charters"]
+        ORCH --> HP
+
+        subgraph teams["parallel teams · one git worktree each"]
+            direction TB
+            T1["planner → plan-reviewer →<br/>executor → tdd_verifier (pytest) →<br/>execution-reviewer"]
+            T2["team-02 …"]
+            T3["team-NN …"]
+        end
+        HP --> T1 & T2 & T3
+
+        MQ["merge queue<br/>rebase → re-verify → fast-forward<br/><i>(bounded retries)</i>"]
+        T1 & T2 & T3 --> MQ
+        MQ --> DEC{"ledger dry?<br/>/ N reached?"}
+        DEC -->|no| ORCH
+    end
+
+    DEC -->|yes| DONE["stop · final report.html"]
+
+    LED[("opportunity<br/>ledger")]
+    HP <-.-> LED
+    MQ -.-> LED
+```
+
+**Termination** is either `fixed-N` (exactly N iterations) or `until-converged` (stop once the
+ledger has no open opportunity above the value threshold for `convergence_dry_streak`
+iterations). Both are hard-bounded by `--max-iterations` and a budget cap.
+
+## Run (headless)
+
+```bash
+python -m cih.runner --mode fixed-N --iterations 3 \
+  --target-repo /abs/path/to/target --state-dir /abs/path/to/state \
+  --focus tests --focus performance
+```
+
+`until-converged` runs until the ledger is dry, bounded by `--max-iterations`:
+
+```bash
+python -m cih.runner --mode until-converged \
+  --target-repo /abs/path/to/target --state-dir /abs/path/to/state \
+  --max-iterations 25
+```
+
+## Run (interactive)
+
+Invoke the `cih` skill in Claude Code (`.claude/skills/cih/SKILL.md`) with the target repo and
+state dir. The skill renders the same agent contracts and orchestration steps, delegating to the
+Agent/Task tools instead of `claude -p`.
+
+Before the loop starts, the skill runs a short **Q&A scoping interview** to fill `run.json`. A
+`--depth` flag caps how many questions it asks:
+
+| `--depth` | question budget |
+|-----------|-----------------|
+| `low`     | up to 3         |
+| `medium`  | up to 6 (default) |
+| `high`    | up to 10        |
+
+It asks one question at a time about *intent only* (`focus_areas`, `mode` + caps,
+`value_threshold`), stops early once it understands the goal, shows a summary for a single
+confirmation, then runs **fully autonomously** with no further interruptions. `--depth` itself
+is never written to `run.json`.
+
+## Visual report
+
+Generate a self-contained HTML view of a run's state:
+
+```bash
+python -m cih.report --state-dir /abs/path/to/state   # writes <state_dir>/report.html
+```
+
+Or pass `--report` to the runner to (re)write `report.html` after every iteration; open it in a
+browser — it auto-refreshes while the run is `in_progress` and stops once it's `done`/`failed`.
+The page is fully self-contained (inline CSS, no network) and read-only over the state directory.
+
+## Safety
+
+- The harness **never pushes** and **never uses `git add -A`** — staging is explicit-only and
+  the bypass is structurally unreachable, not merely discouraged.
+- `target_repo` and `state_dir` are absolute, distinct, and non-nested; state lives **outside**
+  the target repo, so agents can never stage harness artifacts.
+- All work happens in disposable per-team worktrees; the target's working tree is never dirtied.
+- Every git command is logged.
+
+## Tests
+
+```bash
+python -m pytest -q
+```
+
+> Design specs and implementation plans live locally under `docs/superpowers/` (untracked).

cih_agent-0.1.0/cih/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

cih_agent-0.1.0/cih/agents.py

@@ -0,0 +1,57 @@
+# cih/agents.py
+import json
+import subprocess
+from typing import Protocol
+from cih.contracts import AgentContract
+
+class AgentRunner(Protocol):
+    def run(self, contract: AgentContract, input_data: dict) -> dict: ...
+
+class StubRunner:
+    """Test double: returns canned responses keyed by role."""
+    def __init__(self, responses: dict):
+        self.responses = responses
+        self.calls: list[dict] = []
+
+    def run(self, contract: AgentContract, input_data: dict) -> dict:
+        self.calls.append({"role": contract.role, "input": input_data})
+        if contract.role not in self.responses:
+            raise KeyError(f"no stub response for role {contract.role}")
+        return self.responses[contract.role]
+
+class ClaudeCliRunner:
+    """Headless adapter: drives `claude -p --append-system-prompt`.
+
+    Flags precede the prompt; output is expected as JSON on stdout.
+    """
+    def __init__(self, cwd: str, extra_args: list[str] | None = None):
+        self.cwd = cwd
+        self.extra_args = extra_args or []
+
+    def run(self, contract: AgentContract, input_data: dict) -> dict:
+        prompt = json.dumps(input_data)
+        cmd = ["claude", "-p", "--output-format", "json",
+               "--append-system-prompt", contract.role_prompt,
+               *self.extra_args, "--", prompt]
+        proc = subprocess.run(cmd, cwd=self.cwd, capture_output=True, text=True)
+        if proc.returncode != 0:
+            raise RuntimeError(f"claude failed for {contract.role}: {proc.stderr}")
+        try:
+            envelope = json.loads(proc.stdout)
+        except json.JSONDecodeError as e:
+            raise RuntimeError(f"{contract.role}: non-JSON stdout from claude -p: {proc.stdout[:500]!r}") from e
+        if envelope.get("is_error"):
+            raise RuntimeError(f"{contract.role}: claude reported error: {envelope.get('result')}")
+        result = envelope.get("result")
+        if isinstance(result, dict):
+            return result
+        try:
+            return json.loads(result)
+        except (TypeError, json.JSONDecodeError) as e:
+            from cih.contracts import OutputValidationError
+            raise OutputValidationError(f"{contract.role}: result was not JSON: {result!r}") from e
+
+def invoke(runner: AgentRunner, contract: AgentContract, input_data: dict) -> dict:
+    output = runner.run(contract, input_data)
+    contract.validate_output(output)
+    return output

cih_agent-0.1.0/cih/attempts.py

@@ -0,0 +1,61 @@
+from dataclasses import dataclass, asdict
+from enum import Enum
+from typing import Optional
+
+class AttemptKind(str, Enum):
+    PLAN = "plan_retry"
+    EXECUTION = "execution_retry"
+    INTEGRATION = "integration_retry"
+    FINAL_REJECT = "final_reject"
+
+class AttemptCapExceeded(Exception):
+    pass
+
+@dataclass
+class Attempt:
+    attempt_id: str
+    kind: str
+    base_sha: str
+    branch: str
+    worktree_path: str
+    feedback_input: str
+    parent_attempt_id: Optional[str] = None
+    is_current: bool = True
+
+class AttemptLog:
+    def __init__(self, team_id: str, cap: int):
+        self.team_id = team_id
+        self.cap = cap
+        self._attempts: list[Attempt] = []
+
+    def start(self, kind: AttemptKind, base_sha: str, branch: str,
+              worktree_path: str, feedback: str,
+              parent: Optional[str] = None) -> Attempt:
+        if len(self._attempts) >= self.cap:
+            raise AttemptCapExceeded(
+                f"{self.team_id}: attempt cap {self.cap} reached")
+        for a in self._attempts:
+            a.is_current = False
+        att = Attempt(
+            attempt_id=f"attempt-{len(self._attempts)+1:02d}",
+            kind=kind.value if isinstance(kind, AttemptKind) else kind,
+            base_sha=base_sha, branch=branch, worktree_path=worktree_path,
+            feedback_input=feedback, parent_attempt_id=parent)
+        self._attempts.append(att)
+        return att
+
+    def current(self) -> Optional[Attempt]:
+        return self._attempts[-1] if self._attempts else None
+
+    def all(self) -> list[Attempt]:
+        return list(self._attempts)
+
+    def to_dict(self) -> dict:
+        return {"team_id": self.team_id, "cap": self.cap,
+                "attempts": [asdict(a) for a in self._attempts]}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AttemptLog":
+        log = cls(team_id=d["team_id"], cap=d["cap"])
+        log._attempts = [Attempt(**a) for a in d["attempts"]]
+        return log

cih_agent-0.1.0/cih/config.py

@@ -0,0 +1,81 @@
+import os
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Optional
+
+class ConfigError(Exception):
+    pass
+
+_MODES = {"fixed-N", "until-converged"}
+
+DEPTH_BUDGET = {"low": 3, "medium": 6, "high": 10}
+DEFAULT_DEPTH = "medium"
+
+
+def depth_budget(name: Optional[str] = None) -> int:
+    """Map a --depth name to its question budget (upper bound). None → default."""
+    if name is None:
+        name = DEFAULT_DEPTH
+    if name not in DEPTH_BUDGET:
+        raise ConfigError(
+            f"depth must be one of {sorted(DEPTH_BUDGET, key=DEPTH_BUDGET.__getitem__)} (got {name!r})"
+        )
+    return DEPTH_BUDGET[name]
+
+
+@dataclass
+class RunConfig:
+    mode: str
+    target_repo: str
+    state_dir: str
+    iterations: Optional[int] = None
+    max_iterations: int = 25
+    budget_cap: Optional[int] = None
+    focus_areas: list[str] = field(default_factory=list)
+    value_threshold: float = 0.5
+    convergence_dry_streak: int = 2
+    plan_review_retries: int = 2
+    exec_review_retries: int = 2
+    max_teams_per_iteration: int = 4
+    integration_retries: int = 2
+    per_team_attempt_cap: int = 4
+    cooldown_iterations: int = 2
+    opportunity_max_attempts: int = 3
+    tdd_adapter: str = "pytest"
+
+    @staticmethod
+    def _validate_paths(target_repo: str, state_dir: str) -> None:
+        for label, p in (("target_repo", target_repo), ("state_dir", state_dir)):
+            if not os.path.isabs(p):
+                raise ConfigError(f"{label} must be an absolute path: {p}")
+        t = Path(target_repo).resolve()
+        s = Path(state_dir).resolve()
+        if t == s:
+            raise ConfigError("target_repo and state_dir must be distinct")
+        if t in s.parents or s in t.parents:
+            raise ConfigError("state_dir must not be nested inside target_repo (or vice versa)")
+        for label, p in (("target_repo", t), ("state_dir", s)):
+            if not p.is_dir():
+                raise ConfigError(f"{label} must be an existing directory: {p}")
+
+    @classmethod
+    def create(cls, **kwargs) -> "RunConfig":
+        mode = kwargs.get("mode")
+        if mode not in _MODES:
+            raise ConfigError(f"mode must be one of {_MODES}")
+        iterations = kwargs.get("iterations")
+        if mode == "fixed-N":
+            if not isinstance(iterations, int) or iterations <= 0:
+                raise ConfigError("fixed-N mode requires iterations to be a positive int")
+        elif mode == "until-converged":
+            if iterations is not None:
+                raise ConfigError("until-converged mode must not set iterations")
+        cls._validate_paths(kwargs["target_repo"], kwargs["state_dir"])
+        return cls(**kwargs)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "RunConfig":
+        return cls.create(**d)

cih_agent-0.1.0/cih/contracts.py

@@ -0,0 +1,32 @@
+# cih/contracts.py
+import hashlib
+import json
+from dataclasses import dataclass, field
+from jsonschema import validate, ValidationError
+
+class OutputValidationError(Exception):
+    pass
+
+@dataclass
+class AgentContract:
+    role: str
+    agent_version: str
+    role_prompt: str
+    input_schema: dict
+    output_schema: dict
+    allowed_tools: list = field(default_factory=list)
+    runtime_adapter_settings: dict = field(default_factory=dict)
+
+    def validate_output(self, output: dict) -> None:
+        try:
+            validate(instance=output, schema=self.output_schema)
+        except ValidationError as e:
+            raise OutputValidationError(f"{self.role} output invalid: {e.message}") from e
+
+    def prompt_hash(self) -> str:
+        blob = json.dumps({"prompt": self.role_prompt, "in": self.input_schema,
+                           "out": self.output_schema, "v": self.agent_version,
+                           "tools": self.allowed_tools,
+                           "adapter": self.runtime_adapter_settings},
+                          sort_keys=True)
+        return hashlib.sha256(blob.encode()).hexdigest()[:16]