fix: complete Swarm harvest cleanup and add readiness diagnostics

[Steel-tech]

A pane-backed slot could merge successfully and then fail automatic archive because its plugin-reported state was still working; Herdr 0.8.2 additionally reports unseen idle agents as done. Harvest now refreshes completed state before archive and recognizes done as settled while retaining ownership, worktree, and active-agent checks.

Adds read-only npm run doctor diagnostics and npm run build / npm run validate commands. Source validation checks each shell script individually, avoiding the first-file-only behavior of bash -n scripts/*.sh, and checks Node module syntax. Documentation now points to the canonical suite site and records the bounded live workflow and remaining recommendations. Version stays 0.3.0 with changes under Unreleased.

Validation:

• Build, ShellCheck, and focused real-git harvest/doctor/source-check regressions pass.
• Exact-head npm run validate on Node 24: 244 tests pass, including all source/manifest/ShellCheck gates. Baseline Node 26 suite also passed (237 tests before these additions).
• Isolated Herdr 0.8.2 session: real fan-out, worker commit, preview, merge, renderer auto-archive, prune dry-run, and a separate abort all passed. Worktrees were removed, branches preserved, and the test server stopped.

The existing newer-than-tested warning remains: the 0.8.2 smoke run does not certify every CLI surface or model-agent integration. No CI/CD changes or global Herdr configuration changes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 003cdac4-008e-42cc-9d9c-0f4fc83a2b04

📥 Commits

Reviewing files that changed from the base of the PR and between a8607e6 and 4f0e2a7.

📒 Files selected for processing (13)

• CHANGELOG.md
• CONTRIBUTING.md
• README.md
• bin/renderer-harvest.mjs
• docs/readiness.md
• package.json
• scripts/check-source.mjs
• scripts/doctor.sh
• scripts/harvest-step.sh
• scripts/lib.sh
• tests/check-source.test.mjs
• tests/doctor.test.mjs
• tests/harvest.test.mjs

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change reconciles Harvest state before archive, accepts Herdr done states, adds build, lint, validation, and prerequisite checks, and documents the workflows and readiness evidence.

Changes

Harvest and validation updates

Layer / File(s)	Summary
Archive reconciliation and settled states bin/renderer-harvest.mjs, scripts/harvest-step.sh, tests/harvest.test.mjs	Merged slots now preview before archive. Archive accepts idle, done, and absent states. Regression tests cover state reconciliation and both settled states.
Validation and prerequisite commands package.json, scripts/check-source.mjs, scripts/doctor.sh, scripts/lib.sh, tests/check-source.test.mjs, tests/doctor.test.mjs	New npm scripts run manifest, source, ShellCheck, and test validation. Source checks validate shell and Node syntax. doctor.sh checks local Node, Git, and Herdr prerequisites without starting a session.
Workflow documentation and readiness record CHANGELOG.md, CONTRIBUTING.md, README.md, docs/readiness.md	Documentation describes the new commands, archive state behavior, installation diagnostics, validation steps, live smoke evidence, and publishing guidance.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Low

Suggested reviewers: claude

Merge Risk: ⚪ Minimal · up to 4f0e2

No actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 8 files. (5 skipped: 5…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the two primary changes: completing Swarm harvest cleanup and adding readiness diagnostics.

Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 8 files. (5 skipped: 5 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/swarm-readiness

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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