@assistkick/create 1.0.0

package/templates/product-system/packages/shared/lib/relevance_search.ts

@@ -0,0 +1,159 @@
+/**
+ * Graph-aware relevance search with ranking.
+ *
+ * Algorithm:
+ *   1. Direct matches — keyword substring in node name or body
+ *   2. Graph expansion — 1-hop neighbors of each direct match via edges
+ *   3. Rank by edge type weight — strong architectural signals score higher
+ *   4. Deduplicate — keep highest relevance per node
+ *   5. Cold start fallback — if zero direct matches, return top-5 most-connected per type
+ */
+
+/** Edge types that carry strong architectural signal. */
+const STRONG_EDGES = new Set([
+  'depends_on',
+  'implemented_with',
+  'governed_by',
+  'contains',
+]);
+
+/**
+ * @typedef {Object} RankedResult
+ * @property {string} id
+ * @property {string} name
+ * @property {string} type
+ * @property {string} status
+ * @property {number} completeness
+ * @property {number} open_questions_count
+ * @property {string} relevance - 'direct' | 'via <sourceId> → <edgeType>' description
+ * @property {number} _score - internal sort score (higher = more relevant)
+ */
+
+/**
+ * Run a relevance-ranked search over the graph.
+ *
+ * @param {string} keyword - search term (case-insensitive substring match)
+ * @param {Array} allNodes - full node list from readGraph().nodes
+ * @param {Array} allEdges - full edge list from readGraph().edges
+ * @param {Function} getBody - async (nodeId) => string|null — fetches body content
+ * @returns {Promise<RankedResult[]>} ranked results, direct first then neighbors
+ */
+export const relevanceSearch = async (keyword, allNodes, allEdges, getBody) => {
+  const q = keyword.toLowerCase();
+
+  // --- Step 1: direct matches ---
+  const directMatches = [];
+  for (const n of allNodes) {
+    if (n.name.toLowerCase().includes(q)) {
+      directMatches.push(n);
+      continue;
+    }
+    const body = await getBody(n.id);
+    if (body && body.toLowerCase().includes(q)) {
+      directMatches.push(n);
+    }
+  }
+
+  // --- Cold start fallback ---
+  if (directMatches.length === 0) {
+    return coldStartFallback(allNodes, allEdges);
+  }
+
+  // Build a map for quick lookup
+  const nodeMap = new Map(allNodes.map(n => [n.id, n]));
+  const directIds = new Set(directMatches.map(n => n.id));
+
+  // Results keyed by node id → best RankedResult
+  const resultsMap = new Map();
+
+  // Add direct matches with score 100
+  for (const n of directMatches) {
+    resultsMap.set(n.id, toResult(n, 'direct', 100));
+  }
+
+  // --- Step 2: 1-hop graph expansion ---
+  for (const match of directMatches) {
+    const neighbors = getNeighbors(match.id, allEdges);
+    for (const { nodeId, edgeType, direction } of neighbors) {
+      if (!nodeMap.has(nodeId)) continue;
+      const isStrong = STRONG_EDGES.has(edgeType);
+      const score = isStrong ? 50 : 20;
+      const label = `via ${match.id} ${direction} ${edgeType}`;
+
+      const existing = resultsMap.get(nodeId);
+      if (!existing || existing._score < score) {
+        resultsMap.set(nodeId, toResult(nodeMap.get(nodeId), label, score));
+      }
+    }
+  }
+
+  // --- Step 3: sort by score descending, then by id for stability ---
+  const results = [...resultsMap.values()];
+  results.sort((a, b) => b._score - a._score || a.id.localeCompare(b.id));
+
+  return results;
+};
+
+/**
+ * Cold start fallback: return top 5 most-connected nodes per type as structural overview.
+ */
+export const coldStartFallback = (allNodes, allEdges) => {
+  // Count edges per node
+  const edgeCounts = new Map();
+  for (const e of allEdges) {
+    edgeCounts.set(e.from, (edgeCounts.get(e.from) || 0) + 1);
+    edgeCounts.set(e.to, (edgeCounts.get(e.to) || 0) + 1);
+  }
+
+  // Group by type
+  const byType = new Map();
+  for (const n of allNodes) {
+    if (!byType.has(n.type)) byType.set(n.type, []);
+    byType.get(n.type).push(n);
+  }
+
+  const results = [];
+  for (const [type, typeNodes] of byType) {
+    // Sort by edge count descending
+    typeNodes.sort((a, b) => (edgeCounts.get(b.id) || 0) - (edgeCounts.get(a.id) || 0));
+    const top5 = typeNodes.slice(0, 5);
+    for (const n of top5) {
+      const count = edgeCounts.get(n.id) || 0;
+      results.push(toResult(n, `structural overview (${count} connections)`, count));
+    }
+  }
+
+  // Sort by edge count descending overall, then by id
+  results.sort((a, b) => b._score - a._score || a.id.localeCompare(b.id));
+  return results;
+};
+
+/**
+ * Get 1-hop neighbors of a node from the edge list.
+ * Returns both outbound (node → neighbor) and inbound (neighbor → node).
+ */
+const getNeighbors = (nodeId, edges) => {
+  const neighbors = [];
+  for (const e of edges) {
+    if (e.from === nodeId) {
+      neighbors.push({ nodeId: e.to, edgeType: e.relation, direction: '→' });
+    } else if (e.to === nodeId) {
+      neighbors.push({ nodeId: e.from, edgeType: e.relation, direction: '←' });
+    }
+  }
+  return neighbors;
+};
+
+/**
+ * Create a ranked result object from a node.
+ */
+const toResult = (node, relevance, score) => ({
+  id: node.id,
+  name: node.name,
+  type: node.type,
+  status: node.status,
+  completeness: node.completeness,
+  open_questions_count: node.open_questions_count,
+  relevance,
+  _score: score,
+});

