@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/release/sync-plugin-versions.js

@@ -15,6 +15,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { REPO_ROOT } = require('../helper/repo-root.js');
+const { contentDigest } = require('../runtime/packages/digest.js');
 
 /** Every distribution manifest that repeats the release version, relative to the repo root. */
 const PLUGIN_MANIFESTS = [
@@ -23,15 +24,50 @@ const PLUGIN_MANIFESTS = [
   'core/.plugin/plugin.json',
 ];
 
+/** The point registry that lists the bundled first-party packages (122 IC-015), relative to the repo root. */
+const POINTS_FILE = 'core/registry/contribution-points.json';
+
+/**
+ * 122 PN-8: a bundled package's manifest repeats the release version (`version`, and `doflow` as the exact range
+ * `=<version>`), and its directory's content digest is pinned in `contribution-points.json`. A bump changes the
+ * manifest bytes, so the three move together: rewrite the manifest, hash the directory, pin the digest. Returns the
+ * files it rewrote. Targeted replacement keeps the formatting of both files.
+ */
+function syncBundledPackages(version        , repoRoot        , fsImpl     )           {
+  const pointsFile = path.join(repoRoot, POINTS_FILE);
+  let pointsText = fsImpl.readFileSync(pointsFile, 'utf8');
+  const points = JSON.parse(pointsText);
+  const rewritten           = [];
+  for (const entry of points.bundled) {
+    const manifestRel = path.posix.join(entry.dir, 'doflow-package.json');
+    const manifestFile = path.join(repoRoot, manifestRel);
+    const text = fsImpl.readFileSync(manifestFile, 'utf8');
+    const next = text
+      .replace(/("version":\s*")[^"]*"/, (_m        , head        ) => `${head}${version}"`)
+      .replace(/("doflow":\s*")[^"]*"/, (_m        , head        ) => `${head}=${version}"`);
+    if (next !== text) {
+      fsImpl.writeFileSync(manifestFile, next, 'utf8');
+      rewritten.push(manifestRel);
+    }
+    const digest = contentDigest(path.join(repoRoot, entry.dir), { limits: points.limits, fsImpl });
+    if (digest !== entry.contentDigest) {
+      pointsText = pointsText.replace(entry.contentDigest, digest);
+      rewritten.push(POINTS_FILE);
+    }
+  }
+  if (rewritten.includes(POINTS_FILE)) fsImpl.writeFileSync(pointsFile, pointsText, 'utf8');
+  return [...new Set(rewritten)];
+}
+
 /**
  * Rewrites each plugin manifest's version to package.json's, preserving formatting by targeted
- * string replacement rather than re-serializing the whole file.
+ * string replacement rather than re-serializing the whole file. The bundled packages follow (`bundled`).
  * @param {Object} [options]
  * @param {string} [options.repoRoot]
  * @param {Object} [options.fsImpl]
- * @returns {{version: string, updated: Array<string>, unchanged: Array<string>}}
+ * @returns {{version: string, updated: Array<string>, unchanged: Array<string>, bundled: Array<string>}}
  */
-function syncPluginVersions({ repoRoot = REPO_ROOT, fsImpl = fs }                                      = {})                                                              {
+function syncPluginVersions({ repoRoot = REPO_ROOT, fsImpl = fs }                                      = {})                                                                                 {
   const pkg = JSON.parse(fsImpl.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
   if (typeof pkg.version !== 'string' || pkg.version.trim() === '') {
     throw new Error('package.json declares no version to project');
@@ -54,13 +90,13 @@ function syncPluginVersions({ repoRoot = REPO_ROOT, fsImpl = fs }
     fsImpl.writeFileSync(file, next, 'utf8');
     updated.push(rel);
   }
-  return { version: pkg.version, updated, unchanged };
+  return { version: pkg.version, updated, unchanged, bundled: syncBundledPackages(pkg.version, repoRoot, fsImpl) };
 }
 
 if (require.main === module) {
   const result = syncPluginVersions();
-  for (const rel of result.updated) console.log(`synced ${rel} -> ${result.version}`);
-  if (result.updated.length === 0) console.log(`all plugin manifests already at ${result.version}`);
+  for (const rel of [...result.updated, ...result.bundled]) console.log(`synced ${rel} -> ${result.version}`);
+  if (result.updated.length === 0 && result.bundled.length === 0) console.log(`all plugin manifests and bundled packages already at ${result.version}`);
 }
 
-module.exports = { syncPluginVersions, PLUGIN_MANIFESTS };
+module.exports = { syncPluginVersions, PLUGIN_MANIFESTS, POINTS_FILE };

package/src/runtime/advice/bench-gate.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// The bench bar that act mode requires. User decision D3 (2026-10-26): act is unreachable in 084. The bar may only be
+// met by a DoFlow-owned scored bench corpus, none ships yet, and a file in the caller's project is never read, so the
+// bar is always unmet. Producing that corpus is the future row "trusted bench scores" (not yet registered).
+
+                          
+               
+                
+                  
+                 
+ 
+
+function evaluateBenchBar(kind        , model        )                 {
+  return {
+    kind,
+    model,
+    passed: false,
+    reason: `no trusted bench scores ship for kind '${kind}' and model '${model}'`,
+  };
+}
+
+module.exports = {
+  evaluateBenchBar,
+};

package/src/runtime/advice/cli.js

@@ -9,11 +9,14 @@ const { REPO_ROOT } = require('../../helper/repo-root.js');
 const { loadAdviceRegistry } = require('./registry.js');
 const { loadStorageRegistry } = require('../storage/registry.js');
 const { resolveRoots } = require('../storage/roots.js');
-const { resolveSetting, writeSetting } = require('./config.js');
+const { resolveSetting } = require('./config.js');
+const { loadSettings } = require('../settings/resolve.js');
+const { writeLayer } = require('../settings/write.js');
 const { createAdviceClient } = require('./client.js');
 const { materializeKind, validateQuestionSet, validateStaticAnswer } = require('./kinds.js');
 const { findPick, appendOutcome } = require('./record.js');
 const { strengthWords } = require('./strength.js');
+const { projectLayerSource } = require('../settings/project-layers.js');
 
 function loadSources(repoRoot     ) {
   const read = (name     ) => JSON.parse(fs.readFileSync(path.join(repoRoot, 'core/registry', name), 'utf8'));
@@ -28,11 +31,39 @@ function loadRuntime({ projectRoot, global = false }      = {}) {
   const advice = loadAdviceRegistry({ repoRoot: REPO_ROOT });
   const storage = loadStorageRegistry({ repoRoot: REPO_ROOT });
   const roots = resolveRoots({ registry: storage, projectRoot, global });
+  const projectLayers = projectLayerSource(projectRoot);
   const sources = loadSources(REPO_ROOT);
   const adviceRegistry = advice.ok ? advice.registry : null;
-  return { adviceRegistry, adviceError: advice.ok ? null : advice.detail, storage, roots, sources };
+  return { adviceRegistry, adviceError: advice.ok ? null : advice.detail, storage, roots, sources, projectLayers };
 }
 
+function emitDeprecatedNotes(runtime     , loadSettingsImpl      = loadSettings)       {
+  emitDeprecatedNotesByCode(runtime, loadSettingsImpl);
+}
+
+function emitDeprecatedNotesByCode(runtime     , loadSettingsImpl      = loadSettings)       {
+  if (!runtime.adviceRegistry) return;
+  const roots = runtime.roots || {};
+  const projectRoot = roots['project-doflow'] ? path.dirname(roots['project-doflow']) : null;
+
+  try {
+    const view = loadSettingsImpl({ projectRoot, fsImpl: fs });
+    const enabled = view.get('advice.enabled', 'global');
+    const canReadProject = enabled.value === true && enabled.state === 'ok' && enabled.origin.via === null;
+    for (const note of view.notes || []) {
+      if (note.code !== 'deprecated') continue;
+      const sourceLayer = view.files.find((file     ) => file.path === note.source)?.layer;
+      if (!note.key || !['user', 'project'].includes(sourceLayer)) continue;
+      if (sourceLayer === 'project' && !canReadProject) continue;
+      let resolution;
+      try { resolution = view.get(note.key, sourceLayer === 'user' ? 'global' : 'project'); } catch { continue; }
+      if (!resolution.origin.legacy || resolution.origin.source !== note.source) continue;
+      console.error('note: ' + note.text);
+    }
+  } catch {
+    // Advice remains usable when legacy-source reporting fails.
+  }
+}
 function emitResult(result     , { json, kind }     ) {
   if (result.reason === 'over-limit') {
     return usageError('advise', result.detail || 'request exceeds an advice limit', json);
@@ -141,7 +172,7 @@ function writeFailure(message     , json     ) {
 }
 
 async function handleConfigure(options     , runtime     ) {
-  const { adviceRegistry, adviceError, roots, sources } = runtime;
+  const { adviceRegistry, adviceError, roots, sources, projectLayers } = runtime;
   const { json, project, global, force } = options;
   const hasModel = typeof options.model === 'string' && options.model.length > 0;
   const hasOff = options.off === true;
@@ -152,17 +183,28 @@ async function handleConfigure(options     , runtime     ) {
   if (project && (global || !options.projectRoot)) return usageError('advise', '--project requires a project root', json);
   if (adviceError || !adviceRegistry) return writeFailure(`advice registry is invalid: ${adviceError || 'missing registry'}`, json);
 
+  if (!project && !roots['config-home']) return usageError('advise', 'no config home resolves; set an absolute HOME or XDG_CONFIG_HOME, or use --project', json);
+  emitDeprecatedNotes(runtime);
+
   const file = project
-    ? path.join(roots['project-doflow'], 'decision-model.json')
-    : path.join(roots['config-home'], 'decision-model.json');
+    ? path.join(projectLayers.layersFrom || roots['project-doflow'], 'settings.json')
+    : path.join(roots['config-home'], 'settings.json');
   const fsImpl = fs;
+  const inheritedFromMain = !!project && projectLayers.checkout === 'main';
+  const discloseWrite = (setting     ) => {
+    const result      = { written: file, setting };
+    if (inheritedFromMain) result.inheritedFromMainCheckout = true;
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else if (inheritedFromMain) console.log(`(inherited from the main checkout)`);
+  };
   if (hasOff) {
-    const setting = project ? { schema: 1, enabled: false } : { schema: 1, enabled: false };
-    const written = writeSetting({ file, level: project ? 'project' : 'user', setting, force, fsImpl });
+    const written = writeLayer({ file, set: { 'advice.enabled': false }, force, fsImpl });
     if (!written.ok) return writeFailure(written.detail, json);
     const effective = resolveSetting({ adviceRegistry, roots, fsImpl });
-    if (json) console.log(JSON.stringify({ written: file, setting: effective }, null, 2));
-    else console.log(project ? `Decision model for this project: off (wrote ${file}).` : `Decision model off (wrote ${file}).`);
+    if (json) discloseWrite(effective);
+    else console.log(project
+      ? `Decision model for this project: off (wrote ${file}${inheritedFromMain ? ' (inherited from the main checkout)' : ''}).`
+      : `Decision model off (wrote ${file}).`);
     return finishRuntime(0);
   }
 
@@ -172,7 +214,7 @@ async function handleConfigure(options     , runtime     ) {
   if (project && userSetting.state !== 'on') {
     return writeFailure('turn the decision model on at user level first; a project cannot enable it', json);
   }
-  const providerId = userSetting.provider || 'ollama';
+  const providerId = userSetting.provider ?? loadSettings({ global: true }).get('advice.provider', 'global').value;
   const provider = adviceRegistry.providers.find((entry     ) => entry.id === providerId);
   if (!provider) return writeFailure(`provider '${providerId}' is not in core/registry/advice.json`, json);
   const endpoint = project
@@ -185,14 +227,14 @@ async function handleConfigure(options     , runtime     ) {
   if (failure) return writeFailure(failure, json);
 
   const setting = project
-    ? { schema: 1, model: options.model }
-    : { schema: 1, enabled: true, provider: provider.id, endpoint, model: options.model };
-  const written = writeSetting({ file, level: project ? 'project' : 'user', setting, force, fsImpl });
+    ? { 'advice.model': options.model }
+    : { 'advice.enabled': true, 'advice.provider': provider.id, 'advice.endpoint': endpoint, 'advice.model': options.model };
+  const written = writeLayer({ file, set: setting, force, fsImpl });
   if (!written.ok) return writeFailure(written.detail, json);
   const effective = resolveSetting({ adviceRegistry, roots, fsImpl });
-  if (json) console.log(JSON.stringify({ written: file, setting: effective }, null, 2));
+  if (json) discloseWrite(effective);
   else console.log(project
-    ? `Decision model for this project: ${options.model} (wrote ${file}).`
+    ? `Decision model for this project: ${options.model} (wrote ${file}${inheritedFromMain ? ' (inherited from the main checkout)' : ''}).`
     : `Decision model on: ${options.model} at ${endpoint} (wrote ${file}).`);
   return finishRuntime(0);
 }
@@ -274,10 +316,11 @@ async function handleAdviseCommand(options      = {}) {
     const shaped = { ...options, projectRoot };
     if (action === 'configure') return await handleConfigure(shaped, runtime);
     if (action === 'outcome') return handleOutcome(shaped, runtime);
+    emitDeprecatedNotes(runtime);
     return await handleAsk(shaped, runtime);
   } catch (error     ) {
     return writeFailure(error?.message || 'advice command failed', options.json);
   }
 }
 
-module.exports = { handleAdviseCommand };
+module.exports = { handleAdviseCommand, emitDeprecatedNotes };

package/src/runtime/advice/client.js

@@ -6,6 +6,7 @@ const fs = require('node:fs');
 const http = require('node:http');
 const https = require('node:https');
 const { resolveSetting } = require('./config.js');
+const { loadSettings } = require('../settings/resolve.js');
 const { checkEndpoint } = require('./endpoint-guard.js');
 const { strengthOf } = require('./strength.js');
 const { validateQuestionSet, validateStaticAnswer } = require('./kinds.js');
@@ -41,7 +42,14 @@ function networkReason(error     ) {
     ? 'timeout' : 'unreachable';
 }
 
-function requestAction({ endpoint, action, pinnedLookup, timeoutMs, httpModule = http, httpsModule = https }     ) {
+function timeoutError(message        ) {
+  const error      = new Error(message);
+  error.code = 'ADVICE_TIMEOUT';
+  return error;
+}
+
+/** `signal`, when given, aborts the request the way its own timeout does: the request is destroyed and the timer cleared. */
+function requestAction({ endpoint, action, pinnedLookup, timeoutMs, signal, httpModule = http, httpsModule = https }     ) {
   return new Promise     ((resolve, reject) => {
     let request     ;
     let settled = false;
@@ -49,15 +57,18 @@ function requestAction({ endpoint, action, pinnedLookup, timeoutMs, httpModule =
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      signal?.removeEventListener?.('abort', onAbort);
       if (error) reject(error);
       else resolve(response);
     };
-    const timer = setTimeout(() => {
-      const error      = new Error(`decision model request timed out after ${timeoutMs}ms`);
-      error.code = 'ADVICE_TIMEOUT';
+    const stop = (error     ) => {
       request?.destroy(error);
       finish(error);
-    }, timeoutMs);
+    };
+    const onAbort = () => stop(timeoutError('decision model request aborted by the caller'));
+    const timer = setTimeout(() => stop(timeoutError(`decision model request timed out after ${timeoutMs}ms`)), timeoutMs);
+    if (signal?.aborted) { onAbort(); return; }
+    signal?.addEventListener?.('abort', onAbort, { once: true });
 
     try {
       const url = new URL(endpoint);
@@ -117,7 +128,11 @@ function createAdviceClient({
   httpsModule = https,
   clock = () => new Date(),
 }      = {}) {
-  async function ask({ questionSet, kind, staticAnswer, caller, taskId = null, record = true }      = {}) {
+  /**
+   * `model`, when given, replaces the setting's model for this call: it is the model asked, recorded and reported.
+   * `signal`, when given, ends the call early: an in-flight request is destroyed and the call is unavailable with 'timeout'.
+   */
+  async function ask({ questionSet, kind, staticAnswer, caller, taskId = null, record = true, model, signal }      = {}) {
     const startedAt = Date.now();
     let setting      = null;
     const effectiveKind = typeof kind === 'string' && kind ? kind : 'adhoc';
@@ -137,6 +152,7 @@ function createAdviceClient({
       if (setting.state !== 'on') {
         return emptyAdviceResult('off', setting.reason, setting.notes?.[0] || null, setting, durationSince(startedAt));
       }
+      if (typeof model === 'string' && model.trim()) setting = { ...setting, model: model.trim() };
 
       const provider = adviceRegistry?.providers?.find((entry     ) => entry.id === setting.provider);
       const adapter = provider && ADAPTERS[provider.adapter];
@@ -166,14 +182,17 @@ function createAdviceClient({
         return unavailable('over-limit', `request body is ${bodyBytes} bytes; the limit is ${adviceRegistry.limits.maxBodyBytes} (core/registry/advice.json limits.maxBodyBytes)`);
       }
 
+      if (signal?.aborted) return unavailable('timeout', 'decision model request aborted by the caller');
       const endpointCheck = await checkEndpoint(setting.endpoint, {
         lookup,
         file: setting.decidedBy?.user || 'provider default',
         timeoutMs: Math.max(0, adviceRegistry.timeoutMs - durationSince(startedAt)),
+        signal,
       });
       if (!endpointCheck.ok) return unavailable(endpointCheck.reason || 'non-loopback', endpointCheck.message);
       const remainingMs = adviceRegistry.timeoutMs - durationSince(startedAt);
       if (remainingMs <= 0) return unavailable('timeout', 'decision model request budget exhausted');
+      if (signal?.aborted) return unavailable('timeout', 'decision model request aborted by the caller');
 
       let response;
       try {
@@ -182,6 +201,7 @@ function createAdviceClient({
           action: request,
           pinnedLookup: endpointCheck.pinnedLookup,
           timeoutMs: remainingMs,
+          signal,
           httpModule,
           httpsModule,
         });
@@ -242,16 +262,19 @@ function createAdviceClient({
     }
   }
 
-  async function inspect({ endpoint, model, provider: providerId = 'ollama', file, minVersion, timeoutMs }      = {}) {
+  async function inspect({ endpoint, model, provider: providerId, file, minVersion, timeoutMs }      = {}) {
     const unavailable = (state     , message     , version      = null, versionOk = false) => ({
       endpoint: { state, version, versionOk, message: message ?? null },
       models: [],
       model: { installed: false, decisionCapable: false },
     });
     try {
-      const provider = adviceRegistry?.providers?.find((entry     ) => entry.id === providerId);
+      const effectiveProviderId = providerId
+        ?? resolveSetting({ adviceRegistry, roots, fsImpl }).provider
+        ?? loadSettings({ global: true, env: {}, fsImpl }).get('advice.provider', 'global').value;
+      const provider = adviceRegistry?.providers?.find((entry     ) => entry.id === effectiveProviderId);
       const adapter = provider && ADAPTERS[provider.adapter];
-      if (!provider || !adapter) return unavailable('refused', `provider '${providerId}' is unavailable`);
+      if (!provider || !adapter) return unavailable('refused', `provider '${effectiveProviderId}' is unavailable`);
       const probeLimit = Number.isFinite(timeoutMs) ? timeoutMs : adviceRegistry.probeTimeoutMs;
       const budgetMs = Number.isFinite(adviceRegistry.doctorBudgetMs) ? adviceRegistry.doctorBudgetMs : probeLimit * 4;
       const startedAt = Date.now();

package/src/runtime/advice/config.js

@@ -5,14 +5,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { resolveRoots } = require('../storage/roots.js');
-
-const SETTING_FILE = 'decision-model.json';
-const PROJECT_NOTE = 'a project cannot enable the decision model or choose its endpoint';
-const KNOWN_KEYS = new Set(['schema', 'enabled', 'provider', 'endpoint', 'model']);
-
-function isObject(value     )          {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
+const { loadSettings } = require('../settings/resolve.js');
 
 function offResult(reason        , decidedBy     , notes           = [], setting      = {})      {
   return {
@@ -26,65 +19,58 @@ function offResult(reason        , decidedBy     , notes           = [], setting
   };
 }
 
-function readJson(file               , fsImpl     )                                                {
-  if (!file) return { exists: false };
-  try {
-    return { exists: true, value: JSON.parse(fsImpl.readFileSync(file, 'utf8')) };
-  } catch (error     ) {
-    if (error?.code === 'ENOENT') return { exists: false };
-    return { exists: true, error };
-  }
+function projectLayer(layer        )          {
+  return layer === 'project' || layer === 'local';
 }
 
-function parseUserSetting(value     , adviceRegistry     )      {
-  if (!isObject(value)) return { error: 'user setting must be a JSON object' };
-  if (value.schema !== 1) return { error: 'user setting schema must be 1' };
-  if (typeof value.enabled !== 'boolean') return { error: 'user setting enabled must be a boolean' };
-
-  const providers = Array.isArray(adviceRegistry?.providers) ? adviceRegistry.providers : [];
-  const providerId = value.provider === undefined ? 'ollama' : value.provider;
-  const provider = providers.find((item     ) => item?.id === providerId);
-  if (typeof providerId !== 'string' || !provider) return { error: `user setting provider '${providerId}' is not in advice.json providers` };
-
-  let endpoint = provider.defaultEndpoint;
-  if (value.endpoint !== undefined) {
-    if (typeof value.endpoint !== 'string' || !value.endpoint.trim()) return { error: 'user setting endpoint must be a URL string' };
-    try { new URL(value.endpoint); } catch { return { error: 'user setting endpoint must be a URL string' }; }
-    endpoint = value.endpoint;
-  }
-  if (typeof endpoint !== 'string' || !endpoint) return { error: `providers.${providerId}.defaultEndpoint is missing` };
-
-  if (value.model !== undefined && (typeof value.model !== 'string' || !value.model.trim())) {
-    return { error: 'user setting model must be a non-empty string' };
+function errorNote(error     , offBy                = null)         {
+  if (error.legacy && error.layer === 'user') {
+    if (error.code === 'unreadable' || error.code === 'not-file'
+      || (error.code === 'unparseable' && error.reason.startsWith('not valid JSON'))) {
+      return `user setting at ${error.source} could not be read: ${error.reason}`;
+    }
+    return `${error.reason} (${error.source})`;
   }
-  if (value.enabled && (typeof value.model !== 'string' || !value.model.trim())) {
-    return { error: 'user setting model is required when enabled is true' };
+  if (projectLayer(error.layer)) {
+    if (offBy && error.source === offBy) return `project setting at ${error.source} is invalid: ${error.reason}; advice is off`;
+    return `project setting at ${error.source} ignored: ${error.reason}`;
   }
+  return `user setting at ${error.source} is invalid${error.key ? ` for '${error.key}'` : ''}: ${error.reason}`;
+}
 
-  const notes = Object.keys(value)
-    .filter((key) => !KNOWN_KEYS.has(key))
-    .map((key) => `unknown user key '${key}' ignored`);
-  return {
-    value: { enabled: value.enabled, provider: providerId, endpoint, model: value.model ?? null },
-    notes,
-  };
+function settingNotes(view     , includeProject         , includeDeprecated = false, offBy                = null)           {
+  const notes = view.notes
+    .filter((note     ) => {
+      if (note.code !== 'deprecated' || !includeDeprecated) return note.code !== 'deprecated';
+      const sourceLayer = view.files.find((file     ) => file.path === note.source)?.layer;
+      if (!note.key || !['user', 'project'].includes(sourceLayer)) return false;
+      const resolution = view.get(note.key, sourceLayer === 'user' ? 'global' : 'project');
+      return resolution.origin.legacy && resolution.origin.source === note.source;
+    })
+    .filter((note     ) => includeProject || !projectLayer(view.files.find((file     ) => file.path === note.source)?.layer))
+    .map((note     ) => note.text);
+  const seen = new Set        ();
+  for (const error of view.errors) {
+    if (!includeProject && projectLayer(error.layer)) continue;
+    const key = error.legacy
+      ? `${error.layer}\0${error.source}`
+      : `${error.layer}\0${error.source}\0${error.key}\0${error.code}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    notes.push(errorNote(error, offBy));
+  }
+  return notes;
 }
 
-function parseProjectSetting(value     )      {
-  if (!isObject(value)) return { error: 'project setting must be a JSON object' };
-  if (value.schema !== 1) return { error: 'project setting schema must be 1' };
-  if (value.enabled !== undefined && typeof value.enabled !== 'boolean') return { error: 'project setting enabled must be a boolean' };
-  if (value.model !== undefined && (typeof value.model !== 'string' || !value.model.trim())) return { error: 'project setting model must be a non-empty string' };
+function modelSource(setting     )                {
+  if (setting.value === null || setting.value === undefined) return null;
+  if (setting.origin.layer === 'user') return 'user';
+  return projectLayer(setting.origin.layer) ? 'project' : null;
+}
 
-  const notes           = [];
-  if (value.enabled === true) notes.push(`project key 'enabled' ignored: ${PROJECT_NOTE}`);
-  for (const key of ['endpoint', 'provider']) {
-    if (Object.hasOwn(value, key)) notes.push(`project key '${key}' ignored: ${PROJECT_NOTE}`);
-  }
-  for (const key of Object.keys(value)) {
-    if (!['schema', 'enabled', 'model', 'endpoint', 'provider'].includes(key)) notes.push(`unknown project key '${key}' ignored`);
-  }
-  return { value: { disabled: value.enabled === false, model: value.model ?? null }, notes };
+function decidedSource(setting     , layer                    )                {
+  if (layer === 'user') return setting.origin.layer === 'user' ? setting.origin.source : null;
+  return projectLayer(setting.origin.layer) ? setting.origin.source : null;
 }
 
 function resolveSetting({
@@ -95,95 +81,74 @@ function resolveSetting({
   global = false,
   env = process.env,
   fsImpl = fs,
+  includeDeprecated = false,
 }      = {})      {
-  const notes           = [];
   let resolvedRoots = roots;
   try {
     if (!resolvedRoots) resolvedRoots = resolveRoots({ registry: storageRegistry, projectRoot, global, env });
   } catch (error     ) {
     return offResult('config-invalid', { user: null, project: null }, [`storage roots could not be resolved: ${error.message}`]);
   }
-  const userFile = resolvedRoots?.['config-home'] ? path.join(resolvedRoots['config-home'], SETTING_FILE) : null;
-  const projectFile = resolvedRoots?.['project-doflow'] ? path.join(resolvedRoots['project-doflow'], SETTING_FILE) : null;
-  const decidedBy = { user: null, project: null };
-  const userRead = readJson(userFile, fsImpl);
-  if (!userRead.exists) return offResult('not-configured', decidedBy, notes);
-  if (userRead.error) {
-    return offResult('config-invalid', { user: userFile, project: null }, [`user setting at ${userFile} could not be read: ${userRead.error.message}`]);
+  const resolverEnv = { ...env };
+  if (resolvedRoots?.['config-home']) {
+    resolverEnv.XDG_CONFIG_HOME = path.dirname(resolvedRoots['config-home']);
+  } else {
+    delete resolverEnv.XDG_CONFIG_HOME;
+    delete resolverEnv.HOME;
   }
-  const user = parseUserSetting(userRead.value, adviceRegistry);
-  if (user.error) return offResult('config-invalid', { user: userFile, project: null }, [`${user.error} (${userFile})`]);
-  decidedBy.user = userFile;
-  notes.push(...user.notes);
-
-  const base = { ...user.value, modelFrom: user.value.model ? 'user' : null };
-  if (!user.value.enabled) return offResult('user-disabled', decidedBy, notes, base);
+  const resolverProjectRoot = !global && resolvedRoots?.['project-doflow']
+    ? path.dirname(resolvedRoots['project-doflow'])
+    : null;
 
-  const projectRead = readJson(projectFile, fsImpl);
-  if (projectRead.exists) {
-    if (projectRead.error) {
-      notes.push(`project setting at ${projectFile} ignored: ${projectRead.error.message}`);
-    } else {
-      const project = parseProjectSetting(projectRead.value);
-      if (project.error) {
-        notes.push(`project setting at ${projectFile} ignored: ${project.error}`);
-      } else {
-        notes.push(...project.notes);
-        if (project.value.disabled) {
-          decidedBy.project = projectFile;
-          return offResult('project-disabled', decidedBy, notes, base);
-        }
-        if (project.value.model) {
-          decidedBy.project = projectFile;
-          return {
-            state: 'on', reason: null, provider: base.provider, endpoint: base.endpoint,
-            model: project.value.model, decidedBy, modelFrom: 'project', notes,
-          };
-        }
-      }
+  let view     ;
+  try {
+    view = loadSettings({ projectRoot: resolverProjectRoot, global, env: resolverEnv, fsImpl });
+    const enabledGlobal = view.get('advice.enabled', 'global');
+    const canReadProject = !global && enabledGlobal.value === true
+      && enabledGlobal.state === 'ok' && enabledGlobal.origin.via === null;
+    const enabled = canReadProject ? view.get('advice.enabled', 'project') : enabledGlobal;
+    const provider = view.get('advice.provider', 'global');
+    const endpoint = view.get('advice.endpoint', 'global');
+    const modelGlobal = view.get('advice.model', 'global');
+    const model = canReadProject && enabled.value === true ? view.get('advice.model', 'project') : modelGlobal;
+    const decidedBy = {
+      user: decidedSource(enabledGlobal, 'user'),
+      project: decidedSource(enabled, 'project') || decidedSource(model, 'project'),
+    };
+    let reason                = null;
+    if (enabled.state === 'invalid' || enabled.origin.via === 'fail-safe' || enabled.origin.via === 'cross-key') {
+      reason = 'config-invalid';
+    } else if (enabled.value !== true) {
+      if (enabled.origin.layer === 'default' || enabled.origin.via === 'no-config-home') reason = 'not-configured';
+      else if (projectLayer(enabled.origin.layer)) reason = 'project-disabled';
+      else reason = 'user-disabled';
     }
-  }
-  return {
-    state: 'on', reason: null, provider: base.provider, endpoint: base.endpoint,
-    model: base.model, decidedBy, modelFrom: base.modelFrom, notes,
-  };
-}
 
-function writeSetting({ file, setting, level = 'user', force = false, fsImpl = fs }      = {})      {
-  if (typeof file !== 'string' || !file || !isObject(setting)) {
-    return { ok: false, reason: 'config-invalid', detail: 'file and setting object are required' };
-  }
-  const directory = path.dirname(file);
-  let existing      = {};
-  try {
-    if (fsImpl.existsSync(file)) {
-      try {
-        const parsed = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
-        if (!isObject(parsed)) throw new Error('setting must be a JSON object');
-        existing = parsed;
-      } catch (error     ) {
-        if (!force) return { ok: false, reason: 'config-invalid', detail: `${file}: ${error.message}` };
-      }
+    // A project file that turned advice off (fail-safe, reason config-invalid) is not "ignored": say advice is off.
+    const notes = settingNotes(view, canReadProject, includeDeprecated, reason === 'config-invalid' ? decidedBy.project : null);
+    if (reason === 'not-configured') return offResult(reason, decidedBy, notes);
+    if (reason === 'config-invalid' && (enabledGlobal.state === 'invalid'
+      || enabledGlobal.origin.via === 'fail-safe' || enabledGlobal.origin.via === 'cross-key')) {
+      return offResult(reason, decidedBy, notes);
     }
 
-    const preserved = Object.fromEntries(Object.entries(existing).filter(([key]) => !KNOWN_KEYS.has(key)));
-    const retainedUserFields = level === 'user' && setting.enabled === false
-      ? Object.fromEntries(['provider', 'endpoint', 'model'].filter((key) => existing[key] !== undefined).map((key) => [key, existing[key]]))
-      : {};
-    const output = { ...preserved, ...retainedUserFields, ...setting };
-    fsImpl.mkdirSync(directory, { recursive: true });
-    const suffix = `${Date.now()}-${Math.random().toString(16).slice(2)}`;
-    const temporary = path.join(directory, `.${path.basename(file)}.${suffix}.tmp`);
-    try {
-      fsImpl.writeFileSync(temporary, `${JSON.stringify(output, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
-      fsImpl.renameSync(temporary, file);
-    } finally {
-      try { if (fsImpl.existsSync(temporary)) fsImpl.unlinkSync(temporary); } catch { /* keep the primary result */ }
+    const effectiveModel = reason === 'config-invalid' ? modelGlobal : model;
+    const effectiveModelFrom = modelSource(effectiveModel);
+    if (reason) {
+      return offResult(reason, decidedBy, notes, {
+        provider: provider.value,
+        endpoint: endpoint.value,
+        model: effectiveModel.value,
+        modelFrom: effectiveModelFrom,
+      });
     }
-    return { ok: true, file, setting: output };
+    return {
+      state: 'on', reason: null, provider: provider.value, endpoint: endpoint.value,
+      model: effectiveModel.value, decidedBy, modelFrom: effectiveModelFrom, notes,
+    };
   } catch (error     ) {
-    return { ok: false, reason: 'config-invalid', detail: `${file}: ${error.message}` };
+    return offResult('config-invalid', { user: null, project: null }, [`settings resolver could not be loaded: ${error.message}`]);
   }
 }
 
-module.exports = { resolveSetting, writeSetting };
+module.exports = { resolveSetting };