shipwright-cli 2.1.1 → 2.2.0

package/docs/AGI-WHATS-NEXT.md

@@ -0,0 +1,69 @@
+# What's Next — Gaps, Not Fully Implemented, Not Integrated, E2E Audit
+
+**Status:** 2026-02-16  
+**Companion to:** [docs/AGI-PLATFORM-PLAN.md](AGI-PLATFORM-PLAN.md)
+
+---
+
+## 1. Still broken or risky
+
+| Item                                         | What                                                                                                                                                                                    | Fix                                                                                           |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| **Platform-health workflow threshold check** | ~~Report step used string comparison for threshold.~~ **Fixed:** Now normalizes to numeric with default 0.                                                                              | Done.                                                                                         |
+| **policy.sh when REPO_DIR not set**          | If a script is run from a different cwd (e.g. CI from repo root), `git rev-parse --show-toplevel` may point to a different repo.                                                        | Already uses SCRIPT_DIR/.. when SCRIPT_DIR is set; document that callers must set SCRIPT_DIR. |
+| **Daemon get_adaptive_heartbeat_timeout**    | When policy has no entry for a stage, we fall back to case statement only when `policy_get` is not available; when policy exists but stage is missing we keep HEALTH_HEARTBEAT_TIMEOUT. | Verified: logic is correct (policy stage → else case → HEALTH_HEARTBEAT_TIMEOUT).             |
+
+---
+
+## 2. Not fully implemented
+
+| Item                                       | What                                                                                                                                                                                          | Next step                                                                                       |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| ~~**Phase 3 libs not sourced**~~           | **Done.** `pipeline-quality.sh` sourced by `sw-pipeline.sh` and `sw-quality.sh`; `daemon-health.sh` sourced by `sw-daemon.sh`.                                                                | Wired and verified.                                                                             |
+| **Policy JSON Schema validation**          | We run `jq empty` in CI. Optional `ajv` step exists in platform-health workflow but is untested.                                                                                              | Trigger platform-health workflow once to validate; or document "schema is reference only".      |
+| ~~**Sweep workflow still hardcoded**~~     | **Done.** Sweep workflow now checks out repo, reads `config/policy.json`, and exports `STUCK_THRESHOLD_HOURS`, `RETRY_TEMPLATE`, `RETRY_MAX_ITERATIONS`, `STUCK_RETRY_MAX_ITERATIONS` to env. | Wired.                                                                                          |
+| ~~**Helpers adoption (Phase 1.4)**~~       | **Done.** 4 scripts migrated: `sw-hygiene.sh`, `sw-doctor.sh`, `sw-pipeline.sh`, `sw-quality.sh`. More in progress.                                                                           | Continue migrating remaining scripts in batches.                                                |
+| **Monolith decomposition (Phase 3.1–3.4)** | Pipeline stages, pipeline quality gate, daemon poll loop, daemon health are **not** extracted into separate sourced files. Line counts unchanged (8600+ / 6000+).                             | Defer or do incrementally: extract one module (e.g. pipeline quality gate block) and source it. |
+
+---
+
+## 3. Not integrated
+
+| Item                             | What                                                                                                                                              | Next step                                                                                                    |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| ~~**pipeline-quality.sh**~~      | **Done.** Sourced by `sw-pipeline.sh` and `sw-quality.sh`; duplicate policy_get for thresholds removed.                                           | Wired.                                                                                                       |
+| ~~**daemon-health.sh**~~         | **Done.** Sourced by `sw-daemon.sh`; `get_adaptive_heartbeat_timeout` calls `daemon_health_timeout_for_stage` when loaded.                        | Wired.                                                                                                       |
+| **Strategic + platform-hygiene** | Strategic reads `.claude/platform-hygiene.json` when present but there is no automated run of `hygiene platform-refactor` before strategic in CI. | Optional: add a job that runs platform-refactor then strategic (e.g. in shipwright-strategic.yml or patrol). |
+| ~~**Test suite and policy**~~    | **Done.** Policy read test added to `sw-hygiene-test.sh` (Test 12): verifies `policy_get` reads from config and returns default when key missing. | Covered.                                                                                                     |
+
+---
+
+## 4. Not audited E2E
+
+| Item                                | What                                                                                                                           | Next step                                                                                                                                                              |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Pipeline E2E with policy**        | E2E integration test runs pipeline but does not assert that coverage/quality thresholds come from policy.                      | Add a case: set policy.json with a custom threshold, run pipeline through compound_quality (or quality gate), assert threshold used (e.g. from logs or exit behavior). |
+| **Daemon E2E with policy**          | No test runs daemon with policy and checks POLL_INTERVAL or health timeouts.                                                   | Add daemon test that loads config + policy and asserts POLL_INTERVAL (or equivalent) matches policy.                                                                   |
+| **Platform-health workflow E2E**    | Workflow has not been run in CI yet (new file). Possible issues: path to scripts, `npm ci` vs script-only, permissions.        | Trigger workflow (workflow_dispatch) and fix any path/permission errors.                                                                                               |
+| **Doctor with no platform-hygiene** | When `.claude/platform-hygiene.json` is missing, doctor shows "Platform hygiene not run". Not wrong, but we never auto-run it. | Optional: doctor could run `hygiene platform-refactor` once and then show section (add flag `--skip-platform-scan` to preserve current fast behavior).                 |
+| **Full npm test with policy**       | `npm test` runs 98 suites; none specifically load policy or assert policy-driven behavior.                                     | Run `npm test` after policy changes to ensure no regressions; add one policy-aware test in hygiene or a new policy-test.sh.                                            |
+
+---
+
+## 5. Summary checklist
+
+- [x] **Wire or remove** pipeline-quality.sh and daemon-health.sh — sourced in pipeline, quality, daemon.
+- [ ] **Policy schema** — Optional ajv step exists in CI; trigger once to validate or document as reference-only.
+- [x] **Sweep** — Workflow reads policy.json and exports env vars.
+- [x] **Helpers** — 4 scripts migrated (hygiene, doctor, pipeline, quality); continuing batch migration.
+- [x] **Test** — Policy read test in hygiene-test.sh (Test 12).
+- [ ] **E2E** — Run platform-health workflow once; optionally add pipeline/daemon E2E with policy.
+- [ ] **TODO/FIXME/HACK** — Phase 4: triage backlog (issues or "accepted tech debt" comments); run dead-code and reduce fallbacks over time.
+
+---
+
+## References
+
+- [AGI-PLATFORM-PLAN.md](AGI-PLATFORM-PLAN.md) — Phases and success criteria.
+- [PLATFORM-TODO-BACKLOG.md](PLATFORM-TODO-BACKLOG.md) — TODO/FIXME/HACK triage.
+- [config-policy.md](config-policy.md) — Policy usage and schema.

