knoxis-helper 1.6.2 → 1.6.4

package/bin/knoxis-helper.js

@@ -59,6 +59,7 @@ function parseArgs() {
     if (arg === '--update') { args.update = true; continue; }
     if (arg === '--uninstall') { args.uninstall = true; continue; }
     if (arg === '--restart') { args.restart = true; continue; }
+    if (arg === '--version' || arg === '-v') { args.version = true; continue; }
     if (arg.startsWith('--')) {
       const key = arg.slice(2);
       const next = process.argv[i + 1];
@@ -100,6 +101,7 @@ function installAgentLocally(force) {
   const sourceStateScaffold = path.join(libDir, 'state-scaffold.js');
   const sourcePortalSync = path.join(libDir, 'portal-sync.js');
   const sourceSessionRecorder = path.join(libDir, 'session-recorder.js');
+  const sourceFrameworkVersion = path.join(libDir, 'framework-version.js');
   const sourceTemplatesDir = path.join(libDir, 'templates');
   const sourcePackage = path.join(__dirname, '..', 'package.json');
 
@@ -156,6 +158,11 @@ function installAgentLocally(force) {
     console.log('  Installed: session-recorder.js');
   }
 
+  if (fs.existsSync(sourceFrameworkVersion)) {
+    fs.copyFileSync(sourceFrameworkVersion, path.join(AGENT_DIR, 'framework-version.js'));
+    console.log('  Installed: framework-version.js');
+  }
+
   if (fs.existsSync(sourceTemplatesDir)) {
     copyDirRecursive(sourceTemplatesDir, path.join(AGENT_DIR, 'templates'));
     console.log('  Installed: templates/');
@@ -375,6 +382,26 @@ function restart() {
 async function main() {
   const args = parseArgs();
 
+  // Version — print npm release version and embedded framework bundle version.
+  if (args.version) {
+    let pkgVersion = 'unknown';
+    try {
+      pkgVersion = require(path.join(__dirname, '..', 'package.json')).version;
+    } catch (e) {}
+    let fw;
+    try {
+      fw = require(path.join(__dirname, '..', 'lib', 'framework-version.js'));
+    } catch (e) {
+      fw = null;
+    }
+    console.log(`knoxis-helper@${pkgVersion}`);
+    if (fw) {
+      console.log(`framework bundle: v${fw.bundle}`);
+      console.log(`  kickoff v${fw.documents.kickoff}, resume v${fw.documents.resume}, session-end v${fw.documents.sessionEnd}, recovery v${fw.documents.recovery}, ruleset v${fw.documents.codingRuleset}, portal-contract v${fw.documents.portalContract}`);
+    }
+    process.exit(0);
+  }
+
   // Uninstall
   if (args.uninstall) {
     uninstall();

package/lib/framework-version.js

@@ -0,0 +1,27 @@
+'use strict';
+
+// Framework bundle version embedded in this knoxis-helper release.
+// Source: docs/Pair Programmer Docs/pair-programmer/VERSION (+ CHANGELOG.md)
+// and the per-document version headers in pair-programmer/framework/*.md.
+//
+// Why this is separate from package.json: knoxis-helper version (npm release)
+// bumps for helper-side fixes — sync bugs, scaffold tweaks, CLI changes —
+// that don't change the methodology. The framework bundle version bumps when
+// the canonical docs change. One npm package, two version labels: the package
+// version answers "what release am I running"; the framework version answers
+// "what methodology version is baked into it." Both ride together in every
+// session record so the portal can render them.
+module.exports = {
+  bundle: '1.0.0',
+  documents: {
+    overview: 1,
+    kickoff: 7,
+    resume: 3,
+    sessionEnd: 3,
+    recovery: 3,
+    codingRuleset: 3,
+    marketplaceMcp: 3,
+    migration: 3,
+    portalContract: '0.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).`
     }
   ];
 
@@ -694,11 +732,29 @@ async function run() {
   const userTask = (task || '').trim();
   task = userTask || `[${mode || 'default'} session]`;
 
+  // Resolve operator + product/project identity early so the scaffolder can
+  // also drop a product.local.json skeleton in the product parent directory
+  // when the framework's Phase -1 product context isn't already written.
+  const knoxisConfig = (() => {
+    const p = path.join(os.homedir(), '.knoxis', 'config.json');
+    try { return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : {}; } catch (e) { return {}; }
+  })();
+  const engineerId = args['engineer-id'] || knoxisConfig.userId || null;
+  const productSlug = args['product-slug'] || knoxisConfig.productSlug || null;
+  const projectSlug = args['project-slug'] || knoxisConfig.projectSlug || path.basename(workspace);
+  const userId = args['user-id'] || knoxisConfig.userId || null;
+  const workspaceIdArg = args['workspace-id'] || null;
+  const taskIdsArg = (() => {
+    const raw = args['task-id'];
+    if (!raw) return [];
+    return Array.isArray(raw) ? raw : [raw];
+  })();
+
   // Always ensure the standardized layout exists. The pair programmer takes
   // over development across the company, so every task — regardless of mode —
   // must land in a workspace that has CODING_RULES.md and the state files.
   // Scaffolding is idempotent; existing files are preserved.
-  const scaffoldResult = scaffoldStateLayout(workspace);
+  const scaffoldResult = scaffoldStateLayout(workspace, { productSlug, projectSlug, engineerId });
 
   // Mode-specific preconditions: resume / session-end need real state. If the
   // workspace was just scaffolded for them, the placeholder STATUS/HANDOFF
@@ -784,25 +840,6 @@ async function run() {
     process.exit(1);
   }
 
-  // Resolve operator identity for the session record. CLI flags win, then
-  // ~/.knoxis/config.json (where the local-agent stores userId), then null.
-  const knoxisConfig = (() => {
-    const p = path.join(os.homedir(), '.knoxis', 'config.json');
-    try { return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : {}; } catch (e) { return {}; }
-  })();
-  const engineerId = args['engineer-id'] || knoxisConfig.userId || null;
-  const productSlug = args['product-slug'] || knoxisConfig.productSlug || null;
-  const projectSlug = args['project-slug'] || knoxisConfig.projectSlug || path.basename(workspace);
-  // QIG portal linkage — passed by the local-agent when the caller (e.g.
-  // PairProgramSheet) supplies them.
-  const userId = args['user-id'] || knoxisConfig.userId || null;
-  const workspaceIdArg = args['workspace-id'] || null;
-  const taskIdsArg = (() => {
-    const raw = args['task-id'];
-    if (!raw) return [];
-    return Array.isArray(raw) ? raw : [raw];
-  })();
-
   console.log('==============================================');
   console.log('Knoxis Pair Programming Session');
   console.log(`Workspace: ${workspace}`);
@@ -821,6 +858,9 @@ async function run() {
     if (scaffoldResult.skipped.length) {
       console.log(`Existing files preserved: ${scaffoldResult.skipped.join(', ')}`);
     }
+    if (scaffoldResult.productContext && scaffoldResult.productContext.created) {
+      console.log(`  + file ${scaffoldResult.productContext.path} (Phase -1 skeleton — fill in via kickoff)`);
+    }
     console.log('');
   }
 

package/lib/session-recorder.js

@@ -7,6 +7,8 @@ const { execSync } = require('child_process');
 const util = require('util');
 const { exec } = require('child_process');
 
+const FRAMEWORK_VERSION = require('./framework-version');
+
 const SESSIONS_DIR = path.join(os.homedir(), '.knoxis', 'sessions');
 
 function ensureSessionDir() {
@@ -65,6 +67,31 @@ function readStateFiles(workspace) {
   return out;
 }
 
+// Snapshot product.local.json from the project's parent directory (per
+// kickoff v7 Phase -1) so the session record carries product context up to
+// the portal. Multiple projects under one product share this file; the
+// snapshot also lets the frontend visualize how directories and repos under
+// a product are connected.
+function readProductContext(workspace) {
+  if (!workspace) return null;
+  const productFile = path.join(path.dirname(workspace), 'product.local.json');
+  try {
+    const stat = fs.statSync(productFile);
+    if (!stat.isFile()) return null;
+    if (stat.size > MAX_STATE_FILE_BYTES) {
+      return { path: productFile, data: null, error: `File ${stat.size} bytes exceeds ${MAX_STATE_FILE_BYTES}-byte cap` };
+    }
+    const raw = fs.readFileSync(productFile, 'utf8');
+    try {
+      return { path: productFile, data: JSON.parse(raw) };
+    } catch (e) {
+      return { path: productFile, data: null, error: `JSON parse error: ${e.message}` };
+    }
+  } catch (e) {
+    return null;
+  }
+}
+
 // 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).
@@ -223,6 +250,7 @@ class SessionRecorder {
     return {
       sessionId: this.sessionId,
       version: '1.1.0',
+      frameworkVersion: FRAMEWORK_VERSION,
       mode: this.mode,
       archetype: this.archetype,
       productSlug: this.productSlug,
@@ -246,6 +274,9 @@ class SessionRecorder {
       // display the latest STATUS / HANDOFF / DECISIONS / etc. without
       // needing live filesystem access on the dev's machine.
       stateFiles: readStateFiles(this.workspace),
+      // Snapshot of product.local.json from the parent directory so the
+      // frontend can render product context alongside the session record.
+      productContext: readProductContext(this.workspace),
       decisionsLogged: [],
       waiversRequested: [],
       incidentsFlagged: [],
@@ -266,5 +297,7 @@ module.exports = {
   SESSIONS_DIR,
   ensureSessionDir,
   slugify,
-  extractFilesTouched
+  extractFilesTouched,
+  readStateFiles,
+  readProductContext
 };

package/lib/state-scaffold.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const { codingRuleset } = require('./templates');
 
-// Standardized layout per the kit (docs/Pair Programmer Docs/01-kickoff.md Phase 0.3).
+// Standardized layout per the framework (docs/Pair Programmer Docs/pair-programmer/framework/01-kickoff.md Phase 0.3, v7).
 const STATE_LAYOUT = {
   dirs: [
     'docs/product',
@@ -68,13 +68,13 @@ function ensureDir(p) {
   }
 }
 
-function scaffoldStateLayout(workspace) {
+function scaffoldStateLayout(workspace, opts = {}) {
   if (!workspace) {
     throw new Error('scaffoldStateLayout: workspace path required');
   }
   ensureDir(workspace);
 
-  const created = { dirs: [], files: [], skipped: [] };
+  const created = { dirs: [], files: [], skipped: [], productContext: null };
 
   for (const rel of STATE_LAYOUT.dirs) {
     const abs = path.join(workspace, rel);
@@ -95,9 +95,50 @@ function scaffoldStateLayout(workspace) {
     created.files.push(spec.path);
   }
 
+  // Phase -1 product context (kickoff v7). The framework places product.local.json
+  // in the product parent directory — the project's parent. Scaffold a TBD skeleton
+  // only when a product slug is known and no file already exists; never overwrite.
+  // Kickoff Phase -1 fills in the real values interactively.
+  created.productContext = scaffoldProductContext(workspace, opts);
+
   return created;
 }
 
+function scaffoldProductContext(workspace, { productSlug, projectSlug, engineerId } = {}) {
+  if (!productSlug) return null;
+  const productDir = path.dirname(workspace);
+  const productFile = path.join(productDir, 'product.local.json');
+  if (fs.existsSync(productFile)) {
+    return { path: productFile, created: false, reason: 'exists' };
+  }
+  let canWrite = false;
+  try {
+    fs.accessSync(productDir, fs.constants.W_OK);
+    canWrite = true;
+  } catch (e) {
+    canWrite = false;
+  }
+  if (!canWrite) {
+    return { path: productFile, created: false, reason: 'parent-unwritable' };
+  }
+  const skeleton = {
+    product_id: productSlug,
+    name: '<TBD>',
+    slug: productSlug,
+    internal_classification: '<TBD: low|medium|high>',
+    compliance_engineered_for: [],
+    approved_agents: [],
+    denied_tools: [],
+    parent_directory_convention: productDir,
+    product_owner_id: null,
+    operator: { id: engineerId || null, name: null },
+    established_at: new Date().toISOString(),
+    _note: 'Skeleton written by knoxis-helper. Run kickoff Phase -1 to fill in real values.'
+  };
+  fs.writeFileSync(productFile, JSON.stringify(skeleton, null, 2) + '\n', 'utf8');
+  return { path: productFile, created: true, projectSlug: projectSlug || null };
+}
+
 // Minimum files required for a given mode. Resume and session-end need state files
 // to exist; kickoff has no preconditions; recovery is mode-agnostic.
 const REQUIRED_FILES_BY_MODE = {
@@ -127,6 +168,7 @@ function assertStateLayout(workspace, mode) {
 
 module.exports = {
   scaffoldStateLayout,
+  scaffoldProductContext,
   assertStateLayout,
   STATE_LAYOUT
 };