package/templates/product-system/packages/shared/lib/session.ts

@@ -0,0 +1,152 @@
+/**
+ * Session operations backed by Drizzle/Turso.
+ * Replaces direct session file I/O in tools.
+ */
+
+import { eq, desc, max, isNotNull, gte, and } from 'drizzle-orm';
+import { getDb } from './db.js';
+import { sessions, nodes } from '../db/schema.js';
+
+/**
+ * Get the next session number (max existing + 1).
+ */
+export const getNextSessionNumber = async (projectId?: string) => {
+  const db = getDb();
+  const query = projectId
+    ? db.select({ maxNum: max(sessions.sessionNumber) }).from(sessions).where(eq(sessions.projectId, projectId))
+    : db.select({ maxNum: max(sessions.sessionNumber) }).from(sessions);
+  const rows = await query;
+  return (rows[0]?.maxNum || 0) + 1;
+};
+
+/**
+ * Create a new session record.
+ */
+export const createSession = async (sessionNum, body, projectId?: string) => {
+  const db = getDb();
+  const now = new Date().toISOString();
+
+  await db.insert(sessions).values({
+    sessionNumber: sessionNum,
+    startedAt: now,
+    endedAt: null,
+    summary: null,
+    nodesTouched: '[]',
+    questionsResolved: 0,
+    body: body || '',
+    projectId: projectId || null,
+  });
+
+  return { session: sessionNum, started_at: now };
+};
+
+/**
+ * Get the latest (most recent) session.
+ */
+export const getLatestSession = async (projectId?: string) => {
+  const db = getDb();
+  const query = projectId
+    ? db.select().from(sessions).where(eq(sessions.projectId, projectId)).orderBy(desc(sessions.sessionNumber)).limit(1)
+    : db.select().from(sessions).orderBy(desc(sessions.sessionNumber)).limit(1);
+  const rows = await query;
+  return rows[0];
+};
+
+/**
+ * Update/end a session with summary and metadata.
+ */
+export const endSession = async (sessionNum, updates) => {
+  const db = getDb();
+
+  const updateFields = {};
+  if (updates.ended_at) updateFields.endedAt = updates.ended_at;
+  if (updates.summary) updateFields.summary = updates.summary;
+  if (updates.nodes_touched) updateFields.nodesTouched = JSON.stringify(updates.nodes_touched);
+  if (updates.questions_resolved !== undefined) updateFields.questionsResolved = updates.questions_resolved;
+  if (updates.body !== undefined) updateFields.body = updates.body;
+
+  await db.update(sessions).set(updateFields).where(eq(sessions.sessionNumber, sessionNum));
+};
+
+/**
+ * Get a session by number.
+ */
+export const getSession = async (sessionNum) => {
+  const db = getDb();
+  const rows = await db.select().from(sessions).where(eq(sessions.sessionNumber, sessionNum));
+  return rows[0];
+};
+
+/**
+ * Get the last N ended sessions (most recent first).
+ */
+export const getRecentSessions = async (count = 3, projectId?: string) => {
+  const db = getDb();
+  const conditions = [isNotNull(sessions.endedAt)];
+  if (projectId) conditions.push(eq(sessions.projectId, projectId));
+  const rows = await db.select()
+    .from(sessions)
+    .where(and(...conditions))
+    .orderBy(desc(sessions.sessionNumber))
+    .limit(count);
+  return rows;
+};
+
+/**
+ * Get the N most recently modified nodes (by updated_at).
+ */
+export const getRecentlyModifiedNodes = async (count = 10, projectId?: string) => {
+  const db = getDb();
+  const query = projectId
+    ? db.select({
+        id: nodes.id,
+        name: nodes.name,
+        type: nodes.type,
+        status: nodes.status,
+        completeness: nodes.completeness,
+        updatedAt: nodes.updatedAt,
+      })
+        .from(nodes)
+        .where(eq(nodes.projectId, projectId))
+        .orderBy(desc(nodes.updatedAt))
+        .limit(count)
+    : db.select({
+        id: nodes.id,
+        name: nodes.name,
+        type: nodes.type,
+        status: nodes.status,
+        completeness: nodes.completeness,
+        updatedAt: nodes.updatedAt,
+      })
+        .from(nodes)
+        .orderBy(desc(nodes.updatedAt))
+        .limit(count);
+  const rows = await query;
+  return rows;
+};
+
+/**
+ * Get decision nodes updated within the timeframe of recent sessions.
+ * Uses the earliest startedAt from recentSessions as the cutoff.
+ */
+export const getRecentDecisions = async (recentSessions) => {
+  if (!recentSessions || recentSessions.length === 0) return [];
+
+  const earliest = recentSessions[recentSessions.length - 1].startedAt;
+  const db = getDb();
+  const rows = await db.select({
+    id: nodes.id,
+    name: nodes.name,
+    status: nodes.status,
+    body: nodes.body,
+    updatedAt: nodes.updatedAt,
+  })
+    .from(nodes)
+    .where(
+      eq(nodes.type, 'decision'),
+    )
+    .orderBy(desc(nodes.updatedAt));
+
+  // Filter in JS since drizzle-orm sqlite doesn't support combined where with gte on text dates reliably
+  return rows.filter(r => r.updatedAt >= earliest);
+};

