@jaimevalasek/aioson 1.9.3 → 1.17.2

package/src/commands/op-capture.js

@@ -0,0 +1,146 @@
+'use strict';
+
+/**
+ * aioson op:capture — record a standing-decision signal (Phase 2, v1.13.0).
+ *
+ * Usage:
+ *   aioson op:capture --signal=authorization --quote="..." --proposal="..." --source-agent=dev
+ *
+ * Flow (architecture-operator-memory.md § Phase 2 capture pipeline):
+ *   1. Validate --signal in {authorization, exclusion, correction, confirmation}
+ *   2. Resolve identity (Phase 1)
+ *   3. deriveSlug(--proposal) — deterministic kebab + truncate
+ *   4. Check proposals/{slug}.md:
+ *      - absent: write proposal with detected_count=1, exit 0 silent
+ *      - present: detected_count++
+ *        - count >= 2: promoteProposal (atomic) + stdout audit line
+ *        - count < 2: update proposal, exit 0 silent
+ *   5. Telemetry op_capture before file write
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveIdentity } = require('../operator-memory/identity');
+const { ensureStorageTree, recordIdentityActivity, openIndexDb, getStorageRoot } = require('../operator-memory/storage');
+const { deriveSlug, fingerprintProposal } = require('../operator-memory/slug');
+const { captureSignal, readProposal, VALID_SIGNAL_TYPES } = require('../operator-memory/proposal');
+const { promoteProposal } = require('../operator-memory/decision');
+const { emitDossierEvent } = require('../lib/dossier-telemetry');
+
+const PROMOTION_THRESHOLD = 2;
+
+function existsCheckFactory(identity) {
+  return (slug) => {
+    const existing = readProposal(identity, slug);
+    if (!existing) return null;
+    return existing.proposal_fingerprint || fingerprintProposal(existing.proposal || '');
+  };
+}
+
+async function runOpCapture({ args = [], options = {}, logger }) {
+  const targetDir = process.cwd();
+  const helpRequested = options.help === true || args.includes('--help') || args.includes('-h');
+  if (helpRequested) {
+    const msg = `op:capture — capture a standing-decision signal into the proposals queue.
+Usage:
+  aioson op:capture --signal=<type> --quote=<verbatim> --proposal=<paraphrase> --source-agent=<agent>
+Signal types: ${VALID_SIGNAL_TYPES.join(', ')}
+First detection writes to proposals/{slug}.md. Second detection promotes to decisions/{slug}.md atomically.`;
+    if (options.json) return { ok: true, help: true };
+    if (logger) logger.log(msg);
+    return { ok: true };
+  }
+
+  const signal = options.signal;
+  const quote = options.quote;
+  const proposal = options.proposal;
+  const sourceAgent = options['source-agent'] || options.sourceAgent || 'unknown';
+
+  if (!signal || !proposal) {
+    const err = `op:capture — required: --signal=<type> --proposal=<paraphrase>. Got signal=${signal}, proposal=${proposal ? 'present' : 'missing'}.`;
+    if (options.json) return { ok: false, error: err };
+    if (logger && logger.error) logger.error(err);
+    return { ok: false, exitCode: 1, error: err };
+  }
+  if (!VALID_SIGNAL_TYPES.includes(signal)) {
+    const err = `op:capture — invalid --signal='${signal}'. Must be one of: ${VALID_SIGNAL_TYPES.join(', ')}.`;
+    if (options.json) return { ok: false, error: err };
+    if (logger && logger.error) logger.error(err);
+    return { ok: false, exitCode: 1, error: err };
+  }
+
+  const resolved = resolveIdentity();
+  ensureStorageTree(resolved.identity);
+  const db = openIndexDb();
+  try {
+    recordIdentityActivity(db, { identity: resolved.identity, source: resolved.source });
+  } finally {
+    db.close();
+  }
+
+  const slug = deriveSlug(proposal, existsCheckFactory(resolved.identity));
+
+  await emitDossierEvent(targetDir, {
+    agent: 'op-capture',
+    type: 'op_capture',
+    summary: `${signal}: ${slug}`,
+    meta: { identity_prefix: resolved.identity.slice(0, 8), signal_type: signal, slug, source_agent: sourceAgent }
+  });
+
+  let result;
+  try {
+    result = captureSignal({
+      identity: resolved.identity,
+      slug,
+      signal_type: signal,
+      quote,
+      proposal,
+      source_agent: sourceAgent
+    });
+  } catch (err) {
+    const errMsg = `op:capture failed: ${err.message}`;
+    if (options.json) return { ok: false, error: errMsg };
+    if (logger && logger.error) logger.error(errMsg);
+    return { ok: false, exitCode: 1, error: errMsg };
+  }
+
+  const count = result.proposal.detected_count;
+
+  if (count >= PROMOTION_THRESHOLD) {
+    // Promote to decision
+    let decision;
+    try {
+      decision = promoteProposal({ identity: resolved.identity, proposal: result.proposal });
+    } catch (err) {
+      const errMsg = `op:capture promotion failed: ${err.message}`;
+      if (options.json) return { ok: false, error: errMsg };
+      if (logger && logger.error) logger.error(errMsg);
+      return { ok: false, exitCode: 1, error: errMsg };
+    }
+
+    await emitDossierEvent(targetDir, {
+      agent: 'op-capture',
+      type: 'op_promote',
+      summary: `promoted ${slug} (${signal})`,
+      meta: { identity_prefix: resolved.identity.slice(0, 8), slug, signal_type: signal, category: decision.category }
+    });
+
+    const auditLine = `✔ Memory: '${proposal}'. aioson op:forget ${slug} p/ desfazer.`;
+    if (options.json) {
+      return { ok: true, promoted: true, slug, identity: resolved.identity, category: decision.category };
+    }
+    if (logger) logger.log(auditLine);
+    return { ok: true, promoted: true, slug };
+  }
+
+  // First detection (or below threshold) — silent
+  if (options.json) {
+    return { ok: true, promoted: false, slug, detected_count: count, identity: resolved.identity };
+  }
+  return { ok: true, promoted: false, slug, detected_count: count };
+}
+
+module.exports = {
+  runOpCapture,
+  PROMOTION_THRESHOLD
+};

package/src/commands/op-forget.js

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * aioson op:forget <slug> — soft-delete a decision or proposal to history/.
+ * Phase 2 (v1.13.0).
+ */
+
+const path = require('node:path');
+const { resolveIdentity } = require('../operator-memory/identity');
+const { ensureStorageTree } = require('../operator-memory/storage');
+const { forgetEntry } = require('../operator-memory/decision');
+const { emitDossierEvent } = require('../lib/dossier-telemetry');
+
+async function runOpForget({ args = [], options = {}, logger }) {
+  const targetDir = process.cwd();
+  const positional = (args || []).filter((a) => typeof a === 'string' && !a.startsWith('-') && a !== '.');
+  const slug = positional[0];
+
+  if (options.help === true || args.includes('--help') || args.includes('-h')) {
+    if (logger) logger.log('op:forget <slug> — soft-delete a decision or proposal to history/. Idempotent.');
+    return { ok: true };
+  }
+
+  if (!slug) {
+    const err = 'op:forget — required argument: <slug>. Usage: aioson op:forget <slug>';
+    if (options.json) return { ok: false, error: err };
+    if (logger && logger.error) logger.error(err);
+    return { ok: false, exitCode: 1, error: err };
+  }
+
+  const resolved = resolveIdentity();
+  ensureStorageTree(resolved.identity);
+  const result = forgetEntry(resolved.identity, slug);
+
+  await emitDossierEvent(targetDir, {
+    agent: 'op-forget',
+    type: 'op_forget',
+    summary: `${result.mode}: ${slug}`,
+    meta: { identity_prefix: resolved.identity.slice(0, 8), slug, mode: result.mode }
+  });
+
+  if (options.json) {
+    return { ok: true, mode: result.mode, archived: result.archivedPath };
+  }
+  if (result.mode === 'noop') {
+    if (logger) logger.log(`op:forget — '${slug}' not found (idempotent no-op).`);
+  } else {
+    const archivedRel = result.archivedPath ? path.basename(result.archivedPath) : null;
+    if (logger) logger.log(`op:forget — '${slug}' archived as history/${archivedRel} (${result.mode}).`);
+  }
+  return { ok: true, mode: result.mode };
+}
+
+module.exports = { runOpForget };

