claude-memory-lint 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-18
+
+First public release.
+
+### Added
+
+- `memory-lint` CLI with a dispatcher over six detectors, plus an `all` subcommand
+  that runs every detector in one pass.
+- **`budget`** — closed size budget for the memory index: line count, byte count,
+  and a proximity warning before the reader's line limit is reached.
+- **`frontmatter`** — every memory file must carry valid frontmatter with a
+  non-empty `description`, so it can be selected instead of sitting unread on disk.
+- **`provenance`** — per-line provenance markers on claims that carry a date or a
+  number, with a baseline file so an existing archive can adopt the rule without a
+  flag on every pre-existing line.
+- **`perishable`** — perishable-state tracking: claims about external systems that
+  were true when written and decay silently afterwards.
+- **`pii`** — personal-data and secrets scan over the archive, with a category file
+  that can be replaced through config.
+- **`honesty`** — suppression-instruction detector, judged by the effect of the
+  instruction rather than by its wording.
+- Mention-is-not-use handling across the detectors: a marker, date, or pattern
+  inside a code span or backticks is read as an example, not as a real occurrence.
+- Machine-readable output and distinct exit codes per outcome, for use as a CI gate.
+- Config resolution from `memory-lint.config.json` and environment variables, over
+  built-in defaults.
+- No runtime dependencies and no network calls. The tool reads the archive and
+  reports; it never edits it.
+
+[Unreleased]: https://github.com/vgrosetti-maker/claude-memory-lint/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/vgrosetti-maker/claude-memory-lint/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nord Leads
+
+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.

package/README.md

