@jaimevalasek/aioson 1.20.0 → 1.21.3

package/src/commands/memory-search.js

@@ -1,135 +1,135 @@
-'use strict';
-
-/**
- * aioson memory:search "<query>" — full-text search over project_learnings + promoted rules.
- *
- * Active Learning Loop Phase 2 (DD-4: BM25 default via ORDER BY rank ASC).
- * Tier-1 silent telemetry-wise (no runtime:emit per DD-4 guardrail #8) but writes
- * results to stdout (or JSON if --json) — this is a user-facing CLI verb, not a
- * background hook.
- *
- * Usage:
- *   aioson memory:search "<query>" [--limit=5] [--surface=rules|learnings|all]
- *                                  [--include-archived] [--json]
- */
-
-const path = require('node:path');
-const { openRuntimeDb } = require('../runtime-store');
-const { searchProjectLearnings, QUERY_MAX_CHARS } = require('../learning-loop-fts5');
-
-function tFn(t, key, params) {
-  if (typeof t === 'function') {
-    try { return t(key, params || {}); } catch { /* fall through */ }
-  }
-  return null;
-}
-
-function stripDelimiters(snippet) {
-  if (!snippet) return '';
-  return String(snippet).replace(/«|»/g, '');
-}
-
-function formatTextResults(results) {
-  const lines = [];
-  for (let i = 0; i < results.length; i++) {
-    const r = results[i];
-    lines.push(
-      `${i + 1}. [${r.target_type}] ${r.target_id} (status=${r.status}${r.feature_slug ? `, feature=${r.feature_slug}` : ''}, score=${Number(r.score).toFixed(4)})`
-    );
-    lines.push(`   ${stripDelimiters(r.snippet)}`);
-  }
-  return lines.join('\n');
-}
-
-async function runMemorySearch({ args, options = {}, logger, t }) {
-  const targetDir = path.resolve(process.cwd(), args[1] !== undefined ? args[1] : '.');
-  // Positional 0 is the query string. Some shells will pass it as args[0].
-  const query = args[0] !== undefined && args[0] !== null && String(args[0]).trim() !== ''
-    ? String(args[0])
-    : (options.query ? String(options.query) : '');
-
-  const wantJson = Boolean(options.json);
-  const log = (msg) => { if (logger && typeof logger.log === 'function') logger.log(msg); };
-
-  if (!query || !query.trim()) {
-    const msg = tFn(t, 'memory_search.query_empty') || `memory:search requires a non-empty query.`;
-    if (wantJson) return { ok: false, reason: 'query_empty' };
-    log(msg);
-    return { ok: false, reason: 'query_empty' };
-  }
-  if (query.length > QUERY_MAX_CHARS) {
-    const msg = tFn(t, 'memory_search.query_too_long', { max: QUERY_MAX_CHARS })
-      || `memory:search query exceeds ${QUERY_MAX_CHARS} chars.`;
-    if (wantJson) return { ok: false, reason: 'query_too_long', max: QUERY_MAX_CHARS };
-    log(msg);
-    return { ok: false, reason: 'query_too_long' };
-  }
-
-  const limit = options.limit !== undefined ? Number(options.limit) : 5;
-  const surface = options.surface || 'all';
-  const includeArchived = Boolean(options['include-archived'] || options.includeArchived);
-
-  let dbHandle;
-  try {
-    dbHandle = await openRuntimeDb(targetDir);
-  } catch (err) {
-    const message = err && err.message ? err.message : String(err);
-    if (wantJson) return { ok: false, reason: 'runtime_db_unavailable', error: message };
-    log(`memory:search runtime db unavailable: ${message}`);
-    return { ok: false, reason: 'runtime_db_unavailable' };
-  }
-
-  const { db } = dbHandle;
-  let outcome;
-  try {
-    outcome = searchProjectLearnings(db, { query, limit, surface, includeArchived });
-  } finally {
-    db.close();
-  }
-
-  if (!outcome.ok) {
-    if (outcome.reason === 'invalid_surface') {
-      const msg = tFn(t, 'memory_search.invalid_surface', { value: outcome.value })
-        || `memory:search invalid --surface value: ${outcome.value}.`;
-      if (wantJson) return { ok: false, reason: 'invalid_surface', value: outcome.value };
-      log(msg);
-      return { ok: false, reason: 'invalid_surface' };
-    }
-    if (outcome.reason === 'query_unparseable') {
-      const msg = tFn(t, 'memory_search.query_unparseable', { value: outcome.value })
-        || `memory:search query reduces to empty after sanitization: "${outcome.value}".`;
-      if (wantJson) return { ok: false, reason: 'query_unparseable', value: outcome.value };
-      log(msg);
-      return { ok: false, reason: 'query_unparseable' };
-    }
-    if (wantJson) return outcome;
-    log(`memory:search rejected: ${outcome.reason}`);
-    return outcome;
-  }
-
-  const { results } = outcome;
-  if (wantJson) {
-    return {
-      ok: true,
-      query: outcome.query,
-      surface: outcome.surface,
-      limit: outcome.limit,
-      result_count: results.length,
-      results
-    };
-  }
-
-  if (results.length === 0) {
-    const msg = tFn(t, 'memory_search.no_results', { query }) || `No matches for "${query}".`;
-    log(msg);
-    return { ok: true, result_count: 0 };
-  }
-
-  const header = tFn(t, 'memory_search.results_header', { count: results.length, query })
-    || `Top ${results.length} hits for "${query}":`;
-  log(header);
-  log(formatTextResults(results));
-  return { ok: true, result_count: results.length };
-}
-
-module.exports = { runMemorySearch };
+'use strict';
+
+/**
+ * aioson memory:search "<query>" — full-text search over project_learnings + promoted rules.
+ *
+ * Active Learning Loop Phase 2 (DD-4: BM25 default via ORDER BY rank ASC).
+ * Tier-1 silent telemetry-wise (no runtime:emit per DD-4 guardrail #8) but writes
+ * results to stdout (or JSON if --json) — this is a user-facing CLI verb, not a
+ * background hook.
+ *
+ * Usage:
+ *   aioson memory:search "<query>" [--limit=5] [--surface=rules|learnings|all]
+ *                                  [--include-archived] [--json]
+ */
+
+const path = require('node:path');
+const { openRuntimeDb } = require('../runtime-store');
+const { searchProjectLearnings, QUERY_MAX_CHARS } = require('../learning-loop-fts5');
+
+function tFn(t, key, params) {
+  if (typeof t === 'function') {
+    try { return t(key, params || {}); } catch { /* fall through */ }
+  }
+  return null;
+}
+
+function stripDelimiters(snippet) {
+  if (!snippet) return '';
+  return String(snippet).replace(/«|»/g, '');
+}
+
+function formatTextResults(results) {
+  const lines = [];
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i];
+    lines.push(
+      `${i + 1}. [${r.target_type}] ${r.target_id} (status=${r.status}${r.feature_slug ? `, feature=${r.feature_slug}` : ''}, score=${Number(r.score).toFixed(4)})`
+    );
+    lines.push(`   ${stripDelimiters(r.snippet)}`);
+  }
+  return lines.join('\n');
+}
+
+async function runMemorySearch({ args, options = {}, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args[1] !== undefined ? args[1] : '.');
+  // Positional 0 is the query string. Some shells will pass it as args[0].
+  const query = args[0] !== undefined && args[0] !== null && String(args[0]).trim() !== ''
+    ? String(args[0])
+    : (options.query ? String(options.query) : '');
+
+  const wantJson = Boolean(options.json);
+  const log = (msg) => { if (logger && typeof logger.log === 'function') logger.log(msg); };
+
+  if (!query || !query.trim()) {
+    const msg = tFn(t, 'cli.memory_search.query_empty') || `memory:search requires a non-empty query.`;
+    if (wantJson) return { ok: false, reason: 'query_empty' };
+    log(msg);
+    return { ok: false, reason: 'query_empty' };
+  }
+  if (query.length > QUERY_MAX_CHARS) {
+    const msg = tFn(t, 'cli.memory_search.query_too_long', { max: QUERY_MAX_CHARS })
+      || `memory:search query exceeds ${QUERY_MAX_CHARS} chars.`;
+    if (wantJson) return { ok: false, reason: 'query_too_long', max: QUERY_MAX_CHARS };
+    log(msg);
+    return { ok: false, reason: 'query_too_long' };
+  }
+
+  const limit = options.limit !== undefined ? Number(options.limit) : 5;
+  const surface = options.surface || 'all';
+  const includeArchived = Boolean(options['include-archived'] || options.includeArchived);
+
+  let dbHandle;
+  try {
+    dbHandle = await openRuntimeDb(targetDir);
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    if (wantJson) return { ok: false, reason: 'runtime_db_unavailable', error: message };
+    log(`memory:search runtime db unavailable: ${message}`);
+    return { ok: false, reason: 'runtime_db_unavailable' };
+  }
+
+  const { db } = dbHandle;
+  let outcome;
+  try {
+    outcome = searchProjectLearnings(db, { query, limit, surface, includeArchived });
+  } finally {
+    db.close();
+  }
+
+  if (!outcome.ok) {
+    if (outcome.reason === 'invalid_surface') {
+      const msg = tFn(t, 'cli.memory_search.invalid_surface', { value: outcome.value })
+        || `memory:search invalid --surface value: ${outcome.value}.`;
+      if (wantJson) return { ok: false, reason: 'invalid_surface', value: outcome.value };
+      log(msg);
+      return { ok: false, reason: 'invalid_surface' };
+    }
+    if (outcome.reason === 'query_unparseable') {
+      const msg = tFn(t, 'cli.memory_search.query_unparseable', { value: outcome.value })
+        || `memory:search query reduces to empty after sanitization: "${outcome.value}".`;
+      if (wantJson) return { ok: false, reason: 'query_unparseable', value: outcome.value };
+      log(msg);
+      return { ok: false, reason: 'query_unparseable' };
+    }
+    if (wantJson) return outcome;
+    log(`memory:search rejected: ${outcome.reason}`);
+    return outcome;
+  }
+
+  const { results } = outcome;
+  if (wantJson) {
+    return {
+      ok: true,
+      query: outcome.query,
+      surface: outcome.surface,
+      limit: outcome.limit,
+      result_count: results.length,
+      results
+    };
+  }
+
+  if (results.length === 0) {
+    const msg = tFn(t, 'cli.memory_search.no_results', { query }) || `No matches for "${query}".`;
+    log(msg);
+    return { ok: true, result_count: 0 };
+  }
+
+  const header = tFn(t, 'cli.memory_search.results_header', { count: results.length, query })
+    || `Top ${results.length} hits for "${query}":`;
+  log(header);
+  log(formatTextResults(results));
+  return { ok: true, result_count: results.length };
+}
+
+module.exports = { runMemorySearch };

