@lumoai/cli 1.52.0 → 1.53.0

package/assets/skill/SKILL.md

@@ -126,6 +126,7 @@ lumo fidelity show LUM-42 --json
 - `lumo milestone add/remove <id> <task...>` — batch bind/unbind tasks
 - `lumo milestone triage <id> <task...> --claimable|--not-claimable` — steward batch agent-claimable triage (LUM-646): mark in-milestone tasks (not) claimable; tasks not in the milestone are skipped. Feeds `lumo next --claimable`
 - `lumo milestone summary [--retry]` — AI retro
+- `lumo milestone changelog <id> [--json]` — structured changelog from DONE tasks + merged PRs + frozen claimSnapshot (pure assembly, no LLM; runs on any status). Headline counts carry a baseline vs prior completed milestones (LUM-508); each claim shows provenance, no-PR/no-claim rendered explicitly (LUM-649)
 - `lumo milestone reorder/move` — manual ordering
 - `lumo milestone criteria set/list/verdict` — milestone-level **exit criteria** (LUM-643): the close contract, drafted & adjudicated (裁定) by the steward (LUM-640) or a human. Unresolved criteria (pending or NOT_MET) block `--status completed` **and** the LUM-624 auto-rollup with 409/fail-closed; human override is web-only (`?force=1`, stamped as a persistent trail). `verdict --met` on `EXTERNAL_FACT` requires `--evidence` (422); `PENDING_OUTCOME` can never be MET
 

package/assets/skill/references/milestones.md

@@ -91,6 +91,14 @@ Sprint coverage:
   Unscheduled             1 task
 ```
 
+**Cross-milestone learning (LUM-648):** when this milestone's STEWARD sessions were injected prior-milestone distilled learning (the LUM-647 learning unit), a **Cross-milestone learning** section reports how much of it was actually used — `Injected: N prior learnings (from K prior milestones)` and `Usage rate: Z% (judged-used X/Y)`. The rate reuses lineage's `used=true/false/null` usage voting (judged at the successor milestone's close): abstentions (un-audited / judge-abstained impressions) are **excluded from the denominator**, so it is a lower bound. Below 3 judged edges it reads `insufficient (judged Y, need ≥3)` rather than a fabricated percentage. The section is omitted entirely when nothing was injected (that's "nothing to migrate", not 0%).
+
+```
+Cross-milestone learning:
+  Injected: 8 prior learnings (from 2 prior milestones)
+  Usage rate: 62% (judged-used 5/8)
+```
+
 ```bash
 lumo milestone show "Q3 Launch"
 lumo milestone show 11111111-2222-3333-4444-555555555555
@@ -293,6 +301,31 @@ lumo milestone summary 11111111-2222-3333-4444-555555555555
 
 When to suggest: user asks "summarize the milestone", "milestone retro", "give me a summary of the Q3 milestone".
 
