project-mgr 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.5.1 - 2026-11-02
+
+### Added
+
+- Export `openWork(db, project?)` and expose it through `pmgr next` / `pmgr status next`, combining open pins, unpinned Todos, and unconverted legacy steps.
+- Add live `openWork` to CLI `current --json` and show open work with pin markers in text mode. Historical reads retain their previous shape.
+- Add repeatable `add --done-todo` / `--cancel-todo` for atomic closures and `todo-convert` by entry/index, project, or all current legacy sources.
+
+### Changed
+
+- **CLI behavior change:** plain `add` now keeps open pins; `--next` and `--next-todo` append (first-occurrence uid order). Use `--replace-next` to replace or clear pins without changing Todo status. Domain `addStatus` still defaults to replace; imports/exports stay unchanged. Fixed-uid re-pin of an already-carried pin remains a documented L2 limitation for direct API callers.
+- Reuse prior open Todos for exact trimmed `--next` titles, including unassigned Todos already pinned on the project, preferring pinned work, then the oldest Todo, while preserving provenance. Duplicate new titles in one write still create separate Todos.
+- Make `pmgr next --json` the daily checklist and guide agents to keep, finish, or explicitly retire work before adding new actions. Legacy carry preserves unconverted strings until explicit conversion. No automatic cancellation.
+- CLI `current` builds open work in one scan and groups it per project instead of re-querying each project.
+- Translate the new Todo/open-work section of `README_CN.md` into Chinese and document the L2 fixed-UID retry limitation in the architecture notes.
+
 ## 0.5.0 - 2026-10-29
 
 ### Added

package/README.md

@@ -337,9 +337,12 @@ Independently migrated copies of legacy data receive different UUIDs. Cross-impo
 ### Todos and dashboard actions
 
 Todos own actionable work. A new status snapshot stores ordered `nextTodoUids`
-and does not persist next-step prose. `add --next` creates one Todo per title
-and stores those UIDs in the same transaction. Repeating the same text on a
-later snapshot creates new Todos; pass `--next-todo` to keep existing work.
+and does not persist next-step prose. CLI `add` now carries open pins by default;
+plain `add` no longer clears them, and `--next` appends new work. An exact,
+case-sensitive title (after trimming) reuses a prior open Todo in that project
+or an unassigned Todo already pinned on it, preferring a current pin, then the oldest Todo. Provenance stays unchanged.
+Duplicate new titles within one write still create separate Todos.
+Use `--next-todo` to pin an existing UID explicitly.
 Do not combine `--next` with `--next-todo`. Duplicate UIDs in one list are rejected.
 
 ```sh
@@ -348,28 +351,48 @@ pmgr add --project demo --status active --summary "Review queued" \
 pmgr todo-add --title "Unassigned idea" --json
 pmgr add --project demo --status active --summary "Pin the idea" \
   --next-todo <todo-uuid> --source agent --json
-pmgr todos --project demo --status open --json
+pmgr next --project demo --json
 pmgr todo-update --uid <todo-uuid> --status completed --json
 pmgr todo-update --uid <todo-uuid> --status cancelled --json
 ```
 
-`todos --status open` answers open work from Todos, not from string next steps.
-With `--project`, UIDs pinned on the current snapshot are ordered first.
-Completing or cancelling a Todo updates every resolved view and does not rewrite
-snapshots. Omitting a UID from a newer snapshot unpins it and does not change
-the Todo status.
-
-Legacy snapshots keep string `nextSteps` and omit `nextTodoUids`. Convert each
-index explicitly; conversion does not append a snapshot. While any source index
-is still unconverted, a completion follow-up copies the full string list and
-`nextStepsSourceUid`. After every index has a Todo, the follow-up materializes
-`nextTodoUids` in source-index order and does not create Todos or change status.
-A snapshot never stores both prose and refs.
-
-`current` and `history` include stored `nextTodoUids` plus live `nextTodos`
-(`uid`, `title`, `status`, `project`). That view is the Todo now, not its state
-at the snapshot time. `at` returns the stored snapshot, including refs when
-present, and does not add the live view.
+The canonical daily checklist is `pmgr next --json` (also `pmgr status next`).
+Do not combine `nextSteps`, `nextTodos`, and `todos` by hand. Before every `add`,
+run `pmgr next --project P --json` and decide each item: keep it (do nothing;
+existing pins carry), finish it with `--done-todo <uid>`, or retire superseded
+work with `--cancel-todo <uid>`. Both close flags are repeatable and run in the
+same transaction as the snapshot. Unpinned work remains visible in the backlog.
+Use `--next` only for new actions, never status descriptions; put blockers in
+`--blocker`. No Todo is automatically cancelled by age or similarity.
+
+`--replace-next` restores replacement behavior: without next work it unpins
+everything; with next work it pins only those UIDs. It never closes Todos.
+The domain `addStatus` API still defaults to `nextMode: "replace"`; CLI `add`
+passes `"carry"` unless `--replace-next` is present. Imports stay strict.
+
+Legacy snapshots retain strings until explicitly converted. A plain carry-mode
+`add` preserves the full legacy list and `nextStepsSourceUid` while any index is
+unconverted; adding new next work then requires conversion or `--replace-next`.
+Conversion is idempotent and appends no snapshot:
+
+```sh
+pmgr todo-convert --entry <id-or-uid> --index 0 --json
+pmgr todo-convert --project demo --json
+# Back up before an explicit, user-run conversion of every current legacy source.
+pmgr export --format json > backup.json
+pmgr todo-convert --all --json
+```
+
+Once all source indices have Todos, the next carry-mode `add` materializes refs
+in index order, filtering out closed Todos. Historical snapshots stay unchanged.
+`next` combines converted Todos and unconverted strings without duplicates.
+
+`current --json` adds live `openWork` for each project's checklist, while its
+stored `nextSteps`, `nextTodoUids`, and live `nextTodos` retain their previous
+meaning, including closed pins. Text `current` prints open work with `[pinned]`
+markers. `history`, `at`, and `getEntry` do not gain `openWork`; `history` text
+and `completeActivity` follow-up copying stay unchanged. `at` returns stored
+snapshots without live Todo resolution.
 
 A snapshot may reference Todos that are unassigned or already in that project.
 If a Todo appears in any `nextTodoUids`, or is linked to a source entry, its

