@ersbeth/codelife 0.0.0-bootstrap.0 → 0.11.1

package/scripts/lenses/FAIL.md

@@ -0,0 +1,57 @@
+# Lens FAIL — Silent failures
+
+## Objective
+
+Say where a failure stays silent — swallowed, unawaited, hidden behind a fallback, or lost as it
+crosses a boundary. A failure that reports itself is a bug someone will fix; one that returns the
+same value as success is a bug nobody sees until its consequence arrives somewhere else.
+
+## Questions
+
+- **Does any `catch` swallow?** An empty handler, one that logs and carries on as if nothing
+  happened, one that catches everything to handle one case. Whatever file it is in — a build
+  script, a test's cleanup, a hook — the failure it hides is this lens's.
+- **Is every promise awaited, every status read?** A call whose rejection nobody observes, an exit
+  code nobody checks, a `|| true` that turns a failure into a pass.
+- **Does a fallback hide an error?** A default returned when the real value could not be read is a
+  decision; returned without saying so, it is a failure wearing the shape of success.
+- **Does a failure stay a failure as it crosses a boundary** — a subshell, a pipe, a callback, a
+  worker, a process? A flag set where nobody reads it is the classic form.
+- Is anything **guarded by a comment instead of by code** — *must be called after init*, *do not
+  pass null* — so that breaking it fails nowhere?
+- Are the **known limits written where a user meets them**? A documented limit is a decision; an
+  undocumented one is a failure nobody will report.
+
+## Probes
+
+- **The shell scripts this repository ships** — the tracked files whose first line is a shell
+  shebang, `^#!.*sh`: the subject of the next two. None → FAIL's shell probes have no subject, said
+  under `Limits` — finding nothing in no script is the wrong answer wearing the shape of "every
+  script is armed".
+- **Does every shipped script arm itself against unset variables and failed pipes?** — the scripts
+  in which `set -[a-z]*u` is not found.
+- **The failure that does not cross the boundary** — `\| *while` in those scripts: a `while` on the
+  right of a pipe runs in a subshell under bash, so a flag set inside it is lost when the loop ends.
+- **Failures turned into passes**, in every tracked file — `\|\| *(true|:)( |$)`.
+- **Handlers that swallow**, in the languages the tree carries —
+  `catch *(\([^)]*\))? *\{ *\}|except[^:]*: *pass`.
+
+## For a change
+
+A change adds no path that can fail without saying so — a `catch` that swallows, a promise not
+awaited, a `|| true`, a fallback that returns a default where it used to throw — and widens no
+`catch` that was narrow. A call it moves across a boundary — into a callback, a subshell, a worker
+— still reports its failure to the caller. A test's setup or cleanup is code like any other: a
+restore that can fail silently is this lens's, not VERIF's.
+
+## Signals learned
+
+- **`| while` is codelife's own recurring defect**, and a shape worth looking for anywhere.
+  Campaign A1 filed it as T-4 — a `ko` setting `fail=1` inside a pipeline subshell, so the script
+  printed FAIL and exited 0. It was fixed, and then written again in one of the plugin's own suites
+  in the very session that fixed it. Read from a redirect: `done < <(…)`.
+- A variant worth its own look: a pipeline that **swallows its own diagnostics**. The same file
+  piped its FAIL lines into `grep -q`, so the check fired correctly and never showed which line
+  triggered it. A guard that cannot say *where* costs as much as one that does not fire.
+- `set -euo pipefail` at the top of every script is a good sign and not a conclusion — `-e` does not
+  survive a function called in a condition, which is where the interesting failures live.

package/scripts/lenses/GOV.md