package/templates/product-system/packages/shared/lib/validator.ts

@@ -0,0 +1,117 @@
+/**
+ * Invariant checks for the interview system knowledge graph.
+ * All assertion functions throw on failure.
+ * Backed by Drizzle/Turso queries.
+ */
+
+import { eq, and } from 'drizzle-orm';
+import { NODE_TYPES, VALID_RELATIONS } from './constants.js';
+import { getDb } from './db.js';
+import { nodes, edges } from '../db/schema.js';
+
+/**
+ * Assert that a node with the given ID exists in the database.
+ */
+export const assertNodeExists = async (id) => {
+  const db = getDb();
+  const rows = await db.select({ id: nodes.id }).from(nodes).where(eq(nodes.id, id));
+  if (!rows[0]) {
+    throw new Error(`Node does not exist: ${id}`);
+  }
+};
+
+/**
+ * Assert that a type string is a valid node type.
+ */
+export const assertValidType = (type) => {
+  if (!NODE_TYPES[type]) {
+    const valid = Object.keys(NODE_TYPES).join(', ');
+    throw new Error(`Invalid node type "${type}". Valid types: ${valid}`);
+  }
+};
+
+/**
+ * Assert that a relation string is a valid edge relation.
+ */
+export const assertValidRelation = (relation) => {
+  if (!VALID_RELATIONS.includes(relation)) {
+    throw new Error(
+      `Invalid relation "${relation}". Valid relations: ${VALID_RELATIONS.join(', ')}`
+    );
+  }
+};
+
+/**
+ * Assert that an edge doesn't already exist in the database.
+ */
+export const assertNoDuplicateEdge = async (from, relation, to) => {
+  const db = getDb();
+  const rows = await db.select().from(edges).where(
+    and(
+      eq(edges.fromId, from),
+      eq(edges.relation, relation),
+      eq(edges.toId, to),
+    )
+  );
+  if (rows[0]) {
+    throw new Error(`Duplicate edge: ${from} --${relation}--> ${to}`);
+  }
+};
+
+/**
+ * Assert that adding a depends_on edge from → to won't create a cycle.
+ * Uses BFS from `to` following depends_on edges to check if `from` is reachable.
+ */
+export const assertNoCycle = async (from, to, projectId?: string) => {
+  const db = getDb();
+
+  // Get all depends_on edges
+  const conditions = [eq(edges.relation, 'depends_on')];
+  if (projectId) conditions.push(eq(edges.projectId, projectId));
+  const depEdges = await db.select().from(edges).where(and(...conditions));
+
+  // Build adjacency list
+  const adj = new Map();
+  for (const edge of depEdges) {
+    if (!adj.has(edge.fromId)) adj.set(edge.fromId, []);
+    adj.get(edge.fromId).push(edge.toId);
+  }
+
+  // BFS from `to` — if we can reach `from`, adding from→to creates a cycle
+  const visited = new Set();
+  const queue = [to];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === from) {
+      throw new Error(
+        `Cycle detected: adding ${from} --depends_on--> ${to} would create a circular dependency`
+      );
+    }
+    if (visited.has(current)) continue;
+    visited.add(current);
+
+    const neighbors = adj.get(current) || [];
+    for (const neighbor of neighbors) {
+      if (!visited.has(neighbor)) {
+        queue.push(neighbor);
+      }
+    }
+  }
+};
+
+/**
+ * Assert that no other node of the same type has the same name.
+ */
+export const assertUniqueName = async (type, name, projectId?: string) => {
+  const db = getDb();
+  const conditions = [eq(nodes.type, type)];
+  if (projectId) conditions.push(eq(nodes.projectId, projectId));
+  const allOfType = await db.select().from(nodes).where(and(...conditions));
+  const duplicate = allOfType.find(n => n.name.toLowerCase() === name.toLowerCase());
+  if (duplicate) {
+    throw new Error(
+      `A ${type} node named "${name}" already exists (${duplicate.id})`
+    );
+  }
+};