package/docs/KNOWN-ISSUES.md

@@ -142,28 +142,6 @@ If only one pane is listed while agents are active, the fallback occurred.
 
 ---
 
-## White/Bright Pane Backgrounds on Agent Spawn
-
-**Severity:** Medium — cosmetic but distracting
-
-**Problem:** When Claude Code spawns agent panes via tmux, new panes sometimes inherit the terminal's default background (often white/bright) instead of the tmux dark theme.
-
-**Root Cause:** tmux's `window-style` applies at the window level but newly spawned panes from external processes (like Claude Code) don't always inherit it.
-
-**Fix:** As of v1.3.0, `shipwright-overlay.conf` uses `set-hook` to force the dark theme on every new pane:
-
-```conf
-set-hook -g after-split-window "select-pane -P 'bg=#1a1a2e,fg=#e4e4e7'"
-set-hook -g after-new-window   "select-pane -P 'bg=#1a1a2e,fg=#e4e4e7'"
-set-hook -g after-new-session  "select-pane -P 'bg=#1a1a2e,fg=#e4e4e7'"
-```
-
-Run `shipwright init` or `shipwright upgrade --apply` to get the updated overlay with these hooks.
-
-**Status:** ✅ Resolved in v1.3.0
-
----
-
 ## TPM plugins not loading
 
 **Severity:** Low — cosmetic
@@ -204,4 +182,4 @@ shipwright reaper --dry-run    # Preview what would be reaped
 
 Or use the tmux keybinding: `prefix + R` for a quick one-shot cleanup.
 
-**Status:** Resolved in v1.6.0
+**Status:** ✅ Resolved in v1.6.0 — reaper is the recommended solution.

package/docs/PLATFORM-TODO-BACKLOG.md

@@ -0,0 +1,41 @@
+# Platform TODO/FIXME/HACK Backlog
+
+**Source:** `shipwright hygiene platform-refactor` → `.claude/platform-hygiene.json`  
+**Purpose:** Track TODO, FIXME, and HACK markers for triage; strategic agent can suggest "Resolve TODO in X" as issues.
+
+## How to refresh
+
+```bash
+shipwright hygiene platform-refactor
+jq '.counts, .findings_sample[0:10]' .claude/platform-hygiene.json
+```
+
+**File:line list for triage** (after refresh):
+
+```bash
+jq -r '.findings_sample[]? | "\(.file):\(.line)"' .claude/platform-hygiene.json
+```
+
+## Triage
+
+- **TODO** — Create a GitHub issue or implement; add `TODO(issue #N)` in code when deferred.
+- **FIXME** — Same as TODO; prefer fix or document.
+- **HACK/KLUDGE** — Replace with proper fix or add comment: `# HACK: reason (tracked in #N)`.
+
+## Current counts (from last scan: 2026-02-16)
+
+| Marker | Count | Action                                                     |
+| ------ | ----- | ---------------------------------------------------------- |
+| TODO   | 37    | Triage; create issues or mark "accepted tech debt" in code |
+| FIXME  | 19    | Same as TODO                                               |
+| HACK   | 17    | Replace or document with tracking comment                  |
+
+See `.claude/platform-hygiene.json` for live counts and `findings_sample` (file:line).  
+Strategic agent uses this file when suggesting platform refactor issues.
+
+## Prioritized next steps
+
+1. **Run triage** — Use `jq -r '.findings_sample[]? | "\(.file):\(.line)"' .claude/platform-hygiene.json` to list all; batch into issues by file or theme.
+2. **High-traffic scripts first** — sw-pipeline.sh, sw-daemon.sh, sw-recruit.sh have most findings; address critical path items.
+3. **Dead code (Phase 4.3)** — Run `shipwright hygiene` dead-code scan; remove or refactor unused functions.
+4. **Fallback reduction (Phase 4.4)** — Where policy or adaptive data exists, remove duplicate hardcoded fallbacks.

package/docs/PLATFORM-TODO-TRIAGE.md

