@jaimevalasek/aioson 1.9.2 → 1.16.0

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 };

package/src/commands/op-reinforce.js

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * aioson op:reinforce <slug> — update last_reinforced without signal capture.
+ * Phase 5 (v1.16.0). User-driven action when decay prompt fires.
+ */
+
+const fs = require('node:fs');
+const { resolveIdentity } = require('../operator-memory/identity');
+const { ensureStorageTree } = require('../operator-memory/storage');
+const { readDecision, decisionPath, serializeDecision } = require('../operator-memory/decision');
+const { regenerateIndex } = require('../operator-memory/index-md');
+const { emitDossierEvent } = require('../lib/dossier-telemetry');
+
+async function runOpReinforce({ 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:reinforce <slug> — refresh a decision\'s last_reinforced timestamp without re-capturing the signal.');
+    return { ok: true };
+  }
+
+  if (!slug) {
+    const err = 'op:reinforce — required argument: <slug>. Usage: aioson op:reinforce <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 decision = readDecision(resolved.identity, slug);
+  if (!decision) {
+    const err = `op:reinforce — decision '${slug}' not found for identity ${resolved.identity}.`;
+    if (options.json) return { ok: false, error: err };
+    if (logger && logger.error) logger.error(err);
+    return { ok: false, exitCode: 1, error: err };
+  }
+
+  const now = new Date().toISOString();
+  const previous = decision.last_reinforced;
+  const updated = {
+    ...decision,
+    slug,
+    last_reinforced: now,
+    reinforcement_count: Number(decision.reinforcement_count || 0) + 1
+  };
+  // serialize keeps quotes + body + frontmatter intact
+  const out = serializeDecision({ ...updated, body: decision.body, title: decision.body?.split('\n')[0]?.replace(/^# /, '') || slug });
+  const filePath = decisionPath(resolved.identity, slug);
+  const tmp = `${filePath}.tmp`;
+  fs.writeFileSync(tmp, out, 'utf8');
+  fs.renameSync(tmp, filePath);
+
+  try { regenerateIndex(resolved.identity); } catch { /* non-fatal */ }
+
+  await emitDossierEvent(targetDir, {
+    agent: 'op-reinforce',
+    type: 'op_reinforce',
+    summary: `reinforced ${slug}`,
+    meta: { identity_prefix: resolved.identity.slice(0, 8), slug, previous, now }
+  });
+
+  if (options.json) {
+    return { ok: true, slug, last_reinforced: now, previous, reinforcement_count: updated.reinforcement_count };
+  }
+  if (logger) logger.log(`op:reinforce — '${slug}' last_reinforced refreshed to ${now}.`);
+  return { ok: true, slug };
+}
+
+module.exports = { runOpReinforce };

package/src/commands/op-show.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * aioson op:show <slug> — print a single decision body + frontmatter (Phase 3, v1.14.0).
+ */
+
+const fs = require('node:fs');
+const { resolveIdentity } = require('../operator-memory/identity');
+const { ensureStorageTree } = require('../operator-memory/storage');
+const { readDecision, decisionPath } = require('../operator-memory/decision');
+const { readProposal } = require('../operator-memory/proposal');
+
+async function runOpShow({ args = [], options = {}, logger }) {
+  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:show <slug> — print a single decision (frontmatter + body). --json for structured output.');
+    return { ok: true };
+  }
+
+  if (!slug) {
+    const err = 'op:show — required argument: <slug>. Usage: aioson op:show <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 decision = readDecision(resolved.identity, slug);
+  if (decision) {
+    if (options.json) {
+      return { ok: true, kind: 'decision', identity: resolved.identity, slug, ...decision };
+    }
+    if (logger) {
+      const filePath = decisionPath(resolved.identity, slug);
+      const raw = fs.readFileSync(filePath, 'utf8');
+      logger.log(raw);
+    }
+    return { ok: true, kind: 'decision' };
+  }
+
+  const proposal = readProposal(resolved.identity, slug);
+  if (proposal) {
+    if (options.json) {
+      return { ok: true, kind: 'proposal', identity: resolved.identity, slug, ...proposal };
+    }
+    if (logger) {
+      logger.log(`# Proposal: ${slug}`);
+      logger.log('');
+      logger.log(`signal_type: ${proposal.signal_type}`);
+      logger.log(`detected_count: ${proposal.detected_count}`);
+      logger.log(`first_detected: ${proposal.first_detected}`);
+      logger.log(`last_detected: ${proposal.last_detected}`);
+      logger.log(`proposal: ${proposal.proposal}`);
+      logger.log('');
+      logger.log('## Quotes');
+      for (const q of (proposal.quotes || [])) logger.log(`- "${q}"`);
+    }
+    return { ok: true, kind: 'proposal' };
+  }
+
+  const err = `op:show — '${slug}' not found in decisions/ or proposals/ for identity ${resolved.identity}.`;
+  if (options.json) return { ok: false, error: err };
+  if (logger && logger.error) logger.error(err);
+  return { ok: false, exitCode: 1, error: err };
+}
+
+module.exports = { runOpShow };

package/src/commands/op-stubs.js

@@ -0,0 +1,67 @@
+'use strict';
+
+/**
+ * aioson op:* — Phase 1 stubs for commands shipped in later phases.
+ *
+ * Each stub emits a "Not yet implemented" stderr message + structured
+ * `op_command_stub` telemetry event, then exits non-zero. Replaced in
+ * Phases 2-5 with full implementations.
+ *
+ * AC-P1-07: six CLI commands respond with at least --help text; op:identity
+ * is fully functional in Phase 1; the other five are stubs until their
+ * respective phases ship.
+ */
+
+const { emitDossierEvent } = require('../lib/dossier-telemetry');
+
+const STUB_INFO = {
+  'op:capture':  { phase: 2, release: 'v1.13.0', summary: 'capture LLM-driven signal into proposals/ queue' },
+  'op:promote':  { phase: 2, release: 'v1.13.0', summary: 'manually promote a proposal to decisions/ (skip 2x threshold)' },
+  'op:forget':   { phase: 2, release: 'v1.13.0', summary: 'soft-delete a decision or proposal to history/' },
+  'op:list':     { phase: 3, release: 'v1.14.0', summary: 'list active decisions (and --include-archived)' },
+  'op:show':     { phase: 3, release: 'v1.14.0', summary: 'print a single decision body + frontmatter' }
+};
+
+function makeStub(commandName) {
+  const info = STUB_INFO[commandName];
+  if (!info) {
+    throw new Error(`makeStub: unknown command '${commandName}'`);
+  }
+
+  return async function runStub({ args = [], options = {}, logger } = {}) {
+    const targetDir = process.cwd();
+    const helpRequested = options.help === true || args.includes('--help') || args.includes('-h');
+
+    if (helpRequested) {
+      const msg = `${commandName} — ${info.summary}\n  Status: shipped in Phase ${info.phase} (${info.release}).\n  Phase 1 (v1.12.0) wires the command surface but defers logic to that release.`;
+      if (options.json) return { ok: true, stub: true, command: commandName, phase: info.phase, release: info.release, summary: info.summary };
+      if (logger) logger.log(msg);
+      return { ok: true, stub: true };
+    }
+
+    await emitDossierEvent(targetDir, {
+      agent: commandName,
+      type: 'op_command_stub',
+      summary: `${commandName} invoked before its release phase`,
+      meta: { command: commandName, phase: info.phase, release: info.release }
+    });
+
+    const errMsg = `${commandName} — Not yet implemented (ships in Phase ${info.phase} / ${info.release}). Run \`${commandName} --help\` for scope.`;
+    if (options.json) {
+      return { ok: false, stub: true, command: commandName, phase: info.phase, release: info.release, error: errMsg };
+    }
+    if (logger && logger.error) {
+      logger.error(errMsg);
+    }
+    return { ok: false, stub: true, exitCode: 1 };
+  };
+}
+
+module.exports = {
+  runOpCapture: makeStub('op:capture'),
+  runOpPromote: makeStub('op:promote'),
+  runOpForget:  makeStub('op:forget'),
+  runOpList:    makeStub('op:list'),
+  runOpShow:    makeStub('op:show'),
+  STUB_INFO
+};