@yegor256/dogent 0.11.0 → 0.12.1

package/README.md

@@ -53,7 +53,7 @@ Most rewrite prompts for you or score a file, while we enforce
 Run it on any manifesto file, no installation required:
 
 ```bash
-npx @yegor256/dogent@0.10.0 SKILL.md
+npx @yegor256/dogent@0.11.0 SKILL.md
 ```
 
 Point it at a directory to lint the default manifestos it holds
@@ -75,9 +75,14 @@ CLAUDE.md
   24:  article "the" detected, remove noise
   31:  section name too long, use 1-3 words
 
-4 problems found, exit code 1
+Locally: 4 problems found, exit code 1
+Spotted a false positive? dogent is in beta, please report it at https://github.com/yegor256/dogent/issues
 ```
 
+The standalone checks report under their own `Locally:` summary line.
+When a token enables AI verification, a second `OpenAI:` summary line
+  follows, reporting the problems the model found on top.
+
 The command exits with a non-zero status when problems are found,
   so it plugs directly into CI and pre-commit hooks.
 
@@ -124,11 +129,13 @@ The command exits with a non-zero status when problems are found,
 `dogent` works standalone by default,
   using fast deterministic checks with no network access.
 When `OPENAI_API_KEY` is present in the environment,
-  and only after the standalone rules find nothing,
-  `dogent` asks OpenAI for a second, deeper opinion.
+  `dogent` first reports the problems found locally,
+  then asks OpenAI for a second, deeper opinion and reports those apart.
 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.
+Each step closes with its own summary line, `Locally:` then `OpenAI:`,
+  so both counts stay visible even when neither step finds a problem.
 The model defaults to `gpt-4o-mini`; override it with `OPENAI_MODEL`.
 Requests go to `https://api.openai.com/v1` by default;
   set `OPENAI_BASE_URL` to any OpenAI-compatible endpoint instead,
@@ -162,6 +169,14 @@ npx @yegor256/dogent --offline CLAUDE.md
 
 Pass `--sarif` to print the report as SARIF instead of plain text.
 
+Pass `--hints` to append, for every rule that reported a violation, one
+  English paragraph explaining how to fix it. This helps you or your agent
+  repair the manifesto faster:
+
+```bash
+npx @yegor256/dogent --hints CLAUDE.md
+```
+
 Pass `--suppress` to silence a rule by its id. Repeat the option or
   join several ids with commas to silence many at once:
 
@@ -251,7 +266,7 @@ Reference `dogent` as a remote hook in `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/yegor256/dogent
-    rev: 0.10.0
+    rev: 0.11.0
     hooks:
       - id: dogent
 ```
