Metadata-Version: 2.4
Name: project-loop-harness
Version: 0.5.1
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: build>=1; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: setuptools>=69; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Provides-Extra: mcp-test
Requires-Dist: mcp==1.28.1; extra == "mcp-test"
Dynamic: license-file

# Project Loop Harness

> A local, model-neutral control plane that turns an agent's “done” into
> reviewable Evidence, verification status, residual risk, and a resumable next
> step.

## Understand it in 30 seconds

Coding agents are good at producing changes. They are less reliable at
remembering project state, proving completion, stopping at human decisions, and
handing work to another session or model.

Project Loop Harness (`pcl`) gives Codex, Claude Code, and similar agents a
shared local state machine:

- SQLite keeps current state; JSONL keeps an auditable event projection.
- Tests, artifacts, reviews, and completion packets preserve what “done” means.
- Agents continue routine safe work; humans are asked only for genuine product,
  permission, security, destructive, or external-service decisions.
- The runtime does not call an LLM and does not depend on one agent vendor.

It is designed for people coordinating multiple coding agents, not as another
single-agent chat wrapper.

## Get first value in five minutes

### One-time operator setup

Install the runtime, inspect the adoption plan, and initialize the repository:

```bash
pipx install project-loop-harness
cd /path/to/your-project
pcl init --dry-run --json
pcl init
```

`pcl init` retains existing `AGENTS.md`, `CLAUDE.md`, and `.gitignore` content
and appends its marked instruction block once. It also preserves an existing
`pcl.yaml` by default. `--force` can replace generated templates such as
`pcl.yaml`, workflows, the bundled Skill, and dashboard files; it does not
replace existing project-instruction content. See the
[Adoption Guide](docs/adoption-guide.md) for the exact file boundary.

### After setup, tell the agent the outcome you want

Copy this into Cockpit, Codex, Claude Code, or another coding-agent session:

```text
Read AGENTS.md, CLAUDE.md if present, and pcl.yaml. Use the Project Control
Loop. Start this goal: <describe the outcome>. Continue every agent-safe next
action, run the configured checks, preserve evidence, emit a completion packet,
and close the goal. Do not ask me to run routine pcl commands. Stop only for a
genuine human decision or external blocker.
```

The agent owns the routine `pcl start → implementation → finish → close` flow.
The operator uses the CLI during setup or deliberate maintenance, not to
manually advance every task.

The project remains local-only by default. No telemetry, provider call, cloud
sync, or automatic GitHub write is enabled by initialization.

## Install and inspect in more detail

Use `python -m pip install project-loop-harness` when installing inside a
project-specific virtual environment or CI job instead of exposing the command
globally. Confirm the installed runtime with:

```bash
pcl --version
pcl --help
```

For unreleased changes, install from a pinned GitHub tag or commit:

```bash
pipx install "git+https://github.com/mocchalera/project-loop-harness.git@<commit-or-tag>"
```

Initialize a target project:

```bash
cd target-project
pcl init --dry-run --json
pcl init
pcl doctor
pcl validate --strict
pcl render --json
```

Check whether a newer PyPI release is available:

```bash
pcl update check
pcl update command
```

`pcl update check` is explicit and advisory. It uses PyPI project metadata, keeps
a short local cache, performs no telemetry collection, and never upgrades the
environment by itself. Use `pcl doctor --check-updates` when you want the same
advisory warning alongside normal harness health checks. Set
`PCL_NO_VERSION_CHECK=1` to disable version checks.

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.

Compatibility promises for JSON contracts, typed errors, migrations, and
internal surfaces are documented in the
[Alpha Stability Policy](docs/stability-policy.md).

## 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   = derived append-only projection of authoritative SQLite events
dashboard.html = generated human-readable view, not agent context
Plugin         = Codex distribution wrapper
MCP            = optional read/local-render bridge
```

Agents should never edit `.project-loop/project.db` or read, parse, or edit generated dashboard HTML as project state. State changes go through `pcl` commands or internal service functions, and every state mutation appends an event. For machine context, use `pcl` JSON commands, reports, evidence paths, or `.project-loop/dashboard/dashboard-data.json`.

## 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
```

## Local Development

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
pytest
pcl --help
```

## Distribution Smoke Test

Before releasing a new version or handing the runtime to another project,
verify distribution artifacts rather than only editable install. The wheel is
the runtime install artifact; the sdist is the source artifact and must remain
self-contained for docs-as-contract tests.

```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
```

For release builds, also verify the sdist:

```bash
python -m build --outdir /tmp/pcl-release-dist --sdist --wheel
python scripts/verify_sdist_contracts.py --dist-dir /tmp/pcl-release-dist
```

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 target-project
setup, optional Git and local wheel handoff paths, 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 --dry-run --json
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
```

