convene-cli 1.1.1 → 1.3.0

package/dist/catalog/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CATALOG_VERSION = exports.CATALOG = void 0;
+exports.loadCatalog = loadCatalog;
+const catalog_generated_1 = require("./catalog.generated");
+Object.defineProperty(exports, "CATALOG", { enumerable: true, get: function () { return catalog_generated_1.CATALOG; } });
+Object.defineProperty(exports, "CATALOG_VERSION", { enumerable: true, get: function () { return catalog_generated_1.CATALOG_VERSION; } });
+/**
+ * Load the catalog, preferring the live server copy when `api` is given. Any
+ * failure (no client, non-ok status, network error, empty body) silently falls
+ * back to the bundled mirror — this never throws.
+ */
+async function loadCatalog(api, timeoutMs = 5_000) {
+    if (api) {
+        try {
+            const res = await api.getCatalog(timeoutMs);
+            if (res.ok && res.json && Array.isArray(res.json.practices) && res.json.version) {
+                return { catalog: res.json, source: 'live' };
+            }
+        }
+        catch {
+            /* fail-soft → bundled */
+        }
+    }
+    return { catalog: catalog_generated_1.CATALOG, source: 'bundled' };
+}

package/dist/catalog/manifest.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.semverLt = semverLt;
+exports.bumpClass = bumpClass;
+exports.compareToCatalog = compareToCatalog;
+/**
+ * Strict SemVer less-than over the dotted numeric core (pre-release/build
+ * metadata ignored — the catalog uses plain X.Y.Z). Missing components read as
+ * 0 so "1.2" < "1.2.1". Non-numeric components compare as 0.
+ */
+function semverLt(a, b) {
+    const pa = a.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    const pb = b.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x < y)
+            return true;
+        if (x > y)
+            return false;
+    }
+    return false;
+}
+/**
+ * Classify the bump from `from` → `to` over the dotted numeric core: 'major' if
+ * the X differs, else 'minor' if Y differs, else 'patch' if Z differs, else
+ * 'none'. A DOWNGRADE (to < from on any component) reads as 'none' — the repo is
+ * not behind, so update has nothing to take. Missing components read as 0.
+ */
+function bumpClass(from, to) {
+    if (!semverLt(from, to))
+        return 'none'; // equal or ahead → nothing to take
+    const pa = from.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    const pb = to.split('.').map((n) => Number.parseInt(n, 10) || 0);
+    if ((pa[0] ?? 0) !== (pb[0] ?? 0))
+        return 'major';
+    if ((pa[1] ?? 0) !== (pb[1] ?? 0))
+        return 'minor';
+    return 'patch';
+}
+/** Compare a repo's adopted manifest against the catalog. Pure; never throws. */
+function compareToCatalog(manifest, catalog) {
+    const byId = new Map(catalog.practices.map((p) => [p.id, p]));
+    const repoVersion = manifest.catalogVersion;
+    const catalogVersion = catalog.version;
+    const adopted = [];
+    const unknownIds = [];
+    for (const entry of manifest.practices) {
+        const cat = byId.get(entry.id);
+        if (!cat) {
+            unknownIds.push(entry.id);
+            continue;
+        }
+        adopted.push({
+            id: entry.id,
+            title: cat.title,
+            manifestVersion: entry.version,
+            catalogVersion: cat.version,
+            level: entry.level,
+            outdated: semverLt(entry.version, cat.version),
+        });
+    }
+    return {
+        repoVersion,
+        catalogVersion,
+        behind: repoVersion !== catalogVersion,
+        adopted,
+        unknownIds,
+    };
+}

package/dist/catalog/materialize.js