@@ -271,3 +286,33 @@ repos:
 ```
 
 Either way, the commit is rejected until every flagged line is fixed.
+
+## Architecture
+
+The component diagram below shows how the pieces fit together
+  ([source](components.svg)):
+
+![dogent component diagram](components.svg)
+
+A user, or an AI agent, runs `dogent` from the console against a manifesto
+  such as `SKILL.md`.
+`dogent` parses the file into a document, applies every deterministic rule,
+  and renders the violations as text or SARIF.
+Only after the rules find nothing, and only when a token is present,
+  it asks an OpenAI-compatible LLM for a second, deeper opinion.
+
+## How to Contribute
+
+First, make sure you can build it locally:
+
+```bash
+npm test
+```
+
+The build has to be clean.
+If it's not, [submit an issue](https://github.com/yegor256/dogent/issues).
+
+Then, make your changes, make sure the build is still clean,
+  and [submit a pull request][guidelines].
+
+[guidelines]: https://www.yegor256.com/2014/04/15/github-guidelines.html

package/package.json

@@ -40,7 +40,7 @@
     "lint": "eslint .",
     "test": "mocha 'test/**/*.js' --timeout 60000"
   },
-  "version": "0.11.0",
+  "version": "0.12.1",
   "dependencies": {
     "minimist": "^1.2.8",
     "pretty-ms": "^7.0.1"

package/src/args.js

@@ -17,6 +17,8 @@ const minimist = require('minimist');
  * flag, also spelled `-h`, asks for the usage banner. The `--version` flag
  * asks for the release number. The `--suppress` option names a rule to
  * silence; repeat it or join names with commas to silence many at once. The
+ * `--hints` flag appends, for every rule that reported a violation, one
+ * English paragraph telling the agent how to fix it. The
  * `--openai-http-header` option adds one `Name: Value` header to every OpenAI
  * call; repeat it to add many. Everything after a `--` separator counts as a
  * path, never as an option.
@@ -24,7 +26,7 @@ const minimist = require('minimist');
 class Args {
   constructor(
     argv,
-    flags = ['sarif', 'offline', 'help', 'version'],
+    flags = ['sarif', 'offline', 'help', 'version', 'hints'],
     options = ['suppress', 'openai-http-header']
   ) {
     this.flags = flags;
@@ -46,6 +48,9 @@ class Args {
   version() {
     return this.parsed.version === true;
   }
+  hints() {
+    return this.parsed.hints === true;
+  }
   suppress() {
     return [].concat(this.parsed.suppress || [])
       .flatMap((item) => String(item).split(','))

package/src/defaults.js

@@ -40,7 +40,12 @@ class Defaults {
       .split('\n')
       .map((line) => line.trim())
       .filter((line) => line !== '' && !line.startsWith('#'))
-      .flatMap((line) => line.split(/\s+/u));
+      .flatMap((line) => {
+        const separator = line.search(/\s/u);
+        return separator < 0
+          ? [line]
+          : [line.slice(0, separator), line.slice(separator).trimStart()];
+      });
   }
 }
 

package/src/dogent.js

@@ -21,7 +21,7 @@ const rules = require('./rules');
 
 const args = new Args(new Defaults().argv().concat(process.argv.slice(2)));
 const sarif = args.sarif();
-const banner = 'Usage: dogent [--sarif] [--offline] [--suppress=RULE,...] <file.md|dir>...';
+const banner = 'Usage: dogent [--sarif] [--offline] [--hints] [--suppress=RULE,...] <file.md|dir>...';
 if (args.version()) {
   process.stdout.write(`${version}\n`);
   process.exit(0);
@@ -34,6 +34,7 @@ if (args.help()) {
     '  --sarif    render the report as SARIF JSON\n' +
     '  --offline  never call the LLM, even when a token exists\n' +
     '  --suppress silence a rule by id; repeat or comma-join to silence many\n' +
+    '  --hints    append a fixing hint for every rule that reported a violation\n' +
     '  --openai-http-header  add a "Name: Value" header to OpenAI calls\n' +
     '  --version  show the version and exit\n' +
     '  --help     show this help and exit\n\n' +
@@ -61,7 +62,17 @@ if (paths.length === 0) {
   process.stderr.write(`${banner}\n`);
   process.exit(2);
 }
-const scanned = new Sources(paths).files();
+const scan = () => {
+  try {
+    return new Sources(paths).files();
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.stderr.write(`${banner}\n`);
+    process.exit(2);
+  }
+  return [];
+};
+const scanned = scan();
 scanned.forEach((file) => process.stderr.write(`Scanning ${file}\n`));
 const checks = rules();
 process.stderr.write(`${scanned.length} files scanned, ${checks.length} rules applied\n`);
@@ -77,6 +88,7 @@ documents.forEach((document) => {
     rule.violations(document).filter(allowed).forEach((violation) => found.push(violation));
   });
 });
+const localMillis = Date.now() - started;
 const key = process.env.OPENAI_API_KEY;
 const audit = async (docs) => {
   const oracle = new Oracle(
@@ -100,23 +112,42 @@ const audit = async (docs) => {
     {extra: [], usage: new Usage('', 0, 0)}
   );
 };
-const finish = (usage, aiMillis) => {
-  const report = new Report('dogent', found, Date.now() - started);
-  process.stdout.write(`${sarif ? JSON.stringify(report.sarif(), null, 2) : report.text()}\n`);
-  if (usage !== null) {
-    process.stderr.write(`${usage.text()}, analysed in ${prettyMs(aiMillis)}\n`);
-  }
-  process.exit(report.count() > 0 ? 1 : 0);
-};
 const verify = async () => {
   const clock = Date.now();
   const result = await audit(documents);
-  result.extra.filter(allowed).forEach((violation) => found.push(violation));
-  return {usage: result.usage, aiMillis: Date.now() - clock};
+  return {
+    extra: result.extra.filter(allowed),
+    usage: result.usage,
+    aiMillis: Date.now() - clock
+  };
+};
+const consult = Boolean(key) && !args.offline();
+const human = (outcome) => {
+  const all = found.concat(outcome.extra);
+  process.stdout.write(`${new Report('dogent', found, localMillis, 'Locally').text()}\n`);
+  if (consult) {
+    process.stdout.write(`${new Report('dogent', outcome.extra, outcome.aiMillis, 'OpenAI').text()}\n`);
+  }
+  if (args.hints() && all.length > 0) {
+    process.stdout.write(`\n${new Report('dogent', all).hints(checks)}\n`);
+  }
+};
+const render = (outcome) => {
+  const all = found.concat(outcome.extra);
+  if (sarif) {
+    const report = new Report('dogent', all, localMillis + outcome.aiMillis);
+    process.stdout.write(`${JSON.stringify(report.sarif(), null, 2)}\n`);
+  } else {
+    human(outcome);
+  }
+  if (outcome.usage !== null) {
+    process.stderr.write(`${outcome.usage.text()}, analysed in ${prettyMs(outcome.aiMillis)}\n`);
+  }
+  process.exit(all.length > 0 ? 1 : 0);
 };
 (async () => {
-  let outcome = {aiMillis: 0, usage: null};
-  if (found.length === 0 && key && !args.offline()) {
+  let outcome = {extra: [], aiMillis: 0, usage: null};
+  if (consult) {
     try {
       outcome = await verify();
     } catch (error) {
@@ -124,5 +155,5 @@ const verify = async () => {
       process.exit(2);
     }
   }
-  finish(outcome.usage, outcome.aiMillis);
+  render(outcome);
 })();

package/src/report.js

@@ -14,21 +14,44 @@ const prettyMs = require('pretty-ms');
  * violation it gathered. Renders itself for humans or as a SARIF log.
  * When handed the analysis duration in milliseconds, the human text
  * closes with a friendly "in 340ms" rendered through pretty-ms.
+ * A label tags the summary line, telling local checks from AI ones.
+ * Given the rules that ran, it can also render one fixing hint per rule
+ * that reported a violation, in first-appearance order.
  */
 class Report {
-  constructor(tool, violations, millis = null) {
+  constructor(tool, violations, millis = null, label = '') {
     this.tool = tool;
     this.bag = violations;
     this.millis = millis;
+    this.label = label;
   }
   count() {
     return this.bag.length;
   }
   text() {
     const suffix = this.millis === null ? '' : ` in ${prettyMs(this.millis)}`;
-    return this.bag
+    const prefix = this.label === '' ? '' : `${this.label}: `;
+    const lines = this.bag
       .map((violation) => violation.text())
-      .concat(`${this.bag.length} problems found${suffix}`)
+      .concat(`${prefix}${this.bag.length} problems found${suffix}`);
+    if (this.bag.length > 0) {
+      lines.push(
+        'Spotted a false positive? dogent is in beta, please report it at ' +
+        'https://github.com/yegor256/dogent/issues'
+      );
+    }
+    return lines.join('\n');
+  }
+  hints(rules) {
+    const byId = new Map(rules.map((rule) => [rule.id, rule]));
+    const seen = [];
+    this.bag.forEach((violation) => {
+      if (!seen.includes(violation.rule) && byId.has(violation.rule)) {
+        seen.push(violation.rule);
+      }
+    });
+    return seen
+      .map((id) => `[${id}]: ${byId.get(id).hint()}`)
       .join('\n');
   }
   sarif() {

package/src/rules/ambiguous-or.js

@@ -24,6 +24,9 @@ class AmbiguousOr {
   constructor() {
     this.id = 'ambiguous-or';
   }
+  hint() {
+    return 'Replace every either-or choice such as and/or or a slashed alternative with one explicit branch, naming exactly which option the agent must take so no guessing remains.';
+  }
   prompt() {
     return `${this.id}: flag either-or ambiguity beyond "and/or" and slashed alternatives, and state exactly which option applies`;
   }

package/src/rules/atomic.js

@@ -24,6 +24,9 @@ class Atomic {
   constructor() {
     this.id = 'atomic';
   }
+  hint() {
+    return 'Split a line that bundles several instructions into one line per instruction, since the agent reads each line as a single command and welded clauses get half-followed.';
+  }
   prompt() {
     return `${this.id}: flag any line that carries more than one instruction, counting distinct clauses whether or not a semicolon, "and", or "then" welds them, yet never count a coordinated object or noun phrase trailing "and" or "then" as a second instruction`;
   }

package/src/rules/budget.js

@@ -24,6 +24,9 @@ class Budget {
     this.id = 'budget';
     this.cap = cap;
   }
+  hint() {
+    return 'Trim or split the manifesto so it holds fewer instructions than the budget, moving secondary guidance into separate referenced files to keep the core small.';
+  }
   prompt() {
     return '';
   }

package/src/rules/command.js

@@ -20,6 +20,9 @@ class Command {
   constructor() {
     this.id = 'command';
   }
+  hint() {
+    return 'Rewrite the line as a direct imperative that opens with a base-form verb such as Write, Strip, or Keep, dropping any pronoun, question, or plain statement.';
+  }
   prompt() {
     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`;
   }

