@yegor256/dogent 0.10.0 → 0.12.0

package/README.md

@@ -13,23 +13,47 @@ Vague, bloated, or ambiguous instructions make agents behave unpredictably.
 `dogent` enforces a clear, command-style discipline
   so every line earns its place.
 
-We respect [agent-sh/agnix](https://github.com/agent-sh/agnix)
-  as a prototype of this idea, but the two lint different layers.
-`agnix` validates the harness around a prompt — frontmatter schema,
-  hook JSON, MCP config, tool wiring — asking whether the configuration
-  is well-formed and correctly wired.
-`dogent` lints the prose of the instructions themselves,
-  asking whether every line is a tight, unambiguous command.
-In short: `agnix` lints the harness, `dogent` lints the prompt.
-`dogent` is the stricter, more opinionated of the two,
-  aiming for extreme quality with no compromise.
+## Alternatives
+
+Several tools sit near this problem, yet none lint manifesto prose
+  the way we do.
+Most rewrite prompts for you or score a file, while we enforce
+  line-level discipline and fail the build when one line breaks it.
+
+- [agent-sh/agnix](https://github.com/agent-sh/agnix)
+  validates the harness — frontmatter schema, hook JSON, MCP config, tools —
+    while we lint the prose, asking if each line is a tight command.
+
+- [AgentLinter](https://agentlinter.com)
+  lints the same files but scores them 0–100 across eight dimensions,
+    while we run a strict pass/fail gate, not a scorer.
+
+- [microsoft/SkillOpt](https://github.com/microsoft/SkillOpt)
+  rewrites `skill.md` against benchmarks to raise an agent's task score,
+    while we never rewrite, need no benchmarks, and judge discipline.
+
+- [linshenkx/prompt-optimizer](https://github.com/linshenkx/prompt-optimizer)
+  rewrites a prompt through an LLM in the browser, round by round,
+    while we lint manifesto files offline in CI.
+
+- [DSPy](https://github.com/stanfordnlp/dspy)
+  tunes prompts as programs to maximize a metric on a dataset,
+    while we lint hand-written manifestos, demanding clarity over a score.
+
+- Prompt platforms like [LangSmith](https://www.langchain.com/langsmith),
+    [PromptLayer](https://www.promptlayer.com), and
+    [Braintrust](https://www.braintrust.dev)
+  version, trace, and evaluate prompts from runtime data,
+    while we lint statically and offline, needing no traces or account.
 
 ## Usage
 
+[Watch the demo](https://github.com/user-attachments/assets/0f05c975-2bc8-4a95-9c3a-76a78fe5d655)
+
 Run it on any manifesto file, no installation required:
 
 ```bash
-npx @yegor256/dogent@0.7.2 SKILL.md
+npx @yegor256/dogent@0.11.0 SKILL.md
 ```
 
 Point it at a directory to lint the default manifestos it holds
@@ -51,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.
 
@@ -100,12 +129,19 @@ 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,
+  such as a local vLLM, Ollama, or LocalAI server, or a private gateway.
+For a keyless local server, set `OPENAI_API_KEY` to any placeholder,
+  since the server ignores it yet `dogent` calls the LLM only when it is set.
 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`.
@@ -115,6 +151,15 @@ export OPENAI_API_KEY=...
 npx @yegor256/dogent CLAUDE.md
 ```
 
+Point it at a local model the same way:
+
+```bash
+export OPENAI_BASE_URL=http://localhost:11434/v1
+export OPENAI_MODEL=llama3
+export OPENAI_API_KEY=dummy
+npx @yegor256/dogent CLAUDE.md
+```
+
 Pass `--offline` to keep `dogent` away from the LLM,
   even when `OPENAI_API_KEY` is present in the environment:
 
@@ -124,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:
 
@@ -131,6 +184,43 @@ Pass `--suppress` to silence a rule by its id. Repeat the option or
 npx @yegor256/dogent --suppress=name-matches-dir,line-length CLAUDE.md
 ```
 
+Pass `--openai-http-header` to add one `Name: Value` header to every OpenAI
+  call, handy for a gateway that wants its own token beside the API key.
+Repeat the option to add several headers:
+
+```bash
+npx @yegor256/dogent \
+  --openai-http-header='X-Api-Key: secret' \
+  --openai-http-header='X-Tenant: acme' \
+  CLAUDE.md
+```
+
+A header value often holds a secret, so keep it out of your shell history
+  by listing the option in a `.dogent` file (see below) instead.
+
+## Defaults file
+
+Tired of repeating the same flags on every run?
+Drop a `.dogent` file beside your project, and `dogent` reads its options
+  as defaults before it touches the command line.
+The file holds one option per line, written exactly as you would type it,
+  with the value after a space (for example `--suppress name-matches-dir`).
+A blank line is ignored, and a line that starts with `#` is a comment:
+
+```text
+# project defaults for dogent
+--offline
+--suppress name-matches-dir
+--suppress line-length
+```
+
+`dogent` looks first in the current directory, then in your home directory,
+  and reads the first `.dogent` it finds.
+The file only supplies defaults, so any option you type on the command line
+  overrides the same option in the file.
+Thus `npx @yegor256/dogent --sarif .` still prints SARIF even when the file
+  says nothing about it, and a hand-typed flag always wins.
+
 ## GitHub Actions
 
 Because `dogent` runs through `npx`, no extra action is needed.
@@ -176,7 +266,7 @@ Reference `dogent` as a remote hook in `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/yegor256/dogent
-    rev: 0.7.2
+    rev: 0.11.0
     hooks:
       - id: dogent
 ```
@@ -196,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.10.0",
+  "version": "0.12.0",
   "dependencies": {
     "minimist": "^1.2.8",
     "pretty-ms": "^7.0.1"

package/src/args.js

@@ -16,14 +16,18 @@ const minimist = require('minimist');
  * any talk to the LLM even when a token sits in the environment. The `--help`
  * 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.
- * Everything after a `--` separator counts as a path, never as an option.
+ * 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.
  */
 class Args {
   constructor(
     argv,
-    flags = ['sarif', 'offline', 'help', 'version'],
-    options = ['suppress']
+    flags = ['sarif', 'offline', 'help', 'version', 'hints'],
+    options = ['suppress', 'openai-http-header']
   ) {
     this.flags = flags;
     this.options = options;
@@ -44,12 +48,28 @@ 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(','))
       .map((name) => name.trim())
       .filter((name) => name !== '');
   }
+  headers() {
+    return [].concat(this.parsed['openai-http-header'] || [])
+      .map(String)
+      .map((line) => line.trim())
+      .filter((line) => line !== '')
+      .reduce((acc, line) => {
+        const at = line.indexOf(':');
+        if (at < 0) {
+          throw new Error(`Malformed header "${line}", expected "Name: Value"`);
+        }
+        return {...acc, [line.slice(0, at).trim()]: line.slice(at + 1).trim()};
+      }, {});
+  }
   paths() {
     return this.parsed._.concat(this.parsed['--']).map(String);
   }

package/src/defaults.js

@@ -0,0 +1,47 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/**
+ * Defaults.
+ *
+ * The default command-line options pulled from a `.dogent` file. Dogent looks
+ * first in the current directory, then in the user home, and reads the first
+ * file it finds. Each line names one option, written exactly as typed on the
+ * command line, with its value after a space. A blank line vanishes, and a
+ * line that opens with `#` reads as a comment. These options sit ahead of the
+ * real argv, so any flag typed by hand overrides the file.
+ */
+class Defaults {
+  constructor(
+    dirs = [process.cwd(), os.homedir()],
+    exists = (file) => fs.existsSync(file),
+    reader = (file) => fs.readFileSync(file, 'utf8')
+  ) {
+    this.dirs = dirs;
+    this.exists = exists;
+    this.reader = reader;
+  }
+  argv() {
+    const file = this.dirs
+      .map((dir) => path.join(dir, '.dogent'))
+      .find((candidate) => this.exists(candidate));
+    if (!file) {
+      return [];
+    }
+    return this.reader(file)
+      .split('\n')
+      .map((line) => line.trim())
+      .filter((line) => line !== '' && !line.startsWith('#'))
+      .flatMap((line) => line.split(/\s+/u));
+  }
+}
+
+module.exports = Defaults;

package/src/dogent.js

@@ -8,6 +8,7 @@
 
 const fs = require('fs');
 const Args = require('./args');
+const Defaults = require('./defaults');
 const Markdown = require('./markdown');
 const Report = require('./report');
 const Sources = require('./sources');
@@ -18,9 +19,9 @@ const prettyMs = require('pretty-ms');
 const version = require('./version');
 const rules = require('./rules');
 
-const args = new Args(process.argv.slice(2));
+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);
@@ -33,8 +34,13 @@ 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'
+    '  --help     show this help and exit\n\n' +
+    'Defaults:\n' +
+    '  A .dogent file in the current directory or home holds default\n' +
+    '  options, one per line; options typed by hand override it.\n'
   );
   process.exit(0);
 }
@@ -44,12 +50,29 @@ if (unknown.length > 0) {
   process.stderr.write(`${banner}\n`);
   process.exit(2);
 }
+let headers = {};
+try {
+  headers = args.headers();
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exit(2);
+}
 const paths = args.paths();
 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`);
@@ -65,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(
@@ -72,7 +96,11 @@ const audit = async (docs) => {
     new Openai(
       key,
       process.env.OPENAI_MODEL || 'gpt-4o-mini',
-      (url, options) => globalThis.fetch(url, options)
+      process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1',
+      (url, options) => globalThis.fetch(
+        url,
+        {...options, headers: {...options.headers, ...headers}}
+      )
     )
   );
   const replies = await Promise.all(docs.map((doc) => oracle.violations(doc)));
@@ -84,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) {
@@ -108,5 +155,5 @@ const verify = async () => {
       process.exit(2);
     }
   }
-  finish(outcome.usage, outcome.aiMillis);
+  render(outcome);
 })();

package/src/openai.js

@@ -10,20 +10,23 @@ 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
- * paired with a Usage tally of the model and the tokens it consumed.
+ * A thin adapter over an OpenAI-compatible chat-completions endpoint.
+ * Sends one 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 base URL is configurable, so the same adapter reaches OpenAI itself
+ * or any compatible server, such as vLLM, Ollama, or a private gateway.
  * The transport is injected so the class runs in tests without a socket.
  */
 class Openai {
-  constructor(key, model, transport) {
+  constructor(key, model, base, transport) {
     this.key = key;
     this.model = model;
+    this.base = base;
     this.transport = transport;
   }
   async answer(prompt) {
     const response = await this.transport(
-      'https://api.openai.com/v1/chat/completions',
+      `${this.base.replace(/\/+$/u, '')}/chat/completions`,
       {
         method: 'POST',
         headers: {

package/src/prompt.js

@@ -41,10 +41,6 @@ class Prompt {
       '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',

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

@@ -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');
+const mask = require('../mask');
+
+/**
+ * AmbiguousOr.
+ *
+ * An "either-or" choice left to the reader is an instruction the agent
+ * cannot follow without guessing. This flags the literal "and/or" and a
+ * two-term slashed alternative like "tabs/spaces", each demanding the
+ * author pick one branch and state exactly which option applies. Inline
+ * code is masked first, so a backticked path such as `src/app` never
+ * matches. Subtler ambiguities stay with the oracle; prompt() defers
+ * the open-ended either-or judgement to it.
+ */
+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`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const masked = mask(text);
+    const pattern = /\band\/or\b|(?<![\w./])[A-Za-z]{2,}\/[A-Za-z]{2,}(?![\w/]|\.\w)/giu;
+    const found = [];
+    let hit = pattern.exec(masked);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'warning',
+        `ambiguous "${hit[0]}", state exactly which option applies`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = pattern.exec(masked);
+    }
+    return found;
+  }
+}
+
+module.exports = AmbiguousOr;

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`;
   }