@@ -0,0 +1,56 @@
+# Platform TODO/FIXME/HACK Triage (Phase 4)
+
+**Date:** 2026-02-16  
+**Source:** `rg -n "TODO|FIXME|HACK" scripts/ docs/ config/ .github/ .claude/` (comment-style markers only)
+
+This document categorizes all TODO/FIXME/HACK comment markers found in the codebase. Only actual technical-debt comment markers are included (not variable names like `STATUS_TODO`, grep patterns, or documentation references).
+
+## Summary by Category
+
+| Category      | Count |
+| ------------- | ----- |
+| fix-now       | 0     |
+| github-issue  | 4     |
+| accepted-debt | 3     |
+| stale         | 0     |
+| **Total**     | **7** |
+
+## Full Triage Table
+
+| File                          | Line | Marker | Text                                                                | Category      |
+| ----------------------------- | ---- | ------ | ------------------------------------------------------------------- | ------------- |
+| scripts/sw-scale.sh           | 173  | TODO   | Integrate with tmux/SendMessage to spawn agent                      | github-issue  |
+| scripts/sw-scale.sh           | 199  | TODO   | Integrate with SendMessage to shut down agent                       | github-issue  |
+| scripts/sw-scale.sh           | 337  | TODO   | Parse pipeline context to generate actual recommendations           | github-issue  |
+| scripts/sw-swarm.sh           | 365  | TODO   | Implement queue depth and resource monitoring                       | github-issue  |
+| scripts/sw-testgen.sh         | 271  | TODO   | Claude unavailable (generated stub when Claude API unavailable)     | accepted-debt |
+| scripts/sw-testgen.sh         | 277  | TODO   | Implement test for \$func (placeholder in generated test template)  | accepted-debt |
+| scripts/sw-predictive-test.sh | 70   | TODO   | add input validation (intentional fixture for security patrol test) | accepted-debt |
+
+## Category Definitions
+
+- **fix-now**: Simple, actionable, can be addressed in a single session (e.g., replace hardcoded value with policy read).
+- **github-issue**: Needs a tracked GitHub issue for future work; non-trivial integration or feature work.
+- **accepted-debt**: Intentional or documented trade-off; no action required beyond documentation.
+- **stale**: No longer relevant; safe to remove from source.
+
+## Recommended Actions
+
+### github-issue (create issues)
+
+1. **sw-scale.sh** (lines 173, 199): Create issue _"Integrate scale up/down with tmux/SendMessage"_ — when scaling, spawn/shutdown agents via tmux or SendMessage instead of emitting events only.
+2. **sw-scale.sh** (line 337): Create issue _"Parse pipeline context for scale recommendations"_ — use active pipeline state to generate context-aware scaling recommendations.
+3. **sw-swarm.sh** (line 365): Create issue _"Implement queue depth and resource monitoring for swarm"_ — add queue depth and resource utilization monitoring to auto-scaling analysis.
+
+### accepted-debt (no change)
+
+- **sw-testgen.sh** (271, 277): These are intentional placeholders in generated test templates. The TODO text signals fallback behavior when Claude is unavailable or when no test implementation exists.
+- **sw-predictive-test.sh** (70): Intentional test fixture. The test creates sample vulnerable code (SQL injection, missing input validation) to verify the security patrol detects these issues. The TODO is part of the deliberately bad code.
+
+### stale
+
+None identified.
+
+### fix-now
+
+None identified. All TODOs are either deferred integration work (github-issue) or intentional placeholders (accepted-debt).

package/docs/README.md

@@ -0,0 +1,83 @@
+# Shipwright Documentation
+
+Navigation hub for all Shipwright docs. Start here or jump to a section.
+
+---
+
+## Root Documentation
+
+| Doc                                          | Purpose                                             |
+| -------------------------------------------- | --------------------------------------------------- |
+| [../README.md](../README.md)                 | Project overview, quick start, features             |
+| [../STRATEGY.md](../STRATEGY.md)             | Vision, priorities, technical principles            |
+| [../CHANGELOG.md](../CHANGELOG.md)           | Version history                                     |
+| [../.claude/CLAUDE.md](../.claude/CLAUDE.md) | 100+ commands, architecture, development guidelines |
+
+---
+
+## docs/ Sections
+
+### Strategy & GTM
+
+| Doc                                                                  | Purpose                                               |
+| -------------------------------------------------------------------- | ----------------------------------------------------- |
+| [strategy/README.md](strategy/README.md)                             | Strategic docs index — market research, brand, GTM    |
+| [strategy/01-market-research.md](strategy/01-market-research.md)     | Market size, competitive landscape, customer segments |
+| [strategy/02-mission-and-brand.md](strategy/02-mission-and-brand.md) | Mission, vision, brand positioning, messaging         |
+| [strategy/03-gtm-and-roadmap.md](strategy/03-gtm-and-roadmap.md)     | Go-to-market, 4-phase roadmap, success metrics        |
+
+### Team Patterns (Wave-Style)
+
+| Doc                                                                      | Purpose                                       |
+| ------------------------------------------------------------------------ | --------------------------------------------- |
+| [patterns/README.md](patterns/README.md)                                 | Wave patterns index — parallel agent work     |
+| [patterns/feature-implementation.md](patterns/feature-implementation.md) | Multi-component feature builds                |
+| [patterns/research-exploration.md](patterns/research-exploration.md)     | Codebase exploration                          |
+| [patterns/test-generation.md](patterns/test-generation.md)               | Test coverage campaigns                       |
+| [patterns/refactoring.md](patterns/refactoring.md)                       | Large-scale transformations                   |
+| [patterns/bug-hunt.md](patterns/bug-hunt.md)                             | Tracking complex bugs                         |
+| [patterns/audit-loop.md](patterns/audit-loop.md)                         | Self-reflection and quality gates in the loop |
+
+### tmux Research
+
+| Doc                                                                                              | Purpose                                   |
+| ------------------------------------------------------------------------------------------------ | ----------------------------------------- |
+| [tmux-research/TMUX-RESEARCH-INDEX.md](tmux-research/TMUX-RESEARCH-INDEX.md)                     | Index and reading guide                   |
+| [tmux-research/TMUX-BEST-PRACTICES-2025-2026.md](tmux-research/TMUX-BEST-PRACTICES-2025-2026.md) | Configuration bible                       |
+| [tmux-research/TMUX-ARCHITECTURE.md](tmux-research/TMUX-ARCHITECTURE.md)                         | Visual architecture, integration patterns |
+| [tmux-research/TMUX-QUICK-REFERENCE.md](tmux-research/TMUX-QUICK-REFERENCE.md)                   | Fast lookup, keybindings                  |
+| [tmux-research/TMUX-AUDIT.md](tmux-research/TMUX-AUDIT.md)                                       | Shipwright tmux config audit report       |
+
+### Platform & AGI
+
+| Doc                                                  | Purpose                                     |
+| ---------------------------------------------------- | ------------------------------------------- |
+| [AGI-PLATFORM-PLAN.md](AGI-PLATFORM-PLAN.md)         | Phased refactor for autonomous product dev  |
+| [AGI-WHATS-NEXT.md](AGI-WHATS-NEXT.md)               | Gaps, not-yet-implemented, E2E audit status |
+| [PLATFORM-TODO-BACKLOG.md](PLATFORM-TODO-BACKLOG.md) | TODO/FIXME/HACK triage backlog              |
+| [config-policy.md](config-policy.md)                 | Policy config schema and usage              |
+
+### Reference & Troubleshooting
+
+| Doc                                                            | Purpose                                             |
+| -------------------------------------------------------------- | --------------------------------------------------- |
+| [TIPS.md](TIPS.md)                                             | Power user tips, team patterns                      |
+| [KNOWN-ISSUES.md](KNOWN-ISSUES.md)                             | Tracked bugs and workarounds                        |
+| [definition-of-done.example.md](definition-of-done.example.md) | Template for `shipwright loop --definition-of-done` |
+
+---
+
+## .claude/ Agent Definitions
+
+| File                                                                 | Purpose                                                                 |
+| -------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [../.claude/DEFINITION-OF-DONE.md](../.claude/DEFINITION-OF-DONE.md) | Pipeline completion checklist                                           |
+| [../.claude/agents/](../.claude/agents/)                             | Role definitions (pipeline-agent, code-reviewer, test-specialist, etc.) |
+
+---
+
+## See Also
+
+- [demo/README.md](../demo/README.md) — Demo app for pipeline testing
+- [claude-code/CLAUDE.md.shipwright](../claude-code/CLAUDE.md.shipwright) — Downstream repo template
+- [.github/pull_request_template.md](../.github/pull_request_template.md) — PR checklist

