shipwright-cli 3.1.0 → 3.3.0

package/scripts/skills/architecture-design.md

@@ -0,0 +1,50 @@
+## Architecture Design Expertise
+
+Create an Architecture Decision Record (ADR) that future developers can use as a map.
+
+### Component Decomposition
+- Identify the 3-5 key components this change touches
+- Define clear boundaries — each component should have ONE reason to change
+- Specify interfaces between components (function signatures, data contracts, event schemas)
+- Dependencies should point inward — outer layers depend on inner, never the reverse
+
+### Interface Contracts
+- Define input/output types for every public function or API boundary
+- Specify error contracts — what errors can each component return?
+- Document preconditions and postconditions
+- Use types to enforce invariants — make invalid states unrepresentable
+
+### Design Decisions
+For each non-obvious design decision, document:
+1. **Context** — What constraint or requirement drives this?
+2. **Decision** — What did you choose?
+3. **Alternatives** — What else was considered? Why rejected?
+4. **Consequences** — What trade-offs does this create?
+
+### Patterns to Apply
+- **Dependency Injection** — Don't hardcode dependencies, accept them as parameters
+- **Single Responsibility** — Each module does one thing well
+- **Open/Closed** — Extend through composition, not modification
+- **Interface Segregation** — Don't force consumers to depend on methods they don't use
+
+### Anti-Patterns to Flag
+- God objects that know about everything
+- Circular dependencies between modules
+- Shared mutable state across components
+- Leaky abstractions (implementation details in public interfaces)
+
+### Testing Architecture
+- How will each component be tested in isolation?
+- What are the integration test boundaries?
+- Which external dependencies need mocking?
+
+### Required Output (Mandatory)
+
+Your output MUST include these sections when this skill is active:
+
+1. **Component Diagram**: ASCII-art or structured text diagram showing 3-5 components and their dependencies
+2. **Interface Contracts**: TypeScript-style signatures for all public APIs/functions with input/output types and error contracts
+3. **Data Flow**: How data moves between components (request → processing → response)
+4. **Error Boundaries**: Which components handle which errors, and how errors propagate up the stack
+
+If any section is not applicable, explicitly state why it's skipped.

package/scripts/skills/brainstorming.md

@@ -0,0 +1,43 @@
+## Brainstorming: Socratic Design Refinement
+
+**IMPORTANT: You are in an autonomous pipeline. Do NOT ask questions or wait for answers. Instead, answer each question yourself based on the issue context, codebase analysis, and your best judgment. Document your reasoning directly in the plan.**
+
+Before writing the implementation plan, challenge your assumptions with these questions:
+
+### Requirements Clarity
+- What is the **minimum viable change** that satisfies this issue?
+- Are there implicit requirements not stated in the issue?
+- What are the acceptance criteria? If none are stated, define them.
+
+### Design Alternatives
+- What are at least 2 different approaches to solve this?
+- What are the trade-offs of each? (complexity, performance, maintainability)
+- Which approach minimizes the blast radius of changes?
+
+### Risk Assessment
+- What could go wrong with the chosen approach?
+- What existing functionality could break?
+- Are there edge cases not covered by the issue description?
+
+### Dependency Analysis
+- What existing code does this depend on?
+- What other code depends on what you're changing?
+- Are there any circular dependency risks?
+
+### Simplicity Check
+- Can this be solved with fewer files changed?
+- Is there existing infrastructure you can reuse?
+- Would a simpler approach work for 90% of cases?
+
+Document your reasoning in the plan. Show the alternatives you considered and why you chose this approach.
+
+### Required Output (Mandatory)
+
+Your output MUST include these sections when this skill is active:
+
+1. **Task Decomposition**: Numbered list of concrete implementation tasks with explicit dependencies (e.g., "Task 3 blocks Task 5")
+2. **Risk Analysis**: For each identified risk, state what could break and your mitigation strategy
+3. **Definition of Done**: Specific, testable acceptance criteria that prove this issue is resolved
+4. **Alternatives Considered**: At least 2 approaches with explicit trade-offs (complexity, performance, maintainability, blast radius)
+
+If any section is not applicable, explicitly state why it's skipped.