@@ -0,0 +1,56 @@
+# Lens GOV — Governance & release
+
+## Objective
+
+Say whether every branch has a status, every version a tag, and the licence a decision. This lens
+looks at what the repository says about itself as a project rather than as code — and its findings
+are usually things nobody owns, which is why they accumulate.
+
+## Questions
+
+Whether a merged branch is still a head on `origin`, a name falls outside the model, the shipped
+version has no tag, a licence is missing, and this clone keeps refs the forge deleted, is the
+script's to say. A branch list nobody prunes is a list nobody reads, and the one stale branch that
+matters hides in it.
+
+- **Does every branch have a status?** Unmerged and untouched for months, or kept for a reason
+  nobody wrote down.
+- **Does every tag have a release entry?**
+- **Who may merge to `main` and `develop`?** A default branch anyone with push rights can merge
+  to, or force-push, is a release nobody reviewed.
+- Is the **licence decided and consistent** — the same identifier in `LICENSE`, the manifest and the
+  published artefact?
+
+## Probes
+
+`GOV.mjs`, run by `verify` before the lenses, whose lines you are handed. Read
+from `origin` — a remote-tracking ref outlives the branch's deletion at merge — it
+reports each head merged into `develop` and still there, an `origin` with no `develop`, each name
+outside the model, the version of the contract's `release.version_file` with no tag, no `LICENSE`,
+that manifest with no `license`, each ref this clone keeps for a branch the forge deleted, and
+`fetch.prune` not set to `true`. With `origin` unreachable it could not tell — never an empty
+list, which would read as *no merged branch left*.
+
+The forge's own settings — its protected branches and who may merge or push to each — are read by
+no one: say so in one *Limits* line.
+
+## For a change
+
+**No** — a change says nothing about the branch list, the tag history or the licence.
+
+## Signals learned
+
+- **The forge's harvest and the clone's drift are two numbers, and only one of them is this
+  lens's.** Measured on codelife, at its campaign A3: `origin` held four heads, of which one was
+  merged into `develop` and still present, while this clone carried six remote-tracking refs for
+  branches the forge had already deleted at merge. The script takes the first from `git ls-remote`
+  and the second from the difference; a probe that reads `refs/remotes` for the first reports the second and
+  calls it the first.
+- **Zero tags with a `0.0.0` version is a coherent state**, not a defect: nothing has been released.
+  Say so rather than filing a missing-tag finding — the defect would be a bumped version *without*
+  a tag.
+- **The manifest that must name the licence is the one the artefact ships with** — the contract's
+  `release.version_file` — and a root `package.json` that is private and unpublished has no consumer
+  to decide it for: its missing `license` key is not a finding. On codelife, a finding was filed
+  against exactly that, from a probe that read `package.json` while the shipping manifest agreed
+  with `LICENSE`.

package/scripts/lenses/GUARD.md

@@ -0,0 +1,47 @@
+# Lens GUARD — CI and guards
+
+## Objective
+
+Say what actually stops a regression from shipping, and whether the guards check facts or merely
+declare intentions. A hook that runs a script that runs nothing is a guard with nothing behind it,
+and it looks green.
+
+## Questions
+
+Whether the hooks are wired and executable, the tiers exist and run something, and every guard of
+the contract resolves, is the script's to say; a guard pointing at a deleted script never fires and
+never says so.
+
+- **What runs, and when?** Map each hook to the script it calls and each script to what it
+  actually executes, reading them. Follow it to the end: a tier that runs something may still run
+  nothing that matters.
+- Are the hooks **versioned**? `.githooks/` in the repository, `core.hooksPath` set by
+  `postinstall` — or a hook that exists only in one developer's `.git/hooks/`, which protects
+  nobody else.
+- Does **CI run what the hooks run**? A check that exists only locally is bypassed by anyone who
+  pushes from another machine; a check that exists only in CI lets a red commit into the branch.
+- Can a guard be **bypassed silently**? `--no-verify` is always available — the question is
+  whether the repository notices afterwards.
+
+## Probes
+
+`GUARD.mjs`, run by `verify` before the lenses, whose lines you are handed — the
+tiers themselves are the campaign's baseline, already run. It reports `core.hooksPath` unset or
+naming nothing, each hook that is not executable, a `verify:commit` or `verify:push` absent or
+hollow — nothing but `echo` — and each `guards[].run` command not found.
+
+## For a change
+
+A change weakens no guard — no hook shortened, no check removed, no threshold raised — and a hook it touches checks a fact, not a declaration. A
+weakened guard costs nothing to the change that weakens it, which stays green, and everything to
+the next one.
+
+## Signals learned
+
+- **A tier that prints `nothing to run` passes.** Found on codelife: `verify:push` guarded the
+  moment code leaves the machine and proved nothing. Always follow a script to what it executes,
+  never stop at its exit code.
+- A `pre-commit` that reformats files without re-staging them leaves the commit missing the
+  formatting it just applied.
+- Hooks wired by `postinstall` only protect someone who has run an install. A fresh clone that is
+  read, edited and committed without installing has no hooks at all.

