@plebeiantech/lat.md 0.12.3-fork.11 → 0.12.3-fork.13

package/dist/src/cli/check-mode.js

@@ -95,12 +95,40 @@ function inlineTextOf(node) {
     })
         .join('');
 }
+/**
+ * A GFM table that the parser handed back as a paragraph.
+ *
+ * `src/parser.ts` runs remark without `remark-gfm`, so a pipe table is never a
+ * `table` node — its rows arrive as one paragraph and every reference document
+ * containing a table failed with "this is a second paragraph", while the error
+ * text told the author to use a table. Adding the plugin would mean editing an
+ * upstream file and changing what `remarkStringify` emits for the whole tool,
+ * which `tests/roundtrip` pins; recognising the shape here costs nothing
+ * outside this check.
+ *
+ * The signature is a delimiter row — `| --- | :--: |` — under a line that opens
+ * a row. Both are required, because a delimiter row is what separates a table
+ * from prose that merely contains pipes.
+ */
+function isPipeTable(node, lines) {
+    const start = node.position?.start.line;
+    const end = node.position?.end.line;
+    if (!start || !end || end - start < 1)
+        return false;
+    const rows = lines.slice(start - 1, end);
+    return rows.some((row, i) => i > 0 &&
+        /^\s*\|?(?:\s*:?-{3,}:?\s*\|)+\s*:?-{3,}:?\s*\|?\s*$/.test(row) &&
+        rows[i - 1].trimStart().startsWith('|'));
+}
 /**
  * Extra top-level paragraphs found under headings, beyond the one
  * `checkSections` already permits as the leading summary. A paragraph
  * before the first heading is the document lead, not narrative prose.
+ *
+ * A pipe table is not prose and never counts, in either position: it is
+ * neither the leading summary a reference is allowed nor an offender.
  */
-function extraParagraphs(tree) {
+function extraParagraphs(tree, lines) {
     const offenders = [];
     let currentHeading = null;
     let seenParagraphUnderHeading = false;
@@ -111,6 +139,8 @@ function extraParagraphs(tree) {
             continue;
         }
         if (node.type === 'paragraph') {
+            if (isPipeTable(node, lines))
+                continue;
             if (currentHeading === null) {
                 // Document lead paragraph before any heading — allowed.
                 continue;
@@ -329,7 +359,7 @@ export async function checkMode(latticeDir, projectRoot = dirname(latticeDir), o
             continue;
         }
         if (mode === 'reference') {
-            for (const offender of extraParagraphs(tree)) {
+            for (const offender of extraParagraphs(tree, content.split('\n'))) {
                 errors.push({
                     file: relPath,
                     line: offender.line,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plebeiantech/lat.md",
-  "version": "0.12.3-fork.11",
+  "version": "0.12.3-fork.13",
   "description": "A knowledge graph for your codebase, written in markdown",
   "type": "module",
   "license": "MIT",

package/templates/fork/conventions.md

@@ -17,15 +17,41 @@ enforces one shape rule for each:
 | `lat.md/reference/` | lookup facts: fields, states, limits, names | no narrative prose — no second paragraph under a heading |
 | `lat.md/explanation/` | why the design is what it is | no imperative commands |
 
-Do not write documents at the top of `lat.md/`. The root index is the only file
-that belongs there. When it carries `require-mode: true`, a document with no
-declared mode and no mode directory is a `lat check` error.
+A document is classified either by the directory it sits in, or by declaring
+the mode in its own frontmatter:
+
+```markdown
+---
+lat:
+  mode: explanation
+---
+```
+
+Both are enforced identically — `lat check mode` applies the shape rule to any
+document that declares a mode, whether or not the root index carries
+`require-mode: true`. That flag adds a separate rule: a document declaring *no*
+mode, in no mode directory, becomes an error too.
+
+Prefer the directory in a tree you own outright. Prefer the declaration when
+the file cannot move — a document another project maintains, or a tree other
+agents are writing to while you work. Moving costs every reference to the file;
+declaring costs nothing at read time, because frontmatter sits above the first
+heading and outside every section.
 
 **A document that fails its mode is usually two documents.** A file that lists
 the states *and* argues for the design is mixed: the lookup half goes in
 `reference/`, the reasoning half in `explanation/`, and each links the other.
 Filing it under one mode and softening the prose until the check passes is the
-wrong repair. So is leaving it at the top level where no check can see it.
+wrong repair.
+
+Classifying a mixed document does not make it pass. Narrative prose put under
+`reference/` fails on contact, because a reference may not carry a second
+paragraph under a heading — so a move is not a way to adopt the rule cheaply.
+Split first, then place. And `explanation` is not the safe default: it bans
+only imperative commands, so nearly any prose passes it. Declaring it is a
+claim about the document, not somewhere to put whatever is left over. A
+document you cannot honestly classify is better left undeclared than
+mislabelled.
 
 Classify before writing, not after. If a `diataxis` skill is available, use it.