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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-loop-harness
-Version: 0.2.3
+Version: 0.2.4
 Summary: Local control plane for agentic project development loops
 Author: Project Loop Harness Contributors
 License: MIT
@@ -26,6 +26,8 @@ License-File: LICENSE
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: setuptools>=69; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
 Dynamic: license-file
 
 # Project Loop Harness

project_loop_harness-0.2.4/agent-tasks/0102-source-drift-health-warning.md

@@ -0,0 +1,62 @@
+# 0102: Source drift must surface as evidence health warning
+
+Milestone: v0.2.4 Trust Patch
+Priority: P1
+Area: evidence
+Origin: docs/project-loop-harness-v0.2.3-third-party-review.md P1-1 (verified against main)
+
+## Problem
+
+`_collect_copied_member_findings` in `src/pcl/evidence.py` emits `source_drifted`
+findings (detail `missing` or `size_mismatch`) when the original source of a
+copied evidence member has drifted. But `source_drifted` is not in
+`ADHOC_WARNING_FINDING_CODES` (evidence.py:36), so `_adhoc_assessment` returns
+`health: "ok"` when the only findings are `source_drifted`. Agents and humans
+read "ok" and miss the provenance/freshness problem.
+
+## Scope
+
+1. Add `"source_drifted"` to `ADHOC_WARNING_FINDING_CODES` in
+   `src/pcl/evidence.py`.
+2. Confirm the rendering path in `src/pcl/validators.py` (the
+   `elif code == "source_drifted":` branch around line 977) stays consistent
+   with the new classification — the finding text must keep re-rendering
+   identically through the shared `assess_adhoc_evidence` path (0095 pattern).
+3. Tests that pin the semantics:
+   - copied artifact intact + source file deleted → `health: "warning"` with a
+     `source_drifted` finding, `detail: "missing"`.
+   - copied artifact intact + source size mismatch → `health: "warning"` with
+     `detail: "size_mismatch"`.
+   - copied artifact intact + source intact → `health: "ok"` (no regression).
+   - copied artifact corrupted (`copy_hash_mismatch`) + source drifted →
+     still `warning` (both findings present, no double-count crash).
+4. `pcl validate --strict --json` must treat `source_drifted` as a warning that
+   remains a warning under strict (extend the existing
+   `_strict_warning_remains_warning` coverage), not an error, and must stay
+   green overall.
+
+## Invariants (what to protect, on the normal paths)
+
+- The copied artifact stays usable: no finding may remove or rewrite copied
+  files under `.project-loop/evidence/adhoc-files/`; assessment is read-only.
+- The findings array shape is additive-only: existing finding codes, their
+  `path`/`detail` fields, and their ordering semantics are unchanged.
+- Health values remain the existing three-level `ok | warning | error`; do not
+  introduce `artifact_health` / `source_health` split fields (explicitly
+  deferred by approval 2026-07-08).
+
+## Non-scope
+
+- artifact_health / source_health separation (deferred until dogfood
+  source_drift_rate data exists).
+- Schema or migration changes.
+- Context pack / dashboard surfacing changes beyond what the shared
+  assessment already propagates.
+
+## Acceptance
+
+- All tests above green; full `pytest` green.
+- Live smoke: create copied evidence in a scratch project, delete the source,
+  run `pcl validate --strict --json` → evidence health shows `warning`,
+  strict stays `ok: true`.
+- Release note entry describing the semantic change.

project_loop_harness-0.2.4/agent-tasks/0103-security-policy-v02x.md

