Break-glass merge PR #2628

Author: DeusData

README.md

@@ -798,7 +798,7 @@ codebase-memory-mcp config list                          # show all settings
 codebase-memory-mcp config set auto_index true           # auto-index on session start
 codebase-memory-mcp config set auto_index_limit 50000    # max files for auto-index
 codebase-memory-mcp config set auto_watch false          # don't register background git watcher (default: true)
-codebase-memory-mcp config set doc_candidates false      # skip doc<->code candidate scoring on huge repos (default: true)
+codebase-memory-mcp config set doc_candidates false      # skip doc<->code candidate scoring on huge repos (default: auto = on for full, off for moderate/fast)
 codebase-memory-mcp config set watcher_enabled false     # stop the watcher thread entirely (default: true)
 codebase-memory-mcp config set watch_non_git true        # also poll non-git project roots (default: false)
 codebase-memory-mcp config set index_max_files 250000    # optional per-index source-file limit

docs/CONFIGURATION.md

@@ -88,7 +88,7 @@ Current keys:
 | `auto_index` | `false` | Automatically index new projects when an MCP session starts. |
 | `auto_index_limit` | `50000` | Maximum file count allowed for automatic indexing of a new project. |
 | `auto_watch` | `true` | Register the session's project with the background git watcher on connect. Set `false` to keep a session from registering its project (the watcher still runs for other projects). |
