@plebeiantech/lat.md 0.12.3-fork.10 → 0.12.3-fork.12

package/dist/src/fork/upstream-drift.js

@@ -63,7 +63,7 @@ export function fetchUpstream(repo, url, ref) {
         throw new Error(`fetching ${url} failed: ${result.stderr.trim()}`);
     }
 }
-// @lat: [[fork#Watching the drift]]
+// @lat: [[upstream-guard#The upstream guard#Watching the drift]]
 export function analyzeDrift(opts) {
     const root = repoRoot(opts.repo);
     const head = git(root, ['rev-parse', 'HEAD']).stdout.trim();

package/dist/src/fork/upstream-guard.d.ts

@@ -1,7 +1,7 @@
 export declare const SYNC_POINT_FILE = "fork-upstream-sync-point";
 /**
  * The commit this fork was originally cut from. It is not the guard's
- * baseline — see [[fork#The upstream guard#The sync point]] for why a frozen
+ * baseline — see [[upstream-guard#The upstream guard#The sync point]] for why a frozen
  * one cannot tell the fork's changes from upstream's.
  */
 export declare const ORIGINAL_FORK_POINT = "65d2f5b220853b2b10dca3de18d511f575bc12c7";

package/dist/src/fork/upstream-guard.js

@@ -1,15 +1,15 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
-// @lat: [[fork#The upstream guard]]
+// @lat: [[upstream-guard#The upstream guard]]
 export const SYNC_POINT_FILE = 'fork-upstream-sync-point';
 /**
  * The commit this fork was originally cut from. It is not the guard's
- * baseline — see [[fork#The upstream guard#The sync point]] for why a frozen
+ * baseline — see [[upstream-guard#The upstream guard#The sync point]] for why a frozen
  * one cannot tell the fork's changes from upstream's.
  */
 export const ORIGINAL_FORK_POINT = '65d2f5b220853b2b10dca3de18d511f575bc12c7';
-// @lat: [[fork#The upstream guard#The allowlist]]
+// @lat: [[upstream-guard#The upstream guard#The allowlist]]
 export const ALLOWLIST_FILE = 'fork-upstream-allowlist.tsv';
 export const REASON_PLACEHOLDER = 'TODO';
 const ALLOWLIST_HEADER = [
@@ -188,7 +188,7 @@ export function upstreamPaths(repo, rev, paths) {
     }
     return out;
 }
-// @lat: [[fork#The upstream guard#The sync point]]
+// @lat: [[upstream-guard#The upstream guard#The sync point]]
 export function parseSyncPoint(text) {
     for (const raw of text.split('\n')) {
         const line = raw.replace(/\r$/, '').trim();
@@ -216,7 +216,7 @@ export function isShallow(repo) {
     const result = git(repo, ['rev-parse', '--is-shallow-repository']);
     return result.stdout.trim() === 'true';
 }
-// @lat: [[fork#The upstream guard#Running it in CI]]
+// @lat: [[upstream-guard#The upstream guard#Running it in CI]]
 export function fetchSyncPoint(repo, rev) {
     const result = git(repo, ['fetch', '--no-tags', '--depth=1', 'origin', rev]);
     return result.status === 0 && hasCommit(repo, rev);
@@ -317,7 +317,7 @@ export function runGuard(options) {
         warnings: result.warnings,
     };
 }
-// @lat: [[fork#The upstream guard#The sync point]]
+// @lat: [[upstream-guard#The upstream guard#The sync point]]
 function recordSyncPoint(repo, file, rev) {
     const resolved = git(repo, ['rev-parse', `${rev}^{commit}`]);
     if (resolved.status !== 0) {

package/package.json

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

package/templates/fork/conventions.md

@@ -1,7 +1,7 @@
 # lat.md conventions this project enforces
 
-`lat check` fails on every rule below except the last, which is a reading
-practice no check can see. None of them are style preferences. This block is
+`lat check` fails on the first three rules below. The last two it cannot see,
+and they matter as much. None of the five are style preferences. This block is
 generated and a later `lat init` replaces it — record project guidance in
 `lat.md/`, never here.
 
@@ -95,6 +95,38 @@ covers it, and every section needs at least one sentence saying what it
 verifies and why. `lat check` reports any spec section no test claims, and any
 ref pointing at no section.
 
+## One specialty per document
+
+A document is **small**, **discrete**, and does **not conflict** with any
+other. Those are three demands on the same thing: a reader must be able to
+find the one place a fact is written down, and trust it.
+
+**Small — a document covers one specialty.** Not one topic area; one
+specialty. When a document covers two, it is two documents. Past roughly forty
+sections it has almost certainly become several, and an agent then loads all of
+it to reach one part.
+
+**Discrete — each document covers its own specialty.** Before writing a new
+document, search for the specialty first:
+
+```
+lat search "the thing you are about to document"
+```
+
+An overlap has two honest repairs, and picking neither is what produces the
+third copy. Either the two are one document and belong merged, or the part they
+share is its own document that both link. Deciding they are "mostly different"
+and writing anyway is how the set rots.
+
+**Does not conflict — two documents never say different things about the same
+specialty.** Never restate a fact another document owns. Link to it with
+`[[section]]`. A restatement is a second copy, a second copy drifts, and drift
+is how document B ends up contradicting document A while both look maintained.
+
+The mode rule above is the sharpest available test of "one specialty": a
+document that fails its mode is usually two documents. Split it. Do not soften
+the prose until the check passes.
+
 ## Read sections, not files
 
 `lat search` prints a section id and the exact lines that section occupies.
@@ -113,7 +145,3 @@ asked about.
 
 Use `lat expand` on a prompt carrying `[[refs]]` for the same reason: it
 resolves each ref to a location and a preview rather than to a file.
-
-The authoring half of the same rule: when a document passes roughly forty
-sections, it has usually become several documents. Split it before an agent
-has to load all of it to reach one part.