package/README_CN.md

@@ -335,8 +335,9 @@ pmgr revoke-completion --entry 12 --by 18 --reason "验收仍未完成" --source
 ### 待办与仪表板操作
 
 待办是具体工作的来源。新的状态快照按顺序存储 `nextTodoUids`，不再把下一步原文写入快照。
-`add --next` 会为每条标题创建一个待办，并在同一事务里写入这些 UID。
-之后的快照如果再次输入相同文本，会创建新的待办；要沿用已有工作，请传 `--next-todo`。
+CLI `add` 现在默认沿用仍处于 open 的钉住项：不带下一步的 `add` 不再清空它们，`--next` 会追加新工作。
+去掉首尾空白后，标题与该项目已有的 open 待办（或已钉在该项目上的未归属待办）完全一致（区分大小写）时，会复用那个待办：优先已钉住的，其次最早创建的。来源信息保持不变。
+同一次写入里重复的新标题仍会各自创建待办。要显式钉住已有 UID，请传 `--next-todo`。
 不要把 `--next` 和 `--next-todo` 写在同一次 `add` 里。同一列表里的重复 UID 会被拒绝。
 
 ```sh
@@ -345,24 +346,39 @@ pmgr add --project demo --status active --summary "已排队复查" \
 pmgr todo-add --title "未归属的想法" --json
 pmgr add --project demo --status active --summary "钉住这个想法" \
   --next-todo <todo-uuid> --source agent --json
-pmgr todos --project demo --status open --json
+pmgr next --project demo --json
 pmgr todo-update --uid <todo-uuid> --status completed --json
 pmgr todo-update --uid <todo-uuid> --status cancelled --json
 ```
 
-`todos --status open` 从待办而不是字符串下一步回答「还有哪些未完成工作」。
-加上 `--project` 时，当前快照钉住的 UID 会排在前面。
-完成或取消待办会立刻反映在所有解析视图上，且不会改写历史快照。
-新快照不再列入某个 UID，只表示它不再是当前下一步，不会改变该待办的状态。
+每日清单统一使用 `pmgr next --json`（也可写作 `pmgr status next`），不要手动拼接 `nextSteps`、`nextTodos` 和 `todos`。
+每次 `add` 之前先运行 `pmgr next --project P --json`，逐条决定：保留（什么都不做，已钉住的会自动沿用）、用 `--done-todo <uid>` 完成，或用 `--cancel-todo <uid>` 退役被取代的工作。
+这两个关闭参数可重复，并与快照在同一事务中执行。未钉住的工作仍会作为积压项显示。
+`--next` 只写新的行动，不写状态描述；阻塞写进 `--blocker`。系统不会按时间或相似度自动取消任何待办。
 
-旧快照保留字符串 `nextSteps`，并省略 `nextTodoUids`。转换仍按来源下标显式进行，且不会追加快照。
-只要还有来源下标未转换，完成活动时的后续快照会复制完整字符串列表和 `nextStepsSourceUid`。
-每个下标都已有待办之后，后续快照才按原下标顺序写入 `nextTodoUids`，不新建待办，也不改变状态。
-一条快照不能同时保存原文和引用。
+`--replace-next` 恢复替换语义：不带下一步时取消全部钉住，带下一步时只钉住这些 UID。它不会关闭待办。
+领域层 `addStatus` 默认仍是 `nextMode: "replace"`；CLI `add` 除非带 `--replace-next`，否则传 `"carry"`。导入仍保持严格校验。
+已知限制：领域 API 用固定 UID 重新钉住一个已沿用的待办时，原样重试会报 `conflicting entry uid`。CLI 不传固定 UID，`--external-ref` 重放不受影响。
 
