@arka-labs/nemesis 1.2.0

package/lib/core/flowmap/machine.js

@@ -0,0 +1,281 @@
+import { setup, assign } from 'xstate';
+
+/**
+ * STEP_METADATA — lookup table derived from FLOWMAP.json
+ * Maps each XState state key to its FLOWMAP metadata.
+ */
+export const STEP_METADATA = {
+  F00:           { step_id: 'F00',           phase: 'CADRAGE',             who: 'Leader + PM',        label: 'Initialisation — Mission Contract à rédiger' },
+  F01:           { step_id: 'F01',           phase: 'CADRAGE',             who: 'AGP ou PM',          label: 'Mission Contract en attente de validation' },
+  F02:           { step_id: 'F02',           phase: 'CADRAGE',             who: 'Leader',             label: 'Mission Contract validé — OdM à rédiger' },
+  F03:           { step_id: 'F03',           phase: 'DISPATCH',            who: 'Leader',             label: 'OdM validé par PM — à dispatcher' },
+  F04:           { step_id: 'F04',           phase: 'EXECUTION',           who: 'Expert',             label: 'Expert reçoit l\'OdM — prise en charge' },
+  F05:           { step_id: 'F05',           phase: 'EXECUTION',           who: 'Expert',             label: 'Expert en cours d\'implémentation' },
+  F06:           { step_id: 'F06',           phase: 'EXECUTION',           who: 'Expert',             label: 'Expert termine — livraison au Leader' },
+  F07:           { step_id: 'F07',           phase: 'CONTROLE_EVIDENCE',   who: 'Leader',             label: 'Leader reçoit la livraison Expert — contrôle administratif' },
+  F08:           { step_id: 'F08',           phase: 'QA',                  who: 'QA',                 label: 'QA reçoit l\'OdM — exécution SALVA' },
+  F09:           { step_id: 'F09',           phase: 'QA',                  who: 'Leader',             label: 'Lecture du verdict QA' },
+  F10:           { step_id: 'F10',           phase: 'VALIDATION_FINALE',   who: 'Leader',             label: 'Leader prépare la clôture — artefacts finaux' },
+  F10_reserve:   { step_id: 'F10_reserve',   phase: 'VALIDATION_FINALE',   who: 'Leader + AGP',       label: 'Réserve active — qualification AGP ou escalade PM' },
+  F11:           { step_id: 'F11',           phase: 'VALIDATION_FINALE',   who: 'PM',                 label: 'Livraison au PM — mission close' },
+  FX_ESCALADE:   { step_id: 'FX-ESCALADE',   phase: 'EXCEPTION',           who: 'Leader',             label: 'Escalade PM — cas non couvert ou blocage' },
+  FX_RENVOI:     { step_id: 'FX-RENVOI',     phase: 'EXCEPTION',           who: 'Leader',             label: 'OdM renvoyé à Expert pour correction' },
+  FX_AMENDMENT:  { step_id: 'FX-AMENDMENT',  phase: 'EXCEPTION',           who: 'Leader',             label: 'OdM gelé — amendement requis' },
+  FIN:           { step_id: 'FIN',           phase: 'TERMINEE',            who: '-',                  label: 'Mission terminée' },
+};
+
+/**
+ * addHistoryEntry — assign action that appends a transition to context.history
+ */
+const addHistoryEntry = assign({
+  history: ({ context, event }) => [
+    ...context.history,
+    {
+      from: context.currentStepId,
+      to: null, // filled by entry action of target state
+      event: event.type,
+      timestamp: new Date().toISOString(),
+      actor: event.actor || null,
+      note: event.note || null,
+    },
+  ],
+  updatedAt: () => new Date().toISOString(),
+});
+
+/**
+ * makeEntryAction — creates an assign action that updates currentStepId/phase/who
+ * and patches the last history entry with the correct "to" value.
+ */
+function makeEntryAction(stateKey) {
+  const meta = STEP_METADATA[stateKey];
+  return assign({
+    currentStepId: meta.step_id,
+    phase: meta.phase,
+    who: meta.who,
+    history: ({ context }) => {
+      if (context.history.length === 0) return context.history;
+      const updated = [...context.history];
+      const last = { ...updated[updated.length - 1], to: meta.step_id };
+      updated[updated.length - 1] = last;
+      return updated;
+    },
+  });
+}
+
+/**
+ * ESCALATE event — spread into every non-final state.
+ */
+const ESCALATE_EVENT = {
+  ESCALATE: {
+    target: 'FX_ESCALADE',
+    actions: addHistoryEntry,
+  },
+};
+
+/**
+ * REQUEST_AMENDMENT event — spread into states where OdM is frozen (post-dispatch F04+).
+ * Per FLOWMAP: "L'OdM est gelé mais un changement est nécessaire."
+ */
+const AMENDMENT_EVENT = {
+  REQUEST_AMENDMENT: {
+    target: 'FX_AMENDMENT',
+    actions: addHistoryEntry,
+  },
+};
+
+/**
+ * flowmapMachine — XState v5 state machine for the Nemesis FLOWMAP workflow.
+ */
+export const flowmapMachine = setup({
+  guards: {
+    isControlOk: ({ event }) => event.result === 'OK',
+    isControlFail: ({ event }) => event.result === 'RENVOI',
+    isVerdictPass: ({ event }) => event.verdict === 'PASS',
+    isVerdictFail: ({ event }) => event.verdict === 'FAIL',
+    isVerdictReserve: ({ event }) => event.verdict === 'RESERVE',
+    isVerdictNotObservable: ({ event }) => event.verdict === 'NOT_OBSERVABLE',
+    isReserveNoImpact: ({ event }) => event.impact === 'aucun',
+    isReserveBlocking: ({ event }) => event.impact !== 'aucun',
+    isPmTargetF00: ({ event }) => event.targetStep === 'F00',
+    isPmTargetF02: ({ event }) => event.targetStep === 'F02',
+    isPmTargetF05: ({ event }) => event.targetStep === 'F05',
+    isPmTargetF10: ({ event }) => event.targetStep === 'F10',
+  },
+  actions: {
+    addHistoryEntry,
+    entryF00: makeEntryAction('F00'),
+    entryF01: makeEntryAction('F01'),
+    entryF02: makeEntryAction('F02'),
+    entryF03: makeEntryAction('F03'),
+    entryF04: makeEntryAction('F04'),
+    entryF05: makeEntryAction('F05'),
+    entryF06: makeEntryAction('F06'),
+    entryF07: makeEntryAction('F07'),
+    entryF08: makeEntryAction('F08'),
+    entryF09: makeEntryAction('F09'),
+    entryF10: makeEntryAction('F10'),
+    entryF10_reserve: makeEntryAction('F10_reserve'),
+    entryF11: makeEntryAction('F11'),
+    entryFX_ESCALADE: makeEntryAction('FX_ESCALADE'),
+    entryFX_RENVOI: makeEntryAction('FX_RENVOI'),
+    entryFX_AMENDMENT: makeEntryAction('FX_AMENDMENT'),
+    entryFIN: makeEntryAction('FIN'),
+  },
+}).createMachine({
+  id: 'flowmap',
+  initial: 'F00',
+  context: ({ input }) => ({
+    missionId: input?.missionId || null,
+    odmId: input?.odmId || null,
+    projectId: input?.projectId || null,
+    currentStepId: 'F00',
+    phase: 'CADRAGE',
+    who: 'Leader + PM',
+    history: [],
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    metadata: input?.metadata || {},
+  }),
+  states: {
+    F00: {
+      entry: 'entryF00',
+      on: {
+        SUBMIT_MC: { target: 'F01', actions: 'addHistoryEntry' },
+        ...ESCALATE_EVENT,
+      },
+    },
+    F01: {
+      entry: 'entryF01',
+      on: {
+        VALIDATE_MC: { target: 'F02', actions: 'addHistoryEntry' },
+        REJECT_MC: { target: 'F00', actions: 'addHistoryEntry' },
+        ...ESCALATE_EVENT,
+      },
+    },
+    F02: {
+      entry: 'entryF02',
+      on: {
+        SUBMIT_ODM: { target: 'F03', actions: 'addHistoryEntry' },
+        ...ESCALATE_EVENT,
+      },
+    },
+    F03: {
+      entry: 'entryF03',
+      on: {
+        DISPATCH_ODM: { target: 'F04', actions: 'addHistoryEntry' },
+        ...ESCALATE_EVENT,
+      },
+    },
+    F04: {
+      entry: 'entryF04',
+      on: {
+        ACKNOWLEDGE_ODM: { target: 'F05', actions: 'addHistoryEntry' },
+        ...ESCALATE_EVENT,
+        ...AMENDMENT_EVENT,
+      },
+    },
+    F05: {
+      entry: 'entryF05',
+      on: {
+        COMPLETE_IMPLEMENTATION: { target: 'F06', actions: 'addHistoryEntry' },
+        ...ESCALATE_EVENT,
+        ...AMENDMENT_EVENT,
+      },
+    },
+    F06: {
+      entry: 'entryF06',
+      on: {
+        DELIVER_ODM: { target: 'F07', actions: 'addHistoryEntry' },
+        ...ESCALATE_EVENT,
+        ...AMENDMENT_EVENT,
+      },
+    },
+    F07: {
+      entry: 'entryF07',
+      on: {
+        CONTROL_VERDICT: [
+          { guard: 'isControlOk', target: 'F08', actions: 'addHistoryEntry' },
+          { guard: 'isControlFail', target: 'FX_RENVOI', actions: 'addHistoryEntry' },
+        ],
+        ...ESCALATE_EVENT,
+        ...AMENDMENT_EVENT,
+      },
+    },
+    F08: {
+      entry: 'entryF08',
+      on: {
+        QA_COMPLETE: { target: 'F09', actions: 'addHistoryEntry' },
+        ...ESCALATE_EVENT,
+        ...AMENDMENT_EVENT,
+      },
+    },
+    F09: {
+      entry: 'entryF09',
+      on: {
+        QA_VERDICT: [
+          { guard: 'isVerdictPass', target: 'F10', actions: 'addHistoryEntry' },
+          { guard: 'isVerdictFail', target: 'FX_RENVOI', actions: 'addHistoryEntry' },
+          { guard: 'isVerdictReserve', target: 'F10_reserve', actions: 'addHistoryEntry' },
+          { guard: 'isVerdictNotObservable', target: 'F10', actions: 'addHistoryEntry' },
+        ],
+        ...ESCALATE_EVENT,
+        ...AMENDMENT_EVENT,
+      },
+    },
+    F10: {
+      entry: 'entryF10',
+      on: {
+        PREPARE_CLOSING: { target: 'F11', actions: 'addHistoryEntry' },
+        ...ESCALATE_EVENT,
+        ...AMENDMENT_EVENT,
+      },
+    },
+    F10_reserve: {
+      entry: 'entryF10_reserve',
+      on: {
+        RESERVE_VERDICT: [
+          { guard: 'isReserveNoImpact', target: 'F10', actions: 'addHistoryEntry' },
+          { guard: 'isReserveBlocking', target: 'FX_ESCALADE', actions: 'addHistoryEntry' },
+        ],
+        ...ESCALATE_EVENT,
+        ...AMENDMENT_EVENT,
+      },
+    },
+    F11: {
+      entry: 'entryF11',
+      on: {
+        CLOSE_MISSION: { target: 'FIN', actions: 'addHistoryEntry' },
+        ...ESCALATE_EVENT,
+      },
+    },
+    FX_ESCALADE: {
+      entry: 'entryFX_ESCALADE',
+      on: {
+        PM_DECISION: [
+          { guard: 'isPmTargetF00', target: 'F00', actions: 'addHistoryEntry' },
+          { guard: 'isPmTargetF02', target: 'F02', actions: 'addHistoryEntry' },
+          { guard: 'isPmTargetF05', target: 'F05', actions: 'addHistoryEntry' },
+          { guard: 'isPmTargetF10', target: 'F10', actions: 'addHistoryEntry' },
+        ],
+      },
+    },
+    FX_RENVOI: {
+      entry: 'entryFX_RENVOI',
+      on: {
+        RENVOI_TO_EXPERT: { target: 'F05', actions: 'addHistoryEntry' },
+        ...ESCALATE_EVENT,
+      },
+    },
+    FX_AMENDMENT: {
+      entry: 'entryFX_AMENDMENT',
+      on: {
+        CREATE_AMENDMENT: { target: 'F02', actions: 'addHistoryEntry' },
+        ...ESCALATE_EVENT,
+      },
+    },
+    FIN: {
+      entry: 'entryFIN',
+      type: 'final',
+    },
+  },
+});