@@ -0,0 +1,46 @@
+# 0103: SECURITY.md v0.2.x update and copied-evidence policy
+
+Milestone: v0.2.4 Trust Patch
+Priority: P1
+Area: docs/security
+Origin: docs/project-loop-harness-v0.2.3-third-party-review.md P1-2 (verified: SECURITY.md still says `0.1.x` while the released line is 0.2.x)
+
+## Problem
+
+SECURITY.md states the current public release line is `0.1.x`, contradicting
+the v0.2.3 release. Additionally, v0.2.3 introduced `pcl evidence add --copy`,
+which retains copies of source files under
+`.project-loop/evidence/adhoc-files/` — a new secret-retention surface that the
+security policy does not mention.
+
+## Scope
+
+Update `SECURITY.md` only (no code changes):
+
+1. Supported versions table: `0.2.x` = supported, `<0.2` = not supported.
+2. Add a "Copied evidence" section stating:
+   - `.project-loop/evidence/adhoc-files/` may contain copied sensitive source
+     files when `--copy` is used.
+   - Copied evidence must not be committed unless intentionally curated;
+     `.project-loop/` is gitignored by default and should stay so.
+   - Redaction is caller responsibility; `pcl` performs path-shape sensitive
+     guards (0096) but is not a secret scanner (established v0.1.11 decision —
+     keep this wording).
+   - MCP / read-only exposure must not reveal raw evidence contents by
+     default.
+   - Dashboard HTML is a human view, not a machine context source.
+3. Note that the release checklist (0106) will include a SECURITY.md
+   supported-versions check per release.
+
+## Invariants
+
+- Do not weaken any existing statement in SECURITY.md; changes are additive or
+  version-string corrections.
+- Keep the established epistemic vocabulary (claims-not-facts; no "scanned /
+  guaranteed secret-free" style assertions).
+
+## Acceptance
+
+- SECURITY.md shows `0.2.x` as the supported line.
+- Copied evidence risks and commit policy are stated.
+- `pytest` green (docs-only change; no test changes expected).

project_loop_harness-0.2.4/agent-tasks/0104-python-ci-matrix.md

@@ -0,0 +1,44 @@
+# 0104: Python 3.10–3.13 CI matrix
+
+Milestone: v0.2.4 Trust Patch
+Priority: P2
+Area: ci
+Origin: docs/project-loop-harness-v0.2.3-third-party-review.md P2-1 (verified: ci.yml pins `python-version: '3.11'` while pyproject classifiers list 3.10/3.11/3.12/3.13)
+
+## Problem
+
+`pyproject.toml` declares `requires-python = ">=3.10"` and classifiers for
+3.10–3.13, but CI runs a single Python 3.11. The advertised support range is
+not continuously verified.
+
+## Scope
+
+Update `.github/workflows/ci.yml`:
+
+1. Run lint + tests + smoke on a matrix of `["3.10", "3.11", "3.12", "3.13"]`:
+   - `ruff check .`
+   - `pytest`
+   - smoke: `pcl --version`; then in a fresh temp directory `pcl init`
+     (note: `pcl init` takes no positional argument, run it inside the temp
+     cwd), `pcl validate --strict --json`, `pcl render --json`.
+2. Keep build / twine check / sdist contract steps on a single canonical
+   version (3.12).
+3. Keep total CI time reasonable — matrix jobs run in parallel; do not add
+   new workflow files unless the existing one cannot express it.
+
+## Invariants
+
+- Existing CI steps (including the advisory retrieval eval step from 0080)
+  keep their current blocking/advisory semantics; the matrix must not turn an
+  advisory step into a blocking one or vice versa.
+- No changes to pyproject metadata, package code, or tests are expected. If a
+  Python-version-specific test failure surfaces, report it in the task output
+  rather than papering over it with skips — that finding is the point of this
+  task.
+
+## Acceptance
+
+- CI green on all four Python versions (verify with a branch push / PR run or
+  `gh run watch` after pushing the branch).
+- Classifiers and CI matrix agree.
+- Release note mentions the matrix result.

project_loop_harness-0.2.4/agent-tasks/0105-evidence-copy-observability.md

@@ -0,0 +1,51 @@
+# 0105: Evidence copy observability
+
+Milestone: v0.2.4 Trust Patch
+Priority: P2
+Area: evidence
+Origin: docs/project-loop-harness-v0.2.3-third-party-review.md P2-2
+Depends on: 0102 (both touch src/pcl/evidence.py — start after 0102 merges)
+
+## Problem
+
+v0.2.3 serialized evidence ID allocation to fix a concurrency race. When
+`evidence add --copy` copies large files, the copy work may extend the time a
+SQLite write transaction/lock is held. We have no measurements, so we cannot
+judge whether reserved-row or counter designs are ever needed. Observability
+first, redesign only if data demands it.
+
+## Scope
+
+1. Measure and record, for `pcl evidence add --copy` invocations:
+   - `copy_duration_ms` (wall time of the file-copy phase)
+   - `copied_total_bytes`
+   - `member_count`
+   These go into the `evidence_added` event payload (additive fields) via the
+   standard `append_event` path (both stores, per the 0089 lesson — no
+   JSONL-only or SQLite-only side channels).
+2. Where measurable without redesign, record lock-related diagnostics (e.g.
+   time spent inside the write transaction) as an additive payload field; if
+   it is not cleanly measurable, state so in the task output instead of
+   adding invasive instrumentation.
+3. Add a concurrent copy stress test: N parallel `evidence add --copy`
+   processes against one project must all succeed deterministically with
+   unique IDs (extend the existing 0101 race-test pattern).
+
+## Invariants
+
+- Timestamps/durations must not break determinism guarantees of existing
+  contracts: duration fields live only in event payloads, not in receipts,
+  context packs, manifests, or anything byte-compared by tests.
+- ID allocation semantics are unchanged (serialized allocation from 0101 is
+  kept as-is).
+- Non-`--copy` `evidence add` behavior and payload shape are unchanged
+  except for fields explicitly listed above being absent.
+- No new tables, no migration.
+
+## Acceptance
+
+- `evidence add --copy --json` emits an event whose payload includes the three
+  metrics; existing consumers/tests unaffected (additive-only).
+- Concurrent stress test green and deterministic across repeated runs.
+- Full `pytest` green; `pcl validate --strict --json` green after live copy
+  operations in a scratch project.

project_loop_harness-0.2.4/agent-tasks/0106-release-checklist.md

@@ -0,0 +1,21 @@
+# 0106: Release checklist contract
+
+Milestone: v0.2.4 Trust Patch
+Priority: P2
+Area: docs/release
+Origin: docs/project-loop-harness-v0.2.3-third-party-review.md PLH-0108
+Implementation: orchestrator-authored — deliverable is `docs/release-checklist.md`
+
+## Goal
+
+Make every release reproducible by contract, capturing the steps and traps
+already proven across v0.1.7–v0.2.3 releases.
+
+## Acceptance
+
+- `docs/release-checklist.md` exists and covers: version bump, release note,
+  ruff, pytest (matrix), editable-install sanity, build, twine check, sdist
+  contract verification, fresh-venv wheel smoke, `pcl validate --strict
+  --json`, `pcl render --json`, SECURITY.md supported-versions check, tag →
+  GitHub Release → trusted publishing → PyPI verification, local pipx update.
+- The v0.2.4 release is executed against this checklist.

project_loop_harness-0.2.4/agent-tasks/0107-agent-tasks-backlog-index.md

@@ -0,0 +1,20 @@
+# 0107: agent-tasks backlog index
+
+Milestone: v0.2.4 Trust Patch
+Priority: P3
+Area: docs/backlog
+Origin: docs/project-loop-harness-v0.2.3-third-party-review.md PLH-0109
+Implementation: orchestrator-authored — deliverable is `agent-tasks/README.md`
+
+## Goal
+
+Make the `agent-tasks/` directory navigable: distinguish active backlog from
+completed design history without duplicating `TASKS.md` (which stays the
+canonical ordered index).
+
+## Acceptance
+
+- `agent-tasks/README.md` exists: explains the spec-first workflow, points to
+  `TASKS.md` for the full history, and lists the active backlog with
+  milestone/priority/status.
+- New contributors and agents can find the next task from it.

project_loop_harness-0.2.4/agent-tasks/README.md

@@ -0,0 +1,35 @@
+# agent-tasks
+
+Spec-first backlog and design history for Project Loop Harness.
+
+Each file is one task spec: problem, scope, invariants ("what to protect",
+stated against the normal paths), non-scope, and acceptance criteria. Specs
+are committed to `main` **before** any worker starts implementing — workers
+implement from the spec file, not from prompt summaries.
+
+- **Canonical ordered index (all tasks, oldest first):** [`../TASKS.md`](../TASKS.md)
+- **Roadmap and milestone rationale:** [`../docs/growth-plan-v0.2.4-v0.5.md`](../docs/growth-plan-v0.2.4-v0.5.md)
+
+## Active backlog
+
+| ID | Title | Milestone | Priority | Status |
+|---|---|---|---|---|
+| 0102 | Source drift health warning | v0.2.4 Trust Patch | P1 | done |
+| 0103 | SECURITY.md v0.2.x + copied-evidence policy | v0.2.4 Trust Patch | P1 | done |
+| 0104 | Python 3.10–3.13 CI matrix | v0.2.4 Trust Patch | P2 | done |
+| 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) |
+
+## 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.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 |
+
+Everything with an ID below 0102 is completed design history; see `TASKS.md`
+for the one-line summary of each.

