code-delegation-harness 0.2.1__tar.gz

code_delegation_harness-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grok Coding Delegate Contributors
+
+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.

code_delegation_harness-0.2.1/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: code-delegation-harness
+Version: 0.2.1
+Summary: A harness for delegating coding work to LLMs while keeping your main agent clean. Structured artifacts, long-running support, and swappable backends.
+Author-email: Joshua Fielden <joshua@fielden.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/joshuafielden43/code-delegation-harness
+Project-URL: Repository, https://github.com/joshuafielden43/code-delegation-harness
+Keywords: ai,llm,coding,delegation,automation,grok,agent,sidecar,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# code-delegation-harness
+
+A simple harness for delegating coding work to LLMs while keeping your main agent clean.
+
+It gives you structured output + reviewable artifacts (JSON + human report + patch) even on long-running tasks, and lets you swap different backends without rewriting your top-level orchestration.
+
+## Quick Start
+
+For normal use:
+
+```bash
+pip install git+https://github.com/joshuafielden43/code-delegation-harness.git@v0.2.1
+gcdh --help
+```
+
+For development or the absolute latest code, see the [full installation guide](docs/installation.md).
+
+Works best with Grok right now, but designed to be usable with other models too.
+
+## Why This Exists
+
+Most agent setups mix your long-term context, style, and memory with the actual coding work. Over time that gets messy.
+
+This tool tries to keep those concerns separate:
+- Your primary agent/persona stays yours.
+- Coding tasks get handed off to a focused execution environment.
+- You get back clean, reviewable results instead of another giant conversation.
+
+It also gives you the option to swap the backend harness later without having to change how you orchestrate things at the top level.
+
+## Current Output
+
+When you run a task with `--output-file`, you get:
+- `result.json` — structured data
+- `result.report.md` — human-readable review document with diffs and observations
+- `result.patch` — ready-to-apply unified diff (when code changed)
+
+The goal is simple: you stay you. The work gets done well. And you only have to review the actual result.
+
+## Current Output (What You Actually Review)
+
+When you delegate with `--output-file`, the harness produces:
+
+- `result.json` — full structured data (status, files changed, summaries, errors)
+- `result.report.md` — the primary document for reviewing the **end result** (clear status, per-file change descriptions with line stats and diff previews, observations from any analysis, verification steps)
+- `result.patch` (when code was modified) — a ready-to-apply unified diff you can review or apply directly with `git apply`
+
+The design goal is that you spend your time reviewing actual delivered work and collaborating on changes, not reviewing incremental proposals.
+
+## Basic Usage
+
+From within a Grok / agent session:
+
+```
+Delegate this task using the code-delegation-harness:
+
+Task: Add Google-style docstrings and type hints to the `process_batch` function in src/batch.py. Do not change behavior.
+
+Target directory: /path/to/your/project
+
+Constraints: Follow the existing style in the file. Keep changes minimal.
+```
+
+For the best experience, have the underlying wrapper called with `--output-file` so you receive the full set of review artifacts.
+
+### Professional CLI (`gcdh`)
+
+**Recommended today (immediate & reliable):**
+
+```bash
+cd code-delegation-harness
+chmod +x bin/gcdh
+export PATH="$PWD/bin:$PATH"
+
+gcdh --help
+gcdh --quiet --task "..." --target-dir /path/to/project --output-file result.json
+```
+
+**Installation**
+
+See the [full Installation guide](docs/installation.md) for the recommended path for primary agents versus development use.
+
+## Documentation
+
+Full documentation lives in the `docs/` directory:
+
+- [Installation](docs/installation.md)
+- [Usage Notes](docs/usage-notes.md)
+- [Examples](docs/examples/)
+- [Dogfooding Case Study](docs/dogfooding-case-study.md)
+- [Complete Proposed Documentation Structure](docs/DOCUMENTATION-STRUCTURE.md) (what we intend to build over time)
+
+### For Agents, Sidecars & Automation (Robot-Useful)
+
+The harness was built to be driven by other agents and sidecars:
+
+- `--quiet` (`-q`) → minimal, clean output perfect for programmatic consumption.
+- `--output-file` is strongly recommended — it produces the full machine + human artifact set.
+- Structured JSON output is stable and self-describing.
+- `--dry-run` + `--quiet` gives agents a cheap, safe way to preview a task before committing.
+- Persistent status files + `--status` / `--resume` make long-running work observable and resumable from outside.
+
+This design makes it a strong primitive for building reliable delegation into larger agent architectures (including future sidecar systems).
+
+### Quiet Mode
+
+`--quiet` (`-q`) is one of the most useful flags for both humans and agents. In quiet mode the tool only emits errors and the final artifact paths, making runs much cleaner — especially when combined with `--output-file`.
+
+Long-running tasks are well supported:
+- Use `--timeout` (seconds) and `--max-turns` to give big jobs room to breathe.
+- Add `--wait-for-completion --max-wait 14400` (for example) and the wrapper will automatically poll until a background run finishes, then deliver the complete artifacts (full .json + .report.md + .patch + .run-meta.json).
+- Persistent `.cdh-run-<id>.status` files are written for any run using `--run-name` or `--wait-for-completion`. These contain task snippet, run_name, timing, and state (launched / waiting / completed / max_wait_exceeded).
+- Use `--status --target-dir /path` at any time to see both active and completed runs in that tree.
+- Use `--resume <run-id-or-file>` to re-attach to a background run (smart short-circuit if it already finished).
+- All final human review artifacts reflect the full background/resumption story when relevant.
+
+See the `docs/` directory for usage notes, examples, and case studies.
+
+### Dry-Run Preview Mode
+
+Use `--dry-run` (ideally with `--quiet`) before expensive or long-running delegations. It shows exactly what would happen without executing anything or writing files:
+
+- The full prompt that would be sent
+- Resolved configuration and flags
+- Expected output artifacts
+
+This is extremely useful for agents and for humans reviewing scope.
+
+Combine with `--quiet` for the cleanest preview output.
+
+## Strengths
+
+- Produces excellent, self-contained review artifacts by default
+- Strong, reliable support for long-running and background tasks
+- Clean handling of read-only / no-change work
+- Clear error categorization and status reporting
+- Full observability via persistent status files + `--status` / `--resume`
+
+## Current Status (Production Ready)
+
+The harness is ready for real, repeated use on production work.
+
+It delivers clean, reviewable end results even on long-running tasks:
+- Complete structured JSON
+- High-signal human `.report.md` with checklists and "How to Review This Change" guidance
+- Ready-to-apply `.patch`
+- `.run-meta.json` for reproducibility
+- Persistent status files (`.cdh-run-*.status`) with full launch → wait → completion lifecycle, queryable via `--status`
+
+Long-running support is first-class:
+- `--timeout` / `--max-turns`
+- `--wait-for-completion` with automatic background recovery
+- `--status` and smart `--resume` for visibility and control
+
+The project maintains two aligned purposes:
+- A practical, MIT-licensed tool for reliable coding delegation
+- The primary dogfooding platform for designing clean delegation patterns for future sidecar architectures
+
+The code in this repository is the current production version.
+
+## Development & Contributing
+
+Core implementation lives in `src/code_delegation_harness/harness.py` (with shims in `bin/gcdh`; `scripts/grok_delegate.py` is a legacy compatibility shim). You can also run with `python -m code_delegation_harness` after install or with PYTHONPATH=src.
+
+See `CHANGELOG.md` for release history. Full development notes live in the upstream development tree.
+
+## License
+
+MIT
+
+---
+
+Built as a focused coding harness. The priority is useful, low-friction delegation with excellent output — for the person who still has to read, understand, and take responsibility for the final result.

