@yegor256/dogent 0.10.0 → 0.12.0

package/src/rules/referential.js

@@ -31,6 +31,9 @@ class Referential {
       'iu'
     );
   }
+  hint() {
+    return 'Open the line by naming its own subject instead of a bare pronoun, since a dangling pronoun points at another line and breaks one line, one instruction.';
+  }
   prompt() {
     return `${this.id}: flag any line whose subject is a pronoun with no antecedent on the same line, including mid-line dangling references a head pattern misses`;
   }

package/src/rules/scope.js

@@ -0,0 +1,34 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Scope.
+ *
+ * Demands that one SKILL.md stay bound to a single coherent
+ * responsibility. Agent reliability scales with specialisation: a
+ * well-scoped single-stage skill beats a monolith that conflates
+ * unrelated subtasks. Whether the sections cohere or diverge is not
+ * visible line by line, so this check is pure judgement: prompt()
+ * defers the verdict to the AI oracle and violations() finds nothing
+ * on its own.
+ */
+class Scope {
+  constructor() {
+    this.id = 'scope';
+  }
+  hint() {
+    return 'Split a SKILL.md that mixes unrelated responsibilities into separate single-purpose skills, since reliability scales with a narrow scope.';
+  }
+  prompt() {
+    return `${this.id}: in a SKILL.md, judge whether the sections describe a single coherent responsibility or several unrelated ones, and recommend a split when they diverge`;
+  }
+  violations() {
+    return [];
+  }
+}
+
+module.exports = Scope;

package/src/rules/section-level.js

@@ -23,6 +23,9 @@ class SectionLevel {
   constructor() {
     this.id = 'section-level';
   }
+  hint() {
+    return 'Make every section a level-2 heading marked by two hashes, allowing only one optional top-level title to open the file.';
+  }
   prompt() {
     return '';
   }

package/src/rules/self-contained.js

@@ -32,6 +32,9 @@ class SelfContained {
       'iu'
     );
   }
+  hint() {
+    return 'Replace a relative cross-reference such as see above with a concrete named target, so the line survives reordering and chunking.';
+  }
   prompt() {
     return `${this.id}: flag any line leaning on a relative cross-reference such as "see above" that breaks when the file is reordered or chunked, deferring subtler dangling references to the oracle`;
   }

package/src/rules/short-sections.js