package/scripts/skills/data-pipeline.md

@@ -0,0 +1,44 @@
+## Data Pipeline Expertise
+
+Apply these data engineering patterns:
+
+### Schema Design
+- Define schemas explicitly — never rely on implicit structure
+- Use migrations for all schema changes (never manual ALTER TABLE)
+- Add indexes for frequently queried columns
+- Consider denormalization for read-heavy paths
+
+### Data Integrity
+- Use transactions for multi-step operations
+- Implement idempotency keys for operations that could be retried
+- Validate data at ingestion — reject bad data early
+- Use constraints (NOT NULL, UNIQUE, FOREIGN KEY) in the database layer
+
+### Query Patterns
+- Avoid N+1 queries — use JOINs or batch loading
+- Use EXPLAIN to verify query plans for complex queries
+- Paginate large result sets — never SELECT * without LIMIT
+- Use parameterized queries — never string concatenation for SQL
+
+### Migration Safety
+- Migrations must be reversible (include rollback steps)
+- Test migrations on a copy of production data
+- Add new columns as nullable, then backfill, then add NOT NULL
+- Never drop columns in the same deploy as code changes
+
+### Backpressure & Resilience
+- Implement circuit breakers for external data sources
+- Use dead letter queues for failed processing
+- Set timeouts on all external calls
+- Monitor queue depths and processing latency
+
+### Required Output (Mandatory)
+
+Your output MUST include these sections when this skill is active:
+
+1. **Schema Changes**: Full migration SQL with both forward and rollback scripts, plus data backfill strategy if required
+2. **Data Flow Diagram**: Text diagram showing data ingestion → processing → output with failure points marked
+3. **Idempotency Strategy**: How the system handles duplicate requests (idempotency keys, deduplication, side-effect safety)
+4. **Rollback Plan**: Step-by-step process to revert schema changes and restore data consistency
+
+If any section is not applicable, explicitly state why it's skipped.

package/scripts/skills/deploy-safety.md

@@ -0,0 +1,64 @@
+## Deploy Safety: Ship Without Breaking Production
+
+Every deploy is a controlled experiment. Verify before promoting.
+
+### Pre-Deploy Checklist
+- [ ] All CI checks green on the exact commit being deployed
+- [ ] No open critical/security review findings
+- [ ] Database migrations are backward-compatible (old code can run with new schema)
+- [ ] Feature flags are in place for risky changes
+- [ ] Rollback plan is documented and tested
+
+### Blue-Green / Canary Strategy
+1. Deploy to inactive slot (green) — do NOT shift traffic yet
+2. Run health checks against green slot directly
+3. Run smoke tests against green slot
+4. Shift small percentage of traffic (canary: 5-10%)
+5. Monitor error rates for 5 minutes
+6. If clean, promote to 100%
+7. If errors spike, rollback immediately
+
+### Rollback Readiness
+- Verify rollback command works BEFORE deploying
+- Keep previous version running until new version is verified
+- Database migrations must be reversible (never drop columns in same deploy)
+- Cache invalidation: new version must handle old cached data
+
+### Deploy Risk by Issue Type
+
+**Frontend deploys:**
+- CDN cache invalidation timing
+- Browser cache busting (new asset hashes)
+- Progressive enhancement for users with old cached bundles
+
+**API deploys:**
+- Backward compatibility with existing clients
+- API versioning if breaking changes
+- Rate limit configuration for new endpoints
+
+**Database deploys:**
+- Migration order: schema first, then code, then cleanup
+- Backfill operations should be idempotent
+- Monitor query performance after index changes
+
+**Infrastructure deploys:**
+- DNS propagation delay
+- Connection draining for load balancer changes
+- Secret rotation: both old and new must work during transition
+
+### Incident Prevention
+- Deploy during low-traffic windows when possible
+- Have a human (or monitor) watching for 15 minutes post-deploy
+- Set up alerts for error rate spikes before deploying
+- Never deploy on Friday unless it's a hotfix
+
+### Required Output (Mandatory)
+
+Your output MUST include these sections when this skill is active:
+
+1. **Pre-Deploy Checklist**: Verification of all items (CI green, no critical findings, migrations backward-compatible, feature flags in place, rollback plan tested)
+2. **Blue-Green Strategy**: Specific sequence of steps from green deployment through canary through full promotion
+3. **Rollback Verification**: Confirmation that rollback command has been tested and works (not just theoretical)
+4. **Deploy Risk Assessment**: Explicit identification of risks by issue type (frontend cache, API compatibility, database migration, infrastructure changes)
+
+If any section is not applicable, explicitly state why it's skipped.

