@noir-ai/skills 1.15.0 → 1.16.0

package/dist/index.js

@@ -108,6 +108,306 @@ function discoverAll(opts = {}) {
 
 // src/quality.ts
 import { ARTIFACT_TYPES } from "@noir-ai/core";
+
+// src/residue.ts
+var RESIDUE = [
+  {
+    token: "workflow/<task",
+    why: "Names a state file of the removed workflow plugin, which nothing in this repository reads."
+  },
+  {
+    token: "noir-workflow.mode",
+    why: "Names the mode flag of the removed workflow plugin, which nothing in this repository reads."
+  },
+  {
+    token: "noir-workflow",
+    why: "Names the removed workflow plugin as a plugin or a path, so a reader following it finds nothing."
+  },
+  {
+    token: "@uiigateway",
+    why: "Names a package from the project this one was extracted from, which no consumer can resolve."
+  },
+  // 'ClickUp'/'clickup' were forbidden while the predecessor plugin was being
+  // ported, because the ClickUp REST precedent lived inside it. ClickUp now
+  // ships as a first-class integration, so the token names a legitimate
+  // subject and is deliberately absent from this list.
+  {
+    token: "<EXTREMELY-IMPORTANT",
+    why: "Copied rhetorical markup from the upstream tool, which carries no instruction a reader can follow."
+  },
+  {
+    token: "SUBAGENT-STOP",
+    why: "Copied rhetorical markup from the upstream tool, which carries no instruction a reader can follow."
+  },
+  {
+    token: "plugins/noir-workflow",
+    why: "Names the removed plugin path, which no longer exists in this repository."
+  }
+];
+var FORBIDDEN_RESIDUE = RESIDUE.map((entry) => entry.token);
+var RESIDUE_RULES = RESIDUE.map((entry) => ({
+  id: `residue-${entry.token.replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "").toLowerCase()}`,
+  tier: "fail",
+  pattern: new RegExp(`(?<![\\w-])${escapeForRegExp(entry.token)}(?![\\w-])`),
+  rationale: entry.why,
+  fix: "Remove the reference. If it named a mechanism, name the mechanism that replaced it.",
+  appliesTo: "both"
+}));
+function escapeForRegExp(literal2) {
+  return literal2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/hygiene.ts
+var HYGIENE_EXEMPT_MARKERS = {
+  code: "// noir-hygiene: exempt",
+  markdown: "<!-- noir-hygiene: exempt -->"
+};
+var MAX_COMMENT_BLOCK_LINES = 12;
+var MARKER = String.raw`(?:^[ \t]*|[ \t])(?:\/\/|#|\/\*|\*)`;
+var VARIATION_SELECTOR = String.fromCharCode(65039);
+var PICTOGRAPH = String.raw`[\u{1F300}-\u{1FAFF}]`;
+var DECORATION_EMOJI = `[\u26A0\u2705\u{1F389}\u2728\u{1F525}\u{1F680}\u{1F9E0}\u{1F4A1}\u{1F527}\u{1F4CC}]${VARIATION_SELECTOR}?`;
+var BACKTICK = String.fromCharCode(96);
+var QUOTE_OR_BACKTICK = `[${BACKTICK}'"]`;
+var MARKER_WORDS = ["TODO", "FIXME"];
+var REASON_WORDS = [
+  "because",
+  "since",
+  "until",
+  "once",
+  "when",
+  "unless",
+  "blocked",
+  "otherwise",
+  "revisit"
+];
+var OWNER = String.raw`(?:@[A-Za-z0-9_-]|\([A-Za-z][A-Za-z0-9_-]*\)|#\d+)`;
+var DECORATIVE_BANNER = {
+  id: "decorative-banner",
+  tier: "fail",
+  pattern: new RegExp(String.raw`${MARKER}[ \t]*[-=*_~]{4,}`, "m"),
+  rationale: "A divider drawn in punctuation marks a section for the person writing the file, not for the reader: it carries no information, and it makes the file read as machine output.",
+  fix: "Delete the divider. If the label names a section a reader needs, make it a heading or name it in the declaration below.",
+  appliesTo: "both"
+};
+var WORKFLOW_NARRATION = {
+  id: "workflow-narration",
+  tier: "fail",
+  pattern: new RegExp(
+    String.raw`${MARKER}[ \t]*(?:step[ \t]*\d+[ \t]*[:.)]|(?:first|second|third|then|next|finally|lastly)[ \t]*[,:](?![ \t]*(?:which|that|who)\b)(?![^\n]*\b(?:so|because|since)\b))`,
+    "im"
+  ),
+  rationale: "Numbered narration restates what the code already says in the order it already says it, and it goes stale the moment that order changes.",
+  fix: "Drop the step markers. Keep only what the code cannot show: why this order, which invariant is held, or what breaks otherwise.",
+  appliesTo: "code"
+};
+var DECORATIVE_EMOJI_IN_COMMENT = {
+  id: "decorative-emoji-comment",
+  tier: "fail",
+  pattern: new RegExp(
+    String.raw`${MARKER}[^\n]*(?<!${QUOTE_OR_BACKTICK})${DECORATION_EMOJI}(?!${VARIATION_SELECTOR}?${QUOTE_OR_BACKTICK})`,
+    "mu"
+  ),
+  rationale: "A decorative emoji in a comment adds no information a reader needs, and it is the clearest single sign that the text was generated rather than written.",
+  fix: "Remove the emoji and let the sentence carry the emphasis. If it marked a state, name the state in a word.",
+  appliesTo: "code"
+};
+var DECORATIVE_PICTOGRAPH = {
+  id: "decorative-pictograph-comment",
+  tier: "fail",
+  pattern: new RegExp(
+    String.raw`${MARKER}[ \t]*(?!${DECORATION_EMOJI})${PICTOGRAPH}${VARIATION_SELECTOR}?`,
+    "mu"
+  ),
+  rationale: "A comment that opens with a pictograph is decoration: the pictograph marks nothing a reader can act on, and it reads as a generated flourish.",
+  fix: "Remove the pictograph. If it stood for a state or a result, write that in words.",
+  appliesTo: "code"
+};
+var DECORATIVE_EMOJI_IN_PROSE = {
+  id: "decorative-emoji-doc",
+  tier: "fail",
+  pattern: new RegExp(
+    String.raw`^[ \t]{0,3}(?:#{1,6}[ \t]+)?(?:[-*+][ \t]+)?(?:${DECORATION_EMOJI}|${PICTOGRAPH}${VARIATION_SELECTOR}?)`,
+    "mu"
+  ),
+  rationale: "A heading or a bullet that opens with a decorative emoji spends a reader attention on the emoji and none of it on the point of the line.",
+  fix: "Remove the emoji and put the point of the line in its words.",
+  appliesTo: "markdown"
+};
+var IRREGULAR_SCRIPT_SOURCES = [
+  String.raw`\u{0370}-\u{03ff}`,
+  // Greek
+  String.raw`\u{1f00}-\u{1fff}`,
+  // Greek extended
+  String.raw`\u{0400}-\u{052f}`,
+  // Cyrillic and its supplement
+  String.raw`\u{2de0}-\u{2dff}`,
+  // Cyrillic extended A
+  String.raw`\u{a640}-\u{a69f}`,
+  // Cyrillic extended B
+  String.raw`\u{0590}-\u{05ff}`,
+  // Hebrew
+  String.raw`\u{0600}-\u{06ff}`,
+  // Arabic
+  String.raw`\u{0750}-\u{077f}`,
+  // Arabic supplement
+  String.raw`\u{fb1d}-\u{fb4f}`,
+  // Hebrew presentation forms
+  String.raw`\u{fb50}-\u{fdff}`,
+  // Arabic presentation forms A
+  String.raw`\u{fe70}-\u{feff}`,
+  // Arabic presentation forms B, and the byte-order mark
+  String.raw`\u{0900}-\u{097f}`,
+  // Devanagari
+  String.raw`\u{0e00}-\u{0e7f}`,
+  // Thai
+  String.raw`\u{1100}-\u{11ff}`,
+  // Hangul Jamo
+  String.raw`\u{2e80}-\u{2fdf}`,
+  // CJK radicals
+  String.raw`\u{3000}-\u{30ff}`,
+  // CJK symbols and punctuation, Hiragana, Katakana
+  String.raw`\u{3100}-\u{318f}`,
+  // Bopomofo, Hangul compatibility Jamo
+  String.raw`\u{31c0}-\u{31ef}`,
+  // CJK strokes and Katakana extensions
+  String.raw`\u{3200}-\u{33ff}`,
+  // Enclosed and compatibility CJK
+  String.raw`\u{3400}-\u{4dbf}`,
+  // CJK unified ideographs extension A
+  String.raw`\u{4e00}-\u{9fff}`,
+  // CJK unified ideographs
+  String.raw`\u{ac00}-\u{d7af}`,
+  // Hangul syllables
+  String.raw`\u{f900}-\u{faff}`,
+  // CJK compatibility ideographs
+  String.raw`\u{ff00}-\u{ffef}`,
+  // Fullwidth and halfwidth forms
+  String.raw`\u{200b}-\u{200f}`,
+  // Zero-width space, joiners and the bidirectional marks
+  String.raw`\u{202a}-\u{202e}`,
+  // Bidirectional embeddings and overrides
+  String.raw`\u{2066}-\u{2069}`,
+  // Bidirectional isolates
+  String.raw`\u{fffd}`,
+  // the replacement character
+  String.raw`\u{e000}-\u{f8ff}`,
+  // Private use area
+  String.raw`\u{f0000}-\u{ffffd}`,
+  // Private use planes 15 and 16
+  String.raw`\u{100000}-\u{10fffd}`
+  // Private use plane 17
+];
+var IRREGULAR_SCRIPT = `[${IRREGULAR_SCRIPT_SOURCES.join("")}]`;
+var IRREGULAR_SCRIPT_IN_TEXT = {
+  id: "no-irregular-script",
+  tier: "fail",
+  pattern: new RegExp(IRREGULAR_SCRIPT, "u"),
+  rationale: "Generated text can leak a token from another script, or carry the bytes a mis-decoding turned into a replacement or invisible character. Either way the reader is shown something the writer never meant to say.",
+  fix: "Rewrite the text in the project language, and delete the invisible character. Keep a character from another script only in a deliberate fixture, which states its own exemption with the marker above.",
+  appliesTo: "both"
+};
+var LONG_COMMENT_BLOCK = {
+  id: "long-comment-block",
+  tier: "warn",
+  pattern: new RegExp(
+    String.raw`(?:^[ \t]*(?:\/\/|\/\*|\*|#[ \t])(?![ \t]*[-=*_~]{4})[ \t]*\S[^\n]*(?:\n|$)){${MAX_COMMENT_BLOCK_LINES},}`,
+    "m"
+  ),
+  rationale: `A run of ${MAX_COMMENT_BLOCK_LINES} or more comment lines with no break between them is usually narration or a restatement of the code below it, which a reader skips and which drifts out of date.`,
+  fix: "Cut the block to the part a reader cannot get from the code, and move reference detail into the document that owns it.",
+  appliesTo: "code"
+};
+var BARE_TODO = {
+  id: "bare-todo",
+  tier: "warn",
+  pattern: new RegExp(
+    String.raw`${MARKER}[ \t]*(?:${MARKER_WORDS.join("|")})\b(?![^\n]*${OWNER})(?![^\n]*\b(?:${REASON_WORDS.join("|")})\b)`,
+    "im"
+  ),
+  rationale: "A TODO with no owner and no reason cannot be acted on: no one knows who will do it, or what would make it unnecessary.",
+  fix: 'Name an owner or a tracked issue and the condition that retires the marker, such as "revisit once the v2 client lands".',
+  appliesTo: "code"
+};
+var HYGIENE_RULES = [
+  DECORATIVE_BANNER,
+  WORKFLOW_NARRATION,
+  DECORATIVE_EMOJI_IN_COMMENT,
+  DECORATIVE_PICTOGRAPH,
+  DECORATIVE_EMOJI_IN_PROSE,
+  IRREGULAR_SCRIPT_IN_TEXT,
+  LONG_COMMENT_BLOCK,
+  BARE_TODO,
+  ...RESIDUE_RULES
+];
+function checkHygiene(text, kind) {
+  const findings = collectFindings(text, kind);
+  const exemptAt = exemptionLine(text, kind);
+  if (exemptAt !== 0 && exemptAt < (findings[0]?.line ?? Number.POSITIVE_INFINITY)) return [];
+  return findings;
+}
+function collectFindings(text, kind) {
+  const lineStarts = lineStartOffsets(text);
+  const findings = [];
+  for (const rule of HYGIENE_RULES) {
+    if (rule.appliesTo !== "both" && rule.appliesTo !== kind) continue;
+    let reportedLine = 0;
+    for (const match of text.matchAll(globalPattern(rule.pattern))) {
+      const line = lineNumberAt(lineStarts, match.index ?? 0);
+      if (line === reportedLine) continue;
+      reportedLine = line;
+      findings.push({
+        id: rule.id,
+        tier: rule.tier,
+        line,
+        text: lineTextAt(text, lineStarts, line),
+        rationale: rule.rationale,
+        fix: rule.fix
+      });
+    }
+  }
+  return findings.sort((a, b) => a.line - b.line);
+}
+function exemptionLine(text, kind) {
+  const marker = HYGIENE_EXEMPT_MARKERS[kind];
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) if ((lines[i] ?? "").trim() === marker) return i + 1;
+  return 0;
+}
+function lineStartOffsets(text) {
+  const starts = [0];
+  for (let i = text.indexOf("\n"); i !== -1; i = text.indexOf("\n", i + 1)) starts.push(i + 1);
+  return starts;
+}
+function lineNumberAt(lineStarts, index) {
+  let low = 0;
+  let high = lineStarts.length - 1;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if ((lineStarts[mid] ?? 0) <= index) low = mid;
+    else high = mid - 1;
+  }
+  return low + 1;
+}
+function lineTextAt(text, lineStarts, line) {
+  const start = lineStarts[line - 1] ?? 0;
+  const end = text.indexOf("\n", start);
+  return text.slice(start, end === -1 ? text.length : end).trim();
+}
+function globalPattern(pattern) {
+  const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
+  return new RegExp(pattern.source, flags);
+}
+
+// src/quality.ts
+function bodyOf(md) {
+  return md.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+}
+function authoredBody(body) {
+  if (body.startsWith("\r\n")) return body.slice(2);
+  if (body.startsWith("\n")) return body.slice(1);
+  return body;
+}
 var MAX_BODY_LINES = 500;
 var MIN_FULL_BODY_LINES = 20;
 var WHEN_SECTION = /^## When to use$/im;
