Worktrunk: parallel worktrees, lifecycle control and source analysis
Build a read-only Worktrunk readiness report: a practical extension exercise
Design a small audit report for branches, configuration and unresolved risks without automatically approving hooks, merging code or deleting worktrees.
What you will learn
- A useful extension should reduce uncertainty before adding autonomy
- Define input and output before choosing a visual interface
- Acceptance tests should prevent accidental promotion into an operator
Before you start
- Basic Git branches and command-line navigation
- A disposable repository for optional reader exercises
Explain worktree boundaries, verify a first checkout and review configured commands before adopting automation.
Key takeaways
- The readiness report is an editorial proposal, not an upstream feature.
- Unknown is a first-class state, not a passing check.
- A report must not silently become an execution engine.
A useful extension should reduce uncertainty before adding autonomy
A manageable learning project is a readiness report, not another autonomous merge button. Given a captured worktree inventory and a manually reviewed configuration summary, produce a list of missing decisions: branch ownership, port assignment, hook reviewer and cleanup retention. This is our proposed exercise, not a shipped Worktrunk feature or an announced upstream roadmap.
Use synthetic input first. The tool should read only explicitly supplied records and write a report; it should not discover home-directory secrets, approve commands, contact a model or run hooks. Keeping the first version offline makes the output reviewable and separates report correctness from the hazards of acting on a live repository.
Define input and output before choosing a visual interface
Each record needs a branch, path, owner, optional port, configuration revision and tri-state review fields. Unknown must remain distinct from false: an absent cleanliness observation does not prove a dirty checkout, and an absent risk finding does not prove safety. Output should distinguish missing evidence from a confirmed conflict such as two records claiming the same port.
Begin with a text or JSON report that can be inspected and tested. An SVG can show shared services and per-task ownership without requiring JavaScript to read it. Three.js would be justified only by a concrete spatial interaction the report needs; a small dependency graph does not gain accuracy from a 3D scene. Keep any future interactive view backed by accessible static content.
Acceptance tests should prevent accidental promotion into an operator
Use fixtures containing duplicate ports, an unknown status, two paths with similar names and a changed configuration revision. Require deterministic findings that name the affected record and the missing evidence. Also assert that generating the report invokes no subprocess, network request, approval mutation or removal action. These are proposed extension tests, distinct from the small approval teaching model in this series.
A later integration can consume a documented machine-readable inventory after version compatibility and path handling are reviewed. Keep execution as a separate, explicit user action; never turn a green report into permission to merge or delete. The finished exercise teaches evidence modeling and operational boundaries even before any live Worktrunk integration exists.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Define synthetic branch, path, owner and port records.
- 2
Return missing-evidence and confirmed-conflict findings separately.
- 3
Test deterministic output with no external actions.
- 4
Add live integration only after a separate compatibility review.
Copy-ready example
{
"proposal": true,
"records": [
{
"branch": "demo-review",
"path": "/example/review",
"owner": null,
"port": 3000,
"clean": null,
"configRevision": null
}
],
"findings": [
"owner not recorded",
"cleanliness not observed",
"configuration revision missing"
],
"executeActions": false
}Frequently asked questions
Is this extension already included in Worktrunk?
No. It is a proposed learning exercise.
Do I need Three.js for it?
No. JSON, text and an accessible SVG are sufficient for the proposed information relationships.
Sources
- Worktrunk / docs/src/content/docs/config.mdSource checked 2026-09-14
- Worktrunk / docs/src/content/docs/list.mdSource checked 2026-09-14
- Worktrunk / docs/src/content/docs/hook.mdSource checked 2026-09-14