project_loop_harness-0.2.4/docs/growth-plan-v0.2.4-v0.5.md

@@ -0,0 +1,197 @@
+# Project Loop Harness 成長計画 v0.2.4 → v0.5.0
+
+**作成日:** 2026-07-08
+**作成者:** Fable 5（orchestrator）
+**入力:** docs/project-loop-harness-v0.2.3-third-party-review.md（第三者レビュー提言書）+ 実コード検証 + ax1-moc1 実使用フィードバック + 引き継ぎ履歴
+**ステータス:** DRAFT — 坂本承認待ち
+
+---
+
+## 0. 第三者レビューの精査結果
+
+レビューは「ローカル clone・テスト実行なし」と明記しているため、事実主張を実コード（v0.2.3 = main HEAD 0a6c1c2）で検証した。
+
+| レビュー主張 | 検証結果 |
+|---|---|
+| P1-1: `source_drifted` が warning codes に含まれず health が `ok` のまま | **事実**。`src/pcl/evidence.py:36` の `ADHOC_WARNING_FINDING_CODES` に `source_drifted` がない。findings は生成される（evidence.py:577-597）が `_adhoc_assessment` は ok を返す |
+| P1-2: SECURITY.md が `0.1.x` のまま | **事実**。SECURITY.md:8 |
+| P2-1: CI が Python 3.11 単独 vs classifiers 3.10–3.13 | **事実**。ci.yml:14 vs pyproject.toml:22-25 |
+| P2-3: code context receipt が target-bound でない | **事実**（0078 実装は latest receipt 解決。binding metadata なし） |
+| 提案タスク採番 PLH-0101〜0110 | **衝突**。agent-tasks/0100・0101 は既に使用済み → 本計画では 0102〜 に再採番 |
+
+レビューの方向性判断（local control plane 特化、hosted/telemetry/LLM-in-core の回避、Trust Patch 最優先）は、既存の承認済み方針（2026-07-04 方向性決定、0097 設計、epistemic 語彙規律）と整合しており採用する。
+
+**採用しない/修正する点:**
+
+1. **ユーザー満足度の軸が弱い。** レビューは trust / context binding に集中しており、実ユーザー（ax1-moc1）から出た摩擦 F4/F5/F7、坂本の「人間判断の日本語化・わかりやすい escalation」要望（Milestone 13）に触れていない。本計画では Operator Experience リリースを Master Trace 形式化より前に挿入する。
+2. **Master Trace は「新規構想」ではない。** docs/master-trace-handoff.md（M0）が既に存在し、既存コマンドだけで動く。v0.3.x での作業は発明ではなく契約の形式化 + context pack への optional section 追加に縮小できる。
+3. **コスト計測の解像度。** レビューの成功指標（§13）にコスト軸を追加する（後述 §5）。charclass/v1 token 推定器・0090 の token_cost_estimate という既存資産を handoff 経済の計測に転用する。
+
+---
+
+## 1. 戦略テーゼ — なぜこの製品が「これからの世界」で効くか
+
+前提とする世界観: **モデル性能は上がり続け、コスト管理は厳しくなり続ける。**
+
+### テーゼ1: 生成はコモディティ化し、信頼が希少資源になる
+
+モデルが賢くなるほど、agent が生み出す「主張」の量は増える。ボトルネックは生成ではなく **検証・監査・引き継ぎの信頼** に移る。PLH は生成の側に立たず（core は LLM を呼ばない）、claims-not-facts・evidence・receipt という検証の側に立つ。この設計はモデル進化に対して中立であり、worker が賢くなるほど pull-context 方式の効率が上がる — つまり **モデル性能向上がそのまま PLH の価値を増幅する**。
+
+### テーゼ2: output token が最も高価な世界では、push 型長文指示書が最大の浪費
+
+高性能 master agent に長文指示書を書かせるのは、最も高価な token（高性能モデルの output）の最も低付加価値な使い方である。PLH の pull 型 handoff（master transcript → evidence → intent-index → context pack → worker が pull）は、この支出を構造的に消す。さらに PLH 自体の限界トークンコストはゼロ（local / deterministic / dependency-light）。**コスト厳格化が進むほど、この差別化は強くなる。**
+
+### テーゼ3: 検証支出にも予算規律が要る
+
+「全部を毎回検証する」は賢いモデルの世界でもコスト的に成立しない。migration 005 の verification feedback loop（execution_rate / executed_pass_rate）は「どの検証提案が実行され、何が通ったか」を計測する基盤であり、検証支出の配分最適化に直結する。dogfood でこの数値を貯めることが v0.4 の本丸。
+
+### テーゼ4: ユーザー満足度は「境界の賢さ」と「摩擦の少なさ」で決まる
+
+実ユーザーの声が既にある: human gate（requires_human）は称賛され、epistemic 境界を弱める要望はゼロだった。一方で摩擦は「終端処理の認知負荷が実装より重い」（F7）、human-gate handoff 文面（F5）、オール英語表記。**満足度の最短経路は境界を緩めることではなく、境界の手前と後ろの体験を磨くこと**である。
+
+### ターゲットペインの再確認
+
+理想ユーザー = 複数 AI エージェントを指揮する AI 開発パワーユーザー / AI プロダクトオーナー（坂本さん自身）。ペインは:
+
+```text
+忘却     — agent が文脈・決定・却下案を忘れる / 拾い間違える
+暴走     — 承認なき破壊的操作、スコープ逸脱
+証拠不足 — 「done」の根拠が辿れない、レビュー不能
+高コスト — master の長文指示書、無駄な再検証、handoff やり直し
+終端負荷 — 完了処理・引き継ぎ処理の認知コストが人間に残る
+```
+
+PLH の一文: **AI coding agent に、忘れず・暴走せず・証拠を残して・次にやることを判断させるための local control plane。** — この定義（レビュー §4.1）を README / PyPI / 冒頭ピッチの正とする。
+
+---
+
+## 2. 品質 × コスト × 満足度のマッピング
+
+| リリース | 品質 | コスト | 満足度 |
+|---|---|---|---|
+| v0.2.4 Trust Patch | evidence 意味論の正しさ、CI 実証範囲 | copy lock 観測（並列 agent の待ち時間削減の前提データ） | 「表示が嘘をつかない」信頼 |
+| v0.3.0 Target-Bound Context | 誤 receipt による誤修正の防止 | handoff やり直しの削減 | worker への引き継ぎ不安の解消 |
+| v0.3.1 Operator Experience | human gate 判断品質（why_blocked の ja 化） | 終端処理の master token 削減（F7） | **本丸**: F5/F7/ja、坂本の願いに直結 |
+| v0.3.2 Master Trace 形式化 | intent-index の claims-not-facts 契約 | **本丸**: master output token の構造的削減 | 長文指示書からの解放 |
+| v0.4.0 Dogfood Operations | 実測に基づく信頼性実証 | コスト KPI の実測値（テーゼの証明） | 実運用 runbook |
+| v0.5.0 Adoption | 契約安定性ポリシー | — | 初見 3 分で価値理解 |
+
+---
+
+## 3. ロードマップ
+
+レビュー §8 を土台に、順序を 1 箇所変更（Operator Experience を Master Trace 形式化より前に挿入）し、実リポジトリの採番・既存資産に合わせて調整した。
+
+### v0.2.4 Trust Patch（最優先・小粒）
+
+目的: v0.2.3 の evidence durability を「表示が嘘をつかない」状態に固める。
+
+| タスク | 内容 | 由来 | サイズ |
+|---|---|---|---|
+| 0102 | `source_drifted` health 修正 — 短期は `ADHOC_WARNING_FINDING_CODES` への追加 + missing / size_mismatch テスト固定。artifact_health / source_health 分離は論点として温存（§6 論点2） | レビュー P1-1（検証済み事実） | S |
+| 0103 | SECURITY.md v0.2.x 更新 + copied evidence 機密リスク・commit policy・MCP exposure 明記 + release checklist に version check 追加 | レビュー P1-2（検証済み事実） | S |
+| 0104 | Python 3.10–3.13 CI matrix（pytest + smoke: `pcl --version` / `init` / `validate --strict --json` / `render --json`。build/twine は 3.12 単独） | レビュー P2-1（検証済み事実） | S |
+| 0105 | evidence copy observability — copy duration / copied bytes / member count を event metadata に、concurrent copy stress test。reserved-row / counter 方式への変更はしない（観測が先） | レビュー P2-2 | S-M |
+| 0106 | `docs/release-checklist.md` — 既存リリース手順（trusted publishing / fresh venv smoke / sdist contract / editable 指し先確認の罠を含む）を契約化 | レビュー PLH-0108 | S |
+| 0107 | `agent-tasks/README.md` — ID / status / milestone / priority の backlog index（orchestrator 執筆で可） | レビュー PLH-0109 | S |
+
+成功条件: source drift が warning 表示 / SECURITY.md 整合 / 3.10–3.13 matrix green / checklist に沿って v0.2.4 をリリース。
+
+### v0.3.0 Target-Bound Context
+
+目的: context pack を agent handoff の信頼できる契約に進化させる。「便利な CLI」から「handoff の制御層」への転換点。
+
+| タスク | 内容 | サイズ |
+|---|---|---|
+| 0108 | target-bound code context receipts — `pcl impact --diff --for-task T-XXXX / --for-job J-XXXX`、receipt に binding metadata（target_type / target_id / binding_strength）、`context pack --require-bound-receipt`、unbound latest fallback は warning | M-L |
+
+設計上の注意: receipt 契約は `code-context-summary/v0` 絶縁層（0078 承認済み設計）を崩さず additive に拡張する。staleness（working_tree_changed_since_receipt / receipt_age_seconds）は 0082 の relevance / receipt_age 資産を再利用。
+
+### v0.3.1 Operator Experience（レビューにない追加リリース）
+
+目的: 実ユーザーが表明した摩擦と坂本の願い（人間に判りやすい escalation）を潰す。満足度の本丸であり、F7 は master token 削減というコスト施策でもある。
+
+| タスク | 内容 | 由来 | サイズ |
+|---|---|---|---|
+| 0109 | `pcl finish` 集約コマンド — 終端処理（test pass --evidence → task 遷移 → jobs complete → report）の一括化。冪等（0092 資産）前提 | ax1-moc1 F7（最重要摩擦） | M-L |
+| 0110 | human-gate handoff 文面改善 + ja ローカライズ拡張 — `pcl next` の requires_human 出力に why_blocked / options / risk_if_run（0070 資産）を ja で | ax1-moc1 F5 + Milestone 13 + 坂本要望 | M |
+| 0111 | feature_coverage 既存カバレッジ検出で no-op | ax1-moc1 F4 | M |
+
+### v0.3.2 Master Trace / Intent Index v0 形式化
+
+目的: 既存の M0 dogfood ワークフロー（docs/master-trace-handoff.md）を契約に昇格し、pull 型 handoff のコスト優位を製品機能にする。
+
+| タスク | 内容 | サイズ |
+|---|---|---|
+| 0112 | `master-trace/v0` + `intent-index/v0` 契約 docs + context pack への optional `master_trace_context` section（trace_evidence_id / intent_index_evidence_id / trust_model: claims-not-facts / raw_transcript_inlined: false / source_paths）。LLM 呼び出しは core に入れない。raw transcript の inline 禁止 | M |
+
+first-class trace entity 化は v0.4 dogfood の結果を見てから判断（レビュー論点4 と同意見 — 早すぎる抽象化を避ける）。
+
+### v0.4.0 Dogfood Operations
+
+目的: テーゼ 2・3 を実測で証明する。機能追加より計測を優先。
+
+- PLH 自身 + 外部 repo（ax1-moc1 継続 or 新規）の 2 repo dogfood report（`docs/dogfood-report-v0.4.md`）
+- **コスト KPI の実測**: master_brief_tokens_saved（pull 型 vs push 型の比較実測）、average_context_pack_tokens、finish による終端 round-trip 削減数
+- verification feedback の実データ: execution_rate / executed_pass_rate / feedback_coverage_rate
+- handoff KPI: worker_handoff_success_rate / handoff_confusion_count / bound_receipt_coverage
+- Codex / Claude Code handoff runbook
+
+### v0.5.0 Adoption / Distribution
+
+- 0113: README split（レビュー PLH-0107 準拠: 30 秒ピッチ + 3 分 quickstart + docs/operator-manual.md / contracts.md / agent-handoff.md / internals.md へ分離）
+- JSON contract stability policy（論点3 の決定を文書化）
+- examples/ + Codex / Claude Code quickstart + `.project-loop` commit policy
+- **v0.4 の実測数値を README の訴求に使う**（「master の指示書 token を X% 削減」— 実測が最強のマーケティング）
+
+---
+
+## 4. やらないこと（レビュー §3.4 を承認済み方針として再確認）
+
+hosted backend / cloud sync / marketplace / telemetry / multi-user collaboration / 複雑な自動 scheduler / dashboard の過剰リッチ化 / core からの LLM API 呼び出し。
+
+追加: semantic search / embeddings の昇格は既存ゲート（eval fixture で lexical チューニング後も missing-critical-context が改善しない場合のみ）を維持。
+
+---
+
+## 5. 成功指標
+
+レビュー §13 の 4 分類（handoff / evidence 信頼性 / context pack 品質 / release 品質）を採用し、コスト軸を追加する。
+
+| コスト指標 | 意味 | 計測手段 |
+|---|---|---|
+| master_brief_tokens_saved | pull 型 handoff で master が書かずに済んだ output token | charclass/v1 推定器で transcript vs 従来指示書を比較 |
+| average_context_pack_tokens | handoff 1 回あたりの入力コスト | pack の token 推定（既存） |
+| finish_roundtrips_saved | `pcl finish` による終端コマンド往復削減数 | dogfood 実測 |
+| verification_spend_efficiency | executed_pass_rate × execution_rate（実行された検証が意味を持った割合） | migration 005 stats |
+| bound_receipt_coverage | 誤 context による手戻り（最も高価な失敗）の予防率 | v0.3.0 以降の pack 統計 |
+
+---
+
+## 6. 坂本の決定が必要な論点
+
+1. **ロードマップ順序**: Operator Experience（v0.3.1）を Master Trace 形式化（v0.3.2）より前に挿入する変更を承認するか。（推奨: 承認。F7 は実ユーザー最重要摩擦かつ M0 ワークフローは形式化前でも dogfood 可能）
+2. **evidence health の形**: 短期は `source_drifted` を warning codes に追加（0102）。中期の artifact_health / source_health 分離は additive contract 変更として v0.3.x で再検討。（推奨: 短期案のみ先行、分離は dogfood の source_drift_rate 実測後）
+3. **ID gap 許容**（レビュー論点2）: 現状維持し、0105 の観測データで判断。（推奨: 現状維持）
+4. **`.project-loop` commit policy**（レビュー論点5）: evidence/adhoc-files は commit しない現状を SECURITY.md（0103）に明文化。project.db / events.jsonl の扱いは v0.5.0 までに決定。
+5. **v0.2.4 リリース範囲**: 0102–0107 の 6 本で切るか。
+
+---
+
+## 7. 実行計画（Cockpit 委譲）
+
+実装は従来どおり codex worker（cockpit task、worktree 分離）へ委譲し、Fable が spec 起票と独立検収を行う。
+
+```text
+順序:
+  0103 + 0104 + 0107   並行可（互いに独立、S サイズ）
+  0102 → 0105          evidence.py を触るため直列
+  0106                 リリース直前に Fable 執筆でも可
+検収規律（確立済み）:
+  - spec は worker 着手前に main へコミット（0078 の教訓）
+  - 不変条件は「何を守るか」を正規経路・対象スコープ付きで書く（0087/0089/0090 の教訓）
+  - 検収は PYTHONPATH=worktree/src、終了後 canonical repo で pip install -e '.[dev]' 復元
+  - worker task complete 前に editable の指し先確認（v0.2.1 の罠）
+```
+
+v0.2.4 は全タスク S〜S-M のため、承認後 1〜2 セッションでリリース可能な見込み。

