@holoscript/framework 6.0.3

package/src/behavior/StateTrait.ts

@@ -0,0 +1,67 @@
+/**
+ * StateTrait.ts
+ *
+ * Declarative FSM attachment to HoloScript+ nodes.
+ * Allows nodes to define states and transitions as trait config.
+ *
+ * @trait state
+ */
+
+import type { TraitHandler, HSPlusNode } from '@holoscript/core';
+import { StateMachine, StateMachineConfig } from './StateMachine';
+
+// =============================================================================
+// CONFIG
+// =============================================================================
+
+export interface StateTraitConfig {
+  machine: StateMachineConfig;
+}
+
+// Extended properties interface for state-aware nodes
+interface StateAwareProperties {
+  _state?: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- extensible properties bag
+  [key: string]: any;
+}
+
+// Per-node state machines
+const nodeStateMachines = new Map<string, StateMachine>();
+
+export const stateTraitHandler: TraitHandler<StateTraitConfig> = {
+  name: 'state' as const,
+  defaultConfig: { machine: { initialState: 'idle', states: [], transitions: [] } },
+
+  onAttach(node: HSPlusNode, config: StateTraitConfig, _context: unknown) {
+    const nodeId = node.id!;
+    const sm = new StateMachine(config.machine);
+    nodeStateMachines.set(nodeId, sm);
+
+    // Surface state on node properties
+    if (node.properties) {
+      (node.properties as StateAwareProperties)._state = sm.getCurrentState();
+    }
+  },
+
+  onDetach(node: HSPlusNode, _config: StateTraitConfig, _context: unknown) {
+    nodeStateMachines.delete(node.id!);
+  },
+
+  onUpdate(node: HSPlusNode, _config: StateTraitConfig, _context: unknown, delta: number) {
+    const sm = nodeStateMachines.get(node.id!);
+    if (!sm) return;
+
+    sm.update(delta);
+
+    if (node.properties) {
+      (node.properties as StateAwareProperties)._state = sm.getCurrentState();
+    }
+  },
+};
+
+/**
+ * Get the StateMachine for a given node (for external event sending).
+ */
+export function getNodeStateMachine(nodeId: string): StateMachine | undefined {
+  return nodeStateMachines.get(nodeId);
+}

package/src/behavior/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Behavior module barrel
+ * Re-exports all behavior functionality from @holoscript/framework
+ */
+export * from './BehaviorPresets';
+export * from './BehaviorTree';
+export * from './StateMachine';
+export * from './StateTrait';

package/src/behavior.ts

@@ -0,0 +1,8 @@
+/**
+ * Behavior Tree — Lightweight node builders for agent decision-making.
+ * Re-exported from @holoscript/framework/behavior barrel (A.011.02e migration)
+ *
+ * Import from '@holoscript/framework/bt' or '@holoscript/framework/behavior'
+ */
+
+export * from './behavior/index';

package/src/board/audit.ts

