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

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

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

project_loop_harness-0.4.0/agent-tasks/0134-completion-packet-v1-contract.md

@@ -0,0 +1,77 @@
+# 0134: completion-packet/v1 contract + validator + fixtures
+
+- **Status:** Approved（Wave B activation、DEC-0003 / `docs/plan-v0.4.0.md`）
+- **Milestone:** v0.4.0 Dogfood Operations + Three-command Wedge
+- **Priority:** P0
+- **Estimated size:** M
+- **Dependencies:** 0123 (merged — master-trace/v0 契約と同じ claims-not-facts 方針)
+- **Origin:** integrated roadmap bundle 0131（`docs/roadmap/integrated/agent-tasks-proposed/0131-completion-packet-v1-contract.md`）の repo 再採番。bundle の `schemas/completion-packet-v1.schema.json` と `examples/completion-packet-*.json` は**参照素材（planning proposal 権威）**であり、本 spec と実装レビューが契約の正。
+
+## Problem
+
+`pcl finish`（0120、plan-only）は close-out plan を作れるが、agent/runtime を
+またいで利用できる安定した完了 artifact がない。内部 DB row をそのまま公開
+すると schema migration と外部互換性が結合する。
+
+## Goal
+
+claim / check / diff / risk / outcome を表現する versioned completion packet
+contract、canonical serializer、validator、fixtures を実装する。runtime
+統合（finish からの emit）は 0135 で行い、本タスクは契約層のみ。
+
+## Scope
+
+1. `completion-packet/v1` JSON Schema を package data として追加する
+   （`pyproject.toml` の `[tool.setuptools.package-data]` に登録し、wheel から
+   読めることをテストする）。bundle schema の top-level fields
+   （contract_version / packet_id / producer / generated_at / outcome / target
+   / repository / changes / checks / claims / unverified_claims / risks /
+   human_decisions / next_action / verifier_provenance(optional)）を出発点に、
+   現行 PLH の entity model（Goal/Task/Evidence ID 形式）へ合わせて確定する。
+2. positive（minimal / full）+ negative fixtures。negative は期待 reason 付き。
+3. canonical serializer（deterministic ordering）+ schema validator。JSON
+   Schema library を新規依存に入れる場合は最小構成にし、入れない場合は既存
+   validation 方針（手書き validator）に合わせる — どちらを選んだか根拠を返す。
+4. claim-scoped proof level の決定論的計算 rule を pure module として定義する。
+5. packet ID / timestamp / diff hash の canonicalization を決める
+   （packet ID は content hash か random ID か — 選択と根拠を返す）。
+6. read-only 検証 surface: `pcl contract validate --type completion-packet/v1
+   <file>`（`--json` あり、stdout purity 維持、exit code contract 明記）。
+7. contract docs（versioning / field semantics / non-guarantees /
+   compatibility policy）。`docs/master-trace-intent-index.md` と同じ
+   claims-not-facts の trust model を明記する。
+
+## Invariants
+
+- 別モデル review だけで proof level L2 以上にしない。
+- 実行していない check を passed にしない（passed/failed/skipped/not_run/
+  timed_out を区別）。
+- budget exhaustion を completed outcome にしない。
+- packet generation はモデル（LLM）を呼ばない。
+- Evidence は本文でなく ref を既定にする。内部 DB primary key や private path
+  を必須 field にしない。
+- 既存 CLI / schema / migration に破壊的変更なし（本タスクは純追加）。
+
+## Non-goals
+
+- `pcl finish` runtime 統合（0135）。handoff packet（0137）。remote upload。
+  UI rendering。
+
+## Acceptance criteria
+
+- minimal/full fixtures が validator を通り、各 negative fixture が期待
+  reason で失敗する。
+- wheel を build し、install した環境から schema package data を読める。
+- proof calculator が claim/Evidence class から決定論的に同じ level を返す
+  （table test）。
+- outcome と critical claim proof の整合性 validator が negative を弾く。
+- `pcl contract validate` の stdout/exit code contract test がある。
+- ruff + full pytest green。
+
+## Agent execution protocol
+
+開始前: 対象 commit SHA、変更予定 path、既存 contract 群（context-pack/v1、
+master-trace/v0）の characterization 結果、scope 外事項。
+完了時: 変更概要と設計判断（schema library 採否、packet ID 方式、bundle
+schema からの差分）、全 test command と exit code、Acceptance 別根拠、
+未確認事項。「テストは通るはず」では close しない。