package/scripts/skills/documentation.md

@@ -0,0 +1,38 @@
+## Documentation Expertise
+
+For documentation-focused issues, apply a lightweight approach:
+
+### Scope
+- Focus on accuracy over comprehensiveness
+- Update only what's actually changed or incorrect
+- Remove outdated information rather than marking it deprecated
+- Keep examples current and runnable
+
+### Writing Style
+- Use active voice and present tense
+- Lead with the most important information
+- Use code examples for anything technical
+- Keep paragraphs short — 2-3 sentences max
+
+### Structure
+- Start with a one-line summary of what this documents
+- Include prerequisites and setup if applicable
+- Provide a quick start / most common usage first
+- Put advanced topics and edge cases later
+
+### Skip Heavy Stages
+This is a documentation change. The following pipeline stages can be simplified:
+- **Design stage**: Skip — documentation doesn't need architecture design
+- **Build stage**: Focus on file edits only, no compilation needed
+- **Test stage**: Verify links work and examples are syntactically correct
+- **Review stage**: Focus on accuracy and clarity, not code patterns
+
+### Required Output (Mandatory)
+
+Your output MUST include these sections when this skill is active:
+
+1. **What to Document**: List of documentation files created/modified with specific sections added to each
+2. **What to Skip**: Explicitly state which topics are NOT documented and why (e.g., "Advanced topic X is out of scope for this issue")
+3. **Audience**: Who will read this documentation (developers, users, operators) and what level of detail is appropriate
+
+If any section is not applicable, explicitly state why it's skipped.

package/scripts/skills/frontend-design.md

@@ -0,0 +1,45 @@
+## Frontend Design Expertise
+
+Apply these frontend patterns to your implementation:
+
+### Accessibility (Required)
+- All interactive elements must have keyboard support
+- Use semantic HTML elements (button, nav, main, article)
+- Include aria-labels for non-text interactive elements
+- Ensure color contrast meets WCAG AA (4.5:1 for text)
+- Test with screen reader mental model: does the DOM order make sense?
+
+### Responsive Design
+- Mobile-first: start with mobile layout, enhance for larger screens
+- Use relative units (rem, %, vh/vw) instead of fixed pixels
+- Test breakpoints: 320px, 768px, 1024px, 1440px
+- Touch targets: minimum 44x44px
+
+### Component Patterns
+- Keep components focused — one responsibility per component
+- Lift state up only when siblings need to share it
+- Use composition over inheritance
+- Handle loading, error, and empty states for every data-dependent component
+
+### Performance
+- Lazy-load below-the-fold content
+- Optimize images (appropriate format, size, lazy loading)
+- Minimize re-renders — check dependency arrays in effects
+- Avoid layout thrashing — batch DOM reads and writes
+
+### User Experience
+- Provide immediate feedback for user actions
+- Show loading indicators for operations > 300ms
+- Use optimistic updates where safe
+- Preserve user input on errors — never clear forms on failed submit
+
+### Required Output (Mandatory)
+
+Your output MUST include these sections when this skill is active:
+
+1. **Component Hierarchy**: Tree structure showing parent/child relationships and where state lives
+2. **State Management Approach**: How state flows (props, context, local state, external store) with explicit data flow
+3. **Accessibility Checklist**: WCAG AA compliance items checked (keyboard support, semantic HTML, color contrast, aria-labels)
+4. **Responsive Breakpoints**: Explicit breakpoints tested (320px, 768px, 1024px, 1440px) and how layout changes at each
+
+If any section is not applicable, explicitly state why it's skipped.

package/scripts/skills/generated/_refinements/adversarial-quality.patch.md

@@ -0,0 +1,3 @@
+
+### Learned (2026-03-09)
+Produce a manifest of identified edge cases with resolution status (fixed, deferred, acknowledged) so that future iterations can prioritize unresolved gaps.

