knoxis-helper 1.6.2 → 1.6.3

package/lib/knoxis-interactive-pair.js

@@ -289,6 +289,52 @@ function readIdentityFromEnv() {
   };
 }
 
+// === STATE-FILE UPDATE PROMPT ===
+// Forces Claude to actually write docs/state/*.md before the session closes.
+// The QIG dashboard reads these files; without this step they stay as scaffold
+// placeholders and the dashboard tiles show "0 done" regardless of what
+// happened in the session.
+function buildUpdateStatePrompt(task) {
+  return [
+    "Now update the project's state files to reflect what just happened.",
+    "This is non-negotiable — the QIG dashboard reads these files and skipping them",
+    "means the team loses visibility on what was accomplished.",
+    "",
+    "**Write the files. Do not describe what you would put in them — actually write them.**",
+    "",
+    "1. **`docs/state/STATUS.md`** — overwrite. Update `_Last updated:` line. Then:",
+    "   - `## Done`: one bullet per concrete thing completed in this session.",
+    "   - `## In flight`: anything started but not finished. Empty if none.",
+    "   - `## Next`: ONE concrete next step.",
+    "   - `## Notes`: caveats. Empty if none.",
+    "",
+    "2. **`docs/state/HANDOFF.md`** — overwrite the whole file:",
+    "   - `## Where I stopped`: 2-4 sentences (file, function, feature, state).",
+    "   - `## Why I stopped here`: brief reason.",
+    "   - `## First thing to do next session`: ONE concrete action with file:line if relevant.",
+    "   - `## Landmines / gotchas`: anything surprising. \"None.\" if none.",
+    "   - `## Environment state`: running services / env / branches. \"None.\" if none.",
+    "",
+    "3. **`docs/state/CHANGELOG.md`** — if code shipped or behavior changed, append a one-line bullet under `## [Unreleased]` in the right section (Added/Changed/Fixed/Removed). Skip if nothing shipped.",
+    "",
+    "4. **`docs/state/DECISIONS.md`** — if a non-trivial choice was made, append:",
+    "   ```",
+    "   ## <today's date>: <one-line title>",
+    "   **Context:** <2 sentences>",
+    "   **Decision:** <what you chose>",
+    "   **Alternatives considered:** <what else and why not>",
+    "   **Consequences:** <implications>",
+    "   ```",
+    "   Skip if no real decisions.",
+    "",
+    "5. **`docs/state/OPEN_QUESTIONS.md`** — if any genuine unresolved question emerged, append to `## Active`. Skip if none.",
+    "",
+    "Original task: " + task,
+    "",
+    "Write the files now. Then briefly summarize which files you wrote and which you skipped."
+  ].join('\n');
+}
+
 // === RECORDER + PORTAL FINALIZATION ===
 // Saves the session JSON locally and POSTs to the portal stub. Called from
 // every exit path so partial / fallback sessions still surface in the UI.