@@ -0,0 +1,284 @@
+/**
+ * Done-Log Audit Logic (FW-0.3)
+ *
+ * Absorbed from mcp-server/src/holomesh/http-routes.ts.
+ * Verifies commit proof, detects duplicates, checks monotonic timestamps,
+ * and provides per-agent/per-source statistics.
+ *
+ * Two APIs:
+ * - `auditDoneLog(entries)` — the original function (unchanged signature)
+ * - `DoneLogAuditor` class — richer audit with stats, violations, and Team integration
+ */
+
+import type { DoneLogEntry } from './board-types';
+
+// ── Types ──
+
+export interface AuditResult {
+  total: number;
+  proofRequiredTotal: number;
+  nonProofEntries: number;
+  verified: number;
+  unverified: number;
+  duplicates: number;
+  unverifiedTasks: Array<{
+    taskId: string;
+    title: string;
+    completedBy: string;
+    summary: string;
+    timestamp: string;
+  }>;
+  duplicateTasks: Array<{ title: string; count: number }>;
+  health: {
+    verificationRate: number;
+    message: string;
+  };
+}
+
+/** A single violation found by the auditor. */
+export interface AuditViolation {
+  /** Which check produced this violation. */
+  rule: 'missing-completedBy' | 'missing-summary' | 'missing-commit' | 'duplicate-entry' | 'non-monotonic-timestamp';
+  /** Human-readable description. */
+  message: string;
+  /** The entry that triggered the violation. */
+  entry: DoneLogEntry;
+}
+
+/** Per-agent completion statistics. */
+export interface AgentStats {
+  agent: string;
+  completed: number;
+  verified: number;
+  unverified: number;
+}
+
+/** Per-source completion statistics. */
+export interface SourceStats {
+  source: string;
+  completed: number;
+}
+
+/** Completion rate bucket for a time period. */
+export interface CompletionBucket {
+  /** ISO date string (YYYY-MM-DD). */
+  date: string;
+  completed: number;
+}
+
+/** Full statistics from DoneLogAuditor.stats(). */
+export interface DoneLogStats {
+  total: number;
+  byAgent: AgentStats[];
+  bySource: SourceStats[];
+  completionOverTime: CompletionBucket[];
+}
+
+/** Combined audit + stats result from DoneLogAuditor. */
+export interface FullAuditResult {
+  /** Original AuditResult (backward compatible). */
+  audit: AuditResult;
+  /** Structural violations (missing fields, duplicates, non-monotonic). */
+  violations: AuditViolation[];
+  /** Statistics breakdown. */
+  stats: DoneLogStats;
+}
+
+// ── Helper Functions ──
+
+/** Check if a done-log entry is a report/session summary (not real task work). */
+export function isLikelyReportEntry(entry: { title?: string; summary?: string }): boolean {
+  const title = (entry.title || '').toLowerCase();
+  const summary = (entry.summary || '').toLowerCase();
+  return title.startsWith('[report]') || summary.startsWith('session end');
+}
+
+/** Check if a commit hash looks like real git proof. */
+export function isCommitProof(commitHash?: string): boolean {
+  if (!commitHash) return false;
+  const hash = commitHash.trim();
+  if (!hash) return false;
+  if (['uncommit', 'local-uncommitted', 'local_uncommitted', 'none', 'n/a', 'na'].includes(hash.toLowerCase())) {
+    return false;
+  }
+  return /^[0-9a-f]{7,40}$/i.test(hash);
+}
+
+/** Audit a done log: verify commits, find duplicates, calculate health. */
+export function auditDoneLog(doneLog: DoneLogEntry[]): AuditResult {
+  const proofRequired = doneLog.filter((e) => !isLikelyReportEntry(e));
+  const nonProofEntries = doneLog.filter((e) => isLikelyReportEntry(e));
+
+  const verified = proofRequired.filter((e) => isCommitProof(e.commitHash));
+  const unverified = proofRequired.filter((e) => !isCommitProof(e.commitHash));
+
+  const duplicateMap = new Map<string, number>();
+  for (const e of doneLog) {
+    duplicateMap.set(e.title, (duplicateMap.get(e.title) || 0) + 1);
+  }
+  const duped = [...duplicateMap.entries()]
+    .filter(([, count]) => count > 1)
+    .map(([title, count]) => ({ title, count }));
+
+  const denominator = proofRequired.length;
+  const verificationRate = denominator > 0 ? Math.round((verified.length / denominator) * 100) : 100;
+
+  return {
+    total: doneLog.length,
+    proofRequiredTotal: proofRequired.length,
+    nonProofEntries: nonProofEntries.length,
+    verified: verified.length,
+    unverified: unverified.length,
+    duplicates: duped.length,
+    unverifiedTasks: unverified.map((e) => ({
+      taskId: e.taskId,
+      title: e.title,
+      completedBy: e.completedBy,
+      summary: e.summary,
+      timestamp: e.timestamp,
+    })),
+    duplicateTasks: duped,
+    health: {
+      verificationRate,
+      message: unverified.length === 0
+        ? 'All tasks have commit proof.'
+        : `${unverified.length} tasks need verification — missing or invalid commit proof.`,
+    },
+  };
+}
+
+// ── DoneLogAuditor Class ──
+
+/**
+ * Stateless auditor that inspects a done-log for structural violations
+ * and computes aggregate statistics. Designed for Team.audit() integration.
+ */
+export class DoneLogAuditor {
+  constructor(private readonly entries: DoneLogEntry[]) {}
+
+  /**
+   * Run all audit checks and return violations.
+   *
+   * Checks:
+   * 1. Every done task has completedBy, summary, and commit proof
+   * 2. No duplicate entries (by taskId)
+   * 3. Timestamps are monotonically increasing
+   */
+  audit(): AuditViolation[] {
+    const violations: AuditViolation[] = [];
+
+    const seenIds = new Map<string, DoneLogEntry>();
+
+    let prevTimestamp = '';
+
+    for (const entry of this.entries) {
+      // Skip report entries — they don't need the same rigor
+      if (isLikelyReportEntry(entry)) continue;
+
+      // Check required fields
+      if (!entry.completedBy) {
+        violations.push({
+          rule: 'missing-completedBy',
+          message: `Task "${entry.title}" (${entry.taskId}) has no completedBy field.`,
+          entry,
+        });
+      }
+
+      if (!entry.summary) {
+        violations.push({
+          rule: 'missing-summary',
+          message: `Task "${entry.title}" (${entry.taskId}) has no summary.`,
+          entry,
+        });
+      }
+
+      if (!isCommitProof(entry.commitHash)) {
+        violations.push({
+          rule: 'missing-commit',
+          message: `Task "${entry.title}" (${entry.taskId}) has no valid commit proof.`,
+          entry,
+        });
+      }
+
+      // Duplicate check by taskId
+      if (seenIds.has(entry.taskId)) {
+        violations.push({
+          rule: 'duplicate-entry',
+          message: `Task "${entry.title}" (${entry.taskId}) appears more than once in the done log.`,
+          entry,
+        });
+      } else {
+        seenIds.set(entry.taskId, entry);
+      }
+
+      // Monotonic timestamp check
+      if (prevTimestamp && entry.timestamp < prevTimestamp) {
+        violations.push({
+          rule: 'non-monotonic-timestamp',
+          message: `Task "${entry.title}" (${entry.taskId}) timestamp ${entry.timestamp} is before previous ${prevTimestamp}.`,
+          entry,
+        });
+      }
+      prevTimestamp = entry.timestamp;
+    }
+
+    return violations;
+  }
+
+  /** Get aggregate statistics over the done log. */
+  stats(): DoneLogStats {
+    // By agent
+    const agentMap = new Map<string, { completed: number; verified: number; unverified: number }>();
+    for (const entry of this.entries) {
+      const agent = entry.completedBy || 'unknown';
+      const existing = agentMap.get(agent) ?? { completed: 0, verified: 0, unverified: 0 };
+      existing.completed++;
+      if (isCommitProof(entry.commitHash)) {
+        existing.verified++;
+      } else {
+        existing.unverified++;
+      }
+      agentMap.set(agent, existing);
+    }
+
+    // By source — extract source prefix from taskId (e.g., "task_synth_" → "synthesizer")
+    const sourceMap = new Map<string, number>();
+    for (const entry of this.entries) {
+      // Best-effort source detection from summary or taskId pattern
+      let source = 'manual';
+      if (entry.taskId.includes('synth')) source = 'synthesizer';
+      else if (entry.summary?.includes('scout')) source = 'scout';
+      else if (entry.summary?.includes('derive')) source = 'derive';
+      sourceMap.set(source, (sourceMap.get(source) ?? 0) + 1);
+    }
+
+    // Completion over time (by date)
+    const dateMap = new Map<string, number>();
+    for (const entry of this.entries) {
+      const date = entry.timestamp.slice(0, 10); // YYYY-MM-DD
+      dateMap.set(date, (dateMap.get(date) ?? 0) + 1);
+    }
+
+    return {
+      total: this.entries.length,
+      byAgent: Array.from(agentMap.entries())
+        .map(([agent, s]) => ({ agent, ...s }))
+        .sort((a, b) => b.completed - a.completed),
+      bySource: Array.from(sourceMap.entries())
+        .map(([source, completed]) => ({ source, completed }))
+        .sort((a, b) => b.completed - a.completed),
+      completionOverTime: Array.from(dateMap.entries())
+        .map(([date, completed]) => ({ date, completed }))
+        .sort((a, b) => a.date.localeCompare(b.date)),
+    };
+  }
+
+  /** Run full audit: original AuditResult + violations + stats. */
+  fullAudit(): FullAuditResult {
+    return {
+      audit: auditDoneLog(this.entries),
+      violations: this.audit(),
+      stats: this.stats(),
+    };
+  }
+}