Humans can 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 guard --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
```

## Context Packs

Use context packs to hand focused, budget-aware loop context to another agent
without making generated dashboard HTML a machine context source:

```bash
pcl context pack --job J-0001
pcl context pack --job J-0001 --role verifier --max-tokens 12000 --json
pcl context pack --task T-0001 --json
```

The JSON contract is `context-pack/v1`. It includes included/omitted section
metadata, role profile selection, `token_estimator: "charclass/v1"`,
`estimated_token_count`, source commands, source paths, and the generated
Markdown package. Job packs include lease fields and rubric-aware verification
columns for `rubric/v1`; task packs include dependencies, dependents, linked
goal/feature/defect context, sibling tasks, and recent events. Tight budgets
omit whole sections deterministically rather than slicing through rendered
Markdown.
See [docs/context-pack.md](docs/context-pack.md) for the contract shape and
boundaries.

## Work Briefs

An optional `work-brief/v1` artifact can capture a target's reviewed intent,
acceptance criteria, constraints, non-goals, and assumptions without changing
the default `pcl start` path:

```bash
pcl contract validate --type work-brief/v1 work-brief.json --json
pcl brief add work-brief.json --summary "Reviewed execution input" --dry-run --json
pcl brief add work-brief.json --summary "Reviewed execution input" --json
pcl brief review E-0001 --actor "agent:codex" --actor-kind agent \
  --reason "Self-review completed; human gate remains open" --json
# Normally run by the agent after the human says "approve" in conversation:
pcl brief approve E-0001 --actor "human:owner" --actor-kind human \
  --recorded-by "agent:codex" --recorder-kind agent \
  --source-kind conversation --source-ref "conversation:<approval-reference>" \
  --reason "Human explicitly approved the presented review packet" --json
pcl brief show --target task:T-0001 --json
pcl route recommend --target task:T-0001 --json
pcl policy explain --target task:T-0001
pcl route override --target task:T-0001 --profile assure \
  --actor "human:owner" --reason "Require independent review" --dry-run --json
pcl route override --target task:T-0001 --profile assure \
  --actor "human:owner" --reason "Require independent review" --json
pcl route current --target task:T-0001 --json
```

Brief content is immutable Evidence. Review and approval are separate
hash-bound events: agent/system review cannot satisfy the human approval gate.
Task context, resume, and dashboard data expose the factual actor kind, actor,
recorder, source reference, timestamp, target, and bound hash without treating
assumptions as facts. Humans normally approve in conversation or Cockpit; the
agent records that decision through PCL. Direct human CLI use remains a
compatibility path, not the expected routine UX. See
[docs/work-brief-v1.md](docs/work-brief-v1.md).
Deterministic Direct/Discover/Assure recommendation is documented in
[docs/route-recommendation-v1.md](docs/route-recommendation-v1.md).
Multi-axis resolution and field-level source rules are documented in
[docs/adaptive-policy-v1.md](docs/adaptive-policy-v1.md).
An applied override preserves its original recommendation and policy
resolution as separate hash-bound Evidence. Task context, completion packets,
and resume handoffs expose additive references without rewriting historical
artifacts.

## Council Profile (opt-in)

Council is an external advisory boundary for ambiguous or high-risk work. It is
not a model provider, executor, verifier, approval, or replacement for Direct.
The Core prepares a deterministic request, validates and stores returned bytes,
and keeps any proposed choice behind a human Decision:

```bash
pcl --json profile list
pcl --json profile prepare council.discovery --target task:T-0001 --brief E-0001 \
  --output /tmp/council-request.json
pcl --json profile fixture-run --request /tmp/council-request.json --status completed \
  --output-dir /tmp/council-output
pcl --json profile ingest --request /tmp/council-request.json \
  --bundle /tmp/council-output/profile-output-bundle.json --dry-run
pcl --json profile ingest --request /tmp/council-request.json \
  --bundle /tmp/council-output/profile-output-bundle.json
```

Real network or paid execution is outside Core and requires a hash-bound human
authorization. `pcl profile authorize` only emits an authorized request; it
never runs a provider. Revoke an authorization through the governed CLI, never
by editing SQLite:

```bash
pcl --json profile authorize --revoke EV-XXXXXXXXXXXX --actor "human:owner" \
  --recorded-by "agent:codex" --source-kind cockpit \
  --source-ref "cockpit:<task-id>" --reason "Withdraw provider scope"