package/scripts/lenses/INTENT.md

@@ -0,0 +1,52 @@
+# Lens INTENT — Intent
+
+## Objective
+
+Say whether the code does what was asked of it — what its issues asked of a change, what `docs/spec/`
+specifies of a tree. A change can be correct, tested and clean and still not be the change anyone
+wanted; nothing else in a campaign reads the code against the request.
+
+## Questions
+
+- **What is missing?** A requirement the request states, a case it cites, something the author
+  announces as done — in the description, a commit, a comment — that the code does not do.
+- **What is extra?** Behaviour the request did not ask for, slipped in beside what it did. Not
+  wrong by itself: unasked, so unreviewed against any intention.
+- **What is misunderstood?** The code does something close to what was asked and not it — the
+  right case under the wrong condition, the rule applied to the wrong set.
+- **Is each verifiable claim of the author true?** *Fixes X*, *covers every caller*, *no behaviour
+  change*: each one checked against the code, never taken as given.
+- **In tree scope, does the tree do what the specification states?** Read a rule and its cases,
+  then the code or the skill that should do it, and say whether they agree.
+
+A drift **quotes both sides and chooses neither**: which one is wrong is the author's decision —
+the specification is obsolete, and a new note records the change, or the implementation is wrong,
+and it gets a fix. The recommendation says so, and is always **untried**: choosing the side is the
+author's.
+Whether a document's *verifiable statements* —
+a command, a path, a version — are true is DOC's; whether the behaviour it *specifies* is done is
+this lens's.
+
+## Probes
+
+- **The specification's rules and cases**, the referential of a tree-scope run —
+  `^#{3,4} [A-Z]+-[0-9]+ — ` over `docs/spec/`. No `docs/spec/` among the tracked files → nothing is
+  specified: say so under `Limits`, never compare against a README instead.
+- **What implements a rule** — where a rule names a skill, a command or a file, that name as a whole
+  word, a fixed string, outside `docs/spec/`.
+
+The probes list what is specified; the method is reading each rule beside its implementation.
+Name in *Method* which rules were read — a campaign cannot read every one, and the ones it did not
+read are a line of *Limits*.
+
+## For a change
+
+**The issue first** — what it asks, and the rules and cases it cites. A change meets each
+requirement and each cited case, at a place the plan names; adds nothing the issue does not ask;
+and makes no claim, in its commits or its description, that is not true. A requirement no file of
+the plan can meet is said at the plan, before any code.
+
+## Signals learned
+
+- **This lens ships without campaign history**, written when the specification moved the merge
+  request's intention out of DOC's duties. Its first campaigns will write this section.

package/scripts/lenses/LEAN.md

