@assistkick/create 1.0.0

package/templates/product-system/packages/shared/db/migrations/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1772730355833,
+      "tag": "0000_dashing_gorgon",
+      "breakpoints": true
+    }
+  ]
+}

package/templates/product-system/packages/shared/db/schema.ts

@@ -0,0 +1,137 @@
+import { sqliteTable, text, real, integer, primaryKey } from 'drizzle-orm/sqlite-core';
+
+// --- nodes table ---
+export const nodes = sqliteTable('nodes', {
+  id: text('id').primaryKey(),
+  type: text('type').notNull(),
+  name: text('name').notNull(),
+  status: text('status').notNull(),
+  priority: text('priority').notNull(),
+  completeness: real('completeness').notNull().default(0),
+  openQuestionsCount: integer('open_questions_count').notNull().default(0),
+  kind: text('kind'),
+  createdAt: text('created_at').notNull(),
+  updatedAt: text('updated_at').notNull(),
+  body: text('body'),
+  projectId: text('project_id'),
+});
+
+// --- edges table ---
+export const edges = sqliteTable('edges', {
+  fromId: text('from_id').notNull(),
+  relation: text('relation').notNull(),
+  toId: text('to_id').notNull(),
+  projectId: text('project_id'),
+}, (table) => [
+  primaryKey({ columns: [table.fromId, table.relation, table.toId] }),
+]);
+
+// --- kanban table ---
+export const kanban = sqliteTable('kanban', {
+  nodeId: text('node_id').primaryKey().references(() => nodes.id),
+  columnName: text('column_name').notNull(),
+  position: integer('position').notNull(),
+  projectId: text('project_id'),
+});
+
+// --- sessions table ---
+export const sessions = sqliteTable('sessions', {
+  sessionNumber: integer('session_number').primaryKey(),
+  startedAt: text('started_at').notNull(),
+  endedAt: text('ended_at'),
+  summary: text('summary'),
+  nodesTouched: text('nodes_touched'),
+  questionsResolved: integer('questions_resolved').notNull().default(0),
+  body: text('body'),
+  projectId: text('project_id'),
+});
+
+// --- coherence_reviews table ---
+export const coherenceReviews = sqliteTable('coherence_reviews', {
+  id: text('id').primaryKey(),
+  type: text('type').notNull(),             // add_edge, add_node, remove_edge, deprecate_node, update_description
+  fromId: text('from_id'),
+  toId: text('to_id'),
+  relation: text('relation'),
+  proposedNodeType: text('proposed_node_type'),
+  proposedNodeName: text('proposed_node_name'),
+  targetNodeId: text('target_node_id'),      // for deprecate_node and update_description
+  proposedDescription: text('proposed_description'), // for update_description
+  confidence: text('confidence'),            // high, medium, low
+  batchId: text('batch_id'),                 // groups related proposals
+  reasoning: text('reasoning').notNull(),
+  status: text('status').notNull(),
+  createdAt: text('created_at').notNull(),
+  resolvedAt: text('resolved_at'),
+  projectId: text('project_id'),
+});
+
+// --- review_meta table ---
+export const reviewMeta = sqliteTable('review_meta', {
+  key: text('key').primaryKey(),
+  value: text('value').notNull(),
+  projectId: text('project_id'),
+});
+
+// --- users table ---
+export const users = sqliteTable('users', {
+  id: text('id').primaryKey(),
+  email: text('email').notNull().unique(),
+  passwordHash: text('password_hash').notNull(),
+  role: text('role').notNull().default('user'),
+  createdAt: text('created_at').notNull(),
+  updatedAt: text('updated_at').notNull(),
+});
+
+// --- refresh_tokens table ---
+export const refreshTokens = sqliteTable('refresh_tokens', {
+  id: text('id').primaryKey(),
+  userId: text('user_id').notNull().references(() => users.id),
+  tokenHash: text('token_hash').notNull(),
+  expiresAt: text('expires_at').notNull(),
+  createdAt: text('created_at').notNull(),
+});
+
+// --- password_reset_tokens table ---
+export const passwordResetTokens = sqliteTable('password_reset_tokens', {
+  id: text('id').primaryKey(),
+  userId: text('user_id').notNull().references(() => users.id),
+  tokenHash: text('token_hash').notNull(),
+  expiresAt: text('expires_at').notNull(),
+  createdAt: text('created_at').notNull(),
+  usedAt: text('used_at'),
+});
+
+// --- invitations table ---
+export const invitations = sqliteTable('invitations', {
+  id: text('id').primaryKey(),
+  email: text('email').notNull(),
+  tokenHash: text('token_hash').notNull(),
+  invitedBy: text('invited_by').notNull().references(() => users.id),
+  expiresAt: text('expires_at').notNull(),
+  acceptedAt: text('accepted_at'),
+  createdAt: text('created_at').notNull(),
+});
+
+// --- projects table ---
+export const projects = sqliteTable('projects', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  isDefault: integer('is_default').notNull().default(0),
+  archivedAt: text('archived_at'),
+  createdAt: text('created_at').notNull(),
+  updatedAt: text('updated_at').notNull(),
+});
+
+// --- pipeline_state table ---
+export const pipelineState = sqliteTable('pipeline_state', {
+  featureId: text('feature_id').primaryKey(),
+  status: text('status').notNull(),
+  cycle: integer('cycle').notNull().default(1),
+  tasksJson: text('tasks_json'),
+  toolCallsJson: text('tool_calls_json'),
+  workSummariesJson: text('work_summaries_json'),
+  error: text('error'),
+  updatedAt: text('updated_at').notNull(),
+  projectId: text('project_id'),
+});

