Extract harvest mechanics into a tested pact_harvest CLI (#1034)

Extracts the harvest skill's inline-Python journal glue into a tested, importable `pact_harvest` CLI (`resolve-session-dir` + `resolve-artifacts`), replacing brittle inline logic with an exit-code-keyed, off-lead-safe entry point. Folds in the CLI-extraction follow-up originally split out.

What landed:
- New `hooks/shared/pact_harvest.py` CLI (2 subcommands; sys.path bootstrap; 0/2/1 exit contract; stdout=data / stderr=diagnostics)
- `resolve_latest_artifacts` / `_ts_supersedes` pure helper (fail-open ts compare, last-wins tie-break, trailing-Z anchor, naive->UTC coerce)
- SKILL.md rewrite (inline-Python -> CLI; JSON-array parse)
- Hardening: session-dir containment check, defensive non-str path-element skip, naive/aware timestamp coercion
- Comprehensive non-vacuous test coverage (containment, path-type, missing-arg, mixed-ts, naive/aware, B1 drift parity)

Reviewed by 3 cross-lane reviewers + 3 fresh blind reviewers (all APPROVE); full suite green (9676 passed / 0 failed / 0 errors) + CI green. PATCH bump 4.4.41 -> 4.4.42.

Part of the harvest/artifact-durability arc; supersedes the CLI-extraction split.

Author: michael-wojcik

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "PACT",
       "source": "./pact-plugin",
       "description": "Orchestration harness that turns Claude Code into a coordinated team of specialist AI agents",
-      "version": "4.4.41",
+      "version": "4.4.42",
       "author": {
         "name": "Synaptic-Labs-AI"
       },

README.md

@@ -605,7 +605,7 @@ When installed as a plugin, PACT lives in your plugin cache:
 │   └── cache/
 │       └── pact-plugin/
 │           └── PACT/
-│               └── 4.4.41/      # Plugin version
+│               └── 4.4.42/      # Plugin version
 │                   ├── agents/
 │                   ├── commands/
 │                   ├── skills/

pact-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "PACT",
-  "version": "4.4.41",
+  "version": "4.4.42",
   "description": "Orchestration harness that turns Claude Code into a coordinated team of specialist AI agents",
   "author": {
     "name": "Synaptic-Labs-AI",

pact-plugin/README.md

@@ -1,6 +1,6 @@
 # PACT — Orchestration Harness for Claude Code
 
-> **Version**: 4.4.41
+> **Version**: 4.4.42
 
 Turn a single Claude Code session into a managed team of specialist AI agents that prepare, design, build, and test your code systematically.
 

pact-plugin/commands/orchestrate.md

@@ -494,7 +494,19 @@ Agent(
 Completed-phase teammates remain as consultants. Do not shutdown during this workflow.
 
 **Before next phase**:
-- [ ] Outputs exist in `docs/preparation/`
+- [ ] **Artifact exists and is non-empty** — for a PREPARE phase that **ran** (not skipped), the expected per-feature artifact at `docs/preparation/{feature}.md` (and any additional produced files, e.g. `environment-model-{feature}.md`) MUST exist on disk and be non-empty before you complete the phase task or emit below. A missing or empty artifact is a **failure to investigate**, not an absence of work: do **NOT** complete the phase, do **NOT** emit, and INVESTIGATE first (specialist wrote to the wrong location, produced nothing, or used a different slug), then resolve it. A **skipped** PREPARE phase is exempt — it legitimately produces no artifact, so neither the check nor the emit applies.
+- [ ] **Emit `artifact_paths`** — before marking the PREPARE phase task completed, glob the worktree's `docs/preparation/` directory and write a path-only `artifact_paths` journal event so the artifact is recoverable after garbage-collection independently of any HANDOFF. Enumerate the full absolute path list yourself (do NOT read paths from a HANDOFF — a recovery pointer must not depend on the thing it recovers). If the glob finds nothing, do NOT emit an empty event (the missing-artifact case above already covers that anomaly).
+  ```bash
+  set -e
+  trap 'rc=$?; echo "[JOURNAL WRITE FAILED] orchestrate.md (bash line $LINENO): \"${BASH_COMMAND%%$'\''\n'\''*}\" exit=$rc" >&2; exit $rc' ERR
+  SJ="{plugin_root}/hooks/shared/session_journal.py"
+  # Enumerate this feature's PREPARE artifacts (worktree-isolated → this feature only).
+  # Emit only when ≥1 non-empty path is found; an empty result is the missing-artifact anomaly, not an event.
+  python3 "$SJ" write --type artifact_paths --session-dir '{session_dir}' --stdin <<'JSON'
+  {"workflow": "prepare", "feature": "{feature}", "paths": ["{absolute_path_1}", "{absolute_path_2}"], "task_id": "{prepare_task_id}"}
+JSON
+  ```
+- [ ] **Complete the PREPARE phase task** — ONLY after the artifact check and the `artifact_paths` emit above: `TaskUpdate(prepareTaskId, status="completed")`. This ordering is load-bearing: the emit MUST land before the phase-task completion so the durability pointer is on disk by the time completion is observed. (A skipped PREPARE phase completes earlier with `metadata.skipped=true` and runs neither the check nor the emit.)
 - [ ] Specialist HANDOFF received
 - [ ] If blocker reported → `/PACT:imPACT`
 - [ ] **S4 Checkpoint** (see [pact-s4-checkpoints.md](../protocols/pact-s4-checkpoints.md)): Environment stable? Model aligned? Plan viable? Optionally query secretary for S4 pattern check (variety 7+). See [pact-orchestrator §Memory Management](../agents/pact-orchestrator.md#memory-management).
@@ -589,7 +601,19 @@ Agent(
 Completed-phase teammates remain as consultants. Do not shutdown during this workflow.
 
 **Before next phase**:
-- [ ] Outputs exist in `docs/architecture/`
+- [ ] **Artifact exists and is non-empty** — for an ARCHITECT phase that **ran** (not skipped), the expected per-feature artifact at `docs/architecture/{feature}.md` (and any additional produced files) MUST exist on disk and be non-empty before you complete the phase task or emit below. A missing or empty artifact is a **failure to investigate**, not an absence of work: do **NOT** complete the phase, do **NOT** emit, and INVESTIGATE first (specialist wrote to the wrong location, produced nothing, or used a different slug), then resolve it. A **skipped** ARCHITECT phase is exempt — it legitimately produces no artifact, so neither the check nor the emit applies.
+- [ ] **Emit `artifact_paths`** — before marking the ARCHITECT phase task completed, glob the worktree's `docs/architecture/` directory and write a path-only `artifact_paths` journal event so the artifact is recoverable after garbage-collection independently of any HANDOFF. Enumerate the full absolute path list yourself (do NOT read paths from a HANDOFF). If the glob finds nothing, do NOT emit an empty event (the missing-artifact case above covers that anomaly).
+  ```bash
+  set -e
+  trap 'rc=$?; echo "[JOURNAL WRITE FAILED] orchestrate.md (bash line $LINENO): \"${BASH_COMMAND%%$'\''\n'\''*}\" exit=$rc" >&2; exit $rc' ERR
+  SJ="{plugin_root}/hooks/shared/session_journal.py"
+  # Enumerate this feature's ARCHITECT artifacts (worktree-isolated → this feature only).
+  # Emit only when ≥1 non-empty path is found; an empty result is the missing-artifact anomaly, not an event.
+  python3 "$SJ" write --type artifact_paths --session-dir '{session_dir}' --stdin <<'JSON'
+  {"workflow": "architect", "feature": "{feature}", "paths": ["{absolute_path_1}", "{absolute_path_2}"], "task_id": "{architect_task_id}"}
+JSON
+  ```
+- [ ] **Complete the ARCHITECT phase task** — ONLY after the artifact check and the `artifact_paths` emit above: `TaskUpdate(architectTaskId, status="completed")`. This ordering is load-bearing: the emit MUST land before the phase-task completion so the durability pointer is on disk by the time completion is observed. (A skipped ARCHITECT phase completes earlier with `metadata.skipped=true` and runs neither the check nor the emit.)
 - [ ] Specialist HANDOFF received
 - [ ] If blocker reported → `/PACT:imPACT`
 - [ ] **S4 Checkpoint**: Environment stable? Model aligned? Plan viable?
@@ -757,6 +781,16 @@ The auditor stores its final signal as `metadata.audit_summary` via `TaskUpdate`
   {"sha": "{short_sha}", "message": "{first_line}", "phase": "CODE"}
 JSON
   ```
+- [ ] **Emit `artifact_paths` for auditor decision-logs (conditional, capture-if-present)** — if a concurrent auditor produced decision-log artifacts, glob `docs/decision-logs/{feature}-*.md`; when ≥1 is present, write a path-only `artifact_paths` event (`workflow=code-auditor`) so they harvest. Unlike PREPARE/ARCHITECT, this is **capture-if-present, not flag-if-missing**: the auditor is optional, so absence is normal — emit nothing and do NOT flag a missing artifact.
+  ```bash
+  set -e
+  trap 'rc=$?; echo "[JOURNAL WRITE FAILED] orchestrate.md (bash line $LINENO): \"${BASH_COMMAND%%$'\''\n'\''*}\" exit=$rc" >&2; exit $rc' ERR
+  SJ="{plugin_root}/hooks/shared/session_journal.py"
+  # Best-effort: only when the glob found ≥1 decision-log; if none, skip this emit entirely (auditor is optional).
+  python3 "$SJ" write --type artifact_paths --session-dir '{session_dir}' --stdin <<'JSON'
+  {"workflow": "code-auditor", "feature": "{feature}", "paths": ["{absolute_decision_log_path}"]}
+JSON
+  ```
 - [ ] **Process coder HANDOFFs** (non-blocking):
   ```
   TaskCreate(subject="secretary: harvest pending HANDOFFs",

pact-plugin/commands/peer-review.md

@@ -279,7 +279,16 @@ See also: [Communication Charter](../protocols/pact-communication-charter.md) fo
 ---
 
 **After all reviews complete**:
-1. Synthesize findings into a unified review summary with consolidated recommendations
+1. Synthesize findings into a unified review summary with consolidated recommendations, written to `docs/review/`. After writing it, confirm the review doc exists on disk and is non-empty before continuing.
+   - **Emit `artifact_paths`**: write a path-only `artifact_paths` journal event pointing at the review doc(s) so the consolidated review is recoverable after garbage-collection independently of any HANDOFF. The review doc is the lead's own product — enumerate its absolute path(s) here, not from any HANDOFF.
+     ```bash
+     set -e
+     trap 'rc=$?; echo "[JOURNAL WRITE FAILED] peer-review.md (bash line $LINENO): \"${BASH_COMMAND%%$'\''\n'\''*}\" exit=$rc" >&2; exit $rc' ERR
+     python3 "{plugin_root}/hooks/shared/session_journal.py" write \
+       --type artifact_paths --session-dir '{session_dir}' --stdin <<'JSON'
+     {"workflow": "peer-review", "feature": "{feature}", "paths": ["{absolute_review_doc_path}"]}
+JSON
+     ```
 2. **Journal events**: Write a `review_finding` event for each synthesized finding:
    ```bash
    set -e

pact-plugin/commands/plan-mode.md

@@ -194,7 +194,7 @@ Each consultant dispatch creates **two tasks**, not one:
 - **Task A** — TEACHBACK gate. `subject = "{specialist}: TEACHBACK for plan consultation on {feature}"`, owner = consultant. Description: lightweight understanding-confirm of the consultation scope.
 - **Task B** — primary consultation. `subject = "{specialist}: plan consultation for {feature}"`, owner = consultant, `blockedBy = [<Task A id>]`.
 
-Both are created BEFORE the `Agent(...)` spawn call. The consultant claims A, submits teachback metadata, idles on `awaiting_lead_completion`. You review and accept via the two-call atomic pair: `SendMessage(to=consultant, ...)` FIRST, then `TaskUpdate(A, status="completed")` — see [Teachback Review](../protocols/pact-completion-authority.md#teachback-review) for the rationale. On accept, the consultant wakes to claim B and produce the consultation HANDOFF.
+Both are created BEFORE the `Agent(...)` spawn call. The consultant claims A, submits teachback metadata, idles on `awaiting_lead_completion`. You review and accept via the two-call atomic pair: `SendMessage(to=consultant, ...)` FIRST, then `TaskUpdate(A, status="completed")` — see [Teachback Review](../protocols/pact-completion-authority.md#teachback-review) for the rationale. On accept, the consultant wakes to claim B and produce the consultation HANDOFF. The consultant writes the HANDOFF and signals stage-ready, then idles — **you (the lead) complete Task B**, not the consultant. Lead-side completion is what reliably journals the consultation HANDOFF; a consultant self-completing their own Task B can leave the HANDOFF unrecorded.
 
 ```
 # A-FIRST ORDERING (required): create Task A (the teachback gate) BEFORE Task B so the gate gets the LOWER id. Creating Task B first — giving the gate the HIGHER id — is WRONG: it inverts the intuitive "lower id = earlier" reading. The blocking wiring below legitimately names both ids because it runs AFTER both tasks exist.
@@ -354,6 +354,27 @@ TaskUpdate(
 
 Save the synthesized plan to `docs/plans/{feature-slug}-plan.md`.
 
+**Plan-doc self-check**: after writing the plan, confirm `docs/plans/{feature-slug}-plan.md` exists on disk and is non-empty before continuing. An empty or missing plan doc is a failure to investigate (the synthesis did not land), not a no-op — resolve it before completing the planning task.
+
+**Emit `artifact_paths`**: write a path-only `artifact_paths` journal event pointing at the plan doc so it (and the consultation work it synthesizes) is recoverable after garbage-collection independently of any HANDOFF. The plan doc is the lead's own product, so the lead knows its absolute path directly — enumerate it here, not from any HANDOFF.
+
+```bash
+set -e
+trap 'rc=$?; echo "[JOURNAL WRITE FAILED] plan-mode.md (bash line $LINENO): \"${BASH_COMMAND%%$'\''\n'\''*}\" exit=$rc" >&2; exit $rc' ERR
+SJ="{plugin_root}/hooks/shared/session_journal.py"
+python3 "$SJ" write --type artifact_paths --session-dir '{session_dir}' --stdin <<'JSON'
+{"workflow": "plan-mode", "feature": "{feature-slug}", "paths": ["{absolute_plan_doc_path}"]}
+JSON
+```
+
+**Trigger a harvest** (consult-only durability): plan-mode is a consultation-only flow with no later CODE/peer-review boundary to trigger memory harvest, so the plan doc and the consultation HANDOFFs would otherwise never reach pact-memory. Create a secretary harvest task after writing the plan so the `artifact_paths` event resolves and the consultation HANDOFFs distill into institutional memory:
+
+```
+TaskCreate(subject="secretary: harvest plan-mode consultation",
+  description="Harvest HANDOFFs and artifact_paths for team {team_name}. Follow the Standard Harvest workflow in your pact-handoff-harvest skill, resolving artifact_paths events to read the plan doc and any consultation artifacts off disk. Report summary when done.")
+TaskUpdate(taskId, owner="secretary")
+```
+
 **Handling existing plans**:
 
 If a plan already exists for this feature slug:

pact-plugin/hooks/shared/pact_context.py

@@ -565,6 +565,47 @@ def get_session_dir() -> str:
     return str(_build_session_path(slug, session_id))
 
 
+def reconstruct_session_dir(project_dir: str, session_id: str) -> str:
+    """Reconstruct the absolute session directory from explicit context-file
+    fields — the off-lead, frame-independent counterpart to get_session_dir().
+
+    An off-lead reader (notably the `pact-secretary` harvest, which runs in a
+    teammate frame where get_session_dir() false-returns '') resolves the dir by
+    reading `pact-session-context.json` and passing its `project_dir` +
+    `session_id` fields here. Both fields are persisted RAW (write_context stores
+    the caller-supplied values; init() sanitizes only the PATH segment it builds,
+    not the stored field — see build_context_cache / the write_context contract),
+    so this helper MUST reproduce the writer's path-sanitization to land on the
+    SAME on-disk directory init() wrote to:
+
+      - session_id: sanitized via _UNSAFE_SLUG_CHARS_RE (mirrors the substitution
+        init() applies to the id before building the context path).
+      - slug: derived as Path(project_dir).name and sanitized + traversal-guarded
+        inside _build_session_path (the single source of truth for the slug leg).
+
+    Routing BOTH axes through the writer's derivation (the regex for the id, the
+    shared path-builder for the slug) makes this SSOT-by-construction: an off-lead
+    reconstruction cannot drift from the writer, and a future change to either
+    guard updates both the writer and this reader at once. Without this, a
+    project basename or session_id containing a non-`[A-Za-z0-9_-]` character
+    (e.g. a dot or space) would reconstruct a DIFFERENT directory than the one the
+    journal was written to → the off-lead read silently returns 0 events.
+
+    Args:
+        project_dir: The `project_dir` field from pact-session-context.json.
+        session_id: The `session_id` field from pact-session-context.json (raw).
+
+    Returns:
+        The absolute session directory path, or '' if either input is falsy
+        (matching get_session_dir()'s empty-on-unavailable contract).
+    """
+    if not project_dir or not session_id:
+        return ""
+    safe_id = _UNSAFE_SLUG_CHARS_RE.sub("_", str(session_id))
+    slug = Path(project_dir).name
+    return str(_build_session_path(slug, safe_id))
+
+
 def get_plugin_root() -> str:
     """Convenience: return plugin_root from context. Falls back to the
     CLAUDE_PLUGIN_ROOT env var (exported into every hook process by the