knoxis-helper 1.6.3 → 1.7.1

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.1.0',
+  documents: {
+    overview: 1,
+    kickoff: 8,
+    resume: 4,
+    sessionEnd: 4,
+    recovery: 3,
+    codingRuleset: 3,
+    marketplaceMcp: 3,
+    migration: 3,
+    portalContract: '0.3'
+  }
+};

package/lib/knoxis-pair-program.js

@@ -732,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
@@ -822,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}`);
@@ -859,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',
@@ -46,8 +46,29 @@ const STATE_LAYOUT = {
       overwrite: false
     },
     {
+      // Three sections: Pending Answers (kickoff/resume interview questions
+      // awaiting operator input — the question bus), Active (project-level
+      // unresolved questions), Resolved. Kickoff/resume detect "Pending
+      // Answers" with `_(fill in)_` placeholders to decide whether to wait
+      // or proceed.
       path: 'docs/state/OPEN_QUESTIONS.md',
-      content: () => `# Open Questions\n\n## Active\n\n## Resolved\n`,
+      content: () => `# Open Questions
+
+> **How this file works**
+>
+> - \`## Pending Answers\` — kickoff and resume use this section as a question bus. When the AI needs operator input, it appends numbered entries here with \`**Answer:** _(fill in)_\` placeholders.
+> - To answer: open this file, replace each \`_(fill in)_\` with your answer (plain text, any length), save, then re-run the same kickoff/resume command. The AI consumes the answers, generates the framework files, and moves the entries to \`## Resolved\`.
+> - \`## Active\` — project-level questions you want to track over time but that don't block this session.
+> - \`## Resolved\` — answered questions, kept for history.
+
+## Pending Answers
+
+_(Empty — kickoff or resume will populate this when it needs your input.)_
+
+## Active
+
+## Resolved
+`,
       overwrite: false
     },
     {
@@ -68,13 +89,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 +116,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 +189,7 @@ function assertStateLayout(workspace, mode) {
 
 module.exports = {
   scaffoldStateLayout,
+  scaffoldProductContext,
   assertStateLayout,
   STATE_LAYOUT
 };