@ersbeth/codelife 0.0.0-bootstrap.0 → 0.11.1

package/scripts/spec-form.mjs

@@ -0,0 +1,444 @@
+#!/usr/bin/env node
+// Holds the form of docs/spec/ and of the notes folded into it, run from the repository's root:
+// `node node_modules/@ersbeth/codelife/scripts/spec-form.mjs spec`, `note <note>` before its writing, or
+// `fold <note> [--base <rev>]` after it; `cases` prints what a plan is cut from and holds nothing.
+// A blocking rule prints `<file>:<line>: <rule>: <what is wrong>` and the exit code is 1; a report
+// prints the same way and changes nothing. No dependency, no build: built-in modules only.
+import './node-floor.mjs'
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { lf } from './text.mjs'
+
+const SPEC = 'docs/spec'
+const VERBS = ['creates', 'changes', 'retires', 'renames']
+const ENTRIES = ['README.md', 'glossary.md', 'journeys', 'principles.md', 'product', 'system', 'users.md']
+const CLOSING = ['What stays open', 'Rejected']
+const LETTER = { persona: 'P', journey: 'J', capability: 'K', rule: 'R', case: 'C' }
+const SECTIONS = {
+  capability: ['What it is for, and for whom', 'Behaviour', 'Internal design', ...CLOSING],
+  journey: ['Steps', 'Success criteria', 'Out of this journey', ...CLOSING],
+}
+
+let red = false
+const asGiven = new Set() // a note is named by its own path; a document by its path under docs/spec/
+const say = (file, line, rule, what) => console.log(`${asGiven.has(file) ? file : `${SPEC}/${file}`}:${line}: ${rule}: ${what}`)
+const block = (...a) => { red = true; say(...a) }
+
+// An address, `<path> § <heading>` in a code span — between double backticks when the heading
+// holds code, as CommonMark writes such a span. `addressed` reads either form from a match whose
+// first group is the path.
+const ADDRESS = '``([^`§]*?\\.md) §\\s+((?:[^`]|`(?!`))+?)``|`([^`§]*?\\.md) §\\s+([^`]+)`'
+const addressed = (m, at = 1) => ({
+  file: path.posix.normalize((m[at] || m[at + 2]).trim().replace(/^docs\/spec\//, '')),
+  heading: (m[at + 1] || m[at + 3]).replace(/\s+/g, ' ').trim(),
+})
+
+const git = (...args) => execFileSync('git', args, { encoding: 'utf8', maxBuffer: 1 << 28, stdio: ['ignore', 'pipe', 'ignore'] })
+
+// Every file under a directory, as paths relative to it; a `.gitkeep` is not a document.
+function walk(dir, under = '') {
+  return fs.readdirSync(path.join(dir, under), { withFileTypes: true }).flatMap((e) => {
+    const rel = path.posix.join(under, e.name)
+    return e.isDirectory() ? walk(dir, rel) : e.name === '.gitkeep' ? [] : [rel]
+  })
+}
+
+// A document: its text, its lines, and its headings outside fenced blocks — each with its level,
+// its full text, the identifier that opens it when there is one, and the heading after it.
+const read = (file, dir = SPEC) => parse(file, fs.readFileSync(path.join(dir, file), 'utf8'))
+
+function parse(file, crlf) {
+  const text = lf(crlf), lines = text.split('\n')
+  const headings = []
+  let fenced = false
+  lines.forEach((l, i) => {
+    if (/^\s*```/.test(l)) fenced = !fenced
+    const h = !fenced && /^(#{1,6}) +(.+?) *$/.exec(l)
+    if (!h) return
+    const id = /^([PJKRC]-\d+) — (.+)$/.exec(h[2])
+    headings.push({ level: h[1].length, text: h[2], id: id && id[1], title: id ? id[2] : h[2], line: i + 1 })
+  })
+  return { file, text, lines, headings }
+}
+
+const kind = (file) =>
+  /^(product|system)\//.test(file) ? 'capability' : file.startsWith('journeys/') ? 'journey' : 'entry'
+
+// The headings of one `##` section, and the line after its last one.
+function section(doc, name) {
+  const from = doc.headings.findIndex((h) => h.level === 2 && h.text === name)
+  if (from < 0) return { headings: [], start: 0, end: 0 }
+  const next = doc.headings.findIndex((h, i) => i > from && h.level <= 2)
+  const inside = doc.headings.slice(from + 1, next < 0 ? undefined : next)
+  return { headings: inside, start: doc.headings[from].line, end: next < 0 ? doc.lines.length : doc.headings[next].line - 1 }
+}
+
+// The list items between two lines, a wrapped item joined into one string.
+function items(doc, start, end) {
+  const out = []
+  for (let i = start; i < end; i++) {
+    const l = doc.lines[i]
+    if (/^- /.test(l)) out.push({ text: l.slice(2), line: i + 1 })
+    else if (/^\s+\S/.test(l) && out.length) out[out.length - 1].text += ' ' + l.trim()
+  }
+  return out
+}
+
+// A specification is in the form once its seven entries all exist. Until then it is being brought
+// to it — or /setup just gave it its README.md — and nothing blocks, or a migration could not be
+// committed; the commit that completes the seven is the first one held.
+const formed = () => ENTRIES.every((e) => fs.existsSync(path.join(SPEC, e)))
+
+// No entry beside the seven.
+function sevenEntries() {
+  for (const n of fs.readdirSync(SPEC).filter((n) => !n.startsWith('.'))) {
+    if (!ENTRIES.includes(n)) block(n, 1, 'seven-entries', 'not one of the seven entries')
+  }
+}
+
+// A capability sits at <branch>/<domain>/<capability>.md and a journey at journeys/<journey>.md:
+// the domain level is mandatory and never nested.
+function domainLevel(files) {
+  for (const f of files) {
+    const depth = f.split('/').length
+    if (/^(product|system)\//.test(f) && depth !== 3) block(f, 1, 'domain-level', 'a capability is <branch>/<domain>/<capability>.md')
+    if (f.startsWith('journeys/') && depth !== 2) block(f, 1, 'domain-level', 'a journey is journeys/<journey>.md')
+  }
+}
+
+// The entry index links every document, and links nothing that is not there.
+function indexTree(files, docs) {
+  const index = docs.get('README.md')
+  if (!index) return
+  const linked = new Map()
+  index.lines.forEach((l, i) => {
+    for (const m of l.matchAll(/\]\(([^)#\s]+\.md)(#[^)]*)?\)/g)) if (!/^[a-z]+:/.test(m[1])) linked.set(path.posix.normalize(m[1]), i + 1)
+  })
+  for (const f of files) if (f !== 'README.md' && !linked.has(f)) block('README.md', 1, 'index-tree', `${f} is in the tree and not in the index`)
+  for (const [f, line] of linked) if (!files.includes(f)) block('README.md', line, 'index-tree', `${f} is in the index and not in the tree`)
+}
+
+// A capability and a journey have exactly their `##` sections, in order; users.md and
+// principles.md end on the two closing ones.
+function sections(doc) {
+  const have = doc.headings.filter((h) => h.level === 2).map((h) => h.text)
+  const want = SECTIONS[kind(doc.file)]
+  const okay = want
+    ? have.join('\n') === want.join('\n')
+    : !['users.md', 'principles.md'].includes(doc.file) || have.slice(-2).join('\n') === CLOSING.join('\n')
+  if (!okay) block(doc.file, 1, 'sections', `expected ${(want || CLOSING).join(' · ')}${want ? '' : ' to close the document'}, found ${have.join(' · ') || 'none'}`)
+}
+
+function givenWhenThen(doc, h, end) {
+  const steps = doc.lines.slice(h.line, end).map((l) => /^(Given|When|Then) /.exec(l)).filter(Boolean).map((m) => m[1])
+  if (steps.join(' ') !== 'Given When Then') block(doc.file, h.line, 'given-when-then', `"${h.text}" reads ${steps.join(', ') || 'none of them'}`)
+}
+
+// Behaviour is rules: each `###` has at least one `####` case, and each case reads Given, When, Then
+// in that order.
+function behaviour(doc) {
+  const b = section(doc, 'Behaviour')
+  b.headings.forEach((h, i) => {
+    const next = b.headings[i + 1]
+    const end = next ? next.line - 1 : b.end
+    if (h.level === 3) {
+      if (!next || next.level !== 4) block(doc.file, h.line, 'rule-without-case', `"${h.text}" has no case`)
+    } else if (h.level === 4) givenWhenThen(doc, h, end)
+  })
+}
+
+// A heading is unique in its file, being the address of what carries no identifier.
+function duplicateHeading(doc) {
+  const seen = new Set()
+  for (const h of doc.headings) {
+    if (seen.has(h.text)) block(doc.file, h.line, 'duplicate-heading', `"${h.text}" is written twice`)
+    seen.add(h.text)
+  }
+}
+
+// Every `<path> § <heading>` address resolves, and every `- § <heading> — …` line of a
+// `## Rejected` names a heading of its own file.
+function addresses(doc, docs) {
+  const has = heading
+  for (const m of doc.text.matchAll(new RegExp(ADDRESS, 'g'))) {
+    const { file, heading } = addressed(m)
+    const line = doc.text.slice(0, m.index).split('\n').length
+    if (!docs.has(file)) block(doc.file, line, 'address', `${file} is not in the tree`)
+    else if (!has(docs.get(file), heading)) block(doc.file, line, 'address', `${file} has no heading "${heading}"`)
+  }
+  const r = section(doc, 'Rejected')
+  for (const it of items(doc, r.start, r.end)) {
+    if (!it.text.startsWith('§ ')) continue
+    const parts = it.text.slice(2).split(' — ')
+    const found = parts.some((_, n) => has(doc, parts.slice(0, n + 1).join(' — ')))
+    if (!found) block(doc.file, it.line, 'address', `no heading here is "${parts[0]}"`)
+  }
+}
+
+// What each heading of a document defines: a persona, a journey, a capability, a rule or a case.
+function defined(doc) {
+  const k = kind(doc.file)
+  const out = []
+  if (doc.file === 'users.md') for (const h of doc.headings) if (h.level === 2 && !CLOSING.includes(h.text)) out.push({ h, what: 'persona' })
+  if (k !== 'entry' && doc.headings[0] && doc.headings[0].level === 1) out.push({ h: doc.headings[0], what: k })
+  if (k === 'capability') for (const h of section(doc, 'Behaviour').headings) {
+    if (h.level === 3) out.push({ h, what: 'rule' })
+    if (h.level === 4) out.push({ h, what: 'case' })
+  }
+  return out
+}
+
+// Where each identifier is defined; `report` hears of a heading that carries none of its letter,
+// or one already taken, and of a rule or a case outside a capability's Behaviour, which nothing
+// reads.
+function definitions(docs, report = () => {}) {
+  const at = new Map()
+  for (const doc of docs.values()) {
+    const own = defined(doc)
+    for (const h of doc.headings) if (/^[RC]-/.test(h.id) && !own.some((d) => d.h === h)) report(doc.file, h.line, 'outside-behaviour', `${h.id} opens a heading outside Behaviour, where no rule or case is read`)
+    for (const { h, what } of own) {
+      if (!h.id || h.id[0] !== LETTER[what]) { report(doc.file, h.line, 'identifier', `a ${what} opens on ${LETTER[what]}-<number> — <heading>`); continue }
+      if (at.has(h.id)) report(doc.file, h.line, 'identifier', `${h.id} is also ${SPEC}/${at.get(h.id).file}:${at.get(h.id).line}`)
+      else at.set(h.id, { file: doc.file, line: h.line, title: h.title })
+    }
+  }
+  return at
+}
+
+// Everything that is cited opens its heading on an identifier of its letter, unique under
+// docs/spec/. Every identifier cited has such a heading, except one written `retired <id>` that
+// stands in a line of a `## Rejected` — a retired one bare, or `retired` beside a living one, is
+// refused — and where ` — ` follows a cited identifier, its real heading follows, except in a
+// `## Rejected`, whose lines open on the identifier alone.
+function identifiers(docs) {
+  const at = definitions(docs, block)
+  const gone = new Set()
+  const ranges = new Map([...docs.values()].map((d) => [d, section(d, 'Rejected')]))
+  for (const [doc, r] of ranges) for (const it of items(doc, r.start, r.end)) { const m = it.text.match(/^([PJKRC]-\d+) — /); if (m) gone.add(m[1]) }
+  for (const doc of docs.values()) {
+    const r = ranges.get(doc)
+    doc.lines.forEach((l, i) => {
+      if (/^#{1,6} /.test(l)) return
+      const rejected = i + 1 > r.start && i < r.end
+      for (const m of l.matchAll(/\b[PJKRC]-\d+\b/g)) {
+        const real = at.get(m[0])
+        const retired = gone.has(m[0])
+        const said = /\bretired\s+$/i.test(`${doc.lines[i - 1] ?? ''} ${l.slice(0, m.index)}`)
+        if (!rejected && (real ? said : !(said && retired))) block(doc.file, i + 1, 'identifier', real ? `${m[0]} is not retired, and "retired" stands beside it` : retired ? `${m[0]} is retired: write "retired ${m[0]}", or cite what replaced it` : `${m[0]} resolves to nothing`)
+        const after = (l.slice(m.index + m[0].length) + ' ' + doc.lines.slice(i + 1, i + 3).join(' ')).replace(/\s+/g, ' ')
+        if (!real || rejected || !after.startsWith(' — ')) continue
+        const beside = after.slice(3)
+        if (!beside.startsWith(real.title) || /^\w/.test(beside.slice(real.title.length))) block(doc.file, i + 1, 'identifier', `${m[0]} is "${real.title}", which is not what is written beside it`)
+      }
+    })
+  }
+}
+
+// A journey without a persona, and a product capability no journey walks unless its *What it is for*
+// says so on a `**No journey.**` line, block (#1035). A system capability that no product
+// capability, no other system capability and no principle cites is reported only, since a note may
+// rightly add it before the product one that uses it.
+function orphans(docs) {
+  const all = [...docs.values()]
+  const cited = (from, id) => from.some((d) => new RegExp(`\\b${id}\\b`).test(d.text))
+  const journeys = all.filter((d) => kind(d.file) === 'journey')
+  const product = all.filter((d) => d.file.startsWith('product/'))
+  for (const j of journeys) {
+    if (!/^\*\*Persona\.\*\*.*\bP-\d+\b/m.test(j.text)) block(j.file, 1, 'orphan', 'a journey without a persona')
+  }
+  for (const d of product) {
+    const cases = d.headings.filter((h) => h.level === 4 && h.id)
+    if (!cases.some((c) => cited(journeys, c.id)) && !/^\*\*No journey\.\*\* \S/m.test(d.text)) block(d.file, 1, 'orphan', 'a product capability no journey walks, and no `**No journey.**` line saying why')
+  }
+  for (const d of all.filter((x) => x.file.startsWith('system/'))) {
+    const id = d.headings[0] && d.headings[0].id
+    const users = all.filter((x) => x !== d && (kind(x.file) === 'capability' || x.file === 'principles.md'))
+    if (!id || !cited(users, id)) say(d.file, 1, 'orphan', 'a system capability nothing uses')
+  }
+}
+
+const tree = () => new Map(walk(SPEC).filter((f) => f.endsWith('.md')).map((f) => [f, read(f)]))
+const heading = (doc, text) => doc.headings.some((h) => h.text === text || h.title === text)
+
+function spec() {
+  if (!formed()) return console.log(`${SPEC}/ is not in the form — nothing is held`)
+  sevenEntries()
+  const docs = tree()
+  const files = [...docs.keys()]
+  domainLevel(files)
+  indexTree(files, docs)
+  for (const doc of docs.values()) {
+    sections(doc)
+    if (kind(doc.file) === 'capability') behaviour(doc)
+    duplicateHeading(doc)
+    addresses(doc, docs)
+  }
+  identifiers(docs)
+  orphans(docs)
+}
+
+// The lines from a `**<Name>.**` marker to the next marker or heading, inside [from, to).
+function part(doc, name, from, to) {
+  const start = doc.lines.findIndex((l, i) => i >= from && i < to && l.startsWith(`**${name}.**`))
+  if (start < 0) return null
+  let end = start + 1
+  while (end < to && !/^(\*\*[A-Z][a-z ]*\.\*\*|#{1,6} )/.test(doc.lines[end])) end++
+  return { start, end }
+}
+
+// One address of a **Target.**: what is changed, retired or renamed exists today, by identifier or
+// by `<path> § <heading>`; what is created does not.
+function target(doc, it, docs, at) {
+  const m = new RegExp(`^(${VERBS.join('|')}) (.+)$`).exec(it.text)
+  if (!m) return block(doc.file, it.line, 'note-target', `opens on none of ${VERBS.join(', ')}`)
+  if (!docs) return m
+  const address = m[2].split(' → ')[0]
+  const id = /^([PJKRC]-\d+) — (.+)$/.exec(address)
+  const by = new RegExp(`^(?:${ADDRESS})$`).exec(address)
+  const { file, heading: title } = by ? addressed(by) : {}
+  const exists = id ? at.has(id[1]) && id[2] === at.get(id[1]).title : by && docs.has(file) && heading(docs.get(file), title)
+  if (!id && !by) block(doc.file, it.line, 'note-target', 'names neither an identifier with its heading nor a `<path> § <heading>`')
+  else if (m[1] === 'creates' && exists) block(doc.file, it.line, 'note-target', 'creates what already exists')
+  else if (m[1] !== 'creates' && !exists) block(doc.file, it.line, 'note-target', `${m[1]} what does not exist today`)
+  return m
+}
+
+// A note's own shape, read against the specification before its writing: every decision has its
+// Target, its Decision and its Rejected with an `<option> — <cost>` line; every target resolves; a
+// decision on a rule, or with **Cases.**, has a Given / When / Then case, the case headings unique,
+// and one with cases names exactly one rule to write them under; a note creates a heading once;
+// every term its definition.
+function shape(doc, docs, at) {
+  const terms = part(doc, 'Terms', 0, doc.lines.length)
+  for (const it of terms ? items(doc, terms.start, terms.end) : []) if (!/^\*\*[^*]+\*\* — \S/.test(it.text)) block(doc.file, it.line, 'note-terms', 'a term with no definition')
+  const d = section(doc, 'Decisions')
+  const decisions = d.headings.filter((h) => h.level === 3)
+  const seen = new Set()
+  const created = new Map()
+  decisions.forEach((h, n) => {
+    const end = decisions[n + 1] ? decisions[n + 1].line - 1 : d.end
+    const [t, dec, rej] = ['Target', 'Decision', 'Rejected'].map((name) => part(doc, name, h.line, end))
+    for (const [name, p] of [['Target', t], ['Decision', dec], ['Rejected', rej]]) if (!p) block(doc.file, h.line, 'note-decision', `"${h.text}" has no ${name}`)
+    if (rej && !items(doc, rej.start, rej.end).some((it) => / — \S/.test(it.text))) block(doc.file, rej.start + 1, 'note-decision', 'Rejected holds no `<option> — <cost>` line')
+    const targets = t ? items(doc, t.start, t.end).map((it) => target(doc, it, docs, at)).filter(Boolean) : []
+    if (t && !targets.length) block(doc.file, t.start + 1, 'note-target', 'Target names no address')
+    const cases = d.headings.filter((c) => c.level === 4 && c.line > h.line && c.line <= end)
+    if (!cases.length && (part(doc, 'Cases', h.line, end) || targets.some((m) => /^R-\d+ — /.test(m[2])))) block(doc.file, h.line, 'note-cases', `"${h.text}" changes a behaviour and carries no case`)
+    const rules = new Set(targets.filter((m) => m[1] === 'creates' || (m[1] !== 'retires' && /^R-\d+ — /.test(m[2])))
+      .map((m) => (/^R-\d+(?= — )/.exec(m[2]) || [m[2]])[0]))
+    if (cases.length && rules.size !== 1) block(doc.file, h.line, 'note-cases', `"${h.text}" carries cases and names ${rules.size || 'no'} rule${rules.size === 1 ? '' : 's'} to write them under`)
+    for (const m of targets.filter((m) => m[1] === 'creates')) {
+      if (created.has(m[2])) block(doc.file, h.line, 'note-target', `"${h.text}" creates ${m[2]}, which "${created.get(m[2])}" already creates`)
+      else created.set(m[2], h.text)
+    }
+    cases.forEach((c, i) => {
+      givenWhenThen(doc, c, cases[i + 1] ? cases[i + 1].line - 1 : end)
+      if (seen.has(c.text)) block(doc.file, c.line, 'note-cases', `"${c.text}" is written twice`)
+      seen.add(c.text)
+    })
+  })
+}
+
+// docs/spec/ as a revision holds it, read relative to where the script runs.
+function committed(base) {
+  const files = git('ls-tree', '-r', '-z', '--name-only', base, '--', SPEC).split('\0').filter((f) => f.endsWith('.md'))
+  return new Map(files.map((f) => [f.slice(SPEC.length + 1), parse(f.slice(SPEC.length + 1), git('show', `${base}:./${f}`))]))
+}
+
+// With the note still on disk, its shape holds against the base, and the fold lost nothing: every
+// case heading of the note is under docs/spec/, the identifier the fold assigned set aside, and
+// every refusal line in a `## Rejected`
+// as written — of a former state, which the fold rewrites "in force <from> → <to>", the option;
+// no heading of the base revision is gone or reworded unless the note retires or renames it; and an
+// identifier gone stands in a `- <id> — …` line of a `## Rejected`.
+function fold(args) {
+  const base = args.includes('--base') ? args[args.indexOf('--base') + 1] : 'HEAD'
+  if (!args[0] || args[0].startsWith('--')) { console.error('fold: which note?'); process.exit(2) }
+  asGiven.add(args[0])
+  const doc = read(args[0], '')
+  if (!formed()) return block(args[0], 1, 'fold', `${SPEC}/ is not in the form — nothing is folded there`)
+  const after = [...tree().values()]
+  const now = definitions(new Map(after.map((d) => [d.file, d])))
+  const squeeze = (s) => s.replace(/\s+/g, ' ').trim()
+  const rejected = after.flatMap((d) => { const r = section(d, 'Rejected'); return items(d, r.start, r.end).map((it) => squeeze(it.text)) })
+  const d = section(doc, 'Decisions')
+  const released = new Set()
+  for (const c of d.headings.filter((h) => h.level === 4)) {
+    if (!after.some((a) => a.headings.some((h) => h.level === 4 && h.title === c.text))) block(args[0], c.line, 'fold-case', `"${c.text}" is not under ${SPEC}/`)
+  }
+  d.headings.filter((h) => h.level === 3).forEach((h, n, all) => {
+    const end = all[n + 1] ? all[n + 1].line - 1 : d.end
+    const [t, r] = ['Target', 'Rejected'].map((name) => part(doc, name, h.line, end))
+    for (const it of t ? items(doc, t.start, t.end) : []) {
+      const m = new RegExp(`^(retires|renames) (?:([PJKRC]-\\d+) — |${ADDRESS})`).exec(it.text)
+      const by = m && !m[2] && addressed(m, 3)
+      if (m) released.add(m[2] || `${by.file} § ${by.heading}`)
+    }
+    for (const it of r ? items(doc, r.start, r.end) : []) {
+      const line = squeeze(it.text)
+      const needle = / — in force since /.test(line) ? line.split(' — ')[0] : line
+      if (!rejected.some((x) => x.includes(needle))) block(args[0], it.line, 'fold-refusal', `"${needle}" is in no Rejected under ${SPEC}/`)
+    }
+  })
+  const then = committed(base)
+  const before = definitions(then)
+  shape(doc, then, before)
+  for (const [id, was] of before) {
+    const is = now.get(id)
+    if (!is && !rejected.some((x) => x.startsWith(`${id} — `))) block(was.file, was.line, 'fold-identifier', `${id} is gone and stands in no line of Rejected`)
+    if ((!is || is.title !== was.title) && !released.has(id)) block(was.file, was.line, 'fold-heading', `"${id} — ${was.title}" is gone, and the note neither retires nor renames it`)
+  }
+  for (const was of then.values()) {
+    const is = after.find((a) => a.file === was.file)
+    for (const h of is ? was.headings.filter((x) => !x.id) : []) {
+      if (!heading(is, h.text) && !released.has(`${was.file} § ${h.text}`)) block(was.file, h.line, 'fold-heading', `"${h.text}" is gone, and the note neither retires nor renames it`)
+    }
+  }
+}
+
+// Before the writing, a note's own shape against docs/spec/ as it stands: what `fold` holds it to
+// after, read while its author can still answer.
+function note(args) {
+  if (!args[0]) { console.error('note: which note?'); process.exit(2) }
+  asGiven.add(args[0])
+  const doc = read(args[0], '')
+  if (!formed()) return block(args[0], 1, 'note', `${SPEC}/ is not in the form — no note is written there`)
+  const docs = tree()
+  shape(doc, docs, definitions(docs))
+}
+
+// What a plan is cut from, one line per fact, its kind first and tab-separated: every rule and
+// case with its capability, a case with its rule; the cases each journey's steps cite; and the
+// index of every rule and case heading, the one place a heading is written. Blocks nothing,
+// writes nothing.
+function cases() {
+  if (!formed()) return console.log(`${SPEC}/ is not in the form — nothing is held`)
+  const docs = [...tree().values()].sort((a, b) => (a.file < b.file ? -1 : 1))
+  const out = { facts: [], journey: [], index: [] }
+  const cited = (doc) => {
+    const s = section(doc, 'Steps')
+    return [...new Set(doc.lines.slice(s.start, s.end).join('\n').match(/\bC-\d+\b/g))]
+  }
+  for (const doc of docs) {
+    const own = doc.headings[0] && doc.headings[0].id
+    if (kind(doc.file) === 'journey') out.journey.push(['journey', own, cited(doc).join(' ')])
+    if (kind(doc.file) !== 'capability') continue
+    let rule
+    for (const { h, what } of defined(doc).filter((d) => d.h.id && (d.what === 'rule' || d.what === 'case'))) {
+      if (what === 'rule') rule = h.id
+      out.facts.push(what === 'rule' ? ['rule', h.id, own] : ['case', h.id, own, rule])
+      out.index.push(['index', `${h.id} — ${h.title}`])
+    }
+  }
+  for (const l of Object.values(out).flat()) console.log(l.filter(Boolean).join('\t'))
+}
+
+const modes = { spec, note, fold, cases }
+const mode = modes[process.argv[2]]
+if (!mode) {
+  console.error(`usage: node ${path.basename(process.argv[1])} ${Object.keys(modes).join(' | ')}`)
+  process.exit(2)
+}
+mode(process.argv.slice(3))
+process.exitCode = red ? 1 : 0

package/scripts/spec.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// `codelife spec <identifier>` (K-43, § The specification is read by identifier): one entry of
+// docs/spec/ by its identifier, never a document whole. Run from the repository's root.
+// A heading below the title — a rule, a case, a persona — prints its text down to the next heading
+// of its level or above, a rule's cases included; a title — a capability, a journey — prints the
+// outline of its headings. Then the lines of `## Rejected` opening on the identifier; a retired one
+// prints those alone. Each part opens on `<file>:<line>`. Exit 1 when the identifier resolves to
+// nothing, 2 on a malformed one or no docs/spec/.
+import './node-floor.mjs'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { lf } from './text.mjs'
+
+const SPEC = 'docs/spec'
+const id = process.argv[2] ?? ''
+if (!/^[PJKRC]-\d+$/.test(id)) {
+  console.error('usage: codelife spec <identifier>, as R-12 or C-340')
+  process.exit(2)
+}
+if (!existsSync(SPEC)) {
+  console.error(`codelife spec: no ${SPEC}/ here — run it from the repository's root`)
+  process.exit(2)
+}
+
+const files = (d) => readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))
+  .flatMap((e) => (e.isDirectory() ? files(join(d, e.name)) : e.name.endsWith('.md') ? [join(d, e.name)] : []))
+// levels <lines> — each line's heading level, 0 for a line that is none: a `#` line inside a fenced
+// block is the block's text.
+const levels = (lines) => {
+  let fenced = false
+  return lines.map((l) => (/^\s*```/.test(l) ? ((fenced = !fenced), 0) : fenced ? 0 : (l.match(/^(#{1,6}) /) ?? [, ''])[1].length))
+}
+const out = []
+for (const f of files(SPEC)) {
+  const lines = lf(readFileSync(f, 'utf8')).split('\n'), heads = levels(lines), level = (_, i) => heads[i]
+  const at = lines.findIndex((l, i) => level(l, i) && l.slice(level(l, i) + 1).startsWith(`${id} — `))
+  if (at >= 0) {
+    const own = level(lines[at], at)
+    const end = lines.findIndex((l, i) => i > at && level(l, i) && level(l, i) <= own)
+    const body = own === 1
+      ? lines.filter((l, i) => i >= at && level(l, i) > 1 && level(l, i) <= 4)
+      : lines.slice(at + 1, end < 0 ? undefined : end)
+    out.push(`${f}:${at + 1}`, lines[at], ...body)
+    while (out.at(-1) === '') out.pop()
+  }
+  let rejected = false
+  lines.forEach((l, i) => {
+    if (level(l, i)) rejected = l === '## Rejected'
+    if (rejected && l.startsWith(`- ${id} — `)) out.push(`${f}:${i + 1}: ${l}`)
+  })
+}
+if (!out.length) {
+  console.error(`codelife spec: ${id} resolves to nothing under ${SPEC}/`)
+  process.exit(1)
+}
+console.log(out.join('\n'))

package/scripts/tags.mjs

@@ -0,0 +1,27 @@
+// A release's tag, the one place its spelling is written (R-88): `codelife release cut` writes it,
+// scripts/changelog.mjs and `codelife overview` read whether a version is tagged, and
+// `codelife release prep` finds a line's last tag. Built-in modules only: changelog.mjs runs in a
+// hook of the repository it was written into.
+import './node-floor.mjs'
+
+// The tag a release writes: an annotated `v<version>`, in every repository.
+export const tagFor = (version) => `v${version}`
+
+// The tags that say <version> is released: `v<version>`, or `<name>--v<version>` for a repository
+// tagged that way before every tag was `v` (codelife up to 0.10.0), its name read without an npm
+// scope; another name's tag at that version says nothing.
+export const spellings = (version, name = '') => [tagFor(version), ...(name ? [`${name.split('/').pop()}--v${version}`] : [])]
+
+// The patterns `git describe --match` takes for a line's last tag: both spellings above, and the
+// `r<version>` tags older lines spelled (R-242), read as history and never written.
+export const PATTERNS = ['v[0-9]*', '*--v[0-9]*', 'r[0-9]*']
+
+// The version a release tag names, whichever spelling it has.
+export const versionOf = (tag) => tag.replace(/^.*--v/, '').replace(/^[vr]/, '')
+
+// semver's order, a prerelease before its release: 1.0.0-rc.1 < 1.0.0 (#1068).
+const parse = (v) => { const [core, pre] = v.split(/-(.*)/); return { n: core.split('.').map(Number), pre } }
+export const compare = (a, b) => {
+  const [x, y] = [parse(a), parse(b)]
+  return x.n[0] - y.n[0] || x.n[1] - y.n[1] || x.n[2] - y.n[2] || (x.pre === undefined) - (y.pre === undefined) || (x.pre ?? '').localeCompare(y.pre ?? '', 'en', { numeric: true })
+}

package/scripts/target/target-app.md

@@ -0,0 +1,134 @@
+# A conforming application — on top of the base
+
+Everything in `target-base.md` applies here in full; this file adds the toolchain, and nothing it
+says replaces a base row.
+
+An application is a repository nothing installs. That is the only thing distinguishing it from a
+library here, and it decides every row below: the build is a bundle rather than a `pack`, the
+output is not versioned because no consumer resolves it, and the dev server is the application
+itself rather than a page written to exercise something else.
+
+**This file describes a toolchain, never a stack.**
+The framework, the router, the CSS approach, the i18n and the deployment target are decided at each
+application's first port and recorded in that repository's `CLAUDE.md`. A choice three applications
+have made the same way may move here; until then, a row naming one would make CONF report a drift
+no skill remedies.
+
+## Package manager
+
+pnpm, pinned in `packageManager`, with `minimumReleaseAge` set explicitly in `pnpm-workspace.yaml`,
+on the library's rule for both: an application with in-house dependencies
+is a workspace — `pnpm-workspace.yaml` with `packages: [submodules/*]`, each in-house library a
+**root** submodule initialised non-recursively, and `pnpm.overrides` sending every in-house package
+to `workspace:*` for as long as those libraries are not published.
+
+## Toolchain
+
+Vite+, invoked as `vp`: the `vite-plus` devDependency, installed with the repository's other
+dependencies and run through its scripts — not a machine binary. One `vite.config.ts` at the root,
+carrying the plugin of the framework the application uses — the one row of this file whose content
+the repository supplies, which is why the package's vite preset serves a library and
+none serves an application: a template naming a framework would be the stack this file refuses to name.
+
+The target commits to the **configuration surface** and the `vp` scripts, not to Vite+ itself,
+which is beta: if it stalls, the same configuration runs under Vite, Vitest, Oxlint and Oxfmt
+installed separately, which changes this file and not the target.
+
+## Build
+
+`vp build`, Rolldown behind it, and `vp preview` to serve what it produced. The output is **not
+versioned** — nothing installs an application from the forge, so a build in the history would be a
+generated artefact no consumer ever reads, going stale in every branch.
+
+Correspondingly, the contract of a conforming application declares **no `generated`** entry. That
+is a value, not an omission: `/audit`'s derived-file lens reads it and reports nothing rather than
+reporting an unknown.
+
+## Types, lint, format
+
+The library's rules, from the same source: the package's `presets/tsconfig.json`, which the
+`tsconfig.json` template extends for both kinds, and Oxlint and Oxfmt through
+`vp check`. They are stated here by reference and not restated, so that one flag never has two
+descriptions to be at odds.
+
+## Tests
+
+Vitest through `vp test` for the pure modules — computations, state, anything that runs without a
+document — with `test/` mirroring `src/` as it does in a library.
+
+**Browser tests are set up by default**, Vitest browser mode on Playwright Chromium, and the
+start-up smoke written when the repository was ported is their first case: the application mounts
+without a console error. An application's interesting failures are in the browser, so a repository
+where a browser test is an afternoon's setup away is one where nobody writes the first one.
+
+The characterisation tests of the port — that smoke, and the pure modules captured by snapshot —
+are kept as the **floor**: they describe what the application already did, so they are extended,
+never weakened to let a change pass.
+
+## Dev mode
+
+`vp dev`, serving the application itself. There is no `playground/`: a library needs a page written
+to exercise it, and an application is one.
+
+## Hooks
+
+The base's three, unchanged, and that is the whole row: an application versions no build, so its
+`pre-commit` builds nothing.
+
+## MCP server
+
+A conforming application carries **no** `.mcp.json`: the browser server serves only the agent, so
+the plugin declares it, in its manifest, pinned to an exact version, and it asks for the approval a
+project's servers get when the folder is trusted. The demo credentials the server substitutes sit in
+`.claude/codelife.secrets.env`, git-ignored, the path the plugin fixes.
+
+`.claude/settings.local.json` is **not** part of the target: it is not versioned and it is the
+user's, so per-tool permissions stay theirs to grant.
+
+## Application facts in the contract
+
+A conforming application's contract carries an `app:` block — the facts about *this* application
+that the plugin cannot decide and that differ in every repository:
+
+```markdown
+app:
+  url: <where the running application is reached, port included>
+  start: <the command that starts it, and the directory it runs in when that is not the root>
+```
+
+One block rather than two top-level fields: it is present exactly when `kind: app`, which is one
+validation rule instead of two, and the two facts are meaningless apart — a URL nobody starts starts
+nothing. The demo credentials are no fact of the contract: they sit in `.claude/codelife.secrets.env`,
+the path the plugin's browser server reads.
+
+The block is written once by `/setup` and read by whatever drives the running application.
+
+## Per application, at the first port
+
+The framework, the router, the CSS approach, the i18n and the deployment target — decided in that
+repository and recorded in its `CLAUDE.md`, not here. `codelife port prep` does not measure them, and
+an application answering each of them differently is conforming.
+
+## Standard scripts
+
+The base's five names, with an application's commands, verbatim — `test:one` takes the file as its
+argument, and `verify:release` is the push tier itself, which the `pre-push` hook and `/release` run
+alone on a version tag:
+
+| Script | Runs |
+|---|---|
+| `verify:commit` | `vp check && vp test` |
+| `verify:push` | `vp check && vp test && vp test --browser && vp build` |
+| `verify:release` | `pnpm verify:push` |
+| `test:all` | `vp test` |
+| `test:one` | `vp test` |
+
+**Five names, not six.** The browser suite is a command inside the push tier and never a sixth
+standard script: the base fixes those five for every kind, so a sixth would be a base change
+reaching `none` and `lib` too, for a suite neither of them has. A repository keeping a
+`test:browser` of its own for convenience is neither required to nor forbidden from doing so — it
+is simply not what a skill invokes.
+
+`--browser` and `build` are in the push tier and not the commit tier, on the library's reasoning:
+the commit tier runs on every commit, and a browser run plus a bundle there costs more than it
+catches, while a push is what makes the result someone else's problem.