project_loop_harness-0.4.0/agent-tasks/0135-finish-emits-completion-packet.md

@@ -0,0 +1,81 @@
+# 0135: 既存 pcl finish を completion packet 生成へ拡張（後方互換）
+
+- **Status:** Approved（Wave B activation、DEC-0003 / `docs/plan-v0.4.0.md`）
+- **Milestone:** v0.4.0 Dogfood Operations + Three-command Wedge
+- **Priority:** P0
+- **Estimated size:** XL — 必要なら contract 層 / 実行層の 2 PR に分割してよい
+- **Dependencies:** 0134 (contract merged 前提)、0128/0131 (merged)
+- **Origin:** bundle 0132 の repo 再採番。ADOPTION.md 最小合意 4「既存
+  `pcl finish`（0120）を置き換えず拡張する」を前提とする。
+
+## Problem
+
+現行 `pcl finish` は plan-only（`finish_plan`、`src/pcl/commands.py:721`）+
+`--execute`（残 step なしのときだけ validate/render を実行する tail、
+`src/pcl/cli.py:1059`）。外部利用可能な packet、diff 固定、check Evidence、
+terminal outcome を一つの冪等 use case で生成する surface がない。
+
+## Goal
+
+既存 finish contract（help / JSON / exit code）を後方互換に保ちながら、
+safe plan → check 実行 → validation → completion packet 生成 → state commit
+までを opt-in で実行できるよう拡張する。
+
+## Scope
+
+1. **最初に現行 `pcl finish` を characterize する**（help / JSON / exit code /
+   既存 tests）。既定挙動は plan-only のまま変えない。
+2. 実行 mode は明示 opt-in（例: `--apply` / `--emit-packet`。`--execute` の
+   既存意味は維持し、migration 設計を返す）。`--dry-run` / `--json` /
+   non-interactive 確認 semantics を定義する。
+3. active target、base/head revision、dirty state、changed paths を解決する。
+   git diff hash は packet 生成時 snapshot と一致させ、finish 実行中の repo
+   変更を検出する。
+4. check plan は project config / policy から作り、実行前に表示する。
+   preconfigured check 以外の任意 command を暗黙実行しない。
+5. check 実行は guarded executor（0131 の `workflow guard` 実行基盤 /
+   `guarded_process.py`）を再利用し、stdout/stderr/exit code を Evidence 化
+   する（出力上限・redaction は 0131 contract に従う）。
+6. claim–Evidence binding、strict validation、human gate、budget 状態を確認
+   し、`completion-packet/v1`（0134）を content-addressed artifact として
+   Evidence store に保存する。
+7. packet ref / terminal state / event を**同一 transaction**で commit する
+   （0128 outbox 経由。raw SQL 禁止）。packet 生成後に state commit が失敗
+   した場合、orphan artifact を `pcl audit check` で検出可能にする（0129 の
+   anomaly 分類へ additive 追加）。
+8. 冪等性: 同一 state での再実行は既存 packet を返すか明示的 no-op。
+   NO_CHANGES / check 失敗（INCOMPLETE_VALIDATION）/ budget・human gate
+   block の各 outcome semantics を定義する。
+
+## Invariants
+
+- check 未実行を passed にしない。critical blocker を黙って override しない。
+- 同じ packet を重複して別完了として数えない。
+- 既存 finish の plan-only 既定・JSON contract・exit code を壊さない
+  （characterization test が証拠）。
+- LLM 呼び出しなし。自動 PR 作成なし。
+
+## Non-goals
+
+- handoff packet / resume（0137）。profile discovery（Wave C+）。cloud upload。
+
+## Acceptance criteria
+
+- clean success: checks + packet が Evidence 化され terminal outcome が
+  COMPLETED_VERIFIED になる。
+- check failure: INCOMPLETE_VALIDATION packet が残り、task/goal を completed
+  にしない。
+- budget / human gate block: 対応する incomplete outcome と next action。
+- no changes: NO_CHANGES を説明し、acceptance Evidence 不足なら active 維持。
+- unchanged completed state の再実行が重複完了を作らない（idempotency test）。
+- finish 実行中の repo 変更 race test。outbox/projector 失敗 path test。
+- 既存 finish regression suite green + ruff + full pytest green。
+
+## Agent execution protocol
+
+開始前: 対象 commit SHA と 0134 merge 済みの証拠、変更予定 path、現行 finish
+の characterization 結果、scope 外事項。
+完了時: 変更概要と設計判断（opt-in flag 設計、outcome semantics）、全 test
+command と exit code、各 outcome の example packet（Evidence ref）、CLI 互換
+性への影響、Acceptance 別根拠、未確認事項と rollback 方法。
+「テストは通るはず」では close しない。

