rvlib-shipkit 0.38.0 → 1.0.0

package/src/collections/pings.ts

@@ -4,10 +4,14 @@
 // gitignored territory); a repo without node_modules gets NO pings rather
 // than re-fired backlogs (no persistence = no dedup = stay silent). For
 // ask-backed items the marker is the ask file's own `pinged:` field — the
-// SAME once-ever guarantee every other ping path uses.
+// SAME once-ever guarantee every other ping path uses. A hub in a linked
+// worktree is a side checkout (a test hub, a branch under review): it never
+// notifies and never marks, so the phone and the markers belong to the main
+// checkout's hub alone.
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import { markPinged } from '../asks/asks-queue.ts'
+import { isLinkedWorktree } from '../core/git-root.ts'
 import type { NeedItem } from './collection-types.ts'
 
 export type PingIo = {
@@ -24,13 +28,33 @@ export type PingIo = {
 
 const stateDir = (root: string): string | null => (existsSync(join(root, 'node_modules')) ? join(root, 'node_modules', '.cache', 'shipkit') : null)
 
-const loadPinged = (root: string): Set<string> | null => {
+/** the state file's shape. It is bumped when the IDS a surface emits move,
+ *  because dedup marks are worthless under a name nothing emits any more:
+ *  v1 was a bare array, written while a repo health row was one wire line of
+ *  STATUS.md; v2 arrived with one resource per gate check. */
+const STATE_VERSION = 2
+
+/** `adopt` = the marks in hand cannot be compared to the ids in front of us,
+ *  so this tick MARKS the machine-owned reds and notifies about none of them.
+ *  The alternative is the whole backlog firing again, at once, on his phone. */
+type PingState = { ids: Set<string>; adopt: boolean }
+
+const loadPinged = (root: string): PingState | null => {
     const dir = stateDir(root)
     if (dir == null) return null
+    const file = join(dir, 'pinged.json')
+    // no file at all = a repo that never pinged: there is no backlog to
+    // protect, and its first tick is the normal first tick
+    if (!existsSync(file)) return { ids: new Set(), adopt: false }
     try {
-        return new Set(JSON.parse(readFileSync(join(dir, 'pinged.json'), 'utf8')) as string[])
+        const raw = JSON.parse(readFileSync(file, 'utf8')) as unknown
+        if (Array.isArray(raw)) return { ids: new Set(raw as string[]), adopt: true }
+        const s = raw as { v?: number; ids?: string[] }
+        return { ids: new Set(s.ids ?? []), adopt: s.v !== STATE_VERSION }
     } catch {
-        return new Set()
+        // unreadable marks say nothing about what he has already seen, and
+        // the safe direction is silence, never a burst
+        return { ids: new Set(), adopt: true }
     }
 }
 
@@ -38,28 +62,30 @@ const savePinged = (root: string, ids: Set<string>): void => {
     const dir = stateDir(root)
     if (dir == null) return
     mkdirSync(dir, { recursive: true })
-    writeFileSync(join(dir, 'pinged.json'), JSON.stringify([...ids].sort()))
+    writeFileSync(join(dir, 'pinged.json'), JSON.stringify({ v: STATE_VERSION, ids: [...ids].sort() }))
 }
 
 /** one tick: ping ONCE for the batch of never-pinged red items, mark them.
  *  Returns the pinged ids (empty = silence). */
 export function pingTick(root: string, asksDir: string, needs: NeedItem[], io: PingIo): string[] {
-    const pinged = loadPinged(root)
-    if (pinged == null) return [] // no persistence, no pings — never re-fire a backlog
+    if (isLinkedWorktree(root)) return []
+    const state = loadPinged(root)
+    if (state == null) return [] // no persistence, no pings — never re-fire a backlog
     const fresh: NeedItem[] = []
     for (const n of needs) {
         if (n.severity !== 'red') continue
         if (n.askOwned === true) continue // the covering ask's pinged: field already fired the once-ever ping
         if (n.collection === 'asks') {
-            // ask file owns the once-ever marker (shared with agent pings)
+            // an ask's marker lives in the ask FILE and survives any id move,
+            // so it is never adopted: a new ask still fires on a migrating tick
             const file = n.id.replace(/^ask:/, '')
             if (markPinged(join(root, asksDir), file)) fresh.push(n)
-        } else if (!pinged.has(n.id)) {
-            pinged.add(n.id)
-            fresh.push(n)
+        } else if (!state.ids.has(n.id)) {
+            state.ids.add(n.id)
+            if (!state.adopt) fresh.push(n)
         }
     }
-    savePinged(root, pinged)
+    savePinged(root, state.ids)
     if (fresh.length === 0) return []
     const head = fresh.slice(0, 3).map((n) => n.text.slice(0, 80)).join(' · ')
     const message = `${fresh.length} new item(s) need you: ${head}${fresh.length > 3 ? ' · …' : ''}${io.link != null ? ` → ${io.link}` : ''}`

package/src/collections/posts.ts

@@ -1,4 +1,4 @@
-// social-posts collection — projects `.rv-social/<channel>/` post files
+// social-posts collection — projects `.shipkit/social/<channel>/` post files
 // (contract v2) into the needs feed. Status-aware: rejected/posted history
 // stays on disk as training data and never floods the feed. Drafts-as-rolls:
 // variants are sibling files `<slug>.a.md`, `<slug>.b.md`; picking one flips
@@ -43,7 +43,7 @@ export function parsePostFile(dir: string, channel: string, file: string): PostF
 }
 
 export function listPosts(root: string): PostFile[] {
-    const social = join(root, '.rv-social')
+    const social = join(root, '.shipkit/social')
     if (!existsSync(social)) return []
     const out: PostFile[] = []
     for (const ch of readdirSync(social)) {
@@ -71,12 +71,17 @@ export function socialPostsCollection(root: string): Collection {
                 return lines.length > 0 ? lines.slice(-3) : undefined
             }
             for (const [key, variants] of bySlug) {
-                const fileOf = (v: PostFile): string => `.rv-social/${v.channel}/${v.file}`
+                const fileOf = (v: PostFile): string => `.shipkit/social/${v.channel}/${v.file}`
+                // the row is the post, the venue is the slot beside it
+                const place = { label: key.split('/').slice(1).join('/'), slot: variants[0]!.channel }
                 const missing = variants.filter((v) => v.status == null)
                 if (missing.length > 0) {
                     out.push({
                         id: `post:${key}:invalid`,
+                        ...place,
                         text: `${key} — missing/invalid status: frontmatter (${missing.map((v) => v.file).join(', ')})`,
+                        type: 'post',
+                        path: fileOf(missing[0]!),
                         severity: 'red',
                         file: fileOf(missing[0]!),
                     })
@@ -86,7 +91,10 @@ export function socialPostsCollection(root: string): Collection {
                 if (picked != null) {
                     out.push({
                         id: `post:${key}:topost`,
+                        ...place,
                         text: `${key} — picked, waiting to be POSTED (copy → post → paste the URL)`,
+                        type: 'post',
+                        path: fileOf(picked),
                         severity: 'red',
                         artifact: { copy: postSection(picked.body) },
                         verbs: ['paste-proof', 'rate'],
@@ -100,7 +108,10 @@ export function socialPostsCollection(root: string): Collection {
                 if (drafts.length > 0) {
                     out.push({
                         id: `post:${key}:pick`,
+                        ...place,
                         text: `${key} — ${drafts.length} draft(s), pick one`,
+                        type: 'post',
+                        path: fileOf(drafts[0]!),
                         severity: 'yellow',
                         verbs: ['pick', 'rate'],
                         candidates: drafts.map((v) => ({ id: v.file, label: v.variant ?? 'draft', hint: postSection(v.body).slice(0, 200) })),
@@ -114,7 +125,12 @@ export function socialPostsCollection(root: string): Collection {
                 const shown = posted ?? variants[0]!
                 out.push({
                     id: `post:${key}:${posted != null ? 'posted' : 'rejected'}`,
+                    ...place,
                     text: `${key} — ${posted != null ? `posted${posted.posted != null ? ` (${posted.posted})` : ''}` : 'rejected'}`,
+                    type: 'post',
+                    path: fileOf(shown),
+                    // posted and rejected are history: visible, never loud
+                    state: 'quiet',
                     file: fileOf(shown),
                     remarks: feedback(shown),
                 })

package/src/collections/providers.ts

@@ -5,9 +5,9 @@
 // asks READ path never minting asks/ on a repo without one. Dedup doctrine
 // : dedup = acted-on once, NEVER hidden — an
 // ask-covered missing cred still shows RED in secrets with a pointer to the
-// ask; verbs and pings stay with the ask. Each wire line of STATUS.md lives
-// in exactly ONE collection: cred probe lines in secrets, everything else
-// in repo health.
+// ask; verbs and pings stay with the ask. No provider reads STATUS.md: a
+// verdict comes from the run record, which gate runs and health passes both
+// write, through the checks collection (collections/checks.ts).
 import { existsSync, readFileSync } from 'fs'
 import { join } from 'path'
 import { isStale } from '../assets/gen/derived.ts'
@@ -19,13 +19,19 @@ import { assetDir, listRolls, readPick } from '../assets/roll-workspace.ts'
 import type { healIdentity } from '../assets/run-assets.ts'
 import { doneAsks, openAsks } from '../asks/asks-queue.ts'
 import { evaluateContracts } from '../contracts/contracts-engine.ts'
-import { parseWireOutput } from '../core/wire.ts'
+import { CheckCtx } from '../core/check-ctx.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { activeContracts, contractsConfigFrom } from '../contracts/apply-contracts.ts'
-import type { Collection, Instance } from './collection-types.ts'
+import type { CheckFacts, Collection, Instance } from './collection-types.ts'
+import { mdBody } from './md-body.ts'
 import { socialPostsCollection } from './posts.ts'
+import { assetState, secretState, type SecretProbe } from './state-rules.ts'
+import { reflectionsCollection } from './reflections.ts'
+import { testsCollection } from './tests.ts'
+import { checksCollection } from './checks.ts'
+import { LAYOUT } from '../core/layout.ts'
 
-const askDirOf = (root: string, c: RepoConfig): string => join(root, c.asks?.dir ?? 'asks')
+const askDirOf = (root: string, c: RepoConfig): string => join(root, c.asks?.dir ?? LAYOUT.asks)
 // read path must not mint an asks/ dir (listAsks mkdirs on read)
 const openAsksSafe = (root: string, c: RepoConfig): ReturnType<typeof openAsks> => {
     const dir = askDirOf(root, c)
@@ -34,21 +40,81 @@ const openAsksSafe = (root: string, c: RepoConfig): ReturnType<typeof openAsks>
 
 const CRED_LINE = /cred ([a-z0-9-]+\/[a-z0-9-]+\/[a-z0-9-]+) missing/
 
-/** STATUS.md's check output, regrouped: one item per ok/WARN/FAIL wire line
- *  with its indented fix: pointers riding along. The writer's markdown
- *  wrapper (comment, title, verdict, fences) parses as notes and drops out. */
-type WireItem = { kind: 'ok' | 'warn' | 'fail'; text: string; fixes: string[] }
-const statusWire = (root: string): WireItem[] => {
-    const p = join(root, 'STATUS.md')
-    if (!existsSync(p)) return []
-    const items: WireItem[] = []
-    for (const l of parseWireOutput(readFileSync(p, 'utf8'))) {
-        if (l.kind === 'ok' || l.kind === 'warn' || l.kind === 'fail') items.push({ kind: l.kind, text: l.text, fixes: [] })
-        else if ((l.kind === 'fix-warn' || l.kind === 'fix-fail') && items.length > 0) items[items.length - 1]!.fixes.push(l.text)
+/** the secret name as a WHOLE token in a wire line: `rv/npm/token` must not
+ *  read itself in a line about `rv/npm/token-2` */
+const namesSecret = (text: string, name: string): boolean =>
+    new RegExp(`(^|[^\\w/-])${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[^\\w/-])`).test(text)
+
+/** what a secret row reads off one check: the last recorded verdict and the
+ *  lines that run printed, the fields of the checks collection's own facts */
+export type CheckVerdict = Pick<CheckFacts, 'checkId' | 'status' | 'lastLines' | 'lastAt' | 'measuredAt' | 'keepsUntil' | 'ttl'>
+
+/** a check's printed lines, one item per WARN/FAIL/skip line with its
+ *  indented fix: pointers riding along */
+type PrintedLine = { kind: 'fail' | 'warn' | 'skip' | 'other'; text: string; fixes: string[] }
+const printed = (lines: string[]): PrintedLine[] => {
+    const out: PrintedLine[] = []
+    for (const raw of lines) {
+        const fix = raw.match(/^\s+fix: (.*)$/)
+        if (fix != null) { out.at(-1)?.fixes.push(fix[1]!); continue }
+        const m = raw.match(/^(FAIL: |WARN |skip: )(.*)$/)
+        const kind = m == null ? 'other' : m[1] === 'FAIL: ' ? 'fail' : m[1] === 'WARN ' ? 'warn' : 'skip'
+        out.push({ kind, text: m == null ? raw.replace(/^ok: /, '') : m[2]!, fixes: [] })
+    }
+    return out
+}
+
+/** every secret some check proved MISSING, with the line that said so. A
+ *  check that cannot block has its FAIL demoted to a WARN on the wire, so a
+ *  WARN counts too when the run record says the check itself failed */
+const missingFrom = (verdicts: CheckVerdict[]): Map<string, PrintedLine> => {
+    const out = new Map<string, PrintedLine>()
+    for (const v of verdicts)
+        for (const l of printed(v.lastLines)) {
+            if (!(l.kind === 'fail' || (l.kind === 'warn' && v.status === 'fail'))) continue
+            const name = l.text.match(CRED_LINE)?.[1]
+            if (name != null && !out.has(name)) out.set(name, l)
+        }
+    return out
+}
+
+/** `just now`, `4m ago`, `3h ago`, `2d ago` */
+const ago = (ms: number): string => {
+    const m = Math.max(0, Math.round(ms / 60_000))
+    if (m === 0) return 'just now'
+    return `${m < 60 ? `${m}m` : m < 60 * 48 ? `${Math.round(m / 60)}h` : `${Math.round(m / 1440)}d`} ago`
+}
+
+/** what the probing check's last recorded run says about one present secret,
+ *  and the plain words the row carries for it */
+export function probeOf(name: string, probedBy: string | undefined, verdicts: Map<string, CheckVerdict>, now: number): { probe: SecretProbe; words: string; md?: string } {
+    if (probedBy == null) return { probe: 'none', words: 'no check probes this secret' }
+    const v = verdicts.get(probedBy)
+    if (v == null) return { probe: 'warn', words: `probed by ${probedBy}, which is not a check of this repo` }
+    if (v.status == null) return { probe: 'unmeasured', words: `its probe ${probedBy} never ran here` }
+    const lines = printed(v.lastLines)
+    const md = v.lastLines.length > 0 ? wireMd(v.lastLines.map((l) => l.trim())) : undefined
+    if (v.status === 'skip') return { probe: 'unmeasured', words: `its probe ${probedBy} was skipped`, md }
+    const unmeasured = lines.find((l) => l.kind === 'skip' && namesSecret(l.text, name))
+    if (unmeasured != null) return { probe: 'unmeasured', words: `${probedBy} did not check it: ${unmeasured.text}`, md }
+    if (v.status === 'fail') {
+        const why = lines.find((l) => l.kind === 'fail') ?? lines.find((l) => l.kind === 'warn')
+        return { probe: 'fail', words: `its probe ${probedBy} failed${why != null ? `: ${why.text}` : ''}`, md }
     }
-    return items
+    if (v.status === 'warn') {
+        const why = lines.find((l) => l.kind === 'warn')
+        return { probe: 'warn', words: `its probe ${probedBy} warned${why != null ? `: ${why.text}` : ''}`, md }
+    }
+    const at = v.measuredAt ?? v.lastAt ?? now
+    if (v.keepsUntil != null && now > v.keepsUntil)
+        return { probe: 'stale', words: `last checked ${ago(now - at)} by ${probedBy}, older than its ${v.ttl} ttl`, md }
+    return { probe: 'pass', words: `checked ${ago(now - at)} by ${probedBy}`, md }
 }
 
+/** a wire line as ONE path segment. The line text is the instance id too,
+ *  so equal slugs mean equal lines and nothing distinct collides */
+const slug = (t: string): string => t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 72)
+
 /** wire lines re-rendered as a fenced block for an instance's md */
 const wireMd = (lines: string[]): string => `\`\`\`\n${lines.join('\n')}\n\`\`\``
 
@@ -58,14 +124,20 @@ export function asksCollection(root: string, c: RepoConfig): Collection {
         title: 'asks',
         media: 'text',
         list: async () => {
-            const rel = c.asks?.dir ?? 'asks'
+            const rel = c.asks?.dir ?? LAYOUT.asks
             const open = openAsksSafe(root, c).map((a): Instance => ({
                 id: `ask:${a.file}`,
                 text: `${a.title}${a.kind !== '' ? ` (${a.kind})` : ''}`,
+                // the tree carries the title and puts the kind in its own
+                // slot, so a column of asks reads as a column of kinds
+                label: a.title,
+                slot: a.kind !== '' ? a.kind : undefined,
+                type: 'ask' as const,
+                path: `${rel}/${a.file}`,
                 severity: 'red' as const,
                 verbs: ['done' as const, 'paste-proof' as const],
                 file: `${rel}/${a.file}`,
-                md: askMd(join(root, rel, a.file)),
+                md: mdBody(join(root, rel, a.file)),
                 remarks: lastRemarks(join(root, rel, a.file)),
             }))
             // the done/ archive rides along QUIET (no severity) — past answers
@@ -73,8 +145,13 @@ export function asksCollection(root: string, c: RepoConfig): Collection {
             const done = doneAsks(askDirOf(root, c)).map((a): Instance => ({
                 id: `ask:done/${a.file}`,
                 text: `${a.title}${a.kind !== '' ? ` (${a.kind})` : ''}`,
+                label: a.title,
+                slot: 'done',
+                type: 'ask' as const,
+                path: `${rel}/done/${a.file}`,
+                state: 'quiet' as const,
                 file: `${rel}/done/${a.file}`,
-                md: askMd(join(root, rel, 'done', a.file)),
+                md: mdBody(join(root, rel, 'done', a.file)),
                 remarks: lastRemarks(join(root, rel, 'done', a.file)),
             }))
             return [...open, ...done]
@@ -82,19 +159,6 @@ export function asksCollection(root: string, c: RepoConfig): Collection {
     }
 }
 
-// a card, not a document dump — the cut is loud (…) so a clamped card never
-// passes for the whole truth file
-const MD_CAP = 4000
-
-/** the ask file's markdown body: frontmatter stripped, trimmed, capped */
-const askMd = (path: string): string | undefined => {
-    if (!existsSync(path)) return undefined
-    const body = readFileSync(path, 'utf8').replace(/^---\n[\s\S]*?\n---\n?/, '').trim()
-    if (body === '') return undefined
-    // code-point slice — a UTF-16 cut can strand half a surrogate pair
-    return body.length > MD_CAP ? `${[...body].slice(0, MD_CAP).join('')}…` : body
-}
-
 /** the latest dated remark lines from a file's tail, the boot briefing */
 const lastRemarks = (path: string, max = 3): string[] | undefined => {
     if (!existsSync(path)) return undefined
@@ -102,55 +166,73 @@ const lastRemarks = (path: string, max = 3): string[] | undefined => {
     return lines.length > 0 ? lines.slice(-max) : undefined
 }
 
-/** repo-declared secrets (repo.config `creds:`) + cred FAIL lines from
- *  STATUS.md — the tile carries the mint artifact as data. EVERY declared
+export type CredsOpts = {
+    /** injected by tests; production reads the checks collection, which is
+     *  the run record every gate run and health pass writes */
+    verdicts?: () => Promise<CheckVerdict[]>
+    now?: () => number
+}
+
+/** the verdicts a secret row reads, off the checks collection's own rows, so
+ *  a secret and its probing check can never disagree */
+export const verdictsOf = async (checks: Collection): Promise<CheckVerdict[]> =>
+    (await checks.list()).flatMap((i) => (i.check == null ? [] : [i.check]))
+
+/** a declared service, in parentheses after the name */
+const named = (name: string, service: string | undefined): string => (service != null ? `${name} (${service})` : name)
+
+/** repo-declared secrets (repo.config `creds:`) plus every secret a check
+ *  proved missing. The tile carries the mint artifact as data. EVERY declared
  *  cred is listed. Missing + unclaimed = red with the set verb + artifact;
- *  missing + ask-covered = STILL red (never hidden), no verbs — the text
- *  points at the ask that owns the action. The probe FAIL line (+ its fix:
- *  pointers) rides the instance's md, never a health line.
- *  Declared-and-present creds show QUIET, the vault is consultable. */
-export function credsCollection(root: string, c: RepoConfig): Collection {
+ *  missing + ask-covered = STILL red (never hidden), no verbs: the text
+ *  points at the ask that owns the action. The line that proved it missing
+ *  (+ its fix: pointers) rides the instance's md, never a health line.
+ *  A present secret wears the verdict of the check that probes it
+ *  (`probedBy`), read from the run record (state-rules.ts secretState) */
+export function credsCollection(root: string, c: RepoConfig, o: CredsOpts = {}): Collection {
     return {
         id: 'creds',
         title: 'secrets',
         media: 'pointer',
         list: async () => {
-            const rel = c.asks?.dir ?? 'asks'
+            const rel = c.asks?.dir ?? LAYOUT.asks
             const asks = openAsksSafe(root, c)
             const coveringAsk = (name: string): { file: string } | undefined =>
                 asks.find((a) => a.title.toLowerCase().includes(name.split('/')[1] ?? name))
-            // only a FAIL probe proves missing — a WARN/narrative mention never reds
-            const probes = new Map<string, WireItem>()
-            for (const i of statusWire(root)) {
-                if (i.kind !== 'fail') continue
-                const name = i.text.match(CRED_LINE)?.[1]
-                if (name != null && !probes.has(name)) probes.set(name, i)
-            }
+            const verdicts = await (o.verdicts ?? (() => verdictsOf(checksCollection(root, c))))()
+            const now = (o.now ?? Date.now)()
+            const missing = missingFrom(verdicts)
+            const byId = new Map(verdicts.map((v) => [v.checkId, v]))
             const out: Instance[] = []
-            for (const [name, probe] of probes) {
+            for (const [name, line] of missing) {
                 const decl = (c.creds ?? []).find((d) => d.name === name)
-                const md = wireMd([`FAIL: ${probe.text}`, ...probe.fixes.map((f) => `fix: ${f}`)])
+                const md = wireMd([`FAIL: ${line.text}`, ...line.fixes.map((f) => `fix: ${f}`)])
                 const ask = coveringAsk(name)
                 if (ask != null)
                     // dedup = acted-on once, never hidden: the ask keeps the
                     // verbs and the ping; the cred still shows RED here
                     out.push({
                         id: `cred:${name}`,
-                        text: `${name} missing${decl?.service != null ? ` — ${decl.service}` : ''} — ask ${rel}/${ask.file} owns this`,
+                        text: `${named(name, decl?.service)} missing, ask ${rel}/${ask.file} owns this`,
+                        ...credPlace(name, true),
                         severity: 'red',
                         md,
                         askOwned: true,
                     })
                 else out.push({ ...credInstance(name, c.credsCommand, decl), md })
             }
-            // every declared cred not proven missing is a quiet instance —
-            // present secrets carry no severity and no copy command (nothing
-            // to run), just the mint pointer when one is declared
+            // every declared cred not proven missing is present: no copy
+            // command (nothing to run), the mint pointer when one is declared,
+            // and the colour of what its probe last proved
             for (const d of c.creds ?? []) {
-                if (probes.has(d.name)) continue
+                if (missing.has(d.name)) continue
+                const p = probeOf(d.name, d.probedBy, byId, now)
                 out.push({
                     id: `cred:${d.name}`,
-                    text: `${d.name}${d.service != null ? ` — ${d.service}` : ''}`,
+                    text: `${named(d.name, d.service)} present, ${p.words}`,
+                    ...credPlace(d.name, false),
+                    ...secretState({ missing: false, probe: p.probe }),
+                    md: p.md,
                     artifact: d.mintUrl != null ? { url: d.mintUrl } : undefined,
                 })
             }
@@ -161,9 +243,16 @@ export function credsCollection(root: string, c: RepoConfig): Collection {
 
 // the store command is repo config DATA (`credsCommand` template) — the lib
 // never names any particular secret manager
+// a secret has no file: the name is already slash shaped, so a virtual root
+// groups it by vendor for free
+const credPlace = (name: string, missing: boolean): Pick<Instance, 'type' | 'path' | 'virtual' | 'label' | 'slot'> =>
+    // the tree row is the NAME, and present or missing is the slot beside it
+    ({ type: 'secret', path: `secrets/${name}`, virtual: true, label: name, slot: missing ? 'missing' : 'present' })
+
 const credInstance = (name: string, cmdTemplate: string | undefined, decl?: { service?: string; mintUrl?: string; steps?: string[] }): Instance => ({
     id: `cred:${name}`,
-    text: `${name} missing${decl?.service != null ? ` — ${decl.service}` : ''}`,
+    text: `${named(name, decl?.service)} missing`,
+    ...credPlace(name, true),
     severity: 'red',
     artifact: { copy: cmdTemplate?.replaceAll('{name}', name), url: decl?.mintUrl, steps: decl?.steps },
     verbs: ['set'],
@@ -185,7 +274,7 @@ export function mediaKitCollection(root: string, kit: ResolvedKit | null, heal:
             const idn = await heal(root)
             const out: Instance[] = []
             if (idn.state === 'blocked')
-                out.push({ id: 'media:identity', text: `identity — ${idn.detail ?? 'blocked'}`, severity: 'red', href: '/#identity-logo', verbs: ['pick'] })
+                out.push({ id: 'media:identity', text: `identity — ${idn.detail ?? 'blocked'}`, type: 'asset', path: 'assets/identity', virtual: true, severity: 'red', href: '/#identity-logo', verbs: ['pick'] })
             if (kit == null) return out
             const notes = assetNotes(root)
             for (const f of allAssets(kit)) {
@@ -195,32 +284,45 @@ export function mediaKitCollection(root: string, kit: ResolvedKit | null, heal:
                 const base: Instance = {
                     id: `media:${f.asset.id}`,
                     text: f.asset.id,
+                    // the roll count is the one fact a row of assets is read for
+                    slot: rolls.length > 0 ? `${rolls.length} roll${rolls.length === 1 ? '' : 's'}` : manual ? 'manual' : undefined,
+                    type: 'asset',
+                    // the roll workspace dir, which is where this asset's
+                    // bytes actually live: on the kit file they all collide
+                    // on one node
+                    path: `${kit.workspace}/${f.asset.id}`,
                     href: `/#${f.asset.id}`,
                     // image kinds only — /api/thumb serves raw roll bytes, and
                     // an mp3 inside an <img> is a broken glyph on every tile
                     img: rolls.length > 0 && mediaOf(f.kind) === 'image' ? `/media/api/thumb?id=${encodeURIComponent(f.asset.id)}` : undefined,
-                    file: '.rv-assets/kit.ts',
+                    file: '.shipkit/assets/kit.ts',
                     remarks: notes.get(f.asset.id),
                 }
-                if (manual && rolls.length === 0)
+                const picked = rolls.length > 0 && (await readPick(dir)).pick != null
+                const stale = picked && (await isStale(kit, join(root, kit.workspace), f))
+                // the colour comes from the ONE asset rule, the words and the
+                // verbs from the case that produced it
+                const colour = assetState({ manual, rolls: rolls.length, picked, stale })
+                const said: Partial<Instance> = manual && rolls.length === 0
                     // the brief IS the paste-ready artifact ("I don't even
                     // know what to paste" — the tile hands him the prompt)
-                    out.push({ ...base, text: `${f.asset.id} — manual, nothing uploaded`, severity: 'red', verbs: ['provide'], artifact: f.asset.prompt != null ? { copy: f.asset.prompt } : undefined })
-                else if (rolls.length > 0 && (await readPick(dir)).pick == null)
-                    out.push({ ...base, text: `${f.asset.id} — ${rolls.length} roll(s), default in use, none picked`, severity: 'yellow', verbs: ['pick'] })
-                else if (await isStale(kit, join(root, kit.workspace), f))
-                    out.push({ ...base, text: `${f.asset.id} — stale (a parent was re-picked)`, severity: 'yellow', verbs: ['pick'] })
-                else out.push(base) // healthy — visible, dim, never in needs
+                    ? { text: `${f.asset.id} — manual, nothing uploaded`, label: f.asset.id, verbs: ['provide'], artifact: f.asset.prompt != null ? { copy: f.asset.prompt } : undefined }
+                    : rolls.length > 0 && !picked
+                        ? { text: `${f.asset.id} — ${rolls.length} roll(s), default in use, none picked`, label: f.asset.id, verbs: ['pick'] }
+                        : stale
+                            ? { text: `${f.asset.id} — stale (a parent was re-picked)`, label: f.asset.id, verbs: ['pick'] }
+                            : {}
+                out.push({ ...base, ...said, ...colour })
             }
             return out
         },
     }
 }
 
-/** `.rv-assets/notes.md`, dated asset remarks in one git-tracked file:
+/** `.shipkit/assets/notes.md`, dated asset remarks in one git-tracked file:
  *  `- YYYY-MM-DD [asset-id]: text` */
 const assetNotes = (root: string): Map<string, string[]> => {
-    const p = join(root, '.rv-assets', 'notes.md')
+    const p = join(root, '.shipkit/assets', 'notes.md')
     const map = new Map<string, string[]>()
     if (!existsSync(p)) return map
     for (const m of readFileSync(p, 'utf8').matchAll(/^- (\d{4}-\d{2}-\d{2}) \[([^\]]+)\]: (.+)$/gm)) {
@@ -230,12 +332,13 @@ const assetNotes = (root: string): Map<string, string[]> => {
     return map
 }
 
-/** repo health — NON-curatable feed items: EVERY wire line of STATUS.md's
- *  check output (ok = quiet, WARN = yellow, FAIL = red; the passing lines
- *  ARE listed — the page shows the whole check run), plus contract
- *  FAIL/WARN and hub process staleness. fix: pointers ride the owning
- *  instance's md as a code block. Cred probe FAIL lines (+ their fixes) are
- *  routed to the secrets collection, never duplicated here. */
+/** repo health — what belongs to no check and no other collection: contract
+ *  FAIL/WARN lines and hub process staleness. Every check, rule and task of
+ *  the gate is its own resource now (collections/checks.ts), so re-parsing
+ *  STATUS.md into one row per wire line would state the same verdicts a
+ *  second time, under ids that are whole sentences, and the two would
+ *  disagree the moment one run narrowed. Cred probe FAIL lines (+ their
+ *  fixes) stay routed to the secrets collection. */
 export function repoHealthCollection(root: string, c: RepoConfig, o?: { bootVersion?: string; libVersion?: () => string }): Collection {
     return {
         id: 'health',
@@ -246,35 +349,39 @@ export function repoHealthCollection(root: string, c: RepoConfig, o?: { bootVers
             if (o?.bootVersion != null && o.libVersion != null) {
                 const now = o.libVersion()
                 if (now !== o.bootVersion)
-                    out.push({ id: 'health:stale-hub', severity: 'red', text: `hub is running shipkit ${o.bootVersion} but ${now} is on disk (stale process, stale pages, old studio code). Restart the 🚀 shipkit task` })
+                    out.push({ id: 'health:stale-hub', type: 'health', path: 'health/stale-hub', virtual: true, severity: 'red', text: `hub is running shipkit ${o.bootVersion} but ${now} is on disk (stale process, stale pages, old studio code). Restart the 🚀 shipkit task` })
             }
-            for (const i of statusWire(root)) {
-                if (i.kind === 'fail' && CRED_LINE.test(i.text)) continue // secrets own the cred probe + its fix lines
-                // the feed line carries severity already — a raw FAIL:/WARN marker would stack the signal
-                // id = full text (never sliced: a shared 60-char prefix must not collide two items — pings dedup on ids)
-                out.push({
-                    id: `health:${i.text}`,
-                    text: i.text,
-                    severity: i.kind === 'fail' ? 'red' : i.kind === 'warn' ? 'yellow' : undefined,
-                    md: i.fixes.length > 0 ? wireMd(i.fixes.map((f) => `fix: ${f}`)) : undefined,
-                })
-            }
-            const r = await evaluateContracts(activeContracts(c), contractsConfigFrom(c, root))
+            const disk = CheckCtx.open({ root, config: c })
+            const r = await evaluateContracts(activeContracts(c), contractsConfigFrom(c, disk), disk)
             for (const l of r.lines) {
-                if (l.kind === 'fail') out.push({ id: `health:contract:${l.text}`, severity: 'red', text: l.text })
-                else if (l.kind === 'warn') out.push({ id: `health:contractwarn:${l.text}`, severity: 'yellow', text: l.text })
+                if (l.kind === 'fail') out.push({ id: `health:contract:${l.text}`, type: 'contract', path: `health/contracts/${slug(l.text)}`, virtual: true, severity: 'red', text: l.text })
+                else if (l.kind === 'warn') out.push({ id: `health:contractwarn:${l.text}`, type: 'contract', path: `health/contracts/${slug(l.text)}`, virtual: true, severity: 'yellow', text: l.text })
             }
             return out
         },
     }
 }
 
+/** one listing for every caller while it is in flight: the hub lists every
+ *  collection at once, and the secrets read the checks listing too */
+const sharedList = (col: Collection): Collection => {
+    let inFlight: Promise<Instance[]> | null = null
+    return {
+        ...col,
+        list: () => (inFlight ??= col.list().finally(() => { inFlight = null })),
+    }
+}
+
 export function buildCollections(root: string, c: RepoConfig, kit: ResolvedKit | null, o?: { bootVersion?: string; libVersion?: () => string }): Collection[] {
+    const checks = sharedList(checksCollection(root, c))
     return [
+        checks,
         repoHealthCollection(root, c, o),
         asksCollection(root, c),
-        credsCollection(root, c),
+        credsCollection(root, c, { verdicts: () => verdictsOf(checks) }),
         mediaKitCollection(root, kit),
         socialPostsCollection(root),
+        reflectionsCollection(root),
+        testsCollection(root, c),
     ]
 }