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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-loop-harness
-Version: 0.2.4
+Version: 0.3.0
 Summary: Local control plane for agentic project development loops
 Author: Project Loop Harness Contributors
 License: MIT

project_loop_harness-0.3.0/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.0/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.0/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.0/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.2.4 → project_loop_harness-0.3.0}/agent-tasks/README.md

@@ -20,13 +20,20 @@ implement from the spec file, not from prompt summaries.
 | 0105 | Evidence copy observability | v0.2.4 Trust Patch | P2 | done |
 | 0106 | Release checklist contract | v0.2.4 Trust Patch | P2 | done (`docs/release-checklist.md`) |
 | 0107 | agent-tasks backlog index | v0.2.4 Trust Patch | P3 | done (this file) |
+| 0113 | Generic evidence_links table (migration 007) | v0.3.0 Target-Bound Context | P1 | spec ready |
+| 0108 | Target-bound code context receipts (sits on 0113) | v0.3.0 Target-Bound Context | P1 | spec ready |
+| 0114 | Source hash drift detection (default-on) | v0.3.0 Target-Bound Context | P2 | spec ready |
+| 0115 | Context pack target-bound contract fixtures | v0.3.0 Target-Bound Context | P2 | spec ready |
+
+v0.3.0 dispatch order: **0113 + 0114 in parallel** (independent; different
+`evidence.py` surfaces) → **0108** (needs 0113 merged) → **0115** (freezes the
+0108 contract).
 
 ## Planned next (see growth plan for scope)
 
 | Milestone | Theme |
 |---|---|
-| v0.3.0 | Target-bound code context receipts (`impact --for-task/--for-job`, `--require-bound-receipt`) |
-| v0.3.1 | Operator experience: `pcl finish` (F7), human-gate ja copy (F5), feature_coverage no-op (F4) |
+| v0.3.1 | Operator experience: `pcl finish` (F7), human-gate ja copy (F5), feature_coverage no-op (F4), `pcl context check` preflight |
 | v0.3.2 | Master trace / intent-index v0 contract formalization |
 | v0.4.0 | Dogfood operations + cost KPI measurement |
 | v0.5.0 | Adoption: README split, contract stability policy |

{project_loop_harness-0.2.4 → project_loop_harness-0.3.0}/docs/code-context.md

@@ -39,6 +39,8 @@ pcl impact --diff --staged --json
 pcl impact --diff --unstaged --json
 pcl impact --diff --include-untracked --json
 pcl impact --diff --all-changes --json
