@jaimevalasek/aioson 1.21.0 → 1.21.3

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.21.3] - 2026-05-28
+
+### Security
+- **`memory:trim --archive=<path>` is now contained under the project root (TS-LC-01).** It was resolved relative to `cwd` with no containment, so a crafted/typo'd path could write or overwrite a file outside the project. Now resolved under the project root and rejected with `archive_path_escape` on absolute or `..`-traversal escape — mirroring the containment wall in `memory-reflect-commit`. Localized message added in all 4 locales.
+- **`feature:close` auto-trim hook now honors `AIOSON_RUNTIME_HOOK` (TS-LC-02).** The hook called the trim engine directly, bypassing the hook-context guard that `memory:trim` enforces. It now skips when running in a hook/automation context, so a tier-2 memory mutation never fires outside explicit human action.
+
+### Tests
+- Coverage pass over the v1.21.2 agent-loading-contract code (`node --test --experimental-test-coverage`): `current-state-trim.js` 98.8%→100% line, `memory-trim.js` 73.9%→88.6% line / 64.4%→76.7% branch. Adds error/edge-path tests (`no_current_state`, `section_not_found`, custom/escaping `--archive`, headerless archive, hook skip paths) and verifies all `cli.memory_{archive,restore,search}` keys resolve.
+
+## [1.21.2] - 2026-05-28
+
+### Added
+- **Agent loading contract + `memory:trim`.** `bootstrap/current-state.md` is an append-only log that every implementation/review agent read in full at activation (~81KB / ~33k tokens, 84% of the bootstrap). New `aioson memory:trim [--keep=<N>] [--archive=<path>] [--dry-run] [--json]` splits its "## What the system already has" section into a HOT log + a cold `current-state-archive.md` (entries MOVED verbatim, never deleted; active-feature entries exempt). `feature:close` (PASS) auto-rolls aged entries (`--no-trim` to opt out). New governance doc `.aioson/design-docs/agent-loading-contract.md` defines the three loading tiers + retention policy. The repo's own current-state was trimmed 81KB → 21KB.
+- **`context:health` now measures `bootstrap/*.md`** — the per-activation layer it previously ignored — and excludes the cold `*-archive.md`; a heavy `current-state.md` now points to `memory:trim`.
+- **Shared code-health analysis lens** `.aioson/docs/quality/code-health-analysis.md` (plan → investigate → refine → operate → test → adjust over coverage, test sufficiency, regression need, execution-chain, performance, componentization), wired on-demand into `@tester`/`@qa`/`@pentester`/`@architect`/`@sheldon`/`@deyvin`.
+- **Current-state entry tagging** — the reflect engine, `@dev`, and `@committer` now prefix new entries with `[{slug} · {YYYY-MM-DD}]` for precise rollup; `@qa`/`@architect`/`@dev`/`@deyvin` bootstrap sections gained archive-awareness (grep the archive before flagging a capability as missing).
+
+### Fixed
+- **`memory:archive` / `memory:restore` / `memory:search` logged raw i18n keys** in every locale — they called message keys without the required `cli.` namespace prefix, so `t()` missed and echoed the key (e.g. `memory_archive.id_required`). All 25 calls now use the `cli.` prefix and localize correctly.
+
+## [1.21.1] - 2026-06-XX
+
+### Fixed
+- **`memory:reflect-commit --dry-run` is now non-destructive.** The command never read the `--dry-run` flag, so a "dry run" silently performed the full destructive commit — it wrote the bootstrap files **and** unlinked the single-use manifest, leaving the flow unrecoverable (`missing_manifest`) on the next call. `--dry-run` now runs validation + path containment exactly like a real commit, then returns `{ ok: true, dryRun: true, would_write: [...] }` without writing any file or consuming the manifest, so a real commit can still follow. Regression coverage in `tests/memory-reflect-commit-dry-run.test.js`. Note: the reflect manifest remains single-use — a successful real commit consumes it (re-run by re-running `memory:reflect-prepare`).
+
 ## [1.21.0] - 2026-06-XX
 
 ### Added

