@noir-ai/skills 1.16.0 → 1.17.0

package/builtin/noir-over-engineering-review/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: noir-over-engineering-review
+description: Use when the user says "review for over-engineering", "what can we delete", "is this over-engineered", or "simplify". Review the current diff for reinvented stdlib, unneeded dependencies, speculative abstractions, and dead flexibility, one line per finding. Do NOT use for a correctness or security review (noir-verifying or noir-security), a read-only codebase search (noir-exploring), a project-health diagnostic (noir-doctor), or a whole-repo audit (noir-codebase-audit).
+metadata:
+  category: meta
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+---
+
+# noir-over-engineering-review
+
+Review the current diff for complexity that does not earn its place: code that reimplements the standard library, dependencies pulled in for what a few lines would cover, abstractions with one caller, and flexibility nothing uses. Report one line per finding so each can be cut on the spot.
+
+## When to use
+
+- The user says "review for over-engineering", "what can we delete", "is this over-engineered", or "simplify".
+- A diff has grown and the reviewer wants a deletion-first pass before the correctness pass.
+- **Do NOT use** for a correctness or security review (`noir-verifying`, `noir-security`), a read-only codebase search (`noir-exploring`), a project-health diagnostic (`noir-doctor`), or the whole-repo audit (`noir-codebase-audit`).
+
+## Procedure
+
+1. **Read the diff, not the file.** Scope findings to lines the change adds or touches. Existing complexity is out of scope unless the change depends on it.
+2. **Run the four checks in order:** reinvented stdlib, unneeded dependency, speculative abstraction, dead flexibility.
+3. **Write one line per finding.** Name the location, what to cut, and what replaces it. For example: `src/parse.ts:12 hand-rolled slug regex; replace with the slug helper in src/text.ts`.
+4. **Stop at deletion.** When the fix is "delete the thing", write that and move on. A finding that needs a paragraph to justify is not ready to cut today.
+
+## Verification
+
+- [ ] Every finding names a location, the thing to cut, and what replaces it.
+- [ ] Findings cover only lines the diff adds or touches.
+- [ ] No finding is a correctness bug; those go to `noir-verifying`.
+- [ ] Each finding is one line; anything longer was rewritten to fit.
+
+## Notes
+
+- Deletion over rewriting: a wrapper that adds nothing gets deleted, not described.
+- A factory for one product, an interface with one implementation, a config knob nobody turns: all delete.
+- Report the highest-value cuts first; the reader may stop after the first three.
+
+## When done → next skill
+
+→ `noir-verifying` to confirm the deletions left the behavior intact. Or `noir-codebase-audit` for the whole-repo pass.

package/builtin/noir-readme/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: noir-readme
-description: Use when generating or updating a project README or documentation from the codebase — keeping docs accurate. Use when the user says "write a README" or "update the docs"; when a new feature ships.
+description: Use when generating or updating a project README or documentation from the codebase — keeping docs accurate. Use when the user says "write a README" or "update the docs"; when a new feature ships. Do NOT use for the code or spec itself; that work belongs to noir-executing-plans or noir-spec.
 metadata:
   category: document
   version: 1.0.0

package/builtin/noir-rules/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: noir-rules
-description: Use when reviewing or editing the project's AI working-rules (.noir/rules/RULES.md) — decide whether a directive belongs in the always-on contract vs a skill, a memory, or an ADR. Use when the user says "update the rules" or "add a rule".
+description: Use when reviewing or editing the project's AI working-rules (.noir/rules/RULES.md) — decide whether a directive belongs in the always-on contract vs a skill, a memory, or an ADR. Use when the user says "update the rules" or "add a rule". Do NOT use for a directive that applies only sometimes; that belongs in a skill or memory, not the always-on contract.
 metadata:
   category: meta
   version: 1.0.0

package/builtin/noir-security/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: noir-security
-description: Use when reviewing code for security vulnerabilities — injection, auth, SSRF, data exposure, and supply chain risks. Use when the user says "security review" or "audit this for security"; before shipping a feature that handles user input, auth, or sensitive data.
+description: Use when reviewing code for security vulnerabilities — injection, auth, SSRF, data exposure, and supply chain risks. Use when the user says "security review" or "audit this for security"; before shipping a feature that handles user input, auth, or sensitive data. Do NOT use for general code review or style; use noir-codebase-audit.
 metadata:
   category: verify
   version: 1.0.0

