@g3nomaly/g3n-skills 0.1.3 → 0.1.5

package/skills/coding/document/references/rust.md

@@ -0,0 +1,122 @@
+# Rust
+
+Rustdoc: a `/** */` block directly above the item, written in Markdown. Never `///`.
+
+- **Line 1**: `// src/users/store.rs`, the relative path. No `//!` or `/*! */` module or crate docs.
+- **Declarations with a docstring**: functions, methods, structs, enums, traits and type aliases.
+- **Summary**: `/** Adds two numbers. */` on one line. The first line is the `@brief`: a longer block opens with the summary, then a blank ` *` line.
+- **Tags**: Markdown sections `# Arguments`, `# Returns`, `# Errors`, `# Panics` and `# Examples`. Arguments are a list of `` * `name` - text ``.
+- **Fields and variants**: Rust has no field tag, so this is the one exception to the owner rule. Each struct field and enum variant gets its own one-line `/** */`. Rustdoc and analyze both read it from there.
+- **Examples**: a fenced block under `# Examples`. `cargo test` compiles and runs it, so it must build. Setup lines start with `# `, which hides them from the rendered docs.
+
+```rust
+/** Adds two numbers. */
+pub fn add(a: i32, b: i32) -> i32 {
+    a + b
+}
+
+/**
+ * Retrieves a user by id.
+ *
+ * # Arguments
+ *
+ * * `user_id` - Surrogate key from the `users` table, not the auth provider's id.
+ *
+ * # Returns
+ *
+ * Custom User struct used by the authentication service, or `None` when no row matches.
+ *
+ * # Errors
+ *
+ * `StoreError::Connection` when the database is unreachable.
+ */
+pub async fn get_user(user_id: i64) -> Result<Option<User>, StoreError> {
+    // ...
+}
+
+/**
+ * Error for a file on disk that does not match its schema.
+ *
+ * Holds the path of the file and one issue per rejected field, and its
+ * `Display` lists them all. Returned by `parse_file` and by the readers in
+ * `filetree/`, `decisions/` and `vocabulary/` that check a file's layout by
+ * hand. Callers tell it apart from other errors by matching on the type.
+ *
+ * # Examples
+ *
+ * ```
+ * # use harbor::{FileValidationError, FileValidationIssue};
+ * let error = FileValidationError {
+ *     file: "/home/me/app/docs/auth.md".into(),
+ *     issues: vec![FileValidationIssue { field: "status".into(), message: r#"is "done""#.into() }],
+ * };
+ * ```
+ */
+#[derive(Debug)]
+pub struct FileValidationError {
+    /** Absolute path of the file that failed, e.g. `/home/me/app/docs/auth.md`. */
+    pub file: PathBuf,
+    /** Rejected fields, e.g. `FileValidationIssue { field: "phases.0.status".into(), message: "is required".into() }`. */
+    pub issues: Vec<FileValidationIssue>,
+}
+
+/** Entries a set of requests resolved to, and the requests that did not resolve. */
+pub struct Resolution {
+    /** Resolved entries by key, e.g. `emphasise`. */
+    pub entries: HashMap<String, SourceOffer>,
+    /** Requests no source offers, e.g. `ghost@mine`. */
+    pub unknown: Vec<String>,
+    /** Why an entry nobody named is in the set, e.g. `("vocabulary", "dep of plan")`. */
+    pub notes: HashMap<String, String>,
+}
+```
+
+`harbor` in the example stands for the crate's own name. Doctests use the crate from outside, so `crate::` does not work there.
+
+A function that returns `Result` always has `# Errors`. One that can panic always has `# Panics`.
+
+## Bad
+
+Each one next to what is wrong with it. The examples above show the fix.
+
+```rust
+/// Adds two numbers.
+pub fn add(a: i32, b: i32) -> i32
+```
+A `///` comment. Use `/** Adds two numbers. */`.
+
+```rust
+/**
+ * Entries a set of requests resolved to.
+ *
+ * # Fields
+ *
+ * * `entries` - Resolved entries by key.
+ */
+pub struct Resolution {
+    pub entries: HashMap<String, SourceOffer>,
+}
+```
+Fields listed in the struct's docstring. Neither rustdoc nor analyze reads them there. The `/** */` goes on the field.
+
+```rust
+/** Parses a file. */
+pub fn parse_file(path: &Path) -> Result<Tree, FileValidationError>
+```
+Returns `Result` with no `# Errors` section.
+
+```rust
+/**
+ * # Examples
+ *
+ * ```
+ * let error = FileValidationError::new(path, vec![issue]);
+ * ```
+ */
+```
+`path` and `issue` are never defined and the type is never imported, so `cargo test` fails on it.
+
+```rust
+/*! User storage. */
+```
+A module docstring. Line 1 is the path comment, and the items carry the docs.

package/skills/coding/document/vscode/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "g3n-doc-tags",
+  "displayName": "g3n Doc Tags",
+  "description": "Colours the sections and argument names of Rust doc comments and Python docstrings like JSDoc tags.",
+  "publisher": "g3nomaly",
+  "version": "0.1.0",
+  "license": "Elastic-2.0",
+  "engines": {
+    "vscode": "^1.80.0"
+  },
+  "categories": [
+    "Programming Languages"
+  ],
+  "contributes": {
+    "grammars": [
+      {
+        "scopeName": "g3n.doc-tags.rust",
+        "path": "./syntaxes/rust.json",
+        "injectTo": ["source.rust", "text.html.markdown"]
+      },
+      {
+        "scopeName": "g3n.doc-tags.python",
+        "path": "./syntaxes/python.json",
+        "injectTo": ["source.python", "text.html.markdown"]
+      }
+    ]
+  }
+}

package/skills/coding/document/vscode/syntaxes/python.json

@@ -0,0 +1,56 @@
+{
+  "scopeName": "g3n.doc-tags.python",
+  "injectionSelector": "L:string.quoted.docstring.multi.python, L:string.quoted.docstring.raw.multi.python",
+  "patterns": [
+    { "include": "#named-section" },
+    { "include": "#raises-section" },
+    { "include": "#plain-section" }
+  ],
+  "repository": {
+    "named-section": {
+      "comment": "`Args:` or `Attributes:` and the `name (type):` items under it. The section ends at the first line that is not indented deeper, or at the closing quotes.",
+      "begin": "^(\\s*)(Args|Arguments|Attributes|Keyword Args|Keyword Arguments|Other Parameters)(:)\\s*$",
+      "end": "(?=\"\"\"|''')|^(?!\\1\\s+\\S|\\s*$)",
+      "beginCaptures": {
+        "2": { "name": "storage.type.class.jsdoc" },
+        "3": { "name": "punctuation.separator.jsdoc" }
+      },
+      "patterns": [
+        {
+          "match": "^\\s+(\\*{0,2}[A-Za-z_]\\w*)(?:\\s*\\(([^)]*)\\))?(:)(?=\\s|$)",
+          "captures": {
+            "1": { "name": "variable.other.jsdoc" },
+            "2": { "name": "entity.name.type.instance.jsdoc" },
+            "3": { "name": "punctuation.separator.jsdoc" }
+          }
+        }
+      ]
+    },
+    "raises-section": {
+      "comment": "`Raises:` and the `ErrorType:` items under it.",
+      "begin": "^(\\s*)(Raises)(:)\\s*$",
+      "end": "(?=\"\"\"|''')|^(?!\\1\\s+\\S|\\s*$)",
+      "beginCaptures": {
+        "2": { "name": "storage.type.class.jsdoc" },
+        "3": { "name": "punctuation.separator.jsdoc" }
+      },
+      "patterns": [
+        {
+          "match": "^\\s+([A-Za-z_][\\w.]*)(:)(?=\\s|$)",
+          "captures": {
+            "1": { "name": "entity.name.type.instance.jsdoc" },
+            "2": { "name": "punctuation.separator.jsdoc" }
+          }
+        }
+      ]
+    },
+    "plain-section": {
+      "comment": "Sections whose body is prose or code, such as `Returns:` and `Example:`. Only the heading is coloured.",
+      "match": "^\\s*(Returns|Yields|Example|Examples|Note|Notes|Warning|Warnings|See Also|Todo)(:)\\s*$",
+      "captures": {
+        "1": { "name": "storage.type.class.jsdoc" },
+        "2": { "name": "punctuation.separator.jsdoc" }
+      }
+    }
+  }
+}

package/skills/coding/document/vscode/syntaxes/rust.json

@@ -0,0 +1,25 @@
+{
+  "scopeName": "g3n.doc-tags.rust",
+  "injectionSelector": "L:comment.block.documentation.rust",
+  "patterns": [
+    { "include": "#section" },
+    { "include": "#argument" }
+  ],
+  "repository": {
+    "section": {
+      "comment": "A section heading such as ` * # Errors`. Only known names, so a hidden doctest line such as `# use harbor::Tree;` stays plain.",
+      "match": "^\\s*\\*?\\s*(#)\\s+(Arguments|Returns|Errors|Panics|Safety|Examples)\\s*$",
+      "captures": {
+        "1": { "name": "punctuation.definition.block.tag.jsdoc" },
+        "2": { "name": "storage.type.class.jsdoc" }
+      }
+    },
+    "argument": {
+      "comment": "An item of the Arguments list: ` * * `user_id` - text`.",
+      "match": "^\\s*\\*?\\s*[*-]\\s+(`)([A-Za-z_]\\w*)(`)\\s+(-)(?=\\s)",
+      "captures": {
+        "2": { "name": "variable.other.jsdoc" }
+      }
+    }
+  }
+}

package/skills/coding/vocabulary/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: vocabulary
+description: Use when about to name a domain concept in code, a task or a doc, when the user corrects a word, when two words are in use for one thing, or when another skill needs a term looked up or recorded.
+registryDependencies: [domain-modeling]
+disable-model-invocation: false
+---
+
+Every session starts without the last one's words, so names _drift_: the _phase_ of Monday is the _stage_ of Tuesday, and by Friday the code has both. The glossary is the one list that stops it. Each **term** carries a definition and the **avoided words** it replaces.
+
+The terms live in `docs/glossary.md`. Read and edit it directly. `g3n-analyze` reads the same file and links every term to its first use in the docs and code, and the task-manager's `get-entry` and `next-entry` list the terms each entry mentions.
+
+## Looking a word up
+
+Before you name a domain concept, search `docs/glossary.md` for the word.
+
+- **Found as a term.** Use it as spelled.
+- **Found under `_Avoid_`.** Use the term it belongs to instead, in prose and in identifiers alike.
+- **Not found.** Use the word, and record it on its second sighting.
+
+## Recording a term
+
+**Record on the second sighting.** One use of a word is prose. The same concept named twice, or named differently by two people, is a term. A correction from the user is always a term.
+
+Create the file when the first term is recorded. Keep this layout, because the parsers depend on it:
+
+```md
+# Glossary
+
+One sentence on what the project is about.
+
+## Planning
+
+**Phase**:
+One step of a plan, holding tasks.
+_Avoid_: stage, milestone
+
+**Task**:
+One piece of work inside a phase, done in one session.
+```
+
+- **Term.** A line that starts with the bold name and a colon: `**Phase**:`.
+- **Definition.** One or two sentences on the lines below, saying what the thing _is_. Leave out how it is built.
+- **`_Avoid_:`.** The synonyms actually seen, comma-separated, on the last line of the term. Leave the line out when there are none.
+- **Groups.** A `##` heading above a run of terms groups them. A flat list is fine for a small glossary.
+- **One meaning per word.** A word is a term or an avoided word of one term, never both and never twice. Before adding a word to `_Avoid_`, check that no other term already owns it.
+
+A term whose meaning is still contested is sharpened with the `/domain-modeling` skill first, then recorded here.

package/skills/coding/vocabulary/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Vocabulary"
+  short_description: "One word per concept across sessions, recorded in docs/glossary.md"
+policy:
+  allow_implicit_invocation: false

package/skills/task-manager/.claude-plugin/plugin.json

@@ -1,12 +1,11 @@
 {
   "name": "task-manager",
-  "description": "Query and drive a tree of plans, phases and tasks through hooks, with the plan's decisions and the project vocabulary kept beside them.",
+  "description": "Query and drive a tree of plans, phases and tasks through hooks, with the plan's decisions kept beside them.",
   "version": "0.1.0",
   "license": "UNLICENSED",
   "hooks": "./hooks.json",
   "skills": [
     "./task-manager",
-    "./vocabulary",
     "./decisions"
   ]
 }

package/skills/task-manager/task-manager/hooks/get-entry.ts

@@ -1,9 +1,9 @@
 // packages/g3n-skills/skills/task-manager/task-manager/hooks/get-entry.ts
 import { locateEntry, readEntry } from "../src/filetree";
-import { readVocabulary, termsMentioned } from "../src/vocabulary";
-import { hasFlag, printJson, requireFlag, resolveRoot, runHook } from "../src/hooks";
+import { readGlossary, termsMentioned } from "../src/vocabulary";
+import { hasFlag, printJson, requireFlag, resolveProject, resolveRoot, runHook } from "../src/hooks";
 
-/** Prints the plan, phase or task named by `--id` with its body and the vocabulary terms it mentions. */
+/** Prints the plan, phase or task named by `--id` with its body and the glossary terms it mentions. */
 async function run(argv: readonly string[]): Promise<void> {
   const root = await resolveRoot(argv);
   const name = requireFlag(argv, "--id", "auth-rework");
@@ -19,7 +19,7 @@ async function run(argv: readonly string[]): Promise<void> {
       trail: location.trail,
       meta,
       ...(hasFlag(argv, "--meta-only") ? {} : { body }),
-      vocabulary: termsMentioned(`${meta.title}\n${meta.summary}\n${body}`, await readVocabulary(root)),
+      vocabulary: termsMentioned(`${meta.title}\n${meta.summary}\n${body}`, await readGlossary(resolveProject(argv))),
     },
     argv,
   );

package/skills/task-manager/task-manager/hooks/guard-tree.ts

@@ -104,8 +104,8 @@ async function run(): Promise<void> {
     deny(
       `${target} is inside the task-manager tree, which is read through its hooks. ` +
         "Use get-entry --id <name> for one plan, phase or task in full, next-entry for the " +
-        "front of a queue, list-entries --in <name> to see what a folder holds, get-term --term <word> " +
-        "for the vocabulary, or list-decisions --in <plan> for a plan's decisions.",
+        "front of a queue, list-entries --in <name> to see what a folder holds, or list-decisions " +
+        "--in <plan> for a plan's decisions.",
     );
   }
 }

