nodeengine 0.1.0__tar.gz

nodeengine-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "node-engine",
+  "description": "Hash-and-compare guards so derived things report stale instead of silently lying",
+  "owner": {
+    "name": "Alexyodude",
+    "email": "jihoonhotmail.com@gmail.com"
+  },
+  "plugins": [
+    {
+      "name": "node-engine",
+      "description": "Make staleness fail a check instead of relying on someone remembering. Sets up hash-and-compare guards for summaries, translations, generated files and any fact restated in prose. Carries the discipline too: fix the class not the instance, and a new check is guilty until it has failed on demand.",
+      "version": "0.1.0",
+      "author": {
+        "name": "Alexyodude",
+        "email": "jihoonhotmail.com@gmail.com"
+      },
+      "source": "./",
+      "category": "quality",
+      "homepage": "https://github.com/Alexyodude/NodeEngine",
+      "tags": [
+        "drift",
+        "consistency",
+        "documentation",
+        "checks",
+        "content-addressing"
+      ]
+    }
+  ],
+  "version": "0.1.0"
+}

nodeengine-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "node-engine",
+  "version": "0.1.0",
+  "description": "Make staleness fail a check instead of relying on someone remembering. Hash-and-compare guards for derived facts, generated artefacts and translations.",
+  "author": {
+    "name": "Alexyodude",
+    "email": "jihoonhotmail.com@gmail.com"
+  },
+  "repository": "https://github.com/Alexyodude/NodeEngine",
+  "homepage": "https://github.com/Alexyodude/NodeEngine",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "documentation",
+    "drift",
+    "consistency",
+    "checks",
+    "provenance"
+  ],
+  "skills": "./skills/"
+}

nodeengine-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.omc/
+__pycache__/
+*.pyc
+.build/
+dist/
+.playwright-mcp/

nodeengine-0.1.0/CLAUDE.md