package/src/commands/op-identity.js

@@ -0,0 +1,145 @@
+'use strict';
+
+/**
+ * aioson op:identity — operator-memory identity resolution (Phase 1, v1.12.0).
+ *
+ * Subcommands:
+ *   show (default) — resolve current identity + emit summary
+ *   set <id>       — Phase 1 stub. Full impl in Phase 5; prints guidance to use env override.
+ *
+ * Usage:
+ *   aioson op:identity show
+ *   aioson op:identity show --json
+ *   aioson op:identity set ci-bot-shared       (Phase 1: prints guidance only)
+ *   AIOSON_OPERATOR_ID=ci-bot aioson op:identity show
+ */
+
+const {
+  resolveIdentity,
+  validateOverride,
+  OVERRIDE_REGEX
+} = require('../operator-memory/identity');
+const {
+  ensureStorageTree,
+  openIndexDb,
+  recordIdentityActivity,
+  getStorageRoot
+} = require('../operator-memory/storage');
+const { emitDossierEvent } = require('../lib/dossier-telemetry');
+
+function parseSubcommand(args) {
+  // parser.js strips the command name, so args contains positional args only.
+  // Filter out a leading '.' (legacy convention from other AIOSON commands that
+  // take a project path; op:* commands are machine-local so '.' is ignored).
+  const positional = (args || []).filter((a) => typeof a === 'string' && !a.startsWith('-') && a !== '.');
+  const sub = positional[0] || 'show';
+  const setValue = sub === 'set' ? positional[1] : null;
+  return { sub, setValue };
+}
+
+async function runOpIdentity({ args = [], options = {}, logger }) {
+  const targetDir = process.cwd();
+  const { sub, setValue } = parseSubcommand(args);
+
+  if (sub !== 'show' && sub !== 'set') {
+    const err = `op:identity — unknown subcommand '${sub}'. Use: show | set <id>`;
+    if (options.json) return { ok: false, error: err };
+    if (logger) logger.error(err);
+    return { ok: false, error: err, exitCode: 1 };
+  }
+
+  if (sub === 'set') {
+    if (!setValue) {
+      const err = `op:identity set — missing <id>. Usage: aioson op:identity set <id>`;
+      if (options.json) return { ok: false, error: err };
+      if (logger) logger.error(err);
+      return { ok: false, error: err, exitCode: 1 };
+    }
+    const validation = validateOverride(setValue);
+    if (!validation.ok) {
+      const err = `op:identity set — '${setValue}' invalid (${validation.reason}; expected ${OVERRIDE_REGEX}, no reserved prefix _* or aioson-*).`;
+      if (options.json) return { ok: false, error: err };
+      if (logger) logger.error(err);
+      return { ok: false, error: err, exitCode: 1 };
+    }
+    // Phase 5 full impl: process.env mutation works only within this Node process.
+    // For shell-session persistence the user must export AIOSON_OPERATOR_ID. This
+    // command initializes the identity storage tree for the new id so subsequent
+    // op:* invocations in the same process see a ready identity.
+    process.env.AIOSON_OPERATOR_ID = setValue;
+    ensureStorageTree(setValue);
+    let db;
+    try {
+      db = openIndexDb();
+      recordIdentityActivity(db, { identity: setValue, source: 'override' });
+    } finally {
+      if (db) { try { db.close(); } catch { /* ignore */ } }
+    }
+    const msg = `op:identity set — process env AIOSON_OPERATOR_ID=${setValue} (this process only). Persist via shell:\n  export AIOSON_OPERATOR_ID=${setValue}\n  # or .bashrc / equivalent`;
+    if (options.json) {
+      return {
+        ok: true,
+        identity: setValue,
+        source: 'override',
+        storage_root: getStorageRoot(setValue),
+        persistence: 'process_env_only',
+        shell_export: `export AIOSON_OPERATOR_ID=${setValue}`
+      };
+    }
+    if (logger) logger.log(msg);
+    return { ok: true };
+  }
+
+  // sub === 'show'
+  const resolved = resolveIdentity();
+  ensureStorageTree(resolved.identity);
+
+  let db;
+  try {
+    db = openIndexDb();
+    recordIdentityActivity(db, { identity: resolved.identity, source: resolved.source });
+  } finally {
+    if (db) {
+      try { db.close(); } catch { /* swallow */ }
+    }
+  }
+
+  if (resolved.source === 'anonymous-fallback') {
+    await emitDossierEvent(targetDir, {
+      agent: 'op-identity',
+      type: 'op_identity_unresolved',
+      summary: 'git email unavailable; using _anonymous bucket',
+      meta: { identity: resolved.identity, source: resolved.source }
+    });
+  }
+
+  const storageRoot = getStorageRoot(resolved.identity);
+
+  const result = {
+    ok: true,
+    identity: resolved.identity,
+    source: resolved.source,
+    storage_root: storageRoot,
+    warning: resolved.warning
+  };
+
+  if (options.json) return result;
+
+  if (resolved.warning && logger && logger.error) {
+    logger.error(`⚠ ${resolved.warning}`);
+  }
+  const sourceLabel = resolved.source === 'override'
+    ? '(override via AIOSON_OPERATOR_ID)'
+    : resolved.source === 'anonymous-fallback'
+      ? '(anonymous fallback — set git config user.email to scope memory)'
+      : '(git-email-hash)';
+  if (logger) {
+    logger.log(`op:identity — ${resolved.identity} ${sourceLabel}`);
+    logger.log(`storage_root: ${storageRoot}`);
+  }
+  return result;
+}
+
+module.exports = {
+  runOpIdentity
+};

