project-logbook 0.3.2 → 0.3.4

package/dist/lib/template-helpers.js

@@ -1,20 +1,25 @@
 import { linkJiraIds } from './jira-helpers.js';
-const html = (strings, ...values) => {
+import { formatAbsoluteDate } from '../utils/date.js';
+import { escapeHtml } from './html-escape.js';
+import { ATTR_ENTRY_SLUG, ATTR_DATA_DATE, CLASS_COMMIT_SHA, CLASS_COMMIT_TIME, CLASS_COMMIT_MESSAGE, } from './html-attributes.js';
+export const html = (strings, ...values) => {
     return strings.reduce((acc, str, i) => acc + str + (values[i] ?? ''), '');
 };
 export const navLink = (entry, dir) => {
     const label = dir === 'prev' ? '← Previous' : 'Next →';
-    const t = `${entry.ticket ? `${entry.ticket}: ` : ''}${entry.title}`;
+    const ticket = entry.ticket ? escapeHtml(entry.ticket) : '';
+    const title = escapeHtml(entry.title);
+    const t = `${ticket ? `${ticket}: ` : ''}${title}`;
     return `<a href="../${entry.slug}/index.html" class="post-nav-link"><span class="post-nav-label">${label}</span><span class="post-nav-title">${t}</span></a>`;
 };
 const renderWorkspaces = (workspaces) => {
     if (!workspaces || workspaces.length === 0)
         return '';
-    return workspaces.map((ws) => `<span class="tag-badge tag-workspace">${ws}</span>`).join('');
+    return workspaces.map((ws) => `<span class="tag-badge tag-workspace">${escapeHtml(ws)}</span>`).join('');
 };
 export const renderTagsAndWorkspaces = (tags, workspaces) => {
     const tagsHtml = tags && tags.length > 0
-        ? tags.map((tag) => `<span class="tag-badge tag-${tag.replace('#', '')}">${tag}</span>`).join('')
+        ? tags.map((tag) => `<span class="tag-badge tag-${tag.replace('#', '')}">${escapeHtml(tag)}</span>`).join('')
         : '';
     const wsHtml = renderWorkspaces(workspaces);
     if (!tagsHtml && !wsHtml)
@@ -26,43 +31,49 @@ export const renderCommits = (commits) => {
     if (!commits || commits.length === 0)
         return '';
     const rows = commits
-        .map((c) => `<div class="commit-item"><span class="commit-sha">${c.sha}</span><span class="commit-message">${c.message}</span><span class="commit-time" title="${c.timestamp}">${c.relativeTime}</span></div>`)
+        .map((c) => {
+        const formatted = formatAbsoluteDate(c.timestamp);
+        const sha = escapeHtml(c.sha);
+        const message = escapeHtml(c.message);
+        return `<div class="commit-item"><span class="${CLASS_COMMIT_SHA}">${sha}</span><span class="${CLASS_COMMIT_MESSAGE}">${message}</span><span class="${CLASS_COMMIT_TIME}" title="${c.timestamp}" ${ATTR_DATA_DATE}="${c.timestamp}">${formatted}</span></div>`;
+    })
         .join('');
     return `<div class="commit-list"><h3 class="commit-list-heading">Git Commits</h3>${rows}</div>`;
 };
-export const renderTimelineEntryItem = (e) => html `<div class="timeline-item" data-entry-slug="${e.slug}">
+export const renderTimelineEntryItem = (e) => {
+    const ticket = e.ticket ? escapeHtml(e.ticket) : '';
+    const title = e.title ? escapeHtml(e.title) : '';
+    const llm = e.llm ? escapeHtml(e.llm) : '';
+    const harness = e.harness ? escapeHtml(e.harness) : '';
+    const prompter = e.prompter ? escapeHtml(e.prompter) : '';
+    const summary = e.summary ? escapeHtml(e.summary) : '';
+    return html `<div class="timeline-item" ${ATTR_ENTRY_SLUG}="${e.slug}">
     <a class="timeline-card" href="./${e.slug}/index.html"
       ><div class="item-content">
         <div class="item-meta">
-          <span data-date="${e.dateStart}">${e.displayDate}</span> • <span class="sort-time">${e.sortTime}</span> •
-          ${e.llm ? ` ${e.llm} via ` : ''}${e.harness}${e.prompter ? ` / ${e.prompter}` : ''}
+          <span ${ATTR_DATA_DATE}="${e.dateStart}">${e.displayDate}</span> •
+          ${llm ? ` ${llm} via ` : ''}${harness}${prompter ? ` / ${prompter}` : ''}
         </div>
         <h3 class="item-title">
-          <span class="new-badge" style="display:none;">NEW</span>${e.ticket ? `${e.ticket}: ` : ''}${e.title}
+          <span class="new-badge" style="display:none;">NEW</span>${ticket ? `${ticket}: ` : ''}${title}
         </h3>
-        <div class="item-summary">${e.summary}</div>
+        <div class="item-summary">${summary}</div>
         ${renderTagsAndWorkspaces(e.tags, e.workspaces)}
       </div>
       <span class="item-arrow">›</span></a
     >
   </div>`;
+};
 export const renderTimelineCommitItem = (c, jiraBaseUrl, jiraPrefix) => {
-    const message = jiraBaseUrl && jiraPrefix ? linkJiraIds(c.message, jiraBaseUrl, jiraPrefix) : c.message;
-    return `<div class="timeline-item timeline-item--commit"><div class="commit-chip"><span class="commit-sha">${c.sha}</span><span class="commit-message">${message}</span><span class="commit-time" title="${c.timestamp}" data-date="${c.timestamp}">${c.relativeTime}</span></div></div>`;
+    const message = jiraBaseUrl && jiraPrefix ? linkJiraIds(c.message, jiraBaseUrl, jiraPrefix) : escapeHtml(c.message);
+    const formatted = formatAbsoluteDate(c.timestamp);
+    const sha = escapeHtml(c.sha);
+    return `<div class="timeline-item timeline-item--commit"><div class="commit-chip"><span class="${CLASS_COMMIT_SHA}">${sha}</span><span class="${CLASS_COMMIT_MESSAGE}">${message}</span><span class="${CLASS_COMMIT_TIME}" title="${c.timestamp}" ${ATTR_DATA_DATE}="${c.timestamp}">${formatted}</span></div></div>`;
 };
 export const renderTimelineTagItem = (t) => {
-    const formatted = new Date(t.timestamp)
-        .toLocaleString('de-DE', {
-        year: 'numeric',
-        month: '2-digit',
-        day: '2-digit',
-        hour: '2-digit',
-        minute: '2-digit',
-        second: '2-digit',
-        hour12: false,
-    })
-        .replace(',', '');
-    return `<div class="timeline-item timeline-item--tag"><div class="tag-chip"><span class="tag-chip-icon">🏷</span><span class="tag-chip-name">${t.name}</span><span class="tag-chip-date" title="${t.timestamp}">${formatted}</span></div></div>`;
+    const formatted = formatAbsoluteDate(t.timestamp);
+    const name = escapeHtml(t.name);
+    return `<div class="timeline-item timeline-item--tag"><div class="tag-chip"><span class="tag-chip-icon">🏷</span><span class="tag-chip-name">${name}</span><span class="tag-chip-date" title="${t.timestamp}" ${ATTR_DATA_DATE}="${t.timestamp}">${formatted}</span></div></div>`;
 };
 export const paginationLinks = (currentPage, totalPages) => {
     let links = '';

package/dist/lib/template-types.d.ts

@@ -60,7 +60,6 @@ export interface TimelineCommitItem {
     sha: string;
     message: string;
     timestamp: string;
-    relativeTime: string;
     displayDate: string;
     monthGroup: string;
     sortTime: string;
@@ -83,7 +82,6 @@ export interface GitCommit {
     sha: string;
     message: string;
     timestamp: string;
-    relativeTime: string;
 }
 /**
  * Configuration for the post template

package/dist/lib/templates.d.ts

@@ -10,5 +10,11 @@ export declare const layout: ({ title, header, content, projectName, basePath, d
     bodySlug?: string;
     buildMeta?: string;
 }) => string;
-export declare const timelineTemplate: (props: TimelineTemplateProps) => string;
-export declare const postTemplate: (props: PostTemplateProps) => string;
+export declare const timelineTemplate: (props: TimelineTemplateProps) => {
+    header: string;
+    content: string;
+};
+export declare const postTemplate: (props: PostTemplateProps) => {
+    header: string;
+    content: string;
+};

package/dist/lib/templates.js

@@ -1,13 +1,12 @@
-import { navLink, renderTagsAndWorkspaces, renderCommits, renderTimelineEntryItem, renderTimelineCommitItem, renderTimelineTagItem, paginationLinks, } from './template-helpers.js';
-const html = (strings, ...values) => {
-    return strings.reduce((acc, str, i) => acc + str + (values[i] ?? ''), '');
-};
+import { ATTR_PAGE_SLUG, ATTR_DATA_DATE } from './html-attributes.js';
+import { escapeHtml, validateUrlScheme } from './html-escape.js';
+import { html, navLink, renderTagsAndWorkspaces, renderCommits, renderTimelineEntryItem, renderTimelineCommitItem, renderTimelineTagItem, paginationLinks, } from './template-helpers.js';
 export const tabsComponent = (tabs, defaultActive = 0) => {
     const tabsHtml = tabs
-        .map((tab, index) => `<div class="tab ${index === defaultActive ? 'active' : ''}" role="tab" aria-selected="${index === defaultActive}" aria-controls="${tab.id}" tabindex="${index === defaultActive ? '0' : '-1'}" onclick="showTab(event, '${tab.id}')">${tab.title}</div>`)
+        .map((tab, index) => `<div class="tab ${index === defaultActive ? 'active' : ''}" role="tab" aria-selected="${index === defaultActive}" aria-controls="${escapeHtml(tab.id)}" tabindex="${index === defaultActive ? '0' : '-1'}" onclick="showTab(event, '${escapeHtml(tab.id)}')">${escapeHtml(tab.title)}</div>`)
         .join('');
     const sectionsHtml = tabs
-        .map((tab, index) => `<div id="${tab.id}" class="content-section" role="tabpanel" style="${index === defaultActive ? '' : 'display:none;'}">${tab.content}</div>`)
+        .map((tab, index) => `<div id="${escapeHtml(tab.id)}" class="content-section" role="tabpanel" style="${index === defaultActive ? '' : 'display:none;'}">${tab.content}</div>`)
         .join('');
     return html `<div class="tabs-wrapper">
     <div class="tabs" id="tabs" role="tablist" aria-label="Navigation tabs">${tabsHtml}</div>
@@ -18,12 +17,12 @@ export const layout = ({ title, header, content, projectName, basePath = './', d
 <html lang="en">
 <head>
     <meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>${title} | ${projectName}</title>
-    ${description ? `<meta name="description" content="${description.replace(/"/g, '"').substring(0, 160)}">` : ''}
+    <title>${escapeHtml(title)} | ${escapeHtml(projectName)}</title>
+    ${description ? `<meta name="description" content="${escapeHtml(description).replace(/"/g, '&quot;').substring(0, 160)}">` : ''}
     <link rel="icon" type="image/svg+xml" href="${basePath}favicon.svg">
     <link rel="stylesheet" href="${basePath}style.css">
 </head>
-<body${bodySlug ? ` data-page-slug="${bodySlug}"` : ''}>
+<body${bodySlug ? ` ${ATTR_PAGE_SLUG}="${bodySlug}"` : ''}>
     ${header}<main>${content}</main>
     <footer>${buildMeta ? `<p class="build-time">${buildMeta}</p>` : ''}</footer>
     <script src="${basePath}logbook.js"></script>
@@ -47,51 +46,56 @@ export const timelineTemplate = (props) => {
         .join('')}
     ${paginationLinks(currentPage, totalPages)}
   </div>`;
-    return html `<header>
-      <h1><a href="./index.html">${projectName}</a></h1>
-      <p class="tagline">A brief summary of the recent changes to the project.</p>
-    </header>
-    ${tabsComponent([
+    const header = html `<header>
+    <h1><a href="./index.html">${escapeHtml(projectName)}</a></h1>
+    <p class="tagline">A brief summary of the recent changes to the project.</p>
+  </header>`;
+    const content = tabsComponent([
         { id: 'timeline', title: 'Timeline', content: timelineTab },
         { id: 'readme', title: 'Project Readme', content: readmeHtml || '<p>No README available.</p>' },
         { id: 'about', title: 'About this Logbook', content: aboutHtml || '<p>No information available.</p>' },
-    ], 0)}`;
+    ], 0);
+    return { header, content };
 };
 export const postTemplate = (props) => {
     const { title, displayDate, dateStart, harness, llm, prompter, content, ticketHtml, logHtml, commits, version, jiraUrl, prevEntry, nextEntry, tags, workspaces } = props; // prettier-ignore
-    const jiraBtn = jiraUrl
-        ? `<a href="${jiraUrl}" class="jira-link-btn" target="_blank" rel="noopener noreferrer">View in Jira ↗</a>`
+    // Validate jiraUrl scheme to prevent javascript: URLs
+    const validatedJiraUrl = jiraUrl ? validateUrlScheme(jiraUrl) : undefined;
+    const jiraBtn = validatedJiraUrl
+        ? `<a href="${escapeHtml(validatedJiraUrl)}" class="jira-link-btn" target="_blank" rel="noopener noreferrer">View in Jira ↗</a>`
         : '';
-    const tabBtn = (id, label, active = false) => `<div class="tab${active ? ' active' : ''}" role="tab" aria-selected="${active}" aria-controls="${id}" tabindex="${active ? '0' : '-1'}" onclick="showTab(event, '${id}')">${label}</div>`;
-    return html `<header>
-      <h1>${title}</h1>
-      <div class="tagline">
-        <span data-date="${dateStart}">${displayDate}</span> •
-        ${llm ? `${llm} via ` : ''}${harness}${prompter ? ` / ${prompter}` : ''} • v${version}
-      </div>
-    </header>
-    <article class="tabs-wrapper">
-      <div class="action-bar">
-        <a href="../index.html" class="back-link">← Back to Timeline</a>
-        <div class="action-tabs-wrapper">
-          <div class="tabs" role="tablist" aria-label="Entry sections">
-            ${tabBtn('story', 'Story', true)}${tabBtn('spec', 'Original Spec')}${tabBtn('log', 'Technical Log')}
-          </div>
+    const tabBtn = (id, label, active = false) => `<div class="tab${active ? ' active' : ''}" role="tab" aria-selected="${active}" aria-controls="${escapeHtml(id)}" tabindex="${active ? '0' : '-1'}" onclick="showTab(event, '${escapeHtml(id)}')">${escapeHtml(label)}</div>`;
+    const header = html `<header>
+    <h1>${escapeHtml(title)}</h1>
+    <div class="tagline">
+      <span ${ATTR_DATA_DATE}="${dateStart}">${displayDate}</span> •
+      ${llm ? `${escapeHtml(llm)} via ` : ''}${escapeHtml(harness)}${prompter ? ` / ${escapeHtml(prompter)}` : ''} •
+      v${version}
+    </div>
+  </header>`;
+    const mainContent = html `<article class="tabs-wrapper">
+    <div class="action-bar">
+      <a href="../index.html" class="back-link">← Back to Timeline</a>
+      <div class="action-tabs-wrapper">
+        <div class="tabs" role="tablist" aria-label="Entry sections">
+          ${tabBtn('story', 'Story', true)}${tabBtn('spec', 'Original Spec')}${tabBtn('log', 'Technical Log')}
         </div>
-        ${jiraBtn ? `${jiraBtn}` : ''}
       </div>
-      <div class="content-sections">
-        <div id="story" class="content-section" role="tabpanel">
-          ${renderTagsAndWorkspaces(tags, workspaces)}${content}
-        </div>
-        <div id="spec" class="content-section" role="tabpanel" style="display:none;">${ticketHtml}</div>
-        <div id="log" class="content-section" role="tabpanel" style="display:none;">
-          ${logHtml}${renderCommits(commits)}
-        </div>
+      ${jiraBtn ? `${jiraBtn}` : ''}
+    </div>
+    <div class="content-sections">
+      <div id="story" class="content-section" role="tabpanel">
+        ${renderTagsAndWorkspaces(tags, workspaces)}${content}
+      </div>
+      <div id="spec" class="content-section" role="tabpanel" style="display:none;">${ticketHtml}</div>
+      <div id="log" class="content-section" role="tabpanel" style="display:none;">
+        ${logHtml}${renderCommits(commits)}
       </div>
-      <nav class="post-nav">
-        <div class="post-nav-prev">${prevEntry ? navLink(prevEntry, 'prev') : '<span></span>'}</div>
-        <div class="post-nav-next">${nextEntry ? navLink(nextEntry, 'next') : '<span></span>'}</div>
-      </nav>
-    </article>`;
+    </div>
+    <nav class="post-nav">
+      <div class="post-nav-prev">${prevEntry ? navLink(prevEntry, 'prev') : '<span></span>'}</div>
+      <div class="post-nav-next">${nextEntry ? navLink(nextEntry, 'next') : '<span></span>'}</div>
+    </nav>
+  </article>`;
+    return { header, content: mainContent };
 };

package/dist/lib/theme.d.ts

@@ -0,0 +1,37 @@
+/** Success message styling (green) */
+export declare const success: import("chalk").ChalkInstance;
+/** Error message styling (red) */
+export declare const error: import("chalk").ChalkInstance;
+/** Warning message styling (yellow) */
+export declare const warning: import("chalk").ChalkInstance;
+/** Info/secondary message styling (blue) */
+export declare const info: import("chalk").ChalkInstance;
+/** Neutral/disabled styling (gray) */
+export declare const neutral: import("chalk").ChalkInstance;
+/** Highlight/emphasis styling (cyan) */
+export declare const highlight: import("chalk").ChalkInstance;
+/** Bold text */
+export declare const bold: import("chalk").ChalkInstance;
+/**
+ * Format a section header (e.g., "Checking project integrity...").
+ * Uses blue color for visual separation.
+ */
+export declare function header(text: string): string;
+/**
+ * Format an error message with context.
+ * @param prefix - The category/command name
+ * @param message - The error message
+ */
+export declare function errorMessage(prefix: string, message: string): string;
+/**
+ * Format a warning message with context.
+ * @param prefix - The category/command name
+ * @param message - The warning message
+ */
+export declare function warningMessage(prefix: string, message: string): string;
+/**
+ * Format a success message with context.
+ * @param prefix - The category/command name
+ * @param message - The success message
+ */
+export declare function successMessage(prefix: string, message: string): string;

package/dist/lib/theme.js

@@ -0,0 +1,50 @@
+/**
+ * Centralized styling/theme for CLI output.
+ * Ensures consistent colors and visual hierarchy across all commands.
+ */
+import chalk from 'chalk';
+/** Success message styling (green) */
+export const success = chalk.green;
+/** Error message styling (red) */
+export const error = chalk.red;
+/** Warning message styling (yellow) */
+export const warning = chalk.yellow;
+/** Info/secondary message styling (blue) */
+export const info = chalk.blue;
+/** Neutral/disabled styling (gray) */
+export const neutral = chalk.gray;
+/** Highlight/emphasis styling (cyan) */
+export const highlight = chalk.cyan;
+/** Bold text */
+export const bold = chalk.bold;
+/**
+ * Format a section header (e.g., "Checking project integrity...").
+ * Uses blue color for visual separation.
+ */
+export function header(text) {
+    return info(text);
+}
+/**
+ * Format an error message with context.
+ * @param prefix - The category/command name
+ * @param message - The error message
+ */
+export function errorMessage(prefix, message) {
+    return `${error(prefix)}: ${message}`;
+}
+/**
+ * Format a warning message with context.
+ * @param prefix - The category/command name
+ * @param message - The warning message
+ */
+export function warningMessage(prefix, message) {
+    return `${warning(prefix)}: ${message}`;
+}
+/**
+ * Format a success message with context.
+ * @param prefix - The category/command name
+ * @param message - The success message
+ */
+export function successMessage(prefix, message) {
+    return `${success(prefix)}: ${message}`;
+}

package/dist/lib/url-helpers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Check if a URL/path is external (has an absolute URI scheme).
+ * @param url - The URL or path to check
+ * @returns true if the URL has an absolute URI scheme (http://, https://, ftp://, etc.)
+ */
+export declare function isExternalUrl(url: string): boolean;
+/**
+ * Check if a value is an external URL or an anchor link.
+ * Used to identify URLs that should not be processed (rewritten, collected, etc.)
+ * @param href - The href/src value to check
+ * @returns true if the value is external or an anchor
+ */
+export declare function isExternalUrlOrAnchor(href: string): boolean;

package/dist/lib/url-helpers.js

@@ -0,0 +1,27 @@
+/**
+ * Regex pattern to detect absolute URLs with URI schemes.
+ * Matches URIs like: http://, https://, ftp://, data:, etc.
+ * Pattern breakdown:
+ *   ^[a-z]        - Starts with a letter (lowercase)
+ *   [a-z\d+\-.]*: - Followed by alphanumeric, +, -, or . characters, ending with :
+ * Example matches: http://, https://, ftp://, mailto:, data:
+ * Used to distinguish external URLs from relative paths.
+ */
+const EXTERNAL_URL_SCHEME_REGEX = /^[a-z][a-z\d+\-.]*:/i;
+/**
+ * Check if a URL/path is external (has an absolute URI scheme).
+ * @param url - The URL or path to check
+ * @returns true if the URL has an absolute URI scheme (http://, https://, ftp://, etc.)
+ */
+export function isExternalUrl(url) {
+    return EXTERNAL_URL_SCHEME_REGEX.test(url);
+}
+/**
+ * Check if a value is an external URL or an anchor link.
+ * Used to identify URLs that should not be processed (rewritten, collected, etc.)
+ * @param href - The href/src value to check
+ * @returns true if the value is external or an anchor
+ */
+export function isExternalUrlOrAnchor(href) {
+    return EXTERNAL_URL_SCHEME_REGEX.test(href) || href.startsWith('#');
+}

package/dist/linters/diff-to-narrative.d.ts

@@ -0,0 +1,6 @@
+import { Linter } from '../lib/lint-types.js';
+export declare function stripFrontmatter(content: string): string;
+export declare function stripMarkdown(text: string): string;
+export declare function getWordCount(content: string): number;
+declare const linter: Linter;
+export default linter;

package/dist/linters/diff-to-narrative.js

@@ -0,0 +1,114 @@
+import { getActiveEntry } from '../lib/session.js';
+import { getChangedLOC } from '../lib/git-helpers.js';
+import fs from 'fs-extra';
+import { join } from 'node:path';
+// Thresholds & Limits Configuration
+const TRIVIAL_LOC_MAX = 20;
+const STANDARD_LOC_MAX = 150;
+const TRIVIAL_WORDS = { min: 30, max: 150 };
+const STANDARD_WORDS = { min: 50, max: 300 };
+const LARGE_WORDS = { min: 100, max: 400 };
+export function stripFrontmatter(content) {
+    const lines = content.split(/\r?\n/);
+    if (lines[0]?.trim() === '---') {
+        const endIdx = lines.indexOf('---', 1);
+        if (endIdx !== -1) {
+            return lines.slice(endIdx + 1).join('\n');
+        }
+    }
+    return content;
+}
+export function stripMarkdown(text) {
+    return text
+        .replace(/<[^>]*>/g, '') // HTML tags
+        .replace(/!\[([^\]]*)]\([^)]*\)/g, '$1') // images
+        .replace(/\[([^\]]*)]\([^)]*\)/g, '$1') // links
+        .replace(/```[\s\S]*?```/g, '') // code blocks
+        .replace(/`([^`]+)`/g, '$1') // inline code
+        .replace(/(\*\*|__)(.*?)\1/g, '$2') // bold
+        .replace(/(\*|_)(.*?)\1/g, '$2') // italic
+        .replace(/^\s*>\s+/gm, '') // blockquotes
+        .replace(/^\s*#+\s+/gm, '') // headings
+        .replace(/^\s*[-*+]\s+/gm, '') // list bullets
+        .replace(/^\s*\d+\.\s+/gm, ''); // ordered lists
+}
+export function getWordCount(content) {
+    const clean = stripMarkdown(stripFrontmatter(content));
+    return clean.split(/\s+/).filter((w) => w.trim().length > 0).length;
+}
+const linter = {
+    name: 'diff-to-narrative',
+    description: 'Checks word count of active index.md against total LOC changed',
+    async check(context) {
+        // Only target project-level checks
+        if (context.entryName)
+            return [];
+        const active = await getActiveEntry();
+        if (!active || active.source !== 'lockfile') {
+            return [];
+        }
+        const logbookDir = context.config.logbookDir;
+        const { total: totalLOC } = await getChangedLOC(logbookDir);
+        // If there are no active changes and the tree is completely clean, skip gracefully
+        if (totalLOC === 0) {
+            return [];
+        }
+        const indexPath = join(process.cwd(), logbookDir, active.slug, 'index.md');
+        if (!(await fs.pathExists(indexPath))) {
+            return [];
+        }
+        const content = await fs.readFile(indexPath, 'utf-8');
+        const wordCount = getWordCount(content);
+        const issues = [];
+        if (totalLOC < TRIVIAL_LOC_MAX) {
+            if (wordCount < TRIVIAL_WORDS.min) {
+                issues.push({
+                    level: 'warning',
+                    category: 'story-ratio',
+                    message: `Code change is trivial (${totalLOC} LOC), but index.md has only ${wordCount} words (minimum is ${TRIVIAL_WORDS.min}). Please expand the narrative.`,
+                });
+            }
+            else if (wordCount > TRIVIAL_WORDS.max) {
+                issues.push({
+                    level: 'warning',
+                    category: 'story-ratio',
+                    message: `Warning: Code change is trivial, but index.md exceeds ${TRIVIAL_WORDS.max} words. Please summarize.`,
+                });
+            }
+        }
+        else if (totalLOC <= STANDARD_LOC_MAX) {
+            if (wordCount < STANDARD_WORDS.min) {
+                issues.push({
+                    level: 'warning',
+                    category: 'story-ratio',
+                    message: `Code change is standard (${totalLOC} LOC), but index.md has only ${wordCount} words (minimum is ${STANDARD_WORDS.min}). Please expand the narrative.`,
+                });
+            }
+            else if (wordCount > STANDARD_WORDS.max) {
+                issues.push({
+                    level: 'warning',
+                    category: 'story-ratio',
+                    message: `Warning: Code change is standard (${totalLOC} LOC), but index.md exceeds ${STANDARD_WORDS.max} words. Please summarize.`,
+                });
+            }
+        }
+        else {
+            if (wordCount < LARGE_WORDS.min) {
+                issues.push({
+                    level: 'warning',
+                    category: 'story-ratio',
+                    message: `Code change is large (${totalLOC} LOC), but index.md has only ${wordCount} words (minimum is ${LARGE_WORDS.min}). Please expand the narrative.`,
+                });
+            }
+            else if (wordCount > LARGE_WORDS.max) {
+                issues.push({
+                    level: 'warning',
+                    category: 'story-ratio',
+                    message: `Warning: Story exceeds ${LARGE_WORDS.max} words. Consider summarizing and linking to a Wiki/ADR.`,
+                });
+            }
+        }
+        return issues;
+    },
+};
+export default linter;

package/dist/linters/index.js

@@ -1,3 +1,4 @@
+import diffToNarrative from './diff-to-narrative.js';
 import frontmatter from './frontmatter.js';
 import jiraPrefix from './jira-prefix.js';
 import links from './links.js';
@@ -7,6 +8,7 @@ import projectIntegrity from './project-integrity.js';
 import readability from './readability.js';
 import workspaces from './workspaces.js';
 export const linters = [
+    diffToNarrative,
     frontmatter,
     jiraPrefix,
     links,

package/dist/templates/CONTRIBUTING.md

@@ -47,12 +47,21 @@ Only update the currently active logbook entry. Do not edit other existing entri
 When you finish writing `index.md`, **remove the boilerplate link line** that the template inserts:
 
 ### 3. Quality Assurance
-Before submitting your work, you MUST release the active entry and run the linter:
+Before finalizing your work, you should run the linter to verify there are no errors:
 ```bash
-logbook release
 logbook lint
 ```
-`logbook release` removes the `.logbook-active` lockfile. The linter will fail if the lockfile is still present, enforcing that no entry is left dangling in a committed state.
+
+You can also check the overall status of the logbook, configuration settings, and statistics (total tasks, done, and drafts) using:
+```bash
+logbook status
+```
+
+The linter will warn you if the lockfile `.logbook-active` is still present, which is expected during active development.
+
+Once the work is ready:
+- **If you are an AI agent**: Do not release the entry. Hand back to the prompter, who will review and run `logbook release`.
+- **If you are a human developer**: Run `logbook release` to remove the lockfile and finalize the entry.
 
 The linter enforces rules to be followed.
 

package/dist/templates/index.md

@@ -3,19 +3,19 @@
 ticket: {{id}}
 # The title should be a human-readable description of the work
 title: {{title}}
-prompter: [PROMPTER]
-harness: [HARNESS]
-llm: [LLM]
-summary: [WRITE_SUMMARY_HERE]
+prompter: "[PROMPTER]"
+harness: "[HARNESS]"
+llm: "[LLM]"
+summary: "[WRITE_SUMMARY_HERE]"
 # Tags for categorizing the change (must be from allowed list in .project-logbook)
 tags: []
 # Workspace(s) this change affects (must match package.json workspaces; leave empty for single-project)
 # Example: workspaces: ["frontend", "shared"]
 workspaces: []
 # Set automatically by `logbook start`
-dateStart: [DATE_START]
+dateStart: "[DATE_START]"
 # Set automatically by `logbook release`
-dateEnd: [DATE_END]
+dateEnd: "[DATE_END]"
 ---
 
 ## Summary