@geraldmaron/construct 1.0.6 → 1.0.8

package/lib/provider-capabilities.js

@@ -117,23 +117,36 @@ export function resolveProviderCapabilitiesSync(modelId) {
 }
 
 /**
- * Probe provider for live capabilities (async).
- * Results are cached for 24h.
+ * Probe provider for capabilities and cache the result for 24h.
+ *
+ * Static path (probe=false): resolves capabilities from the adapter's static
+ * declaration. Live path (probe=true): dispatches to the adapter's optional
+ * `probe(modelId)` export — adapters that don't implement it fall back to the
+ * static declaration. Construct itself stays provider-agnostic; per-vendor
+ * probing is the adapter's responsibility.
  *
  * @param {string} modelId
  * @param {object} opts - { probe: boolean }
  * @returns {Promise<object>}
  */
 export async function probeProviderCapabilities(modelId, { probe = false } = {}) {
-  const caps = await resolveProviderCapabilities(modelId);
+  const adapterKey = resolveAdapterKey(modelId);
+  const loader = ADAPTERS[adapterKey] || ADAPTERS.generic;
 
+  let caps;
   if (probe) {
-    // TODO: implement live probing (API call) in Phase A follow-up
-    // For now, just return the static capabilities
+    try {
+      const mod = await loader();
+      caps = typeof mod.probe === 'function'
+        ? await mod.probe(modelId)
+        : mod.capabilities(modelId);
+    } catch {
+      caps = await resolveProviderCapabilities(modelId);
+    }
+  } else {
+    caps = await resolveProviderCapabilities(modelId);
   }
 
-  // Cache by adapter key
-  const adapterKey = resolveAdapterKey(modelId);
   const cache = getCache();
   cache[adapterKey] = caps;
   writeCapabilityCache(cache);

package/lib/providers/auth-manager.mjs

@@ -1,15 +1,23 @@
-// lib/providers/auth-manager.mjs
-// OAuth refresh and token lifecycle management
+/**
+ * lib/providers/auth-manager.mjs — Token lifecycle and refresh dispatch.
+ *
+ * Provider-agnostic store and contract for credential rotation. The actual
+ * refresh flow (OAuth, JWT, vendor-specific) lives in a registered adapter;
+ * dispatch goes to the adapter's `refresh(state)` and the result is persisted
+ * back to the auth store. Adapters lacking a refresh implementation leave the
+ * operator on a reauthenticate-manually path — the safe agnostic default.
+ */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { homedir } from 'node:os';
 
-const AUTH_DIR = path.join(homedir(), '.construct', 'auth');
-
-try {
-  fs.mkdirSync(AUTH_DIR, { recursive: true, mode: 0o700 });
-} catch { /* ignore */ }
+function authDir() {
+  const home = process.env.HOME || homedir();
+  const dir = path.join(home, '.construct', 'auth');
+  try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* ignore */ }
+  return dir;
+}
 
 const PROVIDER_CONFIGS = {
   github: {
@@ -28,9 +36,20 @@ const PROVIDER_CONFIGS = {
   },
 };
 
+const refreshAdapters = new Map();
+
+/**
+ * Register a refresh adapter for a provider. Contract:
+ *   adapter(state) -> Promise<{ success, token, refreshToken?, expiresAt? }>
+ * If no adapter is registered, refresh returns a manual-reauth instruction.
+ */
+export function registerRefreshAdapter(provider, adapter) {
+  if (typeof adapter === 'function') refreshAdapters.set(provider, adapter);
+}
+
 export function loadAuthState(provider) {
   try {
-    const file = path.join(AUTH_DIR, `${provider}.json`);
+    const file = path.join(authDir(), `${provider}.json`);
     if (fs.existsSync(file)) {
       return JSON.parse(fs.readFileSync(file, 'utf8'));
     }
@@ -40,7 +59,7 @@ export function loadAuthState(provider) {
 
 export function saveAuthState(provider, state) {
   try {
-    const file = path.join(AUTH_DIR, `${provider}.json`);
+    const file = path.join(authDir(), `${provider}.json`);
     fs.writeFileSync(file, JSON.stringify(state, null, 2), { mode: 0o600 });
     return true;
   } catch {
@@ -111,16 +130,38 @@ async function refreshToken(provider) {
   if (!config?.refreshable) {
     return { success: false, error: 'Provider does not support refresh' };
   }
-  
+
   const state = loadAuthState(provider);
   if (!state?.refreshToken) {
     return { success: false, error: 'No refresh token available' };
   }
-  
-  // Provider-specific refresh logic would go here
-  // For now, just indicate refresh is needed
-  return {
-    success: false,
-    error: 'Token refresh required - reauthenticate manually',
-  };
+
+  const adapter = refreshAdapters.get(provider);
+  if (!adapter) {
+    return {
+      success: false,
+      error: 'Token refresh required - reauthenticate manually',
+    };
+  }
+
+  try {
+    const result = await adapter(state);
+    if (result?.success && result.token) {
+      const next = {
+        ...state,
+        token: result.token,
+        refreshToken: result.refreshToken || state.refreshToken,
+        expiresAt: result.expiresAt || null,
+        rotatedAt: new Date().toISOString(),
+      };
+      saveAuthState(provider, next);
+      return { success: true, expiresAt: next.expiresAt };
+    }
+    return {
+      success: false,
+      error: result?.error || 'Refresh adapter returned no token',
+    };
+  } catch (err) {
+    return { success: false, error: `Refresh adapter threw: ${err.message}` };
+  }
 }

package/lib/providers/circuit-breaker.mjs

@@ -104,6 +104,20 @@ export function getBreaker(key, options) {
   return REGISTRY.get(key);
 }
 
+export function getState(providerName) {
+  const b = REGISTRY.get(providerName);
+  if (!b) return null;
+  return {
+    state: b.state.toUpperCase(),
+    failures: b.failureCount,
+    lastFailure: b.openedAt ? new Date(b.openedAt) : null,
+  };
+}
+
+export function reset(providerName) {
+  REGISTRY.get(providerName)?.reset();
+}
+
 export function describeBreakers() {
   return [...REGISTRY.values()].map((b) => ({
     key: b.key,

package/lib/providers/contract.mjs

@@ -3,7 +3,7 @@
  *
  * A provider integrates Construct with an external system that holds work
  * artefacts: GitHub repos, Jira projects, Confluence spaces, Slack channels,
- * Salesforce orgs, etc. Providers are stateless adapters — durable state
+ * Salesforce orgs, etc. Providers are stateless adapters; durable state
  * (cached search results, last-seen markers, observations distilled from
  * fetched items) lives in core stores, not in the provider.
  *
@@ -29,11 +29,75 @@
  *
  * `assertProviderContract(provider)` runs at registry load time and refuses
  * to accept providers that miss required fields or declare capabilities
- * they don't implement. The check is deliberately loose — providers can
- * extend the shape with extra methods — but it gates the load-bearing
+ * they don't implement. The check is deliberately loose; providers can
+ * extend the shape with extra methods; but it gates the load-bearing
  * fields so a typo in a plugin can't take down the registry.
+ *
+ * Scope validation: `ALLOWLIST_SCHEMA` declares the allowlist fields
+ * supported per provider. `validateAllowlist(providerName, target, config)`
+ * checks whether `target` (a repo name, channel ID, project key, etc.) is
+ * permitted by the caller's config. When no allowlist fields are set the
+ * call is allowed through; when any allowlist field is set the target must
+ * satisfy it.
+ *
+ * Glob matching for `*Glob` fields follows minimatch-style single-segment
+ * patterns where `*` matches any sequence of non-slash characters.
  */
 
+export const ALLOWLIST_SCHEMA = Object.freeze({
+  github:                 { fields: ['org', 'repoAllowlist', 'repoAllowGlob'] },
+  'atlassian-jira':       { fields: ['instance', 'projectAllowlist'] },
+  'atlassian-confluence': { fields: ['instance', 'spaceAllowlist'] },
+  slack:                  { fields: ['workspace', 'channelAllowlist'] },
+  salesforce:             { fields: ['instance', 'objectAllowlist'] },
+});
+
+function globMatch(pattern, value) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*');
+  return new RegExp(`^${escaped}$`).test(value);
+}
+
+export function validateAllowlist(providerName, target, config = {}) {
+  const schema = ALLOWLIST_SCHEMA[providerName];
+
+  // Unknown providers pass through; no schema means no restriction.
+  if (!schema) return { allowed: true, reason: 'no allowlist schema for provider' };
+
+  const listFields = schema.fields.filter((f) => f.endsWith('Allowlist'));
+  const globFields = schema.fields.filter((f) => f.endsWith('AllowGlob'));
+
+  const hasListConstraint = listFields.some((f) => Array.isArray(config[f]) && config[f].length > 0);
+  const hasGlobConstraint = globFields.some((f) => typeof config[f] === 'string' && config[f].length > 0);
+
+  // No allowlist configured: permit everything.
+  if (!hasListConstraint && !hasGlobConstraint) {
+    return { allowed: true, reason: 'no allowlist configured' };
+  }
+
+  // Check explicit list membership.
+  for (const field of listFields) {
+    if (Array.isArray(config[field]) && config[field].length > 0) {
+      if (config[field].includes(target)) {
+        return { allowed: true, reason: `matched ${field}` };
+      }
+    }
+  }
+
+  // Check glob patterns.
+  for (const field of globFields) {
+    if (typeof config[field] === 'string' && config[field].length > 0) {
+      if (globMatch(config[field], target)) {
+        return { allowed: true, reason: `matched ${field} pattern '${config[field]}'` };
+      }
+    }
+  }
+
+  return {
+    allowed: false,
+    reason: `'${target}' is not in the configured allowlist for ${providerName}`,
+  };
+}
+
 export const CAPABILITIES = Object.freeze([
   'read',
   'search',

package/lib/providers/creds.mjs

@@ -0,0 +1,219 @@
+/**
+ * lib/providers/creds.mjs — credential management for provider integrations.
+ *
+ * Reads and writes provider credentials stored in `~/.construct/config.env`.
+ * Each provider block is delimited by comment markers so the file can be
+ * parsed without a full ini/dotenv library and can also be sourced by a shell.
+ *
+ * Block format (example for `github`):
+ *
+ *   # CONSTRUCT_CREDS_GITHUB
+ *   CONSTRUCT_CREDS_GITHUB_KEY=ghp_xxx
+ *   CONSTRUCT_CREDS_GITHUB_ACCOUNT=myorg
+ *   CONSTRUCT_CREDS_GITHUB_ROTATED_AT=2026-05-27
+ *   # END_CONSTRUCT_CREDS_GITHUB
+ *
+ * Security: `writeCreds` sets the file mode to 0600 after every write.
+ * `checkCredsFileMode` reports whether the current mode is within policy.
+ *
+ * All functions are synchronous except those that need the filesystem and
+ * are documented as async. Currently all ops are sync; the async signature
+ * is reserved for future keychain-backend support.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const CONSTRUCT_DIR = path.join(os.homedir(), '.construct');
+const CONFIG_FILE = 'config.env';
+
+export function credsFilePath() {
+  return path.join(CONSTRUCT_DIR, CONFIG_FILE);
+}
+
+function providerKey(provider) {
+  return provider.toUpperCase().replace(/-/g, '_');
+}
+
+function blockStart(key) {
+  return `# CONSTRUCT_CREDS_${key}`;
+}
+
+function blockEnd(key) {
+  return `# END_CONSTRUCT_CREDS_${key}`;
+}
+
+function readRaw() {
+  const fp = credsFilePath();
+  try {
+    return fs.readFileSync(fp, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return '';
+    throw err;
+  }
+}
+
+function writeRaw(content) {
+  const fp = credsFilePath();
+  fs.mkdirSync(path.dirname(fp), { recursive: true });
+  fs.writeFileSync(fp, content, { encoding: 'utf8', mode: 0o600 });
+
+  // Re-apply mode after write; some platforms reset on open.
+  fs.chmodSync(fp, 0o600);
+}
+
+function extractBlocks(raw) {
+  const blocks = {};
+  const lines = raw.split('\n');
+  let current = null;
+  let currentLines = [];
+
+  for (const line of lines) {
+    const startMatch = line.match(/^# CONSTRUCT_CREDS_([A-Z0-9_]+)$/);
+    const endMatch = line.match(/^# END_CONSTRUCT_CREDS_([A-Z0-9_]+)$/);
+
+    if (startMatch) {
+      current = startMatch[1];
+      currentLines = [line];
+      continue;
+    }
+    if (endMatch && current === endMatch[1]) {
+      currentLines.push(line);
+      blocks[current] = currentLines.join('\n');
+      current = null;
+      currentLines = [];
+      continue;
+    }
+    if (current) {
+      currentLines.push(line);
+    }
+  }
+
+  return blocks;
+}
+
+function parseBlock(blockText) {
+  const result = {};
+  for (const line of blockText.split('\n')) {
+    const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+    if (!m) continue;
+    result[m[1]] = m[2];
+  }
+  return result;
+}
+
+function buildBlock(key, { account, apiKey, rotatedAt }) {
+  const prefix = `CONSTRUCT_CREDS_${key}`;
+  const lines = [blockStart(key)];
+  if (apiKey !== undefined) lines.push(`${prefix}_KEY=${apiKey}`);
+  if (account !== undefined) lines.push(`${prefix}_ACCOUNT=${account}`);
+  if (rotatedAt !== undefined) lines.push(`${prefix}_ROTATED_AT=${rotatedAt}`);
+  lines.push(blockEnd(key));
+  return lines.join('\n');
+}
+
+function nextRotationDue(rotatedAtStr) {
+  if (!rotatedAtStr) return null;
+  const d = new Date(rotatedAtStr);
+  if (isNaN(d.getTime())) return null;
+  d.setDate(d.getDate() + 90);
+  return d.toISOString().slice(0, 10);
+}
+
+export function readCreds() {
+  const raw = readRaw();
+  const blocks = extractBlocks(raw);
+  const result = {};
+
+  for (const [upperKey, blockText] of Object.entries(blocks)) {
+    const prefix = `CONSTRUCT_CREDS_${upperKey}`;
+    const fields = parseBlock(blockText);
+    const rotatedAt = fields[`${prefix}_ROTATED_AT`] || null;
+    result[upperKey.toLowerCase().replace(/_/g, '-')] = {
+      account: fields[`${prefix}_ACCOUNT`] || null,
+      key: fields[`${prefix}_KEY`] || null,
+      rotatedAt,
+      nextRotationDue: nextRotationDue(rotatedAt),
+    };
+  }
+
+  return result;
+}
+
+export function writeCreds(provider, { key, account } = {}) {
+  const pKey = providerKey(provider);
+  const raw = readRaw();
+  const blocks = extractBlocks(raw);
+
+  const existing = blocks[pKey] ? parseBlock(blocks[pKey]) : {};
+  const prefix = `CONSTRUCT_CREDS_${pKey}`;
+
+  const rotatedAt = key !== undefined
+    ? new Date().toISOString().slice(0, 10)
+    : (existing[`${prefix}_ROTATED_AT`] || null);
+
+  const mergedAccount = account !== undefined ? account : (existing[`${prefix}_ACCOUNT`] || undefined);
+  const mergedKey = key !== undefined ? key : (existing[`${prefix}_KEY`] || undefined);
+
+  const newBlock = buildBlock(pKey, { account: mergedAccount, apiKey: mergedKey, rotatedAt });
+
+  let newRaw;
+  if (blocks[pKey]) {
+    const startIdx = raw.indexOf(blockStart(pKey));
+    const endIdx = raw.indexOf(blockEnd(pKey)) + blockEnd(pKey).length;
+    newRaw = raw.slice(0, startIdx) + newBlock + raw.slice(endIdx);
+  } else {
+    const trimmed = raw.trimEnd();
+    newRaw = trimmed ? `${trimmed}\n\n${newBlock}\n` : `${newBlock}\n`;
+  }
+
+  writeRaw(newRaw);
+}
+
+export function deleteCreds(provider) {
+  const pKey = providerKey(provider);
+  const raw = readRaw();
+  const start = blockStart(pKey);
+  const end = blockEnd(pKey);
+
+  const startIdx = raw.indexOf(start);
+  if (startIdx === -1) return;
+
+  const endIdx = raw.indexOf(end, startIdx);
+  if (endIdx === -1) return;
+
+  const before = raw.slice(0, startIdx).trimEnd();
+  const after = raw.slice(endIdx + end.length).trimStart();
+
+  const newRaw = before && after
+    ? `${before}\n\n${after}`
+    : before
+      ? `${before}\n`
+      : after || '';
+
+  writeRaw(newRaw);
+}
+
+export function checkCredsFileMode() {
+  const fp = credsFilePath();
+  try {
+    const stat = fs.statSync(fp);
+    const mode = stat.mode & 0o777;
+    const modeStr = '0' + mode.toString(8);
+    return { ok: mode <= 0o600, mode: modeStr };
+  } catch (err) {
+    if (err.code === 'ENOENT') return { ok: true, mode: 'absent' };
+    throw err;
+  }
+}
+
+export function listCreds() {
+  const all = readCreds();
+  return Object.entries(all).map(([provider, data]) => ({
+    provider,
+    account: data.account,
+    rotatedAt: data.rotatedAt,
+    nextRotationDue: data.nextRotationDue,
+  }));
+}

package/lib/providers/scaffold.mjs

@@ -0,0 +1,107 @@
+/**
+ * lib/providers/scaffold.mjs — provider scaffold generator.
+ *
+ * Reads the template files from `templates/provider-scaffold/`, substitutes
+ * the %%PROVIDER_NAME%% and %%CAPABILITIES%% placeholders, and writes the
+ * result into `lib/providers/<name>/`. Returns the list of files created so
+ * the CLI can report them to the user.
+ *
+ * Supported capabilities: read, search, write, watch, webhook.
+ * The `read` and `search` methods are always included in the generated
+ * index.mjs; additional capabilities listed in `options.capabilities` add
+ * stub implementations for write, watch, and webhook.
+ *
+ * `scaffoldProvider` is idempotent with respect to the directory: it will
+ * not overwrite an existing file unless `options.force = true`. This prevents
+ * accidental loss of work when a developer reruns the command.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.resolve(__dirname, '..', '..', 'templates', 'provider-scaffold');
+
+const ALL_CAPABILITIES = ['read', 'search', 'write', 'watch', 'webhook'];
+
+function capabilityStub(cap) {
+  const stubs = {
+    write: `
+    async write(payload, config = {}) {
+      // Replace with a real write operation against the remote system. // construct-lint-ignore
+      throw new Error('not implemented');
+    },`,
+    watch: `
+    async watch(config = {}, callback) {
+      // Replace with a real subscription; call callback(item) on new events. // construct-lint-ignore
+      throw new Error('not implemented');
+    },`,
+    webhook: `
+    async webhook(config = {}, request) {
+      // Replace with real webhook signature verification and dispatch. // construct-lint-ignore
+      return { ok: false, error: 'not implemented' };
+    },`,
+  };
+  return stubs[cap] || '';
+}
+
+function renderIndex(name, capabilities) {
+  const capList = capabilities.filter((c) => ALL_CAPABILITIES.includes(c));
+  const capString = capList.join(', ');
+
+  const extraStubs = capList
+    .filter((c) => !['read', 'search'].includes(c))
+    .map(capabilityStub)
+    .join('\n');
+
+  const template = fs.readFileSync(path.join(TEMPLATES_DIR, 'index.mjs'), 'utf8');
+  let rendered = template
+    .replace(/%%PROVIDER_NAME%%/g, name)
+    .replace(/%%CAPABILITIES%%/g, capString);
+
+  if (extraStubs) {
+    rendered = rendered.replace(
+      /(\s+async search\(query, config = \{\}\) \{[\s\S]*?throw new Error\('not implemented'\);\n\s+\},)/,
+      `$1\n${extraStubs}`,
+    );
+  }
+
+  return rendered;
+}
+
+function renderTest(name) {
+  const template = fs.readFileSync(path.join(TEMPLATES_DIR, 'health.test.mjs'), 'utf8');
+  return template.replace(/%%PROVIDER_NAME%%/g, name);
+}
+
+export async function scaffoldProvider(name, options = {}) {
+  const {
+    capabilities = ['read', 'search'],
+    cwd = process.cwd(),
+    force = false,
+  } = options;
+
+  if (!name || typeof name !== 'string' || !/^[a-z0-9-]+$/.test(name)) {
+    throw new Error(`scaffoldProvider: name must be a lowercase alphanumeric-and-hyphen string, got '${name}'`);
+  }
+
+  const providerDir = path.join(cwd, 'lib', 'providers', name);
+  fs.mkdirSync(providerDir, { recursive: true });
+
+  const files = [];
+
+  const indexPath = path.join(providerDir, 'index.mjs');
+  if (force || !fs.existsSync(indexPath)) {
+    fs.writeFileSync(indexPath, renderIndex(name, capabilities), 'utf8');
+    files.push(indexPath);
+  }
+
+  const testPath = path.join(providerDir, 'health.test.mjs');
+  if (force || !fs.existsSync(testPath)) {
+    fs.writeFileSync(testPath, renderTest(name), 'utf8');
+    files.push(testPath);
+  }
+
+  return { providerDir, files };
+}

package/lib/reflect.mjs

@@ -8,10 +8,11 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
 import { join, resolve, basename } from 'node:path';
 import { execSync } from 'node:child_process';
-import { addObservation } from './observation-store.mjs';
+import { addObservation, listObservations } from './observation-store.mjs';
 import { loadConstructEnv } from './env-config.mjs';
 import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS, inferKnowledgeTarget } from './knowledge/layout.mjs';
 import { extractSessionObservation } from './reflect/extractor.mjs';
+import { readContextState, contextSummaryLine } from './context-state.mjs';
 
 const HOME = process.env.HOME || process.env.USERPROFILE;
 const USER_ENV_PATH = join(HOME, '.construct', 'config.env');
@@ -47,12 +48,19 @@ export async function runReflectCli(args) {
     target = `knowledge/${target}`;
   }
 
-  // If no summary provided, try to get it from stdin or prompt
+  let summarySource = 'cli';
   if (!summary) {
-    // For now, we'll require explicit summary - in future could read from chat context
-    console.error('Error: --summary=<text> is required to capture improvement feedback');
-    console.error('Example: construct reflect --target=internal --summary="Improve Slack channel intent parsing to handle edge cases"');
-    process.exit(1);
+    const derived = deriveSummaryFromContext(process.cwd());
+    if (derived) {
+      summary = derived;
+      summarySource = 'auto-derived';
+      console.error(`Note: --summary not provided; using auto-derived summary from .cx/context.md and recent observations.`);
+      console.error(`Captured summary: "${summary.slice(0, 180)}${summary.length > 180 ? '…' : ''}"`);
+    } else {
+      console.error('Error: --summary=<text> is required (no .cx/context.md or recent session summaries to derive from)');
+      console.error('Example: construct reflect --target=internal --summary="Improve Slack channel intent parsing to handle edge cases"');
+      process.exit(1);
+    }
   }
 
   // Resolve the knowledge directory for this target
@@ -110,15 +118,14 @@ export async function runReflectCli(args) {
   // Write the file
   writeFileSync(filePath, content);
 
-  // Record an observation about this feedback
-  const observationSummary = `[reflect] Improvement feedback captured: ${summary.slice(0, 100)}${summary.length > 100 ? '...' : ''}`;
+  const observationSummary = `[reflect] Improvement feedback captured (${summarySource}): ${summary.slice(0, 100)}${summary.length > 100 ? '...' : ''}`;
   addObservation(process.cwd(), {
     role: 'construct',
-    category: 'insight', // Feedback is typically an insight unless it's about a problem
+    category: 'insight',
     summary: observationSummary,
-    content: `Feedback captured via construct reflect:\n\n${summary}\n\nStored as: ${filePath}\nTarget: ${knowledgeSubdir}/`,
-    tags: ['reflect', 'improvement-feedback', `knowledge:${knowledgeSubdir}`],
-    confidence: 0.9,
+    content: `Feedback captured via construct reflect (${summarySource}):\n\n${summary}\n\nStored as: ${filePath}\nTarget: ${knowledgeSubdir}/`,
+    tags: ['reflect', 'improvement-feedback', `knowledge:${knowledgeSubdir}`, `source:${summarySource}`],
+    confidence: summarySource === 'auto-derived' ? 0.65 : 0.9,
     source: 'reflect-command',
   });
 
@@ -186,6 +193,36 @@ export async function runReflectAuto({ transcriptPath, cwd, sessionId, durationM
   return result?.id ?? null;
 }
 
+/**
+ * Derive a one-paragraph reflect summary from durable session state — the
+ * context.md digest first, then the most recent session-summary observation.
+ * Returns null when neither source yields useful content.
+ */
+export function deriveSummaryFromContext(cwd) {
+  const parts = [];
+
+  try {
+    const state = readContextState(cwd);
+    const line = contextSummaryLine(state);
+    if (line && line.trim().length > 20) parts.push(line.trim());
+  } catch { /* best effort */ }
+
+  try {
+    const recent = listObservations(cwd, { limit: 5 }) || [];
+    const sessionSummary = recent.find((o) => Array.isArray(o.tags) && o.tags.includes('session-summary'));
+    if (sessionSummary?.summary) {
+      const text = String(sessionSummary.summary).replace(/^\[[^\]]+\]\s*/, '').trim();
+      if (text.length > 20 && !parts.some((p) => p.includes(text.slice(0, 40)))) {
+        parts.push(text);
+      }
+    }
+  } catch { /* best effort */ }
+
+  if (parts.length === 0) return null;
+  const joined = parts.join(' — ');
+  return joined.length > 600 ? joined.slice(0, 580) + '…' : joined;
+}
+
 function safeProject(cwd) {
   try { return basename(cwd) || null; } catch { return null; }
 }