@markstanden/opencode-docs-plugin 0.8.0 → 0.10.0

package/CONVENTION.md

@@ -36,6 +36,23 @@ are RepoContext. A repo adds other local roots in
 `.opencode/docs-lakes.json`; a personal or managed base file lists the
 machine, global and wiki lakes.
 
+Lakes are named, and several per class are supported. A root nested inside
+another lake's root belongs to the **narrowest enclosing lake**: the outer lake
+skips it, search returns the inner lake's entry, a bare `read` resolves there,
+and `add` writes to the deepest writable knowledge lake. Nesting is decided on
+real paths, so reaching one root through a symlink cannot defeat containment.
+Two lakes that do not nest holding the same relative path stay a refusal —
+pass `lake`. Near-twin checks apply inside one lake and never pair across the
+nesting boundary.
+
+Lake notes — a missing root, or a root outside version control — are computed
+per call, not captured at startup: create, remove or version a root and the
+next `check`, `search` and help reflect it without a restart.
+
+Validation follows writability: `check` validates only writable knowledge lakes.
+A read-only lake is indexed for search and never validated, and the report names
+it as skipped.
+
 The excluded areas — never scanned, never validated in a knowledge lake — are
 `plans/` (scratch, gitignored, deleted when the work lands), `requirements/`
 and `wiki/` (vendored mirrors). The wiki profile has no such exclusions; only

package/README.md

@@ -169,6 +169,12 @@ Lake entries:
 | `name`     | Lower-case dashes; defaults to the root folder name. `instructions` is reserved.                 |
 | `writable` | Defaults true for knowledge classes, fixed false for `wiki`.                                     |
 
+Validation follows writability: `check` validates a writable knowledge lake
+only. A read-only knowledge lake, and every `wiki` lake, is indexed for search
+and never validated — the plugin cannot write there, so findings could not be
+fixed through it. Each skipped lake is named in the report, so "no findings" is
+never mistaken for compliance.
+
 Lake paths never follow symlinks: a symlinked doc is skipped by search and
 `check`, refused by `read`, and refused by `add`. The configured `root` itself
 may be a symlink; the content beneath it must be real.
@@ -181,10 +187,17 @@ writable repo lake may sit inside a larger read-only wiki lake, and search,
 only decides its own profile and defaults; `repo`, `machine`, `global` and
 `wiki` all skip a nested root the same way.
 
