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

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

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

project_loop_harness-0.2.3/agent-tasks/0095-supporting-evidence-health.md

@@ -0,0 +1,156 @@
+# Task 0095: Supporting Evidence Health in Verification Stats (v0.2.3, P0)
+
+Origin: GPT-5.5-pro v0.2.2 review agenda, blind spot B ("feedback stats
+do not look at the health of supporting evidence"). No migration, no
+new runtime dependency; schema stays v5.
+
+## Goal
+
+`verification_feedback` rows can reference a `supporting_evidence_id`.
+Since v0.2.2 that evidence is often an `adhoc_artifact` / `adhoc_bundle`
+whose members are referenced (not copied) and hash-pinned. Stats can
+therefore show a healthy `executed_pass_rate` while the artifacts
+backing those feedbacks have since gone missing or drifted.
+
+Add a **derived, read-only health axis** to `pcl verification stats
+--json` that reports whether the supporting evidence behind executed
+feedback is still reviewable today. Do NOT change any existing metric
+and do NOT rewrite any feedback row: PLH records facts append-only;
+health is a separate, current-time observation about reviewability.
+
+## Vocabulary (binding)
+
+- Health values: `ok` | `warning` | `error` | `unknown`.
+- Health describes "current reviewability of the referenced
+  artifacts". It never asserts the original claim was true or false.
+- Forbidden in new output, help text, and docs for this feature:
+  "verified", "proven", "guaranteed", "invalid(ated)". A drifted
+  artifact does not invalidate a past feedback; it makes it harder to
+  review now.
+
+## Scope
+
+### 1. Shared adhoc health assessment
+
+Extract the adhoc manifest/member checks that already exist in
+`src/pcl/validators.py` (`_validate_adhoc_evidence_manifests` /
+`_validate_adhoc_members`) into a shared, structured assessment
+function in `src/pcl/evidence.py`, e.g.:
+
+```python
+def assess_adhoc_evidence(paths, *, evidence_id, evidence_type, manifest_path_value) -> dict
+# -> {"health": "ok"|"warning"|"error", "findings": [{"code": ..., "path": ...?, "detail": ...?}]}
+```
+
+Structured finding codes (at minimum): `manifest_not_local`,
+`manifest_missing`, `manifest_not_file`, `manifest_corrupt`,
+`contract_version_unsupported`, `evidence_id_mismatch`,
+`evidence_type_mismatch`, `members_invalid`, `member_entry_invalid`,
+`member_missing`, `member_hash_mismatch`.
+
+Severity mapping mirrors today's validator semantics exactly:
+structural manifest problems are `error`; member drift (missing file
+or hash mismatch) is `warning`; everything intact is `ok`.
+
+`validators.py` must consume this shared function so drift semantics
+have a single source. Protective invariant, scoped: **the rendered
+`pcl validate` / `pcl validate --strict` messages for the existing
+test fixtures must remain unchanged — all existing validator tests
+pass unmodified.** If message-identical rendering from structured
+findings proves impossible for some edge case, stop and report
+instead of changing a message.
+
+The assessment must tolerate (ignore) unknown extra keys on manifest
+members — task 0096 will add fields such as `path_scope` later.
+
+### 2. `supporting_evidence_health` in stats
+
+In `verification_feedback_stats` (`src/pcl/verification_feedback.py`),
+assess every **distinct** `supporting_evidence_id` referenced by
+feedback rows already loaded for stats (all statuses, not just
+executed — a `skipped` feedback can also carry evidence):
+
+- Evidence row absent in `evidence` table → `error` with finding
+  `evidence_row_missing`. (Normally impossible — record-time checks
+  existence — but deletion/corruption must surface, not crash.)
+- Evidence row present, `type` in (`adhoc_artifact`, `adhoc_bundle`)
+  → result of the shared assessment.
+- Evidence row present, any other type (`context_receipt`, ingested
+  agent output, test evidence, ...) → `unknown` with finding
+  `health_not_assessed_for_type`. v0 assesses adhoc only; do not
+  invent checks for other types.
+
+Each distinct evidence id is assessed (and its member files hashed)
+at most once per stats invocation.
+
+New sibling section in the returned `stats` object (additive only —
+no existing key changes, no metric formula changes):
+
+```json
+"supporting_evidence_health": {
+  "assessed_evidence_count": 2,
+  "feedback_events_with_supporting_evidence_count": 3,
+  "health_counts": {"ok": 1, "warning": 0, "error": 0, "unknown": 1},
+  "by_evidence_id": {
+    "E-0018": {"health": "ok", "findings": []},
+    "E-0017": {"health": "unknown",
+               "findings": [{"code": "health_not_assessed_for_type",
+                              "detail": "context_receipt"}]}
+  }
+}
+```
+
+Additionally, each entry in the existing
+`latest_feedback_by_suggestion` map gains a
+`supporting_evidence_health` key: the health string when that
+feedback row has a `supporting_evidence_id`, else `null`.
+
+### 3. Read surfaces and docs
+
+- `pcl verification stats --json` carries the new section (it already
+  prints the stats dict; no new flag).
+- Docs: extend `docs/verification-feedback.md` with a
+  "Supporting evidence health" section covering the four health
+  values, the adhoc-only v0 scope, and the binding vocabulary rule
+  (health ≠ truth; feedback rows are never rewritten).
+
+## Non-goals
+
+- No change to `pcl validate` behavior or output (refactor only).
+- No dashboard/report rendering of health (v0.2.4 UX round).
+- No health for non-adhoc evidence types beyond `unknown`.
+- No caching of hash checks across invocations.
+- No new events, no DB writes: stats stays a pure read. Protective
+  invariant, scoped: **a `pcl verification stats` invocation must not
+  append to `events.jsonl` nor change any table row** (assert in a
+  test via row counts / file size before and after).
+
+## Tests
+
+1. Feedback with adhoc supporting evidence, members intact → `ok`;
+   health appears in `by_evidence_id` and in
+   `latest_feedback_by_suggestion`.
+2. Overwrite one member file after recording → `warning` with
+   `member_hash_mismatch`; delete a member → `warning` with
+   `member_missing`. Existing metrics (`executed_pass_rate` etc.)
+   unchanged by drift.
+3. Delete the manifest file → `error` with `manifest_missing`.
+4. Supporting evidence of a non-adhoc type → `unknown`.
+5. Feedback without `supporting_evidence_id` → excluded from
+   `health_counts`; `supporting_evidence_health: null` in
+   `latest_feedback_by_suggestion`.
+6. Same evidence id referenced by two feedback rows → assessed once,
+   counted once in `health_counts`.
+7. Stats invocation performs no writes (events.jsonl byte size and
+   evidence/feedback row counts identical before/after).
+8. All existing validator and stats tests pass unmodified.
+
+## Definition of done
+
+- Implementation + tests green (`python3 -m pytest`).
+- Live smoke against this repo's own `.project-loop` (it already has
+  VF-0001/VF-0002 and E-0017/E-0018 from dogfood): stats shows
+  `ok` for E-0018 (adhoc) and `unknown` for E-0017 (context_receipt);
+  then temporarily drift a member copy in a scratch project (not the
+  live DB) to show `warning`.
+- Docs updated. Evidence paths for all claims.