project_loop_harness-0.4.0/agent-tasks/0136-lite-pcl-start.md

@@ -0,0 +1,75 @@
+# 0136: Lite `pcl start` entry point
+
+- **Status:** Approved（Wave B activation、DEC-0003 / `docs/plan-v0.4.0.md`）
+- **Milestone:** v0.4.0 Dogfood Operations + Three-command Wedge
+- **Priority:** P0
+- **Estimated size:** L
+- **Dependencies:** 0134 (merged — start receipt が packet 語彙と整合するため)
+- **Origin:** bundle 0133 の repo 再採番。
+
+## Problem
+
+初回利用者が Goal / Feature / Story / Task / Workflow の ontology を理解して
+から価値へ到達する構造は重い。明確な仕事を一つ始めるだけの集約 command が
+必要（M2 exit: 10 分以内・3 操作で有用 packet）。
+
+## Goal
+
+一つの自然言語 intent から、必要最小の project state と active work target
+を作り、次の agent action を返す `pcl start` を提供する。
+
+## Scope
+
+1. contract 設計: `pcl start "<intent>"`、`--dry-run`、`--json`、`--no-init`、
+   `--new`。`--profile` は Wave C（route/policy）導入前なので**受け付けない**
+   （将来 additive に追加できる extension point だけ設計する）。
+2. 未初期化 directory では、明示的な start 操作として最小 project 初期化を
+   行う（既存 `init_project`（`src/pcl/init_project.py:243`）を再利用）。
+   auto-init が作る files を dry-run で完全列挙する。
+3. 既存 project では最小 target を作る。作る entity は **Goal + Task**
+   （現行 model で task が goal に紐づくため）を推奨とするが、Task のみ案との
+   比較根拠を返して確定する。既存 creation service（`create_goal`
+   `src/pcl/commands.py:43`、`create_task` `src/pcl/tasks.py:37`）を再利用し、
+   raw DB write を増やさない。
+4. active work が既にある場合、重複作成せず resume / 明示 `--new` を案内する
+   （`pcl next` / `loop_status` の active 判定を再利用）。
+5. intent text / actor / repository revision / created IDs を start receipt
+   として Evidence + event に残す（0128 outbox 経由）。
+6. `--json` は confirmation 待ちをせず、created IDs / next action を stable
+   schema で返す（stdout purity）。最初の next action は agent-neutral な
+   text/JSON にする。
+
+## Invariants
+
+- 一回の start で重複 active work を作らない。
+- LLM 呼び出しなし。意味的な acceptance criteria を勝手に生成しない。
+- 既存 project files を暗黙上書きしない。dry-run は zero mutation
+  （DB/event count 不変を test で証明）。
+- 細かい既存 commands を廃止・変更しない（純追加）。
+- intent string を shell command や path として解釈しない
+  （escaping / unicode test 必須）。
+
+## Non-goals
+
+- Discovery questions / option 生成（Wave C+）。agent process 起動。
+  acceptance criteria 自動生成。README 導線の書き換え（v0.5.0）。
+
+## Acceptance criteria
+
+- empty repo: start dry-run が予定 files/state を列挙し mutation しない。
+- empty repo: start apply 後、active target と next safe action が返る。
+- 既存 active work で再 start すると duplicate を作らず resume 案内になる。
+  `--new` で明示的に追加できる。
+- `--json` が created IDs / next action を stable schema で返す（fixture）。
+- 3-command demo transcript（start → finish → resume の start 部分）と
+  time-to-first-value の手動計測 note を Evidence として残す。
+- uninitialized / initialized / active-work の matrix test、idempotency、
+  Windows path、CLI help/JSON snapshot。ruff + full pytest green。
+
+## Agent execution protocol
+
+開始前: 対象 commit SHA と 0134 merge 済みの証拠、変更予定 path、既存 init /
+goal / task creation service の characterization 結果、scope 外事項。
+完了時: 変更概要と設計判断（最小 entity の選択根拠、auto-init 既定の判断）、
+全 test command と exit code、created state/event audit、Acceptance 別根拠、
+未確認事項。「テストは通るはず」では close しない。

