@vpxa/aikit 0.1.145 → 0.1.147

package/scaffold/dist/definitions/skills/session-handoff.mjs

@@ -230,7 +230,8 @@ If multiple aspects "Need Exploration", spend time re-exploring the codebase bef
  *
  * Usage:
  *   node check_staleness.js <handoff-file>
- *   node check_staleness.js .handoffs/2024-01-15-143022-auth.md
+ *   node check_staleness.js .aikit-state/handoffs/add-auth/2024-01-15-143022-auth.md
+ *   node check_staleness.js .aikit-state/handoffs/_standalone/2024-01-15-143022-auth.md
  */
 
 const fs = require('node:fs');
@@ -367,6 +368,15 @@ function calculateStaleness(daysOld, commitsSince, filesChanged, branchMatches,
   return { level, recommendation, issues };
 }
 
+function resolveProjectRootFromHandoff(handoffPath) {
+  const handoffsDir = path.dirname(handoffPath);
+  const handoffMarkerDir = path.basename(path.dirname(handoffsDir));
+  const stateMarkerDir = path.basename(path.dirname(path.dirname(handoffsDir)));
+  const isFlowScoped = handoffMarkerDir === 'handoffs' && stateMarkerDir === '.aikit-state';
+
+  return isFlowScoped ? path.resolve(handoffsDir, '..', '..', '..') : path.resolve(handoffsDir, '..');
+}
+
 function checkStaleness(handoffPath) {
   if (!fs.existsSync(handoffPath)) return { error: \`Handoff file not found: \${handoffPath}\` };
 
@@ -374,7 +384,7 @@ function checkStaleness(handoffPath) {
   const projectPath =
     meta.projectPath && fs.existsSync(meta.projectPath)
       ? meta.projectPath
-      : path.resolve(path.dirname(handoffPath), '..'); // Up from .handoffs/
+      : resolveProjectRootFromHandoff(handoffPath);
 
   const isGitRepo = runCmd('git rev-parse --git-dir', projectPath).ok;
 
@@ -475,7 +485,8 @@ function printReport(result) {
 const args = process.argv.slice(2);
 if (args.includes('--help') || args.includes('-h') || args.length === 0) {
   console.log('Usage: node check_staleness.js <handoff-file>');
-  console.log('       node check_staleness.js .handoffs/2024-01-15-143022-auth.md');
+  console.log('       node check_staleness.js .aikit-state/handoffs/<flow-slug>/2024-01-15-143022-auth.md');
+  console.log('       node check_staleness.js .aikit-state/handoffs/_standalone/2024-01-15-143022-auth.md');
   process.exit(args.length === 0 ? 1 : 0);
 }
 
@@ -502,6 +513,7 @@ if (args.includes('--json')) {
  *   node create_handoff.js [task-slug]
  *   node create_handoff.js "implementing-auth"
  *   node create_handoff.js "auth-part-2" --continues-from 2024-01-15-auth.md
+ *   node create_handoff.js "auth-part-2" --flow add-auth
  *   node create_handoff.js  # auto-generates slug from timestamp
  */
 
@@ -549,48 +561,118 @@ function getGitInfo(projectPath) {
   return info;
 }
 
-function findPreviousHandoffs(projectPath) {
-  const dir = path.join(projectPath, '.handoffs');
-  if (!fs.existsSync(dir)) return [];
+function getFlowDirectories(projectPath) {
+  const flowsDir = path.join(projectPath, '.flows');
+  if (!fs.existsSync(flowsDir)) return [];
 
-  const handoffs = [];
-  for (const name of fs.readdirSync(dir)) {
-    if (!name.endsWith('.md')) continue;
-    const fp = path.join(dir, name);
+  return fs
+    .readdirSync(flowsDir)
+    .map((name) => ({ name, path: path.join(flowsDir, name) }))
+    .filter(({ name, path: flowPath }) => {
+      try {
+        return !name.startsWith('.') && fs.statSync(flowPath).isDirectory();
+      } catch {
+        return false;
+      }
+    })
+    .sort((a, b) => {
+      try {
+        return fs.statSync(b.path).mtimeMs - fs.statSync(a.path).mtimeMs;
+      } catch {
+        return 0;
+      }
+    });
+}
+
+function getActiveFlowSlug(projectPath) {
+  const flowDirs = getFlowDirectories(projectPath);
+  if (flowDirs.length === 0) return null;
+
+  const activeFlow = flowDirs.find(({ path: flowPath }) => {
+    const metaPath = path.join(flowPath, 'meta.json');
+    if (!fs.existsSync(metaPath)) return false;
 
-    let title = name;
     try {
-      const content = fs.readFileSync(fp, 'utf-8');
-      const m = content.match(/^#\\s+(?:Handoff:\\s*)?(.+)$/m);
-      if (m) title = m[1].trim();
+      const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+      return meta.status === 'active';
     } catch {
-      /* ignore */
+      return false;
     }
+  });
 
-    let date = null;
-    const dm = name.match(/^(\\d{4}-\\d{2}-\\d{2})-(\\d{6})/);
-    if (dm) {
+  return activeFlow ? activeFlow.name : null;
+}
+
+function getHandoffsDir(projectPath, flowSlug) {
+  if (flowSlug) return path.join(projectPath, '.aikit-state', 'handoffs', flowSlug);
+
+  const activeFlowSlug = getActiveFlowSlug(projectPath);
+  if (activeFlowSlug) return path.join(projectPath, '.aikit-state', 'handoffs', activeFlowSlug);
+
+  return path.join(projectPath, '.aikit-state', 'handoffs', '_standalone');
+}
+
+function findPreviousHandoffs(projectPath, flowSlug) {
+  const handoffs = [];
+  const baseDir = path.join(projectPath, '.aikit-state', 'handoffs');
+
+  function collectFromDir(dir, flow) {
+    if (!fs.existsSync(dir)) return;
+
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.endsWith('.md')) continue;
+      const fp = path.join(dir, name);
+
+      let title = name;
       try {
-        date = new Date(\`\${dm[1]}T\${dm[2].slice(0, 2)}:\${dm[2].slice(2, 4)}:\${dm[2].slice(4, 6)}\`);
+        const content = fs.readFileSync(fp, 'utf-8');
+        const m = content.match(/^#\\s+(?:Handoff:\\s*)?(.+)$/m);
+        if (m) title = m[1].trim();
       } catch {
         /* ignore */
       }
+
+      let date = null;
+      const dm = name.match(/^(\\d{4}-\\d{2}-\\d{2})-(\\d{6})/);
+      if (dm) {
+        try {
+          date = new Date(\`\${dm[1]}T\${dm[2].slice(0, 2)}:\${dm[2].slice(2, 4)}:\${dm[2].slice(4, 6)}\`);
+        } catch {
+          /* ignore */
+        }
+      }
+
+      handoffs.push({ filename: name, path: fp, title, date, flow });
     }
+  }
+
+  if (!fs.existsSync(baseDir)) return handoffs;
+
+  const flowDirs = flowSlug
+    ? [flowSlug]
+    : fs.readdirSync(baseDir).filter((name) => {
+        try {
+          return fs.statSync(path.join(baseDir, name)).isDirectory();
+        } catch {
+          return false;
+        }
+      });
 
-    handoffs.push({ filename: name, path: fp, title, date });
+  for (const fd of flowDirs) {
+    collectFromDir(path.join(baseDir, fd), fd === '_standalone' ? null : fd);
   }
 
   handoffs.sort((a, b) => (b.date || 0) - (a.date || 0));
   return handoffs;
 }
 
-function getPreviousHandoffInfo(projectPath, continuesFrom) {
-  const handoffs = findPreviousHandoffs(projectPath);
+function getPreviousHandoffInfo(projectPath, continuesFrom, flowSlug) {
+  const handoffs = findPreviousHandoffs(projectPath, flowSlug);
 
   if (continuesFrom) {
     const found = handoffs.find((h) => h.filename.includes(continuesFrom));
     return found
-      ? { exists: true, filename: found.filename, title: found.title }
+      ? { exists: true, filename: found.filename, title: found.title, flow: found.flow }
       : { exists: false, filename: continuesFrom, title: 'Not found' };
   }
 
@@ -599,6 +681,7 @@ function getPreviousHandoffInfo(projectPath, continuesFrom) {
       exists: true,
       filename: handoffs[0].filename,
       title: handoffs[0].title,
+      flow: handoffs[0].flow,
       suggested: true,
     };
   }
@@ -613,7 +696,7 @@ function sanitizeSlug(slug) {
     .replace(/[^a-z0-9-]/g, '');
 }
 
-function generateHandoff(projectPath, slug, continuesFrom) {
+function generateHandoff(projectPath, slug, continuesFrom, flowSlug) {
   const now = new Date();
   const timestamp = now.toISOString().replace('T', ' ').slice(0, 19);
   const fileTs = \`\${now.toISOString().slice(0, 10)}-\${String(now.getHours()).padStart(2, '0')}\${String(now.getMinutes()).padStart(2, '0')}\${String(now.getSeconds()).padStart(2, '0')}\`;
@@ -622,12 +705,13 @@ function generateHandoff(projectPath, slug, continuesFrom) {
   slug = sanitizeSlug(slug);
   const filename = \`\${fileTs}-\${slug}.md\`;
 
-  const handoffsDir = path.join(projectPath, '.handoffs');
+  const resolvedFlowSlug = flowSlug || getActiveFlowSlug(projectPath);
+  const handoffsDir = getHandoffsDir(projectPath, flowSlug);
   fs.mkdirSync(handoffsDir, { recursive: true });
   const filepath = path.join(handoffsDir, filename);
 
   const git = getGitInfo(projectPath);
-  const prev = getPreviousHandoffInfo(projectPath, continuesFrom);
+  const prev = getPreviousHandoffInfo(projectPath, continuesFrom, resolvedFlowSlug);
 
   const branchLine = git.branch || '[not a git repo or detached HEAD]';
 
@@ -651,9 +735,13 @@ function generateHandoff(projectPath, slug, continuesFrom) {
 
   let chainSection;
   if (prev.exists) {
+    const currentFlowDir = resolvedFlowSlug || '_standalone';
+    const prevFlowDir = prev.flow || '_standalone';
+    const prevPath =
+      prevFlowDir === currentFlowDir ? \`./\${prev.filename}\` : \`../\${prevFlowDir}/\${prev.filename}\`;
     chainSection = \`## Handoff Chain
 
-- **Continues from**: [\${prev.filename}](./\${prev.filename})
+- **Continues from**: [\${prev.filename}](\${prevPath})
   - Previous title: \${prev.title || 'Unknown'}
 - **Supersedes**: [list any older handoffs this replaces, or "None"]
 
@@ -758,39 +846,68 @@ function generateHandoff(projectPath, slug, continuesFrom) {
 \`;
 
   fs.writeFileSync(filepath, content, 'utf-8');
-  return { filepath, filename };
+
+  const compactContent = \`## Handoff: \${slug}
+Branch: \${branchLine} | Created: \${timestamp}
+
+### State
+[TODO: 1-2 sentences — what's happening, where we left off]
+
+### Decisions
+- [TODO: key decisions with rationale]
+
+### Next Steps
+1. [TODO: most critical action]
+2. [TODO: second priority]
+
+### Blockers
+- [TODO: what's blocking progress]
+
+### Assumptions
+- [TODO: assumptions that if wrong, change the approach]\`;
+
+  return { filepath, filename, compactContent };
 }
 
 // --- Main ---
 const args = process.argv.slice(2);
 if (args.includes('--help') || args.includes('-h')) {
-  console.log('Usage: node create_handoff.js [task-slug] [--continues-from <previous>]');
+  console.log('Usage: node create_handoff.js [task-slug] [--continues-from <previous>] [--flow <flow-slug>]');
   console.log('       node create_handoff.js "implementing-auth"');
   console.log('       node create_handoff.js "auth-part-2" --continues-from 2024-01-15-auth.md');
+  console.log('       node create_handoff.js "auth-part-2" --flow add-auth');
   process.exit(0);
 }
 
 let slug = null;
 let continuesFrom = null;
+let flowSlug = null;
 for (let i = 0; i < args.length; i++) {
   if (args[i] === '--continues-from' && i + 1 < args.length) {
     continuesFrom = args[++i];
+  } else if (args[i] === '--flow' && i + 1 < args.length) {
+    flowSlug = sanitizeSlug(args[++i]);
   } else if (!args[i].startsWith('-')) {
     slug = args[i];
   }
 }
 
 const cwd = process.cwd();
-const { filepath } = generateHandoff(cwd, slug, continuesFrom);
+const { filepath, compactContent } = generateHandoff(cwd, slug, continuesFrom, flowSlug);
 console.log(\`Created handoff: \${filepath}\`);
+console.log('\\nCompact flow knowledge entry:');
+console.log('---');
+console.log(compactContent);
+console.log('---');
 console.log(\`\\nNext: Open the file and fill in all [TODO: ...] sections.\`);
 console.log(\`Then validate: node scripts/validate_handoff.js \${filepath}\`);
 `},{file:`scripts/list_handoffs.js`,content:`#!/usr/bin/env node
 /**
  * List available handoff documents in the current project.
  *
- * Searches for handoff documents in .handoffs/ and displays:
+ * Searches for handoff documents in .aikit-state/handoffs/<flow-slug>/ and .aikit-state/handoffs/_standalone/ and displays:
  * - Filename with date
+ * - Flow scope
  * - Title extracted from document
  * - Status (complete / in progress / needs work)
  *
@@ -842,23 +959,50 @@ function parseDateFromFilename(filename) {
 }
 
 function listHandoffs(projectPath) {
-  const dir = path.join(projectPath, '.handoffs');
-  if (!fs.existsSync(dir)) return [];
-
   const handoffs = [];
-  for (const name of fs.readdirSync(dir)) {
-    if (!name.endsWith('.md')) continue;
-    const fp = path.join(dir, name);
-    const stat = fs.statSync(fp);
-
-    handoffs.push({
-      path: fp,
-      filename: name,
-      title: extractTitle(fp),
-      status: checkCompletion(fp),
-      date: parseDateFromFilename(name),
-      size: stat.size,
-    });
+  const baseDir = path.join(projectPath, '.aikit-state', 'handoffs');
+
+  function collectFromDir(dir, flow) {
+    if (!fs.existsSync(dir)) return;
+
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.endsWith('.md')) continue;
+      const fp = path.join(dir, name);
+      const stat = fs.statSync(fp);
+
+      handoffs.push({
+        path: fp,
+        filename: name,
+        flow,
+        title: extractTitle(fp),
+        status: checkCompletion(fp),
+        date: parseDateFromFilename(name),
+        size: stat.size,
+      });
+    }
+  }
+
+  if (fs.existsSync(baseDir)) {
+    const flowDirs = fs
+      .readdirSync(baseDir)
+      .filter((name) => {
+        try {
+          return fs.statSync(path.join(baseDir, name)).isDirectory();
+        } catch {
+          return false;
+        }
+      })
+      .sort((a, b) => {
+        try {
+          return fs.statSync(path.join(baseDir, b)).mtimeMs - fs.statSync(path.join(baseDir, a)).mtimeMs;
+        } catch {
+          return 0;
+        }
+      });
+
+    for (const flow of flowDirs) {
+      collectFromDir(path.join(baseDir, flow), flow === '_standalone' ? null : flow);
+    }
   }
 
   handoffs.sort((a, b) => (b.date || 0) - (a.date || 0));
@@ -882,17 +1026,19 @@ const handoffs = listHandoffs(projectPath);
 
 if (handoffs.length === 0) {
   console.log('No handoff documents found.');
-  console.log(\`Looked in: \${path.join(projectPath, '.handoffs')}\`);
+  console.log(\`Looked in: \${path.join(projectPath, '.aikit-state', 'handoffs', '*')}\`);
+  console.log(\`           \${path.join(projectPath, '.aikit-state', 'handoffs', '_standalone')}\`);
   console.log('\\nCreate one with: node scripts/create_handoff.js [task-slug]');
   process.exit(0);
 }
 
 console.log(\`\\nFound \${handoffs.length} handoff(s) in \${projectPath}:\\n\`);
-console.log(\`\${'Date'.padEnd(18)} \${'Status'.padEnd(25)} Title\`);
-console.log(\`\${'-'.repeat(18)} \${'-'.repeat(25)} \${'-'.repeat(40)}\`);
+console.log(\`\${'Date'.padEnd(18)} \${'Flow'.padEnd(18)} \${'Status'.padEnd(25)} Title\`);
+console.log(\`\${'-'.repeat(18)} \${'-'.repeat(18)} \${'-'.repeat(25)} \${'-'.repeat(40)}\`);
 
 for (const h of handoffs) {
-  console.log(\`\${formatDate(h.date).padEnd(18)} \${h.status.padEnd(25)} \${h.title}\`);
+  const flowLabel = h.flow || '[standalone]';
+  console.log(\`\${formatDate(h.date).padEnd(18)} \${flowLabel.padEnd(18)} \${h.status.padEnd(25)} \${h.title}\`);
 }
 
 if (args.includes('--json')) {
@@ -911,7 +1057,8 @@ if (args.includes('--json')) {
  *
  * Usage:
  *   node validate_handoff.js <handoff-file>
- *   node validate_handoff.js .handoffs/2024-01-15-143022-auth.md
+ *   node validate_handoff.js .aikit-state/handoffs/add-auth/2024-01-15-143022-auth.md
+ *   node validate_handoff.js .aikit-state/handoffs/_standalone/2024-01-15-143022-auth.md
  */
 
 const fs = require('node:fs');
@@ -1039,11 +1186,20 @@ function calculateScore(todosClear, reqComplete, missingReq, missingRec, secrets
   return { score, rating };
 }
 
+function resolveProjectRootFromHandoff(filepath) {
+  const handoffsDir = path.dirname(filepath);
+  const handoffMarkerDir = path.basename(path.dirname(handoffsDir));
+  const stateMarkerDir = path.basename(path.dirname(path.dirname(handoffsDir)));
+  const isFlowScoped = handoffMarkerDir === 'handoffs' && stateMarkerDir === '.aikit-state';
+
+  return isFlowScoped ? path.resolve(handoffsDir, '..', '..', '..') : path.resolve(handoffsDir, '..');
+}
+
 function validateHandoff(filepath) {
   if (!fs.existsSync(filepath)) return { error: \`File not found: \${filepath}\` };
 
   const content = fs.readFileSync(filepath, 'utf-8');
-  const basePath = path.resolve(path.dirname(filepath), '..'); // Up from .handoffs/
+  const basePath = resolveProjectRootFromHandoff(filepath);
 
   const { clear: todosClear, todos } = checkTodos(content);
   const { complete: reqComplete, missing: missingReq } = checkRequiredSections(content);
@@ -1128,7 +1284,8 @@ function printReport(result) {
 const args = process.argv.slice(2);
 if (args.includes('--help') || args.includes('-h') || args.length === 0) {
   console.log('Usage: node validate_handoff.js <handoff-file>');
-  console.log('       node validate_handoff.js .handoffs/2024-01-15-143022-auth.md');
+  console.log('       node validate_handoff.js .aikit-state/handoffs/<flow-slug>/2024-01-15-143022-auth.md');
+  console.log('       node validate_handoff.js .aikit-state/handoffs/_standalone/2024-01-15-143022-auth.md');
   process.exit(args.length === 0 ? 1 : 0);
 }
 
@@ -1147,7 +1304,7 @@ metadata:
   domain: general
   applicability: always
   inputs: [session-state, decisions]
-  outputs: [handoff-document]
+  outputs: [handoff-document, flow-knowledge-entry]
   requires: [aikit]
   relatedSkills: [lesson-learned]
 ---
@@ -1169,7 +1326,23 @@ Determine which mode applies:
 **Proactive suggestion?** After substantial work (5+ file edits, complex debugging, major decisions), suggest:
 > "We've made significant progress. Consider creating a handoff document to preserve this context for future sessions. Say 'create handoff' when ready."
 
-> **aikit Integration:** If the project uses the aikit MCP server, complement file-based handoffs with \`knowledge({ action: "remember", title: "Session checkpoint: ...", content: "...", category: "conventions" })\` to persist key decisions in the AI Kit knowledge store. Use \`search({ query: "SESSION CHECKPOINT" })\` at session start to retrieve past checkpoints.
+> **aikit Integration:** Handoffs use dual storage — file in \`.aikit-state/handoffs/{flow-slug}/\` (gitignored, browsable) + compact knowledge entry (\`knowledge({ scope: "flow" })\`). On resume, \`withdraw\` retrieves the compact version automatically. For full context, read the file from \`.aikit-state/\`.
+
+## Dual Format Storage
+
+Each handoff creates TWO artifacts:
+
+1. **Full document** → \`.aikit-state/handoffs/{flow-slug}/<timestamp>-<slug>.md\`
+  - Complete template with all sections
+  - Browsable on disk but NOT committed to git
+  - Auto-cleaned when \`.aikit-state/\` is cleared
+
+2. **Compact knowledge entry** → \`knowledge({ action: "remember", scope: "flow", category: "session", title: "Session Handoff: <slug>", content: "<compact format>" })\`
+  - ~1-2K chars, optimized for \`withdraw\` retrieval
+  - Contains: State, Decisions, Next Steps, Blockers, Assumptions
+  - Auto-retrieved by resuming agents via \`withdraw({ scope: "flow", profile: "implementer", budget: 6000 })\`
+
+The compact format ensures continuity even if the next session doesn't explicitly load the full handoff file.
 
 ## CREATE Workflow
 
@@ -1179,6 +1352,7 @@ Run the smart scaffold script to create a pre-filled handoff document:
 
 \`\`\`bash
 node scripts/create_handoff.js [task-slug]
+node scripts/create_handoff.js [task-slug] --flow <flow-slug>
 \`\`\`
 
 Example: \`node scripts/create_handoff.js implementing-user-auth\`
@@ -1188,12 +1362,16 @@ Example: \`node scripts/create_handoff.js implementing-user-auth\`
 node scripts/create_handoff.js "auth-part-2" --continues-from 2024-01-15-auth.md
 \`\`\`
 
-The script will:
-- Create \`.handoffs/\` directory if needed
-- Generate timestamped filename
-- Pre-fill: timestamp, project path, git branch, recent commits, modified files
-- Add handoff chain links if continuing from previous
-- Output file path for editing
+The script generates:
+- Full handoff file in \`.aikit-state/handoffs/{active-flow}/\`
+- Compact format string (printed to stdout for pasting into \`knowledge({ action: "remember", ... })\`)
+
+It also:
+- Uses \`--flow\` to override the active flow slug
+- Falls back to \`.aikit-state/handoffs/_standalone/\` when no flow is active
+- Pre-fills: timestamp, project path, git branch, recent commits, modified files
+- Adds handoff chain links if continuing from previous
+- Outputs file path for editing
 
 ### Step 2: Complete the Handoff Document
 
@@ -1264,6 +1442,19 @@ The script checks:
 - Branch divergence
 - Missing referenced files
 
+### Step 2b: Check Flow Knowledge
+
+If a flow is active, check for compact handoffs in flow knowledge:
+\`\`\`
+knowledge({ action: "withdraw", scope: "flow", profile: "implementer", budget: 6000 })
+\`\`\`
+
+If a "Session Handoff:" entry appears but is truncated:
+\`\`\`
+knowledge({ action: "list", category: "session", scope: "flow" })
+knowledge({ action: "read", path: "<handoff-entry>" })
+\`\`\`
+
 ### Step 3: Load the Handoff
 
 Read the relevant handoff document completely before taking any action.
@@ -1317,7 +1508,10 @@ When resuming from a chain, read the most recent handoff first, then reference p
 
 ## Storage Location
 
-Handoffs are stored in: \`.handoffs/\`
+**Primary (flow-scoped):** \`.aikit-state/handoffs/{flow-slug}/\`
+**Standalone fallback:** \`.aikit-state/handoffs/_standalone/\` (when no flow is active)
+
+All handoffs live in \`.aikit-state/\` which is gitignored — handoffs are ephemeral context, not project history.
 
 Naming convention: \`YYYY-MM-DD-HHMMSS-[slug].md\`
 
@@ -1329,7 +1523,7 @@ Example: \`2024-01-15-143022-implementing-auth.md\`
 
 | Script | Purpose |
 |--------|---------|
-| \`create_handoff.js [slug] [--continues-from <file>]\` | Generate new handoff with smart scaffolding |
+| \`create_handoff.js [slug] [--continues-from <file>] [--flow <flow-slug>]\` | Generate new handoff with smart scaffolding |
 | \`list_handoffs.js [path]\` | List available handoffs in a project |
 | \`validate_handoff.js <file>\` | Check completeness, quality, and security |
 | \`check_staleness.js <file>\` | Assess if handoff context is still current |