@ersbeth/codelife 0.0.0-stage → 0.11.1

package/scripts/lenses/VERIF.md

@@ -0,0 +1,81 @@
+# Lens VERIF — Verification
+
+## Objective
+
+Say whether a verification would fail if a behaviour broke, and what the repository ships that
+nothing would notice disappearing. A suite that always passes is worse than no suite: it buys
+confidence without selling anything — and what an agent can break with nothing going red is the
+same question asked of every shipped file.
+
+## Questions
+
+- **Can each suite fail?** Would a test go red if what it asserts broke, or does its mock answer
+  whatever is asserted? A suite whose tests would pass against a broken subject asserts nothing.
+- **What can be removed or corrupted with nothing going red?** A shipped file no suite names — a
+  reference, a template, a configuration the tooling reads — is what an agent can silently
+  destroy.
+- What has **no test at all**? Name the modules, not a percentage: coverage figures hide which
+  half is covered.
+- Are **fixed bugs pinned**? A defect fixed without a test that goes red for it will come back, and
+  nothing will say so.
+- Does a behaviour reach **every place that should adopt it**? A new rule applied in one of the
+  three call sites that need it is a regression waiting for the other two.
+- Do the tests assert **behaviour or implementation**? A test that mirrors the code line by line
+  fails on every refactor and catches nothing.
+- Are there **skipped, `.only`, flaky or commented-out** tests?
+- Is `test:one` usable on a single file, and does `test:all` run everything the repository has — or
+  only what the default configuration happened to match?
+
+A test is code every lens reads: a `catch` that swallows inside a test is FAIL's, a wrong
+assertion BUG's. VERIF asks whether the verification would *see* a break, not whether the test
+code is correct.
+
+## Probes
+
+- **The suites and what they match** — the `scripts` of `package.json`, and the baseline's output
+  you were handed: the suite as it ran, what it ran and what it reported. Not handed → a line of
+  `Limits`, the suite unread rather than run.
+- **Tests that are not run** — `\.skip|\.only|xit\(|xdescribe\(` in the tracked `*.test.*` and
+  `*.spec.*` files.
+- **What has no neighbour test**, where the repository keeps its tests in a mirror of its sources —
+  both directories read from the tracked files and named in *Method*, the sources whose name has no
+  counterpart among the suites' once `.test` or `.spec` is set aside. No mirror → the neighbour-test
+  question is not applicable, said under `Limits`.
+
+**Two suspicions are candidates, never probes**: a lens runs nothing, and the lenses beside it read
+the same tree.
+
+- **An assertion that would stay green inverted** — a mock that answers whatever is asserted, a
+  matcher that accepts anything. The candidate names the assertion's `file:line` and why the suite
+  would stay green with it inverted.
+- **A shipped file nothing tests** — a tracked file whose basename no suite carries. The candidate
+  names the file and why the suite would stay green without it.
+
+A suspicion you cannot say why of is not one to return.
+
+## For a change
+
+A behaviour a change adds has a test that fails without it, and no test it changes is weakened — no
+widened matcher, no removed assertion, no skip, no snapshot regenerated without its reason in the
+commit's message. A place outside the files it touches that owes the behaviour too — a sibling of
+the touched function, a second caller — adopts it, or the plan says why not.
+
+## Signals learned
+
+- **Reviews most often find defects in the tests themselves.** The Kappa project's kept review
+  findings were about the tests more than about the code they test — an assertion that cannot fail,
+  a fixture that hides the case, a test that passes for the wrong reason. Read a test as hard as
+  the code it guards.
+- **A shipped file nothing tests is the sharpest question here.** Measured on codelife: 39
+  `references/` files shipped, no assertion touched any of them, and removing a lens reference left
+  the suite green — after which `/audit` reported that lens as *not implemented* and carried on.
+  An agent could delete a measuring instrument and nothing objected.
+- **Coverage is uneven in a way the counts hide.** The same repository asserted every skill's
+  frontmatter and anatomy, so `SKILL.md` was well guarded, while the `references/` and `templates/`
+  beside it were guarded by nothing. Report the *shape* of the gap, not a percentage.
+- A repository whose `test:all` is `echo 'nothing to run'` has a *not ported* state, not an empty
+  suite — say which, they are different findings.
+- A suite that only runs on the developer's machine, never in a hook, is a GUARD finding as much as
+  a VERIF one: file it once, on the lens whose reference explains it best.
+- Snapshot suites drift silently, and when a snapshot was last regenerated against the code it
+  covers is per-file history no lens is handed: a snapshot suite is a line of *Limits*, not a date.

package/scripts/link.mjs

