@g3nomaly/g3n-skills 0.1.3 → 0.1.4

package/.claude-plugin/marketplace.json

@@ -17,11 +17,12 @@
     {
       "name": "coding",
       "source": "./skills/coding",
-      "description": "How to write, check and document code, per language, and query a repository with analyze.",
+      "description": "How to write, check and document code, per language, query a repository with analyze, and keep its glossary.",
       "skills": [
         "./code",
         "./document",
-        "./analyze"
+        "./analyze",
+        "./vocabulary"
       ]
     },
     {
@@ -49,10 +50,9 @@
     {
       "name": "task-manager",
       "source": "./skills/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.",
       "skills": [
         "./task-manager",
-        "./vocabulary",
         "./decisions"
       ]
     },

package/README.md

@@ -54,6 +54,7 @@ Skills marked _manual_ run only when you type their command, such as `/grill-me`
 | `coding` | `code` | Rules for writing and checking code, with a toolchain reference per language |
 | `coding` | `document` | Docstrings and comments for functions and classes, and where the reasons behind code go |
 | `coding` | `analyze` | Query a repository's model with `g3n-analyze` and rebuild its documentation site in `analyze_out/` |
+| `coding` | `vocabulary` | One word per concept, recorded in `docs/glossary.md`, so names don't drift between sessions |
 | `grilling` | `grilling` | Interview the user relentlessly to stress-test a plan, decision or idea |
 | `grilling` | `grill-me` | _Manual._ Starts a `/grilling` session |
 | `grilling` | `grill-with-docs` | _Manual._ A grilling session that writes ADRs and a glossary as it goes |
@@ -63,7 +64,6 @@ Skills marked _manual_ run only when you type their command, such as `/grill-me`
 | `speech` | `plain-language` | Write text readers can find, understand and use on the first read, following ISO 24495-1 |
 | `speech` | `no-questions` | Replies end without questions or offers; a Stop hook refuses a reply that asks one |
 | `task-manager` | `task-manager` | Query plans, phases and tasks and change their status through hooks |
-| `task-manager` | `vocabulary` | One word per concept, stored in the task-manager tree, so names don't drift between sessions |
 | `task-manager` | `decisions` | Record and look up a plan's decisions as numbered files inside the plan |
 | `using-hooks` | `hook-pre-tool-use` | _Manual._ Writing a `PreToolUse` hook, which can allow, deny or escalate a tool call |
 | `using-hooks` | `hook-post-tool-use` | _Manual._ Writing a `PostToolUse` hook, which reacts to a finished tool call |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g3nomaly/g3n-skills",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "The g3n skills, each with its own hooks: a skill source for @g3nomaly/skills and a Claude Code plugin marketplace.",
   "type": "module",
   "files": [

package/skills/coding/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "coding",
-  "description": "How to write, check and document code, per language, and query a repository with analyze.",
+  "description": "How to write, check and document code, per language, query a repository with analyze, and keep its glossary.",
   "version": "0.1.0",
   "license": "UNLICENSED",
-  "skills": ["./code", "./document", "./analyze"]
+  "skills": ["./code", "./document", "./analyze", "./vocabulary"]
 }

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";

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

@@ -1,22 +1,11 @@
 // packages/g3n-skills/skills/task-manager/task-manager/src/vocabulary/match.ts
 import type { Term } from "../schemas/term";
 
-/**
- * Term found by `findTerm`, with how the name matched it.
- *
- * @property term - The matched term.
- * @property matched - `"term"` when the name is the term itself, `"avoid"` when it is one of the term's avoided words.
- */
-export interface TermMatch {
-  term: Term;
-  matched: "term" | "avoid";
-}
-
 /**
  * Term a text uses, with the avoided words the text used for it.
  *
  * @property term - Name of the term.
- * @property definition - Definition of the term, as the vocabulary file holds it.
+ * @property definition - Definition of the term, as the glossary holds it.
  * @property avoided - Avoided words the text uses in place of `term`.
  */
 export interface TermMention {
@@ -25,26 +14,6 @@ export interface TermMention {
   avoided: string[];
 }
 
-/** Tells whether two words are equal, ignoring case. */
-function sameWord(a: string, b: string): boolean {
-  return a.toLowerCase() === b.toLowerCase();
-}
-
-/**
- * @brief Finds the term that answers to `name`, by its own name first and by an avoided word second.
- *
- * @param terms - Vocabulary to search.
- * @param name - Word to look up, compared ignoring case.
- * @returns The match, or `null` when no term has the name.
- */
-export function findTerm(terms: readonly Term[], name: string): TermMatch | null {
-  const own = terms.find((term) => sameWord(term.term, name));
-  if (own !== undefined) return { term: own, matched: "term" };
-
-  const replaced = terms.find((term) => term.avoid.some((word) => sameWord(word, name)));
-  return replaced === undefined ? null : { term: replaced, matched: "avoid" };
-}
-
 /** Tells whether `word` occurs in `text` as a whole word, ignoring case. */
 function mentions(text: string, word: string): boolean {
   const escaped = word.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -54,10 +23,10 @@ function mentions(text: string, word: string): boolean {
 /**
  * @brief Finds the terms `text` uses, by name or by an avoided word, in the order of `terms`.
  *
- * Used by the `get-entry` hook, which attaches each mention to its entry.
+ * Used by the `get-entry` and `next-entry` hooks, which attach each mention to its entry.
  *
  * @param text - Text to search, such as an entry's title, summary and body.
- * @param terms - Vocabulary to search.
+ * @param terms - Glossary to search.
  * @returns One mention per term the text uses.
  */
 export function termsMentioned(text: string, terms: readonly Term[]): TermMention[] {

package/skills/task-manager/vocabulary/SKILL.md

@@ -1,42 +0,0 @@
----
-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: [task-manager, 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 vocabulary is the one list that stops it. Each **term** carries a definition and the **avoided words** it replaces.
-
-Its hooks are scripts in its own `hooks/` folder, run as `bun <vocabulary-dir>/hooks/<hook>.ts`, where `<vocabulary-dir>` is this skill's base directory: the folder holding this `SKILL.md`.
-
-The terms live in `vocabulary.md` at the tree root. **Reach them through the hooks only.** `guard-tree` denies a direct read, and a hand edit is overwritten by the next `set-term`.
-
-| Hook | Does | Use it when |
-|---|---|---|
-| `get-term` | Returns one term, found by its name or by an avoided word | about to use a word for a domain concept |
-| `list-terms` | Returns every term, sorted by name | starting work in an unfamiliar area |
-| `set-term` | Adds a term, or replaces its definition and avoided words. **Writes.** | a concept got a name, or a name got sharper |
-| `remove-term` | Deletes one term. **Writes.** | the concept left the project |
-
-Copy each invocation from [`references/usage.md`](references/usage.md).
-
-They share `--project`, `--root` and `--pretty` with the task-manager hooks. `get-term` and `remove-term` exit `1` when nothing answers to the name. `list-terms` prints `[]` for an empty vocabulary.
-
-## Reading an answer
-
-`get-term` reports how it found the term in `matched`:
-
-- **`"term"`** means the word is the right one. Use it as spelled.
-- **`"avoid"`** means the word is a retired synonym. Use the returned `term` instead, in prose and in identifiers alike.
-
-`get-entry` and `next-entry` attach a `vocabulary` array to every plan, phase and task they return. It lists each term the entry mentions, and under `avoided` the retired words the entry still uses. Treat a non-empty `avoided` as a defect in the entry and write the term in whatever you produce from it.
-
-## 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.
-
-- **Definition.** One or two sentences saying what the thing _is_. Leave out how it is built.
-- **`--avoid`.** The synonyms actually seen, comma-separated. `set-term` refuses a word another term already owns, which is how two terms are kept from claiming one meaning.
-- **`set-term` replaces.** Pass the full definition and the full avoid list every time, since flags left out are cleared.
-
-A term whose meaning is still contested is sharpened with the `/domain-modeling` skill first, then stored here.

package/skills/task-manager/vocabulary/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Vocabulary"
-  short_description: "One word per concept across sessions, kept in the task-manager tree through hooks"
-policy:
-  allow_implicit_invocation: false

package/skills/task-manager/vocabulary/hooks/get-term.ts

@@ -1,18 +0,0 @@
-// packages/g3n-skills/skills/task-manager/vocabulary/hooks/get-term.ts
-import { findTerm, readVocabulary } from "@task-manager/vocabulary";
-import { printJson, requireFlag, resolveRoot, runHook } from "@task-manager/hooks";
-
-/** Prints the term `--term` names, found by its name or by one of its avoided words. */
-async function run(argv: readonly string[]): Promise<void> {
-  const root = await resolveRoot(argv);
-  const name = requireFlag(argv, "--term", "phase");
-
-  const match = findTerm(await readVocabulary(root), name);
-  if (match === null) {
-    throw new Error(`"${name}" is not in the vocabulary, as a term or as an avoided word`);
-  }
-
-  printJson({ ...match.term, matched: match.matched }, argv);
-}
-
-runHook(() => run(process.argv.slice(2)));

package/skills/task-manager/vocabulary/hooks/list-terms.ts

@@ -1,12 +0,0 @@
-// packages/g3n-skills/skills/task-manager/vocabulary/hooks/list-terms.ts
-import { readVocabulary } from "@task-manager/vocabulary";
-import { printJson, resolveRoot, runHook } from "@task-manager/hooks";
-
-/** Prints every term in the vocabulary. */
-async function run(argv: readonly string[]): Promise<void> {
-  const root = await resolveRoot(argv);
-
-  printJson(await readVocabulary(root), argv);
-}
-
-runHook(() => run(process.argv.slice(2)));

package/skills/task-manager/vocabulary/hooks/remove-term.ts

@@ -1,22 +0,0 @@
-// packages/g3n-skills/skills/task-manager/vocabulary/hooks/remove-term.ts
-import { findTerm, readVocabulary, vocabularyPathFor, writeVocabulary } from "@task-manager/vocabulary";
-import { printJson, requireFlag, resolveRoot, runHook } from "@task-manager/hooks";
-
-/** Removes the term named by `--term` from the vocabulary and prints it. */
-async function run(argv: readonly string[]): Promise<void> {
-  const root = await resolveRoot(argv);
-  const name = requireFlag(argv, "--term", "phase");
-
-  const terms = await readVocabulary(root);
-  const match = findTerm(terms, name);
-
-  if (match === null || match.matched !== "term") {
-    throw new Error(`"${name}" is not a term in the vocabulary`);
-  }
-
-  await writeVocabulary(root, terms.filter((term) => term !== match.term));
-
-  printJson({ file: vocabularyPathFor(root), removed: match.term }, argv);
-}
-
-runHook(() => run(process.argv.slice(2)));

package/skills/task-manager/vocabulary/hooks/set-term.ts

@@ -1,37 +0,0 @@
-// packages/g3n-skills/skills/task-manager/vocabulary/hooks/set-term.ts
-import { findTerm, readVocabulary, vocabularyPathFor, writeVocabulary } from "@task-manager/vocabulary";
-import { printJson, readFlag, requireFlag, resolveRoot, runHook } from "@task-manager/hooks";
-
-/** Splits a comma-separated `--avoid` value into trimmed words; empty when the flag is absent. */
-function splitWords(list: string | undefined): string[] {
-  return list === undefined ? [] : list.split(",").map((word) => word.trim()).filter((word) => word !== "");
-}
-
-/** Adds the term `--term` or replaces its definition and avoided words, and prints the result. */
-async function run(argv: readonly string[]): Promise<void> {
-  const root = await resolveRoot(argv);
-
-  const name = requireFlag(argv, "--term", "phase");
-  const definition = requireFlag(argv, "--definition", '"One step of a plan."');
-  const avoid = splitWords(readFlag(argv, "--avoid"));
-
-  const terms = await readVocabulary(root);
-  const existing = findTerm(terms, name);
-
-  if (existing?.matched === "avoid") {
-    throw new Error(`"${name}" is an avoided word of "${existing.term.term}"; define that term instead`);
-  }
-  for (const word of avoid) {
-    const owner = findTerm(terms, word);
-    if (owner !== null && owner.term !== existing?.term) {
-      throw new Error(`cannot avoid "${word}": it already belongs to the term "${owner.term.term}"`);
-    }
-  }
-
-  const term = { term: existing?.term.term ?? name, definition, avoid };
-  await writeVocabulary(root, [...terms.filter((t) => t !== existing?.term), term]);
-
-  printJson({ file: vocabularyPathFor(root), created: existing === null, ...term }, argv);
-}
-
-runHook(() => run(process.argv.slice(2)));

package/skills/task-manager/vocabulary/references/usage.md

@@ -1,26 +0,0 @@
-# Term hooks — usage
-
-How each hook is called, and what the file they write looks like. This is the disclosed reference for the [`vocabulary`](../SKILL.md) skill.
-
-## Invocations
-
-```bash
-bun <vocabulary-dir>/hooks/get-term.ts --term stage
-bun <vocabulary-dir>/hooks/list-terms.ts --pretty
-bun <vocabulary-dir>/hooks/set-term.ts --term Phase --definition "One step of a plan, holding tasks." --avoid "stage, milestone"
-bun <vocabulary-dir>/hooks/remove-term.ts --term Phase
-```
-
-## The file
-
-`set-term` and `remove-term` rewrite `vocabulary.md` whole, terms sorted by name:
-
-```md
-# Vocabulary
-
-## Phase
-
-One step of a plan, holding tasks.
-
-_Avoid_: stage, milestone
-```

package/skills/task-manager/vocabulary/tsconfig.json

@@ -1,7 +0,0 @@
-{
-  "compilerOptions": {
-    "paths": {
-      "@task-manager/*": ["../task-manager/src/*"]
-    }
-  }
-}