@yegor256/dogent 0.10.0 → 0.11.0

package/src/rules/placement.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');
+
+/**
+ * Placement.
+ *
+ * Transformers attend most to the start and the end of their input and
+ * skim the middle, so a critical section buried in the middle third of a
+ * manifesto sits exactly where the model is least likely to use it. This
+ * standalone check spots a critical section by a heading keyword (Safety,
+ * Security, Mission, Critical, Constraints) and warns when it lands in
+ * the middle third rather than near the top or bottom. The generic word
+ * "Rules" is left out on purpose: it names a neutral section in many
+ * manifestos and would misfire. Its prompt hands the deeper judgement to
+ * the AI oracle, which weighs which instruction matters most and whether
+ * it is well placed.
+ */
+class Placement {
+  constructor() {
+    this.id = 'placement';
+    this.keyword = /^#{1,6}\s+.*\b(?:safety|security|mission|critical|constraints?)\b/iu;
+  }
+  prompt() {
+    return `${this.id}: identify the single most important instruction and judge whether it sits near the top or bottom of the file rather than buried in the middle`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    const total = document.text().split('\n').length;
+    return document.walk({
+      header: (text, row) => this.check(text, row, total, uri),
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  check(text, row, total, uri) {
+    if (!this.keyword.test(text)) {
+      return [];
+    }
+    const ratio = row / total;
+    if (ratio <= 1 / 3 || ratio >= 2 / 3) {
+      return [];
+    }
+    const name = text.replace(/^#+\s*/u, '').trim();
+    return [new Violation(
+      this.id,
+      'warning',
+      `critical section "${name}" is buried, move it to the top or bottom`,
+      new Region(uri, row, 1)
+    )];
+  }
+}
+
+module.exports = Placement;

package/src/rules/quantifier.js

@@ -0,0 +1,63 @@
+/*
+ * 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');
+
+/**
+ * Quantifier.
+ *
+ * Flags vague quantity words that leave the count to the agent: "some",
+ * "several", "a few", "many", "multiple", and the like. Models track
+ * exact quantifiers well yet diverge from human intent on vague ones,
+ * whose meaning is an underspecified distribution rather than a number,
+ * so a command manifesto should state the exact count or threshold. The
+ * list is kept apart from the vague qualifiers so the two rules never
+ * double-report. Its prompt hands implicit vagueness, where no listed
+ * word appears, to the AI oracle.
+ */
+class Quantifier {
+  constructor() {
+    this.id = 'quantifier';
+  }
+  prompt() {
+    return `${this.id}: flag a vague amount that names no exact count even without a listed word, and propose a concrete number or threshold to replace 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 found = [];
+    const regex = new RegExp(
+      '\\b(?:some|several|a few|a couple|many|multiple|various|' +
+      'numerous|a lot of|plenty of)\\b',
+      'giu'
+    );
+    const masked = mask(text);
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'warning',
+        `vague quantity "${hit[0]}", state an exact number or threshold`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+}
+
+module.exports = Quantifier;

package/src/rules/scope.js

@@ -0,0 +1,31 @@
+/*
+ * 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';
+  }
+  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/transition.js

@@ -0,0 +1,59 @@
+/*
+ * 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';
+  }
+  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/units.js

@@ -0,0 +1,81 @@
+/*
+ * 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'
+    );
+  }
+  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/weak-verb.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');
+
+/**
+ * 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';
+  }
+  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/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.11.0` marks an unreleased build straight from source.
  */
-const version = '0.10.0';
+const version = '0.11.0';
 
 module.exports = version;