@@ -0,0 +1,40 @@
+// The link a repository's install makes: `.claude/skills/codelife`, to the package in its
+// `node_modules/` (R-272) — a symbolic link, a junction on Windows, which needs no administrator
+// right. Imported by `install.mjs` and `init.mjs`. Git is told to ignore it through the clone's
+// `.git/info/exclude`, so no tracked file changes.
+import './node-floor.mjs'
+import { existsSync, lstatSync, mkdirSync, readFileSync, appendFileSync, readlinkSync, rmSync, symlinkSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+export const LINK = '.claude/skills/codelife'
+
+// Links <repo>'s LINK to its installed package; says so, and fails nothing, when there is none;
+// returns whether it made the link.
+export function link(repo) {
+  const pkg = join(repo, 'node_modules/@ersbeth/codelife')
+  const at = join(repo, LINK)
+  if (!existsSync(pkg)) return console.log(`codelife: no ${pkg}, so no ${LINK} link — install the package first`)
+  const target = process.platform === 'win32' ? resolve(pkg) : '../../node_modules/@ersbeth/codelife'
+  let st = null
+  try { st = lstatSync(at) } catch { /* absent */ }
+  if (st && !st.isSymbolicLink()) {
+    console.error(`codelife: ${at} exists and is not a link, left untouched — move it aside and install again`)
+    process.exit(1)
+  }
+  if (st && resolve(dirname(at), readlinkSync(at)) === resolve(dirname(at), target)) return false
+  if (st) rmSync(at, { force: true })
+  mkdirSync(dirname(at), { recursive: true })
+  symlinkSync(target, at, 'junction')   // the type is read on Windows only
+  exclude(repo)
+  return true
+}
+
+function exclude(repo) {
+  const g = (...a) => spawnSync('git', a, { cwd: repo, encoding: 'utf8' })
+  if (g('rev-parse', '--git-dir').status !== 0 || g('check-ignore', '-q', LINK).status === 0) return
+  const file = resolve(repo, g('rev-parse', '--git-path', 'info/exclude').stdout.trim())
+  mkdirSync(dirname(file), { recursive: true })
+  const had = existsSync(file) ? readFileSync(file, 'utf8') : ''
+  appendFileSync(file, `${had && !had.endsWith('\n') ? '\n' : ''}/${LINK}\n`)
+}

package/scripts/methods/cause.md

@@ -0,0 +1,21 @@
+codelife help method cause — locate a defect's cause before a fix is planned
+
+1. **See it happen first.** Run what the report says shows the symptom, with the cheapest
+   instrument that can answer — a command, a test run, a log — never a browser unless nothing else
+   can. Not observed, or the attempt fails → stop: `not located`, quoting what you ran and what it
+   printed. A failed attempt says the attempt failed, not that the problem is absent. A report
+   that could mean two behaviours: ask which, or, when nobody can answer, take the likelier and
+   say so.
+2. **State one hypothesis that can be false**: a mechanism an observation can come out against —
+   *the cache is not invalidated when the key changes, so the second call returns the first's
+   value*, not *the value is stale*. A report naming a `file:line` gives the first hypothesis.
+3. **Say, before observing, what result would refute it**, then observe: a throwaway probe in a
+   scratch directory, never in the repository. A probe inside a source file copies the file aside
+   first and restores from that copy with a `trap` armed before the edit — never from the index or
+   `HEAD`.
+4. **Refuted** → note it with what refuted it, never try it again, back to 2. **Survived** → refine
+   it until a fix can be planned against it. The third refuted hypothesis is the cap: stop there,
+   `not located`.
+5. **Report** the cause, or `not located` with every hypothesis ruled out and what ruled it out —
+   never a guess promoted to a cause because the run was long. A probe is not a proof: throw it
+   away; the regression case is written later, by the red-green method.

package/scripts/methods/comments.md

@@ -0,0 +1,157 @@
+codelife help method comments — the records the plugin posts on an issue, each opening on its line
+
+Plugin-owned, never parameterised by a contract. Each opens with **one recognisable line**:
+
+```markdown
+codelife: <kind> — <skill> — <date>
+```
+
+That line is the whole mechanism: it is how `/overview` finds an approved plan months later, how
+`/work` knows a plan has no closing comment yet, and how a human scanning an issue sees at a
+glance which comments came from a skill and which from a person. A review's pass on a merge request
+reads `codelife: review — pass <k> — <sha>` instead, its number and head standing for the skill and
+the date. `codelife issue view <n>` reads an issue's records back, oldest first.
+
+## `plan` — written by `/work`, before implementation starts
+
+```markdown
+codelife: plan — /work — <date>
+
+<the planner's report whole: `## What is wrong`, `## The cause` for a located `bug`,
+`## The approach`, `## The cases` when the issue cites some, `## What proves it`, `## Objectives`,
+`## Files`, `## Verification`, `## Commits`, `## Out of scope`, `## Difficulty`>
+
+## Go-ahead
+<who gave this run its go-ahead, as its brief or its driver's brief stated it: you, typing the
+command or answering the brief; your confirmed table in the driver it names; delegated, the command
+you typed and each constraint the table carried for this issue, quoted; or relayed, the session that
+relayed it and your words it quoted>
+```
+
+`## Go-ahead` is in every plan, and informs: it delegates nothing, and a relayed go-ahead is not a
+delegation. `/mr`'s lead is read from it.
+
+The **resumption artefact**: a `plan` comment with no `closing` comment after it means the work
+was started and not finished. It is posted **before** the code is written, so an interrupted
+session leaves its thinking behind rather than its diff.
+
+## `closing` — written by `/work`, at the end
+
+```markdown
+codelife: closing — /work — <date>
+
+Fixed in `<hash>` — <the commit's subject>.
+Proved by: <the proof the plan named, `<path>` for a test> — <what it proves>.
+Verified: <the tier that ran, the guards the diff triggered, and each objective of the plan with its answer, or left to the review>.
+<anything a number moved, with the baseline it was compared to>
+```
+
+An issue already satisfied by an earlier commit, `#<earlier>` the issue its `Closes:` or `Refs:` footer names, opens its second line on `Already fixed
+in <hash> (#<earlier>) — <that commit's subject>.` instead, the rest unchanged.
+
+The issue is closed **by hand** with this comment; the `Closes:` footer its commit carries is a
+cross-reference, never what closes: the closing is a statement about what was verified, not a
+side effect of a branch landing.
+
+**The STATUS** opens on the same first line and is what a delegated run posts when it stops: why
+it stopped, what was tried, what remains. The issue stays open above it.
+
+## `lot-closing` — written by `/work`, or `codelife lot leave`, on a lot's umbrella with its last open member
+
+```markdown
+codelife: lot-closing — </work, or codelife lot leave> — <date>
+
+Branch: `<the branch it ran on>`.
+Members closed: <#n, #n, … — each row of the umbrella, read from its issue>.
+Merge request: not yet opened — `/work <umbrella>` opens it from the branch once every member's commit is there.
+```
+
+The umbrella's own form: a member's `closing` fields — the hash, the proof, the tier — describe one
+issue's fix, and each member carries its own. The umbrella closes with its last member, before
+the merge; this says where the lot's work is and that the merge request is still to come. A leave
+that takes the last open member writes the same comment without the `Branch:` and `Merge request:`
+lines, since it runs on whatever branch and promises no merge request; when no row is left the
+umbrella closes `wontfix`, its members closed `none`.
+
+## `finding` — written by `codelife audit file`, right after `create`
+
+```markdown
+codelife: finding — /audit — <date>
+
+<the finding as its file in the campaign folder carries it — the lead, What happens, Why it matters, Evidence
+with the reproduction and its output, What to do with its `tried` / `untried` marker — without its
+`Disposition` line, which would name the issue this comment sits on>
+```
+
+The one copy of a finding that outlives the campaign: the report folder is deleted at the close,
+so the comment is where `/work` reads the evidence and where a finding found wrong later is
+corrected. The issue's body is the finding's lead and a *Where it comes from* naming the campaign
+and the finding id, with no file anchor. On a repository not known to be private, an exploitable
+reproduction is left out by the judge that wrote the finding, which says *withheld*.
+
+## `re-reported` — written by `codelife audit file`, on a still-open issue
+
+```markdown
+codelife: re-reported — /audit — <date>
+
+Campaign A<n> observed this again, as finding <id>: <the finding's lead>.
+```
+
+What makes a recurring campaign compound instead of repeat: an issue is not filed twice, it is
+annotated.
+
+## `duplicate` — written by `/new-issue`, on the open issue that already carries a subject
+
+```markdown
+codelife: duplicate — /new-issue — <date>
+
+Seen again from <the origin: this merge request, this issue, or "a subject typed from nowhere">: <what this run adds to the issue, or "nothing it lacks">.
+```
+
+A run that is not a campaign has no `re-reported`'s "Campaign A<n>"; this says whose sighting it is.
+
+## `rewritten` — written by `/roadmap`, on an open issue a rule change made stale
+
+```markdown
+codelife: rewritten — /roadmap — <date>
+
+Rewritten to <R-n — heading> as it stands at <commit>, the commit `/roadmap` read.
+<for a started issue: what its commits <hashes> already do>
+```
+
+The body above is the confirmed one; this says why it changed, for whoever works the issue next.
+
+## `refused` — written by `/work`, on the issue whose held choice the user refused
+
+```markdown
+codelife: refused — /work — <date>
+
+The held choice of `<hash>` — `Held: <its trailer>` — is refused: <the user's reason, quoted>.
+Later commits on its files: <the hashes its `held:` line names, or "none">.
+```
+
+Posted by `codelife issue reopen`. The decision the member's new plan starts from: `/work` redoes
+the work with this answer and closes the issue again. The later commits are named because they may have built on the refused choice.
+
+## `debt-link` — written by `/new-issue`
+
+```markdown
+codelife: debt-link — /new-issue — <date>
+
+Filed as #<n> — <its title, tag included>.
+Noticed while <the origin: this merge request, this issue>.
+```
+
+Posted on the **origin** — the issue or merge request the session was on, or the umbrella of a
+member of an open lot, where `/work`'s table offers the join — so the trail from "noticed here" to
+"filed there" survives the session. When `/new-issue` finds the subject already
+carried, the first line is the same and the second reads `Already carried by #<n> —
+<title>; noted there.`, so the trail ends at the issue that has it.
+
+## Never
+
+- Write a comment without its first line, or change the line's shape: it is a lookup key.
+- Post a `plan` after the implementation — it is the artefact that survives an interruption, and
+  posted late it is only a summary.
+- Use these templates for a conversation with a person: they are records, and a discussion belongs
+  in a plain comment.

package/scripts/methods/description.md

@@ -0,0 +1,67 @@
+codelife help method description — a merge request's description, which `codelife mr open` checks
+
+Copy from the begin marker to the end marker, fill it from the dry run of `codelife mr open` and
+your sources, and give the file to the verb: it refuses a region or a heading missing or out of
+order. A first line `# <title>` above the region titles a new merge request.
+
+<!-- codelife:begin -->
+<!-- For a reviewer who knows the language and the forge, not this repository: a term the project
+     coined is explained where it first appears and linked by the `links:` URL, never by a path.
+     Every section present, as long as a reviewer without context needs, and no longer. -->
+
+<!-- The lead, no heading: one or two sentences that stand alone. When a linked issue's plan says
+     under `## Go-ahead` that the work was delegated or relayed, the lead says it ran without you
+     present, and how. -->
+
+*Not reviewed by codelife* — <each `hand commit:` line, its hash and subject>
+
+<!-- Absent when `hand commits: 0`. On a merge request /work opened, its review's account stays and
+     this line names the hand commits alone. -->
+
+## Why
+
+<!-- The situation before this branch and what was wrong with it, with a concrete example, from the
+     linked issues. On a lot's branch, the umbrella's common cause, then one sentence per member. -->
+
+## What changes
+
+<!-- What the branch does, grouped by subject and never by commit, with the choices made and the
+     alternatives set aside — a held choice among them, as its commit body names it. On a lot's
+     branch, one paragraph per member, opening on its number. A unit /work reviewed says what its
+     review found and what was fixed. -->
+
+## Reading the diff
+
+<!-- Where to start, what can be skimmed, what deserves attention; on a small branch one sentence,
+     "one file, line 42"; on a lot's branch one reading order, naming the files several members
+     touch. A change repeated across files is one entry: the change, the count, one example. What
+     was not read line by line is listed by directory, with its files and changed lines. -->
+
+## How to test
+
+<!-- One line per runnable thing, in this order: each regression test the diff adds, the push tier,
+     each manual step a plan names as its proof. /review-mr runs them as written. Reading one file
+     against another is no test: it goes under Reading the diff. A red proof is cited where the
+     issue's closing comment records it. A manual step: one action per numbered line, then a last
+     Expected line. `{{run}}` is the `run:` line. -->
+
+- `{{run}} test:one <path>` — green; proved red before the fix, see #<n>'s closing comment
+- `{{run}} verify:push`
+- *manual* — <title>
+  1. <one action>
+  2. **Expected:** <the outcome>
+
+## Linked issues
+
+<!-- The `linked:` lines, as printed. -->
+
+- Closes #<n> — <title>
+
+## Debt noticed
+
+<!-- What the work found and did not fix, each already filed: anything unfiled is /new-issue. Each
+     number is kept only if its `debt:` line names the issue its line describes. "None" is an
+     answer. -->
+
+- #<n> — <one line>
+<!-- codelife:end -->

package/scripts/methods/message.md

@@ -0,0 +1,24 @@
+codelife help method message — a commit message, whose first line the `commit-msg` hook checks
+
+`<type>(<scope>)<!>: <subject>` — imperative, 72 characters at most. The type is chosen, never
+guessed: `feat`, `fix` and `perf` reach the changelog; `refactor`, `test`, `docs`, `chore`, `ci`,
+`build` and `style` do not, unless `!` marks a break, which reaches it whatever the type. The scope is the repository's own word:
+
+```bash
+git log -200 --format=%s | sed -nE 's/^[a-z]+\(([^)]+)\).*/\1/p' | sort | uniq -c | sort -rn
+```
+
+With none, the package name in a workspace; otherwise no scope.
+
+The body says **why**: what was wrong, what constraint decided the approach — never what the diff
+already shows.
+
+The footer is the **last paragraph**, the session's `Co-Authored-By:` lines in it: git reads
+trailers from that paragraph alone. It links, and never closes: `Refs: #<n>` for an issue that
+stays open, `Closes: #<n>` for one closed by hand anyway; the finding id (`A3-PKG-1`) when there is
+one; `Answers: pass <k>: <n>, …` on a commit answering a review's pass.
+
+**In a delegated run** the body also names each choice the commit took alone — what, why, and what
+it costs if wrong. A choice held for the user's validation is a commit of its own, saying the same,
+ending on `Held: <what the user has to validate>`; the redo of one refused ends on one
+`Replaces: <its hash>` line per hash.

package/scripts/methods/red-green.md

@@ -0,0 +1,28 @@
+codelife help method red-green — prove a behaviour's fix: a test red for its stated reason, then green
+
+0. **Prove the runner can fail.** Run `test:one` on the file you will write into. A script that
+   returns 0 on a file it cannot have run, or prints *nothing to run*, verifies nothing: stop and
+   say the runner cannot go red. No such script → the repository is not ported: stop.
+1. **Write the case** where the suite keeps its subject, named like its neighbours. Its title opens
+   on the specification's identifier it proves (`C-<n> …`), else cites the issue (`(#<n>)`).
+2. **Run it red**, narrowed to the new case. Read the failure: it must be the reason the plan
+   states — for a feature, *not implemented*: the symbol undefined, the old behaviour observed.
+   Another reason → **broken, not red**: quote it and stop. Green on the red run → nothing
+   to fix, or the case misses the defect: say which, and stop.
+3. **Fix**: the smallest change that makes it pass, inside the plan's files.
+4. **Run green**: `test:one` on the whole file, then `test:all`; report the runner's counts.
+   `test:all` red → the fix is not green, whatever `test:one` said.
+5. **Refactor** only with green, only inside the plan's files, then `test:all` again; red after a
+   refactor is reverted, not chased.
+
+Every test run — step 0's, the red, the green, the run after a refactor — has its whole output
+written to a file, never into the conversation: a pass prints the runner's count line, a failure
+the exit status and the last 40 lines of that file.
+
+A repair that leaves the red red, or a verification re-run that stays red, counts as an attempt:
+three, and stop, no fourth tried. A run that could not measure — the runner does not start, the
+failure is environmental — spends none and stops at once. Quote failures, never summarise them; never change an
+assertion or a snapshot to match what was observed. Prose or structure has no red: it is proved by the guard that
+would have caught it, named — or, prose an agent follows at run time, by a run played by hand in
+the merge request's *How to test*. Never a grep on the sentence just written, nor a guard
+over a file nothing will edit again.

package/scripts/methods/refusal.md

@@ -0,0 +1,22 @@
+codelife help method refusal — one line of `## Rejected`, what a decision not to do something leaves
+
+A refusal is a decision whose rejected option is doing the thing, so it leaves one line of the
+specification's memory of refusals — what `codelife search` finds when the idea comes back — and no
+note:
+
+```markdown
+- <address> — <what is not done> — <why, and what doing it would have cost> — <YYYY-MM-DD>
+```
+
+- **Where** — the `## Rejected` of the capability whose rule the refused change would have touched,
+  found by `codelife search`; that of `principles.md` when it concerns none.
+- **The address** — `R-<n>` or `K-<n>`, or `§ <heading>` for a heading of that file with no
+  identifier.
+- **The reason** — the evidence that carried it, verbatim, and the cost of doing it. *Not now* is
+  no refusal: it is an issue left open.
+- **The date** — `date +%F`, never from memory.
+
+Append the line to the section as it stands and edit nothing else; the pre-commit hook holds it.
+Every later reference to the refusal — a closing comment, a reply, a disposition — quotes the line
+and its file. A specification not in the form (`codelife form spec` says so) takes no line: the
+reason goes into the tracker's closing comment alone, and the result block says why.