package/src/board/board-ops.ts

@@ -0,0 +1,336 @@
+/**
+ * Board Operations — Pure state machine logic for task and suggestion lifecycle.
+ *
+ * Absorbed from mcp-server/src/holomesh/http-routes.ts.
+ * These are pure functions that mutate board/suggestion arrays.
+ * The HTTP layer calls these and handles persistence + responses.
+ */
+
+import type { TeamTask, TaskAction, DoneLogEntry, TeamSuggestion, SuggestionCategory, SlotRole } from './board-types';
+import { normalizeTitle, generateTaskId, generateSuggestionId } from './board-types';
+
+// ── Task Operations ──
+
+export interface ClaimResult {
+  success: boolean;
+  error?: string;
+  task?: TeamTask;
+}
+
+export interface DoneResult {
+  success: boolean;
+  error?: string;
+  task?: TeamTask;
+  doneEntry?: DoneLogEntry;
+}
+
+export interface TaskActionResult {
+  success: boolean;
+  error?: string;
+  task?: TeamTask;
+  doneEntry?: DoneLogEntry;
+}
+
+/** Claim an open task. Returns error if task isn't open or has unmet dependencies. */
+export function claimTask(
+  board: TeamTask[],
+  taskId: string,
+  claimerId: string,
+  claimerName: string
+): TaskActionResult {
+  const task = board.find((t) => t.id === taskId);
+  if (!task) return { success: false, error: 'Task not found' };
+  if (task.status !== 'open') return { success: false, error: `Task is ${task.status}, not open` };
+
+  // Check dependencies — all must be done (not on the board)
+  if (task.dependsOn && task.dependsOn.length > 0) {
+    const pending = task.dependsOn.filter((depId) => board.some((t) => t.id === depId && t.status !== 'done'));
+    if (pending.length > 0) {
+      return { success: false, error: `Blocked by ${pending.length} unfinished dependencies: ${pending.join(', ')}` };
+    }
+  }
+
+  task.status = 'claimed';
+  task.claimedBy = claimerId;
+  task.claimedByName = claimerName;
+  return { success: true, task };
+}
+
+/** Mark a task as done. Removes from board, returns done log entry. */
+export function completeTask(
+  board: TeamTask[],
+  taskId: string,
+  completedBy: string,
+  opts: { commit?: string; summary?: string } = {}
+): { result: TaskActionResult & { onComplete?: TaskAction[]; unblocked?: string[] }; updatedBoard: TeamTask[] } {
+  const task = board.find((t) => t.id === taskId);
+  if (!task) return { result: { success: false, error: 'Task not found' }, updatedBoard: board };
+
+  task.status = 'done';
+  task.completedBy = completedBy;
+  task.commitHash = opts.commit;
+  task.completedAt = new Date().toISOString();
+
+  const doneEntry: DoneLogEntry = {
+    taskId: task.id,
+    title: task.title,
+    completedBy,
+    commitHash: task.commitHash,
+    timestamp: task.completedAt,
+    summary: opts.summary || task.title,
+  };
+
+  // Unblock dependent tasks — move from 'blocked' to 'open' if all their deps are done
+  const unblocked: string[] = [];
+  if (task.unblocks) {
+    for (const depId of task.unblocks) {
+      const dep = board.find((t) => t.id === depId);
+      if (!dep) continue;
+      // Check if ALL of dep's dependencies are now done (off the board or status=done)
+      const allDepsMet = !dep.dependsOn || dep.dependsOn.every(
+        (id) => id === taskId || !board.some((t) => t.id === id && t.status !== 'done')
+      );
+      if (allDepsMet && dep.status === 'blocked') {
+        dep.status = 'open';
+        unblocked.push(depId);
+      }
+    }
+  }
+
+  const updatedBoard = board.filter((t) => t.id !== taskId);
+  return {
+    result: {
+      success: true,
+      task,
+      doneEntry,
+      onComplete: task.onComplete,
+      unblocked: unblocked.length > 0 ? unblocked : undefined,
+    },
+    updatedBoard,
+  };
+}
+
+/** Block a task. */
+export function blockTask(board: TeamTask[], taskId: string): TaskActionResult {
+  const task = board.find((t) => t.id === taskId);
+  if (!task) return { success: false, error: 'Task not found' };
+  task.status = 'blocked';
+  return { success: true, task };
+}
+
+/** Reopen a task (unclaim). */
+export function reopenTask(board: TeamTask[], taskId: string): TaskActionResult {
+  const task = board.find((t) => t.id === taskId);
+  if (!task) return { success: false, error: 'Task not found' };
+  task.status = 'open';
+  task.claimedBy = undefined;
+  task.claimedByName = undefined;
+  return { success: true, task };
+}
+
+/** Delegate a task from a source board to a target board. */
+export function delegateTask(
+  sourceBoard: TeamTask[],
+  targetBoard: TeamTask[],
+  taskId: string
+): { result: TaskActionResult; updatedSource: TeamTask[]; updatedTarget: TeamTask[] } {
+  const task = sourceBoard.find((t) => t.id === taskId);
+  if (!task) return { result: { success: false, error: 'Task not found' }, updatedSource: sourceBoard, updatedTarget: targetBoard };
+
+  const updatedSource = sourceBoard.filter((t) => t.id !== taskId);
+  
+  // Clone task so it's fresh for the new board (unclaimed)
+  const delegatedTask: TeamTask = {
+    ...task,
+    status: 'open',
+    claimedBy: undefined,
+    claimedByName: undefined,
+  };
+  
+  targetBoard.push(delegatedTask);
+  return { result: { success: true, task: delegatedTask }, updatedSource, updatedTarget: targetBoard };
+}
+
+/** Add tasks to a board with dedup against existing + done log. */
+export function addTasksToBoard(
+  board: TeamTask[],
+  doneLog: DoneLogEntry[],
+  tasks: Array<Omit<TeamTask, 'id' | 'status' | 'createdAt'>>
+): { added: TeamTask[]; updatedBoard: TeamTask[] } {
+  const existingNorm = new Set([
+    ...board.map((t) => normalizeTitle(t.title)),
+    ...doneLog.map((d) => normalizeTitle(d.title)),
+  ]);
+
+  const added: TeamTask[] = [];
+  for (const t of tasks) {
+    const title = String(t.title || '').slice(0, 200);
+    if (!title || existingNorm.has(normalizeTitle(title))) continue;
+
+    const task: TeamTask = {
+      id: generateTaskId(),
+      title,
+      description: String(t.description || '').slice(0, 1000),
+      status: 'open',
+      source: String(t.source || 'manual'),
+      priority: t.priority || 5,
+      role: t.role,
+      createdAt: new Date().toISOString(),
+    };
+    board.push(task);
+    existingNorm.add(normalizeTitle(title));
+    added.push(task);
+  }
+
+  return { added, updatedBoard: board };
+}
+
+// ── Suggestion Operations ──
+
+export interface SuggestionActionResult {
+  success: boolean;
+  error?: string;
+  suggestion?: TeamSuggestion;
+  promotedTask?: TeamTask;
+}
+
+/** Create a suggestion with dedup against existing open suggestions. */
+export function createSuggestion(
+  suggestions: TeamSuggestion[],
+  opts: {
+    title: string;
+    description?: string;
+    category?: SuggestionCategory;
+    evidence?: string;
+    proposedBy: string;
+    proposedByName: string;
+  }
+): SuggestionActionResult {
+  const title = opts.title.trim().slice(0, 200);
+  if (!title) return { success: false, error: 'title is required' };
+
+  const existingNorm = new Set(
+    suggestions.filter((s) => s.status === 'open').map((s) => normalizeTitle(s.title))
+  );
+  if (existingNorm.has(normalizeTitle(title))) {
+    return { success: false, error: 'A similar open suggestion already exists' };
+  }
+
+  const suggestion: TeamSuggestion = {
+    id: generateSuggestionId(),
+    title,
+    description: (opts.description || '').slice(0, 2000),
+    category: opts.category || 'other',
+    proposedBy: opts.proposedBy,
+    proposedByName: opts.proposedByName,
+    votes: [],
+    score: 0,
+    status: 'open',
+    evidence: opts.evidence?.slice(0, 1000),
+    createdAt: new Date().toISOString(),
+  };
+  suggestions.push(suggestion);
+  return { success: true, suggestion };
+}
+
+/** Vote on a suggestion. Auto-promotes at majority, auto-dismisses at negative majority. */
+export function voteSuggestion(
+  suggestions: TeamSuggestion[],
+  board: TeamTask[],
+  suggestionId: string,
+  voterId: string,
+  voterName: string,
+  value: 1 | -1,
+  maxSlots: number,
+  reason?: string
+): SuggestionActionResult {
+  const suggestion = suggestions.find((s) => s.id === suggestionId);
+  if (!suggestion) return { success: false, error: 'Suggestion not found' };
+  if (suggestion.status !== 'open') return { success: false, error: `Suggestion is ${suggestion.status}, voting closed` };
+
+  // Replace previous vote from same agent
+  suggestion.votes = suggestion.votes.filter((v) => v.agentId !== voterId);
+  suggestion.votes.push({
+    agentId: voterId,
+    agentName: voterName,
+    value,
+    reason,
+    votedAt: new Date().toISOString(),
+  });
+  suggestion.score = suggestion.votes.reduce((sum, v) => sum + v.value, 0);
+
+  let promotedTask: TeamTask | undefined;
+
+  // Auto-promote at majority
+  const promoteThreshold = Math.ceil(maxSlots / 2);
+  if (suggestion.score >= promoteThreshold && suggestion.status === 'open') {
+    suggestion.status = 'promoted';
+    suggestion.resolvedAt = new Date().toISOString();
+
+    promotedTask = {
+      id: generateTaskId(),
+      title: suggestion.title,
+      description: `${suggestion.description}\n\n[Auto-promoted from suggestion by ${suggestion.proposedByName} with ${suggestion.score} votes]`,
+      status: 'open',
+      source: `suggestion:${suggestion.id}`,
+      priority: suggestion.category === 'architecture' ? 2 : suggestion.category === 'testing' ? 3 : 4,
+      createdAt: new Date().toISOString(),
+    };
+    board.push(promotedTask);
+    suggestion.promotedTaskId = promotedTask.id;
+  }
+
+  // Auto-dismiss at negative majority
+  const dismissThreshold = -Math.ceil(maxSlots / 2);
+  if (suggestion.score <= dismissThreshold && suggestion.status === 'open') {
+    suggestion.status = 'dismissed';
+    suggestion.resolvedAt = new Date().toISOString();
+  }
+
+  return { success: true, suggestion, promotedTask };
+}
+
+/** Promote a suggestion manually. Creates a board task. */
+export function promoteSuggestion(
+  suggestions: TeamSuggestion[],
+  board: TeamTask[],
+  suggestionId: string,
+  promoterName: string,
+  opts: { priority?: number; role?: SlotRole } = {}
+): SuggestionActionResult {
+  const suggestion = suggestions.find((s) => s.id === suggestionId);
+  if (!suggestion) return { success: false, error: 'Suggestion not found' };
+  if (suggestion.status !== 'open') return { success: false, error: `Suggestion is already ${suggestion.status}` };
+
+  suggestion.status = 'promoted';
+  suggestion.resolvedAt = new Date().toISOString();
+
+  const task: TeamTask = {
+    id: generateTaskId(),
+    title: suggestion.title,
+    description: `${suggestion.description}\n\n[Promoted by ${promoterName} from suggestion by ${suggestion.proposedByName}]`,
+    status: 'open',
+    source: `suggestion:${suggestion.id}`,
+    priority: opts.priority || 3,
+    role: opts.role,
+    createdAt: new Date().toISOString(),
+  };
+  board.push(task);
+  suggestion.promotedTaskId = task.id;
+
+  return { success: true, suggestion, promotedTask: task };
+}
+
+/** Dismiss a suggestion. */
+export function dismissSuggestion(
+  suggestions: TeamSuggestion[],
+  suggestionId: string
+): SuggestionActionResult {
+  const suggestion = suggestions.find((s) => s.id === suggestionId);
+  if (!suggestion) return { success: false, error: 'Suggestion not found' };
+  if (suggestion.status !== 'open') return { success: false, error: `Suggestion is already ${suggestion.status}` };
+
+  suggestion.status = 'dismissed';
+  suggestion.resolvedAt = new Date().toISOString();
+  return { success: true, suggestion };
+}