project_loop_harness-0.2.4/docs/release-checklist.md

@@ -0,0 +1,66 @@
+# Release Checklist
+
+Contract for every `project-loop-harness` release. Follow it in order; record
+the outcome of each step in the release note. Steps marked **(trap)** encode
+failures that actually happened in past releases — do not skip them.
+
+## 1. Pre-flight
+
+- [ ] All tasks for the milestone are merged to `main` and pushed; CI is green.
+- [ ] **(trap)** Editable install points at the canonical repo, not a deleted
+      worker worktree: `pip show project-loop-harness | grep Location` must
+      resolve under `~/Dev/project-loop-harness`. If not:
+      `pip install -e '.[dev]'` from the canonical repo. Symptom otherwise:
+      previously-green `main` suddenly fails ~6 executor/sandbox subprocess
+      tests with exit 1.
+- [ ] `SECURITY.md` supported-versions table matches the release line being
+      published.
+- [ ] `TASKS.md` lists every shipped `agent-tasks/` spec for this release.
+
+## 2. Version bump
+
+- [ ] Bump `version` in `pyproject.toml`.
+- [ ] `tests` do not hardcode the version string (`test_cli_version` reads
+      `pcl.__version__`); grep for the old version to catch strays:
+      `grep -rn "<old-version>" src/ tests/ pyproject.toml`.
+- [ ] Write the release note: scope, task IDs, semantic changes (e.g. evidence
+      health semantics), CI matrix result, verification evidence.
+
+## 3. Local verification
+
+- [ ] `ruff check .`
+- [ ] `pytest` (full suite) from the canonical repo.
+- [ ] `pcl validate --strict --json` → `ok: true` on a scratch project
+      (`pcl init` in a temp dir; note `pcl init` takes no positional argument).
+- [ ] `pcl render --json` succeeds on the scratch project.
+
+## 4. Build and packaging contracts
+
+- [ ] `python -m build` (sdist + wheel).
+- [ ] `twine check dist/*`.
+- [ ] sdist contract: unpack the sdist and confirm `docs/` and `agent-tasks/`
+      are included; `test_agent_adapter_docs_match_contract` passes from the
+      unpacked sdist. **(trap)** Inside the sdist, the 3 `test_distribution`
+      cases that depend on `.github/` / wheel build are expected to fail —
+      that is outside the contract and normal.
+- [ ] Fresh-venv wheel smoke: new venv → `pip install dist/*.whl` →
+      `pcl --version` → `pcl init` in a temp dir → `pcl validate --strict
+      --json` reports the expected schema version and `consistent: true`.
+      **(trap)** Run this smoke in a clean environment; a polluted
+      `PYTHONPATH` makes wheel-install tests fail spuriously.
+
+## 5. Publish
+
+- [ ] Tag `vX.Y.Z` on the release commit; push the tag.
+- [ ] Create the GitHub Release (not draft) with the release note.
+- [ ] Trusted publishing workflow publishes to PyPI — wait for completion.
+
+## 6. Post-publish verification
+
+- [ ] PyPI shows the new version as latest, with both wheel and sdist.
+- [ ] Fresh venv: `pip install project-loop-harness==X.Y.Z` →
+      `pcl --version` → init/validate smoke.
+- [ ] Update local pipx: `pipx upgrade project-loop-harness` (or install).
+      **(trap)** A stale pipx `pcl` shadows the editable install and has
+      caused old-schema `pcl migrate` runs against live DBs in the past.
+- [ ] Update the handoff memory / session log with the release record.