-| `doc_candidates` | `true` | Score documentation sections against code to store doc↔code candidates (the possible targets of a section, and the sections that may describe a function or file, each with a judged probability). The scoring grows with sections × functions: under a second up to ~100k functions, ~15 s at ~400k, ~3 minutes on the Linux kernel. Set `false` to skip it; no candidates are stored and the rest of the graph is unchanged. `index_repository` also takes `doc_candidates` for a single index, which wins over this setting. Applies from the next index. |
+| `doc_candidates` | `auto` | Score documentation sections against code to store doc↔code candidates (the possible targets of a section, and the sections that may describe a function or file, each with a judged probability). Unset (`auto`), the index mode decides: on for `full` indexes (the default mode), off for `moderate` and `fast`. Set `true` or `false` to choose for every mode; `config reset doc_candidates` returns to `auto`. The scoring grows with sections × functions: under a second up to ~100k functions, ~15 s at ~400k, ~3 minutes on the Linux kernel. Off stores no candidates and leaves the rest of the graph unchanged; on in `fast` mode stores candidates without adding `fast`'s skipped `SIMILAR_TO` / `SEMANTICALLY_RELATED` edges. `index_repository` also takes `doc_candidates` for a single index, which wins over this setting. Applies from the next index. |
 | `watcher_enabled` | `true` | Master switch for the background watcher subsystem. Set `false` to stop the watcher from starting at all — no poll thread and no project registration. Reindex manually with `index_repository` when disabled. Only an open MCP session's own project is ever watched; `index_status` reports the current state in its `watch` object. |
 | `watch_non_git` | `false` | Also poll project roots that are **not git repositories**. By default the watcher only follows git projects, so a project indexed from a plain directory is never refreshed after its first index — reindex it manually with `index_repository`. Set `true` to poll such roots on the same adaptive cadence with a file-tree scan: the indexer's own discovery walk (same skip lists, `.gitignore` and `.cbmignore` rules) hashed over each file's path, size and mtime. Any change reindexes once; paths the indexer skips (including cbm's own `.codebase-memory/` output) never trigger. The first poll after the daemon starts reindexes each such project once, since nothing records which tree state the index holds. The scan walks the whole tree every poll, so it costs more than git polling on very large trees. Read once when the daemon starts, like `watcher_enabled`. |
 | `index_max_files` | `off` | Optional maximum number of accepted source files in one discovery run. |

src/cli/cli.c

@@ -7461,18 +7461,29 @@ const char *cbm_config_get(cbm_config_t *cfg, const char *key, const char *defau
     return result;
 }
 
-bool cbm_config_get_bool(cbm_config_t *cfg, const char *key, bool default_val) {
+bool cbm_config_get_bool_set(cbm_config_t *cfg, const char *key, bool *value) {
     const char *val = cbm_config_get(cfg, key, NULL);
     if (!val) {
-        return default_val;
+        return false;
     }
+    bool parsed;
     if (strcmp(val, "true") == 0 || strcmp(val, "1") == 0 || strcmp(val, "on") == 0) {
-        return true;
-    }
-    if (strcmp(val, "false") == 0 || strcmp(val, "0") == 0 || strcmp(val, "off") == 0) {
+        parsed = true;
+    } else if (strcmp(val, "false") == 0 || strcmp(val, "0") == 0 || strcmp(val, "off") == 0) {
+        parsed = false;
+    } else {
         return false;
     }
-    return default_val;
+    if (value) {
+        *value = parsed;
+    }
+    return true;
+}
+
+bool cbm_config_get_bool(cbm_config_t *cfg, const char *key, bool default_val) {
+    bool value = default_val;
+    (void)cbm_config_get_bool_set(cfg, key, &value);
+    return value;
 }
 
 int cbm_config_get_int(cbm_config_t *cfg, const char *key, int default_val) {
@@ -7574,6 +7585,9 @@ static const config_key_def_t CONFIG_KEYS[] = {
     {CBM_CONFIG_AUTO_INDEX, "false", "Enable auto-indexing on MCP session start"},
     {CBM_CONFIG_AUTO_INDEX_LIMIT, "50000", "Max files for auto-indexing new projects"},
     {CBM_CONFIG_AUTO_WATCH, "true", "Register background git watcher on session connect"},
+    /* Unset: the index mode decides (cbm_pipeline_doc_candidates_enabled). */
+    {CBM_CONFIG_DOC_CANDIDATES, "auto",
+     "Doc-code candidates: auto = on for full, off for moderate/fast; true/false forces"},
     {CBM_CONFIG_WATCHER_ENABLED, "true",
      "Run the background watcher thread (auto-reindex); false to disable"},
     {CBM_CONFIG_WATCH_NON_GIT, "false",

src/cli/cli.h

@@ -434,6 +434,11 @@ const char *cbm_config_get(cbm_config_t *cfg, const char *key, const char *defau
 /* Get a config value as bool. "true"/"1"/"on" → true. */
 bool cbm_config_get_bool(cbm_config_t *cfg, const char *key, bool default_val);
 
+/* A key the user set to a boolean ("true"/"1"/"on", "false"/"0"/"off"):
+ * true, with *value. Unset or unparseable: false, *value untouched -- the
+ * caller's own default applies (cbm_config_get_bool's reading). */
+bool cbm_config_get_bool_set(cbm_config_t *cfg, const char *key, bool *value);
+
 /* Get a config value as int. Returns default_val if not found or invalid. */
 int cbm_config_get_int(cbm_config_t *cfg, const char *key, int default_val);
 

src/cli/runtime_settings.c

@@ -46,10 +46,12 @@ static const setting_t settings[] = {
     CFG("auto_watch", "Automatic watching",
         "Register a background Git watcher when an MCP session connects.", "boolean", "true", 0, 0,
         NULL, "src/mcp/mcp.c", "next-session"),
+    /* No fixed default: unset, the index mode decides (shown as automatic). */
     CFG("doc_candidates", "Doc-code candidates",
-        "Score documentation sections against code for doc-code candidates. Costly on very large "
-        "repositories; off stores none.",
-        "boolean", "true", 0, 0, NULL, "src/mcp/mcp.c", "next-session"),
+        "Score documentation sections against code for doc-code candidates. Automatic: on for "
+        "full indexes, off for moderate and fast; on or off applies to every mode. Costly on very "
+        "large repositories; off stores none.",
+        "boolean", NULL, 0, 0, NULL, "src/mcp/mcp.c", "next-session"),
     CFG("watcher_enabled", "Background watcher", "Enable the daemon's background watcher thread.",
         "boolean", "true", 0, 0, NULL, "src/daemon/application.c", "restart"),
     {"ui-lang", "Interface language", "Language preference used by subsequent HTTP requests.",

src/daemon/application.c

@@ -2319,12 +2319,16 @@ static bool application_index_args_add_policy(cbm_daemon_application_t *applicat
     cbm_index_resource_policy_t policy;
     char error[CBM_SZ_256] = {0};
     bool loaded = cbm_config_load_index_policy(config, &policy, error, sizeof(error));
+    /* The worker reads no config: a doc_candidates setting the user set
+     * travels with the request; unset, the worker's index mode decides. */
+    bool doc_candidates_encoded =
+        !loaded || cbm_mcp_index_doc_candidates_add_to_args(document, root, config);
     cbm_config_close(owned_config);
     if (!loaded) {
         cbm_log_error("daemon.index.policy", "error", error);
         return false;
     }
-    return cbm_mcp_index_policy_add_to_args(document, root, &policy);
+    return doc_candidates_encoded && cbm_mcp_index_policy_add_to_args(document, root, &policy);
 }
 
 static char *application_auto_index_args(cbm_daemon_application_t *application,

src/mcp/mcp.c

@@ -549,7 +549,8 @@ static const tool_def_t TOOLS[] = {
      "\"persistence\":{\"type\":\"boolean\",\"default\":false,\"description\":"
      "\"Write .codebase-memory/graph.db.zst.\"},"
      "\"doc_candidates\":{\"type\":\"boolean\",\"description\":"
-     "\"Doc-code candidates; default: the doc_candidates setting (on).\"},"
+     "\"Doc-code candidates; default: the doc_candidates setting, else on for full, off for "
+     "moderate/fast.\"},"
      "\"async\":{\"type\":\"boolean\",\"default\":false,\"description\":"
      "\"Start the index in the background and return immediately; it keeps running if this "
      "call is cancelled or times out. Not with status or cross-repo-intelligence. Refused for a "
@@ -11457,6 +11458,13 @@ bool cbm_mcp_index_policy_add_to_args(yyjson_mut_doc *doc, yyjson_mut_val *root,
     return valid && yyjson_mut_obj_add_val(doc, root, "_cbm_index_policy", encoded);
 }
 
+bool cbm_mcp_index_doc_candidates_add_to_args(yyjson_mut_doc *doc, yyjson_mut_val *root,
+                                              cbm_config_t *config) {
+    bool enabled = false;
+    return !cbm_config_get_bool_set(config, CBM_CONFIG_DOC_CANDIDATES, &enabled) ||
+           yyjson_mut_obj_add_bool(doc, root, "doc_candidates", enabled);
+}
+
 /* Run index_repository in a supervised worker subprocess with skip-and-continue
  * (Stage 3c). Returns the response string (caller frees):
  *   - the worker's own response on a clean first run (the common path);
@@ -11786,8 +11794,11 @@ static char *index_run_supervised_path(cbm_mcp_server_t *srv, const char *root_p
     yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
     yyjson_mut_val *root = yyjson_mut_obj(doc);
     yyjson_mut_doc_set_root(doc, root);
+    /* A doc_candidates setting the user set travels with the request (the
+     * worker reads no config); unset, the worker's index mode decides. */
     if (!yyjson_mut_obj_add_strcpy(doc, root, "repo_path", root_path) ||
-        !cbm_mcp_index_policy_add_to_args(doc, root, &policy)) {
+        !cbm_mcp_index_policy_add_to_args(doc, root, &policy) ||
+        !cbm_mcp_index_doc_candidates_add_to_args(doc, root, srv ? srv->config : NULL)) {
         yyjson_mut_doc_free(doc);
         return NULL;
     }
@@ -11837,32 +11848,52 @@ static bool resolve_session_repo_path(cbm_mcp_server_t *srv, char **repo_path) {
     return true;
 }
 
-/* doc_candidates for one index: an explicit boolean argument wins, else the
- * doc_candidates setting (default on). The parent resolves it once and passes
- * the decided value on, so a daemon job or supervised worker gets it as an
- * argument instead of reading a config of its own. */
-static bool index_doc_candidates_enabled(cbm_mcp_server_t *srv, const char *args) {
+/* doc_candidates for one index, explicit or unset: an explicit boolean
+ * argument wins, else a doc_candidates setting the user set to a boolean.
+ * Neither: unset, and the pipeline's index mode decides (on for full, off
+ * for moderate and fast). The parent resolves an explicit value once and
+ * passes it on, so a daemon job or supervised worker gets it as an argument
+ * instead of reading a config of its own; an unset one is not passed. */
+typedef enum {
+    INDEX_DOC_CANDIDATES_BY_MODE = 0,
+    INDEX_DOC_CANDIDATES_ON,
+    INDEX_DOC_CANDIDATES_OFF,
+} index_doc_candidates_t;
+
+static index_doc_candidates_t index_doc_candidates_choice(cbm_mcp_server_t *srv, const char *args) {
     yyjson_doc *doc = args ? yyjson_read(args, strlen(args), 0) : NULL;
     yyjson_val *val = doc ? yyjson_obj_get(yyjson_doc_get_root(doc), "doc_candidates") : NULL;
     bool explicit_value = val && yyjson_is_bool(val);
-    bool enabled = explicit_value ? yyjson_get_bool(val) : true;
+    bool enabled = explicit_value && yyjson_get_bool(val);
     yyjson_doc_free(doc);
-    if (!explicit_value && srv && srv->config) {
-        enabled = cbm_config_get_bool(srv->config, CBM_CONFIG_DOC_CANDIDATES, true);
+    if (!explicit_value) {
+        explicit_value =
+            cbm_config_get_bool_set(srv ? srv->config : NULL, CBM_CONFIG_DOC_CANDIDATES, &enabled);
+    }
+    if (!explicit_value) {
+        return INDEX_DOC_CANDIDATES_BY_MODE;
+    }
+    return enabled ? INDEX_DOC_CANDIDATES_ON : INDEX_DOC_CANDIDATES_OFF;
+}
+
+/* An explicit choice is set on the pipeline; unset leaves the mode default. */
+static void index_doc_candidates_apply(cbm_pipeline_t *p, index_doc_candidates_t choice) {
+    if (choice != INDEX_DOC_CANDIDATES_BY_MODE) {
+        cbm_pipeline_set_doc_candidates_enabled(p, choice == INDEX_DOC_CANDIDATES_ON);
     }
-    return enabled;
 }
 
 /* Preserve every index option while replacing all caller-supplied repo_path
  * keys with the one canonical path that was actually authorized. A non-empty
  * project_name likewise replaces any caller "name" (#2134: the project key the
  * parent resolved for this root travels to the daemon job / worker verbatim,
- * so lease key and written index cannot diverge). doc_candidates is replaced
- * by the value the parent resolved. */
+ * so lease key and written index cannot diverge). Every caller doc_candidates
+ * is replaced by the explicit value the parent resolved, or dropped when it
+ * is unset, so the worker's index mode decides. */
 static char *index_args_with_repo_path(const char *args, const char *canonical_repo_path,
                                        const char *project_name,
                                        const cbm_index_resource_policy_t *policy,
-                                       bool doc_candidates) {
+                                       index_doc_candidates_t doc_candidates) {
     if (!args || !canonical_repo_path || !policy) {
         return NULL;
     }
@@ -11906,7 +11937,9 @@ static char *index_args_with_repo_path(const char *args, const char *canonical_r
     if ((has_name && !yyjson_mut_obj_add_strcpy(copy, copy_root, "name", project_name)) ||
         !yyjson_mut_obj_add_strcpy(copy, copy_root, "repo_path", canonical_repo_path) ||
         !cbm_mcp_index_policy_add_to_args(copy, copy_root, policy) ||
-        !yyjson_mut_obj_add_bool(copy, copy_root, "doc_candidates", doc_candidates)) {
+        (doc_candidates != INDEX_DOC_CANDIDATES_BY_MODE &&
+         !yyjson_mut_obj_add_bool(copy, copy_root, "doc_candidates",
+                                  doc_candidates == INDEX_DOC_CANDIDATES_ON))) {
         yyjson_mut_doc_free(copy);
         return NULL;
     }
@@ -12272,7 +12305,7 @@ static char *handle_index_repository(cbm_mcp_server_t *srv, const char *args) {
         index_args_free(repo_path, mode_str, name_override);
         return cbm_mcp_text_result(policy_error, true);
     }
-    bool doc_candidates = index_doc_candidates_enabled(srv, args);
+    index_doc_candidates_t doc_candidates = index_doc_candidates_choice(srv, args);
 
     /* A daemon session delegates the one physical write to its shared job
      * registry only after path canonicalization and workspace authorization. */
@@ -12371,7 +12404,7 @@ static char *handle_index_repository(cbm_mcp_server_t *srv, const char *args) {
     free(name_override);
     cbm_pipeline_set_persistence(p, persistence);
     cbm_pipeline_set_resource_policy(p, &resource_policy);
-    cbm_pipeline_set_doc_candidates_enabled(p, doc_candidates);
+    index_doc_candidates_apply(p, doc_candidates);
 
     char *project_name = heap_strdup(cbm_pipeline_project_name(p));
 
@@ -20080,7 +20113,7 @@ static void *autoindex_thread(void *arg) {
         cbm_log_warn("autoindex.err", "msg", "pipeline_create_failed");
         return NULL;
     }
-    cbm_pipeline_set_doc_candidates_enabled(p, index_doc_candidates_enabled(srv, NULL));
+    index_doc_candidates_apply(p, index_doc_candidates_choice(srv, NULL));
 
     /* Block until any concurrent pipeline finishes */
     cbm_pipeline_lock();

src/mcp/mcp_internal.h

@@ -54,6 +54,12 @@ bool cbm_mcp_jsonrpc_response_prepend_notice(char **response_io, const char *not
 bool cbm_mcp_index_policy_add_to_args(yyjson_mut_doc *doc, yyjson_mut_val *root,
                                       const cbm_index_resource_policy_t *policy);
 
+/* Encode a doc_candidates setting the user set to a boolean on an internal
+ * worker request (the worker reads no config). Unset or unparseable adds no
+ * key, so the worker's index mode decides. False only when encoding fails. */
+bool cbm_mcp_index_doc_candidates_add_to_args(yyjson_mut_doc *doc, yyjson_mut_val *root,
+                                              struct cbm_config *config);
+
 enum { CBM_MCP_DEFAULT_AUTO_INDEX_LIMIT = 50000 };
 
 /* Count indexable files with the pipeline's native full-mode discovery policy,

src/pipeline/pass_semantic_edges.c

@@ -3184,8 +3184,16 @@ static void phase6c_doc_sections(cbm_pipeline_ctx_t *ctx, const cbm_sem_func_t *
 }
 
 int cbm_pipeline_pass_semantic_edges(cbm_pipeline_ctx_t *ctx) {
-    /* Controlled by pipeline mode (moderate/full), not env var */
-    cbm_log_info("pass.start", "pass", "semantic_edges");
+    /* Controlled by pipeline mode, not env var. Full and moderate run every
+     * phase. Fast mode has no SEMANTICALLY_RELATED edges: it runs the pass
+     * only for doc -> code candidates, doc-only -- phases 1-4 (the corpus and
+     * vectors phase 6c scores against) and 6c, never the LSH + scoring of
+     * 5-6 -- and not at all with doc candidates off. */
+    bool doc_only = ctx->mode == CBM_MODE_FAST;
+    if (doc_only && !cbm_pipeline_doc_candidates_enabled(ctx->pipeline)) {
+        return 0;
+    }
+    cbm_log_info("pass.start", "pass", "semantic_edges", "doc_only", doc_only ? "true" : "false");
 
     cbm_gbuf_t *gbuf = ctx->gbuf;
     cbm_sem_config_t cfg = cbm_sem_get_config();
@@ -3254,22 +3262,25 @@ int cbm_pipeline_pass_semantic_edges(cbm_pipeline_ctx_t *ctx) {
 
     cbm_log_info("pass.semantic.vectors_stored", "count", itoa_log(func_count));
 
-    /* Phase 5: LSH hyperplanes → signatures → buckets. */
-    CBM_PROF_START(t_phase5);
     uint64_t *signatures = NULL;
     sem_bucket_t **band_buckets = NULL;
-    phase5_lsh_build(funcs, func_count, worker_count, &signatures, &band_buckets);
-    CBM_PROF_END_N("semantic_edges", "5_lsh_build", t_phase5, func_count);
+    int total_edges = 0;
+    if (!doc_only) {
+        /* Phase 5: LSH hyperplanes → signatures → buckets. */
+        CBM_PROF_START(t_phase5);
+        phase5_lsh_build(funcs, func_count, worker_count, &signatures, &band_buckets);
+        CBM_PROF_END_N("semantic_edges", "5_lsh_build", t_phase5, func_count);
 
-    cbm_log_info("pass.semantic.lsh_built", "functions", itoa_log(func_count), "bands",
-                 itoa_log(SEM_LSH_BANDS));
-    sem_mem_mark("5_lsh");
+        cbm_log_info("pass.semantic.lsh_built", "functions", itoa_log(func_count), "bands",
+                     itoa_log(SEM_LSH_BANDS));
+        sem_mem_mark("5_lsh");
 
-    /* Phase 6: Parallel scoring + sequential edge merge. */
-    int total_edges =
-        run_scoring_phase(gbuf, funcs, signatures, band_buckets, cfg, func_count, worker_count);
+        /* Phase 6: Parallel scoring + sequential edge merge. */
+        total_edges =
+            run_scoring_phase(gbuf, funcs, signatures, band_buckets, cfg, func_count, worker_count);
 
-    sem_mem_mark("6_score");
+        sem_mem_mark("6_score");
+    }
 
     /* Phase 6c: doc sections -> function candidates (doc_link_candidates). */
     phase6c_doc_sections(ctx, funcs, func_count, corpus, worker_count);