package/src/commands/op-list.js

@@ -0,0 +1,105 @@
+'use strict';
+
+/**
+ * aioson op:list — list active decisions (Phase 3, v1.14.0).
+ *
+ * Output formats:
+ *   --format=table (default): human-readable columns
+ *   --format=json: machine-readable JSON
+ *
+ * Flags:
+ *   --proposals          show pending proposals instead of decisions
+ *   --include-archived   include MEMORY-archive.md entries
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveIdentity } = require('../operator-memory/identity');
+const { ensureStorageTree, getStorageRoot } = require('../operator-memory/storage');
+const { loadMemoryIndex } = require('../operator-memory/index-md');
+const { readDecision } = require('../operator-memory/decision');
+
+async function runOpList({ args = [], options = {}, logger }) {
+  if (options.help === true || args.includes('--help') || args.includes('-h')) {
+    if (logger) logger.log('op:list [--proposals] [--include-archived] [--format=table|json] — list active decisions.');
+    return { ok: true };
+  }
+
+  const format = options.format || 'table';
+  const showProposals = Boolean(options.proposals);
+  const includeArchived = Boolean(options['include-archived']);
+
+  const resolved = resolveIdentity();
+  ensureStorageTree(resolved.identity);
+  const root = getStorageRoot(resolved.identity);
+
+  let items = [];
+  if (showProposals) {
+    const proposalsDir = path.join(root, 'proposals');
+    if (fs.existsSync(proposalsDir)) {
+      const files = fs.readdirSync(proposalsDir).filter((f) => f.endsWith('.md'));
+      const { readProposal } = require('../operator-memory/proposal');
+      for (const f of files) {
+        const slug = f.slice(0, -3);
+        const p = readProposal(resolved.identity, slug);
+        if (p) items.push({ slug, ...p });
+      }
+    }
+  } else {
+    const active = loadMemoryIndex(resolved.identity, 'active');
+    if (active && active.entries) {
+      // Enrich with full decision data so --format=json carries category + body summary
+      for (const entry of active.entries) {
+        const d = readDecision(resolved.identity, entry.slug);
+        if (d) items.push({ slug: entry.slug, title: entry.title, ...d });
+      }
+    }
+    if (includeArchived) {
+      const archive = loadMemoryIndex(resolved.identity, 'archive');
+      if (archive && archive.entries) {
+        for (const entry of archive.entries) {
+          const d = readDecision(resolved.identity, entry.slug);
+          if (d) items.push({ slug: entry.slug, title: entry.title, tier: 'archive', ...d });
+        }
+      }
+    }
+  }
+
+  if (format === 'json' || options.json) {
+    const result = {
+      ok: true,
+      identity: resolved.identity,
+      identity_source: resolved.source,
+      tier: showProposals ? 'proposals' : (includeArchived ? 'active+archive' : 'active'),
+      count: items.length,
+      items
+    };
+    if (options.json) {
+      return result;
+    }
+    if (logger) logger.log(JSON.stringify(result, null, 2));
+    return result;
+  }
+
+  if (items.length === 0) {
+    const msg = showProposals
+      ? `op:list — no pending proposals for identity ${resolved.identity}.`
+      : `op:list — no decisions for identity ${resolved.identity}.`;
+    if (logger) logger.log(msg);
+    return { ok: true, count: 0 };
+  }
+
+  if (logger) {
+    logger.log(`op:list — ${items.length} ${showProposals ? 'proposal(s)' : 'decision(s)'} for ${resolved.identity}:`);
+    logger.log('');
+    for (const item of items) {
+      const dateOnly = String(item.last_reinforced || item.last_detected || '').slice(0, 10);
+      const category = item.category || (showProposals ? 'proposal' : 'default');
+      const tier = item.tier === 'archive' ? '[archive] ' : '';
+      logger.log(`  ${tier}${item.slug.padEnd(40)}  ${item.signal_type.padEnd(14)}  ${category.padEnd(10)}  ${dateOnly}`);
+    }
+  }
+  return { ok: true, count: items.length };
+}
+
+module.exports = { runOpList };

package/src/commands/op-migrate.js

@@ -0,0 +1,158 @@
+'use strict';
+
+/**
+ * aioson op:migrate — explicit one-shot migration from `.aioson/context/user-profile.md`
+ * (Phase 5, v1.16.0). PMD-10: deprecation tied to feature.md status, not version.
+ *
+ * Idempotent: re-runs after first successful migration skip silently (checks
+ * deprecated_by frontmatter field on user-profile.md).
+ *
+ * Field mapping (known 8 dimensions, conservative subset):
+ *   autonomy_preference   → category=identity, signal_type=authorization
+ *   communication_style   → category=identity, signal_type=authorization
+ *   feedback_density      → category=identity, signal_type=authorization
+ *   correction_tolerance  → category=identity, signal_type=correction
+ *   tool_authorization    → category=tooling, signal_type=authorization
+ *   workflow_strictness   → category=autonomy, signal_type=authorization
+ *   ui_style              → category=identity, signal_type=authorization
+ *   verbosity             → category=identity, signal_type=authorization
+ *
+ * Unknown fields in user-profile.md are preserved (not migrated).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveIdentity } = require('../operator-memory/identity');
+const { ensureStorageTree } = require('../operator-memory/storage');
+const { captureSignal } = require('../operator-memory/proposal');
+const { readDecision, promoteProposal } = require('../operator-memory/decision');
+const { deriveSlug } = require('../operator-memory/slug');
+const { emitDossierEvent } = require('../lib/dossier-telemetry');
+
+const KNOWN_FIELDS = {
+  autonomy_preference: { category: 'identity', signal_type: 'authorization' },
+  communication_style: { category: 'identity', signal_type: 'authorization' },
+  feedback_density: { category: 'identity', signal_type: 'authorization' },
+  correction_tolerance: { category: 'identity', signal_type: 'correction' },
+  tool_authorization: { category: 'tooling', signal_type: 'authorization' },
+  workflow_strictness: { category: 'autonomy', signal_type: 'authorization' },
+  ui_style: { category: 'identity', signal_type: 'authorization' },
+  verbosity: { category: 'identity', signal_type: 'authorization' }
+};
+
+function parseUserProfileFrontmatter(content) {
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  const out = {};
+  for (const line of m[1].split('\n')) {
+    const fm = line.match(/^([a-z_]+):\s*(.*)$/);
+    if (fm) {
+      let v = fm[2].trim();
+      if (v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1);
+      if (v.startsWith("'") && v.endsWith("'")) v = v.slice(1, -1);
+      out[fm[1]] = v;
+    }
+  }
+  return out;
+}
+
+function rewriteUserProfileWithDeprecation(filePath, fm) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return false;
+  if (fm.deprecated_by === 'operator-memory') return false; // already deprecated
+  const updatedFm = { ...fm, deprecated_by: 'operator-memory', deprecated_at: new Date().toISOString() };
+  const fmLines = Object.entries(updatedFm).map(([k, v]) => `${k}: ${v}`);
+  const newContent = `---\n${fmLines.join('\n')}\n---\n${content.slice(m[0].length)}`;
+  const tmp = `${filePath}.tmp`;
+  fs.writeFileSync(tmp, newContent, 'utf8');
+  fs.renameSync(tmp, filePath);
+  return true;
+}
+
+async function runOpMigrate({ args = [], options = {}, logger }) {
+  const targetDir = process.cwd();
+  const profilePath = path.join(targetDir, '.aioson', 'context', 'user-profile.md');
+
+  if (options.help === true || args.includes('--help') || args.includes('-h')) {
+    if (logger) logger.log('op:migrate — explicit one-shot import from .aioson/context/user-profile.md into operator-memory. Idempotent.');
+    return { ok: true };
+  }
+
+  if (!fs.existsSync(profilePath)) {
+    const msg = 'op:migrate — no .aioson/context/user-profile.md to migrate (skipped).';
+    if (options.json) return { ok: true, migrated: 0, skipped: 0, reason: 'no_user_profile' };
+    if (logger) logger.log(msg);
+    return { ok: true, migrated: 0 };
+  }
+
+  const content = fs.readFileSync(profilePath, 'utf8');
+  const fm = parseUserProfileFrontmatter(content);
+  if (!fm) {
+    if (options.json) return { ok: false, error: 'user-profile.md has no parseable frontmatter' };
+    if (logger && logger.error) logger.error('op:migrate — user-profile.md has no parseable frontmatter');
+    return { ok: false, exitCode: 1 };
+  }
+
+  if (fm.deprecated_by === 'operator-memory') {
+    const msg = 'op:migrate — user-profile.md already deprecated (idempotent skip).';
+    if (options.json) return { ok: true, migrated: 0, skipped: 0, reason: 'already_deprecated' };
+    if (logger) logger.log(msg);
+    return { ok: true, migrated: 0, idempotent: true };
+  }
+
+  const resolved = resolveIdentity();
+  ensureStorageTree(resolved.identity);
+
+  let migrated = 0;
+  let skipped = 0;
+  const results = [];
+
+  for (const [field, value] of Object.entries(fm)) {
+    if (!KNOWN_FIELDS[field]) continue; // unknown field — preserve in user-profile.md
+    if (!value || value === 'null' || value === '') { skipped += 1; continue; }
+    const config = KNOWN_FIELDS[field];
+    const proposalText = `${field}: ${value}`;
+    const slug = deriveSlug(proposalText);
+
+    const existing = readDecision(resolved.identity, slug);
+    if (existing) {
+      skipped += 1;
+      results.push({ field, slug, action: 'skipped_existing' });
+      continue;
+    }
+
+    // Capture + immediately promote (one-shot, skip 2x threshold)
+    const cap = captureSignal({
+      identity: resolved.identity,
+      slug,
+      signal_type: config.signal_type,
+      quote: `(migrated from user-profile.md: ${field})`,
+      proposal: proposalText,
+      source_agent: 'migrate'
+    });
+    promoteProposal({ identity: resolved.identity, proposal: { ...cap.proposal, detected_count: 2 } });
+    migrated += 1;
+    results.push({ field, slug, action: 'migrated', category: config.category });
+
+    await emitDossierEvent(targetDir, {
+      agent: 'op-migrate',
+      type: 'op_migrate',
+      summary: `migrated ${field} → ${slug}`,
+      meta: { identity_prefix: resolved.identity.slice(0, 8), field, slug, category: config.category }
+    });
+  }
+
+  rewriteUserProfileWithDeprecation(profilePath, fm);
+
+  if (options.json) {
+    return { ok: true, migrated, skipped, results, identity: resolved.identity };
+  }
+  if (logger) {
+    logger.log(`op:migrate — imported ${migrated} field(s) from user-profile.md (${skipped} skipped).`);
+    if (migrated > 0) logger.log('user-profile.md frontmatter marked deprecated_by: operator-memory');
+  }
+  return { ok: true, migrated, skipped };
+}
+
+module.exports = { runOpMigrate, KNOWN_FIELDS };

package/src/commands/op-promote.js

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * aioson op:promote <slug> — manually promote a proposal (skip 2x threshold).
+ * Phase 2 (v1.13.0).
+ */
+
+const { resolveIdentity } = require('../operator-memory/identity');
+const { ensureStorageTree } = require('../operator-memory/storage');
+const { readProposal } = require('../operator-memory/proposal');
+const { promoteProposal } = require('../operator-memory/decision');
+const { emitDossierEvent } = require('../lib/dossier-telemetry');
+
+async function runOpPromote({ args = [], options = {}, logger }) {
+  const targetDir = process.cwd();
+  const positional = (args || []).filter((a) => typeof a === 'string' && !a.startsWith('-') && a !== '.');
+  const slug = positional[0];
+
+  if (options.help === true || args.includes('--help') || args.includes('-h')) {
+    if (logger) logger.log('op:promote <slug> — manually promote a pending proposal to a decision.');
+    return { ok: true };
+  }
+
+  if (!slug) {
+    const err = 'op:promote — required argument: <slug>. Usage: aioson op:promote <slug>';
+    if (options.json) return { ok: false, error: err };
+    if (logger && logger.error) logger.error(err);
+    return { ok: false, exitCode: 1, error: err };
+  }
+
+  const resolved = resolveIdentity();
+  ensureStorageTree(resolved.identity);
+  const proposal = readProposal(resolved.identity, slug);
+  if (!proposal) {
+    const err = `op:promote — proposal '${slug}' not found.`;
+    if (options.json) return { ok: false, error: err };
+    if (logger && logger.error) logger.error(err);
+    return { ok: false, exitCode: 1, error: err };
+  }
+
+  let decision;
+  try {
+    decision = promoteProposal({ identity: resolved.identity, proposal });
+  } catch (err) {
+    const errMsg = `op:promote failed: ${err.message}`;
+    if (options.json) return { ok: false, error: errMsg };
+    if (logger && logger.error) logger.error(errMsg);
+    return { ok: false, exitCode: 1, error: errMsg };
+  }
+
+  await emitDossierEvent(targetDir, {
+    agent: 'op-promote',
+    type: 'op_promote',
+    summary: `manual promote ${slug}`,
+    meta: { identity_prefix: resolved.identity.slice(0, 8), slug, signal_type: decision.signal_type, category: decision.category, mode: 'manual' }
+  });
+
+  const auditLine = `✔ Memory: '${proposal.proposal}'. aioson op:forget ${slug} p/ desfazer.`;
+  if (options.json) {
+    return { ok: true, slug, identity: resolved.identity, category: decision.category };
+  }
+  if (logger) logger.log(auditLine);
+  return { ok: true, slug };
+}
+
+module.exports = { runOpPromote };