@noir-ai/skills 1.15.0 → 1.16.0-beta.1

package/README.md

@@ -1,6 +1,6 @@
 # @noir-ai/skills
 
-The native `noir-*` skill pack (26 builtins plus 1 integration) and a copy-and-validate compiler. `noir init` / `noir sync` emit it idempotently for hosts with a skill surface: Claude uses `.claude/skills/`; Cursor uses `.cursor/rules/*.mdc`. There is no plugin or marketplace.
+The native `noir-*` skill pack (27 builtins plus 1 integration) and a copy-and-validate compiler. `noir init` / `noir sync` emit it idempotently for hosts with a skill surface: Claude uses `.claude/skills/`; Cursor uses `.cursor/rules/*.mdc`. There is no plugin or marketplace.
 
 Part of the **[Noir](https://github.com/agaaaptr/noir#readme)** toolkit — the discipline, context, and memory layer for any agentic CLI.
 

package/builtin/noir-code-hygiene/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: noir-code-hygiene
+description: Use when writing or reviewing comments, docstrings, summaries, or documents — keep every line carrying something a reader can act on. Use when the user says "clean this up", "this reads like machine output", or asks for a comment sweep. Do NOT use for layout (indentation, quoting, line length); this is about what the text says.
+metadata:
+  category: meta
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+references:
+  - examples.md
+---
+
+# noir-code-hygiene
+
+Text that reads as machine-generated fails in a small number of ways, and every
+one of them is a sentence a reader cannot act on. The ten defects below are
+those ways, each as a Tell (what it looks like), a Why (what it costs a reader)
+and a Fix (what to write instead). Four of them — restating, stale text, jargon,
+unstated assumptions — are judgements a person makes; the rest are mechanical
+enough that the quality gate checks them itself.
+
+## When to use
+
+- Writing or reviewing a comment, docstring, summary, or document that a reader will meet without the context its author had.
+- Sweeping a file, a diff, or a report for text that reads as generated.
+- The user says "clean this up", "this reads like machine output", or asks for a comment sweep.
+- Reviewing your own output before handing it back: comments and summaries are where these defects concentrate.
+- **Do NOT use:** for layout (indentation, quoting, line length), or as a substitute for a formatter or a type checker. This is about what the text says, not how it is drawn.
+
+## Procedure
+
+1. **Read the text as somebody who did not write it.** For each sentence, ask what a reader learns that the code, the diff, or the line above does not already say. A sentence that teaches nothing is the one to delete.
+2. **Delete before rewriting.** Most defects end at deletion: a divider, a restated line, an empty label, a fact that is no longer true. Rewriting a comment that should not exist only makes the noise longer.
+3. **Keep what the code cannot say.** The reason a value is what it is, the invariant a caller depends on, the condition that would break the order, the precondition. When only a restatement would be left, the comment is finished.
+4. **Name things in the reader's terms.** Replace a codename, or a shorthand that resolves only against a planning document, with the mechanism it stood for. State the path, the command, or the precondition instead of assuming the reader knows it.
+5. **Run the gate.** `noir skills lint` over a skill body, `noir doctor` over a repository. Fix every fail-tier finding; read a warn-tier one as a question about the line rather than a rule to satisfy.
+
+## Tell / Why / Fix
+
+### Decorative separators and banners
+
+**Tell:** a line of punctuation used as a divider — a run of `=`, `-`, `*`, `_`,
+or `~` characters, with or without a label inside it — or a heading whose only
+job is to sit above another heading.
+
+**Why:** the divider marks a section for whoever wrote the file, not for a reader. It carries nothing, and it is the fastest way to make a file read as machine-written.
+
+**Fix:** delete it. If the label named something a reader needs, make it a heading in a document, or name it in the declaration the divider sat above.
+
+### Restating the obvious
+
+**Tell:** a comment that says what the line below does in the words the code already uses — a getter described as getting, a counter described as counting, a paragraph that repeats the sentence before it.
+
+**Why:** it doubles the reading cost, and it is the first thing to go stale: the code changes and the echo of it does not. A reader who learns the comments are redundant skips the one that matters.
+
+**Fix:** delete it. Keep a comment only when it carries something the code does not — why this value, what the caller relies on, which invariant holds.
+
+### Workflow narration
+
+**Tell:** a comment that walks a reader through the file in the order it runs, with ordinals as markers, or a summary that lists a function's statements in sequence.
+
+**Why:** the code already gives the order, and it gives the true one. The narration goes stale the moment the order changes, and a reader takes it as a promise about behavior.
+
+**Fix:** drop the markers. Keep only what the code cannot show: why this order, which invariant the order holds, or what breaks when it changes.
+
+### Empty labels
+
+**Tell:** a heading, a comment, or a field that names a category and stops — a lone label above nothing, a section with no content under it, a marker recorded with no owner and no reason.
+
+**Why:** a label promises information. A reader pays to open it, finds nothing, and learns to skip the next one.
+
+**Fix:** delete it, or say the thing: what is set up and by whom, what the note adds, what would retire the marker.
+
+### Stale comments
+
+**Tell:** a comment that described the code before an edit — a parameter that no longer exists, a step that no longer happens, a docstring for behavior that has changed, a stated limit the constant beside it contradicts.
+
+**Why:** worse than no comment at all. A wrong comment is trusted, and the reader who acts on it investigates the wrong thing.
+
+**Fix:** when the code changes, read the comment above it in the same edit. Delete what no longer holds, rewrite what changed meaning. A comment is part of the change, not a leftover from it.
+
+### Decorative icons and emoji
+
+**Tell:** an emoji or pictograph used as a bullet, as a heading prefix, as a status flourish in a comment, or as a symbol standing in for a word — a check mark for done, a warning sign for careful.
+
+**Why:** the glyph takes attention and returns none of it, it renders differently or not at all across terminals and fonts, and it announces the text as generated. In output a screen reader reads aloud, it is noise in the middle of a sentence.
+
+**Fix:** remove it and let the words carry the meaning. A glyph that is part of a program's own output — a status badge, a CLI label — belongs inside the string that prints it, not in the text around the code.
+
+### Unexpected characters from another script
+
+**Tell:** a character from a writing system this project does not write in — Han,
+Kana, Hangul, Cyrillic, Greek, Arabic, Hebrew, Thai, Devanagari — or a fullwidth
+form, a zero-width space, a byte-order mark, a bidirectional override, or the
+replacement character a bad decode leaves behind. It turns up inside a word or a
+string, where no author would have typed it.
+
+**Why:** a model can leak a token from another script into generated text, and
+bytes that were decoded wrongly arrive as an invisible character or a
+replacement mark. Either way the reader is shown something nobody meant to
+write, and inside a string it can change what the code does.
+
+**Fix:** rewrite the text in the project's language and delete the invisible
+character; a deliberate fixture — a test that measures how a wide glyph is laid
+out, say — states its own exemption with the marker instead of the text keeping
+the character. `noir doctor`'s hygiene check reports these as failures.
+
+### Verbosity
+
+**Tell:** three sentences where one does; a preamble that restates the request; a summary of a summary; a dozen comment lines above a four-line function; a document that explains the same decision twice.
+
+**Why:** every extra sentence is a cost the reader pays before reaching the one that matters. Length also hides the defects above, because prose that repeats itself is prose nobody re-reads closely.
+
+**Fix:** cut to what the reader cannot get elsewhere, and move reference detail into the document that owns it, linked, instead of inlined.
+
+### Internal jargon
+
+**Tell:** a label that resolves only against a planning document — a task code, a milestone codename, a bare section citation, an abbreviation defined once in a note nobody keeps.
+
+**Why:** no reader of this file can resolve it, and it ties the source to a document that will be deleted. The code outlives the plan, so the shorthand ends up naming nothing at all.
+
+**Fix:** name the mechanism, the behavior, or the condition in self-contained words. When a code is the only handle that exists, give the fact it stood for beside it.
+
+### Unstated assumptions
+
+**Tell:** an instruction or a comment that works only if the reader already knows something the text does not say — the path, the file that has to exist first, the command, the environment, or the choice made silently between two options.
+
+**Why:** the reader either guesses, and a wrong guess surfaces as a bug somewhere else, or stops to ask. Both cost more than the sentence that would have prevented it.
+
+**Fix:** state it — the path, the command, the precondition, the reason for the choice. When the answer changes what the text should say, ask rather than pick one silently and leave the reader to find out.
+
+## Worked example
+
+The defects a pattern can catch are the easy half. This pair is the other half:
+neither snippet trips a rule, and the first one still wastes a reader's time.
+
+Before:
+
+```ts
+/** Fetches the user. */
+// NOTE: 30 second timeout because the gateway is slow.
+// Added during the checkout rewrite — see the planning note for context.
+// Gets the user by id from the client.
+export async function fetchUser(id: string): Promise<User> {
+  return client.get(`/users/${id}`, { timeoutMs: 5000 });
+}
+```
+
+After:
+
+```ts
+/**
+ * Loads a user. A healthy gateway answers in well under a second, so five
+ * seconds is the point past which the request is a hang rather than a slow
+ * read — the caller hears about it instead of waiting on nothing.
+ */
+export async function fetchUser(id: string): Promise<User> {
+  return client.get(`/users/${id}`, { timeoutMs: 5000 });
+}
+```
+
+The behavior is identical. What changed: the name restated as a sentence is
+gone, the timeout figure that contradicted the constant beside it is gone, and
+the two facts a reader cannot get from the expression — why the timeout exists
+and why it is this value — are all that is left. The codename went with them.
+
+## Enforcement
+
+Two commands run the same rules, so this guidance and the gate agree:
+
+- `noir skills lint` validates each shipped skill body. A fail-tier pattern is an error and exits non-zero; a warn-tier pattern is a warning and does not.
+- `noir doctor` scans the repository's own text — the root documents, `docs/` outside the planning corpus, `.claude/skills`, each package's `src` and `test` trees, and `scripts/` — reporting fail-tier findings in a failing row and warn-tier findings in a warning row. It exits non-zero whenever a fail-tier finding is present, so a repository's continuous integration can call it as its gate.
+
+The rules themselves are one table in the skills package, and each entry carries its tier, the reason the shape is noise, and the fix. Read the table when a line's status is unclear rather than working from memory.
+
+**The exemption marker.** Some files have to name what the rules forbid: the rule table, its fixtures, and the examples file this skill ships. Such a file states its own exemption with the marker the rules honour — the text `noir-hygiene: exempt` alone on a line above its first finding, written as a source comment in code and as an HTML comment in a document. The marker is a statement about the whole file, not a way to silence one line, so it belongs only where the prohibited shape is the subject. A file that carries it to keep a defect is worse off than the defect: the gate stops reporting it, and the reason it was written is now invisible.
+
+## Reference
+
+[examples.md](references/examples.md) carries a worked before/after pair for every defect above, the mechanical shapes the gate catches included — a divider, numbered narration, a decorative emoji, a marker nobody can act on.
+
+## Verification
+
+- [ ] Every sentence kept carries something the code, the diff, or the line above does not.
+- [ ] No divider, no restatement, no ordinal marker, no empty label survives the pass.
+- [ ] Every fact stated beside the code is true of the code as it stands now.
+- [ ] Every codename or shorthand is replaced by the mechanism it stood for.
+- [ ] The path, the command, and the precondition are stated rather than assumed.
+- [ ] `noir skills lint` (skill body) or `noir doctor` (repository) reports no fail-tier finding.
+
+## Notes
+
+- The tiers differ in what to do with a finding, not in whether the shape is real. A fail-tier pattern is never the right thing to write, so it is removed. A warn-tier one is a mechanical threshold too, but the shape is sometimes the right choice — a marker is sometimes the right note, a block sometimes the right length — so the tier asks a reviewer to look at the line rather than forbidding it.
+- Deleting is the most common fix. A file gets clearer by getting shorter, and a shorter file has fewer places to be wrong.
+- The standard covers what an agent reports back, not only what it writes into a file: a summary that narrates its own steps, or that repeats the request before answering it, is the same defect in a different medium.
+
+## When done → next skill
+
+→ `noir-verifying` to confirm the sweep left nothing broken. Or `noir-writing-skills` when the text being cleaned is a skill body.

package/builtin/noir-code-hygiene/references/examples.md

@@ -0,0 +1,248 @@
+<!-- Worked examples for the noir-code-hygiene skill.
+
+     This file exists to show the shapes the rules forbid, so it must contain
+     them. It therefore declares the exemption the rules honour with the marker
+     below, alone on its line and above the first finding.
+
+     The pairs follow the same shape as the skill: what arrives first, then the
+     same thing after the pass. The code is the same both times; what changes is
+     what the text says about it. -->
+<!-- noir-hygiene: exempt -->
+
+# Worked examples
+
+One pair per defect. The first snippet in each pair is what a draft or a
+generator tends to produce; the second is the same code after the pass the
+skill describes. Read the pair for the defect you met rather than the whole
+file.
+
+## Decorative separators and banners
+
+Before:
+
+```ts
+// ============================================================
+// ====================== Users ===============================
+// ============================================================
+
+/** Loads a user. The timeout bounds a hung request, not a healthy one. */
+export async function fetchUser(id: string): Promise<User> {
+  return client.get(`/users/${id}`, { timeoutMs: 5000 });
+}
+```
+
+After:
+
+```ts
+/** Loads a user. The timeout bounds a hung request, not a healthy one. */
+export async function fetchUser(id: string): Promise<User> {
+  return client.get(`/users/${id}`, { timeoutMs: 5000 });
+}
+```
+
+## Workflow narration
+
+Before:
+
+```ts
+async function sync(): Promise<void> {
+  // Step 1: read the config.
+  const cfg = await readConfig();
+  // Step 2: resolve the profile named on the command line.
+  const profile = pick(cfg, name);
+  // Step 3: start the daemon.
+  await start(profile);
+}
+```
+
+After:
+
+```ts
+async function sync(): Promise<void> {
+  // The profile is resolved against the config's profile table, so the config
+  // has to be read first — a profile name is not self-describing.
+  const cfg = await readConfig();
+  const profile = pick(cfg, name);
+  await start(profile);
+}
+```
+
+## Restating the obvious
+
+Before:
+
+```ts
+// Increments the retry counter.
+retries++;
+```
+
+After:
+
+```ts
+// Per request, not per host: a retry storm against one endpoint must not
+// exhaust the budget the other endpoints share.
+retries++;
+```
+
+## Empty labels
+
+Before:
+
+```ts
+// TODO: handle the timeout case.
+export async function fetchUser(id: string): Promise<User> {
+  return client.get(`/users/${id}`, { timeoutMs: 5000 });
+}
+```
+
+After:
+
+```ts
+// The client rejects rather than returning a partial page once the request
+// budget is gone, so callers must handle a rejected promise. Revisit once the
+// export job needs partial results.
+export async function fetchUser(id: string): Promise<User> {
+  return client.get(`/users/${id}`, { timeoutMs: 5000 });
+}
+```
+
+## Stale comments
+
+Before:
+
+```ts
+// Backs off for 30 seconds between retries, matching the gateway's window.
+const BACKOFF_MS = 250;
+```
+
+After:
+
+```ts
+// The gateway rate-limits per second, so a longer backoff only delays the
+// request the user is already waiting on.
+const BACKOFF_MS = 250;
+```
+
+## Decorative icons and emoji
+
+Before:
+
+```ts
+// ✅ The second read is served from cache.
+// 🚀 Ready to ship.
+export function read(id: string): User | undefined {
+  return cache.get(id);
+}
+```
+
+After:
+
+```ts
+// Read twice and the second read makes no request, so a caller may treat a
+// hit as free.
+export function read(id: string): User | undefined {
+  return cache.get(id);
+}
+```
+
+## Unexpected characters from another script
+
+Before:
+
+```ts
+// The retry 次数 is capped so a flapping upstream cannot hold the request open.
+const MAX_RETRIES = 3;
+```
+
+After:
+
+```ts
+// The retry count is capped so a flapping upstream cannot hold the request open.
+const MAX_RETRIES = 3;
+```
+
+## Verbosity
+
+Before:
+
+```ts
+/**
+ * Loads a user.
+ * This function takes an id and returns the user it names.
+ * It calls the client, which performs the HTTP request.
+ * If the request fails, the error is propagated to the caller.
+ * The caller decides what to do with the error.
+ * The id is validated before the request is made.
+ * An invalid id therefore never reaches the client.
+ * The validation is a format check only.
+ * It does not confirm that the user exists.
+ * A missing user produces the client's own error.
+ * The result is not cached.
+ * A second call repeats the request.
+ */
+export async function fetchUser(id: string): Promise<User> {
+  assertId(id);
+  return client.get(`/users/${id}`);
+}
+```
+
+After:
+
+```ts
+/**
+ * Loads a user. The id is checked for shape, not for existence, so a
+ * well-formed id that names nobody fails with the client's own error.
+ */
+export async function fetchUser(id: string): Promise<User> {
+  assertId(id);
+  return client.get(`/users/${id}`);
+}
+```
+
+## Internal jargon
+
+Before:
+
+```ts
+// Part of the checkout rework — see the planning note, section 4.
+const flags = parseFlags(raw);
+```
+
+After:
+
+```ts
+// Flags arrive as a comma-separated list from the runner's environment: a flag
+// set for a preview deploy is not set on the production runner.
+const flags = parseFlags(raw);
+```
+
+## Unstated assumptions
+
+Before:
+
+```bash
+# Restart it after the migration.
+sudo systemctl restart api
+```
+
+After:
+
+```bash
+# Run on the application host, not the database host. The API reads the schema
+# at boot and keeps it, so it serves the old one until it restarts.
+sudo systemctl restart api
+```
+
+## Which tier each shape lands in
+
+The divider, the ordinal narration, the decorative emoji and a character from
+another script are mechanical, and the gate fails on them — through
+`noir skills lint` for a skill body and through `noir doctor` for a repository.
+The marker with no owner and the long comment block are warnings instead: a
+marker is sometimes the right note and a block is sometimes the right length, so
+those rules ask whether the line earns its place rather than forbidding the
+shape.
+
+Restating, stale text, jargon and unstated assumptions have no pattern behind
+them at all, so only a reader catches them. That is why the skill covers them
+beside the rules the gate can see: the pass is one pass, not two.

package/dist/index.d.ts

@@ -245,6 +245,62 @@ declare function discoverAll(opts?: {
     integrations: IntegrationSkill[];
 };
 
+type HygieneTier = 'fail' | 'warn';
+/** The two kinds of text a rule can be written for: source, or prose. */
+type HygieneKind = 'code' | 'markdown';
+interface HygieneRule {
+    id: string;
+    tier: HygieneTier;
+    /** Anchored: a pattern that matches ordinary writing is the failure this
+     *  rule source exists to prevent, so every pattern below is reviewed against
+     *  plain prose and against string literals. */
+    pattern: RegExp;
+    rationale: string;
+    fix: string;
+    appliesTo: HygieneKind | 'both';
+}
+interface HygieneFinding {
+    /** The id of the rule that matched, exactly as `HYGIENE_RULES` declares it. */
+    id: string;
+    tier: HygieneTier;
+    /** 1-based number of the line the pattern matched. */
+    line: number;
+    /** The matched line, trimmed of surrounding whitespace. */
+    text: string;
+    rationale: string;
+    fix: string;
+}
+/** The line that exempts a file from every rule. A file that must keep what the
+ *  rules flag — the rule source, the token table, a document that states the
+ *  ban — carries the line matching its kind near the top. */
+declare const HYGIENE_EXEMPT_MARKERS: Readonly<Record<HygieneKind, string>>;
+/** A run of this many consecutive comment lines counts as a comment block. A
+ *  blank comment line is a paragraph break and a divider is reported on its
+ *  own, so neither one extends a block. */
+declare const MAX_COMMENT_BLOCK_LINES = 12;
+/** Every rule the gate enforces: the deterministic patterns first, then the
+ *  judgement calls, then the tokens this project must never ship again. */
+declare const HYGIENE_RULES: readonly HygieneRule[];
+/** Checks `text` against every rule that applies to `kind`, and returns the
+ *  findings in reading order: one per rule per line.
+ *
+ *  A file is exempt from every rule when it carries the marker
+ *  `HYGIENE_EXEMPT_MARKERS` declares for its kind on a line above the first
+ *  finding — the rule source itself, the token table, and any guidance or
+ *  fixture file that has to name what the rules forbid. Such a file states its
+ *  own exemption, so no consumer keeps a list of paths to skip. A marker placed
+ *  at or below the first finding exempts nothing.
+ *
+ *  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[];
+
+/** 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
+ *  a reader loads. The validator and the two body-structure lint rules both
+ *  measure this string, so it lives here (single source of truth) rather than
+ *  in compiler.ts. */
+declare function bodyOf(md: string): string;
 /** The max body length the canon recommends (Anthropic: "under 500 lines").
  *  SKILL.md is a navigator, not a repository — split to references/ past this. */
 declare const MAX_BODY_LINES = 500;
@@ -289,13 +345,13 @@ declare function looksLikeWhenDescription(description: string): boolean;
 declare function lintWarnings(skill: BuiltinSkill): string[];
 
 declare function parseFrontmatter(md: string): SkillFrontmatter;
-declare function bodyOf(md: string): string;
 declare function validateSkill(skill: BuiltinSkill): ValidationResult;
 /**
  * `lintSkill` — the soft quality gate. Errors = `validateSkill` errors (a
- * skill that fails validation is broken); warnings = `quality.ts` style rules
- * (thin body, no examples, first-person narration, …). A skill can validate
- * clean yet still carry lint warnings the author should resolve.
+ * skill that fails validation is broken, the hygiene fail tier included);
+ * warnings = the hygiene warn tier plus the `quality.ts` style rules (thin
+ * body, no examples, first-person narration, …). A skill can validate clean
+ * yet still carry lint warnings the author should resolve.
  */
 declare function lintSkill(skill: BuiltinSkill): {
     name: string;
@@ -393,6 +449,15 @@ interface EvalSuite {
     skill_name: string;
     evals: SkillEval[];
 }
+/**
+ * Candidate answers keyed by eval id — what a model (or a stub standing in for
+ * one) actually produced. An id present here is the text the assertions run
+ * against. An id absent is a failure for that eval: the run recorded no answer,
+ * and asserting the golden `expected_output` instead would report a pass the
+ * harness cannot vouch for. Pass no source at all to assert `expected_output`,
+ * which is how suites that predate candidate output keep working.
+ */
+type CandidateOutputs = Record<string, string>;
 /** Parse + validate a raw `evals.json` payload. Throws on malformed shape. */
 declare function parseEvalSuite(raw: unknown): EvalSuite;
 /** Run a list of assertions against `output`. Returns pass + per-assertion failures. */
@@ -408,11 +473,13 @@ declare const EVALS_DIR: string;
  * bug, not a skip).
  */
 declare function loadEvalSuites(dir?: string): EvalSuite[];
-/** Evaluate one suite: for each eval, check its assertions against
- *  `expected_output` (the directive the skill should produce). Returns pass/fail
- *  per eval with the assertion failures. This is the offline core the vitest
- *  runner drives. */
-declare function evaluateSuite(suite: EvalSuite): Array<{
+/** Evaluate one suite: for each eval, check its assertions against the
+ *  candidate output supplied for that eval. With no candidate source at all,
+ *  each eval is checked against `expected_output` (the directive the skill
+ *  should produce); with a source that omits an eval, that eval fails as
+ *  unrecorded. Returns pass/fail per eval with the assertion failures. This is
+ *  the offline core the vitest runner drives. */
+declare function evaluateSuite(suite: EvalSuite, candidates?: CandidateOutputs): Array<{
     id: string;
     pass: boolean;
     failures: string[];
@@ -552,6 +619,16 @@ declare function buildRegistry(): SkillRegistryEntry[];
 /** Convenience: registry filtered to a single category (CLI grouping). */
 declare function registryByCategory(category: string): SkillRegistryEntry[];
 
+/** The forbidden tokens, in the order they are declared. */
 declare const FORBIDDEN_RESIDUE: readonly string[];
+/** One fail-tier rule per forbidden token. A token matches only when it stands
+ *  alone — neither side is a word character or a hyphen — so `noir-workflow`
+ *  does not fire inside a longer identifier such as `noir-workflow-engine-`,
+ *  which names this repository's own workflow engine rather than the removed
+ *  plugin. It still fires on `plugins/noir-workflow/` and `noir-workflow.mode`,
+ *  which name the plugin itself; a token that contains another
+ *  (`noir-workflow.mode`) is reported by both rules, so the narrower token is
+ *  never the only thing matching a line. */
+declare const RESIDUE_RULES: readonly HygieneRule[];
 
-export { BUILTIN_DIR, type BuiltinReference, type BuiltinSkill, type CompileTarget, type CompiledIntegration, type CompiledSkill, EVALS_DIR, type EmitSummary, type EmittedFile, type EvalAssertion, type EvalSuite, FORBIDDEN_RESIDUE, INTEGRATIONS_DIR, IntegrationAuthSchema, type IntegrationDeclaration$1 as IntegrationDeclaration, IntegrationDeclarationSchema, IntegrationMcpSchema, IntegrationSddSchema, type IntegrationSkill, MAX_BODY_LINES, MIN_FULL_BODY_LINES, NOIR_NAMESPACE, type SkillConflict, type SkillEval, type SkillFrontmatter, type SkillRegistryEntry, type ValidationResult, bodyOf, buildRegistry, chainedReferences, compileIntegration, compileSkill, discoverAll, discoverBuiltin, discoverIntegrations, emitSkillsToDir, evaluateSuite, isWhatWhenDescription, lintSkill, lintWarnings, loadEvalSuites, looksLikeWhenDescription, missingSections, parseEvalSuite, parseFrontmatter, parseIntegration, registryByCategory, runAssertions, runtimeEmitsHostMcp, validateIntegration, validateSkill, withinLineBudget };
+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 };