@@ -142,23 +442,24 @@ function looksLikeWhenDescription(description) {
 }
 function lintWarnings(skill) {
   const warnings = [];
-  const body = skill.skillMd;
+  const file = skill.skillMd;
+  const body = bodyOf(file);
   const bodyLines = body.split("\n").length;
-  if (bodyLines < MIN_FULL_BODY_LINES + 6) {
+  if (bodyLines < MIN_FULL_BODY_LINES) {
     warnings.push("thin-body: full playbook body is under 20 lines");
   }
   const hasExample = /```/.test(body) || /\bexample:?\b/i.test(body) || /\be\.g\.\b/i.test(body);
   if (!hasExample) {
     warnings.push("no-example: no concrete code fence or worked example in the body");
   }
-  if (/\b(I|we|you)\s+(will|should|can|need|must|do|write|create|implement|run|build)\b/i.test(body)) {
+  if (/\b(I|we|you)\s+(will|should|can|need|must|do|write|create|implement|run|build)\b/i.test(file)) {
     warnings.push("first-person: narration addresses the reader instead of imperative steps");
   }
-  if (/\b(?:wait|sleep|retry|backoff|limit|cap)\s+[a-z]*\s*(\d{1,4})\b/i.test(body) && !/because|to (avoid|prevent|give|let)/i.test(body)) {
+  if (/\b(?:wait|sleep|retry|backoff|limit|cap)\s+[a-z]*\s*(\d{1,4})\b/i.test(file) && !/because|to (avoid|prevent|give|let)/i.test(file)) {
     warnings.push("voodoo-constant: numeric threshold without a stated reason");
   }
-  const hasVersionPin = /as of \d{4}|\bversion \d+\.\d+\.\d+\b|"v\d+\.\d+"/i.test(body);
-  const hasLegacySection = /^## Legacy|^## Old patterns/i.test(body);
+  const hasVersionPin = /as of \d{4}|\bversion \d+\.\d+\.\d+\b|"v\d+\.\d+"/i.test(file);
+  const hasLegacySection = /^## Legacy|^## Old patterns/i.test(file);
   if (hasVersionPin && !hasLegacySection) {
     warnings.push("time-sensitive: version/date pin outside a Legacy section");
   }
@@ -202,6 +503,56 @@ function artifactPathDrift(skill) {
   }
   return [...drifts];
 }
+function splitFencedBlocks(body) {
+  const prose = [];
+  const code = [];
+  let closing = null;
+  for (const line of body.split("\n")) {
+    let boundary = false;
+    if (closing === null) {
+      const open = line.match(/^[ \t]{0,3}(`{3,}|~{3,})/);
+      const run = open?.[1];
+      if (run) {
+        const char = run[0] ?? "";
+        closing = new RegExp(`^[ \\t]{0,3}${char}{${run.length},}[ \\t]*$`);
+        boundary = true;
+      }
+    } else if (closing.test(line)) {
+      closing = null;
+      boundary = true;
+    }
+    const isCode = closing !== null && !boundary;
+    prose.push(isCode ? "" : line);
+    code.push(isCode ? line : "");
+  }
+  return { prose: prose.join("\n"), code: code.join("\n") };
+}
+function exemptionLine2(body) {
+  const marker = HYGIENE_EXEMPT_MARKERS.markdown;
+  const lines = body.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    if ((lines[i] ?? "").trim() === marker) return i + 1;
+  }
+  return 0;
+}
+function hygieneFindings(body) {
+  const text = authoredBody(body);
+  const { prose, code } = splitFencedBlocks(text);
+  const findings = [...checkHygiene(prose, "markdown"), ...checkHygiene(code, "code")];
+  const seen = /* @__PURE__ */ new Set();
+  const ordered = findings.filter((f) => {
+    const key = `${f.id}:${f.line}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  }).sort((a, b) => a.line - b.line);
+  const exemptAt = exemptionLine2(text);
+  if (exemptAt !== 0 && exemptAt < (ordered[0]?.line ?? Number.POSITIVE_INFINITY)) return [];
+  return ordered;
+}
+function hygieneMessage(finding) {
+  return `${finding.id} (line ${finding.line}): ${finding.rationale} ${finding.fix}`;
+}
 
 // src/compiler.ts
 var FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
@@ -218,9 +569,6 @@ function parseFrontmatter(md) {
   }
   return fm;
 }
-function bodyOf(md) {
-  return md.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
-}
 function validateSkill(skill) {
   const errors = [];
   const warnings = [];
@@ -253,6 +601,11 @@ function validateSkill(skill) {
     if (!r.content.trim()) errors.push(`reference "${r.name}" is empty`);
   }
   for (const d of artifactPathDrift(skill)) errors.push(d);
+  for (const finding of hygieneFindings(body)) {
+    const message = hygieneMessage(finding);
+    if (finding.tier === "fail") errors.push(message);
+    else warnings.push(message);
+  }
   warnings.push(...lintWarnings(skill));
   return { ok: errors.length === 0, errors, warnings: warnings.length > 0 ? warnings : void 0 };
 }
@@ -642,12 +995,18 @@ function loadEvalSuites(dir = EVALS_DIR) {
   }
   return suites;
 }
-function evaluateSuite(suite) {
-  return suite.evals.map((e) => ({
-    id: e.id,
-    pass: e.assertions ? runAssertions(e.expected_output, e.assertions).pass : true,
-    failures: e.assertions ? runAssertions(e.expected_output, e.assertions).failures : []
-  }));
+function evaluateSuite(suite, candidates) {
+  return suite.evals.map((e) => {
+    if (candidates && !(e.id in candidates)) {
+      return { id: e.id, pass: false, failures: [`no candidate output for eval "${e.id}"`] };
+    }
+    const output = candidates ? candidates[e.id] ?? e.expected_output : e.expected_output;
+    return {
+      id: e.id,
+      pass: e.assertions ? runAssertions(output, e.assertions).pass : true,
+      failures: e.assertions ? runAssertions(output, e.assertions).failures : []
+    };
+  });
 }
 
 // src/registry.ts
@@ -684,43 +1043,26 @@ function buildRegistry() {
 function registryByCategory(category) {
   return buildRegistry().filter((e) => e.category === category);
 }
-
-// src/residue.ts
-var FORBIDDEN_RESIDUE = [
-  "workflow/<task",
-  // predecessor state file
-  "noir-workflow.mode",
-  // predecessor mode flag
-  "noir-workflow",
-  // predecessor plugin name (as a plugin/path reference)
-  "@uiigateway",
-  // predecessor Angular specifics
-  // NOTE: 'ClickUp'/'clickup' were forbidden during the predecessor-port era (the
-  // ClickUp REST precedent lived in the deleted noir-workflow plugin). ClickUp is
-  // now reintroduced as a first-class Noir integration (skills/integrations/noir-clickup),
-  // so the token is no longer residue — it is the integration's legitimate subject.
-  "<EXTREMELY-IMPORTANT",
-  // Superpowers rhetoric
-  "SUBAGENT-STOP",
-  // Superpowers rhetoric
-  "plugins/noir-workflow"
-  // predecessor path
-];
 export {
   BUILTIN_DIR,
   EVALS_DIR,
   FORBIDDEN_RESIDUE,
+  HYGIENE_EXEMPT_MARKERS,
+  HYGIENE_RULES,
   INTEGRATIONS_DIR,
   IntegrationAuthSchema,
   IntegrationDeclarationSchema,
   IntegrationMcpSchema,
   IntegrationSddSchema,
   MAX_BODY_LINES,
+  MAX_COMMENT_BLOCK_LINES,
   MIN_FULL_BODY_LINES,
   NOIR_NAMESPACE,
+  RESIDUE_RULES,
   bodyOf,
   buildRegistry,
   chainedReferences,
+  checkHygiene,
   compileIntegration,
   compileSkill,
   discoverAll,