```

See [docs/council-profile.md](docs/council-profile.md) for the operator flow,
privacy boundary, status handling, and adoption constraints.

## Evidence Sets

Use `evidence-set/v1` when one passing artifact is not enough and the target
must retain which declared reports were included or excluded:

```bash
pcl evidence-set plan --target task:T-0001 --work-root work/lp \
  --manifest work/lp/reports/report-manifest.json \
  --required-kind visual_check \
  --include visual_check=E-0001:acceptance --json
pcl evidence-set record --target task:T-0001 --work-root work/lp \
  --manifest work/lp/reports/report-manifest.json \
  --required-kind visual_check \
  --include visual_check=E-0001:acceptance \
  --summary "LP verification evidence set" --json
```

Planning is read-only. Recording creates immutable, target-linked Evidence and
keeps known exclusions visible. See
[docs/evidence-set-v1.md](docs/evidence-set-v1.md).

Use a domain-neutral completion policy when a Test must require an external
JSON verdict rather than merely retain the report set:

```bash
pcl completion evaluate --policy completion-policy.json \
  --evidence-set E-0003 --test TC-0001 --json
pcl test pass TC-0001 --summary "Completion contract passed" \
  --evidence-id E-0003 --completion-policy completion-policy.json --json
pcl test reverify TC-0001 --summary "Modernized completion receipt" \
  --evidence-id E-0004 --completion-policy completion-policy.json --json
```

Only allowlisted JSON predicates are evaluated. The Evidence Set must target
the exact Test, remain complete, and retain matching report hashes. See
[docs/completion-policy-v1.md](docs/completion-policy-v1.md).

## Explainable Code Context

Build a local code context snapshot when an agent handoff needs auditable code
candidate context:

```bash
pcl index build --json
pcl index status --json
pcl code search "context pack" --json
pcl impact --diff --json
pcl eval retrieval --fixture tests/fixtures/retrieval_v0.json --json
```

The index is dependency-free and explicit. It records file metadata, hashes for
small text files, language, symbol-lite summaries, and test hints. It respects
default local-state exclusions and gitignore rules, and it records omitted
paths with reasons.

`pcl impact --diff --json` returns `impact/v0` and writes a context receipt
under `.project-loop/evidence/context-receipts/`, registered as normal
evidence. Receipts use the fields `included_candidate_context`, `omitted`, and
`staleness_warnings` to explain what PLH provided and why.

See [docs/code-context.md](docs/code-context.md) for the index, impact,
receipt, and retrieval-eval contracts.

### Target-bound agent handoff (v0.3)

To hand another agent auditable, target-scoped code context, bind a receipt to
the task or job, then require that binding when you build the pack:

```bash
pcl index build --json
pcl impact --diff --for-task T-0001 --json
pcl context pack --task T-0001 --include-code-context --require-bound-receipt --json
```

Use the `--for-job` / `--job` forms for an agent-job handoff:

```bash
pcl impact --diff --for-job J-0001 --json
pcl context pack --job J-0001 --include-code-context --require-bound-receipt --json
```

`pcl impact --diff --for-task` (or `--for-job`) records a caller-asserted binding
between the diff-based receipt and the target. With `--require-bound-receipt` the
pack fails with `context_pack_bound_receipt_required` instead of silently using an
unrelated latest receipt, so a worker never receives another task's context under
a target-bound label. The binding records that a receipt was created for the
target (`binding_strength: caller_asserted`) — not that the receipt is sufficient
or that any agent read it. Because the receipt comes from a diff, this is a
review/continuation handoff and presumes a change already exists for the target.

## 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."
}
```

When no active work or real human decision exists, the same schema returns
`type: "idle"`, `command: null`, `requires_human: false`, and
`run_policy: "idle"`. If a user has already supplied explicit work, pass that
literal intent to `pcl start "<intent>"` instead of inventing a Goal title or
asking for a second approval merely to register it.

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. unfinished executor resume routing
6. expired job lease reaping
7. active workflow lifecycle
8. executor retry routing
9. open defect lifecycle
10. workflow proposal review
11. checkpoint review after several done features
12. task backlog item under an open goal
13. open goal continuation
14. uncovered feature coverage
15. create goal