package/templates/product-system/packages/shared/drizzle.config.js

@@ -0,0 +1,14 @@
+import { defineConfig } from 'drizzle-kit';
+import { config } from 'dotenv';
+
+config({ path: '../../.env' });
+
+export default defineConfig({
+  schema: './db/schema.ts',
+  out: './db/migrations',
+  dialect: 'turso',
+  dbCredentials: {
+    url: process.env.TURSO_DATABASE_URL,
+    authToken: process.env.TURSO_AUTH_TOKEN,
+  },
+});

package/templates/product-system/packages/shared/lib/claude-service.ts

@@ -0,0 +1,215 @@
+/**
+ * Claude CLI Invocation Service.
+ * Encapsulates all Claude subprocess spawning and stream-json parsing.
+ * This is the mockable boundary for testing pipeline logic.
+ */
+
+import { spawn } from 'node:child_process';
+
+/**
+ * Generic subprocess helper.
+ * @param {string} cmd - command to run
+ * @param {string[]} args - command arguments
+ * @param {string} cwd - working directory
+ * @param {function} log - logging function
+ * @returns {Promise<string>} stdout
+ */
+const spawnCommand = (cmd, args, cwd, log) => new Promise((resolve, reject) => {
+  const cmdStr = `${cmd} ${args.join(' ')}`;
+  log('SPAWN', `Running: ${cmdStr} (cwd: ${cwd})`);
+  const child = spawn(cmd, args, { cwd, env: process.env, stdio: ['pipe', 'pipe', 'pipe'] });
+  let stdout = '';
+  let stderr = '';
+  child.stdout.on('data', d => { stdout += d; });
+  child.stderr.on('data', d => { stderr += d; });
+  child.on('close', code => {
+    if (code === 0) {
+      log('SPAWN', `OK: ${cmdStr} (stdout: ${stdout.slice(0, 200).trim()})`);
+      resolve(stdout);
+    } else {
+      log('SPAWN', `FAIL: ${cmdStr} exit=${code} stderr=${stderr.slice(0, 300).trim()}`);
+      reject(new Error(`${cmd} exited with code ${code}: ${stderr}`));
+    }
+  });
+  child.on('error', (err) => {
+    log('SPAWN', `ERROR: ${cmdStr} — ${err.message}`);
+    reject(err);
+  });
+});
+
+/**
+ * Parse a stream-json line and log tool/text activity for verbose mode.
+ */
+const formatStreamEvent = (jsonStr, tag) => {
+  try {
+    const event = JSON.parse(jsonStr);
+
+    if (event.type === 'assistant' && event.message?.content) {
+      for (const block of event.message.content) {
+        if (block.type === 'text' && block.text) {
+          const preview = block.text.slice(0, 200).replace(/\n/g, '\\n');
+          process.stdout.write(`  [${tag}] 💬 ${preview}${block.text.length > 200 ? '...' : ''}\n`);
+        }
+        if (block.type === 'tool_use') {
+          const name = block.name || 'unknown';
+          const input = block.input || {};
+          if (name === 'Read' || name === 'Glob') {
+            process.stdout.write(`  [${tag}] 📖 ${name}: ${input.file_path || input.pattern || ''}\n`);
+          } else if (name === 'Edit') {
+            process.stdout.write(`  [${tag}] ✏️  Edit: ${input.file_path || ''}\n`);
+          } else if (name === 'Write') {
+            process.stdout.write(`  [${tag}] 📝 Write: ${input.file_path || ''}\n`);
+          } else if (name === 'Bash') {
+            const cmd = (input.command || '').slice(0, 120);
+            process.stdout.write(`  [${tag}] 🔧 Bash: ${cmd}${(input.command || '').length > 120 ? '...' : ''}\n`);
+          } else if (name === 'Grep') {
+            process.stdout.write(`  [${tag}] 🔍 Grep: "${input.pattern || ''}" ${input.path || ''}\n`);
+          } else if (name === 'Task') {
+            process.stdout.write(`  [${tag}] 🤖 Task: ${input.description || input.prompt?.slice(0, 80) || ''}\n`);
+          } else {
+            process.stdout.write(`  [${tag}] 🔧 ${name}\n`);
+          }
+        }
+      }
+    }
+
+    if (event.type === 'result') {
+      const cost = event.cost_usd != null ? ` ($${event.cost_usd.toFixed(4)})` : '';
+      const duration = event.duration_ms != null ? ` ${(event.duration_ms / 1000).toFixed(1)}s` : '';
+      process.stdout.write(`  [${tag}] ✅ Done${duration}${cost}\n`);
+    }
+  } catch {
+    // Not valid JSON — skip silently
+  }
+};
+
+/**
+ * Extract the final text result from stream-json output.
+ */
+const extractResultText = (raw) => {
+  const lines = raw.split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    try {
+      const event = JSON.parse(line);
+      if (event.type === 'result' && event.result != null) {
+        return event.result;
+      }
+    } catch { /* skip */ }
+  }
+  let text = '';
+  for (const line of lines) {
+    try {
+      const event = JSON.parse(line.trim());
+      if (event.type === 'assistant' && event.message?.content) {
+        for (const block of event.message.content) {
+          if (block.type === 'text') text += block.text;
+        }
+      }
+    } catch { /* skip */ }
+  }
+  return text;
+};
+
+/**
+ * Extract tool_use events from a stream-json line and invoke a callback.
+ * Only fires for tool_use blocks found in assistant messages.
+ */
+export const emitToolUseEvents = (jsonStr, callback) => {
+  try {
+    const event = JSON.parse(jsonStr);
+    if (event.type === 'assistant' && event.message?.content) {
+      for (const block of event.message.content) {
+        if (block.type === 'tool_use') {
+          callback(block.name || 'unknown', block.input || {});
+        }
+      }
+    }
+  } catch {
+    // Not valid JSON — skip silently
+  }
+};
+
+/**
+ * Create a Claude CLI invocation service.
+ * @param {{ verbose: boolean, log: function }} opts
+ * @returns {{ spawnClaude: function, spawnCommand: function }}
+ */
+export const createClaudeService = ({ verbose = false, log: logFn }) => {
+  const spawnClaude = (prompt, cwd, label = 'claude', { onToolUse } = {}) => new Promise((resolve, reject) => {
+    const promptPreview = prompt.slice(0, 100).replace(/\n/g, '\\n');
+    logFn('CLAUDE', `Spawning ${label} in ${cwd} — prompt length: ${prompt.length} chars`);
+    logFn('CLAUDE', `Prompt preview: "${promptPreview}..."`);
+
+    const claudeArgs = ['--dangerously-skip-permissions', '-p', '-'];
+    if (verbose) {
+      claudeArgs.push('--verbose', '--output-format', 'stream-json');
+    }
+
+    const child = spawn('claude', claudeArgs, {
+      cwd,
+      env: process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    let lineBuf = '';
+
+    const tag = `${label.toUpperCase()}`;
+
+    child.stdout.on('data', d => {
+      const chunk = d.toString();
+      stdout += chunk;
+      if (verbose) {
+        lineBuf += chunk;
+        const lines = lineBuf.split('\n');
+        lineBuf = lines.pop();
+        for (const line of lines) {
+          if (line.trim()) {
+            formatStreamEvent(line.trim(), tag);
+            if (onToolUse) emitToolUseEvents(line.trim(), onToolUse);
+          }
+        }
+      }
+    });
+
+    child.stderr.on('data', d => {
+      const chunk = d.toString();
+      stderr += chunk;
+      if (verbose) {
+        chunk.split('\n').forEach(line => {
+          if (line.trim()) process.stderr.write(`  [${tag}:err] ${line}\n`);
+        });
+      }
+    });
+
+    child.stdin.write(prompt);
+    child.stdin.end();
+    logFn('CLAUDE', `Prompt written to stdin, waiting for ${label} to complete...`);
+
+    child.on('close', code => {
+      if (verbose && lineBuf.trim()) {
+        formatStreamEvent(lineBuf.trim(), tag);
+        if (onToolUse) emitToolUseEvents(lineBuf.trim(), onToolUse);
+      }
+      if (code === 0) {
+        const result = verbose ? extractResultText(stdout) : stdout;
+        logFn('CLAUDE', `${label} OK — result length: ${result.length} chars`);
+        resolve(result);
+      } else {
+        logFn('CLAUDE', `${label} FAIL exit=${code} stderr=${stderr.slice(0, 500).trim()}`);
+        reject(new Error(`claude exited with code ${code}: ${stderr}`));
+      }
+    });
+    child.on('error', (err) => {
+      logFn('CLAUDE', `${label} ERROR: ${err.message}`);
+      reject(err);
+    });
+  });
+
+  return {
+    spawnClaude,
+    spawnCommand: (cmd, args, cwd) => spawnCommand(cmd, args, cwd, logFn),
+  };
+};

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

@@ -0,0 +1,278 @@
+/**
+ * Coherence review operations backed by Drizzle/Turso.
+ * Supports 5 proposal types: add_edge, add_node, remove_edge, deprecate_node, update_description.
+ */
+
+import { eq } from 'drizzle-orm';
+import { getDb } from './db.js';
+import { coherenceReviews, reviewMeta } from '../db/schema.js';
+
+const META_KEY = 'coherence:state';
+
+/**
+ * Valid proposal types ordered by processing priority.
+ * remove actions first (cascading), then updates, then additions.
+ */
+export const PROPOSAL_TYPE_ORDER = [
+  'deprecate_node',
+  'remove_edge',
+  'update_description',
+  'add_edge',
+  'add_node',
+];
+
+/**
+ * Map a DB row to the API proposal shape.
+ */
+const rowToProposal = (r) => ({
+  id: r.id,
+  type: r.type,
+  ...(r.fromId ? { from_id: r.fromId } : {}),
+  ...(r.toId ? { to_id: r.toId } : {}),
+  ...(r.relation ? { relation: r.relation } : {}),
+  ...(r.proposedNodeType ? { proposed_node_type: r.proposedNodeType } : {}),
+  ...(r.proposedNodeName ? { proposed_node_name: r.proposedNodeName } : {}),
+  ...(r.targetNodeId ? { target_node_id: r.targetNodeId } : {}),
+  ...(r.proposedDescription ? { proposed_description: r.proposedDescription } : {}),
+  ...(r.confidence ? { confidence: r.confidence } : {}),
+  ...(r.batchId ? { batch_id: r.batchId } : {}),
+  reasoning: r.reasoning,
+  status: r.status,
+  created_at: r.createdAt,
+  resolved_at: r.resolvedAt,
+});
+
+/**
+ * Read coherence review state and proposals from the database.
+ * Returns: { last_review_timestamp, review_status, partial_run, proposals[] }
+ */
+export const loadCoherence = async (projectId?: string) => {
+  const db = getDb();
+
+  const metaKey = projectId ? `${META_KEY}:${projectId}` : META_KEY;
+  const metaRows = await db.select().from(reviewMeta)
+    .where(eq(reviewMeta.key, metaKey));
+  const meta = metaRows[0]
+    ? JSON.parse(metaRows[0].value)
+    : { last_review_timestamp: null, review_status: 'idle', partial_run: false };
+
+  const rows = projectId
+    ? await db.select().from(coherenceReviews).where(eq(coherenceReviews.projectId, projectId))
+    : await db.select().from(coherenceReviews);
+  const proposals = rows.map(rowToProposal);
+
+  return {
+    last_review_timestamp: meta.last_review_timestamp,
+    review_status: meta.review_status,
+    partial_run: meta.partial_run || false,
+    proposals,
+  };
+};
+
+/**
+ * Save coherence review state and proposals to the database.
+ */
+export const saveCoherence = async (data, projectId?: string) => {
+  const db = getDb();
+
+  const metaKey = projectId ? `${META_KEY}:${projectId}` : META_KEY;
+  const metaValue = JSON.stringify({
+    last_review_timestamp: data.last_review_timestamp,
+    review_status: data.review_status,
+    partial_run: data.partial_run || false,
+  });
+
+  const existing = await db.select().from(reviewMeta)
+    .where(eq(reviewMeta.key, metaKey));
+  if (existing[0]) {
+    await db.update(reviewMeta).set({ value: metaValue })
+      .where(eq(reviewMeta.key, metaKey));
+  } else {
+    await db.insert(reviewMeta).values({ key: metaKey, value: metaValue, projectId: projectId || null });
+  }
+
+  // Sync proposals — delete all and re-insert
+  if (projectId) {
+    await db.delete(coherenceReviews).where(eq(coherenceReviews.projectId, projectId));
+  } else {
+    await db.delete(coherenceReviews);
+  }
+  for (const p of data.proposals) {
+    await db.insert(coherenceReviews).values({
+      id: p.id,
+      type: p.type,
+      fromId: p.from_id || null,
+      toId: p.to_id || null,
+      relation: p.relation || null,
+      proposedNodeType: p.proposed_node_type || null,
+      proposedNodeName: p.proposed_node_name || null,
+      targetNodeId: p.target_node_id || null,
+      proposedDescription: p.proposed_description || null,
+      confidence: p.confidence || null,
+      batchId: p.batch_id || null,
+      reasoning: p.reasoning,
+      status: p.status,
+      createdAt: p.created_at,
+      resolvedAt: p.resolved_at || null,
+      projectId: projectId || null,
+    });
+  }
+};
+
+/**
+ * Get a single proposal by ID.
+ */
+export const getProposal = async (proposalId) => {
+  const db = getDb();
+  const rows = await db.select().from(coherenceReviews)
+    .where(eq(coherenceReviews.id, proposalId));
+  if (!rows[0]) return null;
+  return rowToProposal(rows[0]);
+};
+
+/**
+ * Update a proposal's status.
+ */
+export const updateProposalStatus = async (proposalId, status, resolvedAt = null) => {
+  const db = getDb();
+  const updates = { status };
+  if (resolvedAt) updates.resolvedAt = resolvedAt;
+  await db.update(coherenceReviews).set(updates)
+    .where(eq(coherenceReviews.id, proposalId));
+};
+
+/**
+ * Update coherence state metadata (last_review_timestamp, review_status, partial_run).
+ */
+export const updateCoherenceState = async (state) => {
+  const db = getDb();
+  const metaValue = JSON.stringify(state);
+
+  const existing = await db.select().from(reviewMeta)
+    .where(eq(reviewMeta.key, META_KEY));
+  if (existing[0]) {
+    await db.update(reviewMeta).set({ value: metaValue })
+      .where(eq(reviewMeta.key, META_KEY));
+  } else {
+    await db.insert(reviewMeta).values({ key: META_KEY, value: metaValue });
+  }
+};
+
+/**
+ * Add new proposals to the database.
+ */
+export const addProposals = async (proposals, projectId?: string) => {
+  const db = getDb();
+  for (const p of proposals) {
+    await db.insert(coherenceReviews).values({
+      id: p.id,
+      type: p.type,
+      fromId: p.from_id || null,
+      toId: p.to_id || null,
+      relation: p.relation || null,
+      proposedNodeType: p.proposed_node_type || null,
+      proposedNodeName: p.proposed_node_name || null,
+      targetNodeId: p.target_node_id || null,
+      proposedDescription: p.proposed_description || null,
+      confidence: p.confidence || null,
+      batchId: p.batch_id || null,
+      reasoning: p.reasoning,
+      status: p.status,
+      createdAt: p.created_at,
+      resolvedAt: p.resolved_at || null,
+      projectId: projectId || null,
+    });
+  }
+};
+
+/**
+ * Build a dismissal key for a proposal to prevent re-proposing.
+ * Uses exact tuple matching as specified.
+ */
+export const getDismissalKey = (proposal) => {
+  switch (proposal.type) {
+    case 'add_edge':
+    case 'remove_edge':
+      return `${proposal.type}:${proposal.from_id}:${proposal.relation}:${proposal.to_id}`;
+    case 'add_node':
+      return `${proposal.type}:${proposal.proposed_node_type}:${proposal.proposed_node_name}`;
+    case 'deprecate_node':
+      return `${proposal.type}:${proposal.target_node_id}`;
+    case 'update_description':
+      return `${proposal.type}:${proposal.target_node_id}`;
+    default:
+      return `${proposal.type}:${proposal.id}`;
+  }
+};
+
+/**
+ * Sort proposals by type priority order, then by batch.
+ */
+export const sortProposals = (proposals) => {
+  return [...proposals].sort((a, b) => {
+    const aIdx = PROPOSAL_TYPE_ORDER.indexOf(a.type);
+    const bIdx = PROPOSAL_TYPE_ORDER.indexOf(b.type);
+    if (aIdx !== bIdx) return aIdx - bIdx;
+    // Within same type, keep batch members together
+    if (a.batch_id && b.batch_id && a.batch_id === b.batch_id) return 0;
+    if (a.batch_id && !b.batch_id) return -1;
+    if (!a.batch_id && b.batch_id) return 1;
+    return 0;
+  });
+};
+
+/**
+ * Detect conflicting proposals.
+ * Returns a Map<proposalId, Set<conflictingProposalId>>.
+ */
+export const detectConflicts = (proposals) => {
+  const conflicts = new Map();
+  const pending = proposals.filter(p => p.status === 'pending');
+
+  // Nodes being deprecated
+  const deprecatedNodeIds = new Set(
+    pending.filter(p => p.type === 'deprecate_node').map(p => p.target_node_id)
+  );
+
+  for (const p of pending) {
+    const pConflicts = new Set();
+
+    if (p.type === 'add_edge') {
+      // Conflict: add edge to/from a node being deprecated
+      if (deprecatedNodeIds.has(p.from_id) || deprecatedNodeIds.has(p.to_id)) {
+        const deprecator = pending.find(d =>
+          d.type === 'deprecate_node' &&
+          (d.target_node_id === p.from_id || d.target_node_id === p.to_id)
+        );
+        if (deprecator) pConflicts.add(deprecator.id);
+      }
+    }
+
+    if (p.type === 'remove_edge') {
+      // Conflict: removing an edge while also adding the same edge
+      const addDup = pending.find(a =>
+        a.type === 'add_edge' &&
+        a.from_id === p.from_id && a.relation === p.relation && a.to_id === p.to_id
+      );
+      if (addDup) pConflicts.add(addDup.id);
+    }
+
+    if (p.type === 'update_description' && deprecatedNodeIds.has(p.target_node_id)) {
+      const deprecator = pending.find(d =>
+        d.type === 'deprecate_node' && d.target_node_id === p.target_node_id
+      );
+      if (deprecator) pConflicts.add(deprecator.id);
+    }
+
+    if (pConflicts.size > 0) {
+      conflicts.set(p.id, pConflicts);
+      // Add reverse conflicts
+      for (const cId of pConflicts) {
+        if (!conflicts.has(cId)) conflicts.set(cId, new Set());
+        conflicts.get(cId).add(p.id);
+      }
+    }
+  }
+
+  return conflicts;
+};

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

@@ -0,0 +1,30 @@
+/**
+ * Completeness scoring for nodes.
+ * Calculates a 0–1 score based on the node type's scoring rules.
+ */
+
+import { SCORING_RULES } from './constants.js';
+
+/**
+ * Score a node's completeness from 0 to 1 based on its type and current content.
+ *
+ * @param {string} type - The node type (e.g., 'feature', 'component')
+ * @param {object} frontmatter - Parsed frontmatter object
+ * @param {object} sections - Map of section name → content string
+ * @returns {number} Score between 0 and 1, rounded to 2 decimal places
+ */
+export function scoreNode(type, frontmatter, sections) {
+  const rules = SCORING_RULES[type];
+  if (!rules) {
+    return 0;
+  }
+
+  let score = 0;
+  for (const rule of rules) {
+    if (rule.check(frontmatter, sections)) {
+      score += rule.weight;
+    }
+  }
+
+  return Math.round(score * 100) / 100;
+}