@zerwiz/ymir 0.1.16 → 0.1.18

package/assets/reference/docs/plans/phase-3-measurable-goals.md

@@ -0,0 +1,106 @@
+# Phase 3: Add Measurable Goals to ticket-manager Skill
+
+**Project**: command (COM)
+**Priority**: Critical
+**Estimated Effort**: 3 days
+**Measurable Goal**: `ticket_measurable_goal_coverage:100%:mcp_validation:30d:95%`
+
+---
+
+## Problem Statement
+
+Dex Horthy: "An agent given a number to move will go much further than one given a description." Current ticket templates have **Acceptance Criteria** (descriptive) but no **Measurable Goal** (quantitative, business-tied). The "back-pressure" metric is what lets an agent run experiments, check data daily, and pick a winner.
+
+## Current State
+
+- Ticket template at `/home/zerwiz/.pi/thoughts/global/templates/ticket-template.md` has Acceptance Criteria (checkboxes)
+- Ticket frontmatter in `ticket-manager/SKILL.md` has no `measurable_goal` field
+- Plans have "Success Criteria" but they're descriptive, not quantitative
+- No validation that goals are measurable vs descriptive
+
+## Requirements
+
+### 1. Add `measurable_goal` Frontmatter Field
+```yaml
+measurable_goal: "metric:target:method:timeframe:rollback"
+# Examples:
+# "checkout_conversion:15%:mixpanel:14d:11%"
+# "api_p99_latency:200ms:datadog:7d:300ms"
+# "deployment_frequency:daily:github:30d:weekly"
+```
+
+Format: `metric_name:target_value:measurement_method:timeframe:rollback_threshold`
+
+### 2. Update Ticket Template
+Add Measurable Goal section after Acceptance Criteria:
+```markdown
+## Measurable Goal (Back-Pressure Metric)
+
+**Metric**: [e.g., checkout conversion rate]
+**Current Baseline**: [e.g., 12.3%]
+**Target**: [e.g., 15.0%]
+**Measurement Method**: [e.g., Mixpanel event 'checkout_complete' / 'checkout_start']
+**Timeframe**: [e.g., 14 days post-deploy]
+**Rollback Threshold**: [e.g., < 11% for 48h]
+```
+
+### 3. Update `ticket-manager` Skill
+- Add `measurable_goal` to frontmatter schema
+- Validation: must match `metric:target:method:timeframe:rollback` format
+- `create-plan` requires measurable goal from ticket
+- `validate-implementation` checks goal achievement
+
+### 4. Add Validation Script
+`bin/measurable-goal-validate.sh` — checks goal is quantitative, not descriptive
+
+## Implementation Approach
+
+**Use MCP for all ticket/plan operations** — never hand-write markdown or git-push to f-rr-d. The MCP keeps DB row + canonical markdown + collision-safe numbering in sync.
+
+1. **Edit `ticket-manager/SKILL.md`**: Add `measurable_goal` to frontmatter schema
+2. **Edit global `ticket-template.md`**: Add Measurable Goal section (via MCP `templates_update`)
+3. **Edit `create-plan/SKILL.md`**: Require measurable goal from linked ticket (read via `tickets_get`)
+4. **Edit `validate-implementation/SKILL.md`**: Add goal validation step
+5. **Create `bin/measurable-goal-validate.sh`**: Format + quantitative check
+6. **Test via MCP**: Create ticket with `tickets_create` including measurable_goal, verify validation
+
+## Phases
+
+- [ ] Phase 3.1: Add frontmatter field + template section (1 day)
+- [ ] Phase 3.2: Update create-plan to require goal (0.5 day)
+- [ ] Phase 3.3: Update validate-implementation to check goal (0.5 day)
+- [ ] Phase 3.4: Create validation script (0.5 day)
+- [ ] Phase 3.5: Test with existing tickets (0.5 day)
+
+## Success Criteria
+
+### Automated Verification:
+- [ ] New tickets require `measurable_goal` frontmatter
+- [ ] Format validation rejects descriptive goals ("improve UX")
+- [ ] `create-plan` fails if ticket lacks measurable goal
+- [ ] `validate-implementation` reports goal status
+
+### Manual Verification:
+- [ ] Goals are quantitative (numbers, not adjectives)
+- [ ] Measurement method is specific (tool + query)
+- [ ] Rollback threshold defined
+
+## Acceptance Criteria
+
+- [ ] 100% of new tickets in `command` project have measurable_goal within 30 days
+- [ ] Rollback threshold: < 95% coverage triggers review
+- [ ] Descriptive goals ("make it faster") rejected by validation
+
+## Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Hard to quantify some work | Medium | Medium | Allow "learning goal" variant with captain sign-off |
+| Metric infrastructure missing | Low | High | Document required analytics setup |
+| Gaming the metric | Low | Medium | Rollback threshold + captain review |
+
+## References
+
+- Research: `docs/agentic-engineering-workflow.md` (Measurable Goals section)
+- Dex Horthy: "If you can tell it a measurable output, the agent will move mountains for you"
+- Back-pressure concept: LLM-as-judge acceptable, but real business metric drives convergence