package/docs/TIPS.md

@@ -145,7 +145,7 @@ Press `prefix + G` to toggle zoom on the current pane. This makes one agent fill
 
 ### Synchronized input
 
-Press `prefix + Alt-t` to toggle synchronized panes. When enabled, anything you type goes to ALL panes simultaneously. Useful for:
+Press `prefix + S` or `prefix + Alt-t` (M-t) to toggle synchronized panes. When enabled, anything you type goes to ALL panes simultaneously. Useful for:
 
 - Stopping all agents at once (`Ctrl-C` in all panes)
 - Running the same command in all agent directories
@@ -154,7 +154,7 @@ Press `prefix + Alt-t` to toggle synchronized panes. When enabled, anything you
 
 ### Capture pane contents
 
-Press `prefix + Alt-s` to save the current pane's visible content to a file in `/tmp/`. Useful for debugging agent output after the fact.
+Press `prefix + Alt-s` (M-s) to save the current pane's visible content to a file in `/tmp/`. Useful for debugging agent output after the fact.
 
 ---
 
@@ -341,3 +341,40 @@ Each agent writes findings/results to a file in this directory. The team lead re
 | [Test Generation](patterns/test-generation.md)               | 3-4+  | 2-3    | Coverage campaigns          |
 | [Refactoring](patterns/refactoring.md)                       | 3-4   | 2      | Large-scale transformations |
 | [Bug Hunt](patterns/bug-hunt.md)                             | 3-4   | 2-3    | Complex, elusive bugs       |
+
+---
+
+## Shipwright-Specific Tips
+
+### Use `--worktree` for parallel builds
+
+When running multiple agents or pipelines concurrently, use worktree isolation to avoid conflicts:
+
+```bash
+shipwright pipeline start --issue 42 --worktree
+shipwright loop "Refactor auth" --agents 2 --worktree
+```
+
+### Keep docs in sync
+
+```bash
+shipwright docs check   # Report stale AUTO sections (exit 1 if any)
+shipwright docs sync   # Regenerate all stale sections
+```
+
+### Definition of Done for loops
+
+Use a DoD file with `shipwright loop` to prevent premature completion:
+
+```bash
+shipwright loop "Add RBAC" --quality-gates --definition-of-done dod.md
+```
+
+Template at `docs/definition-of-done.example.md` (or `~/.shipwright/templates/` after install).
+
+### Run all test suites
+
+```bash
+npm test              # All 96+ test suites
+./scripts/sw-pipeline-test.sh   # Pipeline tests only (no real Claude/GitHub)
+```

package/docs/config-policy.md