package/src/commands/memory-trim.js

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * aioson memory:trim [.] [--keep=<N>] [--archive=<path>] [--dry-run] [--json]
+ *
+ * P0 of the agent-loading-contract: rolls COLD entries out of the
+ * `## What the system already has` section of bootstrap/current-state.md into a
+ * separate archive (default `bootstrap/current-state-archive.md`), keeping only
+ * the newest `--keep` entries (default 12) plus any entry tied to an in_progress
+ * feature. Frontmatter and every other section are preserved byte-for-byte, and
+ * archived entries are MOVED verbatim — never deleted.
+ *
+ * Tier-2 (memory mutation): refuses to run inside a runtime hook and emits
+ * `notify --level=warn` before any disk write. `--dry-run` mutates nothing.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { runNotify } = require('./notify');
+const {
+  splitCurrentState,
+  buildArchiveContent,
+  parseActiveSlugs
+} = require('../current-state-trim');
+
+const CURRENT_STATE_REL = '.aioson/context/bootstrap/current-state.md';
+const DEFAULT_ARCHIVE_REL = '.aioson/context/bootstrap/current-state-archive.md';
+const FEATURES_REL = '.aioson/context/features.md';
+
+function tFn(t, key, params) {
+  if (typeof t === 'function') {
+    try { return t(key, params || {}); } catch { /* fall through */ }
+  }
+  return null;
+}
+
+function isHookContext() {
+  return process.env.AIOSON_RUNTIME_HOOK === '1';
+}
+
+function readFileOrNull(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return null; }
+}
+
+function parseKeep(value) {
+  if (value === undefined || value === null || value === '') return 12;
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return 12;
+  return Math.floor(n);
+}
+
+async function runMemoryTrim({ args, options = {}, logger, t }) {
+  const targetDir = path.resolve(process.cwd(), args && args[0] ? args[0] : '.');
+  const wantJson = Boolean(options.json);
+  const dryRun = Boolean(options['dry-run'] || options.dryRun);
+  const keep = parseKeep(options.keep);
+  const log = (msg) => { if (logger && typeof logger.log === 'function') logger.log(msg); };
+
+  if (isHookContext()) {
+    if (wantJson) return { ok: false, reason: 'hook_blocked' };
+    log(tFn(t, 'cli.memory_trim.hook_blocked')
+      || 'memory:trim cannot be invoked from a runtime hook (tier-2 requires human action).');
+    return { ok: false, reason: 'hook_blocked' };
+  }
+
+  const currentStatePath = path.join(targetDir, CURRENT_STATE_REL);
+  let archivePath;
+  if (options.archive) {
+    // SECURITY (TS-LC-01): contain --archive under the project root. Resolve
+    // relative to the project (not cwd) and reject absolute escapes / `..`
+    // traversal, so the command can never write/overwrite a file outside the
+    // project — mirrors the containment wall in memory-reflect-commit.js.
+    const root = path.resolve(targetDir);
+    const resolved = path.resolve(root, String(options.archive));
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+      if (wantJson) return { ok: false, reason: 'archive_path_escape' };
+      log(tFn(t, 'cli.memory_trim.archive_path_escape', { path: String(options.archive) })
+        || `memory:trim: refused --archive outside the project: ${options.archive}`);
+      return { ok: false, reason: 'archive_path_escape' };
+    }
+    archivePath = resolved;
+  } else {
+    archivePath = path.join(targetDir, DEFAULT_ARCHIVE_REL);
+  }
+
+  const content = readFileOrNull(currentStatePath);
+  if (content === null) {
+    if (wantJson) return { ok: false, reason: 'no_current_state' };
+    log(tFn(t, 'cli.memory_trim.no_current_state', { path: CURRENT_STATE_REL })
+      || `memory:trim: ${CURRENT_STATE_REL} not found (nothing to trim).`);
+    return { ok: false, reason: 'no_current_state' };
+  }
+
+  const activeSlugs = parseActiveSlugs(readFileOrNull(path.join(targetDir, FEATURES_REL)) || '');
+  const result = splitCurrentState(content, { keep, activeSlugs });
+  if (!result.ok) {
+    if (wantJson) return { ok: false, reason: result.reason };
+    log(tFn(t, 'cli.memory_trim.section_not_found')
+      || `memory:trim: "## What the system already has" section not found — nothing to do.`);
+    return { ok: false, reason: result.reason };
+  }
+
+  const { hotContent, archivedEntries, stats } = result;
+
+  if (archivedEntries.length === 0) {
+    if (wantJson) return { ok: true, dry_run: dryRun, archived: 0, stats };
+    log(tFn(t, 'cli.memory_trim.nothing_to_archive', { kept: stats.kept, keep })
+      || `memory:trim: ${stats.kept} entr${stats.kept === 1 ? 'y' : 'ies'} within keep=${keep} window — nothing to archive.`);
+    return { ok: true, dry_run: dryRun, archived: 0, stats };
+  }
+
+  if (dryRun) {
+    if (!wantJson) {
+      log(tFn(t, 'cli.memory_trim.dry_run_summary', {
+        archived: stats.archived,
+        kept: stats.kept,
+        total: stats.total_entries,
+        keep,
+        saved_kb: (stats.saved_bytes / 1024).toFixed(1),
+        before_kb: (stats.before_bytes / 1024).toFixed(1),
+        after_kb: (stats.after_bytes / 1024).toFixed(1)
+      }) || `memory:trim [dry-run]: would archive ${stats.archived}/${stats.total_entries} entries (keep=${keep}, active-slug exempt). ${(stats.before_bytes / 1024).toFixed(1)}KB → ${(stats.after_bytes / 1024).toFixed(1)}KB (saves ${(stats.saved_bytes / 1024).toFixed(1)}KB). No files written.`);
+      for (const e of archivedEntries.slice(0, 5)) {
+        log(`  - would archive: ${e.slice(0, 100)}${e.length > 100 ? '…' : ''}`);
+      }
+      if (archivedEntries.length > 5) log(`  … and ${archivedEntries.length - 5} more`);
+    }
+    return { ok: true, dry_run: true, archived: stats.archived, stats, archive_path: path.relative(targetDir, archivePath) };
+  }
+
+  // Real run — tier-2 notify before any mutation (BR-ALL-06).
+  try {
+    const notifyResult = await runNotify({
+      args: [targetDir],
+      options: {
+        level: 'warn',
+        topic: 'memory',
+        message: tFn(t, 'cli.memory_trim.notify_template', { archived: stats.archived })
+          || `trimming current-state.md: archiving ${stats.archived} cold entries`,
+        agent: 'memory-trim',
+        json: wantJson ? true : undefined
+      },
+      logger: logger || { log: () => {} }
+    });
+    if (notifyResult && notifyResult.ok === false) {
+      if (wantJson) return { ok: false, reason: 'notify_blocked', exitCode: notifyResult.exitCode };
+      log('memory:trim aborted: tier-2 notify returned non-zero exit code.');
+      return { ok: false, reason: 'notify_blocked' };
+    }
+  } catch (err) {
+    if (wantJson) return { ok: false, reason: 'notify_failed', error: String((err && err.message) || err) };
+    log(`memory:trim notify failed: ${(err && err.message) || err}`);
+    return { ok: false, reason: 'notify_failed' };
+  }
+
+  const nowIso = new Date().toISOString();
+  const eol = /\r\n/.test(content) ? '\r\n' : '\n';
+  const existingArchive = readFileOrNull(archivePath) || '';
+  const newArchive = buildArchiveContent(existingArchive, archivedEntries, nowIso, eol);
+
+  try {
+    fs.mkdirSync(path.dirname(archivePath), { recursive: true });
+    fs.writeFileSync(archivePath, newArchive, 'utf8');
+    fs.writeFileSync(currentStatePath, hotContent, 'utf8');
+  } catch (err) {
+    if (wantJson) return { ok: false, reason: 'write_failed', error: String((err && err.message) || err) };
+    log(`memory:trim write failed: ${(err && err.message) || err}`);
+    return { ok: false, reason: 'write_failed' };
+  }
+
+  if (wantJson) {
+    return {
+      ok: true,
+      dry_run: false,
+      archived: stats.archived,
+      stats,
+      current_state_path: path.relative(targetDir, currentStatePath),
+      archive_path: path.relative(targetDir, archivePath)
+    };
+  }
+  log(tFn(t, 'cli.memory_trim.trimmed_success', {
+    archived: stats.archived,
+    kept: stats.kept,
+    before_kb: (stats.before_bytes / 1024).toFixed(1),
+    after_kb: (stats.after_bytes / 1024).toFixed(1),
+    archive: path.relative(targetDir, archivePath)
+  }) || `memory:trim ✓ archived ${stats.archived} entries (kept ${stats.kept}). ${(stats.before_bytes / 1024).toFixed(1)}KB → ${(stats.after_bytes / 1024).toFixed(1)}KB. Archive: ${path.relative(targetDir, archivePath)}`);
+  return { ok: true, dry_run: false, archived: stats.archived, stats };
+}
+
+module.exports = { runMemoryTrim };