+### `lumo milestone changelog <identifier> [--project <ref>] [--json]` — structured changelog (LUM-649)
+
+Assembles a **structured changelog** from the milestone's **DONE tasks + merged PRs + frozen claimSnapshot**. Pure deterministic assembly — **no LLM**, and (unlike `summary`) **no COMPLETED gate**: it runs on a milestone of any status, so an ACTIVE milestone reports "what has shipped so far". Only DONE tasks ever appear. `<identifier>` accepts a milestone name or UUID; `--project <ref>` is required when the identifier is a name and the workspace has >1 project.
+
+Honest-reporting contract (why this is more than a task list):
+
+- **Headline counts carry a baseline (LUM-508 reuse).** "Tasks shipped" and "PRs merged" are rendered as a current-vs-base stat against the reference class of **prior COMPLETED milestones in the same project** — e.g. `4 (base 3, +33% · above)`. With **fewer than 3** prior milestones the base is honestly suppressed to `4 (no baseline yet)` — never a naked number, never a thin fabricated baseline.
+- **Claim provenance.** Each DONE task shows its frozen `claimSnapshot` tagged with its source + session (`Claim [RUN_SUMMARY · sess-1]: …`). A synthesized-but-empty claim reads `(no claim recorded)` (fail-closed "no material"), distinct from a never-synthesized `(not synthesized)`.
+- **Nothing silently dropped.** A DONE task with no merged PR renders an explicit `PRs: (no merged PR)`. Entries are ordered newest-delivery-first (by task `updatedAt` — Task has no `completedAt` column, so this is a best-available proxy).
+
+`--json` emits the raw structured payload (milestone / headline baseline stats / entries) unchanged for programmatic use.
+
+| Flag              | Type    | Notes                                                                                      |
+| ----------------- | ------- | ------------------------------------------------------------------------------------------ |
+| `--project <ref>` | string  | Project name or slug. Required when identifier is a name and the workspace has >1 project. |
+| `--json`          | boolean | Emit the raw structured changelog payload instead of the human markdown.                   |
+
+```bash
+lumo milestone changelog "Agent-Native Milestones"
+lumo milestone changelog "Agent-Native Milestones" --json
+lumo milestone changelog 11111111-2222-3333-4444-555555555555
+```
+
+When to suggest: user asks for a "changelog", "release notes", "what shipped in this milestone", or wants a structured delivery list they can paste into a release note. For the AI narrative retro use `milestone summary`; for the honest delivery-count/cost rollup see `milestone show`.
+
 ### `lumo milestone reorder <ref...> [--project <ref>]` — set the full milestone order
 
 Reorders a project's milestones. Pass **every** milestone in the project (by name, case-insensitive, or its cuid) in the desired order — the command rewrites each milestone's `sortOrder` to match. An incomplete list (not every milestone named), an unknown ref, or a duplicate is rejected **before any network mutation**, with a message naming the offending / missing milestones.

