shipwright-cli 2.1.2 → 2.2.0

package/.claude/agents/devops-engineer.md

@@ -6,18 +6,20 @@ You are a DevOps and CI/CD specialist for the Shipwright project. You work on Gi
 
 Workflows live in `.github/workflows/` with the `shipwright-*.yml` naming prefix:
 
-| Workflow                    | Purpose                       |
-| --------------------------- | ----------------------------- |
-| `shipwright-release.yml`    | Release automation            |
-| `shipwright-auto-label.yml` | Issue/PR auto-labeling        |
-| `shipwright-auto-retry.yml` | Failed pipeline auto-retry    |
-| `shipwright-health.yml`     | Health check monitoring       |
-| `shipwright-patrol.yml`     | Security patrol scans         |
-| `shipwright-pipeline.yml`   | CI pipeline trigger           |
-| `shipwright-sweep.yml`      | Stale resource cleanup        |
-| `shipwright-watchdog.yml`   | Process watchdog              |
-| `shipwright-test.yml`       | Test suite runner             |
-| `shipwright-website.yml`    | Documentation site deployment |
+| Workflow                         | Purpose                         |
+| -------------------------------- | ------------------------------- |
+| `shipwright-release.yml`         | Release automation              |
+| `shipwright-auto-label.yml`      | Issue/PR auto-labeling          |
+| `shipwright-auto-retry.yml`      | Failed pipeline auto-retry      |
+| `shipwright-health.yml`          | Health check monitoring         |
+| `shipwright-platform-health.yml` | Platform health monitoring      |
+| `shipwright-docs.yml`            | Docs sync (AUTO sections, wiki) |
+| `shipwright-patrol.yml`          | Security patrol scans           |
+| `shipwright-pipeline.yml`        | CI pipeline trigger             |
+| `shipwright-sweep.yml`           | Stale resource cleanup          |
+| `shipwright-watchdog.yml`        | Process watchdog                |
+| `shipwright-test.yml`            | Test suite runner               |
+| `shipwright-website.yml`         | Documentation site deployment   |
 
 ## GitHub CLI Patterns
 

package/.claude/agents/doc-fleet-agent.md