package/skills/task-manager/task-manager/hooks/next-entry.ts

@@ -1,8 +1,8 @@
 // packages/g3n-skills/skills/task-manager/task-manager/hooks/next-entry.ts
 import { ENTRY_TYPE, listEntryNames, readEntry, resolveParent } from "../src/filetree";
 import type { TaskStatus } from "../src/schemas";
-import { readVocabulary, termsMentioned } from "../src/vocabulary";
-import { hasFlag, printJson, readFlag, resolveRoot, runHook } from "../src/hooks";
+import { readGlossary, termsMentioned } from "../src/vocabulary";
+import { hasFlag, printJson, readFlag, resolveProject, resolveRoot, runHook } from "../src/hooks";
 
 const FINISHED: readonly TaskStatus[] = ["completed"];
 const NOT_WORKABLE: readonly TaskStatus[] = ["completed", "blocked"];
@@ -20,7 +20,7 @@ async function run(argv: readonly string[]): Promise<void> {
     const { file, meta, body } = await readEntry(dir, level, name);
     if (skipped.includes(meta.status)) continue;
 
-    const vocabulary = termsMentioned(`${meta.title}\n${meta.summary}\n${body}`, await readVocabulary(root));
+    const vocabulary = termsMentioned(`${meta.title}\n${meta.summary}\n${body}`, await readGlossary(resolveProject(argv)));
 
     printJson({ type: ENTRY_TYPE[level], name, file, meta, body, vocabulary }, argv);
     return;

package/skills/task-manager/task-manager/references/hooks.md

@@ -16,7 +16,7 @@ JSON on stdout, messages on stderr.
 
 - `next-entry` and `get-entry` return one entry; none found exits `1`.
 - `list-entries` and `cleanup` return a list; `[]` exits `0`.
-- `get-entry` and `next-entry` attach a `vocabulary` array: the terms the entry mentions.
+- `get-entry` and `next-entry` attach a `vocabulary` array: the terms of `docs/glossary.md` the entry mentions.
 - `set-state`, `cleanup` and `sync-tree` write; the others only read.
 
 ## Fired by the plugin

package/skills/task-manager/task-manager/references/tree.md

@@ -3,7 +3,6 @@
 ```
 <filetreeRoot>/                    # skills.settings.filetreeRoot, default docs/task-manager
 ├── root-index.json
-├── vocabulary.md
 └── <plan>/
     ├── <plan>.md
     ├── plan-index.json

package/skills/task-manager/task-manager/src/hooks/cli.ts

@@ -82,7 +82,17 @@ export async function resolveRoot(argv: readonly string[]): Promise<string> {
   const override = readFlag(argv, "--root");
   if (override !== undefined) return resolve(override);
 
-  return resolveFiletreeRoot(resolve(readFlag(argv, "--project") ?? process.cwd()));
+  return resolveFiletreeRoot(resolveProject(argv));
+}
+
+/**
+ * @brief Resolves the project the hook works in: `--project`, or the working directory.
+ *
+ * @param argv - Arguments of the hook.
+ * @returns Absolute project root.
+ */
+export function resolveProject(argv: readonly string[]): string {
+  return resolve(readFlag(argv, "--project") ?? process.cwd());
 }
 
 /** Reads everything piped to the hook on stdin, or returns `""` when run from a terminal. */

package/skills/task-manager/task-manager/src/hooks/index.ts

@@ -1,3 +1,3 @@
 // packages/g3n-skills/skills/task-manager/task-manager/src/hooks/index.ts
-export { readFlag, requireFlag, hasFlag, oneOf, resolveRoot, readStdin, printJson, runHook } from "./cli";
+export { readFlag, requireFlag, hasFlag, oneOf, resolveRoot, resolveProject, readStdin, printJson, runHook } from "./cli";
 export type { Hook } from "./cli";

package/skills/task-manager/task-manager/src/schemas/index.ts

@@ -32,8 +32,8 @@ export {
 } from "./decision";
 export type { DecisionStatus, Decision, DecisionIndex } from "./decision";
 
-export { TermSchema, VocabularySchema } from "./term";
-export type { Term, Vocabulary } from "./term";
+export { TermSchema, GlossarySchema } from "./term";
+export type { Term, Glossary } from "./term";
 
 export { CONFIG_FILE, DEFAULT_FILETREE_ROOT, FiletreeConfigSchema } from "./config";
 export type { FiletreeConfig } from "./config";

package/skills/task-manager/task-manager/src/schemas/term.ts

@@ -1,38 +1,25 @@
 // packages/g3n-skills/skills/task-manager/task-manager/src/schemas/term.ts
 import { z } from "zod";
 
-/** One line of text that cannot be mistaken for a Markdown heading. */
-const TermNameSchema = z
-  .string()
-  .regex(/^[^\s#][^\n]*$/, "must be a single line that does not start with # or a space");
-
-/** One entry of `vocabulary.md`: the word to use, what it means, and the words it replaces. */
+/** One term of `docs/glossary.md`: the word to use, what it means, and the words it replaces. */
 export const TermSchema = z.strictObject({
-  term: TermNameSchema,
-  definition: z
-    .string()
-    .min(1)
-    .refine(
-      (text) => !text.split("\n").some((line) => line.startsWith("#") || line.startsWith("_Avoid_:")),
-      "must not contain a line starting with # or _Avoid_:",
-    ),
-  avoid: z
-    .array(TermNameSchema.refine((word) => !word.includes(","), "must not contain a comma"))
-    .default([]),
+  term: z.string().min(1),
+  definition: z.string(),
+  avoid: z.array(z.string().min(1)).default([]),
 });
 
 /**
- * One entry of `vocabulary.md`, as `TermSchema` parses it.
+ * One term of `docs/glossary.md`, as `TermSchema` parses it.
  *
  * @property term - The word to use.
- * @property definition - What the term means, as written under its heading.
+ * @property definition - What the term means, as written below its name.
  * @property avoid - Words that mean the same thing and must not be used in its place.
  */
 export type Term = z.infer<typeof TermSchema>;
 
-export const VocabularySchema = z.strictObject({
+export const GlossarySchema = z.strictObject({
   terms: z.array(TermSchema).default([]),
 });
 
-/** Every term of `vocabulary.md`, as `VocabularySchema` parses it. */
-export type Vocabulary = z.infer<typeof VocabularySchema>;
+/** Every term of `docs/glossary.md`, as `GlossarySchema` parses it. */
+export type Glossary = z.infer<typeof GlossarySchema>;

package/skills/task-manager/task-manager/src/vocabulary/file.ts

@@ -1,114 +1,70 @@
 // packages/g3n-skills/skills/task-manager/task-manager/src/vocabulary/file.ts
 import { join } from "node:path";
 import { FileValidationError, parseFile } from "../schemas/validation";
-import { VocabularySchema, type Term } from "../schemas/term";
+import { GlossarySchema, type Term } from "../schemas/term";
 
-/** File at the tree root holding every term. Written by the term hooks only. */
-export const VOCABULARY_FILE = "vocabulary.md";
+/** File holding every term, relative to the project root. Written by hand, as the `vocabulary` skill describes. */
+export const GLOSSARY_FILE = join("docs", "glossary.md");
 
-const TITLE = "# Vocabulary";
-const TERM_HEADING = "## ";
-const AVOID_PREFIX = "_Avoid_:";
+/** `**Phase**:` or `**Phase:**`, optionally followed by the start of the definition. */
+const TERM_LINE = /^\*\*(.+?):?\*\*:?\s*(.*)$/;
+/** `_Avoid_: stage, milestone` */
+const AVOID_LINE = /^_Avoid_:\s*(.*)$/i;
 
 /**
- * @brief Builds the path of the vocabulary file in a tree.
+ * @brief Reads every term of the project's glossary, in the order they sit in the file.
  *
- * @param root - Absolute tree root folder.
- * @returns Path of `vocabulary.md` inside `root`.
- */
-export function vocabularyPathFor(root: string): string {
-  return join(root, VOCABULARY_FILE);
-}
-
-/**
- * @brief Reads every term of the tree at `root`, in the order they sit in the file.
+ * Text that is not part of a term, such as the title, the intro and the group headings, is skipped.
  *
- * @param root - Absolute tree root folder.
- * @returns Terms in file order, or an empty list when there is no vocabulary file yet.
- * @throws FileValidationError when the file strays from the layout
- *   `writeVocabulary` produces, or names one term twice
+ * @param projectRoot - Absolute folder holding `docs/glossary.md`.
+ * @returns Terms in file order, or an empty list when the project has no glossary.
+ * @throws FileValidationError when one term is defined twice.
  */
-export async function readVocabulary(root: string): Promise<Term[]> {
-  const file = vocabularyPathFor(root);
+export async function readGlossary(projectRoot: string): Promise<Term[]> {
+  const file = join(projectRoot, GLOSSARY_FILE);
   if (!(await Bun.file(file).exists())) return [];
 
-  const terms = parseFile(VocabularySchema, file, { terms: parseTerms(file, await Bun.file(file).text()) }).terms;
+  const terms = parseFile(GlossarySchema, file, { terms: parseTerms(await Bun.file(file).text()) }).terms;
   rejectDuplicates(file, terms);
 
   return terms;
 }
 
 /**
- * @brief Replaces the vocabulary file with `terms`, sorted by name so the file reads the same on every write.
+ * @brief Splits the glossary text into raw terms, one per bold term line.
  *
- * @param root - Absolute tree root folder.
- * @param terms - Terms to write; validated and checked for duplicate names first.
- */
-export async function writeVocabulary(root: string, terms: readonly Term[]): Promise<void> {
-  const file = vocabularyPathFor(root);
-  const validated = parseFile(VocabularySchema, file, { terms }).terms;
-  rejectDuplicates(file, validated);
-
-  const sorted = [...validated].sort(
-    (a, b) => a.term.localeCompare(b.term, "en", { sensitivity: "base" }) || a.term.localeCompare(b.term),
-  );
-
-  await Bun.write(file, `${[TITLE, ...sorted.map(renderTerm)].join("\n\n")}\n`);
-}
-
-/**
- * @brief Renders one term as its `## ` block in the vocabulary file.
+ * A term runs until the next term line or heading. Its `_Avoid_:` line is its avoid list, the rest its definition.
  *
- * @param term - Term to render.
+ * @param text - Full text of the glossary.
+ * @returns One raw term per bold term line, ready for `parseFile`.
  */
-function renderTerm(term: Term): string {
-  const lines = [`${TERM_HEADING}${term.term}`, "", term.definition.trim()];
-  if (term.avoid.length > 0) lines.push("", `${AVOID_PREFIX} ${term.avoid.join(", ")}`);
-
-  return lines.join("\n");
-}
-
-/**
- * @brief Splits the file text at its `## ` headings into raw term entries.
- *
- * The last `_Avoid_:` line of a block is its avoid list.
- *
- * @param file - Path of the file, used in the error message.
- * @param text - Full text of the vocabulary file.
- * @returns One raw entry per heading, ready for `parseFile`.
- * @throws FileValidationError when text sits above the first heading.
- */
-function parseTerms(file: string, text: string): unknown[] {
-  const terms: { term: string; lines: string[] }[] = [];
-
-  text.split("\n").forEach((line, index) => {
-    if (line.startsWith(TERM_HEADING)) {
-      terms.push({ term: line.slice(TERM_HEADING.length).trim(), lines: [] });
-      return;
+function parseTerms(text: string): unknown[] {
+  const terms: { term: string; lines: string[]; avoid: string[] }[] = [];
+  let open = false;
+
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("#")) {
+      open = false;
+      continue;
     }
 
-    const current = terms.at(-1);
-    if (current !== undefined) {
-      current.lines.push(line);
-      return;
+    const termMatch = TERM_LINE.exec(trimmed);
+    if (termMatch) {
+      terms.push({ term: (termMatch[1] ?? "").trim(), lines: [termMatch[2] ?? ""], avoid: [] });
+      open = true;
+      continue;
     }
 
-    if (line.trim() !== "" && line.trim() !== TITLE) {
-      throw new FileValidationError(file, [
-        { field: `line ${index + 1}`, message: `"${line}" sits above the first ${TERM_HEADING.trim()} heading` },
-      ]);
-    }
-  });
+    const current = terms.at(-1);
+    if (!open || current === undefined) continue;
 
-  return terms.map(({ term, lines }) => {
-    const avoidAt = lines.map((line) => line.startsWith(AVOID_PREFIX)).lastIndexOf(true);
-    const avoid = avoidAt === -1
-      ? []
-      : (lines[avoidAt] ?? "").slice(AVOID_PREFIX.length).split(",").map((word) => word.trim()).filter((word) => word !== "");
-    const definition = lines.filter((_, index) => index !== avoidAt).join("\n").trim();
+    const avoidMatch = AVOID_LINE.exec(trimmed);
+    if (avoidMatch) current.avoid = (avoidMatch[1] ?? "").split(",").map((word) => word.trim()).filter((word) => word !== "");
+    else current.lines.push(line);
+  }
 
-    return { term, definition, avoid };
-  });
+  return terms.map(({ term, lines, avoid }) => ({ term, definition: lines.join("\n").trim(), avoid }));
 }
 
 /**

package/skills/task-manager/task-manager/src/vocabulary/index.ts

@@ -1,5 +1,5 @@
 // packages/g3n-skills/skills/task-manager/task-manager/src/vocabulary/index.ts
-export { VOCABULARY_FILE, vocabularyPathFor, readVocabulary, writeVocabulary } from "./file";
+export { GLOSSARY_FILE, readGlossary } from "./file";
 
-export { findTerm, termsMentioned } from "./match";
-export type { TermMatch, TermMention } from "./match";
+export { termsMentioned } from "./match";
+export type { TermMention } from "./match";