Turn-Commit-Kontask Lifecycle Design

Details

Raw Data

{
  "id": "45340793-3cee-4db6-90e8-b5615a22c515",
  "type": "general",
  "status": "completed",
  "title": "Turn-Commit-Kontask Lifecycle Design",
  "description": "Design for auto-commit after every turn and linking commits to kontasks",
  "context": {
    "output": "<div style=\"background:#1e1e1e;color:#e0e0e0;padding:20px;border-radius:8px;font-family:sans-serif;\">\n<h2 style=\"color:#fff;margin:0 0 16px 0;\">🔄 Turn-Commit-Kontask Lifecycle Design</h2>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#f97316;margin:0 0 12px 0;\">⚠️ The Problem</h3>\n<p style=\"color:#e0e0e0;line-height:1.6;\">Today's incident took <strong>2 hours</strong> to recover from because:</p>\n<ul style=\"color:#e0e0e0;margin:0;padding-left:20px;line-height:1.8;\">\n<li>Multiple turns of work were committed together</li>\n<li>When it broke, we couldn't tell which change caused it</li>\n<li>Had to roll back everything and lose all progress</li>\n<li>No linkage between kontasks and commits for traceability</li>\n</ul>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#98c379;margin:0 0 12px 0;\">✅ Solution 1: Auto-Commit After Every Turn</h3>\n<p style=\"color:#9ca3af;margin:0 0 12px 0;\">Add to CLAUDE.md as a MUST-follow rule:</p>\n<div style=\"background:#1e1e1e;padding:12px;border-radius:4px;font-family:monospace;font-size:0.9rem;\">\n<pre style=\"margin:0;color:#e0e0e0;\">## Turn Completion Protocol\n\n**CRITICAL: Commit at the end of EVERY turn that modifies files.**\n\n1. Before creating the output kontask, check `git status`\n2. If there are changed/added/deleted files:\n   - Stage all changes: `git add -A`\n   - Commit with descriptive message + kontask reference\n   - Include commit SHA in kontask context\n3. Create the output kontask with commit info embedded\n\n**Commit message format:**\n```\nTurn: {brief description}\n\nKontask: {kontask-id}\nSession: {session-id}\n\n🤖 Generated with Claude Code\nCo-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;\n```</pre>\n</div>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#61afef;margin:0 0 12px 0;\">✅ Solution 2: Link Commits to Kontasks</h3>\n<p style=\"color:#9ca3af;margin:0 0 12px 0;\">Add new fields to kontask schema:</p>\n<table style=\"width:100%;border-collapse:collapse;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"padding:8px;text-align:left;color:#daa520;\">Field</th>\n<th style=\"padding:8px;text-align:left;color:#daa520;\">Type</th>\n<th style=\"padding:8px;text-align:left;color:#daa520;\">Purpose</th>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px;\"><code style=\"background:#3d3d3d;padding:2px 6px;border-radius:3px;\">commitSha</code></td>\n<td style=\"padding:8px;\">string</td>\n<td style=\"padding:8px;\">Git commit SHA for this turn's changes</td>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px;\"><code style=\"background:#3d3d3d;padding:2px 6px;border-radius:3px;\">filesChanged</code></td>\n<td style=\"padding:8px;\">string[]</td>\n<td style=\"padding:8px;\">List of files modified in this turn</td>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px;\"><code style=\"background:#3d3d3d;padding:2px 6px;border-radius:3px;\">linesAdded</code></td>\n<td style=\"padding:8px;\">number</td>\n<td style=\"padding:8px;\">Lines added in this turn</td>\n</tr>\n<tr>\n<td style=\"padding:8px;\"><code style=\"background:#3d3d3d;padding:2px 6px;border-radius:3px;\">linesRemoved</code></td>\n<td style=\"padding:8px;\">number</td>\n<td style=\"padding:8px;\">Lines removed in this turn</td>\n</tr>\n</table>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#c678dd;margin:0 0 12px 0;\">🔗 Solution 3: Additional Lifecycle Gaps to Close</h3>\n<table style=\"width:100%;border-collapse:collapse;\">\n<tr style=\"background:#3d3d3d;\">\n<th style=\"padding:8px;text-align:left;color:#daa520;\">Gap</th>\n<th style=\"padding:8px;text-align:left;color:#daa520;\">Solution</th>\n<th style=\"padding:8px;text-align:left;color:#daa520;\">Priority</th>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px;\">No rollback button</td>\n<td style=\"padding:8px;\">Add \"↩ Rollback\" button to kontask detail that runs <code>git revert {sha}</code></td>\n<td style=\"padding:8px;color:#98c379;\">High</td>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px;\">Can't see what changed</td>\n<td style=\"padding:8px;\">Show <code>git diff</code> in kontask card when <code>commitSha</code> present</td>\n<td style=\"padding:8px;color:#98c379;\">High</td>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px;\">Multi-turn features risk</td>\n<td style=\"padding:8px;\">Use feature branches: <code>git checkout -b turn/{requestId}</code></td>\n<td style=\"padding:8px;color:#e5c07b;\">Medium</td>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px;\">Service restart breaks context</td>\n<td style=\"padding:8px;\">Persist session state to file before restart (already documented)</td>\n<td style=\"padding:8px;color:#e5c07b;\">Medium</td>\n</tr>\n<tr style=\"border-bottom:1px solid #444;\">\n<td style=\"padding:8px;\">No build verification</td>\n<td style=\"padding:8px;\">Run <code>deno check</code> before commit, abort if fails</td>\n<td style=\"padding:8px;color:#e5c07b;\">Medium</td>\n</tr>\n<tr>\n<td style=\"padding:8px;\">Tests not run</td>\n<td style=\"padding:8px;\">Run affected service tests before commit (optional flag)</td>\n<td style=\"padding:8px;color:#7f848e;\">Low</td>\n</tr>\n</table>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#e5c07b;margin:0 0 12px 0;\">📋 CLAUDE.md Update - New Section</h3>\n<div style=\"background:#1e1e1e;padding:12px;border-radius:4px;font-family:monospace;font-size:0.85rem;overflow-x:auto;\">\n<pre style=\"margin:0;color:#e0e0e0;\">## Turn Completion Protocol (MANDATORY)\n\n**Every turn that modifies files MUST commit before creating the output kontask.**\n\nThis rule exists because:\n- Rolling back multi-turn commits is painful (2+ hours of lost work)\n- Kontasks without commits have no recovery path\n- Git bisect becomes possible with atomic commits\n\n### End-of-Turn Checklist\n\n1. **Check for changes:** `git status --porcelain`\n2. **If files changed:**\n   - Stage: `git add -A`\n   - Verify: `deno check` on affected services (optional but recommended)\n   - Commit with format below\n3. **Include commit in kontask:** Add `commitSha` to context\n4. **Create kontask** with full output\n\n### Commit Message Format\n\n```\nTurn: {brief 50-char max description}\n\n{optional body with details}\n\nKontask: {kontask-title}\nFiles: {count} changed (+{added}/-{removed} lines)\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;\n```\n\n### Recovery Actions\n\n| Situation | Action |\n|-----------|--------|\n| Turn broke something | `git revert {sha}` (via kontask rollback button) |\n| Need to see what changed | View diff in kontask detail (when `commitSha` present) |\n| Multiple turns broke it | `git log --oneline` → find last good → `git reset --hard {sha}` |\n\n### Exceptions (No Commit Required)\n\n- Read-only turns (queries, searches, explanations)\n- Turns that only produce output (no file changes)\n- When user explicitly says \"don't commit\"</pre>\n</div>\n</div>\n\n<div style=\"background:#2d2d2d;padding:16px;border-radius:6px;margin-bottom:16px;\">\n<h3 style=\"color:#56b6c2;margin:0 0 12px 0;\">🔧 Implementation Steps</h3>\n<ol style=\"color:#e0e0e0;margin:0;padding-left:20px;line-height:1.8;\">\n<li><strong>Update CLAUDE.md</strong> with Turn Completion Protocol section</li>\n<li><strong>Update kontask-types.ts</strong> to add <code>commitSha</code>, <code>filesChanged</code> fields</li>\n<li><strong>Update kontask-detail.ts</strong> to show commit info + rollback button</li>\n<li><strong>Create helper script</strong> <code>/konnectvol/bin/turn-commit.sh</code> for consistent commits</li>\n<li><strong>Test the flow</strong> with a simple change</li>\n</ol>\n</div>\n\n<div style=\"background:#2d2d2d;padding:12px;border-radius:6px;\">\n<h4 style=\"margin:0 0 8px 0;color:#fff;\">What's Next?</h4>\n<p style=\"color:#9ca3af;margin:0;\">Choose how to proceed:</p>\n</div>\n</div>",
    "requestedAt": "2026-01-07T03:10:00Z",
    "requestId": "8a53c5d7-89c7-4a33-a521-b12a1949a621",
    "choices": [
      {
        "label": "Update CLAUDE.md now",
        "value": "Update CLAUDE.md with the Turn Completion Protocol section. Make this the first commit demonstrating the new pattern.",
        "primary": true
      },
      {
        "label": "Add kontask fields first",
        "value": "Update kontask-types.ts to add commitSha, filesChanged, linesAdded, linesRemoved fields to the Kontask interface"
      },
      {
        "label": "Full implementation",
        "value": "Implement all 5 steps: CLAUDE.md update, kontask schema, detail page UI, helper script, and test"
      },
      {
        "label": "Discuss approach",
        "value": "I have questions or want to discuss a different approach to the lifecycle improvements"
      }
    ],
    "turnTiming": {
      "totalMs": 80202,
      "ttfeMs": 49,
      "thinkingMs": 80153,
      "toolExecutionMs": 0,
      "toolCallCount": 0,
      "thinkingPct": 100,
      "toolsPct": 0,
      "ttfePct": 0
    }
  },
  "createdBy": "claude",
  "createdAt": "2026-01-07T03:13:22.479Z",
  "updatedAt": "2026-01-07T03:13:32.316Z",
  "requestId": "8a53c5d7-89c7-4a33-a521-b12a1949a621",
  "scope": "vibetools",
  "tags": [
    "lifecycle",
    "git",
    "kontasks",
    "recovery"
  ],
  "targetUser": "claude"
}