package/builtin/noir-worktree/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: noir-worktree
-description: Use when creating an isolated git workspace for feature work — keeping the main checkout clean. Use when the user says "worktree" or "isolate this work".
+description: Use when creating an isolated git workspace for feature work — keeping the main checkout clean. Use when the user says "worktree" or "isolate this work". Do NOT use for a plain branch switch or commit; use git directly.
 metadata:
   category: git
   version: 1.0.0

package/dist/index.d.ts

@@ -294,6 +294,13 @@ declare const HYGIENE_RULES: readonly HygieneRule[];
  *  Pure and deterministic: each pattern is recompiled per call, so no
  *  `lastIndex` state escapes and the same text always gives the same findings. */
 declare function checkHygiene(text: string, kind: HygieneKind): HygieneFinding[];
+/** Whether `text` carries the exemption marker for `kind` above the first
+ *  finding the hygiene rules report, so every rule — the prose finders
+ *  included — leaves the file alone. The prose finders run outside
+ *  `checkHygiene`, so consumers that run them gate the file on this predicate
+ *  rather than on `checkHygiene`'s findings. A marker placed at or below the
+ *  first finding exempts nothing. */
+declare function hasHygieneExemption(text: string, kind: HygieneKind): boolean;
 
 /** The SKILL.md body — the markdown after the YAML frontmatter block. The
  *  frontmatter is metadata the host reads on its own; the body is the playbook
@@ -485,6 +492,8 @@ declare function evaluateSuite(suite: EvalSuite, candidates?: CandidateOutputs):
     failures: string[];
 }>;
 
+declare function humanizerFindings(text: string): HygieneFinding[];
+
 /** Auth shape. Locked: `env-var` only until keychain lands (refuse OAuth,
  *  never silently lower the security bar). `fallback:'manual-paste'` keeps the
  *  no-token path honest (the playbook tells the user to paste a value); `'none'`
@@ -631,4 +640,11 @@ declare const FORBIDDEN_RESIDUE: readonly string[];
  *  never the only thing matching a line. */
 declare const RESIDUE_RULES: readonly HygieneRule[];
 
