project-loop-harness 0.3.0__tar.gz → 0.3.1__tar.gz

{project_loop_harness-0.3.0/src/project_loop_harness.egg-info → project_loop_harness-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-loop-harness
-Version: 0.3.0
+Version: 0.3.1
 Summary: Local control plane for agentic project development loops
 Author: Project Loop Harness Contributors
 License: MIT
@@ -269,6 +269,33 @@ evidence. Receipts use the fields `included_candidate_context`, `omitted`, and
 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:

{project_loop_harness-0.3.0 → project_loop_harness-0.3.1}/README.md

@@ -237,6 +237,33 @@ evidence. Receipts use the fields `included_candidate_context`, `omitted`, and
 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:

project_loop_harness-0.3.1/agent-tasks/0116-receipt-link-agreement-validation.md

@@ -0,0 +1,163 @@
+# 0116: Target-bound receipt / link agreement validation
+
+Milestone: v0.3.1 Handoff Integrity + Operator Experience
+Priority: P1
+Area: context/validation
+Origin: third-party v0.3.0 post-release review (P1①). Sakamoto approved the
+recommended plan 2026-07-09 (integrity pair 0116+0117 first).
+
+## Problem
+
+v0.3.0 selects a target-bound code-context receipt purely from the
+`evidence_links` routing row plus the evidence type. `_select_code_context_receipt_ref`
+(`context.py:780-791`) reads `newest_linked_evidence_id(... link_role="code_context")`,
+loads the evidence row, checks only `evidence_type == context_receipt`, and returns
+`"target_bound"`. Downstream, `_latest_code_context_summary` (`context.py:725-751`)
+loads the receipt artifact but **never compares the artifact's `target_binding`
+to the requested pack target**, and `_code_context_relevance` (`context.py:857`)
+stamps `scope: target_bound` from `selection_scope` alone. Strict validation
+(`_validate_evidence_links`, `validators.py:621-659`) only checks dangling links
+(evidence row exists; `target_id` exists in `tasks`/`agent_jobs`); it does not
+read the artifact binding either.
+
+On the normal write path this cannot break: 0108 writes the `evidence_links`
+row and the artifact `target_binding` in one transaction with the same target,
+and inserts the `code_context` link **only when `target_binding is not None`**
+(`code_context/receipts.py:123-129`). But a hand-edited DB, a future writer bug,
+a migration accident, or raw SQL can leave the link routing a receipt whose
+artifact binding names a *different* target. Today that receipt would surface as
+`scope: target_bound` for the wrong target — the exact "target-bound label that
+lies" failure this milestone must foreclose.
+
+This is defense-in-depth / corruption resilience, not a normal-path bug. The
+guarantee to establish: **nothing is ever reported as `target_bound` unless the
+selected receipt artifact's own `target_binding` agrees with the requested
+target.**
+
+## Scope
+
+### 1. Agreement predicate (single reusable helper)
+
+Add one pure helper (in `context.py`, or a small shared location `pcl context
+check` (0119) can also import — do not duplicate this logic later):
+
+```python
+def _receipt_target_binding_agrees(
+    receipt_payload: dict[str, Any], *, target_type: str, target_id: str
+) -> bool:
+    binding = receipt_payload.get("target_binding")
+    if not isinstance(binding, dict):
+        return False  # a code_context-linked artifact with no binding is anomalous
+    return (
+        str(binding.get("target_type")) == target_type
+        and str(binding.get("target_id")) == target_id
+    )
+```
+
+Missing / non-dict `target_binding` on a receipt reached through a `code_context`
+link counts as **disagreement** (per the 0108 invariant such a link always has a
+binding, so its absence is corruption).
+
+### 2. Read-side guard in selection
+
+In `_select_code_context_receipt_ref`, after obtaining the candidate
+`receipt_ref` from the link and confirming `evidence_type == context_receipt`,
+load the receipt artifact (reuse `resolve_context_receipt_path` +
+`json.loads`, both already used at `context.py:725-727`):
+
+- **Artifact load fails** (OSError / JSONDecodeError / not a dict): NOT a
+  mismatch. Preserve current behavior — return `(_public_receipt_ref(...),
+  "target_bound")` and let `_latest_code_context_summary` render
+  `receipt_unavailable`. (Unreadable ≠ disagreement; do not turn transient FS
+  errors into mismatches.)
+- **Artifact loads and binding agrees**: return `(ref, "target_bound")` (today's
+  happy path, unchanged).
+- **Artifact loads and binding disagrees** (including missing/blank binding):
+  MISMATCH.
+  - `require_bound_receipt=True` → raise a new distinct
+    `ContextPackBoundReceiptMismatchError` (see §3). Do **not** raise the
+    existing `...RequiredError` — the operator must be able to tell "corrupt
+    binding" from "no receipt".
+  - `require_bound_receipt=False` → skip this receipt and fall through to the
+    existing `latest_context_receipt_ref` path, returning `"unscoped_latest"`
+    (or `"missing_receipt"` if none). It MUST NOT return `"target_bound"`.
+    SHOULD: surface that a mismatched bound link was skipped in the
+    `unscoped_latest` relevance `warning` (distinct wording from plain "no
+    target-bound receipt found"); if threading a flag is awkward, the MUST
+    (never `target_bound`) is sufficient for this task.
+
+### 3. New typed error
+
+Add `ContextPackBoundReceiptMismatchError(PclError)` modeled on
+`ContextPackBoundReceiptRequiredError` (`context.py:47-58`):
+
+- `code = "context_pack_bound_receipt_mismatch"`, `exit_code = EXIT_USAGE`.
+- `message`: names the target and that a linked receipt's binding disagrees.
+- `details`: `target_type`, `target_id`, the offending `evidence_id`, the
+  artifact's claimed `target_binding` (as read), and
+  `suggested_refresh_commands = [_target_refresh_command(target_type, target_id)]`.
+
+### 4. Strict-validation agreement check
+
+Thread `ProjectPaths` into the evidence-links validation (`validate_project`
+already has `paths` at `validators.py:110`; update the call site
+`_validate_evidence_links(conn, result)` at `validators.py:266`). For each
+`evidence_links` row with `link_role == "code_context"` and a **known**
+`target_type`:
+
+- Resolve the receipt artifact via `evidence_ref_by_id(paths, evidence_id)` +
+  `resolve_context_receipt_path`.
+- If the artifact is **readable** and its `target_binding` disagrees with the
+  row's `(target_type, target_id)` (using the §1 predicate), `result.add_error`
+  with a message naming the link, the row target, and the artifact's claimed
+  binding.
+- If the artifact is **missing/unreadable**, add no new error here (existing
+  evidence-health / dangling checks own that surface; avoid double-reporting).
+
+Only `code_context` links are checked (supporting links have no artifact
+binding). Unknown `target_type` stays tolerated (no error), as in 0113.
+
+## Invariants (what to protect, on the normal paths)
+
+- Normal-path target-bound selection and output are byte-for-byte unchanged: a
+  receipt whose artifact binding matches keeps `scope: target_bound` /
+  `binding_strength: caller_asserted` and the same `receipt_ref`.
+- No new claim vocabulary. Binding stays `caller_asserted`; no
+  `verified_relevant` / `safe_to_continue` / `agent_read` / semantic wording.
+  A mismatch error states a *fact* ("the routing row and the artifact binding
+  disagree"), never a judgment about relevance.
+- `pcl` remains the only mutation path; this task adds read-side checks only and
+  writes nothing.
+- Additive: no schema change (schema stays 7), no migration, no new table or
+  column. `require_human_approval: database_migration` does NOT apply.
+
+## Non-scope
+
+- `pcl context check` (0119) — it will import the §1 predicate; do not build the
+  command here.
+- Auto-repair / re-linking of a mismatched link. Detection and safe refusal
+  only; never mutate `evidence_links` to "fix" a mismatch.
+- Any change to the 0108 write path (it is already correct and atomic).
+- Markdown refresh-command wording (that is 0117).
+
+## Acceptance
+
+- New helper is unit-tested: agrees on matching binding; disagrees on
+  mismatched target, on missing `target_binding`, and on non-dict payload.
+- Contract fixture added (extend the 0115 code-context contract set): an
+  `evidence_links` `code_context` row pointing at target A while the artifact
+  `target_binding` names target B —
+  - `--require-bound-receipt` → error
+    `context_pack_bound_receipt_mismatch` (not `..._required`);
+  - default (no require) → `code_context.relevance.scope` is `unscoped_latest`
+    or `missing_receipt`, **never** `target_bound`.
+- `validate --strict --json` reports the hand-built mismatch row as an error;
+  an agreeing `code_context` row and any `supporting` row produce no new error;
+  an unknown `target_type` row is still tolerated.
+- All existing target-bound / require / unscoped tests stay green (normal path
+  unaffected).
+- Full `pytest` green; live smoke in a scratch project proving: a normal
+  `impact --for-task` + `context pack --require-bound-receipt` still selects
+  `target_bound`, and a deliberately corrupted link (built through `pcl`-created
+  state, then the `.db` row's `target_id` diverged for the test only) yields the
+  mismatch error under `--require-bound-receipt` and `unscoped_latest` without.

project_loop_harness-0.3.1/agent-tasks/0117-markdown-target-refresh-command.md

@@ -0,0 +1,76 @@
+# 0117: Target-specific refresh command in code-context Markdown
+
+Milestone: v0.3.1 Handoff Integrity + Operator Experience
+Priority: P1
+Area: context/markdown
+Origin: third-party v0.3.0 post-release review (P1②). Sakamoto approved the
+recommended plan 2026-07-09 (integrity pair 0116+0117 first).
+
+## Problem
+
+The JSON context pack exposes a target-specific refresh command
+(`suggested_refresh_commands` ends with `pcl impact --diff --for-task T-XXXX
+--json` / `--for-job J-XXXX --json`; see `context.py:313,431` and the JSON tests
+at `tests/test_context.py:1626,1660,1694`). But the **Markdown** safety section
+`_render_code_context_safety_section` (`context.py:1001-1027`) hardcodes a
+generic line in both the `missing_receipt` and `receipt_unavailable` branches:
+
+```
+Next action: `pcl index build --json`, then `pcl impact --diff --json`.
+```
+
+An agent reading the Markdown pack (many workers read Markdown, not JSON) is told
+to run the **unbound** `pcl impact --diff --json`, which produces an unbound
+receipt — the exact anti-pattern v0.3.0's target binding exists to prevent. The
+stamped `summary` already carries the target: `relevance.target_id`,
+target-specific `next_actions` (set for `missing_receipt` in
+`_stamp_code_context_pack_facts`, `context.py:827-831`), and a target-rewritten
+`refresh_replay` (`_target_refresh_replay`). The Markdown renderer simply ignores
+them.
+
+## Scope
+
+1. In `_render_code_context_safety_section`, replace the hardcoded generic
+   "Next action" line in **both** the `missing_receipt` and `receipt_unavailable`
+   branches with commands derived from the **same** target-specific source the
+   JSON uses: `recommended_refresh_commands(summary)` (already imported into
+   `context.py:12`). Render them as the "Next action" line so Markdown and JSON
+   cannot diverge.
+2. Establish the invariant explicitly: **the Markdown safety "Next action"
+   commands equal the JSON `suggested_refresh_commands`** for the same pack.
+   Whatever list drives `pack["suggested_refresh_commands"]` must be what the
+   Markdown line renders — one source, two renderings.
+3. If `recommended_refresh_commands(summary)` is empty for some state, fall back
+   to the prior generic text (do not crash / emit an empty line); target-bound
+   states are the ones that matter here.
+
+## Invariants (what to protect)
+
+- No behavioral change to the JSON pack; only the Markdown string changes.
+- For a task pack the rendered command contains `--for-task <task_id>`; for a job
+  pack, `--for-job <job_id>`. The `pcl index build --json` prelude is preserved
+  if it is part of `recommended_refresh_commands`.
+- `## Code Context Safety` heading and the surrounding "Receipt selection and
+  freshness facts" lines are unchanged.
+- No new claim vocabulary; this is a command-string fix only.
+
+## Non-scope
+
+- Read-side agreement / mismatch handling (0116).
+- JSON `suggested_refresh_commands` (already target-specific).
+- Any change to `recommended_refresh_commands` / `refresh_replay` themselves.
+
+## Acceptance
+
+- New/updated test on the **Markdown**: for a `missing_receipt` task pack the
+  safety section contains `pcl impact --diff --for-task T-XXXX --json` and does
+  **not** contain a bare `pcl impact --diff --json` line; the job pack variant
+  contains `--for-job J-XXXX`. Add the equivalent assertion for the
+  `receipt_unavailable` branch.
+- A test asserts the equivalence invariant: the Markdown safety "Next action"
+  commands match `pack["suggested_refresh_commands"]` for the same pack.
+- Existing `"## Code Context Safety" in pack["markdown"]` assertions
+  (`tests/test_context.py:1076,1528,1896` etc.) stay green.
+- Full `pytest` green; live smoke: a `context pack --task T-XXXX
+  --include-code-context` with no receipt shows the target-specific command in
+  the rendered Markdown.

project_loop_harness-0.3.1/agent-tasks/0118-canonical-target-bound-handoff-docs.md

@@ -0,0 +1,64 @@
+# 0118: Canonical target-bound handoff docs (README + adoption)
+
+Milestone: v0.3.1 Handoff Integrity + Operator Experience
+Priority: P1
+Area: docs
+Origin: third-party v0.3.0 post-release review (P1③ — README does not surface
+v0.3's canonical `--require-bound-receipt` flow). Sakamoto approved 2026-07-09.
+Implemented by the orchestrator (opus) directly, not delegated — README/adoption
+copy is user-facing, where taste matters more than throughput.
+
+## Problem
+
+v0.3.0's headline value is the target-bound context pack, gated by
+`pcl context pack --include-code-context --require-bound-receipt`. But the README
+front door (`## Context Packs`, `## Explainable Code Context`) shows only the
+basic `pcl context pack --task ...` and `pcl impact --diff --json` forms, so a
+first-time reader never sees the canonical strict handoff. `grep` on README for
+`--require-bound-receipt` / `--for-task` / `--include-code-context` returns zero.
+
+## Scope (orchestrator-owned files only)
+
+Disjoint from 0119 (which owns `src/`, `tests/`, and the new
+`docs/context-check.md`). This task edits only:
+
+- `README.md`: add a short "Target-bound agent handoff (v0.3)" subsection near
+  `## Context Packs` / `## Explainable Code Context` showing the canonical
+  command for a task and a job:
+  ```
+  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
+  ```
+  State plainly: with `--require-bound-receipt` the pack fails
+  (`context_pack_bound_receipt_required`) instead of silently using an unrelated
+  latest receipt; binding is a caller assertion (`caller_asserted`), not a
+  relevance proof.
+- `docs/context-pack.md`: mark `--require-bound-receipt` as the canonical strict
+  handoff path for worker handoffs.
+- `docs/code-context.md`: add a short "review/continuation vs pre-work" boundary
+  note — receipts are built from `pcl impact --diff`, so a target-bound receipt
+  presumes a diff exists; pre-implementation handoff is a separate future path.
+- `docs/adoption-guide.md`: add the worker-handoff command as the recommended
+  default.
+
+## Invariants (what to protect)
+
+- Docs only. No `src/`, no `tests/`, no schema, no behavior change.
+- Every command shown must be one that actually exists and works in v0.3.0
+  (verify by running each in a scratch repo before claiming it).
+- Do not document `pcl context check` here — it does not exist until 0119 merges
+  (a follow-up may cross-link once both are in).
+- Keep the epistemic framing: no "safe"/"verified"/"understood" language; the
+  pack records that a receipt was created for a target, not that it is
+  sufficient.
+
+## Acceptance
+
+- README contains the canonical task and job handoff commands and the
+  `--require-bound-receipt` semantics; `grep` for `--require-bound-receipt` in
+  README is non-empty.
+- The three docs carry the canonical-path / boundary notes.
+- Each shown command verified against a live scratch repo (paste evidence in the
+  commit or handoff).
+- No code or test files changed.

project_loop_harness-0.3.1/agent-tasks/0119-context-check-preflight.md

@@ -0,0 +1,145 @@
+# 0119: `pcl context check` — read-only target-bound handoff preflight
+
+Milestone: v0.3.1 Handoff Integrity + Operator Experience
+Priority: P1
+Area: cli/context
+Origin: third-party v0.2.4 + v0.3.0 reviews (context-check deferred to v0.3.1);
+Sakamoto approved starting 0118+0119 together 2026-07-09. Builds on 0116.
+
+## Problem
+
+Today an operator or agent only learns whether a target has a usable
+target-bound code-context receipt by *running* `pcl context pack
+--include-code-context --require-bound-receipt` and reading the error, or by
+inspecting `relevance.scope` in a full pack. There is no cheap, read-only
+preflight that answers, for a task or job: is there a target-bound code-context
+receipt, is it the corrupt (mismatched) kind, how much supporting evidence is
+linked, and what is the exact canonical command to produce a bound handoff.
+
+Add `pcl context check`: a **read-only** diagnostic that reports these facts and
+the next command, without mutating anything and without running `index build` or
+`impact`.
+
+## Scope
+
+### CLI
+Add a sibling of `context pack` under the existing `context` subparser
+(`cli.py:587-589`):
+
+```
+pcl context check (--task T-XXXX | --job J-XXXX) [--json] [--require-bound-receipt]
+```
+
+- `--task` / `--job` are a required mutually-exclusive group (mirror
+  `context pack`, `cli.py:590-592`).
+- `--require-bound-receipt`: optional; changes exit behavior (see Exit codes).
+- Dispatch under `if args.command == "context" and args.context_command ==
+  "check":` next to the `pack` handler (`cli.py:1923`). Emit
+  `_print_json({"ok": True, "context_check": payload})` for `--json`, else a
+  short factual text summary.
+
+### Behavior (read-only)
+Implement a `context_check_for_task` / `context_check_for_job` (or one
+`check_context(paths, *, target_type, target_id, ...)`) in `context.py` that:
+
+1. Validates the target id shape and existence by reusing the impact validators
+   `_validate_target_id_shape` + `_require_existing_target`
+   (`code_context/impact.py`) so a bad/absent target raises the same typed
+   `ImpactTargetError` (`impact_target_invalid` / not-found) as `impact
+   --for-task`. Do not invent a new not-found error.
+2. Determines the target-bound code-context status by reusing 0116 machinery,
+   read-only:
+   - `newest_linked_evidence_id(conn, target_type, target_id,
+     link_role="code_context")`;
+   - if found and the evidence row is a `context_receipt`, load the artifact and
+     apply `_receipt_target_binding_agrees` (from `context_binding.py`):
+     agree -> `status: "present"`; disagree/missing-binding -> `status:
+     "mismatched"`; artifact unreadable -> `status: "present"` is NOT claimed —
+     report `status: "unavailable"` (cannot confirm agreement) rather than
+     asserting a bound receipt;
+   - if no `code_context` link -> `status: "missing"`.
+3. Counts supporting evidence: number of `evidence_links` rows for
+   `(target_type, target_id, link_role="supporting")` (a `SELECT COUNT` read;
+   the existing supporting-link query is at `context.py:1419`). SELECT-only reads
+   are allowed; this task writes nothing.
+
+### Output payload (`context_check`)
+Factual fields only:
+- `target`: `{ "type": "task"|"agent_job", "id": "T-XXXX" }`
+- `supporting_evidence_count`: int
+- `target_bound_code_context`: `{ "status": "present"|"missing"|"mismatched"|
+  "unavailable", "receipt_ref"?: {"evidence_id","created_at"},
+  "claimed_target_binding"?: <on mismatched> }`
+- `canonical_context_pack_command`: the exact command a caller should run for a
+  strict bound handoff, e.g.
+  `pcl context pack --task T-XXXX --include-code-context --require-bound-receipt
+  --json` (job variant with `--job`).
+- `recommended_refresh_command`: `_target_refresh_command(target_type,
+  target_id)` — present when status is `missing`/`mismatched`/`unavailable`.
+- `warnings`: list of factual strings (e.g. `"No target-bound code context
+  receipt exists for this task."`, `"A code_context link disagrees with its
+  artifact binding."`).
+
+### Exit codes
+- Default (no `--require-bound-receipt`): the diagnostic itself succeeded ->
+  exit 0, status in payload, even when `status != present`.
+- Bad/absent target: typed `ImpactTargetError` -> exit 2 (existing behavior).
+- With `--require-bound-receipt`: exit 2 when `status != present`, raising the
+  SAME typed errors as `context pack` for scriptable parity —
+  `context_pack_bound_receipt_required` for `missing`/`unavailable`,
+  `context_pack_bound_receipt_mismatch` for `mismatched`. (Reuse the existing
+  error classes from `context.py`.)
+
+## Invariants (what to protect)
+
+- **Read-only.** `context check` MUST NOT run `index build`, MUST NOT run
+  `impact`, and MUST NOT write any evidence row, event, `evidence_links` row, or
+  artifact. It only does SELECT reads and reads a receipt artifact file. A test
+  MUST assert row/event/adhoc-file counts are identical before and after.
+- **Epistemic discipline (hard).** Report facts about *what exists*, never a
+  sufficiency/safety/relevance judgment. Do NOT add `ready_for_handoff`,
+  `safe_to_continue`, `safe_to_run`, `verified_relevant`, `agent_read`,
+  `semantic_match`, or any go/no-go or cognition field — **even though the
+  originating third-party review sketched `ready_for_handoff`, we deliberately do
+  not adopt it.** `binding_strength` stays `caller_asserted` where surfaced. A
+  test MUST assert these forbidden keys are absent from the JSON.
+- Additive: no schema change, no migration, no new table/column. No change to
+  `context pack` behavior or output.
+- `pcl` stays the only mutation interface; this command mutates nothing.
+
+## Non-scope
+
+- README / adoption-guide / `docs/context-pack.md` / `docs/code-context.md`
+  edits — those belong to **0118** (disjoint ownership; do not touch them). If a
+  command-surface contract test or doc must be updated to register the new
+  subcommand and it is one of those four files, STOP and report the conflict
+  instead of editing it.
+- `pcl context prepare` / pre-work context synthesis (v0.4).
+- Any staleness scoring beyond echoing the receipt `created_at` (no new age
+  policy; you may include an age in seconds computed from an injected `now`, but
+  it is optional).
+- Auto-running refresh or repairing a mismatch.
+
+## Acceptance
+
+- `pcl context check --task T-XXXX --json` on a task with a matching bound
+  receipt -> `status: present`, `receipt_ref` populated, `supporting_evidence_count`
+  correct, `canonical_context_pack_command` present, exit 0.
+- Missing bound receipt -> `status: missing`, `recommended_refresh_command`
+  target-specific, exit 0; with `--require-bound-receipt` -> exit 2 and
+  `context_pack_bound_receipt_required`.
+- Mismatched link (as built by the 0116 contract fixture pattern) -> `status:
+  mismatched`, exit 0; with `--require-bound-receipt` -> exit 2 and
+  `context_pack_bound_receipt_mismatch`.
+- Job variant works symmetrically.
+- Bad/absent target id -> typed error, exit 2.
+- Read-only proof test: evidence/event/adhoc-file counts unchanged across a
+  `context check` invocation.
+- Forbidden-key test: `ready_for_handoff` / `safe_*` / `verified_relevant` /
+  `agent_read` / `semantic_match` absent from the payload.
+- New `docs/context-check.md` documents the command (read-only, the four status
+  values, the canonical command, exit-code behavior).
+- `ruff` clean; full `pytest` green (v0.3.1 baseline 488; expect > 488).
+- Live smoke (`python -m pcl` in a fresh scratch repo): build a bound receipt,
+  `context check` -> present; a second task with none -> missing (+ exit 2 under
+  `--require-bound-receipt`); paste the JSON for both.

project_loop_harness-0.3.1/agent-tasks/0120-pcl-finish-terminal-closeout.md

@@ -0,0 +1,140 @@
+# 0120: `pcl finish` — terminal close-out planner (safe first slice)
+
+Milestone: v0.3.1 Handoff Integrity + Operator Experience
+Priority: P1
+Area: cli/loop
+Origin: ax1-moc1 agent feedback F7 ("終端処理の認知負荷が実装より重い");
+growth-plan v0.3.1 Operator Experience. Sakamoto approved proceeding 2026-07-09.
+
+## Problem
+
+Closing out a loop is a long, easy-to-misorder sequence (Golden Path):
+`pcl jobs complete` (per job) -> `pcl verification record` -> `pcl loop
+complete` -> `pcl goal close` -> `pcl validate --strict` -> `pcl report` ->
+`pcl render`. The cognitive load of knowing *what to run, in what order, and
+what still blocks closure* is heavier than the work itself. There is no single
+command that answers "what is left to finish this, and what needs my decision."
+
+Add `pcl finish`: a terminal close-out **planner** that computes the ordered
+remaining steps for the active run and its goal, classifies each, and — only
+when asked — runs the safe generation tail. It never fabricates a completion,
+verification, or closure.
+
+## Design boundary (non-negotiable)
+
+`pcl finish` MUST NOT assert state on the human's behalf. It never records a
+verification, completes a job, completes/fails a run, or closes a goal or
+defect. Those are all `safe_to_run=False` / `requires_human` steps in the
+existing `next_action` model; `finish` plans them and hands them back as
+explicit commands. `finish --execute` runs ONLY `safe_to_run=True` generation
+(`pcl validate --strict`, `pcl render`), and only once no state-transition step
+remains. This keeps `finish` inside PLH's epistemic discipline: it organizes and
+reports, it does not claim work is done.
+
+## Scope
+
+### CLI
+Add a top-level `pcl finish [--json] [--execute]` (sibling of `pcl next`).
+Optional `--run WR-XXXX` / `--goal G-XXXX` to target explicitly; default is
+auto-detect (below). Dispatch in `cli.py` next to the `next` handler; emit
+`_print_json({"ok": True, "finish": payload})` for `--json`, else a short
+ordered text summary.
+
+### Target detection (reuse existing state model, read-only)
+- Auto-detect the active run exactly as `_active_workflow_next_action`
+  (`commands.py:1302`) does: newest `workflow_runs` row with status in
+  `ACTIVE_RUN_STATUSES`. Its `goal_id` is the goal in scope.
+- If no active run: fall back to the newest open goal from `loop_status`
+  (`commands.py:309`). If neither exists, return a `finished`/nothing-to-do
+  payload (idempotent), not an error.
+
+### Plan (the core, read-only)
+Compute the ordered remaining close-out steps and classify each. Reuse the
+existing ladder in `_active_workflow_next_action` for the run portion — do not
+reinvent it — extracting the same step dicts (`type`, `command`, `reason`,
+`requires_human`, `safe_to_run`, produced by `build_next_action`,
+`commands.py:340`). Steps, in order:
+1. Run close-out ladder (reuse `_active_workflow_next_action` semantics /
+   `_job_status_counts`): `continue_workflow` (active jobs remain) ->
+   `resolve_workflow_failure` (failed/cancelled jobs) -> `record_verification`
+   (all jobs terminal, no approved verification; `requires_human=True`) ->
+   `complete_workflow` (approved verification exists).
+2. `close_goal`: if the run's goal is not yet `closed`/`cancelled` and the run
+   is (or becomes) passed, the remaining step is
+   `pcl goal close {goal_id} --summary '...' --verification {verification_id}`
+   (`requires_human=True`, `safe_to_run=False`). Include the approved
+   `verification_id` when known.
+3. Generation tail (only listed as remaining when steps 1-2 are all done):
+   `pcl validate --strict` and `pcl render` (`safe_to_run=True`,
+   `requires_human=False`). These are read-only / idempotent regeneration.
+
+Payload:
+```
+{
+  "target": {"run": "WR-XXXX"|null, "goal": "G-XXXX"|null},
+  "finished": bool,                  # true when no state-transition step remains
+  "remaining_steps": [ {type, command, reason, requires_human, safe_to_run} ],
+  "next_command": "<first remaining step command>"|null,
+  "executed": [ {command, ok} ],     # only with --execute
+  "changed": bool                    # only with --execute
+}
+```
+
+### `--execute` (safe tail only)
+- If any `safe_to_run=False` step remains (jobs/verification/run/goal
+  assertions): run NOTHING, return the plan, `changed: false`, `next_command`
+  set. (You cannot safely generate from non-final state, and you must never run
+  the assertion.)
+- If no `safe_to_run=False` step remains: run the generation tail
+  (`validate --strict`, then `render`) in order, capture each in `executed`,
+  set `changed: true` if anything ran. `finished: true`.
+- Idempotent: a fully-closed, already-generated loop re-run with `--execute`
+  reports `finished: true`, `remaining_steps: []`. Regenerating render is
+  acceptable; do not error and do not assert anything.
+
+## Invariants (what to protect)
+
+- `finish` writes NO loop state itself: no verification, job completion, run
+  complete/fail, goal/defect close. It only ever *invokes* the existing safe
+  read-only generators (`validate`, `render`) under `--execute`, and otherwise
+  reads. A test MUST assert that a plan (no `--execute`) changes no rows/events,
+  and that `--execute` with a pending assertion changes no rows/events.
+- Reuse the existing `requires_human` / `safe_to_run` classification from the
+  `next_action` machinery; do not invent a parallel policy. `finish`'s per-step
+  flags must match what `pcl next` reports for the same step.
+- No new claim vocabulary. `finish` states facts ("all jobs terminal; no
+  approved verification exists; next: record verification") — never that work is
+  correct, sufficient, or safe.
+- Additive: no schema change, no migration.
+
+## Non-scope
+
+- Auto-completing evidenced jobs, auto-recording verifications, or auto-closing
+  goals (a possible future opt-in slice; NOT this task).
+- `report` generation in the tail (keep the tail to `validate` + `render`;
+  reports can be a later addition).
+- Feature-coverage / escalation / decision handling — `finish` is scoped to the
+  active run + its goal close-out, not the whole `next_action` priority ladder.
+- Localization (0121) and any human-gate wording changes.
+
+## Acceptance
+
+- Mid-run (`continue_workflow`): `pcl finish --json` lists the remaining ladder
+  with correct `requires_human`/`safe_to_run` per step, `next_command` = jobs
+  read/continue; `--execute` runs nothing (`changed:false`) because an assertion
+  is pending.
+- All jobs terminal, no verification: `next_command` = `verification record`,
+  step `requires_human:true`; `--execute` still runs nothing.
+- Run passed + verification approved, goal open: `next_command` = `goal close`
+  with the `--verification` id; `--execute` runs nothing.
+- Everything closed: `finished:true`, `remaining_steps:[]`; `--execute` runs
+  `validate --strict` then `render`, reports them in `executed`, `changed:true`;
+  a second `--execute` is idempotent.
+- Read-only proof test: a plan and a `--execute` with a pending assertion each
+  leave evidence/event/row counts unchanged.
+- No active run and no open goal: `finished:true`/nothing-to-do, exit 0, no
+  error.
+- `ruff` clean; full `pytest` green (v0.3.1 baseline 497; expect > 497).
+- New `docs/finish.md` (or a `## Finish` section in an existing loop doc, but do
+  not touch README / the 0118-owned docs). Live smoke (`python -m pcl`) pasting
+  the plan JSON at two ladder stages plus the closed-loop `--execute`.