project_loop_harness-0.4.0/agent-tasks/0137-handoff-packet-pcl-resume.md

@@ -0,0 +1,78 @@
+# 0137: handoff-packet/v1 + read-only `pcl resume`
+
+- **Status:** Approved（Wave B activation、DEC-0003 / `docs/plan-v0.4.0.md`）
+- **Milestone:** v0.4.0 Dogfood Operations + Three-command Wedge
+- **Priority:** P0
+- **Estimated size:** L
+- **Dependencies:** 0135 (merged — latest completion/incomplete packet を選択
+  対象に含むため)
+- **Origin:** bundle 0134 の repo 再採番。bundle
+  `schemas/handoff-packet-v1.schema.json` / `examples/handoff-packet.json` は
+  参照素材、契約の正は本 spec と実装レビュー。
+
+## Problem
+
+session や model を変えると、利用者は会話履歴・diff・test 結果・decision を
+再説明する。現行 context pack（target-bound、0115/0132）は有用だが、再開の
+ための安定した外部 packet と単純な entry point がない。
+
+## Goal
+
+現在の work target を小さい handoff packet へ集約し、`pcl resume` で
+read-only に取得できるようにする。
+
+## Scope
+
+1. `handoff-packet/v1` schema / fixtures / validator を 0134 と同じ方式で
+   package 化する（`pcl contract validate --type handoff-packet/v1` に追加）。
+   bundle top-level fields（target / current_state / summary / verified /
+   unverified / decisions / blockers / risks / next_safe_action / context_refs
+   / intent_index_ref(optional) / budget_remaining(optional)）を出発点にする。
+2. `pcl resume [--target] [--format json|markdown] [--output]` を実装する。
+3. 選択 logic: current Goal/Task、latest completion/incomplete packet（0135）、
+   Decision、Evidence、blocker、risk。deterministic ordering と target-bound
+   link（0113/0116 の links / binding agreement）を使い、superseded/stale
+   判定（0114 drift、receipt freshness）を考慮する。
+4. **verified と unverified を分離する**。verified に入れられるのは Evidence
+   ref で裏づく claim のみ（claims-not-facts、DEC-0002 と同方針）。
+5. context refs に freshness/hash を付け、本文全量は既定で inline しない
+   （`master_trace_context` 0132 と同じ ref 方式）。packet size と omitted
+   sections を記録する（`token_estimation.py` charclass/v1 を再利用）。
+6. multiple active targets 時は勝手に選ばず candidate list を返す
+   （`context_pack_target_selection_required` の既存 pattern に合わせる）。
+7. read-only 保証: export file 以外の state を変更しない（DB hash / event
+   count 不変 assertion を test に入れる）。Markdown renderer は JSON contract
+   の派生であり source of truth にしない。`--json` stdout purity。
+
+## Invariants
+
+- resume は state を変更しない。full transcript を既定で含めない。
+- unverified claim を verified 欄へ入れない。
+- 複数 target を曖昧に自動選択しない。
+- LLM 呼び出しなし。agent 自動起動なし。
+
+## Non-goals
+
+- Master Trace の生成（既存 0123 契約の消費のみ。bundle 0145 相当の統合深化
+  は後続 wave）。remote sync。context embedding。agent-specific adapters。
+
+## Acceptance criteria
+
+- active / incomplete / completed target ごとに valid handoff packet を生成
+  できる（fixture matrix）。
+- **cross-session replay**: 別 session の test agent が packet だけから
+  documented next check を再実行できる（integration test または dogfood
+  Evidence）。
+- multiple target で exit/JSON が selection required を明示する。
+- packet 生成前後で DB/event count が変わらない（read-only assertion）。
+- Markdown と JSON が同じ verified/unverified semantics を持つ。
+- packet size / omission の記録 test。ruff + full pytest green。
+
+## Agent execution protocol
+
+開始前: 対象 commit SHA と 0135 merge 済みの証拠、変更予定 path、context
+pack / links / drift の characterization 結果、scope 外事項。
+完了時: 変更概要と設計判断（default target selection の扱い、Markdown
+renderer の安定性を contract に含めたか）、全 test command と exit code、
+sample handoff packets、Acceptance 別根拠、未確認事項。
+「テストは通るはず」では close しない。