@@ -517,6 +563,15 @@ async function main() {
     appendLog('## Phase 3: Verification\n' + phase3b.stdout.substring(0, 5000) + '\n');
     recorder.completeStep(phase3bIdx, phase3b.stdout, phase3b.code !== 0 ? `exit ${phase3b.code}` : null);
 
+    // Same Phase 4 (update state) as the normal path so the dashboard sees
+    // updates even when session-resume failed mid-flow.
+    const updateStatePromptFb = buildUpdateStatePrompt(task);
+    const phase4bIdx = recorder.startStep('update-state', 'Claude Code', updateStatePromptFb);
+    recorder.setStepPrompt(phase4bIdx, updateStatePromptFb);
+    const phase4b = await runClaudeTurn(updateStatePromptFb, true);
+    appendLog('## Phase 4: Update state files\n' + phase4b.stdout.substring(0, 5000) + '\n');
+    recorder.completeStep(phase4bIdx, phase4b.stdout, phase4b.code !== 0 ? `exit ${phase4b.code}` : null);
+
     console.log('');
     console.log('╔══════════════════════════════════════════════════════════════╗');
     console.log('║        PAIR PROGRAMMING SESSION COMPLETE                    ║');
@@ -570,6 +625,26 @@ async function main() {
   recorder.completeStep(phase3Idx, phase3.stdout, phase3.code !== 0 ? `exit ${phase3.code}` : null);
 
 
+  // ═══════════════════════════════════════════
+  // PHASE 4: UPDATE STATE FILES (non-skippable)
+  // The QIG dashboard reads docs/state/*.md from the captured session.
+  // Without this step, every dashboard tile shows "0 done" no matter what
+  // actually happened during the session.
+  // ═══════════════════════════════════════════
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('  PHASE 4: Update state files');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+  appendLog('## Phase 4: Update state files\n');
+
+  const updateStatePrompt = buildUpdateStatePrompt(task);
+  const phase4Idx = recorder.startStep('update-state', 'Claude Code', updateStatePrompt);
+  recorder.setStepPrompt(phase4Idx, updateStatePrompt);
+  const phase4 = await runClaudeTurn(updateStatePrompt, true);
+  appendLog(phase4.stdout.substring(0, 5000) + '\n');
+  recorder.completeStep(phase4Idx, phase4.stdout, phase4.code !== 0 ? `exit ${phase4.code}` : null);
+
+
   // ═══════════════════════════════════════════
   // DONE
   // ═══════════════════════════════════════════

package/lib/knoxis-pair-program.js

@@ -307,6 +307,44 @@ Quick checklist:
 - Anything we should test?
 
 Give me the summary and any follow-up recommendations.`
+    },
+    {
+      key: 'update-state',
+      title: 'Update state files',
+      template: ({ taskDescription }) => `Now update the project's state files to reflect what just happened. This is non-negotiable — the QIG dashboard reads these files and skipping them means the team loses visibility on what was accomplished.
+
+**Write the files. Do not describe what you would put in them — actually write them.**
+
+1. **\`docs/state/STATUS.md\`** — overwrite it. Update the \`_Last updated:\` line to today's date, then:
+   - \`## Done\`: one bullet per concrete thing completed in this session (specific file changes, features wired, bugs fixed). Be terse but specific.
+   - \`## In flight\`: anything started but not finished. Empty list if none.
+   - \`## Next\`: ONE concrete next step for the next session, not a list of wishes.
+   - \`## Notes\`: caveats, gotchas, or context that doesn't fit elsewhere. Empty list if none.
+
+2. **\`docs/state/HANDOFF.md\`** — overwrite the whole file:
+   - \`## Where I stopped\`: 2-4 sentences. Concrete: file, function, feature, what state.
+   - \`## Why I stopped here\`: brief. Finished a chunk / blocked / end of task.
+   - \`## First thing to do next session\`: ONE concrete action, not "continue the feature." Reference an exact file:line if applicable.
+   - \`## Landmines / gotchas\`: anything that would surprise next-session-me. Write "None." if none.
+   - \`## Environment state\`: running services, env vars, open branches, anything not normal config. Write "None." if none.
+
+3. **\`docs/state/CHANGELOG.md\`** — if code shipped or a meaningful behavior changed, append a one-line bullet under \`## [Unreleased]\` in the right section (Added / Changed / Fixed / Removed). If nothing shipped (planning, exploration), don't write anything to CHANGELOG.
+
+4. **\`docs/state/DECISIONS.md\`** — if a non-trivial choice was made (which library, which pattern, which abstraction), append:
+   \`\`\`
+   ## <today's date>: <one-line decision title>
+   **Context:** <2 sentences>
+   **Decision:** <what you chose>
+   **Alternatives considered:** <what else and why not>
+   **Consequences:** <what this implies going forward>
+   \`\`\`
+   If no real decisions were made, skip this file.
+
+5. **\`docs/state/OPEN_QUESTIONS.md\`** — if any genuine unresolved question emerged (not a question you already answered), append to \`## Active\` as \`### N. <question>\`. Skip if no new questions.
+
+The original task was: ${taskDescription}
+
+Use that as the frame for what to write. Then briefly summarize which files you wrote and which you skipped (with reason).`
     }
   ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knoxis-helper",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "Local helper for Knoxis pair programming - connects your machine to Knoxis on qig.ai",
   "bin": {
     "knoxis-helper": "./bin/knoxis-helper.js"