rvlib-shipkit 0.35.8 → 0.37.0

package/src/prose/ste.ts

@@ -0,0 +1,436 @@
+// STE prose checker — the mechanical subset of ASD-STE100 (Issue 9) that a
+// machine can judge without reading for meaning. The standard has 53 rules
+// and a ~900-word dictionary; this file implements the classes where a regex
+// is not a guess, and stays silent everywhere else. The house standard and
+// the exemptions: identity/writing-voice.md.
+//
+// Three tiers, because the cost of being wrong is not the same for each:
+//   fix  — one mechanical rewrite, meaning preserved. `--fix` applies it.
+//   hard — a real violation whose repair is a judgement call. Reported.
+//   soft — needs a human read (length, voice). Warns, never blocks alone.
+//
+// The class ids are STABLE: a baseline count and a `steAllow` entry both
+// name them.
+
+export type ProseTier = 'fix' | 'hard' | 'soft'
+
+export type ProseClass =
+    | 'contraction'
+    | 'abbrev'
+    | 'slop'
+    | 'modal'
+    | 'semicolon'
+    | 'comma-ing'
+    | 'perfect'
+    | 'vague'
+    | 'sentence'
+    | 'passive'
+    | 'paragraph'
+
+export type ProseHit = {
+    line: number // 1-based, true to the file
+    start: number // offset into the source
+    end: number
+    cls: ProseClass
+    tier: ProseTier
+    text: string // the offending span
+    fix?: string // the replacement, when the class is mechanical
+    why: string // one line, what STE wants instead
+}
+
+export type ProseOpts = {
+    /** class ids this file or repo does not want checked */
+    allow?: ProseClass[]
+    /** procedural limit (20) instead of the descriptive one (25) */
+    strict?: boolean
+}
+
+const TIER: Record<ProseClass, ProseTier> = {
+    contraction: 'fix',
+    abbrev: 'fix',
+    slop: 'fix',
+    modal: 'soft',
+    semicolon: 'hard',
+    'comma-ing': 'soft',
+    perfect: 'soft',
+    vague: 'hard',
+    sentence: 'soft',
+    passive: 'soft',
+    paragraph: 'soft',
+}
+
+export const PROSE_CLASSES = Object.keys(TIER) as ProseClass[]
+export const tierOf = (c: ProseClass): ProseTier => TIER[c]
+
+// --- vocabulary tables ---------------------------------------------------
+
+/** contractions → the full form. STE keeps every word a reader can look up. */
+const CONTRACTIONS: Record<string, string> = {
+    "aren't": 'are not', "can't": 'cannot', "couldn't": 'could not', "didn't": 'did not',
+    "doesn't": 'does not', "don't": 'do not', "hadn't": 'had not', "hasn't": 'has not',
+    "haven't": 'have not', "isn't": 'is not', "mustn't": 'must not', "shouldn't": 'should not',
+    "wasn't": 'was not', "weren't": 'were not', "won't": 'will not', "wouldn't": 'would not',
+    "he's": 'he is', "here's": 'here is', "it's": 'it is', "let's": 'let us', "she's": 'she is',
+    "that's": 'that is', "there's": 'there is', "they're": 'they are', "they've": 'they have',
+    "we're": 'we are', "we've": 'we have', "what's": 'what is', "who's": 'who is',
+    "you're": 'you are', "you've": 'you have', "i'm": 'I am', "we'll": 'we will',
+    "you'll": 'you will', "it'll": 'it will', "they'll": 'they will',
+}
+
+/** latin and shorthand a non-native reader must decode */
+const ABBREV: Record<string, string> = {
+    'e.g.': 'for example', 'i.e.': 'that is', 'vs.': 'against', 'w/': 'with',
+}
+
+/** one mechanical replacement, meaning preserved. Sourced from the STE
+ *  dictionary's not-approved column where the alternative is unambiguous,
+ *  plus the AI-slop words rule 1.5 (keep it short) covers.
+ *  `verb: true` lets the checker carry the inflection across, so `utilizes`
+ *  becomes `uses` and not `utilizes`. Without it a table of base forms
+ *  silently misses most real prose. */
+const SUBSTITUTIONS: { from: string; to: string; verb?: boolean }[] = [
+    { from: 'leverage', to: 'use', verb: true },
+    { from: 'utilize', to: 'use', verb: true },
+    { from: 'commence', to: 'start', verb: true },
+    { from: 'terminate', to: 'stop', verb: true },
+    { from: 'obtain', to: 'get', verb: true },
+    { from: 'facilitate', to: 'help', verb: true },
+    { from: 'streamline', to: 'make simpler', verb: false },
+    { from: 'prior to', to: 'before' },
+    { from: 'in order to', to: 'to' },
+    { from: 'due to the fact that', to: 'because' },
+    { from: 'in the event that', to: 'if' },
+    { from: 'out of the box', to: 'by default' },
+    { from: 'under the hood', to: 'internally' },
+    { from: 'a number of', to: 'some' },
+    { from: 'is able to', to: 'can' },
+    { from: 'are able to', to: 'can' },
+    { from: 'has the ability to', to: 'can' },
+    { from: 'plethora', to: 'many' },
+    { from: 'myriad', to: 'many' },
+    { from: 'additionally', to: 'also' },
+    { from: 'furthermore', to: 'also' },
+    { from: 'moreover', to: 'also' },
+]
+
+/** carry an English verb inflection from the banned word onto its
+ *  replacement. Only the four regular endings, because an irregular form is
+ *  a guess and this table exists to avoid guesses. */
+const IRREGULAR: Record<string, Record<string, string>> = {
+    get: { s: 'gets', es: 'gets', d: 'got', ed: 'got', ing: 'getting' },
+    stop: { s: 'stops', es: 'stops', d: 'stopped', ed: 'stopped', ing: 'stopping' },
+    run: { s: 'runs', es: 'runs', d: 'ran', ed: 'ran', ing: 'running' },
+}
+
+function inflect(base: string, suffix: string): string {
+    if (suffix === '') return base
+    const irr = IRREGULAR[base]?.[suffix]
+    if (irr != null) return irr
+    if (suffix === 's' || suffix === 'es') return /(s|x|z|ch|sh)$/.test(base) ? `${base}es` : `${base}s`
+    if (suffix === 'd' || suffix === 'ed') return base.endsWith('e') ? `${base}d` : `${base}ed`
+    if (suffix === 'ing') return base.endsWith('e') ? `${base.slice(0, -1)}ing` : `${base}ing`
+    return base
+}
+
+/** the same idea where the replacement must eat neighbouring punctuation.
+ *  'However, X' becomes 'But X', never 'But, X'. */
+const PHRASE_SUBSTITUTIONS: { re: RegExp; to: string; why: string }[] = [
+    { re: /\bhowever,\s+/gi, to: 'but ', why: "STE writes 'but'" },
+    { re: /\bnevertheless,\s+/gi, to: 'but ', why: "STE writes 'but'" },
+    { re: /\bnonetheless,\s+/gi, to: 'but ', why: "STE writes 'but'" },
+]
+
+/** deletable: the word carries no fact, and removing it leaves valid grammar.
+ *  Intensifiers are deliberately NOT here. `very` is an approved STE word, and
+ *  an intensifier a writer chose states a degree, so deleting it edits the
+ *  claim rather than the prose. */
+const DELETIONS = [
+    'simply', 'seamlessly', 'effortlessly', 'blazingly', 'basically', 'essentially',
+    'it is worth noting that', 'it is important to note that', 'needless to say',
+]
+
+/** a real violation with no safe mechanical repair: the writer picks the fact */
+const VAGUE: Record<string, string> = {
+    robust: 'delete it, or give the measurable property',
+    powerful: 'delete it, or give the measurable property',
+    comprehensive: 'delete it, or name what it covers',
+    performant: 'delete it, or give the number',
+    'state-of-the-art': 'delete it',
+    'best-in-class': 'delete it',
+    ensure: 'write "make sure that", or name the guarantee',
+    etc: 'name the items, or write "and the rest of <the family>"',
+    'and/or': 'pick one, or write "X, or Y, or both"',
+    'as needed': 'state the condition',
+    'as necessary': 'state the condition',
+    'gracefully handles': 'say what it does',
+}
+
+const MODALS = ['should', 'would', 'may', 'might', 'could']
+
+const PARTICIPLES =
+    'written|built|done|made|kept|held|read|sent|shown|given|taken|known|seen|found|lost|run|set|put|told|left|drawn|thrown|caught|brought|bought|spent|meant|dealt|felt|gone|come|become|begun'
+
+// --- masking -------------------------------------------------------------
+
+const blankOut = (m: string): string => m.replace(/[^\n]/g, ' ')
+
+/** everything that is NOT house prose, blanked to spaces of the same length,
+ *  so every offset a regex reports still points at the real source.
+ *  Out of scope by the standard's own Untouchables plus the house exemptions:
+ *  frontmatter, code fences, inline code, double-quoted verbatim spans,
+ *  URLs and link targets, and `>` blockquotes (paste-ready copy). */
+export function maskProse(src: string): string {
+    let m = src.replace(/^---\n[\s\S]*?\n---\n/, blankOut)
+    m = m.replace(/```[\s\S]*?```/g, blankOut)
+    m = m.replace(/`[^`\n]*`/g, blankOut)
+    // a verbatim quote is spec, never house prose. The cap keeps one unpaired
+    // quote from swallowing the rest of the page.
+    m = m.replace(/"[^"]{0,800}"/g, blankOut)
+    m = m.replace(/“[^”]{0,800}”/g, blankOut)
+    // a verbatim quoted with SINGLE quotes, which house pages use as often as
+    // double ones. The opening quote must follow a boundary, so an apostrophe
+    // inside a word (`don't`) can never open a span and swallow the line.
+    // a word-internal apostrophe (`you're`) stays INSIDE the span. Real
+    // quotations are full of them, and a span that stops at the first one
+    // masks nothing, after which the fixer rewrites the quotation.
+    m = m.replace(/(^|[\s(\[])'(?:[^'\n]|(?<=\w)'(?=\w))*'(?=[\s.,;:!?)\]]|$)/gm, (full) => full[0] + blankOut(full.slice(1)))
+    m = m.replace(/(^|[\s(\[])‘[^’\n]{0,300}’/gm, (full) => full[0] + blankOut(full.slice(1)))
+    m = m.replace(/\]\([^)\n]*\)/g, blankOut)
+    m = m.replace(/https?:\/\/\S+/g, blankOut)
+    m = m.replace(/^[ \t]*>.*$/gm, blankOut)
+    return m
+}
+
+/** a table row is structure: word classes still apply inside a cell, sentence
+ *  and paragraph limits do not. Same for a heading. */
+/** `is unmaintained` is a state, not a passive voice: there is no verb `to
+ *  unmaintain`, so no actor exists to name. The `un-` prefix catches almost
+ *  the whole family; the rest are participles coined off a noun. */
+const COINED = new Set(['gitignored', 'backticked', 'sandboxed', 'siloed'])
+/** words that end in the two letters and were never a verb. `be + \w+ed` cannot
+ *  tell them from a participle, and it reported `is red` as a passive voice. */
+const NOT_PARTICIPLES = new Set(['red', 'tired', 'hundred', 'aged', 'learned', 'sacred', 'bed', 'need', 'feed', 'speed', 'seed', 'freed', 'agreed', 'indeed'])
+const isAdjectival = (participle: string): boolean => {
+    const w = participle.toLowerCase()
+    return (w.startsWith('un') && w.endsWith('ed')) || COINED.has(w) || NOT_PARTICIPLES.has(w)
+}
+
+const isStructureLine = (l: string): boolean => /^\s*\|/.test(l) || /^\s*#{1,6}\s/.test(l) || /^\s*[-|: ]+$/.test(l)
+
+// --- sentence segmentation ----------------------------------------------
+
+/** house prose puts one bullet per line and uses ` — ` as a SEPARATOR, never
+ *  as sentence punctuation (identity/writing-voice.md). Both are boundaries
+ *  here, so a route line is not read as one 40-word sentence. */
+const splitSentences = (line: string): { text: string; at: number }[] => {
+    const out: { text: string; at: number }[] = []
+    let at = 0
+    for (const part of line.split(/(?<=[.!?])\s+|\s+[—–]\s+/)) {
+        const i = line.indexOf(part, at)
+        out.push({ text: part, at: i < 0 ? at : i })
+        at = (i < 0 ? at : i) + part.length
+    }
+    return out
+}
+
+/** STE counts a code span, a command or a path as ONE word */
+const wordCount = (s: string): number =>
+    s
+        .replace(/`[^`]*`/g, 'x')
+        .replace(/^\s*(?:[-*+]|\d+\.)\s+/, '')
+        .replace(/[*_]/g, '')
+        .split(/\s+/)
+        .filter((w) => /[A-Za-z0-9]/.test(w)).length
+
+// --- the checker ---------------------------------------------------------
+
+const capitalizeLike = (sample: string, replacement: string): string =>
+    /^[A-Z]/.test(sample) ? replacement.charAt(0).toUpperCase() + replacement.slice(1) : replacement
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+export function checkProse(src: string, opts: ProseOpts = {}): ProseHit[] {
+    const allow = new Set(opts.allow ?? [])
+    const masked = maskProse(src)
+    const hits: ProseHit[] = []
+    // line index → offset, once
+    const lineStart: number[] = [0]
+    for (let i = 0; i < src.length; i++) if (src[i] === '\n') lineStart.push(i + 1)
+    const lineOf = (off: number): number => {
+        let lo = 0
+        let hi = lineStart.length - 1
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1
+            if (lineStart[mid]! <= off) lo = mid
+            else hi = mid - 1
+        }
+        return lo + 1
+    }
+
+    const push = (cls: ProseClass, start: number, end: number, why: string, fix?: string) => {
+        if (allow.has(cls)) return
+        const text = src.slice(start, end)
+        hits.push({ line: lineOf(start), start, end, cls, tier: TIER[cls], text, fix, why })
+    }
+
+    const scan = (re: RegExp, run: (m: RegExpExecArray) => void) => {
+        re.lastIndex = 0
+        let m: RegExpExecArray | null
+        while ((m = re.exec(masked)) != null) {
+            if (m[0].trim() === '') continue
+            run(m)
+        }
+    }
+
+    // --- fix tier
+    scan(new RegExp(`\\b(${Object.keys(CONTRACTIONS).map(escapeRe).join('|')})`, 'gi'), (m) => {
+        const full = CONTRACTIONS[m[0].toLowerCase()]
+        if (full != null) push('contraction', m.index, m.index + m[0].length, 'STE keeps the full form', capitalizeLike(m[0], full))
+    })
+    scan(new RegExp(`(?<![\\w.])(${Object.keys(ABBREV).map(escapeRe).join('|')})`, 'gi'), (m) => {
+        const full = ABBREV[m[0].toLowerCase()]
+        if (full != null) push('abbrev', m.index, m.index + m[0].length, 'write the words a non-native reader can read', capitalizeLike(m[0], full))
+    })
+    // a verb entry matches its inflected forms too, and the ending rides onto
+    // the replacement
+    const verbs = SUBSTITUTIONS.filter((x) => x.verb === true)
+    const plain = SUBSTITUTIONS.filter((x) => x.verb !== true)
+    for (const e of verbs) {
+        // a base ending in `e` drops it before `-ing` (leverage → leveraging),
+        // so the stem is matched both ways
+        const stem = e.from.endsWith('e') ? e.from.slice(0, -1) : e.from
+        scan(new RegExp(`\\b(?:${escapeRe(e.from)}(es|s|ed|d)?|${escapeRe(stem)}(ing))\\b`, 'gi'), (m) => {
+            const to = inflect(e.to, (m[1] ?? m[2] ?? '').toLowerCase())
+            push('slop', m.index, m.index + m[0].length, `STE writes '${e.to}'`, capitalizeLike(m[0], to))
+        })
+    }
+    scan(new RegExp(`\\b(${plain.map((x) => escapeRe(x.from)).join('|')})\\b`, 'gi'), (m) => {
+        const e = plain.find((x) => x.from === m[0]!.toLowerCase())
+        if (e != null) push('slop', m.index, m.index + m[0].length, `STE writes '${e.to}'`, capitalizeLike(m[0], e.to))
+    })
+    // a deletion gives back exactly one space, and WHICH one depends on what
+    // follows: before punctuation the space in front goes with the word, or
+    // the page keeps `the world : publish`. At the start of a line the fix is
+    // withheld entirely, because deleting the first word moves the capital
+    // onto the next one and that is the writer's call.
+    scan(new RegExp(`( *)\\b(${DELETIONS.map(escapeRe).join('|')})\\b( *)`, 'gi'), (m) => {
+        const lead = m[1] ?? ''
+        let end = m.index + m[0].length
+        const after = masked[end] ?? ''
+        const before = masked[m.index - 1] ?? ''
+        // inside an enumeration the word owns one of the two commas around it,
+        // or deleting it leaves `Also,, X`
+        if (before === ',' && after === ',') end += 1
+        const punctuationFollows = /[.,:;!?)\]]/.test(after)
+        const fix = lead === '' ? undefined : punctuationFollows ? '' : lead
+        push('slop', m.index, end, 'the word carries no fact', fix)
+    })
+    for (const p of PHRASE_SUBSTITUTIONS)
+        scan(new RegExp(p.re.source, 'gi'), (m) => push('slop', m.index, m.index + m[0].length, p.why, capitalizeLike(m[0], p.to)))
+
+    // --- hard tier
+    scan(new RegExp(`\\b(${MODALS.join('|')})\\b`, 'gi'), (m) =>
+        push('modal', m.index, m.index + m[0].length, "a requirement is 'must', a possibility is 'can', a recommendation is a fact or it is deleted"),
+    )
+    scan(/;/g, (m) => push('semicolon', m.index, m.index + 1, 'write two sentences'))
+    scan(/,\s+(\w+ing)\b/g, (m) => {
+        if (/^(nothing|something|anything|everything|during|string|thing)$/i.test(m[1]!)) return
+        // an `-ing` word used as an ADJECTIVE (`, missing path`) is not the
+        // participial clause the rule bans, and no regex can tell them apart.
+        // Measured on a real wiki, roughly two in three hits were a noun
+        // in an enumeration (`selection, loading, empty, error and the pager`)
+        // rather than a clause, which is why this class is SOFT: a rule that
+        // cries wolf gets switched off, and then it guards nothing.
+        if (/^(missing|following|existing|remaining|leading|trailing|incoming|outgoing|ongoing|pending|willing|living|growing|surrounding|underlying)$/i.test(m[1]!)) return
+        // `Renaming a file, moving a responsibility, or changing any contract`
+        // is a coordinated list of gerund NOUNS, not the participial clause
+        // the rule bans. The tell is a second gerund behind `and` or `or`.
+        const line = masked.slice(masked.lastIndexOf('\n', m.index) + 1, (masked.indexOf('\n', m.index) + 1 || masked.length + 1) - 1)
+        if (/\b(and|or)\s+\w+ing\b/.test(line)) return
+        push('comma-ing', m.index, m.index + m[0].length, "STE bans an '-ing' verb after a comma: start a new sentence, or write the relative clause")
+    })
+    scan(new RegExp(`\\b(has|have|had)\\s+(been|\\w+ed|${PARTICIPLES})\\b`, 'gi'), (m) =>
+        push('perfect', m.index, m.index + m[0].length, 'STE uses simple tenses only'),
+    )
+    scan(new RegExp(`\\b(${Object.keys(VAGUE).map(escapeRe).join('|')})\\b`, 'gi'), (m) => {
+        const why = VAGUE[m[0].toLowerCase()]
+        if (why != null) push('vague', m.index, m.index + m[0].length, why)
+    })
+
+    // --- soft tier, line by line
+    const limit = opts.strict === true ? 20 : 25
+    const lines = masked.split('\n')
+    let paraStart = -1
+    let paraSentences = 0
+    const flushParagraph = (endLine: number) => {
+        if (paraStart >= 0 && paraSentences > 6)
+            push('paragraph', lineStart[paraStart]!, lineStart[paraStart]! + (lines[paraStart]?.length ?? 0), `${paraSentences} sentences in one paragraph: STE allows six`)
+        paraStart = -1
+        paraSentences = 0
+        void endLine
+    }
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i]!
+        const off = lineStart[i]!
+        if (line.trim() === '') {
+            flushParagraph(i)
+            continue
+        }
+        if (isStructureLine(line)) {
+            flushParagraph(i)
+            continue
+        }
+        // passive voice: a form of `be` plus a past participle
+        const passRe = new RegExp(`\\b(is|are|was|were|be|been|being)\\s+(\\w+ed|${PARTICIPLES})\\b`, 'gi')
+        let pm: RegExpExecArray | null
+        while ((pm = passRe.exec(line)) != null) {
+            if (isAdjectival(pm[2]!)) continue
+            push('passive', off + pm.index, off + pm.index + pm[0].length, 'STE wants the active voice: name the actor')
+        }
+        const isBullet = /^\s*(?:[-*+]|\d+\.)\s/.test(line)
+        if (!isBullet) {
+            if (paraStart < 0) paraStart = i
+        }
+        for (const s of splitSentences(line)) {
+            const w = wordCount(s.text)
+            if (!isBullet && paraStart >= 0 && w > 0) paraSentences++
+            if (w > limit)
+                push('sentence', off + s.at, off + s.at + s.text.length, `${w} words: the limit is ${limit}`)
+        }
+    }
+    flushParagraph(lines.length)
+
+    return hits.sort((a, b) => a.start - b.start)
+}
+
+/** apply every mechanical rewrite, left to right, first hit wins.
+ *
+ *  Two scans can claim the same characters: the deletion scan takes the space
+ *  in front of its word, and a phrase substitution takes the space behind the
+ *  comma it eats. Writing both over each other ate the text between them
+ *  (`However, simply.` came back as `But `). So a hit that starts inside an
+ *  already-applied span is DROPPED and the next pass picks it up on clean
+ *  text, which is why this runs to a FIXED POINT rather than once. Bounded,
+ *  because a fixer that cannot converge must say so rather than spin. */
+export function fixProse(src: string, opts: ProseOpts = {}): { text: string; applied: number } {
+    let text = src
+    let applied = 0
+    for (let pass = 0; pass < 5; pass++) {
+        const hits = checkProse(text, opts).filter((h) => h.fix != null)
+        if (hits.length === 0) break
+        let out = ''
+        let cursor = 0
+        let wrote = 0
+        for (const h of [...hits].sort((a, b) => a.start - b.start)) {
+            if (h.start < cursor) continue
+            out += text.slice(cursor, h.start) + h.fix
+            cursor = h.end
+            wrote++
+        }
+        if (wrote === 0) break
+        text = out + text.slice(cursor)
+        applied += wrote
+    }
+    return { text, applied }
+}
+

package/src/repo-config.ts

@@ -17,9 +17,12 @@ import { FLOOR_IDS, resolveFloor, type FloorResolution } from './core/floor.ts'
 export { resolveFloor, type FloorResolution, type FloorSource } from './core/floor.ts'
 import { evaluateContractsOnce } from './contracts/contracts-once.ts'
 import type { ContractManifest } from './contracts/contract-types.ts'
+import type { ProseConfig } from './prose/run-prose.ts'
+import { validateSmokeConfig, type SmokeConfig } from './smoke/run-smoke.ts'
 import { contractsFulfillness } from './rules/SK002-contracts-fulfillness.ts'
 import { BUILTIN_RULE_IDS, validateRules } from './rules/rule-registry.ts'
 import type { Rule } from './rules/rule.ts'
+import { leakAllowProblems } from './hooks/leak-guard.ts'
 import type { HooksConfig } from './hooks/run-hooks.ts'
 import type { ReleaseConfig } from './release/run-release.ts'
 import { UNIT_DECL_KEYS, type ReleaseUnitDecl } from './release/units.ts'
@@ -66,6 +69,12 @@ export type RepoConfig = {
     creds?: { name: string; service?: string; mintUrl?: string; steps?: string[] }[]
     /** store-command template for a missing secret tile, `{name}` substituted (e.g. your secret manager's set command) */
     credsCommand?: string
+    /** READ-command template, the twin of `credsCommand`: prints one field of
+     *  a secret, `{name}` and `{field}` (get = the value, account = the
+     *  identity stored beside it) substituted, run WITHOUT a shell. The one
+     *  way a value reaches a command (`shipkit smoke` login), so it never sits
+     *  in config, argv or env. Required when `smoke.login` is declared. */
+    credsReadCommand?: string
     /** notify command for new RED needs while the hub serves, `{message}` substituted (e.g. a push-notification CLI) */
     notifyCommand?: string
     contracts?: { exempt?: Record<string, string>; extra?: ContractManifest[] }
@@ -129,6 +138,16 @@ export type RepoConfig = {
      *  once here; a file that differs overrides with its own
      *  `export const blocking = true`. With neither, the check fails loud. */
     checkDefaults?: { blocking?: boolean }
+    /** house prose in STE (identity/writing-voice.md), gated by rule SK014.
+     *  `include` is what makes the rule run at all: a repo that declares no
+     *  scope is skipped rather than failed, because STE binds the prose an
+     *  agent WRITES and no repo can be opted in from the outside.
+     *  prose/run-prose.ts */
+    prose?: ProseConfig
+    /** `shipkit smoke`: the deployed url, the routes a read only browser pass
+     *  visits after a deploy, and how it logs in. The password is a secret
+     *  NAME: the value never sits in config, argv or env. smoke/run-smoke.ts */
+    smoke?: SmokeConfig
     /** extra dashboard panels appended after the built-in Tasks/Checks (`shipkit tui`) */
     tui?: { panels?: TuiPanelDef[] }
     /** the `shipkit serve` hub: port + optional graph hooks */
@@ -136,7 +155,7 @@ export type RepoConfig = {
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'visibility', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'logDir'])
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'visibility', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'logDir', 'prose', 'smoke'])
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
@@ -182,6 +201,22 @@ export function defineRepo(c: RepoConfig): RepoConfig {
     // repo rules are validated against the built-ins, so a bad id, a duplicate,
     // or an SK squatter dies at config load, not silently mid-check
     if (c.rules != null) validateRules(c.rules, { label: 'defineRepo: rules', taken: BUILTIN_RULE_IDS })
+    // a smoke typo would land as a run that visits nothing and exits 0
+    if (c.smoke != null) validateSmokeConfig(c.smoke)
+    // a leak-guard waiver is the one config row that can make a gate quieter,
+    // so a malformed one dies here rather than being dropped at commit time
+    if (c.hooks?.leakAllow != null) {
+        const problems = leakAllowProblems(c.hooks.leakAllow, 'defineRepo: hooks.leakAllow', true)
+        if (problems.length > 0) throw new Error(problems[0])
+    }
+    if (c.credsReadCommand != null && !/\{name\}/.test(c.credsReadCommand))
+        throw new Error(`defineRepo: credsReadCommand must carry {name} (and {field} for get | account), e.g. 'my-secrets {field} {name}'`)
+    if (c.smoke?.login != null && (c.credsReadCommand ?? '') === '')
+        throw new Error(`defineRepo: smoke.login reads its password through credsReadCommand, which this repo does not declare (e.g. 'my-secrets {field} {name}')`)
+    // without {field} the account read answers the VALUE, and the run types the
+    // password into the identity box, where a failed-login journal keeps it
+    if (c.smoke?.login?.emailSecret != null && !/\{field\}/.test(c.credsReadCommand ?? ''))
+        throw new Error(`defineRepo: smoke.login.emailSecret needs credsReadCommand to carry {field}, or the account read answers the password itself`)
     return c
 }
 
@@ -203,6 +238,12 @@ export async function loadRepoConfig(root: string): Promise<RepoConfig> {
 // so a key would be risk against no reward. It is not `never:` either: the
 // contract dirs describe it perfectly well, so claiming nothing can is false,
 // and `never` has to keep meaning "somebody looked and no key exists".
+//
+// Declaring `inputs: ['.']` to clear its burn-down row was TRIED and reverted:
+// a keyable contracts task writes a ledger entry inside every fixture repo,
+// which is six ledger tests asserting an entry count that is really about the
+// task under test. The row it leaves behind is the honest cost of the model
+// having no third state between "nobody looked" and "no key can exist".
 export function contractsTask(c: RepoConfig, root: string): TaskDef {
     return {
         id: 'contracts',

package/src/rules/SK014-prose-ste.ts

@@ -0,0 +1,50 @@
+// SK014 — the STE prose standard, in the gate (identity/writing-voice.md).
+//
+// Opt-in by declaration: a repo with no `prose.include` is SKIPPED, not
+// failed. STE is house doctrine for prose an agent writes, and a rule that
+// turned every existing repo red the day it shipped would be turned off
+// rather than obeyed.
+//
+// The tier split is the whole design. `fix` and `hard` hits BLOCK: they are
+// mechanical, and a machine reporting them is never guessing. `soft` hits
+// (sentence length, passive voice) need a human read, so they WARN, and only
+// a declared `baseline` makes them blocking, as a ratchet that can only go
+// down.
+//
+// It carries NO `fix()` on purpose. `shipkit ci` runs `--fix-rules` by
+// default, so a rule with a fixer rewrites tracked files unattended, and
+// prose is not repo shape: a wrong package.json line is a config, a wrong
+// sentence is content. The rewrite lives behind an explicit `shipkit prose
+// --fix` that a human ran and can read the diff of.
+import { classSummary, proseLines, runProseCheck } from '../prose/run-prose.ts'
+import type { Rule } from './rule.ts'
+
+const OWNER = 'identity/writing-voice.md'
+
+export const proseSte: Rule = {
+    id: 'SK014',
+    blocking: true,
+    title: 'STE prose',
+    owner: OWNER,
+    inputs: ['.'],
+    lint: (t, env) => {
+        const cfg = env.config.prose
+        if (cfg == null || (cfg.include ?? []).length === 0) {
+            t.ok(`no prose scope declared — add \`prose: { include: [...] }\` to repo.config.ts to gate house prose on STE`)
+            return
+        }
+        const r = runProseCheck({ root: env.root, config: cfg })
+        const blocking = r.byTier.fix + r.byTier.hard
+        for (const l of proseLines(r, { cap: 12, tiers: ['fix', 'hard'] })) t.note(l)
+        if (blocking > 0)
+            t.fail(
+                `${blocking} STE violation(s) across ${r.byFile.length}/${r.files} file(s) — ${classSummary(r)}`,
+                r.fixable > 0 ? `shipkit prose --fix rewrites ${r.fixable} of them` : undefined,
+            )
+        if (cfg.baseline != null && r.byTier.soft > cfg.baseline)
+            t.fail(`${r.byTier.soft} soft hits (sentence length, passive voice), above the declared baseline of ${cfg.baseline} — the ratchet only goes down`)
+        else if (r.byTier.soft > 0)
+            t.warn(`${r.byTier.soft} soft hit(s): sentence length and passive voice need a human read${cfg.baseline != null ? ` (baseline ${cfg.baseline})` : ''}`)
+        if (!t.failed && blocking === 0) t.ok(`${r.files} file(s) STE-clean on the mechanical rules`)
+    }
+}