@@ -0,0 +1,340 @@
+# claude-memory-lint
+
+[![CI](https://github.com/vgrosetti-maker/claude-memory-lint/actions/workflows/ci.yml/badge.svg)](https://github.com/vgrosetti-maker/claude-memory-lint/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/claude-memory-lint.svg)](https://www.npmjs.com/package/claude-memory-lint)
+
+Structural checks for an agent memory archive: size budget, required frontmatter, per-line provenance, perishable state, personal data, and suppression instructions.
+
+Six detectors, one CLI, machine-readable output, no network calls. It reads your memory files and reports. It never edits them.
+
+## The problem
+
+An agent memory archive is append-only by nature. Every session that ends well adds a line, and nothing ever takes one out. Three failure modes follow from that, and none of them announce themselves.
+
+**The index file grows past what the reader loads.** The memory index is read at every session boot. The host application loads up to a certain number of lines and warns about the rest. Newly written entries land at the end of the index, so they are the first to fall off the edge. The file still exists, the lines are still in it, and the agent simply never sees them. Nothing is broken, nothing errors, and the memory you wrote last week is silently out of context.
+
+**Provenance collapses.** In the same paragraph you will find something a person said, a number that came out of a command that actually ran, and the model's own guess. After a week nobody can tell them apart, and the guess gets cited later as if it had been measured.
+
+**Perishable state is recorded as if it were stable.** A handoff note says an external system is blocked, a migration is paused at step five, a spec lives in section two. All true the day it was written. Days later the block is gone, but the note still says it is there, and someone builds an expensive workaround around a restriction that no longer exists.
+
+None of the three produces an error message, so they surface only when somebody acts on the wrong answer, usually months later.
+
+## Install
+
+Requires Node 18 or newer. No dependencies.
+
+```
+npx claude-memory-lint all
+```
+
+Or install it in the project that holds your config and baseline:
+
+```
+npm install --save-dev claude-memory-lint
+npx memory-lint all
+```
+
+## Usage
+
+```
+memory-lint <command> [flags]
+```
+
+| Command | What it checks |
+| --- | --- |
+| `budget` | closed line and byte budget for the memory index file |
+| `frontmatter` | valid frontmatter with a non-empty `description` on every file |
+| `provenance` | per-line `(stated)` / `(measured)` / `(inferred)` markers |
+| `perishable` | stable residue vs. perishable state on state cards |
+| `pii` | personal data and secrets that should never be recorded |
+| `honesty` | suppression instructions, judged by effect |
+| `all` | runs every detector and reports each verdict |
+
+`--json` works on every command and prints the full verdict, including the failing lines, as JSON.
+
+```
+memory-lint budget --json
+memory-lint all --json
+```
+
+Note on `all --json`: it prints one JSON document per detector, separated by a `=== name ===` header line. That is a stream of six documents, not a single JSON document, so parse it per detector or call the detectors individually.
+
+### Flags handled at the dispatcher
+
+Two flags are read by `memory-lint` itself and work on every command:
+
+| Flag | Effect |
+| --- | --- |
+| `--archive <dir>` | scan `<dir>` instead of the auto-detected archive. It sets `MEMORY_LINT_DIR` for the detector's own process, so the origin line prints `MEMORY_LINT_DIR` next to the path. |
+| `--categories <file>` | `pii` only: use `<file>` instead of the shipped category list. It sets `MEMORY_LINT_PII_CATEGORIES`. |
+
+```
+memory-lint pii --archive ./fixtures/archive --categories ./my-categories.json
+memory-lint all --archive ./fixtures/archive
+```
+
+`--archive` is the flag to use when trying the tool out: point it at a throwaway directory instead of running the first check against a real archive.
+
+An unrecognized `--flag` is a hard error and exits `2`. It is never dropped silently, because a dropped flag means the detector goes on to scan whatever archive it finds by default, and a green result over the wrong directory reads exactly like a green result over the right one.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | checked, nothing failed |
+| `1` | checked, something failed |
+| `2` | **not checked**: archive missing, config unreadable, category list unreadable, baseline absent, or an unrecognized flag |
+
+Exit `2` is deliberately distinct from `0`. A check that could not run is not a check that passed, and a gate that reports "green" when it never looked is worse than no gate. In CI, treat `2` as a failure.
+
+### First run: creating the provenance baseline
+
+`provenance` refuses to run without a baseline, and exits `2` until one exists. Create it once:
+
+```
+memory-lint provenance --genesis
+```
+
+Genesis writes a content baseline: a per-file hash of every line that exists today, unfiltered. Those lines are exempt from judgment from then on. Only lines written after the baseline are judged. This is the alternative to a detector that debuts by flagging the entire archive, which leaves the gate permanently red and therefore meaningless. Commit the baseline file.
+
+Two more flags on `provenance`:
+
+- `--record-baseline` adds newly written lines to the baseline incrementally. It **rejects** any line that asserts a verifiable fact without a marker, so re-recording is not an amnesty: the rejected lines stay in the gate and the check stays red until they are marked.
+- `--audit-baseline` checks that the baseline file is committed and unmodified in git. An uncommitted baseline is an exemption list that nobody reviewed.
+
+## Configuration
+
+`memory-lint.config.json` in the current working directory, merged over the built-in defaults. Point `MEMORY_LINT_CONFIG` at another path to override the location.
+
+```json
+{
+  "budget": {
+    "lines": 200,
+    "bytes": 20000,
+    "readerLineLimit": 200,
+    "proximityWarning": 190
+  },
+  "provenance": {
+    "baselineFile": "memory-lint.baseline.json",
+    "markers": ["stated", "measured", "inferred"]
+  },
+  "perishable": { "cutoffDate": null },
+  "pii": { "categoriesFile": null }
+}
+```
+
+- `budget.lines` / `budget.bytes` are the ceiling for the index file. The shipped numbers are round placeholders, not a measurement of anything. Run `memory-lint budget` once, read your actual size, and set the ceiling to that size. That is what makes the budget *closed*: new content has to merge into or replace existing content instead of only adding to it.
+- `budget.readerLineLimit` is how many lines the host application actually loads at boot. It is configurable because it is the host's behavior, not this tool's, and it can change. It is checked separately from the budget: the budget bounds growth, this bounds visibility. A ceiling set above the reader's cutoff can stay green while the newest lines never reach context.
+- `budget.proximityWarning` warns before the reader limit starts cutting, rather than after.
+- `provenance.markers` sets the three marker words. They default to English; change them if your archive is written in another language.
+- `perishable.cutoffDate` (`YYYY-MM-DD`) judges only files touched on or after that date. Set it to the date you adopt the convention so pre-existing files are not flagged retroactively. `null` judges everything.
+- `pii.categoriesFile` points at your own category list. A custom file **replaces** the shipped list, it never merges with it, so a partial file silently drops the categories it omits.
+
+### Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `MEMORY_LINT_DIR` | the archive directory to check |
+| `MEMORY_LINT_CONFIG` | path to the config file |
+| `MEMORY_LINT_BASELINE` | path to the provenance baseline |
+| `MEMORY_LINT_PII_CATEGORIES` | path to the `pii` category list, replacing the shipped one |
+
+`MEMORY_LINT_PII_CATEGORIES` wins over `pii.categoriesFile` in the config file, which in turn wins over the shipped list. `--categories <file>` is the same setting from the command line: it sets the variable for the run.
+
+### Where the archive is found
+
+In order: `MEMORY_LINT_DIR` (which is what `--archive <dir>` sets), then `autoMemoryDirectory` in `~/.claude/settings.local.json` or `~/.claude/settings.json`, then a default derived from your home directory. Every command prints which of the three decided, next to the path. A path with no stated origin is how an audit ends up scanning the wrong folder and reporting a confident zero.
+
+## The six detectors
+
+### `budget`
+
+Measures the index file in lines and bytes against the configured ceiling, and separately against the reader line limit.
+
+Lines and bytes are a **proxy** for the token cost of loading the file at boot, never a conversion. A bytes-per-token ratio measured on English text underestimates other languages by a wide margin. If you want the real token number, measure it by ablation (compare two boots with and without the file), not by dividing bytes.
+
+### `frontmatter`
+
+Every file needs valid frontmatter with a non-empty `description`. Without one, the file is invisible to whatever decides which memory to open: it is on disk and it is never selected.
+
+Declared scope: it fails on missing frontmatter or a missing description. It does not judge whether the description is any good. That is a content call, not detectable by shape.
+
+### `provenance`
+
+One marker per claim, three values:
+
+- `(stated)` a person said so, this session or an earlier one
+- `(measured)` it came out of a command that actually ran
+- `(inferred)` the model's hypothesis, not verified
+
+A marker is required only on a line that **asserts a verifiable fact**: a number or count, a date, a URL, or an id or hash. Headings, blank lines, pointers to another note, separators and blockquotes are exempt by design. Reading "every line carries a marker" literally would make the file unreadable and fail the gate on plain prose, which is not the problem this solves.
+
+The cut is by **line**, not by file. Judging by file drags a whole old note into the gate the moment you append three lines to it, and an append-only archive gets appended to constantly.
+
+### `perishable`
+
+The split it enforces:
+
+- **Stable residue**: the area exists, the decision was made, the rule holds. Write it down, it ages well.
+- **Perishable state**: "paused at step 5 of 9", "the block is active", "the spec is in section 2". This is a measurement of a moment. Let it expire, or if it has to stay on record, give it a **measurement date** and a **recheck route**, so it is perishable by construction.
+
+Which files count as state cards comes from a declared signal, not from reading prose: `type: project` in the frontmatter, or an explicit `measuredOn:` / `recheck:` field. Judging the body by keyword ("paused", "live", "active") was considered and rejected, because it cannot tell an actual state claim from prose describing someone else's state, and it produces false positives in both directions.
+
+### `pii`
+
+Scans for personal data and secrets against one category list, `lib/pii-categories.json`. The detector file declares no pattern of its own: a category that lives in two places becomes two categories that drift, and the one that drifts is always the one the gate reads.
+
+Three gate levels:
+
+| Gate | Behavior | Categories |
+| --- | --- | --- |
+| `block` | an occurrence exits `1` | `nationalId`, `bankAccount`, `health`, `credential` |
+| `warn` | counted and reported, never exits `1` | `minor`, `specialCategoryOther`, `directIdentifier`, `onlineIdentifier`, `criminalRecord` |
+| `doctrine` | not detectable by form, carries no pattern, never enters code | `falseAnonymity` |
+
+#### What the gate measures
+
+Every category carries a `gateRationale`. It prints on every run, under that category's count line, and it sits in `--json` at `summary.byCategory.<id>.gateRationale`. Read it before you read the gate, because the gate ranks how far the pattern can be trusted. **A `warn` category is not a less sensitive category.**
+
+`health` is `block` and `minor` is `warn`. Both are special-category data under GDPR Art. 9(1), carrying the same legal exposure. What differs is the vocabulary. The clinical terms behind `health` have almost no other meaning in an engineering note. The words that signal a minor collide constantly with ordinary prose, where a "child" is a DOM node or a process. `specialCategoryOther` is `warn` for the same reason, and `criminalRecord` is `warn` even though Art. 10 carries its own strict regime, because "requires a background check" is a policy sentence and a real disclosure written with the same words.
+
+So a clean `block` line with warnings under it is not a clean archive. It is an archive where the high-precision patterns found nothing and the noisier ones found something a human still has to read.
+
+#### Why a `doctrine` category prints no count
+
+`falseAnonymity` is never evaluated. The report prints `not machine-checkable — needs a human pass` for it, and `--json` carries `machineCheckable: false` on that category and `true` on the other nine. It used to print `0 occurrence(s)`, which is indistinguishable from a check that ran and came back clean.
+
+#### The report state
+
+`pii` reports one of three states, at the top level of `--json`:
+
+| `state` | Meaning | Exit |
+| --- | --- | --- |
+| `ok` | no occurrence in any machine-checkable category | `0` |
+| `ok_with_warnings` | nothing in a `block` category, at least one `warn` occurrence | `0` |
+| `blocked` | at least one occurrence in a `block` category | `1` |
+
+`ok_with_warnings` exists because the run used to report `ok` with warnings sitting in the same summary. Exit codes did not change: only a `block` occurrence exits `1`, so a CI job keyed on the exit code behaves as it did. A job that wants warnings to be visible has to read `state`, or `summary.warning`.
+
+Ten categories, of which three are `warn` categories that are easy to overlook:
+
+- `directIdentifier` — an e-mail address or a phone number. Carve-out: a published business contact.
+- `onlineIdentifier` — an IPv4 address, which is personal data when it can be tied to a person. Carve-out: a CIDR range or reserved block used to document infrastructure. A cookie or device ID is deliberately not matched: there is no shared format across vendors to match on.
+- `criminalRecord` — an offence, conviction or related proceeding. Carve-out: stating a policy requirement rather than a person's record.
+
+`credential` matches shapes that exist for nothing but the secret itself: a token or key format, a PEM private-key header (`-----BEGIN ... PRIVATE KEY-----`), and a password written out in plain text (`password:` or `password=` followed by a value). Like `nationalId` and `bankAccount`, it is matched against the raw line, so a key header or a password pasted inside a fenced log block still counts.
+
+`specialCategoryOther` also carries a **genetic data** pattern (`genetic test / marker / screening / data`, `DNA test / sample / marker`) alongside the rest of its closed vocabulary. Art. 9 names genetic data next to biometric data, and only the second one had a term.
+
+The detector **refuses** a category that declares `doctrine` and still carries a pattern. That would be doctrine becoming a gate through the back door.
+
+Two things worth knowing before you read a report:
+
+- A long numeric platform id can match the phone-number pattern and be counted as a `directIdentifier` warning. It is noise, not a block, and it is the price of a phone pattern loose enough to catch international formats.
+- The shipped category list carries a Luhn-valid test card number and a canonical example IBAN as fabricated examples. They are public test values, not anyone's data, but a third-party secret scanner may flag them.
+
+Exemptions are scoped two ways: an exemption applies to the pattern ids named in its `appliesTo` (all of the category's patterns when `appliesTo` is absent), and it has to appear in the **same clause** as the match, where clauses split on `, ; : . ! ?`. "Card ending in 6467" is one clause and stays exempt; a carve-out phrase in a different clause of the same line does not excuse a match somewhere else on that line.
+
+An exemption can also be voided. `nullifiedBy` on an exemption lists the pattern ids that cancel it: if any of them matches in the same clause, the exemption does not apply, even where its own wording is present. The case it exists for is a note that names a category in order to teach it. "PII note: the contact has cancer" and "Never store this kind of thing: the contact is pregnant" both name the rule and record the thing the rule forbids, in one clause. Naming a category is not a carve-out for a real occurrence of it, so the clinical patterns are listed in `nullifiedBy` on that exemption and the occurrence is reported.
+
+`health` ships with a closed vocabulary and a declared low coverage, stated in the category record itself. It is the pattern most likely to miss a real case, because prose describing a condition in someone's own words will not match a closed vocabulary. Declaring that gap is the honest response; widening the regex would only hide it behind false positives.
+
+### `honesty`
+
+No memory in the archive should contain an instruction that, if followed, would make a real problem stop being raised. Someone tells their agent it can disagree and push back, then on a bad afternoon writes a memory saying to stop questioning their numbers. From then on, every future session quietly obeys the second instruction, and nobody notices until an error that should have been flagged was not.
+
+**The criterion is the effect, not the wording.** An instruction is still caught when it arrives softened ("only flag it if it's really bad"), scoped to one topic, justified by a deadline, or dressed up as a preference about format, tone or efficiency. So the detector never looks for one forbidden sentence. It looks for the structure *suppressor plus honesty act*, across six families: `negated_act`, `negated_signal`, `silencing`, `noun_cut`, `forced_agreement`, `severity_threshold`.
+
+**What passes:** a legitimate preference about *form*. Length ("keep it short"), tone ("blunt, no pleasantries"), directness ("skip the preamble"), scope of an edit ("only change the part I asked about"). None of those stop a problem from being raised, and none of them trip this detector.
+
+A finding here is not fixed by writing a softer version of the same memory. Needing a softer version is itself the signal that the line should not be on record. Editing a memory is the owner's call, not the tool's.
+
+## Mention is not use
+
+Shared by `provenance`, `perishable`, `pii` and `honesty`: text inside a backtick span or a fenced code block is quotation and is out of judgment, both ways. A note explaining one of these detectors has to be able to show the phrase it catches without tripping the gate on itself. A marker quoted inside backticks equally does not count as a real marker.
+
+Three `pii` categories opt out of that rule: `nationalId`, `bankAccount` and `credential` are matched against the raw line, code spans included. For a category whose match *is* the leak, a token or an ID pasted inside a fenced log block is still a leaked token or ID. The prose categories a note might cite while explaining itself keep the exemption.
+
+Quotation marks are deliberately **not** exempted the same way. A real instruction fits inside quotes just as well as a quoted one does, so exempting them would move the false positive rather than remove it.
+
+## Design choices
+
+Three that are easy to miss from the command list:
+
+1. **Provenance is per line, with a content baseline.** Not per file, not per session, and with no amnesty path: re-recording the baseline rejects unmarked lines instead of absorbing them.
+2. **Perishable and stable are different kinds of memory**, and only the perishable kind is required to carry an expiry route. The boundary is a declared frontmatter signal, never a keyword scan of the prose.
+3. **Personal data is a gate on the memory archive itself**, with the categories in data rather than in code, and with the low-recall category saying so in its own record instead of implying coverage it does not have.
+
+## What this tool does not see
+
+Read this section before trusting a green result.
+
+- **It never edits your memory files.** Every detector reports. Remediation is a human decision.
+- **`memory-lint budget` reads `MEMORY_LINT_DIR`, or the current directory if that is unset.** It does not use the archive auto-discovery the other five detectors use. If `budget` reports the index file as absent, set `MEMORY_LINT_DIR`.
+- **Lines and bytes are not tokens.** See `budget` above.
+- **`provenance` only judges lines written after the baseline.** Everything older is reported as declared backlog and is never judged. The count is printed so the gap is visible rather than implied.
+- **`provenance` judges whether a claim carries a marker, not whether the marker is true.** Writing `(measured)` on a number you invented passes.
+- **`perishable` only looks at files that declare themselves state cards.** Perishable state written in a file with no such signal is not seen.
+- **The prose-based `pii` categories (`health`, `minor`, `specialCategoryOther`, `criminalRecord`) use English vocabulary only.** An archive kept in another language will have lower recall on those until someone adds that language. The format-based categories (`nationalId`, `bankAccount`, `credential`, `onlineIdentifier`, and the e-mail pattern of `directIdentifier`) are language-independent. This limit is stated in `_meta.languageScope` of the category list, and repeated in `_meta.coverageScope`.
+- **`pii` declares a list of things it does not scan for at all**, printed under `NOT scanned by this list` on every run and held in `_meta.coverageScope`: a person's **name** in free-form prose, a full **postal address** in prose, **precise geolocation** written as prose rather than coordinates, a **cookie or device identifier**, and **philosophical or political conviction** beyond the closed vocabulary already in `specialCategoryOther`. Names and addresses have no fixed shape to match on, and catching them needs named-entity recognition, which this list does not attempt. A clean `pii` run says nothing about any of them.
+- **`pii` never evaluates `falseAnonymity`.** It is a `doctrine` category: re-identification by combination is a judgment about how small a population a set of attributes narrows down to, and no regex approximates that. The report says `not machine-checkable` for it on every run instead of a count, so a green `pii` run says nothing at all about it.
+- **A `warn` gate ranks the pattern, not the data.** `minor`, `specialCategoryOther` and `criminalRecord` carry the same legal exposure as the categories that block; their patterns are just noisier. Each category's `gateRationale`, printed on every run, states the reason for its own gate.
+- **`pii` does not decide legal basis, retention, or whether you are allowed to hold a piece of data.** It reports that something matching a category is sitting in a long-lived file. What follows from that is your call and your jurisdiction's.
+- **`honesty` catches a structure, not an intention.** A suppression phrased outside its six families will pass, and a sentence that resembles the structure while meaning something else can be flagged. Treat a finding as a prompt to go read the line.
+- **Nothing here judges whether a memory is *worth keeping*.** Every check is structural. A well-formed, fully marked, budget-compliant archive of useless notes passes cleanly.
+
+## Example
+
+Synthetic archive, two files:
+
+```
+$ memory-lint all
+=== budget ===
+archive: /tmp/archive/MEMORY.md
+lines: 3 / budget 200   bytes: 54 / budget 20000
+
+BUDGET: within budget
+
+=== perishable ===
+total: 1  state cards: 1  stable residue (out of scope): 0
+in cutoff: ok 0  unmarked 1  (missing: 2)
+
+PERISHABLE: 1 failed.
+  example-card.md  [measurement_date+recheck_route]  (metadata.type: project)
+```
+
+Every number above comes from a two-file archive fabricated for this example, and the budget figures in it are the shipped placeholder defaults. They are not a measurement of any real archive.
+
+A `pii` run over a second fabricated archive, trimmed to the lines that show the per-category output:
+
+```
+$ memory-lint pii --archive ./fixtures/archive
+pieces judged: 2  occurrences: 1 (block 0 / warn 1)
+  ...
+  onlineIdentifier [warn]: 1 occurrence(s), 0 exempt(ed) by carve-out
+      gate: warn: an IPv4 address is only personal data when it links back to a
+      person, and this list has no way to tell [...]
+  falseAnonymity [doctrine]: not machine-checkable — needs a human pass
+      gate: doctrine, not warn: re-identification by combination has no fixed
+      shape at all [...]
+
+  note-one.md (body):1  [onlineIdentifier/ipv4]
+     ... The staging box answered from 203.0.113.9 (measured). ...
+```
+
+The same run with `--json` reports `"state": "ok_with_warnings"` and exits `0`. The two `gate:` lines are each one line in the real output, wrapped and cut here to fit. The archive is fabricated and the address is from the documentation range reserved for examples.
+
+## In CI
+
+```yaml
+- run: npx memory-lint all
+```
+
+`all` exits with the worst code of the six, so `2` (something could not be checked) fails the job the same as `1`. If you run only `provenance`, remember the baseline has to be committed for `--audit-baseline` to mean anything.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

package/bin/memory-lint.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+'use strict';
+// Unified CLI: dispatches to each detector's own CLI block.
+//
+// Usage:
+//   memory-lint budget [--json]
+//   memory-lint frontmatter [--json]
+//   memory-lint provenance [--json | --record-baseline | --genesis | --audit-baseline]
+//   memory-lint perishable [--json]
+//   memory-lint pii [--json]
+//   memory-lint honesty [--json]
+//   memory-lint all [--json]
+//
+// Each subcommand's exit code is the standard one for that detector: 0 ok,
+// 1 failed, 2 not checked (archive/config missing). `all` exits non-zero if
+// any sub-check exits non-zero.
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const HELP = `memory-lint <command> [flags]
+
+Commands:
+  budget        closed line/byte budget for MEMORY.md
+  frontmatter   required frontmatter + description on every file
+  provenance    per-line (stated)/(measured)/(inferred) marker check
+  perishable    stable residue vs. perishable state on "project" cards
+  pii           personal data / secrets that should never be recorded
+  honesty       suppression instructions, judged by effect
+  all           run every detector, report each verdict
+
+Flags are forwarded to the detector:
+  --json              full verdict as JSON, on any command
+  --genesis           provenance only: write the initial line baseline
+  --record-baseline   provenance only: add new lines, reject unmarked ones
+  --audit-baseline    provenance only: check the baseline is committed in git
+
+Flags handled HERE, at the dispatcher, on every command:
+  --archive <dir>     scan <dir> instead of the auto-detected archive
+                       (sets MEMORY_LINT_DIR for the detector's own process)
+  --categories <file> pii only: use <file> instead of the shipped category
+                       list (sets MEMORY_LINT_PII_CATEGORIES)
+
+An unrecognized "--flag" is a hard error (exit 2), never a silent no-op: a
+misspelled or unsupported flag used to be dropped on the floor and the
+detector would go on to scan whatever archive it finds by default — a green
+result over the WRONG directory reads exactly like a green result over the
+right one.
+
+Exit codes: 0 nothing failed | 1 something failed | 2 NOT CHECKED (archive,
+config, baseline missing, or a bad flag). "all" exits with the worst code of
+the six. See README.md.
+`;
+
+const DETECTORS = {
+  budget: path.join(__dirname, '..', 'lib', 'detectors', 'budget.js'),
+  frontmatter: path.join(__dirname, '..', 'lib', 'detectors', 'frontmatter.js'),
+  provenance: path.join(__dirname, '..', 'lib', 'detectors', 'provenance.js'),
+  perishable: path.join(__dirname, '..', 'lib', 'detectors', 'perishable.js'),
+  pii: path.join(__dirname, '..', 'lib', 'detectors', 'pii.js'),
+  honesty: path.join(__dirname, '..', 'lib', 'detectors', 'honesty.js'),
+};
+
+// Flags every detector's own CLI block already parses for itself — these
+// pass through untouched. `--archive`/`--categories` are NOT in this set:
+// they are consumed here and turned into env vars instead (see `parseArgs`).
+const PASSTHROUGH_FLAGS = new Set(['--json', '--genesis', '--record-baseline', '--audit-baseline']);
+
+// Splits `rest` into: env overrides this dispatcher applies, flags to forward
+// to the detector's own process unchanged, and (if anything doesn't parse) an
+// error message. Never returns a partially-applied result silently — either
+// everything parsed, or `error` is set and nothing runs.
+function parseArgs(rest) {
+  const forward = [];
+  let archive = null;
+  let categoriesFile = null;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === '--archive') {
+      archive = rest[++i];
+      if (archive === undefined) return { error: '--archive requires a directory argument' };
+      continue;
+    }
+    if (a === '--categories') {
+      categoriesFile = rest[++i];
+      if (categoriesFile === undefined) return { error: '--categories requires a file argument' };
+      continue;
+    }
+    if (a.startsWith('--')) {
+      if (!PASSTHROUGH_FLAGS.has(a)) return { error: `unknown flag "${a}"` };
+      forward.push(a);
+      continue;
+    }
+    return { error: `unexpected argument "${a}" (flags start with --)` };
+  }
+  return { forward, archive, categoriesFile };
+}
+
+function run(name, extraArgs) {
+  const parsed = parseArgs(extraArgs);
+  if (parsed.error) {
+    console.error(`memory-lint: ${parsed.error}\n`);
+    console.log(HELP);
+    return 2;
+  }
+  const env = Object.assign({}, process.env);
+  if (parsed.archive) env.MEMORY_LINT_DIR = parsed.archive;
+  if (parsed.categoriesFile) env.MEMORY_LINT_PII_CATEGORIES = parsed.categoriesFile;
+  const args = [DETECTORS[name], ...parsed.forward];
+  const r = spawnSync(process.execPath, args, { stdio: 'inherit', env });
+  return r.status === null ? 2 : r.status;
+}
+
+function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    console.log(HELP);
+    process.exit(cmd ? 0 : 2);
+  }
+  if (cmd === 'all') {
+    let worst = 0;
+    for (const name of Object.keys(DETECTORS)) {
+      console.log(`\n=== ${name} ===`);
+      const code = run(name, rest);
+      worst = Math.max(worst, code);
+    }
+    process.exit(worst);
+  }
+  if (!DETECTORS[cmd]) {
+    console.error(`memory-lint: unknown command "${cmd}"\n`);
+    console.log(HELP);
+    process.exit(2);
+  }
+  process.exit(run(cmd, rest));
+}
+
+main();