sentinelayer-cli 0.22.0 → 0.24.0

package/src/guide/generator.js

@@ -41,6 +41,29 @@ function parseNumberedLines(block) {
     .filter(Boolean);
 }
 
+// Labeled bullets the builder emits per phase (e.g. "- Objective: ...").
+// We capture these as structured fields so ticket bodies carry real content
+// instead of dropping every non-numbered line.
+const PHASE_FIELD_LABELS = new Map([
+  ["objective", "objective"],
+  ["dependencies", "dependencies"],
+  ["files", "files"],
+  ["commands", "commands"],
+  ["tests", "tests"],
+  ["rollback", "rollback"],
+  ["evidence", "evidence"],
+]);
+
+// "Phase 0 (P0) — Repo Bootstrap" -> "P0"; "Phase 2 ..." -> "P2".
+function parsePhaseHeadingId(title) {
+  const paren = String(title || "").match(/\(\s*([A-Za-z]+\d+)\s*\)/);
+  if (paren) {
+    return paren[1].toUpperCase();
+  }
+  const phaseNum = String(title || "").match(/^Phase\s+(\d+)\b/i);
+  return phaseNum ? `P${phaseNum[1]}` : "";
+}
+
 function parsePhasePlan(specMarkdown) {
   const phaseBlock = sectionBody(specMarkdown, "Phase Plan");
   if (!phaseBlock) {
@@ -58,16 +81,39 @@ function parsePhasePlan(specMarkdown) {
       if (current) {
         phases.push(current);
       }
+      const title = headingMatch[1].trim();
       current = {
-        title: headingMatch[1].trim(),
+        title,
+        phaseId: parsePhaseHeadingId(title),
         tasks: [],
+        fields: {},
       };
       continue;
     }
 
+    if (!current) {
+      continue;
+    }
+
     const taskMatch = line.match(/^\d+\.\s+(.+)$/);
-    if (taskMatch && current) {
+    if (taskMatch) {
       current.tasks.push(taskMatch[1].trim());
+      continue;
+    }
+
+    const bulletMatch = line.match(/^[-*]\s+(.+)$/);
+    if (bulletMatch) {
+      const body = bulletMatch[1].trim();
+      const labelMatch = body.match(/^([A-Za-z][A-Za-z ]*?):\s*(.*)$/);
+      if (labelMatch) {
+        const key = labelMatch[1].trim().toLowerCase();
+        if (PHASE_FIELD_LABELS.has(key)) {
+          current.fields[PHASE_FIELD_LABELS.get(key)] = labelMatch[2].trim();
+          continue;
+        }
+      }
+      // An unlabeled bullet is real work -> treat it as a task.
+      current.tasks.push(body);
     }
   }
 
@@ -78,6 +124,46 @@ function parsePhasePlan(specMarkdown) {
   return phases;
 }
 
+// Expand a dependency token into phase ids: "P0-P4" -> [P0..P4], "P0" -> [P0].
+function expandPhaseRange(token) {
+  const raw = String(token || "").trim();
+  if (!raw) {
+    return [];
+  }
+  const range = raw.match(/^([A-Za-z]+)(\d+)\s*[-–—]\s*([A-Za-z]+)?(\d+)$/);
+  if (range) {
+    const prefix = range[1].toUpperCase();
+    const start = Number(range[2]);
+    const end = Number(range[4]);
+    if (Number.isFinite(start) && Number.isFinite(end) && end >= start && end - start <= 50) {
+      const out = [];
+      for (let value = start; value <= end; value += 1) {
+        out.push(`${prefix}${value}`);
+      }
+      return out;
+    }
+  }
+  const single = raw.match(/^([A-Za-z]+\d+)$/);
+  return single ? [single[1].toUpperCase()] : [];
+}
+
+// Parse a declared "Dependencies" field into a list of phase ids.
+function parseDeclaredDependencies(value) {
+  const raw = String(value || "").trim();
+  if (!raw || /^none\b/i.test(raw)) {
+    return [];
+  }
+  const ids = [];
+  for (const part of raw.split(/[,;]/)) {
+    for (const id of expandPhaseRange(part)) {
+      if (!ids.includes(id)) {
+        ids.push(id);
+      }
+    }
+  }
+  return ids;
+}
+
 function parseProjectName(specMarkdown) {
   const match = String(specMarkdown || "").match(/^#\s*SPEC\s*-\s*(.+)$/im);
   return match ? match[1].trim() : "Project";
@@ -113,19 +199,58 @@ function estimateEffortHours({ phaseTitle, taskCount, riskSurfaceCount }) {
   };
 }
 
-function normalizeAcceptanceCriteria(specMarkdown, phaseTasks) {
+// Real, phase-specific acceptance criteria derived from the captured fields
+// (Tests/Evidence/Objective) and any tasks, instead of an empty placeholder.
+function derivePhaseAcceptance(specMarkdown, phase) {
   const globalCriteria = parseNumberedLines(sectionBody(specMarkdown, "Acceptance Criteria"));
   if (globalCriteria.length > 0) {
-    return globalCriteria.slice(0, 3);
+    return globalCriteria.slice(0, 5);
+  }
+  const fields = phase.fields || {};
+  const out = [];
+  if (fields.tests) {
+    out.push(`Tests pass: ${fields.tests}`);
+  }
+  if (fields.evidence) {
+    out.push(`Evidence captured: ${fields.evidence}`);
+  }
+  if (fields.objective) {
+    out.push(`Objective met: ${fields.objective}`);
   }
-  return phaseTasks.slice(0, 3).map((task) => `Validated completion: ${task}`);
+  for (const task of (phase.tasks || []).slice(0, 3)) {
+    out.push(`Completed: ${task}`);
+  }
+  if (out.length === 0) {
+    out.push("Phase outcomes are verified by deterministic checks.");
+  }
+  return out.slice(0, 5);
+}
+
+// Structured detail lines (objective/files/tests/...) for the ticket body.
+function renderPhaseDetailLines(phase) {
+  const fields = phase.fields || {};
+  const order = ["objective", "files", "commands", "tests", "rollback", "evidence"];
+  const labels = {
+    objective: "Objective",
+    files: "Files",
+    commands: "Commands",
+    tests: "Tests",
+    rollback: "Rollback",
+    evidence: "Evidence",
+  };
+  return order
+    .filter((key) => String(fields[key] || "").trim().length > 0)
+    .map((key) => `${labels[key]}: ${fields[key]}`);
 }
 
 function renderPhaseMarkdown(phase) {
+  const detailLines = renderPhaseDetailLines(phase);
+  const detailBlock =
+    detailLines.length > 0 ? `\n${detailLines.map((line) => `- ${line}`).join("\n")}` : "";
   const taskLines =
     phase.tasks.length > 0
       ? phase.tasks.map((task, index) => `${index + 1}. ${task}`).join("\n")
-      : "1. Define implementation tasks for this phase.";
+      : "1. Deliver the phase objective above with deterministic checks.";
   const acceptanceLines =
     phase.acceptanceCriteria.length > 0
       ? phase.acceptanceCriteria.map((item, index) => `${index + 1}. ${item}`).join("\n")
@@ -135,7 +260,7 @@ function renderPhaseMarkdown(phase) {
 
   return `### ${phase.title}
 - Estimated effort: ${phase.effort.label}
-- Dependencies: ${dependencyLine}
+- Dependencies: ${dependencyLine}${detailBlock}
 
 #### Implementation Tasks
 ${taskLines}
@@ -147,29 +272,38 @@ ${acceptanceLines}
 
 function buildTicket(phase, index) {
   const issueNumber = index + 1;
+  const phaseId = String(phase.phaseId || "").trim();
   const labels = ["sentinelayer", "build-guide", `phase-${issueNumber}`];
+  if (phaseId) {
+    labels.push(phaseId.toLowerCase());
+  }
   const dependencyLine =
     phase.dependencies.length > 0 ? phase.dependencies.join(", ") : "none (entry phase)";
   const acceptanceBlock = phase.acceptanceCriteria
     .map((item, criterionIndex) => `${criterionIndex + 1}. ${item}`)
     .join("\n");
   const taskBlock = phase.tasks.map((task, taskIndex) => `${taskIndex + 1}. ${task}`).join("\n");
+  const detailLines = renderPhaseDetailLines(phase);
+  const detailBlock = detailLines.length > 0 ? ["Details:", ...detailLines, ""] : [];
 
   return {
     id: `phase-${issueNumber}`,
+    phase_id: phaseId,
     title: phase.title,
     estimate_hours: {
       min: phase.effort.minHours,
       max: phase.effort.maxHours,
     },
     dependencies: phase.dependencies,
+    dependency_ids: phase.dependencyIds || [],
     labels,
     description: [
       `Dependencies: ${dependencyLine}`,
       `Estimated effort: ${phase.effort.label}`,
       "",
+      ...detailBlock,
       "Implementation tasks:",
-      taskBlock || "1. Define implementation tasks for this phase.",
+      taskBlock || "1. Deliver the phase objective above with deterministic checks.",
       "",
       "Acceptance criteria:",
       acceptanceBlock || "1. Phase outcomes are verified by deterministic checks.",
@@ -210,19 +344,42 @@ export function generateBuildGuide({
   const goal = parseGoal(source);
   const riskSurfaceCount = parseRiskSurfaceCount(source);
 
+  // Map declared phase ids (P0, P1, ...) to titles so a "Dependencies: P0-P1"
+  // line resolves to a real prerequisite graph instead of naive sequencing.
+  const idToTitle = new Map(
+    phases.filter((phase) => phase.phaseId).map((phase) => [phase.phaseId, phase.title])
+  );
+
   const resolvedPhases = phases.map((phase, index) => {
-    const dependencies = index > 0 ? [phases[index - 1].title] : [];
+    const declaredIds = parseDeclaredDependencies(phase.fields?.dependencies);
+    const knownIds = declaredIds.filter(
+      (id) => idToTitle.has(id) && idToTitle.get(id) !== phase.title
+    );
+    let dependencies;
+    if (knownIds.length > 0) {
+      // Honor the spec's declared dependency graph.
+      dependencies = knownIds.map((id) => idToTitle.get(id));
+    } else if (declaredIds.length === 0 && index > 0) {
+      // Nothing declared -> fall back to the previous phase only.
+      dependencies = [phases[index - 1].title];
+    } else {
+      // Declared "none", or deps that don't resolve -> entry phase.
+      dependencies = [];
+    }
     const effort = estimateEffortHours({
       phaseTitle: phase.title,
       taskCount: phase.tasks.length,
       riskSurfaceCount,
     });
-    const acceptanceCriteria = normalizeAcceptanceCriteria(source, phase.tasks);
+    const acceptanceCriteria = derivePhaseAcceptance(source, phase);
 
     return {
       title: phase.title,
+      phaseId: phase.phaseId,
       tasks: phase.tasks,
+      fields: phase.fields,
       dependencies,
+      dependencyIds: knownIds,
       effort,
       acceptanceCriteria,
     };

package/src/legacy-cli.js

@@ -2133,6 +2133,13 @@ Project: ${projectName}
 - [ ] Re-run gate and confirm clean status.
 - [ ] Merge only after quality gates are green.
 
+## Ticket Trail Contract (Per PR — lean, only if the project has a board/Jira)
+- [ ] One ticket = one PR; the PR body carries the ticket id.
+- [ ] On PR open: move the ticket to In-review + comment the PR link.
+- [ ] On merge + green: move the ticket to Done + comment "merged, gate green".
+- [ ] On gate fail: move the ticket to Blocked + the finding.
+- [ ] One update per transition — not every step (same discipline as senti).
+
 ## Command Roadmap (Local Terminal)
 - [ ] \`sentinel /omargate deep --path <repo>\`: local deep scan pipeline
 - [ ] \`sentinel /audit --path <repo>\`: security + quality audit summary
@@ -2182,6 +2189,7 @@ export function buildHandoffPrompt({
   buildFromExistingRepo,
   authMode,
   codingAgent,
+  sessionId,
 }) {
   const codingAgentProfile = resolveCodingAgent(codingAgent || DEFAULT_CODING_AGENT_ID);
   const codingAgentConfigPath = codingAgentProfile.configFile || "none";
@@ -2218,6 +2226,13 @@ Execution mode:
 - Keep commits scoped and deterministic.
 - Stop only for blocking secrets/permission gaps.
 
+Ticket trail (lean, only if the project has a board/Jira — do this on every PR, not every step):
+- One ticket = one PR; put the ticket id in the PR body.
+- On PR open -> move the ticket to In-review and comment the PR link.
+- On merge + green -> move the ticket to Done and comment "merged, gate green".
+- On gate fail -> move the ticket to Blocked with the finding.
+- Post one short senti update per transition (same discipline as the ticket).
+
 Coding agent profile:
 - Selected agent: ${codingAgentProfile.name} (${codingAgentProfile.id})
 - Prompt target: ${codingAgentProfile.promptTarget}
@@ -2245,7 +2260,16 @@ Repo context:
 - Target repo: ${repoSlug || "not provided"}
 - Workspace mode: ${buildFromExistingRepo ? "existing codebase" : "new scaffold"}
 
-## Multi-Agent Coordination (if session active)
+${
+  String(sessionId || "").trim()
+    ? `## Multi-Agent Coordination
+
+Project senti session (auto-created at init): \`${String(sessionId).trim()}\`
+- Join before starting work: \`sl session join ${String(sessionId).trim()} --agent <your-agent-name>\`
+- Post status updates as you work: \`sl session say ${String(sessionId).trim()} "<update>" --agent <your-agent-name>\`
+- Audit runs (\`sentinel /audit\`) relay per-persona progress into this session automatically, so swarm agents can watch each other's findings without losing context.`
+    : `## Multi-Agent Coordination (if session active)`
+}
 
 ${renderCoordinationNumberedList()}
 
@@ -2577,6 +2601,7 @@ async function writeInitConfigLockfile({
   secretName,
   repoSlug,
   workflowPath,
+  sessionId,
 }) {
   const lockDir = path.join(projectDir, ".sentinelayer");
   const configPath = path.join(lockDir, "config.json");
@@ -2588,6 +2613,7 @@ async function writeInitConfigLockfile({
     required_secret_name: String(secretName || "SENTINELAYER_TOKEN").trim() || "SENTINELAYER_TOKEN",
     repo_slug: normalizeRepoSlug(repoSlug || ""),
     workflow_path: path.relative(projectDir, workflowPath).replace(/\\/g, "/"),
+    session_id: String(sessionId || "").trim(),
   };
 
   await fsp.mkdir(lockDir, { recursive: true });
@@ -3145,6 +3171,26 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
       expectedSpecId: generatedSpecId || workflowSpecIdFromTemplate,
     });
   }
+  // Project senti session: every new project gets its own coordination room
+  // so agents (audit personas, builders, reviewers) can post progress and see
+  // each other's messages without losing context. Local-first + best-effort:
+  // an offline/unauthenticated init still completes.
+  let projectSession = null;
+  if (!boolFromEnv(process.env.SENTINELAYER_SKIP_PROJECT_SESSION)) {
+    try {
+      const { bootstrapProjectSession } = await import("./session/project-bootstrap.js");
+      projectSession = await bootstrapProjectSession({
+        projectDir,
+        projectName: effectiveProjectName,
+        skipGuides: true,
+      });
+    } catch (error) {
+      console.log(
+        pc.yellow(`! Senti project session bootstrap skipped: ${error?.message || error}`)
+      );
+    }
+  }
+
   const configLockfilePath = await writeInitConfigLockfile({
     projectDir,
     specId: workflowSpecId || generatedSpecId || workflowSpecIdFromTemplate,
@@ -3152,6 +3198,7 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
     secretName,
     repoSlug: interview.repoSlug || detectRepoSlug(projectDir) || "",
     workflowPath,
+    sessionId: projectSession?.sessionId || "",
   });
 
   await writeTextFile(
@@ -3177,6 +3224,7 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
       buildFromExistingRepo: interview.buildFromExistingRepo,
       authMode: effectiveAuthMode,
       codingAgent: interview.codingAgent,
+      sessionId: projectSession?.sessionId || "",
     })
   );
   await writeTextFile(
@@ -3189,6 +3237,19 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
     codingAgent: interview.codingAgent,
   });
 
+  // Guides go in after the coding-agent config so the config scaffold above
+  // doesn't see a guide-created AGENTS.md/CLAUDE.md and skip itself.
+  if (projectSession?.sessionId) {
+    try {
+      const { setupSessionGuides } = await import("./session/setup-guides.js");
+      projectSession.guides = await setupSessionGuides(projectSession.sessionId, {
+        targetPath: projectDir,
+      });
+    } catch (error) {
+      console.log(pc.yellow(`! Session coordination guides skipped: ${error?.message || error}`));
+    }
+  }
+
   await ensureSentinelStartScript(projectDir, effectiveProjectName);
 
   // Code scaffold: write starter source files, skip existing
@@ -3281,6 +3342,32 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
   printSection("Complete");
   console.log(pc.green(`✔ Sentinelayer orchestration initialized in ${projectDir}`));
   console.log(pc.green(`✔ Config lockfile written: ${configLockfilePath}`));
+  if (projectSession?.sessionId) {
+    console.log(pc.green(`✔ Senti project session created: ${projectSession.sessionId}`));
+    console.log(pc.green(`  Dashboard: ${projectSession.dashboardUrl}`));
+    if (projectSession.daemon?.spawned) {
+      console.log(
+        pc.green(`  Senti: managing this session (daemon pid ${projectSession.daemon.pid}, detached).`)
+      );
+    } else if (projectSession.daemon?.reason && projectSession.daemon.reason !== "disabled") {
+      console.log(
+        pc.yellow(
+          `  Senti daemon not started (${projectSession.daemon.reason}); run: sl session daemon ${projectSession.sessionId}`
+        )
+      );
+    }
+    console.log(
+      pc.gray(
+        `  Agents coordinate here: sl session join ${projectSession.sessionId} --agent <name>; audit runs post progress automatically.`
+      )
+    );
+  } else {
+    console.log(
+      pc.yellow(
+        "! Senti project session not created. Run `sl session start` inside the project to create the coordination room."
+      )
+    );
+  }
   if (workflowSpecId) {
     console.log(pc.green(`✔ Omar workflow spec binding validated: ${workflowSpecId}`));
   } else {

package/src/session/audit-reporter.js

@@ -0,0 +1,164 @@
+import { createAgentEvent } from "../events/schema.js";
+import { registerAgent } from "./agent-registry.js";
+import { listActiveSessions } from "./store.js";
+import { appendToStream } from "./stream.js";
+
+const ORCHESTRATOR_AGENT_ID = "audit-orchestrator";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function formatSeveritySummary(summary = {}) {
+  return `P0=${Number(summary.P0 || 0)} P1=${Number(summary.P1 || 0)} P2=${Number(summary.P2 || 0)} P3=${Number(summary.P3 || 0)}`;
+}
+
+function formatDurationSeconds(durationMs) {
+  return `${Math.max(0, Math.round(Number(durationMs || 0) / 1000))}s`;
+}
+
+/**
+ * Resolve which senti session an audit run should report into.
+ * Explicit id wins; otherwise the workspace's most recently active local
+ * session (the one `create-sentinelayer` bootstraps for new projects).
+ * Returns "" when relay is disabled or no session exists — audit runs
+ * never require a session.
+ */
+export async function resolveAuditSessionId({
+  targetPath = process.cwd(),
+  explicitSessionId = "",
+  disabled = false,
+} = {}) {
+  if (disabled) {
+    return "";
+  }
+  const explicit = normalizeString(explicitSessionId);
+  if (explicit) {
+    return explicit;
+  }
+  const sessions = await listActiveSessions({ targetPath }).catch(() => []);
+  if (!Array.isArray(sessions) || sessions.length === 0) {
+    return "";
+  }
+  const sorted = [...sessions].sort((left, right) =>
+    normalizeString(right.lastInteractionAt || right.updatedAt || right.createdAt).localeCompare(
+      normalizeString(left.lastInteractionAt || left.updatedAt || left.createdAt)
+    )
+  );
+  return normalizeString(sorted[0]?.sessionId);
+}
+
+/**
+ * Relay audit-orchestrator lifecycle events into a senti session so swarm
+ * personas can see each other's progress (start, per-agent completion,
+ * final summary) in the project's shared room.
+ *
+ * Posts are queued sequentially so transcript order matches audit order,
+ * and every post is best-effort: a session outage never fails an audit.
+ */
+export function createAuditSessionReporter({ sessionId, targetPath = process.cwd() } = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return null;
+  }
+
+  const registeredAgents = new Set();
+  let postedCount = 0;
+  let failedCount = 0;
+  let queue = Promise.resolve();
+
+  const post = (agentId, message) => {
+    const id = normalizeString(agentId) || ORCHESTRATOR_AGENT_ID;
+    queue = queue.then(async () => {
+      try {
+        if (!registeredAgents.has(id)) {
+          registeredAgents.add(id);
+          await registerAgent(normalizedSessionId, {
+            agentId: id,
+            model: "audit-persona",
+            role: "auditor",
+            targetPath,
+            trackProcessExit: false,
+          }).catch(() => {});
+        }
+        const event = createAgentEvent({
+          event: "session_message",
+          agent: { id, persona: id },
+          sessionId: normalizedSessionId,
+          payload: { message, channel: "session" },
+        });
+        await appendToStream(normalizedSessionId, event, { targetPath, awaitRemoteSync: true });
+        postedCount += 1;
+      } catch {
+        failedCount += 1;
+      }
+    });
+    return queue;
+  };
+
+  const handleEvent = (evt) => {
+    if (!evt || typeof evt !== "object") {
+      return;
+    }
+    const payload = evt.payload && typeof evt.payload === "object" ? evt.payload : {};
+    switch (evt.event) {
+      case "phase_start":
+        if (payload.phase === "dispatch") {
+          void post(
+            ORCHESTRATOR_AGENT_ID,
+            `🔍 Audit dispatch started: ${Number(payload.agentCount || 0)} persona(s), max ${Number(payload.maxParallel || 1)} in parallel.`
+          );
+        }
+        break;
+      case "dispatch":
+        void post(
+          payload.agentId,
+          `▶ Starting ${normalizeString(payload.persona) || normalizeString(payload.agentId)} audit (${normalizeString(payload.domain) || "general"}).`
+        );
+        break;
+      case "agent_complete":
+        void post(
+          payload.agentId,
+          `✅ ${normalizeString(payload.agentId)} audit complete: ${Number(payload.findingCount || 0)} finding(s) (${formatSeveritySummary(payload.summary)}), status=${normalizeString(payload.status) || "ok"}, ${formatDurationSeconds(payload.durationMs)}.`
+        );
+        break;
+      case "phase_complete":
+        if (payload.phase === "dispatch") {
+          void post(
+            ORCHESTRATOR_AGENT_ID,
+            `Dispatch complete: ${Number(payload.agentCount || 0)} persona result(s) in ${formatDurationSeconds(payload.durationMs)}.`
+          );
+        }
+        break;
+      default:
+        break;
+    }
+  };
+
+  const stats = () => ({ posted: postedCount, failed: failedCount });
+
+  const completed = async (result = {}) => {
+    await post(
+      ORCHESTRATOR_AGENT_ID,
+      `🏁 Audit run ${normalizeString(result.runId)} complete — ${formatSeveritySummary(result.summary)} across ${Array.isArray(result.agentResults) ? result.agentResults.length : 0} persona(s). Report: ${normalizeString(result.reportMarkdownPath)}`
+    );
+    await queue;
+    return stats();
+  };
+
+  const failed = async (error) => {
+    await post(
+      ORCHESTRATOR_AGENT_ID,
+      `❌ Audit run failed: ${normalizeString(error?.message) || "unknown error"}`
+    );
+    await queue;
+    return stats();
+  };
+
+  return {
+    sessionId: normalizedSessionId,
+    handleEvent,
+    completed,
+    failed,
+  };
+}