@@ -0,0 +1,99 @@
+# Documentation Fleet Agent
+
+You are a specialized agent in the Shipwright documentation fleet. The fleet orchestrates multiple agents, each with a focused documentation role. Your specific role is assigned at spawn time.
+
+## Fleet Roles
+
+### 1. Doc Architect (leader)
+
+You own the **documentation structure and information architecture**. Your job:
+
+- Audit the full docs tree: `docs/`, `.claude/`, `README.md`, `STRATEGY.md`, `CHANGELOG*.md`
+- Identify duplicate content, orphan pages, missing cross-links, and structural gaps
+- Propose a coherent information hierarchy with clear navigation paths
+- Ensure every doc has a clear audience (contributor, user, operator, agent)
+- Create/update index files (`docs/README.md`, `docs/strategy/README.md`, etc.)
+- Maintain a docs manifest in `.claude/pipeline-artifacts/docs-manifest.json`
+
+### 2. Claude MD Specialist
+
+You own **all CLAUDE.md files and agent role definitions**. Your job:
+
+- Audit `.claude/CLAUDE.md` for accuracy, completeness, and freshness
+- Ensure AUTO sections are current (cross-reference with actual script files)
+- Audit `.claude/agents/*.md` role definitions — are they accurate? complete?
+- Audit `claude-code/CLAUDE.md.shipwright` template for downstream repos
+- Remove stale content, update command tables, fix broken references
+- Ensure development guidelines match actual codebase conventions
+- Keep the CLAUDE.md focused and scannable — no bloat
+
+### 3. Strategy & Plans Curator
+
+You own **strategic documentation and planning artifacts**. Your job:
+
+- Audit `STRATEGY.md` — are priorities still current? are metrics up to date?
+- Audit `docs/AGI-PLATFORM-PLAN.md` — completed items should be marked done
+- Audit `docs/AGI-WHATS-NEXT.md` — remove completed gaps, add new ones
+- Audit `docs/PLATFORM-TODO-BACKLOG.md` — triage and prioritize
+- Audit `docs/strategy/` directory — market research, brand, GTM freshness
+- Cross-reference strategy docs with actual shipped features
+- Remove aspirational content that's now reality; add new aspirations
+
+### 4. Pattern & Guide Writer
+
+You own **developer-facing guides and patterns**. Your job:
+
+- Audit `docs/patterns/` — are all wave patterns still accurate?
+- Audit `docs/TIPS.md` — add new tips from recent development
+- Audit `docs/KNOWN-ISSUES.md` — resolved issues should be removed
+- Audit `docs/config-policy.md` — does it match `config/policy.json` schema?
+- Audit `docs/definition-of-done.example.md` vs `.claude/DEFINITION-OF-DONE.md`
+- Create any missing how-to guides (e.g., "How to add a new agent")
+- Ensure tmux docs in `docs/tmux-research/` are current
+
+### 5. README & Onboarding Optimizer
+
+You own the **public-facing documentation and first-impression experience**. Your job:
+
+- Audit `README.md` — is it accurate, compelling, and up-to-date?
+- Verify all command tables match actual CLI behavior (test with `sw <cmd> help`)
+- Ensure install instructions work on a fresh machine
+- Audit the "Quick Start" flow — does it actually work?
+- Check that badge URLs, links, and examples are valid
+- Optimize for scannability: TOC, headers, tables over prose
+- Audit `.github/pull_request_template.md` for completeness
+
+## Rules for All Roles
+
+### DO
+
+- Read before writing — always verify current state before making changes
+- Preserve existing AUTO section markers — they power the docs sync system
+- Use tables for reference content, prose for concepts
+- Cross-link between documents using relative paths
+- Commit after each meaningful change with descriptive messages
+- Verify links point to files that actually exist
+- Keep line lengths reasonable (< 120 chars for prose)
+
+### DON'T
+
+- Don't create documentation for features that don't exist yet
+- Don't duplicate content across files — link instead
+- Don't remove AUTO section markers (they're used by `sw docs sync`)
+- Don't change the structure of `.claude/CLAUDE.md` without good reason — many tools parse it
+- Don't add aspirational/marketing language to technical docs
+- Don't introduce emoji in technical documentation
+- Don't create new files when updating existing ones would suffice
+
+### Shell Standards (if editing scripts or examples)
+
+- Bash 3.2 compatible
+- `set -euo pipefail` at the top
+- Atomic file writes: tmp + `mv`
+- JSON via `jq --arg`, never string interpolation
+
+## Completion
+
+- Output `LOOP_COMPLETE` when your assigned documentation scope is fully audited and updated
+- List what you changed, what you removed, and what you recommend for follow-up
+- Do not mark complete if you found issues you couldn't resolve — document them instead

package/.claude/agents/test-specialist.md

@@ -1,6 +1,6 @@
 # Test Specialist
 
-You are a test development specialist for the Shipwright project. The project has 20 test suites with 320+ individual tests, all written in Bash following a consistent harness pattern.
+You are a test development specialist for the Shipwright project. The project has 90+ test suites (see `package.json` scripts.test and the AUTO:test-suites table in `.claude/CLAUDE.md`), all written in Bash following a consistent harness pattern.
 
 ## Test Harness Conventions
 
@@ -160,9 +160,11 @@ echo "================================"
 - **Deterministic**: tests must produce the same results on every run
 - **Fast**: individual test functions should complete in under 5 seconds
 
-## Current Test Suites (20)
+## Current Test Suites
 
-| Suite                        | Tests                   | Source Under Test                     |
+See the AUTO:test-suites table in `.claude/CLAUDE.md` for the full list (90+ suites). Representative suites:
+
+| Suite                        | Source Under Test       |
 | ---------------------------- | ----------------------- | ------------------------------------- |
 | sw-pipeline-test.sh          | Pipeline flow           | sw-pipeline.sh                        |
 | sw-daemon-test.sh            | Daemon lifecycle        | sw-daemon.sh                          |

package/README.md

@@ -12,35 +12,55 @@
 <p align="center">
   <a href="https://github.com/sethdford/shipwright/actions/workflows/test.yml"><img src="https://github.com/sethdford/shipwright/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
   <a href="https://github.com/sethdford/shipwright/actions/workflows/shipwright-pipeline.yml"><img src="https://github.com/sethdford/shipwright/actions/workflows/shipwright-pipeline.yml/badge.svg" alt="Pipeline"></a>
