convene-cli 1.2.0 → 1.4.0

package/dist/catalog/prompt.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickPracticesInteractively = pickPracticesInteractively;
+/**
+ * Interactive best-practices picker for `convene init` / `convene setup`.
+ *
+ * STRICTLY interactive: the caller MUST gate on `process.stdin.isTTY &&
+ * process.stdout.isTTY && !opts.yes` before invoking this — it is never reached in
+ * tests (which run non-TTY) or under `--yes` (agents/CI). The whole flow is wrapped
+ * so any error / EOF / Ctrl-D falls back to `[]` (adopt nothing) — a picker hiccup
+ * must NEVER crash onboarding. The readline interface is always closed in a finally.
+ */
+const promises_1 = __importDefault(require("node:readline/promises"));
+const select_1 = require("./select");
+const out = (m) => process.stdout.write(m + '\n');
+/** Count of opt-in (default-ON) practices in the named tiers — for the menu labels. */
+function presetCount(catalog, preset) {
+    return (0, select_1.presetSelections)(catalog, preset).length;
+}
+/**
+ * Run the onboarding picker and resolve a Selection[]. Returns [] on EOF / any
+ * error / explicit "None". Never throws.
+ */
+async function pickPracticesInteractively(catalog) {
+    const rl = promises_1.default.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        out('');
+        out('Adopt Convene best practices for this repo? (lean CLAUDE.md guidance now; enforcement hooks later)');
+        out(`  [1] Essentials (${presetCount(catalog, 'essentials')})`);
+        out(`  [2] Essentials + Recommended (${presetCount(catalog, 'recommended')})  [default]`);
+        out(`  [3] Everything (${presetCount(catalog, 'all')})`);
+        out('  [4] Customize');
+        out('  [n] None');
+        const choice = (await rl.question('Choose [2]: ')).trim().toLowerCase();
+        if (choice === 'n' || choice === 'none')
+            return [];
+        if (choice === '1')
+            return (0, select_1.presetSelections)(catalog, 'essentials');
+        if (choice === '3')
+            return (0, select_1.presetSelections)(catalog, 'all');
+        if (choice === '4')
+            return await customize(catalog, rl);
+        // Empty input or "2" → the recommended default.
+        return (0, select_1.presetSelections)(catalog, 'recommended');
+    }
+    catch {
+        // EOF (Ctrl-D), a closed pipe, anything — never crash onboarding.
+        return [];
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Customize from the recommended preset: for each chosen practice show
+ * `title [defaultLevel]` and accept enter=keep, 's'=skip, or a level name from
+ * availableLevels. Skimmable; unknown levels re-prompt-free (keep at default).
+ */
+async function customize(catalog, rl) {
+    const base = (0, select_1.presetSelections)(catalog, 'recommended');
+    const byId = new Map(catalog.practices.map((p) => [p.id, p]));
+    const result = [];
+    out('');
+    out('Customize — for each: [enter] keep · [s] skip · or type a level name.');
+    for (const sel of base) {
+        const p = byId.get(sel.id);
+        if (!p)
+            continue;
+        const levels = p.availableLevels.join('/');
+        const ans = (await rl.question(`  ${p.title} [${sel.level}] (${levels}): `)).trim().toLowerCase();
+        if (ans === 's' || ans === 'skip')
+            continue;
+        if (ans === '') {
+            result.push(sel);
+            continue;
+        }
+        if (p.availableLevels.includes(ans)) {
+            result.push({ id: sel.id, level: ans });
+        }
+        else {
+            out(`    (unrecognized level "${ans}" — keeping ${sel.level})`);
+            result.push(sel);
+        }
+    }
+    return result;
+}

package/dist/catalog/report.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportManifest = reportManifest;
+/**
+ * Phase 5 — report the adopted best-practices manifest to the server so the
+ * dashboard can show per-project adoption.
+ *
+ * This is PURELY observability and is ALWAYS best-effort / fail-OPEN: it must
+ * never fail or slow down `convene init` (onboarding) or `convene update --apply`
+ * because the report failed, was offline, or the server is down. The whole thing
+ * is fire-and-forget — every failure path returns `{ ok: false }` and is swallowed
+ * by the caller.
+ */
+const api_1 = require("../api");
+const config_1 = require("../config");
+const git_1 = require("../git");
+/** A short, fixed budget — the report is non-blocking, so never the 10s default. */
+const REPORT_TIMEOUT_MS = 5_000;
+/**
+ * Fire-and-forget the manifest report. Resolves to `{ ok }`, NEVER throws and
+ * NEVER prints. Skips silently (ok:false) when offline or with no API key — the
+ * report is optional and onboarding/update proceed regardless.
+ *
+ *   - `offline` — caller ran with --offline; skip the network entirely.
+ *   - no api key / no member — not logged in; nothing to authenticate the POST.
+ */
+async function reportManifest(top, slug, manifest, opts = {}) {
+    try {
+        if (opts.offline)
+            return { ok: false };
+        const cfg = (0, config_1.resolveConfig)();
+        if (!cfg.apiKey)
+            return { ok: false };
+        const session = cfg.member ? (0, git_1.sessionId)(cfg.member, top) : null;
+        const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool);
+        const res = await api.reportBestPractices(slug, manifest, REPORT_TIMEOUT_MS);
+        return { ok: res.ok };
+    }
+    catch {
+        // Belt-and-suspenders: ConveneApi.request is already fail-soft, but the
+        // report is observability-only — any unexpected throw is swallowed so a call
+        // site can fire-and-forget without a try/catch of its own.
+        return { ok: false };
+    }
+}

