project-loop-harness 0.1.2__tar.gz

project_loop_harness-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Project Loop Harness 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.

project_loop_harness-0.1.2/PKG-INFO

@@ -0,0 +1,361 @@
+Metadata-Version: 2.4
+Name: project-loop-harness
+Version: 0.1.2
+Summary: Local control plane for agentic project development loops
+Author: Project Loop Harness Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/mocchalera/project-loop-harness
+Project-URL: Repository, https://github.com/mocchalera/project-loop-harness
+Project-URL: Issues, https://github.com/mocchalera/project-loop-harness/issues
+Project-URL: Documentation, https://github.com/mocchalera/project-loop-harness/tree/main/docs
+Keywords: agents,codex,claude-code,sqlite,dashboard,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# Project Loop Harness
+
+Project Loop Harness is a local control plane for coding agents.
+
+It is not just an Agent Skill. The core product is `pcl`, a small local CLI/runtime that gives Codex, Claude Code, and similar agents a guarded project-scoped loop: durable state in SQLite, append-only audit events in JSONL, generated prompts and evidence, strict validation, human-readable reports, and a deterministic dashboard.
+
+## Quick Start
+
+Until a PyPI package is published, install from a pinned GitHub tag or commit:
+
+```bash
+pipx install "git+https://github.com/mocchalera/project-loop-harness.git@v0.1.2"
+pcl --help
+```
+
+PyPI publishing is prepared through GitHub Actions Trusted Publishing. See
+[docs/pypi-publishing.md](docs/pypi-publishing.md) for the TestPyPI/PyPI setup
+and release checklist.
+
+Initialize a target project:
+
+```bash
+cd target-project
+pcl init
+pcl doctor
+pcl validate --strict
+pcl render --json
+```
+
+Then ask your coding agent to read `AGENTS.md`, `CLAUDE.md` if present, and
+`pcl.yaml`, run `pcl next --json`, and follow the next safe harness action.
+
+## Mental Model
+
+```text
+Goal -> Harness -> Workflow -> Agent Jobs -> Evidence -> Verification -> State -> Dashboard -> Stop/Retry/Escalate
+```
+
+The important separation is:
+
+```text
+Skill          = instructions for agents
+pcl CLI        = runtime that mutates state, validates, renders, and routes work
+project.db     = current normalized loop memory
+events.jsonl   = append-only audit log
+dashboard.html = generated human-readable view
+Plugin         = Codex distribution wrapper
+MCP            = optional read/local-render bridge
+```
+
+Agents should never edit `.project-loop/project.db` or generated dashboard HTML directly. State changes go through `pcl` commands or internal service functions, and every state mutation appends an event.
+
+## Repository Layout
+
+```text
+project-loop-harness/
+|- src/pcl/                         # Python CLI/runtime
+|- skills/project-control-loop/      # Standalone Agent Skill template
+|- plugins/codex-project-loop/       # Codex plugin packaging scaffold and inventory
+|- docs/                            # Architecture and operational docs
+|- agent-tasks/                     # Numbered implementation tasks
+|- examples/                        # Example project configs
+`- tests/                           # CLI/runtime tests
+```
+
+## Install For Local Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+pytest
+pcl --help
+```
+
+## Distribution Smoke Test
+
+Before publishing or handing the runtime to another project, verify a wheel install rather than only editable install:
+
+```bash
+python -m pip wheel . --no-deps --no-build-isolation -w /tmp/pcl-wheelhouse
+python -m venv /tmp/pcl-wheel-venv
+/tmp/pcl-wheel-venv/bin/python -m pip install --no-deps /tmp/pcl-wheelhouse/project_loop_harness-*.whl
+/tmp/pcl-wheel-venv/bin/pcl --help
+/tmp/pcl-wheel-venv/bin/pcl-mcp --help
+```
+
+The automated version is covered by:
+
+```bash
+pytest tests/test_distribution.py
+```
+
+## Adoption Guide
+
+For practical rollout into another repository, use
+[docs/adoption-guide.md](docs/adoption-guide.md). It covers the current GitHub
+install path, local wheel handoff, what `pcl init` adds to a target project,
+which files to commit, and starter prompts for the first agent session.
+
+## Golden Path
+
+This path runs a complete feature-coverage loop in a temporary project:
+
+```bash
+rm -rf /tmp/pcl-demo
+mkdir -p /tmp/pcl-demo
+
+pcl init --target /tmp/pcl-demo
+pcl doctor --root /tmp/pcl-demo
+
+pcl goal create --root /tmp/pcl-demo --title "Reach basic feature coverage"
+pcl loop run --root /tmp/pcl-demo feature_coverage --goal G-0001
+
+pcl next --root /tmp/pcl-demo --json
+pcl jobs read --root /tmp/pcl-demo J-0001
+pcl jobs complete --root /tmp/pcl-demo J-0001 --summary "Mapped project surfaces"
+pcl jobs complete --root /tmp/pcl-demo J-0002 --summary "Wrote user stories"
+pcl jobs complete --root /tmp/pcl-demo J-0003 --summary "Designed test cases"
+
+pcl next --root /tmp/pcl-demo --explain
+pcl verification record --root /tmp/pcl-demo --run WR-0001 --result approved --reason "Reviewed generated coverage"
+pcl loop complete --root /tmp/pcl-demo WR-0001 --summary "Feature coverage complete"
+pcl goal close --root /tmp/pcl-demo G-0001 --summary "Coverage goal done" --verification V-0001
+
+pcl validate --root /tmp/pcl-demo --strict
+pcl report goal --root /tmp/pcl-demo G-0001
+pcl report run --root /tmp/pcl-demo WR-0001
+pcl feature list --root /tmp/pcl-demo --json
+pcl render --root /tmp/pcl-demo
+```
+
+Open `/tmp/pcl-demo/.project-loop/dashboard/dashboard.html` after rendering.
+
+See [docs/golden-path.md](docs/golden-path.md) for the same path with expected checkpoints and a human-decision branch.
+
+For approved workflows that pass the executor preflight, the guarded automatic
+path is:
+
+```bash
+pcl workflow verify --root /tmp/pcl-demo --template executor_smoke
+pcl workflow sandbox --root /tmp/pcl-demo --template executor_smoke --json
+pcl loop execute --root /tmp/pcl-demo executor_smoke --json
+```
+
+Failed or interrupted executor runs are recovered explicitly:
+
+```bash
+pcl loop execute workflow_id --retry WR-0001
+pcl loop execute workflow_id --resume WR-0001
+```
+
+Agent steps are not launched unless explicitly enabled:
+
+```bash
+pcl loop execute workflow_id --agent-adapter generic_shell --allow-agent-exec
+```
+
+## Guided Next Actions
+
+`pcl next` is the loop router. The JSON output keeps the original fields and adds stable guidance fields:
+
+```json
+{
+  "type": "continue_workflow",
+  "command": "pcl jobs read J-0001",
+  "reason": "A workflow run is already active and has queued or running jobs.",
+  "target": {"id": "WR-0001"},
+  "priority": 40,
+  "blocking": false,
+  "requires_human": false,
+  "safe_to_run": true,
+  "run_policy": "agent_safe",
+  "human_guidance": "An agent or automation may run this command in the current project context.",
+  "expected_after": "The agent job prompt is reviewed and the job can be executed or completed."
+}
+```
+
+Use:
+
+```bash
+pcl next --json
+pcl next --explain
+pcl next --strict --json
+```
+
+Priority order is fixed:
+
+1. strict validation failure
+2. open escalation
+3. open decision
+4. `needs_human` verification requiring escalation
+5. active workflow lifecycle
+6. executor retry routing
+7. open defect lifecycle
+8. workflow proposal review
+9. checkpoint review after several done features
+10. open goal continuation
+11. uncovered feature coverage
+12. create goal
+
+## Checkpoint Reviews
+
+Dogfooding showed that Project Loop is effective at small verified improvements,
+but large UX goals still need periodic human prioritization. Use checkpoint
+reviews to pause after several done features, organize commit/package boundaries,
+refresh UX or interaction checklists, and choose the next feature by product
+impact:
+
+```bash
+pcl checkpoint status --json
+pcl checkpoint record \
+  --review-type integration \
+  --summary "Reviewed commit boundary, UX checklist, and next priority" \
+  --evidence "Reviewed validation output, git diff, UX checklist, and next feature priority"
+```
+
+When five features are marked `done` after the latest checkpoint, `pcl next`
+returns `checkpoint_review` before recommending another feature-coverage run.
+
+## Human Decision Flow
+
+When verification needs human judgment, keep ambiguity and the decision as durable state:
+
+```bash
+pcl verification record --root /tmp/pcl-demo --run WR-0001 --result needs_human --reason "Product decision required"
+pcl next --root /tmp/pcl-demo --json
+
+pcl escalation open --root /tmp/pcl-demo --run WR-0001 --severity high --question "What should ship?" --recommendation "Choose the safest reversible path"
+pcl decision open --root /tmp/pcl-demo --escalation ESC-0001 --question "Which path should we take?" --recommendation "Choose the safest reversible path"
+pcl decision resolve --root /tmp/pcl-demo DEC-0001 --selected-option "Ship locally first" --reason "Risk stays local"
+pcl escalation resolve --root /tmp/pcl-demo ESC-0001 --decision DEC-0001 --summary "Human decision recorded"
+```
+
+Escalations and decisions are linked through `decisions.blocks_json` and event payloads. Dashboard rows and reports show `linked_escalation_ids` and `linked_decision_ids`.
+
+## Reports And Dashboard
+
+Generated artifacts are review surfaces, not sources of truth:
+
+```bash
+pcl report goal --root /tmp/pcl-demo G-0001
+pcl report run --root /tmp/pcl-demo WR-0001
+pcl report feature --root /tmp/pcl-demo F-0001
+pcl report defect --root /tmp/pcl-demo D-0001
+pcl report validation --root /tmp/pcl-demo --strict
+pcl render --root /tmp/pcl-demo
+```
+
+Reports are written to `.project-loop/reports/`. The dashboard writes:
+
+```text
+.project-loop/dashboard/dashboard-data.json
+.project-loop/dashboard/dashboard.html
+```
+
+Run `pcl validate` before rendering whenever possible. `pcl render` already performs normal validation and refuses to render on errors.
+
+If validation fails or generated artifacts look stale, use [docs/recovery-playbook.md](docs/recovery-playbook.md) before continuing normal work.
+
+## Example Projects
+
+Seed configs live under [examples/](examples/). Copy one to a scratch directory, run `pcl init --target ...`, then follow the golden path without committing generated `.project-loop/` state back into the example.
+
+## Current Runtime Surface
+
+The current local runtime supports:
+
+- `pcl init`, `doctor`, `validate`, `migrate`, migration status, `render`;
+- feature creation, inspection, and evidence-backed status changes;
+- workflow run creation from static templates;
+- agent job prompts, filtered inspection, adapter commands, completion/failure/cancellation;
+- documented agent adapter command contract;
+- hardened Codex CLI adapter command template;
+- hardened Claude Code manual adapter instructions;
+- generic shell adapter command template;
+- validated agent output ingestion as evidence;
+- job-centric evidence linkage for ingested agent output;
+- verification recording;
+- workflow run, goal, defect, escalation, and decision lifecycle commands;
+- escalation/decision linkage;
+- checkpoint review commands for commit/package, UX checklist, and next-priority pauses;
+- strict validation invariants and audit-log integrity checks;
+- evidence-backed Markdown reports;
+- deterministic dashboard data and HTML with JSON artifact paths, a versioned data contract, evidence navigation, and risk/blocker summary;
+- guided `pcl next` actions with uncovered-feature routing;
+- complete CSV export for reviewable loop state;
+- optional local stdio MCP server;
+- Codex plugin packaging scaffold with package inventory and reusable GitHub Action for local validation;
+- workflow proposal mode, guarded human approval, static verifier checks, limited sandbox planning/execution, guarded automatic workflow execution with explicit retry/resume, and a bundled `executor_smoke` workflow for dogfooding the executor.
+
+## Implementation Task Order
+
+Give tasks to coding agents in numeric order:
+
+```text
+agent-tasks/0001-hardening-cli.md
+...
+agent-tasks/0017-next-action-guided-loop.md
+agent-tasks/0018-readme-golden-path.md
+agent-tasks/0019-recovery-playbook.md
+agent-tasks/0020-example-project-refresh.md
+agent-tasks/0021-agent-adapter-contract.md
+agent-tasks/0022-agent-output-validation.md
+agent-tasks/0023-codex-exec-adapter-hardening.md
+agent-tasks/0024-claude-manual-adapter-hardening.md
+agent-tasks/0025-generic-shell-adapter.md
+agent-tasks/0026-agent-job-evidence-ingestion.md
+agent-tasks/0027-dashboard-data-contract.md
+agent-tasks/0028-dashboard-evidence-navigation.md
+agent-tasks/0029-dashboard-risk-and-blockers.md
+agent-tasks/0030-distribution-readiness.md
+agent-tasks/0031-workflow-proposal-mode.md
+agent-tasks/0032-workflow-proposal-review.md
+agent-tasks/0033-workflow-verifier.md
+agent-tasks/0034-limited-execution-sandbox.md
+agent-tasks/0035-automatic-workflow-executor.md
+agent-tasks/0036-executor-dogfood-workflow.md
+agent-tasks/0037-executor-retry-resume.md
+```
+
+Do not skip directly to MCP, plugin distribution, hosted services, or dynamic workflow generation before the CLI/runtime and project state layer are solid.
+
+## Non-Goals For The First Production Milestone
+
+- No cloud backend.
+- No hosted dashboard.
+- No production database access.
+- No autonomous destructive operations.
+- No automatic external notifications.
+- No fully dynamic workflow generation before static workflow templates are stable.