package/scripts/skills/generated/_refinements/architecture-design.patch.md

@@ -0,0 +1,3 @@
+
+### Learned (2026-03-09)
+Include a step to verify that the designed configuration is discoverable by the relevant CLI command (e.g., `shipwright templates list`) before design is considered complete.

package/scripts/skills/generated/_refinements/brainstorming.patch.md

@@ -0,0 +1,3 @@
+
+### Learned (2026-03-09)
+For configuration/infrastructure tasks, brainstorming should explicitly produce time/complexity bounds and validate them against at least one real-world example of the target use case before proceeding to design.

package/scripts/skills/generated/cli-version-management.md

@@ -0,0 +1,29 @@
+## CLI Version Management: Package.json Integration
+
+**Pattern**: Read version from package.json, format for display, handle edge cases.
+
+### Version Source Resolution
+- **Canonical source**: Always read from `package.json` at repo root or script-relative location
+- **Path resolution**: Use `$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)` to find script dir, then traverse up to repo root (where package.json lives)
+- **Validation**: Verify JSON is valid before parsing; provide actionable error if missing/corrupt
+
+### Version Extraction & Formatting
+- **Parser**: Use `jq '.version' package.json` (safer than regex or sed)
+- **Format standard**: `Shipwright vX.Y.Z` (prefix + space + v + semver)
+- **Validation**: Warn if version doesn't match semver (x.y.z pattern); don't fail, but log warning
+
+### Error Handling
+- Missing file: `error "package.json not found at <path>"` → exit 1
+- Invalid JSON: Catch jq error → `error "package.json is malformed"` → exit 1
+- Missing version field: `error "version field missing in package.json"` → exit 1
+
+### Testing Pattern
+- **Unit test**: Create temp package.json with known version, invoke command, assert exact output
+- **Isolation**: Don't depend on real package.json; create fixtures for each test case
+- **Edge cases**: test missing file, malformed JSON, missing version field, non-semver version
+- **Bash 3.2 safe**: Use `$()` not `<()`, no `readarray`, no `declare -A`
+
+### CLI Display
+- **Standard output**: Version string only (e.g., `Shipwright v1.2.3`), no extra whitespace or formatting
+- **Exit code**: 0 on success, 1 on error
+- **Integration**: `sw hello` should output version alongside any other greeting output

package/scripts/skills/generated/collection-system-validation.md