-`current` 和 `history` 会带上存储的 `nextTodoUids`，以及实时的 `nextTodos`（`uid`、`title`、`status`、`project`）。
-这个视图是待办的当前状态，不是快照发生时的历史状态。
-`at` 返回当时的快照；如果存了引用就包含引用，但不会附加实时视图。
+旧快照保留字符串 `nextSteps`，并省略 `nextTodoUids`，直到显式转换。
+只要还有来源下标未转换，沿用模式的 `add`（以及完成活动时的后续快照）会复制完整字符串列表和 `nextStepsSourceUid`；此时要写入新的下一步，需先转换或使用 `--replace-next`。
+转换是幂等的，不会追加快照：
+
+```sh
+pmgr todo-convert --entry <id-or-uid> --index 0 --json
+pmgr todo-convert --project demo --json
+# 对所有当前旧快照做显式转换前，先备份；仅在用户要求时执行。
+pmgr export --format json > backup.json
+pmgr todo-convert --all --json
+```
+
+每个下标都已有待办之后，下一次沿用模式的 `add` 会按原下标顺序写入引用，并过滤掉已关闭的待办。历史快照保持不变。
+`next` 会合并已转换的待办和未转换的字符串，不会重复。
+
+`current --json` 为每个项目增加实时的 `openWork` 清单；存储的 `nextSteps`、`nextTodoUids` 以及实时的 `nextTodos` 含义不变，仍包含已关闭的钉住项。
+文本模式的 `current` 会列出未完成工作，并用 `[pinned]` 标出钉住项。
+`history`、`at` 和 `getEntry` 不带 `openWork`；`history` 文本输出和完成活动的后续快照复制规则不变。
+`at` 返回当时存储的快照，不附加实时待办状态。
 
 快照只能引用未归属的待办，或已经属于该项目的待办。
 待办一旦出现在任意 `nextTodoUids` 中，或关联了来源动态，就不能再改项目。

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { readFileSync, realpathSync } from "node:fs";
 import { basename } from "node:path";
 import { pathToFileURL } from "node:url";