-The skip compares the configured roots as written, so reach the tree the same
-way from both declarations. If one lake names the real directory and the other
-reaches it through a symlink, junction or mapped drive, the two paths never
-match and the nested doc is indexed twice.
+The skip is decided on real paths: every configured root is resolved through
+symlinks, junctions and mapped drives before the comparison, so the two
+declarations may reach the tree by different routes and the nested doc is
+still indexed once.
+
+A doc belongs to the **narrowest enclosing lake**. With nested roots, `search`
+returns the inner lake's entry and a bare `read` resolves to it; `add` writes
+to the deepest writable knowledge lake, so an outer read-only wrapper never
+hijacks the write. Two lakes that do not nest holding the same relative path
+stay a refusal — pass `lake`. Near-twin checks apply inside one lake and never
+pair across the nesting boundary.
 
 ```jsonc
 {
@@ -220,6 +233,10 @@ it `— missing`, and `add` refuses with the path rather than bootstrapping a
 tree. Create the directory deliberately. Area folders beneath an existing root
 are still created on write.
 
+Root and git notes are computed per call, not captured at startup: a root that
+appears, disappears or gains a git checkout is reflected by the next `check`,
+`search` and help without a restart.
+
 `maxDocLines` (default 200, `0` disables) is a **soft** note on a long doc, not a
 refusal. `perLakeQuota` (default 3, `0` disables) is the per-source result
 reservation.
@@ -235,12 +252,15 @@ wiki's owners decide.
 
 ## Check
 
-`check` validates the knowledge lakes: required front-matter, an H1, at least
-one claim section (`Facts`, `Inferred`, `Tested`, `Failed approaches`,
+`check` validates the **writable** knowledge lakes: required front-matter, an H1,
+at least one claim section (`Facts`, `Inferred`, `Tested`, `Failed approaches`,
 `Open questions`), no hand-maintained `Date`, a distinctive H1+Keywords
-identity, same-area near-twins, and broken relative `.md` links. Obsolete
-`Status`/`Supersedes` fields, long docs, and unversioned or missing roots are
-**notes**, not findings. An empty findings list means compliant.
+identity, same-area near-twins, and broken relative `.md` links. Read-only
+knowledge lakes and wiki lakes are searched in full but never validated; the
+report names each skipped lake and why. Obsolete `Status`/`Supersedes` fields,
+long docs, and unversioned or missing roots are **notes**, not findings. An
+empty findings list means compliant. A very large report is capped with an
+`and N more lines not shown` tail; narrow it with `lake`.
 
 There is no lifecycle field. A doc is current or deleted; git is the archive.
 Correct a wrong doc by replacing it in place. A failed attempt is valid

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@markstanden/opencode-docs-plugin",
-    "version": "0.8.0",
+    "version": "0.10.0",
     "type": "module",
     "description": "OpenCode V2 plugin: a `docs` tool and `/docs` command over configurable knowledge lakes (repo, machine, global and read-only wiki), nested README.md search, and the writing convention they share",
     "repository": {

package/src/SKILL.md

@@ -64,12 +64,15 @@ variable, never the value — and no personal data in GlobalContext or Wiki.
 
 ## Check it
 
-`check` audits the lakes: front-matter, an `H1`, a claim section, no
-hand-maintained `Date`, a distinctive identity, near-twins and broken relative
-links. Obsolete fields, long docs and missing roots are **notes**, not findings;
-wiki lakes are not validated. `add` enforces the structural rules at the write
-boundary; cross-document audits stay with `check`. `maxDocLines` (default 200,
-`0` disables) is a soft size signal, not a refusal.
+`check` audits the **writable** knowledge lakes: front-matter, an `H1`, a claim
+section, no hand-maintained `Date`, a distinctive identity, near-twins and broken
+relative links. Obsolete fields, long docs and missing roots are **notes**, not
+findings. Validation follows writability — read-only lakes, wiki lakes and
+READMEs are not validated, and skipped lakes are named in the report. A very
+large report is capped with an `and N more lines not shown` tail; narrow it with
+`lake`. `add` enforces the structural rules at the write boundary;
+cross-document audits stay with `check`. `maxDocLines` (default 200, `0`
+disables) is a soft size signal, not a refusal.
 
 Run the project's tests and typecheck before proposing a commit, fixing
 failures rather than papering over them. Prepare the commit and **wait for

package/src/index.ts

@@ -126,7 +126,7 @@ export const DOCS_INPUT = Schema.Struct({
     check: Schema.optional(
         Schema.Boolean.annotate({
             description:
-                "Validate every knowledge doc: front-matter, an H1, a claim section, no hand-maintained Date, a distinctive H1+Keywords identity, near-twins, broken relative links, a soft length note. Wiki lakes and READMEs are not validated.",
+                "Validate every knowledge doc: front-matter, an H1, a claim section, no hand-maintained Date, a distinctive H1+Keywords identity, near-twins, broken relative links, a soft length note. Only writable knowledge lakes are validated; read-only lakes, wiki lakes and READMEs are not, and skipped lakes are named.",
         }),
     ),
     read: Schema.optional(
@@ -541,6 +541,13 @@ export const MIN_TERM_LENGTH = 3;
  */
 export const MAX_RESULTS = 10;
 
+/**
+ * The most characters a `check` report returns before it is truncated with an
+ * `and N more` tail. A finding-heavy run once returned 39,871 characters in one
+ * tool result; the cap keeps a report readable. The single knob for the cap.
+ */
+export const MAX_CHECK_CHARS = 8000;
+
 /** Split a raw query into lower-cased, non-empty terms, dropping filler. */
 function termsOf(query: string): string[] {
     const terms = query
@@ -2214,6 +2221,17 @@ export interface LakeSpec {
     writable: boolean;
 }
 
+/**
+ * Whether `check` validates a lake: validation follows writability, because a
+ * lake the plugin cannot write is out of its control. A wiki lake is never
+ * validated. One rule, no per-lake override.
+ * @param lake The configured lake.
+ * @returns True when the lake's docs are validated.
+ */
+function lakeValidated(lake: LakeSpec): boolean {
+    return lake.profile === "knowledge" && lake.writable;
+}
+
 /** A lake with its runtime seams. */
 export interface Lake extends LakeSpec {
     /** Collects this lake's docs. */
@@ -2227,8 +2245,12 @@ export interface Lake extends LakeSpec {
      * existing root; throws when the root is absent rather than creating it.
      */
     write: (path: string, contents: string) => void;
-    /** Environment notes for `check` (missing root, unversioned root). */
-    notes: readonly string[];
+    /**
+     * Legacy seam notes only. Real lakes compute their environment notes at
+     * call time — a root that appears, disappears or gains a git checkout is
+     * re-probed on the next `check`, `search` and help, never captured here.
+     */
+    notes?: readonly string[];
     /** Whether `check` should verify relative links; false for the legacy seam. */
     linkCheck: boolean;
 }
@@ -2314,7 +2336,6 @@ export function createLake(
     };
     return {
         ...spec,
-        notes: unversionedNote(spec.root, spec.name),
         linkCheck: true,
         collect: () =>
             collectDocs(spec.root, (paths) => fallbackDates(spec.root, paths), {
@@ -2346,18 +2367,27 @@ export function createLake(
 
 /**
  * Build every configured lake, each aware of the others so a nested root is
- * collected once.
+ * collected once. Nesting is decided on real paths, so a symlinked root cannot
+ * defeat containment: the skip paths handed to the walker are re-anchored
+ * under the collecting lake's configured root.
  * @param specs The configured lakes.
  * @returns The runtime lakes.
  */
 export function createLakes(specs: readonly LakeSpec[]): Lake[] {
-    return specs.map((spec) =>
-        createLake(spec, {
-            skip: specs
-                .filter((other) => other !== spec)
-                .map((other) => other.root),
-        }),
-    );
+    const realRoots = specs.map((spec) => realPathOf(spec.root));
+    return specs.map((spec, index) => {
+        const own = realRoots[index] ?? spec.root;
+        const skip = specs.flatMap((other, otherIndex) => {
+            if (otherIndex === index) {
+                return [];
+            }
+            const otherRoot = realRoots[otherIndex] ?? other.root;
+            return otherRoot !== own && isUnder(otherRoot, own)
+                ? [join(spec.root, relative(own, otherRoot))]
+                : [];
+        });
+        return createLake(spec, { skip });
+    });
 }
 
 /** The lake classes the configuration accepts. */
@@ -2819,6 +2849,44 @@ function findLake(lakes: readonly Lake[], name: string): Lake | undefined {
     return lakes.find((lake) => lake.name === name);
 }
 
+/**
+ * The environment notes for one lake, probed at call time. Legacy seams keep
+ * their captured notes; every real lake re-probes, so a root that appears,
+ * disappears or gains a git checkout is reported by the next surface that
+ * looks — `check`, `search` and help never disagree with a stale capture.
+ * @param lake The lake to describe.
+ * @returns The note lines.
+ */
+function lakeNotes(lake: Lake): readonly string[] {
+    return lake.root === ""
+        ? (lake.notes ?? [])
+        : unversionedNote(lake.root, lake.name);
+}
+
+/** Whether a lake root is absent, probed at call time. */
+function lakeMissing(lake: Lake): boolean {
+    return lake.root !== "" && !existsSync(lake.root);
+}
+
+/**
+ * How many knowledge lakes enclose a lake — the nesting depth used to pick the
+ * narrowest owner of a path and the deepest writable target for `add`. Wiki
+ * lakes never enclose anything.
+ * @param lake The lake to measure.
+ * @param lakes The configured lakes.
+ * @returns The number of enclosing knowledge lakes.
+ */
+function nestingDepth(lake: Lake, lakes: readonly Lake[]): number {
+    const root = realPathOf(lake.root);
+    return lakes.filter((other) => {
+        if (other === lake || other.profile === "wiki") {
+            return false;
+        }
+        const otherRoot = realPathOf(other.root);
+        return otherRoot !== root && isUnder(root, otherRoot);
+    }).length;
+}
+
 /** The lake `add` writes to, or the refusal reason. */
 function writableLake(
     lakes: readonly Lake[],
@@ -2836,14 +2904,34 @@ function writableLake(
         }
         return lake;
     }
-    return (
-        lakes.find((lake) => lake.class === "repo" && lake.writable) ??
-        lakes.find((lake) => lake.profile === "knowledge" && lake.writable) ?? {
+    // The narrowest writable knowledge lake wins: with nested roots the inner
+    // lake owns the file, so an outer read-only lake must not hijack the write.
+    const repos = lakes.filter(
+        (lake) => lake.class === "repo" && lake.writable,
+    );
+    const pool =
+        repos.length > 0
+            ? repos
+            : lakes.filter(
+                  (lake) => lake.profile === "knowledge" && lake.writable,
+              );
+    if (pool.length === 0) {
+        return {
             reason:
                 `${REFUSE} no writable knowledge lake is configured; ` +
                 "add a repo, machine, or global lake.",
+        };
+    }
+    let target = pool[0] as Lake;
+    let depth = nestingDepth(target, lakes);
+    for (const candidate of pool.slice(1)) {
+        const candidateDepth = nestingDepth(candidate, lakes);
+        if (candidateDepth > depth) {
+            target = candidate;
+            depth = candidateDepth;
         }
-    );
+    }
+    return target;
 }
 
 /** Qualify a path with its lake when more than one lake is configured. */
@@ -2887,9 +2975,8 @@ function searchDocs(
     const missing = runtime.lakes
         .filter(
             (lake) =>
-                lake.root !== "" &&
                 (lakeName === undefined || lakeName === lake.name) &&
-                !existsSync(lake.root),
+                lakeMissing(lake),
         )
         .map((lake) => missingRootNote(lake.root, lake.name));
     return {
@@ -2902,6 +2989,80 @@ function searchDocs(
     };
 }
 
+/** Why a lake is skipped by `check`, in one short line. */
+function skippedLakeLine(lake: LakeSpec): string {
+    const why = lake.profile === "wiki" ? "wiki class, read-only" : "read-only";
+    return `${lake.name}: ${why}, not validated.`;
+}
+
+/**
+ * Truncate a check report at a line boundary, counting the lines cut and
+ * pointing at the narrower report. A finding-heavy lake otherwise floods a
+ * tool result.
+ * @param content The full report text.
+ * @returns The report, within {@link MAX_CHECK_CHARS}, or its capped form.
+ */
+function cappedCheck(content: string): string {
+    if (content.length <= MAX_CHECK_CHARS) {
+        return content;
+    }
+    const lines = content.split("\n");
+    const kept: string[] = [];
+    let length = 0;
+    for (const line of lines) {
+        const next = length + (kept.length > 0 ? 1 : 0) + line.length;
+        if (next > MAX_CHECK_CHARS) {
+            break;
+        }
+        kept.push(line);
+        length = next;
+    }
+    const omitted = lines.length - kept.length;
+    const head = kept.length > 0 ? `${kept.join("\n")}\n\n` : "";
+    return (
+        `${head}… and ${omitted} more lines not shown. ` +
+        "Narrow it per lake with the `lake` selector."
+    );
+}
+
+/** Run one lake's check report and count the docs looked at. */
+function lakeReport(
+    runtime: Runtime,
+    lake: Lake,
+): { report: string; checked: number } {
+    const entries = lake.collect();
+    return {
+        report: checkDocs(entries, lake.read, lakeNotes(lake), {
+            maxDocLines: runtime.maxDocLines,
+            ...(lake.linkCheck ? { exists: lake.exists } : {}),
+        }),
+        checked: entries.length,
+    };
+}
+
+/**
+ * Join the validated lakes' reports and the skipped-lake lines. Only the
+ * reports are capped: "no findings" must never read as "compliant" when a lake
+ * was simply not looked at.
+ * @param reports The validated lakes' reports, in configuration order.
+ * @param skipped One-line reasons for each lake `check` did not validate.
+ * @returns The check result text.
+ */
+function assembleCheck(
+    reports: readonly string[],
+    skipped: readonly string[],
+): string {
+    const report = reports.length > 0 ? cappedCheck(reports.join("\n\n")) : "";
+    const tail = skipped.join("\n");
+    if (report === "" && tail === "") {
+        return "No knowledge lakes configured.";
+    }
+    if (report === "" || tail === "") {
+        return report || tail;
+    }
+    return `${report}\n\n${tail}`;
+}
+
 /** Check the knowledge lakes, optionally limited to one. */
 function checkLakes(
     runtime: Runtime,
@@ -2912,54 +3073,24 @@ function checkLakes(
         if (lake === undefined) {
             return { content: `No lake named '${lakeName}'.`, checked: 0 };
         }
-        if (lake.profile === "wiki") {
-            return {
-                content:
-                    `Lake '${lake.name}' is a wiki lake — read-only reference, ` +
-                    "not validated.",
-                checked: 0,
-            };
+        if (!lakeValidated(lake)) {
+            return { content: skippedLakeLine(lake), checked: 0 };
         }
-        const entries = lake.collect();
-        return {
-            content: checkDocs(entries, lake.read, lake.notes, {
-                maxDocLines: runtime.maxDocLines,
-                ...(lake.linkCheck ? { exists: lake.exists } : {}),
-            }),
-            checked: entries.length,
-        };
+        const { report, checked } = lakeReport(runtime, lake);
+        return { content: cappedCheck(report), checked };
     }
-    const knowledge = runtime.lakes.filter(
-        (lake) => lake.profile === "knowledge",
-    );
     let checked = 0;
-    const reports = knowledge.map((lake) => {
-        const entries = lake.collect();
-        checked += entries.length;
-        const report = checkDocs(entries, lake.read, lake.notes, {
-            maxDocLines: runtime.maxDocLines,
-            ...(lake.linkCheck ? { exists: lake.exists } : {}),
-        });
-        return knowledge.length > 1 || runtime.lakes.length > 1
-            ? `${lake.name}:\n${report}`
-            : report;
+    const reports = runtime.lakes.filter(lakeValidated).map((lake) => {
+        const outcome = lakeReport(runtime, lake);
+        checked += outcome.checked;
+        return runtime.lakes.length > 1
+            ? `${lake.name}:\n${outcome.report}`
+            : outcome.report;
     });
-    const wiki = runtime.lakes
-        .filter((lake) => lake.profile === "wiki")
-        .map((lake) => lake.name);
-    if (wiki.length > 0) {
-        reports.push(
-            `note: wiki lakes are read-only reference and are not validated: ` +
-                `${wiki.join(", ")}.`,
-        );
-    }
-    return {
-        content:
-            reports.length > 0
-                ? reports.join("\n\n")
-                : "No knowledge lakes configured.",
-        checked,
-    };
+    const skipped = runtime.lakes
+        .filter((lake) => !lakeValidated(lake))
+        .map(skippedLakeLine);
+    return { content: assembleCheck(reports, skipped), checked };
 }
 
 /** Add a doc to the target lake. */
@@ -3064,14 +3195,26 @@ function uniqueHolder(
     if (holders.length === 0) {
         return { reason: `No doc at ${path}.` };
     }
-    if (holders.length > 1) {
-        return {
-            reason:
-                `${REFUSE} ${path} exists in multiple lakes ` +
-                `(${holders.map((lake) => lake.name).join(", ")}); pass lake.`,
-        };
+    if (holders.length === 1) {
+        return holders[0] as Lake;
+    }
+    // Nested lakes both hold an inner path: the narrowest enclosing lake owns
+    // it. Non-nested holders tie on depth, which stays a documented refusal —
+    // never a silent pick by collection order.
+    const deepest = holders.map((lake) => ({
+        lake,
+        depth: nestingDepth(lake, holders),
+    }));
+    const max = Math.max(...deepest.map((item) => item.depth));
+    const winners = deepest.filter((item) => item.depth === max);
+    if (winners.length === 1) {
+        return winners[0]?.lake as Lake;
     }
-    return holders[0] as Lake;
+    return {
+        reason:
+            `${REFUSE} ${path} exists in multiple lakes ` +
+            `(${holders.map((lake) => lake.name).join(", ")}); pass lake.`,
+    };
 }
 
 /** Read one doc, resolving a `lake:path` prefix or the unique match. */
@@ -3121,8 +3264,8 @@ function lakeInfo(lakes: readonly Lake[]): LakeInfo[] {
         class: lake.class,
         root: lake.root,
         writable: lake.writable,
-        validated: lake.profile === "knowledge",
-        missing: lake.root !== "" && !existsSync(lake.root),
+        validated: lakeValidated(lake),
+        missing: lakeMissing(lake),
     }));
 }