@yegor256/dogent 0.6.1 → 0.7.0

package/README.md

@@ -76,8 +76,19 @@ The command exits with a non-zero status when problems are found,
 - Every sentence must start with a capital and end with a period.
 - No articles, no noise, no bloated text.
 - Simple grammar, no ambiguity.
+- No tangled, multi-clause instructions.
+- A `SKILL.md` `name` must equal its parent directory.
+- No courtesy or scaffolding words.
+- No leftover markers or unfilled placeholders.
+- A section must hold at most ten instructions.
+- A `SKILL.md` `description` must say when to use the skill.
+- Every line must carry exactly one instruction.
+- No hedging or soft wording.
+- No passive voice; use the active imperative.
+- No instruction may repeat another.
 - `SKILL.md` must open with valid frontmatter.
 - Frontmatter must declare only allowed keys.
+- A `SKILL.md` `name` must be kebab-case.
 
 ## AI verification
 
@@ -90,6 +101,9 @@ It sends the manifesto together with one instruction per rule,
   then prints any violation the model reports for ambiguity,
   weak phrasing, and instructions that only pretend to be commands.
 The model defaults to `gpt-4o-mini`; override it with `OPENAI_MODEL`.
+After the report, `dogent` prints a one-line usage summary to standard error,
+  naming the model, the tokens sent and received, and an estimated cost,
+  for example `OpenAI: gpt-4o-mini, 1234 sent, 567 received, ~$0.0005`.
 
 ```bash
 export OPENAI_API_KEY=...

package/package.json

@@ -40,5 +40,8 @@
     "lint": "eslint .",
     "test": "mocha 'test/**/*.js' --timeout 60000"
   },
-  "version": "0.6.1"
+  "version": "0.7.0",
+  "dependencies": {
+    "minimist": "^1.2.8"
+  }
 }

package/src/answer.js

@@ -8,16 +8,22 @@
 const Violation = require('./violation');
 const Region = require('./region');
 
+const FLOOR = 0.6;
+
 /**
  * Answer.
  *
  * The oracle's raw reply, treated as untrusted input. Parses the JSON
  * object it carries and turns every well-formed SARIF result back into a
- * native violation, ignoring any result it cannot read.
+ * native violation, ignoring any result it cannot read. Drops a result
+ * whose self-reported confidence sits below the floor, so the model's
+ * own doubt filters out its guesses; a result without a confidence is
+ * trusted and kept.
  */
 class Answer {
-  constructor(raw) {
+  constructor(raw, floor = FLOOR) {
     this.raw = raw;
+    this.floor = floor;
   }
   violations() {
     return this.results().flatMap((result) => {
@@ -27,6 +33,9 @@ class Answer {
       if (typeof line !== 'number' || typeof text !== 'string' || !spot.artifactLocation) {
         return [];
       }
+      if (typeof result.confidence === 'number' && result.confidence < this.floor) {
+        return [];
+      }
       return [new Violation(
         result.ruleId || 'oracle',
         result.level || 'warning',

package/src/args.js

@@ -5,32 +5,35 @@
 
 'use strict';
 
+const minimist = require('minimist');
+
 /**
  * Args.
  *
- * The command-line arguments handed to dogent. It splits the raw argv into
- * recognized options and the manifesto paths that remain. The `--sarif`
- * flag switches the report to SARIF, while `--offline` forbids any talk to
- * the LLM even when a token sits in the environment.
+ * The command-line arguments handed to dogent. It leans on minimist to split
+ * the raw argv into recognized options and the manifesto paths that remain.
+ * The `--sarif` flag switches the report to SARIF, while `--offline` forbids
+ * any talk to the LLM even when a token sits in the environment. Everything
+ * after a `--` separator counts as a path, never as an option.
  */
 class Args {
-  constructor(argv, flags = ['--sarif', '--offline']) {
-    this.argv = argv;
+  constructor(argv, flags = ['sarif', 'offline']) {
     this.flags = flags;
+    this.parsed = minimist(argv, {boolean: flags, '--': true});
   }
   sarif() {
-    return this.argv.includes('--sarif');
+    return this.parsed.sarif === true;
   }
   offline() {
-    return this.argv.includes('--offline');
+    return this.parsed.offline === true;
   }
   paths() {
-    return this.argv.filter((arg) => !arg.startsWith('-'));
+    return this.parsed._.concat(this.parsed['--']).map(String);
   }
   unknown() {
-    return this.argv.filter(
-      (arg) => arg.startsWith('-') && !this.flags.includes(arg)
-    );
+    return Object.keys(this.parsed)
+      .filter((key) => key !== '_' && key !== '--' && !this.flags.includes(key))
+      .map((key) => `${key.length === 1 ? '-' : '--'}${key}`);
   }
 }
 

package/src/dogent.js

@@ -13,6 +13,7 @@ const Report = require('./report');
 const Sources = require('./sources');
 const Openai = require('./openai');
 const Oracle = require('./oracle');
+const Usage = require('./usage');
 const rules = require('./rules');
 
 const args = new Args(process.argv.slice(2));
@@ -41,27 +42,43 @@ documents.forEach((document) => {
   });
 });
 const key = process.env.OPENAI_API_KEY;
+const audit = async (docs) => {
+  const oracle = new Oracle(
+    rules(),
+    new Openai(
+      key,
+      process.env.OPENAI_MODEL || 'gpt-4o-mini',
+      (url, options) => globalThis.fetch(url, options)
+    )
+  );
+  const replies = await Promise.all(docs.map((doc) => oracle.violations(doc)));
+  return replies.reduce(
+    (acc, reply) => ({
+      extra: acc.extra.concat(reply.found),
+      usage: acc.usage.plus(reply.usage)
+    }),
+    {extra: [], usage: new Usage('', 0, 0)}
+  );
+};
+const finish = (usage) => {
+  const report = new Report('dogent', found);
+  process.stdout.write(`${sarif ? JSON.stringify(report.sarif(), null, 2) : report.text()}\n`);
+  if (usage !== null) {
+    process.stderr.write(`${usage.text()}\n`);
+  }
+  process.exit(report.count() > 0 ? 1 : 0);
+};
 (async () => {
+  let usage = null;
   if (found.length === 0 && key && !args.offline()) {
     try {
-      const oracle = new Oracle(
-        rules(),
-        new Openai(
-          key,
-          process.env.OPENAI_MODEL || 'gpt-4o-mini',
-          (url, options) => globalThis.fetch(url, options)
-        )
-      );
-      const extra = await Promise.all(
-        documents.map((document) => oracle.violations(document))
-      );
-      extra.forEach((bag) => bag.forEach((violation) => found.push(violation)));
+      const result = await audit(documents);
+      result.extra.forEach((violation) => found.push(violation));
+      ({usage} = result);
     } catch (error) {
       process.stderr.write(`AI verification failed: ${error.message}\n`);
       process.exit(2);
     }
   }
-  const report = new Report('dogent', found);
-  process.stdout.write(`${sarif ? JSON.stringify(report.sarif(), null, 2) : report.text()}\n`);
-  process.exit(report.count() > 0 ? 1 : 0);
+  finish(usage);
 })();

package/src/markdown.js

@@ -42,7 +42,8 @@ class Markdown {
         items = [];
       }
     };
-    const lines = this.content.split('\n');
+    const body = this.content.replace(/\r\n?/gu, '\n');
+    const lines = body.split('\n');
     let skip = 0;
     if (lines[0].trim() === '---') {
       const rest = lines.slice(1);
@@ -98,7 +99,7 @@ class Markdown {
     if (fence !== '') {
       pieces.push(new Snippet(block.join('\n'), opened));
     }
-    return new Document(this.address, pieces, this.content);
+    return new Document(this.address, pieces, body);
   }
 }
 

package/src/openai.js

@@ -5,11 +5,14 @@
 
 'use strict';
 
+const Usage = require('./usage');
+
 /**
  * Openai.
  *
  * A thin adapter over the OpenAI chat-completions endpoint. Sends one
- * prompt, demands a JSON object back, and returns the assistant text.
+ * prompt, demands a JSON object back, and returns the assistant text
+ * paired with a Usage tally of the model and the tokens it consumed.
  * The transport is injected so the class runs in tests without a socket.
  */
 class Openai {
@@ -38,7 +41,16 @@ class Openai {
     if (!response.ok) {
       throw new Error(`OpenAI request rejected with status ${response.status}`);
     }
-    return (await response.json()).choices[0].message.content;
+    const body = await response.json();
+    const usage = body.usage || {};
+    return {
+      content: body.choices[0].message.content,
+      usage: new Usage(
+        this.model,
+        usage.prompt_tokens || 0,
+        usage.completion_tokens || 0
+      )
+    };
   }
 }
 

package/src/oracle.js

@@ -13,7 +13,8 @@ const Answer = require('./answer');
  *
  * The AI second opinion. Wraps the rules and a chat endpoint, builds one
  * prompt from a document, asks the endpoint, and parses the reply into
- * violations. Mirrors a rule, but consults a model instead of guessing.
+ * violations paired with the token usage the model reported. Mirrors a
+ * rule, but consults a model instead of guessing.
  */
 class Oracle {
   constructor(rules, chat) {
@@ -21,9 +22,11 @@ class Oracle {
     this.chat = chat;
   }
   async violations(document) {
-    return new Answer(
-      await this.chat.answer(new Prompt(this.rules, document).text())
-    ).violations();
+    const reply = await this.chat.answer(new Prompt(this.rules, document).text());
+    return {
+      found: new Answer(reply.content).violations(),
+      usage: reply.usage
+    };
   }
 }
 

package/src/prompt.js

@@ -25,14 +25,35 @@ class Prompt {
     return [
       'You are a strict linter for an AI-agent manifesto.',
       `The file under review is "${uri}".`,
+      'The manifesto is written in a terse house style: each line is',
+      'one compressed imperative command, with articles and filler',
+      'words deliberately stripped. Read the first word of every line',
+      'as an imperative verb, so "Tag release before shipping" is the',
+      'order "tag the release", not a noun phrase about a tag. Never',
+      'flag a line for being short, for dropping articles, or for',
+      'omitting a subject; that compression is the required style.',
+      'A heading opens a section, and every line beneath it, until the',
+      'next heading, belongs to that section. Treat a deeper heading as',
+      'a subsection of the one above, never as a misplaced instruction.',
       'Apply only the checks listed below this header.',
-      'Report a violation only when it is clear and certain.',
-      'When in doubt, stay silent and report nothing.',
+      'Most manifestos are clean. An empty result list is the normal,',
+      'expected reply: when no line clearly breaks a listed check,',
+      'report nothing and return {"results": []}. Never invent a',
+      'violation to seem useful, and never flag a line merely for',
+      'sitting in a plain, on-topic section.',
+      'One clash is never a false alarm: when two lines give the same',
+      'order twice, or demand opposite things, report each offending',
+      'line with high confidence, even while every other check stays',
+      'conservative. A clean file has no such clash and stays silent.',
+      'Report a violation only when you are certain it breaks a check.',
+      'Give every result a "confidence" number from 0 to 1, your own',
+      'probability that the violation is real, and omit any result you',
+      'score below 0.6. When unsure, lower the confidence, never guess.',
       'Reply with one JSON object and nothing else, shaped as',
       '{"results":[ ... ]}, where each item is a SARIF result with',
-      'keys ruleId, level "warning", message.text, and locations.',
-      'Set ruleId to the rule name and startLine to the printed',
-      'line number; locations[0].physicalLocation must carry',
+      'keys ruleId, level "warning", message.text, confidence, and',
+      'locations. Set ruleId to the rule name and startLine to the',
+      'printed line number; locations[0].physicalLocation must carry',
       `artifactLocation.uri "${uri}" and region.startColumn 1.`
     ].join('\n');
   }
@@ -43,9 +64,11 @@ class Prompt {
       .join('\n');
   }
   body() {
-    return this.doc
-      .text()
-      .split('\n')
+    const lines = this.doc.text().split('\n');
+    if (lines.length > 0 && lines[lines.length - 1] === '') {
+      lines.pop();
+    }
+    return lines
       .map((line, index) => `${index + 1}: ${line}`)
       .join('\n');
   }

package/src/rules/atomic.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');
+
+/**
+ * Atomic.
+ *
+ * Demands that every line carry exactly one instruction. A standalone
+ * checker only spots the loud signs: a sentence terminator sitting
+ * mid-line with more text after it, or two verb phrases welded together
+ * with a semicolon, an " and ", or a " then ". The prompt hands the
+ * subtler clause-counting to the AI oracle.
+ *
+ * @todo #21:45min Upgrade to a real clause-count check through an AI
+ *  oracle so that subtle multi-instruction lines, which the conservative
+ *  heuristic cannot see today, are reliably caught, as requested in
+ *  issue #21.
+ */
+class Atomic {
+  constructor() {
+    this.id = 'atomic';
+  }
+  prompt() {
+    return `${this.id}: flag any line that carries more than one instruction`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.judge(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  judge(text, line, uri) {
+    const clean = text.replace(/^\s*(?:[-*+]|\d+\.)\s+/u, '').trimEnd();
+    const welded = /;|\s(?:and|then)\s+[a-z]+\s+\S/u;
+    if (!/[.!?]\s+\S/u.test(clean) && !welded.test(clean)) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'line carries more than one instruction',
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = Atomic;

package/src/rules/command.js

@@ -21,7 +21,7 @@ class Command {
     this.id = 'command';
   }
   prompt() {
-    return `${this.id}: flag any line that reads as a description, a question, or a plain statement rather than a direct order`;
+    return `${this.id}: flag any line that reads as a description, a question, or a plain statement rather than a direct order; a line opening with a base-form imperative verb, such as "Write", "Strip", "Drop", or "Keep", is itself a direct order and must never be flagged`;
   }
   violations(document) {
     const uri = document.uri();

package/src/rules/consistent.js

@@ -0,0 +1,30 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Consistent.
+ *
+ * Demands that the manifesto never say one thing twice nor say two
+ * things that fight each other. A duplicate instruction wastes the
+ * context budget; a contradictory pair leaves the agent guessing which
+ * order wins. Neither is visible line by line, so this check is pure
+ * judgement: prompt() hands the whole comparison to the AI oracle and
+ * violations() finds nothing on its own.
+ */
+class Consistent {
+  constructor() {
+    this.id = 'consistent';
+  }
+  prompt() {
+    return `${this.id}: flag an instruction that repeats another instruction word for word, or that directly contradicts another instruction in the same file`;
+  }
+  violations() {
+    return [];
+  }
+}
+
+module.exports = Consistent;

package/src/rules/crowded.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');
+
+/**
+ * Crowded.
+ *
+ * Demands that every section stay small, holding no more instructions
+ * than the limit allows. A section runs from one heading to the next
+ * heading or to end-of-file; its instructions are the prose lines that
+ * sit between them. Prose before the first heading is loose and belongs
+ * to the grouped rule, so this rule ignores it.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class Crowded {
+  constructor(limit) {
+    this.id = 'crowded';
+    this.limit = limit;
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    const marks = document.walk({
+      header: (text, line) => [{header: true, line}],
+      prose: (text, line) => [{header: false, line}],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+    const result = [];
+    let open = null;
+    let count = 0;
+    marks.forEach((mark) => {
+      if (mark.header) {
+        this.flush(open, count, uri, result);
+        open = mark;
+        count = 0;
+      } else if (open) {
+        count += 1;
+      }
+    });
+    this.flush(open, count, uri, result);
+    return result;
+  }
+  flush(open, count, uri, result) {
+    if (open && count > this.limit) {
+      result.push(new Violation(
+        this.id,
+        'error',
+        `section holds ${count} instructions, limit ${this.limit}`,
+        new Region(uri, open.line, 1)
+      ));
+    }
+  }
+}
+
+module.exports = Crowded;

package/src/rules/description-triggers.js

@@ -0,0 +1,64 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * DescriptionTriggers.
+ *
+ * Demands that a SKILL.md description say when to use the skill. A
+ * standalone checker can only approximate: it flags a value that is too
+ * short or that never names a trigger with the word "when". Its prompt
+ * hands the deeper judgement to the AI oracle.
+ *
+ * @todo #19:30min Upgrade the trigger check to an AI oracle that judges
+ *  whether the description truly names the situations and user phrases
+ *  that should activate the skill, as requested in issue #19.
+ */
+class DescriptionTriggers {
+  constructor() {
+    this.id = 'description-triggers';
+    this.minimum = 20;
+  }
+  prompt() {
+    return `${this.id}: in a SKILL.md, flag a description that is too short or never says when to use the skill`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const pairs = document.walk({
+      header: () => [],
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: (keys) => keys
+    });
+    const found = pairs.filter((pair) => pair.key === 'description');
+    if (found.length === 0) {
+      return [];
+    }
+    return this.judge(found[0], uri);
+  }
+  judge(pair, uri) {
+    const value = pair.value.trim();
+    if (value.length < this.minimum) {
+      return [this.flag('description too short', pair.row, uri)];
+    }
+    if (!/\bwhen\b/iu.test(value)) {
+      return [this.flag('description must say when to use the skill', pair.row, uri)];
+    }
+    return [];
+  }
+  flag(message, row, uri) {
+    return new Violation(this.id, 'warning', message, new Region(uri, row, 1));
+  }
+}
+
+module.exports = DescriptionTriggers;

package/src/rules/grouped.js

@@ -13,13 +13,16 @@ const Region = require('../region');
  *
  * Demands that every instruction live under a section. Any prose that
  * appears before the first heading is loose and therefore a violation.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
  */
 class Grouped {
   constructor() {
     this.id = 'grouped';
   }
   prompt() {
-    return `${this.id}: flag any instruction that sits under a section where it does not belong`;
+    return '';
   }
   violations(document) {
     const uri = document.uri();

package/src/rules/hedging.js

@@ -0,0 +1,61 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * Hedging.
+ *
+ * Flags soft, non-committal, or hedging wording that weakens an order.
+ * Catches words like "should", "just", "usually", and phrases like
+ * "try to" or "if possible", each a sign of timid instruction.
+ *
+ * @todo #22:30min Upgrade to an AI oracle that catches subtler hedging,
+ *  such as conditional escape hatches and vague scope, which the fixed
+ *  blacklist of hedge words cannot detect today, as requested in
+ *  issue #22.
+ */
+class Hedging {
+  constructor() {
+    this.id = 'hedging';
+  }
+  prompt() {
+    return `${this.id}: flag soft, non-committal, or hedging wording`;
+  }
+  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(?:should|try to|if possible|as appropriate|as needed|' +
+      'when necessary|usually|generally|etc|just|simply|very)\\b',
+      'giu'
+    );
+    let hit = regex.exec(text);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'warning',
+        `hedge word "${hit[0]}" must be removed`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = regex.exec(text);
+    }
+    return found;
+  }
+}
+
+module.exports = Hedging;

package/src/rules/index.js

@@ -14,8 +14,20 @@ const NoArticles = require('./no-articles');
 const Command = require('./command');
 const Punctuation = require('./punctuation');
 const Frontmatter = require('./frontmatter');
+const NameFormat = require('./name-format');
 const DeadImport = require('./dead-import');
 const Redundant = require('./redundant');
+const NameMatchesDir = require('./name-matches-dir');
+const Polite = require('./polite');
+const Unfinished = require('./unfinished');
+const Crowded = require('./crowded');
+const DescriptionTriggers = require('./description-triggers');
+const Atomic = require('./atomic');
+const Hedging = require('./hedging');
+const Passive = require('./passive');
+const Unique = require('./unique');
+const Consistent = require('./consistent');
+const Simple = require('./simple');
 
 module.exports = () => [
   new Grouped(),
@@ -28,9 +40,21 @@ module.exports = () => [
   new Punctuation(),
   new DeadImport(),
   new Redundant(),
+  new Consistent(),
+  new Simple(),
+  new NameMatchesDir(),
+  new Polite(),
+  new Unfinished(),
+  new Crowded(10),
+  new DescriptionTriggers(),
+  new Atomic(),
+  new Hedging(),
+  new Passive(),
+  new Unique(),
   new Frontmatter(
     'SKILL.md',
     ['name', 'description'],
     ['name', 'description', 'license', 'allowed-tools']
-  )
+  ),
+  new NameFormat()
 ];

package/src/rules/line-length.js

@@ -13,6 +13,9 @@ const Region = require('../region');
  *
  * Demands that every instruction and every heading stay within a
  * maximum width. Code snippets are exempt, since code is not prose.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
  */
 class LineLength {
   constructor(max) {
@@ -20,7 +23,7 @@ class LineLength {
     this.max = max;
   }
   prompt() {
-    return `${this.id}: flag any instruction too wordy to grasp in a single read`;
+    return '';
   }
   violations(document) {
     const uri = document.uri();

package/src/rules/name-format.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');
+
+/**
+ * NameFormat.
+ *
+ * Demands that a SKILL.md frontmatter "name" read as kebab-case: lower
+ * letters and digits joined by single hyphens, no leading or trailing
+ * hyphen. Ignores every other file and leaves a missing name to the
+ * frontmatter rule.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class NameFormat {
+  constructor() {
+    this.id = 'name-format';
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const blocks = document.walk({
+      header: () => [],
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: (pairs) => [pairs]
+    });
+    if (blocks.length === 0) {
+      return [];
+    }
+    return this.check(blocks[0].find((pair) => pair.key === 'name'), uri);
+  }
+  check(name, uri) {
+    if (!name || /^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(name.value)) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'error',
+      `name "${name.value}" must be kebab-case`,
+      new Region(uri, name.row, 1)
+    )];
+  }
+}
+
+module.exports = NameFormat;

package/src/rules/name-matches-dir.js

@@ -0,0 +1,61 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const path = require('path');
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * NameMatchesDir.
+ *
+ * Demands that a SKILL.md frontmatter "name" equal the name of the
+ * directory that holds the file. The check applies only to SKILL.md
+ * and stays silent when the file carries no "name" key.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class NameMatchesDir {
+  constructor() {
+    this.id = 'name-matches-dir';
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const blocks = document.walk({
+      header: () => [],
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: (pairs) => [pairs]
+    });
+    const name = blocks.length === 0
+      ? null
+      : blocks[0].find((pair) => pair.key === 'name');
+    return this.mismatch(uri, name);
+  }
+  mismatch(uri, name) {
+    const parent = path.basename(path.dirname(uri));
+    if (!name || name.value === parent) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'error',
+      `name "${name.value}" must match directory "${parent}"`,
+      new Region(uri, name.row, 1)
+    )];
+  }
+}
+
+module.exports = NameMatchesDir;

package/src/rules/passive.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');
+
+/**
+ * Passive.
+ *
+ * Demands active imperative voice. A standalone checker can only guess:
+ * it flags a "be" verb followed, perhaps through an adverb, by a past
+ * participle, the surest mark of passive voice.
+ *
+ * @todo #24:45min Upgrade to an AI oracle for accurate passive-voice
+ *  detection, since the regular-expression heuristic both misses many
+ *  irregular participles and cannot judge true grammatical voice, as
+ *  requested in issue #24.
+ */
+class Passive {
+  constructor() {
+    this.id = 'passive';
+  }
+  prompt() {
+    return `${this.id}: flag any instruction written in passive voice`;
+  }
+  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 = /\b(?:is|are|was|were|be|been|being)\b\s+(?:\w+ly\s+)?(?:\w+ed|written|done|made|built|kept|sent|shown|seen|taken|given|held|found|run|read|set)\b/iu;
+    if (!regex.test(text)) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'line uses passive voice',
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = Passive;

package/src/rules/polite.js

@@ -0,0 +1,56 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * Polite.
+ *
+ * Flags courtesy and scaffolding phrases that soften an instruction
+ * without adding meaning: "please", "kindly", "feel free to", and the
+ * like. Each phrase wastes tokens and weakens a command, so every hit
+ * earns its own violation.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class Polite {
+  constructor() {
+    this.id = 'polite';
+  }
+  prompt() {
+    return '';
+  }
+  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 = /\b(?:please|kindly|feel free to|make sure to|be sure to|don't forget to|remember to|note that|it is important to)\b/giu;
+    let hit = regex.exec(text);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'error',
+        `courtesy phrase "${hit[0]}" must be removed`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = regex.exec(text);
+    }
+    return found;
+  }
+}
+
+module.exports = Polite;

package/src/rules/short-sections.js

@@ -13,13 +13,16 @@ const Region = require('../region');
  *
  * Demands that every section name be a short label of one to three
  * words, so the manifesto reads as a map and not as prose.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
  */
 class ShortSections {
   constructor() {
     this.id = 'short-sections';
   }
   prompt() {
-    return `${this.id}: flag any section heading that is not a short, noun-style label`;
+    return '';
   }
   violations(document) {
     const uri = document.uri();

package/src/rules/simple.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');
+
+/**
+ * Simple.
+ *
+ * Demands simple grammar over ambiguity. A standalone checker can only
+ * guess: it counts commas and conjunctions to flag lines that pile up
+ * clauses. Its prompt hands the subtler tangle judgement to the oracle.
+ *
+ * @todo #29:45min Upgrade to true clause-depth analysis through an AI
+ *  oracle so that subtle tangled instructions, which the comma and
+ *  conjunction heuristic cannot measure today, are reliably caught, as
+ *  requested in issue #29.
+ */
+class Simple {
+  constructor() {
+    this.id = 'simple';
+  }
+  prompt() {
+    return `${this.id}: flag any grammatically tangled, multi-clause instruction`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.judge(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  judge(text, line, uri) {
+    const commas = text.match(/,/gu);
+    const commaCount = commas === null ? 0 : commas.length;
+    const hasConjunction = /\b(?:if|when|unless|because|although|while)\b/iu.test(text);
+    const tangled = hasConjunction && commaCount >= 2 || commaCount >= 3;
+    if (!tangled) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'line is grammatically tangled, split into simpler lines',
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = Simple;

package/src/rules/unfinished.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');
+
+/**
+ * Unfinished.
+ *
+ * Flags any prose line that still carries a leftover marker, the
+ * fingerprint of work left half done. It catches the uppercase tokens
+ * TODO, TBD, FIXME, XXX, and WIP, the placeholder phrase "lorem ipsum",
+ * a trailing bare ellipsis, and an unfilled angle-bracket placeholder
+ * such as <placeholder>.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class Unfinished {
+  constructor() {
+    this.id = 'unfinished';
+  }
+  prompt() {
+    return '';
+  }
+  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 markers = [
+      /\b(?:TODO|TBD|FIXME|XXX|WIP)\b/u,
+      /lorem ipsum/iu,
+      /\.\.\.\s*$/u,
+      /<[^>\n]*>/u
+    ];
+    if (!markers.some((marker) => marker.test(text))) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'error',
+      'leftover marker found, file looks unfinished',
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = Unfinished;

package/src/rules/unique.js

@@ -0,0 +1,73 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+const normalize = (text) => {
+  const clean = text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/gu, '')
+    .replace(/\b(?:a|an|the)\b/gu, '')
+    .replace(/\s+/gu, ' ')
+    .trim();
+  return clean.split(' ').sort().join(' ');
+};
+
+/**
+ * Unique.
+ *
+ * Flags any instruction that repeats another instruction in the file.
+ * It normalizes each prose line, then remembers the first line where
+ * each normal form appeared, so a later twin earns one violation.
+ *
+ * @todo #25:45min Upgrade to semantic near-duplicate detection through
+ *  embeddings or an AI oracle, to catch same-meaning different-words
+ *  pairs the normalizer misses, as requested in issue #25.
+ */
+class Unique {
+  constructor() {
+    this.id = 'unique';
+  }
+  prompt() {
+    return `${this.id}: flag any instruction that repeats another instruction in the file`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    const lines = document.walk({
+      header: () => [],
+      prose: (text, line) => [{text, line}],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+    return this.repeats(uri, lines);
+  }
+  repeats(uri, lines) {
+    const seen = new Map();
+    const found = [];
+    lines.forEach((item) => {
+      const norm = normalize(item.text);
+      if (norm === '') {
+        return;
+      }
+      if (seen.has(norm)) {
+        found.push(new Violation(
+          this.id,
+          'warning',
+          `instruction repeats line ${seen.get(norm)}`,
+          new Region(uri, item.line, 1)
+        ));
+      } else {
+        seen.set(norm, item.line);
+      }
+    });
+    return found;
+  }
+}
+
+module.exports = Unique;

package/src/usage.js

@@ -0,0 +1,52 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Price table.
+ *
+ * United States dollars per one million tokens, sent and received, for
+ * every model dogent knows. An unknown model falls back to zero, so the
+ * summary still prints token counts without inventing a price.
+ */
+const PRICES = {
+  'gpt-4o-mini': {input: 0.15, output: 0.6},
+  'gpt-4o': {input: 2.5, output: 10},
+  'gpt-4.1-nano': {input: 0.1, output: 0.4},
+  'gpt-4.1-mini': {input: 0.4, output: 1.6},
+  'gpt-4.1': {input: 2, output: 8}
+};
+
+/**
+ * Usage.
+ *
+ * One immutable tally of an OpenAI exchange: the model, the tokens sent,
+ * and the tokens received. Sums itself with another tally and renders a
+ * single human summary line, complete with an estimated cost in cents.
+ */
+class Usage {
+  constructor(model, sent, received) {
+    this.model = model;
+    this.sent = sent;
+    this.received = received;
+  }
+  plus(other) {
+    return new Usage(
+      this.model || other.model,
+      this.sent + other.sent,
+      this.received + other.received
+    );
+  }
+  cost() {
+    const price = PRICES[this.model] || {input: 0, output: 0};
+    return this.sent / 1e6 * price.input + this.received / 1e6 * price.output;
+  }
+  text() {
+    return `OpenAI: ${this.model}, ${this.sent} sent, ${this.received} received, ~${(this.cost() * 100).toFixed(2)}¢`;
+  }
+}
+
+module.exports = Usage;