package/docs/pt/living-memory/reflexao-in-harness.md

@@ -121,6 +121,8 @@ O agente é livre para usar o LLM como achar melhor para fazer a reescrita. O CL
 
 Se tudo passa: escreve, apaga o manifest, emite `memory_reflect_committed` em runtime. Se falha: emite `memory_reflect_failed` com a lista de erros e o agente tem 1 retry.
 
+> **`--dry-run` (pré-visualização não-destrutiva):** `aioson memory:reflect-commit . --agent=dev --output=<json> --dry-run` roda a validação + containment de path exatamente como o commit real, mas **não escreve nada e não consome o manifest** — retorna `{ ok: true, dryRun: true, would_write: [...] }`. Use pra conferir o output antes de aplicar. Atenção: o manifest é **single-use** — um commit real (sem `--dry-run`) o apaga; pra recomeçar, rode `memory:reflect-prepare` de novo.
+
 ## Exemplo end-to-end
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.21.0",
+  "version": "1.21.3",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/cli.js

@@ -18,6 +18,7 @@ const { runChainAudit } = require('./commands/chain-audit');
 const { runMemorySearch } = require('./commands/memory-search');
 const { runMemoryArchive } = require('./commands/memory-archive');
 const { runMemoryRestore } = require('./commands/memory-restore');
+const { runMemoryTrim } = require('./commands/memory-trim');
 const { runSetupContext } = require('./commands/setup-context');
 const { runLocaleApply } = require('./commands/locale-apply');
 const { runSmokeTest } = require('./commands/smoke');
@@ -525,6 +526,8 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'memory-archive',
   'memory:restore',
   'memory-restore',
+  'memory:trim',
+  'memory-trim',
   'memory:reflect-prepare',
   'memory-reflect-prepare',
   'memory:reflect-commit',
@@ -1355,6 +1358,8 @@ async function main() {
       result = await runMemoryArchive({ args, options, logger: commandLogger, t });
     } else if (command === 'memory:restore' || command === 'memory-restore') {
       result = await runMemoryRestore({ args, options, logger: commandLogger, t });
+    } else if (command === 'memory:trim' || command === 'memory-trim') {
+      result = await runMemoryTrim({ args, options, logger: commandLogger, t });
     } else if (command === 'memory:reflect-prepare' || command === 'memory-reflect-prepare') {
       result = await runMemoryReflectPrepare({ args, options, logger: commandLogger });
     } else if (command === 'memory:reflect-commit' || command === 'memory-reflect-commit') {

package/src/commands/context-health.js

@@ -84,6 +84,34 @@ async function runContextHealth({ args, options = {}, logger }) {
     } catch { /* skip unreadable files */ }
   }
 
+  // bootstrap/*.md is the per-activation memory layer: dev/qa/architect/deyvin
+  // read it on every session start, so it dominates the real activation cost.
+  // It lives in a subdir, so the top-level scan above missed it entirely —
+  // include it here so the heaviest layer is visible, not hidden (P0 of the
+  // agent-loading-contract). Backward-compatible: no bootstrap/ dir → no change.
+  const bootstrapDir = path.join(contextDir, 'bootstrap');
+  let bootstrapFiles = [];
+  try {
+    // Exclude *-archive.md: cold storage is never loaded at activation, so
+    // counting it would inflate the report and mislabel intended bulk as CRITICAL.
+    bootstrapFiles = (await fs.readdir(bootstrapDir))
+      .filter((f) => f.endsWith('.md') && !f.endsWith('-archive.md'));
+  } catch { /* no bootstrap dir — pre-Living-Memory projects */ }
+  for (const file of bootstrapFiles) {
+    try {
+      const content = await fs.readFile(path.join(bootstrapDir, file), 'utf8');
+      const tokens = estimateTokens(content);
+      totalTokens += tokens;
+      report.push({
+        file: `bootstrap/${file}`,
+        sizeBytes: content.length,
+        tokens,
+        heavy: tokens > HEAVY_TOKEN_THRESHOLD,
+        critical: tokens > CRITICAL_TOKEN_THRESHOLD
+      });
+    } catch { /* skip unreadable files */ }
+  }
+
   report.sort((a, b) => b.tokens - a.tokens);
 
   const doneFeatures = await loadFeatureStatuses(contextDir);