package/src/constants.js

@@ -68,6 +68,7 @@ const MANAGED_FILES = [
   '.aioson/docs/sheldon/harness-contract.md',
   '.aioson/docs/dev/stack-conventions.md',
   '.aioson/docs/dev/execution-discipline.md',
+  '.aioson/docs/quality/code-health-analysis.md',
   '.aioson/skills/process/decision-presentation/SKILL.md',
   '.aioson/skills/process/decision-presentation/references/jargon-map.en.yaml',
   '.aioson/skills/process/decision-presentation/references/jargon-map.pt-BR.yaml',

package/src/current-state-trim.js

@@ -0,0 +1,170 @@
+'use strict';
+
+// Pure engine for trimming bootstrap/current-state.md (P0 of the
+// agent-loading-contract design-doc).
+//
+// The "## What the system already has" section is an append-only log that grows
+// unbounded (newest entries prepended). Every implementation/continuity/review
+// agent reads the whole file at activation, so this single section dominates the
+// per-activation token cost.
+//
+// splitCurrentState() moves COLD entries (older than the keep window AND not tied
+// to an active feature) out of that ONE section into a separate archive, keeping
+// frontmatter and every OTHER section byte-for-byte. Nothing is ever deleted —
+// archived entries are preserved verbatim and stay grep/`memory:search`-able.
+
+const HOT_SECTION = '## What the system already has';
+
+function detectEol(content) {
+  return /\r\n/.test(String(content || '')) ? '\r\n' : '\n';
+}
+
+function splitLines(content) {
+  return String(content || '').split(/\r?\n/);
+}
+
+function isEntry(line) {
+  return /^- /.test(line);
+}
+
+// Locate the hot-log section: its header line index and the index of the next
+// "## " header (or EOF). Returns null when the section is absent.
+function locateSection(lines) {
+  const headerIdx = lines.findIndex((l) => l.trim() === HOT_SECTION);
+  if (headerIdx === -1) return null;
+  let endIdx = lines.length;
+  for (let i = headerIdx + 1; i < lines.length; i++) {
+    if (/^##\s/.test(lines[i])) { endIdx = i; break; }
+  }
+  return { headerIdx, endIdx };
+}
+
+function entryMatchesActiveSlug(entryText, activeSlugs) {
+  return activeSlugs.some((s) => s && entryText.includes(s));
+}
+
+/**
+ * Split current-state.md into hot content + the entries that should be archived.
+ *
+ * @param {string} content raw current-state.md
+ * @param {object} opts
+ * @param {number} [opts.keep=12] number of newest entries to keep HOT
+ * @param {string[]} [opts.activeSlugs=[]] feature slugs whose entries are kept regardless of age
+ * @returns {{ok:boolean, reason?:string, hotContent?:string, archivedEntries?:string[], stats?:object}}
+ */
+function splitCurrentState(content, { keep = 12, activeSlugs = [] } = {}) {
+  const eol = detectEol(content);
+  const lines = splitLines(content);
+  const loc = locateSection(lines);
+  if (!loc) return { ok: false, reason: 'section_not_found' };
+
+  const { headerIdx, endIdx } = loc;
+  const sectionBody = lines.slice(headerIdx + 1, endIdx);
+  const entries = sectionBody.filter(isEntry);
+  const totalEntries = entries.length;
+
+  const kept = [];
+  const archivedEntries = [];
+  entries.forEach((entry, idx) => {
+    const recent = idx < keep;                                // newest-first: top N stay
+    const active = entryMatchesActiveSlug(entry, activeSlugs); // never archive active-feature history
+    if (recent || active) kept.push(entry);
+    else archivedEntries.push(entry);
+  });
+
+  // Section preamble = non-entry lines before the first bullet (the intro line).
+  const firstEntryOffset = sectionBody.findIndex(isEntry);
+  const preamble = firstEntryOffset === -1 ? sectionBody : sectionBody.slice(0, firstEntryOffset);
+  const introLines = preamble.filter((l) => l.trim() !== '');
+  const rest = lines.slice(endIdx); // next "## " section onward, kept verbatim
+
+  const hotLines = [
+    ...lines.slice(0, headerIdx + 1), // frontmatter … through the section header
+    '',
+    ...introLines,
+    '',
+    ...kept,
+    '',
+    ...rest
+  ];
+  const hotContent = hotLines.join(eol);
+
+  const beforeBytes = Buffer.byteLength(content, 'utf8');
+  const afterBytes = Buffer.byteLength(hotContent, 'utf8');
+  return {
+    ok: true,
+    hotContent,
+    archivedEntries,
+    stats: {
+      total_entries: totalEntries,
+      kept: kept.length,
+      archived: archivedEntries.length,
+      keep,
+      active_slugs: activeSlugs,
+      before_bytes: beforeBytes,
+      after_bytes: afterBytes,
+      saved_bytes: Math.max(0, beforeBytes - afterBytes)
+    }
+  };
+}
+
+const ARCHIVE_HEADER = '## Archived capabilities';
+
+function buildArchiveContent(existing, newEntries, nowIso, eol = '\n') {
+  if (!newEntries.length) return existing || '';
+  if (!existing || !existing.trim()) {
+    return [
+      '---',
+      'generated_by: memory-trim',
+      `updated_at: "${nowIso}"`,
+      '---',
+      '',
+      '# Current State — Archive',
+      '',
+      '> Cold storage for `current-state.md` entries rolled off the hot log by `aioson memory:trim`.',
+      '> Searchable (`memory:search` / grep); never loaded at agent activation. Append-only — never deleted.',
+      '',
+      ARCHIVE_HEADER,
+      '',
+      ...newEntries,
+      ''
+    ].join(eol);
+  }
+  // Prepend the new batch right after the archive header (newest-first), and
+  // bump updated_at when present.
+  const lines = existing.split(/\r?\n/);
+  const headerIdx = lines.findIndex((l) => l.trim() === ARCHIVE_HEADER);
+  let bumped = lines.map((l) =>
+    /^updated_at\s*:/.test(l) ? `updated_at: "${nowIso}"` : l
+  );
+  if (headerIdx === -1) {
+    return [...bumped, '', ...newEntries, ''].join(eol);
+  }
+  const insertAt = headerIdx + 1;
+  const head = bumped.slice(0, insertAt);
+  const tail = bumped.slice(insertAt);
+  return [...head, '', ...newEntries, ...tail].join(eol);
+}
+
+/**
+ * Parse in_progress feature slugs from a features.md pipe table.
+ * @returns {string[]}
+ */
+function parseActiveSlugs(featuresMd) {
+  return splitLines(featuresMd)
+    .map((l) => l.split('|').map((c) => c.trim()))
+    .filter((cols) => cols.length >= 4 && cols[2] === 'in_progress')
+    .map((cols) => cols[1])
+    .filter((slug) => slug && slug !== 'slug' && !/^-+$/.test(slug));
+}
+
+module.exports = {
+  HOT_SECTION,
+  ARCHIVE_HEADER,
+  splitCurrentState,
+  buildArchiveContent,
+  parseActiveSlugs,
+  // exported for tests
+  locateSection,
+  detectEol
+};

package/src/doctor.js

@@ -241,6 +241,23 @@ async function runDoctor(targetDir) {
     });
   }
 
+  // Gemini CLI deprecation advisory (gemini-phaseout Phase 1 / v1.21.0).
+  // Emits ONLY when the project actually uses Gemini (.gemini/permissions.toml
+  // OR .gemini/GEMINI.md present) so greenfield projects stay silent (BR-GP-03).
+  const geminiInUse =
+    (await exists(path.join(targetDir, '.gemini/permissions.toml'))) ||
+    (await exists(path.join(targetDir, '.gemini/GEMINI.md')));
+  if (geminiInUse) {
+    checks.push({
+      id: 'harness:gemini_deprecation',
+      severity: 'warning',
+      key: 'doctor.gemini_deprecation',
+      params: {},
+      ok: false,
+      hintKey: 'doctor.gemini_deprecation_hint'
+    });
+  }
+
   const contextPath = path.join(targetDir, '.aioson/context/project.context.md');
   checks.push({
     id: 'context:project',