project-logbook 1.1.0 → 1.3.0

package/dist/templates/hub.js

@@ -0,0 +1,628 @@
+(function () {
+  'use strict';
+
+  const projects = {};
+  const projectEvents = {};
+  const expandedProjects = new Set();
+  const projectsEl = document.getElementById('projects');
+  const countEl = document.getElementById('project-count');
+  const connEl = document.getElementById('conn-status');
+  const sortBtn = document.getElementById('sort-toggle');
+  const jiraSortBtn = document.getElementById('jira-sort-toggle');
+
+  // --- Tab switching ---
+  const tabs = document.querySelectorAll('.tab-btn');
+  const tabContents = document.querySelectorAll('.tab-content');
+
+  function switchTab(target) {
+    tabs.forEach((t) => t.classList.remove('active'));
+    tabContents.forEach((tc) => tc.classList.remove('active'));
+    const btn = document.querySelector('.tab-btn[data-tab="' + target + '"]');
+    if (btn) btn.classList.add('active');
+    document.getElementById('tab-' + target).classList.add('active');
+    sortBtn.style.display = target === 'projects' ? '' : 'none';
+    jiraSortBtn.style.display = target === 'jira' ? '' : 'none';
+  }
+
+  tabs.forEach((tab) => {
+    tab.addEventListener('click', () => {
+      const target = tab.getAttribute('data-tab');
+      window.location.hash = target;
+      switchTab(target);
+    });
+  });
+
+  function applyHash() {
+    const hash = window.location.hash.replace('#', '') || 'projects';
+    switchTab(hash);
+  }
+  applyHash();
+  window.addEventListener('hashchange', applyHash);
+
+  // --- Help tab: fetch strategies ---
+  fetch('/_logbook/strategies')
+    .then((r) => r.json())
+    .then((strategies) => {
+      let currentSource = '';
+      const tbody = strategies
+        .map((s) => {
+          let groupHeader = '';
+          if (s.source !== currentSource) {
+            currentSource = s.source;
+            groupHeader = '<tr class="help-group-header"><td colspan="5">' + currentSource + '</td></tr>';
+          }
+          const blockers =
+            s.blockedBy && s.blockedBy.length > 0
+              ? '<span class="blocked-by">blocked by: ' + s.blockedBy.join(', ') + '</span>'
+              : '';
+          return (
+            groupHeader +
+            '<tr>' +
+            '<td><span class="badge badge-' +
+            s.severity +
+            '">' +
+            s.label +
+            '</span></td>' +
+            '<td>' +
+            s.source +
+            '</td>' +
+            '<td>' +
+            s.severity +
+            '</td>' +
+            '<td>' +
+            (s.description || '') +
+            '</td>' +
+            '<td>' +
+            blockers +
+            '</td>' +
+            '</tr>'
+          );
+        })
+        .join('');
+      document.getElementById('help-table-body').innerHTML = tbody;
+    })
+    .catch(function () {});
+
+  // --- Sort toggle ---
+  var sortMode = localStorage.getItem('logbook-sort') || 'newest';
+  sortBtn.textContent = 'Sort (' + (sortMode === 'newest' ? 'Newest' : 'Name') + ')';
+  sortBtn.addEventListener('click', function () {
+    sortMode = sortMode === 'newest' ? 'name' : 'newest';
+    localStorage.setItem('logbook-sort', sortMode);
+    sortBtn.textContent = 'Sort (' + (sortMode === 'newest' ? 'Newest' : 'Name') + ')';
+    renderProjects();
+  });
+
+  // --- Utility functions ---
+  function relativeTime(iso) {
+    if (!iso) return '';
+    var diff = Date.now() - new Date(iso).getTime();
+    var s = Math.floor(diff / 1000);
+    if (s < 60) return 'just now';
+    var m = Math.floor(s / 60);
+    if (m < 60) return m + ' min ago';
+    var h = Math.floor(m / 60);
+    if (h < 24) return h + 'h ago';
+    return Math.floor(h / 24) + 'd ago';
+  }
+
+  function escapeHtml(s) {
+    var el = document.createElement('div');
+    el.textContent = s;
+    return el.innerHTML;
+  }
+
+  function renderCollectorFooter(p) {
+    var parts = [];
+    if (p.glabLastUpdated) parts.push('GitLab updated ' + relativeTime(p.glabLastUpdated));
+    if (p.jiraLastUpdated) parts.push('Jira updated ' + relativeTime(p.jiraLastUpdated));
+    if (parts.length === 0) return '';
+    return '<div class="card-collector-footer">' + parts.join('. ') + '.</div>';
+  }
+
+  function updateTabFooters() {
+    var jiraFooter = document.getElementById('jira-tab-footer');
+    var jiraTimestamps = Object.values(projects)
+      .map(function (p) {
+        return p.jiraLastUpdated;
+      })
+      .filter(Boolean);
+    if (jiraFooter) {
+      if (jiraTimestamps.length > 0) {
+        var latest = jiraTimestamps.sort().pop();
+        jiraFooter.textContent = 'Jira updated ' + relativeTime(latest) + '.';
+        jiraFooter.style.display = '';
+      } else {
+        jiraFooter.style.display = 'none';
+      }
+    }
+    var glabFooter = document.getElementById('gitlab-tab-footer');
+    var glabTimestamps = Object.values(projects)
+      .map(function (p) {
+        return p.glabLastUpdated;
+      })
+      .filter(Boolean);
+    if (glabFooter) {
+      if (glabTimestamps.length > 0) {
+        var latest = glabTimestamps.sort().pop();
+        glabFooter.textContent = 'GitLab updated ' + relativeTime(latest) + '.';
+        glabFooter.style.display = '';
+      } else {
+        glabFooter.style.display = 'none';
+      }
+    }
+  }
+
+  function renderBranchMeta(p) {
+    var branch = p.branch || '\u2014';
+    var branchUrl =
+      p.mrUrl ||
+      (p.repositoryUrl && p.branch
+        ? p.repositoryUrl.replace(/\/$/, '') + '/-/tree/' + encodeURIComponent(p.branch)
+        : null);
+    var value = branchUrl
+      ? '<a class="meta-link" href="' +
+        escapeHtml(branchUrl) +
+        '" target="_blank" rel="noopener">' +
+        escapeHtml(branch) +
+        '<span class="link-icon">\u00A0&#x2197;</span></a>'
+      : escapeHtml(branch);
+    return (
+      '<div class="meta-item"><span class="meta-label">branch:</span> <span class="meta-value">' +
+      value +
+      '</span></div>'
+    );
+  }
+
+  function renderTicketMeta(p) {
+    var ticket = p.activeTicket || 'none';
+    var ticketUrl =
+      p.jiraBaseUrl && p.activeTicket
+        ? p.jiraBaseUrl.replace(/\/+$/, '') + '/browse/' + encodeURIComponent(p.activeTicket)
+        : null;
+    var value = ticketUrl
+      ? '<a class="meta-link" href="' +
+        escapeHtml(ticketUrl) +
+        '" target="_blank" rel="noopener">' +
+        escapeHtml(ticket) +
+        '<span class="link-icon">\u00A0&#x2197;</span></a>'
+      : escapeHtml(ticket);
+    var jiraLabel = p.jiraStatus ? ' <span class="jira-status">' + escapeHtml(p.jiraStatus) + '</span>' : '';
+    return (
+      '<div class="meta-item"><span class="meta-label">ticket:</span> <span class="meta-value">' +
+      value +
+      jiraLabel +
+      '</span></div>'
+    );
+  }
+
+  function renderPathMeta(p) {
+    if (!p.projectPath) return '';
+    return (
+      '<div class="card-path"><span class="meta-label">path:</span> <span class="meta-value meta-path" title="' +
+      escapeHtml(p.projectPath) +
+      '">' +
+      escapeHtml(p.projectPath) +
+      '</span></div>'
+    );
+  }
+
+  function renderTimeline(path) {
+    var events = projectEvents[path];
+    if (!events || events.length === 0) return '';
+    var items = events
+      .slice(0, 20)
+      .map(function (e) {
+        return (
+          '<li><span class="activity-time">' +
+          relativeTime(e.timestamp) +
+          '</span>' +
+          '<span class="activity-source">' +
+          escapeHtml(e.source) +
+          '</span>' +
+          '<span class="activity-desc">' +
+          escapeHtml(e.description) +
+          '</span></li>'
+        );
+      })
+      .join('');
+    return '<div class="activity-timeline"><h4>Activity</h4><ul class="activity-list">' + items + '</ul></div>';
+  }
+
+  function renderProjects() {
+    var entries = Object.values(projects);
+    countEl.textContent = entries.length;
+    countEl.style.display = entries.length > 0 ? '' : 'none';
+    if (entries.length === 0) {
+      projectsEl.innerHTML = '<div class="empty">Waiting for projects to connect...</div>';
+      return;
+    }
+    if (sortMode === 'newest') {
+      entries.sort(function (a, b) {
+        return (b.lastActivity || '').localeCompare(a.lastActivity || '');
+      });
+    } else {
+      entries.sort(function (a, b) {
+        return (a.projectName || '').localeCompare(b.projectName || '');
+      });
+    }
+    var html = entries
+      .map(function (p) {
+        var mrIds = new Set([
+          'mr-draft',
+          'mr-open-comments',
+          'mr-approved',
+          'mr-approval-optional',
+          'mr-conflicts',
+          'no-mr',
+        ]);
+        var badges = (p.statuses || [])
+          .map(function (s) {
+            var isMr = mrIds.has(s.id) && p.mrUrl;
+            if (isMr)
+              return (
+                '<a class="badge badge-' +
+                s.severity +
+                '" href="' +
+                escapeHtml(p.mrUrl) +
+                '" target="_blank" rel="noopener" title="' +
+                (s.detail || '') +
+                '">' +
+                s.label +
+                '</a>'
+              );
+            return (
+              '<span class="badge badge-' + s.severity + '" title="' + (s.detail || '') + '">' + s.label + '</span>'
+            );
+          })
+          .join('');
+        var log = p.latestLog ? '<div class="card-log">' + escapeHtml(p.latestLog) + '</div>' : '';
+        var collectorFooter = renderCollectorFooter(p);
+        var d = p.details;
+        var grid = d
+          ? '<div class="details-grid">' +
+            '<div class="detail-item"><div class="detail-label">LOC changed</div><div class="detail-value">' +
+            d.locChanged +
+            '</div></div>' +
+            '<div class="detail-item"><div class="detail-label">Insertions</div><div class="detail-value positive">+' +
+            d.insertions +
+            '</div></div>' +
+            '<div class="detail-item"><div class="detail-label">Deletions</div><div class="detail-value negative">-' +
+            d.deletions +
+            '</div></div>' +
+            '<div class="detail-item"><div class="detail-label">Staged</div><div class="detail-value">' +
+            d.stagedFiles +
+            '</div></div>' +
+            '<div class="detail-item"><div class="detail-label">Unstaged</div><div class="detail-value">' +
+            d.unstagedFiles +
+            '</div></div>' +
+            '<div class="detail-item"><div class="detail-label">Commits ahead</div><div class="detail-value">' +
+            d.commitsAhead +
+            '</div></div>' +
+            '<div class="detail-item"><div class="detail-label">On branch</div><div class="detail-value">' +
+            d.commitsOnBranch +
+            '</div></div>' +
+            '<div class="detail-item"><div class="detail-label">vs</div><div class="detail-value">' +
+            escapeHtml(d.defaultBranch) +
+            '</div></div>' +
+            '</div>'
+          : '';
+        var details = '<div class="card-details">' + grid + renderTimeline(p.projectPath) + '</div>';
+        var cls = expandedProjects.has(p.projectPath) ? ' expanded' : '';
+        var borderColor = p.primaryColor && /^#[0-9a-fA-F]{3,8}$/.test(p.primaryColor) ? p.primaryColor : '#dee2e6';
+        var agentLabel = p.agentName ? '<span class="card-agent">' + escapeHtml(p.agentName) + '</span>' : '';
+        var previewBtns = p.activeTicket
+          ? '<span class="preview-buttons">' +
+            '<button class="preview-btn" data-preview="story" data-project="' +
+            escapeHtml(p.projectPath) +
+            '">&#x1F4D6; Story</button>' +
+            '<button class="preview-btn" data-preview="log" data-project="' +
+            escapeHtml(p.projectPath) +
+            '">&#x1F4CB; Log</button>' +
+            '<button class="preview-btn" data-preview="ticket" data-project="' +
+            escapeHtml(p.projectPath) +
+            '">&#x1F3AB; Ticket</button>' +
+            '</span>'
+          : '';
+        return (
+          '<div class="card' +
+          cls +
+          '" data-path="' +
+          escapeHtml(p.projectPath) +
+          '" style="border-left-color:' +
+          borderColor +
+          '">' +
+          '<div class="card-header"><span class="card-title">' +
+          escapeHtml(p.projectName) +
+          agentLabel +
+          '</span><span class="card-time">' +
+          relativeTime(p.lastActivity) +
+          '</span></div>' +
+          '<div class="card-meta">' +
+          renderBranchMeta(p) +
+          renderTicketMeta(p) +
+          '</div>' +
+          renderPathMeta(p) +
+          '<div class="badges">' +
+          badges +
+          previewBtns +
+          '</div>' +
+          log +
+          details +
+          collectorFooter +
+          '</div>'
+        );
+      })
+      .join('');
+    projectsEl.innerHTML = html;
+    projectsEl.querySelectorAll('.card').forEach(function (card) {
+      card.addEventListener('click', function (e) {
+        if (e.target.closest('a')) return;
+        var path = card.getAttribute('data-path');
+        if (expandedProjects.has(path)) expandedProjects.delete(path);
+        else expandedProjects.add(path);
+        renderProjects();
+      });
+    });
+  }
+
+  // --- Jira tab ---
+  var jiraSortMode = localStorage.getItem('logbook-jira-sort') || 'updated';
+  var jiraSortLabels = { updated: 'Updated', key: 'Key', status: 'Status' };
+  jiraSortBtn.textContent = 'Sort (' + jiraSortLabels[jiraSortMode] + ')';
+  jiraSortBtn.addEventListener('click', function () {
+    var modes = ['updated', 'key', 'status'];
+    var idx = modes.indexOf(jiraSortMode);
+    jiraSortMode = modes[(idx + 1) % modes.length];
+    localStorage.setItem('logbook-jira-sort', jiraSortMode);
+    jiraSortBtn.textContent = 'Sort (' + jiraSortLabels[jiraSortMode] + ')';
+    renderJiraIssues();
+  });
+
+  var cachedJiraIssues = [];
+
+  function renderJiraIssues() {
+    var container = document.getElementById('jira-issues-content');
+    var issues = cachedJiraIssues;
+    if (!issues || issues.length === 0) {
+      container.innerHTML =
+        '<div class="placeholder-msg">No assigned Jira issues found.<br>Set the <code>JIRA_API_TOKEN</code> environment variable and connect a project with <code>jiraBaseUrl</code> configured.</div>';
+      return;
+    }
+
+    var sorted = [...issues];
+    if (jiraSortMode === 'updated') {
+      sorted.sort(function (a, b) {
+        return (b.updated || '').localeCompare(a.updated || '');
+      });
+    } else if (jiraSortMode === 'key') {
+      sorted.sort(function (a, b) {
+        return a.key.localeCompare(b.key);
+      });
+    } else if (jiraSortMode === 'status') {
+      sorted.sort(function (a, b) {
+        return a.status.localeCompare(b.status);
+      });
+    }
+
+    var grouped = {};
+    sorted.forEach(function (i) {
+      if (!grouped[i.jiraBaseUrl]) grouped[i.jiraBaseUrl] = [];
+      grouped[i.jiraBaseUrl].push(i);
+    });
+
+    var html = '';
+    for (var baseUrl in grouped) {
+      if (!grouped.hasOwnProperty(baseUrl)) continue;
+      var items = grouped[baseUrl];
+      html +=
+        '<h3 class="group-heading"><a href="' +
+        escapeHtml(baseUrl) +
+        '" target="_blank" rel="noopener">' +
+        escapeHtml(baseUrl) +
+        '<span class="group-link-icon"> &#x2197;</span></a></h3>';
+      html +=
+        '<table class="help-table"><thead><tr><th>Key</th><th>Status</th><th>Summary</th><th>Last Update</th></tr></thead><tbody>';
+      items.forEach(function (i) {
+        html +=
+          '<tr>' +
+          '<td class="cell-mono"><a class="meta-link" href="' +
+          escapeHtml(i.url) +
+          '" target="_blank" rel="noopener">' +
+          escapeHtml(i.key) +
+          '<span class="link-icon">\u00A0&#x2197;</span></a></td>' +
+          '<td><span class="jira-status">' +
+          escapeHtml(i.status) +
+          '</span></td>' +
+          '<td>' +
+          escapeHtml(i.summary) +
+          '</td>' +
+          '<td class="cell-time">' +
+          relativeTime(i.updated) +
+          '</td>' +
+          '</tr>';
+      });
+      html += '</tbody></table>';
+    }
+    container.innerHTML = html;
+  }
+
+  function loadJiraIssues() {
+    fetch('/_logbook/jira-issues')
+      .then(function (r) {
+        return r.json();
+      })
+      .then(function (issues) {
+        var countEl2 = document.getElementById('jira-count');
+        var count = issues ? issues.length : 0;
+        countEl2.textContent = count;
+        countEl2.style.display = count > 0 ? '' : 'none';
+        cachedJiraIssues = issues || [];
+        renderJiraIssues();
+      })
+      .catch(function () {
+        document.getElementById('jira-issues-content').innerHTML =
+          '<div class="placeholder-msg">Failed to load Jira issues.</div>';
+      });
+  }
+  loadJiraIssues();
+  setInterval(loadJiraIssues, 5 * 60 * 1000);
+
+  // --- GitLab tab ---
+  function loadGitLabMrs() {
+    fetch('/_logbook/gitlab-mrs')
+      .then(function (r) {
+        return r.json();
+      })
+      .then(function (mrs) {
+        var container = document.getElementById('gitlab-mrs-content');
+        var countEl3 = document.getElementById('gitlab-count');
+        var count = mrs ? mrs.length : 0;
+        countEl3.textContent = count;
+        countEl3.style.display = count > 0 ? '' : 'none';
+        if (!mrs || mrs.length === 0) {
+          container.innerHTML =
+            '<div class="placeholder-msg">No open merge requests found.<br>Install the <code>glab</code> CLI and run <code>glab auth login</code> to connect.</div>';
+          return;
+        }
+        var grouped = {};
+        mrs.forEach(function (m) {
+          if (!grouped[m.projectUrl]) grouped[m.projectUrl] = [];
+          grouped[m.projectUrl].push(m);
+        });
+        var html = '';
+        for (var projUrl in grouped) {
+          if (!grouped.hasOwnProperty(projUrl)) continue;
+          var items = grouped[projUrl];
+          var fullName = items[0].projectName || projUrl;
+          var projName = fullName.includes(' / ') ? fullName.split(' / ').pop() : fullName;
+          html +=
+            '<h3 class="group-heading">' +
+            '<a href="' +
+            escapeHtml(projUrl) +
+            '" target="_blank" rel="noopener">' +
+            escapeHtml(projName) +
+            '<span class="group-link-icon"> &#x2197;</span></a></h3>';
+          html +=
+            '<table class="help-table"><thead><tr><th>Title</th><th>Status</th><th>Comments</th><th>Branch</th></tr></thead><tbody>';
+          items.forEach(function (m) {
+            var statusBadge =
+              m.status === 'draft'
+                ? '<span class="badge badge-info">Draft</span>'
+                : '<span class="badge badge-success">Open</span>';
+            var branchUrl = projUrl ? projUrl.replace(/\/$/, '') + '/-/tree/' + encodeURIComponent(m.sourceBranch) : '';
+            var branchCell = branchUrl
+              ? '<a class="meta-link" href="' +
+                escapeHtml(branchUrl) +
+                '" target="_blank" rel="noopener">' +
+                escapeHtml(m.sourceBranch) +
+                '<span class="link-icon">\u00A0&#x2197;</span></a>'
+              : escapeHtml(m.sourceBranch);
+            var titleCell = m.url
+              ? '<a class="meta-link" href="' +
+                escapeHtml(m.url) +
+                '" target="_blank" rel="noopener">' +
+                escapeHtml(m.title) +
+                '<span class="link-icon">\u00A0&#x2197;</span></a>'
+              : escapeHtml(m.title);
+            html +=
+              '<tr>' +
+              '<td>' +
+              titleCell +
+              '</td>' +
+              '<td>' +
+              statusBadge +
+              '</td>' +
+              '<td>' +
+              m.comments +
+              '</td>' +
+              '<td class="cell-branch">' +
+              branchCell +
+              '</td>' +
+              '</tr>';
+          });
+          html += '</tbody></table>';
+        }
+        container.innerHTML = html;
+      })
+      .catch(function () {
+        document.getElementById('gitlab-mrs-content').innerHTML =
+          '<div class="placeholder-msg">Failed to load merge requests.</div>';
+      });
+  }
+  loadGitLabMrs();
+  setInterval(loadGitLabMrs, 5 * 60 * 1000);
+
+  // --- SSE connection ---
+  function connect() {
+    var es = new EventSource('/_logbook/events');
+    es.onopen = function () {
+      connEl.textContent = 'connected';
+      connEl.classList.remove('disconnected');
+    };
+    es.onmessage = function (e) {
+      try {
+        var data = JSON.parse(e.data);
+        if (data.type === 'status-update') {
+          projects[data.project.projectPath] = data.project;
+          renderProjects();
+          updateTabFooters();
+        } else if (data.type === 'project-removed') {
+          delete projects[data.projectPath];
+          delete projectEvents[data.projectPath];
+          renderProjects();
+        } else if (data.type === 'full-state') {
+          for (var i = 0; i < data.projects.length; i++) projects[data.projects[i].projectPath] = data.projects[i];
+          if (data.events)
+            for (var path in data.events) {
+              if (data.events.hasOwnProperty(path)) projectEvents[path] = data.events[path];
+            }
+          renderProjects();
+          updateTabFooters();
+        } else if (data.type === 'activity-event') {
+          if (!projectEvents[data.projectPath]) projectEvents[data.projectPath] = [];
+          projectEvents[data.projectPath].unshift(data.event);
+          renderProjects();
+        }
+      } catch (_) {}
+    };
+    es.onerror = function () {
+      connEl.textContent = 'disconnected';
+      connEl.classList.add('disconnected');
+      es.close();
+      setTimeout(connect, 3000);
+    };
+  }
+
+  setInterval(renderProjects, 30000);
+  connect();
+
+  // --- Lightbox ---
+  var lightbox = document.getElementById('lightbox');
+  var lightboxTitle = document.getElementById('lightbox-title');
+  var lightboxBody = document.getElementById('lightbox-body');
+  document.getElementById('lightbox-close').addEventListener('click', function () {
+    lightbox.classList.remove('open');
+  });
+  lightbox.addEventListener('click', function (e) {
+    if (e.target === lightbox) lightbox.classList.remove('open');
+  });
+
+  document.addEventListener('click', function (e) {
+    var btn = e.target.closest('.preview-btn');
+    if (!btn) return;
+    e.stopPropagation();
+    var type = btn.getAttribute('data-preview');
+    var path = btn.getAttribute('data-project');
+    var project = projects[path];
+    if (!project) return;
+    var content;
+    if (type === 'story') content = project.renderedStory;
+    else if (type === 'log') content = project.renderedLog;
+    else if (type === 'ticket') content = project.renderedTicket;
+    var titleMap = { story: 'Story', log: 'Log', ticket: 'Ticket' };
+    lightboxTitle.textContent = (titleMap[type] || type) + ' \u2014 ' + project.projectName;
+    lightboxBody.innerHTML = content || '<p class="empty-content">No content available yet.</p>';
+    lightbox.classList.add('open');
+  });
+})();