project_loop_harness-0.2.3/agent-tasks/0096-evidence-add-path-guards.md

@@ -0,0 +1,185 @@
+# Task 0096: Evidence Add Path Guards — Scope + Sensitive Shape (v0.2.3, P0)
+
+Origin: GPT-5.5-pro v0.2.2 review agenda, blind spots C (project
+boundary) and D (secret-shaped files), merged into one task because
+both are record-time guards on the same code path
+(`src/pcl/evidence.py::_adhoc_members`). No migration, no new runtime
+dependency; schema stays v5. Runs AFTER 0095 is merged (both touch
+`evidence.py` / `validators.py`).
+
+## Goal
+
+`pcl evidence add` accepts any existing local file. Two gaps:
+
+1. A file outside the project root is silently recorded with a
+   `../...` relative member path — invisible in the manifest, likely
+   unreproducible on another machine.
+2. An agent can pass `.env`, a private key, or a credentials file and
+   PLH records it without any friction.
+
+Add explicit accounting for the project boundary and a name-shaped
+sensitive-path guard. PLH is NOT a content scanner and must not
+become one: both guards look at paths only, never file contents, and
+docs must say so.
+
+## Part A: path scope accounting
+
+### Member field
+
+Every manifest member (and the members echoed in the
+`adhoc_evidence_recorded` event payload and the CLI JSON result)
+gains:
+
+```json
+"path_scope": "in_project" | "outside_project"
+```
+
+Determination: after the existing `resolve()`, the member is
+`in_project` iff `resolved.relative_to(paths.root.resolve())`
+succeeds — the same boundary `_relative_path` already uses.
+
+### Behavior
+
+- Default: `outside_project` members are recorded, with a warning.
+  - Text mode: warning line on stderr.
+  - JSON mode: additive top-level `"warnings": [...]` array in the
+    result (present only when non-empty), one entry per
+    outside-project member, e.g.
+    `"evidence member outside project root: ../tmp/report.txt"`.
+- `pcl.yaml` opt-in hard boundary:
+
+  ```yaml
+  evidence:
+    allow_outside_root: false
+  ```
+
+  When set to `false`, any outside-project member → typed error
+  `evidence_add_outside_root` (exit 2). Absent key or `true` =
+  default warning behavior. Read the key with the same tolerant
+  pcl.yaml reading approach used elsewhere (see
+  `_configured_yaml_list` in `src/pcl/code_context/scan.py` for the
+  house style; a scalar sibling helper is fine).
+
+## Part B: sensitive-shaped path guard
+
+### Patterns
+
+- Reuse `DEFAULT_SENSITIVE_EXCLUDES` and `_path_pattern_matches` from
+  `pcl.code_context` (import them; do NOT copy the pattern list —
+  one source of truth).
+- Optional additional patterns from `pcl.yaml`:
+
+  ```yaml
+  evidence:
+    sensitive_exclude:
+      - "*.sqlite3"
+  ```
+
+- `code_index.sensitive_include_override` does NOT apply here — it is
+  index-scoped. There is no override list for evidence; the override
+  is the explicit CLI flag below.
+
+### Matching
+
+For each member, match patterns against:
+
+1. the recorded member path (the project-relative / `../`-relative
+   form that goes into the manifest), and
+2. the file's basename (so `/Users/x/.env` recorded as
+   `../../.env` still matches `.env`; directory patterns like
+   `.aws/` cannot anchor across `../` prefixes otherwise).
+
+### Behavior
+
+- If any member matches and `--allow-sensitive-evidence` was NOT
+  passed → typed error `evidence_add_sensitive_path` (exit 2) listing
+  the matched paths and patterns in `details`, and telling the caller
+  about `--allow-sensitive-evidence`. This is the default in ALL
+  modes — the CLI is non-interactive; there is no prompt.
+- With `--allow-sensitive-evidence`:
+  - members are recorded; each matched member gains
+    `"sensitive_pattern": "<pattern>"` in the manifest/event/result;
+  - the manifest gains top-level
+    `"sensitive_path_warning_count": <int>` (count of matched
+    members); the event payload carries the same count;
+  - a warning is still emitted (stderr in text mode, `warnings` array
+    entry in JSON mode).
+- Help text and docs must state: this is a filename-shape check only;
+  PLH does not scan file contents and recording with the flag is the
+  caller's explicit decision.
+
+## Guard ordering and atomicity
+
+Both guards run inside the pre-DB stage (`_adhoc_members`), after the
+existing exists/readable/duplicate checks, before any ID allocation,
+manifest write, DB insert, or event append. Protective invariant,
+scoped, same as 0093: **on any typed error from `pcl evidence add`,
+zero traces — no evidence row, no JSONL event, no manifest file, no
+consumed evidence ID, and the `evidence/adhoc/` directory file count
+is unchanged** (assert in tests).
+
+Evaluation order when multiple guards fire: report the sensitive
+error first (it is the safety guard), then outside-root. A single
+typed error is enough; do not build a multi-error report.
+
+## Validators (`src/pcl/validators.py`)
+
+- New optional member fields `path_scope`, `sensitive_pattern` and
+  manifest field `sensitive_path_warning_count` are accepted:
+  - absent → fine (pre-0096 manifests stay valid, no new errors);
+  - present with an invalid value (unknown scope string,
+    non-string pattern, negative/non-int count) → error.
+- New warning, applies to old and new manifests alike since it is
+  derivable from the path itself: a member path starting with `../`
+  → warning `Adhoc evidence <id> member <path> is outside the project
+  root.` This complements, not replaces, the existing drift warnings.
+- The 0095 shared assessment function gains a corresponding finding
+  code `member_outside_project_root` at `warning` severity, so stats
+  health reflects the same fact. Existing fixtures without outside
+  members must produce byte-identical validate output.
+
+## Non-goals
+
+- No content scanning, no entropy heuristics, no secret detection.
+- No change to code index sensitive behavior or context receipts.
+- No dashboard/report highlighting (v0.2.4 UX round).
+- No copy/snapshot mode (task 0097 designs it).
+- No interactive confirmation prompts.
+
+## Tests
+
+1. In-project file → `path_scope: "in_project"`, no warnings key,
+   output otherwise identical to v0.2.2 shape plus the new field.
+2. File under a temp dir outside root → recorded, member has
+   `outside_project`, JSON result has `warnings`, manifest path is
+   `../...`.
+3. Same with `evidence.allow_outside_root: false` → typed
+   `evidence_add_outside_root`, exit 2, zero traces.
+4. `.env` inside project without flag → typed
+   `evidence_add_sensitive_path`, exit 2, zero traces.
+5. `.env` with `--allow-sensitive-evidence` → recorded;
+   `sensitive_pattern` on the member;
+   `sensitive_path_warning_count: 1`; warning emitted.
+6. Outside-project `/tmp/.../credentials-prod.json` without flag →
+   blocked via basename matching.
+7. `evidence.sensitive_exclude` additional pattern matches → blocked
+   without flag.
+8. Bundle mixing one sensitive + one clean member without flag →
+   blocked, zero traces (no partial manifest).
+9. Sensitive + outside-root simultaneously, no flag → the sensitive
+   error is the one reported.
+10. Validators: pre-0096 manifest (no new fields) still valid;
+    manifest with `../` member path → outside-root warning; invalid
+    `path_scope` value → error.
+11. Strict validate output for existing fixtures unchanged.
+
+## Definition of done
+
+- Implementation + tests green (`python3 -m pytest`).
+- Live smoke in a scratch project (`pcl init /tmp/pcl-demo` style):
+  demonstrate cases 2, 4, 5 with real files and show the manifest
+  JSON. Do NOT add sensitive-named files to the live PLH repo DB.
+- `docs/evidence-entry-paths-design.md` gains a short "Path guards
+  (0096)" section documenting scope accounting, the guard, the
+  config keys, and the not-a-content-scanner boundary.
+- Evidence paths for all claims.