@@ -0,0 +1,151 @@
+# NodeEngine
+
+A Claude Code **plugin** that makes staleness fail a check instead of relying on
+someone remembering. It ships one skill and a copyable scaffold.
+
+**This repo is mostly prose, and the prose is the product.** The scaffold is
+~150 lines of Python plus a self-contained HTML viewer; the value is in
+`SKILL.md` and `reference/`. Edits that make the guidance vaguer make the
+plugin worse, even when they make it shorter.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `python skills/node-engine/scaffold/stale.py` | No CLI — it is a module. Import it to smoke-test. |
+| `python -c "import sys; sys.path.insert(0,'skills/node-engine/scaffold'); import stale"` | Confirm the scaffold imports |
+| `python skills/node-engine/scaffold/checkall.py --prove` | Print how to break each check in the runner |
+| `python tools/check_claude_md.py` | Is this file still true? Paths exist, versions agree, sections vs the template |
+| `python install.py --dry-run` | Show what installing into the current repo would write |
+| `python install.py --into <dir>` | Copy the scaffold elsewhere; finds the git root, refuses to overwrite |
+| `uvx --from <this repo> nodeengine --dry-run` | The same installer via its packaged entry point — exercises `pyproject.toml` |
+
+There is no build and no test suite. The scaffold is copied into other projects,
+not executed here — `install.py` is the copier, and `commands/install.md` is the
+`/node-engine:install` command that runs it and then walks the wiring-up.
+
+## Architecture
+
+```
+NodeEngine/
+  install.py              copies the scaffold into another repo
+  pyproject.toml          packages install.py ONLY, so `uvx nodeengine` works
+  commands/
+    install.md            /node-engine:install — copy, then wire it up
+  tools/
+    check_claude_md.py    is CLAUDE.md still true? (see docs/SYNCING.md)
+  docs/
+    SYNCING.md            why the template is checked, not synced
+  .claude-plugin/
+    plugin.json           the manifest; `skills` points at ./skills/
+    marketplace.json      makes the repo installable as its own marketplace
+  skills/node-engine/
+    SKILL.md              the method, the rule, when NOT to use it
+    reference/
+      patterns.md         the three shapes, with implementations
+      traps.md            ten checks that could not fail — all real
+      taxonomy.md         thirteen defect classes
+    scaffold/
+      stale.py            store + comparators, meant to be read and edited
+      checkall.py         the runner
+      viewer.html         browser search over the stores; keyOf must match key_of
+```
+
+**The version appears in four places** — `plugin.json`, twice in
+`marketplace.json` (the plugin entry and the top-level field), and
+`pyproject.toml`. They must agree. This is precisely the class of defect the
+plugin exists to catch; `tools/check_claude_md.py` fails if they disagree,
+including the TOML one — its JSON glob never sees `pyproject.toml`, so that
+copy needed its own read, proven by breaking it (`0.9.9` → exit 1).
+
+## Key files
+
+- `skills/node-engine/SKILL.md` — what an agent loads. Frontmatter `description`
+  is what makes it fire, so it must name the symptoms someone would actually
+  type ("stop this drifting", "why did that go stale"), not just the concept.
+- `skills/node-engine/reference/traps.md` — the highest-value file. Ten worked
+  examples of checks that shipped unable to fail.
+- `skills/node-engine/scaffold/stale.py` — deliberately not a library.
+
+## Editing conventions
+
+**Keep the examples concrete and real.** Every example in `reference/` is from a
+project that actually shipped the defect. `"A check compared PDFs to themselves
+and reported 9 rendered and current"` transfers; `"ensure comparison operands
+differ"` does not. Do not generalise an example to make it tidier.
+
+**The scaffold is copied, not imported.** Its docstrings say so. Do not add
+dependencies or packaging *to the scaffold* — a dependency you cannot read is
+one you will trust when it is wrong, which is the failure the plugin exists to
+prevent. The root `pyproject.toml` is not an exception: it packages the
+*installer* as the `nodeengine` entry point, and what that entry point does is
+still copy readable files into `tools/`. If a change would make the scaffold
+itself installable or importable, it is wrong.
+
+**Do not strip the dense docstrings.** They record the measured defect each
+guard was built to catch. That is institutional knowledge, not slop.
+
+## Gotchas
+
+- **`.omc/` reappears constantly.** OMC writes state into whatever directory a
+  command runs from, including this one and `skills/node-engine/scaffold/`. It is
+  gitignored; check `git status` before committing anyway.
+- **`__pycache__/` appears in `scaffold/`** the moment anything imports `stale.py`
+  from there. Also gitignored.
+- **Git reports LF→CRLF warnings on every commit** on Windows. Harmless.
+- **Installing from a local path is not the same as from GitHub.** Test with
+  `/plugin marketplace add <path>` before pushing, then again from the remote —
+  the manifest is only exercised properly on a real install.
+
+## Publishing
+
+```
+git push -u origin main
+/plugin marketplace add Alexyodude/NodeEngine
+/plugin install node-engine@node-engine
+```
+
+Bump the version in **all four places** together — `plugin.json`, twice in
+`marketplace.json`, `pyproject.toml` — or the install will resolve to something
+that does not exist. `check_claude_md.py` catches a missed one.
+
+## Known gaps
+
+- ~~The one-line installer 404s until the repo is public.~~ **Closed 2026-08-31**
+  — the repo is public and the happy path is verified: both
+  `curl -fsSL .../install.py | python` and `uv run <github raw URL>` installed
+  `stale.py` + `checkall.py` into a fresh repo's `tools/`, exit 0. Before the
+  push, a 404 body was piped straight into the interpreter (`<!DOCTYPE html>`
+  SyntaxError) — `curl` needs `-f`, and `uv run` does not check HTTP status.
+
+
+Stated plainly because this plugin is about not letting claims drift:
+
+- ~~The version is restated in three places and nothing checks it.~~ **Closed**
+  — `tools/check_claude_md.py` fails if the manifests disagree. Proven by
+  setting `plugin.json` to `0.2.0` and watching it fire.
+- **`nodeengine` is not on PyPI**, so the bare `uvx nodeengine` / `pipx run
+  nodeengine` does not resolve. What works without a publish is
+  `uvx --from git+https://github.com/Alexyodude/NodeEngine nodeengine`. The
+  name was free on PyPI as of 2026-08-31 — publishing would claim it and make
+  the two-word form real.
+- **The scaffold has no tests.** Its correctness is asserted by the reference
+  docs, not demonstrated. `checkall.py --prove` prints how to break the checks
+  it describes, but nothing runs them here.
+- The skill has never been invoked cold in an unfamiliar repo. Until it has, the
+  claim that it "sets up guards in any repo" is untested.
+
+## Upstream template
+
+`CLAUDE.md` here follows the template in the `claude-md-management` plugin
+(`skills/claude-md-improver/references/templates.md`). To re-check this file
+against the current upstream guidance:
+
+```
+/plugin marketplace update claude-plugins-official
+/revise-claude-md
+```
+
+The template is *guidance*, not a file to copy — there is no automatic sync, and
+`/revise-claude-md` reads the session for learnings rather than diffing against
+the template. See `docs/SYNCING.md` for what can and cannot be automated.