package/dist/catalog/select.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectionsForTiers = selectionsForTiers;
+exports.parseSelectionFlags = parseSelectionFlags;
+exports.presetSelections = presetSelections;
+/** All `optInDefault:'on'` practices in the given tiers, at each one's defaultLevel. */
+function selectionsForTiers(catalog, tiers) {
+    const want = new Set(tiers);
+    return catalog.practices
+        .filter((p) => want.has(p.tier) && p.optInDefault === 'on')
+        .map((p) => ({ id: p.id, level: p.defaultLevel }));
+}
+/**
+ * Resolve CLI selection flags into a Selection[] — or `null` when NO selection
+ * flag was passed (the caller then decides: prompt interactively, or skip the
+ * catalog entirely). Precedence, applied in CATALOG order at the end so the
+ * result is deterministic regardless of flag order:
+ *   --no-practices      → [] (explicitly adopt nothing)
+ *   --all-practices     → every practice at its defaultLevel
+ *   --tier a,b          → selectionsForTiers
+ *   --practice id|id=lvl → add/override that id at the level (validated)
+ * `--practice` always wins over a tier pick for the same id.
+ */
+function parseSelectionFlags(opts, catalog) {
+    const hasTier = typeof opts.tier === 'string' && opts.tier.length > 0;
+    const hasPractice = Array.isArray(opts.practice) && opts.practice.length > 0;
+    if (!opts.noPractices && !opts.allPractices && !hasTier && !hasPractice)
+        return null;
+    // --no-practices is the explicit "adopt nothing" — it short-circuits everything.
+    if (opts.noPractices)
+        return [];
+    const byId = new Map(catalog.practices.map((p) => [p.id, p]));
+    // Keep levels in a map keyed by id; emit in CATALOG order at the end.
+    const chosen = new Map();
+    if (opts.allPractices) {
+        for (const p of catalog.practices)
+            chosen.set(p.id, p.defaultLevel);
+    }
+    else if (hasTier) {
+        const tiers = opts.tier.split(',').map((t) => t.trim()).filter(Boolean);
+        for (const s of selectionsForTiers(catalog, tiers))
+            chosen.set(s.id, s.level);
+    }
+    // --practice add/override (after tier so it wins): "id" → defaultLevel, "id=level" → that level.
+    if (hasPractice) {
+        for (const raw of opts.practice) {
+            const eq = raw.indexOf('=');
+            const id = (eq >= 0 ? raw.slice(0, eq) : raw).trim();
+            const lvl = eq >= 0 ? raw.slice(eq + 1).trim() : null;
+            const p = byId.get(id);
+            if (!p)
+                throw new Error(`unknown practice "${id}" — not in the catalog (run \`convene doctor\` to see ids)`);
+            let level;
+            if (lvl === null) {
+                level = p.defaultLevel;
+            }
+            else {
+                if (!p.availableLevels.includes(lvl)) {
+                    throw new Error(`invalid level "${lvl}" for practice "${id}" — choose one of: ${p.availableLevels.join(', ')}`);
+                }
+                level = lvl;
+            }
+            chosen.set(id, level);
+        }
+    }
+    return catalog.practices.filter((p) => chosen.has(p.id)).map((p) => ({ id: p.id, level: chosen.get(p.id) }));
+}
+/**
+ * Named onboarding presets:
+ *   essentials  — essentials-tier opt-ins
+ *   recommended — essentials + recommended opt-ins
+ *   all         — every practice at its defaultLevel
+ *   none        — []
+ */
+function presetSelections(catalog, preset) {
+    switch (preset) {
+        case 'none':
+            return [];
+        case 'essentials':
+            return selectionsForTiers(catalog, ['essentials']);
+        case 'recommended':
+            return selectionsForTiers(catalog, ['essentials', 'recommended']);
+        case 'all':
+            return catalog.practices.map((p) => ({ id: p.id, level: p.defaultLevel }));
+    }
+}