package/dist/cli/src/commands/milestone-changelog.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatBaselineStat = formatBaselineStat;
+exports.formatMilestoneChangelog = formatMilestoneChangelog;
+exports.renderChangelogOutput = renderChangelogOutput;
+exports.milestoneChangelog = milestoneChangelog;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const resolve_1 = require("../lib/resolve");
+const sanitize_1 = require("../lib/sanitize");
+// Mirror of lib/baseline/types.MIN_BASELINE_SAMPLE — the honest floor below
+// which a baseline is suppressed. The server fold already nulls `base` under
+// this threshold; the check here is defensive so a thin baseline can never leak.
+const MIN_BASELINE_SAMPLE = 3;
+/**
+ * Render one BaselineStat as an honest inline string:
+ * - real base → `4 (base 3, +33% · above)`
+ * - no base / thin sample → `2 (no baseline yet)`
+ * - current unmeasured → `— (no baseline yet)`
+ */
+function formatBaselineStat(stat) {
+    const current = stat.current === null ? '—' : String(stat.current);
+    const grounded = stat.base !== null &&
+        stat.current !== null &&
+        stat.sampleSize >= MIN_BASELINE_SAMPLE;
+    if (!grounded) {
+        return `${current} (no baseline yet)`;
+    }
+    const unit = stat.deltaKind === 'rate' ? 'pt' : '%';
+    const parts = [`base ${stat.base}`];
+    if (stat.deltaPct !== null) {
+        const sign = stat.deltaPct > 0 ? '+' : '';
+        parts.push(`${sign}${stat.deltaPct}${unit}`);
+    }
+    if (stat.band !== null) {
+        parts.push(`· ${stat.band}`);
+    }
+    return `${current} (${parts.join(' ')})`;
+}
+function formatWindow(startDate, targetDate) {
+    const fmt = (iso) => iso.slice(0, 10);
+    if (startDate && targetDate)
+        return `${fmt(startDate)} → ${fmt(targetDate)}`;
+    if (startDate)
+        return `from ${fmt(startDate)}`;
+    if (targetDate)
+        return `target ${fmt(targetDate)}`;
+    return null;
+}
+function formatClaim(claim) {
+    switch (claim.status) {
+        case 'present': {
+            const tag = [claim.source, claim.sessionId].filter(Boolean).join(' · ');
+            const label = tag ? `Claim [${(0, sanitize_1.sanitizeField)(tag)}]` : 'Claim';
+            return `  ${label}: ${(0, sanitize_1.sanitizeField)(claim.text)}`;
+        }
+        case 'empty':
+            return '  Claim: (no claim recorded)';
+        case 'unsynthesized':
+            return '  Claim: (not synthesized)';
+    }
+}
+function formatEntry(entry) {
+    const lines = [
+        `### ${entry.identifier} — ${(0, sanitize_1.sanitizeField)(entry.title)}`,
+    ];
+    if (entry.prs.length === 0) {
+        lines.push('  PRs: (no merged PR)');
+    }
+    else {
+        const prs = entry.prs
+            .map(pr => {
+            const sha = pr.mergeCommitSha
+                ? ` (${pr.mergeCommitSha.slice(0, 7)})`
+                : '';
+            return `${pr.repo}#${pr.number} "${(0, sanitize_1.sanitizeField)(pr.title)}"${sha}`;
+        })
+            .join(', ');
+        lines.push(`  PRs: ${prs}`);
+    }
+    lines.push(formatClaim(entry.claim));
+    return lines.join('\n');
+}
+function formatMilestoneChangelog(cl) {
+    const lines = [
+        `# Changelog — ${(0, sanitize_1.sanitizeField)(cl.milestone.name)} (${cl.milestone.status})`,
+    ];
+    const window = formatWindow(cl.milestone.startDate, cl.milestone.targetDate);
+    if (window)
+        lines.push(window);
+    lines.push('', '## Summary');
+    lines.push(`- Tasks shipped: ${formatBaselineStat(cl.headline.tasksShipped)}`);
+    lines.push(`- PRs merged: ${formatBaselineStat(cl.headline.prsMerged)}`);
+    lines.push('', '## Shipped');
+    if (cl.entries.length === 0) {
+        lines.push('(no tasks delivered yet)');
+    }
+    else {
+        for (const entry of cl.entries) {
+            lines.push('', formatEntry(entry));
+        }
+    }
+    return lines.join('\n');
+}
+/** The exact string the command prints — markdown, or raw JSON with --json. */
+function renderChangelogOutput(cl, opts) {
+    return opts.json ? JSON.stringify(cl, null, 2) : formatMilestoneChangelog(cl);
+}
+async function milestoneChangelog(identifier, opts) {
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const apiUrl = (0, api_1.resolveAuthedApiUrl)(creds.apiUrl);
+    const base = (0, api_1.trimTrailingSlash)(apiUrl);
+    let resolved;
+    try {
+        resolved = await (0, resolve_1.resolveMilestoneId)(base, creds.token, identifier, opts.project);
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    let res;
+    try {
+        res = await fetch(`${base}/api/milestones/${resolved.id}/changelog`, {
+            headers: { Authorization: `Bearer ${creds.token}` },
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API at ${apiUrl} (${msg})`);
+        return 1;
+    }
+    if (res.status === 401) {
+        console.error('Error: API key invalid or revoked. Run `lumo auth login`.');
+        return 1;
+    }
+    if (!res.ok) {
+        let errMsg = `milestone changelog failed (HTTP ${res.status})`;
+        try {
+            const errBody = (await res.json());
+            if (errBody.error)
+                errMsg = errBody.error;
+        }
+        catch {
+            // ignore
+        }
+        console.error(`Error: ${(0, sanitize_1.sanitizeField)(errMsg)}`);
+        return 1;
+    }
+    const cl = (await res.json());
+    process.stdout.write(renderChangelogOutput(cl, { json: !!opts.json }) + '\n');
+}

package/dist/cli/src/commands/milestone-show.js

@@ -39,6 +39,27 @@ function sprintCoverageLines(coverage) {
     }
     return ['', 'Sprint coverage:', ...rows];
 }
+/**
+ * LUM-648: the cross-milestone learning-migration read-out. Omitted entirely
+ * when this milestone's stewards were injected no prior learning (injected=0) —
+ * that's "nothing to migrate", not a 0% usage rate. When judged samples are too
+ * thin the rate reads `insufficient` rather than a fabricated percentage.
+ */
+function crossMilestoneLearningLines(learning) {
+    if (!learning || learning.injected === 0)
+        return [];
+    const { injected, judged, judgedUsed, sourceMilestones, rate } = learning;
+    const srcLabel = `${sourceMilestones} prior milestone${sourceMilestones === 1 ? '' : 's'}`;
+    const rateLabel = rate === null
+        ? `insufficient (judged ${judged}, need ≥3)`
+        : `${Math.round(rate * 100)}% (judged-used ${judgedUsed}/${judged})`;
+    return [
+        '',
+        'Cross-milestone learning:',
+        `  Injected: ${injected} prior learning${injected === 1 ? '' : 's'} (from ${srcLabel})`,
+        `  Usage rate: ${rateLabel}`,
+    ];
+}
 function formatMilestoneShow(m, tasks) {
     const total = m.taskCounts.TODO +
         m.taskCounts.IN_PROGRESS +
@@ -64,6 +85,7 @@ function formatMilestoneShow(m, tasks) {
         `Tasks:        ${total} total (TODO ${m.taskCounts.TODO} / IN_PROGRESS ${m.taskCounts.IN_PROGRESS} / IN_REVIEW ${m.taskCounts.IN_REVIEW} / DONE ${m.taskCounts.DONE})`,
     ];
     lines.push(...sprintCoverageLines(m.sprintCoverage));
+    lines.push(...crossMilestoneLearningLines(m.crossMilestoneLearning));
     if (tasks.length > 0) {
         lines.push('', (0, format_1.formatTaskListTable)(tasks));
     }
@@ -144,5 +166,6 @@ async function milestoneShow(identifier, opts) {
         health: milestone.health,
         staleness: milestone.staleness,
         sprintCoverage: milestone.sprintCoverage,
+        crossMilestoneLearning: milestone.crossMilestoneLearning,
     }, tasks) + '\n');
 }

package/dist/cli/src/index.js

@@ -100,6 +100,7 @@ const milestone_add_1 = require("./commands/milestone-add");
 const milestone_remove_1 = require("./commands/milestone-remove");
 const milestone_triage_1 = require("./commands/milestone-triage");
 const milestone_summary_1 = require("./commands/milestone-summary");
+const milestone_changelog_1 = require("./commands/milestone-changelog");
 const milestone_reorder_1 = require("./commands/milestone-reorder");
 const milestone_move_1 = require("./commands/milestone-move");
 const milestone_criteria_set_1 = require("./commands/milestone-criteria-set");
@@ -658,6 +659,12 @@ milestoneCmd
     .option('--project <ref>', 'Project name or slug (when identifier is a name)')
     .option('--retry', 'Trigger summary regeneration before fetching')
     .action(wrap((identifier, options) => (0, milestone_summary_1.milestoneSummary)(identifier, options)));
+milestoneCmd
+    .command('changelog <identifier>')
+    .description("Assemble a structured changelog from the milestone's DONE tasks + merged PRs + frozen claimSnapshot (pure assembly, no LLM; runs on any status). Headline counts carry a baseline vs prior completed milestones; every claim shows provenance. Identifier accepts a milestone name or UUID. --json emits the raw structured payload.")
+    .option('--project <ref>', 'Project name or slug (when identifier is a name)')
+    .option('--json', 'Emit the raw structured changelog payload')
+    .action(wrap((identifier, options) => (0, milestone_changelog_1.milestoneChangelog)(identifier, options)));
 milestoneCmd
     .command('reorder <refs...>')
     .description("Reorder a project's milestones. Pass every milestone (name or UUID) in the desired order. --project required when workspace has >1 project.")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumoai/cli",
-  "version": "1.52.0",
+  "version": "1.53.0",
   "description": "Lumo CLI — manage tasks and sessions from the terminal",
   "license": "MIT",
   "author": "cli@uselumo.ai",