nodeengine-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexyodude
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nodeengine-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: nodeengine
+Version: 0.1.0
+Summary: Install the NodeEngine staleness-guard scaffold into the current repo
+Project-URL: Homepage, https://github.com/Alexyodude/NodeEngine
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# NodeEngine
+
+A Claude Code plugin. Makes staleness **fail a check** instead of relying on
+someone remembering.
+
+*The name is literal: what it builds is a graph of **nodes** — clauses, blocks,
+generated files — each holding the hash of the source it was derived from. The
+engine walks that graph and reports every edge whose source has moved.*
+
+A fact stated twice is a fact that will disagree with itself — not might, will,
+usually within hours, because the two copies are edited by different people at
+different times for different reasons.
+
+The usual response is to be careful. That fails, because carefulness does not
+survive a deadline. What works is to make the second copy *derived*, and then
+make derivation *checkable*.
+
+## The idea, in one line
+
+> **Store the hash of the source beside the derived thing. Compare on every run.**
+
+```json
+"6.2B": { "hash": "3e40ff04…", "summary": "The reservations preserve rights as partners only…" }
+            ^^^^^^^^^^^^^^^^^ the source text when a human last confirmed
+                              this summary was true of it
+```
+
+Change the source and its hash changes; the summary no longer matches its
+anchor; the check says `summary-stale: 6.2B`. Nobody had to remember. The
+staleness is not caught by cleverness — it is **structurally unable to hide**.
+
+## Install
+
+One line, in any repo:
+
+```
+curl -sL https://raw.githubusercontent.com/Alexyodude/NodeEngine/main/install.py | python -
+```
+
+That copies `stale.py`, `checkall.py` and `viewer.html` into `./tools/` and
+prints what to do next. No clone, no plugin, no dependencies. Add
+`--into scripts` or `--dry-run` after `python -` if you want them.
+
+If you have [uv](https://docs.astral.sh/uv/), the same installer runs as a
+packaged tool — same files land, same refusal to overwrite:
+
+```
+uvx --from git+https://github.com/Alexyodude/NodeEngine nodeengine
+```
+
+*It runs code fetched over the network, which is worth being deliberate about.
+To read it first:*
+
+```
+curl -sL https://raw.githubusercontent.com/Alexyodude/NodeEngine/main/install.py -o install.py
+less install.py && python install.py
+```
+
+**As a Claude Code plugin**, if you also want the skill and the guided setup:
+
+```
+/plugin marketplace add Alexyodude/NodeEngine
+/plugin install node-engine@node-engine
+/node-engine:install
+```
+
+The plugin adds the method itself — an agent that knows the three shapes, the
+defect taxonomy, and the rule that a new check is guilty until it has failed on
+demand. The one-liner just gives you the files.
+
+## What it covers
+
+Three shapes, because different relationships need different guarantees:
+
+| Shape | For | Guarantee |
+|---|---|---|
+| **Anchored** | a human judgement about a source — summaries, descriptions, a sentence citing a spec | re-anchoring is an explicit act; you cannot clear a stale flag by accident |
+| **Content-addressed** | anything that must track an original exactly — translations, mirrors | the hash *is* the key, so a changed source has no entry rather than the wrong one |
+| **Ordered** | files a human generates by running a command | catches the case the others cannot: nobody ran it |
+
+Plus the cheapest win in most repos: **a number restated in prose should be
+computed at check time and compared** — version, file count, step count, size.
+No hash needed; the artefact is the source of truth.
+
+## Two files carry the human side
+
+**`tools/DUPLICATION.md`** is the survey: what this repo states twice, where
+both copies live, which shape guards each, and what is knowingly left
+unguarded. The wiring-up writes it first, because a survey that lives only in
+a conversation is gone when the session is.
+
+**`tools/viewer.html`** is the search UI. Open it in a browser — no server, no
+dependencies — drop in the store JSONs your checks keep, and search every id,
+hash and summary. Paste a piece of source text and it computes the same key
+`stale.py` computes, then tells you whether anything still anchors that exact
+text. Read-only on purpose: re-anchoring stays a deliberate act in code,
+because the one action that must remain expensive is clearing a stale flag
+without looking.
+
+## It carries the discipline, not just the machinery
+
+When a defect is found:
+
+1. Fix the instance.
+2. **Name the class.**
+3. **Measure what else has that shape** — grep for the *claim*, not the sentence.
+4. Fix the class.
+5. **Add a check, and make it fail on purpose before believing it.**
+
+Step 5 is where this is won or lost. **A new check that passes has told you
+nothing.** It might be correct; it might be structurally incapable of failing,
+and you cannot tell those apart by reading it.
+
+## Why that last point is not paranoia
+
+`reference/traps.md` documents ten checks that shipped, each reporting a clean
+pass, each unable to fail. In **eight of ten the failure mode was a clean
+result** — not a crash, not a wrong answer, a pass. Examples:
+
+- `glob_newer_than("*.pdf", ".pdf", ".pdf")` — compared every file to itself and
+  reported *"9 rendered and current"*
+- a regex using `[^.]` to span `2.4 … 11.1`, where every id contains a period —
+  returned zero across the whole corpus, three times, by someone who had already
+  documented the bug twice
+- `if not X: return {}` upstream of `if X:` downstream — an unparseable input
+  silently switched off every check that depended on it, while the run printed `ok`
+- `if not path.exists(): continue` in a checker — a moved file quietly left the
+  watch list and the run still said `clean`
+
+Remembering these does not prevent them. Breaking the check does.
+
+## Contents
+
+```
+skills/node-engine/
+  SKILL.md              the method, the rule, and when not to use it
+  reference/
+    patterns.md         the three shapes, with implementations
+    traps.md            ten checks that could not fail — all real
+    taxonomy.md         thirteen defect classes, ranked by how many each produced
+  scaffold/
+    stale.py            the store and comparators (~150 lines, meant to be read)
+    checkall.py         the runner; `--prove` prints how to break each check
+    viewer.html         search the stores in a browser; paste text, see what anchors it
+```
+
+The scaffold is deliberately **not** a library. Copy it in, delete what you do
+not need, change what does not fit. A dependency you cannot read is one you will
+trust when it is wrong — which is the exact failure this plugin exists to prevent.
+
+## Origin
+
+Extracted from a bilingual legal package: nine documents making claims about a
+tenth, in two languages, with a generated digest in the middle. Thirteen defect
+classes and about forty real defects informed it.
+
+The examples throughout stay concrete on purpose. *"A check compared PDFs to
+themselves and reported 9 rendered and current"* transfers. *"Ensure comparison
+operands differ"* does not.
+
+## Licence
+
+MIT

nodeengine-0.1.0/README.md

@@ -0,0 +1,163 @@
+# NodeEngine
+
+A Claude Code plugin. Makes staleness **fail a check** instead of relying on
+someone remembering.
+
+*The name is literal: what it builds is a graph of **nodes** — clauses, blocks,
+generated files — each holding the hash of the source it was derived from. The
+engine walks that graph and reports every edge whose source has moved.*
+
+A fact stated twice is a fact that will disagree with itself — not might, will,
+usually within hours, because the two copies are edited by different people at
+different times for different reasons.
+
+The usual response is to be careful. That fails, because carefulness does not
+survive a deadline. What works is to make the second copy *derived*, and then
+make derivation *checkable*.
+
+## The idea, in one line
+
+> **Store the hash of the source beside the derived thing. Compare on every run.**
+
+```json
+"6.2B": { "hash": "3e40ff04…", "summary": "The reservations preserve rights as partners only…" }
+            ^^^^^^^^^^^^^^^^^ the source text when a human last confirmed
+                              this summary was true of it
+```
+
+Change the source and its hash changes; the summary no longer matches its
+anchor; the check says `summary-stale: 6.2B`. Nobody had to remember. The
+staleness is not caught by cleverness — it is **structurally unable to hide**.
+
+## Install
+
+One line, in any repo:
+
+```
+curl -sL https://raw.githubusercontent.com/Alexyodude/NodeEngine/main/install.py | python -
+```
+
+That copies `stale.py`, `checkall.py` and `viewer.html` into `./tools/` and
+prints what to do next. No clone, no plugin, no dependencies. Add
+`--into scripts` or `--dry-run` after `python -` if you want them.
+
+If you have [uv](https://docs.astral.sh/uv/), the same installer runs as a
+packaged tool — same files land, same refusal to overwrite:
+
+```
+uvx --from git+https://github.com/Alexyodude/NodeEngine nodeengine
+```
+
+*It runs code fetched over the network, which is worth being deliberate about.
+To read it first:*
+
+```
+curl -sL https://raw.githubusercontent.com/Alexyodude/NodeEngine/main/install.py -o install.py
+less install.py && python install.py
+```
+
+**As a Claude Code plugin**, if you also want the skill and the guided setup:
+
+```
+/plugin marketplace add Alexyodude/NodeEngine
+/plugin install node-engine@node-engine
+/node-engine:install
+```
+
+The plugin adds the method itself — an agent that knows the three shapes, the
+defect taxonomy, and the rule that a new check is guilty until it has failed on
+demand. The one-liner just gives you the files.
+
+## What it covers
+
+Three shapes, because different relationships need different guarantees:
+
+| Shape | For | Guarantee |
+|---|---|---|
+| **Anchored** | a human judgement about a source — summaries, descriptions, a sentence citing a spec | re-anchoring is an explicit act; you cannot clear a stale flag by accident |
+| **Content-addressed** | anything that must track an original exactly — translations, mirrors | the hash *is* the key, so a changed source has no entry rather than the wrong one |
+| **Ordered** | files a human generates by running a command | catches the case the others cannot: nobody ran it |
+
+Plus the cheapest win in most repos: **a number restated in prose should be
+computed at check time and compared** — version, file count, step count, size.
+No hash needed; the artefact is the source of truth.
+
+## Two files carry the human side
+
+**`tools/DUPLICATION.md`** is the survey: what this repo states twice, where
+both copies live, which shape guards each, and what is knowingly left
+unguarded. The wiring-up writes it first, because a survey that lives only in
+a conversation is gone when the session is.
+
+**`tools/viewer.html`** is the search UI. Open it in a browser — no server, no
+dependencies — drop in the store JSONs your checks keep, and search every id,
+hash and summary. Paste a piece of source text and it computes the same key
+`stale.py` computes, then tells you whether anything still anchors that exact
+text. Read-only on purpose: re-anchoring stays a deliberate act in code,
+because the one action that must remain expensive is clearing a stale flag
+without looking.
+
+## It carries the discipline, not just the machinery
+
+When a defect is found:
+
+1. Fix the instance.
+2. **Name the class.**
+3. **Measure what else has that shape** — grep for the *claim*, not the sentence.
+4. Fix the class.
+5. **Add a check, and make it fail on purpose before believing it.**
+
+Step 5 is where this is won or lost. **A new check that passes has told you
+nothing.** It might be correct; it might be structurally incapable of failing,
+and you cannot tell those apart by reading it.
+
+## Why that last point is not paranoia
+
+`reference/traps.md` documents ten checks that shipped, each reporting a clean
+pass, each unable to fail. In **eight of ten the failure mode was a clean
+result** — not a crash, not a wrong answer, a pass. Examples:
+
+- `glob_newer_than("*.pdf", ".pdf", ".pdf")` — compared every file to itself and
+  reported *"9 rendered and current"*
+- a regex using `[^.]` to span `2.4 … 11.1`, where every id contains a period —
+  returned zero across the whole corpus, three times, by someone who had already
+  documented the bug twice
+- `if not X: return {}` upstream of `if X:` downstream — an unparseable input
+  silently switched off every check that depended on it, while the run printed `ok`
+- `if not path.exists(): continue` in a checker — a moved file quietly left the
+  watch list and the run still said `clean`
+
+Remembering these does not prevent them. Breaking the check does.
+
+## Contents
+
+```
+skills/node-engine/
+  SKILL.md              the method, the rule, and when not to use it
+  reference/
+    patterns.md         the three shapes, with implementations
+    traps.md            ten checks that could not fail — all real
+    taxonomy.md         thirteen defect classes, ranked by how many each produced
+  scaffold/
+    stale.py            the store and comparators (~150 lines, meant to be read)
+    checkall.py         the runner; `--prove` prints how to break each check
+    viewer.html         search the stores in a browser; paste text, see what anchors it
+```
+
+The scaffold is deliberately **not** a library. Copy it in, delete what you do
+not need, change what does not fit. A dependency you cannot read is one you will
+trust when it is wrong — which is the exact failure this plugin exists to prevent.
+
+## Origin
+
+Extracted from a bilingual legal package: nine documents making claims about a
+tenth, in two languages, with a generated digest in the middle. Thirteen defect
+classes and about forty real defects informed it.
+
+The examples throughout stay concrete on purpose. *"A check compared PDFs to
+themselves and reported 9 rendered and current"* transfers. *"Ensure comparison
+operands differ"* does not.
+
+## Licence
+
+MIT

nodeengine-0.1.0/commands/install.md

@@ -0,0 +1,92 @@
+---
+description: Install NodeEngine's staleness guards into the current repository
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+---
+
+Install the NodeEngine scaffold here, then wire it to what this repository
+actually duplicates. Copying files is the trivial part; step 2 is the work.
+
+## Step 1 — Copy the scaffold
+
+```bash
+python "${CLAUDE_PLUGIN_ROOT}/install.py"
+```
+
+Add `--into <dir>` if this project does not use `tools/`. It refuses to
+overwrite existing files, so it is safe to re-run.
+
+## Step 2 — Find what is stated twice
+
+This is the whole job, and it cannot be done from a template. Survey the repo
+and build a real list. Look for:
+
+- **Numbers in prose** — versions, counts, sizes, "three steps", "nine files".
+  These are the most common and the cheapest to guard: compute them at check
+  time and compare.
+- **The same version in several manifests** — `package.json`, a lockfile, a
+  `__version__`, a badge in the README.
+- **Docs describing structure** — a README or CLAUDE.md with a directory tree,
+  a list of commands, a table of modules. Paths rot silently.
+- **Generated files** a human regenerates by running something.
+- **Anything translated or mirrored** — i18n, a second-language README.
+- **Summaries of code** — docstrings or docs that describe behaviour someone
+  can change without touching the description.
+
+Write the list to `tools/DUPLICATION.md` — each item, where both copies live,
+and (once decided) which shape guards it or why it is left unguarded. This file
+is the survey's permanent home; a list that lives only in the conversation is
+gone when the session is. Then report it to the user. Ask which matter; do not
+guard everything, and say plainly which ones you think are not worth it.
+
+## Step 3 — Pick a shape for each
+
+Read `${CLAUDE_PLUGIN_ROOT}/skills/node-engine/reference/patterns.md`.
+
+| The derived thing is… | Shape |
+|---|---|
+| a human judgement about a source | **anchored** — hash stored beside it, `--confirm` to re-anchor |
+| a mechanical transform that must match exactly | **content-addressed** — the hash is the key |
+| produced by a command someone runs | **ordered**, or have the generator self-check |
+| a count, size or inventory | **derive it live** — no hash needed, the artefact is the truth |
+
+That last row usually covers most of what you found.
+
+## Step 4 — Write the table, not the checks
+
+Edit `tools/checkall.py` so its `CHECKS` table names the real checks. Each row
+carries a fourth column: **how to make this one fail**. That column is not
+documentation — it is the verification instruction, and if you cannot fill it
+in, you do not yet know whether the check can fail.
+
+Adding a watched thing must mean adding a row. If it means writing a function,
+the design has drifted: that is how you get one guard per instance and a gap
+wherever nobody has been bitten yet.
+
+## Step 5 — Break every one
+
+```bash
+python tools/checkall.py --prove     # prints how to break each
+python tools/checkall.py             # should be green first
+```
+
+Then actually do it, one at a time: make the change, confirm the check fails,
+revert, confirm it passes. **Report the evidence** — the failing output, not
+"verified".
+
+Read `${CLAUDE_PLUGIN_ROOT}/skills/node-engine/reference/traps.md` before this
+step. Ten checks documented there shipped unable to fail, and in eight of ten
+the failure mode was a clean pass. The most common causes:
+
+- comparing a thing to itself
+- a pattern that cannot match the shape the text is in
+- a sweep returning zero, which reads as "clean"
+- an empty or missing input treated as "nothing to check" rather than as a finding
+- `if not path.exists(): continue` inside a checker
+
+## Step 6 — Record it
+
+Add a short section to `CLAUDE.md` (or the README) saying what is guarded, what
+is not, and how to run the checks. State the gaps plainly — a checking system
+that overstates its own coverage is the first thing to mislead someone.
+
+Then commit, with the evidence from step 5 in the message.