package/assets/reference/docs/plans/phase-4-context-budget.md

@@ -0,0 +1,106 @@
+# Phase 4: Create context-budget Skill
+
+**Project**: command (COM)
+**Priority**: Medium
+**Estimated Effort**: 3 days
+**Status**: ✅ COMPLETED (2026-09-10)
+**Measurable Goal**: `context_budget_warning_accuracy:95%:token_tracking:30d:90%`
+
+---
+
+## Problem Statement
+
+Dex Horthy: "The 'dumb zone' at ~50% context is real — for models AND humans." Current factory has no token budget awareness. Agents token-max while bottleneck is code review, leading to degraded model quality in the second half of context window.
+
+## Current State
+
+- No token tracking in `fm-session-start.sh`, `fm-spawn.sh`, or harness adapters
+- No warning at 50% context ("dumb zone")
+- No enforcement of "structural decisions early when cheap"
+- Harness adapters don't report token usage
+
+## What Was Implemented
+
+### 1. Created `context-budget` Skill
+**Location**: `~/.config/opencode/skills/context-budget/` + copied to `command/.agents/skills/context-budget/`
+
+- `SKILL.md` — skill definition with triggers, thresholds, integration points
+- `bin/context-budget.sh` — token tracking script (tested: green<30, yellow=30-50, red=50-85, critical≥85)
+- `config/context-budget.yaml` — thresholds per harness
+
+### 2. Token Thresholds (implemented)
+```yaml
+thresholds:
+  green: 30      # < 30% — structural decisions optimal
+  yellow: 50     # 30-50% — "dumb zone" — make structural decisions NOW
+  red: 85        # 50-85% — warn, suggest compaction
+  critical: 85   # > 85% — force compaction or handoff
+```
+
+### 3. Integration with Existing Skills
+- `create-plan`: Added context budget check before design work; added `## Context Budget at Creation` to plan template
+- `ticket-executor`: Added `Context Budget Enforcement` section; Phase 0 validation gate includes budget check
+- `validate-implementation`: Added budget compliance check (Step 0.5) and report line
+
+### 4. Deferred (Future Work)
+- `fm-session-start.sh` budget initialization
+- `fm-spawn.sh` passing budget to worker
+- Harness adapter token reporting (Claude, Codex, OpenCode, etc.)
+- `fm-brief.sh` budget section
+
+## Implementation Approach
+
+**Created locally in opencode config first** (`~/.config/opencode/`), then copied to `command` project for MCP registration.
+
+1. Created skill directory: `.config/opencode/skills/context-budget/`
+2. Wrote `SKILL.md`: Define triggers, thresholds, integration points
+3. Wrote `bin/context-budget.sh`: Core tracking logic (tested working)
+4. Wrote `config/context-budget.yaml`: Thresholds per harness
+5. Updated `create-plan` skill: budget check + template section
+6. Updated `ticket-executor` skill: enforcement section + Phase 0 gate
+7. Updated `validate-implementation` skill: Step 0.5 + report
+8. Copied all artifacts to `command/.agents/skills/context-budget/` for MCP registration
+
+## Phases
+
+- [x] Phase 4.1: Create skill structure + SKILL.md (0.5 day)
+- [x] Phase 4.2: Write bin/context-budget.sh (1 day)
+- [x] Phase 4.3: Update create-plan + ticket-executor + validate-implementation (0.5 day)
+- [x] Phase 4.4: Copy to command project for MCP (0.5 day)
+- [ ] Phase 4.5: fm-session-start.sh budget init (deferred)
+- [ ] Phase 4.6: fm-spawn.sh pass budget to worker (deferred)
+- [ ] Phase 4.7: Harness adapters token reporting (deferred)
+- [ ] Phase 4.8: fm-brief.sh budget section (deferred)
+
+## Success Criteria
+
+### Automated Verification:
+- [x] `bin/context-budget.sh` correctly categorizes: 10=green, 35=yellow, 55=red, 80=red, 90=critical
+- [x] Skills updated with budget integration
+
+### Manual Verification:
+- [ ] Structural decisions made early (< 50% context)
+- [ ] No token-maxing while bottleneck is code review
+
+## Acceptance Criteria
+
+- [x] Context budget skill created and tested
+- [x] Integrated with create-plan, ticket-executor, validate-implementation
+- [x] Copied to command project for MCP registration
+- [ ] Context budget tracking active for all spawned tasks (deferred)
+- [ ] Measurable goal: 95% warning accuracy within 30 days
+- [ ] Rollback threshold: < 90% accuracy triggers review
+
+## Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Harness token APIs differ | High | Medium | Abstract in context-budget skill |
+| Token counting inaccurate | Medium | High | Calibrate per harness |
+| Overhead too high | Low | Medium | Sample, don't count every token |
+
+## References
+
+- Research: `docs/agentic-engineering-workflow.md` (Context Engineering Principles)
+- Dex Horthy: "One 43k-token session with sharp context > re-reading a 3,000-line diff later"
+- Victor Tali trick: Ask model "which choices are you not confident about?" before run

