@ersbeth/codelife 0.0.0-bootstrap.0 → 0.11.1

package/scripts/verbs.mjs

@@ -0,0 +1,579 @@
+// The verbs of the `codelife` command line (K-43): each runs one script of the package with the
+// arguments that follow its name, and carries the manual `codelife help <verb>` prints. The one
+// list: scripts/codelife.mjs dispatches on it, and tests/skills.test.mjs holds every verb a brief
+// names to it (C-843). A script's path is from the package's root; `lead` goes before the arguments.
+import './node-floor.mjs'
+import { readdirSync, readFileSync } from 'node:fs'
+
+export const VERBS = {
+  help: {
+    summary: 'list the verbs, or print one verb\'s manual, one shared method or one template',
+    manual: `codelife help [<verb>]
+codelife help method [<name>]
+codelife help template [<name>]
+
+With no verb, one line per verb. With one, its manual: what it runs, its arguments, what it prints.
+\`help method\` lists the methods two briefs share; with a name, prints that method, read at the
+step that uses it (anatomy.md C-845). \`help template\` lists the templates a brief drafts from —
+an issue's, which \`setup item templates\` also copies to the forge, and a specification
+document's —; with a name, prints that template.`,
+  },
+  init: {
+    script: 'scripts/init.mjs',
+    lead: ['init'],
+    summary: 'install codelife into the repository you stand in (R-272)',
+    manual: `codelife init [<package spec>]
+
+Adds @ersbeth/codelife as a devDependency of the repository you stand in, with its own package
+manager, and links the plugin; nothing else — /setup does the rest. The spec defaults to the
+published version this binary belongs to. Run as \`pnpm dlx @ersbeth/codelife init\`.`,
+  },
+  spec: {
+    script: 'scripts/spec.mjs',
+    summary: 'print one rule, case, persona, journey or capability of docs/spec/ by its identifier',
+    manual: `codelife spec <identifier>
+
+Run from the repository's root. Prints the file and line where the identifier is defined, then:
+a rule, a case, a persona — its heading and its text, a rule's cases included; a capability or a
+journey — its title and the outline of its headings, never the document whole. Then the lines of
+Rejected that open on the identifier, if any; a retired identifier prints those alone. Exit 1
+when it resolves to nothing, 2 on a malformed identifier or no docs/spec/.`,
+  },
+  search: {
+    script: 'scripts/search.mjs',
+    summary: 'search what is already known about a subject: the open issues, what docs/spec/ decided, the pending notes (R-179)',
+    manual: `codelife search <terms file>
+
+Run from the repository's root. One term per line of the file. Searches each term alone, as a whole
+word, regardless of case: over the open issues — the forge's search, or the issues/ files under
+\`tracker.kind: none\` —, then over what docs/spec/ decided, each rule's heading and each line of a
+\`## Rejected\`, by its text, then over the notes of docs/brainstorm/, each one's title and its
+**Open** items. Prints a \`### search\` block: the terms, then each pass's count and
+its first ten lines, each line once after the number of terms it matched and a tab, the most first.
+Writes nothing. Exit 2 on a missing or empty file.`,
+  },
+  form: {
+    script: 'scripts/spec-form.mjs',
+    summary: 'hold docs/spec/ to its form, check a note was copied into it whole, or print what a plan is cut from (K-23)',
+    manual: `codelife form spec
+codelife form note <note>
+codelife form fold <note> [--base <rev>]
+codelife form cases
+
+Run from the repository's root; the form script the pre-commit hook runs. \`spec\` holds docs/spec/
+to its form. \`note\` holds a note's own shape against docs/spec/ as it stands, before its
+writing: each decision's target, rejected options and cases, the cases under one rule. \`fold\`
+checks that the writing of <note> into docs/spec/ lost nothing against <rev>, HEAD by default —
+each case, refusal line and identifier — and the note's shape against <rev>. A blocking rule prints
+\`<file>:<line>: <rule>: <what is wrong>\` and exits 1; an \`orphan:\` line is a report. \`cases\`
+prints every rule and case with its capability, the cases each journey cites and the index of their
+headings, and holds nothing. On a docs/spec/ without its seven entries each mode prints that it is
+not in the form and holds nothing, \`fold\` blocking. Exit 2 on no mode.`,
+  },
+  checks: {
+    script: 'scripts/checks.mjs',
+    summary: 'run the push tier, the guards a diff fires, the reading hygiene scripts, the stale outputs and How to test\'s commands, before any agent (C-853)',
+    manual: `codelife checks <base> [<commands file>]
+
+Run from the repository's root, before any agent of a review starts. Runs the push tier
+(verify:push), then every guards[] command of the contract whose \`when\` matches a path the diff
+from <base> to HEAD touches, then the hygiene scripts that only read — DEPS and GUARD, and TYPE
+under \`kind: lib\` —, then checks each generated[] output whose \`when\` the diff matches,
+failed when the diff leaves it untouched, then runs each distinct line of the commands file, a
+\`<manager> verify:push\` line skipped — one after the other. Prints one line per check, \`passed: <check>\`,
+\`failed: <check>\` or, for a hygiene script whose subject is absent, \`could not tell: <check>\`,
+anything but a pass followed by the last lines of its output and a guard's note, and nothing else.
+Exit 0 when no check failed, 1 when one failed or could not run, 2 when <base> resolves to no
+commit or git finds no diff from it to HEAD — no merge base, a shallow clone.`,
+  },
+  'review prep': {
+    script: 'scripts/review-mr/prepare.mjs',
+    summary: 'prepare a review: the merge request, the head asserted, the diff, the known list, the reader\'s case (C-762)',
+    manual: `codelife review prep <mr>
+
+Run from the repository's root, at the merge request's head, on a clean tree, on another person's merge request. Reads the merge
+request, the account, the forge CLI against its floor, the diff from the merge base, the submodules at the head, the open issues
+and the debt the description names, and the issues the commits close with what each cites; writes
+nothing in the tree. Writes a run folder outside it — mr.json, comments.md, diff.diff, lines.tsv,
+known.txt, case.md — and prints one \`### prepare\` summary; a \`- stop:\` line names what stops the review
+before any agent, and the exit is 1.`,
+  },
+  'feedback prep': {
+    script: 'scripts/work-feedback/prepare.mjs',
+    summary: 'prepare an answer to a review: your merge request, its branch asserted, the rows left to answer (K-13)',
+    manual: `codelife feedback prep [<mr>]
+
+Run from the repository's root, on the merge request's branch, at its head or ahead of it, on a
+clean tree, as its author. Reads the merge request — the argument, or the one open for the current
+branch —, the latest review pass, the answers to it, the comments people wrote after it and the
+threads they opened, and the \`Answers:\` trailers since the merge base; writes nothing in the tree.
+A row is a pass's number still \`new\`, \`open\` or \`refused … kept\`, a comment or an open thread,
+less those an answer's table already carries; one a trailer names is marked with its commit. Writes
+rows.md in a run folder outside the tree and prints one \`### prepare\` summary; a \`- stop:\` line
+names what stops the run — nothing left to answer among them — and the exit is 1.`,
+  },
+  'issue view': {
+    script: 'scripts/tracker/issue.view.mjs',
+    summary: 'print an issue whole: its description, then every comment and close, oldest first',
+    manual: `codelife issue view <n>
+
+Run from the repository's root, the tracker connected. Prints the issue's title, state and labels,
+its description, then each comment and each close or reopening under a \`## <date> — <author or
+state>\` heading, oldest first — every page, system notes left out. Under \`tracker.kind: none\`, the
+file's \`## Notes\` sections, with no history of its state.`,
+  },
+  'issue section': {
+    script: 'scripts/tracker/issue.section.mjs',
+    summary: 'print one section of an issue, or its latest plan',
+    manual: `codelife issue section <n> <heading>
+
+Run from the repository's root, the tracker connected. Prints the issue's description from its
+\`## <heading>\` line — the heading's opening words, any case — to the next \`## \`. The heading
+\`plan\` prints instead the latest comment opening on \`codelife: plan — \`. Exit 1 when there is none.`,
+  },
+  verify: {
+    script: 'scripts/verify.mjs',
+    summary: 'run a tier, the guards the change fires and the outputs it makes stale (R-199)',
+    manual: `codelife verify commit|push [<base>]
+
+Run from the repository's root. Runs each contract \`generated[]\` command whose \`when\` matches
+a path the working tree changed — or the diff from <base> to HEAD, when given — and stages its path,
+then the \`verify:commit\` or \`verify:push\` script through the package manager and each
+\`guards[]\` entry whose \`when\` matches. Prints one line per check, \`passed\`
+or \`failed\` with its last lines and a guard's note; exit 1 on a failure or a tier not ported.`,
+  },
+  'issue note': {
+    script: 'scripts/tracker/note.mjs',
+    summary: 'post one new comment on an issue from a file (R-199)',
+    manual: `codelife issue note <n> <comment file>
+
+Run from the repository's root, the tracker connected. Posts the file as one new comment on the
+issue — under \`tracker.kind: none\`, a dated section appended to its file — and prints \`noted #<n>\`.`,
+  },
+  'issue create': {
+    script: 'scripts/tracker/create.mjs',
+    summary: 'file one new issue from a file, its title tagged by its origin, and print its number (C-868)',
+    manual: `codelife issue create [--once] <bug|feature|lot|-> <critical|high|mid|low|-> <origin|-> <file>
+
+Run from the repository's root, the tracker connected. The file opens on a \`# <sentence>\` line, the
+rest is the body. Files one issue titled \`[<origin>] <sentence>\` — the sentence alone for \`-\` —,
+labelled with the nature and \`severity-<s>\`; a \`lot\` is an umbrella, titled \`[lot · <origin>]\` and
+labelled \`lot\` alone; a nature \`-\` takes no label, as the roadmap does. Under \`tracker.kind: none\`, a new issues/ file.
+Prints \`created #<n> — <link or path>\`; exit 1 when the number does not read back. With --once, an
+issue whose tag already holds the origin, open or closed, files nothing: \`exists #<n> — <its line>\`.`,
+  },
+  'issue update': {
+    script: 'scripts/tracker/issue.update.mjs',
+    summary: 'replace an issue\'s description from a file, its title from another (K-8)',
+    manual: `codelife issue update <n> <body file>|- [<title file>]
+
+Run from the repository's root, the tracker connected. Replaces the issue's description with the
+file — \`-\` leaves it — and its title with the second file's first line, when given; under
+\`tracker.kind: none\`, its issues/ file. Prints \`updated #<n>\`.`,
+  },
+  'issue close': {
+    script: 'scripts/work/close.mjs',
+    summary: 'close an issue on its own commit, tick its umbrella, close the umbrella with its last member (R-193)',
+    manual: `codelife issue close <n> <comment file> <hash>… [--wontfix]
+
+Run from the repository's root, the tracker connected. Posts nothing unless HEAD contains every
+hash the comment cites and each one's \`Closes:\` footer names the issue — or, for \`Already fixed
+in <hash> (#<earlier>)\`, whose \`Closes:\` or \`Refs:\` footer names that issue, closed on the tracker;
+with \`--wontfix\`, a hash may instead add to docs/spec/ the refusal line the comment quotes. Then posts the comment and closes the issue, ticks its line
+in its umbrella with every row whose issue is already closed, and when no member is open closes
+the umbrella on a \`lot-closing\` comment. A \`- stop:\` line names a refusal, and the exit is 1.`,
+  },
+  'issue reopen': {
+    script: 'scripts/work/reopen.mjs',
+    summary: 'reopen an issue whose held choice you refused, its reason posted, its umbrella line unticked (R-295)',
+    manual: `codelife issue reopen <n> <comment file>
+
+Run from the repository's root, the tracker connected. Reads the issue and its umbrella first, then
+posts the comment, reopens the issue, unticks its line in its umbrella and reopens the umbrella when
+it was closed. Under tracker.kind none, or a task list that cannot be unticked, a \`- stop:\` line,
+exit 1, nothing posted.`,
+  },
+  'mr comments': {
+    script: 'scripts/tracker/mr.comments.mjs',
+    summary: 'print the latest review pass, the comments people wrote after it and the threads they opened (C-865)',
+    manual: `codelife mr comments <mr>
+
+Run from the repository's root, the tracker connected. Prints a \`### comments\` block — the latest
+pass (\`codelife: review — pass <k> — <sha>\`) with its number, sha, author and link, every pass's
+link, and how many answers, comments and open threads people left after it — then the pass whole,
+each answer to it (\`codelife: answer — pass <k> — \`), each comment written after it, and each
+open thread a person opened. Writes nothing.`,
+  },
+  'mr post': {
+    script: 'scripts/tracker/mr.post.mjs',
+    summary: 'post one new comment from a file, never edited, and print its link (C-864)',
+    manual: `codelife mr post <mr> <file>
+
+Run from the repository's root, the tracker connected. Posts the file as one new general comment
+and prints its link, read back. A file whose first line opens on \`codelife:\` and ends on a sha
+is about that head: when the merge request's head is another, nothing is posted and the exit is 1;
+when that very comment is already there, nothing is posted and its link is printed.`,
+  },
+  'mr verdict': {
+    script: 'scripts/tracker/mr.verdict.mjs',
+    summary: 'send the forge\'s own verdict: approve, or request changes (C-866)',
+    manual: `codelife mr verdict <mr> approve|request [<pass link>]
+
+Run from the repository's root, the tracker connected. On GitLab, approves, or sets the account's
+reviewer state to requested changes and reads it back; on GitHub, submits a review in that state,
+its body the pass's link. An approval of the account's own merge request is refused, exit 1.`,
+  },
+  'mr open': {
+    script: 'scripts/mr/open.mjs',
+    summary: 'print what a branch\'s merge request sends, or push it and open or update the request (C-873)',
+    manual: `codelife mr open [<description file>] [--send] [--wrap | --append]
+
+Run from the repository's root, the tracker connected, on the branch to open. Without --send prints
+a \`### mr open\` block and sends nothing: the branch and its derived target, how many commits the
+target holds that it lacks and whether a merge of them conflicts or changes its tree, the commits
+leaving with their count, each held choice waiting and each one a \`Replaces:\` took out of the wait,
+the members of the lot still open each with its last STATUS, and whether a merge request opens or
+\`!n\` is updated, the existing description written to a file it names. Then what the description
+is written from: a \`linked:\` line per issue the commits cite, lot member and umbrella, with its title;
+each \`hand commit:\`, the ones no unit's closing comment cites; the \`links:\` base, the \`run:\` prefix,
+the \`generated:\` outputs the diff touches, a \`debt:\` line per number the file's Debt noticed cites,
+and, when the only new commit merges the target in, that the description is kept. A line that asks
+a question says so: a held choice's later commits on its files, a merge of the target to accept. With --send checks again and refuses, exit 1 with a \`- stop:\` line and nothing
+sent, a branch behind its target whose merge changes its tree or conflicts, or a tree not clean; runs
+the push tier against the target, a red naming its failure; pushes with the upstream set, never
+forced; then creates the merge request or replaces the tagged region of the existing description,
+nothing outside it, and prints the link. A new request's title is the file's first line when it reads
+\`# <title>\`, dropped from the description, or else the branch's issue's — the dry run saying so when
+the commits close several issues and no umbrella names them. The file must carry the region and the template's headings;
+an existing description with no region is refused unless --wrap (the region replaces it whole) or
+--append (the region is added below it) says which; an update without a file keeps the description; the dry run needs none, a --send that creates does. Under tracker.kind none, exit 1. Exit 2 on a usage error.`,
+  },
+  'audit prep': {
+    script: 'scripts/audit/prepare.mjs',
+    summary: 'open or resume an audit campaign: its lenses, the known list, the fingerprint, the push tier, the facts and the cut, a folder per part to judge (C-869)',
+    manual: `codelife audit prep [full | targeted <LENS>…] [--red]
+
+Run from the repository's root, before any agent. Stops, exit 1 with a \`- stop:\` line, on a tree
+not clean but for a campaign folder, a campaign under way at another commit than HEAD, a retired lens
+or one with no reference, no verify:push script, or a red push tier unless --red audits it. Resumes
+the campaign under way — its index reads IN PROGRESS —, with its own lenses; otherwise opens the next
+number of docs/audit/README.md's table: every lens the contract's kind makes applicable and every
+domain lens for full, the named ones for targeted. Writes the known list — the open issues and what
+docs/spec/ decided —, takes the fingerprint of every file outside docs/audit/, runs verify's report
+at HEAD (the push tier, the hygiene scripts, the history, PERF's timings, the cut), then writes the
+campaign folder, its index and fingerprint.tsv, and outside the tree a folder for the judge of every
+part whose folder holds no part.md, emptied for it, listed in judges.tsv. Prints one
+\`### audit prep\` summary, ending on the cap of judges at once. Exit 2 on a usage error.`,
+  },
+  'audit table': {
+    script: 'scripts/audit/table.mjs',
+    summary: 'print the table one lens\'s findings are confirmed on, every part judged and accounted for (R-110)',
+    manual: `codelife audit table <LENS>[,<LENS>…]
+
+Run from the repository's root, a campaign under way. Stops, exit 1, on a part with no part.md or
+whose judge left a received candidate id unaccounted, naming what to run again. Prints one row per
+finding of the lenses across the parts — id, title, severity with UNVERIFIED, effort, and its state:
+its disposition, filed #n when an issue's tag carries its id, known #n, or new, a title two rows share
+flagged — then, below the rows, each To watch, Deliberate choice and False line of its judges, and
+the Contested ones. Writes nothing.`,
+  },
+  'audit file': {
+    script: 'scripts/audit/file.mjs',
+    summary: 'file one confirmed table: an issue per new finding, a re-reported comment per known one, each disposition written back (R-111, R-112)',
+    manual: `codelife audit file <rows file>
+
+Run from the repository's root, a campaign under way. One row a line: \`<id> <bug|feature> <severity>\`,
+\`<id> known\`, \`<id> false\`, \`<id> refused <address>\` or \`<id> merged <id>\`. Checks every row
+first. A new finding is filed through \`issue create --once\` with the origin audit:<id>, its body the
+finding's lead, then the finding whole as its first comment, \`codelife: finding\`; an issue already
+tagged with the id is taken as filed. A known one gets a \`codelife: re-reported\` comment. Each
+disposition is appended to its finding's file as its row is done; a row already disposed is skipped.
+Prints one line per row; exit 1 with a \`- stop:\` line on a bad row or a forge write that fails.`,
+  },
+  'audit close': {
+    script: 'scripts/audit/close.mjs',
+    summary: 'close the campaign under way: the checks, the findings by lens, the banner frozen, the fingerprint compared (R-226, R-227)',
+    manual: `codelife audit close
+
+Run from the repository's root. Stops, exit 1 and nothing written, on a finding with no disposition
+or an index still holding a placeholder the session writes. Then fills the index's findings by lens
+and the paths no lens read in the end, turns its banner FROZEN, names every file outside docs/audit/
+that differs from the fingerprint — docs/spec/'s refusal lines apart —, removes fingerprint.tsv, and
+prints the close commit's message and paths.`,
+  },
+  'audit fold': {
+    script: 'scripts/audit/fold.mjs',
+    summary: 'once the close commit is HEAD, delete the campaign folder and write its row in the campaign table (R-226)',
+    manual: `codelife audit fold
+
+Run from the repository's root, HEAD being \`docs(audits): close campaign A<n>\`. Stages the deletion
+of that campaign's folder and writes its row at the top of docs/audit/README.md's table — its id
+linked to the index at that commit on the forge, or the sha and the path with no forge —, then prints
+the fold commit's message and paths. Exit 1 with a \`- stop:\` line otherwise.`,
+  },
+  'work prep': {
+    script: 'scripts/work/prepare.mjs',
+    summary: 'prepare a lot or a lone issue: its members in order, or the issue, its branch, its joins (R-288)',
+    manual: `codelife work prep <umbrella-or-issue>
+
+Run from the repository's root, on a clean tree, the tracker connected, with a \`test:one\` script.
+Reads the number as an umbrella — an issue labelled lot — or a lone issue: the umbrella, its
+members and the orphans a debt-link on it points at; or the issue, its evidence and its last plan or refusal; then the
+branch the work belongs on, and whether a rule a member or the issue cites moved since the
+roadmap's mark; writes nothing. A lot's member names its umbrella and stops. Prints one
+\`### prepare\` summary; a \`- stop:\` line names what stops the run before any table, and the exit is 1.`,
+  },
+  overview: {
+    script: 'scripts/overview/overview.mjs',
+    summary: 'print where the repository stands, one screen, and the first rule of Next that holds (K-6)',
+    manual: `codelife overview
+
+Run from the repository's root. Reads the contract, the tree, git, origin, the tracker and the
+registry, and prints one \`### overview\` screen: the connection, the contract, the target, the
+audit, the issues by lot then the orphans by severity, the merge requests, the resumption
+artefacts, then \`**Next**\`, the first rule of R-173 that holds with its reason and its row. A
+source that does not answer prints as unreadable with its error, never as empty, and stops Next
+at the first rule that reads it. Writes nothing, asks nothing; exit 0.`,
+  },
+  'roadmap prep': {
+    script: 'scripts/roadmap/prepare.mjs',
+    summary: 'prepare a plan: the roadmap and its mark, what docs/spec/ changed since, the open issues sorted, a folder per capability to cut (K-8)',
+    manual: `codelife roadmap prep [<label-or-milestone>] [--from <sha>]
+
+Run from the repository's root, the tracker connected. Reads the roadmap — its mark, its order, the
+orphans it left alone — or, with none, where a first run starts; then what docs/spec/ changed from
+the mark, or <sha>, to HEAD: each case with the commit that last wrote it, proposed built when the
+merge that brought it changed a file outside docs/. Reads every open issue, each written to
+issues/<n>.md, and prints the umbrellas with their Done when, each member whose latest plan says
+\`Waits for: C-<n>\` and the issue that builds it, the issues citing what changed, the orphans — those
+the label or milestone names, when given. Writes a run folder outside the tree — cases.tsv,
+cut.tsv, built.tsv, journeys.txt, one K-<n>/ per capability to cut, its document and index.txt, on
+a first run over tests its tests.txt — and prints one \`### prepare\` summary; a \`- stop:\` line names
+what stops the run before any table, and the exit is 1. Writes nothing on the forge.`,
+  },
+  'roadmap cut': {
+    script: 'scripts/roadmap/cut.mjs',
+    summary: 'cut a prepared range into lots from the prerequisites blocks saved in its folder (K-8)',
+    manual: `codelife roadmap cut <run folder>
+
+Run from the repository's root on the folder \`codelife roadmap prep\` printed, each prerequisites
+block saved in its blocks/. Cuts the cases into lots — each one capability's cases at one stage,
+within about ten, after the lots it waits for — places them after the roadmap's confirmed lines,
+adds the open lot building a case a lot presumes outside the cut and the last open lot of each of
+its capabilities, proposes an orphan citing one of a member's cases as that member and an effort
+from the member's cases. Writes table.md in the folder and prints one \`### cut\` summary, a line per
+lot and per flag; a \`- stop:\` line names what the cut could not judge, and the exit is 1.`,
+  },
+  'roadmap write': {
+    script: 'scripts/roadmap/write.mjs',
+    summary: 'rewrite the roadmap, last: the mark read, the orphans left alone, the open lots in order (R-263)',
+    manual: `codelife roadmap write <run folder> <order file> [<left alone file>]
+
+Run from the repository's root on the folder \`codelife roadmap prep\` printed. The order file holds
+one \`#<n> <sentence>\` line per open lot, in order, \` — after #<a>, #<b>\` when it waits for open
+lots; the left-alone file one \`#<n> <sentence>\` per orphan grouped with nothing. Writes the roadmap
+from its template, the mark at the HEAD the folder read, and updates it — or creates the first.
+A line out of shape is refused, nothing sent, exit 1.`,
+  },
+  'lot join': {
+    script: 'scripts/work/member.mjs',
+    lead: ['join'],
+    summary: 'join issues to a lot: each title\'s lot half and its row in the umbrella (R-251)',
+    manual: `codelife lot join <umbrella> <n>[:S|M|L]...
+
+Run from the repository's root, the tracker connected. Writes the lot into each issue's title and
+appends its row, with the effort when given, to the umbrella's \`## The order\` in the order given,
+the umbrella read and written once, every write computed before the first; a part already written is
+left as it is; \`<n> S|M|L\` reads as \`<n>:S|M|L\`. Refuses an issue of another lot, writing nothing.
+Prints one \`### lot join\` summary; a \`- stop:\` line, exit 1.`,
+  },
+  'lot leave': {
+    script: 'scripts/work/member.mjs',
+    lead: ['leave'],
+    summary: 'take an issue out of a lot, its reason written on both (R-202)',
+    manual: `codelife lot leave <umbrella> <n> <reason file>
+
+Run from the repository's root, the tracker connected. Removes the lot from the issue's title,
+opens its body on \`Left lot #<umbrella> on <date>: <reason>\`, and replaces its row in the
+umbrella's \`## The order\` with one \`Left on\` line; when no row left is an open issue, closes the
+open umbrella on a \`lot-closing\` comment, \`wontfix\` when no row is left. Prints one
+\`### lot leave\` summary.`,
+  },
+  commit: {
+    script: 'scripts/git/commit.mjs',
+    summary: 'commit the named paths from a message file, waiting on no input (R-84)',
+    manual: `codelife commit <message file> <path>...
+
+Run from the repository's root; reads no stdin. Checks first, touching nothing, and refuses with
+exit 2 naming the problem: no path or message file, a named path holding a newline (\`unreadable\`),
+a file staged that no named path covers (\`staged beforehand: <path>\`, not checked during a merge,
+cherry-pick or revert), a path \`git add\` cannot take (ignored, unmatched) — a path, a file or a folder
+gone from the disk, whose deletion \`git rm\` already staged is that path's change. Then stages the paths and commits the index whole
+with the message file's text; a refusing hook is printed as git prints it, exit 1, the only 1. Then prints \`<hash> <subject>\`, \`left unstaged: <path>\` per named path still
+changed (what a hook reformatted), and \`not committed: <path>\` per other change; a name holding a
+newline prints \`unreadable: <label>\` in place of the path. Any other failure exits 2.`,
+  },
+  'release prep': {
+    script: 'scripts/release/prep.mjs',
+    summary: 'state a release before its version is asked: the branch, origin, the last tag, the commits since it, the bump, a release prepared, the audit due (K-16)',
+    manual: `codelife release prep [--prepare]
+
+Run from the repository's root. Reads only. Prints one \`### release prep\` block: the branch and the
+release it makes — develop, main after a hotfix, a support/ line; any branch with --prepare —, origin
+as the forge has it, the version file, the line's last tag (\`v<version>\`, \`<name>--v<version>\` or
+\`r<version>\`), the commits since it by type and each breaking one, the scheme and the bump it
+gives, a support/ line the moved peer opens, a version prepared and untagged — \`resume:\` when
+nothing landed after its release commit —, the audit the cadence proposes, the changelog generator
+run with --check, the tracker. A \`- stop:\` line per thing that stops the release — a work branch, a
+tree not clean, a branch behind or diverged, nothing since the tag — and exit 1.`,
+  },
+  'release cut': {
+    script: 'scripts/release/cut.mjs',
+    summary: 'make the confirmed release locally: version, changelog, outputs, release tier, commit, then merge and tag; push nothing (R-245, R-246)',
+    manual: `codelife release cut [<version>] [--prepare]
+
+Run from the repository's root, on a clean tree, with the version you confirmed — none to resume a
+prepared one. Writes the version into the version file and every published package.json, renders
+the changelog section, regenerates the generated[] outputs the range since the last tag fires, then
+runs verify:release and the guards that range fires: a red, a generator failing, or a path changed
+outside those declared restores every tracked file and stops. Then commits \`chore(release):
+<version>\` and prints a \`- section:\` line, the section's lines and entries per heading
+counted; with --prepare it stops there. Otherwise, on develop: merged into main with a merge
+commit, the annotated \`v<version>\` tag on main, develop fast-forwarded; on main: tagged, then
+merged back into develop; on a support/ branch: tagged there. Pushes nothing: prints one
+\`- push:\` line per branch and one for the tag, each yours to run. Exit 1 on a stop, 2 on usage.`,
+  },
+  'release entry': {
+    script: 'scripts/release/entry.mjs',
+    summary: 'once the tag is on origin, create the forge\'s release entry from the changelog section, then print the hand-off (R-247)',
+    manual: `codelife release entry
+
+Run from the repository's root, once \`v<version>\` is on origin. Creates the forge's release entry on
+the tag, its notes the version's changelog section; an entry that exists is left, one the forge
+refuses is a \`degraded\` line; under tracker.kind none, or with no origin, the section is the entry.
+Then prints the pipeline's URL, the registry page of a package that is not private, and the three
+failure modes to recognise. Publishes and watches nothing. Exit 1 when the tag is missing here or
+on origin.`,
+  },
+  'setup prep': {
+    script: 'scripts/setup/prep.mjs',
+    summary: 'state a repository before /setup asks: the mode, origin and its connection, what the contract is inferred from, the forge settings, each base item (K-1)',
+    manual: `codelife setup prep
+
+Run from the repository's root. Reads only. Prints one \`### setup prep\` block: the mode — first run,
+or update with the contract current, stale or invalid —, origin and the forge its host is, the CLI,
+the connection and its expiry, a token variable set in the shell, and when not connected the
+guide: the token page, its name and boundary, every permission, the login command for your own
+terminal. Then what the contract's values come from — kind, release.version_file, generated
+candidates —, the prose to read whole, the default branch, the merge method, the package, the
+former form, and one \`- item <name>:\` line per base item, done, to do with why, not applicable
+or not read. A \`- stop:\` line per thing that stops the run — not connected, an invalid contract, a
+default branch other than main —, and exit 1.`,
+  },
+  'setup contract': {
+    script: 'scripts/setup/contract.mjs',
+    summary: 'hold the contract you confirmed to its schema and write it, the settings settled (K-1)',
+    manual: `codelife setup contract <file>
+
+Run from the repository's root. Reads the file — a draft, or .claude/codelife.md you edited — and
+holds it to the schema: a \`- invalid:\` line each and exit 1, nothing written; a \`- stale:\` line
+each. Then writes it to .claude/codelife.md, and replaces a former marketplace's lines in
+.claude/settings.json by "codelife@codelife": false. Prints \`- paths:\`, what \`codelife commit\` takes.`,
+  },
+  'setup item': {
+    script: 'scripts/setup/item.mjs',
+    summary: 'show what one base item changes, or with --write do it and run its check; commit nothing (K-1)',
+    manual: `codelife setup item <labels|templates|scripts|hooks|folders|changelog|develop> [--write] [--test <file>]
+
+Run from the repository's root. Without --write, reads only: what the item would create, write or
+move, an existing file's difference included. With --write, does it, then runs the item's check:
+labels — each fixed one on the tracker; templates — the forge's three files; scripts — engines, the
+packageManager pnpm wrote, node_modules/ ignored, then each of the five run (test:one on --test);
+hooks — verify:commit and verify:push green first, the former form migrated, the three stubs, the
+prepare line, ## Setup's line, the install run, a \`wip\` commit refused; folders — the base's;
+changelog — the marker, the generated part, --check reproducing it; develop — created from main,
+or fast-forwarded. Prints \`- paths:\` for \`codelife commit\`; a \`- stop:\` line exits 1 with nothing
+written, a \`- failed:\` line exits 1 after.`,
+  },
+  'port prep': {
+    script: 'scripts/port/prep.mjs',
+    summary: 'state a toolchain port before /port-toolchain proposes: each item done, to do, deferred, refused or blocked, the summary line, the next item (K-2)',
+    manual: `codelife port prep
+
+Run from the repository's root. Reads only. Prints one \`### port prep\` block: the kind and the ported
+package — the directory of release.version_file —, one \`- item <name>:\` line per toolchain item, in
+the order the port plays them — done, not applicable, not read, to do with why, deferred or refused
+with its \`port:\` issue, blocked by the item its precondition waits on —, the \`- toolchain:\` summary
+line, and \`- next:\`, the first item to do whose precondition is done. A \`- stop:\` line — no
+contract or an invalid one, kind none, the base's scripts or hooks to do, not connected, a tree not
+clean — and exit 1.`,
+  },
+  'port item': {
+    script: 'scripts/port/item.mjs',
+    summary: 'show what one toolchain item writes from the templates, or with --write write it and run its checks, or --check alone; commit nothing (K-2)',
+    manual: `codelife port item <a1|a2|b|c|d|e|e'|f> [--write | --check] [--test <file>] [--playground]
+
+Run from the repository's root. Without a flag, reads only: what the item writes from the plugin —
+b the characterisation tests, their declaration half left out when the build ships none; d
+vite.config.ts, and with --playground the playground and its dev script; e tsconfig.json; f the
+target's five scripts — each file's difference included, the generated[] entry d implies, and the
+checks it runs. With --write, writes them, then runs the checks: the item's own, then test:all — f
+runs the five, test:one on --test. With --check, the checks alone. Prints \`- paths:\` for
+\`codelife commit\`; a \`- stop:\` line exits 1 with nothing written, a \`- failed:\` line exits 1 after.`,
+  },
+  'port version': {
+    script: 'scripts/port/version.mjs',
+    summary: 'the version a tool moves to: past minimumReleaseAge, vite-plus\'s exact pin, or the newest every peer range admits (R-162)',
+    manual: `codelife port version <tool>
+
+Run from the repository's root. Reads the registry through pnpm, and pnpm-lock.yaml. Prints one
+\`### port version\` block: the current version, the window, each lockfile package's peer range on the
+tool, then \`- version:\` — vite-plus's newest release past the window, the exact version it pins for a
+tool it carries (Vitest and @vitest/*, Oxlint, Oxfmt, Vite), else the newest past the window every
+range admits. \`- ask:\` for a move across a major, with the newest release inside the current one;
+\`- held:\` for a newer release the window still holds. Exit 1 when the registry does not answer.`,
+  },
+  'onboard prep': {
+    script: 'scripts/onboard/prep.mjs',
+    summary: 'state the documentation set before /onboard proposes: the set the kind makes, each document and when it changed, the facts, the open bugs and pending notes (K-3)',
+    manual: `codelife onboard prep
+
+Run from the repository's root. Reads only. Prints one \`### onboard prep\` block: \`- kind:\` and the set it
+makes — README, CONTRIBUTING, CLAUDE.md, a library's SKILL.md beside its version file, a workspace
+package's CLAUDE.md where one exists —; one \`- document <name>:\` line each, absent, or present with its
+last commit against the code's, and for SKILL.md a frontmatter name that is no skill name or a
+\`files\` list it is missing from; the facts — package, entry points, workspace packages, source and
+test files by directory, hooks, release, generated[], licence —; \`- known:\` the open bugs by title,
+\`not read\` with the reason when the tracker does not answer; \`- notes:\` the pending notes of
+docs/brainstorm/. A \`- stop:\` line — no contract or an invalid one, a document of the set with changes
+not committed — and exit 1.`,
+  },
+  'log since': {
+    script: 'scripts/git/log_since.mjs',
+    summary: 'print the commits since a ref whose footer cites an issue (R-201)',
+    manual: `codelife log since <ref> <n>
+
+Run from the repository's root. Prints one \`<sha> <subject>\` line per commit of <ref>..HEAD whose
+\`Closes:\` or \`Refs:\` footer cites #<n>; exit 1, nothing on stdout, when none does.`,
+  },
+}
+
+// The methods two briefs share (anatomy.md R-289), scripts/methods/<name>.md, and the templates a
+// brief drafts from — an issue's, scripts/tracker/templates/, a specification document's,
+// scripts/target/templates/spec/: one file each, printed by `codelife help method|template <name>`
+// rather than loaded as a skill. `method` and `template` return its text, or undefined.
+const shelf = (...dirs) => {
+  const files = () => Object.fromEntries(dirs.flatMap((d) => readdirSync(d).filter((f) => f.endsWith('.md')).map((f) => [f.slice(0, -3), new URL(f, d)])))
+  return [() => Object.keys(files()).sort(), (name) => Object.hasOwn(files(), name) ? readFileSync(files()[name], 'utf8') : undefined]
+}
+export const [methods, method] = shelf(new URL('./methods/', import.meta.url))
+export const [templates, template] = shelf(new URL('./tracker/templates/', import.meta.url), new URL('./target/templates/spec/', import.meta.url))
+
+// verb <words> — the longest verb whose words open the list, and the words after it; or undefined.
+export const verb = (words) => {
+  for (let k = words.length; k > 0; k--) {
+    const name = words.slice(0, k).join(' ')
+    if (Object.hasOwn(VERBS, name)) return [name, words.slice(k)]
+  }
+  return undefined
+}

