@plebeiantech/lat.md 0.12.3-fork.2 → 0.12.3-fork.21

package/templates/fork/conventions.md

@@ -0,0 +1,173 @@
+# lat.md conventions this project enforces
+
+`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.
+
+## Every document goes in a Diátaxis mode directory
+
+A document belongs in exactly one of four subdirectories, and `lat check mode`
+enforces one shape rule for each:
+
+| Directory | Holds | Shape rule |
+| --- | --- | --- |
+| `lat.md/tutorials/` | a guided first pass for someone new | an ordered list of steps, and a stated outcome |
+| `lat.md/how-to/` | a recipe for a task that recurs | an ordered list of steps |
+| `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 |
+
+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.
+
+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.
+
+## Every project has at least one `@lat:` code ref
+
+`lat check` fails a tree that has documents and no `@lat:` ref anywhere in the
+codebase. A graph nothing points at cannot be reached from the code, which is
+the only reason it exists.
+
+Start at the application entrypoint — `config/application.rb`, `src/index.ts`,
+`main.go`, `manage.py`, whatever a new reader opens first — and point it at the
+root index:
+
+```ruby
+# @lat: [[lat#Acme]]
+module Acme
+```
+
+Then one ref per section that source code actually implements, placed at that
+code. Never in a block at the top of a file.
+
+### An `@lat:` pointer is exempt from this project's comment conventions
+
+A repository that minimises, budgets, or forbids comments is right about prose
+comments and does not reach this one. An `@lat:` line is a machine directive,
+in the same class as `# frozen_string_literal:` or `// eslint-disable`. It
+carries no rationale, asserts nothing a reader could dispute, and cannot rot
+quietly — `lat check` fails the moment its target moves or disappears.
+
+Add the ref. Then, if the reasoning that would have been a comment is worth
+keeping, put it in a `lat.md/explanation/` section and let the pointer reach it.
+
+### The marker is a comment syntax, not a language allowlist
+
+`//` for C-family languages; `#` for Ruby, Python, shell, Elixir, YAML, Make,
+and everything else that comments with `#`. The scan is textual and walks every
+non-markdown file in the project, so every language works.
+
+Any list of example languages you find is a list of examples. Never conclude a
+language is unsupported because it is absent from one. `lat check` prints what
+it scanned:
+
+```
+Scanned 41 .md, 622 .rb, 118 .tsx in 1.2s
+```
+
+Read that line rather than guessing, and if you are still unsure, add one ref
+and run the check. It costs one command.
+
+(The tree-sitter grammars limit only `[[src/file.ts#symbol]]` wiki links, which
+resolve a symbol inside source. `@lat:` refs point the other way and have no
+such limit.)
+
+## Test specs are wired to their tests
+
+A document describing tests declares it in frontmatter:
+
+```markdown
+---
+lat:
+  require-code-mention: true
+---
+```
+
+Every leaf section then needs exactly one `@lat:` comment at the test that
+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.
+Resolve it with `lat section`, or read only that line range. Opening the whole
+file is the reflex to break, and it is the expensive one:
+
+```
+lat search "how does backend selection work"
+lat section "cli#CLI#search#Backend selection"
+```
+
+not a `read` of `lat.md/cli.md`. Measured on lat.md's own graph, the section
+costs 4 KB against the file's 44 KB — eleven times the context for the same
+answer, and the answer arrives buried in forty-one sections that were not
+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.

package/templates/opencode-plugin.ts

@@ -1,11 +1,11 @@
 import { type Plugin, tool } from "@opencode-ai/plugin"
-import { execSync } from "child_process"
+import { execSync, execFileSync } from "child_process"
 
-/** Absolute path to the lat binary, injected by `lat init`. */
-const LAT = "__LAT_BIN__"
+/** Executable and prefix arguments, injected by `lat init`. */
+const LAT = __LAT_INVOCATION__
 
 function run(args: string[]): string {
-  return execSync(`${LAT} ${args.join(" ")}`, {
+  return execFileSync(LAT.command, [...LAT.args, ...args], {
     cwd: process.cwd(),
     encoding: "utf-8",
     timeout: 30_000,
@@ -33,7 +33,7 @@ export const LatPlugin: Plugin = async (ctx) => {
           ),
         },
         async execute(args) {
-          const cliArgs = ["search", JSON.stringify(args.query)]
+          const cliArgs = ["search", args.query]
           if (args.limit) cliArgs.push("--limit", String(args.limit))
           const output = tryRun(cliArgs)
           return output || "No results found."
@@ -49,7 +49,7 @@ export const LatPlugin: Plugin = async (ctx) => {
           ),
         },
         async execute(args) {
-          const output = tryRun(["section", JSON.stringify(args.query)])
+          const output = tryRun(["section", args.query])
           return output || "Section not found."
         },
       }),
@@ -61,7 +61,7 @@ export const LatPlugin: Plugin = async (ctx) => {
           query: tool.schema.string("Section name to locate"),
         },
         async execute(args) {
-          const output = tryRun(["locate", JSON.stringify(args.query)])
+          const output = tryRun(["locate", args.query])
           return output || "No sections matching query."
         },
       }),
