knoxis-helper 1.4.8 → 1.5.0

package/bin/knoxis-helper.js

@@ -81,10 +81,25 @@ function ask(rl, question) {
  * Copy agent files to ~/.knoxis/agent/ so they persist across npx cache clears,
  * VPN changes, and reboots. Returns the stable path.
  */
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(src)) return;
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDirRecursive(s, d);
+    else if (entry.isFile()) fs.copyFileSync(s, d);
+  }
+}
+
 function installAgentLocally(force) {
-  const sourceAgent = path.join(__dirname, '..', 'lib', 'knoxis-local-agent.js');
-  const sourcePairProgram = path.join(__dirname, '..', 'lib', 'knoxis-pair-program.js');
-  const sourceInteractivePair = path.join(__dirname, '..', 'lib', 'knoxis-interactive-pair.js');
+  const libDir = path.join(__dirname, '..', 'lib');
+  const sourceAgent = path.join(libDir, 'knoxis-local-agent.js');
+  const sourcePairProgram = path.join(libDir, 'knoxis-pair-program.js');
+  const sourceInteractivePair = path.join(libDir, 'knoxis-interactive-pair.js');
+  const sourceStateScaffold = path.join(libDir, 'state-scaffold.js');
+  const sourcePortalSync = path.join(libDir, 'portal-sync.js');
+  const sourceTemplatesDir = path.join(libDir, 'templates');
   const sourcePackage = path.join(__dirname, '..', 'package.json');
 
   if (!fs.existsSync(sourceAgent)) {
@@ -125,6 +140,21 @@ function installAgentLocally(force) {
     console.log('  Installed: knoxis-interactive-pair.js');
   }
 
+  if (fs.existsSync(sourceStateScaffold)) {
+    fs.copyFileSync(sourceStateScaffold, path.join(AGENT_DIR, 'state-scaffold.js'));
+    console.log('  Installed: state-scaffold.js');
+  }
+
+  if (fs.existsSync(sourcePortalSync)) {
+    fs.copyFileSync(sourcePortalSync, path.join(AGENT_DIR, 'portal-sync.js'));
+    console.log('  Installed: portal-sync.js');
+  }
+
+  if (fs.existsSync(sourceTemplatesDir)) {
+    copyDirRecursive(sourceTemplatesDir, path.join(AGENT_DIR, 'templates'));
+    console.log('  Installed: templates/');
+  }
+
   if (fs.existsSync(sourcePackage)) {
     fs.copyFileSync(sourcePackage, path.join(AGENT_DIR, 'package.json'));
   }

package/lib/knoxis-local-agent.js

@@ -580,6 +580,47 @@ function resolveInteractiveScript() {
   return null;
 }
 
+// Resolve the kit-aware pair-program runner (used when caller specifies --mode)
+function resolvePairProgramScript() {
+  const candidates = [
+    path.join(__dirname, 'knoxis-pair-program.js'),
+    path.join(__dirname, '..', 'knoxis-pair-program.js'),
+    path.join(os.homedir(), '.knoxis', 'agent', 'knoxis-pair-program.js'),
+    path.join(__dirname, '..', '..', 'knoxis-pair-program.js'),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+const KIT_MODES = new Set(['kickoff', 'resume', 'session-end', 'recovery']);
+
+function buildPairProgramCommand({ scriptPath, workspace, mode, archetype, pattern, productSlug, projectSlug, taskPrompt, userId, workspaceId, taskIds }) {
+  const q = v => `"${escapeForDoubleQuotedShellArg(v)}"`;
+  // Mode/archetype/pattern are constrained to known short tokens — no need to quote.
+  // Slugs and paths can contain spaces or special chars — always quote.
+  const parts = [`node ${q(scriptPath)}`, `--workspace ${q(workspace)}`];
+  if (mode) parts.push(`--mode ${mode}`);
+  if (archetype) parts.push(`--archetype ${archetype}`);
+  if (pattern) parts.push(`--pattern ${pattern}`);
+  if (productSlug) parts.push(`--product-slug ${q(productSlug)}`);
+  if (projectSlug) parts.push(`--project-slug ${q(projectSlug)}`);
+  if (userId) parts.push(`--user-id ${q(userId)}`);
+  if (workspaceId) parts.push(`--workspace-id ${q(workspaceId)}`);
+  if (Array.isArray(taskIds)) {
+    for (const t of taskIds) {
+      if (t) parts.push(`--task-id ${q(t)}`);
+    }
+  }
+  if (taskPrompt && taskPrompt.length) {
+    // Use base64 to avoid shell-quoting hazards (newlines, quotes, backticks).
+    const b64 = Buffer.from(taskPrompt, 'utf8').toString('base64');
+    parts.push(`--prompt-base64 ${b64}`);
+  }
+  return parts.join(' ');
+}
+
 // Request handler
 async function handleRequest(req, res) {
   const parsedUrl = url.parse(req.url, true);
@@ -867,8 +908,22 @@ async function handleRequest(req, res) {
       const body = await parseBody(req);
       const { workspace, task, file, provider, headless, sessionId, claudeMdContent } = body;
       const interactive = body.interactive === true || body.interactive === 'true';
-
-      if (!task) {
+      const kitMode = typeof body.mode === 'string' && KIT_MODES.has(body.mode) ? body.mode : null;
+      const archetype = typeof body.archetype === 'string' ? body.archetype : null;
+      const pattern = typeof body.pattern === 'string' ? body.pattern : null;
+      const productSlug = typeof body.productSlug === 'string' ? body.productSlug : null;
+      const projectSlug = typeof body.projectSlug === 'string' ? body.projectSlug : null;
+      // QIG portal linkage — let session records get tied back to the user / workspace / tasks.
+      const portalUserId = typeof body.userId === 'string' ? body.userId : null;
+      const portalWorkspaceId = typeof body.workspaceId === 'string' ? body.workspaceId : null;
+      const portalTaskIds = Array.isArray(body.taskIds)
+        ? body.taskIds.filter(t => typeof t === 'string' && t)
+        : (typeof body.taskId === 'string' ? [body.taskId] : []);
+
+      // Kickoff and session-end modes don't strictly need a task — the kit prompt
+      // drives the interaction. For all other paths a task is still required.
+      const taskOptionalForMode = kitMode === 'kickoff' || kitMode === 'session-end';
+      if (!task && !taskOptionalForMode) {
         return sendJSON(res, 400, { success: false, error: 'Task description required' }, requestOrigin);
       }
 
@@ -895,16 +950,44 @@ async function handleRequest(req, res) {
         }
       }
 
-      // Write the actual task to a temp file
+      // Write the actual task to a temp file (used by single-shot and interactive paths)
       const promptFile = path.join(os.tmpdir(), `knoxis-task-${sessionId || Date.now()}.txt`);
-      const promptText = file ? `Working on file: ${file}\n\nTask: ${task}` : task;
-      fs.writeFileSync(promptFile, promptText, 'utf8');
+      const promptText = task ? (file ? `Working on file: ${file}\n\nTask: ${task}` : task) : '';
+      if (promptText) fs.writeFileSync(promptFile, promptText, 'utf8');
 
-      // Determine the command to run
+      // Determine the command to run.
       let command;
       let mode = 'single-shot';
 
-      if (interactive) {
+      // Route through knoxis-pair-program.js whenever it's installed — gives
+      // every task auto-scaffold, the standards systemIntro, auto-context, and
+      // portal-sync. Kit mode adds --mode; default mode runs the standard
+      // 4-step pipeline. Interactive (Groq) mode and the legacy claude-pipe
+      // fallback remain available when the runner isn't present.
+      const ppScript = resolvePairProgramScript();
+      if (kitMode && !ppScript) {
+        return sendJSON(res, 500, { success: false, error: 'knoxis-pair-program.js not found — reinstall knoxis-helper.' }, requestOrigin);
+      }
+
+      if (kitMode || (ppScript && !interactive && promptText)) {
+        command = buildPairProgramCommand({
+          scriptPath: ppScript,
+          workspace: workspaceDir,
+          mode: kitMode || null,
+          archetype,
+          pattern,
+          productSlug,
+          projectSlug,
+          taskPrompt: promptText,
+          userId: portalUserId,
+          workspaceId: portalWorkspaceId,
+          taskIds: portalTaskIds
+        });
+        mode = kitMode
+          ? `kit:${kitMode}${archetype ? `/${archetype}` : ''}${pattern ? `/${pattern}` : ''}`
+          : 'pair-program:default';
+        console.log(`🧰 ${kitMode ? 'Kit' : 'Pair-program (default pipeline)'}: ${mode}`);
+      } else if (interactive) {
         const scriptPath = resolveInteractiveScript();
         if (scriptPath) {
           // Interactive mode: multi-turn with Groq pair programmer
@@ -917,17 +1000,19 @@ async function handleRequest(req, res) {
           command = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';
         }
       } else {
-        // Standard single-shot mode: pipe task to Claude
+        // Legacy fallback when neither pair-program nor interactive scripts are installed.
         command = buildCatCommand(promptFile) + ' | claude --dangerously-skip-permissions';
       }
 
       if (headless) {
-        if (interactive && mode === 'interactive') {
-          // Headless interactive: run the script directly as a process
+        // Anything routed through pair-program.js or knoxis-interactive-pair.js
+        // is a script invocation — run the assembled command verbatim.
+        const isScriptInvocation = mode === 'interactive' || mode === 'pair-program:default' || (kitMode != null);
+        if (isScriptInvocation) {
           const result = await runHeadlessProcess({
             workspace: workspaceDir,
             command,
-            sessionLabel: sessionId || 'interactive-pair'
+            sessionLabel: sessionId || (kitMode ? `kit-${kitMode}` : (mode === 'interactive' ? 'interactive-pair' : 'pair-program'))
           });
           return sendJSON(res, result.success ? 200 : 500, { ...result, mode }, requestOrigin);
         }
@@ -956,10 +1041,15 @@ async function handleRequest(req, res) {
 
       return sendJSON(res, 200, {
         success: true,
-        message: interactive ? 'Interactive pair programming session started' : 'Pair programming session started',
+        message: kitMode ? `Pair programming session started (kit mode: ${kitMode})`
+          : interactive ? 'Interactive pair programming session started'
+          : 'Pair programming session started',
         mode,
+        kitMode: kitMode || null,
+        archetype: archetype || null,
+        pattern: pattern || null,
         workspace: workspaceDir,
-        task,
+        task: task || null,
         file: file || null
       }, requestOrigin);
     } catch (error) {
@@ -1338,8 +1428,37 @@ function connectRelayWebSocket() {
         }
 
         const interactive = msg.interactive === true;
-
-        if (taskPrompt) {
+        const kitMode = typeof msg.mode === 'string' && KIT_MODES.has(msg.mode) ? msg.mode : null;
+        const archetype = typeof msg.archetype === 'string' ? msg.archetype : null;
+        const pattern = typeof msg.pattern === 'string' ? msg.pattern : null;
+        const productSlug = typeof msg.productSlug === 'string' ? msg.productSlug : null;
+        const projectSlug = typeof msg.projectSlug === 'string' ? msg.projectSlug : null;
+        const portalUserId = typeof msg.userId === 'string' ? msg.userId : null;
+        const portalWorkspaceId = typeof msg.workspaceId === 'string' ? msg.workspaceId : null;
+        const portalTaskIds = Array.isArray(msg.taskIds)
+          ? msg.taskIds.filter(t => typeof t === 'string' && t)
+          : (typeof msg.taskId === 'string' ? [msg.taskId] : []);
+        const ppScript = resolvePairProgramScript();
+        const routeViaPairProgram = (kitMode || (ppScript && !interactive && taskPrompt));
+
+        if (routeViaPairProgram && ppScript) {
+          command = buildPairProgramCommand({
+            scriptPath: ppScript,
+            workspace: wsDir,
+            mode: kitMode || null,
+            archetype,
+            pattern,
+            productSlug,
+            projectSlug,
+            taskPrompt: taskPrompt || '',
+            userId: portalUserId,
+            workspaceId: portalWorkspaceId,
+            taskIds: portalTaskIds
+          });
+          console.log(`   🧰 ${kitMode ? `Kit mode: ${kitMode}` : 'Pair-program (default pipeline)'}${archetype ? `/${archetype}` : ''}${pattern ? `/${pattern}` : ''}`);
+        } else if (kitMode) {
+          console.warn(`   ⚠️ knoxis-pair-program.js not found — cannot run kit mode`);
+        } else if (taskPrompt) {
           promptFile = path.join(os.tmpdir(), `knoxis-task-${msg.requestId || Date.now()}.txt`);
           fs.writeFileSync(promptFile, taskPrompt, 'utf8');
 
@@ -1406,6 +1525,28 @@ function connectRelayWebSocket() {
         }
       } else if (msg.type === 'connected') {
         console.log(`🤝 Backend acknowledged: ${msg.message}`);
+      } else if (msg.type === 'portal_config') {
+        // Backend is auto-distributing the portal-sync token + URL so devs
+        // don't paste them by hand. Merge into ~/.knoxis/config.json so
+        // portal-sync.js picks them up on the next session save.
+        try {
+          ensureKnoxisDir();
+          const cfgPath = path.join(KNOXIS_DIR, 'config.json');
+          let existing = {};
+          try {
+            if (fs.existsSync(cfgPath)) existing = JSON.parse(fs.readFileSync(cfgPath, 'utf8')) || {};
+          } catch (_) {}
+          if (typeof msg.portalToken === 'string' && msg.portalToken) existing.portalToken = msg.portalToken;
+          if (typeof msg.portalUrl === 'string' && msg.portalUrl) existing.portalUrl = msg.portalUrl;
+          if (typeof msg.portalSessionsPath === 'string' && msg.portalSessionsPath) {
+            existing.portalSessionsPath = msg.portalSessionsPath;
+          }
+          fs.writeFileSync(cfgPath, JSON.stringify(existing, null, 2));
+          // Don't log the token itself.
+          console.log(`🔐 Portal-sync config received (token len ${(msg.portalToken || '').length})`);
+        } catch (cfgErr) {
+          console.warn(`⚠️ Failed to persist portal_config: ${cfgErr.message}`);
+        }
       }
     } catch (e) {
       console.error('❌ Relay message handling error:', e.message);

package/lib/knoxis-pair-program.js

@@ -4,6 +4,9 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { spawn, spawnSync, execSync } = require('child_process');
+const kitTemplates = require('./templates');
+const { scaffoldStateLayout, assertStateLayout } = require('./state-scaffold');
+const { syncSessionToPortal } = require('./portal-sync');
 
 // ===== RETRY CONFIGURATION =====
 // Can be overridden via environment variables
@@ -634,7 +637,7 @@ function slugify(text) {
 }
 
 class SessionRecorder {
-  constructor(task, workspace, aiProvider) {
+  constructor(task, workspace, aiProvider, meta = {}) {
     this.sessionId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     this.task = task;
     this.workspace = workspace;
@@ -642,6 +645,16 @@ class SessionRecorder {
     this.startedAt = new Date().toISOString();
     this.steps = [];
     this.initialCommit = safeExec('git rev-parse --short HEAD', workspace);
+    // Schema-aligned metadata — maps to portal contract §3.4 SESSION fields.
+    this.mode = meta.mode || null;
+    this.archetype = meta.archetype || null;
+    this.productSlug = meta.productSlug || null;
+    this.projectSlug = meta.projectSlug || null;
+    this.engineerId = meta.engineerId || null;
+    // QIG portal linkage (set when launching from collaboration/tasks UI).
+    this.userId = meta.userId || null;            // profiles.id (auth user)
+    this.workspaceId = meta.workspaceId || null;  // collab_workspaces.id
+    this.taskIds = Array.isArray(meta.taskIds) ? meta.taskIds.filter(Boolean) : [];
     ensureSessionDir();
   }
 
@@ -671,59 +684,99 @@ class SessionRecorder {
   }
 
   async saveAsync() {
-    const record = {
-      sessionId: this.sessionId, version: '1.0.0',
-      task: this.task, workspace: this.workspace, aiProvider: this.aiProvider,
-      startedAt: this.startedAt, completedAt: new Date().toISOString(),
-      totalDurationMs: Date.now() - new Date(this.startedAt).getTime(),
-      steps: this.steps,
-      totalSteps: this.steps.length,
-      completedSteps: this.steps.filter(s => s.completedAt && !s.error).length,
-      git: {
-        initialCommit: this.initialCommit,
-        finalCommit: await safeExecAsync('git rev-parse --short HEAD', this.workspace) || '',
-        totalDiff: await safeExecAsync('git diff', this.workspace) || ''
-      },
-      environment: { platform: os.platform(), nodeVersion: process.version }
-    };
+    const finalCommit = await safeExecAsync('git rev-parse --short HEAD', this.workspace) || '';
+    const totalDiff = await safeExecAsync('git diff', this.workspace) || '';
+    const record = this._buildRecord(finalCommit, totalDiff);
     const filename = `${this.sessionId}-${slugify(this.task)}.json`;
     const filepath = path.join(SESSIONS_DIR, filename);
     await fs.promises.writeFile(filepath, JSON.stringify(record, null, 2), 'utf8');
     // Append to index
     try {
       await fs.promises.appendFile(path.join(SESSIONS_DIR, 'index.jsonl'),
-        JSON.stringify({ sessionId: record.sessionId, task: record.task, startedAt: record.startedAt, totalDurationMs: record.totalDurationMs, file: filename }) + '\n');
+        JSON.stringify({ sessionId: record.sessionId, mode: record.mode, archetype: record.archetype, task: record.task, startedAt: record.startedAt, totalDurationMs: record.totalDurationMs, file: filename }) + '\n');
     } catch (e) {}
     return filepath;
   }
 
   // Sync version kept for backward compatibility
   save() {
-    const record = {
-      sessionId: this.sessionId, version: '1.0.0',
-      task: this.task, workspace: this.workspace, aiProvider: this.aiProvider,
-      startedAt: this.startedAt, completedAt: new Date().toISOString(),
-      totalDurationMs: Date.now() - new Date(this.startedAt).getTime(),
-      steps: this.steps,
-      totalSteps: this.steps.length,
-      completedSteps: this.steps.filter(s => s.completedAt && !s.error).length,
-      git: {
-        initialCommit: this.initialCommit,
-        finalCommit: safeExec('git rev-parse --short HEAD', this.workspace),
-        totalDiff: safeExec('git diff', this.workspace) || ''
-      },
-      environment: { platform: os.platform(), nodeVersion: process.version }
-    };
+    const finalCommit = safeExec('git rev-parse --short HEAD', this.workspace);
+    const totalDiff = safeExec('git diff', this.workspace) || '';
+    const record = this._buildRecord(finalCommit, totalDiff);
     const filename = `${this.sessionId}-${slugify(this.task)}.json`;
     const filepath = path.join(SESSIONS_DIR, filename);
     fs.writeFileSync(filepath, JSON.stringify(record, null, 2), 'utf8');
     // Append to index
     try {
       fs.appendFileSync(path.join(SESSIONS_DIR, 'index.jsonl'),
-        JSON.stringify({ sessionId: record.sessionId, task: record.task, startedAt: record.startedAt, totalDurationMs: record.totalDurationMs, file: filename }) + '\n');
+        JSON.stringify({ sessionId: record.sessionId, mode: record.mode, archetype: record.archetype, task: record.task, startedAt: record.startedAt, totalDurationMs: record.totalDurationMs, file: filename }) + '\n');
     } catch (e) {}
     return filepath;
   }
+
+  buildFinalRecord() {
+    const finalCommit = safeExec('git rev-parse --short HEAD', this.workspace);
+    const totalDiff = safeExec('git diff', this.workspace) || '';
+    return this._buildRecord(finalCommit, totalDiff);
+  }
+
+  _buildRecord(finalCommit, totalDiff) {
+    const completedSteps = this.steps.filter(s => s.completedAt && !s.error).length;
+    const closedCleanly = this.steps.length > 0 && completedSteps === this.steps.length;
+    return {
+      // Identification
+      sessionId: this.sessionId,
+      version: '1.1.0',
+      // Portal contract §3.4 SESSION shape
+      mode: this.mode,
+      archetype: this.archetype,
+      productSlug: this.productSlug,
+      projectSlug: this.projectSlug,
+      engineerId: this.engineerId,
+      // QIG portal linkage
+      userId: this.userId,
+      workspaceId: this.workspaceId,
+      taskIds: this.taskIds,
+      task: this.task,
+      workspace: this.workspace,
+      aiProvider: this.aiProvider,
+      startedAt: this.startedAt,
+      completedAt: new Date().toISOString(),
+      totalDurationMs: Date.now() - new Date(this.startedAt).getTime(),
+      // Step-level detail (preserved from v1.0.0)
+      steps: this.steps,
+      totalSteps: this.steps.length,
+      completedSteps,
+      closedCleanly,
+      // Derived collections — populated initially as empty arrays so the
+      // portal can index them; structured extraction from Claude responses
+      // is a follow-up. Maps to portal contract fields decisions_logged,
+      // waivers_requested, incidents_flagged, rule_violations.
+      filesTouched: extractFilesTouched(totalDiff),
+      decisionsLogged: [],
+      waiversRequested: [],
+      incidentsFlagged: [],
+      ruleViolations: [],
+      archetypeSpecificData: {},
+      git: {
+        initialCommit: this.initialCommit,
+        finalCommit,
+        totalDiff
+      },
+      environment: { platform: os.platform(), nodeVersion: process.version }
+    };
+  }
+}
+
+function extractFilesTouched(diff) {
+  if (!diff || typeof diff !== 'string') return [];
+  const seen = new Set();
+  const re = /^diff --git a\/(\S+) b\/(\S+)/gm;
+  let match;
+  while ((match = re.exec(diff)) !== null) {
+    seen.add(match[2] || match[1]);
+  }
+  return Array.from(seen);
 }
 
 // ===== MAIN =====
@@ -753,17 +806,61 @@ async function run() {
 
   const timeline = args['timeline-base64'] ? decodeJsonBase64(args['timeline-base64'], 'timeline') : null;
 
+  // Kit mode dispatch — when --mode is set, the runner replaces the default
+  // 4-step pipeline with a single-step invocation of the matching kit prompt
+  // (docs/Pair Programmer Docs/0[1-4]-*.md). Default mode (no --mode flag)
+  // preserves existing behavior so callers like knoxis-interactive-pair.js
+  // and the local-agent's single-shot path remain unaffected.
+  const mode = typeof args.mode === 'string' ? args.mode : null;
+  const archetype = typeof args.archetype === 'string' ? args.archetype : null;
+  const recoveryPattern = typeof args.pattern === 'string' ? args.pattern : null;
+
+  if (mode && !kitTemplates.isKitMode(mode)) {
+    console.error(`Unknown --mode "${mode}". Supported: ${kitTemplates.listModes().join(', ')}`);
+    process.exit(1);
+  }
+
   let task = args['prompt-base64'] ? decodeBase64(args['prompt-base64']) : args.prompt;
   if ((!task || !task.trim()) && timeline && typeof timeline.task === 'string') {
     task = timeline.task;
   }
 
-  if (!task || !task.trim()) {
-    console.error('A task prompt is required via --prompt, --prompt-base64, or timeline.task.');
+  // Kickoff and session-end can run without a prompt — the kit prompt itself
+  // drives the interaction. Resume and recovery accept an optional prompt as
+  // operator context. Default mode still requires a task.
+  const taskOptionalForMode = mode === 'kickoff' || mode === 'session-end';
+  if ((!task || !task.trim()) && !taskOptionalForMode) {
+    if (mode) {
+      console.error(`A --prompt is required for --mode ${mode} (operator context).`);
+    } else {
+      console.error('A task prompt is required via --prompt, --prompt-base64, or timeline.task.');
+    }
     process.exit(1);
   }
 
-  task = task.trim();
+  // Keep the user-provided task separate from the recorder/slug placeholder
+  // so the kit prompt header doesn't render `Initial task hint: [kickoff session]`.
+  const userTask = (task || '').trim();
+  task = userTask || `[${mode || 'default'} session]`;
+
+  // 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);
+
+  // Mode-specific preconditions: resume / session-end need real state. If the
+  // workspace was just scaffolded for them, the placeholder STATUS/HANDOFF
+  // exist — assertStateLayout will pass against the placeholders and the
+  // operator gets a useful warning at runtime instead of an error.
+  if (mode === 'resume' || mode === 'session-end') {
+    try {
+      assertStateLayout(workspace, mode);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  }
 
   const aiConfig = resolveAiProvider(args['ai-provider'] || args.provider);
 
@@ -778,11 +875,43 @@ async function run() {
     globalContextInputs.push(timeline.sharedContext);
   }
 
+  // Default mode: auto-include the standards + live state files so every task
+  // lands with the rules and prior context already in the prompt. Kit modes
+  // skip this — their authored prompts tell Claude which files to read itself,
+  // and we don't want to balloon their token budget with redundant content.
+  if (!mode && !args['no-auto-context']) {
+    for (const rel of ['CODING_RULES.md', 'docs/state/STATUS.md', 'docs/state/HANDOFF.md', 'docs/state/DECISIONS.md']) {
+      const abs = path.join(workspace, rel);
+      if (fs.existsSync(abs)) globalContextInputs.push(rel);
+    }
+  }
+
   const globalContext = await gatherContext(workspace, globalContextInputs);
   const globalContextBlock = globalContext.sections.join('\n\n');
 
   let scheduledSteps;
-  if (timeline && Array.isArray(timeline.steps) && timeline.steps.length) {
+  if (mode) {
+    const tpl = kitTemplates.getTemplate(mode, {
+      taskDescription: userTask || null,
+      archetype,
+      pattern: recoveryPattern,
+      productSlug: args['product-slug'] || null,
+      projectSlug: args['project-slug'] || null,
+      workspace
+    });
+    scheduledSteps = [{
+      key: tpl.key,
+      title: tpl.title,
+      displayName: aiConfig.label,
+      persona: null,
+      instruction: tpl.body,
+      contextPaths: [],
+      includeContext: true,
+      // Suppress the generic systemIntro — kit prompts set their own role/framing
+      // and the kit's coaching tone shouldn't be overridden.
+      suppressSystemIntro: true
+    }];
+  } else if (timeline && Array.isArray(timeline.steps) && timeline.steps.length) {
     scheduledSteps = timeline.steps.map((step, index) => ({
       key: step.key || `step-${index + 1}`,
       title: step.title || '',
@@ -804,14 +933,46 @@ 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}`);
   console.log(`AI Partner: ${aiConfig.label}`);
+  if (mode) console.log(`Mode: ${mode}${archetype ? ` (archetype: ${archetype})` : ''}${recoveryPattern ? ` (pattern: ${recoveryPattern})` : ''}`);
   console.log(`Task: ${task}`);
   console.log('==============================================');
   console.log('');
 
+  if (scaffoldResult) {
+    if (scaffoldResult.dirs.length || scaffoldResult.files.length) {
+      console.log('Scaffolded standard layout:');
+      scaffoldResult.dirs.forEach(d => console.log(`  + dir  ${d}/`));
+      scaffoldResult.files.forEach(f => console.log(`  + file ${f}`));
+    }
+    if (scaffoldResult.skipped.length) {
+      console.log(`Existing files preserved: ${scaffoldResult.skipped.join(', ')}`);
+    }
+    console.log('');
+  }
+
   if (globalContext.labels.length) {
     console.log(`Shared context files: ${globalContext.labels.join(', ')}`);
     console.log('');
@@ -821,7 +982,16 @@ async function run() {
   const recordingEnabled = !args['no-record'];
   let recorder = null;
   if (recordingEnabled) {
-    recorder = new SessionRecorder(task, workspace, aiConfig.label);
+    recorder = new SessionRecorder(task, workspace, aiConfig.label, {
+      mode,
+      archetype,
+      productSlug,
+      projectSlug,
+      engineerId,
+      userId,
+      workspaceId: workspaceIdArg,
+      taskIds: taskIdsArg
+    });
     console.log(`Recording: ON`);
     console.log('');
   }
@@ -847,6 +1017,14 @@ Your technical approach:
 - Don't over-engineer - solve the problem at hand
 - Leave the codebase better than you found it
 
+Project standards (binding for every task):
+- Apply the rules in \`CODING_RULES.md\` at the workspace root. They are not optional.
+- Before substantive work, read \`docs/state/STATUS.md\` and \`docs/state/HANDOFF.md\` to orient on prior context.
+- When the task is complete, update \`docs/state/STATUS.md\` (Done / In flight / Next) and overwrite \`docs/state/HANDOFF.md\` with a concrete pickup point for next session.
+- If the task ships or merges code, append a one-line entry to \`docs/state/CHANGELOG.md\` under \`## [Unreleased]\`.
+- Capture any non-trivial decisions in \`docs/state/DECISIONS.md\` (Context / Decision / Alternatives / Consequences). Architectural decisions go in \`docs/architecture/adr/\` instead.
+- Add genuinely unresolved questions to \`docs/state/OPEN_QUESTIONS.md\`.
+
 IMPORTANT: Work autonomously. Do not ask questions or wait for confirmation. Make decisions and implement.
 Only work inside the provided workspace and preserve user data.`;
 
@@ -868,7 +1046,7 @@ Only work inside the provided workspace and preserve user data.`;
 
     const includeContext = history.length <= 1 || step.includeContext || stepContext.sections.length > 0;
     const prompt = buildPrompt({
-      systemIntro,
+      systemIntro: step.suppressSystemIntro ? null : systemIntro,
       personaIntro: step.persona,
       conversation: conversationLines(),
       instructionLabel: 'Coordinator',
@@ -901,11 +1079,20 @@ Only work inside the provided workspace and preserve user data.`;
     }
   }
 
-  // Save session recording
+  // Save session recording, then sync to the portal stub if configured.
   if (recorder) {
     const recordPath = recorder.save();
     console.log(`Session recorded: ${recordPath}`);
     console.log('');
+
+    if (!args['no-portal-sync']) {
+      try {
+        const finalRecord = recorder.buildFinalRecord();
+        await syncSessionToPortal(finalRecord);
+      } catch (e) {
+        console.warn(`[Portal] Sync errored: ${e.message}`);
+      }
+    }
   }
 
   // Print retry statistics if any retries occurred