@ersbeth/codelife 0.0.0-stage → 0.11.1

package/skills/onboard/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: onboard
+description: Create or update the documents a newcomer — human or agent — needs to arrive: README, CONTRIBUTING, CLAUDE.md, the per-package briefs, and a library's consumer SKILL.md — the code read first, every change proposed as its own passage.
+argument-hint: "[document…]"
+---
+
+# /onboard
+
+Creates or updates the **documentation set** a newcomer needs to arrive — `README.md` the map,
+`CONTRIBUTING.md` the human register, `CLAUDE.md` the agent brief, a package's own `CLAUDE.md`, and
+a library's consumer `SKILL.md` that ships in its tarball. It reads the code first and the documents
+second, lists every gap, and proposes each change as a **passage** you accept or refuse on its own.
+A whole document is written only when it is absent, or on request. One verb reads; this brief
+carries what is yours to decide and the writing.
+
+## Preconditions
+
+None to check here: `codelife onboard prep` prints a `- stop:` line for each — no contract or an
+invalid one, a document of the set with changes not committed. A stop ends the run: say it in your
+reply with what to do, and run nothing else. A `- known: not read` line does not stop: say it, and
+go on. Work on the branch checked out.
+
+## Brief
+
+**Who gave the go-ahead**, and from what, opens it: you, typing the command or answering this
+brief; your confirmed table in a driver, which answers what it named — ask only the rest; the word
+`delegate`; or a session that relayed your words, quoted here — relayed is not delegated. Typed or
+tabled, this brief is an announcement; otherwise the run **stops here** for your go-ahead, after
+nothing but a preparation that only reads.
+
+Then `codelife onboard prep`, and its block written **in your reply**, in the user's language — a
+tool's output is not one: the kind and the set it makes, each document, the facts, the open bugs
+and the pending notes; and that passages will be proposed, not rewrites.
+
+## Parameters
+
+`[document…]` — `readme`, `contributing`, `claude`, `skill`, or a package name, case-insensitive,
+file names accepted; **all** by default. A full rewrite of one document, on request only. Inferred
+from the conversation when a gap was noticed there — a passage `/setup` named in its *Next*, a false
+sentence a review read — and **stated**.
+
+## Steps
+
+1. **Read the code** — from prep's facts, the code the documents describe: the entry points, the
+   central mechanism, the layering, the build. Before any document: a document read first frames
+   what the code is looked at for.
+2. **Read the set; list the gaps** — each document against its template, `templates/<document>.md`
+   in this skill's directory, which gives its sections, its audience and what it never holds;
+   against the code and prep's facts; and against `- known:` and `- notes:`. A status paragraph is
+   read first, claim by claim. A gap is:
+   - a verifiable statement now false — a path, a script name, a version, a name that moved;
+   - a count — answered by removing it and naming the command that gives it;
+   - a section of the template missing;
+   - a verifiable fact copied — from the contract, a tool file, or another document of the set;
+   - a rule the contract now declares — `## Never`, `## Raise before doing`, a `guards[]` entry —
+     still written as prose or as a habit;
+   - a behaviour an open bug contradicts, or a pending note's subject, written as the design;
+   - a document absent, or a `SKILL.md` prep flags.
+3. **Propose** — every passage in one reply, numbered: the document, the gap in one line, the
+   current text and the proposed text. An absent document is its template filled from the code,
+   shown whole. You answer in one message: each **accepted**, **refused** — recorded, not argued —
+   or **later**, with what it waits for. Write the accepted ones and nothing around them.
+4. **Commit** — `codelife commit <message file> <path>…` on the files an accepted passage changed,
+   `docs: <what changed>`. Nothing accepted → no commit, said in one line.
+
+### What the documents hold
+
+- A **verifiable fact** — a command, a script's body, a version, a path, a tier — is **cited**
+  where it lives, never copied: *the verification tiers are in `.claude/codelife.md`*; *Node ≥ 22,
+  see `engines` in `package.json`*. The plugin's conventions — the skills, the scripts, the
+  branches, the labels, the changelog, the release — are cited as the plugin's. A **rule** may be
+  written in both `CONTRIBUTING.md` and `CLAUDE.md`: didactic in one, dense in the other.
+- Diagrams are mermaid.
+- A package's own `CLAUDE.md` is proposed only when a package has rules of its own — its own test
+  configuration or toolchain, a root rule naming it.
+- `SKILL.md` exists for `kind: lib` only, beside the version file: its frontmatter `name` is the
+  package name without its scope, and listing it in the package's `files` is the one configuration
+  line this skill proposes.
+
+## Never
+
+- Copy a verifiable fact the contract or a tool file states, or write a count.
+- Write a passage not accepted; reformat, reflow or reorder the text around one; or rewrite a
+  refused passage into another proposal in the same run.
+- Touch code, tests, configuration — `files` for `SKILL.md` aside — or a document outside the set.
+- Put tagged regions or generated markers into a document: a public `README.md` carries none.
+- Check out, switch, stash, add a worktree, or chain into another skill.
+- Answer in a language the user did not write in, or write anything but English into the
+  repository or the tracker.
+
+## Output
+
+The run ends on this block, under this exact heading, its fields in the user's language:
+
+```markdown
+### onboard result
+- Produced: the documents written or changed, and the commit.
+- Decided: each passage accepted, refused or later, in the user's terms.
+- Left open: each passage refused or later, with its document and its reason — what the next
+  audit's DOC lens reads.
+- Next: `/audit targeted DOC` when a document was written whole; otherwise nothing. Name it; start
+  none.
+```

