@m8i-51/shoal 0.1.14 → 0.1.16

package/.env.example

@@ -99,3 +99,9 @@ GITHUB_REPO=owner/repo
 
 MAX_EXPLORERS=4
 MAX_BROWSERS=2
+
+# Persona templates (optional)
+# Path to a local YAML/JSON file, or an npm package name.
+# If omitted, shoal auto-discovers personas.yaml / personas.yml / personas.json in the project root.
+# SHOAL_PERSONAS=./personas.yaml
+# SHOAL_PERSONAS=shoal-personas-ecommerce

package/framework/__tests__/coverage.test.ts

@@ -22,6 +22,7 @@ function makeEntry(overrides: Partial<RunCoverage> = {}): RunCoverage {
     byCategory: {},
     byLens: {},
     byScenario: {},
+    visitedPaths: [],
     ...overrides,
   };
 }

package/framework/__tests__/report.test.ts

@@ -52,6 +52,7 @@ function makeAgentLog(overrides: Partial<AgentLog> = {}): AgentLog {
     status: "completed",
     iterations: 3,
     actions: [],
+    visitedPaths: [],
     issuesPosted: [],
     regressionChecks: [],
     error: null,

package/framework/coverage.ts

@@ -10,6 +10,7 @@ export interface RunCoverage {
   byCategory: Record<string, number>;
   byLens: Record<string, number>;
   byScenario: Record<string, number>;
+  visitedPaths: string[];
 }
 
 export interface Coverage {
@@ -45,10 +46,18 @@ function saveCoverage(coverage: Coverage): void {
   fs.writeFileSync(COVERAGE_PATH, JSON.stringify(coverage, null, 2), "utf-8");
 }
 
+export function getLastRunPaths(): { visitedPaths: string[]; runId: string } | null {
+  const coverage = loadCoverage();
+  if (coverage.entries.length === 0) return null;
+  const last = coverage.entries[coverage.entries.length - 1];
+  return { visitedPaths: last.visitedPaths ?? [], runId: last.runId };
+}
+
 export function updateCoverage(
   runId: string,
   findings: Finding[],
   agentAssignments: Map<string, { scenario?: Scenario; lens?: string }>,
+  visitedPaths: string[] = [],
 ): void {
   const coverage = loadCoverage();
 
@@ -69,6 +78,7 @@ export function updateCoverage(
     }
   }
 
+  const uniquePaths = [...new Set(visitedPaths)].sort();
   coverage.entries.push({
     runId,
     timestamp: new Date().toISOString(),
@@ -76,6 +86,7 @@ export function updateCoverage(
     byCategory,
     byLens,
     byScenario,
+    visitedPaths: uniquePaths,
   });
 
   if (coverage.entries.length > MAX_ENTRIES) {

package/framework/diary.ts

@@ -0,0 +1,96 @@
+import * as fs from "fs";
+import * as path from "path";
+import { createLLMClient } from "./llm-client.js";
+import type { Finding } from "./types.js";
+
+function loadFindings(runId: string): Finding[] {
+  const dir = path.join(process.cwd(), "findings", runId);
+  if (!fs.existsSync(dir)) return [];
+  const out: Finding[] = [];
+  for (const file of fs.readdirSync(dir)) {
+    if (!file.endsWith(".json")) continue;
+    try {
+      out.push(JSON.parse(fs.readFileSync(path.join(dir, file), "utf-8")));
+    } catch { /* skip */ }
+  }
+  return out;
+}
+
+function extractEvents(lines: string[]): string[] {
+  const events: string[] = [];
+  let navCount = 0;
+  for (const line of lines) {
+    if (/^\[(explorer|browser|regression)\] .+ (start|done|cancelled)/.test(line)) {
+      events.push(line.trim());
+    } else if (/→ \[findings\] saved:/.test(line)) {
+      events.push(line.trim());
+    } else if (/→ navigate\(/.test(line) && navCount < 25) {
+      navCount++;
+      const t = line.trim();
+      events.push(t.length > 100 ? t.slice(0, 100) + "…" : t);
+    }
+  }
+  return events;
+}
+
+export async function generateDiary(runId: string, logLines: string[]): Promise<string> {
+  const findings = loadFindings(runId);
+  const events = extractEvents(logLines);
+
+  const findingsSummary = findings.length > 0
+    ? findings.map((f) => `- [${f.category}] ${f.title}`).join("\n")
+    : "（発見なし）";
+
+  const eventsText = events.length > 0
+    ? events.join("\n")
+    : "（イベントログなし）";
+
+  const { client, defaultModel } = createLLMClient();
+
+  const msg = await client.createMessage({
+    model: defaultModel,
+    max_tokens: 1500,
+    system: `あなたは AI エージェント群の探索を、読み手の心を動かす「探索日誌」として記録する書記役です。
+エンジニアだけでなく、プロダクトオーナーやデザイナーにも伝わる、物語体の日本語で書いてください。
+技術的なログを人間味あふれる冒険譚に変換するのがあなたの仕事です。`,
+    tools: [],
+    messages: [
+      {
+        role: "user",
+        content: `以下の探索ログをもとに、shoal エージェント群の「探索日誌」を Markdown 形式で作成してください。
+
+## 発見された問題（${findings.length}件）
+${findingsSummary}
+
+## 主要イベントログ
+${eventsText}
+
+## 作成ルール
+- タイトルは \`# 探索日誌 — ${runId}\`
+- explorer エージェントを「地図製作者」、browser を「現地調査員」、regression を「検証係」として擬人化する
+- 各エージェントの動きを旅人の行動として物語る（「〇〇は△△のページへと足を踏み入れた」など）
+- 発見した問題を「驚き」や「発見」として自然に物語に組み込む
+- 全体で 400〜700 字程度のコンパクトな物語にまとめる
+- 最後に「## 今回の旅のまとめ」セクションを箇条書きで追加する
+- Markdown のみで出力する（説明文は不要）`,
+      },
+    ],
+  });
+
+  const text = msg.content
+    .filter((b) => b.type === "text")
+    .map((b) => (b as { type: "text"; text: string }).text)
+    .join("");
+
+  const diaryPath = path.join(process.cwd(), "logs", `diary_${runId}.md`);
+  fs.mkdirSync(path.dirname(diaryPath), { recursive: true });
+  fs.writeFileSync(diaryPath, text, "utf-8");
+
+  return text;
+}
+
+export function getDiaryPath(runId: string): string | null {
+  if (!/^run_\d+$/.test(runId)) return null;
+  const p = path.join(process.cwd(), "logs", `diary_${runId}.md`);
+  return fs.existsSync(p) ? p : null;
+}

package/framework/persona-pack.ts

@@ -0,0 +1,137 @@
+import * as fs from "fs";
+import * as path from "path";
+import { parse as parseYaml } from "yaml";
+
+export interface PersonaTemplate {
+  name: string;
+  role: string;
+  persona: string;
+  lenses?: string[];
+}
+
+export interface PersonaPack {
+  name: string;
+  version?: string;
+  personas: PersonaTemplate[];
+}
+
+function isPersonaTemplate(v: unknown): v is PersonaTemplate {
+  if (typeof v !== "object" || v === null) return false;
+  const o = v as Record<string, unknown>;
+  return typeof o.name === "string" && typeof o.role === "string" && typeof o.persona === "string";
+}
+
+function parseRaw(raw: unknown, source: string): PersonaPack | null {
+  if (typeof raw !== "object" || raw === null) {
+    console.warn(`[persona-pack] ${source}: expected an object, got ${typeof raw}`);
+    return null;
+  }
+  const obj = raw as Record<string, unknown>;
+
+  // Support { personas: [...] } or bare array
+  const list = Array.isArray(obj) ? obj : Array.isArray(obj.personas) ? obj.personas : null;
+  if (!list) {
+    console.warn(`[persona-pack] ${source}: no "personas" array found`);
+    return null;
+  }
+
+  const personas = list.filter((v) => {
+    if (!isPersonaTemplate(v)) {
+      console.warn(`[persona-pack] ${source}: skipping invalid entry (missing name/role/persona)`);
+      return false;
+    }
+    return true;
+  }) as PersonaTemplate[];
+
+  if (personas.length === 0) {
+    console.warn(`[persona-pack] ${source}: 0 valid personas found`);
+    return null;
+  }
+
+  const packName = typeof obj.name === "string" ? obj.name : source;
+  const version = typeof obj.version === "string" ? obj.version : undefined;
+  return { name: packName, version, personas };
+}
+
+function loadFromFile(filePath: string): PersonaPack | null {
+  const resolved = path.isAbsolute(filePath)
+    ? filePath
+    : path.join(process.cwd(), filePath);
+
+  if (!fs.existsSync(resolved)) {
+    console.warn(`[persona-pack] file not found: ${resolved}`);
+    return null;
+  }
+
+  const content = fs.readFileSync(resolved, "utf-8");
+  const ext = path.extname(resolved).toLowerCase();
+  let raw: unknown;
+  try {
+    raw = ext === ".json" ? JSON.parse(content) : parseYaml(content);
+  } catch (e) {
+    console.warn(`[persona-pack] failed to parse ${resolved}: ${e}`);
+    return null;
+  }
+  return parseRaw(raw, resolved);
+}
+
+async function loadFromPackage(packageName: string): Promise<PersonaPack | null> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const mod = await import(packageName);
+    // Support both default export and named export
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    const raw = mod?.default ?? mod?.personas ? { personas: mod.personas } : mod;
+    return parseRaw(raw, packageName);
+  } catch (e) {
+    console.warn(`[persona-pack] failed to load package "${packageName}": ${e}`);
+    return null;
+  }
+}
+
+function lookupLocalDefault(): PersonaPack | null {
+  for (const name of ["personas.yaml", "personas.yml", "personas.json"]) {
+    const p = path.join(process.cwd(), name);
+    if (fs.existsSync(p)) return loadFromFile(p);
+  }
+  return null;
+}
+
+export async function loadPersonaPack(): Promise<PersonaPack | null> {
+  const source = process.env.SHOAL_PERSONAS?.trim();
+
+  if (!source) {
+    // Auto-discover personas.yaml / personas.yml / personas.json in cwd
+    const pack = lookupLocalDefault();
+    if (pack) console.log(`[persona-pack] loaded "${pack.name}" (${pack.personas.length} templates)`);
+    return pack;
+  }
+
+  // Looks like a file path
+  if (source.startsWith(".") || source.startsWith("/")) {
+    const pack = loadFromFile(source);
+    if (pack) console.log(`[persona-pack] loaded "${pack.name}" (${pack.personas.length} templates) from ${source}`);
+    return pack;
+  }
+
+  // Treat as npm package name
+  const pack = await loadFromPackage(source);
+  if (pack) console.log(`[persona-pack] loaded "${pack.name}" (${pack.personas.length} templates) from package ${source}`);
+  return pack;
+}
+
+export function formatPackForPrompt(pack: PersonaPack): string {
+  const lines = [
+    `[Persona Templates from "${pack.name}"${pack.version ? ` v${pack.version}` : ""}]`,
+    "Prefer using these as a starting point. You may adapt names/personas to fit the app, but keep the role archetype intact.",
+    "",
+    ...pack.personas.map((p, i) =>
+      [
+        `${i + 1}. ${p.name} (${p.role})`,
+        `   ${p.persona}`,
+        ...(p.lenses?.length ? [`   Suggested lenses: ${p.lenses.join(", ")}`] : []),
+      ].join("\n")
+    ),
+  ];
+  return lines.join("\n");
+}

package/framework/trackers/asana.ts

@@ -48,6 +48,19 @@ export class AsanaTracker implements IssueTracker {
     return url;
   }
 
+  async commentOnIssue(issueNumber: number | string, body: string): Promise<boolean> {
+    const res = await fetch(`https://app.asana.com/api/1.0/tasks/${issueNumber}/stories`, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({ data: { text: body } }),
+    });
+    if (!res.ok) {
+      const msg = await res.text().catch(() => "");
+      console.error(`[asana] failed to comment on task ${issueNumber} (${res.status}): ${msg.slice(0, 200)}`);
+    }
+    return res.ok;
+  }
+
   async fetchOpenIssues(): Promise<OpenIssue[]> {
     const res = await fetch(
       `https://app.asana.com/api/1.0/tasks?project=${this.projectId}&completed_since=now&opt_fields=gid,name&limit=50`,

package/framework/trackers/backlog.ts

@@ -46,6 +46,20 @@ export class BacklogTracker implements IssueTracker {
     return url;
   }
 
+  async commentOnIssue(issueNumber: number | string, body: string): Promise<boolean> {
+    const form = new URLSearchParams({ content: body });
+    const res = await fetch(this.endpoint(`/issues/${issueNumber}/comments`), {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: form,
+    });
+    if (!res.ok) {
+      const msg = await res.text().catch(() => "");
+      console.error(`[backlog] failed to comment on issue ${issueNumber} (${res.status}): ${msg.slice(0, 200)}`);
+    }
+    return res.ok;
+  }
+
   async fetchOpenIssues(): Promise<OpenIssue[]> {
     const res = await fetch(this.endpoint("/issues", {
       "projectId[]": String(this.projectId),

package/framework/trackers/github.ts

@@ -21,4 +21,22 @@ export class GitHubTracker implements IssueTracker {
   async fetchClosedIssues(): Promise<ClosedIssue[]> {
     return ghFetchClosed(this.opts);
   }
+
+  async commentOnIssue(issueNumber: number | string, body: string): Promise<boolean> {
+    const [owner, repo] = this.opts.repo.split("/");
+    const res = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${issueNumber}/comments`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.opts.token}`,
+        "Content-Type": "application/json",
+        Accept: "application/vnd.github+json",
+      },
+      body: JSON.stringify({ body }),
+    });
+    if (!res.ok) {
+      const msg = await res.text().catch(() => "");
+      console.error(`[github] failed to comment on issue #${issueNumber} (${res.status}): ${msg.slice(0, 200)}`);
+    }
+    return res.ok;
+  }
 }

package/framework/trackers/index.ts

@@ -44,6 +44,15 @@ export class AggregatedTracker implements IssueTracker {
       return r.value;
     });
   }
+
+  async commentOnIssue(issueNumber: number | string, body: string): Promise<boolean> {
+    if (this.trackers.length === 0) return false;
+    const results = await Promise.allSettled(this.trackers.map((t) => t.commentOnIssue(issueNumber, body)));
+    for (const r of results) {
+      if (r.status === "rejected") console.error("[trackers] commentOnIssue error:", r.reason);
+    }
+    return results.some((r) => r.status === "fulfilled" && r.value === true);
+  }
 }
 
 export function buildTrackers(): AggregatedTracker {

package/framework/trackers/jira.ts

@@ -73,6 +73,25 @@ export class JiraTracker implements IssueTracker {
     }));
   }
 