code_delegation_harness-0.2.1/README.md

@@ -0,0 +1,173 @@
+# code-delegation-harness
+
+A simple harness for delegating coding work to LLMs while keeping your main agent clean.
+
+It gives you structured output + reviewable artifacts (JSON + human report + patch) even on long-running tasks, and lets you swap different backends without rewriting your top-level orchestration.
+
+## Quick Start
+
+For normal use:
+
+```bash
+pip install git+https://github.com/joshuafielden43/code-delegation-harness.git@v0.2.1
+gcdh --help
+```
+
+For development or the absolute latest code, see the [full installation guide](docs/installation.md).
+
+Works best with Grok right now, but designed to be usable with other models too.
+
+## Why This Exists
+
+Most agent setups mix your long-term context, style, and memory with the actual coding work. Over time that gets messy.
+
+This tool tries to keep those concerns separate:
+- Your primary agent/persona stays yours.
+- Coding tasks get handed off to a focused execution environment.
+- You get back clean, reviewable results instead of another giant conversation.
+
+It also gives you the option to swap the backend harness later without having to change how you orchestrate things at the top level.
+
+## Current Output
+
+When you run a task with `--output-file`, you get:
+- `result.json` — structured data
+- `result.report.md` — human-readable review document with diffs and observations
+- `result.patch` — ready-to-apply unified diff (when code changed)
+
+The goal is simple: you stay you. The work gets done well. And you only have to review the actual result.
+
+## Current Output (What You Actually Review)
+
+When you delegate with `--output-file`, the harness produces:
+
+- `result.json` — full structured data (status, files changed, summaries, errors)
+- `result.report.md` — the primary document for reviewing the **end result** (clear status, per-file change descriptions with line stats and diff previews, observations from any analysis, verification steps)
+- `result.patch` (when code was modified) — a ready-to-apply unified diff you can review or apply directly with `git apply`
+
+The design goal is that you spend your time reviewing actual delivered work and collaborating on changes, not reviewing incremental proposals.
+
+## Basic Usage
+
+From within a Grok / agent session:
+
+```
+Delegate this task using the code-delegation-harness:
+
+Task: Add Google-style docstrings and type hints to the `process_batch` function in src/batch.py. Do not change behavior.
+
+Target directory: /path/to/your/project
+
+Constraints: Follow the existing style in the file. Keep changes minimal.
+```
+
+For the best experience, have the underlying wrapper called with `--output-file` so you receive the full set of review artifacts.
+
+### Professional CLI (`gcdh`)
+
+**Recommended today (immediate & reliable):**
+
+```bash
+cd code-delegation-harness
+chmod +x bin/gcdh
+export PATH="$PWD/bin:$PATH"
+
+gcdh --help
+gcdh --quiet --task "..." --target-dir /path/to/project --output-file result.json
+```
+
+**Installation**
+
+See the [full Installation guide](docs/installation.md) for the recommended path for primary agents versus development use.
+
+## Documentation
+
+Full documentation lives in the `docs/` directory:
+
+- [Installation](docs/installation.md)
+- [Usage Notes](docs/usage-notes.md)
+- [Examples](docs/examples/)
+- [Dogfooding Case Study](docs/dogfooding-case-study.md)
+- [Complete Proposed Documentation Structure](docs/DOCUMENTATION-STRUCTURE.md) (what we intend to build over time)
+
+### For Agents, Sidecars & Automation (Robot-Useful)
+
+The harness was built to be driven by other agents and sidecars:
+
+- `--quiet` (`-q`) → minimal, clean output perfect for programmatic consumption.
+- `--output-file` is strongly recommended — it produces the full machine + human artifact set.
+- Structured JSON output is stable and self-describing.
+- `--dry-run` + `--quiet` gives agents a cheap, safe way to preview a task before committing.
+- Persistent status files + `--status` / `--resume` make long-running work observable and resumable from outside.
+
+This design makes it a strong primitive for building reliable delegation into larger agent architectures (including future sidecar systems).
+
+### Quiet Mode
+
+`--quiet` (`-q`) is one of the most useful flags for both humans and agents. In quiet mode the tool only emits errors and the final artifact paths, making runs much cleaner — especially when combined with `--output-file`.
+
+Long-running tasks are well supported:
+- Use `--timeout` (seconds) and `--max-turns` to give big jobs room to breathe.
+- Add `--wait-for-completion --max-wait 14400` (for example) and the wrapper will automatically poll until a background run finishes, then deliver the complete artifacts (full .json + .report.md + .patch + .run-meta.json).
+- Persistent `.cdh-run-<id>.status` files are written for any run using `--run-name` or `--wait-for-completion`. These contain task snippet, run_name, timing, and state (launched / waiting / completed / max_wait_exceeded).
+- Use `--status --target-dir /path` at any time to see both active and completed runs in that tree.
+- Use `--resume <run-id-or-file>` to re-attach to a background run (smart short-circuit if it already finished).
+- All final human review artifacts reflect the full background/resumption story when relevant.
+
+See the `docs/` directory for usage notes, examples, and case studies.
+
+### Dry-Run Preview Mode
+
+Use `--dry-run` (ideally with `--quiet`) before expensive or long-running delegations. It shows exactly what would happen without executing anything or writing files:
+
+- The full prompt that would be sent
+- Resolved configuration and flags
+- Expected output artifacts
+
+This is extremely useful for agents and for humans reviewing scope.
+
+Combine with `--quiet` for the cleanest preview output.
+
+## Strengths
+
+- Produces excellent, self-contained review artifacts by default
+- Strong, reliable support for long-running and background tasks
+- Clean handling of read-only / no-change work
+- Clear error categorization and status reporting
+- Full observability via persistent status files + `--status` / `--resume`
+
+## Current Status (Production Ready)
+
+The harness is ready for real, repeated use on production work.
+
+It delivers clean, reviewable end results even on long-running tasks:
+- Complete structured JSON
+- High-signal human `.report.md` with checklists and "How to Review This Change" guidance
+- Ready-to-apply `.patch`
+- `.run-meta.json` for reproducibility
+- Persistent status files (`.cdh-run-*.status`) with full launch → wait → completion lifecycle, queryable via `--status`
+
+Long-running support is first-class:
+- `--timeout` / `--max-turns`
+- `--wait-for-completion` with automatic background recovery
+- `--status` and smart `--resume` for visibility and control
+
+The project maintains two aligned purposes:
+- A practical, MIT-licensed tool for reliable coding delegation
+- The primary dogfooding platform for designing clean delegation patterns for future sidecar architectures
+
+The code in this repository is the current production version.
+
+## Development & Contributing
+
+Core implementation lives in `src/code_delegation_harness/harness.py` (with shims in `bin/gcdh`; `scripts/grok_delegate.py` is a legacy compatibility shim). You can also run with `python -m code_delegation_harness` after install or with PYTHONPATH=src.
+
+See `CHANGELOG.md` for release history. Full development notes live in the upstream development tree.
+
+## License
+
+MIT
+
+---
+
+Built as a focused coding harness. The priority is useful, low-friction delegation with excellent output — for the person who still has to read, understand, and take responsibility for the final result.