@@ -0,0 +1,40 @@
+# Shipwright Policy Configuration
+
+**Location:** `config/policy.json` (repo) or `~/.shipwright/policy.json` (user override)
+
+All tunable policy — timeouts, limits, thresholds — should live in policy config. Scripts may still have in-code defaults for backwards compatibility but should prefer policy when present. Adaptive/learned values (e.g. from `~/.shipwright/adaptive-*.json`, optimization outputs) override policy when available.
+
+## Why centralize policy?
+
+- **AGI-level self-improvement:** Strategic agent and platform-refactor scans can suggest moving more values here instead of hardcoding.
+- **Single place to tune:** Daemon, pipeline, quality, strategic, and sweep behavior can be adjusted without editing scripts.
+- **Clean architecture:** Policy is data, not code; easier to validate, document, and evolve.
+
+## Schema (high level)
+
+| Section     | Purpose                                                                                                                                                 |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `daemon`    | Poll interval, health timeouts per stage, auto-scale/optimize/stale-reaper intervals, stale thresholds, `stale_timeout_multiplier`, `stale_state_hours` |
+| `pipeline`  | Max iterations, coverage/quality gate thresholds, memory baseline fallbacks, `max_cycles_convergence_cap`                                               |
+| `quality`   | Coverage and gate score thresholds, `audit_weights` (test_pass, coverage, security, etc.)                                                               |
+| `strategic` | Max issues per cycle, cooldown, overlap threshold, strategy line limit                                                                                  |
+| `sweep`     | Cron interval, stuck threshold, retry template and iteration caps                                                                                       |
+| `hygiene`   | Artifact age for cleanup                                                                                                                                |
+| `recruit`   | Agent recruitment: self_tune, match thresholds, model, promote thresholds                                                                               |
+
+## Usage
+
+- **From bash:** Prefer `jq` to read values, e.g. `jq -r '.daemon.poll_interval_seconds // 60' config/policy.json`.
+- **Override:** If `~/.shipwright/policy.json` exists, scripts may merge or prefer it over repo `config/policy.json`.
+- **Adaptive overrides:** Daemon/pipeline already use learned timeouts and iteration counts when present; those continue to override policy.
+
+## Schema
+
+- **config/policy.schema.json** — JSON Schema (draft-07) for policy. Validate in CI with `jq empty config/policy.json`; optional full validation with `ajv validate -s config/policy.schema.json -d config/policy.json`.
+
+## Roadmap
+
+- ~~Add `scripts/lib/policy.sh`~~ (done)
+- ~~Migrate daemon/pipeline/quality/strategic/hygiene defaults to read from policy~~ (done)
+- Strategic agent can recommend issues like "Move more tunables to config/policy.json."
+- Future: Add `recruit` section to `policy.schema.json` for full validation; schema currently allows additional properties.

package/docs/definition-of-done.example.md

@@ -3,6 +3,8 @@
 Use this template with `shipwright loop --definition-of-done <file>` to enforce completion criteria.
 Copy and customize for your project.
 
+> **Shipwright contributors:** See `.claude/DEFINITION-OF-DONE.md` for the project-specific checklist (bash standards, pipeline compliance, etc.).
+
 ## Checklist
 
 - [ ] All specified functionality is implemented

package/docs/patterns/README.md

@@ -35,6 +35,7 @@ Each wave:
 | [Test Generation](test-generation.md)               | Comprehensive test coverage campaigns     | 3-4+          | 2-3 agents |
 | [Refactoring](refactoring.md)                       | Large-scale code transformations          | 3-4           | 2 agents   |
 | [Bug Hunt](bug-hunt.md)                             | Tracking down complex, elusive bugs       | 3-4           | 2-3 agents |
+| [Audit Loop](audit-loop.md)                         | Self-reflection, quality gates in loop    | N/A           | 1-2 agents |
 
 ---
 
@@ -147,3 +148,7 @@ Choose the right model for each agent's task:
 | Architecture decisions, complex debugging | `opus`   | Best reasoning         |
 | Test generation                           | `sonnet` | Good pattern matching  |
 | Documentation, reports                    | `sonnet` | Clear writing          |
+
+---
+
+See also: [docs/README.md](../README.md) — Documentation hub

package/docs/strategy/02-mission-and-brand.md

@@ -57,7 +57,7 @@ Shipwright orchestrates autonomous Claude Code agent teams with full-cycle deliv
 
 **Headline:** From GitHub issue to merged PR with zero human in the loop
 **Description:** Label a GitHub issue with `shipwright` and walk away. The daemon watches, triages, plans, designs, builds, tests, reviews, gates, and merges — all while learning from failures and adapting its approach. Teams get back 20+ hours per engineer per month by eliminating manual triage, code review, and routine feature shipping.
-**Proof Point:** Shipwright dogfoods itself — this repo processes its own issues with zero human intervention. See [live examples](../../actions/workflows/shipwright-pipeline.yml).
+**Proof Point:** Shipwright dogfoods itself — this repo processes its own issues with zero human intervention. See [live examples](../../.github/workflows/shipwright-pipeline.yml).
 
 ### 2. **Autonomous Teams That Learn**
 
@@ -572,8 +572,8 @@ This document will evolve. Update it when:
 - Metrics show messaging isn't landing
 - Team adds new features that shift differentiation
 
-**Last updated:** 2025-02-14
-**Next review:** 2025-05-14 (quarterly)
+**Last updated:** 2026-02-14
+**Next review:** 2026-05-14 (quarterly)
 **Owner:** Brand / Product Marketing
 
 ---

package/docs/strategy/README.md

@@ -167,6 +167,7 @@ Enterprise Edition ($5K-$50K/yr)
 
 See also:
 
-- `/README.md` — Project overview
-- `.claude/CLAUDE.md` — Technical documentation
-- `.github/workflows/shipwright-pipeline.yml` — Production CI/CD
+- [docs/README.md](../README.md) — Documentation hub
+- [README.md](../../README.md) — Project overview
+- [.claude/CLAUDE.md](../../.claude/CLAUDE.md) — Technical documentation
+- [.github/workflows/shipwright-pipeline.yml](../../.github/workflows/shipwright-pipeline.yml) — Production CI/CD