-import { addStatus, createTodo, listTodos, updateTodo, at, current, history, importLedger, exportLedger, changeCompletion, listProjects, openLedger, parseTime, setProjectMetadata, startServer, ValidationError, } from "./index.js";
+import { addStatus, createTodo, convertNextStep, getEntry, openWork, openWorkByProject, listTodos, updateTodo, at, current, history, importLedger, exportLedger, changeCompletion, listProjects, openLedger, parseTime, setProjectMetadata, startServer, ValidationError, } from "./index.js";
 const booleanFlags = new Set([
     "json",
     "clear-description",
@@ -11,6 +11,8 @@ const booleanFlags = new Set([
     "no-open",
     "help",
     "version",
+    "replace-next",
+    "all",
 ]);
 const repeats = new Set([
     "next",
@@ -19,6 +21,8 @@ const repeats = new Set([
     "decision",
     "tag",
     "completes",
+    "done-todo",
+    "cancel-todo",
 ]);
 function parse(argv) {
     const command = [];
@@ -66,6 +70,9 @@ const allowedFlags = new Map([
             "blocker",
             "next",
             "next-todo",
+            "replace-next",
+            "done-todo",
+            "cancel-todo",
             "decision",
             "tag",
             "at",
@@ -77,6 +84,8 @@ const allowedFlags = new Map([
     ],
     ["todo-add", new Set(["title", "project", "entry", "json"])],
     ["todos", new Set(["project", "status", "json"])],
+    ["next", new Set(["project", "json"])],
+    ["todo-convert", new Set(["entry", "index", "project", "all", "json"])],
     ["todo-update", new Set(["uid", "status", "project", "json"])],
     ["complete", new Set(["entry", "by", "reason", "source", "json"])],
     ["revoke-completion", new Set(["entry", "by", "reason", "source", "json"])],
@@ -105,6 +114,11 @@ const allowedFlags = new Map([
     ["serve", new Set(["port", "host", "open", "no-open", "json"])],
 ]);
 const commandHelp = {
+    next: ["List all open work, pinned first", "[--project <name>] [--json]"],
+    "todo-convert": [
+        "Convert legacy next steps without appending a snapshot",
+        "--entry <id-or-uid> --index <n> | --project <name> | --all [--json]",
+    ],
     "todo-add": [
         "Create an independent or linked Todo",
         "--title <text> [--project <name>] [--entry <uid>] [--json]",
@@ -119,7 +133,7 @@ const commandHelp = {
     ],
     add: [
         "Append a status snapshot",
-        "--project <name> --summary <text> [--next <text> | --next-todo <uid>] [options]",
+        "--project <name> --summary <text> [--next <text> | --next-todo <uid>] [--replace-next] [--done-todo <uid>] [--cancel-todo <uid>] [options]",
     ],
     complete: [
         "Link a completed activity to its follow-up",
@@ -193,7 +207,7 @@ function validateInvocation(command, flags) {
     const action = command[statusCommand ? 1 : 0];
     const allowed = typeof action === "string" ? allowedFlags.get(action) : undefined;
     if (typeof action !== "string" || !allowed)
-        throw new ValidationError("usage: pmgr <add|complete|revoke-completion|import|current|projects|list|set-project|history|at|export|serve> (or: pmgr status <action>)");
+        throw new ValidationError("usage: pmgr <add|next|todo-add|todos|todo-update|todo-convert|complete|revoke-completion|import|current|projects|list|set-project|history|at|export|serve> (or: pmgr status <action>)");
     const positional = command.slice(statusCommand ? 2 : 1);
     if (action === "import") {
         if (positional.length > 1)
@@ -232,7 +246,7 @@ function output(value, json, write) {
         write(`${JSON.stringify(value)}\n`);
     else if (Array.isArray(value)) {
         const rows = value
-            .map((entry) => `${entry.project}\t${entry.effectiveStatus ?? entry.status}\t${entry.occurredAt}\t${entry.summary}${entry.completedBy ? ` (completed by #${entry.completedBy.id}; original: ${entry.status})` : ""}`)
+            .map((entry) => `${entry.project}\t${entry.effectiveStatus ?? entry.status}\t${entry.occurredAt}\t${entry.summary}${entry.completedBy ? ` (completed by #${entry.completedBy.id}; original: ${entry.status})` : ""}${entry.openWork ? entry.openWork.map((item) => `\n  - ${item.title}${item.pinned ? " [pinned]" : ""}`).join("") : ""}`)
             .join("\n");
         write(`${rows || "No entries found."}\n`);
     }
@@ -312,6 +326,50 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
     const json = flags.json === true;
     try {
         switch (action) {
+            case "next": {
+                const items = openWork(db, stringFlag(flags, "project"));
+                if (json)
+                    output(items, true, write);
+                else
+                    write(items.length
+                        ? items
+                            .map((item) => `${item.project ?? "-"}\t${item.kind === "todo" ? item.uid : `${item.entryUid}#${item.stepIndex}`}\t${item.pinned ? "pinned" : "-"}\t${item.title}`)
+                            .join("\n") + "\n"
+                        : "No open work.\n");
+                break;
+            }
+            case "todo-convert": {
+                const ref = stringFlag(flags, "entry");
+                const project = stringFlag(flags, "project");
+                if (Number(ref !== undefined) +
+                    Number(project !== undefined) +
+                    Number(flags.all === true) !==
+                    1)
+                    throw new ValidationError("use exactly one of --entry, --project, or --all");
+                if ((ref === undefined) !== (flags.index === undefined))
+                    throw new ValidationError("--entry requires --index; --index requires --entry");
+                const todos = db
+                    .transaction(() => {
+                    if (ref !== undefined)
+                        return [convertNextStep(db, ref, numberFlag(flags, "index", 0))];
+                    return current(db, project).flatMap((entry) => {
+                        if (entry.nextTodoUids !== undefined)
+                            return [];
+                        const source = entry.nextStepsSourceUid
+                            ? getEntry(db, entry.nextStepsSourceUid)
+                            : entry;
+                        return source.nextSteps.map((_, index) => convertNextStep(db, source.uid, index));
+                    });
+                })
+                    .immediate();
+                if (json)
+                    output(todos, true, write);
+                else
+                    write(todos
+                        .map((todo) => `${todo.uid}\t${todo.status}\t${todo.project}\t${todo.title}`)
+                        .join("\n") + "\n");
+                break;
+            }
             case "todo-add":
                 output(createTodo(db, {
                     title: stringFlag(flags, "title", true),
@@ -363,6 +421,17 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
                         progress: stringFlag(flags, "progress"),
                         blockers: listFlag(flags, "blocker"),
                         nextSteps: next,
+                        nextMode: flags["replace-next"] === true ? "replace" : "carry",
+                        closeTodos: [
+                            ...listFlag(flags, "done-todo").map((uid) => ({
+                                uid,
+                                status: "completed",
+                            })),
+                            ...listFlag(flags, "cancel-todo").map((uid) => ({
+                                uid,
+                                status: "cancelled",
+                            })),
+                        ],
                         ...(nextTodo.length > 0 ? { nextTodoUids: nextTodo } : {}),
                         decisions: listFlag(flags, "decision"),
                         tags: listFlag(flags, "tag"),
@@ -384,9 +453,16 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
                     command[command[0] === "status" ? 2 : 1] ??
                     "")).map((result) => result.entry), json, write);
                 break;
-            case "current":
-                output(current(db, stringFlag(flags, "project")), json, write);
+            case "current": {
+                const project = stringFlag(flags, "project");
+                // One open-work scan for all projects, grouped per project.
+                const { groups } = openWorkByProject(db, project);
+                output(current(db, project).map((entry) => ({
+                    ...entry,
+                    openWork: groups.get(entry.project),
+                })), json, write);
                 break;
+            }
             case "projects":
             case "list":
                 outputProjects(listProjects(db, { query: stringFlag(flags, "query") }), json, write);

package/dist/db.d.ts

@@ -1,10 +1,35 @@
 import Database from "better-sqlite3";
-import { type ProjectMetadata, type ProjectOverview, type Source, type StatusEntry } from "./domain.js";
+import { type ProjectMetadata, type ProjectOverview, type Source, type StatusEntry, type StatusEntryInput } from "./domain.js";
 export type Ledger = Database.Database;
 export type InsertResult = {
     entry: StatusEntry;
     inserted: boolean;
 };
+export type AddStatusInput = StatusEntryInput & {
+    nextMode?: "carry" | "replace";
+    closeTodos?: {
+        uid: string;
+        status: "completed" | "cancelled";
+    }[];
+};
+export type OpenWorkItem = {
+    kind: "todo";
+    uid: string;
+    title: string;
+    project: string | null;
+    pinned: boolean;
+    pinIndex: number | null;
+    createdAt: string;
+    entryUid: string | null;
+} | {
+    kind: "legacy-step";
+    project: string;
+    entryUid: string;
+    stepIndex: number;
+    title: string;
+    pinned: true;
+    pinIndex: number;
+};
 export type HistoryOptions = {
     since?: string;
     until?: string;
@@ -20,6 +45,12 @@ export declare function listProjects(db: Ledger, options?: {
 export declare function addStatus(db: Ledger, value: unknown, defaultSource?: Source, completes?: string[]): InsertResult;
 export declare function importStatuses(db: Ledger, values: unknown[]): InsertResult[];
 export declare function current(db: Ledger, project?: string): StatusEntry[];
+/** Per-project open work from one current() and one Todo scan; no cross-project dedupe. */
+export declare function openWorkByProject(db: Ledger, project?: string): {
+    groups: Map<string, OpenWorkItem[]>;
+    unassigned: Todo[];
+};
+export declare function openWork(db: Ledger, project?: string): OpenWorkItem[];
 export declare function history(db: Ledger, project?: string, options?: HistoryOptions): StatusEntry[];
 export declare function at(db: Ledger, project: string, occurredAt: string): StatusEntry | undefined;
 export declare function countEntries(db: Ledger, project?: string): number;

package/dist/db.js

@@ -230,7 +230,7 @@ function linkCompletions(db, targets, byUid, source) {
     for (const target of targets)
         changeCompletion(db, target, byUid, "complete", undefined, source);
 }
-function existingIdentity(db, input, recordedAt, textRetry = false) {
+function existingIdentity(db, input, recordedAt, textRetry = false, carry = false) {
     if (input.uid) {
         const existing = one(db, `${select} WHERE e.uid = ?`, input.uid);
         if (existing) {
@@ -241,7 +241,7 @@ function existingIdentity(db, input, recordedAt, textRetry = false) {
             });
             // Text/ref equivalence is only for addStatus sugar retries, not imports.
             const sameWrite = isDeepStrictEqual(toPortableStatusEntry(existing), candidate) ||
-                (textRetry && textRefEquivalent(db, existing, input));
+                (textRetry && textRefEquivalent(db, existing, input, carry));
             if (!sameWrite ||
                 (recordedAt !== undefined && recordedAt !== existing.recordedAt))
                 throw new ValidationError("conflicting entry uid");
@@ -260,13 +260,25 @@ function existingIdentity(db, input, recordedAt, textRetry = false) {
     }
     return undefined;
 }
-function textRefEquivalent(db, existing, input) {
-    // A text --next retry is the same write as the refs snapshot it produced.
-    if (existing.nextTodoUids === undefined || input.nextTodoUids !== undefined)
+function textRefEquivalent(db, existing, input, carry = false) {
+    // Retry against stored pins, never today's open status or latest snapshot.
+    if (existing.nextTodoUids === undefined) {
+        if (!carry || input.nextTodoUids !== undefined || input.nextSteps?.length)
+            return false;
+        return isDeepStrictEqual(toPortableStatusEntry(existing), toPortableStatusEntry({
+            ...input,
+            nextSteps: existing.nextSteps,
+            nextStepsSourceUid: existing.nextStepsSourceUid,
+        }));
+    }
+    if (!carry && input.nextTodoUids !== undefined)
         return false;
     assert.ok(input.nextSteps);
     const titles = input.nextSteps;
-    if (titles.length !== existing.nextTodoUids.length)
+    const size = input.nextTodoUids?.length ?? titles.length;
+    if (carry
+        ? size > existing.nextTodoUids.length
+        : size !== existing.nextTodoUids.length)
         return false;
     const candidate = toPortableStatusEntry({
         ...input,
@@ -277,41 +289,116 @@ function textRefEquivalent(db, existing, input) {
     });
     if (!isDeepStrictEqual(toPortableStatusEntry(existing), candidate))
         return false;
-    return existing.nextTodoUids.every((uid, index) => {
+    const suffix = existing.nextTodoUids.slice(existing.nextTodoUids.length - size);
+    return suffix.every((uid, index) => {
+        if (input.nextTodoUids !== undefined)
+            return uid === input.nextTodoUids[index];
         const todo = todoByUid(db, uid);
         return todo !== undefined && todo.title === titles[index];
     });
 }
 export function addStatus(db, value, defaultSource = "human", completes = []) {
-    const input = validateStatusEntry(value, defaultSource);
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new ValidationError("entry must be an object");
+    const { nextMode = "replace", closeTodos = [], ...fields } = value;
+    if (nextMode !== "carry" && nextMode !== "replace")
+        throw new ValidationError("invalid nextMode");
+    if (!Array.isArray(closeTodos))
+        throw new ValidationError("closeTodos must be an array");
+    const input = validateStatusEntry(fields, defaultSource);
     if (input.nextStepsSourceUid)
         throw new ValidationError("new snapshots cannot set nextStepsSourceUid");
     return db
         .transaction(() => {
-        const replay = existingIdentity(db, input, undefined, true);
+        const replay = existingIdentity(db, input, undefined, true, nextMode === "carry");
         if (replay) {
             linkCompletions(db, completes, replay.entry.uid, input.source);
             return replay;
         }
-        if (input.nextTodoUids !== undefined) {
-            assertSnapshotRefs(db, input.project, input.nextTodoUids);
-            const result = addValidatedStatus(db, { ...input, nextSteps: [] });
+        const latest = current(db, input.project)[0];
+        const preserved = latest
+            ? preservedNextWork(db, latest)
+            : { nextSteps: [], nextTodoUids: [] };
+        // Without refs, latest is a pending legacy snapshot: pin its converted indices.
+        const legacy = preserved.nextTodoUids === undefined
+            ? legacySource(db, latest)
+            : undefined;
+        const pins = preserved.nextTodoUids ??
+            legacy.nextSteps.flatMap((_, index) => {
+                const todo = stepTodo(db, legacy.uid, index);
+                return todo ? [todo.uid] : [];
+            });
+        const closing = new Map();
+        for (const value of closeTodos) {
+            const close = record(value, ["uid", "status"]);
+            const uid = validateUid(close.uid);
+            if (close.status !== "completed" && close.status !== "cancelled")
+                throw new ValidationError("invalid closeTodos status");
+            if ((closing.has(uid) && closing.get(uid) !== close.status) ||
+                input.nextTodoUids?.includes(uid))
+                throw new ValidationError("cannot close a Todo in both statuses or also pin it");
+            const todo = todoByUid(db, uid);
+            if (!todo || (todo.project !== input.project && !pins.includes(uid)))
+                throw new ValidationError(`todo ${uid} does not belong to project ${input.project} or its current pins`);
+            closing.set(uid, close.status);
+        }
+        for (const [uid, status] of closing)
+            updateTodo(db, uid, { status });
+        if (nextMode === "carry" && preserved.nextTodoUids === undefined) {
+            if (input.nextSteps.length || input.nextTodoUids !== undefined)
+                throw new ValidationError(`project ${input.project} has unconverted legacy next steps; run pmgr todo-convert --project ${input.project} or pass --replace-next`);
+            const result = addValidatedStatus(db, { ...input, ...preserved });
             linkCompletions(db, completes, result.entry.uid, input.source);
             return result;
         }
-        // Text --next sugar: one new Todo per title, stored only as refs.
+        if (input.nextTodoUids !== undefined)
+            assertSnapshotRefs(db, input.project, input.nextTodoUids);
+        // Freeze candidates before creating this write's Todos: repeated new titles stay separate.
+        // Same-project open Todos plus unassigned open Todos already pinned here.
+        const candidates = [
+            ...listTodos(db, input.project, { status: "open" }),
+            ...pins.flatMap((pin) => {
+                const todo = todoByUid(db, pin);
+                return todo?.project === null && todo.status === "open" ? [todo] : [];
+            }),
+        ];
+        candidates.sort((a, b) => Number(pins.includes(b.uid)) - Number(pins.includes(a.uid)) ||
+            a.createdAt.localeCompare(b.createdAt) ||
+            a.uid.localeCompare(b.uid));
         const uid = input.uid ?? randomUUID();
-        const nextTodoUids = input.nextSteps.map(() => randomUUID());
+        const newTodos = [];
+        const resolved = input.nextTodoUids ??
+            input.nextSteps.map((title, index) => {
+                const match = input.nextSteps.indexOf(title) === index
+                    ? candidates.find((todo) => todo.title === title)
+                    : undefined;
+                if (match)
+                    return match.uid;
+                const uid = randomUUID();
+                newTodos.push({ uid, title });
+                return uid;
+            });
+        const nextTodoUids = [
+            ...new Set([
+                ...(nextMode === "carry"
+                    ? pins.filter((uid) => todoByUid(db, uid)?.status === "open")
+                    : []),
+                ...resolved,
+            ]),
+        ];
+        if (nextTodoUids.length > 100)
+            throw new ValidationError("nextTodoUids must be an array of at most 100 uuids");
         const recordedAt = new Date().toISOString();
         const result = addValidatedStatus(db, { ...input, uid, nextSteps: [], nextTodoUids }, recordedAt);
         assert.equal(result.inserted, true);
-        input.nextSteps.forEach((title, index) => {
+        newTodos.forEach(({ uid, title }) => {
             insertTodo(db, {
-                uid: nextTodoUids[index],
+                uid,
                 title,
                 project: result.entry.project,
                 entryUid: result.entry.uid,
-                stepIndex: index,
+                // Provenance indexes the final snapshot, including carried/reused pins.
+                stepIndex: nextTodoUids.indexOf(uid),
                 status: "open",
                 createdAt: recordedAt,
                 completedAt: null,
@@ -369,6 +456,109 @@ export function current(db, project) {
         .all(...(project ? [project] : []));
     return rows.map((row) => annotateEntry(db, entryFromRow(row)));
 }
+/** Per-project open work from one current() and one Todo scan; no cross-project dedupe. */
+export function openWorkByProject(db, project) {
+    const latest = current(db, project);
+    const byProject = new Map();
+    const unassigned = [];
+    for (const todo of listTodos(db, project)) {
+        if (todo.project === null)
+            unassigned.push(todo);
+        else
+            byProject.set(todo.project, [
+                ...(byProject.get(todo.project) ?? []),
+                todo,
+            ]);
+    }
+    const names = project !== undefined
+        ? [project]
+        : [
+            ...latest.map((entry) => entry.project),
+            ...[...byProject.keys()]
+                .filter((name) => !latest.some((entry) => entry.project === name))
+                .sort(),
+        ];
+    const groups = new Map();
+    for (const name of names) {
+        const items = [];
+        const seen = new Set();
+        const add = (todo, pinIndex) => {
+            if (todo.status !== "open" || seen.has(todo.uid))
+                return;
+            seen.add(todo.uid);
+            items.push({
+                kind: "todo",
+                uid: todo.uid,
+                title: todo.title,
+                project: name,
+                pinned: pinIndex !== null,
+                pinIndex,
+                createdAt: todo.createdAt,
+                entryUid: todo.entryUid,
+            });
+        };
+        const entry = latest.find((entry) => entry.project === name);
+        if (entry?.nextTodoUids !== undefined) {
+            entry.nextTodoUids.forEach((uid, index) => {
+                const todo = todoByUid(db, uid);
+                if (todo)
+                    add(todo, index);
+            });
+        }
+        else if (entry) {
+            const source = legacySource(db, entry);
+            source.nextSteps.forEach((title, index) => {
+                const todo = stepTodo(db, source.uid, index);
+                if (todo)
+                    add(todo, index);
+                else
+                    items.push({
+                        kind: "legacy-step",
+                        project: name,
+                        entryUid: source.uid,
+                        stepIndex: index,
+                        title,
+                        pinned: true,
+                        pinIndex: index,
+                    });
+            });
+        }
+        for (const todo of byProject.get(name) ?? [])
+            add(todo, null);
+        groups.set(name, items);
+    }
+    return { groups, unassigned };
+}
+export function openWork(db, project) {
+    const { groups, unassigned } = openWorkByProject(db, project);
+    if (project !== undefined)
+        return groups.get(project);
+    // Globally, a Todo pinned by several projects appears only under the first.
+    const items = [];
+    const seen = new Set();
+    for (const group of groups.values())
+        for (const item of group) {
+            if (item.kind === "todo") {
+                if (seen.has(item.uid))
+                    continue;
+                seen.add(item.uid);
+            }
+            items.push(item);
+        }
+    for (const todo of unassigned)
+        if (todo.status === "open" && !seen.has(todo.uid))
+            items.push({
+                kind: "todo",
+                uid: todo.uid,
+                title: todo.title,
+                project: null,
+                pinned: false,
+                pinIndex: null,
+                createdAt: todo.createdAt,
+                entryUid: todo.entryUid,
+            });
+    return items;
+}
 export function history(db, project, options = {}) {
     const clauses = [];
     const params = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-mgr",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Local-first append-only project status ledger",
   "type": "module",
   "bin": {

package/skills/project-mgr/SKILL.md

@@ -64,10 +64,12 @@ pmgr list --query "keyword" --json
 pmgr serve --port 3000 --no-open --json
 
 # Record a completed milestone while the project remains active.
-# --next creates Todos and stores their UIDs on the snapshot. Reuse work with --next-todo.
+# Inspect open work before every add. Existing open pins carry automatically.
+pmgr next --project my-project --json
+# Use --next for new actions; exact prior open titles reuse their Todo UID.
 pmgr add --project my-project --status active --summary "Implemented the CLI" \
   --progress "Tests pass" --next "Publish the package" --source agent --json
-pmgr todos --project my-project --status open --json
+pmgr next --project my-project --json
 
 # Same project, with a tag naming the sub-project this snapshot covers.
 pmgr add --project acme --status active --summary "Shipped the web dashboard" \
@@ -94,4 +96,37 @@ When this update resolves all commitments of earlier entries (including blockers
 
 Use `complete --entry <id-or-uid> --by <id-or-uid> --source agent` for an existing follow-up. Use `revoke-completion --entry <id-or-uid> --by <id-or-uid> --reason "..." --source agent` to correct a mistaken link. Links require the same project and strictly increasing occurrence times. Query the affected history afterward to verify effective completion. Do not bulk-close old entries without evidence.
 
-Export produces a version-2 bundle when there are no Todos or refs, version 3 when Todos exist without refs, and version 4 when snapshots store `nextTodoUids` (one bundle per line for JSONL). Legacy imports remain supported and do not create Todos. Open work is `todos --status open`; current `nextTodoUids` only order that project's open items. Do not combine `--next` with `--next-todo`. Repeating `--next` text on a later snapshot creates a new Todo; pass existing UIDs to keep the same work. Cancelling or completing a Todo is `todo-update`, not deleting text from a snapshot. `at` has no completion annotations and does not resolve live Todo status. Project current state still comes from the latest snapshot.
+## Daily open-work checklist
+
+Use `pmgr next --json` as the canonical daily checklist. Do not combine
+`nextSteps`, `nextTodos`, and `todos` by hand. Before every `add`, run
+`pmgr next --project P --json`. Decide each item from evidence: keep it (do
+nothing; open pins carry), finish it (`--done-todo <uid>`), or retire superseded
+work (`--cancel-todo <uid>`). Close flags are repeatable and atomic with `add`.
+Unpinned Todos remain visible as backlog; pin them explicitly with `--next-todo`.
+Use `--next` only for new actions, not status descriptions. Put blockers in
+`--blocker`. Never cancel older or similar work automatically.
+
+CLI behavior change: plain `add` keeps open pins instead of clearing them;
+`--next` appends. Exact trimmed, case-sensitive titles reuse an existing open
+Todo of the same project, or an unassigned Todo already pinned on it, preferring
+a pin, then the oldest by creation time and UID. Its provenance stays unchanged. Duplicate new titles in one write still
+create separate Todos. Do not combine `--next` and `--next-todo`.
+`--replace-next` only replaces pins (or clears them with no next work); it does
+not close Todos. The domain API defaults to replace; imports remain strict.
+
+Legacy strings appear as `legacy-step` items until explicitly converted with
+`pmgr todo-convert --project P --json`, or `--entry <id-or-uid> --index <n>`.
+`--all` converts every current legacy source only when the user requests it;
+back up first with `pmgr export --format json > backup.json`. Conversion is
+idempotent and appends no snapshot. A plain `add` preserves partially converted
+legacy strings; new next work requires conversion or `--replace-next`.
+Once fully converted, the next carry-mode `add` pins the open converted Todos
+in index order.
+
+`current --json` adds live `openWork`, and text `current` marks pinned work.
+Raw `nextSteps`, `nextTodoUids`, and `nextTodos` retain their existing meaning.
+`history`, `at`, and `getEntry` do not gain `openWork`; `at` does not resolve
+live Todo status. Project current state still comes from the latest snapshot.
+Export emits version 2 without Todos/refs, version 3 with Todos but no refs,
+and version 4 with refs. Import/export never carries, reuses, or closes work.