-  <img src="https://img.shields.io/badge/tests-500%2B_passing-4ade80?style=flat-square" alt="500+ tests">
-  <img src="https://img.shields.io/badge/version-2.1.0-00d4ff?style=flat-square" alt="v2.1.0">
+  <img src="https://img.shields.io/badge/tests-99_suites_passing-4ade80?style=flat-square" alt="99 suites">
+  <img src="https://img.shields.io/badge/version-2.1.2-00d4ff?style=flat-square" alt="v2.1.2">
   <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT License">
   <img src="https://img.shields.io/badge/bash-3.2%2B-7c3aed?style=flat-square" alt="Bash 3.2+">
 </p>
 
 ---
 
+## Table of Contents
+
+- [Shipwright Builds Itself](#shipwright-builds-itself)
+- [What's New in v2.1.2](#whats-new-in-v212)
+- [How It Works](#how-it-works)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Commands](#commands)
+- [Pipeline Templates for Teams](#pipeline-templates-for-teams)
+- [Configuration](#configuration)
+- [Prerequisites](#prerequisites)
+- [Architecture](#architecture)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
 ## Shipwright Builds Itself
 
 This repo uses Shipwright to process its own issues. Label a GitHub issue with `shipwright` and the autonomous pipeline takes over: semantic triage, plan, design, build, test, review, quality gates, PR. No human in the loop.
 
-**[See it live](../../actions/workflows/shipwright-pipeline.yml)** | **[Create an issue](../../issues/new?template=shipwright.yml)** and watch it build.
+**[See it live](https://github.com/sethdford/shipwright/actions/workflows/shipwright-pipeline.yml)** | **[Create an issue](https://github.com/sethdford/shipwright/issues/new?template=shipwright.yml)** and watch it build.
 
 ---
 
-## What's New in v2.1.0
+## What's New in v2.1.2
+
+**AGI-Level Agent Recruitment** — dynamic role creation, LLM-powered matching, closed-loop learning:
 
-**tmux visual overhaul** — role-colored borders, pipeline status widgets, and active pane depth:
+- **`recruit match`** — AI/heuristic task→role matching with `--json` output for pipeline integration
+- **`recruit team`** — Context-aware team composition with cost estimation
+- **`recruit route`** — Smart routing based on agent performance history
+- **Cross-system integration** — Pipeline, PM, triage, loop, and swarm all use recruit for model/role selection
+- **Self-tuning heuristics** — System learns keyword→role mappings from successful outcomes
+- **Meta-learning** — Accuracy tracking and self-correction for matching decisions
+- **CI auto-discovery** — All 99 test suites now run in CI (previously 26)
 
-- **Role-Colored Pane Borders** — Border color reflects agent role (builder=blue, reviewer=orange, tester=yellow)
-- **Pipeline Stage Badge** — Live `⚙ BUILD` / `⚡ TEST` / `↑ PR` widget in status bar with stage-colored badges
-- **Active Pane Lift** — Subtle background depth effect between active and inactive panes
-- **Agent Count Widget** — `λN` heartbeat-based agent counter in status bar
-- **`shipwright init --repair`** — Force clean reinstall after OS upgrades
-- **Color Palette Overhaul** — Warm grays replace harsh near-white text across all tmux chrome
-- **7 tmux Bug Fixes** — Pane indexing, capture bindings, reload, clipboard, and more
+**v2.1.0**: tmux visual overhaul — role-colored borders, pipeline status widgets, active pane depth
 
-**v2.0.0 highlights**: 18 autonomous agents, 100+ CLI commands, intelligence layer, multi-repo fleet, local mode
+**v2.0.0**: 18 autonomous agents, 100+ CLI commands, intelligence layer, multi-repo fleet, local mode
 
 ---
 
@@ -187,7 +207,7 @@ Each stage is configurable with quality gates that auto-proceed or pause for app
 | Template     | Stages                            | Use Case                  |
 | ------------ | --------------------------------- | ------------------------- |
 | `fast`       | intake → build → test → PR        | Quick fixes, score >= 70  |
-| `standard`   | + plan, review                    | Normal feature work       |
+| `standard`   | + plan, design, review            | Normal feature work       |
 | `full`       | All 12 stages                     | Production deployment     |
 | `hotfix`     | Minimal, all auto                 | Urgent production fixes   |
 | `autonomous` | All stages, all auto              | Daemon-driven delivery    |
@@ -282,12 +302,12 @@ Instant issue processing via GitHub webhooks instead of polling. Register webhoo
 ### PR Lifecycle Automation
 
 ```bash
-shipwright pr auto-review
-shipwright pr merge
+shipwright pr review <pr#>
+shipwright pr merge <pr#>
 shipwright pr cleanup
 ```
 
-Fully automated PR management: auto-review based on predictive risk and coverage, intelligent auto-merge when gates pass, cleanup stale branches. Reduces manual PR overhead by 90%.
+Fully automated PR management: review based on predictive risk and coverage, intelligent auto-merge when gates pass, cleanup stale branches. Reduces manual PR overhead by 90%.
 
 ### Fleet Auto-Discovery
 
@@ -304,10 +324,11 @@ ACID-safe state management replacing JSON files. Replaces volatile `.claude/pipe
 ### Issue Decomposition
 
 ```bash
-shipwright decompose --issue 42
+shipwright decompose analyze 42
+shipwright decompose decompose 42
 ```
 
-AI-powered issue analysis: auto-split complex features into manageable subtasks, create child issues with inherited labels/assignees, generate dependency graph for parallel execution.
+AI-powered issue analysis: `analyze` scores complexity; `decompose` creates child issues with inherited labels/assignees and a dependency graph.
 
 ### Linux systemd Support
 
@@ -338,16 +359,16 @@ shipwright pipeline start --issue 42
 shipwright daemon start --detach
 
 # Agent teams
-shipwright swarm list
+shipwright swarm status
 shipwright recruit --roles builder,tester
 shipwright standup
-shipwright guild members
+shipwright guild list
 
 # Quality gates
 shipwright code-review
 shipwright security-audit
 shipwright testgen
-shipwright quality check
+shipwright quality validate
 
 # Observability
 shipwright vitals
@@ -375,11 +396,11 @@ shipwright upgrade --apply
 shipwright --help
 ```
 
-See `.claude/CLAUDE.md` for the complete 100+ command reference organized by workflow.
+See [.claude/CLAUDE.md](.claude/CLAUDE.md) for the complete 100+ command reference organized by workflow. Full documentation: [docs/](docs/).
 
 ## Pipeline Templates for Teams
 
-24 team templates covering the full SDLC:
+25 team templates covering the full SDLC:
 
 ```bash
 shipwright templates list
@@ -411,7 +432,7 @@ shipwright templates list
 
 ## Architecture
 
-95+ bash scripts (~100K lines), 27 test suites (500+ tests), plus a TypeScript dashboard server. Bash 3.2 compatible — runs on macOS and Linux out of the box.
+100+ bash scripts (~100K lines), 99 test suites (1000+ tests), plus a TypeScript dashboard server. Bash 3.2 compatible — runs on macOS and Linux out of the box.
 
 **Core Layers:**
 
@@ -477,12 +498,12 @@ Tools & UX
 
 ## Contributing
 
-**Let Shipwright build it:** Create an issue using the [Shipwright template](../../issues/new?template=shipwright.yml) and label it `shipwright`. The autonomous pipeline will triage, plan, build, test, review, and create a PR.
+**Let Shipwright build it:** Create an issue using the [Shipwright template](https://github.com/sethdford/shipwright/issues/new?template=shipwright.yml) and label it `shipwright`. The autonomous pipeline will triage, plan, build, test, review, and create a PR.
 
 **Manual development:** Fork, branch, then:
 
 ```bash
-npm test    # 450+ tests across 24 suites
+npm test    # 1000+ tests across 99 suites
 ```
 
 ## License

package/claude-code/CLAUDE.md.shipwright

@@ -19,7 +19,7 @@ This project uses [Shipwright](https://github.com/sethdford/shipwright) for auto
 | `shipwright cost show` | Token usage and spending dashboard |
 | `shipwright cost budget set <amount>` | Set daily budget limit |
 | `shipwright cost remaining-budget` | Check remaining daily budget (used by auto-scaler) |
-| `shipwright memory list` | View captured failure patterns |
+| `shipwright memory show` | View captured failure patterns |
 | `shipwright dashboard` | Real-time web dashboard (requires Bun) |
 | `shipwright dashboard start` | Start dashboard in background |
 | `shipwright heartbeat list` | Show agent heartbeat status |
@@ -170,7 +170,7 @@ Generate with `shipwright daemon init`, then edit `.claude/daemon-config.json`:
 | Command | Purpose |
 |---------|---------|
 | `shipwright pipeline resume` | Resume from last completed stage |
-| `shipwright memory show` | View captured failure patterns |
+| `shipwright memory show`     | View captured failure patterns |
 | `shipwright doctor` | Diagnose setup issues |
 | `shipwright status` | Check team and agent status |
 | `shipwright cleanup --force` | Kill orphaned sessions |

package/config/policy.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://shipwright.dev/schemas/policy-v1.json",
+  "description": "Central policy for Shipwright — timeouts, limits, thresholds. Prefer adaptive/learned overrides when available.",
+  "version": "1",
+  "daemon": {
+    "poll_interval_seconds": 60,
+    "health_heartbeat_timeout": 120,
+    "stage_timeouts": {
+      "intake": 60,
+      "plan": 60,
+      "design": 60,
+      "lint": 60,
+      "format": 60,
+      "build": 300,
+      "test": 180,
+      "review": 180,
+      "compound_quality": 180
+    },
+    "auto_scale_interval_cycles": 5,
+    "optimize_interval_cycles": 10,
+    "stale_reaper_interval_cycles": 10,
+    "stale_timeout_multiplier": 2,
+    "stale_state_hours": 2
+  },
+  "pipeline": {
+    "max_iterations_default": 10,
+    "max_cycles_convergence_cap": 50,
+    "coverage_threshold_percent": 60,
+    "quality_gate_score_threshold": 70,
+    "memory_baseline_fallback_percent": 20,
+    "memory_inject_fallback_percent": 30
+  },
+  "quality": {
+    "coverage_threshold": 60,
+    "gate_score_threshold": 70,
+    "audit_weights": {
+      "test_pass": 30,
+      "coverage": 20,
+      "security": 20,
+      "architecture": 15,
+      "correctness": 15
+    }
+  },
+  "strategic": {
+    "max_issues_per_cycle": 5,
+    "cooldown_seconds": 14400,
+    "overlap_threshold_percent": 60,
+    "strategy_lines": 200
+  },
+  "sweep": {
+    "cron_minutes": 30,
+    "stuck_threshold_hours": 4,
+    "retry_template": "full",
+    "retry_max_iterations": 25,
+    "stuck_retry_max_iterations": 30
+  },
+  "hygiene": {
+    "artifact_age_days": 7
+  },
+  "recruit": {
+    "self_tune_min_matches": 5,
+    "self_tune_min_success_rate": 60,
+    "match_confidence_threshold": 0.3,
+    "max_match_history_size": 5000,
+    "max_profile_task_history": 50,
+    "meta_learning_accuracy_floor": 50,
+    "auto_evolve_after_outcomes": 20,
+    "llm_timeout_seconds": 30,
+    "default_model": "sonnet",
+    "promote_threshold_tasks": 10,
+    "promote_threshold_success_rate": 85
+  }
+}

package/config/policy.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://shipwright.dev/schemas/policy-v1.json",
+  "title": "Shipwright Policy",
+  "description": "Central policy for Shipwright — timeouts, limits, thresholds.",
+  "type": "object",
+  "properties": {
+    "version": { "type": "string" },
+    "daemon": {
+      "type": "object",
+      "properties": {
+        "poll_interval_seconds": { "type": "integer", "minimum": 10 },
+        "health_heartbeat_timeout": { "type": "integer", "minimum": 60 },
+        "stage_timeouts": {
+          "type": "object",
+          "additionalProperties": { "type": "integer", "minimum": 0 }
+        },
+        "auto_scale_interval_cycles": { "type": "integer" },
+        "optimize_interval_cycles": { "type": "integer" },
+        "stale_reaper_interval_cycles": { "type": "integer" }
+      }
+    },
+    "pipeline": {
+      "type": "object",
+      "properties": {
+        "max_iterations_default": { "type": "integer" },
+        "coverage_threshold_percent": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "quality_gate_score_threshold": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "memory_baseline_fallback_percent": { "type": "integer" },
+        "memory_inject_fallback_percent": { "type": "integer" }
+      }
+    },
+    "quality": {
+      "type": "object",
+      "properties": {
+        "coverage_threshold": { "type": "integer" },
+        "gate_score_threshold": { "type": "integer" }
+      }
+    },
+    "strategic": {
+      "type": "object",
+      "properties": {
+        "max_issues_per_cycle": { "type": "integer" },
+        "cooldown_seconds": { "type": "integer" },
+        "overlap_threshold_percent": { "type": "integer" },
+        "strategy_lines": { "type": "integer" }
+      }
+    },
+    "sweep": {
+      "type": "object",
+      "properties": {
+        "cron_minutes": { "type": "integer" },
+        "stuck_threshold_hours": { "type": "integer" },
+        "retry_template": { "type": "string" },
+        "retry_max_iterations": { "type": "integer" },
+        "stuck_retry_max_iterations": { "type": "integer" }
+      }
+    },
+    "hygiene": {
+      "type": "object",
+      "properties": {
+        "artifact_age_days": { "type": "integer" }
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/docs/AGI-PLATFORM-PLAN.md

@@ -0,0 +1,122 @@
+# AGI-Level Platform Plan: Refactor, Refine, Remove, Redo
+
+**Status:** Active  
+**Created:** 2026-02-16  
+**Goal:** Make Shipwright a fully autonomous product development team — reduce hardcoded/static policy, clean architecture, and let the platform improve itself.
+
+---
+
+## Success Criteria
+
+- **Policy:** All tunables (timeouts, limits, thresholds) live in `config/policy.json` or env; scripts read via `policy_get` or jq. Zero new hardcoded magic numbers in core paths.
+- **Monoliths:** `sw-pipeline.sh` and `sw-daemon.sh` decomposed into sourced modules (stages, health, poll loop); single-file line count < 2000 for core orchestration.
+- **Helpers:** All scripts use `lib/helpers.sh` for colors/output/events (or a single other canonical source); no duplicated info/success/warn/error blocks.
+- **Platform health:** `shipwright hygiene platform-refactor` counts trend down (hardcoded, fallback, TODO/FIXME/HACK); strategic agent routinely suggests platform refactor issues.
+- **Continuous:** Hygiene + platform-refactor run in CI or weekly; strategic reads platform-hygiene and policy; AGI-level criterion is part of product thinking.
+
+---
+
+## Phase 1: Foundation (Policy + Helpers Adoption)
+
+**Goal:** Policy and helpers are the default; at least two key scripts read from policy; plan is visible and tracked.
+
+**Status:** Done. 1.1–1.3 done (strategic + hygiene read policy; plan linked from STRATEGY P6). 1.4 done — 4 scripts migrated to helpers (hygiene, doctor, pipeline, quality); batch migration continuing.
+
+| #   | Task                                                                                                                                                                                              | Owner | Acceptance                                                                                   |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | -------------------------------------------------------------------------------------------- |
+| 1.1 | **Strategic reads policy** — In sw-strategic.sh, after constants block, source policy.sh and override STRATEGIC_MAX_ISSUES, COOLDOWN, STRATEGY_LINES, OVERLAP_THRESHOLD from policy when present. | Agent | strategic run uses config/policy.json values when file exists; fallback to current literals. |
+| 1.2 | **Hygiene reads policy** — In sw-hygiene.sh, read artifact_age_days from policy (policy_get ".hygiene.artifact_age_days" 7) when policy.sh available.                                             | Agent | hygiene --artifact-age default comes from policy when present.                               |
+| 1.3 | **Document plan** — This doc (docs/AGI-PLATFORM-PLAN.md) is the single source of truth; link from STRATEGY.md P6.                                                                                 | Done  | STRATEGY P6 references this plan.                                                            |
+| 1.4 | **Helpers adoption** — Migrate 3–5 high-traffic scripts to source lib/helpers.sh instead of defining info/success/warn/error (e.g. sw-strategic, sw-hygiene, sw-quality).                         | Agent | No duplicate color/output blocks in those scripts; they source helpers.                      |
+
+---
+
+## Phase 2: Policy Migration (First Batch)
+
+**Goal:** Daemon, pipeline, quality, and sweep read their key tunables from policy; hardcoded count drops.
+
+**Status:** Done. 2.1–2.5 complete. Daemon (timeouts, intervals), pipeline (coverage/quality thresholds), quality (thresholds), sweep (workflow reads policy.json and exports env vars).
+
+| #   | Task                                                                                                                                                                                                                 | Owner | Acceptance                                                                                                                |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------- |
+| 2.1 | **Daemon timeouts** — In sw-daemon.sh, health heartbeat and stage timeouts read from policy_get when policy exists (else keep current defaults).                                                                     | Agent | daemon_health_timeout_for_stage uses policy .daemon.stage_timeouts and .daemon.health_heartbeat_timeout.                  |
+| 2.2 | **Daemon intervals** — POLL_INTERVAL, AUTO_SCALE_INTERVAL, OPTIMIZE_INTERVAL, STALE_REAPER_INTERVAL read from policy when present.                                                                                   | Agent | One place (policy) controls daemon timing.                                                                                |
+| 2.3 | **Pipeline thresholds** — Coverage and quality gate thresholds in pipeline read from policy (pipeline.coverage_threshold_percent, quality_gate_score_threshold, memory fallbacks).                                   | Agent | Pipeline quality gate uses policy_get for thresholds when policy exists.                                                  |
+| 2.4 | **Quality script** — sw-quality.sh reads coverage_threshold and gate_score_threshold from policy.                                                                                                                    | Agent | quality validate/gate use policy.                                                                                         |
+| 2.5 | **Sweep (workflow)** — Document in plan that sweep workflow (shipwright-sweep.yml) uses hardcoded 4h/30min; add optional env or later step to read from policy (e.g. script that emits workflow inputs from policy). | Agent | Either sweep reads policy in a wrapper or doc states “sweep defaults documented in config/policy.json; override via env.” |
+
+---
+
+## Phase 3: Monolith Decomposition
+
+**Goal:** Pipeline and daemon are split into sourced modules; no single file > 2000 lines for orchestration core.
+
+**Status:** 3.2 and 3.4 done (pipeline-quality.sh and daemon-health.sh created, wired, and sourced). 3.1 and 3.3 (full stage/poll extraction) deferred — high risk, requires incremental approach.
+
+| #   | Task                                                                                                                                                                                                   | Owner | Acceptance                                                            |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | --------------------------------------------------------------------- |
+| 3.1 | **Pipeline stages lib** — Extract stage run logic (run_intake, run_plan, run_build, run_test, …) into scripts/lib/pipeline-stages.sh or scripts/lib/pipeline-stages/\*.sh; source from sw-pipeline.sh. | Agent | sw-pipeline.sh sources stages; line count drops; existing tests pass. |
+| 3.2 | **Pipeline quality gate** — Extract quality gate and audit selection into scripts/lib/pipeline-quality.sh; source from sw-pipeline.sh.                                                                 | Agent | Quality gate logic in one place; pipeline sources it.                 |
+| 3.3 | **Daemon poll loop** — Extract daemon_poll_loop, daemon_poll_issues, daemon_reap_completed into scripts/lib/daemon-poll.sh; source from sw-daemon.sh.                                                  | Agent | Daemon sources daemon-poll; line count drops.                         |
+| 3.4 | **Daemon health** — Extract health check and timeout logic into scripts/lib/daemon-health.sh.                                                                                                          | Agent | Daemon sources daemon-health; tests pass.                             |
+
+---
+
+## Phase 4: Cleanup (TODO / FIXME / HACK / Dead Code)
+
+**Goal:** Triage all TODO/FIXME/HACK; remove dead code; reduce fallback count.
+
+**Status:** 4.1–4.2 done (PLATFORM-TODO-BACKLOG.md + file:line triage one-liner). 4.3–4.4 ongoing (run hygiene dead-code; reduce fallbacks over time).
+
+| #   | Task                                                                                                                                                                                                    | Owner | Acceptance                                               |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | -------------------------------------------------------- |
+| 4.1 | **TODO/FIXME backlog** — Generate list (from platform-refactor findings); create GitHub issues for each or mark “accepted tech debt” in code; strategic can then suggest “Resolve TODO in X” as issues. | Agent | Every TODO/FIXME has an issue or comment; count tracked. |
+| 4.2 | **HACK/KLUDGE** — Same as 4.1; replace or document.                                                                                                                                                     | Agent | HACK count explained or reduced.                         |
+| 4.3 | **Dead code** — Run hygiene dead-code; remove or refactor unused functions/scripts.                                                                                                                     | Agent | Dead code count in hygiene report drops.                 |
+| 4.4 | **Fallback reduction** — Where adaptive/learned data exists, remove duplicate hardcoded fallbacks so one code path wins (policy → adaptive → minimal default).                                          | Agent | Fallback count in platform-refactor scan drops.          |
+
+---
+
+## Phase 5: Continuous (CI + Strategic + Metrics)
+
+**Goal:** Platform health is measured and improved continuously.
+
+**Status:** 5.1 done (shipwright-platform-health.yml with threshold gate). 5.2 done (strategic reads platform-hygiene + AGI rule). 5.3 done (doctor shows platform health counts). 5.4 done (policy.schema.json + optional ajv in CI). Policy read test added to hygiene-test.
+
+| #   | Task                                                                                                                                                                                               | Owner | Acceptance                                                |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | --------------------------------------------------------- |
+| 5.1 | **Hygiene in CI** — Add a job (e.g. in shipwright-sweep or a new workflow) that runs `shipwright hygiene platform-refactor` and fails or warns if counts exceed thresholds (e.g. hardcoded > 100). | Agent | CI runs platform-refactor; optional gate.                 |
+| 5.2 | **Strategic creates refactor issues** — Ensure strategic prompt and platform-hygiene input are used; run strategic periodically so it suggests platform refactor issues.                           | Done  | Strategic already has platform health + AGI rule.         |
+| 5.3 | **Metrics dashboard** — Optional: add a small “platform health” section to dashboard or doctor showing platform-hygiene counts and trend.                                                          | Agent | Doctor or dashboard shows hardcoded/fallback/TODO counts. |
+| 5.4 | **Policy schema** — Add JSON schema for config/policy.json and validate in CI or on load.                                                                                                          | Agent | policy.json validated against schema.                     |
+
+---
+
+## Current Snapshot (from platform-refactor scan)
+
+- **hardcoded:** 58 | **fallback:** 54 | **TODO:** 37 | **FIXME:** 19 | **HACK/KLUDGE:** 17
+- **Largest scripts:** sw-pipeline.sh (8600+), sw-daemon.sh (6000+), sw-loop.sh (2400+), sw-recruit.sh (2200+), sw-prep.sh (1600+), sw-memory.sh (1600+).
+- _Last scan: 2026-02-16. Re-scan after helpers migration to track delta._
+
+---
+
+## Sweep defaults (Phase 2.5)
+
+Sweep workflow (`.github/workflows/shipwright-sweep.yml`) uses hardcoded values: stuck = 4h, cron every 30min, retry template = full, retry max_iterations = 25, stuck retry = 30. These are documented in **config/policy.json** under `sweep`. To override: set env in the workflow (e.g. `STUCK_THRESHOLD_HOURS`, `RETRY_MAX_ITERATIONS`) or add a wrapper step that reads policy and exports env for the dispatch step.
+
+## How to Use This Plan
+
+1. **Run platform-refactor:** `shipwright hygiene platform-refactor` to refresh `.claude/platform-hygiene.json`.
+2. **Run strategic:** `shipwright strategic run` to get AI-suggested issues (including platform refactor).
+3. **Execute phases in order:** Phase 1 → 2 → 3 → 4 → 5; mark tasks done in this doc or in issues.
+4. **Policy first:** Any new tunable goes in config/policy.json; scripts use policy_get or jq.
+
+---
+
+## References
+
+- **STRATEGY.md** — P6 Platform Self-Improvement, Technical Principle 8 (AGI-level criterion).
+- **config/policy.json** — Central policy schema.
+- **docs/config-policy.md** — Policy usage and roadmap.
+- **scripts/lib/policy.sh** — policy_get helper.
+- **scripts/lib/helpers.sh** — Canonical colors and output helpers.