package/src/rules/concise.js

@@ -25,6 +25,9 @@ class Concise {
     this.id = 'concise';
     this.max = max;
   }
+  hint() {
+    return 'Shorten the file or split its detail into referenced files so its middle instructions survive, since models attend to the start and end and skim the middle.';
+  }
   prompt() {
     return `${this.id}: flag a manifesto so long its middle instructions risk being lost, and recommend splitting detail into referenced files`;
   }

package/src/rules/conditional.js

@@ -23,6 +23,9 @@ class Conditional {
   constructor() {
     this.id = 'conditional';
   }
+  hint() {
+    return 'Break a line that packs several conditions into one case per line, so the agent never has to untangle a whole decision tree welded onto a single line.';
+  }
   prompt() {
     return `${this.id}: flag implicit branching that carries no keyword, and split each case into its own command`;
   }

package/src/rules/consistent.js

@@ -19,6 +19,9 @@ class Consistent {
   constructor() {
     this.id = 'consistent';
   }
+  hint() {
+    return 'Delete the duplicate instruction or reconcile the contradictory pair, so each instruction is stated once and never both ordered and forbidden across two lines.';
+  }
   prompt() {
     return `${this.id}: flag an instruction that repeats another instruction word for word, or that logically contradicts another instruction about the very same subject, where one line orders exactly what another forbids; ignore lines that merely share a theme but govern different concerns, since complementary instructions never clash`;
   }

package/src/rules/counter-example.js

@@ -25,6 +25,9 @@ class CounterExample {
   constructor() {
     this.id = 'counter-example';
   }
+  hint() {
+    return 'Remove the demonstration of the wrong form and show only the correct form, since displaying a mistake can teach the agent to repeat it.';
+  }
   prompt() {
     return `${this.id}: judge whether each example shows the correct behavior, and flag any example that demonstrates the incorrect form`;
   }

package/src/rules/crowded.js

@@ -25,6 +25,9 @@ class Crowded {
     this.id = 'crowded';
     this.limit = limit;
   }
+  hint() {
+    return 'Split an overcrowded section into smaller sections, each holding only a handful of related instructions under its own short heading.';
+  }
   prompt() {
     return '';
   }

package/src/rules/dead-import.js

@@ -57,8 +57,11 @@ class DeadImport {
     this.id = 'dead-import';
     this.depth = 5;
   }
+  hint() {
+    return 'Fix or remove the @path import so it points to a real file, and break any circular or overly deep import chain the host tool cannot resolve.';
+  }
   prompt() {
-    return `${this.id}: flag any @path/to/file import that points to no file on disk`;
+    return `${this.id}: flag any @path/to/file import that points to no file on disk; only an @-prefixed token counts as an import, so never treat a bare path in prose as one`;
   }
   violations(document) {
     const uri = document.uri();

package/src/rules/default.js

@@ -23,6 +23,9 @@ class Default {
   constructor() {
     this.id = 'default';
   }
+  hint() {
+    return 'State the default outcome whenever you mark behavior optional, telling the agent exactly what to do when it declines the option.';
+  }
   prompt() {
     return `${this.id}: flag optionality that names no default even without a listed marker, and state the default`;
   }

package/src/rules/description-length.js

@@ -25,6 +25,9 @@ class DescriptionLength {
     this.id = 'description-length';
     this.ceiling = 1024;
   }
+  hint() {
+    return 'Write a SKILL.md description that is neither empty nor bloated, stating the capability concisely so it fits the loader budget.';
+  }
   prompt() {
     return '';
   }

package/src/rules/description-triggers.js

@@ -22,6 +22,9 @@ class DescriptionTriggers {
     this.id = 'description-triggers';
     this.minimum = 20;
   }
+  hint() {
+    return 'Name the concrete situations and user phrases that should activate the skill in its description, so the loader knows exactly when to invoke it.';
+  }
   prompt() {
     return `${this.id}: in a SKILL.md, flag a description that is too short or fails to name the concrete situations and user phrases that should activate the skill, even when it contains the word "when"`;
   }

package/src/rules/description-voice.js

@@ -27,6 +27,9 @@ class DescriptionVoice {
     this.id = 'description-voice';
     this.pronoun = /\b(?:I|we|you|your|my|our)\b/giu;
   }
+  hint() {
+    return 'Write the SKILL.md description as a third-person capability statement such as Extracts tables, never in first or second person.';
+  }
   prompt() {
     return `${this.id}: in a SKILL.md, flag a description written in first or second person and demand a third-person capability statement`;
   }

package/src/rules/done.js

@@ -21,6 +21,9 @@ class Done {
   constructor() {
     this.id = 'done';
   }
+  hint() {
+    return 'Add a verifiable, pass-or-fail completion check to the SKILL.md so the agent knows exactly how to confirm the work is finished.';
+  }
   prompt() {
     return `${this.id}: in a SKILL.md, judge whether the stated completion check is actually pass/fail testable rather than a vague gesture toward being finished`;
   }

package/src/rules/duplicate-section.js

@@ -28,6 +28,9 @@ class DuplicateSection {
   constructor() {
     this.id = 'duplicate-section';
   }
+  hint() {
+    return 'Give every section a distinct heading, merging or renaming any two sections that share the same name.';
+  }
   prompt() {
     return '';
   }

package/src/rules/emoji.js

@@ -27,6 +27,9 @@ class Emoji {
     this.id = 'emoji';
     this.glyph = /[\p{Extended_Pictographic}\u{2190}-\u{21FF}\u{2300}-\u{27BF}\u{2B00}-\u{2BFF}]/gu;
   }
+  hint() {
+    return 'Delete decorative emoji and pictographic symbols, since they add token noise without carrying any instruction, and keep the text plain.';
+  }
   prompt() {
     return '';
   }

package/src/rules/emphasis.js

@@ -25,6 +25,9 @@ class Emphasis {
     this.id = 'emphasis';
     this.shout = new Set(['IMPORTANT', 'ALWAYS', 'NEVER', 'MUST', 'CRITICAL', 'REQUIRED']);
   }
+  hint() {
+    return 'Drop shouting such as all-caps words or repeated exclamation marks and state the instruction plainly, since volume adds no meaning for the model.';
+  }
   prompt() {
     return `${this.id}: flag emphatic shouting the patterns miss, including borderline all-caps and reward framing, since emphasis adds no instruction`;
   }

package/src/rules/empty.js

@@ -23,6 +23,9 @@ class Empty {
   constructor() {
     this.id = 'empty';
   }
+  hint() {
+    return 'Fill the hollow section with at least one instruction, or delete the heading, so no section declares itself without a body.';
+  }
   prompt() {
     return '';
   }

package/src/rules/example-format.js

@@ -21,6 +21,9 @@ class ExampleFormat {
   constructor() {
     this.id = 'example-format';
   }
+  hint() {
+    return 'Make the example in the SKILL.md conform exactly to the declared output format, since a mismatched example teaches the agent the wrong shape.';
+  }
   prompt() {
     return `${this.id}: in a SKILL.md that both shows an example and declares an output format, judge whether the example conforms to the declared format and flag any mismatch`;
   }

package/src/rules/example.js

@@ -24,6 +24,9 @@ class Example {
   constructor() {
     this.id = 'example';
   }
+  hint() {
+    return 'Add at least one concrete worked input and output example to the SKILL.md, since a single demonstration guides the agent far better than prose alone.';
+  }
   prompt() {
     return `${this.id}: in a SKILL.md, judge whether a present code block is a genuine worked example rather than a stray snippet, and flag a skill that only describes without demonstrating`;
   }

package/src/rules/external-link.js

@@ -23,6 +23,9 @@ class ExternalLink {
   constructor() {
     this.id = 'external-link';
   }
+  hint() {
+    return 'Inline the durable guidance instead of linking to an external URL, since the page may rot or smuggle hidden instructions at run time.';
+  }
   prompt() {
     return `${this.id}: judge whether an external link is load-bearing, and flag durable guidance that should be inlined instead`;
   }

package/src/rules/fence-language.js

@@ -24,6 +24,9 @@ class FenceLanguage {
     this.id = 'fence-language';
     this.fence = /^\s*(?:```|~~~)\s*(?<lang>\S*)/u;
   }
+  hint() {
+    return 'Declare a language right after the opening fence of every code block so readers and tooling know the snippet syntax.';
+  }
   prompt() {
     return '';
   }

package/src/rules/format.js

@@ -26,6 +26,9 @@ class Format {
   constructor() {
     this.id = 'format';
   }
+  hint() {
+    return 'Declare and show the exact output format whenever the skill generates output, since a pinned-down contract makes structured output far more reliable.';
+  }
   prompt() {
     return `${this.id}: in a SKILL.md, judge whether the declared output format is concrete and machine-checkable, and flag a generating skill that pins down no format`;
   }

package/src/rules/frontmatter.js

@@ -22,6 +22,9 @@ class Frontmatter {
     this.required = required;
     this.allowed = allowed;
   }
+  hint() {
+    return 'Open the file with a YAML frontmatter block that declares every required key with a real value and carries no key outside the allowed set.';
+  }
   prompt() {
     return `${this.id}: in a ${this.name} file, flag any required key whose value is empty, vague, or a leftover placeholder`;
   }

package/src/rules/grouped.js

@@ -21,6 +21,9 @@ class Grouped {
   constructor() {
     this.id = 'grouped';
   }
+  hint() {
+    return 'Move every loose instruction under a section heading, since prose before the first heading belongs to no section.';
+  }
   prompt() {
     return '';
   }

package/src/rules/hedging.js

@@ -22,6 +22,9 @@ class Hedging {
   constructor() {
     this.id = 'hedging';
   }
+  hint() {
+    return 'Remove hedging words such as should, just, or usually and state the order firmly, since timid wording weakens the command.';
+  }
   prompt() {
     return `${this.id}: flag soft, non-committal, or hedging wording, including conditional escape hatches and vague scope that carry no fixed hedge word`;
   }

package/src/rules/hidden-char.js

@@ -26,6 +26,9 @@ class HiddenChar {
     this.id = 'hidden-char';
     this.hidden = /[\u200B-\u200D\uFEFF\u202A-\u202E\u2066-\u2069\uFE00-\uFE0F\u{E0100}-\u{E01EF}]/gu;
   }
+  hint() {
+    return 'Delete the invisible or control character named by its codepoint, since hidden characters can corrupt parsing or smuggle instructions.';
+  }
   prompt() {
     return '';
   }

package/src/rules/homoglyph.js

@@ -28,6 +28,9 @@ class Homoglyph {
     this.latin = /[A-Za-z]/u;
     this.confusable = /[Ѐ-ӿͰ-Ͽ＀-￯]/u;
   }
+  hint() {
+    return 'Replace the mixed-script look-alike character with its plain ASCII equivalent, since a foreign codepoint hidden inside a word breaks tooling.';
+  }
   prompt() {
     return '';
   }

package/src/rules/inline-code.js

@@ -34,6 +34,9 @@ class InlineCode {
   constructor() {
     this.id = 'inline-code';
   }
+  hint() {
+    return 'Wrap a bare literal token, such as a command, path, filename, or flag, in backticks so the model treats it as a literal and never rewords it.';
+  }
   prompt() {
     return `${this.id}: flag a bare literal token (command, path, filename, or flag) that should be wrapped in backticks, judging borderline cases`;
   }

package/src/rules/jargon.js

@@ -48,6 +48,8 @@ const defined = (masked) => {
   while (hit !== null) {
     if (hit.groups.acronym) {
       found.add(hit.groups.acronym);
+    } else if (/^[A-Z]{2,}$/u.test(hit.groups.gloss)) {
+      found.add(hit.groups.gloss);
     } else {
       found.add(initials(hit.groups.gloss));
     }
@@ -64,10 +66,11 @@ const undefining = (acronym, scope) => !scope.known.has(acronym) &&
  *
  * Flags an acronym that lands in prose without ever being expanded. An
  * acronym counts as defined when the document, anywhere, follows it with
- * a parenthetical gloss, as in "RBAC (role-based access control)", or when
+ * a parenthetical gloss, as in "RBAC (role-based access control)", when
  * a parenthetical's word initials spell it, as in "AAA pattern
- * (Arrange-Act-Assert)", so a single expansion licenses every later
- * mention. Well-known acronyms sit
+ * (Arrange-Act-Assert)", or when the expansion precedes a parenthetical
+ * acronym, as in "Virtual Private Network (VPN)", so a single expansion
+ * licenses every later mention. Well-known acronyms sit
  * in a built-in allowlist and pass untouched. Only the first unexpanded
  * occurrence of each acronym is reported. Its prompt hands non-acronym
  * domain jargon, the rare nouns a reader cannot parse, to the AI oracle.
@@ -76,6 +79,9 @@ class Jargon {
   constructor() {
     this.id = 'jargon';
   }
+  hint() {
+    return 'Expand each acronym on first use with a parenthetical gloss, and replace rare domain jargon with plain words a fresh reader can parse.';
+  }
   prompt() {
     return `${this.id}: flag non-acronym domain jargon, rare nouns a fresh reader cannot parse, and ask for a plain-word definition on first use`;
   }

package/src/rules/line-length.js

@@ -22,6 +22,9 @@ class LineLength {
     this.id = 'line-length';
     this.max = max;
   }
+  hint() {
+    return 'Shorten the line below the width cap, splitting it into separate instructions if needed so each stays easy to read.';
+  }
   prompt() {
     return '';
   }

package/src/rules/meta-reference.js

@@ -24,6 +24,9 @@ class MetaReference {
     this.id = 'meta-reference';
     this.phrase = /\b(?:as an ai|as a language model|you are an ai|you are a model|this prompt|these instructions|this manifesto|the system prompt)\b/giu;
   }
+  hint() {
+    return 'Delete self-referential framing such as as an AI or this prompt, since it narrates the setup instead of issuing a command.';
+  }
   prompt() {
     return `${this.id}: flag self-referential framing of the model or document beyond the fixed list, and delete it`;
   }

package/src/rules/name-format.js

@@ -23,6 +23,9 @@ class NameFormat {
   constructor() {
     this.id = 'name-format';
   }
+  hint() {
+    return 'Write the SKILL.md frontmatter name in kebab-case, using only lowercase letters and digits joined by single hyphens.';
+  }
   prompt() {
     return '';
   }

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

@@ -24,6 +24,9 @@ class NameMatchesDir {
   constructor() {
     this.id = 'name-matches-dir';
   }
+  hint() {
+    return 'Rename the SKILL.md frontmatter name so it matches the name of the directory that holds the file.';
+  }
   prompt() {
     return '';
   }

package/src/rules/no-articles.js

@@ -19,6 +19,9 @@ class NoArticles {
   constructor() {
     this.id = 'no-articles';
   }
+  hint() {
+    return 'Remove filler articles such as a, an, and the, since they add noise without changing the instruction.';
+  }
   prompt() {
     return `${this.id}: flag filler or noise words that add nothing to an instruction`;
   }

package/src/rules/ordered.js

@@ -24,6 +24,9 @@ class Ordered {
   constructor() {
     this.id = 'ordered';
   }
+  hint() {
+    return 'Convert a sequence of steps into a numbered list, since models follow numbered ordered steps far more reliably than unordered bullets.';
+  }
   prompt() {
     return `${this.id}: flag an implied sequence that no marker word signals, demanding a numbered list whenever the order of steps matters`;
   }

package/src/rules/passive.js

@@ -21,6 +21,9 @@ class Passive {
   constructor() {
     this.id = 'passive';
   }
+  hint() {
+    return 'Rewrite the line in active imperative voice, naming the action to take instead of describing what gets done.';
+  }
   prompt() {
     return `${this.id}: flag any instruction written in passive voice, judging true grammatical voice including irregular past participles a fixed pattern misses`;
   }

package/src/rules/persona.js

@@ -24,6 +24,9 @@ class Persona {
   constructor() {
     this.id = 'persona';
   }
+  hint() {
+    return 'Delete the role-play persona such as You are a senior engineer, since assigning a role adds no instruction and can hurt performance.';
+  }
   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`;
   }

package/src/rules/placement.js

@@ -27,6 +27,9 @@ class Placement {
     this.id = 'placement';
     this.keyword = /^#{1,6}\s+.*\b(?:safety|security|mission|critical|constraints?)\b/iu;
   }
+  hint() {
+    return 'Move the critical section to the top or bottom of the file, since models attend least to the buried middle of a long context.';
+  }
   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`;
   }

package/src/rules/polite.js

@@ -24,6 +24,9 @@ class Polite {
   constructor() {
     this.id = 'polite';
   }
+  hint() {
+    return 'Remove courtesy and scaffolding phrases such as please or make sure to, since they waste tokens and weaken the command.';
+  }
   prompt() {
     return '';
   }

package/src/rules/positive.js

@@ -19,14 +19,18 @@ const mask = require('../mask');
  * "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.
+ * command. The prompt demands an actual negation before flagging, so
+ * an affirmative imperative that already states what to do stays clean.
  */
 class Positive {
   constructor() {
     this.id = 'positive';
   }
+  hint() {
+    return 'Rewrite a prohibition as a positive imperative stating what to do, since a ban forces the model to process the forbidden idea first.';
+  }
   prompt() {
-    return `${this.id}: flag any instruction phrased as a prohibition, including bans carrying no fixed keyword, and rewrite each as a positive imperative`;
+    return `${this.id}: flag an instruction only when it forbids or negates an action, including a ban that carries no fixed keyword, and rewrite each as a positive imperative; leave an affirmative imperative that already states what to do untouched, returning nothing for it`;
   }
   violations(document) {
     const uri = document.uri();

package/src/rules/pseudo-heading.js

@@ -25,6 +25,9 @@ class PseudoHeading {
   constructor() {
     this.id = 'pseudo-heading';
   }
+  hint() {
+    return 'Replace a bold line posing as a heading with a real level-2 heading marked by two hashes.';
+  }
   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`;
   }

package/src/rules/punctuation.js

@@ -19,6 +19,9 @@ class Punctuation {
   constructor() {
     this.id = 'punctuation';
   }
+  hint() {
+    return 'Write each instruction as one complete sentence that opens with a capital letter and closes with a period.';
+  }
   prompt() {
     return `${this.id}: flag any instruction that is not one complete, grammatical sentence`;
   }

package/src/rules/quantifier.js

@@ -25,6 +25,9 @@ class Quantifier {
   constructor() {
     this.id = 'quantifier';
   }
+  hint() {
+    return 'Replace a vague quantity word such as some or several with an exact number or threshold the agent can act on.';
+  }
   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`;
   }

package/src/rules/rationale.js

@@ -23,6 +23,9 @@ class Rationale {
   constructor() {
     this.id = 'rationale';
   }
+  hint() {
+    return 'Delete the explanation or convert it into a direct order, since a manifesto carries commands, not justifications.';
+  }
   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`;
   }

package/src/rules/redundant.js

@@ -54,6 +54,9 @@ class Redundant {
     this.id = 'redundant';
     this.phrases = phrases;
   }
+  hint() {
+    return 'Delete the line that restates default model behavior, since generic advice the model already knows wastes the context budget.';
+  }
   prompt() {
     return `${this.id}: flag any line that restates default agent behavior already known to the model, not a project-specific instruction, including reworded paraphrases that match no fixed phrase list`;
   }

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

@@ -20,6 +20,9 @@ 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`;
   }

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

@@ -23,6 +23,9 @@ 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`;
   }

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

@@ -33,6 +33,9 @@ class Units {
       '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`;
   }

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

@@ -25,6 +25,9 @@ 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`;
   }

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.11.0` marks an unreleased build straight from source.
+ * The default `0.12.1` marks an unreleased build straight from source.
  */
-const version = '0.11.0';
+const version = '0.12.1';
 
 module.exports = version;