package/scripts/verify/BUILD.mjs

@@ -0,0 +1,33 @@
+// BUILD's facts: the build runs, silently, leaves the committed output as it is, and gives the same
+// bytes twice. It builds in the tree, as the campaign that runs it says in its *Method*.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { absent, fail, lines, manifest, named, paths, runner, sh } from './lib.mjs';
+
+const pkg = manifest();
+if (!pkg.scripts?.build) absent('no build script — BUILD has no subject');
+const [pm, run] = runner(pkg);
+const build = () => sh(pm, [...run, 'build']);
+
+// What a build wrote: tracked files it changed, and files it created, ignored ones included.
+const touched = () =>
+  [
+    ...paths('diff', '--name-only'),
+    ...paths('ls-files', '--others', '--exclude-standard'),
+    ...paths('ls-files', '--others', '--ignored', '--exclude-standard'),
+  ].filter((p) => !p.startsWith('node_modules/') && existsSync(p) && statSync(p).isFile());
+const hashes = (paths) => new Map(paths.map((p) => [p, createHash('sha256').update(readFileSync(p)).digest('hex')]));
+
+const first = build();
+if (first.status !== 0) {
+  fail(`build fails: exit ${first.status}`);
+  process.exit(0);
+}
+for (const l of lines(`${first.out}\n${first.err}`))
+  if (/\bwarn(ing)?\b/i.test(l) && !/^(npm|pnpm|yarn) warn/i.test(l)) fail(`build warns: ${l.trim()}`);
+for (const p of paths('diff', '--name-only')) fail(`stale committed output: ${named(p)}`);
+
+const once = hashes(touched());
+build();
+const twice = hashes([...once.keys()].filter(existsSync));
+for (const [p, h] of once) if (twice.get(p) !== h) fail(`not reproducible: ${named(p)}`);

package/scripts/verify/DEPS.mjs

@@ -0,0 +1,15 @@
+// DEPS's facts: one lockfile, the manager's own, and a runtime and a manager pinned. Which
+// dependency fixes a horizon, and what the scripts call undeclared, are the hygiene subagent's.
+import { existsSync } from 'node:fs';
+import { fail, manifest } from './lib.mjs';
+
+const pkg = manifest();
+const managers = { 'package-lock.json': 'npm', 'pnpm-lock.yaml': 'pnpm', 'yarn.lock': 'yarn' };
+const locks = Object.keys(managers).filter((f) => existsSync(f));
+const named = (pkg.packageManager || '').split('@')[0];
+
+if (locks.length > 1) fail(`several lockfiles: ${locks.join(' ')}`);
+for (const lock of locks)
+  if (named && managers[lock] !== named) fail(`lockfile ${lock} does not match packageManager ${named}`);
+if (!pkg.engines) fail('no engines');
+if (!pkg.packageManager) fail('no packageManager');