package/dist/catalog/types.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Canonical type contract for the Convene best-practices catalog — the data model
+ * shared by the server (source of truth, seeds the DB + serves GET /api/v1/catalog)
+ * and the CLI (a generated mirror it materializes into repos). Kept deliberately
+ * small and stable; the CLI carries a byte-mirror of this file (see brand.ts for the
+ * same dual-copy convention) so the two packages never import across the workspace.
+ *
+ * Versioning: every Practice carries its own SemVer (so a single practice can be
+ * tightened without rev'ing the whole catalog), and the Catalog itself carries a
+ * release SemVer. A repo's manifest pins the (practice, version, level) triple it
+ * adopted — see PracticeManifestEntry — so updates are diffable and never silent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/commands/auth.js

@@ -13,6 +13,8 @@ const node_child_process_1 = require("node:child_process");
 const brand_1 = require("../brand");
 const api_1 = require("../api");
 const config_1 = require("../config");
+const catalog_1 = require("../catalog");
+const manifest_1 = require("../catalog/manifest");
 const git_1 = require("../git");
 const hook_1 = require("../hook");
 const cache_1 = require("../cache");
@@ -310,6 +312,48 @@ async function doctor(opts) {
     for (const c of checks) {
         process.stdout.write(`${c.ok ? '✓' : '✗'} ${c.name.padEnd(8)} ${c.detail}\n`);
     }
+    // Best practices (local-only, advisory): adopted-practice inventory + whether
+    // the repo trails the catalog. Fail-soft — never throws and never alters the
+    // doctor exit code.
+    reportBestPractices(top, proj?.slug ?? null);
     if (!checks.every((c) => c.ok))
         process.exitCode = 1;
 }
+/**
+ * Print doctor's "Best practices" section. Local-only this phase: reads the repo
+ * manifest and diffs it against the bundled catalog. Purely informational — it
+ * never throws (a malformed manifest is swallowed) and never sets the exit code.
+ *   - manifest present → catalog freshness line + each adopted practice + unknowns.
+ *   - on the bus but no manifest → a single nudge to adopt some.
+ *   - not on the bus → nothing.
+ */
+function reportBestPractices(top, slug) {
+    try {
+        const manifest = (0, config_1.loadManifest)(top);
+        if (!manifest) {
+            if (slug) {
+                process.stdout.write('· no best practices adopted — run `convene init` to choose some\n');
+            }
+            return;
+        }
+        const cmp = (0, manifest_1.compareToCatalog)(manifest, catalog_1.CATALOG);
+        process.stdout.write(cmp.behind
+            ? `· catalog v${cmp.catalogVersion} available (repo on v${cmp.repoVersion}) — run \`convene update\`\n`
+            : `· best practices up to date at v${cmp.repoVersion}\n`);
+        for (const p of cmp.adopted) {
+            const flag = p.outdated ? ` (outdated → v${p.catalogVersion})` : '';
+            process.stdout.write(`    ${p.id} @ ${p.manifestVersion} [${p.level}]${flag}\n`);
+        }
+        if (cmp.unknownIds.length) {
+            process.stdout.write(`    unknown (not in catalog): ${cmp.unknownIds.join(', ')}\n`);
+        }
+        // Adoption is reported to the server on init/update — point the human at the
+        // dashboard view. Local-only hint; no network call (slug present ⇒ on the bus).
+        if (slug) {
+            process.stdout.write(`    adoption is visible on the dashboard: ${(0, config_1.resolveConfig)().baseUrl}/p/${slug}\n`);
+        }
+    }
+    catch {
+        /* fail-soft: best-practices reporting must never break doctor */
+    }
+}

package/dist/commands/fetch.js

@@ -21,6 +21,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const git_1 = require("../git");
 const config_1 = require("../config");
 const cache_1 = require("../cache");
+const manifest_1 = require("../catalog/manifest");
 const api_1 = require("../api");
 const render_1 = require("../render");
 const catchup_1 = require("./catchup");
@@ -28,6 +29,30 @@ const exit_1 = require("../exit");
 const CACHE_TTL_SEC = 3;
 const FETCH_TIMEOUT_MS = 4000;
 const WATCHDOG_MS = 6000;
+/** Catalog-version cache TTL for the behind-nudge — long enough to stay off the hot path. */
+const CATALOG_VERSION_TTL_SEC = 3600;
+/**
+ * A single fail-soft nudge line iff the repo's adopted-practices manifest trails a
+ * CACHED live catalog version. Reads only local state (the manifest + the catalog-
+ * version cache) — NEVER hits the network, so it can't slow the hot path. On a cache
+ * miss, no manifest, or any error → null (no line; never spam when up to date).
+ */
+function catalogBehindNudge(top) {
+    try {
+        const manifest = (0, config_1.loadManifest)(top);
+        if (!manifest)
+            return null;
+        const live = (0, cache_1.readCatalogVersion)(CATALOG_VERSION_TTL_SEC);
+        if (!live)
+            return null;
+        if (!(0, manifest_1.semverLt)(manifest.catalogVersion, live))
+            return null;
+        return `convene: best-practices catalog v${live} available (repo on v${manifest.catalogVersion}) — run \`convene update\``;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Write a rendered block. In `codexHook` mode, wrap it in Codex's UserPromptSubmit
  * hook envelope so its `additionalContext` lands in the model's per-turn context;
@@ -128,10 +153,21 @@ async function runFetch(opts = {}) {
             // DEGRADED/failure under --since-last emits nothing (structural suppression).
             return done(0);
         }
+        // A fail-soft, network-free nudge line emitted alongside a healthy block when
+        // the repo trails the CACHED live catalog version (suppressed under --json /
+        // codex-hook to keep those envelopes clean).
+        const emitNudge = () => {
+            if (opts.json || opts.codexHook)
+                return;
+            const nudge = catalogBehindNudge(top);
+            if (nudge)
+                process.stdout.write(nudge + '\n');
+        };
         // Cache short-circuit for rapid successive prompts.
         const cache = (0, cache_1.readCache)(slug);
         if (cache && (0, cache_1.ageSeconds)(cache) < CACHE_TTL_SEC) {
             renderData(cache.data, { slug, member, session, lookback, syncedAgoSec: (0, cache_1.ageSeconds)(cache), json: opts.json });
+            emitNudge();
             return done(0);
         }
         // Slow path: bounded network fetch.
@@ -140,6 +176,20 @@ async function runFetch(opts = {}) {
         if (res.ok && res.json) {
             (0, cache_1.writeCache)(slug, res.json);
             renderData(res.json, { slug, member, session, lookback, syncedAgoSec: 0, json: opts.json });
+            // Opportunistically refresh the catalog-version cache off the slow path (never
+            // its own round-trip on the hot path): only when the cached version is stale,
+            // and only if a manifest exists (a non-best-practices repo never needs it).
+            if ((0, config_1.loadManifest)(top) && !(0, cache_1.readCatalogVersion)(CATALOG_VERSION_TTL_SEC)) {
+                try {
+                    const cat = await api.getCatalog(FETCH_TIMEOUT_MS);
+                    if (cat.ok && cat.json?.version)
+                        (0, cache_1.writeCatalogVersion)(cat.json.version);
+                }
+                catch {
+                    /* fail-soft: the nudge just stays suppressed until next refresh */
+                }
+            }
+            emitNudge();
             return done(0);
         }
         // Fetch failed/timed out → DEGRADED from stale cache (or absent).

package/dist/commands/init.js

@@ -24,6 +24,11 @@ const api_1 = require("../api");
 const protocol_1 = require("../protocol");
 const hook_1 = require("../hook");
 const githook_1 = require("../githook");
+const catalog_1 = require("../catalog");
+const materialize_1 = require("../catalog/materialize");
+const select_1 = require("../catalog/select");
+const prompt_1 = require("../catalog/prompt");
+const report_1 = require("../catalog/report");
 const ctx_1 = require("../ctx");
 /**
  * The repo-relative paths convene init writes (the onboarding footprint). Shared by
@@ -477,6 +482,44 @@ function writeMcpConfigs(top, baseUrl) {
     writeCodexConfig(top, baseUrl);
     log('· Cline & Windsurf register MCP only in a user-global file — add `convene` (`npx -y convene-mcp`) there manually; see CONVENE_PROTOCOL.md.');
 }
+/**
+ * Resolve + materialize the adopted best practices for this repo (Phase 2). Flags
+ * win when present; otherwise a real interactive TTY (and NOT --yes) gets the
+ * picker; otherwise we skip silently. An EMPTY selection writes NOTHING (no
+ * manifest, no doc, no ref region) — that invariant keeps a plain init byte-identical.
+ */
+async function adoptBestPractices(top, slug, opts) {
+    let selections;
+    const flags = (0, select_1.parseSelectionFlags)(opts, catalog_1.CATALOG);
+    if (flags !== null) {
+        selections = flags;
+    }
+    else if (process.stdin.isTTY && process.stdout.isTTY && !opts.yes) {
+        selections = await (0, prompt_1.pickPracticesInteractively)(catalog_1.CATALOG);
+    }
+    else {
+        // Non-interactive with no --tier/--practice flags: adopt nothing, silently — a plain
+        // headless onboarding stays byte-identical. `convene doctor` is where a human is
+        // nudged that best practices are available to adopt.
+        return;
+    }
+    // Respect --no-hook: when init declines to write the committed project settings,
+    // the materialized settingsHook guards are skipped too (settingsJson/gitignore
+    // still apply — they are not Claude-Code hooks).
+    const wireHooks = !(opts.noHook === true || opts.hook === false);
+    const entries = (0, materialize_1.materializePractices)(top, slug, selections, catalog_1.CATALOG, { wireHooks });
+    if (entries.length) {
+        const manifest = { catalogVersion: catalog_1.CATALOG.version, channel: 'minor', practices: entries };
+        (0, config_1.writeManifest)(top, manifest);
+        log(`✓ adopted ${entries.length} best practices (.convene/best-practices.md) — see them with \`convene doctor\``);
+        // Phase 5: report adoption to the server so the dashboard can show it.
+        // Best-effort, fail-OPEN, fire-and-forget — onboarding NEVER fails/slows
+        // because the report failed; skipped silently when --offline or no api key.
+        const { ok } = await (0, report_1.reportManifest)(top, slug, manifest, { offline: opts.offline });
+        if (ok)
+            log('· reported adoption to the dashboard');
+    }
+}
 async function init(opts) {
     const top = (0, git_1.gitToplevel)();
     if (!top)
@@ -698,6 +741,12 @@ async function init(opts) {
     }
     // 8. memory seed (best-effort, outside the repo)
     seedMemory(top, slug, baseUrl);
+    // 8-bis. best-practices (Phase 2). Resolve selections from flags; else prompt
+    //   interactively at a real TTY; else (non-TTY / no flags) skip. CRITICAL
+    //   INVARIANT: when `selections` is empty NOTHING is written — no manifest, no
+    //   .convene/best-practices.md, no ref region — so a plain non-interactive init
+    //   stays byte-identical to its pre-catalog output (init.test.ts passes unchanged).
+    await adoptBestPractices(top, slug, opts);
     // 8a. optional isolated commit — stage ONLY the convene files (never `git add -A`),
     //     so onboarding can never be bundled into unrelated work (the VAcontractorCo
     //     entangled-commit failure). Off by default; `--commit` opts in.

package/dist/commands/offboard.js

@@ -27,8 +27,65 @@ const api_1 = require("../api");
 const hook_1 = require("../hook");
 const githook_1 = require("../githook");
 const init_1 = require("./init");
+const materialize_1 = require("../catalog/materialize");
+const catalog_1 = require("../catalog");
 const protocol_1 = require("../protocol");
 const ctx_1 = require("../ctx");
+/**
+ * The permissions.deny entries to subtract on off-board. materialize.ts writes a
+ * practice's settingsJson(permissions.deny) artifact ONLY at hook-hard, so the exact
+ * set this repo could have materialized is the deny artifacts of the practices its
+ * MANIFEST records at hook-hard — not every practice in the live catalog. Filtering by
+ * the manifest (what was actually adopted) stops off-board from removing a teammate's
+ * own deny rule that happens to match an UNADOPTED catalog practice's entry, and keeps
+ * reversal correct as the catalog grows/shrinks after onboarding.
+ *
+ * Fallback: a repo with no readable manifest (pre-schema-2, or unreadable) → the full
+ * catalog managed set (the prior behavior), so older repos still get cleaned.
+ *
+ * KNOWN RESIDUAL: artifacts are read from the CURRENT catalog by practice id, so if an
+ * adopted practice's deny STRING itself changed between the version materialized and the
+ * current catalog, the old string can still be orphaned. Fully closing that needs the
+ * manifest to record the materialized contributions (a manifest-schema change, deferred).
+ */
+function catalogManagedDenyEntries(manifest) {
+    const out = new Set();
+    const adopted = manifest ? new Map(manifest.practices.map((e) => [e.id, e.level])) : null;
+    for (const p of catalog_1.CATALOG.practices) {
+        if (adopted && adopted.get(p.id) !== 'hook-hard')
+            continue; // deny materializes only at hook-hard
+        for (const a of p.artifacts) {
+            if (a.kind === 'settingsJson') {
+                for (const d of (0, materialize_1.denyEntriesOf)(a))
+                    out.add(d);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The .gitignore lines to subtract on off-board. materialize.ts appends a practice's
+ * gitignore artifact at ANY hook level (hook-soft / hook-hard), so the set is the
+ * gitignore artifacts of the practices the MANIFEST records at a hook level. Same
+ * manifest-filtering rationale (and the same fallback + known residual) as
+ * catalogManagedDenyEntries.
+ */
+function catalogManagedGitignoreLines(manifest) {
+    const out = [];
+    const adopted = manifest ? new Map(manifest.practices.map((e) => [e.id, e.level])) : null;
+    for (const p of catalog_1.CATALOG.practices) {
+        if (adopted) {
+            const lvl = adopted.get(p.id);
+            if (!lvl || !(0, materialize_1.isHookLevel)(lvl))
+                continue; // gitignore materializes only at hook levels
+        }
+        for (const a of p.artifacts) {
+            if (a.kind === 'gitignore')
+                out.push(...a.lines);
+        }
+    }
+    return out;
+}
 const log = (m) => process.stdout.write(m + '\n');
 const abs = (top, rel) => node_path_1.default.join(top, rel);
 const jsonOut = (obj) => JSON.stringify(obj, null, 2) + '\n';
@@ -84,15 +141,23 @@ function delIfOurs(top, rel, expected, touched, dryRun) {
     if (!dryRun)
         node_fs_1.default.rmSync(p, { force: true });
 }
-/** Strip the convene managed block from a Markdown doc; delete the file if nothing else remains. */
+/**
+ * Strip BOTH convene-managed regions from a Markdown doc — the main coordination
+ * block AND the Phase-2 best-practices ref region (`<!-- convene:practices:begin -->`
+ * …) — in ONE read/write so the file is reported (and staged) at most once. Deletes
+ * the file if nothing else remains. The dedicated `.convene/best-practices.md` +
+ * `.convene/practices/` docs are removed wholesale by `delPath('.convene')`.
+ */
 function stripMarker(top, rel, touched, dryRun) {
     const p = abs(top, rel);
     if (!node_fs_1.default.existsSync(p))
         return;
-    const { content, removed } = (0, init_1.removeMarkerBlock)(node_fs_1.default.readFileSync(p, 'utf8'));
-    if (!removed)
+    const orig = node_fs_1.default.readFileSync(p, 'utf8');
+    const block = (0, init_1.removeMarkerBlock)(orig);
+    const ref = (0, materialize_1.removeRefRegion)(block.content);
+    if (!block.removed && !ref.removed)
         return;
-    applyStripOrDelete(top, rel, content, touched, dryRun);
+    applyStripOrDelete(top, rel, ref.content, touched, dryRun);
 }
 /** Strip the convene block from a Codex config.toml; delete if nothing else remains. */
 function stripToml(top, rel, touched, dryRun) {
@@ -189,8 +254,15 @@ function finalizeJson(top, rel, obj, touched, dryRun) {
             node_fs_1.default.writeFileSync(p, jsonOut(obj));
     }
 }
-/** Strip convene hooks from the committed .claude/settings.json; delete if nothing else remains. */
-function stripClaudeSettings(top, rel, touched, dryRun) {
+/**
+ * Strip convene-managed content from the committed .claude/settings.json — both the
+ * convene-authored hooks (withoutConveneHooks, which also matches the materialized
+ * `convene practice-guard …` PreToolUse/Stop hooks) AND the Phase-3 permissions.deny
+ * entries materialize.ts merged in (subtract EXACTLY the catalog's managed set;
+ * drop permissions.deny if it empties, then permissions if it empties). A teammate's
+ * own hooks / deny rules / settings are preserved. Delete the file if nothing remains.
+ */
+function stripClaudeSettings(top, rel, touched, dryRun, manifest) {
     const p = abs(top, rel);
     if (!node_fs_1.default.existsSync(p))
         return;
@@ -202,7 +274,27 @@ function stripClaudeSettings(top, rel, touched, dryRun) {
         log(`· ${rel} (left as-is — unparseable JSON)`);
         return;
     }
-    const { settings, removed } = (0, hook_1.withoutConveneHooks)(obj);
+    const stripped = (0, hook_1.withoutConveneHooks)(obj);
+    let removed = stripped.removed;
+    const settings = stripped.settings;
+    // Subtract the convene-managed permissions.deny entries (only ours — those this repo
+    // actually adopted at hook-hard, per the manifest).
+    const managedDeny = catalogManagedDenyEntries(manifest);
+    const deny = settings?.permissions?.deny;
+    if (Array.isArray(deny) && managedDeny.size) {
+        const kept = deny.filter((d) => !(typeof d === 'string' && managedDeny.has(d)));
+        if (kept.length !== deny.length) {
+            removed = true;
+            if (kept.length > 0) {
+                settings.permissions.deny = kept;
+            }
+            else {
+                delete settings.permissions.deny;
+                if (settings.permissions && Object.keys(settings.permissions).length === 0)
+                    delete settings.permissions;
+            }
+        }
+    }
     if (!removed)
         return;
     if ((0, hook_1.settingsIsEmpty)(settings)) {
@@ -236,24 +328,41 @@ function handleGitHook(top, touched, dryRun) {
     else if (r.status === 'skipped-foreign')
         log('· .githooks/pre-push (left as-is — foreign hook)');
 }
-/** Reverse the .gitignore guard (and re-enable any blanket rule init disabled). */
-function handleGitignore(top, touched, dryRun) {
+/**
+ * Reverse BOTH .gitignore footprints: init's cache guard (removeGitignoreGuard, which
+ * also re-enables any blanket rule init disabled) AND the Phase-3 practices lines +
+ * managed marker materialize.ts appended (removeGitignoreLines). Done in one
+ * read/write so the file is reported/staged at most once; deletes the file if empty.
+ */
+function handleGitignore(top, touched, dryRun, manifest) {
     const rel = '.gitignore';
     const p = abs(top, rel);
     if (!node_fs_1.default.existsSync(p))
         return;
     const old = node_fs_1.default.readFileSync(p, 'utf8');
-    const willChange = old.includes('.convene/cache/') ||
+    const practiceLines = catalogManagedGitignoreLines(manifest);
+    const practicesProbe = (0, materialize_1.removeGitignoreLines)(old, practiceLines);
+    const willChangeGuard = old.includes('.convene/cache/') ||
         old.includes('.convene/*.local.json') ||
         old.includes('# convene (keep local cache') ||
         /\(disabled by convene init/.test(old);
-    if (!willChange)
+    if (!willChangeGuard && !practicesProbe.removed)
         return;
     if (dryRun) {
         touched.push({ rel, action: 'strip' });
         return;
     }
-    if ((0, init_1.removeGitignoreGuard)(top)) {
+    // 1. Strip the Phase-3 practices lines first (write-back so removeGitignoreGuard
+    //    operates on the practices-free body).
+    if (practicesProbe.removed) {
+        if (practicesProbe.content.trim().length === 0)
+            node_fs_1.default.rmSync(p, { force: true });
+        else
+            node_fs_1.default.writeFileSync(p, practicesProbe.content);
+    }
+    // 2. Then reverse init's cache guard (no-op if the file was already deleted).
+    const guardChanged = node_fs_1.default.existsSync(p) ? (0, init_1.removeGitignoreGuard)(top) : false;
+    if (practicesProbe.removed || guardChanged) {
         touched.push({ rel, action: node_fs_1.default.existsSync(p) ? 'strip' : 'delete' });
     }
 }
@@ -374,6 +483,11 @@ async function offboard(opts) {
     }
     // 2. Local footprint removal.
     const touched = [];
+    // Read the adopted-practices manifest BEFORE any deletion — delPath('.convene')
+    // removes .convene/project.json, the manifest's home. It tells off-board which
+    // practices (and at what level) this repo actually materialized, so reversal
+    // subtracts exactly those deny/gitignore entries (never a teammate's own rule).
+    const manifest = (0, config_1.loadManifest)(top);
     stripMarker(top, 'CLAUDE.md', touched, dryRun);
     stripMarker(top, 'AGENTS.md', touched, dryRun);
     handleProtocolDoc(top, touched, dryRun);
@@ -381,13 +495,13 @@ async function offboard(opts) {
     delPath(top, '.convene', touched, dryRun);
     delPath(top, '.cursor/rules/convene.mdc', touched, dryRun);
     delPath(top, '.clinerules/convene.md', touched, dryRun);
-    stripClaudeSettings(top, '.claude/settings.json', touched, dryRun);
+    stripClaudeSettings(top, '.claude/settings.json', touched, dryRun, manifest);
     stripToml(top, '.codex/config.toml', touched, dryRun);
     stripJsonServer(top, '.cursor/mcp.json', 'mcpServers', touched, dryRun);
     stripJsonServer(top, '.vscode/mcp.json', 'servers', touched, dryRun);
     stripGemini(top, '.gemini/settings.json', touched, dryRun);
     handleGitHook(top, touched, dryRun);
-    handleGitignore(top, touched, dryRun);
+    handleGitignore(top, touched, dryRun, manifest);
     if (!dryRun)
         cleanupEmptyDirs(top);
     // 3. Repo-specific seeded memory is always cleaned (it's keyed to THIS repo's path).