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

{project_loop_harness-0.2.4/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.2.4
+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.2.4 → 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/0108-target-bound-code-context-receipts.md

@@ -0,0 +1,152 @@
+# 0108: Target-bound code context receipts
+
+Milestone: v0.3.0 Target-Bound Context
+Priority: P1
+Area: code-context/context-pack
+Origin: docs/growth-plan-v0.2.4-v0.5.md v0.3.0; docs/project-loop-harness-v0.2.3-third-party-review.md P2-3
+Depends on: 0113 (evidence_links table, migration 007) — merge first.
+
+> **Revision 2026-07-08 (坂本承認):** the original no-migration invariant is
+> **retracted**. Target binding is now persisted as a queryable `evidence_links`
+> row (`link_role="code_context"`, from 0113) **and** embedded in the receipt
+> artifact; receipt selection is a SQL query, not an artifact scan. This unblocks
+> `pcl context check` (v0.3.1) and v0.4 `bound_receipt_coverage` without a second
+> migration later.
+
+## Problem
+
+`pcl context pack --include-code-context` currently reads the latest
+`context_receipt` evidence row. The pack tells the reader that this is
+`scope: "unscoped_latest"` with `binding_strength: "none"`, which is honest,
+but it still risks handing a worker a receipt from an unrelated task or job.
+
+The existing docs reserve `scope: "target_bound"` and
+`binding_strength: "caller_asserted"`, but there is no command path that
+creates or requires such a receipt. v0.3.0 turns that reserved contract into a
+narrow, explicit handoff workflow, backed by queryable link state.
+
+## Scope
+
+1. Extend `pcl impact --diff` with explicit target flags:
+   - `--for-task T-XXXX`
+   - `--for-job J-XXXX`
+   Exactly zero or one target flag is allowed. Existing diff mode flags
+   (`--base`, `--staged`, `--unstaged`, `--include-untracked`,
+   `--all-changes`, and provided diff input) keep their current semantics.
+2. Validate the named target before writing a receipt. Missing or malformed
+   target IDs must fail with a typed error and must not create evidence or an
+   `evidence_links` row.
+3. When a target flag is present, record the binding in **two** places, in the
+   same transaction that writes the receipt evidence:
+   - An `evidence_links` row (0113 helper): `(evidence_id=<receipt>,
+     target_type, target_id, link_role="code_context", created_at)`, where
+     `target_type` is `task` or `agent_job`.
+   - Target binding metadata inside the `impact/v0` response and the
+     `context-receipt/v0` artifact so the receipt is self-describing:
+     ```json
+     {
+       "target_binding": {
+         "target_type": "task",
+         "target_id": "T-0001",
+         "binding_strength": "caller_asserted",
+         "source": "impact_flag"
+       }
+     }
+     ```
+     For job targets, use `target_type: "agent_job"`. The link row and the
+     artifact `target_binding` must agree.
+4. Update context-pack receipt selection when `--include-code-context` is used.
+   Selection is a **query on `evidence_links`** (0113 helper), not an artifact
+   scan:
+   - For a task pack, prefer the newest receipt evidence with a matching
+     `evidence_links` row `(target_type="task", target_id=<task>,
+     link_role="code_context")`.
+   - For a job pack, prefer the newest matching
+     `(target_type="agent_job", target_id=<job>, link_role="code_context")`.
+   - If no matching bound receipt exists, preserve the current unscoped latest
+     fallback unless the caller requires a bound receipt.
+5. Add `pcl context pack --require-bound-receipt`, valid only with
+   `--include-code-context`. When no matching bound receipt exists, fail with a
+   typed error `context_pack_bound_receipt_required` and include a
+   target-specific refresh suggestion:
+   - `pcl impact --diff --for-task T-XXXX --json`
+   - `pcl impact --diff --for-job J-XXXX --json`
+6. Update `code_context.relevance` in the embedded summary:
+   - Matching bound receipt: `scope: "target_bound"`,
+     `binding_strength: "caller_asserted"`, plus `target_type` and
+     `target_id`.
+   - Unbound fallback: keep `scope: "unscoped_latest"` and
+     `binding_strength: "none"` with an explicit warning.
+   - Missing receipt: keep `scope: "missing_receipt"` and
+     `binding_strength: "none"`.
+7. Update docs and CLI help for `docs/code-context.md`,
+   `docs/context-pack.md`, and relevant tests.
+
+## Invariants (what to protect, on the normal paths)
+
+- Binding is recorded in lockstep: when a target flag is given, the receipt
+  evidence row, its `evidence_links` `code_context` row, and the artifact
+  `target_binding` are written in one transaction and must agree. Never write
+  the link row without the receipt, or an artifact `target_binding` without the
+  link row.
+- Binding is a **caller assertion**, not PLH proof that the receipt is
+  semantically relevant. Use claims-not-facts vocabulary; do not add fields such
+  as `safe_to_continue`, `verified_relevant`, or `agent_read`.
+- Extend `impact/v0`, `context-receipt/v0`, and `context-pack/v1` **additively**
+  via the `code-context-summary/v0` insulation layer (0078). The pack embeds the
+  summary and `receipt_ref` (evidence_id / receipt_path) only — never the full
+  receipt body or copied evidence contents.
+- `pcl context pack` remains read-only: it must not run `pcl index build`,
+  `pcl impact`, Git commands, tests, or any artifact-generating command. It
+  reads `evidence_links` and evidence rows only.
+- `source_commands` remain read-only re-fetch commands. Artifact-generating
+  commands (`pcl impact …`) appear only under `suggested_refresh_commands`.
+- Existing unscoped latest behavior remains available when
+  `--require-bound-receipt` is absent.
+- Deterministic generated artifacts stay deterministic; timestamped facts remain
+  in receipt/evidence payloads where timestamps already exist.
+
+## Non-scope
+
+- Semantic or embedding-based relevance proof.
+- Automatic target inference from changed files, branches, or task text.
+- `pcl context pack --receipt ...` manual receipt selection.
+- `pcl receipt list` / `pcl evidence link` CLI verbs.
+- Dashboard redesign or MCP surface changes.
+- Hosted code analysis, cloud sync, telemetry, or external LLM calls.
+- `pcl context check` preflight (deferred to v0.3.1).
+
+## Acceptance
+
+- `pcl impact --diff --for-task T-0001 --json` writes a receipt with
+  `target_binding.target_type == "task"` and `target_id == "T-0001"`, and an
+  `evidence_links` row `(target_type="task", target_id="T-0001",
+  link_role="code_context")`.
+- `pcl impact --diff --for-job J-0001 --json` writes a receipt with
+  `target_binding.target_type == "agent_job"` and `target_id == "J-0001"`, and
+  the matching `code_context` link row.
+- Invalid target IDs and mutually exclusive target flags fail with typed errors
+  before any evidence or link row is created.
+- `pcl context pack --task T-0001 --include-code-context --json` chooses the
+  newest matching task-bound receipt over a newer unbound receipt, via the
+  `evidence_links` query.
+- `pcl context pack --job J-0001 --include-code-context --json` chooses the
+  newest matching job-bound receipt over a newer unbound receipt.
+- Without a matching bound receipt and without `--require-bound-receipt`,
+  context pack still succeeds with the existing unscoped latest warning and a
+  target-specific suggested refresh command.
+- With `--require-bound-receipt` and no matching bound receipt, context pack
+  fails with `context_pack_bound_receipt_required` and does not silently fall
+  back to unscoped latest.
+- `source_commands` for code-context packs still contain only read-only
+  commands; `pcl impact` appears only under `suggested_refresh_commands`.
+- Full `pytest` green.
+- Live smoke in a scratch project:
+  1. `pcl init`
+  2. create a goal and task
+  3. `pcl index build --json`
+  4. make a small tracked change
+  5. `pcl impact --diff --for-task T-0001 --json`
+  6. `pcl context pack --task T-0001 --include-code-context --require-bound-receipt --json`
+  7. `pcl validate --strict --json`
+  8. `pcl render --json`

project_loop_harness-0.3.1/agent-tasks/0113-evidence-links-table.md

@@ -0,0 +1,118 @@
+# 0113: Generic evidence links table (migration 007)
+
+Milestone: v0.3.0 Target-Bound Context
+Priority: P1
+Area: schema/evidence
+Origin: docs/growth-plan-v0.2.4-v0.5.md v0.3.0; third-party review 議題1 — migration
+approved and 0108 no-migration invariant retracted (Sakamoto approved 2026-07-08).
+
+## Problem
+
+Evidence-to-target linkage is currently a single `evidence.linked_task_id`
+column (migration 006), which can only express "supporting evidence for a
+task". v0.3.0 introduces a second link role — a code-context receipt bound
+to a task or job (0108) — and v0.3.2 will add master-trace / intent-index
+roles. A single typed column cannot express a role, and adding one column per
+target type (`linked_job_id`, `linked_goal_id`, and so on) sprawls.
+
+Introduce a generic, queryable `evidence_links` table so target-bound receipt
+selection (0108), `pcl context check` (v0.3.1), and v0.4 coverage KPIs become
+SQL queries rather than artifact scans. This is a control-plane primitive, not
+a per-feature column.
+
+## Scope
+
+1. Add migration `007_evidence_links.sql`:
+   ```sql
+   PRAGMA foreign_keys = ON;
+
+   CREATE TABLE IF NOT EXISTS evidence_links (
+     evidence_id TEXT NOT NULL REFERENCES evidence(id),
+     target_type TEXT NOT NULL,
+     target_id   TEXT NOT NULL,
+     link_role   TEXT NOT NULL,
+     created_at  TEXT NOT NULL,
+     PRIMARY KEY (evidence_id, target_type, target_id, link_role)
+   );
+
+   CREATE INDEX IF NOT EXISTS idx_evidence_links_target
+     ON evidence_links(target_type, target_id, link_role, created_at);
+
+   -- Backfill existing task-linked evidence as role 'supporting'.
+   INSERT OR IGNORE INTO evidence_links(evidence_id, target_type, target_id, link_role, created_at)
+   SELECT id, 'task', linked_task_id, 'supporting', created_at
+   FROM evidence
+   WHERE linked_task_id IS NOT NULL;
+   ```
+   Vocabulary in use now: `target_type` is `task` or `agent_job`;
+   `link_role` is `supporting` or `code_context`. Reserve (do not emit yet)
+   `goal` / `workflow_run` / `decision` / `escalation` and
+   `master_trace` / `intent_index` / `worker_output`.
+2. Write path: `pcl evidence add --task T-XXXX` (evidence.py) keeps setting the
+   `evidence.linked_task_id` column (0.x compat) and also inserts an
+   `evidence_links` row `(evidence_id, 'task', task_id, 'supporting', now)` in
+   the same transaction, before the existing `append_event`.
+3. Read path: `context.py._linked_task_evidence` selects from `evidence_links`
+   where `target_type='task' AND link_role='supporting'`, joined to `evidence`
+   for the display columns, ordered `created_at, evidence_id`. When the
+   `evidence_links` table is absent (pre-migration DB opened by a newer binary
+   mid-upgrade), fall back to the current `linked_task_id` column query. Output
+   shape, ordering, and member/stored-path resolution are unchanged.
+4. Strict validation (`validators.py`): add a dangling-link check modeled on the
+   verification `receipt_evidence_id` check (validators.py:596) — every
+   `evidence_links.evidence_id` must resolve to an existing evidence row (the
+   existing `PRAGMA foreign_key_check` already covers this; keep an explicit,
+   message-consistent check too), and for known target types the `target_id`
+   must exist (`task` maps to `tasks`, `agent_job` maps to `agent_jobs`).
+   Unknown `target_type` values are tolerated with no error (forward
+   compatibility).
+5. Provide two small internal helpers for 0108 to reuse (no new CLI surface):
+   insert a link row, and select the newest `evidence_id` for a given
+   `(target_type, target_id, link_role)`.
+
+## Invariants (what to protect, on the normal paths)
+
+- The canonical write path for a task-linked ad-hoc evidence is, in one
+  transaction: the `evidence` row plus the `linked_task_id` column plus the
+  `evidence_links` row plus the `adhoc_evidence_recorded` event. Do not drop the
+  `linked_task_id` column write (compat). Do not write an `evidence_links` row
+  without its mirroring `evidence` row.
+- The migration backfill is idempotent (`INSERT OR IGNORE`) and additive: it
+  must not update or delete any `evidence` row, and re-running `pcl migrate`
+  must be a no-op.
+- `evidence_links` is written only through `pcl` (evidence add today, 0108
+  tomorrow). No command deletes links in this task; no raw-SQL mutation path.
+- The existing task context-pack `linked_evidence` output — shape, ordering,
+  member/stored paths — is unchanged for existing DBs after backfill.
+- Additive only: no existing table or column is dropped or repurposed. Schema
+  version advances 6 to 7; `never-downgrade` and DB-ahead typed rejection (0076)
+  continue to hold.
+
+## Non-scope
+
+- `pcl evidence link` / `unlink` CLI verbs (links are written implicitly by
+  `evidence add` and, in 0108, by `impact --for-task/--for-job`).
+- Job / goal / decision linking commands beyond the helper 0108 needs.
+- Dashboard changes. The existing `heading_evidence_links` locale string is an
+  unrelated UI heading, not this table.
+- Removing or deprecating `linked_task_id` (deferred past 0.x).
+- Reading `evidence_links` from the code-context receipt selection path (that is
+  0108).
+
+## Acceptance
+
+- Fresh `pcl init` gives schema v7, `evidence_links` present,
+  `pcl validate --strict --json` green.
+- A v6 to v7 live migration backfills every `linked_task_id` row into
+  `evidence_links` as role `supporting`; backfilled row count equals the number
+  of non-null `linked_task_id` rows; a second `pcl migrate` changes nothing.
+- `pcl evidence add --task T-0001` writes both the column and the
+  `evidence_links` row; the task context pack lists the evidence identically to
+  before.
+- A hand-broken dangling link (an `evidence_links` row whose `target_type='task'`
+  `target_id` has no matching task) is reported by `validate --strict`; a row
+  with an unknown `target_type` is tolerated (no error).
+- An older (v6-aware) `pcl` binary typed-rejects a v7 DB with
+  `schema_version_ahead` (0076 behavior preserved).
+- Full `pytest` green; live smoke in a scratch project (`init`, then `evidence
+  add --task`, then `validate --strict`, then context pack).

project_loop_harness-0.3.1/agent-tasks/0114-source-hash-drift.md

@@ -0,0 +1,78 @@
+# 0114: Source hash drift detection for copied evidence
+
+Milestone: v0.3.0 Target-Bound Context
+Priority: P2
+Area: evidence
+Origin: docs/growth-plan-v0.2.4-v0.5.md 論点2; third-party review P1 / 議題2 —
+default-on approved (坂本承認 2026-07-08). Extends 0102.
+
+## Problem
+
+`_collect_copied_member_findings` in `src/pcl/evidence.py` (the source-freshness
+block at evidence.py:589-605) detects source drift only via `detail: "missing"`
+and `detail: "size_mismatch"`. A **same-size content change** to the source
+file is undetected: `source_drifted` never fires, so a copied evidence member
+whose origin was silently rewritten to a different-but-equal-length body reads
+as fresh. The recorded member `sha256` (`expected_sha256`) is already a
+parameter of this function (evidence.py:545) but is never compared against the
+current source.
+
+0102 already classifies `source_drifted` as an evidence-health **warning**, so
+closing this gap needs no health-model change — only the missing hash
+comparison.
+
+## Scope
+
+1. In `_collect_copied_member_findings`, extend the `else` branch that currently
+   only handles the size check: when the source exists **and**
+   `source_stat.st_size == size_bytes`, compute the source file sha256 (reuse
+   `_sha256_file`, evidence.py:907) and compare to `expected_sha256`.
+   - Mismatch → append `{"code": "source_drifted", "path": member_path,
+     "detail": "hash_mismatch"}`.
+   - `OSError` while reading the source → treat as unreadable and reuse the
+     existing `detail: "missing"` finding (do not crash, do not add a new code).
+2. Default-on, no `--deep` flag. The hash is computed **only** in the same-size
+   branch, so `missing` and `size_mismatch` stay the cheap fast paths. The
+   `copy_max_member_bytes` cap (10MB, 0097) bounds per-member cost.
+3. Confirm the `validators.py` `source_drifted` rendering branch (the
+   `elif code == "source_drifted":` branch, ~line 977) renders the new
+   `hash_mismatch` detail consistently through the shared
+   `assess_adhoc_evidence` path (0095 pattern) — health stays `warning`.
+
+## Invariants (what to protect, on the normal paths)
+
+- Read-only assessment: no finding rewrites or removes copied artifacts under
+  `.project-loop/evidence/adhoc-files/` or any source file.
+- Findings shape is additive-only: `source_drifted` gains one new `detail`
+  value, `hash_mismatch`. Existing `missing` / `size_mismatch` details, their
+  `path` field, and ordering are unchanged.
+- Copied-artifact health stays semantically **separate** from source freshness
+  in wording (0102 invariant): `copy_hash_mismatch` = the copied artifact broke;
+  `source_drifted/hash_mismatch` = the origin changed since the copy. Do not
+  merge or cross-reference the two codes.
+- Health stays the three-level `ok | warning | error`; no `artifact_health` /
+  `source_health` split (still deferred until dogfood `source_drift_rate` data).
+
+## Non-scope
+
+- A `--deep` / lightweight-vs-deep mode split (unnecessary: the size gate plus
+  the 10MB member cap already bound cost).
+- Hashing sources of **reference** (non-copied) members — reference members are
+  already hash-checked against the source directly by `_assess_reference_member`.
+- `artifact_health` / `source_health` field separation.
+
+## Acceptance
+
+- Test: copied artifact intact + source rewritten to different content of the
+  **same byte length** → `health: "warning"` with a `source_drifted` finding,
+  `detail: "hash_mismatch"`.
+- Test: copied artifact intact + source intact → `health: "ok"` (no regression).
+- Test: `copy_hash_mismatch` (artifact corrupted) + `source_drifted/hash_mismatch`
+  co-occur → still `warning`, both findings present, no double-count crash.
+- `pcl validate --strict --json` treats `source_drifted/hash_mismatch` as a
+  warning that remains a warning under strict (extend
+  `_strict_warning_remains_warning` coverage) and stays green overall.
+- Live smoke: in a scratch project, `evidence add --copy` a file, edit the
+  source to same-length different content, `pcl validate --strict --json` →
+  evidence health `warning`, detail `hash_mismatch`, strict `ok: true`.
+- Full `pytest` green; release note entry describing the tightened semantics.

project_loop_harness-0.3.1/agent-tasks/0115-context-pack-contract-fixtures.md

@@ -0,0 +1,72 @@
+# 0115: Context pack target-bound contract fixtures
+
+Milestone: v0.3.0 Target-Bound Context
+Priority: P2
+Area: context-pack/tests
+Origin: docs/growth-plan-v0.2.4-v0.5.md v0.3.0; third-party review 0111 —
+required in v0.3.0 (坂本承認 2026-07-08). Depends on 0108 and 0113.
+
+## Problem
+
+0108 changes the `context-pack/v1` code-context contract: `code_context.relevance`
+gains `scope: "target_bound"` / `binding_strength: "caller_asserted"` with
+`target_type` / `target_id`, a `receipt_ref`, a `--require-bound-receipt` typed
+error, and target-specific `suggested_refresh_commands`. PLH has shipped three
+contract regressions caught only in review (0087 git-status key loss, 0089
+audit-mirror break, 0090 receipt-content storage). Freeze the v0.3.0 handoff
+contract with deterministic fixture-based tests so future changes are provably
+additive and any silent shape change fails a test.
+
+## Scope
+
+Add fixture-backed tests covering six code-context selection states. Each
+fixture asserts `included_sections`, the required / non-droppable safety
+sections, `source_paths`, `suggested_refresh_commands`, and
+`code_context.relevance`:
+
+1. **no receipt** — `scope: "missing_receipt"`, `binding_strength: "none"`.
+2. **unscoped latest only** — a receipt with no `target_binding`;
+   `scope: "unscoped_latest"`, `binding_strength: "none"`, with the existing
+   unscoped warning and a target-specific suggested refresh command.
+3. **matching task-bound receipt** — `scope: "target_bound"`,
+   `binding_strength: "caller_asserted"`, `target_type: "task"`, `target_id`
+   set; chosen over a newer unbound receipt.
+4. **matching job-bound receipt** — same as (3) with `target_type: "agent_job"`.
+5. **stale bound receipt** — a matching bound receipt old enough that the 0082
+   `age_warning` fires; relevance stays `target_bound` and the age warning is
+   present (staleness is a surfaced fact, not a downgrade).
+6. **require-bound missing** — `--require-bound-receipt` with no matching bound
+   receipt → typed error `context_pack_bound_receipt_required` with the
+   target-specific refresh suggestion; assert there is **no** silent fallback to
+   unscoped latest.
+
+## Invariants (what to protect, on the normal paths)
+
+- Fixtures are byte-deterministic: inject `now` at the CLI boundary the way
+  existing pack tests do; no wall-clock reads inside generated artifacts.
+- Budget truncation never drops required safety sections: the
+  `code_context_safety` pin (priority 10000, 0078/0083) survives a deliberately
+  tight budget — at least one fixture asserts this.
+- Contract assertions are additive-only in spirit: adding a new field is
+  allowed; changing or removing an asserted field, shape, or ordering must fail
+  a fixture. Do not weaken an assertion to make a change pass.
+- Fixtures must not inline receipt bodies or copied evidence file contents
+  (0090 boundary): assert `receipt_ref` carries `evidence_id` / `receipt_path`
+  only.
+
+## Non-scope
+
+- Any new runtime behavior — this is a pure test / fixture task. If a fixture
+  reveals a 0108 defect, fix it in 0108, not here.
+- Dashboard, MCP, or CLI-surface changes.
+- Golden-file snapshotting of the entire pack (assert the contract-bearing
+  fields, not incidental whitespace).
+
+## Acceptance
+
+- Six fixtures committed and green.
+- A deliberate contract break (e.g., dropping `binding_strength` from
+  `relevance`, or letting `--require-bound-receipt` fall back silently) makes at
+  least one fixture fail with a clear message.
+- The tight-budget fixture proves the safety section is never truncated away.
+- Full `pytest` green.

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.