+pcl impact --diff --for-task T-0001 --json
+pcl impact --diff --for-job J-0001 --json
 git diff --no-ext-diff --no-textconv --name-status main -- | pcl impact --diff - --json
 ```
 
@@ -349,6 +351,12 @@ under `.project-loop/evidence/context-receipts/`.
     "omitted": [],
     "sensitive_omitted_count": 1,
     "staleness_warnings": [],
+    "target_binding": {
+      "target_type": "task",
+      "target_id": "T-0001",
+      "binding_strength": "caller_asserted",
+      "source": "impact_flag"
+    },
     "receipt_path": ".project-loop/evidence/context-receipts/e-0001-impact-v0.json",
     "evidence_id": "E-0001"
   }
@@ -409,6 +417,24 @@ operations for the selected mode, such as staging changes for `--staged`, using
 `--include-untracked` when untracked files are present, comparing against a
 default branch, or checking a provided diff.
 
+`--for-task T-XXXX` and `--for-job J-XXXX` bind a written context receipt to an
+existing task or agent job as a caller assertion. Exactly zero or one target
+flag is allowed. PLH validates the target before writing any receipt evidence.
+Malformed, missing, or mutually exclusive target flags return typed errors and
+do not create evidence rows, receipt artifacts, or `evidence_links` rows.
+
+When a target flag is present and the diff is non-empty, PLH records the
+binding in both durable query state and the self-describing receipt artifact:
+
+- `evidence_links(evidence_id, target_type, target_id, link_role="code_context")`
+- `target_binding` in the `impact/v0` response and the `context-receipt/v0`
+  artifact
+
+Task bindings use `target_type: "task"`. Job bindings use
+`target_type: "agent_job"`. The binding strength is always
+`caller_asserted`, with `source: "impact_flag"`. This is a caller label, not
+PLH proof that the receipt is semantically relevant to the target.
+
 The receipt contract is `context-receipt/v0`. Its core fields are:
 
 - `diff_source`: the same source label returned by `impact/v0`, with `base_ref`
@@ -426,6 +452,8 @@ The receipt contract is `context-receipt/v0`. Its core fields are:
   the working tree.
 - `untracked_included_count`: present only when the diff source explicitly
   includes untracked files.
+- `target_binding`: present only for receipts written with `--for-task` or
+  `--for-job`; it records the caller-asserted target label.
 
 Receipts are evidence artifacts. They record PLH output and reasons; they do
 not make claims about agent cognition. Verification suggestion objects carry
@@ -519,12 +547,16 @@ the receipt, so the refresh remains generic.
 
 ## Context Pack Bridge
 
-`pcl context pack --include-code-context` links the latest context receipt into
-normal task and job handoffs without inlining the receipt body.
+`pcl context pack --include-code-context` links a context receipt into normal
+task and job handoffs without inlining the receipt body.
 
-The context pack resolves the newest evidence row with type `context_receipt`,
-loads its JSON artifact, and converts it through a stable
-`code-context-summary/v0` isolation layer. The summary is embedded under
+For task and job packs, PLH first queries `evidence_links` for the newest
+matching row with `link_role: "code_context"` and the pack target
+(`target_type: "task"` or `"agent_job"`). When a matching bound receipt exists,
+that receipt is preferred over a newer unbound receipt. If no matching bound
+receipt exists, PLH keeps the unscoped-latest fallback unless the caller used
+`--require-bound-receipt`. The selected receipt artifact is converted through a
+stable `code-context-summary/v0` isolation layer. The summary is embedded under
 `context_pack.code_context`; the original receipt remains referenced by
 `receipt_ref.evidence_id`, `receipt_ref.receipt_path`, and the pack's
 `source_paths`.
@@ -564,7 +596,13 @@ listing.
 
 If no receipt exists, the command still returns a valid context pack with empty
 receipt refs, a message, and next actions: `pcl index build --json` followed by
-`pcl impact --diff --json`.
+a target-specific impact command such as
+`pcl impact --diff --for-task T-0001 --json`.
+
+`--require-bound-receipt` is valid only with `--include-code-context`. When no
+matching bound receipt exists, context pack fails with typed error
+`context_pack_bound_receipt_required` and suggests a target-specific refresh
+command. It does not fall back to the unscoped latest receipt in that mode.
 
 The bridge does not add schema, rebuild the index, run impact automatically,
 make continuation claims, or expose a `safe_to_continue` field.

{project_loop_harness-0.2.4 → project_loop_harness-0.3.0}/docs/context-pack.md

@@ -13,6 +13,7 @@ pcl context pack --job J-0001
 pcl context pack --job J-0001 --role verifier --max-tokens 12000 --json
 pcl context pack --task T-0001 --json
 pcl context pack --task T-0001 --include-code-context --json
+pcl context pack --task T-0001 --include-code-context --require-bound-receipt --json
 ```
 
 Exactly one of `--job` or `--task` is required.
@@ -75,12 +76,29 @@ treating model output as source of truth.
 
 `--include-code-context` is opt-in. Without the flag, context packs do not look
 for code-context receipts and keep the same v1 payload shape. With the flag,
-the pack resolves the latest `context_receipt` evidence row, loads that receipt
-artifact, and embeds only a stable `code-context-summary/v0` under
-`context_pack.code_context`. The receipt body is never inlined; it is referenced
-through `code_context.receipt_ref.evidence_id`,
+the pack first queries `evidence_links` for the newest receipt bound to the
+requested target with `link_role: "code_context"`:
+
+- task packs query `target_type: "task"` and the task id;
+- job packs query `target_type: "agent_job"` and the job id.
+
+When a matching bound receipt exists, it is preferred over a newer unbound
+receipt. If no matching bound receipt exists, the pack preserves the current
+unscoped-latest fallback unless `--require-bound-receipt` is set. The selected
+receipt artifact is loaded and embedded only as a stable
+`code-context-summary/v0` under `context_pack.code_context`. The receipt body is
+never inlined; it is referenced through
+`code_context.receipt_ref.evidence_id`,
 `code_context.receipt_ref.receipt_path`, and `source_paths`.
 
