knoxis-helper 1.6.4 → 1.7.2

package/lib/framework-version.js

@@ -12,12 +12,12 @@
 // "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',
+  bundle: '1.1.0',
   documents: {
     overview: 1,
-    kickoff: 7,
-    resume: 3,
-    sessionEnd: 3,
+    kickoff: 8,
+    resume: 4,
+    sessionEnd: 4,
     recovery: 3,
     codingRuleset: 3,
     marketplaceMcp: 3,

package/lib/knoxis-interactive-pair.js

@@ -36,6 +36,7 @@ const os = require('os');
 const { SessionRecorder } = require('./session-recorder');
 const { scaffoldStateLayout } = require('./state-scaffold');
 const { syncSessionToPortal } = require('./portal-sync');
+const kitTemplates = require('./templates');
 
 // === CONFIG ===
 const CONFIG_PATH = path.join(os.homedir(), '.knoxis', 'config.json');
@@ -354,10 +355,89 @@ async function finalizeSession(recorder) {
   }
 }
 
+// === KIT MODE (kickoff / resume) ===
+// When the local agent routes a kit mode here, it sets KNOXIS_KIT_MODE so we
+// load the matching kit template (the same module pair-program.js uses) and
+// run it as a single Claude turn via runClaudeTurn — i.e. through `claude -p
+// --session-id`, which has the file-writing tool access the kit prompts need.
+// The 4-phase Groq flow is bypassed entirely; kit prompts are self-contained
+// frameworks with their own state machine.
+async function runKitMode(kitMode, task, identity, scaffoldResult) {
+  const archetype = process.env.KNOXIS_KIT_ARCHETYPE || null;
+  const pattern = process.env.KNOXIS_KIT_PATTERN || null;
+  let tpl;
+  try {
+    tpl = kitTemplates.getTemplate(kitMode, {
+      taskDescription: task || null,
+      archetype,
+      pattern,
+      productSlug: identity.productSlug,
+      projectSlug: identity.projectSlug,
+      workspace: identity.workspace
+    });
+  } catch (e) {
+    console.error('Kit template error: ' + e.message);
+    process.exit(1);
+  }
+
+  const recorder = new SessionRecorder(task || `[${kitMode} session]`, identity.workspace, 'Claude Code (kit)', {
+    mode: kitMode,
+    archetype,
+    productSlug: identity.productSlug,
+    projectSlug: identity.projectSlug,
+    engineerId: identity.engineerId,
+    userId: identity.userId,
+    workspaceId: identity.workspaceId,
+    taskIds: identity.taskIds
+  });
+
+  console.log('');
+  console.log('╔══════════════════════════════════════════════════════════════╗');
+  console.log('║        KNOXIS KIT MODE: ' + kitMode.toUpperCase().padEnd(36) + '║');
+  console.log('╚══════════════════════════════════════════════════════════════╝');
+  console.log('');
+  console.log('  Mode:      ' + kitMode + (archetype ? ' (archetype: ' + archetype + ')' : ''));
+  console.log('  Workspace: ' + identity.workspace);
+  console.log('  Session:   ' + SESSION_ID);
+  console.log('  Recorded:  ' + recorder.sessionId);
+  if (task) console.log('  Hint:      ' + task.substring(0, 100) + (task.length > 100 ? '...' : ''));
+  if (scaffoldResult && (scaffoldResult.dirs.length || scaffoldResult.files.length)) {
+    console.log('  Scaffolded: ' + (scaffoldResult.dirs.length + scaffoldResult.files.length) + ' new entries (CODING_RULES + docs/state/)');
+  }
+  console.log('');
+
+  appendLog('# Knoxis Kit Mode: ' + kitMode);
+  appendLog('Session: ' + SESSION_ID);
+  if (task) appendLog('Hint: ' + task);
+  appendLog('Date: ' + new Date().toISOString());
+  appendLog('');
+
+  const stepKey = 'kit-' + kitMode;
+  const stepIdx = recorder.startStep(stepKey, 'Claude Code', tpl.body);
+  recorder.setStepPrompt(stepIdx, tpl.body);
+  const result = await runClaudeTurn(tpl.body, false);
+  appendLog(result.stdout.substring(0, 10000) + '\n');
+  recorder.completeStep(stepIdx, result.stdout, result.code !== 0 ? 'exit ' + result.code + (result.stderr ? ': ' + result.stderr.slice(0, 200) : '') : null);
+
+  console.log('');
+  console.log('╔══════════════════════════════════════════════════════════════╗');
+  console.log('║        KIT SESSION COMPLETE                                 ║');
+  console.log('╚══════════════════════════════════════════════════════════════╝');
+  console.log('');
+  const logFile = saveSessionLog();
+  if (logFile) console.log('  Log: ' + logFile);
+  console.log('  Resume: claude --resume ' + SESSION_ID);
+  console.log('');
+
+  await finalizeSession(recorder);
+  process.exit(result.code || 0);
+}
+
 // === MAIN ===
 async function main() {
+  const kitMode = process.env.KNOXIS_KIT_MODE || null;
   const task = loadTask();
-  if (!task) {
+  if (!task && !kitMode) {
     console.error('No task found. Set KNOXIS_TASK_FILE, pass as CLI argument, or include in CLAUDE.md.');
     process.exit(1);
   }
@@ -376,6 +456,17 @@ async function main() {
     console.warn('  Scaffold failed: ' + e.message);
   }
 
+  // Kit modes (kickoff/resume) take a different path: run the kit template as
+  // a single Claude turn. Skips the 4-phase Groq plan/implement/verify flow —
+  // the kit prompt is the framework.
+  if (kitMode) {
+    if (!kitTemplates.isKitMode(kitMode)) {
+      console.error('Unknown KNOXIS_KIT_MODE "' + kitMode + '". Supported: ' + kitTemplates.listModes().join(', '));
+      process.exit(1);
+    }
+    return runKitMode(kitMode, task, identity, scaffoldResult);
+  }
+
   const recorder = new SessionRecorder(task, identity.workspace, 'Claude Code + Knoxis (Groq)', {
     mode: null,             // interactive flow isn't a kit mode
     archetype: null,

package/lib/knoxis-local-agent.js

@@ -595,6 +595,13 @@ function resolvePairProgramScript() {
 }
 
 const KIT_MODES = new Set(['kickoff', 'resume', 'session-end', 'recovery']);
+// kickoff and resume rely on Claude actually writing files to disk
+// (docs/state/OPEN_QUESTIONS.md and the rest of the context pack). The
+// interactive runner invokes `claude -p --session-id`, which gives Claude
+// proper tool access; pair-program.js pipes to `claude` without -p and
+// silently skips the file writes. Route those two kits through the
+// interactive runner so their kit prompts actually do their work.
+const KIT_MODES_VIA_INTERACTIVE = new Set(['kickoff', 'resume']);
 
 function buildPairProgramCommand({ scriptPath, workspace, mode, archetype, pattern, productSlug, projectSlug, taskPrompt, userId, workspaceId, taskIds }) {
   const q = v => `"${escapeForDoubleQuotedShellArg(v)}"`;
@@ -965,11 +972,28 @@ async function handleRequest(req, res) {
       // 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) {
+      const kitViaInteractive = kitMode && KIT_MODES_VIA_INTERACTIVE.has(kitMode);
+      if (kitMode && !kitViaInteractive && !ppScript) {
         return sendJSON(res, 500, { success: false, error: 'knoxis-pair-program.js not found — reinstall knoxis-helper.' }, requestOrigin);
       }
-
-      if (kitMode || (ppScript && !interactive && promptText)) {
+      if (kitViaInteractive) {
+        const scriptPath = resolveInteractiveScript();
+        if (!scriptPath) {
+          return sendJSON(res, 500, { success: false, error: 'knoxis-interactive-pair.js not found — reinstall knoxis-helper.' }, requestOrigin);
+        }
+        const kitEnv = { KNOXIS_WORKSPACE_PATH: workspaceDir, KNOXIS_KIT_MODE: kitMode };
+        if (promptText) kitEnv.KNOXIS_TASK_FILE = promptFile;
+        if (archetype) kitEnv.KNOXIS_KIT_ARCHETYPE = archetype;
+        if (pattern) kitEnv.KNOXIS_KIT_PATTERN = pattern;
+        if (productSlug) kitEnv.KNOXIS_PRODUCT_SLUG = productSlug;
+        if (projectSlug) kitEnv.KNOXIS_PROJECT_SLUG = projectSlug;
+        if (portalUserId) kitEnv.KNOXIS_USER_ID = portalUserId;
+        if (portalWorkspaceId) kitEnv.KNOXIS_WORKSPACE_ID = portalWorkspaceId;
+        if (portalTaskIds && portalTaskIds.length) kitEnv.KNOXIS_TASK_IDS = portalTaskIds.join(',');
+        command = buildEnvCommand(kitEnv, `node "${scriptPath}"`);
+        mode = `kit:${kitMode}${archetype ? `/${archetype}` : ''}`;
+        console.log(`🧰 Kit (interactive runner): ${mode} — ${scriptPath}`);
+      } else if (kitMode || (ppScript && !interactive && promptText)) {
         command = buildPairProgramCommand({
           scriptPath: ppScript,
           workspace: workspaceDir,
@@ -1447,9 +1471,35 @@ function connectRelayWebSocket() {
           ? 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) {
+        const kitViaInteractive = kitMode && KIT_MODES_VIA_INTERACTIVE.has(kitMode);
+        const routeViaPairProgram = !kitViaInteractive && (kitMode || (ppScript && !interactive && taskPrompt));
+
+        if (kitViaInteractive) {
+          const scriptPath = resolveInteractiveScript();
+          if (scriptPath) {
+            // kickoff/resume need Claude's tool path (claude -p --session-id),
+            // which the interactive runner provides. Pass the kit mode + identity
+            // via env so the runner picks the kit branch instead of the 4-phase
+            // Groq flow.
+            if (taskPrompt) {
+              promptFile = path.join(os.tmpdir(), `knoxis-task-${msg.requestId || Date.now()}.txt`);
+              fs.writeFileSync(promptFile, taskPrompt, 'utf8');
+            }
+            const kitEnv = { KNOXIS_WORKSPACE_PATH: wsDir, KNOXIS_KIT_MODE: kitMode };
+            if (promptFile) kitEnv.KNOXIS_TASK_FILE = promptFile;
+            if (archetype) kitEnv.KNOXIS_KIT_ARCHETYPE = archetype;
+            if (pattern) kitEnv.KNOXIS_KIT_PATTERN = pattern;
+            if (productSlug) kitEnv.KNOXIS_PRODUCT_SLUG = productSlug;
+            if (projectSlug) kitEnv.KNOXIS_PROJECT_SLUG = projectSlug;
+            if (portalUserId) kitEnv.KNOXIS_USER_ID = portalUserId;
+            if (portalWorkspaceId) kitEnv.KNOXIS_WORKSPACE_ID = portalWorkspaceId;
+            if (portalTaskIds && portalTaskIds.length) kitEnv.KNOXIS_TASK_IDS = portalTaskIds.join(',');
+            command = buildEnvCommand(kitEnv, `node "${scriptPath}"`);
+            console.log(`   🧰 Kit (interactive runner): ${kitMode}${archetype ? `/${archetype}` : ''} — ${scriptPath}`);
+          } else {
+            console.warn(`   ⚠️ knoxis-interactive-pair.js not found — cannot run kit mode ${kitMode}`);
+          }
+        } else if (routeViaPairProgram && ppScript) {
           command = buildPairProgramCommand({
             scriptPath: ppScript,
             workspace: wsDir,

package/lib/state-scaffold.js

@@ -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
     },
     {

package/lib/templates/kickoff.js

@@ -2,6 +2,117 @@
 
 // Source: docs/Pair Programmer Docs/pair-programmer/framework/01-kickoff.md (v7 — product-centric)
 // Embedded so the runner is self-contained and versioned with the package.
+//
+// Single-shot adaptation (v8): the helper runs Claude in single-shot mode (no
+// interactive REPL between Claude and the operator). The framework body below
+// is written for an interactive coach. The OPERATING_MODE_PREAMBLE prepended
+// at buildKickoffPrompt() time turns the interview into a file-mediated flow
+// driven by docs/state/OPEN_QUESTIONS.md so single-shot kickoff actually
+// produces the context pack instead of stalling on the first question.
+const OPERATING_MODE_PREAMBLE = `# Operating mode — single-shot, file-mediated (v8)
+
+You are running in single-shot mode. There is no interactive REPL with the operator: you produce one response and the process exits. The framework body that follows tells you to ask one question at a time and wait — **ignore that pacing**. Use the file-mediated flow below instead.
+
+The interview happens through \`docs/state/OPEN_QUESTIONS.md\`. You write questions there, the operator fills in answers there, the operator re-runs kickoff, you read the answers and produce the context pack. Same questions, same coverage, just batched.
+
+## Step 0 — Read state and pick a branch
+
+Before anything else, read \`docs/state/OPEN_QUESTIONS.md\` (if it doesn't exist, scaffold the layout first). It has three sections: \`## Pending Answers\`, \`## Active\`, \`## Resolved\`. Look only at \`## Pending Answers\` to decide which branch you're in.
+
+Each pending entry has this shape:
+
+\`\`\`markdown
+### N. <question>
+*Phase: <phase>. Raised: <date>.*
+**Answer:** _(fill in)_
+\`\`\`
+
+An entry is **answered** when the \`**Answer:**\` line is anything other than the literal placeholder \`_(fill in)_\` and is non-empty.
+
+Branch:
+- **A. No \`## Pending Answers\` section, or section is empty** → State A (first run, generate questions).
+- **B. \`## Pending Answers\` exists with at least one entry whose answer is still \`_(fill in)_\`** → State B (waiting on operator).
+- **C. \`## Pending Answers\` exists and every entry is answered** → State C (consume answers, write context pack).
+
+## State A — Generate questions
+
+Scaffold the layout if missing (\`docs/state/\`, \`docs/product/\`, \`docs/architecture/adr/\`, \`docs/planning/\`, plus \`OPEN_QUESTIONS.md\` with \`## Pending Answers\`, \`## Active\`, \`## Resolved\` sections).
+
+Walk through Phases -1 through 6 of the framework body below and **batch every question you would ask** into \`docs/state/OPEN_QUESTIONS.md\` under \`## Pending Answers\`. Number them sequentially. Tag each with the phase it belongs to. Group conceptually but keep numbering global. For each question:
+
+- Be specific — the operator answers in plain text, no follow-up.
+- Where the framework offers a default or 3–4 options, list them inline so the operator can just pick.
+- Where Phase -1 already has portal-provided product context (a \`product.local.json\` exists in the parent dir or was pasted), pre-fill those answers instead of re-asking.
+
+Format each entry exactly:
+
+\`\`\`markdown
+### N. <question, including any options>
+*Phase: <-1|0|1|2|3|4|5|6>. Raised: <today's ISO date>.*
+**Answer:** _(fill in)_
+\`\`\`
+
+Do **not** write README.md, CLAUDE.md, PRD.md, ARCHITECTURE.md, BACKLOG.md, or any other context-pack file in this state. Only OPEN_QUESTIONS.md and the directory scaffold.
+
+End your response with a short block telling the operator exactly what to do next:
+
+\`\`\`
+Kickoff interview written to docs/state/OPEN_QUESTIONS.md (<count> questions).
+
+Next:
+  1. Open docs/state/OPEN_QUESTIONS.md
+  2. Fill in **Answer:** lines (replace \`_(fill in)_\`)
+  3. Re-run: knoxis-pair-program --mode kickoff --workspace <name>
+
+The framework files (README, PRD, ARCHITECTURE, etc.) will be generated on the next run once answers are present.
+\`\`\`
+
+Then stop.
+
+## State B — Waiting on operator
+
+Do not re-ask. Do not re-write OPEN_QUESTIONS.md. Do not write the context pack.
+
+Read \`## Pending Answers\` and list the question numbers that still have \`_(fill in)_\`. Print:
+
+\`\`\`
+Kickoff is waiting on answers in docs/state/OPEN_QUESTIONS.md.
+
+Unanswered: #<n>, #<n>, #<n>
+Answered:   #<n>, #<n>
+
+Fill in the remaining **Answer:** lines and re-run kickoff to generate the context pack.
+\`\`\`
+
+Then stop.
+
+## State C — Consume answers and write the context pack
+
+Now execute Phases 1 through 8 of the framework body below in one pass, using the answers as your source of truth. Specifically:
+
+1. Read every \`### N. <question>\` / \`**Answer:** ...\` pair in \`## Pending Answers\`.
+2. Resolve each phase's questions against those answers. If an answer is ambiguous, pick the most pragmatic interpretation and note the assumption in DECISIONS.md rather than asking again.
+3. Write the full context pack — README.md, CLAUDE.md, docs/product/PRD.md, docs/architecture/ARCHITECTURE.md (and any ADRs), docs/product/GLOSSARY.md, docs/planning/EXECUTION_PLAN.md, docs/planning/BACKLOG.md (with acceptance criteria), and the state files (STATUS.md, HANDOFF.md, DECISIONS.md, CHANGELOG.md, RISKS.md, KICKOFF.md). Apply the YAML frontmatter convention from the framework body.
+4. Move every \`### N.\` from \`## Pending Answers\` to \`## Resolved\` in OPEN_QUESTIONS.md, preserving the question text and adding a one-line resolution note (e.g. *"Resolved <date>: captured in PRD / CLAUDE.md / D-1 / etc."*). Leave the \`## Pending Answers\` section header in place but empty.
+5. Any genuinely unresolved item that emerged during the write-up (TBDs the answers didn't cover) goes under \`## Active\` — not \`## Pending Answers\`. Pending Answers is reserved for kickoff/resume interview questions awaiting operator input; Active is for project-level open questions.
+6. Append a one-line entry to docs/state/CHANGELOG.md under \`## [Unreleased]\` → \`### Added\`: \`Project initialized via kickoff (session <id>).\`
+
+End your response with a tour of what was written (file paths only, not full contents) and the Session 1 kickoff prompt in a copyable code block, per Phase 9.
+
+## Operator identity / session id
+
+Use \`KNOXIS_USER_ID\` from the environment (or whatever the framework body's "operator" question collected). Generate a session ID locally if no portal MCP is connected: \`s-<YYYY-MM-DD>-<HHmm>\`. Tag every artifact's frontmatter with this.
+
+## Non-negotiables
+
+- Always write to disk in States A and C. Do not describe what you would write.
+- Never wait for operator input mid-response.
+- Never overwrite an existing file unless the framework body explicitly says so for that file. STATUS.md, HANDOFF.md, CHANGELOG.md, OPEN_QUESTIONS.md may be appended/updated; README.md, CLAUDE.md, PRD.md, ARCHITECTURE.md must not exist already in State C (if they do, halt and report — that means kickoff already ran).
+
+---
+
+`;
+
 const KICKOFF_BODY = `# 01 — Project Kickoff (Coached, v7)
 
 > Use at the start of a new project. Generates the full context pack: README, PRD, ARCHITECTURE, CLAUDE.md, GLOSSARY, EXECUTION_PLAN, BACKLOG (with acceptance criteria), state scaffolding, and the Session 1 kickoff prompt.
@@ -534,11 +645,11 @@ function buildKickoffPrompt({ taskDescription, productSlug, projectSlug, workspa
   if (workspace) header.push(`Workspace: ${workspace}`);
   if (taskDescription) header.push(`Initial task hint: ${taskDescription}`);
   const ctx = header.length ? `Session context:\n${header.join('\n')}\n\n` : '';
-  return ctx + KICKOFF_BODY;
+  return ctx + OPERATING_MODE_PREAMBLE + KICKOFF_BODY;
 }
 
 module.exports = {
   title: 'Project Kickoff',
-  body: KICKOFF_BODY,
+  body: OPERATING_MODE_PREAMBLE + KICKOFF_BODY,
   buildPrompt: buildKickoffPrompt
 };

package/lib/templates/resume.js

@@ -1,6 +1,107 @@
 'use strict';
 
 // Source: docs/Pair Programmer Docs/pair-programmer/framework/02-resume.md (v3 — product-centric)
+//
+// Single-shot adaptation (v4): same as kickoff — the framework body is written
+// for an interactive coach but the helper runs Claude in single-shot mode. The
+// OPERATING_MODE_PREAMBLE prepended at buildResumePrompt() time turns resume
+// into a self-driving session that updates state files at the end and uses
+// docs/state/OPEN_QUESTIONS.md as the question bus when something genuinely
+// can't be decided autonomously.
+const OPERATING_MODE_PREAMBLE = `# Operating mode — single-shot, file-mediated (v4)
+
+You are running in single-shot mode. There is no interactive REPL with the operator: you produce one response and the process exits. The framework body that follows tells you to confirm direction, ask about archetype, and wait between steps — **ignore that pacing**. Use the file-mediated flow below.
+
+The handshake with the operator happens through \`docs/state/OPEN_QUESTIONS.md\`. If you genuinely can't proceed without operator input, write the question there under \`## Pending Answers\` and stop. Otherwise, do the work and update state files at the end.
+
+## Step 0 — Read state and pick a branch
+
+Read \`docs/state/OPEN_QUESTIONS.md\` first. It has three sections: \`## Pending Answers\` (kickoff/resume interview questions waiting on the operator), \`## Active\` (project-level unresolved questions), \`## Resolved\`. An entry under \`## Pending Answers\` is **answered** when the \`**Answer:**\` line is anything other than the literal placeholder \`_(fill in)_\` and is non-empty.
+
+Branch:
+- **A. \`## Pending Answers\` exists with at least one entry whose answer is still \`_(fill in)_\`** → State A (waiting on operator).
+- **B. \`## Pending Answers\` is empty or absent, or every entry there is answered** → State B (do the work).
+
+## State A — Waiting on operator
+
+Do not start work. Do not edit code. Do not write any other state files.
+
+Print:
+
+\`\`\`
+Resume blocked — waiting on answers in docs/state/OPEN_QUESTIONS.md.
+
+Unanswered: #<n>, #<n>
+Answered:   #<n>, #<n>
+
+Fill in the remaining **Answer:** lines and re-run resume.
+\`\`\`
+
+If any answered entries from a previous run are now ready to consume, briefly note what you'd do with them — but still don't act until **all** Pending Answers are resolved (the operator may be answering in batches).
+
+Then stop.
+
+## State B — Do the work
+
+Read CLAUDE.md, docs/state/STATUS.md, docs/state/HANDOFF.md, docs/state/DECISIONS.md, and the \`## Active\` section of OPEN_QUESTIONS.md to orient. The framework body below describes the archetype rituals (feature / bug / refactor / spike / review). Follow the matching ritual but **do not pause to ask the operator** which archetype this is — the runner passed an \`Archetype hint\` in the session context header above; use it. If absent, infer from the operator note / HANDOFF / pre-flight (default \`feature\`).
+
+Work autonomously. Make decisions. Where the framework says "wait for confirmation," substitute "make the most pragmatic call and capture the assumption in DECISIONS.md."
+
+If you hit something you genuinely can't decide alone — a security/compliance question, a missing credential, a contradiction between PRD and STATUS, a waiver request, an architectural fork that warrants the operator's call — append it to \`## Pending Answers\` in OPEN_QUESTIONS.md using the same shape kickoff uses:
+
+\`\`\`markdown
+### N. <question>
+*Phase: resume. Raised: <today's ISO date>.*
+**Answer:** _(fill in)_
+\`\`\`
+
+Then stop with a short note pointing at the new question(s). Do not partially-finish code.
+
+## Step N — Non-negotiable state update at end of work
+
+Before your response ends, **write the following files**. Do not describe them — actually write them. The QIG dashboard reads these; skipping any of them means the team loses visibility on what happened.
+
+1. **\`docs/state/STATUS.md\`** — overwrite. Update \`_Last updated:\` line. Sections:
+   - \`## 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. Concrete: file, function, feature, state.
+   - \`## Why I stopped here\`: brief.
+   - \`## 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 vars, 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 (including assumptions you locked in to avoid stalling), append:
+   \`\`\`
+   ## D-<n>: <one-line title>
+   **Context:** <2 sentences>
+   **Decision:** <what you chose>
+   **Alternatives considered:** <what else and why not>
+   **Consequences:** <implications>
+   \`\`\`
+   Skip only if no real decisions were made.
+
+5. **\`docs/state/OPEN_QUESTIONS.md\`** — move any newly-resolved Pending Answers to \`## Resolved\` with a one-line resolution note. Append any new project-level unknowns to \`## Active\`. Append any new operator-blocking questions to \`## Pending Answers\` per State B above.
+
+6. **\`docs/state/RISKS.md\`** — append any newly identified risks; update status of existing watched risks if they materialized / dissolved this session.
+
+End your response with a one-paragraph summary plus a list of files written and skipped (with reason for skips).
+
+## Non-negotiables
+
+- Always update STATUS.md and HANDOFF.md, even if the session was tiny.
+- Never wait for operator input mid-response. Use OPEN_QUESTIONS.md \`## Pending Answers\` as the question bus.
+- Never partially apply changes and stop. Either finish a logical unit and update state, or revert to a clean tree and surface the blocker via OPEN_QUESTIONS.md.
+
+---
+
+`;
+
 const RESUME_HEAD = `# 02 — Session Resume (Coached, v3)
 
 > Paste at the start of every working session after Session 1. Claude reads project state, refreshes product context from the portal, runs pre-flight checks, confirms direction with you, identifies the session archetype, and adapts. Apply the standard coding ruleset (\`05-coding-ruleset.md\` v3; rules referenced by ID).
@@ -288,12 +389,12 @@ function buildResumePrompt({ archetype, taskDescription, productSlug, projectSlu
     archetypeBlock = ALL_ARCHETYPES;
   }
 
-  return ctx + RESUME_HEAD + archetypeBlock + RESUME_TAIL;
+  return ctx + OPERATING_MODE_PREAMBLE + RESUME_HEAD + archetypeBlock + RESUME_TAIL;
 }
 
 module.exports = {
   title: 'Session Resume',
-  body: RESUME_HEAD + ALL_ARCHETYPES + RESUME_TAIL,
+  body: OPERATING_MODE_PREAMBLE + RESUME_HEAD + ALL_ARCHETYPES + RESUME_TAIL,
   buildPrompt: buildResumePrompt,
   archetypes: Object.keys(ARCHETYPE_MAP)
 };

package/lib/templates/session-end.js

@@ -242,13 +242,19 @@ Show me the changes. Confirm path.
 
 ## Step 7 — Update RISKS.md
 
-**Orientation:** "RISKS is what could go wrong, watched over time."
+**Orientation:** "RISKS is what could go wrong, watched over time. Two updates each session: add anything new that surfaced, update the status of any existing risk that materialized, dissolved, or shifted."
 
-Most sessions: nothing changes here. That's fine. Just ask:
+Walk through:
+
+- **New risks to add.** Scan the session for risk candidates: technical debt introduced, brittle integrations, unhandled edge cases, security or compliance concerns, deferred work, dependencies on unstable upstream systems, scope creep, fragile tests. Propose what you noticed:
+
+  > "Here are risks I noticed this session: <list 0–3 candidates with one-line framing>. Anything else?"
+
+- **Existing risks to update.** Read the current RISKS.md. For each watched risk, ask whether anything changed this session — did it become real, get mitigated, or dissolve?
 
-> "Anything I should add to RISKS? New risks I noticed, old risks that became real, old risks that went away?"
+  > "Looking at the watched risks: <list current R-<n> ids and one-line summaries>. Any status changes?"
 
-If yes, format:
+For each new risk, append:
 
 \`\`\`markdown
 ## R-<number>: <one-line risk>
@@ -259,7 +265,11 @@ If yes, format:
 - *Status:* watching / mitigated / materialized / dissolved
 \`\`\`
 
-If nothing, skip and note "no risk updates this session."
+For status changes on existing risks, update the *Status:* line in place and note the change in the Step 10 summary.
+
+If nothing genuinely surfaced and no existing risk shifted, say so explicitly. Don't fabricate to fill the file.
+
+Show me the changes. Confirm path.
 
 ## Step 8 — Rule events, waivers, incidents
 

package/package.json

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