project-loop-harness 0.2.0__tar.gz → 0.2.2__tar.gz

{project_loop_harness-0.2.0/src/project_loop_harness.egg-info → project_loop_harness-0.2.2}/PKG-INFO

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

project_loop_harness-0.2.2/agent-tasks/0089-dogfood-fixture-propose.md

@@ -0,0 +1,107 @@
+# Task 0089: Dogfood-to-Fixture Propose (v0.2.1)
+
+Design source: `docs/verification-feedback-design.md` Part 4 plus the
+Approval addendum item 4 (staging location). Where this spec and the
+design doc disagree, the design doc wins. No migration, no new
+runtime dependency.
+
+## Goal
+
+An eval suite whose fixtures do not grow from real usage is not
+credible. Add `pcl eval fixture propose --from-receipt <evidence-id>`
+so real context receipts become UNLABELED fixture candidates that a
+human labels before adoption. PLH never fabricates ground-truth
+labels.
+
+## Design constraints (approved, do not relitigate)
+
+- Staging area is repo-root `fixtures/proposed/` — a reviewable,
+  Git-tracked source asset, NOT `.project-loop/` state.
+- Proposed candidates carry `labels_status: "unlabeled"` and EMPTY
+  `expected_files` / `expected_tests` / `critical_context` arrays.
+  Filling them is a human review step by definition.
+- Adoption into `tests/fixtures/` is a manual `git mv`-style step
+  after human labeling. NO auto-adoption path exists, and none may
+  be added.
+
+## Scope
+
+### 1. `pcl eval fixture propose --from-receipt <evidence-id> [--json]`
+
+- Loads the referenced evidence row; it must be `type =
+  'context_receipt'` with a readable `context-receipt/v0` artifact —
+  unknown evidence, wrong type, or unreadable artifact are distinct
+  typed errors (reuse the receipt-loading discipline from
+  `verification_feedback.py` where sensible).
+- Emits `fixtures/proposed/<receipt-evidence-id>-retrieval.json`
+  (lowercased evidence id, deterministic name; refuse to overwrite an
+  existing file unless `--force` — overwriting a half-labeled
+  candidate silently would destroy human work).
+- Candidate shape: `retrieval-fixture/v0` with ONE task:
+  - `id`: derived from the receipt evidence id (deterministic).
+  - `diff`: a minimal synthetic unified diff touching exactly the
+    receipt's `changed_files` paths (same mechanical style as
+    existing fixtures). Receipts do not store original diff text, so
+    the replay diff is synthesized; record that honestly via
+    `diff_synthesized_from_receipt: true` inside the task.
+  - `expected_files: []`, `expected_tests: []`,
+    `critical_context: []`, `labels_status: "unlabeled"`.
+  - `source_receipt` provenance block: `evidence_id`, `created_at`,
+    `diff_source`, `base_ref` (when present), and
+    `retrieved_candidate_paths` (the receipt's
+    `included_candidate_context` paths) — this is the raw material
+    the human labeler starts from, clearly provenance, not labels.
+- Record one standard `eval_fixture_proposed` event via the shared
+  `append_event` path (SQLite events table + JSONL mirror, sequential
+  event id), recording the receipt evidence id and output path. The
+  event row is the ONLY permitted SQLite write; no other tables may
+  be touched.
+  **Clarified 2026-07-06 after first acceptance pass:** the original
+  wording "JSONL event ... No SQLite mutation" was over-constrained
+  and led to a JSONL-only event with a uuid id, which violates the
+  task-0012 audit integrity invariant (`validate --strict` errors on
+  JSONL event ids missing from the DB events table). Events always go
+  through `append_event` to both stores; do not invent side-channel
+  event writers.
+
+### 2. Guard: eval refuses unlabeled fixtures
+
+- `pcl eval retrieval` on a fixture whose tasks carry
+  `labels_status: "unlabeled"` (or empty expected+critical blocks
+  alongside that marker) fails with a typed error telling the
+  operator to label the candidate and move it into `tests/fixtures/`.
+  Labeled/legacy fixtures (no `labels_status` field) evaluate as
+  today.
+
+### 3. Documentation
+
+- `docs/code-context.md` (eval section): propose workflow, staging
+  directory, human labeling step, manual adoption, and the
+  no-fabricated-labels rule.
+- Add `fixtures/proposed/.gitkeep` (or a one-line README.md in that
+  directory) so the staging area exists in Git.
+
+## Acceptance Criteria
+
+- Proposing from a real receipt fixture yields a candidate that is
+  byte-deterministic given the same receipt (no timestamps of its
+  own — reuse the receipt's `created_at`).
+- Candidate visibly unlabeled: `labels_status: "unlabeled"`, all
+  three expected/critical arrays empty (contract test).
+- `pcl eval retrieval` against the proposed candidate → typed error;
+  after a test labels it (filling expected blocks, removing/flipping
+  `labels_status`), evaluation runs and produces metrics.
+- Unknown/wrong-type/unreadable receipt → distinct typed errors,
+  nothing written.
+- Existing candidate without `--force` → typed error, file untouched.
+- `ruff check .` passes; full `python3 -m pytest` passes; `pcl init`
+  smoke against a temp dir passes.
+
+## Do Not
+
+- Do not fill or guess expected/critical labels from receipt data.
+- Do not add an auto-adoption or auto-labeling path.
+- Do not write candidates anywhere under `.project-loop/`.
+- Do not mutate SQLite; the only side effects are the candidate file
+  and one JSONL event.
+- Do not use hit/miss/usefulness vocabulary.

project_loop_harness-0.2.2/agent-tasks/0090-eval-baseline-record-compare.md

@@ -0,0 +1,134 @@
+# Task 0090: Eval Baseline Record / Compare (v0.2.1)
+
+Design source: `docs/verification-feedback-design.md` Part 3 plus the
+Approval addendum. Where this spec and the design doc disagree, the
+design doc wins. Depends on task 0089 (unlabeled-fixture guard) being
+merged. No migration, no new runtime dependency.
+
+## Goal
+
+Make retrieval eval results durable, comparable evidence with full
+provenance, so the semantic promotion gate can eventually be decided
+by evidence instead of enthusiasm. Metric thresholds stay ADVISORY;
+only broken measurement infrastructure blocks.
+
+## Scope
+
+### 1. Metrics completion (additive to `retrieval-eval/v0` output)
+
+- Add `false_positive_rate` = (retrieved_total − true_positive_total)
+  / retrieved_total (aggregate and per task; `null` on empty
+  denominator — same rule as everywhere else).
+- Add `token_cost_estimate` = deterministic `charclass/v1` estimate
+  for the retrieved candidate files (per task and aggregate). Reuse
+  the existing estimator; it is an estimate label, never a billing
+  claim. Files missing from the index contribute 0 and are listed in
+  a `token_cost_unestimated_paths` array rather than silently
+  skipped.
+  **Clarified 2026-07-06 after first acceptance pass:** the estimate
+  basis is a per-file `token_estimate` INTEGER computed at index
+  build time (file text is already in memory during scan) and stored
+  in the index detail payload. The detail artifact must NEVER store
+  file content — the index stays hashes + symbol-lite metadata
+  (architecture boundary; 0077 budget discipline; 0072 sensitive
+  surface). Old details lacking `token_estimate` route those paths
+  into `token_cost_unestimated_paths`. The first implementation
+  embedded full `indexed_content` text into the detail; do not
+  repeat that.
+- Existing precision / recall / missing_critical_context stay
+  unchanged.
+
+### 2. Fixture kind coverage (5 kinds)
+
+The approved kinds: code change, docs-only, config-only, rename/move,
+secret omission. Code change, rename/move, and secret omission
+already exist (`retrieval_v0.json`, `retrieval_adversarial_v0.json`).
+Add small labeled fixture tasks for **docs-only** and **config-only**
+changes in the same synthetic style. Keep the existing floor-test
+discipline: assert metric floors per fixture in tests so regressions
+fail loudly.
+
+### 3. `pcl eval retrieval --record-baseline`
+
+- Runs the eval, then stores the full evaluation payload as a normal
+  evidence artifact under `.project-loop/evidence/retrieval-eval/`
+  (evidence row + JSONL event, following the receipt-recording
+  pattern).
+- Baseline artifact carries a `baseline_provenance` block with ALL
+  SIX approved fields, each REQUIRED:
+  1. `fixture_path` + `fixture_content_hash` (sha256 of fixture
+     bytes),
+  2. `git_head` of the target repo,
+  3. `index_run_id` + `index_detail_hash` (hash of the index detail
+     artifact),
+  4. `code_context_config_hash` (hash of the effective `code_index`
+     config subtree from `pcl.yaml`, canonicalized),
+  5. `pcl_version` (the real `pcl.__version__`),
+  6. `eval_contract_version` (`retrieval-eval/v0`).
+- Missing provenance input (e.g., no index run exists, not a git
+  repo) → typed error, nothing recorded. Broken provenance is not a
+  baseline.
+
+### 4. `pcl eval retrieval --compare-baseline`
+
+- Finds the LATEST recorded baseline whose `fixture_content_hash`
+  matches the current fixture; reports per-metric deltas
+  (precision, recall, missing-critical-context count,
+  false_positive_rate, token_cost_estimate) plus both provenance
+  blocks side by side.
+- No baseline with a matching fixture hash → typed
+  "not comparable" error naming the nearest baseline and why it does
+  not match (hash mismatch is stated explicitly, never silently
+  compared).
+- Comparison output is a report, not a verdict: deltas and facts
+  only. No pass/fail field, no threshold evaluation.
+
+### 5. CI advisory comparison
+
+- Extend `scripts/run_advisory_retrieval_eval.py` (or add a sibling
+  script wired the same way) so CI runs the eval and, when a
+  committed baseline reference exists, prints the comparison as an
+  advisory artifact.
+- Metric regressions NEVER fail CI.
+- Eval INFRASTRUCTURE failures DO fail CI: eval command error,
+  fixture contract violation, unreadable fixture, provenance
+  computation failure. Broken measurement is not advisory.
+
+### 6. Documentation
+
+- `docs/code-context.md` eval section: baseline lifecycle, the six
+  provenance fields, the advisory-vs-blocking boundary, and the
+  semantic promotion gate linkage (evidence decides promotion).
+
+## Acceptance Criteria
+
+- Recording twice on an unchanged repo+fixture yields identical
+  metrics and identical provenance except evidence id/created_at.
+- Compare on matching hash reports per-metric deltas; compare after
+  editing the fixture → typed not-comparable error that names the
+  hash mismatch.
+- Missing index run → typed error from `--record-baseline`, no
+  evidence row, no event.
+- `false_positive_rate` and `token_cost_estimate` appear per task
+  and aggregate, `null` on empty denominators;
+  `token_cost_unestimated_paths` lists unindexed files.
+- Docs-only and config-only fixture tasks exist with floor tests.
+- CI script: a deliberately corrupted fixture fails the script
+  (blocking path test); a metric delta does not (advisory path
+  test).
+- `pcl validate --strict` untouched by baselines beyond standard
+  evidence integrity.
+- `ruff check .` passes; full `python3 -m pytest` passes; `pcl init`
+  smoke against a temp dir passes.
+
+## Do Not
+
+- Do not implement metric thresholds, pass/fail verdicts, or release
+  gates on metric values.
+- Do not compare across different fixture hashes "helpfully".
+- Do not read generated dashboard HTML, mutate state from the eval
+  path beyond the evidence row + event, or add raw SQL.
+- Do not use hit/miss/usefulness vocabulary; token cost is an
+  estimate, not a price.
+- Do not touch embeddings / Tree-sitter / call graphs — the semantic
+  promotion gate is unchanged.

project_loop_harness-0.2.2/agent-tasks/0092-idempotent-status-transitions.md

@@ -0,0 +1,78 @@
+# Task 0092: Idempotent Same-State Transitions (v0.2.2, F1)
+
+Source: first external-project agent dogfood feedback
+(`docs/feedback/2026-07-06-ax1-moc1-agent-feedback.md`, item F1).
+`pcl feature status F-0001 --status passing` exits 2 when the feature
+is already passing. For scripting agents a same-state request is a
+satisfied postcondition, not an input error; exit 2 forces every
+caller to pre-read state or wrap errors. No migration, no new
+dependency.
+
+## Behavior change (all four sites)
+
+Same-state transition requests become successful no-ops:
+
+- `pcl feature status <id> --status <current>` (`commands.py`
+  `set_feature_status`)
+- `pcl goal complete` / goal lifecycle same-state (`lifecycle.py`,
+  the "Goal ... is already ..." site)
+- `pcl test <verb>` when the test case is already in the requested
+  terminal state (`stories.py`, the "Test case ... is already ..."
+  site)
+- `pcl task status <id> <current>` (`tasks.py`, the "Task ... is
+  already ..." site)
+
+No-op semantics (identical across all four):
+
+- Exit code 0; JSON gains `"changed": false` plus the current status.
+- NOTHING is recorded: no status update, no inline evidence row, no
+  event append. A no-op that logs is not a no-op — repeated agent
+  retries must not inflate the audit trail.
+- Human-readable output states plainly that the entity was already in
+  the requested state (e.g. `Feature F-0001 already passing; no
+  change recorded.`).
+- Supplied `--evidence` / `--reason` text on a no-op is NOT recorded;
+  the response must make that explicit (e.g.
+  `"evidence_recorded": false`) so callers do not believe evidence
+  was attached. Attaching fresh evidence to an already-terminal state
+  (re-verification) is out of scope here and belongs to the evidence
+  entry-path design.
+
+Changed transitions additionally gain `"changed": true` (additive
+JSON field; existing fields untouched).
+
+## What must NOT change
+
+- Invalid TARGET states and disallowed transitions (e.g. rubric or
+  guard violations, unknown entities) keep their existing typed
+  errors and exit codes. Only the exact same-state case becomes a
+  no-op.
+- Evidence-backed terminal-state validation invariants are untouched
+  (a no-op changes nothing, so nothing new to validate).
+- No behavior change for transitions that DO change state, other
+  than the additive `changed` field.
+
+## Acceptance Criteria
+
+- For each of the four commands: same-state call → exit 0,
+  `changed: false`, row count of events/evidence unchanged (assert
+  counts before/after), status unchanged, and repeated invocation is
+  stable (call twice more, same result).
+- Same-state call with `--evidence "..."` → `evidence_recorded:
+  false` in JSON and no evidence row.
+- Changed-state calls still record exactly as before and now carry
+  `changed: true`.
+- Unknown entity / invalid target status still typed errors (regression
+  tests kept).
+- Docs: `docs/golden-path.md` or command docs note the idempotent
+  semantics in one short paragraph.
+- `ruff check .` passes; full `python3 -m pytest` passes; `pcl init`
+  smoke against a temp dir passes.
+
+## Do Not
+
+- Do not make disallowed transitions succeed.
+- Do not append events or evidence on no-ops.
+- Do not add a `--force` re-record path (that is evidence-path design
+  territory).
+- Do not touch schema or raw SQL outside the existing service layer.

project_loop_harness-0.2.2/agent-tasks/0093-evidence-add-command.md

@@ -0,0 +1,95 @@
+# Task 0093: `pcl evidence add` + Adhoc Bundles (v0.2.2, F2/F6)
+
+Design source: `docs/evidence-entry-paths-design.md`
+(**APPROVED 2026-07-07**, Parts 1-2 and the approval record). Where
+this spec and the design doc disagree, the design doc wins. No
+migration, no new runtime dependency; schema stays v5.
+
+## Goal
+
+Operators and agents produce reviewable artifacts outside the job
+loop (test output, screenshots, visual-check reports) and PLH has no
+honest way to accept them as evidence. Add the missing primitive.
+
+## Scope
+
+### 1. `pcl evidence add`
+
+```bash
+pcl evidence add --file work/reports/pytest-out.txt \
+  --summary "pytest run for suggestion E-0017/VS-01" \
+  --command "python3 -m pytest tests/test_context.py" --json
+```
+
+- `--file` is required and repeatable; every path must exist and be
+  readable at record time (missing/unreadable → typed error, nothing
+  recorded). `--summary` required. `--command` optional — it is the
+  CALLER'S claim of how the artifact was produced; PLH stores it
+  verbatim and never runs or verifies it (docs and help must say
+  this).
+- One file → evidence `type = 'adhoc_artifact'` (approved). Two or
+  more files → `type = 'adhoc_bundle'` (approved).
+- In both cases PLH writes a small manifest JSON under
+  `.project-loop/evidence/adhoc/` recording, per member: relative
+  path, size_bytes, sha256 — pinned AT RECORD TIME. Members are
+  referenced in place, NOT copied (approved; a `--copy` mode is a
+  possible later addition, do not add it now).
+- The evidence row's `path` points at the manifest; `command` and
+  `summary` come from the flags. One evidence row per invocation, one
+  standard event via `append_event` (SQLite + JSONL both — never a
+  side-channel writer; see agent-tasks/0089 clarification).
+- Manifest contract name: `adhoc-evidence/v0` with a
+  `contract_version` field. Deterministic member ordering (input
+  order preserved; duplicates by path → typed error).
+- JSON output returns the evidence id, type, manifest path, and the
+  member list with hashes.
+
+### 2. Strict validation integration
+
+- `pcl validate --strict` verifies for adhoc evidence rows that the
+  manifest file exists and parses; missing/corrupt manifest is an
+  ERROR (state integrity).
+- Member hash drift (file changed or deleted since recording) is a
+  WARNING, not an error (approved): drift is the working tree moving
+  on; the pinned hash remains the recorded claim. Warning text must
+  name the evidence id, member path, and which aspect drifted
+  (missing vs hash mismatch).
+
+### 3. Documentation
+
+- New section in `docs/data-model.md` or `docs/golden-path.md`:
+  the adhoc evidence flow, the claim/pointer epistemic boundary, and
+  the worked example ending in
+  `pcl verification feedback ... --evidence E-00xx`.
+- `docs/evidence-entry-paths-design.md` stays the design record; do
+  not duplicate it wholesale.
+
+## Acceptance Criteria
+
+- Single file → `adhoc_artifact`; multiple files → `adhoc_bundle`;
+  manifest carries per-member path/size/sha256; JSON output matches.
+- Determinism: same files, same flags → identical manifest content
+  except created_at/evidence id.
+- Missing file, unreadable file, duplicate path → distinct typed
+  errors, no evidence row, no event, no manifest file left behind.
+- `validate --strict`: green after add; deleting a member → WARNING
+  (still ok); editing a member → WARNING naming the hash mismatch;
+  deleting the MANIFEST → ERROR.
+- End-to-end test: `evidence add` → `verification feedback
+  --status executed --evidence <new id>` succeeds (closes the M2
+  dogfood gap).
+- Events mirrored in SQLite and JSONL; strict audit integrity stays
+  green (regression test).
+- `ruff check .` passes; full `python3 -m pytest` passes; `pcl init`
+  smoke against a temp dir passes.
+
+## Do Not
+
+- Do not copy member files or add `--copy` yet.
+- Do not execute `--command` or capture output (`--capture` is out of
+  scope by design).
+- Do not add an M:N evidence link table or any migration.
+- Do not use "verified"/"safe" language for adhoc evidence — it is a
+  recorded claim with pinned hashes.
+- Do not touch `verification feedback` flags (`--output-file` is
+  formally superseded, not implemented).

project_loop_harness-0.2.2/agent-tasks/0094-job-completion-evidence.md

@@ -0,0 +1,71 @@
+# Task 0094: Job Completion Evidence Linkage (v0.2.2, F3)
+
+Design source: `docs/evidence-entry-paths-design.md`
+(**APPROVED 2026-07-07**, Part 3). Depends on 0093 being merged (its
+adhoc evidence rows are natural inputs here, and both touch cli.py /
+validators tests). No migration; schema stays v5.
+
+## Goal
+
+In the ax1-moc1 dogfood run, `pcl jobs list --json` showed empty
+evidence for jobs whose `output_path` files existed, and there was no
+way to attach evidence when completing a job. Close both gaps using
+the EXISTING `latest_evidence_id` pointer on agent jobs.
+
+## Scope
+
+### 1. `pcl jobs complete <job-id> --evidence E-00xx`
+
+- Optional repeatable? NO — single `--evidence` flag (the
+  one-pointer model matches `latest_evidence_id`; multiple artifacts
+  are one adhoc bundle from 0093).
+- The referenced evidence row must exist → typed error otherwise,
+  nothing changed.
+- Sets `latest_evidence_id` on the job as part of the existing
+  completion flow; completion event payload gains the evidence id.
+  All existing completion semantics (summary, status transition,
+  guards) unchanged.
+
+### 2. Jobs-list evidence visibility audit (the ax1-moc1 symptom)
+
+- Reproduce first: in the ax1-moc1 run, jobs completed through the
+  normal flow showed `evidence: []`/empty in `pcl jobs list --json`
+  even though `output_path` existed and ingest had run. Find out
+  why (linkage never set? read path not surfacing it? ingest path
+  only sets it on certain flows?) and fix the actual cause — do not
+  paper over it in the list renderer.
+- After the fix: a job whose output was ingested surfaces its
+  evidence reference in `jobs read` / `jobs list --json` and
+  dashboard-data.
+
+### 3. Documentation
+
+- `docs/golden-path.md` / agent adapter docs: one short paragraph —
+  complete a job with `--evidence` when the artifact is already
+  recorded (0093 flow), otherwise ingest output as before.
+
+## Acceptance Criteria
+
+- `jobs complete --evidence E-00xx` sets `latest_evidence_id`,
+  appends the completion event with the evidence id, and the linkage
+  appears in `jobs read --json`, `jobs list --json`, and
+  dashboard-data.
+- Unknown evidence id → typed error; job stays incomplete and
+  unchanged.
+- Root-cause test for the visibility bug: a test that reproduces the
+  original empty-evidence symptom path and asserts it is fixed
+  (write the test against the actual discovered cause, and explain
+  the cause in the task report).
+- Existing completion without `--evidence` behaves exactly as
+  before.
+- `ruff check .` passes; full `python3 -m pytest` passes; `pcl init`
+  smoke against a temp dir passes; strict validate/audit integrity
+  regression stays green.
+
+## Do Not
+
+- Do not add repeatable `--evidence` or an M:N link table.
+- Do not auto-create evidence from `output_path` without ingest —
+  linkage requires a real evidence row.
+- Do not change ingest contracts (`agent-output/v1`) or job state
+  machine semantics.

{project_loop_harness-0.2.0 → project_loop_harness-0.2.2}/docs/agent-adapter-contract.md

@@ -78,6 +78,12 @@ The expected output path is deterministic:
 
 The ingest path must be the project-scoped `.project-loop/evidence/agent-runs/<job_id>/output.md`. Files from another directory, even if they contain an `agent-runs/<job_id>` segment, are rejected. Ingest is also a guarded state transition: cancelled or failed jobs cannot be revived by late output, and inactive workflow runs cannot accept new agent output.
 
+If a job artifact has already been recorded with `pcl evidence add`, complete
+the job with `pcl jobs complete <job-id> --evidence E-00xx` to link that
+existing evidence row. Otherwise, keep using `pcl ingest-agent-run` for raw
+agent output so PLH validates `agent-output/v1`, creates the evidence row, and
+marks the job passed in one guarded transition.
+
 After ingest, `pcl jobs read J-0001 --json` and `pcl jobs list --json` expose the derived evidence linkage:
 
 ```json
@@ -88,7 +94,7 @@ After ingest, `pcl jobs read J-0001 --json` and `pcl jobs list --json` expose th
 }
 ```
 
-The linkage is derived from `agent_output_ingested` events and `evidence` rows, not from a mutable `agent_jobs.evidence_id` column. Repeated ingests can therefore preserve multiple evidence ids while the latest evidence remains easy to find from job surfaces and the dashboard.
+The linkage is derived from `agent_output_ingested` events, evidence-bearing `agent_job_completed` events, and `evidence` rows, not from a mutable `agent_jobs.evidence_id` column. Repeated ingests can therefore preserve multiple evidence ids while the latest evidence remains easy to find from job surfaces and the dashboard.
 
 ## Minimal Output File
 

{project_loop_harness-0.2.0 → project_loop_harness-0.2.2}/docs/code-context.md

@@ -55,6 +55,8 @@ Evaluate retrieval behavior against labels:
 
 ```bash
 pcl eval retrieval --fixture tests/fixtures/retrieval_v0.json --json
+pcl eval retrieval --fixture tests/fixtures/retrieval_v0.json --record-baseline --json
+pcl eval retrieval --fixture tests/fixtures/retrieval_v0.json --compare-baseline --json
 ```
 
 ## Index Contract
@@ -109,6 +111,7 @@ needs every file, ignored path, and hash-skip entry on stdout.
       "mtime": 123456789,
       "sha256": "abc123",
       "line_count": 10,
+      "token_estimate": 42,
       "symbol_summary": {
         "contract_version": "symbol-summary/v0",
         "symbols": [{"type": "function", "name": "pack_context_for_job", "line": 1}]
@@ -629,6 +632,29 @@ Task fields:
   `assertion_note`, and `must_not_retrieve`, are metadata and are ignored by
   the evaluator.
 
+Dogfood receipts become fixture candidates through a staging workflow:
+
+```bash
+pcl eval fixture propose --from-receipt E-0001 --json
+```
+
+The command reads a real `context_receipt` evidence row and writes an
+UNLABELED `retrieval-fixture/v0` candidate to repo-root `fixtures/proposed/`.
+That directory is a Git-tracked source staging area, not `.project-loop/`
+runtime state. The candidate has one task, a synthetic unified diff touching
+the receipt's `changed_files` paths, `diff_synthesized_from_receipt: true`, and
+source receipt provenance (`evidence_id`, `created_at`, `diff_source`,
+optional `base_ref`, and retrieved candidate paths). The synthetic diff is only
+a replay handle because receipts do not store original diff text.
+
+PLH never fabricates ground-truth labels. Proposed tasks carry
+`labels_status: "unlabeled"` and empty `expected_files`, `expected_tests`, and
+`critical_context` arrays. `pcl eval retrieval` refuses these candidates with a
+typed error. A human must inspect the source receipt, fill the expected and
+critical arrays, remove or change the unlabeled marker, and manually adopt the
+fixture into `tests/fixtures/` with a normal Git move. There is no auto-labeling
+or auto-adoption path.
+
 Fixture evolution is additive in v0:
 
 - New optional fields may be added without a version bump.
@@ -640,6 +666,8 @@ Fixture evolution is additive in v0:
 
 The checked-in fixture families have different purposes:
 
+- `retrieval_v0.json`: small synthetic coverage for code change, docs-only,
+  and config-only tasks.
 - `real-history`: derived from actual repository changes, currently following
   the `tests/fixtures/retrieval_real_history_v0.json` pattern. These fixtures
   measure ordinary retrieval quality against real change history.
@@ -649,23 +677,88 @@ The checked-in fixture families have different purposes:
   omission, stale-index signaling, and an annotated renamed-file baseline miss.
 
 `pcl eval retrieval --fixture <path> --json` returns `retrieval-eval/v0` with
-precision, recall, `missing_critical_context`, and per-task retrieved paths.
+precision, recall, false-positive rate, token cost estimate,
+`missing_critical_context`, and per-task retrieved paths.
+
+Metric fields:
+
+- `precision`: true positives divided by retrieved paths, preserving the v0
+  empty-denominator rule.
+- `recall`: true positives divided by expected files/tests, preserving the v0
+  empty-denominator rule.
+- `false_positive_rate`: `(retrieved - true_positives) / retrieved`; empty
+  retrieved denominators yield `null`.
+- `token_cost_estimate`: deterministic `charclass/v1` estimate over retrieved
+  paths' per-file `token_estimate` integers from
+  `.project-loop/cache/code-index-detail.json`. The estimate is computed at
+  index build time from indexed text already in memory; the detail artifact does
+  not store raw file contents. It is an estimate of indexed text volume, not a
+  price or billing signal.
+- `token_cost_unestimated_paths`: retrieved paths that are absent from the
+  detail artifact or present without a `token_estimate`, including details
+  built by older versions. They contribute `0` to the estimate and are listed
+  explicitly.
+- `missing_critical_context`: labeled critical paths not retrieved.
+
 Task output may also include additive diagnostic fields used by adversarial
 fixtures: `retrieval_source`, `staleness_warnings`,
 `staleness_affected_paths`, `sensitive_omitted_count`,
 `retrieved_snapshot_consistency`, `excluded_changed_files`, and
 `expected_misses`.
 
+### Baseline Lifecycle
+
+`pcl eval retrieval --fixture <path> --record-baseline --json` runs the eval
+and stores the full payload as normal evidence under
+`.project-loop/evidence/retrieval-eval/`. Recording writes an evidence row and
+the standard mirrored event in SQLite and `.project-loop/events.jsonl`; it does
+not use a JSONL-only side channel.
+
+Every baseline artifact carries `baseline_provenance` with these required
+fields:
+
+- `fixture_path`
+- `fixture_content_hash` (sha256 of fixture bytes)
+- `git_head`
+- `index_run_id`
+- `index_detail_hash` (sha256 of the code index detail artifact)
+- `code_context_config_hash` (canonical effective `code_index` subtree)
+- `pcl_version`
+- `eval_contract_version` (`retrieval-eval/v0`)
+
+Missing provenance inputs, such as no index run, missing index detail artifact,
+or a non-Git target, are typed errors. In those cases no baseline artifact,
+evidence row, or event is recorded.
+
+`pcl eval retrieval --fixture <path> --compare-baseline --json` compares the
+current eval with the latest recorded baseline whose `fixture_content_hash`
+matches the current fixture. It reports current metrics, baseline metrics,
+metric deltas, current provenance, and baseline provenance. The reported deltas
+cover precision, recall, missing-critical-context count, false-positive rate,
+and token cost estimate.
+
+Comparison never crosses fixture hashes. If only a different fixture hash is
+available, the command returns a typed not-comparable error naming the nearest
+baseline and the hash mismatch. The comparison output is facts and deltas only:
+no threshold logic, no verdict field, and no release gate.
+
 CI runs `python3 scripts/run_advisory_retrieval_eval.py` after pytest. The step
 initializes and indexes the checked-out project, evaluates the checked-in
 real-history fixtures, evaluates the checked-in adversarial fixture against a
-prepared temp project, and prints a compact JSON summary. This is advisory:
-metric values are not release blockers and no recall/precision threshold is set
-in v0.1.11. Crashed eval runs or broken fixture files still fail the command.
-
-Promotion condition: retrieval metrics become release blockers only after
-dogfood data from real projects exists, thresholds are chosen from that data,
-and the thresholds are documented in a later task. Until then, proposals for
-semantic retrieval, Tree-sitter parsing, or call-graph retrieval must bring
-eval evidence showing improvement on these fixtures, but this document does
-not define concrete numeric gates.
+prepared temp project, and prints a compact JSON summary. When a local
+retrieval-eval baseline exists, the script also prints the same comparison
+facts as advisory output.
+
+Advisory-vs-blocking boundary:
+
+- Metric deltas never fail CI in v0.2.1.
+- Eval infrastructure integrity failures do fail CI: eval command errors,
+  fixture contract violations, unreadable fixtures, and provenance computation
+  failures.
+- Broken measurement is not advisory.
+
+Semantic promotion gate: richer retrieval approaches such as semantic
+retrieval, Tree-sitter parsing, or call-graph retrieval remain out of scope for
+v0.2.1. Future promotion is evidence-driven: baseline history and fixture
+coverage decide whether richer retrieval is justified, not enthusiasm. This
+document deliberately defines no metric thresholds or release gates.