package/lib/core/flowmap/persistence.js

@@ -0,0 +1,83 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const STATE_DIR = 'state';
+const SCHEMA = 'nemesis.flowmap_snapshot.v1';
+
+function stateDir(root) {
+  return join(root, '.nemesis', STATE_DIR);
+}
+
+function snapshotPath(root, missionId) {
+  return join(stateDir(root), `${missionId}.json`);
+}
+
+/**
+ * Ensure .nemesis/state/ exists.
+ */
+export function ensureStateDir(root) {
+  const dir = stateDir(root);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+/**
+ * Save an XState snapshot to disk.
+ */
+export function saveSnapshot(root, missionId, snapshot) {
+  ensureStateDir(root);
+  const data = {
+    _schema: SCHEMA,
+    mission_id: missionId,
+    saved_at: new Date().toISOString(),
+    snapshot,
+  };
+  writeFileSync(snapshotPath(root, missionId), JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Load an XState snapshot from disk. Returns null if absent or corrupted.
+ */
+export function loadSnapshot(root, missionId) {
+  const filepath = snapshotPath(root, missionId);
+  if (!existsSync(filepath)) return null;
+  try {
+    const raw = readFileSync(filepath, 'utf-8');
+    const data = JSON.parse(raw);
+    if (!data.snapshot) return null;
+    return data.snapshot;
+  } catch (_e) {
+    /* fallback: corrupted snapshot */
+    return null;
+  }
+}
+
+/**
+ * Check if a snapshot exists for the given mission.
+ */
+export function hasSnapshot(root, missionId) {
+  return existsSync(snapshotPath(root, missionId));
+}
+
+/**
+ * List all mission IDs that have snapshots.
+ */
+export function listSnapshots(root) {
+  const dir = stateDir(root);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter(f => f.endsWith('.json'))
+    .map(f => f.replace('.json', ''));
+}
+
+/**
+ * Delete a snapshot for the given mission.
+ */
+export function deleteSnapshot(root, missionId) {
+  const filepath = snapshotPath(root, missionId);
+  if (existsSync(filepath)) {
+    unlinkSync(filepath);
+  }
+}

package/lib/core/generators.js

@@ -0,0 +1,183 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+
+/**
+ * Generate memory.md content for a new agent.
+ */
+export function generateMemory(agentName, role, project) {
+  return `> Session name: ${agentName}
+> Agent ID: ${agentName.replace('Agent_', '')}
+
+# Memory — ${agentName}
+
+> Memoire persistante de l'agent ${role.toLowerCase()}.
+> Mise a jour reguliere au fil des sessions.
+
+---
+
+## Profil
+
+- **Agent ID** : \`${agentName.replace('Agent_', '')}\`
+- **Role** : ${role}
+- **Mission** : A definir
+- **Mode** : ${role}
+- **Langue** : Francais pour les echanges, anglais pour le code
+
+---
+
+## Onboarding
+
+- **Date** : ${new Date().toISOString().split('T')[0]}
+- **Contexte** : Projet ${project.name || project.id}
+
+---
+
+## Regles specifiques
+
+- A definir par le PM
+
+---
+
+## Etat du projet
+
+_(a remplir au fil des sessions)_
+
+---
+
+## Sessions
+
+_(vide — premiere session)_
+`;
+}
+
+/**
+ * Generate onboarding prompt for a new agent.
+ * Pure JSON — blocking checklist, agent validates or reports NON READY.
+ */
+export function generateOnboardingPrompt(opts) {
+  const { agentName, role, profileId, reportsTo, project, odmIds, leader } = opts;
+
+  const steps = [
+    {
+      id: 1,
+      action: 'Lire ta memoire',
+      blocked: true,
+      instruction: `Lis le fichier .nemesis/claude/${agentName}/memory.md`,
+      validation: 'Cite ton Agent ID et ton role depuis le fichier',
+      on_fail: 'Status: NON READY — Cause: memoire introuvable ou illisible'
+    },
+    {
+      id: 2,
+      action: 'Verifier acces HCM',
+      blocked: true,
+      instruction: 'Appelle hcm_status pour verifier que le HCM est accessible',
+      validation: 'Le HCM repond avec un status ok',
+      on_fail: 'Status: NON READY — Cause: HCM non disponible (serveur MCP HCM absent ou injoignable)'
+    }
+  ];
+
+  if (profileId) {
+    steps.push(
+      {
+        id: 3,
+        action: 'Lire ton profil Kairos',
+        blocked: true,
+        instruction: `Appelle hcm_get_profile_atoms(profileId: "${profileId}")`,
+        validation: 'Confirme role, mission et mindset depuis les atoms NUCLEUS',
+        on_fail: `Status: NON READY — Cause: profil ${profileId} introuvable sur le HCM`
+      },
+      {
+        id: 4,
+        action: 'Lire les atoms de gouvernance',
+        blocked: true,
+        instruction: 'Appelle hcm_get_governance_atoms',
+        validation: 'Integre les regles transversales a ton comportement',
+        on_fail: 'Status: NON READY — Cause: atoms de gouvernance indisponibles'
+      }
+    );
+  }
+
+  const prompt = {
+    onboarding: {
+      agent: agentName,
+      role,
+      projet: project.name || project.id,
+      reporte_a: reportsTo || 'PM',
+      profil_kairos: profileId || null,
+      odms: (odmIds && odmIds.length > 0) ? odmIds : [],
+      leader: leader || false,
+    },
+    checklist: {
+      description: 'Execute chaque etape dans l\'ordre. Chaque etape est bloquante. Tu ne decides PAS de ce qui est bloquant.',
+      steps
+    },
+    on_success: {
+      status: 'READY',
+      format: {
+        agent: agentName,
+        role,
+        profil: profileId || 'aucun',
+        hcm: 'connecte',
+        memoire: 'lue'
+      }
+    },
+    on_failure: {
+      status: 'NON READY',
+      format: 'Cause: <liste des etapes en echec>'
+    },
+    regles: [
+      'Pas de decision d\'architecture sans validation PM',
+      'Pas de push sans validation PM',
+      'Depots dans .nemesis/HCM/',
+      'GitNexus avant toute modification de code',
+      'Francais pour les echanges, anglais pour le code',
+      ...(leader ? [
+        'Tu coordonnes les agents qui te reportent en tant que leader.',
+        'Tu distribues les taches via des OdMs et synthetises les avancees pour le PM.',
+      ] : []),
+    ]
+  };
+
+  return JSON.stringify(prompt, null, 2);
+}
+
+/**
+ * Update ~/.claude/CLAUDE.md — add agent to table and workflow.
+ */
+export function updateClaudeMd(claudeMdPath, opts) {
+  const { agentName, repo, role, memoryPath } = opts;
+  let content = readFileSync(claudeMdPath, 'utf-8');
+
+  if (content.includes(agentName)) return;
+
+  // Add to agents table
+  const tableRow = `| **${agentName}** | ${repo} | ${role} | \`${memoryPath}\` |`;
+  const externesIdx = content.indexOf('## Agents externes');
+  if (externesIdx !== -1) {
+    const beforeExternes = content.lastIndexOf('\n\n', externesIdx);
+    if (beforeExternes !== -1) {
+      content = content.slice(0, beforeExternes) + '\n' + tableRow + content.slice(beforeExternes);
+    }
+  }
+
+  // Add to workflow tree
+  const workflowLine = `  ├── ${agentName} : ${role}`;
+  const workflowBlockStart = content.indexOf('## Workflow inter-agents');
+  if (workflowBlockStart !== -1) {
+    const codeBlockStart = content.indexOf('```\n', workflowBlockStart);
+    if (codeBlockStart !== -1) {
+      const codeBlockEnd = content.indexOf('\n```', codeBlockStart + 4);
+      if (codeBlockEnd !== -1) {
+        content = content.slice(0, codeBlockEnd) + '\n' + workflowLine + content.slice(codeBlockEnd);
+      }
+    }
+  }
+
+  writeFileSync(claudeMdPath, content, 'utf-8');
+}
+
+/**
+ * Extract repo name from root path.
+ */
+export function getRepoName(root) {
+  return root.split('/').pop() || 'repo';
+}