project_loop_harness-0.4.0/agent-tasks/0138-kpi-report-surface.md

@@ -0,0 +1,101 @@
+# 0138: コスト KPI 集計 surface（`pcl report kpi`）
+
+- **Status:** Approved（v0.4.0 Dogfood Operations / `docs/plan-v0.4.0.md` §2b）
+- **Milestone:** v0.4.0 Dogfood Operations + Three-command Wedge
+- **Priority:** P1
+- **Estimated size:** M
+- **Dependencies:** なし（0134–0137 と並行可。packet 系指標は「未計測」表示で
+  先行実装し、0135/0137 merge 後に additive に埋まる設計にする）
+- **Origin:** growth plan v0.4.0（`docs/growth-plan-v0.2.4-v0.5.md` §3/§5）
+  由来。bundle 由来ではない。
+
+## Problem
+
+growth plan §5 のコスト KPI（テーゼ2 の証明）を dogfood report に書くための
+集計 surface がない。verification feedback stats
+（`src/pcl/verification_feedback.py:145` `verification_feedback_stats`、
+migration 005）は CLI から取れるが、context pack の token 推定は生成時に
+表示されるだけで**永続記録されない**（`src/pcl/context.py` は event を emit
+しない read-only 設計）ため、average_context_pack_tokens を後から集計できない。
+
+## Goal
+
+既存記録データの read-only 集計 command `pcl report kpi --json` と、集計に
+必要な最小の usage 記録を追加し、`docs/dogfood-report-v0.4.md` の実測値を
+機械的に再現可能にする。
+
+## Scope
+
+1. `pcl report kpi [--json] [--since <ISO date>]`（read-only）。growth plan
+   §5 の指標を section 化して返す:
+   - `verification_spend_efficiency`: execution_rate / executed_pass_rate /
+     feedback_coverage_rate（既存 `verification_feedback_stats` の再利用 +
+     executed_pass_rate × execution_rate の合成値）
+   - `context_pack`: 生成回数 / average_context_pack_tokens /
+     bound_receipt_coverage（bound receipt 付き生成の割合）
+   - `finish`: finish 実行回数 / packet outcome 分布 /
+     finish_roundtrips_saved の算出材料（0135 未 merge の間は
+     `not_yet_measured` を明示）
+   - `handoff`: resume/packet 生成回数（0137 未 merge の間は同上）
+   - 各指標に `data_source`（event type / table）と `window` を明記する。
+2. **context pack usage の明示 opt-in 記録**（DEC-0004、2026-07-10 設計確定。
+   characterization の結果、default-on の event 追加は既存 read-only 契約
+   — `tests/test_context.py::test_master_trace_context_contract_fixtures` が
+   pack 前後の events 件数 / `events.jsonl` bytes / outbox 完全一致を assert、
+   `docs/architecture.md` / `docs/context-pack.md` も明文化 — と両立せず、
+   さらに 0128 以降 event 書込みは write lock + outbox transaction を要する
+   ため read path の運用退行（Windows では mutation と直列化）になると判断）:
+   - `pcl context pack` の**既定挙動は完全 read-only のまま変えない**
+     （既存 test / docs は無修正で green のこと）。
+   - 新 flag `--record-usage` 指定時のみ、`context_pack_generated` event
+     （estimated_token_count / token_estimator / target / bound_receipt 有無 /
+     truncated 有無）を 0128 outbox 経由の通常 mutation transaction で
+     **正確に 1 件** emit する。event 内容は pack の成果物 selection に影響
+     しない。
+   - `--record-usage` 指定時に記録へ失敗した場合は明示的に失敗する
+     （silent skip 禁止）。
+   - docs（`docs/context-pack.md` / `docs/architecture.md`）へ additive に
+     「既定 read-only、usage 記録は明示 opt-in」を追記する。
+   - dogfood report 雛形と KPI report の `context_pack` section に、記録
+     coverage は opt-in 実行分に限られる旨（計測手順として dogfood では
+     `--record-usage` を常用する旨）を明記する。
+3. 未計測値の扱い: データが無い指標は `null` + `reason`（`not_yet_measured` /
+   `no_data_in_window`）を返す。**擬似精度禁止** — 推定値を実測値のように
+   出さない。master_brief_tokens_saved は transcript 比較の手動計測（dogfood
+   report 側）とし、この command では算出しない旨を docs に明記する。
+4. `docs/dogfood-report-v0.4.md` の**雛形**を追加する（KPI 表、計測手順、
+   2 repo 分の記入欄。実測値の記入は運用作業であり本タスクの scope 外）。
+
+## Invariants
+
+- report は read-only（DB/event count 不変 assertion）。
+- raw SQL を CLI 外へ公開しない。既存 stats API を再利用する。
+- LLM 呼び出しなし。telemetry / 外部送信なし（計測はすべて local）。
+- 既存 command の JSON contract を壊さない（event 追加は additive）。
+
+## Non-goals
+
+- master_brief_tokens_saved の自動算出。dashboards の過剰リッチ化。
+  KPI の閾値 gate 化（計測が先、判断は v0.4.0 exit review）。
+
+## Acceptance criteria
+
+- `pcl report kpi --json` が上記 section を stable schema で返す（fixture）。
+- verification 指標が `verification_feedback_stats` と一致する（同一 DB での
+  equality test）。
+- `--record-usage` 付き pack 成功時に `context_pack_generated` event が
+  正確に 1 件記録され、平均 token 集計が event から再現できる（統合 test）。
+  flag なしの pack は従来どおり zero mutation（既存 read-only test が無修正で
+  green）。`--record-usage` の記録失敗が明示的エラーになる test。
+- 未計測指標が null + reason で返る（0135/0137 前の状態を fixture 化）。
+- dogfood report 雛形が存在し、KPI 表の各行に計測手段が書かれている。
+- ruff + full pytest green。baseline fixture への影響があれば Intended
+  changes 節へ記録されている。
+
+## Agent execution protocol
+
+開始前: 対象 commit SHA、変更予定 path、context pack read-only test と
+verification stats の characterization 結果、scope 外事項。
+完了時: 変更概要と設計判断（event 追加の契約影響評価を含む）、全 test
+command と exit code、Acceptance 別根拠、未確認事項。
+「テストは通るはず」では close しない。