@@ -87,7 +87,7 @@ export const LatPlugin: Plugin = async (ctx) => {
           text: tool.schema.string("Text containing [[refs]] to expand"),
         },
         async execute(args) {
-          const output = tryRun(["expand", JSON.stringify(args.text)])
+          const output = tryRun(["expand", args.text])
           return output || args.text
         },
       }),
@@ -101,7 +101,7 @@ export const LatPlugin: Plugin = async (ctx) => {
           ),
         },
         async execute(args) {
-          const output = tryRun(["refs", JSON.stringify(args.query)])
+          const output = tryRun(["refs", args.query])
           return output || "No references found."
         },
       }),

package/templates/pi-extension.ts

@@ -30,12 +30,12 @@ function collapsibleResult(
   );
 }
 
-/** Absolute path to the lat binary, injected by `lat init`. */
-const LAT = "__LAT_BIN__";
+/** Executable and prefix arguments, injected by `lat init`. */
+const LAT = __LAT_INVOCATION__;
 
 function run(args: string[], cwd?: string): string {
-  const { execSync } = require("child_process") as typeof import("child_process");
-  return execSync(`${LAT} ${args.join(" ")}`, {
+  const { execFileSync } = require("child_process") as typeof import('child_process');
+  return execFileSync(LAT.command, [...LAT.args, ...args], {
     cwd: cwd ?? process.cwd(),
     encoding: "utf-8",
     timeout: 30_000,
@@ -69,7 +69,7 @@ export default function (pi: ExtensionAPI) {
       ),
     }),
     async execute(_id, params) {
-      const args = ["search", JSON.stringify(params.query)];
+      const args = ["search", params.query];
       if (params.limit) args.push("--limit", String(params.limit));
       const output = tryRun(args);
       return {
@@ -99,7 +99,7 @@ export default function (pi: ExtensionAPI) {
       }),
     }),
     async execute(_id, params) {
-      const output = tryRun(["section", JSON.stringify(params.query)]);
+      const output = tryRun(["section", params.query]);
       return {
         content: [
           { type: "text", text: output || "Section not found." },
@@ -126,7 +126,7 @@ export default function (pi: ExtensionAPI) {
       query: Type.String({ description: "Section name to locate" }),
     }),
     async execute(_id, params) {
-      const output = tryRun(["locate", JSON.stringify(params.query)]);
+      const output = tryRun(["locate", params.query]);
       return {
         content: [
           { type: "text", text: output || "No sections matching query." },
@@ -179,7 +179,7 @@ export default function (pi: ExtensionAPI) {
       text: Type.String({ description: "Text containing [[refs]] to expand" }),
     }),
     async execute(_id, params) {
-      const output = tryRun(["expand", JSON.stringify(params.text)]);
+      const output = tryRun(["expand", params.text]);
       return {
         content: [{ type: "text", text: output || params.text }],
       };
@@ -205,7 +205,7 @@ export default function (pi: ExtensionAPI) {
       }),
     }),
     async execute(_id, params) {
-      const output = tryRun(["refs", JSON.stringify(params.query)]);
+      const output = tryRun(["refs", params.query]);
       return {
         content: [{ type: "text", text: output || "No references found." }],
       };
@@ -276,7 +276,7 @@ export default function (pi: ExtensionAPI) {
       "Use `lat_section` to read the full content of relevant matches.",
       "Do not read files, write code, or run commands until you have searched.",
       "",
-      "Remember: `lat.md/` must stay in sync with meaningful codebase state. If you change behavior, architecture, tests, or planned work, update the relevant current-state sections and run `lat_check` before finishing. Do not use `lat.md/` as a journal/changelog or add notes for insignificant details.",
+      "Remember: `lat.md/` must stay in sync with meaningful codebase state. If you change implemented behavior, architecture, or tests, update the relevant current-state sections and run `lat_check` before finishing. Plans may be drafted in `lat.md/` alongside implementation, with the intent that by commit time they describe what was implemented. Otherwise, keep proposals, hypothetical designs, and future work outside `lat.md/` unless the user explicitly requests them there. Do not use `lat.md/` as a journal/changelog or add notes for insignificant details.",
     ].join("\n");
 
     return {
@@ -307,7 +307,7 @@ export default function (pi: ExtensionAPI) {
     let needsSync = false;
     let codeLines = 0;
     try {
-      const { execSync } = require("child_process") as typeof import("child_process");
+      const { execSync } = require("child_process") as typeof import('child_process');
       const numstat = execSync("git diff HEAD --numstat", {
         encoding: "utf-8",
         cwd: process.cwd(),

package/templates/skill/SKILL.md

@@ -10,11 +10,13 @@ description: >-
 
 This skill covers the syntax, structure rules, and conventions for writing `lat.md/` files. Load it whenever you need to create or edit sections in the `lat.md/` directory.
 
+Project-specific lat documentation belongs in `lat.md/`. Do not modify this generated skill or a generated `AGENTS.md` to record project guidance: both are owned by lat tooling and may be replaced by a later `lat init`.
+
 ## What belongs in lat.md
 
 `lat.md/` files describe **what** the project does and **why** — domain concepts, key design decisions, business logic, and test specifications. They do NOT duplicate source code. Think of each section as an anchor that source code references back to.
 
-Treat `lat.md/` as a focused snapshot of the current state of affairs or planned features. Do not use it as a journal or changelog, and do not grow it just to record insignificant implementation details.
+Treat `lat.md/` as a focused snapshot of the current implemented state. Plans may be drafted in `lat.md/` alongside implementation, with the intent that by commit time they describe what was implemented. Otherwise, keep proposals, hypothetical designs, and future work outside `lat.md/` unless the user explicitly requests them there. A planning-only task does not require a knowledge-graph update. Do not use it as a journal or changelog, and do not grow it just to record insignificant implementation details.
 
 Good candidates for sections:
 - Architecture decisions and their rationale
@@ -27,6 +29,7 @@ Bad candidates:
 - Step-by-step code walkthroughs (the code itself is the walkthrough)
 - Auto-generated API docs (use tools for that)
 - Journal/changelog entries for each change
+- Proposals, planned features, hypothetical designs, or promises of future behavior, unless explicitly requested by the user or drafted alongside implementation to describe implemented behavior by commit time
 - Temporary notes or TODOs
 - Insignificant implementation details that do not change the current-state model
 
@@ -67,17 +70,36 @@ Sections are addressed by file path and heading chain:
 
 Examples: `lat.md/tests/search#RAG Replay Tests`, `cli#init`, `parser#Wiki Links`.
 
+Configured external sources use `[[handle:path/to/file.md#Heading]]` for
+Markdown headings and `[[handle:path/to/file.ts#symbol]]` for supported code
+symbols. Run `lat external show <handle>` before cloning an external source;
+its output includes the pinned commit and safe checkout suggestions.
+
 ## Wiki links
 
 Cross-reference other sections or source code with `[[target]]` or `[[target|alias]]`.
 
 ### Section links
 
+Section links connect related concepts while keeping their stable graph identities explicit.
+
 ```markdown
 See [[cli#init]] for setup details.
 The parser validates [[parser#Wiki Links|wiki link syntax]].
 ```
 
+### Repository path links
+
+Reference any existing file or directory beneath the project root without a fragment:
+
+```markdown
+[[schema.sql]]
+[[CHANGELOG]]
+[[src/components]]
+```
+
+Unsupported formats validate as references but cannot be opened by Lat. A `#fragment` requires a `lat.md/` section or a supported source file.
+
 ### Source code links
 
 Reference functions, classes, constants, and methods in source files:
@@ -91,6 +113,8 @@ Reference functions, classes, constants, and methods in source files:
 [[src/app.h#Greeter]]                   — C struct
 ```
 
+When prose names an implementation symbol or a behavior governed by one, link the symbol instead of using a bare code span or copying its literal value. Prefer `[[src/config.ts#DEFAULT_TIMEOUT]]` (or `[[src/config.ts#DEFAULT_TIMEOUT|the default timeout]]`) over a bare identifier or copied value. Keep the behavioral explanation in prose; the link makes its implementation binding navigable and validated.
+
 `lat check` validates that all targets exist.
 
 ## Code refs
@@ -108,7 +132,7 @@ def init():
     ...
 ```
 
-Supported comment styles: `//` (JS/TS/Rust/Go/C) and `#` (Python).
+Supported comment styles: `//` (JS/TS/Rust/Go/C/PHP) and `#` (Python/PHP).
 
 Place one `@lat:` comment per section, at the relevant code — not at the top of the file.
 
@@ -162,25 +186,12 @@ lat:
 ---
 ```
 
-Supported fields: `require-code-mention` for test spec enforcement, and `mode` for Diátaxis mode declaration.
-
-## Diátaxis modes
-
-Documents in `tutorials/`, `how-to/`, `reference/`, or `explanation/` under `lat.md/` are checked against their Diátaxis mode. Declare it with nested frontmatter:
-
-```yaml
----
-lat:
-  mode: reference
----
-```
-
-If the document is in one of the four mode directories, the declared mode must match that directory. Each mode enforces one shape rule: tutorials need an ordered list of steps and a stated outcome; how-to guides need an ordered list of steps; reference docs must not contain narrative prose (no second paragraph under a heading); explanations must not give imperative commands. `lat check mode` validates this.
+Currently the only supported field is `require-code-mention` for test spec enforcement.
 
 ## Validation
 
 Always run `lat check` after editing `lat.md/` files. It validates:
-- All wiki links point to existing sections or source code symbols
+- All wiki links point to existing sections, repository paths, or source code symbols
 - All relative markdown links point to existing files
 - Full and collapsed reference-style links have definitions
 - All `@lat:` code refs point to existing sections

package/dist/src/cli/check-frontmatter.d.ts

@@ -1,12 +0,0 @@
-import type { CheckError } from './check.js';
-/**
- * Report frontmatter that parses to nothing useful, or that puts a lat field
- * somewhere the parser will not look.
- *
- * Both failures are quiet by nature, and both fail OPEN. A misplaced or
- * unparseable `require-code-mention` turns a validation off, and `lat check`
- * then reports success on a file whose leaf sections are no longer required to
- * carry `@lat:` coverage. Nothing else in the output says the rule stopped
- * applying, which is precisely why it has to be said here.
- */
-export declare function checkFrontmatter(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;

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

@@ -1,44 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { dirname, relative } from 'node:path';
-import { listLatticeFiles, parseFrontmatter } from '../lattice.js';
-import { toPosix } from '../walk.js';
-/**
- * Report frontmatter that parses to nothing useful, or that puts a lat field
- * somewhere the parser will not look.
- *
- * Both failures are quiet by nature, and both fail OPEN. A misplaced or
- * unparseable `require-code-mention` turns a validation off, and `lat check`
- * then reports success on a file whose leaf sections are no longer required to
- * carry `@lat:` coverage. Nothing else in the output says the rule stopped
- * applying, which is precisely why it has to be said here.
- */
-export async function checkFrontmatter(latticeDir, projectRoot = dirname(latticeDir)) {
-    const files = await listLatticeFiles(latticeDir);
-    const errors = [];
-    for (const file of files) {
-        const content = await readFile(file, 'utf-8');
-        const problems = parseFrontmatter(content).problems;
-        if (!problems)
-            continue;
-        const relPath = relative(process.cwd(), file);
-        const target = toPosix(relative(projectRoot, file)).replace(/\.md$/, '');
-        for (const problem of problems) {
-            if (problem.kind === 'root-level-field') {
-                errors.push({
-                    file: relPath,
-                    line: 1,
-                    target,
-                    message: `frontmatter sets "${problem.field}" at the document root, where it is ignored — nest it under "lat:" instead:\n    ---\n    lat:\n      ${problem.field}: ...\n    ---`,
-                });
-                continue;
-            }
-            errors.push({
-                file: relPath,
-                line: 1,
-                target,
-                message: `frontmatter is not valid YAML (${problem.message}) — every lat field in this document is being ignored, including any that turn a check on`,
-            });
-        }
-    }
-    return errors;
-}

package/dist/src/cli/check-mode.d.ts

@@ -1,6 +0,0 @@
-import type { CheckError } from './check.js';
-export declare const DIATAXIS_MODES: readonly ["tutorial", "how-to", "reference", "explanation"];
-export type DiataxisMode = (typeof DIATAXIS_MODES)[number];
-/** Directory below lat.md/ that holds each mode. */
-export declare const MODE_DIRS: Record<DiataxisMode, string>;
-export declare function checkMode(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;