project-loop-harness 0.5.2__tar.gz → 0.5.3__tar.gz

{project_loop_harness-0.5.2/src/project_loop_harness.egg-info → project_loop_harness-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-loop-harness
-Version: 0.5.2
+Version: 0.5.3
 Summary: Local control plane for agentic project development loops
 Author: Project Loop Harness Contributors
 License: MIT
@@ -189,8 +189,9 @@ exist, the project does not claim external adoption.
 - [Security](SECURITY.md) and [Contributing](CONTRIBUTING.md).
 
 Advanced contracts stay in `docs/`: completion packets, evidence sets,
-completion policy, context packs, code context, workflow execution, Council
-Profile, trace/resume, reports, migrations, and dashboard data.
+completion policy, [Harness Gap Reports](docs/gap-report-v1.md), context packs,
+code context, workflow execution, Council Profile, trace/resume, reports,
+migrations, and dashboard data.
 
 ## Local development
 

{project_loop_harness-0.5.2 → project_loop_harness-0.5.3}/README.md

@@ -154,8 +154,9 @@ exist, the project does not claim external adoption.
 - [Security](SECURITY.md) and [Contributing](CONTRIBUTING.md).
 
 Advanced contracts stay in `docs/`: completion packets, evidence sets,
-completion policy, context packs, code context, workflow execution, Council
-Profile, trace/resume, reports, migrations, and dashboard data.
+completion policy, [Harness Gap Reports](docs/gap-report-v1.md), context packs,
+code context, workflow execution, Council Profile, trace/resume, reports,
+migrations, and dashboard data.
 
 ## Local development
 

{project_loop_harness-0.5.2 → project_loop_harness-0.5.3}/agent-tasks/0199-v052-release-publication.md

@@ -1,6 +1,6 @@
 # 0199: v0.5.2 release preparation and publication
 
-- **Status:** Active; publication authorized
+- **Status:** Done; published and publicly verified
 - **Milestone:** v0.5.2 Reliability and Harness Minimization
 - **Priority:** P0
 - **Size:** M
@@ -44,4 +44,13 @@ uncollected external first-use cohort as adoption proof.
 
 ## Completion evidence
 
-- Pending publication and public-artifact verification.
+- Release commit: `bbe14cf5a8375e72eaa121c1b8a5a96362560d1d`
+- GitHub Release: `v0.5.2`
+- Green release-commit CI run: `29638815262`
+- Trusted Publishing run: `29639130354`, success
+- Public wheel SHA-256:
+  `d7f5dda21e721c3405e694991fa7bbc844f7a31daecb4572efd67c48ffc81048`
+- Public sdist SHA-256:
+  `529e2236628d70cef2efade82a4ff3017649658e960e6c5b3e8afc0e2f1f601b`
+- Clean public install, strict validation, render, and pipx update: passed
+- `docs/evidence/0199-v052-publication-closeout.md`

project_loop_harness-0.5.3/agent-tasks/0200-gap-report-contract.md

@@ -0,0 +1,83 @@
+# 0200: gap-report/v1 Harness Gap Evidence
+
+- **Status:** Complete
+- **Milestone:** Harness Engineering Feedback Loop
+- **Priority:** P0
+- **Size:** L
+- **Dependency:** 0146 Work Brief, 0197 Harness Ablation, strict Evidence resolvers
+- **Project Loop:** Goal `G-0058`, Task `T-0122`, Feature `F-0064`, Story `US-0062`, Test `TC-0135`
+- **DB schema:** remains 8
+
+## Goal
+
+Add the one missing layer identified while reviewing the Harness Engineering
+proposal: record the earliest failed handoff and a closed gap classification as
+immutable, target-bound Evidence. Candidate lessons stay isolated until a
+hash-bound human decision authorizes promotion; authorization must not claim
+that the lesson has already been applied to its durable owner.
+
+## Reviewed design corrections
+
+The inherited Cockpit plan is accepted with these corrections:
+
+1. Gap targets include observed execution boundaries (`workflow_run` and
+   `agent_job`) in addition to Goal, Task, Feature, and Defect targets.
+2. `pcl gap promote` records `gap_lesson_promotion_approved` with
+   `application_status=pending`; it never edits AGENTS.md, Skills, tests, or
+   other durable owners automatically.
+3. Read paths verify exactly one anchor event, one target link, canonical path
+   shape, regular-file identity, recorded bytes, and SHA-256 before returning a
+   healthy report or accepting promotion.
+4. Candidate lessons require cited Evidence before promotion so uncorroborated
+   producer self-report cannot become approved policy by implication.
+
+## Contract
+
+`gap-report/v1` is a producer-authored claim artifact with:
+
+- producer, timestamp, and a target;
+- optional related completion-packet / Evidence / Workflow Run references;
+- one `earliest_failed_handoff` with `stage` and `description`;
+- one closed `gap_class`:
+  `context`, `capability`, `domain_ownership`, `authority`, `proof`,
+  `feedback_delivery`, or `worker_limitation`;
+- zero or more candidate lessons in an object keyed by stable, structurally
+  unique `lesson_id` values, each with a proposed `durable_owner` and
+  supporting Evidence references.
+
+The diagnosis is a claim, not a fact. `worker_limitation` remains especially
+provisional; one report cannot establish a general model limitation.
+
+## CLI scope
+
+- `pcl contract validate --type gap-report/v1 FILE`
+- `pcl gap add FILE --summary ... [--dry-run]`
+- `pcl gap show --evidence E-XXXX`
+- `pcl gap list [--target TYPE:ID] [--gap-class CLASS]`
+- `pcl gap promote E-XXXX --lesson LESSON_ID --actor ... --reason ...`
+
+Human-mediated promotion records actor, recorder, Cockpit/conversation source,
+artifact hash, lesson digest, and pending durable-owner application. Non-human
+promotion and unhealthy or uncited lessons fail closed.
+
+## Acceptance
+
+1. Packaged JSON Schema and hand-written validator agree and reject unknown
+   fields, malformed IDs/real-date timestamps, invalid enums, duplicate raw
+   JSON lesson keys, and non-finite JSON.
+2. Add/dry-run/show/list are deterministic, target-bound, and zero-mutation on
+   failure; strict reads surface tampering instead of trusting the file path.
+3. Promotion is human-only, hash-bound, Evidence-corroborated, idempotent, and
+   explicitly pending application.
+4. Fresh `pcl init` installs a compact router contract once without adding a
+   parallel `.plh/`, HARNESS.md, or harness.yaml structure.
+5. No migration, dependency, completion-packet change, automatic durable-owner
+   write, hosted service, or `pcl harness review/improve` aggregator is added.
+6. Targeted tests, full pytest, Ruff, fresh-init/E2E smoke, strict validation,
+   audit check, render, and PCL completion proof pass.
+
+## Sources
+
+- Cockpit task `e22916a5` and reviewed plan
+- <https://github.com/lopopolo/harness-engineering>
+- Harness Engineering `Improve One Harnessed Job` playbook

project_loop_harness-0.5.3/agent-tasks/0201-gap-report-integrity-hardening.md

@@ -0,0 +1,43 @@
+# 0201: gap-report/v1 Integrity Hardening
+
+- **Status:** Complete
+- **Milestone:** Harness Engineering Feedback Loop
+- **Priority:** P1
+- **Size:** M
+- **Dependency:** 0200 Gap Report contract and Evidence flow
+- **Project Loop:** Goal `G-0059`, Task `T-0123`, Feature `F-0065`, Story `US-0063`, Test `TC-0136`
+- **DB schema:** remains 8
+
+## Goal
+
+Close the four integrity gaps found by the independent implementation review
+without expanding the Gap Report feature or changing completion semantics.
+
+## Corrections
+
+1. Create the artifact directory, temporary file, and final file through
+   canonical no-follow handles. Reject pre-existing directory, temporary-file,
+   or final-file symlinks without writing outside the project or mutating PLH
+   state.
+2. Make Schema and runtime validation agree on real UTC calendar timestamps.
+   Represent candidate lessons as an object keyed by `lesson_id`, and reject
+   duplicate raw JSON keys at load time so uniqueness is structural.
+3. Bind `artifact_sha256` to the exact stored bytes. Whitespace-only,
+   same-length changes must make the report unhealthy.
+4. Filter lists using the immutable class in the anchor event. Return both
+   `recorded_gap_class` and `artifact_gap_class`, and do not silently hide
+   records whose anchor class is invalid.
+
+## Acceptance
+
+1. Redirected artifact directory/temp/final paths fail with zero Evidence,
+   event, outbox, or link mutations and leave the external target unchanged.
+2. The packaged timestamp pattern and hand validator accept valid leap dates
+   and reject invalid dates and year zero; duplicate lesson keys fail loading.
+3. Same-size semantic-preserving byte drift produces
+   `artifact_hash_mismatch`.
+4. Artifact class tampering remains listed only under the recorded class and
+   exposes both recorded and artifact values.
+5. Targeted tests, full pytest, Ruff, source/wheel/sdist smoke, strict PLH
+   validation, audit check, and render complete with results recorded as
+   Evidence.

project_loop_harness-0.5.3/agent-tasks/0202-v053-local-release-preparation.md

@@ -0,0 +1,50 @@
+# 0202: v0.5.3 local release preparation
+
+- **Status:** Complete
+- **Milestone:** v0.5.3 Evidence Integrity and Harness Feedback
+- **Priority:** P0
+- **Size:** M
+- **Dependency:** 0200 Gap Report, 0201 Gap Report integrity hardening, event-anchored strict Evidence resolvers
+- **Project Loop:** Goal `G-0060`, Task `T-0124`, Feature `F-0066`, Story `US-0064`, Test `TC-0137`
+- **DB schema:** remains 8
+
+## Goal
+
+Prepare a reviewable local v0.5.3 release candidate containing the completed
+Evidence-integrity and Gap Report work. Keep publication as a separate,
+explicitly authorized operation.
+
+## Scope
+
+1. Align package, runtime, MCP fixture, task index, and release-note surfaces
+   on v0.5.3.
+2. Describe only commits actually included since public v0.5.2, preserving the
+   distinction between artifact integrity and factual validity.
+3. Run source QA, scratch-project validation/render, wheel and sdist contracts,
+   metadata checks, and a clean wheel-install smoke.
+4. Record artifact hashes and exact verification results as durable Evidence.
+5. Commit the complete local release candidate without tagging, pushing,
+   publishing, or changing pipx.
+
+## Invariants
+
+- No Git tag, push, GitHub Release, PyPI/TestPyPI upload, pipx mutation, or
+  external announcement.
+- No schema migration, dependency addition, hosted service, telemetry, or
+  unrelated repair.
+- Existing `.claude` session state and unrelated untracked files remain
+  untouched and outside the release commit.
+- Public v0.5.2 adoption documents remain historical v0.5.2 records; they are
+  not mechanically renamed to v0.5.3.
+
+## Acceptance
+
+1. `pyproject.toml`, `pcl.__version__`, CLI/MCP runtime output, wheel, and
+   sdist metadata agree on `0.5.3`.
+2. Ruff and the full pytest suite pass from the canonical source checkout.
+3. Fresh scratch init, strict doctor/validate, audit, and render pass using
+   the worktree source.
+4. Wheel and sdist build, `twine check`, extracted-sdist contract, and
+   clean-wheel init/strict-validate/render/Gap Report contract smoke pass.
+5. SHA-256 hashes, file sizes, commit boundary, known warnings, and publication
+   boundary are reviewable in a new write-once Evidence note.

{project_loop_harness-0.5.2 → project_loop_harness-0.5.3}/agent-tasks/README.md

@@ -116,7 +116,10 @@ implement from the spec file, not from prompt summaries.
 | 0197 | Layered harness minimization ablation | Harness Minimization | P0 | done (`modify`) |
 | 0197b | Layered ablation fixture materializer | Harness Minimization | P0 | done |
 | 0198 | Evidence-gated direct-flow reduction | Harness Minimization | P1 | done; not implemented after `modify` verdict |
-| 0199 | v0.5.2 release preparation and publication | v0.5.2 Reliability and Harness Minimization | P0 | active; publication authorized |
+| 0199 | v0.5.2 release preparation and publication | v0.5.2 Reliability and Harness Minimization | P0 | done; published and publicly verified |
+| 0200 | `gap-report/v1` Harness Gap Evidence | Harness Engineering Feedback Loop | P0 | done |
+| 0201 | `gap-report/v1` Integrity Hardening | Harness Engineering Feedback Loop | P1 | done |
+| 0202 | v0.5.3 local release preparation | v0.5.3 Evidence Integrity and Harness Feedback | P0 | done; local RC ready, not published |
 
 v0.3.0 dispatch order: **0113 + 0114 in parallel** (independent; different
 `evidence.py` surfaces) → **0108** (needs 0113 merged) → **0115** (freezes the
@@ -196,6 +199,10 @@ external first-use cohort remains open and no adoption claim is made. Task
 **0199** prepares, publishes, and verifies the reliability release under the
 owner's separate publication instruction.
 
+v0.5.3 packages event-anchored strict Evidence resolution and the bounded
+`gap-report/v1` feedback layer. Task **0202** prepares and verifies the local
+release candidate; tagging, pushing, and public publication remain separate.
+
 ## Planned next (see growth plan for scope)
 
 | Milestone | Theme |
@@ -211,6 +218,7 @@ owner's separate publication instruction.
 | v0.5.1 | Trace & Efficient Handoff: source-bound claims-not-facts handoff plus controlled cross-session/runtime resume evidence |
 | post-v0.5.1 | Behavior-preserving staged CLI split; 0184 presentation, then 0185 guide, 0186 loop status, 0187 doctor, and 0188 report-artifact handlers |
 | v0.5.2 | 0189 config-ready adoption and frozen cohort → 0190 participant kit and deterministic proof evaluator → five-user outcome cohort → observed-friction repair |
+| v0.5.3 | strict copied-Evidence resolution → 0200 Gap Report contract → 0201 integrity hardening → 0202 local release candidate |
 
 Everything with an ID below 0102 is completed design history; see `TASKS.md`
 for the one-line summary of each.

{project_loop_harness-0.5.2 → project_loop_harness-0.5.3}/docs/command-guide.md

@@ -28,3 +28,19 @@ The guide is available before `pcl init` and does not create `.project-loop`.
 It complements `pcl next --json`: use `guide` to learn a purpose-oriented route
 and `next` to read the authoritative recommendation for the current project
 state.
+
+## Record a repeated harness failure
+
+When a bounded trajectory exposes an environment problem rather than only a
+product defect, validate and record a `gap-report/v1`:
+
+```bash
+pcl contract validate --type gap-report/v1 gap-report.json --json
+pcl gap add gap-report.json --summary "Earliest failed handoff" --dry-run --json
+pcl gap add gap-report.json --summary "Earliest failed handoff" --json
+pcl gap list --target task:T-0001 --gap-class context --json
+```
+
+Candidate lessons remain claims. `pcl gap promote` requires hash-bound human
+provenance and records approval with durable-owner application still pending.
+See [Gap Report v1](gap-report-v1.md).

project_loop_harness-0.5.3/docs/evidence/0199-v052-publication-closeout.md

@@ -0,0 +1,60 @@
+# 0199 v0.5.2 publication closeout
+
+**Verified:** 2026-07-18
+
+**Outcome:** published and publicly verified
+
+## Immutable source chain
+
+- Release commit: `bbe14cf5a8375e72eaa121c1b8a5a96362560d1d`
+- Annotated tag object: `7643ce5ff982c79822dcef9dcf77396f55f9cc7a`
+- Tag target: `bbe14cf5a8375e72eaa121c1b8a5a96362560d1d`
+- GitHub Release:
+  `https://github.com/mocchalera/project-loop-harness/releases/tag/v0.5.2`
+- Release published at: `2026-07-18T09:25:20Z`
+- Release is neither draft nor prerelease.
+
+## CI and publication
+
+- The first candidate CI run `29638536535` failed because the newly frozen
+  ablation tests could not resolve historical commits from a shallow checkout.
+  `docs/evidence/0199-v052-ci-history-repair.md` records the bounded workflow
+  repair; no runtime or test expectation was weakened.
+- Release-commit CI run `29638815262`: success across Python 3.10, 3.11, 3.12,
+  and 3.13; Ubuntu/Windows MCP conformance; Windows CLI smoke; build; Twine;
+  installed CLI smoke; and sdist contracts.
+- Release-triggered Trusted Publishing run `29639130354`: success.
+- Build-distributions job `88066532078`: success.
+- Publish-to-PyPI job `88066563827`: success.
+
+## Public PyPI artifacts
+
+PyPI reports `project-loop-harness 0.5.2`, `Requires-Python >=3.10`, one wheel,
+and one sdist. Downloaded bytes matched PyPI JSON digests.
+
+| Artifact | Size | Uploaded | SHA-256 |
+| --- | ---: | --- | --- |
+| `project_loop_harness-0.5.2-py3-none-any.whl` | 487878 | `2026-07-18T09:26:10.519255Z` | `d7f5dda21e721c3405e694991fa7bbc844f7a31daecb4572efd67c48ffc81048` |
+| `project_loop_harness-0.5.2.tar.gz` | 1401906 | `2026-07-18T09:26:12.162754Z` | `529e2236628d70cef2efade82a4ff3017649658e960e6c5b3e8afc0e2f1f601b` |
+
+## Clean public install
+
+A new Python 3.13 venv installed
+`project-loop-harness==0.5.2` from PyPI with `--no-cache-dir` and no
+`PYTHONPATH`:
+
+- `pcl --version`: `pcl 0.5.2`;
+- `pcl init` on a fresh temporary project: passed;
+- `pcl validate --strict --json`: `ok: true`, no errors or warnings;
+- `pcl render --json`: generated dashboard HTML and JSON successfully.
+
+The existing pipx installation was upgraded from 0.5.1 to 0.5.2 and both
+`pcl` and `pcl-mcp` are registered. Pipx separately reported an invalid
+interpreter for unrelated package `haconiwa`; no repair was attempted because
+it is outside this release.
+
+## Claim boundary
+
+The external five-person first-use cohort is still unrun. This release proves
+artifact integrity and engineering verification only; it does not prove user
+adoption, activation thresholds, or seven-day reuse.

project_loop_harness-0.5.3/docs/evidence/0201-gap-report-integrity-hardening.md

@@ -0,0 +1,39 @@
+# 0201 Gap Report Integrity Hardening Evidence
+
+Date: 2026-07-19
+
+## Review findings closed
+
+1. Gap Report artifacts are created through canonical directory descriptors;
+   directory, temporary-file, and final-file symlinks fail before any external
+   write or PLH mutation.
+2. `candidate_lessons` is an object keyed by `lesson_id`, duplicate raw JSON
+   keys fail during loading, and the packaged timestamp pattern accepts only
+   real UTC dates at second precision.
+3. The anchor hash covers the exact stored UTF-8 bytes, so same-size,
+   whitespace-only drift is detected.
+4. Class filtering uses the immutable anchor value and exposes separate
+   `recorded_gap_class` and `artifact_gap_class` fields.
+
+## Verification
+
+- `PYTHONPATH=src pytest -q tests/test_gap_reports.py`
+  - passed: 27
+- `PYTHONPATH=src pytest -q tests/test_gap_reports.py tests/test_contract_cli.py tests/test_evidence_add.py tests/test_evidence_show.py tests/test_evidence_sets.py tests/test_cli_init.py tests/test_distribution.py`
+  - passed: 128
+- `PYTHONPATH=src pytest -q`
+  - passed: 1160
+  - skipped: 1
+- `ruff check .`
+  - passed
+- `python -m build --outdir /tmp/pcl-gap-0201-dist.JtvmwW`
+  - built wheel and sdist successfully
+  - emitted pre-existing setuptools license-metadata deprecation warnings
+- `python scripts/verify_sdist_contracts.py --dist-dir /tmp/pcl-gap-0201-dist.JtvmwW`
+  - passed; unpacked-sdist contract test: 1 passed
+- isolated wheel install at `/tmp/pcl-gap-0201-wheel.vvioRV`
+  - `pcl --help`: passed
+  - `pcl contract validate --type gap-report/v1 tests/fixtures/gap_report/minimal.json --json`: `ok: true`
+
+No dependency, migration, hosted service, external publication, or automatic
+durable-owner write was added.

project_loop_harness-0.5.3/docs/evidence/0202-v053-local-release-preparation.md

@@ -0,0 +1,101 @@
+# 0202 v0.5.3 local release-candidate verification
+
+**Verified:** 2026-07-20
+
+**Candidate base before the release commit:**
+`287ea03e1697f0ca408a7cc488ad28e00dd1bd4b`
+
+**Outcome:** local release candidate ready for independent review; not
+published
+
+## Version and scope
+
+- `pyproject.toml`, `pcl.__version__`, CLI output, MCP transcript fixture,
+  wheel metadata, and sdist metadata resolve to `0.5.3`.
+- The candidate packages event-anchored strict Evidence resolution, the
+  `gap-report/v1` contract, and Gap Report integrity hardening completed after
+  v0.5.2.
+- DB schema remains 8. Runtime dependencies remain empty; optional development
+  and MCP-test dependencies are unchanged. Python metadata remains `>=3.10`.
+- The remote `v0.5.2` tag exists and GitHub reports v0.5.2 as the latest
+  published release. No remote state was changed.
+
+## Source verification
+
+- `python -m ruff check .`: passed.
+- `PYTHONPATH=src pytest -q`: 1160 passed, 1 skipped in 264.52 seconds.
+- The first full run identified only the expected version snapshot delta. The
+  current-contract snapshot and its intentional-change log were updated from
+  `0.5.2` to `0.5.3`; the focused baseline test then passed 2 tests and the
+  final full run passed.
+- `PYTHONPATH=src python -m pcl --root . validate --strict --json`: `ok: true`,
+  with 3 active and 26 historical pre-existing warnings.
+- `PYTHONPATH=src python -m pcl --root . render --json`: passed.
+- `git diff --check`: passed.
+
+Repository `pcl audit check --json` remains `issues_found` with 55
+human-review Evidence reconciliation findings: 3 current Evidence corruption,
+50 source-drift findings with healthy durable copies, and 2 superseded
+historical drift findings. These pre-existing repository-history findings were
+not repaired or weakened during release preparation; the new scratch projects
+both produced clean audits.
+
+## Scratch-project verification
+
+An initial truly empty scratch at
+`/tmp/pcl-v053-source-smoke.ZZbGfY` correctly failed strict doctor because the
+generic template retains `CHANGE_ME`, empty commands, and no finish check. A
+new detected Python project at `/tmp/pcl-v053-source-ready.tNQX21` then passed:
+
+- init dry-run and apply;
+- strict doctor and strict validation with zero findings;
+- clean audit with 9 matching SQLite/JSONL events and zero anomalies;
+- deterministic dashboard render.
+
+This preserves the empty-generic-project safety contract while proving the
+config-ready first-use path.
+
+## Build and artifact verification
+
+Final artifacts were built in `/tmp/pcl-v053-final-dist.bBJHhD` after the
+release note and task status were finalized.
+
+| Artifact | Bytes | SHA-256 |
+| --- | ---: | --- |
+| `project_loop_harness-0.5.3-py3-none-any.whl` | 504394 | `73aa2a34de1c07ddb12e22da477eb41b66e725e036b0252cd5eda94bee2211e7` |
+| `project_loop_harness-0.5.3.tar.gz` | 1471601 | `5e18bfeedf7a22153b0c01b6f80fb93cf502bd4318e7557a8a4564a1285d4234` |
+
+- `python -m build`: passed for wheel and sdist.
+- `python -m twine check`: passed for both artifacts.
+- `python scripts/verify_sdist_contracts.py --dist-dir
+  /tmp/pcl-v053-final-dist.bBJHhD`: passed; extracted-sdist contract test passed 1
+  test.
+- The sdist contains Task 0202 and the v0.5.3 release note.
+- Wheel metadata reports project version `0.5.3`, Python `>=3.10`, and no
+  unconditional `Requires-Dist` entry.
+
+## Clean-wheel smoke
+
+A new isolated environment at `/tmp/pcl-v053-final-wheel.7Yn5Nc` installed the
+final wheel with `--no-deps` and `PYTHONPATH` removed.
+
+- CLI, import, and installed metadata all reported `0.5.3`.
+- Packaged `gap-report/v1` validation accepted the minimal fixture.
+- Config-ready init dry-run and apply passed.
+- Strict doctor and strict validation returned zero findings.
+- Audit was clean with 9 matching SQLite/JSONL events and zero anomalies.
+- Dashboard render passed.
+
+## Residual risks and publication boundary
+
+- Local verification used macOS arm64 and Python 3.13.12. The Python 3.10-3.12
+  and Windows CI matrix was not rerun locally; Windows-specific secure Gap
+  Report file creation therefore remains dependent on remote CI/review.
+- Setuptools emitted the existing license TOML-table and classifier
+  deprecation warnings with a 2027-02-18 deadline. Artifact construction and
+  Twine checks passed.
+- Artifact hashes identify this local candidate build. A separately authorized
+  publication flow must rebuild or byte-compare final artifacts from the
+  reviewed release commit.
+- No Git tag, push, GitHub Release, PyPI/TestPyPI upload, pipx mutation, or
+  external announcement was performed.

project_loop_harness-0.5.3/docs/gap-report-v1.md

@@ -0,0 +1,137 @@
+# Gap Report v1
+
+`gap-report/v1` records one producer's diagnosis of the earliest failed
+handoff in a bounded agent trajectory. It adds a feedback layer above existing
+Work Brief, Evidence, approval-provenance, and completion-packet contracts; it
+does not create a second harness directory or alter completion semantics.
+
+The design adapts the bounded loop in the Harness Engineering
+[Improve One Harnessed Job](https://github.com/lopopolo/harness-engineering/blob/trunk/playbooks/improve-harness.md)
+playbook to PLH's existing local state and Evidence model.
+
+## Trust boundary
+
+- A valid report is a producer-authored claim, not a verified fact.
+- `earliest_failed_handoff` and `gap_class` remain diagnoses. Shape validation
+  does not prove that the producer found the true earliest cause.
+- `worker_limitation` is provisional. One trajectory cannot establish a
+  general worker limitation.
+- A candidate lesson is isolated from project policy until a human-origin
+  decision approves promotion against the recorded artifact hash.
+- Promotion approval does not apply the lesson. The event always records
+  `application_status: pending`; a later authorized task must update the
+  named durable owner through its normal workflow and proof boundary.
+- PLH never writes AGENTS.md, Skills, tests, APIs, or runbooks automatically
+  from a Gap Report.
+
+## Contract fields
+
+Top-level fields are strict; unknown fields fail closed.
+
+- `contract_version`: exactly `gap-report/v1`.
+- `producer`: non-empty producer `name` and `version`.
+- `generated_at`: RFC 3339 UTC at whole-second precision ending in `Z`.
+- `target`: one existing `goal`, `task`, `feature`, `defect`, `workflow_run`,
+  or `agent_job` and its PLH ID.
+- `related` (optional): a completion `packet_id`, typed `evidence:E-NNNN`
+  references, or an existing Workflow Run ID.
+- `earliest_failed_handoff`: non-empty `stage` and `description`.
+- `gap_class`: one closed value:
+  `context`, `capability`, `domain_ownership`, `authority`, `proof`,
+  `feedback_delivery`, or `worker_limitation`.
+- `candidate_lessons`: an object keyed by unique `lesson_id` values. Each value
+  contains the lesson, proposed durable owner, and supporting typed Evidence
+  references. Duplicate JSON object keys are rejected while loading.
+
+Durable owners are closed to `agents_md`, `skill`, `types`, `api`, `tests`,
+`runbook`, `project_docs`, and `tool_error_message`. A new owner or gap class
+changes the protected v1 contract and requires schema, validator, fixture,
+documentation, and compatibility review.
+
+## Validate and record
+
+Validation is read-only and does not require an initialized project:
+
+```bash
+pcl contract validate --type gap-report/v1 gap-report.json --json
+```
+
+Recording validates the artifact and all target/related Evidence references
+before mutation. `--dry-run` performs the same preflight without writing a
+file, Evidence row, target link, event, or outbox record.
+
+```bash
+pcl gap add gap-report.json \
+  --summary "Release runbook was not discoverable" \
+  --dry-run --json
+
+pcl gap add gap-report.json \
+  --summary "Release runbook was not discoverable" \
+  --json
+```
+
+Recorded files use the canonical project-local path
+`.project-loop/evidence/gap-reports/e-nnnn-gap-report-v1.json`. The anchor event
+stores target, path, byte size, the SHA-256 of the exact stored UTF-8 bytes, gap
+class, and candidate count. Creation opens canonical directories without
+following symlinks, writes a new no-follow temporary file, and publishes it
+without overwriting an existing final path. The same normalized report cannot
+be recorded twice.
+
+## Inspect and filter
+
+```bash
+pcl gap show --evidence E-0002 --json
+pcl gap list --target task:T-0001 --gap-class context --json
+```
+
+Read paths require exactly one `gap_report_recorded` anchor and one
+`gap_report` target link. They verify the canonical path, reject symlinks and
+identity changes, read the recorded byte size once, revalidate the contract,
+and compare the exact stored-byte SHA-256 with the anchor. `--gap-class`
+filters by the anchor's immutable recorded class, while the current artifact
+class is returned separately as `artifact_gap_class`; tampering therefore
+cannot move a warning into another filter bucket. An unreadable or invalid
+anchor class is included in filtered results so the warning is not hidden.
+Findings remain visible as `health: warning`; unhealthy reports cannot
+authorize promotion.
+
+## Approve candidate promotion
+
+Candidate lessons need at least one existing supporting Evidence reference.
+Agent and system actors fail with `gap_lesson_human_approval_required`.
+
+The usual path is a conversational or Cockpit decision recorded by an agent:
+
+```bash
+pcl gap promote E-0002 \
+  --lesson lesson-release-route \
+  --actor human:owner \
+  --actor-kind human \
+  --recorded-by agent:codex \
+  --recorder-kind agent \
+  --source-kind cockpit \
+  --source-ref cockpit:<task-id> \
+  --reason "Reviewed the cited Evidence and approved promotion" \
+  --json
+```
+
+The append-only `gap_lesson_promotion_approved` event binds the human actor,
+recorder, source, report Evidence ID/hash, lesson ID/hash, supporting refs,
+durable owner, and `application_status: pending`. Repeating the same approval
+is idempotent. Changing the report or lesson invalidates the binding.
+
+## Compatibility and scope
+
+This feature keeps DB schema 8. Projects with no Gap Reports behave unchanged.
+`completion-packet/v1`, terminal-state rules, dashboard contracts, and legacy
+Evidence display semantics are unchanged. The packaged schema is available
+through `pcl.contracts.gap_report.gap_report_schema()`.
+
+The AGENTS.md and CLAUDE.md marker blocks are append-once. Fresh initialization
+gets the compact operating contract; existing initialized projects are not
+silently rewritten and must adopt the new router lines through an explicit,
+reviewed instruction update.
+
+Aggregation (`pcl harness review/improve`), automatic owner mutation, causal
+claims, telemetry, hosted storage, and external provider calls are outside v1.