@g3nomaly/g3n-skills 0.1.0 → 0.1.1

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

@@ -15,10 +15,17 @@ export const TaskSchema = z.strictObject({
   status: StatusSchema,
 });
 
+/**
+ * Frontmatter of one task file, as `TaskSchema` parses it.
+ *
+ * @property worktree - Always `true`: every task is worked in its own git worktree.
+ * @property complexity - Effort from 1 to 5, when set.
+ */
 export type Task = z.infer<typeof TaskSchema>;
 
 export const TaskIndexSchema = z.strictObject({
   tasks: z.array(TaskSchema).default([]),
 });
 
+/** Every task of one phase, as `TaskIndexSchema` parses it. */
 export type TaskIndex = z.infer<typeof TaskIndexSchema>;

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

@@ -16,16 +16,23 @@ export const TermSchema = z.strictObject({
       (text) => !text.split("\n").some((line) => line.startsWith("#") || line.startsWith("_Avoid_:")),
       "must not contain a line starting with # or _Avoid_:",
     ),
-  /** Words that mean the same thing and must not be used in its place */
   avoid: z
     .array(TermNameSchema.refine((word) => !word.includes(","), "must not contain a comma"))
     .default([]),
 });
 
+/**
+ * One entry of `vocabulary.md`, as `TermSchema` parses it.
+ *
+ * @property term - The word to use.
+ * @property definition - What the term means, as written under its heading.
+ * @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({
   terms: z.array(TermSchema).default([]),
 });
 
+/** Every term of `vocabulary.md`, as `VocabularySchema` parses it. */
 export type Vocabulary = z.infer<typeof VocabularySchema>;

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

@@ -1,20 +1,35 @@
 // packages/g3n-skills/skills/task-manager/task-manager/src/schemas/validation.ts
 import { z } from "zod";
 
