project-loop-harness 0.4.3__tar.gz → 0.5.0__tar.gz

{project_loop_harness-0.4.3/src/project_loop_harness.egg-info → project_loop_harness-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: project-loop-harness
-Version: 0.4.3
+Version: 0.5.0
 Summary: Local control plane for agentic project development loops
 Author: Project Loop Harness Contributors
 License: MIT
@@ -34,23 +34,77 @@ Dynamic: license-file
 
 # Project Loop Harness
 
-Project Loop Harness is a local control plane for coding agents.
+> A local, model-neutral control plane that turns an agent's “done” into
+> reviewable Evidence, verification status, residual risk, and a resumable next
+> step.
 
-It is not just an Agent Skill. The core product is `pcl`, a small local CLI/runtime that gives Codex, Claude Code, and similar agents a guarded project-scoped loop: durable state in SQLite, append-only audit events in JSONL, generated prompts and evidence, strict validation, human-readable reports, and a deterministic dashboard.
+## Understand it in 30 seconds
 
-## Quick Start
+Coding agents are good at producing changes. They are less reliable at
+remembering project state, proving completion, stopping at human decisions, and
+handing work to another session or model.
 
-Install the published `pcl` CLI/runtime from PyPI with `pipx`:
+Project Loop Harness (`pcl`) gives Codex, Claude Code, and similar agents a
+shared local state machine:
+
+- SQLite keeps current state; JSONL keeps an auditable event projection.
+- Tests, artifacts, reviews, and completion packets preserve what “done” means.
+- Agents continue routine safe work; humans are asked only for genuine product,
+  permission, security, destructive, or external-service decisions.
+- The runtime does not call an LLM and does not depend on one agent vendor.
+
+It is designed for people coordinating multiple coding agents, not as another
+single-agent chat wrapper.
+
+## Get first value in five minutes
+
+### One-time operator setup
+
+Install the runtime, inspect the adoption plan, and initialize the repository:
 
 ```bash
 pipx install project-loop-harness
-pcl --version
-pcl --help
+cd /path/to/your-project
+pcl init --dry-run --json
+pcl init
 ```
 
+`pcl init` retains existing `AGENTS.md`, `CLAUDE.md`, and `.gitignore` content
+and appends its marked instruction block once. It also preserves an existing
+`pcl.yaml` by default. `--force` can replace generated templates such as
+`pcl.yaml`, workflows, the bundled Skill, and dashboard files; it does not
+replace existing project-instruction content. See the
+[Adoption Guide](docs/adoption-guide.md) for the exact file boundary.
+
+### After setup, tell the agent the outcome you want
+
+Copy this into Cockpit, Codex, Claude Code, or another coding-agent session:
+
+```text
+Read AGENTS.md, CLAUDE.md if present, and pcl.yaml. Use the Project Control
+Loop. Start this goal: <describe the outcome>. Continue every agent-safe next
+action, run the configured checks, preserve evidence, emit a completion packet,
+and close the goal. Do not ask me to run routine pcl commands. Stop only for a
+genuine human decision or external blocker.
+```
+
+The agent owns the routine `pcl start → implementation → finish → close` flow.
+The operator uses the CLI during setup or deliberate maintenance, not to
+manually advance every task.
+
+The project remains local-only by default. No telemetry, provider call, cloud
+sync, or automatic GitHub write is enabled by initialization.
+
+## Install and inspect in more detail
+
 Use `python -m pip install project-loop-harness` when installing inside a
 project-specific virtual environment or CI job instead of exposing the command
-globally.
+globally. Confirm the installed runtime with:
+
+```bash
+pcl --version
+pcl --help
+```
 
 For unreleased changes, install from a pinned GitHub tag or commit:
 
@@ -85,6 +139,10 @@ advisory warning alongside normal harness health checks. Set
 Then ask your coding agent to read `AGENTS.md`, `CLAUDE.md` if present, and
 `pcl.yaml`, run `pcl next --json`, and follow the next safe harness action.
 
+Compatibility promises for JSON contracts, typed errors, migrations, and
+internal surfaces are documented in the
+[Alpha Stability Policy](docs/stability-policy.md).
+
 ## Mental Model
 
 ```text
@@ -289,6 +347,39 @@ resolution as separate hash-bound Evidence. Task context, completion packets,
 and resume handoffs expose additive references without rewriting historical
 artifacts.
 
+## Council Profile (opt-in)
+
+Council is an external advisory boundary for ambiguous or high-risk work. It is
+not a model provider, executor, verifier, approval, or replacement for Direct.
+The Core prepares a deterministic request, validates and stores returned bytes,
+and keeps any proposed choice behind a human Decision:
+
+```bash
+pcl --json profile list
+pcl --json profile prepare council.discovery --target task:T-0001 --brief E-0001 \
+  --output /tmp/council-request.json
+pcl --json profile fixture-run --request /tmp/council-request.json --status completed \
+  --output-dir /tmp/council-output
+pcl --json profile ingest --request /tmp/council-request.json \
+  --bundle /tmp/council-output/profile-output-bundle.json --dry-run
+pcl --json profile ingest --request /tmp/council-request.json \
+  --bundle /tmp/council-output/profile-output-bundle.json
+```
+
+Real network or paid execution is outside Core and requires a hash-bound human
+authorization. `pcl profile authorize` only emits an authorized request; it
+never runs a provider. Revoke an authorization through the governed CLI, never
+by editing SQLite:
+
+```bash
+pcl --json profile authorize --revoke EV-XXXXXXXXXXXX --actor "human:owner" \
+  --recorded-by "agent:codex" --source-kind cockpit \
+  --source-ref "cockpit:<task-id>" --reason "Withdraw provider scope"
+```
+
+See [docs/council-profile.md](docs/council-profile.md) for the operator flow,
+privacy boundary, status handling, and adoption constraints.
+
 ## Evidence Sets
 
 Use `evidence-set/v1` when one passing artifact is not enough and the target
@@ -509,10 +600,14 @@ pcl report run --root /tmp/pcl-demo WR-0001
 pcl report feature --root /tmp/pcl-demo F-0001
 pcl report defect --root /tmp/pcl-demo D-0001
 pcl report validation --root /tmp/pcl-demo --strict
+pcl report skill-usage --since 2026-07-01 --json
 pcl render --root /tmp/pcl-demo
 ```
 
-Reports are written to `.project-loop/reports/`. The dashboard writes:
+Entity and validation reports are written to `.project-loop/reports/`.
+`report skill-usage` is read-only and prints its privacy-safe aggregate to
+stdout unless `--output` is explicit; see [Local Skill usage report](docs/skill-usage-report.md).
+The dashboard writes:
 
 ```text
 .project-loop/dashboard/dashboard-data.json
@@ -527,6 +622,17 @@ flag, `pcl render` reads `dashboard.locale` from `pcl.yaml` and then falls back
 to English. The locale affects only `dashboard.html`; `dashboard-data.json`
 keys and values stay English for agents and integrations.
 
+The dashboard opens with a simple operator view: **Now, Done, Next, Human
+needed, and Risks**. `Done` lists only evidence-backed terminal records; it does
+not turn a status label into a success claim. Counters, commands, queues, and
+entity tables remain available under **Detailed Project Loop information**.
+
+Agents should render routinely but present the dashboard only after plan
+approval, at a major milestone, when a human decision blocks progress, and
+after goal closure. When the host provides a visual or file panel, the agent
+opens it and explains what to review; otherwise it provides the generated path.
+The human should not need to remember when to ask for the dashboard.
+
 If validation fails or generated artifacts look stale, use [docs/recovery-playbook.md](docs/recovery-playbook.md) before continuing normal work.
 
 ## Example Projects

{project_loop_harness-0.4.3 → project_loop_harness-0.5.0}/README.md

@@ -1,22 +1,76 @@
 # Project Loop Harness
 
-Project Loop Harness is a local control plane for coding agents.
+> A local, model-neutral control plane that turns an agent's “done” into
+> reviewable Evidence, verification status, residual risk, and a resumable next
+> step.
 
-It is not just an Agent Skill. The core product is `pcl`, a small local CLI/runtime that gives Codex, Claude Code, and similar agents a guarded project-scoped loop: durable state in SQLite, append-only audit events in JSONL, generated prompts and evidence, strict validation, human-readable reports, and a deterministic dashboard.
+## Understand it in 30 seconds
 
-## Quick Start
+Coding agents are good at producing changes. They are less reliable at
+remembering project state, proving completion, stopping at human decisions, and
+handing work to another session or model.
 
-Install the published `pcl` CLI/runtime from PyPI with `pipx`:
+Project Loop Harness (`pcl`) gives Codex, Claude Code, and similar agents a
+shared local state machine:
+
+- SQLite keeps current state; JSONL keeps an auditable event projection.
+- Tests, artifacts, reviews, and completion packets preserve what “done” means.
+- Agents continue routine safe work; humans are asked only for genuine product,
+  permission, security, destructive, or external-service decisions.
+- The runtime does not call an LLM and does not depend on one agent vendor.
+
+It is designed for people coordinating multiple coding agents, not as another
+single-agent chat wrapper.
+
+## Get first value in five minutes
+
+### One-time operator setup
+
+Install the runtime, inspect the adoption plan, and initialize the repository:
 
 ```bash
 pipx install project-loop-harness
-pcl --version
-pcl --help
+cd /path/to/your-project
+pcl init --dry-run --json
+pcl init
 ```
 
+`pcl init` retains existing `AGENTS.md`, `CLAUDE.md`, and `.gitignore` content
+and appends its marked instruction block once. It also preserves an existing
+`pcl.yaml` by default. `--force` can replace generated templates such as
+`pcl.yaml`, workflows, the bundled Skill, and dashboard files; it does not
+replace existing project-instruction content. See the
+[Adoption Guide](docs/adoption-guide.md) for the exact file boundary.
+
+### After setup, tell the agent the outcome you want
+
+Copy this into Cockpit, Codex, Claude Code, or another coding-agent session:
+
+```text
+Read AGENTS.md, CLAUDE.md if present, and pcl.yaml. Use the Project Control
+Loop. Start this goal: <describe the outcome>. Continue every agent-safe next
+action, run the configured checks, preserve evidence, emit a completion packet,
+and close the goal. Do not ask me to run routine pcl commands. Stop only for a
+genuine human decision or external blocker.
+```
+
+The agent owns the routine `pcl start → implementation → finish → close` flow.
+The operator uses the CLI during setup or deliberate maintenance, not to
+manually advance every task.
+
+The project remains local-only by default. No telemetry, provider call, cloud
+sync, or automatic GitHub write is enabled by initialization.
+
+## Install and inspect in more detail
+
 Use `python -m pip install project-loop-harness` when installing inside a
 project-specific virtual environment or CI job instead of exposing the command
-globally.
+globally. Confirm the installed runtime with:
+
+```bash
+pcl --version
+pcl --help
+```
 
 For unreleased changes, install from a pinned GitHub tag or commit:
 
@@ -51,6 +105,10 @@ advisory warning alongside normal harness health checks. Set
 Then ask your coding agent to read `AGENTS.md`, `CLAUDE.md` if present, and
 `pcl.yaml`, run `pcl next --json`, and follow the next safe harness action.
 
+Compatibility promises for JSON contracts, typed errors, migrations, and
+internal surfaces are documented in the
+[Alpha Stability Policy](docs/stability-policy.md).
+
 ## Mental Model
 
 ```text
@@ -255,6 +313,39 @@ resolution as separate hash-bound Evidence. Task context, completion packets,
 and resume handoffs expose additive references without rewriting historical
 artifacts.
 
+## Council Profile (opt-in)
+
+Council is an external advisory boundary for ambiguous or high-risk work. It is
+not a model provider, executor, verifier, approval, or replacement for Direct.
+The Core prepares a deterministic request, validates and stores returned bytes,
+and keeps any proposed choice behind a human Decision:
+
+```bash
+pcl --json profile list
+pcl --json profile prepare council.discovery --target task:T-0001 --brief E-0001 \
+  --output /tmp/council-request.json
+pcl --json profile fixture-run --request /tmp/council-request.json --status completed \
+  --output-dir /tmp/council-output
+pcl --json profile ingest --request /tmp/council-request.json \
+  --bundle /tmp/council-output/profile-output-bundle.json --dry-run
+pcl --json profile ingest --request /tmp/council-request.json \
+  --bundle /tmp/council-output/profile-output-bundle.json
+```
+
+Real network or paid execution is outside Core and requires a hash-bound human
+authorization. `pcl profile authorize` only emits an authorized request; it
+never runs a provider. Revoke an authorization through the governed CLI, never
+by editing SQLite:
+
+```bash
+pcl --json profile authorize --revoke EV-XXXXXXXXXXXX --actor "human:owner" \
+  --recorded-by "agent:codex" --source-kind cockpit \
+  --source-ref "cockpit:<task-id>" --reason "Withdraw provider scope"
+```
+
+See [docs/council-profile.md](docs/council-profile.md) for the operator flow,
+privacy boundary, status handling, and adoption constraints.
+
 ## Evidence Sets
 
 Use `evidence-set/v1` when one passing artifact is not enough and the target
@@ -475,10 +566,14 @@ pcl report run --root /tmp/pcl-demo WR-0001
 pcl report feature --root /tmp/pcl-demo F-0001
 pcl report defect --root /tmp/pcl-demo D-0001
 pcl report validation --root /tmp/pcl-demo --strict
+pcl report skill-usage --since 2026-07-01 --json
 pcl render --root /tmp/pcl-demo
 ```
 
-Reports are written to `.project-loop/reports/`. The dashboard writes:
+Entity and validation reports are written to `.project-loop/reports/`.
+`report skill-usage` is read-only and prints its privacy-safe aggregate to
+stdout unless `--output` is explicit; see [Local Skill usage report](docs/skill-usage-report.md).
+The dashboard writes:
 
 ```text
 .project-loop/dashboard/dashboard-data.json
@@ -493,6 +588,17 @@ flag, `pcl render` reads `dashboard.locale` from `pcl.yaml` and then falls back
 to English. The locale affects only `dashboard.html`; `dashboard-data.json`
 keys and values stay English for agents and integrations.
 
+The dashboard opens with a simple operator view: **Now, Done, Next, Human
+needed, and Risks**. `Done` lists only evidence-backed terminal records; it does
+not turn a status label into a success claim. Counters, commands, queues, and
+entity tables remain available under **Detailed Project Loop information**.
+
+Agents should render routinely but present the dashboard only after plan
+approval, at a major milestone, when a human decision blocks progress, and
+after goal closure. When the host provides a visual or file panel, the agent
+opens it and explains what to review; otherwise it provides the generated path.
+The human should not need to remember when to ask for the dashboard.
+
 If validation fails or generated artifacts look stale, use [docs/recovery-playbook.md](docs/recovery-playbook.md) before continuing normal work.
 
 ## Example Projects

project_loop_harness-0.5.0/agent-tasks/0154-profile-boundary-adr-contract-freeze.md

@@ -0,0 +1,55 @@
+# 0154: Profile boundary ADR and proposal contract freeze
+
+- **Status:** Done; ADR accepted by human owner on 2026-07-12
+- **Milestone:** v0.5.0 Council Profile
+- **Priority:** P0
+- **Size:** M
+- **Dependencies:** 0153b; human Accept/Modify/Reject of the Profile boundary
+- **DB schema:** no change
+
+## Goal
+
+Freeze the model-independent PLH/external-runner boundary and the seven
+artifact shapes before adding runtime Profile behavior.
+
+## Scope
+
+- Add ADR-005 and the Council proposal under `docs/proposals/council-profile/`.
+- Add seven proposal schemas plus canonical positive and targeted negative
+  fixtures outside the runtime package.
+- Resolve the unshipped `decision-proposal/v0` shape conflict in the integrated
+  roadmap and update its example/references atomically.
+- Record canonical JSON/digest, status, path, size, and cross-reference rules.
+- Define request-basis digest and embedded `approval-provenance/v1` binding for
+  paid/network authorization without a circular request digest.
+- Freeze exact request-basis exclusions for generated time and context receipt
+  age fields while retaining receipt timestamps, source refs, and hashes.
+- Define project fingerprint inputs and confirm only the digest is emitted.
+- Define how `claim-set/v0` classes map to normal Evidence, Verification,
+  Decision, Work Brief, residual risk, and completion-packet boundaries.
+- Record the terminology contract: route profile, runner Profile ID, and role
+  profile use distinct JSON fields, help text, and error language.
+- Record that MVP is v0.5.0, built-in-only, schema 8, and strict-human-gated.
+
+## Invariants
+
+- No runtime Profile command, provider code, network, credential, external
+  execution, DB migration, or state mutation.
+- No two incompatible shapes remain documented under one contract version.
+- Model judgment is never deterministic proof.
+
+## Acceptance
+
+1. ADR has an explicit human outcome.
+2. Seven schemas are valid JSON, declare Draft 2020-12, and have canonical
+   examples plus a validation transcript. Runtime conformance is implemented
+   by 0155 standard-library validators; no dependency is added.
+3. Negative fixtures cover unknown fields, unsupported versions, bad status,
+   bad references, and invalid digest/path declarations.
+4. The old decision-proposal draft has a visible supersession note.
+5. Authorized-policy fixtures prove any semantic request change invalidates the
+   approval binding.
+6. Candidate and authorized requests built at different wall-clock times have
+   the same basis digest when semantic state is unchanged.
+7. Claim-to-proof and terminology mappings have no implicit promotion path.
+8. `ruff check .` and full `pytest` pass without dependency changes.

project_loop_harness-0.5.0/agent-tasks/0155-profile-contract-runtime-and-registry.md

@@ -0,0 +1,44 @@
+# 0155: Profile contract runtime and built-in registry
+
+- **Status:** Done
+- **Milestone:** v0.5.0 Council Profile
+- **Priority:** P0
+- **Size:** L
+- **Dependencies:** 0154 contract freeze
+- **DB schema:** no change
+
+## Goal
+
+Package standard-library validators and expose a deterministic, non-executable
+registry for the built-in `council.discovery` manifest.
+
+## Scope
+
+- Add one current-convention validator module and packaged schema per contract.
+- Export contracts through `src/pcl/contracts/__init__.py`.
+- Add `src/pcl/profiles.py` and a package-data built-in manifest.
+- Add `pcl profile list/show/validate` in text and JSON modes.
+- Use `route_profile`, `runner_profile_id`, and `role_profile` consistently in
+  public JSON/help/errors; snapshot help text that explains the distinction.
+- Reject unknown keys/versions, duplicate IDs, invalid capabilities, missing
+  package data, and executable hooks.
+- Enforce mediated approval recording: an agent/system recorder of a human
+  action requires conversation/Cockpit source provenance and a non-empty
+  source ref.
+- Enforce the frozen authorization data-class mapping and provider/cost scope;
+  JSON Schema shape conformance alone is insufficient.
+
+## Invariants
+
+- Built-in only; arbitrary filesystem discovery is unsupported.
+- Manifest is data-only and cannot import or invoke code.
+- No provider SDK, runtime dependency, state mutation, or hidden network call.
+- Discovery and finding order are deterministic.
+
+## Acceptance
+
+1. Canonical and negative contract fixtures pass manual validators.
+2. list/show/validate have stable JSON and text snapshots.
+3. Wheel/sdist contain every schema and the manifest.
+4. Clean-wheel commands run without source checkout or network.
+5. Existing CLI snapshots and full test suite pass.

project_loop_harness-0.5.0/agent-tasks/0156-profile-read-only-prepare.md

@@ -0,0 +1,49 @@
+# 0156: Deterministic read-only Profile request preparation
+
+- **Status:** Done
+- **Milestone:** v0.5.0 Council Profile
+- **Priority:** P0
+- **Size:** L
+- **Dependencies:** 0155
+- **DB schema:** no change
+
+## Goal
+
+Build `profile-run-request/v1` from current PLH state without invoking a runner
+or mutating project state.
+
+## Scope
+
+- Add `pcl profile prepare <id> --target type:ID [--brief E-ID] [--output]`.
+- Resolve one healthy Work Brief candidate, effective route, adaptive policy,
+  context payload, and linked Evidence hashes.
+- Allow an unapproved Brief for Discovery but label it; require `--brief` when
+  candidates are ambiguous.
+- Bind manifest, project fingerprint, target, Brief, route/override, policy,
+  context, limits, data policy, and request digest.
+- Compute a stable request-basis digest. Without matching authorization,
+  paid/network policy returns a candidate request plus `human_required` and
+  does not claim permission.
+- Normalize generated time and receipt-age presentation fields using the exact
+  0154 pointer list while retaining underlying receipts and source hashes.
+- Compute the project fingerprint from local root/config/schema/Git inputs and
+  emit only the digest plus project basename.
+
+## Invariants
+
+- No SQLite, event, outbox, Evidence, report, dashboard, or route mutation.
+- `--output` writes only the named request file.
+- No absolute project root, dashboard HTML, database, secret, or transcript.
+- Route mismatch fails and points to existing audited override commands.
+
+## Acceptance
+
+1. Reverse-order data reads and different wall-clock execution produce the same
+   basis digest when semantic state is unchanged.
+2. Before/after DB, JSONL, Evidence, report, and dashboard hashes are unchanged.
+3. Missing/ambiguous Brief, route mismatch, approval, and context-budget errors
+   are stable and repairable.
+4. Root path and secret sentinels are absent.
+5. Paid/network policy cannot become allowed without a matching authorization
+   event; the offline path remains fully usable before 0159.
+6. Targeted and full suites pass.

project_loop_harness-0.5.0/agent-tasks/0157-profile-bundle-validation-dry-run.md

@@ -0,0 +1,52 @@
+# 0157: Profile bundle validation and dry-run planner
+
+- **Status:** Done
+- **Milestone:** v0.5.0 Council Profile
+- **Priority:** P0
+- **Size:** L
+- **Dependencies:** 0156
+- **DB schema:** no change
+
+## Goal
+
+Validate an externally produced bundle and return a deterministic mutation plan
+without copying files or touching PLH state.
+
+## Scope
+
+- Add `pcl profile ingest --request ... --bundle ... --dry-run`.
+- Enforce parse/size limits before schema validation and reject duplicate keys.
+- Validate request/project/target/manifest binding, bundle digest/status,
+  listed paths, parents, symlinks, case-fold collisions, files, sizes, hashes,
+  contracts, and cross-references.
+- Return exact planned Evidence/link/Decision/event counts and next action.
+- Add valid status fixtures and a comprehensive invalid corpus.
+
+## Invariants
+
+- Dry-run is entirely read-only and ignores unlisted neighboring files.
+- Verification-plan commands are data and are never executed.
+- Findings and repair guidance are stable and deterministically ordered.
+- `partial`, `budget_exhausted`, and `failed` are never execution-ready.
+
+## Acceptance
+
+1. Valid fixtures yield stable plans and next actions.
+2. Every invalid fixture fails with zero filesystem/DB/event mutation.
+3. Path traversal, absolute/UNC/drive paths, symlinks, case collisions,
+   hash/size drift, bad status, and cross-reference errors are covered.
+4. Bundle/request limits are enforced before expensive parsing/hashing.
+5. Targeted and full suites pass.
+
+## Implementation evidence
+
+- `src/pcl/profile_ingest.py` validates request/bundle bindings, bounded strict
+  JSON, listed artifact bytes, safe paths, contracts, and cross-references.
+- `pcl profile ingest --request ... --bundle ... --dry-run` returns a stable,
+  exact mutation plan without copying files or executing runner/verification
+  commands.
+- `tests/fixtures/profile_bundle/cases.json` and
+  `tests/test_profile_ingest_dry_run.py` cover all six statuses and the invalid
+  corpus, with before/after state snapshots.
+- Verification after Claude Fable review fixes: `ruff check .` and `pytest -q`
+  (912 passed, 1 skipped).

project_loop_harness-0.5.0/agent-tasks/0158-profile-bundle-atomic-ingest.md

@@ -0,0 +1,61 @@
+# 0158: Atomic Profile bundle Evidence ingest and idempotency
+
+- **Status:** Done
+- **Milestone:** v0.5.0 Council Profile
+- **Priority:** P0
+- **Size:** L
+- **Dependencies:** 0157
+- **DB schema:** remain 8; stop if a migration becomes necessary
+
+## Goal
+
+Persist one validated external bundle as immutable target-linked Evidence with
+an outbox event, zero partial mutation, and exact replay idempotency.
+
+## Scope
+
+- Add a dedicated directory-bundle staging/copy service for validated external
+  inputs without changing the existing permissive adhoc outside-root policy.
+- Re-hash staged bytes before beginning the DB mutation.
+- Insert one `profile_output_bundle` Evidence, target link, and
+  `profile_output_ingested` event in one transaction.
+- Store profile/request/bundle metadata in the immutable manifest and event.
+- Implement exact replay and same-ID/different-digest conflict behavior.
+- Require `--accept-failed --summary` to persist a failed bundle.
+- Extend `audit._check_evidence` to detect finalized unreferenced Profile bundle
+  directories left by rename-before-commit crashes and return report/quarantine
+  guidance without automatic deletion.
+
+## Invariants
+
+- Rejected or interrupted pre-commit input leaves zero rows/events and no
+  staging residue.
+- Existing Evidence semantics and adhoc path restrictions do not weaken.
+- Stored artifacts are immutable and only listed files are authoritative.
+- JSONL projection remains recoverable through the existing outbox/audit path.
+
+## Acceptance
+
+1. A valid non-human bundle adds exactly one Evidence, one target link, and one
+   ingest event.
+2. Exact replay returns original IDs with zero mutation; conflicts fail.
+3. Crash injection covers copy, pre-rename, post-rename/pre-commit, and outbox.
+4. Audit detects Profile temp files and finalized unreferenced bundle
+   directories; cleanup remains explicit and never guesses durable state.
+5. Source, wheel, and sdist ingest tests pass without migration/dependency.
+
+## Implementation evidence
+
+- `src/pcl/profile_bundle_store.py` re-validates staged bytes, copies only
+  listed artifacts, atomically publishes one immutable directory, and commits
+  one Evidence/link/event/outbox transaction.
+- Exact replay returns the original Evidence/event IDs; same bundle ID with a
+  different digest fails closed.
+- Failed bundles require `--accept-failed --summary`; `needs_human` remains
+  blocked until task 0159 adds Decision handling.
+- `audit._check_evidence` validates stored hashes and reports staging/finalized
+  orphan directories with explicit quarantine/report guidance only.
+- Four process-kill fault points cover copy, pre-rename,
+  post-rename/pre-commit, and post-outbox/pre-commit behavior.
+- Verification: `ruff check .`; targeted source/wheel/sdist tests 46 passed;
+  full suite 922 passed, 1 skipped.