diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 57d84a3..81ea359 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -125,7 +125,7 @@ {"id":"skills-a50w","title":"review-gate: Post-merge verification and rollback","description":"**Raised by:** gpt\n\n**Problem:**\nWhat if merge succeeds but breaks master? CI fails after merge? No revert procedure defined.\n\n**gpt:**\n\u003e \"Add a 'post-merge verification' stage: Merge → CI required → only then 'bd close'. Define revert procedure and who owns it (HQ vs new worker). Optionally enable 'merge queue' semantics.\"\n\n**Suggested fixes:**\n1. merged_pending_ci status before done\n2. Post-merge CI verification required\n3. Revert playbook section\n4. \"fix-forward\" task spawning on breakage\n5. Consider merge queue semantics","status":"open","priority":3,"issue_type":"task","created_at":"2026-01-12T09:24:12.120656389-08:00","created_by":"dan","updated_at":"2026-01-12T09:42:04.942124168-08:00","comments":[{"id":10,"issue_id":"skills-a50w","author":"dan","text":"[RECLASSIFY:2026-01-12T09:42:04-08:00] Moved from HQ to review-gate layer.\n\nPost-merge CI verification is quality enforcement. review-gate or CI should handle this, not HQ logic.","created_at":"2026-01-12T17:42:04Z"}]} {"id":"skills-a6mz","title":"Build property-based verification","description":"Verification checks that can be automated:\n- file_exists, dir_exists\n- function_defined (AST parsing)\n- tests_pass (run pytest/npm test/etc)\n- compiles (language-specific)\n- no_new_lint_errors\n- git_state (branch merged, worktree cleaned, etc)\n\nShould be composable and extensible.","status":"closed","priority":2,"issue_type":"task","created_at":"2026-01-11T16:19:45.54512229-08:00","created_by":"dan","updated_at":"2026-01-11T16:38:26.547049098-08:00","closed_at":"2026-01-11T16:38:26.547049098-08:00","close_reason":"Pausing - need to validate approach with simpler spike first","dependencies":[{"issue_id":"skills-a6mz","depends_on_id":"skills-y0p0","type":"blocks","created_at":"2026-01-11T16:20:20.641495149-08:00","created_by":"dan"}]} {"id":"skills-al5","title":"Consider repo-setup-verification skill","description":"The dotfiles repo has a repo-setup-prompt.md verification checklist that could become a skill.\n\n**Source**: ~/proj/dotfiles/docs/repo-setup-prompt.md\n\n**What it does**:\n- Verifies .envrc has use_api_keys and skills loading\n- Checks .skills manifest exists with appropriate skills\n- Optionally checks beads setup\n- Verifies API keys are loaded\n\n**As a skill it could**:\n- Be invoked to audit any repo's agent setup\n- Offer to fix missing pieces\n- Provide consistent onboarding for new repos\n\n**Questions**:\n- Is this better as a skill vs a slash command?\n- Should it auto-fix or just report?\n- Does it belong in skills repo or dotfiles?","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-06T12:38:32.561337354-08:00","updated_at":"2025-12-28T22:22:57.639520516-05:00","closed_at":"2025-12-28T22:22:57.639520516-05:00","close_reason":"Decided: keep as prompt doc in dotfiles, not a skill. Claude can read it when asked. No wrapper benefit, and it's dotfiles-specific setup (not general skill). ai-tools-doctor handles version checking separately."} -{"id":"skills-ankb","title":"Define Intent/Approach/Work workflow","description":"Document the three-phase workflow for structured beads.\n\n## Phases\n\n### Intent (what)\n- **Problem statement** - what's broken or missing?\n- **Context** - what code/docs were read? Include file hashes/versions if long-running\n- **What could go wrong?** - edge cases, failure modes (AI is happy-path oriented)\n- **Proposed solution** - high-level, not technical\n- **Constraints** - requirements, limits, must-haves\n\n### Approach (how)\n- **Technical approach** - how we'll solve it\n- **Interface contracts** - define types/signatures BEFORE logic\n- **Rejected alternatives** - what we considered and why not (prevents AI defaulting to generic)\n- **Verification plan** - how will we prove success? Prefer automated tests\n- **Side effects** - security, performance, auth implications\n- **Rollback plan** - how to undo if it fails in production\n- **Non-goals** - what we will NOT touch\n- **Files to change**\n- Dependencies and risks\n\n### Work (do)\n- **Pre-flight check** - \"I have all info needed. Missing: [X]\"\n- Concrete steps as checkboxes\n- Each item small and testable\n- First step often: write the failing test (red test)\n- Commit after 1-2 checkboxes (atomic commits)\n- Check off as completed\n\n### Review (verify)\n- Human reviews diff against Intent\n- Raw test/compiler output required (no \"trust me it works\")\n- Definition of Done checklist:\n - [ ] Meets Intent?\n - [ ] Follows Approach?\n - [ ] Verification passed?\n - [ ] Scaffolding removed? (debug prints, commented code, unused imports)\n - [ ] Linter passes?\n - [ ] Docs updated if needed?\n\n## Workflow Mechanics\n\n### Human Gates\nHuman-in-the-loop at every phase transition:\n```\nIntent → [approve] → Approach → [approve] → Work → [execute] → Review → [done]\n```\n\n**Anti-rubber-stamp**: Don't just click approve. Add a critique, constraint, or question to prove engagement. If you can't find anything, you didn't read it.\n\n### Context Anchoring\nDuring Work phase, re-inject Intent + Approach summary as system prompt. Don't rely on chat history alone - AI will drift by step 5.\n\n### Pivot Protocol\nWhen Work reveals Approach was wrong:\n1. **Stop** - don't hack around it\n2. **Diagnose** - AI summarizes WHY it failed\n3. **Learn** - failure reason becomes negative constraint in Intent (\"Do NOT use X because Y\")\n4. **Revert** - return to Approach phase\n5. **Revise** - update Approach with new constraint\n\nIf changing \u003e2 lines of Approach to make Work succeed → trigger Pivot.\n\n### Complexity Promotion\nWhen a Work item grows complex mid-implementation:\n- **Promote it** to its own bead with Intent/Approach/Work\n- Original checkbox becomes reference to new bead\n- **Depth limit**: Max 2 levels of nesting. Deeper = human intervention required.\n\n### When to Use Structure\n**Rule of Three** (+ security):\n- Affects \u003e3 files\n- Introduces \u003e1 new dependency\n- Changes existing interface/API\n- **Involves security, auth, or data persistence** (even if 1 file)\n- Requires reasoning, not just recall\n\nIf any true → use full structure.\n\n## Meta-Insight\n\n\u003e \"This framework is a Context Compression algorithm. Intent compresses the Past, Approach compresses the Future, Work is the Decompression.\"\n\nThe critical success factor is **strictness of Human Gates**. Rigorous Approach review = magic Work phase. Rubber-stamp = hallucination engine.\n\n## Deliverable\n- Document phase definitions ✓\n- Human gate requirements ✓\n- Anti-rubber-stamp guidance ✓\n- Context anchoring ✓\n- Pivot protocol with diagnose/learn ✓\n- Complexity promotion with depth limit ✓\n- Threshold heuristics ✓\n- Examples at different scales (todo)","status":"open","priority":2,"issue_type":"task","owner":"dan@delpad","created_at":"2026-01-18T08:13:57.556869846-08:00","created_by":"dan","updated_at":"2026-01-18T12:37:16.328365259-08:00","dependencies":[{"issue_id":"skills-ankb","depends_on_id":"skills-oh8m","type":"blocks","created_at":"2026-01-18T08:14:32.423457925-08:00","created_by":"dan"},{"issue_id":"skills-ankb","depends_on_id":"skills-ya44","type":"blocks","created_at":"2026-01-18T08:14:44.502821773-08:00","created_by":"dan"}]} +{"id":"skills-ankb","title":"Define Intent/Approach/Work workflow","description":"Document the three-phase workflow for structured beads.\n\n## Phases\n\n### Intent (what)\n- **Problem statement** - what's broken or missing?\n- **Context** - what code/docs were read? Include file hashes/versions if long-running\n- **What could go wrong?** - edge cases, failure modes (AI is happy-path oriented)\n- **Proposed solution** - high-level, not technical\n- **Constraints** - requirements, limits, must-haves\n\n### Approach (how)\n- **Technical approach** - how we'll solve it\n- **Interface contracts** - define types/signatures BEFORE logic\n- **Rejected alternatives** - what we considered and why not (prevents AI defaulting to generic)\n- **Verification plan** - how will we prove success? Prefer automated tests\n- **Side effects** - security, performance, auth implications\n- **Rollback plan** - how to undo if it fails in production\n- **Non-goals** - what we will NOT touch\n- **Files to change**\n- Dependencies and risks\n\n### Work (do)\n- **Pre-flight check** - \"I have all info needed. Missing: [X]\"\n- Concrete steps as checkboxes\n- Each item small and testable\n- First step often: write the failing test (red test)\n- Commit after 1-2 checkboxes (atomic commits)\n- Check off as completed\n\n### Review (verify)\n- Human reviews diff against Intent\n- Raw test/compiler output required (no \"trust me it works\")\n- Definition of Done checklist:\n - [ ] Meets Intent?\n - [ ] Follows Approach?\n - [ ] Verification passed?\n - [ ] Scaffolding removed? (debug prints, commented code, unused imports)\n - [ ] Linter passes?\n - [ ] Docs updated if needed?\n\n---\n\n## Workflow Mechanics\n\n### Human Gates\nHuman-in-the-loop at every phase transition:\n```\nIntent → [approve] → Approach → [approve] → Work → [execute] → Review → [done]\n```\n\n**Anti-rubber-stamp**: Don't just click approve. Add a critique, constraint, or question to prove engagement. If you can't find anything, you didn't read it.\n\n### Context Anchoring\nDuring Work phase, re-inject Intent + Approach summary as system prompt. Don't rely on chat history alone - AI will drift by step 5.\n\n### Pivot Protocol\nWhen Work reveals Approach was wrong:\n1. **Stop** - don't hack around it\n2. **Diagnose** - AI summarizes WHY it failed\n3. **Learn** - failure reason becomes negative constraint in Intent (\"Do NOT use X because Y\")\n4. **Revert** - return to Approach phase\n5. **Revise** - update Approach with new constraint\n\nIf changing \u003e2 lines of Approach to make Work succeed → trigger Pivot.\n\n### Complexity Promotion\nWhen a Work item grows complex mid-implementation:\n- **Promote it** to its own bead with Intent/Approach/Work\n- Original checkbox becomes reference to new bead\n- **Depth limit**: Max 2 levels of nesting. Deeper = human intervention required.\n\n### When to Use Structure\n**Rule of Three** (+ security):\n- Affects \u003e3 files\n- Introduces \u003e1 new dependency\n- Changes existing interface/API\n- **Involves security, auth, or data persistence** (even if 1 file)\n- Requires reasoning, not just recall\n\nIf any true → use full structure.\n\n---\n\n## Example: Human Gate in Action\n\n### Scene: AI proposes Intent\n\n**AI**: \n```\n## Intent\n**Problem**: Users report slow dashboard load times\n**Context**: Read src/pages/Dashboard.tsx, src/api/metrics.ts\n**Solution**: Add caching to metrics API\n**Constraints**: Must invalidate on data change\n```\n\n**Human (anti-rubber-stamp)**:\n\u003e \"What's the current load time? What's our target? Also, did you check if the bottleneck is actually the API vs rendering?\"\n\n**AI revises Intent**:\n```\n**Problem**: Dashboard loads in 4.2s, target is \u003c1s. Profiling shows 3.8s spent in /api/metrics\n**Context**: Read src/pages/Dashboard.tsx, src/api/metrics.ts, ran Chrome DevTools profile\n...\n```\n\n**Human**: \"Approved. Proceed to Approach.\"\n\n---\n\n## Example: Pivot Protocol in Action\n\n### Scene: Work reveals Approach was wrong\n\n**Approach said**: Use Redis INCR for rate limiting\n**Work step 3**: Implement sliding window\n\n**AI hits blocker**:\n\u003e \"Redis INCR doesn't support sliding window natively. The MULTI/EXEC approach adds 15ms latency, violating our 5ms constraint.\"\n\n**Pivot triggered**:\n\n1. **Stop**: AI halts, doesn't try to hack around it\n2. **Diagnose**: \"Redis INCR is fixed-window only. Sliding window requires Lua script or sorted sets, both add latency.\"\n3. **Learn**: Add to Intent constraints: \"Do NOT use Redis INCR - doesn't support sliding window within latency budget\"\n4. **Revert**: Return to Approach\n5. **Revise**: New Approach uses Redis sorted sets with pipeline, or considers in-memory with sync\n\n---\n\n## Example: Complexity Promotion\n\n### Scene: Work item grows complex\n\n**Original Work list**:\n```\n- [ ] Add user authentication\n- [ ] Add rate limiting \n- [ ] Add logging\n```\n\n**During \"Add user authentication\"**:\n\u003e This needs JWT setup, session management, password hashing, login/logout endpoints, middleware, and tests. Too big for a checkbox.\n\n**Promote**:\n```\n- [ ] Add user authentication → See bead skills-xyz\n- [ ] Add rate limiting\n- [ ] Add logging\n```\n\n**New bead skills-xyz** gets full Intent/Approach/Work treatment.\n\n---\n\n## Meta-Insight\n\n\u003e \"This framework is a Context Compression algorithm. Intent compresses the Past, Approach compresses the Future, Work is the Decompression.\"\n\nThe critical success factor is **strictness of Human Gates**. Rigorous Approach review = magic Work phase. Rubber-stamp = hallucination engine.\n\n---\n\n## Deliverable\n- Document phase definitions ✓\n- Human gate requirements ✓\n- Anti-rubber-stamp guidance ✓\n- Context anchoring ✓\n- Pivot protocol with diagnose/learn ✓\n- Complexity promotion with depth limit ✓\n- Threshold heuristics ✓\n- Examples ✓","status":"open","priority":2,"issue_type":"task","owner":"dan@delpad","created_at":"2026-01-18T08:13:57.556869846-08:00","created_by":"dan","updated_at":"2026-01-18T13:10:18.184355088-08:00","dependencies":[{"issue_id":"skills-ankb","depends_on_id":"skills-oh8m","type":"blocks","created_at":"2026-01-18T08:14:32.423457925-08:00","created_by":"dan"},{"issue_id":"skills-ankb","depends_on_id":"skills-ya44","type":"blocks","created_at":"2026-01-18T08:14:44.502821773-08:00","created_by":"dan"}]} {"id":"skills-audh","title":"Use parseEnum for heartbeat status instead of case statement","description":"[SMELL] LOW worker.nim:276-280 - Status string parsed with case statement with silent fallback. Use parseEnum or direct HeartbeatStatus input, error on invalid.","status":"closed","priority":4,"issue_type":"task","created_at":"2026-01-10T20:12:11.408603257-08:00","created_by":"dan","updated_at":"2026-01-11T15:46:39.025667838-08:00","closed_at":"2026-01-11T15:46:39.025667838-08:00","close_reason":"Closed"} {"id":"skills-bcu","title":"Design doc-review skill","description":"# doc-review skill\n\nFight documentation drift with a non-interactive review process that generates patchfiles for human review.\n\n## Problem\n- No consistent documentation system across repos\n- Stale content accumulates\n- Structural inconsistencies (docs not optimized for agents)\n\n## Envisioned Workflow\n\n```bash\n# Phase 1: Generate patches (non-interactive, use spare credits, test models)\ndoc-review scan ~/proj/foo --model claude-sonnet --output /tmp/foo-patches/\n\n# Phase 2: Review patches (interactive session)\ncd ~/proj/foo\nclaude # human reviews patches, applies selectively\n```\n\n## Design Decisions Made\n\n- **Trigger**: Manual invocation (not CI). Use case includes burning extra LLM credits, testing models repeatably.\n- **Source of truth**: Style guide embedded in prompt template. Blessed defaults, overridable per-repo.\n- **Output**: Patchfiles for human review in interactive Claude session.\n- **Chunking**: Based on absolute size, not file count. Logical chunks easy for Claude to review.\n- **Scope detection**: Graph-based discovery starting from README.md or AGENTS.md, not glob-all-markdown.\n\n## Open Design Work\n\n### Agent-Friendly Doc Conventions (needs brainstorming)\nWhat makes docs agent-readable?\n- Explicit context (no \"as mentioned above\")\n- Clear section headers for navigation\n- Self-contained sections\n- Consistent terminology\n- Front-loaded summaries\n- ???\n\n### Prompt Content\nFull design round needed on:\n- What conventions to enforce\n- How to express them in prompt\n- Examples of \"good\" vs \"bad\"\n\n### Graph-Based Discovery\nHow does traversal work?\n- Parse links from README/AGENTS.md?\n- Follow relative markdown links?\n- Depth limit?\n\n## Skill Structure (tentative)\n```\nskills/doc-review/\n├── prompt.md # Core review instructions + style guide\n├── scan.sh # Orchestrates: find docs → invoke claude → emit patches\n└── README.md\n```\n\n## Out of Scope (for now)\n- Cross-repo standardization (broader than skills repo)\n- CI integration\n- Auto-apply without human review","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-04T14:01:43.305653729-08:00","updated_at":"2025-12-04T16:44:03.468118288-08:00","closed_at":"2025-12-04T16:44:03.468118288-08:00","dependencies":[{"issue_id":"skills-bcu","depends_on_id":"skills-1ig","type":"blocks","created_at":"2025-12-04T14:02:17.144414636-08:00","created_by":"daemon","metadata":"{}"},{"issue_id":"skills-bcu","depends_on_id":"skills-53k","type":"blocks","created_at":"2025-12-04T14:02:17.164968463-08:00","created_by":"daemon","metadata":"{}"}]} {"id":"skills-be3","title":"Define trace security and redaction policy","description":"Wisps will leak secrets without explicit policy.\n\nRequired:\n- Default-deny for env vars (allowlist: PROJECT, USER, etc.)\n- Redaction rules for sensitive fields\n- No file contents by default\n- Classification field: internal|secret|public\n\nImplementation:\n- redact: [\"env.AWS_SECRET_ACCESS_KEY\", \"inputs.token\"]\n- Sanitization before writing to disk\n- Block elevation if classification=secret\n\nFrom consensus: both models flagged as medium-high severity.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-23T19:49:31.041661947-05:00","updated_at":"2025-12-23T20:55:04.446363188-05:00","closed_at":"2025-12-23T20:55:04.446363188-05:00","close_reason":"ADRs revised with orch consensus feedback"}