-/** One rejected field, as `field` reads in the source file. */
+/**
+ * One rejected field of a file, as `parseFile` reports it.
+ *
+ * @property field - Dotted path of the field as it reads in the file, e.g. `phases.0.status`, or `(whole file)`.
+ * @property message - Why the field was rejected, e.g. `is required`.
+ */
 export interface FileValidationIssue {
   field: string;
   message: string;
 }
 
 /**
- * Thrown by `parseFile` when a file on disk does not match its schema.
- * Carries the path that was read so a caller can report it without tracking it.
+ * @brief 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 message
+ * lists them all. Thrown by `parseFile` and by the readers in `filetree/`,
+ * `decisions/` and `vocabulary/` that check a file's layout by hand. Callers
+ * tell it apart from other errors with `instanceof FileValidationError`.
  */
 export class FileValidationError extends Error {
   readonly file: string;
   readonly issues: FileValidationIssue[];
 
+  /**
+   * @brief Builds the message from the file path and every issue.
+   *
+   * @param file - Path of the file that failed, e.g. `/home/me/app/docs/task-manager/auth/auth.md`.
+   * @param issues - Rejected fields, e.g. `{ field: "phases.0.status", message: "is required" }`.
+   */
   constructor(file: string, issues: FileValidationIssue[]) {
     const detail = issues.map((i) => `  ${i.field}: ${i.message}`).join("\n");
     super(`${file} does not match its schema:\n${detail}`);
@@ -24,18 +39,27 @@ export class FileValidationError extends Error {
   }
 }
 
-/** Turns a zod path into the dotted field name a reader can find in the file. */
+/**
+ * @brief Turns a zod issue path into the dotted field name a reader can find in the file.
+ *
+ * @param path - Segments of the issue path, e.g. `["phases", 0, "status"]`.
+ * @returns Dotted name, or `(whole file)` for an empty path.
+ */
 function fieldName(path: ReadonlyArray<PropertyKey>): string {
   if (path.length === 0) return "(whole file)";
   return path.map((segment) => String(segment)).join(".");
 }
 
 /**
- * Checks data read from a file against its schema.
+ * @brief Checks data read from a file against its schema.
+ *
  * Every file read from disk goes through here before it is handed on.
  *
- * @param file path of the file the data came from, used in the error message
- * @throws FileValidationError naming the file and every field that failed
+ * @param schema - Zod schema of the file's layout.
+ * @param file - Path of the file the data came from, used in the error message.
+ * @param data - Raw data read from the file, before validation.
+ * @returns The data as the schema parses it.
+ * @throws FileValidationError naming the file and every field that failed.
  */
 export function parseFile<S extends z.ZodType>(
   schema: S,

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

@@ -10,14 +10,21 @@ const TITLE = "# Vocabulary";
 const TERM_HEADING = "## ";
 const AVOID_PREFIX = "_Avoid_:";
 
+/**
+ * @brief Builds the path of the vocabulary file in a tree.
+ *
+ * @param root - Absolute tree root folder.
+ * @returns Path of `vocabulary.md` inside `root`.
+ */
 export function vocabularyPathFor(root: string): string {
   return join(root, VOCABULARY_FILE);
 }
 
 /**
- * Every term of the tree at `root`, in the order they sit in the file. A tree
- * with no vocabulary file yet has no terms.
+ * @brief Reads every term of the tree at `root`, in the order they sit in the file.
  *
+ * @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
  */
@@ -31,7 +38,12 @@ export async function readVocabulary(root: string): Promise<Term[]> {
   return terms;
 }
 
-/** Replaces the vocabulary file with `terms`, sorted by name so the file reads the same on every write. */
+/**
+ * @brief Replaces the vocabulary file with `terms`, sorted by name so the file reads the same on every write.
+ *
+ * @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;
@@ -44,6 +56,11 @@ export async function writeVocabulary(root: string, terms: readonly Term[]): Pro
   await Bun.write(file, `${[TITLE, ...sorted.map(renderTerm)].join("\n\n")}\n`);
 }
 
+/**
+ * @brief Renders one term as its `## ` block in the vocabulary file.
+ *
+ * @param term - Term to render.
+ */
 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(", ")}`);
@@ -51,7 +68,16 @@ function renderTerm(term: Term): string {
   return lines.join("\n");
 }
 
-/** Splits the file at its `## ` headings; the last `_Avoid_:` line of a block is its avoid list. */
+/**
+ * @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[] }[] = [];
 
@@ -85,6 +111,13 @@ function parseTerms(file: string, text: string): unknown[] {
   });
 }
 
+/**
+ * @brief Throws when two terms share a name, ignoring case.
+ *
+ * @param file - Path of the file, used in the error message.
+ * @param terms - Terms to check.
+ * @throws FileValidationError naming the term that is defined twice.
+ */
 function rejectDuplicates(file: string, terms: readonly Term[]): void {
   const seen = new Set<string>();
 

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

@@ -1,25 +1,42 @@
 // packages/g3n-skills/skills/task-manager/task-manager/src/vocabulary/match.ts
 import type { Term } from "../schemas/term";
 
-/** A term found by name, and whether the name given was the term itself or a word it replaces. */
+/**
+ * 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";
 }
 
-/** A term a text touches, with the exact words that touched it. */
+/**
+ * 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 avoided - Avoided words the text uses in place of `term`.
+ */
 export interface TermMention {
   term: string;
   definition: string;
-  /** Avoided words the text uses in place of `term` */
   avoided: string[];
 }
 
+/** Tells whether two words are equal, ignoring case. */
 function sameWord(a: string, b: string): boolean {
   return a.toLowerCase() === b.toLowerCase();
 }
 
-/** The term answering to `name`, by its own name first and by an avoided word second. */
+/**
+ * @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" };
@@ -28,15 +45,20 @@ export function findTerm(terms: readonly Term[], name: string): TermMatch | null
   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, "\\$&");
   return new RegExp(`(?<![\\p{L}\\p{N}])${escaped}(?![\\p{L}\\p{N}])`, "iu").test(text);
 }
 
 /**
- * Terms `text` uses, by name or by an avoided word, in the order of `terms`.
- * Attached to an entry by the task-manager hooks so the reader gets each
- * definition along with the entry.
+ * @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.
+ *
+ * @param text - Text to search, such as an entry's title, summary and body.
+ * @param terms - Vocabulary to search.
+ * @returns One mention per term the text uses.
  */
 export function termsMentioned(text: string, terms: readonly Term[]): TermMention[] {
   const found: TermMention[] = [];

package/skills/workflow/run/hooks/advance-step.ts

@@ -4,12 +4,24 @@ import { oneOf, printJson, requireFlag, resolveRoot, runHook } from "@task-manag
 import { readPhaseRun, type PhaseRun } from "../src/phase";
 import { PHASE_STATUS_AT, STEPS, stepFor, type Step, type StepState } from "../src/steps";
 
-/** Comma-separated ids of the phase's tasks in any of `statuses`, for an error message. */
+/**
+ * @brief Lists the ids of the phase's tasks in any of `statuses`, comma-separated, for an error message.
+ *
+ * @param run - Phase whose tasks are checked.
+ * @param statuses - Task statuses to match.
+ */
 function idsWith(run: PhaseRun, ...statuses: string[]): string {
   return run.tasks.filter((task) => statuses.includes(task.status)).map((task) => task.id).join(", ");
 }
 
-/** State the phase moves to once `from` is finished, or a stated reason it is not. */
+/**
+ * @brief Works out the state a phase moves to once step `from` is finished.
+ *
+ * @param run - Phase to advance.
+ * @param from - Step being finished.
+ * @returns State the phase moves to.
+ * @throws Error naming the reason when the step cannot be finished yet.
+ */
 function stateAfter(run: PhaseRun, from: Step): StepState {
   const name = run.location.name;
 

package/skills/workflow/run/src/gates.ts

@@ -1,15 +1,26 @@
 // packages/g3n-skills/skills/workflow/run/src/gates.ts
 import type { Phase } from "@task-manager/schemas";
 
-/** A phase that cannot start yet, and the phases it is waiting for. */
+/**
+ * A phase whose gate is closed, and the dependencies it is waiting for.
+ *
+ * @property name - Name of the waiting phase.
+ * @property waiting_on - Dependencies that are not completed yet.
+ */
 export interface WaitingPhase {
   name: string;
   waiting_on: string[];
 }
 
-/** A plan's phases sorted by whether their gate is open. Every list is in queue order. */
+/**
+ * A plan's phases sorted by whether their gate is open. Every list is in queue order.
+ *
+ * @property ready - Phases neither finished nor blocked, whose every dependency is completed.
+ * @property waiting - Phases with at least one dependency not completed yet.
+ * @property blocked - Names of the blocked phases.
+ * @property completed - Names of the completed phases.
+ */
 export interface PlanGates {
-  /** Not finished, not blocked, and every phase it depends on is completed */
   ready: Phase[];
   waiting: WaitingPhase[];
   blocked: string[];
@@ -17,12 +28,14 @@ export interface PlanGates {
 }
 
 /**
- * Sorts a plan's phases by gate. A phase's gate opens once every phase in its
- * `depends_on` is completed. Used by the `ready-phases` hook, which the
- * orchestrator skill calls between phases.
+ * @brief Sorts a plan's phases by gate.
+ *
+ * A phase's gate opens once every phase in its `depends_on` is completed.
+ * Used by the `ready-phases` hook.
  *
- * @param phases every phase of one plan, in queue order
- * @throws Error when a phase depends on a name no phase of the plan has
+ * @param phases - Every phase of one plan, in queue order.
+ * @returns The phases sorted by gate.
+ * @throws Error when a phase depends on a name no phase of the plan has.
  */
 export function gatesFor(phases: readonly Phase[]): PlanGates {
   const statusOf = new Map(phases.map((phase) => [phase.name, phase.status]));

package/skills/workflow/run/src/phase.ts

@@ -3,10 +3,18 @@ import { childDirFor, listEntryNames, locateEntryOfType, readEntry, type EntryLo
 import type { Phase, Task } from "@task-manager/schemas";
 import { stepFor, type StepState } from "./steps";
 
-/** A phase with everything the step hooks report on: its fields, its tasks, its step. */
+/**
+ * A phase with everything the step hooks report on, as `readPhaseRun` builds it.
+ *
+ * @property location - Where the phase sits in the tree.
+ * @property plan - Name of the plan holding the phase.
+ * @property meta - Frontmatter of the phase.
+ * @property body - Markdown body of the phase file.
+ * @property tasks - Tasks of the phase, in queue order.
+ * @property step - Step the phase is on, worked out from its status and its tasks.
+ */
 export interface PhaseRun {
   location: EntryLocation;
-  /** Name of the plan holding the phase */
   plan: string;
   meta: Phase;
   body: string;
@@ -14,7 +22,13 @@ export interface PhaseRun {
   step: StepState;
 }
 
-/** Reads the phase named `name` with its tasks, in queue order, and works out its step. */
+/**
+ * @brief Reads the phase named `name` with its tasks, in queue order, and works out its step.
+ *
+ * @param root - Absolute tree root folder.
+ * @param name - Name of the phase, e.g. `01-schema`.
+ * @returns The phase with its tasks and step.
+ */
 export async function readPhaseRun(root: string, name: string): Promise<PhaseRun> {
   const location = await locateEntryOfType(root, name, "phase");
   const { meta, body } = await readEntry(location.dir, "plan", location.name);

package/skills/workflow/run/src/steps.ts

@@ -4,9 +4,10 @@ import type { TaskStatus } from "@task-manager/schemas/primitives";
 /** The steps a phase is worked through, in order. Each has a workflow skill of the same name. */
 export const STEPS = ["plan", "execute", "review", "sync"] as const;
 
+/** One step a phase is worked through: a member of `STEPS`. */
 export type Step = (typeof STEPS)[number];
 
-/** Where a phase stands: on a step, finished, or stuck on blocked work. */
+/** State a phase stands in: one of the `STEPS`, `done`, or `blocked`. */
 export type StepState = Step | "done" | "blocked";
 
 /** Status a phase carries while it stands at each state. */
@@ -20,9 +21,14 @@ export const PHASE_STATUS_AT: Record<StepState, TaskStatus> = {
 };
 
 /**
- * Step a phase is on, worked out from its own status and its tasks' statuses.
- * Nothing else records the step, so a task sent back from review returns the
- * phase to `execute` without anything being told.
+ * @brief Works out the step a phase is on, from its own status and its tasks' statuses.
+ *
+ * The step is not stored. A task sent back from review therefore returns the
+ * phase to `execute` on its own.
+ *
+ * @param phaseStatus - Status in the phase's frontmatter.
+ * @param taskStatuses - Statuses of the phase's tasks.
+ * @returns The step the phase is on.
  */
 export function stepFor(phaseStatus: TaskStatus, taskStatuses: readonly TaskStatus[]): StepState {
   if (phaseStatus === "completed") return "done";