-export { BUILTIN_DIR, type BuiltinReference, type BuiltinSkill, type CandidateOutputs, type CompileTarget, type CompiledIntegration, type CompiledSkill, EVALS_DIR, type EmitSummary, type EmittedFile, type EvalAssertion, type EvalSuite, FORBIDDEN_RESIDUE, HYGIENE_EXEMPT_MARKERS, HYGIENE_RULES, type HygieneFinding, type HygieneKind, type HygieneRule, type HygieneTier, INTEGRATIONS_DIR, IntegrationAuthSchema, type IntegrationDeclaration$1 as IntegrationDeclaration, IntegrationDeclarationSchema, IntegrationMcpSchema, IntegrationSddSchema, type IntegrationSkill, MAX_BODY_LINES, MAX_COMMENT_BLOCK_LINES, MIN_FULL_BODY_LINES, NOIR_NAMESPACE, RESIDUE_RULES, type SkillConflict, type SkillEval, type SkillFrontmatter, type SkillRegistryEntry, type ValidationResult, bodyOf, buildRegistry, chainedReferences, checkHygiene, compileIntegration, compileSkill, discoverAll, discoverBuiltin, discoverIntegrations, emitSkillsToDir, evaluateSuite, isWhatWhenDescription, lintSkill, lintWarnings, loadEvalSuites, looksLikeWhenDescription, missingSections, parseEvalSuite, parseFrontmatter, parseIntegration, registryByCategory, runAssertions, runtimeEmitsHostMcp, validateIntegration, validateSkill, withinLineBudget };
+declare const KILL_ON_SIGHT: readonly ["delve", "utilize", "leverage", "facilitate", "elucidate", "embark", "endeavor", "encompass", "multifaceted", "tapestry", "testament", "paradigm", "synergy", "holistic", "catalyze", "juxtapose", "realm", "landscape", "myriad", "plethora"];
+declare const CLUSTER_WORDS: readonly ["robust", "comprehensive", "seamless", "cutting-edge", "innovative", "streamline", "empower", "foster", "enhance", "elevate", "optimize", "scalable", "pivotal", "intricate", "profound", "resonate", "underscore", "harness", "navigate", "cultivate", "bolster", "galvanize", "cornerstone", "game-changer"];
+declare const FILLER_PHRASES: readonly ["it is important to note", "it's important to note", "it is worth noting", "in today's", "in conclusion", "needless to say"];
+declare const SLOP_TRIGRAMS: readonly ["a testament to", "a tapestry of", "in the realm of", "the power of", "serves as a", "in order to", "the fact that", "plays a crucial"];
+declare const SLOP_ALLOWLIST: readonly string[];
+declare function slopFindings(text: string): HygieneFinding[];
+
+export { BUILTIN_DIR, type BuiltinReference, type BuiltinSkill, CLUSTER_WORDS, type CandidateOutputs, type CompileTarget, type CompiledIntegration, type CompiledSkill, EVALS_DIR, type EmitSummary, type EmittedFile, type EvalAssertion, type EvalSuite, FILLER_PHRASES, FORBIDDEN_RESIDUE, HYGIENE_EXEMPT_MARKERS, HYGIENE_RULES, type HygieneFinding, type HygieneKind, type HygieneRule, type HygieneTier, INTEGRATIONS_DIR, IntegrationAuthSchema, type IntegrationDeclaration$1 as IntegrationDeclaration, IntegrationDeclarationSchema, IntegrationMcpSchema, IntegrationSddSchema, type IntegrationSkill, KILL_ON_SIGHT, MAX_BODY_LINES, MAX_COMMENT_BLOCK_LINES, MIN_FULL_BODY_LINES, NOIR_NAMESPACE, RESIDUE_RULES, SLOP_ALLOWLIST, SLOP_TRIGRAMS, type SkillConflict, type SkillEval, type SkillFrontmatter, type SkillRegistryEntry, type ValidationResult, bodyOf, buildRegistry, chainedReferences, checkHygiene, compileIntegration, compileSkill, discoverAll, discoverBuiltin, discoverIntegrations, emitSkillsToDir, evaluateSuite, hasHygieneExemption, humanizerFindings, isWhatWhenDescription, lintSkill, lintWarnings, loadEvalSuites, looksLikeWhenDescription, missingSections, parseEvalSuite, parseFrontmatter, parseIntegration, registryByCategory, runAssertions, runtimeEmitsHostMcp, slopFindings, validateIntegration, validateSkill, withinLineBudget };

package/dist/index.js

