knoxis-helper 1.5.2 → 1.6.2

package/lib/session-recorder.js

@@ -32,10 +32,45 @@ function extractFilesTouched(diff) {
   return Array.from(seen);
 }
 
-// Default git-call helpers — return null on any failure (callers want a string or null).
+// Snapshot the 6 well-known state files (docs/state/*.md) so the
+// session record carries the latest STATUS / HANDOFF / DECISIONS / etc.
+// up to the portal for display on qig.ai.
+const STATE_FILES_TO_CAPTURE = [
+  'docs/state/STATUS.md',
+  'docs/state/HANDOFF.md',
+  'docs/state/DECISIONS.md',
+  'docs/state/CHANGELOG.md',
+  'docs/state/OPEN_QUESTIONS.md',
+  'docs/state/RISKS.md'
+];
+const MAX_STATE_FILE_BYTES = 256 * 1024; // 256KB per file
+
+function readStateFiles(workspace) {
+  const out = {};
+  if (!workspace) return out;
+  for (const rel of STATE_FILES_TO_CAPTURE) {
+    const abs = path.join(workspace, rel);
+    try {
+      const stat = fs.statSync(abs);
+      if (!stat.isFile()) continue;
+      if (stat.size > MAX_STATE_FILE_BYTES) {
+        out[rel] = `[File omitted: ${stat.size} bytes exceeds ${MAX_STATE_FILE_BYTES}-byte cap]`;
+        continue;
+      }
+      out[rel] = fs.readFileSync(abs, 'utf8');
+    } catch (e) {
+      // Missing file is normal — skip silently.
+    }
+  }
+  return out;
+}
+
+// Default git-call helpers — return null on any failure (callers want a string
+// or null). stdio: 'pipe' prevents stderr from leaking to the parent process
+// (e.g. "fatal: Needed a single revision" when the repo has no commits).
 function defaultSafeExec(cmd, cwd) {
   try {
-    return execSync(cmd, { cwd, encoding: 'utf8', timeout: 30000 }).trim();
+    return execSync(cmd, { cwd, encoding: 'utf8', timeout: 30000, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
   } catch (e) {
     return null;
   }
@@ -44,7 +79,10 @@ function defaultSafeExec(cmd, cwd) {
 const execAsync = util.promisify(exec);
 async function defaultSafeExecAsync(cmd, cwd) {
   try {
-    const { stdout } = await execAsync(cmd, { cwd, encoding: 'utf8', timeout: 30000, maxBuffer: 10 * 1024 * 1024 });
+    // exec() inherits stderr by default; redirect to /dev/null at the shell
+    // level so failures (no commits, missing repo) don't pollute output.
+    const safeCmd = process.platform === 'win32' ? `${cmd} 2>nul` : `${cmd} 2>/dev/null`;
+    const { stdout } = await execAsync(safeCmd, { cwd, encoding: 'utf8', timeout: 30000, maxBuffer: 10 * 1024 * 1024 });
     return stdout.trim();
   } catch (e) {
     return null;
@@ -204,6 +242,10 @@ class SessionRecorder {
       completedSteps,
       closedCleanly,
       filesTouched: extractFilesTouched(totalDiff),
+      // Snapshot of docs/state/*.md at session-end so the QIG frontend can
+      // display the latest STATUS / HANDOFF / DECISIONS / etc. without
+      // needing live filesystem access on the dev's machine.
+      stateFiles: readStateFiles(this.workspace),
       decisionsLogged: [],
       waiversRequested: [],
       incidentsFlagged: [],

package/lib/state-scaffold.js

@@ -19,13 +19,17 @@ const STATE_LAYOUT = {
       overwrite: false
     },
     {
+      // Empty sections so the digest parser returns []s instead of inheriting
+      // scaffold copy. Claude populates Done / In flight / Next / Notes during
+      // session-end per the standards in the systemIntro.
       path: 'docs/state/STATUS.md',
-      content: () => `# Status\n\n_Last updated: ${today()}_\n\n## Done\n- (Project initialized; nothing yet.)\n\n## In flight\n- (None.)\n\n## Next\n- Run \`knoxis-pair-program --mode kickoff\` to populate the context pack, then begin Session 1.\n\n## Notes\n- Scaffolded by knoxis-helper.\n`,
+      content: () => `# Status\n\n_Last updated: ${today()}_\n\n## Done\n\n## In flight\n\n## Next\n\n## Notes\n`,
       overwrite: false
     },
     {
+      // Empty placeholder. HANDOFF gets overwritten in full at every session-end.
       path: 'docs/state/HANDOFF.md',
-      content: () => `# Handoff\n\n_Session ended: not yet — project freshly scaffolded._\n\n## Where I stopped\nProject scaffold created. No code written yet.\n\n## Why I stopped here\nWaiting on the kickoff interview to populate the context pack.\n\n## First thing to do next session\nRun \`knoxis-pair-program --mode kickoff\` and complete the interview.\n\n## Landmines / gotchas\nNone.\n\n## Environment state\nNone.\n`,
+      content: () => `# Handoff\n\n_No prior session — this file is overwritten at session-end._\n\n## Where I stopped\n\n## Why I stopped here\n\n## First thing to do next session\n\n## Landmines / gotchas\n\n## Environment state\n`,
       overwrite: false
     },
     {
@@ -34,8 +38,11 @@ const STATE_LAYOUT = {
       overwrite: false
     },
     {
+      // Empty Unreleased block — Claude appends real entries at session-end
+      // when code actually shipped. No fake "scaffolded" entry that would
+      // surface as a real changelog item on the dashboard.
       path: 'docs/state/CHANGELOG.md',
-      content: () => `# Changelog\n\nAll notable changes to this project will be documented in this file.\nFormat: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).\n\n## [Unreleased]\n\n### Added\n- Project scaffolded by knoxis-helper on ${today()}.\n`,
+      content: () => `# Changelog\n\nAll notable changes to this project will be documented in this file.\nFormat: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).\n\n## [Unreleased]\n\n### Added\n\n### Changed\n\n### Fixed\n\n### Removed\n`,
       overwrite: false
     },
     {

package/package.json

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