package/dist/templates/index.md

@@ -2,7 +2,7 @@
 # The ticket field should match the ID portion (e.g., LB-34)
 ticket: {{id}}
 # The title should be a human-readable description of the work
-title: {{title}}
+title: {{yamlTitle}}
 prompter: "[PROMPTER]"
 harness: "[HARNESS]"
 llm: "[LLM]"
@@ -27,9 +27,10 @@ TODO: Write a polished, highly readable ticket summary that reads like an engagi
 
 ### Formatting & Style Rules:
 - **Maintain the narrative tone:** TODO: Keep the storytelling flair (e.g., describing how problems accumulated or how gaps surfaced), but stay strictly factual based on the provided changes.
-- **Add thematic headings:** TODO: Break the narrative down into logical chapters using Markdown headings (e.g., ### The Friction Points, ### The Fix, ### Closing the Gap).
-- **Use bullet points:** TODO: Whenever listing multiple items (like friction points, test scenarios, or rewritten paths), use a bulleted list instead of a dense paragraph to make it scannable.
+- **Add thematic headings:** TODO: Break the narrative down into logical chapters using action-oriented Markdown subheadings that describe what was improved/solved (e.g., ### Improving TabGroup Accessibility, ### Binding Dialog Colors to the Theme) rather than dry, generic headers like "Friction" or "The Fix".
+- **Avoid forced bullet points:** TODO: Write in natural, flowing paragraphs (like in a dev blog post). Only use bullet points for actual, simple lists of items (e.g., list of modified files or configuration options), never to structure or split your main story thoughts.
 - **Use bold emphasis:** TODO: Bold key concepts, problems, and solutions to guide the reader's eye.
 - **Format code:** TODO: Use inline backticks for files, plugins, HTML elements, and code snippets (e.g., `src/lib/build-helpers.ts`).
-- **Keep paragraphs short:** TODO: Ensure no paragraph is longer than 3-4 sentences. Keep the pacing quick and engaging.
+- **Keep paragraphs short:** TODO: Ensure no paragraph is longer than 4 sentences. Keep the pacing quick and engaging.
+- **Weave the narrative:** TODO: Do not list all friction points in one massive block followed by all fixes/solutions in another. Instead, weave them together chronologically or by component/theme (e.g., describe the friction and its corresponding fix within the same chapter or paragraph).
 - **Do not state the obvious**: TODO: Passed tests, lints, pre-commit suites are mandatory and no ticket is released without this. This does not need to be mentioned

package/dist/templates/steer.txt

@@ -33,9 +33,22 @@ You MUST log your work continuously using `logbook log "<message>"`. This is not
 Phase 3: Synthesize
 1. When implementation is finished, write the narrative in `index.md`.
 2. Storytelling Mode: Explain the "Why" and the "Journey." Avoid simple technical bullet points.
+   - **Keep paragraphs short**: Max 4 sentences per paragraph to ensure fast-paced, readable prose.
+   - **Use bold & code formatting**: Use inline backticks for files/code, and bolding for key terms/problems.
+   - **Structure with H3 headings**: Use action-oriented subheadings describing the topic/component modified (e.g., ### Improving TabGroup Accessibility, ### Binding Dialog Colors to the Theme) instead of generic "Friction" or "Fix" headers.
+   - **Avoid forced lists**: Write in natural, flowing paragraphs. Only use bullet points for simple lists of items (e.g., files modified, options checked), never to split or structure your core narrative thoughts.
+   - **Weave friction & fix**: Do not separate all problems into one block and all solutions into another. Weave them together chronologically or group them by component/theme.
 3. Clean up all template placeholders and complete the frontmatter (author, summary, dates).
 
 Phase 4: Verify
 1. Run `npm run pre` (which includes `logbook lint` and other quality gates).
 2. Ensure there are no linter errors, unreplaced placeholders, or architectural violations before concluding your work. 
-3. Hand back to the prompter, who will review and run `logbook release`.
+3. Hand back to the prompter for local QA/review.
+
+Phase 5: Local QA & Iterative Refinement
+1. Expect feedback loops: The prompter will test your changes, challenge decisions, and request refinements.
+2. In each iteration loop:
+   - Log decisions and pivots in `log.md` in real-time (`logbook log "<message>"`).
+   - Update the story in `index.md` to reflect any design/code changes.
+   - Run verification again (`npm run pre`).
+3. Optimize the git commit message (conforming to project standards) before final release.