@@ -0,0 +1,99 @@
+## Collection System Validation & Auto-Repair
+
+### Core Responsibility
+Design and implement validators that check heterogeneous data collection systems (events.jsonl, pipeline state, DORA metrics, cost tracking, memory patterns) for health, detect gaps systematically, and safely auto-repair broken collectors.
+
+### Multi-System Validation Architecture
+
+**System-Specific Validators**
+- Events system: Check events.jsonl writes, verify timestamps are recent, detect missing event types (pipeline_start, pipeline_complete, stage_start)
+- Pipeline state: Verify .claude/pipeline-state.md writes work, timestamps are fresh
+- Cost tracking: Validate ~/.shipwright/costs.json updates, compare against expected frequency
+- DORA metrics: Check metrics.json is populated, has recent data points
+- Memory system: Validate memory files created, readable, contain valid patterns
+
+**Gap Detection Patterns**
+- Missing events for active pipelines (spawn time + expected stages = missing events)
+- Stale timestamps (last write > threshold, e.g., 24h)
+- Unreachable files (ENOENT, EPERM on expected paths)
+- Incomplete writes (truncated JSON, missing closing braces)
+- Permission issues (ls -l reveals 000 or other broken states)
+
+**Health Scoring**
+- Per-system: 0-100 based on recency, write success rate, completeness
+- Overall: Weighted average (events 30%, state 25%, cost 15%, DORA 20%, memory 10%)
+- Thresholds: Critical (<30), Warning (30-70), Healthy (>70)
+
+### Auto-Repair Strategies (Safety First)
+
+**File System Repairs**
+- Fix permissions: `chmod 755 ~/.shipwright/` (idempotent, safe)
+- Create missing dirs: `mkdir -p` on standard paths (safe if idempotent)
+- Cleanup truncated files: Back up to `.bak`, recreate empty or last-known-good version
+- Rotate stale logs: Move logs >30d to archive (preserve data)
+
+**Collector Restarts**
+- Daemon restart: Signal SIGHUP, not SIGKILL (graceful)
+- Loop restart: Only if process is hung (check for zombie)
+- Checkpoint restore: Use last valid state from .claude/checkpoints/ before restart
+
+**Data Restoration**
+- Never delete data unilaterally—always preserve backups
+- Restore from last checkpoint if available
+- If repair requires data loss, alert and wait for manual approval
+
+### Health Reporting Format
+
+```json
+{
+  "timestamp": "2026-03-10T14:23:00Z",
+  "overall_health": 85,
+  "systems": {
+    "events": {"health": 95, "last_write": "2026-03-10T14:22:00Z", "status": "healthy"},
+    "pipeline_state": {"health": 80, "last_write": "2026-03-10T14:21:00Z", "status": "warning", "gaps": ["build stage missing"]},
+    "cost_tracking": {"health": 100, "last_write": "2026-03-10T14:20:00Z", "status": "healthy"},
+    "dora_metrics": {"health": 60, "last_write": "2026-03-10T12:00:00Z", "status": "warning", "stale_hours": 2},
+    "memory": {"health": 90, "status": "healthy"}
+  },
+  "repairs_attempted": [{"system": "dora", "action": "chmod 755", "success": true}],
+  "alerts": ["DORA metrics not updated in 2 hours"]
+}
+```
+
+### Patrol Integration
+
+**Daily Validation Run**
+- Schedule: 02:00 UTC (off-peak, before metrics review)
+- Runs: `shipwright metrics validate --repair` (auto-repair enabled in daemon)
+- Output: JSON + summary logged to events.jsonl with type `metrics_validation`
+
+**Alert Thresholds**
+- Overall health < 70: Alert to patrol log, escalate for manual review
+- Missing events > 5 consecutive runs: Critical alert
+- Permission failures: Attempt repair, alert if repair fails
+
+**Repair Decision Logic**
+- Low-risk repairs (permissions, mkdir): Auto-execute
+- Medium-risk (truncated file cleanup): Log and alert, wait 10 min for manual override, then auto-execute
+- High-risk (collector restart): Alert and wait for approval, or skip if patrol is in critical path
+
+### Testing Strategy
+
+**Unit Tests per Validator**
+- events.jsonl: Simulate ENOENT, EPERM, truncated JSON, missing event types
+- State file: Simulate stale timestamp, missing fields
+- Cost tracker: Simulate missing file, zero events
+- DORA: Simulate outdated metrics.json, malformed JSON
+- Memory: Simulate unreadable patterns, corrupted files
+
+**Integration Test (Proof of Repair)**
+1. Create healthy baseline (all systems populated)
+2. Inject failures (chmod 000, truncate file, stop daemon)
+3. Run validator with --repair
+4. Verify: All systems restored to healthy state, backups created, alerts fired
+5. Run again: Zero new repairs needed (idempotency proof)
+
+**Negative Tests**
+- High-risk repairs skipped correctly when approval not given
+- Repair doesn't cause data loss (backups preserved)
+- Validator doesn't create false positives on legitimate stale data (e.g., idle repos)

package/scripts/skills/generated/large-scale-c-refactoring-coordination.md

