@thanbir-tamim/enterprise-project-intelligence-agent 0.1.1 → 0.2.0

package/skills/project-documentation-discovery/scripts/secrets.mjs

@@ -0,0 +1,99 @@
+/**
+ * Shared secret-likeness detection (no dependencies).
+ * Used by inventory.mjs (redaction before indexing) and by the repo-level release audit.
+ *
+ * Design goals (from the evaluation findings F-08/F-09):
+ *  - catch real-looking secrets: private-key blocks, keyed assignments (API_KEY=..., token: ...),
+ *    AWS access key IDs, bearer tokens, credentialed connection strings, high-entropy tokens;
+ *  - do NOT flag ordinary identifiers (SNAKE_CASE / kebab-case names), slash-separated prose,
+ *    or file paths — those caused false positives and destroyed evidence headings.
+ * Matching is heuristic: a safeguard, not proof that no secret exists.
+ */
+
+export function shannonEntropy(s) {
+  const freq = new Map();
+  for (const ch of s) freq.set(ch, (freq.get(ch) || 0) + 1);
+  let h = 0;
+  for (const n of freq.values()) { const p = n / s.length; h -= p * Math.log2(p); }
+  return h;
+}
+
+const KEY_NAME = String.raw`[A-Za-z0-9_.-]*(?:api[_-]?key|secret|token|passw(?:or)?d|pwd|credential|access[_-]?key|private[_-]?key|client[_-]?secret)[A-Za-z0-9_.-]*`;
+
+export const SECRET_RULES = [
+  { id: "private-key-block", re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g },
+  { id: "aws-access-key-id", re: /\bAKIA[0-9A-Z]{16}\b/g },
+  { id: "bearer-token", re: /\bBearer\s+[A-Za-z0-9\-_.=]{20,}/g },
+  { id: "connection-string-with-credentials", re: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@<>]+:[^\s:/@<>]+@[^\s]+/gi },
+  // KEY=value / key: "value" where the key name looks secret-bearing and the value is non-trivial
+  { id: "keyed-secret-assignment", re: new RegExp(String.raw`\b(${KEY_NAME})\s*[:=]\s*["']?([^\s"'#,;]{12,})`, "gi"), valueGroup: 2, keyFilter: true },
+];
+
+const IDENTIFIER_LIKE = [
+  /^[A-Z0-9]+(?:_[A-Z0-9]+)+$/,          // SNAKE_CASE constants / handler names
+  /^[a-z0-9]+(?:[-_][a-z0-9]+)+$/,       // kebab-case / snake_case words
+  /^[A-Za-z]+(?:\/[A-Za-z]+)+$/,          // slash-separated words (security/privacy/legal)
+  /^[a-f0-9]{32}$|^[a-f0-9]{40}$|^[a-f0-9]{64}$/i, // content hashes / commit SHAs are not secrets
+  /^sha(?:1|256|384|512)-[A-Za-z0-9+/]+={0,2}$/,   // subresource-integrity hashes (package metadata)
+];
+
+/** Paths, slugs and compound names: mostly real words joined by - _ / . (e.g. a-b--c/d.md#e). */
+function isWordy(tok) {
+  const parts = tok.split(/[-_/.#=+]+/).filter(Boolean);
+  const words = parts.filter((p) => /^[A-Za-z]{3,}$/.test(p));
+  return parts.length >= 3 && words.length / parts.length >= 0.6;
+}
+
+/** True when a long token looks like a random secret rather than an identifier. */
+export function isHighEntropyToken(tok) {
+  if (tok.length < 32) return false;
+  if (IDENTIFIER_LIKE.some((re) => re.test(tok)) || isWordy(tok)) return false;
+  if (!/[0-9]/.test(tok) || !/[A-Za-z]/.test(tok)) return false;
+  return shannonEntropy(tok) >= 3.8;
+}
+
+const PLACEHOLDER_VALUE = /^(<[^>]*>|\$\{[^}]*\}|x{6,}|\*{6,}|changeme|example|your[_-]?\w*|placeholder|redacted.*|\[redacted.*)$/i;
+
+/** Find secret-like spans in one line. Returns [{ rule, start, end }]. Never returns the value itself. */
+export function findSecrets(line) {
+  const hits = [];
+  for (const rule of SECRET_RULES) {
+    rule.re.lastIndex = 0;
+    let m;
+    while ((m = rule.re.exec(line))) {
+      if (rule.valueGroup) {
+        const value = m[rule.valueGroup];
+        if (PLACEHOLDER_VALUE.test(value) || /^(true|false|null|none|\d+)$/i.test(value)) continue;
+        // code references (token: getToken(), secret = config.secret, short identifiers) are not secrets
+        if (IDENTIFIER_LIKE.slice(0, 3).some((re) => re.test(value)) || /[().]/.test(value) || (value.length < 20 && /^[A-Za-z_]+$/.test(value))) continue;
+        const start = m.index + m[0].lastIndexOf(value);
+        hits.push({ rule: rule.id, start, end: start + value.length });
+      } else {
+        hits.push({ rule: rule.id, start: m.index, end: m.index + m[0].length });
+      }
+    }
+  }
+  const tokRe = /[A-Za-z0-9+/_-]{32,}={0,2}/g;
+  let t;
+  while ((t = tokRe.exec(line))) {
+    if (hits.some((h) => t.index < h.end && t.index + t[0].length > h.start)) continue;
+    if (isHighEntropyToken(t[0])) hits.push({ rule: "high-entropy-token", start: t.index, end: t.index + t[0].length });
+  }
+  return hits.sort((a, b) => a.start - b.start);
+}
+
+/** Redact secret-like spans in text. Returns { text, findings: [{ line, rule }] }. */
+export function redactText(text) {
+  const findings = [];
+  let inKey = false;
+  const lines = text.split("\n").map((line, i) => {
+    if (/-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(line)) { inKey = true; findings.push({ line: i + 1, rule: "private-key-block" }); return "[REDACTED-PRIVATE-KEY]"; }
+    if (inKey) { if (/-----END [A-Z ]*PRIVATE KEY-----/.test(line)) inKey = false; return ""; }
+    const hits = findSecrets(line);
+    if (!hits.length) return line;
+    let out = line;
+    for (const h of [...hits].reverse()) { out = out.slice(0, h.start) + "[REDACTED-SECRET-LIKE-VALUE]" + out.slice(h.end); findings.push({ line: i + 1, rule: h.rule }); }
+    return out;
+  });
+  return { text: lines.join("\n"), findings: findings.sort((a, b) => a.line - b.line) };
+}

package/skills/project-knowledge-assistant/SKILL.md

@@ -1,12 +1,6 @@
 ---
 name: project-knowledge-assistant
-description: >-
-  Answer questions about a target project strictly from the evidence collected by
-  project-documentation-discovery (and, where applicable, software-reverse-engineering), always
-  citing source_location, and clearly separating documented facts from inference. Use this skill
-  whenever a user asks "what does the system do", "how does X work", or any question about the
-  target project, after an evidence index exists. Never answers from general knowledge about similar
-  systems as if it were specific to this project.
+description: "Answer questions about a target project strictly from the evidence collected by project-documentation-discovery (and, where applicable, software-reverse-engineering), always citing source_location, and clearly separating documented facts from inference. Use this skill whenever a user asks 'what does the system do', 'how does X work', or any question about the target project, after an evidence index exists. Never answers from general knowledge about similar systems as if it were specific to this project."
 metadata:
   version: 1.0.0
   partOf: enterprise-project-intelligence-agent

package/skills/software-change-impact-analyzer/SKILL.md

@@ -1,10 +1,6 @@
 ---
 name: software-change-impact-analyzer
-description: >-
-  Trace the likely effects of a proposed change across modules, APIs, workflows, tests, data
-  entities, and documentation, using evidence from software-reverse-engineering and
-  project-documentation-discovery. Use this skill before implementing a non-trivial change, when
-  estimating risk/effort, or when a user asks "what would break if we changed X".
+description: "Trace the likely effects of a proposed change across modules, APIs, workflows, tests, data entities, and documentation, using evidence from software-reverse-engineering and project-documentation-discovery. Use this skill before implementing a non-trivial change, when estimating risk/effort, or when a user asks 'what would break if we changed X'."
 metadata:
   version: 1.0.0
   partOf: enterprise-project-intelligence-agent
@@ -22,23 +18,30 @@ the available documentation/code actually reveals, rather than a confident-sound
 ## Required inputs
 
 - A description of the proposed change (what module/API/data entity/workflow it touches).
-- Architecture/data-model evidence from `software-reverse-engineering`.
+- `system-map.json` from `software-reverse-engineering`
+  (schema: `skills/software-reverse-engineering/references/system-map-schema.md`) when it exists.
+  If it does not, build the minimal map you need directly from the code and documentation (modules,
+  routes, entities, tests that reference the target) and state in the report that no system map was
+  available.
 - Evidence index from `project-documentation-discovery`.
 
 ## Execution procedure
 
 1. **Identify the direct target** (the module/API/entity named in the change) and confirm it exists
    in the evidence, citing it.
-2. **Trace direct dependents** using `references/impact-dimensions.md`: callers of a changed API,
+2. **Search exhaustively for references to the target** (the route string, entity/field name,
+   function name, and its documented spelling variants such as `{id}` vs `:id`) across code, tests,
+   configuration, and documentation; every hit is a candidate impact.
+3. **Trace direct dependents** using `references/impact-dimensions.md`: callers of a changed API,
    consumers of a changed data entity, UI components bound to a changed route, tests exercising the
    changed code, and documentation describing the changed behavior.
-3. **Trace indirect/second-order effects** only as far as evidence supports (e.g., a downstream
+4. **Trace indirect/second-order effects** only as far as evidence supports (e.g., a downstream
    service that itself calls the directly affected service); label second-order effects as
    `likely, lower confidence` rather than equally certain to first-order effects.
-4. **Classify severity per impacted item**: `breaking` (contract changes), `behavioral`
+5. **Classify severity per impacted item**: `breaking` (contract changes), `behavioral`
    (output/behavior changes without a contract break), `cosmetic`, or `unknown-needs-investigation`.
-5. **List tests and documentation that must be updated**, not just code.
-6. **State what could not be assessed** (e.g., parts of the system outside the available evidence)
+6. **List tests and documentation that must be updated**, not just code.
+7. **State what could not be assessed** (e.g., parts of the system outside the available evidence)
    explicitly, rather than implying full coverage.
 
 ## Expected outputs
@@ -71,3 +74,4 @@ reference, a documented workflow step).
 ## References
 
 - `references/impact-dimensions.md`
+- `skills/software-reverse-engineering/references/system-map-schema.md` — input artifact format

package/skills/software-reverse-engineering/SKILL.md

@@ -1,18 +1,13 @@
 ---
 name: software-reverse-engineering
-description: >-
-  Reconstruct a target system's architecture, modules, APIs, data model, workflows, and external
-  dependencies from available evidence (documentation and/or source code), clearly separating facts
-  verified in code from facts only documented and from inferences. Use this skill after
-  project-documentation-discovery when the user needs an architecture picture, a module map, a data
-  model, or a workflow reconstruction, especially when documentation is incomplete, outdated, or the
-  codebase is only partially available.
+description: "Reconstruct a target system's architecture, modules, APIs, data model, workflows, and external dependencies from available evidence (documentation and/or source code), clearly separating facts verified in code from facts only documented and from inferences. Use this skill after project-documentation-discovery when the user needs an architecture picture, a module map, a data model, or a workflow reconstruction, especially when documentation is incomplete, outdated, or the codebase is only partially available."
 metadata:
   version: 1.0.0
   partOf: enterprise-project-intelligence-agent
   references:
     - references/reconstruction-method.md
     - references/architecture-diagram-notation.md
+    - references/system-map-schema.md
 ---
 
 # software-reverse-engineering
@@ -45,17 +40,25 @@ what cannot be determined from the materials provided.
    the reconstruction as `documented-only, not code-verified`.
 5. **Identify external dependencies** (third-party services, libraries with material behavioral
    impact, infrastructure dependencies) from manifests/config and documentation.
-6. **Reconcile conflicts.** When documentation and code disagree, record both, mark the code as
+6. **Cross-check every documented item against code.** For each endpoint, route, health check,
+   scheduled job, setting, or procedure mentioned in documentation (including runbooks and READMEs,
+   not only API references), confirm it exists in the inspected code. Record each one that does not
+   as a `documented-not-implemented` discrepancy, and each implemented item missing from the docs
+   as `implemented-not-documented`.
+7. **Reconcile conflicts.** When documentation and code disagree, record both, mark the code as
    generally more authoritative for *current* behavior, and flag the documentation as outdated —
    but do not discard the documentation; it may describe intended/future behavior.
-7. **Record architectural decisions and security boundaries** found in ADRs, comments, or
+8. **Record architectural decisions and security boundaries** found in ADRs, comments, or
    documentation; do not infer a security boundary that is not actually enforced in code if code is
    available to check.
-8. **State explicit limitations** — list what could not be verified due to missing/partial code,
+9. **State explicit limitations** — list what could not be verified due to missing/partial code,
    obfuscation, or unavailable services, rather than presenting a best-guess architecture as complete.
 
 ## Expected outputs
 
+- `system-map.json` following `references/system-map-schema.md` (written to the user's private
+  working directory) — the machine-readable map other skills consume.
+
 - Module/subsystem map with evidence citations.
 - API/route inventory with verification status.
 - Data model summary with relationship evidence.
@@ -97,3 +100,4 @@ a citation for the first two and a stated rationale for the third.
 
 - `references/reconstruction-method.md`
 - `references/architecture-diagram-notation.md`
+- `references/system-map-schema.md` — shared `system-map.json` artifact format

package/skills/software-reverse-engineering/references/system-map-schema.md

@@ -0,0 +1,27 @@
+# system-map.json schema (shared artifact)
+
+`software-reverse-engineering` writes this file next to its report (in the user's private working
+directory, e.g. `.local-knowledge/<project-id>/system-map.json`). `software-change-impact-analyzer`
+and `engineering-knowledge-transfer` read it instead of re-deriving the architecture.
+
+```json
+{
+  "generatedFrom": "evidence-index.json + source files inspected (list them)",
+  "modules":   [{ "id": "mod:tickets-routes", "name": "Ticket routes", "location": "src/tickets.js#L4-L19", "status": "verified-in-code" }],
+  "apis":      [{ "id": "api:GET /tickets/:id", "method": "GET", "path": "/tickets/:id", "auth": "agent",
+                  "implementedAt": "src/tickets.js#L10", "documentedAt": "docs/api.md#endpoints",
+                  "status": "verified-in-code", "testedBy": ["tests/tickets.test.js#L2-L5"] }],
+  "dataEntities": [{ "id": "data:Ticket", "fields": ["subject", "body", "status"], "evidence": "src/tickets.js#L6", "status": "verified-in-code" }],
+  "dependencies": [{ "id": "dep:db", "kind": "datastore", "evidence": "src/tickets.js#L4", "status": "inferred", "note": "technology unknown" }],
+  "edges":     [{ "from": "api:GET /tickets/:id", "to": "data:Ticket", "relation": "reads", "evidence": "src/tickets.js#L11", "status": "verified-in-code" }],
+  "discrepancies": [{ "kind": "documented-not-implemented", "item": "DELETE /tickets/{id}", "documentedAt": "docs/api.md#endpoints", "codeChecked": ["src/tickets.js"] }],
+  "unknowns": ["database technology", "auth implementation"]
+}
+```
+
+Rules
+- `status` is one of `verified-in-code`, `documented-only`, `inferred`.
+- Every entry carries at least one `source_location` (`evidence`, `implementedAt`, or `documentedAt`).
+- `discrepancies[].kind` is one of `documented-not-implemented`, `implemented-not-documented`,
+  `value-mismatch`, `behavior-mismatch`.
+- Never add an entry without evidence; record gaps in `unknowns` instead.

package/skills/technical-document-generator/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: technical-document-generator
-description: >-
-  Produce consistent technical documentation (Markdown and HTML reliably; DOCX/PPTX only through a
-  verified workflow) from project evidence and/or other skills' outputs, following a consistent
-  document structure and citation style. Use this skill whenever a user needs a written artifact
-  (architecture doc, AI planning doc, onboarding guide, risk register) assembled from evidence
-  already gathered by other skills, rather than generating prose from scratch without grounding.
+description: "Produce consistent technical documentation (Markdown and HTML reliably; DOCX/PPTX only through a verified workflow) from project evidence and/or other skills' outputs, following a consistent document structure and citation style. Use this skill whenever a user needs a written artifact (architecture doc, AI planning doc, onboarding guide, risk register) assembled from evidence already gathered by other skills, rather than generating prose from scratch without grounding."
 metadata:
   version: 1.0.0
   partOf: enterprise-project-intelligence-agent
@@ -37,8 +32,11 @@ dropping evidence links in the process.
    repo-root `templates/` directory if one exists for this document type.
 2. **Populate sections from evidence**, preserving every citation attached to the source finding.
    Do not paraphrase away a citation.
-3. **Render to the target format.** For Markdown → HTML, use `scripts/render-markdown-to-html.mjs`
-   (built-in, verified). For DOCX/PPTX, only claim support if the consuming project has wired in a
+3. **Render to the target format.** For Markdown → HTML, run
+   `node scripts/render-markdown-to-html.mjs <in.md> <out.html>` (built-in, verified). It supports
+   headings, paragraphs, bullet and numbered lists, blockquotes, tables, fenced and inline code,
+   links, bold and italic; it HTML-escapes all text and drops links whose scheme is not http(s),
+   mailto, relative, or `#anchor` (e.g. `javascript:`), so untrusted Markdown cannot inject script. For DOCX/PPTX, only claim support if the consuming project has wired in a
    verified exporter; otherwise, hand back a Markdown document plus an explicit note that DOCX/PPTX
    export requires an additional, verified conversion step.
 4. **Validate the result**: well-formed Markdown (no unmatched code fences, consistent heading

package/skills/technical-document-generator/scripts/render-markdown-to-html.mjs

@@ -1,93 +1,103 @@
 #!/usr/bin/env node
-import { pathToFileURL } from "node:url";
 /**
- * Minimal, dependency-free Markdown -> HTML renderer covering headings, paragraphs, lists,
- * code fences, links, bold/italic, and tables. Intentionally conservative: it does not attempt
- * full CommonMark compliance, only enough to produce valid, well-formed HTML for the structured
- * documents this toolkit generates. Verified by tests/render.test.mjs.
+ * Minimal, dependency-free Markdown -> HTML renderer for the structured documents this toolkit
+ * generates: headings, paragraphs, unordered and ordered lists, blockquotes, fenced code, tables,
+ * links, bold/italic, and inline code. Not full CommonMark.
+ *
+ * Safety: all text is HTML-escaped; link URLs are restricted to http(s), mailto, relative paths and
+ * #anchors — anything else (javascript:, data:, vbscript:, ...) is rendered as plain text, so
+ * model- or user-supplied Markdown cannot inject script. Verified by tests/markdown-render.test.mjs.
  */
+import { pathToFileURL } from "node:url";
+
+const escapeHtml = (t) => t.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+export function isSafeUrl(url) {
+  const u = url.trim().replace(/[\u0000-\u001F\u007F\s]+/g, "");
+  if (/^(https?:|mailto:)/i.test(u)) return true;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(u)) return false; // any other scheme (javascript:, data:, file:, ...)
+  return true; // relative path, ./x, ../x, /x, #anchor
+}
+
+/** Inline formatting with code spans protected from emphasis/link processing. */
+function inline(text) {
+  const codes = [];
+  let t = text.replace(/`([^`]+)`/g, (_, c) => { codes.push(c); return `\u0000${codes.length - 1}\u0000`; });
+  t = escapeHtml(t);
+  t = t.replace(/\[([^\]]+)\]\(([^()\s]+(?:\([^()\s]*\))?[^()\s]*)\)/g, (m, label, url) => {
+    const raw = url.replace(/&amp;/g, "&").replace(/&quot;/g, '"');
+    return isSafeUrl(raw) ? `<a href="${escapeHtml(raw)}">${label}</a>` : `${label} (unsafe link removed)`;
+  });
+  t = t.replace(/\*\*(.+?)\*\*/g, "<strong>$1</strong>").replace(/(^|[^\w*])\*(?!\s)(.+?)\*(?!\w)/g, "$1<em>$2</em>");
+  return t.replace(/\u0000(\d+)\u0000/g, (_, i) => `<code>${escapeHtml(codes[Number(i)])}</code>`);
+}
+
 export function renderMarkdownToHtml(md) {
-  const lines = md.split("\n");
-  let html = "";
+  const lines = md.replace(/\r\n/g, "\n").split("\n");
+  const out = [];
+  let list = null;      // "ul" | "ol"
+  let table = null;     // row count
+  let quote = [];       // pending blockquote lines
   let inCode = false;
-  let inList = false;
-  let inTable = false;
-  let tableRow = 0;
-
-  const inline = (text) =>
-    text
-      .replace(/&/g, "&amp;")
-      .replace(/</g, "&lt;")
-      .replace(/>/g, "&gt;")
-      .replace(/\*\*(.+?)\*\*/g, "<strong>$1</strong>")
-      .replace(/\*(.+?)\*/g, "<em>$1</em>")
-      .replace(/`(.+?)`/g, "<code>$1</code>")
-      .replace(/\[(.+?)\]\((.+?)\)/g, '<a href="$2">$1</a>');
 
-  const closeList = () => { if (inList) { html += "</ul>\n"; inList = false; } };
-  const closeTable = () => { if (inTable) { html += "</table>\n"; inTable = false; tableRow = 0; } };
+  const closeList = () => { if (list) { out.push(`</${list}>`); list = null; } };
+  const closeTable = () => { if (table !== null) { out.push("</table>"); table = null; } };
+  const closeQuote = () => { if (quote.length) { out.push(`<blockquote>${renderMarkdownToHtml(quote.join("\n")).match(/<body>\n([\s\S]*)<\/body>/)[1].trim()}</blockquote>`); quote = []; } };
+  const closeAll = () => { closeList(); closeTable(); closeQuote(); };
 
-  for (const raw of lines) {
-    const line = raw;
-    if (line.trim().startsWith("```")) {
-      closeList(); closeTable();
-      html += inCode ? "</code></pre>\n" : "<pre><code>";
-      inCode = !inCode;
-      continue;
+  for (const line of lines) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      if (!inCode) { closeAll(); out.push("<pre><code>"); } else out.push("</code></pre>");
+      inCode = !inCode; continue;
     }
-    if (inCode) { html += inline(line) + "\n"; continue; }
+    if (inCode) { out.push(escapeHtml(line)); continue; }
 
-    const heading = /^(#{1,6})\s+(.*)$/.exec(line);
-    if (heading) {
-      closeList(); closeTable();
-      const level = heading[1].length;
-      html += `<h${level}>${inline(heading[2])}</h${level}>\n`;
-      continue;
-    }
+    const bq = /^\s*>\s?(.*)$/.exec(line);
+    if (bq) { closeList(); closeTable(); quote.push(bq[1]); continue; }
+    closeQuote();
+
+    const heading = /^(#{1,6})\s+(.*?)\s*#*\s*$/.exec(line);
+    if (heading) { closeAll(); const l = heading[1].length; out.push(`<h${l}>${inline(heading[2])}</h${l}>`); continue; }
 
-    const listItem = /^[-*]\s+(.*)$/.exec(line);
-    if (listItem) {
+    const ul = /^\s*[-*+]\s+(.*)$/.exec(line);
+    const ol = /^\s*\d+[.)]\s+(.*)$/.exec(line);
+    if (ul || ol) {
       closeTable();
-      if (!inList) { html += "<ul>\n"; inList = true; }
-      html += `<li>${inline(listItem[1])}</li>\n`;
-      continue;
+      const kind = ul ? "ul" : "ol";
+      if (list !== kind) { closeList(); out.push(`<${kind}>`); list = kind; }
+      out.push(`<li>${inline((ul || ol)[1])}</li>`); continue;
     }
+    if (list && /^\s{2,}\S/.test(line)) { out[out.length - 1] = out[out.length - 1].replace(/<\/li>$/, ` ${inline(line.trim())}</li>`); continue; }
     closeList();
 
-    const tableLine = /^\|(.+)\|$/.exec(line.trim());
+    const tableLine = /^\|(.+)\|\s*$/.exec(line.trim());
     if (tableLine) {
       const cells = tableLine[1].split("|").map((c) => c.trim());
-      if (cells.every((c) => /^-+$/.test(c))) continue; // separator row
-      if (!inTable) { html += "<table>\n"; inTable = true; tableRow = 0; }
-      const tag = tableRow === 0 ? "th" : "td";
-      html += `<tr>${cells.map((c) => `<${tag}>${inline(c)}</${tag}>`).join("")}</tr>\n`;
-      tableRow++;
+      if (cells.every((c) => /^:?-+:?$/.test(c))) continue; // separator row
+      if (table === null) { out.push("<table>"); table = 0; }
+      const tag = table === 0 ? "th" : "td";
+      out.push(`<tr>${cells.map((c) => `<${tag}>${inline(c)}</${tag}>`).join("")}</tr>`); table++;
       continue;
     }
     closeTable();
 
-    if (line.trim() === "") { html += "\n"; continue; }
-    html += `<p>${inline(line)}</p>\n`;
+    if (/^\s*(---+|\*\*\*+)\s*$/.test(line)) { out.push("<hr>"); continue; }
+    if (line.trim() === "") { out.push(""); continue; }
+    out.push(`<p>${inline(line)}</p>`);
   }
-  closeList(); closeTable();
-  if (inCode) html += "</code></pre>\n";
-
-  return `<!DOCTYPE html>\n<html><head><meta charset="utf-8"></head><body>\n${html}</body></html>\n`;
+  closeAll();
+  if (inCode) out.push("</code></pre>");
+  return `<!DOCTYPE html>\n<html><head><meta charset="utf-8"></head><body>\n${out.join("\n")}\n</body></html>\n`;
 }
 
 async function main() {
   const [inPath, outPath] = process.argv.slice(2);
-  if (!inPath) {
-    console.error("Usage: node render-markdown-to-html.mjs <input.md> [output.html]");
-    process.exit(1);
-  }
-  const fs = await import("node:fs");
-  const md = fs.readFileSync(inPath, "utf8");
-  const html = renderMarkdownToHtml(md);
-  if (outPath) fs.writeFileSync(outPath, html);
-  else console.log(html);
+  if (!inPath) { console.error("Usage: node render-markdown-to-html.mjs <input.md> [output.html]"); process.exit(1); }
+  try {
+    const fs = await import("node:fs");
+    const html = renderMarkdownToHtml(fs.readFileSync(inPath, "utf8"));
+    if (outPath) fs.writeFileSync(outPath, html); else process.stdout.write(html);
+  } catch (err) { console.error(`render-markdown-to-html: ${err.message}`); process.exit(1); }
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  main();
-}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();