@meetless/mla 0.1.4 → 0.1.6

package/dist/lib/redactor.js

@@ -6,8 +6,10 @@
 // captured content. Cross-plane parity is locked by a shared fixture test
 // (tools/meetless-agent/test/lib/redactor-parity.spec.ts).
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REDACTED = void 0;
+exports.CREDENTIAL_RULE_IDS = exports.SECRET_SCANNER_VERSION = exports.REDACTED = void 0;
 exports.redact = redact;
+exports.scanForSecrets = scanForSecrets;
+exports.scanForCredentials = scanForCredentials;
 exports.redactPayload = redactPayload;
 exports.REDACTED = "[REDACTED]";
 // Order matters: env_assignment runs first so KEY=value pairs are redacted
@@ -73,6 +75,107 @@ function redact(text) {
     out = out.replace(ENTROPY_TOKEN, (m) => (looksHighEntropy(m) ? exports.REDACTED : m));
     return out;
 }
+// --- Block-on-detect secret scanner (SECRET-1) ---
+//
+// The agent-memory capture pipeline
+// (notes/20260626-agent-memory-auto-capture-proposal.md) must BLOCK a file from
+// leaving the machine when it contains a known high-risk secret, rather than
+// silently redact-and-send. This reuses the parity-locked PATTERNS + entropy
+// heuristic above for detection and adds directive-style secrets the
+// substitution redactor does not carry.
+//
+// HONEST SCOPE (do not overstate to users): this blocks KNOWN secret PATTERNS
+// locally; it is NOT a guarantee that "secrets cannot leave the machine." A
+// novel or low-entropy credential can still pass. Returns the set of matched
+// rule ids, sorted + de-duplicated; the matched secret text is NEVER returned,
+// so a caller that logs findings cannot leak the secret. Empty array == clean.
+// Directive-style secrets the substitution redactor intentionally omits (it
+// substitutes; this one only blocks). requirepass/masterauth/masteruser are
+// Redis/Sentinel config directives: a lowercase keyword + space + value, which
+// the uppercase env_assignment pattern and the 32-char entropy gate both miss
+// (e.g. an 8-char `requirepass <value>` slips past both).
+const BLOCK_DIRECTIVE_PATTERNS = [
+    ["redis_directive", /\b(requirepass|masterauth|masteruser)\s+('[^']*'|"[^"]*"|\S+)/gi],
+];
+// A pure-hex token (git SHA, content hash, digest) is not a secret, and the
+// agent-memory corpus is dense with them. Excluding hex from the entropy block
+// keeps the dry-run from blocking nearly every file on an incidental 40-char
+// hash while still catching base64/mixed-class credential blobs.
+function isHexToken(token) {
+    return /^[0-9a-f]+$/i.test(token);
+}
+// Bump when the block-on-detect pattern set or entropy heuristic changes. The
+// capture ledger stores this alongside a blocked file so a policy upgrade
+// re-evaluates content blocked under an older version (RETRY-2 for blocks).
+exports.SECRET_SCANNER_VERSION = "2026-06-27.1";
+function scanForSecrets(text) {
+    if (!text)
+        return [];
+    const hits = new Set();
+    for (const [name, pat] of PATTERNS) {
+        pat.lastIndex = 0;
+        if (pat.test(text))
+            hits.add(name);
+    }
+    for (const [name, pat] of BLOCK_DIRECTIVE_PATTERNS) {
+        pat.lastIndex = 0;
+        if (pat.test(text))
+            hits.add(name);
+    }
+    ENTROPY_TOKEN.lastIndex = 0;
+    let m;
+    while ((m = ENTROPY_TOKEN.exec(text)) !== null) {
+        const tok = m[0];
+        if (!isHexToken(tok) && looksHighEntropy(tok)) {
+            hits.add("high_entropy_token");
+            break;
+        }
+    }
+    return [...hits].sort();
+}
+// --- Pre-upload credential denylist (Phase 2A/2B, proposal §4/§6) ---
+//
+// The LIVE capture path (Phase 2A+) must withhold a file from upload when it
+// carries a KNOWN, high-confidence credential FORMAT, because the real corpus
+// contains a live credential (SECRET-1). This is DELIBERATELY NOT scanForSecrets:
+// it excludes the generic Shannon-entropy heuristic, which over-blocked 99.2% of
+// the corpus in the Phase 0A static audit and is explicitly rejected for the
+// blocking path. It runs ONLY the precision-first format matchers: provider-token
+// prefixes (sk-/ghp_/AKIA/...), Authorization headers (Bearer/Basic), cookies,
+// PEM private-key blocks, the Redis `requirepass`/`masterauth`/`masteruser`
+// directives, and credential-named env assignments.
+//
+// HONEST SCOPE (do not overstate to users): a clean result means "none of these
+// known formats are present," NOT "no secret exists." A novel or unformatted
+// credential can still pass; that is an accepted, documented limit (§4 SECRET-1).
+// Returns the matched rule ids, sorted + de-duplicated; the secret text is NEVER
+// returned. Empty array == clean (eligible for upload). Reuses the parity-safe
+// PATTERNS + BLOCK_DIRECTIVE_PATTERNS so the block formats stay in lockstep with
+// the observe-only scanner, minus entropy.
+exports.CREDENTIAL_RULE_IDS = [
+    "env_assignment",
+    "bearer",
+    "provider_token",
+    "cookie",
+    "pem_key",
+    "redis_directive",
+];
+function scanForCredentials(text) {
+    if (!text)
+        return [];
+    const hits = new Set();
+    for (const [name, pat] of PATTERNS) {
+        pat.lastIndex = 0;
+        if (pat.test(text))
+            hits.add(name);
+    }
+    for (const [name, pat] of BLOCK_DIRECTIVE_PATTERNS) {
+        pat.lastIndex = 0;
+        if (pat.test(text))
+            hits.add(name);
+    }
+    return [...hits].sort();
+}
 function redactPayload(value) {
     if (typeof value === "string")
         return redact(value);

package/dist/lib/scanner/agent-memory.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_AGENT_MEMORY_PROVIDERS = exports.claudeCodeProvider = void 0;
 exports.agentMemoryDir = agentMemoryDir;
 exports.readAgentMemoryFiles = readAgentMemoryFiles;
 exports.parseAgentMemoryDirectives = parseAgentMemoryDirectives;
+exports.collectAgentMemoryFiles = collectAgentMemoryFiles;
 exports.discoverAgentMemoryDirectives = discoverAgentMemoryDirectives;
 // src/lib/scanner/agent-memory.ts
 //
@@ -18,6 +20,7 @@ exports.discoverAgentMemoryDirectives = discoverAgentMemoryDirectives;
 // "not attested" and can NEVER earn must-follow; it rides advisory until a human attests.
 // `render.ts` already enforces this (must-follow requires `human_attested`), and
 // `scanWorkspace` keeps these out of the auto-injected `confirmedRulesXml` pack entirely.
+const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
@@ -27,11 +30,27 @@ const frontmatter_1 = require("./frontmatter");
 // Mirrors parse-directives.ts MUST_TOKENS so strength is consistent across sources.
 const MUST_TOKENS = /\b(MUST|NEVER|ALWAYS|REQUIRED|DO NOT|DON'?T|FORBIDDEN|NON-NEGOTIABLE)\b/;
 // Resolve the agent-memory dir for a workspace cwd. Replicates Claude Code's projects-dir
-// encoding (slashes AND dots become dashes). `home` is injectable for tests.
+// encoding (slashes AND dots become dashes). `home` is injectable for tests. This is an
+// implementation detail of the Claude Code provider below, NOT a workspace identity: the
+// same repo encodes to different dirs from its git root, a nested dir, a worktree, or a
+// symlinked clone (memo Phase 2). Discovery keeps it behind the provider seam so the
+// path convention never leaks into the workspace model.
 function agentMemoryDir(cwd, home = (0, node_os_1.homedir)()) {
     const encoded = cwd.replace(/[/.]/g, "-");
     return (0, node_path_1.join)(home, ".claude", "projects", encoded, "memory");
 }
+// Claude Code: ~/.claude/projects/<encoded-cwd>/memory/.
+exports.claudeCodeProvider = {
+    name: "claude-code",
+    memoryDirs(searchPath, home) {
+        return [agentMemoryDir(searchPath, home)];
+    },
+};
+// The default provider set. Today only Claude Code; the list is the extension point.
+exports.DEFAULT_AGENT_MEMORY_PROVIDERS = [exports.claudeCodeProvider];
+function contentFingerprint(text) {
+    return (0, node_crypto_1.createHash)("sha256").update(text, "utf8").digest("hex");
+}
 // Read the `feedback_*.md` topic files (the "rules the user gave" bucket) from an
 // agent-memory dir, sorted for a stable/diffable worklist. Fails open to []: a missing
 // dir (fresh machine, no prior agent memory) is the common case and must never abort the
@@ -92,8 +111,40 @@ function parseAgentMemoryDirectives(files) {
 // surface in full; bounding scan-time I/O only matters at the absurd end. Scan runs on
 // `mla activate`, not the per-Write hot path, so reading a few hundred small files is cheap.
 const DEFAULT_AGENT_MEMORY_CAP = 500;
-// Discover + parse the agent-memory rules for a workspace cwd. The advisory worklist is
+// Collect feedback memory files for a workspace across every provider and search path,
+// deduped by CONTENT fingerprint: the same memory found under two encoded paths (e.g. the
+// repo opened once at its root and once at a nested dir) collapses to a single entry,
+// tagged with the first provider/path that surfaced it. Missing memory is a harmless
+// zero-result. Sorted by name (then sourcePath) for a stable, diffable worklist.
+function collectAgentMemoryFiles(cwd, home = (0, node_os_1.homedir)(), opts = {}) {
+    const providers = opts.providers ?? exports.DEFAULT_AGENT_MEMORY_PROVIDERS;
+    // Active session path + canonical root, order-preserving and de-duplicated.
+    const searchPaths = [];
+    for (const p of [cwd, opts.canonicalRoot]) {
+        if (p && !searchPaths.includes(p))
+            searchPaths.push(p);
+    }
+    const seen = new Set();
+    const out = [];
+    for (const provider of providers) {
+        for (const searchPath of searchPaths) {
+            for (const dir of provider.memoryDirs(searchPath, home)) {
+                for (const f of readAgentMemoryFiles(dir)) {
+                    const fp = contentFingerprint(f.text);
+                    if (seen.has(fp))
+                        continue;
+                    seen.add(fp);
+                    out.push({ ...f, provider: provider.name, sourcePath: (0, node_path_1.join)(dir, f.name) });
+                }
+            }
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name) || (a.sourcePath ?? "").localeCompare(b.sourcePath ?? ""));
+}
+// Discover + parse the agent-memory rules for a workspace. The advisory worklist is
 // surfaced for review, never bulk-injected. Fully fail-open via readAgentMemoryFiles.
-function discoverAgentMemoryDirectives(cwd, home = (0, node_os_1.homedir)(), cap = DEFAULT_AGENT_MEMORY_CAP) {
-    return parseAgentMemoryDirectives(readAgentMemoryFiles(agentMemoryDir(cwd, home))).slice(0, cap);
+// The default 3-arg call (cwd, home, cap) is preserved; pass opts to search a canonical
+// root or a custom provider set.
+function discoverAgentMemoryDirectives(cwd, home = (0, node_os_1.homedir)(), cap = DEFAULT_AGENT_MEMORY_CAP, opts = {}) {
+    return parseAgentMemoryDirectives(collectAgentMemoryFiles(cwd, home, opts)).slice(0, cap);
 }

package/dist/lib/scanner/scan.js

@@ -12,6 +12,7 @@ const parse_directives_1 = require("./parse-directives");
 const parse_structured_1 = require("./parse-structured");
 const render_1 = require("./render");
 const agent_memory_1 = require("./agent-memory");
+const managed_rules_1 = require("./managed-rules");
 const MAX_FILE_BYTES = 256 * 1024; // skip large files for the free pass
 function scanWorkspace(cwd, opts) {
     const tracked = gitLsFiles(cwd);
@@ -21,6 +22,11 @@ function scanWorkspace(cwd, opts) {
     let decisionDocs = 0;
     let legacyNotes = 0;
     for (const rel of tracked) {
+        // The mla-managed rule file is handled by its own parser below (read directly from disk
+        // so it is effective before it is committed). Skip it here so it is not also processed as
+        // a generic T2 prose doc, which would double-count it and run stale detection on it.
+        if (rel === managed_rules_1.MANAGED_RULES_PATH)
+            continue;
         const tier = (0, score_1.classifyTier)(rel);
         if (!tier)
             continue;
@@ -70,6 +76,14 @@ function scanWorkspace(cwd, opts) {
         seenSources.add(s.source);
         return true;
     });
+    // The mla-managed rule file (.meetless/rules.md) is the canonical source of durable repo
+    // policy (memo Phase 1). Read it DIRECTLY from disk (not via git ls-files) so a rule is
+    // effective locally the moment it is written, before the human commits and pushes to share
+    // it. Every managed rule is human_attested, so a MUST_FOLLOW one earns must-follow injection.
+    // Searched at the active path and the canonical root, the same as agent-memory, and folded
+    // into the directive list BEFORE dedupe so it participates in authority ranking.
+    const canonicalRoot = gitToplevel(cwd);
+    directives.push(...readManagedDirectives(cwd, canonicalRoot));
     // Collapse the same rule attested by multiple instruction files into one, so
     // the stored array, the reported rule count, and the grounding pack all agree
     // on distinct rules rather than per-file occurrences.
@@ -80,7 +94,13 @@ function scanWorkspace(cwd, opts) {
     // human review and deliberately excluded from `confirmedRulesXml` (never auto-injected as
     // must-follow): untracked => not attested => ingest is not accept.
     const committedTexts = new Set(dedupedDirectives.map((d) => d.text));
-    const advisoryDirectives = (0, agent_memory_1.discoverAgentMemoryDirectives)(cwd, opts.home).filter((d) => !committedTexts.has(d.text));
+    // Search the active session path AND the canonical repo root: the same repo opened at a
+    // nested dir or a worktree encodes to a different agent-memory dir, so binding identity to
+    // a single path would silently miss memory (memo Phase 2). Discovery dedupes by content.
+    // canonicalRoot was resolved above for the managed-rules read; reuse it.
+    const advisoryDirectives = (0, agent_memory_1.discoverAgentMemoryDirectives)(cwd, opts.home, undefined, {
+        canonicalRoot,
+    }).filter((d) => !committedTexts.has(d.text));
     const inventory = {
         instructionFiles,
         decisionDocs,
@@ -112,6 +132,37 @@ function gitLsFiles(cwd) {
         return [];
     }
 }
+// The canonical repo root (git toplevel), or undefined outside a repo. Used only to widen
+// agent-memory discovery beyond the active session path; it does NOT define workspace identity.
+function gitToplevel(cwd) {
+    try {
+        const top = (0, node_child_process_1.execFileSync)("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" }).trim();
+        return top || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Read + parse the mla-managed rule file from disk at the active path and (if distinct) the
+// canonical root, merging both into one human_attested directive set. Reading from disk (not
+// git) is deliberate: a freshly written rule is effective locally before it is committed.
+// Missing file is a harmless zero-result. The two reads are deduped by rule id inside
+// parseManagedRules/managedRulesToDirectives, so an uncommitted-vs-committed copy collapses.
+function readManagedDirectives(cwd, canonicalRoot) {
+    const roots = [cwd, canonicalRoot].filter((r) => Boolean(r));
+    const seen = new Set();
+    const dirs = [];
+    for (const root of roots) {
+        if (seen.has(root))
+            continue;
+        seen.add(root);
+        const text = safeRead((0, node_path_1.join)(root, managed_rules_1.MANAGED_RULES_PATH));
+        if (text === null)
+            continue;
+        dirs.push(...(0, managed_rules_1.managedRulesToDirectives)((0, managed_rules_1.parseManagedRules)(text)));
+    }
+    return dirs;
+}
 function gitHead(cwd) {
     try {
         return (0, node_child_process_1.execFileSync)("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" }).trim();

package/dist/lib/scanner/score.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCuratedDoc = isCuratedDoc;
 exports.classifyTier = classifyTier;
 exports.isInstructionFile = isInstructionFile;
 // Agent-instruction filenames matched by BASENAME, not full path: real monorepos
@@ -9,23 +10,60 @@ exports.isInstructionFile = isInstructionFile;
 const T1_BASENAMES = new Set([
     "CLAUDE.md", "AGENTS.md", "GEMINI.md", "memory.md", "copilot-instructions.md",
 ]);
-const T2_NAMES = new Set(["README.md", "README", "ARCHITECTURE.md", "CONTRIBUTING.md"]);
+// Curated decision / instruction-adjacent docs: known high-signal BASENAMES plus
+// decision-record directories. Basenames are matched by basename (not full path) for
+// the SAME reason as T1_BASENAMES above: a monorepo keeps a README.md / ARCHITECTURE.md
+// per package, and full-path matching would treat every nested one as anonymous prose.
+// These are still tier T2, but `isCuratedDoc` lets the enrichment ranker float them
+// above generic prose so a tight target budget is not spent on arbitrary marketing .md
+// while a real ADR or package README is crowded out (plan §5b).
+const T2_BASENAMES = new Set(["README.md", "README", "ARCHITECTURE.md", "CONTRIBUTING.md"]);
 const T2_DIRS = ["docs/adr/", "docs/rfc/", "docs/decisions/", "docs/specs/", "docs/runbooks/"];
 const T3_NAMES = new Set(["package.json", "prisma/schema.prisma", "docker-compose.yml", ".env.example"]);
 const DENY_EXT = /\.(ts|tsx|js|jsx|py|go|rs|java|lock|map|png|jpg|svg|snap)$/i;
 const DENY_NAME = /(^|\/)(pnpm-lock\.yaml|package-lock\.json|yarn\.lock)$/i;
+// Generated / vendored output directories. Even when a repo commits them (e.g. a
+// Forge app that checks in its webpack bundle), nothing under them is a governance
+// doc: it is third-party or machine-emitted. Match the segment anywhere in the path
+// so a committed `apps/x/build/static/...` is excluded the same as a root `dist/`.
+const DENY_DIR = /(^|\/)(node_modules|dist|build|out|coverage|vendor|\.next|\.nuxt|\.svelte-kit|\.turbo|\.cache|\.output)\//i;
+// Minified-bundle license sidecars (terser/webpack emit `<chunk>.js.LICENSE.txt`):
+// pure third-party license boilerplate, never a governance doc, and they can sit
+// outside a build dir when an app serves its bundle from a tracked static folder.
+const DENY_GENERATED = /\.LICENSE\.txt$/i;
+// Test / eval / fixture corpora. These trees hold test data, eval benchmarks, and
+// deliberately-broken fixtures (e.g. an eval's `broken_outputs/*.txt` are MALFORMED
+// answers used to test the harness): reading them as governance docs both drowns the
+// real docs and risks minting false claims from poison. The intel repo proved it: 171
+// of 179 tracked .md files live under `evals/`, crowding a real `notes/` doc out of
+// the top 20. Match whole path SEGMENTS so `latest/` or a `docs/testing-policy.md` are
+// untouched. Deliberately EXCLUDES `spec`/`specs` (overloaded: `docs/specs/` is a
+// governance T2_DIR, and OpenAPI/spec docs are real). Widen only on real dogfood need.
+const DENY_TESTDIR = /(^|\/)(evals?|tests?|__tests__|e2e|fixtures|__fixtures__|testdata|test[-_]data|__mocks__|__snapshots__)\//i;
 function basename(p) {
     const i = p.lastIndexOf("/");
     return i >= 0 ? p.slice(i + 1) : p;
 }
+// A curated T2 doc: a known high-signal doc name (at any depth) or a file under a
+// decision-record directory, as opposed to arbitrary prose that merely ends in .md.
+// Used by the enrichment ranker to order curated docs above generic prose within T2.
+// Pure name/path test: it does NOT run the DENY checks, so call it only on a path
+// `classifyTier` has already accepted (the deny gates ran there first).
+function isCuratedDoc(p) {
+    return T2_BASENAMES.has(basename(p)) || T2_DIRS.some((d) => p.startsWith(d));
+}
 function classifyTier(p) {
-    if (DENY_NAME.test(p) || DENY_EXT.test(p))
+    if (DENY_NAME.test(p) ||
+        DENY_EXT.test(p) ||
+        DENY_DIR.test(p) ||
+        DENY_GENERATED.test(p) ||
+        DENY_TESTDIR.test(p))
         return null;
     if (T1_BASENAMES.has(basename(p)) || p.startsWith(".claude/rules/") || p.startsWith(".cursor/rules/"))
         return "T1";
     if (p.startsWith("notes/"))
         return "T4";
-    if (T2_NAMES.has(p) || T2_DIRS.some((d) => p.startsWith(d)))
+    if (isCuratedDoc(p))
         return "T2";
     if (T3_NAMES.has(p) || p.startsWith(".github/workflows/"))
         return "T3";

package/dist/lib/scanner/scout-mission.js

@@ -71,12 +71,13 @@ function renderCategories(policy) {
     return policy.categories.map((c) => `  • ${c.kind}: ${c.gloss}`);
 }
 /**
- * The default `fast` tier invitation to go agentic. When the deterministic pass
- * left deep docs unread (decision/spec docs or legacy notes it could only count),
- * return a one-line nudge naming `mla activate --bootstrap agentic` and quantifying
- * the unread surface, so the deeper bootstrap is discoverable without reading
- * `--help` (design: "invite agentic bootstrap inside the first session", line 709).
- * When there is nothing deep to scout, return null so the bundle does not nag.
+ * The default `fast` tier invitation to go deeper. When the deterministic pass left
+ * deep docs unread (decision/spec docs or legacy notes it could only count), return a
+ * one-line nudge naming the consolidated `/mla onboard` flow and quantifying the
+ * unread surface, so the deeper read is discoverable without reading `--help`
+ * (notes/20260624-mla-new-user-value-and-brownfield-proof.md, Phase 2: one public
+ * onboarding flow). When there is nothing deep to scout, return null so the bundle
+ * does not nag.
  */
 function renderAgenticInvitation(scan) {
     const docs = scan.inventory.decisionDocs;
@@ -86,7 +87,8 @@ function renderAgenticInvitation(scan) {
     }
     return (`Deeper docs went unread in this fast pass ` +
         `(${pluralize(docs, "decision/spec doc")}, ${pluralize(notes, "legacy note")}). ` +
-        "Run `mla activate --bootstrap agentic` for a scout mission that digs into them.");
+        "Run `/mla onboard` inside a Claude Code session to dispatch two read-only scouts " +
+        "that dig into them and surface candidates born PENDING for review.");
 }
 /**
  * Render the agentic scout mission for `mla activate --bootstrap agentic`. Pure

package/dist/lib/upgrade-apply.js

@@ -37,6 +37,7 @@ exports.REEXEC_GUARD_ENV = void 0;
 exports.stateFilePath = stateFilePath;
 exports.readUpdateState = readUpdateState;
 exports.writeUpdateState = writeUpdateState;
+exports.stampLatestFromManifest = stampLatestFromManifest;
 exports.liveBinaryPath = liveBinaryPath;
 exports.prevBinaryPath = prevBinaryPath;
 exports.stagedDir = stagedDir;
@@ -105,6 +106,30 @@ function writeUpdateState(state) {
         // best-effort; a read-only HOME just means we re-check next time.
     }
 }
+// Persist the latest published version + minimum-supported floor learned from a
+// freshly VERIFIED manifest into the update cache. The passive nag reads ONLY the
+// cache; a foreground `mla upgrade [--check]` fetches the manifest LIVE. Without
+// this, the two disagree: `--check` can see a new release while the throttled
+// background check leaves the cache stale, so the nag never fires (it has nothing
+// newer to report). Stamping here makes any foreground upgrade path refresh the
+// cache as a side effect, so the manual and passive surfaces always agree.
+//
+// Preserves lastCheckedAt (the background-check throttle is a separate concern)
+// and any staged binary. Best-effort: a cache write must never fail an otherwise
+// successful upgrade command.
+function stampLatestFromManifest(manifest) {
+    try {
+        const prev = readUpdateState();
+        writeUpdateState({
+            ...prev,
+            latestVersion: manifest.version,
+            minVersion: manifest.minVersion,
+        });
+    }
+    catch {
+        // never let a cache write break `mla upgrade`
+    }
+}
 // --- filesystem layout -------------------------------------------------------
 // The curl install puts the binary here (install.sh: $HOME/.meetless/bin/mla),
 // as a plain file (no symlink), so rename(2) over this path atomically swaps the
@@ -574,6 +599,11 @@ async function runUpgrade(opts) {
         return 1;
     }
     const manifest = verified.manifest;
+    // We just verified the authoritative "latest" pointer live. Refresh the cache
+    // the passive nag reads BEFORE any of the early returns below (--check,
+    // up-to-date, no-artifact, ...), so a manual `mla upgrade --check` un-sticks a
+    // stale nag instead of discarding what it learned.
+    stampLatestFromManifest(manifest);
     const triple = (0, update_check_1.currentTriple)(process.platform, process.arch);
     const plan = (0, update_check_1.planUpgrade)({ current, manifest, triple, force: args.force });
     switch (plan.action) {

package/dist/lib/wire.js

@@ -856,6 +856,8 @@ There are exactly two scouts: \`documentation\` and \`history\`. For each role:
   c. The subagent returns exactly one JSON object (a scout result). Capture it verbatim. If it wrapped the JSON in prose, extract only the JSON object.
 Do NOT pass a scout anything other than the brief from step 2a. The brief is the exact contract \`enrich ingest\` validates against; adding your own files or instructions breaks that contract. Do NOT edit a scout's returned JSON.
 
+If a dispatch fails with "Agent type '${scout_brief_1.SCOUT_AGENT_NAME.documentation}' (or '${scout_brief_1.SCOUT_AGENT_NAME.history}') not found", do NOT fall back to \`general-purpose\` or any other agent: the scouts' tool boundary (doc scout = Read only; history scout = no tools) is enforced by those subagent definitions, and a substitute would run the scout with the wrong capabilities. This failure means the scout agents were installed (by \`mla init\`/\`mla rewire\`) AFTER this Claude Code session started, and Claude Code loads agent definitions only at session start. Stop and tell An: the scout agents are installed but not yet loaded; restart Claude Code (or open a new session), then re-run \`/mla onboard\`. The run record from Step 1 is durable, so nothing is lost.
+
 Step 3: Ingest.
 Assemble one JSON object: \`{"runId": "<runId>", "results": [<documentation result>, <history result>]}\`. Write it to a temporary file (for example \`/tmp/mla-onboard-<runId>.json\`) with the Write tool, then run \`mla enrich ingest --run-id <runId> --results-file <that file>\`. Print its summary verbatim. It reports, per scout, how many candidates were accepted, rejected, and persisted born PENDING.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meetless/mla",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "license": "Apache-2.0",
   "private": false,
   "description": "Meetless CLI (mla): governed change-control and knowledge for AI coding agents.",
@@ -61,9 +61,9 @@
     "ts-jest": "^29.1.2",
     "ts-node": "^10.9.2",
     "typescript": "^5.4.5",
+    "@meetless/ask-core": "0.1.0",
     "@meetless/mcp": "0.1.0",
-    "@meetless/trace-core": "0.1.0",
-    "@meetless/ask-core": "0.1.0"
+    "@meetless/trace-core": "0.1.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/copy-assets.js && node scripts/gen-build-info.js && node scripts/bundle-esm.js && chmod +x dist/cli.js dist/pretool-entry.js",