@@ -0,0 +1,97 @@
+## Large-Scale C Refactoring Phase Coordination
+
+When refactoring 30+ files across a C codebase with strict testing requirements (3849+ tests, ASan compliance), poor phase planning causes cascading test failures, leaked allocations detected late, and scope creep that undermines velocity.
+
+### Phase Planning Discipline
+
+1. **Identify minimal-dependency phases** — Group files by coupling:
+   - Phase 1: New module + infrastructure (hu_data_loader, CMake xxd setup)
+   - Phase 2: Static/non-behavioral changes (word lists, prompts)
+   - Phase 3: Threshold configurations (no logic changes)
+   - Phase 4: Integrations (callers updated)
+   - Don't merge phases with circular dependencies or high rework risk
+
+2. **Test stability checkpoints** — After each phase:
+   - Run full suite: `./build/human_tests` (all 3849+)
+   - Run ASan: `./build/human_tests --asan-report` (0 errors)
+   - Diff test counts: ensure no tests skip or disappear
+   - Single regression fails the phase
+
+3. **Rollback points** — If a phase breaks tests:
+   - Never push through red tests hoping later phases fix them
+   - Revert the phase, fix root cause, re-test in isolation
+   - Document why it failed in your memory for similar patterns
+
+### One-Concern-Per-Commit Rule
+
+Large refactors tempt you to batch changes. Resist:
+
+```
+❌ WRONG: "Externalize data + refactor loader API + add config"
+✅ RIGHT: "Add hu_data_loader module with xxd embedding"
+         "Update CMakeLists.txt for xxd generation"
+         "Replace hardcoded word lists with hu_data_load() calls"
+```
+
+Each commit should pass tests independently. If a later commit breaks something, bisect pinpoints the exact change.
+
+### ASan Leak Detection Between Phases
+
+- After each phase, run: `ASAN_OPTIONS=detect_leaks=1 ./build/human_tests`
+- New leaks in data loading must be fixed before moving forward
+- Track ASan suppressions in `.claudeignore` or test config, document why
+- Example: if xxd-embedded data needs special cleanup, add integration test to verify
+
+### Scope Creep Prevention
+
+- **Resist refactoring temptation** — If you find ugly code while phasing, note it in MEMORY but don't fix it now. Separate PR later.
+- **Document phase boundaries** — Write them in your task list and stick to scope.
+- **Review diffs carefully** — Large phases hide changes. Keep phase PRs under 400 lines if possible.
+
+### Coordination Across Phases
+
+- Use a shared checklist (`.claude/phase-checklist.md`) to track: data files created, config schema updated, tests passing, ASan clean
+- If a later phase reveals earlier phase needs rework, update the phase and re-run its tests before continuing
+- Don't hold uncommitted changes across phases—commit or stash between phases
+
+### Common Pitfalls
+
+1. **Building embedded defaults before measuring** — Measure original hardcoded values first (word count, threshold ranges, string encodings). Ensure embedded defaults match exactly.
+2. **Forgetting cleanup paths** — New data loader functions must free allocations. ASan will catch this at phase end, but better to test per-function.
+3. **CMake fragility** — xxd-based file generation can fail silently on some platforms. Test incremental rebuilds (`touch data/file.txt && cmake --build build`) on Linux + macOS.
+4. **Config backward compatibility** — If adding new required fields (e.g., `data_dir`), don't break existing deployments. Provide sensible defaults or environment variable overrides.
+5. **Mixing behaviors** — Don't change logic (e.g., "also apply new threshold") in the same phase as externalizing the threshold. Two phases: externalize first, change behavior second.
+
+### Example Phase Sequence
+
+```
+Phase 0: Setup
+  - Create src/data/loader.c with hu_data_load() skeleton
+  - Create data/ directory structure
+  - Add CMake xxd command (doesn't embed anything yet)
+  - Tests: 3849 pass, ASan clean
+
+Phase 1: Embedded Defaults
+  - Add a single data file (e.g., data/prompts/safety_rules.txt)
+  - Generate embedded_safety_rules.c via xxd
+  - Implement hu_data_load() to return embedded data
+  - Update one caller to use hu_data_load()
+  - Tests: 3849 pass, ASan clean, verify embedded data loads correctly
+
+Phase 2: File Override Path
+  - Extend hu_data_load() to check ~/.human/data/ first
+  - Add unit test: hu_data_load() returns file override if present
+  - Tests: 3849 pass, ASan clean
+
+Phase 3: Remaining Data Files
+  - Add remaining data files (word lists, prompts, etc.)
+  - Update all callers to hu_data_load()
+  - Tests: 3849 pass, ASan clean
+
+Phase 4: Config Integration
+  - Add temp_dir, data_dir, threshold fields to config
+  - Update callers to use config fields instead of hardcoded values
+  - Tests: 3849 pass, ASan clean
+```
+
+Each phase is independently testable and deployable.