project_loop_harness-0.2.3/agent-tasks/0097-evidence-durability-design.md

@@ -0,0 +1,54 @@
+# Task 0097: Evidence Durability Modes — Design Only (v0.2.3, P1)
+
+Origin: GPT-5.5-pro v0.2.2 review agenda, blind spot A ("hash-pin is
+not durability"). **This task produces a design document only — no
+code, no schema change, no CLI change.** Authored by the
+orchestrator (not dispatched to an implementation worker) because it
+is a judgment/trade-off document requiring approval, not a build.
+
+## Problem
+
+v0.2.2 adhoc evidence records member path + size + sha256 but never
+copies the file. This is honest ("existed with this content at record
+time") but weak for later review: cleanup deletes
+`work/reports/pytest-out.txt`, CI artifacts expire, screenshots live
+outside the repo, overwritten files leave only a drift warning.
+
+A naive `--copy` does not fix this either, because
+`.project-loop/evidence/` is **gitignored** (`.gitignore:20`): a copy
+survives local cleanup but still does not travel to another machine
+or reviewer. Durability design is inseparable from the git/versioning
+boundary of `.project-loop`, so the boundary question must be settled
+before any implementation.
+
+## Deliverable
+
+`docs/evidence-durability-design.md` covering at minimum:
+
+1. Modes: `reference` (today, stays default) vs explicit `--copy`
+   (member files copied under `.project-loop/evidence/adhoc-files/`)
+   vs a possible `--snapshot`/export-bundle variant; what each does
+   and does not promise.
+2. Manifest accounting: `storage_mode: reference | copied` per
+   member or per manifest; interaction with drift detection (a copy
+   can also drift or be deleted).
+3. The gitignore boundary problem: options (keep evidence local-only;
+   carve out a committed evidence subdirectory; an explicit
+   `pcl evidence export` bundle for hand-off) with a recommendation.
+4. Interaction with 0096 guards: copying must never weaken them —
+   sensitive-shaped members and outside-root members and copy mode
+   compose (e.g. copying an outside-root file pulls it inside the
+   boundary: is that a feature or a loophole? decide and say why).
+5. Size discipline: soft cap for copied members, `large_evidence_member`
+   warning, relation to strict-validate hash cost (review blind spot
+   F stays backlog; the design should not preclude it).
+6. Truthfulness boundary: PLH never claims copied content is correct,
+   only that it was copied from the named path at record time.
+7. Decision points listed explicitly for approval; no default-copy —
+   copying stays opt-in per invocation.
+
+## Definition of done
+
+- Design doc committed to `main`, marked as awaiting approval.
+- Open decisions presented for approval before any implementation
+  task is cut (implementation would be a v0.2.4+ task).

project_loop_harness-0.2.3/agent-tasks/0098-field-feedback-next-weight-and-run-report-scope.md

@@ -0,0 +1,69 @@
+# Task 0098: Field Feedback — `pcl next` Recommendation Weight + Run Report Record Scope
+
+Origin: Cockpit task 0c7d3d85 (kikulab-design, Codex gpt-5.5). An
+implementation agent ran a full mockup-to-code job under the
+project-control-loop skill and reported structured feedback. The
+documentation-side items (direct implementation loop template,
+workflow close-out procedure, human-gate stop rule, `pcl.yaml`
+`commands.*` clarification) were applied to
+`skills/project-control-loop/SKILL.md` and synced to all
+distribution copies. Two items are product behavior, not docs, and
+are tracked here.
+
+## Problem A: `pcl next` recommends a workflow run for every open goal
+
+Observed in kikulab-design and reproduced in this repo: with one open
+goal and no open defects, `pcl next` returns
+`pcl loop run feature_coverage --goal G-XXXX` (priority 60,
+`continue_goal`). For a single direct implementation task this is
+heavier than needed: it creates mapper/story/test_designer queued
+jobs the agent must later produce outputs for and ingest, and ends in
+a human-gated `verification record` for the run.
+
+The field agent followed the recommendation literally and only later
+realized the minimal feature/story/test path would have sufficed.
+
+### Direction (design before code)
+
+- `pcl next` should distinguish "goal has no feature/story/test
+  activity at all" (workflow suggestion is reasonable) from "goal has
+  in-flight direct work" (suggest continuing the feature/story/test
+  path instead).
+- Alternatively or additionally: include an explicit
+  `alternative` field in the `pcl next` JSON pointing at the minimal
+  direct-implementation path, so agents can choose deliberately. The
+  skill now documents the choice; the CLI should not fight it.
+- Keep `safe_to_run: false` semantics unchanged.
+
+## Problem B: `pcl report run WR-XXXX` shows "No records" for existing features/stories/tests
+
+Observed: after F-0001 / US-0001 / TC-0001 existed and jobs were all
+passed, the run report still rendered Features / User Stories / Test
+Cases sections as "No records". The records existed in the project;
+they were simply not linked to the workflow run. To a reader the
+report looks like the work does not exist.
+
+### Direction (design before code)
+
+- Decide the intended scope of the run report sections: run-linked
+  records only, or run-linked plus goal-scoped records.
+- If run-linked only: label the sections accordingly ("No records
+  linked to this run") and consider linking records created during
+  the run window or referenced by ingested agent outputs.
+- Add a pointer line to the goal-level totals so an empty section is
+  never mistaken for an empty project.
+
+## Non-goals
+
+- No change to human-gate semantics for run verification (the gate is
+  correct; the skill now tells agents to stop and report it).
+- No autonomous verification recording.
+
+## Definition of done
+
+- Design note agreed for A and B (may be one doc).
+- Implementation + tests green (`python3 -m pytest`).
+- Live smoke against a scratch project showing (a) `pcl next` output
+  for a goal with in-flight direct work, and (b) a run report whose
+  empty sections are self-explanatory.
+- Evidence paths for all claims.

project_loop_harness-0.2.3/agent-tasks/0099-evidence-copy-mode.md

@@ -0,0 +1,76 @@
+# Task 0099: Evidence `--copy` Mode (v0.2.4, P1)
+
+Origin: approved design `docs/evidence-durability-design.md`
+(task 0097; all six decision points approved as recommended on
+2026-07-08). Demand signal: the master-trace context handoff plan
+needs transcripts (typically short-lived files under `.work/` or
+scratch directories) to survive workspace cleanup so a worker agent
+can read them later.
+
+Implements the design as specified. Where this file and the design
+doc disagree, the design doc wins.
+
+## Scope
+
+Add opt-in `--copy` to `pcl evidence add`.
+
+1. **Copy semantics.** After all 0096 guards pass, copy each member
+   to `.project-loop/evidence/adhoc-files/<evidence-id>/<NN>-<basename>`
+   (`NN` = two-digit member index). Stage copies in a temp directory;
+   move into place only after every member succeeds and before the DB
+   row/event are written. Re-hash each copy; a mismatch with the
+   source hash is a typed error with zero traces (same atomicity rule
+   as 0093/0096).
+2. **Manifest accounting.** Member-level `storage_mode: "copied"` and
+   `stored_path`. One mode per invocation — no mixed bundles.
+   Reference-mode members omit both fields; pre-existing manifests
+   stay valid (additive rule from 0096).
+3. **Drift semantics.** Copied members: health checks hash the copy
+   only. Missing/drifted copy → `warning` with new finding codes
+   `copy_missing` / `copy_hash_mismatch`. Original drifting →
+   informational finding `source_drifted`, no warning.
+4. **Guards compose.** Sensitive-shaped member + `--copy` still
+   requires `--allow-sensitive-evidence`; the copy inherits
+   `sensitive_pattern` and the combined warning text states that
+   copying amplifies exposure. Outside-root member + `--copy` keeps
+   `path_scope: outside_project` with the original path in the
+   manifest while `stored_path` holds the local copy.
+   `evidence.allow_outside_root: false` still blocks recording
+   entirely — configuration wins over copy.
+5. **Size discipline.** New config `evidence.copy_max_member_bytes`,
+   default 10 MB. Over cap → typed error
+   `evidence_copy_member_too_large` (zero traces). Over half cap →
+   `large_evidence_member` warning. Reference mode is untouched by
+   the cap.
+6. **Truthfulness wording.** `--help` and docs assert only: "at
+   record time, PLH wrote a byte-identical copy (same sha256) of the
+   file the caller named, to `stored_path`". "Durable" is always
+   scoped as "survives workspace cleanup on this machine".
+
+## Out of scope
+
+- `pcl evidence export` transfer bundles (future task; design doc
+  gitignore boundary option (c)).
+- Any change to the gitignore status of `.project-loop/evidence/`
+  (option (a) approved: local-only).
+- Default-copy behavior. Copying stays opt-in per invocation.
+- LLM calls, network access, new dependencies.
+
+## Definition of done
+
+- `pcl evidence add --copy` behaves as specified, including guard
+  composition, atomicity, and typed errors.
+- Health stats (0095) treat copied members as specified without
+  changing the "each evidence id hashed once per stats invocation"
+  cost model.
+- Tests cover: happy path single/multi member, staging atomicity on
+  mid-copy failure, hash-mismatch abort, sensitive × copy,
+  outside-root × copy, over-cap error, half-cap warning, drift
+  findings for copy vs original, manifest backward compatibility.
+- `docs/context-pack.md` untouched; `docs/evidence-durability-design.md`
+  status updated only if implementation deviates (it should not).
+- Update `docs/data-model.md` and command help where manifest fields
+  and config keys are user-visible.
+- `pytest` passes; `pcl validate --strict --json` passes;
+  `pcl init` smoke-tested against `/tmp/pcl-demo`.
+- Evidence paths recorded for all verification claims.

project_loop_harness-0.2.3/agent-tasks/0100-evidence-task-linking.md

@@ -0,0 +1,57 @@
+# Task 0100: Evidence-to-Task Linking in Task Context Packs (M1, P2)
+
+Origin: M0 master-trace dogfood (goal G-0002, 2026-07-08; runbook
+`docs/master-trace-handoff.md`). M0's workaround — writing evidence
+IDs and copied paths into the task description by hand — worked but
+is omission-prone: the throwaway reproduction (evidence E-0024)
+showed a task without description refs gets a context pack with no
+route to adhoc evidence at all. This is the deliberately-generic
+alternative to a `master_trace_context` pack section, which was
+considered and rejected (see the runbook's Discarded Options).
+
+## Scope
+
+1. `pcl evidence add --task T-XXXX` links the recorded adhoc
+   evidence row to an existing task. Invalid/unknown task id is a
+   typed error with zero traces (same atomicity discipline as
+   0093/0096/0099). Linking is optional; unlinked behavior is
+   unchanged.
+2. Task context packs gain a linked-evidence section listing, per
+   linked evidence row: id, type, summary, manifest path, member
+   path(s), `stored_path` when copied, and created_at. Do NOT inline
+   member file contents by default.
+3. The section is additive within `context-pack/v1` (same rule as
+   0067/0078): packs without linked evidence are byte-identical to
+   today's output.
+4. Section ordering and `--max-tokens` budgeting follow the existing
+   section-priority mechanism in `src/pcl/context.py`; document the
+   chosen priority in `docs/context-pack.md`.
+5. When linked evidence is model-derived (e.g. an intent index), the
+   pack must carry the existing "claims, not verified facts"
+   vocabulary — reuse the wording pattern from the code-context
+   summary sections.
+
+## Out of scope
+
+- Linking to goals/jobs (`--goal`/`--job`); job evidence already
+  flows through `_job_evidence`.
+- A first-class trace entity or `pcl trace` command family.
+- Retroactive linking of existing evidence rows (a separate
+  `pcl evidence link` can be a later task if demand appears).
+- Any DB migration beyond the minimal link column/table needed.
+
+## Definition of done
+
+- `pcl evidence add --task` round-trips: link recorded, visible in
+  `pcl context pack --task ... --json`.
+- Additive contract verified by a test asserting packs without links
+  are unchanged.
+- Tight `--max-tokens` budgets degrade the section per the documented
+  priority without breaking required sections.
+- `docs/context-pack.md`, `docs/data-model.md`, and command help
+  updated.
+- `pytest` passes; `pcl validate --strict --json` passes; `pcl init`
+  smoke-tested against `/tmp/pcl-demo`.
+- The M0 runbook (`docs/master-trace-handoff.md`) gets a short
+  "M1 landed" note updating the Known Hole and Next Decision
+  sections.

project_loop_harness-0.2.3/agent-tasks/0101-evidence-id-allocation-race.md

@@ -0,0 +1,49 @@
+# Task 0101: Evidence ID Allocation Race (defect, P1)
+
+Origin: observed in the field during the M0 dogfood (2026-07-08).
+A worker ingesting three agent outputs in parallel hit
+`UNIQUE constraint failed: evidence.id` on `J-0001`'s ingestion;
+retrying sequentially succeeded (allocated E-0030). The failure is
+in prefixed-ID allocation (`next_prefixed_id`): two connections read
+the same max id before either inserts, then both try to insert the
+same `E-XXXX`.
+
+This affects every entity that allocates through the same helper,
+not just evidence — audit the call sites (`src/pcl/ids.py` and
+callers) and state in the fix which entities were exposed.
+
+## Scope
+
+1. Make prefixed-ID allocation safe under concurrent writers. Two
+   acceptable shapes — implementer picks one and justifies it in the
+   task output:
+   - allocate inside an immediate/exclusive transaction so the
+     read-max and insert are atomic, or
+   - catch the UNIQUE failure and retry allocation a bounded number
+     of times.
+2. Whatever the shape, a failed attempt must leave zero traces
+   (no orphan manifest/copy artifacts, no partial events) —
+   the 0093/0096/0099 atomicity rule extends to retries. For copy
+   mode (0099) note the ordering hazard: copies land under a
+   directory named for the candidate evidence id *before* the DB row
+   is inserted, so an id retry must re-stage or rename the copy
+   directory, never leave one behind under the losing id.
+3. Add a concurrency regression test (multiprocessing or threads +
+   separate connections) that reliably reproduced the race before
+   the fix and passes after.
+4. Document the concurrency guarantee (or its limits) in
+   `docs/data-model.md`.
+
+## Out of scope
+
+- Switching to UUIDs or changing the human-readable ID format.
+- A general write-lock/daemon architecture.
+
+## Definition of done
+
+- The regression test fails on pre-fix code and passes post-fix.
+- Parallel `pcl evidence add --copy` invocations (the M0 failure
+  shape) succeed with distinct IDs and intact copies.
+- `pytest` passes; `pcl validate --strict --json` passes; `pcl init`
+  smoke-tested against `/tmp/pcl-demo`.
+- Evidence paths recorded for all verification claims.