@jjanczur/tyran 0.1.0

package/scripts/yaml-lite.mjs

@@ -0,0 +1,383 @@
+#!/usr/bin/env node
+/**
+ * yaml-lite — a deliberately small YAML subset parser/serializer.
+ *
+ * Tyran's core has zero dependencies (see CONTRIBUTING). Rather than ship a
+ * full YAML implementation, we support the strict subset our own config,
+ * knowledge and policy files are allowed to use — and REJECT everything
+ * else loudly, so a file that would parse differently under a real YAML
+ * engine can never silently mean something else here.
+ *
+ * Supported
+ *   key: value                      scalars: string, number, bool, null
+ *   key:                            nested mappings (2-space indent)
+ *     nested: value
+ *   key:                            block sequences of scalars or mappings
+ *     - item
+ *     - key: v
+ *       key2: v
+ *   key: [a, b]                     inline flow sequences of scalars
+ *   'single' / "double" quoted strings · # comments · --- document start
+ *
+ * Rejected loudly (with a line number): anchors/aliases (& *), tags (! !!),
+ * multi-line scalars (| >), flow mappings ({}), nested flow sequences,
+ * tabs for indentation, duplicate keys, multiple documents.
+ */
+import { formatCodePoint, invisibleProblem } from './invisible.mjs';
+
+// Prototype-free lookup: `constructor`/`__proto__` must be data, not
+// inherited members (review E2S2-R2).
+const BOOL = Object.assign(Object.create(null), {
+  true: true,
+  false: false,
+  yes: true,
+  no: false,
+  on: true,
+  off: false,
+});
+
+export class YamlLiteError extends Error {
+  constructor(message, line) {
+    super(line ? `line ${line}: ${message}` : message);
+    this.line = line ?? null;
+  }
+}
+
+/** Guards shared by keys and values — the subset boundary in one place. */
+function rejectUnsupported(value, lineNo, what) {
+  if (value[0] === '&' || value[0] === '*') {
+    throw new YamlLiteError(`anchors and aliases are not supported (in ${what})`, lineNo);
+  }
+  if (value[0] === '!') throw new YamlLiteError(`tags are not supported (in ${what})`, lineNo);
+  if (value[0] === '|' || value[0] === '>') {
+    throw new YamlLiteError(`multi-line block scalars are not supported (in ${what})`, lineNo);
+  }
+  if (value[0] === '{') throw new YamlLiteError(`flow mappings are not supported (in ${what})`, lineNo);
+}
+
+/** Split a flow sequence body on commas that sit outside quotes. */
+function splitFlow(inner, lineNo) {
+  const parts = [];
+  let current = '';
+  let inSingle = false;
+  let inDouble = false;
+  for (const c of inner) {
+    if (c === "'" && !inDouble) inSingle = !inSingle;
+    else if (c === '"' && !inSingle) inDouble = !inDouble;
+    if (c === ',' && !inSingle && !inDouble) {
+      parts.push(current);
+      current = '';
+    } else current += c;
+  }
+  if (inSingle || inDouble) throw new YamlLiteError('unterminated quoted string in flow sequence', lineNo);
+  parts.push(current);
+  return parts;
+}
+
+function unquote(value, lineNo) {
+  // Single-quoted YAML escapes a quote by doubling it — undo that, so
+  // stringify→parse is symmetric (review E2S2-R3).
+  if (value[0] === "'" && value.at(-1) === "'") return value.slice(1, -1).replace(/''/g, "'");
+  const inner = value.slice(1, -1);
+  // Backslash escapes inside double quotes are real YAML but not part of
+  // this subset — decoding them half-way would mean something different
+  // than a real loader (review E2S2 note 2).
+  if (inner.includes('\\')) {
+    throw new YamlLiteError('backslash escapes inside double quotes are not supported — use single quotes', lineNo);
+  }
+  return inner;
+}
+
+function parseScalar(raw, lineNo, { allowFlow = true } = {}) {
+  const value = raw.trim();
+  if (value === '') return '';
+  rejectUnsupported(value, lineNo, 'value');
+  if (value.startsWith('[')) {
+    if (!allowFlow) throw new YamlLiteError('nested flow sequences are not supported', lineNo);
+    const close = value.lastIndexOf(']');
+    if (close === -1) throw new YamlLiteError('unterminated flow sequence', lineNo);
+    if (value.slice(close + 1).trim() !== '') {
+      throw new YamlLiteError('unexpected content after flow sequence', lineNo);
+    }
+    const inner = value.slice(1, close).trim();
+    if (inner === '') return [];
+    return splitFlow(inner, lineNo).map((part) => parseScalar(part, lineNo, { allowFlow: false }));
+  }
+  if ((value[0] === '"' && value.at(-1) === '"' && value.length > 1) ||
+      (value[0] === "'" && value.at(-1) === "'" && value.length > 1)) {
+    return unquote(value, lineNo);
+  }
+  if (value === 'null' || value === '~') return null;
+  const lower = value.toLowerCase();
+  if (Object.hasOwn(BOOL, lower)) return BOOL[lower];
+  if (/^-?\d+$/.test(value)) return Number(value);
+  if (/^-?\d*\.\d+$/.test(value)) return Number(value);
+  return value;
+}
+
+function stripComment(line, lineNo) {
+  // Comments start at ` #` outside quotes; a leading `#` is a full-line comment.
+  let inSingle = false;
+  let inDouble = false;
+  let cut = -1;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (c === "'" && !inDouble) inSingle = !inSingle;
+    else if (c === '"' && !inSingle) inDouble = !inDouble;
+    else if (c === '#' && !inSingle && !inDouble && (i === 0 || /\s/.test(line[i - 1]))) {
+      cut = i;
+      break; // the comment body is not YAML — stop tracking quotes there
+    }
+  }
+  // An unbalanced quote means our comment detection disagreed with a real
+  // YAML loader (`a: don't ask # why`) — refuse rather than guess
+  // (review E2S2 note 1).
+  if (inSingle || inDouble) {
+    throw new YamlLiteError('unbalanced quote — quote the whole value if it contains an apostrophe', lineNo);
+  }
+  return cut === -1 ? line : line.slice(0, cut);
+}
+
+/** Parse a YAML-subset document into a plain JS object. */
+export function parse(text) {
+  const rawLines = text.split('\n');
+  const lines = [];
+  let sawDocStart = false;
+  rawLines.forEach((raw, i) => {
+    const lineNo = i + 1;
+    const beforeContent = raw.slice(0, raw.search(/\S|$/));
+    if (beforeContent.includes('\t')) {
+      throw new YamlLiteError('tabs are not allowed for indentation', lineNo);
+    }
+    const line = stripComment(raw, lineNo).replace(/\s+$/, '');
+    if (line.trim() === '') return;
+    if (line.trim() === '---' || line.trim() === '...') {
+      // Only a leading document marker is allowed: a second one would mean
+      // a multi-document stream, where a real YAML loader takes only the
+      // first document (review E2S2-R4).
+      if (sawDocStart || lines.length > 0) {
+        throw new YamlLiteError('multiple documents are not supported', lineNo);
+      }
+      sawDocStart = true;
+      return;
+    }
+    const indent = line.length - line.trimStart().length;
+    if (indent % 2 !== 0) throw new YamlLiteError('indentation must be a multiple of 2 spaces', lineNo);
+    lines.push({ indent, text: line.trim(), lineNo });
+  });
+
+  let pos = 0;
+
+  function parseBlock(indent) {
+    // Sequence?
+    if (pos < lines.length && lines[pos].indent === indent && lines[pos].text.startsWith('- ')) {
+      const items = [];
+      while (pos < lines.length && lines[pos].indent === indent && lines[pos].text.startsWith('- ')) {
+        const { text, lineNo } = lines[pos];
+        const rest = text.slice(2).trim();
+        const colon = keyColonIndex(rest);
+        if (colon === -1) {
+          items.push(parseScalar(rest, lineNo));
+          pos++;
+        } else {
+          // Mapping item: first pair sits on the dash line, siblings follow indented.
+          const map = Object.create(null);
+          const key = unquoteKey(rest.slice(0, colon), lineNo);
+          const inlineValue = rest.slice(colon + 1).trim();
+          pos++;
+          if (inlineValue === '') {
+            const next = lines[pos];
+            map[key] = next && next.indent > indent + 2 ? parseBlock(next.indent) : null;
+          } else map[key] = parseScalar(inlineValue, lineNo);
+          const childIndent = indent + 2;
+          while (pos < lines.length && lines[pos].indent === childIndent && !lines[pos].text.startsWith('- ')) {
+            const child = lines[pos];
+            const c = keyColonIndex(child.text);
+            if (c === -1) throw new YamlLiteError('expected "key: value" inside sequence item', child.lineNo);
+            const k = unquoteKey(child.text.slice(0, c), child.lineNo);
+            if (Object.hasOwn(map, k)) throw new YamlLiteError(`duplicate key "${k}"`, child.lineNo);
+            const v = child.text.slice(c + 1).trim();
+            pos++;
+            if (v === '') {
+              const next = lines[pos];
+              map[k] = next && next.indent > childIndent ? parseBlock(next.indent) : null;
+            } else map[k] = parseScalar(v, child.lineNo);
+          }
+          items.push({ ...map });
+        }
+      }
+      return items;
+    }
+
+    // Mapping
+    const map = Object.create(null);
+    while (pos < lines.length && lines[pos].indent === indent) {
+      const { text, lineNo } = lines[pos];
+      if (text.startsWith('- ')) break;
+      const colon = keyColonIndex(text);
+      if (colon === -1) throw new YamlLiteError(`expected "key: value", got "${text}"`, lineNo);
+      const key = unquoteKey(text.slice(0, colon), lineNo);
+      if (Object.hasOwn(map, key)) throw new YamlLiteError(`duplicate key "${key}"`, lineNo);
+      const value = text.slice(colon + 1).trim();
+      pos++;
+      if (value === '') {
+        const next = lines[pos];
+        if (!next || next.indent <= indent) map[key] = null;
+        else map[key] = parseBlock(next.indent);
+      } else {
+        map[key] = parseScalar(value, lineNo);
+      }
+    }
+    return { ...map }; // hand back an ordinary object, prototype-free during construction
+  }
+
+  const result = lines.length === 0 ? {} : parseBlock(lines[0].indent);
+  if (pos < lines.length) {
+    throw new YamlLiteError(`unexpected indentation`, lines[pos].lineNo);
+  }
+  return result;
+}
+
+function keyColonIndex(text) {
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === "'" && !inDouble) inSingle = !inSingle;
+    else if (c === '"' && !inSingle) inDouble = !inDouble;
+    else if (c === ':' && !inSingle && !inDouble && (i + 1 === text.length || /\s/.test(text[i + 1]))) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+function unquoteKey(raw, lineNo) {
+  const key = raw.trim();
+  if (key === '') throw new YamlLiteError('empty key', lineNo);
+  if ((key[0] === '"' && key.at(-1) === '"' && key.length > 1) ||
+      (key[0] === "'" && key.at(-1) === "'" && key.length > 1)) {
+    return unquote(key, lineNo);
+  }
+  // Keys go through the same subset guards as values (review E2S2-R4):
+  // `&anchor key:` and `!!tag key:` must not be swallowed into the key name.
+  rejectUnsupported(key, lineNo, 'key');
+  return key;
+}
+
+/** Serialize a plain object back into the same subset (stable key order). */
+export function stringify(value, indent = 0) {
+  const pad = ' '.repeat(indent);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return `${pad}[]\n`;
+    return value
+      .map((item) => {
+        if (item !== null && typeof item === 'object' && !Array.isArray(item)) {
+          const body = stringify(item, indent + 2);
+          return `${pad}- ${body.slice(indent + 2)}`;
+        }
+        return `${pad}- ${formatScalar(item)}\n`;
+      })
+      .join('');
+  }
+  if (value !== null && typeof value === 'object') {
+    return Object.entries(value)
+      .map(([k, v]) => {
+        if (v !== null && typeof v === 'object' && (Array.isArray(v) ? v.length > 0 : Object.keys(v).length > 0)) {
+          return `${pad}${formatKey(k)}:\n${stringify(v, indent + 2)}`;
+        }
+        if (v !== null && typeof v === 'object') return `${pad}${formatKey(k)}: ${Array.isArray(v) ? '[]' : 'null'}\n`;
+        return `${pad}${formatKey(k)}: ${formatScalar(v)}\n`;
+      })
+      .join('');
+  }
+  return `${pad}${formatScalar(value)}\n`;
+}
+
+/**
+ * Refuse to SERIALIZE an invisible codepoint, the same way this file already
+ * refuses a newline and for the same reason.
+ *
+ * This subset has no lossless way to carry one. Double-quoted \uXXXX escapes
+ * are real YAML but explicitly out of the subset — `unquote` rejects a
+ * backslash rather than decode it half-way — so the only representations
+ * available are RAW (a Trojan Source payload in a config file) or VISIBLY
+ * ESCAPED (which parses back as different data and breaks the round trip this
+ * file guarantees). Neither is acceptable, so the answer is the one
+ * `formatScalar` already gives for newlines: fail loudly at serialization
+ * time rather than write a file that reads back as something else.
+ *
+ * Refusing is the strongest fix available TO A SERIALIZER, which is a narrower
+ * claim than the one that stood here first. The worst case is a poisoned value
+ * PERSISTED to a config file: it would re-enter the conductor's context at
+ * every session start, through a path where none of the runtime layers is
+ * looking. This guard stops THIS WRITER from authoring such a file.
+ *
+ * It does NOT make the file impossible, and the earlier wording here said it
+ * did — corrected after a review disproved it by measurement. `parse` is
+ * untouched and reads a hand-written hostile file without complaint (measured:
+ * 7 invisible codepoints straight into a value), and the file can arrive by an
+ * editor, an agent's write tool, or a template copied from elsewhere. The
+ * honest guarantee is "tyran will not author one", not "one cannot exist".
+ * Closing the READ side is a separate decision with a live consumer question
+ * behind it — `schema.mjs` is the only importer today and its parsed values do
+ * not leave the validating function — so it is deliberately not done here.
+ *
+ * Measured before choosing: `stringify` has ZERO production consumers today —
+ * only its own unit test imports it, and `schema.mjs` imports `parse` alone.
+ * So the persisted-poison case is not reachable in this repository right now,
+ * and this guard is prophylactic. It is still worth having, because "no caller
+ * yet" is a fact about today and this module is published API.
+ */
+function rejectInvisible(s, what) {
+  for (const ch of s) {
+    const problem = invisibleProblem(ch.codePointAt(0));
+    if (problem !== null) {
+      throw new YamlLiteError(
+        `cannot serialize a ${what} containing ${formatCodePoint(ch.codePointAt(0))} — ${problem}. ` +
+          'This subset has no escape for it, so writing it would either hide it in the file ' +
+          'or change the value on the way back.',
+      );
+    }
+  }
+}
+
+function formatKey(key) {
+  const s = String(key);
+  if (s.includes('\n')) {
+    // Mirrors the guard in formatScalar: a newline has no representation in
+    // this subset, so refuse at serialization time instead of emitting a file
+    // our own parser rejects with a confusing "unbalanced quote" (review
+    // E2S2-R11, note 1).
+    throw new YamlLiteError('cannot serialize a key containing a newline (no block scalars in this subset)');
+  }
+  rejectInvisible(s, 'key');
+  if (s === '' || /[\s:#'"&*!|>[\]{},]/.test(s)) return `'${s.replace(/'/g, "''")}'`;
+  return s;
+}
+
+function formatScalar(value) {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'boolean' || typeof value === 'number') return String(value);
+  const s = String(value);
+  if (s.includes('\n')) {
+    // The subset has no block scalars, so a newline cannot be represented.
+    // Failing loudly beats writing a file that reads back as different data
+    // (review E2S2-R1).
+    throw new YamlLiteError('cannot serialize a string containing a newline (no block scalars in this subset)');
+  }
+  rejectInvisible(s, 'string');
+  const needsQuotes =
+    s === '' ||
+    /^\s|\s$/.test(s) ||
+    /^[-?:,[\]{}#&*!|>'"%@`]/.test(s) ||
+    /:\s/.test(s) ||
+    /\s#/.test(s) || // ` #` would be read back as a comment (review E2S2-R1)
+    s.includes("'") ||
+    s.includes('"') || // an unquoted apostrophe now fails to parse (review E2S2-R11)
+    Object.hasOwn(BOOL, s.toLowerCase()) ||
+    s === 'null' ||
+    s === '~' ||
+    /^-?\d+(\.\d+)?$/.test(s);
+  return needsQuotes ? `'${s.replace(/'/g, "''")}'` : s;
+}

package/skills/browser-check/SKILL.md

@@ -0,0 +1,118 @@
+---
+description: Drive a real browser and come back with a MEASUREMENT rather than an impression - deterministic waits instead of sleeps, console errors and >=400 responses as counts, computed styles dumped to JSON when appearance is disputed. Use when work touches UI, when a review must verify one, or when fidelity-gate asks for its measurement.
+---
+
+# Browser check — proving a UI works, in numbers
+
+> Three places in this plugin order a browser pass — the conductor's quality
+> gates, the reviewer, the implementer — and `fidelity-gate` asks for computed
+> styles on top. None of them said how. This is the how, and it exists so that
+> "I checked it in the browser" stops being a sentence and starts being a
+> counter someone else can re-run.
+
+**A browser pass is a measurement.** It returns numbers: pages visited, links
+resolved, console errors, failed responses. `Looks fine`, `renders correctly`
+and `no obvious issues` are REJECTED by the evidence contract exactly like a
+test report with no output, and for the same reason — nothing in them can be
+wrong.
+
+## Before you promise a run
+
+1. **The browser exists.** `npx playwright --version`, and install only
+   chromium (`npx playwright install chromium`) — a full browser install is
+   several GB for two extra engines nobody asked for.
+2. **The server is up and SERVING WHAT YOU THINK.** Fetch one known URL and
+   check the status before automating anything. A dev server that is still
+   compiling, or is serving a stale build on a port you forgot to kill,
+   produces a page of failures that have nothing to do with your change.
+3. **Build first when the target is a static site.** Testing the dev server
+   and shipping the build tests two different programs.
+
+## Waits are deterministic — never a sleep
+
+Wait for a *condition*: a response, a selector, a network-idle state, a font
+ready promise. `waitForTimeout` is a guess that is simultaneously too long on
+your machine and too short in CI, and the failures it produces are
+indistinguishable from real ones. The only defensible fixed wait is settling an
+animation you cannot observe, and it says so in a comment.
+
+**Warm the routes before a batch run.** The first request to a route compiles
+it; a cold compile times out and reads as a defect in the page. Hitting every
+route once before measuring costs one pass and removes a whole class of false
+finding.
+
+## What you collect, and what you return
+
+Subscribe before you navigate — listeners attached after the first `goto` miss
+everything that page already did:
+
+- `console` events of type `error`
+- `pageerror` — uncaught exceptions, which are NOT console errors and are
+  routinely missed by checking only the first
+- `response` with status `>= 400`, including the ones fired by the page's own
+  fetches, which no amount of clicking will reveal
+- every in-page link, resolved once and cached by URL
+
+Return them as **counts plus the first few offenders**, then a single verdict
+line. A pass with `0` console errors is a fact; "the console was clean" is a
+recollection.
+
+## Selectors that do not go blind
+
+Anchor on what the user sees — a role, a label, the text — not on a container
+class or an nth-child. This is not a style preference. A selector scoped to the
+markup it was written against keeps passing while silently checking LESS of the
+page as the page grows, and it reports the narrowed number as success. That has
+already happened in this repo: a link check named two regions of one framework's
+chrome, and went from checking every link to checking half of them on the day a
+page was added outside that chrome — with no failure anywhere.
+
+So: assert the COUNT you expected as well as the condition. `24 links checked,
+0 broken` catches the regression that `0 broken` cannot.
+
+## When the disagreement is about appearance
+
+Settle it with `getComputedStyle`, dumped to JSON, compared against the
+inventory. Never by looking, and never by asking a model to look:
+
+```js
+await page.$$eval(SELECTORS, (els) => els.map((el) => {
+  const s = getComputedStyle(el);
+  return { text: el.textContent.trim(), fontSize: s.fontSize, fontWeight: s.fontWeight, color: s.color };
+}));
+```
+
+Two rules that keep this a measurement:
+
+- **Assert the element's text alongside its geometry.** A structural selector
+  with no text assertion measures the wrong element when the markup is
+  renumbered, and reports a confident wrong number instead of a loud miss.
+- **A zero-size box is a failure, not a pass.** An element that renders with no
+  width, or a glyph that inherits `fill: none`, is present in the DOM and
+  invisible on the screen. Check the bounding box whenever you check anything
+  visual, or the check passes on a page nobody can read.
+
+For a frozen reference, this step belongs to `fidelity-gate`, which owns the
+inventory, the relics list and the verdict format. Do not invent a second one.
+
+## Artefacts and cleanup
+
+Screenshots, JSON dumps and logs go under `.tyran/`, never `/tmp` — they are
+evidence for a report, and evidence a colleague cannot open is not evidence.
+Name them for the run, not `screenshot.png`.
+
+End the way you started: close the browser, and stop the server you started
+with SIGTERM so it can release its port. `kill -9` leaves the port held and the
+next run fails for a reason that has nothing to do with the code.
+
+## The report
+
+```
+PAGES 13 · LINKS 24/24 · CONSOLE ERRORS 0 · PAGE ERRORS 0 · HTTP>=400 0
+BROWSER PASS: OK
+```
+
+Then the failures, if any, with the URL that produced each. State plainly what
+you did NOT drive — the viewport you skipped, the flow behind a login, the
+browser you do not have. An unchecked area named in the report is a decision
+for the conductor; an unchecked area left out of it is a claim.

package/skills/code-review/SKILL.md

@@ -0,0 +1,83 @@
+---
+description: The depth half of a review - the dimensions a diff is read against (correctness, boundaries, concurrency, failure paths, secrets, test quality, lifecycle) and the rule that a finding is refuted before it is reported. The verdict itself stays with the reviewer agent. Use when reviewing a diff or a pull request.
+---
+
+# Code review — reading depth
+
+> This is HOW a diff is read. WHAT the verdict looks like belongs to
+> `tyran:reviewer` — binary APPROVE or CHANGES-REQUESTED, numbered executable
+> counterexamples, a re-review that first checks the previous round's findings
+> are pinned as tests, and a section naming what was not checked. Do not
+> restate any of that here; two definitions of "reviewed" drift apart, and the
+> drift only shows up when they disagree in front of someone.
+
+## Read the diff twice, for different things
+
+**First pass — does it do what the story says?** Against the acceptance
+criteria, not against your idea of the feature. A correct implementation of the
+wrong thing is the most expensive defect on this list, and it is the one a
+dimension sweep never catches.
+
+**Second pass — the sweep below.** Every dimension gets looked at explicitly.
+Skipping one is a decision that belongs in the "did not check" section, not a
+gap nobody notices.
+
+## The dimensions
+
+- **Correctness at the edges.** Empty, one, many. Zero, negative, overflow. The
+  first and last iteration. Null versus absent versus empty-string — three
+  different states that most code conflates and most tests exercise as one.
+- **Boundaries and shared zones.** Does the change reach outside its story's
+  scope? An API shape, a schema, a shared file, a generated artefact, a
+  published type. Those are the conductor's to authorise, and a review that
+  waves one through has spent authority it does not have.
+- **Concurrency and ordering.** Two of these running at once: what is read
+  after being written elsewhere, what assumes it is alone, what holds a lock
+  and what forgot to release one on the failure path.
+- **Failure paths.** Follow every error to where it is handled. An error that
+  is caught and logged is not handled; an error swallowed to keep a pipeline
+  green is a silent failure with a good story. Check the *partial* failure —
+  the write that succeeded before the one that did not.
+- **Secrets and untrusted input.** Anything reaching a shell, a query, a path,
+  a template or a rendered page. Values from the environment or a fixture that
+  look like real credentials. This dimension has a floor: it is reviewed
+  properly or the review is not finished.
+- **Test quality, not test count.** Does each new test fail when the behaviour
+  is broken? Delete a line of the implementation in your head and ask which
+  test goes red — if the answer is none, the test asserts nothing. Watch for a
+  test that pins the CURRENT output rather than the CORRECT one, which converts
+  a bug into a requirement.
+- **Resource lifecycle.** What is opened, started, spawned or leased, and where
+  it is closed — including on the path where an exception is thrown.
+- **The gate itself.** If the change touches a check, ask what that check can
+  no longer see. A loosened tolerance, a narrowed selector, a broadened
+  try/catch and a skipped test all keep the run green while removing its
+  meaning.
+
+## Refute before you report
+
+**Try to kill your own finding first.** Re-read the surrounding code, look for
+the guard you may have missed, and where it is cheap, run the case. Report what
+survives that attempt.
+
+This is not politeness, it is arithmetic: a review that reports six findings of
+which two are wrong costs more than one that reports four, because every wrong
+finding is a round trip plus an argument, and it trains the conductor to
+discount the other four.
+
+- **A finding you cannot state as an input and an expected result is not
+  ready.** That form is what makes it pinnable as a test, and what the
+  reviewer's verdict requires.
+- **Rank by severity, not by reading order.** Wrong behaviour, then a boundary
+  crossed, then a missing test, then everything else. A list in the order you
+  happened to notice things makes the reader do the triage you were asked to do.
+- **Say plainly when you found nothing.** Manufacturing a finding to look
+  thorough is the cheapest way to become ignorable.
+
+## Before you fix N things, ask whether they are one thing
+
+Several findings that all point at the same wrong baseline, the same missing
+guard or the same misread contract are ONE finding. Fixing them individually
+leaves the cause in place, and the next change re-derives them. Say so
+explicitly when it happens — the conductor is deciding how to schedule the
+work, and "six issues" and "one cause with six symptoms" are different plans.

package/skills/deslop/SKILL.md

@@ -0,0 +1,97 @@
+---
+description: The optimization pass, defined - delete before you add, one smell class per pass, behaviour pinned by a test that ran BEFORE the edit and again after. Lints a SKILL.md and prose by the same instinct. Use for the per-story optimization pass, before promoting a skill, or when code has grown noisy without growing capable.
+---
+
+# Deslop — the pass that removes rather than adds
+
+> Every story here owes an optimization pass, and until this file existed the
+> pass was whatever the agent felt like that afternoon. This is what one is.
+
+**The default action is deletion.** A pass that ends with more lines than it
+started with was a refactor, and a refactor is a different piece of work with a
+different risk profile. If you cannot delete anything, say so and stop — that is
+a complete and respectable outcome.
+
+## The order, and why it is an order
+
+1. **Pin the behaviour BEFORE you touch anything.** Run the relevant tests and
+   keep the output. A green run *after* an edit proves nothing on its own: you
+   do not know it was green before. If no test covers the area, write the
+   narrowest one that does, and it must go red when you break the behaviour on
+   purpose — otherwise it is not a net, it is decoration.
+2. **One smell class per pass**, verified between passes. Dead code, then
+   duplication, then naming and error handling, then tests. Bundling them
+   produces a diff nobody can review and a bisect that cannot isolate the
+   change that broke something.
+3. **Re-read the diff as the reviewer will.** Anything in it that is not the
+   smell you set out to remove comes back out.
+
+## What counts as slop
+
+- **Dead code** — unreachable branches, unused exports, stale flags, debugging
+  left in place, backwards-compatibility shims for something nothing calls.
+  Verify it is unused before deleting; "I could not find a caller" and "there is
+  no caller" are different statements and only one of them is a fact.
+- **Duplication that has diverged.** Two copies that agree are a cost; two
+  copies that quietly disagree are a defect.
+- **Pass-through wrappers and single-use helpers.** Indirection that costs a
+  jump and buys nothing. **Three similar lines beat a premature abstraction** —
+  the abstraction commits you to a shape you have seen once.
+- **Defensive handling for states that cannot occur** on a trusted internal
+  path. It reads as care and works as camouflage: the `catch` that cannot fire
+  today is the one that swallows the real error next year.
+- **Casts that exist to silence a type error** rather than to state a truth the
+  compiler cannot see.
+- **Work nobody asked for** — an improvement, a rename, a docstring, a
+  reformat on code the story never touched. It inflates the diff, hides the real
+  change, and puts an unreviewed decision in someone else's file.
+- **Comments restating the line below them.** Keep the comment that explains
+  WHY, delete the one that narrates WHAT.
+
+## What is not slop, and stays
+
+Behaviour. A guard on genuinely untrusted input. A comment carrying a reason.
+An abstraction with three real callers. A test that looks redundant but pins a
+past bug — check the history before deleting a test; the second time a bug is
+fixed, the deleted test is the reason.
+
+**Keep behaviour unchanged unless you are fixing a defect you can name.** If the
+pass uncovers a real bug, that is a finding for the report and usually a
+separate change, not something to quietly correct inside a cleanup.
+
+## Skill-file mode
+
+The same instinct, applied to a `SKILL.md`. Run it before promoting a skill:
+
+- **Stale lines** — guidance written for a version of the skill that no longer
+  exists. Cut it.
+- **Bloat** — detail that belongs in the caller, in a reference, or nowhere.
+- **Dead sentences** — a line that changes nothing if deleted.
+- **Duplication** — the same rule stated in two files, which will drift.
+- **Premature stop** — the method ends before the work does: it asks the
+  question but never records the answer, cleans but never verifies.
+- **Weak anchor** — no single idea the skill turns on.
+- **A missing assumption** — the skill does not say what has to be true for it
+  to apply. See `skill-writing`.
+
+## Prose mode
+
+For a README, a report, an error message or a commit body:
+
+- **Lead with the outcome.** The first sentence is the line a reader would ask
+  for if they said "just tell me".
+- **Name the number, the file, the command.** "Faster" is weaker than "40s to
+  9s". "Fixed the config bug" is weaker than the path.
+- **Cut the filler** — *just*, *simply*, *basically*, *it is worth noting*. If
+  a sentence changes nothing when removed, remove it.
+- **No dead-end error messages.** Every failure names what happened and what to
+  do next.
+- Do not achieve brevity by compressing sentences into fragments. Achieve it by
+  dropping what the reader does not need.
+
+## The report
+
+Files touched, what class of slop came out of each, the test output from before
+and after, and one line on what you deliberately left. The last part matters: a
+cleanup that silently declined to touch the worst file in the area looks
+identical to one that found nothing there.