@@ -0,0 +1,49 @@
+# Lens LEAN — Code that should not exist
+
+## Objective
+
+Say what code the repository carries that it does not need — dead, duplicating what the platform
+or a dependency already does, abstracted for a second case that never came, or longer than the
+logic it says. Every line is a line the next reader reads and the next review searches; the
+cheapest code to keep true is the code that is gone.
+
+## Questions
+
+- **What is dead?** A function nothing calls, a branch no input reaches, a flag never set, a file
+  nothing references. Not style: dead code is a statement about intent that no longer holds.
+- **What does the standard library, the platform or an installed dependency already do?** A
+  hand-written helper beside the built-in that does the same, a second library for one function of
+  the first.
+- **Which abstraction has one implementation?** An interface with one class, a factory with one
+  product, a parameter every caller passes the same value — an indirection a reader pays for and
+  nothing uses.
+- **What shorter form says the same logic?** A loop that is a `map`, a chain of conditions that is
+  a table, two near-identical functions that are one with a parameter.
+
+A point here is a finding only when its fix removes code: the fix's balance decides, as for every
+lens, and a shorter form that adds a dependency or a layer is not lean.
+
+## Probes
+
+- **Files nothing references** — a first pass, by name: for each tracked `*.sh`, `*.mjs`, `*.js` or
+  `*.ts`, its basename as a whole word, a fixed string, in every other file. Read each file with no
+  hit before reporting it: a file can be loaded by a pattern, a manifest or a tool's convention
+  rather than by its name.
+- **Exported names used nowhere but their own file** — `export (function|const|class) [A-Za-z0-9_]+`,
+  then each name as a whole word, the files that carry it listed. The export syntax is the
+  language's: name the one you used in *Method*.
+- **The names that mean "nowhere else to put this"** — tracked paths through a `utils`, `helpers`,
+  `misc` or `common` directory; their contents are often a platform's function written again.
+
+## For a change
+
+A change adds no code that should not exist — a helper the platform already has, an abstraction
+with one implementation, a branch nothing can reach, a longer form of logic the file already says
+shortly — and leaves nothing dead of what it replaced: no old function still there, no flag no
+longer read.
+
+## Signals learned
+
+- **This lens ships without campaign history**, written when the specification made a
+  simplification a finding whichever lens finds it. Its first campaigns will write
+  this section.

package/scripts/lenses/LINES.md

@@ -0,0 +1,48 @@
+# Lens LINES — Release lines
+
+## Objective
+
+Say which release lines exist, how far each has drifted from the one that ships — **in both
+directions** — and what carries a fix across them. A line nobody ports to is a line whose users are
+on their own; a line whose divergence nobody has measured is worse, because the decision to keep it
+was never re-taken.
+
+## Questions
+
+Which older lines exist on the forge and how far each has diverged from `main`, in both directions,
+is the script's to say. What the counts are made of — fixes or features — it does not say, and a
+line of *Limits* says so rather than a guess.
+
+- For each older line, **what does it have that the shipping line does not, and what does the
+  shipping line have that it does not?** Both directions, always: the second is the backlog of
+  unported fixes, the first is what deleting the line would lose.
+- **What ports a fix across** — a written procedure, a habit visible in the history, or nothing? A
+  cherry-pick nobody documented is a procedure one person knows.
+- **Is each line's head tagged**, and does its tag agree with the version its manifest declares?
+- **Which lines are supported**, and is that written where a consumer reads it rather than where a
+  maintainer remembers it?
+- A line that has diverged in **neither** direction can be closed; a line that has diverged in
+  **one** has been abandoned in the other, and which one it is decides who is hurt.
+
+## Probes
+
+`LINES.mjs`, run by `verify` before the lenses, whose lines you are handed. Read
+from `origin`, it measures each `support/*` line against `main` in both directions and reports a
+line diverged one way only, with its two counts, and a line diverged in neither, which can be
+closed. With `origin` unreachable, or one release line, it could not tell.
+
+## For a change
+
+**No** — a change lands on one line and says nothing about the distance between lines.
+
+## Signals learned
+
+- **This lens ships without campaign history**, its subject being a repository with more than one
+  release line and the plugin's own having one. Grow it from the first campaign that runs it.
+- **Divergence in one direction only is the finding.** Equal counts both ways are two lines being
+  maintained; commits only on the shipping line are an abandoned older line whose users still
+  install it. Report the direction, never a single distance.
+- **The porting procedure is the real subject.** Where none is written, the finding is the absence
+  and not the arithmetic — the numbers will be different next campaign and the gap will not.
+- A tag that disagrees with its line's manifest is a release nobody can reproduce; it belongs here
+  when it is about a line, and to GOV when it is about the repository as a whole.