package/docs/tmux-research/TMUX-AUDIT.md

@@ -5,6 +5,8 @@
 **Repository:** `/Users/sethford/Documents/shipwright`
 **Scope:** tmux configuration, CLI scripts, and integration code
 
+> **Note:** This audit is a point-in-time snapshot. Some issues may have been resolved since (e.g. sw-reaper.sh now uses `#{pane_id}` per line 117). Re-run the audit or verify each finding before acting.
+
 ---
 
 ## Executive Summary

package/docs/tmux-research/TMUX-RESEARCH-INDEX.md

@@ -1,5 +1,7 @@
 # tmux Research Index: Best-in-Class 2025-2026
 
+↑ [docs/](../README.md) — Documentation hub
+
 **Research Completion Date**: February 12, 2026
 **Focus Areas**: 14 comprehensive topics
 **Total Documentation**: 4 detailed guides + this index
@@ -87,6 +89,21 @@ This research compiled best-in-class tmux configurations, patterns, and integrat
 
 ---
 
+### 4. TMUX-AUDIT.md
+
+**Shipwright tmux configuration audit (this repo)**
+
+| Section            | Content                                              |
+| ------------------ | ---------------------------------------------------- |
+| Executive Summary  | Findings, severity counts (critical/major/minor)     |
+| Critical Issues    | Race conditions, command injection, pane format bugs |
+| Major Issues       | Pane referencing, error handling, version compat     |
+| Test Coverage Gaps | Integration scenarios, edge cases                    |
+
+**When to Use**: Understanding Shipwright's tmux integration issues, triage for fixes
+
+---
+
 ## Key Findings Summary
 
 ### Best-in-Class Configuration (2025-2026)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shipwright-cli",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Orchestrate autonomous Claude Code agent teams in tmux",
   "bin": {
     "shipwright": "./scripts/sw",
@@ -8,6 +8,7 @@
     "cct": "./scripts/sw"
   },
   "files": [
+    "config/",
     "scripts/",
     "!scripts/*-test.sh",
     "!scripts/build-release.sh",
@@ -29,7 +30,7 @@
   ],
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
-    "test": "bash scripts/sw-activity-test.sh && bash scripts/sw-adaptive-test.sh && bash scripts/sw-adversarial-test.sh && bash scripts/sw-architecture-enforcer-test.sh && bash scripts/sw-auth-test.sh && bash scripts/sw-autonomous-test.sh && bash scripts/sw-changelog-test.sh && bash scripts/sw-checkpoint-test.sh && bash scripts/sw-ci-test.sh && bash scripts/sw-cleanup-test.sh && bash scripts/sw-code-review-test.sh && bash scripts/sw-connect-test.sh && bash scripts/sw-context-test.sh && bash scripts/sw-cost-test.sh && bash scripts/sw-daemon-test.sh && bash scripts/sw-dashboard-test.sh && bash scripts/sw-db-test.sh && bash scripts/sw-decompose-test.sh && bash scripts/sw-deps-test.sh && bash scripts/sw-developer-simulation-test.sh && bash scripts/sw-discovery-test.sh && bash scripts/sw-docs-agent-test.sh && bash scripts/sw-docs-test.sh && bash scripts/sw-doctor-test.sh && bash scripts/sw-dora-test.sh && bash scripts/sw-durable-test.sh && bash scripts/sw-e2e-orchestrator-test.sh && bash scripts/sw-eventbus-test.sh && bash scripts/sw-feedback-test.sh && bash scripts/sw-fix-test.sh && bash scripts/sw-fleet-discover-test.sh && bash scripts/sw-fleet-test.sh && bash scripts/sw-fleet-viz-test.sh && bash scripts/sw-frontier-test.sh && bash scripts/sw-github-app-test.sh && bash scripts/sw-github-checks-test.sh && bash scripts/sw-github-deploy-test.sh && bash scripts/sw-github-graphql-test.sh && bash scripts/sw-guild-test.sh && bash scripts/sw-heartbeat-test.sh && bash scripts/sw-hygiene-test.sh && bash scripts/sw-incident-test.sh && bash scripts/sw-init-test.sh && bash scripts/sw-instrument-test.sh && bash scripts/sw-intelligence-test.sh && bash scripts/sw-jira-test.sh && bash scripts/sw-launchd-test.sh && bash scripts/sw-linear-test.sh && bash scripts/sw-logs-test.sh && bash scripts/sw-loop-test.sh && bash scripts/sw-memory-test.sh && bash scripts/sw-mission-control-test.sh && bash scripts/sw-model-router-test.sh && bash scripts/sw-otel-test.sh && bash scripts/sw-oversight-test.sh && bash scripts/sw-patrol-meta-test.sh && bash scripts/sw-pipeline-composer-test.sh && bash scripts/sw-pipeline-test.sh && bash scripts/sw-pipeline-vitals-test.sh && bash scripts/sw-pm-test.sh && bash scripts/sw-pr-lifecycle-test.sh && bash scripts/sw-predictive-test.sh && bash scripts/sw-prep-test.sh && bash scripts/sw-ps-test.sh && bash scripts/sw-public-dashboard-test.sh && bash scripts/sw-quality-test.sh && bash scripts/sw-reaper-test.sh && bash scripts/sw-recruit-test.sh && bash scripts/sw-regression-test.sh && bash scripts/sw-release-manager-test.sh && bash scripts/sw-release-test.sh && bash scripts/sw-remote-test.sh && bash scripts/sw-replay-test.sh && bash scripts/sw-retro-test.sh && bash scripts/sw-scale-test.sh && bash scripts/sw-security-audit-test.sh && bash scripts/sw-self-optimize-test.sh && bash scripts/sw-session-test.sh && bash scripts/sw-setup-test.sh && bash scripts/sw-standup-test.sh && bash scripts/sw-status-test.sh && bash scripts/sw-strategic-test.sh && bash scripts/sw-stream-test.sh && bash scripts/sw-swarm-test.sh && bash scripts/sw-team-stages-test.sh && bash scripts/sw-templates-test.sh && bash scripts/sw-testgen-test.sh && bash scripts/sw-tmux-pipeline-test.sh && bash scripts/sw-tmux-test.sh && bash scripts/sw-trace-test.sh && bash scripts/sw-tracker-test.sh && bash scripts/sw-triage-test.sh && bash scripts/sw-upgrade-test.sh && bash scripts/sw-ux-test.sh && bash scripts/sw-webhook-test.sh && bash scripts/sw-widgets-test.sh && bash scripts/sw-worktree-test.sh && bash scripts/sw-e2e-smoke-test.sh",
+    "test": "bash scripts/sw-agi-roadmap-test.sh && bash scripts/sw-activity-test.sh && bash scripts/sw-adaptive-test.sh && bash scripts/sw-adversarial-test.sh && bash scripts/sw-architecture-enforcer-test.sh && bash scripts/sw-auth-test.sh && bash scripts/sw-autonomous-test.sh && bash scripts/sw-changelog-test.sh && bash scripts/sw-checkpoint-test.sh && bash scripts/sw-ci-test.sh && bash scripts/sw-cleanup-test.sh && bash scripts/sw-code-review-test.sh && bash scripts/sw-connect-test.sh && bash scripts/sw-context-test.sh && bash scripts/sw-cost-test.sh && bash scripts/sw-daemon-test.sh && bash scripts/sw-dashboard-test.sh && bash scripts/sw-db-test.sh && bash scripts/sw-decompose-test.sh && bash scripts/sw-deps-test.sh && bash scripts/sw-developer-simulation-test.sh && bash scripts/sw-discovery-test.sh && bash scripts/sw-doc-fleet-test.sh && bash scripts/sw-docs-agent-test.sh && bash scripts/sw-docs-test.sh && bash scripts/sw-doctor-test.sh && bash scripts/sw-dora-test.sh && bash scripts/sw-durable-test.sh && bash scripts/sw-e2e-orchestrator-test.sh && bash scripts/sw-eventbus-test.sh && bash scripts/sw-feedback-test.sh && bash scripts/sw-fix-test.sh && bash scripts/sw-fleet-discover-test.sh && bash scripts/sw-fleet-test.sh && bash scripts/sw-fleet-viz-test.sh && bash scripts/sw-frontier-test.sh && bash scripts/sw-github-app-test.sh && bash scripts/sw-github-checks-test.sh && bash scripts/sw-github-deploy-test.sh && bash scripts/sw-github-graphql-test.sh && bash scripts/sw-guild-test.sh && bash scripts/sw-heartbeat-test.sh && bash scripts/sw-hygiene-test.sh && bash scripts/sw-incident-test.sh && bash scripts/sw-init-test.sh && bash scripts/sw-instrument-test.sh && bash scripts/sw-intelligence-test.sh && bash scripts/sw-jira-test.sh && bash scripts/sw-launchd-test.sh && bash scripts/sw-linear-test.sh && bash scripts/sw-logs-test.sh && bash scripts/sw-loop-test.sh && bash scripts/sw-memory-test.sh && bash scripts/sw-mission-control-test.sh && bash scripts/sw-model-router-test.sh && bash scripts/sw-otel-test.sh && bash scripts/sw-oversight-test.sh && bash scripts/sw-patrol-meta-test.sh && bash scripts/sw-pipeline-composer-test.sh && bash scripts/sw-pipeline-test.sh && bash scripts/sw-pipeline-vitals-test.sh && bash scripts/sw-pm-test.sh && bash scripts/sw-pr-lifecycle-test.sh && bash scripts/sw-predictive-test.sh && bash scripts/sw-prep-test.sh && bash scripts/sw-ps-test.sh && bash scripts/sw-public-dashboard-test.sh && bash scripts/sw-quality-test.sh && bash scripts/sw-reaper-test.sh && bash scripts/sw-recruit-test.sh && bash scripts/sw-regression-test.sh && bash scripts/sw-release-manager-test.sh && bash scripts/sw-release-test.sh && bash scripts/sw-remote-test.sh && bash scripts/sw-replay-test.sh && bash scripts/sw-retro-test.sh && bash scripts/sw-scale-test.sh && bash scripts/sw-security-audit-test.sh && bash scripts/sw-self-optimize-test.sh && bash scripts/sw-session-test.sh && bash scripts/sw-setup-test.sh && bash scripts/sw-standup-test.sh && bash scripts/sw-status-test.sh && bash scripts/sw-strategic-test.sh && bash scripts/sw-stream-test.sh && bash scripts/sw-swarm-test.sh && bash scripts/sw-team-stages-test.sh && bash scripts/sw-templates-test.sh && bash scripts/sw-testgen-test.sh && bash scripts/sw-tmux-pipeline-test.sh && bash scripts/sw-tmux-test.sh && bash scripts/sw-trace-test.sh && bash scripts/sw-tracker-test.sh && bash scripts/sw-triage-test.sh && bash scripts/sw-upgrade-test.sh && bash scripts/sw-ux-test.sh && bash scripts/sw-webhook-test.sh && bash scripts/sw-widgets-test.sh && bash scripts/sw-worktree-test.sh && bash scripts/sw-policy-e2e-test.sh && bash scripts/sw-e2e-smoke-test.sh",
     "test:smoke": "bash scripts/sw-e2e-smoke-test.sh",
     "test:integration": "bash scripts/sw-e2e-integration-test.sh"
   },

