convene-cli 1.3.0 → 1.4.1

package/dist/commands/offboard.js

@@ -32,14 +32,28 @@ const catalog_1 = require("../catalog");
 const protocol_1 = require("../protocol");
 const ctx_1 = require("../ctx");
 /**
- * Every permissions.deny entry the catalog's settingsJson artifacts contribute —
- * the EXACT set materialize.ts can write into .claude/settings.json at hook-hard.
- * Off-board subtracts exactly these (and only these), so a teammate's own deny rule
- * is never removed. Computed from CATALOG so it tracks the catalog automatically.
+ * 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() {
+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))
@@ -50,12 +64,21 @@ function catalogManagedDenyEntries() {
     return out;
 }
 /**
- * Every .gitignore line the catalog's gitignore artifacts contribute — the set
- * materialize.ts appends at any hook level. Off-board removes exactly these.
+ * 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() {
+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);
@@ -239,7 +262,7 @@ function finalizeJson(top, rel, obj, touched, dryRun) {
  * 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) {
+function stripClaudeSettings(top, rel, touched, dryRun, manifest) {
     const p = abs(top, rel);
     if (!node_fs_1.default.existsSync(p))
         return;
@@ -254,8 +277,9 @@ function stripClaudeSettings(top, rel, touched, dryRun) {
     const stripped = (0, hook_1.withoutConveneHooks)(obj);
     let removed = stripped.removed;
     const settings = stripped.settings;
-    // Subtract the convene-managed permissions.deny entries (only ours).
-    const managedDeny = catalogManagedDenyEntries();
+    // 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)));
@@ -310,13 +334,13 @@ function handleGitHook(top, touched, dryRun) {
  * 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) {
+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 practiceLines = catalogManagedGitignoreLines();
+    const practiceLines = catalogManagedGitignoreLines(manifest);
     const practicesProbe = (0, materialize_1.removeGitignoreLines)(old, practiceLines);
     const willChangeGuard = old.includes('.convene/cache/') ||
         old.includes('.convene/*.local.json') ||
@@ -459,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);
@@ -466,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).

package/dist/commands/practice-guard.js

@@ -89,12 +89,27 @@ function note(reason) {
 function blockReason(reason) {
     process.stderr.write(reason + '\n');
 }
-/** The one-line reminder for a practice: its catalog `title` (stable, lean). */
+/**
+ * A compact "why + source" suffix for a practice, drawn from the catalog. Hitting a
+ * gate is the highest-frequency moment an agent could LEARN the rationale, so every
+ * reminder/block cites the practice's `why` (the failure mode it prevents) and a
+ * `sourceUrls[0]` reference right there — turning enforcement into in-context
+ * teaching with zero new infra (the catalog is already loaded; no hot-path network).
+ * Empty when the practice or its `why` is unknown. Pure + local.
+ */
+function whySuffix(id) {
+    const p = catalog_1.CATALOG.practices.find((x) => x.id === id);
+    if (!p || !p.why)
+        return '';
+    const src = p.sourceUrls && p.sourceUrls.length > 0 ? `\n  source: ${p.sourceUrls[0]}` : '';
+    return `\n  why: ${p.why}${src}`;
+}
+/** The one-line reminder for a practice: its catalog `title` + why/source (lean). */
 function reminderFor(id) {
     const p = catalog_1.CATALOG.practices.find((x) => x.id === id);
     if (!p)
         return `convene: best practice ${id} applies here.`;
-    return `convene: ${p.title} — ${p.id} (level: reminder).`;
+    return `convene: ${p.title} — ${p.id}.${whySuffix(id)}`;
 }
 /**
  * DEFAULT protected paths for protect-shared-files (used when the repo has not
@@ -235,12 +250,14 @@ async function run(opts, id) {
             if (level === 'hook-hard') {
                 blockReason(`convene: BLOCKED — ${shortRel(target, top)} is a shared/global file (lockfile, migration, or root config) ` +
                     `protected by practice protect-shared-files. Editing it across sessions reliably breaks integration. ` +
-                    `If this session OWNS this change: \`convene override protect-shared-files --reason "<why>"\`, then retry.`);
+                    `If this session OWNS this change: \`convene override protect-shared-files --reason "<why>"\`, then retry.` +
+                    whySuffix(id));
                 return 2;
             }
             // hook-soft → remind, allow.
             note(`convene: ${shortRel(target, top)} is a shared/global file — protect-shared-files. ` +
-                `Only edit it if this session is the assigned owner; otherwise sequence the change.`);
+                `Only edit it if this session is the assigned owner; otherwise sequence the change.` +
+                whySuffix(id));
             return 0;
         }
         case 'worktree-per-session': {
@@ -249,7 +266,8 @@ async function run(opts, id) {
             const live = (0, cache_1.liveSessionCount)(slug, 15 * 60);
             if (live > 1) {
                 note(`convene: ${live} live sessions share this checkout — worktree-per-session. ` +
-                    `Run each concurrent agent in its own worktree (\`convene worktree <branch>\`) to avoid silent clobbering.`);
+                    `Run each concurrent agent in its own worktree (\`convene worktree <branch>\`) to avoid silent clobbering.` +
+                    whySuffix(id));
             }
             return 0;
         }
@@ -258,7 +276,8 @@ async function run(opts, id) {
             if (behindOriginMain(top)) {
                 const b = (0, git_1.currentBranch)(top) ?? 'this branch';
                 note(`convene: ${b} is behind origin/main — pull-main-before-execution. ` +
-                    `Rebase onto origin/main and re-validate the plan before editing.`);
+                    `Rebase onto origin/main and re-validate the plan before editing.` +
+                    whySuffix(id));
             }
             return 0;
         }

package/dist/commands/practices.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.practices = practices;
+/**
+ * `convene practices [id]` — the LEARN surface for the best-practices catalog.
+ *
+ * Without an id: lists every catalog practice grouped by tier, marking the ones THIS
+ * repo adopted (and at what level), so a human or agent can see what is on offer and
+ * what is active. With an id: prints that practice in depth — what it is, WHY (the
+ * failure mode it prevents), its enforcement levels, provenance, and the source URLs
+ * the practice was distilled from.
+ *
+ * The `why` and `sourceUrls` are authored on every one of the catalog's practices but
+ * were rendered nowhere — the picker shows a bare title, the materialized doc and the
+ * dashboard show the `what`/id. This command is where a repo LEARNS the rationale,
+ * before or after adopting. It deliberately lives OFF the always-loaded path (a doc
+ * imported into CLAUDE.md every turn would tax the agent — Gloaguen et al. 2026), so
+ * the heavy rationale is on-demand here, not in the hot path.
+ *
+ * Reads the bundled offline mirror (CATALOG) — network-free, instant, fail-soft. The
+ * repo manifest (loadManifest) only annotates adoption; its absence is fine (every
+ * practice then shows as available/not-adopted).
+ */
+const git_1 = require("../git");
+const config_1 = require("../config");
+const catalog_1 = require("../catalog");
+const out = (s) => process.stdout.write(s + '\n');
+/** id → adopted level, from the repo manifest. Empty (and never throws) when none. */
+function adoptedLevels() {
+    const m = new Map();
+    try {
+        const top = (0, git_1.gitToplevel)();
+        if (!top)
+            return m;
+        const manifest = (0, config_1.loadManifest)(top);
+        if (manifest)
+            for (const e of manifest.practices)
+                m.set(e.id, e.level);
+    }
+    catch {
+        /* fail-soft: no manifest annotations, list still works */
+    }
+    return m;
+}
+/** Entry point: detail view when an id is given, else the grouped list. Never throws. */
+function practices(id, _opts = {}) {
+    const adopted = adoptedLevels();
+    const wanted = (id ?? '').trim();
+    if (wanted)
+        printDetail(wanted, adopted);
+    else
+        printList(adopted);
+}
+/** The grouped list: every practice by tier, adopted ones marked with their level. */
+function printList(adopted) {
+    out(`Convene best-practices catalog v${catalog_1.CATALOG.version} — ${catalog_1.CATALOG.practices.length} practices, ` +
+        `${adopted.size} adopted in this repo.`);
+    out('Run `convene practices <id>` for the why + sources behind any one.');
+    // Pad ids to a common width so titles line up; ✓ marks an adopted practice.
+    const idWidth = Math.min(34, catalog_1.CATALOG.practices.reduce((w, p) => Math.max(w, p.id.length), 0));
+    for (const tier of catalog_1.CATALOG.tiers) {
+        const inTier = catalog_1.CATALOG.practices.filter((p) => p.tier === tier.id);
+        if (inTier.length === 0)
+            continue;
+        out('');
+        out(`${tier.name}`);
+        for (const p of inTier) {
+            const lvl = adopted.get(p.id);
+            const mark = lvl ? `✓ [${lvl}]` : '·';
+            out(`  ${mark.padEnd(13)} ${p.id.padEnd(idWidth)}  ${p.title}`);
+        }
+    }
+}
+/** The depth view for one practice: what / why / levels / provenance / sources. */
+function printDetail(id, adopted) {
+    const p = catalog_1.CATALOG.practices.find((x) => x.id === id);
+    if (!p) {
+        out(`No practice "${id}" in catalog v${catalog_1.CATALOG.version}.`);
+        const near = catalog_1.CATALOG.practices.filter((x) => x.id.includes(id) || id.includes(x.id)).slice(0, 5);
+        if (near.length) {
+            out('Did you mean:');
+            for (const n of near)
+                out(`  ${n.id}`);
+        }
+        else {
+            out('Run `convene practices` to list them all.');
+        }
+        return;
+    }
+    const lvl = adopted.get(p.id);
+    out(p.title);
+    out(`${p.id}  ·  ${p.tier} / ${p.category}  ·  v${p.version}`);
+    out(lvl ? `adopted here at: ${lvl}` : `not adopted here (suggested level: ${p.defaultLevel})`);
+    out(`enforcement levels: ${p.availableLevels.join(', ')}`);
+    if (p.productionLearned) {
+        out('provenance: production-learned at the BrightAI Opportunity Explorer');
+    }
+    out('');
+    out('WHAT');
+    out(`  ${p.what}`);
+    out('');
+    out('WHY');
+    out(`  ${p.why}`);
+    if (p.sourceUrls && p.sourceUrls.length > 0) {
+        out('');
+        out('SOURCES');
+        for (const u of p.sourceUrls)
+            out(`  - ${u}`);
+    }
+}