package/scripts/lenses/PERF.md

@@ -0,0 +1,61 @@
+# Lens PERF — Performance & memory
+
+## Objective
+
+Say what is measured, and whether a regression would be seen. Where nothing is measured, say the
+absence: a number invented to fill this lens becomes a baseline the next campaign compares against,
+and a delta measured from a figure nobody produced is worse than no figure at all.
+
+## Questions
+
+- **What has a recorded duration or size today, and where is it recorded?** A figure in a commit
+  message is not a baseline; a file another campaign reads is one.
+- **Would a regression be seen?** By what — a threshold something enforces, or a person who happens
+  to notice the wait? The second is not detection.
+- **What does a contributor wait for**, and what does a consumer wait for? They are rarely the same
+  thing, and only one of them is usually measured.
+- **What grows without a bound** — a cache with no eviction, a log nothing rotates, a structure that
+  accumulates for the life of the process, an input read whole into memory?
+- Is a **budget pinned** anywhere — a size limit, a timeout, a threshold a guard reads — or is every
+  number descriptive?
+- Where the repository is **already slow on purpose**, is the reason written? A deliberate cost
+  nobody recorded is indistinguishable from a regression.
+
+## Probes
+
+- **What a contributor waits for** — the timings `verify` took before the lenses, under `PERF` in
+  its block: each script's median and runs, with its command. A timing it *could not tell* is a line
+  of `Limits`, with its reason.
+- **What the repository carries, by weight** — the largest tracked files and the whole tree's size,
+  from the count, the total and the largest the cut reports in `verify`'s block.
+- **Whether any threshold is enforced anywhere, as opposed to observed** —
+  `(timeout|budget|max[-_]?(size|bytes|time)|--max|ulimit)` across the tree. A budget is a number
+  compared against something; a number only printed is a measurement.
+- **Is there a baseline file at all** — something a later campaign re-reads: the tracked paths
+  matching `baseline|benchmark|perf`, or the line saying nothing in the tree is named as one.
+
+A probe whose subject comes back empty is *not applicable* under `Limits`, never a zero: a
+repository with no runtime code has nothing for this lens, and saying so is a measurement.
+
+## For a change
+
+A change adds no work to a path something already waits on, and removes no number a regression
+would be seen against. Timing the change against its target branch is no objective: two runs on
+one machine, minutes apart, differ by more than most of what it would call a regression.
+
+## Signals learned
+
+- **This lens ships without campaign history.** It was written when the eleven implemented lenses had
+  already run three campaigns and it had run none, so the section below carries what the corpus
+  argues rather than what a report measured. Grow it from the first campaign that runs PERF.
+- **The absence is the finding.** *Nothing is measured, so no regression can be seen* is a real
+  result with a real consequence, and it is written as a finding rather than left to *Limits* when
+  something depends on the speed — a hook a contributor runs at every commit, a build a consumer
+  waits for. Where nothing depends on it, it is an observation.
+- **A slow command is not a finding on its own.** What makes it one is a dependency: the command
+  runs in a hook, or in a path a person is blocked on. A command nobody waits for being slow is a
+  fact, not a defect.
+- **Measure the tier, not the suite.** The thing a contributor actually waits for is whatever the
+  contract's verification tiers run, and those are named in the contract rather than guessed.
+- Do not report a number without the command beside it. A duration is the most re-measured figure
+  an audit produces and the easiest to produce differently.

package/scripts/lenses/PKG.md

