@plebeiantech/lat.md 0.12.3-fork.8 → 0.13.4-fork.1

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

@@ -16,7 +16,7 @@ Project-specific lat documentation belongs in `lat.md/`. Do not modify this gene
 
 `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
@@ -29,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
 
@@ -60,6 +61,14 @@ This is invalid — "Bad Section" has no leading paragraph.
 
 `lat check` enforces this rule.
 
+## Diagrams
+
+Default to prose. Reserve Mermaid diagrams for concepts involving more than seven interacting subjects (such as components, states, or stages) with complex sequencing, branching, or dependencies that prose alone makes hard to follow.
+
+The subject count alone does not justify a diagram; omit diagrams for simple sequences or relationships that a short paragraph or list explains clearly. A diagram should give users and later agents an overview of the interactions.
+
+Keep each diagram focused on one process, use readable labels, and explain the important decisions in surrounding prose with precise source-symbol links. Prefer a small overview or several focused diagrams over one dense diagram. Use fenced `mermaid` blocks and run `lat check` to validate syntax and readability.
+
 ## Section IDs
 
 Sections are addressed by file path and heading chain:
@@ -69,17 +78,38 @@ 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]]`.
 
+When documenting implemented behavior, prefer the narrowest relevant source-symbol link over a whole-file link. Use whole-file or directory links when discussing the module or resource as a whole, or when no supported symbol represents the target. If prose names a symbol, link that symbol directly.
+
 ### 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:
@@ -93,6 +123,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
@@ -110,7 +142,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.
 
@@ -169,7 +201,7 @@ Currently the only supported field is `require-code-mention` for test spec enfor
 ## 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-coverage.d.ts

@@ -1,2 +0,0 @@
-import type { CheckError } from './check.js';
-export declare function checkCoverage(latticeDir: string, projectRoot?: string): Promise<CheckError[]>;

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

@@ -1,71 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { relative } from 'node:path';
-import { scanCodeRefs } from '../code-refs.js';
-import { listLatticeFiles } from '../lattice.js';
-import { indexNameFor } from './check-mode.js';
-import { toPosix } from '../walk.js';
-import { basename, dirname } from 'node:path';
-/**
- * Fail a `lat.md/` tree that has documents and no `@lat:` ref pointing into it
- * from anywhere in the codebase.
- *
- * `require-code-mention` was the only thing asking for refs, and it is opt-in
- * frontmatter: an agent setting up a tree can simply not write it, and every
- * check still passes. One did. Its reasons were both ordinary — it read a list
- * of example comment markers as an exclusive language list and concluded its
- * language was unsupported, and it was optimising for a green check rather
- * than a correct one, so the option that could not fail was the one it took.
- *
- * A graph nothing points at cannot be reached from the code, which is the only
- * reason it exists. So the floor is one ref, and the message says where to put
- * the first one.
- *
- * Deliberately a floor and not a coverage ratio. Half this repository's own
- * documents have no incoming ref and should not have one — a per-document rule
- * would have to be either wrong here or watered down everywhere.
- */
-/** Nothing to anchor: a tree of pure navigation, or a project with no code. */
-function isIndex(latticeDir, file) {
-    const holder = basename(dirname(file));
-    return (basename(file) ===
-        indexNameFor(holder === '' ? basename(latticeDir) : holder));
-}
-export async function checkCoverage(latticeDir, projectRoot = dirname(latticeDir)) {
-    const files = await listLatticeFiles(latticeDir);
-    const documents = files.filter((f) => !isIndex(latticeDir, f));
-    if (documents.length === 0)
-        return [];
-    const scan = await scanCodeRefs(projectRoot);
-    if (scan.files.length === 0)
-        return [];
-    if (scan.refs.length > 0)
-        return [];
-    const rootIndexPath = `${latticeDir}/${indexNameFor(basename(latticeDir))}`;
-    const rootIndexRel = toPosix(relative(process.cwd(), rootIndexPath));
-    // Quote the ref the reader should actually paste. A generic placeholder gets
-    // pasted verbatim and then fails `lat check code-refs`, which turns one
-    // error into two.
-    const stem = basename(latticeDir).replace(/\.md$/, '');
-    let anchor = `${stem}#Your Project`;
-    try {
-        const heading = (await readFile(rootIndexPath, 'utf-8')).match(/^#\s+(.+)$/m);
-        if (heading)
-            anchor = `${stem}#${heading[1].trim()}`;
-    }
-    catch {
-        // No root index, or unreadable — the placeholder still names the shape.
-    }
-    return [
-        {
-            file: rootIndexRel,
-            line: 1,
-            target: toPosix(relative(projectRoot, latticeDir)),
-            message: `${documents.length} document(s) here and no \`@lat:\` code ref anywhere in the project — nothing in the codebase can reach this graph.\n` +
-                '    Start at the application entrypoint (config/application.rb, src/index.ts, main.go, manage.py) and point it at the root index:\n' +
-                `        # @lat: [[${anchor}]]\n` +
-                '    Then add one ref per section that source code implements, at that code.\n' +
-                '    The marker is a comment syntax, not a language allowlist: `//` for C-family, `#` for Ruby, Python, shell, Elixir and the rest. The scan is textual and reads every non-markdown file.\n' +
-                '    An `@lat:` line is a machine directive, like a magic comment or a linter pragma. A project convention that minimises comments does not reach it.',
-        },
-    ];
-}

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,21 +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>;
-/**
- * The index file a directory is required to carry, e.g. `lat.md` for the root
- * and `reference.md` for `reference/`. An index is navigation rather than
- * content, so the `require-mode` gate below never asks one to declare a mode.
- */
-export declare function indexNameFor(dirName: string): string;
-export type CheckModeOptions = {
-    /**
-     * Enforce as if the root index said this, whatever it actually says. Used to
-     * price adoption — running once each way and taking the difference is what
-     * the offer in `lat init` reports, and it keeps that number defined by this
-     * checker rather than by a second copy of its rules.
-     */
-    requireMode?: boolean;
-};
-export declare function checkMode(latticeDir: string, projectRoot?: string, options?: CheckModeOptions): Promise<CheckError[]>;