package/scripts/lib/daemon-health.sh

@@ -0,0 +1,32 @@
+# daemon-health.sh — Daemon health timeouts from policy (for sw-daemon.sh)
+# Source from sw-daemon.sh. Requires SCRIPT_DIR, REPO_DIR, and policy.sh.
+[[ -n "${_DAEMON_HEALTH_LOADED:-}" ]] && return 0
+_DAEMON_HEALTH_LOADED=1
+
+# Policy overrides when config/policy.json exists
+[[ -f "${SCRIPT_DIR:-}/lib/policy.sh" ]] && source "${SCRIPT_DIR:-}/lib/policy.sh"
+
+# Per-stage heartbeat timeout: policy .daemon.stage_timeouts.<stage> or .daemon.health_heartbeat_timeout
+# Usage: daemon_health_timeout_for_stage <stage> [fallback]
+daemon_health_timeout_for_stage() {
+    local stage="${1:-unknown}"
+    local fallback="${2:-120}"
+    if type policy_get &>/dev/null 2>&1; then
+        local policy_val
+        policy_val=$(policy_get ".daemon.stage_timeouts.$stage" "")
+        if [[ -n "$policy_val" && "$policy_val" =~ ^[0-9]+$ ]]; then
+            echo "$policy_val"
+            return 0
+        fi
+        policy_val=$(policy_get ".daemon.health_heartbeat_timeout" "$fallback")
+        [[ -n "$policy_val" && "$policy_val" =~ ^[0-9]+$ ]] && echo "$policy_val" || echo "$fallback"
+    else
+        case "$stage" in
+            build)  echo "300" ;;
+            test)   echo "180" ;;
+            review|compound_quality) echo "180" ;;
+            lint|format|intake|plan|design) echo "60" ;;
+            *)      echo "$fallback" ;;
+        esac
+    fi
+}