package/dist/index.js

@@ -61,6 +61,7 @@ const practice_guard_1 = require("./commands/practice-guard");
 const override_1 = require("./commands/override");
 const watch_1 = require("./commands/watch");
 const explain_1 = require("./commands/explain");
+const practices_1 = require("./commands/practices");
 const update_1 = require("./commands/update");
 const program = new commander_1.Command();
 // Read the version from package.json so `convene --version` always tracks the
@@ -235,6 +236,10 @@ program
     .command('explain [question]')
     .description('ask how Convene itself works (protocol, lanes, halts, privacy, …) — fail-soft, public')
     .action((question) => (0, explain_1.explain)(question));
+program
+    .command('practices [id]')
+    .description('learn the best practices: list adopted + available, or pass an id for the why + sources')
+    .action((id) => (0, practices_1.practices)(id));
 program
     .command('suggest <text>')
     .description('send a feature request / bug report / feedback into Convene')

package/dist/protocol.js

@@ -31,7 +31,7 @@ function block(flavor, slug, member, baseUrl) {
         `This repo is on **Convene** — a tool-agnostic AI development coordination bus — as project \`${slug}\`.`,
         `Dashboard: ${baseUrl}/p/${slug}`,
         '',
-        `> Not connected yet on this machine? Run \`convene setup\` here (or fetch ${baseUrl}/start and follow it) — it self-provisions you and plugs into this project.`,
+        `> **Not connected on this machine?** Paste this one line into your Claude Code **or** Codex session: *"Connect me to Convene for this repo: run \`npm i -g convene-cli@latest\`, then \`convene setup\` and follow the prompts, then \`convene doctor\`."* — or run those yourself, or fetch ${baseUrl}/start and follow it. One time per machine; both tools are then wired automatically.`,
         '',
         'Each turn you get a `<convene-channel>` block — a health line, open items addressed to you, and',
         'recent activity. (Claude Code injects it via the `convene fetch` UserPromptSubmit hook; with other',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convene-cli",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Convene CLI — AI development coordination bus client + UserPromptSubmit hook. Install: npm i -g convene-cli; then `convene setup`.",
   "license": "MIT",
   "homepage": "https://dev.convene.live",