+  async commentOnIssue(issueNumber: number | string, body: string): Promise<boolean> {
+    const res = await fetch(`${this.baseUrl}/rest/api/3/issue/${issueNumber}/comment`, {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({
+        body: {
+          type: "doc",
+          version: 1,
+          content: [{ type: "paragraph", content: [{ type: "text", text: body }] }],
+        },
+      }),
+    });
+    if (!res.ok) {
+      const msg = await res.text().catch(() => "");
+      console.error(`[jira] failed to comment on issue ${issueNumber} (${res.status}): ${msg.slice(0, 200)}`);
+    }
+    return res.ok;
+  }
+
   async fetchClosedIssues(): Promise<ClosedIssue[]> {
     const jql = encodeURIComponent(
       `project = ${this.projectKey} AND statusCategory = Done AND labels = "feedback-agent" ORDER BY updated DESC`

package/framework/trackers/notion.ts

@@ -50,6 +50,22 @@ export class NotionTracker implements IssueTracker {
     return url;
   }
 
+  async commentOnIssue(issueNumber: number | string, body: string): Promise<boolean> {
+    const res = await fetch("https://api.notion.com/v1/comments", {
+      method: "POST",
+      headers: this.headers,
+      body: JSON.stringify({
+        parent: { page_id: String(issueNumber) },
+        rich_text: [{ type: "text", text: { content: body } }],
+      }),
+    });
+    if (!res.ok) {
+      const msg = await res.text().catch(() => "");
+      console.error(`[notion] failed to comment on page ${issueNumber} (${res.status}): ${msg.slice(0, 200)}`);
+    }
+    return res.ok;
+  }
+
   async fetchOpenIssues(): Promise<OpenIssue[]> {
     return this._queryPages("Open");
   }

package/framework/trackers/types.ts

@@ -17,4 +17,5 @@ export interface IssueTracker {
   createIssue(title: string, body: string, labels: string[]): Promise<string | null>;
   fetchOpenIssues(): Promise<OpenIssue[]>;
   fetchClosedIssues(): Promise<ClosedIssue[]>;
+  commentOnIssue(issueNumber: number | string, body: string): Promise<boolean>;
 }

package/framework/types.ts

@@ -43,6 +43,7 @@ export interface AgentLog {
   status: "completed" | "error" | "iteration_limit";
   iterations: number;
   actions: ToolAction[];
+  visitedPaths: string[];
   issuesPosted: IssuePosted[];
   regressionChecks: RegressionCheck[];
   error: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m8i-51/shoal",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "type": "module",
   "description": "Multi-agent web exploration framework — finds bugs, UX issues, and missing features by running AI agents against your app",
   "repository": {
@@ -42,7 +42,8 @@
     "express-rate-limit": "^8.5.0",
     "openai": "^6.33.0",
     "playwright": "^1.59.1",
-    "tsx": "^4.21.0"
+    "tsx": "^4.21.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",

package/run.ts

@@ -17,7 +17,8 @@ import type { Tool } from "./framework/llm-client";
 import { createMessageWithRetry, runAgentLoop, sleep, rateLimitRetries } from "./framework/agent-loop";
 import { collectedFindings, initRunLog, saveRunLog, saveFinding, runLog } from "./framework/findings";
 import { loadAgents, addAgent, retireAgent } from "./framework/agent-store";
-import { updateCoverage, computeWeightedSummary } from "./framework/coverage";
+import { updateCoverage, computeWeightedSummary, getLastRunPaths } from "./framework/coverage";
+import { loadPersonaPack, formatPackForPrompt, type PersonaPack } from "./framework/persona-pack";
 import { buildTrackers } from "./framework/trackers/index";
 import {
   setupObservation,
@@ -231,6 +232,10 @@ function makeExecutor(agentLog: AgentLog, scenarioOutcomes: ScenarioOutcome[], s
             `**Regression:** #${original_issue_number} "${original_issue_title}" has reappeared.\n\n${body}\n\n---\n*This issue was auto-generated by an AI regression agent*`,
             ["regression", "feedback-agent"]
           );
+          await trackers.commentOnIssue(
+            original_issue_number,
+            `⚠️ **Regression detected** by AI agent on ${new Date().toISOString().slice(0, 10)}\n\n${body}${url ? `\n\nNew issue: ${url}` : ""}`
+          );
           const check: RegressionCheck = {
             issueNumber: Number(original_issue_number),
             issueTitle: String(original_issue_title),
@@ -248,6 +253,10 @@ function makeExecutor(agentLog: AgentLog, scenarioOutcomes: ScenarioOutcome[], s
           const { original_issue_number, original_issue_title, note } = input as {
             original_issue_number: number; original_issue_title: string; note: string;
           };
+          await trackers.commentOnIssue(
+            original_issue_number,
+            `✅ **Verified as fixed** by AI agent on ${new Date().toISOString().slice(0, 10)}\n\n${note}`
+          );
           agentLog.regressionChecks.push({
             issueNumber: Number(original_issue_number),
             issueTitle: String(original_issue_title),
@@ -304,6 +313,7 @@ async function runExplorer(
     status: "completed",
     iterations: 0,
     actions: [],
+    visitedPaths: [],
     issuesPosted: [],
     regressionChecks: [],
     error: null,
@@ -357,6 +367,7 @@ async function runRegressionAgent(
     status: "completed",
     iterations: 0,
     actions: [],
+    visitedPaths: [],
     issuesPosted: [],
     regressionChecks: [],
     error: null,
@@ -405,6 +416,16 @@ const PERSONA_DESIGNER_TOOLS: Anthropic.Tool[] = [
     description: "Get a weighted summary of what has been explored across past runs. Use this to identify underrepresented lenses and perspectives before deciding whom to hire. / 過去のrunで何がどれだけ探索されたかの重み付きサマリーを取得する。採用方針の決定前に確認すること",
     input_schema: { type: "object", properties: {}, required: [] },
   },
+  {
+    name: "get_path_coverage",
+    description: "Get the list of URL paths visited in the previous run. Use this to identify unexplored areas of the app and recruit agents likely to visit NEW paths. / 前回のrunで訪れたURLパス一覧を取得する。未探索エリアを特定し、新しいパスを訪れる可能性の高いペルソナを採用するために使う",
+    input_schema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "get_persona_templates",
+    description: "Get the persona template pack defined for this project. Prefer these archetypes when adding agents — adapt names/details to fit the app context but keep the role intact. / このプロジェクト用に定義されたペルソナテンプレート一覧を取得する。エージェントを追加する際はまずこのテンプレートから選ぶこと",
+    input_schema: { type: "object", properties: {}, required: [] },
+  },
   {
     name: "get_open_issues",
     description: "Get the titles and labels of currently open GitHub Issues (known problems). Use this to understand what is already known and recruit agents who are likely to explore DIFFERENT areas. / 現在オープンなGitHub Issueのタイトルとラベルを取得する。既知の問題を把握し、未探索領域を掘れるペルソナを採用するために使う",
@@ -448,6 +469,8 @@ async function runPersonaDesigner(
   openIssues: { number: number | string; title: string; labels: string[] }[],
   scenarios: Scenario[],
   testAccounts: TestAccount[] = [],
+  lastRunPaths: { visitedPaths: string[]; runId: string } | null = null,
+  personaPack: PersonaPack | null = null,
 ): Promise<void> {
   console.log("\n[persona-designer] starting...");
   const messages: Anthropic.MessageParam[] = [
@@ -458,6 +481,14 @@ async function runPersonaDesigner(
     ? `\n[Available Test Accounts (one per role)]\n${testAccounts.map((a) => `- ${a.role}: ${a.email}`).join("\n")}\nWhen recruiting agents, match each persona's role to one of these accounts so they can operate with appropriate permissions.`
     : "";
 
+  const pathCoverageStep = lastRunPaths
+    ? "3. Call get_path_coverage to see which URL paths were visited last run — recruit agents whose role would naturally take them to DIFFERENT or unexplored paths"
+    : "3. (No previous run data yet — skip get_path_coverage)";
+
+  const personaTemplateStep = personaPack
+    ? "2. Call get_persona_templates to get project-specific persona archetypes — prefer these over inventing new personas from scratch"
+    : "2. (No persona templates configured — invent personas that fit the app context)";
+
   const systemPrompt = `You are the persona designer for "${productSpec.appName}".
 You create and manage test agents that simulate real users of the app.
 
@@ -466,11 +497,13 @@ ${orgGuidance}${accountContext}
 
 [Steps]
 1. Call get_coverage to review which lenses and categories are underrepresented in past runs
-2. Call get_open_issues to understand what problems are already known — recruit agents likely to find DIFFERENT issues in unexplored areas
-3. Call get_scenarios to see the user test scenarios generated for this run — about 70% of agents will be assigned a scenario, so recruit personas whose background fits those scenarios
-4. Call get_agents to check the current agent roster
-5. Add 2–3 agents with add_agent — balance between scenario-fit personas (step 3), underrepresented lenses (step 1), and unexplored areas (step 2)${testAccounts.length > 0 ? "\n   — assign each agent a role that matches one of the available test accounts" : ""}
-6. If there are agents with old createdAt dates (oldest 1–2), retire them with retire_agent`;
+${personaTemplateStep}
+${pathCoverageStep}
+4. Call get_open_issues to understand what problems are already known — recruit agents likely to find DIFFERENT issues in unexplored areas
+5. Call get_scenarios to see the user test scenarios generated for this run — about 70% of agents will be assigned a scenario, so recruit personas whose background fits those scenarios
+6. Call get_agents to check the current agent roster
+7. Add 2–3 agents with add_agent — balance between scenario-fit personas (step 5), underrepresented lenses (step 1), unexplored paths (step 3), and unexplored areas (step 4)${testAccounts.length > 0 ? "\n   — assign each agent a role that matches one of the available test accounts" : ""}
+8. If there are agents with old createdAt dates (oldest 1–2), retire them with retire_agent`;
 
   try {
     let iterations = 0;
@@ -494,6 +527,20 @@ ${orgGuidance}${accountContext}
         if (toolUse.name === "get_coverage") {
           result = computeWeightedSummary().formatted;
           console.log("  [persona-designer] coverage summary fetched");
+        } else if (toolUse.name === "get_persona_templates") {
+          if (!personaPack) {
+            result = "(no persona templates configured — set SHOAL_PERSONAS env var or add personas.yaml to your project)";
+          } else {
+            result = formatPackForPrompt(personaPack);
+          }
+          console.log(`  [persona-designer] persona templates fetched (${personaPack?.personas.length ?? 0})`);
+        } else if (toolUse.name === "get_path_coverage") {
+          if (!lastRunPaths || lastRunPaths.visitedPaths.length === 0) {
+            result = "(no path coverage data yet — this is the first run or no paths were recorded)";
+          } else {
+            result = `Paths visited in last run (${lastRunPaths.runId}):\n${lastRunPaths.visitedPaths.map((p) => `- ${p}`).join("\n")}\n\nRecruit agents whose role naturally takes them to paths NOT in this list.`;
+          }
+          console.log(`  [persona-designer] path coverage fetched (${lastRunPaths?.visitedPaths.length ?? 0} paths)`);
         } else if (toolUse.name === "get_open_issues") {
           if (openIssues.length === 0) {
             result = "(no open issues — either GitHub is not configured or there are no known issues yet)";
@@ -555,6 +602,7 @@ interface BrowserAgentLog {
   status: "completed" | "error" | "iteration_limit";
   iterations: number;
   actions: BrowserAction[];
+  visitedPaths: string[];
   feedbacksSaved: { title: string; category: string; findingId: string }[];
   error: string | null;
 }
@@ -690,6 +738,7 @@ async function executeBrowserTool(
         await page.goto(`${BASE_URL}${navPath}`, { waitUntil: "networkidle" });
         await page.waitForTimeout(3000);
         screenshot = await takeScreenshot(page, `navigate_${navPath.replace(/\//g, "_")}`);
+        agentLog.visitedPaths.push(navPath);
         resultText = `Navigated to ${navPath}`;
         break;
       }
@@ -870,6 +919,7 @@ async function runBrowserAgent(
     status: "completed",
     iterations: 0,
     actions: [],
+    visitedPaths: [],
     feedbacksSaved: [],
     error: null,
   };
@@ -1102,7 +1152,9 @@ async function main() {
     }
 
     // 4. HR agent
-    await runPersonaDesigner(productSpec, orgDesign.personaGuidance, openIssues, scenarios, testAccounts);
+    const lastRunPaths = getLastRunPaths();
+    const personaPack = await loadPersonaPack();
+    await runPersonaDesigner(productSpec, orgDesign.personaGuidance, openIssues, scenarios, testAccounts, lastRunPaths, personaPack);
 
     // 5. load agents + closed issues
     const allAgents = loadAgents();
@@ -1159,7 +1211,7 @@ async function main() {
     browserAgents.forEach((a) => console.log(`  - ${a.name} (${a.role})`));
 
     await sleep(2000);
-    await Promise.all(
+    const browserLogs = await Promise.all(
       browserAgents.map(async (agent) => {
         const assignment = pickAssignment(dispatchIdx++, scenarios);
         agentAssignments.set(agent.id, assignment);
@@ -1182,6 +1234,7 @@ async function main() {
         }
       })
     );
+    const allVisitedPaths = browserLogs.flatMap((log) => log.visitedPaths);
 
     // 8. triage (API + browser findings)
     await sleep(2000);
@@ -1199,7 +1252,7 @@ async function main() {
     console.log(`\n[report] ${reportPath}`);
 
     // 10. update coverage
-    updateCoverage(runLog.runId, collectedFindings, agentAssignments);
+    updateCoverage(runLog.runId, collectedFindings, agentAssignments, allVisitedPaths);
 
   } finally {
     await browser.close();