package/src/rules/rule-registry.ts

@@ -16,6 +16,7 @@ import { undeclaredReleaseUnit } from './SK010-undeclared-release-unit.ts'
 import { siblingUnitRanges } from './SK011-sibling-unit-ranges.ts'
 import { configBarrelImport } from './SK012-config-barrel-import.ts'
 import { oneWayInPolicy } from './SK013-one-way-in-policy.ts'
+import { proseSte } from './SK014-prose-ste.ts'
 
 export const RULES: readonly Rule[] = [
     packageJsonShape,
@@ -31,6 +32,7 @@ export const RULES: readonly Rule[] = [
     siblingUnitRanges,
     configBarrelImport,
     oneWayInPolicy,
+    proseSte,
 ]
 
 // THE id shape, one place: 2-4 uppercase letters + exactly 3 digits. `SK` is

package/src/rules/untrack-generated.ts

@@ -31,13 +31,16 @@ export const GENERATED_IGNORE_LINES = [
     'STATUS.md',
     'STATUS.md.lock',
     '.STATUS.md.tmp-*',
+    'STATUS.full.md',
+    'STATUS.full.md.lock',
+    '.STATUS.full.md.tmp-*',
 ]
 
 /** the LITERAL subset an autofix may remove from the index. Never a glob and
  *  never derived from a pattern: `git rm --cached` driven by a wildcard is how
  *  a fixer eats source it was never pointed at. A future entry is added HERE,
  *  by hand, spelled out. */
-export const GENERATED_TRACKED_PATHS = ['STATUS.md', 'STATUS.md.lock'] as const
+export const GENERATED_TRACKED_PATHS = ['STATUS.md', 'STATUS.md.lock', 'STATUS.full.md', 'STATUS.full.md.lock'] as const
 
 export type UntrackOutcome =
     | { did: 'nothing' }