@markstanden/opencode-docs-plugin 0.12.0 → 0.13.0

package/README.md

@@ -407,6 +407,9 @@ npm test          # node --test
 npm run typecheck
 ```
 
+Testing instructions, the behavioural placement trials and their container
+live in [TESTING.md](TESTING.md).
+
 Tests run the plugin source directly under Node's type-stripping (`noEmit`,
 `erasableSyntaxOnly`), so the file OpenCode loads is the file under test.
 
@@ -415,15 +418,37 @@ ranking harness pins behaviour against — edit it directly. It holds invented
 paths and summaries only; never snapshot a real docs tree into it.
 
 `tests/fixtures/placement-cases.json` is a synthetic evaluation fixture for
-the placement guidance (cases E01–E16, each with a claim, evidence,
+the placement guidance (cases E01–E18, each with a claim, evidence,
 destinations, expected scope or action, acceptable rationale and tempting
-wrong answer). To evaluate the guidance behaviourally: run the cases through
-a model with the docs tools mounted, holding model, settings and tool
-configuration constant, and score first-choice accuracy, unnecessary
-splitting, inappropriate fallback writes and the tool calls needed to correct
-recording. No behavioural trials have been run with the current wording; a
-fixture that merely asserts expected answers in Node is not evidence a model
-follows the guidance.
+wrong answer). `tests/fixtures/placement-harness/harness.mts` runs the cases
+behaviourally: `generate` materialises one prompt, one pristine fixture tree
+and one out-of-band rubric per case (defaults `~/tmp/docs-placement/` for
+prompts, rubrics and results, `~/test-dir/docs-placement/` for fixtures),
+`run` copies one case into a stamped results directory and drives a headless
+`opencode run` session there, `judge` scores each answer against the case
+rubric with a second, plugin-free model call (`--judge-model` names a stronger
+judge than the workhorse), and `export` bundles a sweep into one `dossier.md`
+for deep review by an external model. Trials judge placement from the supplied
+finding: a per-case run container sees only that case's sandbox, prompt, an
+id-only case list and the result, and the requested shell/edit/read denials
+are defence in depth rather than guarantees — each case's trail exposure is
+classified and reported in the sweep summary.
+`container-run.sh` runs the harness inside a Debian-slim trial container
+(Node LTS, current `@opencode/cli`, read-only root filesystem) so trials see
+no host filesystem at all; the harness can also run directly on the host.
+Runs modify neither the repository nor the fixture trees. The first
+behavioural sweep is recorded: sweep-1 (2026-11-07, plugin 0.12.0 at main
+`f5a5882`), decision-only prompts with the `docs` skill in session, workhorse
+`opencode-go/deepseek-v4.1-flash` in the trial container — 14/17 under the
+workhorse judge, 17/17 under `zai-coding-plan/glm-5.3-flash`, with the three
+disagreements resolved by manual review in favour of rewording the fixture
+and rubric (E09, E06) rather than the guidance; see [TESTING.md](TESTING.md).
+The principle stands: a fixture that merely asserts expected answers in Node
+is not evidence a model follows the guidance. In this repository,
+`/placement` (workflow in
+`.opencode/skills/placement-trials/`) drives the harness: trials run on the
+workhorse model, judging defaults to the current session model, and `export`
+bundles a sweep for a stronger external reviewer.
 
 ## Licence
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@markstanden/opencode-docs-plugin",
-    "version": "0.12.0",
+    "version": "0.13.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/index.ts

@@ -1156,12 +1156,44 @@ function readDirectory(directory: string): Dirent[] {
     }
 }
 
+/**
+ * The one collection-visibility rule for a root-relative doc path: the
+ * path segment that makes it invisible to collection, or null when the path
+ * is collected. Knowledge lakes skip the scratch and mirror areas at the
+ * top level; every profile skips dot-directories and `node_modules` at any
+ * depth. Shared by the collection walk ({@link collectDocPaths}) and the
+ * `add` target validation, so a write can never land where collection
+ * refuses to look.
+ * @param path Root-relative doc path, `/`-separated.
+ * @param profile The lake's writing convention.
+ * @returns The offending segment, or null when the path is collected.
+ */
+export function uncollectedSegment(
+    path: string,
+    profile: LakeProfile,
+): string | null {
+    const segments = path.split("/");
+    const top = segments[0] ?? "";
+    if (
+        profile === "knowledge" &&
+        (EXCLUDED_AREAS as readonly string[]).includes(top)
+    ) {
+        return top;
+    }
+    for (const segment of segments) {
+        if (segment.startsWith(".") || segment === "node_modules") {
+            return segment;
+        }
+    }
+    return null;
+}
+
 /**
  * Whether a directory is outside the lake's collection rules.
  * @param item The directory entry.
  * @param directory Its parent directory.
  * @param root The lake root.
- * @param excluded Top-level areas the profile excludes.
+ * @param profile The lake's writing convention.
  * @param nested Other lake roots nested inside this one.
  * @returns True when the walk should not enter it.
  */
@@ -1169,12 +1201,9 @@ function skipDirectory(
     item: Dirent,
     directory: string,
     root: string,
-    excluded: readonly string[],
+    profile: LakeProfile,
     nested: readonly string[],
 ): boolean {
-    if (item.name.startsWith(".") || item.name === "node_modules") {
-        return true;
-    }
     if (item.isSymbolicLink()) {
         return true;
     }
@@ -1182,7 +1211,12 @@ function skipDirectory(
     if (nested.some((other) => isUnder(path, other))) {
         return true;
     }
-    return directory === root && excluded.includes(item.name);
+    return (
+        uncollectedSegment(
+            relative(root, path).split(sep).join("/"),
+            profile,
+        ) !== null
+    );
 }
 
 /**
@@ -1223,14 +1257,12 @@ export function collectDocPaths(
     const nested = skip.filter(
         (other) => other !== root && isUnder(other, root),
     );
-    const excluded =
-        profile === "knowledge" ? (EXCLUDED_AREAS as readonly string[]) : [];
     const paths: string[] = [];
     const walk = (directory: string): void => {
         for (const item of readDirectory(directory)) {
             const path = join(directory, item.name);
             if (item.isDirectory()) {
-                if (!skipDirectory(item, directory, root, excluded, nested)) {
+                if (!skipDirectory(item, directory, root, profile, nested)) {
                     walk(path);
                 }
                 continue;
@@ -1238,7 +1270,11 @@ export function collectDocPaths(
             if (
                 !item.isFile() ||
                 item.isSymbolicLink() ||
-                !item.name.endsWith(".md")
+                !item.name.endsWith(".md") ||
+                uncollectedSegment(
+                    relative(root, path).split(sep).join("/"),
+                    profile,
+                ) !== null
             ) {
                 continue;
             }
@@ -1342,13 +1378,49 @@ function isReadme(name: string): boolean {
     return name.toLowerCase() === "readme.md";
 }
 
+/**
+ * Resolve an `add` request's target path and apply the collection-visibility
+ * rule: the resolved path (derived or explicit) must be a path the target
+ * lake would actually collect, or the refusal explains why.
+ * @param add The typed request.
+ * @param profile The target lake's writing convention.
+ * @returns The target path, or the refusal reason.
+ */
+function resolvedTargetOf(
+    add: DocsAdd,
+    profile: LakeProfile,
+): { path: string } | { reason: string } {
+    const target = targetOf(add);
+    if ("reason" in target) {
+        return target;
+    }
+    const invisible = uncollectedSegment(target.path, profile);
+    if (invisible !== null) {
+        return {
+            reason:
+                `'${invisible}' in ${target.path} is never collected by a ` +
+                `${profile} lake — the write would succeed yet stay ` +
+                "invisible to search, read and check. Choose a visible " +
+                "Area or path.",
+        };
+    }
+    return target;
+}
+
 /**
  * The project's nested README paths, relative to `location`. Inside a git work
  * tree git supplies the list — tracked plus untracked, honouring `.gitignore` —
  * so dependency, build and scratch directories follow the project's own rules.
  * Outside one, a walk skips {@link README_EXCLUDED_DIRS} and dot-directories.
- * Paths under `skip` (the lake root) are dropped: they are already lake docs.
- * A tracked file deleted from disk is dropped too — git still lists it.
+ * Both sources keep regular files only, and never follow a link: a leaf
+ * symlink, a broken link, or a symlinked directory anywhere along the path
+ * below `location` is not the project's own content, and following it could
+ * index a file outside the tree — git can still list tracked paths whose
+ * directory was replaced by a link. The project directory itself is the
+ * trusted root: when it resolves through a symlink, containment is validated
+ * from it downward, not above. Paths under `skip` (the lake root) are
+ * dropped: they are already lake docs. A tracked file deleted from disk is
+ * dropped too — git still lists it.
  * @param location The project directory the plugin loaded in.
  * @param skip Absolute roots whose READMEs are collected elsewhere.
  * @returns Project-relative README paths, ordered by path.
@@ -1359,13 +1431,54 @@ export function readmePaths(
 ): string[] {
     const candidates = gitReadmePaths(location) ?? walkedReadmePaths(location);
     return candidates
-        .filter((path) => existsSync(join(location, path)))
+        .filter((path) => isContainedRegularFile(location, path))
         .filter(
             (path) => !skip.some((root) => isUnder(join(location, path), root)),
         )
         .sort(compareText);
 }
 
+/** Whether a path exists and is a regular file, never following a symlink. */
+function isRegularFile(path: string): boolean {
+    try {
+        return lstatSync(path).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/** Whether a path exists and is a real directory, never following a symlink. */
+function isRealDirectory(path: string): boolean {
+    try {
+        return lstatSync(path).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Whether `relativePath` names a regular file whose every intermediate
+ * component below `location` is a real directory, never a symlink — the
+ * leaf check alone would follow a link planted mid-path into outside
+ * content.
+ * @param location The trusted project root; containment is validated below it.
+ * @param relativePath A project-relative README candidate path.
+ * @returns True only for a fully contained regular file.
+ */
+function isContainedRegularFile(
+    location: string,
+    relativePath: string,
+): boolean {
+    const parts = relativePath.split("/");
+    const leaf = parts.pop() ?? "";
+    let current = location;
+    for (const part of parts) {
+        current = join(current, part);
+        if (!isRealDirectory(current)) return false;
+    }
+    return isRegularFile(join(current, leaf));
+}
+
 /**
  * README paths from git's index and untracked non-ignored files, or undefined
  * when `location` is not inside a git work tree.
@@ -1744,6 +1857,30 @@ function revisionRefusal(add: DocsAdd): string | null {
     return null;
 }
 
+/**
+ * The first required metadata field whose value carries a line break, or
+ * null. The front-matter serialisation is flat `Key: value` lines: a break
+ * inside a value would emit a second line that parses as its own field (a
+ * hand-maintained `Date`, a shadowed `Keywords`), so multiline values are
+ * refused at the boundary rather than corrupted on disk.
+ * @param metadata The typed request metadata.
+ * @returns The offending field name, or null.
+ */
+function multilineMetadataField(metadata: DocMetadata): string | null {
+    for (const { name } of FRONT_MATTER_FIELDS) {
+        const value = metadata[name];
+        const pieces = Array.isArray(value) ? value : [value];
+        if (
+            pieces.some(
+                (piece) => typeof piece === "string" && /[\r\n]/.test(piece),
+            )
+        ) {
+            return name;
+        }
+    }
+    return null;
+}
+
 /**
  * The refusal for DTO content a knowledge doc may not carry: blank required
  * metadata, an `Area` off the root, a missing `H1`, no claim section, or an
@@ -1756,6 +1893,15 @@ function contentRefusal(add: DocsAdd): string | null {
     if (blank !== null) {
         return `${blank} is required and must not be blank.`;
     }
+    const multiline = multilineMetadataField(add.metadata);
+    if (multiline !== null) {
+        return (
+            `${multiline} must be a single line: line breaks in serialized ` +
+            "front-matter would corrupt the doc's metadata (a second line " +
+            "becomes a field of its own). Keep each value one line; pass " +
+            "Keywords as several elements, not one delimited string."
+        );
+    }
     if (/[/\\]|\.\./.test(add.metadata.Area)) {
         return "Area must be a single folder name under the lake root.";
     }
@@ -1790,19 +1936,23 @@ function contentRefusal(add: DocsAdd): string | null {
  * path or `Area` escaping the lake root, a non-`.md` target and a title that
  * yields no slug are all refused. A same-area near-twin — a doc matching every
  * reconcile query term ({@link reconcileQuery}) — refuses a create unless a
- * non-blank `allowNearTwinReason` explains the deliberate distinct doc.
+ * non-blank `allowNearTwinReason` explains the deliberate distinct doc. A
+ * target the lake would never collect ({@link uncollectedSegment}) is
+ * refused too: a successful write that search cannot see is a silent loss.
  * Target existence is the caller seam's to verify: creates must not overwrite
  * and replaces must exist.
  * @param add The typed request.
  * @param entries The current docs, for reconcile and neighbours.
- * @param options Soft-limit configuration.
+ * @param options Soft-limit configuration and the target lake's profile.
  * @param options.maxDocLines Note when the body exceeds this line count; `0` disables.
+ * @param options.profile The target lake's writing convention, for the
+ * collection-visibility rule; defaults to `knowledge`.
  * @returns The prepared write, or the refusal.
  */
 export function prepareAdd(
     add: DocsAdd,
     entries: readonly DocEntry[],
-    options: { maxDocLines?: number } = {},
+    options: { maxDocLines?: number; profile?: LakeProfile } = {},
 ): AddOutcome {
     const refuse = (reason: string): AddOutcome => ({
         action: "refuse",
@@ -1826,7 +1976,7 @@ export function prepareAdd(
     if (content !== null) {
         return refuse(content);
     }
-    const target = targetOf(add);
+    const target = resolvedTargetOf(add, options.profile ?? "knowledge");
     if ("reason" in target) {
         return refuse(target.reason);
     }
@@ -4382,6 +4532,7 @@ function addDoc(
     const entries = target.collect();
     const outcome = prepareAdd(add, entries, {
         maxDocLines: runtime.maxDocLines,
+        profile: target.profile,
     });
     if (outcome.action === "refuse") {
         return { content: outcome.reason, written: false };