plumbbob 0.9.3 → 0.10.0

package/node_modules/checkride/dist/init.js

@@ -11,18 +11,19 @@
  * Generation, not transformation: every file is written once; the project owns
  * it afterward.
  */
+import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ADAPTERS, SLOTS } from './adapters.js';
 import { planSnippets, selectDocFiles } from './snippets.js';
-import { CLAUDE_SETTINGS_FILE, writeStopHook } from './agent-setup/index.js';
+import { detectHarnesses, writeCursorSkills, writeHooks } from './agent-setup/index.js';
 import { BASELINE_FILE, isFingerprintable } from './baseline/index.js';
 import { runBaseline } from './baseline-command.js';
-import { configSchemaUrl, resolveChecks } from './config.js';
-import { runChecks } from './orchestrator.js';
-import { detectPackageManager } from './pm/index.js';
+import { configSchemaUrl, loadConfig, resolveChecks } from './config.js';
+import { runChecks, selectChecks } from './orchestrator.js';
+import { detectPackageManager, execCommand, runScript } from './pm/index.js';
 const NULL_OUT = { write: () => true };
 /** Run the adopted checks once; a failing (non-skipped) check marks its slot. */
 async function defaultProbe(slots, cwd) {
@@ -33,22 +34,158 @@ async function defaultProbe(slots, cwd) {
 }
 const HERE = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(HERE, '..', 'templates');
-const STANZA_BEGIN = '<!-- checkride:begin -->';
+const STANZA_BEGIN_PREFIX = '<!-- checkride:begin';
 const STANZA_END = '<!-- checkride:end -->';
+/** The block, capturing its stamp (absent on stanzas written before v0.10.1) and its body. */
+const STANZA_RE = /<!-- checkride:begin(?: hash=([0-9a-z]+))? -->([\s\S]*?)<!-- checkride:end -->/;
+const STANZA_BEGIN_RE = /<!-- checkride:begin(?: hash=[0-9a-z]+)? -->/;
 // ----------------------------------------------------------------------------
 // AGENTS.md stanza (gate: idempotent)
 // ----------------------------------------------------------------------------
-function escapeRegex(text) {
-    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Compare two stanza bodies the way a reader would: line endings and trailing
+ * whitespace are not edits. Deliberately minimal — one checkride version stamps
+ * a block and a later one verifies that stamp, so every rule here has to keep
+ * holding across versions or a pristine stanza starts reading as an edited one.
+ */
+function normalizeStanza(text) {
+    return text.replace(/\r\n/g, '\n').replace(/[ \t]+$/gm, '').trim();
+}
+/**
+ * The stamp written into the begin marker: a digest of the body checkride
+ * generated. A later run recomputes it from what is on disk — a match means the
+ * block is still checkride's own output and is safe to refresh; a mismatch means
+ * someone edited it and refreshing would destroy their work.
+ *
+ * The `v1` prefix earns its place twice: it dates the normalization rules above
+ * (change them and bump it, so old stamps read as unverifiable rather than
+ * edited), and it guarantees the token contains a digit. cspell ignores words
+ * with digits, so a digest that happened to come up all `a`-`f` cannot fail the
+ * `spell` check of the repo checkride wrote it into.
+ */
+function stanzaStamp(body) {
+    return `v1${createHash('sha256').update(normalizeStanza(body)).digest('hex').slice(0, 16)}`;
+}
+/**
+ * A stanza body without its trailing generated `Active checks in this repo: …`
+ * line — the part that is pure wording, identical in every repo running a given
+ * checkride version.
+ *
+ * The active-checks line is what makes two stanzas from the same release differ,
+ * so a registry of released wordings has to compare everything but that. If the
+ * line is missing, or something follows it inside the markers, nothing is
+ * stripped and the digest simply fails to match — which is the safe answer.
+ */
+function stanzaPreamble(body) {
+    return normalizeStanza(normalizeStanza(body).replace(/\nActive checks in this repo:[^\n]*$/, ''));
+}
+/**
+ * The wording of every stanza checkride released before it stamped them, keyed
+ * by {@link stanzaPreamble} digest. Four distinct texts across v0.1.1–v0.10.0.
+ *
+ * This is what makes the stamp's arrival a non-event for repos that never
+ * touched their stanza. Without it, every upgrading repo looked `unstamped` —
+ * an older version's wording is not distinguishable from a customization by
+ * comparison alone — so the first run after upgrading refused and wrote
+ * *nothing*, hooks and config included. That is how the 0.10.1 gate-timeout fix
+ * failed to reach the repos that most needed it: the guard protecting AGENTS.md
+ * prose was also withholding a fix for a gate that had silently stopped gating.
+ *
+ * Recognizing the wording collapses that to the case it was always meant to
+ * cover. A pre-stamp stanza whose preamble is one of these is checkride's own
+ * output, untouched, and refreshing it loses nothing; one that has been edited
+ * still fails to match and is still refused.
+ *
+ * The list is closed. Every release from 0.10.1 stamps what it writes, so no
+ * future version can add an unstamped wording — nothing here needs maintaining.
+ */
+const LEGACY_STANZA_PREAMBLES = new Set([
+    'v16da2ec6a25e24085', // v0.1.1–v0.1.6
+    'v190c2d48a280ff92c', // v0.2.0–v0.7.0
+    'v1d4b4eaeeccb5faa2', // v0.8.0–v0.9.6
+    'v17a3a1a85e3c3123e', // v0.10.0 (0.10.1 shares the wording but stamps it)
+]);
+/** Classify the stanza in `content` against the `body` checkride would write. */
+export function inspectStanza(content, body) {
+    const match = STANZA_RE.exec(content);
+    if (!match) {
+        // A begin marker with no end is a stanza someone edited badly, not an absent
+        // one: appending a second block would be the same data loss in another form.
+        return content.includes(STANZA_BEGIN_PREFIX) ? 'edited' : 'absent';
+    }
+    const [, stamp, found = ''] = match;
+    if (stamp === undefined) {
+        if (normalizeStanza(found) === normalizeStanza(body))
+            return 'pristine';
+        return LEGACY_STANZA_PREAMBLES.has(stanzaStamp(stanzaPreamble(found))) ? 'pristine' : 'unstamped';
+    }
+    return stamp === stanzaStamp(found) ? 'pristine' : 'edited';
+}
+/**
+ * The `struct` slot's section: where the boundary rules live, not what they say.
+ *
+ * checkride ships opinionated ast-grep defaults (`no-class.yml` and friends),
+ * but it does not own the repo's architecture, and the stanza is the one place
+ * a repo cannot talk back — editing it blocks the next refresh. So this points
+ * at the rule files and stops. A repo that allows classes, default exports, or
+ * bundler-style extensionless imports deletes those rules and this stays true.
+ */
+function structSection() {
+    return [
+        '### Module boundaries',
+        '',
+        'The `struct` check runs whatever ast-grep rules `sgconfig.yml` points at',
+        "(`rules/` by default). Those files are this repo's boundary convention —",
+        'read them rather than assuming one.',
+        '',
+    ];
+}
+/**
+ * The `prose` slot's voice section, present only when the repo names an
+ * `exemplars` directory in its config. The instruction runs one way — read and
+ * imitate, never edit — because the exemplars are the repo's hand-written voice
+ * reference, the fresh human signal that keeps generated prose from converging
+ * on the model's own register. A generated "improvement" to one would replace
+ * the original with a copy, which is the drift the directory exists to prevent.
+ */
+function proseSection(exemplars) {
+    return [
+        '### Prose voice',
+        '',
+        'Before writing or editing prose (markdown, doc comments), read the exemplars in',
+        `\`${exemplars}\` and imitate their voice — sentence rhythm, word choice, register.`,
+        'They are hand-written and human-owned: never edit, rewrite, or add to them, and',
+        'never generate new ones. When your draft and an exemplar disagree about how a',
+        'sentence should sound, the exemplar wins.',
+        '',
+    ];
 }
-/** The agent-facing contract block, parameterized by the active checks. */
-export function buildStanza(activeSlots) {
+/**
+ * The agent-facing contract block, parameterized by the active checks and the
+ * repo's package manager.
+ *
+ * `pm` is not cosmetic. The stanza is a list of commands an agent is told to
+ * run, and `pnpm check` in an npm repo is an instruction that cannot succeed —
+ * the agent either invents a substitute or reports the pipeline as broken.
+ * Everything here routes through {@link runScript}/{@link execCommand} for that
+ * reason; nothing spells a launcher literally.
+ *
+ * The gate profile is deliberately *not* a parameter. A repo can add `gate` to
+ * checkride.config.json without re-running `agent-setup`, so a stanza naming a
+ * specific profile would go stale in exactly the direction that costs something
+ * — telling an agent the hook covered everything when it no longer does. The
+ * paragraph points at the gate's verdict instead, which is generated per run and
+ * states the narrowing itself (see `gate.ts`'s `profileClause`).
+ */
+export function buildStanza(activeSlots, pm = 'pnpm', proseExemplars = null) {
+    const check = runScript(pm, 'check');
+    const triage = execCommand(pm, ['checkride', 'triage']);
     return [
         '## Checkride: the definition of done',
         '',
-        '`pnpm check` is the single source of truth for "done". Exit 0 means the work is',
+        `\`${check}\` is the single source of truth for "done". Exit 0 means the work is`,
         'complete; any other exit code means it is not. Never claim a task is finished while',
-        '`pnpm check` is red.',
+        `\`${check}\` is red.`,
         '',
         'When it fails:',
         '',
@@ -56,13 +193,19 @@ export function buildStanza(activeSlots) {
         "2. Read that check's raw output (`.check/<slot>.json` or `.check/<slot>.stdout.txt`).",
         '3. Fix the root cause, then re-run.',
         '',
-        'Tight feedback loops: `pnpm check --bail`, `pnpm check --only types,lint`, and',
-        '`pnpm check --changed`.',
+        `\`${triage}\` runs this procedure in full and reads \`.check/\` for you`,
+        '(`/checkride:check` and `/checkride-check` are the same thing as a skill).',
         '',
-        'If a Claude Code Stop hook is configured (`.claude/settings.json`), it runs the full',
-        '`pnpm check` as the final gate — so while iterating, prefer the narrow commands above',
-        'and let the hook run the authoritative pipeline once at the end rather than running',
-        'the full check yourself every loop.',
+        `Tight feedback loops: \`${check} --bail\`, \`${check} --only types,lint\`, and`,
+        `\`${check} --changed\`.`,
+        '',
+        'If a stop-gate hook is configured (`.claude/settings.json` or `.cursor/hooks.json`),',
+        'it runs the check when a turn ends — so while iterating, prefer the narrow commands',
+        "above rather than running the full check yourself every loop. Read the gate's verdict",
+        'rather than assuming it covered everything: a repo can narrow the gate with `gate` in',
+        '`checkride.config.json`, and a narrowed one prints `NOT the full check` in every',
+        `verdict. That green is not the "done" defined above; run \`${check}\` in full before you`,
+        'claim the work is finished.',
         '',
         '### Baseline',
         '',
@@ -72,27 +215,29 @@ export function buildStanza(activeSlots) {
         'the ratchet, so the baseline only ever shrinks. Never add to the baseline to make a',
         'check pass; fix the finding.',
         '',
-        '### Module boundaries',
-        '',
-        'A module is a unit of encapsulation. A single file is a module; promote it to a',
-        'folder with a barrel `index.ts` when it grows internals worth hiding. A folder',
-        "module's `index.ts` is its only public surface — re-exports only, no logic. Import",
-        "siblings through `'../<sibling>/index.js'`, never their internals.",
-        '',
-        'Named exports only; no classes; `.js` extensions on relative imports.',
-        '',
+        ...(activeSlots.includes('struct') ? structSection() : []),
+        ...(proseExemplars !== null ? proseSection(proseExemplars) : []),
         `Active checks in this repo: ${activeSlots.join(', ')}.`,
     ].join('\n');
 }
 /**
  * Insert or refresh the checkride stanza in an AGENTS.md body. Idempotent:
- * applying twice yields identical output.
+ * applying twice yields identical output. It rewrites the marked region without
+ * looking at what was there — callers gate on {@link inspectStanza} first.
  */
 export function applyStanza(content, body) {
-    const block = `${STANZA_BEGIN}\n\n${body}\n\n${STANZA_END}`;
-    const re = new RegExp(`${escapeRegex(STANZA_BEGIN)}[\\s\\S]*?${escapeRegex(STANZA_END)}`);
-    if (re.test(content)) {
-        return content.replace(re, block);
+    // A replacer function, not the string: a `$&` in the stanza would otherwise be
+    // read as a backreference.
+    const block = `${STANZA_BEGIN_PREFIX} hash=${stanzaStamp(body)} -->\n\n${body}\n\n${STANZA_END}`;
+    if (STANZA_RE.test(content)) {
+        return content.replace(STANZA_RE, () => block);
+    }
+    if (STANZA_BEGIN_RE.test(content)) {
+        // A begin marker with no end: replace the marker in place rather than
+        // appending a second block, which would leave two begins and make the next
+        // refresh swallow everything between them. What followed the orphaned marker
+        // stays where it is — now outside the markers, so nothing rewrites it again.
+        return content.replace(STANZA_BEGIN_RE, () => block);
     }
     if (content.trim().length === 0) {
         return `${block}\n`;
@@ -312,18 +457,57 @@ async function writePackage(w, dir, pkgName, value) {
     await put(w, join(dir, 'src', 'index.test.ts'), smokeTest(value));
 }
 /**
- * Write/refresh the Claude Code Stop hook unless opted out (`hook === false`),
- * using the repo's detected package manager (b7). Records the file when it
- * changed, else a no-op note in `skipped` when one is provided.
+ * Write/refresh the agent hooks unless opted out (`hook === false`), remove any
+ * named for removal, for the selected harnesses (default: detected) and the
+ * repo's detected package manager. Records each file when it changed, else a
+ * no-op note in `skipped` when one is provided.
+ *
+ * `--no-hook` and `--remove-hook` compose rather than conflict: the first says
+ * "write nothing", the second "take this one out", and together they mean
+ * "remove the gate and leave the rest of the setup untouched" — which is the
+ * whole point of being able to drop a hook after the fact.
+ */
+async function writeHook(w, options, skipped) {
+    const remove = options.removeHooks ?? [];
+    if (options.hook === false && remove.length === 0)
+        return;
+    const hooks = options.hook === false ? [] : options.hooks;
+    const result = await writeHooks(w.cwd, {
+        dryRun: w.dryRun,
+        ...(hooks ? { hooks } : {}),
+        ...(remove.length > 0 ? { remove } : {}),
+        ...(options.harnesses ? { harnesses: options.harnesses } : {}),
+    });
+    record(w, result.files, skipped);
+}
+/**
+ * Write the bundled skills for every selected harness that cannot install them
+ * as a plugin. Only Cursor needs this today; Claude Code gets the same two
+ * skills from `.claude-plugin/`, installed once for every repo.
+ *
+ * Unlike the hooks this is not covered by `--no-hook`: that flag turns off the
+ * mechanical gate, and a skill gates nothing.
  */
-async function writeHook(w, hook, skipped) {
-    if (hook === false)
+async function writeSkills(w, options, skipped) {
+    const harnesses = options.harnesses ?? detectHarnesses(w.cwd);
+    if (!harnesses.includes('cursor'))
         return;
-    const result = await writeStopHook(w.cwd, { dryRun: w.dryRun });
-    if (result.changed)
-        w.written.push(result.path);
-    else
-        skipped?.push(`${CLAUDE_SETTINGS_FILE} (Stop hook unchanged)`);
+    record(w, await writeCursorSkills(w.cwd, { dryRun: w.dryRun }), skipped);
+}
+/**
+ * Fold a writer's file list into the run's written/removed/skipped report. A
+ * deleted file is a change, but not a *write* — counting it as one would have
+ * `--remove-hook gate` report that it wrote a file it actually took away.
+ */
+function record(w, files, skipped) {
+    for (const f of files) {
+        if (!f.changed)
+            skipped?.push(`${f.path} (${f.removed === true ? 'absent' : 'unchanged'})`);
+        else if (f.removed === true)
+            w.removed.push(f.path);
+        else
+            w.written.push(f.path);
+    }
 }
 // ----------------------------------------------------------------------------
 // New-project mode
@@ -361,7 +545,7 @@ async function writeNewScaffold(w, s) {
  * into `.claude/settings.json` idempotently rather than overwriting.
  */
 async function planCollisions(s, cwd) {
-    const plan = { cwd, dryRun: true, written: [] };
+    const plan = { cwd, dryRun: true, written: [], removed: [] };
     await writeNewScaffold(plan, s);
     return plan.written.filter((rel) => existsSync(join(cwd, rel)));
 }
@@ -388,7 +572,7 @@ function resolveNewScaffold(options, cwd) {
     };
 }
 /**
- * Overwrite protection (D4): unless `force`, refuse rather than clobber any file
+ * Overwrite protection: unless `force`, refuse rather than clobber any file
  * the scaffold would write. Planning on a dry writer first means a collision
  * bails before a single real byte is written — the refusal writes nothing.
  */
@@ -412,14 +596,24 @@ function reportNew(stdout, shape, w, cwd) {
 async function initNew(options, cwd) {
     const scaffold = resolveNewScaffold(options, cwd);
     await assertNoCollisions(scaffold, cwd, options.force ?? false);
-    const w = { cwd, dryRun: options.dryRun ?? false, written: [] };
+    const w = { cwd, dryRun: options.dryRun ?? false, written: [], removed: [] };
     await writeNewScaffold(w, scaffold);
-    // Claude Code Stop hook (opt-out; step 12). A fresh project has no PM lockfile
+    // Claude Code Stop hook (opt-out). A fresh project has no PM lockfile
     // yet, so it resolves to the `pnpm` default — matching the generated scripts.
-    await writeHook(w, options.hook);
+    await writeHook(w, options);
+    await writeSkills(w, options);
     if (options.stdout)
         reportNew(options.stdout, scaffold.shape, w, cwd);
-    return { mode: 'new', shape: scaffold.shape, written: w.written, skipped: [], disabled: [], grandfathered: [], exitCode: 0 };
+    return {
+        mode: 'new',
+        shape: scaffold.shape,
+        written: w.written,
+        removed: w.removed,
+        skipped: [],
+        disabled: [],
+        grandfathered: [],
+        exitCode: 0,
+    };
 }
 // ----------------------------------------------------------------------------
 // Existing-project mode
@@ -433,9 +627,9 @@ async function readIfExists(path) {
     }
 }
 // ----------------------------------------------------------------------------
-// Publish-ready bundle (step 9): the library path scaffolds the opt-in artifact
+// Publish-ready bundle: the library path scaffolds the opt-in artifact
 // checks into `checkride.config.json` so a buildable library orders itself out
-// of the box (build → pack/smoke/attw/publint/snippets, D4).
+// of the box (build → pack/smoke/attw/publint/snippets).
 // ----------------------------------------------------------------------------
 /**
  * The publish-ready bundle, in wave order. Each slot's value is the adapter
@@ -446,7 +640,7 @@ async function readIfExists(path) {
 const PUBLISH_BUNDLE_SLOTS = ['build', 'publint', 'attw', 'pack', 'smoke', 'snippets'];
 /** `--add` values that expand to the whole bundle. */
 const PUBLISH_BUNDLE_ALIASES = new Set(['publish', 'bundle']);
-/** Printed (and recorded in `skipped`) when snippets is requested but no tagged fence exists (Q12). */
+/** Printed (and recorded in `skipped`) when snippets is requested but no tagged fence exists. */
 const SNIPPETS_POINTER = 'snippets-dist: no tagged fences found — add a `<!-- snippet: check -->` marker above a ' +
     'ts/typescript fence in README.md or docs/*.md to enable the doc-snippet typecheck';
 /**
@@ -465,9 +659,9 @@ function readInitManifest(cwd) {
 }
 /**
  * True when README.md or a non-recursive docs/*.md carries at least one tagged
- * snippet fence — the signal that gates scaffolding `snippets-dist` (Q12).
- * Reuses step 7's pure discovery/plan primitives so the detection matches what
- * the slot itself checks.
+ * snippet fence — the signal that gates scaffolding `snippets-dist`.
+ * Reuses the snippets module's pure discovery/plan primitives so the detection
+ * matches what the slot itself checks.
  */
 async function hasTaggedSnippets(cwd) {
     let docsEntries = [];
@@ -488,7 +682,7 @@ async function hasTaggedSnippets(cwd) {
 }
 /**
  * Fold the requested publish slots into config entries, gating `build` on a
- * build script and `snippets` (→ `snippets-dist`) on a tagged fence (Q12) — the
+ * build script and `snippets` (→ `snippets-dist`) on a tagged fence — the
  * two slots that would otherwise stand down as a skip (`build`) or hard-error on
  * zero snippets (`snippets`).
  */
@@ -540,16 +734,80 @@ function splitAdd(add, manifest) {
     }
     return { publishRequested, fileAdds };
 }
+/**
+ * The stanza's active-check list: the selection a default `checkride` run
+ * makes, resolved config-aware from disk. `inventory()` is the wrong input
+ * here — it has detection semantics and never reads checkride.config.json, so
+ * it under-reports the gate (opt-in slots the config opts in, custom checks)
+ * to the exact audience the stanza exists to inform. Mirrors `doctor`'s
+ * `defaultActive` derivation.
+ */
+function activeCheckSlots(cwd, slots, adapters) {
+    const resolved = resolveChecks({ slots, adapters, config: loadConfig(cwd), cwd });
+    return selectChecks(resolved, {})
+        .filter((r) => r.adapter !== null)
+        .map((r) => r.slot);
+}
+/**
+ * The voice-exemplars directory the repo's config names on its `prose` entry,
+ * or `null`. Read fresh at every stanza build rather than threaded from a
+ * caller, so the stanza and the config it describes cannot drift apart within
+ * one run — `initExisting` writes config between its stanza guard and its
+ * stanza write.
+ */
+function proseExemplarsDir(cwd) {
+    const entry = loadConfig(cwd)?.checks?.['prose'];
+    return entry && typeof entry === 'object' && 'use' in entry && typeof entry.exemplars === 'string'
+        ? entry.exemplars
+        : null;
+}
+const STANZA_REFUSALS = {
+    edited: 'it has been edited since checkride wrote it',
+    unstamped: 'it predates the stanza stamp and matches no wording checkride has released, so it has been changed since it was written',
+};
+/**
+ * Refuse to refresh a stanza that is not checkride's own output, so a repo's
+ * edge-case additions survive the next `init`/`agent-setup` instead of being
+ * silently overwritten. `opts.force` overrides.
+ *
+ * Called before either entry point writes anything, so a refusal leaves the repo
+ * exactly as it found it (the same rule `assertNoCollisions` follows in new
+ * mode). In existing mode that puts it ahead of the config write, so `body` here
+ * reflects the config as it is on disk now rather than as this run will leave
+ * it — which no longer costs anything: a stamped stanza is checked against its
+ * own stamp, and an unstamped one against a registry of released wordings that
+ * ignores the active-checks line entirely. Neither reads `body`'s slot list.
+ *
+ * Hook management deliberately does not come through here — see the `hooks`
+ * command, which never touches AGENTS.md and so has nothing to refuse.
+ */
+async function assertStanzaUnedited(cwd, body, opts) {
+    if (opts.force === true)
+        return;
+    const existing = await readIfExists(join(cwd, 'AGENTS.md'));
+    if (existing === null)
+        return;
+    const state = inspectStanza(existing, body);
+    if (state === 'absent' || state === 'pristine')
+        return;
+    const remedy = state === 'edited'
+        ? 'Move your additions outside the markers — checkride never rewrites what is outside them — or re-run with --force to discard them and refresh.'
+        : 'If you have not edited it, re-run with --force: the refreshed stanza carries a stamp, and later runs tell an edit from a refresh on their own.';
+    throw new Error(`refusing to overwrite the checkride stanza in AGENTS.md: ${STANZA_REFUSALS[state]}.\n  ${remedy}`);
+}
 /**
  * Write (or refresh) the AGENTS.md stanza for `slots`, idempotently: it writes
  * only when the applied stanza differs from the current file, records the outcome
  * on `w`/`skipped`, and honours dry-run. Shared by `initExisting` and
  * `runAgentSetup` (both create-or-refresh the same stanza).
+ *
+ * It rewrites the marked region unconditionally; whether that is allowed is
+ * {@link assertStanzaUnedited}'s call, made before either caller writes anything.
  */
-async function writeAgentsStanza(w, cwd, slots, skipped) {
+async function writeAgentsStanza(w, cwd, slots, pm, skipped) {
     const agentsPath = join(cwd, 'AGENTS.md');
     const existing = await readIfExists(agentsPath);
-    const nextAgents = applyStanza(existing ?? '', buildStanza(slots));
+    const nextAgents = applyStanza(existing ?? '', buildStanza(slots, pm, proseExemplarsDir(cwd)));
     if (nextAgents !== existing) {
         if (!w.dryRun)
             await writeFile(agentsPath, nextAgents);
@@ -566,12 +824,19 @@ const ADD_CONFIGS = {
     types: [['shared/tsconfig.base.json', 'tsconfig.base.json'], ['flat/tsconfig.json', 'tsconfig.json']],
     format: [['shared/prettierrc.json', '.prettierrc.json']],
     lint: [['shared/oxlintrc.json', '.oxlintrc.json']],
+    // `struct` scaffolds the boundary rule and stops. New-mode `init` writes all
+    // four (`writeSharedStatic`), and that is a different bargain: there checkride
+    // is creating the package, so its house style has nobody to override. Here the
+    // repo already exists and has already decided. `no-class`, `no-default-export`
+    // and `require-js-extension` are style and module-system opinions — a repo
+    // with classes, default exports, or bundler resolution goes red on adoption
+    // for writing the code it always wrote, which reads as checkride being broken.
+    // `no-deep-sibling-import` is the one that makes `struct` the slot it is, and
+    // failing it means what it says. The other three stay one copy away, in
+    // `docs/deep-modules.md`.
     struct: [
         ['shared/sgconfig.yml', 'sgconfig.yml'],
-        ['shared/rules/no-class.yml', 'rules/no-class.yml'],
-        ['shared/rules/no-default-export.yml', 'rules/no-default-export.yml'],
         ['shared/rules/no-deep-sibling-import.yml', 'rules/no-deep-sibling-import.yml'],
-        ['shared/rules/require-js-extension.yml', 'rules/require-js-extension.yml'],
     ],
     dead: [['flat/fallow.toml', 'fallow.toml']],
     // dupes/health are the same fallow tool + config as `dead`, just other slots.
@@ -580,6 +845,23 @@ const ADD_CONFIGS = {
     test: [['shared/vitest.config.ts.template', 'vitest.config.ts']],
     docs: [['shared/markdownlint-cli2.jsonc', '.markdownlint-cli2.jsonc']],
     spell: [['shared/cspell.json', 'cspell.json']],
+    // `prose` is the one slot whose config alone scaffolds nothing usable: vale's
+    // .vale.ini is a pointer at a StylesPath, and an empty StylesPath lints
+    // nothing. The rules are the deliverable, so they come with it. They are the
+    // repo's from the moment they land — plain YAML, no `vale sync`, no upstream
+    // to track — which is also why `struct`'s restraint does not apply here:
+    // ast-grep's extra rules assert what the repo's code already is, while these
+    // assert nothing about code at all, and a prose rule the author disagrees
+    // with is deleted in one line.
+    prose: [
+        ['shared/vale.ini', '.vale.ini'],
+        ['shared/styles/Repo/Drift.yml', '.vale/styles/Repo/Drift.yml'],
+        ['shared/styles/Repo/Latin.yml', '.vale/styles/Repo/Latin.yml'],
+        ['shared/styles/Repo/LyHyphen.yml', '.vale/styles/Repo/LyHyphen.yml'],
+        ['shared/styles/Repo/Minted.yml', '.vale/styles/Repo/Minted.yml'],
+        ['shared/styles/Repo/ThereIs.yml', '.vale/styles/Repo/ThereIs.yml'],
+        ['shared/styles/Repo/Weasel.yml', '.vale/styles/Repo/Weasel.yml'],
+    ],
 };
 /** `--add <slots>`: scaffold blessed-default configs for the named empty slots. */
 async function addConfigs(w, add, skipped) {
@@ -625,7 +907,7 @@ async function addCheckAlias(w, skipped) {
     w.written.push('package.json (added check script)');
 }
 /**
- * Classify each failing adopted slot. `--baseline` (step 6 / c10) grandfathers a
+ * Classify each failing adopted slot. `--baseline` grandfathers a
  * failing *fingerprintable* slot (kept enabled; the baseline masks its debt and
  * the ratchet carries the cleanup); a failing slot with no extractor can't be
  * grandfathered, so it still falls back to a `false` disable. Without
@@ -652,7 +934,7 @@ async function captureBaselineIfNeeded(options, cwd, grandfathered, dryRun) {
 }
 /**
  * Write checkride.config.json for the adopted tools (disabled failures as
- * `false`) plus the publish-ready bundle (step 9); never clobber an existing one.
+ * `false`) plus the publish-ready bundle; never clobber an existing one.
  */
 async function writeExistingConfig(w, cwd, adopted, disabledSet, bundleChecks, skipped) {
     if (existsSync(join(cwd, 'checkride.config.json'))) {
@@ -667,7 +949,7 @@ async function writeExistingConfig(w, cwd, adopted, disabledSet, bundleChecks, s
             checks[i.slot] = i.adapter;
     }
     // The opt-in publish bundle follows the adopted default slots; explicit
-    // entries opt these slots into the run (D4 — the library orders itself).
+    // entries opt these slots into the run (the library orders itself).
     for (const [slot, adapter] of Object.entries(bundleChecks))
         checks[slot] = adapter;
     const config = { $schema: configSchemaUrl(productVersion()), checks };
@@ -708,7 +990,7 @@ function reportExisting(stdout, adopted, w, grandfathered, disabled) {
     }
 }
 /**
- * Plan the publish-ready bundle (step 9) for existing-repo init. Only meaningful
+ * Plan the publish-ready bundle for existing-repo init. Only meaningful
  * when a config will actually be written: `writeExistingConfig` never clobbers an
  * existing `checkride.config.json`, so an existing config means the bundle has
  * nowhere to land. The bundle is scaffolded *enabled* — not probed/disabled like
@@ -733,8 +1015,12 @@ async function initExisting(options, cwd) {
     const adapters = options.adapters ?? ADAPTERS;
     const slots = options.slots ?? SLOTS;
     const manifest = readInitManifest(cwd);
-    const w = { cwd, dryRun: options.dryRun ?? false, written: [] };
+    const w = { cwd, dryRun: options.dryRun ?? false, written: [], removed: [] };
     const skipped = [];
+    const pm = detectPackageManager({ cwd });
+    // Before the first write: a stanza this repo has customized stops the run
+    // rather than being clobbered by the refresh below.
+    await assertStanzaUnedited(cwd, buildStanza(activeCheckSlots(cwd, slots, adapters), pm, proseExemplarsDir(cwd)), options);
     // Route --add: publish slots (and the library path) opt into the bundle; the
     // rest scaffold blessed configs before inventory, so they're detected this run.
     const { publishRequested, fileAdds } = splitAdd(options.add ?? [], manifest);
@@ -746,24 +1032,35 @@ async function initExisting(options, cwd) {
     const failing = new Set(await probe(adopted.map((i) => i.slot), cwd));
     const { grandfathered, disabled } = resolveAdoptionPlan(adopted, failing, options.baseline ?? false);
     await captureBaselineIfNeeded(options, cwd, grandfathered, w.dryRun);
-    // Publish-ready bundle (step 9): planned only when a config will be written.
+    // Publish-ready bundle: planned only when a config will be written.
     const bundle = await planInitBundle(publishRequested, manifest, cwd);
     if (bundle.snippetsPointer)
         skipped.push(bundle.snippetsPointer);
     await writeExistingConfig(w, cwd, adopted, new Set(disabled), bundle.checks, skipped);
     await ensureGitignore(w, cwd, skipped);
-    // package.json: add the `check: checkride` alias (decision 8) if missing.
+    // package.json: add the `check: checkride` alias if missing.
     await addCheckAlias(w, skipped);
-    // AGENTS.md stanza (create or refresh, idempotent).
-    await writeAgentsStanza(w, cwd, adopted.map((i) => i.slot), skipped);
+    // AGENTS.md stanza (create or refresh, idempotent), derived from the config
+    // written above so it reports the gate as configured, not as detected.
+    await writeAgentsStanza(w, cwd, activeCheckSlots(cwd, slots, adapters), pm, skipped);
     await writeClaudePointer(w, cwd, skipped);
-    // Claude Code Stop hook (opt-out; step 12), using the repo's detected PM (b7).
-    await writeHook(w, options.hook, skipped);
+    // Claude Code Stop hook (opt-out), using the repo's detected PM.
+    await writeHook(w, options, skipped);
+    await writeSkills(w, options, skipped);
     if (options.stdout) {
         reportExisting(options.stdout, adopted, w, grandfathered, disabled);
         reportInitBundle(options.stdout, bundle);
     }
-    return { mode: 'existing', shape: null, written: w.written, skipped, disabled, grandfathered, exitCode: 0 };
+    return {
+        mode: 'existing',
+        shape: null,
+        written: w.written,
+        removed: w.removed,
+        skipped,
+        disabled,
+        grandfathered,
+        exitCode: 0,
+    };
 }
 // ----------------------------------------------------------------------------
 // Entry
@@ -780,25 +1077,32 @@ export async function runInit(options) {
 /**
  * `checkride agent-setup` — wire the agent contract into an *existing* repo
  * without a full `init`: the `check` alias the hook resolves to, the AGENTS.md
- * stanza (the human-readable contract), and the Claude Code Stop hook (the
- * mechanical gate). Every write is additive and idempotent — a second run is a
- * no-op — and the hook is opt-out (`hook: false`).
+ * stanza (the human-readable contract), the stop-gate hooks for every detected
+ * harness (the mechanical gate), and the skills a harness cannot get from the
+ * bundled plugin. Every write is additive and idempotent — a second run is a
+ * no-op — and the hooks are opt-out (`hook: false`).
  */
 export async function runAgentSetup(options) {
     const cwd = options.cwd ?? process.cwd();
     const slots = options.slots ?? SLOTS;
     const adapters = options.adapters ?? ADAPTERS;
-    const w = { cwd, dryRun: options.dryRun ?? false, written: [] };
+    const w = { cwd, dryRun: options.dryRun ?? false, written: [], removed: [] };
     const skipped = [];
+    const stanzaSlots = activeCheckSlots(cwd, slots, adapters);
+    const pm = detectPackageManager({ cwd });
+    // Before the first write: a stanza this repo has customized stops the run
+    // rather than being clobbered by the refresh below.
+    await assertStanzaUnedited(cwd, buildStanza(stanzaSlots, pm, proseExemplarsDir(cwd)), options);
     // The `check` alias the hook's `<pm> run check` resolves to (never clobbers).
     await addCheckAlias(w, skipped);
-    // AGENTS.md stanza for the currently-adopted slots (create or refresh).
-    const adopted = inventory({ cwd, slots, adapters }).filter((i) => i.status === 'adopted');
-    await writeAgentsStanza(w, cwd, adopted.map((i) => i.slot), skipped);
-    await writeHook(w, options.hook, skipped);
+    // AGENTS.md stanza for the checks the default run selects (create or refresh).
+    await writeAgentsStanza(w, cwd, stanzaSlots, pm, skipped);
+    await writeHook(w, options, skipped);
+    await writeSkills(w, options, skipped);
     if (options.stdout) {
-        options.stdout.write(`checkride agent-setup: wrote ${w.written.length} file(s)${w.dryRun ? ' [dry run]' : ''}.\n`);
+        const removed = w.removed.length > 0 ? `, removed ${w.removed.length}` : '';
+        options.stdout.write(`checkride agent-setup: wrote ${w.written.length} file(s)${removed}${w.dryRun ? ' [dry run]' : ''}.\n`);
     }
-    return { written: w.written, skipped, exitCode: 0 };
+    return { written: w.written, removed: w.removed, skipped, exitCode: 0 };
 }
 //# sourceMappingURL=init.js.map