@@ -109,6 +109,16 @@ function discoverAll(opts = {}) {
 // src/quality.ts
 import { ARTIFACT_TYPES } from "@noir-ai/core";
 
+// src/debt-marker.ts
+var DEBT_MARKER_RULE = {
+  id: "noir-debt",
+  tier: "warn",
+  appliesTo: "code",
+  pattern: /(?:^[ \t]*|[ \t])(?:\/\/|#|\/\*|\*)[ \t]*noir-debt:(?!.*\b(?:when|if|once)\b)/m,
+  rationale: "a debt marker without a ceiling or upgrade trigger is an un-trackable shortcut",
+  fix: "name the ceiling and the condition that justifies the upgrade"
+};
+
 // src/residue.ts
 var RESIDUE = [
   {
@@ -338,6 +348,7 @@ var HYGIENE_RULES = [
   IRREGULAR_SCRIPT_IN_TEXT,
   LONG_COMMENT_BLOCK,
   BARE_TODO,
+  DEBT_MARKER_RULE,
   ...RESIDUE_RULES
 ];
 function checkHygiene(text, kind) {
@@ -346,6 +357,12 @@ function checkHygiene(text, kind) {
   if (exemptAt !== 0 && exemptAt < (findings[0]?.line ?? Number.POSITIVE_INFINITY)) return [];
   return findings;
 }
+function hasHygieneExemption(text, kind) {
+  const exemptAt = exemptionLine(text, kind);
+  if (exemptAt === 0) return false;
+  const firstFinding = collectFindings(text, kind)[0];
+  return exemptAt < (firstFinding?.line ?? Number.POSITIVE_INFINITY);
+}
 function collectFindings(text, kind) {
   const lineStarts = lineStartOffsets(text);
   const findings = [];
@@ -1009,6 +1026,86 @@ function evaluateSuite(suite, candidates) {
   });
 }
 
+// src/humanizer.ts
+var HEDGES = [
+  "it is worth mentioning",
+  "it should be noted",
+  "it goes without saying",
+  "arguably"
+];
+var EM_DASH_PER_PARAGRAPH = 2;
+function proseOnly(text) {
+  return text.replace(/```[\s\S]*?```/g, "");
+}
+function lineOf(text, index) {
+  let line = 1;
+  for (let i = 0; i < index; i++) if (text[i] === "\n") line++;
+  return line;
+}
+function firstMatch(text, re) {
+  const match = re.exec(text);
+  return match ? match.index : -1;
+}
+function* paragraphsOf(text) {
+  let paragraph = "";
+  let startLine = 1;
+  let line = 1;
+  for (const raw of text.split("\n")) {
+    if (raw.trim() === "") {
+      if (paragraph.trim() !== "") yield { text: paragraph, line: startLine };
+      paragraph = "";
+      startLine = line + 1;
+    } else {
+      if (paragraph === "") startLine = line;
+      paragraph += (paragraph === "" ? "" : "\n") + raw;
+    }
+    line++;
+  }
+  if (paragraph.trim() !== "") yield { text: paragraph, line: startLine };
+}
+function humanizerFindings(text) {
+  const prose = proseOnly(text);
+  const findings = [];
+  for (const hedge of HEDGES) {
+    const index = firstMatch(prose, new RegExp(hedge, "i"));
+    if (index !== -1) {
+      findings.push({
+        id: "humanizer-hedge",
+        tier: "warn",
+        line: lineOf(prose, index),
+        text: hedge,
+        rationale: "a hedging opener",
+        fix: "delete it"
+      });
+    }
+  }
+  const contrastIndex = firstMatch(prose, /\bnot\s+\w+[\w\s,]{0,40}\bbut\b/i);
+  if (contrastIndex !== -1) {
+    findings.push({
+      id: "humanizer-contrast",
+      tier: "warn",
+      line: lineOf(prose, contrastIndex),
+      text: "not X but Y",
+      rationale: "a formulaic contrast",
+      fix: "state the second clause alone"
+    });
+  }
+  for (const { text: paragraph, line } of paragraphsOf(prose)) {
+    const count = (paragraph.match(/—/g) ?? []).length;
+    if (count > EM_DASH_PER_PARAGRAPH) {
+      findings.push({
+        id: "humanizer-em-dash",
+        tier: "warn",
+        line,
+        text: `${count} em-dashes`,
+        rationale: "em-dash density is an AI tell",
+        fix: "use periods or parentheticals"
+      });
+    }
+  }
+  return findings;
+}
+
 // src/registry.ts
 var NOIR_NAMESPACE = "noir-";
 function fallbackCategory(name) {
@@ -1043,9 +1140,160 @@ function buildRegistry() {
 function registryByCategory(category) {
   return buildRegistry().filter((e) => e.category === category);
 }
+
+// src/slop.ts
+var KILL_ON_SIGHT = [
+  "delve",
+  "utilize",
+  "leverage",
+  "facilitate",
+  "elucidate",
+  "embark",
+  "endeavor",
+  "encompass",
+  "multifaceted",
+  "tapestry",
+  "testament",
+  "paradigm",
+  "synergy",
+  "holistic",
+  "catalyze",
+  "juxtapose",
+  "realm",
+  "landscape",
+  "myriad",
+  "plethora"
+];
+var CLUSTER_WORDS = [
+  "robust",
+  "comprehensive",
+  "seamless",
+  "cutting-edge",
+  "innovative",
+  "streamline",
+  "empower",
+  "foster",
+  "enhance",
+  "elevate",
+  "optimize",
+  "scalable",
+  "pivotal",
+  "intricate",
+  "profound",
+  "resonate",
+  "underscore",
+  "harness",
+  "navigate",
+  "cultivate",
+  "bolster",
+  "galvanize",
+  "cornerstone",
+  "game-changer"
+];
+var FILLER_PHRASES = [
+  "it is important to note",
+  "it's important to note",
+  "it is worth noting",
+  "in today's",
+  "in conclusion",
+  "needless to say"
+];
+var SLOP_TRIGRAMS = [
+  "a testament to",
+  "a tapestry of",
+  "in the realm of",
+  "the power of",
+  "serves as a",
+  "in order to",
+  "the fact that",
+  "plays a crucial"
+];
+var SLOP_ALLOWLIST = ["harness"];
+function proseOnly2(text) {
+  return text.replace(/```[\s\S]*?```/g, "");
+}
+function wordRe(word) {
+  return new RegExp(`\\b${word.replace(/[-']/g, "[-\\s]?")}\\b`, "i");
+}
+var CLUSTER_THRESHOLD = 3;
+function lineOf2(text, index) {
+  let line = 1;
+  for (let i = 0; i < index; i++) if (text[i] === "\n") line++;
+  return line;
+}
+function firstMatch2(text, re) {
+  const match = re.exec(text);
+  return match ? match.index : -1;
+}
+function* paragraphsOf2(text) {
+  let paragraph = "";
+  let startLine = 1;
+  let line = 1;
+  for (const raw of text.split("\n")) {
+    if (raw.trim() === "") {
+      if (paragraph.trim() !== "") yield { text: paragraph, line: startLine };
+      paragraph = "";
+      startLine = line + 1;
+    } else {
+      if (paragraph === "") startLine = line;
+      paragraph += (paragraph === "" ? "" : "\n") + raw;
+    }
+    line++;
+  }
+  if (paragraph.trim() !== "") yield { text: paragraph, line: startLine };
+}
+function slopFindings(text) {
+  const prose = proseOnly2(text);
+  const findings = [];
+  for (const word of KILL_ON_SIGHT) {
+    if (SLOP_ALLOWLIST.includes(word)) continue;
+    const index = firstMatch2(prose, wordRe(word));
+    if (index !== -1) {
+      findings.push({
+        id: "slop-kill",
+        tier: "warn",
+        line: lineOf2(prose, index),
+        text: word,
+        rationale: "a word LLMs overuse, flagged on first use",
+        fix: `replace "${word}" with a plain verb or noun`
+      });
+    }
+  }
+  for (const { text: paragraph, line } of paragraphsOf2(prose)) {
+    const hits = CLUSTER_WORDS.filter(
+      (w) => !SLOP_ALLOWLIST.includes(w) && wordRe(w).test(paragraph)
+    ).length;
+    if (hits >= CLUSTER_THRESHOLD) {
+      findings.push({
+        id: "slop-cluster",
+        tier: "warn",
+        line,
+        text: `${hits} cluster words`,
+        rationale: "a paragraph dense with abstract praise reads machine-written",
+        fix: "rewrite in concrete terms; keep at most one such word"
+      });
+    }
+  }
+  for (const phrase of [...FILLER_PHRASES, ...SLOP_TRIGRAMS]) {
+    const index = firstMatch2(prose, new RegExp(phrase.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i"));
+    if (index !== -1) {
+      findings.push({
+        id: "slop-phrase",
+        tier: "warn",
+        line: lineOf2(prose, index),
+        text: phrase,
+        rationale: "a filler phrase or slop trigram",
+        fix: "delete it or state the point directly"
+      });
+    }
+  }
+  return findings;
+}
 export {
   BUILTIN_DIR,
+  CLUSTER_WORDS,
   EVALS_DIR,
+  FILLER_PHRASES,
   FORBIDDEN_RESIDUE,
   HYGIENE_EXEMPT_MARKERS,
   HYGIENE_RULES,
@@ -1054,11 +1302,14 @@ export {
   IntegrationDeclarationSchema,
   IntegrationMcpSchema,
   IntegrationSddSchema,
+  KILL_ON_SIGHT,
   MAX_BODY_LINES,
   MAX_COMMENT_BLOCK_LINES,
   MIN_FULL_BODY_LINES,
   NOIR_NAMESPACE,
   RESIDUE_RULES,
+  SLOP_ALLOWLIST,
+  SLOP_TRIGRAMS,
   bodyOf,
   buildRegistry,
   chainedReferences,
@@ -1070,6 +1321,8 @@ export {
   discoverIntegrations,
   emitSkillsToDir,
   evaluateSuite,
+  hasHygieneExemption,
+  humanizerFindings,
   isWhatWhenDescription,
   lintSkill,
   lintWarnings,
@@ -1082,6 +1335,7 @@ export {
   registryByCategory,
   runAssertions,
   runtimeEmitsHostMcp,
+  slopFindings,
   validateIntegration,
   validateSkill,
   withinLineBudget