Task routing only considers tasks linked to an `open` or `active` goal through
`related_goal_id`. Unlinked tasks stay visible in backlog surfaces, but `pcl
next` intentionally does not route them in v1.

## Agent Registry And Leases

Register local agents before leasing jobs:

```bash
pcl agent register --name codex-worker --role implementer --adapter codex_exec --max-concurrency 1
pcl agent list --json
pcl jobs assign J-0001 --agent A-0001
pcl jobs lease J-0001 --agent A-0001 --ttl-seconds 1800 --json
pcl jobs heartbeat J-0001 --json
pcl jobs release J-0001 --reason "Pausing for handoff"
```

Lease expiry is lazy. No daemon or timer mutates job state. When `pcl next`
reports `reap_expired_leases`, run:

```bash
pcl jobs reap --json
```

`loop.lease_ttl_seconds` defaults to `1800`. `loop.max_lease_attempts` defaults
to `2`, meaning the first expired lease is requeued and the second expired lease
blocks the job and opens a high-severity escalation for human review.

## 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`.

To record caller feedback for a context receipt suggestion, quote the suggestion ID:

```bash
pcl verification feedback --root /tmp/pcl-demo --suggestion 'E-0001/VS-01' --status executed --result passed --evidence E-0009
pcl verification stats --root /tmp/pcl-demo --json
```

## 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 report skill-usage --since 2026-07-01 --json
pcl render --root /tmp/pcl-demo
```

Entity and validation reports are written to `.project-loop/reports/`.
`report skill-usage` is read-only and prints its privacy-safe aggregate to
stdout unless `--output` is explicit; see [Local Skill usage report](docs/skill-usage-report.md).
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.
Agents should use `.project-loop/dashboard/dashboard-data.json` or `pcl` JSON commands for rendered machine context; `dashboard.html` is human-only.

Use `pcl render --locale ja` to render Japanese dashboard chrome. Without the
flag, `pcl render` reads `dashboard.locale` from `pcl.yaml` and then falls back
to English. The locale affects only `dashboard.html`; `dashboard-data.json`
keys and values stay English for agents and integrations.

The dashboard opens with a simple operator view: **Now, Done, Next, Human
needed, and Risks**. `Done` lists only evidence-backed terminal records; it does
not turn a status label into a success claim. Counters, commands, queues, and
entity tables remain available under **Detailed Project Loop information**.

Agents should render routinely but present the dashboard only after plan
approval, at a major milestone, when a human decision blocks progress, and
after goal closure. When the host provides a visual or file panel, the agent
opens it and explains what to review; otherwise it provides the generated path.
The human should not need to remember when to ask for the dashboard.

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`, inspect-first `pcl init --dry-run`, `doctor`, `validate`, `migrate`, migration status, `render`;
- feature creation, inspection, and evidence-backed status changes;
- user story and test case lifecycle commands for behavior-facing TDD/BDD loops;
- task/backlog CRUD, reasoned status changes, and guarded dependency links;
- workflow run creation from static templates;
- agent job prompts, filtered inspection, adapter commands, completion/failure/cancellation;
- local agent registry plus explicit job assignment, lease, heartbeat, release, and reap commands;
- documented agent adapter command contract;
- hardened Codex CLI adapter command template;
- hardened Claude Code manual adapter instructions;
- generic shell adapter command template;
- read-only context packs for focused agent handoff;
- explainable code context indexing, lexical code search, impact receipts, and retrieval evaluation;
- validated agent output ingestion as evidence;
- job-centric evidence linkage for ingested agent output;
- verification recording;
- context receipt suggestion feedback and read-only feedback stats;
- structured `rubric/v1` verification metadata with inline/file recording and read-only inspection;
- workflow run, goal, defect, escalation, and decision lifecycle commands;
- escalation/decision linkage;
- checkpoint review commands for commit/package, UX checklist, and next-priority pauses;
- task-aware `pcl next` routing for goal-linked backlog items with satisfied dependencies;
- 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;
- consolidated `human_decisions` dashboard data plus localized English/Japanese dashboard HTML chrome;
- 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, guarded host-process 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
...
agent-tasks/0062-task-backlog-entity.md
agent-tasks/0063-structured-verification-rubric.md
agent-tasks/0064-task-loop-integration.md
agent-tasks/0065-dashboard-human-decisions.md
agent-tasks/0066-agent-registry-lease.md
agent-tasks/0067-context-pack-improvements.md
agent-tasks/0068-context-token-estimator.md
agent-tasks/0069-explainable-code-context-v0.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.