package/assets/reference/docs/plans/phase-5-pre-mortem-confidence.md

@@ -0,0 +1,100 @@
+# Phase 5: Create pre-mortem-confidence Skill
+
+**Project**: command (COM)
+**Priority**: Medium
+**Estimated Effort**: 2 days
+**Status**: ✅ COMPLETED (2026-09-10)
+**Measurable Goal**: `pre_mortem_coverage:100%:design_review:30d:95%`
+
+---
+
+## Problem Statement
+
+Victor Tali technique: "After a change, ask the model *'while working on this, which choices did you make that you're not confident of?'*." Dex's system does this **before the run instead of after** — surfacing uncertain choices during program design, not post-hoc. Current factory has no pre-mortem confidence check.
+
+## Current State
+
+- No pre-mortem step in `create-plan`, `ticket-executor`, or `fm-brief.sh`
+- No structured way to capture "low confidence choices" for review focus
+- Models make silent structural decisions (Layer 3) without flagging uncertainty
+
+## What Was Implemented
+
+### 1. Created `pre-mortem-confidence` Skill
+**Location**: `~/.config/opencode/skills/pre-mortem-confidence/` + copied to `command/.agents/skills/pre-mortem-confidence/`
+
+- `SKILL.md` — skill definition with triggers, output format, integration
+- `bin/pre-mortem-check.sh` — prompts agent for confidence assessment (tested: rejects confidence ≤6 without mitigation)
+
+### 2. Pre-Mortem Output Format (implemented)
+```markdown
+## Pre-Mortem Confidence Check
+
+While designing this, which choices are you NOT confident about?
+(List each with reasoning — these become review focus areas)
+
+| Choice | Confidence (1-10) | Reasoning | Mitigation |
+|--------|-------------------|-----------|------------|
+| ... | ... | ... | ... |
+```
+
+### 3. Integration with Existing Skills
+- `create-plan`: Added Step 3 mention + `## Pre-Mortem Confidence Check` section in template (after Layer 3)
+- `validate-plan`: Added section 1d "Pre-Mortem Confidence Validation" + output format
+
+### 4. Deferred (Future Work)
+- `fm-brief.sh`: Include pre-mortem section in brief scaffold
+- `multi-model-review` skill (Phase 6): Use low-confidence items as review focus
+
+## Implementation Approach
+
+**Created locally in opencode config first** (`~/.config/opencode/`), then copied to `command` project for MCP registration.
+
+1. Created skill directory: `.config/opencode/skills/pre-mortem-confidence/`
+2. Wrote `SKILL.md`: Define triggers, output format, integration
+3. Wrote `bin/pre-mortem-check.sh`: Prompts agent, produces table (tested working)
+4. Updated `create-plan` skill: pre-mortem step after Layer 3 + template section
+5. Updated `validate-plan` skill: section 1d validation
+6. Copied all artifacts to `command/.agents/skills/pre-mortem-confidence/` for MCP registration
+
+## Phases
+
+- [x] Phase 5.1: Create skill structure + SKILL.md (0.5 day)
+- [x] Phase 5.2: Write bin/pre-mortem-check.sh (0.5 day)
+- [x] Phase 5.3: Update create-plan + validate-plan skills (0.5 day)
+- [x] Phase 5.4: Copy to command project for MCP (0.5 day)
+- [ ] Phase 5.5: fm-brief.sh pre-mortem section (deferred)
+- [ ] Phase 5.6: multi-model-review uses low-confidence items (deferred)
+
+## Success Criteria
+
+### Automated Verification:
+- [x] `bin/pre-mortem-check.sh` rejects confidence ≤6 without mitigation
+- [x] Skills updated with pre-mortem integration
+
+### Manual Verification:
+- [ ] Reviewers focus on low-confidence areas
+- [ ] Fewer post-hoc "I didn't like that decision" moments
+
+## Acceptance Criteria
+
+- [x] Pre-mortem confidence skill created and tested
+- [x] Integrated with create-plan + validate-plan
+- [x] Copied to command project for MCP registration
+- [ ] 100% of plans have pre-mortem confidence check within 30 days
+- [ ] Measurable goal: 100% coverage in design reviews
+- [ ] Rollback threshold: < 95% coverage triggers process review
+
+## Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Agents overconfident | High | Medium | Calibrate with examples |
+| Adds process overhead | Medium | Low | Keep it lightweight (5 min) |
+| Gaming confidence scores | Low | Medium | Review focuses on low scores anyway |
+
+## References
+
+- Research: `docs/agentic-engineering-workflow.md` (Pre-Mortem Confidence section)
+- Victor Tali: "Ask the model which choices it was not confident about — before the run, not after"
+- Dex Horthy: "Surfacing uncertain choices during program design, not post-hoc"