@@ -21,6 +21,9 @@ class ShortSections {
   constructor() {
     this.id = 'short-sections';
   }
+  hint() {
+    return 'Trim every section heading to a label of one to three words so the manifesto reads as a map, not as prose.';
+  }
   prompt() {
     return '';
   }

package/src/rules/simple.js

@@ -39,6 +39,9 @@ class Simple {
   constructor() {
     this.id = 'simple';
   }
+  hint() {
+    return 'Split a tangled multi-clause sentence into several short, simple lines so the grammar leaves no room for ambiguity.';
+  }
   prompt() {
     return `${this.id}: flag any grammatically tangled, multi-clause instruction, judging true clause depth even when the line carries few commas or conjunctions`;
   }

package/src/rules/stale.js

@@ -24,6 +24,9 @@ class Stale {
   constructor() {
     this.id = 'stale';
   }
+  hint() {
+    return 'Replace a volatile time or version reference such as currently or a pinned version number with a durable rule that never rots.';
+  }
   prompt() {
     return `${this.id}: flag any implicit time-bound or version-bound claim that carries no keyword, and propose a durable rule that never rots`;
   }

package/src/rules/terms.js

@@ -29,6 +29,9 @@ class Terms {
       ['function', 'method', 'routine']
     ];
   }
+  hint() {
+    return 'Pick one canonical term for each concept and use it everywhere, since naming the same idea two ways makes the agent guess they differ.';
+  }
   prompt() {
     return `${this.id}: flag any pair of words used interchangeably for one concept, and demand a single canonical term across the whole file`;
   }

package/src/rules/token-count.js

@@ -21,6 +21,9 @@ class TokenCount {
     this.id = 'token-count';
     this.cap = cap;
   }
+  hint() {
+    return 'Cut bloated wording across the file so its total token count fits the cap, keeping every instruction terse.';
+  }
   prompt() {
     return `${this.id}: flag bloated wording that wastes the context budget`;
   }

package/src/rules/tool-clarity.js

@@ -23,6 +23,9 @@ class ToolClarity {
   constructor() {
     this.id = 'tool-clarity';
   }
+  hint() {
+    return 'Name the exact tool, path, or invocation instead of a generic noun like the script, so the agent never guesses which one to run.';
+  }
   prompt() {
     return `${this.id}: flag any vague reference to a tool or command beyond the fixed list, and demand the exact name, path, or invocation instead`;
   }

package/src/rules/transition.js

@@ -0,0 +1,62 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+const mask = require('../mask');
+
+/**
+ * Transition.
+ *
+ * Flags a discourse connector that opens an instruction, like
+ * "furthermore", "in summary", or "however". A leading connector
+ * chains prose without adding a command, so it earns one violation.
+ * The check stays disjoint from the polite rule: it lists no courtesy
+ * word such as "please" or "make sure to". Its prompt hands looser
+ * connective filler to the AI oracle for deletion.
+ */
+class Transition {
+  constructor() {
+    this.id = 'transition';
+  }
+  hint() {
+    return 'Delete a discourse connector such as furthermore or however that opens a line, since it chains prose without adding a command.';
+  }
+  prompt() {
+    return `${this.id}: flag connective filler beyond the fixed list, and delete it`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const masked = mask(text);
+    const [lead] = masked.match(/^\s*(?:[-*+]|\d+\.)?\s*/u);
+    const rest = masked.slice(lead.length);
+    const regex = /^(?:furthermore|moreover|additionally|in summary|in conclusion|in other words|as you can see|of course|basically|essentially|that said|however)\b/iu;
+    const hit = regex.exec(rest);
+    if (hit === null) {
+      return [];
+    }
+    return [
+      new Violation(
+        this.id,
+        'warning',
+        `discourse transition "${hit[0]}" adds no instruction, delete it`,
+        new Region(uri, line, lead.length + 1)
+      )
+    ];
+  }
+}
+
+module.exports = Transition;

package/src/rules/unfinished.js

@@ -25,6 +25,9 @@ class Unfinished {
   constructor() {
     this.id = 'unfinished';
   }
+  hint() {
+    return 'Resolve every leftover marker such as TODO, a placeholder, or a trailing ellipsis, since they signal half-finished work.';
+  }
   prompt() {
     return '';
   }

package/src/rules/unique.js

@@ -31,6 +31,9 @@ class Unique {
   constructor() {
     this.id = 'unique';
   }
+  hint() {
+    return 'Remove the repeated instruction and state each rule once, since duplicated guidance wastes context and can drift out of sync.';
+  }
   prompt() {
     return `${this.id}: flag any instruction that repeats another instruction in the file, including two lines that carry the same meaning in different words, not only lines matching after normalized case, punctuation, and word order`;
   }

package/src/rules/units.js

@@ -0,0 +1,84 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+const mask = require('../mask');
+
+/**
+ * Units.
+ *
+ * Demands that every magnitude carry a unit so the reader knows what
+ * the number measures. A bare cardinal like "under 80" leaves the
+ * scale implicit; "under 80 symbols" states it. The checker masks
+ * inline code first, then scans each run of digits and flags one that
+ * names no unit, skipping percentages, units already present, decimals
+ * and versions, and leading list ordinals. Distinct from quantifier,
+ * which targets vague amount words like "several"; here the number is
+ * exact but its unit is missing.
+ */
+class Units {
+  constructor() {
+    this.id = 'units';
+    this.unit = new RegExp(
+      '^ ?(?:ms|s|sec|secs|second|seconds|min|mins|minute|minutes|' +
+      'h|hr|hrs|hour|hours|d|day|days|week|weeks|month|months|' +
+      'year|years|b|kb|mb|gb|tb|byte|bytes|bit|bits|char|chars|' +
+      'character|characters|symbol|symbols|line|lines|word|words|' +
+      'token|tokens|px|em|rem|pt|time|times|x)\\b',
+      'u'
+    );
+  }
+  hint() {
+    return 'State the unit beside every magnitude, such as 80 symbols, so the reader knows what the number measures.';
+  }
+  prompt() {
+    return `${this.id}: flag a magnitude whose unit is implicit even in context, and state what it measures`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const clean = mask(text);
+    const found = [];
+    const digits = /\d+/gu;
+    let hit = digits.exec(clean);
+    while (hit !== null) {
+      if (!this.skip(clean, hit)) {
+        found.push(new Violation(
+          this.id,
+          'warning',
+          `number "${hit[0]}" has no unit, state what it measures`,
+          new Region(uri, line, hit.index + 1)
+        ));
+      }
+      hit = digits.exec(clean);
+    }
+    return found;
+  }
+  skip(clean, hit) {
+    const after = clean.slice(hit.index + hit[0].length);
+    if (after.startsWith('%') || this.unit.test(after)) {
+      return true;
+    }
+    const before = clean.charAt(hit.index - 1);
+    if (/[.v@\d]/u.test(before) || /^\.\d/u.test(after)) {
+      return true;
+    }
+    const lead = /^\s*(?<num>\d+)\.\s/u.exec(clean);
+    return lead !== null && lead.index + lead[0].indexOf(lead.groups.num) === hit.index;
+  }
+}
+
+module.exports = Units;

package/src/rules/untrusted.js

@@ -26,6 +26,9 @@ class Untrusted {
   constructor() {
     this.id = 'untrusted';
   }
+  hint() {
+    return 'Add a data-only guard when an instruction consumes external content, telling the agent to treat it as untrusted and never follow embedded instructions.';
+  }
   prompt() {
     return `${this.id}: judge whether a consumed source is genuinely untrusted external input and whether its data-only guard is sufficient against prompt injection`;
   }

package/src/rules/vague.js

@@ -24,6 +24,9 @@ class Vague {
   constructor() {
     this.id = 'vague';
   }
+  hint() {
+    return 'Replace a subjective qualifier such as properly or clean with a concrete, checkable threshold the agent can measure.';
+  }
   prompt() {
     return `${this.id}: flag any subjective or unmeasurable qualifier beyond the fixed list, and propose a concrete, checkable threshold to replace it`;
   }

package/src/rules/weak-verb.js

@@ -0,0 +1,65 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+const mask = require('../mask');
+
+/**
+ * Weak verb.
+ *
+ * Flags a leading imperative that names no concrete action: "handle",
+ * "manage", "process", "support", "ensure", "maintain", "deal with",
+ * "take care of", "work on". Each tells the agent to do something
+ * unspecified, so the line carries no real instruction. The check fires
+ * only on the first word of the line, leaving the same verb mid-sentence
+ * alone, and stays apart from "vague" (adjectives) and "command"
+ * (imperative form). Its prompt hands subtler catch-all verbs outside
+ * the fixed list to the AI oracle.
+ */
+class WeakVerb {
+  constructor() {
+    this.id = 'weak-verb';
+  }
+  hint() {
+    return 'Replace a vague leading verb such as handle or manage with a precise action verb that names exactly what to do.';
+  }
+  prompt() {
+    return `${this.id}: flag a leading imperative verb that names no concrete action beyond the fixed list, and propose a precise action verb`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const masked = mask(text);
+    const regex = new RegExp(
+      '^(?<lead>\\s*(?:[-*+]|\\d+\\.)?\\s*)' +
+      '(?<verb>handle|manage|process|support|ensure|maintain|' +
+      'deal with|take care of|work on)\\b',
+      'iu'
+    );
+    const hit = regex.exec(masked);
+    if (hit === null) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      `weak verb "${hit.groups.verb}" names no concrete action, use a precise verb`,
+      new Region(uri, line, hit.groups.lead.length + 1)
+    )];
+  }
+}
+
+module.exports = WeakVerb;

package/src/sources.js

@@ -26,6 +26,9 @@ class Sources {
   files() {
     const found = [];
     this.paths.forEach((entry) => {
+      if (!fs.existsSync(entry)) {
+        throw new Error(`No such file or directory: ${entry}`);
+      }
       if (fs.statSync(entry).isDirectory()) {
         this.scan(entry, found);
       } else {

package/src/version.js

@@ -9,8 +9,8 @@
  * Version.
  *
  * The current release of dogent, replaced on every release by rultor.
- * The default `0.10.0` marks an unreleased build straight from source.
+ * The default `0.12.0` marks an unreleased build straight from source.
  */
-const version = '0.10.0';
+const version = '0.12.0';
 
 module.exports = version;