Add scientific reference formatting workbench

scientific-reference-workbench/README.md

@@ -0,0 +1,35 @@
+# Scientific Reference Workbench
+
+Dependency-free citation and cross-reference checks for a real-time scientific editor.
+
+This module focuses on the publication-formatting layer of issue #12. It turns manuscript sections, Markdown text, equation blocks, figures, tables, and bibliography entries into a deterministic export-readiness packet.
+
+## Run
+
+```bash
+npm run check
+npm test
+npm run demo
+```
+
+## Demo Output
+
+```text
+Manuscript: Protocol-Guided Perturbation Screening
+Status: format-review-needed
+Citations discovered: 3
+Missing citations: missing2026
+Cross references: 3
+Formatting tasks: 1
+Top action: Add bibliography entry for @missing2026 or remove the citation.
+```
+
+## Files
+
+- `src/reference-workbench.js` extracts citations and cross references, builds numbering, formats blocks, validates style requirements, emits reviewer tasks, and signs the packet with a stable digest.
+- `data/sample-manuscript.json` contains synthetic manuscript sections, bibliography entries, equation/figure/table labels, and references.
+- `test/reference-workbench.test.js` verifies citation coverage, label numbering, formatted text, export blocking, and resolved-export behavior.
+- `docs/requirement-map.md` maps the slice to issue #12.
+- `docs/demo.svg` and `docs/demo.mp4` provide a short visual artifact for review.
+
+No external reference-manager credential, private manuscript, or third-party API is used.

scientific-reference-workbench/data/sample-manuscript.json

@@ -0,0 +1,93 @@
+{
+  "manuscriptId": "collab-editor-reference-demo",
+  "title": "Protocol-Guided Perturbation Screening",
+  "style": {
+    "name": "SCIBASE short article",
+    "citationMode": "numeric",
+    "requiredSections": ["abstract", "methods", "results", "data-availability"]
+  },
+  "sections": [
+    {
+      "id": "abstract",
+      "heading": "Abstract",
+      "blocks": [
+        {
+          "id": "abs-1",
+          "type": "markdown",
+          "text": "We combine registered protocols with live analysis notebooks [@nguyen2025] and summarize the reproducibility gates in {{fig:workflow}}."
+        }
+      ]
+    },
+    {
+      "id": "methods",
+      "heading": "Methods",
+      "blocks": [
+        {
+          "id": "meth-1",
+          "type": "markdown",
+          "text": "The loss function follows {{eq:weighted-loss}} and the metadata schema extends prior collaborative notebook work [@park2024; @missing2026]."
+        },
+        {
+          "id": "meth-eq-1",
+          "type": "equation",
+          "label": "eq:weighted-loss",
+          "text": "L = alpha * error + beta * drift"
+        }
+      ]
+    },
+    {
+      "id": "results",
+      "heading": "Results",
+      "blocks": [
+        {
+          "id": "res-1",
+          "type": "markdown",
+          "text": "A blinded reviewer can inspect {{tbl:quality-gates}} before accepting a release candidate."
+        },
+        {
+          "id": "res-fig-1",
+          "type": "figure",
+          "label": "fig:workflow",
+          "caption": "Reference-aware collaboration workflow."
+        },
+        {
+          "id": "res-table-1",
+          "type": "table",
+          "label": "tbl:quality-gates",
+          "caption": "Formatting gates for reviewer-ready manuscripts."
+        }
+      ]
+    },
+    {
+      "id": "data-availability",
+      "heading": "Data Availability",
+      "blocks": [
+        {
+          "id": "data-1",
+          "type": "markdown",
+          "text": "Synthetic editor traces and bibliography fixtures are included with this module."
+        }
+      ]
+    }
+  ],
+  "bibliography": [
+    {
+      "key": "nguyen2025",
+      "title": "Live Scientific Editing with Structured Protocols",
+      "authors": ["Nguyen", "Sato"],
+      "year": 2025
+    },
+    {
+      "key": "park2024",
+      "title": "Notebook Review Pipelines for Collaborative Research",
+      "authors": ["Park"],
+      "year": 2024
+    },
+    {
+      "key": "unused2023",
+      "title": "Unused Background Citation",
+      "authors": ["Mendez"],
+      "year": 2023
+    }
+  ]
+}

scientific-reference-workbench/docs/requirement-map.md

@@ -0,0 +1,31 @@
+# Requirement Map
+
+This module contributes a focused rich-formatting slice for issue #12, "Real-time collaborative research editor & interface."
+
+| Issue area | Covered by this module |
+| --- | --- |
+| Markdown and LaTeX support | Tracks equation blocks and deterministic equation numbering |
+| Cross-referencing figures, tables, and citations | Extracts citation keys and `{{label}}` references, validates coverage, and renders deterministic display labels |
+| Reference manager integration | Verifies bibliography coverage for citation keys and surfaces unused bibliography entries |
+| Publication-style templates | Checks required publication sections and blocks export when style requirements fail |
+| Inline reviewer workflow | Emits owner-assigned formatting tasks for missing citations, missing cross-references, duplicate labels, and missing sections |
+
+## Distinctness
+
+Existing #12 submissions focus on broad collaborative editors, operation replay, governance, offline conflict resolution, and notebook collaboration. This module focuses on the publication-formatting layer that a scientific editor needs before export:
+
+- citation-key extraction from manuscript text
+- bibliography coverage checks
+- figure/table/equation label numbering
+- unresolved cross-reference detection
+- style-specific required-section checks
+- reviewer-ready formatting task output
+
+## Verification
+
+```bash
+cd scientific-reference-workbench
+npm run check
+npm test
+npm run demo
+```

scientific-reference-workbench/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "scientific-reference-workbench",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Dependency-free scientific citation and cross-reference formatting workbench.",
+  "scripts": {
+    "check": "node --check src/reference-workbench.js && node --check scripts/demo.js && node --check test/reference-workbench.test.js",
+    "demo": "node scripts/demo.js",
+    "test": "node test/reference-workbench.test.js"
+  },
+  "keywords": [
+    "scientific-editor",
+    "citations",
+    "cross-references",
+    "publication-formatting"
+  ],
+  "license": "MIT"
+}

scientific-reference-workbench/scripts/demo.js

@@ -0,0 +1,16 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { buildReferenceWorkbench } = require("../src/reference-workbench");
+
+const samplePath = path.join(__dirname, "..", "data", "sample-manuscript.json");
+const manuscript = JSON.parse(fs.readFileSync(samplePath, "utf8"));
+const report = buildReferenceWorkbench(manuscript);
+
+console.log(`Manuscript: ${report.title}`);
+console.log(`Status: ${report.dashboard.status}`);
+console.log(`Citations discovered: ${report.citations.uniqueKeys.length}`);
+console.log(`Missing citations: ${report.citations.missing.join(", ") || "none"}`);
+console.log(`Cross references: ${report.crossReferences.occurrences.length}`);
+console.log(`Formatting tasks: ${report.tasks.length}`);
+console.log(`Top action: ${report.dashboard.topAction}`);
+console.log(`Digest: ${report.digest}`);