opencastle 0.27.3 → 0.28.0

package/src/dashboard/src/pages/index.astro

@@ -44,13 +44,13 @@ try {
     <nav class="dash-sidebar" id="dash-sidebar">
       <ul class="dash-sidebar__list">
         <li><a class="dash-sidebar__link dash-sidebar__link--active" href="#overall-section" data-section="overall-section" aria-label="Overview section">Overview</a></li>
-        <li><a class="dash-sidebar__link" href="#convoy-section" data-section="convoy-section" aria-label="Convoy section">Convoy</a></li>
         <li><a class="dash-sidebar__link" href="#tasks-section" data-section="tasks-section" aria-label="Tasks section">Tasks</a></li>
         <li><a class="dash-sidebar__link" href="#quality-section" data-section="quality-section" aria-label="Quality section">Quality</a></li>
         <li><a class="dash-sidebar__link" href="#reliability-section" data-section="reliability-section" aria-label="Reliability section">Reliability</a></li>
         <li><a class="dash-sidebar__link" href="#drift-section" data-section="drift-section" aria-label="Drift section">Drift</a></li>
         <li><a class="dash-sidebar__link" href="#outputs-section" data-section="outputs-section" aria-label="Outputs section">Outputs</a></li>
         <li><a class="dash-sidebar__link" href="#event-timeline-section" data-section="event-timeline-section" aria-label="Event Log section">Event Log</a></li>
+        <li><a class="dash-sidebar__link" href="#convoy-section" data-section="convoy-section" aria-label="Convoy section">Convoy</a></li>
       </ul>
     </nav>
 
@@ -59,11 +59,11 @@ try {
     <section class="overall-stats" id="overall-section" data-nav-section>
       <div class="overall-stats__header">
         <h2 class="overall-stats__title">Overall Stats</h2>
-        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: How all runs behave across your project." data-tooltip="How all runs behave across your project.">ℹ️</span>
+        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: How all runs behave across your project." data-tooltip="How all runs behave across your project."><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg></span>
       </div>
       <div class="overall-stats__grid">
         <div class="overall-kpi" id="overall-total-runs">
-          <span class="overall-kpi__label">Total Runs <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Number of convoy runs executed" data-tooltip="Number of convoy runs executed">ℹ️</span></span>
+          <span class="overall-kpi__label">Total Runs <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Number of convoy runs executed" data-tooltip="Number of convoy runs executed"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg></span></span>
           <span class="overall-kpi__value">&mdash;</span>
         </div>
         <div class="overall-kpi" id="overall-running">
@@ -94,7 +94,7 @@ try {
       <div class="convoy-detail-header__top">
         <h2 class="convoy-detail-header__name" id="selected-convoy-name">No convoy selected</h2>
         <span class="status-badge" id="selected-convoy-status" role="status"></span>
-        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: A convoy is a set of AI tasks working together on one goal." data-tooltip="A convoy is a set of AI tasks working together on one goal.">ℹ️</span>
+        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: A convoy is a set of AI tasks working together on one goal." data-tooltip="A convoy is a set of AI tasks working together on one goal."><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg></span>
       </div>
       <p class="convoy-status-explanation" id="convoy-status-explanation" role="status" aria-live="polite"></p>
       <div class="convoy-detail-header__meta" id="selected-convoy-meta">
@@ -106,7 +106,7 @@ try {
     <section class="chart-card" id="tasks-section" data-nav-section style="display:none">
       <div class="chart-card__header">
         <h2 class="chart-card__title">Tasks</h2>
-        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Individual units of work in this convoy." data-tooltip="Individual units of work in this convoy.">ℹ️</span>
+        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Individual units of work in this convoy." data-tooltip="Individual units of work in this convoy."><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg></span>
         <p class="chart-card__desc" id="tasks-section-desc">Task breakdown for the selected convoy</p>
       </div>
       <div class="chart-card__body" id="tasks-section-body">
@@ -120,7 +120,7 @@ try {
     <section class="chart-card" id="quality-section" data-nav-section style="display:none">
       <div class="chart-card__header">
         <h2 class="chart-card__title">Quality / Review</h2>
-        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Code review results and dispute resolution." data-tooltip="Code review results and dispute resolution.">ℹ️</span>
+        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Code review results and dispute resolution." data-tooltip="Code review results and dispute resolution."><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg></span>
         <p class="chart-card__desc">Code review results and quality gate outcomes for the selected convoy</p>
       </div>
       <div class="chart-card__body">
@@ -133,7 +133,7 @@ try {
     <section class="chart-card" id="reliability-section" data-nav-section style="display:none">
       <div class="chart-card__header">
         <h2 class="chart-card__title">Reliability</h2>
-        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Errors, retry attempts, and safety mechanisms." data-tooltip="Errors, retry attempts, and safety mechanisms.">ℹ️</span>
+        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Errors, retry attempts, and safety mechanisms." data-tooltip="Errors, retry attempts, and safety mechanisms."><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg></span>
         <p class="chart-card__desc">Retry queue and error overview for the selected convoy</p>
       </div>
       <div class="chart-card__body">
@@ -150,7 +150,7 @@ try {
     <section class="chart-card" id="drift-section" data-nav-section style="display:none">
       <div class="chart-card__header">
         <h2 class="chart-card__title">Drift</h2>
-        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: How far the actual work deviated from the original plan." data-tooltip="How far the actual work deviated from the original plan.">ℹ️</span>
+        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: How far the actual work deviated from the original plan." data-tooltip="How far the actual work deviated from the original plan."><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg></span>
         <p class="chart-card__desc">Plan adherence and deviation metrics for the selected convoy</p>
       </div>
       <div class="chart-card__body">
@@ -163,7 +163,7 @@ try {
     <section class="chart-card" id="outputs-section" data-nav-section style="display:none">
       <div class="chart-card__header">
         <h2 class="chart-card__title">Outputs &amp; Artifacts</h2>
-        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Files, data, and summaries produced by this convoy." data-tooltip="Files, data, and summaries produced by this convoy.">ℹ️</span>
+        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Files, data, and summaries produced by this convoy." data-tooltip="Files, data, and summaries produced by this convoy."><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg></span>
         <p class="chart-card__desc">Files, summaries, and structured data produced by tasks in this convoy</p>
       </div>
       <div class="chart-card__body">
@@ -176,7 +176,7 @@ try {
     <section class="chart-card" id="event-timeline-section" data-nav-section style="display:none">
       <div class="chart-card__header">
         <h2 class="chart-card__title">Event Timeline</h2>
-        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Chronological log of everything that happened during this run." data-tooltip="Chronological log of everything that happened during this run.">ℹ️</span>
+        <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Chronological log of everything that happened during this run." data-tooltip="Chronological log of everything that happened during this run."><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg></span>
         <p class="chart-card__desc">Convoy events in reverse chronological order</p>
       </div>
       <div class="chart-card__body">
@@ -424,8 +424,21 @@ try {
     }
   }
 
+  async function loadJson(path) {
+    try {
+      const res = await fetch(path);
+      if (!res.ok) return [];
+      return await res.json();
+    } catch {
+      return [];
+    }
+  }
+
   // ── Helpers ───────────────────────────────────────────────
 
+  // ── Info Icon SVG ─────────────────────────────────────
+  const INFO_ICON = '<svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>';
+
   const TIER_COLORS = {
     premium: '#f59e0b',
     standard: '#a78bfa',
@@ -2009,7 +2022,7 @@ try {
     el.innerHTML = cards.map(card =>
       '<div class="task-summary-card task-summary-card--' + card.mod + '">' +
         '<span class="task-summary-card__label">' + escapeHtml(card.label) +
-          ' <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: ' + escapeHtml(card.tooltip) + '" data-tooltip="' + escapeHtml(card.tooltip) + '">\u2139\uFE0F</span>' +
+          ' <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: ' + escapeHtml(card.tooltip) + '" data-tooltip="' + escapeHtml(card.tooltip) + '">' + INFO_ICON + '</span>' +
         '</span>' +
         '<span class="task-summary-card__value">' + card.value + '</span>' +
       '</div>'
@@ -2152,7 +2165,7 @@ try {
       cardsEl.innerHTML = qCards.map(function(card) {
         return '<div class="task-summary-card task-summary-card--' + card.mod + '">' +
           '<span class="task-summary-card__label">' + escapeHtml(card.label) +
-          ' <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: ' + escapeHtml(card.tooltip) + '" data-tooltip="' + escapeHtml(card.tooltip) + '">\u2139\uFE0F</span>' +
+          ' <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: ' + escapeHtml(card.tooltip) + '" data-tooltip="' + escapeHtml(card.tooltip) + '">' + INFO_ICON + '</span>' +
           '</span>' +
           '<span class="task-summary-card__value">' + card.value + '</span>' +
           '</div>';
@@ -2210,7 +2223,7 @@ try {
     if (dlqCardEl) {
       dlqCardEl.innerHTML =
         '<div class="task-summary-card task-summary-card--' + (dlqCount > 0 ? 'errors' : 'done') + '">' +
-        '<span class="task-summary-card__label">Retry Queue <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Tasks that failed too many times and need manual attention. Also known as Dead Letter Queue (DLQ)." data-tooltip="Tasks that failed too many times and need manual attention. Also known as Dead Letter Queue (DLQ).">\u2139\uFE0F</span></span>' +
+        '<span class="task-summary-card__label">Retry Queue <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Tasks that failed too many times and need manual attention. Also known as Dead Letter Queue (DLQ)." data-tooltip="Tasks that failed too many times and need manual attention. Also known as Dead Letter Queue (DLQ).">' + INFO_ICON + '</span></span>' +
         '<span class="task-summary-card__value">' + dlqCount + '</span>' +
         '</div>';
     }
@@ -2290,7 +2303,7 @@ try {
       cardsEl.innerHTML = driftCards.map(function(card) {
         return '<div class="task-summary-card task-summary-card--' + card.mod + '">' +
           '<span class="task-summary-card__label">' + escapeHtml(String(card.label)) +
-          ' <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: ' + escapeHtml(card.tooltip) + '" data-tooltip="' + escapeHtml(card.tooltip) + '">\u2139\uFE0F</span>' +
+          ' <span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: ' + escapeHtml(card.tooltip) + '" data-tooltip="' + escapeHtml(card.tooltip) + '">' + INFO_ICON + '</span>' +
           '</span>' +
           '<span class="task-summary-card__value">' + card.value + '</span>' +
           '</div>';
@@ -2331,7 +2344,7 @@ try {
       cardsEl.innerHTML =
         '<div class="task-summary-card task-summary-card--done">' +
         '<span class="task-summary-card__label">Outputs Produced ' +
-        '<span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Files, data, and summaries produced by this convoy." data-tooltip="Files, data, and summaries produced by this convoy.">\u2139\uFE0F</span>' +
+        '<span class="tooltip-trigger" tabindex="0" role="button" aria-label="Info: Files, data, and summaries produced by this convoy." data-tooltip="Files, data, and summaries produced by this convoy.">' + INFO_ICON + '</span>' +
         '</span>' +
         '<span class="task-summary-card__value">' + artifactCount + '</span>' +
         '</div>';
@@ -2498,6 +2511,7 @@ try {
   async function main() {
     const events = await loadNdjson(base + 'data/events.ndjson');
     const pipelines = await loadNdjson(base + 'data/pipelines.ndjson');
+    const convoys = window.__DASHBOARD_DATA__?.convoyList ?? [];
 
     const sessions = events.filter((e) => e.type === 'session');
     const delegations = events.filter((e) => e.type === 'delegation');
@@ -2578,7 +2592,7 @@ try {
       if (refreshInterval) return;
       refreshInterval = setInterval(async () => {
         const freshEvents = await loadNdjson(base + 'data/events.ndjson');
-        const freshConvoys = await loadNdjson(base + 'data/convoys.ndjson');
+        const freshConvoys = await loadJson(base + 'data/convoy-list.json');
         const freshPipelines = await loadNdjson(base + 'data/pipelines.ndjson');
         rawSessions = freshEvents.filter((e) => e.type === 'session');
         rawDelegations = freshEvents.filter((e) => e.type === 'delegation');
@@ -2634,17 +2648,26 @@ try {
 
     sections.forEach((s) => observer.observe(s));
 
+    // Convoy-detail sections that start hidden and need a convoy selected first
+    const CONVOY_DETAIL_SECTIONS = ['tasks-section', 'quality-section', 'reliability-section', 'drift-section', 'outputs-section', 'event-timeline-section'];
+
     // Smooth scroll on click
     links.forEach((link) => {
-      link.addEventListener('click', (e) => {
+      link.addEventListener('click', async (e) => {
         e.preventDefault();
         const sectionId = link.dataset.section;
 
-        // Auto-select latest convoy/pipeline if section is hidden
-        if (sectionId === 'convoy-section') {
-          const convoySelect = document.getElementById('filter-convoy');
-          if (convoySelect && !convoySelect.value && convoySelect.options.length > 1) {
-            convoySelect.value = convoySelect.options[1].value;
+        if (CONVOY_DETAIL_SECTIONS.includes(sectionId)) {
+          // Auto-select and load convoy detail if none selected yet
+          const convoySelectEl = document.getElementById('convoy-select');
+          if (convoySelectEl && !convoySelectEl.value && convoySelectEl.options.length > 1) {
+            convoySelectEl.value = convoySelectEl.options[1].value;
+            await loadConvoyDetail(convoySelectEl.value);
+          }
+        } else if (sectionId === 'convoy-section') {
+          const convoyFilterEl = document.getElementById('filter-convoy');
+          if (convoyFilterEl && !convoyFilterEl.value && convoyFilterEl.options.length > 1) {
+            convoyFilterEl.value = convoyFilterEl.options[1].value;
             applyFilters();
           }
         } else if (sectionId === 'convoy-pipeline-section') {
@@ -2656,7 +2679,7 @@ try {
         }
 
         const target = document.getElementById(sectionId);
-        if (target && target.style.display !== 'none') {
+        if (target) {
           target.scrollIntoView({ behavior: 'smooth', block: 'start' });
         }
       });

package/src/orchestrator/prompts/fix-convoy.prompt.md

@@ -0,0 +1,79 @@
+---
+description: 'Fix schema validation errors in a convoy YAML spec. Goal is the broken spec YAML; context is the error list from the validation step.'
+agent: 'Team Lead (OpenCastle)'
+output: convoy-spec
+---
+
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
+
+# Fix Convoy Spec
+
+You are the Team Lead. The convoy spec below failed validation. Fix **every reported error** and output a complete, corrected spec.
+
+## Failing Spec
+
+```yaml
+{{goal}}
+```
+
+## Validation Errors
+
+{{context}}
+
+---
+
+## Fix Instructions
+
+1. Read every error before touching the YAML.
+2. Fix **all** reported errors — do not partially fix.
+3. Do not change the intent, agent assignments, or task scope of any task. Only fix what is broken.
+4. Preserve all `id`, `prompt`, `agent`, `review`, and `files` values that are not part of the reported errors.
+
+### Common Fix Patterns
+
+**Glob patterns in `files`**
+- `src/**/*.ts` → `src/` (use the directory, not a glob)
+- `app/api/**` → `app/api/`
+- `components/*.tsx` → `components/`
+
+**Missing required fields**
+- Add `name:` at the top level if missing
+- Add `version: 2` at the top level if missing
+- Add `id:` to any task that lacks one (use kebab-case derived from the task purpose)
+- Add `prompt:` to any task that lacks one — write a 2-sentence self-contained description
+
+**Dependency cycles**
+- If A depends on B and B depends on A: remove the weaker edge (the one that can be inferred from ordering)
+- If the cycle is A → B → C → A: introduce a new intermediate task or reorder so earlier tasks do not depend on later ones
+
+**Partition conflicts (two parallel tasks sharing files)**
+- Option 1: Add a `depends_on` edge to serialize the conflicting tasks
+- Option 2: Split one task's `files` list to use a more specific path that does not overlap
+
+**Invalid `agent` value**
+Replace with the closest valid agent from:
+`api-designer`, `architect`, `content-engineer`, `copywriter`, `data-expert`,
+`database-engineer`, `developer`, `devops-expert`, `documentation-writer`,
+`performance-expert`, `release-manager`, `researcher`, `security-expert`,
+`seo-specialist`, `team-lead`, `testing-expert`, `ui-ux-expert`
+
+**Invalid `timeout` format**
+- `"30 minutes"` → `30m`
+- `"1 hour"` → `1h`
+- `"120"` → `120s`
+
+---
+
+## Output
+
+Return the **complete corrected YAML** inside a fenced code block (not just the changed lines):
+
+```yaml
+# .opencastle/convoys/<same-filename-as-original>
+name: ...
+version: 2
+tasks:
+  ...
+```
+
+Do not add explanatory prose before or after the YAML block.

package/src/orchestrator/prompts/generate-convoy.prompt.md

@@ -37,8 +37,8 @@ The output file must conform to the following schema. Fields marked **(required)
 | `gates` | array of strings | no | — | Shell commands run after all tasks complete; each must exit 0 |
 | `gate_retries` | integer ≥ 0 | no | `0` | How many times to retry failing gates with an auto-fix task |
 | `guard` | object | no | — | Post-convoy guard configuration (see Guard below) |
-| `hooks` | array of Hook | no | — | Post-convoy lifecycle hooks (see Hooks below) |
-| `watch` | object | no | — | Watch mode configuration for continuous re-runs (see Watch below) |
+| `hooks` | array of Hook | no | — | Post-convoy lifecycle hooks. Use `post_convoy` hooks for notifications or cleanup scripts after the run completes. |
+| `watch` | object | no | — | Watch mode configuration for continuous re-runs. Set this when the goal is a recurring workflow (e.g. nightly sync, CI re-run on file change). |
 | `tasks` | list | **yes** | — | Non-empty list of task objects |
 | `depends_on_convoy` | list of strings | no | — | (version 2 only) Other convoy spec names to run before this one |
 
@@ -49,31 +49,21 @@ All fields are optional. Values are merged into each task unless the task overri
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `timeout` | duration | `30m` | Default task timeout (`<n><s\|m\|h>`) |
-| `model` | string | — | AI model override for all tasks |
 | `max_retries` | integer | `1` | Default max retry attempts |
 | `agent` | string | `developer` | Default agent role |
-| `adapter` | string | — | Default adapter override |
-| `gates` | array of strings | — | Per-task gate commands run after adapter success |
+| `gates` | array of strings | — | Gate commands run after every task completes (use for project-wide lint/type-check) |
 | `review` | `auto` \| `fast` \| `panel` \| `none` | — | Review level for completed tasks |
-| `reviewer_model` | string | — | Model used for reviews |
-| `review_budget` | integer | — | Max review token budget |
-| `on_review_budget_exceeded` | `skip` \| `downgrade` \| `stop` | — | Action when review budget exhausted |
-| `max_concurrent_reviews` | integer | — | Parallel review limit |
-| `review_heuristics` | object | — | Auto-routing rules (see Review Heuristics below) |
-| `detect_drift` | boolean | — | Enable drift detection on streaming adapters |
-| `on_dispute` | `continue` \| `stop` | — | Behavior on panel disputes |
-| `on_exhausted` | `dlq` \| `skip` \| `stop` | — | Action when max_retries exhausted |
-| `escalate_to` | string | — | Agent for DLQ escalation |
-| `inject_lessons` | boolean | — | Auto-inject relevant lessons from LESSONS-LEARNED.md into prompts |
-| `track_discovered_issues` | boolean | — | Enable discovered issues tracking in prompts |
-| `avoid_weak_agents` | boolean | — | Skip assigning agents to tasks matching their weak areas |
-| `max_swarm_concurrency` | integer (1–50) | `8` | Max parallel tasks in swarm mode (`concurrency: auto`) |
-| `built_in_gates` | object | — | Built-in gate configuration (see Built-in Gates below) |
-| `browser_test` | object | — | Default browser test gate config (see Browser Test below) |
-| `circuit_breaker` | object | — | Circuit breaker config (see Circuit Breaker below) |
-| `mcp_servers` | array of MCPServer | — | MCP servers available to tasks |
-| `mcp_approve_all` | boolean | — | Auto-approve all MCP tool calls |
-| `mcp_server_approval_timeout` | number | — | Timeout (seconds) for MCP approval prompts |
+| `review_heuristics` | object | — | Auto-routing rules (see Review Heuristics below). Use to automatically assign `panel` review for security-sensitive paths or agents. |
+| `detect_drift` | boolean | — | Enable drift detection on streaming adapters. Set `true` for long-running (>1h) tasks on streaming adapters to catch scope creep early. |
+| `on_exhausted` | `dlq` \| `skip` \| `stop` | — | Action when max_retries exhausted. Use `dlq` for critical tasks in unattended overnight runs so failures are tracked. |
+| `escalate_to` | string | — | Agent for DLQ escalation (e.g. `architect`). Pair with `on_exhausted: dlq`. |
+| `inject_lessons` | boolean | — | Auto-inject relevant lessons from LESSONS-LEARNED.md into prompts. **Always set `true`.** |
+| `track_discovered_issues` | boolean | — | Enable discovered issues tracking in prompts. **Always set `true`.** |
+| `avoid_weak_agents` | boolean | — | Skip assigning agents to tasks matching their weak areas. **Always set `true`.** |
+| `max_swarm_concurrency` | integer (1–50) | `8` | Max parallel tasks in swarm mode. Only relevant when `concurrency: auto`. |
+| `built_in_gates` | object | — | Built-in gate configuration (see Built-in Gates below). Enable `secret_scan: true` for any task writing auth/config/env files; `dependency_audit: true` when the run adds new packages. |
+| `browser_test` | object | — | Default browser test gate config (see Browser Test below). Set when the goal involves UI changes. |
+| `circuit_breaker` | object | — | Circuit breaker config (see Circuit Breaker below). Set for long multi-agent runs to prevent cascading failures. |
 
 ### Built-in Gates
 
@@ -170,21 +160,19 @@ Enables continuous re-execution triggered by file changes, cron, or git push.
 | `agent` | string | no | `developer` | Agent role hint (see Agent Roster below) |
 | `description` | string | no | same as `id` | Short human label shown in progress output |
 | `depends_on` | list of ids | no | `[]` | Task ids that must finish before this one starts |
-| `files` | list of globs | no | `[]` | File scope the agent is allowed to modify |
+| `files` | list of paths | no | `[]` | File scope the agent is allowed to modify. Must be plain file paths or directory paths. **Glob patterns (`*`, `?`, `**`) are not allowed** — use a plain directory path (e.g., `components/`) to cover a whole directory. |
 | `timeout` | duration | no | `30m` | Max wall time (`<number><s\|m\|h>`, e.g. `10m`, `1h`) |
-| `max_retries` | integer | no | from `defaults` or `1` | Max retry attempts for this task |
-| `model` | string | no | — | AI model override for this task |
-| `adapter` | string | no | — | Per-task adapter override |
-| `gates` | list of strings | no | — | Per-task gate commands run after adapter success |
+| `max_retries` | integer | no | from `defaults` or `1` | Max retry attempts for this task. Override to `3` for high-risk tasks (DB migrations, security changes) or `0` for tasks that must not auto-retry. |
+| `gates` | list of strings | no | — | Per-task gate commands when this task needs specific validation beyond global `gates` (e.g. a task-specific test suite or a schema diff check). |
 | `review` | `auto` \| `fast` \| `panel` \| `none` | no | from `defaults` | Review level for this task |
-| `detect_drift` | boolean | no | — | Enable drift detection (streaming adapters only) |
-| `persistent` | boolean | no | — | Enable persistent agent identity across convoy runs |
-| `steps` | list of TaskStep | no | — | Multi-step sub-prompts (see Steps below) |
-| `hooks` | list of Hook | no | — | Per-task lifecycle hooks |
-| `outputs` | list of TaskOutput | no | — | Named artifacts this task produces |
-| `inputs` | list of TaskInput | no | — | Named artifacts this task consumes from upstream tasks |
-| `browser_test` | object | no | — | Per-task browser test config (same schema as defaults) |
-| `built_in_gates` | object | no | — | Per-task built-in gates override |
+| `detect_drift` | boolean | no | — | Enable drift detection (streaming adapters only). Set `true` for long (>1h) streaming-adapter tasks to catch scope creep. |
+| `persistent` | boolean | no | — | Enable persistent agent identity across convoy runs. Set `true` for research, exploration, or multi-session implementation tasks where the agent's accumulated discoveries and decisions should be available in future convoy runs targeting the same workstream. Omit (defaults to `false`) for short, self-contained tasks. |
+| `steps` | list of TaskStep | no | — | Multi-step sub-prompts. Use when a task has distinct sequential phases that need intermediate gates (e.g. step 1: generate migration, gate: dry-run; step 2: apply migration). |
+| `hooks` | list of Hook | no | — | Per-task lifecycle hooks. Uncommon at task level; prefer top-level `hooks` for post-convoy actions. |
+| `outputs` | list of TaskOutput | no | — | Named artifacts this task produces (used with `inputs` for explicit artifact passing between tasks). |
+| `inputs` | list of TaskInput | no | — | Named artifacts this task consumes from upstream tasks. |
+| `browser_test` | object | no | — | Per-task browser test config. Set when only this task's output requires visual/a11y validation. |
+| `built_in_gates` | object | no | — | Per-task built-in gates override. Use to enable `secret_scan: true` for specific tasks writing credentials or keys. |
 
 ### Task Steps
 
@@ -218,18 +206,6 @@ Tasks can produce named artifacts and consume artifacts from upstream tasks.
 | `name` | string | **yes** | Artifact name from the source task |
 | `as` | string | no | Rename the artifact in the consuming task |
 
-### MCP Server Config
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | **yes** | Server identifier |
-| `type` | string | **yes** | Server type (e.g. `stdio`, `http`) |
-| `local` | boolean | no | Whether the server runs locally |
-| `command` | string | no | Command to start the server |
-| `args` | list of strings | no | Arguments for the command |
-| `url` | string | no | URL for HTTP-based servers |
-| `config` | object | no | Additional server configuration |
-
 ### Agent Roster
 
 Available values for the `agent` field:
@@ -263,9 +239,16 @@ For each workstream, break it down into the smallest meaningful unit of work tha
 
 1. **Single responsibility** — each task does exactly one thing.
 2. **Self-contained prompt** — the `prompt` field must contain everything the agent needs: objective, file paths, constraints, acceptance criteria. The agent has no other context.
-3. **Explicit file scopes** — list every directory or file the task may touch in `files`. This prevents conflicts between parallel tasks.
-4. **Appropriate agent** — pick the agent whose speciality matches the task (e.g., `testing-expert` for tests, `database-engineer` for migrations).
-5. **Realistic timeouts** — default 30 m is fine for most tasks; use `1h` for large refactors or test suites; use `10m` for small docs or config changes.
+3. **Explicit file scopes** — list every directory or file the task may touch in `files`. Use plain paths only: exact file paths (e.g., `app/page.tsx`) or directory paths with a trailing slash (e.g., `app/about/`). **Glob patterns (`*`, `?`, `**`) are not allowed** — the engine rejects them.
+
+4. **No partition conflicts** — two tasks may not share a `files` entry if they run in parallel (same phase). Resolve conflicts by either:
+   - **Specificity**: replace a broad directory path with the specific files each task actually creates (e.g., instead of both tasks claiming `components/`, one gets `components/Hero.tsx` and the other gets `components/ProjectCard.tsx`)
+   - **Sequencing**: add a `depends_on` edge from the later task to the earlier one, so they run in different phases
+
+   > **Common mistake:** multiple tasks all depending on a single `setup` task will run in parallel and conflict if they share a directory like `components/`, `app/globals.css`, or `app/layout.tsx`. Always use specific file paths or sequence conflicting tasks.
+
+5. **Appropriate agent** — pick the agent whose speciality matches the task (e.g., `testing-expert` for tests, `database-engineer` for migrations).
+6. **Realistic timeouts** — default 30 m is fine for most tasks; use `1h` for large refactors or test suites; use `10m` for small docs or config changes.
 
 ### 3. Define the Dependency Graph (DAG)
 
@@ -287,12 +270,20 @@ For each workstream, break it down into the smallest meaningful unit of work tha
 - `on_failure` — use `continue` (default) when tasks are independent so one failure doesn't waste the whole run. Use `stop` when every subsequent task depends on success.
 - `adapter` — **omit this field** to let the CLI auto-detect the first available adapter. Only set explicitly if the user requests a specific adapter.
 - `branch` — derive from the goal, e.g., `feat/auth-refactor`. Use a descriptive branch name.
-- `defaults` — set sensible defaults for timeout, max_retries, and review. Enable `inject_lessons: true` for self-improving runs, `track_discovered_issues: true` for issue discovery, and `avoid_weak_agents: true` to route around known weaknesses. Model can be left unset for auto-detection.
+- `defaults` — always include `inject_lessons: true`, `track_discovered_issues: true`, and `avoid_weak_agents: true`. Omit `model` and `adapter` to allow auto-detection.
 - `gates` — include standard validation gates (lint, type-check, test) unless the user specifies otherwise.
 - `gate_retries` — set to 1–2 if you want the engine to auto-fix gate failures by spawning a fix-up task.
 - `guard` — enable for post-convoy compliance checks (observability, cleanup, cost reporting).
-- For security-sensitive or database migration tasks, use `review: panel` or set `review_heuristics.panel_paths` to target critical paths.
-- For long-running or unreliable tasks, configure `circuit_breaker` with a `fallback_agent`.
+- `review` / `review_heuristics` — use `review: fast` as the default. Upgrade to `panel` for security, auth, and database migration tasks. Use `review_heuristics.panel_paths` to auto-escalate specific file patterns (e.g. `db/migrations/`, `libs/auth/`) without setting per-task overrides.
+- `built_in_gates` — set `secret_scan: true` in `defaults.built_in_gates` whenever the run touches auth, config, or env files. Set `dependency_audit: true` when adding new packages.
+- `on_exhausted` + `escalate_to` — set `on_exhausted: dlq` and `escalate_to: architect` in `defaults` for unattended overnight runs so exhausted tasks are queued for human review rather than silently skipped.
+- `detect_drift` — set `detect_drift: true` in `defaults` for runs with tasks longer than 1h on streaming adapters.
+- `circuit_breaker` — configure with a `fallback_agent` for long multi-agent runs to prevent one flaky agent from stalling the whole convoy.
+- `persistent` — set `persistent: true` on individual tasks that do research, codebase exploration, or long implementation work where the agent's accumulated discoveries should persist across future convoy runs (e.g. a Researcher task mapping the auth system, or a Database Engineer task discovering schema quirks). Omit for short, self-contained tasks.
+- `steps` — use on a task when it has distinct sequential phases that need intermediate validation gates between them (e.g. generate migration → dry-run gate → apply migration). Do not use `steps` just to split a large prompt; use separate tasks instead.
+- Per-task `gates` — add to a task only when that specific task needs validation gates beyond the global `gates` (e.g. a dedicated test suite for a specific module, a schema diff command).
+- Per-task `max_retries` — override to `3` for high-risk tasks (DB migrations, security changes) or `0` when a task must not auto-retry (e.g. payment processing changes).
+- `hooks` — use top-level `post_convoy` hooks for notifications, changelog generation, or cleanup scripts that should run once after all tasks complete.
 
 ### 5. Write the Prompts
 
@@ -317,7 +308,8 @@ Before presenting the YAML, mentally verify:
 - [ ] Every task has a unique `id`
 - [ ] Every `depends_on` reference points to a valid `id` defined earlier in the list
 - [ ] No dependency cycles exist
-- [ ] No two parallel tasks share the same `files` entries (partition check)
+- [ ] No two parallel tasks share the same `files` entries — group tasks by phase and check each phase for overlaps; resolve with specific file paths or `depends_on` (see Step 2, rule 4)
+- [ ] No `files` entry contains `*`, `?`, or `**` — use plain file paths or directory paths (trailing `/`) only
 - [ ] Prompts are self-contained — an agent with zero context can execute them
 - [ ] Timeouts are reasonable for the scope of each task
 - [ ] `outputs`/`inputs` references are consistent (consuming task depends on producing task)
@@ -347,7 +339,9 @@ tasks:
     description: <short label>
     timeout: <duration>
     files:
-      - <glob>
+      - app/some-file.tsx
+      - components/Hero.tsx
+      - components/Button.tsx
     prompt: |
       <full self-contained instruction>
 
@@ -356,7 +350,8 @@ tasks:
       - <task-id>
     agent: <agent>
     files:
-      - <glob>
+      - app/other-file.tsx
+      - components/OtherComponent.tsx
     prompt: |
       <full self-contained instruction>
 

package/src/orchestrator/prompts/generate-prd.prompt.md

@@ -0,0 +1,120 @@
+---
+description: 'Generate a Product Requirements Document from a high-level feature prompt. Output feeds directly into the generate-convoy step.'
+agent: 'Team Lead (OpenCastle)'
+output: prd
+---
+
+<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
+
+# Generate PRD
+
+You are the Team Lead. Convert the feature request below into a structured Product Requirements Document (PRD). The PRD will be consumed by the `generate-convoy` step to produce an automated agent task spec, so every section must be **concrete**, **specific**, and **implementation-ready**.
+
+## Feature Request
+
+{{goal}}
+
+## Additional Context
+
+{{context}}
+
+---
+
+## Required PRD Structure
+
+Produce the PRD in Markdown using **exactly** the sections below. Do not skip or merge sections. Do not wrap the output in a code fence — output raw Markdown starting directly with the `#` heading.
+
+---
+
+# [Feature Name] — PRD
+
+## Overview
+
+2–3 sentences: what this feature does, who benefits, and why it matters now.
+
+## Goals
+
+Numbered list of specific, measurable outcomes this feature must achieve. Each goal should be a single sentence with a clear success condition.
+
+1. …
+2. …
+
+## Non-Goals
+
+Explicit exclusions — what this work does **not** cover. If nothing is excluded, write "None."
+
+## User Stories & Acceptance Criteria
+
+For each primary scenario, write a user story + binary acceptance criteria. Criteria must be testable (pass/fail — no subjective language).
+
+**US-1: [Short title]**
+As a [user type], I want [action] so that [benefit].
+
+Acceptance criteria:
+- [ ] [Specific, testable condition]
+- [ ] [Another condition]
+
+*(Repeat for each user story)*
+
+## Technical Requirements
+
+Specific technical constraints the implementation must respect:
+- Libraries, framework versions to use or avoid
+- API contracts or interfaces that must not break
+- Performance thresholds (e.g., "<200 ms p95 latency")
+- Security requirements
+- Browser/platform compatibility
+
+## Implementation Scope
+
+List **every file and directory** that will be created, modified, or deleted. Use specific paths — not broad paths like `src/`. Group by concern.
+
+| Concern | Files / Directories |
+|---------|---------------------|
+| [Frontend components] | `components/feature/`, `app/feature/page.tsx` |
+| [API routes] | `app/api/feature/route.ts` |
+| [Database] | `db/migrations/add_feature.sql`, `db/schema.ts` |
+| [Shared types] | `types/feature.ts` |
+| [Tests] | `__tests__/feature.test.ts`, `e2e/feature.spec.ts` |
+| [Config / env] | `.env.example` |
+
+**File partition rules (important for parallel execution):**
+- No two concurrent workstreams may modify the same file
+- If two workstreams need the same file, they must be sequenced (Phase N+1 after Phase N)
+
+## Task Breakdown
+
+Decompose into the minimum number of phases. Tasks in the same phase run in parallel and **must not share any files**.
+
+```
+Phase 1 — Foundation (parallel, no dependencies):
+  - [Workstream A title]: [2-sentence description]
+    Files: [list exact files]
+  - [Workstream B title]: [2-sentence description]
+    Files: [list exact files]
+
+Phase 2 — Integration (depends on Phase 1):
+  - [Workstream C title]: [2-sentence description]
+    Files: [list exact files]
+    Depends on: Phase 1
+
+Phase 3 — Verification (depends on Phase 2):
+  - [Tests]: Run full test suite, achieve ≥ 95% coverage on new files
+  - [Documentation]: Update READMEs and changelogs
+```
+
+## Success Criteria
+
+Measurable, binary checks that confirm the feature is shippable:
+- [ ] All acceptance criteria in User Stories & Acceptance Criteria pass
+- [ ] TypeScript compiles with zero errors
+- [ ] Lint passes with zero warnings
+- [ ] Unit test coverage ≥ 95% on all new/changed files
+- [ ] [Feature-specific checks]
+
+## Risks & Open Questions
+
+- **[Risk title]**: [Description of the risk] — *Mitigation: [How to handle it]*
+- **[Open question]**: [What needs to be decided before implementation can start]
+
+If there are no risks or open questions, write "None identified."