package/templates/product-system/packages/shared/lib/work_summary_parser.ts

@@ -0,0 +1,130 @@
+/**
+ * WorkSummaryParser — extracts structured work summary blocks from
+ * developer Claude output and git diff --name-status output.
+ */
+
+export interface WorkSummary {
+  cycle: number;
+  filesCreated: string[];
+  filesUpdated: string[];
+  filesDeleted: string[];
+  approach: string;
+  decisions: string[];
+  timestamp: string;
+}
+
+const SUMMARY_START = '## Work Summary';
+const APPROACH_HEADER = '### Approach';
+const DECISIONS_HEADER = '### Decisions';
+
+export class WorkSummaryParser {
+  /**
+   * Parse the structured work summary block from developer Claude's output.
+   * Expected format:
+   *   ## Work Summary
+   *   ### Approach
+   *   <paragraph>
+   *   ### Decisions
+   *   - <decision 1>
+   *   - <decision 2>
+   */
+  parseFromOutput = (output: string): { approach: string; decisions: string[] } => {
+    const summaryIdx = output.indexOf(SUMMARY_START);
+    if (summaryIdx === -1) {
+      return { approach: '', decisions: [] };
+    }
+
+    const summaryBlock = output.slice(summaryIdx + SUMMARY_START.length);
+
+    // Extract approach
+    const approachIdx = summaryBlock.indexOf(APPROACH_HEADER);
+    const decisionsIdx = summaryBlock.indexOf(DECISIONS_HEADER);
+
+    let approach = '';
+    if (approachIdx !== -1) {
+      const approachStart = approachIdx + APPROACH_HEADER.length;
+      const approachEnd = decisionsIdx !== -1 ? decisionsIdx : summaryBlock.length;
+      approach = summaryBlock.slice(approachStart, approachEnd).trim();
+    }
+
+    // Extract decisions
+    const decisions: string[] = [];
+    if (decisionsIdx !== -1) {
+      const decisionsBlock = summaryBlock.slice(decisionsIdx + DECISIONS_HEADER.length);
+      // Stop at the next ## heading or end of text
+      const nextHeadingIdx = decisionsBlock.indexOf('\n## ');
+      const decisionsText = nextHeadingIdx !== -1
+        ? decisionsBlock.slice(0, nextHeadingIdx)
+        : decisionsBlock;
+
+      for (const line of decisionsText.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('- ') || trimmed.startsWith('* ')) {
+          decisions.push(trimmed.slice(2).trim());
+        }
+      }
+    }
+
+    return { approach, decisions };
+  };
+
+  /**
+   * Parse git diff --name-status output into categorized file lists.
+   * Each line has a status letter (A/M/D) followed by a tab and the file path.
+   * Example input:
+   *   A\tsrc/new_file.ts
+   *   M\tsrc/existing.ts
+   *   D\tsrc/removed.ts
+   */
+  parseDiffNameStatus = (diffOutput: string): { filesCreated: string[]; filesUpdated: string[]; filesDeleted: string[] } => {
+    const filesCreated: string[] = [];
+    const filesUpdated: string[] = [];
+    const filesDeleted: string[] = [];
+
+    if (!diffOutput.trim()) {
+      return { filesCreated, filesUpdated, filesDeleted };
+    }
+
+    for (const line of diffOutput.trim().split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+
+      const status = trimmed[0];
+      const filePath = trimmed.slice(1).trim();
+      if (!filePath) continue;
+
+      switch (status) {
+        case 'A':
+          filesCreated.push(filePath);
+          break;
+        case 'D':
+          filesDeleted.push(filePath);
+          break;
+        case 'M':
+        default:
+          filesUpdated.push(filePath);
+          break;
+      }
+    }
+
+    return { filesCreated, filesUpdated, filesDeleted };
+  };
+
+  /**
+   * Build a complete WorkSummary from cycle info, git diff --name-status, and Claude output.
+   */
+  buildSummary = (cycle: number, diffNameStatusOutput: string, claudeOutput: string): WorkSummary => {
+    const { filesCreated, filesUpdated, filesDeleted } = this.parseDiffNameStatus(diffNameStatusOutput);
+    const { approach, decisions } = this.parseFromOutput(claudeOutput);
+
+    return {
+      cycle,
+      filesCreated,
+      filesUpdated,
+      filesDeleted,
+      approach: approach || 'No approach narrative provided.',
+      decisions,
+      timestamp: new Date().toISOString(),
+    };
+  };
+}

