docs(vz): record launchd drill evidence

[rmusser01]

Summary

• add a 2026-07-03 prepared-host launchd-drill evidence packet
• record isolated LaunchAgent bootstrap/kickstart/helper readiness/protocol checks and drill-owned bootout
• document the relative-helper diagnostic failure and update the residual-gap table so launchd lifecycle evidence is recorded while launchd-managed VM smoke remains manual-only

Verification

• /Users/macbook-dev/Documents/GitHub/tldw_server2/.venv/bin/python -m pytest tldw_Server_API/tests/Infrastructure/test_vz_linux_host_gated_workflow.py -q
• git diff --check
• Bandit skipped: committed scope is Markdown/Backlog only

Human-authored Change summary still required before merge per repo policy.

---

Summary by cubic

Added a 2026-07-03 launchd drill evidence packet to the prepared-host tracker for the macOS VZ helper, capturing isolated LaunchAgent bootstrap, kickstart, helper readiness, protocol checks, and drill-owned bootout. Notes the relative-helper plist failure and updates the residual-gap table; launchd-managed VM smoke stays manual-only (tracks TASK-12137).

^{Written for commit fdd2527. Summary will update on new commits.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 5c29e0fb-5426-4dba-8c96-23abbb59d2a3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/vz-launchd-drill-evidence

---

_{Comment @coderabbitai help to get the list of available commands.}

[gemini-code-assist]

Code Review

This pull request documents the results of a local launchd-drill lifecycle check performed on July 3, 2026, updating the prepared-host evidence tracker and adding a corresponding backlog task file. The feedback suggests renaming the newly added backlog task file to use lowercase kebab-case without spaces to avoid potential command-line and link resolution issues.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The filename contains spaces and mixed casing (e.g., task-12137 - Record-VZ-launchd-drill-prepared-host-evidence.md). It is highly recommended to use lowercase kebab-case without spaces for filenames in the repository (e.g., task-12137-record-vz-launchd-drill-prepared-host-evidence.md). This prevents potential issues with shell scripts, command-line tools, and link resolution in markdown parsers.

[qodo-code-review]

PR Summary by Qodo

Record prepared-host launchd-drill evidence for VZ helper lifecycle

📝 Documentation 🕐 10-20 Minutes

AI Description

• Add a 2026-07-03 prepared-host launchd-drill evidence packet for macOS VZ helper.
• Document LaunchAgent bootstrap/kickstart/readiness/protocol checks and drill-owned bootout
 cleanup.
• Update residual-gap tracking so launchd lifecycle evidence is recorded while VM smoke stays
 manual-only.

Diagram

graph TD
  A["Local operator"] --> B["vz-helperctl.py launchd-drill"] --> C["LaunchAgent lifecycle evidence"] --> D["Prepared-host evidence doc"]
  D --> E["Residual-gap table"]
  F["Backlog task TASK-12137"] --> D
  subgraph Legend
    direction LR
    _actor["Operator"] ~~~ _cmd["Script/Command"] ~~~ _doc["Documentation"]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Automate launchd-drill on a dedicated macOS runner

• ➕ Repeatable evidence capture with less operator variance
• ➕ Enables trend/history over time with consistent environment capture
• ➖ Requires provisioning/maintaining a suitable runner that can safely validate LaunchAgents
• ➖ May conflict with the stated intent to keep launchd-managed VM smoke manual-only

2. Add a templated evidence packet generator (scripted Markdown output)

• ➕ Reduces documentation drift and ensures consistent fields (paths, labels, exit codes, artifacts)
• ➕ Makes future evidence packets faster and more comparable
• ➖ Introduces new tooling/maintenance overhead
• ➖ Still requires manual execution and careful handling of local-only paths

Recommendation: Keep the PR’s current docs-only approach: it meets the goal of recording manual launchd lifecycle evidence without expanding CI scope. Consider a future templated evidence generator if evidence packets become frequent or reviewers see inconsistency across runs; defer CI automation until a dedicated runner strategy and safety constraints are agreed.

Files changed (2) +146 / -1

Documentation (2) +146 / -1

vz-linux-prepared-host-evidence.mdAdd 2026-07-03 launchd-drill evidence packet and update residual-gap entry +85/-1

Add 2026-07-03 launchd-drill evidence packet and update residual-gap entry

• Adds a detailed prepared-host evidence packet for a local launchd-drill run, including runtime paths, commands, results, artifacts, expected skips, and cleanup verification. Updates the residual-gap table to reflect that launchd lifecycle evidence is now recorded while launchd-managed VM smoke remains explicit/manual-only.

Docs/Sandbox/vz-linux-prepared-host-evidence.md

task-12137 - Record-VZ-launchd-drill-prepared-host-evidence.mdAdd completed backlog task documenting acceptance criteria, notes, and verification +61/-0

Add completed backlog task documenting acceptance criteria, notes, and verification

• Introduces TASK-12137 as a Done task capturing acceptance criteria, implementation notes (including the relative-helper diagnostic failure), verification commands, and a final summary that links back to the evidence tracker.

backlog/tasks/task-12137 - Record-VZ-launchd-drill-prepared-host-evidence.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 74 rules

1. Workstation paths committed 🐞 Bug ⚙ Maintainability

Description

The new launchd-drill evidence packet records a developer-specific absolute home directory path
("/Users/..."), which makes the docs less portable and leaks workstation-specific directory
structure. Other backlog artifacts explicitly sanitize workstation-specific paths and sometimes use
a redacted placeholder, so these additions regress that documentation hygiene.

Code

Docs/Sandbox/vz-linux-prepared-host-evidence.md[139]

+    --helper /Users/macbook-dev/Documents/GitHub/tldw_server2/.worktrees/vz-launchd-drill-evidence/tools/macos-vz-helper/.build/debug/macos-vz-helper \

Evidence

The evidence packet hard-codes an absolute /Users/... helper path and the new task note hard-codes
both a worktree path and a venv path under /Users/.... Elsewhere, the repo explicitly notes
sanitizing task notes to remove workstation-specific paths and demonstrates a
<local_worktree_path_redacted> placeholder convention.

Docs/Sandbox/vz-linux-prepared-host-evidence.md[133-145]
backlog/tasks/task-12137 - Record-VZ-launchd-drill-prepared-host-evidence.md[32-45]
backlog/tasks/task-241 - ACP-Stage-1-retention-and-redaction-implementation.md[63-66]
backlog/tasks/task-293 - Specify-Persona-Buddy-renderer-capability-registry.md[45-47]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The PR commits workstation-specific absolute paths (e.g., `/Users/<name>/...`) into documentation/backlog evidence notes. This reduces portability and regresses the repo’s existing practice of sanitizing/redacting workstation-specific paths.

## Issue Context
The evidence remains useful without the full local path; placeholders like `<local_worktree_path_redacted>`, `$WORKTREE`, `~`, or a relative repo path are typically sufficient.

## Fix Focus Areas
- Docs/Sandbox/vz-linux-prepared-host-evidence.md[138-144]
- backlog/tasks/task-12137 - Record-VZ-launchd-drill-prepared-host-evidence.md[33-45]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

1. Workstation paths committed 🐞 Bug ⚙ Maintainability

The new launchd-drill evidence packet records a developer-specific absolute home directory path
("/Users/..."), which makes the docs less portable and leaks workstation-specific directory
structure. Other backlog artifacts explicitly sanitize workstation-specific paths and sometimes use
a redacted placeholder, so these additions regress that documentation hygiene.

Agent Prompt

## Issue description
The PR commits workstation-specific absolute paths (e.g., `/Users/<name>/...`) into documentation/backlog evidence notes. This reduces portability and regresses the repo’s existing practice of sanitizing/redacting workstation-specific paths.

## Issue Context
The evidence remains useful without the full local path; placeholders like `<local_worktree_path_redacted>`, `$WORKTREE`, `~`, or a relative repo path are typically sufficient.

## Fix Focus Areas
- Docs/Sandbox/vz-linux-prepared-host-evidence.md[138-144]
- backlog/tasks/task-12137 - Record-VZ-launchd-drill-prepared-host-evidence.md[33-45]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools