@yegor256/dogent 0.9.1 → 0.11.0

package/src/rules/ordered.js

@@ -0,0 +1,57 @@
+/*
+ * 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');
+
+/**
+ * Ordered.
+ *
+ * Demands a numbered list when order matters. Models follow numbered,
+ * sequentially ordered steps far more reliably than unordered bullets,
+ * and shuffling steps drops accuracy sharply. A standalone checker flags
+ * an unordered bullet item that carries a sequence marker like "first",
+ * "then", "next", "after that", "finally", or "step 2", since the order
+ * is real but the structure hides it. Its prompt hands implicit ordering
+ * with no marker word to the AI oracle.
+ */
+class Ordered {
+  constructor() {
+    this.id = 'ordered';
+  }
+  prompt() {
+    return `${this.id}: flag an implied sequence that no marker word signals, demanding a numbered list whenever the order of steps matters`;
+  }
+  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) {
+    if (!/^\s*[-*+]\s+/u.test(text)) {
+      return [];
+    }
+    const markers = /\b(?:first|second|third|then|next|after that|afterwards|finally|lastly|step\s+\d+)\b/iu;
+    if (!markers.test(mask(text))) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'sequence detected, use a numbered list to fix the order',
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = Ordered;

package/src/rules/persona.js

@@ -0,0 +1,55 @@
+/*
+ * 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');
+
+/**
+ * Persona.
+ *
+ * Flags gratuitous role-play that opens a manifesto with a persona:
+ * "You are a senior engineer", "Act as an expert reviewer", and the
+ * like. The largest controlled study finds personas do not improve task
+ * performance and can hurt, so a role-play line is pure context bloat
+ * that adds no instruction. A standalone checker flags the line whose
+ * head assigns the agent a role; its prompt hands the indirect persona
+ * framing the regex misses to the AI oracle.
+ */
+class Persona {
+  constructor() {
+    this.id = 'persona';
+  }
+  prompt() {
+    return `${this.id}: flag indirect persona or role-play framing that assigns the agent a role with no fixed keyword, since a persona adds no instruction`;
+  }
+  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 regex = /^(?<marker>\s*(?:[-*+]|\d+\.)\s+)?(?:you are an? |act as |imagine you are |pretend to be |as an? \w+,)/iu;
+    const hit = regex.exec(mask(text));
+    if (hit === null) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'persona assignment adds no instruction, delete it',
+      new Region(uri, line, (hit.groups.marker || '').length + 1)
+    )];
+  }
+}
+
+module.exports = Persona;

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/positive.js

@@ -0,0 +1,57 @@
+/*
+ * 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');
+
+/**
+ * Positive.
+ *
+ * Demands positive, goal-oriented imperatives over bans. A standalone
+ * checker flags a line whose head is an obvious prohibition: "do not",
+ * "don't", "never", "avoid", "refrain from", "must not", or "no longer".
+ * A ban forces the model to process the forbidden concept first, so
+ * "Only use real data" beats "Don't use mock data". Its prompt hands
+ * subtler bans, those carrying no head keyword, to the AI
+ * oracle, which rewrites a prohibition with no keyword as a positive
+ * command.
+ */
+class Positive {
+  constructor() {
+    this.id = 'positive';
+  }
+  prompt() {
+    return `${this.id}: flag any instruction phrased as a prohibition, including bans carrying no fixed keyword, and rewrite each as a positive imperative`;
+  }
+  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 regex = /^(?<marker>\s*(?:[-*+]|\d+\.)\s+)?(?:do not|don't|never|avoid|refrain from|must not|no longer)\b/iu;
+    const hit = regex.exec(mask(text));
+    if (hit === null) {
+      return [];
+    }
+    const marker = hit.groups.marker || '';
+    return [new Violation(
+      this.id,
+      'warning',
+      'negative phrasing detected, state the positive command instead',
+      new Region(uri, line, marker.length + 1)
+    )];
+  }
+}
+
+module.exports = Positive;

package/src/rules/pseudo-heading.js

@@ -0,0 +1,55 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * PseudoHeading.
+ *
+ * Rejects a bold line posing as a section heading, such as
+ * "**Setup:**" standing alone. The whole line, once an optional list
+ * marker drops, must sit inside one emphasis run, wrapped by "**" or
+ * "__" and ending in an optional colon. A line carrying only inline
+ * bold inside other words, like "Use **bold** sparingly.", stays free,
+ * since the emphasis wraps a fragment, not the whole label.
+ *
+ * Its prompt hands borderline label-versus-instruction calls to the AI
+ * oracle.
+ */
+class PseudoHeading {
+  constructor() {
+    this.id = 'pseudo-heading';
+  }
+  prompt() {
+    return `${this.id}: flag any bold line posing as a section heading, deferring borderline label-versus-instruction calls to the oracle, and demand a real level-2 "##" heading`;
+  }
+  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 body = text.trim().replace(/^(?:[-*+]|\d+\.)\s+/u, '');
+    if (!/^(?<fence>\*\*|__)(?!\s)(?:.+?)(?<!\s)\k<fence>:?$/u.test(body)) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'bold pseudo-heading found, use a level-2 "##" heading',
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = PseudoHeading;

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/rationale.js

@@ -0,0 +1,54 @@
+/*
+ * 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');
+
+/**
+ * Rationale.
+ *
+ * Demands orders, not explanations. A standalone checker flags a line
+ * that opens with a justification marker such as "because", "the
+ * reason", "this keeps", "this ensures", "this helps", "so that", or
+ * "in order to", since such a line argues a point instead of issuing a
+ * command. Justification belongs in commit messages and design docs, so
+ * its prompt hands subtler explanation-only lines to the AI oracle.
+ */
+class Rationale {
+  constructor() {
+    this.id = 'rationale';
+  }
+  prompt() {
+    return `${this.id}: flag any line that explains a reason, motivation, or benefit instead of issuing a direct order, even when it carries no fixed marker, and convert each into a command or 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 clean = mask(text).replace(/^\s*(?:[-*+]|\d+\.)\s+/u, '');
+    const regex = /^(?:because|the reason|this keeps|this ensures|this helps|so that|in order to)\b/iu;
+    if (!regex.test(clean)) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'rationale carries no command, delete or convert to an order',
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = Rationale;

package/src/rules/referential.js

@@ -0,0 +1,67 @@
+/*
+ * 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');
+
+/**
+ * Referential.
+ *
+ * Demands that every line name its own subject. A standalone checker
+ * flags a line that opens with a bare pronoun acting as the subject:
+ * "it", "they", and "them" always, and "this", "that", "these", or
+ * "those" only when a verb follows rather than a noun, so a determiner
+ * like "These rules stay final" stays clean. Such a pronoun points at a
+ * previous line, breaking the "one line, one instruction" contract. Its
+ * prompt hands the subtler mid-line dangling references to the AI oracle.
+ */
+class Referential {
+  constructor() {
+    this.id = 'referential';
+    this.verbs = new RegExp(
+      '^(?:is|are|was|were|be|been|being|will|would|can|could|shall|' +
+      'should|must|may|might|has|have|had|do|does|did|only|then|runs|' +
+      'run|applies|apply|happens|happen|means|requires|needs|comes|' +
+      'goes|makes|breaks|points|refers)$',
+      'iu'
+    );
+  }
+  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`;
+  }
+  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 regex = /^(?<marker>\s*(?:[-*+]|\d+\.)\s+)?(?<pro>it|this|that|they|them|these|those)\b\s+(?<next>[\w']+)/iu;
+    const hit = regex.exec(mask(text));
+    if (hit === null) {
+      return [];
+    }
+    const pronoun = hit.groups.pro.toLowerCase();
+    const ambiguous = /^(?:this|that|these|those)$/u.test(pronoun);
+    if (ambiguous && !this.verbs.test(hit.groups.next)) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      `pronoun "${hit.groups.pro}" has no antecedent on this line, name the subject`,
+      new Region(uri, line, (hit.groups.marker || '').length + 1)
+    )];
+  }
+}
+
+module.exports = Referential;

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/self-contained.js

@@ -0,0 +1,66 @@
+/*
+ * 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');
+
+/**
+ * SelfContained.
+ *
+ * Demands that every line stand on its own without leaning on its
+ * neighbours. A standalone checker flags a relative cross-reference
+ * phrase like "see above", "as mentioned below", or "the previous
+ * step" that breaks the moment the file is reordered or chunked. A
+ * line pointing somewhere concrete through a markdown link stays
+ * clean. Distinct from referential, which targets bare pronouns; this
+ * one targets positional cross-references. Its prompt hands subtler
+ * dangling references to the AI oracle.
+ */
+class SelfContained {
+  constructor() {
+    this.id = 'self-contained';
+    this.phrase = new RegExp(
+      'mentioned above|mentioned below|see above|see below|' +
+      'as discussed|the section above|the section below|' +
+      'the previous step|as stated earlier|mentioned earlier|' +
+      'refer to the guide',
+      'iu'
+    );
+  }
+  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`;
+  }
+  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);
+    if (clean.includes('](')) {
+      return [];
+    }
+    const hit = this.phrase.exec(clean);
+    if (hit === null) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      `relative reference "${hit[0]}" breaks when reordered, name the target`,
+      new Region(uri, line, hit.index + 1)
+    )];
+  }
+}
+
+module.exports = SelfContained;

package/src/rules/stale.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');
+
+/**
+ * Stale.
+ *
+ * Flags volatile time and version references that rot over time:
+ * words like "currently", "now", "today", "recently", and hardcoded
+ * version literals such as "18.17.0". Each pins an instruction to a
+ * moment or release that drifts, so the manifesto silently ages. The
+ * rule scans only prose, never fenced snippets, so version pins inside
+ * code blocks survive untouched. Its prompt hands implicit time-bound
+ * claims with no keyword to the AI oracle.
+ */
+class Stale {
+  constructor() {
+    this.id = 'stale';
+  }
+  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`;
+  }
+  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(?:currently|now|today|recently|lately|at present|as of|' +
+      'the latest)\\b|\\bv?\\d+\\.\\d+(?:\\.\\d+)?\\b',
+      'giu'
+    );
+    const masked = mask(text);
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'warning',
+        `volatile reference "${hit[0]}" will rot, state a durable rule`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+}
+
+module.exports = Stale;