package/templates/product-system/packages/shared/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@interview-system/shared",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.ts",
+  "scripts": {
+    "build": "echo 'Shared runs via tsx — no build step needed'",
+    "clean": "echo 'No build artifacts'",
+    "db:migrate": "tsx db/migrate.ts",
+    "db:rollback": "drizzle-kit rollback",
+    "db:generate": "drizzle-kit generate",
+    "db:assign-project": "npx tsx scripts/assign-project.ts --"
+  },
+  "dependencies": {
+    "@libsql/client": "^0.17.0",
+    "chalk": "^5.3.0",
+    "commander": "^11.0.0",
+    "dotenv": "^17.3.1",
+    "drizzle-orm": "^0.45.1",
+    "glob": "11.1.0",
+    "gray-matter": "^4.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "drizzle-kit": "^0.31.9",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/product-system/packages/shared/scripts/assign-project.ts

@@ -0,0 +1,52 @@
+/**
+ * Assign all rows with NULL project_id to a given project.
+ * Usage: npx tsx scripts/assign-project.ts <project_id>
+ * Example: npx tsx scripts/assign-project.ts proj_bcb96324
+ */
+import { config } from 'dotenv';
+config({ path: '../../.env' });
+
+import { createClient } from '@libsql/client';
+
+const TABLES = [
+  'nodes',
+  'edges',
+  'kanban',
+  'coherence_reviews',
+  'pipeline_state',
+  'review_meta',
+  'sessions',
+];
+
+const projectId = process.argv[2];
+if (!projectId) {
+  console.error('Usage: npx tsx scripts/assign-project.ts <project_id>');
+  process.exit(1);
+}
+
+async function main() {
+  const client = createClient({
+    url: process.env.TURSO_DATABASE_URL!,
+    authToken: process.env.TURSO_AUTH_TOKEN!,
+  });
+
+  console.log(`Assigning unassigned rows to project: ${projectId}\n`);
+
+  let total = 0;
+  for (const table of TABLES) {
+    const result = await client.execute({
+      sql: `UPDATE ${table} SET project_id = ? WHERE project_id IS NULL`,
+      args: [projectId],
+    });
+    console.log(`  ${table}: ${result.rowsAffected} rows`);
+    total += result.rowsAffected;
+  }
+
+  client.close();
+  console.log(`\nDone — ${total} total rows assigned.`);
+}
+
+main().catch((err) => {
+  console.error('Failed:', err);
+  process.exit(1);
+});

package/templates/product-system/packages/shared/tools/add_edge.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+/**
+ * add_edge — Creates a typed relationship between two nodes.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { readGraph, addEdge as graphAddEdge } from '../lib/graph.js';
+import { readNode, writeNode, appendToSection } from '../lib/markdown.js';
+import {
+  assertNodeExists,
+  assertValidRelation,
+  assertNoDuplicateEdge,
+  assertNoCycle,
+} from '../lib/validator.js';
+
+program
+  .argument('<from>', 'Source node ID')
+  .argument('<relation>', 'Relation type')
+  .argument('<to>', 'Target node ID')
+  .requiredOption('--project-id <id>', 'Project ID')
+  .parse();
+
+const [from, relation, to] = program.args;
+const opts = program.opts();
+
+(async () => {
+  try {
+    await assertNodeExists(from);
+    await assertNodeExists(to);
+    assertValidRelation(relation);
+    await assertNoDuplicateEdge(from, relation, to);
+
+    if (relation === 'depends_on') {
+      await assertNoCycle(from, to, opts.projectId);
+    }
+
+    // Add edge to DB
+    await graphAddEdge(from, relation, to, opts.projectId);
+
+    // Append relation references to both nodes' body content
+    const graph = await readGraph();
+    const fromNode = graph.nodes.find(n => n.id === from);
+    const toNode = graph.nodes.find(n => n.id === to);
+
+    const fromData = await readNode(from);
+    appendToSection(fromData.sections, 'Relations', `- ${relation} → ${to} (${toNode.name})`);
+    await writeNode(from, fromData.frontmatter, fromData.sections);
+
+    const toData = await readNode(to);
+    appendToSection(toData.sections, 'Relations', `- ${relation} ← ${from} (${fromNode.name})`);
+    await writeNode(to, toData.frontmatter, toData.sections);
+
+    console.log(chalk.green(`✓ Added edge: ${from} --${relation}--> ${to}`));
+    console.log(JSON.stringify({ from, relation, to }));
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();