@@ -0,0 +1,516 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GITIGNORE_PRACTICES_MARKER = exports.REF_END = exports.REF_BEGIN = exports.PRACTICES_DOC_HEADER = exports.PRACTICE_END = exports.PRACTICE_BEGIN = void 0;
+exports.renderPracticeSection = renderPracticeSection;
+exports.regionHash = regionHash;
+exports.currentRegionHashes = currentRegionHashes;
+exports.extractPracticeBlocks = extractPracticeBlocks;
+exports.splicePreservedBlocks = splicePreservedBlocks;
+exports.detectDrift = detectDrift;
+exports.buildPracticesDoc = buildPracticesDoc;
+exports.upsertRefRegion = upsertRefRegion;
+exports.removeRefRegion = removeRefRegion;
+exports.isHookLevel = isHookLevel;
+exports.mergeDenyArray = mergeDenyArray;
+exports.mergeSettingsJson = mergeSettingsJson;
+exports.denyEntriesOf = denyEntriesOf;
+exports.ensureGitignoreLines = ensureGitignoreLines;
+exports.removeGitignoreLines = removeGitignoreLines;
+exports.materializePractices = materializePractices;
+exports.dematerializePractices = dematerializePractices;
+/**
+ * Materialize adopted best practices into a repo — the Phase-2 doc/ref core PLUS
+ * the Phase-3 ENFORCEMENT artifacts (settingsJson / gitignore / settingsHook).
+ * PURE-ish: the rendering helpers (renderPracticeSection / buildPracticesDoc /
+ * regionHash / upsertRefRegion / removeRefRegion / mergeDenyArray / ensureGitignoreLines)
+ * are side-effect-free and deterministic (no dates, byte-identical for identical
+ * inputs); only materialize/dematerialize touch the filesystem, and they do so
+ * idempotently via writeIfChanged.
+ *
+ * What lands in a repo when practices are adopted, BY LEVEL:
+ *   - .convene/best-practices.md       — the full managed catalog of adopted practices.
+ *   - a small ref region in CLAUDE.md   (@.convene/best-practices.md) and AGENTS.md.
+ *   - any `doc` artifact under .convene/practices/ (write-if-absent).
+ *   - settingsJson (permissions.deny) — ONLY at hook-hard (advisory → doc stanza only).
+ *   - gitignore lines — at ANY hook level (hook-soft / hook-hard).
+ *   - settingsHook (PreToolUse/Stop guards) — at hook-soft OR hook-hard, wired via
+ *     ensureHook into the COMMITTED .claude/settings.json (only when init is
+ *     installing the project settings — respects --no-hook).
+ *
+ * Modeled precisely on init.ts (upsertMarkerBlock / stripBetween / writeIfChanged):
+ * same marker discipline, same blank-line/newline collapsing, same "git history is
+ * the backup" no-.bak ethos. node:crypto is the only new dependency.
+ */
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const hook_1 = require("../hook");
+// ── Markers ────────────────────────────────────────────────────────────────
+// Per-practice markers carry the version so a drift/update pass can find a stale
+// region. The ref region markers (added to CLAUDE.md/AGENTS.md) are a separate,
+// versionless pair — that block's content is a single stable @-import line.
+/** Begin marker for one practice's section inside .convene/best-practices.md. */
+const PRACTICE_BEGIN = (id, version) => `<!-- convene:practice ${id} v${version} -->`;
+exports.PRACTICE_BEGIN = PRACTICE_BEGIN;
+/** End marker for one practice's section. */
+const PRACTICE_END = (id) => `<!-- /convene:practice ${id} -->`;
+exports.PRACTICE_END = PRACTICE_END;
+/** Stable managed header for .convene/best-practices.md — no timestamps (PURE). */
+exports.PRACTICES_DOC_HEADER = '<!-- convene:best-practices (managed) — do not edit between the practice markers; local edits are overwritten on update -->\n' +
+    '# Adopted best practices\n\n' +
+    'This file is generated and maintained by Convene from the shared best-practices catalog.\n' +
+    'Each section below is an adopted practice, pinned at the level your repo chose.\n';
+/** Begin/end markers for the small ref region added to CLAUDE.md / AGENTS.md. */
+exports.REF_BEGIN = '<!-- convene:practices:begin -->';
+exports.REF_END = '<!-- convene:practices:end -->';
+// ── Pure rendering ───────────────────────────────────────────────────────────
+/**
+ * A LEAN markdown section for one adopted practice: a heading tagged with tier and
+ * level, the practice's claudeMd body (if any), then a one-line note per `ci` /
+ * `doc` artifact. Pure (no dates); kept tight because this loads as guidance.
+ */
+function renderPracticeSection(p, level) {
+    const lines = [`## ${p.title}  [${p.tier} · ${level}]`];
+    for (const a of p.artifacts) {
+        if (a.kind === 'claudeMd')
+            lines.push(a.body);
+    }
+    for (const a of p.artifacts) {
+        if (a.kind === 'ci')
+            lines.push(`CI: ${a.body}`);
+        else if (a.kind === 'doc')
+            lines.push(`Doc: see ${a.path}`);
+    }
+    return lines.join('\n');
+}
+/** sha256 hex of a section's text — the manifest's drift-detection hash. */
+function regionHash(section) {
+    return node_crypto_1.default.createHash('sha256').update(section, 'utf8').digest('hex');
+}
+/** Path to a repo's managed best-practices doc. */
+function practicesDocPath(top) {
+    return node_path_1.default.join(top, '.convene', 'best-practices.md');
+}
+/**
+ * Parse .convene/best-practices.md at `top` and return a map of practice id →
+ * regionHash of that practice's CURRENT inner body (the text between its
+ * PRACTICE_BEGIN/END markers, with the single wrapping newlines buildPracticesDoc
+ * adds stripped). The hash is taken over the same string renderPracticeSection
+ * produces, so a clean (unedited) region hashes byte-identical to the manifest
+ * entry. A missing/unreadable doc → empty map (no drift can be asserted). Pure
+ * read; never throws.
+ */
+function currentRegionHashes(top) {
+    const out = new Map();
+    let doc;
+    try {
+        doc = node_fs_1.default.readFileSync(practicesDocPath(top), 'utf8');
+    }
+    catch {
+        return out; // no doc → nothing to hash
+    }
+    // PRACTICE_BEGIN(id, v) and PRACTICE_END(id) are HTML comments; capture the id
+    // from BEGIN and the inner body up to the matching END. buildPracticesDoc wraps
+    // the section as: BEGIN + '\n' + section + '\n' + END, so trim exactly one
+    // leading and one trailing newline to recover the rendered section verbatim.
+    const re = /<!-- convene:practice (\S+) v\S+ -->([\s\S]*?)<!-- \/convene:practice \1 -->/g;
+    let m;
+    while ((m = re.exec(doc)) !== null) {
+        const id = m[1];
+        let body = m[2];
+        if (body.startsWith('\n'))
+            body = body.slice(1);
+        if (body.endsWith('\n'))
+            body = body.slice(0, -1);
+        out.set(id, regionHash(body));
+    }
+    return out;
+}
+/**
+ * Extract each practice's FULL on-disk block (BEGIN marker → END marker inclusive,
+ * verbatim) from .convene/best-practices.md, keyed by id. `convene update` uses
+ * this to PRESERVE skipped (drifted / major-bump) sections byte-for-byte while
+ * re-materializing the rest. Missing/unreadable doc → empty map. Pure read.
+ */
+function extractPracticeBlocks(top) {
+    const out = new Map();
+    let doc;
+    try {
+        doc = node_fs_1.default.readFileSync(practicesDocPath(top), 'utf8');
+    }
+    catch {
+        return out;
+    }
+    const re = /<!-- convene:practice (\S+) v\S+ -->[\s\S]*?<!-- \/convene:practice \1 -->/g;
+    let m;
+    while ((m = re.exec(doc)) !== null)
+        out.set(m[1], m[0]);
+    return out;
+}
+/**
+ * Replace each practice block in .convene/best-practices.md whose id appears in
+ * `blocks` with the supplied verbatim block text (BEGIN→END inclusive). Used by
+ * `convene update --apply` to splice PRESERVED skipped sections back into a
+ * freshly re-materialized doc, so a skipped (drifted/major) region is left exactly
+ * as it sat on disk. Practices not present in the doc are appended in the order
+ * given (defensive; normally every id is already present). Writes only if changed.
+ */
+function splicePreservedBlocks(top, blocks) {
+    if (blocks.size === 0)
+        return;
+    const file = practicesDocPath(top);
+    let doc;
+    try {
+        doc = node_fs_1.default.readFileSync(file, 'utf8');
+    }
+    catch {
+        return;
+    }
+    let next = doc;
+    const appendIds = [];
+    for (const [id, block] of blocks) {
+        const re = new RegExp(`<!-- convene:practice ${escapeRe(id)} v\\S+ -->[\\s\\S]*?<!-- /convene:practice ${escapeRe(id)} -->`);
+        if (re.test(next))
+            next = next.replace(re, () => block);
+        else
+            appendIds.push(id);
+    }
+    for (const id of appendIds) {
+        next = (next.endsWith('\n') ? next : next + '\n') + '\n' + blocks.get(id) + '\n';
+    }
+    writeIfChanged(file, next);
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Return the manifest practice ids whose CURRENT region hash (as the doc sits on
+ * disk) differs from the hash recorded in the manifest — i.e. the practice's
+ * section was hand-edited locally. A practice absent from the doc (no current
+ * hash) is NOT reported as drift (it is a missing region, a different condition);
+ * only a present-but-changed region counts. Side-effect-free; never throws.
+ */
+function detectDrift(top, manifest) {
+    const current = currentRegionHashes(top);
+    const drifted = [];
+    for (const entry of manifest.practices) {
+        const cur = current.get(entry.id);
+        if (cur !== undefined && cur !== entry.hash)
+            drifted.push(entry.id);
+    }
+    return drifted;
+}
+/**
+ * The full .convene/best-practices.md for a set of selections: the managed header
+ * followed by each adopted practice wrapped in its PRACTICE_BEGIN/END markers, in
+ * CATALOG order (selections not in the catalog are dropped). PURE → byte-identical
+ * for the same (slug, selections, catalog).
+ */
+function buildPracticesDoc(slug, selections) {
+    const parts = [exports.PRACTICES_DOC_HEADER];
+    for (const { practice, level } of selections) {
+        parts.push((0, exports.PRACTICE_BEGIN)(practice.id, practice.version) +
+            '\n' +
+            renderPracticeSection(practice, level) +
+            '\n' +
+            (0, exports.PRACTICE_END)(practice.id));
+    }
+    // Header + one blank line between each block; trailing newline.
+    return parts.join('\n\n') + '\n';
+}
+/**
+ * Insert/replace the REF_BEGIN..REF_END region in a CLAUDE.md / AGENTS.md.
+ * Modeled exactly on init.ts upsertMarkerBlock: replace between markers if present,
+ * else append with the same blank-line separator discipline. `refBody` is the
+ * region's inner content (the markers are added here).
+ */
+function upsertRefRegion(content, refBody) {
+    const block = exports.REF_BEGIN + '\n' + refBody + '\n' + exports.REF_END;
+    const start = content.indexOf(exports.REF_BEGIN);
+    const end = content.indexOf(exports.REF_END);
+    if (start >= 0 && end > start) {
+        return content.slice(0, start) + block + content.slice(end + exports.REF_END.length);
+    }
+    const sep = content.length === 0 ? '' : content.endsWith('\n') ? '\n' : '\n\n';
+    return content + sep + block + '\n';
+}
+/**
+ * Inverse of upsertRefRegion (off-board) — removes the ref region, collapsing the
+ * blank separator before it and the trailing newline after, so a file that ONLY
+ * ever held the region returns to '' (caller deletes it) and a file with
+ * pre-existing content round-trips BYTE-IDENTICAL. Mirrors init.ts stripBetween.
+ */
+function removeRefRegion(content) {
+    const start = content.indexOf(exports.REF_BEGIN);
+    const endIdx = content.indexOf(exports.REF_END);
+    if (start < 0 || endIdx <= start)
+        return { content, removed: false };
+    const head = content.slice(0, start).replace(/\n+$/, '');
+    const tail = content.slice(endIdx + exports.REF_END.length).replace(/^\n+/, '');
+    let joined = head && tail ? head + '\n\n' + tail : head + tail;
+    if (joined.length > 0 && !joined.endsWith('\n'))
+        joined += '\n';
+    return { content: joined, removed: true };
+}
+// ── Pure enforcement helpers (Phase 3) ───────────────────────────────────────
+// Side-effect-free + deterministic so they unit-test without a repo and so a re-run
+// is byte-identical. A level "wires a hook" iff it is hook-soft or hook-hard.
+/** A mechanical hook level — the gate is wired in settings (settingsHook artifacts). */
+function isHookLevel(level) {
+    return level === 'hook-soft' || level === 'hook-hard';
+}
+/**
+ * UNION two permissions.deny string arrays, deduped, in a STABLE order: the existing
+ * entries first (their original order preserved), then any artifact entries not
+ * already present (in artifact order). Idempotent — re-merging the same set is a
+ * no-op, so a re-run stays byte-identical.
+ */
+function mergeDenyArray(existing, add) {
+    const out = [];
+    const seen = new Set();
+    const push = (v) => {
+        if (typeof v === 'string' && !seen.has(v)) {
+            seen.add(v);
+            out.push(v);
+        }
+    };
+    if (Array.isArray(existing))
+        for (const e of existing)
+            push(e);
+    for (const a of add)
+        push(a);
+    return out;
+}
+/**
+ * Deep-merge a permissions-deny settingsJson artifact into a parsed settings object
+ * (mutates + returns it). UNIONs permissions.deny; every OTHER key is preserved
+ * untouched. Only the `permissions.deny` shape is handled (the only settingsJson
+ * artifact the catalog ships); other merge keys are ignored defensively.
+ */
+function mergeSettingsJson(settings, art) {
+    const next = settings && typeof settings === 'object' ? settings : {};
+    const deny = art.merge?.permissions?.deny;
+    if (Array.isArray(deny) && deny.length) {
+        next.permissions = next.permissions && typeof next.permissions === 'object' ? next.permissions : {};
+        next.permissions.deny = mergeDenyArray(next.permissions.deny, deny);
+    }
+    return next;
+}
+/**
+ * The full set of permissions.deny entries a settingsJson artifact contributes —
+ * used by off-board to subtract EXACTLY those (and only those) on reversal. Pure.
+ */
+function denyEntriesOf(art) {
+    const deny = art.merge?.permissions?.deny;
+    return Array.isArray(deny) ? deny.filter((d) => typeof d === 'string') : [];
+}
+/**
+ * Append `lines` to a .gitignore body idempotently (never duplicate an existing
+ * line, ignoring surrounding whitespace), under a single managed marker so off-board
+ * can recognize + strip them. Mirrors init's ensureGitignoreGuard blank-line/newline
+ * discipline. PURE — returns the next content (caller writes if changed).
+ */
+exports.GITIGNORE_PRACTICES_MARKER = '# convene best-practices (managed)';
+function ensureGitignoreLines(content, lines) {
+    const present = new Set(content.split('\n').map((l) => l.trim()));
+    const missing = lines.filter((l) => !present.has(l.trim()));
+    if (missing.length === 0)
+        return content;
+    const hasMarker = content.split('\n').some((l) => l.trim() === exports.GITIGNORE_PRACTICES_MARKER);
+    const block = (hasMarker ? '' : exports.GITIGNORE_PRACTICES_MARKER + '\n') + missing.join('\n') + '\n';
+    const sep = content.length === 0 ? '' : content.endsWith('\n') ? '' : '\n';
+    return content + sep + block;
+}
+/**
+ * Remove `lines` (and the managed marker once no managed lines remain) from a
+ * .gitignore body — the inverse of ensureGitignoreLines. Returns the next content
+ * and whether anything changed. Collapses a trailing blank run so a file that ONLY
+ * held the managed block round-trips byte-identical.
+ */
+function removeGitignoreLines(content, lines) {
+    // Drop the managed practice lines AND the managed marker — the only content the
+    // single managed block ever holds, so removing all of it returns the file to its
+    // pre-materialize body.
+    const drop = new Set([...lines.map((l) => l.trim()), exports.GITIGNORE_PRACTICES_MARKER]);
+    const srcLines = content.split('\n');
+    let removed = false;
+    const kept = srcLines.filter((l) => {
+        if (drop.has(l.trim())) {
+            removed = true;
+            return false;
+        }
+        return true;
+    });
+    if (!removed)
+        return { content, removed: false };
+    let joined = kept.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\n+$/, '');
+    if (joined.length > 0)
+        joined += '\n';
+    return { content: joined, removed: true };
+}
+// ── fs orchestration ─────────────────────────────────────────────────────────
+// Mirrors init.ts: every file lives in the git repo, so git history IS the backup;
+// write only when content actually changes (idempotent / merge-safe).
+function writeIfChanged(file, content) {
+    const old = node_fs_1.default.existsSync(file) ? node_fs_1.default.readFileSync(file, 'utf8') : null;
+    if (old === content)
+        return;
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    node_fs_1.default.writeFileSync(file, content);
+}
+/** The inner body of the CLAUDE.md ref region — a single @-import line. */
+const CLAUDE_REF_BODY = '@.convene/best-practices.md';
+/** The inner body of the AGENTS.md ref region — a prose pointer (no @-import). */
+const AGENTS_REF_BODY = '**Adopted best practices:** see `.convene/best-practices.md` (managed by Convene).';
+/** Phase-3 settingsHook practices that init's OWN hooks already cover — do NOT wire
+ *  them again. `recheck-main-before-deploy-lane` is gated by init's `convene gate-push`
+ *  PreToolUse/PostToolUse hooks; double-gating it would fire two deploy gates. */
+const HOOK_COVERED_BY_INIT = new Set(['recheck-main-before-deploy-lane']);
+/**
+ * Materialize the adopted selections into the repo at `top` and return the manifest
+ * entries (in CATALOG order). Idempotent: byte-identical inputs → byte-identical
+ * tree. CRITICAL no-op contract: an EMPTY `selections` writes NOTHING and returns
+ * [], so a plain onboarding stays byte-identical to its pre-catalog form.
+ *
+ * Writes, applied PER ADOPTED PRACTICE ACCORDING TO LEVEL:
+ *   - .convene/best-practices.md; the ref region in CLAUDE.md + AGENTS.md; and each
+ *     adopted practice's `doc` artifacts (write-if-absent) — at ANY level.
+ *   - settingsJson (permissions.deny) — ONLY at hook-hard (advisory → doc stanza only).
+ *   - gitignore lines — at ANY hook level (hook-soft / hook-hard).
+ *   - settingsHook — at hook-soft OR hook-hard, wired via ensureHook into the
+ *     committed .claude/settings.json (gated on binarySupportsVerb so a stale CLI
+ *     degrades gracefully; respects opts.wireHooks for --no-hook). The
+ *     init-covered recheck-main-before-deploy-lane hook is intentionally NOT wired
+ *     (init's gate-push already covers it).
+ */
+function materializePractices(top, slug, selections, catalog, opts = {}) {
+    if (selections.length === 0)
+        return [];
+    const wireHooks = opts.wireHooks !== false;
+    const levelById = new Map(selections.map((s) => [s.id, s.level]));
+    // Resolve to (practice, level) in CATALOG order; silently drop unknown ids.
+    const resolved = catalog.practices
+        .filter((p) => levelById.has(p.id))
+        .map((p) => ({ practice: p, level: levelById.get(p.id) }));
+    if (resolved.length === 0)
+        return [];
+    // 1. .convene/best-practices.md (the full managed doc).
+    writeIfChanged(node_path_1.default.join(top, '.convene', 'best-practices.md'), buildPracticesDoc(slug, resolved));
+    // 2. ref region in CLAUDE.md + AGENTS.md (insert/replace; preserves other content).
+    for (const [fname, refBody] of [
+        ['CLAUDE.md', CLAUDE_REF_BODY],
+        ['AGENTS.md', AGENTS_REF_BODY],
+    ]) {
+        const file = node_path_1.default.join(top, fname);
+        const old = node_fs_1.default.existsSync(file) ? node_fs_1.default.readFileSync(file, 'utf8') : '';
+        writeIfChanged(file, upsertRefRegion(old, refBody));
+    }
+    // 3. `doc` artifacts — write-if-absent (never clobber a hand-enriched doc).
+    for (const { practice } of resolved) {
+        for (const a of practice.artifacts) {
+            if (a.kind !== 'doc')
+                continue;
+            const file = node_path_1.default.join(top, a.path);
+            if (node_fs_1.default.existsSync(file))
+                continue;
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+            node_fs_1.default.writeFileSync(file, a.body);
+        }
+    }
+    // 4. settingsJson (permissions.deny) — ENFORCE only at hook-hard. Deep-merge into
+    //    the committed .claude/settings.json: UNION permissions.deny, preserve all else.
+    //    (advisory adoption writes only the CLAUDE.md stanza — no settings change.)
+    const denyArts = [];
+    for (const { practice, level } of resolved) {
+        if (level !== 'hook-hard')
+            continue;
+        for (const a of practice.artifacts) {
+            if (a.kind === 'settingsJson')
+                denyArts.push(a);
+        }
+    }
+    if (denyArts.length) {
+        const file = (0, hook_1.projectSettingsPath)(top);
+        const settings = (0, hook_1.parseSettings)((0, hook_1.readSettingsRaw)(file));
+        if (settings !== null) {
+            // unparseable → don't clobber
+            let merged = settings;
+            for (const a of denyArts)
+                merged = mergeSettingsJson(merged, a);
+            writeIfChanged(file, (0, hook_1.serializeSettings)(merged));
+        }
+    }
+    // 5. gitignore lines — at ANY hook level. Append idempotently under a managed marker.
+    const ignoreLines = [];
+    for (const { practice, level } of resolved) {
+        if (!isHookLevel(level))
+            continue;
+        for (const a of practice.artifacts) {
+            if (a.kind === 'gitignore')
+                ignoreLines.push(...a.lines);
+        }
+    }
+    if (ignoreLines.length) {
+        const file = node_path_1.default.join(top, '.gitignore');
+        const old = node_fs_1.default.existsSync(file) ? node_fs_1.default.readFileSync(file, 'utf8') : '';
+        writeIfChanged(file, ensureGitignoreLines(old, ignoreLines));
+    }
+    // 6. settingsHook — wire at hook-soft / hook-hard into the committed project
+    //    settings, via ensureHook (idempotent + merge-safe). Skip when init isn't
+    //    installing project settings (--no-hook), skip init-covered hooks, and gate
+    //    each on binarySupportsVerb so a stale CLI degrades gracefully (matches
+    //    registerCoordinationHooks). The materialized hooks are fail-open (the
+    //    practice-guard command is fail-open-loud).
+    if (wireHooks) {
+        const settingsPath = (0, hook_1.projectSettingsPath)(top);
+        for (const { practice, level } of resolved) {
+            if (!isHookLevel(level))
+                continue;
+            if (HOOK_COVERED_BY_INIT.has(practice.id))
+                continue;
+            for (const a of practice.artifacts) {
+                if (a.kind !== 'settingsHook')
+                    continue;
+                const verb = a.verb ?? 'practice-guard';
+                if (!(0, hook_1.binarySupportsVerb)(verb))
+                    continue;
+                (0, hook_1.ensureHook)(a.event, a.command, a.matcher, settingsPath);
+            }
+        }
+    }
+    // 7. manifest entries, in CATALOG order.
+    return resolved.map(({ practice, level }) => ({
+        id: practice.id,
+        version: practice.version,
+        level,
+        hash: regionHash(renderPracticeSection(practice, level)),
+    }));
+}
+/**
+ * The off-board reverse of materializePractices: strip the ref region from CLAUDE.md
+ * and AGENTS.md (deleting a file that becomes empty, mirroring init's stripMarker
+ * delete), and return the repo-relative paths touched (for reporting). Does NOT
+ * delete .convene/best-practices.md or .convene/practices/ — those live under
+ * .convene, which `convene off-board` already removes wholesale.
+ */
+function dematerializePractices(top) {
+    const touched = [];
+    for (const fname of ['CLAUDE.md', 'AGENTS.md']) {
+        const file = node_path_1.default.join(top, fname);
+        if (!node_fs_1.default.existsSync(file))
+            continue;
+        const old = node_fs_1.default.readFileSync(file, 'utf8');
+        const { content, removed } = removeRefRegion(old);
+        if (!removed)
+            continue;
+        if (content.length === 0)
+            node_fs_1.default.rmSync(file, { force: true });
+        else if (content !== old)
+            node_fs_1.default.writeFileSync(file, content);
+        touched.push(fname);
+    }
+    return touched;
+}