package/skills/onboard/templates/CLAUDE.md

@@ -0,0 +1,31 @@
+# CLAUDE.md
+
+{{What the project is, in two dense sentences, for an agent that will edit it. Then: the
+verifiable facts about this repository — its kind, its tracker, the file that carries the
+version, the guards, the generated outputs — live in `.claude/codelife.md`, the codelife contract.
+This document stays prose, for an agent working on the repository: architecture, the rules the
+code cannot teach, and the reasons — never the commands and tiers, which are the contract's, nor
+the audit findings, which are the tracker's.}}
+
+## Architecture
+
+{{The layering, as a mermaid diagram when the layers are more than two, and the one sentence on
+which direction imports go. The central mechanism, named. Where the entry points are.}}
+
+## Rules not guessable from the code
+
+{{One rule per line, each with its reason: a peer version pinned for a reason the manifest does
+not state, an ordering the tests do not enforce, a file that is generated and must not be edited.
+A rule the contract's `## Never` or `## Raise before doing` already states is cited, not repeated.}}
+
+## Conventions
+
+{{What the plugin does not fix and this repository chose: naming, the test file next to its
+module, the scope vocabulary of commits read from the history. Everything the plugin fixes —
+branches, labels, tiers, the release — is the plugin's and is not written here.}}
+
+## Further reading
+
+{{`docs/spec/README.md`, the specification's entry point, where each decision is recorded;
+`docs/brainstorm/`, the topics not settled yet, each an unfinished note; the contributor guide — as
+links, with one line each on when to open them.}}

package/skills/onboard/templates/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to {{name}}
+
+{{Two sentences on what a contributor is joining: what the project is, and how it is worked on —
+with the codelife skills, one deliberate step at a time. This file is didactic, in full
+sentences, for a human contributor; `CLAUDE.md` says the same rules densely, and neither defers to
+the other. No verifiable fact the contract or `package.json` states is copied here.}}
+
+## Setup
+
+{{What a fresh clone needs, cited rather than copied: the runtime version is in `engines` of
+`package.json`; the package manager is the one `packageManager` names; the guards are wired as
+`.claude/codelife.md`'s `## Setup` says. Then the one thing a newcomer would not guess.}}
+
+## Layout
+
+{{The packages or directories, each with its role and the layer it belongs to, in the order a
+reader meets them. Where the tests live, and where the build writes.}}
+
+## The daily loop
+
+{{The skills in the order of a working day, each in one sentence of what it does for you: the
+overview, an issue worked, a commit, a merge request, its review, its feedback. The commands are the
+plugin's; this section says when you reach for each.}}
+
+## Verification and hooks
+
+{{Cite the contract: the verification tiers, the guards a diff triggers and the generated outputs
+are in `.claude/codelife.md`. Then the rule worth explaining — why a tier exists, what a guard
+protects — in a sentence or two. No script body here.}}
+
+## Releasing
+
+{{Who releases, from which branch, and that `/release` does it from the contract. The release
+lines the project maintains, and what a hotfix is for.}}

package/skills/onboard/templates/README.md

@@ -0,0 +1,30 @@
+# {{name}}
+
+{{What it is, in two sentences: the need it answers and the shape it takes — a library, an
+application, a tool. This file is the map, for anyone arriving: no command, no rule, no
+architecture.}}
+
+## Layout
+
+{{One line per package or top-level directory that a newcomer needs to place: what it holds and
+who it is for. A single-package repository says so in one line.}}
+
+## Where to go
+
+| You are | Read |
+|---|---|
+| using {{the library or the application}} | {{the consumer document — `SKILL.md` for a library, the user guide for an application}} |
+| contributing | [`CONTRIBUTING.md`](CONTRIBUTING.md) |
+| an agent working on this repository | [`CLAUDE.md`](CLAUDE.md) |
+| an agent writing code that uses it | {{`packages/<name>/SKILL.md`, or "nothing: an application has no consumer"}} |
+| reporting a vulnerability | {{the channel — a private issue, an address}} |
+
+## Project state
+
+{{The tracker, as a link. The audit campaigns, as a link to the table of `docs/audit/README.md`.
+The changelog, as a link. One paragraph of status if the project wants one — every claim in it
+verifiable, and read claim by claim at the next `/onboard`.}}
+
+## Licence
+
+{{The licence, and a link to the file.}}

package/skills/onboard/templates/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: {{the package name without its scope — lowercase letters, digits and hyphens}}
+description: {{"Use when writing, reviewing or debugging code that uses <package>": what it is, and the one rule that decides whether that code works.}}
+---
+
+# Using {{package}}
+
+{{The core usage rule, first and in bold: the one call, order or ownership rule that every
+correct use follows and every silent failure breaks. One paragraph, with a two-line example. This
+file is for an agent *using* the library: no internals, nothing a contributor needs.}}
+
+## The API's shape
+
+{{The handful of entry points, each in one line: what it takes, what it returns, when it is
+called. No internals. Link to the reference documentation rather than restating it.}}
+
+## The mistakes that silently break it
+
+{{One per line, each as *doing X looks fine and breaks Y because Z*: the reactivity lost, the
+listener leaked, the value read at the wrong time. This section is the reason the file exists.}}
+
+## Disposal and lifecycle
+
+{{What must be disposed, in which order, and what happens when it is not. What outlives what.}}

package/skills/onboard/templates/package-CLAUDE.md

@@ -0,0 +1,15 @@
+# {{package}} — CLAUDE.md
+
+{{The package's role in one sentence, and the layer it sits in, for an agent working inside it.
+This brief exists because the package has rules of its own; what the root `CLAUDE.md` already says
+is not repeated here.}}
+
+## Its own rules
+
+{{One per line, with its reason: the toolchain it differs on, the test configuration it carries,
+the dependency it may not take.}}
+
+## What it must not touch
+
+{{The packages or directories an edit here must leave alone, and why — the direction imports go,
+the output another package owns.}}

package/skills/overview/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: overview
+description: Read-only — where the repository stands, what is stale, and the single most useful skill to run next.
+---
+
+# /overview
+
+One screen, **read-only**, saying where the repository stands, then the one skill to run next. It
+asks nothing and writes nothing, which is its whole value: it can be run at any moment without
+consequence. Everything on the screen, *Next* included, is read and decided by `codelife overview`:
+*Next* is the first rule of a fixed table that holds, never a judgement.
+
+## Preconditions
+
+None to check: a repository without a contract, a machine not connected, a tracker that does not
+answer — each is a line of the screen, and *Next* says what to run.
+
+## Brief
+
+**Who gave the go-ahead**, and from what, opens it: you, typing the command or answering this
+brief; your confirmed table in a driver, which answers what it named — ask only the rest; the word
+`delegate`; or a session that relayed your words, quoted here — relayed is not delegated. Typed or
+tabled, this brief is an announcement; otherwise the run **stops here** for your go-ahead, after
+nothing but a preparation that only reads.
+
+Nothing else: the screen follows.
+
+## Parameters
+
+None, of any kind.
+
+## Steps
+
+1. **Read** — `codelife overview`, from the repository's root. It takes a few seconds per dozen
+   open issues; let it finish.
+2. **Show** — write its screen in your reply, in the user's language — a tool's output is not one:
+   every section, in its order, every line kept, *unreadable* and *none* lines included, and the
+   **Next** line with its reason. Translate the words, never the commands, numbers, branches or
+   quoted errors.
+3. **Close** — the result block below, in the same language.
+
+## Never
+
+- Write anything — no file, comment, label or issue — even to fix what the screen shows stale: it
+  says so, and the skill *Next* names fixes it.
+- Ask anything, or chain into the skill *Next* names.
+- Change *Next*, reorder the screen, drop an empty section, or read a source the verb did not.
+- Answer in a language the user did not write in, or write anything but English into the
+  repository or the tracker.
+
+## Output
+
+The run ends on this block, under this exact heading, its fields in the user's language:
+
+```markdown
+### overview result
+- Left open: the verb's **Left open** lines, one each, as it lists them — or nothing.
+- Next: the verb's **Next** line, its command and its reason.
+```

package/skills/port-toolchain/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: port-toolchain
+description: Bring a library's or an application's toolchain to the target, one commit per item — an item you defer is filed, and the close names each item left with the issue carrying its reason.
+argument-hint: "[item]"
+---
+
+# /port-toolchain
+
+Brings the toolchain of a library or an application to the plugin's target — pnpm and its
+workspace, Vitest, characterisation tests, Vite+, TypeScript, Oxlint and Oxfmt — one item at a
+time, on a repository `/setup` has set up. It keeps **no state file** — the verbs read what is done
+from the repository — and never chains into another skill. Three verbs read, and write what the
+plugin fixes; this brief carries what is yours to decide and the work done by hand.
+
+## Preconditions
+
+None to check here: `codelife port prep` prints a `- stop:` line for each — no contract or an
+invalid one, `kind: none`, the base's scripts or hooks to do, a machine not connected, a tree not
+clean. A stop ends the run: say it in your reply with what to do, and run nothing else. Work on the
+branch checked out.
+
+## Brief
+
+**Who gave the go-ahead**, and from what, opens it: you, typing the command or answering this
+brief; your confirmed table in a driver, which answers what it named — ask only the rest; the word
+`delegate`; or a session that relayed your words, quoted here — relayed is not delegated. Typed or
+tabled, this brief is an announcement; otherwise the run **stops here** for your go-ahead, after
+nothing but a preparation that only reads.
+
+Then `codelife port prep`, and its block written **in your reply**, in the user's language — a
+tool's output is not one: every line kept as printed, the kind, each item with its state and its
+reasons, the `- toolchain:` line and the item it proposes.
+
+## Parameters
+
+`[item]` — one item to play or replay; without it, every item *to do*, from prep's `- next:`.
+
+## Steps
+
+1. **Propose** prep's `- next:` item, or `[item]`: `codelife port item <name>`, its block in your
+   reply — what it writes, an existing file's difference included, and its checks — with the work
+   below; then **now, or later**. An item *deferred* names its issue: show it, never ask blind.
+   - **Later** — a deferral, never a refusal: `codelife issue create --once feature low
+     port:<item> <file>`, the reason just given as its body; the run goes on with the next item prep
+     proposes, never this one again in this run. A repository that will never take it closes that
+     issue `wontfix`.
+2. **Play** — the item's work below; `codelife port item <name> --write` where it writes from the
+   plugin, `--check` once the work by hand is done. A `- stop:` or `- failed:` line ends the run,
+   quoted: report it, never route around it. **Nothing to change** is an outcome only when every
+   point below was checked and the check is green: no commit, reported *already satisfied*.
+3. **Commit** — `codelife commit` on the verb's `- paths:` and the files the work changed,
+   `chore(toolchain): <what the item did>`, one item to one commit — two for `e` and `e'`. Then
+   `codelife port prep` again and back to 1: proposing the next item asks whether to continue.
+4. **Close** — `codelife port prep` once more, nothing written: its `- toolchain:` line, each item
+   not done with its reason and its issue; then the result block.
+
+### The items
+
+A tool's version is `codelife port version <tool>`'s `- version:` line. An `- ask:` line — a major
+crossed — is put to the user with its date and the newest release inside the current major; a
+`- held:` one only when the work needs that release. A refused install takes an older version,
+never a `minimumReleaseAgeExclude` entry.
+
+- **a1 · workspace** — every in-house dependency, transitively (a path, a git URL, a link to another
+  repository of the owner), a **root** submodule under `submodules/<name>`, initialised
+  non-recursively; `pnpm-workspace.yaml` covering `submodules/*` and the repository's own packages,
+  `minimumReleaseAge: 1440` unless one is set; `pnpm.overrides` sending each in-house package to
+  `workspace:*`, the repository's `file:` specifications converted; `packageManager` pinned, the
+  other lockfile deleted, `prepare` kept. Run the build the repository had: it must still pass. A
+  phantom dependency is filed with the import that revealed it, never hoisted silently.
+- **a2 · Vitest** — `vitest`, the `test/` folder, one trivial test: break it once, see it red,
+  restore it.
+- **b · non-regression** — `--write` instantiates the characterisation tests, and its check's first
+  run records the snapshots and the bundle baseline against the build **as it stands**. A build with
+  no declaration file leaves that half out: file its issue. File one issue naming what the tests do
+  not cover — they hold the package's shape, not what it computes. An application's are written by
+  hand: the build, a start-up smoke in Vitest browser mode, the pure modules snapshotted.
+- **c · Vitest up to date** — moved to its version, the configuration migrated from Vitest's own
+  migration notes; a test that passes only on the old version is filed with both outputs.
+- **d · the build** — `vite-plus` at its version; `--write` for `vite.config.ts`, every Vitest
+  configuration moved into its `test` block, one project per file, and deleted; the former
+  bundler's commands replaced in the manifest and every caller, its configuration deleted; the
+  `generated[]` entry the verb prints written through `codelife setup contract
+  .claude/codelife.md`. Show the regenerated output against the previous one — export names,
+  format, size — and explain each difference before going on; a size that dropped for stripped
+  comments re-records the baseline, with that reason. For a library, ask once whether it wants a
+  playground: yes → `--write --playground`, `tsconfig.json`'s `paths` mapping its name to `src/`.
+  A plugin of the old bundler with no equivalent is filed, naming what it did.
+- **e · TypeScript** — moved first, alone: `chore(toolchain): move TypeScript to <version>`. Then
+  `--write` for `tsconfig.json`, `target` and `lib` at the library's runtime floor; `.js` renamed to
+  `.ts` one folder at a time, its errors fixed before the next; `chore(toolchain): type the source`.
+  An escape that stays carries its reason beside the line, and is filed, one issue each.
+- **e' · lint and format** — the old linter's enabled rules compared with Oxlint's one by one: a
+  rule with no equivalent is covered by a named mechanism, or filed as lost. Two commits, never
+  merged: `chore(toolchain): fix the lint errors`, the source alone, the target's linter run by
+  hand; then `chore(toolchain): move lint and format to the target's tools` — the old tools taken
+  off the ported package (excluded where a sibling package keeps them, their own check still green)
+  and the formatter run, its check first: when it changes nothing, the body says so. A rule
+  disabled to get here is filed, one issue each.
+- **f · scripts** — `--write` puts the target's five verbatim, the difference shown first: a script
+  doing more is kept inside the new command or filed with its command quoted. Every caller updated —
+  CI, `README.md`, `CONTRIBUTING.md` — then `--write --test <a test file>`.
+
+## Never
+
+- Propose an item whose precondition is not met, stop the run at a deferred item, mix two items in
+  one commit, or widen one to fix what it finds — that is an issue, `codelife issue create`.
+- Apply an escape hatch silently, silence a type error with a blanket `any`, weaken a
+  characterisation test, or edit a snapshot by hand.
+- Overwrite a script, a hook or a configuration without showing the difference first.
+- Create a branch, check out, stash, bypass a hook, keep a state file, or chain into `/setup`,
+  `/audit` or any other skill.
+- Answer in a language the user did not write in, or write anything but English into the
+  repository or the tracker.
+
+## Output
+
+The run ends on this block, under this exact heading, its fields in the user's language:
+
+```markdown
+### port-toolchain result
+- Produced: one commit per item played.
+- Decided: each item played, already satisfied or deferred, and each decision an item raised,
+  attributed to the user.
+- Left open: prep's `- toolchain:` line, each item not done with its issue; the debt an item filed.
+- Next: `/port-toolchain` again for the items left; `/audit`. Name them; start none.
+```

package/skills/release/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: release
+description: Cut a version — the bump confirmed, the changelog section, the release commit, the merge into main and the tag, the release entry and the hand-off to the pipeline.
+---
+
+# /release
+
+Closes the cycle: `develop` → `main`, a patch on `main` after a hotfix, or a patch on a `support/`
+line. Three verbs do the work; this brief asks what is yours to decide — the version, an audit
+first, each push — and **hands off**: it never publishes to a registry and never watches a pipeline.
+`--prepare` stops at the release commit, on any branch; a later plain `/release` on `develop`
+resumes it at the merge.
+
+## Preconditions
+
+None to check here: `codelife release prep` checks the branch, a clean tree, `origin`, the version
+file and the changelog generator, and prints a `- stop:` line for each that fails. A stop ends the
+run — say it in your reply with what to do, and run nothing else.
+
+## Brief
+
+**Who gave the go-ahead**, and from what, opens it: you, typing the command or answering this
+brief; your confirmed table in a driver, which answers what it named — ask only the rest; the word
+`delegate`; or a session that relayed your words, quoted here — relayed is not delegated. Typed or
+tabled, this brief is an announcement; otherwise the run **stops here** for your go-ahead, after
+nothing but a preparation that only reads.
+
+Then `codelife release prep` (with `--prepare` when given), and its block written **in your reply**,
+in the user's language — a tool's output is not one: every line, the `breaking:` ones included,
+commands, versions and quoted errors kept as printed. Then the questions, together, each with its
+recommendation: the version — `bump:`'s, or the first one when there is no tag; the `support:` line
+with it, one answer; the audit `audit:` proposes, recommended. A `resume:` line asks nothing: the run
+goes to step 2 with no version.
+
+## Parameters
+
+`[--prepare]`. Nothing else: the branch, the scheme, the bump, the tag and its target are derived,
+and the version is asked in the brief.
+
+## Steps
+
+1. **Audit** — when you accept the one proposed, the run stops here: Next is `/audit`, then
+   `/release` again. Declined, it is said in the result block.
+2. **Cut** — `codelife release cut <version>` (`--prepare` when given; no version on a `resume:`).
+   It writes the version, the changelog section and the generated outputs, runs the release tier,
+   commits `chore(release): <version>`, then merges and tags locally. Write its block in your reply,
+   then the section `section:` counts: whole, read from `CHANGELOG.md`, when it has 40 lines or
+   fewer; longer, its `— **breaking**` entries and the file's path — the counts are the verb's,
+   never yours. A `- stop:` line ends the run, said with what to do. Under `--prepare` the run ends
+   here.
+3. **Push** — each `- push:` line is a command for **you** to run, one at a time, with `! ` before
+   it: list them in your reply, in order, and wait until you say they are done. Nothing is pushed by
+   the run.
+4. **Entry** — `codelife release entry`, its block written in your reply: the release entry, the
+   pipeline's URL, the registry page and what to watch for.
+
+## Never
+
+- Push, publish, watch a pipeline, or move a branch or a tag yourself — the verbs and you do that.
+- Edit the generated list of the changelog section; the prose around it may be retouched, then
+  committed as its own `docs` commit.
+- Go on past a `- stop:` line, or cut a version you did not confirm.
+- Answer in a language the user did not write in, or write anything but English into the
+  repository or the tracker.
+
+## Output
+
+The run ends on this block, under this exact heading, its fields in the user's language:
+
+```markdown
+### release result
+- Produced: the release commit, the merge, the tag, the changelog section, the release entry, the
+  hand-off URLs — or, under `--prepare`, the commit alone.
+- Decided: the version, the support line when one was opened, the audit run or declined.
+- Left open: a push not yet made; an entry `degraded`; an audit declined.
+- Next: nothing — the pipeline is watched by a person at the URL above; `/audit` when you accepted
+  one; `/release` on `develop` once a `--prepare` branch is merged.
+```

package/skills/review-mr/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: review-mr
+description: Review another person's merge request — the checks, How to test, Claude Code's /code-review and a reader against the specification and the plan — in one numbered comment a pass, issues for the debt it did not create, and the forge's own verdict.
+argument-hint: "[mr-number]"
+---
+
+# /review-mr
+
+Reviews the diff between a merge request's head and its merge base, in place at the head: the
+checks and *How to test* first, then `/code-review` and a reader, blind to each other. Each pass
+posts one new comment; the debt it did not create becomes issues; the verdict is the forge's own.
+
+## Preconditions
+
+`codelife review prep` checks them and stops on the first that fails, naming it: a contract whose
+`tracker.kind` names a forge, connected — else `/setup`; a merge request another account authored,
+since one's own was reviewed inside its unit; `HEAD` at its head and a clean tree — asserted, never
+arranged: the stop names the forge's checkout command.
+
+## Brief
+
+**Who gave the go-ahead**, and from what, opens it: you, typing the command or answering this
+brief; your confirmed table in a driver, which answers what it named — ask only the rest; the word
+`delegate`; or a session that relayed your words, quoted here — relayed is not delegated. Typed or
+tabled, this brief is an announcement; otherwise the run **stops here** for your go-ahead, after
+nothing but a preparation that only reads.
+
+Made from `review prep`'s summary alone: the merge request and where its number came from, its
+target and merge base, which pass, *How to test*'s commands and manual steps, the issues it closes
+and each citation that resolves to nothing; with a manual step, that in Claude Code's default
+permission mode its `reproduce` agent asks you to approve commands, the review waiting on each;
+and what will be posted — one comment, issues, a verdict.
+
+## Parameters
+
+`[mr-number]`; absent, the open merge request of the current branch, which the preparation names.
+Nothing else: a review has one shape, whatever the size of the diff.
+
+## Steps
+
+1. **Prepare** — `TMPDIR=<the session's scratchpad> codelife review prep [<n>]`. A `- stop:` line
+   ends the run, its reason said. Its run folder holds what the next steps read.
+2. **The checks, before any agent** — `codelife checks <merge base> <run folder>/commands.txt`.
+   Each `failed:` line is an introduced `high`, quoted from its lines — *How to test*'s at its line
+   in the description: the merge request does not do what it says. A failure the merge request did
+   not cause — a missing binary, no network — and a `could not tell` are no finding, but a line of
+   the pass. Each bullet the summary names *not runnable as written* is a `low` on the description.
+3. **Each manual step** of `manual.md`, one at a time, to one `codelife:reproduce` agent, the step
+   and the summary's `app:` line its prompt: `yes` passes; `no` is an introduced `high`, quoting what happened; `inconclusive` is
+   *not played*, with what was tried. Its question goes to you, your answer back to it with
+   `SendMessage`. A step that needs this merge request's own plugin — it runs `/review-mr`, or a
+   session loading the branch — goes to none: *not played*, naming
+   `claude --plugin-dir <a checkout of the head>` and its actions as what to run by hand.
+4. **Hunt, blind, in one message**: one `codelife:reader` agent, its prompt *read
+   `<run folder>/case.md`, the diff it names and the rules it touches; your report is your last
+   message*, and nothing of this conversation; and the Skill tool on `code-review`, args
+   `medium <merge base>...<head> — review the diff between these two commits of this checkout; post
+   nothing and fix nothing`, wrapped in no agent. Neither sees the other's findings; wait for both.
+5. **Merge, refute nothing** — one list, each finding with its severity, `file:line`, why, fix and
+   source; two that name one defect are one. On a line `lines.tsv` lists it is introduced;
+   elsewhere it is debt, filed unless `known.txt` carries it — *named, not filed* under a submodule
+   the summary names. A finding that holds a rule's *reason* false, not the diff against the rule,
+   is a **contest**: an issue, no number. On a later pass, `comments.md` holds the earlier pass and
+   what people wrote since: each earlier number keeps it and takes its state — *fixed by* a commit,
+   *open*, *refused* with the author's reason, or *now pre-existing, filed as #n* once `lines.tsv`
+   no longer lists its line —, new ones after the highest.
+6. **One table** — each number with its severity, place, state and source; each refusal, accepted
+   or kept open; each debt and contest to file; and the verdict: **approve** when no introduced
+   finding is left open, **request changes** otherwise — which GitLab shows and does not enforce. A
+   draft gets a status instead, *not ready* with the count left open or *ready for review*, and no
+   verdict. Debt never weighs. One answer; nothing is posted before it.
+7. **Post**, from the confirmed table: each debt to file and contest written as
+   `codelife help template bug` or `feature` prints an issue, its first line `# <sentence>` — a
+   contest's body quoting the rule's reason and the fact against it, and asking whether the rule
+   still holds — and filed by `codelife issue create <nature> <severity|-> mr:!<n> <file>`; then the
+   pass, written from `templates/pass.md` into the run folder, its comments removed, and posted by
+   `codelife mr post <n> <file>`, which posts nothing when the head moved; then, unless a draft,
+   `codelife mr verdict <n> approve|request <the pass's link>`.
+8. **Close** — remove the run folder, then read `git status --porcelain` and remove nothing: a file
+   a guard rebuilt is named under *Left open*; any other stops the run, named as one the review left.
+
+## Never
+
+- Check out, stash, detach or switch anything.
+- File, post or send a verdict the table did not confirm.
+- Weigh debt in the verdict, or carry it in the comment.
+- Hand either hunter the other's findings, start an agent to refute one, or wrap `/code-review`.
+- Edit or delete a comment; open, answer or resolve a thread; renumber an earlier finding.
+- Fix, commit or push on the merge request's branch, or widen the diff into an audit.
+- Answer in a language the user did not write in, or write anything but English into the
+  repository or the tracker.
+
+## Output
+
+The run ends on this block, under this exact heading:
+
+```markdown
+### review-mr result
+- Produced: the pass's link; the issues filed, debt and contests; the verdict or the draft's status.
+- Decided: the table, any severity you changed, the verdict.
+- Left open: the citations that resolved to nothing; the steps not played or not runnable; each
+  debt named, `<file:line> — <why>: /new-issue from <submodule>`; each file a guard rebuilt, or the
+  file that stopped the close.
+- Next: `/work <n>` on the debt filed; `/brainstorm #<n>` on a contest; `/work-feedback` for the
+  author.
+```

package/skills/review-mr/templates/pass.md

@@ -0,0 +1,29 @@
+codelife: review — pass <k> — <the head sha this pass read>
+
+**<Changes requested | Approved | Not ready: a draft | Ready for review: a draft>** — <one sentence: the
+findings left open that hold it, or that nothing does>. The verdict is the forge's own.
+
+### Findings
+
+<!-- The earlier passes' numbers first, in their order, then the new ones. The link is the line at
+     the head: https://<host>/<project>/-/blob/<sha>/<path>#L<line> on GitLab,
+     https://github.com/<owner>/<repo>/blob/<sha>/<path>#L<line> on GitHub; a How to test step's
+     place is its line in the description. None: the one line "Nothing." -->
+
+1. **<critical | high | mid | low>** · [`<path>:<line>`](<link>) — <the problem, in plain words>.
+   <Why it matters, one or two sentences.> **Fix:** <the fix it suggests>.
+   *<new | open | fixed by <short sha> | refused — <the author's reason>, accepted | refused — <the
+   author's reason>, kept | now pre-existing, filed as #<n>>*
+
+### Filed
+
+<!-- Left out when nothing was filed. -->
+
+- #<n> — <title>
+
+### What this pass read
+
+- `codelife checks`: <each failed or could-not-tell line, or "every check passed">
+- *How to test*: <each step — passed, failed, not played and what to run by hand, not runnable> |
+  none in the description
+- `/code-review` at `medium`, and the reader against <the issues closed, or the description>