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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-loop-harness
-Version: 0.3.0
+Version: 0.3.3
 Summary: Local control plane for agentic project development loops
 Author: Project Loop Harness Contributors
 License: MIT
@@ -28,6 +28,8 @@ 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
@@ -95,7 +97,7 @@ The important separation is:
 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
+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
@@ -204,7 +206,7 @@ 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 workflow guard --root /tmp/pcl-demo --template executor_smoke --json
 pcl loop execute --root /tmp/pcl-demo executor_smoke --json
 ```
 
@@ -269,6 +271,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:
@@ -453,7 +482,7 @@ The current local runtime supports:
 - 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.
+- 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
 

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

@@ -63,7 +63,7 @@ The important separation is:
 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
+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
@@ -172,7 +172,7 @@ 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 workflow guard --root /tmp/pcl-demo --template executor_smoke --json
 pcl loop execute --root /tmp/pcl-demo executor_smoke --json
 ```
 
@@ -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:
@@ -421,7 +448,7 @@ The current local runtime supports:
 - 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.
+- 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
 

project_loop_harness-0.3.3/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.3/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.3/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.3/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.