+`--require-bound-receipt` is valid only with `--include-code-context`. When no
+matching bound receipt exists, JSON mode returns `ok:false` with
+`error.code: "context_pack_bound_receipt_required"` and details that include a
+target-specific refresh command such as
+`pcl impact --diff --for-task T-0001 --json` or
+`pcl impact --diff --for-job J-0001 --json`. In this mode PLH does not silently
+fall back to the unscoped latest receipt.
+
 `source_commands` are read-only re-fetch commands. They are commands a reader
 can run to reproduce the inputs this pack was built from, and they must not
 create evidence rows, receipt artifacts, reports, exports, or other project
@@ -91,8 +109,10 @@ When `--include-code-context` is requested, the pack also includes a top-level
 `suggested_refresh_commands` field. These commands are artifact-regenerating
 suggestions for refreshing the underlying code-context evidence; they may
 create new evidence or artifacts. Stale or missing code context suggests
-`pcl index build --json` followed by `pcl impact --diff --json`; fresh code
-context suggests an impact refresh command.
+`pcl index build --json` followed by a target-specific impact command; fresh
+code context suggests a target-specific impact refresh command. These commands
+preserve replayable diff scope where possible and add `--for-task` or
+`--for-job` for the pack target.
 
 The embedded `code_context.refresh_replay` object explains how closely those
 refresh commands preserve the previous receipt scope:
@@ -127,19 +147,21 @@ keeps the command first and may append the ID at the end.
 
 `relevance` is stamped by the context-pack builder because it knows the pack
 target and the receipt selection method. It is not produced by the pure receipt
-summarizer. In v0.1.12, the only shipping selection scopes are:
+summarizer. The shipping selection scopes are:
+
+- `scope: "target_bound"`: a context receipt was selected through a matching
+  `evidence_links` row for this pack target.
 
 - `scope: "unscoped_latest"`: the most recent context receipt was selected by
-  recency and was not created for the pack target.
+  recency because no matching bound receipt was available. The summary includes
+  an explicit warning.
 - `scope: "missing_receipt"`: no context receipt was available.
 
-The only shipping binding strength is `binding_strength: "none"`, meaning no
-caller or PLH mechanism asserted a target linkage. Future vocabulary reserves
-`scope: "target_bound"` and `binding_strength: "caller_asserted"` for a
-possible caller-labeled flow. A caller-asserted binding would be a caller label,
-not a PLH-verified semantic relation between the receipt and the target. This
-version does not implement `--for-task`, `--for-job`, or
-`--require-bound-receipt` flags.
+Binding strength is `binding_strength: "caller_asserted"` only for
+`target_bound` receipts created with `pcl impact --diff --for-task` or
+`--for-job`. This is a caller label, not a PLH-verified semantic relation
+between the receipt and the target. Unscoped fallback and missing-receipt states
+use `binding_strength: "none"`.
 
 `receipt_age` records freshness facts for the embedded receipt:
 `{"created_at": "...", "age_seconds": 123}`. Age is computed against a single
@@ -158,8 +180,8 @@ the context pack.
 
 When no receipt exists, `--include-code-context` still succeeds and returns a
 `code_context` summary with `status: "missing_receipt"`, empty receipt refs, a
-message, and next actions: `pcl index build --json` and
-`pcl impact --diff --json`. The same commands are exposed in
+message, and next actions: `pcl index build --json` and a target-specific
+impact refresh command. The same commands are exposed in
 `context_pack.suggested_refresh_commands`; they are not placed in
 `source_commands`. The summary still includes `relevance` with
 `scope: "missing_receipt"` and `binding_strength: "none"`. Receipt-derived
@@ -276,7 +298,7 @@ The selected profile name is returned as `role_profile`.
 - It does not read or parse `.project-loop/dashboard/dashboard.html`.
 - It never executes `pcl impact` during pack generation.
 - It does not run `pcl index build` or `pcl impact`; `--include-code-context`
-  reads the latest existing receipt evidence only.
+  reads `evidence_links`, evidence rows, and existing receipt artifacts only.
 - It does not inline the full context receipt body.
 
 Agents should use `pcl` JSON commands, reports, evidence paths, or