devflow-kit 3.0.1 → 3.2.0

package/dist/cli/commands/install-report.js

@@ -1,6 +1,6 @@
 /**
  * Rendering for the post-install summary — pure functions that turn an
- * {@link InstallReport} into lines, logging nothing (applies ADR-013).
+ * {@link InstallReport} into lines, logging nothing.
  *
  * Its own module rather than a section of init.ts because `devflow tracker --set`
  * renders the same overlay outcomes from a different command. A CLI command
@@ -18,18 +18,18 @@ import { prefixSkillName } from '../../core/plugins.js';
  * shadowed, and a unit it could not refresh is left in one of the states
  * {@link OverlayFailureState} enumerates — running on the previous install, half
  * replaced, absent, or recoverable only from a backup path. None of that is visible from
- * the filesystem at a glance, so all of it reaches the summary — PF-015: a report field
+ * the filesystem at a glance, so all of it reaches the summary — a report field
  * with no render site is not a report, and a render site that flattens four states into
  * one sentence is the same defect one layer up.
  *
- * Pure function — returns lines, logs nothing (applies ADR-013).
+ * Pure function — returns lines, logs nothing.
  *
  * @param skillName - Bare name of the skill hosting the generated references,
  *   rendered `devflow:`-prefixed. Defaults to the core constant the build path and
  *   the installer's overlay trigger both read, so the renderer is never a third
- *   independent statement of which skill owns them — the divergence PF-013
- *   describes, where changing the answer means finding every retyped spelling and
- *   nothing fails if one is missed.
+ *   independent statement of which skill owns them — a divergence where changing
+ *   the answer means finding every retyped spelling and nothing fails if one is
+ *   missed.
  */
 export function formatOverlaySummary(report, skillName = SKILL_REFS_SKILL_NAME) {
     const lines = [];
@@ -59,7 +59,7 @@ export function formatOverlaySummary(report, skillName = SKILL_REFS_SKILL_NAME)
  * be told about.
  *
  * Exported because `devflow tracker --set` renders the same states when it aborts
- * on an overlay failure (applies PF-013 — one sentence per state, in one place,
+ * on an overlay failure (one sentence per state, in one place,
  * rather than a second wording that drifts).
  *
  * Exhaustive over {@link OverlayFailureState} — a new state added to the union without a
@@ -103,7 +103,7 @@ export function describeOverlayFailureState(state) {
  * The delta line is emitted only when something moved: on a steady-state re-init
  * the counts are noise.
  *
- * Pure function — returns lines, logs nothing (applies ADR-013).
+ * Pure function — returns lines, logs nothing.
  *
  * @param previous - The provider recorded by the PRIOR manifest, or undefined on
  *   a first install. Rendered only when it differs from `provider`.
@@ -144,7 +144,7 @@ export function formatTrackerAssetSummary(input) {
  *     how the selection was assembled, and a duplicate name in either list is a
  *     manifest detail rather than a different selection.
  *
- * Pure function (applies ADR-013).
+ * Pure function.
  *
  * @param previousPlugins - `manifest.plugins` as it stands before this run, or
  *   `null` when there is no prior manifest.
@@ -176,7 +176,7 @@ export function isPluginListUnchanged(previousPlugins, effectivePluginNames) {
  * it is FALSE when there is no prior manifest: a first install removed nothing a
  * user had, so there is no upgrade to explain (design review L2).
  *
- * Pure function — returns lines, logs nothing (applies ADR-013).
+ * Pure function — returns lines, logs nothing.
  */
 export function formatSkillScopeSummary(report, pluginListUnchanged) {
     const lines = [];

package/dist/cli/commands/learning.js

@@ -3,25 +3,119 @@ import { promises as fs } from 'fs';
 import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
-import { getLearningDir, getLearningTuningConfigPath, getDecisionsLogPath, getDecisionsLockDir, } from '../../core/project-paths.js';
+import { getLearningDir, getLearningTuningConfigPath, } from '../../core/project-paths.js';
 import { readMachineFeature, writeMachineFeature } from '../../core/feature-switch.js';
 import { loadSettingsModule, narrowedSwitchLabel, personalConfigTrackedWarning } from '../../core/evidence-policy.js';
 import { getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
 import { getLedgerRoot } from '../../core/ledger-root.js';
-import { sweepLegacyDreamMarkers, drainLearningQueue } from '../../core/learning-queue-cleanup.js';
-import { readObservations, warnIfInvalid, } from '../../core/observation-io.js';
+import { drainLearningQueue } from '../../core/learning-queue-cleanup.js';
+import { firstSymbolicLink } from '../../core/linked-path.js';
+import { formatRefusedDrain } from '../../core/queue-drain.js';
+import { formatLearningStoreUnavailable, loadLearningStore, } from '../../core/learning-store.js';
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+/** What the read and restore commands say about a project with no `.devflow/learning/`. */
+const NO_LEARNING_DATA = 'No learning data in this project yet.';
+/**
+ * How long a writer here (--restore, --clear, --reset) waits for the learning lock
+ * before it refuses as busy. An op holds the lock for milliseconds, so a longer
+ * wait means a stuck holder, and the store's own 30 s wait would leave the command
+ * looking hung.
+ */
+const LOCK_WAIT_MS = 5000;
+/**
+ * Code point ranges JSON.stringify leaves raw that a terminal may act on, or may
+ * display reordered: DEL and the C1 controls, the directional marks, the line and
+ * paragraph separators, and the bidirectional embeddings, overrides and isolates.
+ */
+const TERMINAL_UNSAFE_RANGES = [
+    [0x7f, 0x9f],
+    [0x200e, 0x200f],
+    [0x2028, 0x2029],
+    [0x202a, 0x202e],
+    [0x2066, 0x2069],
+];
+/**
+ * `value` as pretty JSON a terminal shows as written: every character in
+ * TERMINAL_UNSAFE_RANGES becomes its `\uXXXX` escape. Such characters can occur
+ * only inside JSON strings, where the escape means the same character, so the
+ * text still parses back to `value`.
+ */
+function terminalSafeJson(value) {
+    let text = '';
+    for (const ch of JSON.stringify(value, null, 2)) {
+        const code = ch.codePointAt(0) ?? 0;
+        const unsafe = TERMINAL_UNSAFE_RANGES.some(([low, high]) => code >= low && code <= high);
+        text += unsafe ? `\\u${code.toString(16).padStart(4, '0')}` : ch;
+    }
+    return text;
+}
+/** `1 decision`, `2 decisions`. */
+function counted(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+/**
+ * The learning store (D-LEARNING-STORE-SEAM), or null after reporting why it
+ * cannot be used and setting exit code 1.
+ */
+function requireStore() {
+    const loaded = loadLearningStore();
+    if (loaded.ok)
+        return loaded.value;
+    p.log.error(`Learning: ${formatLearningStoreUnavailable(loaded.error)}`);
+    process.exitCode = 1;
+    return null;
+}
+/** What a writer says when the store refused; `undone` completes "Nothing was …". */
+function storeRefusal(error, undone) {
+    switch (error.kind) {
+        case 'no-learning-dir': return NO_LEARNING_DATA;
+        case 'busy': return `The learning store is busy: another run holds its lock. Nothing was ${undone}; try again in a moment.`;
+        default: return error.message;
+    }
+}
+/**
+ * Ask `message` on a terminal and say whether to go on, logging `cancelled` when the
+ * answer is no. With no terminal there is no one to ask: a script that passed the
+ * flag has decided.
+ */
+async function confirmOnTerminal(message, cancelled) {
+    if (!process.stdin.isTTY)
+        return true;
+    const confirmed = await p.confirm({ message, initialValue: false });
+    if (p.isCancel(confirmed) || !confirmed) {
+        p.log.info(cancelled);
+        return false;
+    }
+    return true;
+}
+/** True when `dir` is a directory; false when nothing, or something else, is there. */
+async function isDirectory(dir) {
+    try {
+        return (await fs.stat(dir)).isDirectory();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return false;
+        throw err;
+    }
+}
 // ---------------------------------------------------------------------------
 // Sub-command handlers
 // ---------------------------------------------------------------------------
 function printUsage() {
     p.intro(color.bgCyan(color.black(' Learning ')));
-    p.note(`${color.cyan('devflow learning --enable')}      Enable learning in every project (a repository can opt out)\n` +
-        `${color.cyan('devflow learning --disable')}     Disable learning in every project (drains this project's queue)\n` +
-        `${color.cyan('devflow learning --status')}      Show learning status\n` +
-        `${color.cyan('devflow learning --list')}        Show all observations\n` +
-        `${color.cyan('devflow learning --configure')}   Configuration wizard\n` +
-        `${color.cyan('devflow learning --clear')}       Truncate decisions log\n` +
-        `${color.cyan('devflow learning --reset')}       Remove all learning state files`, 'Usage');
+    p.note(`${color.cyan('devflow learning --enable')}        Enable learning in every project (a repository can opt out)\n` +
+        `${color.cyan('devflow learning --disable')}       Disable learning in every project (drains this project's queue)\n` +
+        `${color.cyan('devflow learning --status')}        Show learning status and entry counts\n` +
+        `${color.cyan('devflow learning --list')}          List entries, inactive entries and observations\n` +
+        `${color.cyan('devflow learning --show <id>')}     Print one entry or observation as JSON\n` +
+        `${color.cyan('devflow learning --restore <id>')}  Make an inactive entry active again\n` +
+        `${color.cyan('devflow learning --configure')}     Configuration wizard\n` +
+        `${color.cyan('devflow learning --clear')}         Drop the observations no entry uses, and drain the queue\n` +
+        `${color.cyan('devflow learning --reset')}         Remove all learning state files`, 'Usage');
     p.outro(color.dim('Detects architectural decisions and known pitfalls from your sessions'));
 }
 /**
@@ -40,10 +134,35 @@ async function requireLedgerRoot(actionSuffix) {
     }
     return ledgerRoot;
 }
+/**
+ * The --status entry lines: active entries by type, inactive ones by status (in
+ * the store's order, each status present), the active entries still in the v1
+ * format — the migration still to do — and the observations.
+ */
+function entryCountLines(listing, logRowCount, inactiveStatuses) {
+    const active = listing.active;
+    const decisions = active.filter(entry => entry.type === 'decision').length;
+    const pitfalls = active.filter(entry => entry.type === 'pitfall').length;
+    const byStatus = inactiveStatuses
+        .map(status => ({ status, count: listing.inactive.filter(entry => entry.status === status).length }))
+        .filter(({ count }) => count > 0)
+        .map(({ status, count }) => `${status} ${count}`);
+    const legacy = active.filter(entry => entry.schema === 1).length;
+    return [
+        `Entries: ${active.length} active (${counted(decisions, 'decision')}, ${counted(pitfalls, 'pitfall')}), `
+            + `${listing.inactive.length} inactive${byStatus.length > 0 ? ` (${byStatus.join(', ')})` : ''}`,
+        `Legacy v1 entries: ${legacy} of ${active.length} active`,
+        `Observations: ${logRowCount} in the log, ${listing.observations.length} not yet promoted`,
+    ];
+}
+/**
+ * `--status`: the machine switch, then the counts the store reads. Reads only:
+ * malformed lines are counted, never quarantined, and no scope is checked.
+ */
 async function handleStatus() {
     // D-FEATURES-NARROW-ONLY: the machine switch is the manifest's and reads the
     // same from every directory; a repository layer can only narrow it, and adds a
-    // line only when it does. The observation counts are per-project.
+    // line only when it does. The entry counts are per-project.
     const enabled = await readMachineFeature(getDevFlowDirectory(), 'learning');
     const settingsModule = loadSettingsModule();
     const narrowed = enabled ? narrowedSwitchLabel(settingsModule, { dir: process.cwd() }, 'learning') : null;
@@ -54,69 +173,106 @@ async function handleStatus() {
         p.log.warn(trackedWarning);
     const ledgerRoot = await getLedgerRoot();
     if (!ledgerRoot) {
-        p.log.info(`${stateLine}\nObservations: not in a git project`);
-        return;
-    }
-    const logPath = getDecisionsLogPath(ledgerRoot);
-    const { observations, invalidCount } = await readObservations(logPath);
-    const decisionObs = observations.filter(o => o.type === 'decision' || o.type === 'pitfall');
-    const decisions = observations.filter(o => o.type === 'decision');
-    const pitfalls = observations.filter(o => o.type === 'pitfall');
-    const created = decisionObs.filter(o => o.status === 'created');
-    const ready = decisionObs.filter(o => o.status === 'ready');
-    const observing = decisionObs.filter(o => o.status === 'observing');
-    const deprecated = decisionObs.filter(o => o.status === 'deprecated');
-    const lines = [stateLine];
-    if (decisionObs.length === 0) {
-        lines.push('Observations: none');
+        p.log.info(`${stateLine}\nEntries: not in a git project`);
+        return;
     }
-    else {
-        lines.push(`Observations: ${decisionObs.length} total`);
-        lines.push(`  Decisions: ${decisions.length}, Pitfalls: ${pitfalls.length}`);
-        lines.push(`  Status: ${observing.length} observing, ${ready.length} ready, ${created.length} promoted, ${deprecated.length} deprecated`);
+    const loaded = loadLearningStore();
+    if (!loaded.ok) {
+        p.log.info(`${stateLine}\nEntries: unavailable (${formatLearningStoreUnavailable(loaded.error)})`);
+        return;
+    }
+    const store = loaded.value;
+    const { ledgerRows, logRows, rejected } = store.readLearningState(ledgerRoot);
+    const listing = store.buildListing(ledgerRows, logRows, { rejected });
+    p.log.info([stateLine, ...entryCountLines(listing, logRows.length, store.INACTIVE_STATUSES)].join('\n'));
+    const { ledger, log } = listing.malformed;
+    if (ledger + log > 0) {
+        p.log.warn(`Malformed lines skipped: ${ledger} in the ledger, ${log} in the log. ` +
+            'The next op that rewrites a file moves its malformed lines to a .rejected.jsonl file beside it.');
     }
-    p.log.info(lines.join('\n'));
-    warnIfInvalid(invalidCount);
 }
+/**
+ * `--list`: the store's listing — the same text json-helper's `list` op prints —
+ * on stdout. Read-only. Outside a git project it reads the current directory.
+ */
 async function handleList() {
-    // Resolve the log from the ledger root (matches --status, --clear, --reset,
-    // --disable) so `--list` run from a subdirectory or a linked worktree finds
-    // the real log instead of a nonexistent one under process.cwd(). Falls back
-    // to cwd when not in a git project, preserving the prior behavior for that case.
-    const ledgerRoot = await getLedgerRoot();
-    const logPath = getDecisionsLogPath(ledgerRoot ?? process.cwd());
-    let logExists = true;
-    try {
-        await fs.access(logPath);
+    const root = (await getLedgerRoot()) ?? process.cwd();
+    const store = requireStore();
+    if (!store)
+        return;
+    const listed = store.readListing(root);
+    if (!listed.ok) {
+        if (listed.error.kind === 'no-learning-dir') {
+            p.log.info(NO_LEARNING_DATA);
+            return;
+        }
+        p.log.error(listed.error.message);
+        process.exitCode = 1;
+        return;
     }
-    catch {
-        logExists = false;
+    process.stdout.write(`${store.formatListing(listed.value)}\n`);
+}
+/**
+ * `--show <id>`: one entry, by its anchor or its observation id, as the JSON
+ * json-helper's `show` op prints, made terminal-safe. Read-only. Outside a git
+ * project it reads the current directory.
+ */
+async function handleShow(key) {
+    const root = (await getLedgerRoot()) ?? process.cwd();
+    const store = requireStore();
+    if (!store)
+        return;
+    const shown = store.showByKey(root, key);
+    if (!shown.ok) {
+        p.log.error(shown.error.kind === 'no-learning-dir' ? NO_LEARNING_DATA : shown.error.message);
+        process.exitCode = 1;
+        return;
     }
-    if (!logExists) {
-        p.log.info('No observations yet. Decisions log not found.');
+    process.stdout.write(`${terminalSafeJson(shown.value)}\n`);
+}
+/**
+ * `--restore <id>`: make an inactive entry active again through the store's
+ * restoreAnchor, which clears its notes and its verification so maintenance
+ * reviews it again, and re-renders the files. A refusal writes nothing.
+ */
+async function handleRestore(anchor) {
+    const ledgerRoot = await requireLedgerRoot('restore not performed');
+    if (!ledgerRoot) {
+        process.exitCode = 1;
         return;
     }
-    const { observations, invalidCount } = await readObservations(logPath);
-    const filtered = observations.filter(o => o.type === 'decision' || o.type === 'pitfall');
-    if (filtered.length === 0) {
-        p.log.info('No decision/pitfall observations recorded yet.');
+    const store = requireStore();
+    if (!store)
+        return;
+    if (!store.ANCHOR_ID_RE.test(anchor)) {
+        p.log.error(`--restore takes an entry id (ADR-NNN or PF-NNN), not ${JSON.stringify(anchor)}`);
+        process.exitCode = 1;
         return;
     }
-    // Sort by confidence descending
-    filtered.sort((a, b) => b.confidence - a.confidence);
-    p.intro(color.bgCyan(color.black(' Learning Observations ')));
-    for (const obs of filtered) {
-        const typeIcon = obs.type === 'decision' ? 'D' : 'F';
-        const statusIcon = obs.status === 'created' ? color.green('created')
-            : obs.status === 'ready' ? color.yellow('ready')
-                : obs.status === 'deprecated' ? color.dim('deprecated')
-                    : color.dim('observing');
-        const conf = (obs.confidence * 100).toFixed(0);
-        p.log.info(`[${typeIcon}] ${color.cyan(obs.pattern)} (${conf}% | ${obs.observations}x | ${statusIcon})`);
+    const restored = store.restoreAnchor(ledgerRoot, anchor, { timeoutMs: LOCK_WAIT_MS });
+    if (!restored.ok) {
+        p.log.error(storeRefusal(restored.error, 'restored'));
+        process.exitCode = 1;
+        return;
     }
-    warnIfInvalid(invalidCount);
-    p.outro(color.dim(`${filtered.length} observation(s) total`));
+    p.log.success(`Restored ${restored.value.anchor_id} (${restored.value.status}); it is due for review again.`);
 }
+/**
+ * The scope choices of `devflow learning --configure`.
+ *
+ * D-LEARNING-MODEL-PRECEDENCE: the session-start hook takes the first layer that
+ * supplies a model — the project file, then a `devflow agents` Learning mapping,
+ * then the global file. A global file therefore has no effect for a user who has
+ * such a mapping, and its hint says so.
+ */
+export const CONFIGURE_SCOPE_OPTIONS = [
+    { value: 'project', label: 'Project', hint: 'This project only (.devflow/learning/learning.json)' },
+    {
+        value: 'global',
+        label: 'Global',
+        hint: 'All projects (~/.devflow/learning.json); a devflow agents Learning mapping takes precedence over it',
+    },
+];
 async function handleConfigure() {
     p.intro(color.bgCyan(color.black(' Learning Configuration ')));
     const model = await p.select({
@@ -141,10 +297,7 @@ async function handleConfigure() {
     }
     const scope = await p.select({
         message: 'Configuration scope',
-        options: [
-            { value: 'project', label: 'Project', hint: 'This project only (.devflow/learning/learning.json)' },
-            { value: 'global', label: 'Global', hint: 'All projects (~/.devflow/learning.json)' },
-        ],
+        options: [...CONFIGURE_SCOPE_OPTIONS],
     });
     if (p.isCancel(scope)) {
         p.cancel('Configuration cancelled.');
@@ -166,91 +319,92 @@ async function handleConfigure() {
         // from the ledger ($LEDGER_ROOT/.devflow/learning/), so write it there — the
         // main checkout in a linked worktree; the current directory outside git.
         const projectRoot = (await getLedgerRoot()) ?? process.cwd();
-        await fs.mkdir(getLearningDir(projectRoot), { recursive: true });
+        const learningDir = getLearningDir(projectRoot);
         const projectConfigPath = getLearningTuningConfigPath(projectRoot);
+        // D-CLI-NO-SYMLINK (core/linked-path.ts): nothing is written through a .devflow,
+        // a learning folder or a learning.json that is a symbolic link.
+        const linked = await firstSymbolicLink([path.dirname(learningDir), learningDir, projectConfigPath]);
+        if (linked !== null) {
+            p.log.error(`Project config not written: ${linked} is a symbolic link, and devflow writes nothing through one`);
+            process.exitCode = 1;
+            return;
+        }
+        await fs.mkdir(learningDir, { recursive: true });
         await fs.writeFile(projectConfigPath, configJson, 'utf-8');
         p.log.success(`Project config written to ${color.dim(projectConfigPath)}`);
     }
     p.outro(color.green('Configuration saved.'));
 }
+/**
+ * `--reset`: remove all learning state — entries, observations, rendered files,
+ * the tuning config, and the queue with its claim — through the store's
+ * resetLearning, under the learning lock every learning writer takes
+ * (D-ONE-LEARNING-LOCK, D-RESET-UNDER-LOCK). A project with no learning directory
+ * has nothing to reset, and nothing is created there (D-NO-STRAY-TREE).
+ */
 async function handleReset() {
     const ledgerRoot = await requireLedgerRoot('reset not performed');
     if (!ledgerRoot)
         return;
-    const lockDir = getDecisionsLockDir(ledgerRoot);
-    // Ensure the parent directory exists so a second reset (after .devflow/learning/
-    // was already removed) does not fail with ENOENT and emit a false contention error.
-    await fs.mkdir(path.dirname(lockDir), { recursive: true });
-    // Acquire lock to prevent conflict with a concurrent `devflow learning` invocation.
-    // Non-recursive: EEXIST still means genuine contention.
-    try {
-        await fs.mkdir(lockDir);
-    }
-    catch {
-        p.log.error('Learning system is currently running. Try again in a moment.');
+    const store = requireStore();
+    if (!store)
+        return;
+    if (!(await isDirectory(getLearningDir(ledgerRoot)))) {
+        p.log.info('No learning data to reset.');
         return;
     }
-    try {
-        if (process.stdin.isTTY) {
-            const confirm = await p.confirm({
-                message: 'Remove all learning state files? This cannot be undone.',
-                initialValue: false,
-            });
-            if (p.isCancel(confirm) || !confirm) {
-                p.log.info('Reset cancelled.');
-                return;
-            }
-        }
-        // Remove the entire learning directory (contains queue files, content files,
-        // ledger, and tuning config). Single-dir semantics: all learning state lives here.
-        try {
-            await fs.rm(getLearningDir(ledgerRoot), { recursive: true, force: true });
-        }
-        catch { /* best effort */ }
-        // Clean legacy dream marker-pipeline stamps from old installs.
-        // Best-effort: sweeps the now-absent dir silently (ENOENT-tolerant).
-        try {
-            await sweepLegacyDreamMarkers(getLearningDir(ledgerRoot));
-        }
-        catch { /* best effort */ }
-        p.log.success('Reset complete — removed .devflow/learning/ state.');
-    }
-    finally {
-        try {
-            await fs.rmdir(lockDir);
+    const proceed = await confirmOnTerminal('Remove all learning state files? This cannot be undone.', 'Reset cancelled.');
+    if (!proceed)
+        return;
+    const reset = store.resetLearning(ledgerRoot, { timeoutMs: LOCK_WAIT_MS });
+    if (!reset.ok) {
+        if (reset.error.kind === 'no-learning-dir') {
+            p.log.info('No learning data to reset.');
+            return;
         }
-        catch { /* already cleaned */ }
+        p.log.error(storeRefusal(reset.error, 'reset'));
+        process.exitCode = 1;
+        return;
     }
+    p.log.success('Reset complete — removed .devflow/learning/ state.');
 }
+/**
+ * `--clear`: drop the observations no entry uses (D-CLEAR-UNREFERENCED), then
+ * drain the learning queue. The queue is drained only once the clear succeeded:
+ * a busy lock or a refusal leaves both the log and the queue as they were, so a
+ * failed clear changes nothing.
+ */
 async function handleClear() {
     const ledgerRoot = await requireLedgerRoot('clear not performed');
     if (!ledgerRoot)
         return;
-    const decisionsLogPath = getDecisionsLogPath(ledgerRoot);
-    try {
-        await fs.access(decisionsLogPath);
-    }
-    catch {
-        p.log.info('No decisions log to clear.');
+    const store = requireStore();
+    if (!store)
+        return;
+    if (!(await isDirectory(getLearningDir(ledgerRoot)))) {
+        p.log.info('No learning data to clear.');
         return;
     }
-    if (process.stdin.isTTY) {
-        const confirm = await p.confirm({
-            message: 'Clear all decision/pitfall observations? This cannot be undone.',
-            initialValue: false,
-        });
-        if (p.isCancel(confirm) || !confirm) {
-            p.log.info('Clear cancelled.');
+    const proceed = await confirmOnTerminal('Drop every observation no entry uses? Entries and the observations they use are kept. This cannot be undone.', 'Clear cancelled.');
+    if (!proceed)
+        return;
+    const cleared = store.clearUnreferenced(ledgerRoot, { timeoutMs: LOCK_WAIT_MS });
+    if (!cleared.ok) {
+        if (cleared.error.kind === 'no-learning-dir') {
+            p.log.info('No learning data to clear.');
             return;
         }
+        p.log.error(storeRefusal(cleared.error, 'cleared'));
+        process.exitCode = 1;
+        return;
     }
-    await fs.writeFile(decisionsLogPath, '', 'utf-8');
-    // Drain the learning (decisions-detection) queue so stale turns don't process
-    // on the next session — mirrors memory.ts's drain-on-disable behavior for
-    // the sibling memory queue. A mid-run Learning agent whose claimed batch
-    // vanishes aborts without changes — the desired outcome of clearing.
-    await drainLearningQueue(ledgerRoot);
-    p.log.success('Decisions log cleared.');
+    // A mid-run Learning agent whose claimed batch vanishes stops without further
+    // writes — the desired outcome of clearing.
+    const drain = await drainLearningQueue(ledgerRoot);
+    p.log.success(`Cleared ${counted(cleared.value.cleared, 'observation')} no entry uses and kept ${cleared.value.kept} ` +
+        `that entries use${drain.drained ? '; drained the learning queue.' : '.'}`);
+    if (!drain.drained)
+        p.log.warn(formatRefusedDrain('learning', drain.linkedFolder));
 }
 /**
  * `--enable` / `--disable`: the machine-wide switch (D-FEATURES-NARROW-ONLY),
@@ -275,7 +429,9 @@ async function handleToggle(enabled) {
     // batch vanishes aborts without changes — the desired outcome of disabling.
     const ledgerRoot = await getLedgerRoot();
     if (ledgerRoot) {
-        await drainLearningQueue(ledgerRoot);
+        const drain = await drainLearningQueue(ledgerRoot);
+        if (!drain.drained)
+            p.log.warn(formatRefusedDrain('learning', drain.linkedFolder));
     }
     p.log.success('Learning disabled in every project');
 }
@@ -283,24 +439,26 @@ export const learningCommand = new Command('learning')
     .description('Enable or disable learning (decision/pitfall detection) in every project')
     .option('--enable', 'Enable learning in every project (a repository can opt out)')
     .option('--disable', 'Disable learning in every project')
-    .option('--status', 'Show learning status and observation counts')
-    .option('--list', 'Show all decision/pitfall observations sorted by confidence')
+    .option('--status', 'Show learning status and entry counts')
+    .option('--list', 'List entries, inactive entries with their notes, and observations')
+    .option('--show <id>', 'Print one entry (ADR-NNN or PF-NNN) or observation (obs_...) as JSON')
+    .option('--restore <id>', 'Make an inactive entry active again')
     .option('--configure', 'Interactive configuration wizard for learning.json')
-    .option('--clear', 'Truncate decisions log (removes all observations)')
+    .option('--clear', 'Drop the observations no entry uses, and drain the learning queue')
     .option('--reset', 'Remove all learning state files and artifacts')
     .action(async (options) => {
     const knownFlags = [
-        'enable', 'disable', 'status', 'list', 'configure',
+        'enable', 'disable', 'status', 'list', 'show', 'restore', 'configure',
         'clear', 'reset',
     ];
-    const hasFlag = knownFlags.some((f) => options[f]);
+    const hasFlag = knownFlags.some((f) => options[f] !== undefined);
     if (!hasFlag) {
         printUsage();
         return;
     }
-    // Thin router — dispatch order matches the precedence of the original
-    // inline implementation (status, list, configure, reset, clear, enable,
-    // disable). Each handler owns its own path resolution and I/O.
+    // Thin router — the read-only commands first (status, list, show), then
+    // configure, reset, clear, restore, enable, disable. Each handler owns its own
+    // path resolution and I/O.
     if (options.status) {
         await handleStatus();
         return;
@@ -309,6 +467,10 @@ export const learningCommand = new Command('learning')
         await handleList();
         return;
     }
+    if (options.show !== undefined) {
+        await handleShow(options.show);
+        return;
+    }
     if (options.configure) {
         await handleConfigure();
         return;
@@ -321,6 +483,10 @@ export const learningCommand = new Command('learning')
         await handleClear();
         return;
     }
+    if (options.restore !== undefined) {
+        await handleRestore(options.restore);
+        return;
+    }
     if (options.enable) {
         await handleToggle(true);
         return;