code_delegation_harness-0.2.1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "code-delegation-harness"
+version = "0.2.1"
+description = "A harness for delegating coding work to LLMs while keeping your main agent clean. Structured artifacts, long-running support, and swappable backends."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+  {name = "Joshua Fielden", email = "joshua@fielden.dev"}
+]
+keywords = ["ai", "llm", "coding", "delegation", "automation", "grok", "agent", "sidecar", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.scripts]
+# After `pip install -e .` (or `pip install .`), users get the professional command:
+#   gcdh --help
+gcdh = "code_delegation_harness.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/joshuafielden43/code-delegation-harness"
+Repository = "https://github.com/joshuafielden43/code-delegation-harness"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+exclude = ["tests*"]

code_delegation_harness-0.2.1/setup.cfg

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

code_delegation_harness-0.2.1/src/code_delegation_harness/__init__.py

@@ -0,0 +1,34 @@
+"""
+Code Delegation Harness
+
+Professional packaging for the `gcdh` command.
+"""
+
+from importlib.metadata import version as _pkg_version, PackageNotFoundError
+
+from .harness import (
+    main,
+    prune_completed_status_files,
+    normalize_result,
+    render_human_report,
+    _determine_status,
+    _compute_diffs_and_stats,
+    _print_dry_run_preview,
+    _make_delegate_status,
+    _write_status_file,
+    _finalize_delegate_status,
+    _wait_for_background_completion,
+)
+
+try:
+    __version__ = _pkg_version("code-delegation-harness")
+except (PackageNotFoundError, Exception):
+    __version__ = "0.2.0"
+
+__all__ = [
+    "main",
+    "prune_completed_status_files",
+    "normalize_result",
+    "render_human_report",
+    "__version__",
+]

code_delegation_harness-0.2.1/src/code_delegation_harness/__main__.py

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

code_delegation_harness-0.2.1/src/code_delegation_harness/cli.py

@@ -0,0 +1,9 @@
+"""
+CLI entry point for the `gcdh` command.
+
+This module provides the console_script target:
+    gcdh = "code_delegation_harness.cli:main"
+"""
+from .harness import main
+
+__all__ = ["main"]