package/assets/reference/docs/plans/phase-6-incident-to-agent.md

@@ -0,0 +1,109 @@
+# Phase 6: Incident-to-Agent Pipeline
+
+**Project**: command (COM)
+**Priority**: Medium
+**Estimated Effort**: 1 week
+**Status**: ✅ CORE IMPLEMENTED (2026-09-10) — Infrastructure deferred
+**Measurable Goal**: `incident_to_pr_latency:<30min:pagerduty:30d:<60min`
+
+---
+
+## Problem Statement
+
+Dex Horthy: "**I don't wake up to an alert, I wake up to a pull request.**" Current factory has no incident-to-agent pipeline. David Ondrej's working version: GLM 5.2 reviews every uptime incident, classifies it (provider outage vs missing migration + specific fix), runs on cron (Vercel/GH Actions + render.com inference).
+
+## Current State
+
+- `process-event-sources` skill exists but no incident source types
+- No incident classifier (GLM 5.2 style)
+- No auto-brief generation from incident classification
+- No cron infrastructure for incident polling
+
+## What Was Implemented
+
+### 1. Created `incident-to-agent` Skill
+**Location**: `~/.config/opencode/skills/incident-to-agent/` + copied to `command/.agents/skills/incident-to-agent/`
+
+- `SKILL.md` — skill definition with triggers and outputs
+- `bin/incident-classifier.sh` — GLM 5.2 style classification (tested: JSON title extraction fixed)
+- `bin/incident-to-brief.sh` — generates four-layer brief from classification (tested: fix brief + runbook brief both work)
+
+### 2. Incident Classification (implemented)
+```markdown
+## Incident Classification
+
+- Type: provider_outage | missing_migration | config_drift | code_regression | unknown
+- Actionable: true/false
+- Fix: specific fix description (if actionable)
+- Priority: P1/P2/P3
+```
+
+### 3. Auto-Brief Generation (implemented)
+- Actionable incidents → full four-layer brief targeting the fix
+- Non-actionable incidents → documentation/update runbook brief
+- Includes measurable goal (e.g., "restore API availability to 99.9%")
+
+### 4. Deferred (Requires Captain Credentials/Deployment)
+- **`process-event-sources` extension**: Add incident source types (PagerDuty, GH Actions, Vercel, custom health checks)
+- **Cron infrastructure**: Vercel/GitHub Actions for polling + render.com for inference
+- **`fm-spawn.sh` integration**: Accept incident-triggered briefs
+- **`fm-pr-check.sh`/`fm-teardown.sh`**: Track incident-linked PRs/tasks
+- **End-to-end test**: Simulate incident → classification → brief → spawn → PR
+
+## Implementation Approach
+
+**Created locally in opencode config first** (`~/.config/opencode/`), then copied to `command` project for MCP registration.
+
+1. Created skill directory: `.config/opencode/skills/incident-to-agent/`
+2. Wrote `SKILL.md`: Define triggers, outputs, classification schema
+3. Wrote `bin/incident-classifier.sh`: LLM-based classification (JSON parsing fixed, tested on PagerDuty-style payload)
+4. Wrote `bin/incident-to-brief.sh`: Four-layer brief generation (fix brief + `--runbook` brief tested)
+5. Copied all artifacts to `command/.agents/skills/incident-to-agent/` for MCP registration
+
+## Phases
+
+- [x] Phase 6.1: Create incident-to-agent skill + classifier + brief scripts (2 days)
+- [ ] Phase 6.2: Extend process-event-sources with incident sources (1 day) — **deferred, needs captain creds**
+- [ ] Phase 6.3: Cron infrastructure (Vercel + render.com) (2 days) — **deferred, needs captain creds**
+- [ ] Phase 6.4: Integrate with fm-spawn + fm-pr-check (1 day) — **deferred**
+- [ ] Phase 6.5: End-to-end test with simulated incident (1 day) — **deferred**
+
+## Success Criteria
+
+### Automated Verification:
+- [x] `bin/incident-classifier.sh` correctly extracts title from PagerDuty-style JSON
+- [x] `bin/incident-to-brief.sh` generates valid fix brief + runbook brief
+- [ ] Incident webhook triggers classification (deferred)
+- [ ] Classification produces actionable/non-actionable verdict (deferred)
+- [ ] Actionable incidents generate four-layer brief (deferred)
+- [ ] Brief spawns agent via fm-spawn (deferred)
+- [ ] PR created and tracked as incident-linked (deferred)
+
+### Manual Verification:
+- [ ] "Wake up to PR, not alert" workflow works (deferred)
+- [ ] Classification accuracy > 90% on test incidents (deferred)
+- [ ] Mean time to PR < 30 minutes (deferred)
+
+## Acceptance Criteria
+
+- [x] Core incident-to-agent skill created and tested locally
+- [x] Copied to command project for MCP registration
+- [ ] Incident-to-PR pipeline operational for `command` project (deferred)
+- [ ] Measurable goal: < 30min incident-to-PR latency within 30 days (deferred)
+- [ ] Rollback threshold: < 60min latency triggers review (deferred)
+- [ ] Classification accuracy > 90% (deferred)
+
+## Risk Assessment
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Classifier accuracy low | Medium | High | Human-in-loop for first 2 weeks |
+| Webhook security | High | High | Signature verification, secret rotation |
+| Cron reliability | Medium | High | Multi-region, dead-man switches |
+| False positive PRs | Medium | Medium | Require captain approval for P1 |
+
+## References
+
+- Research: `docs/agentic-engineering-workflow.md` (Incident Routing section)
+- David Ondrej: GLM 5.2 reviews every uptime incident, cron on Vercel/GH Actions + render.com
+- Dex Horthy: "Route the incident straight into the agent pipeline"