project_loop_harness-0.4.0/agent-tasks/0139-executable-resume-context.md

@@ -0,0 +1,130 @@
+# 0139: executable restart context for `pcl resume`
+
+- **Status:** Approved repair for `D-0001` / `F-0006`
+- **Milestone:** v0.4.0 Three-command Wedge exit repair
+- **Priority:** P0
+- **Estimated size:** M
+- **Dependencies:** 0135 and 0137 merged
+- **Evidence:** `E-0050` (Yohaku Dorobo real-task blind replay)
+
+## Problem
+
+The first real `start -> finish --emit-packet -> resume` dogfood produced a
+valid handoff packet quickly, but a fresh Codex reviewer judged it **NOT
+USEFUL** as a standalone restart packet. It exposed `DONE`, the completion
+outcome, revision, claims, and Evidence IDs, but did not expose a public way to
+resolve those IDs or the concrete commands behind the verified finish checks.
+For terminal targets, `next_safe_action.command` was `null` even though the
+completion packet already contained reproducible passed commands.
+
+The reviewer consequently had to inspect package scripts and explore the CLI.
+This fails the cross-session replay acceptance criterion in 0137 and blocks
+G-0007.
+
+## Goal
+
+Make a generated `handoff-packet/v1` executable enough for a fresh session to:
+
+1. identify the acceptance target without prior chat;
+2. resolve every surfaced Evidence ref through a documented read-only command;
+3. rerun at least one verified check directly from the packet;
+4. find bounded project-documentation and changed-path context without inlining
+   evidence bodies or full transcripts.
+
+## Scope
+
+### 1. Read-only Evidence metadata command
+
+Add:
+
+```text
+pcl evidence show E-XXXX [--json]
+```
+
+The command returns stable metadata already held by Project Loop: Evidence ID,
+type, summary, claimed command, recorded path, creation time, and, for supported
+manifest-backed Evidence, member/stored paths and hashes. It must not inline
+artifact bodies, execute the claimed command, or mutate DB/events/outbox/files.
+Unknown IDs return a typed input error.
+
+### 2. Additive `handoff-packet/v1` restart context
+
+Add an optional top-level `restart_context` object. Old valid v1 packets without
+this field remain valid. Generated packets include it with deterministic,
+bounded ordering:
+
+- `target_intent`: factual task description/title or goal title;
+- `acceptance_status`: `intent_only`, `work_brief_linked`, or `missing`;
+- `acceptance_ref`: the target work brief ref when one is actually recorded;
+- `target_review_command`: `pcl task read ... --json` or the corresponding goal
+  report command;
+- `verification_commands`: deduplicated reproducible completion checks, keeping
+  command, previous status, Evidence refs, and proof source;
+- `evidence_resolution_commands`: one `pcl evidence show ... --json` command per
+  referenced Evidence ID;
+- `changed_paths`: bounded paths from the selected completion packet;
+- `documentation_candidates`: bounded changed files whose basename is an
+  established project documentation shape such as `README*`, `CONTRIBUTING*`,
+  or files under `docs/`. These are navigation hints, not verified acceptance
+  facts.
+
+The contract must distinguish missing acceptance detail from verified facts. It
+must never infer a launch URL, claim a documentation candidate is authoritative,
+or promote a generic Evidence summary into `verified`.
+
+### 3. Executable next safe action
+
+For a terminal target with a valid completion packet, use the first
+deterministically ordered reproducible passed check as
+`next_safe_action.command`. If none exists, fall back to the existing review-only
+action with `command: null`. Open human decisions and explicit completion
+`next_action` continue to take precedence.
+
+### 4. Markdown and docs
+
+Render the restart context from the JSON packet. JSON remains the source of
+truth. Document Evidence metadata lookup and the trust boundary: commands are
+replay instructions sourced from the completion packet, not newly executed
+facts.
+
+## Invariants
+
+- `pcl resume` and `pcl evidence show` are fully read-only.
+- No evidence body or full transcript is inlined.
+- No shell command is invented from package files; replay commands come only
+  from the selected completion packet.
+- No acceptance criteria are invented. `intent_only` is explicit when no
+  work-brief link exists.
+- Existing `handoff-packet/v1` fixtures remain valid.
+- Deterministic order, content-derived packet ID, metrics, and size bounds remain
+  intact.
+- No schema migration, dependency, LLM call, agent launch, or remote operation.
+
+## Acceptance criteria
+
+- `pcl evidence show` resolves completion-packet and completion-check Evidence
+  metadata and has read-only fingerprint assertions.
+- A real-shaped completion packet yields deterministic verification commands,
+  Evidence resolution commands, target intent, changed paths, and README/docs
+  candidates.
+- A terminal resume packet exposes a non-null replay command when a reproducible
+  passed check exists.
+- A fresh-session integration test uses only `pcl resume` output and public CLI
+  commands from the packet to resolve Evidence and rerun a documented check.
+- Missing work brief remains explicit `intent_only`; it is not represented as a
+  complete acceptance specification.
+- Markdown and JSON preserve identical verified/unverified and restart-command
+  semantics.
+- Old handoff fixture validation, packet tamper checks, finish compatibility,
+  ruff, targeted tests, and the full pytest suite pass.
+
+## Agent execution protocol
+
+Before editing, characterize the Yohaku Dorobo failure in `E-0050`, the existing
+completion-packet check shape, Evidence table/manifest variants, and current
+read-only fingerprint tests. Keep changes to the smallest contract/CLI/docs/test
+surface required here.
+
+At completion, report the commit SHA, changed files, exact test commands/counts,
+sample JSON for `pcl resume` and `pcl evidence show`, read-only proof, backward
+compatibility proof, and unresolved limitations. Do not push or merge.