project_loop_harness-0.2.4/docs/release-notes/v0.2.4.md

@@ -0,0 +1,57 @@
+# v0.2.4 - Trust Patch
+
+Project Loop Harness v0.2.4 tightens the evidence trust surface from the
+v0.2.3 evidence durability release.
+
+Highlights:
+- `source_drifted` copied-evidence findings now surface as evidence health
+  warnings, so deleted or size-changed source files no longer render as
+  healthy provenance.
+- `SECURITY.md` now tracks the `0.2.x` release line and documents copied
+  evidence handling, commit policy, and read-only exposure expectations.
+- CI now runs the full suite across Python 3.10, 3.11, 3.12, and 3.13; the
+  Python 3.12 lane also builds distributions, runs `twine check`, and verifies
+  the sdist contract.
+- `pcl evidence add --copy` records additive copy observability metrics in the
+  evidence event payload: `copy_duration_ms`, `copied_total_bytes`,
+  `member_count`, and `write_transaction_pre_event_duration_ms`.
+- `agent-tasks/README.md` now reflects the v0.2.4 Trust Patch backlog status,
+  and `docs/release-checklist.md` is the release contract for future releases.
+
+Compatibility:
+- Schema migration: none.
+- No new runtime dependencies.
+
+Verification:
+- `python -m pip install -e '.[dev]'` installed
+  `project-loop-harness==0.2.4` from
+  `/Users/mocchalera/Dev/project-loop-harness`.
+- `python -m pcl --version` returned `pcl 0.2.4`.
+- `ruff check .` passed.
+- `python -m pytest` passed: 459 tests.
+- `PYTHONPATH=src python -m pcl validate --strict --json` returned `ok: true`
+  on the canonical repo state, with pre-existing local evidence warnings for
+  `E-0018` and `E-0025`.
+- Scratch project smoke passed: `pcl init`, `pcl validate --strict --json`,
+  and `pcl render --json`.
+- Latest `main` CI for `0df9bcb` passed across Python 3.10, 3.11, 3.12, and
+  3.13:
+  https://github.com/mocchalera/project-loop-harness/actions/runs/28929819418
+- Built sdist/wheel under `release-dist/v0.2.4`.
+- `python -m twine check release-dist/v0.2.4/*` passed.
+- `python scripts/verify_sdist_contracts.py --dist-dir release-dist/v0.2.4`
+  passed.
+- Fresh wheel venv smoke installed `project-loop-harness==0.2.4` and ran
+  `pcl --version`, `pcl init`, `pcl validate --strict --json`, and
+  `pcl render --json`.
+
+Release checklist status:
+- Pre-flight: complete for the current `main` commit. 0102-0107 are merged to
+  `main`, latest `main` CI is green, `SECURITY.md` tracks `0.2.x`, and
+  `TASKS.md` lists every shipped spec.
+- Version bump: complete locally. Version files are bumped to `0.2.4`; Python
+  source/tests have no remaining `0.2.3` version literals.
+- Local verification: complete.
+- Build and packaging contracts: complete.
+- Publish: pending human approval for tag, GitHub Release, and PyPI publish.
+- Post-publish verification: pending.

{project_loop_harness-0.2.3 → project_loop_harness-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "project-loop-harness"
-version = "0.2.3"
+version = "0.2.4"
 description = "Local control plane for agentic project development loops"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -35,7 +35,9 @@ Documentation = "https://github.com/mocchalera/project-loop-harness/tree/main/do
 [project.optional-dependencies]
 dev = [
   "pytest>=8",
-  "ruff>=0.6"
+  "ruff>=0.6",
+  "setuptools>=69",
+  "wheel"
 ]
 
 [project.scripts]

project_loop_harness-0.2.4/src/pcl/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.4"