@@ -0,0 +1,58 @@
+# Lens PKG — Packaging & tarball
+
+## Objective
+
+Say whether what a consumer installs is correct: the entry points the manifest declares resolve to
+files the tarball actually contains, the tarball carries nothing private, and nothing executes on
+the consumer's machine at install time without a reason. This lens is the only one that looks at
+the artefact rather than at the repository, and they differ more often than anyone expects.
+
+## Questions
+
+Whether every entry point is in the tree and in the tarball, whether a lifecycle script runs at
+install time, and whether a tracked file carries a secret, is the script's to say; a
+lifecycle script is read here for its reason — *it builds the package* is a reason that says the
+build should have shipped instead.
+
+- **What is in the tarball** that should not be? Something private in it is the finding that costs
+  the most.
+- **Are the export conditions complete** — a default present, no condition reachable only by
+  accident? (The position of `types` is TYPE's.)
+- **Are the dependency classes right?** A runtime dependency in `devDependencies` breaks the
+  consumer's install; a peer expressed as a dependency gives them two copies of it.
+- **Does the committed build match its source**, where the build is versioned? BUILD's script
+  reports a tracked file a fresh build changes; a tag whose artefact is behind its source ships old
+  code from a repository whose history says otherwise.
+
+## Probes
+
+`PKG.mjs`, run by `verify` before the lenses, whose lines you are handed. Against
+`npm pack --dry-run --ignore-scripts`, it reports each entry point — `main`, `module`, `types`,
+`typings`, `browser`, `bin`, every `exports` leaf — absent from the tree or left out of the
+tarball; each `preinstall`, `install`, `postinstall` or `prepare` script; each tracked file named
+like a secret; and each line of a tracked file — fixtures and tests included, the history not —
+holding a credential's shape: a private-key header, a GitLab, GitHub or npm token. It prints such
+a value's first four characters and nothing more. With no `package.json` it could not tell.
+
+## For a change
+
+A change alters what a consumer receives only where the plan says so — an added or removed
+`exports` condition, a moved entry point, a dependency that changed class, a lifecycle script that
+appeared. No path it deletes or renames is one the manifest's `files` or entry points still reach:
+a file leaving the tarball is a break no test catches, because every test runs against the
+repository and not against the artefact, so the pack dry run checks it.
+
+A change that touches neither the manifest nor a packaged path has no objective here.
+
+## Signals learned
+
+- **This lens ships without campaign history**, the plugin's own repository being `kind: none` and
+  publishing no package. Grow it from the first library campaign.
+- **Resolution in the repository is not resolution in the tarball.** The two checks are different
+  and the second is the one that matters; a probe that only stats the path answers the wrong
+  question.
+- **A `prepare` script that builds is a finding, not a convenience.** It moves the build onto the
+  consumer's machine, where the toolchain may be absent and the result is unverified — the reason
+  a versioned build exists at all.
+- Do not report a missing `exports` map as a defect on its own. Report what a consumer cannot reach
+  because of it, or say it is deliberate.

package/scripts/lenses/SEC.md

@@ -0,0 +1,49 @@
+# Lens SEC — Security
+
+## Objective
+
+Say what comes from outside, what it reaches, and what defends it. A security defect is a path
+from an input someone else controls to something they should not touch, with nothing in between;
+the lens traces that path rather than listing vulnerability names.
+
+## Questions
+
+- **What are the entries?** A request, an argument, an environment variable, a file the code
+  imports or parses, a message, a URL a user supplies — anything whose content the repository does
+  not write.
+- **What does each entry reach?** A shell, a query, a path on disk, an HTML sink, a deserialiser,
+  a redirect, an `eval` — followed through the code, not guessed from a name.
+- **What defends it on the way?** Validation, escaping, an allow-list, a parameterised call, a
+  permission check — and does the defence sit on every path, or only the one its author tested?
+- **Where do secrets go?** Read from where, logged where, sent where, kept in memory how long. A
+  secret printed into a log or an error message is a leak whatever file it is in.
+- **What does the repository trust that it should not?** A file it downloads and runs, a lockfile
+  it does not check, a hook a contributor's machine executes.
+
+A secret's *shape* in a tracked file is a fact PKG's script already reports, and an advisory on a
+dependency is DEPS's: this lens asks what the code does with what comes from outside. A finding
+here carries `Affects: consumers` when what ships is exposed, and `critical` when it is exploitable.
+
+## Probes
+
+- **Sinks worth tracing back to an entry**, in the languages the tree carries —
+  `\beval\(|new Function\(|child_process|exec(Sync)?\(|spawn\(|innerHTML|dangerouslySetInnerHTML|\bsh -c\b`.
+- **Shell scripts that run what they download**, or expand an input unquoted into a command —
+  `curl[^|]*\| *(ba)?sh|wget[^|]*\| *(ba)?sh`.
+- **Secrets read from the environment, and the lines that print or send them** —
+  `process\.env\.[A-Z_]*(TOKEN|SECRET|KEY|PASS)|\$\{?[A-Z_]*(TOKEN|SECRET|KEY|PASS)`.
+
+The probes list sinks and secrets; the method is the trace from each back to an entry, or the
+statement that none reaches it. Name in *Method* which sinks were traced.
+
+## For a change
+
+An entry, a sink, or a path between them that a change adds — a new argument reaching a shell, a
+parsed file reaching the disk, a value reaching HTML — has a defence the objective names. The
+change removes and narrows no defence — no validation deleted, no escape bypassed, no check moved
+after the use — even above a sink it leaves untouched, and prints, logs or sends no secret.
+
+## Signals learned
+
+- **This lens ships without campaign history.** Its first campaigns will write this
+  section.

package/scripts/lenses/STANDARDS.md

@@ -0,0 +1,62 @@
+# Lens STANDARDS — Standards
+
+## Objective
+
+Say whether the code breaks a rule an authority document states, and whether new code has one
+possible shape. A rule written down and not followed is worse than no rule: the next contributor
+reads it, trusts it, and meets code that contradicts it.
+
+## Questions
+
+- **Which rules do the authority documents state about code?** The `CLAUDE.md`, or whatever file an
+  agent reads first, the principles, the glossary — *every HTTP call goes through `src/lib/http.ts`*,
+  *a skill never assumes a path*, *a term means one thing*. Only those: a working instruction — how
+  to name a branch, how to title a commit, which tone to answer in — guides an agent writing code and
+  is not a standard the code can break.
+- **Does the code break one?** A candidate cites the rule, its file and line, and the code that
+  breaks it — never a rule paraphrased, never a preference no document states.
+- **Take the newest file and the oldest of a kind. Are they the same shape?** Same error handling,
+  same naming, same layout, same way of reporting a result.
+- Where two shapes coexist, is the **boundary written** — a date, a directory, a note saying *the
+  old form stays until X*? A migration nobody declared is indistinguishable from an inconsistency.
+- Could a contributor **derive the shape from the code**, or would they need a person to tell them?
+  Is a shape **enforced by anything** — a template, a test, a lint rule — or only by whoever reviews?
+
+Whether the authority document is itself true is DOC's question; whether the code does what the
+specification asks is INTENT's. This lens reads the documents only for the rules they impose on
+code.
+
+## Probes
+
+- **The authority documents, and the rules they state about code** — which of `CLAUDE.md`,
+  `AGENTS.md`, `docs/spec/principles.md` and `docs/spec/glossary.md` the tracked files hold, and in
+  the first two `^\s*[-*0-9.]+ .*\b(never|always|must|only|every)\b`.
+- **One kind of artefact, every instance, the same structural markers** — the kind this repository
+  ships most, as a glob over the tracked files, and the markers its instances are supposed to
+  share, both read from the tree and named in *Method*: the markers counted in each instance. No
+  instance → this probe has no subject, said under `Limits`.
+- **Two instances side by side** — the one carrying the fewest markers beside one carrying them all:
+  what the first lacks is the drift.
+
+## For a change
+
+A change breaks no rule an authority document states about code — the objective cites the rule —
+and adds no second shape for something the repository already has a shape for: every file it adds
+reads like its sibling. The commits, the branch and the description are working instructions, not
+code, and no objective of this lens bears on them.
+
+## Signals learned
+
+- **Uniformity is a finding too, and a good one.** Measured on codelife itself, whose two kinds
+  filled the shape probe as `kind='*.test.mjs'` with
+  `^import assert from 'node:assert/strict'|from 'node:test'|from './lib.mjs'`,
+  and `kind='*/SKILL.md'` with `^## `: every suite carried the same three markers. Report it;
+  a lens that only ever speaks when something is wrong teaches a reader nothing about what is
+  right.
+- The strongest signal is **age against shape**: two files written a week apart that look different
+  say more than twenty files that look alike.
+- A shape enforced by a **test** rather than by review is the difference between a convention and a
+  rule. codelife asserts its skills' anatomy in a suite of its own; that is why the answer there
+  was short.
+- Do not report naming preferences. This lens is about a rule someone wrote and a contributor's
+  ability to *derive* the next file, not about which name you would have chosen.

package/scripts/lenses/TYPE.md

@@ -0,0 +1,56 @@
+# Lens TYPE — Public surface & types
+
+## Objective
+
+Say whether the declarations a consumer receives describe the surface the documentation promises,
+and whether they resolve under every module resolution a consumer may have configured. A package
+whose types resolve under one setting and vanish under another is untyped for half its users, and
+nothing in the repository notices.
+
+## Questions
+
+Whether a types entry exists, whether its condition comes first wherever it is declared, and
+whether a declaration entry imports a package the consumer does not receive, is the script's to say.
+
+- **What does the package export, according to the emitted declarations?** Enumerate it — names,
+  and for each whether it is a value, a type, or both — reading the declaration files the manifest
+  names, never a path literal.
+- **Does that set match the documented surface**, in both directions? A name in the declarations
+  and in no document is surface nobody was told about and everybody may now depend on; a name in a
+  document and not in the declarations is a promise the package does not keep. The two differences
+  are two findings with different severities: undocumented surface is a `low` that grows, and
+  documented surface that does not exist is a `high` the first consumer meets.
+- **Is any exported type effectively opaque** — an `any`, an unexported alias that leaks, a
+  parameter typed only by inference from a private shape? Read in context, never counted.
+- **Are the declarations emitted or written by hand?** Hand-written ones drift from the
+  implementation silently, and the drift is found by a consumer.
+
+## Probes
+
+`TYPE.mjs`, run by `verify` before the lenses, whose lines you are handed. It reports
+a package with no types entry, each `exports` object whose `types` condition is not first, and each
+package a declaration entry imports that is in neither `dependencies` nor `peerDependencies`. With
+no `package.json` it could not tell.
+
+## For a change
+
+A change to the public surface changes the documentation with it. The declarations are the
+subject, not the implementation: a refactor that changes no exported name has no objective here
+however large it is, and a one-line signature change has one. An exported name removed or renamed
+in the files the manifest's `types` and `exports` reach carries a `breaking` marker — the break
+this lens exists to catch.
+
+## Signals learned
+
+- **This lens ships without campaign history**, the plugin's own repository publishing no
+  declarations. Grow it from the first library campaign.
+- **The position of the types condition is the defect, not its absence.** A types condition listed
+  after a runtime one is skipped by whichever resolver reads conditions in order, so the package is
+  typed for some consumers and not others — and every check that runs inside the repository passes.
+- **Compare against the documentation, not against the implementation.** The implementation and the
+  declarations agree by construction when the declarations are emitted; what nothing checks is
+  whether either matches what a reader was told.
+- **An emitted declaration file with commits of its own is a contradiction worth reporting**: either
+  it is not emitted, or someone has been editing generated output.
+- Do not report an internal type as missing from the surface. This lens asks whether the surface is
+  described, never whether it is large enough.