@@ -150,8 +178,13 @@ async function runContextHealth({ args, options = {}, logger }) {
     for (const r of heavyFiles) {
       const label = r.critical ? 'CRITICAL' : 'heavy';
       logger.log(`⚠  ${r.file} is ${label} (${formatBytes(r.sizeBytes)}). Consider:`);
-      logger.log(`   → Run: aioson context:pack . --scope=<feature>`);
-      logger.log(`     Creates a scoped context for a specific feature`);
+      if (r.file === 'bootstrap/current-state.md') {
+        logger.log(`   → Run: aioson memory:trim . --dry-run`);
+        logger.log(`     Archives old log entries out of the hot bootstrap (every agent reads this at activation)`);
+      } else {
+        logger.log(`   → Run: aioson context:pack . --scope=<feature>`);
+        logger.log(`     Creates a scoped context for a specific feature`);
+      }
     }
     logger.log('');
   }

package/src/commands/feature-close.js

@@ -25,6 +25,12 @@ const { loadConfig } = require('../sub-task-engine');
 const { runDistillation, readFeatureClassification } = require('../learning-loop-engine');
 const { openRuntimeDb } = require('../runtime-store');
 const { runNotify } = require('./notify');
+const { splitCurrentState, buildArchiveContent, parseActiveSlugs } = require('../current-state-trim');
+
+// P0 agent-loading-contract: a feature closing is the natural cadence to roll
+// aged-out current-state.md entries into the cold archive. Conservative window
+// (gentle, automatic) — manual `memory:trim --keep=<N>` can trim harder.
+const AUTO_CLOSE_KEEP = 25;
 
 function nowDate() {
   return new Date().toISOString().slice(0, 10);
@@ -531,6 +537,36 @@ async function runFeatureClose({ args, options = {}, logger }) {
     updates.push('distill: skipped (--no-distill flag)');
   }
 
+  // Auto-rollup bootstrap/current-state.md (P0 agent-loading-contract). The
+  // just-closed slug is already `done` in features.md, so it no longer counts as
+  // an active-slug exemption — its aged entries become eligible. Best-effort and
+  // non-blocking: a failure here must never break the closure. Opt out: --no-trim.
+  // SECURITY (TS-LC-02): the trim hook calls the engine directly, bypassing the
+  // AIOSON_RUNTIME_HOOK guard that memory:trim enforces. Honor that guard here
+  // too, so a tier-2 memory mutation never fires inside a hook/automation context.
+  const skipTrim = options['no-trim'] === true || options.trim === false
+    || process.env.AIOSON_RUNTIME_HOOK === '1';
+  if (verdict === 'PASS' && !skipTrim) {
+    try {
+      const csPath = path.join(targetDir, '.aioson/context/bootstrap/current-state.md');
+      const csContent = await readFileSafe(csPath);
+      if (csContent) {
+        const activeSlugs = parseActiveSlugs((await readFileSafe(path.join(targetDir, '.aioson/context/features.md'))) || '');
+        const split = splitCurrentState(csContent, { keep: AUTO_CLOSE_KEEP, activeSlugs });
+        if (split.ok && split.archivedEntries.length > 0) {
+          const archPath = path.join(targetDir, '.aioson/context/bootstrap/current-state-archive.md');
+          const eol = /\r\n/.test(csContent) ? '\r\n' : '\n';
+          const existingArchive = (await readFileSafe(archPath)) || '';
+          await fs.writeFile(archPath, buildArchiveContent(existingArchive, split.archivedEntries, nowDate(), eol), 'utf8');
+          await fs.writeFile(csPath, split.hotContent, 'utf8');
+          updates.push(`trim: archived ${split.archivedEntries.length} aged current-state entries (kept ${split.stats.kept})`);
+        }
+      }
+    } catch (err) {
+      updates.push(`trim: hook error (${(err && err.message) || err})`);
+    }
+  }
+
   const result = {
     ok: true,
     feature: slug,

package/src/commands/memory-archive.js

@@ -1,193 +1,193 @@
-'use strict';
-
-/**
- * aioson memory:archive --id=<rule|learning|brain>:<slug> --reason="<text>" [--dry-run] [--json]
- *
- * Tier-2 human-actioned command (PMD-4 / Article VII / BR-ALL-01). Moves a
- * curated artifact to `_archived/{YYYY-MM-DD}/` and records the transition in
- * `evolution_log` using the validity-window pattern (BR-ALL-02 append-only):
- *  - supersedes the prior active entry (sets `end_at`)
- *  - inserts a new `event_type='archived'` row
- *  - for learnings: also flips `project_learnings.status` to 'archived'
- *
- * Refuses to run when `process.env.AIOSON_RUNTIME_HOOK === '1'` (BR-ALL-01:
- * hook code paths are never permitted to archive — only direct invocation by
- * a human).
- *
- * Emits `aioson notify --level=warn` BEFORE mutating disk or DB (BR-ALL-06).
- */
-
-const path = require('node:path');
-const { openRuntimeDb } = require('../runtime-store');
-const { runNotify } = require('./notify');
-const {
-  parseTargetId,
-  normalizeKind,
-  archiveTarget,
-  TARGET_TYPES
-} = require('../learning-loop-archive');
-
-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';
-}
-
-async function runMemoryArchive({ 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 log = (msg) => { if (logger && typeof logger.log === 'function') logger.log(msg); };
-
-  if (isHookContext()) {
-    const msg = tFn(t, 'memory_archive.hook_blocked')
-      || 'memory:archive cannot be invoked from a runtime hook (BR-ALL-01: tier-2 requires human action).';
-    if (wantJson) return { ok: false, reason: 'hook_blocked' };
-    log(msg);
-    return { ok: false, reason: 'hook_blocked' };
-  }
-
-  const rawId = options.id || options.target || '';
-  const reason = options.reason ? String(options.reason).trim() : '';
-
-  if (!rawId) {
-    const msg = tFn(t, 'memory_archive.id_required')
-      || 'memory:archive requires --id=<rule|learning|brain>:<slug>.';
-    if (wantJson) return { ok: false, reason: 'missing_id' };
-    log(msg);
-    return { ok: false, reason: 'missing_id' };
-  }
-  if (!reason) {
-    const msg = tFn(t, 'memory_archive.reason_required')
-      || 'memory:archive requires --reason="<text>".';
-    if (wantJson) return { ok: false, reason: 'missing_reason' };
-    log(msg);
-    return { ok: false, reason: 'missing_reason' };
-  }
-
-  const parsed = parseTargetId(rawId);
-  const kind = normalizeKind(parsed.kind);
-  if (!kind || !TARGET_TYPES.has(kind)) {
-    const msg = tFn(t, 'memory_archive.invalid_id', { value: rawId })
-      || `memory:archive invalid --id value: "${rawId}". Expected rule|learning|brain:<slug>.`;
-    if (wantJson) return { ok: false, reason: 'invalid_id', value: rawId };
-    log(msg);
-    return { ok: false, reason: 'invalid_id' };
-  }
-  if (!parsed.slug) {
-    const msg = tFn(t, 'memory_archive.invalid_id', { value: rawId })
-      || `memory:archive invalid --id value: "${rawId}". Missing slug after ":".`;
-    if (wantJson) return { ok: false, reason: 'invalid_id', value: rawId };
-    log(msg);
-    return { ok: false, reason: 'invalid_id' };
-  }
-
-  // BR-ALL-06: emit tier-2 notify BEFORE any mutation (defense in depth).
-  // notify.runNotify returns { ok, exitCode } — non-zero aborts.
-  const notifyMessage = tFn(t, 'memory_archive.notify_template', { kind, slug: parsed.slug, reason })
-    || `archiving ${kind} "${parsed.slug}": ${reason}`;
-  let notifyResult;
-  try {
-    notifyResult = await runNotify({
-      args: [targetDir],
-      options: {
-        level: 'warn',
-        topic: 'memory',
-        message: notifyMessage,
-        agent: 'memory-archive',
-        json: wantJson ? true : undefined
-      },
-      logger: logger || { log: () => {} }
-    });
-  } catch (err) {
-    if (wantJson) return { ok: false, reason: 'notify_failed', error: String(err && err.message || err) };
-    log(`memory:archive notify failed: ${err && err.message ? err.message : err}`);
-    return { ok: false, reason: 'notify_failed' };
-  }
-  if (notifyResult && notifyResult.ok === false) {
-    if (wantJson) return { ok: false, reason: 'notify_blocked', exitCode: notifyResult.exitCode };
-    log('memory:archive aborted: tier-2 notify returned non-zero exit code.');
-    return { ok: false, reason: 'notify_blocked' };
-  }
-
-  let dbHandle;
-  try {
-    dbHandle = await openRuntimeDb(targetDir);
-  } catch (err) {
-    if (wantJson) return { ok: false, reason: 'runtime_db_unavailable', error: String(err && err.message || err) };
-    log(`memory:archive runtime db unavailable: ${err && err.message ? err.message : err}`);
-    return { ok: false, reason: 'runtime_db_unavailable' };
-  }
-
-  const { db } = dbHandle;
-  let outcome;
-  try {
-    outcome = archiveTarget(db, {
-      targetDir,
-      kind,
-      slug: parsed.slug,
-      reason,
-      actor: 'human',
-      featureSlug: options.feature ? String(options.feature).trim() : null,
-      dryRun
-    });
-  } finally {
-    db.close();
-  }
-
-  if (!outcome.ok) {
-    if (wantJson) return outcome;
-    if (outcome.reason === 'already_archived') {
-      const msg = tFn(t, 'memory_archive.already_archived', { path: outcome.archivedAt })
-        || `memory:archive: "${parsed.slug}" already archived (${outcome.archivedAt || 'unknown path'}). No-op.`;
-      log(msg);
-    } else if (outcome.reason === 'target_not_found') {
-      const msg = tFn(t, 'memory_archive.target_not_found', { kind, slug: parsed.slug })
-        || `memory:archive: ${kind} "${parsed.slug}" not found in active state.`;
-      log(msg);
-    } else {
-      log(`memory:archive failed: ${outcome.reason}${outcome.error ? ' — ' + outcome.error : ''}`);
-    }
-    return outcome;
-  }
-
-  if (wantJson) {
-    return {
-      ok: true,
-      dry_run: Boolean(outcome.dryRun),
-      kind,
-      slug: parsed.slug,
-      source_path: outcome.sourcePath,
-      dest_path: outcome.destPath,
-      archived_entry_id: outcome.archivedEntryId || null,
-      superseded_entry_id: outcome.supersededEntryId || null,
-      start_at: outcome.startAt || null
-    };
-  }
-
-  if (outcome.dryRun) {
-    const msg = tFn(t, 'memory_archive.dry_run_summary', {
-      kind,
-      slug: parsed.slug,
-      source: outcome.sourcePath || '(no source path)',
-      dest: outcome.destPath,
-      has_active: outcome.hasActiveEntry ? 'yes' : 'no'
-    }) || `memory:archive [dry-run]: would move ${outcome.sourcePath || kind + ':' + parsed.slug} → ${outcome.destPath} (active entry: ${outcome.hasActiveEntry ? 'yes' : 'no'}).`;
-    log(msg);
-  } else {
-    const msg = tFn(t, 'memory_archive.archived_success', {
-      kind,
-      slug: parsed.slug,
-      dest: outcome.destPath
-    }) || `memory:archive ✓ ${kind} "${parsed.slug}" archived to ${outcome.destPath}.`;
-    log(msg);
-  }
-  return outcome;
-}
-
-module.exports = { runMemoryArchive };
+'use strict';
+
+/**
+ * aioson memory:archive --id=<rule|learning|brain>:<slug> --reason="<text>" [--dry-run] [--json]
+ *
+ * Tier-2 human-actioned command (PMD-4 / Article VII / BR-ALL-01). Moves a
+ * curated artifact to `_archived/{YYYY-MM-DD}/` and records the transition in
+ * `evolution_log` using the validity-window pattern (BR-ALL-02 append-only):
+ *  - supersedes the prior active entry (sets `end_at`)
+ *  - inserts a new `event_type='archived'` row
+ *  - for learnings: also flips `project_learnings.status` to 'archived'
+ *
+ * Refuses to run when `process.env.AIOSON_RUNTIME_HOOK === '1'` (BR-ALL-01:
+ * hook code paths are never permitted to archive — only direct invocation by
+ * a human).
+ *
+ * Emits `aioson notify --level=warn` BEFORE mutating disk or DB (BR-ALL-06).
+ */
+
+const path = require('node:path');
+const { openRuntimeDb } = require('../runtime-store');
+const { runNotify } = require('./notify');
+const {
+  parseTargetId,
+  normalizeKind,
+  archiveTarget,
+  TARGET_TYPES
+} = require('../learning-loop-archive');
+
+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';
+}
+
+async function runMemoryArchive({ 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 log = (msg) => { if (logger && typeof logger.log === 'function') logger.log(msg); };
+
+  if (isHookContext()) {
+    const msg = tFn(t, 'cli.memory_archive.hook_blocked')
+      || 'memory:archive cannot be invoked from a runtime hook (BR-ALL-01: tier-2 requires human action).';
+    if (wantJson) return { ok: false, reason: 'hook_blocked' };
+    log(msg);
+    return { ok: false, reason: 'hook_blocked' };
+  }
+
+  const rawId = options.id || options.target || '';
+  const reason = options.reason ? String(options.reason).trim() : '';
+
+  if (!rawId) {
+    const msg = tFn(t, 'cli.memory_archive.id_required')
+      || 'memory:archive requires --id=<rule|learning|brain>:<slug>.';
+    if (wantJson) return { ok: false, reason: 'missing_id' };
+    log(msg);
+    return { ok: false, reason: 'missing_id' };
+  }
+  if (!reason) {
+    const msg = tFn(t, 'cli.memory_archive.reason_required')
+      || 'memory:archive requires --reason="<text>".';
+    if (wantJson) return { ok: false, reason: 'missing_reason' };
+    log(msg);
+    return { ok: false, reason: 'missing_reason' };
+  }
+
+  const parsed = parseTargetId(rawId);
+  const kind = normalizeKind(parsed.kind);
+  if (!kind || !TARGET_TYPES.has(kind)) {
+    const msg = tFn(t, 'cli.memory_archive.invalid_id', { value: rawId })
+      || `memory:archive invalid --id value: "${rawId}". Expected rule|learning|brain:<slug>.`;
+    if (wantJson) return { ok: false, reason: 'invalid_id', value: rawId };
+    log(msg);
+    return { ok: false, reason: 'invalid_id' };
+  }
+  if (!parsed.slug) {
+    const msg = tFn(t, 'cli.memory_archive.invalid_id', { value: rawId })
+      || `memory:archive invalid --id value: "${rawId}". Missing slug after ":".`;
+    if (wantJson) return { ok: false, reason: 'invalid_id', value: rawId };
+    log(msg);
+    return { ok: false, reason: 'invalid_id' };
+  }
+
+  // BR-ALL-06: emit tier-2 notify BEFORE any mutation (defense in depth).
+  // notify.runNotify returns { ok, exitCode } — non-zero aborts.
+  const notifyMessage = tFn(t, 'cli.memory_archive.notify_template', { kind, slug: parsed.slug, reason })
+    || `archiving ${kind} "${parsed.slug}": ${reason}`;
+  let notifyResult;
+  try {
+    notifyResult = await runNotify({
+      args: [targetDir],
+      options: {
+        level: 'warn',
+        topic: 'memory',
+        message: notifyMessage,
+        agent: 'memory-archive',
+        json: wantJson ? true : undefined
+      },
+      logger: logger || { log: () => {} }
+    });
+  } catch (err) {
+    if (wantJson) return { ok: false, reason: 'notify_failed', error: String(err && err.message || err) };
+    log(`memory:archive notify failed: ${err && err.message ? err.message : err}`);
+    return { ok: false, reason: 'notify_failed' };
+  }
+  if (notifyResult && notifyResult.ok === false) {
+    if (wantJson) return { ok: false, reason: 'notify_blocked', exitCode: notifyResult.exitCode };
+    log('memory:archive aborted: tier-2 notify returned non-zero exit code.');
+    return { ok: false, reason: 'notify_blocked' };
+  }
+
+  let dbHandle;
+  try {
+    dbHandle = await openRuntimeDb(targetDir);
+  } catch (err) {
+    if (wantJson) return { ok: false, reason: 'runtime_db_unavailable', error: String(err && err.message || err) };
+    log(`memory:archive runtime db unavailable: ${err && err.message ? err.message : err}`);
+    return { ok: false, reason: 'runtime_db_unavailable' };
+  }
+
+  const { db } = dbHandle;
+  let outcome;
+  try {
+    outcome = archiveTarget(db, {
+      targetDir,
+      kind,
+      slug: parsed.slug,
+      reason,
+      actor: 'human',
+      featureSlug: options.feature ? String(options.feature).trim() : null,
+      dryRun
+    });
+  } finally {
+    db.close();
+  }
+
+  if (!outcome.ok) {
+    if (wantJson) return outcome;
+    if (outcome.reason === 'already_archived') {
+      const msg = tFn(t, 'cli.memory_archive.already_archived', { path: outcome.archivedAt })
+        || `memory:archive: "${parsed.slug}" already archived (${outcome.archivedAt || 'unknown path'}). No-op.`;
+      log(msg);
+    } else if (outcome.reason === 'target_not_found') {
+      const msg = tFn(t, 'cli.memory_archive.target_not_found', { kind, slug: parsed.slug })
+        || `memory:archive: ${kind} "${parsed.slug}" not found in active state.`;
+      log(msg);
+    } else {
+      log(`memory:archive failed: ${outcome.reason}${outcome.error ? ' — ' + outcome.error : ''}`);
+    }
+    return outcome;
+  }
+
+  if (wantJson) {
+    return {
+      ok: true,
+      dry_run: Boolean(outcome.dryRun),
+      kind,
+      slug: parsed.slug,
+      source_path: outcome.sourcePath,
+      dest_path: outcome.destPath,
+      archived_entry_id: outcome.archivedEntryId || null,
+      superseded_entry_id: outcome.supersededEntryId || null,
+      start_at: outcome.startAt || null
+    };
+  }
+
+  if (outcome.dryRun) {
+    const msg = tFn(t, 'cli.memory_archive.dry_run_summary', {
+      kind,
+      slug: parsed.slug,
+      source: outcome.sourcePath || '(no source path)',
+      dest: outcome.destPath,
+      has_active: outcome.hasActiveEntry ? 'yes' : 'no'
+    }) || `memory:archive [dry-run]: would move ${outcome.sourcePath || kind + ':' + parsed.slug} → ${outcome.destPath} (active entry: ${outcome.hasActiveEntry ? 'yes' : 'no'}).`;
+    log(msg);
+  } else {
+    const msg = tFn(t, 'cli.memory_archive.archived_success', {
+      kind,
+      slug: parsed.slug,
+      dest: outcome.destPath
+    }) || `memory:archive ✓ ${kind} "${parsed.slug}" archived to ${outcome.destPath}.`;
+    log(msg);
+  }
+  return outcome;
+}
+
+module.exports = { runMemoryArchive };

package/src/commands/memory-reflect-commit.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// aioson memory:reflect-commit [.] --agent=<name> [--output=<path-to-json>] [--json]
+// aioson memory:reflect-commit [.] --agent=<name> [--output=<path-to-json>] [--json] [--dry-run]
 //
 // Reads the reflect manifest written by memory:reflect-prepare, accepts the
 // agent's reflected output (as a JSON map of relative path → new content),
@@ -63,13 +63,14 @@ async function emitEvent(targetDir, agent, type, message, payload) {
 async function runMemoryReflectCommit({ args, options = {}, logger }) {
   const targetDir = path.resolve(process.cwd(), args?.[0] || '.');
   const agent = String(options.agent || '').trim() || 'unknown';
+  const dryRun = Boolean(options['dry-run'] || options.dryRun);
 
   const manifestPath = path.join(targetDir, REFLECT_PROMPT_RELATIVE);
   let manifest;
   try {
     manifest = await readJsonFile(manifestPath);
   } catch {
-    const message = `manifest not found at ${path.relative(targetDir, manifestPath)} — run memory:reflect-prepare first`;
+    const message = `manifest not found at ${path.relative(targetDir, manifestPath)} — it may have been consumed by a previous successful reflect-commit; run memory:reflect-prepare to generate a new one`;
     if (!options.json) logger.log(`✗ ${message}`);
     return { ok: false, error: 'missing_manifest', message };
   }
@@ -102,9 +103,11 @@ async function runMemoryReflectCommit({ args, options = {}, logger }) {
   // verify that every resolved absolute path stays under the project's
   // bootstrap directory. validate() already rejects absolute paths and
   // `..` segments, but this is the second wall in case the manifest's
-  // allowed_paths is ever extended beyond bootstrap/.
+  // allowed_paths is ever extended beyond bootstrap/. Run this for BOTH
+  // dry-run and real commits so a dry-run validates exactly what a real
+  // commit would do.
   const bootstrapRoot = path.resolve(targetDir, '.aioson/context/bootstrap');
-  const written = [];
+  const planned = [];
   for (const [relPath, content] of Object.entries(files)) {
     const absPath = path.resolve(targetDir, relPath);
     if (!absPath.startsWith(bootstrapRoot + path.sep) && absPath !== bootstrapRoot) {
@@ -116,6 +119,27 @@ async function runMemoryReflectCommit({ args, options = {}, logger }) {
       });
       return { ok: false, error: 'path_escape', message: msg };
     }
+    planned.push({ relPath, absPath, content });
+  }
+
+  // --dry-run: validation + path containment already passed. Report what WOULD
+  // be written and stop — no disk writes, and crucially the manifest is NOT
+  // consumed, so a real commit can still follow. A dry-run must never mutate
+  // state (this is the bug fix: previously --dry-run was ignored and ran the
+  // full destructive commit).
+  if (dryRun) {
+    const wouldWrite = planned.map((p) => p.relPath);
+    if (!options.json) {
+      logger.log('• reflect-commit DRY RUN — no files written, manifest preserved');
+      for (const w of wouldWrite) logger.log(`  - would write: ${w}`);
+    }
+    await emitEvent(targetDir, agent, 'memory_reflect_dry_run',
+      `dry-run validated ${wouldWrite.length} file(s)`, { would_write: wouldWrite });
+    return { ok: true, dryRun: true, would_write: wouldWrite };
+  }
+
+  const written = [];
+  for (const { relPath, absPath, content } of planned) {
     // SF-project-22: scrub zero-width / bidi / HTML-comment injection carriers
     // from the LLM-authored content before it lands in bootstrap. Path
     // containment is already enforced above; this is the content layer of the