package/scripts/lib/pipeline-quality.sh

@@ -0,0 +1,23 @@
+# pipeline-quality.sh — Quality gate thresholds from policy (for pipeline + quality scripts)
+# Source from sw-pipeline.sh or sw-quality.sh. Requires SCRIPT_DIR and policy.sh.
+[[ -n "${_PIPELINE_QUALITY_LOADED:-}" ]] && return 0
+_PIPELINE_QUALITY_LOADED=1
+
+# Policy overrides when config/policy.json exists
+[[ -f "${SCRIPT_DIR:-}/lib/policy.sh" ]] && source "${SCRIPT_DIR:-}/lib/policy.sh"
+if type policy_get &>/dev/null 2>&1; then
+    PIPELINE_COVERAGE_THRESHOLD=$(policy_get ".pipeline.coverage_threshold_percent" "60")
+    PIPELINE_QUALITY_GATE_THRESHOLD=$(policy_get ".pipeline.quality_gate_score_threshold" "70")
+    QUALITY_COVERAGE_THRESHOLD=$(policy_get ".quality.coverage_threshold" "70")
+    QUALITY_GATE_SCORE_THRESHOLD=$(policy_get ".quality.gate_score_threshold" "70")
+else
+    PIPELINE_COVERAGE_THRESHOLD=60
+    PIPELINE_QUALITY_GATE_THRESHOLD=70
+    QUALITY_COVERAGE_THRESHOLD=70
+    QUALITY_GATE_SCORE_THRESHOLD=70
+fi
+
+# Minimum quality gate threshold for non-strict mode (floor)
+pipeline_quality_min_threshold() {
+    echo "${PIPELINE_QUALITY_GATE_THRESHOLD:-70}"
+}

package/scripts/lib/policy.sh

@@ -0,0 +1,32 @@
+# policy.sh — Load central policy from config/policy.json or ~/.shipwright/policy.json
+# Source this to get POLICY_* vars (optional). Scripts can also jq config/policy.json directly.
+# Usage: source "$SCRIPT_DIR/lib/policy.sh"   (after SCRIPT_DIR is set)
+[[ -n "${POLICY_LOADED:-}" ]] && return 0
+POLICY_LOADED=1
+
+# Resolve repo root (caller may set REPO_DIR)
+_REPO_DIR="${REPO_DIR:-}"
+[[ -z "$_REPO_DIR" && -n "${SCRIPT_DIR:-}" ]] && _REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+[[ -z "$_REPO_DIR" ]] && _REPO_DIR="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+
+_POLICY_FILE=""
+[[ -n "$_REPO_DIR" && -f "$_REPO_DIR/config/policy.json" ]] && _POLICY_FILE="$_REPO_DIR/config/policy.json"
+[[ -f "${HOME}/.shipwright/policy.json" ]] && _POLICY_FILE="${HOME}/.shipwright/policy.json"
+
+# Export a single helper: policy_get <json_path> [default]
+# e.g. policy_get ".daemon.poll_interval_seconds" 60
+policy_get() {
+    local path="$1"
+    local default="${2:-}"
+    if [[ -z "$_POLICY_FILE" || ! -f "$_POLICY_FILE" ]]; then
+        echo "$default"
+        return 0
+    fi
+    local val
+    val=$(jq -r "${path} // \"\"" "$_POLICY_FILE" 2>/dev/null)
+    if [[ -z "$val" || "$val" == "null" ]]; then
+        echo "$default"
+    else
+        echo "$val"
+    fi
+}