project_loop_harness-0.4.0/agent-tasks/0140-kpi-post-integration-sources.md

@@ -0,0 +1,57 @@
+# 0140: KPI post-integration data sources
+
+- **Status:** Approved release blocker
+- **Milestone:** v0.4.0 release candidate
+- **Priority:** P0
+- **Estimated size:** S
+- **Dependencies:** 0135 and 0137 merged
+
+## Problem
+
+`pcl report kpi` still labels finish and handoff metrics with
+`not_available_until_task_0135` and `not_available_until_task_0137` after both
+tasks have shipped. The wording is stale. Some finish metrics can now be derived
+from durable `completion_packet_created` events, while `pcl resume` intentionally
+remains read-only and records no execution event.
+
+## Goal
+
+Report the post-integration measurement truth without inventing data:
+
+- derive finish execution count and packet outcome distribution from
+  `completion_packet_created` events;
+- keep manually measured round-trip savings explicitly unavailable until a
+  comparison is recorded;
+- explain that resume and handoff generation counts are unavailable because the
+  read-only operation is not recorded.
+
+## Scope
+
+1. Query `completion_packet_created` events using the existing `--since` window.
+2. Return `finish_execution_count` as the event count and
+   `packet_outcome_distribution` as deterministic outcome counts.
+3. Return `null` plus `no_data_in_window` for the distribution when no finish
+   event exists in the selected window.
+4. Return `finish_roundtrips_saved: null` with
+   `manual_comparison_not_recorded` and a factual manual-comparison data source.
+5. Return both handoff metrics as `null` with
+   `read_only_operation_not_recorded` and a factual `pcl resume` data source.
+6. Update the stable empty fixture and add event/window regression coverage.
+
+## Invariants
+
+- `pcl report kpi` remains fully read-only.
+- `kpi-report/v1` section and metric names remain unchanged.
+- No resume telemetry, schema migration, dependency, external transmission, or
+  fabricated estimate is introduced.
+- Malformed recorded event payloads fail explicitly instead of being skipped.
+
+## Acceptance criteria
+
+- Empty repositories report finish count `0`, no-data distribution, manual
+  round-trip reason, and read-only handoff reasons without stale task IDs.
+- Multiple completion events produce a deterministic outcome distribution.
+- `--since` excludes older completion events.
+- DB size/counts and JSONL bytes remain unchanged by the report.
+- Targeted KPI tests, ruff, and the full test suite pass.
+